# DOCX / XLSX 工件直接预览

日期：2026-08-14

# 目标

让 Agent 在工作区生成的 Word、Excel 文件可以在“工件”抽屉中直接查看，而不是只能下载。聊天主链路和工件文件下载接口保持不变。

# 实现

• 后端将 .docx、.xlsx 识别为可预览工件，并补齐 Office MIME 类型；bash 的自动工件识别也涵盖这两种后缀。
• 前端仅在用户选中 Office 工件时动态加载解析库：DOCX 使用 docx-preview 渲染为 HTML，XLSX 使用 SheetJS（xlsx）读取工作表和单元格。
• XLSX 提供工作表切换，表格最多展示前 500 行；单元格以纯文本插入 React 节点，不执行文件内脚本。
• Office 文件不会再走原本的 response.text() 文本预览分支，避免二进制被错误显示或产生重复请求。
• 解析失败、超过后端 1 MB 预览上限，或复杂内容无法忠实呈现时，抽屉保留“下载”入口，不影响对话。

# 预览边界

• DOCX 适合阅读常见正文、表格和基础图片排版；复杂分页、批注、嵌入对象及 Office 专有特性不保证像 Word 一样完全一致。
• XLSX 用于快速查看数据：不执行宏、不重算公式，也不渲染图表、透视表、条件格式等高保真效果。
• 生产环境迁移 OSS 时，只需将工件内容 URL 改为授权下载 URL；前端解析和稳定 artifactId 关联方式不变。

# 验证

• mvn -pl pi-agent-v1 test：通过（当前模块没有测试源码）。
• web/ 下 npm run build：TypeScript 检查与 Vite 生产构建通过。
• 构建产物确认 docx-preview 与 xlsx 为独立懒加载 chunk，普通聊天首屏不会加载这两个解析器。