安装 && 快速上手使用

快速开始

安装

# 全局安装（beta 通道）
npm install -g @mindfoldhq/trellis@beta

# 进入你的项目目录
cd your-project

系统要求：Mac、Linux、Windows 全部支持。需要 Node.js 18+ 和 Python 3.9+。

trellis init 会自动检测已安装的平台，也可以用 flag 显式指定。每一个平台都需要最少 init 一次。随意组合：

# 交互式：检测已安装的平台并询问要配置哪些
trellis init -u your-name

# 显式：配置一个或多个平台
trellis init -u your-name --claude
trellis init -u your-name --claude --cursor --opencode
trellis init -u your-name --codex --gemini
trellis init -u your-name --pi

your-name 会成为你的开发者身份，在 .trellis/workspace/your-name/ 创建个人工作区。支持的 flag：--claude、--cursor、--opencode、--codex、--kiro、--gemini、--qoder、--codebuddy、--copilot、--droid、--pi、--antigravity、--windsurf、--kilo。除了这 14 个已配置平台，任何读取 .agents/skills/ 规范的 AI 编码 agent（Amp、Cline、Deep Agents、Firebender、Kimi Code CLI、Warp 等）也能直接消费 Trellis：Codex 的 skill 就写在这个目录下，这些文件能被该生态的其他 agent 直接读取。

平台配置

trellis init 为每个平台写入各自的配置目录。.trellis/ 下的核心概念跨平台一致，差异在于 command、skill、sub-agent、hook 的交付方式。

平台	配置目录
Claude Code	`.claude/commands/trellis/`、`agents/`、`skills/`、`hooks/`
Cursor	`.cursor/commands/`、`agents/`、`skills/`、`hooks/`
OpenCode	`.opencode/commands/trellis/`、`agents/`、`skills/`、`plugins/`
Codex	`.codex/agents/`、`skills/`、`hooks/` + 仓库根 `AGENTS.md`
Kiro	`.kiro/agents/`、`skills/`、`hooks/`
Gemini CLI	`.gemini/commands/trellis/`、`agents/`、`skills/`、`hooks/`
Qoder	`.qoder/commands/`、`agents/`、`skills/`、`hooks/`
CodeBuddy	`.codebuddy/commands/trellis/`、`agents/`、`skills/`、`hooks/`
Copilot	`.github/copilot/`、`prompts/`、`agents/`、`skills/`、`hooks/`
Droid	`.factory/commands/trellis/`、`droids/`、`skills/`、`hooks/`
Pi Agent	`.pi/prompts/`、`skills/`、`agents/`、`extensions/trellis/`、`settings.json`
Kilo	`.kilocode/workflows/`、`skills/`
Antigravity	`.agent/workflows/`、`skills/`
Windsurf	`.windsurf/workflows/`、`skills/`

.agents/skills/ 是一份跨平台共享层（agentskills.io 规范），trellis init 会把所有 skill 都写一份到这里，供 Amp、Cline、Deep Agents、Firebender、Kimi Code CLI、Warp 等遵循 .agents/skills/ 规范的 agent 直接读取。

init 场景对照

trellis init 根据 .trellis/ 与 .trellis/.developer 的存在状态自动分派。按你的情境挑对应的命令：

场景	命令	产物
首次 init 项目	`trellis init -u your-name --claude`	创建 `.trellis/` 骨架 + bootstrap task `00-bootstrap-guidelines`，引导填项目 spec
往已有项目加新平台	`trellis init --cursor`（或不带参数走交互式，会列出未配置平台）	在现有 `.trellis/` 上铺新平台配置目录；不产生 task
新开发者加入已有项目	`trellis init -u their-name`	生成 joiner 引导 task `00-join-<slug>`，引导读 workflow + spec；准备开始时在当前 AI 会话里 start 它
同一开发者换机器	同上	同样生成一份 joiner task（因为 `.developer` 不进 git），嫌多可直接 `task.py archive`
同一人同机器 re-init	`trellis init -u your-name`	no-op —— `.trellis/` 与 `.developer` 都在，啥都不做

--force / --skip-existing 只影响 有冲突的文件怎么处理（强制覆盖 / 跳过），不改变 init 的分派逻辑本身。

判据信号：.trellis/.developer 是 gitignored 的 per-checkout 身份文件（天然不进 git），所以新克隆的 checkout 永远没有它 —— 这是判断”新开发者”的干净信号。.trellis/workspace/<name>/ 进 git，不能作为判据。

基本流程

描述你要做什么即可，AI 会按 workflow.md 走 Plan → Execute → Finish。如果你觉得当前流程走完了，就运行 /trellis:continue。

# 1. 描述你要做什么
"新增用户登录功能"

# 2. AI 按 workflow.md 走 Plan → Execute → Finish

# 3. 你测试 + commit，然后
/trellis:finish-work

Agent-capable 平台（Claude Code、OpenCode、Cursor、Gemini、Qoder、CodeBuddy、Copilot、Droid、Pi Agent，以及开了 features.hooks 的 Codex —— 旧版用 codex_hooks）每次开会话都会通过 SessionStart hook 或 extension 自动加载 workflow 和上下文，这些平台本身不发 /trellis:start 这个 slash 命令；想重新加载就新开一个会话。只有 Kilo / Antigravity / Windsurf 这类 agent-less 平台会发 /trellis:start（或 /start.md）作为显式入口。

目录结构

下面是用 Claude Code 跑完 trellis init 后的目录。其他平台会写到各自的子目录，但 .trellis/ 核心一致。

your-project/
├── .trellis/                          # Trellis 核心（跨平台一致）
│   ├── .developer                     # 开发者身份（gitignored）
│   ├── .version                       # Trellis 版本号
│   ├── .template-hashes.json          # 模板文件 hash（update 用）
│   ├── workflow.md                    # 开发工作流指南
│   ├── config.yaml                    # 项目配置（packages、update.skip、hooks）
│   │
│   ├── .runtime/                      # 每个会话自己的运行时状态（gitignored）
│   │   └── sessions/                  #   每个 AI 会话/窗口对应一个 active task
│   │       └── <session-key>.json
│   │
│   ├── spec/                          # 项目 spec 库
│   │   ├── frontend/                  #   前端 spec（monorepo 可按 package 分层）
│   │   ├── backend/                   #   后端 spec
│   │   └── guides/                    #   思考指南
│   │
│   ├── workspace/                     # 开发者工作区
│   │   ├── index.md
│   │   └── {developer-name}/
│   │       ├── index.md
│   │       └── journal-N.md
│   │
│   ├── tasks/                         # 任务目录
│   │   ├── {MM-DD-task-name}/         #   活跃任务
│   │   │   ├── task.json              #     任务元信息
│   │   │   ├── prd.md                 #     需求文档
│   │   │   ├── info.md                #     技术设计（可选）
│   │   │   ├── implement.jsonl        #     trellis-implement 上下文
│   │   │   ├── check.jsonl            #     trellis-check 上下文
│   │   │   └── research.jsonl         #     trellis-research 上下文
│   │   └── archive/                   #   归档任务
│   │       └── {YYYY-MM}/
│   │
│   └── scripts/                       # 自动化脚本（Python）
│       ├── task.py                    #   任务管理
│       ├── get_context.py             #   会话上下文
│       ├── add_session.py             #   记录会话
│       ├── create_bootstrap.py        #   首次 spec bootstrap
│       └── common/                    #   共享库
│
├── .claude/                           # Claude Code 配置
│   ├── settings.json                  #   hook 和权限配置
│   ├── commands/trellis/              #   显式命令
│   │   ├── start.md
│   │   ├── finish-work.md
│   │   └── continue.md
│   ├── agents/                        #   Sub-agent 定义
│   │   ├── trellis-implement.md
│   │   ├── trellis-check.md
│   │   └── trellis-research.md
│   ├── skills/                        #   Auto-trigger skills
│   │   ├── trellis-brainstorm/
│   │   ├── trellis-before-dev/
│   │   ├── trellis-check/
│   │   ├── trellis-update-spec/
│   │   └── trellis-break-loop/
│   └── hooks/                         #   Hook 脚本
│       ├── session-start.py
│       ├── inject-subagent-context.py
│       └── inject-workflow-state.py
│
├── .cursor/           # Cursor：commands/ + rules/
├── .opencode/         # OpenCode：commands/trellis/、agents/、skills/、plugins/
├── .codex/            # Codex：prompts/、skills/ + 仓库根 AGENTS.md
├── .kiro/             # Kiro：steering/、prompts/、skills/
├── .gemini/           # Gemini CLI：commands/trellis/
├── .qoder/            # Qoder：commands/、skills/、agents/、hooks/
├── .codebuddy/        # CodeBuddy：commands/trellis/
├── .factory/          # Droid：commands/trellis/、skills/、hooks/
├── .pi/               # Pi Agent：prompts/、skills/、agents/、extensions/trellis/
└── .github/           # Copilot：copilot-instructions.md、prompts/

你的第一个任务

启动会话

General
Codex
Kiro
Kilo / Antigravity / Windsurf

打开终端，SessionStart hook 自动触发，Trellis 上下文已经在 AI 的上下文里了：

workflow.md 的 TOC + Phase 1/2/3 step 详情
身份、git 状态、活跃任务列表
spec 索引

直接描述任务即可。怀疑自动注入没跑、想重新加载上下文，就新开一个会话——SessionStart hook 会再跑一遍 workflow.md + get_context.py，然后把 “想干什么？” 甩给你。这类平台上 /trellis:start 不是 slash 命令（start 已经被 hook 吃掉，别去找）。

在 ~/.codex/config.toml 开启：

[features]
hooks = true   # Codex 0.129+。旧版用 `codex_hooks = true`。

Codex 0.129+ 还要在 TUI 里跑一次 /hooks 命令，审批 Trellis 安装的 UserPromptSubmit hook，否则 hook 不会激活、workflow 指引不会自动注入。Trellis 内置 fallback 会在 hook 没触发时让 AI 手动读 trellis-start skill，所以工作流仍然能跑，只是体验下降。之后和 Class-1 平台一样：打开终端，SessionStart hook 自动注入 Trellis 上下文，直接描述任务即可。

Kiro 默认通过 .kiro/ 下的 agent / skill 文件交付 Trellis 内容。Kiro 的 Agent Hook 是用户自己配置的（文件保存触发、构建成功触发等），Trellis 不原生带任何 Agent Hook wiring。直接描述任务，Kiro 按 skill 匹配进入 brainstorm 流程；需要完整上下文报告时跑 @trellis:start。

这三个平台只有 workflow + skill，没有 hook 和 sub-agent。入口：

Kilo：/start.md
Antigravity：打开 .agent/workflows/start.md
Windsurf：/trellis-start

AI 执行 workflow 里写的步骤：读 workflow.md、跑 get_context.py、读 spec 索引、询问你想做什么。后续的 implement / check 阶段会在主会话里内联跑，而不是 spawn sub-agent。

AI 建任务并开发

你说：“新增用户登录功能”。AI 按 workflow.md 的三阶段走：

Phase 1 — Plan（和你互动）
 1.0 task.py create 创建任务目录（.trellis/tasks/MM-DD-user-login/）
 1.1 激活 trellis-brainstorm skill，和你一问一答澄清需求，迭代 prd.md
 1.2 需要调研时 spawn trellis-research sub-agent，产物写到 research/
 1.3 AI curate implement.jsonl / check.jsonl（task create 已 seed）
     填入 Phase 2 sub-agent 需要的 spec + research 文件，不放代码路径
 1.4 task.py start 把任务写进当前会话的 runtime

Phase 2 — Execute
 2.1 spawn trellis-implement sub-agent（class-1 平台 hook 自动注入 implement.jsonl）
     → 按 prd.md 写代码，不 git commit
 2.2 spawn trellis-check sub-agent（hook 自动注入 check.jsonl）
     → 对照 spec 审 diff + 跑 lint / typecheck / test，自修复违规

Phase 3 — Finish
 3.1 激活 trellis-check skill，做最终验证
 3.2（按需）激活 trellis-break-loop skill 做 debug 复盘
 3.3 激活 trellis-update-spec skill，把新知识写回 .trellis/spec/
 3.4 提醒你跑 /trellis:finish-work

AI 停下或跳步骤时：跑 /trellis:continue，AI 根据当前 task 的 status 和每轮注入的 workflow-state breadcrumb，按 workflow.md 判断下一步该做什么（before-dev / check / update-spec 等）继续推进。

结束会话

/trellis:finish-work

finish-work 调 add_session.py 追加一条 journal，更新个人索引。任务真正完成（代码已合入、验收条件满足）时，通过 task.py archive 归档。

跨会话记忆

下次打开会话，SessionStart hook（或平台 prelude）会读你的 workspace journal 和活跃任务列表，AI 能回忆起上次做了什么：

AI："Alice 好，你上次完成了用户登录功能（commit abc1234），
     包含 LoginForm 组件、JWT 中间件、users 表。
     接下来想干什么？"

Journal 存在 .trellis/workspace/{name}/journal-N.md；每次 /trellis:finish-work 都会追加一条。Trellis 内部会按 AI 会话/窗口记录各自的当前 task，下次进同一个会话能直接接上；task.py finish 会清掉这个指针。

远程 Spec 模板

不用从零写 spec，在 init 时拉取预置的 spec 模板：

官方 Marketplace

# 交互式：浏览可用模板并挑一个
trellis init -u your-name

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

交互选择器会列出官方 marketplace 的所有模板，选一个或者直接从空 spec 开始。

自定义 Registry（`--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

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

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

不写 ref（branch/tag）时默认 main。

已有 spec 的处理

.trellis/spec/ 已存在时，用 strategy flag：

Flag	行为
`--overwrite`	删除现有 spec 目录再下载
`--append`	只拷贝不存在的文件
（都不传）	交互式询问怎么处理

构建自定义 Marketplace

在仓库根目录创建 index.json：

{
  "version": 1,
  "templates": [
    {
      "id": "my-backend-spec",
      "type": "spec",
      "name": "My Backend Spec",
      "description": "团队后端约定",
      "path": "marketplace/specs/my-backend-spec",
      "tags": ["backend", "node"]
    }
  ]
}

path 相对仓库根目录。目前只支持 type: "spec"。

私有仓库

私有仓库要设置 GIGET_AUTH 环境变量，值是 personal access token：

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

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

开始使用

进阶

Use Cases

Resource Marketplace

社区

安装 && 快速上手使用

快速开始

安装

平台配置

init 场景对照

基本流程

目录结构

你的第一个任务

启动会话

AI 建任务并开发

结束会话

跨会话记忆

远程 Spec 模板

官方 Marketplace

自定义 Registry（`--registry`）

已有 spec 的处理

构建自定义 Marketplace

私有仓库

开始使用

进阶

Use Cases

Resource Marketplace

社区

Documentation Index

​快速开始

​安装

​平台配置

​init 场景对照

​基本流程

​目录结构

​你的第一个任务

​启动会话

​AI 建任务并开发

​结束会话

​跨会话记忆

​远程 Spec 模板

​官方 Marketplace

​自定义 Registry（--registry）

​已有 spec 的处理

​构建自定义 Marketplace

​私有仓库

快速开始

安装

平台配置

init 场景对照

基本流程

目录结构

你的第一个任务

启动会话

AI 建任务并开发

结束会话

跨会话记忆

远程 Spec 模板

官方 Marketplace

自定义 Registry（`--registry`）

已有 spec 的处理

构建自定义 Marketplace

私有仓库