Skip to content

维护者指南

这份文档面向维护者和二次开发者，不面向普通使用者。
主 README 负责上手入口；这里负责解释维护时需要同时关注的代码、文档和同步链路。

维护范围

  • 执行边界：主动模型轮次与 agent 订阅
  • 工具域边界：device / bench / common / media / coding
  • 接口工具：协议请求、提取、校验和批量执行能力
  • 文档拆分与同步：README.md、docs/*.md、.github/workflows/sync-to-software-center.yml

系统骨架

架构与实现按以下权威链维护：

ARCHITECTURE_SYSTEM.md
  -> Mind / AppServer / Fabric 跨系统架构
  -> constrains ARCHITECTURE.md
  -> constrains implementation

Server contract + protocol/schema + protocol/client
  -> 线上 wire 契约

README.md 和 docs/ 只负责入口、解释与教学，不得反向定义 Architecture Truth。 维护时需要保证系统架构、客户端架构、正式协议、实现与用户文档一致。

执行边界

  • exec 和交互会话共用统一模型轮次、工具生命周期和请求协议
  • agent 是订阅入口，负责 /agents/open、/agents/ws、恢复链路和远端任务映射
  • Helix 是可选能力提供者，由 --helix 或 /helix-link 显式接入，不下沉到 CompositeToolRuntime 自动启动；/helix-mode 只选择工具过滤器
  • 工具过滤策略保留独立过滤模式，调用来源确定前不得复用为应用运行模式

维护要求： - 如果改了工具过滤逻辑，必须同步更新对应策略测试和工具说明 - 如果改了 CLI 帮助或示例，也要确认 README 和 docs/ 是否仍然对齐 - 不要在文档里承诺未实现的 REPL 指令 - 不要把 agent 写成 REPL 内部状态；它是独立 CLI 入口 - 不要在 CLI、TUI、请求协议或会话状态中重新引入 chat / fast / xtra

工具域边界

  • device：应用与系统控制、UI 操作链
  • bench：性能、稳定性与接口执行能力
  • common：环境与基础能力
  • media：截图、录屏、音视频处理与帧级流水线
  • coding：原生 coding 工具、shell/git 受控执行

关键约束： - 接口能力不是独立 api 域，而是归在协议执行这一侧 - 如果工具注册名、域名或能力归属变更，README、对应 playbook 和产品背景说明要一起改；只有状态所有权或系统边界变化时才修改架构权威文档

文档分层规则

  • README.md：入口页，只保留最小上手、边界、速查和跳转
  • ARCHITECTURE_SYSTEM.md：Mind、AppServer 与 Fabric 的系统级唯一架构权威
  • ARCHITECTURE.md：ProxyMind 客户端内部唯一架构权威，受系统架构约束
  • ARCHITECTURE_SCORECARD.md：阶段性架构评审与成熟度记录，不定义架构事实
  • docs/README.md：长文档索引，由 website/mind/docs_manifest.json 生成
  • docs/playbook.api.md：接口约定与协议说明
  • docs/playbook.load.md：云端压测、异步任务与结果收束边界
  • docs/playbook.media.md：媒体命令与链路
  • docs/playbook.performance.md：性能案例与典型跑法
  • docs/interactive-mode.md：全部 REPL slash 命令、会话管理和输入约束的权威参考
  • docs/cli-usage.md：全部 CLI 命令、选项和组合规则的权威参考
  • docs/agent-mode.md：订阅模式说明
  • docs/architecture.md：产品背景、使用入口、可选能力和生态介绍，不定义架构事实
  • website/mind/pages/：官网展示壳与站点入口页
  • website/mind/docs_manifest.json：官网生成层的正文清单与专题摘要
  • website/mind/scripts/check_docs.py：命令覆盖、manifest 和生成页链接校验
  • website/mind/CLOUDFLARE.md：Cloudflare Pages 部署说明

维护原则： - 用户入口变重时，优先下沉到 docs/ - 维护者说明不要反向塞回 README - website/mind/pages/generated/ 只当生成产物看，不要手改 - slash 命令只在 docs/interactive-mode.md 维护完整说明，CLI 命令只在 docs/cli-usage.md 维护完整说明；README 和官网入口页只保留摘要

文档维护约定

  • 标题统一使用中文标题，不再在标题尾部追加英文副标题
  • README 和 docs/ 内部链接统一使用仓库内相对路径
  • 术语一旦在 README 中定稿，docs/ 中应保持同一写法，不要派生近义口径
  • 只要改了 README.md、docs/*.md 或 LICENSE.md，都应判断是否需要同步到 SoftwareCenter

工具文档约定

对模型直接暴露的工具，说明文本必须按“模型可读”和“MCP 客户端可消费”标准维护，不能把实现注释直接暴露成工具说明。

维护要求： - 文档必须按真实能力写，不要承诺代码没有实现的行为 - 优先写“做什么 / 不做什么 / 前置条件或限制”，避免堆实现细节 - 工具说明应帮助模型判断是否该调用该工具，而不是解释内部实现过程 - 工具对外描述优先写在 @mcp.tool(description=...)，不要依赖函数 docstring - 不要在 description 中重复 domain / class / action / return 这类内部标签；这些信息应由工具名、meta 和返回结构承担 - 不要在 description 中罗列完整参数清单；字段级说明应落到 inputSchema，优先用 Annotated[..., Field(description=...)] 或 Pydantic 输入模型 - 能力边界要写清： - 是否只下发命令 - 是否会等待最终状态 - 是否只看当前页面 - 是否会自动滚动、自动点击、自动重试 - 前置条件要写清： - 是否依赖输入焦点 - 是否依赖可滚动容器 - 是否依赖系统权限、ROM 支持或输入法状态 - 不稳定或不建议依赖的能力要直接说明，不要写成默认推荐路径 - 参数默认值、可选值和实现保持一致；如果实现改了，doc block 要一起改 - 不要把“默认目录”“内部回填”“增强层自动传参”这类内部机制直接写进工具契约，除非它本身就是稳定能力边界

推荐写法： - 第 1 句：这个工具实际执行什么动作 - 第 2 句：它不负责什么，或它的边界在哪里 - 第 3 句：它依赖什么条件，或在哪些情况下可能无效果/失败 - 句子里只点名真正影响选工具的关键参数，例如 kind、saved、activity - 复杂参数多到一段 description 说不清时，优先补字段 description，不要把工具 description 写成参数手册

避免这样写： - D: / C: / A: / P: / R: / N: 这类内部标签块 - “万能入口”“智能处理”“自动完成页面操作” 这类泛化表述 - 只写底层 adb 命令，不写实际能力边界 - 把内部增强层、模板表达式或临时实现细节写成用户契约

同步链路

同步工作流在： - .github/workflows/sync-to-software-center.yml

当前同步目标： 

SoftwareCenter/Assets/Mind/
  ├── README.md
  ├── ARCHITECTURE_SYSTEM.md
  ├── ARCHITECTURE.md
  ├── ARCHITECTURE_SCORECARD.md
  ├── AGENTS.md
  ├── LICENSE.md
  └── docs/

SoftwareCenter/site/mind/
  ├── mkdocs.yml
  ├── requirements.txt
  ├── scripts/
  └── pages/

命令或文档变更后的本地校验顺序：

python website/mind/scripts/check_docs.py
python website/mind/scripts/sync_docs.py
python website/mind/scripts/check_docs.py --generated

维护要求： - README 和 docs/README.md 必须使用仓库内相对路径，不要写本机绝对路径 - 如果新增 docs/*.md，要确认： - website/mind/docs_manifest.json 已补清单 - 运行 website/mind/scripts/sync_docs.py 后，docs/README.md 已自动补索引 - README 是否需要补入口 - 同步后相对路径仍可达 - 如果改了 website/mind/，要确认同步后仍映射到 SoftwareCenter/site/mind/ - 如果改了正文文档结构，记得同步检查 website/mind/docs_manifest.json - 同步 workflow 会先校验命令文档，再运行 website/mind/scripts/sync_docs.py，最后校验生成页并复制官网壳到公共仓库

变更检查清单

每次涉及模式、文档或同步链路的改动，至少检查下面这些点：

  1. README 的能力边界是否仍与实现一致
  2. 系统级与客户端内部 Architecture Truth 是否仍由对应权威文档唯一维护
  3. docs/ 中对应说明是否只解释权威事实而未重新定义
  4. 是否引入了绝对路径或失效相对链接
  5. sync-to-software-center.yml 是否仍会把新增文档同步出去
  6. Docs 索引 是否补到了新文档入口

适合新增深技术文档的场景

只有在下面几类情况，才值得继续加更深的技术文档： - 新增工具注册机制或工具路由规则 - 新增模式或大改模式过滤逻辑 - 新增同步仓库、发布仓库或目录映射 - 新增面向用户的独立执行入口

否则优先保持当前文档层次，不要让入口文档重新膨胀。