SuperAPI AI 工具集

docs-standards

写作与研究

查看项目

更新于 10-16 09:54

技能介绍

用途:为 Squad 文档提供统一写作规范,遵循 Microsoft 风格指南并附加 Squad 专属约定,以保持文档一致性、提升可发现性。

主要能力与规则:标题使用句子式大小写,如“Getting started”而非“Getting Started”;使用主动语态、第二人称、现在时;正文中不用 & 符号,应写 and,代码、品牌名或 UI 元素除外。

格式约定:优先可扫读性,叙述性段落最多 3-4 句,列表用项目符号,结构化数据用表格;功能或场景页顶部放用户可直接复制的“Try this”提示;预览功能顶部加实验性警告标注;正文末尾放相关页面交叉引用。

结构:H1 标题 → 警告/标注 → Try this 代码 → 概述 → 分隔线 → H2 内容章节。

测试同步:向 features/、scenarios/、guides/ 添加文档页时,必须在同一提交中更新 test/docs-build.test.ts 中对应的 EXPECTED_* 数组。

正确示例包含句子式标题、实验性警告、Try this 的 bash 代码块(squad init)及二级章节。反模式包括:为好看使用标题式大小写、被动语态或第三人称、长而密的段落、添加文档却不更新测试断言、在代码块外使用 &。

限制:官方未提供更多实现细节、安装方式或适用范围,暂未提供。