From 941942c7e176377f39d99b70d0f786efb223bd6e Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Wed, 7 Oct 2026 22:25:41 +0800 Subject: [PATCH] docs: add researched authoring handbook and portable validation --- .gitignore | 5 + AGENTS.md | 17 ++++ CONTRIBUTING.md | 54 +++++++++++ README.md | 6 ++ authoring/CHANGELOG.md | 18 ++++ authoring/README.md | 75 +++++++++++++++ authoring/adoption.md | 44 +++++++++ authoring/checklist.md | 46 +++++++++ authoring/research/SRC-01.md | 31 ++++++ authoring/research/SRC-02.md | 33 +++++++ authoring/research/SRC-03.md | 32 +++++++ authoring/research/SRC-04.md | 32 +++++++ authoring/research/SRC-05.md | 32 +++++++ authoring/research/SRC-06.md | 32 +++++++ authoring/research/SRC-07.md | 32 +++++++ authoring/research/SRC-08.md | 32 +++++++ authoring/research/SRC-09.md | 32 +++++++ authoring/research/SRC-10.md | 19 ++++ authoring/research/SRC-11.md | 32 +++++++ authoring/research/SRC-12.md | 19 ++++ authoring/research/SRC-13.md | 19 ++++ authoring/research/SRC-14.md | 32 +++++++ authoring/research/SRC-15.md | 32 +++++++ authoring/research/sources.md | 41 ++++++++ authoring/research/synthesis.md | 50 ++++++++++ authoring/rules/DOC-001.md | 37 +++++++ authoring/rules/DOC-002.md | 37 +++++++ authoring/rules/DOC-003.md | 37 +++++++ authoring/rules/DOC-004.md | 37 +++++++ authoring/rules/DOC-005.md | 37 +++++++ authoring/rules/DOC-006.md | 37 +++++++ authoring/rules/DOC-007.md | 37 +++++++ authoring/rules/DOC-008.md | 37 +++++++ authoring/rules/DOC-009.md | 37 +++++++ authoring/rules/DOC-010.md | 37 +++++++ authoring/rules/DOC-011.md | 37 +++++++ authoring/rules/DOC-012.md | 37 +++++++ authoring/rules/DOC-013.md | 37 +++++++ authoring/rules/DOC-014.md | 37 +++++++ authoring/rules/DOC-015.md | 37 +++++++ authoring/rules/DOC-016.md | 37 +++++++ authoring/rules/DOC-017.md | 37 +++++++ authoring/rules/DOC-018.md | 37 +++++++ authoring/rules/DOC-019.md | 37 +++++++ authoring/rules/DOC-020.md | 37 +++++++ authoring/rules/DOC-021.md | 37 +++++++ authoring/rules/DOC-022.md | 37 +++++++ authoring/rules/DOC-023.md | 37 +++++++ authoring/rules/DOC-024.md | 37 +++++++ authoring/templates/README.md | 16 ++++ authoring/templates/TPL-01.md | 43 +++++++++ authoring/templates/TPL-02.md | 47 +++++++++ authoring/templates/TPL-03.md | 49 ++++++++++ authoring/templates/TPL-04.md | 44 +++++++++ authoring/workflow.md | 62 ++++++++++++ tools/README.md | 39 ++++++++ tools/check_docs.py | 164 ++++++++++++++++++++++++++++++++ tools/tests/test_check_docs.py | 119 +++++++++++++++++++++++ 58 files changed, 2268 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 authoring/CHANGELOG.md create mode 100644 authoring/README.md create mode 100644 authoring/adoption.md create mode 100644 authoring/checklist.md create mode 100644 authoring/research/SRC-01.md create mode 100644 authoring/research/SRC-02.md create mode 100644 authoring/research/SRC-03.md create mode 100644 authoring/research/SRC-04.md create mode 100644 authoring/research/SRC-05.md create mode 100644 authoring/research/SRC-06.md create mode 100644 authoring/research/SRC-07.md create mode 100644 authoring/research/SRC-08.md create mode 100644 authoring/research/SRC-09.md create mode 100644 authoring/research/SRC-10.md create mode 100644 authoring/research/SRC-11.md create mode 100644 authoring/research/SRC-12.md create mode 100644 authoring/research/SRC-13.md create mode 100644 authoring/research/SRC-14.md create mode 100644 authoring/research/SRC-15.md create mode 100644 authoring/research/sources.md create mode 100644 authoring/research/synthesis.md create mode 100644 authoring/rules/DOC-001.md create mode 100644 authoring/rules/DOC-002.md create mode 100644 authoring/rules/DOC-003.md create mode 100644 authoring/rules/DOC-004.md create mode 100644 authoring/rules/DOC-005.md create mode 100644 authoring/rules/DOC-006.md create mode 100644 authoring/rules/DOC-007.md create mode 100644 authoring/rules/DOC-008.md create mode 100644 authoring/rules/DOC-009.md create mode 100644 authoring/rules/DOC-010.md create mode 100644 authoring/rules/DOC-011.md create mode 100644 authoring/rules/DOC-012.md create mode 100644 authoring/rules/DOC-013.md create mode 100644 authoring/rules/DOC-014.md create mode 100644 authoring/rules/DOC-015.md create mode 100644 authoring/rules/DOC-016.md create mode 100644 authoring/rules/DOC-017.md create mode 100644 authoring/rules/DOC-018.md create mode 100644 authoring/rules/DOC-019.md create mode 100644 authoring/rules/DOC-020.md create mode 100644 authoring/rules/DOC-021.md create mode 100644 authoring/rules/DOC-022.md create mode 100644 authoring/rules/DOC-023.md create mode 100644 authoring/rules/DOC-024.md create mode 100644 authoring/templates/README.md create mode 100644 authoring/templates/TPL-01.md create mode 100644 authoring/templates/TPL-02.md create mode 100644 authoring/templates/TPL-03.md create mode 100644 authoring/templates/TPL-04.md create mode 100644 authoring/workflow.md create mode 100644 tools/README.md create mode 100644 tools/check_docs.py create mode 100644 tools/tests/test_check_docs.py diff --git a/.gitignore b/.gitignore index 08166ab..86de252 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,8 @@ !.env.example *.pem *.key + +# Generated Python state for the read-only documentation checker +__pycache__/ +*.py[cod] +.venv/ diff --git a/AGENTS.md b/AGENTS.md index 0521258..65bd663 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,14 @@ 适用于本目录及所有子目录。 +## 每次修改的必读入口 + +- 修改前阅读 [文档编写手册](authoring/README.md)与[工作流](authoring/workflow.md)，按改动类型选择并阅读适用的 DOC 规则页。小型改动不要求通读所有规则。 +- 结构性改写至少核对 DOC-001、002、005、015、021、024；新增页面选择适合职责的[模板](authoring/templates/README.md)，不要机械填充无关段落。 +- 修改后按[检查清单](authoring/checklist.md)核对主定义、目录、文法、例子与规范状态，并运行[检查工具](tools/README.md)。交付时记录适用规则及实际完成的检查。 +- 结构检查、人工语义核对、真实程序执行与读者测试分别报告；工具通过不代表例子已经运行。 +- 文档规范不替代语言决定，不因润色、采用模板或 AI 续写而确认未定语法。 + ## 文档组织 - 正文放在 guide，按概念依赖顺序编号；术语、文法、设计状态和补充说明放在 appendices。 @@ -31,3 +39,12 @@ - 名称查找、可见性和数据读取成员的假设明确说明，不虚构未确认 API。 - 已确定约定、语法提案和未定义边界统一记录在 appendices/specification-status.md；文档重构不代表语法提案被确认。 - 共用程序和表达式文法；UI 单根限制仅约束 render，不限制全语言。 + +## 仓库与交付 + +- 保留其他作者的未提交改动；共享链接使用仓库相对路径，不依赖本机目录或会话历史。 +- 对 gitea.entroia.com 的操作只认证为 codex-bot。仓库 owner 不代表认证身份，不借用 owner 的账户、密钥或凭据。 +- 在本仓库范围配置提交作者为 Codex Bot、codex-bot@gitea.entroia.local；SSH 使用 git 用户、22222 端口和 bot 专用密钥，以 -F /dev/null 与 IdentitiesOnly=yes 隔离其他身份。 +- 密钥和其他认证材料只在各电脑安全配置，不写入仓库。权限不足时完成可进行的本地工作，再申请 bot 权限。 +- 仅在用户授权时提交或推送，不强推覆盖远端。每次提交或推送后的中文报告覆盖所有改动文件及目的，并说明提交标识、推送状态、检查结果和未完成步骤。 +- 完整协作流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b6971e9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# 贡献与跨电脑协作 + +本仓库维护语言文档和作者手册。语言正文使用 guide，查询附录使用 appendices，研究、规则与模板使用 authoring。 + +## 开始阅读 + +首次参与先读 [AGENTS.md](AGENTS.md)、[作者手册](authoring/README.md)及目标章节的主要定义。每次改动按[工作流](authoring/workflow.md)选择适用规则。 + +本轮写作标准不改变语言设计稿的确定程度。提案确认需要明确的语言决定，不能仅凭修订文档或加入模板获得确认。 + +## 本地检查 + +检查工具只依赖 Python 3.10 或更新版本的标准库： + +```sh +python3 tools/check_docs.py +python3 -m unittest discover -s tools/tests -v +git diff --check +``` + +能力与限制见[工具说明](tools/README.md)。没有语言编译或执行工具时，只报告结构检查和人工核对，不宣称源码运行通过。 + +## Git 身份 + +远端为 [Endorphin-Document](https://gitea.entroia.com/Zayden-Jung/Endorphin-Document)。仓库 owner 与认证身份分开：所有 Codex Git 操作只使用 `codex-bot`，不得借用 owner 的账户、密钥或凭据。 + +提交作者在本仓库范围配置为： + +```sh +git config --local user.name "Codex Bot" +git config --local user.email "codex-bot@gitea.entroia.local" +``` + +SSH 使用用户 git、端口 22222 和本机为 codex-bot 配置的专用密钥，并以 `-F /dev/null` 与 `IdentitiesOnly=yes` 隔离其他身份。各电脑需要自行取得 bot 授权并配置专用密钥；不把密钥、密码或 Authorization 头存进仓库。 + +远端的 SSH 地址为： + +```text +ssh://git@gitea.entroia.com:22222/Zayden-Jung/Endorphin-Document.git +``` + +## 修改与交付 + +开始前检查分支与未提交改动，保留其他作者的编辑。修改后核对主定义、例子、文法、目录与状态，再审查暂存范围。 + +仅在用户授权时提交或推送，不强推覆盖远端。权限不足时保留本地工作，请用户为 codex-bot 授予权限，不切换账号。 + +交付报告使用中文，说明提交标识、推送状态、检查结果，以及每个修改文件的目的与内容。可以按共同目的分组，但新增、移动或删除文件也需要覆盖。 + +## 不入库的内容 + +个人编辑器状态、机器专用路径、环境秘密与认证材料不随文档同步。共享的是文本、相对链接、规则和验证流程，而不是某台电脑的会话或配置。 + +[语言文档入口](README.md) · [作者手册](authoring/README.md) diff --git a/README.md b/README.md index 9b94748..5be311e 100644 --- a/README.md +++ b/README.md @@ -46,3 +46,9 @@ Endorphin 是一门面向云原生应用的编程语言，使用统一的语言 “代码归属”写在代码块之前，用于说明外部上下文，不属于源码。函数体片段和渲染节点片段会注明使用位置。示例中的用户和 namespace 为示意名称。 正文的函数示例围绕商品定价展开：`alice:shop.pricing` 提供定价逻辑，`bob:shop.checkout` 组合它，`bob:shop.ui` 表达界面；数据读取示例使用 `alice:shop.data`。这些路径表示代码组织，不指定执行位置。 + +## 文档维护入口 + +编写或修改本书时，从[文档编写手册](authoring/README.md)开始。手册包含案例分析、稳定编号的写作规则、页面模板与检查流程，不属于语言学习主线，也不确认新的语言语义。 + +[贡献与跨电脑协作](CONTRIBUTING.md)说明维护约定和本地检查；[检查工具](tools/README.md)提供无需第三方依赖的结构验证。 diff --git a/authoring/CHANGELOG.md b/authoring/CHANGELOG.md new file mode 100644 index 0000000..dff0335 --- /dev/null +++ b/authoring/CHANGELOG.md @@ -0,0 +1,18 @@ +# 手册维护记录 + +## 2026-10-07 + +- 建立 DOC-001～DOC-024 写作规则，每条独立分页。 +- 登记 SRC-01～SRC-15：用户提供 13 个来源，补充 2 个方法来源。 +- 完成 12 个可读页面的结构观察与适用分析；3 个知乎来源保留未读记录。 +- 增加 TPL-01～TPL-04、修改流程、检查清单和基线应用评估。 +- 增加可迁移的检查工具与测试，把手册入口接入仓库约定。 +- 未操作原站交互实例，未进行真实读者实验，未确认新的语言语义。 + +## 维护方式 + +增补记录使用实际核查日期，说明改动的规则、来源或模板 ID。状态变化保留先前记录，编号不重新分配。 + +不可读来源取得正文后，先核对对应页面，再补充分析与引用关系。语言正文的语义确认记录由规范状态维护，不用手册变更替代。 + +[手册入口](README.md) diff --git a/authoring/README.md b/authoring/README.md new file mode 100644 index 0000000..d44d93c --- /dev/null +++ b/authoring/README.md @@ -0,0 +1,75 @@ +# 文档编写手册 + +本手册用于 Endorphin 文档的新增、修改和审查。它将外部案例分析转化为可执行的项目写作约定，不定义新的语言语义。 + +## 每次修改的入口 + +1. 阅读仓库 [AGENTS.md](../AGENTS.md) 与[工作流](workflow.md)。 +2. 从下面的问题索引选择适用规则，阅读对应规则页；结构性改写至少检查 DOC-001、002、005、015、021、024。 +3. 选择[页面模板](templates/README.md)，编辑主要定义与关联引用。 +4. 使用[检查清单](checklist.md)，运行[文档检查工具](../tools/README.md)，记录结果。 + +小型错字修正不要求阅读全部 24 页；更改语法或章节结构必须覆盖其影响范围。手册规则与用户明确的语言决定冲突时，以用户决定为准并同步修订手册。 + +## 按问题查阅 + +| 正在解决的问题 | 规则 | +| --- | --- | +| 读者不知道这是什么，首页像约定清单 | [001](rules/DOC-001.md)、[003](rules/DOC-003.md) | +| 章节像聊天记录，教学、查询与争论混在一起 | [002](rules/DOC-002.md)、[018](rules/DOC-018.md) | +| 阅读时反复跳转，概念未介绍就出现 | [004](rules/DOC-004.md)、[005](rules/DOC-005.md) | +| 一章过大或分得过碎 | [006](rules/DOC-006.md) | +| 知道问题但找不到具体规则 | [007](rules/DOC-007.md)、[008](rules/DOC-008.md) | +| 示例不知道放哪里、没有结果或过于复杂 | [009](rules/DOC-009.md)、[010](rules/DOC-010.md)、[011](rules/DOC-011.md) | +| 只有成功用法，没有边界 | [012](rules/DOC-012.md)、[013](rules/DOC-013.md) | +| 多个概念或方案看起来一样 | [014](rules/DOC-014.md) | +| 不清楚哪些是提案，或正文充满免责声明 | [015](rules/DOC-015.md) | +| 语言用法混入系统实现 | [016](rules/DOC-016.md) | +| 名词、代码与输出记法不一致 | [017](rules/DOC-017.md)、[019](rules/DOC-019.md) | +| 外部建议无法核查，读不到页面 | [020](rules/DOC-020.md) | +| 改完一个章节后其他页面失配 | [021](rules/DOC-021.md) | +| 需要换电脑、换作者或让 AI 接续 | [022](rules/DOC-022.md)、[023](rules/DOC-023.md) | +| 工具检查都通过，但读者还是不懂 | [024](rules/DOC-024.md) | + +## 规则索引 + +规则 ID 是稳定身份，不是阅读顺序。核心规则一般适用；建议规则按内容判断；条件规则只在对应情境使用。修改或废弃规则不重新分配其 ID。 + +| 编号 | 规则 | 分类 | 级别 | +| --- | --- | --- | --- | +| [DOC-001](rules/DOC-001.md) | 先确定读者与阅读目标 | 读者与定位 | 核心 | +| [DOC-002](rules/DOC-002.md) | 确定页面的主要职责 | 读者与定位 | 核心 | +| [DOC-003](rules/DOC-003.md) | 入口先建立全局理解 | 读者与定位 | 核心 | +| [DOC-004](rules/DOC-004.md) | 显式交代前置知识与上下文 | 读者与定位 | 核心 | +| [DOC-005](rules/DOC-005.md) | 按概念依赖安排阅读顺序 | 结构与导航 | 核心 | +| [DOC-006](rules/DOC-006.md) | 按读者问题分页 | 结构与导航 | 核心 | +| [DOC-007](rules/DOC-007.md) | 同时支持顺序阅读与按需查找 | 结构与导航 | 核心 | +| [DOC-008](rules/DOC-008.md) | 稳定编号与唯一主定义 | 结构与导航 | 核心 | +| [DOC-009](rules/DOC-009.md) | 最小示例必须有完整条件 | 示例与教学 | 核心 | +| [DOC-010](rules/DOC-010.md) | 形成代码、结果与解释的闭环 | 示例与教学 | 核心 | +| [DOC-011](rules/DOC-011.md) | 每个递进例子只增加少量新概念 | 示例与教学 | 建议 | +| [DOC-012](rules/DOC-012.md) | 把边界与失败写在相关规则旁 | 示例与教学 | 核心 | +| [DOC-013](rules/DOC-013.md) | 用可观察契约说明语义 | 语义与边界 | 核心 | +| [DOC-014](rules/DOC-014.md) | 比较方案时给出选择维度 | 语义与边界 | 条件 | +| [DOC-015](rules/DOC-015.md) | 区分确定规则、语法提案与未定边界 | 语义与边界 | 核心 | +| [DOC-016](rules/DOC-016.md) | 区分语言模型与实现机制 | 语义与边界 | 核心 | +| [DOC-017](rules/DOC-017.md) | 统一术语与展示记法 | 表述与证据 | 核心 | +| [DOC-018](rules/DOC-018.md) | 使用独立成立的文档陈述 | 表述与证据 | 核心 | +| [DOC-019](rules/DOC-019.md) | 让格式服务理解与查找 | 表述与证据 | 建议 | +| [DOC-020](rules/DOC-020.md) | 证据、分析与项目规则分层 | 表述与证据 | 核心 | +| [DOC-021](rules/DOC-021.md) | 每次改动完成影响检查 | 协作与质量 | 核心 | +| [DOC-022](rules/DOC-022.md) | 把文档作为可迁移的仓库资产 | 协作与质量 | 核心 | +| [DOC-023](rules/DOC-023.md) | 为人工与 AI 作者规定相同交付标准 | 协作与质量 | 核心 | +| [DOC-024](rules/DOC-024.md) | 用读者任务验收文档 | 协作与质量 | 核心 | + +## 研究与应用 + +- [来源登记](research/sources.md)：15 个来源的 URL、类别与访问状态，其中 13 个由用户提供，2 个为补充方法资料。 +- [分析总览](research/synthesis.md)：为什么这些做法有用，以及不应照搬什么。 +- [当前文档的应用评估](adoption.md)：基线检查、剩余问题与后续改写优先级。 +- [维护记录](CHANGELOG.md)：手册自身的变更及未读来源的补充状态。 +- [贡献流程](../CONTRIBUTING.md)：跨电脑和多作者协作。 + +研究页区分可观察做法与作用推断。没有进行用户可用性实验，不把分析写成已验证的阅读效率。不可读来源不参与观点归纳。 + +[语言文档入口](../README.md) diff --git a/authoring/adoption.md b/authoring/adoption.md new file mode 100644 index 0000000..6f09296 --- /dev/null +++ b/authoring/adoption.md @@ -0,0 +1,44 @@ +# 当前文档的应用评估 + +评估对象：语言文档基线提交 `a33f809`。方法：作者按本手册进行结构与内容自查，未进行真实用户实验或语言执行测试。 + +## 已具备的组织 + +| 项目 | 对应规则 | 基线情况 | +| --- | --- | --- | +| 概念依赖顺序 | DOC-005 | 身份与 namespace 在程序结构、语法及应用之前 | +| 独立查询主题 | DOC-006、007 | 类、表达式、函数、数据和 UI 分章，附录集中参考 | +| 明确语法状态 | DOC-015 | 入口与附录说明设计稿，get 和官方引用保留局部说明 | +| 跨 namespace 语义 | DOC-013、016 | 参数、结果与数据依赖不绑定协议实现 | +| 连续业务背景 | DOC-011 | 商品与定价贯穿主要例子 | +| 术语与记法 | DOC-017 | Preflight、inflight 和外部归属统一展示 | + +以上只记录观察到的组织，不表示全部规则已完美满足。 + +## 优先改进项目 + +### A-01 增加明确的读者目标 + +读者背景与每章阅读后的能力仍可更具体。后续优先为首页说明适合谁、需要哪些基础，以及设计稿不等于可执行教程。适用规则：DOC-001、003、004。 + +### A-02 完善示例闭环 + +数据读取等章节虽然说明预期效果，但并非所有关键例子都有同等清晰的输入和核对点。可补充成功路径的确定输入与结果，同时保留 get 的提案状态。适用规则：DOC-009、010、015。 + +### A-03 补充边界用法的解释 + +函数参数数量、类型和单根规则已有说明，仍可用更一致的“原因—诊断阶段—修正思路”组织。未确定的错误处理语法不能补造。适用规则：DOC-012、013。 + +### A-04 支持真正的跳转阅读 + +检查从术语表或文法直接进入类、调用和 UI 页时，是否拥有足够的局部条件。对未定义成员或官方来源保留短注，但减少对其他章节的强记忆依赖。适用规则：DOC-004、007、008。 + +### A-05 验证理解而非只验证格式 + +让未参与设计的人尝试复述定位与调用模型、寻找 use 规则并预测组合函数结果；记录卡住的位置。当前只具备作者自查，不能宣称读者测试通过。适用规则：DOC-024。 + +## 本轮边界 + +本轮建立手册、模板和维护流程，不自动根据上述评估改写语言正文，不将任何提案确认成最终规范。后续每个应用项目分别修改与验证，保留可审查的差异。 + +[分析总览](research/synthesis.md) · [手册入口](README.md) diff --git a/authoring/checklist.md b/authoring/checklist.md new file mode 100644 index 0000000..bb88c1e --- /dev/null +++ b/authoring/checklist.md @@ -0,0 +1,46 @@ +# 文档修改检查清单 + +适用于每次文档改动。逐项记录通过、不通过或不适用及原因，不把勾选清单当作验证结果。 + +## 读者与结构 + +- [ ] DOC-001：本页读者与阅读目标可明确表达。 +- [ ] DOC-002：主要职责明确，不混入研发记录。 +- [ ] DOC-003～008：概念前提、分页、目录、主定义与稳定引用合适。 +- [ ] DOC-018：未参与聊天的人能理解陈述。 + +## 用法与示例 + +- [ ] DOC-004、009：外部归属、片段位置、依赖和假设明确。 +- [ ] DOC-010、011：例子有可核对结果，变化范围合理。 +- [ ] DOC-012、013：边界、类型、依赖和阶段说明与语法一致。 +- [ ] DOC-014：若存在对比，其共同维度与适用条件明确。 +- [ ] DOC-015、016：提案未被擅自确认，实现机制未成为语法规则。 +- [ ] DOC-017、019：术语、展示记法和格式一致。 + +## 证据与协作 + +- [ ] DOC-020：来源可核查，分析与事实分开，不可读来源未被伪造。 +- [ ] DOC-021：文法、导航、示例和状态已同步。 +- [ ] DOC-022、023：工作区被保留，文件无本机依赖或凭据，AI 未越过语义决定范围。 +- [ ] DOC-024：完成冷读、主题定位与结果预测自查，记录障碍。 + +## 自动检查 + +- [ ] `python3 tools/check_docs.py`：记录退出码与报告。 +- [ ] `python3 -m unittest discover -s tools/tests -v`：记录工具测试结果。 +- [ ] `git diff --check`：无差异格式问题。 +- [ ] 需要提交时另运行 `git diff --cached --check`。 + +## 验证等级 + +| 等级 | 可以报告的事实 | 不能据此宣称 | +| --- | --- | --- | +| 自动结构检查 | 链接、锚点、围栏和有限约定通过 | 源码已经编译运行 | +| 作者语义自查 | 示例计算、上下文与已写规则一致 | 静态类型体系全部实现 | +| 作者冷读自查 | 以读者任务检查并记录障碍 | 真实用户可用性实验通过 | +| 真实执行或读者测试 | 指定环境和参与者下取得的实际结果 | 所有环境与所有读者均无问题 | + +本仓库未提供完整语言编译与执行工具。若未执行，写明“未做编译或运行验证”；不要将预期输出贴成执行日志。 + +[规则索引](README.md#规则索引) · [工作流](workflow.md) diff --git a/authoring/research/SRC-01.md b/authoring/research/SRC-01.md new file mode 100644 index 0000000..5872672 --- /dev/null +++ b/authoring/research/SRC-01.md @@ -0,0 +1,31 @@ +# SRC-01 Vue：简介 + +来源：[Vue：简介](https://cn.vuejs.org/guide/introduction.html)。类别：官方项目指南。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：“什么是 Vue”“预备知识”“API 风格”“选择你的学习路径”。 + +- 开篇定义用途，紧接计数器示例与结果。 +- 明确预备知识，区分 API 风格和学习入口。 + +## 作用分析 + +入口同时回答产品定位与学习起点；不同读者不必走同一条路线。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +概览先解释 Endorphin 的用途与核心模型；语言介绍、语法查询和作者手册各自有入口。 + +## 借鉴边界 + +可以借鉴入口组织，不能照搬其单文件组件、响应式模型或两套 API 风格。 + +## 对应规则 + +- [DOC-003](../rules/DOC-003.md) +- [DOC-007](../rules/DOC-007.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-02.md b/authoring/research/SRC-02.md new file mode 100644 index 0000000..4f3dde7 --- /dev/null +++ b/authoring/research/SRC-02.md @@ -0,0 +1,33 @@ +# SRC-02 MDN：表达式与运算符 + +来源：[MDN：表达式与运算符](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Expressions_and_operators)。类别：技术平台指南。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：运算符分类、赋值表、优先级、分组示例、参考链接。 + +- 按运算符类别分节，并用表格集中查询。 +- 用分组前后结果解释优先级，另链详细参考。 + +## 作用分析 + +分类入口减少扫描范围；相近表达式的不同结果帮助理解规则，而不仅记住符号。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +表达式章节说明值与组合方式，文法附录提供精确形式；优先级配对照结果。 + +## 借鉴边界 + +页面仍包含标为非标准或实验性的内容。组织值得借鉴，不代表每项 JavaScript 内容均可当作稳定规范；也不将优先级等同于所有调用的执行顺序。 + +## 对应规则 + +- [DOC-008](../rules/DOC-008.md) +- [DOC-010](../rules/DOC-010.md) +- [DOC-013](../rules/DOC-013.md) +- [DOC-015](../rules/DOC-015.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-03.md b/authoring/research/SRC-03.md new file mode 100644 index 0000000..6e1aa90 --- /dev/null +++ b/authoring/research/SRC-03.md @@ -0,0 +1,32 @@ +# SRC-03 W3Schools：HTML Elements + +来源：[W3Schools：HTML Elements](https://www.w3schools.com/html/html_elements.asp)。类别：第三方入门教程。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：元素结构表、Nested HTML Elements、Example Explained、Tag Reference。 + +- 把元素拆成结构表，再展示嵌套实例。 +- 例子之后解释组成部分，并提供尝试和参考入口。 + +## 作用分析 + +结构拆解使符号与概念对应；从局部到嵌套降低一次理解的范围。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +scene、render 和节点分别解释；首次嵌套例子说明根与子节点。 + +## 借鉴边界 + +只学习教学组织；HTML 标签及其语义不能推导 Endorphin 组件规则。 + +## 对应规则 + +- [DOC-005](../rules/DOC-005.md) +- [DOC-010](../rules/DOC-010.md) +- [DOC-019](../rules/DOC-019.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-04.md b/authoring/research/SRC-04.md new file mode 100644 index 0000000..8a31dd6 --- /dev/null +++ b/authoring/research/SRC-04.md @@ -0,0 +1,32 @@ +# SRC-04 W3Schools：React Render HTML + +来源：[W3Schools：React Render HTML](https://www.w3schools.com/react/react_render.asp)。类别：第三方任务教程。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：The Container、简化文件、createRoot、render、结果图、运行入口。 + +- 说明宿主容器与已有项目上下文，再简化示例。 +- 连接代码、结果图和运行入口。 + +## 作用分析 + +读者能定位操作环境与预期结果；去掉无关配置让当前步骤更突出。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +教程交代代码归属与使用位置；一个示例只承担本节需要演示的变化。 + +## 借鉴边界 + +它依赖前章准备的文件。Endorphin 没有源码文件模型，不能照搬文件路径；本研究没有实际操作运行入口。 + +## 对应规则 + +- [DOC-004](../rules/DOC-004.md) +- [DOC-009](../rules/DOC-009.md) +- [DOC-010](../rules/DOC-010.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-05.md b/authoring/research/SRC-05.md new file mode 100644 index 0000000..28a8ab8 --- /dev/null +++ b/authoring/research/SRC-05.md @@ -0,0 +1,32 @@ +# SRC-05 W3Schools：Rust Arrays + +来源：[W3Schools：Rust Arrays](https://www.w3schools.com/rust/rust_arrays.php)。类别：第三方主题教程。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：创建、索引、修改、长度、循环、固定与动态大小。 + +- 围绕同一结构安排一组基本操作。 +- 在取值与修改处说明条件，并对比固定与动态结构。 + +## 作用分析 + +操作顺序形成可跟随路径；条件与边界在相关动作旁出现。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +围绕 Product 与定价串联声明、访问和调用；把不合法使用与相关规则放在一起。 + +## 借鉴边界 + +不能把数组、mut 或 vectors 的语义移植到语言设计；错误例子必须进一步说明属于 Preflight 还是 inflight。 + +## 对应规则 + +- [DOC-011](../rules/DOC-011.md) +- [DOC-012](../rules/DOC-012.md) +- [DOC-014](../rules/DOC-014.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-06.md b/authoring/research/SRC-06.md new file mode 100644 index 0000000..b3b12e1 --- /dev/null +++ b/authoring/research/SRC-06.md @@ -0,0 +1,32 @@ +# SRC-06 Matplotlib：Application Interfaces + +来源：[Matplotlib：Application Interfaces](https://matplotlib.org/stable/users/explain/figure/api_interfaces.html)。类别：官方概念说明。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：两类接口、相同绘图示例、操作对照表、Why be explicit、总结。 + +- 用相同任务对照显式与隐式接口。 +- 解释选择理由，并给出操作对应表。 + +## 作用分析 + +同任务对比突出真实差异；选择依据把知识转成决策，而不是孤立罗列 API。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +解释归属 key 与 use key、一次读取与持续结果等概念时，按共同维度比较。 + +## 借鉴边界 + +不据此给 Endorphin 增设两套接口，也不借研究选择未确定的调用或渲染方案。 + +## 对应规则 + +- [DOC-014](../rules/DOC-014.md) +- [DOC-016](../rules/DOC-016.md) +- [DOC-019](../rules/DOC-019.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-07.md b/authoring/research/SRC-07.md new file mode 100644 index 0000000..67f8de3 --- /dev/null +++ b/authoring/research/SRC-07.md @@ -0,0 +1,32 @@ +# SRC-07 VS Code：Agents Overview + +来源：[VS Code：Agents Overview](https://code.visualstudio.com/docs/agents/overview)。类别：官方产品概览。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：目标与工作方式表、agent loop、不同入口、Stay in control、Next steps。 + +- 按使用目标连接工作方式与下一步页面。 +- 描述行动与验证流程，并明确人工审查责任。 + +## 作用分析 + +读者从目标选择入口；自动执行的能力与人的责任边界同时可见。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +作者工作流连接任务、相关规则、改动和检查；AI 不自行确认语言设计。 + +## 借鉴边界 + +产品与账号可用性易变化，只借鉴结构；本手册不规定任何编辑器、模型或运行服务。 + +## 对应规则 + +- [DOC-007](../rules/DOC-007.md) +- [DOC-021](../rules/DOC-021.md) +- [DOC-023](../rules/DOC-023.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-08.md b/authoring/research/SRC-08.md new file mode 100644 index 0000000..811f08e --- /dev/null +++ b/authoring/research/SRC-08.md @@ -0,0 +1,32 @@ +# SRC-08 pandas：User Guide + +来源：[pandas：User Guide](https://pandas.pydata.org/docs/user_guide/index.html#user-guide)。类别：官方指南目录。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：开篇定位、入门链接、API reference、How to read、主题目录。 + +- 提供新人入口、主题指南与 API 查询入口。 +- 说明普通代码与 notebook 输入输出记法。 + +## 作用分析 + +按经验和问题分流；记法说明防止读者把展示标记误当源码。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +统一归属标记、片段与预期结果记法；为完整阅读和具体查找提供不同索引。 + +## 借鉴边界 + +本次目录页研究不评价其全部主题内容；不把 notebook 提示符或导入方式当作 Endorphin 写法。 + +## 对应规则 + +- [DOC-007](../rules/DOC-007.md) +- [DOC-009](../rules/DOC-009.md) +- [DOC-017](../rules/DOC-017.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-09.md b/authoring/research/SRC-09.md new file mode 100644 index 0000000..b906cc3 --- /dev/null +++ b/authoring/research/SRC-09.md @@ -0,0 +1,32 @@ +# SRC-09 scikit-learn：User Guide + +来源：[scikit-learn：User Guide](https://scikit-learn.org/stable/user_guide.html)。类别：官方主题索引。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：监督学习、无监督学习、评估、转换、常见问题及多层编号。 + +- 按主题体系组织多层编号目录。 +- 除算法外，单列评估、实践问题和选择入口。 + +## 作用分析 + +主题层次为大范围内容提供定位坐标；学习对象与使用决策都有入口。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +语言概念按依赖排序；规则使用独立稳定编号，目录重排不改变规则身份。 + +## 借鉴边界 + +观察仅针对所给目录，不推断每个子页面质量；不以目录越深或编号越多判断文档越好。 + +## 对应规则 + +- [DOC-005](../rules/DOC-005.md) +- [DOC-006](../rules/DOC-006.md) +- [DOC-008](../rules/DOC-008.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-10.md b/authoring/research/SRC-10.md new file mode 100644 index 0000000..fcbe69d --- /dev/null +++ b/authoring/research/SRC-10.md @@ -0,0 +1,19 @@ +# SRC-10 知乎问题 19945828 + +来源：[用户指定页面](https://www.zhihu.com/question/19945828)。核查日期：2026-10-07。 + +## 访问记录 + +状态：未取得正文。 + +直接访问未返回可读正文；使用精确链接或编号检索也没有找到可核对的目标内容。未确认作者、标题或具体建议，不用其他知乎页面代替该来源。 + +## 研究边界 + +本页不参与建议推导，也不计为已阅读案例。当前手册可以使用其他已读取资料完成，不因该页面不可读而伪造其观点。 + +## 补充流程 + +取得用户提供的正文或可访问版本后，记录对应页面与作者、核对文本来源，再按观察、作用分析、适用边界补充案例。保留来源编号，并在手册变更记录中注明补充时间。 + +[来源目录](sources.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-11.md b/authoring/research/SRC-11.md new file mode 100644 index 0000000..5a90a71 --- /dev/null +++ b/authoring/research/SRC-11.md @@ -0,0 +1,32 @@ +# SRC-11 Wikipedia：Software documentation + +来源：[Wikipedia：Software documentation](https://en.wikipedia.org/wiki/Software_documentation)。类别：背景资料，不作为规范权威。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：文档类别、User documentation、Docs as Code。 + +- 区分需求、设计、技术与用户等文档用途。 +- 提到索引与版本控制等维护组织。 + +## 作用分析 + +同一软件的不同文档服务不同工作；用户手册不应成为实现记录的集合。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +语言正文、未定设计、研究笔记和作者规则分开；全部随仓库版本维护。 + +## 借鉴边界 + +百科是背景材料；流程规则由本项目制定，不冒充百科条目的强制标准。 + +## 对应规则 + +- [DOC-002](../rules/DOC-002.md) +- [DOC-018](../rules/DOC-018.md) +- [DOC-022](../rules/DOC-022.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-12.md b/authoring/research/SRC-12.md new file mode 100644 index 0000000..6c4ab5c --- /dev/null +++ b/authoring/research/SRC-12.md @@ -0,0 +1,19 @@ +# SRC-12 知乎回答 2075892005796950996 + +来源：[用户指定页面](https://www.zhihu.com/question/27002458/answer/2075892005796950996)。核查日期：2026-10-07。 + +## 访问记录 + +状态：未取得正文。 + +直接访问未返回可读正文；使用精确链接或编号检索也没有找到可核对的目标内容。未确认作者、标题或具体建议，不用其他知乎页面代替该来源。 + +## 研究边界 + +本页不参与建议推导，也不计为已阅读案例。当前手册可以使用其他已读取资料完成，不因该页面不可读而伪造其观点。 + +## 补充流程 + +取得用户提供的正文或可访问版本后，记录对应页面与作者、核对文本来源，再按观察、作用分析、适用边界补充案例。保留来源编号，并在手册变更记录中注明补充时间。 + +[来源目录](sources.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-13.md b/authoring/research/SRC-13.md new file mode 100644 index 0000000..9805ae6 --- /dev/null +++ b/authoring/research/SRC-13.md @@ -0,0 +1,19 @@ +# SRC-13 知乎回答 1983859842016879856 + +来源：[用户指定页面](https://www.zhihu.com/question/27439430/answer/1983859842016879856)。核查日期：2026-10-07。 + +## 访问记录 + +状态：未取得正文。 + +直接访问未返回可读正文；使用精确链接或编号检索也没有找到可核对的目标内容。未确认作者、标题或具体建议，不用其他知乎页面代替该来源。 + +## 研究边界 + +本页不参与建议推导，也不计为已阅读案例。当前手册可以使用其他已读取资料完成，不因该页面不可读而伪造其观点。 + +## 补充流程 + +取得用户提供的正文或可访问版本后，记录对应页面与作者、核对文本来源，再按观察、作用分析、适用边界补充案例。保留来源编号，并在手册变更记录中注明补充时间。 + +[来源目录](sources.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-14.md b/authoring/research/SRC-14.md new file mode 100644 index 0000000..d8b31bb --- /dev/null +++ b/authoring/research/SRC-14.md @@ -0,0 +1,32 @@ +# SRC-14 Diátaxis：文档类型框架 + +来源：[Diátaxis：文档类型框架](https://diataxis.fr/)。类别：补充的方法作者资料。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：首页四种文档需求及对应类型。 + +- 区分教程、操作指南、技术参考与解释。 +- 以读者需要组织内容类型。 + +## 作用分析 + +写作时先决定页面解决什么问题，可避免把教学步骤、精确查询和设计理由混在一起。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +页面先确定主要职责；共享主题可以互链，不要求每页承担所有职责。 + +## 借鉴边界 + +该框架不是 Endorphin 的既定目录，也不要求立刻创建空教程或四套重复章节。 + +## 对应规则 + +- [DOC-001](../rules/DOC-001.md) +- [DOC-002](../rules/DOC-002.md) +- [DOC-006](../rules/DOC-006.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/SRC-15.md b/authoring/research/SRC-15.md new file mode 100644 index 0000000..940f9e4 --- /dev/null +++ b/authoring/research/SRC-15.md @@ -0,0 +1,32 @@ +# SRC-15 Google Technical Writing：Audience + +来源：[Google Technical Writing：Audience](https://developers.google.com/tech-writing/one/audience)。类别：补充的官方写作课程。核查日期：2026-10-07。 + +## 可核查的页面做法 + +定位：Define your audience、学习目标、知识接近程度、Curse of knowledge。 + +- 从读者背景与需要学习的内容确定写作范围。 +- 提醒作者避免默认读者具有团队内部知识。 + +## 作用分析 + +按知识差距选择解释内容，比按照作者研究顺序罗列信息更贴近读者。 + +这是根据页面结构作出的分析，不是原作者承诺或用户测试结论。 + +## Endorphin 的应用 + +每次修改先记录目标读者、已知知识与阅读后的能力；冷读时检查未解释术语。 + +## 借鉴边界 + +课程提供方法，不提供语言设计决定；本项目没有进行用户实验，相关收益是分析推断。 + +## 对应规则 + +- [DOC-001](../rules/DOC-001.md) +- [DOC-004](../rules/DOC-004.md) +- [DOC-024](../rules/DOC-024.md) + +[来源目录](sources.md) · [分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/sources.md b/authoring/research/sources.md new file mode 100644 index 0000000..745aca2 --- /dev/null +++ b/authoring/research/sources.md @@ -0,0 +1,41 @@ +# 来源登记 + +核查日期：2026-10-07（Asia/Shanghai）。研究对象是指定页面的组织与表述，不是这些技术的全站能力。 + +## 阅读状态 + +- 已读取：12 个页面，包括用户提供的 10 个可读来源及 2 个补充方法来源。 +- 未取得正文：3 个知乎来源。 +- 未执行：网页里的交互例子、真实读者实验、全站或全部子页面审查。 + +“已读取”表示取得正文并核对案例页所列部分，不表示运行其代码。页面会变化；再次引用具体产品或语义时应重新核查。 + +## 索引 + +| 编号 | 来源与原始地址 | 类别 | 状态 | 分析页 | +| --- | --- | --- | --- | --- | +| SRC-01 | [Vue：简介](https://cn.vuejs.org/guide/introduction.html) | 官方项目指南 | 已读取指定页面 | [记录](SRC-01.md) | +| SRC-02 | [MDN：表达式与运算符](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Expressions_and_operators) | 技术平台指南 | 已读取指定页面 | [记录](SRC-02.md) | +| SRC-03 | [W3Schools：HTML Elements](https://www.w3schools.com/html/html_elements.asp) | 第三方入门教程 | 已读取指定页面 | [记录](SRC-03.md) | +| SRC-04 | [W3Schools：React Render HTML](https://www.w3schools.com/react/react_render.asp) | 第三方任务教程 | 已读取指定页面 | [记录](SRC-04.md) | +| SRC-05 | [W3Schools：Rust Arrays](https://www.w3schools.com/rust/rust_arrays.php) | 第三方主题教程 | 已读取指定页面 | [记录](SRC-05.md) | +| SRC-06 | [Matplotlib：Application Interfaces](https://matplotlib.org/stable/users/explain/figure/api_interfaces.html) | 官方概念说明 | 已读取指定页面 | [记录](SRC-06.md) | +| SRC-07 | [VS Code：Agents Overview](https://code.visualstudio.com/docs/agents/overview) | 官方产品概览 | 已读取指定页面 | [记录](SRC-07.md) | +| SRC-08 | [pandas：User Guide](https://pandas.pydata.org/docs/user_guide/index.html#user-guide) | 官方指南目录 | 已读取指定页面 | [记录](SRC-08.md) | +| SRC-09 | [scikit-learn：User Guide](https://scikit-learn.org/stable/user_guide.html) | 官方主题索引 | 已读取指定页面 | [记录](SRC-09.md) | +| SRC-10 | [知乎问题 19945828](https://www.zhihu.com/question/19945828) | 用户提供的教程线索 | 未取得正文 | [记录](SRC-10.md) | +| SRC-11 | [Wikipedia：Software documentation](https://en.wikipedia.org/wiki/Software_documentation) | 背景资料，不作为规范权威 | 已读取指定页面 | [记录](SRC-11.md) | +| SRC-12 | [知乎回答 2075892005796950996](https://www.zhihu.com/question/27002458/answer/2075892005796950996) | 用户提供的教程线索 | 未取得正文 | [记录](SRC-12.md) | +| SRC-13 | [知乎回答 1983859842016879856](https://www.zhihu.com/question/27439430/answer/1983859842016879856) | 用户提供的教程线索 | 未取得正文 | [记录](SRC-13.md) | +| SRC-14 | [Diátaxis：文档类型框架](https://diataxis.fr/) | 补充的方法作者资料 | 已读取指定页面 | [记录](SRC-14.md) | +| SRC-15 | [Google Technical Writing：Audience](https://developers.google.com/tech-writing/one/audience) | 补充的官方写作课程 | 已读取指定页面 | [记录](SRC-15.md) | + +## 证据处理 + +保留原始链接；跳转后仍需核对目标是否为同一页面。观察以页内标题或区域定位，不用可能变化的抓取行号作为永久索引。 + +知乎来源已经尝试直接访问和精确链接或编号检索，尚未取得可核对正文。不得用相似标题的页面或未经核对的摘要代替。取得正文后保留原编号，补充作者、标题、观察与核查日期。 + +研究笔记只进行有限转述，不镜像原页、不搬运整段源代码。所有项目规则是综合适配建议，不宣称原站逐项认可。 + +[分析总览](synthesis.md) · [手册入口](../README.md) diff --git a/authoring/research/synthesis.md b/authoring/research/synthesis.md new file mode 100644 index 0000000..6af3152 --- /dev/null +++ b/authoring/research/synthesis.md @@ -0,0 +1,50 @@ +# 文档案例分析总览 + +优秀文档的价值不在统一的外观，而在于读者能建立模型、完成当前任务、找到精确规则并核对结果。下表归纳不同页面的侧重；效果解释属于本项目分析，不是测量结论。 + +## 各案例的长处与边界 + +| 案例 | 可观察做法 | 值得借鉴的重点 | 不宜照搬 | +| --- | --- | --- | --- | +| [Vue / SRC-01](SRC-01.md) | 定义、示例、前提与学习入口 | 先形成全局认识 | 文件模型和多 API 风格 | +| [MDN / SRC-02](SRC-02.md) | 分类、表格、结果对照与参考链接 | 概念讲解和精确查询互相连接 | 非标准条目当作稳定规范 | +| [HTML / SRC-03](SRC-03.md) | 结构拆解、嵌套、例子解释 | 从小结构建立组合关系 | 标签语义移植到组件 | +| [React / SRC-04](SRC-04.md) | 交代容器、简化代码、展示结果 | 上下文与结果闭环 | 依赖文件与前章准备的形式 | +| [Rust / SRC-05](SRC-05.md) | 连续操作、条件与边界 | 少量新概念逐步加入 | 在本语言中引入对应 API | +| [Matplotlib / SRC-06](SRC-06.md) | 同任务接口对照与选择原因 | 概念差异用于判断 | 因比较而创造另一套语法 | +| [VS Code / SRC-07](SRC-07.md) | 目标分流、验证与人工审查 | 写作流程有职责边界 | 绑定特定编辑器、账号或模型 | +| [pandas / SRC-08](SRC-08.md) | 不同学习入口、记法与主题目录 | 多入口与展示规范 | 仅凭目录评价所有章节 | +| [scikit-learn / SRC-09](SRC-09.md) | 多层主题与实践、选择入口 | 大范围内容可定位 | 追求复杂编号或目录深度 | +| [Wikipedia / SRC-11](SRC-11.md) | 文档用途与维护方式分类 | 使用手册不等于实现记录 | 百科作为项目强制标准 | +| [Diátaxis / SRC-14](SRC-14.md) | 按需求区分文档职责 | 先决定页面要做什么 | 为分类复制整套内容 | +| [Google / SRC-15](SRC-15.md) | 读者背景与学习目标 | 按知识差距选解释 | 作者自查冒充读者实验 | + +[三个知乎记录](sources.md)未取得正文，不在该比较中评价其优劣。 + +## 对 Endorphin 的综合方法 + +### 让主线服务理解 + +身份和 namespace 是程序定位的前提；程序结构、阶段、类型和表达式支持后续调用与 UI 用法。章节顺序由这些关系决定，而不是研发议题出现的顺序。 + +### 让参考服务查询 + +一份主定义、一套完整文法、稳定规则 ID、术语和主题索引共同支持跳转阅读。结构精简不是删除必要条件；局部页面仍需要最小上下文。 + +### 让例子服务迁移 + +采用声明、输入、结果与关键解释的闭环。逐步组合少量概念，在触及边界时说明失败。源码、展示结果与提案状态必须可区分。 + +### 让写作与语言决定分离 + +文档可以采用确定的编写规范，同时保持语言处于设计稿阶段。官方引用、get、等待和错误处理等未定项不能因为页面要写得流畅而被擅自确认。 + +### 让维护可复现 + +每次修改选择适用规则，检查关联章节，再运行工具并完成读者任务自查。版本控制保存变更；真实读者测试、语法检查与运行测试分别报告。 + +## 尚需验证的效果 + +本研究尚未证明上述方法提高了真实读者的理解或定位速度。后续评估可让未参与设计的人完成冷读、找规则和预测结果任务，记录具体障碍，再调整页面。检查方案见 [DOC-024](../rules/DOC-024.md)。 + +[手册入口](../README.md) diff --git a/authoring/rules/DOC-001.md b/authoring/rules/DOC-001.md new file mode 100644 index 0000000..b2d659c --- /dev/null +++ b/authoring/rules/DOC-001.md @@ -0,0 +1,37 @@ +# DOC-001 先确定读者与阅读目标 + +分类：读者与定位。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +每次新增或改写页面，先写出目标读者、已知知识和读完后能够完成的事项。 + +## 原因 + +作者熟悉的内容不等于读者已经知道的内容；范围应由知识差距与任务决定。 + +## 执行方法 + +1. 在改动说明中记录读者与知识前提，不把这份内部记录塞入每个正文开头。 +2. 用可检查的目标替换“详细介绍”，例如“能区分归属 key 与引用 key”。 +3. 删去与目标无关的实现历史；必要的背景链接到主定义页。 + +## 改写对照 + +问题写法：本文详细介绍我们之前讨论的东西。 + +推荐做法：本文说明 namespace key 的组成、最小归属和引用关系。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 无需聊天历史即可确定主题。 +- [ ] 页面能对应至少一个具体阅读目标。 +- [ ] 没有默认读者理解团队内部代称。 + +## 依据与边界 + +[SRC-15](../research/SRC-15.md)、[SRC-14](../research/SRC-14.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-002.md b/authoring/rules/DOC-002.md new file mode 100644 index 0000000..f05dad3 --- /dev/null +++ b/authoring/rules/DOC-002.md @@ -0,0 +1,37 @@ +# DOC-002 确定页面的主要职责 + +分类：读者与定位。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +页面先选择教程、操作指南、参考或概念解释中的主要职责，再决定组织方式。 + +## 原因 + +不同读者任务需要不同信息；把学习步骤、精确规则与设计争论混在一起，会破坏查阅路径。 + +## 执行方法 + +1. 教程带读者完成一次受控练习；操作指南解决一个明确任务。 +2. 参考集中给出形式、参数、约束和结果；解释说明概念关系与选择理由。 +3. 一页可以包含少量辅助说明，但次要内容不改变其主线；用互链代替重复。 + +## 改写对照 + +问题写法：函数章节同时记录全部提案争论、部署步骤和关键字表。 + +推荐做法：函数用法留在正文，完整文法与未定设计分别链接附录。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 可用一句话说明该页主要用途。 +- [ ] 标题与正文职责一致。 +- [ ] 无需为了分类创建没有内容的四套目录。 + +## 依据与边界 + +[SRC-14](../research/SRC-14.md)、[SRC-11](../research/SRC-11.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-003.md b/authoring/rules/DOC-003.md new file mode 100644 index 0000000..d76f12f --- /dev/null +++ b/authoring/rules/DOC-003.md @@ -0,0 +1,37 @@ +# DOC-003 入口先建立全局理解 + +分类：读者与定位。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +介绍页先回答是什么、解决什么问题、有哪些核心概念，再提供学习与查询入口。 + +## 原因 + +读者先形成整体模型，之后才有位置安放细节。 + +## 执行方法 + +1. 第一段使用具体用途定义语言，不用特性口号替代定义。 +2. 用少量核心概念展示应用模型；选择一个小例子，不在概览堆全部语法。 +3. 列出顺序阅读、主题查询和作者协作的入口，说明各自服务谁。 + +## 改写对照 + +问题写法：首页以十几条限制和待定事项开头。 + +推荐做法：首页先介绍统一的声明与调用模型，再连接语言正文和作者手册。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 初次读者能复述用途。 +- [ ] 读者知道从哪里继续。 +- [ ] 概览没有变成全部规范的重复摘要。 + +## 依据与边界 + +[SRC-01](../research/SRC-01.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-004.md b/authoring/rules/DOC-004.md new file mode 100644 index 0000000..a8aeefd --- /dev/null +++ b/authoring/rules/DOC-004.md @@ -0,0 +1,37 @@ +# DOC-004 显式交代前置知识与上下文 + +分类：读者与定位。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +示例和任务中的必要前提必须在使用点可见，不能依赖读者猜测。 + +## 原因 + +上下文遗漏会使正确的片段看起来像独立程序，也会把尚未定义的能力伪装成默认规则。 + +## 执行方法 + +1. 标明外部归属、声明或片段类型；若名称来自前文，给出定位链接。 +2. 在跳转读者需要的地方重述最小前提，而不是复制整章。 +3. 未定的入口、官方导入或成员声明使用局部短注；没有实际环境时不承诺可运行。 + +## 改写对照 + +问题写法：直接给出 Product.get(id)，不说明 Product 和 get 的来源。 + +推荐做法：注明 Product 的定义位置，以及 get 是尚未确定的读取提案。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 片段使用位置明确。 +- [ ] 涉及的名称有声明、前提或明确占位说明。 +- [ ] 没有虚构安装命令或运行入口。 + +## 依据与边界 + +[SRC-04](../research/SRC-04.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-005.md b/authoring/rules/DOC-005.md new file mode 100644 index 0000000..13f4b0c --- /dev/null +++ b/authoring/rules/DOC-005.md @@ -0,0 +1,37 @@ +# DOC-005 按概念依赖安排阅读顺序 + +分类：结构与导航。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +章节顺序由理解前提决定，不由实现顺序、聊天顺序或文件创建时间决定。 + +## 原因 + +顺序阅读需要已经介绍的概念支持新概念；反复前后跳转会中断理解。 + +## 执行方法 + +1. 为主题列出必要前置概念，先排依赖再排应用。 +2. Endorphin 主线先讲身份与 namespace，再讲导入、阶段、语法与应用。 +3. 概览可以预览后文，但预览应简短且注明详情入口；正式规则不要依赖未解释术语。 + +## 改写对照 + +问题写法：在身份与导入之前，先要求读者理解跨 namespace 的数据调用。 + +推荐做法：先定义定位与引用，再解释调用和结果依赖。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 正文前后顺序能说明理由。 +- [ ] 重要术语在正式使用前已定义或链接。 +- [ ] 目录调整没有改变语言语义。 + +## 依据与边界 + +[SRC-03](../research/SRC-03.md)、[SRC-09](../research/SRC-09.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-006.md b/authoring/rules/DOC-006.md new file mode 100644 index 0000000..f52d201 --- /dev/null +++ b/authoring/rules/DOC-006.md @@ -0,0 +1,37 @@ +# DOC-006 按读者问题分页 + +分类：结构与导航。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +一页承担一个主要主题或任务；按独立查阅需要拆分，而不是按固定字数或每句话拆分。 + +## 原因 + +好的边界既支持定位，也保留理解当前主题所需的上下文。 + +## 执行方法 + +1. 可以独立命名和查阅的内容单列页面。 +2. 类型声明与取得数据是不同问题；类结构和数据读取分别成章。 +3. 短而紧密依赖的子项保留在同页，避免制造大量空壳或跳转。 + +## 改写对照 + +问题写法：把所有类声明、读取、界面更新和失败方案放在同一章。 + +推荐做法：将结构、读取和渲染分开，并在使用点连接。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 页名说明主题，不叫“更多”或“其他”。 +- [ ] 拆分页仍可独立阅读。 +- [ ] 没有仅因字数达到阈值而拆分。 + +## 依据与边界 + +[SRC-09](../research/SRC-09.md)、[SRC-14](../research/SRC-14.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-007.md b/authoring/rules/DOC-007.md new file mode 100644 index 0000000..2f935e6 --- /dev/null +++ b/authoring/rules/DOC-007.md @@ -0,0 +1,37 @@ +# DOC-007 同时支持顺序阅读与按需查找 + +分类：结构与导航。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +目录、章节导航与主题索引共同提供学习和查询路径。 + +## 原因 + +新读者需要主线，熟悉的读者需要直接定位；单一大目录不能完全替代二者。 + +## 执行方法 + +1. 保持相邻章节导航和正文目录一致。 +2. 为术语、具体语法与作者任务提供索引；用读者会搜索的名称。 +3. 进入一个页面后能看出主题、相关详情和返回位置。 + +## 改写对照 + +问题写法：只提供文件列表，让读者猜先后关系。 + +推荐做法：正文有顺序目录，附录有术语与文法，手册另有问题索引。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 能从目录进入并返回。 +- [ ] 指定术语能定位到主要定义。 +- [ ] 作者资料不会混入语言学习主线。 + +## 依据与边界 + +[SRC-01](../research/SRC-01.md)、[SRC-07](../research/SRC-07.md)、[SRC-08](../research/SRC-08.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-008.md b/authoring/rules/DOC-008.md new file mode 100644 index 0000000..5940494 --- /dev/null +++ b/authoring/rules/DOC-008.md @@ -0,0 +1,37 @@ +# DOC-008 稳定编号与唯一主定义 + +分类：结构与导航。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +规则 ID 固定，概念只有一个主要定义来源；目录位置和显示编号不作为规则身份。 + +## 原因 + +重排页面不应使长期引用失效，重复定义也会造成版本分歧。 + +## 执行方法 + +1. 重要写作规则使用 DOC 编号，来源使用 SRC 编号，模板使用 TPL 编号。 +2. 修改规则内容保留 ID；废弃时保留说明或定向链接，不将旧 ID 分配给其他规则。 +3. 语言文法集中在一个附录，正文只解释相关用法并连接主定义。 + +## 改写对照 + +问题写法：把每章完整复制的文法当作各自独立版本。 + +推荐做法：一份完整 EBNF 为主来源，章节连接对应产生式。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] ID 唯一且不因排序变化而更换。 +- [ ] 定义页可定位。 +- [ ] 相同规则没有多份相互矛盾的权威描述。 + +## 依据与边界 + +[SRC-02](../research/SRC-02.md)、[SRC-09](../research/SRC-09.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-009.md b/authoring/rules/DOC-009.md new file mode 100644 index 0000000..5442313 --- /dev/null +++ b/authoring/rules/DOC-009.md @@ -0,0 +1,37 @@ +# DOC-009 最小示例必须有完整条件 + +分类：示例与教学。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +示例尽量小，但不能靠省略必要条件缩短；明确它是完整声明、局部片段还是提案示意。 + +## 原因 + +读者需要知道代码如何放置，而不是只看到一段外观正确的符号。 + +## 执行方法 + +1. 去掉与本节目标无关的配置，保留必要声明与输入。 +2. 局部名称来自参数或前文时明确说明；不同外部 key 的代码分开标记。 +3. 未定能力使用说明而非补写虚构实现；复制执行的承诺只对经过真实验证的例子作出。 + +## 改写对照 + +问题写法：把 use 与顶层 let 混成一份所谓完整程序。 + +推荐做法：完整函数展示 use 与函数体；查询片段注明 let 位于函数体内。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 所有必要条件可查。 +- [ ] 占位符没有冒充实际 API。 +- [ ] 示例标签与验证等级一致。 + +## 依据与边界 + +[SRC-04](../research/SRC-04.md)、[SRC-08](../research/SRC-08.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-010.md b/authoring/rules/DOC-010.md new file mode 100644 index 0000000..bd157fc --- /dev/null +++ b/authoring/rules/DOC-010.md @@ -0,0 +1,37 @@ +# DOC-010 形成代码、结果与解释的闭环 + +分类：示例与教学。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +关键示例必须给出预期结果或可观察效果，并解释导致该结果的相关规则。 + +## 原因 + +代码展示形式，结果提供核对点，解释使读者能迁移到自己的输入。 + +## 执行方法 + +1. 数值示例写出结果；UI 示例说明内容与排列；失败示例说明诊断或状态。 +2. 解释只针对本例中的关键关系，不逐行重述明显语法。 +3. 标明预期效果与真实运行结果的区别；没有运行环境时不要制造测试输出。 + +## 改写对照 + +问题写法：只贴 payable 的函数体，不解释最终金额。 + +推荐做法：说明两次计算依次得到 90 和 85，第二次依赖第一次的结果。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 读者可预测例子结果。 +- [ ] 结果与源码计算一致。 +- [ ] 效果说明没有被误标为执行日志。 + +## 依据与边界 + +[SRC-01](../research/SRC-01.md)、[SRC-02](../research/SRC-02.md)、[SRC-03](../research/SRC-03.md)、[SRC-04](../research/SRC-04.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-011.md b/authoring/rules/DOC-011.md new file mode 100644 index 0000000..ec5e32c --- /dev/null +++ b/authoring/rules/DOC-011.md @@ -0,0 +1,37 @@ +# DOC-011 每个递进例子只增加少量新概念 + +分类：示例与教学。级别：建议。本规则是项目写作约定，不是语言语义。 + +## 规则 + +递进示例围绕同一对象或任务，明确本次新增的变量。 + +## 原因 + +主题与命名稳定，使读者把注意力放在新增规则而不是重建业务背景。 + +## 执行方法 + +1. 先展示基本形式，再加入一个参数、子节点或调用组合。 +2. 共用商品、价格与优惠的背景；确有必要换场景时交代原因。 +3. 独立参考页仍保留最小上下文，不强迫读者记忆整个教程。 + +## 改写对照 + +问题写法：从数字绑定突然跳到陌生的 Agent 工作流，且同时新增许多语法。 + +推荐做法：先绑定金额，再调用定价函数，最后组合两次调用。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 新示例与前例差异明确。 +- [ ] 新增概念有对应解释。 +- [ ] 一致场景不会强制所有专业例子使用商品。 + +## 依据与边界 + +[SRC-05](../research/SRC-05.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-012.md b/authoring/rules/DOC-012.md new file mode 100644 index 0000000..a5dab14 --- /dev/null +++ b/authoring/rules/DOC-012.md @@ -0,0 +1,37 @@ +# DOC-012 把边界与失败写在相关规则旁 + +分类：示例与教学。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +成功路径之外，说明读者容易触及的限制和失败类别；不要默默忽略错误。 + +## 原因 + +只有成功例子无法表达完整契约，错误位置决定读者应如何修正理解。 + +## 执行方法 + +1. 选择有代表性的数量、类型、根结构或结果状态边界。 +2. 区分 Preflight 可检查错误与 inflight 中才出现的失败。 +3. 未确定的错误处理写法说明边界并链接状态页，不随意创造 catch、await 或错误类型。 + +## 改写对照 + +问题写法：错误参数会被忽略，所以不用提。 + +推荐做法：说明参数数量或类型应被检查；读取缺失与执行失败需要独立表达。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 边界与相应主题相邻。 +- [ ] 没有把所有失败称为语法错误。 +- [ ] 未定处理语法仍保持未定。 + +## 依据与边界 + +[SRC-02](../research/SRC-02.md)、[SRC-05](../research/SRC-05.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-013.md b/authoring/rules/DOC-013.md new file mode 100644 index 0000000..252f999 --- /dev/null +++ b/authoring/rules/DOC-013.md @@ -0,0 +1,37 @@ +# DOC-013 用可观察契约说明语义 + +分类：语义与边界。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +语法说明应明确输入、名称或类型约束、结果、依赖与相关阶段，而不止列关键字。 + +## 原因 + +读者需要理解写法意味着什么，系统实现也需要可核对的行为要求。 + +## 执行方法 + +1. 对函数说明参数、返回类型与结果；对组件说明参数与子节点约束。 +2. 只有阶段差异影响理解时才专门说明 Preflight 与 inflight，避免每段重复阶段定义。 +3. 区分算术结合、调用参数求值顺序和数据依赖；未定义的语义不由示例补出。 + +## 改写对照 + +问题写法：只写 function 后面跟名字与括号。 + +推荐做法：同时说明输入类型、返回值及依赖结果何时可被使用。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 语法、规则和示例结果相互一致。 +- [ ] 有可检查的效果。 +- [ ] 没有用底层机制替代语言契约。 + +## 依据与边界 + +[SRC-02](../research/SRC-02.md)、[SRC-06](../research/SRC-06.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-014.md b/authoring/rules/DOC-014.md new file mode 100644 index 0000000..57ccc15 --- /dev/null +++ b/authoring/rules/DOC-014.md @@ -0,0 +1,37 @@ +# DOC-014 比较方案时给出选择维度 + +分类：语义与边界。级别：条件。本规则是项目写作约定，不是语言语义。 + +## 规则 + +多个概念容易混淆或确有替代方案时，使用同任务、同输入和共同维度进行比较。 + +## 原因 + +比较要帮助理解或决策，而不是展示两段无关联代码。 + +## 执行方法 + +1. 先确定比较的是定位、阶段、结果还是使用情境。 +2. 列出共同点、不同点与适用条件；表格只在映射确实有帮助时使用。 +3. 未定语言方案的比较不等于替用户选择最终设计。 + +## 改写对照 + +问题写法：把 namespace key 与连接地址并列，却不解释职责差异。 + +推荐做法：分别说明归属 key 定位当前代码，use key 定位依赖，两者都不是传输连接。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 比较对象与维度明确。 +- [ ] 读者知道差异是否影响用法。 +- [ ] 没有为了比较而创造不存在的第二套 API。 + +## 依据与边界 + +[SRC-05](../research/SRC-05.md)、[SRC-06](../research/SRC-06.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-015.md b/authoring/rules/DOC-015.md new file mode 100644 index 0000000..d93886d --- /dev/null +++ b/authoring/rules/DOC-015.md @@ -0,0 +1,37 @@ +# DOC-015 区分确定规则、语法提案与未定边界 + +分类：语义与边界。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +状态集中记录，关键假设在使用点短注；编辑文档不能自动确认语言设计。 + +## 原因 + +既不能把草案写成稳定能力，也不能让每段说明淹没在同一免责声明中。 + +## 执行方法 + +1. 全书入口说明设计稿范围，状态附录记录各主题确定程度。 +2. Product.get 和官方导入等影响代码合法性的假设在例子旁说明。 +3. 规则确定后同步主定义、示例、文法与状态；确认需要有明确用户决定。 + +## 改写对照 + +问题写法：为了让例子完整，给所有 class 宣称自动 get。 + +推荐做法：读取形式标为提案，并说明成员声明仍未定义。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 局部假设可见。 +- [ ] 没有新增未经确认的强制规则。 +- [ ] 同一状态声明不在每节重复。 + +## 依据与边界 + +[SRC-02](../research/SRC-02.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-016.md b/authoring/rules/DOC-016.md new file mode 100644 index 0000000..7d3cdfb --- /dev/null +++ b/authoring/rules/DOC-016.md @@ -0,0 +1,37 @@ +# DOC-016 区分语言模型与实现机制 + +分类：语义与边界。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +语言文档描述源码与应有效果，系统实现资料另行组织。 + +## 原因 + +执行机制可以变化，用户需要依赖的是语言意义与可观察行为。 + +## 执行方法 + +1. 说明声明、参数和结果，不要求业务用法配置 HTTP、缓存或监听器。 +2. S3 仅解释代码存储约定，不据此定义业务数据后端。 +3. 比较概念时明确层次，不能把 namespace、应用角色与处理阶段互相替代。 + +## 改写对照 + +问题写法：用传输协议和固定绘制命令解释函数和组件的语言规则。 + +推荐做法：说明函数结果、数据依赖和组件排列效果，不绑定具体编排方案。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 没有出现开发软件代称。 +- [ ] 实现选择没有伪装成语法限制。 +- [ ] 必要的存储说明限定在代码组织范围。 + +## 依据与边界 + +[SRC-06](../research/SRC-06.md)、[SRC-11](../research/SRC-11.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-017.md b/authoring/rules/DOC-017.md new file mode 100644 index 0000000..2f18c85 --- /dev/null +++ b/authoring/rules/DOC-017.md @@ -0,0 +1,37 @@ +# DOC-017 统一术语与展示记法 + +分类：表述与证据。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +同一概念使用同一术语，源码、结果、归属和结构示意使用可区分的记法。 + +## 原因 + +术语漂移与展示混淆会使读者无法判断看到的是代码还是说明。 + +## 执行方法 + +1. Preflight 和 inflight 保持固定大小写；handle 与显示名分别定义。 +2. 外部 key 写在代码块前，代码块只含对应源码；结果使用 text 或效果说明。 +3. 首次正式使用术语时定义或连接术语表，后文保持一致。 + +## 改写对照 + +问题写法：把 key、文件路径、模块地址混称；在源码内写展示提示符。 + +推荐做法：区分 namespace key 与存储对象键，并明确片段与预期结果。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 术语与术语表一致。 +- [ ] 源码展示没有混入非源码标签。 +- [ ] 记法适用于从其他页面跳入的读者。 + +## 依据与边界 + +[SRC-08](../research/SRC-08.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-018.md b/authoring/rules/DOC-018.md new file mode 100644 index 0000000..b8a8a71 --- /dev/null +++ b/authoring/rules/DOC-018.md @@ -0,0 +1,37 @@ +# DOC-018 使用独立成立的文档陈述 + +分类：表述与证据。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +正文陈述概念和规则，不记录作者与用户的对话过程。 + +## 原因 + +读者不应该依靠之前的讨论理解今天的用法。 + +## 执行方法 + +1. 把“你之前说”“先这样”“以后再看”等过程叙述移出语言正文。 +2. 用对象、动作、条件和结果构成明确句子；保留教程所需的直接操作指令。 +3. 待定项目使用集中状态，不让“不能”“不是”成为每段唯一内容。 + +## 改写对照 + +问题写法：我们上次说过，这里先这样写，以后再讨论。 + +推荐做法：该声明定义字段结构；读取成员的声明形式列于规范状态。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 移除聊天历史后仍可理解。 +- [ ] 代词指向明确。 +- [ ] 使用第二人称教学指令本身不被误判为问题。 + +## 依据与边界 + +[SRC-11](../research/SRC-11.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-019.md b/authoring/rules/DOC-019.md new file mode 100644 index 0000000..a4a0b91 --- /dev/null +++ b/authoring/rules/DOC-019.md @@ -0,0 +1,37 @@ +# DOC-019 让格式服务理解与查找 + +分类：表述与证据。级别：建议。本规则是项目写作约定，不是语言语义。 + +## 规则 + +按信息关系选择文字、代码、表格或图，避免机械地给每段增加图表。 + +## 原因 + +格式应减少理解成本，而不是证明页面很完整。 + +## 执行方法 + +1. 签名、参数和重复映射适合表格；依赖和树形关系适合小图。 +2. 短定义用段落，步骤用有序列表，源码用标注语言的代码块。 +3. 标题表达实际主题；表格不能代替关键的原因或边界说明。 + +## 改写对照 + +问题写法：单个字段解释也配一张复杂流程图。 + +推荐做法：渲染树用小型结构示意，组件参数用表格，其余直接说明。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 格式与关系类型匹配。 +- [ ] 源码可复制，结构示意不冒充源码。 +- [ ] Markdown 标题、列表与代码块正确闭合。 + +## 依据与边界 + +[SRC-03](../research/SRC-03.md)、[SRC-06](../research/SRC-06.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-020.md b/authoring/rules/DOC-020.md new file mode 100644 index 0000000..a4a5f82 --- /dev/null +++ b/authoring/rules/DOC-020.md @@ -0,0 +1,37 @@ +# DOC-020 证据、分析与项目规则分层 + +分类：表述与证据。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +外部来源的具体观察、作者的效果分析和本项目决定分别标记，引用靠近对应判断。 + +## 原因 + +来源可以启发做法，但不能替代语法授权或验证结果。 + +## 执行方法 + +1. 记录原始 URL、核查日期、页面位置与访问状态。 +2. 判断“为什么好”时说明是结构分析；没有用户研究时不提供虚构指标。 +3. 不可读来源保留编号，不编造标题、作者与观点；转述不整页复制。 + +## 改写对照 + +问题写法：没有读到知乎正文，却把建议归给该回答。 + +推荐做法：记录访问未成功，不将该来源用于规则推导。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 每个外部观察可定位到原页。 +- [ ] 推断明确标记。 +- [ ] 无把搜索摘要冒充完整阅读的情况。 + +## 依据与边界 + +本项目的来源核查流程；未读材料的处理记录见 [SRC-10](../research/SRC-10.md)、[SRC-12](../research/SRC-12.md)、[SRC-13](../research/SRC-13.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-021.md b/authoring/rules/DOC-021.md new file mode 100644 index 0000000..58abc94 --- /dev/null +++ b/authoring/rules/DOC-021.md @@ -0,0 +1,37 @@ +# DOC-021 每次改动完成影响检查 + +分类：协作与质量。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +文档修改同时检查关联定义、示例、导航与状态，不以改完当前文件作为结束。 + +## 原因 + +局部正确不代表整套文档一致，尤其是同一写法在多个位置出现时。 + +## 执行方法 + +1. 修改前找出主定义和引用位置，编辑后复查影响范围。 +2. 运行链接、锚点、代码块、编号和格式检查；按风险检查例子与计算。 +3. 报告实际检查等级、未执行步骤与失败；工具通过不等于语言运行验证。 + +## 改写对照 + +问题写法：修改 use 示例后只检查当前段落。 + +推荐做法：同步正文、文法、索引和所有相关示例，并记录验证范围。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 相关引用无过时版本。 +- [ ] 命令和结果可复现。 +- [ ] 报告没有把静态检查称为编译或运行测试。 + +## 依据与边界 + +[SRC-07](../research/SRC-07.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-022.md b/authoring/rules/DOC-022.md new file mode 100644 index 0000000..f3e1a04 --- /dev/null +++ b/authoring/rules/DOC-022.md @@ -0,0 +1,37 @@ +# DOC-022 把文档作为可迁移的仓库资产 + +分类：协作与质量。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +正文、作者规则、模板和验证工具一起版本管理，个人环境与凭据不进入仓库。 + +## 原因 + +协作应依赖明确文件与流程，而不是单台电脑的聊天记忆或编辑器状态。 + +## 执行方法 + +1. 使用仓库相对路径和低依赖检查命令；远端修改前检查分支与工作区。 +2. 本地编辑器状态和凭据不上传；不强推覆盖其他贡献。 +3. Gitea 仅使用 codex-bot，身份与仓库 owner 分开，专用密钥在本机配置。 + +## 改写对照 + +问题写法：把个人配置与密钥一并打包，让其他电脑照搬。 + +推荐做法：共享 AGENTS、手册和验证脚本，各机器独立配置授权身份。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 他人能从 README 找到贡献流程。 +- [ ] 工具无本机绝对路径。 +- [ ] 提交和推送状态有记录，权限不足不换用 owner 凭据。 + +## 依据与边界 + +[SRC-11](../research/SRC-11.md)、[SRC-07](../research/SRC-07.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-023.md b/authoring/rules/DOC-023.md new file mode 100644 index 0000000..32ced61 --- /dev/null +++ b/authoring/rules/DOC-023.md @@ -0,0 +1,37 @@ +# DOC-023 为人工与 AI 作者规定相同交付标准 + +分类：协作与质量。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +每个作者都先读取项目约定与适用规则，再编辑、检查并报告；AI 不拥有额外语义决定权。 + +## 原因 + +共享上下文与审查标准可以减少跨电脑、跨会话的文档漂移。 + +## 执行方法 + +1. 先读 AGENTS、手册入口、任务适用规则和目标章节的主定义。 +2. 记录本次采用的规则 ID、语言假设和改动范围。 +3. 不擅自确认语法、不补造 API、不扩展为实现或凭据操作；审查变更与验证结果。 + +## 改写对照 + +问题写法：AI 为了例子顺畅，自行添加 await、云端实体和官方账号。 + +推荐做法：保留未定边界，只实现已授权的文档调整并标明假设。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 其他会话不依赖原聊天仍能接续。 +- [ ] 改动说明含适用规则与验证。 +- [ ] 作者身份不影响语义确认要求。 + +## 依据与边界 + +[SRC-07](../research/SRC-07.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/rules/DOC-024.md b/authoring/rules/DOC-024.md new file mode 100644 index 0000000..86a3385 --- /dev/null +++ b/authoring/rules/DOC-024.md @@ -0,0 +1,37 @@ +# DOC-024 用读者任务验收文档 + +分类：协作与质量。级别：核心。本规则是项目写作约定，不是语言语义。 + +## 规则 + +除结构检查外，按冷读、定位和结果预测任务检查文档。 + +## 原因 + +文件无格式错误不表示读者已经能够理解或使用它。 + +## 执行方法 + +1. 冷读：不查看聊天，复述用途、概念关系和一个核心例子。 +2. 定位：只从目录或术语索引寻找指定规则；记录卡住的地方。 +3. 预测：根据例子解释结果、合法边界与提案状态；将人工评审与真实用户测试分别记录。 + +## 改写对照 + +问题写法：139 个链接通过，所以文档一定易懂。 + +推荐做法：链接检查通过后，再检查读者能否区分归属与引用并预测 90 和 85。 + +以上是说明写作差异的项目例子，不新增语言能力。 + +## 验收 + +- [ ] 验收任务与页面目标对应。 +- [ ] 发现的理解障碍有具体位置。 +- [ ] 没有把作者自查冒充真实用户测试。 + +## 依据与边界 + +[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 + +[规则索引](../README.md#规则索引) · [检查清单](../checklist.md) diff --git a/authoring/templates/README.md b/authoring/templates/README.md new file mode 100644 index 0000000..b75d81e --- /dev/null +++ b/authoring/templates/README.md @@ -0,0 +1,16 @@ +# 页面模板 + +模板用于确定信息职责，不要求机械填满所有栏目。删去不适用的栏目，并保留真正影响合法性与理解的条件。 + +| 编号 | 模板 | 适用目的 | +| --- | --- | --- | +| TPL-01 | [概念指南](TPL-01.md) | 逐步建立一个概念及其基本用法 | +| TPL-02 | [任务指南](TPL-02.md) | 已有前提下完成一个明确操作 | +| TPL-03 | [语法或 API 参考](TPL-03.md) | 查询形式、参数、约束和效果 | +| TPL-04 | [概念解释与比较](TPL-04.md) | 理解关系、设计理由或替代方案 | + +模板借鉴 [Diátaxis 的职责区分](../research/SRC-14.md)，是本项目的页面组织建议。概念指南可以结合少量讲解与示例；尚无执行环境时不将它包装成可运行教程。 + +模板代码块里的文字是写作占位，不是文件名、真实链接或 Endorphin 源码。实际正文必须替换占位内容，并通过[检查清单](../checklist.md)。 + +[手册入口](../README.md) diff --git a/authoring/templates/TPL-01.md b/authoring/templates/TPL-01.md new file mode 100644 index 0000000..77cae50 --- /dev/null +++ b/authoring/templates/TPL-01.md @@ -0,0 +1,43 @@ +# TPL-01 概念指南 + +用途：读者首次理解某个概念，知道它的基本形式和行为。适用规则：DOC-001、003、004、005、010、013、015、018。 + +## 内容顺序 + +````markdown +# 主题名称 + +定义：对象是什么，在应用中承担什么职责。 + +## 前置知识 + +只列理解本页必需的概念与实际链接。已经由全书说明的前提不重复堆叠。 + +## 基本形式 + +展示最小形式，并解释组成部分。 + +## 示例 + +标明代码归属与使用位置；给出声明或片段。 +展示预期结果或效果，说明导致结果的关键规则。 + +## 使用约束 + +说明相关类型、结构与依赖；阶段差异影响理解时再说明阶段。 +未定能力在使用点短注，并链接实际的规范状态区域。 + +## 延伸 + +连接下一步和精确参考，不复制相关章节。 +```` + +## 删除不适用栏目 + +若页面只介绍身份或 namespace，不强行提供函数代码或计算结果。使用 key 对照与定位示例即可。前置知识简单时可融入首段。 + +## 完成条件 + +读者可以复述概念职责、识别基本形式并解释一个例子。主要定义没有被复制为多份权威版本。 + +[模板目录](README.md) diff --git a/authoring/templates/TPL-02.md b/authoring/templates/TPL-02.md new file mode 100644 index 0000000..54e03c9 --- /dev/null +++ b/authoring/templates/TPL-02.md @@ -0,0 +1,47 @@ +# TPL-02 任务指南 + +用途：有明确前提的读者完成一项操作。适用规则：DOC-001、002、004、009、010、012、021。 + +## 内容顺序 + +````markdown +# 完成某项任务 + +说明起点、目标结果和适用场景。 + +## 前提 + +列出已具备的声明、权限、输入与使用环境。 +若入口尚未定义，说明本页是逻辑用法而非可运行操作教程。 + +## 步骤 + +1. 准备必要输入。 +2. 编写当前步骤的声明或调用。 +3. 使用结果完成目标。 + +每一步仅提供需要的解释和可观察核对点。 + +## 验证结果 + +说明成功值或效果，以及验证所用环境和等级。 + +## 常见边界 + +按原因、可观察情况和可用处理方式组织。 +未定的错误处理语法明确链接状态，不给虚构补救代码。 + +## 相关任务 + +连接必要参考和邻近任务。 +```` + +## 执行真实性 + +没有定义的安装、入口、官方引用或读取成员不能为“完整教程”补造。只有真实验证过的操作才使用“执行后输出”等表述；提案使用“预期结果”。 + +## 完成条件 + +目标结果可核对，步骤前提明确；读者不需猜测中间缺失的信息。 + +[模板目录](README.md) diff --git a/authoring/templates/TPL-03.md b/authoring/templates/TPL-03.md new file mode 100644 index 0000000..a971790 --- /dev/null +++ b/authoring/templates/TPL-03.md @@ -0,0 +1,49 @@ +# TPL-03 语法或 API 参考 + +用途：直接查询精确写法、输入和行为。适用规则：DOC-004、008、012、013、015、017、019。 + +## 内容顺序 + +````markdown +# 声明、表达式或组件名称 + +一段定义与用途，连接必要概念，不重讲整个教程。 + +## 形式 + +给出签名或语法结构。 +完整 EBNF 已有主来源时连接其区域，不建立另一套版本。 + +## 参数与类型 + +按名称、位置、类型、默认值和含义组织。 +没有默认值时明确说明；未确定的默认值保持提案状态。 + +## 结果与效果 + +说明返回值、结构、依赖及影响行为的阶段要求。 + +## 约束与失败 + +写出数量、类型、结构或结果状态边界。 +区分静态诊断与执行失败。 + +## 示例 + +最小有效例子、预期结果和必要前提。 +不将占位符或假设成员写成实际可用 API。 + +## 相关定义 + +连接主定义、提案状态和必要主题。 +```` + +## 一致性 + +同类参考页使用相近字段，但没有意义的字段不凑齐。组件的“子节点约束”比没有函数返回值时强填“返回”更合适。 + +## 完成条件 + +跳入该页的读者能查到形式、合法输入及效果，所有假设可见。 + +[模板目录](README.md) diff --git a/authoring/templates/TPL-04.md b/authoring/templates/TPL-04.md new file mode 100644 index 0000000..fa9a549 --- /dev/null +++ b/authoring/templates/TPL-04.md @@ -0,0 +1,44 @@ +# TPL-04 概念解释与比较 + +用途：解释概念关系、区别或选择理由。适用规则：DOC-002、005、014、016、018、019、020。 + +## 内容顺序 + +````markdown +# 概念关系或比较主题 + +明确本页要解释的区别及其使用情境。 + +## 共同背景 + +定义比较对象，连接各自主要说明页。 + +## 区别 + +用相同任务或输入进行比较。 +按职责、结果、约束等共同维度说明。 +信息确有重复映射时使用小表或图。 + +## 使用判断 + +说明哪些情境应关注哪个区别。 +若比较的是未定提案，列出需要决定的语义，不替用户确认。 + +## 边界 + +区分语言模型与实现机制；说明本页没有决定什么。 + +## 相关用法 + +连接参考或任务指南，不重复完整步骤。 +```` + +## 证据要求 + +讨论外部做法时保留可核对来源，将页面观察与自己的分析区分。没有效果数据时，不声称某种形式必然提高多少效率。 + +## 完成条件 + +读者知道比较对象、共同维度和区别的实际影响。没有为填充比较表创造第二套语法。 + +[模板目录](README.md) diff --git a/authoring/workflow.md b/authoring/workflow.md new file mode 100644 index 0000000..a4db5e5 --- /dev/null +++ b/authoring/workflow.md @@ -0,0 +1,62 @@ +# 文档修改工作流 + +本流程适用于人工与 AI 作者。目标是把写作约定落实到每次修改，并避免无关文件或未经确认的语言决定进入提交。 + +## 1. 开始前 + +读取仓库 [AGENTS.md](../AGENTS.md)、[手册入口](README.md)和目标主题的主要定义。检查当前分支、远端与工作区；已有未提交修改属于原作者，未经授权不清除或覆盖。 + +记录： + +- 目标读者与本次阅读目标。 +- 页面主要职责与本次改动范围。 +- 适用的 DOC 规则 ID。 +- 已确定语义、局部假设和未定设计。 +- 预计需要同步的定义、示例、导航与状态。 + +## 2. 选择相关规则 + +| 改动 | 最少阅读的相关规则 | +| --- | --- | +| 错字、链接或术语 | DOC-017、021 | +| 新增用法与示例 | DOC-004、009、010、012、013、015、021 | +| 新增或拆分章节 | DOC-001、002、005、006、007、008、021、024 | +| 外部资料研究 | DOC-020；再根据结论选相关规则 | +| AI 或跨电脑接续 | DOC-022、023；再选任务适用规则 | + +这是起点，不替代按风险判断。引用规则页见[规则索引](README.md#规则索引)。 + +## 3. 编辑 + +先修改主要定义，再同步依赖内容。使用适用的[模板](templates/README.md)，但不要填满与主题无关的栏目。 + +语法提案保持提案身份。涉及新的语言决定时，说明所需决定而不擅自补造语法。研究与作者规则放在 authoring，不混入读者语言主线。 + +## 4. 验证 + +在仓库根目录执行： + +```sh +python3 tools/check_docs.py +python3 -m unittest discover -s tools/tests -v +git diff --check +``` + +另行核对示例计算、归属与引用、文法及局部假设，并执行[读者任务检查](rules/DOC-024.md)。检查清单见 [checklist.md](checklist.md)。 + +工具只验证结构及有限约定，不证明语言可编译、程序正确或文档易懂。新工具的检查能力以 [tools/README.md](../tools/README.md) 为准。 + +## 5. 交付与提交 + +报告改动文件、目的、规则 ID、验证范围和未完成项目。用户要求提交或推送时： + +1. 检查暂存文件，排除无关编辑、个人配置与凭据。 +2. 使用仓库约定的作者与认证身份。 +3. 提交后核对提交文件与标识；推送后核对远端分支。 +4. 如被拒绝，保留本地提交并报告原因，不强推或改用其他账户。 + +## 6. 接续工作 + +另一作者从仓库文件和 Git 状态开始，不依赖聊天记忆。维护手册时保留 DOC、SRC 和 TPL 编号；新增来源先登记访问状态。 + +[手册入口](README.md) · [贡献流程](../CONTRIBUTING.md) diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 0000000..2f5e273 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,39 @@ +# 文档检查工具 + +## 环境与命令 + +Python 3.10 或更新版本，无第三方依赖。在仓库根目录执行： + +```sh +python3 tools/check_docs.py +python3 -m unittest discover -s tools/tests -v +git diff --check +``` + +脚本默认以自身位置定位仓库，不依赖当前目录或本机绝对路径。可使用 `--root` 指定另一个本地检出；检查仅读取文件，不访问网络、不修改仓库。 + +## 检查范围 + +- 非隐藏目录中的 UTF-8 Markdown 文件。 +- 普通行内相对链接的目标和 Markdown 标题锚点。 +- 反引号或波浪号围栏的闭合，包括四重围栏模板。 +- DOC、SRC 文件编号与首标题的对应。 +- guide 中的正文代码不声明自身 namespace，use 具有完整 key 的基本形状。 +- 正文章节连续编号、README 收录与相邻导航。 +- 本机绝对链接和越出仓库的相对链接。 + +模板围栏中的占位链接不作为实际链接验证。标题锚点采用常见的 Markdown slug 规则，重复标题使用数字后缀；其他渲染器的锚点行为仍需检查实际显示。 + +## 不检查的内容 + +不抓取外部链接，不校验完整 Markdown 标准、引用式链接、HTML 链接或所有渲染器的扩展语法。不解析完整 Endorphin 文法、不执行类型检查或程序，也不检验自然语言正确性和真实可用性。 + +use 检查只判断基本结构，不制定用户名字符规范。词法与源码语义仍需按正文和文法人工核对。 + +## 退出状态 + +退出码 0 表示当前结构检查没有发现问题；非 0 表示需要处理报告。通过检查不等于语言已实现或示例已经运行。 + +`tools/tests/test_check_docs.py` 使用临时隔离目录测试工具，覆盖有效与无效链接、围栏、编号、导入和章节顺序；不修改真实文档。 + +[修改工作流](../authoring/workflow.md) · [检查清单](../authoring/checklist.md) · [目录](../README.md) diff --git a/tools/check_docs.py b/tools/check_docs.py new file mode 100644 index 0000000..76ba4cd --- /dev/null +++ b/tools/check_docs.py @@ -0,0 +1,164 @@ +#!/usr/bin/env python3 +"""Read-only structural checks for the documentation repository (Python 3.10+).""" +from __future__ import annotations + +import argparse +from collections import Counter +from dataclasses import dataclass, field +from pathlib import Path, PureWindowsPath +import re +from urllib.parse import unquote, urlsplit + + +@dataclass +class Report: + files: int = 0 + links: int = 0 + blocks: int = 0 + errors: list[str] = field(default_factory=list) + + +def heading_slug(title: str) -> str: + title = re.sub(r"<[^>]+>", "", title).strip().lower() + title = re.sub(r"[^\w\s-]", "", title) + return re.sub(r"\s", "-", title) + + +def extract(body: str, label: str, report: Report): + """Return non-fenced lines and (language, start line, content) code blocks.""" + visible = [] + blocks = [] + marker = None + language = "" + start = 0 + content = [] + for number, line in enumerate(body.splitlines(), 1): + match = re.match(r"^ {0,3}(`{3,}|~{3,})(.*)$", line) + if marker is None: + if match: + marker = match[1] + language = match[2].strip().split(maxsplit=1)[0] if match[2].strip() else "" + start = number + content = [] + else: + visible.append((number, line)) + elif match and match[1][0] == marker[0] and len(match[1]) >= len(marker) and not match[2].strip(): + blocks.append((language, start, "\n".join(content))) + marker = None + else: + content.append(line) + if marker is not None: + report.errors.append(f"{label}:{start}: unclosed code fence") + report.blocks += len(blocks) + return visible, blocks + + +def heading_ids(lines): + counts = Counter() + result = set() + for _, line in lines: + match = re.match(r"^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$", line) + if not match: + continue + base = heading_slug(match[1]) + count = counts[base] + counts[base] += 1 + result.add(base if count == 0 else f"{base}-{count}") + return result + + +def check_repository(root: Path) -> Report: + root = root.resolve() + report = Report() + if not (root / "README.md").is_file(): + report.errors.append("README.md: missing repository entry") + pages = sorted(p for p in root.rglob("*.md") if not any(part.startswith(".") for part in p.relative_to(root).parts)) + parsed = {} + for page in pages: + label = page.relative_to(root).as_posix() + try: + body = page.read_text(encoding="utf-8") + except (OSError, UnicodeError) as error: + report.errors.append(f"{label}: cannot read UTF-8 text: {error}") + continue + report.files += 1 + parsed[page] = extract(body, label, report) + if page.parent == root / "authoring" / "rules" or page.parent == root / "authoring" / "research": + id_match = re.fullmatch(r"(DOC-\d{3}|SRC-\d{2})\.md", page.name) + if id_match and not body.startswith(f"# {id_match[1]} "): + report.errors.append(f"{label}: filename and first heading ID differ") + + anchors = {page: heading_ids(value[0]) for page, value in parsed.items()} + link_pattern = re.compile(r"!?\[[^\]\n]*\]\(([^)\n]+)\)") + for page, (lines, blocks) in parsed.items(): + label = page.relative_to(root).as_posix() + for number, line in lines: + line = re.sub(r"`+[^`]*`+", "", line) + for match in link_pattern.finditer(line): + target = match[1].strip() + # Simple inline Markdown links; optional quoted link titles are allowed. + target = re.sub(r'\s+["\x27].*["\x27]$', "", target).strip("<>") + if target.startswith("//"): + continue # Protocol-relative web URL, not a local filesystem link. + if PureWindowsPath(unquote(target)).drive or target.lower().startswith("file:"): + report.errors.append(f"{label}:{number}: machine-specific absolute link: {target}") + continue + parts = urlsplit(target) + if parts.scheme or parts.netloc: + continue + report.links += 1 + path = unquote(parts.path) + fragment = unquote(parts.fragment) + if path.startswith("/") or PureWindowsPath(path).drive: + report.errors.append(f"{label}:{number}: machine-specific absolute link: {target}") + continue + destination = (page.parent / path).resolve() if path else page + if not destination.is_relative_to(root): + report.errors.append(f"{label}:{number}: link escapes repository: {target}") + elif not destination.is_file(): + report.errors.append(f"{label}:{number}: missing link target: {target}") + elif fragment and destination.suffix == ".md" and fragment not in anchors.get(destination, set()): + report.errors.append(f"{label}:{number}: missing heading anchor: {target}") + + if page.parent == root / "guide": + for language, number, code in blocks: + if language != "endorphin": + continue + if re.search(r"^\s*namespace\b", code, re.M): + report.errors.append(f"{label}:{number}: source declares its own namespace") + for offset, line in enumerate(code.splitlines(), 1): + if re.match(r"^\s*use\b", line) and not re.fullmatch( + r"\s*use\s+[^\s:{}]+:[^\s:.{}]+(?:\.[^\s:.{}]+)*\s*", line + ): + report.errors.append(f"{label}:{number + offset}: use must reference one complete namespace key") + + chapters = sorted((root / "guide").glob("[0-9][0-9]-*.md")) + numbers = [int(page.name[:2]) for page in chapters] + if numbers and numbers != list(range(1, len(chapters) + 1)): + report.errors.append("guide/: chapter numbering must be unique and contiguous from 01") + entry = "\n".join(line for _, line in parsed.get(root / "README.md", ([], []))[0]) + for index, page in enumerate(chapters): + body = "\n".join(line for _, line in parsed.get(page, ([], []))[0]) + if f"(guide/{page.name})" not in entry: + report.errors.append(f"{page.name}: missing chapter in README") + for adjacent in chapters[max(0, index - 1):index] + chapters[index + 1:index + 2]: + if f"({adjacent.name})" not in body: + report.errors.append(f"{page.name}: missing navigation to {adjacent.name}") + return report + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[1]) + args = parser.parse_args() + report = check_repository(args.root) + print(f"Checked {report.files} Markdown files, {report.links} local links, {report.blocks} fenced blocks.") + for error in report.errors: + print(f"ERROR: {error}") + if not report.errors: + print("PASS: structural checks only; no language compilation, execution, or usability testing.") + return int(bool(report.errors)) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/tests/test_check_docs.py b/tools/tests/test_check_docs.py new file mode 100644 index 0000000..1fe72a8 --- /dev/null +++ b/tools/tests/test_check_docs.py @@ -0,0 +1,119 @@ +"""Tests use isolated temporary fixtures and require only Python's standard library.""" +from pathlib import Path +import sys +import tempfile +import unittest + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +from check_docs import check_repository, heading_slug + + +class DocumentationChecks(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.addCleanup(self.directory.cleanup) + self.root = Path(self.directory.name) + self.write("README.md", "# Entry\n") + + def write(self, name, content): + path = self.root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8") + + def errors(self): + return check_repository(self.root).errors + + def test_valid_local_link_and_unicode_anchor(self): + self.write("README.md", "# Entry\n[Topic](topic.md#用户身份)\n") + self.write("topic.md", "# 用户身份\n") + self.assertEqual(self.errors(), []) + + def test_missing_file_is_reported(self): + self.write("README.md", "# Entry\n[Missing](absent.md)\n") + self.assertTrue(any("missing link target" in item for item in self.errors())) + + def test_missing_anchor_is_reported(self): + self.write("README.md", "# Entry\n[Missing](topic.md#absent)\n") + self.write("topic.md", "# Topic\n") + self.assertTrue(any("missing heading anchor" in item for item in self.errors())) + + def test_template_links_inside_fences_are_ignored(self): + self.write("README.md", "# Entry\n````markdown\n[Placeholder](none.md)\n```text\nexample\n```\n````\n") + self.assertEqual(self.errors(), []) + + def test_unclosed_fence_is_reported(self): + self.write("README.md", "# Entry\n```text\nexample\n") + self.assertTrue(any("unclosed code fence" in item for item in self.errors())) + + def test_duplicate_heading_anchor_suffix(self): + self.write("README.md", "# Entry\n[Second](topic.md#topic-1)\n") + self.write("topic.md", "# Topic\n## Topic\n") + self.assertEqual(self.errors(), []) + + def test_external_link_is_not_fetched(self): + self.write("README.md", "# Entry\n[External](https://example.invalid/path#missing)\n") + self.assertEqual(self.errors(), []) + self.assertEqual(check_repository(self.root).links, 0) + + def test_machine_specific_link_is_rejected(self): + self.write("README.md", "# Entry\n[Local](/absolute/local.md)\n") + self.assertTrue(any("absolute link" in item for item in self.errors())) + + def test_escape_from_repository_is_rejected(self): + self.write("README.md", "# Entry\n[Outside](../outside.md)\n") + self.assertTrue(any("escapes repository" in item for item in self.errors())) + + def test_windows_absolute_link_is_rejected(self): + self.write("README.md", "# Entry\n[Local](C:/workspace/local.md)\n") + self.assertTrue(any("absolute link" in item for item in self.errors())) + + def test_protocol_relative_web_link_is_not_fetched(self): + self.write("README.md", "# Entry\n[External](//example.invalid/path)\n") + self.assertEqual(self.errors(), []) + + def test_file_uri_is_rejected(self): + self.write("README.md", "# Entry\n[Local](file:///workspace/local.md)\n") + self.assertTrue(any("absolute link" in item for item in self.errors())) + + def test_invalid_utf8_is_reported_without_crashing(self): + (self.root / "README.md").write_bytes(b"\xff") + self.assertTrue(any("cannot read UTF-8" in item for item in self.errors())) + + def test_rule_id_mismatch_is_reported(self): + self.write("authoring/rules/DOC-001.md", "# DOC-002 Wrong identity\n") + self.assertTrue(any("heading ID differ" in item for item in self.errors())) + + def test_source_id_mismatch_is_reported(self): + self.write("authoring/research/SRC-01.md", "# SRC-02 Wrong identity\n") + self.assertTrue(any("heading ID differ" in item for item in self.errors())) + + def guide_fixture(self, code): + self.write("README.md", "# Entry\n[Guide](guide/01-example.md)\n") + self.write("guide/01-example.md", "# Guide\n```endorphin\n" + code + "\n```\n") + + def test_valid_use(self): + self.guide_fixture("use alice:shop.pricing") + self.assertEqual(self.errors(), []) + + def test_use_without_user_separator_is_rejected(self): + self.guide_fixture("use alice.shop.pricing") + self.assertTrue(any("complete namespace key" in item for item in self.errors())) + + def test_selective_import_is_rejected(self): + self.guide_fixture("use alice:shop.ui::{Column}") + self.assertTrue(any("complete namespace key" in item for item in self.errors())) + + def test_source_namespace_declaration_is_rejected(self): + self.guide_fixture("namespace alice:shop") + self.assertTrue(any("own namespace" in item for item in self.errors())) + + def test_gapped_chapter_sequence_is_rejected(self): + self.write("guide/02-example.md", "# Guide\n") + self.assertTrue(any("chapter numbering" in item for item in self.errors())) + + def test_heading_punctuation_is_removed(self): + self.assertEqual(heading_slug("4.4 名称引用"), "44-名称引用") + + +if __name__ == "__main__": + unittest.main()