shield_lock
JinDaGe
← Back to skills
extension
Category: Productivity & OfficeNo API key required

福昕 Office 连接助手

福昕 Office 连接助手是整套福昕Office Skill套件能力的前置检查工具。它会在执行文档操作前，自动验证本地 Office 环境、注册项、依赖库与进程状态；发现异常时给出明确的修复步骤，避免在正式任务中因环境问题中断任务。

personAuthor: foxitnethubgithub
open_in_newRepositorydownloadDownload package

fuxin-office-bridge — 福昕 Office 连接与预检技能

定位: 基础设施技能，供 fuxin-word / fuxin-excel / fuxin-ppt / fuxin-doc-qa / fuxin-batch-undo 及 fuxin-office 汇总层调用，不直接面向最终用户的编排。 依赖: FuxinAiService（端口由 MCPServerPort.ini 动态读取，见下「运行端口」）

功能概述

本技能负责执行 5 层预检，确保福昕 Office 集成链路完整，并在任一环节失败时 给出明确的诊断与操作指引。它是所有写操作前必须执行的"第一道闸门"， 也是用户提示文案（「用户提示文案（统一出口）」章节）的统一出口。

⚠️ 与旧版差异：本技能不存在 Bridge_check_office_ready 这一场景工具。 预检通过 REST 接口 + 各产品只读工具 组合实现，无需也不允许调用名为 *_check_office_ready 的工具。

运行端口（动态读取 · v2.2 起）

⚠️ 端口非固定值 58688：网关监听端口可能随环境变化，禁止硬编码。 本技能统一从此配置文件读取端口，供本章第 1 层 GET /api/... 及所有 REST 调用拼 base URL 使用。 其他技能（word/excel/ppt/doc-qa/batch-undo/office）一律引用本小节，不自行写死端口。

配置文件路径：%ProgramData%\Foxit Software\Fuxin Office\MCP\MCPServerPort.ini （%ProgramData% 为环境变量，实际目录视机器而定，如 C:\ProgramData；禁止写死盘符）

[MCPServer]
ListenPort=58688

用 shell / PowerShell 读取并拼 base URL：

$ini = Join-Path $env:ProgramData 'Foxit Software\Fuxin Office\MCP\MCPServerPort.ini'
$m  = Get-Content $ini -Raw | Select-String '^\s*ListenPort\s*=\s*(\d+)'
$port = $m.Matches[0].Groups[1].Value
$base = "http://127.0.0.1:$port"   # 后续所有 REST 调用以此为准

若运行环境无 shell/PowerShell，可让网关暴露读配置的只读端点，但首要按上述读取判断。

预检决策树（5 层）

第0层  本机是否已安装福昕Office
        未安装 → 状态=未安装，引导下载/安装（「Office 未安装」文案）
        ↓ 已安装
第1层  GET /api/skill/products
        失败/拒连 → 未就绪（Gateway 未启动）
        ↓ 成功
第2层  GET /api/skill/products 返回的列表是否为空？目标产品在列表？
        ▸ 列表为空 → 先探测福昕Office 应用进程是否在运行（PowerShell Get-Process）：
            · 进程在运行 → 半就绪（Office 已启动，但未开启任一产品/无活动文档）→ 「无活动文档」
            · 进程未运行 → 未就绪（Office 未运行/插件未加载/连接失败）→ 「未运行」
        ▸ 列表非空但缺目标产品  → 半就绪（Office 已启动，目标产品未启动/无活动文档）
        ↓ 目标产品在列表
第3层  GET /api/skill/product/{产品}
        失败 → 未就绪（产品层连接失败）
        ↓ 成功
第4层  MCP tools/call {产品}_get_path / _get_document_info / _get_doc_status
        无活动文档 → 半就绪（需打开文档）
        成功  → 就绪
        ↓
第5层  （Word 额外）{产品}_get_document_info / _get_doc_status
        读取 is_empty / is_read_only / page_count 等，并入就绪清单

第2层进阶：进程运行判定（列表为空时用）

当 GET /api/skill/products 返回空列表时，先探测福昕Office 应用进程是否在真实运行， 用于区分「Office 已启动但未开启任一产品」与「Office 未启动」两种状态：

# 探测福昕Office 及其三大组件进程（任一个在运行即视为 Office 应用已启动）
$names = 'FuxinOffice','FuxinOfficeWord','FuxinOfficeExcel','FuxinOfficePPT'
$proc = $names | ForEach-Object { Get-Process -Name $_ -ErrorAction SilentlyContinue } | Select-Object -First 1
$office_running = $null -ne $proc   # $true=进程在运行；$false=未运行

判定口径：

  • 进程在运行 → 判「半就绪」，输出「无活动文档」文案。
  • 进程未运行 → 判「未就绪」，输出「未运行」文案。

应用进程名为 FuxinOffice* 体系（主程序 FuxinOffice.exe 及 FuxinOfficeWord / FuxinOfficeExcel / FuxinOfficePPT 组件），仅用于判定「整装 Office 应用进程是否已启动」，不按产品拆分。

第 0 层：真实安装判定（v2.1 定稿 · 读注册表 + 校验文件）

⚠️ 误区根源：GET /api/skill/products 列出的 product 来自 %ProgramData%\Foxit Software\Fuxin Office\MCP\products\{产品}\tools.json（DEBUG 导出产物）。 目录存在 ≠ 真安装——任意一次 DEBUG 启动都会固化"已安装"。因此禁止用 products 列表或该目录存在性作为"是否已安装"的依据。

本层通过 shell / PowerShell 读取注册表并校验可执行文件真实存在（不强依赖网关新端点）：

# 读取注册表安装信息
$key='HKLM:\SOFTWARE\WOW6432Node\Foxit Software\Fuxin Office'
$ip=(Get-ItemProperty $key -ErrorAction SilentlyContinue).InstallPath   # 如 C:\Program Files (x86)\Fuxin Office\
$ian=(Get-ItemProperty $key -ErrorAction SilentlyContinue).InstallAppName # 如 FuxinOffice.exe
# 校验可执行文件真实存在
$exe=Join-Path $ip $ian
$installed = $ip -and $ian -and (Test-Path $exe)   # 三条件全满足才判定已安装

判定口径：注册表键存在 + InstallPath 非空 + InstallAppName 非空 + 拼出的 exe 文件真实存在， 四者同时满足才为「已安装」；否则为「未安装」。福昕 Office 是单一安装包（含 Word/Excel/PPT 三组件），第 0 层只判"整装是否已装"这一层，不按产品拆分。

⚠️ 字段判据唯一权威（硬性口径）：当 InstallPath 或 InstallAppName 任一为空（如卸载后 注册表残留壳键、但字段被清空）时，立即判「未安装」，禁止回退磁盘目录/文件搜索当「已安装」 证据。仅当两字段都非空时，磁盘上 FuxinOffice exe 文件的存在性才用于二次校验；磁盘残留 （旧安装目录 / SDK 下的 FuxinOffice*.exe）不构成「已安装」依据。

若运行环境无 shell/PowerShell，可退化为让网关暴露一个读注册表的只读端点，但首要按上述 PowerShell 判断。

产品 ID 与应用程序名映射（v2.1 · 关键口径）

两个命名空间必须区分，不可混用：

| 维度 | 取值 | 用途 | |------|------|------| | MCP 产品 ID | Word / Excel / PowerPoint | 网关注册的产品名；工具调用前缀 {产品ID}_get_*；products 列表项 | | 应用进程/前台窗口 | FuxinOfficeWord / FuxinOfficeExcel / FuxinOfficePPT | 应用进程名/窗口名；作为切换窗口（SwitchWindow）目标、切窗提示所用应用名 |

用法口径：

  • 工具调用必须用产品 ID（Word_get_path），绝不能用应用名（FuxinOfficeWord_get_path 不存在）。
  • 应用名（FuxinOffice*）仅用于切换窗口（SwitchWindow）目标 / 切窗提示，不代表 MCP 产品 ID， 不作为预检失败判据（“产品窗口不对”判定已移除）。

判定矩阵（对齐四档状态）

| 状态 | 判定条件 | 用户提示 | |------|----------|----------| | 未安装 | 第 0 层检测到本机未安装福昕 Office | 「Office 未安装」，引导下载/安装 | | 未就绪 | 第 1/2/3 层失败：网关未运行、products 列表为空且福昕Office 应用进程未运行（Office 未启动/插件未加载/连接失败）、产品层连接失败 | 「未运行」「插件未加载」「连接失败」，引导启动 Office / 检查插件 | | 半就绪 | 第 2 层 products 列表为空但福昕Office 应用进程已运行（Office 已启动但未开启任一产品）；或列表非空但缺目标产品；或第 4 层无活动文档 | 「无活动文档」，引导打开文档 | | 就绪 | 第 5 层通过 | 就绪文案，附活动文档清单（路径/只读/页数等），可安全执行写操作 |

⚠️ 重要：get_path 返回空路径不代表无活动文档，须以 GetID() / doc_id / 文档信息为准。 PowerPoint 空演示（0 页）也是活动文档，不应误判为无文档。

⚠️ 第 2 层关键口径：GET /api/skill/products 返回列表非空， 说明 Office / Agent Bridge 已启动并注册了产品。此时仅缺目标产品（如只启动了 PowerPoint， 目标为 Word）≠ "Office 未运行"，不得判「未就绪」，应判「半就绪」并输出「无活动文档」 文案，引导用户在目标产品中新建/打开文档。

⚠️ 列表为空时先判进程（暨本工单修复合规口径）：products 列表为空可能对应两种状态， 不得一律判「未就绪」。应先用 PowerShell Get-Process 探测福昕Office 应用进程：

  • 进程在运行（Office 已启动但未打开任一产品/无活动文档）→ 判「半就绪」，输出「无活动文档」。
  • 进程未运行（Office 未启动/插件未加载/连接失败）→ 判「未就绪」，输出「未运行」。 切勿仅因 products 列表为空就输出「未运行」文案。

使用方式

各编排技能（word/excel/ppt/doc-qa）执行写操作前，按 fuxin-office-bridge 的 5 层决策树 逐层预检，直到遇到失败层即停止并给出指引，全部通过后继续主流程。

⚠️ 第 0 层必先做真实安装判定：不得用 GET /api/skill/products 返回列表或 MCP\products\ 目录存在性当作"是否已安装"。必须先按上文 PowerShell 读注册表 InstallPath / InstallAppName 并校验 exe 存在。注册表/文件校验通过 → 进入第 1 层链路； 校验失败 → 直接判定「未安装」并输出对应文案，不再继续预检。

📊 埋点（调用统计）：预检中通过 MCP tools/call 调用只读工具（{产品}_get_path / _get_document_info / _get_doc_status 等）时，同样在 arguments 顶层携带 skill_id（固定 fuxin-office-bridge）与 scenario_id（如 preflight-word / preflight-excel / preflight-ppt / doc-qa），网关据此关联预检调用计入统计； 有则有、无则无，未传不回显。REST 接口（GET /api/...）不走 MCP call_tool，无埋点字段。

预检通过 → 允许执行写操作
预检失败 → 按下方「用户提示文案（统一出口）」输出，禁止执行写操作

用户提示文案（统一出口，v2.0.0 规范化）

所有技能向用户输出预检/错误/成功提示时，统一遵循以下文案规范，逐字一致使用，含标点， {变量} 按场景替换，严禁擅自发明新文案。

就绪状态六档

预检结果收敛为以下档位，任一档对应的 user_message 如下：

| 状态 | 判定 | 用户提示（user_message） | |------|------|--------------------------| | 未安装 | 本机未安装福昕 Office | 本机未检测到福昕Office。请先安装福昕Office（Word / Excel / PPT），安装完成后启动并打开文档，再告诉我「已就绪」继续。 | | 未就绪 | Office 已启动但未运行 / 插件未加载 / 连接失败 / 无活动文档 | 见下方「未就绪 / 半就绪（明细）」对应行，引导启动/开文档 | | 半就绪 | 有窗口但无活动文档，或只读文档 | 见下方「无活动文档」「只读文档」 | | 就绪 | 目标产品窗口有活动文档，可安全写操作 | 「已就绪」+ 活动文档清单 |

预检阶段的具体失败类别，按「未就绪 / 半就绪（明细）」的「未安装 / 未运行 / 插件未加载 / 连接失败 / 无活动文档 / 只读文档」逐条取用；无法精细分时的统一出口见「错误 / 异常（统一展示）」。

未就绪 / 半就绪（明细）

| 场景 | 展示给用户的文案（定稿 · 逐字一致） | |------|--------------------------| | Office 未安装 | 本机未检测到福昕Office。请先安装福昕Office（Word / Excel / PPT），安装完成后启动并打开文档，再告诉我「已就绪」继续。 | | 未运行 | 福昕Office 未运行。请先启动福昕Office，并打开 Word、Excel 或 PPT 中的任意文档，然后告诉我「已启动」，我再继续操作。 | | 插件未加载 | Agent Bridge 插件未加载。请确认已安装福昕Office Agent Toolkit，并在福昕Office 中启用该插件后重试。 | | 连接失败 | 无法连接到 Agent Bridge（本地服务无响应）。请确认福昕Office 正在运行且未被安全软件拦截，然后重试。 | | 无活动文档 | 福昕Office 已启动，但当前没有打开的活动文档。请在 {Word/Excel/PPT} 中新建或打开一个文档后重试。 | | 只读文档 | 当前文档为只读，无法修改。请将文档另存为可编辑副本，或关闭只读保护后重试。 |

已就绪 / 成功

| 场景 | 展示给用户的文案（定稿 · 逐字一致） | |------|--------------------------| | 已就绪 | 福昕Office 已就绪，当前活动文档：{Word/Excel/PPT}。可以开始执行文档操作。 | | 单次操作成功 | 已在文档中完成「{操作名}」。请在福昕Office 中查看效果。（仅用于单次操作完成后，不用于整个场景收尾） | | 一组操作完成 | 本组修改已完成。如需撤销，请在福昕Office 中按一次「撤销」即可恢复整组操作。（用于一组/一批操作完成后，作为批量撤销引导） | | 写后撤销提示 | 改好了。要撤回改动：回复「撤销」，或在福昕Office 按 Ctrl+Z。 | | 保存确认提示 | Agent 请求保存当前文档「{文档名}」。是否允许保存？保存 / 取消 | | 保存确认通过 | 已获你确认，正在保存文档「{文档名}」… | | 保存确认取消 | 已取消保存，文档未发生改变。 | | 场景任务完成 | 「{场景名}」已执行完毕。请检查文档是否符合预期。（用于整个场景收尾） |

三档区分：

  • 单次操作成功：一次单步操作（如单次查找替换、单次高亮）完成时输出「单次操作成功」。
  • 一组操作完成：同一场景内的多步/批量操作合并为组完成后，输出「一组操作完成」+「写后撤销提示」，作为该组收尾。
  • 场景任务完成：整个场景（write_report / unify_terminology / highlight_and_comment 等）完全执行完毕后，才输出「场景任务完成」。 三者不可互相替代：单次/一组完成不得直接套用场景完成文案，反之场景完成也不回退为单次/一组文案。

写操作场景：成功输出后，追加固定写后撤销提示「写后撤销提示」（逐字一致）。 支持 Elicitation 的客户端仍可能有系统二次确认，用户按系统提示确认即可（Skill 不再写前二次确认）。

保存操作例外（必须预确认）：save_document / save_document_as 属不可逆保存操作（无撤销、可能覆盖文件）。 调用前必须先弹窗确认，使用「保存确认提示」并等待用户选择；用户同意才调用保存工具，用户取消则不执行 并输出「保存确认取消」。此例外仅限保存类工具，其余写操作仍按「不写前二次确认」。取消/超时文案见「错误 / 异常（统一展示）」的「用户取消确认」「确认超时」。

错误 / 异常（统一展示）

工艺说明（面向 Agent，不进用户文案）：跨产品写前闸门（确认目标产品窗口）的话术不在此表重复维护，由 fuxin-office「五·一、跨产品写前闸门」统一出口；本表仅收录用户可见的错误/异常/提示定稿句。

| 场景 | 展示给用户的文案（定稿 · 逐字一致） | |------|--------------------------| | Office 未安装（汇总） | 本机未检测到福昕Office。请先安装福昕Office（Word / Excel / PPT），安装完成后启动并打开文档，再告诉我「已就绪」继续。 | | Office 未运行（汇总） | 福昕Office 未运行。请先启动福昕Office，并打开 Word、Excel 或 PPT 中的任意文档，然后告诉我「已启动」，我再继续操作。 | | 无文档窗口 | 请先打开一个 {Word/Excel/PPT} 文档窗口。当前没有可编辑的活动文档，我无法继续操作。 | | 产品不匹配 | 当前打开的是 {当前产品}，本次需要 {目标产品}。请切换到正确的产品窗口后再试。 |

| 参数有误 | 工具参数有误，本次操作未执行。请检查是否缺少必填项（如 Sheet 名、列名、单元格区域等）后重试。 | | 连接超时 | 连接 Agent Bridge 超时，操作未完成。请确认福昕Office 未卡死，关闭后重新打开再试。 | | 批量操作未结束 | 上一批批量操作未正常结束，请先结束当前批次或重启福昕Office 后再试。 | | 用户取消确认 | 您已取消本次保存/修改确认，相关操作未执行。文档保持变更前状态。 | | 工具未注册/未加载 | 工具未注册或未加载（网关返回 method not found / tool not found）。请确认 FuxinAiService 已正常启动、MCP 网关已重新注册全部工具，且福昕Office 相关插件已加载后重试；若仍无法解决，请重启 FuxinAiService 再试。 | | 工具未注册/未加载（统一出口） | 工具未注册或未加载（如返回 method not found / tool not found）。请重启 FuxinAiService，并确认福昕Office 插件已加载后重试。 | | 确认超时 | 操作确认超时，为安全起见未执行保存。如需保存，请重新发起并尽快确认。 | | 无法连接文档 | 无法连接到福昕Office 文档。请确认 {Word/Excel/PPT} 已打开且有活动文档，然后重试。 | | 操作超时 | 文档操作超时，可能因文档过大或 Office 繁忙。请稍后重试，或拆分为更小的步骤。 | | 替换未找到 | 「替换文本」未找到匹配内容，或替换次数与预期不符。请确认要查找的文本是否存在，或改用逐次查找替换。 | | 操作未完成 | 操作未能完成。文档当前状态可能已部分更改，请检查文档并按需撤销。 |

错误响应必须包含中文 user_message，禁止编造「已成功/已完成」。 文档正文不得出现在面向用户的错误展示中。 同一错误在不区分明细时取「错误 / 异常（统一展示）」条目；区分时取「未就绪 / 半就绪（明细）」明细。

参数类错误归一化（必做）：当工具返回 ok:false 且错误属于参数缺失/非法/空值类（如 sections不能为空、title不能为空、缺 Sheet 名/列名/单元格区域、空数组等）时，Agent 禁止把工具原始 error 字段原样回显给用户，必须归一化为定稿文案：

工具参数有误，本次操作未执行。请检查是否缺少必填项（如 Sheet 名、列名、单元格区域等）后重试。

判断口径：仅当错误可判定为参数问题才落此出口；其他错误（连接超时、操作未完成、替换未找到等）按「错误 / 异常（统一展示）」对应条目提示，不套用本文案。

⚠️ 工具层行为正确（拦截、ok=false、零写入），缺的是 Skill/Agent 文案层，修复落在本提示出口而非网关场景工具。

与其它技能协同

  • 消费方：fuxin-word / fuxin-excel / fuxin-ppt / fuxin-doc-qa / fuxin-batch-undo
  • 编排人：fuxin-office 汇总层在 E2E 分步前先跑预检，再路由到具体产品技能
  • 文案规范：见上文提示表，统一在本技能维护