添加中文文档
This commit is contained in:
101
docs/zh/setup-wiring.md
Normal file
101
docs/zh/setup-wiring.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# 安装连线——状态与剩余工作
|
||||
|
||||
最后更新：2026-04-09
|
||||
|
||||
## 已完成
|
||||
|
||||
### 双库拆分（Session DB 写入隔离）
|
||||
- Session DB 拆分为 `inbound.db`（宿主机拥有）和 `outbound.db`（容器拥有）
|
||||
- 每个文件有且仅有一个写入者——消除了跨越宿主机-容器挂载的 SQLite 写入竞争
|
||||
- 宿主机使用偶数 seq 号，容器使用奇数（无冲突）
|
||||
- 容器心跳通过文件 touch（`/workspace/.heartbeat`）而非 DB UPDATE
|
||||
- 调度 MCP 工具通过 messages_out 发出系统操作；宿主机在 `delivery.ts:handleSystemAction()` 中将其应用到 inbound.db
|
||||
- 宿主机 sweep 读取 `processing_ack` 表 + 心跳文件 mtime 以检测过期
|
||||
- 容器在启动时清除过期的 `processing_ack` 条目（崩溃恢复）
|
||||
- 文件：`src/db/schema.ts`（INBOUND_SCHEMA + OUTBOUND_SCHEMA）、`src/session-manager.ts`、`src/delivery.ts`、`src/host-sweep.ts`、`container/agent-runner/src/db/connection.ts`、`messages-in.ts`、`messages-out.ts`、`poll-loop.ts`、`mcp-tools/scheduling.ts`、`mcp-tools/interactive.ts`
|
||||
- 容器镜像已使用 tsconfig（`container/agent-runner/tsconfig.json`）重建
|
||||
- E2E 已验证：宿主机 → Docker 容器 → Claude 响应 → "E2E works!" ✓
|
||||
|
||||
### OneCLI 集成
|
||||
- 在 `src/container-runner.ts` 中，`ensureAgent()` 调用已添加在 `applyContainerConfig()` 之前
|
||||
- 如果没有 `ensureAgent`，OneCLI 会拒绝未知的 agent 标识符并返回 false，使容器没有凭据
|
||||
- E2E 已验证 OneCLI 凭据注入 ✓
|
||||
|
||||
### 频道 Barrel
|
||||
- `src/index.ts` 导入 `./channels/index.js`（barrel）
|
||||
- 主干仅提供 barrel + Chat SDK 桥接；`/add-<channel>` 技能将适配器文件放入并通过 barrel 槽注册
|
||||
- 主干不提供任何频道适配器
|
||||
|
||||
### 安装注册（部分完成）
|
||||
- `setup/register.ts` 在 `data/v2.db` 中创建实体（`agent_groups`、`messaging_groups`、`messaging_group_agents`）
|
||||
- 接受 `--platform-id` 标志
|
||||
- `getMessagingGroupAgentByPair()` 防止重复连线
|
||||
- `setup/verify.ts` 检查中央库（统计有连线的 agent group 数量）
|
||||
|
||||
### 路由日志
|
||||
- `src/router.ts` 在没有 agent 连线时以 WARN 级别记录 `MESSAGE DROPPED`，并提供可操作的指导
|
||||
|
||||
---
|
||||
|
||||
## 之前未完成——现已解决
|
||||
|
||||
### 1. ~~频道技能不注册 Group~~ ✅
|
||||
|
||||
频道技能现在在其"下一步"部分指向 `/manage-channels`。注册由 `/manage-channels` 技能处理，该技能读取每个频道的 `## Channel Info` 部分以获取平台特定指导。频道技能保持精简（仅凭据）。
|
||||
|
||||
### 2. ~~安装 SKILL.md 缺少 Group 注册步骤~~ ✅
|
||||
|
||||
在频道安装（第 5 步）和挂载白名单（第 6 步）之间添加了第 5a 步"将频道连接到 Agent Group"。此步骤调用 `/manage-channels`，它处理 agent group 创建、隔离级别决策和连线。
|
||||
|
||||
### 3. ~~频道技能应知道频道类型~~ ✅
|
||||
|
||||
每个频道技能都有一个结构化的 `## Channel Info` 部分，包含：type、terminology、how-to-find-id、supports-threads、typical-use、default-isolation。`/manage-channels` 技能读取这些信息以提供上下文建议。
|
||||
|
||||
### 4. ~~验证步骤频道认证检查~~ ✅
|
||||
|
||||
`setup/verify.ts` 检查所有频道 token：DISCORD_BOT_TOKEN、TELEGRAM_BOT_TOKEN、SLACK_BOT_TOKEN+SLACK_APP_TOKEN、GITHUB_TOKEN、LINEAR_API_KEY、GCHAT_CREDENTIALS、TEAMS_APP_ID+TEAMS_APP_PASSWORD、WEBEX_BOT_TOKEN、MATRIX_ACCESS_TOKEN、RESEND_API_KEY、WHATSAPP_ACCESS_TOKEN、IMESSAGE_ENABLED，以及 WhatsApp Baileys 认证目录。
|
||||
|
||||
### 5. Agent-Shared Session 模式 ✅
|
||||
|
||||
添加了 `session_mode: 'agent-shared'` 用于跨频道共享 session（例如 GitHub + Slack 在同一对话中）。当设置此模式时，Session 解析按 agent_group_id 而非 messaging_group_id 查找。
|
||||
|
||||
---
|
||||
|
||||
## 架构参考
|
||||
|
||||
### 实体模型
|
||||
```
|
||||
agent_groups (id, name, folder, agent_provider, container_config)
|
||||
↕ 多对多
|
||||
messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy)
|
||||
通过
|
||||
messaging_group_agents (messaging_group_id, agent_group_id, trigger_rules, session_mode, priority)
|
||||
|
||||
users (id, kind, display_name) -- 命名空间为 "<channel>:<handle>"
|
||||
user_roles (user_id, role, agent_group_id) -- owner / admin（全局或限定范围）
|
||||
agent_group_members (user_id, agent_group_id) -- 非特权访问关卡
|
||||
user_dms (user_id, channel_type, messaging_group_id) -- 冷启动 DM 缓存
|
||||
```
|
||||
|
||||
权限是用户级别的概念——没有"主"agent group 或"管理员"messaging group。`user_roles` 携带 `owner`（仅全局，首次配对设置）和 `admin`（全局或限定到一个 `agent_group_id`）。未知发送者门控是按 messaging group 的，通过 `messaging_groups.unknown_sender_policy`（`strict | request_approval | public`）。
|
||||
|
||||
### 消息流程
|
||||
```
|
||||
频道适配器 → routeInbound() → 解析 messaging_group → 通过 messaging_group_agents 解析 agent
|
||||
→ 解析/创建 session → 写入 inbound.db → 唤醒容器 → agent-runner 轮询 inbound.db
|
||||
→ agent 响应 → 写入 outbound.db → 宿主机投递轮询读取 outbound.db → 通过适配器投递
|
||||
```
|
||||
|
||||
### 关键文件
|
||||
| 文件 | 用途 |
|
||||
|------|---------|
|
||||
| `src/index.ts` | 入口点，导入频道 barrel |
|
||||
| `src/channels/index.ts` | 频道 barrel——主干仅包含注册表/Chat SDK 桥接；技能将适配器放入 |
|
||||
| `src/router.ts` | 入站路由，自动创建 messaging group |
|
||||
| `src/session-manager.ts` | 为每个 session 创建 inbound.db + outbound.db |
|
||||
| `src/delivery.ts` | 轮询 outbound.db，投递，处理系统操作 |
|
||||
| `src/host-sweep.ts` | 同步 processing_ack，过期检测，重复执行 |
|
||||
| `src/container-runner.ts` | 启动容器，OneCLI ensureAgent + applyContainerConfig |
|
||||
| `setup/register.ts` | 创建实体（agent_group、messaging_group、连线） |
|
||||
| `setup/verify.ts` | 检查中央库中已注册的 group |
|
||||
| `container/agent-runner/src/db/connection.ts` | 双库连接层（inbound 只读，outbound 读写） |
|
||||
Reference in New Issue
Block a user