Trellis：让 AI 编码助手拥有项目记忆的工程框架

用过 Claude Code 或 Cursor 的人大概都遇到过这种情况：上次会话里花半小时跟 AI 解释的项目约定，这次开新会话又得从头说一遍。AI 写代码很快，但每次会话都从零开始，不记得你的代码规范、不记得上次做了什么、不记得团队的技术决策。mindfold-ai/Trellis 这个项目就是来解决这个问题。

前言

Trellis 的定位是「AI 编码的工程框架」。核心思路很简单：把规范、任务、记忆持久化到代码仓库里，这样任何 AI 编码助手都能读到。

具体来说，Trellis 在项目根目录创建一个 .trellis/ 目录，里面存放三类东西：

• .trellis/spec/ — 编码规范，按包和层级组织。写一次，每次 AI 会话自动注入相关规范

• .trellis/tasks/ — 任务记录，包含需求文档、设计文档、执行计划、上下文清单

• .trellis/workspace/ — 开发者日志，记录每次 AI 会话做了什么，跨会话保留上下文

这些文件跟着 Git 走，团队成员共享同一套规范和任务记录。个人日志保持独立，不会互相干扰。

```bash

# 安装

npm install -g @mindfoldhq/trellis@latest

# 在项目里初始化

trellis init -u your-name

# 也可以指定要集成的平台

trellis init --cursor --opencode --codex -u your-name

```

trellis init 命令会检测项目类型（是否 monorepo、有哪些包），然后生成对应的 .trellis/ 目录结构、AGENTS.md、以及各平台的配置文件（如 Claude Code 的 CLAUDE.md、Cursor 的 .cursorrules）。

CLI 入口在 packages/cli/src/index.ts，只暴露两个 API：版本号和 init 命令。init 命令的实现做了不少事情：检测 Python 版本（要求 >= 3.9）、检测项目结构、生成工作流文件、初始化模板哈希。

```typescript

export { VERSION } from "./constants/version.js";

export { init } from "./commands/init.js";

```

核心包 packages/core 的入口更简洁，只做 barrel re-export：

```typescript

export * from "./channel/index.js";

export * from "./task/index.js";

```

channel 模块导出了一整套类型定义和工具函数，包括 ChannelScope、ChannelType、ContextEntry、ChannelEvent 等。这些是 Trellis 上下文注入系统的基础设施。

Trellis 的核心是一个四阶段循环，定义在 .trellis/workflow.md 中：

```

Phase 1: Plan    → 分类需求、创建任务、编写规划产物

Phase 2: Execute → 任务状态变为 in_progress 后开始实现

Phase 3: Finish  → 验证、更新规范、提交、收尾

```

每个阶段有严格的步骤和检查点。Phase 1 要先判断是简单任务还是复杂任务，简单任务只需要 prd.md，复杂任务还需要 design.md 和 implement.md。Phase 1.3 会为子 Agent 平台整理 implement.jsonl 和 check.jsonl，这两个文件是上下文清单，告诉实现 Agent 和检查 Agent 该读哪些规范文件。

```jsonl

{"file": ".trellis/spec/cli/backend/conventions.md", "reason": "CLI 后端编码约定"}

{"file": ".trellis/spec/core/types/error-handling.md", "reason": "错误处理规范"}

```

格式是一行一个 JSON 对象，file 字段是仓库根目录的相对路径，reason 字段说明为什么要读这个文件。子 Agent 启动时，平台的 hook 会读取这些 jsonl 文件，把引用的规范内容注入到 Agent 的 prompt 里。

Trellis 最有意思的设计是 workflow-state breadcrumb 系统。workflow.md 里嵌入了类似这样的标签块：

```

[workflow-state:planning]

Load trellis-brainstorm; stay in planning.

Lightweight: prd.md can be enough...

[/workflow-state:planning]

```

每个任务状态（no_task、planning、in_progress、completed）对应一个标签块。当用户提交新消息时，平台 hook（Python 脚本 inject-workflow-state.py 或 OpenCode 插件）会读取当前任务状态，找到对应的标签块，把里面的文本注入到 AI 的 prompt 里。

这样 AI 每一轮对话都能知道自己处于哪个阶段、该做什么。不需要 AI 自己记住"我现在在 Phase 2 的 2.1 步"，因为每轮对话都会重新注入。

get_context.py 是上下文注入的入口脚本，支持三种模式：

```bash

python3 ./.trellis/scripts/get_context.py                            # 完整会话上下文

python3 ./.trellis/scripts/get_context.py --mode packages            # 列出包和规范层

python3 ./.trellis/scripts/get_context.py --mode phase --step 1.1    # 某个步骤的详细指引

```

在支持子 Agent 的平台（Claude Code、Cursor、OpenCode 等）上，Trellis 采用分发模式而不是内联实现。主会话负责调度，不直接写代码。

三个 Agent 角色有明确的职责边界：

• trellis-implement — 读规范和任务产物，写代码，跑 lint 和 typecheck。禁止 git commit

• trellis-check — 拿 git diff，对照规范和 PRD 审查，能修的小问题直接修，设计层面的问题记录上报。同样禁止 commit

• trellis-research — 做技术调研，输出写到 research/ 目录

implement Agent 的 prompt 定义在 .trellis/agents/implement.md 里，规定了读取顺序：先读 implement.jsonl 里列的规范文件，再读 prd.md，然后 design.md，最后 implement.md。报告格式也有模板，要求列出修改的文件、实现步骤、验证结果和未解决的问题。

check Agent 的 prompt 更严格。它要求区分两类问题：机械性的（lint 报错、类型缺失、错误 import）直接修；设计判断类的问题只记录不修，留给主会话决策。这个设计避免了检查 Agent 擅自改动设计逻辑。

分发时有自豁免规则：如果已经是 implement Agent，就不再 spawn 新的 implement 或 check Agent。防止 Agent 无限递归生成。

Trellis 支持 16 个 AI 编码平台，包括 Claude Code、Cursor、OpenCode、Codex、Kiro、Gemini、Qoder、CodeBuddy、Copilot、Droid、Pi 等。不同平台分两类：

• 子 Agent 分发型（Claude Code、Cursor 等）：主会话调度子 Agent，通过 jsonl 注入上下文

• 内联型（Codex inline、Kilo、Antigravity、Devin）：主会话直接写代码，用 trellis-before-dev skill 加载规范

workflow.md 中用平台标签块区分两种模式的指令。比如 Phase 2 的实现步骤，分发型平台写的是"Spawn the implement sub-agent"，内联型平台写的是"Load the trellis-before-dev skill to read project guidelines"。

task_store.py 实现了任务的完整 CRUD。任务创建时会生成日期前缀的目录名（如 07-09-feature-auth），写入 task.json，同时创建默认的 prd.md。

任务生命周期：

1. task.py create — 创建任务，状态设为 planning

2. task.py start — 状态翻转为 in_progress，breadcrumb 自动切换

3. task.py archive — 状态设为 completed，目录移到 archive/

支持父子任务树。一个复杂需求可以拆成多个子任务，每个子任务独立规划、实现、验证、归档。父子关系不是依赖系统，如果子任务 B 依赖子任务 A，要在 B 的 prd.md 里写明顺序。

README 的 FAQ 里专门回答了这个问题。CLAUDE.md、AGENTS.md、.cursorrules 这些文件是有用的入口点，但容易变成一个大而全的文件。Trellis 在它们之上加了分层规范、任务 PRD、工作流检查点、工作区记忆和平台感知的生成文件。

简单说，CLAUDE.md 是一份静态的提示词，Trellis 是一套有状态的工作流系统。

Trellis 依赖 Python 脚本做任务管理和上下文注入，要求项目环境有 Python >= 3.9。对于纯前端团队来说，引入 Python 依赖算一个额外成本。

.trellis/ 目录会产生不少文件，每个任务有独立的目录和多个产物文件。任务量大时，这个目录的结构维护需要一定的纪律性。项目提供了 trellis update 命令来同步模板更新，但自定义的 workflow 修改需要手动维护一致性。

AGPL-3.0 协议对商业使用有一定限制，团队选型时需要评估合规要求。

Trellis 适合两类场景：一是团队协作中需要统一 AI 编码标准的，规范跟着仓库走，新人 clone 下来就能用同一套约定；二是个人开发者在大型项目中使用多个 AI 编码工具的，Trellis 提供了跨平台的任务和记忆持久化。

项目地址：https://github.com/mindfold-ai/Trellis

如果这篇文章对你有帮助，可以关注一下我的公众号「编码者视角」，我会不定期分享类似的开源工具发现。

结语

Trellis 适合两类场景：一是团队协作中需要统一 AI 编码标准的，规范跟着仓库走，新人 clone 下来就能用同一套约定；二是个人开发者在大型项目中使用多个 AI 编码工具的，Trellis 提供了跨平台的任务和记忆持久化。 项目地址：https://github.com/mindfold-ai/Trellis