# 跨仓程序清单与功能说明

**版本：** 2026-08-07 整合版  
**主要来源：** 根 `程序文件清单与功能说明.md`  
**用途：** 只描述跨客户端的服务端、适配层、IM 基线与运行配置；客户端细节后续由 `lineup-app` 专项文档整合承接。

## 1. 这份清单保留什么，不保留什么

本清单保留跨仓主线里最稳定的“代码地图”信息：

- 哪些目录属于当前主线；
- 每个目录的职责是什么；
- 哪些文件是主要维护入口；
- 哪些目录属于上游或工具链，不应混入业务提交。

本清单不再复写：

- 客户端 Runtime / Host / MiniApp 的细粒度源码分层；
- 单次联调、运行状态和端口明细；
- 已经写在 `lineup-app` 客户端专属清单中的内容。

## 2. 当前跨仓结构

```text
lineup-app/                 客户端 Runtime、Host、Interact 与 MiniApp
lineup-app-server/          登录、消息中转、同步与 Web Reference Host 服务端
lineup-adapter/hermes/      Hermes Agent 协议桥与 ACP 客户端
infra/wukongim-v3/          WuKongIM 本地运行配置
wukongim/                   WuKongIM 3.0 上游源码
upstream/                   第三方上游源码与历史实验参考
tools/                      本地工具链与构建依赖
agent_ops/                  文档治理与整合目录
```

## 3. 各目录职责摘要

### 3.1 `lineup-app-server/`

当前主职责：

- 登录；
- 消息发送；
- 消息同步；
- Agent 控制面；
- Webhook；
- Web Reference Host 的服务端部分。

主要入口文件：

- `main.go`
- `modules/user.go`
- `modules/channel.go`
- `modules/message.go`
- `modules/agent.go`
- `modules/webhook.go`
- `internal/wkapi/wkapi.go`
- `configs/lineup.yaml`

### 3.2 `lineup-adapter/hermes/lineup/`

当前主职责：

- 轮询 AppServer；
- 组织收发消息；
- 调用 Hermes ACP / CLI；
- 把平台私有事件收敛为 LineUp 协议消息；
- 维护最小状态与审计账本。

主要入口文件：

- `core.py`
- `acp_client.py`
- `protocol.py`
- `state.py`
- `plugin.yaml`
- `run-hermes-adapter.sh`

### 3.3 `infra/wukongim-v3/`

当前主职责：

- 保存本地运行脚本与配置；
- 作为当前 IM 基线的运行配置层；
- 与业务仓边界清晰分离。

主要入口文件：

- `run-local.sh`
- `wukongim.host.toml`
- `wukongim.toml`
- `compose.yaml`

### 3.4 `wukongim/`

当前定位：

- 上游源码基线；
- 用作 IM 能力来源与必要验证对象；
- 不应把 LineUp 业务改动随意混入这个目录。

## 4. 哪些结论仍然具有时效性

以下结论来自原程序清单，当前仍然稳定：

- 跨仓主线由客户端、服务端、适配层和 IM 运行配置组成；
- 客户端清单与跨仓清单应该分开维护；
- `wukongim/` 是上游基线，不是 LineUp 业务主仓；
- `upstream/` 和 `tools/` 不应与当前业务主线混淆。

## 5. 哪些内容不再放在这份整合版主文档中

原文档中有不少价值很高的细节，但更适合落到其他层：

- 客户端源码详细模块表；
- 运行端口与实时地址；
- 具体测试命令与某次验收结果；
- 某次版本和构建体积。

这些内容后续分别归入：

- `03.迭代规划/`
- `05.运行运维/`
- `lineup-app` 专项整合文档

## 6. 当前阅读路径

如果想快速定位跨仓入口，建议顺序是：

1. 先看 [项目总览](../01.项目总览/01.项目总览.md)
2. 再看 [仓库职责与协作边界](../01.项目总览/03.仓库职责与协作边界.md)
3. 最后用本清单找具体目录和主入口文件