> ## Documentation Index
> Fetch the complete documentation index at: https://gnero.genetind.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 常见问题

> 关于 Trellis 的常见问题

## 通用

<AccordionGroup>
  <Accordion title="看着很好用但听起来很复杂，怎么快速上手使用？">
    `npm install -g @mindfoldhq/trellis@latest`，在你的项目下面用 `trellis init` 进行初始化，然后就可以直接开始使用了。

    1. **Claude Code / iFlow 用户** — 打开一个新会话就可以直接开始使用。session start hook 会自动注入 AI 所需的所有信息（Trellis 工作流程、最近的 git 提交、最近的 journal 记录、项目上下文）。说需求，AI 会自动创建 task、生成 PRD、加载相关 spec 规范，然后委派给专门的 agent（implement、check 等）去干活。验收通过后用 `/trellis:record-session` 记录日志。也可以手动执行 `/trellis:start` 了解完整流程。

    2. **OpenCode 用户** — 跟 Claude Code 类似。session start 插件会在你第一条消息时自动注入上下文。用 `/trellis:start` 开始，然后按流程：说需求 → AI 加载 spec → 干活 → `/trellis:check-backend` 或 `/trellis:check-frontend` 自检 → `/trellis:record-session` 记录。要完整支持多 agent 流水线，需要安装 [oh-my-opencode](https://github.com/nicepkg/oh-my-opencode) 全局插件。

    3. **Cursor 用户** — 用 `trellis init --cursor` 初始化。Cursor 目前不支持 hooks，所以每次会话需要手动触发 `/trellis-start`。流程：`/trellis-start` → `/trellis-before-backend-dev` 或 `/trellis-before-frontend-dev` 加载规范 → 干活 → `/trellis-check-backend` 或 `/trellis-check-frontend` 自检 → `/trellis-record-session` 记录。注意 Cursor 命令用 `-` 而不是 `:`。

    4. **Codex 用户** — Codex 使用 skills（`$` 前缀）而不是 slash commands。流程：`$start` → `$before-backend-dev` 或 `$before-frontend-dev` → 干活 → `$check-backend` 或 `$check-frontend` → `$record-session`。

    5. **其它工具**（Trae、Windsurf 等） — 可以根据自己用的 IDE/CLI 手动创建对应的 slash command，然后按 Cursor 类似的流程使用。
  </Accordion>

  <Accordion title="如何安装？全局 vs 局部？版本切换？">
    **安装（推荐全局安装）：**

    ```bash theme={null}
    npm install -g @mindfoldhq/trellis@latest
    ```

    **验证安装：**

    ```bash theme={null}
    trellis --version
    ```

    **在项目中初始化：**

    ```bash theme={null}
    trellis init                # （推荐）交互式，逐项确认
    trellis init -y             # 跳过确认，使用默认配置
    trellis init -u {username}  # 同时设置开发者身份（不加此参数会自动从 .git/ 读取默认配置）
    trellis init -f             # 强制覆盖已有文件
    trellis init -s             # 跳过已有文件
    ```

    **版本切换与更新：**

    ```bash theme={null}
    trellis update                    # 对比版本差异并更新
    trellis update --migrate          # 应用文件重命名/删除等迁移
    ```

    **回退到正式版：** `npm install -g @mindfoldhq/trellis@latest`

    `trellis update` 永远不会覆盖 `.trellis/workspace/`、`.trellis/tasks/`、`.trellis/.developer`、`.trellis/spec/frontend/`、`.trellis/spec/backend/` — 这些路径受保护。并且每次 update 时，`.trellis/`、`.cursor/`、`.claude/` 等目录下的所有内容都会自动生成一个备份保存在 `.trellis/.backup-*` 目录下，无需担心更新会破坏原有结构。
  </Accordion>

  <Accordion title="为什么用 Trellis 而不是 Skills？">
    Skills 是可选的 — AI 可能跳过它们，导致质量不一致。Trellis 通过注入来强制执行规范。不管 AI
    "想不想"，每次会话都会拿到规范。
  </Accordion>

  <Accordion title="规范文件手写还是让 AI 生成？">
    AI 通常根据你的指示来生成规范。但当你有 AI 无法独立弄明白的架构洞察时，你应该参与进来 —
    比如"我们用这个错误格式是因为 X 历史原因"或者"这个模式存在是因为 Y 约束"。
  </Accordion>

  <Accordion title="跟 CLAUDE.md / AGENTS.md / .cursorrules 有什么区别？">
    那些格式每次都加载全部内容。如果你有 50 页规范，每个会话都读全部 50 页。

    Trellis 用分层架构和上下文压缩。JSONL 文件指定哪个任务加载哪些规范。你的认证功能加载认证规范。你的 UI 组件加载前端规范。噪音少，信号多。
  </Accordion>

  <Accordion title="多人协作会冲突吗？">
    不会。每个团队成员在 `.trellis/workspace/{name}/` 有隔离的工作区。你的日志是你的。队友的日志是他们的。

    规范是共享的，这正是重点 — 所有人遵循同样的约定。
  </Accordion>

  <Accordion title="AI 怎么记住之前的对话？">
    用 `/trellis:record-session` 让 AI 把摘要写到日志文件。下次会话开始时，它读取最近的日志和 git 信息来恢复上下文。

    这不是魔法记忆。是明确的日志记录。你控制什么被记住。
  </Accordion>

  <Accordion title="Trellis 支持 Cursor 吗？">
    支持。运行 `trellis init --cursor` 来配置 Cursor 专用命令。

    Trellis 会创建 `.cursor/commands/`，包含所有命令（如 `/trellis-start`、`/trellis-finish-work`）。注意 Cursor 的命令用 `-` 而不是 `:`。

    **Hooks**：Cursor 目前不支持自动注入 hooks，所以每次会话开始需要手动触发 `/trellis-start`。

    **Multi-Agent**（同目录多 agent）：有限支持，需手动协调。

    **Multi-Session**（worktree 隔离）：不支持。
  </Accordion>
</AccordionGroup>

## Specs 规范

<AccordionGroup>
  <Accordion title="规范应该多长？">
    短到能在 30 秒内扫完。如果更久，拆成多个文件。

    AI 会读整个规范，但规范太长时每部分得到的注意力就少。
  </Accordion>

  <Accordion title="我的规范没被遵循，哪里出问题了？">
    常见原因：

    1. **太模糊** — "用好的错误处理"没意义。加上带代码例子的具体模式。
    2. **没例子** — 放实际代码。AI 从例子学比从描述学更有效。
    3. **路径过时** — 如果你引用的文件不存在了，规范就让人困惑。
    4. **规则冲突** — 两个规范说了不同的事。选一个。

    测一下：开新会话，让它写规范覆盖的代码，看规则有没有被遵循。
  </Accordion>

  <Accordion title="规范可以覆盖非代码的东西吗？">
    可以。文档风格、commit message 格式、PR 模板、API 设计模式 — 任何你想保持一致的东西。
  </Accordion>
</AccordionGroup>

## Tasks 和 Workspace

<AccordionGroup>
  <Accordion title="每件事都要创建任务吗？">
    不用。任务在需要追踪和上下文隔离时有帮助。快速修复不需要任务。多天的功能开发有任务会受益。
  </Accordion>

  <Accordion title="忘了设置当前任务会怎样？">
    会话在没有任务特定上下文的情况下运行。规范还是会从默认值加载，但 AI 不知道你的 PRD 或任务特定的文件。

    做任务相关的工作时，先用 `/trellis:start` 命令开始会话。
  </Accordion>

  <Accordion title="JSONL 上下文文件怎么工作？">
    每行指定一个要包含的文件：

    ```json theme={null}
    {"file": ".trellis/spec/backend/index.md", "reason": "后端编码规范"}
    {"file": "src/api/users.ts", "reason": "API 实现上下文"}
    ```

    不同 agent 拿到不同的文件。implement agent 可能比 check agent 需要更多上下文。
  </Accordion>
</AccordionGroup>

## 多 Agent

<AccordionGroup>
  <Accordion title="能同时跑多少个 agent？">
    没有硬性限制，但实际受限于：

    * API 额度（每个 agent 消耗 token）
    * 你审查输出的能力

    3-5 个 agent 可控。再多就难跟踪了。
  </Accordion>

  <Accordion title="两个 agent 改同一个文件会怎样？">
    取决于运行模式：

    * **Multi-Agent（同目录）**：agent 共享同一目录，可能产生冲突。规划任务时避免文件重叠。
    * **Multi-Session（worktree）**：每个 agent 在独立的 Git worktree 工作，开发过程不冲突。合并 PR 时再解决冲突。
  </Accordion>
</AccordionGroup>

## 问题排查

<AccordionGroup>
  <Accordion title="装了 Trellis 但好像没什么不同">
    Trellis 在后台工作。没有 UI 变化。

    验证：

    1. `.trellis/` 目录存在
    2. `.claude/settings.json` 有 hook 配置
    3. 开个会话 — 规范应该出现在上下文里
  </Accordion>

  <Accordion title="AI 忽略我的规范">
    可能的原因：

    1. **规范没加载**：检查 `.trellis/spec/` 和 JSONL 上下文文件的路径
    2. **对话太长**：AI 可能在长对话中「忘记」规范。开新会话或提醒它
    3. **规范清晰度**：具体的规范比模糊的更有效

    Trellis 能提升一致性，但不是银弹。AI 仍然会犯错。
  </Accordion>

  <Accordion title="怎么升级？">
    先更新 CLI：

    ```bash theme={null}
    npm install -g @mindfoldhq/trellis@latest
    ```

    然后更新项目：

    ```bash theme={null}
    trellis update
    ```

    这只动没改过的文件，你改的东西不会丢。

    **受保护路径**（永远不会被覆盖）：`.trellis/workspace/`、`.trellis/tasks/`、`.trellis/.developer`、`.trellis/spec/frontend/`、`.trellis/spec/backend/`。

    **自动备份**：每次 update 都会将 `.trellis/`、`.cursor/`、`.claude/` 等目录的内容备份到 `.trellis/.backup-*`，无需担心破坏性更新。

    有破坏性改动（比如目录结构调整）时，加 `--migrate`：

    ```bash theme={null}
    trellis update --migrate
    ```

    这会执行文件迁移 — 重命名和删除旧文件来适配新结构。改过的文件会先问你再动。
  </Accordion>
</AccordionGroup>