Trellis 阅读分析与使用笔记

这篇文章解决什么问题

Trellis 是 Mindfold 做的一个 AI coding harness，仓库地址：

mindfold-ai/Trellis

它不是模型、不是 IDE、也不是单纯的 prompt 集合。更准确地说，它是在代码仓库里加一层可版本化的 AI 工作流基础设施：

用 .trellis/workflow.md 规定 AI 做事流程。
用 .trellis/spec/ 保存团队编码约定。
用 .trellis/tasks/ 保存 PRD、研究记录、实现上下文和检查上下文。
用 .trellis/workspace/ 保存每个开发者的会话日志。
用 .claude/、.codex/、.cursor/、.opencode/ 等目录适配不同 AI 编程工具。

一句话：

Trellis 想解决的不是“让 AI 更聪明”，而是“让 AI 在团队仓库里按同一套流程和上下文做事”。

采集时间：2026-06-01。
阅读对象：GitHub main 分支、官方文档、packages/cli 源码和仓库内 .trellis/ 自举配置。
说明：本文未本地安装、未运行 trellis init、未执行测试。

先说结论

Trellis 的核心价值是把 AI 编程从“聊天记录驱动”改成“仓库文件驱动”。
它最重要的设计不是某个 agent prompt，而是 .trellis/ 目录：workflow、spec、task、workspace 都落在文件里。
它适合团队、多工具、长周期项目；对一次性小改动会显得重。
它和 AGENTS.md、CLAUDE.md 不冲突，而是把这些单文件规则拆成可作用域化、可任务化、可更新的结构。
它很依赖初始 spec 质量。空泛 spec 会让 AI 继续写通用代码；具体 spec 才能让 AI 贴合当前仓库。
多平台支持是它的强项，但不同平台能力不等价：hooks、sub-agent、slash command、skill 的支持差异很大。
源码包版本显示为 0.5.19，仓库和文档里已有 0.6 beta 轨迹；实际落地前必须确认 trellis --version 和当前文档版本。

我的判断：

Trellis 更像“把 AI 编程流程产品化的 repo 层框架”，不是单个 agent 的能力增强包。

它解决的真实问题

AI 编程在小任务里很顺，但在团队仓库里常见几个问题：

问题	典型表现
上下文反复丢	每次新会话都要重新解释目录、风格、测试规则
规则不可审查	规则散在聊天、个人 prompt、IDE 配置里
任务边界不清	AI 顺手改无关文件，或把设计、实现、检查混在一起
检查不稳定	写完代码后才想起 lint、typecheck、测试、文档同步
团队不可复用	一个人调出来的好流程，别人换工具后又要重搭

Trellis 的解法是把“AI 要遵守什么、当前在做什么、下一步该做什么”都落成仓库文件。

这点和单纯写一个更长的 AGENTS.md 不一样。AGENTS.md 适合放入口规则，但长期增长后容易变成大杂烩。Trellis 把内容拆开：

内容	放在哪里
流程规则	`.trellis/workflow.md`
团队约定	`.trellis/spec/`
单个任务	`.trellis/tasks/<task>/`
个人会话记忆	`.trellis/workspace/<developer>/`
平台适配	`.claude/`、`.codex/`、`.cursor/` 等

核心目录模型

初始化后，关键结构大致是：

text

.trellis/
  workflow.md
  config.yaml
  spec/
  tasks/
  workspace/
  scripts/

.claude/
.codex/
.cursor/
.opencode/
...

最值得关注的是 .trellis/，它是跨平台共用的事实层。

1. workflow：流程源头

.trellis/workflow.md 是 Trellis 的流程合同。源码模板里把流程分成三段：

阶段	作用
Phase 1: Plan	创建任务、澄清需求、写 `prd.md`、整理上下文
Phase 2: Execute	实现代码、运行检查、根据问题回修
Phase 3: Finish	更新 spec、提交代码、归档任务、写 journal

这个文件里还有 [workflow-state:STATUS] 块。hook 每轮会解析这些块，把当前任务状态注入给 AI。

这点很关键：hook 只是解析器，具体文案和流程规则仍然在 .trellis/workflow.md。如果要改流程，应该改 workflow，不应该先改 hook 脚本。

2. spec：团队约定

.trellis/spec/ 存团队规则。默认模板会按前端、后端、guides 分层，例如：

text

.trellis/spec/
  backend/
  frontend/
  guides/

官方文档强调好 spec 必须具体，例如精确文件路径、真实代码示例、明确反例。空泛规则没有用：

text

使用良好的错误处理。

更好的写法是：

text

API 错误统一从 src/lib/errors.ts 的 AppError 抛出。
不要直接 throw new Error。

我的理解：

.trellis/spec/ 不是写“理想工程原则”的地方，而是写“这个仓库现在真实执行的约定”的地方。

3. tasks：任务事实

每个任务一个目录，官方架构文档和源码里的结构基本一致：

text

.trellis/tasks/<MM-DD-slug>/
  task.json
  prd.md
  info.md
  implement.jsonl
  check.jsonl
  research/

文件	作用
`task.json`	任务状态、负责人、分支、PR、父子任务等元数据
`prd.md`	需求、验收标准、边界
`info.md`	可选技术设计
`implement.jsonl`	实现阶段必须先读的 spec / research
`check.jsonl`	检查阶段必须先读的 spec / research
`research/`	调研结果，给后续 agent 和会话复用

这里最有意思的是 implement.jsonl 和 check.jsonl。它们不是列要改的源码文件，而是列“实现/检查前必须加载的规则和背景文件”。

示例：

jsonl

{"file": ".trellis/spec/frontend/component-guidelines.md", "reason": "组件写法约定"}
{"file": ".trellis/tasks/04-30-example/research/platforms.md", "reason": "平台行为调研"}

这是一种很实用的上下文收口方式：不把全仓库塞给 agent，只把当前任务真正需要的规范和研究材料注入进去。

4. workspace：个人长期记忆

.trellis/workspace/<developer>/ 存个人 journal。

/trellis:finish-work 会写入 session 摘要，下一次会话启动时再读回关键状态。默认 journal 超过一定行数会轮转，源码模板里默认值是 2000 行。

这不是团队通用规则，而是开发者维度的会话连续性。团队规则应该沉淀到 .trellis/spec/，任务事实应该留在 .trellis/tasks/。

日常工作流

官方 README 把流程概括成四步：

描述你要做什么。
AI 用 trellis-brainstorm 一题一题澄清需求，直到 PRD 清楚。
AI 调用实现和检查路径，对照 spec、lint、type-check、test 自检。
完成或上下文快满时运行 /trellis:finish-work，归档任务并更新 journal。

源码模板里的实际流程更细。

no_task：没有任务时先分类

没有 active task 时，workflow 让 AI 先判断：

路径	场景
Direct answer	纯问答、解释、查阅，不写文件
Create a task	实现、改代码、改文档、构建、迁移、重构
Inline escape hatch	用户明确说跳过 Trellis、直接改、小修一下

这个设计很硬：默认只要是工作产物，就要建 task。它能保证可追踪，但也会让小改动变重。

planning：先写 PRD，再整理上下文

进入 planning 后，AI 要做几件事：

创建任务目录。
通过 trellis-brainstorm 澄清需求。
必要时派 trellis-research 做调研。
写 prd.md。
整理 implement.jsonl 和 check.jsonl。
运行 task.py start <task> 进入实现阶段。

这里的关键是第 5 步。只写 PRD 不够，还要明确实现和检查阶段应该读哪些 spec / research。

in_progress：实现、检查、沉淀、提交

进入 in_progress 后，默认路径是：

text

trellis-implement
-> trellis-check
-> trellis-update-spec
-> commit
-> /trellis:finish-work

trellis-implement 负责写代码，但禁止 commit。
trellis-check 负责看 diff、对照 spec、运行检查，并且可以直接修复发现的问题。
trellis-update-spec 负责判断这次任务有没有可复用规则要沉淀。
真正提交由主会话驱动，/trellis:finish-work 只做归档和 journal，不是提交 feature code 的命令。

这个分工是 Trellis 的核心工程纪律：实现、检查、知识沉淀、提交、归档是不同边界。

源码分层

Trellis 仓库本身是 monorepo，但主要实现集中在 packages/cli。

text

packages/cli/
  src/
    cli/
    commands/
    configurators/
    constants/
    migrations/
    templates/
    types/
    utils/

CLI 入口

packages/cli/src/cli/index.ts 定义了三个核心命令：

命令	作用
`trellis init`	初始化 `.trellis/` 和平台配置
`trellis update`	更新 Trellis 生成文件
`trellis uninstall`	移除 Trellis 生成文件

packages/cli/package.json 里暴露两个 bin：

json

{
  "trellis": "./bin/trellis.js",
  "tl": "./bin/trellis.js"
}

源码包版本是 0.5.19，engines 要求 Node >=18.17.0。README 写的是 Node.js >=18，这里以 package.json 为更严格的落地条件。

平台注册表

packages/cli/src/types/ai-tools.ts 是多平台配置的核心。

它把平台抽成 registry：

字段	作用
`templateDirs`	这个平台要复制哪些模板
`configDir`	平台配置写到哪个目录
`supportsAgentSkills`	是否写 `.agents/skills/`
`hasPythonHooks`	是否使用 Python hook
`templateContext`	slash command、skill、workflow、sub-agent 能力差异

当前 registry 包含 Claude Code、Cursor、OpenCode、Codex、Kilo、Kiro、Gemini、Antigravity、Windsurf、Qoder、CodeBuddy、GitHub Copilot、Factory Droid、Pi Agent。

这个设计比在各处写平台 if/else 更稳。新增平台时，数据入口在 registry，行为入口在 configurator，模板在 templates。

初始化逻辑

packages/cli/src/commands/init.ts 做几件事：

步骤	说明
检查运行目录	避免在 home 目录误初始化
检查 Python	需要 Python `>=3.9`，支持 `TRELLIS_PYTHON_CMD` 和跳过检查
检测项目类型	frontend、backend、fullstack、unknown
检测 monorepo	给不同 package 创建 spec
创建 `.trellis/`	复制脚本、workflow、config、spec 模板
配置平台目录	写 `.claude/`、`.codex/` 等
创建 bootstrap task	第一次初始化后生成 `00-bootstrap-guidelines`
初始化 developer	写 `.trellis/.developer` 和 workspace

最值得记的是 bootstrap task。它不是“初始化完成就万事大吉”，而是提醒你填真实 spec：

空 spec 会让后续 sub-agent 写通用代码；真实 spec 才会让它贴合团队模式。

模板与更新

packages/cli/src/templates/ 放各平台模板。通用 workflow、spec、scripts 在 templates/trellis 和 templates/markdown 里。

trellis update 不是盲目覆盖文件。源码里有 .template-hashes.json，用 hash 判断生成文件有没有被用户改过：

情况	行为
文件未改	可自动更新
用户改过	需要确认、跳过或写 `.new`
用户数据	永远保护

受保护路径包括：

text

.trellis/workspace/
.trellis/tasks/
.trellis/spec/
.trellis/.developer

这个边界设计很重要。spec、tasks、workspace 都是项目知识，不应该被模板升级覆盖。

上下文注入机制

Trellis 的技术核心是“把文件里的状态按时注入给 AI”。

1. SessionStart

会话开始时，hook 或平台扩展会加载启动上下文。官方文档列的典型内容包括：

上下文	来源
developer identity	`.trellis/.developer`
git state	当前分支、dirty files、recent commits
active task	`.trellis/.runtime/sessions/<session-key>.json`
active task list	`.trellis/tasks/*/task.json`
workflow summary	`.trellis/workflow.md`
spec index	`.trellis/spec/**/index.md`
workspace memory	`.trellis/workspace/<developer>/`

启动上下文不是全量代码 dump，而是让主会话知道“我是谁、当前任务是什么、规则入口在哪里”。

每轮用户输入时，inject-workflow-state.py 会：

从当前目录向上找 .trellis/。
解析 session-scoped active task。
读取任务 task.json.status。
从 .trellis/workflow.md 找 [workflow-state:<status>]。
注入 <workflow-state>...</workflow-state>。

这解决的是“AI 做到一半忘了流程”的问题。尤其是上下文很长时，per-turn breadcrumb 能持续提醒下一步。

3. sub-agent context

inject-subagent-context.py 在 sub-agent 启动前注入任务上下文。

实现 agent 读取：

来源	用途
`implement.jsonl`	实现阶段必须遵守的 spec / research
`prd.md`	需求
`info.md`	可选技术设计

检查 agent 读取：

来源	用途
`check.jsonl`	检查阶段必须遵守的 spec / research
`prd.md`	验收标准
changed files	实际 diff

这比“主会话告诉 sub-agent 一段话”可靠，因为上下文来自任务目录和 spec 文件。

一个文档和源码的差异点

我看到一个需要注意的轻微漂移：

来源	说法
`How It Works` 文档	active task pointer 提到 `.trellis/.runtime/sessions/<session-key>.json`，并提到 `.trellis/.current-task` fallback
`Architecture Overview` 和源码 `active_task.py`	当前任务是 session-scoped；没有稳定 session key 就没有 active task，旧 `.current-task` 只是历史残留/兼容线索

我的采信顺序：

以源码和架构文档为准：active task 应理解为 session-scoped，不要把 .trellis/.current-task 当成当前 canonical 机制。

这个差异不影响理解主流程，但落地排查时很重要。如果 AI 一直找不到 active task，应先看 session key、hook 输入、TRELLIS_CONTEXT_ID，不要先假设有一个全局 current-task 文件。

多平台支持不是同能力支持

Trellis 支持的平台很多，但不是每个平台都有同样的能力。

官方多平台文档把能力差异拆成：

能力	说明
SessionStart / extension auto-inject	会话启动时自动注入上下文
Sub-agent context injection	sub-agent 启动前自动注入 PRD/spec
Sub-agents	平台是否有独立 agent 能力
Auto-trigger skills	是否能按描述自动触发 skill
Explicit commands	是否支持 `/trellis:*` 这类命令

Codex 是一个特别例子：

需要启用 hooks。
新版本还需要 /hooks 一次性审批。
.agents/skills/ 是重要共享层。
config.yaml 里有 codex.dispatch_mode，默认倾向 inline，因为 Codex sub-agent 隔离下不一定能继承父会话任务上下文。

所以“支持 14 个平台”不要理解成“每个平台体验完全一样”。更准确的理解是：

.trellis/ 是统一事实层，各平台只是用自己的 hook、skill、command、agent 机制去消费它。

和 Superpowers 的区别

我会这样区分：

维度	Superpowers	Trellis
核心形态	一组 agentic skills 和流程纪律	repo 级工作流、任务、spec、workspace 基础设施
规则存放	skill 文件为主	`.trellis/` 文件体系为主
任务管理	更偏执行方法论	有 `.trellis/tasks/` 任务事实
团队复用	可复用 skill	可提交到 repo 的 specs / workflow / tasks
多平台	取决于 skill 生态	内置多平台适配器和模板

不是谁替代谁。Superpowers 更像“给 agent 加流程习惯”，Trellis 更像“给项目加 AI 工作流操作系统”。

如果项目已经有很强的 AGENTS.md 和轻量流程，Superpowers 可能够用。
如果团队需要跨工具、跨会话、跨成员保持一致，Trellis 的 repo 文件模型更合适。

适合什么场景

适合

场景	原因
多人团队	spec 和 workflow 可以进 repo，被评审和复用
多 AI 工具并存	Claude、Cursor、Codex 等可共享 `.trellis/` 事实层
长周期项目	tasks、workspace、spec 能保存跨会话上下文
需要严格流程	PRD、实现、检查、spec 更新、提交边界清楚
大仓库协作	JSONL 上下文比把全仓库丢给 agent 更可控

不适合

场景	原因
一次性脚本	初始化成本大于收益
个人小仓库且改动很少	AGENTS.md 可能已经够用
团队不愿维护 spec	空 spec 只会增加流程噪声
不希望 AI 自动驱动流程	Trellis 的默认流程会比较强势
高度定制平台	需要读生成文件和 hook，再按本地能力改

最小上手建议

如果要试用，我不会一开始就全量铺开。更稳的路径是：

选一个真实但小的仓库。
安装并初始化一个你实际使用的平台。
先填 3 到 5 个最关键 spec，不要试图一次写完整规范。
用一个小任务跑完整流程。
观察 AI 是否真的按 spec 写代码。
只把稳定规则沉淀到 .trellis/spec/。

命令大致是：

bash

npm install -g @mindfoldhq/trellis@latest
trellis init -u your-name --codex

如果是团队仓库，先不要让每个人各自乱改 spec。建议把 .trellis/spec/ 当代码评审：

规则	原因
spec 要引用真实路径	AI 才能读到实际模式
spec 要写反例	减少常见坏输出
spec 要短	太长会被忽略
spec 要跟代码同步	过期规则比没有规则更坏
新规则要来自真实任务	避免把理想规范写成噪声

我的使用判断

Trellis 最值得借鉴的不是“多装几个 agent”，而是这几个工程判断：

判断	价值
对话会丢，文件不会	把 PRD、研究、规则落仓库
规则要作用域化	不把所有东西塞进一个大 prompt
实现和检查分离	降低 AI 自证正确的风险
上下文要策展	用 JSONL 指定本任务要读什么
经验要回写	`trellis-update-spec` 让项目越用越贴合

我会把它放在这类工具里理解：

它不是 RAG，不负责帮 AI 找所有代码；它是工作流和知识层，负责告诉 AI “这次任务该按什么流程、读哪些规则、把结果存哪里”。

真正落地时，成败主要取决于三件事：

.trellis/spec/ 是否足够具体。
团队是否愿意把任务事实和经验沉淀成文件。
平台 hook / skill / sub-agent 能力是否能稳定运行。

如果这三点成立，它会显著降低 AI 编程的上下文重复成本。
如果这三点不成立，它可能只是把“AI 不守规矩”变成“AI 不守一堆文件里的规矩”。

GSAP

示例

Trellis 阅读分析与使用笔记

这篇文章解决什么问题

先说结论

它解决的真实问题

核心目录模型

1. workflow：流程源头

2. spec：团队约定

3. tasks：任务事实

4. workspace：个人长期记忆

日常工作流

no_task：没有任务时先分类

planning：先写 PRD，再整理上下文

in_progress：实现、检查、沉淀、提交

源码分层

CLI 入口

平台注册表

初始化逻辑

模板与更新

上下文注入机制

1. SessionStart

3. sub-agent context

一个文档和源码的差异点

多平台支持不是同能力支持

和 Superpowers 的区别

适合什么场景

适合

不适合

最小上手建议

我的使用判断

参考资料

Trellis 阅读分析与使用笔记 ​

这篇文章解决什么问题 ​

先说结论 ​

它解决的真实问题 ​

核心目录模型 ​

1. workflow：流程源头 ​

2. spec：团队约定 ​

3. tasks：任务事实 ​

4. workspace：个人长期记忆 ​

日常工作流 ​

no_task：没有任务时先分类 ​

planning：先写 PRD，再整理上下文 ​

in_progress：实现、检查、沉淀、提交 ​

源码分层 ​

CLI 入口 ​

平台注册表 ​

初始化逻辑 ​

模板与更新 ​

上下文注入机制 ​

1. SessionStart ​

2. workflow-state breadcrumb ​

3. sub-agent context ​

一个文档和源码的差异点 ​

多平台支持不是同能力支持 ​

和 Superpowers 的区别 ​

适合什么场景 ​

适合 ​

不适合 ​

最小上手建议 ​

我的使用判断 ​

参考资料 ​

Trellis 阅读分析与使用笔记

这篇文章解决什么问题

先说结论

它解决的真实问题

核心目录模型

1. workflow：流程源头

2. spec：团队约定

3. tasks：任务事实

4. workspace：个人长期记忆

日常工作流

no_task：没有任务时先分类

planning：先写 PRD，再整理上下文

in_progress：实现、检查、沉淀、提交

源码分层

CLI 入口

平台注册表

初始化逻辑

模板与更新

上下文注入机制

1. SessionStart

2. workflow-state breadcrumb

3. sub-agent context

一个文档和源码的差异点

多平台支持不是同能力支持

和 Superpowers 的区别

适合什么场景

适合

不适合

最小上手建议

我的使用判断

参考资料