EcoPaste 仓库中的 Trellis 规范任务规划指南：单 Agent 执行模型、工作单元分解与 PRD 模板实践-平芜编程栈

桌面应用

【免费下载链接】EcoPaste

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

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

本文围绕 EcoPaste 仓库内.agents/skills/trellis-spec-bootstrap/references/spec-task-planning.md的核心内容展开，讲解在基于 Trellis 的 AI 编码工作流中，如何为.trellis/spec/规范文档创建工作单元（spec work units）、如何编写可验收的 Trellis 任务 PRD，以及如何在不依赖特定平台与 CLI 的前提下组织可选辅助 Agent。读完本文，你将掌握一套平台无关（platform-neutral）的规范引导（spec bootstrap）任务规划方法，并能够直接在类似 EcoPaste 这样"Rust-First + 前端展示"的 Tauri 仓库中落地执行。

一、定位：这份文档在 Trellis 工作流中的角色

EcoPaste 仓库使用 Trellis 管理 AI 编码工作流。根据 AGENTS.md 中维护的 Trellis 指令块，项目的工作知识按以下目录组织：

.trellis/workflow.md—— 开发阶段划分、何时创建任务、技能路由；
.trellis/spec/—— 按包（package）和层（layer）划分的编码规范（写代码前先读对应层规范）；
.trellis/workspace/—— 开发者日志与会话痕迹；
.trellis/tasks/—— 进行中与已归档的任务（PRD、研究资料、jsonl 上下文）。

而.agents/skills/目录下存放了一组可复用的 Trellis 技能，其中trellis-spec-bootstrap专门负责"从真实代码库创建或刷新.trellis/spec/规范"。本次作为主体的 spec-task-planning.md 正是该技能工作流中关于"规范工作分解与任务规划"的参考文档，与同级参考文档 repository-analysis.md（仓库架构分析）和 spec-writing.md（规范写作）共同构成完整的引导闭环。

在 EcoPaste 仓库的实际环境中，这类规划直接服务于为src-tauri/（Rust 后端）与src/（React 前端）编写项目专属的编码规范——即把 AGENTS.md 中已经沉淀的架构边界（如"剪贴板监听、数据库读写、窗口定位必须在 Rust 实现"）进一步拆解为可被未来 Agent 直接执行的.trellis/spec/<layer>/<topic>.md文档。

二、默认执行模型：单 Agent 全流程所有权

文档开头即给出一个关键设计决策：默认使用单个 Agent 作为执行模型。该 Agent 可以为了可追溯性（traceability）创建 Trellis 任务，但技能本身不应要求特定平台、特定 CLI 或并行 worker 模型。

这一原则在 SKILL.md 中有更完整的展开：一个有能力（capable）的 Agent 拥有整个闭环——分析仓库、选择规范边界、撰写文档、验证结果，并且"工作流不依赖特定宿主、CLI 或 Agent 品牌"。对应的五步工作流为：

确认 Trellis 已初始化，并检查当前.trellis/spec/树；
用可得的最好工具（GitNexus、ABCoder、语言工具链、直接源码阅读）分析仓库架构；
仅在符合真实代码库形态时，按包与层分解规范工作；
用项目中的真实模式、文件路径、示例与反例填充或重塑规范文件；
验证最终规范内部一致、无模板占位符。

值得注意的约束是：EcoPaste 仓库的 biome.json 已将.trellis/.runtime列入 lint/format 排除范围，说明.trellis/目录被当作仓库正式管理的工作区资产，其内容（包括任务规划产生的 spec 文件）不应被代码格式化工具意外改动——这也印证了单 Agent 执行时需要尊重仓库既有的目录约定。

实践要点：作为执行 Agent，你应该默认承担从分析到验证的全部工作；平台是否提供/trellis:*命令、是否存在辅助 Agent，都不应成为技能能否运行的前提。

三、工作单元分解（Decomposition）：围绕真实所有权边界

文档明确反对"为了拆分而拆分"。规范工作单元应围绕真实的所有权边界（real ownership boundaries）创建，具体规则如下：

一个包对应一个工作单元：当一个包有自己的约定（conventions）时，以包为单位；
同一包内按层拆分：当同一个包内部存在不同的前端、后端、CLI、worker 或共享库规则时，按层（layer）拆分；
跨层模式单独成文：当一个模式跨越多个包且不归属于某一层时，创建一个跨切面（cross-cutting）指南；
避免人为拆分：一个小型库通常只需要一次聚焦的规范引导（spec pass），而不是多个任务。

把这一原则映射到 EcoPaste 的真实代码结构上，可以给出清晰的拆分示范。从仓库目录结构看，项目明显分为两大层：

层	目录	典型所有权内容
Rust 后端	src-tauri/src/	`commands/`（tauri command 入口，只做校验与转发）、`db/`（sqlx 仓储）、`clipboard/`（剪贴板读写与监听）、`window/`（窗口管理）、`keystroke/`、`keyboard/`、`tray/`、`menu/`等
React 前端	src/	`components/`、`pages/`、`stores/`、`hooks/`、`locales/`、`utils/`
跨层契约	两端共享	命令名、事件名、channel/storage key 等字面量的集中维护（Rust 模块常量 + src/constants/ 同步更新）

结合 AGENTS.md 的架构边界约定可以推断：在 EcoPaste 上做规范引导时，合理的分解方案是"后端一层 + 前端一层 + 一个跨端契约指南"，而不是为每个 Rust 子模块（clipboard/、window/、db/等）各建一个任务——因为它们共享同一套 Rust 约定（async 命令、Result<T, AppError>、thiserror/anyhow错误处理等），可以合并为一次聚焦的后端规范引导。

四、任务形态（Task Shape）：可直接复用的 PRD 模板

当 Trellis 任务确实有用时，文档要求编写一份简洁的 PRD（Product Requirements Document），并给出了完整的七段式模板。该模板是本篇的核心可复用资产，完整继承如下：

# Fill <package-or-layer> Trellis Specs ## Goal Write project-specific `.trellis/spec/` guidance for <scope>. ## Scope - Spec directory: - Source directories to inspect: - Tests to inspect: - Out of scope: ## Architecture Context Summarize the concrete findings from repository analysis. ## Files To Create Or Update - `.trellis/spec/.../index.md` - `.trellis/spec/.../<topic>.md` ## Rules - Adapt the spec file set to the real codebase. - Use real source examples with file paths. - Remove template-only sections that do not apply. - Do not modify product source code unless the task explicitly asks for it. ## Acceptance Criteria - [ ] Specs contain concrete examples and anti-patterns from the repository. - [ ] No placeholder text remains. - [ ] Index files match the final spec files. - [ ] Claims are backed by source files, tests, or project docs.

各段落的填写要点

Goal（目标）：一句话说明要为哪个范围编写项目专属的.trellis/spec/指南。例如在 EcoPaste 中可以是"为src-tauri/（Rust 后端层）编写项目专属规范"。
Scope（范围）：明确四个维度——目标规范目录、需要检查的源码目录、需要检查的测试、明确排除的内容。排除项的写法尤其重要，它能防止 Agent 越界修改产品代码或无关模块。
Architecture Context（架构上下文）：先做仓库分析，再写任务，而非从模板出发填空。这与 repository-analysis.md 的核心指令一致："不要从通用 spec 模板开始填空，要从代码出发，再让规范结构跟随代码。"分析阶段需要捕获的信息包括：包边界（每个包拥有什么、哪些导入跨越边界）、运行时层（CLI/后端/前端/worker/共享库/测试工具）、核心抽象（类型、服务、存储、命令、路由）、数据流（用户输入从哪进入、如何校验、状态持久化在哪）、错误处理（失败如何表示、记录、展示、测试）、配置（默认值、环境配置、生成文件、模板在哪）、测试（哪些测试风格是可信范例）。
Files To Create Or Update（待创建或更新的文件）：明确列出index.md与主题文档。根据 spec-writing.md 的结构原则：index.md保持为规范目录的导航文件；主题在开发者会独立查找时拆分、在重复时会合并、不适用的模板文件删除、模板遗漏的重要本地模式则新增文件。
Rules（规则）：四条硬性规则——规范文件集必须适配真实代码库；必须使用带文件路径的真实源码示例；删除不适用的模板段落；除非任务明确要求，不得修改产品源码。
Acceptance Criteria（验收标准）：四条可勾选的标准构成完成定义的底线——规范包含来自仓库的具体示例与反例、无占位符残留、index 文件与最终规范文件集一致、所有论断都有源码/测试/项目文档支撑。

与仓库既有质量标准的衔接

PRD 模板中的"Claims are backed by source files, tests, or project docs"与 spec-writing.md 的"证据驱动写作"一脉相承：每条重要规则都应由以下之一背书——展示偏好的模式的源文件、展示预期行为的测试文件、定义约定的项目文档、或多个文件中的重复模式。而 EcoPaste 仓库恰好提供了大量可作证据的实体，例如 AGENTS.md 中的 Rust 约定（命令与仓储函数使用async并返回Result<T, AppError>、SQL 用sqlx::query/query_as而非query!宏、已发布 migration 不回改等）都是可直接写入 spec 并以src-tauri/src/下真实文件为引用的素材。

五、可选辅助 Agent（Optional Helper Agents）：有清晰所有权的分工

文档将辅助 Agent 明确定位为可选项：如果宿主支持子代理（subagents），辅助 Agent 可以检查独立包或运行验证，但主 Agent 仍然拥有集成与最终质量的所有权。技能内部不应编码辅助 Agent 的名称、厂商特定命令或平台特定路由——任务里只放必要的工作与验收标准。

辅助任务的职责边界按类型划分：

只读研究任务（Read-only research tasks）：可以检查分配范围内任何需要的源码；
写入任务（Write tasks）：应拥有不相交的规范目录（disjoint spec directories），避免并发写入冲突；
验证任务（Verification tasks）：检查占位符是否清除、链接是否断裂、整体一致性。

结合 SKILL.md 的运行规则可以确认："默认单所有权执行，可选辅助 Agent 是实现细节，不是要求或用户可见依赖"，且"除非目标项目已经标准化于某平台，否则不要写平台特定指令"。因此在 EcoPaste 这样的仓库中，合理的辅助 Agent 用法是：让一个只读 Agent 独立核查src-tauri/src/db/（例如确认query_as字段与测试结构体字面量的一致性），同时让主 Agent 处理前端规范；两端规范目录互不重叠，最后由主 Agent 统一验收。

六、规划产出的质量闭环：验证与一致性

任务规划不只是写出 PRD，还隐含了最终的质量闭环。结合本技能体系，规划阶段的验收标准应与执行阶段的终检衔接：

占位符清理：最终.trellis/spec/不得残留占位符文本。trellis-spec-bootstrap体系的 spec-writing.md 提供了可执行的终检命令：

grep -R "To be filled\|TODO: fill\|placeholder" .trellis/spec

链接与索引一致性：检查链接、index 文件，以及是否有任何 spec 仍在描述模板而非当前仓库。
与既有技能衔接：本技能的"引导"职责与trellis-update-spec技能的"持续更新"职责（见 trellis-update-spec/SKILL.md）形成前后端闭环——引导阶段建立可执行的契约文档，后续每次调试、修复、实现产生的"可执行契约"再回流更新对应 spec 文件，这正是 EcoPaste 中 Trellis 体系"把一次会话学到的知识沉淀为跨会话的机构记忆"的实现方式。

七、在 EcoPaste 上的落地示例

将本文所述方法应用到 EcoPaste，一次典型的 Trellis 规范引导任务规划可以这样填充：

# Fill src-tauri（Rust 后端层）Trellis Specs ## Goal 为 Rust 后端层编写项目专属 `.trellis/spec/` 指南，覆盖命令层、DB 层与剪贴板模块的编码契约。 ## Scope - Spec directory: `.trellis/spec/backend/` - Source directories to inspect: `src-tauri/src/commands/`、`src-tauri/src/db/`、`src-tauri/src/clipboard/`、`src-tauri/src/core/` - Tests to inspect: `src-tauri/src/db/` 下的仓储测试、`cargo test` 覆盖的模块测试 - Out of scope: `src/`（前端规范单独规划）、`src-tauri/migrations/` 既有 SQL 内容（只读参照） ## Architecture Context 仓库采用 Rust-First 的 Tauri 架构；`commands/` 是薄层（参数校验 + 转发），`db/` 是 sqlx 仓储与连接池，`clipboard/` 承担监听与读写；命令与仓储均为 async 并返回 `Result<T, AppError>`。 ## Files To Create Or Update - `.trellis/spec/backend/index.md` - `.trellis/spec/backend/commands.md` - `.trellis/spec/backend/db.md` ## Rules - 规范文件集适配真实代码库（参考 AGENTS.md 的 Rust 约定章节）。 - 使用真实源码示例并标注文件路径。 - 删除不适用的模板段落（如无 CLI 层则不写 CLI 相关段落）。 - 除任务明确要求外，不修改产品源码。 ## Acceptance Criteria - [ ] 规范包含来自仓库的具体示例与反例（如 `query_as` 字段不匹配导致 UI 空结果的反例）。 - [ ] 无占位符文本残留。 - [ ] index 文件与最终规范文件集一致。 - [ ] 每条论断都有源码、测试或项目文档支撑。

这个示例中的反例素材（query_as字段不匹配可能表现为 UI 空结果、平台代码用#[cfg(target_os = ...)]隔离、已发布 migration 不回改等）全部出自 AGENTS.md，是规划任务时可以直接引用的仓库证据。

结语

spec-task-planning.md提供了一套精简但完备的 Trellis 规范任务规划方法论：单 Agent 默认执行、按真实所有权边界分解、用七段式 PRD 模板承载任务、让辅助 Agent 承担有清晰所有权的分工。在 EcoPaste 这类同时拥有 Rust 后端与 React 前端的仓库中，这套方法帮助你在不引入额外平台依赖的前提下，把 AGENTS.md 沉淀的架构约定逐步转化为.trellis/spec/中可执行、可验收、可被未来 Agent 直接引用的编码规范。