Operit 文档单一事实源解析：docs/doc-src 的目录规范、维护纪律与工程联动-平芜编程栈

AI Agent
人工智能
大模型
AI 应用
工具调用
本地部署
MCP Clients
Agent 记忆

【免费下载链接】Operit

The most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent

项目地址：https://gitcode.com/gh_mirrors/op/Operit

导读

docs/doc-src是 Operit 仓库中所有设计、开发与功能文档的单一事实源（single source of truth），它把零散的技术资料按主题收编为可长期维护、可被 Agent 检索的结构化文档体系。本文以该目录的官方说明为骨架，结合仓库内真实文档、构建脚本与 CI 校验代码，讲解其目录约定、维护规范、写作指南，以及文档如何与源码契约、自动化检查形成闭环，帮助你快速定位实现方案，也为后续贡献文档提供可直接套用的纪律清单。

一、定位：为什么需要“单一事实源”

在docs/README.md中，项目把docs/下的目录划分为四个职责明确的区域：

目录	职责
`docs/.META`	元数据区，目前用来充当“垃圾箱”，存放归档、遗留资料
`docs/assets`	文档使用的图片等资源文件
`docs/doc-src`	长期维护的文档单一事实源
`docs/TODO`	留给开发者协作的改动计划区，见 TODO/README.md

docs/doc-src/README.md进一步明确了它的核心价值：“这里是项目设计、开发和功能相关文档的单一事实源，按主题分类维护，方便快速了解当前实现和方案及构建 i18n 和文档站。”也就是说，doc-src 同时承担两类职责：对内是开发者快速理解当前实现的地图，对外是构建国际化文档站的内容基底。因此它强调“单一事实源”，避免同一主题在 README、TODO、源码注释中各自表述，最终以 doc-src 为准。

二、目录结构：六类主题的收编规则

docs/doc-src/README.md给出了六个主题目录的分类说明，仓库当前实际内容与之一一对应：

主题目录	官方定义	仓库内代表性文档（截至当前版本）
`architecture/`	整体架构、核心模块和运行流程设计	DEFAULT_TOOLS_ARCH.md（默认工具架构与参数变更清单）、RENDERER_ARCH.md、speech_service_profiles.md
`dev-core/`	核心开发资料，包括构建、贡献指南和底层接口说明	BUILDING.md（Linux 环境 Android 编译指南）、CONTRIBUTING.md、JAVA_BRIDGE_INTERFACE.md
`feature-protocol/`	具体功能与协议流程，例如意图触发、工具调用和聊天导入	workflow_intent_trigger.md、toolcall_xml_conversion.md、external_http_chat.md
`package-dev/`	各功能包和业务模块的开发说明，同时用于给用户及其 Agent 开发包	index.md 及 android、chat、core、files、memory、network、toolpkg、workflow 等 18 个包文档
`research/`	对引入、接入的外部依赖或 API 等的调研记录和技术验证结果	mnn_toolcall_research.md、speech_service_config_comparison.md
`test-example/`	对项目内功能的测试示例、实验记录和问题分析	chat_import_markdown_example.md、toolpkg_probe_timing_breakdown.md

从实际文件分布可以看出这套规则的收编效果：设计决策（architecture）、构建与协作（dev-core）、协议流程（feature-protocol）、包 API 文档（package-dev）、第三方调研（research）、实验记录（test-example）互不串门，任何一个主题都能在固定位置被找到。

三、文档维护规范：六条可执行的纪律

docs/doc-src/README.md用“文档维护”一节给出了核心纪律，逐条展开如下：

1. 归类与命名：放进最匹配的目录，文件名体现主题

新增文档时应放入语义最匹配的主题目录，文件名直接体现内容主题。例如工具调用协议的文档放feature-protocol/，包开发 API 放package-dev/。这保证了 Agent 或搜索引擎在检索时，仅凭路径与文件名即可建立初步主题判断。

2. 方案变更必须同步更新文档

“方案发生较大变化时，应同步更新相关设计文档，避免文档与当前实现不一致。”这条纪律在 DEFAULT_TOOLS_ARCH.md 中被落实成了硬性 checklist：修改某个工具参数时，必须同步SystemToolPrompts.kt（schema）、ToolRegistration.kt（注册）、Kotlin 执行实现、JsTools.kt（JS 封装）、examples/types/*.d.ts（类型定义）、示例代码、打包产物以及docs/doc-src/package-dev/*.md（文档），并明确指出“很多问题其实来自文档与实现不一致”。

3. 遵守项目排布规范，必要时引入标签化索引

“请按照项目规范排布文档、脚本、源码和其他文件，必要时可引入标签化索引。”docs/doc-src/before_docing.md给出了更细的排布格式约束（详见本文第五节），例如草案禁用 Markdown 图表、目录树用制表符且目录结尾带/。

4. 移动文件前必须用 rg 检查引用

“在移动文件位置前，务必用rg检查所有文档和文件，查看是否有依赖自身相对位置的引用，记得及时修改。”这条纪律背后有工程支撑：仓库的 CI 脚本 check_markdown_links.py 专门检测 merge candidate 是否引入了失效的本地 Markdown 链接，它会把文档中的相对链接基于源文件目录解析后与仓库树比对，任何移动后未同步更新的引用都会被报告为诊断项。因此移动文档不只是mv，而是“移动 + rg 全局搜索 + 修复所有相对引用”的组合动作。

5. 移动文件建议交给 Agent，并明确提示检查引用

“建议使用 Agent 来移动文件位置，除非你清楚自己在做什么，并记得明确提示检查各类引用和相对链接。”这是仓库针对 Agent 协作场景的明确建议：让 Agent 移动时，必须在提示词中显式要求检查引用与相对链接，避免 Agent 只搬运文件而漏改链接。

6. 构建与发布不得依赖文档相对位置

两条强约束值得特别注意：

“构建 App 不应直接依赖文档的相对位置，应先解析适当的元数据；若没有，应做必要的创建。”这与 before_docing.md 推荐的 YAML front matter 元数据（如tips、For_Agent字段）相呼应：文档自带元数据后，构建脚本与文档站生成器就可以通过解析元数据来定位文档，而不是硬编码目录层级。
“严禁让发布版或 CDN 直接索引项目目录位置，这会严重限制日后结构改动，且降低稳健性。”这意味着文档目录结构应当是可重构的，任何对外发布渠道都必须以元数据或清单为入口，而不是把docs/doc-src的物理路径当作 URL 结构直接暴露。

四、文档在“对外契约链”中的位置

从 DEFAULT_TOOLS_ARCH.md 可以看到，默认工具链被划分为七个层级：

工具 Prompt / Schema（对 LLM 的说明书）
工具注册（toolName → executor 绑定）
Kotlin 执行实现
脚本侧封装（JS Tools）
示例与类型定义（examples/types与examples/**）
文档（docs/doc-src/package-dev等）
打包资源 / 产物（app/src/main/assets/packages/*.js等）

其中 (1)(4)(5)(6) 被明确定义为“对外契约”，(2)(3) 是实现。文档在这里不是可有可无的附注，而是与 schema、类型定义并列的对外契约层——脚本作者通过 package-dev/index.md 了解Tools.Files、Tools.Net等命名空间的用法，其内容直接决定了第三方包能否正确编写。修改工具参数而不更新文档，等同于破坏对外契约。

五、配套写作规范：before_docing.md 要点

docs/doc-src/README.md末尾要求“建议参考文档撰写指南”，该指南是 doc-src 体系的格式配套，核心要点包括：

元数据：可使用 YAML 格式栅栏---填充文档元数据；For_Agent字段提醒“不要假设任何一个你写或改过的文档是发布版或最终版，除非用户明确表示”，这对 Agent 协作场景尤其关键。
排版：默认以双换行表示换行；不要滥用加粗，英文文档需要强调时用大写NOT；不要滥用括号，善用连词和句式替代。
视图：开发者文档与所有草稿、中间文档禁用 Markdown 图表（DX 太差）；总览目录应使用制表符树视图，目录结尾带/；Mermaid 适合展示任务图，但尽量不用于草案。
链接与路径：善用[md 链接格式]()；文档应使用相对自身的链接而非盘上的绝对路径，善用../但不应超过五层；层级太深时可用空、/或项目名指示根目录，但不表示为链接。
列表使用：善用无序列表和有序列表并注意语义；叶子节点成句时列表不超过两层，词或短语允许三层；叶子节点结尾不成句时不加句号。

这些规范与docs/doc-src/README.md的“构建与发布不得依赖文档相对位置”共同构成一套自洽的文档哲学：文档位置可自由重构，但文档内链接必须相对自身、层级受限、引用完整。

六、与 CI、协作工作流的联动

doc-src 不是孤立的文档堆，它深度嵌入了仓库的工程流程：

CI 校验：CONTRIBUTING.md 要求本地检查执行python3 -B ci/script/check_markdown_links.py --base "$BASE_SHA" --candidate "$CANDIDATE_SHA"，同时还有check_localizations.py、check_repo_hygiene.py等仓库卫生检查；PR 进入pr-check.yml工作流后，本地化、翻译资源（AAPT2 resource compile）、WebChat 与 ToolPkg 都会按路径变化触发专项检查。文档链接失效会在合并前被拦截。
协作计划：TODO/README.md 描述了大型改动的协作纪律——起一个以特性命名的文件夹、写index.md并在元数据中填入 fork 仓库地址、按“旧实现/意图修正/新实现”写分步文档、完成时加[DONE]。这与 doc-src 的“解析元数据”原则同源：协作计划以元数据为入口，而不是依赖固定路径。
构建联动：仓库根目录 package.json 中的build:webchat会先构建web-chat/的 React/Vite 产物，再通过 web-chat/scripts/sync-to-android-assets.mjs 同步到app/src/main/assets/web-chat；示例包则由python3 tools/example_packages/sync_example_packages.py按packages_whitelist.txt打包同步到app/src/main/assets/packages/。这些流程都体现了“构建依赖确定的元数据与清单、不依赖文档相对位置”的原则。

七、如何利用 doc-src 快速上手

对开发者与 Agent 而言，doc-src 是一张可直接检索的技术地图：

想理解整体架构与默认工具链路 → 读 architecture/DEFAULT_TOOLS_ARCH.md；
想在 Linux 下编译出 APK → 照 dev-core/BUILDING.md 的 JDK 21、Android SDK 34、NDK 25.1.8937393、npm run build:webchat、sync_example_packages.py、./gradlew assembleDebug流程执行；
想开发脚本包并弄清类型入口 → 读 package-dev/index.md，它说明examples/types/index.d.ts重导出各.d.ts、注入全局对象与Tools命名空间，脚本顶部用/// <reference path="./types/index.d.ts" />即可获得 IDE 提示；
想提交文档 → 遵守本节维护纪律，写作前先看 before_docing.md，改完本地跑一遍check_markdown_links.py。