Trellis - 跨平台 AI 编程脚手架

约 1574 字大约 5 分钟

2026-05-28

简介

Trellis 是一个跨 14+ AI 编程平台的统一 agent harness（代理脚手架），由 Mindfold 团队（mindfold-ai/Trellis）维护。它把团队的编码规范、任务上下文和跨会话记忆，自动注入每一次 AI 编码会话，让 AI 沿着既定的"藤蔓支架"生长，而不是四处蔓延。

官方一句话定位："AI 的能力像藤蔓一样生长，充满活力但四处蔓延，Trellis 是 AI 的支架，引导它沿着你的规范前行。"

项目 2026-01-26 才创建，到 5 月已收获 8.5k+ stars、467 forks，开发节奏极快，使用 AGPL-3.0 协议开源。

解决什么问题？

在 Trellis 出现之前，深度使用 AI 编程助手的团队会撞到一组共性问题：

痛点	Trellis 的方案
每次开会话都要手动喂规范、贴上下文	Hooks 在 `SessionStart` / `UserPromptSubmit` 时自动注入规范与状态
规范散落、随时间漂移	`.trellis/spec/` 把规范写成版本化的"可执行契约"，纳入 Git
AI 跨会话失忆，前面做的事下次忘光	`.trellis/workspace/<dev>/journal-N.md` 持久日志，每人独立
多 AI 工具配置割裂（CLAUDE.md / .cursorrules / Copilot 各一套）	同一份 `.trellis/` 适配 14+ 平台
团队 AI 水平不齐	共享 spec 让全员复用最佳实践，新人 onboarding 成本骤降

核心概念

Trellis 整套体系围绕 .trellis/ 目录展开：

.trellis/
├── workflow.md          # Plan→Execute→Finish 状态机（唯一真源）
├── config.yaml          # 项目配置
├── spec/                # 团队规范（frontend/、backend/、guides/）
├── workspace/<dev>/     # 每位开发者的 journal-N.md（隔离记忆）
├── tasks/<date-slug>/   # prd.md / info.md / implement.jsonl / check.jsonl / research/
├── .runtime/sessions/   # 会话↔任务映射，gitignored
└── scripts/             # task.py / get_context.py 等 Python 工具

八个核心概念：

概念	说明
Spec	Markdown 编码规范，区分 Design Decision / Convention / Pattern / Gotcha 四种形态，强调"可执行契约"而非口号
Workspace	每位开发者独立日志区，避免多人协作时记忆互相污染
Task	单元工作容器，含 PRD、context manifest（JSONL）、阶段产物
Skill	自动触发的工作流，不需手动调用
Sub-agent	三个内置角色：`trellis-research` / `trellis-implement` / `trellis-check`
Command	三个显式命令：`/trellis:start` `/trellis:continue` `/trellis:finish-work`
Hook	`SessionStart` + `UserPromptSubmit`，注入 `[workflow-state:STATUS]` 上下文块
Journal	持久会话记录，写在 `.trellis/workspace/{name}/journal-N.md`

内置 Skill 一览：

trellis-brainstorm —— 把模糊需求转成结构化 PRD
trellis-before-dev —— 写码前自动加载相关 spec
trellis-check —— 实现完成后自检并自修
trellis-update-spec —— 把本次经验沉淀回 spec
trellis-break-loop —— debug 后主动写规则防复发

兼容的 AI 平台

目前支持 14 个平台：Claude Code、Cursor、OpenCode、Codex、Kiro、Kilo、Gemini CLI、Antigravity、Windsurf、Qoder、CodeBuddy、GitHub Copilot、Droid、Pi Agent。

接入方式分三类：

类别	平台	机制
Hook-Push	Claude Code / Cursor / OpenCode / CodeBuddy / Droid / Pi	Hook 主动推送上下文
Pull-Prelude	Codex / Copilot / Gemini CLI / Kiro	Sub-agent 启动时显式读取前置内容
Native Skill	Kilo / Windsurf	在主会话里内联加载

安装与配置

环境要求：Node ≥ 18、Python ≥ 3.9，支持 macOS / Linux / Windows。

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

# 交互式初始化（自动检测当前项目用了哪些 AI 工具）
trellis init -u your-name

# 指定单个平台
trellis init -u your-name --claude

# 多平台同时接入
trellis init -u your-name --claude --cursor --opencode

# 用官方模板 bootstrap
trellis init -u your-name --template electron-fullstack

# 从远程仓库继承规范注册表
trellis init --registry gh:myorg/myrepo/specs

使用方式

三个核心命令

/trellis:start          # 启动一个新任务（许多平台经 hook 自动触发）
/trellis:continue       # 把当前任务推进到下一阶段，无需手动记步骤
/trellis:finish-work    # 仅在 commit 后调用，归档任务并写 journal

Task 工具脚本

task.py 暴露了底层操作：

python .trellis/scripts/task.py create <name>     # 创建任务
python .trellis/scripts/task.py start <id>        # 开始
python .trellis/scripts/task.py finish <id>       # 完成
python .trellis/scripts/task.py archive <id>      # 归档
python .trellis/scripts/task.py add-context <id>  # 追加上下文
python .trellis/scripts/task.py validate <id>     # 校验

实际示例

一次完整的端到端使用流程：

1. 用自然语言描述需求
   └─> trellis-brainstorm 自动生成 .trellis/tasks/<date-slug>/prd.md

2. /trellis:continue
   └─> AI 准备 implement / check 阶段所需上下文

3. /trellis:continue
   └─> sub-agent 写代码 + 自检（trellis-check）

4. /trellis:continue
   └─> 经验 crystallize 回 spec/

5. git commit && /trellis:finish-work
   └─> 任务归档，写入 journal-N.md

团队协作场景：.trellis/spec/、.trellis/tasks/、.trellis/workflow.md 全部入 Git；.runtime/ 和 workspace/<dev>/ 分别 gitignored 或隔离。一个 50 人团队同时使用 Claude Code 与 Cursor，shared spec 能让 trellis-check 在两种工具下产出一致的校验结果。

与同类工具的差异

vs. Claude Code 的 CLAUDE.md + skills 体系：Trellis 独立于 CLAUDE.md，通过 hooks 注入结构化的 [workflow-state] breadcrumb；带显式三段式状态机（Plan / Execute / Finish）；同一份配置还能同时驱动 Cursor、Copilot 等工具。
vs. Cursor .cursorrules / Continue 配置：.cursorrules 是静态字符串拼接，Trellis 是任务感知的动态上下文路由（按 task status 注入不同 block）。
vs. spec-kit / Kiro 等：差异化关键在 跨平台统一 harness + workflow 状态机 + 跨会话 journal 记忆 + 自动触发的 skill，开发者基本不用记命令，三段式 continue 即可推进全流程。

最佳实践

适合使用的场景：

中大型团队，多人 + 多种 AI 工具混用
已有较成熟的编码规范，希望 AI 严格遵循
重视长期项目记忆，不希望新人 onboarding 成本太高

不太必要的场景：

个人小项目、一次性脚本（设置成本盖过收益）
团队尚未沉淀任何规范（spec 写不出，Trellis 也救不了）
只用单一 AI 工具且原生配置已经够用（如纯 Claude Code 团队用好 CLAUDE.md + skills 通常够了）

写 Spec 时的要点：把规范写成可执行契约——明确"在什么情况下、必须做什么、违反时如何检测"，避免空泛口号，否则 trellis-check 无法把它落地为校验。

Claude Code

OpenAI

Qwen Code