知识库运行手册项目与自测
项目目标
为一个虚构的“本地会议摘要脚本”写一篇运行手册。项目只验收文档质量，不要求创建或运行脚本。读者应能从零判断环境、执行步骤、预期结果、失败处理和安全边界。先独立完成，再查看 参考答案；参考答案中的命令同样是教学情境，不代表仓库中存在对应脚本。
任务情境与交付物
- 场景：脚本只读取本地 UTF-8 会议文本和一份本地
config.json，输出本地 Markdown 摘要草稿，不联网、不发送消息。 - 交付物：一篇名为
会议摘要运行手册.md的笔记；不要把练习文件写进本知识库正式课程目录。 - 受众：会打开 PowerShell、但不了解 Python 项目的初学者。
- 证据边界：可以写“预期输出”，不能把未运行命令写成“已验证通过”。
- 安全边界：只使用虚构会议内容和占位路径，不使用真实录音、客户信息或凭据。
必需结构
元数据
frontmatter 至少有 title、tags、aliases。属性只放可检索元数据，详细说明放正文。
概述与边界
说明脚本把本地虚构会议文本转换成摘要草稿；不连接真实会议系统，不自动发送，不读取真实凭据。
前置条件
列出 Windows 11、PowerShell 7、Python 3，以及如何用命令验证。不要擅自承诺某个未检查版本。
操作步骤
命令按顺序编号，每段说明：目的、当前目录、命令、预期输出和失败时停止条件。命令和输出使用不同语言围栏。
输入输出契约
用表格记录文件名、格式、必填内容、敏感级别和保留策略。至少定义 meeting.txt、config.json 与 summary.md，并给出完全虚构的最小输入、配置和预期输出。
验收与排错
至少包含：文件不存在、编码错误、JSON 语法错误、输出为空四种故障。每种写可观察表现、诊断命令和安全恢复。
Mermaid 流程图
画出“读取→验证→摘要→人工确认→结束”。明确人工确认前没有外部副作用。
来源与变更记录
外部资料使用标准链接并记录获取日期。变更记录说明改了什么和验证了什么，不写无法证明的“完全可用”。
质量检查
| 维度 | 不通过 | 通过 |
|---|---|---|
| 结构 | 标题堆叠、无顺序 | 读者能按层级定位任务 |
| 命令 | 缺目录和预期 | 命令、输出、占位符清楚分开 |
| 链接 | 模糊或断链 | 内链路径明确，外链有描述 |
| 证据 | 把预期写成实测 | 明确区分已执行与未执行 |
| 安全 | 示例含真实数据或凭据 | 仅虚构数据，危险边界明确 |
| 渲染 | 未检查围栏与图 | 编辑视图和阅读视图均复核 |
真实任务验收
邀请另一位没有背景的读者只按手册回答：
- 从哪个目录运行？
- 怎样确认 Python 可用？
- 输入包含什么，哪些数据禁止使用？
- 什么结果算成功？
- 哪些错误必须停止？
- 输出会不会自动发送？
若读者需要作者口头补充，手册仍缺信息。将问题记录为文档测试结果再修订。
评分规则
总分 20 分，每项 0～2 分：
- 受众、目标与非目标是否明确；
- 前置条件是否给出验证命令；
- 每一步是否说明工作目录、命令和停止条件；
- 输入输出契约是否可检查；
- 预期结果与实际验证是否分开；
- 四类故障是否都有可观察现象和安全恢复；
- 内链是否指向真实完整路径，外链是否有描述；
- Mermaid 是否只表达关键控制流；
- 是否没有真实敏感信息和破坏性命令；
- 是否记录来源日期、修改内容和未验证项。
达到 16 分且没有安全项 0 分才算完成；若另一位读者仍需口头补充，最多记 15 分。
全库自测
- Markdown 与渲染器是什么关系？
- CommonMark、GFM 与 Obsidian 扩展为何不能混为一谈？
- 为什么标题层级比字体大小更重要？
- 围栏代码与行内代码怎样选择？
- 内部文件重名时如何避免链接歧义？
- 为什么外部 URL 不使用 wikilink？
- 表格什么时候不如列表？
- Mermaid 适合表达哪类关系？
- 文档怎样区分预期结果与实际验证？
- 为什么文档也需要安全审查？
掌握检查
- 完成一篇包含元数据、步骤、表格、代码围栏、链接和 Mermaid 的手册。
- 所有内部链接都解析到真实文件，外部链接有描述。
- 在 Obsidian 编辑视图与阅读视图检查排版。
- 让另一位读者按手册完成一次纸面演练。
- 记录未验证项，不把示例输出冒充实测。
- 文档不含真实凭据、敏感数据或不安全的批量删除命令。
上一节：综合写作练习与 Mermaid 排错。
完成后先与 参考答案逐项比较，再回到 Markdown 目录。
参考资料
获取日期：2026-07-14。