安装与首个任务

快速开始

安装

# 全局安装
npm install -g @mindfoldhq/trellis@latest

# 在项目目录初始化
cd your-project

操作系统要求: Mac、Linux、Windows 完整支持。脚本已全部迁移为 Python，跨平台兼容。

初始化命令根据你使用的平台选择：

trellis init -u your-name —— 自动检测 Claude Code，配置 .claude/（commands、agents、hooks）。

trellis init -u your-name —— 自动检测 Cursor，配置 .cursor/commands/。

trellis init --opencode -u your-name —— 写入 .opencode/commands/trellis/、.opencode/agents/、.opencode/plugins/（session-start hook）。

trellis init --codex -u your-name —— 写入 AGENTS.md、.agents/skills/、.codex/agents/、.codex/hooks/。~/.codex/config.toml 里开 codex_hooks = true 可启用完整 hook 支持。

trellis init --iflow -u your-name —— 写入 .iflow/commands/trellis/ + .iflow/hooks/session-start.py（与 Claude Code 同一套 Python hook）。

trellis init --gemini -u your-name —— 写入 TOML 命令文件到 .gemini/commands/trellis/ + 共享 .agents/skills/。

trellis init --kilo -u your-name —— 写入 workflow 文件到 .kilocode/workflows/（调用方式 /start.md 等）。

trellis init --kiro -u your-name —— 写入 skill 形态的命令到 .kiro/skills/。

trellis init --qoder -u your-name —— 写入 .qoder/skills/{name}/SKILL.md（12 个 Trellis 命令全部以 auto-trigger skill 交付；不写 .qoder/commands/，把 Qoder 原生 Custom Commands 空间留给你自己用）。

trellis init --copilot -u your-name —— 写入 .github/copilot-instructions.md + .github/prompts/trellis-{name}.prompt.md。

trellis init --windsurf -u your-name —— 写入 .windsurf/workflows/trellis-{name}.md + .windsurf/rules/trellis.md。

trellis init --codebuddy -u your-name —— 写入 12 个 slash 命令到 .codebuddy/commands/trellis/。

trellis init --antigravity -u your-name —— 写入 Trellis workflow 到 .agent/workflows/（通过 Antigravity 的 workflow 选择器调用）。

trellis init --droid -u your-name —— 写入 .factory/commands/trellis/ + .factory/agents/ + .factory/hooks/session-start.py。

一条命令可以带多个平台 flag：trellis init --codex --gemini --copilot -u your-name。 your-name 会成为你的开发者身份标识，并创建个人工作区 .trellis/workspace/your-name/。

平台配置

trellis init 会自动检测并配置已安装的平台：

平台	配置目录	命令格式
Claude Code	`.claude/commands/trellis/`、`.claude/agents/`、`.claude/hooks/`	`/trellis:start`
Cursor	`.cursor/commands/*.md`	`/trellis-start`
OpenCode	`.opencode/commands/trellis/`、`.opencode/agents/`、`.opencode/plugins/`	`/trellis:start`
Codex	`AGENTS.md`、`.agents/skills/`、`.codex/agents/`、`.codex/hooks/`	`$start`
iFlow	`.iflow/commands/trellis/`、`.iflow/hooks/`	`/trellis:start`
Gemini CLI	`.gemini/commands/trellis/*.toml`	`/trellis:start`
Kilo	`.kilocode/workflows/`	`/start.md`
Kiro	`.kiro/skills/*/SKILL.md`	`@start`
Qoder	`.qoder/skills/`	skill 自动匹配
GitHub Copilot	`.github/copilot-instructions.md`、`.github/prompts/`	Run Prompt
Windsurf	`.windsurf/workflows/`、`.windsurf/rules/`	workflow 选择器
CodeBuddy	`.codebuddy/commands/trellis/*.md`	`/trellis:start`
Antigravity	`.agent/workflows/*.md`	workflow 选择器
Factory Droid	`.factory/commands/trellis/`、`.factory/agents/`、`.factory/hooks/`	`/trellis:start`

平台能力对比（0.4.0 GA——14 个平台）

能力	CC	Cursor	OpenCode	Codex	iFlow	Gemini	Kilo	Kiro	Qoder	Copilot	Windsurf	CodeBuddy	Antigravity	Droid
会话自动注入	✅	❌	✅	⚡	✅	❌	⚡	⚡	⚡	⚡	⚡	❌	❌	✅
子 Agent 规范注入	✅	❌	✅	⚡	✅	❌	❌	⚡	❌	❌	❌	❌	❌	✅
Ralph Loop 质量门	✅	❌	⚡	❌	✅	❌	❌	⚡	❌	❌	❌	❌	❌	⚡
Multi-Agent Pipeline	✅	❌	✅	❌	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌

CC = Claude Code。图例：✅ 完整 / ⚡ 部分（通过手动调用或 opt-in 平台 flag）/ ❌ 不支持。

首次使用三步走

# 步骤 1：打开 Claude Code 终端
# Hook 自动注入上下文，你可以直接描述任务（也可运行 /start 了解完整流程）

# 步骤 2：描述你要做什么

"添加用户登录功能"

# 步骤 3：AI 自动工作

# AI 会读取规范 → 创建任务 → 调用 Agent 实现 → 自我检查

# 完成后你测试、提交、记录会话即可

# 步骤 1：打开 Cursor，必须先调用
/start

# 步骤 2：描述你要做什么
"添加用户登录功能"

# 步骤 3：AI 自动工作
# AI 会读取规范 → 创建任务 → 实现 → 你手动运行 /trellis-check 检查
# 完成后你测试、提交、记录会话即可

# 步骤 1：Codex 通过 AGENTS.md 提供基础上下文
# 需要运行 $start 获取完整上下文

# 步骤 2：描述你要做什么

"添加用户登录功能"

# 步骤 3：AI 自动工作

# 完成后你测试、提交、记录会话即可

# 步骤 1：打开 OpenCode 终端
# Hook 自动注入上下文，你可以直接描述任务（也可运行 /start 了解完整流程）

# 步骤 2：描述你要做什么
"添加用户登录功能"

# 步骤 3：AI 自动工作
# 完成后你测试、提交、记录会话即可

# 步骤 1：Kilo 通过 .kilocode/rules/ 自动加载项目规范
# 可运行 /start.md workflow 获取完整上下文

# 步骤 2：描述你要做什么

"添加用户登录功能"

# 步骤 3：AI 自动工作

# Kilo Orchestrator Mode 会拆解任务分配给 Code/Architect 等模式

# 完成后你测试、提交、记录会话即可

# 步骤 1：Kiro 通过 .kiro/steering/ 自动加载项目规范
# 选择 Spec 模式生成需求→设计→任务三件套

# 步骤 2：描述你要做什么
"添加用户登录功能"

# 步骤 3：AI 自动工作
# Kiro 按 tasks.md 中的 checklist 逐步实现
# Agent Hooks 可在文件保存时自动触发检查
# 完成后你测试、提交、记录会话即可

上面 Tab 展示的是最常用平台。另外 8 个平台（Gemini CLI、iFlow、Qoder、GitHub Copilot、Windsurf、CodeBuddy、Antigravity、Factory Droid）安装后工作流跟 Claude Code 一致——详见第 13 章各平台章节。

远程 Spec 模板

你可以在初始化时直接拉取现成的 Spec 模板，而不用从零开始写。

官方 Marketplace

# 交互模式：浏览并选择可用模板
trellis init -u your-name

# 非交互模式：指定模板 ID
trellis init -u your-name --template electron-fullstack

交互式选择器会展示官方 Marketplace 中的所有模板。你也可以选择空白模板从头开始。

自定义仓库（`--registry`）

从你自己的 GitHub、GitLab 或 Bitbucket 仓库拉取 Spec：

# 直接下载：仓库目录直接成为 .trellis/spec/
trellis init --registry gh:myorg/myrepo/my-team-spec

# Marketplace 模式：仓库包含 index.json 和多个模板
trellis init --registry gh:myorg/myrepo/marketplace

# 从自定义 Marketplace 选择特定模板
trellis init --registry gh:myorg/myrepo/marketplace --template my-template

# 指定分支
trellis init --registry gh:myorg/myrepo/specs#develop

# GitLab 或 Bitbucket
trellis init --registry gitlab:myorg/myrepo/specs
trellis init --registry bitbucket:myorg/myrepo/specs

源格式：provider:user/repo[/subdir][#ref]

Provider	前缀
GitHub	`gh:` 或 `github:`
GitLab	`gitlab:`
Bitbucket	`bitbucket:`

ref（分支/标签）省略时默认为 main。

处理已有 Spec

当 .trellis/spec/ 已存在时，使用策略参数：

参数	行为
`--overwrite`	删除现有 spec 目录后重新下载
`--append`	只复制目标目录中不存在的文件
（都不加）	交互式询问如何处理

搭建自定义 Marketplace

在你的仓库中创建 index.json：

{
  "version": 1,
  "templates": [
    {
      "id": "my-backend-spec",
      "type": "spec",
      "name": "My Backend Spec",
      "description": "Backend conventions for our team",
      "path": "marketplace/specs/my-backend-spec",
      "tags": ["backend", "node"]
    }
  ]
}

path 字段相对于仓库根目录。目前仅支持 type: "spec" 类型。

私有仓库

对于私有仓库，通过 GIGET_AUTH 环境变量设置个人访问令牌：

GIGET_AUTH=ghp_xxxxx trellis init --registry gh:myorg/private-repo/specs

GitHub fine-grained token 需要 Contents 和 Metadata 读权限。

目录结构全貌

your-project/
├── .trellis/                          # Trellis 核心目录
│   ├── .developer                     # 开发者身份 (gitignored)
│   ├── .current-task                  # 当前活跃任务指针
│   ├── .version                       # Trellis 版本号
│   ├── .template-hashes.json          # 模板文件哈希 (用于 update)
│   ├── workflow.md                    # 开发工作流指南
│   ├── worktree.yaml                  # Multi-Agent worktree 配置
│   │
│   ├── spec/                          # 项目规范库
│   │   ├── frontend/                  #   前端规范
│   │   │   ├── index.md               #     规范索引
│   │   │   ├── component-guidelines.md
│   │   │   ├── hook-guidelines.md
│   │   │   ├── state-management.md
│   │   │   ├── type-safety.md
│   │   │   ├── quality-guidelines.md
│   │   │   └── directory-structure.md
│   │   ├── backend/                   #   后端规范
│   │   │   ├── index.md
│   │   │   ├── database-guidelines.md
│   │   │   ├── error-handling.md
│   │   │   ├── logging-guidelines.md
│   │   │   ├── quality-guidelines.md
│   │   │   └── directory-structure.md
│   │   └── guides/                    #   思维指南
│   │       ├── index.md
│   │       ├── cross-layer-thinking-guide.md
│   │       └── code-reuse-thinking-guide.md
│   │
│   ├── workspace/                     # 开发者工作区
│   │   ├── index.md                   #   工作区总索引
│   │   └── {developer-name}/          #   每人独立目录
│   │       ├── index.md               #     个人索引
│   │       └── journal-N.md           #     会话日志
│   │
│   ├── tasks/                         # 任务目录
│   │   ├── {MM-DD-task-name}/         #   活跃任务
│   │   │   ├── task.json              #     任务元数据
│   │   │   ├── prd.md                 #     需求文档
│   │   │   ├── info.md                #     技术设计 (可选)
│   │   │   ├── implement.jsonl        #     Implement Agent 上下文
│   │   │   ├── check.jsonl            #     Check Agent 上下文
│   │   │   └── debug.jsonl            #     Debug Agent 上下文
│   │   └── archive/                   #   已归档任务
│   │       └── {YYYY-MM}/
│   │
│   └── scripts/                       # 自动化脚本
│       ├── task.py                    #   任务管理 (14 个子命令)
│       ├── get-context.py             #   获取会话上下文
│       ├── get-developer.py           #   获取开发者身份
│       ├── init-developer.py          #   初始化开发者
│       ├── add-session.py             #   记录会话
│       ├── common/                    #   公共库
│       │   ├── paths.py
│       │   ├── developer.py
│       │   ├── git-context.py
│       │   ├── task-utils.py
│       │   ├── task-queue.py
│       │   ├── phase.py
│       │   ├── registry.py
│       │   └── worktree.py
│       └── multi-agent/               #   并行开发脚本
│           ├── plan.py
│           ├── start.py
│           ├── status.py
│           ├── create-pr.py
│           └── cleanup.py
│
├── .claude/                           # Claude Code 配置
│   ├── settings.json                  #   Hook 和权限配置
│   ├── commands/                      #   Slash 命令
│   │   └── trellis/                   #     Trellis 命令集
│   │       ├── start.md
│   │       ├── parallel.md
│   │       ├── record-session.md
│   │       ├── finish-work.md
│   │       ├── onboard.md
│   │       ├── before-dev.md
│   │       ├── before-dev.md
│   │       ├── check.md
│   │       ├── check.md
│   │       ├── check-cross-layer.md
│   │       ├── break-loop.md
│   │       ├── create-command.md
│   │       └── integrate-skill.md
│   ├── agents/                        #   Agent 定义
│   │   ├── dispatch.md
│   │   ├── plan.md
│   │   ├── implement.md
│   │   ├── check.md
│   │   ├── debug.md
│   │   └── research.md
│   ├── hooks/                         #   Hook 脚本
│   │   ├── session-start.py
│   │   ├── inject-subagent-context.py
│   │   └── ralph-loop.py
│   └── skills/                        #   Skill 目录
│
├── .cursor/                           # Cursor 配置
│   └── commands/
│       └── trellis-*.md               #   Cursor 版命令集
│
├── AGENTS.md                          # Codex 入口文件
├── .agents/                           # Agent Skills (Codex / OpenCode)
│   └── skills/
│
├── .kilocode/                         # Kilo Code 配置
│   ├── rules/                         #   项目规则（所有模式通用）
│   ├── workflows/                     #   Workflow 命令
│   └── skills/                        #   Agent Skills
│
├── .kiro/                             # Kiro 配置
│   ├── steering/                      #   项目上下文（Steering 系统）
│   ├── hooks/                         #   Agent Hooks（事件驱动自动化）
│   ├── prompts/                       #   自定义提示词
│   └── specs/                         #   Spec-Driven Development 文档
│
├── .iflow/                            # iFlow 配置
│   ├── commands/trellis/              #   Slash 命令
│   └── hooks/                         #   SessionStart hook
│
├── .gemini/                           # Gemini CLI 配置
│   └── commands/trellis/              #   TOML 命令
│
├── .qoder/                            # Qoder 配置
│   └── skills/                        #   12 个 auto-trigger skill
│
├── .github/                           # GitHub Copilot 配置
│   ├── copilot-instructions.md        #   自动加载的 prelude
│   └── prompts/                       #   各命令 prompt
│
├── .windsurf/                         # Windsurf 配置
│   ├── workflows/                     #   命令 workflow
│   └── rules/                         #   常驻 prelude
│
├── .codebuddy/                        # CodeBuddy 配置
│   └── commands/trellis/              #   12 个 slash 命令
│
├── .agent/                            # Antigravity 配置
│   └── workflows/                     #   Workflow 文件
│
└── .factory/                          # Factory Droid 配置
    ├── commands/trellis/              #   Slash 命令
    ├── agents/                        #   Sub-agent 定义
    └── hooks/                         #   SessionStart hook

你的第一个任务

启动会话

Claude Code
Cursor
Codex
OpenCode

打开 Claude Code 终端，session-start.py Hook 自动触发，上下文已注入。你可以直接描述任务，也可以运行 /start 了解完整流程。AI 会自动执行以下操作：

读取 workflow.md 了解开发流程
运行 get-context.py 获取当前状态（你的身份、Git 状态、活跃任务）
读取 spec/frontend/index.md 和 spec/backend/index.md 了解项目规范
问你：“What would you like to work on?”

打开 Cursor，必须先输入：

/start

AI 才会读取上下文。Cursor 的 Hook 支持尚在开发中，当前需要通过命令手动触发上下文加载。

Codex 通过 AGENTS.md 提供基础上下文，但需要运行 $start 获取完整的项目上下文（身份、Git 状态、活跃任务等）。

OpenCode 的 Hook 系统在会话开始时自动注入上下文，无需手动输入 /start。用户打开终端即可直接描述任务。可选运行 /start 获取更详细的上下文报告。

AI 创建任务并开发

你说：“添加用户登录功能”。AI 会：

1. 调用 Research Agent 分析代码库
   → 找到相关 spec 文件和代码模式

2. 创建任务目录
   → .trellis/tasks/02-27-user-login/
   → 生成 task.json、prd.md、implement.jsonl 等

3. 激活任务
   → task.py start（设置 .current-task）

4. 调用 Implement Agent
   → Hook 自动注入 implement.jsonl 中配置的所有 spec
   → Agent 按规范实现功能

5. 调用 Check Agent
   → Hook 注入 check.jsonl 中配置的检查规范
   → Agent 检查代码质量并自动修复
   → Ralph Loop 确保 lint/typecheck 通过

测试和提交

AI 完成后会提示你：

# 运行项目测试
pnpm lint && pnpm typecheck && pnpm test

# 确认功能正常后提交
git add src/components/LoginForm.tsx src/api/auth.ts
git commit -m "feat(auth): add user login feature"

记录会话

/record-session

AI 会调用 add-session.py，将本次会话内容追加到你的 journal 文件中，并更新个人索引。

第二天回来 — 跨会话记忆

第二天打开新会话，输入 /start：

AI: "Hi Alice! 昨天你完成了用户登录功能 (commit abc1234)，
     包括: LoginForm 组件、JWT middleware、users 表。
     今天想做什么？"

AI 通过 session-start.py Hook 读取了你的 workspace journal，记住了上次的工作内容。

平台差异: Claude Code 和 OpenCode 通过 Hook 自动读取 journal 实现跨会话记忆。 Cursor、Codex 用户需要通过 /start（或 $start）命令手动触发上下文加载，才能获得跨会话记忆。

开始使用

进阶

Use Cases

Resource Marketplace

社区

安装与首个任务

快速开始

安装

平台配置

平台能力对比（0.4.0 GA——14 个平台）

首次使用三步走

远程 Spec 模板

官方 Marketplace

自定义仓库（`--registry`）

处理已有 Spec

搭建自定义 Marketplace

私有仓库

目录结构全貌

你的第一个任务

启动会话

AI 创建任务并开发

测试和提交

记录会话

第二天回来 — 跨会话记忆

开始使用

进阶

Use Cases

Resource Marketplace

社区

​快速开始

​安装

​平台配置

​平台能力对比（0.4.0 GA——14 个平台）

​首次使用三步走

​远程 Spec 模板

​官方 Marketplace

​自定义仓库（--registry）

​处理已有 Spec

​搭建自定义 Marketplace

​私有仓库

​目录结构全貌

​你的第一个任务

​启动会话

​AI 创建任务并开发

​测试和提交

​记录会话

​第二天回来 — 跨会话记忆

快速开始

安装

平台配置

平台能力对比（0.4.0 GA——14 个平台）

首次使用三步走

远程 Spec 模板

官方 Marketplace

自定义仓库（`--registry`）

处理已有 Spec

搭建自定义 Marketplace

私有仓库

目录结构全貌

你的第一个任务

启动会话

AI 创建任务并开发

测试和提交

记录会话

第二天回来 — 跨会话记忆