ITADN
NikolaRHristov/STE-Code
代码 动态 Issues 合并请求 版本
NikolaRHristov/STE-Code · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

STE-Code 📘

License: MIT Version Standard Source

ASD-STE100 是 简化技术英语。 它是来自航空航天行业的一种受控语言。 它为作者提供了一套写作规则和一本批准使用的词典。飞机维护手册使用它， 以确保没有任何句子具有两种含义。

STE-Code 将该理念应用于代码文档：9 个章节中的 54 条写作规则、4 条通用规则、 一个代码领域词典和一个同义词表——用于注释、文档字符串、错误消息、提交信息、 API 文档、变更日志和配置文件。该标准消除了歧义、行话和含糊其辞。

您无需亲自阅读该标准。将级别工件加载到大型语言模型中， 该模型即可按照标准为您编写项目的技术文档。

你将获得的内容 📦

每个级别都是一个纯文本文件。将该文件复制到你的模型的 system-prompt 字段中。 级别越高，约束越严格，消耗的上下文也越多。

级别要加载的文件大小Token 数新增内容
-2ste-code/artifacts/level-2/system-prompt.txt5 KB~1.2K14 条核心原则
-1ste-code/artifacts/level-1/system-prompt.txt26 KB~5.9K+ 同义词表
0ste-code/artifacts/level0/system-prompt.txt17 KB~4.3K+ 简短词典摘录
1ste-code/artifacts/level1/system-prompt.txt58 KB~14.5K+ 文档模板
2ste-code/artifacts/level2/system-prompt.txt75 KB~18.5K+ 章节语法规则
3ste-code/artifacts/level3/system-prompt.txt388 KB~94.7K+ 完整词典和全部 54 条规则
4ste-code/artifacts/level4/system-prompt.txt462 KB~116.0K+ 扩展内容和参考目录
5ste-code/artifacts/level5/system-prompt.txt539 KB~133.8K+ 来源信息（完整标准）

[!TIP]

从级别 1 开始。 它适合普通的上下文窗口，并且包含 模板。只有当你需要完整的规则覆盖时，才升级到级别 3 或更高。

每一层都是一个小型子文档的目录，因此智能体读取和写入的文件仅有几十 KB，而不会是一个大文件。system-prompt.txt 是这些子文档的合并，而 _index.md 列出了它们。

ste-code/artifacts/ 的顶层还有两个文件：

文件用途
llms.txt每一层的 llms.txt 风格索引
llms-full.txt所有提炼后的子文档在一个文件中

Size 是 system-prompt.txt 在磁盘上的大小。Token 计数使用 o200k_base 分词器（GPT-4o、GPT-4.1、GPT-5、o 系列）。cl100k_base（GPT-4、 GPT-3.5-turbo）的误差在 0.3% 以内，而 Claude 和 Llama 分词器在英文文本中 误差保持在几个百分点以内。使用以下命令重新生成这些数字：

Terminal

python3 .agents/tools/maintenance/measure_artifacts.py
python3 .agents/tools/release/facts.py

使用它 🚀

将 level 加载到任何接受 system prompt 的模型中。

Terminal

# Ollama, llama.cpp, or any CLI that takes a system-prompt file
ollama run llama3 --system "$(cat ste-code/artifacts/level1/system-prompt.txt)"

Python

# OpenAI-compatible API
from pathlib import Path
from openai import OpenAI

system = Path("ste-code/artifacts/level1/system-prompt.txt").read_text()
client = OpenAI()

reply = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": system},
        {"role": "user", "content": "Rewrite: /** Basically handles user stuff. */"},
    ],
)
print(reply.choices[0].message.content)

该模型随后应用已批准的词汇表、同义词表以及 句子长度限制。它用已批准的词语替换行话，使用 主动语态和祈使语气，并且确保每个句子仅包含一条 指令。

You:  Rewrite this docstring.
      /** This function basically handles user stuff. */

LLM:  /** Creates a user, or updates the data of a user. */

规则 📏

54 条规则位于 ste-code/final/rules/，每条规则 一个文件。

章节规则数涵盖范围
114词汇：批准词汇表、词性、技术名词和动词
23名词短语：冠词、名词簇
37动词：时态、语态、语气、动词形式
45句子：长度、清晰度、完整性
55流程：指导性写作、步骤结构
66描述：描述性写作、比较
73警告：BREAKING、DEPRECATED 和 NOTE 格式
87标点符号：逗号、连字符、括号、列表
94文档结构：标题、列表、表格、组织

每条规则都包含针对代码领域的适配，并提供面向 面向对象、函数式、过程式、声明式和系统范式的指导。

ste-code/final/ 还包含词典（rules/a-dictionary.md）、22 个 技术名词类别（rules/a-categories.md）、六个填空扩展 （extensions/）、参考目录以及来源记录。四条 通用规则（GR1–GR4）位于 ste-code/adapted/a-sec9-gr1..4.md。

标准的构建方式 🏗️

该流水线读取 ASD-STE100 Issue 9 规范并写入级别 工件。它分五个阶段运行。

Pipeline

Extraction → Refinement → Merge → Adaptation → Artifacts
 extracted/    refined/    grouped/   adapted/   artifacts/
                                      final/
阶段读取写入类型
Extractionspec/issue-09-2025/page-dir/ste-code/extracted/ (109 files)LLM workers
Refinementste-code/extracted/ste-code/refined/ (109 files)LLM workers
Mergeste-code/refined/ste-code/grouped/ (24 groups)Deterministic
Adaptationste-code/grouped/ste-code/adapted/, then ste-code/final/LLM workers
Artifactsste-code/final/ste-code/artifacts/ (8 tiers)Deterministic + LLM

Merge 和 Artifacts 组装阶段有意采用纯 Python 实现。当任务涉及重组而非撰写时， 流水线移动字节而非重新输入，因此内容不会丢失。

阅读 docs/pipeline.md 了解运行器、门控以及如何 运行某个阶段。

工件构建 🧩

交付物由混合设计生成，因此内容永远不会丢失， 也永远不会被静默截断：

  1. Scaffold (deterministic). levels_scaffold.py 读取 ste-code/final/ 并为 8 个层级中的每一个，在 ste-code/artifacts/_base/level<N>/ 下输出一个包含有界子文档的目录。 超大的规则部分会被拆分。此层是字节可复现的，且无需模型。
  2. Distill (LLM). distill_one.py 为每个子文档运行一个会话。 工作进程将其基础子文档重写为位于 ste-code/artifacts/level<N>/<subdoc> 的优化文件，并通过多次 write_file 和 patch 调用进行写入。在任何失败情况下，确定性的基础版本保持原样，因此 不会丢失任何内容。
  3. Assemble (deterministic). artifact_batch.py 写入每个层级的 _index.md 和 system-prompt.txt，然后是顶层的 llms.txt， llms-full.txt，以及 VERSION。无需模型，且无截断。

Build

final/  ──levels_scaffold.py──▶  _base/level<N>/  ──distill_one.py (LLM)──▶  level<N>/<subdoc>
   │                                                                                 │
   └────────────────────────artifact_batch.py───────────────▶ llms.txt + llms-full.txt

仓库 🗂️

PathContents
ste-code/artifacts/交付物：8 级目录，llms.txt，llms-full.txt，VERSION
ste-code/final/标准：54 条规则、词典、类别、扩展、目录、来源
ste-code/extensions/代码领域的补全条目：动词、形容词、名词、反模式、领域
ste-code/所有其他流水线层，从 extracted/ 到 enriched/
spec/ASD-STE100 Issue 9 源文件。PDF 共 434 页；拆分后生成 426 个页面文件
docs/MkDocs 文档站点
translations/10 种语言的本地化脚手架
.agents/仅用于开发。构建 ste-code/ 的机制：流水线运行器、工具、技能、基准测试以及写入隔离环境。它不属于交付物，且永远不会加载到模型中

验证结账 ✅

Terminal

make check

该门输出 RESULT: all policies passed。请参阅 CONTRIBUTING.md 了解其他 make 目标。

任何 markdown 层的质量检查：

Terminal

python3 .agents/tools/quality/check-rails.py  # the 8 rails
python3 .agents/tools/quality/check-tables.py # table integrity
bash .agents/tools/linkcheck/run_linkcheck.sh # lychee link check

链接检查器扫描 ste-code/final/**/*.md 和 ste-code/artifacts/**/*.md。它忽略有意保留的遗留 master.md#… 反向链接，并报告真实的损坏：过时的内部路径和失效的外部 URL。配置为 .agents/tools/linkcheck/lychee.toml。

与 Agent 无关的工具 🛠️

每个流水线脚本都使用 .agents/tools/lib/ 中的 agent runner。默认 后端是 Hermes，其他后端在 .agents/config/agents.yaml 中配置。提示词被外部化到 .agents/tools/prompts/*.md，并由 templater.py 使用双大括号 {{token}} 语法进行渲染。

Terminal

# List the configured agent backends
python3 .agents/tools/lib/agent-runner.py --list

# Assemble the consolidated artifacts (deterministic, from final/)
python3 .agents/tools/artifacts/artifact_batch.py
python3 .agents/tools/artifacts/verify-artifacts.py

# Build the deterministic boilerplate sub-documents
python3 .agents/tools/artifacts/levels_scaffold.py

# Distill one sub-document with a model (one worker, own process)
python3 .agents/tools/artifacts/distill_one.py level3 01-principles.md 3 "..."

# Run the whole downstream chain
bash .agents/tools/runners/launch-downstream.sh

模型从 STE_MODEL 环境变量中读取。默认值为 tencent/hy3:free。完整文档：文档站点 和 .agents/AGENTS.md。

Benchmark 📊

基准测试套件位于 .agents/benchmark/。它包含 14 个类别中的 59 个测试，并针对同一模型， 比较其带有 level artifact 与不带 level artifact 时的得分。

Terminal

python3 .agents/benchmark/benchmark-levels.py --levels -2,-1,0,1,2,3,4,5
python3 .agents/benchmark/orchestrator-control.py # plain-assistant baseline

[!NOTE]

运行输出不会提交到本仓库，因此本 README 不发布任何分数。请运行测试套件以获取您自己模型的数值。

许可证 ⚖️

MIT。参见 LICENSE。

Citation

@misc{ste-code-2025,
  title        = {{STE-Code}: Simplified Technical English for Code Documentation},
  author       = {{Nikola Hristov}},
  year         = {2025},
  howpublished = {\url{https://github.com/NikolaRHristov/STE-Code}},
  note         = {Adapted from ASD-STE100 Issue 9 (January 2025)}
}

致谢与参考资料 📚

STE-Code 建立在数十年的受控语言研究、文档 理论和验证工具之上。

主要标准 📜

  • ASD-STE100 简化技术英语，第 9 版（2025 年 1 月） — 该 标准被 STE-Code 适配到代码领域。它由 ASD （欧洲航空航天、安全与国防工业协会）所有， 并由 简化技术英语维护组 (STEMG) 维护。 https://www.asd-ste100.org/

受控自然语言理论 🧠

文档与可读性 📖

  • John M. Carroll — 极简主义（ACM SIGDOC）。语域 分层的基础：用户首先行动，并在需要时阅读。

相邻标准 🔗

知识产权 ⚠️

[!NOTE]

ASD-STE100 是 ASD, Brussels 的版权和商标。 STE-Code 将该标准的_原则和规则类别_应用于软件 领域。它不复制该标准的词典或规则文本。 请直接通过 ASD 的免费官方表格获取 Issue 9： https://www.asd-ste100.org/。

由 Nikola Hristov 用 ❤️ 构建。