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/审批/标点规范等改进都是这样热更新上去的）

兼容性

核心只依赖 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 生成图表 / 把选中的翻译成英文"等请求时会自动调用桥接。

二、架构

多文档模型：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 单选区）。

通用

Word 组

Excel 组

PPT 组

环境诊断

四、能力边界（实测结论，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 错误码降级

设计原则：环境不支持的 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 即收到全部更新（当前无其他安装者，随仓库演进）。

七、排查

八、能力发现（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 处理建议与是否可重试）：

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

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