跳转至

Outlook Add-in 单证识别

outlook-addin/ 现在是 Outlook 里的轻量入口，不再承担结果审阅工作区。它读取当前邮件附件或本地文件，允许用户从 document-recognition runtime registry 里选择 runtime agent，提交后只创建 canonical document-recognition run，然后把用户带到 outlook-index 继续处理。

架构关系

本地开发链路如下：

flowchart LR
  Outlook[Outlook / OWA] --> Addin[outlook-addin Vite<br/>https://localhost:3100]
  Addin -->|/api proxy| DemoBackend[demo-backend<br/>http://localhost:3000]
  DemoBackend --> AIService[ai-service]

关键点：

  • outlook-addin 不直接请求 ai-service。
  • 前端统一调用同源 /api/*，由 Vite 代理转发给 demo-backend。
  • 提交时走 canonical /api/document-recognition/runs，不再使用 owner-agent extraction-job 路径。
  • 创建成功后只负责 handoff，不再渲染字段摘要、review 控件或历史列表。

启动方式

先启动 demo backend，再启动 add-in dev server：

just run-demo-backend
cd outlook-addin
npm install
npm run dev

默认端口：

  • demo-backend: http://localhost:3000
  • outlook-addin: https://localhost:3100

之所以将 add-in 改到 3100，是为了避免与 demo-backend 的本地默认端口冲突。

环境变量

在 outlook-addin/.env 中可设置：

VITE_DEFAULT_AGENT_ID=your-fusion-runtime-agent-id
DEMO_BACKEND_URL=http://localhost:3000
VITE_ADDIN_HOST_URL=https://localhost:3100
VITE_OUTLOOK_INDEX_URL=http://localhost:5173

说明：

  • VITE_DEFAULT_AGENT_ID：可选，用于默认选中某个 Fusion runtime agent。
  • DEMO_BACKEND_URL：Vite 开发代理的目标地址。
  • VITE_ADDIN_HOST_URL：本地 add-in 宿主地址，会同时影响 Vite dev server 端口与生成后的 manifest.xml。
  • VITE_OUTLOOK_INDEX_URL：任务完成后跳转的详细工作区地址。

Manifest 与 Office API 约束

为了从 Outlook 当前邮件读取附件内容，manifest 需要至少声明 Mailbox 1.8。 为了让 Outlook Web 任务窗格显示固定图钉，manifest 还需要在 VersionOverridesV1_1 的 ShowTaskpane action 下声明 SupportsPinning=true。固定任务窗格只适用于 Microsoft 365 的新式 Outlook Web；个人版 Outlook.com 不支持该能力。

这一点对应到前端实现时，依赖两个 Office 附件 API：

  • item.getAttachmentsAsync()：获取当前项的附件列表
  • item.getAttachmentContentAsync()：获取附件内容并转成浏览器可提交的 File
  • Office.EventType.ItemChanged：任务窗格固定后，切换邮件时通知前端重新读取当前邮件

如果只在普通浏览器里打开 https://localhost:3100，Office 宿主上下文不存在，此时：

  • 无法读取真实 Outlook 附件
  • 但仍然可以通过本地文件上传测试运行选择、提交和 handoff UI

前端职责

outlook-addin 的识别模式主要包含四块：

  1. Fusion runtime agent 选择
  2. 当前邮件附件选择与 staging
  3. 可选的启动自动上传开关，用于在加载到当前邮件附件时自动创建 run
  4. 通过 document-recognition 创建 canonical run
  5. 只读 handoff 状态与跳转到详细工作区

与 demo-frontend 相比，差异点主要在输入源：

  • demo-frontend：本地文件上传为主
  • outlook-addin：当前邮件附件为主，本地上传为回退路径

在 outlook-addin 里，runtime 面板提供一个 Startup auto upload 开关。启用后，add-in 在启动并成功加载到当前邮件中的首个支持附件时，会自动触发上传提取；关闭后仍保留原来的手动 Upload and extract 路径。这个设置通过浏览器本地存储持久化。

在 Outlook Web 中处理多封邮件时，先打开 Recognize Docs，再用 Outlook 任务窗格标题栏上的图钉固定面板。固定后，切换到其他邮件会触发 ItemChanged，add-in 会重新加载当前邮件附件，并按 Startup auto upload 设置决定是否自动上传。收到新邮件但没有打开或固定任务窗格时，前端 add-in 不会在后台自动运行。

如果任务窗格没有自动列出当前邮件附件，可以点击附件列表底部的 Read Outlook attachments。该按钮会重新调用 Outlook 附件 API，并显示 Outlook 返回的原始附件数量、支持的 PDF/图片附件数量，以及被过滤掉的 unsupported/inline 附件数量。

发布与下载

生产发布后的公开入口分成三类：

  • Add-in 宿主页：https://outlook.aibot.zata.cafe
  • 宿主 manifest：https://outlook.aibot.zata.cafe/manifest.xml
  • 下载页：见 Outlook Add-in 下载

当前 .exe 交付的是 Windows 安装助手，而不是组织级分发包。它会把当前生产 manifest 下载到本地，并打开下载说明页，便于继续 sideload。

当前后端接口

旧 POST/GET /api/agents/{agent_id}/extraction-jobs* 路径已经移除，本指南保留该流转仅作为历史背景。当前 Outlook add-in 相关的单证识别查询面应改为：

  • GET /document-recognition/runtime-agents
  • GET /document-recognition/runs
  • GET /document-recognition/runs/{run_id}
  • PATCH /document-recognition/runs/{run_id}/field-reviews/{field_id}
  • GET /document-recognition/runs/{run_id}/field-reviews/{field_id}/revisions

其中可被 Outlook 入口选择的 Fusion agent 不再由前端自行推断，而是由管理端显式维护：

  • PUT /admin/document-recognition/runtime-agents/{agent_id}
  • DELETE /admin/document-recognition/runtime-agents/{agent_id}

这样做的好处是：

  • 不再把通用 Fusion history 混进 document-recognition 查询面
  • Outlook 入口和 Studio/Admin 共用同一套 canonical run/read/review surface
  • 可选 Fusion runtime 的名字、描述和启用状态可以通过 registry 明确暴露