企业官网建设流程全解析

SimpleEnglish 改写前后对比：8类技术文档改写实测（违规率下降74.6%）

【免费下载链接】SimpleEnglishAgent skill: make LLMs write docs in ASD-STE100 Simplified Technical项目地址: https://gitcode.com/gh_mirrors/si/SimpleEnglish

SimpleEnglish 是一个 Agent skill：让大语言模型（LLM）按照 ASD-STE100 简化技术英语标准写技术文档。开启它之后，AI 生成的 README、错误消息、事故报告等 8 类技术文档平均少 74.6% 的规范违规（7 个 Claude 模型 × 8 项写作任务实测，RESULTS.md）。本文用仓库里真实的 Before/After 原文对比，逐类展示改写效果 👇

什么是 SimpleEnglish？1 分钟看懂

一句话：把"AI 腔"从技术文档里删掉，换成航空维修手册式的写法。

• 规则来源：ASD-STE100，航空业从 1983 年沿用至今的受控英语标准，目标是让疲劳的非母语读者也不能误读指令
• 落地形式：一个文件夹，零依赖，MIT 协议。核心是 SKILL.md：53 条编号规则 + 9 个章节
• 工作方式：装进任何支持 Agent Skills 标准的工具（Claude Code、Cursor、Codex 等）后，说"rewrite this with simple-english"即可
• 两种模式：Pragmatic（默认，保留你的领域词）和 Strict（额外执行词典词汇纪律）
• 快速上手：npx skills add AminBlg/SimpleEnglish；Claude Code 用户可装插件（含 skill + 会话钩子 + 输出样式）：claude plugin marketplace add AminBlg/SimpleEnglish && claude plugin install simple-english@simple-english

53 条规则里真正干活的是这些：指令句 ≤20 词、描述句 ≤25 词；一词一义；只用简单时态；主动语态；条件放在命令之前；一句一条指令。

改写实测：8 类文档 Before/After 全记录

以下所有 Before 均为未加 skill 的真实 AI 输出，After 为同一内容应用 skill 后的结果。完整 5 组对照在 examples/before-after.md，更多原始输出在 evals/results/openai-2026-09-01/raw/。

1️⃣ README 开头（描述型）

Before（1 个 30 词的长句 + 悬垂 -ing 从句）：

sqlpipe is a command-line tool for syncing PostgreSQL tables to Amazon S3 as Parquet files. It's built for teams who need a lightweight way to move data out of Postgres into a data lake without standing up a full ETL platform. … Configuration lives in a single YAML file, making it easy to version-control your sync definitions…

After（最长句 21 词，一段一个主题）：

sqlpipe is a command-line tool that copies PostgreSQL tables to Amazon S3 as Parquet files. It moves data into a data lake without a full ETL platform.

The configuration is one YAML file. You can keep this file in version control with your infrastructure code.

2️⃣ Getting Started 快速上手（步骤型）

Before：

Next, configure your pipeline by creating asqlpipe.yamlfile in your working directory. This file defines your data sources, SQL transformations, destinations, and any scheduling or environment variables required for your workflows. The YAML format is simple and flexible, enabling you to tailor pipelines according to your project needs.

After（编号步骤 + 条件在前）：

2. Create the configuration filesqlpipe.yaml. Edit this file to set the source and target databases.
3. Run sqlpipe using the configuration file. Enter this command:sqlpipe run --config sqlpipe.yaml
4. Watch the output for any errors. If sqlpipe stops with an error, examine the message and fix the problem in the configuration.

3️⃣ Troubleshooting 故障排查（步骤型）

Before（40 词长句、缩写、条件写在命令后面）：

If sqlpipe hangs or fails withdial tcp: i/o timeout, check that the host running sqlpipe can reach the Postgres port (usually 5432) — this is often a security group or firewall rule blocking the connection. If you're connecting to a managed database (RDS, Cloud SQL, etc.), confirm the instance allows connections from sqlpipe's IP. You can also try increasingsource.connect_timeout_seconds…

After（一句一条指令，"check/confirm" 统一为 "make sure that"）：

sqlpipe stops withdial tcp: i/o timeoutwhen it cannot reach the Postgres port (5432 by default).

1. Make sure that the host that runs sqlpipe can reach the Postgres port. A firewall or security group usually blocks it.
2. If the database is managed (RDS, Cloud SQL), make sure that the instance accepts connections from the IP of sqlpipe.
3. If the network is slow, increasesource.connect_timeout_secondsin the configuration.

4️⃣ Error Message 错误消息（步骤型）

Before：

Oops! Something went wrong while attempting to establish a connection to the database. Please ensure your credentials have been properly configured and try again, or reach out to your administrator if the issue persists.

After：

Connection to the database failed: the password for userappwas not correct. SetDB_PASSWORDto the correct value, then connect again. If the error continues, ask your database administrator for access.

错误消息是收益最高的场景——它是凌晨 2 点给焦虑读者的指令（use-cases.md 原话）。

5️⃣ Incident Report 事故报告（描述型）

Before：

We have identified an issue that may have impacted some users' ability to access the service. Our team has been working diligently to resolve this and services have now been fully restored. We sincerely apologize for any inconvenience this may have caused.

After（只用简单过去时，时间线一目了然）：

Between 14:02 and 14:31 UTC, 12% of requests to the API failed with HTTP 502. A deploy at 14:00 removed the cache warmup step, and the cache nodes overloaded. We reverted the deploy at 14:27. All requests succeeded from 14:31.

6️⃣ Release Notes 发布说明中的破坏性变更（描述型）

Before：

Please note that we've made some changes to the users endpoint that may require updates to your integration. Thenamefield has been deprecated in favor of separatefirst_nameandlast_namefields, so you'll want to update your code accordingly.

After（"Breaking" 警告模式：命令在前）：

Breaking:Update your calls to/v2/users. Thenamefield split intofirst_nameandlast_name. Thenamefield will return null after 2026-09-01.

7️⃣ Runbook 运维手册（极端简化）

Before：

Verify backup exists before migrating.

After（保留完整语法，这才是 STE，不是电报体）：

Make sure that the backup exists before you run the migration.

8️⃣ Architecture 架构说明（描述型）

Before（典型 AI 腔：robust / leveraging / fault-tolerant）：

SQLPipe is a data pipeline designed to efficiently transfer and convert data from a Postgres database to S3 storage in Parquet format. … It incorporates robust retry mechanisms to ensure data durability and successful uploads, even in the face of transient network or service disruptions.

After（一句一个新事实）：

sqlpipe has three main parts. A reader process streams rows from Postgres in batches. A converter turns each batch into a Parquet row group. An uploader writes objects to Amazon S3 as multipart uploads. The uploader retries parts that fail to upload.

为什么是 74.6%？基准测试方法说明

评分靠一个确定性正则 linter（ste_lint.py）统计每 100 词的 STE 违规数，两组条件用同一套规则，112 次生成的原始文件全部提交在仓库里，任何数字都可复现（python3 evals/run_bench.py）。

跨框架同样成立：GLM-5.2 max 下降 84.4%，GPT-5.6 Sol 下降 88.0%，gpt-4.1-mini 下降 95.8%。盲评（56 组配对，评委不知道哪边是 skill 输出）中，评委在 45 组里偏好 skill 版本，且 7 个模型的输出 token 数全部下降——更短，也更准。

FAQ 常见问题

会让文档变得机器人味十足吗？会像空客手册：平淡、无法误读。对文档来说这恰恰是目的——营销文案请保留自己的风格。

为什么不直接提示 "write clearly"？"清晰"是一种观点，"句子不超过 20 词"是规格。Agent 只会照规格执行。

支持哪些工具？所有读取 Agent Skills 标准的 Agent：Claude Code、Cursor、VS Code Copilot、OpenAI Codex、Gemini CLI 等约 25+ 工具。没有 skill 支持的模型，可直接粘贴 system-prompt.md（文末还附 60 token 精简版）。

规则细节在哪看？完整 53 条规则在 SKILL.md；改写用的词表在 word-swaps.md；交付前的自查清单在 checklist.md；压测场景在 pressure-tests.md。

总结

SimpleEnglish 把"写清楚"从玄学变成了可执行、可度量的规格：8 类技术文档全部通过同一套 53 条规则改写，违规率平均下降 74.6%。所有 Before/After 原文都在 examples/before-after.md，想亲手验证的话，装好 skill 后说"rewrite this with simple-english"就行 ✅

【免费下载链接】SimpleEnglishAgent skill: make LLMs write docs in ASD-STE100 Simplified Technical项目地址: https://gitcode.com/gh_mirrors/si/SimpleEnglish