Files

T

freedak f7a720204a Update: 将子项目从 submodule 转为完整内容

- 移除 GovAI, nomifun-tauri, 算力盒子 的 submodule 引用
- 添加所有子项目的完整源代码
- 保留原始 .git 为 .git.bak 备份

2026-07-04 19:20:46 +08:00

6.2 KiB

Raw Permalink Blame History

Remote 能力 API（外部伙伴 / MCP 接入指南）

NomiFun 把整个平台的能力（agent / browser / computer / 知识库 / 文件 / 以及平台控制）通过一个网络可达、伙伴访问令牌鉴权的 MCP 端点暴露出来。任何 MCP 客户端（Claude Code、Cursor、自研 LLM agent）填一个 URL + 一枚访问令牌，就能像"桌面伙伴"一样驱动平台——这就是"外部伙伴"。每枚令牌绑定到一个具体伙伴：持令牌调用即以该伙伴的身份运行，继承它的 profile 模型 / 人格 / 知识库，互不串扰。

📋 可复制的对接示例（MCP 客户端 / curl / Python / CLI / 自动化 / OpenAPI codegen / LLM 框架）见 remote-capability-api-examples.zh.md。

⚠️ 安全须知

持有伙伴访问令牌即可调用平台能力，等价于授予远程代码执行（RCE）能力（可驱动 agent、读写文件、操作 computer/browser）。因此：

只把令牌交给你信任的客户端/agent。
仅在可信网络暴露；公网暴露务必前置 TLS 反代 + 防火墙。
令牌可随时吊销/轮换（见下）；吊销只影响对应伙伴，其它伙伴的令牌不受影响。
默认安全栏：危险能力（secret.*、system.factory_reset 等）在 Remote 面被拒；破坏性操作需二次确认（协议级握手，见「权限模型」）。

端点

/mcp（MCP Streamable-HTTP）随后端进程内挂载，与 WebUI 共用监听器：

本机：http://127.0.0.1:<port>/mcp（桌面应用的回环端口，或 nomifun-web 的服务端口）
局域网/远程：开启 WebUI 远程访问后 http://<你的IP>:25808/mcp

鉴权：HTTP 头 Authorization: Bearer <伙伴访问令牌>。

一、获取伙伴访问令牌

令牌只存哈希、明文只在铸造时返回一次，且绑定到一个具体伙伴（{id} = 伙伴 id）。两种获取方式：

桌面应用（本机可信客户端）

桌面 webview 自带本地信任，可直接调本地端点（也会有 UI 入口）。下文 <companion-id> 为要绑定的伙伴 id：

# 铸造（返回明文一次，并绑定到该伙伴）
curl -X POST http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token
# => {"success":true,"data":{"token":"<64位hex令牌>","companion_id":"<companion-id>"}}
#    若该伙伴尚无可用模型，data 还会带 "warning":"…"（令牌照常铸造，但 nomi_agent_run 等
#    需要模型的能力会失败，先去「模型管理」配置）

# 查询是否已配置（不返回令牌）
curl http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token
# => {"success":true,"data":{"configured":true}}

# 吊销
curl -X DELETE http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token
# => {"success":true,"data":{"configured":false}}

这些 /api/webui/companions/{id}/access-token 端点仅本地可信客户端可达（require_local_trust），远程浏览器拿不到。每个伙伴各持一枚令牌（再次铸造会覆盖旧令牌）。

无头服务器（headless `nomifun-web`）

无头部署用环境变量在启动时播种，绑定到默认伙伴（仅当该令牌尚未配置时生效，不覆盖已有；若实例中尚无任何伙伴会跳过并告警）：

NOMIFUN_COMPANION_TOKEN="$(openssl rand -hex 32)" \
  nomifun-web --host 127.0.0.1 --port 8787

把这串 hex 作为客户端的 Bearer 令牌。

二、连接 MCP 客户端

Claude Code / 通用 MCP 客户端（Streamable-HTTP）

{
  "mcpServers": {
    "nomifun": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:25808/mcp",
      "headers": { "Authorization": "Bearer <伙伴访问令牌>" }
    }
  }
}

连上后 tools/list 即可看到平台在 Remote 面暴露的工具（nomi_*）；tools/call 驱动。

三、权限模型（Remote 面）

外部调用方落在 Surface::Remote，权限矩阵：

能力危险级	Remote 行为
读 / 写	允许
破坏性（删除等）	需确认：先返回 `{"needs_confirmation":true,...}`，agent 复述动作征得用户同意后，带 `"confirm": true` 重试
敏感（`secret.*` / `factory_reset`）	拒绝（默认不在 Remote 暴露）

被拒的工具不出现在 tools/list（更好的 UX + 纵深防御）。

四、能力继承

平台能力通过同一条能力总线（nomifun-gateway 的 Capability Registry）暴露到 MCP/HTTP/CLI/Skill 等外部面。新增能力时，应同时评估它是否适合 Remote surface、是否需要确认，以及是否应进入 /mcp-agent 精简集。

调用方以令牌所绑定的伙伴身份运行：继承该伙伴的 profile 模型、人格与知识库，伙伴之间彼此隔离。因此 nomi_agent_run 在不显式指定 model 时，会解析所绑定伙伴的 profile 模型——该伙伴必须配置好可用模型（否则铸造时会返回 warning，且需要模型的能力会失败）。

当前可用面

✅ MCP：/mcp（全量 ~140 工具）+ /mcp-agent（curated 干活子集）。
✅ 委派目标：nomi_agent_run(goal,workspace?,model?,timeout_secs?) 一句话把任务交给一个自治 nomi agent，跑完返回终稿；长任务返回 {status:running} 句柄，用 nomi_agent_result(conversation_id) 轮询。
✅ HTTP REST：POST /v1/tools/{name}、GET /v1/tools[?profile=agent]、GET /v1/openapi.json[?profile=agent]（OpenAPI 3.1，同令牌）。
✅ CLI：nomicore tools（离线列能力）、nomicore call <name> [json]、nomicore agent "<目标>"（读 NOMIFUN_URL/NOMIFUN_COMPANION_TOKEN 或 --url/--token）。
✅ Skill：docs/skills/drive-nomifun/SKILL.md —— 教外部 agent 如何连上并驱动 NomiFun（可发布到技能市场）。
✅ Computer：桌面版（computer-use 构建）暴露 nomi_computer_*（snapshot/click/type/key/scroll/launch/screenshot/…），外部调用方可驱动桌面（headless/web 构建不含）。
✅ 流式：POST /v1/tools/{name}/stream（SSE）—— 流式工具（如 nomi_agent_run）实时吐 {type:..} delta，末帧 {type:"__result__"} 带终值；非流式工具仅末帧。nomi_agent_run 已流式（订阅 agent 广播逐条转发）。

6.2 KiB Raw Permalink Blame History Unescape Escape