52 lines
1.8 KiB
Markdown
52 lines
1.8 KiB
Markdown
# 杜康好客 · v3.5.18 开发文档
|
||
|
||
> **2026-09-08** · integrations/wecom · admin-web · shared-types
|
||
> **主题**：企微智能机器人 **MCP 插件**（Streamable HTTP），与 REST API 插件并存
|
||
|
||
---
|
||
|
||
## 1. 版本目标
|
||
|
||
企微后台「添加 MCP 插件」可对接本系统：托管大模型按 MCP `tools/list` / `tools/call` 拉数。不改长连接 Bot、不删 REST/OpenAPI。
|
||
|
||
**不做**：写操作、明文手机/地址、把 `/admin/*` JWT 暴露给企微、第一期 SSE 传输。
|
||
|
||
---
|
||
|
||
## 2. 端点
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| MCP URL | `/api/v1/wecom/plugin/mcp` |
|
||
| 传输 | Streamable HTTP，无状态（每请求新建 `McpServer`） |
|
||
| 鉴权 | Header `X-Api-Key`（与 REST 同一套 HQ 实例） |
|
||
| 响应 | JSON-RPC；**无** `{code,message,data}` 信封 |
|
||
| 工具结果 | `JSON.stringify(查询结果)` |
|
||
| 权限 | `tools/list` 只注册已勾选权限；QueryService 仍 `requirePerm` |
|
||
| 开发计划 | `dev_plan.read` → `query_versions`、`query_tasks`（任务按 TODO/IN_PROGRESS/DEVELOPED/RELEASED/STOPPED 筛选） |
|
||
|
||
生产：`https://api.dukanghaoke.com/api/v1/wecom/plugin/mcp`
|
||
测试：`https://api-test.dukanghaoke.com/api/v1/wecom/plugin/mcp`
|
||
|
||
---
|
||
|
||
## 3. 变更面
|
||
|
||
| 层 | 路径 |
|
||
|----|------|
|
||
| shared-types | `WECOM_PLUGIN_MCP_*`、`allowedWecomPluginMcpTools` |
|
||
| API | `wecom-plugin-mcp.*`；`WecomPluginMcpFactory`；Interceptor skip MCP |
|
||
| HQ | `WecomApiPluginsPage` 展示 MCP URL |
|
||
| 文档 | [`企微API插件-配置手册.md`](./企微API插件-配置手册.md) |
|
||
|
||
---
|
||
|
||
## 4. 验收
|
||
|
||
- [ ] 无 Key / 错 Key → MCP 入口 401
|
||
- [ ] 带 Key `tools/list` 仅含该实例已勾选权限
|
||
- [ ] `tools/call` 查询口径与 REST 一致，结果无 REST 信封
|
||
- [ ] HQ 日志 `botKey=plugin:{id}`
|
||
- [ ] 现有 API 插件机器人行为不变
|
||
- [ ] 长连接 Bot 不变
|