Back to search
simplified-technical-chinese
SkillWorks with Claude CodeGitHub
用简明技术中文(STC)写或改写中文技术内容:操作步骤、安装部署、故障排查、接口和参数说明、技术概念解释、给人读的解释性回答。用户提到「简明技术中文」「STC」「受控中文」「像 ASD-STE100 那样写中文」「一词一义」时使用;用户要求把中文技术说明「写清楚」「别有歧义」时也可使用。不用于营销文案、叙事、法律原文和代码。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/mzopedia--simplified-technical-chinese)HTML
<a href="/listings/mzopedia--simplified-technical-chinese"><img src="/api/listings/mzopedia--simplified-technical-chinese/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 129 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: simplified-technical-chinese
- description: 用简明技术中文(STC)写或改写中文技术内容:操作步骤、安装部署、故障排查、接口和参数说明、技术概念解释、给人读的解释性回答。用户提到「简明技术中文」「STC」「受控中文」「像 ASD-STE100 那样写中文」「一词一义」时使用;用户要求把中文技术说明「写清楚」「别有歧义」时也可使用。不用于营销文案、叙事、法律原文和代码。
- ---
- # 简明技术中文
- 目标:读者读一遍就不会读错。做法:限制用词,限制句式,一句一事。
- 完整规则见 [规范.md](规范.md),词表见 [词表.md](词表.md)。本文件只列最常用的部分。
- ## 模式
- - 常规模式(默认):执行全部【必须】规则和词表的自动检查条目。【建议】规则只在明显时处理。
- - 严格模式:用户说「严格」「全部规则」时,执行全部规则。
- 用户没有说明时用常规模式。
- ## 写之前先分类
- - 操作句:告诉读者做什么。放在编号列表里,动词开头,不超过 30 字。
- - 描述句:其他句子。不超过 40 字。
- 字数算法:每个汉字计 1,每个英文单词或数字串计 1,行内代码计 1,标点不计。
- ## 必须遵守的规则
- 词:
- - 一个概念全文只用一个词。不换同义词。(1.1)
- - 不用「进行」「加以」「作出」「予以」加动词。直接用动词。(1.4)
- - 不用没有数值的程度词:「很」「非常」「较」「大量」「尽快」「及时」。写数值或条件。(1.5)
- - 缩写首次出现写全称并括注,之后固定写法。(1.6)
- - 不用黑话:「赋能」「抓手」「闭环」「拉通」「沉淀」「痛点」「对标」「打法」「拉齐」。(1.7)
- 句:
- - 一句只说一件事。分号不能用来把两句并成一句。(2.2)
- - 操作句用祈使句,不写「请」「您」「用户需要」「应该」。(2.3)
- - 用主动句,写出执行者。「被」「由」「受到」是信号。(2.4)
- - 条件写在动作前面:「如果 X,做 Y」。不放句尾,不放括号。(2.5)
- - 一句最多一个否定。不用「不得不」「不无」「没有……不」。(2.6)
- - 名词前的修饰语不超过 15 字。连续的「的」是信号。(2.7)
- - 「其」「该」「此」「它」只指代上一句的对象。否则重复名词。不用「相关」「上述」。(2.8)
- - 不用反问、设问、感叹。(2.9)
- 段和步骤:
- - 一段一个主题,不超过 6 句。(3.1、3.2)
- - 步骤用编号列表,每个编号一个动作。不在正文里写「首先……然后……」。(3.3、4.1)
- - 不用「等」结尾的开放列举。列全,或写数量加「包括」。(3.5)
- - 警告独立成段,放在它针对的步骤之前,以「警告:」开头。(4.3)
- - 人的动作用祈使句;系统的行为写「系统 + 动词」。(4.4)
- - 前置条件单独列出,放在步骤之前。(4.5)
- 数字:
- - 阿拉伯数字,数字与单位之间空格。(5.1)
- - 不用数字后的「以上」「以下」「以内」。用「大于」「不小于」「不超过」,或「3 至 5(含)」。(5.2)
- - 不用相对时间:「明天」「近期」「稍后」「尽快」。用绝对日期或时长。(5.3)
- - 操作句里不用「约」「几」「若干」「多次」。写数值。(5.4)
- - 减少不用「倍」。百分比和百分点分开。(5.5)
- 标记:
- - 界面元素名用「」括起,和界面文字一致。(6.1)
- - 代码、命令、路径、字段名用代码标记,原样保留。(6.2)
- ## 词表速查
- 最常撞上的 20 条。完整表见 [词表.md](词表.md)。
- | 不用 | 用 |
- | --- | --- |
- | 「进行安装」 | 安装 |
- | 「相关配置」 | 写出具体对象 |
- | 「支持 A、B 等」 | 列全,或「包括 3 种:A、B、C」 |
- | 「10 以上」 | 大于 10 / 不小于 10 |
- | 「大概 5 秒左右」 | 5 秒 |
- | 「尽快」 | 30 分钟内 |
- | 「如果失败的话」 | 如果失败 |
- | 「检查一下」 | 检查 |
- | 「出现错误的情况」 | 出现错误时 |
- | 「应该」「务必」「一定要」 | 必须(强制)/ 建议(推荐) |
- | 「不得」「不准」 | 禁止 |
- | 「单击」「点按」 | 点击 |
- | 「删掉」「去掉」 | 删除 |
- | 「开启功能」 | 启用功能 |
- | 「打开程序」 | 启动程序 |
- | 「登出」 | 退出登录 |
- | 「键入」 | 输入 |
- | 「入参」「出参」 | 参数 / 返回值 |
- | 「登陆」「帐号」「缺省」 | 登录、账号、默认 |
- | 「报错」(名词) | 错误 |
- 一词一义里最常错的 4 个:
- - 打开:只用于文件、窗口、页面、连接。功能用「启用」,程序用「启动」。
- - 可以:只表示允许。能力用「支持」。
- - 问题:只表示疑问。故障、错误、缺陷分开写。
- - 更新:只用于数据和内容。版本用「升级」。
- ## 工作流程
- 1. 判断内容类型。营销、叙事、法律原文不用本规范。
- 2. 判断模式。默认常规模式。
- 3. 写或改写。先定术语,再写句子。操作内容用编号列表。
- 4. 如果结果保存成了文件,运行检查脚本:
- ```bash
- python3 tools/check.py 文件.md
- ```
- 聊天回答这类没有编号步骤的内容,加 `--kind 描述`。
- 5. 修复全部【必须】级别的发现。【建议】级别的按判断处理。
- 6. 改写别人的文稿时,不改变事实、数字、条件和确定程度。原文说「可能」,改写后仍是「可能」。
- ## 不要做的事
- - 不改写代码、命令、路径、字段名、URL。
- - 不为了缩短句子而删除条件、例外和警告。
- - 不把「可能」改成「会」,不把「建议」改成「必须」。
- - 不给原文没有的数字、日期和时限编一个。缺信息时写「待确认」。
- - 不把规范用在它不适用的文体上。
- ## 检查脚本的局限
- 脚本只查句法。它查不出事实错误、术语选错、逻辑顺序错。它用「编号列表项」判断操作句,用「的」的数量近似长定语,用几个标记词近似被动句。所有发现都要人工确认。
README.md · README · 180 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 简明技术中文
- [](https://github.com/mzopedia/simplified-technical-chinese/actions/workflows/test.yml) [English](README.en.md)
- Simplified Technical Chinese(STC)。一套受控的中文写法,用于技术说明、操作步骤、接口文档和 AI 的解释性回答。目标是读者读一遍就不会读错。
- 它借鉴 [ASD-STE100](https://www.asd-ste100.org/)(Simplified Technical English)的方法:限制用词,限制句式,一句一事。它不是 ASD-STE100 的译本,与 ASD 没有关系。
- <!-- stc:off -->
- > **English.** STC is a controlled language for Chinese technical writing, modelled on the method of ASD-STE100: a numbered rule set, a controlled vocabulary (one meaning, one word), and a zero-dependency checker. It is not a translation of STE and is not affiliated with ASD. The rules are written for the ambiguities of Chinese: nominalised verbs (进行 + verb), long pre-nominal modifiers, the inclusive/exclusive ambiguity of 以上/以下, permission vs ability of 可以, and object restrictions on 打开/关闭/启动.
- <!-- stc:on -->
- ## 一个例子
- 节选自 [examples/before.md](examples/before.md):
- > 改写前:用户首先需要登陆到目标服务器,然后切换到 /opt 目录并且创建一个用于存放采集器配置文件以及运行时产生的临时数据的工作目录。
- 节选自 [examples/after.md](examples/after.md):
- > 1. 登录目标服务器。
- > 2. 切换到 `/opt` 目录。
- > 3. 创建工作目录 `/opt/collector`。工作目录存放配置文件和临时数据。
- 检查脚本对改写前那一句的输出:
- ```text
- examples/before.md:11: [1.3][必须] 禁用词「登陆」,改用:登录
- examples/before.md:11: [2.1][必须] 操作句 56 字,不超过 30 字
- examples/before.md:11: [4.1][建议] 禁用词「然后」,改用:拆成编号步骤
- examples/before.md:11: [4.1][必须] 禁用词「并且」,改用:拆句
- ```
- 整篇改写前的文档有 34 条【必须】级别的发现,改写后是 0 条。
- ## 为什么做这个
- 2026 年 10 月,Andrej Karpathy [发帖](https://x.com/karpathy/status/2105819303471976479)说,让大模型用 ASD-STE100 来解释东西,读起来清楚得多。ASD-STE100 是航空维修手册用的受控英语:53 条写作规则,加一本约 900 个词的词典,每个词只有一个意思。
- 中文没有对应的东西。已有的中文技术写作规范管排版、标点和文档结构,见[和现有项目的区别](#和现有项目的区别)。它们都没有做 STE 的核心:编号规则、受控词表、可以自动检查的句法约束。本项目补这一块。
- ## 内容
- | 文件 | 内容 |
- | --- | --- |
- | [规范.md](规范.md) | 写作规则。6 节,40 条,每条带「不批准 / 批准」例句。规则分【必须】和【建议】两级 |
- | [词表.md](词表.md) | 受控词表。禁用词及替换、选词表(一个意义一个词)、一词一义限定。约 170 条 |
- | [tools/check.py](tools/check.py) | 检查脚本。零依赖,Python 3.9 及以上。读规范和词表,输出行号、规则号、级别 |
- | [SKILL.md](SKILL.md) | 给 Claude Code、Codex、Cursor 这类 agent 用的技能文件 |
- | [examples/](examples/) | 改写前后的完整示例 |
- 规则的六节:词、句、段、步骤与警告、数字时间与范围、术语与标记。最常用的几条:
- - 一个概念全文只用一个词。
- - 不用「进行」「加以」加动词。直接用动词。
- - 操作句不超过 30 字,描述句不超过 40 字。
- - 操作句用祈使句,动词开头,不写「请」「您」「用户需要」。
- - 条件写在动作前面。警告独立成段,放在步骤前。
- - 不用数字后的「以上」「以下」,写「大于」「不小于」。
- - 「打开」只用于文件和窗口。功能用「启用」,程序用「启动」。
- - 「可以」只表示允许。能力用「支持」。
- ## 给 AI 用
- ### 装成技能
- 用 [skills](https://github.com/vercel-labs/skills) 安装器:
- ```bash
- npx skills add mzopedia/simplified-technical-chinese
- ```
- 或手动复制。Claude Code 的全局技能目录是 `~/.claude/skills/`:
- ```bash
- git clone --depth 1 https://github.com/mzopedia/simplified-technical-chinese.git ~/.claude/skills/simplified-technical-chinese
- ```
- 装好后,agent 在写中文技术说明时会按规范写,并在保存成文件后运行检查脚本。
- ### 直接写进提示词
- 不装技能时,把下面这段放进系统提示或对话里:
- ```text
- 用简明技术中文回答。规则:一句只说一件事,操作句不超过 30 字,描述句不超过 40 字;操作步骤用编号列表,动词开头,不写「请」「您」;用主动句;条件写在动作前面;一个概念全文只用一个词;不用「进行」「相关」「等」「以上」「尽快」「大概」;不用反问和感叹;数字后不用「以上」「以下」,写「大于」「不小于」。
- ```
- 这对应规范的常规模式,也就是 Karpathy 说的「做到八成」。要全部规则时,把 [规范.md](规范.md) 整个给模型。
- ## 给人用
- 读 [规范.md](规范.md)。写完后用检查脚本过一遍:
- ```bash
- python3 tools/check.py 文档.md
- ```
- 在 CI 里用 `--strict`,有【必须】级别的发现时退出码为 1:
- ```bash
- python3 tools/check.py --strict docs/*.md
- ```
- ## 检查脚本
- ```text
- python3 tools/check.py 文件.md [更多文件]
- --strict 有【必须】级别的发现时退出码为 1
- --json JSON 输出
- --kind 操作|描述 强制按一种句型检查。聊天回答用「描述」
- --max-op 30 操作句字数上限
- --max-desc 40 描述句字数上限
- --no-vocab 不检查词表
- --check-counterexamples 也检查「不批准:」开头的反例行
- ```
- 脚本能稳定查出的:
- - 禁用词,以及选词表中标为自动检查的词
- - 句长、段落句数
- - 操作句里的被动句、情态词、程度词和估计词
- - 操作句句尾的条件、双重否定、「等」结尾的开放列举
- - 相对日期、中文数字、「倍」表示减少、问句和感叹句
- 脚本查不出的:事实是否正确、术语选得对不对、逻辑顺序、一词一义限定。也查不出定语长度、指代是否清楚、缩写是否一致、步骤里的警告和原因。这几条规则在真实文档上校准时精确率太低,只留在规范文本里由人判断,见 [docs/校准报告.md](docs/校准报告.md)。脚本用编号列表项判断操作句。所有发现都要人工确认。
- 脚本不检查的内容:
- - 「」里的内容,按界面文字处理
- - 代码块和行内代码
- - HTML 注释,`stc:` 指令除外
- - 文件开头的 YAML front matter
- - 以「不批准:」「反例」「改写前」开头的行
- - `<!-- stc:off -->` 和 `<!-- stc:on -->` 之间的内容;`<!-- stc:skip -->` 跳过它后面的一段
- ## 和 ASD-STE100 的关系
- - 方法来自 STE:一词一义、句长限制、祈使句、条件在前、段落句数、不用开放列举。
- - 规则是按中文重写的。中文没有时态和词形变化,但有自己的歧义来源。例如名词化结构、长定语、「以上」的端点歧义、「可以」的许可和能力歧义。对应关系见规范的附录 B。
- - ASD-STE100 是注册商标。本项目不使用这个名字,不暗示与 ASD 有关系,也不表示符合本规范的文本符合 ASD-STE100。
- ## 和现有项目的区别
- | 项目 | 管什么 | 本项目的关系 |
- | --- | --- | --- |
- | [ruanyf/document-style-guide](https://github.com/ruanyf/document-style-guide) | 标题、段落、数值、标点、文档结构 | 互补。本规范不管排版 |
- | [yikeke/zh-style-guide](https://github.com/yikeke/zh-style-guide) | 语言风格、标点、文档元素 | 互补 |
- | [Fenng/Tech-Doc-Style-Chinese](https://github.com/Fenng/Tech-Doc-Style-Chinese) | 事实保真、改写流程、术语排版,有一节受控写作原则 | 它有 6 条原则和改写样例,没有编号规则和词表,并且明确不把句长做成硬规则。本项目做的正是这部分 |
- 写完整文档时,建议三者配合:用本规范管句子和用词,用上面的项目管排版和结构。
- ## 状态
- 0.2。规则、阈值和自动检查的词表在 350 万字真实中文技术文档上校准过。语料是 8 个开源项目的中文文档,共 2856 个文件。它们是 TiDB、Kubernetes、MDN、Vue、Vite、Ant Design 的文档,以及《Rust 程序设计语言》中文版和阮一峰的 ES6 教程。
- 脚本执行的每条规则都在真实文本上抽样判定过,错多于对的规则已从脚本移除。好文档上的提示从每万字 194 条降到 88 条,其中一半以上是句长提示。不算句长,从 151 条降到 40 条。句长上限取好文档句长分布的 90 分位:90% 的操作句不超过 33 字,90% 的描述句不超过 41 字。细节见 [docs/校准报告.md](docs/校准报告.md)。
- 规范、本文件和 SKILL.md 自身都通过了检查脚本(0 条【必须】),CI 每次提交都会复查。
- 已知问题:
- - 词表约 170 条,只覆盖通用技术写作。
- - 没有做过阅读理解的对照实验。校准量的是误报率,不是阅读速度和出错率。
- - 检查脚本只做句法层面的检查。
- ## 参与
- 提一个词的方法:开 issue,写清四项:词、意义、建议的处理(禁用 / 选词 / 限定)、一个例句。
- 改词表时保持表格的列顺序,「自动检查」列只填「是」或「否」。改完运行测试:
- ```bash
- python3 -m unittest discover tests
- ```
- ## 许可
- - 规范和词表的文本:[CC BY 4.0](LICENSE-CC-BY-4.0)
- - 检查脚本和测试:[MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.