# 知识库维护指南

# 项目定位

本项目是由 AI 协助整理和维护的知识库，通过文件夹组织主题，使用 Markdown 记录知识。维护目标是让内容准确、易于查找、便于理解和持续更新。

本指南适用于仓库内所有文件；子目录中的 AGENTS.md 可以补充该目录的专用规范。

# 工作原则

• 修改前先阅读相关目录和文档，理解已有分类、命名和写作习惯。
• 默认使用简体中文；技术术语、代码标识符和引用标题保留必要的原文。
• 优先更新已有内容，避免为同一知识点创建重复文档。
• 修改范围应围绕当前任务，避免无关的重写、重命名或目录调整。
• 保留用户已有的内容和未完成修改；未经明确要求，不删除有价值的记录。
• 信息不足时明确标注不确定性，不编造事实、来源、链接或验证结果。

# 目录与文件

• 知识库的所有知识原文与主题目录统一存放在 docs/ 目录下（如 docs/languages/ 等）；仓库根目录仅保留构建脚本、环境配置与全库级说明，后续编写的所有知识库原文均必须放置在 docs/ 目录下。
• 按主题在 docs/ 下组织文件夹，同一目录下的内容应具有清晰的共同主题，避免不必要的深层嵌套。
• 文件与目录名称应简洁、明确，优先沿用所在目录的命名风格，避免使用“未命名”“其他”“最终版”等含糊名称。
• 每篇文档围绕一个明确主题；只有在内容可以独立阅读和维护时才拆分文件。
• 需要导航时使用目录下的 README.md 说明主题范围并列出主要文档；新增或移动文档时同步更新相关导航（如根目录 README.md 与 docs/README.md）。
• 图片和附件放在相关主题附近的 assets/ 目录，使用有意义的文件名，并通过相对路径引用。
• 不提交临时文件、缓存、密钥、访问令牌或未经授权的敏感资料。

# Markdown 写作

• 每篇文档使用一个一级标题，以二级及以下标题组织内容，避免跳级。
• 开头简要说明主题、用途或核心结论，再展开必要的解释、步骤和示例。
• 按内容需要添加适用条件、限制、参考资料等部分，不强制套用无关章节。
• 优先使用清晰的段落；并列信息使用列表，比较信息使用表格，命令和代码使用标明语言的代码块。
• 仓库内的文档和附件使用相对链接，引用具体章节时检查标题锚点。
• 示例应说明必要的前提；未执行过的命令或代码不得描述为已验证。
• 避免堆砌空泛描述、重复总结和没有实际信息的占位章节。

# 知识准确性与来源

• 区分可核验的事实、个人观点、推断和待确认事项。
• 引用外部资料时保留可追溯的来源链接，优先使用官方文档、原始论文或其他一手资料。
• 涉及版本、价格、政策、产品能力等易变信息时，注明适用版本或核验日期；日期使用 YYYY-MM-DD 格式。
• 无法核验的内容应明确标记为“待核验”，不要将猜测写成确定结论。
• 整理资料时用自己的语言提炼关键内容，保留必要的上下文和适用范围，避免无授权的大段转载。
• 发现内容冲突或过时时，核查来源并更新相关表述；必要时说明历史版本的适用范围。

# 修改后的检查

• 检查文档结构、措辞、代码块和 Markdown 格式是否完整、清晰。
• 检查新增或修改的内部链接、图片路径与导航是否指向正确位置。
• 移动或重命名文件后，搜索并更新仓库中的相关引用。
• 如果仓库已有 Markdown 检查工具，运行与本次修改相关的检查；不要仅为普通文档修改引入额外工具链。
• 提交前检查差异，确认没有无关改动、临时文件或敏感信息；说明未能完成的核验。

# Git 提交规范

所有 Git 提交必须遵循 Conventional Commits，格式为：

纯文本<type>[可选 scope]: <简明描述>

[可选正文]

[可选页脚]

• type 使用小写英文，冒号后保留一个空格，描述默认使用简体中文。
• scope 可省略；需要时使用稳定、明确的主题或目录名称。
• 提交标题准确描述本次修改，不使用“更新内容”“修改文件”等含糊表述。
• 每次提交围绕一个逻辑完整的变更，提交前检查暂存区，避免混入无关修改。
• 仅在用户要求提交或任务已明确授权提交时执行 Git 提交；编辑文档本身不代表需要自动提交。

常用类型：

示例：

纯文本docs(rag): 添加检索增强生成的基础说明
docs: 修复知识库索引中的失效链接
chore: 完善 AGENTS.md 维护与提交规范
fix(scripts): 修复链接检查脚本的路径解析

如果变更确实破坏既有工具接口或使用约定，在类型或作用域后添加 !，并在正文或 BREAKING CHANGE: 页脚中解释影响及迁移方式。普通文档增补不应标记为破坏性变更。