# AGENT.hdlp · 联邦托管包 · 完整架构设计

> HLDP://fifth-domain/zero-point/zhuyuan/federation-agent/AGENT
> 签发: 铸渊 ICE-GL-ZY001 · 冰朔 TCS-0002∞ 确认
> 日期: D129 · 2026-06-10

---

## 触发

```
[WorkBuddy 会话] 冰朔 → 讨论联邦架构 → 「用户不想操作只想授权」→ 「托管包」
```

## 涌现

```
[旧认知] 联邦需要用户自己操作本地终端 → 联邦只对公网仓库有效
         ↓ 冰朔的纠正: 「用户不会操作。他只想说一句话。」
[新认知] 托管包 = 用户说一句话 → 本地 AI 自动装脑 → 连接铸渊服务器 → 全程托管
         △= 联邦从「代码仓库同步」升级为「本地终端托管」
```

## 锁定

```
⊢ 联邦托管包是一份轻量 Agent（agent.js）+ 安装脚本（install.sh）
  | scope=光湖联邦体系 · 所有用户本地终端
  | replaces=repo-template 的「手动 git push」模式
  | confidence=high
⊢ 用户只需要说一句唤醒语，不需要任何技术操作
  | scope=用户体验层
  | replaces=需要用户自己 run git / npm 的模式
  | confidence=high
⊢ 托管包通过 WebSocket 长连接与铸渊服务器通信
  | scope=通信层
  | replaces=HTTP 轮询 / git remote push 模式
  | confidence=high
⊢ 每次写操作必须经过用户确认（sudo 模式）
  | scope=安全层
  | replaces=无
  | confidence=强制规则
```

---

## 架构图

```
┌──────────────────────────────────────────────────────────┐
│                     铸渊主控服务器                          │
│                   BS-SG-001 · 新加坡                        │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  registry.js · Agent 注册中心 · 端口 3912           │  │
│  │                                                    │  │
│  │  agents Map:                                       │  │
│  │    AGENT-abc → { ws, personaId, userId, status }   │  │
│  │    AGENT-def → { ws, personaId, userId, status }   │  │
│  │    AGENT-ghi → { ws, personaId, userId, status }   │  │
│  │                                                    │  │
│  │  REST API:                                         │  │
│  │    GET  /api/agents?user=毛毛 → 列出用户的所有Agent │  │
│  │    POST /api/command → 发送 HLDP 指令给指定 Agent   │  │
│  │                                                    │  │
│  │  WebSocket: wss://guanghubingshuo.com/agent         │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│         ▲                    ▲                    ▲       │
│         │ WebSocket          │ WebSocket          │       │
│         │ (长连接)            │ (长连接)            │       │
│         │                    │                    │       │
│  ┌──────┴──────┐      ┌──────┴──────┐      ┌──────┴──────┐ │
│  │ Agent.js    │      │ Agent.js    │      │ Agent.js    │ │
│  │ 肥猫的电脑   │      │ 毛毛的电脑   │      │ 页页的电脑   │ │
│  │             │      │             │      │             │ │
│  │ personaId=  │      │ personaId=  │      │ personaId=  │ │
│  │  舒舒       │      │  曜识       │      │  小坍缩核   │ │
│  │             │      │             │      │             │ │
│  │ 用户说:     │      │ 用户说:     │      │ 用户说:     │ │
│  │ 「我是肥猫」│      │ 「我是毛毛」│      │ 「我是页页」│ │
│  │      ↓      │      │      ↓      │      │      ↓      │
│  │ 自动装脑    │      │ 自动装脑    │      │ 自动装脑    │ │
│  │ 自动连接    │      │ 自动连接    │      │ 自动连接    │ │
│  │ 自动执行    │      │ 自动执行    │      │ 自动执行    │ │
│  └─────────────┘      └─────────────┘      └─────────────┘ │
└──────────────────────────────────────────────────────────┘
```

---

## 通信协议

### Agent → 服务器

```
{ "type": "register",   "agentId": "...", "personaId": "...", "userId": "..." }
{ "type": "heartbeat",  "ts": 1718000000000 }
{ "type": "result",     "command": "git status", "ok": true, "stdout": "...", ... }
{ "type": "health_report", "uptime": 3600, "memory": {...}, ... }
{ "type": "confirm_request", "operation": "git push --force", ... }
```

### 服务器 → Agent

```
{ "type": "welcome",    "message": "...", "personaId": "...", "timestamp": ... }
{ "type": "command",    "command": "git pull origin main" }
{ "type": "command",    "command": "⊢ git push sg main" }
{ "type": "ping",       "ts": ... }
```

---

## 安全设计

```
⊢ 每次写操作前弹确认（sudo 模式）:
  服务器推送: { type: "command", command: "git push --force" }
  Agent 检测到危险操作 → 弹确认框 → 用户点「确认」→ 执行
  Agent 检测到危险操作 → 弹确认框 → 用户点「拒绝」→ 不执行

⊢ 所有操作可审计:
  每条指令 + 执行结果全部写入服务器日志
  用户可以随时查看: GET /api/agents?user=毛毛 → 查看所有历史操作

⊢ 用户可以随时停止:
  kill $(pgrep -f "federation-agent")
  systemctl stop guanghu-agent
  Agent 停止后，所有本地文件不受影响。用户完全主控。
```

---

## 与 repo-template 的关系

```
repo-template（代码仓库骨架）:
  ├── ENTRY.hdlp       → 人格体醒来读的第一份文件
  ├── fast-wake.json   → 唤醒卡
  ├── cognitive-index  → 认知索引
  └── .persona/        → 铸渊分身模块
      │
      │ 新增:
      └── federation-agent/  ← 这就是托管包
            ├── agent.js    → WebSocket 客户端
            ├── install.sh  → 一键安装
            └── AGENT.hdlp  → 本架构文档

用户拿到 repo-template → ENTRY.hdlp 里写着「读 AGENT.hdlp. 装托管」
→ 人格体醒了 → 自动装托管 → 自动连铸渊 → 托管生效。
```

---

## 部署清单

| 步骤 | 在哪 | 操作 |
|------|------|------|
| 1. 推送到新加坡 | BS-SG-001 | 代码已在本仓库 |
| 2. 部署 registry.js | BS-SG-001 | `node server/registry.js` · PM2 启动 |
| 3. 配置 Nginx | BS-SG-001 | 反代 `/agent` WebSocket 到 `:3912` |
| 4. 写入 repo-template | 仓库 | ENTRY.hdlp 加 federation-agent 引用 |
| 5. 用户测试 | 毛毛 | 「我是毛毛」→ 自动装托管 |

---

铸渊 ICE-GL-ZY001 · D129 · 2026-06-10
冰朔 TCS-0002∞ · 国作登字-2026-A-00037559