docs-style

name: docs-style description: 将草稿文档转换为符合项目写作风格的正式文档。当用户调用 /docs、提到润色文档、或 docs/ 下的 markdown 文件含有 todo[docs] 标记时触发。处理 VitePress markdown（中文为主），基于深度风格内化——不是格式规则而是写作思维模式。

文档风格助手

将 todo[docs] 标记的草稿内容改写为符合本项目文档声音的正式文本。本 skill 基于原则而非样例运作——可泛化到任何文档类型，包括从未见过的新类型。

执行流程

1. 扫描

定位目标文件中的 todo[docs] 标记。

指定文件路径（/docs docs/feat/ags.md）：仅扫描该文件。 不指定路径（/docs）：扫描所有 docs/**/*.md（默认排除 docs/en/**）。

标记语法：

块级：

<!-- todo[docs] -->
草稿内容
<!-- /todo[docs] -->

带类型覆盖：

<!-- todo[docs] type=changelog -->
草稿内容
<!-- /todo[docs] -->

行内：

某段草稿文本 <!-- todo[docs] -->

行内作用域：仅改写标记前同一行的文本，绝不吞并下一行。

解析安全规则：

• 忽略代码块、HTML 块、YAML frontmatter 内部的标记
• 若块级开标签无对应闭标签 → 报错并停止，绝不猜测边界

2. 分类

根据路径判断文档类型（标记 type= 可覆盖）：

从 references/skeletons.md 加载对应骨架。

3. 改写

应用下方声音合约和决策框架。仅改写 todo[docs] 标记内的内容。周围文本 = 只读上下文；可调整边界过渡，但绝不改写现有文本。

事实锁定规则：

• 禁止编造草稿/上下文中不存在的版本号、命令、参数、URL、路径、配置键、平台特性或功能行为
• 关键事实缺失时，保留简洁的 TODO 占位符，不要猜测

4. 校验

运行自检清单（见第 5 层）。任何一项不通过则修订后再应用。

5. 应用

移除 todo[docs] 标记，通过 Edit 工具应用变更。 --review 标志：仅输出建议，不实际编辑。

第 1 层：声音合约

三条不可妥协的原则，定义了本项目作者的思维和写作方式。每句话都必须通过全部三条检验。

V1：机制优先（Mechanism over Motivation）

描述程序做了什么。绝不解释为什么有用——读者已经知道自己为什么来。

❌ 聚合搜索是一个强大的功能，可以帮助用户提高搜索效率 ✅ 从下文输入方式获取一组搜索词，然后将多个搜索列表一次性在预览窗口中列出，后面就是常规选择下载流程

❌ 此功能可以方便地管理您的剪贴板历史 ✅ 选择符合适用性的网站即可开启使用，点击按钮即触发流程

V2：极致简洁（Radical Brevity）

能用 3 个字说完的绝不写 10 个。省略主语。不加句号。一个事实一行。片段优于完整句。

❌ 该功能的作用是为了帮助用户翻越防火墙的限制 ✅ 翻墙用

❌ 这个选项会影响后台下载任务的速度 ✅ 影响后台下载速度

❌ 用户需要注意的是，当日志等级配置不为空时，控制台不会打印信息 ✅ 当LOG_FILE不为空时，控制台不会打印任何信息

节奏模式：中文片段 + 行尾 （两空格换行）实现视觉分隔。换行 = 新事实。事实之间不加连接词。

V3：对等直说（Peer Directness）

无敬语。无客套。无铺垫。直接陈述或命令。

❌ 请您按照以下步骤操作：首先，请点击"文件"按钮 ✅ 👉点击 \from 文件` 按钮`

❌ 建议您在开始之前先了解一下相关配置 ✅ 有自定义需求的，参考 [🔨主配置文档](/config/index.md) 进行设置

❌ 接下来，我们来看看如何使用聚合搜索功能 ✅ （直接开始新段落，不加过渡）

第 2 层：决策框架

容器选择树

问：这段信息的角色是什么？

规则：如果内容是信息主流程，不要包在容器里。 容器是对主流程的标注，不是主流程本身。

内容单元选择

问：这段信息是什么形状？

平台差异内容

内容因操作系统而异时：

• 简短差异：win: 和 mac: 标签同行，用   分隔
• 较长差异：[win] 和 [macOS] 带括号标签，各自独立代码块

未知类型意图路由

当文档类型为 unknown 时，在使用回退骨架前先根据草稿信号判断意图：

第 3 层：骨架路由

各文档类型的结构骨架详见 references/skeletons.md。

该文件定义了每种类型（feature、changelog、faq、config、deploy、dev）的信息流顺序，以及一个 unknown 回退骨架用于新/未知文档类型。

核心原则：遵循骨架的信息流顺序，即使当前文档库中没有匹配的现成样例。骨架就是泛化层。

第 4 层：负约束

AI 绝对不能做的 10 种行为。每条包含为什么是错的和应该怎么做。

N1：禁止价值推销

❌ 描述功能的好处/强大/便利 → 描述机制。读者知道自己要什么。

N2：禁止敬语和客套

❌ 请您 / 建议您 / 您可以考虑 / 您可能需要 → 直接陈述或命令式。翻墙用，不是 您可以使用代理来翻墙

N3：禁止超过 3 句的段落

❌ 4 句以上连续散文 → 拆成独立行或列表。一个事实一行。用 换行。

N4：禁止翻译技术术语

❌ scrapy (一个Python爬虫框架) / Redis (内存数据库) → 保留英文内联：使用 scrapy 框架。读者看得懂这些术语。

N5：禁止词典式解释

❌ 剪贴板是操作系统提供的一种临时数据存储机制 → 跳过定义，直接说用法：需配合剪贴板软件使用

N6：禁止自创新结构

❌ 发明新的章节布局、新的 emoji 体系、或骨架中不存在的结构模式 → 遵循现有骨架。新功能用 unknown 回退。

N7：禁止容器滥用

❌ 把每段都包在 ::: tip 或 ::: info 里 → 大多数内容是纯文本。容器是手术刀式标注，不是默认包装。

N8：禁止过渡性填充

❌ 接下来我们来看 / 首先让我们了解 / 下面将介绍 / 总之 → 直接开始新段落。过渡句是噪音。

N9：禁止编造事实

❌ 编造草稿/上下文中不存在的版本号、CLI 参数、配置键、URL 或平台特性 → 只使用来源材料中存在的事实。缺失的事实 → TODO 占位符。

N10：禁止作用域溢出

❌ 改写 todo[docs] 标记外的文本或添加超出草稿范围的内容 → 仅改写标记区域。周围文本是只读上下文。

第 5 层：自校验清单

改写完成后，应用前逐项检查。任何一项不通过则修订。

□ 简洁性: 所有段落 ≤ 3 句？
□ 禁用词: 不含 请您/建议您/接下来/首先让我们/总之/您可以考虑？
□ 机制性: 没有句子在描述功能为什么有用（只描述做了什么）？
□ 容器合理性: 每个 ::: 容器符合决策框架中的角色？
□ 术语完整性: 无不必要的英文技术术语中文翻译？
□ 骨架一致性: 信息流顺序符合对应类型骨架？
□ 标记清理: 所有 todo[docs] 标记已移除？
□ 保护完整性: frontmatter/代码块/HTML块/链接URL/图片路径未被修改？
□ Emoji: 页面标题有 emoji？Changelog 用 +？功能条目用 ✨🌐🐞？
□ 反引号: 文件路径、配置键、UI 元素、命令都用反引号包裹？
□ 作用域: 标记外的文本未被修改？
□ 事实性: 无编造的版本号/命令/URL/配置键？缺失事实用 TODO？

格式参考

页面标题

始终 # <emoji> <标题>：# 🔎聚合搜索、# 🕑 更新历史、# ❓ 常见问题

Changelog 列表符

始终用 +，不用 - 或 *。功能前缀：✨ 新增 / 🌐 站点 / 🐞 修复。

操作提示

👉点击 \按钮名` 操作描述`

交叉引用

[📋跳转阅读 > 使用](/feat/clip) / [🔗适用的网站](/feat/#适用性) / [🔨主配置文档](/config/index.md)

反引号目标

文件路径、配置键（sv_path）、UI 元素（from 文件）、命令（cgs-cli）、格式（.cbz）

受保护元素（禁止修改）

YAML frontmatter、::: 容器结构、代码块内容、HTML 块、链接 URL、图片路径、VitePress callout（> [!TIP]、> [!Info] 等）