初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
@@ -0,0 +1,69 @@
+# 项目总览
+
+**版本：** 2026-08-07 整合版  
+**来源整合：** 根 `README.md`、`仓库职责说明.md`、`程序文件清单与功能说明.md`
+
+## 1. 项目一句话定义
+
+LineUp 是一个连接用户设备、消息服务与远程 Agent 的协作运行体系。用户通过客户端与 Agent 协作，Agent 的执行、工具调用和交互请求通过统一协议与运行时能力落到用户侧。
+
+当前更准确的理解方式是：
+
+```text
+用户侧 Host / Runtime
+  ←→ AppServer / Message Transport
+  ←→ Hermes Adapter / Agent Platform
+```
+
+它不是单纯的聊天客户端，也不是任务管理系统。项目长期核心资产是：
+
+- LineUp 协议；
+- Runtime 与 Host 边界；
+- Agent 适配层；
+- 交互与工具的标准化运行方式。
+
+## 2. 当前主线定位
+
+从现有根文档整合后，可以把项目主线收敛为以下结构：
+
+```text
+lineup-app/                 客户端 Runtime、Host、Interact 与 MiniApp
+lineup-adapter/             Agent 平台适配层，当前主线为 Hermes
+lineup-app-server/          登录、同步、消息收发和 Web Reference Host 服务端边界
+infra/wukongim-v3/          本地运行配置
+wukongim/                   上游 IM 基线源码
+agent_ops/                  文档治理、迁移、设计与阶段资料整理目录
+```
+
+## 3. 当前产品边界
+
+根文档里最稳定、且跨多份文档一致的结论包括：
+
+- 产品定位是“远程 Agent 操作交互端”；
+- 当前主交互仍围绕 IM 展开，但目标不止于聊天；
+- Agent 任务拆解和执行属于 Agent 自己，不由 LineUp 变成任务管理系统；
+- 客户端长期核心是 Runtime，而不是某一个具体聊天页面；
+- AppServer 负责传输与服务边界，不负责高层交互语义；
+- Adapter 负责平台私有协议到 LineUp 标准协议的桥接，不把平台特判下沉进 Runtime。
+
+## 4. 当前实现基线
+
+截至本轮整合，可以认为以下内容仍然是当前主线基线：
+
+- 客户端主仓是 `lineup-app/`；
+- 主要 Agent 适配路径是 `lineup-adapter/hermes/`；
+- 服务端主仓是 `lineup-app-server/`；
+- 通讯基础设施主线围绕 WuKongIM 3.0；
+- 当前客户端唯一有效实现/验收基线是 Tauri Desktop Host + Web Reference Host；
+- 不再规划独立 Android/Kotlin 客户端作为当前产品主线；
+- 历史唐僧叨叨相关材料仅保留背景参考，不再作为当前运行主线。
+
+## 5. 阅读顺序建议
+
+如果第一次进入项目，推荐从这里继续看：
+
+1. [当前状态与阶段判断](./02.当前状态与阶段判断.md)
+2. [仓库职责与协作边界](./03.仓库职责与协作边界.md)
+3. [跨仓程序清单与功能说明](../04.程序清单/01.跨仓程序清单与功能说明.md)
+
+设计与迭代文档现已迁入 `agent_ops/02.架构设计/` 与 `agent_ops/03.迭代规划/`，后续可直接从这两个目录继续深入。
@@ -0,0 +1,88 @@
+# 当前状态与阶段判断
+
+**版本：** 2026-08-07 整合版  
+**主要来源：** 根 `项目状态记录.md`  
+**说明：** 本文不原样复制运行细节，而是提炼当前阶段结论，并明确哪些判断带有时间边界。
+
+## 1. 当前阶段结论
+
+根据 `项目状态记录.md` 中截至 2026-08-03 的核验内容，以及根目录其他文档的交叉表述，当前更稳妥的阶段判断是：
+
+**LineUp 已经完成了以 `lineup-app`、`lineup-app-server`、`lineup-adapter/hermes` 为核心的一条主线闭环，重点已经从“是否能跑通”转向“如何收敛 Runtime、MiniApp、工作区、设计和文档体系”。**
+
+这比“某个服务此刻是否在线”更适合作为当前文档主结论。
+
+## 2. 当前仍有效的高层事实
+
+以下结论在多份文档中相互支持，仍适合作为当前状态摘要：
+
+- 项目主线已从早期探索阶段进入结构收敛阶段；
+- `lineup-app` 已经成为客户端主仓与当前唯一有效客户端基线；
+- `Hermes Adapter` 是当前正式保留的 Agent 适配主线；
+- `lineup-app-server` 承担登录、消息收发、同步与 Web Reference Host 服务边界；
+- 文档、设计、程序清单和迭代资料已经足够多，继续分散维护的成本开始高于整合成本；
+- 下一阶段重点不只是继续写功能，也包括整理信息架构与文档治理。
+
+## 3. 需要保留日期边界的事实
+
+原 `项目状态记录.md` 中有很多高价值事实，但它们都是“截至某次核验”的事实，不能直接提升为无日期的长期结论。例如：
+
+- 某个端口正在监听；
+- 某个服务“运行中”；
+- 某个提交号是当前基线；
+- 某个验证在某天通过；
+- 某个 APK 体积是多少；
+- 某个密钥尚未配置。
+
+这些内容建议后续拆到 `05.运行运维/`，并保留：
+
+- 核验日期；
+- 核验方式；
+- 适用范围；
+- 是否仍需复核。
+
+其中，2026-08-03 的首轮运行基线和验证事实，现已迁入：
+
+- [2026-08-03运行基线与验证记录](../05.运行运维/01.2026-08-03运行基线与验证记录.md)
+
+## 4. 以今天视角看，哪些内容已经偏“运行记录”
+
+以下内容不适合继续放在项目总览层，而更适合作为运行/联调记录保存：
+
+- 在线架构图中的实时地址和端口；
+- “当前在线”组件状态表；
+- 某次端到端验证通过时间点；
+- 某次已知问题与部署待办。
+
+它们不是不重要，而是时效性太强。把这些内容长期放在总览文档中，会导致读者混淆“结构性结论”和“当日运行事实”。
+
+## 5. 当前阶段的文档判断
+
+从文档治理角度看，当前项目已经到了必须做三件事的阶段：
+
+1. 把项目总览、状态、职责和程序清单从根目录散点文档收拢成统一入口；
+2. 维护已经迁入 `agent_ops/02.架构设计/` 的当前有效设计文档，作为新的架构主入口；
+3. 把 `lineup-app/迭代/` 中的计划、设计评审和验收评审建立清晰索引。
+
+## 6. 对原文档时效性的判断
+
+### 6.1 仍可直接沿用的部分
+
+- 总体阶段判断；
+- 项目组件分层认识；
+- 运行主线已经跑通这一结论；
+- 已知限制需要继续收敛的方向。
+
+### 6.2 需要带日期沿用的部分
+
+- 服务在线状态；
+- 具体端口、地址、版本、提交号；
+- 某次真机、浏览器、Adapter 验收记录。
+
+### 6.3 本轮不直接沿用为主入口的部分
+
+- 细粒度部署说明；
+- 历史兼容性论证全文；
+- 逐文件组件明细。
+
+这些内容后续分别下沉到 `05.运行运维/`、`02.架构设计/`、`04.程序清单/` 更合适。
@@ -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；
+- 迭代目标是否混淆了客户端、适配层和服务端职责；
+- 文档命名和归档是否按这条边界来组织。