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。

# {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 条用户可能怎么提问的口语化说法。不是堆关键词，是模拟真实提问：

✅ 好的：

aliases:
  - 怎么建任务
  - 新建待办
  - 加一条 todo
  - 我要建任务

❌ 不好的（关键词堆砌）：

aliases:
  - 任务
  - 创建
  - 添加
  - 新建
  - 任务管理

否定信息（negative）的写法

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

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

正文也要重复一次（让 chunk 自包含）：

## 不支持
- 快速创建不支持设置截止时间，需用完整创建

跨引用 [[id]] 语法

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

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

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

正例 vs 反例

反例 1：依赖截图

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

问题：LLM 看不到截图。 改：

点击项目详情页右上角的「+」按钮，选「快速添加任务」。

反例 2：跨章节指代

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

问题：切块后看不到「上一节」。 改：

项目角色有三级：成员、负责人、管理员。本文只讲负责人。
（或用 [[project.role.concept]] 指向定义文）

反例 3：故事化叙述

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

问题：信息密度低。 改：

## 入口
左侧栏「仪表盘」→「今日待办」卡片

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

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

# 任务标签

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

问题：信息量太少，且没说限制。 改：

# 任务标签

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

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

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

写完检查清单

提交 PR 前，每条 chunk 自检：

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