QA to Tutorial

把问答日志「去曲折」为教程笔记：模型只做识别、分类与定位，正文由脚本按 id 机械搬运，同时满足「保持原文」「报错不遗漏」与「省 token」。

工作流选择

• 笔记不存在 / 第一次整理 → Build：读 references/build-workflow.md。
• 笔记已存在，导入新导出记录 → Merge：读 references/merge-workflow.md。
• 「哪些能改、哪些不能改、章节如何排序、矛盾如何处理」 → 读 references/style-rules.md。
• 初始化会在笔记目录生成一份《文档化操作手册.md》（本 skill 规则的项目级固化副本），执行前先读它。

Build 概览（详见 references/build-workflow.md）

1. parse 导出文件 → blocks.jsonl（脚本完成，模型零参与）
2. dedup（无 manifest）→ 批内去重与术语重叠提示
3. 分批 Read blocks.jsonl（每批约 8–12k tokens，仅一遍），为每个 QA 定性：主线 / 报错插曲 / 概念插曲
4. 按学习路径设计章节大纲，先交用户确认
5. 写 build plan（只含 id 引用）→ init + apply → verify

Merge 概览（详见 references/merge-workflow.md）

1. parse 新导出（建议 --id-prefix 日期）
2. dedup --manifest：整 QA / 块重复自动识别，错误签名与命令产出路由候选（high/mid/low）
3. 读 candidates + manifest（不读 tutorial.md 全文），裁决每个新 QA：
   attach_detour / insert_items / new_step / new_section /
   merge_detour / merge_item / drop_qa
4. 写 merge plan → apply（更新结构、全量重渲染）→ verify

命令速查

T=<skill>/scripts/qatut.py
python3 $T parse export.md -o blocks.jsonl [--id-prefix 1010] [--cutmap cuts.json]
python3 $T stats blocks.jsonl
python3 $T dedup blocks.jsonl [--manifest <dir>/.qa-tutorial/manifest.json] --outprefix out
python3 $T init --dir <笔记目录> --title "教程标题"
python3 $T apply plan.json --dir <笔记目录> --blocks blocks.jsonl
python3 $T verify --dir <笔记目录> [--blocks blocks.jsonl]

不可违反的约定

1. 正文不经过模型重新输出。plan 中只出现 qa_id / block_id；原文由脚本从 blocks 取。禁止润色、扩写、缩写代码/事实/结论（完整红线见 style-rules）。
2. 报错不遗漏：含实操报错的 QA 不得整体丢弃，报错日志块必须进入笔记，按「现象/原因/解决/验证」挂到对应步骤。
3. Merge 不读笔记全文；路由靠 manifest，核对细节只 grep 或局部读目标小节。
4. <!-- sec/step/qa/det/blk --> 标记、<a id> 锚点、目录与附录索引区域是工具锚点，禁止手工删除、改名或编辑。
5. 每个 QA 必须有唯一终态：被一个 item / 插曲引用，或在 drop（drop 需 reason）；插曲的 source QA 块必须 100% 被 parts 或 drop_blocks 覆盖。同一块只在一处出现。
6. apply 后必须 verify 通过再向用户报告；失败先修复。脚本自动备份 .bak。
7. parse 识别不到角色边界时，用 .uncut.txt + cutmap 兜底，不得猜测内容或放弃任务。
8. 密码、Token、隐私原文默认不收录；用户明确禁止的内容不收录。

用户就笔记提问时（检索作答红线）

1. 问题在笔记主题范围内，必须先检索，禁止凭印象直接答。
2. 检索三跳：manifest（标题/摘要/关键词/错误签名/原始问法）→ grep 原文 → 局部读命中小节。
3. 作答即搬运：给出锚点链接 + 原文摘录，命令、数字、结论不改写。
4. 零命中须明说「笔记中没有」；改用通用知识回答时显式标注「此内容不在笔记中」。

产物结构

<笔记目录>/
├── tutorial.md                  # 教程笔记本体
├── 文档化操作手册.md             # 操作逻辑固化副本（项目级）
└── .qa-tutorial/
    ├── manifest.json            # 章节树 + 摘要/关键词 + 错误签名 + 命令键（路由地图）
    ├── blocks-store.jsonl       # 已收录块原文仓库（不进模型上下文）
    └── *.bak                    # 最近备份

与 qa-notebook 的边界

• 本 skill 处理离线批量导入导出文件（历史记录重构、去曲折、增量合并）；qa-notebook 处理对话中每轮实时沉淀。
• 默认本 skill 维护独立教程笔记目录，避免两个 skill 双写同一文件。
• 若用户要求把导出内容并入 qa-notebook 维护的笔记：先读取该笔记的结构规范，本 skill 只执行导入并遵守其格式，不启用第二套写入规则。