一套是我自己在做的 Zenith 组件迁移 workflow。这个 workflow 里面有很多 subagent，每个 agent 通常会调用一两个 skill 去完成自己的局部工作。另一套是比较出名的 Trellis。它的 coding workflow 明显更完整，除了 agent 和 skill，还有很多专业的脚本、插件、hooks、任务状态、上下文注入、检查和沉淀机制。

Trellis 很有启发，但我不敢直接把它那套 workflow 放进当前做 Zenith 组件迁移的项目里。不是因为它不好，而是因为它太完整了。一旦放进去，两套 workflow 的 agents、skills、hooks、commands、plugins 和运行产物很容易挤在一起，项目会变得非常乱。

这让我开始意识到一个问题：现在很多 agent 生态已经有了 skills、agents、commands、hooks、plugins、knowledge，但这些仍然更像一堆能力零件。真正复杂的工作不是调用某个 skill，而是执行一条 workflow。

所以我现在更倾向于一个判断：agent 平台不应该只提供 skills，也应该把 workflow 作为一等抽象。

两套 workflow 都有价值，但直接混放会乱​

Zenith 组件迁移 workflow 和 Trellis coding workflow 解决的是不同问题。

组件迁移更关心：

• 旧组件能力怎么识别；
• 新组件能力怎么对齐；
• 参数和事件怎么映射；
• 样式、交互、业务语义怎么校验；
• 迁移过程中的截图、对比、失败原因怎么留证据。

Trellis coding workflow 更关心：

• 需求怎么写成 PRD；
• 任务状态怎么从 planning 进入 in progress；
• implement / check / update spec 怎么形成闭环；
• 上下文怎么注入给 agent；
• 代码修改后如何验证、提交和归档。

它们都很有价值，但它们不应该被简单倒进同一个 .opencode/agents、.opencode/skills、.opencode/hooks 或 .opencode/commands 里。

因为当一个 workflow 同时包含 agents、skills、hooks、commands、plugins、knowledge 和运行产物时，它就不再是几个配置文件，而是一套工作系统。如果不同工作系统的零件都散放在同一个目录层级里，用户很快就会失去边界感：这个 agent 属于哪个 workflow？这个 skill 是通用的，还是只服务某个迁移流程？这个 hook 会不会影响别的任务？这个运行产物能不能删？

这不是洁癖问题，而是可维护性问题。

skills 解决不了 workflow 的组织问题​

现在很多 agent 平台已经支持 skills。skill 很适合表达“某个能力怎么做”，比如读文档、查表格、处理 Figma、发消息、搜索代码、生成图片。

但 workflow 不是 skill 的集合那么简单。

一个组件迁移 workflow 不是“调用组件迁移 skill”就结束了。它至少需要经历这样的过程：

识别迁移对象
  -> 调研旧组件
  -> 调研新组件
  -> 建立参数映射
  -> 拆分实现任务
  -> 调用不同 subagent
  -> 记录中间结论
  -> 做结构、行为、视觉、语义校验
  -> 保存证据
  -> 把失败经验沉淀回流程

这条链路里确实会用到 skills，但 skill 只是能力单元。真正需要被表达的是：这些能力应该按什么顺序使用、每一步需要什么输入、产出放在哪里、失败时怎么处理、最后如何检查和沉淀。

也就是说，skill 解决的是“我会什么”，workflow 解决的是“我如何稳定完成一类任务”。

如果只有 skills，没有 workflow，系统会越来越像一个能力抽屉：里面东西很多，但用户每次都要重新组织一次流程。

workflow 应该是聚合层，而不是能力层​

我现在更倾向于把这些概念拆开看：

• skill：一个可复用能力，例如查资料、读设计稿、发消息、跑检查。
• agent：一个执行角色，例如迁移分析 agent、实现 agent、review agent。
• command：一个明确入口，例如启动迁移、启动检查、生成报告。
• hook：生命周期中的自动动作，例如会话开始时注入上下文，任务结束时归档产物。
• plugin：平台扩展机制，例如接入浏览器、文件系统、远端服务。
• knowledge：背景知识、项目规范、组件约定、历史经验。
• workflow：把上面这些组织起来的一条可执行流程。
• run / state：一次执行过程中产生的中间产物和运行状态。

这样看，workflow 的职责不是替代 skill，而是编排 skill。它应该描述一类任务的完整工作方式，而不是某个局部能力的调用说明。

一个比较理想的 workflow package 里，至少应该能回答这些问题：

• 这个 workflow 解决什么问题；
• 它有哪些阶段；
• 每个阶段需要什么输入；
• 每个阶段会产生什么输出；
• 哪些 agents 会参与；
• 依赖哪些 shared skills；
• 有哪些 workflow-local skills；
• 哪些 plugins / hooks / commands 可用；
• 需要读取哪些 knowledge；
• 中间产物放在哪里；
• 如何判断这次运行完成；
• 如何把经验沉淀回可复用知识。

这才是 workflow 作为一等抽象的意义。

公共 skill 应该被引用，而不是复制​

这里还有一个容易混淆的点：如果 workflow 有自己的边界，那公共 skill 怎么办？

我不觉得每个 workflow 都应该复制一份 skill。像读文档、查代码、处理 Figma、生成截图、发消息这类能力，本来就应该是公共的。如果每个 workflow 都内置一份，很快会变成重复维护，也会让 skill 的版本和行为变得不可控。

更合理的方式是：workflow 拥有自己的边界，但公共 skill 通过依赖声明被引用进来。

也就是说，一个 workflow package 里可以有自己的 local skills，用来表达这个流程特有的能力；同时它也可以声明自己依赖哪些 shared skills：

name: zenith-component-migration

skills:
  shared:
    - code-search
    - figma-reader
    - screenshot-compare

  local:
    - component-prop-mapper
    - migration-report-writer

这样 workflow 不需要复制公共能力，但也不会默认看到所有能力。它能用什么，应该是显式声明出来的。

这点很重要。因为如果所有 workflow 都能隐式访问所有 skills，系统还是会退回到“能力抽屉”的状态：东西很多，但边界不清楚。用户不知道某个 skill 是这个 workflow 真正需要的，还是刚好在全局目录里被匹配到了。

所以我更倾向于让 workflow 像 package 一样声明依赖。公共 skill 可以放在项目级、用户级，甚至远端 registry 里；workflow 启动时只解析自己声明过的那一组能力。

一个比较清楚的解析顺序可能是：

workflow local skill
  -> project shared skill
  -> user/global shared skill
  -> remote registry skill

这样既能共享，也能隔离。workflow-local skill 可以覆盖公共 skill，但这个覆盖只影响当前 workflow，不会污染其他流程。

这也说明 workflow 自己同样需要配置。

skill 的配置回答的是：这个能力怎么调用、需要什么输入、有什么权限、产物放在哪里。workflow 的配置回答的是：这条流程怎么启动、能用哪些能力、分几个阶段、运行产物放在哪里、失败后怎么恢复。

换句话说：

skill config = 能力配置
workflow config = 流程配置

如果 workflow 没有 manifest，它就很容易退化成一段 prompt 或一组松散目录。只有当 workflow 能明确声明自己的入口、依赖、阶段、产物和权限时，它才真的像一个可以复用、可以 review、可以迁移的 package。

目录不应该只是统一，而应该分层​

一开始我会很自然地想：既然 OpenCode 负责 agent，那是不是所有东西都应该塞进 .opencode？

但后来我觉得这个目标应该稍微改一下。

更合理的目标不是“全部塞进一个目录”，而是：一个入口目录，配置与产物分层。

比如可以想象成这样：

.opencode/
  skills/
    code-search/
    figma-reader/
    screenshot-compare/

  workflows/
    zenith-component-migration/
      manifest.yaml
      agents/
      skills/
        component-prop-mapper/
        migration-report-writer/
      commands/
      hooks/
      plugins/
      knowledge/
      lib/

    trellis-coding/
      manifest.yaml
      agents/
      skills/
        spec-writer/
        task-state-updater/
      commands/
      hooks/
      plugins/
      knowledge/
      lib/

  state/
    <run_id>/
      logs/
      artifacts/
      evidence/
      cache/
      results/

这里的关键不是一定要叫 .opencode/workflows 或 .opencode/state，而是要区分两类东西。

.opencode/skills 可以放项目级共享能力，workflows/<name>/skills 则放当前 workflow 的私有能力。前者可以被多个 workflow 显式引用，后者只服务当前 workflow。

第一类是可复用的工作包，也就是 workflow package。它应该适合版本化，适合 review，适合被复制到另一个项目里。agents、skills、commands、hooks、plugins、knowledge、manifest、lib 都属于这一类。

第二类是一次执行产生的运行产物，也就是 workflow run。它可能很大，会频繁变化，还可能包含敏感内容。日志、缓存、下载的依赖、截图、评测结果、临时文件、失败记录都属于这一类。

这也是为什么 .trellis 这类并列产物目录会存在。它不是没有道理。运行产物如果和配置混在一起，git 状态会很吵，清理也麻烦，多人协作时更容易误提交。

所以问题不是“为什么有 .trellis”，而是用户需要一个更清晰的心智模型：哪些是可复用 workflow package，哪些是一次性 workflow run。

配置应该可版本化，产物应该可清理。这两个边界如果不清楚，workflow 越强，项目越乱。

workflow 不应该靠模糊匹配启动​

还有一个问题是启动方式。

skill 可以靠模糊匹配触发。用户说“帮我查一下会议纪要”，系统判断需要调用某个 skill，这可以接受。因为 skill 是局部能力，即使匹配错了，影响范围通常也比较小。

但 workflow 不一样。

workflow 一旦启动，意味着 agent 要进入一套比较长的状态机：创建任务、读取规范、调用 subagent、生成中间产物、执行检查、更新沉淀。如果它像 skill 一样靠模糊匹配启动，用户很难知道自己到底进入了哪条流程，也很难判断什么时候应该退出、暂停、恢复或清理。

所以 workflow 更适合用硬命令启动，例如：

/workflow zenith-component-migration
/workflow trellis-coding
/workflow blog-writing

或者更短一些：

+run zenith-component-migration
+run trellis-coding
+run blog-writing

命令形式不重要，重要的是 workflow 应该有明确入口。用户真正需要记住的，不应该是哪些 agent、skill、hook 分别放在哪里，而是：我要运行哪个 workflow。

一旦 workflow 被显式启动，系统就可以明确告诉用户：

• 当前使用的是哪个 workflow；
• 当前处在哪个 phase；
• 本次 run 的产物目录在哪里；
• 哪些 agents / skills / hooks / plugins 会参与；
• 当前缺哪些输入；
• 下一步会做什么；
• 如何暂停、恢复或结束。

这比“AI 猜测用户想调用哪个 skill”稳定得多。

中间产物也需要自己的位置​

很多 agent 系统最大的问题是：过程发生在聊天里，结果也留在聊天里。

这对简单问题没关系，但对 workflow 来说很危险。

一次组件迁移过程中会产生很多东西：

• 迁移对象列表；
• 旧组件能力分析；
• 新组件能力分析；
• 参数映射表；
• 不兼容点；
• 截图证据；
• 校验结果；
• 失败原因；
• 后续修正建议。

一次 coding workflow 也会产生很多东西：

• PRD；
• 技术设计；
• research；
• 任务状态；
• check result；
• spec 更新建议；
• commit 前验证记录。

就连写博客这种看起来很轻的任务，也会产生内容类型、来源模式、写作风格、追问答案、文章骨架、草稿、构建结果。

这些内容不能只散在聊天记录里。它们应该有明确的 artifact location。

否则下一次继续任务时，agent 只能重新从聊天历史里猜；换一个 agent 时，上下文更容易丢；多人协作时，别人也不知道哪些结论是过程产物，哪些结论已经沉淀成规范。

workflow 如果要可靠，就必须认真对待中间产物。它们不是噪音，而是流程能被恢复、检查、复盘和改进的证据。

几个 workflow 的共同结构​

Zenith 组件迁移、Trellis coding workflow、博客写作 workflow 看起来是完全不同的事情，但它们有很相似的结构。

Zenith 组件迁移需要多个 subagent 协作。有人负责读旧组件，有人负责找新组件能力，有人负责参数映射，有人负责视觉和行为校验。这里的重点不是某一个 skill，而是迁移流程本身。

Trellis coding workflow 更接近一个成熟 harness。它有任务状态，有脚本，有 hooks，有上下文注入，有检查和沉淀。它证明了 workflow 可以比简单 agent prompt 更稳定。

博客写作 workflow 看起来轻量，但也有流程：确认内容类型、确认来源模式、确认风格、追问关键问题、生成结构、写正文、构建验证。它说明 workflow 不只属于 coding，也适合知识工作。

这些例子共同说明一件事：复杂任务需要的不是更多零散能力，而是一套能组织能力、状态和产物的 workflow 层。

如果推动到上游，应该最小化迁移​

如果要把这个想法推动到 OpenCode 或 Trellis 上游，我不觉得应该一上来就要求重构所有目录。

更现实的路径可能是三步。

第一步，只做路径解析和兼容。

支持从 .opencode/workflows/<name>/ 读取一个 workflow package，但保留现有目录结构。旧的 .trellis 仍然能用，已有项目不需要迁移，也不会被破坏。

第二步，提供可配置的产物根目录。

默认仍然可以使用 .trellis 或原来的目录，但允许用户切换到 .opencode/state/。这样不会破坏已有用户的清理脚本、ignore 规则和协作习惯。

第三步，补一个最小示例 workflow 和文档。

让用户能看到：只要一个目录名或一个 command，就能启动完整 workflow。维护者也更容易理解这个抽象的价值，因为它不再只是目录规范，而是一个可运行的用户体验。

这个迁移路径的重点是“最小可合并”。先让 workflow package 这个概念出现，再逐步让配置、产物、命令入口和文档形成闭环。

Agent 需要 workflow 层​

我现在越来越觉得，agent 平台下一步要补的不是更多零散 skills，而是 workflow 这一层。

skills 解决的是“我会什么”。workflow 解决的是“我如何稳定完成一类任务”。

如果 workflow 没有自己的命名空间、启动入口和产物边界，那么能力越多，项目越乱。反过来，如果 workflow 可以被打包、显式启动、隔离运行、沉淀产物，那么 agent 才真正从“能调用工具”走向“能执行流程”。

这也是我为什么不敢直接把 Trellis workflow 放进 Zenith 项目的原因。

我不是不想复用它，而是希望复用的是一个清晰的 workflow package，而不是把另一套工作流的 agents、skills、hooks、commands 和运行产物一起倒进当前项目。

它听起来像是在讨论社会制度、教育筛选和精英叙事，但落到日常里，常常只是一些很小的瞬间：一句阴阳怪气的话，一个听说别人没拿奖学金后的眼神，或者看到同学多做成一点事后，心里冒出来的酸意。

比较本身不一定有问题。真正麻烦的是，比较会慢慢变成价值判断：别人做得好，就像更配；自己暂时没做到，就像低人一等。于是人与人之间很容易从互相参照，滑向互相审判。

我以前也会这样想​

我之前也有过类似的心态。

本科的时候，我也会不自觉地陷进那种优绩主义思维里。看到别人比自己强，心里会酸，会给自己找一些解释：他是不是更会投机取巧，他是不是刚好运气好，他是不是只是更会包装。

等到自己某些方面比别人好一点，又会很容易产生一种隐秘的优越感，好像自己终于站到了一个可以评价别人的位置上。

现在回头看，这种心态其实挺累的。

它表面上是在追求进步，实际上是在不断把自己和别人绑在同一张排名表上。别人前进一步，自己就像被挤下去一点；自己好不容易前进一步，又忍不住回头看有没有人落在后面。

久而久之，努力不再是为了把事情做好，而是为了证明“我比谁更值得”。

我后来也遇到过一些很具体的场景。比如之前我没有拿到奖学金，跟我一起健身的朋友听到以后，态度里似乎闪过了一点不屑。当然这也可能只是我的猜测，不一定真是他这样想。但那一瞬间我确实能感觉到，某个外部结果很容易被拿来判断一个人。

这也是优绩主义最隐蔽的地方。它不一定非要有人直接说“你不行”。有时候一个眼神、一句玩笑、一个语气，就足够让人感受到那张看不见的排名表。

排名别人之前，也要准备好被别人排名​

最近网上还流行一种玩法，叫“从夯到拉”排名。

这种东西当然可以说只是玩梗。人喜欢分类，喜欢排序，喜欢给事物打标签，这本身也很正常。问题是，当这种排名习惯从娱乐蔓延到人身上，它就会变得很微妙。

你今天把别人放进一个排名里，明天也要接受别人把你放进另一个排名里。

所以我会觉得，给别人排名这件事，本质上要做好被别人排名的准备。你用某个标准衡量别人，别人也可以用另一个标准衡量你。你觉得别人“拉”，别人也可能觉得你在别的地方不行。

这算不算优绩主义的一种？我觉得不一定完全等同，但它们背后有相似的冲动：先假设人可以被放进一套等级里，再用某个指标决定谁更高级，谁更低级。

优绩主义更强调“成绩”“能力”“努力之后的结果”；网络排名可能更轻浮，也更随意。但它们最后都很容易走向同一个方向：把复杂的人压扁成一个位置。

一个人不再是一个具体的人，而是榜单上的一个名次，是某个圈层里的一个等级，是可以被比较、被嘲笑、被归类的对象。

这种思维一旦变成习惯，人和人的关系就会越来越紧绷。因为你永远不知道自己什么时候会被放到别人的尺子下面。

鄙视链也是一种日常化的排名​

工作以后，这种东西也没有消失，只是换了形式。

比如我现在做前端。前端在很多研发鄙视链里，经常被放在比较靠下的位置。有人会觉得前端只是切图、调样式，不够“底层”，也不够“硬核”。

这个和优绩主义有没有关系？我觉得有关系，但不是简单的一一对应。

岗位鄙视链不只是优绩主义，它还混着技术崇拜、行业偏见、话语权分配，以及很多人对“难度”的想象。可是它确实借用了优绩主义的那套逻辑：谁更难，谁更核心，谁更接近系统底层，谁就更值得被尊重。

问题是，真实的软件工作没有这么简单。

前端当然有简单的部分，后端、算法、基础架构也都有重复、琐碎、工程化的一面。一个岗位是不是有价值，不应该只看它在鄙视链上的位置，而要看它解决了什么问题、承担了什么复杂度、服务了什么人。

但鄙视链很方便。它不需要理解别人的工作，只需要给对方贴一个位置。

学历鄙视圈也是一样。

最经典的一句话就是：“自我以上众生平等，自我以下等级森严。”这句话好笑，是因为它太真实了。很多人不是反对等级，只是反对自己被放在等级下面。只要自己刚好站在一个还不错的位置，就很容易开始维护那套等级。

学校、学历、岗位、收入、城市、公司、title，这些东西都可以变成新的尺子。尺子越多，人就越容易在某一把尺子上找到一点优越感，也越容易在另一把尺子上感到羞耻。

这可能就是我现在越来越警惕的地方。

如果一个人总要靠把别人排低一点来确认自己，那他其实也很难真正自由。因为他相信这套排名，所以他也必须永远活在这套排名里。

同路人没有必要互相拖下水​

很多时候，大家本来就是同学一场，或者朋友一场。说得直接一点，很多人本来就是同一个阶层、同一种处境里的人。

大家面对的压力其实很相似：学业、就业、家庭期待、未来的不确定性，还有那种“不知道自己够不够好”的焦虑。

在这种情况下，如果还要互相讥讽，互相踩一脚，其实很不划算。

你拿了奖学金，当然值得高兴。别人没拿，也不代表他这个人就低一等。你找到一个好机会，当然可以分享。别人暂时没有，也不需要立刻被放到某个失败者的位置上。

一个人做成了一件事，不管大小，对他自己来说都可能是一次进步。我们当然可以比较，但比较最好是为了互相激励，而不是为了互相拖下水。

我现在越来越觉得，人和人之间最珍贵的东西，不是永远在同一个水平线上，也不是假装大家没有差距。

差距当然存在。能力有差距，资源有差距，选择有差距，运气也有差距。真正重要的是，我们怎么看待这些差距。

如果看到别人往前走，第一反应是贬低他，那我们其实是在用别人的进步惩罚自己。如果看到别人暂时失意，第一反应是轻视他，那我们也只是在提前训练自己接受一个更冷酷的世界：只要你不够成功，你就不值得被好好对待。

但人不应该只在成功的时候才被尊重。

有些时候，帮不上忙也没关系。互相安慰一下，聊聊天，帮对方消化一点情绪，也是一种很具体的支持。不是每段关系都要提供资源，不是每次交流都要产生收益。

很多时候，能让一个人觉得“我不是一个人在扛”，就已经很重要了。

放低姿态不是认输​

现在和别人相处时，我更倾向于放低一点姿态。

这不是说真的觉得自己低人一等，也不是故意装傻、讨好别人。更准确地说，是我不太想在日常关系里持续释放竞争信号。

因为我发现，很多关系一旦进入“谁更强”的语境，就很难再轻松聊天了。你说自己做成了什么，别人可能听成炫耀；别人说自己做成了什么，你也可能不自觉地开始比较。最后大家都很累。

放低姿态有时候是一种降噪。

它不是否认自己的努力，也不是放弃争取更好的结果，而是尽量不把每一次交流都变成隐形的面试、答辩和排名。

我可以承认自己有不会的地方，可以承认自己没拿到某些东西，可以承认自己也会羡慕、会焦虑、会不确定。这样反而更容易和别人建立真实一点的关系。

当然，这不意味着要纵容别人轻视自己。放低姿态不是给别人踩自己的许可。如果对方真的只想通过贬低别人获得优越感，那保持距离也很正常。

只是对我来说，我不想再那么积极地参与那套排名游戏了。

优绩主义的问题，不是它让人想变好。

想变好没有错，努力也没有错，争取更好的结果更没有错。问题在于，当“成绩”“奖项”“机会”“排名”变成衡量人的唯一尺度时，我们就会忘记：一个人除了这些外部结果之外，还有很多东西值得被看见。

他的挣扎值得被看见，他的迟疑值得被看见，他的小进步值得被看见，他没有说出口的压力也值得被看见。

所以我现在更愿意提醒自己：不要急着把别人放进高低排序里。

别人做成了一点事，可以祝贺。自己暂时没做到，可以承认失落，但不必立刻把失落转化成酸意。别人遇到困难，如果能帮就帮一下，帮不了就陪他说说话。

人与人之间不一定总要互相成就什么宏大的东西，至少不要轻易互相消耗。

说到底，我们很多人其实都在同一条路上。

路已经够难走了，没必要一边走，一边还要把身边的人推下去。

这篇文章面向想研究本项目 Trellis harness 的开发者。目标不是列一份冷冰冰的文件清单，而是给你一条可执行的学习路线：先读什么、再看什么、哪些命令值得亲手跑一遍，以及如何建立一套稳定的心智模型。

先建立心智模型：Trellis 到底在协调什么？​

理解 Trellis harness 的关键，是先把它看成一条上下文驱动的工作流链路：

user input
  -> SessionStart / workflow-state injection
  -> AI reads current status
  -> no_task / planning / in_progress / completed
  -> .trellis/workflow.md determines next step
  -> task.py manages task lifecycle
  -> JSONL controls sub-agent preloaded context
  -> implement / check / update-spec / finish-work completes the loop

换句话说，Trellis 并不是只靠 AI “记住流程”。它把流程写进文件，把状态落到任务目录，把上下文通过 hook 或 adapter 注入给 AI，再用脚本维护生命周期。

你可以把它想象成几层：

1. 用户输入触发一次会话轮次。
2. SessionStart / workflow-state 注入告诉 AI 当前任务状态和下一步该做什么。
3. .trellis/workflow.md 是总流程说明书。
4. .trellis/tasks/ 保存每个任务的 PRD、状态、上下文 JSONL。
5. .trellis/scripts/task.py 负责创建、激活、校验、查询任务。
6. .trellis/scripts/get_context.py 负责按 phase、package、spec 等维度取上下文。
7. implement.jsonl / check.jsonl 决定 implement/check sub-agent 预加载哪些 spec 和 research。
8. .trellis/spec/ 保存项目约定，避免 AI 凭空发挥。
9. .trellis/workspace/ 保存开发者工作记忆和 journal。
10. .opencode/ 把这一套接到 OpenCode 平台。
11. trellis-meta 用来研究和修改 Trellis harness 自身。

先记住这条链路，后面看文件时就不会迷路。

推荐学习顺序​

1. 从 .trellis/workflow.md 开始：先看“流程宪法”​

第一站一定是：

.trellis/workflow.md

这个文件定义了 Trellis 的三大阶段：

• Phase 1: Plan：创建任务、澄清需求、研究、整理上下文、启动任务。
• Phase 2: Execute：实现和质量检查。
• Phase 3: Finish：最终验证、更新 spec、提交、归档收尾。

阅读时重点关注这些内容：

• no_task、planning、in_progress、completed 这些 status 分别意味着什么。
• 每个 phase 里哪些步骤是 [required]，哪些是 [once]。
• workflow-state block 如何把“当前状态下 AI 应该做什么”写成可注入提示词。
• 为什么在 in_progress 状态下默认要走 trellis-implement、trellis-check、trellis-update-spec。

如果只读一个文件来理解 Trellis 的行为，那就是它。

2. 看 .trellis/tasks/：理解任务如何落地​

第二站是任务目录：

.trellis/tasks/

每个任务通常是一个独立目录，里面会出现这些文件：

prd.md
info.md
implement.jsonl
check.jsonl
task.json
research/

它们的分工大致如下：

• prd.md：需求文档，告诉 agent 要做什么。
• info.md：技术设计，可选；复杂任务会更有用。
• implement.jsonl：implement sub-agent 需要预加载的 spec / research。
• check.jsonl：check sub-agent 需要预加载的 spec / research。
• task.json：任务元信息和状态。
• research/：研究产物，尤其适合第三方 API、架构方案、技术比较。

这里最重要的认识是：Trellis 不把需求只留在聊天里，而是要求写进任务文件。 聊天会被压缩、遗忘或跨会话丢失，但任务目录会保留下来。

3. 研究 task.py：任务生命周期的控制台​

接下来可以看脚本：

.trellis/scripts/task.py

它是任务生命周期的主要入口。你不需要一开始读完全部实现，可以先从命令行为反推它的职责。

创建一个探索任务：

python3 ./.trellis/scripts/task.py create "Explore Trellis harness" --slug explore-trellis-harness

查看当前任务和来源：

python3 ./.trellis/scripts/task.py current --source

给 implement agent 增加上下文：

python3 ./.trellis/scripts/task.py add-context <task> implement ".trellis/spec/backend/index.md" "Backend conventions"

校验任务目录：

python3 ./.trellis/scripts/task.py validate <task>

启动任务，进入 in_progress：

python3 ./.trellis/scripts/task.py start <task>

这些命令对应的是 Trellis 的基本生命周期：

create -> planning -> add context / validate -> start -> in_progress -> finish/archive

学习时建议你边看 .trellis/workflow.md，边对照 task.py 里的 command handler。这样你会更清楚：workflow 里的规则不是抽象说明，而是由脚本和 hook 共同执行的。

4. 理解 active task / session state：AI 为什么知道“现在该做什么”​

Trellis 的一个关键能力是：新开会话或继续会话时，AI 会收到当前任务状态、开发者身份、git 状态、active tasks、spec 索引等信息。

这类信息通常来自 SessionStart 注入和运行时状态解析。你可以通过命令观察当前任务来源：

python3 ./.trellis/scripts/task.py current --source

这里值得关注两个问题：

1. 当前 session 指向哪个 active task？
2. 如果没有 active task，workflow-state 为什么会变成 no_task？

当状态是 no_task 时，AI 应该直接回答简单问题；一旦用户请求实现、重构、构建或修改代码，就应该创建任务并进入 Plan。状态是 planning 时，AI 应该写 PRD、整理 JSONL、再 start。状态是 in_progress 时，AI 应该走 implement/check/update-spec/commit/finish 的闭环。

这就是 workflow-state 的意义：它把“下一步该做什么”从主观判断变成状态机驱动。

5. 看 get_context.py：上下文是如何按需取出的​

然后阅读：

.trellis/scripts/get_context.py

这个脚本负责把 workflow、phase、package、spec 等信息按不同模式取出来。

常用命令包括：

python3 ./.trellis/scripts/get_context.py

列出 package 和 spec layer：

python3 ./.trellis/scripts/get_context.py --mode packages

查看某个 phase step 的详细说明：

python3 ./.trellis/scripts/get_context.py --mode phase --step 1.3

如果说 task.py 管的是“任务状态”，那么 get_context.py 管的就是“该给 AI 哪些说明”。这也是 Trellis 能跨会话保持一致行为的重要原因。

6. 研究 workflow-state injection：提示词不是凭空出现的​

当你看到会话开头出现类似当前状态、任务路径、workflow-state 的内容时，不要把它当成普通日志。它是 Trellis harness 的核心机制之一。

重点阅读路径：

.trellis/workflow.md
.trellis/scripts/get_context.py
.opencode/plugins/
.opencode/commands/trellis/

其中：

• .trellis/workflow.md 写了每个 [workflow-state:...] block 的正文。
• .trellis/scripts/get_context.py 可以按 phase、package 等模式取出 workflow 和 spec 上下文。
• .opencode/plugins/ 与 .opencode/commands/trellis/ 是 OpenCode 侧把这些上下文接入会话、命令和 agent 行为的适配入口。
• 如果你的 fork 里新增了专门的 workflow-state 注入脚本或契约文档，也应把它和 .trellis/workflow.md 一起阅读，确认 status writer、hook 可达性和测试不变量一致。

建议你重点看 no_task、planning、in_progress 的差异。因为绝大多数日常开发都会在这三个状态之间流转。

7. 理解 sub-agent context injection：为什么有 implement.jsonl 和 check.jsonl​

在 agent-capable 平台上，Trellis 通常不希望主会话直接写代码，而是派发：

• trellis-implement
• trellis-check
• trellis-update-spec

这时，sub-agent 需要知道哪些 spec、research、任务文档必须提前阅读。答案就在任务目录下的 JSONL 文件：

implement.jsonl
check.jsonl

每行是一个 JSON object，例如：

{"file":".trellis/spec/backend/index.md","reason":"Backend conventions"}

也可以用命令追加：

python3 ./.trellis/scripts/task.py add-context <task> implement ".trellis/spec/backend/index.md" "Backend conventions"

这个设计解决了一个很实际的问题：主会话知道的上下文，sub-agent 未必知道。JSONL 就像交接清单，保证 implement/check agent 启动时能获得正确资料。

8. 看 .trellis/spec/：项目约定的长期记忆​

接下来阅读：

.trellis/spec/

它保存项目级开发规范。典型结构可能包括：

.trellis/spec/backend/index.md
.trellis/spec/frontend/index.md
.trellis/spec/guides/

学习时先看 index，再按 index 的 Pre-Development Checklist 继续读具体指南。

你要特别关注这些问题：

• 哪些目录结构是约定好的？
• 错误处理、日志、质量规则有什么禁用模式？
• 是否有跨层思考指南，例如数据从 backend 到 frontend 如何流动？
• 是否有代码复用指南，提醒改常量或新增 helper 前先搜索？

Trellis 的重要习惯是：一次任务中学到的可复用经验，应通过 trellis-update-spec 沉淀回 .trellis/spec/。 这样下一次 agent 才能继承经验，而不是每轮重新踩坑。

9. 看 .trellis/workspace/：开发者自己的工作记忆​

然后看：

.trellis/workspace/

这里通常按开发者保存 journal、session trace 或其他工作记忆。例如：

.trellis/workspace/<developer>/journal-1.md

如果 .trellis/tasks/ 是“任务记忆”，那么 .trellis/workspace/ 更像“开发者记忆”。它能记录会话、收尾、归档等过程中的信息。

这部分不一定是你理解执行链路的第一优先级，但当你研究 /finish-work、归档、journal 更新时，它会变得很重要。

10. 研究 .opencode/：OpenCode 平台适配层​

如果你在 OpenCode 环境里使用 Trellis，就需要看：

.opencode/

推荐阅读路径：

.opencode/agents/
.opencode/commands/
.opencode/skills/
.opencode/skills/trellis-meta/

不同项目结构可能略有差异，但学习目标是一致的：搞清楚 Trellis workflow 如何被接入平台能力。

重点关注：

• trellis-implement agent 如何被定义。
• trellis-check agent 如何被定义。
• /trellis:finish-work 这类命令如何映射到脚本。
• skills 如何把 workflow、spec、task context 注入到 agent 行为中。

你可以把 .opencode/ 理解成“平台适配器”：Trellis 的核心状态和规则在 .trellis/，而 OpenCode 需要通过 adapter 把这些规则接入具体的 agent、command、hook、skill。

11. 最后用 trellis-meta 研究和定制 Trellis 本身​

当你不只是使用 Trellis，而是想修改 Trellis harness 本身时，再进入 trellis-meta。

相关入口通常在：

.opencode/skills/trellis-meta/

trellis-meta 的定位是帮助你理解和定制本地 Trellis 架构，包括：

• .trellis/ 工作流文件。
• platform hooks。
• settings。
• agents。
• skills。
• commands。
• prompts。
• workflow 自定义。

一个实用建议是：在你还没理解 .trellis/workflow.md、task.py、get_context.py、workflow-state injection 之前，不要急着改 trellis-meta 相关内容。否则很容易只改了提示词，却没同步状态机契约或脚本行为。

一条实用的文件阅读路线​

如果你想系统阅读，可以按下面这条路线走。

总体工作流​

.trellis/workflow.md
.trellis/scripts/task.py
.trellis/scripts/get_context.py
.opencode/plugins/
.opencode/commands/trellis/

这条线帮你理解：状态如何流转、上下文如何生成、AI 为什么收到那些指令。

任务实现细节​

.trellis/tasks/<task>/prd.md
.trellis/tasks/<task>/info.md
.trellis/tasks/<task>/implement.jsonl
.trellis/tasks/<task>/check.jsonl
.trellis/tasks/<task>/task.json

这条线帮你理解：一个具体任务如何从需求变成实现上下文。

OpenCode 适配​

.opencode/agents/
.opencode/commands/
.opencode/skills/

这条线帮你理解：Trellis 如何接入 OpenCode 的 agent、command、skill 体系。

项目规范和长期记忆​

.trellis/spec/
.trellis/workspace/

这条线帮你理解：项目约定和开发者记忆如何沉淀下来。

自定义 Trellis​

.opencode/skills/trellis-meta/
.trellis/workflow.md
.trellis/scripts/task.py
.trellis/scripts/get_context.py

这条线帮你理解：如果要改 harness，应遵循哪些契约。

一条 hands-on 探索路线​

只读文件不如亲手跑一遍。你可以在一个安全分支上尝试下面的探索路径。

第一步，创建一个实验任务：

python3 ./.trellis/scripts/task.py create "Explore Trellis harness" --slug explore-trellis-harness

第二步，查看当前任务来源：

python3 ./.trellis/scripts/task.py current --source

第三步，查看 package/spec 信息：

python3 ./.trellis/scripts/get_context.py --mode packages

第四步，研究 Phase 1.3 为什么要求整理 JSONL：

python3 ./.trellis/scripts/get_context.py --mode phase --step 1.3

第五步，给 implement 上下文追加一个 spec：

python3 ./.trellis/scripts/task.py add-context <task> implement ".trellis/spec/backend/index.md" "Backend conventions"

第六步，校验任务：

python3 ./.trellis/scripts/task.py validate <task>

第七步，启动任务：

python3 ./.trellis/scripts/task.py start <task>

第八步，再查看一次当前上下文：

python3 ./.trellis/scripts/get_context.py

跑完这条路径，你会对 planning 到 in_progress 的切换、JSONL 的作用、spec 注入的意义有直观感受。

常见误区​

误区一：把 Trellis 当成普通文档目录​

.trellis/ 不是只有文档。它包含 workflow、状态、脚本、spec、workspace memory。文档和脚本共同构成 harness。

误区二：认为 AI 会自动记住所有上下文​

不会。Trellis 之所以要求 prd.md、implement.jsonl、check.jsonl，就是因为不同 session 和 sub-agent 之间不能依赖隐式记忆。

误区三：只改 workflow 文本，不考虑状态契约​

如果你修改了 .trellis/workflow.md 中的 required step 或 workflow-state block，需要确认脚本、hook 和 spec 契约是否仍一致。尤其要参考：

.trellis/scripts/task.py
.trellis/scripts/get_context.py
.opencode/plugins/
.opencode/commands/trellis/

误区四：跳过 trellis-update-spec​

如果一次任务产生了可复用经验，却没有沉淀到 .trellis/spec/，下一次 agent 很可能还会重复犯错。trellis-update-spec 是 Trellis 闭环的一部分，不只是文档洁癖。

总结：用状态机理解 Trellis，用文件系统验证 Trellis​

学习 Trellis harness 最有效的方法，是同时抓住两件事：

第一，用状态机理解它：

no_task -> planning -> in_progress -> completed

第二，用文件系统验证它：

.trellis/workflow.md
.trellis/tasks/
.trellis/scripts/
.trellis/spec/
.trellis/workspace/
.opencode/

当你能解释这条链路时，就说明你已经掌握了 Trellis 的核心：

user input -> injected context -> workflow-state -> task lifecycle -> agents -> check/update/finish

之后再去看 trellis-meta，你就不会只是“改几个 prompt”，而是在理解整个 harness 契约的基础上做定制。

这也是 Trellis 最值得学习的地方：它不是让 AI 更自由地发挥，而是用可读、可查、可验证的文件和脚本，把 AI 协作变成一条稳定的工程流程。