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

# 多平台与团队配置

## 多平台与团队配置

### 13.1 Claude Code 完整体验

Claude Code 是 Trellis 的主力平台，拥有最完整的自动化能力。三大 Hook 构成自动化闭环：

| Hook                         | 触发时机                 | 能力                       |
| ---------------------------- | -------------------- | ------------------------ |
| `session-start.py`           | SessionStart         | 自动注入上下文（身份、历史、任务）        |
| `inject-subagent-context.py` | PreToolUse (Task)    | 自动为 Agent 注入精准的 Spec 上下文 |
| `ralph-loop.py`              | SubagentStop (check) | 自动验证代码质量（Ralph Loop）     |

**Claude Code 独有功能**：

* Hook 自动注入 — 打开终端即开始工作，无需手动 `/start`
* Multi-Agent Pipeline — `/parallel` 并行编排多个 worktree Agent
* Ralph Loop — 自动质量门，Check Agent 失败自动重试
* Agent 系统 — 6 个专业 Agent（dispatch、plan、implement、check、debug、research）

### 13.2 Cursor 集成

`trellis init` 自动在 `.cursor/commands/` 下生成 Trellis 命令文件：

| Claude Code 命令         | Cursor 对应                      |
| ---------------------- | ------------------------------ |
| `/start`               | `/start`                       |
| `/check-backend`       | `/trellis-check-backend`       |
| `/check-frontend`      | `/trellis-check-frontend`      |
| `/finish-work`         | `/trellis-finish-work`         |
| `/before-backend-dev`  | `/trellis-before-backend-dev`  |
| `/before-frontend-dev` | `/trellis-before-frontend-dev` |
| ...                    | ...                            |

**与 Claude Code 的差异**：

* 文件位于 `.cursor/commands/trellis-{name}.md`
* Cursor 共 12 个命令（不含 `/parallel`，因为 Cursor 不支持 Multi-Agent Pipeline）
* 无 Hook 支持 — 规范注入需要通过命令手动触发
* 无 Agent 系统 — 所有工作在主对话中完成
* 无 Ralph Loop — 需要手动运行 check 命令

**Cursor 用户推荐工作流**：

```bash theme={null}
# 1. 启动会话（必须，替代 Hook 自动注入）
/start

# 2. 加载相关规范（推荐，替代 PreToolUse Hook）
/trellis-before-backend-dev    # 后端任务
/trellis-before-frontend-dev   # 前端任务

# 3. 描述任务，AI 开发...

# 4. 手动检查代码质量（替代 Ralph Loop）
/trellis-check-backend         # 后端检查
/trellis-check-frontend        # 前端检查
/trellis-check-cross-layer     # 跨层检查

# 5. 完工清单
/trellis-finish-work
```

### 13.3 Codex 集成

```bash theme={null}
trellis init --codex -u your-name
```

会生成以下配置：

* **`AGENTS.md`**（根目录） — Codex 的入口文件，提供项目基础上下文（类似 `CLAUDE.md` 的角色）
* **`.agents/skills/`** — Agent Skills 目录，存放可复用的 AI 能力模块

### 13.4 Kilo Code 集成

[Kilo Code](https://kilo.ai) 是一个开源（Apache 2.0）AI 编程 Agent 平台，支持 VS Code 扩展、JetBrains 插件和 CLI 三种形态，拥有 750K+ 用户。

```bash theme={null}
trellis init --kilo -u your-name
```

会在 `.kilocode/` 目录下生成配置：

**Trellis 到 Kilo 的映射关系**：

| Trellis / Claude Code   | Kilo Code                            | 说明                                   |
| ----------------------- | ------------------------------------ | ------------------------------------ |
| `CLAUDE.md`             | `AGENTS.md` + `.kilocode/rules/*.md` | Kilo 同时支持 AGENTS.md 开放标准和自有 rules 目录 |
| `.claude/commands/*.md` | `.kilocode/workflows/*.md`           | 在聊天中输入 `/start.md` 等调用               |
| `.claude/agents/*.md`   | `.kilocode/skills/*/SKILL.md`        | Skills 带 YAML frontmatter，可跨工具共享     |
| `.claude/hooks/`        | `.kilocode/launchConfig.json`（有限）    | Kilo 无完整 Hook 系统，Auto-Launch 是最接近的   |
| 子 Agent（Task 工具）        | Orchestrator Mode + `new_task()`     | 内置多模式委派，支持 worktree 并行               |

**Kilo 配置目录结构**：

```
project/
├── AGENTS.md                           # 开放标准（跨工具兼容）
├── .kilocode/
│   ├── rules/                          # 通用规则（所有模式）
│   │   └── trellis-workflow.md         # Trellis 工作流指南
│   ├── rules-code/                     # Code 模式专用规则
│   ├── rules-architect/                # Architect 模式专用规则
│   ├── workflows/                      # 命令（等同于 slash commands）
│   │   ├── start.md                    # /start 等效
│   │   ├── check-backend.md            # /check-backend 等效
│   │   └── finish-work.md              # /finish-work 等效
│   ├── skills/                         # Agent Skills
│   │   └── trellis-dispatch/
│   │       └── SKILL.md
│   ├── mcp.json                        # MCP 服务器配置
│   └── launchConfig.json               # 自动启动配置
```

**Kilo 用户推荐工作流**：

```bash theme={null}
# 1. Kilo 通过 .kilocode/rules/ 自动加载 Trellis 规范
# 或运行 workflow 获取完整上下文
/start.md

# 2. 切换到 Orchestrator 模式处理复杂任务
# Kilo 自动拆解任务并分配给 Code/Architect 等模式

# 3. 描述任务，AI 开发...

# 4. 运行检查 workflow
/check-backend.md

# 5. 完工
/finish-work.md
```

<Info>
  Kilo 的 Orchestrator Mode 与 Trellis 的 Multi-Agent Pipeline 理念相似，但实现不同：
  Trellis 使用 git worktree 物理隔离 + Hook 编排，Kilo 使用内置模式切换 + 独立对话上下文。
  两者可以互补——Trellis 的 Spec 管理和 Task 系统为 Kilo 提供结构化的项目上下文。
</Info>

### 13.5 Kiro 集成

[Kiro](https://kiro.dev) 是 Amazon 推出的 AI IDE，基于 Code OSS（VS Code 开源内核），主打 **Spec-Driven Development（规范驱动开发）**。支持 IDE、CLI 和 Autonomous Agent 三种形态。

```bash theme={null}
trellis init --kiro -u your-name
```

会在 `.kiro/` 目录下生成配置：

**Trellis 到 Kiro 的映射关系**：

| Trellis / Claude Code     | Kiro                                                   | 说明                                  |
| ------------------------- | ------------------------------------------------------ | ----------------------------------- |
| `CLAUDE.md`               | `.kiro/steering/*.md`                                  | Kiro 使用多个 Markdown 文件组成 Steering 系统 |
| `.trellis/spec/`          | `.kiro/steering/`                                      | Trellis spec 可映射为 Kiro steering 文件  |
| `.claude/commands/*.md`   | `.kiro/prompts/`                                       | 在聊天中输入 `@start` 等调用                 |
| `.claude/hooks/`          | `.kiro/hooks/*.kiro.hook`                              | Kiro 有原生 Hook 系统（JSON 配置）           |
| `.claude/agents/*.md`     | `.kiro/agents/`                                        | Kiro CLI 支持自定义 Agent 配置             |
| `.trellis/tasks/*/prd.md` | `.kiro/specs/*/requirements.md + design.md + tasks.md` | Kiro 将 PRD 拆为三件套                    |

**Kiro 配置目录结构**：

```
project/
├── .kiro/
│   ├── steering/                       # 项目上下文（等同于 CLAUDE.md）
│   │   ├── product.md                  # 产品概述（可自动生成）
│   │   ├── tech.md                     # 技术栈（可自动生成）
│   │   ├── structure.md                # 目录结构（可自动生成）
│   │   └── trellis-workflow.md         # Trellis 工作流指南
│   ├── hooks/                          # Agent Hooks（事件驱动自动化）
│   │   └── check-on-save.kiro.hook     # 保存时自动检查
│   ├── specs/                          # Spec-Driven Development
│   │   └── feature-name/
│   │       ├── requirements.md         # 需求（EARS 格式）
│   │       ├── design.md               # 技术设计
│   │       └── tasks.md                # 实现 checklist
│   ├── prompts/                        # 自定义提示词（命令）
│   ├── agents/                         # 自定义 Agent 配置（CLI）
│   └── settings/
│       └── mcp.json                    # MCP 服务器配置
```

**Kiro 用户推荐工作流**：

```bash theme={null}
# 1. Kiro 通过 .kiro/steering/ 自动加载 Trellis 规范
# 无需手动 /start

# 2. 选择 Spec 模式（推荐）或 Vibe 模式
# Spec 模式：自动生成 requirements → design → tasks 三件套
# Vibe 模式：传统自由编码

# 3. 描述任务，AI 按 tasks.md 逐步实现...

# 4. Agent Hooks 在文件保存时自动触发检查
# 也可手动运行 prompt 检查

# 5. 完成后提交代码
```

<Info>
  Kiro 的 Spec-Driven Development 与 Trellis 的任务管理系统高度互补：
  Trellis 的 `prd.md` 可以作为 Kiro Spec 的输入，而 Kiro 生成的 `requirements.md` / `design.md` / `tasks.md`
  可以反哺 Trellis 的 `spec/` 目录。两者结合可以实现从需求到交付的完整闭环。
</Info>

### 13.6 操作系统兼容性

| 操作系统        | 支持状态   | 说明                           |
| ----------- | ------ | ---------------------------- |
| **macOS**   | ✅ 完整支持 | 主力开发平台，所有功能均已验证              |
| **Linux**   | ✅ 完整支持 | 所有功能均已验证                     |
| **Windows** | ✅ 完整支持 | 脚本已全部迁移为 Python，原生支持 Windows |

**跨平台注意事项**：

| 注意事项         | 说明                                                    |
| ------------ | ----------------------------------------------------- |
| Python 脚本    | `.trellis/scripts/` 下的脚本为 Python，需要 Python 3.8+，跨平台兼容 |
| Python Hook  | `.claude/hooks/` 下的 Hook 脚本需要 Python 3.8+，跨平台兼容       |
| 路径分隔符        | Trellis 内部使用 `/`，Python 自动处理路径转换                      |
| Git worktree | Multi-Agent Pipeline 依赖 git worktree，各平台均支持           |

### 13.7 多开发者协作

**不冲突的部分**（各人独立）：

* `workspace/{name}/` — 每人独立目录
* `.developer` — gitignored，每人独立
* 并行任务的 worktree — 物理隔离

**可能冲突的部分**（需要协调）：

* `spec/` — 多人可能同时修改同一规范
* `tasks/` — 多人可能操作同一任务

**最佳实践**：

* Spec 修改通过 PR 审查
* 任务指派明确（`--assignee` 参数）
* 重要的 spec 变更在团队会议上讨论

### 13.8 worktree.yaml 完整配置

```yaml theme={null}
# Worktree Configuration for Multi-Agent Pipeline

#───────────────────────────────────────────────────
# Paths
#───────────────────────────────────────────────────

# Worktree 存储目录（相对于项目根目录）
worktree_dir: ../trellis-worktrees

#───────────────────────────────────────────────────
# Files to Copy
#───────────────────────────────────────────────────

# 每个 worktree 需要独立副本的文件
# 这些文件包含敏感信息或需要独立配置
copy:
  - .env                     # 环境变量
  - .env.local               # 本地环境变量
  - .trellis/.developer      # 开发者身份

#───────────────────────────────────────────────────
# Post-Create Hooks
#───────────────────────────────────────────────────

# 创建 worktree 后执行的命令
# 在 worktree 目录中按顺序执行，失败则中止
post_create:
  - pnpm install --frozen-lockfile
  # - npm install
  # - yarn install --frozen-lockfile

#───────────────────────────────────────────────────
# Check Agent Verification (Ralph Loop)
#───────────────────────────────────────────────────

# 验证代码质量的命令
# 配置后，Ralph Loop 运行这些命令 — 全部通过才放行
# 不配置则使用 completion markers 模式
verify:
  - pnpm lint
  - pnpm typecheck
  # - pnpm test
```

### 13.9 `trellis update` 与版本管理

```bash theme={null}
# 查看当前版本
cat .trellis/.version

# 更新到最新版本
trellis update

# 预览更新（不实际应用）
trellis update --dry-run

# 强制覆盖所有文件
trellis update -f

# 跳过所有变更文件
trellis update -s
```

**模板哈希机制**：

`.trellis/.template-hashes.json` 存储了每个模板文件的 SHA-256 哈希。`trellis update` 时：

1. 计算本地文件哈希
2. 与记录的模板哈希对比
3. 如果一致 → 文件未被用户修改 → 安全更新
4. 如果不一致 → 文件被用户修改 → 提示冲突
5. 用户选择：覆盖 / 跳过 / 合并