longclaw-checkup

name	longclaw-checkup
description	longClaw 运行时体检与诊断。用于检查 skill 不触发、hook 不生效、DEV LOG 异常、state.db 记账异常、memory 检索退化、配置迁移不完整等问题。Use when the user says 体检、自检、诊断、doctor、status、排查 longClaw、skill 不触发、hook 有问题、sidecar 异常、DEV LOG 乱了.
version	1.0.0
author	jinglong92
license	MIT
requires	["file_read","shell_exec"]

longClaw Checkup

对 longClaw 做“先体检、后深挖”的诊断闭环。 目标不是泛泛 review，而是快速回答三件事：

1. 现在有没有明显异常
2. 异常落在哪一层
3. 下一步最小修复动作是什么

触发条件

硬触发关键词（出现任一即命中）：

• "体检一下" / "自检一下" / "诊断一下"
• "doctor 一下" / "跑下 doctor" / "看看 status"
• "排查 longClaw" / "longClaw 有啥问题"
• "skill 不触发" / "为什么没命中 skill"
• "hook 没生效" / "sidecar 有问题"
• "DEV LOG 乱了" / "路由不对" / "session 不对"
• "memory 检索有问题" / "state.db 有问题"
• 用户发 /checkup / /doctor

软触发（ENGINEER 路由后 CTRL 判断）：

• 用户描述的是运行异常、配置漂移、诊断请求，而不是代码实现需求
• 任务目标是“定位问题在哪一层”，不是立刻改代码

不触发条件

• 用户要改代码、修 bug、补功能：用 research-execution-protocol 或 code-agent
• 用户要接入外部 skill / 仓库并评估风险：用 skill-safety-audit

分层模型

体检时按 5 层排查，不要一上来读一堆文件。

1. L0 总览层

   • 看 doctor 和 status
   • 判断是否已有 FAIL / WARN / 空账本 / 路径异常

2. L1 Skill / 配置层

   • 看 skill registry、skill 目录层级、frontmatter、.claude/settings.json
   • 判断 skill 是否“根本没进 registry”或 hook dispatcher 未接入

3. L2 Sidecar / ledger 层

   • 看 memory/state.db、sessions / route_decisions / tool_events 计数
   • 判断是否是 sidecar 未写入、schema 异常、会话本身是 ephemeral

4. L3 协议 / 注入层

   • 看 AGENTS.md、CTRL_PROTOCOLS.md、DEV_LOG.md、相关 hook 插件
   • 判断是否是协议未重注入、PostCompact 补救失败、DEV LOG 模板漂移

5. L4 定向深挖层

   • 只在前四层发现线索后，才读具体文件 / 日志 / 插件实现

标准流程

Step 1：先跑最便宜的体检

立即执行：

python3 scripts/longclaw-doctor --json
python3 scripts/longclaw-status --json

若命令不可执行，再退回读取：

• runtime_sidecar/doctor/checks.py
• runtime_sidecar/doctor/config_check.py
• runtime_sidecar/state/readers.py

Step 2：按症状决定分支

分支 A：skill 不触发 / 命中异常

优先检查：

• skills/ 目录是否为一层目录
• 目标 skill 的 name / description / requires
• 是否存在 3-5 个硬触发关键词
• 若环境可用，检查 registry 中是否真的有该 skill

重点结论只回答：

• 没进 registry
• 进 registry 但触发词太软
• 命中后不执行
• requires 不满足

分支 B：hook / sidecar / DEV LOG 异常

优先检查：

• .claude/settings.json 是否包含 hook_dispatcher
• runtime_sidecar/plugins/ 对应事件插件是否存在
• memory/state.db 是否存在、是否能写入
• scripts/hooks/ 是否与 sidecar 分发器一致
• DEV_LOG.md 与 hook 注入提醒是否一致

重点结论只回答：

• dispatcher 没接上
• sidecar 写账本失败
• session 是 ephemeral，不是 bug
• PostCompact / SessionStart 注入链断裂

分支 C：memory / recall 异常

优先检查：

• tools/memory_search.py 是否存在
• memory/heartbeat-state.json / memory/session-state.json 是否可解析
• 检索异常是“没索引”还是“embedding provider 不可用”
• 是否应该 fallback 到 read/rg 或 fts-only

重点结论只回答：

• 索引缺失
• embedding 链路失败
• fallback 路径错误
• 其实是预期行为，不是 bug

Step 3：输出最小诊断结论

不要输出散乱观察，统一压成以下格式：

体检结论：<健康 / 有警告 / 有故障>

摘要：
- <一句话总结当前最重要的问题或“未见明显异常”>

分层结果：
- [L0] doctor/status：<PASS/WARN/FAIL + 关键信息>
- [L1] skill/config：<结论>
- [L2] sidecar/ledger：<结论>
- [L3] protocol/injection：<结论>
- [L4] targeted drilldown：<仅在实际深挖时填写>

发现的问题（按严重度）：
- [P0] ...
- [P1] ...
- [P2] ...

下一步最小动作：
1. ...
2. ...
3. ...

执行原则

• 先跑 doctor / status，不要一上来全文 review
• 先回答“哪一层坏了”，再回答“怎么修”
• 若某层已有明确故障，不继续无意义扩大排查范围
• 若当前只是 warning，不要夸大为故障
• 若现象属于预期行为，明确写“预期行为，不是 bug”

longclaw-checkup 负责运行时体检：

• doctor
• status
• hook
• state.db
• skill 发现/命中
• DEV LOG 注入链
• memory 检索退化

一句话心法

先跑现成体检入口，定位故障层，再做最小深挖，不把“review 文档”当成“诊断系统”。