Dbk Doc Style

---
name: dbk-doc-style
description: |
  检查与生成中英文项目文档（README、设计文档、PR 描述、release notes、周报/报告、邮件、博客等）的文风，遵循通用写作规范：简洁主动、可扫描结构、中文全角标点与去冗余、英文 Title Case 与 Oxford comma、统一术语、对外文档不泄漏内部信息。当用户要求检查文风、帮你看看文档写得怎么样、指出哪里写得不好、润色改写、生成文档正文，或提到"文风""语态""措辞""标点""冗余""啰嗦""正式一点""简洁一点"时使用，也适用于任何需要写正文输出的场景。
metadata:
  author: DBinK
  version: "0.1.0"
---

# 项目文档文风规范

通用项目文档写作规范。用于两件事：**检查**已有文档是否合规，**生成**新文档正文。中英文都适用，规则细节在 [references/style-guide.md](references/style-guide.md)。

## 适用范围

- **适用**：README、设计文档、PR 描述、release notes、周报/报告、邮件、博客、对外公告等任何正文
- **不适用**：代码本身（走 dbk-python-style 等语言技能）、仓库资产的结构化模板（README/CHANGELOG 固定结构不在本技能范围）

## 模式选择

根据用户指令选择模式：

| 用户意图                                       | 模式                                           |
| ---------------------------------------------- | ---------------------------------------------- |
| "检查文风""看看写得怎么样""查标点"             | **检查**：报告问题，不自动改，除非用户明确要求 |
| "润色""改得简洁点""帮我写""生成 release notes" | **生成/改写**：按规范输出或修改文件            |

## 两种模式的工作流

### 检查模式

1. 加载 [references/style-guide.md](references/style-guide.md)；内容含中文时再加载 [references/zh-colloquial-lexicon.md](references/zh-colloquial-lexicon.md)
2. 判定语言（英文 / 中文 / 混排），按类别逐项检查
3. 逐条应用**价值过滤**与**语义保全**（见下）
4. 输出报告，用**精确原文**定位问题，不用行号（行号随版本漂移，原文可跨版本搜索）
5. 询问"发现 N 个问题，要自动修复吗"，用户确认后才改文件

### 生成/改写模式

1. 加载同样的规则文件
2. 按规范写作或改写
3. 交付前用下方自检清单过一遍

## 核心心法（最高优先级）

1. **先定读者再定规则**。对外文档（README、release notes、公开 PR）不写内部代号、未定稿状态（已定稿/未验证/测试中）、内部工具名、产线流程；内部文档（设计文档、代码评审）可用。给读者的信息要写明**能依赖到什么程度**，不绝对承诺（"保证""永不"）。
2. **改前问价值**：这个改动是否让文本显著更清晰、更准确？只删一个词没有结构收益就不改。
3. **删前问语义**：要删的词是否承载语义？删了变义就不删。
4. **规则服务于可读性，不是字数**。拿不准就保持原样。

## 检查清单

详细规则与例子见 references/style-guide.md，这里只列类别：

- [ ] **英文**：标题 Title Case、Oxford comma、主动语态现在时、数字 0–9 拼写、无冗余副词（quite/very/quickly/easily）
- [ ] **中文**：全角标点、正文不用分号 `；`（拆句、改顿号/逗号或用列表）、口语化去公文腔、删冗余（的/了/进行/可以/需要注意的是）、对照口语词表
- [ ] **结构**：短段落（3–7 行）、标题前置关键词、平行标题、标题不加句号
- [ ] **一致性**：同一概念全文同词（如"固件/韧体"统一），产品名大小写唯一；有术语表就查表
- [ ] **读者边界**：不绝对承诺、不拟人化（设备"会想/决定"）、内部信息不泄漏

## 例外（不要误报、不要误改）

- **警告类文案**：警示语气词（如"请勿"）是有意为之的强度表达，保留
- **发布记录**：以结构为主，语调从宽，礼貌用语不必删
- **固定句式**：约定俗成的引用语、指引套话不算冗余
- **代码标识符、命令、URL、文件名**：按原文保留，不改写不翻译
- **引文/他人原文**：不改动

## 注意事项

- 用户说"看看/评估下文档写得如何"是**咨询类**指令，只出报告不自动改；"改/润色"才是改动类。咨询类里即使发现明显问题也只指出。
- 中英混排文档：按语言分别应用对应规则。
- "你" vs "您"：团队没有统一约定时，不强制改某一种，保持一致即可。
- 检查报告格式：

```
## 文风检查报告

**范围：** <文件路径或"粘贴文本">
**语言：** <English / 中文 / 混排>
**问题数：** <N>

| 类别 | 当前文本 | 建议修改 |
|------|---------|---------|
| 冗余词 | `对文档进行了更新` | `更新了文档` |
```