weaver-work-cli 0.1.1 → 0.1.4

package/skills/weaver-e10-yepiaotong/references/invoice-import.md

@@ -0,0 +1,45 @@
+# 导入发票文件
+
+## 什么时候读取
+
+用户要把本地发票文件导入票夹时读取本文件。开始前也读取共享高风险协议：`../../weaver-e10-shared/references/high-risk-write.md`。
+
+## Operation
+
+| 阶段 | Operation | 必填输入 |
+| --- | --- | --- |
+| 识别预览 | `invoice.ocr.preview` | `file` |
+| 准备导入 | `invoice.import.prepare` | `file`、`validate`、`syncToOa` |
+| 确认导入 | `invoice.import.apply` | `file`、`continuation`、`confirm=true` |
+
+## 示例
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.ocr.preview --input-json '{"file":"./invoice.pdf"}'
+
+weaver-work-cli --json invoice run invoice.import.prepare --input-json '{"file":"./invoice.pdf","validate":true,"syncToOa":true}'
+
+weaver-work-cli --json invoice run invoice.import.apply --input-json '{"file":"./invoice.pdf","continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json invoice run invoice.ocr.preview --input-json '{"file":"./invoice.pdf"}'
+
+weaver-work-cli --json invoice run invoice.import.prepare --input-json '{"file":"./invoice.pdf","validate":true,"syncToOa":true}'
+
+weaver-work-cli --json invoice run invoice.import.apply --input-json '{"file":"./invoice.pdf","continuation":"PREPARE_CONTINUATION","confirm":true}'
+```
+
+## 注意
+
+导入前必须先提醒用户：发票附件/图片/文件内容可能被上传到 E10 业票通、OCR/查验服务，并可能进入当前大模型上下文用于理解和处理；只有用户明确确认后才执行 `invoice.import.prepare/apply`。用户仅提供文件路径或文件名不等于同意导入或解析。
+
+导入本地发票文件的正常业务链路是：先 OCR 预览票面 -> 再导入并查验 -> 最后回查导入结果。Agent 不要因为用户只说“上传/导入发票”就默认跳过查验。
+
+`validate` 和 `syncToOa` 必须显式传布尔值。默认推荐 `validate=true`、`syncToOa=true`；`validate=true` 分支由服务端固定同步 OA，不能设置 `syncToOa=false`。只有用户明确要求跳过发票查验或离线导入时，才传 `validate=false`；`validate=false` 表示跳过查验，不能描述为“查验通过”。
+
+`.prepare` 返回 `preview`、`continuation`、`expiresInSeconds` 和 `workflow.state="AWAITING_CONFIRMATION"`。展示风险后等待用户明确确认，再调用 `.apply`。

package/skills/weaver-e10-yepiaotong/references/invoice-issuing-examples.md

@@ -0,0 +1,120 @@
+# 开票与红冲端到端示例
+
+## 什么时候读取
+
+需要参考开票或红冲完整对话流程时读取本文件。
+
+---
+
+## 示例 1：一句话开专票
+
+**用户**：帮我开一张专票给深圳腾讯科技有限公司，税号 91440300MA5G3JE95L，10万的信息技术咨询服务费，含税
+
+**AI 处理**：
+- 提取：purchaser_name, purchaser_tax_no, goods_name, amount_raw=100000, amount_is_tax_inclusive=true
+- 推断税率：信息技术咨询服务 → 6%
+- 用户确认税率 → "好的"
+- 金额计算：不含税 94339.62，税额 5660.38
+- 预览展示 → 用户"确认开票"
+- 调用 makeInvoice → 展示流水号
+
+---
+
+## 示例 2：信息不全需追问
+
+**用户**：帮我开票
+
+**AI**：
+> 需要以下信息：
+> 1. **购方名称**（开给谁？）
+> 2. **商品/服务名称**（开什么？）
+> 3. **金额**（多少钱？含税还是不含税？）
+
+**用户**：开给杭州阿里巴巴，技术服务费5万，不含税
+
+**AI**：
+> 推断税率 6%。需要购方税号吗？如需开专票请提供。
+
+**用户**：专票，税号 91330100MA27F4RQ12
+
+→ 金额计算 → 预览 → 确认 → 提交
+
+---
+
+## 示例 3：个人普票
+
+**用户**：开普票，购方张三，500块钱的餐饮服务，含税
+
+**AI 推断**：invoiceType="7", personLogo="1"，税率 6%，不含税 471.70，税额 28.30
+
+→ 预览 → 确认 → 提交
+
+---
+
+## 示例 4：多明细行
+
+**用户**：开专票给北京XX公司，税号 91110000MA01B6BH1K，明细：
+1. 软件开发服务 8万不含税
+2. 技术咨询服务 2万不含税
+3. 服务器硬件 5台每台6000含税
+
+**AI**：3 个明细行，分别推断税率 6%/6%/13%，一次性展示 → 用户确认 → 预览 → 提交
+
+---
+
+## 示例 5：Excel 附件开票
+
+**用户**：（上传 Excel）帮我按这个表开票，购方杭州XX科技，税号91330100XX，专票，不含税
+
+**AI**：
+1. 解析 Excel 表头判断同一张发票多明细行
+2. 推断税率 → 预览 → 确认 → 提交
+
+---
+
+## 示例 6：存入待开台账
+
+**用户**：帮我开票给XX公司...（常规流程）
+
+预览后用户回复："**先存台账**"
+
+**AI**：调用 makeInvoice 时添加 `"operateType": "5"` → 展示"已存入待开台账"
+
+---
+
+## 示例 7：全额红冲
+
+**用户**：帮我红冲发票 24532000000070468898
+
+**AI**：
+1. queryAvailableBlueInfo 查蓝票
+2. 展示蓝票信息（购方、金额、明细）
+3. 追问：全额/部分？原因？
+
+**用户**：全额红冲，开票有误
+
+4. 展示红冲预览 → 用户确认
+5. redConfirmationApply（isPart="0", redCause="01"）
+6. 展示结果：确认单编号 + 状态
+
+---
+
+## 示例 8：部分红冲
+
+**用户**：红冲发票 2453200...899，只冲第 1 行的 3 万
+
+**AI**：查蓝票 → 展示 → 追问原因 → "销售折让"
+
+提交：isPart="1"，detail 传 blueInvoiceLine="1"，amount="30000" → 展示结果
+
+---
+
+## 示例 9：查询红冲并确认
+
+**用户**：看看最近有没有待确认的红冲
+
+**AI**：queryRedConfirmationList → 过滤待确认记录 → 展示列表
+
+**用户**：同意第 1 条
+
+**AI**：queryRedConfirmationDetail 展示详情 → 用户确认 → redConfirmationConfirm(confirmType="Y") → 展示结果

package/skills/weaver-e10-yepiaotong/references/invoice-issuing-field-rules.md

@@ -0,0 +1,161 @@
+# 开票字段提取规则
+
+## 什么时候读取
+
+AI 需要从用户输入中推断税率、计算金额、校验字段格式，或判断发票类型时读取本文件。
+
+---
+
+## 税率推断规则
+
+### 13% — 销售货物、有形动产租赁
+
+| 关键词 | 典型商品 |
+|--------|---------|
+| 货物/商品/材料/配件/零件 | 各类实物商品 |
+| 设备/机器/仪器/电子产品 | 机械设备、电器 |
+| 食品/饮料/酒水/药品 | 食品医药 |
+| 服装/家具/钢材/水泥/建材 | 服装建材 |
+| 动产租赁/设备租赁 | 有形动产经营租赁 |
+
+### 9% — 建筑服务、交通运输、不动产
+
+| 关键词 | 典型服务 |
+|--------|---------|
+| 建筑/施工/装修/安装/工程 | 建筑安装 |
+| 运输/物流/快递/搬运 | 交通运输 |
+| 不动产/房屋/房租/土地 | 不动产 |
+| 农产品/自来水/天然气 | 农产品等 |
+
+### 6% — 现代服务、生活服务
+
+| 关键词 | 典型服务 |
+|--------|---------|
+| 咨询/顾问/策划/技术/研发 | 咨询技术 |
+| 软件/系统/SaaS/信息/数据 | 信息技术 |
+| 设计/广告/营销/培训 | 文化创意 |
+| 餐饮/住宿/旅游/物业 | 生活服务 |
+| 会计/审计/法律/检测 | 鉴证服务 |
+| 金融/保险/代理/中介 | 金融经纪 |
+
+### 3% — 小规模纳税人
+
+用户明确说"3%"或"小规模"时使用。
+
+### 推断优先级
+
+1. 用户明确指定的税率 → 最高优先
+2. 商品名称关键词匹配 → 按上表
+3. 多关键词冲突 → 取最相关（如"建筑材料"→13% 因为是货物销售）
+4. 无法确定 → 展示常见选项让用户选
+
+### 展示格式
+
+```
+根据商品名称"{goods_name}"，AI 推断：
+- 适用税率：{X}%
+其他常见税率：13%（货物）| 9%（建筑/交通）| 6%（服务）| 3%（小规模）
+如税率不正确请告知，否则将按 {X}% 计算。
+```
+
+多个明细行时每行独立推断，一次性展示所有。
+
+---
+
+## 金额计算规则
+
+### 已知含税金额
+
+```
+不含税金额 = round(含税金额 / (1 + 税率), 2)
+税额 = 含税金额 - 不含税金额
+```
+
+### 已知不含税金额
+
+```
+税额 = round(不含税金额 × 税率, 2)
+含税金额 = 不含税金额 + 税额
+```
+
+### 单价计算
+
+```
+不含税单价 = round(不含税金额 / 数量, 合理精度)
+```
+
+### 合计
+
+```
+totalAmount = sum(每行 amount)
+taxAmount = sum(每行 taxAmount)
+totalAmountWithTax = sum(每行 amountWithTax)
+```
+
+### 尾差处理
+
+```
+允许尾差 = |amountWithTax - amount - taxAmount| <= 0.06
+```
+
+超出范围提示用户核实。
+
+---
+
+## 校验规则
+
+| 规则 | 说明 |
+|------|------|
+| 购方名称必填 | 所有发票类型 |
+| 购方税号 | 专票必填；普票可选；无税号时强制普票 |
+| 税号格式 | 15/18/20位，数字+大写字母。正则：`^[0-9A-Z]{15}$\|^[0-9A-Z]{18}$\|^[0-9A-Z]{20}$` |
+| 明细至少一行 | details 不能为空 |
+| 税率合法性 | 0 / 0.01 / 0.03 / 0.05 / 0.06 / 0.09 / 0.13 |
+| 金额平衡 | amountWithTax = amount + taxAmount（允许尾差 ≤ 0.06） |
+| 合计平衡 | 明细行 amount 之和 = totalAmount |
+
+---
+
+## 购方信息提取模式
+
+| 用户表述 | 提取目标 |
+|---------|---------|
+| "给XX公司开票" / "购方XX" | purchaserName |
+| "税号XXXX" / "纳税人识别号XXXX" | purchaserTaxNo |
+| "地址：XX路XX号" | purchaserAddress |
+| "电话XXX" | purchaserTel |
+| "开户行XX银行" | purchaserBankName |
+| "账号XXXX" | purchaserBankAccount |
+
+### 从文档/图片提取
+
+| 位置 | 提取目标 |
+|------|---------|
+| 合同甲方/乙方/购买方 | purchaserName |
+| 统一社会信用代码 | purchaserTaxNo |
+| 联系地址/通讯地址 | purchaserAddress |
+| 联系电话 | purchaserTel |
+| 开户银行 | purchaserBankName |
+| 银行账号 | purchaserBankAccount |
+
+---
+
+## 商品明细提取
+
+### 从 Excel 表头匹配
+
+| 表头关键词 | 映射字段 |
+|-----------|---------|
+| 商品名称/品名/项目名称 | goods_name |
+| 规格/规格型号 | specification |
+| 单位/计量单位 | unit |
+| 数量 | quantity |
+| 单价/不含税单价 | unit_price |
+| 金额/不含税金额/含税金额 | amount_raw |
+| 税率 | tax_rate |
+
+### externalDocumentNo 生成规则
+
+用户未提供时自动生成：`AI-{YYYYMMDD}-{HHmmss}-{4位随机}`
+
+用户提供合同号/订单号时优先使用。

package/skills/weaver-e10-yepiaotong/references/invoice-issuing.md

@@ -0,0 +1,99 @@
+# 智能开票与存台账
+
+## 什么时候读取
+
+用户要求开票、开发票、开专票、开普票、填开发票、存台账，或已经给出开票字段并要求提交到业票通时读取本文件。
+
+## Operation
+
+| 阶段 | Operation | 风险 |
+| --- | --- | --- |
+| 准备开票或存台账 | `invoice.issuing.make.prepare` | read-before-write |
+| 确认提交 | `invoice.issuing.make.apply` | high-risk-write |
+
+## 输入要点
+
+`mode` 必填：
+
+- `issue`：正式开票，CLI 会确保 `operateType` 不传。
+- `ledger`：仅存入待开台账，CLI 会固定 `operateType="5"`。
+
+`payload` 是已整理好的 `MakeInvoiceReqDTO`。核心字段至少包括购方名称、发票类型、外部单号、金额合计和一条商品明细。专票或全电纸质专票必须提供购方税号。
+
+CLI 会固定销方名称 `上海泛微网络科技股份有限公司`、销方税号 `9131000070322836XD`，并补齐 `billingType="0"`、`sourceType="4"`、`asyncCallFlag="1"`、`invoiceMethod="5"`、`taxSign="1"`。Agent 不要把 Cookie、ETEAMSID、业务 Token 或认证字段放入 payload。
+
+## 命令
+
+简单 payload 可直接传 `--input-json`。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.issuing.make.prepare --input-json '{"mode":"ledger","payload":{"invoiceType":"8","externalDocumentNo":"AI-20260827-001","purchaserName":"XX科技有限公司","purchaserTaxNo":"91310000MA1234AB56","totalAmount":100,"taxAmount":6,"totalAmountWithTax":106,"details":[{"goodsName":"信息技术咨询服务","revenueCode":"3040205","taxRate":0.06,"amount":100,"amountWithTax":106,"taxAmount":6,"quantity":"1","unit":"项"}]}}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json invoice run invoice.issuing.make.prepare --input-json '{"mode":"ledger","payload":{"invoiceType":"8","externalDocumentNo":"AI-20260827-001","purchaserName":"XX科技有限公司","purchaserTaxNo":"91310000MA1234AB56","totalAmount":100,"taxAmount":6,"totalAmountWithTax":106,"details":[{"goodsName":"信息技术咨询服务","revenueCode":"3040205","taxRate":0.06,"amount":100,"amountWithTax":106,"taxAmount":6,"quantity":"1","unit":"项"}]}}'
+```
+
+复杂 payload 建议保存为 UTF-8 JSON 文件。
+
+Windows PowerShell：
+
+```powershell
+Set-Content -Encoding utf8 -LiteralPath .\issuing.json -Value @'
+{
+  "mode": "issue",
+  "payload": {
+    "invoiceType": "8",
+    "externalDocumentNo": "AI-20260827-001",
+    "purchaserName": "XX科技有限公司",
+    "purchaserTaxNo": "91310000MA1234AB56",
+    "totalAmount": 100,
+    "taxAmount": 6,
+    "totalAmountWithTax": 106,
+    "details": [{"goodsName":"信息技术咨询服务","taxRate":0.06,"amount":100,"amountWithTax":106,"taxAmount":6,"quantity":"1","unit":"项"}]
+  }
+}
+'@
+weaver-work-cli --json invoice run invoice.issuing.make.prepare --input .\issuing.json
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+cat > ./issuing.json <<'JSON'
+{
+  "mode": "issue",
+  "payload": {
+    "invoiceType": "8",
+    "externalDocumentNo": "AI-20260827-001",
+    "purchaserName": "XX科技有限公司",
+    "purchaserTaxNo": "91310000MA1234AB56",
+    "totalAmount": 100,
+    "taxAmount": 6,
+    "totalAmountWithTax": 106,
+    "details": [{"goodsName":"信息技术咨询服务","taxRate":0.06,"amount":100,"amountWithTax":106,"taxAmount":6,"quantity":"1","unit":"项"}]
+  }
+}
+JSON
+weaver-work-cli --json invoice run invoice.issuing.make.prepare --input ./issuing.json
+```
+
+## 确认链
+
+`.prepare` 返回 `preview`、`normalizedPayload`、`continuation` 和 `workflow.state="AWAITING_CONFIRMATION"`。向用户展示发票类型、购方名称、税号、外部单号、明细数量、合计不含税、税额和价税合计；用户明确确认开票或存台账后，再用相同 payload、continuation 和 `confirm=true` 调用 `.apply`。
+
+## 输出处理
+
+`.apply` 成功返回 `mode`、`serialNo`、`orderNo`、`ledgerOnly` 和原始响应。正式开票时说明申请已提交；存台账时说明已保存为待开台账。接口失败时展示业务错误原因，不自动重试。
+
+## 注意
+
+正式开票是高风险且不可逆的业务写入。同一 continuation 只服务一次确认场景；如果用户修改购方、金额、税率或明细，必须重新 prepare。
+
+字段提取、税率推断和金额计算由 Agent 在调用 CLI 前完成。原始税号、金额、名称、编码等值必须逐字符保留；不要为了“补齐位数”或“格式化”改写用户或接口给出的 ID、日期和金额。
+
+如果用户提供 Excel、Word、TXT、图片或截图来提取开票字段，解析前必须先提醒用户：文件内容可能进入当前大模型上下文，并可能发送到解析服务；必须等待明确确认。

package/skills/{weaver-work-cli-invoice → weaver-e10-yepiaotong}/references/invoice-ocr-preview.md

@@ -16,12 +16,20 @@
 
 ## 示例
 
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.ocr.preview --input-json '{"file":"./invoice.pdf"}'
+
+weaver-work-cli --json invoice run invoice.ocr.preview --input-json '{"upload":{"id":"UPLOAD_FILE_ID","fileType":"pdf","fileName":"invoice.pdf"}}'
+```
+
+macOS/Linux（bash/zsh）：
+
 ```bash
-printf '%s\n' '{"file":"./invoice.pdf"}' \
-  | weaver-work-cli --json invoice run invoice.ocr.preview --input -
+weaver-work-cli --json invoice run invoice.ocr.preview --input-json '{"file":"./invoice.pdf"}'
 
-printf '%s\n' '{"upload":{...}}' \
-  | weaver-work-cli --json invoice run invoice.ocr.preview --input -
+weaver-work-cli --json invoice run invoice.ocr.preview --input-json '{"upload":{"id":"UPLOAD_FILE_ID","fileType":"pdf","fileName":"invoice.pdf"}}'
 ```
 
 ## 失败后的处理
@@ -30,4 +38,6 @@ printf '%s\n' '{"upload":{...}}' \
 
 ## 注意
 
+OCR 前必须先提醒用户：发票附件/图片/文件内容可能被上传到 E10 业票通和 OCR 服务，并可能进入当前大模型上下文用于理解和处理；只有用户明确确认后才执行 `invoice.ocr.preview` 或复用已上传的 `upload` 对象继续 OCR。
+
 `saved=false` 表示 CLI 不把 OCR 预览描述为已入票夹。用户要导入时走 `invoice.import.prepare -> invoice.import.apply`。

package/skills/weaver-e10-yepiaotong/references/invoice-personal-list.md

@@ -0,0 +1,58 @@
+# 查询个人票夹
+
+## 什么时候读取
+
+用户要查询个人票夹、搜索自己的发票，或按报销状态筛选个人发票时读取本文件。
+
+## Operation
+
+| Operation | 固定规则 |
+| --- | --- |
+| `invoice.list` | 固定 `flag=0`；默认 `sreim="3"`、`bill_type=0`，只查未报销发票 |
+
+## 输入
+
+列表字段以 `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`（只有用户明确指定报销状态时才传）
+- `bill_type`（只有用户明确要求查凭证时才传）
+
+`sreim` 是字符串类型的查询筛选参数：`"0"` 获取全部发票，`"1"` 发票报销中，`"2"` 报销完成，`"3"` 获取未报销发票，`"4"` 获取不可报销。用户没有明确要求“全部发票/已报销/报销中/不可报销”时，必须省略 `sreim`，让 CLI 默认传 `"3"` 查询未报销发票。不要为了“最近发票”“查询发票”“个人票夹”主动传 `sreim="0"`。
+
+`bill_type` 是票据类型筛选参数：`0` 获取发票，`1` 获取凭证。用户没有明确要求“凭证”时，必须省略 `bill_type`，让 CLI 默认传 `0` 查询发票。
+
+## 示例
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"content":"滴滴"}'
+
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"sreim":"2"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"content":"滴滴"}'
+
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"sreim":"2"}'
+```
+
+## 返回
+
+返回 `items`、`total`、`totalAmount`、`totalAmountExcludingTax`、`hasMore` 和 `scope="personal"`。分页时递增 `start_pos`，保持筛选条件和排序不变。
+
+## 注意
+
+不要在输入里传 `flag`；即使传入也会被 CLI 忽略并固定为个人票夹。空筛选条件直接省略，不要把空字符串传给 integer 字段。除非用户明确要求全部或某个报销状态，否则不要传 `sreim`；除非用户明确要求凭证，否则不要传 `bill_type`。