AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe 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.mddocs/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.mddev-core/核心开发资料包括构建、贡献指南和底层接口说明BUILDING.mdLinux 环境 Android 编译指南、CONTRIBUTING.md、JAVA_BRIDGE_INTERFACE.mdfeature-protocol/具体功能与协议流程例如意图触发、工具调用和聊天导入workflow_intent_trigger.md、toolcall_xml_conversion.md、external_http_chat.mdpackage-dev/各功能包和业务模块的开发说明同时用于给用户及其 Agent 开发包index.md 及 android、chat、core、files、memory、network、toolpkg、workflow 等 18 个包文档research/对引入、接入的外部依赖或 API 等的调研记录和技术验证结果mnn_toolcall_research.md、speech_service_config_comparison.mdtest-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.ktschema、ToolRegistration.kt注册、Kotlin 执行实现、JsTools.ktJS 封装、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。结语docs/doc-src的本质是一套“文档即契约”的工程实践用单一事实源收敛信息、用主题目录保证可检索、用元数据解耦构建、用 CI 拦截链接腐化、用写作规范统一格式。理解它就等于拿到了进入 Operit 技术栈的导航图与守则手册维护它则是每一个涉及方案变更的贡献都应履行的基本义务。赞分享AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载相关推荐changedetection.io API 文档自动化生成与维护指南以 OpenAPI 规范为单一事实来源changedetection.io API 文档自动化生成与维护指南以 OpenAPI 规范为单一事实来源 本指南围绕 docs/ 目录的入口文档 docs后端AI 应用网页爬虫Skill Seekers 文档架构指南docs 目录组织、分类规范与维护流程全解析Skill Seekers 文档架构指南docs 目录组织、分类规范与维护流程全解析 本文档对应的原稿为 docs/ARCHITECTURE.md https人工智能AI 应用AI 技能RAGMCP 服务网页爬虫ChatLab 公开文档站源码结构指南docs 目录、VitePress 配置与维护规范ChatLab 公开文档站源码结构指南docs 目录、VitePress 配置与维护规范 本篇技术指南聚焦 ChatLab 开源仓库中的 docs/ 目录讲上一篇从代码到财富Java设计模式实战指南之Travel2Earn平台架构解析下一篇终极指南Guava核心工具类Objects、Preconditions与MoreObjects详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
