Astrbot Office 助手

• 部分效果
• 快速了解
• 快速开始
• 配置说明
• 工具与命令
• Word 工作流
• 支持的文件格式
• 系统依赖安装
• Docker 部署
• 常见问题
• 后续规划
• 交流

• 群聊默认不启用（enable_features_in_group=false），启用后需要 @ 机器人才暴露工具。
• 指令支持中英文别名，比如 /pdf_status 和 /pdf状态。
• 群聊里先上传文件、后面再处理，用 /doc 系列命令更顺手。
• 插件生效时会自动隐藏 astrbot_execute_shell 等执行类工具。
• 默认只能访问工作区内路径，可配置放开。
• 复杂 Word 走四步链：create_document → add_blocks → finalize_document → export_document，支持封面、正文、列表、表格、图片、目录等。

通过 AstrBot 插件管理器安装，Python 依赖会自动装好。

Word 导出走 JS 渲染器，机器上需要 Node.js（建议 18+），先确认 node -v 能跑。

第一次部署或拉了新代码后，在插件目录里构建一次：

cd word_renderer_js
npm install
npm run build

构建完会生成 word_renderer_js/dist/cli.js，没这个文件 Word 工具链没法导出。

• /fileinfo：看插件运行状态和配置
• /pdf_status（或 /pdf状态）：看 PDF 转换是否可用

• 发个 .txt 或 .md 给机器人，让它读取并总结
• 让机器人生成一个 .xlsx
• 装了转换依赖的话，试一次 Office → PDF

在 AstrBot 管理面板中设置。常用的几项：

主要给群聊用。先上传文件，再决定拿哪几个往下处理。

/doc list
/doc clear
/doc clear f1
/doc use f1 根据这份文件整理成正式汇报
/doc use f1 f2 根据这些文件整理成正式汇报

会话里只有一个文件时可以省略文件 ID：

/doc use 根据这份文件整理成正式汇报

文件按"平台 + 会话 + 用户"隔离，群里其他人的文件不会混进来。

先建草稿，一块一块填内容，最后锁定导出。适合周报月报、管理层汇报、简历、带表格和图的报告这些东西。

1. create_document：建草稿，定主题、表格模板、密度、强调色
2. add_blocks：往里加内容，可以多次调用
3. finalize_document：锁定，之后不能再追加
4. export_document：导出 .docx，自动发文件和预览图

┌───────────────────────────┐
│     create_document       │
│                           │
│  theme_name               │
│  table_template           │
│  density                  │
│  accent_color             │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│       add_blocks          │◄──┐
│                           │   │
│  page_template hero_banner│   │
│  heading      paragraph   │   │
│  list         table image │   │ 可多次调用
│  summary_card accent_box  │   │
│  metric_cards page_break  │   │
│  section_break toc        │   │
│  group       columns      │   │
└─────────────┬─────────────┘   │
              │ 内容完成        │
              │─────────────────┘
              ▼
┌───────────────────────────┐
│   finalize_document       │
│       锁定草稿            │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│    export_document        │
│  导出 .docx + 自动发送    │
└───────────────────────────┘

• 主题：business_report、project_review、executive_brief
• 表格样式：report_grid、metrics_compact、minimal
• 排版密度：comfortable（宽松）或 compact（紧凑）
• 强调色：accent_color=RRGGBB
• 卡片变体：summary 或 conclusion
• 页面模板：business_review_cover（经营复盘封面）、technical_resume（技术简历）
• 段落和表格支持富文本（粗体、斜体、下划线、颜色、字体、超链接等）和边框
• 表格支持两层表头（header_groups）
• 支持页眉页脚（首页不同、奇偶页不同）、分节、目录

• 中途出错别续旧草稿，重新来一份更稳。
• 想参考旧版内容，先上传旧文档让模型提取，再用提取结果生成新的。

• Office：.docx .xlsx .pptx .doc .xls .ppt
• PDF：.pdf
• 文本和代码：.txt .md .log .rst .json .yaml .yml .toml .xml .csv .html .css .sql .sh .bat .py .js .ts .jsx .tsx .c .cpp .h .java .go .rs

.docx .xlsx .pptx

# 旧格式读取 + win32com 转换
pip install pywin32

# Word 转 PDF
pip install docx2pdf

# 读 .doc
apt install antiword

# Office -> PDF
apt install libreoffice-writer libreoffice-calc libreoffice-impress

# 读 .doc
brew install antiword

# Office -> PDF
brew install --cask libreoffice

写进 Dockerfile，镜像重建也不丢：

RUN apt-get update && apt-get install -y \
    antiword \
    libreoffice-writer libreoffice-calc libreoffice-impress \
    && rm -rf /var/lib/apt/lists/*

docker exec -it <容器名> bash
apt-get update
apt-get install -y antiword
apt-get install -y libreoffice-writer libreoffice-calc libreoffice-impress

• 默认只能访问插件工作区。开了外部路径也只放开读取和转换，删除不受影响。
• 群聊默认关闭，按需开。白名单留空 = 仅管理员可用。
• 大文件超限直接拒绝，纯文本超出分块上限会截断并提示。

enable_features_in_group 默认 false，打开它。如果还需要去掉 @ 限制，把 require_at_in_group 也关了。

查白名单。留空只有管理员能用。

三种可能：preview_settings.enable 关了；缺 pymupdf；Office 预览目前只支持 Windows 上的 Word。

PDF → Excel 是抽表格的，扫描件、跨页表格、复杂版面都容易出问题。换一份干净的 PDF，或者装 Java + tabula-py 试试。

跑 /pdf_status 看缺什么。Windows 上 Word 要 Office + docx2pdf，Excel/PPT 要 Office + pywin32；Linux/macOS 装 LibreOffice。

• 合并单元格和跨列表头
• 局部字体/颜色/边框
• 脚注/尾注
• 超链接
• 页码格式（罗马数字等）

• 独立的工作簿/工作表模型，支持 create_workbook -> write_rows -> export_workbook
• 覆盖大多数新建报表场景：多工作表、表头、分批写入、导出
• 补齐常用报表格式：列宽、冻结窗格、自动筛选、数字格式、条件格式
• 增加已有 .xlsx 的读取与续写能力，支持“先读后建”和基于现有文件继续生成
• 高级能力按需补充：公式、图表、复杂模板编辑

• 独立的演示文稿模型
• 标题页、内容页、结论页

遇到问题或者有想法，来群里聊：QQ 群 1072198212

AGPL-3.0

项目架构见 docs/architecture.md。

欢迎提 Issue 和 PR。涉及行为变更的话附上复现步骤和预期结果。