企业官网建设流程全解析

• 桌面应用

导读

在 EcoPaste（一个跨平台剪贴板管理工具）的仓库中，开发流程引入了 Trellis 多智能体工作流。本文聚焦其中承担"代码质量最后一道防线"的Check Agent（检查代理，trellis-check）：它负责在代码写完后，通过git diff获取变更、对照任务需求文档（PRD）与开发规范（Spec）逐项审查、直接自我修复问题，并最终跑通 lint 与类型检查。读完本文，你将理解该代理的角色契约、上下文注入机制、四步检查工作流与标准化报告格式，并能把同样的"检查代理"模式复用到自己的 AI 辅助开发流程中。

检查代理在 Trellis 工作流中的位置

Trellis 是一个多智能体开发流水线，典型做法是主会话（main session）依次派发三类子代理：

检查代理的角色文档 .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

要点有二：

1. 必须使用专用代理：Trellis 任务验证、check.jsonl上下文注入、自我修复式代码审查都应由trellis-check完成，不应退化为通用代理。
2. 工具集合：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.md；
  • <task-path>/design.md（若存在）；
  • <task-path>/implement.md（若存在）。

源码级的注入实现

EcoPaste 仓库中的 .cursor/hooks/inject-subagent-context.py 正是这套协议的实现载体。它在PreToolUse（Task 工具调用之前）触发，通过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, don't just report 4. **Run verification** - Run project's lint and typecheck commands ## Important Constraints - Fix issues yourself, don't just report - Must execute complete checklist in check specs - Pay special attention to impact radius analysis (L1-L5)"""

从源码可以看到三个关键设计：

1. 标记即契约：注入后的提示词第一行就是<!-- trellis-hook-injected -->，供代理判断"上下文是否已注入"；
2. 检查上下文的组成（get_check_context）：check.jsonl中列出的条目 →prd.md（需求） →design.md（技术设计，若存在） →implement.md（执行计划，若存在）；
3. 影响半径分析（L1–L5）：检查代理被明确要求关注变更的影响半径，从单文件局部改动（L1）到跨层数据流（L5）逐级排查，防止"改了 A 破坏了 B"。

此外，Hook 还区分了"常规检查阶段"与"Finish 阶段"：当原始提示词中出现[finish]标记时，会改用get_finish_context()（复用check.jsonl+prd.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 索引清单等结构化上下文，让整个会话始终"知道现在做到哪一步"。

检查前的上下文清单

角色文档要求，在正式检查之前必须先读四类资料：

1. .trellis/spec/—— 开发规范（Development guidelines）；
2. 任务prd.md—— 需求文档；
3. 任务design.md—— 技术设计（若存在）；
4. 任务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）。

检查代理的五大核心职责

角色文档将检查代理的职责归纳为五点，这也是整个工作流的骨架：

1. Get code changes—— 用git diff获取未提交的代码；
2. Review task artifacts—— 将变更对照prd.md、design.md（若存在）、implement.md（若存在）逐项核对；
3. Check against specs—— 验证代码是否符合开发规范；
4. Self-fix—— 亲自修复发现的问题，而不只是报告问题；
5. Run verification—— 运行类型检查（typecheck）与 lint。

其中第四点被单独强调为一条"重要原则"：

Fix issues yourself, don't 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）

发现问题后立即执行三步：

1. 直接修复问题（使用编辑工具）；
2. 记录修复内容；
3. 继续检查其他问题。

也就是说，检查代理应当"边查边修"，而不是积累一批问题再统一处理。

Step 4: 运行验证

运行项目实际的 lint 与 typecheck 命令验证修改：

• 若失败，继续修复并重新运行；
• 只有全部通过，才算完成。

EcoPaste 仓库中的项目级验证命令可以参照 package.json（前端 pnpm 脚本）与 src-tauri/Cargo.toml（Rust 侧构建）来确认——检查代理在实际运行时会调用项目自身的命令，而非通用命令。

标准化报告格式

检查代理完成工作后，必须以固定格式输出报告，角色文档给出了完整模板：

## 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 HEAD+git status；Step 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.md）：

python3 ./.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，与检查流程相关的关键项：

环境变量开关

三个 Hook 均支持显式禁用（源码中均有判断逻辑）：

• TRELLIS_HOOKS=0或TRELLIS_DISABLE_HOOKS=1—— 关闭 Trellis 钩子；
• CLAUDE_NON_INTERACTIVE=1、CURSOR_NON_INTERACTIVE=1等平台非交互变量 —— 跳过 SessionStart 注入。

实践要点总结

把 EcoPaste 仓库中的这套"检查代理"模式提炼成可复用经验：

1. 专用代理 + 递归守卫：为质量检查单独定义一个带明确工具集（含 Write/Edit）的代理，并硬性禁止子代理再派发子代理；
2. 上下文先于工作：检查前必须拿到prd.md/design.md/implement.md/ Spec /check.jsonl清单，且用<!-- trellis-hook-injected -->标记让代理自检上下文是否已注入，未注入则走兜底读取路径；
3. 自修复而非仅报告：检查代理直接修代码，并把修复记录成文件:行号格式，让审查过程可追溯；
4. 验证闭环：所有修复必须以项目真实的 lint 与 typecheck 通过为终点；
5. 影响半径思维：跨层变更要沿数据流（Storage ↔ Service ↔ API ↔ UI）追查，同时检查代码复用与导入依赖，避免局部修复引入全局破坏；
6. 标准化报告：固定Files Checked / Issues Found and Fixed / Issues Not Fixed / Verification Results / Summary五段式输出，使主会话可以快速决策并留档。

这套模式的价值在于：它把"代码审查"从一次性的主观判断，变成了"上下文注入 → 对照规范逐项核查 → 自主修复 → 工具验证 → 结构化报告"的可重复流水线——对 EcoPaste 这类前后端一体（Tauri + React + Rust）的仓库来说，检查代理正是保证 Spec、任务需求与代码三者始终同步的关键环节。

• 桌面应用