跳转到主要内容

​
多平台与团队配置

Trellis 支持 13 个平台（Claude Code、Cursor、OpenCode、Codex、Kiro、Kilo、Gemini CLI、Antigravity、Windsurf、Qoder、CodeBuddy、GitHub Copilot、Droid），以及任何读取 .agents/skills/ 规范的 AI 编码 agent（Amp、Cline、Deep Agents、Firebender、Kimi Code CLI、Warp 等）。.trellis/ 核心跨平台一致；差异在于各平台如何交付 hook、skill、sub-agent、command。

​
加入已初始化的 Trellis 项目

项目已经被别人 trellis init 过了，你作为新成员加入——直接跑 trellis init，CLI 会识别出已初始化，给你三个选项： 
? Trellis is already initialized. What would you like to do?
❯ Add AI platform(s)
  Set up developer identity on this device
  Full re-initialize
选项何时选
Add AI platform(s)想给当前项目加一个别人没装的平台（如你用 Cursor、但别人只装了 CC）
Set up developer identity on this device你是新成员，只要把自己的身份写到本机
Full re-initialize项目配置坏了，重来一遍
新成员选第 2 个。CLI 会问你想用的开发者名（默认取自 Git user），然后：
  • 写 .trellis/.developer 记录你的开发者名（gitignored，每台机器独立）
  • 在 .trellis/workspace/<your-name>/ 下建你自己的 journal 目录
完成后，在支持 SessionStart hook 的平台上开新会话就自动注入 Trellis 上下文；没 hook 的平台跑 /trellis:start（Kiro 上 @trellis:start）。
不要选 Full re-initialize——那会覆盖 .trellis/、.claude/ 等已有配置，影响全团队。

​
能力矩阵

能力Claude CodeCursorOpenCodeCodexKiroGeminiQoderCodeBuddyCopilotDroid
SessionStart hook（自动注入）✅✅✅⚡⚡✅✅✅✅✅
Sub-agent PreToolUse hook✅✅✅❌❌❌❌✅❌✅
Sub-agent（trellis-*）✅✅✅✅✅✅✅✅✅✅
Auto-trigger skill✅✅✅✅✅✅✅✅✅✅
显式 /trellis:* 命令✅✅✅——✅—✅✅✅
图例：✅ Trellis 写入配置并由平台执行 · ⚡ 部分支持（Codex 需 codex_hooks = true 开启；Kiro 的 Agent Hook 需用户自行 wiring） · ❌ 平台不暴露这个事件 · — 该平台没有命令原语，start / finish-work / continue 作为 skill 交付 .kilocode/、.agent/（Antigravity）、.windsurf/ 只有 workflow 和 skill，没有 sub-agent 也没有 hook。.agents/skills/ 在所有平台都会写一份，作为跨平台共享层。

​
Claude Code

自动化最完整。Hook 布局：
Hook触发效果
session-start.pySessionStart注入身份、git 状态、活跃任务
inject-workflow-state.pyUserPromptSubmit提示 AI 遵守当前任务的状态契约
inject-subagent-context.pyPreToolUse（Task）加载 implement.jsonl / check.jsonl / 等
Sub-agent：trellis-implement、trellis-check、trellis-research，在 .claude/agents/。 Skill：trellis-brainstorm、trellis-before-dev、trellis-check、trellis-update-spec、trellis-break-loop，在 .claude/skills/。 Command：start、finish-work、continue，在 .claude/commands/trellis/。

​
Cursor

trellis init -u your-name --cursor
Trellis 0.5 起 Cursor 是完整 class-1 平台：真 hook、真 sub-agent、真 skill。 布局：
  • .cursor/commands/trellis-{name}.md：start、finish-work、continue（扁平命名加 trellis- 前缀，调用形式 /trellis-start 等）
  • .cursor/skills/trellis-{name}/SKILL.md：5 个 trellis skill
  • .cursor/agents/：trellis-implement.md、trellis-check.md、trellis-research.md
  • .cursor/hooks/：共享 Python hook 脚本（与 Claude Code 兼容）
  • .cursor/hooks.json：hook 配置（Cursor 用独立文件，不是 settings.json）

​
OpenCode

trellis init -u your-name --opencode
OpenCode 1.2.x 是 class-1 平台（真 hook + 真 sub-agent）：
  • .opencode/commands/trellis/：start / finish-work / continue
  • .opencode/agents/：trellis-implement.md、trellis-check.md、trellis-research.md
  • .opencode/skills/：5 个 trellis skill
  • .opencode/plugins/：JS 插件：session-start.js、inject-subagent-context.js、inject-workflow-state.js
插件是 factory function（OpenCode 1.2+）。Trellis 生成的版本对齐 Claude Code 行为。

​
Codex

trellis init -u your-name --codex
布局：
  • AGENTS.md（仓库根）：入口文件，Codex 每个 session 自动读取（作为 prelude）
  • .codex/prompts/：trellis-start.md、trellis-finish-work.md、trellis-continue.md
  • .codex/skills/：5 个 trellis skill
  • .codex/agents/：TOML sub-agent：trellis-implement.toml、trellis-check.toml、trellis-research.toml
  • .codex/hooks/session-start.py + .codex/hooks.json：SessionStart hook（实验性）
Codex hook 是实验特性。在 ~/.codex/config.toml 开启：
[features]
codex_hooks = true
不开启时 Codex 走纯 prelude（每次读 AGENTS.md），内容一致，只是没有事件驱动注入。

​
Kiro

trellis init -u your-name --kiro
布局：
  • .kiro/steering/trellis.md：Trellis prelude，每个 session 加载
  • .kiro/prompts/trellis-*.md：prompt 式命令
  • .kiro/skills/*/SKILL.md：auto-trigger skill（Kiro 按 description/YAML 匹配）
Kiro 的 Agent Hook 可以在文件保存或构建成功时自动跑 Trellis skill，但这是用户自己配的；Trellis 不原生带任何 Kiro Agent Hook。

​
Gemini CLI

trellis init -u your-name --gemini
布局：
  • .gemini/commands/trellis/{name}.toml：TOML 命令文件——start.toml、finish-work.toml、continue.toml
  • .gemini/skills/trellis-{name}/SKILL.md：5 个 trellis skill
  • .gemini/agents/{name}.md：带 pull-based prelude 的 sub-agent 定义（sub-agent 自己 Read 自己的 JSONL，因为 Gemini 没有 sub-agent PreToolUse hook）
  • .gemini/hooks/session-start.py：SessionStart hook
  • .gemini/settings.json：hook 配置（只有 SessionStart）

​
Qoder

trellis init -u your-name --qoder
Qoder 本身支持 Custom Commands（在 Agent 输入框输入 / 调用，存放在 ~/.qoder/commands/ 或 <项目>/.qoder/commands/），但 Trellis 在 Qoder 上的设计选择是全部以 auto-trigger skill 交付，把 .qoder/commands/ 留给用户自己的 Custom Commands： 布局：
  • .qoder/skills/trellis-{name}/SKILL.md：所有模板（start、finish-work、continue、brainstorm、before-dev、check、update-spec、break-loop）都以 skill 形式交付，靠 skill 匹配驱动
  • .qoder/agents/{name}.md：带 pull-based prelude 的 sub-agent 定义
  • .qoder/hooks/session-start.py：SessionStart hook
  • .qoder/settings.json：hook 配置（只有 SessionStart——Qoder 没有 sub-agent PreToolUse hook）

​
CodeBuddy

trellis init -u your-name --codebuddy
CodeBuddy 是完整 class-1 平台（真 hook + 真 sub-agent）。 布局：
  • .codebuddy/commands/trellis/{name}.md：start、finish-work、continue
  • .codebuddy/skills/trellis-{name}/SKILL.md：5 个 trellis skill
  • .codebuddy/agents/{name}.md：sub-agent 定义
  • .codebuddy/hooks/*.py：共享 Python hook 脚本
  • .codebuddy/settings.json：hook 配置（SessionStart + sub-agent PreToolUse 注入）

​
GitHub Copilot

trellis init -u your-name --copilot
布局：
  • .github/copilot-instructions.md：Trellis prelude，每个 session 自动加载
  • .github/prompts/trellis-{name}.prompt.md：start / finish-work / continue 的 prompt 文件
  • .github/skills/trellis-{name}/SKILL.md：5 个 trellis skill
  • .github/agents/{name}.agent.md：带 pull-based prelude 的 sub-agent 定义（Copilot 的 sub-agent hook 触发不稳定，所以让 sub-agent 自己 Read 自己的 JSONL）
  • .github/copilot/hooks/*.py：Copilot 专属 + 共享 Python hook 脚本
  • .github/copilot/hooks.json：hook 配置（只有 SessionStart——sub-agent PreToolUse 不可用）

​
Droid

trellis init -u your-name --droid
Droid（factory.ai）是 class-1 平台，有 hook + sub-agent：
  • .factory/commands/trellis/：start / finish-work / continue
  • .factory/agents/：三个 trellis-* sub-agent
  • .factory/skills/：5 个 trellis skill
  • .factory/hooks/：SessionStart + sub-agent injection

​
其他支持平台

Trellis 还原生带有上面能力矩阵之外几个平台的配置器：
  • Kilo（--kilo）：写 .kilocode/workflows/（命令：start、finish-work）和 .kilocode/skills/trellis-{name}/SKILL.md（5 个 trellis skill）。没有 hook 集成。
  • Antigravity（--antigravity）：写 Antigravity 原生的 workflow 文件（3 个命令）。
  • Windsurf（--windsurf）：写 Windsurf 原生的 command 和 rule 文件。
除了 13 个已配置平台，Trellis 还能被任何遵循 .agents/skills/ 约定（agentskills.io 规范）的 AI 编码 agent 直接使用。Codex 的 skill 就写在这个目录下，这些文件也能被该生态的其他 agent（Amp、Cline、Deep Agents、Firebender、Kimi Code CLI、Warp 等）直接读取。这些平台上你通过 .trellis/ 核心加上各自 agent 读取的 prelude 文件来管理 Trellis。

​
操作系统

OS状态备注
macOS✅ 完整主平台
Linux✅ 完整已验证
Windows✅ 完整脚本全部 Python；Claude Code 通过 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 确保 hook cwd 正确
.trellis/scripts/ 和 Python hook 需要 Python 3.10+。OpenCode 插件需要 Node.js 18+。

​
多开发者协作

按开发者隔离（不冲突）：
  • .trellis/workspace/{name}/：各自的 journal 和索引
  • .trellis/.developer：gitignored
  • .trellis/.current-task：gitignored
共享状态（通过 PR 协调）：
  • .trellis/spec/：团队约定，和代码一样走 PR review
  • .trellis/tasks/：task JSON；显式 --assignee 避免冲突
Spec 的重要改动应在 review 中讨论；把 spec 库当成团队代码来对待。

​
trellis update 与版本管理

cat .trellis/.version          # 当前版本
trellis update                  # 升级到最新
trellis update --dry-run        # 预演
trellis update --migrate        # 应用破坏性变更的 migration（大版本必需）
trellis update -f               # 强制覆盖本地改过的文件
trellis update -s               # 跳过本地改过的文件
模板 hash 机制（.trellis/.template-hashes.json）：
  1. 计算本地文件 hash。
  2. 和记录的模板 hash 对比。
  3. 一致 ⇒ 用户未改 ⇒ 安全更新。
  4. 不一致 ⇒ 询问（覆盖 / 跳过），或根据 -f / -s 策略静默处理。
破坏性变更（比如 0.5.0-beta.0 移除 Multi-Agent Pipeline）以 migration manifest 形式发布。对破坏性 manifest 跑 trellis update 而不加 --migrate 会退出并打印说明，不会静默重命名。trellis update --migrate 应用 rename / delete 条目，每个冲突询问一次。