> ## 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

## 附录 F：FAQ

## 入门与升级

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

新请求直接用自然语言描述即可。有 active task 且希望 AI 推进到下一步时，再用
`/trellis:continue`。

之前 `/trellis:start` 显式注入的那套上下文 —— 当前开发者身份、git 分支和
状态、active task、active tasks 列表、`workflow.md` 的 phase index、spec
index 路径、最近 journal 摘要 —— 现在由各平台自己的启动路径交付。Claude-style
平台走 SessionStart hook 或 extension。Codex 走 `AGENTS.md` 加
`UserPromptSubmit` breadcrumb；没有 active task 时，这段 breadcrumb 可以指引 AI
读取一次 `trellis-start`。

需要让 AI 重新定位当前流程位置 / 推进下一步时，输入 `/trellis:continue`，
AI 会读 task 状态、artifact presence 和 `workflow.md` 决定下一步。

没有 SessionStart hook 的平台（Kilo、Antigravity、Devin）开新会话时仍然跑 `/trellis:start` 或对应平台的 start workflow。

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

1. `npm install -g @mindfoldhq/trellis@latest`
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，跨平台：

```bash theme={null}
# 1. 装 Node.js 18+ 和 Python 3.9+
# 2. 装 Trellis
npm install -g @mindfoldhq/trellis@latest
# 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 时怎么不丢自定义内容？

先升级全局 CLI：

```bash theme={null}
trellis upgrade                              # CLI 0.6.0+
npm install -g @mindfoldhq/trellis@latest    # CLI 0.5.x 或更早（还没有 upgrade 命令）
```

再同步项目文件：

```bash theme={null}
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 迁移条目，留下"半迁移"状态。

```bash theme={null}
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`，没升上去，怎么回事？

升级是两步，对应两个层面：

```bash theme={null}
trellis upgrade                           # 1. 升级 CLI 本身（CLI 0.6.0+）
trellis update --migrate                  # 2. 把项目同步到 CLI 当前版本
```

`trellis update` 只把项目升到当前 CLI 版本。如果 CLI 自己还是 0.4.0，那项目最多也只能到 0.4.0。先把全局 CLI 升到 `@latest`，再跑 `trellis update --migrate`。

如果你的 CLI 早于 0.6.0，`trellis upgrade` 命令还不存在——第 1 步改用 `npm install -g @mindfoldhq/trellis@latest`，之后的升级就能用 `trellis upgrade` 了。

## 核心概念

### 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 /
Devin）开新会话时，手动加载 Trellis orientation。有启动 hook、extension、
`AGENTS.md` 或 prompt-hook bootstrap 的平台通常不需要这个命令。

`/trellis:continue` 用于推进当前 active task 到下一步工作流。任何阶段边界、
不知道下一步该做什么时输入它，AI 会读 task 状态、artifact presence 和
`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（见[自定义工作流](./custom-workflow)）。
* **每轮 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：

```bash theme={null}
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。先分类请求，并在进入 planning 前征求创建 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/` 在 `.gitignore` 里时，怎么关掉 auto-commit？

`.gitignore` 排除 `.trellis/` 时脚本会尊重它 — 打印警告并跳过 `git add` / `git commit`。journal 和 task archive 文件仍写入磁盘，只是不进 git。

要显式关掉 auto-commit（不管 `.gitignore`），在 `.trellis/config.yaml` 里设：

```yaml theme={null}
session_auto_commit: false
```

默认 `true`，接受 `true / false / yes / no / 1 / 0 / on / off`。影响 `add_session.py`（journal）和 `task.py archive`（任务归档）。

## 团队协作与跨项目

### Q29: 多人用 Trellis 会冲突吗？

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

### Q30: `.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 的核心价值。

### Q31: 队友没有都装 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}/` 目录。

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

不用从头写。把团队通用规则维护成你自己的 spec 模板仓库，新项目用 `trellis init -r <git-url>` 直接拉：

```bash theme={null}
trellis init -r git@github.com:your-org/trellis-spec-template.git
```

支持 GitHub / GitLab / Bitbucket / 自托管 GitLab（HTTPS / SSH 都行）。这样团队级编码规范由内网 git 服务器集中分发，不用每个项目手抄一遍。

## 定制与兼容

### Q33: 同一会话能不能同时用其他 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 的工作流避开冲突。

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

不推荐。这几个本质上都是工作流框架（不只是 skill 集合），各自有注入机制、触发规则、阶段定义。两套工作流框架在同一个会话里跑会出现：

* AI 同时收到两套阶段提示，按概率走，输出不可预期
* Hook / SessionStart / breadcrumb 之间互相覆盖或叠加，上下文膨胀
* 出问题时不知道是哪一套引起的，调试成本剧增

**每个会话只用一套工作流框架。** 想换就在新会话里换，不要混。

实在想兼用其中某一个**具体的 skill**（不是整套工作流），见 Q34 —— 用 `trellis-meta` 把 Trellis 流程改造一下让它调用对方那个 skill，但不要让两套阶段控制系统并存。

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

用 `trellis-meta` skill。它专门为二开 Trellis 而做：删 / 加 phase（比如本地嫌 check 慢直接去掉，或者加 PRD 准入门禁、系统测试门禁）、改 skill 触发条件、改 sub-agent prompt、定制 workflow-state 文案，全部通过 skill 引导你修改 `.trellis/workflow.md` 和相关模板。

安装：

```bash theme={null}
npx skills add mindfold-ai/marketplace --skill trellis-meta
```

更多见 [`docs.trytrellis.app/zh/skills-market/trellis-meta`](https://docs.trytrellis.app/zh/skills-market/trellis-meta)。所有改动都是 markdown，不用碰 Python 或 hook 代码。

### Q36: Obsidian 看不到 `.trellis/` 目录怎么办？

Obsidian 默认隐藏点开头目录。两种解法。Obsidian Settings → Files & Links，打开 `Detect all file extensions` 和 `Show hidden files`（部分版本不暴露这个选项）。否则建个可见的软链，把 vault 指过去：

```bash theme={null}
ln -s .trellis trellis-vault
```

另一个相关痛点：`MM-DD-<slug>/` 任务目录在 Obsidian 文件浏览器里会被截断。

### Q37: Trellis 支持中文工作流 / 中文 spec / 中文 journal 吗？

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

***