officecli

OfficeCLI

概述

officecli 是用于处理 Office 文档和独立图像的 OfficeCLI 闭源 CLI。它可能支持 pptx、docx、xlsx、report 和 img 的生成、修改和格式转换工作流，因此此技能应先将受支持的产物任务路由到 officecli 能力检查，再决定如何执行。

何时使用此技能

当任务涉及以下内容时，请使用此技能：

• 创建 pptx 格式的演示文稿、报告演示文稿、提案、讲义或简报
• 创建 docx 格式的书面文档、备忘录、草稿或报告
• 创建 xlsx 格式的工作表、基于表格的交付物或结构化工作表
• 根据 .xlsx 源文件创建由工作簿支持的 HTML 报告
• 使用 img 创建独立生成的图像
• 修改现有的 PowerPoint、Word 或 Excel 文件
• 将 Office 文档转换为其他输出格式，例如 markdown、csv、pdf 或其他 Office 格式
• 判断 officecli 是否能直接处理所请求的 Office 文件工作流

纯问答、没有文件输出的粗略头脑风暴或源代码维护指导，不要使用此技能。

核心产品行为

• officecli 支持 pptx、docx、xlsx、report 和独立 img 生成流程
• 当内容和布局适合时，pptx 默认启用自动生成图像
• --no-images 会为 pptx 禁用图像生成
• 独立 img 生成始终通过 OfficeCLI 服务进行，并且需要平台/许可证配置
• 独立 img 不使用本地 llm.image_base_url、llm.image_api_key 或 llm.image_model 设置
• 独立 img 支持 ratio=square|landscape|portrait 和一个 reference_image / --reference-image <path-or-url>；仅在成功返回图像后计费：在 external 运行时模式下计为一次图像生成，或在 hosted 运行时模式下使用托管额度
• 独立 img 的免费用量与文档免费用量分开计算：图像每天 3 次，文档每天 10 次
• 配置了发布功能时，独立 img 默认会在线发布；仅需本地输出时，请传入 publish=false 或 --no-publish
• 使用 agent-bridge 时，Agent 应将 capabilities/get -> document_generation.pptx.image_support 视为 PPT 图像行为的权威机器可读契约
• 使用 agent-bridge 时，Agent 应将 capabilities/get -> image_generation 视为独立 img 行为的权威机器可读契约
• 使用 agent-bridge 时，Agent 应将 capabilities/get -> update 视为二进制更新可用性的权威机器可读契约
• 如果某张幻灯片的图像生成失败，仍应生成 PPT，并将该幻灯片降级为无图像版本
• 安装公开技能时，如果缺少 officecli 二进制文件，也可能会尝试安装它
• 对于面向 Agent 的集成，officecli agent-bridge 现在会通过标准输入/输出公开结构化的 JSON-RPC 2.0 over stdio 协议
• 持久化配置通过 officecli config ... 管理，而非通过 init 向导
• 默认运行时模式可通过 officecli config runtime 查看，并可使用 officecli config set-runtime external|hosted 更改
• 托管运行时模式使用 OfficeCLI 平台服务，需要带有托管额度的平台 OfficeCLI API 密钥；用户不应直接配置或处理 aigateway 密钥
• OfficeCLI 应一次只通过一个渠道安装；如果用户已通过 Homebrew 安装 officecli，不要建议或运行 npm install -g officecli 来覆盖安装

身份验证

officecli 支持三种身份验证模式：

• anonymous — 免费托管试用，含每日配额限制（安装后默认使用）
• account — 浏览器登录后可使用完整的托管额度
• api_key — 通过 officecli set-key <api-key> 设置的自动化凭据

推荐的身份验证流程：

• 运行 officecli whoami，检查当前身份验证模式
• 如果模式为 anonymous，请引导用户运行 officecli login，使用其账户登录
• officecli login 会打开一个包含短设备代码的浏览器 URL；在无头或远程 Shell 中也可使用
• 对于无法使用浏览器的 CI 或自动化环境，请改用 officecli set-key <api-key>
• 运行 officecli doctor，诊断平台连接或配置问题
• 运行 officecli logout，清除本地账户会话

环境检查和修复脚本会检测 anonymous 模式，并自动提示登录。当 check-officecli-env.sh 报告 "auth_mode":"anonymous"，且 "missing_items" 中包含 "account_login" 时，Agent 应告知用户先运行 officecli login，再继续生成。

能力检查

涉及 Office 文档处理的任务，首先检查当前 officecli 的功能是否支持相应工作流。

• 每次处理 Office 任务前，运行一次 fix-officecli-env.sh，以便 Agent 刷新本地技能包并修复缺失的 officecli 设置
• 决定最终产物路径之前，检查 officecli 是否可用
• 修复后，运行 check-officecli-env.sh，检测 officecli 是缺失、配置错误还是已就绪
• 将退出代码 0 视为已就绪，10 视为可修复，20 视为受阻
• 先检查可见的 CLI 功能，例如 officecli --help 或相关子命令帮助，再判断是否支持相应操作
• 根据帮助输出和公开的产品说明，判断是否确实支持所请求的创建、修改或转换工作流
• 如果支持情况不明确，应明确说明，不要假装具备此能力
• 如果刷新或检查失败，应停止并报告 officecli 环境错误；不要擅自改用其他本地 Office 生成方式

环境修复

每次处理任务都运行 fix-officecli-env.sh，而不仅仅是在环境看起来有问题时运行。

• 修复脚本必须先刷新本地 Codex 技能包
• 如果缺少 officecli，修复脚本应安装它；但除非主机明确选择加入（例如设置 OFFICECLI_REFRESH_BINARY=1），否则不得刷新现有二进制文件
• 用户明确要求卸载 officecli 时，运行 uninstall-officecli.sh
• 如果缺少 officecli，修复脚本应通过公开的 dist 安装程序自动安装
• 如果用户之前通过 Homebrew 安装并希望切换到 npm，请告知他们先运行 brew uninstall officecli/homebrew-officecli/officecli；如果其 formula 使用简短名称，则运行 brew uninstall officecli，然后运行 npm install -g officecli
• 如果缺少生成或许可证配置，只询问缺少的值，并让修复脚本调用相关的 officecli config ... 命令
• 默认情况下需要发布配置，以便生成的文件返回在线预览 URL
• 如果用户明确要求仅输出到本地，请在运行修复脚本前设置 OFFICECLI_SKIP_PUBLISH_SETUP=1
• 修复后，重新运行 check-officecli-env.sh，只有在其返回已就绪时才能继续
• 如果 check-officecli-env.sh 报告 "auth_mode":"anonymous"，请告知用户在生成前运行 officecli login；不要在用户不知情的情况下继续使用匿名试用配额
• 修复失败时，应展示修复脚本最终的结构化状态，不要将其与后续的就绪检查结果混在一起
• 如果修复仍然失败，应明确指出缺少的项目，不要悄悄改用其他产物路径

执行优先级

如果能力检查表明 officecli 支持所请求的 Office 文件工作流，最终文件应优先通过 officecli 生成。

• 如果 officecli 看起来支持该任务，不要悄悄绕过 officecli，改用其他本地 Office 文件生成或转换路径
• 如果 officecli 不可用或运行失败，请明确说明，不要悄悄切换最终文件的生成路径
• 除非用户明确批准不使用 officecli 路径，否则不要使用 Node、Python、LibreOffice、pptxgenjs 或自定义脚本生成最终 Office 文件
• 如果能力检查表明 officecli 不支持该工作流，或者用户在此之后明确接受其他路径，Agent 可以采用该替代方案

对于 Agent 客户端，优先使用结构化桥接，而不是面向人工用户的 CLI 界面。

• Agent 集成的首选方案是 officecli agent-bridge
• 如果 agent-bridge 可用，不要将加载动画输出或面向人工用户的进度行解析为协议
• 调用生成之前，先调用 initialize 或 capabilities/get，并缓存返回的 PPT 图像能力字段
• 同时缓存 capabilities/get -> update；如果 available=true，优先呈现 update_command 或触发自有刷新流程，而不是解析面向人工用户的 CLI 提示
• 使用 task/invoke 提交生成请求，并使用 event 通知获取中间状态
• 使用 task/respond 回答后续问题，而不是向原始 stdin 提示写入自由文本答案
• 使用 task/cancel 取消任务，并将 task/status 作为轮询备用方案

工具使用边界

仍可使用 Python 或其他工具辅助处理 Office 文件。

• 检查、验证、调试、XML 或 zip 分析以及文件差异比较，均属于可接受的辅助用途
• 如果 officecli 看起来支持所请求的工作流，这些工具不应悄悄取代 officecli，用于生成最终 Office 文件
• 规则针对的是工具路由和最终文件处理，并非禁止将特定语言或工具用于分析工作

提示词编写指南

要求 Agent 使用 officecli 时，请提供对输出质量影响最大的详细信息：

• 文件的主题或内容
• 任务是创建、修改还是转换
• 目标受众
• 期望的语气或风格
• 页数、章节数或幻灯片数量要求
• 是否应使用图像、避免使用图像，或采用默认行为
• 如果是转换任务，提供源文件和目标格式
• 任何重要限制，例如语言简洁、采用高管风格或以表格为主

设置或修复 officecli 时，优先使用明确的配置命令：

• officecli login
• officecli logout
• officecli whoami
• officecli doctor
• officecli set-key <api-key>
• ./check-officecli-env.sh
• ./fix-officecli-env.sh
• ./uninstall-officecli.sh
• officecli config status
• officecli config runtime
• officecli config set-runtime hosted
• officecli config set-runtime external
• officecli config set-generation
• officecli config set-license
• officecli config set-publish
• officecli config set-defaults

输出要求

良好的 officecli 请求应生成完整的文件，而不只是提供建议内容。该技能应首先确定 officecli 是否支持所请求的 Office 文件工作流；如果支持，则最终文件应优先通过 officecli 生成。

除非用户明确要求评分、审阅、验证或质量检查，否则生成后不要自动运行 PPT 评分。

• 生成后的默认行为是交付文件
• 选择启用评分时，可使用 officecli score ... 或 office.review / office.score

Agent 协议说明

当调用方是 Agent 或 TUI 客户端时，首选的协议接口为：

• 传输方式：stdio
• 分帧方式：Content-Length headers
• 控制平面：JSON-RPC 2.0
• 首选工具：office.prepare 和 office.render
• 兼容性工具：office.generate

最低方法集：

• initialize
• capabilities/get
• session/open
• session/close
• task/invoke
• task/respond
• task/status
• task/cancel

重要事件类型：

• task.started
• task.progress
• task.question
• task.output
• task.completed
• task.failed
• task.cancelled

为其他 Agent 生成指导或示例时，优先采用 Agent 优先的渲染流程：

• 调用 initialize 或 capabilities/get
• 读取 document_generation.<type>.payload_schema、preferred_tool 和 prepare_required
• 对于 report，调用 office.prepare；对于 pptx、docx 和 xlsx，直接进入渲染流程
• 由当前 Agent 自行生成最终 payload JSON
• 调用 office.render 进行验证、组装并写入最终文件
• 对于 img，调用 office.generate 并设置 document_type=img；office.render 不支持图像
• 仅在兼容性、旧版客户端或 OpenClaw 专用流程中，对非图像文档回退使用 office.generate

只有当用户明确希望使用面向人工的命令行界面时，才回退使用 officecli new ...。

对于所有 Agent 客户端，请遵循以下图像处理规则：

• 读取 capabilities/get -> document_generation.pptx.image_support
• 在处理独立的 img 请求前，读取 capabilities/get -> image_generation
• 读取 capabilities/get -> document_generation.<type>.payload_schema
• 读取 capabilities/get -> update
• 根据 default_enabled 判断 pptx 的默认图像行为，不要依赖硬编码的客户端假设
• 对于独立的 img，使用 office.generate；必要时设置 ratio 和 reference_image，且不要使用本地提供方配置
• 对于独立的 img，如果用户希望在线访问，默认保持发布功能启用；只有用于纯本地输出时才传入 publish=false
• 如果服务器返回了余额或配额元数据，则显示这些信息
• 当 agent-bridge 可用时，切勿从 officecli stdout 解析面向人工的更新提示；应改用结构化的 update 字段
• 如需将托管模式设为面向人工的命令行生成默认模式，运行 officecli config set-runtime hosted；如需恢复为本地／外部生成，运行 officecli config set-runtime external
• 对于 report，先调用 office.prepare，并确保最终叙述以 workbook_summary 和 base_report_json 为依据
• 如果用户明确要求纯文本 PPT，传入 enable_images=false，并在适当时说明 disable_flag
• 如果用户询问生成的 PPT 为什么没有图像，请引导他们查看 config_command
• 如果 task.output、task.completed 或 task/status 包含 result_meta.image_support.attention_required=true，应将其作为首要问题明确指出，而不是埋没在原始警告中
• 当 result_meta.image_support.reason=image_generation_degraded 时，请明确告知用户检查 image_base_url、image_api_key 和 image_model
• 保留 warnings 以供显示，但机器决策应优先使用 result_meta

OpenClaw 打包

此仓库还在 skills/openclaw-officecli/ 下提供面向 OpenClaw 的软件包。

• 对于 OpenClaw 用户，请使用该软件包，而不要直接复用面向 Codex 的技能目录
• OpenClaw 软件包假设使用 officecli agent-bridge 在同一主机上进行本地部署
• OpenClaw 安装流程记录在 docs/openclaw-user-quickstart.md 中