Obsidian-Knowledge-Base/X-Knowledge-Base/COMMIT_GUIDELINES.md

提交规范

本仓库同时管理 raw/ 原始资料和 wiki/ 知识页，提交信息需要能说明“这次变更改变了什么知识资产”。

基本格式

推荐格式：

<type>: <summary>

示例：

ingest: add source on llm wiki workflow
wiki: refine entity links for obsidian and joplin
lint: repair orphan pages and missing backlinks
docs: update repository collaboration rules
raw: add screenshots for browser clipping workflow

推荐类型

ingest

用于把新资料导入知识库，并同步更新相关页面。

适用场景：

• 新增原始资料到 raw/
• 新建 source-*.md 摘要页
• 更新相关实体页、概念页、工作流页
• 更新 wiki/index.md 和 wiki/log.md

示例：

• ingest: add article on llm wiki ingestion
• ingest: import joplin notes on linux networking

wiki

用于整理已有知识页，不一定伴随新资料导入。

适用场景：

• 重写摘要
• 合并重复概念
• 增补交叉引用
• 优化页面结构
• 把查询结果回写为新页面

示例：

• wiki: consolidate workflow pages for source summaries
• wiki: add backlinks between entity and concept pages

lint

用于知识库维护和健康检查后的修复。

适用场景：

• 修复断链
• 修复孤立页面
• 补齐缺失来源
• 标注冲突或过时内容
• 调整索引覆盖

示例：

• lint: repair broken wikilinks in index
• lint: mark outdated claims in tool comparison pages

docs

用于仓库说明文档和协作规则更新。

适用场景：

• 更新 README.md
• 更新 CLAUDE.md
• 增加模板、流程文档、说明文档

示例：

• docs: add commit guidelines and log templates
• docs: clarify raw and wiki collaboration boundary

raw

用于只涉及原始资料资产的补充或整理，且暂时不改 wiki/。

适用场景：

• 新增截图、附件、原始导出
• 调整原始资料目录结构
• 补充缺失附件

示例：

• raw: add source images for joplin export
• raw: import clipped articles on browser automation

编写原则

1. 一次提交只表达一个主要意图，不要把导入、重构、清理混在同一条提交里。
2. summary 尽量写具体主题，不要只写 “update files” 或 “fix stuff”。
3. 如果一次导入覆盖多个主题，优先按主题拆分提交。
4. 如果同时修改 raw/ 和 wiki/，通常优先使用 ingest。
5. 如果只是补文档或规则，使用 docs，不要混用 wiki。

推荐节奏

导入资料时

1. 放入 raw/
2. 更新 wiki/
3. 检查 wiki/index.md 和 wiki/log.md
4. 提交：ingest: ...

整理知识时

1. 修改相关页面
2. 修复交叉引用
3. 必要时记录到 wiki/log.md
4. 提交：wiki: ...

维护知识库时

1. 跑一轮人工或 LLM lint
2. 修复断链、孤立页、缺失来源
3. 追加维护记录
4. 提交：lint: ...

不推荐的提交信息

• update
• fix
• change wiki
• notes
• misc

这些信息无法帮助你在以后快速看懂知识库是如何演化的。