read-knowledge-impact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

read_knowledge impact audit

read_knowledge 影响审计

Create a report on the impact of the read_knowledge Dosu MCP on my agent trajectories.

Please analyze my historic agent sessions over the past 1-month and identify both highlights and failures of the read_knowledge MCP.

A highlight is when the information from the read_knowledge call was relevant to the question and solution. The agent does not have to uniquely cite it in plan or code. A failure is when the agent found the information distracting or misleading.

For each highlight and failure, format it as

task -> what the agent was working on
knowledge -> what information was surfaced
impact -> what impact it had

Write an HTML report with the results.

生成一份关于Dosu MCP的read_knowledge对我的Agent轨迹影响的报告。

请分析我过去1个月的历史Agent会话，识别read_knowledge MCP的亮点与失败案例。

亮点指read_knowledge调用返回的信息与问题及解决方案相关。Agent无需在计划或代码中专门引用该信息。失败指Agent认为信息分散注意力或具有误导性。

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

task -> Agent当时正在处理的任务
knowledge -> 呈现的信息内容
impact -> 产生的影响

将结果写入HTML报告。

Product

产品功能

Inventory local agent logs (default: past 30 days, all projects). Cursor / Claude / Codex adapters plus a generic JSON/JSONL walker (Devin, Continue, Windsurf,
```
DOSU_AGENT_LOG_DIRS
```
, …).
Extract every
```
read_knowledge
```
call and its tool result
Judge each call: was the information relevant to the question and solution (not “did the agent uniquely cite it”)
Open the HTML report (
```
generate_impact_report.py --open
```
)

Do not call

write_knowledge

. This skill only reports.

盘点本地Agent日志（默认：过去30天，所有项目）。支持Cursor / Claude / Codex适配器，以及通用JSON/JSONL遍历器（Devin、Continue、Windsurf、
```
DOSU_AGENT_LOG_DIRS
```
等）。
提取所有
```
read_knowledge
```
调用及其工具结果
评估每个调用：返回的信息是否与问题及解决方案相关（而非“Agent是否专门引用了它”）
打开HTML报告（
```
generate_impact_report.py --open
```
）

请勿调用

write_knowledge

。本技能仅用于生成报告。

Session viewer

会话查看器

Every highlight must include a Review session control that opens an inline transcript viewer inside the report.

The viewer must:

Show a chronological, bounded window around the highlighted
```
read_knowledge
```
call.
Visually pin and distinguish:
1. the user's task,
2. the query sent to Dosu,
3. the knowledge Dosu returned,
4. the agent's subsequent reasoning, actions, and answer.
Show the complete sanitized Dosu result when the source log preserved it.
Clearly say "Result payload unavailable in this log source" when it cannot be recovered; never imply the 400-character preview is complete.
Show the agent's other tool calls in the window as compact action turns with sanitized, truncated input and output previews — a bare tool name gives no context for judging the call. Include the agent's reasoning (thinking) turns before and after the call when the log records them.
Use a self-contained HTML dialog or drawer with no network dependency.
Support keyboard navigation, Escape-to-close, readable code blocks, and copy buttons for the query and knowledge result.
Exclude system/developer instructions, secrets, PII, and receipt IDs; never include full raw payloads of other tools — bounded previews only.
Identify the source and session, but do not expose raw filesystem paths.

The summary card remains concise. Transcript detail belongs only in the session viewer.

Fresh run: always re-extract and re-classify. Ignore

/tmp/rk-calls.json

/tmp/rk-findings.json

, and any existing HTML. Do not skip because a previous report exists.

每个亮点必须包含一个查看会话控件，可在报告内打开嵌入式对话查看器。

查看器必须满足以下要求：

显示高亮的
```
read_knowledge
```
调用前后的按时间顺序排列的有限窗口内容。
视觉上标记并区分以下内容：
1. 用户的任务，
2. 发送给Dosu的查询，
3. Dosu返回的知识，
4. Agent后续的推理、操作和回答。
当源日志保留完整结果时，显示完整的脱敏Dosu结果。
当无法恢复结果时，明确显示“此日志源中无可用结果负载”；绝不能暗示400字符预览是完整内容。
将窗口内Agent的其他工具调用显示为紧凑的操作项，包含脱敏、截断的输入和输出预览——仅显示工具名称无法为判断调用提供上下文。当日志记录了调用前后的Agent推理（思考）过程时，需包含这些内容。
使用独立的HTML对话框或侧边栏，无网络依赖。
支持键盘导航、按Esc关闭、易读的代码块，以及查询和知识结果的复制按钮。
排除系统/开发者指令、机密信息、个人身份信息（PII）和收据ID；绝不包含其他工具的完整原始负载——仅显示有限预览。
标识来源和会话，但不暴露原始文件系统路径。

摘要卡片需保持简洁。对话详情仅在会话查看器中展示。

全新运行： 始终重新提取并重新分类。忽略

/tmp/rk-calls.json

、

/tmp/rk-findings.json

和任何现有HTML文件。即使存在之前的报告，也请勿跳过步骤。

Do not ask

无需询问

Never ask which agent, date range, project, or granularity. Defaults:

Decision	Default
Window	`--days 30`
Projects	`--all-projects` (every workspace on this machine)
Sources	cursor, claude, codex, generic

Override only when the user already said so (“this repo”, “last week”, “Claude only”).

Classification: references/classification.md

永远不要询问Agent类型、日期范围、项目或粒度。默认设置如下：

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

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

分类规则：references/classification.md

Workflow

工作流程

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

Progress:
- [ ] 0. SKILL_DIR（本SKILL.md所在的文件夹）
- [ ] 1. 提取read_knowledge调用（覆盖/tmp目录下的文件）
- [ ] 2. 从头开始分类每个调用
- [ ] 3. 写入结果JSON文件
- [ ] 4. 打开HTML报告 → 简短回复

Step 0 — Skill dir

步骤0 — 技能目录

SKILL_DIR

is the directory that contains this

SKILL.md

(the file you are reading now). Confirm the new classifier is loaded:

bash

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"

If any grep fails, stop — you have a stale copy. Use the

dosu-skill

checkout at

skills/read-knowledge-impact/

Then clear previous artifacts:

bash

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

SKILL_DIR

是包含本

SKILL.md

（即您正在阅读的文件）的目录。确认已加载新的分类器：

bash

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命令失败，请停止操作——您使用的是旧版本。请使用

skills/read-knowledge-impact/

路径下的

dosu-skill

检出版本。

然后清除之前的产物：

bash

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

Step 1 — Extract

步骤1 — 提取

bash

undefined

bash

undefined

Set DAYS from the user's window BEFORE extract. The HTML reads this number.

在提取前根据用户指定的时间窗口设置DAYS。HTML报告将读取此数值。

past day / last 24 hours / today → DAYS=1

last week → DAYS=7

last N days → DAYS=N

unspecified → DAYS=30

未指定 → DAYS=30

DAYS=30 python3 "$SKILL_DIR/scripts/extract_read_knowledge.py"
--days "$DAYS" --all-projects
--out /tmp/rk-calls.json


| User says | Flags |
|-----------|--------|
| (default) | `--days 30 --all-projects` |
| "this project" / "this repo" | `--days 30` (drop `--all-projects`) |
| "last N days" / "past day" / "last 24 hours" | `--days N` (`--days 1` for a day) `--all-projects` |
| "Claude only" | `--sources claude --days 30 --all-projects` |

`--days` filters by **call time** (`called_at` from Cursor `<timestamp>` / Claude `timestamp`), not file mtime. A long chat last-touched today does not count last week's calls.

Each call has `id`, `source`, `transcript_id`, `path`, `query`, `result_preview`, `hint` (`empty` / `overflow` / `error` / `rejected` / `unknown`), and the session’s first user task — plus its stable location (`tool_call_id`, `line` / `position`) and a `session_view`: a sanitized, bounded transcript window around the call with the complete Dosu result when the source log preserved it (`result_available`). Cursor JSONL transcripts generally omit tool-result payloads — the viewer then shows the query and downstream context with an honest unavailable-result state; oversized results are recovered from `agent-tools/*.txt` sidecars when possible.

If the extractor prints `calls: 0`, open an empty report anyway and stop.

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`），而非文件修改时间。今天最后一次访问的长对话不会包含上周的调用记录。

每个调用包含`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`，仍需打开空报告并停止操作。

Step 2 — Classify

步骤2 — 分类

Read references/classification.md. Classify from the transcripts, not from a previous findings file.

Keep mechanical hints (
```
empty
```
,
```
overflow
```
,
```
error
```
,
```
rejected
```
) unless the transcript clearly contradicts them.
For
```
hint=unknown
```
, digest the session around that call — start from the call's
```
session_view.turns
```
, then
```
parse_agent_logs.py --digest <id>
```
from the sibling
```
log-to-dosu-knowledge
```
skill if present, otherwise read the JSONL near the tool_use.

Set

outcome

to exactly one of:

relevant

off_topic

empty

rejected

overflow

error

distracting

Fill
```
task
```
,
```
knowledge
```
,
```
impact
```
for every
```
relevant
```
and
```
distracting
```
call, and for overflow/error when you can see what happened. Complete sentences — never cut a field mid-word. The report folds long copy behind “more”. No raw prompts, no secrets.

relevant

= the returned information was relevant to the question and solution. The agent does not have to uniquely cite it. If they also grepped or read code, still mark

relevant

off_topic

= a result came back but it was not about this question or solution.

distracting

= the result sent the agent the wrong way, contradicted the codebase, or crowded out the real answer.

Never use

unused

. On-topic returns that were not uniquely quoted are

relevant

阅读references/classification.md。根据对话记录进行分类，而非之前的结果文件。

保留机械提示（
```
empty
```
、
```
overflow
```
、
```
error
```
、
```
rejected
```
），除非对话记录明确与之矛盾。
对于
```
hint=unknown
```
，梳理该调用周围的会话内容——从调用的
```
session_view.turns
```
开始，若存在同级的
```
log-to-dosu-knowledge
```
技能，则使用
```
parse_agent_logs.py --digest <id>
```
，否则查看工具调用附近的JSONL内容。

将

outcome

精确设置为以下值之一：

relevant

、

off_topic

、

empty

、

rejected

、

overflow

、

error

、

distracting

。

为所有
```
relevant
```
和
```
distracting
```
调用，以及能明确情况的overflow/error调用填写
```
task
```
、
```
knowledge
```
、
```
impact
```
。使用完整句子——绝不要中途截断字段内容。报告会将长文本折叠在“更多”按钮后。请勿包含原始提示或机密信息。

relevant

= 返回的信息与问题及解决方案相关。Agent无需专门引用该信息。即使Agent同时使用了grep或读取了代码，仍标记为

relevant

。

off_topic

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

distracting

= 结果引导Agent走向错误方向、与代码库矛盾，或掩盖了真实答案。

请勿使用

unused

。未被专门引用的相关返回仍标记为

relevant

。

Step 3 — Findings file

步骤3 — 结果文件

Write

/tmp/rk-findings.json

{ "window": …, "calls": [ … ] }

. Copy

window

from

/tmp/rk-calls.json

unchanged (that is how the HTML knows it was 1 day vs 30). Each call is the extractor row plus

outcome

task

knowledge

impact

. Keep extractor fields — in particular carry

session_view

through unchanged (you may drop a turn that leaked something sensitive, never add or rewrite turns). Every

relevant

call must keep its

session_view

; the report generator refuses to build a highlight without a working viewer. Classify every call — do not sample.

Do not set

outcome_notes

. The Outcomes table copy comes from

generate_impact_report.py

. The relevant row must read exactly: "Returned information was relevant to the question and solution."

将

/tmp/rk-findings.json

写入为

{ "window": …, "calls": [ … ] }

格式。原样复制

/tmp/rk-calls.json

中的

window

字段（HTML报告通过此字段判断是1天还是30天的窗口）。每个调用条目是提取器返回的行加上

outcome

task

knowledge

impact

字段。保留提取器的所有字段——尤其要完整保留

session_view

（您可删除泄露敏感信息的对话轮次，但绝不能添加或重写轮次）。所有

relevant

调用必须保留

session_view

；报告生成器会拒绝构建没有可用查看器的亮点。对所有调用进行分类——请勿抽样。

请勿设置

outcome_notes

。结果表格的内容来自

generate_impact_report.py

。

relevant

对应的行必须精确显示："Returned information was relevant to the question and solution."

Step 4 — Report

步骤4 — 生成报告

bash

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

The generator asserts that every highlight has a working Review session viewer (a

session_view

with turns) and exits with an error otherwise — fix the findings, do not strip the field.

Off-topic, empty, and rejected calls are not hidden: they render in a collapsed No effect section at the bottom, each with its own Review session viewer, so a no-effect label can be audited the same way a highlight can.

Reply with the headline numbers (calls, % relevant, highlight count, failure count) and that the HTML is open. Do not paste every card into chat.

bash

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

生成器会检查每个亮点是否有可用的查看会话查看器（即包含对话轮次的

session_view

），否则会报错退出——请修复结果文件，不要删除该字段。

无关、空值和被拒绝的调用不会被隐藏：它们会在底部的折叠无影响部分显示，每个条目都有自己的查看会话查看器，这样无影响标签可以像亮点一样被审计。

回复时只需提供核心数字（调用总数、相关占比、亮点数量、失败数量），并说明HTML报告已打开。请勿将所有卡片内容粘贴到聊天中。

Guardrails

防护规则

Never write secrets / PII / raw log dumps into the report.
Never invent calls that the extractor did not find.
Never skip a call because the session was a harvest, a subagent, or “already classified.”
Never reuse a previous
```
/tmp/rk-findings.json
```
— always classify this run from the extractor output.
User-facing output is the HTML report + a short numeric summary.

绝不要在报告中写入机密信息/PII/原始日志转储。
绝不要编造提取器未找到的调用记录。
绝不要因会话是批量采集、子Agent或“已分类过”而跳过调用。
绝不要复用之前的
```
/tmp/rk-findings.json
```
——始终根据提取器的输出重新分类本次运行。
用户可见的输出是HTML报告 + 简短的数字摘要。