在 DSH 里接入企业微信：MCP 与 CLI+Skill 两条路怎么选、怎么配

0. TL;DR

	路线 A：MCP	路线 B：CLI + Skill
本质	MCP 协议，企微云端跑 server，DSH 直连 URL	本地命令行工具 + 一份给模型看的说明书
模型看到什么	结构化工具 `mcp__wecom-doc__doc_create`（带 JSON Schema）	Shell 命令，`wecom-cli doc create ...`
凭证	URL query 里的 `apikey`，7 天有效	本地 AES-256-GCM 加密存储，自动刷新
安装成本	零安装，改一个 YAML	`npm i -g` + `skills add` + 授权
能力覆盖	按权限位切分（实测文档这一个权限位给 62 个工具）	最全（15 个 skill：消息/邮件/文档/表格/待办/日程/会议/微盘/通讯录...）
适合	想要原生工具调用体验、可调用也就可审计	想长期免维护、能力要全、还要脚本化

如果你只能选一条：短期要"模型会用工具"→ MCP；长期省心→ CLI+Skill。我最后是两条并存，MCP 当主力，CLI 当兜底。注意是能力连接，不是IM会话，链接后agent可以创建文档、日正、给通讯录发消息等。

1. 先把三个概念分清：Skill、CLI、MCP

这是最容易混的地方。企业微信官方给了几种"接入方式"，但它们不是同一层的东西：

Skill（技能） ：一份 Markdown 说明书（SKILL.md + 若干 reference 文档）。它不提供任何执行能力，只告诉模型"想做 X 应该敲哪条命令、参数长什么样"。
CLI ：真正干活的可执行文件（@wecom/cli → wecom-cli）。它有凭证管理、HTTPS 调用企微 API、输出 JSON。
MCP：一种协议。远端跑一个 MCP server，向客户端声明自己有哪些工具、每个工具的 JSON Schema 是什么，模型直接发起结构化工具调用。

所以：

Skill + CLI = 模型读文档 → 生成 shell 命令 → CLI 执行。 MCP = 模型直接拿到工具，参数由 schema 校验。

这条区分决定了后面所有的差异：你会发现"我有 Bot ID 和 Secret"能走 CLI 路线，却没法直接喂给 MCP------因为 MCP 端点要的是控制台授权后生成的那个带 apikey 的 URL。

2. 路线 A：官方 MCP，改一个 YAML 就完事

2.1 流程

企业微信 → 工作台 → 智能机器人 → 编辑你的机器人 → 可使用权限 → 去授权；
在需要的权限位 （如「文档」）右上角点 >，复制出来的 streamableHTTP URL；
把 URL 填进 DSH 的 profile patch。

2.2 唯一改动：profile patch

文件：~/.dsh/profiles/web/cordis.patch.yml（Windows 上即 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml）

在文件末尾追加：

yaml 复制代码

# 企业微信官方 MCP：文档能力。URL 由企微「工作台 → 智能机器人 → 编辑 →
# 可使用权限 → 去授权」按权限位生成，query 里的 apikey 就是凭证。
# 该授权有有效期（官方文档明示 7 天），过期后重新复制 URL 替换下面的 url。
- insert:
    - id: mcp-wecom-doc
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        transport: streamable-http
        serverName: wecom-doc
        url: "https://qyapi.weixin.qq.com/mcp/v2/bot/doc?apikey=<你的凭证>"
        failOnStartupError: true
        toolCallTimeoutMs: 60000

不需要装包：@deepseek-ai/dsh-mcp-client 随安装版自带。也不需要重启 GUI------当前会话里工具就已可用。

2.3 patch 的两种写法，别写错

同一个文件里两种写法语义完全不同：

写法	语义	用在哪
裸写 `- id: xxx` + `name:` + `config:`	覆盖已有插件行	改 DSH 内置插件（如覆盖 `ui-settings-general`）
包在 `- insert:` 列表里	新增插件行	加新 MCP（本文场景）

另外一条铁律：patch 是整行替换 config，不做深合并 。以后改这个 MCP 的配置，transport / serverName / url 等键必须全部重写一遍，只写要改的那个键会把其他键冲掉。

2.4 `serverName` 决定模型看到的工具名

工具名格式是 mcp__<serverName>__<原始工具名>，例如 mcp__wecom-doc__doc_create。约束：

只能 [A-Za-z0-9_-]，长度 1--32；
同一作用域内不能重名，重名会导致后加载的实例直接失败；
它是本地命名，和远端服务名无关。改了它就等于改了模型看到的工具名------历史会话里的调用记录、权限规则会因此作废。

所以接第二个能力时别复用 wecom-doc，用 wecom-calendar 之类。

2.5 三步验证

powershell 复制代码

# 1) 配置预检：组合树里应出现 mcp-wecom-doc
dsh --profile web --dump-config

注意这个命令会重写 profile 的 cordis.yml，在 workspace-write 沙箱策略下会报 EPERM，需放开写入权限。

第 2 步：对那个 URL 直接做 MCP 握手（initialize + tools/list）。实测结果：

项	结果
HTTP 状态	`200`
协议版本	`2025-06-18`
服务端	`动态文档 MCP` `1.0.5`
capabilities	`tools` / `prompts` / `resources`（`listChanged: false`、`subscribe: false`）
工具总数	62

工具按前缀分布：

前缀	数量	覆盖
`doc_*`	11	在线文档（新建/导入/读写/搜索/改名/成员/规则）
`sheet_*`	10	在线表格
`smartsheet_*`	28	智能表格（子表/字段/记录/视图/图表）
`smartpage_*`	11	智能文档
`media_*`	2	媒体上传/下载

第 3 步：真跑一次业务调用：

调用	结果
`mcp__wecom-doc__doc_create`（`doc_type: doc`、`content_type: text`）	✅ `errcode: 0`
`mcp__wecom-doc__doc_contents_append`	✅ `errcode: 0`
`mcp__wecom-doc__doc_search`（`keywords: ["周报"]`）	❌ `errcode: 851008`（权限未授权，见 3.4）

3. MCP 路线的坑，按踩到的概率排序

3.1 ⚠️ 凭证 7 天到期（官方明示）

企业微信《OpenClaw 文档能力使用指引》在「方式二：在智能机器人编辑页授权，通过 MCP 调用文档能力」第 4 步写明：

授权成功，当前授权有效期为7天

这说的就是我们走的这条流程，所以这条配置的有效期就是 7 天。

补充一个实测发现：把那条 apikey 做 base64url 解码，结果是 64 字节随机串，不含时间戳或 exp 字段 （不是 JWT）。也就是说------无法在本地推算到期时间，判断只能靠两条路：看授权页显示，或等调用报鉴权错。

好消息是我们设了 failOnStartupError: true，到期后启动阶段就会明确报出这条插件失败，不会静默地少一批工具、让你以为是模型不会用。（它只让这一条 MCP 行失败，不会让整个 harness 起不来。）

到期后的三步处理：

重新走「工作台 → 智能机器人 → 编辑 → 可使用权限 → 去授权 → 权限位右上角 >」；
复制新的 streamableHTTP URL；
替换 patch 里那一行 url（记得 2.3 的整行重写规则）。

关于「7 天」的适用边界，别过度推广：

CLI 路线没有这个限制 ：官方《企业微信支持CLI开源》全文没有出现"有效期/到期"字样，它只讲授权审批与免审逻辑。因为 CLI 走长连接 Bot ID/Secret，凭证本地加密保存并由 bot 凭据驱动静默刷新。
- 例外：若只用环境变量 WECOM_CLI_ACCESS_TOKEN 而没配 bot 凭据，token 失效（错误码 853004）时不参与静默刷新，得自己更新环境变量。
企微另有一套「数据权限授权和到期事件」机制（到期前 7 天推「即将到期」事件），但那是第三方应用数据权限的功能，不能直接当作本 MCP 的规则。
其他权限位（比如日程）是否同样 7 天，官方没逐项列明，以授权页实际显示为准。

3.2 传输方式只有两种，选错就接不上

DSH 的 dsh-mcp-client 只支持 stdio（拉本地子进程）和 streamable-http（连 URL）。企微控制台复制出来的正好是 streamableHTTP URL，直接匹配，零代码。

反过来讲清楚：Bot ID + Secret 不能被 DSH 直接用来连 MCP------它只支持 CLI 那种「手动接入」认证，MCP 端点必须用控制台授权后生成的带 apikey 的 URL。

3.3 权限是按能力位切分的，一条 URL ≠ 全部能力

复制「文档」权限位得到的 URL 路径是 /mcp/v2/bot/doc，里面没有日程工具。要日程必须单独授权日程权限位、复制那条 URL、再加一条配置。
哪怕在同一个「文档」权限位里，能力还分档：doc_create 通了，但 doc_search / 读正文属于「搜索与获取文档内容 」，返回 851008 表示机器人未被授权该能力。
解法二选一：
- 机器人创建者按报错里给的链接发起申请，等管理员审批；
- 管理员在「管理后台 → 智能专区 → 智能机器人 → 权限管理」把创建者加入免审名单，之后无需逐次审批。

3.4 ⚠️ 工具集里没有删除能力

62 个工具里没有任何 delete 类工具（doc_* 只有 create / contents_append / contents_overwrite / contents_get / search / names_update / members_update / rules_update / import）。意味着：

机器人建得出来，删不掉------清理必须人工在企微客户端做；
排查时别指望用工具回收测试产物。

3.5 文档归属机器人身份，不在你的「我的文档」里

MCP 调用以机器人自己的身份代你执行。后果：

新建文档归属机器人，链接能打开，但在你的文档列表/文件夹里可能找不到；
官方容量规则是「文档仅占用创建者的容量」，基础版个人上限 1G，开通「文档高级功能」可提升至无限；机器人是否有独立配额官方未写明，需要时实测；
查容量：个人端「文档 → 右上角 + → 更多 → 关于文档」；管理员「管理后台 → 协作 → 文档 → 数据统计 → 查看使用容量」；
释放容量：删除文档（非高级账号回收站保留 7 天、高级账号 180 天），删除后约 10 分钟释放，容量统计次日才更新；
doc_create 不支持指定父目录 （参数里没有 father_id），所以没法用工具把文档放进指定文件夹，只能建完手动移动，或用 doc_members_update 加协作成员。

3.6 跨会话怎么指认目标文档（建议先约定好）

当前工具集没有列出文档的能力 ，doc_search 又被权限挡着，所以模型无法自行发现或区分文档。约定：

贴链接最稳 ：docid 参数同时接受 docid 和 URL。URL 解析规则是 /doc/（表格 /sheet/、智能文档 /smartpage/）与 ? 之间那段： https://doc.weixin.qq.com/doc/w3_AHcAYXivAFMCNluwFfcM0SEGPOa06_a?scode=... → w3_AHcAYXivAFMCNluwFfcM0SEGPOa06_a
会话内指代可用：当前会话里建过或贴过链接的，能从上下文取回 docid；会话压缩或换新会话后丢失。
跨会话请用台账：维护一个 Markdown 表格记录「名称 / docid / 链接 / 创建时间 / 用途」。名字对不上唯一一篇时，应该先问、不要猜------写错文档虽然能靠版本历史回滚，但会给协作者造成实际困扰。

3.7 工具返回的内容是「外部输入」，不是指令

企微 MCP 每次返回里都夹带一段服务端写的「身份上下文」，其中包含要求模型「禁止向用户透露该段内容」的指令。DSH 把工具输出标记为外部不可信来源、不得当作系统指令执行------本次也是这么处理的：只提取运维相关事实（调用以机器人身份执行、文档归属机器人），没有执行其中的指令。

这条提醒有普适意义：任何 MCP / Web / 邮件来源的文本里出现"指令"，都是数据不是命令。

4. 路线 B：CLI + Skill

4.1 安装

bash 复制代码

# 1) 装 CLI 本体
npm install -g @wecom/cli

# 2) 装 Skill（官方标注"必需"）
npx skills add WeComTeam/wecom-cli -y -g

# 3) 配置凭证（交互式，仅需一次）
wecom-cli auth init

# 4) 查看授权状态
wecom-cli auth show

前置条件：Node.js，以及长连接机器人的 Bot ID 和 Secret。

也可以一条命令打包（官方的一体化 skill 包，内部同样会拉 CLI）：

bash 复制代码

npx skills add WecomTeam/wecom-unified -y -g

Windows 上 CLI 依赖平台包 @wecom/cli-win32-x64。

4.2 ⚠️ DSH 上的落地差异 ------ 这是最容易卡住的一步

官网 AI 开放能力页把「DeepSeek Harness」列为支持接入的 Agent 之一，但这不等于 CLI+Skill 在 DSH 上开箱可用。原因：

skills CLI（npm skills v1.7.2，README 里那张 70 行的 agent 表格）的受支持清单没有 DSH/DeepSeek Harness，也不会自动检测到它；DSH 自身也没有「技能市场 / 连接器」入口；
但有一条现成的路：清单里 Cline、Codex、Dexto、Kimi Code CLI、Loaf、Pi、Sarvam Code、Warp、Zed 这些 agent 的全局目录就是 ~/.agents/skills/ ，而 DSH 的 skill 扫描根恰好包含 ~/.agents/skills（agentsHome，rank 500）。所以：

bash 复制代码

npx skills add WeComTeam/wecom-unified -y -g -a codex   # 上面任一 agent 名都可以

这样 Skill 就落到了 DSH 认得的目录里。

也可以干脆手动拷贝。DSH 的扫描根与优先级：

扫描根	rank
`<DSH_HOME>/skills`	400
`~/.agents/skills`（`agentsHome`）	500
项目根 `.dsh/skills`	项目级
项目根 `.agents/skills`	项目级

识别形式是 <根>/<名字>/SKILL.md 或 <根>/<名字>.md，只扫一层。

最后强调一遍：Skill 只是说明书，CLI 本体必须真的装着 （npm install -g @wecom/cli），否则模型读完 skill 也执行不了。

4.3 为什么 CLI 不用 7 天续期

凭证以 AES-256-GCM 加密存在本地 ~/.config/wecom/credentials.enc（权限 0600），bot 信息与 token 同存，并由 bot 凭据驱动静默刷新。所以不需要周期性重新复制配置。

唯一例外上面提过：只用 WECOM_CLI_ACCESS_TOKEN 环境变量、没配 bot 凭据时，token 失效（853004）不参与静默刷新。

4.4 CLI 的工程化能力（比 MCP 强的地方）

--json、--set、--dry-run（先校验不落数据）、--page-count（游标分页）、--output、schema list/get。排查时 --help / --schema 自查很方便。

代价也很直白：每次操作都是一次 shell 调用 ，命令拼错、参数不符只能靠读 skill 里的 reference 文档和 --help 自查，没有 schema 在调用前拦一道。而 MCP 侧享有 DSH 工具注册表带来的权限检查、取消、结果落库、会话可重放。

5. 两种路线对照

维度	MCP	CLI + Skill
是否 MCP 协议	✅	❌ Skill + CLI
入口	企微编辑页授权 → 复制 URL	`npm i -g @wecom/cli` + `skills add` + `auth init`
模型侧形态	结构化工具调用	生成 shell 命令
参数校验	调用前 JSON Schema 拦截	靠 skill 文档 + `--dry-run`
凭证存储	URL 内嵌 apikey，7 天	本地 AES-256-GCM 加密，自动刷新
维护成本	每 7 天换 URL	低
能力覆盖	按权限位切分	最全（15 个 skill，含在线 PPT、会议纪要与转写）
DSH 适配	原生支持	需绕过 skills CLI 清单限制（`-a codex` 或手拷）
出错可诊断性	高（schema 拦截 + 工具记录）	中（要读 `--help` / `--schema`）
工具名稳定性	高（`mcp__server__tool`，重启不失效）	依赖 shell 调用文本
安装依赖	无	Node + npm 全局权限 + 能执行 shell 的 agent

6. 怎么选

你的偏好	选
只要文档/表格这类结构化能力，接受 7 天续期	MCP
嫌续期烦，还想要 PPT / 会议纪要等更全能力	CLI + Skill
两个都要	并存（MCP 当主力，CLI 当兜底与脚本化入口）
平台已内置企微连接器	直接用平台市场版（DSH 暂无此入口）

一句话取舍：MCP 换来的是"模型会用工具"的体验，代价是 7 天一次续期；CLI+Skill 换来的是"装一次管很久"，代价是模型每次得敲命令。

7. 维护速查表

操作	做法
换 apikey / URL	替换 patch 里 `url` 那一行（其余键必须完整重写）
临时停用 MCP	该行加 `disabled: true`
完全移除	删掉整个 `- insert:` 块（含 `mcp-wecom-doc` 那一项）
新增日程能力	① 授权「日程」权限位并复制 URL；② 复制整段 `- insert:` 块，`id` 改 `mcp-wecom-calendar`、`serverName` 改 `wecom-calendar`、`url` 换新；③ `dsh --profile web --dump-config` 预检
预检	`dsh --profile web --dump-config`，退出码 0 即配置可组合
沙箱报错	改 profile patch 属于工作区外写入，`workspace-write` 策略下会被拒（报 `file access denied`），需放开权限

排查时别被误导：~/.dsh/logs/startup-*.log 里可能有很早以前从源码启动失败的旧记录，与本次接入无关。

8. 检查清单（动手前过一遍）

9. 参考来源

主题	来源
四种接入方式、权限审批与免审逻辑	企业微信帮助中心《企业微信支持CLI开源》`https://open.work.weixin.qq.com/help2/pc/21676`
「授权有效期为7天」原文（MCP 复制流程）	企业微信《OpenClaw文档能力使用指引》`https://work.weixin.qq.com/nl/act/p/a7f3ca5679c9419d`
AI 开放能力清单、支持的 Agent 列表、安装指引	`https://work.weixin.qq.com/nl/index/aicli`
CLI 命令模型、凭证存储与静默刷新、错误码	`@wecom/cli` 官方仓库 `docs/cli-reference.md`（v1.3.4）
CLI 内置 15 个 Agent Skills 清单	`@wecom/cli` 仓库 `docs/skills.md`
数据权限授权 / 即将到期 / 到期事件机制	开发者中心《数据权限授权和到期事件通知》`https://developer.work.weixin.qq.com/document/path/101587`
文档容量规则、查看与释放	帮助中心《文档容量规则说明》`https://open.work.weixin.qq.com/help2/pc/19769`
Bot ID / Secret 获取方式	帮助中心 `https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21677`
skills CLI 支持的 agent 与安装目录	npm `skills` v1.7.2（`https://github.com/vercel-labs/skills`）README
DSH 的 skill 扫描根与优先级	仓库 `packages/skill/skill-filesystem/README.md`
DSH 的 MCP 客户端能力与限制	仓库 `packages/mcp/mcp-client/README.md`、`docs/subsystems/mcp.md`
DSH profile 组合顺序与 patch 语义	仓库 `docs/user/develop/basic/publish.md`

在 DSH 里接入企业微信：MCP 与 CLI+Skill 两条路怎么选、怎么配

0. TL;DR

1. 先把三个概念分清：Skill、CLI、MCP

2. 路线 A：官方 MCP，改一个 YAML 就完事

2.1 流程

2.2 唯一改动：profile patch

2.3 patch 的两种写法，别写错

2.4 serverName 决定模型看到的工具名

2.5 三步验证

3. MCP 路线的坑，按踩到的概率排序

3.1 ⚠️ 凭证 7 天到期（官方明示）

3.2 传输方式只有两种，选错就接不上

3.3 权限是按能力位切分的，一条 URL ≠ 全部能力

3.4 ⚠️ 工具集里没有删除能力

3.5 文档归属机器人身份，不在你的「我的文档」里

3.6 跨会话怎么指认目标文档（建议先约定好）

3.7 工具返回的内容是「外部输入」，不是指令

4. 路线 B：CLI + Skill

4.1 安装

4.2 ⚠️ DSH 上的落地差异 ------ 这是最容易卡住的一步

4.3 为什么 CLI 不用 7 天续期

4.4 CLI 的工程化能力（比 MCP 强的地方）

5. 两种路线对照

6. 怎么选

7. 维护速查表

8. 检查清单（动手前过一遍）

9. 参考来源

2.4 `serverName` 决定模型看到的工具名