桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载导读在 EcoPaste一个跨平台剪贴板管理工具的仓库中开发流程引入了 Trellis 多智能体工作流。本文聚焦其中承担代码质量最后一道防线的Check Agent检查代理trellis-check它负责在代码写完后通过git diff获取变更、对照任务需求文档PRD与开发规范Spec逐项审查、直接自我修复问题并最终跑通 lint 与类型检查。读完本文你将理解该代理的角色契约、上下文注入机制、四步检查工作流与标准化报告格式并能把同样的检查代理模式复用到自己的 AI 辅助开发流程中。检查代理在 Trellis 工作流中的位置Trellis 是一个多智能体开发流水线典型做法是主会话main session依次派发三类子代理子代理职责角色文档trellis-research查找、解释并持久化信息到{TASK_DIR}/research/*.md.cursor/agents/trellis-research.mdtrellis-implement依据 Spec 与任务产物实现功能禁止 git commit/push/merge.cursor/agents/trellis-implement.mdtrellis-check获取代码变更、对照需求与规范审查、自我修复、运行验证.cursor/agents/trellis-check.md检查代理的角色文档 .cursor/agents/trellis-check.md 在文件头部 Front Matter 中声明了它的专用性约束name: trellis-check description: Trellis quality check agent. Use this exact agent for Trellis task verification, check.jsonl context injection, and self-fixing code review. Do not use generic/default/generalPurpose agents for Trellis checks. tools: Read, Write, Edit, Bash, Glob, Grep要点有二必须使用专用代理Trellis 任务验证、check.jsonl上下文注入、自我修复式代码审查都应由trellis-check完成不应退化为通用代理。工具集合Read / Write / Edit / Bash / Glob / Grep—— 其中Write与Edit的存在暗示了它被授权直接修改代码这与后文自我修复Self-Fix原则一脉相承。递归守卫Recursion Guard递归守卫是子代理角色契约中最容易被忽略、却最容易引发事故的部分。其核心含义当trellis-check被派发时它已经是检查代理本身必须直接完成审查与修复不得再次派发子代理。角色文档明确列出三条规则不得再次派发trellis-check或trellis-implement子代理如果 SessionStart 上下文、工作流面包屑workflow-state breadcrumbs或workflow.md提示要派发trellis-implement/trellis-check应将其理解为主会话指令已被当前角色满足直接执行即可只有主会话main session有权派发 Trellis 的 implement/check 代理。如果需要更多实现工作子代理应提交建议派发的报告而不是自行派发。这一设计避免了代理派发代理派发代理……的递归失控保证每一层智能体都聚焦自己的单一职责。同理trellis-implement.md 中的 Recursion Guard 也采用完全相同的模式。Trellis 上下文加载协议hook 注入与兜底检查代理工作时依赖大量上下文任务产物、开发规范、检查清单因此定义了严格的上下文加载协议优先路径hook 注入标记查看输入中是否存在!-- trellis-hook-injected --标记标记存在任务产物、Spec 与研究文件已被自动加载到输入中直接开始检查工作标记缺失说明 hook 注入未触发常见于 Windows Claude Code、--continue续会话、fork 分发、hook 被禁用等场景需要从派发提示第一行的Active task: path中找到任务路径然后依次读取task-path/check.jsonl及其列出的每个文件task-path/prd.mdtask-path/design.md若存在task-path/implement.md若存在。源码级的注入实现EcoPaste 仓库中的 .cursor/hooks/inject-subagent-context.py 正是这套协议的实现载体。它在PreToolUseTask 工具调用之前触发通过build_check_prompt()构造完整的检查提示词def build_check_prompt(original_prompt: str, context: str) - str: return f!-- trellis-hook-injected -- # Check Agent Task ... ## Workflow 1. **Get changes** - Run git diff --name-only and git diff to get code changes 2. **Check against specs** - Check item by item against specs above 3. **Self-fix** - Fix issues directly, dont just report 4. **Run verification** - Run projects lint and typecheck commands ## Important Constraints - Fix issues yourself, dont just report - Must execute complete checklist in check specs - Pay special attention to impact radius analysis (L1-L5)从源码可以看到三个关键设计标记即契约注入后的提示词第一行就是!-- trellis-hook-injected --供代理判断上下文是否已注入检查上下文的组成get_check_contextcheck.jsonl中列出的条目 →prd.md需求 →design.md技术设计若存在 →implement.md执行计划若存在影响半径分析L1–L5检查代理被明确要求关注变更的影响半径从单文件局部改动L1到跨层数据流L5逐级排查防止改了 A 破坏了 B。此外Hook 还区分了常规检查阶段与Finish 阶段当原始提示词中出现[finish]标记时会改用get_finish_context()复用check.jsonlprd.md与build_finish_prompt()执行 PR 前的最终校验包括验证prd.md的验收标准、必要时同步 Spec。这些钩子统一在 .cursor/hooks.json 中注册{ hooks: { beforeShellExecution: [{ command: python3 .cursor/hooks/inject-shell-session-context.py, timeout: 5 }], preToolUse: [{ command: python3 .cursor/hooks/inject-subagent-context.py, matcher: Task|Subagent, timeout: 30 }], sessionStart: [{ command: python3 .cursor/hooks/session-start.py, timeout: 30 }] }, version: 1 }session-start.py则在会话启动时注入当前任务状态、Git 分支与工作区整洁度、可用 Spec 索引清单等结构化上下文让整个会话始终知道现在做到哪一步。检查前的上下文清单角色文档要求在正式检查之前必须先读四类资料.trellis/spec/—— 开发规范Development guidelines任务prd.md—— 需求文档任务design.md—— 技术设计若存在任务implement.md—— 执行计划若存在。在 EcoPaste 仓库中Spec 按package/layer组织例如 .trellis/spec/backend/ 下的architecture.md、clipboard-pipeline.md、database-and-storage.md以及 .trellis/spec/frontend/ 下的component-guidelines.md、hook-guidelines.md、type-safety.md等跨包思维指南位于 .trellis/spec/guides/。每个index.md是入口内含Pre-Development Checklist与Quality Check两个章节实际指南则散落在其指向的.md文件中。任务产物则存放在.trellis/tasks/下。仓库中归档的真实任务如 .trellis/tasks/archive/2026-07/07-03-onboarding-admin-launch/展示了完整产物集task.json、prd.md、design.md、implement.md、implement.jsonl与check.jsonl。其中check.jsonl采用如下 JSONL 行格式维护检查代理需要注入的文件清单{file: path/to/file.md, reason: why this file is needed} {file: path/to/dir/, type: directory, reason: read all .md files under this dir}需要说明的是新建任务的check.jsonl默认只有一条自述种子行{_example: ...}没有真实的file字段只有存在至少一条含file字段的精选条目时Hook 才会认为该清单已就绪并执行注入这一就绪判断逻辑见 .cursor/hooks/session-start.py 的_has_curated_jsonl_entry。检查代理的五大核心职责角色文档将检查代理的职责归纳为五点这也是整个工作流的骨架Get code changes—— 用git diff获取未提交的代码Review task artifacts—— 将变更对照prd.md、design.md若存在、implement.md若存在逐项核对Check against specs—— 验证代码是否符合开发规范Self-fix—— 亲自修复发现的问题而不只是报告问题Run verification—— 运行类型检查typecheck与 lint。其中第四点被单独强调为一条重要原则Fix issues yourself, dont just report them. You have write and edit tools, you can modify code directly.这与其他只审查不修改的评审代理形成了鲜明对比Trellis 的检查代理被设计为主动修复者而不是旁观者。这种模式显著减少了发现 → 打回 → 再派发 → 再审查的往返轮次。四步检查工作流详解Step 1: 获取变更检查代理的第一步永远是摸清这次改了什么git diff --name-only # 列出变更文件 git diff # 查看具体变更Step 2: 对照任务产物与规范审查读取任务的prd.md、design.md若存在、implement.md若存在再读取 .trellis/spec/ 下的相关规范然后逐项检查是否满足任务需求是否遵循技术设计与执行计划当存在时是否遵循目录结构约定是否遵循命名约定是否遵循代码模式code patterns是否有缺失的类型missing types是否存在潜在 Bug。Step 3: 自我修复Self-Fix发现问题后立即执行三步直接修复问题使用编辑工具记录修复内容继续检查其他问题。也就是说检查代理应当边查边修而不是积累一批问题再统一处理。Step 4: 运行验证运行项目实际的 lint 与 typecheck 命令验证修改若失败继续修复并重新运行只有全部通过才算完成。EcoPaste 仓库中的项目级验证命令可以参照 package.json前端 pnpm 脚本与 src-tauri/Cargo.tomlRust 侧构建来确认——检查代理在实际运行时会调用项目自身的命令而非通用命令。标准化报告格式检查代理完成工作后必须以固定格式输出报告角色文档给出了完整模板## Self-Check Complete ### Files Checked - src/components/Feature.tsx - src/hooks/useFeature.ts ### Issues Found and Fixed 1. file:line - what was fixed 2. file:line - what was fixed ### Issues Not Fixed (If there are issues that cannot be self-fixed, list them here with reasons) ### Verification Results - TypeCheck: Passed - Lint: Passed ### Summary Checked X files, found Y issues, all fixed.这个模板的价值在于可机读、可追踪Files Checked明确审查边界Issues Found and Fixed用文件:行号定位每个修复点Issues Not Fixed显式暴露无法自主修复的问题及原因例如需要产品决策、涉及跨模块契约供主会话决策Verification Results让是否真的跑通了 lint/typecheck一目了然Summary用一行数字总结整体结果。与检查技能SKILL的配合更细的检查清单仓库中还提供了配套的技能文件 .cursor/skills/trellis-check/SKILL.md将上述四步工作流扩展为六步并补充了大量可勾选的检查维度Step 1识别变更git diff --name-only HEADgit statusStep 2读取任务产物并按包/层读取 Spec 的 Quality Check 章节可运行python3 ./.trellis/scripts/get_context.py --mode packages列出包与层Step 3运行项目 lint、类型检查、测试Step 4对照清单审查代码质量lint 通过类型检查通过测试通过无残留调试日志无被压制警告或类型安全绕过测试覆盖新函数 → 有单元测试Bug 修复 → 有回归测试行为变更 → 现有测试已更新Spec 同步.trellis/spec/是否需要更新新模式、新约定、经验教训—— 若未来自己是否会踩同样的坑则应更新对应 Spec 文档Step 5跨层检查维度当变更跨越多个层时数据流触及 3 层时读路径Storage → Service → API → UI与写路径UI → API → Service → Storage是否走通类型/模式是否在各层间正确传递错误是否正确传播代码复用修改常量/创建工具时创建新代码前是否先grep -r pattern src/搜索既有实现两处以上定义同一值 → 是否抽取为共享常量批量修改后是否所有出现点都已更新导入/依赖新建文件时导入路径正确相对 vs 绝对无循环依赖同层一致性其他使用同一概念的地方是否保持一致Step 6报告并修复列出违规项并直接修复修复后重新运行项目检查。这一清单与角色文档中的检查点列表互补角色文档定义代理是谁、怎么运转SKILL 则给出具体查什么。运行环境与配置要点任务生命周期命令检查代理的工作始终围绕活动任务展开任务由 .trellis/scripts/task.py 管理常用命令摘自 .trellis/workflow.mdpython3 ./.trellis/scripts/task.py create title [--slug name] [--parent dir] # 创建任务 python3 ./.trellis/scripts/task.py start name # 激活任务status → in_progress python3 ./.trellis/scripts/task.py current --source # 查看当前活动任务及来源 python3 ./.trellis/scripts/task.py finish # 清除活动任务 python3 ./.trellis/scripts/task.py archive name # 归档到 archive/{year-month}/ python3 ./.trellis/scripts/task.py add-context name action file reason # 向 jsonl 清单添加上下文 python3 ./.trellis/scripts/task.py list-context name [action] # 查看清单 python3 ./.trellis/scripts/task.py validate name # 校验任务注意一个细节task.py start只有在能解析到会话身份来自 hook 输入的 context key、TRELLIS_CONTEXT_ID环境变量或平台原生会话变量时才会成功会话状态存放在.trellis/.runtime/sessions/下。这解释了为什么inject-shell-session-context.py要在 Cursor 执行 shell 命令前写一个有效期 30 秒的运行时票据把对话身份桥接给task.py。配置项项目级配置位于 .trellis/config.yaml与检查流程相关的关键项配置默认值说明max_journal_lines2000会话日志单文件最大行数超限自动轮转到新 journal 文件session_auto_committrue会话日志/任务归档后是否自动 stagecommit可设为false保持本地session_commit_messagechore: record journal自动提交时的提交信息hooks.after_*无任务创建/启动/完成/归档后的生命周期钩子通过TASK_JSON_PATH环境变量拿到任务路径channel.worker_guardidle_timeout: 5m、max_live_workers: 6Channel 工作线程的空闲回收与存活上限环境变量开关三个 Hook 均支持显式禁用源码中均有判断逻辑TRELLIS_HOOKS0或TRELLIS_DISABLE_HOOKS1—— 关闭 Trellis 钩子CLAUDE_NON_INTERACTIVE1、CURSOR_NON_INTERACTIVE1等平台非交互变量 —— 跳过 SessionStart 注入。实践要点总结把 EcoPaste 仓库中的这套检查代理模式提炼成可复用经验专用代理 递归守卫为质量检查单独定义一个带明确工具集含 Write/Edit的代理并硬性禁止子代理再派发子代理上下文先于工作检查前必须拿到prd.md/design.md/implement.md/ Spec /check.jsonl清单且用!-- trellis-hook-injected --标记让代理自检上下文是否已注入未注入则走兜底读取路径自修复而非仅报告检查代理直接修代码并把修复记录成文件:行号格式让审查过程可追溯验证闭环所有修复必须以项目真实的 lint 与 typecheck 通过为终点影响半径思维跨层变更要沿数据流Storage ↔ Service ↔ API ↔ UI追查同时检查代码复用与导入依赖避免局部修复引入全局破坏标准化报告固定Files Checked / Issues Found and Fixed / Issues Not Fixed / Verification Results / Summary五段式输出使主会话可以快速决策并留档。这套模式的价值在于它把代码审查从一次性的主观判断变成了上下文注入 → 对照规范逐项核查 → 自主修复 → 工具验证 → 结构化报告的可重复流水线——对 EcoPaste 这类前后端一体Tauri React Rust的仓库来说检查代理正是保证 Spec、任务需求与代码三者始终同步的关键环节。赞分享桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载相关推荐EcoPaste 代码质量校验实战基于 trellis-check 技能的分层自检工作流EcoPaste 代码质量校验实战基于 trellis check 技能的分层自检工作流 Trellis 是一套以任务制品 prd.md / design.桌面应用EcoPaste 仓库代码质量检查完整流程基于 Trellis trellis-check 技能的分层校验实战指南EcoPaste 仓库代码质量检查完整流程基于 Trellis trellis check 技能的分层校验实战指南 本指南完整解析 EcoPaste 仓库 .桌面应用EcoPaste 中基于 Trellis 的代码质量门禁深度解析 trellis-check 检查技能EcoPaste 中基于 Trellis 的代码质量门禁深度解析 trellis check 检查技能 导读 本文聚焦 EcoPaste 项目中 AI 编码工桌面应用上一篇Digi-Key KiCad Library符号库深度探索从基础元件到高级模块的终极指南 下一篇提升TypeScript开发体验的利器ts-reset创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考