skills/modelstudioai__cli
1
0
Fork 0
mirror of https://github.com/modelstudioai/cli.git synced 2026-09-14 19:49:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: qwenwork connector test

Browse Source
This commit is contained in:
rendianmeng
2026-08-10 14:12:11 +08:00
parent 5d4ead8d7d
commit 689b499a32
1 changed files with 0 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files
qwenwork-connector-integration.md
-298
View File
@@ -1,298 +0,0 @@
# 千问办公连接器集成 bailian-cli — 技术方案
## 1. 背景与目标
### 1.1 背景
千问办公（QwenWork）通过「连接器」把对话助手接到外部系统。bailian-cli（`bl`）是阿里云百炼 / Model Studio 的命令行产品。
### 1.2 目标
在千问办公中以自定义 MCP 连接器调用百炼 CLI 能力（生图、知识库、应用调用等），无需离开对话去开终端。
---
## 2. 千问办公侧
依据：[连接器｜千问办公帮助中心](https://qwenwork.cn/docs/features/connectors)。
入口：左侧「**扩展**」→「**连接器**」→「+ 添加」。本方案只用 **自定义 MCP · STDIO**。
注意：
- 连接器默认关闭，需用户开启。
- 开启/关闭后需**新建对话**才生效。
- STDIO 依赖本机可执行的 `bl`（或开发态等价启动命令）。
推荐配置（优先用本机登录态，JSON 里不写 Key）：
```json
{
"mcpServers": {
"bailian-cli": {
"command": "bl",
"args": ["mcp", "serve"]
}
}
}
```
可选：在连接器里用 `env` 注入模型 API Key（会覆盖本机 config 里的 key，见 §5.5）：
```json
{
"mcpServers": {
"bailian-cli": {
"command": "bl",
"args": ["mcp", "serve"],
"env": {
"DASHSCOPE_API_KEY": "sk-xxx"
}
}
}
}
```
说明：`env` 注入的是**进程环境变量**名 `DASHSCOPE_API_KEY`，不是 `~/.bailian/config.json` 里的字段名 `api_key`。二者不要混用拼写。开发态可用仓库内 `tsx` 启动（见 §6）。
---
## 3. 现状与决策
### 3.1 bailian-cli 与 MCP
| 能力 | 状态 | 说明 |
| ------------------------------- | -------- | ----------------------------------------------- |
| 调用百炼 MCP 广场 | 已有 | `bl mcp list` / `tools` / `call`（commands 库） |
| WebSearch 等 | 已有 | `bl search web` 等 |
| **把自己暴露为本机 MCP Server** | **已有** | `bl mcp serve`（runtime 内建） |
命名区分：
- `mcp list|tools|call`：CLI 当 **MCP Client**，调广场上的远端 server。
- `mcp serve`：CLI 当 **MCP Server**，给千问办公等客户端用。
---
## 4. 架构
```text
千问办公 (MCP Client)
│ STDIO (stdin/stdout JSON-RPC)
▼
bl mcp serve ← createCli 拦截，非 defineCommand
│
▼
packages/runtime/mcp-server ← McpServer + tool 注册 + invoke
│
▼
registry.getLeafEntries() ← 产品全部叶子命令
│
▼
command.run(ctx) ← 复用 authStage + 现有业务实现
│
▼
bailian-cli-core ← 本机鉴权 / HTTP / 配置
```
```mermaid
flowchart TB
QW[千问办公]
QW -->|STDIO| Serve[bl mcp serve]
Serve --> Host[runtime mcp-server]
Host --> Leaves[registry 叶子命令全量]
Leaves --> Run[invoke + authStage + command.run]
```
---
## 5. 实现说明（与代码对齐）
### 5.1 入口：`createCli` 拦截
文件：`packages/runtime/src/create-cli.ts`
- `--version` 在 dispatch 入口统一处理。
- 路径为 `mcp serve` 时：`--help` → `printMcpServeHelp`；否则 → `serveMcpStdio`。
- **不**走 `resolve` / middleware / `defineCommand.run`。
- `bl mcp --help` 会附加一行提示：runtime built-in `mcp serve`。
原因：MCP 需要 `registry.getLeafEntries()` 做全量挂载；commands 库单个 `run(ctx)` 拿不到完整命令表。
### 5.2 MCP host
目录：`packages/runtime/src/mcp-server/`
| 文件 | 职责 |
| ------------------- | ---------------------------------------------------------------- |
| `serve.ts` | `McpServer` + `StdioServerTransport`；`registerTool` 全量注册 |
| `schema.ts` | path → tool 名；flags → Zod `inputSchema` / JSON Schema 辅助 |
| `invoke.ts` | 构造 ctx → `authStage` + `run`；强制 `output=json`、`quiet=true` |
| `output-capture.ts` | ALS 捕获 `emitResult` / `emitBare`，避免污染 MCP stdout |
| `help.ts` | `bl mcp serve --help` 文案 |
依赖：`@modelcontextprotocol/server`、`zod`（挂在 `bailian-cli-runtime`）。
### 5.3 命令 → Tool
- 来源：`registry.getLeafEntries()`（来自 `packages/cli/src/commands.ts` 等产品 map + Command Pack）。
- 命名：`bailian_` + 路径空格改下划线，如 `text chat` → `bailian_text_chat`。
- `inputSchema`：由命令自有 `flags` 转 Zod object（无全局 / 凭证域 flag；凭证走本机 env / `~/.bailian`）。
- 同时传入 `commandPacks`，以便 `plugin *` 等工具可执行。
### 5.4 分层
| 层 | 职责 |
| ------------------- | ------------------------------------------------------- |
| `packages/runtime` | `createCli` 拦截 + MCP host + stdout 隔离 |
| `packages/cli` | 产品命令 map、identity；**不**单独注册 `mcp serve` leaf |
| `packages/commands` | 业务命令实现；**无** `mcp/serve.ts` |
| `packages/core` | 不硬编码千问办公 |
### 5.5 鉴权与输出
复用现有 `authStage` / resolver；MCP **不**把 `--api-key` 等凭证域 flag 暴露进 tool `inputSchema`（避免 Key 进对话）。
#### 模型 API Key（`auth: "apiKey"` 的工具）
解析优先级（`resolveApiKey`）：
1. CLI flag `--api-key`（`mcp serve` 正常挂载调用时一般不会用到）
2. 环境变量 `**DASHSCOPE_API_KEY**`（连接器 JSON 的 `env` 可注入）
3. 本机配置文件 `**~/.bailian/config.json**` 字段 `**api_key**`（`bl auth login` 写入）
因此：连接器若设置了 `DASHSCOPE_API_KEY`，会优先于 config 里的 `api_key`；未设置时才读 `api_key`。
命名对照（不要混用）：
| 来源 | 名称 | 说明 |
| ------------------------ | ------------------- | ---------------------- |
| 连接器 / shell env | `DASHSCOPE_API_KEY` | 环境变量 |
| `~/.bailian/config.json` | `api_key` | 文件字段（snake_case） |
| tool 入参 | （不暴露） | 不在 MCP inputSchema |
`bl auth login`（模型 Key 流程）写入的是 config 的 `api_key`，不是环境变量。
#### Console / OpenAPI
- Console（`auth: "console"`）：读 config 的 `access_token` 等；需事先 `bl auth login --console`。
- OpenAPI（`auth: "openapi"`）：flag → `ALIBABA_CLOUD_ACCESS_KEY_*` env → config 的 `access_key_id` / `access_key_secret` 等。
#### 约束与输出通道
- 交互式浏览器 `auth login` 不在 MCP `tools/call` 内完成；引导终端先 login；可用 `bailian_auth_status` 查看状态。
- 禁止把 raw API Key / Console Token 写入 tool 响应或 verbose 日志。
- stdout：**仅** MCP JSON-RPC；业务结果经 capture 后放进 `content[].text`。
- stderr：就绪日志、进度等（如 `bl mcp serve: STDIO MCP ready (N tools)`）。
### 5.6 与 Skill
| 载体 | 作用 |
| -------------------- | --------------------------- |
| 连接器（本方案 MCP） | 可调用的原子工具 |
| Skill | 多步工作流、选型与 hand-off |
二者互补；连接器主路径是 MCP。
### 5.7 尚未做（后续）
- 集成市场一键安装（底座仍是 STDIO）。
---
## 6. 用户接入
### 6.1 前置
1. 安装带 `mcp serve` 的 bailian-cli（发版后的全局 `bl`，或本仓库开发态）。
2. 鉴权二选一（或同时存在时以 env 优先，见 §5.5）：
- 推荐：`bl auth login` → 写入 `~/.bailian/config.json` 的 `api_key`（Console 场景再加 `--console`）。
- 或：连接器 JSON `env.DASHSCOPE_API_KEY=sk-xxx`。
3. 自检：`bl auth status`；可选 `bl mcp serve --help`。
### 6.2 开发态启动
千问办公 JSON 示例（开发态）：
```json
{
"mcpServers": {
"bailian-cli": {
"command": "pnpm",
"args": [
"-C",
"/path/to/bailian-cli",
"-F",
"bailian-cli",
"exec",
"tsx",
"src/main.ts",
"mcp",
"serve"
]
}
}
}
```
### 6.3 在千问办公中添加
1. 「扩展」→「连接器」→「+ 添加」
2. 粘贴 JSON 或手动 STDIO：`bl` + `mcp serve`
3. 启用连接器，确认工具列表（数量应接近产品叶子命令数）
4. **新建对话**验证（如「查看百炼鉴权状态」「用百炼生成一张图」）
### 6.4 验收（P0）
- [x] `bl mcp serve` 可启动；stderr 打印 tool 数量
- [x] `initialize` / `tools/list` / `tools/call`（如 `bailian_auth_status`）STDIO 联调通过
- [x] 全量叶子命令挂载（无白名单）
- [x] `emitResult` 不污染 MCP stdout
- [ ] 千问办公实机：生图 / 知识库 / 应用调用等成功路径
- [ ] 未登录时错误可读、不泄漏密钥（实机再确认）
---
## 7. 风险
| 风险 | 对策 |
| -------------------- | ------------------------------------------------------- |
| 工具数量多、模型选错 | 接受全量；靠命名 + description / schema；后续再评估分组 |
| 危险写操作误调用 | 与 CLI 一致暴露；依赖连接器默认关闭 + 用户授权 |
| stdout 污染 MCP | ALS 捕获业务输出 |
| 本机无 `bl` / 旧版本 | 发版说明写清；开发态用仓库 `tsx` 路径 |
| 与 `mcp list` 混淆 | help / 文档区分 Client vs Server |
| 长任务超时 | 后续强化 task_id + 轮询（P1） |
---
## 8. 决策摘要
1. **形态**：本地 STDIO，`bl mcp serve`。
2. **工具面**：全量叶子命令，无白名单。
3. **落点**：runtime MCP host + `createCli` 早拦截；不进 commands 库。
4. **SDK**：`@modelcontextprotocol/server`（`McpServer`）。
5. **成功标准**：登录本机 `bl` 后，千问办公 STDIO 连接器可稳定调用与终端一致的能力。
---
## 9. 参考
- 千问办公连接器：[https://qwenwork.cn/docs/features/connectors](https://qwenwork.cn/docs/features/connectors)
- 仓库分层：`AGENTS.md`
- 产品命令 map：`packages/cli/src/commands.ts`
- 入口调度：`packages/runtime/src/create-cli.ts`
- MCP host：`packages/runtime/src/mcp-server/`
---
## 10. 修订记录
| 日期 | 说明 |
| ---------- | -------------------------------------------------------------------------------------------- |
| 2026-08-06 | 初稿：可行性与 STDIO 方案 |
| 2026-08-10 | 决策：全量挂载、仅 STDIO、不做白名单 |
| 2026-08-10 | 按落地实现重写：`createCli` 拦截、`@modelcontextprotocol/server`、文件落点与接入步骤对齐代码 |
| 2026-08-10 | 补齐鉴权：`DASHSCOPE_API_KEY` 与 config `api_key` 优先级、连接器 env 示例与命名对照 |