Trellis 中文教程：先看初始化 diff，再决定是否接入主仓库

Trellis 管的是 AI 编码过程里的工程上下文。它把规范放进 .trellis/spec，把 PRD、实现和审查上下文放进 .trellis/tasks，再用 .trellis/workspace 保存个人工作记录。不同代理读取同一套项目约束，团队就不必在每个新会话里重新解释目录、风格和验收规则。

1. 先确认运行环境

根 README 写的是 Node.js 18+ 和 Python 3.9+；CLI 包清单把 Node engine 写得更精确，为 18.17.0 或更高。先检查本机版本：

node --version
python3 --version

项目采用 AGPL-3.0-only。若要修改后分发，或把修改版放进对外网络服务，应先让负责开源合规的人核对具体义务。

2. 在临时仓库安装和初始化

想跟随根 README 的稳定入口，可用：

npm install -g @mindfoldhq/trellis@latest
trellis --version

mkdir trellis-check && cd trellis-check
git init
trellis init -u your-name --codex
git status --short
git diff --stat

your-name 会成为开发者身份，并创建个人 workspace。先只选一个实际使用的平台，弄清生成内容后再加入其他平台。不要直接在有未提交改动的主仓库里试。

3. 初始化后重点看什么

先检查 .trellis/spec 是否只保留明确、可执行的规则；再看 .trellis/tasks 如何保存 PRD、实现和审查上下文；最后确认 .trellis/workspace 的个人记录是否适合提交。平台目录还可能出现 commands、skills、agents 或 hooks，具体取决于初始化参数。

官方流程分为 Plan、Implement、Verify 和 Finish。验证阶段声称会按规范检查 diff，并运行 lint、类型检查和测试。这里的关键不是目录齐全，而是用一个小任务核对：代理有没有引用正确规范，检查命令是不是项目真实命令，Finish 后又写回了什么。

4. Codex 接入容易漏掉的设置

官方 beta 文档写明，Codex 的完整体验依赖 hooks。支持的版本需要在配置里启用该能力，并在 /hooks 界面审核 Trellis hook。若 hooks 没启用，AGENTS.md 的提示仍可让代理手动读取 trellis-start skill，但命令菜单和自动注入不会完整出现。

[features]
hooks = true

这一项会随 Codex 版本变化，应该以安装时的 Trellis 文档和 Codex 自身配置说明为准。

5. 和 GitHub Spec Kit 怎么选

相比 GitHub Spec Kit，Trellis 更强调常驻仓库的规范、任务、个人 journal 和多代理配置。Spec Kit 的官方入口是规格驱动开发、修复和想法评估，并通过 specify CLI、模板和脚本产出结构化文档。若问题是多个代理长期共用一套工程习惯，Trellis 更贴近；若要从一个明确流程生成规格产物，可以先看 Spec Kit。

6. 验证状态与验证边界

验证边界：初始化文件、Codex hook、四阶段流程、升级以及 ablate/restore 都没有本机实测。上面的命令来自官方资料，执行前仍应在无敏感信息的临时仓库检查实际 diff。

常见问题