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

- 移除 GovAI, nomifun-tauri, 算力盒子的 submodule 引用 - 添加所有子项目的完整源代码 - 保留原始 .git 为 .git.bak 备份
2026-07-04 19:20:46 +08:00
parent 54d6465fa7
commit f7a720204a
3360 changed files with 802660 additions and 3 deletions
@@ -0,0 +1,185 @@
+# Remote Capability API
+
+NomiFun can expose its platform capabilities through a network-reachable,
+token-authenticated MCP and REST front door. A trusted external agent or MCP
+client can connect with a URL plus a companion access token and then call the
+same capability registry used by the desktop app.
+
+Each token is bound to one companion. Calls made with that token run as that
+companion and inherit its profile model, persona, and knowledge context.
+
+For copy-ready integrations, see
+[Remote Capability API Examples](./remote-capability-api-examples.md).
+
+## Security Model
+
+A companion access token is high privilege. It can drive agents, read and
+write files through exposed tools, and in desktop builds may operate browser or
+computer-use capabilities. Treat it like remote code execution authority:
+
+- Give tokens only to clients and agents you trust.
+- Prefer loopback, VPN, or a private network.
+- Put TLS, firewall rules, and rate limits in front of any public exposure.
+- Rotate or revoke tokens immediately if they leave your control.
+- Sensitive tools such as secrets and factory reset are not exposed on the
+  remote surface by default.
+- Destructive tools require a confirmation retry: the first call returns a
+  confirmation challenge; the caller must show the action to the user and retry
+  with `confirm: true`.
+
+## Endpoints
+
+The network front door is mounted by the same backend process as the Web UI.
+
+| Endpoint | Purpose |
+| --- | --- |
+| `/mcp` | Full Streamable-HTTP MCP server. |
+| `/mcp-agent` | Curated MCP profile for external working agents. |
+| `/v1/tools` | REST tool discovery. Add `?profile=agent` for the curated set. |
+| `/v1/tools/{name}` | REST tool call. |
+| `/v1/tools/{name}/stream` | SSE streaming wrapper for tools that emit progress. |
+| `/v1/openapi.json` | OpenAPI 3.1 description for the REST tool surface. |
+
+Authenticate every request with:
+
+```http
+Authorization: Bearer <companion-access-token>
+```
+
+Common base URLs:
+
+- Desktop remote access: `http://<LAN-IP>:25808`
+- Standalone server: `http://<host>:8787` unless you changed the port
+- Local development or embedded desktop backend: `http://127.0.0.1:<port>`
+
+## Creating A Companion Token
+
+Tokens are stored hashed. The plaintext token is shown only once.
+
+### Desktop App
+
+Use the Open Capabilities / remote access UI, or call the trusted local API
+from the desktop WebView context:
+
+```bash
+curl -X POST \
+  http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token
+```
+
+The response returns the plaintext token once:
+
+```json
+{
+  "success": true,
+  "data": {
+    "token": "<64-character-hex-token>",
+    "companion_id": "<companion-id>"
+  }
+}
+```
+
+Status and revoke use the same path:
+
+```bash
+curl http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token
+
+curl -X DELETE \
+  http://127.0.0.1:<loopback-port>/api/webui/companions/<companion-id>/access-token
+```
+
+These token-management endpoints require local trust. A remote browser or plain
+curl client cannot mint tokens.
+
+### Headless `nomifun-web`
+
+Seed a token at startup with `NOMIFUN_COMPANION_TOKEN`. The value binds to the
+default companion when no token is already configured:
+
+```bash
+NOMIFUN_COMPANION_TOKEN="$(openssl rand -hex 32)" \
+  nomifun-web --host 127.0.0.1 --port 8787
+```
+
+Use the generated hex string as the Bearer token. For non-local exposure,
+finish admin setup first and put the server behind TLS.
+
+## MCP Client Configuration
+
+Example Streamable-HTTP MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "nomifun": {
+      "type": "streamable-http",
+      "url": "http://127.0.0.1:25808/mcp-agent",
+      "headers": {
+        "Authorization": "Bearer <companion-access-token>"
+      }
+    }
+  }
+}
+```
+
+Use `/mcp-agent` when an external agent mostly needs work tools
+(agent/browser/computer/knowledge/files). Use `/mcp` when you intentionally
+want the broader platform control surface.
+
+## REST Tool Calls
+
+Discover tools:
+
+```bash
+curl -s "http://127.0.0.1:25808/v1/tools?profile=agent" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Run a delegated NomiFun agent task:
+
+```bash
+curl -s -X POST "http://127.0.0.1:25808/v1/tools/nomi_agent_run" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"goal":"Research competitors and write notes.md","timeout_secs":600}'
+```
+
+Poll a long-running task:
+
+```bash
+curl -s -X POST "http://127.0.0.1:25808/v1/tools/nomi_agent_result" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"conversation_id":123}'
+```
+
+Successful REST calls return `200 {"result": ...}`. Tool validation failures
+return `422`, unknown tools return `404`, invalid tokens return `401`, and
+confirmation-required calls return `409`.
+
+## Streaming
+
+SSE streaming is available for tools that report progress:
+
+```bash
+curl -N -X POST "http://127.0.0.1:25808/v1/tools/nomi_agent_run/stream" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"goal":"Summarize the current repository"}'
+```
+
+Each event is a `data: <json>` line. The final event uses
+`{"type":"__result__","data":{"result":...}}`.
+
+## Companion Context
+
+Because the caller runs as the bound companion, `nomi_agent_run` can use that
+companion's configured model when no `model` argument is supplied. Configure a
+usable provider/model for the companion before relying on model-backed tools;
+token creation may warn if the companion has no usable model.
+
+## Related Docs
+
+- [Remote Capability API Examples](./remote-capability-api-examples.md)
+- [WebUI Remote Access](./webui-remote-access.md)
+- [Web Server Deployment](./web-server-deployment.md)
+- [Computer Use And Browser Use](./computer-browser-use.md)