状态:规划稿,暂停实施
日期:2026-11-06
目标系统:zsjz-ai(Spring Boot + Vue 3/Electron 案件分析系统)
参考项目:E:\workspace\webstom\ZCode
ZCode 的“办公模式(office mode)”本身只是前端界面偏好(office / coding,存 localStorage),不会改变 Agent 工具注册、系统提示词或后端能力。真正的办公能力来自:
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:
execute_python;本方案只做一个轻量 MVP:用现有 Spring Boot + POI/PDFBox/Tika + ArtifactService 提供可配置的办公文档工具,不新增 Node/MCP 运行时。
office 业务工具组,共 6 个工具:
list_documentsread_documentsearch_documentcreate_docxcreate_xlsxcreate_pdfpage:Np:N、表格锚点 table:NSheet!A1:B10line:NArtifactService,不覆盖原件。office-runtime MCP、LibreOffice、Playwright;用户要求:工具在页面上自己配置,不默认启用。
AgentToolRegistry 目前只有一份 registeredGroupNames(),同时承担“默认注册全部组”和“页面可选的组清单”。需要拆成两份语义:
registeredGroupNames() / allGroupNames():页面配置、工具目录、工具包校验可见的全部组(含 office);defaultRegisteredGroupNames():现有 7 个组(person/call/trans/track/graph/file/eds),不含 office。registerBusinessTools(...) 在 enabledGroups 为空时使用 defaultRegisteredGroupNames(),而不是全部组。office 只有在以下情况才注册:
tools_allow_json 显式包含 "office";这样默认数据分析 Agent:
reset_equipped_tools 不出现 office 组;工具目录页仍能看到 office 工具和“办公文档”组,因为目录同步/能力清单使用全部组;但它们只参与页面配置,不参与默认对话装配。
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 资源懒加载,应用启动不检查字体。XWPFDocument / XSSFWorkbook)。
ai-server/pom.xml 显式声明 poi-ooxml,版本与 Fesod 传递版本对齐,避免依赖漂移。PdfFontResolver 依次尝试:
zsjz.office.pdf-font-pathqingjian/system/fonts/msyh.ttc / simhei.ttf,Linux Noto Sans CJK / 文泉驿AutoDetectParser + ToHTMLContentHandler,限制输出字符数;前端沙箱 iframe 渲染。实现位置: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 | artifactanchor: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?)hits: [{ anchor, snippet }]。create_docx(fileName?, title, subtitle?, author?, sections[])heading/paragraphs/bullets/table;create_xlsx(fileName?, sheets[], fromArtifacts?)name/columns/rows/columnWidths/freezeHeader;fromArtifacts 支持把 CSV artifact 全量写入 sheet;create_pdf(fileName?, title, subtitle?, author?, sections[])生成路径:
案件临时目录写入临时文件
-> ArtifactService.registerFile(temp, displayName)
-> 删除临时文件
-> 工具结果返回 artifact 元数据
前端现有 extractMessageArtifacts 会自动识别 artifact 字段。
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 表,页面“插件与技能”可见并可配置。userId/caseId/sessionId 归属,优先读 sidecar_path;PDF 用 PDFBox 逐页读取。file_info → WorkspacePathGuard 校验后读取;未保留原件的文件返回可读错误,提示用 @ 引用上传。ArtifactService.resolve(id) 读取,支持生成后回读。ChatAttachmentService.listSessionAttachments(...) 供 list_documents 使用;ChatAttachmentService.buildBlock 的附件提示词,避免影响现有数据分析模式。sql/office_expert.sql;row_id=1 的工具包绑定;office;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 列);ai/utils/artifacts.ts 已能识别 word/excel,无需改类型。ai-server/src/main/java/com/zsjz/ai/module/office/*ai-server/src/main/java/com/zsjz/ai/module/agent/tools/OfficeDocumentTool.javaai-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.javaai-server/src/main/java/com/zsjz/ai/module/agent/tools/ToolResultLimits.javaai-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.javaai-server/src/main/java/com/zsjz/ai/module/agent/controller/AgentArtifactController.javaai-server/pom.xml(显式 POI 依赖)ai-server/src/main/resources/application.yaml(zsjz.office.*)ai-electron/frontend/src/ai/utils/constants.tsai-electron/frontend/src/ai/api/artifactApi.tsai-electron/frontend/src/ai/components/ArtifactPreviewModal.vueOfficeDocumentWriterTest:
OfficeDocumentServiceTest:
OfficeDocumentToolTest:
AgentToolRegistryTest 断言默认注册仍为 67 个业务工具且不含 office;AgentCapabilityToolkitTest:
ToolDescriptionContractTest:
运行:
mvn -pl ai-server -o test \
-Dtest='Office*Test,AgentToolRegistryTest,AgentCapabilityToolkitTest,ToolDescriptionContractTest,ToolResultLimitsTest'
cd ai-electron/frontend
pnpm type:check
手动验证 docx/xlsx 预览。
@ 引用 PDF/DOCX,要求总结并生成 docx 报告;ZSJZ_OFFICE_PDF_FONT_PATH 后重试;create_xlsx fromArtifacts 能把大 CSV 全量写入;docx-preview 或服务端 LibreOffice。