read-knowledge-impact

read_knowledge 影响审计

生成一份报告，分析 read_knowledge Dosu MCP 对我的 Agent 轨迹造成的影响。

请分析过去 1 个月的历史 Agent 会话，找出 read_knowledge MCP 的亮点和失败案例。

当 read_knowledge 调用中的信息与问题和解决方案相关时，即为亮点。Agent 不必在计划或代码中明确引用该信息。 当 Agent 发现信息会造成干扰或误导时，即为失败案例。

请按以下格式列出每个亮点和失败案例：

• task -> Agent 正在处理的任务
• knowledge -> 提供的信息
• impact -> 造成的影响

请生成一份 HTML 报告。

产品

1. 检查本地 Agent 日志（默认：过去 30 天，所有项目）。支持 Cursor / Claude / Codex 适配器，以及通用 JSON/JSONL 遍历器（Devin、Continue、Windsurf、DOSU_AGENT_LOG_DIRS，等等）。
2. 提取每次 read_knowledge 调用及其工具结果
3. 判断每次调用：信息是否与问题和解决方案相关（而不是“Agent 是否明确引用了它”）
4. 打开 HTML 报告（generate_impact_report.py --open）

不要调用 write_knowledge。此技能仅用于报告。

会话查看器

每个亮点都必须包含一个查看会话控件，用于在报告中打开内嵌的转录查看器。

查看器必须：

• 显示以亮点对应的 read_knowledge 调用为中心、范围受限的时间顺序窗口。
• 以视觉方式标记并区分：
  1. 用户的任务
  2. 发送给 Dosu 的查询
  3. Dosu 返回的知识
  4. Agent 随后的推理、操作和回答
• 在源日志保留完整结果时，显示经过清理的完整 Dosu 结果。
• 在无法恢复结果时，明确说明“此日志来源中没有结果载荷”；绝不能让人误以为 400 字符的预览就是完整结果。
• 将窗口中的其他工具调用显示为简洁的操作轮次，并提供经过清理、截断的输入和输出预览——仅显示工具名称无法为判断调用提供上下文。若日志记录了 Agent 的推理（思考）轮次，也要包含调用前后的推理内容。
• 使用独立的 HTML 对话框或抽屉，不依赖网络。
• 支持键盘导航、按 Escape 键关闭、清晰易读的代码块，以及用于复制查询和知识结果的按钮。
• 排除系统/开发者指令、机密信息、个人身份信息（PII）和回执 ID；绝不能包含其他工具的完整原始载荷，只能提供范围受限的预览。
• 标明来源和会话，但不要暴露原始文件系统路径。

摘要卡片应保持简洁。转录详情仅放在会话查看器中。

**重新运行：**始终重新提取并重新分类。忽略 /tmp/rk-calls.json、/tmp/rk-findings.json 和任何现有 HTML。即使已有报告，也不要跳过。

不要询问

绝不要询问用户想分析哪个 Agent、日期范围、项目或粒度。默认值如下：

决策	默认值
时间窗口	--days 30
项目	--all-projects（此机器上的所有工作区）
来源	cursor、claude、codex、generic

仅当用户已明确说明时才覆盖默认值（例如“此仓库”“上周”“仅 Claude”）。

• 分类：references/classification.md

工作流

Progress:
- [ ] 0. SKILL_DIR (this SKILL.md’s folder)
- [ ] 1. Extract read_knowledge calls (overwrite /tmp)
- [ ] 2. Classify every call from scratch
- [ ] 3. Write findings JSON
- [ ] 4. Open HTML report → short reply

步骤 0 — 技能目录

SKILL_DIR 是包含此 SKILL.md（即你正在阅读的文件）的目录。确认已加载新的分类器：

test -f "$SKILL_DIR/scripts/extract_read_knowledge.py"
grep -F '"relevant": "Returned information was relevant to the question and solution."' \
  "$SKILL_DIR/scripts/generate_impact_report.py"
grep -F "details class='fold'" "$SKILL_DIR/scripts/generate_impact_report.py"
grep -F "Result payload unavailable in this log source" \
  "$SKILL_DIR/scripts/generate_impact_report.py"

如果任何 grep 失败，请停止——你使用的是过期副本。请使用 dosu-skill 检出目录中的 skills/read-knowledge-impact/。

然后清除之前生成的产物：

rm -f /tmp/rk-calls.json /tmp/rk-findings.json /tmp/read-knowledge-impact.html

步骤 1 — 提取

# Set DAYS from the user's window BEFORE extract. The HTML reads this number.
#   past day / last 24 hours / today → DAYS=1
#   last week → DAYS=7
#   last N days → DAYS=N
#   unspecified → DAYS=30
DAYS=30
python3 "$SKILL_DIR/scripts/extract_read_knowledge.py" \
  --days "$DAYS" --all-projects \
  --out /tmp/rk-calls.json

用户说法	标志
（默认）	--days 30 --all-projects
“this project” / “this repo”	--days 30（移除 --all-projects）
“last N days” / “past day” / “last 24 hours”	--days N（一天使用 --days 1）--all-projects
“Claude only”	--sources claude --days 30 --all-projects

--days 按调用时间筛选（Cursor <timestamp> / Claude timestamp 中的 called_at），而非文件修改时间。今天最后一次更新的长对话不计入上周的调用。

每次调用都包含 id、source、transcript_id、path、query、result_preview、hint（empty / overflow / error / rejected / unknown），以及会话中的首个用户任务；还包含其稳定位置（tool_call_id、line / position）和 session_view：调用周围经过清理、长度受限的对话窗口；如果来源日志保留了完整的 Dosu 结果，则会显示完整结果（result_available）。Cursor JSONL 对话通常不包含工具结果载荷——此时查看器会显示查询和后续上下文，并如实标注结果不可用；如果结果过大，则会尽可能从 agent-tools/*.txt 旁路文件中恢复。

如果提取器输出 calls: 0，仍然打开空报告，然后停止。

步骤 2 — 分类

阅读 references/classification.md。根据对话记录分类，而不是根据之前的 findings 文件。

1. 保留机械提示（empty、overflow、error、rejected），除非对话记录明确表明它们不正确。
2. 对于 hint=unknown，梳理该调用周围的会话内容——先查看调用的 session_view.turns，然后运行 scripts/parse_agent_logs.py --digest <id>，否则阅读 tool_use 附近的 JSONL。
3. 将 outcome 设为以下值之一，且必须完全一致：relevant、off_topic、empty、rejected、overflow、error、distracting。
4. 为每个 relevant 和 distracting 调用填写 task、knowledge、impact；对于能够看出发生了什么的 overflow/error 调用也要填写。使用完整句子——字段内容不要截断在单词中间。报告会将较长内容折叠在“更多”后面。不要包含原始提示词或机密信息。

relevant = 返回的信息与问题和解决方案相关。Agent 无须明确引用该信息。如果 Agent 也搜索或阅读了代码，仍标记为 relevant。

off_topic = 返回了结果，但与此问题或解决方案无关。

distracting = 结果将 Agent 引向错误方向、与代码库矛盾，或掩盖了真正的答案。

绝不要使用 unused。与主题相关但未被明确引用的返回结果，仍标记为 relevant。

步骤 3 — Findings 文件

将 { "window": …, "calls": [ … ] } 写入 /tmp/rk-findings.json。从 /tmp/rk-calls.json 原样复制 window（这样 HTML 才能识别时间范围是 1 天还是 30 天）。每次调用都应包含提取器行中的字段，并加上 outcome / task / knowledge / impact。保留提取器字段——尤其要原样保留 session_view（可以移除泄露敏感信息的轮次，但绝不能添加或改写轮次）。每个 relevant 调用都必须保留其 session_view；报告生成器不会为缺少可用查看器的内容生成重点摘要。对每次调用都进行分类——不要抽样。

不要设置 outcome_notes。Outcomes 表格中的文本由 generate_impact_report.py 提供。relevant 行必须完全写为：“Returned information was relevant to the question and solution.”

步骤 4 — 报告

python3 "$SKILL_DIR/scripts/generate_impact_report.py" \
  --findings /tmp/rk-findings.json \
  --out /tmp/read-knowledge-impact.html --open

生成器会检查每个重点摘要是否都有可用的 Review session 查看器（即包含轮次的 session_view），否则会报错退出——请修正 findings，不要移除该字段。

Off-topic、empty 和 rejected 调用不会被隐藏：它们会显示在底部折叠的 No effect 部分中，每项都有自己的 Review session 查看器，因此可以像审查重点摘要一样审查无效果标签。

回复关键数字（调用数、相关调用占比、重点摘要数量、失败数量），并说明 HTML 已打开。不要把所有卡片都粘贴到聊天中。

防护措施

• 切勿将密钥 / 个人身份信息（PII）/ 原始日志转储写入报告。
• 切勿编造提取器未找到的调用。
• 切勿因为会话是采集会话、子 Agent 或“已分类”而跳过调用。
• 切勿重复使用之前的 /tmp/rk-findings.json — 始终根据提取器输出对本次运行进行分类。
• 面向用户的输出是 HTML 报告 + 简短的数字摘要。