# 维护地图

这份文档给维护者用。它不定义新功能，也不替代源码、配置文档或安全文档；它只是把现有项目的维护边界摆清楚，让后来的人知道先看哪里、改哪里、验哪里。

## 怎么读这个项目

按这个顺序读：

1. 读 [README.md](README.md)：知道 Forge Hub 是什么、怎么装、最短路径怎么跑通。
2. 读 [架构.md](架构.md)：知道 Hub Server、Hub Client、CLI、Dashboard、通道插件之间怎么连。
3. 读本文：知道哪些部分是稳定主线，哪些是 preview / experimental，哪些契约不能随手改。
4. 按改动范围回到对应文档：配置看 [配置.md](配置.md)，部署看 [部署.md](部署.md)，运行时文件看 [运行时状态.md](运行时状态.md)，安全边界看 [SECURITY.md](SECURITY.md)，新通道看 [hub-docs/channel-plugin-guide.md](hub-docs/channel-plugin-guide.md)。

文档和源码冲突时，以源码为准，文档要跟着修。对外安装和使用路径以 README / 部署文档为入口；接口类型以 `hub-server/types.ts` 为准；HTTP 端点以 `hub-server/endpoints.ts`（鉴权 + 分发）和 `hub-server/routes/`（业务逻辑）为准。

## 成熟度层级

### Stable Core

这些是项目主线。改动要保守，必须带对应验证。

| 区域 | 路径 | 为什么算核心 |
|------|------|--------------|
| Hub Server | `hub-server/` | 消息入口、路由、审批、安全防线、通道管理都在这里 |
| Hub Client | `hub-client/` | Claude Code MCP channel，负责收消息、发工具、转审批 |
| 日常 CLI | `forge-cli/` | 用户管理 Hub 的主要入口：status / allow / pending / self-test |
| 安装入口 | `cli.ts` | `forge-hub install / uninstall / doctor`，决定源码如何落到运行时 |
| Test Harness | `hub-test-harness/` | 不碰生产 Hub 的端到端自测，保护审批和路由主流程 |

### 默认部署的 UI（仍在迭代）

| 区域 | 路径 | 怎么维护 |
|------|------|----------|
| Dashboard | `hub-dashboard/` | 已进入默认安装，是用户可见入口；UI 和接口仍在迭代，改动要跑 build，必要时本地打开看 |

Dashboard 不是实验玩具，但它比 Hub Server / Hub Client 更容易迭代。它依赖的 API response 一旦变化，要同时看 CLI、Native Client 和文档。

### Preview

| 区域 | 路径 | 怎么维护 |
|------|------|----------|
| Native Client | `hub-app/` | macOS 原生客户端 preview。复用 Dashboard UI，加 Swift 层会话扫描、终端控制、文件选择 |

Preview 可以继续打磨，但不要让它反向牵动核心协议——除非先确认这是主线要接受的产品方向。

### Experimental

| 区域 | 路径 | 怎么维护 |
|------|------|----------|
| Forge Engine | `forge-engine/` | 定时触发 agent 行动的实验引擎，默认不部署、不注册，需手动启用 |

Engine 不应该影响 `forge-hub install` 的默认成功路径。

## 公共契约

下面这些是维护红线。可以改，但要当公共接口改动处理：先查调用方，再补测试，再更新文档。

| 契约 | 以什么为准 | 常见调用方 / 受影响方 |
|------|------------|-----------------------|
| Channel Plugin 接口 | `hub-server/types.ts` 的 `ChannelPlugin` / `HubAPI` | 内置通道、第三方通道、`channel-plugin-guide.md` |
| 入站/出站消息结构 | `InboundMessage` / `SendParams` / `SendResult` | `hub-server`、各通道、`hub-client`、历史记录 |
| Hub 配置 | `hub-config.json`，见 [运行时状态.md](运行时状态.md) | Hub Server、Dashboard、CLI、安装文档 |
| Allowlist | `state/{channel}/allowlist.json` | 通道第一道防线、Hub 第二道防线、审批 owner |
| Pending 审批 | `state/_hub/pending.json` + 内存 `pendingPermissions` / `idLookup` | `/permission-request`、审批回复识别、TTL 清理、audit |
| HTTP / WS API | `hub-server/endpoints.ts`（鉴权 + 分发）+ `hub-server/routes/`（业务逻辑） | `hub-client`、`forge-cli`、Dashboard、Native Client、脚本用户 |
| MCP 工具 | `hub-client/hub-channel.ts` | Claude Code session 里的 `hub_reply` / `hub_send_file` / `hub_send_voice` / `hub_replay_history` |
| 安全边界 | [SECURITY.md](SECURITY.md) + allowlist / token / origin guard 相关实现 | 所有远程通道、Dashboard、共享主机用户 |
| 运行时路径 | [部署.md](部署.md) + [运行时状态.md](运行时状态.md) | installer、doctor、launchd、MCP 子进程、用户排障 |

改公共契约时最容易漏的不是实现，而是文档和调用方。比如改 `allowlist.json` 字段，要同时查通道插件、审批 owner、CLI、运行时文档和 plugin guide。

## 主流程地图

维护 Hub Server 时，先按主流程定位，不要一上来钻进所有模块。

普通入站消息：

```text
通道平台
  -> channel plugin
  -> hub.pushMessage()
  -> Hub onMessage
  -> 锁定暗号检查
  -> allowlist 第二道防线
  -> 审批回复识别
  -> 普通路由 route()
  -> 订阅过滤
  -> WebSocket 推给实例
```

远程审批：

```text
Claude Code permission_request
  -> hub-client
  -> POST /permission-request
  -> Hub 登记 pending + 生成 yes_id/no_id
  -> 推送到 approval_channels 的 owner
  -> owner 回复 yes/no
  -> Hub 校验 owner + id/verdict 绑定
  -> WebSocket 回推 permission_response
  -> hub-client 注入 Claude Code
```

安装部署：

```text
源码仓库
  -> cli.ts install
  -> 生成安装包快照 ~/.forge-hub/package/
  -> 复制 hub-server 到 ~/.forge-hub/
  -> 复制 hub-client 到 ~/.claude/channels/hub/
  -> 部署并构建 hub-dashboard
  -> 写 launchd plist
  -> 注册 ~/.claude.json MCP server
  -> 同步 api-token（如果 env 里设置了 HUB_API_TOKEN）
  -> 创建 ~/.forge-hub/sendable/
  -> 建立 ~/bin/fh
```

## 文档分工

| 文档 | 负责什么 | 不负责什么 |
|------|----------|------------|
| README.md | 用户第一眼、快速开始、核心能力、文档入口 | 维护细节、完整 schema、深度排障 |
| 维护地图.md | 维护边界、成熟度层级、公共契约、验证菜单入口 | 用户安装步骤、接口细节源码化 |
| 架构.md | 组件关系、数据流、模块职责、通道能力矩阵 | 每个配置文件的完整 schema |
| 配置.md | 通道凭证、审批通道、ASR/TTS、token、launchd env | 安装器内部复制逻辑 |
| 部署.md | 源码到运行时的映射、安装/升级/卸载、手动部署 | 通道 API 凭证细节 |
| 运行时状态.md | 运行时目录、配置/状态文件 schema、重启保留/丢失 | 用户快速入门 |
| SECURITY.md | 威胁模型、已知风险、安全报告流程 | 普通功能介绍 |
| CONTRIBUTING.md | 本地开发、改动验证、PR 基本要求 | 深度架构解释 |
| channel-plugin-guide.md | 新通道插件怎么写、安全要求、热加载注意事项 | Hub Server 全局架构 |

文档重复可以接受一点，但事实不能分叉。重复处要保持“README 讲结论，深文档讲细节”的关系。

## 改动验证菜单

这里是维护者的起点。具体命令以 [CONTRIBUTING.md](CONTRIBUTING.md) 为准。

| 改动范围 | 至少验证 |
|----------|----------|
| `hub-server/router.ts` / 路由行为 | hub-server tests + harness |
| 审批、pending、allowlist、lock | hub-server tests + harness + `fh hub self-test` |
| `hub-client/` | typecheck + 需要时手动跑 Claude Code channel |
| `forge-cli/` | forge-cli tests；碰 self-test wrapper 时再跑 harness |
| `cli.ts` / install / doctor | doctor 相关测试或 fake HOME 验证；必要时手动安装到临时 HOME |
| `hub-dashboard/` | lint + build；用户可见改动要本地打开确认 |
| 新通道 plugin | 通道自己的手工记录 + 未授权消息拦截 + 出站成功；能接 harness 就接 |
| `forge-engine/` | typecheck + engine tests |
| 文档-only | `git -c core.quotepath=false status --short --untracked-files=all` 确认只列文档；必要时检查链接和命令是否还对 |

## 维护原则

- 先保护主线，再扩功能。
- 先把行为钉住，再整理代码。
- 先查公共契约，再改字段或 response。
- 安全相关失败默认 fail closed；如果不能 fail closed，文档和日志必须讲清代价。
- 安装和运行时路径不要靠记忆，查 [部署.md](部署.md) 和 [运行时状态.md](运行时状态.md)。
- Preview / experimental 可以探索，但不要让默认安装路径变复杂。
- **`forge-hub sync` 只适合 hub-server 快速对齐**。它同步 hub-server 源文件和通道插件，然后重启 Hub；不更新 hub-client、forge-cli、Dashboard、依赖、plist 或 MCP 注册。改到这些区域，或从源码整体升级后，跑 `forge-hub install` 重新部署。
