任务路由与调试插件
实现于 src/workflows/default/routing.ts、application/task-routing.ts 和 plugins/debug/。默认工作流定义 quick/small/infra/standard/foundation,调试插件贡献 debug。业务仓库描述适用范围、提供原始模板及检查定义;宿主负责授权、执行、证据、恢复和归档。
通用分类:quick 是已定位的低风险微小修改;small 是需求明确、范围有限的小功能或已知原因修复;debug 是需要诊断的异常;standard 是需正式设计的功能/模块协同;foundation 是架构、公共契约、新项目或系统迁移;infra 是工程工具、构建/CI、自动化流程维护。语言、框架、包管理器和领域验收规则不进入通用定义。普通 README 可 quick;infra 按需研究、按影响验证,重大风险提高方案要求。
同一任务内修订
用户调整需求、纠正方案或要求补齐原型、示例、文档、测试时,默认延续当前任务,更新受影响的现有产物。文件类型、Skill 或复杂度变化不是拆子任务的理由;实质方案变化按现有机制重新评估和授权。仅独立交付目标或用户明确要求拆分时创建子任务。
只要求规划时,说明哪些现有产物仍待同步;明确要求更新某项产物后,在当前任务执行。业务仓可以声明原型等同步要求,普通目录不需要增加配置或创建不存在的交付物。当前执行状态以任务、交接和检查证据为准,规划文档不重复维护多份“当前状态”。
配置与任务快照
默认路由无需配置。下面是项目同时增强路由并启用外部调试集成的示例,按实际需要合并到 .agents/rules/workflow.json:
{
"schemaVersion": 1,
"routing": {
"schemaVersion": 1,
"routes": {
"small": { "description": "明确的局部低风险修复", "requiredArtifacts": ["prd.md"], "validation": "affected" },
"infra": { "description": "文档、工具与配置;核对实际运行影响", "requiredArtifacts": ["prd.md"], "validation": "impact" },
"debug": { "description": "Web 问题复现、归因及修复", "requiredArtifacts": ["prd.md"], "validation": "regression" }
}
},
"plugins": { "enable": ["debug"] },
"debug": { "schemaVersion": 1, "nous": true, "zendao": true, "lark": true }
}路由不可设置审批豁免或 validation=none。requiredArtifacts 只允许现有规划产物且必须包含 PRD。standard/foundation 以及升级为人工方案的任务,保留 planning.json.required 和模板;没有业务配置时使用一份包含设计、范围与验收的 PRD。路由与规划配置在创建时冻结,后续修改不改变旧任务的要求。插件启用组合在宿主启动时固定。
新任务即使没有 workflow.json/routing 也冻结内置通用路由;业务 routing/planning 仅增强配置。没有 routing 快照的旧任务继续原有流程。不会批量迁移、补写人工批准或覆盖旧会话。新路由任务不可用 legacy downgrade 绕过要求;旧任务不提供在线转换策略,继续使用已有有效批准即可。升级后已运行的进程需要重启才能加载新插件组合。
实施授权
创建并调用 wenext_start 后结合用户目标、仓库条件和已有证据尽早分类;未知项先定向调查。创建时只生成 PRD,保留完整模板快照但不预填无关文档。使用现有工具在 plan 阶段选流程,此时不签发写入权限:
{
"node": "plan",
"routing": {
"route": "small",
"impact": "runtime",
"writePaths": ["src/counter.ts", "test/counter.test.ts"],
"assessment": {
"complexity": "simple", "risk": "low", "factors": [],
"rationale": "已检查 counter 及直接调用方;不改变公共接口或持久化行为",
"selfCheck": "回归测试验证每次只递增一次"
}
}
}填写返回的必需产物后调用 wenext_enter_node {"node":"implement"},自动复用分类并按当前产物申请 policy 权限;人工方案仍需评审和真实批准。事实和 PRD 已就绪时,也可在 implement 携带 routing 一次完成。标准/架构任务按仓库模板生成所需文档;无仓库声明时新路由默认只要求完整 PRD。已有任务继续被冻结的要求。
产物不足时返回缺失文件;补齐后重复同一请求。满足低风险条件时签发绑定目标/范围/策略的 policy 证据,approvedBy 保持 null。standard/foundation、非低风险、复杂或未知影响、风险因素、整个仓库范围、强制 plan.review 均进入完整方案和真实人工批准。重复有效请求幂等。
原生写入、实施前准备、范围修改、check、恢复和归档共享执行资格。Shell 仍使用原生执行器;工作流不是 OS 沙箱。policy 不能认领已有外部修改、覆盖冲突或授权整个仓库。相同目标的必要范围增加使用 wenext_scope approve,保留 external 归属;新目标/风险升级重新选择需要 human 的方案并批准。
授权后的决策作为执行证据冻结。标签更正可记录在研究说明中,继续原授权,不因改名重走审批。需要改变执行要求时才选择新方案。研究、调试 Findings、运行记录不影响正式计划摘要;PRD 或选中的正式方案修改会使旧授权失效。没有选路由或有效授权的任务不能通过直接 finish 获得执行资格。
调试的领域流程
plugins/debug 拥有来源、阶段、顺序和完成规则。当前复用业务仓 .agents/skills/domains/nous-debug-eval/scripts/ 和 zendao-debug/scripts/ 中的领域工具;启用对应集成时必须提供它们及 Python 3/外部 CLI。基座不解释 Nous/禅道/飞书状态。
- 普通问题进入
wenext_enter_node debug;明确禅道输入先调用wenext_plugin {plugin:"debug",action:"initialize",input:{source:"zendao",bugId:123}}。插件保存来源及首次现场;外部操作在该任务首次使用时请求一次真实 UI 授权。未启用集成可只做本地诊断。 status返回下一步。resolve_local接受localChanges、单行短evidence(业务脚本要求最多 160 字)和可选测试分支branch。脏工作区不等于直接因果;生产/测试问题不得归因为本地改动。query启动托管 Nous 查询。普通来源传原问题question,禅道来源使用冻结快照。输入摘要、run ID 和目录持久化,不返回答案。调用后可并行独立诊断/修复;已确认本地直接因果由领域工具产生 skipped 审计。- 选择 debug 路由进入实施。已初始化且启用 Nous 的调试任务必须先完成归因和查询绑定;换成 small 等标签也不能跳过。写
research/debug-findings.md的复现、根因、修复、验证章节,执行真实wenext_check。 wait短等待查询完成。freeze验证当前 Findings 和质量证据,引用 business-tests 公开 request/output,冻结独立结论。此后才读取 Nous 答案并完成evaluation.md。查询不可用也保留实际失败审计,不能伪装成功。feedback调用业务飞书记录器;按 run ID 幂等创建/更新,验证回执 record ID 及四份材料摘要。用户要求归档后,wenext_finish审计检查、冻结、评测和反馈。自动检查成功不代表已经归档。
仅使用本地诊断
不使用外部系统时,将上述配置的 debug 部分设为:
{ "schemaVersion": 1, "nous": false, "zendao": false, "lark": false }仍需在 plugins.enable 中启用 debug。外部集成关闭后可以执行本地复现、根因调查、修复与回归;不要发起依赖已关闭集成的动作。启用集成也不会自动安装业务脚本、Python 或外部 CLI。外部集成字段省略时默认为 false;lark: true 依赖 nous: true。
恢复与持久化
领域状态保存在 <task>/plugins/debug/state.json,评测仍位于 evaluations/nous/<runId>。重启后 recover 可采纳已落盘的终态;无终态不会静默重发。明确 retry:true、原因和真实 UI 同意后才创建新请求,旧 run 保留。来源不可被后来的 initialize 重新绑定。插件禁用/状态损坏会明确阻断已有任务,而非删除义务。legacy debugVisitedAt 仍审计 Findings;发现旧 Nous 目录需初始化插件后恢复评测。
按影响选择检查
检查由实际变更决定,路由标签不是 skip 开关。quality-web 可声明:
{ "webQuality": { "schemaVersion": 1,
"runtimePaths": ["src", "packages", "package.json", "docs/generated"],
"nonRuntimePaths": ["docs"], "nonRuntimeFiles": ["AGENTS.md"] } }runtimePaths 和 nonRuntimePaths 为相对路径前缀;nonRuntimeFiles 为精确文件。运行范围优先于非运行范围。插件识别仓库根实际存在的 README/CHANGELOG/LICENSE/NOTICE 常见大小写名称;目录与运行例外仍由仓库声明,不按任意 .md 后缀免测。范围完整且只含已声明非运行路径、或真实无改动时,business-tests 为 not_applicable;有未知路径或范围不完整则在工具准备前阻断,先调查影响。混合变更必须全部已映射,不能用一个已知运行文件掩盖其它未知文件。
通用质量声明对应 when.impactPaths={runtimePaths,nonRuntimePaths,nonRuntimeFiles},与旧 changedPaths/unlessOnlyChangedFiles 互斥;旧条件保持兼容。先选择检查,按需执行插件 prepareChecks 和仓库 preparation.whenChecks,再冻结实际执行计划。quality-web 首次被选中才查询/安装工具并固定本进程版本。文档验证由仓库另外声明,全部检查不适用时仍返回 unverified;跳过业务测试不等于业务测试通过。
路由 validation 决定验收指导目标:affected 针对变化及直接协作者,regression 关注复现和回归,impact 关注工具/流程实际影响,acceptance 对齐完整方案及阶段验证。实际自动化检查由真实范围和仓库/插件映射决定,路由不取消必需检查。policy 路由归档要求 outcome、checkEvidence 和 check 节点,复用真实质量/范围/插件门禁;不强制 workspaceNote/specDecision。显式更新规范仍校验路径和内容,工作记录默认使用 outcome。
路由结果与错误处理
| 情况 | 行为 |
|---|---|
| 尚未分类 | planning 状态先提示 wenext_start;启动后 nextAction 指向 plan 携带 routing,不提示补齐完整方案 |
| plan 中选 small | 只选择必需产物,不授权、不准备工具、不启动外部调试集成 |
| standard/foundation | 保留完整仓库原模板及人工方案批准 |
| 文档或只读范围完整 | 业务检查不适用,仍执行声明的静态/产物检查 |
| docs 下的运行例外 | 运行规则优先,必要测试继续执行 |
| 未映射/不完整范围 | 明确影响缺口,无业务工具初始化和盲目全仓执行 |
| 应有测试但工具未发现入口 | 保留失败,不能当成不适用 |
| 重新进入同一已授权任务 | 使用冻结决策,不因新版默认说明变化重新授权 |
正确:README quick 只形成必要说明并验证内容;后端/CLI 的 small 修复执行针对性测试;infra 构建变更验证真实构建影响。错误:先生成全部方案再改成 quick,或先升级工具再发现没有适用业务测试。基础路径仍保留单一任务生命周期和真实证据。
无配置目录的任务级检查
wenext_check 可接受 checks: [{id, command: string[], cwd?, timeoutMs?}],用于本次专项验证。只执行本次提供的清单,不累积为长期任务要求;省略时执行仓库和插件检查。命令、输入与结果保存在冻结检查计划中,有效证据可跨重启和归档复用。专项检查不能覆盖仓库/插件同名项;旧 quality/task-checks.json 只作历史保留,不再与插件合并。归档不自动重放失败或失效的专项验证,需明确选择当前验收需要的检查重新执行。没有 Git 仍可执行真实命令,但范围不完整时不依据路径条件宣布检查不适用。
零个成功检查不标作 passed;没有必需验证要求时 attempt 为 unverified,既不计成功也不消耗失败重试预算。启用 requireVerified 仍阻断。指标沿用 v2 的 unknown/not_applicable 枚举;服务端修正旧客户端 passed + checkCount=0 的展示,原始事件不改写。没有路由配置不再隐式启用调试,旧调试任务需保持插件启用。