llm-intelligence/reports/openclaw/OPENCLAW_CAPABILITY_BACKLOG.md

OpenClaw Capability Backlog

本文件用于持续沉淀 OpenClaw 在 llm-intelligence 项目推进和自我优化过程中暴露出的能力缺口。

记录原则：

• 只写真实 review 暴露的问题
• 每个问题都要说明影响
• 每个建议都要可执行、可验证

---

Review 日志

2026-05-07 22:50（第 1 次 review）

问题 1：验证器依赖 rg（ripgrep）但未声明为前置依赖

• 问题描述：verification_executor.go 的 T-1.1 和 T-3.2 验证命令使用 rg -n "Phase 1|非目标|验收标准"，但执行环境中未安装 ripgrep，导致 exit status 127 而非业务逻辑失败。这将两个真实 PASS 的任务错误标记为 FAIL。
• 问题影响：严重误导任务状态。T-1.1（Phase 1 范围冻结）和 T-3.2（Dashboard 最小组件）实际上功能存在且通过脚本验证（verify_t32.sh 全部 PASS），但 automatic verification_executor 报告为 FAIL。状态可信度归零。
• 优化建议：
  1. 验证命令统一使用 grep -n（POSIX 便携），或检测 rg 不存在时 fallback 到 grep
  2. 验证器启动时应做工具链健全检查（toolchain readiness check），缺失关键工具时输出明确警告而非静默失败
  3. 或者：让验证器记录"工具不可用"的特殊状态，而非归类为 ERROR
• 优先级：P0
• 建议验证方法：go run scripts/verification_executor.go 应在无 rg 环境下仍返回准确状态，不产生误报

问题 2：验证结果退出码设计导致 CI 误判

• 问题描述：验证器在有任何 task ERROR 时整体 exit 1，但 ERROR 并不等于任务失败。exit status 127 是工具缺失信号，不应导致整个验证流程 abort。
• 问题影响：CI 中 make check-fetch-openrouter 会因为工具问题得到非零退出码，但实际业务功能可能是完整的。造成 CI 假阳性。
• 优化建议：验证器应区分：
  • exit 127 → 工具缺失，应 warn 不应 fail
  • exit 1（grep 没匹配）→ 预期证据未找到，才是 FAIL
  • 设计三级状态：PASS / WARN（工具缺失）/ FAIL（业务逻辑不符）
• 优先级：P0
• 建议验证方法：同上

问题 3：session 历史中无法区分"工具错误"和"业务失败"

• 问题描述：当 verification_executor 报 ERROR 时，从外部无法快速定位是命令不存在还是命令执行了但不符合预期。session_history 只显示"exit status 127"，需要额外步骤才能诊断。
• 问题影响：多 session 协作时，子 agent 返回 ERROR 状态时父 agent 无法判断是否需要人工介入。
• 优化建议：
  1. 验证器输出标准化 stderr 格式：[TOOL_MISSING] command not found: rg vs [ASSERT_FAILED] expected evidence not found
  2. 在 sessions_history 中暴露 tool stderr 关键行
• 优先级：P1
• 建议验证方法：模拟 rg 不存在场景，检查错误输出是否包含 [TOOL_MISSING] 前缀

问题 4：cron 任务无主动状态报告机制

• 问题描述：本 review 由 cron 触发，但 cron 任务完成后没有向用户推送结果摘要的机制。review 报告写入了文件，但用户不会主动去看。
• 问题影响：定期 review 变成"静默运行"，用户不知道 review 完成了什么，无法基于结果决策。
• 优化建议：
  1. cron 任务完成后应向 configured channel 推送摘要（Discord / 飞书 / email）
  2. 摘要格式：Review 完成 | 8/10 PASS | 关键 gap: 数据资产空白 | 文件: reports/openclaw/2026-05-07-2250-review.md
  3. 可以复用 HEARTBEAT.md 的推送逻辑
• 优先级：P1
• 建议验证方法：执行 cron 触发 review 后，检查 configured channel 是否在 5 分钟内收到摘要

问题 5：subagent spawn 时没有自动传递当前 workspace 路径

• 问题描述：OPENCLAW_EXECUTION.md 指出本项目的根本问题是"openclaw.json 中 cwd 指向 ai-customer-service 而非本项目"。虽然本项目已有本地 TASKS.md，但 subagent spawn 时仍未验证 cwd 是否正确。
• 问题影响：subagent 会用错误的 cwd 读取任务、写入文件，导致数据散落在错误目录。
• 优化建议：
  1. sessions_spawn 时自动注入 cwd 参数（已支持但需要显式传递）
  2. 或在 workspace 根目录检测 .openclaw/openclaw.json 的 cwd 是否匹配当前路径，不匹配时 warn
  3. 提供 openclaw config validate-workspace 命令检查 cwd 一致性
• 优先级：P1
• 建议验证方法：openclaw config validate-workspace 在 cwd 不匹配时输出警告

2026-05-08 09:05（第 2 次 review）

问题 1：验证器 rg 依赖未修复，持续误导任务状态

• 问题描述：verification_executor.go 的 T-1.1 和 T-3.2 验证命令继续使用 rg，执行环境未安装 ripgrep，导致连续两次 review 均报告 exit status 127。手动验收脚本（verify_t32.sh ~ verify_t35.sh，使用 grep）全部 PASS，证明业务功能完整，但自动验证器持续误报。
• 问题影响：任务状态可信度连续受损。父 agent 或 cron 触发 review 时，看到 8/10 FAIL 会误以为有真实业务缺口，可能触发不必要的修复子任务。
• 优化建议：
  1. 立即：将 TASKS.md 中的 rg 命令替换为 grep -n（POSIX 便携，无需安装）
  2. 短期：验证器增加 toolchain readiness check，启动时检测 rg / grep / python3 等前置工具，缺失时输出 [TOOL_MISSING] 而非 ERROR
  3. 中期：设计三级状态 PASS / WARN（工具缺失）/ FAIL（业务不符），让 CI 和 review 能区分工具问题和业务问题
• 优先级：P0（连续两次 review 均受影响）
• 建议验证方法：go run scripts/verification_executor.go 在无 rg 环境下应返回 10/10 PASS 或正确的 WARN 状态

问题 2：验收脚本无法检测"项目是否能构建"

• 问题描述：verify_t32.sh ~ verify_t35.sh 只能检查代码内容（grep 特定字符串），无法验证前端项目是否能真实编译。当前 frontend/ 无 package.json、tsconfig.json、构建脚本，Explorer.tsx 逻辑正确但整个前端是不可构建的代码片段。
• 问题影响：验收脚本全绿给人"前端已完成"的错觉，实际上没有构建系统就无法运行和部署。文档与实现的不一致被验收脚本掩盖。
• 优化建议：
  1. 验收脚本分层：L1（代码存在，当前）+ L2（可编译/可运行，新增）
  2. 对前端项目，L2 验收应执行 npm install && npm run build（或 tsc --noEmit）
  3. 对 Go 项目，L2 验收应执行 go build 和 go test
  4. 在 TASKS.md 的 verification 中增加 build_test mode，与 artifact_present 并列
• 优先级：P1
• 建议验证方法：为 T-3.x 任务增加 mode: build_test，执行 cd frontend && npm run build，失败时明确报告"构建失败"而非"文件不存在"

问题 3：环境变量/API Key 缺失未在 review 流程中自动检测

• 问题描述：本次 review 发现 OPENROUTER_API_KEY 未设置，导致采集器只能回退到 2 条种子数据。但 review 流程中没有自动检查关键环境变量的步骤，这个问题是人工排查 exec 输出时偶然发现的。
• 问题影响：数据链路的核心瓶颈（缺 API Key）可能被遗漏，review 报告会反复指出"数据资产空白"但给不出根因和修复路径。
• 优化建议：
  1. 在 OPENCLAW_MULTI_REVIEW_PROMPT.md 中增加"环境变量检查"步骤：列出项目依赖的关键 env（如 OPENROUTER_API_KEY、DATABASE_URL），检查是否已配置
  2. 或者在 TASKS.md 中增加环境型任务（如 T-5.1 API Key 配置），用 artifact_present 模式检查 .env 文件或环境变量导出
  3. 如果 Key 未配置，review 报告应在 gap 中明确写出"根因：OPENROUTER_API_KEY 未设置，建议配置后重新验证"
• 优先级：P1
• 建议验证方法：review 流程中自动执行 printenv | grep OPENROUTER_API_KEY || echo 未设置，未设置时在报告中标记为 gap 并给出配置指引

问题 4：文件修改后未触发 commit 提示的机制仍然缺失

• 问题描述：PRD.md 的 Phase 1 范围/非目标/验收标准在 2026-05-04 或更早已写入，但至今（2026-05-08）仍处于 unstaged 状态。同时 git status 显示 17 个未跟踪文件。
• 问题影响：开发状态碎片化，用户不知道哪些文件需要 commit。4 天无 commit 意味着项目看起来"停滞"，即使实际有代码产出。
• 优化建议：
  1. review 流程检测到"最后提交 > 48h 且存在 unstaged/untracked 文件"时，在 Executive Summary 顶部加红色警告横幅
  2. 或者在最终回复中主动提示：git add PRD.md && git commit -m "docs: 补充 Phase 1 范围与验收标准"
  3. 长期：提供 openclaw git snapshot 命令，自动 review → 提示 commit → 用户确认后执行
• 优先级：P2
• 建议验证方法：在存在 48h+ 未提交文件的项目上运行 review，检查报告是否包含明确的 commit 提示

2026-05-08 09:12（第 3 次 review）

前置说明：距上一次 review（09:05）仅 7 分钟，仓库状态零变化。本次 review 所有 prior backlog 条目（问题 1~4）仍然全部未修复，继续有效。以下仅记录本次 review 暴露出的新增流程层面问题。

问题 5：cron 驱动 review 在仓库无 delta 时产生空转，浪费 token 与注意力

• 问题描述：cron 按固定时间间隔（如 7 分钟）触发 review，但 git 无新 commit、无文件变更、无环境变化时，review 产出与上一次 100% 相同的结论。本次 09:12 review 与 09:05 review 的 diff 仅为时间戳。
• 问题影响：
  1. Token 浪费：两次 review 读取、分析、写盘的计算量完全重复，对调用方产生无价值成本
  2. 注意力稀释：用户/父 agent 收到两份几乎一样的报告，难以快速判断是否有新进展，导致"狼来了"效应
  3. 行动噪音：如果 review 后自动触发修复子任务，会导致重复任务 spawn，甚至多个子 agent 竞争同一资源
• 优化建议：
  1. 立即：在 OPENCLAW_MULTI_REVIEW_PROMPT.md 中增加"delta gate"步骤——执行全量 review 前，先检查 git log --since="上次 review 时间" 和 git status --short，如无变化则输出极简摘要并跳过全量分析
  2. 短期：为 review 流程增加状态指纹（hash of git HEAD + env keys + key file mtimes），指纹未变时直接引用上次结论
  3. 中期：提供 openclaw review --skip-if-unchanged 参数，让 cron 任务在配置中声明"仅在有变更时触发全量 review"
• 优先级：P1
• 建议验证方法：在同一仓库 7 分钟内触发两次 review，第二次应输出极简摘要（如"状态未变，引用 reports/openclaw/2026-05-08-0905-review.md"），而非重复生成 5000+ 字节的全量报告

2026-05-08 09:36（第 4 次 review）

前置说明：距上一次 review（09:12）24 分钟，仓库状态零变化。今日已累计触发 3 次 review（09:05、09:12、09:36），结论 100% 相同。所有 prior backlog 条目（问题 1~5）仍然全部未修复，继续有效。本次不新增独立 backlog 条目，仅做以下累积影响更新与确认。**

问题 1（P0）累积确认：rg 依赖持续误报 ×3

• 09:36 状态：rg 仍未安装，verification_executor.go 继续 8/10 FAIL。连续 3 次 review 均受此问题影响。
• 累积影响量化：3 次 review 中均需要人工/自动判断"T-1.1 / T-3.2 是真实 FAIL 还是工具误报"，每次约消耗 200-300 token 的额外诊断注意力。总计 >600 token 注意力浪费。
• 行动状态：零修复动作。建议立即降级为"今日必须修复"。

问题 5（P1）累积确认：cron 空转 ×3

• 09:36 状态：今日第 3 次空转 review 已发生。
• 累积影响量化：
  • 3 次 review 均读取了 TASKS.md（~150 行）、GOALS.md、OPENCLAW_EXECUTION.md、多次 git status、4 个手动验收脚本、db migration、前端源码等
  • 预估每次全量 review 消耗 5k-8k token（读取 + 分析 + 写盘）
  • 今日累计空转 token 浪费：15k-24k，产出为零
  • 同时产生 3 份文件（~5KB+5KB+5KB=15KB 磁盘），对文件系统造成噪音
• 行动状态：零修复动作。建议将 delta gate 纳入 prompt 立即执行。

问题 3（P1）累积确认：环境变量检测缺失

• 09:36 状态：OPENROUTER_API_KEY 仍未配置。review 流程中已手动加入 printenv | grep OPENROUTER_API_KEY 检查，但此步骤依赖 reviewer 记忆，未固化到 OPENCLAW_MULTI_REVIEW_PROMPT.md 的标准步骤中。
• 建议：立即将"环境变量检查"写入 prompt 的"必须先检查"列表，使其成为自动化步骤。

---

当前未修复问题速查表（截至 2026-05-08 09:36）

#	问题	优先级	首次暴露	修复状态	影响次数
1	验证器 rg 依赖误报	P0	05-07 22:50	❌ 未修复	4 次 review
2	验证器退出码设计	P0	05-07 22:50	❌ 未修复	4 次 review
3	session 历史工具/业务错误区分	P1	05-07 22:50	❌ 未修复	4 次 review
4	cron 无主动状态报告机制	P1	05-07 22:50	❌ 未修复	4 次 review
5	subagent spawn 未传递 workspace	P1	05-07 22:50	❌ 未修复	4 次 review
6	验收脚本无法检测构建	P1	05-08 09:05	❌ 未修复	3 次 review
7	环境变量/API Key 缺失未自动检测	P1	05-08 09:05	⚠️ 部分（手工检查）	3 次 review
8	文件修改后未触发 commit 提示	P2	05-08 09:05	❌ 未修复	3 次 review
9	cron review 无 delta 时空转	P1	05-08 09:12	❌ 未修复	2 次 review（09:12、09:36）

---

Backlog 最后更新：2026-05-08 09:36 Asia/Shanghai