跳转到主要内容

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.

​
多平台与团队配置

Trellis 支持 14 个平台（Claude Code、Cursor、OpenCode、Codex、Kiro、Kilo、Gemini CLI、Antigravity、Windsurf、Qoder、CodeBuddy、GitHub Copilot、Droid、Pi Agent），以及任何读取 .agents/skills/ 规范的 AI 编码 agent（Amp、Cline、Deep Agents、Firebender、Kimi Code CLI、Warp 等）。.trellis/ 核心跨平台一致；差异在于各平台如何交付 hook、extension、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 或 extension 的平台上开新会话就自动注入 Trellis 上下文；没有自动会话注入的平台跑 /trellis:start 或对应平台的 start workflow。
不要选 Full re-initialize——那会覆盖 .trellis/、.claude/ 等已有配置，影响全团队。

​
能力矩阵

能力Claude CodeCursorOpenCodeCodexKiroGeminiQoderCodeBuddyCopilotDroidPi Agent
SessionStart / extension 自动注入✅✅✅⚡⚡✅✅✅✅✅✅
Sub-agent 上下文注入✅✅✅❌❌❌❌✅❌✅✅
Sub-agent（trellis-*）✅✅✅✅✅✅✅✅✅✅✅
Auto-trigger skill✅✅✅✅✅✅✅✅✅✅✅
显式 /trellis:* 命令✅✅✅——✅✅✅✅✅✅
图例：✅ Trellis 写入配置并由平台执行 · ⚡ 部分支持（Codex 需 features.hooks = true 开启，0.129+ 还要走一次 /hooks 审批；Kiro 的 Agent Hook 需用户自行 wiring） · ❌ 平台不暴露这个事件 · — 该平台没有命令原语，start / finish-work / continue 作为 skill 交付。Qoder 用的是 /trellis-{name}（连字符，不是冒号），通过原生 Custom Commands 交付 finish-work / continue；start 由 SessionStart hook 自动注入。Pi Agent 走 extension，不走 Python hook 文件，但行为一致：会话上下文、Bash 环境变量传递、sub-agent JSONL 注入都在 agent 动作前完成。 .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]
hooks = true   # Codex 0.129+。旧版用 `codex_hooks = true`。
Codex 0.129+ 还要在 TUI 里跑一次 /hooks 命令，审批 Trellis 安装的 UserPromptSubmit hook，否则 hook 不会激活、workflow 指引不会自动注入。不开启时 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/{name}.md，要求 YAML frontmatter 包含 name 和 description 字段）。Trellis 把 session-boundary 命令放到这里，让你可以显式地调用；阶段级工作流则保留为 auto-trigger skill。 布局：
  • .qoder/commands/trellis-{name}.md：session-boundary 命令 —— finish-work、continue，用 /trellis-finish-work、/trellis-continue 调用（start 由 Qoder 的 SessionStart hook 自动注入，无需命令）
  • .qoder/skills/trellis-{name}/SKILL.md：auto-trigger 工作流 skill —— brainstorm、before-dev、check、update-spec、break-loop
  • .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

​
Pi Agent

trellis init -u your-name --pi
Pi Agent 走 extension，不走 Python hook。Trellis 写入同样的 workflow 原语，然后 extension 解析当前 session id，在 Bash 命令和 sub-agent 运行前注入任务上下文。 布局：
  • .pi/prompts/trellis-{name}.md：会话边界 prompt（finish-work、continue；start 只在需要手动入口的平台存在）
  • .pi/skills/trellis-{name}/SKILL.md：5 个 Trellis 工作流 skill
  • .pi/agents/{name}.md：trellis-implement、trellis-check、trellis-research
  • .pi/extensions/trellis/index.ts：会话上下文、Bash TRELLIS_CONTEXT_ID 传递、sub-agent JSONL 注入
  • .pi/settings.json：extension 注册
extension 把当前任务状态存在 .trellis/.runtime/sessions/<session-key>.json，所以每个 Pi 窗口/会话都可以有自己的任务，不会抢别的窗口。

​
其他支持平台

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 文件。
除了 14 个已配置平台，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.9+。OpenCode 插件需要 Node.js 18+。

​
多开发者协作

按开发者隔离（不冲突）：
  • .trellis/workspace/{name}/：各自的 journal 和索引
  • .trellis/.developer：gitignored
  • .trellis/.runtime/：gitignored 的会话运行时状态；每个 AI 会话/窗口有自己的 active task 文件
共享状态（通过 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 移除 Multi-Agent Pipeline）以 migration manifest 形式发布。对破坏性 manifest 跑 trellis update 而不加 --migrate 会退出并打印说明，不会静默重命名。trellis update --migrate 应用 rename / delete 条目，每个冲突询问一次。