dsh-office-for-mso

English · 日本語 · 中文

DeepSeek Harness（DSH）的 Microsoft Office 插件/技能（v1.3）：在 DSH 会话里发指令，通过 Microsoft Office 加载项操控你正在打开的 Word / Excel / PowerPoint 文档——读取、写入、格式化、结构操作、图表/公式/批注，接近 Copilot for Office 的常见工作流。（本项目的 Office 指 Microsoft Office，不含 WPS 等兼容产品）

你 ──DSH 会话发指令──▶ AI(agent) ──POST──▶ 桥接服务 localhost:3000
                                                │ 指令入队（按 host 路由）
                           Office 加载项（文档内后台轮询，1s）
                                                │ Office.js 执行（34 个 action）
                                                ▼
                            结果回传 ──▶ AI 取回 ──▶ 汇报给你

• 不冲突：加载项跑在 Office 进程内，操作内存文档，与你的编辑由 Office 统一串行处理（无文件锁、无"最后保存者赢"）
• 无侧边栏交互：窗格只是状态显示，所有指令从 DSH 下发
• 🔥 热更新（卖点）：所有 action 实现在 actions.js，改它 → 重启桥接服务 → 窗格自动热更新，无需重开窗格——按你的使用需求随时定制 action，DSH 自动生效；也支持按用户反馈快速迭代（本项目的 re-read/审批/标点规范等改进都是这样热更新上去的）

---

兼容性

平台	核心（server.js + 加载项）	自动托管（计划任务）	自动 sideload（WEF 注册表）	管理脚本（ps1）
Windows	✅ 仅需 Node.js	✅ install.ps1	✅ server 启动自动	✅ 系统自带 PowerShell，直接用
macOS	✅ 仅需 Node.js	❌ 手动 node server.js	❌ Office 菜单手动加载	⚠️ 可选：装 PowerShell Core 才能跑 ps1 脚本；不装不影响核心使用
Linux	⚠️ 无 Office 桌面版加载项宿主（服务器/CI 场景不适用）	—	—	—

核心只依赖 Node.js；PowerShell 是管理便利工具（非运行依赖），Windows 零额外安装，macOS 可选。

一、部署（一次性）

0. 前置条件

• 本技能是 DeepSeek Harness（DSH） 的插件/技能：需先安装 DSH（DeepSeek Harness，基于 Node.js 的 AI 会话环境），并在 DSH 会话中使用本技能
• Node.js ≥ 18（DSH 与桥接服务都依赖）
• Microsoft Office 桌面版（Word / Excel / PowerPoint，Windows 或 macOS）

1. 克隆仓库并安装（推荐：一键常驻服务）

git clone https://github.com/Mikuzjc/dsh-office-for-mso.git
cd dsh-office-for-mso
npm run setup   # 一键：注册计划任务（登录自启、静默常驻）+ 启动服务 + 自动注册加载项（首次会弹 UAC，点「是」）

npm run setup 是正式安装：服务由 Windows 计划任务托管，登录自启、后台常驻，关闭终端不影响运行。 只想临时预览：node server.js（前台运行，关终端即停服务）。

Windows 下服务启动时会自动注册加载项（WEF 注册表）——首次请关闭并重新打开 Office 文档，窗格即出现；macOS 需用 Office 菜单手动加载（见 1.2/1.3）。 （下文路径示例均以你的实际项目目录为准。）

2. 把加载项加载到 Microsoft Office（sideload）

平台：核心（server.js + 加载项）仅依赖 Node.js，Windows / macOS 均可运行；install.ps1/计划任务为 Windows 专属的可选自动托管，macOS 手动 node server.js 即可。

Windows 用户：无需手动 sideload——node server.js（或 npm run setup）启动时自动注册加载项（WEF 注册表，普通权限即可）。首次关闭并重新打开 Office 文档即出现窗格。 仅当需要手动管理时：

cd <你的项目目录>
powershell -ExecutionPolicy Bypass -File sideload.ps1   # 手动注册（-Remove 移除）

macOS 用户：无自动注册，请用 Office 菜单手动加载（见下方开发人员加载项流程）：

1. 启用开发人员选项卡：文件 → 选项 → 自定义功能区 → 主选项卡勾选「开发人员」 → 确定
2. 打开任意 Word / Excel / PowerPoint 文档
3. 开发人员选项卡 → 加载项（或 插入 → 我的加载项）→ 打开「Office 加载项」对话框
4. 对话框底部左侧「管理」下拉选择 开发人员加载项
5. 点 +（添加） → 选择 <你的项目目录>\manifest.xml
6. 侧边栏出现「DSH Office 执行器」窗格，显示 已连接：等待 DSH 指令 即成功

之后保持文档打开即可；窗格可缩小/拖角落，无需操作。

旧版 Office 若仍有「上传我的加载项」入口，也可直接使用。 换电脑：重复以上两步（桥接服务 + 上传 manifest）即可。

1.3 首次使用

安装后，需手动打开一次加载项，DSH 会话才能操作文档：

1. 打开 Word / Excel / PowerPoint 文档
2. 开始（或开发人员）标签页 → 加载项 → 开发人员加载项 → 「DSH Office 执行器」
3. 出现窗格（显示 已连接：等待 DSH 指令）后，即可在 DSH 会话下发指令
4. 窗格可调小/拖到角落，但使用时必须保持开启——它承载 Office.js 执行，关闭后 DSH 无法操作该文档

之后保持文档打开 + 窗格开启即可；窗格意外关闭时 DSH 会提示（addin_offline），按步骤 2 重新打开即可。

1.4 让 DSH 主动使用本技能（重要）

DSH 只会主动调用技能库（~/.agents/skills/）中的技能——仅 clone 仓库不会让 DSH 自动使用。请把本仓库的 SKILL.md 安装进技能库：

# Windows：复制进 DSH 技能库
mkdir "$HOME\.agents\skills\office-bridge" -Force | Out-Null
copy "skills\office-bridge\SKILL.md" "$HOME\.agents\skills\office-bridge\"

或使用 DSH 设置面板的「技能管理」创建 office-bridge 技能（内容见 skills/office-bridge/SKILL.md）。安装后，主模型看到技能描述，在"读 Word 全文 / Excel 生成图表 / 把选中的翻译成英文"等请求时会自动调用桥接。

二、架构

文件	职责
server.js	桥接服务：指令队列、host 路由、心跳、静态文件、能力发现 /office/capabilities、actions 版本 /office/actions-version
taskpane.js	加载项外壳：轮询/心跳/分发/热更新加载（尽量少改，改动需重开窗格）
actions.js	全部 action 实现 + 注册表（热更新单元：改它无需重开窗格）
pako.min.js	本地 zip 解压库（PPT OOXML 读取用，离线）
manifest.xml	加载项清单（权限 ReadWriteDocument，已到顶）
skills/office-bridge/SKILL.md	DSH 技能包：教 AI 使用桥接的完整指令（查状态→发指令→错误处理→安全约定）

多文档模型：Word / Excel / PowerPoint 各自运行一个加载项实例；指令带 host（Word/Excel/PowerPoint）精确路由，GET /office/status 返回在线文档列表（hosts 字段）、**实例明细（instances 字段：instanceId / host / docUrl 文档路径 / docTitle 文档名，用于识别目标文档，docUrl 为空时用 docTitle）**与窗格启动记录（hellos）。

热更新机制：窗格每次轮询前 GET /office/actions-version，比对 actions.js 的 mtime，变化则动态重载脚本。改 actions.js → 重启 server → 自动生效。

三、能力矩阵（36 个 action）

destructive=true 的操作支持 args.dryRun 预览影响（replace_all / remove_empty_paragraphs / delete_sheet 已实现；其余 AI 层先读后写）。W=Word，E=Excel，P=PowerPoint。 改完自动选中（零副作用，仅选中反馈、不改内容/样式）：写入动作执行后自动选中改动处 —— replace_all 选最后一处 / append_text、insert_paragraph 选插入内容 / write_range 选写入区域 / write_selection 由宿主保持选中；多处替换只能选中一处（Office.js 单选区）。

通用

action	平台	说明
read_selection	W/E/P	读取当前选区文本；withStyles=true 附带样式
write_selection	W/E/P	用 {text} 替换当前选区
read_document	W/E/P	Word 全文；Excel 工作表已用区域（sheet 指定表名，5000 格截断）；PPT 全文件逐页文本
read_styles	W/E	选区样式：Word（字体/字号/加粗/斜体/颜色/下划线/高亮）；Excel（逐格，上限 10×10）
replace_all	W/E	全文查找替换 {search, replace, dryRun?}
append_text	W	文末追加段落 {text}
locate_select	W/E	定位并选中（零副作用，不改内容/样式）：{text} 首个匹配 / {bookmark|anchor} / Excel {range|address}（可带 sheet）；blinks>0 才闪烁，默认只选中保持
get_document_info	W/E/P	Common API 文档信息：url / title / mode（只读判断）/ settings 键值（keys 精确读）——一直可用，无需 Word.run
set_setting	W/E/P	文档设置持久化 {key, value}（随文档保存，跨会话可读）——文档级状态标记用

Word 组

action	说明
read_tables	结构化读取全部表格（逐单元格，getRange().text 按 \t/\r 切分）
set_font	全文（含表格段落）设置字体 {font}
remove_empty_paragraphs	删除空段落（跳过含图片段落与文档结尾段，dryRun 预览）
insert_paragraph	插入段落 {text, style?, location?}（style 支持 标题1-3/正文/引用/强调）
insert_table	插入表格 {rows} ⚠️ 此环境 Word.js 表格插入 API 全部不可用（见环境边界）
insert_image	选区插图 {base64, width?, height?}
apply_style	应用内置样式 {style, scope: selection|all}
format_selection	选区格式化 {font, size, bold, italic, color, highlight}
set_paragraph_format	段落格式 {alignment, indent, lineSpacing, listType} ⚠️ 此环境 paragraphFormat 不可用
search	查找 {query, matchCase?, wildcard?} 返回命中列表
add_comment	选区加批注 ⚠️ 此环境 Word comments API 不可用
read_comments	列出批注 ⚠️ 同上
read_properties	文档属性（标题/作者/字数等）

Excel 组

action	说明
list_sheets	列出工作表（名称/位置/可见性）
read_range	读区域 {address: "Sheet1!A1:B10", limit?}（值/公式/数字格式）
write_range	批量写 {address, values?/formulas?}（二维数组，>5000 格自动分块）
format_range	区域格式化 {address, font, size, bold, fill, numberFormat, autoFit, tableStyle}
insert_chart	数据→图表 {type: Column/Line/Bar/Pie/Area/Scatter/…, dataRange, title?}
add_sheet / rename_sheet / delete_sheet	工作表管理（delete 支持 dryRun）
apply_sort	排序 {address, fields: [{column, ascending}]}
apply_filter	AutoFilter {address, columns?}
evaluate_formula	公式求值 {formula: "SUM(A1:A10)"}（白名单 SUM/AVERAGE/COUNT/MAX/MIN/PRODUCT，workbook.functions 类型化求值）
add_comment / read_comments	单元格批注（cell 可带表名前缀自动剥离）
read_properties	工作簿属性

PPT 组

action	说明
read_slides	当前选中页列表（SlideRange：id + title）
ppt_read_notes	全文件备注（OOXML 解析 notesSlides + rels 映射）
read_document	全文件逐页文本（通用）

环境诊断

action	说明
get_environment	宿主版本/平台/requirementSets 支持情况 + Word 对象模型深层探测（用于定位环境边界）

四、能力边界（实测结论，2026-08）

归因澄清：以下"不可用"分两类——

• 平台级不可能（Office.js 规范无此 API，所有版本/机器都做不到）：PPT OOXML 写入、Word 页面设置/目录/剪贴板移动、窗格程序化刷新
• 本机运行时缺失（requirementSets 声明支持 WordApi 1.8/ImageCoercion 1.1，但运行时对象属性实际缺失；非 node.js 问题、非 CDN 缓存——已验证）：Word 批注（body.comments 属性不存在）、paragraphFormat（属性不存在）、表格插入（insertTable/insertOoxml 存在但调用失败）。换机器/更新 Office 很可能可用，本项目如实返回 requirement 错误码降级

平台	可用	不可用及类别
Word	段落/文本插入替换、全文/表格读取、字体设置、样式应用、选区格式化、查找、文档属性、空段清理	表格插入 / paragraphFormat / 批注（本机运行时缺失）；页面设置/目录/剪贴板（平台级）
Excel	工作表管理、区域读写（批量）、格式化、图表、排序、筛选、公式求值、批注、属性	workbook.getRange/calculate 不存在（已用替代 API 绕过）；Range.autoFilter 须用 worksheet 级
PPT	全文件文本/备注读取、SlideRange	OOXML 写入、新建幻灯片/排版（平台级）

设计原则：环境不支持的 API 返回 code: requirement | unsupported | execution，AI 层据此降级或如实告知，绝不假装成功。

五、安全护栏

• 覆盖类操作写前 re-read（机制级）：所有覆盖操作（写入/替换/删除/格式化覆盖）执行前自动读取当前状态，绝不凭记忆覆盖。确认模式由环境变量 OFFICE_CONFIRM_MODE 控制：ask（默认）= re-read 后必须用户确认（confirm: true）；auto = 自动 re-read 后执行、结果附 previousState 供核验。改后重启服务生效（GET /office/config 可查当前模式）

• 破坏性操作 dryRun：replace_all / remove_empty_paragraphs / delete_sheet 支持 dryRun 返回影响预览，AI 层默认先预览后执行

• 图片段落保护：删除空段落时跳过含 inlinePictures 的段落（曾误删流程图，已修复）

• 文档结尾段保护：Word 最后一段（段落标记）不可删除

• 性能护栏：Excel 批量写分块（≤5000 格/批）、getUsedRange(true) 避免全列格式爆炸、大表读截断

六、服务托管（生产环境）

推荐：Windows 计划任务「DSH Office Bridge」（登录自启，静默运行）

• 一键安装：powershell -ExecutionPolicy Bypass -File install.ps1（自动按当前目录注册，跨机器通用，无需改路径）
• 手动注册：触发器=用户登录时启动；Settings=常驻无时限、StartWhenAvailable；启动命令=powershell -NoProfile -WindowStyle Hidden -Command "& '<node完整路径>' '<项目目录>\server.js'"（静默，无窗口）
• 手动管理：
  • 启动：Start-ScheduledTask -TaskName 'DSH Office Bridge'
  • 停止：按端口找进程 netstat -ano | findstr :3000 → Stop-Process -Id <pid>
  • 重启（改代码后）：停进程 → Start-ScheduledTask -TaskName 'DSH Office Bridge'

开发时：powershell -ExecutionPolicy Bypass -File start.ps1 前台运行；npm start 亦可。

自检：powershell -ExecutionPolicy Bypass -File smoke-test.ps1（检查服务/端点/在线文档）。

六·五、用户定制（user-actions.js，更新不冲突）

按需定制/覆盖 action（如加自己的函数、改内置行为），与上游更新隔离：

1. 项目根目录创建 user-actions.js（已在 .gitignore，update.ps1 拉取不会碰它）：

   window.__USER_ACTIONS__ = {
     my_action: { hosts: ['Word'], destructive: false, impl: (host, args) => ({ ok: true, result: { text: String(args.text || '') } }) },
     // 同名覆盖内置：write_selection: { hosts: ['Word'], destructive: true, impl: myVersion }
   };
   

2. 重启桥接服务 → 定制 action 热更新生效（无需重开窗格）
3. 定制 action 与内置一样支持审批/写后验证（定义了 destructive/preview 时）

六·六、更新（已安装用户）

拉取最新版并生效（一条命令）：

cd <你的项目目录>
powershell -ExecutionPolicy Bypass -File update.ps1   # git pull + 自动重启服务

• actions.js 改动：重启服务后窗格自动热更新，无需重开窗格（最快迭代路径）
• 外壳（taskpane.js/html）改动：需重开一次窗格
• server.js / install.ps1 改动：update.ps1 已自动重启服务；计划任务定义变了需重跑 install.ps1

没有自动推送机制：已安装用户执行一次 update.ps1 即收到全部更新（当前无其他安装者，随仓库演进）。

七、排查

现象	处理
窗格显示「桥接服务未连接」	确认 node server.js 在跑（/office/status 有响应）
DSH 指令报 timeout	加载项没在线：确认文档打开 + 窗格显示已连接
DSH 指令立即返回 addin_offline	窗格未开启：打开文档 → 开始/开发人员 → 加载项 → 开发人员加载项 → 打开「DSH Office 执行器」窗格并保持开启
窗格没出现	重新上传 manifest；确认 Office 未以管理员运行（localhost 例外要求普通权限）
修改没生效	确认执行位置（光标/选区）正确；查看窗格执行日志
改了 actions.js 没生效	重启桥接服务（窗格自动热更新，无需重开窗格）
改了 taskpane.js 没生效	需手动重开窗格（外壳代码无法程序化刷新，Office 桌面版限制）

八、能力发现（AI 侧）

• GET /office/capabilities → action 注册表（名称/平台/是否破坏性/参数说明）
• GET /office/status → 在线文档（hosts）+ 窗格启动记录（hellos）
• GET /office/actions-version → actions.js 版本（热更新比对）

九、AI 使用约定（供 DSH 等 AI 调用方）

• 发指令前先 GET /office/status：确认目标 host 在线（hosts 含该文档且心跳新鲜）再发指令
• 收到 code: addin_offline 时不要重试，应提醒用户：打开目标文档 → 开始/开发人员 → 加载项 → 开发人员加载项 → 打开「DSH Office 执行器」窗格并保持开启
• 窗格必须保持开启才能执行操作（可调小/拖角落，但不可关闭）

十、错误码速查（AI 侧）

所有错误统一返回 {ok:false, code, error}（error 为人类可读中文原因），完整枚举可随时 GET /office/errors 获取（含每码的 AI 处理建议与是否可重试）：

code	含义	AI 处理
instance_required	缺 instance（多文档必须指定目标实例）	查 status 拿 instanceId 重发
addin_offline	窗格未开启/离线	提醒用户开窗格，不要重试
busy	上一条指令仍在执行	稍等重发
timeout	90s 无结果	查 status；在线可重试一次，仍超时提醒重开窗格
bad_json / bad_args	请求体/参数非法	按 error 修正后重发
unknown_action	action 名不存在	查 capabilities 用正确名称
unsupported_host	该 action 不支持当前应用	换用支持的 action/应用
confirm_required	ask 模式需审批	展示 result.preview，确认后带 confirm:true 重发
rejected	用户在窗格拒绝/审批超时	停止操作，不要重发
not_found	定位/查找目标不存在	如实告知用户，不要重试同一查找
readonly	文档只读/查看模式，写操作被拒	告知用户另存为可编辑副本，不要重试
requirement / unsupported	环境 API 缺失	如实告知，绝不假装成功
execution	执行期异常	把 error 原样报告给用户

"无匹配"不是错误：search/replace_all(dryRun) 无命中返回 ok:true + count:0，read_*/list_* 空内容返回空数组/空字符串——均非错误，AI 应如实告知"未找到"而非重试。

---

非微软官方产品。DSH 是社区 AI 工具箱生态；本项目是 DSH 与 Microsoft Office 之间的独立桥接。 Vibe-coded：本项目由人类与 AI 结对协作开发（AI 辅助编码），全部功能经真实文档实测验证。