故障排查
先核对启动目录、当前任务和实际配置,再排查对应执行结果。任务状态和质量证据以本地记录为准;仪表盘是观测结果,不参与任务授权。
| 现象 | 排查方向 |
|---|---|
| 简单 README 修改仍要求完整方案 | 检查任务是否为无路由快照的旧任务、风险是否升级、是否强制 plan.review;新任务默认支持路由,路由应在生成完整方案前选择 |
| README 修改仍安装业务测试工具 | 检查非运行路径是否明确,以及仓库 startup 是否自行安装依赖;quality-web 应在选中业务检查后才准备 |
| 应做业务测试却没找到包 | 核对仓库测试入口与工具报告,不能将入口识别失败改成 not_applicable |
| 重启后找不到任务 | 先核对启动根和 WENEXT_PI_HOME,用 projects 查任务路径,再显式指定任务 ID |
| 锁冲突或另一个会话正在写 | 确认占用进程是否仍活着;正常退出旧进程再恢复,不通过删除活锁强制并发 |
/model 无可用模型 | 核对登录状态、models.json 语法、模型服务提供方声明及启动进程环境变量 |
| 切换节点但实际模型没变 | 节点绑定是上下文声明;实际主模型通过 /model 选择,观测值取真实响应 |
| 仪表盘没有数据 | 检查 /wenext-metrics 实际服务器与错误、当前队列 ACK、API/数据库、页面 apiBaseUrl、周与过滤条件;doctor 的旧 outbox 数量不能证明 v2 已入库 |
| flush 成功却看不到旧任务 | 检查是否更换过目的地址、是否旧 v1 数据,或历史本就未采集;flush 不补造历史 |
| 任务耗时不符合体感 | 区分执行、阶段停留和生命周期;核对客户端/服务端版本及缺失数据提示 |
| 检查通过但未归档 | 正常:自动化检查、需求验收与用户要求归档是不同步骤 |
诊断入口
bash
wenext-pi --version
wenext-pi projects --json
wenext-pi doctor --root /path/to/project会话内可用 /wenext-metrics 查看上报状态,让智能体使用 wenext_current 查看任务、wenext_scope 查看范围、wenext_retry 查看失败历史。doctor 会准备状态并可能迁移旧记录;projects 是只读查询。
.coordination 是内部锁目录,不是任务。任务发现只识别含有 task.json 的普通任务目录。保留损坏记录和错误信息;不要删除任务、证据或活进程锁来绕过错误。迁移冲突见存储与迁移,上报链路见指标指南。
历史任务报检查名称重复
若旧任务归档时报 Quality check id must be unique...,可能是 AI 曾保存的任务检查(例如 business-tests)与当前插件内置检查同名。新版不再将历史 quality/task-checks.json 合并为永久门禁,保留该文件及历史执行证据即可。
升级并恢复原任务后,按当前验收需要执行 wenext_check:仓库与插件检查自动加入,专项命令通过本次 checks 参数提供;插件已经负责的同一验证无需重复声明。检查通过后再归档。若是新调用中的 ID 与当前仓库/插件重复,错误会指出具体 ID;不同的专项验证使用不同名称,不能用同名命令覆盖必要检查。