初始化 agent_ops 文档治理体系

2026-08-07 16:56:51 +08:00
commit 10840909ab
75 changed files with 15750 additions and 0 deletions
@@ -0,0 +1,114 @@
+# 2026-08-03 运行基线与验证记录
+
+**记录日期：** 2026-08-03  
+**来源：** 根目录 `项目状态记录.md`  
+**用途：** 保存当时已经核验过的运行事实、技术基线和验证结论，作为历史运行基线，而不是当前实时状态页。
+
+## 1. 这份记录为什么仍然有价值
+
+`项目状态记录.md` 里最有价值的内容，不是“某个端口此刻在线”，而是以下几类长期信息：
+
+- 当时已经跑通的系统主线是什么；
+- 哪条技术路线已经退役、哪些边界已经明确；
+- 核心组件之间如何协作；
+- 哪些问题是结构性的，后续仍需要记住；
+- 哪些运行细节属于 2026-08-03 的历史快照，不能直接当作今天状态。
+
+因此，本文件把 2026-08-03 的内容保留为**历史基线**。
+
+## 2. 当时已经确认的主线架构
+
+截至 **2026 年 8 月 3 日**，项目已经形成如下运行主线：
+
+```text
+客户端 / Host
+  → AppServer
+  → WuKongIM 3.0
+  → Hermes Adapter
+  → Hermes
+```
+
+当时已确认的长期有效结论：
+
+- 当前 IM 主线基于 **WuKongIM 3.0**，不是旧的 WuKongIM v2；
+- LineUp 业务层采用 **AppServer + Hermes Adapter** 的组合；
+- 客户端与 Agent 的连接不再以唐僧叨叨旧业务栈为主线；
+- 历史唐僧叨叨本地环境已经退役，只保留背景参考价值。
+
+## 3. 当时已经明确的技术基线
+
+### 3.1 通讯与存储
+
+- WuKongIM 3.0 官方 `main` 是当前通讯层基线；
+- 单节点集群使用 PebbleDB 持久化；
+- 当前核心启动不依赖 MySQL / Redis。
+
+### 3.2 业务层
+
+- `lineup-app-server/` 负责登录、路由、消息收发、消息同步与 Webhook；
+- `lineup-adapter/hermes/lineup/` 负责 Hermes 对接、协议桥接与会话调用。
+
+### 3.3 客户端形态
+
+截至 2026-08-03，当时记录中仍包含 Android 实验链路与 Web Host 验证链路。  
+这部分内容的历史价值在于说明项目曾经同时验证过多种前端承载方式，但它们不应自动等同于今天的唯一产品形态。
+
+## 4. 当时已经验证通过的高价值事实
+
+以下事实具有较强保留价值，因为它们说明“这条路线曾经真实跑通过”：
+
+- Hermes Adapter 与 AppServer 的端到端消息链路已验证；
+- AppServer 的 Webhook 接入已验证；
+- Adapter 对 HTTP 与 Hermes CLI 已设置超时；
+- SQLite 已用于 inbox/outbox/cursor 等最小持久化；
+- WuKongIM 3.0 单节点本地运行链路已验证可用；
+- 旧唐僧叨叨 Compose 套件已从当前主线中移除。
+
+## 5. 从今天看仍然值得保留的工程结论
+
+### 5.1 已退役路线必须继续保持退役
+
+这份记录明确说明：
+
+- 唐僧叨叨 v1.5 + WuKongIM v2 本地套件已退役；
+- 后续不得再把旧兼容性假设混入当前主线结论。
+
+这条边界今天仍然重要。
+
+### 5.2 运行时细节中的两个关键坑
+
+这份记录里有两条非常有价值的“踩坑结论”：
+
+- WuKongIM `/channel/messagesync` 的 `start_message_seq` 是**包含式**；
+- Adapter / Agent 侧 HTTP 请求必须设置超时，避免挂死。
+
+这两条都值得继续保留，因为它们是会反复影响实现正确性的工程事实。
+
+### 5.3 密钥与部署边界必须明确
+
+记录中明确提到：
+
+- `LINEUP_AGENT_SHARED_SECRET` 未进入私有 `.env` 时，部分在线状态判断不会成立；
+- 这类问题不一定阻断消息通路，但会影响部署完整性与上线判断。
+
+这类结论仍然值得保留为运维注意事项。
+
+## 6. 应被视为历史快照，而不是当前状态的内容
+
+以下内容应继续保留，但必须带日期阅读：
+
+- 当天在线的 IP、端口、URL；
+- 当天使用的提交号、版本号和 APK 体积；
+- 当天某台真机、某个 Web Host、某个 Manager 页面是否可访问；
+- 当天的已知问题、待办项和临时限制。
+
+这些内容对于追溯 2026-08-03 的系统状态有价值，但不应再作为“今天系统还处于该状态”的直接依据。
+
+## 7. 对根目录 `项目状态记录.md` 的整合结论
+
+从文档治理角度，这份源文档最有价值的部分已经分为两层：
+
+- 项目级阶段判断：应保留在 `agent_ops/01.项目总览/02.当前状态与阶段判断.md`
+- 历史运行基线与验证事实：应保留在本文件
+
+这能避免把“历史核验记录”和“当前项目总览”混在一份文档里继续膨胀。