8.4 KiB
8.4 KiB
文档编写手册
本手册用于 Endorphin（对话中也称 Endor）文档的编写、修改与审查。它同时是 endor-docs skill 的完整资源包：从本次任务选择方法，读对应小节，再写作和验收。正式名称、语法及语言决定以目标仓库的主定义为准。
每次修改的入口
- 阅读目标仓库 AGENTS.md 与 SKILL.md，确定读者要完成的判断或操作。
- 从下面选择主任务及补充任务；查询并阅读对应任务页、方法、DOC 规则与相关语言主定义。
- 参考完整案例，选择合适的页面模板，先写主要定义，再同步依赖内容。
- 按工作流完成影响检查，用审查标准判断是否达到目标，记录实际验证。
每次工作都要选择对应路线；小型错字不要求通读手册。多个任务可以合并，例如“深化函数章节并补例子”使用 guide + example。用户明确的新语言决定优先于旧稿，按语义变更路线落实准确范围。
按任务进入
| 本次工作 | 路线 | 实际要得到什么 |
|---|---|---|
| 修正措辞、术语、链接或错字 | edit / TASK-01 | 保留语义的局部修正及必要联动 |
| 新写、深化或标准化一章 | guide / TASK-02 | 可顺序读懂的完整指南 |
| 写语法、参数和行为查询说明 | reference / TASK-03 | 可独立查询的形式、条件与效果 |
| 补全、修复或统一示例 | example / TASK-04 | 有上下文、声明、输入与结果的例子 |
| 调整目录、分页或定义位置 | structure / TASK-05 | 职责清楚的结构及同步导航 |
| 落实语言决定、修复语义冲突 | semantics / TASK-06 | 主定义、文法、状态与例子一致 |
| 评审质量或查找问题 | review / TASK-07 | 有证据、可直接实施的发现 |
| 研究来源、改进手册和 skill | research / TASK-08 | 解决具体写作缺口的方法与验证 |
选择任务后，直接打开该页列出的必读方法、规则和示例；涉及语言断言时再查下面的语言核对地图。每次实际阅读对应小节与注意事项，不能只记录规则编号。
使用与跨电脑接续说明项目级 skill 入口和可迁移方式。整个流程通过 Markdown 查阅完成；程序、脚本和测试只在用户明确要求执行时运行。
具体方法与成稿示范
| 作者需要作出的判断 | 方法 | 示例 |
|---|---|---|
| 当前语言断言是否有依据，哪个维度仍未确定 | 语言核对地图 | 有证据的审稿 |
| 一页放什么、何时拆页、如何安排前提 | 信息架构 | 章节重组 |
| 语法怎样写成合法性与行为说明 | 语义契约 | use 参考成稿 |
| 示例怎样同时做到小、完整、可解释 | 示例设计 | 跨 namespace 调用 |
| 中文说明怎样独立成立且容易检索 | 中文表达与记法 | 身份指南改写 |
| 何种问题必须修复，怎样证明完成 | 审查与验收 | 具体审查发现 |
案例包含原稿、判断、成稿及验收；方法页解释会改变写作决策的条件。24 条 DOC 原则保留稳定编号，承担快速查询与审查依据。
按问题查阅
| 正在解决的问题 | 规则 |
|---|---|
| 读者不知道这是什么，首页像约定清单 | 001、003 |
| 章节像聊天记录，教学、查询与争论混在一起 | 002、018 |
| 阅读时反复跳转，概念未介绍就出现 | 004、005 |
| 一章过大或分得过碎 | 006 |
| 知道问题但找不到具体规则 | 007、008 |
| 示例不知道放哪里、没有结果或过于复杂 | 009、010、011 |
| 只有成功用法，没有边界 | 012、013 |
| 多个概念或方案看起来一样 | 014 |
| 不清楚哪些是提案，或正文充满免责声明 | 015 |
| 语言用法混入系统实现 | 016 |
| 名词、代码与输出记法不一致 | 017、019 |
| 外部建议无法核查，读不到页面 | 020 |
| 改完一个章节后其他页面失配 | 021 |
| 需要换电脑、换作者或让 AI 接续 | 022、023 |
| 工具检查都通过，但读者还是不懂 | 024 |
规则索引
规则 ID 是稳定身份，不是阅读顺序。核心规则一般适用；建议规则按内容判断；条件规则只在对应情境使用。修改或废弃规则不重新分配其 ID。
| 编号 | 规则 | 分类 | 级别 |
|---|---|---|---|
| DOC-001 | 先确定读者与阅读目标 | 读者与定位 | 核心 |
| DOC-002 | 确定页面的主要职责 | 读者与定位 | 核心 |
| DOC-003 | 入口先建立全局理解 | 读者与定位 | 核心 |
| DOC-004 | 显式交代前置知识与上下文 | 读者与定位 | 核心 |
| DOC-005 | 按概念依赖安排阅读顺序 | 结构与导航 | 核心 |
| DOC-006 | 按读者问题分页 | 结构与导航 | 核心 |
| DOC-007 | 同时支持顺序阅读与按需查找 | 结构与导航 | 核心 |
| DOC-008 | 稳定编号与唯一主定义 | 结构与导航 | 核心 |
| DOC-009 | 最小示例必须有完整条件 | 示例与教学 | 核心 |
| DOC-010 | 形成代码、结果与解释的闭环 | 示例与教学 | 核心 |
| DOC-011 | 每个递进例子只增加少量新概念 | 示例与教学 | 建议 |
| DOC-012 | 把边界与失败写在相关规则旁 | 示例与教学 | 核心 |
| DOC-013 | 用可观察契约说明语义 | 语义与边界 | 核心 |
| DOC-014 | 比较方案时给出选择维度 | 语义与边界 | 条件 |
| DOC-015 | 区分确定规则、语法提案与未定边界 | 语义与边界 | 核心 |
| DOC-016 | 区分语言模型与实现机制 | 语义与边界 | 核心 |
| DOC-017 | 统一术语与展示记法 | 表述与证据 | 核心 |
| DOC-018 | 使用独立成立的文档陈述 | 表述与证据 | 核心 |
| DOC-019 | 让格式服务理解与查找 | 表述与证据 | 建议 |
| DOC-020 | 证据、分析与项目规则分层 | 表述与证据 | 核心 |
| DOC-021 | 每次改动完成影响检查 | 协作与质量 | 核心 |
| DOC-022 | 把文档作为可迁移的仓库资产 | 协作与质量 | 核心 |
| DOC-023 | 为人工与 AI 作者规定相同交付标准 | 协作与质量 | 核心 |
| DOC-024 | 用读者任务验收文档 | 协作与质量 | 核心 |
研究与应用
- 来源登记：15 个来源的 URL、类别与访问状态，其中 13 个由用户提供，2 个为补充方法资料。
- 分析总览：为什么这些做法有用，以及不应照搬什么。
- 当前文档的应用评估：基线检查、剩余问题与后续改写优先级。
- 维护记录：手册自身的变更及未读来源的补充状态。
- 行为评估场景：验证 skill 的任务选择、语义判断和实际产物。
- 本次评估记录：作者走查、实际产物及验证范围。
- 贡献流程：跨电脑和多作者协作。
研究页区分可观察做法与作用推断。没有进行用户可用性实验，不把分析写成已验证的阅读效率。不可读来源不参与观点归纳。