初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
@@ -0,0 +1,153 @@
+# 当前权威架构基线
+
+**版本：** 2026-08-07 整合版  
+**主来源：** `01.当前有效设计/APP架构设计.md`、`01.当前有效设计/02.正式方案/*.md`  
+**补充来源：** `90.历史设计归档/` 中与当前实现不冲突的背景材料
+
+## 1. 一句话结论
+
+当前 LineUp 的权威架构基线应理解为：
+
+**LineUp 是用户设备上的主应用；Runtime 是 LineUp App 内部的核心协调环境；MiniApp、Tool、Surface 和 Capability 都必须通过 Runtime 被管理，而不是各自直连服务端或 Agent。**
+
+这一定义以当前有效设计区为准，比历史归档中的直连插件、早期 WebSocket 草案更接近今天的实际实现。
+
+## 2. 当前产品结构
+
+当前主线结构可以收敛为：
+
+```text
+LineUp App
+├── App Shell / Host
+│   ├── Tauri Desktop Host
+│   └── Web Reference Host
+├── LineUp Runtime
+│   ├── 通信、会话、同步和 outbox
+│   ├── App Registry、Instance、Focus、Lifecycle
+│   ├── Tool Router、Inventory、Inbox
+│   ├── Surface、Capability、Artifact、Audit
+│   └── MiniApp SDK
+└── MiniApps
+    ├── Interact
+    ├── Task Dashboard
+    ├── Whiteboard
+    ├── Pomodoro
+    └── 后续其他 MiniApp
+```
+
+## 3. 当前最重要的架构边界
+
+### 3.1 App、Runtime、Host 三者分离
+
+这是当前设计最关键的共识：
+
+- `LineUp App` 是用户安装和使用的产品容器；
+- `Runtime` 是 App 内部唯一拥有通信、可靠性、调度和安全决策的协调中心；
+- `Host` 负责提供桌面或浏览器环境，但不能绕过 Runtime 直接把系统能力交给 App 或 Agent。
+
+### 3.2 MiniApp 不能绕过 Runtime
+
+所有 MiniApp 都必须通过 Runtime SDK 获得：
+
+- 消息与 Inbox；
+- Tool 调用；
+- 生命周期；
+- Surface；
+- Capability；
+- 受控状态投影。
+
+它们不能：
+
+- 直接连接 AppServer 或 Agent；
+- 直接读写 Runtime Store、cursor、outbox；
+- 直接调用 Host 特权或 Tauri 能力；
+- 直接操控其他 MiniApp 或焦点栈。
+
+### 3.3 Agent 只与 Runtime 通信
+
+当前主线下，Agent 不应直接把某个 MiniApp 当作远端可执行对象，而是只能通过 Runtime 发布出来的受控 Tool / Inventory 与系统交互。
+
+## 4. 当前 Host 基线
+
+本轮整合后，当前唯一有效的客户端实现/验收基线是：
+
+```text
+Tauri 2 Desktop Host + Web Reference Host
+```
+
+这意味着：
+
+- Web Host 是开发、联调和验证入口；
+- Tauri Host 是正式桌面交付入口；
+- 二者共享同一份 TypeScript Runtime 与 MiniApp 代码；
+- 它们不是两套客户端。
+
+与此冲突的早期判断，例如“当前以纯 Web 或未来移动端为主线”“局域网 App 直连 Agent 插件”，本轮都不再作为当前架构主结论保留。
+
+## 5. 当前应用模型
+
+### 5.1 Interact 是默认系统级入口
+
+当前设计已经把“聊天页面”提升并重述为更高层的 `Interact`：
+
+- 它是系统级 MiniApp；
+- 当前默认模式是 IM；
+- 后续可扩展 Voice / Video；
+- 当前代码与作用域仍保留 `chat` 兼容命名，但概念上应理解为 `Interact`。
+
+### 5.2 Runtime 管理实例、焦点和恢复
+
+当前基线不再把 App 看成静态页面集合，而是 Runtime 管理的一组实例：
+
+- 哪些 App 已注册；
+- 哪些实例正在运行；
+- 谁在前台；
+- 谁被挂起；
+- 如何恢复；
+- 关闭或失败后如何回退到前一有效实例。
+
+这也是后续工作区、Pomodoro、子会话、恢复与验收闭环成立的基础。
+
+## 6. 当前 Tool 与 Inventory 模型
+
+早期文档把工具分成 `app / toolset / action` 三类，这是有历史价值的草案；但当前主线已经收敛为：
+
+- MiniApp 在受控声明中暴露可发布能力；
+- Runtime 进行校验、裁剪和动态汇总；
+- Agent 只能调用当前可见 Inventory 中的方法；
+- Tool 的生命周期、可见性、风险和结果由 Runtime 裁决。
+
+因此，今天更适合使用“Agent Tool / Inventory / Tool Call / 业务结果 / 协议回执”这套术语，而不是继续把早期三分法当作当前实现的主模型。
+
+## 7. 当前 Surface 与 Capability 约束
+
+这一层是从当前有效设计区的 `02.正式方案/` 中明显成熟起来的：
+
+- 复杂交互不再靠不受控页面，而是放入受限 Surface；
+- 系统能力不属于 MiniApp 自动拥有的权限，而是 Runtime/Host 保管的 Capability；
+- Agent、MiniApp、Surface 都不能绕过 Runtime 直接获得系统动作执行权。
+
+这比 `agent_ops/设计/` 早期协议文档中的能力模型更接近当前安全边界。
+
+## 8. 本轮对旧设计的取舍
+
+### 8.1 仍保留的背景价值
+
+- 产品不是任务管理系统；
+- 需要结构化消息与工具调用；
+- Agent 与 UI 渲染要解耦；
+- 工具、传输、连接需要分层思考。
+
+### 8.2 不再作为当前权威基线的旧结论
+
+- 局域网 WebSocket 直连是当前主线；
+- 当前客户端基线是“Web / 未来移动端”；
+- 工具协议可以脱离 Runtime 架构单独成立；
+- 早期 `app / toolset / action` 三分法就是当前 Tool 模型本身。
+
+## 9. 当前建议阅读顺序
+
+1. 先看本文，建立当前架构全景；
+2. 再看 [Agent工具与运行时边界](./03.Agent工具与运行时边界.md)；
+3. 如需原始来源，再回看 `01.当前有效设计/APP架构设计.md` 与 `01.当前有效设计/02.正式方案/` 各细化文档；
+4. `90.历史设计归档/` 仅用于追溯历史背景，不再作为当前设计入口。
@@ -0,0 +1,116 @@
+# Agent 工具与运行时边界
+
+**版本：** 2026-08-07 整合版  
+**主来源：** `01.当前有效设计/02.正式方案/运行时与智能体工具.md`  
+**辅助来源：** `01.当前有效设计/APP架构设计.md`、`90.历史设计归档/01.前期分析与设计/tool-action-design.md`
+
+## 1. 当前权威结论
+
+当前最重要的结论是：
+
+**Agent Tool 是 Runtime 发布给远端 Agent 的受控调用契约，不是用户按钮，也不是 MiniApp 内部函数的别名。**
+
+这是当前设计相对于早期草案最重要的收敛之一。
+
+## 2. Agent 当前扮演什么角色
+
+远端 Agent 当前应该被理解为：
+
+- 用户意图的理解者；
+- Runtime 已发布能力的调用者；
+- 结果解释与后续编排者。
+
+它不应该被理解为：
+
+- 本地 Runtime 的替身；
+- MiniApp 内部状态的直接操作者；
+- Host 权限的直接调用者；
+- 任意前端函数的远程执行入口。
+
+## 3. 三条入口必须分开
+
+当前有效设计明确把三条入口区分开了：
+
+### 3.1 Agent Tool
+
+由远端 Agent 发起，经过 Runtime 校验、持久化、路由和回传。
+
+### 3.2 本地 UI Action
+
+由用户在 MiniApp 页面中的点击、输入、拖动等触发，经 SDK / Surface Bridge 进入 Runtime。
+
+### 3.3 Host 生命周期意图
+
+由前后台切换、返回、关闭、恢复、锁屏等本地环境事实触发，经 Runtime 的生命周期裁决进入状态机。
+
+这三条入口可以复用内部业务动作，但不能混同身份。
+
+## 4. 为什么早期工具三分法不能直接作为当前主模型
+
+`agent_ops/设计/01.前期分析与设计/tool-action-design.md` 中的 `app / toolset / action` 三分法，在早期用于说明不同工具形态，很有价值；但它已经不能完整表达当前 Runtime 模型，原因是：
+
+- 当前 Runtime 要管理 Inventory 可见性；
+- 要管理 Tool Call 的幂等、状态、回执和终态；
+- 要管理激活过程、App 就绪条件、前台要求和 operation；
+- 要把 Tool、MiniApp instance、子会话、业务 operation 区分开。
+
+因此，当前主模型应优先使用：
+
+- Agent Tool；
+- Agent Inventory；
+- Tool Call；
+- 协议回执 / 进度；
+- 业务结果；
+- MiniApp activation；
+- operation。
+
+## 5. 当前 Runtime 对 Tool 的唯一所有权
+
+Tool 相关的这些职责都必须由 Runtime 统一承担：
+
+- 发布 Inventory；
+- 校验调用；
+- 做幂等去重；
+- 决定是否可见；
+- 决定是否允许启动或复用 MiniApp；
+- 持久化业务状态与 outbox；
+- 回传协议回执与最终结果。
+
+这意味着：
+
+- MiniApp 不能自己向 Agent 宣传 Tool；
+- Surface 不能直接把前端动作伪造成 Tool Call；
+- Agent 不能绕过 Inventory 直接指定任意 instance 或内部函数；
+- Host 事件也不能伪造成 Tool 调用。
+
+## 6. 当前与项目实际情况一致的几个重点
+
+结合当前 `lineup-app` 的实现方向，以下几个判断具有最高优先级：
+
+- Tool 是 Runtime 语义的一部分，不是单独漂浮在外的协议层；
+- Interact / MiniApp / Workspace / Focus / Lifecycle 与 Tool 调用之间已经形成一套统一模型；
+- 长时业务行为需要区分“调用被接受”“激活已就绪”“业务已开始”“业务已完成”；
+- 用户本地操作、Agent 远程调用和 Host 生命周期变化必须各自可审计、可恢复。
+
+## 7. 对旧设计中仍可保留的部分
+
+早期协议文档中这些认识仍然有价值：
+
+- 结构化调用比自然语言裸发更稳定；
+- 工具定义需要 schema 化；
+- 消息需要统一信封与版本化；
+- 调用与返回需要成对、可追踪。
+
+但这些内容如今应作为当前 Runtime Tool 模型的背景，而不是替代它。
+
+## 8. 本轮整合后的使用建议
+
+如果后续在设计、实现或迭代文档里出现以下歧义，优先按本文判断：
+
+- 某个按钮是不是 Agent Tool；
+- 某个本地事件能不能当成 Tool 调用；
+- 某个 MiniApp 能不能直接发消息给 Agent；
+- 某个 operation 是否等同于一次 Tool Call；
+- 某个实例 ID 是否能由 Agent 任意指定。
+
+这些问题的默认答案，都应该先经过 Runtime 边界来裁决，而不是回退到早期直连协议思路。