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
+31
View File
@@ -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)
+45
View File
@@ -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)
+43
View File
@@ -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)
+37
View File
@@ -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)
+38
View File
@@ -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)
+38
View File
@@ -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)
+34
View File
@@ -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)
+37
View File
@@ -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)