初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
@@ -0,0 +1,99 @@
+# 仓库职责与协作边界
+
+**版本：** 2026-08-07 整合版  
+**主要来源：** 根 `仓库职责说明.md`，辅以根 `README.md`
+
+## 1. 核心结论
+
+当前 LineUp 主线的长期稳定分层，不是按“前后端”粗分，而是按能力边界分为三层：
+
+```text
+lineup-app/            LineUp Runtime / Host / Interact / MiniApp
+lineup-adapter/hermes/ Agent 平台适配层
+lineup-app-server/     登录、同步、消息收发和服务接入层
+```
+
+其中最应避免的事情是：为了图快，把某个层的问题一路下沉到不该负责的仓库。
+
+## 2. `lineup-app/` 的职责
+
+`lineup-app/` 是客户端主仓，负责用户真正使用到的交互运行时。
+
+它长期应该承接：
+
+- Runtime；
+- Interact 与主交互模式；
+- MiniApp SDK；
+- Tool Router；
+- App Workspace；
+- Surface / Capability 承载边界；
+- Tauri / Web Host 装配。
+
+它不应该承接：
+
+- Hermes 或其他 Agent 平台的私有 prompt / approval 语义；
+- 登录、同步、消息中转服务逻辑；
+- 平台专属网关状态机。
+
+## 3. `lineup-adapter/hermes/` 的职责
+
+`lineup-adapter/hermes/` 负责把具体 Agent 平台接到 LineUp 标准协议上。
+
+它长期应该承接：
+
+- 平台私有协议与 LineUp 协议之间的桥接；
+- approval / clarify / confirm 等平台私有交互的映射；
+- `call_id`、选项 id、内部 request id 的解析与账本；
+- 白名单化、安全化的 Agent 输出规范化。
+
+它不应该承接：
+
+- Runtime 的长期业务状态机；
+- MiniApp 工作区快照；
+- AppServer 的登录、同步和服务职责；
+- 直接修改客户端展示层语义。
+
+## 4. `lineup-app-server/` 的职责
+
+`lineup-app-server/` 是传输与服务边界层。
+
+它长期应该承接：
+
+- 登录与鉴权；
+- 消息发送与同步；
+- Webhook 和基础服务端 API；
+- 与 WuKongIM 等基础设施对接；
+- Web Reference Host 的服务端部分。
+
+它不应该承接：
+
+- 高层 `lineup.v1` 交互语义解析；
+- Runtime Tool 生命周期；
+- Agent 平台私有协议兼容逻辑；
+- 前端具体展示决策。
+
+## 5. 改动落点判断顺序
+
+整合根文档后，可以把跨仓改动判断顺序压缩为三步：
+
+1. 如果是 LineUp 自己的标准能力、运行时能力、交互协议或工作区语义，优先落在 `lineup-app/`。
+2. 如果是某个 Agent 平台的私有兼容问题，优先落在 `lineup-adapter/hermes/`。
+3. 如果是登录、同步、消息收发或服务接入问题，优先落在 `lineup-app-server/`。
+
+## 6. 为什么这份文档仍具有时效性
+
+与“某个服务今天是否在线”不同，仓库职责文档主要表达的是边界约束。只要主线架构未重组，这类判断就比运行状态更稳定。
+
+因此，本轮整合后认为以下内容仍然具有较强时效性：
+
+- 三仓主边界划分；
+- Runtime / Adapter / AppServer 的分层原则；
+- 跨仓改动的优先判断顺序。
+
+## 7. 后续如何使用本文件
+
+后续在维护 `agent_ops/02.架构设计/` 和 `agent_ops/03.迭代规划/` 时，这份文档可以作为边界校验基线：
+
+- 设计方案是否把平台私有逻辑错误下沉到了 Runtime；
+- 迭代目标是否混淆了客户端、适配层和服务端职责；
+- 文档命名和归档是否按这条边界来组织。