Skip to content

故障排查 ​

文档导航

先核对启动目录、当前任务和实际配置,再排查对应执行结果。任务状态和质量证据以本地记录为准;仪表盘是观测结果,不参与任务授权。

现象排查方向
简单 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;不同的专项验证使用不同名称,不能用同名命令覆盖必要检查。