# 业票通 Agent 说明

本说明用于 AI Agent 调用安装后的 `weaver-work-cli`。Agent 只负责把用户意图映射到 CLI operation 和 JSON 参数；认证、Token、固定接口、写入确认、状态回查和错误判断都由 CLI 完成。

安装后的 Agent Skill 已拆为入口和 references：

- `skills/weaver-e10-shared/SKILL.md`：安装检查、E10 认证、JSON 输出、高风险写入和安全边界。
- `skills/weaver-e10-yepiaotong/SKILL.md`：业票通入口路由。
- `skills/weaver-e10-yepiaotong/references/`：按 schema、查询、文件预览、流程发票字段、报销、开票、写入和暂缓能力拆分的具体说明。

## 准备

```text
weaver-work-cli --version
weaver-work-cli doctor --e10
weaver-work-cli invoice schema
```

如未登录，先让用户完成：

```text
weaver-work-cli auth login --base-url "https://weapp.xxx.cn" --agent_type "<当前智能体名称>"
```

## 固定入口

Agent 优先使用统一 operation 入口。简单 JSON 用 `--input-json`，复杂 JSON 用临时文件和 `--input <path>`；只有确认当前 shell 能稳定传管道时才使用 `--input -`。

Windows PowerShell：

```powershell
weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
```

不要直接 `curl`、`fetch` 或浏览器自动化访问 E10 `/api/inc/*`。不要输出或索取 Cookie、ETEAMSID、发票 Token。

## 输出与大数据处理

输出方式是 JSON envelope 直接写 stdout，失败 envelope 写 stderr；不像飞书 CLI 已内置 `--format table/pretty/ndjson`、`--jq` 和通用翻页参数。因此 Agent 调用时要主动控量：

- **列表类查询优先加 `--view summary`（0.1.17 起）**：一次调用得到语义平表，省略空值字段，10 条发票从约 35KB 降到约 3KB，不必再写脚本解析完整 envelope。仅 `invoice.list` / `invoice.enterprise.list` 支持，其他 operation 传该参数返回 `validation/view_unsupported`。
- 需要精确字段时用 `--fields number,detailUrl`：点路径按原始 JSON 结构投影，`data.items` 逐项裁剪、列表级汇总字段保留。**不要用裸 `total` 取金额**——发票顶层 `total` 是 E10 的独立字段（实测恒为 `0`），价税合计在 `comm_info.price.total`。未命中的路径出现在 `meta.projection.missingFields`，全部未命中返回 `validation/field_not_found`。
- `--view` 与 `--fields` 互斥（同时传返回 `validation/input_conflict`），两者都只裁剪输出、不改变请求参数，因此不受列表查询字段白名单限制。
- CLI 版本低于 0.1.17 时没有这两个参数，可用 `skills/weaver-e10-yepiaotong/references/invoice-summarize.py` 兜底，字段口径一致。
- 列表默认 `page_size=10`，需要更多时再按 `start_pos` 分页。
- 回复用户时只展示结论、数量、关键字段和下一步，不要原样粘完整 stdout JSON。
- 发票列表/详情优先展示 `fid`、代码/号码、购销方、金额、日期、查验/报销状态和附件摘要。
- 全量统计按页读取并只累计必要字段；超长 OCR、详情或调试 JSON 需要保留时落本地文件，再返回路径和摘要。

## 推荐工作流

处理“把这张发票录入业票通”的典型流程：

1. 查询个人票夹和企业票夹，确认目标不存在。
2. `invoice.ocr.preview` 预览文件识别结果，预览阶段固定不保存。
3. 用户确认后执行 `invoice.import.prepare`，输入必须显式包含 `validate` 和 `syncToOa`；默认传 `validate=true`、`syncToOa=true`，表示导入时请求服务端查验并按服务端要求同步 OA。使用 `filedMap` 时保持 JSON 对象输入，不要转成字符串。
4. 把 prepare 返回的 `continuation` 原样交给 `invoice.import.apply`，并传 `confirm=true`。
5. 使用返回的 `fid` 回查详情，按实际结果报告查验状态、写入状态和附件信息。

只有用户明确要求跳过发票查验或离线导入时，Agent 才能传 `validate=false`。这种结果必须报告为“跳过查验”，不能写成“查验通过”。

删除、编辑、新增同样必须使用 `prepare -> apply`。出现 `partial/write_uncertain` 时停止，不能自动重试写操作。

处理“把发票填进流程表单”的场景，使用 `invoice.browse-field.data` 生成浏览按钮控件所需 JSON。处理“报销发票/自动填单”时，先读取 `invoice-reim.md`，用报销相关只读 operation 获取事前申请、工作流、表单结构、预填信息和人员上级；Agent 组装报销单结构化 JSON 后，必须通过 `invoice.reim.flow.create.prepare/apply` 或 `invoice.reim.flow.update.prepare/apply` 写入，创建报销单的 `work_flow_id/mainFormId/request_name/main_fields/detail_rows` 等字段在 operation 顶层传入，不包通用 `payload`。处理“开票/存台账”时，先读取 `invoice-issuing.md` 和 `invoice-issuing-field-rules.md`，从用户输入或附件提取购方、税号、明细、税率和金额；资料不足时追问用户补齐，再走 `invoice.issuing.make.prepare/apply`。当前修正资料包没有客户档案查询或红字发票红冲接口，`invoice.customer.*` 和 `invoice.red.*` 不能调用或绕过。

## 暂缓能力

以下新版源资料已有提交接口，但当前仍不暴露为 Agent 操作：

- 共享发票：缺接收人的稳定 `appid/cid/uid` 解析和共享关系回查契约。
- 转让发票：会改变持有人，缺接收人侧归属回查契约。
- 标记发票：缺标签定义来源、当前关系查询和移除/替换语义。