多平台与团队配置
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） |
- Hook 自动注入 — 打开终端即开始工作，无需手动
/start
- Multi-Agent Pipeline —
/parallel 并行编排多个 worktree Agent
- Ralph Loop — 自动质量门，Check Agent 失败自动重试
- Agent 系统 — 6 个专业 Agent（dispatch、plan、implement、check、debug、research）
Cursor 集成
trellis init 自动在 .cursor/commands/ 下生成 Trellis 命令文件：
| Claude Code 命令 | Cursor 对应 |
|---|
/trellis:start | /trellis-start |
/trellis:before-dev | /trellis-before-dev |
/trellis:brainstorm | /trellis-brainstorm |
/trellis:check | /trellis-check |
/trellis:check-cross-layer | /trellis-check-cross-layer |
/trellis:finish-work | /trellis-finish-work |
/trellis:break-loop | /trellis-break-loop |
/trellis:create-command | /trellis-create-command |
/trellis:integrate-skill | /trellis-integrate-skill |
/trellis:onboard | /trellis-onboard |
/trellis:record-session | /trellis-record-session |
/trellis:update-spec | /trellis-update-spec |
- 文件位于
.cursor/commands/trellis-{name}.md
- Cursor 共 12 个命令（不含
/parallel，因为 Cursor 不支持 Multi-Agent Pipeline）
- 无 Hook 支持 — 规范注入需要通过命令手动触发
- 无 Agent 系统 — 所有工作在主对话中完成
- 无 Ralph Loop — 需要手动运行 check 命令
Cursor 用户推荐工作流：
# 1. 启动会话（必须，替代 Hook 自动注入）
/trellis-start
# 2. 加载相关规范（推荐，替代 PreToolUse Hook）
/trellis-before-dev
# 3. 描述任务，AI 开发...
# 4. 手动检查代码质量（替代 Ralph Loop）
/trellis-check
/trellis-check-cross-layer # 跨层检查
# 5. 完工清单
/trellis-finish-work
Codex 集成
trellis init --codex -u your-name
AGENTS.md（根目录） — Codex 的入口文件，提供项目基础上下文（类似 CLAUDE.md 的角色）.agents/skills/ — 共享 Agent Skills 目录（agentskills.io 开放标准，Codex、Kimi CLI、Amp、Cline 等均可使用）.codex/config.toml — 项目级 Codex 配置.codex/agents/ — 自定义 Codex agents（implement.toml、research.toml、check.toml）.codex/skills/ — Codex 专属 skills（如用于多 agent pipeline 的 parallel）.codex/hooks/session-start.py + .codex/hooks.json — SessionStart hook，自动注入 Trellis 工作流、指南和任务上下文
截至 Codex CLI v0.116.0（2026-03-24），hooks 仍是实验性功能，需要手动启用。在 ~/.codex/config.toml 中添加：[features]
multi_agent = true
codex_hooks = true
Kilo Code 集成
Kilo Code 是一个开源（Apache 2.0）AI 编程 Agent 平台，支持 VS Code 扩展、JetBrains 插件和 CLI 三种形态，拥有 750K+ 用户。
trellis init --kilo -u your-name
.kilocode/ 目录下生成配置：
Trellis 为 Kilo 生成的内容：
trellis init --kilo 会在 .kilocode/workflows/ 下生成工作流文件。这是 Kilo 的 slash command 等效物 — 在聊天中输入 /start.md、/check.md 等调用。
| Trellis / Claude Code | Kilo Code（Trellis 生成） | 说明 |
|---|
.claude/commands/*.md | .kilocode/workflows/*.md | 工作流命令，输入 /start.md 等调用 |
project/
├── .kilocode/
│ └── workflows/ # 命令（等同于 slash commands）
│ ├── start.md # /start.md — 会话初始化
│ ├── brainstorm.md # /brainstorm.md
│ ├── before-dev.md # /before-dev.md
│ ├── check.md # /check.md
│ ├── check-cross-layer.md # /check-cross-layer.md
│ ├── finish-work.md # /finish-work.md
│ ├── break-loop.md # /break-loop.md
│ ├── create-command.md # /create-command.md
│ ├── integrate-skill.md # /integrate-skill.md
│ ├── onboard.md # /onboard.md
│ ├── parallel.md # /parallel.md
│ ├── record-session.md # /record-session.md
│ └── update-spec.md # /update-spec.md
Kilo 还支持 rules/、rules-code/、rules-architect/、skills/、launchConfig.json 和 mcp.json — 但这些不由 Trellis 生成。如有需要可手动创建。详见 Kilo Code 文档。 # 1. 运行 start workflow 获取完整上下文
/start.md
# 2. 切换到 Orchestrator 模式处理复杂任务
# Kilo 自动拆解任务并分配给 Code/Architect 等模式
# 3. 描述任务，AI 开发...
# 4. 运行检查 workflow
/check.md
# 5. 完工
/finish-work.md
Kilo 的 Orchestrator Mode 与 Trellis 的 Multi-Agent Pipeline 理念相似，但实现不同：
Trellis 使用 git worktree 物理隔离 + Hook 编排，Kilo 使用内置模式切换 + 独立对话上下文。
两者可以互补——Trellis 的 Spec 管理和 Task 系统为 Kilo 提供结构化的项目上下文。
Kiro 集成
Kiro 是 Amazon 推出的 AI IDE，基于 Code OSS（VS Code 开源内核），主打 Spec-Driven Development（规范驱动开发）。支持 IDE、CLI 和 Autonomous Agent 三种形态。
trellis init --kiro -u your-name
trellis init --kiro 会在 .kiro/skills/ 下生成 skill 文件。每个 skill 是一个带 YAML frontmatter 的 SKILL.md 文件，遵循 Agent Skills 开放标准。
| Trellis / Claude Code | Kiro（Trellis 生成） | 说明 |
|---|
.claude/commands/*.md | .kiro/skills/*/SKILL.md | 12 个带 YAML frontmatter 的 skill |
project/
├── .kiro/
│ └── skills/ # Agent Skills（YAML frontmatter + 指令）
│ ├── start/SKILL.md
│ ├── brainstorm/SKILL.md
│ ├── before-dev/SKILL.md
│ ├── check/SKILL.md
│ ├── check-cross-layer/SKILL.md
│ ├── finish-work/SKILL.md
│ ├── break-loop/SKILL.md
│ ├── create-command/SKILL.md
│ ├── integrate-skill/SKILL.md
│ ├── onboard/SKILL.md
│ ├── record-session/SKILL.md
│ └── update-spec/SKILL.md
Kiro 还支持 steering/、hooks/、specs/、prompts/、agents/ 和 settings/ 目录 — 但这些不由 Trellis 生成。如有需要可手动创建。详见 Kiro 文档。 # 1. 使用 start skill 初始化会话上下文
# 2. 描述任务，AI 开发...
# 3. 使用 check skill 验证代码质量
# 4. 使用 finish-work skill 进行提交前检查
# 5. 完成后提交代码
OpenCode 集成
OpenCode 是基于 Bun 的开源 AI 编程 CLI。Trellis 把 OpenCode 当成接近 Claude Code 级别的平台对待——.opencode/plugins/ 的插件机制提供了等价于 SessionStart 的 hook。
trellis init --opencode -u your-name
.opencode/commands/trellis/ — slash 命令（start.md、before-dev.md、check.md、finish-work.md 等 0.4 全套命令）.opencode/agents/ — sub-agent 定义（implement.md、research.md、check.md），对接 OpenCode 的 Task 原语.opencode/plugins/session-start.js — 会话开始插件，自动注入 Trellis 上下文.agents/skills/ — 共享 Agent Skills 层（OpenCode 也读这个目录）
调用方式：/trellis:start、/trellis:before-dev 等。OpenCode 是为数不多能真正隔离 spawn sub-agent 的非 Claude 平台。
iFlow 集成
iFlow 是通义系衍生的 AI 编程 CLI。Trellis 与 iFlow 共享 Claude Code 的 Python hook 布局，自动化能力与 Claude Code 相当。
trellis init --iflow -u your-name
.iflow/commands/trellis/ — slash 命令（/trellis:start、/trellis:before-dev 等）.iflow/hooks/session-start.py + .iflow/hooks.json — SessionStart hook（与 Claude Code 共用同一份 Python 脚本）.iflow/settings.json — 项目级 iFlow 配置
iFlow 在 0.5.0-beta.0 被移除。0.4.0 GA 上完全支持；升级到 0.5 会删除 .iflow/ 目录。
Gemini CLI 集成
Gemini CLI 是 Google 官方出品的 Gemini 终端 agent。
trellis init --gemini -u your-name
.gemini/commands/trellis/{name}.toml — 0.4 命令集的 TOML 文件。Gemini CLI 按 TOML 命令格式加载，每个命令的 prompt 写在 prompt = """...""" 块里。.agents/skills/ — 共享 skills 层（Gemini CLI 读 agentskills.io 规范路径）
Gemini CLI 不提供 SessionStart hook，因此 prelude 需要显式跑 /trellis:start 来加载。
Qoder 集成
Qoder 本身支持 Custom Commands（在 Agent 输入框里输入 / 调用，存放在 ~/.qoder/commands/ 或 <项目>/.qoder/commands/）。但 Trellis 在 Qoder 上的设计选择是只以 auto-trigger skill 的形式交付工作流。Trellis 不往 .qoder/commands/ 写东西——那个空间留给你自己的 Custom Commands。
trellis init --qoder -u your-name
.qoder/skills/{name}/SKILL.md — 0.4 全套命令都渲染成 skill（start、brainstorm、before-dev、check、check-cross-layer、finish-work、break-loop、create-command、integrate-skill、onboard、record-session、update-spec）。平台根据用户意图自动匹配。
0.4.0 里 Qoder 在 Trellis 层面没有 SessionStart hook 通道，prelude 上下文靠用户触发 start skill 按需加载（Qoder 的 skill 选择器是唯一的用户入口）。
GitHub Copilot 集成
GitHub Copilot Chat 没有原生的 slash 命令原语。Trellis 把 0.4 命令集做成 prompt 文件，另加一份常驻的 instructions 文件。
trellis init --copilot -u your-name
.github/copilot-instructions.md — 每次 Chat 会话自动加载，承载 Trellis prelude.github/prompts/trellis-{name}.prompt.md — 各命令的 prompt 文件（trellis-start.prompt.md、trellis-check.prompt.md 等），通过 Copilot 的 “Run Prompt” 选择器调用
不支持 hook。prelude 由 instructions 文件顶替 SessionStart。
Windsurf 集成
Windsurf（Codeium 的 agent IDE）用 workflow 文件 + 常驻 rules 构建。Trellis 把命令映射到 Windsurf workflow，prelude 映射到 Windsurf rules。
trellis init --windsurf -u your-name
.windsurf/workflows/trellis-{name}.md — 每个 Trellis 命令对应一个 workflow，从 Windsurf 工作流选择器调用.windsurf/rules/trellis.md — 常驻规则，承载 Trellis prelude
没有 hook。workflow 手动调用，rule 文件保证上下文常在。
CodeBuddy 集成
CodeBuddy 是腾讯云的 AI 编程助手，支持 MCP 扩展能力。
trellis init --codebuddy -u your-name
.codebuddy/commands/trellis/{name}.md —— 12 个 slash 命令（调用方式 /trellis:start、/trellis:check 等）
0.4.0 里 CodeBuddy 是纯 command 平台，没有 hook 或 sub-agent——规范加载需要显式跑 /trellis:before-dev。
Antigravity 集成
Antigravity 是 Google 的实验性 agent IDE，使用 .agent/workflows/ 下的 workflow 文件。
trellis init --antigravity -u your-name
.agent/workflows/{name}.md —— Trellis workflow，通过 Antigravity 的 workflow 选择器调用。内容从共享的 Codex skill 源适配而来。
没有 hook 或 sub-agent 支持；纯手动调用的 workflow 模型。
Factory Droid 集成
Factory Droid 是 Factory.ai 的 agent-capable CLI，有 hook、有 sub-agent，Trellis 对它走接近 Claude Code 的完整流程。
trellis init --droid -u your-name
.factory/commands/trellis/{name}.md — slash 命令.factory/agents/{name}.md — sub-agent 定义（implement、research、check）.factory/skills/ — auto-trigger skills.factory/hooks/session-start.py + .factory/hooks.json — SessionStart hook（与 Claude Code 同一套 Python 脚本）
操作系统兼容性
| 操作系统 | 支持状态 | 说明 |
|---|
| macOS | ✅ 完整支持 | 主力开发平台，所有功能均已验证 |
| Linux | ✅ 完整支持 | 所有功能均已验证 |
| Windows | ✅ 完整支持 | 脚本已全部迁移为 Python，原生支持 Windows |
| 注意事项 | 说明 |
|---|
| Python 脚本 | .trellis/scripts/ 下的脚本为 Python，需要 Python 3.10+，跨平台兼容 |
| Python Hook | .claude/hooks/ 下的 Hook 脚本需要 Python 3.10+，跨平台兼容 |
| 路径分隔符 | Trellis 内部使用 /，Python 自动处理路径转换 |
| Git worktree | Multi-Agent Pipeline 依赖 git worktree，各平台均支持 |
多开发者协作
不冲突的部分（各人独立）：
workspace/{name}/ — 每人独立目录.developer — gitignored，每人独立- 并行任务的 worktree — 物理隔离
可能冲突的部分（需要协调）：
spec/ — 多人可能同时修改同一规范tasks/ — 多人可能操作同一任务
最佳实践：
- Spec 修改通过 PR 审查
- 任务指派明确（
--assignee 参数）
- 重要的 spec 变更在团队会议上讨论
worktree.yaml 完整配置
# 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
trellis update 与版本管理
# 查看当前版本
cat .trellis/.version
# 更新到最新版本
trellis update
# 预览更新（不实际应用）
trellis update --dry-run
# 强制覆盖所有文件
trellis update -f
# 跳过所有变更文件
trellis update -s
.trellis/.template-hashes.json 存储了每个模板文件的 SHA-256 哈希。trellis update 时：
- 计算本地文件哈希
- 与记录的模板哈希对比
- 如果一致 → 文件未被用户修改 → 安全更新
- 如果不一致 → 文件被用户修改 → 提示冲突
- 用户选择：覆盖 / 跳过 / 合并
