# 提交规范

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

## 基本格式

推荐格式：

```text
<type>: <summary>
```

示例：

```text
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`

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