dootask/resources/ai-kb/_schema/chunk-style.md

# Chunk 写作风格指南

这里的内容**只给 LLM 读**，不是给人。写作风格和习惯与人类文档完全不同。这份指南强约束所有 chunk 的形态。

## 核心原则（按重要程度排）

1. **每个 chunk 单独可读**。RAG 切块后会丢失上下文。读者只能看到这一段，前后段都不存在。所以禁止「如上所述」「在前一节」「参见 task.md 第二段」这类指代。
2. **关键名词在第一段出现一次**。提升 dense embedding 召回。
3. **显式同义词**。「子任务」和「subtask」、「列」和「看板列」、「待办」和「todo」要在 `aliases` 字段里并列。
4. **显式否定信息**。"X 不支持，因为 Y" 是高价值信息，能让 LLM 拒绝编造。
5. **结构化优于叙述化**。能用编号列表就别写段落；能用表格就别写散文。
6. **不依赖截图**。所有信息用文字描述，必要时描述按钮位置（"页面右上角"）。

## 字数指引

- 正文（不含 frontmatter）**200-1500 字符**（lint 强制）
- 黄金区间 **250-700 字符**（最贴近切块器目标 512 token）
- 短于 200 字符的内容合并到相关 chunk；长于 1500 字符的必须拆成多篇用 `[[id]]` 互链

## 标题结构

只用 `H1` 和 `H2`。**不要用 H3**。

```markdown
# {title}                        ← 与 frontmatter title 一致，H1 只能一个

## 入口 / 是什么 / 操作步骤      ← H2，按 type 选择模板（见下）
...

## 字段说明 / 不支持项 / 相关
...
```

切块器按标题切；层级浅检索更稳。

## 各 `type` 推荐小节模板

### `concept`（是什么）
```
## 定义
（一句话）

## 关键属性
- 列表化字段

## 与其他概念的关系
- 父子 / 包含 / 依赖
```

### `howto`（怎么做）
```
## 入口
- 桌面端 / 移动端的具体路径

## 操作步骤
1. 编号步骤

## 字段默认值
（可选，表格更清晰）

## 不支持
- negative 中已列的项也在正文重复一次
```

### `faq`（为什么 / 出错怎么办）
```
## 问题
（一句话描述现象）

## 原因
（短解释）

## 解决
1. 步骤
```

### `menu-map`（在哪里）
```
## 路径
桌面端：左侧栏 → 应用 → 审批
移动端：底部 Tabbar → 应用 → 审批
快捷键：无

## 权限要求
- end-user 可见
```

### `glossary`（术语表）
通常一个 feature 一篇，结构化列表：
```
## task（任务）
**别名**：todo, 待办, 卡片
**定义**：一个待完成的工作项，归属于某个项目。

## subtask（子任务）
...
```

### `shortcut`（快捷键）
表格优先：
```
| 操作 | 桌面端 | 移动端 |
|---|---|---|
| AI 助手 | Cmd+I | （无） |
```

## 同义词处理

`aliases` 字段里列 ≥ 1 条用户**可能怎么提问**的口语化说法。不是堆关键词，是模拟真实提问：

✅ 好的：
```yaml
aliases:
  - 怎么建任务
  - 新建待办
  - 加一条 todo
  - 我要建任务
```

❌ 不好的（关键词堆砌）：
```yaml
aliases:
  - 任务
  - 创建
  - 添加
  - 新建
  - 任务管理
```

## 否定信息（negative）的写法

业界实测：在 RAG chunk 里**显式写"不支持 X 因为 Y"**，能显著降低 LLM 编造率。

```yaml
negative:
  - 快速创建不支持设置截止时间，需用完整创建
  - 审批中心不支持嵌套子审批
  - 任务删除后 30 天内可恢复，30 天后无法找回
```

正文也要重复一次（让 chunk 自包含）：
```markdown
## 不支持
- 快速创建不支持设置截止时间，需用完整创建
```

## 跨引用 `[[id]]` 语法

引用其他 chunk 用 `[[id]]`，lint 会校验目标存在：

```markdown
想设置更多字段，切到完整创建模式：[[task.create.howto.full]]
任务的可见性规则见：[[task.visibility.concept]]
```

这种引用比"参见 task.md 第二段"鲁棒得多。

## 正例 vs 反例

### 反例 1：依赖截图

```markdown
点击下图红框中的按钮即可创建任务。
（截图：xxx.png）
```

问题：LLM 看不到截图。
改：
```markdown
点击项目详情页右上角的「+」按钮，选「快速添加任务」。
```

### 反例 2：跨章节指代

```markdown
如上一节所述，权限分三级。这里只讨论第二级。
```

问题：切块后看不到「上一节」。
改：
```markdown
项目角色有三级：成员、负责人、管理员。本文只讲负责人。
（或用 [[project.role.concept]] 指向定义文）
```

### 反例 3：故事化叙述

```markdown
小王是公司的项目经理，他每天早上都要看一下今天的任务。他打开 DooTask，
点击仪表盘，看到今日待办...
```

问题：信息密度低。
改：
```markdown
## 入口
左侧栏「仪表盘」→「今日待办」卡片

## 显示内容
- 今天截止的任务
- 今日新分配的任务
- 已超期的任务（带红色标记）
```

### 反例 4：信息不完整 / 缺否定信息

```markdown
# 任务标签

任务可以打标签便于分类。
```

问题：信息量太少，且没说限制。
改：
```markdown
# 任务标签

## 是什么
任务可以打多个标签，用于分类和筛选。标签按项目隔离，不跨项目共享。

## 操作
- 添加：任务详情页 →「标签」字段 → 选择或新建
- 删除：标签上的 × 按钮
- 项目内管理：项目设置 →「标签管理」

## 不支持
- 标签不跨项目共享（每个项目独立维护）
- 单个任务最多 10 个标签
- 标签名 ≤ 20 字符
```

## 写完检查清单

提交 PR 前，每条 chunk 自检：

- [ ] 不读其他 chunk 也能懂这一篇
- [ ] 关键名词在第一段出现
- [ ] `aliases` 至少 1 条且像真实提问
- [ ] 有 `## 不支持` 小节（或在 frontmatter `negative` 写明"无已知限制"）
- [ ] 没有截图、没有跨章节指代
- [ ] 正文长度在 200-1500 字符
- [ ] `last_verified` 是当前主程序版本号
- [ ] 跨引用 `[[id]]` 目标存在