创见博客
在 Visionary 项目里安装 Trellis 后，我看到了什么
七崽爱吃小饼干2026/07/21阅读 4专栏 Trellis 与 AI Agent 工程化

这篇记录不是 Trellis 的完整教程，而是一次真实接入笔记：我刚刚在 Visionary 这个 Next.js 项目里安装了 Trellis，并且重点看了一下它实际往项目里放了哪些文件、这些文件如何影响 Code Agent 的工作方式，以及后续应该怎么使用和维护。

一句话概括：Trellis 更像是一个给 AI 编程工作流加“轨道”的项目脚手架。它不直接替你写业务代码，而是把任务规划、规范注入、上下文恢复、子代理分工、检查收尾这些流程固化到项目里，让 Agent 不容易在长会话里跑偏。

安装和初始化

全局安装 Trellis：

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

在项目根目录初始化 Trellis：

bash
trellis init -u your-name # 安装所有的 code agent 配置
trellis init --opencode -u your-name # 只安装指定平台配置，比如 OpenCode

初始化时需要选择合适的 spec 模板。Visionary 是一个 Next.js 项目，所以我选择了 Next.js 相关模板。

项目中初始化trellis，选择合适的spec模板

初始化过程中，Trellis 发现项目里已经存在 .opencode/package.json，因此提示配置冲突。我这里选择了跳过，避免覆盖已有 OpenCode 配置。

初始化完成后，git diff 里新增了大量文件。可以把它理解为 Trellis 往项目里安装了一套“AI 协作运行时配置”。

git diff，新增了130个文件

主要新增的是 .trellis 和 .opencode 两个目录，同时 AGENTS.md 里也被写入了一段 Trellis 管理的项目级说明。

目录

AGENTS.md：给所有 Agent 的入口说明

AGENTS.md 是 Agent 进入项目时最先看的说明之一。Trellis 在里面写入了一个受管理的区块，核心信息很简单：

  • .trellis/workflow.md：开发阶段和任务流转规则。
  • .trellis/spec/：项目或分层的编码规范。
  • .trellis/workspace/：开发者会话日志和索引。
  • .trellis/tasks/：任务目录，保存 PRD、设计、执行计划和上下文清单。

这个文件的作用不是装饰，而是把 Agent 的第一反应从“直接改代码”拉回到“先看 Trellis 工作流和项目规范”。

.trellis：任务、规范和工作流的核心目录

.trellis 是 Trellis 的主目录。在这个分支里，我看到它主要包含这些部分。

1. workflow.md：三阶段工作流

.trellis/workflow.md 是核心。它把开发过程拆成三个阶段：

  • Phase 1 Plan：先分类需求，拿到创建任务的确认，再写规划产物。
  • Phase 2 Execute：任务进入 in_progress 后才能执行实现和检查。
  • Phase 3 Finish：验证、更新规范、提交、记录会话和归档。

这个设计最重要的点是：Trellis 把“先规划再实现”变成了默认路径，而不是依赖 Agent 自觉。

它还定义了 <workflow-state> 面包屑。OpenCode 插件会从 workflow.md 的 [workflow-state:...] 区块读取当前状态提示，然后在每一轮用户输入里注入简短提醒。这样长会话里即使上下文变长，Agent 也会持续看到当前任务状态和下一步应该做什么。

2. tasks：每个任务一个目录

.trellis/tasks/ 下每个任务都有自己的目录。一个复杂任务通常会包含：

  • task.json：任务元数据，比如状态、创建人、分支、优先级。
  • prd.md：需求、约束、验收标准。
  • design.md：技术设计。
  • implement.md：执行计划和验证命令。
  • implement.jsonl / check.jsonl：给子代理注入上下文的文件清单。
  • research/：研究记录。

我这次完善文章本身也走了 Trellis 流程：先创建任务，再写 prd.md、design.md、implement.md，确认方向后才进入执行。

这个任务目录的价值是持久化。对 AI 编程来说，聊天上下文会被压缩、会丢失细节，但任务文件不会。下一次继续时，Agent 可以从任务产物恢复状态。

3. spec：给 Agent 注入的开发规范

.trellis/spec/ 是规范目录。这次选择的是 Next.js 全栈模板，所以里面有：

  • frontend/：组件、状态、样式、认证、API 集成等前端规则。
  • backend/：API、数据库、认证、日志、性能、类型安全等后端规则。
  • shared/：通用 TypeScript、依赖和代码质量规则。
  • guides/：开发前思考清单和跨层思考指南。
  • big-question/：常见坑，比如 PostgreSQL JSON/JSONB、Sentry 与 next-intl 冲突、Turbopack 与 flexbox 问题。

需要注意的是，这些 spec 目前更像“Next.js 全栈项目通用模板”，还不是完全贴合 Visionary 的项目真相。比如当前模板里提到了 React 19、TailwindCSS 4、oRPC、Drizzle、PostgreSQL，但 Visionary 当前 package.json 里是 React 18、TailwindCSS 3，并且项目实际依赖里有 MySQL 相关包。

所以我对它的定位是：先作为 Agent 的通用行为约束，后续再逐步把 Visionary 的真实约定沉淀进去。

4. workspace：开发者会话日志

.trellis/workspace/<developer>/ 用来保存开发者会话记录。当前开发者是 liujingmin，对应有 journal 和 index 文件。

这部分解决的是跨会话记忆问题。Trellis 希望每次任务完成后都能把重要决策、提交和总结写入 workspace，避免下次从零开始。

5. config.yaml：项目级配置

.trellis/config.yaml 大部分保持默认值。这个分支里值得注意的是 channel worker guard：

yaml
channel:
  worker_guard:
    idle_timeout: 5m
    max_live_workers: 6

也就是 Trellis channel worker 空闲 5 分钟后会被清理，同时最多允许 6 个 live worker。这是防止多代理协作时 worker 残留过多、占用资源。

.opencode：把 Trellis 接到 OpenCode 上

如果说 .trellis 是工作流和知识库，那么 .opencode 就是 OpenCode 平台的接线层。它主要包含 commands、plugins、skills、agents 和少量本地依赖。

1. OpenCode 插件

这次安装里最关键的是三个插件：

  • .opencode/plugins/session-start.js
  • .opencode/plugins/inject-workflow-state.js
  • .opencode/plugins/inject-subagent-context.js

session-start.js 会在一次会话开始时注入 Trellis SessionStart 上下文。也就是我打开会话后看到的当前开发者、分支、脏文件数量、活动任务、可用 spec 索引等信息。

inject-workflow-state.js 会在每一轮用户消息里注入 <workflow-state>。它不自己硬编码流程，而是读取 .trellis/workflow.md 里的 [workflow-state:STATUS] 区块。这意味着工作流文档本身是单一事实来源。

inject-subagent-context.js 用在 Task 子代理场景。主会话派发 trellis-implement、trellis-check、trellis-research 时，它会读取当前任务的 implement.jsonl 或 check.jsonl，再把相关规范和任务产物注入给子代理。

这三个插件串起来，基本就是 Trellis 在 OpenCode 里的运行机制：

text
SessionStart 上下文
  -> 每轮 workflow-state 提醒
  -> 子代理执行时注入任务和 spec 上下文

2. OpenCode 命令

.opencode/commands/trellis/ 里有几个命令说明：

  • /trellis:start：加载当前状态、工作流概览和 spec 索引。
  • /trellis:continue：根据当前任务状态决定从哪个阶段继续。
  • /trellis:finish-work：归档任务并记录会话日志。

这些命令不是业务命令，而是给 Agent 使用的工作流入口。

3. OpenCode skills

.opencode/skills/ 下有多个 Trellis 技能，例如：

  • trellis-brainstorm：需求不清或新任务规划。
  • trellis-before-dev：写代码前读取任务和规范。
  • trellis-check：修改后做质量检查。
  • trellis-update-spec：把新学到的约定写回 spec。
  • trellis-session-insight：从历史会话里找上下文。
  • trellis-spec-bootstrap：初始化或刷新项目规范。

这类技能本质上是“可复用的工作流提示词 + 约束”。它们把 Agent 在某个阶段应该做的事写得很具体。

4. OpenCode agents

.opencode/agents/ 下定义了 trellis-implement、trellis-check、trellis-research。它们是 OpenCode 的子代理配置。

其中 implement/check 代理都明确禁止执行：

text
git commit
git push
git merge

也就是说，子代理可以实现、检查、甚至修小问题，但提交权仍然留在主会话。这能减少多代理同时操作 git 带来的混乱。

这套机制如何改变 Agent 的行为

没有 Trellis 时，我通常会直接对 Agent 说“帮我改一下”，然后 Agent 开始读文件、改代码、跑验证。这个过程能工作，但长任务里容易出现几个问题：

  • 需求没有沉淀，后面忘记最初目标。
  • 实现前没明确验收标准。
  • 检查时不知道该对照哪些规范。
  • 多个子代理不知道当前任务边界。
  • 会话结束后没有结构化记录。

Trellis 的改法是把这些步骤显性化：

  • 没有任务时，先判断是否需要创建 Trellis task。
  • 复杂任务必须先写 prd.md、design.md、implement.md。
  • 只有任务进入 in_progress 后才执行。
  • 写代码前加载相关 spec。
  • 修改后做 check。
  • 学到新约定后更新 spec。
  • 收尾时归档任务并记录 session。

这会让简单任务显得更“重”，但对中大型改动或多人/多 Agent 协作很有价值。

我的结论

这次安装后，我对 Trellis 的理解是：它不是另一个代码生成器，而是一套把 AI 编程流程项目化的约束系统。

它真正新增的能力主要有四类：

  • 任务结构化：把需求、设计、执行计划和检查上下文落到 .trellis/tasks/。
  • 规范注入：把 .trellis/spec/ 里的规则按阶段注入给 Agent。
  • 状态提醒：通过 SessionStart 和每轮 workflow-state 防止上下文漂移。
  • 子代理协作：让 implement、check、research 代理在同一个任务边界下工作。

但它也不是装完就万事大吉。至少在 Visionary 这个项目里，我后续还会做两件事：

  • 校准 spec：把模板里的通用 Next.js 约定改成真正符合 Visionary 技术栈的项目规范。
  • 控制使用场景：小改动不一定值得完整走一遍复杂流程，但跨文件、跨层、需要验证的任务很适合交给 Trellis 管理。

如果你经常让 Code Agent 做复杂改动，Trellis 的价值不是“让 Agent 更聪明”，而是“让 Agent 更守纪律”。这可能比单纯换一个更强的模型更重要。

评论
0/100