docs: develop task-guided Endor authoring skill and detailed handbook

This commit is contained in:
2026-10-08 00:38:17 +08:00
parent 941942c7e1
commit 10d14612dc
61 changed files with 1332 additions and 27 deletions
+38 -6
View File
@@ -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):跨电脑和多作者协作。
研究页区分可观察做法与作用推断。没有进行用户可用性实验,不把分析写成已验证的阅读效率。不可读来源不参与观点归纳。