Ncurator/doc/doc-guidelines.md

文档准则

本文定义项目文档的骨架与编写要求，由 AGENTS.md 和 doc/tidy.md 引用。

1. 通用要求

• 按职责和骨架编写、逐章整理，只保留本文件需要的内容。
• 完整规则只维护一处，其他文档保留必要概要和引用；修改融入对应章节。
• 保留当前有效内容和约束，删除过时、重复、临时记录及无长期文档价值的实现细节，不为安置它们新增文档。

2. 各文档骨架与编写要求

README.md / README.en.md

• 职责：中英文开源项目首页，帮助读者了解产品、体验应用及参与迭代。
• 骨架：品牌定位与下载入口 → 当前能力 → 快速开始及必要费用、数据边界 → Roadmap → 社区与贡献 → 源码开发入口 → 浏览器插件 → 许可证。
• 编写要求：中文版为默认入口，两版章节、能力边界和计划保持一致。首屏突出本地办公文件 AI 的定位；能力与计划可使用简洁字符图标。截图、演示和案例阅读链接到官网，README 不重复展示；品牌与展示素材统一放 assets/。详细工程规则链接到职责文档，避免复制完整手册。

开源协作文件

• CONTRIBUTING.md / CONTRIBUTING.en.md：反馈方式 → 开发与验证 → PR 流程 → 贡献许可；中英文分文件维护、规则保持一致，命令与项目脚本对应。通过 commit signoff 确认贡献资格及遵守项目许可证，贡献按项目的 AGPL 许可证提供。QQ群、X、邮箱等联系信息统一维护在对应语言的 README，本文件仅引用入口。
• 根目录 LICENSE 保持标准 AGPL v3 正文，不混入项目说明或额外商业限制；项目采用的版本由 package.json 与 README 明确标识。

AGENTS.md

• 职责：项目级协作入口与必须遵守的工程规则。
• 骨架：文档引用（路径及阅读条件）→ 项目目录（结构及用途）→ 目录规范（分层与文件归属）→ 必须遵守的规则（代码和文档协作约束）。
• 编写要求：入口描述简短、路径准确；规则明确到可执行的要求。文档写法引用本文，不复制各文件的骨架与完整准则。

doc/architecture.md

• 职责：解释系统如何组成、模块如何协作及关键架构选择。
• 骨架：技术栈（主要技术及用途）→ 系统分层（进程与存储边界）→ 核心模块（职责与依赖）→ 主要数据流（请求、执行、存储和展示主链路）→ 关键架构设计（领域概要及设计取舍）。
• 编写要求：围绕职责、依赖、边界和设计理由展开；图与文字互相补充，领域能力只保留架构概要，不逐项登记操作、参数、字段和局部算法。

doc/ai-harness/human-harness.md

• 职责：定义 human graph 如何使用消息上下文推进任务并完成交付。
• 骨架：Graph 流转（节点、路由与安全交接）→ 数据源（消息协议及读写分工）→ 投影设计（brain、UI 与多模态投影）→ 前缀缓存（稳定与失效条件）→ Compaction（触发、切点与压缩）→ Resume（恢复与中断修复）→ Toolset、Skill 与 Plan（运行态管理）→ 交付与失败（收尾、错误与重试）；必要时附关键代码索引。
• 编写要求：写清机制、状态流转、消息顺序、范围及不变量；字段和示例限于解释协议所需，不能复制完整数据库字段目录或 Workbench 操作流程。

doc/ai-harness/tool-design.md

• 职责：定义工具契约的设计原则及共用执行、结果投递机制。
• 骨架：设计原则（契约约束）→ 描述分层（工具包、Skill、工具与字段的分工）→ 工具规格结构（注册与类型关系）→ 参数规范化（共用校验边界）→ 统一结果投递（管道与大小处理）→ 渲染格式族（模型反馈形态）→ 执行机制（hand、审批及资源范围）；必要时附关键代码索引。
• 编写要求：说明共用规则、边界和必要的典型例子；单工具的完整参数、输出与调用例子由代码及生成契约维护，不将本文扩成工具使用手册。

doc/storage/design.md

• 职责：定义本地数据库、索引、文件资源与运行缓存的存储布局、持久化关系及生命周期约束。
• 骨架：存储总览（资源分类、所有权与真相来源）→ 数据库存储（SQLite、schema 演进、事务及运行环境约束）→ 索引存储（LanceDB、generation、清理与优化）→ 文件资源与目录布局（附件、工具结果、备份、审核及缓存的存放关系）→ 生命周期与一致性（创建、版本、恢复、保留和清理）。
• 编写要求：兼顾数据库与文件存储，写清资源归属、路径用途、持久化关联、版本及恢复清理约束；区分长期数据、可重建索引和临时缓存，完整表字段引用表目录，不展开 AI 执行或用户操作流程。

doc/storage/tables.md

• 职责：提供当前 SQLite 与 LanceDB 表结构目录。
• 骨架：SQLite（每表用途与字段）→ LanceDB（每表用途与字段）；每表按用途说明、字段表和必要结构约束组织。
• 编写要求：字段表写名称、类型、含义及必要的主键、索引或关联约束，与当前 schema 一致；不复制字段背后的完整业务流程，不记录历次 schema 变化。

doc/brand.md

• 职责：统一用户可见品牌、英文品牌与技术标识的使用口径。
• 骨架：命名层次（名称及适用场景）→ 下载与缓存命名（公开名和技术名的映射）→ 技术标识约束（需保持稳定的标识）→ 当前品牌边界（语言与命名限制）。
• 编写要求：明确每种名称的使用场景与稳定要求；例子用于说明命名，不展开发布脚本、更新流程或页面功能。

doc/ui-style.md

• 职责：定义全前端共用的视觉系统和基础交互规范。
• 骨架：设计语言（整体视觉基调）→ 布局原则（空间关系）→ 配色与尺度（token、字级、间距等）→ Surface 与基础组件（层级与通用状态）→ 文案、动效、光标及辅助功能（共用交互反馈）。
• 编写要求：写跨页面复用的规则和尺度；页面示例只解释视觉原则，不定义业务入口、控件顺序、状态流转或产品验收。

doc/prd/settings.md

• 职责：定义 Settings 的用户功能、行为边界及验收标准。
• 骨架：产品目标（解决的问题）→ 范围与术语（能力边界和产品概念）→ 需求明细（按通用设置、模型、工作地址、文件与网页资料、向量模型、帮助等主题组织）→ 非目标（明确排除的能力）。
• 编写要求：每项需求包含稳定编号、用户操作或触发条件、系统行为、状态反馈及验收编号；约束用产品语言说明，内部重构不写成新需求。编号规则在此准则维护：使用 SET-<模块>-<三位序号>，验收追加 -AC<序号>；删除后保留编号空缺，不重排或复用。

doc/prd/workbench.md

• 职责：定义 Workbench 的用户任务流程、能力边界及验收标准。
• 骨架：产品目标与原则（任务体验）→ 范围、能力边界与术语（产品概念）→ 需求明细（按伙伴、Composer、资料引用、运行交互、内容面板、文件处理与定时任务等主题组织）→ 非目标（明确排除的能力）。
• 编写要求：按用户操作、系统行为、状态反馈、异常边界和验收组织需求，不混入节点、类名、数据库字段和局部算法。编号规则在此准则维护：基础需求使用 WB-<模块>-<三位序号>，定时任务使用 ST-<模块>-<三位序号>，验收追加 -AC<序号>；删除后保留编号空缺，不重排或复用。

doc/test.md

• 职责：定义项目共用的测试体系与执行规范。
• 骨架：测试体系（分类、目录与映射）→ 用例规则（准入、共用字段和各层约束）→ 执行闭环（顺序、runner、命令与日志读取）→ 产物契约（目录、元数据、事件和附件格式）。
• 编写要求：只维护跨领域的分层与执行约束；说明 runner 和产物如何使用，不登记各业务域的完整 suite、case 或单次结果。

doc/test-plan/ai-test.md

• 职责：定义 AI 工具和 human harness 的验证范围与证据要求。
• 骨架：总体目标（验证对象）→ Suite 设计（tool、human 及测试模式分工）→ 领域测试约束（真实程度、前置条件与 Oracle）→ 回归清单（按能力和场景组织）→ 覆盖边界（已覆盖、缺口及人工验收）。
• 编写要求：每个场景说明 What、Why、How、Oracle 和适用测试类型；mock 与 live 边界明确，断言对应真实 case；完整生产规则引用设计文档，不把测试约束写成实现教程。

doc/test-plan/knowledge-test.md

• 职责：定义知识库功能及效果优化的验证范围。
• 骨架：总体目标（功能与效果）→ Suite 设计（foundation 与 optimization 分工）→ 领域测试约束（真实输入、索引及评价依据）→ 回归清单（功能契约与优化场景）→ 覆盖边界（证据及缺口）。
• 编写要求：区分功能正确性和优化效果，写清输入、方法、Oracle 及真实证据；尚无用例的范围如实标明，不以计划表述冒充已覆盖。

doc/test-plan/settings-test.md

• 职责：定义 Settings 产品行为的测试场景和覆盖范围。
• 骨架：总体目标（产品验证范围）→ Suite 设计（按设置主题分工）→ 回归清单（操作、状态与异常场景）→ 发布前真实检查（系统级人工验证）→ 覆盖边界（逐项验收证据与缺口）。
• 编写要求：What、Why、How、Oracle 对应 SET 需求及验收编号；区分 UI 自动化、底层验证和人工检查，需求编号引用不能代替实际断言证据。

doc/test-plan/workbench-test.md

• 职责：定义 Workbench 用户任务闭环的测试场景和覆盖范围。
• 骨架：总体目标（环境与验证对象）→ 测试边界（真实前置及领域约束）→ Suite 设计（conversation、run、result、scheduled-task）→ 执行入口（领域目录与命令）→ 回归清单（用户场景与 Oracle）→ 覆盖边界（验收证据及缺口）。
• 编写要求：按用户闭环组织，不逐章复制 PRD；场景说明 What、Why、How、Oracle 并映射 WB / ST 需求及验收编号，保留必要的真实前置条件，明确自动化证据范围。

doc/deploy/design.md

• 职责：定义构建、发布存储、更新通道与真实升级验证的工程设计。
• 骨架：平台与构建（运行及打包约束）→ 对象存储与公开通道（对象布局、本地保留与清理）→ 自动更新（通道与版本关系）→ 真实覆盖升级验证（隔离方案、执行入口与通过条件）。
• 编写要求：围绕构建边界、产物身份、存储布局和升级约束展开；命令用于说明设计入口，不复制日常发布操作顺序。

doc/deploy/release.md

• 职责：提供可执行的桌面端发布操作流程。
• 骨架：发布准备与 Tag（前置条件及中止）→ 候选包与正式包回归（影响评估及门禁）→ 发布与公开验证（操作及成功证据）→ 中断与恢复（状态及恢复入口）→ 命令参考（参数化执行示例）。
• 编写要求：按执行顺序说明前置条件、动作、通过条件及失败处理；命令与脚本一致，使用参数化示例，不沉淀某次发版记录。

doc/deploy/tencent-cdn-billing.md

• 职责：定义国内下载通道的计费关系、采购与控费策略。
• 骨架：采购结论（当前选择及条件）→ 计费链路（费用由哪里产生）→ 控费配置（封顶与告警）→ 资费依据（区域、计费方式、来源及日期）→ 用量估算（假设与计算口径）→ 采购决策（适用条件及与发布的衔接）。
• 编写要求：区分报价、估算、已配置事实和采购决策；金额与用量注明来源或假设及适用时间，更新当前依据，不堆叠旧报价或临时操作记录。

doc/tidy.md

• 职责：规定周期整理文档、测试与代码的审核及执行流程。
• 骨架：流程（节点推进、方案确认与执行约束）→ 审阅清单（文档与实现、文档健康、需求测试映射、测试分层、代码整洁）。
• 编写要求：保持简短、可执行，文档健康检查引用本文的骨架与准则；不复制每份文档的边界、模板或编写要求，不保存本次审计问题及处理记录。

doc/ai-tool-prompt-audit.md

• 职责：提供从当前代码生成的 Skill / Tool 契约活例子，按需生成、不入库。
• 骨架：由生成器按 Skill / Tool 组织各工具描述、输入、输出和渲染例子，不人工重排。
• 编写要求：使用 pnpm doc:ai-tool-prompt-audit 生成；内容错误时修正契约源码或生成器，不手工修改输出，不追加设计说明或迭代记录。