vibe-coding-cn/docs/research/mindfold-ai-trellis/deep-dive.md

# mindfold-ai/Trellis 深度研究

## 一句话判断

Trellis 的底层设计是：把 AI 编程从“聊天驱动”改造成“仓库控制面驱动”，让任务、规格、上下文、
会话、验证和平台适配都成为可版本化对象。

## 结构拆解

| 层级 | 关键对象 | 作用 |
|:---|:---|:---|
| 仓库控制面 | `.trellis/` | 承载 workflow、spec、tasks、workspace、scripts、config，是 Agent 行为的本地真相源。 |
| 任务层 | `.trellis/tasks/{MM-DD-name}/` | 每个任务保存 `task.json`、`prd.md`、`design.md`、`implement.md`、`implement.jsonl`、`check.jsonl`。 |
| 规格层 | `.trellis/spec/` | 按 package/layer 管理编码规范、质量规则、架构约束和思考指南。 |
| 状态层 | `.trellis/workflow.md` | 定义 Plan、Execute、Finish 相位和 per-turn workflow-state breadcrumb。 |
| 记忆层 | `.trellis/workspace/` 与 `mem` | 保存会话日志，并从 Claude、Codex、OpenCode、Pi 等历史会话中检索上下文。 |
| 适配层 | `.claude/`、`.codex/`、`.cursor/`、`.opencode/` 等 | 把同一套 Trellis 工作流渲染到不同 AI coding 平台。 |
| runtime 层 | `channel`、worker、supervisor、event log | 支撑多 Agent 协作、消息路由、上下文挂载、worker 生命周期和中断。 |

## 关键机制

### 1. 规格注入，而不是模型记忆

Trellis 的 `.trellis/spec/` 把团队规则拆成 package 和 layer，再通过任务的 `implement.jsonl`、`check.jsonl`
选择性注入给实现 Agent 与检查 Agent。这里的关键不是“多写文档”，而是让文档参与运行时：

- spec 是长期规则；
- task artifact 是短期目标；
- jsonl manifest 是本次任务需要加载的上下文清单；
- implement/check Agent 只读与本次任务相关的部分，避免上下文膨胀。

对本仓的启示：`AGENTS.md`、`README.md`、`llms.txt`、`assets/ai-citation/llms-full.txt` 和研究域索引必须保持一致。
它们不是说明书，而是 AI 进入仓库时的上下文入口。

### 2. 任务是执行单元，不是聊天片段

Trellis 的任务目录把“要做什么”拆成可恢复 artifact：

- `task.json` 保存 24 字段的规范任务记录，包含 status、priority、assignee、branch、commit、PR、parent/children 等。
- `prd.md` 保存需求、约束和验收。
- `design.md` 保存边界、契约、数据流和取舍。
- `implement.md` 保存执行顺序、验证命令、review gate 和回滚点。
- `implement.jsonl`、`check.jsonl` 保存进入实现/检查阶段的上下文文件和原因。

对本仓的启示：复杂研究和文档治理任务不能只靠聊天推进。至少要能在文件里回答：目标是什么、上下文在哪里、
验收是什么、验证命令是什么、未完成项是什么。

### 3. workflow breadcrumb 把状态注入每一轮

Trellis 在 `.trellis/workflow.md` 中维护 `[workflow-state:STATUS]` 块，并通过 hook 在每轮用户输入时注入当前状态。
这解决的是 Agent 常见失败：忘记先计划、忘记进入检查、忘记提交前验证、忘记收尾沉淀。

关键设计点：

- `no_task` 要求先判断是否创建任务。
- `planning` 要求轻量任务至少有 PRD，复杂任务补齐 `design.md` 和 `implement.md`。
- `in_progress` 明确实现、检查、更新 spec、commit、finish-work 的顺序。
- Codex 可以走 inline 变体，适配平台子 Agent 隔离问题。

对本仓的启示：工作流规则不应该只写在长文档深处，而应出现在 Agent 每次开始任务时必读的位置。

### 4. 多平台适配不是复制多份规则

Trellis 的 `AI_TOOLS` registry 把 Claude Code、Cursor、OpenCode、Codex、Kilo、Kiro、Gemini、Antigravity、
Devin、Qoder、CodeBuddy、Copilot、Droid、Pi、Reasonix、ZCode、Trae 等平台统一成配置对象。
平台差异被压到 configurator、template 和 hook 能力矩阵中，核心工作流保持一致。

对本仓的启示：多 AI 工具支持应该有一个事实中心。根 `AGENTS.md`、`llms.txt`、`assets/ai-citation/llms-full.txt`
和工具目录不能各讲各的。

### 5. channel runtime 把多 Agent 协作变成事件系统

Trellis 的 `channel` API 暴露 channel、thread、message、context、worker、inbox、interrupt、watch、supervisor 等能力。
CLI 侧提供 `create`、`send`、`wait`、`interrupt`、`spawn`、`run`、`list`、`messages`、`kill`、`post` 等命令。

这说明 Trellis 对 Agent 协作的理解不是“开几个窗口”，而是：

- 共享事件日志；
- 明确 worker 身份；
- 消息有发送者、目标、线程和 delivery mode；
- 上下文可以挂到 channel 或 thread；
- supervisor 管理 worker 生命周期、空闲清理、超时和中断。

对本仓的启示：如果未来真的要做多 Agent 协同研究或 tmux worker 编排，应该优先采用“事件日志 + worker 状态 + 上下文挂载”
的模型，而不是只靠口头分工。

### 6. mem 把历史会话变成可检索材料

Trellis 的 `mem` 子系统从 Claude、Codex、OpenCode、Pi 等平台读取会话，提供 list、search、context、extract、projects。
它的重点不是把所有聊天永久塞回提示词，而是让 Agent 能检索过去发生过的事实、决策和问题。

对本仓的启示：聊天记录可以辅助检索，但稳定知识必须进入仓库文档。真正的长期记忆不是“记住一切”，
而是把有价值的经验晋升到可维护结构。

## 可迁移模式

### 模式一：任务 artifact 最小契约

本仓可以设计轻量版任务契约，不需要引入完整 Trellis runtime：

| 字段 | 最小含义 |
|:---|:---|
| 目的 | 本次任务要改变什么结果。 |
| 对象 | 涉及哪些文件、目录、研究域或流程。 |
| 约束 | 哪些地方不能动、哪些事实必须核验。 |
| 上下文 | 当前任务必须读取的文件和原因。 |
| 验收 | 什么状态算完成。 |
| 验证 | 可复跑的命令、检查或人工审计动作。 |
| 沉淀 | 哪些结论要进入 README、AGENTS、llms、research 或 skills。 |

### 模式二：规格入口一致性

本仓已有多个 AI 入口。Trellis 的启示是：入口可以多，事实只能一个。

最低要求：

- 根 `AGENTS.md` 说明仓库操作规则。
- `llms.txt` 提供短上下文入口。
- `assets/ai-citation/llms-full.txt` 提供完整 AI 引用入口。
- `docs/research/README.md` 和 `docs/README.md` 提供研究域索引。
- 新增研究域必须同步进入 metadata 和 llms。

### 模式三：验证后更新规格

Trellis 的 `trellis-update-spec` 思路可以转成本仓收尾规则：

1. 完成修改。
2. 运行质量门禁。
3. 如果发现新的稳定规则、坑、流程或边界，回写到对应 AGENTS、README、docs 或 skills。
4. 再提交。

这比“写完总结一下”更强，因为它要求下一次 Agent 能自动读到新规则。

## 不采用 Trellis 的边界

- AGPL-3.0 代码边界：本仓不能直接复制 Trellis 的实现、模板或 hook。
- 项目形态边界：本仓是中文 Vibe Coding 知识库，不是 Trellis runtime 分发包。
- 所有权边界：引入完整 CLI、多平台 configurator 和 channel runtime 会显著增加维护面。
- 需求边界：当前本仓主要需要研究域、文档治理和质量门禁，不需要立即运行 worker supervisor。

## 对本仓的下一步建议

1. 在 `docs/research/harness/` 补一份“Agent Harness 控制面检查清单”。
2. 为复杂文档任务定义轻量任务 artifact 契约。
3. 建立“验证后沉淀规格”的收尾规则，把高频教训写回 AGENTS、README 或 skills。
4. 对多 AI 入口做一致性检查，确保 `AGENTS.md`、`llms.txt`、`llms-full.txt` 和研究索引不漂移。
5. 如果未来需要多 Agent 并发执行，再研究 channel runtime 或 `auto-tmux` 的事件化改造。

## 最小试用动作

下一轮可以选一个真实文档任务试用轻量 Trellis 模式：

1. 写一个任务 artifact，明确目的、对象、约束、上下文、验收和验证。
2. 执行修改。
3. 用独立检查视角审计结果。
4. 把新经验回写到稳定入口。
5. 提交前确认索引和 AI 入口同步。