用途
os-improvement-report 用于对一个智能体循环改进周期（agentic loop improvement cycle）进行可视化与文字汇报。它可作用于任何按规范维护 improvement-ledger.md 和每个技能 results.tsv 的插件。其参考输出为 autoresearch 进度图表：时间线上的绿色 KEEP 点、灰色 DISCARD 点、运行最佳阶梯线，以及标注每项改进内容的注释。该技能为 agentic-os 和 exploration-cycle-plugin 的改进周期生成同样的图表。
主要能力
该技能读取以下内容：
- context/experiment-log/index.md（主要来源）：所有已记录的运行；筛选 result_type: numeric 以获取来自编排器运行的 KEEP/DISCARD/评分数据。
- context/memory/improvement-ledger.md（旧版回退）：由 os-improvement-loop Stage 4.7 写入的评估分数进展；当实验日志中没有数值条目时使用。
- .agents/skills/*/evals/results.tsv（补充）：每个技能的详细评估分数历史。
实验日志是数值结果的统一事实来源。改进台账是为向后兼容旧循环运行而保留的旧格式。
它产出：
- context/memory/reports/progress_YYYYMMDD_HHMM.png：进度图表，包含 KEEP/DISCARD 时间线、运行最佳阶梯线、变更注释。
- context/memory/reports/summary_YYYYMMDD_HHMM.md：文字摘要，包含基线对比最佳、按增量排序的命中项、调查有效性、北极星趋势。
使用方式
执行流程分为几个阶段：
Phase 0：读取实验日志中的数值条目。运行 python3 plugins/agent-agentic-os/scripts/experiment_log.py summary，然后读取 context/experiment-log/index.md 并筛选 Result Type 列为 numeric 的行。对每个匹配行读取其链接的 .md 文件，从其 YAML 头中提取 keeps、discards、baseline、best_score、delta、target、date。使用正则 (\d+)K/(\d+)D baseline=([0-9.]+) best=([0-9.]+) delta=([+-][0-9.]+) 解析 verdict 字符串。若存在至少 1 个数值条目，则以其作为图表的主要数据源；若为 0 个，则进入 Phase 1（旧版台账）。桥接步骤：若使用旧版 generate_report.py 脚本，则将提取的数值数据写入 improvement-ledger.md Section 1 格式。
Phase 1：检查旧版数据可用性（仅作为回退）。检查 ${CLAUDE_PROJECT_DIR}/context/memory/improvement-ledger.md 是否存在；若不存在则提示用户先运行至少一个完整循环周期；若存在但 Section 1 表格为空则告知尚无完成的周期，且不要在空台账上运行报告脚本。
Phase 2：运行报告。命令为 python "${PLUGIN_DIR}/skills/os-improvement-report/scripts/generate_report.py" --project-dir "$PROJECT_DIR" --plugin-dir "$PLUGIN_DIR" [--skill SESSION-MEMORY-MANAGER]（--skill 为可选，用于筛选单个技能）。脚本成功时退出码为 0，并将图表路径和文字摘要打印到 stdout。
Phase 3：呈现输出。向用户报告图表路径，内联打印文字摘要，并询问是否需要打开图表图片或显示每个技能的详细信息。
Phase 4：跨插件报告（可选）。若用户希望同时跟踪 agent-agentic-os 和 exploration-cycle-plugin 的改进，可分别对每个插件各运行一次报告，传入各自的 project dir。两个插件都写入各自项目目录下的 context/memory/improvement-ledger.md，各自生成图表，文字摘要可拼接为组合视图。
安装依赖：该技能需要 Python 3.8+、pandas 和 matplotlib。安装命令：pip-compile ./requirements.in 和 pip install -r ./requirements.txt，依赖锁定文件见 ./requirements.txt。
适用场景
适用于需要跟踪和汇报智能体循环改进进展的场景，包括查看改进图表、了解进步情况、生成进度报告、绘制评估分数图表、查看改进周期等。可针对单个技能筛选报告，也可跨插件组合报告。
限制
该技能依赖项目已存在实验日志或改进台账数据。若实验日志无数值条目且旧版台账不存在，则无法生成报告；若台账存在但 Section 1 表格为空，报告脚本会产生空图表，因此不应在空台账上运行。图表解读方面：阶梯线平坦或下降意味着循环未改善技能；频繁的 DISCARD 簇表示假设质量需要改进；阶梯线陡升表示 survey-to-action 链路正常。添加新插件需：初始化 context/memory/improvement-ledger.md 为三段式格式，每次 KEEP 或 DISCARD 周期后写入 Section 1，当 survey 摩擦项导致变更尝试时写入 Section 2，每会话写入 Section 3 的完成率。generate_report.py 对任何符合该格式的台账都可用。