﻿P10-12 给 Hermes 加 NX 能力（不搬 DSH，写插件）

## 关键事实（2026-10-20 查证，禁止再猜）
Hermes Agent = Nous Research 开源框架（MIT），已有完整 agent 能力：
- 内置工具 `tools/`、插件 `plugins/`、技能 `skills/`、定时 `cron/`
- 消息网关 `gateway/`（支持多平台，QQ 应走 `plugins/platforms/`）
- 浏览器栈 `tools/browser_*`、出网防火墙 `agent/proxy_sources/iron_proxy.py`
- ACP（IDE 集成）`acp_adapter/`
- 官方文档：https://hermes-agent.nousresearch.com/docs/
  必读：Programmatic Integration、Adding Tools、Plugins、Gateway Internals、Skills
结论：**不要移植 DSH**，要给 Hermes 增加一个"NX 桥接工具/插件"。
服务器位置：`C:\HermesAgent\`（已在跑，禁止改它的核心文件）。

## 一、先读文档，对齐扩展方式（只读）
1. 读 `docs/developer-guide/adding-tools`、`plugins`、`programmatic-integration`、
   `gateway-internals`，弄清：
   - 自定义工具放哪个目录、用什么接口注册、如何声明参数 schema
   - 插件（plugin）与工具（tool）的区别，NX 桥接该用哪个
   - 外部程序如何以编程方式触发一次 agent 任务（REST？CLI？ACP？）
2. 查服务器 `C:\HermesAgent\plugins\platforms\` 里有没有 QQ 适配器，
   若有，记录平台名与配置方式（**只记录变量名，不读 token 值**）
3. 结论写 `docs\14_Hermes扩展方式.md`

## 二、实现 nx_bridge（Hermes 侧工具）
在 Hermes 的扩展位置（plugins 或 tools，按第 1 步结论）新增一个工具，例如 `nx_bridge`：
```
nx_run(kind, part, params, timeout_sec)   -> 任务下发到本地执行器，等待结果
nx_status(task_id)                        -> 查询状态
nx_files(tag)                             -> 列出产物文件（云端 outbox）
```
- 它**不直接跑 NX**，只把任务写进 `/C:/nxai-cloud/inbox/`，然后轮询 outbox
- 本地由 P10-11 的 `tools\cloud_bridge.py --watch` 领取并执行
- 超时返回明确错误（"本地未上线/任务超时"），不得假装成功

## 三、本地执行器配合（复用 P10-11）
- `cloud_bridge.py --watch` 已在本地跑：拉 inbox → 执行（needs_nx=true）→ 写 outbox → 更新 index
- 需要在 outbox 结果里包含：文件清单、尺寸、sha256、摘要、日志尾部
- 本地没开机时：任务留在 queued，nx_run 返回"本地离线，任务已排队"（这是正确行为）

## 四、护栏（必须实现，参考 Hermes 自带 egress firewall 的思路）
1. 白名单：`nx_run` 只允许 kind ∈ {prepare, stages, check, post, probe}
2. 路径约束：part 必须落在允许目录（`C:\Users\Administrator\Desktop\` 或 `E:\`），禁止 `C:\Windows`
3. 超时：单任务默认 30 分钟，超过标记 failed 并保留日志
4. 幂等：同 task_id 重复下发不重复执行
5. 审计：每次调用写一行 `C:\nxai-cloud\log\bridge_audit.jsonl`（时间/来源/kind/参数摘要/结果）
6. 失败不重试超过 3 次；连续失败进入"熔断"并在 QQ 通知

## 五、验收（实测）
1. `docs\14_Hermes扩展方式.md` 真实内容（工具注册方式、QQ 平台名、编程调用方式）
2. Hermes 侧 `nx_run` 被真实调用一次（可用 CLI 或 gateway 触发），
   贴出：它写入 inbox 的任务 JSON、本地执行器取到并回写 outbox 的结果、Hermes 收到的返回
3. 本地离线场景：停掉本地执行器，再调 `nx_run`，贴出"已排队/离线"的返回原文
4. 白名单与路径护栏：分别用一个非法 kind、一个 `C:\Windows\...` 路径测试，贴出拒绝信息
5. 审计日志 `bridge_audit.jsonl` 的真实几行
6. 门禁全绿 + 新增 .py 含 `P2-02 控制台编码护栏`

## 约束
- **禁止修改 C:\HermesAgent 的核心代码**；只能按官方扩展点（plugins/tools/skills）新增
- 不在服务器装软件、不改系统环境变量
- 不把 token/密码写进 D:\NX_AI
- 云端永远不尝试运行 NX
- 完成后写 `状态\P10-12.done.json`
