markdown-kb-auto-sync

name	markdown-kb-auto-sync
description	Use when the user wants to sync local Markdown files into the built-in markdown_kb global docs directory and then refresh the knowledge base index

Markdown KB Auto Sync Skill

用于把本地 Markdown 文档同步到 AKM 内置 markdown_kb 插件当前使用的全局文档目录，并在目录变更后显式更新索引。

当前 skill 的核心定位不是"只会上传文件"，而是把下面两件事串成一个稳定工作流：

• 维护 markdown_kb 的原始文档目录
• 触发 sync 或 rebuild 让索引数据库跟上目录状态

---

接口参考

以下接口的具体请求方式、参数说明和使用说明，请参见 API 请求规范。

• GET /api/markdown-kb/status — 获取状态和目录信息
• POST /api/markdown-kb/files/upload — 上传文件（辅助入口）
• POST /api/markdown-kb/files/bind-workspace — 绑定工作目录
• POST /api/markdown-kb/sync — 增量同步
• POST /api/markdown-kb/rebuild — 全量重建

---

真实目录规则

1. 优先调用状态接口（参见上文接口参考），读取运行时返回的 docs_dir。
2. 如果状态接口不可用，再回退到当前默认目录 ~/.akm/markdown_kb/docs。
3. 不要把 ~/.akm/markdown-kb/docs 当成当前既定实现，因为仓库中的真实目录名是下划线 _。

---

适用场景

• 用户要把一个或多个 .md 文件加入知识库
• 用户已经直接修改了 markdown_kb 的文档目录，需要更新索引
• 用户要把一个本地目录中的 Markdown 文档批量收敛进知识库
• 用户要在文档变更后执行增量同步或全量重建
• 用户要先为一个新项目初始化一份标准知识库骨架文档，再写入知识库

---

使用原则

1. 默认把 docs_dir 当作全局知识库源目录维护。
2. 默认优先直接维护 docs_dir 中的文件，不强制要求走上传接口。
3. 文件进入 docs_dir 不等于已经进入索引数据库；目录变更后必须显式执行 sync 或 rebuild（参见上文接口参考）。
4. 日常小范围变更优先使用 sync，大范围替换或索引疑似漂移时使用 rebuild。
5. 当前实现把文档目录当作扁平文件池处理，同名文件会互相覆盖；写入前必须先检查文件名冲突。
6. 只处理 .md 文件，不改写 Markdown 内容本身，除非用户明确要求做内容编辑。
7. 如果用户明确要求"初始化知识库"，允许由 skill 生成一份新的 Markdown 知识模块文档，再写入 docs_dir。

---

数据分层

需要始终区分两层数据：

1. 原始文档层

• 目录：docs_dir（通过状态接口获取）
• 内容：Markdown 原文文件
• 作用：作为 markdown_kb 后续切片和建索引的唯一来源

2. 索引数据库层

• 目录：通常位于 ~/.akm/markdown_kb/index_store/（通过状态接口获取）
• 内容：切片结果、向量、索引元数据
• 作用：供 query / ask 实际检索使用

重要说明：

• 上传接口（参见上文接口参考）只会把文件写入原始文档层
• 直接维护 docs_dir 不会天然丢失原文
• 但如果目录变了却没执行 sync 或 rebuild，索引数据库就会过期

---

初始化功能

当用户要求"初始化知识库"时，skill 可以额外执行一次知识模块文档初始化。

初始化目标

• 生成一份新的 Markdown 文档，作为该项目的知识库入口文档
• 默认文件名直接使用项目名称，便于用户按项目维度维护
• 文档内容默认应按固定知识模块组织，而不是自由散写项目概述
• 初始化结果应优先覆盖方法论、问题解决方案、概念原理、外部知识精炼和关联映射

文件名规则

1. 先获取项目名称，优先取用户显式提供的名称，其次取项目 README.md 一级标题，再其次取仓库目录名。
2. 初始化文档的默认文件名格式为 <project_name>.md。
3. 如果目标文件已存在，先提示用户覆盖风险；未得到明确允许前，不要静默覆盖。

初始化内容

初始化文档不再依赖前端/后端模板文件，而是直接围绕当前项目生成一份固定五模块结构的知识文档。推荐模块如下：

• P1. 方法论（怎么做）：操作流程、步骤、SOP、最佳实践、黄金法则、决策框架
• P2. 问题解决方案（踩坑记录）：错误现象、原因、修复方案、调试过程、预警提示
• P3. 概念原理（是什么 + 为什么）：技术架构、设计模式、业务逻辑、领域模型、底层原理
• P4. 外部知识精炼（消化后的外部资料）：书籍/文章摘要、会议纪要、培训收获、行业标准要点
• P5. 关联映射（知识之间的关系）：对比关系、依赖关系、分类体系、选型映射

五模块写作规则

P1. 方法论（怎么做）

• 写"怎么做"，不要写成纯概念说明。
• 至少包含 1 个完整流程，按步骤编号写清楚。
• 优先收录可以直接执行的 SOP、检查表、决策树、发布流程、排障流程。
• 每条规则尽量带触发条件，例如"什么时候用 A，什么时候用 B"。
• 示例小节：发布流程、故障处理 SOP、代码审查 checklist。

P2. 问题解决方案（踩坑记录）

• 写"遇到什么问题、为什么、怎么修复、如何避免再踩坑"。
• 推荐固定格式：现象 -> 原因 -> 修复方案 -> 预防建议。
• 优先写实际报错、调试过程、修复命令、回滚方案和预警信号。
• 如果问题来自外部依赖，补上依赖版本、配置项或环境条件。
• 示例小节：MySQL 连接池耗尽、同步后知识库仍命中旧内容。

P3. 概念原理（是什么 + 为什么）

• 写"是什么、为什么、原理是什么"，不要只列名词。
• 适合放技术架构、设计模式、领域模型、流程图式解释、系统边界。
• 先给一句定义，再给应用场景，最后给关键约束或取舍。
• 如果涉及对比，先说明各自职责，再说明为什么这个项目选了其中一种。
• 示例小节：插件化转发链路、知识库原始文档层与索引层。

P4. 外部知识精炼（消化后的外部资料）

• 只收录已经消化过的外部信息，不直接堆链接。
• 写摘要时优先保留"结论、适用边界、对当前项目的影响"。
• 如果是书籍、文章、培训或会议内容，尽量提炼成能执行的要点。
• 必要时标注来源类别，但不要求逐字复述原文。
• 示例小节：某技术大会笔记、《系统设计面试》要点。

P5. 关联映射（知识之间的关系）

• 写知识之间的关系，而不是孤立条目。
• 优先表达对比、依赖、分类和映射关系，例如 A vs B、上游 -> 下游、类目树。
• 适合放选型表、关系图、决策矩阵、术语映射。
• 如果某个概念会影响多个模块，应在这里做交叉引用。
• 示例小节：SQL vs NoSQL、供应商能力映射、插件与接口关系图。

使用原则：

1. 优先基于当前仓库中的 README、设计文档和关键代码结构生成五模块内容。
2. 如果资料不足以支持某个细节，明确写"资料中未提及"或不写该结论。
3. 如果某个模块缺少足够资料，不要臆测补全；保留空白或明确标注资料不足。
4. 每个模块都尽量给出小标题和条目化内容，避免长段散文。

初始化工作流

适用场景：用户刚开始维护某个项目的知识库，希望先落一份可检索的知识模块总文档。

推荐步骤：

1. 调用状态接口（参见上文接口参考）获取当前 docs_dir
2. 识别项目名称并生成目标文件名
3. 检查目标文件名是否已存在；若存在，先提示覆盖风险
4. 基于当前项目资料整理五模块知识文档
5. 将五模块知识文档写入目标 Markdown 文件
6. 将文件写入 docs_dir
7. 调用增量同步接口，使用 {"apply": true}（参见上文接口参考）
8. 再次调用状态接口，确认索引已收录该初始化文档

初始化边界

• 初始化功能只创建一份 Markdown 知识模块文档，不会真的在磁盘中创建目录树
• 初始化文档仍然属于原始文档层，需要后续 sync 或 rebuild 才能进入索引数据库
• 如果用户后续提供了更完整的项目知识库文档，可以继续覆盖或新增，不要求保留初始化文档的原始结构

---

推荐工作流

日常维护

适用场景：少量新增、修改或删除文档。

推荐步骤：

1. 调用状态接口确认当前 docs_dir
2. 直接把目标 .md 文件写入、更新或删除到该目录
3. 调用增量同步接口，使用 {"apply": true}
4. 再次调用状态接口查看同步结果

批量替换

适用场景：一次性替换大量文档，或调整了切片配置。

推荐步骤：

1. 先把 docs_dir 调整到最终目标状态
2. 调用全量重建接口
3. 重建完成后调用状态接口检查状态、健康和检索结果

同名文件处理

适用场景：多个来源目录中出现同名 .md 文件。

推荐步骤：

1. 写入前先做文件名去冲突
2. 保证 docs_dir 中每个 .md 文件名唯一
3. 再执行 sync 或 rebuild

不要假设不同来源的同名文件可以自然并存；当前实现会直接覆盖旧文件。

---

执行建议

1. 用户说"把这些 markdown 加入知识库"时，先判断是直接维护 docs_dir 更合适，还是需要调用上传接口。
2. 用户说"我已经手动改过目录了"时，优先执行状态检查和索引更新，不要重复上传。
3. 用户说"为什么检索不到新文档"时，优先检查是否只是原文目录已更新但索引数据库尚未同步。
4. 遇到同名文件时，先提示覆盖风险，再决定是否重命名后写入。
5. 如果只是日常小改动，默认 sync；如果是大批量替换，默认 rebuild。
6. 用户说"先帮我初始化一个知识库"时，先生成五模块知识文档，再执行一次 sync。

---

最小执行模板

当用户要求同步 Markdown 文档到知识库时，优先遵循这个顺序：

1. 调用状态接口获取 docs_dir
2. 检查待同步文件是否都是 .md
3. 检查是否存在同名冲突
4. 直接把文件写入或同步到 docs_dir
5. 调用增量同步接口，默认使用 {"apply": true}
6. 再次调用状态接口，确认索引已更新

如果是大范围调整，则把第 5 步替换为调用全量重建接口。

如果用户要求初始化知识库，则优先遵循这个顺序：

1. 调用状态接口获取 docs_dir
2. 确认项目名称来源
3. 按项目名称生成 .md 文件名
4. 基于当前项目资料整理五模块知识文档
5. 将五模块知识文档写入目标 .md 文件
6. 把文件写入 docs_dir
7. 调用增量同步接口，默认使用 {"apply": true}
8. 再次调用状态接口，确认索引已更新