Cowork 3P 7573780956 docs(architecture): fix critical accuracy errors, stale refs, paths

Accuracy fixes:
- app-orchestration.md: remove non-existent constructor params
- models-and-config.md: remove wrong multiAgent field from SettingsSnapshot
- runtime-contracts.md: add missing multiAgent/collaborationMode/routingHint fields

Stale multi-agent refs:
- unified-routing-architecture.md: agent/multi-agent → agent (含 bridge 转发)
- bridge-runtime-routing-map.md: multi-agent tasks → multi-agent forwarding tasks
- cross-repo-task-state-workflow.md: remove multi-agent orchestration from mermaid
- runtime-contracts.md, feature-surfaces.md: 多 agent → agent

Organization:
- Move cloud-session-service and stage4-helper to archive/
- Fix 22 xworkmate/ → xworkmate-app/ paths in archive doc
- Fix XWorkmate.svc.plus repo name in simple-theme-default.md
- Update README.md index and public-api/README.md coverage stats (132/590)

2026-06-04 06:53:38 +00:00

5.1 KiB

Raw Blame History

XWorkmate Public API Engineering Docs

Last Updated: 2026-04-14

Purpose

本目录为 xworkmate-app 的公开接口工程文档下钻层，目标不是替代已有架构文档，而是把“当前主链真正暴露出来的库 / 类 / 函数 / 接口”系统化整理出来。

这一层文档固定采用两层产物：

机器清单层：由脚本自动提取的公开符号与签名，解决“覆盖完整性”
设计解释层：人工编写的职责、参数语义、返回值语义、主调用链、外部副作用，解决“可读性和工程决策语义”

Reading Order

建议按下面顺序阅读：

再回看这些背景文档补架构上下文：

Scope Rule

纳入范围：

lib/app
lib/runtime
lib/models
lib/features/assistant
lib/features/settings
lib/features/mobile
lib/theme
rust/src

文档粒度：

公开顶层符号：非 _ 开头的 class、abstract class、enum、typedef、extension
公开顶层函数
Rust pub struct / pub enum
Rust pub unsafe extern "C" FFI 函数

人工解释层的额外约束：

页面层只覆盖“业务 + 关键页面”
纯展示型 leaf widget 不逐条展开
私有 _ 符号不作为正式 API 条目
低价值 DTO/辅助函数默认留在生成清单，不强行全部补人工说明

Coverage Summary

当前生成清单覆盖 132 个源码文件、590 个公开符号。

Scope	Files	Public Symbols	Detailed Design Entries	Notes
`lib/app`	30	68	10	主写桌面编排入口、扩展、registry 与 shell
`lib/runtime`	66	372	18	主写 bridge contract、runtime client、controller、bootstrap
`lib/models`	1	31	13	主写 settings / execution / provider / snapshot 主模型
`lib/features/assistant`	16	79	1	只展开页面入口与业务挂点
`lib/features/settings`	4	5	1	只展开设置主入口
`lib/features/mobile`	6	19	1	只展开移动端 shell 主入口
`lib/theme`	2	13	2	只展开工程上影响 API 的 theme/palette 入口
`rust/src`	4	16	17	结构体与 FFI 函数全部展开

说明：

“Public Symbols” 以生成清单 JSON 为准
“Detailed Design Entries” 是人工解释层条目数，不等于全量公开符号数
剩余未逐条解释的公开符号，视为“已被生成清单覆盖，但尚未进入高价值解释层”

Explicit Exclusions

下面这些内容被明确排除在“人工解释层”之外，但不代表它们不存在：

Excluded Scope	Files	Public Symbols	Reason
`lib/widgets`	21	51	纯展示 leaf widget 为主，不作为本次设计文档主对象
`lib/data`	1	1	mock/sample 数据，不是运行时公开 contract
`lib/i18n`	1	4	文案与语言辅助，不是业务接口主链
`lib/main.dart`	1	0	启动封装，无独立公开符号

File Map

_generated/public-symbol-inventory.md 公开符号清单，适合做覆盖检查、文件定位、签名对照
_generated/public-symbol-inventory.json 机器可校验版本，适合后续脚本和 CI 使用
app-orchestration.md AppController、导航、设置保存、线程/会话/执行主链
runtime-contracts.md ACP、gateway runtime、settings controller、session client、bootstrap、registry
feature-surfaces.md AssistantPage、SettingsPage、MobileShell、WorkspacePageSpec
models-and-config.md SettingsSnapshot、连接配置、provider/catalog、gateway/runtime snapshot、多 agent 配置
ffi-and-rust.md Rust 公开结构体与 C ABI 面

Validation Workflow

生成清单：

make docs-public-api

最低校验：

python3 scripts/docs/extract_public_api_inventory.py
rg -n '`_' docs/architecture/public-api/*.md

人工核对优先文件：

lib/runtime/gateway_acp_client.dart
lib/runtime/go_task_service_client.dart
lib/runtime/codex_runtime.dart
lib/app/app_controller_desktop_settings_runtime.dart
rust/src/lib.rs

Maintenance Rule

新增公开顶层符号后，先运行 make docs-public-api
如果新增符号属于主链 contract、页面入口、配置主模型、桥接接口或 FFI 面，则必须补到人工解释层
如果只是低价值 DTO、单向 helper、视觉组件或简单枚举，允许仅由生成清单覆盖

5.1 KiB Raw Blame History Unescape Escape