log-to-dosu-knowledge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Log → Dosu Knowledge

日志 → Dosu知识库

Product (keep it this simple):

Read local agent logs
Decide durable learnings (not the user’s prompt — the answer/gotcha found)
Write each under a synthetic
```
dosu/log-backfill/<UTC-timestamp>
```
branch
(server auto-enqueues notes-upflow for that prefix — same path as a PR merge)
Tell the user what was cached, expected token savings, and the backfill branch
Open the HTML report (
```
generate_report.py --open
```
), including Estimated context savings

Dry-run: same extraction, but do not call

write_knowledge

. Output is only the list of calls you would make (with the synthetic branch filled in).

Requires a Dosu MCP connection with

write_knowledge

. Writes must use

dosu/log-backfill/<timestamp>

so they auto-promote; do not fall back to the current checkout branch (those notes stay stranded until a real PR merges).

产品功能（保持简洁）：

读取本地Agent日志
筛选可持久化的知识内容（不是用户的提示词，而是找到的答案/注意事项）
将每个知识条目写入自动生成的
```
dosu/log-backfill/<UTC时间戳>
```
分支
（服务器会自动将该前缀下的笔记加入向上同步队列——与PR合并的流程一致）
告知用户已缓存的内容、预期Token节省量以及回填分支名称
打开HTML报告（执行
```
generate_report.py --open
```
），报告中包含预估上下文节省量

试运行模式： 执行相同的提取操作，但不调用

write_knowledge

。仅输出原本会执行的调用列表（已填充自动生成的分支名称）。

需要具备

write_knowledge

权限的Dosu MCP连接。写入操作必须使用

dosu/log-backfill/<时间戳>

分支，这样笔记会自动升级；不要回退到当前检出分支（这些笔记会一直处于孤立状态，直到真实PR合并）。

Do not ask (non-negotiable)

禁止询问（无协商空间）

Never use AskUserQuestion / multiple-choice / “three scope decisions” for this skill. Especially never ask:

How notes should be attributed to branches (main / per-session / etc.)
Note granularity / consolidation policy
How far back to harvest (unless the user already asked and was ambiguous)

Fixed defaults — just run:

Decision	Default
Time / volume	50 most recent parent sessions
Branch on every `write_knowledge`	One `BACKFILL_BRANCH=dosu/log-backfill/<UTC-timestamp>` for the whole run
Granularity	One durable learning per note (topic-shaped titles); consolidate in content when it’s the same fact

The MCP tool schema saying “use

git branch --show-current

” does not apply here. Override it. Do not ask the user which branch to use. Inform them of

BACKFILL_BRANCH

in one line after

whoami

, then continue.

Setup: references/customer-setup.md
What counts as a learning: references/write-criteria.md
Log paths: references/history-locations.md

绝对不要为该技能使用AskUserQuestion/选择题/“三项范围决策”。尤其绝对不要询问：

笔记应关联到哪个分支（主分支/按会话划分/其他）
笔记的粒度/合并规则
回溯提取的范围（除非用户已提出相关问题且表述模糊）

固定默认值——直接运行：

决策项	默认值
时间/数量	最近50个父会话
每次 `write_knowledge` 的分支	整个运行流程使用同一个 `BACKFILL_BRANCH=dosu/log-backfill/<UTC时间戳>`
粒度	每个笔记对应一个可持久化知识（主题式标题）；若为同一事实则合并内容

MCP工具架构中提到的“使用

git branch --show-current

”不适用于此场景。请覆盖该规则。不要询问用户使用哪个分支。在

whoami

执行后用一行内容告知用户

BACKFILL_BRANCH

，然后继续操作。

配置指南：references/customer-setup.md
知识判定标准：references/write-criteria.md
日志路径：references/history-locations.md

What a write looks like

写入示例

Each learning is one MCP call. Args are exactly:

Arg	Meaning
`title`	Noun-phrase topic ( `Slack PostgREST 1000-row channel picker cap` )
`content`	Self-contained fact a future agent needs
`repo`	Literal `git remote get-url origin`
`branch`	Synthetic `dosu/log-backfill/<UTC-YYYYMMDD-HHMMSS>` for the whole run
`tags`	Optional, e.g. `["from-agent-log", "cursor"]`

Wrong (never do this): using the user’s first message as

title

/ treating inventory “write gaps” as the notes. Gaps are only which sessions to open.

Right: after reading a digest, extract the durable conclusion, e.g.

title:   Slack PostgREST 1000-row channel picker cap
content: slackChannel.getAll used an unbounded PostgREST select; hosted
         PostgREST silently returns ≤1000 rows so large workspaces miss
         channels that exist in slack.channel. Page the query.
repo:    git@github.com:acme/api.git
branch:  dosu/log-backfill/20260810-220015

每个知识条目对应一次MCP调用。参数如下：

参数	含义
`title`	名词短语式主题（例如 `Slack PostgREST 1000-row channel picker cap` ）
`content`	未来Agent需要用到的独立完整事实
`repo`	直接使用 `git remote get-url origin` 的返回值
`branch`	整个运行流程使用同一个自动生成的 `dosu/log-backfill/<UTC-YYYYMMDD-HHMMSS>`
`tags`	可选参数，例如 `["from-agent-log", "cursor"]`

错误示例（绝对禁止）： 将用户的第一条消息作为

title

/将“写入缺口”清单作为笔记内容。缺口仅用于确定需要打开哪些会话。

正确示例： 读取摘要后，提取可持久化的结论，例如：

title:   Slack PostgREST 1000-row channel picker cap
content: slackChannel.getAll 使用了无限制的PostgREST查询；托管版PostgREST会静默返回≤1000行数据，因此大型工作区会遗漏slack.channel中存在的频道。需对查询进行分页处理。
repo:    git@github.com:acme/api.git
branch:  dosu/log-backfill/20260810-220015

Workflow

工作流程

Progress:
- [ ] 0. whoami + REPO/BACKFILL_BRANCH/SKILL_DIR
- [ ] 1. Inventory (find sessions worth mining — internal)
- [ ] 2. Digest those sessions
- [ ] 3. Build the write_knowledge payload list (+ rediscovery token estimate)
- [ ] 4a. Default: write on BACKFILL_BRANCH (auto-promotes) → open HTML report (with estimated context savings) → reply
- [ ] 4b. Dry-run: print the payload list → stop (no writes, no finalize)

Progress:
- [ ] 0. whoami + REPO/BACKFILL_BRANCH/SKILL_DIR
- [ ] 1. Inventory (find sessions worth mining — internal)
- [ ] 2. Digest those sessions
- [ ] 3. Build the write_knowledge payload list (+ rediscovery token estimate)
- [ ] 4a. Default: write on BACKFILL_BRANCH (auto-promotes) → open HTML report (with estimated context savings) → reply
- [ ] 4b. Dry-run: print the payload list → stop (no writes, no finalize)

Step 0 — Target

步骤0 — 目标

bash

SKILL_DIR="$(find .claude/skills .cursor/skills .agents/skills \
  -type d -name 'log-to-dosu-knowledge' 2>/dev/null | head -1)"
REPO="$(git remote get-url origin)"
BACKFILL_BRANCH="dosu/log-backfill/$(date -u +%Y%m%d-%H%M%S)"
test -f "$SKILL_DIR/scripts/parse_agent_logs.py"

Call

whoami

. Confirm

write_knowledge

is available. One line to the user which deployment will receive notes and the

BACKFILL_BRANCH

for this run (informational only — not a question). Never write log-backfill notes to the checkout branch. Do not pause for branch / date-range / granularity choices.

bash

SKILL_DIR="$(find .claude/skills .cursor/skills .agents/skills \
  -type d -name 'log-to-dosu-knowledge' 2>/dev/null | head -1)"
REPO="$(git remote get-url origin)"
BACKFILL_BRANCH="dosu/log-backfill/$(date -u +%Y%m%d-%H%M%S)"
test -f "$SKILL_DIR/scripts/parse_agent_logs.py"

执行

whoami

。确认

write_knowledge

可用。用一行内容告知用户接收笔记的部署环境以及本次运行的

BACKFILL_BRANCH

（仅作信息告知——非提问）。绝对不要将日志回填笔记写入当前检出分支。不要因分支/日期范围/粒度选择而暂停操作。

Step 1 — Inventory (internal)

步骤1 — 清单整理（内部操作）

Default scope is the 50 most recent parent sessions. Override when the user asks:

User says	Flags
(default)	(none — 50 most recent)
"last N days" / "past month"	`--days 30` (all sessions in that window)
"full audit" / "everything"	`--full`
"top N" / "N most recent"	`--limit N`

bash

python3 "$SKILL_DIR/scripts/parse_agent_logs.py" \
  --out /tmp/dosu-log-inventory.json

默认范围为最近50个父会话。当用户提出要求时可覆盖默认值：

用户指令	参数
默认	无参数——最近50个会话
"最近N天"/"过去一个月"	`--days 30` （该时间窗口内的所有会话）
"完整审计"/"所有内容"	`--full`
"前N个"/"最近N个"	`--limit N`

bash

python3 "$SKILL_DIR/scripts/parse_agent_logs.py" \
  --out /tmp/dosu-log-inventory.json

examples:

示例：

... --days 30 --out /tmp/dosu-log-inventory.json

... --full --out /tmp/dosu-log-inventory.json

... --limit 100 --out /tmp/dosu-log-inventory.json


Use write-gap ids to pick digests. **Do not** show gap prompts as the result.


使用写入缺口ID选择摘要。**不要**将缺口提示作为结果展示。

Step 2 — Digest

步骤2 — 摘要提取

bash

python3 "$SKILL_DIR/scripts/parse_agent_logs.py" \
  --digest <id> --json > /tmp/digest-<id>.json

Digest every write-gap in the inventory for the chosen scope. Prefer parent chats over

subagents/

bash

python3 "$SKILL_DIR/scripts/parse_agent_logs.py" \
  --digest <id> --json > /tmp/digest-<id>.json

为所选范围内清单中的每个写入缺口提取摘要。优先选择父聊天记录而非

subagents/

下的内容。

Step 3 — Build the write list

步骤3 — 构建写入列表

For each durable fact per write-criteria.md, append a payload:

json

{
  "title": "…",
  "content": "…",
  "repo": "<$REPO>",
  "branch": "<$BACKFILL_BRANCH>",
  "tags": ["from-agent-log", "cursor"],
  "transcript_id": "<source session id>",
  "approx_rediscovery_tokens": 12000
}

Use the same

BACKFILL_BRANCH

for every candidate in the run. Do not use the checkout branch or a per-log branch name.

approx_rediscovery_tokens

is the analytics analogue of

page_version.generation_tokens

: tokens spent rediscovering this fact in the source session (Read/Grep/Shell/etc. stretches that produced the learning).

Estimate when unsure:

From inventory, take that transcript’s effective tokens × rediscovery share (same fallback as
```
compare_tokens.py
```
: rediscovery_tool_calls / total tools, capped at 0.85; ×0.5 if the session already had knowledge reads).
Split that budget across notes mined from the same transcript.

Skip secrets/PII, task summaries, speculation, obvious one-file facts.

Write the full list to

/tmp/dosu-log-candidates.json

{ "candidates": [ …payloads… ] }

so dry-run, savings summary, and HTML share one shape.

根据write-criteria.md中的标准，为每个可持久化事实添加一条请求参数：

json

{
  "title": "…",
  "content": "…",
  "repo": "<$REPO>",
  "branch": "<$BACKFILL_BRANCH>",
  "tags": ["from-agent-log", "cursor"],
  "transcript_id": "<源会话ID>",
  "approx_rediscovery_tokens": 12000
}

本次运行中的所有候选条目使用同一个

BACKFILL_BRANCH

。不要使用当前检出分支或按日志划分的分支名称。

approx_rediscovery_tokens

是与

page_version.generation_tokens

对应的分析指标：在源会话中重新发现该事实所消耗的Token（产生该知识的Read/Grep/Shell等操作环节）。

若不确定可按以下方式估算：

从清单中获取该会话的有效Token数 × 重新发现占比（与
```
compare_tokens.py
```
的 fallback 逻辑一致：重新发现工具调用数 / 总工具调用数，上限为0.85；若会话已包含知识读取操作则乘以0.5）。
将该预算分配给从同一会话中提取的所有笔记。

跳过机密信息/PII、任务摘要、推测内容、明显的单文件事实。

将完整列表写入

/tmp/dosu-log-candidates.json

，格式为

{ "candidates": [ …请求参数… ] }

，以便试运行、节省量汇总和HTML报告使用统一格式。

Step 4a — Default: write + savings

步骤4a — 默认模式：写入+节省量统计

For each payload, call MCP

write_knowledge

with

title

content

repo

branch

tags

(omit helper fields like

approx_rediscovery_tokens

). Every write must use

BACKFILL_BRANCH

. The server auto-enqueues notes-upflow for

dosu/log-backfill/*

(same step as a PR merge) — no separate promote call.

If MCP write is unavailable:

bash

python3 "$SKILL_DIR/scripts/pending_knowledge.py" append \
  --repo "$REPO" --branch "$BACKFILL_BRANCH" \
  --title "…" --content "…" \
  --tags from-agent-log,pending-sync

Then compute the default user-facing summary:

bash

python3 "$SKILL_DIR/scripts/summarize_savings.py" \
  --candidates /tmp/dosu-log-candidates.json

That stdout is the default reply, plus one line that notes were written on

BACKFILL_BRANCH

and entered the candidate-topic pipeline. Shape:

Cached N notes:
1. <title>
2. <title>

Expected savings: ~Y tokens per future agent read
(same model as analytics: rediscovery/generation cost reused on each hit)

Wrote on dosu/log-backfill/<UTC-YYYYMMDD-HHMMSS> (auto-promoted into the candidate-topic pipeline).

Do not stop at “Saved N notes” without the savings line.

Then always open the HTML report (not opt-in). Estimated context savings is filled from each note's

approx_rediscovery_tokens

— do not skip that field in step 3.

The reporter assumes notes were written; pass

--dry-run

only if generating HTML without write_knowledge.

bash

python3 "$SKILL_DIR/scripts/generate_report.py" \
  --inventory /tmp/dosu-log-inventory.json \
  --candidates /tmp/dosu-log-candidates.json \
  --org-name "…" --repo "$REPO" --branch "$BACKFILL_BRANCH" \
  --out /tmp/dosu-knowledge-report.html --open

Call

finalize_session_knowledge

once with write receipt ids if that tool exists.

为每个请求参数调用MCP的

write_knowledge

接口，传入

title

content

repo

branch

tags

（省略

approx_rediscovery_tokens

等辅助字段）。所有写入操作必须使用

BACKFILL_BRANCH

。服务器会自动将

dosu/log-backfill/*

下的笔记加入向上同步队列（与PR合并的流程一致）——无需单独调用升级接口。

若MCP写入不可用：

bash

python3 "$SKILL_DIR/scripts/pending_knowledge.py" append \
  --repo "$REPO" --branch "$BACKFILL_BRANCH" \
  --title "…" --content "…" \
  --tags from-agent-log,pending-sync

然后计算面向用户的默认汇总信息：

bash

python3 "$SKILL_DIR/scripts/summarize_savings.py" \
  --candidates /tmp/dosu-log-candidates.json

该标准输出即为默认回复内容，再加上一行说明笔记已写入

BACKFILL_BRANCH

并进入候选主题流水线。格式如下：

已缓存N条笔记：
1. <标题>
2. <标题>

预期节省量：未来每次Agent读取可节省约Y个Token
（与分析模型一致：每次命中都会复用重新发现/生成的成本）

已写入分支dosu/log-backfill/<UTC-YYYYMMDD-HHMMSS>（已自动升级至候选主题流水线）。

不要仅回复“已保存N条笔记”而省略节省量说明。

随后必须打开HTML报告（不可选择关闭）。预估上下文节省量由每条笔记的

approx_rediscovery_tokens

填充——步骤3中不要省略该字段。

报告工具默认假设笔记已写入；仅当未调用write_knowledge生成HTML时才传入

--dry-run

参数。

bash

python3 "$SKILL_DIR/scripts/generate_report.py" \
  --inventory /tmp/dosu-log-inventory.json \
  --candidates /tmp/dosu-log-candidates.json \
  --org-name "…" --repo "$REPO" --branch "$BACKFILL_BRANCH" \
  --out /tmp/dosu-knowledge-report.html --open

若存在

finalize_session_knowledge

工具，使用写入回执ID调用一次该工具。

Step 4b — Dry-run (when user asks)

步骤4b — 试运行模式（用户要求时）

Do not call

write_knowledge

. Still set

BACKFILL_BRANCH

and include it on every listed payload. Reply with the payload list, e.g.:

Dry-run — would call write_knowledge N times:

1. title: …
   content: …
   repo: …  branch: …
   approx_rediscovery_tokens: …

2. title: …
   content: …
   repo: …  branch: …
   approx_rediscovery_tokens: …

That list is the dry-run output. Not session prompts. Not inventory scores. Optionally append the same

summarize_savings.py

block (expected savings if these were written). If you open the HTML on a dry-run, pass

--dry-run

不要调用

write_knowledge

。仍需设置

BACKFILL_BRANCH

并将其包含在每个列出的请求参数中。回复请求参数列表，例如：

试运行——原本会调用N次write_knowledge：

1. title: …
   content: …
   repo: …  branch: …
   approx_rediscovery_tokens: …

2. title: …
   content: …
   repo: …  branch: …
   approx_rediscovery_tokens: …

该列表即为试运行输出内容。不要包含会话提示或清单评分。可选择性添加相同的

summarize_savings.py

输出块（若写入这些内容可获得的预期节省量）。若在试运行时打开HTML报告，需传入

--dry-run

参数。

Opt-in extras

可选附加功能

User says	Behavior
"PDF"	Print / Save as PDF from the HTML report already opened
"detailed token report"	Optional `compare_tokens.py` eval with pasted `read_knowledge` responses (overrides the default estimate)

用户指令	行为
"PDF"	从已打开的HTML报告中打印/另存为PDF
"详细Token报告"	可选执行 `compare_tokens.py` 评估，粘贴 `read_knowledge` 响应（覆盖默认估算值）

Guardrails

防护规则

Default writes on
```
dosu/log-backfill/*
```
(server auto-promotes) and always includes expected token savings, opens the HTML report, and fills Estimated context savings on that report.
Never write log-backfill notes to the current checkout branch.
Never ask how to attribute notes to branches — always
```
BACKFILL_BRANCH
```
.
Never invent a scope questionnaire; use the defaults unless the user already specified overrides in their message.
Dry-run only when asked (no write).
Never write secrets / PII / raw log dumps.
One learning per
```
write_knowledge
```
call; keep notes lean.
User-facing output is always about notes (written or proposed) + savings, never raw prompts.

默认模式下写入到
```
dosu/log-backfill/*
```
分支（服务器自动升级），且必须包含预期Token节省量、打开HTML报告，并在报告中填充预估上下文节省量。
绝对不要将日志回填笔记写入当前检出分支。
绝对不要询问笔记应关联到哪个分支——始终使用
```
BACKFILL_BRANCH
```
。
绝对不要创建范围调查问卷；除非用户已在消息中指定覆盖项，否则使用默认值。
仅在用户要求时执行试运行（不写入）。
绝对不要写入机密信息/PII/原始日志转储。
每次
```
write_knowledge
```
调用对应一个知识条目；保持笔记简洁。
面向用户的输出始终围绕笔记（已写入或拟写入）+ 节省量，绝不包含原始提示词。

Quick examples

快速示例

"Please bootstrap my knowledge with Dosu." → write on backfill branch (auto-promotes) + cached titles + expected savings + open HTML report (with estimated context savings).
"Mine my agent logs into Dosu." → same default write flow.
"Dry-run log to dosu knowledge." → list of
```
write_knowledge
```
payloads (synthetic branch) only.

"请用Dosu初始化我的知识。" → 写入回填分支（自动升级）+ 已缓存标题 + 预期节省量 + 打开HTML报告（包含预估上下文节省量）。
"将我的Agent日志提取到Dosu。" → 执行相同的默认写入流程。
"试运行日志导入Dosu知识库。" → 仅列出
```
write_knowledge
```
请求参数（自动生成的分支）。