初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
@@ -0,0 +1,60 @@
+# Stage 1：需求分析与架构设计
+
+**状态：** ✅ 已完成
+**时间：** 2026-07-24 → 2026-07-27
+
+---
+
+## 目标
+
+完成 LineUp Agents 的产品定位、架构设计、协议定义，输出第一版设计方案。
+
+---
+
+## 完成内容
+
+### 产品定位
+
+- 定义为"远程 Agent 操作交互端"，不是任务管理系统
+- MVP 范围：局域网直连，不做中转，不做 MCP 封装，不做通知推送
+
+### 架构设计
+
+- 三层协议：通讯协议层、消息协议层、工具协议层
+- 局域网直连方案，Agent 插件内开 WebSocket 端口 9527
+- 预共享 Token 鉴权
+- 手动输入 IP:端口发现方式
+
+### 消息协议
+
+- 统一信封格式：`{ v, id, type, payload }`
+- 7 种消息类型：system.hello、system.ping/pong、text、image、tool.list、tool.call、tool.result
+
+### 工具协议
+
+- 三类工具：app（有状态应用）、toolset（无状态工具集）、action（单指令工具）
+- app 类型通过 instance_id 管理生命周期，open → use → close
+- tool.call / tool.result 标准化格式
+
+### 技术选型
+
+- App 端：Vite + React + Tailwind + shadcn/ui
+- 通信：裸 WebSocket，不引入 Socket.io
+- Agent 端：Hermes 平台插件优先
+
+### 文档产出
+
+| 文档 | 位置 |
+|------|------|
+| v1 设计方案 | LineUpAgents/设计/design-v1.md |
+| 早期分析与设计 | LineUpAgents/设计/早期分析与设计/ |
+| README 项目入口 | LineUpAgents/README.md |
+
+---
+
+## 关键决策
+
+- 不做独立 Channel 进程，插件嵌入 Agent
+- 不做 MCP 封装，工具路由用字典映射
+- 先纯 Web，后续再考虑 Tauri 壳子
+- 结构化消息返回，不是自然语言裸发
@@ -0,0 +1,44 @@
+# Stage 2：App 端交互原型
+
+**状态：** 🟡 进行中
+**时间：** 2026-07-27 →
+
+---
+
+## 目标
+
+搭建 LineUp App 端的 Vite + React 项目框架，完成核心页面的交互原型。不写业务逻辑（WebSocket 通信、工具调用），只搭 UI 和页面流。
+
+---
+
+## 要做的事
+
+### 1. 搭建项目骨架
+
+- 用 Vite + React + TypeScript 初始化项目
+- 安装 Tailwind CSS + shadcn/ui
+- 配置基础目录结构（pages / components / hooks / types）
+
+### 2. 确定核心页面与交互流程
+
+需要跟用户确认的界面：
+
+- 首页（连接 Agent）—— 输入 IP:端口 + Token，点击连接
+- 连接状态指示 —— 已连接 / 连接中 / 断开
+- 会话主界面 —— 消息流展示（text、image、tool 卡片）
+- 消息输入区 —— 输入框 + 发送按钮
+- 工具渲染 —— choice、confirm、input 三种工具的 UI 原型
+
+### 3. 输出静态原型
+
+- 每个页面一个独立组件，不带状态管理
+- 用 mock 数据展示页面效果
+- 串联成可点击的页面流
+
+---
+
+## 待讨论
+
+- 主界面布局：左侧会话列表 + 右侧对话区，还是单栏对话？
+- 工具卡片样式：choice 选择按钮的排列方式、confirm 确认/取消的视觉样式
+- Dark/Light 主题偏好
@@ -0,0 +1,66 @@
+# Stage 2：中转服务器方案设计
+
+**状态：** 🟡 进行中  
+**最后更新：** 2026-07-30
+
+---
+
+## 目标
+
+建立一套可在本机通过 Docker Compose 启动的 IM 服务环境，供唐僧叨叨客户端完成基础聊天验证，并作为 LineUp 远程 Agent 交互的后续通讯基础。
+
+该环境是一套协作的服务集合，而非两个互相替代的 IM：WuKongIM 是通讯层，唐僧叨叨是业务层。
+
+## 决策记录
+
+| 决策 | 结论 |
+|------|------|
+| 通讯层 | **WuKongIM v2** |
+| 业务层 | **唐僧叨叨服务端 v1.5** |
+| 部署方式 | Docker Compose，本地单节点 |
+| 业务依赖 | MySQL 8、Redis 7、MinIO |
+| 前端入口 | 唐僧叨叨 Web 与 Manager，均仅绑定本机端口 |
+| 消息客户端 | 唐僧叨叨客户端或 WuKongIM 官方 SDK |
+| Agent 接入 | 后续基于 WuKongIM 官方 SDK 或已验证协议实现；不依赖其他平台的专用机器人网关 |
+| 数据策略 | Docker 命名卷持久化；本地环境禁止将密钥写入仓库 |
+
+## 系统架构
+
+```text
+唐僧叨叨 Web / 移动客户端
+  ├─ HTTP 业务请求 ───────────► 唐僧叨叨服务端 :8090
+  └─ TCP / WebSocket 消息 ────► WuKongIM :5100 / :5200
+                                      │
+               HTTP API ◄────────────┤
+                                      └─ Webhook gRPC ─► 唐僧叨叨服务端 :6979
+
+唐僧叨叨服务端 ──► MySQL / Redis / MinIO
+```
+
+## 本地端口边界
+
+| 服务 | 容器端口 | 本机端口 | 作用 |
+|------|----------|----------|------|
+| WuKongIM HTTP API | 5001 | 15001 | 健康检查和本地调试 |
+| WuKongIM TCP | 5100 | 15100 | 官方 SDK 的 TCP 长连接 |
+| WuKongIM WebSocket | 5200 | 15200 | Web / WebSocket 客户端长连接 |
+| WuKongIM 监控 | 5300 | 15300 | 本地监控 |
+| 唐僧叨叨 API | 8090 | 18090 | 业务 API |
+| 唐僧叨叨 Web | 80 | 18082 | 用户聊天界面 |
+| 唐僧叨叨 Manager | 80 | 18083 | 后台管理 |
+| MinIO | 9000 / 9001 | 19000 / 19001 | 文件服务及其控制台 |
+
+所有映射通过 `HOST_BIND_IP` 精确绑定到指定宿主机网卡。当前部署目标为 Tailscale 地址 `100.121.118.116`，同时 `EXTERNAL_IP` 设为该地址，以供客户端连接。数据库、Redis 和容器间 gRPC 不发布到宿主机；如需进一步收紧公开面，可取消 Manager、监控和 MinIO 的端口映射。
+
+## LineUp 集成边界
+
+基础 IM 环境与 LineUp Agent 集成分两个阶段验收：
+
+1. 先验证唐僧叨叨用户注册、登录、单聊/群聊、文件上传和服务重启后的数据持久化。
+2. 再设计 LineUp 中转适配器。适配器需要处理 WuKongIM 的认证、频道/会话、收发消息及自定义消息载荷；其实现应基于官方 SDK 或严格按已验证协议开发。
+
+`tool.call` 和 `tool.result` 仍由 LineUp 定义，但需要先确定与唐僧叨叨/WuKongIM 消息扩展机制的精确映射，不能把尚未验证的 JSON WebSocket 假设写入生产实现。
+
+## 部署与验收
+
+> 该阶段的唐僧叨叨 v1.5 + WuKongIM v2 Compose 套件已于 2026-08-03 退役并从仓库移除。本记录仅保留当时的方案历史；当前本地 IM 环境见 [`infra/wukongim-v3/`](../../infra/wukongim-v3/)。