Trellis v0.5.0 Beta发布：重构工作流与Skill架构

背景

Trellis 是一个旨在规范 AI 编程助手工作流的工具，此前已发布 0.4.0 GA 版本。经过多个迭代周期的开发，Trellis v0.5.0 首个可用 beta 版本正式推出。此次更新被定义为自 0.4.0 GA 以来最大的一次架构换血，核心目标是解决旧版本中工作流定义分散、平台适配碎片化以及 AI 行为不可控等问题，通过引入“Skill-first”架构和单一事实源（SoT）机制，大幅提升多平台 AI Agent 的协作稳定性和可定制性。

核心内容

本次 v0.5.0 beta 版本的重构主要集中在架构统一、工作流控制强化、平台适配优化及清理冗余功能四个方面：

1. 架构重构：Skill-first 与单一事实源

• Skill-first 架构：除 /start、/continue、/finish-work 外，所有 Trellis 命令均转变为 auto-triggered skill（自动触发技能）。AI 会根据上下文自动激活相应技能，无需用户手动输入命令。原有的 before-dev、brainstorm、break-loop、check、update-spec 等命令对应的文件从 commands/<name>.md 迁移至 skills/trellis-<name>/SKILL.md。
• 统一模板源：所有平台的命令和 Skill 模板合并至单一源 packages/cli/src/templates/common/，消除了以往“A 平台更新而 B 平台滞后”的漂移问题。
• Workflow.md 作为唯一 SoT：工作流定义收敛至 .trellis/workflow.md 一个 Markdown 文件。该文件包含 Phase 定义（Plan/Execute/Finish）、Skill 路由表、Per-turn 面包屑内容（[workflow-state:STATUS]）以及 task.py 子命令的使用时机。用户只需修改此文件即可自定义工作流（如增加 Review Phase 或分支逻辑），无需触碰 Python 脚本或 Hook 代码。

2. 工作流执行强化：面包屑与上下文注入

• Workflow Enforcement v2：新增 inject-workflow-state.py 共享 Hook，在每次用户消息触发时注入约 200 字节的 <workflow-state> 块。该块根据当前任务状态提示 AI 下一步行动，确保 AI 严格遵循 plan → execute → finish 三阶段流程，避免跳步。
• SessionStart Payload 升级：新 Session 启动时，AI 读取的 Payload 从 2.7 KB 扩容至 9.5 KB，内联了 Phase 1/2/3 每个 Step 的完整 How-to 指令。这使得 AI 在开场即具备 Step 级操作指南，无需临时加载上下文。同时，guidelines 部分从 10.9 KB 压缩至 4.6 KB，总 Payload 控制在 16.7 KB，以适配 Claude Code 的 ~20 KB 截断阈值。
• Sub-agent 上下文注入策略分化：针对无法通过 Hook 可靠改写 Sub-agent Prompt 的平台（Codex、Copilot、Gemini、Qoder），采用 pull-based prelude 策略，让 Sub-agent 在第一轮自行读取 .current-task、prd.md 等文件；其他平台（Claude、Cursor 等）继续采用 Hook 推送注入。

3. 平台适配升级与清理

• Agent-capable 升级：Qoder、CodeBuddy、Factory Droid、Cursor、Gemini CLI、Kiro、GitHub Copilot 从“仅命令”升级为完整的 agent-capable。Sub-agent 定义按各平台原生格式生成，Hook 基于 shared-hooks/ Python 脚本实现跨平台适配。
• Claude Code 优化：其 Hook 迁移至共享实现，删除了 1435 行平台专有代码。
• 移除支持：正式移除对 iFlow 平台的支持。

4. 命令精简与迁移机制

• 命令合并：/record-session 被 /finish-work 吸收，后者现在覆盖 Quality Gate 和 Commit 提醒。
• 强制迁移 Gate：从 0.4.x 升级至 0.5.0 必须使用 trellis update --migrate 参数，否则升级将失败（exit 1）。此机制防止了旧版本中“半迁移”状态导致的文件冲突。
• 配置自动绕过：若用户在 .trellis/config.yaml 中配置了 update.skip，在 Breaking Change 升级时会自动 bypass 安全文件删除、新文件写入和模板更新，但本地修改的文件仍受 Confirm Prompt 保护。
• 大规模清理：移除了 iFlow 目录、Multi-agent pipeline 相关脚本、Ralph Loop Hook 以及 6 个低使用率命令和 3 个 Sub-agent，所有清理均通过 Hash 校验确保不覆盖用户本地修改。

关键要点

• 升级必加参数：从 0.4.x 升级必须执行 trellis update --migrate，否则升级中断。
• 工作流自定义极简：通过修改 .trellis/workflow.md 即可定义工作流阶段、技能路由和状态提示，无需修改代码。
• AI 行为更可控：通过每轮注入 <workflow-state> 面包屑和 SessionStart 内联 Step 级指令，显著降低 AI 跳步或偏离流程的概率。
• 跨平台统一：消除了不同 IDE/CLI 平台间的模板漂移，所有平台共享同一套命令和 Skill 模板源。
• 性能优化：通过压缩 guidelines 和内联关键指令，将 SessionStart Payload 控制在 Claude Code 的上下文截断阈值内，同时提升 AI 响应速度。
• 清理与废弃：/record-session 命令已废弃，改用 /finish-work；iFlow 平台支持已移除。

意义与影响

Trellis v0.5.0 的发布标志着 AI 辅助开发工作流从“命令驱动”向“状态与技能驱动”的范式转变。通过确立 workflow.md 为单一事实源，开发者能够以极低门槛定制符合团队规范的开发流程，解决了以往多平台适配复杂、工作流定义分散的痛点。

此次架构升级不仅提升了 AI Agent 在执行复杂任务时的稳定性和一致性（通过面包屑和上下文注入），还通过标准化的 Hook 和模板机制，降低了多 IDE/CLI 环境的维护成本。对于用户而言，这意味着更少的配置错误、更清晰的 AI 行为预期以及更灵活的流程定制能力。随着 v0.5.0 GA 版本的推进，Trellis 有望成为多 AI Agent 协作开发的标准基础设施之一。