Trellis 架构与工作流全景

把 AI 编码规范、任务、记忆和多平台入口统一到 .trellis/ 的 repo-local 工作流框架

官方来源

• GitHub README / package.json / 源码入口
• docs.trytrellis.app 的 Quick Start、Task Workflow、Multi-Platform

读取快照

• 时间：2026-03-14
• main 分支 @mindfoldhq/trellis 版本：0.3.10

结论口径

以下流程图优先依据源码和官方文档抽象，而不是二手解读。

它到底是什么

• 不是模型，也不是 IDE 本体
• 本质是“AI 编码工作流脚手架 + 规范分发系统”
• 把团队规则、任务状态、个人记忆、多 agent 并发都放进仓库文件结构
• 平台差异留在入口层；共享工作流收敛到 .trellis/

换句话说：Trellis 想把上下文工程产品化。

1. Trellis 共享内核：.trellis/

• spec/：项目规范库
• tasks/：任务目录，含 task.json、prd.md、implement/check/debug.jsonl
• workspace/：按开发者隔离的 journal / index
• scripts/：Python 运行时脚本
• workflow.md：主工作流说明
• config.yaml：session / hooks 配置
• worktree.yaml：多 agent worktree 配置

这里才是 Trellis 的“操作系统内核”。

2. 平台适配层

AI_TOOLS registry 维护单一事实源：

• Claude Code
• Cursor
• OpenCode / iFlow
• Codex
• Kilo / Kiro
• Gemini CLI
• Antigravity
• Qoder

每个平台只负责把同一套 Trellis 语义映射到自己的命令/skills/hooks 目录。

架构关键点

• .claude/、.cursor/、.agents/skills/ 只是入口壳
• 真正跨工具复用的是 .trellis/ 的任务模型、规范库、工作区记忆和脚本
• 因此 Trellis 的核心设计不是“prompt 模板”，而是“文件系统 + CLI + 脚本约定”

3. trellis init

1. 解析平台 flags、developer、project type
2. 创建 .trellis/ 骨架
3. 生成 spec 模板与 workflow.md
4. 写 .version
5. 为各平台拷贝命令 / skills / hooks
6. 创建根目录 AGENTS.md
7. 初始化 .template-hashes.json
8. 运行 init_developer.py
9. 自动创建 bootstrap task，引导你补齐规范

结论：init 做的是“安装工作流运行时”。

4. trellis update

• 读取 .version 做 CLI / 项目版本比较
• 用 .template-hashes.json 判断文件是否被用户改过
• 未改过的模板可自动更新
• 已改过的模板进入冲突处理
• 默认保护：spec/、tasks/、workspace/、.developer、.current-task

所以它不是盲目覆盖，而是“模板升级器”。

5. 模板与市场

• template-fetcher.ts 支持从官方 marketplace 或自定义 registry 拉模板
• 目前官方 marketplace/index.json 里至少有 spec template 和 trellis-meta skill
• 这意味着 Trellis 不只分发流程，还想分发“可复用工作法”

6. 单 agent 日常启动流

1. init_developer.py <name>
   • 写 .trellis/.developer
   • 建立 workspace/<name>/
   • 创建 journal 与 index
2. get_context.py
   • 汇总 developer / git / current task / active tasks / journal 容量
3. 读 workflow.md
4. 读 spec/*/index.md
5. 再按任务去读更细的 guideline

它把“会话启动 checklist”显式化了。

7. 任务模型

task.py 负责：

• create / list / start / finish / archive
• set-branch / set-scope / create-pr
• parent / child task 关系

task.json 里记录：

• status
• dev_type
• branch / base_branch
• current_phase
• next_action
• assignee / creator
• children / parent

任务目录是 Trellis 的执行单位。

8. 上下文注入机制

任务目录里的 implement.jsonl / check.jsonl / debug.jsonl 会列出：

• 要读的 spec
• 要读的命令 / skill 文档
• 相关文件

实现不是靠把所有规则都塞进一个大提示词，而是把“这次任务需要的上下文”单独编排出来。

9. 相位推进

phase.py 维护统一相位机： planning -> implement -> check -> finish -> create-pr

start / brainstorm / finish-work 这些平台命令，其实都在围绕这套 task + phase 模型运转。

日常开发的本质

Trellis 把“先读规范、再做任务、再检查、再记录”从口头习惯变成仓库里的硬结构。 这样单 agent 会话不容易漂移，换工具时也不会把整个工作法推倒重来。

10. plan.py

• 根据 requirement 创建 task 目录
• 启动 plan agent
• 让 plan agent 先把 prd.md 和任务结构补完整

也就是说：复杂任务先计划，再进入执行。

11. start.py + git worktree

• 为任务分支创建独立 worktree
• 从 worktree.yaml 复制 .trellis/.developer 和必要环境文件
• 在 worktree 内设置 .current-task
• 启动 dispatch / implement agent
• 记录 PID / session / registry

并发不是靠一条分支里硬挤，而是靠物理隔离的 worktree。

12. 监控与收尾

• status.py：看任务摘要、registry、日志、progress
• create_pr.py：stage / commit / push / gh pr create，并回写 task.json
• cleanup.py：归档任务、删 worktree、清 registry、可选删 branch

这让多 agent 流程不只“能跑起来”，还能有完整的收尾闭环。

本质结论

Trellis 可以理解成一个“repo-local AI development OS”。

• 共享内核：.trellis/
• 平台入口：各工具自己的 commands / skills / hooks
• 运行对象：task + spec + workspace + phase
• 并行扩展：git worktree + multi-agent scripts

这是我基于官方源码和文档得出的核心抽象。