log-to-dosu-knowledge

日志 → Dosu 知识库

产品说明（保持简单）：

此技能适用于日志早于 Dosu 的首次使用者。

1. 读取本地 Agent 日志
2. 判断要写入什么（不是用户的提示词，而是答案／注意事项）
3. 将每条内容写入一个合成的 dosu/log-backfill/<UTC-timestamp> 分支 （服务端会为此前缀自动将笔记加入 notes-upflow 队列——与 PR 合并的路径相同）
4. 告知用户缓存了什么、预计节省的令牌量以及回填分支
5. 打开 HTML 报告（generate_report.py --open），其中包括预计的上下文节省量

试运行：提取方式相同，但不要调用 write_knowledge。仅输出你将会进行的调用列表（其中填入合成分支）。

需要连接提供 write_knowledge 的 Dosu MCP。写入时必须使用 dosu/log-backfill/<timestamp>，以便自动提升；不要回退到当前检出分支（这些笔记会一直滞留，直到真正的 PR 合并）。

不要询问（不可妥协）

使用此技能时，绝不要使用 AskUserQuestion／多选题／“三个范围决策”。尤其绝不要询问：

• 笔记应如何归属到分支（main／每个会话等）
• 笔记的粒度／合并策略
• 要向前回溯多久（除非用户已经提出请求且含义模糊）

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

决策	默认值
时间／数量	最近的 50 个父会话
每次 write_knowledge 使用的分支	整个运行过程使用一个 BACKFILL_BRANCH=dosu/log-backfill/<UTC-timestamp>
粒度	每个助手结论一条笔记（长聊天中会有多条笔记）。仅在事实相同时才合并。

MCP 工具架构中写着“使用 git branch --show-current”不适用 于此处。覆盖该要求。不要询问用户要使用哪个分支。在执行 whoami 后，用一行告知用户 BACKFILL_BRANCH，然后继续。

• 设置：references/customer-setup.md
• 写入内容：references/write-criteria.md
• 日志路径：references/history-locations.md

写入示例

每条笔记对应一次 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 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:    [email protected]:acme/api.git
branch:  dosu/log-backfill/20260810-220015

工作流

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)

步骤 0 — 目标

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 可用。用一行告知用户将接收笔记的 Library，以及本次运行的 BACKFILL_BRANCH（仅供告知，并非提问）。如果 whoami 返回了内部目标字段，不要向用户复述该字段——使用 Library／组织名称。绝不要将 log-backfill 笔记写入检出分支。不要暂停并询问分支／日期范围／粒度的选择。

步骤 1 — 清点（内部）

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

用户表述	标志
（默认）	(无 — 最近的 50 个)
“最近 N 天”／“过去一个月”	--days 30（该时间范围内的所有会话）
“完整审计”／“全部”	--full
“前 N 个”／“最近的 N 个”	--limit N

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

使用清单中的所有父会话。排序仅用于排列顺序（candidate_score 最高的排在最前）。不要将用户提示词或清单行作为结果展示给用户。

步骤 2 — 梳理

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

梳理清单中的每个可挖掘的父会话。每次梳理后，按顺序遍历每个用户轮次（而不只是最后一个）。长时间的调查（100k+ learning_tokens、50+ 个用户轮次）应产出许多笔记，而不是 1–2 条。

仅跳过空白或无关紧要的聊天（没有实际的用户查询）。优先处理父聊天，而非 subagents/。不要因为第一条消息看起来像报告、Sentry 内容或 SQL 粘贴而跳过梳理。

步骤 3 — 建立写入清单

对于每个获得了符合 write-criteria.md 之助手结论的用户轮次，追加一个负载。 不要把“我已经从这份记录写了一条笔记”视为完成。

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

plain_english 是用 1–2 句话向队友重新表述这一想法（不要堆砌函数或表名）。仅用于报告——与 approx_rediscovery_tokens 一样，从 write_knowledge 中省略。 how_found 说明通过哪些工作发现了它（读取、SQL、Logfire、代码路径），而不是会话分摊令牌公式。仅用于报告——从 write_knowledge 中省略。 investigation_lines 是传递给 compare_tokens.py --from-digest --lines 的同一组 START-END。每个候选项都必须包含此字段，否则 HTML 中的 Work to learn this 展开区将为空白。仅用于报告——从 write_knowledge 中省略。

本次运行中的所有候选项都使用同一个 BACKFILL_BRANCH。不要使用检出分支或按日志划分的分支名。

approx_rediscovery_tokens 表示学习这一事实本身的成本：得出结论所花费的令牌（问题 + 检索 + 思考 + 结论）。包括 Decant 上下文 + 规划 + 其他。排除 Write/Edit/修改 shell 的开销——笔记无法节省实现令牌。学到 100k → 节省 100k。无上限。不按会话分摊。

将本事实相关的摘要行标记为从第一个相关问题/工具开始，到结论为止。使用以下方法测量：

python3 "$SKILL_DIR/scripts/compare_tokens.py" \
  --from-digest /tmp/digest-<id>.json --lines START-END

将该 JSON 中的 approx_rediscovery_tokens 写入负载。仅当无法确定这一段内容时才省略该字段——绝不虚构会话分摊，不可只用上下文分类，也不可拆分会话预算。

跳过机密/PII、任务摘要、推测内容和显而易见的单文件事实。

将完整清单写入 /tmp/dosu-log-candidates.json，格式为 { "candidates": [ …payloads… ] }，以便试运行、节省量摘要和 HTML 共用同一结构。

步骤 4a — 默认：写入并统计节省量

对每个负载，调用 MCP write_knowledge，并提供 title / content / repo / branch / tags（省略 approx_rediscovery_tokens、plain_english、how_found 和 investigation_lines 等辅助字段）。每次写入都必须使用 BACKFILL_BRANCH。服务端会自动将 notes-upflow 加入队列，适用于 dosu/log-backfill/*（与 PR 合并时的步骤相同）——无需单独调用 promote。

如果 MCP 写入不可用：

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

然后计算默认的面向用户摘要：

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

该标准输出就是默认回复，再加一行说明笔记已写入 BACKFILL_BRANCH，并已进入候选主题流水线。格式如下：

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).

不要只说“已保存 N 条笔记”就停止，必须附上节省量行。

随后始终打开 HTML 报告（并非可选）。预计节省的上下文量取自每条笔记的 approx_rediscovery_tokens（仅当无法确定调查内容的范围时才省略该字段——绝不虚构会话分摊）。

报告器假定笔记已写入；只有在生成 HTML 时未调用 write_knowledge，才传入 --dry-run。

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

如果存在 finalize_session_knowledge 工具，则使用写入回执 ID 调用一次。

步骤 4b — 试运行（用户提出要求时）

不要调用 write_knowledge。仍需设置 BACKFILL_BRANCH，并将其包含在每个列出的负载中。回复负载清单，例如：

Dry-run — would call write_knowledge N times:

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

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

该清单就是试运行输出。不是会话提示词，也不是清单评分。可选择附上同一段 summarize_savings.py 输出（假设这些笔记已写入时的预计节省量）。如果在试运行时打开 HTML，请传入 --dry-run。

可选附加功能

用户说	行为
“PDF”	从已打开的 HTML 报告中打印／另存为 PDF
“详细的令牌报告”	使用粘贴的 read_knowledge 响应运行可选的 compare_tokens.py 评估（覆盖默认估算）

Miner 漏采模式（不要对客户说出这个词）

Agent 指令，确保采集时不会少计：

1. 每个助手结论对应一条笔记，而不是每份转录对应一条——不要在最后一个岔题处停止。
2. 不要因为第一条消息看起来像报告／Sentry／SQL 粘贴内容，就跳过摘要。
3. 始终在生成报告前合并待处理项（generate_report.py --pending）。
4. 解析器会将仅包含 Bootstrap 的会话排除在默认的 50 条之外；如果出现，请跳过。
5. 如果 Library 已有该页面（本次运行的 read_knowledge），则跳过写入；状态 already_in_library 可以接受。
6. HTML 基线是清单中的 learning_tokens，不能只用 effective_tokens 或 context_tokens。
7. 每个候选项都必须包含 investigation_lines，且报告必须使用 --digest-dir /tmp 生成（摘要保留在磁盘上）。缺少其中任一项，要学习的内容就会为空——how_found 不能替代它。

防护规则

• 默认在 dosu/log-backfill/* 上写入（服务会自动提升），并始终包含预期令牌节省量、打开 HTML 报告，以及在该报告中填写预计上下文节省量。
• 绝不将 log-backfill 笔记写入当前检出分支。
• 绝不询问笔记应归属哪个分支——始终使用 BACKFILL_BRANCH。
• 绝不自行编造范围问卷；除非用户已在消息中指定覆盖项，否则使用默认值。
• 只有在用户要求时才进行试运行（不写入）。
• 绝不写入机密信息／PII／原始日志转储。
• 每次 write_knowledge 调用只写一条笔记；笔记应简洁。
• 面向用户的输出始终围绕笔记（已写入或拟写入）和节省量，而不是原始提示词。

快速示例

• “请用 Dosu 为我的知识库做初始化。” → 在回填分支上写入（自动提升）＋缓存标题＋预期节省量＋打开 HTML 报告（含预计上下文节省量）。
• “将我的 Agent 日志提炼到 Dosu 中。” → 使用相同的默认写入流程。
• “试运行日志并写入 Dosu 知识库。” → 仅列出 write_knowledge 载荷（合成分支）。