跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt

Use this file to discover all available pages before exploring further.

​
附录 F：FAQ

​
入门与升级

​
Q1: 不再用 /trellis:start 不习惯怎么办？

直接输入 /trellis:continue 就能拿到原来 /trellis:start 的效果。 之前 /trellis:start 显式注入的那套上下文 —— 当前开发者身份、git 分支和状态、active task、active tasks 列表、workflow.md 的 phase 规则、spec 索引、最近 journal 摘要 —— 0.5.0 之后由 SessionStart hook 在新会话开启时自动注入（Claude Code、Cursor、OpenCode、Gemini CLI、Qoder、CodeBuddy、Copilot、Droid、Pi Agent，以及开了 features.hooks = true 并跑过 /hooks 审批的 Codex；Codex < 0.129 用旧的 codex_hooks = true）。开新会话直接描述任务即可。 需要让 AI 重新定位当前流程位置 / 推进下一步时，输入 /trellis:continue，AI 会读 task 状态 + workflow.md 决定下一步。 没有 SessionStart hook 的平台（Kilo、Antigravity、Windsurf）开新会话时仍然跑 /trellis:start 或对应平台的 start workflow。

​
Q2: 怎么把已有项目迁到 Trellis？

  1. npm install -g @mindfoldhq/trellis@beta
  2. 项目根下 trellis init -u your-name（自动建 bootstrap 任务）。
  3. 打开已配置 Trellis 的 AI 会话；如果平台没有自动会话注入，就运行对应 start workflow。brainstorm skill 会帮你填初始 spec。
  4. 按团队约定手动补充核心 spec。
  5. 把 .trellis/ 和你用的 .{platform}/ 目录 add 并 commit。
  6. 队友 pull 后各自 trellis init -u their-name。

​
Q3: trellis init 模板选项里的 scratch 是啥？

最小模板。选了之后 trellis init 会写一组空 / 占位文件（基本目录骨架 + index.md 占位），让 AI 后续根据你的真实代码填充。当内置模板对不上你的技术栈、或者想用一个干净底子让 cc-codex-spec-bootstrap 之类的 skill 自动填，选 scratch。

​
Q4: Windows 用户怎么装 Trellis？

所有脚本都是 Python，跨平台： 
# 1. 装 Node.js 18+ 和 Python 3.9+
# 2. 装 Trellis
npm install -g @mindfoldhq/trellis@beta
# 3. 初始化
cd your-project
trellis init -u your-name
trellis init 现在会自动把 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 写进 .claude/settings.json。这个环境变量让 Bash 工具的 cwd 保持稳定，hook 脚本在 Windows 上也能正确解析路径——不需要手动配。

​
Q5: 更新 Trellis 时怎么不丢自定义内容？

trellis update --dry-run   # 预演
trellis update             # 应用
Trellis 在安装时对每个模板文件算 hash。update 时发现你改过的文件：未改的自动覆盖，改过的会询问（覆盖 / 跳过）。用 -f 全部强制覆盖、-s 全部跳过。 大版本时加 --migrate 应用 migration manifest 里的 rename / delete。不加 --migrate 碰到破坏性 manifest 会打印说明并退出，不静默重命名。

​
Q6: 从 0.4.x 升级到 0.5.0 怎么走最安全？

大版本升级一定加 --migrate。0.5.0 引入硬闸：不带 --migrate 时 trellis update 会 exit 1 并提示 MIGRATION REQUIRED。没有这个闸时旧行为是静默跳过 rename / delete 迁移条目，留下”半迁移”状态。 
trellis update --migrate --dry-run   # 预览
trellis update --migrate             # 真跑；改过的文件会先问你
trellis update                       # 验证：应该提示 "Already up to date"
每次 update 之前会在 .trellis/.backup-* 生成时间戳备份；本地改过的文件全部走 hash 校验，会出 Modified by you 确认（skip / overwrite / abort）。

​
Q7: 跑 trellis update 显示 0.4.0 → 0.4.0，没升上去，怎么回事？

升级是两步，对应两个层面： 
npm install -g @mindfoldhq/trellis@beta     # 1. 升级 CLI 本身
trellis update --migrate                  # 2. 把项目同步到 CLI 当前版本
trellis update 只把项目升到当前 CLI 版本。如果 CLI 自己还是 0.4.0，那项目最多也只能到 0.4.0。先把全局 CLI 升到 @latest，再跑 trellis update --migrate。

​
核心概念

​
Q8: 会话历史存在哪？

.trellis/workspace/
├── index.md              # 所有开发者的主索引
└── {your-name}/
    ├── index.md          # 个人索引
    └── journal-N.md      # 会话日志（约每 2000 行新起一个文件）

​
Q9: spec 写多细？

每文件 200-500 行、每小节 20-50 行。具体代码例子比抽象规则有用。发现过时立即更新。

​
Q10: .trellis/spec/ 里的 index.md 是干啥的？就是个目录吗？

大致是的 —— 每层 spec 目录下的 index.md 是一份单行目录，列出有哪些 spec 文件和每个的简短理由。brainstorm/research phase 只读 index.md（路径 + 理由），然后把相关条目写进 implement.jsonl / check.jsonl。具体 spec 内容文件（error-handling.md 等）只有在 JSONL 列出来时才会被加载。所以 index.md 是发现入口 —— 保持精简，每个 spec 一行，正文放到对应文件里。

​
Q11: command / skill / sub-agent 有什么区别？

原语触发者典型用途
Command用户（/trellis:*）会话边界（start、finish-work、continue）
Skill平台自动匹配阶段工作流（brainstorm、before-dev、check、update-spec、break-loop）
Sub-agent主会话 spawn隔离角色（implement、check、research）
选型指南见 Advanced 下的定制章节（自定义命令 / Agent / Hook / Skill）。

​
Q12: /trellis:start 和 /trellis:continue 有什么区别？

/trellis:start 用于没有自动注入的平台（Kilo / Antigravity / Windsurf）开新会话时，手动加载 SessionStart 上下文报告。有 SessionStart hook 的平台不需要这个命令。 /trellis:continue 用于推进当前 active task 到下一步工作流。任何阶段边界、不知道下一步该做什么时输入它，AI 会读 task 状态 + workflow.md，决定下一步。 简单理解：start 打开项目这扇窗，continue 在窗内推进光标。

​
Q13: 0.4 → 0.5 改了什么？

主要变化：
  • Skill-first：brainstorm / before-dev / check / update-spec / break-loop 从 slash 命令改为 auto-trigger skill，由平台根据用户意图自动匹配。
  • workflow.md 写清楚流程规则：Phase 定义、skill 路由、每轮 workflow-state 提醒都在 .trellis/workflow.md 里。Fork 工作流 = 改一个 markdown 文件，不用动 Python、不用改 hook（见自定义工作流）。
  • 每轮 workflow-state 面包屑：新增 inject-workflow-state.py hook，每条用户消息触发一次，按当前任务 status 注入 <workflow-state> 块，帮 AI 稳定走完 Plan → Execute → Finish 三阶段。
  • 3 个 sub-agent 取代 6 个：trellis-research / trellis-implement / trellis-check；dispatch / plan / debug 移除；Ralph Loop 和它的 SubagentStop hook 也移除（check sub-agent 自带重试循环）。
  • 8 个平台升级为 agent-capable：Cursor / OpenCode / Gemini CLI / Qoder / CodeBuddy / Copilot / Droid / Pi Agent 都拿到了 sub-agent + hook 或 extension 等价机制；.trellis/ 核心跨 14 个平台保持一致。
  • Multi-Agent Pipeline、/parallel、worktree.yaml 移除：现代 agent CLI 的原生 worktree 支持已经替代它。
  • 强制迁移 gate：破坏性版本必须加 --migrate，没加会 exit 并打印说明，不再静默留下半迁移状态。
完整清单见 0.5.0 破坏性变更 changelog。

​
Q14: /trellis:record-session 没了，怎么办？

0.5.0 已经合并进 /trellis:finish-work —— 一样写 session journal，外加任务归档和 quality gate 提醒。shell alias 或外部脚本里引用了 record-session 的改一下就行。同样在 0.5.0 移除并各自有替代的命令：/parallel（用平台原生 worktree）、/onboard / /create-command / /integrate-skill（使用率低，被 skill routing 或 cc-codex-spec-bootstrap 替代）、/check-cross-layer（合并进 check）。

​
Q15: sub-agent 不是很耗 token 吗？这套架构是不是更费？

sub-agent 是给主 agent 当工具用的：每次调用是一段隔离的子任务，跑完就把结论返回主 agent。主 agent 自己的上下文窗口因此能保持干净，反而比”主 agent 一路从规划写到验证、上下文越滚越长”更省 token。代价是单个 sub-agent 跑实现 / 检查时本身有自己的小上下文，但隔离换来的清晰度比那点开销更值得。 如果整个会话本身就很短（小修小改），sub-agent 的隔离收益不明显，让主 agent 一把过即可，不用 dispatch。

​
平台与多工具

​
Q16: Cursor 用户能拿到和 Claude Code 一样的自动化吗？

可以。Cursor 现在有 Trellis hooks、skills 和 sub-agents。SessionStart 会在对话开始注入 workflow，UserPromptSubmit 会追加 workflow-state 面包屑，sub-agent 上下文注入会在 trellis-implement / trellis-check 运行前把正确的 JSONL 内容传进去。

​
Q17: 切换 AI 编码工具时要重配吗？

不用。trellis init 带多个平台 flag 能一次写多份。已经用了 Cursor 后来想加 Claude Code 和 Pi Agent： 
trellis init -u your-name --claude --pi
.trellis/ 跨工具共享，只是多写一个 .{platform}/ 目录。 不想敲 flag 也行 —— 直接 trellis init 会进入交互模式，让你选”添加新平台 / 添加开发者 / 全部重新初始化”。

​
使用与工作流

​
Q18: 大仓老代码注入 spec 会不会反而把上下文塞满？

不会，因为 Trellis 不是每轮注入所有 spec。每个 spec 文件只覆盖一个主题（error-handling.md、database.md、testing.md），文件本身就小。brainstorm/research phase 时 AI 只把当前任务相关的 spec 路径写进 implement.jsonl / check.jsonl，hook 在 dispatch trellis-implement / trellis-check 时只注入清单里列出的文件。主会话只读 spec 的 index 页（仅路径）。50 万行仓库 + 50 个 spec 文件、当前任务只加载 4 个，对 AI 来说就跟一个 4 文件的项目差不多。如果还在塞 context，那就是 spec 文件本身写太长了，拆。

​
Q19: 任务做完发现不对 / 想补充，怎么办？

直接用自然语言告诉 AI：“这个 task 不满足需求，重新搞” 或 “把 X 扩展到也覆盖 Y”。除非范围变化非常大，否则不需要新建 task。如果真的得新建，运行 task.py create 重起一个，把旧 task 的 prd.md 作为背景引用。不要在中途手动改文件去”修补” task —— 让 AI 重新读 PRD 出新 diff。

​
Q20: 同时跑多个 task 时文件会不会互相污染？

每个 task 有独立目录 .trellis/tasks/<MM-DD-slug>/，里面 prd.md / research/ / implement.jsonl / check.jsonl 各自隔离。sub-agent 只读当前 active task 的 jsonl，所以跨 task 的 spec 注入自动按任务范围分隔。开发者级 journal 在 .trellis/workspace/<name>/，也是隔离的。 不会自动隔离的：task A 的 research/ 里如果留了死路结论或错误实现，下次重新进入 task A 时 AI 会重新读到。习惯做法：研究失败的文档在文件顶部标 ## DEPRECATED，不要留模糊的内容。

​
Q21: 必须先 commit 代码才能 /trellis:finish-work archive / record 吗？

/trellis:finish-work 写 session journal 会带上 commit hash，所以 commit 要在前面。如果只想归档 task 不写 journal，可以直接 task.py archive <task-name>，不用 commit。 推荐顺序：Phase 3.4 commit → /trellis:finish-work（archive + 写 journal）。

​
Q22: 每个任务带 work + archive + journal 三个 commit，是不是太冗余？

3 个 commit 来自不同层：你自己的 work commit（Phase 3.4）；task.py archive 写一个 chore(task): archive ... commit；add_session.py 写一个 chore: record journal commit。合并 PR 时用 squash merge 把它们压成一个就行。如果想保留作为独立历史，work commit 是真正有意义的；archive / journal 是 housekeeping 类，git log --invert-grep -E '^chore' 就能过滤掉。

​
Q23: AI 有时候会跳过 trellis 流程直接写代码，怎么把它拉回来？

两个施压点：
  1. 明确重申规则。 “停。我们用 Trellis。先 brainstorm、建 task。” AI 会按你实际守住的边界校准，不会按你希望守住的边界校准。
  2. 加强 workflow-state hook。 inject-workflow-state.py hook 每轮根据当前 task 状态注入面包屑。如果团队这种跳步频繁，可以 fork workflow.md，在 [workflow-state:no_task] 块里加更严格的提示，没有审过的 PRD 就拒绝进入 Execute。
这是跨模型的常见缺陷（Claude / GPT / DeepSeek 都会犯）。框架能减少不能消除，阶段边界仍然需要人介入。

​
Q24: monorepo（前后端同仓）怎么用 Trellis？

trellis init 会识别 monorepo，按包创建独立 spec 目录。默认会写一份 frontend/ 和一份 backend/ spec。如果包更细，可以用 .trellis/spec/<package>/backend/ 这种结构组织，再在父 index.md 里引用。brainstorm/research phase 会根据任务实际涉及的包路径，把对应的 spec 写进 implement.jsonl。 反过来：纯前端或纯后端单仓项目，trellis init 会按代码语言文件（go.mod / package.json / *.csproj 等）自动检测，只生成对应那一份目录，不会硬塞两套。

​
Q25: 怎么把一个 task 学到的经验流转到另一个 task？

三层：
  • Spec —— 当 task A 总结出代码库或规范层面的稳定结论时，跑 /trellis:update-spec 把它写进 .trellis/spec/。后续 task 的 implement.jsonl 里列了这个 spec 就会自动注入。
  • Workspace journal —— .trellis/workspace/<name>/journal-*.md 跨 task 承载同一个开发者的会话上下文。SessionStart hook 会把最近 journal 显示给 AI。
  • Task PRD 引用 —— task B 的 prd.md 可以显式链接 task A 的 prd.md 或 research/ 文件，brainstorm phase 会把它们作为上下文拉进来。
不会自动流转的：task A 的 research/ 不会自动注入到 task B。结论稳定的提到 spec；任务特有的留在源 task 里、显式引用即可。

​
Q26: 有 TDD 支持吗？

目前还没有内置工作流。当前默认是 implement → check（事后检查），不是 test-first。TDD skill 模板是 0.5.x 后续版本的 roadmap 项。在那之前可以把 TDD 要求写到项目的 .trellis/spec/<package>/testing.md，让 implement / check sub-agent 至少按你的测试模式走。

​
Q27: Trellis 能用于非代码场景（写作 / 法律 / 研究）吗？

可以。已经有用户把 Trellis 搬到长文写作，把 prose 当代码处理：prd.md 定义这篇要论证什么、什么不写；.trellis/spec/ 放语气 / 结构 / 引用格式规则；implement.jsonl 列写作 agent 需要的上下文；check.jsonl 列编辑 checklist 和事实校验规则；journal-*.md 记录决定了什么、删掉了什么。报告的提效幅度：同等质量下产出快 20-30%，主要省在”每次都得提醒 AI 风格指南”这一项。Trellis 帮不了创意火花，只帮一致性和”不用反复解释自己”。

​
团队协作与跨项目

​
Q28: 多人用 Trellis 会冲突吗？

按开发者和会话隔离（workspace/{name}/、.developer、.runtime/sessions/<session-key>.json）。共享状态是 .trellis/spec/ 和 .trellis/tasks/，走 PR review。建任务时用 --assignee 避免撞车。

​
Q29: .trellis/ 哪些目录要 git 跟踪？哪些 ignore？

默认全部跟踪。.trellis/ 设计就是团队共享目录：
  • .trellis/spec/ —— 共享规范，跟踪
  • .trellis/tasks/ —— 任务 PRD、research、上下文，跟踪
  • .trellis/workspace/<name>/ —— 个人 journal，跟踪（队友能互相看到进度）
  • .trellis/workflow.md、scripts/ —— 跟踪
.trellis/.gitignore 已经自动忽略：.developer、.current-task、.runtime/、.backup-*、*.tmp、*.pyc —— 运行时 / 个人指针文件。 如果把整个 .trellis/ 放进项目根的 .gitignore，AI 仍然能读（文件系统层面工作正常），但你失去 team coordination 这一层 —— 这层正是 Trellis 的核心价值。

​
Q30: 队友没有都装 Trellis，我的改动（尤其 AGENTS.md）会影响他们吗？

冲突面很小。AGENTS.md 是 Trellis 写入、且非 Trellis 用户也会改的唯一文件；Trellis 写的内容用 <!-- TRELLIS:START --> / <!-- TRELLIS:END --> marker 包起来，marker 外面的内容不动。 队友完全不想要 Trellis 内容时：
  • 直接跳过 AGENTS.md 写入，.trellis/ 工作不依赖它。
  • 把 .trellis/、.codex/、.agents/、.claude/ 等加到本地 .git/info/exclude（per-clone，不提交），把 Trellis 当成纯私人层。
  • 或者只 commit .trellis/spec/，仓库级 gitignore 平台 .{name}/ 目录。

​
Q31: 新项目要从头沉淀 spec 吗？跨项目通用规则怎么复用？

不用从头写。把团队通用规则维护成你自己的 spec 模板仓库，新项目用 trellis init -r <git-url> 直接拉： 
trellis init -r [email protected]:your-org/trellis-spec-template.git
支持 GitHub / GitLab / Bitbucket / 自托管 GitLab（HTTPS / SSH 都行）。这样团队级编码规范由内网 git 服务器集中分发，不用每个项目手抄一遍。

​
定制与兼容

​
Q32: 同一会话能不能同时用其他 plugin / skill / MCP（Superpowers / Context7 / 自定义 MCP）？

MCP —— 可以。MCP 是模型工具，不会改 Trellis 的工作流注入。 重型 plugin / skill 包（接管工作流的，比如 Superpowers）—— 大概率冲突。Trellis 通过 SessionStart hook + <workflow-state> 面包屑注入工作流；另一个框架在同一个上下文位做同样的事，会互相抢。每个会话只用一套工作流框架。 轻量单功能 skill（一次性帮手、自定义 slash 命令）—— 同时跑没问题。 如果实在想兼容（例如想从 Superpowers 拉一个特定 skill 进来），看 Q34（怎么定制 / trellis-meta），通过 trellis-meta skill 调整 Trellis 的工作流避开冲突。

​
Q33: Trellis 能和 Superpowers / OpenSpec / OMO 等其他框架共用吗？

不推荐。这几个本质上都是工作流框架（不只是 skill 集合），各自有注入机制、触发规则、阶段定义。两套工作流框架在同一个会话里跑会出现：
  • AI 同时收到两套阶段提示，按概率走，输出不可预期
  • Hook / SessionStart / breadcrumb 之间互相覆盖或叠加，上下文膨胀
  • 出问题时不知道是哪一套引起的，调试成本剧增
每个会话只用一套工作流框架。 想换就在新会话里换，不要混。 实在想兼用其中某一个具体的 skill（不是整套工作流），见 Q34 —— 用 trellis-meta 把 Trellis 流程改造一下让它调用对方那个 skill，但不要让两套阶段控制系统并存。

​
Q34: 怎么把 Trellis 改成符合我们团队习惯的样子？

用 trellis-meta skill。它专门为二开 Trellis 而做：删 / 加 phase（比如本地嫌 check 慢直接去掉，或者加 PRD 准入门禁、系统测试门禁）、改 skill 触发条件、改 sub-agent prompt、定制 workflow-state 文案，全部通过 skill 引导你修改 .trellis/workflow.md 和相关模板。 安装： 
npx skills add mindfold-ai/marketplace --skill trellis-meta
更多见 docs.trytrellis.app/zh/skills-market/trellis-meta。所有改动都是 markdown，不用碰 Python 或 hook 代码。

​
Q35: Obsidian 看不到 .trellis/ 目录怎么办？

Obsidian 默认隐藏点开头目录。两种解法。Obsidian Settings → Files & Links，打开 Detect all file extensions 和 Show hidden files（部分版本不暴露这个选项）。否则建个可见的软链，把 vault 指过去： 
ln -s .trellis trellis-vault
另一个相关痛点：MM-DD-<slug>/ 任务目录在 Obsidian 文件浏览器里会被截断。

​
Q36: Trellis 支持中文工作流 / 中文 spec / 中文 journal 吗？

支持 —— 内容层是语言无关的。spec、PRD、journal、workflow.md 全是纯 Markdown，写中文还是英文都行，AI 看到什么读什么。Trellis CLI 输出和默认模板目前是英文，但 trellis init 之后可以替换模板内容为中文（或 fork 你自己的模板仓库，见 Q31）。内置 skill 的中文 prompt 部分已经支持，本地化在 roadmap 里。这些都不影响工作流逻辑。