weaver-work-cli 0.1.0

package/skill-template/business-info.json

@@ -0,0 +1,4 @@
+{
+  "weaver-work-cli-invoice": ["业票通", "发票", "票夹", "OCR", "查验", "报销发票"],
+  "weaver-work-cli-shared": ["安装", "登录", "认证", "E10", "profile", "JSON 输出", "高风险写入"]
+}

package/skill-template/domains/invoice.md

@@ -0,0 +1,23 @@
+本业务域用于 E10 业票通发票管理。入口 `SKILL.md` 按飞书 `lark-approval` 风格组织：CRITICAL 共享前置、路由优先级、高优先级语义、逐 operation 命令表、处理链、执行原则、写操作失败决策树和“不在范围”。具体用法拆到 `references/`：
+
+- `invoice-agent-entry.md`：schema、统一 `invoice run` 入口、stdin JSON 调用方式。
+- `invoice-personal-list.md`：个人票夹查询，默认筛选未报销发票。
+- `invoice-enterprise-list.md`：企业票夹查询，默认筛选未报销发票。
+- `invoice-detail.md`：按 `fid` 或 `number` 查看详情。
+- `invoice-file-upload.md`：上传发票文件。
+- `invoice-ocr-preview.md`：OCR 预览，不描述为已入票夹。
+- `invoice-validation-preview.md`：查验预览，不回写票夹。
+- `invoice-download.md`：下载发票附件。
+- `invoice-import.md`：导入发票文件的 `prepare -> apply` 写入协议。
+- `invoice-add.md`：手工新增发票的 `prepare -> apply` 写入协议。
+- `invoice-update.md`：编辑发票的 `prepare -> apply` 写入协议。
+- `invoice-delete.md`：删除发票的 `prepare -> apply` 写入协议。
+- `invoice-disabled-capabilities.md`：共享、转让、标签等暂未暴露能力的处理边界。
+
+Agent 调优重点：
+
+- `weaver-work-cli invoice schema` 是 operation 合约第一信息源。
+- 业务输入不得包含 Cookie、ETEAMSID、Token 或内部控制字段。
+- 写操作只接受 CLI 生成的 continuation，不手工构造或复用。
+- `validate=false` 只能说明跳过查验，不能描述为查验通过。
+- 结果为 `partial/write_uncertain` 时停止，不自动重放写请求。

package/skill-template/domains/shared.md

@@ -0,0 +1,8 @@
+共享底座用于所有 `weaver-work-cli-*` 业务 Skill。入口 `SKILL.md` 保留安装检查、E10 认证、JSON 输出、高风险写入和安全边界的强触发索引；细节拆到 `references/`：
+
+- `weaver-work-cli-installation.md`：安装、构建、全局 link、当前 skill 列表。
+- `e10-auth-and-session.md`：登录、profile、auth 文件、E10 会话和 `WEAVER_*` 环境变量。
+- `json-output-contract.md`：stdout/stderr、JSON envelope、退出码和脚本判断规则。
+- `high-risk-write.md`：`prepare -> apply`、用户确认、continuation 和停止条件。
+
+业务 Skill 只链接共享底座，不复制共享规则正文，避免多处规则漂移。

package/skill-template/master-skill-template.md

@@ -0,0 +1,29 @@
+---
+name: weaver-work-cli
+description: "泛微工作 CLI 聚合能力入口：{{meta_description}}"
+metadata:
+  requires:
+    bins: ["weaver-work-cli"]
+---
+
+# weaver-work-cli 聚合 Skill
+
+你是 `weaver-work-cli` 的聚合路由层。你的职责是先判断用户要使用哪个 `weaver-work-cli-*` 子能力，再读取并遵循对应子能力的说明。
+
+聚合 Skill 不直接承载具体 API 操作步骤。除非对应子能力已被读取，否则不要仅根据本文件拼命令、猜参数或执行复杂操作。
+
+所有子能力统一收纳在当前 Skill 的 `references/` 目录。选择 `weaver-work-cli-foo` 后，直接读取 `references/weaver-work-cli-foo/SKILL.md`；不要再次调用独立 Skill，也不要遍历整个 references 目录。
+
+{{shared_body}}
+
+## 使用流程
+
+1. 根据用户意图从路由表选择一个或多个子能力。
+2. 直接读取 `references/<skill-name>/SKILL.md` 加载所选子能力。
+3. 仅使用本文件列出的路由与对应子能力入口；目标能力未列出时明确说明无法路由。
+4. 仅读取当前已选子能力明确要求的前置文件和 reference。
+5. 按目标子能力说明执行；安装、E10 认证、JSON 输出和高风险写入优先遵循 `weaver-work-cli-shared`。
+
+## 能力路由
+
+{{domain_entries}}

package/skill-template/skill-template.md

@@ -0,0 +1,60 @@
+---
+name: weaver-work-cli-{{module}}
+description: "{{meta_description}}"
+metadata:
+  requires:
+    bins: ["weaver-work-cli"]
+  cliHelp: "weaver-work-cli {{command}} --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-work-cli-shared/SKILL.md`](../weaver-work-cli-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。**
+所有命令通过 `weaver-work-cli --json {{command}} run <operation> --input -` 执行。调用前先按需读取 references 下对应的文件，查参数结构，不要猜字段；**references 是第一信息源**，`weaver-work-cli {{command}} schema` 是 operation、字段和风险等级的合约来源。
+
+## 路由优先级（先判断是不是 {{title}}，再选 operation）
+
+{{routing_priority}}
+
+### 明确归 `weaver-work-cli-{{module}}` 的高优先级语义
+
+{{intent_bullets}}
+
+**判定规则：** {{routing_rule}}
+
+## 选哪个命令
+
+| 想做什么 | 命令 | 按需读取 reference |
+| --- | --- | --- |
+{{reference_rows}}
+
+处理链：
+
+{{workflow_chains}}
+
+## 执行原则（减少误路由、误重试和无效消耗）
+
+### 1) 先拿最小必要信息，再执行
+
+{{minimum_info_rules}}
+
+### 2) 已知对象时直达动作
+
+{{direct_action_rules}}
+
+### 3) 错误语义驱动，而不是盲目重试
+
+- 失败后先看进程退出码、`error.type`、`error.subtype` 和 `error.message`
+- **除非错误明确提示可恢复或需要补充参数，否则不要重复刷同一个 operation**
+- 写请求已经发出后，遇到结果不确定必须停止；不要把 `.apply` 当成可重试读操作
+
+## 写操作失败处理：{{write_uncertain_label}} 决策树
+
+{{write_uncertain_tree}}
+
+```bash
+weaver-work-cli {{command}} schema
+weaver-work-cli --json {{command}} run <operation> --input -
+```
+
+## 不在本 skill 范围
+
+{{out_of_scope}}

package/skills/weaver-work-cli-invoice/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: weaver-work-cli-invoice
+description: "泛微 E10 业票通发票：查询个人/企业票夹、查看详情、上传/OCR/查验预览/下载附件，并通过 prepare/apply 导入、新增、编辑、删除发票。当用户要处理业票通、发票、票夹、OCR、查验或发票附件时使用。共享、转让、标签当前不在范围。"
+metadata:
+  requires:
+    bins: ["weaver-work-cli"]
+  cliHelp: "weaver-work-cli invoice --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-work-cli-shared/SKILL.md`](../weaver-work-cli-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。**
+所有命令通过 `weaver-work-cli --json invoice run <operation> --input -` 执行。调用前先按需读取 references 下对应的文件，查参数结构，不要猜字段；**references 是第一信息源**，`weaver-work-cli invoice schema` 是 operation、字段和风险等级的合约来源。
+
+## 路由优先级（先判断是不是业票通发票，再选 operation）
+
+业票通发票不是通用 E10 对象。**只要用户的核心对象是业票通发票、个人/企业票夹、发票 OCR、发票查验或发票附件，就优先使用 `weaver-work-cli-invoice`。**
+
+### 明确归 `weaver-work-cli-invoice` 的高优先级语义
+
+出现以下任一语义时，优先走本 Skill：
+
+- 业票通 / 发票 / 票夹 / 个人票夹 / 企业票夹 / 发票详情
+- 发票上传 / OCR 识别 / 查验预览 / 附件下载
+- 导入发票 / 新增发票 / 编辑发票 / 删除发票
+- `fid` / `fileId` / 发票号码 / 发票代码 / 查验状态 / 报销状态
+
+**判定规则：** 只要最终动作是对业票通发票做查询、查看、上传、OCR、查验预览、下载、导入、新增、编辑或删除，就归 `weaver-work-cli-invoice`。只有当用户处理的是非发票类 E10 业务、通用工作流或尚未封装的业票通能力时，才不使用本 Skill。
+
+## 选哪个命令
+| 想做什么 | 命令 | 按需读取 reference |
+|---|---|---|
+| 查看可用 operation、字段和风险等级 | `invoice schema` | [`invoice-agent-entry.md`](references/invoice-agent-entry.md) |
+| 查询个人票夹 | `invoice run invoice.list` | [`invoice-personal-list.md`](references/invoice-personal-list.md) |
+| 查询企业票夹 | `invoice run invoice.enterprise.list` | [`invoice-enterprise-list.md`](references/invoice-enterprise-list.md) |
+| 按 `fid` 或 `number` 查看详情 | `invoice run invoice.get` | [`invoice-detail.md`](references/invoice-detail.md) |
+| 上传发票文件 | `invoice run invoice.upload` | [`invoice-file-upload.md`](references/invoice-file-upload.md) |
+| OCR 预览，不保存到票夹 | `invoice run invoice.ocr.preview` | [`invoice-ocr-preview.md`](references/invoice-ocr-preview.md) |
+| 查验预览，不回写查验结果 | `invoice run invoice.validate.preview` | [`invoice-validation-preview.md`](references/invoice-validation-preview.md) |
+| 下载发票附件 | `invoice run invoice.download` | [`invoice-download.md`](references/invoice-download.md) |
+| 准备/确认导入发票文件 | `invoice run invoice.import.prepare/apply` | [`invoice-import.md`](references/invoice-import.md) |
+| 准备/确认手工新增发票 | `invoice run invoice.add.prepare/apply` | [`invoice-add.md`](references/invoice-add.md) |
+| 准备/确认编辑发票 | `invoice run invoice.update.prepare/apply` | [`invoice-update.md`](references/invoice-update.md) |
+| 准备/确认删除发票 | `invoice run invoice.delete.prepare/apply` | [`invoice-delete.md`](references/invoice-delete.md) |
+| 共享、转让、标签或 schema 未列出的能力 | 无可用命令 | [`invoice-disabled-capabilities.md`](references/invoice-disabled-capabilities.md) |
+
+处理链：
+
+- 查票夹/详情：`invoice.list` 或 `invoice.enterprise.list` -> 必要时 `invoice.get`
+- OCR 识别预览：`invoice.ocr.preview`；如果先上传，可复用 `invoice.upload` 返回的 `upload`
+- 导入文件：`invoice.import.prepare` -> 用户确认 -> `invoice.import.apply` -> 按返回 `fid` 回查/报告
+- 手工新增：`invoice.add.prepare` -> 用户确认 -> `invoice.add.apply`
+- 编辑发票：`invoice.update.prepare` -> 用户确认 -> `invoice.update.apply`
+- 删除发票：`invoice.delete.prepare` -> 用户确认 -> `invoice.delete.apply`
+
+## 执行原则（减少误路由、误重试和无效消耗）
+
+### 1) 先拿最小必要信息，再执行
+
+- 只是查票夹时，优先直接用 `invoice.list` 或 `invoice.enterprise.list`
+- 用户已经给出 `fid` 时，不要先查列表再过滤，直接用 `invoice.get` 或对应 prepare
+- 只有需要附件归属、可编辑/可删除状态或完整票面时，才补 `invoice.get`
+
+### 2) 已知对象时直达动作
+
+- 已拿到 `fid`、`fileId`、本地文件路径或完整 `info` 时，优先调用对应 operation
+- 同一轮里如果已有足够的新鲜查询结果，不要重复查询同一票夹或同一详情
+- 不要默认走 `list -> filter -> get -> prepare -> apply` 全链路；对象已明确时应压缩步骤
+
+### 3) 错误语义驱动，而不是盲目重试
+
+- 失败后先看进程退出码、`error.type`、`error.subtype` 和 `error.message`
+- **除非错误明确提示可恢复或需要补充参数，否则不要重复刷同一个 operation**
+- 写请求已经发出后，遇到结果不确定必须停止；不要把 `.apply` 当成可重试读操作
+- **错误为 `authentication`（未登录，如 `E10 auth not found`）或 `session_expired`（登录态失效）时：立即停止当前操作，不要用示例占位域名或自行猜域名登录，也不要盲目重试**。先读取共享规则 `../weaver-work-cli-shared/references/e10-auth-and-session.md`，按其中流程用宿主提问/弹框让用户输入 E10 登录域名或选择已有 profile，完成登录后再继续原操作。
+
+## 写操作失败处理：`partial/write_uncertain` 决策树
+
+当导入 / 新增 / 编辑 / 删除等写操作返回 `partial/write_uncertain`，或提示网络中断、部分成功、回查失败、回查字段不一致时，按下面规则处理：
+
+1. **先停止盲目重试**，不要连续重复提交相同 `.apply`
+2. 优先从以下角度解释：
+   - 写请求可能已经到达服务端，但连接在结果确认前中断
+   - 服务端可能只处理了部分发票
+   - 写接口已返回成功，但详情回查失败或与预期不一致
+   - continuation、目标文件、目标发票或登录上下文可能已经变化
+3. 如需确认，只补 **一次** 只读查询（例如 `invoice.get` 或列表查询），不要陷入 query/write 循环
+4. 最终给用户明确结论、已知 `workflow.state`、成功/失败项和下一步人工确认建议，而不是继续无意义重试
+
+**特别注意：** 对导入、删除和编辑场景更要严格执行上述规则；这些场景最容易因重复提交造成重复入账、误删或覆盖用户刚修改的数据。
+
+```bash
+weaver-work-cli invoice schema
+printf '%s\n' '{"page_size":10,"start_pos":0}' | weaver-work-cli --json invoice run invoice.list --input -
+printf '%s\n' '{"fid":"12345"}' | weaver-work-cli --json invoice run invoice.get --input -
+printf '%s\n' '{"file":"./invoice.pdf","validate":false,"syncToOa":false}' | weaver-work-cli --json invoice run invoice.import.prepare --input -
+printf '%s\n' '{"file":"./invoice.pdf","continuation":"<prepare返回值>","confirm":true}' | weaver-work-cli --json invoice run invoice.import.apply --input -
+```
+## 不在本 skill 范围
+
+- 禁止加载原始 `weaver-e10-yepiaotong` Skill 代替 CLI。
+- 禁止 curl、fetch、浏览器自动化或直接访问 E10 `/api/inc/*`。
+- 禁止读取或复制 CLI runtime 内部 Token、Cookie、ETEAMSID。
+- 共享、转让和标签当前未纳入 CLI manifest；需要先补稳定 ID 来源、输入 schema、prepare/apply、写后回查和测试后再开放。
+- 非发票类 E10 能力、通用流程编排、表单/审批/组织等业务不由本 Skill 承载。

package/skills/weaver-work-cli-invoice/product.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "product": "weaver-work-cli",
+  "productVersion": "0.1.0",
+  "packageName": "weaver-work-cli",
+  "command": "weaver-work-cli",
+  "nodeEngine": ">=18"
+}

package/skills/weaver-work-cli-invoice/references/invoice-add.md

@@ -0,0 +1,18 @@
+# 手工新增发票
+
+## 什么时候读取
+
+用户要手工录入一张发票，且已经提供或可以整理出完整 `info` 对象时读取本文件。开始前也读取共享高风险协议：`../../weaver-work-cli-shared/references/high-risk-write.md`。
+
+## Operation
+
+| 阶段 | Operation | 必填输入 |
+| --- | --- | --- |
+| 准备新增 | `invoice.add.prepare` | `info`、`scope` |
+| 确认新增 | `invoice.add.apply` | `info`、`continuation`、`confirm=true` |
+
+## 注意
+
+`scope` 必须是 `personal` 或 `enterprise`。CLI 会做票面字段校验和号码重复检查；不要在业务输入中放认证字段或内部控制字段。
+
+`.prepare` 返回 `preview`、`continuation`、`expiresInSeconds` 和 `workflow.state="AWAITING_CONFIRMATION"`。展示风险后等待用户明确确认，再调用 `.apply`。

package/skills/weaver-work-cli-invoice/references/invoice-agent-entry.md

@@ -0,0 +1,38 @@
+# Agent 入口与 Schema
+
+## 什么时候读取
+
+使用 `weaver-work-cli invoice` 前、编写自动化调用、选择 operation 或确认字段结构时读取本文件。
+
+## 准备命令
+
+```bash
+weaver-work-cli --version
+weaver-work-cli doctor --e10
+weaver-work-cli invoice schema
+```
+
+如未登录，按共享规则读取 `../../weaver-work-cli-shared/references/e10-auth-and-session.md` 后处理。
+
+## 固定入口
+
+Agent 优先调用统一 operation 入口：
+
+```bash
+weaver-work-cli --json invoice run <operation> --input -
+```
+
+JSON 通过 stdin 传入，避免 shell 转义和路径注入问题：
+
+```bash
+printf '%s\n' '{"page_size":10,"start_pos":0}' \
+  | weaver-work-cli --json invoice run invoice.list --input -
+```
+
+`weaver-work-cli invoice schema` 是可用 operation、输入字段、固定参数和风险等级的第一信息源。不要用未出现在 schema 中的 operation，也不要把原始 `weaver-e10-yepiaotong` reference 当作可直接调用的 CLI 合约。
+
+## 输出处理
+
+成功结果在 stdout，失败结果在 stderr。判断规则读取共享 reference：`../../weaver-work-cli-shared/references/json-output-contract.md`。
+
+高风险写入读取共享 reference：`../../weaver-work-cli-shared/references/high-risk-write.md`。

package/skills/weaver-work-cli-invoice/references/invoice-delete.md

@@ -0,0 +1,20 @@
+# 删除发票
+
+## 什么时候读取
+
+用户要删除已有发票时读取本文件。开始前也读取共享高风险协议：`../../weaver-work-cli-shared/references/high-risk-write.md`。
+
+## Operation
+
+| 阶段 | Operation | 必填输入 |
+| --- | --- | --- |
+| 准备删除 | `invoice.delete.prepare` | `fid`，可选 `scope` |
+| 确认删除 | `invoice.delete.apply` | `continuation`、`confirm=true` |
+
+## 注意
+
+删除固定为软删除 `flag=0`。CLI 会确认当前状态允许删除，并在删除后回查目标不再可见。
+
+`.prepare` 返回 `preview`、`continuation`、`expiresInSeconds` 和 `workflow.state="AWAITING_CONFIRMATION"`。展示风险后等待用户明确确认，再调用 `.apply`。
+
+如果返回 `partial/write_uncertain`，停止自动重跑 apply；向用户报告 `data` 中的目标 `fid`、`workflow.state` 和需要人工确认的内容。

package/skills/weaver-work-cli-invoice/references/invoice-detail.md

@@ -0,0 +1,29 @@
+# 查看发票详情
+
+## 什么时候读取
+
+用户给出 `fid`、发票号码，或需要查看完整票面、附件、可编辑状态、可删除状态时读取本文件。
+
+## Operation
+
+| Operation | 固定规则 |
+| --- | --- |
+| `invoice.get` | 优先用 `fid`；没有 `fid` 时可用 `number` 查询 |
+
+## 示例
+
+```bash
+printf '%s\n' '{"fid":"12345"}' \
+  | weaver-work-cli --json invoice run invoice.get --input -
+
+printf '%s\n' '{"number":"00188205"}' \
+  | weaver-work-cli --json invoice run invoice.get --input -
+```
+
+## 返回
+
+`invoice.get` 返回服务端详情响应本身。常见字段包括 `infos[].info.fid`、`code`、`number`、`comm_info.pro`、`comm_info.price`、`comm_info.buyer`、`comm_info.payer`、`flist` 和 `modify_info`。
+
+## 注意
+
+用户已经给出 `fid` 时不要先查列表再过滤。找不到或无权查看时按失败 envelope 处理，不要自动扩大数据范围。

package/skills/weaver-work-cli-invoice/references/invoice-disabled-capabilities.md

@@ -0,0 +1,26 @@
+# 暂不暴露的能力
+
+## 什么时候读取
+
+用户要求共享发票、转让发票、打标签、移除标签，或要求调用 `weaver-work-cli invoice schema` 中不存在的业票通接口时读取本文件。
+
+## 当前不暴露
+
+以下原始接口文档存在，但当前没有纳入 `weaver-work-cli invoice` manifest，Agent 不能绕过 CLI 直接调用：
+
+- 共享发票
+- 转让发票
+- 标记发票或移除标签
+
+## 原因
+
+这些能力缺少稳定的 Agent 合约：
+
+- 共享和转让需要接收人的稳定 `appid/cid/uid` 解析来源
+- 转让会改变发票持有人，缺少接收人侧归属回查契约
+- 标签缺少标签定义来源、当前标签关系查询和移除/替换语义
+- 写操作后的读回验证边界不完整
+
+## Agent 行为
+
+遇到这类请求时，明确说明当前 CLI 未暴露该 operation，不能通过 `curl`、`fetch`、浏览器自动化或原始 E10 `/api/inc/*` 绕过。可以建议用户先由 CLI 维护者补齐 manifest、输入 schema、prepare/apply、回查和测试后再开放。

package/skills/weaver-work-cli-invoice/references/invoice-download.md

@@ -0,0 +1,22 @@
+# 下载发票附件
+
+## 什么时候读取
+
+用户要把发票附件下载到本地文件，或已经给出 `fid` 和 `fileId` 时读取本文件。
+
+## Operation
+
+| Operation | 固定规则 |
+| --- | --- |
+| `invoice.download` | 先校验 `fileId` 属于目标 `fid`，拒绝覆盖输出文件 |
+
+## 示例
+
+```bash
+printf '%s\n' '{"fid":"12345","fileId":"67890","output":"./invoice-12345.pdf"}' \
+  | weaver-work-cli --json invoice run invoice.download --input -
+```
+
+## 注意
+
+如果用户没有 `fileId`，先用 `invoice.get` 查看详情里的 `flist`。`output` 已存在时 CLI 会失败，不要自动覆盖用户文件。

package/skills/weaver-work-cli-invoice/references/invoice-enterprise-list.md

@@ -0,0 +1,35 @@
+# 查询企业票夹
+
+## 什么时候读取
+
+用户要查询企业票夹、搜索企业范围发票，或按报销状态筛选企业发票时读取本文件。
+
+## Operation
+
+| Operation | 固定规则 |
+| --- | --- |
+| `invoice.enterprise.list` | 固定 `flag=6`；默认 `sreim=3`，只查未报销发票 |
+
+## 输入
+
+列表字段以 `weaver-work-cli invoice schema` 为准，字段语义与个人票夹一致。常用字段包括 `page_size`、`start_pos`、`content`、购销方、日期、金额、票种、查验状态、来源、排序和 `sreim`。
+
+`sreim` 是查询筛选参数：`0` 获取全部发票，`1` 发票报销中，`2` 报销完成，`3` 获取未报销发票，`4` 获取不可报销。省略时 CLI 默认传 `3`。
+
+## 示例
+
+```bash
+printf '%s\n' '{"page_size":10,"start_pos":0,"buyer_company":"泛微"}' \
+  | weaver-work-cli --json invoice run invoice.enterprise.list --input -
+
+printf '%s\n' '{"page_size":10,"start_pos":0,"sreim":2}' \
+  | weaver-work-cli --json invoice run invoice.enterprise.list --input -
+```
+
+## 返回
+
+返回 `items`、`total`、`totalAmount`、`totalAmountExcludingTax`、`hasMore` 和 `scope="enterprise"`。
+
+## 注意
+
+企业票夹权限失败时不要自动降级查询个人票夹，除非用户明确要求改查个人票夹。不要在输入里传 `flag`；CLI 会固定为企业票夹。

package/skills/weaver-work-cli-invoice/references/invoice-file-upload.md

@@ -0,0 +1,28 @@
+# 上传发票文件
+
+## 什么时候读取
+
+用户只要求上传发票文件、获取上传文件 ID，或后续 OCR 需要先取得 `upload` 对象时读取本文件。
+
+## Operation
+
+| Operation | 固定规则 |
+| --- | --- |
+| `invoice.upload` | 固定上传 `ocr=1` |
+
+## 文件来源
+
+支持本地 `file` 或服务端可访问的 `url`，两者只能选一个。支持扩展名：`pdf`、`ofd`、`xml`、`png`、`jpg`、`jpeg`。
+
+本地文件必须存在、非空且不超过 25 MiB。URL 只允许 `http/https`，不能包含账号密码。
+
+## 示例
+
+```bash
+printf '%s\n' '{"file":"./invoice.pdf"}' \
+  | weaver-work-cli --json invoice run invoice.upload --input -
+```
+
+## 返回
+
+返回规范化后的 `upload` 对象，包含 `id`、`ids`、`fileType`、`fileName`、`totalPages`、`hasFanWei`、`ocrMap` 和 `fail=false`。后续 `invoice.ocr.preview` 可以直接复用这个对象。

package/skills/weaver-work-cli-invoice/references/invoice-import.md

@@ -0,0 +1,28 @@
+# 导入发票文件
+
+## 什么时候读取
+
+用户要把本地发票文件导入票夹时读取本文件。开始前也读取共享高风险协议：`../../weaver-work-cli-shared/references/high-risk-write.md`。
+
+## Operation
+
+| 阶段 | Operation | 必填输入 |
+| --- | --- | --- |
+| 准备导入 | `invoice.import.prepare` | `file`、`validate`、`syncToOa` |
+| 确认导入 | `invoice.import.apply` | `file`、`continuation`、`confirm=true` |
+
+## 示例
+
+```bash
+printf '%s\n' '{"file":"./invoice.pdf","validate":false,"syncToOa":false}' \
+  | weaver-work-cli --json invoice run invoice.import.prepare --input -
+
+printf '%s\n' '{"file":"./invoice.pdf","continuation":"<prepare返回值>","confirm":true}' \
+  | weaver-work-cli --json invoice run invoice.import.apply --input -
+```
+
+## 注意
+
+`validate` 和 `syncToOa` 必须显式传布尔值。`validate=true` 分支由服务端固定同步 OA，不能设置 `syncToOa=false`。`validate=false` 表示跳过查验，不能描述为“查验通过”。
+
+`.prepare` 返回 `preview`、`continuation`、`expiresInSeconds` 和 `workflow.state="AWAITING_CONFIRMATION"`。展示风险后等待用户明确确认，再调用 `.apply`。

package/skills/weaver-work-cli-invoice/references/invoice-ocr-preview.md

@@ -0,0 +1,33 @@
+# OCR 预览
+
+## 什么时候读取
+
+用户要识别发票文件内容，但没有明确要求入票夹或保存发票时读取本文件。
+
+## Operation
+
+| Operation | 固定规则 |
+| --- | --- |
+| `invoice.ocr.preview` | 固定 `flag=13`、`is_sync=1`、`is_save=1`、`operate_type=0`；CLI 返回 `saved=false` |
+
+## 输入
+
+支持 `file`、`url` 或 `upload` 三种来源，三者选一个。`upload` 必须是 `invoice.upload` 返回的对象。
+
+## 示例
+
+```bash
+printf '%s\n' '{"file":"./invoice.pdf"}' \
+  | weaver-work-cli --json invoice run invoice.ocr.preview --input -
+
+printf '%s\n' '{"upload":{...}}' \
+  | weaver-work-cli --json invoice run invoice.ocr.preview --input -
+```
+
+## 失败后的处理
+
+如果上传已成功但 OCR 失败，CLI 会返回 `partial/artifact_uploaded`，其中包含 `data.upload`。不要自动重复上传同一个文件；若用户要求继续 OCR，复用返回的 `upload` 对象。
+
+## 注意
+
+`saved=false` 表示 CLI 不把 OCR 预览描述为已入票夹。用户要导入时走 `invoice.import.prepare -> invoice.import.apply`。

package/skills/weaver-work-cli-invoice/references/invoice-personal-list.md

@@ -0,0 +1,47 @@
+# 查询个人票夹
+
+## 什么时候读取
+
+用户要查询个人票夹、搜索自己的发票，或按报销状态筛选个人发票时读取本文件。
+
+## Operation
+
+| Operation | 固定规则 |
+| --- | --- |
+| `invoice.list` | 固定 `flag=0`；默认 `sreim=3`，只查未报销发票 |
+
+## 输入
+
+列表字段以 `weaver-work-cli invoice schema` 为准。常用字段：
+
+- `page_size`、`start_pos`
+- `content`
+- `date_begin`、`date_end`
+- `create_tm_begin`、`create_tm_end`
+- `payer_company`、`buyer_company`
+- `payer_taxno`、`buyer_taxno`
+- `code`、`number`
+- `total_begin`、`total_end`
+- `valids`、`sources`、`types`
+- `sorts`
+- `sreim`
+
+`sreim` 是查询筛选参数：`0` 获取全部发票，`1` 发票报销中，`2` 报销完成，`3` 获取未报销发票，`4` 获取不可报销。省略时 CLI 默认传 `3`。
+
+## 示例
+
+```bash
+printf '%s\n' '{"page_size":10,"start_pos":0,"content":"滴滴"}' \
+  | weaver-work-cli --json invoice run invoice.list --input -
+
+printf '%s\n' '{"page_size":10,"start_pos":0,"sreim":0}' \
+  | weaver-work-cli --json invoice run invoice.list --input -
+```
+
+## 返回
+
+返回 `items`、`total`、`totalAmount`、`totalAmountExcludingTax`、`hasMore` 和 `scope="personal"`。分页时递增 `start_pos`，保持筛选条件和排序不变。
+
+## 注意
+
+不要在输入里传 `flag`；即使传入也会被 CLI 忽略并固定为个人票夹。空筛选条件直接省略，不要把空字符串传给 integer 字段。

package/skills/weaver-work-cli-invoice/references/invoice-update.md

@@ -0,0 +1,38 @@
+# 编辑发票
+
+## 什么时候读取
+
+用户要修改已有发票字段时读取本文件。开始前也读取共享高风险协议：`../../weaver-work-cli-shared/references/high-risk-write.md`。
+
+## Operation
+
+| 阶段 | Operation | 必填输入 |
+| --- | --- | --- |
+| 准备编辑 | `invoice.update.prepare` | `fid`、`scope`、`changes` |
+| 确认编辑 | `invoice.update.apply` | `continuation`、`confirm=true` |
+
+## 允许修改字段
+
+以 `weaver-work-cli invoice schema` 为准，当前包括：
+
+```text
+code
+number
+comm_info.pro.date
+comm_info.price.amount
+comm_info.price.total
+comm_info.price.dtax
+comm_info.buyer.company
+comm_info.buyer.tcode
+comm_info.payer.company
+comm_info.payer.tcode
+fylx
+currency
+currencyName
+```
+
+## 注意
+
+CLI 会先取完整详情、确认可编辑、生成变更预览，再在 apply 时校验目标未变化并保留附件关联。禁止修改 `fid/id`、附件关联、`sedit`、Dubbo 字段、认证字段、`skipFlag=1` 等内部字段。
+
+`.prepare` 返回 `preview`、`continuation`、`expiresInSeconds` 和 `workflow.state="AWAITING_CONFIRMATION"`。展示风险后等待用户明确确认，再调用 `.apply`。

package/skills/weaver-work-cli-invoice/references/invoice-validation-preview.md

@@ -0,0 +1,26 @@
+# 查验预览
+
+## 什么时候读取
+
+用户要查验已有发票，但没有明确要求把查验结果回写票夹时读取本文件。
+
+## Operation
+
+| Operation | 固定规则 |
+| --- | --- |
+| `invoice.validate.preview` | 先取详情，固定 `flag=100`、`is_save=1`、`needLog=false`，不回写查验结果 |
+
+## 输入
+
+必须提供 `fid` 和 `scope`。`scope` 只能是 `personal` 或 `enterprise`。
+
+## 示例
+
+```bash
+printf '%s\n' '{"fid":"12345","scope":"personal"}' \
+  | weaver-work-cli --json invoice run invoice.validate.preview --input -
+```
+
+## 注意
+
+`invoice.validate.preview` 只做预览。`saved=false` 表示没有回写票夹；不要把预览结果描述为已更新发票。