#软件连接（AI 服务）

状态：已实现（协议 version 4）
源码：py_tauri_works/src-tauri/src/host_bridge.rs、src/services/hostBridge/
设置入口：设置 → 软件连接

py_tauri_works 启动后在本机提供 HTTP AI 服务，供 Git Desk 等桌面工具调用已配置的模型与高价值能力。

监听地址为 0.0.0.0:14220，可用：

http://localhost:14220
http://127.0.0.1:14220
http://<本机局域网IP>:14220

工具侧默认填 localhost；跨设备/局域网访问时改用本机 IP。若内网仍连不上，检查 Windows 防火墙是否放行本应用入站。接口支持 CORS（Access-Control-Allow-Origin: *，含 OPTIONS 预检）。

与 MCP 连接 互补：

顶栏在有工具连入时显示「N 个集成工具已连接」，点击进入本页。页面可实时查看思考与输出；调用次数与 Token 计入 使用统计。

用户向导见 示例项目：Git Desk。

#能力一览

#OpenAI 兼容代理

供 OpenCodeReview、OpenAI SDK、Continue 等标准客户端对接。

#Cloudflare 快速隧道（Cursor 等）

Cursor 云端无法访问 127.0.0.1，需用 trycloudflare 公网 HTTPS：

1. 手动下载 cloudflared-windows-amd64.exe，放到应用 tools 目录或指定路径
2. 在「软件连接」生成并保存访问密钥
3. 点击「开启隧道」，复制公网 https://xxx.trycloudflare.com/v1
4. Cursor Override Base URL 填该地址，API Key 填访问密钥
5. 用完关闭隧道（退出应用也会停止）

隧道开启期间，本机直连 /v1 同样需要该访问密钥；/api/host/*（Desk 等）不受影响。

POST /v1/chat/completions
Authorization: Bearer local
Content-Type: application/json

{
  "model": "default",
  "messages": [{ "role": "user", "content": "你好" }],
  "stream": false
}

流式时返回标准 OpenAI SSE：data: {chunk} … data: [DONE]。

GET /v1/models
Authorization: Bearer local

OpenCodeReview 配置示例见源码旁 HOST_BRIDGE.md。

#1. 探活

GET /api/host/health

亦支持别名：GET /health。

version 为 4。典型字段：

GET /api/host/actions

列出当前对软件连接开放的 Action（含 via: POST /api/host/action）。

#2. 主动登记（推荐）

POST /api/host/register
Content-Type: application/json

{
  "clientId": "git-desk",
  "name": "Git Desk",
  "version": "0.1.0",
  "capabilities": ["git-commit", "sftp"],
  "mcpCommand": "python",
  "mcpArgs": "F:/.../mcp/server.py",
  "mcpCwd": "F:/.../mcp",
  "repoPath": "F:/my-repo",
  "meta": { "projectName": "webman-super" }
}

客户端超过约 90s 无心跳会被视为过期并从列表移除。

#3. 通用对话

外部软件应自行拼装 system / prompt；AI 服务不内置任何具体产品的业务提示词。

POST /api/host/chat
Content-Type: application/json

{
  "clientId": "my-tool",
  "source": "feature-x",
  "system": "可选系统提示",
  "prompt": "用户/工具拼好的提示词",
  "purpose": "可选用途标签"
}

* 兼容：若 /chat 未传 prompt，但带有 files / stagedDiff / unstagedDiff / branch 等结构化字段，会自动转发到 summarize-commit。新工具请显式传 prompt，或直接调对应接口。

成功：

{ "ok": true, "requestId": "chat_…", "message": "…", "text": "…" }

若已开启并就绪向量记忆，会自动检索相关记忆注入上下文，成功后异步写入本轮摘要。写入分区由 memoryScope 决定（见下文「记忆分区」）。

超时约 120s。LLM 调用在服务端串行排队（多工具同时请求不会打爆限流）；HTTP 仍可并发等待各自结果。

#流式对话（SSE）

POST /api/host/chat/stream
Content-Type: application/json

{ "clientId": "my-tool", "prompt": "…", "system": "可选", "purpose": "可选" }

响应 Content-Type: text/event-stream。必须传 prompt（结构化变更请用非流式 /chat 或 /summarize-commit）。

#4. 结构化总结（兼容）

POST /api/host/summarize-commit
Content-Type: application/json

兼容旧客户端（如 Git Desk「AI 总结」）。优先使用请求体中的 prompt / system / instruction（由客户端定义规则）；若只传结构化字段，服务端仅做中性拼接，不包含 Git/产品专用文案。新工具请优先用 /api/host/chat。

同样支持隐式向量记忆。

#5. 白名单 Action（高价值能力）

统一入口：

POST /api/host/action
Content-Type: application/json

{
  "clientId": "my-tool",
  "source": "optional",
  "name": "memory.search",
  "params": { "query": "上次提交风格" }
}

成功时响应含：

{
  "ok": true,
  "requestId": "action_…",
  "message": "人类可读摘要",
  "text": "同上",
  "data": { },
  "content": []
}

失败时可能仍带 data / content；data 内常见 success: false、errorCode 等。data / content 与 Agent Protocol 的 Action 结果对齐（如媒体的 image/video 片段）。

Action 超时约 300s（媒体生成较久）。

#开放列表与便捷路由

便捷路由的 Body 即为 params（可额外带 clientId / source），例如：

curl -s -X POST http://localhost:14220/api/host/memory/search ^
  -H "Content-Type: application/json" ^
  -d "{\"clientId\":\"demo\",\"query\":\"提交规范\"}"

未在白名单内的 Action（如 shell.exec、fs.write）返回 403，响应含 allowedActions。写文件 / Shell 等请用 MCP 连接 或本应用内 Agent。完整 Agent Action 见 Actions 清单。

memory.search / memory.index 在未传 memoryScope 时，服务端按该 clientId 的私域挂接解析分区（与隐式 chat 一致）；未挂接则为 host:{clientId}。

#5.1 记忆分区（memoryScope）与私域挂接

向量记忆按 scope 隔离，与私域工作台中的「记忆 N 条」统计对齐。

重要

1. clientId 在 register 与每次 chat / summarize-commit / action 中必须一致，否则不会写入挂接的私域分区。
2. 软件连接只增加向量记忆，不会自动增加私域五类卡片（知识 / 流程等）；卡片需灵感绑定私域或手工维护。
3. Git Desk：正式版 git-desk，开发版 git-desk-dev；详见 Git Desk 集成。

#调用日志

• 内存：最近约 50 条（localStorage）
• 磁盘：{用户工作目录}/host-bridge-logs/YYYY-MM/YYYY-MM-DD.jsonl
• UI：设置 → 软件连接 → AI 调用过程；打开或点刷新会从内存与当日 jsonl 合并展示（无需整应用重启）

#6. 错误与状态码（摘要）

#7. 多工具约定

1. 只启动一个 AI 服务实例；端口 14220 只能被一个进程占用
2. 每个工具传不同的 clientId；登记与请求体必须相同
3. 工具应 主动 register + 定期 heartbeat；记忆读写依赖 register + 一致 clientId
4. 可在 设置 → 软件连接 将某 clientId 挂接到私域，统一向量记忆分区
5. LLM / Action 串行排队；HTTP 可并发等待
6. 本应用须已启动、前端在线、已选模型；最小化到托盘一般仍可用
7. 记忆 / 联网 / 媒体另需对应组件或配置就绪
8. 本通道是 窄白名单，不是完整 Agent Protocol

#8. 最小示例

curl -s http://localhost:14220/api/host/health

curl -s -X POST http://localhost:14220/api/host/register ^
  -H "Content-Type: application/json" ^
  -d "{\"clientId\":\"demo\",\"name\":\"Demo Tool\",\"version\":\"0.1.0\"}"

curl -s -X POST http://localhost:14220/api/host/chat ^
  -H "Content-Type: application/json" ^
  -d "{\"clientId\":\"demo\",\"prompt\":\"用一句话说什么是 Git\"}"

curl -s -X POST http://localhost:14220/api/host/action ^
  -H "Content-Type: application/json" ^
  -d "{\"clientId\":\"demo\",\"name\":\"memory.status\",\"params\":{}}"

curl -s -X POST http://localhost:14220/api/host/web/search ^
  -H "Content-Type: application/json" ^
  -d "{\"clientId\":\"demo\",\"query\":\"webman php\",\"count\":5}"

流式（PowerShell 可用 curl.exe）：

curl.exe -N -X POST http://localhost:14220/api/host/chat/stream ^
  -H "Content-Type: application/json" ^
  -d "{\"clientId\":\"demo\",\"prompt\":\"列三点 Git 常用命令\"}"

#9. 相关文档

• 私域与记忆分区
• 示例项目：Git Desk（源码：gitee.com/phodit/git_desk）
• MCP 连接
• 集成对接概览
• 使用统计
• Agent Protocol v1
• Agent Actions