office-mode-mvp.md 13 KB

办公模式 MVP 方案(页面配置、无默认暴露)

状态:规划稿,暂停实施
日期:2026-11-06
目标系统:zsjz-ai(Spring Boot + Vue 3/Electron 案件分析系统)
参考项目:E:\workspace\webstom\ZCode

1. 背景

ZCode 的“办公模式(office mode)”本身只是前端界面偏好(office / coding,存 localStorage),不会改变 Agent 工具注册、系统提示词或后端能力。真正的办公能力来自:

  • 4 个内置文档插件:documents(docx)、spreadsheets(xlsx)、presentations(pptx)、pdf;
  • 生成层:各插件的 SKILL.md + Python/Node 脚本(openpyxl、python-docx、pptxgenjs、ReportLab、LibreOffice 等);
  • 查看层:office-runtime 只读 MCP Server,提供 open_document/read_document/search_document/show_in_viewer/get_view,支持页/段/单元格锚点;
  • 质量层:visual-judge 把页面渲染成 PNG 后做视觉验收。

其代价是 4 个 Node MCP Server、LibreOffice、Poppler、Playwright、Tectonic 等重运行时,不适合直接搬进我们的 Spring Boot + Electron 架构。

我们当前的 Agent 是数据分析型 Agent:

  • 7 个基础设施工具;
  • 67 个业务工具(人员/通话/交易/轨迹/图谱/材料/电子数据包),全部只读案件数据;
  • 文档生成只能靠模型写 execute_python;
  • docx/xlsx/pptx 产物只能下载,不能在线预览;
  • 没有办公工具组、办公专家、文档锚点与文档生成契约。

本方案只做一个轻量 MVP:用现有 Spring Boot + POI/PDFBox/Tika + ArtifactService 提供可配置的办公文档工具,不新增 Node/MCP 运行时。

2. 范围

做

  • 新增 office 业务工具组,共 6 个工具:
    • list_documents
    • read_document
    • search_document
    • create_docx
    • create_xlsx
    • create_pdf
  • 文档读取/搜索:
    • PDF:页锚点 page:N
    • DOCX:段落锚点 p:N、表格锚点 table:N
    • XLSX:单元格区域锚点 Sheet!A1:B10
    • TXT/MD:行锚点 line:N
  • docx/xlsx/pdf 结构化生成:
    • 标题、副标题、作者、章节、段落、列表、表格;
    • xlsx 支持多 sheet、列宽、表头样式、冻结表头;
    • xlsx 支持从 CSV 产物导入全量数据,避免把大表行数据塞进模型上下文。
  • 产物统一走现有 ArtifactService,不覆盖原件。
  • 前端 docx/xlsx 在线预览;PDF 沿用现有 iframe 预览。

不做(后续阶段)

  • 默认注册/默认激活 office 组;
  • 预置办公专家、默认绑定工具包;
  • PPTX 生成/预览;
  • docx/pptx 模板引擎、复杂排版、页眉页脚/目录/盖章位;
  • 页面渲染 + visual-judge 视觉质检;
  • 多轮原地编辑同一份文档(MVP 只做读取/搜索/新建产物);
  • office-runtime MCP、LibreOffice、Playwright;
  • 让模型在用户机器上安装 Python/Node 依赖。

3. 关键隔离设计

用户要求:工具在页面上自己配置,不默认启用。

AgentToolRegistry 目前只有一份 registeredGroupNames(),同时承担“默认注册全部组”和“页面可选的组清单”。需要拆成两份语义:

  • registeredGroupNames() / allGroupNames():页面配置、工具目录、工具包校验可见的全部组(含 office);
  • 新增 defaultRegisteredGroupNames():现有 7 个组(person/call/trans/track/graph/file/eds),不含 office。

registerBusinessTools(...) 在 enabledGroups 为空时使用 defaultRegisteredGroupNames(),而不是全部组。office 只有在以下情况才注册:

  • 专家配置 tools_allow_json 显式包含 "office";
  • 或工具包白名单包含任一 office 工具。

这样默认数据分析 Agent:

  • 仍然只注册 7 个基础工具 + 67 个业务工具;
  • reset_equipped_tools 不出现 office 组;
  • 提示词、附件块、工具 schema 全部不变。

工具目录页仍能看到 office 工具和“办公文档”组,因为目录同步/能力清单使用全部组;但它们只参与页面配置,不参与默认对话装配。

4. 后端设计

4.1 新增 module/office

路径:ai-server/src/main/java/com/zsjz/ai/module/office/

  • OfficeDocumentService:来源解析、读取、搜索,输出带锚点的块。
  • OfficeDocumentWriter:docx/xlsx/pdf 生成,共用 OfficeDocumentSpec / WorkbookSpec。
  • OfficeDocumentPreview:DOCX → HTML(Tika),供前端预览。
  • OfficeProperties / PdfFontResolver:读取上限、行列上限、PDF 字体路径;所有字体/POI 资源懒加载,应用启动不检查字体。
  • DTO 用 record/嵌套静态类,保持工具 schema 简洁。

4.2 技术选型

  • DOCX/XLSX:Apache POI(XWPFDocument / XSSFWorkbook)。
    • POI 目前由 Fesod 传递引入;
    • 在 ai-server/pom.xml 显式声明 poi-ooxml,版本与 Fesod 传递版本对齐,避免依赖漂移。
  • PDF:PDFBox 3.0.7(已有)。A4 流式排版;PdfFontResolver 依次尝试:
    1. 配置 zsjz.office.pdf-font-path
    2. qingjian/system/fonts/
    3. Windows msyh.ttc / simhei.ttf,Linux Noto Sans CJK / 文泉驿
    4. 找不到中文字体且内容含中文时返回可读错误,不静默输出乱码。
  • 预览:Tika AutoDetectParser + ToHTMLContentHandler,限制输出字符数;前端沙箱 iframe 渲染。

4.3 六个工具

实现位置:ai-server/src/main/java/com/zsjz/ai/module/agent/tools/OfficeDocumentTool.java

list_documents(keyword?, limit?)

列出当前会话附件 + 当前案件可引用文件,返回:

{
  "documents": [
    {
      "sourceType": "attachment|file",
      "sourceId": "...",
      "name": "...",
      "kind": "DOCUMENT|TABLE|IMAGE|...",
      "sizeBytes": 123
    }
  ]
}

read_document(sourceType, sourceId, anchor?, maxChars?)

  • sourceType:attachment | file | artifact
  • anchor:page:3-5、p:12、Sheet!A1:B10、line:10-20
  • 返回:

    {
    "source": "...",
    "kind": "pdf|docx|xlsx|text",
    "blocks": [
    { "anchor": "page:3", "text": "..." }
    ],
    "truncated": false
    }
    

search_document(sourceType, sourceId, keyword, limit?, contextChars?)

  • 大小写不敏感;
  • 最多 20 条;
  • 返回 hits: [{ anchor, snippet }]。

create_docx(fileName?, title, subtitle?, author?, sections[])

  • section 含 heading/paragraphs/bullets/table;
  • 生成后登记为 artifact。

create_xlsx(fileName?, sheets[], fromArtifacts?)

  • sheet 含 name/columns/rows/columnWidths/freezeHeader;
  • fromArtifacts 支持把 CSV artifact 全量写入 sheet;
  • 限制 sheet 数、行数、列数,避免内存爆炸。

create_pdf(fileName?, title, subtitle?, author?, sections[])

  • 与 docx 共用文档 spec;
  • 生成后登记为 artifact。

生成路径:

案件临时目录写入临时文件
  -> ArtifactService.registerFile(temp, displayName)
  -> 删除临时文件
  -> 工具结果返回 artifact 元数据

前端现有 extractMessageArtifacts 会自动识别 artifact 字段。

4.4 工具组、目录与元数据

  • AgentToolRegistry:
    • 新增 GROUP_OFFICE = "office"、OFFICE_TOOLS 六个工具名;
    • groupLabel 增加“办公文档”;
    • groupToolNames、全部组清单增加 office;
    • 新增 defaultRegisteredGroupNames();registerBusinessTools 默认只用它;
    • 只有 enabled.contains(GROUP_OFFICE) 时才构造/注册 OfficeDocumentTool。
  • ToolMetadataRegistry.POLICIES:
    • 读/搜:只读、低风险;
    • 生成:destructive=false、risk=medium、超时 60s,不审批拦截。
  • ToolResultLimits:office 读/搜结果上限建议 80k;生成结果很小。
  • ToolCatalogInitializer 会自动把 office 工具同步进 agent_tool 表,页面“插件与技能”可见并可配置。

4.5 文档来源与配置

  • 附件:校验 userId/caseId/sessionId 归属,优先读 sidecar_path;PDF 用 PDFBox 逐页读取。
  • 案件文件:file_info → WorkspacePathGuard 校验后读取;未保留原件的文件返回可读错误,提示用 @ 引用上传。
  • 生成物:ArtifactService.resolve(id) 读取,支持生成后回读。
  • 新增 ChatAttachmentService.listSessionAttachments(...) 供 list_documents 使用;
  • 不修改 ChatAttachmentService.buildBlock 的附件提示词,避免影响现有数据分析模式。

4.6 页面配置,不预置默认

  • 不新增 sql/office_expert.sql;
  • 不修改默认专家 row_id=1 的工具包绑定;
  • 用户可在“研判方案”页新建/编辑专家:
    • 旧工具组配置:勾选 office;
    • 工具包配置:新建工具包并选择六个 office 工具。
  • 工具目录同步后即可在“插件与技能 → 工具”看到这些工具;是否启用完全由页面配置决定。

5. 前端改动

  • ai/utils/constants.ts:
    • TOOL_LABELS 增加六个工具;
    • TOOL_GROUP_LABELS 增加 office。
  • ai/api/artifactApi.ts:新增 fetchArtifactPreviewHtml(id)。
  • ai/components/ArtifactPreviewModal.vue:
    • kind === 'word':加载后端 HTML 后用 <iframe sandbox=""> 渲染(禁止脚本);
    • kind === 'excel':用已依赖的 xlsx@0.18.5 读取 blob,首个 sheet 渲染为 Table(MVP 限制 200 行/50 列);
    • 现有 CSV/PDF/图片/文本分支不变;PPTX 仍提示下载,失败回退下载。
  • ai/utils/artifacts.ts 已能识别 word/excel,无需改类型。
  • 不新增独立 workbench 视图、不预置办公模式开关;通过专家/工具包配置进入。

6. 关键文件清单

新增

  • ai-server/src/main/java/com/zsjz/ai/module/office/*
  • ai-server/src/main/java/com/zsjz/ai/module/agent/tools/OfficeDocumentTool.java

修改

  • ai-server/src/main/java/com/zsjz/ai/module/agent/tools/AgentToolRegistry.java(全部组 vs 默认注册组拆分)
  • ai-server/src/main/java/com/zsjz/ai/module/agent/tools/ToolMetadataRegistry.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/tools/ToolResultLimits.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/attachment/ChatAttachmentService.java(仅新增 listSessionAttachments,不改现有 block)
  • ai-server/src/main/java/com/zsjz/ai/module/agent/artifact/ArtifactService.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentArtifactController.java
  • ai-server/pom.xml(显式 POI 依赖)
  • ai-server/src/main/resources/application.yaml(zsjz.office.*)
  • ai-electron/frontend/src/ai/utils/constants.ts
  • ai-electron/frontend/src/ai/api/artifactApi.ts
  • ai-electron/frontend/src/ai/components/ArtifactPreviewModal.vue

7. 验证方案

7.1 后端单测

  • OfficeDocumentWriterTest:
    • 生成 docx/xlsx/pdf;
    • 用 POI/PDFBox 回读校验标题、段落、表格、sheet 数据。
  • OfficeDocumentServiceTest:
    • PDF/DOCX/XLSX/TXT 的读取、锚点、搜索命中。
  • OfficeDocumentToolTest:
    • 工具 JSON 含 artifact;
    • 错误分支可读。
  • 默认隔离测试:
    • AgentToolRegistryTest 断言默认注册仍为 67 个业务工具且不含 office;
    • 显式勾选 office 后为 73 个。
  • AgentCapabilityToolkitTest:
    • 能力目录能看到 office(73);
    • 默认 Agent 看不到。
  • ToolDescriptionContractTest:
    • 描述总预算按全部工具扫描调整(当前 6000,建议提到 8000);
    • 注释说明“目录工具并非全部默认可见”。

运行:

mvn -pl ai-server -o test \
  -Dtest='Office*Test,AgentToolRegistryTest,AgentCapabilityToolkitTest,ToolDescriptionContractTest,ToolResultLimitsTest'

7.2 前端

cd ai-electron/frontend
pnpm type:check

手动验证 docx/xlsx 预览。

7.3 手工 E2E(后端 + Vite,不启动 Electron)

  1. 重启后端;
  2. 打开“插件与技能/研判方案”,确认 office 工具可见;
  3. 新建专家,勾选 office 工具组/工具包;
  4. @ 引用 PDF/DOCX,要求总结并生成 docx 报告;
  5. 要求把查询结果生成 xlsx,验证产物栏、预览、下载;
  6. 生成中文 PDF,验证字体;若无字体,配置 ZSJZ_OFFICE_PDF_FONT_PATH 后重试;
  7. 验证 create_xlsx fromArtifacts 能把大 CSV 全量写入;
  8. 用默认数据分析专家对话,确认工具列表/提示词/行为与改动前一致。

8. 风险与默认

  • PDF 中文字体是 MVP 最大环境风险:
    • 默认走系统字体;
    • 失败时给出明确配置项,不静默输出乱码。
  • Tika HTML 预览会丢失复杂 Word 版式和部分图片:
    • MVP 先保证文本/表格可读;
    • 后续可换 docx-preview 或服务端 LibreOffice。
  • POI 版本需与 Fesod 传递版本对齐,避免 OOXML 解析冲突。
  • office 服务/字体/POI 必须懒加载,任何初始化失败都不能影响应用启动或数据分析链路。

9. 后续阶段(不在本次 MVP)

  • PPTX 生成与预览;
  • docx/xlsx 模板库与占位符渲染;
  • docx/xlsx/pptx → PDF 统一转换;
  • 页面渲染 + visual-judge 视觉质检;
  • 多轮文档编辑、版本对比、批注/复核;
  • 办公文档中心(文档列表、目录、重命名、批量下载)。