cat-xierluo 课程内容整理
任务目标
把现有文本整理成读者无需接触原始转录稿也能理解和使用的课程。正文应完整保留来源中的重要观点、案例、操作过程、失败修正和判断方法，同时去除现场口语、会务信息和转录噪声。
本技能默认生成课程，不自动归档、移动原文件或改造成其他内容产品。用户明确要求生成后的归档或培训方案提取时，再读取 post-generation-actions.md。
输入与交付
开始前确认：
- 一份来源文件或一个来源目录；优先处理
.md、.txt。 - 课程输出目录；未指定时在来源旁建立新的课程目录，并在写入前说明位置。
- 是否存在勘误、编校说明或指定的现行口径文件。
- 是否需要使用用户词典纠正专名或固定术语；需要时从
config/user_dictionary.example.yaml复制为config/user_dictionary.yaml，只登记能够确认的替换。 - 目标目录是否已有内容；不得静默覆盖。
默认交付包括：
00 <课程名称> - 总览.md- 按阅读顺序编号的课程章节
source-index.jsoncourse-manifest.json
原始材料保持只读。临时计划、批次文件、辅助脚本和缓存放在课程目录之外。
核心要求
- 忠实来源：数字、动作、结果、建议和专有名称必须能回到来源；原文没有的能力、流程、案例和结论不得用常识补齐。
- 保留精华：每个有效来源块都要进入素材账本或使用受控理由跳过。案例、操作、踩坑、取舍和判断技巧不得被压成一句摘要。
- 遵守现行口径：来源存在明确修订时，以控制文档为准；旧口径只进入审计记录，不得重新出现在读者正文。
- 证据跟随章节：每个二级标题必须有绑定素材，素材正文证据只能来自自己的目标小节，不跨节借用。
- 书面化而不扩写：删除逐字稿框架和口语赘词，但保留原文的不确定、举例和设想语气；单一样本不得扩成普遍规律或行业惯例。
- 生产与验收分离：生成者完成正文，脚本检查客观约束，最后再由独立审阅者检查素材守恒、事实忠实和阅读质量。
冲突时依次保护：事实忠实与现行口径、核心素材完整、章节证据边界、读者可读性、审计便利。
工作流程
生成任务开始后，先完整读取 generation-workflow.md，再按以下顺序执行；不得跳过账本预检直接写正文。
- 运行
index_sources.py建立确定性来源索引。 - 用
ledger_tool.py init初始化 manifest，确认权威声明并冻结章、节计划。 - 按
status返回的来源块分批建立素材账本，运行 ledger 阶段自动收口和预检。 - 选择少量有教学价值的代表图，由工具生成章节标题和修订句脚手架。
- 读取 overview_prompt.md 和 chapter_prompt.md，先写总览，再逐章生成；每章通过
check-chapter后才进入下一章。 - 运行 final 阶段自动收口和
verify.sh，再完成人工语义复核。
大纲和素材判断规则见 outline_prompt.md。机器字段及 JSON 示例见 course-manifest.md。默认最多 8 章；只有用户明确要求超过 8 章时才读取 advanced-overrides.md。
完成标准
只有同时满足以下条件，才可交付：
- 总览、manifest 声明的全部章节和两份强制 JSON 均存在。
- 素材账本覆盖全部有效来源块，跳过项有受控理由，高价值内容没有无理由净丢失。
- 每章
check-chapter通过，最终verify.sh退出码为0。 - 独立审阅者读取 quality-evaluation.md，按证据完成语义验收；人工抽查确认数字、动作链、建议、结果和专名可回溯，修订口径无冲突，章节之间没有明显重复。
- 读者正文不出现
SRC/BLK/MAT/IMG、门禁解释、生成日志、临时文件或来源没有讨论的内部术语。
脚本通过只证明客观契约成立，不等于语义质量已经通过。交付时分别报告脚本结果、人工复核范围和未验证部分。
配额、网络或平台异常时保留现场并报告，不从头重跑，不把半成品或执行者自报记为成功。
权限与隐私
- 只读取用户指定的来源，只向已说明的课程目录写入。
- 脚本不联网、不安装依赖、不修改原始材料；
init/plan/merge/select-images原子更新索引或 manifest，scaffold只创建缺失的标题脚手架，finalize_manifest.py --write只更新 manifest。 - 未脱敏转录稿和课程材料按最小必要原则处理，不写入公开示例、变更记录或配置模板。
依赖
系统依赖
| 依赖 | 用途 | 安装方式 |
|---|---|---|
python3 >= 3.10 |
运行来源索引、账本和验收脚本 | macOS: brew install pythonLinux: sudo apt-get install python3 |
Python 包
无需第三方 Python 包，全部脚本只使用标准库。
资源索引
- generation-workflow.md：完整生成步骤、命令顺序和失败处理；每次生成课程时读取。
- outline_prompt.md：素材分类、章节规划和图片判断；建立计划与账本时读取。
- overview_prompt.md：总览写作要求；生成总览时读取。
- chapter_prompt.md：章节写作和单章自检；逐章生成时读取。
- course-manifest.md：manifest 字段和 JSON 示例；准备计划、批次或图片选择文件时按需查询。
- quality-evaluation.md：课程成品的语义硬失败、质量评分和版本晋级标准；独立验收或回归比较时读取，不提供给生成者作为写作提纲。
- post-generation-actions.md：归档和培训方案提取；仅在用户明确要求时读取。
- verify.sh：最终确定性验收入口。