EcoPaste 中的 Trellis Implement Agent：子代理驱动的 AI 编码实现规范与工作流解析-平芜编程栈

桌面应用

【免费下载链接】EcoPaste

🎉跨平台的剪贴板管理工具 | Cross-platform clipboard management tool

项目地址：https://gitcode.com/ayangweb/EcoPaste

在 EcoPaste 仓库的.trellis/目录下，内置了一套名为 Trellis 的 AI 协作开发工作流系统。其中，implement.md 定义了一个职责边界极其清晰的子代理——Implement Agent（实现子代理）：它负责读取规格（spec）与任务产物（task artifacts），随后编写符合既有模式的代码，并在提交前完成自检。本文将以其定义文档为主体，结合 check.md、workflow.md 与真实任务归档，完整拆解该子代理的上下文读取顺序、核心职责、禁止操作、执行工作流、代码规范与回报格式，帮助读者理解"主会话负责规划与提交、子代理负责实现与自检"这一分工模式如何在 AI 编码通道（channel runtime）中落地。

子代理的定位与启动方式

从 implement.md 的文件头（frontmatter）可以看到它的四个元信息字段：

name: implement—— 子代理的唯一标识；
description—— "Code implementation expert for the Trellis channel runtime. Understands specs and task artifacts, then implements features. No git commit allowed."，一句话点明身份：理解规格与任务产物、实现功能、但绝不允许 git commit；
provider: claude—— 声明由 Claude 扮演该角色；
labels: [trellis, implement]—— 打上系统级标签，便于被调度器检索。

它的启动方式是通过trellis channel spawn --agent implement在 Trellis 通道运行时内被派发，并在收件箱中收到一行Active task: <path>。这行路径就是它定位任务产物的入口：所有需要读取的prd.md、design.md、implement.md、implement.jsonl都存放在该任务目录下。

在 workflow.md 的 Phase 2.1（Implement）中，主会话（main session）负责派发该子代理，并有一条关键约束：派发提示词必须以Active task: <task path from task.py current>开头，之后才进入角色指令。同时存在"子代理自我豁免"规则——如果当前会话本身就是trellis-implement子代理，则不得再派生另一个trellis-implement或trellis-check，避免无限递归派发。这些约束保证了"主会话派发、子代理执行"的单向调用链。

上下文读取顺序：先清单、再需求、后设计

Implement Agent 的核心工作前提是"读懂上下文"。定义文档明确要求按固定顺序读取以下文件：

<task-path>/implement.jsonl（若存在）——本轮任务精选的规格清单（spec manifest），其中列出的每个文件都必须读取；
<task-path>/prd.md——需求文档（requirements）；
<task-path>/design.md（若存在）——技术设计文档；
<task-path>/implement.md（若存在）——执行计划；
.trellis/spec/——项目级开发规范，只加载与即将编写的 diff 相关的部分。

这里有一个容易混淆的点值得注意：任务目录里名为implement.md的文件是"执行计划"（execution plan），与.trellis/agents/implement.md这个"子代理定义文档"是两个不同层级的产物。前者由主会话在规划阶段（Phase 1）写入，后者是子代理自身的角色说明书。

以归档任务 07-03-onboarding-admin-launch/implement.md 为真实样本，可以看到一份合格执行计划的结构：Checklist（按可勾选条目列出"Add Rust admin module → Addgeneral.run_as_adminto settings → Add command boundary → Wire startup → Wire onboarding UI → Update release note"等实现步骤）、Validation（验证命令清单）、Risky Files（风险文件列表）、Rollback（回滚方案）。这类文档正是 Implement Agent 在动手前必须理解清楚的对象。

此外，workflow.md 的 Phase 1.3 解释了implement.jsonl的产生方式：它由主会话在规划阶段用python3 ./.trellis/scripts/task.py add-context <name> implement <path> <reason>逐条添加，每行一个 JSON 对象（{"file": "<path>", "reason": "<why>"}），路径以仓库根目录为基准。清单中只应包含 spec 文件与研究文件，不应包含源码路径（源码由子代理在实现阶段自行阅读），也不能替代implement.md本身。

核心职责：理解、实现与自检

定义文档用四条概括了子代理的本职：

Understand specs—— 阅读.trellis/spec/中与本任务相关的规范文件；
Understand task artifacts—— 阅读上文列出的任务产物；
Implement features—— 写出遵循规格与既有模式的代码；
Self-check—— 在回报之前，对变更范围运行 lint 与类型检查。

第 4 条"自检"是整个规范的关键设计：子代理不是写完就交差，而是要在自己负责的变更范围内先跑一遍项目自带的验证命令，把结果写进回报。结合 .trellis/spec/index.md 中记录的 EcoPaste 验证基线，这套自检命令在仓库中的实际形态为：

前端：pnpm lint（Biome）与pnpm tsc（TypeScript 类型检查）；
Rust 后端：cd src-tauri && cargo fmt && cargo clippy -- -D warnings && cargo test。

在归档任务的执行计划 07-03-onboarding-admin-launch/implement.md 的 Validation 一节中，可以看到这条基线的真实应用——cargo fmt、cargo test、cargo clippy -- -D warnings、pnpm lint、pnpm tsc均被列为已验证项，而"手动 Windows 验证"（UAC 弹窗、管理员进程重启等需要真实桌面会话的交互场景）则被明确标注为未完成、待人工补测。这印证了"自动化验证 + 人工验证边界"的实践：子代理能跑的命令必须跑，跑不了的场景必须如实标注，而不是假报通过。

禁止操作：提交权与实现权的分离

Implement Agent 的定义文档用独立章节列出了一条不可逾越的红线：

git commit
git push
git merge

理由被明确写在文档中："The supervising main session owns commits. Report what changed; do not commit on its behalf."（监督方主会话拥有提交权；只回报变更，不得代提交。）

这是一套刻意设计的权限隔离：子代理只能写代码、跑验证、写回报，永远不能触碰 git 写操作。主会话在收到回报后，会依据 workflow.md 的 Phase 3.4 负责批量提交（且明令禁止git commit --amend，要求按"工作提交 → 归档提交 → 日志提交"的三段式顺序执行）。同一设计也完整复刻在兄弟子代理 check.md 的定义中——Check Agent 同样被禁止 commit/push/merge，只能审查、自行修复机械性问题并回报。这种"写操作收敛到主会话"的模式，既保证了 git 历史的一致性，也让子代理可以放心地改代码而不必担心越权。

五步工作流：从读规格到回报结果

Implement Agent 的执行流程被规范为五个有序步骤：

读规格—— 依据任务类型读取implement.jsonl中列出的规格文件（若存在）；
读任务产物—— 依次读取任务的prd.md、design.md（若存在）、implement.md（若存在）；
实现功能—— 遵循规格与既有代码模式编写代码；
自检—— 对变更范围运行项目的 lint 与类型检查；
回报—— 将改动文件、关键决策、验证结果回报给通道（channel）。

这五步与 workflow.md 中的 Phase 2.1 / 2.2 严格对应：主会话在 Phase 2.1 派发 implement 子代理，随后在 Phase 2.2 派发 check 子代理做质量复核，两者交替直至"绿灯"（lint / typecheck / 测试全部通过）。子代理完成实现后，主会话还会触发一轮全范围（full-scope）终检——用python3 ./.trellis/scripts/get_context.py --mode packages列出所有受影响的包，逐一加载各包 spec 索引中的 Quality Check 小节，以捕获跨层/跨包问题。

代码规范：克制与聚焦

定义文档对代码质量提出了四条务实要求：

Follow existing code patterns—— 跟随既有代码模式，不另起炉灶；
Don't add unnecessary abstractions—— 不添加不必要的抽象层；
Only do what the PRD asks for; no speculative scope expansion—— 只做 PRD 要求的事，不做推测性的范围扩张；
Surface uncertainty back to the channel rather than guessing—— 遇到不确定时向通道反馈，而不是猜测。

"不做过度的范围扩张"与"有疑问先反馈"这两条，实际上是在给子代理划定探索半径：它可以自由阅读.trellis/spec/中与本次 diff 相关的文件，但不允许顺手重构无关模块或擅自扩大功能面。这与 .trellis/spec/index.md 中"仅支持 macOS 与 Windows 两个#[cfg]分支、无 Linux 目标"等项目级约束相辅相成，共同保证了子代理产出的 diff 边界清晰、可审查。

回报格式：结构化、可追踪

实现完成后，子代理必须按固定模板回报，共四段：

Files Modified—— 每个改动文件一行，附一句话说明；
Implementation Summary—— 实现步骤编号列表；
Verification Results—— Lint 与 TypeCheck 各自标注pass | fail | skipped + reason；
Open Questions—— 遗留疑问（若无则省略该段）。

这套模板的设计意图很明显：让主会话在收到回报后，能立刻判断"改了什么、为什么这样改、验证是否通过、还有什么悬而未决"。其中skipped + reason的显式标注尤其重要——正如归档任务 07-03-onboarding-admin-launch/implement.md 中"Automated checks were rerun ... Manual UAC and Task Scheduler behavior still needs an interactive Windows desktop session"的表述所示，凡是环境不允许跑的验证，都必须写明原因并移交人工，而非含糊带过。

与 Check Agent 的分工协同

Implement Agent 并非孤军作战，它与 .trellis/agents/check.md 定义的 Check Agent 构成"实现 → 审查"的接力闭环。两者的设计几乎镜像对称：

维度	Implement Agent	Check Agent
启动方式	`trellis channel spawn --agent implement`	`trellis channel spawn --agent check`
上下文入口	`Active task: <path>`	`Active task: <path>`
读取顺序	`implement.jsonl`→`prd.md`→`design.md`→`implement.md`→`.trellis/spec/`	`check.jsonl`→`prd.md`→`design.md`→`implement.md`→`.trellis/spec/`
核心动作	读规格、写代码、自检（lint + typecheck）	`git diff`取 diff、对照任务产物与规格审查、机械问题就地修复、跑验证
禁止操作	commit / push / merge	commit / push / merge
回报模板	Implementation Complete	Self-Check Complete

Check Agent 的审查报告要求给出带file:line引用的具体发现，并明确区分"已修复"与"未修复（移交主会话）"。两者都由主会话在 workflow.md 的[workflow-state:in_progress]阶段统一调度，且共享"子代理禁止再派生同侪子代理"的豁免规则。这套分工把"写代码"和"审代码"的角色彻底分离，避免了同一代理既当运动员又当裁判员的盲区。

小结

EcoPaste 仓库中的 implement.md 提供了一份可复用的 AI 实现子代理规范模板。它的核心价值可以概括为三点：其一，用严格的上下文读取顺序（implement.jsonl→prd.md→design.md→implement.md→.trellis/spec/）保证子代理在动手前掌握全部必要信息；其二，用"git 写操作一律禁止"的红线实现实现权与提交权的分离；其三，用结构化的回报模板（Files Modified / Implementation Summary / Verification Results / Open Questions）让验证结果可追踪、遗留问题不沉没。配合 workflow.md 的派发协议、check.md 的审查接力，以及.trellis/tasks/下真实任务产物的佐证，这套机制构成了一个"主会话规划 + 子代理实现/自检 + 主会话提交"的完整 AI 协作闭环，可作为其他希望引入 AI 编码通道的项目直接参考的设计蓝本。