#Office CLI 与编码智能体 Skill

CLI 在本机确定性地处理文件。Skill 告诉编码智能体何时调用 CLI、怎样读取结构化结果、 如何保留源文件，以及怎样验证输出。两者属于同一条工作流，因此安装与用法集中在本页。

#1. 安装 CLI

cargo install \
  --git https://github.com/A3S-Lab/Office.git \
  --locked a3s-office-cli

确认命令可用，并以只读方式检查文件。

a3s-office --version
a3s-office validate report.docx --json
a3s-office view report.docx outline --json

编码智能体应使用 --json。结构化结果可以稳定地用于决策和断言；终端说明文字主要 面向人工阅读。

#2. 为编码智能体安装 Skill

下载后解压到智能体的个人 Skill 目录。

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
tar -xzf a3s-office-skill.tar.gz \
  -C "${CODEX_HOME:-$HOME/.codex}/skills"

压缩包包含 SKILL.md，以及 Writer、Spreadsheet、Presentation、Markdown、PDF 和 MCP 的独立参考资料。

如果 CLI 主机已经缓存了 Skill，应先校验当前包：

a3s-office skills manifest a3s-office --json

manifest 会返回 SKILL.md 和每份引用文档的字节数与 SHA-256，便于智能体 发现过期缓存并重新加载指导，而不是基于旧内容选择编辑器操作。

#3. 执行修改并验证

a3s-office set report.docx /body \
  --find Draft \
  --replace Final \
  --json

a3s-office validate report.docx --json
a3s-office view report.docx outline --json

修改之后应执行语义读取或校验命令。退出码为零只说明命令完成，不能单独证明文件已经 达到用户要求的状态。

#4. 交给编码智能体

一次说明清楚 Skill、源文件、目标修改和验证要求。

使用 $a3s-office 检查这份季度报告，修正报告年份，另存为新文件，
并验证最终目录结构和校验结果。

Skill 不替代应用逻辑，也不会自动上传文件。它只围绕本地 CLI 提供边界明确的工作流； 编码智能体仍需遵循自己的权限与沙箱规则。

#5. 操作五种浏览器编辑器

原生 CLI 负责已保存 Office 文件的类型化修改；浏览器交互需要独立、可观察的契约。 在 Office 源码仓库中，使用基于 Commander 的本地操作 CLI，不要临时拼接 shell 条件：

bun run office:ops -- plan all --json
bun run office:ops -- capabilities --json
bun run office:ops -- doctor --json
bun run office:ops -- gate writer --run \
  --browser-driver standalone \
  --cdp-port 9345
bun run office:ops -- visual spreadsheet --project compact-768

声明式矩阵覆盖 Writer、Spreadsheet、Presentation、Markdown 和 PDF，目前公开 103 个确定性 ACL 契约和 78 个视觉契约。Writer 包括字符位置、缩放、间距、着重号、隐藏文字、OpenType、内容控件、 审阅冲突、成对移动修订、手机端修订、WPS 格式/审阅快捷键、版式/字体网格对齐和数字字段；Spreadsheet 包括自动求和、选择性粘贴、条件格式、日期时间、 单元格样式、富文本、表格汇总、方向与可见性、外观/颜色、自定义序列、表格所有者、左右、部分范围和简体中文文本排序、 斜线边框、线性/路径渐变和图案填充，以及 WPS 字体快捷键、直接颜色复位、从上方复制公式/计算值与目标样式保留、Spreadsheet 手机端任务面板、上下文菜单、查找、工作表重命名、超链接与高级下划线、 Presentation IME/大窗口、手机端图表面板与批注审阅和 PDF 大文件流程。聚焦 gate 会重新生成 被忽略的夹具并解析选定的 A3S Test ACL；传入 --run 时由 A3S Test 承担主交互门禁， Playwright 仅作为桌面与紧凑视口的补充像素基线。证据写入 .a3s-test/office-ops/，不会改动 已提交的视觉基线，也不会等待 CI。

plan <surface> --json 是交给 Codex 的机器可读工作流清单。它把一行矩阵展开为类型化的 夹具、ACL、门禁、视觉、智能体以及（Writer 专用）WPS 参考命令，运行器无需为每个编辑器 编写独立的 shell 条件。 Writer 行还会公开快捷键、版式对齐、字体/网格套件及其生成的 DOCX 夹具；修改 UI 代码前应先检查这份清单。 doctor --json 会报告已安装的 A3S Test 版本；未选择受支持的 1.x 版本时会 fail-closed。 Windows 派发会把选择器和智能体 action JSON 保留在类型化 argv 中，不经过 shell 分词。

在 Windows 上，提供 --cdp-port 后，操作 CLI 会编译并使用 .a3s-test/office-ops 下的原生 .exe CDP 适配器，再以 --cdp <port> 调用锁定版本的独立 agent-browser 驱动。这样选择器和 action JSON 不会经过 .cmd 参数解析；适配器不再分离第二个 连接守护进程或轮询 session 端口文件，原生进程退出后即完成命令，避免继承的 stdio 句柄让已经结束的 ACL 操作继续挂起。Writer 文本框契约也会在 语义点击前先观察工具栏溢出和手机页面滚动；这是真实可发现的用户路径，而不是产品层焦点绕过。

定位单个失败时直接运行主 A3S Test ACL：

bun run office:ops -- a3s run tests/e2e/word-connector-editor.acl \
  --base-url http://127.0.0.1:4175/playground/ \
  --browser-driver standalone \
  --cdp-port 9345 --json

Writer 连接符 ACL 也会验证与 WPS 对齐的线型和箭头样式控件：通过上下文功能区创建实线、虚线、点线和点划线， 并设置开放与隐形端点箭头，再用 WPS 夹具确认 VML dashstyle、startarrow/endarrow 导入。本机 COM 探针记录 DashStyle=4 与有界 3/4 箭头参考；它是映射证据，不是 CI 前置条件。

探索式 UI 会话必须遵循有界生命周期：start → observe → 一次 act → observe → finish/abort。 使用类型化 action schema，状态变化后不要复用旧 ref。原生 GUI 前先检查 CUA Driver/MCP 锁定矩阵：

bun run office:ops -- a3s agent start writer --url http://127.0.0.1:4175/playground/ \
  --cdp-port 9345 --json
bun run office:ops -- a3s cua certification --json

操作 CLI 还提供常用动作的类型化子命令，因此 Codex 不需要手写和转义 action JSON。目标语法统一为 @e7、css=<selector>、role=<role>|<name>、label=<text>、 placeholder=<text>、testid=<id>、automation=<id> 或 text=<text>：

bun run office:ops -- a3s agent click --session <id> \
  --observation <n> --target 'role=button|保存' --json
bun run office:ops -- a3s agent fill --session <id> \
  --target 'label=标题' --value 'A3S Office' --json
bun run office:ops -- a3s agent viewport --session <id> \
  --width 390 --height 844 --scale 1 --json
bun run office:ops -- a3s agent screenshot --session <id> \
  --path evidence/final.png --json

每个封装命令只派发一个 A3S Test action。每次状态变化后都要重新 observe；只有当动作不在类型化封装范围内时，才使用 a3s agent act --action-json。

锁定的 CUA Driver 0.10.0 Windows profile 当前为 unsupported（没有经过审查的 Windows 应用后端）。 因此操作 CLI 对 Windows CUA 声明采取 fail-closed，并使用 A3S Test Web/CDP 证明浏览器编辑器； a3s cua certify 仅供已通过契约测试的平台配合显式 CUA policy/proxy 使用。

定位问题时可以只运行一段：

bun run office:ops -- fixtures
bun run office:ops -- check writer
bun run office:ops -- visual visual-tests/markdown-menu.functional.spec.ts

修改产品代码前先分类失败：编辑器已加载但语义、焦点、响应式几何或诊断断言错误，是产品 失败；选择器、夹具或路由过时，是测试契约失败；预览、浏览器、CDP 连接或锁定 CUA profile 不可用， 属于基础设施分类。

在 Windows 上，WPS COM 参考探针必须显式调用，并与产品运行时隔离：

bun run office:ops -- wps-probe --connector
bun run office:ops -- wps-probe --connector-type elbow

如需验证 Writer 字段对齐，可使用类型化的 WPS 字段探针，记录本机 WPS 实际写出的数字字段指令：

bun run office:ops -- wps-fields-probe --profile numeric \
  --output .a3s-test/office-ops/wps/numeric-fields.docx --json

探针记录 PAGE、NUMPAGES、SECTION 与 PAGEREF，覆盖有界的 ROMAN、ALPHABETIC、Ordinal、超链接和 MERGEFORMAT 开关；随后由 word-wps-numeric-fields.acl 在浏览器编辑器中验证相同指令，并保留截图、 可访问性、控制台与页面错误证据。未知开关保持缓存并进入诊断，不会被猜测替换。

如需字段设置流程的常用字段基线，可改用 --profile common；它会在数字字段之外记录 WPS DATE、TIME、NUMWORDS 和 NUMCHARS 指令。word-field-settings.acl 覆盖桌面与 390px 紧凑功能区中的类型化插入和编辑；COM 探针仍是本地参考，不是 CI 前置条件。

在修改命令或弹窗前，如需查看本机 WPS Writer 的真实 UI/UX，可以使用类型化的界面探针：

bun run office:ops -- wps-ui-probe --profile shell --json
bun run office:ops -- wps-ui-probe --profile fields `
  --output .a3s-test/office-ops/wps/ui/writer-fields.json --json

shell 记录 WPS 窗口以及 Ribbon、状态栏外壳；fields 额外记录字段、窗体字段、邮件合并、 页眉页脚及相关 CommandBar 的原生命令 ID；all 记录完整 CommandBars 清单。每次运行只拥有一个 隐藏的 WPS COM 实例，并在结束时明确关闭。JSON 是 UI/UX 参考证据，不是浏览器布局断言、产品运行时 依赖，也不代表 Windows CUA 已通过。

记录精确 DOCX 路径和 WPS 版本，通过 A3S Office 检查结果，比较结束后只删除精确的临时探针 文件。不要把 WPS COM 当作 CI 前置条件，也不要把 COM 属性当作浏览器布局证明。

#职责边界

全部命令与本地修改协议见 CLI 参考。