Markdown

知识库简介

Markdown 是用纯文本表达标题、段落、列表、链接、代码和表格的轻量标记方式。AI Agent Engineer 会用它维护 README、运行手册、工具契约、提示词说明、实验记录和 Obsidian 知识库。真正目标不是背符号，而是写出：源文件本身可读、目标宿主能稳定渲染、链接可维护、步骤可执行、证据边界清楚的工程文档。

本库把 7 课正式路线与 3 份参考材料分开。Markdown 完整教程 和 Mermaid 完整教程 保留为大型查阅层；学习时先走短课程，再按问题定位章节。动态版本与大型教程的兼容提醒统一见 参考资料、版本与兼容性说明。

在总路线中的位置

本库位于“工程与数学基础”知识域。在四条角色路径中，它通常承接 JSON 并衔接 Git；后续提示词、RAG、Agent、评测与生产化课程都会复用这里建立的结构、链接、证据和安全写作习惯，但不把完整 Markdown 课程设为硬前置。

学习目标

• 使用标题、段落、列表、引用、表格、链接、图片与嵌套代码围栏。
• 从“源文本—解析器—宿主渲染”解释换行、缩进、围栏和兼容差异。
• 区分 CommonMark 0.31.2、GFM 0.29-gfm、Obsidian 扩展与平台功能。
• 使用完整路径 wikilink、标题/块链接、embed 和相邻附件规则。
• 设计类型清楚、无重复键且不含敏感信息的 Properties。
• 用 callout 和 Mermaid 表达必要语义，不让视觉元素替代正文契约。
• 写出可供初学者执行和审查的 Agent 工程文档，区分预期、实测、建议、推断与未知。

前置知识

只需会使用文本编辑器和文件夹；不要求编程。建议用 Obsidian 源码模式或实时预览与阅读视图对照观察。涉及命令的练习以 Windows 11、PowerShell 7 为主，但本课程不会创建虚拟环境、安装依赖或调用外部 API。

推荐学习顺序

顺序	课程	你要解决的问题
1	Markdown 基础语法与可读源文件	Markdown 如何从纯文本变成结构；怎样写出不渲染也能读的文档？
2	CommonMark、GFM 与 Obsidian 语法边界	哪些是可移植核心、GFM 扩展、Obsidian 专用或平台行为？
3	Obsidian 链接、附件与嵌入	如何避免同名入口歧义，并维护标题、块与附件 embed？
4	Properties、Callouts 与可复用笔记	怎样设计可检索元数据与有语义的提示块？
5	面向 Agent 工程的结构化技术写作	怎样让 README、runbook、实验记录和工具契约可执行、可审查？
6	综合写作练习与 Mermaid 排错	如何用小任务练习结构、链接、Properties、图和最小化排错？
7	知识库运行手册项目与自测	如何交付一篇有契约、故障路径、安全边界和读者测试的完整手册？

参考层按需使用：

• Markdown 完整教程：17 个主题与速查表，查具体符号。
• Mermaid 完整教程：大量图类型与项目示例，先读兼容说明再按需查阅。
• 参考资料、版本与兼容性说明：当前版本事实、一手来源与宿主差异。

动手实践与项目入口

• 渲染、链接、Properties 与 Mermaid 训练：综合写作练习与 Mermaid 排错。
• 真实链接与 embed 目标：链接与嵌入练习目标。
• 综合交付：知识库运行手册项目与自测。
• 完成项目后再看：会议摘要运行手册参考答案。

所有练习都要先看源文件，再看阅读视图；两者都应可理解。若没有另一位读者，可以隔一天后只按自己的手册做纸面演练，并记录仍需补充的信息。

掌握标准

• 能用标题层级、段落和列表组织长文，不靠粗体或空格制造结构。
• 能解释块结构与行内结构，并修复换行、缩进和嵌套围栏问题。
• 能给常用语法标注 CommonMark、GFM、Obsidian 或平台层级。
• 能创建无歧义的完整路径笔记/标题/块链接，并嵌入真实目标。
• 能写无重复键、类型稳定且不含秘密的 Properties。
• 能在当前 Obsidian 阅读视图验证 Mermaid，并记录宿主版本未知项。
• 能写一篇包含目标、契约、步骤、故障、安全、验证和来源的运行手册。
• 能让另一位初学者仅靠文档回答“从哪开始、何时停止、什么算成功”。

与其他知识库的关系

知识库	连接点
Git	纯文本 diff、重命名、冲突与审查。
提示词工程、上下文工程	用清晰层级区分任务、数据、示例与输出，但不把围栏当安全边界。
MCP、Agent Skills	工具与技能文档需要输入输出、错误、副作用、审批和版本。
评测体系、运行监控	测试计划、事件记录和复盘需要可追踪证据。

本轮验收记录

验收日期：2026-07-14。

• 实际结构：13 个 Markdown 文件，其中 7 课正式路线、3 份参考材料、2 个真实练习产物和本目录页。
• 所有渲染态内部链接、标题片段、块 ID 与 1 个真实 embed 均已静态解析，断链为 0；新建或修改内容没有歧义短链接。
• 137 个顶层代码围栏全部闭合；62 个 Mermaid 块均有可识别图类型声明。
• 8 个 PowerShell 围栏通过语法解析；Python、JSON 与 JavaScript 示例通过相应静态语法检查。
• 29 个唯一外部 URL 在验收时返回 HTTP 200；动态事实另经一手文档复核。
• git diff --check 通过；未发现缓存、虚拟环境、大文件、模型产物或疑似真实凭据。
• 未执行 Obsidian Reading View 人工验证，也未使用 Mermaid CLI；callout、Properties、真实块 embed 与 Mermaid 的最终 UI 表现仍需在当前 Obsidian 版本抽查。

主要参考资料

核对日期：2026-07-14。动态版本与勘误详见 参考资料、版本与兼容性说明。

• CommonMark Specification 0.31.2
• GitHub Flavored Markdown Specification 0.29-gfm
• Obsidian Flavored Markdown
• Obsidian：Internal links
• Obsidian：Properties
• Mermaid 官方文档

可能变化：不同渲染器支持的扩展并不一致；Mermaid、Properties 与 Obsidian 的具体行为必须在目标版本复核。本轮已完成文件、frontmatter、围栏和内部链接的静态检查；Obsidian Reading View 人工验证只有实际执行后才能记为完成。