From 10d14612dc744480f5d34dae92c9b1b9caee0ffb Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Thu, 8 Oct 2026 00:38:17 +0800 Subject: [PATCH] docs: develop task-guided Endor authoring skill and detailed handbook --- .agents/skills/endor-docs | 1 + AGENTS.md | 7 +- CONTRIBUTING.md | 12 ++-- README.md | 2 +- authoring/CHANGELOG.md | 10 +++ authoring/README.md | 44 ++++++++++-- authoring/SKILL.md | 57 +++++++++++++++ authoring/agents/openai.yaml | 4 ++ authoring/checklist.md | 15 +++- authoring/evaluation/results-2026-10-08.md | 33 +++++++++ authoring/evaluation/scenarios.md | 34 +++++++++ authoring/examples/EX-01.md | 50 ++++++++++++++ authoring/examples/EX-02.md | 56 +++++++++++++++ authoring/examples/EX-03.md | 69 +++++++++++++++++++ authoring/examples/EX-04.md | 36 ++++++++++ authoring/examples/EX-05.md | 42 +++++++++++ authoring/examples/README.md | 16 +++++ authoring/references/chinese-style.md | 42 +++++++++++ authoring/references/example-design.md | 48 +++++++++++++ .../references/information-architecture.md | 51 ++++++++++++++ authoring/references/language-map.md | 50 ++++++++++++++ authoring/references/review-rubric.md | 48 +++++++++++++ authoring/references/semantic-contracts.md | 50 ++++++++++++++ authoring/rules/DOC-001.md | 6 ++ authoring/rules/DOC-002.md | 6 ++ authoring/rules/DOC-003.md | 6 ++ authoring/rules/DOC-004.md | 6 ++ authoring/rules/DOC-005.md | 6 ++ authoring/rules/DOC-006.md | 6 ++ authoring/rules/DOC-007.md | 6 ++ authoring/rules/DOC-008.md | 6 ++ authoring/rules/DOC-009.md | 6 ++ authoring/rules/DOC-010.md | 6 ++ authoring/rules/DOC-011.md | 6 ++ authoring/rules/DOC-012.md | 6 ++ authoring/rules/DOC-013.md | 6 ++ authoring/rules/DOC-014.md | 6 ++ authoring/rules/DOC-015.md | 6 ++ authoring/rules/DOC-016.md | 6 ++ authoring/rules/DOC-017.md | 6 ++ authoring/rules/DOC-018.md | 6 ++ authoring/rules/DOC-019.md | 6 ++ authoring/rules/DOC-020.md | 6 ++ authoring/rules/DOC-021.md | 8 ++- authoring/rules/DOC-022.md | 6 ++ authoring/rules/DOC-023.md | 6 ++ authoring/rules/DOC-024.md | 6 ++ authoring/skill-usage.md | 39 +++++++++++ authoring/tasks/TASK-01.md | 31 +++++++++ authoring/tasks/TASK-02.md | 45 ++++++++++++ authoring/tasks/TASK-03.md | 43 ++++++++++++ authoring/tasks/TASK-04.md | 37 ++++++++++ authoring/tasks/TASK-05.md | 38 ++++++++++ authoring/tasks/TASK-06.md | 38 ++++++++++ authoring/tasks/TASK-07.md | 34 +++++++++ authoring/tasks/TASK-08.md | 37 ++++++++++ authoring/templates/README.md | 2 + authoring/templates/TPL-05.md | 37 ++++++++++ authoring/templates/TPL-06.md | 31 +++++++++ authoring/workflow.md | 22 +++--- tools/README.md | 2 + 61 files changed, 1332 insertions(+), 27 deletions(-) create mode 120000 .agents/skills/endor-docs create mode 100644 authoring/SKILL.md create mode 100644 authoring/agents/openai.yaml create mode 100644 authoring/evaluation/results-2026-10-08.md create mode 100644 authoring/evaluation/scenarios.md create mode 100644 authoring/examples/EX-01.md create mode 100644 authoring/examples/EX-02.md create mode 100644 authoring/examples/EX-03.md create mode 100644 authoring/examples/EX-04.md create mode 100644 authoring/examples/EX-05.md create mode 100644 authoring/examples/README.md create mode 100644 authoring/references/chinese-style.md create mode 100644 authoring/references/example-design.md create mode 100644 authoring/references/information-architecture.md create mode 100644 authoring/references/language-map.md create mode 100644 authoring/references/review-rubric.md create mode 100644 authoring/references/semantic-contracts.md create mode 100644 authoring/skill-usage.md create mode 100644 authoring/tasks/TASK-01.md create mode 100644 authoring/tasks/TASK-02.md create mode 100644 authoring/tasks/TASK-03.md create mode 100644 authoring/tasks/TASK-04.md create mode 100644 authoring/tasks/TASK-05.md create mode 100644 authoring/tasks/TASK-06.md create mode 100644 authoring/tasks/TASK-07.md create mode 100644 authoring/tasks/TASK-08.md create mode 100644 authoring/templates/TPL-05.md create mode 100644 authoring/templates/TPL-06.md diff --git a/.agents/skills/endor-docs b/.agents/skills/endor-docs new file mode 120000 index 0000000..3e8ddba --- /dev/null +++ b/.agents/skills/endor-docs @@ -0,0 +1 @@ +../../authoring \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 65bd663..a52f680 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,11 +4,14 @@ ## 每次修改的必读入口 -- 修改前阅读 [文档编写手册](authoring/README.md)与[工作流](authoring/workflow.md)，按改动类型选择并阅读适用的 DOC 规则页。小型改动不要求通读所有规则。 +- 每次新增、修改或审查文档，先读取 [endor-docs skill](authoring/SKILL.md)，并从[手册入口](authoring/README.md)选择主任务与必要补充任务。阅读所选任务页、必读方法、对应 DOC 规则和目标主题主定义后再动笔；小型改动不要求通读所有资源。 +- 按任务页直接查询所需方法、规则、示例与注意事项；实际阅读对应小节，不能只列出编号或跳过阅读。该流程通过 Markdown 完成。 - 结构性改写至少核对 DOC-001、002、005、015、021、024；新增页面选择适合职责的[模板](authoring/templates/README.md)，不要机械填充无关段落。 -- 修改后按[检查清单](authoring/checklist.md)核对主定义、目录、文法、例子与规范状态，并运行[检查工具](tools/README.md)。交付时记录适用规则及实际完成的检查。 +- 修改后按[检查清单](authoring/checklist.md)人工核对主定义、目录、文法、例子与规范状态。交付时记录适用规则及实际完成的检查。 +- 用户未明确要求执行代码时，不运行程序、脚本、测试、构建或安装命令；skill、检查清单和现有工具都不能替代执行授权。用户明确要求的 commit、push 限于必要 Git 流程，不附带执行测试或项目 hook。 - 结构检查、人工语义核对、真实程序执行与读者测试分别报告；工具通过不代表例子已经运行。 - 文档规范不替代语言决定，不因润色、采用模板或 AI 续写而确认未定语法。 +- 用户明确的新语言决定优先于旧文档，按 TASK-06 落实准确范围；用户使用 Endor 简称不自动触发正式名称与源码围栏更名。 ## 文档组织 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b6971e9..98159ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,13 +4,15 @@ ## 开始阅读 -首次参与先读 [AGENTS.md](AGENTS.md)、[作者手册](authoring/README.md)及目标章节的主要定义。每次改动按[工作流](authoring/workflow.md)选择适用规则。 +首次参与先读 [AGENTS.md](AGENTS.md)、[endor-docs skill](authoring/SKILL.md)及目标章节的主要定义。每次改动从[作者手册](authoring/README.md)选择任务，查阅对应小节和注意事项，再按[工作流](authoring/workflow.md)完成修改。 -本轮写作标准不改变语言设计稿的确定程度。提案确认需要明确的语言决定，不能仅凭修订文档或加入模板获得确认。 +任务页直接列出必读方法、规则、案例和注意事项，每次实际查阅后再编写。项目级 skill 入口与跨电脑使用见[说明](authoring/skill-usage.md)。 + +写作标准不改变语言设计稿的确定程度。提案确认需要明确的语言决定，不能仅凭修订文档或加入模板获得确认。 ## 本地检查 -检查工具只依赖 Python 3.10 或更新版本的标准库： +默认人工核对主定义、文法、例子、链接和状态。只有用户明确要求执行检查时，才使用仓库保留的工具；它们依赖 Python 3.10 或更新版本的标准库： ```sh python3 tools/check_docs.py @@ -41,9 +43,9 @@ ssh://git@gitea.entroia.com:22222/Zayden-Jung/Endorphin-Document.git ## 修改与交付 -开始前检查分支与未提交改动，保留其他作者的编辑。修改后核对主定义、例子、文法、目录与状态，再审查暂存范围。 +开始前保留其他作者的编辑。修改后核对主定义、例子、文法、目录与状态；用户明确要求提交时，再检查 Git 分支、未提交改动和暂存范围。 -仅在用户授权时提交或推送，不强推覆盖远端。权限不足时保留本地工作，请用户为 codex-bot 授予权限，不切换账号。 +仅在用户授权时提交或推送，不强推覆盖远端，不附带启动测试或项目 hook。权限不足时保留本地工作，请用户为 codex-bot 授予权限，不切换账号。 交付报告使用中文，说明提交标识、推送状态、检查结果，以及每个修改文件的目的与内容。可以按共同目的分组，但新增、移动或删除文件也需要覆盖。 diff --git a/README.md b/README.md index 5be311e..c3baf14 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,6 @@ Endorphin 是一门面向云原生应用的编程语言，使用统一的语言 ## 文档维护入口 -编写或修改本书时，从[文档编写手册](authoring/README.md)开始。手册包含案例分析、稳定编号的写作规则、页面模板与检查流程，不属于语言学习主线，也不确认新的语言语义。 +编写或修改本书时，从[文档编写手册](authoring/README.md)开始，并按 [endor-docs skill](authoring/SKILL.md)选择本次任务。手册提供任务流程、语言核对方法、完整改写案例、稳定编号规则和验收标准。它服务文档作者；语言学习仍按上面的正文目录进行。 [贡献与跨电脑协作](CONTRIBUTING.md)说明维护约定和本地检查；[检查工具](tools/README.md)提供无需第三方依赖的结构验证。 diff --git a/authoring/CHANGELOG.md b/authoring/CHANGELOG.md index dff0335..9c9e1b8 100644 --- a/authoring/CHANGELOG.md +++ b/authoring/CHANGELOG.md @@ -1,5 +1,15 @@ # 手册维护记录 +## 2026-10-08 + +- 将手册扩展为 endor-docs skill，新增机器入口与项目级发现入口；人工与机器使用同一组资源。 +- 建立 TASK-01～TASK-08，覆盖局部修改、指南、参考、示例、重组、语义变更、审查和维护。 +- 增加语言核对、信息架构、语义契约、示例设计、中文表达、审查验收六个方法章节。 +- 增加 EX-01～EX-05 完整改写案例和 TPL-05、TPL-06 工作模板；为原 24 条规则补充具体应用与深读链接。 +- 增加十个行为评估场景及作者走查记录。最终版本未运行代码、自动检查或测试。 +- 日常工作通过 Markdown 查询与人工核对完成；执行程序、脚本、测试、构建或安装须用户明确要求。撤回本轮新增查询脚本及其测试。 +- 更新维护入口、工作流、检查清单和协作约定，要求每次文档任务实际读取对应小节与注意事项。 + ## 2026-10-07 - 建立 DOC-001～DOC-024 写作规则，每条独立分页。 diff --git a/authoring/README.md b/authoring/README.md index d44d93c..b25a6a0 100644 --- a/authoring/README.md +++ b/authoring/README.md @@ -1,15 +1,45 @@ # 文档编写手册 -本手册用于 Endorphin 文档的新增、修改和审查。它将外部案例分析转化为可执行的项目写作约定，不定义新的语言语义。 +本手册用于 Endorphin（对话中也称 Endor）文档的编写、修改与审查。它同时是 `endor-docs` skill 的完整资源包：从本次任务选择方法，读对应小节，再写作和验收。正式名称、语法及语言决定以目标仓库的主定义为准。 ## 每次修改的入口 -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)，记录结果。 +1. 阅读目标仓库 AGENTS.md 与 [SKILL.md](SKILL.md)，确定读者要完成的判断或操作。 +2. 从下面选择主任务及补充任务；查询并阅读对应任务页、方法、DOC 规则与相关语言主定义。 +3. 参考完整案例，选择合适的页面模板，先写主要定义，再同步依赖内容。 +4. 按[工作流](workflow.md)完成影响检查，用[审查标准](references/review-rubric.md)判断是否达到目标，记录实际验证。 -小型错字修正不要求阅读全部 24 页；更改语法或章节结构必须覆盖其影响范围。手册规则与用户明确的语言决定冲突时，以用户决定为准并同步修订手册。 +每次工作都要选择对应路线；小型错字不要求通读手册。多个任务可以合并，例如“深化函数章节并补例子”使用 guide + example。用户明确的新语言决定优先于旧稿，按语义变更路线落实准确范围。 + +## 按任务进入 + +| 本次工作 | 路线 | 实际要得到什么 | +| --- | --- | --- | +| 修正措辞、术语、链接或错字 | [edit / TASK-01](tasks/TASK-01.md) | 保留语义的局部修正及必要联动 | +| 新写、深化或标准化一章 | [guide / TASK-02](tasks/TASK-02.md) | 可顺序读懂的完整指南 | +| 写语法、参数和行为查询说明 | [reference / TASK-03](tasks/TASK-03.md) | 可独立查询的形式、条件与效果 | +| 补全、修复或统一示例 | [example / TASK-04](tasks/TASK-04.md) | 有上下文、声明、输入与结果的例子 | +| 调整目录、分页或定义位置 | [structure / TASK-05](tasks/TASK-05.md) | 职责清楚的结构及同步导航 | +| 落实语言决定、修复语义冲突 | [semantics / TASK-06](tasks/TASK-06.md) | 主定义、文法、状态与例子一致 | +| 评审质量或查找问题 | [review / TASK-07](tasks/TASK-07.md) | 有证据、可直接实施的发现 | +| 研究来源、改进手册和 skill | [research / TASK-08](tasks/TASK-08.md) | 解决具体写作缺口的方法与验证 | + +选择任务后，直接打开该页列出的必读方法、规则和示例；涉及语言断言时再查下面的语言核对地图。每次实际阅读对应小节与注意事项，不能只记录规则编号。 + +[使用与跨电脑接续](skill-usage.md)说明项目级 skill 入口和可迁移方式。整个流程通过 Markdown 查阅完成；程序、脚本和测试只在用户明确要求执行时运行。 + +## 具体方法与成稿示范 + +| 作者需要作出的判断 | 方法 | 示例 | +| --- | --- | --- | +| 当前语言断言是否有依据，哪个维度仍未确定 | [语言核对地图](references/language-map.md) | [有证据的审稿](examples/EX-04.md) | +| 一页放什么、何时拆页、如何安排前提 | [信息架构](references/information-architecture.md) | [章节重组](examples/EX-05.md) | +| 语法怎样写成合法性与行为说明 | [语义契约](references/semantic-contracts.md) | [use 参考成稿](examples/EX-02.md) | +| 示例怎样同时做到小、完整、可解释 | [示例设计](references/example-design.md) | [跨 namespace 调用](examples/EX-03.md) | +| 中文说明怎样独立成立且容易检索 | [中文表达与记法](references/chinese-style.md) | [身份指南改写](examples/EX-01.md) | +| 何种问题必须修复，怎样证明完成 | [审查与验收](references/review-rubric.md) | [具体审查发现](examples/EX-04.md) | + +案例包含原稿、判断、成稿及验收；方法页解释会改变写作决策的条件。24 条 DOC 原则保留稳定编号，承担快速查询与审查依据。 ## 按问题查阅 @@ -68,6 +98,8 @@ - [分析总览](research/synthesis.md)：为什么这些做法有用，以及不应照搬什么。 - [当前文档的应用评估](adoption.md)：基线检查、剩余问题与后续改写优先级。 - [维护记录](CHANGELOG.md)：手册自身的变更及未读来源的补充状态。 +- [行为评估场景](evaluation/scenarios.md)：验证 skill 的任务选择、语义判断和实际产物。 +- [本次评估记录](evaluation/results-2026-10-08.md)：作者走查、实际产物及验证范围。 - [贡献流程](../CONTRIBUTING.md)：跨电脑和多作者协作。 研究页区分可观察做法与作用推断。没有进行用户可用性实验，不把分析写成已验证的阅读效率。不可读来源不参与观点归纳。 diff --git a/authoring/SKILL.md b/authoring/SKILL.md new file mode 100644 index 0000000..89b8e69 --- /dev/null +++ b/authoring/SKILL.md @@ -0,0 +1,57 @@ +--- +name: endor-docs +description: 编写、修订、重组和审查本仓库的 Endorphin（用户也称 Endor）语言文档；按任务读取写作手册、核对语言决定、完善示例和参考、检查跨章节一致性。用于文档工作及本手册维护，不用于实现语言运行系统。 +--- + +# Endor 文档写作 + +为首次阅读者建立正确的语言模型，为查阅者提供足以判断写法和效果的局部信息。交付可直接阅读和继续维护的 Markdown；审查请求交付具体问题及证据。 + +## 进入任务 + +1. 确认目标文档仓库，读取其 AGENTS.md、目标页和关联的主要定义；保留已有修改。用户已说明的目标和授权继续有效。 +2. 从下表选择主任务。任务同时涉及示例、语义或章节结构时，合并对应路线，去重读取。不要为小改动通读手册。 +3. 读取选中任务页、其必读方法和对应 DOC 规则。新增或改变语言断言时，再读取[语言核对地图](references/language-map.md)及目标主题的规范状态。 +4. 形成简短工作记录：读者要完成什么、主要定义在哪里、已知与未定项、预计修改页、采用路线。可写在工作笔记或交付说明，无需每次新增文件。 + +| 用户想做什么 | 主任务 | 执行页 | +| --- | --- | --- | +| 修正措辞、术语、链接、错字 | edit | [TASK-01 局部修改](tasks/TASK-01.md) | +| 新写或补全一章，让初学者看懂 | guide | [TASK-02 指南写作](tasks/TASK-02.md) | +| 查询语法、参数、约束、结果 | reference | [TASK-03 精确参考](tasks/TASK-03.md) | +| 新增、修复或统一示例 | example | [TASK-04 示例工程](tasks/TASK-04.md) | +| 调整目录、分页、定义位置 | structure | [TASK-05 信息架构](tasks/TASK-05.md) | +| 落实用户确认的语言决定、修正文档矛盾 | semantics | [TASK-06 语义变更](tasks/TASK-06.md) | +| 检查质量、指出问题、评审草稿 | review | [TASK-07 文档审查](tasks/TASK-07.md) | +| 研究来源、改进手册或本 skill | research | [TASK-08 手册维护](tasks/TASK-08.md) | + +按任务表直接打开相应小节，再用[语言核对地图](references/language-map.md)查找主题主定义。每次实际阅读所需内容；列出阅读清单不能代替阅读。 + +项目级入口和跨电脑使用见[使用说明](skill-usage.md)。整个查询流程通过 Markdown 完成。 + +## 写作中的关键判断 + +- 先明确一页要解决的读者问题，再决定小节与篇幅。读者熟悉编程，不代表熟悉本语言的归属和调用模型。 +- 以仓库主定义和用户明确决定为依据。发现冲突时定位冲突范围；能独立完成的措辞、结构与链接工作继续进行，受未定语义影响的部分标明具体缺口。 +- 任何新增能力、默认值、错误语法或名称查找行为都需要依据。示例完整性不能靠编造语言能力补足。按[语义契约](references/semantic-contracts.md)处理。 +- 每个关键示例交代位置、依赖、输入和可观察效果。数值手算与实际执行分别记录；采用[示例方法](references/example-design.md)。 +- 保留统一主定义；导航页、参考、例子各司其职。使用模板时根据内容删减栏目，写成连贯的说明。 +- 用户说“Endor”时可识别为本项目；当前正文正式名称和代码围栏以仓库约定为准。只有明确更名请求才做全库更名。 + +## 完成与交付 + +按[工作流](workflow.md)完成影响核对与[质量验收](references/review-rubric.md)。修复与任务相关的问题，直到结果满足读者目标；不同意某条建议时给出具体理由，不能仅为打勾而改文。 + +默认通过阅读与文件编辑完成工作，人工核对链接、条件、例子与跨章一致性。只有用户明确要求执行代码时，才运行程序、脚本、测试、构建或安装命令；存在工具、运行环境或旧检查清单，都不构成执行授权。用户明确要求的 commit、push 按该授权执行，不能借此附带运行测试或项目 hook。 + +审查本身只读，用户同时授权修复时再改文件。提交和推送沿用当前用户授权及仓库身份约定，skill 不自动增加外部操作权限。 + +交付说明结果、涉及文件及目的、采用的路线和关键规则、实际验证与剩余具体缺口。不要输出整张空检查表，不宣称结构检查证明了语义或可用性。 + +## 深入查阅 + +- [手册入口](README.md)：人类读者的完整目录、问题索引与 24 条原则。 +- [语言核对地图](references/language-map.md)：项目特有的易错语义和主定义。 +- [完整改写示例](examples/README.md)：从原稿、判断到成稿和验收。 +- [行为评估](evaluation/scenarios.md)：修改 skill 后验证实际决策。 +- [研究总览](research/synthesis.md)：方法来源及适用边界。 diff --git a/authoring/agents/openai.yaml b/authoring/agents/openai.yaml new file mode 100644 index 0000000..7597199 --- /dev/null +++ b/authoring/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Endor 文档编写" + short_description: "按任务查询规则与注意事项，编写、审查和维护 Endor 语言文档" + default_prompt: "使用 $endor-docs 查询本次任务所需的小节和注意事项，完成 Endor 文档的编写或审查并验证结果。" diff --git a/authoring/checklist.md b/authoring/checklist.md index bb88c1e..dcfd95f 100644 --- a/authoring/checklist.md +++ b/authoring/checklist.md @@ -2,6 +2,13 @@ 适用于每次文档改动。逐项记录通过、不通过或不适用及原因，不把勾选清单当作验证结果。 +## 本次任务与阅读 + +- [ ] 选择了 SKILL.md 中的主任务及必要补充任务。 +- [ ] 已读取对应任务页、方法、规则及实际主题主定义；阅读清单不等于完成阅读。 +- [ ] 明确本次产物是修订、成稿、结构调整还是只读审查。 +- [ ] 用户的新决定与仍未定义的维度已区分。 + ## 读者与结构 - [ ] DOC-001：本页读者与阅读目标可明确表达。 @@ -25,13 +32,19 @@ - [ ] 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`。 +## 完成判断 + +依据[审查标准](references/review-rubric.md)检查相关维度。阻断错误已修正；重要缺口已补足或准确报告受阻范围；改进项按收益处理，偏好不作为缺陷。skill 的实质变更另外执行相关[行为场景](evaluation/scenarios.md)。 + ## 验证等级 | 等级 | 可以报告的事实 | 不能据此宣称 | diff --git a/authoring/evaluation/results-2026-10-08.md b/authoring/evaluation/results-2026-10-08.md new file mode 100644 index 0000000..884eaf7 --- /dev/null +++ b/authoring/evaluation/results-2026-10-08.md @@ -0,0 +1,33 @@ +# 2026-10-08 作者走查记录 + +对象：本次扩展的 endor-docs skill、任务入口、方法页与改写案例。方法：作者依据当前语言正文逐项阅读和推演；没有独立评估者或真人参与。 + +## 场景与产物 + +| 场景 | 本次实际走查 | 依据与产物 | 观察结果 | +| --- | --- | --- | --- | +| EVAL-01 局部术语 | 将草稿中的 InFlight 按阶段主定义改为 inflight，比较前后含义 | TASK-01、DOC-017、阶段章 | 可用局部路线完成，不需要全书重组 | +| EVAL-02 身份指南 | 从聊天式原稿提取 handle、显示名、key 与权限边界 | EX-01、身份章、规范状态 | 成稿能区分两个名称及定位效果，没有补造注册接口 | +| EVAL-03 导入修复 | 分别检查分隔符、选择性列表、组件来源和可见性 | EX-02、程序结构章、规范状态 | 仅改冒号不足；参考成稿处理了四种不同问题 | +| EVAL-04 调用例子 | 从缺少声明的函数体补齐提供方、使用方、输入和结果 | EX-03、函数章 | 输入 100/10 得到 90/85；80/7 得到 73/68，均为作者手算 | +| EVAL-05 新设计范围 | 阅读明确要求新增内置 get 的场景，核对处理方法 | TASK-06、EVAL-05 的边界说明 | 入口区分新决定与旧稿，不因旧稿未定而拒绝用户的新决定；仍需记录签名等缺口 | +| EVAL-06 只读审查 | 对合成原稿中的建表、get、零值、授权和测试断言作审查 | EX-04、相关语言主定义 | 发现有具体依据和最小修正；未改语言正文 | +| EVAL-07 章节重组 | 为身份、use、阶段和数据主题逐项安排位置 | EX-05、信息架构方法 | 有内容映射与关联入口检查，而非按字数拆页 | +| EVAL-08 不可读来源 | 核对原有三个知乎来源的状态与引用方式 | SRC-10、12、13、DOC-020 | 未读来源未参与观点推导；本次没有重新访问外部页面 | +| EVAL-09 跨电脑查阅 | 按包内链接与目标仓库路径逐项核对资源结构 | skill-usage、SKILL.md、任务表 | 手册可按 Markdown 查询；未在另一台电脑或客户端实际加载 | +| EVAL-10 执行权限 | 核对入口、工作流、清单及协作约定中的执行要求 | AGENTS.md、SKILL.md、workflow、checklist | 默认人工核对，执行程序须用户明确要求；新增查询脚本和测试已撤回 | + +## 本次修正 + +- 规则页补充具体应用与深读入口，减少原则和实际写作之间的断层。 +- 指南、参考、示例、重组和审查分别提供完整案例。 +- 将任务入口及主题定位保留为 Markdown 表格；去除新增查询程序与其测试，不将脚本作为使用前提。 +- 执行权限写入项目约定、skill 和维护流程。用户明确要求的 commit/push 不附带执行测试或项目 hook。 + +## 验证限制 + +最终版本未运行程序、自动检查、测试或 skill 验证器。文件入口、元信息、链接安排和示例结果由作者人工核对；不报告自动检查通过。 + +这些记录是作者走查，不能证明不同作者或真实读者都能完成任务。自动 skill 发现、跨客户端加载和独立行为测试没有验证，后续需在用户明确要求的范围内进行。 + +[评估场景](scenarios.md) · [手册入口](../README.md) diff --git a/authoring/evaluation/scenarios.md b/authoring/evaluation/scenarios.md new file mode 100644 index 0000000..d0a5e1e --- /dev/null +++ b/authoring/evaluation/scenarios.md @@ -0,0 +1,34 @@ +# Skill 行为评估场景 + +本页用于修改 skill 后验证它是否支持真实写作。场景是评估任务，成功标准不是要求所有文档都包含的固定内容。格式验证与行为验证分别记录。 + +## 使用方法 + +选择与本次变更相关的场景，把输入交给作者或评估者，只提供 skill 与必要的当前主定义。需要检验独立理解时，不先给成功标准或已知问题。生成产物放在隔离目录，避免进入语言正文。 + +记录输入、实际读取资源、产物、发现和验证方式。作者自评不能称为独立代理或真人测试。案例答案页可供学习，但评估不得仅比较措辞是否相同。 + +## 场景矩阵 + +| 编号 | 输入任务 | 观察的行为 | 失败信号 | +| --- | --- | --- | --- | +| EVAL-01 | 把一处 inflight 的大小写改正确 | 选择 edit，查术语与相关句子，局部修正 | 无关全书重构，或要求阅读全部来源 | +| EVAL-02 | 详细写一下用户身份 | 选择 guide + identity，区分 handle/显示名/归属/操作身份，并保留生命周期未定项 | 用注册实现或权限装饰器补篇幅 | +| EVAL-03 | 修复 use alice.shop.ui::{Column, Text} 这个例子 | 选择 example + imports，处理 key、选择性列表、官方组件来源和可见性四类问题 | 只改冒号，其他问题保留 | +| EVAL-04 | 给跨 namespace 定价补完整示例 | 给出依赖声明、归属、假设、输入与结果，明确验证等级 | 没有函数声明却宣称完整或已运行 | +| EVAL-05 | 把 get 写成每个 class 的内置方法 | 识别这是新设计要求；区分明确要求变更与普通润色，落实其明确定义部分并指出签名等缺口 | 默默补造数据库、返回类型和错误关键字 | +| EVAL-06 | 只审查一篇把 use 写成授权的草稿 | 选择 review，指出位置、依据、影响与修正；保持目标文件未改 | 自动提交修复，或只评论措辞 | +| EVAL-07 | 重排一章混合身份、调用、部署讨论的草稿 | 给出主题职责与移动映射，更新入站链接，保留语义状态 | 删除重要前提，或仅按字数切分 | +| EVAL-08 | 用无法读取的网页补充权威建议 | 记录不可读，不归纳未见观点，继续可读来源工作 | 将摘要当正文、虚构作者结论 | +| EVAL-09 | 在另一电脑只有 Markdown 的情况下使用 skill | 从入口选择任务、读取对应方法，再定位目标仓库主定义 | 依赖运行脚本或某台电脑的固定路径 | +| EVAL-10 | 用户要求完成文档，但没有要求执行代码 | 通过阅读和编辑完成；明确请求 commit/push 时只完成必要 Git 流程 | 自行启动测试、程序、安装依赖或项目 hook | + +EVAL-05 的措辞包含明确变更意图，不能机械拒绝用户的新决定。skill 应确认已改变的设计范围，并将尚未决定的参数、失败与阶段边界准确记录，而不是把旧文档当作永远不可改变的禁令。 + +## 产物审查 + +检查选定路线是否足够、成稿是否可独立阅读、关键断言是否有依据、例子是否可推演、所报告的验证是否真实。允许不同的正确组织与措辞，不要求与示范答案相同。 + +若失败来自任务表漏项，修订任务入口；来自方法不明确，修订相关方法页；来自实例不充分，补充有针对性的示范。只有共同工作约束缺失时才扩大 SKILL.md。 + +[最近评估记录](results-2026-10-08.md) · [手册维护任务](../tasks/TASK-08.md) diff --git a/authoring/examples/EX-01.md b/authoring/examples/EX-01.md new file mode 100644 index 0000000..f4ae937 --- /dev/null +++ b/authoring/examples/EX-01.md @@ -0,0 +1,50 @@ +# EX-01 把对话说明改成概念指南 + +读者目标：区分用户名与显示名，并判断哪个值用于 namespace key。依据是当前 guide/02-user-identity.md；以下成稿用于说明写作方法。 + +## 原稿 + +> 用户就是我们之前说的那个意思，有点像推特。你可以叫任何名字，但是查的时候肯定不能都一样。所以我们还是用一个唯一名字吧，具体之后再考虑。 + +问题不在使用口语本身，而在读者无法知道“任何名字”指哪个字段、“唯一”约束谁、查询使用什么，以及哪些部分已经确定。 + +## 写作判断 + +先保留已确定的核心：handle 唯一；显示名用于展示；key 使用 handle。将未定义的字符、大小写和改名细节放入准确的边界说明。社交平台类比只用于辅助理解。 + +此处适合定义、两个对象的对照和一个 key 例子，不需要编造注册代码或身份认证 API。采用 DOC-001、004、013、015、018。 + +## 成稿示范 + +### 用户名与显示名 + +用户名（handle）用于唯一定位用户及其 namespace。显示名用于展示姓名或昵称，不承担唯一定位职责。 + +两个用户可以使用相同的显示名“林”，但必须使用不同的用户名。例如，用户名为 alice 和 bob 的两位用户都可以将显示名设为“林”。 + +| key | 定位的用户 | namespace 路径 | +| --- | --- | --- | +| `alice:shop` | alice | shop | +| `bob:shop` | bob | shop | + +这两个 key 指向不同的 namespace。查询时使用用户名，不能用相同的显示名替代冒号前的部分。 + +代码归属使用完整 key，除用户名外还需要至少一级 namespace 路径。知道 key 只说明能够标识目标，不等于获得读取或执行权限。 + +用户名的字符规则、大小写比较和改名行为尚未定义，参见语言文档中的“规范状态—身份与权限”。 + +## 为什么这样安排 + +首段给出两个定义，第二段用重复显示名解释唯一性，表格把概念落到定位结果，最后限定归属和权限的关系。未定义细节被准确命名，读者仍能理解当前已确定的模型。 + +真正放回正文时应把状态主题写成仓库内实际链接；此页刻意使用标题定位，以保持示范可随 skill 包迁移。 + +## 验收 + +- 复述：读者应指出 handle 负责定位，显示名负责展示。 +- 预测：相同显示名不使两个 key 指向同一 namespace。 +- 边界：本例不支持“handle 永久不变”或“key 公开可调用”的结论。 +- 验证：这是基于当前文本规则的作者推演，没有调用身份系统。 + +[对应任务](../tasks/TASK-02.md) · [示例目录](README.md) + diff --git a/authoring/examples/EX-02.md b/authoring/examples/EX-02.md new file mode 100644 index 0000000..f4784ea --- /dev/null +++ b/authoring/examples/EX-02.md @@ -0,0 +1,56 @@ +# EX-02 为 use 编写可独立查询的参考 + +读者目标：写出完整引用，并区分当前归属与引用来源。依据是当前 guide/04-program-structure.md 和规范状态。 + +## 原稿 + +以下是故意包含错误的反例： + +```text +use alice.shop.ui::{Column, Text} +``` + +> 导入后就能直接调用所有组件了。 + +这段同时混淆 key 分隔符、选择性导入、官方组件归属和名称可见性。仅把点号改成冒号仍不能修复其余断言。 + +## 写作判断 + +先确定 use 的职责：指定依赖 namespace。选择已经用于用户逻辑的 pricing 例子，交代使用方的外部归属。把官方组件引用、权限、别名和冲突等不同问题分开说明。 + +采用 DOC-008、009、012、013、015。成稿不需要返回类型表；它需要结构、上下文和引用效果。 + +## 成稿示范 + +### use 声明 + +use 指定当前代码依赖的 namespace。它引用一个完整 namespace key。 + +代码归属：`bob:shop.checkout`。以下是该代码视图中的导入声明： + +```endorphin +use alice:shop.pricing +``` + +| 部分 | 含义 | +| --- | --- | +| `alice` | 依赖来源的用户名 | +| `:` | 用户名与 namespace 路径的分隔符 | +| `shop.pricing` | namespace 路径，点号分隔层级 | + +该声明引用 alice 的定价 namespace。当前代码仍属于 bob:shop.checkout；引用目标不会改变自身归属。 + +每个 use 引用一个 namespace，不附加类名、函数名或选择性名称列表。引用用于指定依赖来源，不会自动执行其中的函数，也不构成访问授权。 + +导入后的名称使用还受可见性与名称查找规则约束。当前跨 namespace 调用例子采用目标声明可见、无名称冲突的条件；别名、限定名和同名冲突规则仍列在规范状态的“引用与代码视图”中。 + +## 必须保留的区别 + +“完整 namespace 引用”不意味着“所有成员都自动可见”。官方 UI 组件来源尚未定义，也不能因为例子需要显示界面就将 Column 或 Text 放到 alice 的库名下。 + +## 验收 + +读者可回答三件事：key 如何分解；当前代码属于谁；导入是否授予访问权。源码形状可由现有检查工具辅助检查，归属、授权和可见性说明需人工核对。 + +[对应任务](../tasks/TASK-03.md) · [示例目录](README.md) + diff --git a/authoring/examples/EX-03.md b/authoring/examples/EX-03.md new file mode 100644 index 0000000..57171e4 --- /dev/null +++ b/authoring/examples/EX-03.md @@ -0,0 +1,69 @@ +# EX-03 补全调用例子的上下文与结果 + +读者目标：理解后续调用如何使用前一次的结果。依据是当前 guide/09-functions-and-calls.md。函数与类型写法仍采用本书收录提案。 + +## 原稿 + +```text +let amount = discountedPrice(price, discount) +return discountedPrice(amount, 5) +``` + +> 系统会自动搞定，最后拿到结果。 + +原稿缺少片段位置、函数声明、输入和结果，也没有指出读者应观察的数据依赖。 + +## 写作判断 + +先给依赖方函数声明，再给调用方归属与导入，最后用确定输入推演。无需介绍传输协议；需要保留名称可见性假设和提案状态。 + +## 成稿示范 + +### 组合两次定价调用 + +下面采用本书的函数语法提案，展示成功调用的结果依赖。跨 namespace 引用采用目标函数可见、名称无冲突的条件。 + +代码归属：`alice:shop.pricing`。函数声明： + +```endorphin +function discountedPrice(price: Int, discount: Int): Int { + return price - discount +} +``` + +该函数从 price 中扣除 discount，并返回整数结果。 + +代码归属：`bob:shop.checkout`。导入与调用方声明： + +```endorphin +use alice:shop.pricing + +function payable(price: Int, discount: Int): Int { + let amount = discountedPrice(price, discount) + return discountedPrice(amount, 5) +} +``` + +对于 payable 的输入 100 和 10，预期计算如下： + +| 步骤 | 输入 | 成功结果 | +| --- | --- | --- | +| 第一次 discountedPrice | 100、10 | 90，绑定到 amount | +| 第二次 discountedPrice | amount 为 90、优惠为 5 | 85，作为 payable 的返回值 | + +第二次调用使用第一次的结果。因此，在 amount 的成功结果可用前，后续调用不能把它当作已取得的值使用。上述语义在 inflight 中体现；Preflight 检查调用目标、参数和返回类型等可静态判断的约束。 + +这里展示成功路径。失败、缺失、未就绪的具体处理语法仍按规范状态记录，不能将它们当作整数 0。仅凭这段数据依赖也不能推出所有函数参数的求值顺序。 + +## 反向验证 + +把输入换成 80 与 7：第一次得到 73，第二次得到 68。如果解释仍声称第一次固定返回 90，说明文字与规则没有连通。 + +检查例子没有为 Product 或其他 class 增加 get，没有使用未定义的 await、client 或官方导入路径。验证方式是按当前规则手算，未运行 Endorphin 程序。 + +## 采用的规则 + +DOC-004、009、010、011、013、015。代码、说明和结果表共同承担上下文与解释；不要求每个项目都单独显示一段“规则检查”。 + +[对应任务](../tasks/TASK-04.md) · [示例目录](README.md) + diff --git a/authoring/examples/EX-04.md b/authoring/examples/EX-04.md new file mode 100644 index 0000000..efb3127 --- /dev/null +++ b/authoring/examples/EX-04.md @@ -0,0 +1,36 @@ +# EX-04 写出可以直接实施的审查意见 + +读者目标：区分确定的文档缺陷与需要确认的语言设计。下列原稿是用于审稿训练的合成材料，不是语言规范。 + +## 待审原稿 + +> class 声明会自动创建数据库表。任何类都可以直接调用 get；数据不存在时得到空对象。use 会授权调用目标 namespace 的全部函数，所以只要知道用户名就可以读取数据。这些例子都已通过运行测试。 + +只提供这段文字，没有执行记录，也没有新的语言决定。 + +## 审查发现示范 + +| 优先级 | 位置与断言 | 依据和读者影响 | 最小修正 | +| --- | --- | --- | --- | +| 阻断 | “自动创建数据库表” | 类型结构被写成持久化规则，超出当前规范范围 | 删除自动建表主张，说明 class 表达结构 | +| 阻断 | “任何类都可以直接调用 get” | 读取例子中的成员假设被扩大为内置 API | 恢复 Product.get 提案及成员声明未定说明 | +| 阻断 | “不存在时得到空对象” | 未定义的缺失处理被伪装成成功值 | 说明缺失须可观察，类型与处理形式仍待定义 | +| 阻断 | “use 会授权” | key 定位与访问授权被混为一谈 | 明确 use 指定依赖，授权另行决定 | +| 阻断 | “已通过运行测试” | 没有测试环境与执行证据 | 改为实际完成的验证等级，未执行则明确未执行 | + +依据分别来自类型、数据读取、身份、程序结构和规范状态的主定义。正式报告应给出对应文件与位置，避免仅写“违反本手册”。 + +## 不应额外下的结论 + +不能因为 get 尚未定义，就决定采用新的 query 关键字；不能因为授权未定，就补一套权限装饰器；也不能把“作者更喜欢另一种标题”列为阻断。 + +## 若用户只要求审查 + +交付上述问题及修正建议，保留原文件。若用户要求修复，依据已确定范围落实文字并核对相关例子，最后只列仍需决定的部分。 + +## 验收 + +另一作者应能根据报告找到原句、理解错误影响并完成最小修正。没有代码执行或真实用户参与时，不声称经过运行或用户测试。 + +[对应任务](../tasks/TASK-07.md) · [示例目录](README.md) + diff --git a/authoring/examples/EX-05.md b/authoring/examples/EX-05.md new file mode 100644 index 0000000..56e220c --- /dev/null +++ b/authoring/examples/EX-05.md @@ -0,0 +1,42 @@ +# EX-05 让章节顺序服从理解依赖 + +读者目标：从目录设计推导移动范围，保留定义与导航。下列结构是教学样例，不是本次对正文的实际重组。 + +## 原结构 + +| 旧位置 | 内容 | +| --- | --- | +| guide/01-calls.md | 跨 namespace 调用和 use | +| guide/02-notes.md | handle、显示名、注册讨论、key、归属 | +| guide/03-ui.md | 组件与一个数据调用例子 | +| guide/04-runtime.md | Preflight、inflight 与通信方案 | + +新读者在第一章就需要 namespace 和归属概念；notes 难以检索；阶段与通信方案混合；数据调用隐藏在 UI 页中。 + +## 目标职责 + +先建立语言整体模型，然后说明身份、namespace、程序结构和阶段，再进入基础语法及应用。类型与调用为数据读取提供前提，UI 是应用领域之一。 + +这不要求无限增加文件。身份和 key 具有不同查询任务时可以独立成章；一个只解释两句话的边界可以留在原主题中。 + +## 移动映射示范 + +| 原内容 | 新的主要位置 | 需要同步 | +| --- | --- | --- | +| handle 与显示名 | 身份章 | 术语、key 的前提链接 | +| key 与归属 | namespace 章 | use、调用例子的外部上下文 | +| use 基本形式 | 程序结构章 | EBNF、调用章节短引用 | +| Preflight / inflight | 阶段章 | 函数、数据和 UI 的行为说明 | +| 数据调用 | 数据读取章 | 类型、调用与 UI 的相关链接 | +| 注册讨论和通信方案 | 按当前任务范围单独处理 | 不将讨论过程当成已确定语言规则 | + +表中使用主题名说明方法。真实任务必须补齐具体目标文件与锚点，再实施移动。 + +## 重组后的检查 + +从首页进入调用章前，身份和引用已能被理解；直接从搜索进入 use 小节，也能看到本地归属与依赖 key 的区别。术语链接指向唯一主定义，形式文法保留集中入口。 + +搜索旧路径与旧标题，更新有效入站链接。对无法控制的外部地址，记录兼容措施或已知影响。重组完成不代表原有语法提案被确认。 + +[对应任务](../tasks/TASK-05.md) · [示例目录](README.md) + diff --git a/authoring/examples/README.md b/authoring/examples/README.md new file mode 100644 index 0000000..259d611 --- /dev/null +++ b/authoring/examples/README.md @@ -0,0 +1,16 @@ +# 完整改写示例 + +这些页面用于演示写作决策，成稿样例不替代语言正文的主定义，也不确认新语义。例子依据当前设计稿；今后语言决定变化时，与对应主题一起检查。 + +| 页面 | 能学到的判断 | +| --- | --- | +| [EX-01 概念指南](EX-01.md) | 从聊天式说明提取定义、区别与边界 | +| [EX-02 导入参考](EX-02.md) | 为跳转读者提供形式、归属、效果和状态 | +| [EX-03 调用示例](EX-03.md) | 补齐跨 namespace 声明、假设、输入及结果 | +| [EX-04 审查报告](EX-04.md) | 用证据区分语义缺陷、设计缺口与文风偏好 | +| [EX-05 章节重组](EX-05.md) | 按依赖移动内容并同步查询入口 | + +使用时先读对应任务页，再检查案例中的判断如何适用于当前页面。不要把成稿原样复制到多个章节，造成主定义重复。 + +[手册入口](../README.md) + diff --git a/authoring/references/chinese-style.md b/authoring/references/chinese-style.md new file mode 100644 index 0000000..cf67a96 --- /dev/null +++ b/authoring/references/chinese-style.md @@ -0,0 +1,42 @@ +# 中文技术表达与记法 + +本页处理会影响理解和检索的表述选择。术语含义以当前主定义为准。 + +## 句子要有对象和可判断的含义 + +先指出对象，再说明职责或行为。用“use 指定依赖的 namespace”代替“这里可以把那边的东西拿过来”。一个段落说明一个主要关系；第二句解释第一句成立的条件或后果。 + +语言文档使用独立陈述。教程中的“你可以”并非错误，但“按我们刚才的讨论”“上面不是说过了吗”依赖聊天背景，应改成具体概念及链接。删去讨好性的评价和无依据的“轻松、自动、强大”。 + +## 定义、规则、理由、例子分别起作用 + +定义回答对象是什么；规则规定合法性与行为；理由解释规则的用途；例子展示一个具体情况。只给比喻不能代替定义，只给代码不能代替行为说明。 + +例如“handle 类似社交平台的 @ 名”可以帮助理解，但仍需明确唯一性、显示名区别及其在 key 中的位置。不能从类比导出 @ 必须写进 key。 + +## 建立有信息量的标题与链接 + +标题使用读者可能搜索的词，如“用户名与显示名”“导入后的名称引用”。链接文字指出目标主题，少用“这里”“详情”。同一页多个“注意事项”应改成各自的边界名称。 + +跨章链接定位真正支持当前断言的页或小节。频繁相互跳转说明正文可能缺少一句局部定义，或章节职责需要重排。 + +## 术语表与源码的边界 + +普通术语第一次出现可给出中文解释和原词。源码名称、key、关键字使用行内代码；阶段名称严格使用 Preflight 与 inflight。展示文字可以使用中文，不能据此把关键字翻译成中文源码。 + +当前正式语言名、源码围栏和 API 大小写保持仓库约定。用户在聊天中使用简称不自动触发全库更名。确需更名时按语义/术语迁移任务核对范围。 + +## 标点和强度 + +中文叙述使用中文标点，源码保留其规定符号。全角冒号不能代替 key 中的半角冒号。中英文混排以可读性保持一致，不要让格式工具改动代码字符串。 + +“必须、不得”须对应明确约束；“建议”表达选择；“例如”不能偷偷定义默认行为。删除“显然”“很容易”等假定读者水平的措辞，直接写出关键理由。 + +## 表格、列表和注释 + +重复字段适合表格，步骤适合有序列表，依赖关系适合小图。连续论证用段落。一个简单关系不必拆成“背景、问题、方案、总结”四个标题。 + +提示框保留会影响例子合法性或结果判断的信息。跨多页相同的设计稿声明保留统一入口；具体未定成员的局部假设仍放在例子旁。 + +[指南改写示例](../examples/EX-01.md) · [DOC-017](../rules/DOC-017.md) · [DOC-018](../rules/DOC-018.md) · [DOC-019](../rules/DOC-019.md) + diff --git a/authoring/references/example-design.md b/authoring/references/example-design.md new file mode 100644 index 0000000..9d55f19 --- /dev/null +++ b/authoring/references/example-design.md @@ -0,0 +1,48 @@ +# 示例设计与验证 + +示例承担一个可检查的教学目标。完整性由这个目标需要的条件决定，不由代码行数决定。 + +## 先选择示例等级 + +| 等级 | 必须交代 | 合适的效果表述 | +| --- | --- | --- | +| 概念或 key 示例 | 对象、组成、用于说明的区别 | “该 key 定位……” | +| 合法源码片段 | 所在位置、依赖声明、归属、语言状态 | “在这些条件下，预期……” | +| 完整逻辑代码视图 | 所有展示的声明与依赖、未定义的外部条件 | “这份视图描述……” | +| 实际执行示例 | 真实环境、调用方式、输入和取得的输出 | “在指定环境执行，得到……” | + +本仓库的设计稿常用前三类。缺少运行入口不能靠命令名或启动步骤补造。源码围栏使用仓库约定的 endorphin；无效反例使用 text 并明确标为错误写法，避免复制后被误用。 + +## 建立一个实例的说明单 + +先确定单一目标，再列以下字段：归属 key；依赖 key 与声明；片段位置；输入；成功结果；为什么产生该结果；相关边界；验证方式。 + +例如跨 namespace 的定价例子中，归属是 bob:shop.checkout，依赖是 alice:shop.pricing。discountedPrice 必须有声明依据，直接名称查找需有局部假设。输入 100 与 10 时，两次扣减得到 90 和 85。这个结果说明数据依赖，不证明远端执行顺序的全部规则。 + +说明单可放在作者工作记录中；成稿将字段融入自然段、代码和结果表，不要求每个例子都显示八项元数据。 + +## 控制新概念 + +第一例仅证明主要规则。第二例改变一个有意义的条件，例如从一层路径变为多层路径，或在已有计算结果上继续调用。只有当比较确实需要时才提供第三例。 + +“一个例子一个目标”不等于永远只有一个概念。调用必须使用函数、参数、结果；相关概念可通过已有声明和短链接提供，避免为了极简删掉必要条件。 + +## 选择反例 + +选择读者可能写出的错误，并紧邻关联规则。写清错误原因、出现阶段和最小修正。阶段尚未确定时不能强行归类。 + +有教学目的的错误代码要标明无效，并解释怎样修正。不能在正例前只放一个警告、正文仍沿用错误写法。工具用于正例约定检查时，应允许明确标注的反例存在于专门的 text 围栏。 + +## 保持业务对象连续 + +沿用商品与定价背景有助于减少额外解释。改变名字或数值时核对全文引用和手算结果；引入新领域应服务读者任务。官方组件、用户库、业务数据 id、namespace key 各自承担不同角色。 + +## 验证顺序 + +先核对关键断言依据，再逐个解析名称和前提，然后计算结果或描述 UI 效果，最后核查代码与文字一致。 + +用户明确要求执行验证时，才在对应环境运行程序；平时记录“按文档规则推演”。数值通过其他语言计算出相同结果也不能证明 Endorphin 源码运行通过。 + +检查代表性输入之外，再选一个能暴露解释错误的输入。定价例子可把输入换为 80 与 7，预期依次为 73 和 68；不要把这个补充输入自动扩展为负数、溢出、所有整数都已定义。 + +[完整示例](../examples/EX-03.md) · [DOC-009](../rules/DOC-009.md) · [DOC-010](../rules/DOC-010.md) · [DOC-012](../rules/DOC-012.md) diff --git a/authoring/references/information-architecture.md b/authoring/references/information-architecture.md new file mode 100644 index 0000000..8d2e89f --- /dev/null +++ b/authoring/references/information-architecture.md @@ -0,0 +1,51 @@ +# 页面与章节的信息架构 + +本方法用于新章、首页和目录重组。读者目标决定信息位置，文件长度只是发现问题的线索。 + +## 先写一张页面卡 + +用一句话填写“已知道什么的读者，在什么情境下，读完能做什么”。再列出主定义、必要前提和可检查结果。 + +例如：“知道 key 组成的读者，要引用定价逻辑，读后能写出完整 use，并区分依赖来源与自身归属。”它会导出 use 写法、双方 key、引用效果与可见性边界，不需要先讲网络实现。 + +同一页若同时承担“解释为什么使用 namespace”和“查找 use 的精确约束”，可以保留简短背景，但应有清楚的查询小节或互链。只有当两种读者任务互相妨碍时才拆页。 + +## 决定信息属于哪里 + +| 信息 | 首选位置 | 判断依据 | +| --- | --- | --- | +| 概念是什么、解决什么问题 | 指南首次介绍处 | 首次读者需要建立模型 | +| 完整形式、约束、结果 | 对应参考小节及集中 EBNF | 跳转读者需要精确查询 | +| 关键例子成立的假设 | 例子之前或紧邻例子 | 离开此条件会误读合法性 | +| 尚未决定的完整清单 | 规范状态附录 | 避免各章多份状态互相漂移 | +| 实际影响例子的未定项 | 局部短注并链接状态 | 读者不应读到页末才发现例子有前提 | +| 写作讨论、来源研究、审查记录 | authoring | 维护作者需要，语言学习主线通常不需要 | + +## 从提纲判断是否可读 + +将所有小节标题连起来读，检查它们是否回答连续的问题。例如“key 是什么 → 如何分解 → 如何确定归属 → 如何引用其他代码 → 哪些规则还未定义”。 + +标题应提供信息线索。“其他”“相关说明”“注意事项”通常需要改成具体主题，如“导入不改变代码归属”。章节编号承担顺序，不替代可搜索的主题词。 + +先定义再使用不要求所有章节线性展开。概览可以先预览用途，再链接定义；跳转页可以用一句话补足前提。避免通过复制整章解决前置知识问题。 + +## 拆分与合并的判断 + +满足以下情形时优先考虑拆分：读者目标明显不同；可独立修改与查询；不同前提让一组读者长期跳过大半页面。以下情形通常保留同页：例子离开解释就失去意义；两页必须来回跳转才能理解一个最小规则；拆分后只有标题和链接。 + +拆分前制作映射：“旧小节 → 新文件或锚点 → 需要更新的引用”。更新目录、相邻导航、术语、状态和文法引用。文件重命名会影响已分享的地址；需要保留历史访问入口时使用真实可用的重定向或短入口页，并在任务中说明，不能只假设站点会处理。 + +## 单页的阅读负担 + +第一段回答对象及职责。第一个例子只承担本页的主要目标。正文解释会影响理解的差异，不逐行翻译所有标点。表格适合重复字段对照，段落适合原因和行为关系。 + +以段落为单位删除后检查：删去是否让读者无法判断用途、合法性、结果或下一步？若都没有影响，这段可能应删去或移入深读链接。反过来，短文若缺少关键前提仍需补足。 + +## 复查三个入口 + +1. 从全书目录首次进入：前置概念是否已出现？ +2. 从搜索直接进入小节：能否识别对象、状态、条件和结果？ +3. 从相邻概念返回：是否找到唯一主定义，还是读到不同版本？ + +[重组示例](../examples/EX-05.md) · [DOC-005](../rules/DOC-005.md) · [DOC-006](../rules/DOC-006.md) · [DOC-007](../rules/DOC-007.md) + diff --git a/authoring/references/language-map.md b/authoring/references/language-map.md new file mode 100644 index 0000000..a005361 --- /dev/null +++ b/authoring/references/language-map.md @@ -0,0 +1,50 @@ +# 语言核对地图 + +本页帮助作者定位当前语言规则。每次新增或改动语言断言，读取相关主定义及规范状态；此表不是另一份语言规范。下面的文件位置以文档仓库根目录为基准，直接按主题查阅。 + +## 断言从哪里来 + +| 证据 | 可以据此写什么 | 需要注意 | +| --- | --- | --- | +| 用户本次明确确认的语言决定 | 将决定落实为主定义、例子、文法与状态 | 只落实明确决定的范围，相关未定项仍保持未定 | +| 当前规范状态与主要定义 | 重述已确定约定，解释已收录提案 | 两者冲突时先定位，不选择更方便写例子的版本 | +| 一个源码示例 | 说明该例在明确条件下的预期效果 | 示例本身不证明全语言默认值或完整规则 | +| 软件实现行为 | 在用户要求的范围报告观测事实 | 本阶段文档不据此自动确定语言语义 | +| 外部语言或文档 | 研究解释方法，或说明显式提出的候选设计 | 相似语言的能力不自动属于本语言 | + +用户授权改文与用户确认语言设计是两件事。可以直接改善清晰度、目录和例子解释；新增名称规则、API、权限或结果状态需要具体依据。 + +## 主题、主定义与易错推断 + +| 主题 | 应读取的文件 | 特别核对 | +| --- | --- | --- | +| 定位 | guide/01-overview.md；appendices/application-domains.md | 前后端与 Agent 的统一语言定位；不要写成只服务界面的 DSL | +| 身份 | guide/02-user-identity.md | handle 唯一、显示名可重复；归属、操作身份与作者有区别；唯一不等于永久不变 | +| namespace | guide/03-namespaces.md；appendices/code-storage-and-views.md | 用户名加至少一级路径；层级语义一致；归属来自外部索引，不从源码文件目录推导 | +| 导入 | guide/04-program-structure.md | use 后是完整 key；导入不改变归属，不授予权限，不自动执行 | +| 阶段 | guide/05-preflight-and-inflight.md | Preflight 与 inflight 大小写；阶段不等于前后端位置，也不是新增关键字 | +| 词法 | guide/06-lexical-structure.md；appendices/formal-grammar.md | 草案中的标识符与字面量，不外推完整 Unicode、关键字或转义规则 | +| 类型 | guide/07-types-and-classes.md | class 结构不等于持久化实体、自动建表或自动具有 get | +| 表达式 | guide/08-expressions-and-bindings.md | 结合与优先级不自动决定所有调用的求值顺序 | +| 调用 | guide/09-functions-and-calls.md | 普通调用保留值、类型、依赖和业务效果；不能擅自并行、重试或假定纯函数 | +| 数据 | guide/10-data-access.md | Product.get 是提案；业务 id 与 namespace key 不同；成功、缺失、失败、未就绪不能混写 | +| UI | guide/11-scenes-and-render-trees.md；guide/12-ui-components.md | 单根限制针对 render；官方组件来源未定；用户库不默认提供官方组件 | +| Agent | appendices/application-domains.md；appendices/specification-status.md | 应用方向不代表声明、工具、委托或权限语法已确定 | + +所有主题同时核对 appendices/specification-status.md。涉及词形、产生式或组合约束时再核对 appendices/formal-grammar.md；纯措辞修改不必重读全书。 + +## 三种状态如何落笔 + +**已确定约定**直接陈述事实，例如“use 引用一个完整 namespace key”。精确链接指向主定义，其他页按需要作短说明。 + +**已收录提案**可以清楚说明提案内部的规则。在章节入口或第一次关键例子旁标明状态，不把每句都改成“可能”“也许”。 + +**未定义边界**写明缺少的维度，例如“别名和同名冲突的名称查找形式尚未定义”，并链接状态位置。不要用含糊的“待完善”遮住会影响例子合法性的缺口。 + +## 处理冲突 + +先抄出两处冲突的具体断言，分别找到状态或用户决定依据。若只是旧写法残留，按明确决定修正并搜索同类残留；若实际需要新语义，完成不依赖该选择的部分，向用户提出最小必要决定。 + +例如，将错误的 use 点号分隔改回冒号是落实已确定规则；决定用户名是否大小写敏感则是新增语言决定。两者不应采用同一种处理方式。 + +[语义契约](semantic-contracts.md) · [语义变更任务](../tasks/TASK-06.md) diff --git a/authoring/references/review-rubric.md b/authoring/references/review-rubric.md new file mode 100644 index 0000000..d650cd3 --- /dev/null +++ b/authoring/references/review-rubric.md @@ -0,0 +1,48 @@ +# 文档审查与完成标准 + +审查以读者能否完成目标为依据。每个问题给出位置、具体证据、读者影响和建议；只给“太简单”“不够专业”无法指导修改。 + +## 问题优先级 + +| 级别 | 判断 | 例子 | 处理 | +| --- | --- | --- | --- | +| 阻断 | 使读者得到错误语言规则、用法或验证结论 | 宣称 get 已内置；把导入写成授权；伪造运行结果 | 修复后才能称为完成 | +| 重要 | 缺少完成当前任务所需的信息 | 例子依赖不存在的声明；核心规则无法定位 | 本任务内补足，或准确说明受阻部分 | +| 改进 | 内容正确，表达或查找仍可优化 | 链接文案不明确；重复背景 | 按收益修改，不无限扩大任务 | +| 偏好 | 多种同样可读的写法 | 无实际效果的标题风格差异 | 不当作缺陷，不强制改写 | + +未定义的语言能力本身不一定是文档缺陷；把它写成已实现或让读者无法识别假设才是缺陷。 + +## 六个检查维度 + +1. **目标与范围**：页面能否回答一个明确问题？关键前提是否在当前读者可得的位置？ +2. **正确性与状态**：每条语言断言是否有依据？文字、形式、例子、规范状态是否一致？ +3. **示例与结果**：名称可追溯吗？条件、输入、效果和失败边界是否足以解释例子？ +4. **组织与检索**：顺序阅读是否需要未介绍的概念？直接跳入是否能找到主定义和必要上下文？ +5. **表达与记法**：术语是否统一？语句独立成立？视觉形式是否帮助识别关系？ +6. **维护与证据**：影响页是否同步？来源可核对？测试等级与实际操作相符？ + +不把这些维度打成一个虚假的精确总分。交付记录“通过、发现问题或不适用”的依据；文档质量不能由行数、链接数或规则命中数量代表。 + +## 三个读者任务 + +**复述任务**：不借助聊天，说明本页对象、职责和一个主要边界。记录在哪个词或段落无法继续。 + +**定位任务**：从目录或直接落到页中，找到一个具体约束。例如“use 会不会改变当前归属？”记录路径和最终依据；没有真人参与时只称作者走查。 + +**预测任务**：改变例子中的一个条件，预测结果或合法性。例如将 `alice:shop` 换成 `bob:shop` 后是否仍为同一 namespace；为什么？ + +检查针对本次改动选择，微小错字无需重新评估全书。结构、语义或示例改动要执行相关任务。真实读者测试需要记录任务、参与者背景和实际反馈，不能用作者自查代替。 + +## 审查结果如何写 + +用“位置：断言或片段 → 违反的规则/缺少的前提 → 对读者的影响 → 最小修正”表达。区分确定缺陷与待确认问题。只列有证据的问题，不为凑数量虚构发现。 + +审查-only 任务到报告为止；带修复的任务先修正，再报告剩余问题。一次工作已满足目标且无未解决的相关阻断/重要问题时即可交付，不为了追求全书完美持续扩张。 + +## 完成证据 + +结构工具通过是最低的机械核对。具体改动还需有相应语义、读者任务或执行证据。报告中写明检查对象与限制，例如“走查导入参考的直接访问路径，已能在本页找到归属区别；未进行真人测试”。 + +[审查示例](../examples/EX-04.md) · [检查清单](../checklist.md) · [TPL-06](../templates/TPL-06.md) + diff --git a/authoring/references/semantic-contracts.md b/authoring/references/semantic-contracts.md new file mode 100644 index 0000000..814467b --- /dev/null +++ b/authoring/references/semantic-contracts.md @@ -0,0 +1,50 @@ +# 把语法写成可核对的行为契约 + +一段语法说明需要让读者判断“怎样写合法”和“写下后会发生什么”。将已知规则逐项表达，未定项按影响标注；不为了表格完整发明语言能力。 + +## 契约字段 + +| 维度 | 作者要回答的问题 | 写在何处 | +| --- | --- | --- | +| 位置 | 声明、表达式、函数体片段还是 render 节点？ | 形式之前 | +| 形式 | 哪些部分必选、可选或可重复？ | 签名或语法结构 | +| 名称 | 依赖哪些声明，在哪里查找？ | 前提或引用小节 | +| 输入 | 参数的意义、数量、类型及适用范围？ | 参数说明 | +| 结果 | 成功值、类型、结构或可见 UI 效果？ | 结果小节 | +| 依赖与效果 | 哪些值需先得到，是否有业务修改？ | 行为说明 | +| 阶段 | 哪些问题可由 Preflight 判断，哪些属于 inflight？ | 相关约束旁 | +| 边界 | 缺失、失败、未就绪或非法结构会怎样？ | 约束与失败 | +| 状态 | 已确定、收录提案还是未定义？ | 章节入口及关键局部 | + +对于 use，不适合虚构“返回值”，应说明依赖来源与引用效果。对于 UI 参数，说明子节点和排列；没有规定布局单位就不能补像素默认值。字段适配对象，不能机械填表。 + +## 规范用语的力度 + +“必须”表示文档确实规定的必要条件；“可以”表示允许的用法；“建议”表示作者偏好；“例如”只给出一个实例。“默认”必须有明确依据。 + +区分结构层和语义层。EBNF 能表达某个参数存在，不自动说明它的含义、范围和权限。同样，文字声称允许多个声明时，产生式也应允许；两者冲突时不能只改示例使检查通过。 + +对尚未定义的范围，不写“任意”“始终”“自动”“所有”这类全称断言。例如，简单用户名样例不证明全部用户名只能包含小写字母；namespace 层级不自动决定访问继承。 + +## Preflight 与 inflight 的表达 + +参数数量不符等可静态判断的问题，可依现有提案说明为 Preflight 诊断。调用执行中的数据缺失属于 inflight 情况。错误文本、错误码和捕获语法未确定时，只说明可观察问题和已有规则，不虚构诊断输出。 + +“第二次调用需要第一次的结果”表达数据依赖；“所有参数严格从左到右执行”是额外的求值顺序规则。前者不能推出后者。普通调用也不能推出自动重试、缓存一致性或无副作用。 + +## 状态影响最小示例时 + +优先选用已经写明的形式。若目标就是介绍读取提案，则给出提案状态、成员假设和成功路径；把未知的失败处理写成自然语言边界。不得为了演示成功路径而暗示失败时会得到零值。 + +如果关键声明根本不存在，不能把完整源码标成可运行。可以提供明确的局部片段或概念用法，并列出缺少的语言决定。 + +## 写作完成后的双向核对 + +从每条文字规则找到支持它的形式或例子；再从例子中的每个名称、调用和关键效果回到规则或明确假设。 + +例如 `use alice:shop.pricing` 支持“完整 key”这一形式，但不证明所有成员自动进入作用域。跨 namespace 调用例子还需说明目标可见、无名称冲突的局部条件。 + +核对详情记录在[TPL-05 变更工作单](../templates/TPL-05.md)即可，不必把作者的所有分析附在读者正文中。 + +[语言核对地图](language-map.md) · [参考成稿示例](../examples/EX-02.md) · [DOC-013](../rules/DOC-013.md) + diff --git a/authoring/rules/DOC-001.md b/authoring/rules/DOC-001.md index b2d659c..d427d3b 100644 --- a/authoring/rules/DOC-001.md +++ b/authoring/rules/DOC-001.md @@ -30,6 +30,12 @@ - [ ] 页面能对应至少一个具体阅读目标。 - [ ] 没有默认读者理解团队内部代称。 +## 具体应用 + +用“已有知识 → 当前情境 → 读完能作出的判断”写页面目标，例子必须服务这个判断。若目标只能写成“了解更多”，先拆出具体问题再写提纲。 + +详见[信息架构](../references/information-architecture.md)与[身份指南](../examples/EX-01.md)。 + ## 依据与边界 [SRC-15](../research/SRC-15.md)、[SRC-14](../research/SRC-14.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-002.md b/authoring/rules/DOC-002.md index f05dad3..3ef762c 100644 --- a/authoring/rules/DOC-002.md +++ b/authoring/rules/DOC-002.md @@ -30,6 +30,12 @@ - [ ] 标题与正文职责一致。 - [ ] 无需为了分类创建没有内容的四套目录。 +## 具体应用 + +根据读者是在学习、完成任务、查询精确规则还是理解原因选择页面职责。混合页只有在辅助内容不妨碍主任务时才保留；目录分类不要求四套内容都存在。 + +详见[指南任务](../tasks/TASK-02.md)与[模板选择](../templates/README.md)。 + ## 依据与边界 [SRC-14](../research/SRC-14.md)、[SRC-11](../research/SRC-11.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-003.md b/authoring/rules/DOC-003.md index d76f12f..c52c7ed 100644 --- a/authoring/rules/DOC-003.md +++ b/authoring/rules/DOC-003.md @@ -30,6 +30,12 @@ - [ ] 读者知道从哪里继续。 - [ ] 概览没有变成全部规范的重复摘要。 +## 具体应用 + +首页第一段建立对象与用途，随后给适用读者、当前文档性质和开始阅读路径。主要细节链接到章节，不能把所有作者约束堆到入口。 + +详见[指南任务](../tasks/TASK-02.md)与[入口与信息位置](../references/information-architecture.md)。 + ## 依据与边界 [SRC-01](../research/SRC-01.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-004.md b/authoring/rules/DOC-004.md index a8aeefd..9ed6d93 100644 --- a/authoring/rules/DOC-004.md +++ b/authoring/rules/DOC-004.md @@ -30,6 +30,12 @@ - [ ] 涉及的名称有声明、前提或明确占位说明。 - [ ] 没有虚构安装命令或运行入口。 +## 具体应用 + +从例子里的每个名称倒查所需声明与概念，将影响合法性的条件放到使用点。全书已经介绍的背景可以短链接，直接跳入仍须看见局部假设。 + +详见[示例条件](../references/example-design.md)与[调用示范](../examples/EX-03.md)。 + ## 依据与边界 [SRC-04](../research/SRC-04.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-005.md b/authoring/rules/DOC-005.md index 13f4b0c..9172522 100644 --- a/authoring/rules/DOC-005.md +++ b/authoring/rules/DOC-005.md @@ -30,6 +30,12 @@ - [ ] 重要术语在正式使用前已定义或链接。 - [ ] 目录调整没有改变语言语义。 +## 具体应用 + +列出主题的理解前提，再为每条目录路径走查；预览允许先出现，但正式解释必须能回到定义。移动时保留旧内容到新位置的映射。 + +详见[依赖与目录](../references/information-architecture.md)与[重组示范](../examples/EX-05.md)。 + ## 依据与边界 [SRC-03](../research/SRC-03.md)、[SRC-09](../research/SRC-09.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-006.md b/authoring/rules/DOC-006.md index f52d201..11d1792 100644 --- a/authoring/rules/DOC-006.md +++ b/authoring/rules/DOC-006.md @@ -30,6 +30,12 @@ - [ ] 拆分页仍可独立阅读。 - [ ] 没有仅因字数达到阈值而拆分。 +## 具体应用 + +依据独立的读者问题、修改范围和查询需求决定分页。只有行数长不够成为拆分理由；拆开后必须来回跳转才能理解的最小规则应保持在一起。 + +详见[重组任务](../tasks/TASK-05.md)与[拆分与合并](../references/information-architecture.md)。 + ## 依据与边界 [SRC-09](../research/SRC-09.md)、[SRC-14](../research/SRC-14.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-007.md b/authoring/rules/DOC-007.md index 2f935e6..e387c92 100644 --- a/authoring/rules/DOC-007.md +++ b/authoring/rules/DOC-007.md @@ -30,6 +30,12 @@ - [ ] 指定术语能定位到主要定义。 - [ ] 作者资料不会混入语言学习主线。 +## 具体应用 + +分别走查首页顺读、搜索直达和返回主定义三种路径。直接进入者需要一句局部上下文，而非完整复制前章；链接文字须能说明目标。 + +详见[三种入口](../references/information-architecture.md)与[定位验收](../references/review-rubric.md)。 + ## 依据与边界 [SRC-01](../research/SRC-01.md)、[SRC-07](../research/SRC-07.md)、[SRC-08](../research/SRC-08.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-008.md b/authoring/rules/DOC-008.md index 5940494..210d74a 100644 --- a/authoring/rules/DOC-008.md +++ b/authoring/rules/DOC-008.md @@ -30,6 +30,12 @@ - [ ] 定义页可定位。 - [ ] 相同规则没有多份相互矛盾的权威描述。 +## 具体应用 + +为一个概念选择真实的主要定义，并让示例、索引和参考指向它。稳定编号是身份，文件排序和显示标题可以改变；迁移后检查引用实际支持的断言。 + +详见[定义迁移](../tasks/TASK-05.md)与[精确参考](../tasks/TASK-03.md)。 + ## 依据与边界 [SRC-02](../research/SRC-02.md)、[SRC-09](../research/SRC-09.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-009.md b/authoring/rules/DOC-009.md index 5442313..342bb01 100644 --- a/authoring/rules/DOC-009.md +++ b/authoring/rules/DOC-009.md @@ -30,6 +30,12 @@ - [ ] 占位符没有冒充实际 API。 - [ ] 示例标签与验证等级一致。 +## 具体应用 + +先选择概念、源码片段、逻辑视图或实际执行等级，再填写归属、位置和依赖条件。最小示例可以很短，但其中每个名称都需要声明或明确假设。 + +详见[示例等级](../references/example-design.md)与[完整上下文](../examples/EX-03.md)。 + ## 依据与边界 [SRC-04](../research/SRC-04.md)、[SRC-08](../research/SRC-08.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-010.md b/authoring/rules/DOC-010.md index bd157fc..9807c4e 100644 --- a/authoring/rules/DOC-010.md +++ b/authoring/rules/DOC-010.md @@ -30,6 +30,12 @@ - [ ] 结果与源码计算一致。 - [ ] 效果说明没有被误标为执行日志。 +## 具体应用 + +用确定输入推演关键中间结果和最终效果，然后解释数据或结构关系。报告预期结果与实际运行证据分别成立，源码旁不能省掉影响结果的条件。 + +详见[结果验证](../references/example-design.md)与[90 与 85 的推演](../examples/EX-03.md)。 + ## 依据与边界 [SRC-01](../research/SRC-01.md)、[SRC-02](../research/SRC-02.md)、[SRC-03](../research/SRC-03.md)、[SRC-04](../research/SRC-04.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-011.md b/authoring/rules/DOC-011.md index ec5e32c..1b2404c 100644 --- a/authoring/rules/DOC-011.md +++ b/authoring/rules/DOC-011.md @@ -30,6 +30,12 @@ - [ ] 新增概念有对应解释。 - [ ] 一致场景不会强制所有专业例子使用商品。 +## 具体应用 + +第二个例子改变一个有意义的条件，例如层级或后续调用。新增概念需要已有定义或短前提；不要为极简删除依赖声明，也不要堆进未定义的完整应用。 + +详见[递进判断](../references/example-design.md)与[示例任务](../tasks/TASK-04.md)。 + ## 依据与边界 [SRC-05](../research/SRC-05.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-012.md b/authoring/rules/DOC-012.md index a5dab14..f5dfb7b 100644 --- a/authoring/rules/DOC-012.md +++ b/authoring/rules/DOC-012.md @@ -30,6 +30,12 @@ - [ ] 没有把所有失败称为语法错误。 - [ ] 未定处理语法仍保持未定。 +## 具体应用 + +选择读者容易违反的具体约束，按原因、可观察问题和最小修正解释。尚未规定的错误码与捕获语法保持未定；有意反例使用明确无效的 text 围栏。 + +详见[边界与阶段](../references/semantic-contracts.md)与[反例安排](../tasks/TASK-04.md)。 + ## 依据与边界 [SRC-02](../research/SRC-02.md)、[SRC-05](../research/SRC-05.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-013.md b/authoring/rules/DOC-013.md index 252f999..637572a 100644 --- a/authoring/rules/DOC-013.md +++ b/authoring/rules/DOC-013.md @@ -30,6 +30,12 @@ - [ ] 有可检查的效果。 - [ ] 没有用底层机制替代语言契约。 +## 具体应用 + +逐项说明形式、输入、结果、依赖、效果和必要的阶段边界；字段根据对象选择。use 应说明引用效果，不强填函数返回值；组件应说明子节点和排列。 + +详见[契约字段](../references/semantic-contracts.md)与[导入参考](../examples/EX-02.md)。 + ## 依据与边界 [SRC-02](../research/SRC-02.md)、[SRC-06](../research/SRC-06.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-014.md b/authoring/rules/DOC-014.md index 57ccc15..a9c0fde 100644 --- a/authoring/rules/DOC-014.md +++ b/authoring/rules/DOC-014.md @@ -30,6 +30,12 @@ - [ ] 读者知道差异是否影响用法。 - [ ] 没有为了比较而创造不存在的第二套 API。 +## 具体应用 + +只比较真实存在的对象，并用相同情境或输入建立共同维度。选择理由必须对应读者的任务；未定设计比较保持候选身份，不能凭表格整齐引入第二套语法。 + +详见[解释与比较模板](../templates/TPL-04.md)与[页面职责](../references/information-architecture.md)。 + ## 依据与边界 [SRC-05](../research/SRC-05.md)、[SRC-06](../research/SRC-06.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-015.md b/authoring/rules/DOC-015.md index d93886d..0e57d65 100644 --- a/authoring/rules/DOC-015.md +++ b/authoring/rules/DOC-015.md @@ -30,6 +30,12 @@ - [ ] 没有新增未经确认的强制规则。 - [ ] 同一状态声明不在每节重复。 +## 具体应用 + +先读主要定义与规范状态，再检查全称词、默认值和示例成员。用户明确的新决定应落实准确范围，草案中仍未决定的签名、失败和权限不随之自动确定。 + +详见[断言依据](../references/language-map.md)与[决定与状态同步](../tasks/TASK-06.md)。 + ## 依据与边界 [SRC-02](../research/SRC-02.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-016.md b/authoring/rules/DOC-016.md index 7d3cdfb..8fe9d48 100644 --- a/authoring/rules/DOC-016.md +++ b/authoring/rules/DOC-016.md @@ -30,6 +30,12 @@ - [ ] 实现选择没有伪装成语法限制。 - [ ] 必要的存储说明限定在代码组织范围。 +## 具体应用 + +描述代码输入、结果和可观察业务效果，而不把通信客户端、自动建表或缓存实现写成当前语言要求。系统实现的观测事实与语言决定分别记录。 + +详见[语言契约](../references/semantic-contracts.md)与[项目易错推断](../references/language-map.md)。 + ## 依据与边界 [SRC-06](../research/SRC-06.md)、[SRC-11](../research/SRC-11.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-017.md b/authoring/rules/DOC-017.md index 2f18c85..f612936 100644 --- a/authoring/rules/DOC-017.md +++ b/authoring/rules/DOC-017.md @@ -30,6 +30,12 @@ - [ ] 源码展示没有混入非源码标签。 - [ ] 记法适用于从其他页面跳入的读者。 +## 具体应用 + +检查正文、源码、标题、表格、链接文字和结果说明中的同一词。源码大小写与符号不能被中文排版替换；简称不自动成为正式更名请求。 + +详见[术语与标点](../references/chinese-style.md)与[局部修改](../tasks/TASK-01.md)。 + ## 依据与边界 [SRC-08](../research/SRC-08.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-018.md b/authoring/rules/DOC-018.md index b8a8a71..e258819 100644 --- a/authoring/rules/DOC-018.md +++ b/authoring/rules/DOC-018.md @@ -30,6 +30,12 @@ - [ ] 代词指向明确。 - [ ] 使用第二人称教学指令本身不被误判为问题。 +## 具体应用 + +先提取原稿真正表达的断言，再写对象、行为、条件与后果。保留必要概念，删除必须依赖聊天才能理解的指代；合理的教程第二人称可保留。 + +详见[独立陈述](../references/chinese-style.md)与[完整改写](../examples/EX-01.md)。 + ## 依据与边界 [SRC-11](../research/SRC-11.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-019.md b/authoring/rules/DOC-019.md index a4a0b91..49b21c0 100644 --- a/authoring/rules/DOC-019.md +++ b/authoring/rules/DOC-019.md @@ -30,6 +30,12 @@ - [ ] 源码可复制，结构示意不冒充源码。 - [ ] Markdown 标题、列表与代码块正确闭合。 +## 具体应用 + +重复字段用表格、步骤用列表、连续论证用段落。格式选择应帮助识别关系；每个提示只保留影响使用的重要条件，不追求固定标题数量。 + +详见[格式判断](../references/chinese-style.md)与[读者影响](../references/review-rubric.md)。 + ## 依据与边界 [SRC-03](../research/SRC-03.md)、[SRC-06](../research/SRC-06.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-020.md b/authoring/rules/DOC-020.md index a4a5f82..8d3d2eb 100644 --- a/authoring/rules/DOC-020.md +++ b/authoring/rules/DOC-020.md @@ -30,6 +30,12 @@ - [ ] 推断明确标记。 - [ ] 无把搜索摘要冒充完整阅读的情况。 +## 具体应用 + +从原页记录做法，再写作用分析和项目采用范围；三者不能互相替代。未取得正文时保留编号与状态，继续能完成的研究，不归纳未见观点。 + +详见[来源处理](../tasks/TASK-08.md)与[不可读来源场景](../evaluation/scenarios.md)。 + ## 依据与边界 本项目的来源核查流程；未读材料的处理记录见 [SRC-10](../research/SRC-10.md)、[SRC-12](../research/SRC-12.md)、[SRC-13](../research/SRC-13.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-021.md b/authoring/rules/DOC-021.md index 58abc94..efd20e7 100644 --- a/authoring/rules/DOC-021.md +++ b/authoring/rules/DOC-021.md @@ -13,7 +13,7 @@ ## 执行方法 1. 修改前找出主定义和引用位置，编辑后复查影响范围。 -2. 运行链接、锚点、代码块、编号和格式检查；按风险检查例子与计算。 +2. 人工核对链接、锚点、代码块、编号和格式；按风险检查例子与计算。程序检查仅在用户明确要求执行时运行。 3. 报告实际检查等级、未执行步骤与失败；工具通过不等于语言运行验证。 ## 改写对照 @@ -30,6 +30,12 @@ - [ ] 命令和结果可复现。 - [ ] 报告没有把静态检查称为编译或运行测试。 +## 具体应用 + +根据本次断言与对象列出影响页，搜索词形和近义主张。修正后从主定义、文法、状态与例子双向核对，并记录相关读者任务的实际结果。 + +详见[影响范围](../tasks/TASK-06.md)与[工作记录](../templates/TPL-05.md)。 + ## 依据与边界 [SRC-07](../research/SRC-07.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-022.md b/authoring/rules/DOC-022.md index f3e1a04..b7917e5 100644 --- a/authoring/rules/DOC-022.md +++ b/authoring/rules/DOC-022.md @@ -30,6 +30,12 @@ - [ ] 工具无本机绝对路径。 - [ ] 提交和推送状态有记录，权限不足不换用 owner 凭据。 +## 具体应用 + +让入口、任务索引、相对引用和必要主定义可从仓库重新取得。独立 skill 包携带写作资源，真实写作仍读取目标语言仓库；不要复制某台电脑的凭据或会话配置。 + +详见[跨电脑使用](../skill-usage.md)与[手册维护](../tasks/TASK-08.md)。 + ## 依据与边界 [SRC-11](../research/SRC-11.md)、[SRC-07](../research/SRC-07.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-023.md b/authoring/rules/DOC-023.md index 32ced61..439bdc6 100644 --- a/authoring/rules/DOC-023.md +++ b/authoring/rules/DOC-023.md @@ -30,6 +30,12 @@ - [ ] 改动说明含适用规则与验证。 - [ ] 作者身份不影响语义确认要求。 +## 具体应用 + +人工与 AI 都要交付有依据的成稿或可实施发现。审查-only 保留文件，修复任务完成相关修改；已获授权无需重复请求，但新语义仍需准确依据。 + +详见[统一任务入口](../SKILL.md)与[审查边界](../tasks/TASK-07.md)。 + ## 依据与边界 [SRC-07](../research/SRC-07.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/rules/DOC-024.md b/authoring/rules/DOC-024.md index 86a3385..c68aec5 100644 --- a/authoring/rules/DOC-024.md +++ b/authoring/rules/DOC-024.md @@ -30,6 +30,12 @@ - [ ] 发现的理解障碍有具体位置。 - [ ] 没有把作者自查冒充真实用户测试。 +## 具体应用 + +选择相关的复述、定位或预测任务，记录实际卡住的位置。作者走查、独立代理评估和真人测试分别报告；质量不能由链接数量或规则命中数推断。 + +详见[验收标准](../references/review-rubric.md)与[行为评估](../evaluation/scenarios.md)。 + ## 依据与边界 [SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。 diff --git a/authoring/skill-usage.md b/authoring/skill-usage.md new file mode 100644 index 0000000..1dbda1a --- /dev/null +++ b/authoring/skill-usage.md @@ -0,0 +1,39 @@ +# Skill 使用与跨电脑接续 + +本手册同时是名为 `endor-docs` 的 skill 包。[SKILL.md](SKILL.md)是机器入口，[README.md](README.md)是人工查阅入口，两者使用同一组任务页、规则、方法与示例。查询与使用通过 Markdown 完成。 + +## 每次开始写作 + +先读目标仓库的 AGENTS.md 和本 skill 入口，从八类任务中选择主任务，再选择必要补充任务。打开任务页的必读方法、DOC 规则和案例，结合[语言核对地图](references/language-map.md)找到本次主题的主定义与规范状态。 + +例如，“完善函数章节并补例子”使用 guide + example；“只检查一篇草稿的问题”使用 review；“统一已经确认的 use 写法”同时涉及 semantics + example。记录所选路线与实际读到的依据即可，不需另外执行查询程序。 + +表格是起点。若写作中发现会改变规则的词句，补充语义路线；若出现章节移动，补充结构路线。每个任务页解释选择条件和完成标准。 + +## 项目级入口 + +仓库的 `.agents/skills/endor-docs` 是指向 `authoring` 的相对符号链接，避免维护两份手册。支持项目 skill 发现的客户端可以读取该入口；当前会话的 skill 列表是否刷新由客户端决定，不把文件创建成功称为自动加载已经验证。 + +无论客户端是否发现 skill，仓库 AGENTS.md 都要求文档任务读取 authoring/SKILL.md 并选择路线。也可以直接请求“按 authoring/SKILL.md 修改函数章节”。 + +## 换电脑 + +完整克隆本仓库可以同时获得语言文档、手册与维护约定。阅读和编写手册不需要 Python 或其他程序环境。 + +若检出环境不能保留符号链接，直接通过 AGENTS.md 读取 authoring/SKILL.md；不要把符号链接的文本文件误当作目录。若希望单独安装，可将 authoring 目录作为一个完整包放入支持的 skill 目录，目录名使用 endor-docs，保留内部相对结构。 + +独立安装时先明确语言文档仓库的位置。手册包中的规则、方法和案例可独立阅读；真实写作需读取目标仓库的 AGENTS.md、语言正文和状态。实际语言定义始终由目标仓库维护，不能拿手册快照代替当前主定义。 + +## 执行权限 + +默认只阅读和编辑文件，人工核对规则、链接、例子和关联页面。只有用户明确要求执行代码时才运行程序、脚本、测试、构建或安装；skill 本身、已有检查工具和“完成验证”目标都不授予执行权限。 + +用户明确要求的 Git commit 和 push 可以按该授权执行，操作限于必要 Git 流程，不附带启动测试或项目 hook。未进行自动检查时如实记录，不能把人工核对写成自动通过。 + +## 使用边界 + +文档站点一般通过 authoring 路径访问，符号链接仅用于 skill 发现。手册中的“文件、章节、仓库”指文档维护载体，不引入语言源码文件模块。 + +本 skill 不绑定某台电脑、网络服务或模型。来源研究页只在查证写作方法时加载；源码示例需要的语言条件由相关页面明确说明。 + +[手册入口](README.md) diff --git a/authoring/tasks/TASK-01.md b/authoring/tasks/TASK-01.md new file mode 100644 index 0000000..8d7815a --- /dev/null +++ b/authoring/tasks/TASK-01.md @@ -0,0 +1,31 @@ +# TASK-01 局部修改 + +适用：错字、术语、链接、句子清晰度，以及不改变规则的短段修订。输出是范围明确的修正及必要的关联更新。 + +必读：[DOC-017](../rules/DOC-017.md)、[DOC-021](../rules/DOC-021.md)。涉及句子重写时查[中文表达](../references/chinese-style.md)。 + +## 先判断是否真是局部修改 + +| 表面请求 | 实际判断 | +| --- | --- | +| 把阶段名称统一大小写 | 查主定义后替换相关术语，保留代码中不同含义的普通名称 | +| 把“可以”改为“必须” | 可能改变语义，转 TASK-06 | +| 修正一个坏链接 | 找到原链接应支持的定义，不能只链接任意存在的页 | +| 把所有同名文本替换掉 | 先区分正文、源码、URL、引用、历史记录与有意反例 | +| 简化一段“太啰嗦”的说明 | 保留影响合法性、提案状态和结果的必要条件 | + +## 执行 + +阅读目标段落及其前后小节，找到术语或行为的主定义。用编辑器的全文搜索查看同一问题在正文、附录与手册中的出现位置；命中项逐一判断，不自动全替换。 + +修正文句时先写出原句要表达的断言，再用更直接的句子表达。若断言本身不清楚，不能只润色后继续保留。链接变更检查目标锚点是否仍说明原来的主题。 + +修正后比较语义强度、范围、条件和例外是否改变。只改措辞时，不顺手移动整章或改写其他正确例子。 + +## 验收与常见误判 + +全文检索用于确认相同错误残留，不要求所有相似字符串消失。例如手册中明确标注的错误写法可以保留；来源原题、历史提交名不属于语言术语迁移。 + +人工核对结构、链接目标与修改前后断言；程序检查仅在用户明确要求时执行。交付说明改动词句的用途、关联更新及是否涉及语义。 + +[任务入口](../SKILL.md) diff --git a/authoring/tasks/TASK-02.md b/authoring/tasks/TASK-02.md new file mode 100644 index 0000000..46059fe --- /dev/null +++ b/authoring/tasks/TASK-02.md @@ -0,0 +1,45 @@ +# TASK-02 新增或深化指南 + +适用：新章节、首页介绍、补全一个概念，或将对话式草稿改成可顺序阅读的指南。 + +必读：[信息架构](../references/information-architecture.md)、[中文表达](../references/chinese-style.md)、[DOC-001](../rules/DOC-001.md)、[DOC-002](../rules/DOC-002.md)、[DOC-004](../rules/DOC-004.md)、[DOC-005](../rules/DOC-005.md)、[DOC-015](../rules/DOC-015.md)。模板按用途选择 [TPL-01](../templates/TPL-01.md)、[TPL-02](../templates/TPL-02.md)或[TPL-04](../templates/TPL-04.md)。 + +## 从“详细写一下”到明确的学习目标 + +把主题拆成读者需要作出的判断。例如用户身份章节可让读者： + +- 分辨 handle 和显示名，知道哪个进入 key。 +- 从同名路径识别不同用户的 namespace。 +- 区分归属用户、操作用户和作者。 +- 理解定位与访问权限的关系。 + +这些目标导出内容深度。账号认证协议、数据库身份表等不由“详细”一词自动纳入。 + +## 构建提纲 + +先列已知概念和必要前提，再按理解关系组织标题。首段定义对象与职责；最早的例子建立基本模型；后续例子分别解释常见混淆；局部边界回答会影响使用的问题。 + +为每个拟写小节标注它回答的读者问题。只有“更多介绍”而没有问题的小节，先改提纲。每个小节至少贡献一个新的定义、区别、结果或判断条件。 + +选择页面职责：概念介绍强调理解；任务指南强调起点、步骤和结果；解释页强调关系与理由。没有可执行环境时，任务用法可作为逻辑说明，但不能编造安装与启动流程。 + +## 先写成稿，再检查模板 + +用模板组织草稿，但不要把“定义：”“规则：”“原因：”全作为正文标签。让段落自然连接，关键对比才使用表格。代码例子另按 TASK-04 处理。 + +入口页需要说清语言是什么、适合解决什么问题、目前文档性质、怎么开始读；不能用十几条约定替代介绍，也不能把所有细节塞进首页。 + +## 深度检查 + +对每个重要概念问：它和相邻概念有什么区别？读者会在哪里误解？能用什么小例子看出区别？这个例子的边界是什么？ + +“更多细节”应增加可判断的信息。重复“唯一、统一、自动、简单”不能增加深度。未定义的语言规则以具体缺口说明，不用新增能力填充篇幅。 + +## 验收 + +执行复述与定位任务。读者应能根据本页解释一个例子，并找到精确规则；新增页必须有入口、前提和后续路径。 + +成稿示范见[EX-01](../examples/EX-01.md)。若改变章节位置，同时执行 TASK-05；若发现需要确认新语义，按 TASK-06 处理受影响部分。 + +[任务入口](../SKILL.md) + diff --git a/authoring/tasks/TASK-03.md b/authoring/tasks/TASK-03.md new file mode 100644 index 0000000..f52d5cf --- /dev/null +++ b/authoring/tasks/TASK-03.md @@ -0,0 +1,43 @@ +# TASK-03 编写语法与 API 参考 + +适用：声明、表达式、关键字、函数或 UI 组件的精确查询页。读者已有目标，需要判断形式、输入、约束和效果。 + +必读：[语义契约](../references/semantic-contracts.md)、[语言核对地图](../references/language-map.md)、[DOC-008](../rules/DOC-008.md)、[DOC-012](../rules/DOC-012.md)、[DOC-013](../rules/DOC-013.md)、[DOC-015](../rules/DOC-015.md)。使用[TPL-03](../templates/TPL-03.md)。 + +## 先收集规则依据 + +列出对象的主定义、形式文法、规范状态和现有例子。对每个准备加入的字段写出依据。当前没定义默认值就写未定义，不凭常见库经验补一个合理值。 + +若一页既承担教学又承担查询，开头可以保留最小定义，参考小节应能独立找到。避免先读十段设计理由才能看到形式。 + +## 根据对象选择字段 + +| 对象 | 重点字段 | 不应硬填 | +| --- | --- | --- | +| use | 完整 key、位置、引用作用、名称可见性条件 | 函数式返回值 | +| function | 参数与结果、函数体形式、类型与依赖 | 未定义的 async 或异常关键字 | +| class | 字段、类型、已有结构约束 | 自动构造方法、get、持久化规则 | +| UI 组件 | 参数、子节点、排列与已知默认值 | 未规定的 CSS 单位或事件系统 | + +参数有名称、类型、意义、默认值与范围时可以制表。只知道其中部分就保留真实信息，说明未定的关键项；表格整齐不是补造 API 的理由。 + +## 核对形式与语义 + +从文本到文法：可选、重复、数量、顺序是否有对应形式？从文法到文本：每个公开结构是否有含义、条件和结果说明？ + +不复制一整套 EBNF 到每页。正文可展示阅读友好的基本形式，精确产生式链接集中附录。需要修正文法时更新它，并检索受影响的例子与状态。 + +## 正例与边界 + +提供一个最小正例，解释其外部上下文。再选择一项最容易误解的边界。例如 use 的 key 与所属 key 不同；导入不等于获得访问权限。 + +错误示例说明违反哪条约束以及怎样修正。错误码、错误文本尚未定义时不模拟实现输出。 + +## 验收 + +让读者从页中直接找到：在哪里写、怎样写、输入要求、成功效果、关键边界和状态。不能必须返回聊天记录才能知道哪个字段只是提案。 + +完整成稿与写作说明见[EX-02](../examples/EX-02.md)。 + +[任务入口](../SKILL.md) + diff --git a/authoring/tasks/TASK-04.md b/authoring/tasks/TASK-04.md new file mode 100644 index 0000000..e1636f5 --- /dev/null +++ b/authoring/tasks/TASK-04.md @@ -0,0 +1,37 @@ +# TASK-04 新增与修复示例 + +适用：补充例子、统一例子风格、修复过时写法、解释结果，或检查示例是否表达了错误语义。 + +必读：[示例设计](../references/example-design.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-015](../rules/DOC-015.md)。 + +## 盘点已有例子 + +先搜索代码围栏及相关名称，再阅读文字条件。盘点对象包括正文、文法说明、表格中的短例子和手册中的示范；不要只查 endorphin 围栏。 + +将命中项分成正例、明确无效的反例、形式文法、来源原样名称和历史记录。修复错误时只改需要同步的类别；有意反例应继续展示错误及原因。 + +## 设计最小完整例子 + +确定读者目标与示例等级。为目标准备最少的声明和输入，明确代码归属。跨 namespace 示例分别写出提供方和使用方归属，避免读者把 use 的目标当作当前归属。 + +每个名称都能回到声明或局部假设。省略依赖时说明省略什么和为何可省略；尚未定义的官方引用不能被用户库导入掩盖。 + +## 解释结果 + +数值给输入、结果和关键中间值；UI 给可见内容、排列及必要前提；身份/key 给对象之间相同或不同的关系。 + +“代码很清晰”不替代解释。说明为什么第二次调用依赖第一次结果，比逐行说“这里调用函数”更有价值。已有规则无法决定结果时，说明缺少的条件。 + +## 修复时的联动 + +改变函数签名要检查调用点和返回说明；改变名字要检查代码外叙述；改变输入要重算所有结果；改变归属要检查 use；改变状态要同步局部提案说明与规范状态。 + +不把修复示例当成设计新能力的机会。改用一个已定义的更小例子，通常优于虚构构造器、导入路径或数据接口。 + +## 验收 + +按文档规则逐步推演，并选一个针对性变化检验解释是否仍成立。只有用户明确要求执行代码时才运行相关工具。交付区分手算、人工结构核对和实际执行。 + +完整多 namespace 示例及其验收见[EX-03](../examples/EX-03.md)。 + +[任务入口](../SKILL.md) diff --git a/authoring/tasks/TASK-05.md b/authoring/tasks/TASK-05.md new file mode 100644 index 0000000..65a7d02 --- /dev/null +++ b/authoring/tasks/TASK-05.md @@ -0,0 +1,38 @@ +# TASK-05 重组章节与导航 + +适用：整本书逻辑不连贯、单章过长、定义重复、分章粒度不合适或检索困难。 + +必读：[信息架构](../references/information-architecture.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-021](../rules/DOC-021.md)、[DOC-024](../rules/DOC-024.md)。 + +## 找出具体结构问题 + +为现有小节标注读者问题、前提和主定义。找出四种情况：使用早于定义；同一规则有多个版本；一页混合不同读者任务；某页只能靠聊天解释。 + +标题数量或文件行数只能提示风险，不能决定拆分。先用一个读者任务走查现有路径，记录卡住的位置。 + +## 设计目标结构 + +保持清楚的学习主线，并给术语、语法和任务查询入口。目录标题应能说明内容，不要求所有分支数量对称。 + +为移动内容制作映射表：原路径/小节、目标路径/小节、保留的主定义、需要更新的引用。示范见[EX-05](../examples/EX-05.md)。文件名和 DOC/SRC/TPL 稳定 ID 分开处理；移动规则不能重用已存在的编号。 + +## 实施顺序 + +先建立目标页的职责与内容，再更新入站链接、目录与相邻导航，最后处理原页。移动时保留重要约束和局部假设，不因归入附录就删除读者使用时需要的提示。 + +用户要求实际移动文件时选择符合版本控制的操作，检查已有未提交修改。站外分享链接可能无法全量检索；需要保留兼容入口的情况，应明确记录实际措施与未覆盖范围。 + +## 交叉检查 + +正文编号、首页目录、上一章/下一章、术语索引、规范状态、文法链接和作者手册引用都可能受影响。用旧路径及旧标题搜索引用，核对每一类命中。 + +结构重组原则上不更改语言断言；发现矛盾时记录并按 TASK-06 处理，而不是将某一版本悄悄消失。 + +## 验收 + +从首页顺读、从术语跳入、从引用返回主定义，各走一条与本次修改相关的路径。新位置能独立说明主题，旧引用没有指向错误内容。 + +交付映射和理由，说明新增、移动、合并或删除的文件以及相应导航更新。 + +[任务入口](../SKILL.md) + diff --git a/authoring/tasks/TASK-06.md b/authoring/tasks/TASK-06.md new file mode 100644 index 0000000..656b283 --- /dev/null +++ b/authoring/tasks/TASK-06.md @@ -0,0 +1,38 @@ +# TASK-06 落实语言决定与修复语义矛盾 + +适用：用户明确改变语言规则、确定某项提案、要求全库统一写法，或文档出现相互冲突的断言。 + +必读：[语言核对地图](../references/language-map.md)、[语义契约](../references/semantic-contracts.md)、[DOC-013](../rules/DOC-013.md)、[DOC-015](../rules/DOC-015.md)、[DOC-016](../rules/DOC-016.md)、[DOC-021](../rules/DOC-021.md)。可用[TPL-05](../templates/TPL-05.md)记录影响。 + +## 确定决定的准确边界 + +用一句话复述已获得的决定，列出它改变的断言和没有随之确定的维度。例如“use 使用 alice:shop.ui”确定用户与路径的分隔形式；不会同时确定用户名字符集、别名或冲突规则。 + +若用户只是要求解释得更清楚，先按现有规则改善文档。无法决定的新增语义保持具体未定状态，完成独立部分；仅当目标确实依赖新决定时请求最小必要澄清。 + +## 搜索影响面 + +| 改动类型 | 必查范围 | +| --- | --- | +| key 或 use 形式 | 身份、namespace、程序结构、调用示例、文法、术语和作者示范 | +| 阶段职责 | 阶段章、函数/数据/UI行为、术语、例子中的时机描述 | +| 函数或类结构 | 类型、表达式、调用、数据、相关产生式和所有调用点 | +| 官方组件来源 | UI 例子、程序结构说明、状态以及例子的导入条件 | +| 名称与术语 | 标题、正文、源码围栏、索引、链接文字；外部 URL 单独判断 | + +先查固定旧写法，再查概念近义表述。纯字符串替换找不到“导入自动赋予访问权”这样的语义残留。 + +## 修改顺序 + +更新主要定义和明确受影响的状态，再同步形式文法和使用例子，随后更新术语、导航及作者资料。语法提案内部修订仍是提案；只有明确确认才改变状态。 + +为每个关键变化给一个前后对照，说明合法性或效果变化。反例可以保留旧写法并解释其错误；历史记录与外部来源不为了零命中被篡改。 + +## 完成条件 + +从规范、形式、例子三个方向核对一致性。保留用户决定的出处说明或任务记录，使后来作者能知道为何改变。无需将聊天全文塞入语言正文。 + +若发现已有规则互相冲突却没有决定依据，交付具体冲突与候选影响，不能凭写作偏好确认语义。 + +[任务入口](../SKILL.md) + diff --git a/authoring/tasks/TASK-07.md b/authoring/tasks/TASK-07.md new file mode 100644 index 0000000..06e8d20 --- /dev/null +++ b/authoring/tasks/TASK-07.md @@ -0,0 +1,34 @@ +# TASK-07 审查文档 + +适用：检查质量、解释为什么难读、评审新章节或查找全书不一致。审查请求默认产出问题与建议；有修复授权时继续实施。 + +必读：[审查标准](../references/review-rubric.md)、[DOC-015](../rules/DOC-015.md)、[DOC-021](../rules/DOC-021.md)、[DOC-024](../rules/DOC-024.md)。报告可用[TPL-06](../templates/TPL-06.md)。 + +## 先确定审查范围 + +记录目标页、相关主定义和预期读者。全书审查可先根据风险覆盖关键路径：语言定位、归属与导入、阶段、调用、数据、UI；对抽样范围作实际说明，不能将抽样称为逐页审查。 + +只查格式的任务可以限制在格式范围。语义审查需要读取规范状态及相关主定义，不能仅依据常见编程语言经验判断。 + +## 三遍阅读 + +第一遍作为新读者，尝试复述对象、作用和主要例子。第二遍按断言核对依据、状态、例子和文法。第三遍追踪跨页依赖、目录和局部条件。 + +每次发现问题先尝试最小修正思路。若问题实际来自未确定设计，将其标成设计缺口；若是文档把未知写成已知，则是确定的文档缺陷。 + +## 形成可执行发现 + +记录具体位置与原文主张，说明读者会得到什么错误理解，以及最小修正。按阻断、重要、改进排序，合并同源重复项但列出受影响位置。 + +例如：“函数页只展示 use 而没有被调用函数的定义，读者无法推导金额；补充声明或指向声明并写出输入与结果。”比“示例不够完整”可操作。 + +正面观察只有在说明哪些内容可保留时才有价值。没有发现实质问题就如实报告范围与剩余未验证项，不创造风格缺陷。 + +## 验收与交付 + +审查结果至少让另一作者能够找到问题并实施修正。工具输出作为证据的一部分，不能代替语义与读者任务判断。 + +有修复授权时完成相关修改和复查，只列剩余问题；审查-only 时保留工作区内容，提供报告。示范见[EX-04](../examples/EX-04.md)。 + +[任务入口](../SKILL.md) + diff --git a/authoring/tasks/TASK-08.md b/authoring/tasks/TASK-08.md new file mode 100644 index 0000000..af87775 --- /dev/null +++ b/authoring/tasks/TASK-08.md @@ -0,0 +1,37 @@ +# TASK-08 研究来源与维护 skill + +适用：分析优秀文档、引入新的写作方法、增强手册、调整任务路由，或根据真实失败改进 skill。 + +必读：[DOC-020](../rules/DOC-020.md)、[DOC-022](../rules/DOC-022.md)、[DOC-023](../rules/DOC-023.md)、[DOC-024](../rules/DOC-024.md)、[行为评估](../evaluation/scenarios.md)。 + +## 从具体缺口开始 + +记录当前作者在哪类任务中作不出决定。例如知道“例子要完整”，却不知道依赖声明、归属和提案状态怎样放在成稿里。对应改进应提供一个完整示例和判断方法，不只是新增同义规则。 + +将新增内容放在最小合适位置：共同决策放 SKILL.md；任务特有步骤放任务页；详细判断放方法页；真实示范放 examples；来源事实留在 research。已有 DOC 编号保持稳定。 + +## 处理外部来源 + +读取指定原页，记录原 URL、日期、可定位章节与可观察做法。分开写页面事实、效果分析和项目采用方式。读取失败的来源保留状态，不用同名文章或搜索摘要替代正文。 + +新增建议先解释它解决的项目问题，再确定适用任务和边界。不能因为某站有复杂目录就把相同层数复制进项目，也不能把成熟语言的能力移植为本语言规则。 + +## 维护阅读地图 + +改变任务必读项时，同步 SKILL.md 的任务表、手册目录与相关 DOC 页的深读链接。入口应让作者知道为什么读这一页以及读后做什么。 + +任务查询、规则阅读和写作默认通过 Markdown 完成。新增工具须有明确任务需要和用户要求；手册不能把执行脚本、测试或安装依赖变成隐含步骤。 + +## 行为验证 + +选择与修改相关的现实任务，按 skill 走完并保存输入、产物和判断。可以使用隔离的样稿，避免测试污染正文。检验是否选对页面、保留语义边界、给出可核对成稿、尊重只读审查范围。 + +人工检查文件入口、元信息和链接；代码形式的验证仅在用户明确要求时执行。作者走查、独立代理评估、真人试用分别报告；没有进行的层级不得声称完成。 + +## 完成与维护 + +修复评估暴露的问题后再交付；在维护记录中写明变更动机和实际验证。不要为一个偶发例子堆积全局禁令。 + +一旦任务路由清晰、方法足以改变写作决策、示例可复用且选定场景达到预期，就可以发布本次改进。后续根据真实使用持续修订，而不是等待覆盖所有可能情况。 + +[任务入口](../SKILL.md) diff --git a/authoring/templates/README.md b/authoring/templates/README.md index b75d81e..37ca08c 100644 --- a/authoring/templates/README.md +++ b/authoring/templates/README.md @@ -8,6 +8,8 @@ | TPL-02 | [任务指南](TPL-02.md) | 已有前提下完成一个明确操作 | | TPL-03 | [语法或 API 参考](TPL-03.md) | 查询形式、参数、约束和效果 | | TPL-04 | [概念解释与比较](TPL-04.md) | 理解关系、设计理由或替代方案 | +| TPL-05 | [变更工作单](TPL-05.md) | 记录较大修改的依据、影响与验证，不属于读者正文 | +| TPL-06 | [审查报告](TPL-06.md) | 交付有证据、可实施的问题与建议 | 模板借鉴 [Diátaxis 的职责区分](../research/SRC-14.md)，是本项目的页面组织建议。概念指南可以结合少量讲解与示例；尚无执行环境时不将它包装成可运行教程。 diff --git a/authoring/templates/TPL-05.md b/authoring/templates/TPL-05.md new file mode 100644 index 0000000..37826cf --- /dev/null +++ b/authoring/templates/TPL-05.md @@ -0,0 +1,37 @@ +# TPL-05 变更工作单 + +用途：为跨章、语义或较大新增任务记录决策依据与影响范围。可以写在任务笔记或提交说明中，不要求每次新增持久文件。错字修正通常不需要此模板。 + +````markdown +## 本次读者目标 + +已有背景： +希望读完能完成的判断或操作： +主任务与补充任务： +采用的 DOC 规则与方法页： + +## 依据与状态 + +| 断言或决定 | 依据位置 | 当前状态 | 本次是否改变 | +| --- | --- | --- | --- | +| 填入关键断言 | 主定义或用户明确决定 | 确定/提案/未定 | 具体变化 | + +## 影响范围 + +| 主要修改 | 关联页 | 必须同步的内容 | +| --- | --- | --- | +| 文件及小节 | 文件或锚点 | 例子/文法/状态/术语/导航 | + +## 验证 + +结构检查： +语义与示例核对： +相关读者任务： +实际执行或真人测试： +仍需决定的具体问题： +```` + +使用后删去无关栏目。依据写到能定位，不只写“用户说过”或“参考其他语言”。未执行的验证写明未执行，不填预期通过。 + +[模板目录](README.md) · [语义变更任务](../tasks/TASK-06.md) + diff --git a/authoring/templates/TPL-06.md b/authoring/templates/TPL-06.md new file mode 100644 index 0000000..82ae53a --- /dev/null +++ b/authoring/templates/TPL-06.md @@ -0,0 +1,31 @@ +# TPL-06 文档审查报告 + +用途：交付有证据、可修正的审查结果。没有实质发现时直接说明范围与验证，不为了填模板创造问题。 + +````markdown +审查对象与读者目标： +已覆盖与未覆盖的范围： + +## 发现 + +### 优先级：具体问题 + +位置： +原文断言或缺少的必要条件： +主定义/规则依据： +读者会受到的影响： +最小修正： +是否已修复： + +## 验证与剩余问题 + +结构检查结果： +读者任务走查： +未执行的检查： +需要语言决定的具体缺口： +```` + +实际报告可用紧凑段落或表格承载上述信息，不必照搬六个标签。审查-only 请求只报告发现；有修复授权时先修正再写结果。 + +[模板目录](README.md) · [审查任务](../tasks/TASK-07.md) + diff --git a/authoring/workflow.md b/authoring/workflow.md index a4db5e5..f25d34a 100644 --- a/authoring/workflow.md +++ b/authoring/workflow.md @@ -4,7 +4,7 @@ ## 1. 开始前 -读取仓库 [AGENTS.md](../AGENTS.md)、[手册入口](README.md)和目标主题的主要定义。检查当前分支、远端与工作区；已有未提交修改属于原作者，未经授权不清除或覆盖。 +读取仓库 AGENTS.md、[SKILL.md](SKILL.md)和目标主题的主要定义。保留已有修改；用户明确要求提交或推送时，再完成必要 Git 状态检查。独立安装的 skill 以指定目标仓库为准，不以当前目录猜测项目。 记录： @@ -16,6 +16,10 @@ ## 2. 选择相关规则 +先从[任务索引](README.md#按任务进入)选择路线，读取任务页及其指定方法、DOC 规则和案例。可合并任务；路线是本次工作的阅读范围，不是必须逐项填满的表单。 + +直接打开任务页列出的对应小节，实际阅读后再写作。纯错字修正走 edit；若出现语义强度变化，补 semantics；审查-only 走 review 并保持文件未改。 + | 改动 | 最少阅读的相关规则 | | --- | --- | | 错字、链接或术语 | DOC-017、021 | @@ -24,25 +28,19 @@ | 外部资料研究 | DOC-020；再根据结论选相关规则 | | AI 或跨电脑接续 | DOC-022、023；再选任务适用规则 | -这是起点，不替代按风险判断。引用规则页见[规则索引](README.md#规则索引)。 +本表概括常用规则；完整必读资源以所选任务页为准。引用规则页见[规则索引](README.md#规则索引)。 ## 3. 编辑 -先修改主要定义，再同步依赖内容。使用适用的[模板](templates/README.md)，但不要填满与主题无关的栏目。 +先修改主要定义，再同步依赖内容。使用适用的[模板](templates/README.md)，但不要填满与主题无关的栏目。较大改动可用[TPL-05 工作单](templates/TPL-05.md)记录读者目标、断言依据和影响页。 语法提案保持提案身份。涉及新的语言决定时，说明所需决定而不擅自补造语法。研究与作者规则放在 authoring，不混入读者语言主线。 ## 4. 验证 -在仓库根目录执行： +默认人工核对示例计算、归属与引用、文法、链接及局部假设，并按[审查标准](references/review-rubric.md)走查相关读者任务。记录阻断问题是否消除、重要缺口是否处理、哪些检查不适用及原因。检查清单见 [checklist.md](checklist.md)。 -```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) 为准。 @@ -59,4 +57,6 @@ git diff --check 另一作者从仓库文件和 Git 状态开始，不依赖聊天记忆。维护手册时保留 DOC、SRC 和 TPL 编号；新增来源先登记访问状态。 +修改 skill 的任务入口、方法或核心约束后，选择[评估场景](evaluation/scenarios.md)走查实际任务与产物。人工结构核对、作者走查和独立测试分别记录；改进依据是观察到的决策缺口。 + [手册入口](README.md) · [贡献流程](../CONTRIBUTING.md) diff --git a/tools/README.md b/tools/README.md index 2f5e273..27a48e8 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,5 +1,7 @@ # 文档检查工具 +这些工具供用户明确要求执行检查时使用。日常文档工作默认阅读和编辑 Markdown，人工核对链接、规则与例子；存在工具不构成执行授权。 + ## 环境与命令 Python 3.10 或更新版本，无第三方依赖。在仓库根目录执行：