dsh-multitool 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,143 @@
1
- # Temporary Holding Version
1
+ # dsh-multitool
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(dsh)用的**组合包(bundle)**。
4
+
5
+ 一条命令,同时得到两样东西:
6
+
7
+ - **40 个 WPS 工具** —— 读写**本机正开着的** WPS 文字/表格/演示
8
+ - **一份技能** —— 教 AI 什么时候该用这些工具、怎么用才不会选错
9
+
10
+ ```sh
11
+ dsh plugin --profile <你的profile> add dsh-multitool
12
+ ```
13
+
14
+ ---
15
+
16
+ ## 它和 `dsh-wps` 不是一回事(**装之前先看这段**)
17
+
18
+ npm 上已经有一个 `dsh-wps`,是别人做的 **WPS / 金山文档「云文档」集成**(走官方 SkillHub MCP 端点)。
19
+
20
+ 本包操作的是**你电脑上正开着的 WPS 窗口**,不是云文档。两者能力完全不同:
21
+
22
+ | | 本包 `dsh-multitool` | 别人的 `dsh-wps` |
23
+ |---|---|---|
24
+ | 操作对象 | **本机正开着的** WPS 文档 | WPS 云文档 |
25
+ | 需要联网 | 不需要 | 需要 |
26
+ | 需要授权 | 不需要 | 要 OAuth |
27
+ | 工具前缀 | `mcp__wpslocal__*` | `mcp__wps__*` |
28
+ | 能做什么 | 改格式、插图表、排版、批量处理 | 云端文件读写 |
29
+
30
+ **工具前缀刻意不同**(`wpslocal` vs `wps`),所以两个包可以同时装,不会撞车。
31
+
32
+ ---
33
+
34
+ ## 它做了什么
35
+
36
+ ```
37
+ dsh-multitool/
38
+ ├── package.json # 声明 dsh.bundle.patch + engines.dsh
39
+ ├── cordis.patch.yml # 配置层:挂 MCP + 启用技能
40
+ └── assets/
41
+ └── wps-multitool/
42
+ ├── SKILL.md
43
+ └── references/{routing,recipes,errors,dsh}.md
44
+ ```
45
+
46
+ `cordis.patch.yml` 做三件事:
47
+
48
+ 1. **挂官方 MCP 客户端**(`@deepseek-ai/dsh-mcp-client`),指向本机的 `wps-multitool-mcp`
49
+ 2. **启用 `skill-filesystem`**,把本包的 `assets/` 加进技能扫描根
50
+ 3. **启用 `tool-skill`**,让模型能看到并加载技能
51
+
52
+ ---
53
+
54
+ ## 为什么这样写(四条硬约束,改之前先读)
55
+
56
+ ### 1. 插件行按【包名】引用,不写相对源码路径
57
+
58
+ dsh 的 loader 从 profile 的 `node_modules` 解析包名。我们**不自己 `import`** 官方 MCP 客户端 ——
59
+ 那个包只在 dsh 的 `app.asar` 内部可见,从 profile 目录**永远**解析不到。
60
+
61
+ > 这条是踩过坑的:v0.3 让 `index.js` 里 `import('@deepseek-ai/dsh-mcp-client')`,
62
+ > 真机报 `Cannot find package`。改成"由 loader 解析"一次就通。
63
+
64
+ ### 2. 路径必须绝对,用 `!!js` 在求值时算
65
+
66
+ 发布时不可能知道用户把包装在哪,所以 `args` 和 `customSkillDirs` 都用 `!!js`:
67
+
68
+ ```yaml
69
+ customSkillDirs:
70
+ - !!js >-
71
+ process.getBuiltinModule('node:path').join(
72
+ process.getBuiltinModule('node:path').dirname(
73
+ process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dsh-multitool/package.json')
74
+ ),
75
+ 'assets'
76
+ )
77
+ ```
78
+
79
+ **求值上下文提供 `baseUrl` 和 `process.getBuiltinModule`。** 这是从官方 `dsh-base` 的
80
+ `skill-filesystem` 配置里学的写法(它自己就这么算 preset skills 目录)。
81
+
82
+ ### 3. `skill-filesystem` / `tool-skill` 在模板里默认禁用
83
+
84
+ web 模板里这两个是 `disabled: true`。本包的 patch 按 `id` 覆盖它们、**且不写 `disabled`**,
85
+ 等于重新启用。
86
+
87
+ > 官方语义:后层按 `id` **整行覆盖**,`config` 是**整体替换不是深合并** —— 所以 `name` 必须写全。
88
+
89
+ ### 4. serverName 用 `wpslocal`,不是 `wps`
90
+
91
+ 见上方"和 `dsh-wps` 不是一回事"。**这条别改回去** —— 改成 `wps` 会和别人的包撞名,
92
+ 两个都装时 dsh 会报 `serverName "wps" is already in use`。
93
+
94
+ ---
95
+
96
+ ## 两个参数为什么是这两个值
97
+
98
+ | 参数 | 值 | 不这么写会怎样 |
99
+ |---|---|---|
100
+ | `toolCallTimeoutMs` | `130000` | dsh 默认 60000 < 桥的 120000 → **客户端报超时、文档其实已经改完**,用户以为失败又重做一遍 |
101
+ | `failOnStartupError` | `true` | 默认 `false` 会在连不上时**静默降级成零工具**,用户只觉得"AI 不会用 WPS",看不到任何错误 |
102
+ | `command` | `node`(不是 `npx`) | dsh 的 args 直接透传、不过 shell,Windows 上 `npx` 实际是 `npx.cmd`,按 `npx` spawn 会 **ENOENT** |
103
+
104
+ ---
105
+
106
+ ## 依赖
107
+
108
+ `wps-multitool-mcp` 作为 `dependencies` 声明。入口路径按两档解析:
109
+
110
+ 1. 先按依赖解析(`createRequire(baseUrl).resolve('wps-multitool-mcp/dist/index.js')`)
111
+ 2. 解析不到就退回**本包同级目录**(开发者本地 checkout 的情形)
112
+
113
+ ---
114
+
115
+ ## 验证状态(2026-10-22)
116
+
117
+ | 项 | 结果 |
118
+ |---|---|
119
+ | `dsh plugin add ./dsh-bundle` | ✅ exit 0 |
120
+ | `--dump-config` 出现本包层 | ✅ 且显示 `patched by ... dsh-multitool`(覆盖了 skill-filesystem / tool-skill) |
121
+ | 真启动 `dsh --profile web` | ✅ **MCP 进程起来了**(`node ...\wps-multitool-mcp\dist\index.js`) |
122
+ | 技能插件是否报错 | ✅ **stderr 全空**(路径错会抛 ENOENT) |
123
+ | 卸载干净 | ✅ `dsh plugin remove` 后配置树无残留 |
124
+ | 自检 `node dsh-bundle/selftest.js` | ✅ 16 项全过,工具 40 个 |
125
+ | `npm run verify:all` | ✅ 23/23 |
126
+
127
+ **未验证**:工具名在模型侧是否真以 `mcp__wpslocal__*` 出现、技能是否真的进了会话目录 ——
128
+ 这两条要在有 API key 的对话回合里才能看到。
129
+
130
+ ---
131
+
132
+ ## 平台限制
133
+
134
+ **Windows only。** 本包背后是 WPS Office 的 COM 自动化,没有 Windows 跑不了。
135
+
136
+ 默认档 40 个工具(不是全部 284)—— dsh 会把工具定义塞进每一次请求,全量很贵。
137
+ 需要更多就用 `WPS_TOOL_TIER=full`,或按组加载。
138
+
139
+ ---
140
+
141
+ ## 许可
142
+
143
+ MIT。本包只做配置与技能分发,实际能力在 [`wps-multitool-mcp`](https://github.com/forkgo430/wps-multitool-mcp)。
@@ -0,0 +1,130 @@
1
+ ---
2
+ name: wps-multitool
3
+ description: 通过 wps-multitool MCP 操作本机 WPS Office 的工具链,涵盖文字、表格、演示的读取、写入与排版。当用户要求读写 WPS 文档、做表格公式/图表/样式/修订/索引/交叉引用/页眉页脚,或做 PPT 版式/动画/母版/配色时使用。强制走「探活 → 定组 → 加载组 → 选型读反例 → 写前确认」五步,避免选错近名工具、写失败后盲目重放、文档被误改。仅限 Windows + WPS Office;通用 Office 问答、代码任务、以及非 WPS 的文档格式问题不要使用本技能。
4
+ license: MIT
5
+ compatibility: Windows + WPS Office 12.x;需要 wps-multitool MCP 的常驻桥进程在运行
6
+ metadata:
7
+ author: 赢容
8
+ version: "1.0.1"
9
+ ---
10
+
11
+ # 操作 WPS 的正确链路
12
+
13
+ MCP 提供了近 300 个工具(以 `tools/list` 与 `wps_search_tools` 为准),能力不缺;
14
+ 缺的是**按什么顺序用**。本技能只管顺序和判断,
15
+ 不重复工具清单(清单会过期,清单请走 `wps_search_tools`)。
16
+
17
+ ## 什么时候用 / 不用
18
+
19
+ **用**:用户要动 WPS 里的文字、表格、演示 —— 读内容、改格式、加公式、套样式、
20
+ 处理修订、插索引与交叉引用、调页眉页脚、做 PPT 版式与动画。
21
+
22
+ **不用**:
23
+ - 通用 Office 问答("Word 怎么插入页码"这种知识性问题,不需要碰 WPS)
24
+ - 代码任务、Excel 公式语法解释
25
+ - 非 WPS 的格式问题(pdf、md、docx 用别的工具)
26
+
27
+ ## 五步主链路
28
+
29
+ 按顺序走,不要跳步。跳步是本 MCP 最常见的失败原因。
30
+
31
+ ### 1. 探活
32
+
33
+ 先 `wps_common_status`。它会告诉你桥进程通不通、WPS 在不在、有没有活动文档。
34
+
35
+ 三态分别对应三种处理,不要混:
36
+
37
+ | 状态 | 下一步 |
38
+ |---|---|
39
+ | 桥不通 | `wps_common_repair`,修完再探一次 |
40
+ | WPS 没开 | 让用户先打开 WPS,或你用建文档类工具打开 |
41
+ | 没有活动文档 | 必须先建/开文档,否则后续全部失败 |
42
+
43
+ ### 2. 定组
44
+
45
+ `wps_route_intent` 把用户诉求映射到组:`word` / `excel` / `ppt` / `common`。
46
+ 它用的是关键词打分,组间语义差别大时准确;表述含糊时**别硬猜**——去第 4 步搜。
47
+
48
+ ### 3. 加载组
49
+
50
+ 默认只列出 40 个基础工具,其余组要显式加载:`wps_load_tool_group`。
51
+
52
+ **"工具不存在"通常不是没有这个能力,是组没加载。** 先搜再加载,别直接告诉用户做不到。
53
+
54
+ ### 4. 选型(必读反例)
55
+
56
+ `wps_search_tools` 可以直接用中文关键词("插入表格""批注""改背景")。
57
+
58
+ 返回结果里的 **`notFor` 必须读**。本 MCP 有一批近名工具,光看名字分不出来:
59
+
60
+ - 6 个 `background`(纯色 / 图片 / 渐变 / 母版 / 图表区 / 全局)
61
+ - 5 个 `animation`(普通动画 / 预设 / 强调 / 顺序 / 清除)
62
+ - 2 个目录(页目录 vs 文档目录)、2 个缩放
63
+
64
+ 选错不会报错,只会把事情改到别的地方去,用户还看不出来。
65
+
66
+ ### 5. 写前确认
67
+
68
+ 动文档之前做两件事:
69
+
70
+ 1. **锁定目标**:用户可能开着多个文档。用切换文档类工具把目标钉死,
71
+ 否则切一次窗口就写到别的文件里去了。
72
+ 2. **建快照**:COM 写入不是事务,没有撤销。现在有补偿手段了 ——
73
+ - `wps_common_snapshot_create`:存一份磁盘副本,返回路径
74
+ - `wps_common_batch` 检测到破坏性/非幂等步骤时会**自动**建,不用你操心
75
+ - 改坏了用 `wps_common_snapshot_restore`;默认写出`.restored-<时间>`副本(不覆盖),
76
+ 要原地覆盖必须 `overwrite=true` + `confirm=true`,且**先关掉那个文档**(WPS 占着文件会 EBUSY)
77
+ - 两个诚实点必须转述给用户:从未保存过的文档建不了快照(会报 `[勿重试·先另存为]`);
78
+ 有未保存改动时,快照是**磁盘版本**,不含屏幕上还没存的内容
79
+
80
+ ## 三条红线
81
+
82
+ ### 一、`勿重试` 的错误绝不原样重放
83
+
84
+ 工具失败时返回的前缀已经写明了能不能重试:
85
+
86
+ | 前缀 | 含义 | 该做什么 |
87
+ |---|---|---|
88
+ | `[可重试·…]` | 请求**没执行** | 可以重放,退避一下 |
89
+ | `[勿重试·可能已执行一半]` | 可能已经改了一半 | **先查状态**(读回来看结果),不要重放 |
90
+ | `[勿重试·先改参数]` | 参数不对 | 改参数,不是重试 |
91
+
92
+ 超时和 COM 错误都属第二类。盲目重放 = 同一段内容写两遍、样式叠三层。
93
+
94
+ ### 二、破坏性工具要跟用户确认
95
+
96
+ `tools/list` 里每个工具都带 `annotations`,其中 `destructiveHint: true` 的那批
97
+ 会删内容、丢未保存改动、或原地转换格式(删除类、另存为、格式转换、关闭文档)。
98
+ 执行前先说一句,别默默干。
99
+
100
+ `readOnlyHint: true` 的那批不会动文档 —— 但也意味着它**根本没生效**,
101
+ 如果结果不对,别重复调用同一条,先怀疑前置步骤(没加载组、文档没打开、路径不对)。
102
+
103
+ ### 三、PPT 的结果要复核
104
+
105
+ `wps_search_tools` 的结果里有 `verified` 字段:`live` = 真机跑通过,`static` = 只有静态校验。**这个字段仍然要读**——
106
+ PPT 组里还有没逐条验证的,读它才知道哪个工具要额外复核。
107
+
108
+ PPT 组的真值(照 `scripts/manual/tool-verification.json` 的 `ppt` 条目,别凭印象说):
109
+
110
+ - 组级口径仍记 **`static`**:矩阵里仍有 5 条是**有据可查地跳过**的,不是漏跑;
111
+ - 但真机覆盖已经上量:PPT 组共 **100** 个工具,隔离验证矩阵 **103** 行(多出的行是旧名别名),
112
+ 实际执行 **98** 条、**全部跑通**,跳过的 **5** 条各有实测原因;
113
+ - 另有 **18** 个 PPT 工具在台账里逐条记为 `live`。
114
+
115
+ 所以**别说「PPT 没验证过」**,也**别说「PPT 全部验证过了」**——两句都不准确。
116
+ 真话是:绝大多数 PPT 工具跑过真机并有断言,个别几条因 WPS 侧限制或需人工介入而有据跳过。
117
+
118
+ `static` 不是「不能用」,是「没人在真机上验证过这一条」。用它做完事,要如实告诉用户
119
+ 「这个工具只做过静态校验」,别把「没报错」当成「做对了」。
120
+
121
+ ## 参考文档
122
+
123
+ 按需读,**不要一次全读**——它们加起来比本文还长。
124
+
125
+ | 文件 | 什么时候读 |
126
+ |---|---|
127
+ | `references/routing.md` | 意图定不准组、或两个工具不知道选哪个时 |
128
+ | `references/errors.md` | 调用报错、或要决定能不能重试时 |
129
+ | `references/recipes.md` | 任务跨多步(整篇论文排版、批量改格式、做演示)时 |
130
+ | `references/dsh.md` | **在 DeepSeek Harness 里跑的时候**(挂载写法、DSH 特有的坑、平台限制) |
@@ -0,0 +1,88 @@
1
+ # 在 DeepSeek Harness(DSH)里用本 MCP
2
+
3
+ > 什么时候读:**你正在 DSH 里跑**,或者用户说"用 DSH / Harness 调 WPS"。
4
+ > 在别的客户端(Claude Code / Cursor / CodeBuddy / WorkBuddy / Codex)里**不用读这篇**。
5
+
6
+ ---
7
+
8
+ ## 1. 怎么挂上去
9
+
10
+ **挂官方插件,不要挂我们的 bundle。**
11
+
12
+ bundle(`dsh-bundle/`)那份代码在真宿主里必然失败:它要 `import('@deepseek-ai/dsh-mcp-client')`,
13
+ 而那个包只在 DSH 自己的 `app.asar` 内部、只对 DSH 的代码可见。
14
+ **从 bundle 目录永远解析不到它** —— 这不是路径没配对,是解析边界。
15
+
16
+ 正确做法是在 patch 层直接挂官方插件:
17
+
18
+ ```yaml
19
+ - insert:
20
+ - id: mcp-wps
21
+ name: '@deepseek-ai/dsh-mcp-client'
22
+ config:
23
+ serverName: wps
24
+ transport: stdio
25
+ command: node
26
+ args:
27
+ - C:\绝对路径\wps-multitool-mcp\dist\index.js
28
+ toolCallTimeoutMs: 130000
29
+ failOnStartupError: true
30
+ ```
31
+
32
+ 生成这段配置:`node dist/index.js install --client dsh`(会写 `~/.dsh/wps.cordis.yml`)。
33
+
34
+ **三个字段每一个都有理由,别随手改**:
35
+
36
+ | 字段 | 为什么必须是它 |
37
+ |---|---|
38
+ | `command: node` + **绝对路径** | DSH 的 args 直接透传、不过 shell。Windows 上 `npx` 实际是 `npx.cmd`,按 `npx` 去 spawn 会 ENOENT |
39
+ | `toolCallTimeoutMs: 130000` | 必须 **≥ 桥的 `WPS_DAEMON_TIMEOUT`(默认 120000)**。DSH 默认 60000 会先掐断 —— 而 WPS 那边动作**已经改完了**,症状是"客户端报失败、文档其实改了" |
40
+ | `failOnStartupError: true` | 默认 `false` 会在连不上时**静默降级成"零工具"**,用户只会觉得"AI 不会用 WPS" |
41
+
42
+ ---
43
+
44
+ ## 2. DSH 特有的两个坑
45
+
46
+ ### 2.1 `desktop` profile 被 Electron 独占
47
+
48
+ CLI 只能用 `--profile web`,或者自己新建一个 profile。
49
+ 用 `desktop` 跑 CLI 会起不来(Electron 已经占着它)。
50
+
51
+ ### 2.2 装完必须清干净
52
+
53
+ 测完记得 `dsh plugin --profile web remove dsh-wps`,
54
+ 并确认 `dsh --profile web --dump-config` 里已经没有 `dsh-wps` 那一层。
55
+
56
+ ---
57
+
58
+ ## 3. 平台限制(这几条对 DSH 用户同样成立)
59
+
60
+ | 限制 | 说明 |
61
+ |---|---|
62
+ | **Windows only** | WPS 的 COM 自动化只在 Windows 可用。DSH 跑在别的系统上就没有这条通道 |
63
+ | **默认档 40 个工具** | DSH 会把工具定义塞进**每一次请求**,全量 284 个很贵。保持默认档,别在 DSH 里改成全量 |
64
+ | **超时上限 120 秒** | 那是**单次动作的上限**,不是常态耗时。正常一次调用 2~3 毫秒 |
65
+ | **Linux 通道还没有** | 本项目的跨平台路线尚未落地,DSH 在 Linux 上同样没有 |
66
+
67
+ ---
68
+
69
+ ## 4. 一条要提醒的读回限制
70
+
71
+ `wps_word_get_open_documents` / `wps_excel_get_open_workbooks` 在
72
+ **刚执行过 `quit` / `close` 之后**可能短暂读到 0 份 —— 那是 WPS 重新注册到 ROT 的那几秒窗口,
73
+ **文档其实还在**。所以:
74
+
75
+ - 读到 0 份时,**别据此告诉用户"文档没了"**;
76
+ - 隔一会儿再读一次,或**按文档名直接读内容**核实(那个更硬);
77
+ - 工具返回里带 warnings 时,**把 warnings 念给用户听**。
78
+
79
+ ---
80
+
81
+ ## 5. 出问题先看哪
82
+
83
+ | 症状 | 先查 |
84
+ |---|---|
85
+ | DSH 里一个 WPS 工具都没有 | `--dump-config` 里有没有 `dsh-wps` 那层;`failOnStartupError` 是不是 true |
86
+ | 报"文档其实改了但客户端说失败" | `toolCallTimeoutMs` 是不是小于 130000 |
87
+ | 工具列表为空但 CLI 手动跑正常 | 是不是在 `desktop` profile 上跑的 CLI |
88
+ | 桥进程正常但调用超时 | 单次动作 120 秒上限;看是不是发了个导出类大动作 |
@@ -0,0 +1,62 @@
1
+ # 错误前缀与应对
2
+
3
+ 工具失败时返回的文本以一个方括号前缀开头。**先读前缀,再读正文** ——
4
+ 前缀决定了能不能重试,重放错了会写两遍。
5
+
6
+ ## 能重试的(请求根本没执行)
7
+
8
+ | 前缀 | 典型正文 | 怎么办 |
9
+ |---|---|---|
10
+ | `[busy\|可重试·稍后退避]` | WPS 正忙(COM 拒绝调用) | 等一下再发,不要连发 |
11
+ | `[bridge_unavailable\|可重试·需先拉起桥]` | 桥进程没起来 | 先 `wps_common_status`,必要时 `wps_common_repair` |
12
+ | `[daemon_unavailable\|可重试·需先拉起桥]` | 桥客户端已关闭 | 同上 |
13
+ | `[app_not_running\|可重试·需先启动WPS]` | WPS 没开 | 让用户打开 WPS |
14
+ | `[cancelled\|可重试·排队中被取消]` | 请求还在排队就被撤了 | 可以直接重发 |
15
+
16
+ 排队被取消的那类**一定是安全的**——请求从未写进 WPS。
17
+
18
+ ## 不能重试的(可能已经执行了一半)
19
+
20
+ | 前缀 | 典型正文 | 怎么办 |
21
+ |---|---|---|
22
+ | `[timeout\|勿重试·可能已执行一半]` | 超过调用时限 | **先读回来看结果**(用读取类工具确认),确认没生效再重做 |
23
+ | `[com_error\|勿重试·可能已执行一半]` | COM 调用失败 / `RPC_E_CALL_REJECTED` | 同上;连续出现说明 WPS 弹了模态框 |
24
+ | `[invalid_params\|勿重试·先改参数]` | 参数不对 | 改参数,不是重试 |
25
+ | `[document_not_found\|勿重试·先打开文档]` | 没有活动文档 | 先建/开文档 |
26
+ | `[unsupported_operation\|勿重试·本机不支持该接口]` | WPS 版本没这个能力 | 换条路,别重试 |
27
+ | `[unknown\|勿重试·…]` | 没归类成功 | 按前缀给的原因处理;没有就当"可能已执行" |
28
+
29
+ **判据很简单**:请求有没有送到 WPS。送不到的可以重放,送到的先查状态。
30
+
31
+ ## 三个反复出现的坑
32
+
33
+ ### "没有活动文档",但用户明明开着文件
34
+
35
+ WPS 里存在"空壳文档":`Documents.Add()` 立刻返回,但文档还没真正建好,
36
+ 此时取它会报没有活动文档。遇到这个:
37
+
38
+ 1. 先 `wps_common_status` 看文档数是不是 0
39
+ 2. 是 0 就新建;不是 0 却取不到,说明是空壳 → `wps_common_repair`
40
+
41
+ ### 一串 `RPC_E_CALL_REJECTED`
42
+
43
+ 这是 WPS 弹了对话框(有模态框在等)。COM 是单线程的,对话框不关,
44
+ 后面所有调用都会被拒。
45
+
46
+ 处理:告诉用户"请检查 WPS 窗口有没有对话框没关",然后按 `[busy]` 的方式退避重试。
47
+
48
+ ### 一直报桥不通,但 WPS 是开着的
49
+
50
+ 桥和 WPS 是两回事。桥不通不代表 WPS 坏了。顺序:
51
+
52
+ 1. `wps_common_status` — 看桥状态与端口
53
+ 2. 桥起不来 → `wps_common_repair`
54
+ 3. 端口被占 → 换 `WPS_BRIDGE_HTTP_PORT` 再试
55
+
56
+ ## 取消
57
+
58
+ 客户端发取消通知时:
59
+ - 请求还在**排队** → 直接撤,安全,可以重发
60
+ - 已经**在途**(写进 WPS 了)→ 只读动作允许"不等了",写入动作**拒绝取消**
61
+
62
+ 也就是说:写入类操作发取消是无效的,别指望它能打断。
@@ -0,0 +1,83 @@
1
+ # 长任务配方
2
+
3
+ 跨多步的任务,先规划再动手。以下三例是本 MCP 里最常遇到的形态。
4
+
5
+ ## 通则
6
+
7
+ 1. **先探活**(`wps_common_status`),没有文档就先建/开
8
+ 2. **先读后写**:动手之前先读一份现状(现有样式、现有目录、现有数据),
9
+ 照着现状改,不要凭想象写
10
+ 3. **分批**:一次改几十处容易中途失败,前功尽弃。分批做,每批做完验证
11
+ 4. **做完读回来**:写完不验证等于没做。至少读一次确认落位了
12
+ 5. **破坏性动作前留快照**:让用户在 WPS 面板里存一份,MCP 侧没有撤销
13
+
14
+ ## 配方一:整篇文档排版
15
+
16
+ 目标:把一份论文/报告排成正式版式。
17
+
18
+ ```
19
+ 1. status → 确认文档在、桥通
20
+ 2. load_tool_group(word) → 加载文字组
21
+ 3. 读现状 → 现有标题都是什么样式?有没有目录?页边距多少?
22
+ 4. 套样式 → 正文套"正文"样式,标题按级别套"标题 1/2/3"
23
+ 5. 插目录 → 按标题级别生成(不要用重建版,会覆盖)
24
+ 6. 页眉页脚 + 页码 → 页码类工具
25
+ 7. 存快照 / 存盘
26
+ 8. 读回验证 → 抽查几段,确认样式落位、目录条目数对得上
27
+ ```
28
+
29
+ 坑:
30
+ - **别用重建目录**,用户手改过的目录字段会被冲掉
31
+ - 标题层级要连续。跳级(标题 1 直接到标题 3)会导致目录层级乱
32
+ - 套样式**替换**直接格式会让用户的加粗/颜色丢失,动手前说一声
33
+
34
+ ## 配方二:表格数据处理
35
+
36
+ 目标:一份数据表要算指标、套格式、做成图。
37
+
38
+ ```
39
+ 1. status + 打开工作簿
40
+ 2. load_tool_group(excel)
41
+ 3. 读现状 → 先读表头与前几行,确认数据范围和类型
42
+ 4. 写公式 / 批量写区域 → 公式优先于算好的值(用户改数据后能自动更新)
43
+ 5. 格式化 → 数字格式、条件格式、列宽
44
+ 6. 建图 → 图表类工具
45
+ 7. 存盘
46
+ 8. 读回验证 → 重读公式结果,确认没出现 #REF! / #DIV/0!
47
+ ```
48
+
49
+ 坑:
50
+ - **批量写区域前先确认范围**。写超了会覆盖旁边的数据,且无法撤销
51
+ - 公式用相对引用还是绝对引用要想清楚;整列套公式会拖慢 WPS
52
+ - 表头行通常要冻结,用户没说也要做(可逆、体验提升明显)
53
+
54
+ ## 配方三:做演示
55
+
56
+ ```
57
+ 1. status + 确认演示文稿已打开
58
+ 2. load_tool_group(ppt)
59
+ 3. 读现状 → 现有几张幻灯片、什么版式、有没有母版
60
+ 4. 定结构 → 先说清楚要几页、每页讲什么,再动手
61
+ 5. 逐页填内容 → 一次一页,每页填完读回来看
62
+ 6. 统一样式 → 配色 / 母版 / 字体一次定好,不要逐页微调
63
+ 7. 动画(可选)
64
+ 8. 存盘
65
+ ```
66
+
67
+ 坑:
68
+ - **PPT 组个别工具只有静态校验**(组级台账记 `static`:矩阵里 5 条有据跳过)。
69
+ 每一步做完都要读回来看,并按 `wps_search_tools` 返回的 `verified` 字段如实告诉用户
70
+ 「这个工具只做过静态校验」——别笼统说「PPT 没验证过」,那是错的;也别因为它跑通了就当全部都验过。
71
+ - 母版和单页样式冲突时,母版优先;逐页设的背景会被母版覆盖
72
+ - 加动画前先想清楚会不会让阅读变慢,不是每个元素都该动
73
+
74
+ ## 配方四:批量改格式
75
+
76
+ ```
77
+ 1. 读现状 → 搞清楚要改多少处、改完什么样
78
+ 2. 先改 2~3 处 → 读回验证
79
+ 3. 满意了再批量 → 前 3 处没验证就全量跑,错了要全量回滚
80
+ ```
81
+
82
+ 这是最危险的一类任务:范围大、影响面广、没有撤销。
83
+ 中途失败时,已改的部分留在那里,只能靠快照恢复。
@@ -0,0 +1,88 @@
1
+ # 路由与选型
2
+
3
+ ## 四个组
4
+
5
+ | 组 | 装什么 | 什么时候加载 |
6
+ |---|---|---|
7
+ | `core` | 工具组管理、搜索、意图识别 | 永远加载,不用管 |
8
+ | `word` | 文字:样式、修订、表格、交叉引用、索引、页眉页脚 | 动文档时 |
9
+ | `excel` | 表格:公式、图表、单元格、区域、工作表 | 动表格时 |
10
+ | `ppt` | 演示:版式、动画、母版、图表、配色 | 动演示时 |
11
+ | `common` | 跨应用:保存、建文档、状态、修复、格式转换 | 任何写操作前后 |
12
+
13
+ 默认只列 40 个基础工具。要用别的,先 `wps_load_tool_group`。
14
+
15
+ ## 什么时候别信意图识别
16
+
17
+ `wps_route_intent` 是关键词打分,组间语义差别大时它很准;下面这些情况**别硬猜**,
18
+ 直接 `wps_search_tools` 搜中文关键词("插入表格""改背景""做动画"都能命中):
19
+
20
+ - 一句话里同时提到两个应用("把这张表的数据做成 PPT")
21
+ - 诉求是排版/版式类("这篇论文排得像正式期刊")
22
+ - 搜出来的结果里 `notFor` 说"这个不干 X"—— 说明还有更合适的
23
+
24
+ ## 近名工具分辨表
25
+
26
+ 本 MCP 里有大量近名工具。选错**不会报错**,只会把事情改到别处,用户还看不出来。
27
+
28
+ ### 目录 / 索引 / 交叉引用(最常混)
29
+
30
+ | 需求 | 用 | 不是什么 |
31
+ |---|---|---|
32
+ | 按标题级别生成目录 | `wps_word_generate_toc` | 不是重建整篇目录(会覆盖) |
33
+ | 整篇重建目录 | `wps_word_generate_doc_toc` | 不是插段落 |
34
+ | 插"见图 3"这类引用 | `wps_word_cross_reference` | 不是参考文献、不是索引 |
35
+ | 插关键词索引表 | `wps_word_index` | 不是目录 |
36
+
37
+ ### 样式:套用 vs 定义
38
+
39
+ | 需求 | 用 |
40
+ |---|---|
41
+ | 给已有段落套"标题 1"样式 | `wps_word_apply_style` |
42
+ | 新建一个自定义样式 | `wps_word_add_style` |
43
+ | 改样式定义本身 | `wps_word_modify_style` |
44
+ | 删样式定义 | `wps_word_delete_style` |
45
+ | 插入一级标题段落 | `wps_word_add_heading` |
46
+
47
+ ### 表格:插入 vs 改造
48
+
49
+ | 需求 | 用 |
50
+ |---|---|
51
+ | 新建一张表 | `wps_word_insert_table` |
52
+ | 改已有表的样式/边框 | `wps_word_format_table` / `wps_word_set_cell_borders` |
53
+ | 合并单元格 | `wps_word_merge_table_cells` |
54
+ | 拆单元格 | `wps_word_split_cell` |
55
+
56
+ ### Excel:单条 vs 批量
57
+
58
+ | 需求 | 用 |
59
+ |---|---|
60
+ | 写一个格子 | `wps_excel_set_cell_value` |
61
+ | 写一大片区域 | `wps_excel_write_range` |
62
+ | 写公式 | `wps_excel_set_formula` |
63
+ | 插一行 / 多行 | `wps_excel_insert_row` / `wps_excel_insert_rows` |
64
+ | 缩放(`zoom` 与 `set_zoom` 重复) | 二选一,优先 `set_zoom` |
65
+
66
+ ### 修订 vs 批注
67
+
68
+ | 需求 | 用 |
69
+ |---|---|
70
+ | 查看/接受/拒绝已有修订 | `wps_word_revisions` |
71
+ | 插入一条新批注 | `wps_word_insert_comment` |
72
+
73
+ ### PPT 的背景与动画
74
+
75
+ `background` 有 6 个、`animation` 有 5 个,全部靠名字分不出来。
76
+ **先搜再读 `notFor`**,不要凭名字挑:不同工具管的是幻灯片背景 / 母版背景 /
77
+ 图表区背景,纯色 / 图片 / 渐变又是三回事;动画分普通 / 预设 / 强调 / 顺序 / 清除。
78
+
79
+ ## 搜索返回什么
80
+
81
+ ```
82
+ name 工具名
83
+ group 所属组(未加载时 listed: false)
84
+ listed 当前是否已列出
85
+ aliases 中文别名
86
+ examples 什么诉求用它
87
+ notFor 它不干什么、该用谁 ← 必读
88
+ ```
@@ -0,0 +1,72 @@
1
+ # dsh-multitool 组合包 · 配置层
2
+ #
3
+ # 一个包同时给两样东西:
4
+ # ① 40 个 WPS 工具(挂官方 MCP 客户端)
5
+ # ② 一份教 AI 怎么用这些工具的技能(assets/wps-multitool/SKILL.md)
6
+ #
7
+ # 关键点(2026-10-22 实测,别改回去):
8
+ # - 插件行按【包名】引用,由 dsh 的 loader 解析,不写相对源码路径。
9
+ # 我们自己的代码去 import('@deepseek-ai/dsh-mcp-client') 会失败 ——
10
+ # 那个包只在 dsh 的 app.asar 内部可见,从 profile 目录永远解析不到。
11
+ # - assetRoot / args 必须是【绝对路径】,发布时不可能知道用户装在哪,
12
+ # 所以用 !!js 在 loader 求值时算。求值上下文提供 baseUrl 与 process.getBuiltinModule。
13
+
14
+ # ① 挂官方 MCP 客户端,指向本机的 wps-multitool-mcp
15
+ - insert:
16
+ - id: mcp-wps
17
+ name: '@deepseek-ai/dsh-mcp-client'
18
+ config:
19
+ # serverName 决定工具名前缀:mcp__<serverName>__<工具名>
20
+ #
21
+ # 这里用 wpslocal 而不是 wps,原因是【避免和另一个包撞车】:
22
+ # npm 上已有 dsh-wps@0.1.2(别人做的,WPS/金山文档【云文档】集成),
23
+ # 它的工具前缀也是 mcp__wps__*。两边装在一起就会同名冲突。
24
+ # 我们操作的是【本机正开着的 WPS 窗口】,不是云文档,所以叫 wpslocal 更准确。
25
+ # dsh 的 serverName 规则:^[A-Za-z0-9_-]{1,32}$,wpslocal 合规。
26
+ serverName: wpslocal
27
+ transport: stdio
28
+ # 必须 node + 绝对路径,不能用 npx:dsh 的 args 直接透传、不过 shell,
29
+ # Windows 上 npx 实际是 npx.cmd,按 npx 去 spawn 会 ENOENT。
30
+ command: node
31
+ args:
32
+ # 两档解析:先按依赖解析(用户把它作为依赖装了),
33
+ # 解析不到就退回【本包同级目录】(开发者本地 checkout 的情形)。
34
+ - !!js >-
35
+ (() => {
36
+ const req = process.getBuiltinModule('node:module').createRequire(baseUrl);
37
+ const fs = process.getBuiltinModule('node:fs');
38
+ const path = process.getBuiltinModule('node:path');
39
+ try {
40
+ const got = req.resolve('wps-multitool-mcp/dist/index.js');
41
+ if (fs.existsSync(got)) return got;
42
+ } catch {}
43
+ return path.join(path.dirname(req.resolve('dsh-multitool/package.json')), '..', 'wps-multitool-mcp', 'dist', 'index.js');
44
+ })()
45
+ # 必须 >= 桥的 WPS_DAEMON_TIMEOUT(默认 120000)。dsh 默认 60000 会先掐断,
46
+ # 而 WPS 那边动作已经改完了 —— "客户端报失败、文档其实改了"。
47
+ toolCallTimeoutMs: 130000
48
+ # 默认 false 会在连不上时静默降级成"零工具",用户只会觉得 AI 不会用 WPS。
49
+ failOnStartupError: true
50
+ env:
51
+ # 保持默认档:dsh 会把工具定义塞进每一次请求,284 个全量很贵。
52
+ WPS_TOOL_TIER: essential
53
+
54
+ # ② 启用技能系统,把本包的 assets/ 加进扫描根
55
+ #
56
+ # 这两个插件在 web 模板里默认是 disabled: true。
57
+ # 这里按 id 覆盖、且不写 disabled —— 等于重新启用它们。
58
+ # (官方语义:后层按 id 整行覆盖,config 是整体替换不是深合并,所以 name 必须写全。)
59
+ - id: skill-filesystem
60
+ name: '@deepseek-ai/dsh-skill-filesystem'
61
+ config:
62
+ customSkillDirs:
63
+ - !!js >-
64
+ process.getBuiltinModule('node:path').join(
65
+ process.getBuiltinModule('node:path').dirname(
66
+ process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dsh-multitool/package.json')
67
+ ),
68
+ 'assets'
69
+ )
70
+
71
+ - id: tool-skill
72
+ name: '@deepseek-ai/dsh-tool-skill'
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
2
  "name": "dsh-multitool",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.1",
4
+ "description": "WPS Office 多面手 MCP 的 DeepSeek Harness 组合包 —— 让 AI 直接操控你正开着的 WPS 文字/表格/演示。常驻桥进程(每次调用 2~3ms)· Windows only · 一条命令同时装上 40 个工具和一份教 AI 怎么用它们的技能 · 作者赢容",
5
+ "type": "module",
6
+ "files": [
7
+ "cordis.patch.yml",
8
+ "assets",
9
+ "README.md"
10
+ ],
11
+ "dependencies": {
12
+ "wps-multitool-mcp": "^1.0.2"
13
+ },
14
+ "engines": {
15
+ "dsh": ">=0.2.0 <0.3.0"
16
+ },
17
+ "dsh": {
18
+ "bundle": {
19
+ "patch": "./cordis.patch.yml"
20
+ }
21
+ },
22
+ "keywords": [
23
+ "dsh-plugin",
24
+ "deepseek-harness",
25
+ "dsh",
26
+ "mcp",
27
+ "wps",
28
+ "office",
29
+ "skill"
30
+ ],
31
+ "author": "赢容",
32
+ "license": "MIT",
33
+ "repository": {
34
+ "type": "git",
35
+ "url": "git+https://github.com/forkgo430/wps-multitool-mcp.git",
36
+ "directory": "dsh-bundle"
37
+ }
38
+ }