跳转至

Outlook Add-in 单证识别

outlook-addin/ 现在不再只是邮件摘要 demo，而是一个嵌入 Outlook task pane 的单证识别前端。它通过 document-recognition extraction-job 接口创建识别任务，同时继续允许底层绑定到某个 Fusion runtime agent。

架构关系

本地开发链路如下：

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。
  • 这样可以和 demo-frontend 保持同一套 extraction-job 路由与 payload。

启动方式

先启动 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
VITE_DOCUMENT_RECOGNITION_AGENT_ID=your-document-recognition-owner-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。
  • VITE_DOCUMENT_RECOGNITION_AGENT_ID：必填，表示 extraction-job 的 owner 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。

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

  • item.getAttachmentsAsync()：获取当前项的附件列表
  • item.getAttachmentContentAsync()：获取附件内容并转成浏览器可提交的 File

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

  • 无法读取真实 Outlook 附件
  • 但仍然可以通过本地文件上传测试识别 UI 与 extraction-job 流程

前端职责

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

  1. Fusion runtime agent 选择
  2. 当前邮件附件选择与 staging
  3. 通过 document-recognition 创建 extraction job
  4. 只读字段摘要与跳转到详细工作区

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

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

发布与下载

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

  • 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 明确暴露