首页/资讯中心/详情

每日一个开源项目（第145篇）：Trellis - 把项目记忆、规范和任务上下文持久化进代码仓库

每日一个开源项目（第145篇）：Trellis - 把项目记忆、规范和任务上下文持久化进代码仓库
📅 发布时间：2026/6/30 1:52:03

引言

“AI 编码 10% 是写代码，90% 是重新解释你的技术栈。Trellis 解决了 AI Agent 最糟糕的问题：失忆。”

这是"每日一个开源项目"系列的第145篇文章。今天的主角是Trellis——一个把项目规范、任务上下文和会话记忆持久化进代码仓库的 AI 编程 Harness 框架。

你用 Claude Code 开发一个项目，把规范讲清楚、上下文建立好、调出好的结果。关掉终端。第二天打开，重新开始：重新解释技术选型，重新说明代码风格，重新描述当前任务的背景……

这个问题有个名字：Agent 失忆症。每次会话都是新开始，之前所有建立起来的上下文全部消失。

Trellis 的解法是把该记住的东西存进仓库：.trellis/spec/存规范，.trellis/tasks/存任务和 PRD，.trellis/workspace/存会话日志。Agent 启动时自动读取，不需要每次重新解释。

你将学到什么

  • .trellis/三目录系统的设计逻辑：spec / tasks / workspace 各司其职
  • 4 阶段工作流：Plan → Implement → Verify → Finish 的完整闭环
  • Trellis Skill：四个内置工作流模块的具体作用
  • 与 CLAUDE.md / AGENTS.md 的对比：为什么单文件方案会变成单体文件
  • 团队场景：spec 提交到 Git 后如何让整个团队受益
  • 支持的 16 个平台和初始化方式

前置知识

  • 使用过 Claude Code、Cursor 或类似 AI 编程工具
  • 熟悉基本的 Git 工作流
  • 了解 CLAUDE.md 或 .cursorrules 的基本概念

项目背景

项目简介

Trellis 是一个 AI 编程 Agent Harness 框架，定位是"AI 的脚手架，引导它沿着你的规范路径工作"。

“Harness”（驭套）这个词在 2026 年的 AI 编码语境里越来越重要——不是 Agent 本身，而是围绕 Agent 的约束、记忆和工作流结构。Trellis 是这个领域里最系统的开源实现之一，有学术论文引用（OpenReview 上的"Agent Harness Engineering: A Survey"）。

核心设计决策：把所有持久化信息存进 Git 仓库。规范可以被 Code Review，会话记忆可以被团队共享，任务上下文可以跨工具使用。这不只是文件路径的选择，而是把 AI 工作方式纳入工程管理体系的设计取向。

作者/团队介绍

  • 组织: Mindfold AI（mindfold-ai）
  • 文档: docs.trytrellis.app
  • License: AGPL-3.0
  • 技术栈: TypeScript 67.9% / Python 25.8%

项目数据

  • ⭐ GitHub Stars:11,300+
  • 🍴 Forks: 641+
  • 💻 支持平台: 16 个 AI 编程平台
  • 📄 License: AGPL-3.0

主要功能

三目录系统

Trellis 在仓库根目录下维护一个.trellis/目录，三个子目录各有职责：

.trellis/ ├── spec/ ← 项目规范（提交进 Git） │ ├── coding-standards.md │ ├── architecture.md │ ├── tech-stack.md │ └── team-conventions.md │ ├── tasks/ ← 任务和 PRD（提交进 Git） │ ├── active/ │ │ └── feature-auth/ │ │ ├── prd.md │ │ ├── implementation-context.md │ │ └── review-context.md │ └── completed/ │ └── workspace/ ← 会话日志（可选择 .gitignore） └── your-name/ └── journal.md

spec/：这是核心。所有你不想每次都对 Agent 重复解释的内容：技术栈选型的理由、代码风格规定、架构约束、命名约定、已知的坑。这些文件提交进 Git，被 Trellis 在每次会话开始时自动注入到 Agent 的上下文里。

tasks/：任务不只是一行描述，而是完整的工作单元：PRD（需求文档）、实现上下文（Agent 开始编码前需要知道的一切）、审查上下文（检查代码改动时需要对照的内容）。

workspace/：每个开发者的会话日志。记录了"这次会话做了什么，遇到了什么问题，下次继续时需要知道什么"。Agent 在新会话启动时读取这个文件，知道上次在哪里停下。

4 阶段工作流

Trellis 定义了一个完整的工作循环：

Plan → Implement → Verify → Finish ↑ ↓ └──────── spec 更新 ←────────────┘

阶段一：Plan（trellis-brainstorm）

不是直接开始写代码，而是先把需求想清楚：

启动 trellis-brainstorm ↓ Agent 逐问题引导你澄清需求： "这个功能的成功标准是什么？" "有没有需要遵守的技术约束？" "哪些边界情况需要处理？" ↓ 生成 prd.md（产品需求文档） 复杂的调研子任务 → 分配给子 Agent ↓ PRD 存入 .trellis/tasks/active/[task-name]/

阶段二：Implement（trellis-implement）

执行时自动注入上下文：

启动 trellis-implement ↓ 自动读取： - .trellis/spec/ 里的相关规范 - .trellis/tasks/active/[task-name]/prd.md - .trellis/workspace/[your-name]/journal.md ↓ 按 PRD 编写代码，遵守 spec 约束

阶段三：Verify（trellis-check）

代码写完后的自动审查：

启动 trellis-check ↓ 对比 spec：改动是否符合规范？ 运行 lint、类型检查、测试 发现问题 → 尝试自动修复 修复失败的问题 → 汇报给开发者

阶段四：Finish（trellis-update-spec）

这是闭环里最有价值的部分：

启动 trellis-update-spec ↓ 分析本次任务中发现的新模式、新约定、新规则 把这些学习结果提升进 .trellis/spec/ ↓ 下一次会话从这里出发，比这次更智能

与 CLAUDE.md / AGENTS.md 的对比

CLAUDE.md / .cursorrules 的问题： 单一文件 → 随时间增长变成"什么都有"的大杂烩 全量注入 → 不管任务是什么，所有内容都进上下文 无任务结构 → 没有 PRD，没有实现/审查上下文的分离 无持久记忆 → 会话结束，一切归零 Trellis 的做法： 模块化 spec → 按任务相关性按需注入 任务上下文 → PRD + 实现上下文 + 审查上下文分层管理 workspace 记忆 → 跨会话的连续性 Finish 阶段 → 每次任务结束 spec 自动更新

Trellis 不是要替换 CLAUDE.md，而是围绕它建立更系统的结构。你仍然可以有 CLAUDE.md，Trellis 的 spec 文件补充它。

项目详细剖析

安装和初始化

# 安装 Trellis CLInpminstall-g@mindfoldhq/trellis@latest# 基本初始化（自动检测安装了哪些 AI 工具）trellis init-uyour-name# 指定平台初始化trellis init --claude-code--cursor--codex-uyour-name

trellis init会：

  1. 创建.trellis/目录结构
  2. 根据检测到的平台生成对应的配置文件
  3. 创建初始 spec 模板（可以让 AI 基于现有代码分析生成）
  4. 在.gitignore里根据偏好处理 workspace 目录

初始 spec 生成（现有项目）：

在 Claude Code 里： "分析这个项目的代码，为它生成 .trellis/spec/ 的初始内容， 包括技术栈说明、代码风格、架构约束" 然后人工审查和精炼生成的 spec 文件

平台支持

Trellis 支持 16 个 AI 编程平台，生成平台特定的配置文件：

已确认支持的：Claude Code、Cursor、OpenCode、Codex、GitHub Copilot、Devin 等

对于 Claude Code，Trellis 生成CLAUDE.md的 Trellis 结构化版本和相应的 Skill 文件，让 Claude Code 知道在什么时候使用trellis-brainstorm、trellis-implement等工作流。

Trellis Skill 系统

4 个内置 Skill 定义了工作流的入口：

Skill触发时机核心行为
trellis-brainstorm开始新任务时引导需求澄清，输出 PRD
trellis-implement开始编码时注入上下文，执行实现
trellis-check代码完成后对照规范审查，自动修复
trellis-update-spec任务完成后提升新学习结果进规范

这些 Skill 遵循 agentskills.io 开放标准，和 android/skills 等项目使用同一套格式。

团队使用场景

spec 文件提交到 Git 后，整个团队受益于同一套规范：

场景：新团队成员加入 传统方式：文档在 Confluence，可能过时；问老人；踩坑 Trellis 方式： git clone 后 → .trellis/spec/ 里有完整的技术栈说明和约定 AI Agent 自动遵守这些规范 加入者一天内就能用上团队标准的 AI 辅助工作流
场景：团队新发现一个最佳实践 传统方式：口头传递，或者更新某个可能没人读的文档 Trellis 方式： 某个人跑完 trellis-update-spec 后 spec 文件更新 提交 PR，团队 review 合并后，所有人的后续 AI 会话都自动使用新规范

workspace journal 格式

会话日志让 Agent 知道上次在哪里停下：

# Journal - your-name ## 2026-06-28 ### 会话摘要 - 完成了 auth 模块的 JWT 验证逻辑 - 发现 refresh token 在并发请求下有竞态条件 - 暂时用 Redis 加分布式锁解决，但觉得应该有更好的方案 ### 下次继续时需要知道的 - refresh token 竞态问题的修复方案需要进一步评估 - 需要写 auth 模块的集成测试 - Edge case: 同一用户多设备同时 refresh token ### 悬而未决的问题 - 要不要引入 rotating refresh token？需要确认产品需求

下次会话时，Agent 读到这个 journal，知道背景，不需要重新解释。

快速开始

# 安装npminstall-g@mindfoldhq/trellis@latest# 进入你的项目目录cdyour-project# 初始化（自动检测 Claude Code 等工具）trellis init-uyour-name# 开始第一个任务# 在 Claude Code 里说：# "用 trellis-brainstorm 开始一个新任务：为用户认证模块添加 MFA 支持"

项目地址与资源

  • 🌟GitHub: mindfold-ai/Trellis
  • 📖文档: docs.trytrellis.app
  • 🏢Mindfold AI: github.com/mindfold-ai

总结

Trellis 解决的是 AI 编程工具链里一个系统性的问题：每次会话都从零开始，AI 不知道这个项目的上下文、这个团队的约定、上次任务的进展。

把规范、任务上下文和会话记忆存进 Git 仓库是一个设计决策，不只是实现细节。这意味着 AI 的工作方式被纳入了工程管理体系：规范可以被审查，记忆可以被共享，改动可以被追踪。

4 阶段工作流的闭环设计（尤其是 Finish 阶段把学习结果回写进规范）让系统随着使用积累变得更好，而不是每次都从同样的起点出发。

11.3k Stars 说明这个方向有真实需求。对于在多个项目或多个工具之间切换的开发者，或者团队里希望统一 AI 辅助开发标准的 Tech Lead，Trellis 值得认真评估。

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。