# https://github.com/iOfficeAI/OfficeCLI 项目说明书 生成时间：2026-07-06 17:46:11 UTC ## 目录 - [入门与安装](#page-overview) - [三层架构与 Resident / Batch 模式](#page-architecture) - [Skills、MCP、SDK 与插件扩展](#page-ai-sdk) - [常用工作流与社区高频问题排查](#page-ops-troubleshooting) ## 入门与安装
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md) - [SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) - [install.sh](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) - [install.ps1](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.ps1) - [src/officecli/Program.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs)
# 入门与安装 ## 一、OfficeCLI 是什么 OfficeCLI 是一个面向 Word、Excel、PowerPoint 三类 Office 文档的命令行工具，同时也是一个可被 AI Agent 调用的 skill。它的核心思路是把常见的文档编辑动作封装成稳定的子命令（例如 `add`、`set`、`move`、`remove`、`batch`、`create`、`watch` 等），让自动化脚本和大模型能够以可审计、可重放的方式操作 `.docx` / `.xlsx` / `.pptx` 文件，避免在大段 Python 脚本中直接耦合 Office 自动化接口带来的脆弱性。资料来源：[README.md:1-40]() 为了让 AI 能稳定地按工具语义而非“自然语言猜测”去操作文件，仓库还配套提供了一个对外说明文件 `SKILL.md`，供模型在工具调用前读取，作为 prompt / system instruction 的一部分使用。资料来源：[SKILL.md:1-20]() ## 二、运行模式与基本架构 OfficeCLI 提供两种使用形态，理解它们的区别是入门的关键： | 形态 | 启动方式 | 典型用途 | 关联命令 | |------|----------|----------|----------| | 直接调用（无驻留进程） | 每次命令独立运行，进程启动→执行→退出 | 一次性脚本、CI 中转、批处理 | 绝大多数子命令 | | 驻留服务（ResidentServer） | 针对单个文档启动常驻后台进程 | AI Agent 高频编辑同一文件，减少反复打开开销 | `officecli watch `、`create --force`、`batch` | 当命令在驻留进程上执行时，所有写操作会复用同一份进程内的文档对象；最近发布的 v1.0.129 已经修复了 `batch` 与 `create --force` 在驻留模式下不会向 `watch` 推送 SSE 内容补丁的问题。资料来源：[src/officecli/Program.cs:1-60]() ## 三、安装步骤 ### 1. 系统前置要求 - 支持 Windows、macOS、Linux（以仓库提供的安装脚本所覆盖平台为准）。 - 需要能正常读写 `.docx` / `.xlsx` / `.pptx` 文件的运行环境；底层对 Office 文档的操作不依赖本地安装 Microsoft Office。 - 若计划将 OfficeCLI 暴露给局域网内其它机器访问（例如 `watch` 场景），需要确认网络与防火墙放行情况，相关需求已在社区 issue #167 中被提出。资料来源：[issue #167](https://github.com/iOfficeAI/OfficeCLI/issues/167) ### 2. 一键安装脚本 仓库根目录提供了两个平台对应的安装入口脚本： - **macOS / Linux**：执行 `install.sh`，脚本会完成下载、解压并将可执行文件链接到 `PATH` 中，使 `officecli` 在任意目录下可直接调用。 资料来源：[install.sh:1-40]() - **Windows PowerShell**：执行 `install.ps1`，将 `officecli.exe` 放入用户 PATH，并打印使用提示。 资料来源：[install.ps1:1-40]() 安装完成后，建议在终端执行一次 `officecli --help` 验证 CLI 是否已注册成功，以及 `officecli --version` 确认版本号与发行说明一致。 ### 3. 在 AI Agent 中作为 skill 集成 要让大模型（例如 Codex、Claude、各种本地 LLM）能够稳定使用 OfficeCLI，需要： 1. 在 Agent 的 skill / tool 清单中注册 `officecli` 命令及其子命令清单； 2. 将 `SKILL.md` 的内容加载到模型上下文，使其理解每个子命令的输入参数、返回值结构与边界； 3. 在涉及 `.xlsx` 多轮编辑的场景，注意驻留进程的“文件锁冲突”问题：当看到 `main pipe busy or unresponsive` 报错时，应当先执行 `officecli close ` 释放驻留进程，再重试。资料来源：[issue #63](https://github.com/iOfficeAI/OfficeCLI/issues/63) ## 四、首次使用建议与避坑 ### 1. 先用示例命令热身 推荐从最小命令开始： - `officecli create demo.xlsx`：创建一个空文档并落盘，便于理解 `--force` 与 `--output` 的语义。 - 对同一文档连续执行 `add` / `set` 类编辑操作，观察 stdout 中返回的结构化 JSON，确认模型能够正确解析 `success` / `message` / `data` 字段。 ### 2. `watch` 模式的实时预览 `officecli watch ` 会启动一个本地服务，并向浏览器/客户端推送 SSE 流式补丁。在 v1.0.129 之前，`batch` 与 `create --force` 不会触发补丁，导致预览不更新；升级到 v1.0.129 之后这两条路径已经补齐 `NotifyWatch*` 调用，可以放心使用。资料来源：[issue #169](https://github.com/iOfficeAI/OfficeCLI/issues/169), [v1.0.129 release notes](https://github.com/iOfficeAI/OfficeCLI/releases/tag/v1.0.129) ### 3. 模板与格式复用 如果希望新生成的 `.docx` 直接具备已有报告的封面、目录、页眉页脚等格式，不要让模型“从零排版”，而应先准备好一份 `.dotx` / 模板 docx，再通过 `create --template ` 或后续的 `set` 系列命令把样式写回目标文件，从而保证生成结果可直接外发。资料来源：[issue #168](https://github.com/iOfficeAI/OfficeCLI/issues/168) ### 4. 复杂版式（双栏公式等）的边界 对于 Word 中双栏内嵌公式居中、编号右对齐等版式需求，单靠 shell 层 CLI 往往不够，建议先生成结构化草稿，再通过手动微调或额外脚本接管排版细节，避免在 AI 自动化中无限试错。资料来源：[issue #166](https://github.com/iOfficeAI/OfficeCLI/issues/166) ## 五、下一步 - 阅读 `SKILL.md`，把官方推荐的子命令与返回结构纳入 Agent 的工具描述。 - 在小数据集上跑通 `create → watch → batch → close` 全链路，验证驻留进程行为。 - 关注发行说明，及时升级以获得 watch 通知、文件锁处理等行为修复。 --- ## 三层架构与 Resident / Batch 模式
相关源码文件 以下源码文件用于生成本页说明： - [src/officecli/ResidentServer.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) - [src/officecli/ResidentClient.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs) - [src/officecli/CommandBuilder.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) - [src/officecli/Core/BatchExecutor.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/BatchExecutor.cs) - [src/officecli/Core/Watch/WatchServer.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Watch/WatchServer.cs) - [src/officecli/Core/Watch/WatchNotifier.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Watch/WatchNotifier.cs)
# 三层架构与 Resident / Batch 模式 ## 1. 概述 OfficeCLI 是一个面向 Office 文档（pptx/xlsx/docx）的命令行与常驻服务工具，它将"用户→AI→文档"的编辑链路拆解为 **CLI 层、Resident 层、Core 层** 三层结构。其中 **Resident 模式** 通过长驻进程持有文件锁并将多条编辑命令汇聚到同一管道中，避免每次操作都重新打开文件；**Batch 模式** 则把多条命令一次性序列化后交给 Core 层顺序执行，保证事务级一致性。两者协同支撑 `officecli add / set / batch / create / watch` 等子命令。 ## 2. 三层架构 ```mermaid graph TB subgraph CLI["CLI 层 (入口)"] CB["CommandBuilder
解析 argv → CommandRequest"] end subgraph Resident["Resident 层 (常驻服务)"] RC["ResidentClient
命名管道 / 本地发送"] RS["ResidentServer
IPC 派发 + 锁管理"] end subgraph Core["Core 层 (执行)"] BE["BatchExecutor
顺序执行 / 事务回滚"] WS["WatchServer
SSE 推送 / 内容补丁"] WN["WatchNotifier
投递 word-patch / replace / excel-patch"] end CB -->|pipe write| RC RC -->|named pipe| RS RS -->|DirectInvoker| BE BE -->|NotifyWatch*| WN WN -. SSE .-> WS ``` - **CLI 层** 负责解析参数、构造 `CommandRequest`，由 [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) 提供。 - **Resident 层** 由 [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs) 与 [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) 组成，使用命名管道进行进程间通信，并独占文件句柄。 - **Core 层** 由 [`BatchExecutor.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/BatchExecutor.cs) 与 `Core/Watch/*` 提供真实的 Office 读写与监听推送能力。 资料来源：[src/officecli/CommandBuilder.cs:1-120]()、[src/officecli/ResidentClient.cs:1-80]()、[src/officecli/ResidentServer.cs:1-200]()。 ## 3. Resident 模式 `ResidentServer` 在 `officecli ` 首次调用时启动，单进程独占目标 Office 文件并监听命名管道。后续 CLI 调用统一通过 `ResidentClient` 把 `CommandRequest` 投递到主管道 `main pipe`，由 Resident 反序列化为命令后调用 Core 层执行。 - 常驻进程持有文件锁，因此避免了 AI Agent 反复调用产生的"文件锁冲突"（参见社区 Issue #63 中 `Resident for test_data_table.xlsx is running but the command could not be delivered (main pipe busy or unresponsive)` 的错误场景）。 - 该错误本质上意味着主管道被上一条未完成命令阻塞，需要 `officecli close` 关闭后重试，或在客户端侧加入重试与退避。 - `ResidentServer` 还直接暴露了 `ExecuteBatch` 端点，作为 Batch 模式的入口。 资料来源：[src/officecli/ResidentServer.cs:120-260]()、[src/officecli/ResidentClient.cs:40-160]()。 ## 4. Batch 模式 `BatchExecutor` 接收一个命令数组，按顺序调用底层 Invoker 执行，并在遇到失败时按已定义策略回滚已完成的步骤。它被 Resident 模式下的 `ExecuteBatch` 委托调用，从而避免了 AI 在循环中单条命令逐次争夺文件锁的问题。 需要注意的是，社区 Issue #169 报告 `ResidentServer.ExecuteBatch` 历史上不会触发 `NotifyWatch*`，导致 `officecli watch` 预览无法对批量编辑实时刷新；v1.0.129 通过 PR #170（`fix(pptx/xlsx/docx): notify watch SSE after resident batch edits`）修复了这一点，使 `batch` 与 `create --force` 在执行后同样向 `WatchServer` 推送 `excel-patch` / `replace` / `word-patch`。 资料来源：[src/officecli/Core/BatchExecutor.cs:1-220]()、[src/officecli/Core/Watch/WatchNotifier.cs:1-140]()、[src/officecli/ResidentServer.cs:200-320]()。 ## 5. Watch 与 SSE 联动 `WatchServer` 启动一个本地 SSE（默认 host 为 `localhost`，参见 Issue #167 关于监听 `0.0.0.0` 的请求），把 Office 文档的最新内容以 `word-patch` / `replace` / `excel-patch` 三类事件推送给浏览器或编辑器前端。`WatchNotifier` 是统一入口，单条 `add / set / move / remove` 与（修复后的）`batch` / `create --force` 都会调用它，从而保证预览实时同步。 | 触发源 | 是否推送 Watch | 资料来源 | | --- | --- | --- | | 单命令 `add/set/move/remove` | 是 | ResidentServer 单命令路径 | | `batch` / `create --force` | 是（v1.0.129 修复后） | BatchExecutor → WatchNotifier | | `close` 关闭 Resident | 否（终止会话） | ResidentServer | 资料来源：[src/officecli/Core/Watch/WatchServer.cs:1-180]()、[src/officecli/Core/Watch/WatchNotifier.cs:40-160]()。 ## 小结 三层架构通过 **CLI 解析 → Resident 派发 → Core 执行** 的清晰边界，把文件锁管理、命令调度、文档 IO 与预览推送解耦。Resident 模式以单进程持有锁解决了重入问题，Batch 模式以事务化顺序执行满足多步编辑的一致性需求，而 `WatchNotifier` 则把执行结果实时回放到前端——这三者共同构成了 OfficeCLI 面向 AI Agent 的核心交互模型。 --- ## Skills、MCP、SDK 与插件扩展
相关源码文件 以下源码文件用于生成本页说明： - [skills/officecli/SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli/SKILL.md) - [skills/officecli-pptx/SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-pptx/SKILL.md) - [skills/officecli-xlsx/SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md) - [skills/officecli-docx/SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-docx/SKILL.md) - [skills/morph-ppt/SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/morph-ppt/SKILL.md) - [src/officecli/McpServer.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/McpServer.cs)
# Skills、MCP、SDK 与插件扩展 ## 概述 OfficeCLI 通过三层扩展体系向 AI 代理、外部 IDE 与第三方工具开放其 Office 文档编辑能力：**Skills** 提供面向 AI 的结构化提示词与命令范式，**MCP（Model Context Protocol）** 提供标准化的工具调用协议，**SDK 与插件扩展** 则覆盖更深度的程序化集成。这种分层设计使得从轻量级 AI 助手调用到企业级工作流编排都能复用同一套底层 CLI 与常驻服务。 资料来源：[skills/officecli/SKILL.md:1-40]() ## Skills 系统 ### 通用 Skill：`officecli` 根 Skill `skills/officecli/SKILL.md` 定义了 AI 代理调用 OfficeCLI 的通用约定，包括命令格式、参数语义、错误处理规范以及如何保持长任务中的常驻进程（Resident）。当 AI 通过 CLI 创建或编辑文件时，应优先以 resident 模式启动，并复用同一连接，避免反复开关造成的资源浪费。 资料来源：[skills/officecli/SKILL.md:1-80]() ### 专项 Skills：`officecli-pptx` / `officecli-xlsx` / `officecli-docx` 针对三种主要格式分别提供独立的 Skill 描述： - **officecli-pptx**：聚焦 PPT 母版、占位符、文本框与批量替换。 - **officecli-xlsx**：覆盖单元格读写、行列批处理、命名区域以及样式映射。 - **officecli-docx**：处理段落、节、目录、页眉页脚与公式（与 issue #166 中的公式/编号对齐需求相关）。 每个 Skill 都对自家格式的语法约束、批量编辑与不可逆操作设置了更严格的 prompt 边界。 资料来源：[skills/officecli-pptx/SKILL.md:1-60](), [skills/officecli-xlsx/SKILL.md:1-60](), [skills/officecli-docx/SKILL.md:1-60]() ### 第三方 Skill：`morph-ppt` `skills/morph-ppt/SKILL.md` 是面向 PPT 风格迁移与母版复用的扩展 Skill，对应 issue #168 中“如何把已有报告的模板格式几乎原样套用到新文档”的诉求，提供了基于母版克隆与样式继承的提示词范式。 资料来源：[skills/morph-ppt/SKILL.md:1-50](), [Issue #168](https://github.com/iOfficeAI/OfficeCLI/issues/168) ## MCP 服务器 `src/officecli/McpServer.cs` 实现了 Model Context Protocol 端点，将 OfficeCLI 的子命令以工具（tool）形式暴露给兼容 MCP 的客户端（如 AionUi、Cursor、Claude Desktop）。每个工具内部都会将调用代理到底层 CLI 或 ResidentServer，并返回 JSON 结构化结果。MCP 层主要承担以下职责： | 职责 | 说明 | |------|------| | 工具注册 | 把 `add` / `set` / `move` / `remove` / `batch` 等命令注册为独立 MCP tool | | 协议转换 | 将 MCP 请求参数映射到 CLI 参数，处理路径、转义与选项默认值 | | 常驻会话 | 在长任务中复用底层 resident 进程，降低 fork/exec 开销 | | 错误透传 | 把 CLI 返回的 `success=false` 与错误消息原样回传给 AI | issue #63 反映的 “文件锁冲突” 通常源自 AI 误将新 CLI 会话并发到已锁定的文件上——MCP 层应作为单点接入，保证命令串行送达。 资料来源：[src/officecli/McpServer.cs:1-160](), [Issue #63](https://github.com/iOfficeAI/OfficeCLI/issues/63) ## SDK 与插件扩展 ### 命令与执行面 OfficeCLI 的命令面即 `officecli.exe/officecli` 二进制，配合 `watch` 子命令可以启动 SSE 预览服务。issue #169 指出 `batch` / `create --force` 路径此前未触发 `NotifyWatch*`，v1.0.129 通过 PR #170 已修复：`ResidentServer.ExecuteBatch` 现在会在每次批处理完成后向 watch 通道推送 `excel-patch` / `word-patch` / `replace` 事件。 资料来源：[Issue #169](https://github.com/iOfficeAI/OfficeCLI/issues/169), [PR #170](https://github.com/iOfficeAI/OfficeCLI/pull/170) ### 插件扩展模式 虽然仓库当前未发布独立的 NuGet/SDK 包，但插件扩展可沿三条路径实现： 1. **基于 Skill 的扩展**：新增 `skills//SKILL.md` 以引入新的 AI 工作流（例如 `morph-ppt`）。 2. **基于 MCP 的扩展**：在 `McpServer.cs` 注册新的 tool，调用现有 CLI 子命令组合。 3. **基于 Watch/Resident 的扩展**：通过 `officecli watch ` 提供的 SSE 端点订阅内容变更事件，构建第三方可视化或审计插件。 issue #167 提议的 `watch --host` 参数扩展属于第 3 类——在不修改核心服务的前提下以参数形式开放新能力。 资料来源：[src/officecli/McpServer.cs:80-200](), [Issue #167](https://github.com/iOfficeAI/OfficeCLI/issues/167) ## 集成建议 - **优先复用 Skill**：AI 集成方应阅读对应格式的 SKILL.md，让模型先学会命令语义再调用，避免出现 issue #63 中的“文件锁冲突”类误用。 - **单点 MCP 入口**：在同一会话中保持单一 MCP 连接与单一 resident 进程，确保文件锁语义一致。 - **监听 SSE 状态**：任何基于 watch 的扩展都应假设事件可能来自批量路径，并按 v1.0.129 的修复验证补丁类型（`word-patch` / `excel-patch` / `replace`）。 - **样式/模板需求**：当目标是“专业级格式”时，组合 `officecli-docx` 与 `morph-ppt` 风格的母版克隆 Skill，可最大化复用既有模板。 资料来源：[skills/officecli/SKILL.md:40-120](), [src/officecli/McpServer.cs:1-200](), [Release v1.0.129](https://github.com/iOfficeAI/OfficeCLI/releases/tag/v1.0.129) --- ## 常用工作流与社区高频问题排查
相关源码文件 以下源码文件用于生成本页说明： - [src/officecli/Core/ResidentServer.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ResidentServer.cs) - [src/officecli/Commands/WatchCommand.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Commands/WatchCommand.cs) - [src/officecli/Commands/CloseCommand.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Commands/CloseCommand.cs) - [src/officecli/Commands/BatchCommand.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Commands/BatchCommand.cs) - [src/officecli/Core/TemplateMerger.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/TemplateMerger.cs) - [src/officecli/Core/SseBroadcaster.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/SseBroadcaster.cs) - [src/officecli/Core/UpdateChecker.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/UpdateChecker.cs) - [examples/word/document-formatting.py](https://github.com/iOfficeAI/OfficeCLI/blob/main/examples/word/document-formatting.py) - [examples/excel/pivot-tables.py](https://github.com/iOfficeAI/OfficeCLI/blob/main/examples/excel/pivot-tables.py) - [examples/ppt/animations.py](https://github.com/iOfficeAI/OfficeCLI/blob/main/examples/ppt/animations.py)
# 常用工作流与社区高频问题排查 本页汇总 OfficeCLI 在日常使用中最常遇到的工作流模式与社区反馈的高频问题，覆盖 Resident（常驻进程）、`watch` 实时预览、模板套用、批处理通知与多栏排版等场景，给出可执行的排查步骤与官方推荐做法。 ## 1. 典型工作流概览 OfficeCLI 的常见使用模式可以分为三类：**单命令编辑**（`add` / `set` / `move` / `remove`）、**批处理**（`batch`）以及**常驻模式下的实时预览**（`watch`）。三类模式在 ResidentServer 中对应不同的入口方法：单命令走 `ExecuteSingle`，批处理走 `ExecuteBatch`，watch 则通过 `SseBroadcaster` 推送 `word-patch` / `excel-patch` 等补丁事件。社区问题 #169 反馈的"`batch` / `create --force` 不触发预览"即源于 `ExecuteBatch` 早期未调用 `NotifyWatch*` 系列方法，已在 v1.0.129 的 PR #170 中修复 资料来源：[src/officecli/Core/ResidentServer.cs:120-185]() 资料来源：[src/officecli/Core/SseBroadcaster.cs:30-78]()。 下表给出三者的典型组合建议： | 场景 | 推荐命令序列 | 关键注意点 | |------|--------------|------------| | 一次性小改 | 单条 `add` / `set` | 每次返回后 SSE 即时推送补丁 | | 大量结构变更 | `batch` 一次提交 | 需在 v1.0.129+ 才能触发 watch 通知 | | 与外部模板对齐 | 先 `TemplateMerger` 再 `create --force` | 模板套用不会复制页眉页脚字体 | | 实时协作 | `watch` + Resident | 默认 host 为 `localhost`，见 #167 | ## 2. Resident 文件锁冲突排查（Issue #63） 社区问题 #63 描述了在 AionUi 中通过 Codex 多次调用 OfficeCLI skill 写同一份 xlsx 时，会出现 `Resident for test_data_table.xlsx is running but the command could not be delivered (main pipe busy or unresponsive)`。根因在于 ResidentServer 对同一文件持有命名管道（named pipe）句柄，当上游 Agent 并发投递第二条命令时，主管道尚未消费上一条响应。排查步骤： 1. **确认残留进程**：执行 `officecli close ` 主动关闭该文件的常驻会话 资料来源：[src/officecli/Commands/CloseCommand.cs:1-60]()。 2. **回退到非常驻模式**：临时移除 `watch` 与后台 Resident，让每次调用都走一次性 CLI 路径。 3. **串行化 Agent 调用**：在 AionUi / Hermes 这类编排器侧加入"等待 success 后再发下一条"的节流逻辑。 4. **检查命令合法性**：非法参数会令管道长期处于错误返回态，需先 `officecli --help ` 确认语法。 如果错误依旧提示 `pipe busy`，基本可以判定是 Agent 并发而非文件 IO 锁，无需重启 Office 或重新打开文件。 ## 3. `watch` 预览失效与 host 配置（Issue #167、#169） `watch` 子命令通过 SSE 把 `word-patch` / `excel-patch` / `replace` 事件推给浏览器预览页。社区问题 #169 指出 v1.0.128 及更早版本中，`ExecuteBatch` 没有调用 `NotifyWatch*`，导致批处理期间预览无变化；该问题通过 `NotifyWatch*` 钩子在批处理结束后的提交阶段统一推送修复。资料来源：[src/officecli/Commands/BatchCommand.cs:45-110]() 资料来源：[src/officecli/Core/SseBroadcaster.cs:80-140]()。 社区问题 #167 则请求 `watch` 支持 `--host` 参数以绑定 `0.0.0.0`，目前默认仍为 `localhost`。临时方案：在反代或 `ssh -L` 端口转发下访问，或者在容器/WSL 内启动并通过宿主机映射端口。资料来源：[src/officecli/Commands/WatchCommand.cs:20-95]()。 ## 4. 模板套用与多栏排版建议（Issue #166、#168） Issue #168 询问如何将已有报告的格式（封面、目录、页眉页脚、字体）几乎原样套用到新生成的 docx。推荐路径是 `TemplateMerger`：以原报告作为模板源，将新生成的内容合并到模板的 `document.xml` 之外，保留 `styles.xml` / `header*.xml` / `footer*.xml` / `numbering.xml`。需要注意的是，模板套用只能保留**样式定义**而非**应用结果**，因此仍需对新内容显式指定样式名（如 `Heading1`、`TOC1`）。资料来源：[src/officecli/Core/TemplateMerger.cs:50-160]() 资料来源：[examples/word/document-formatting.py:1-120]()。 Issue #166 提到双栏文档中公式居中、编号右对齐的实现困难。在 OfficeCLI 当前公开命令集中，**段落级 `add` 不直接支持分栏切换**；建议的折中做法是先在模板里用 Word 原生分栏 + 连续分节符（continuous section break）划分公式区，再通过 `TemplateMerger` 注入公式段落，并借助 `pPr.numPr` 与 `jc` 属性控制编号位置。资料来源：[examples/word/document-formatting.py:122-210]() 资料来源：[examples/excel/pivot-tables.py:1-90]()。 ## 5. 版本与升级提醒 `UpdateChecker` 会在启动时静默拉取最新版本信息，社区反馈的多数并发与通知类问题已在近期补丁中修复。建议在 Agent 编排器启动命令前显式声明最低版本要求（如 `>= 1.0.129`），以避免被旧版的 `ExecuteBatch` 通知缺失问题影响。资料来源：[src/officecli/Core/UpdateChecker.cs:1-80]()。 --- --- ## Doramagic 踩坑日志 项目：iofficeai/officecli 摘要：发现 15 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug] Encrypted/password-protected files report "File contains corrupted data" instead of being detected as encrypted。 ## 1. 安装坑 · 来源证据：[Bug] Encrypted/password-protected files report "File contains corrupted data" instead of being detected as encrypted - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] Encrypted/password-protected files report "File contains corrupted data" instead of being detected as encrypted - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/iOfficeAI/OfficeCLI/issues/150 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 2. 维护坑 · 来源证据：BOM in presentation.xml.rels causes blank slides in PowerPoint - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：BOM in presentation.xml.rels causes blank slides in PowerPoint - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/iOfficeAI/OfficeCLI/issues/162 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安装坑 · 来源证据：Docs: add a Windows / Git Bash (MSYS path-conversion) section to SKILL.md - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: add a Windows / Git Bash (MSYS path-conversion) section to SKILL.md - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/iOfficeAI/OfficeCLI/issues/164 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 4. 安装坑 · 来源证据：[Windows] stdout pipe hangs ~30s when used via AI agent shell tools (OpenCode) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Windows] stdout pipe hangs ~30s when used via AI agent shell tools (OpenCode) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/iOfficeAI/OfficeCLI/issues/139 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 5. 安装坑 · 来源证据：watch preview does not live-update for `batch` or `create` edits (ResidentServer.ExecuteBatch never calls NotifyWatch*) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：watch preview does not live-update for `batch` or `create` edits (ResidentServer.ExecuteBatch never calls NotifyWatch*) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/iOfficeAI/OfficeCLI/issues/169 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 6. 安装坑 · 来源证据：中文自动编号在view的text模式下不识别导致fallback - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：中文自动编号在view的text模式下不识别导致fallback - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/iOfficeAI/OfficeCLI/issues/161 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://news.ycombinator.com/item?id=48807225 | host_targets=claude_code, claude, cursor ## 8. 配置坑 · 来源证据：view outline fails on WPS-created .docx with numeric style IDs, and ignores explicit outlineLvl - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：view outline fails on WPS-created .docx with numeric style IDs, and ignores explicit outlineLvl - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/iOfficeAI/OfficeCLI/issues/163 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 9. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://news.ycombinator.com/item?id=48807225 | README/documentation is current enough for a first validation pass. ## 10. 维护坑 · 来源证据：[Bug] DOCX: remove /footnote[@footnoteId=N] silently deletes the wrong footnote - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[Bug] DOCX: remove /footnote[@footnoteId=N] silently deletes the wrong footnote - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/iOfficeAI/OfficeCLI/issues/135 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。 ## 11. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48807225 | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48807225 | no_demo; severity=medium ## 13. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48807225 | no_demo; severity=medium ## 14. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48807225 | issue_or_pr_quality=unknown ## 15. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48807225 | release_recency=unknown