weaver-work-cli 0.1.25 → 0.1.28

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

@@ -2,85 +2,127 @@
 
 ## 什么时候读取
 
-需要参考开票完整对话流程时读取本文件。
+需要参考开票完整对话流程时读取本文件。全部示例都是**唯一链路**（契约锁台账 → 开票流程草稿，规则见 [invoice-issuing-workflow.md](invoice-issuing-workflow.md)）。CLI 已移除直接开票接口（0.1.27 起），用户说"直接开票 / 不走流程 / 存待开台账"时同样走主链路建流程草稿，并向用户说明开票必须经流程审批。
 
 ---
 
-## 示例 1：一句话开专票
+# 主链路：按契约锁台账发起开票流程
 
-**用户**：帮我开一张专票给深圳腾讯科技有限公司，税号 91440300MA5G3JE95L，10万的信息技术咨询服务费，含税
+## 示例 1：按合同号开票
 
-**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. `invoice.issuing.qys.list`，`keyword="南昌我爱我家"` → `groups` 命中 1 组（合同号 20266105541，1 行，技术服务费，6.0%，开票金额合计 20000.00）
+2. 展示确认卡片：
+
+> 将为以下合同发起「开票申请」流程（只存草稿，不会直接开票）：
+>
+> 合同号：20266105541（南昌我爱我家科技有限公司开放平台续购20000元10000份）
+> 购方：南昌我爱我家科技有限公司　税号：91360125083909438T
+> 发票类型：全电专票
+>
+> | 序号 | 商品 | 税率 | 开票金额（含税） |
+> | --- | --- | --- | --- |
+> | 1 | 技术服务费 | 6.0% | 20000 |
+>
+> 开票金额合计（含税）：20000.00（共 1 行）
+>
+> 本次开票金额：20000（默认按总金额开）
+>
+> 开票事由：合同20266105541（南昌我爱我家科技有限公司开放平台续购20000元10000份）技术服务费全额开票，金额20000元
+>
+> 预计收款时间：（必填）请选择：本月底 2026-10-31 / 下月底 2026-11-30 / 30 天后 2026-11-22，或直接给一个日期
+>
+> 请回复预计收款时间并确认发起。
+
+**用户**：确认，下月底收款
 
 **AI**：
-> 需要以下信息：
-> 1. **购方名称**（开给谁？）
-> 2. **商品/服务名称**（开什么？）
-> 3. **金额**（多少钱？含税还是不含税？）
 
-**用户**：开给杭州阿里巴巴，技术服务费5万，不含税
+3. `workflow.createForm`，`workflow=["契约锁合同收款发票开具及快递申请(100003460000001852)"]`
+4. 按 [invoice-issuing-form-fill-rules.md](invoice-issuing-form-fill-rules.md) 组装 `data`，用户没有特殊说明，全部取默认值：
+   - `data.main`：「合同号」`20266105541`；「相关合同审批流程」`南昌我爱我家科技有限公司开放平台续购20000元10000份(1326792548468580636)`；「产品类型」`契约锁`；「开票日期」取当天；「开票备注」`20266105541`；「预计收款时间」按"下月底"换算为 `2026-11-30`；「开票事由」自动生成为 `合同20266105541（南昌我爱我家科技有限公司开放平台续购20000元10000份）技术服务费全额开票，金额20000元`。
+   - 明细第 1 行取该组唯一台账行，只传「金额（含税）」`20000`（按总金额开）。货物名称、购买方名称、明细合同号、明细行id、单价、规格类型、单位、税率、总开票金额、已开票金额、未开票金额都由合同号联动带出，不传；开票内容、数量、开户行名称、开户行银行帐号创建时不传；金额(不含税)、税额不传。
+   - `requestName="开票申请-南昌我爱我家科技有限公司-20266105541"`。
 
-**AI**：
-> 请问是开**个人票（普票，无需税号）**还是**企业专票（需提供税号）**？
+   如果用户说"这次先开 1 万"，明细「金额（含税）」改填 `10000`，开票事由改为 `合同20266105541（南昌我爱我家科技有限公司开放平台续购20000元10000份）技术服务费开票，本次10000元，合同开票总额20000.00元`，其余不变。
+5. `workflow.createRequest`，`action="draft"` → `CREATED` → 原样粘贴 `finalMarkdown`，再补一句「预计收款时间按『下月底』填为 2026-11-30」
+
+   如果用户只回"确认"没给日期：**不建草稿**，只问「预计收款时间填哪天？可以直接回 本月底 / 下月底 / 30 天后，或给一个具体日期。」拿到日期后再执行第 3 步。
+6. `linkageResult` 含「是否存在合同明细数据=存在」「总开票金额=20000.00」「货物名称=技术服务费」，且「本次开票总金额=20000.00」与本次填写的金额一致 → 不额外说明
+7. 补正开户行：`workflow.editLoad` 读草稿。假设台账没有开户行信息、「开户行及帐号」为 `兴业银行股份有限公司深圳西乡支行，账号：338160100100000455`，按「，账号：」拆开。`workflow.editPrepare` 只传主表这两个字段，然后问用户：
 
-**用户**：专票，税号 91330100MA27F4RQ12
+   > 草稿已建好。开户行名称和账号需要分开补进草稿：
+   > - 开户行名称：兴业银行股份有限公司深圳西乡支行
+   > - 开户行银行帐号：338160100100000455
+   >
+   > 要把开户行名称和账号分开补进草稿吗？
 
-→ 推断税率 6% → 金额计算 → 预览 → 确认 → 提交
+   用户确认后 `workflow.editApply`。
+8. 回复末尾提醒用户在 E10 里改的项：同一次 `editLoad` 里，开票内容为空，商品只有「技术服务费」，与选项完全相同；明细第 1 行数量是联动带出的 `1201835186337538063`，台账数量是 `1`。
+
+   > 提交前请在 E10 里改：
+   > - 开票内容：请在 E10 里选择「技术服务费」
+   > - 明细第 1 行数量：联动带出的是 1201835186337538063，请在 E10 改成 1
 
 ---
 
-## 示例 3：个人普票
+## 示例 2：命中多份合同，让用户选
+
+**用户**：开一下技术服务费那几单
+
+**AI**：`invoice.issuing.qys.list`，`keyword="技术服务费"` → `groups` 4 组。列出每组的合同号、合同审批流程、购方、行数、开票金额合计，请用户选择**一份**合同；**不替用户选**。
 
-**用户**：开普票，购方张三，500块钱的餐饮服务，含税
+**用户**：中冶南方那个
+
+**AI**：按示例 1 的第 2 步起继续，只处理这一组。用户要求多份一起开时，逐组确认、逐组 `createForm` + `createRequest`，`continuation` 不跨组复用。
+
+---
+
+## 示例 3：同一合同部分行已开票
+
+**用户**：开一下合同 20266105526 的票
 
 **AI**：
-> 是否确认开**个人普票**？（个人票无需税号）
 
-**用户**：对，开个人票
+1. `invoice.issuing.qys.list`，`contractNo="20266105526"` → 1 组，`rowCount=1`，`totalAmount="46292.10"`，`blockedRows=1`，`warnings` 含"同合同另有 1 行已开票、开票中或已废弃…"
+2. 确认卡片只列 1 行可开票明细，末尾追加：
 
-**AI 推断**：invoiceType="7", personLogo="1"，税率 6%，不含税 471.70，税额 28.30
+> ⚠️ 同合同另有 1 行已开票、开票中或已废弃。流程按合同号联动，可能一并带出这些行，请在 E10 草稿里核对明细。
 
-→ 预览 → 确认 → 提交
+3. 用户确认 → `createForm` → `createRequest(draft)` → 粘贴 `finalMarkdown`
+4. `linkageResult` 里「本次开票总金额」与本次填写的 46292.10 不一致（联动带出的行数与可开票行数不同，金额可能填到了已开票的行上）→ 在 `finalMarkdown` 后只追加一行：
+
+> ⚠️ 流程汇总的本次开票总金额为 92584.20，与本次填写的开票金额 46292.10 不一致，请在 E10 核对后再提交。
 
 ---
 
-## 示例 4：多明细行
+## 示例 4：线索为空 / 没有可开票的行
 
-**用户**：开专票给北京XX公司，税号 91110000MA01B6BH1K，明细：
-1. 软件开发服务 8万不含税
-2. 技术咨询服务 2万不含税
-3. 服务器硬件 5台每台6000含税
+**用户**：帮我开票
 
-**AI**：3 个明细行，分别推断税率 6%/6%/13%，一次性展示 → 用户确认 → 预览 → 提交
+**AI**：要给哪个合同开票？请提供合同号或客户名称。
 
----
+**用户**：中冶南方
 
-## 示例 5：Excel 附件开票
+**AI**：`invoice.issuing.qys.list`，`keyword="中冶南方"` → `groups` 为空 → `includeIssued=true` 再查一次 → 1 组，`rowCount=0`，`blockedRows=1`，`items[0].blockers=["已有发票号码 26312000000012345678"]`
 
-**用户**：（上传 Excel）帮我按这个表开票，购方杭州XX科技，税号91330100XX，专票，不含税
+> 中冶南方工程技术有限公司的合同 20266105521 当前没有可开票的行：已有发票号码 26312000000012345678。
 
-**AI**：
-1. 解析 Excel 表头判断同一张发票多明细行
-2. 推断税率 → 预览 → 确认 → 提交
+结束，不发起流程。
 
 ---
 
-## 示例 6：存入待开台账
+## 示例 4.1：购方没有税号，台账却是专票
+
+**用户**：开一下合同 20266105600 的票
+
+**AI**：`invoice.issuing.qys.list`，`contractNo="20266105600"` → 1 组，`purchaserTaxNo=""`，`invoiceTypes=["全电专票"]`，`specialInvoiceWithoutTaxNo=true`
+
+> 张三（个人）没有税号，不能开专票，只能开普票。请先把台账里这份合同的发票类型改成普票（如全电普票），再让我发起。
 
-**用户**：帮我开票给XX公司...（常规流程）
+结束，不展示确认卡片、不发起流程；也不在流程里手工改发票类型。
 
-预览后用户回复："**先存台账**"
 
-**AI**：调用 makeInvoice 时添加 `"operateType": "5"` → 展示"已存入待开台账"

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

@@ -0,0 +1,152 @@
+# 开票流程填单规则
+
+## 什么时候读取
+
+AI 开票组装 `workflow.createRequest` 的 `data` 时读取本文件（流程编排见 [invoice-issuing-workflow.md](invoice-issuing-workflow.md)）。适用流程：`契约锁合同收款发票开具及快递申请(100003460000001852)`。
+
+## 总原则
+
+1. **用户说了就按用户的**：用户本轮对某个字段有特殊说明（金额、日期、事由、收件信息等），一律以用户为准。
+2. **用户没说就按下表默认值填**：下表给了默认值的字段直接填，不再问用户。
+3. **联动字段不传**：填了「合同号」之后，联动会带出主表的购方名称、税号、发票类型，以及明细的整行台账数据（货物名称、购买方名称、明细合同号、明细行id、单价、规格类型、单位、税率、税收分类编码、总开票金额、已开票金额、未开票金额），Agent 不传这些字段。
+4. **创建时不传的三类字段**：
+   - 「开票内容」：它自己的联动会把合同号带出的明细整行冲掉。草稿建好后请用户在 E10 里选。
+   - 明细「数量」：联动会把它写成错值，Agent 改不了。草稿建好后请用户在 E10 里改。
+   - 主表开户行名称与账号：联动会把它们写成混写值。草稿建好后经编辑链补正。
+
+   详见下文「创建后补正」。
+5. **其余字段留空**：下表没有列出、用户也没说的字段，按 `workflow-create.md`「填值纪律」处理（`initialValue` → 历史一致值 → 留空）。留空的必填项会出现在草稿的 `missingFields` 里，由用户提交前补齐。
+
+字段 id 以 `createForm` 返回的 `fields` 按中文名定位为准。下表括号里的 id 是当前版本的实测值，仅供核对。
+
+## 主表
+
+| 字段 | 用户没说时的默认值 | 来源 |
+| --- | --- | --- |
+| 流程标题 `requestName` | `开票申请-{购方名称}-{合同号}` | `group.purchaserName`、`group.contractNo` |
+| 合同号（`100003720000056343`） | 本组合同号原值 | `group.contractNo` |
+| 相关合同审批流程（`100003720000056262`） | `{合同审批流程名称}({流程ID})` | `group.contractFlowName`、`group.contractFlowId`；ID 为空时留空 |
+| 开票内容（`100003720000056243`，必填） | **不传**（实测：创建时传了，明细的货物名称、总开票金额等整行都带不出来）。创建后请用户在 E10 里选：本组只有 1 个商品、且商品名与选项名**完全相同**时，在提醒里给出建议选项（如「技术服务费」）；否则只提醒选择 | `group.goodsNames` 对照字段 `options` |
+| 所售产品版本号（`100003720000056244`，下拉） | 取明细「规格类型」：`group.specifications` 只有 1 个值且与选项名**完全相同**（如 `V8.0`）时填该选项；不在选项里（如 `V8`、`8.0`）时留空，**不自行补全或改写**；有多个不同值时在确认卡片里问用户选哪个；为空时留空（不选「空」选项） | `group.specifications`（即台账「规格型号」）对照字段 `options` |
+| 产品类型（`100003720000056342`） | `契约锁` | 数据来自契约锁合同台账 |
+| 开票日期（`100003720000056255`） | 当天日期 | — |
+| 开票备注（`100003720000118915`） | 合同号 | `group.contractNo` |
+| 本次开票总金额、开票金额（本次开具发票金额） | **不传**：由表单按明细「金额（含税）」汇总（实测填 5900 后两者都联动为 5900.00） | 联动 |
+| 开票事由（填写合同第几笔款项）（`100003720000056252`） | **自动生成**，公式见下文「开票事由生成规则」；用户给了原话就用用户的 | `group`、本次开票金额 |
+| 预计收款时间（`100003720000056250`，必填，日期） | **必须问到用户给出日期才建草稿**，不自己定默认值、不留空，规则见下文「预计收款时间」 | 用户 |
+| 快递地址 | **不传**，由联动带出；用户另有指定时才填 | 联动 |
+| 公司名称、税号、开票地址、发票类型 | **不传**，以合同号联动带出的值为准 | 联动 |
+| 开户行名称（请予客户方财务核实）（`1211869454131068975`） | **创建时不传**，创建后补正为 `group.purchaserBankName` | CLI 已从台账拆好 |
+| 开户行银行帐号（请予客户方财务核实）（`1211869454131068976`） | **创建时不传**，创建后补正为 `group.purchaserBankAccount`（**只含账号**） | CLI 已从台账拆好 |
+| 发票类型 × 购方税号 | **购方没有税号只能开普票，不能开专票**。分组 `specialInvoiceWithoutTaxNo=true` 时不发起流程，让用户先在台账改为普票（见 [invoice-issuing-workflow.md](invoice-issuing-workflow.md) Step 2）。不要在 `data` 里改发票类型：联动值优先，会被覆盖 | `group.purchaserTaxNo`、`group.invoiceTypes` |
+| 收件人、联系电话、合同客户、相关合同（文档） | **不传**：填了「相关合同审批流程」后由联动带出；用户另有指定时才覆盖 | 联动 |
+
+### 开户行名称与账号
+
+是两个字段，**不能混填**：开户行名称只放银行名称（如 `招商银行福田支行`），开户行银行帐号只放账号（如 `8135 8668 8310 001`）。
+
+两个字段都在草稿建好后的「创建后补正」里填，取值按下面的先后顺序：
+
+1. **台账有开户行信息**：台账常把两者一起写进「购买方开户行账号」，合同号联动会把这串原样带进「开户行银行帐号」（如 `招商银行福田支行 8135 8668 8310 001`）。`invoice.issuing.qys.list` 的分组已经拆好，Agent 直接用 `group.purchaserBankName`、`group.purchaserBankAccount`，**不要自己拆**。拆分时分组 `warnings` 会有一条「已拆分为…」，确认卡片照常列出。
+2. **台账没有开户行信息**：表单会从客户资料带出只读字段「开户行及帐号（请予客户方财务核实）」（`100003720000056248`），格式如 `兴业银行股份有限公司深圳西乡支行，账号：338160100100000455`，但不会自动拆进上面两个字段。按「，账号：」拆成名称和账号。格式不是「{名称}，账号：{账号}」时不要猜，告诉用户原值，请其在 E10 里手工拆填。
+3. 两处都为空：这两个字段不补。
+
+## 明细（`subFormId` = `100003690000001811`）
+
+**一行对应一条台账行**，按 `group.formDataIds` 的顺序逐行填，每行的值取 `items[]` 里同一 `formDataId` 的那条台账行。
+
+明细整行由「合同号」联动从台账带出，**创建时 Agent 每行只传「金额（含税）」一列**。实测（合同 20266105492、20266105586）：
+
+- 只传金额时，联动带出货物名称、购买方名称、明细合同号、明细行id、单价、规格类型、单位、税率、税收分类编码，以及**总开票金额、已开票金额、未开票金额**。
+- 把货物名称、明细行id 等列也一起传时，联动**不再**带出总开票金额、已开票金额、未开票金额，草稿里这三列是空的。所以其余列一律不传。
+- 联动会把税率的选项 id（如 `1201835186337538063`）错写进「数量」，创建时传了台账数量也会被覆盖。所以数量不传，草稿建好后请用户在 E10 里改成台账值。
+
+| 字段 | 用户没说时的默认值 | 来源 |
+| --- | --- | --- |
+| 金额（含税）（`100003720000118901`），即本行**本次开票金额** | **按总金额开**：取该台账行的开票金额原值（台账开票金额本身就是含税金额，不再加税） | `items[].amount` |
+| 数量（`100003720000118911`） | **不传**；创建后请用户在 E10 里改成台账原值（用户指定了本次金额时也用台账数量） | `items[].quantity` |
+| 总开票金额、已开票金额、未开票金额 | **不传**：发起节点上是只读字段，传了会被 `createRequest` 以 `notEditable` 拒绝；由联动带出 | 联动 |
+| 货物名称、购买方名称、明细合同号、明细行id、单价、规格类型、单位、税率、税收分类编码 | **不传**，由联动从台账带出 | 联动 |
+| 金额(不含税)、税额、单价(不含税) | **不传、不计算**，留给表单 | — |
+
+- `items` 被 `limit` 截断、缺少本组某个 `formDataId` 时，用 `contractNo` 再查一次拿全本组的行，不要凭 `group` 汇总值拼明细。
+
+写法：`details` 里按 `group.formDataIds` 的顺序给出 N 行，CLI 会按行序把它们与联动带出的行合并。
+
+```json
+{"details": {"100003690000001811": [{"100003720000118901": "20000"}]}}
+```
+
+## 创建后补正
+
+草稿 `CREATED` 后（流程见 [invoice-issuing-workflow.md](invoice-issuing-workflow.md) Step 6 第 5、6 条），分两类处理。
+
+**Agent 经编辑链补正（只改主表）**：一次 `editPrepare` 提交，用户确认一次后 `editApply`。
+
+| 字段 | 补正值 | 不补的情况 |
+| --- | --- | --- |
+| 开户行名称（`1211869454131068975`）、开户行银行帐号（`1211869454131068976`） | 按上文「开户行名称与账号」的先后顺序取值 | 两处都为空；或「开户行及帐号」格式无法拆分；或草稿里已经是这两个值 |
+
+**请用户在 E10 里手工改**：Agent 不经编辑链改这两项。
+
+- 「开票内容」：编辑时会触发它自己的联动，`editPrepare` 实测报错。
+- 明细字段：经 `editPrepare` 改明细，保存后会多出一行，而不是改原行（实测）。
+
+| 字段 | 回复里怎么提醒 |
+| --- | --- |
+| 开票内容 | `开票内容：请在 E10 里选择「{建议选项}」`；没有建议选项时写 `开票内容：请在 E10 里选择` |
+| 明细「数量」 | 按草稿每行的「明细行id」（`1318645704062197885`）找到 `items[]` 里同一 `formDataId` 的台账行：`明细第 {N} 行数量：联动带出的是 {草稿值}，请在 E10 改成 {items[].quantity}`；台账数量为空时写 `请按实际数量改正`；草稿值已经等于台账值时不提 |
+
+- 明细行按「明细行id」对应台账行，**不按行序猜**：联动带出的行序不一定等于 `group.formDataIds` 的顺序。
+
+## 开票事由生成规则
+
+用户没给原话时，Agent 按下面的公式直接生成，**不追问用户**：
+
+| 情形 | 公式 |
+| --- | --- |
+| 按总金额开（默认） | `合同{合同号}（{合同审批流程名称}）{商品}全额开票，金额{本次开票金额}元` |
+| 用户指定了本次金额 | `合同{合同号}（{合同审批流程名称}）{商品}开票，本次{本次开票金额}元，合同开票总额{group.totalAmount}元` |
+
+- `{商品}` 取 `group.goodsNames`，多个时用「、」连接。
+- `{合同审批流程名称}` 为空时，连同括号一起省略。
+- 金额照数据原样写，不自行改格式：本次开票金额用台账 `items[].amount` 或用户原话（如 `5900`、`46292.1`），合同开票总额用 `group.totalAmount`（如 `20000.00`）。
+- 用户说了是第几笔款项（如"第二笔款"），在公式最前面加 `第{N}笔款项：`；用户没说就不加，不要自己推断。
+
+示例：`合同20266105586（深圳市康哲药业有限公司2026年度维护）年度维护费全额开票，金额5900元`
+
+## 预计收款时间
+
+必填字段，由用户决定。**用户没给出日期就不建草稿**：Agent 不推断、不给默认值（不按开票日期、合同条款或历史数据去猜），也不留空先建。
+
+- 用户开票时已经说了（如"预计月底收款"），直接用，卡片里展示换算后的日期，不再问。
+- 用户没说：确认卡片里请用户给出，并附上按当天日期算好的三个候选，方便用户直接选（模板见 [invoice-issuing-workflow.md](invoice-issuing-workflow.md) Step 3）：
+  - `本月底 {YYYY-MM-DD}`
+  - `下月底 {YYYY-MM-DD}`
+  - `30 天后 {YYYY-MM-DD}`
+
+  候选只是选项，用户没选之前不能当成默认值填。
+- 用户只回了"确认 / 继续 / 发起"、没给日期：**不建草稿**，只问一句「预计收款时间填哪天？可以直接回 本月底 / 下月底 / 30 天后，或给一个具体日期。」，拿到日期再建。用户回"随便 / 你定"时，同样请他从候选里选一个。
+- 写法：`YYYY-MM-DD`。用户说相对日期（"下月底""30 天后""11 月 15 号"）时按当天日期换算成具体日期，并在创建后的回复里说明换算结果，如「预计收款时间按『下月底』填为 2026-11-30」。
+
+## 用户指定了本次开票金额
+
+- **单行合同**：用户说「这次开 1 万」「先开一半」，就把该行「金额（含税）」填成用户给的金额，数量在创建后补正为台账值（单价由联动带出台账值，与金额对不上属正常）。「一半」这类说法按用户原意换算成金额，换算结果写进确认卡片，由用户一并确认。
+- **多行合同**：用户逐行说明了金额，就逐行填；用户只给了一个总数、没说怎么分到各行时，**问一次**怎么分，不要自己平摊。
+- 用户给的金额大于该行台账开票金额时，在确认卡片里提示「超过台账开票金额」，用户确认后照填。
+
+## 确认卡片里要体现
+
+确认卡片（见 [invoice-issuing-workflow.md](invoice-issuing-workflow.md) Step 3）在明细表后追加三行：
+
+- `本次开票金额：{合计}（{默认按总金额开 / 按你指定的金额}）`
+- `开票事由：{按上面公式生成的文本}`
+- `预计收款时间：{用户已给的日期}`；用户还没给时写 `预计收款时间：（必填）请选择：本月底 {日期} / 下月底 {日期} / 30 天后 {日期}，或直接给一个日期`
+
+`group.specifications` 非空时再追加一行：
+
+- 能填：`所售产品版本号：{选项}（取自规格类型）`
+- 不在选项里：`所售产品版本号：规格类型「{值}」不在下拉选项里，先留空，提交前请在 E10 选择`
+- 多个值：`所售产品版本号：明细规格类型有 {值1}、{值2}，请告诉我选哪个`
+
+用户在确认时改了金额或事由，以用户的为准，并按公式重新生成事由。

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

@@ -0,0 +1,210 @@
+# AI 开票：契约锁台账 → 开票流程草稿（主链路）
+
+## 什么时候读取
+
+用户说"开票""开一下合同 XX 的票""把 XX 公司那份合同开票""按台账开票""发起开票流程"等开票意图时，**默认读取本文件**。
+
+**本文件是唯一开票链路（0.1.27 起）**：CLI 已移除 `invoice.issuing.make.prepare/apply`、`invoice.issuing.qys.prepare`、`invoice.issuing.result`，不再存在"直接开票""存待开台账"的接口。用户说"直接开票""不走流程""先存台账"时，一律按本链路发起开票流程草稿，并说明开票必须经「契约锁合同收款发票开具及快递申请」流程审批后由流程侧完成；数据不在契约锁台账时，提示用户先在台账录入商品信息。
+
+## 链路概览
+
+本链路**不直接开票**：Agent 只负责从契约锁合同商品台账找到要开票的合同，在 E10 按合同号发起「开票申请」流程并**存为草稿**；用户在 E10 核对后自己提交，审批通过后由流程侧完成开票。
+
+| 步 | 命令 | 所属技能 | 风险 |
+| --- | --- | --- | --- |
+| 1 | `invoice.issuing.qys.list` | 本技能 | read |
+| 2 | `workflow.createForm` | `weaver-e10-workflow` | read |
+| 3 | `workflow.createRequest`（`action` 固定 `draft`） | `weaver-e10-workflow` | high-risk-write |
+| 修改 | `workflow.editLoad` → `workflow.editPrepare` → 用户确认 → `workflow.editApply` | `weaver-e10-workflow` | high-risk-write |
+
+流程的创建与修改依赖同级的 `weaver-e10-workflow` 技能（`../weaver-e10-workflow/`），命令契约与返回处置以 [`workflow-create.md`](../../weaver-e10-workflow/references/workflow-create.md)、[`workflow-edit.md`](../../weaver-e10-workflow/references/workflow-edit.md) 为准。该技能不存在时停止并告知用户需要安装，不要改用直接开票或其他方式代替。
+
+## 开票流程常量
+
+| 常量 | 值 |
+| --- | --- |
+| 开票流程 | `契约锁合同收款发票开具及快递申请(100003460000001852)` |
+| 关联字段 | 主表「合同号」（文本，字段 id `100003720000056343`）；以 `createForm` 返回的 `fields` 按中文名「合同号」定位为准 |
+| 流程标题 `requestName` | `开票申请-{购方名称}-{合同号}` |
+| `action` | 固定 `draft` |
+
+`workflow.createForm` 一律传上表的 `名称(ID)`。**不要按宽词 `开票` 检索**：实测会唯一命中「合同开票冲红流程」（红冲流程，只有「业务红冲原因」「相关开票流程」两个字段）并直接载入表单；「合同开票申请」「发票开具」等同名候选也不是本链路的流程。
+
+载入后必须核对，**两条都满足才往下填**，否则停止并请用户确认开票流程：
+
+- `workflow.id` 等于上表 ID，或名称含「开票」且**不含**「冲红」「红冲」「作废」「退票」；
+- `fields` 里能按中文名找到主表「合同号」字段。
+
+## 对话流程
+
+### Step 1：找台账（`invoice.issuing.qys.list`）
+
+- 用户给了合同号 → 传 `contractNo`；给了公司名、合同名或商品名 → 传 `keyword`。
+- 用户什么线索都没给（只说"帮我开票"）→ **只问一句**："要给哪个合同开票？请提供合同号或客户名称。"不要追问购方、金额、税率——这些都由台账和流程联动带出。
+- 不要传 `limit` 去翻全量；分组看 `groups`，逐行明细才看 `items`。
+- 台账查询返回 `api/business_error`「系统错误」（code 500）时，多半是当前登录租户里没有契约锁合同商品台账页面：如实告知并请用户确认登录的 E10 租户，不要重试、不要换关键词再查。
+
+### Step 2：按分组展示（`data.groups`）
+
+`groups` 已按「合同号 + 购方」分好组，**一组 = 一张开票流程**；`totalAmount` 是 CLI 按分累加的开票金额合计（台账开票金额为**含税**金额），**Agent 不做任何金额计算**。
+
+| `groups` 条数 | 处置 |
+| --- | --- |
+| 0 | 用 `includeIssued=true` 再查**一次**，按组展示 `blockedRows` 与对应 `items[].blockers`（已开票 / 已关联开票流程 / 开票中 / 已废弃），说明这份合同当前没有可开票的行，**结束**。 |
+| 1 | 直接进 Step 3 确认卡片。 |
+| 多条 | 列出分组让用户选（合同号、合同审批流程、购方、行数、商品、开票金额合计），**不要替用户选**；一次只处理一组。 |
+
+`scanComplete=false` 时提醒用户：台账超过扫描上限，结果可能不全。
+
+**税号与发票类型硬拦截**：选定的分组 `specialInvoiceWithoutTaxNo=true`（购方没有税号，台账发票类型却是专票）时，**不展示确认卡片、不发起流程**。只告诉用户：「{购方名称} 没有税号，不能开专票，只能开普票。请先把台账里这份合同的发票类型改成普票（如全电普票），再让我发起。」用户改完台账后从 Step 1 重新查。
+
+- 不要在流程里把「发票类型」改成普票来绕过：发票类型由合同号联动带出，联动值优先，Agent 传的值会被覆盖。
+- 用户坚持要开专票时，说明专票必须有购方税号，请先在台账补全税号。
+
+### Step 3：确认卡片（创建前唯一一次确认）
+
+按下面模板展示，等用户明确回复"确认""发起""好的"等同义确认后再往下走：
+
+```text
+将为以下合同发起「开票申请」流程（只存草稿，不会直接开票）：
+
+合同号：20266105541（南昌我爱我家科技有限公司开放平台续购20000元10000份）
+购方：南昌我爱我家科技有限公司　税号：91360125083909438T
+发票类型：全电专票
+| 序号 | 商品 | 税率 | 开票金额（含税） |
+| 1 | 技术服务费 | 6.0% | 20000 |
+开票金额合计（含税）：20000.00（共 1 行）
+
+本次开票金额：20000（默认按总金额开）
+开票事由：合同20266105541（南昌我爱我家科技有限公司开放平台续购20000元10000份）技术服务费全额开票，金额20000元
+预计收款时间：（必填）请选择：本月底 2026-10-31 / 下月底 2026-11-30 / 30 天后 2026-11-22，或直接给一个日期
+请回复预计收款时间并确认发起。
+```
+
+- `group.purchaserBankName` 或 `group.purchaserBankAccount` 非空时，在「购方」行下加一行 `开户行：{purchaserBankName}　账号：{purchaserBankAccount}`，两个值分开写，不要用台账原始的混写串。
+- 明细表的行取该组 `formDataIds` 对应的 `items[]`：商品取「开票名称」，为空取「商品名称」；金额取 `amount` 原值，不改写。
+- 「开票事由」按填单规则自动生成并展示在卡片里，不问用户；「预计收款时间」由用户决定，卡片里附上按当天日期算好的本月底、下月底、30 天后三个候选日期。**用户没给出日期就不建草稿**：只回"确认 / 继续"时再问一句，拿到日期再往下走；不要自己定默认日期，也不要留空先建（详见填单规则「预计收款时间」）。用户开票时已说了收款时间，卡片里直接展示换算后的日期，末行改为"确认发起吗？"。
+- `warnings` 非空时在卡片末尾逐条列出。命中"同合同另有 N 行已开票…"时追加一句："流程按合同号联动，可能一并带出这些行，请在 E10 草稿里核对明细。"
+- 用户要改购方、金额、税率或商品 → 告知需先在台账修改，再重新从 Step 1 开始；**不要在流程里手工覆盖这些值**。
+
+### Step 4：载入开票流程表单（`workflow.createForm`）
+
+- `workflow` 传「开票流程常量」里的 `名称(ID)`；**不传 `userQuestion`**，也不用 `workflow.createRequestDirect`。
+- 载入后按「开票流程常量」里的两条核对规则检查 `workflow.name` 与「合同号」字段；不满足就停止，不往下填，也不要换别的流程凑。
+- `createForm` 返回 OA 业务错误（如表单布局接口报错）时如实转述并停止，不重试、不换流程。
+
+### Step 5：组装 `data` 并存草稿（`workflow.createRequest`）
+
+`data` 按 [invoice-issuing-form-fill-rules.md](invoice-issuing-form-fill-rules.md) 组装，一句话概括：**用户说了就按用户的，没说就按默认值**。创建时的默认值包括：合同号、相关合同审批流程、产品类型「契约锁」、开票日期取当天、开票备注填合同号、所售产品版本号取明细规格类型（须与下拉选项完全一致）、开票事由按公式自动生成；预计收款时间填用户在卡片环节给的日期（必须有，没有就回到 Step 3 问）。明细每行**只传**「金额（含税）」（按总金额开）；货物名称、购买方名称、明细合同号、明细行id、单价、规格类型、单位、税率、总开票金额、已开票金额、未开票金额都由合同号联动带出，**传了反而会让总开票金额等三列带不出来**。
+
+主表「开票内容」、明细「数量」、主表「开户行名称」「开户行银行帐号」创建时**不传**，原因各不相同：
+- 「开票内容」自己的联动会把合同号带出的明细整行冲掉。
+- 联动会把数量写成税率选项 id。
+- 联动会把开户行写成名称账号混写串。
+
+开户行两个字段在 Step 6 第 5 条经编辑链补正；开票内容、数量在 Step 6 第 6 条提醒用户在 E10 里改。其余购方信息不传；金额(不含税)、税额不传、不计算。
+
+- `requestName` **必传**：`开票申请-{购方名称}-{合同号}`，不留用表单默认标题。
+- `action` 固定 `"draft"`：用户说"直接提交"也只建草稿，并告诉用户去 E10 核对后提交。
+
+`data` 较大时写成 UTF-8 JSON 文件用 `--input <path>` 传入。
+
+### Step 6：回显与核对
+
+1. 按 `workflow-create.md`「createRequest 返回后的处置」处理：`CREATED` / `NEEDS_INPUT` / `BROWSER_FILL` 有 `finalMarkdown` 就**原样粘贴**；`NEEDS_CONFIRMATION` 按 `ambiguities` 处理；`partial` / `write_uncertain` 停止，只读回查一次。
+2. `CREATED` 后用返回的 `linkageResult`（一段「字段联动带出：字段=值、…」文本）核对联动结果。明细其余列由联动写入，`previewDetails` 里只有 Agent 自己填的金额，属正常。只核对三项：
+   - 含「是否存在合同明细数据=存在」；
+   - 含「总开票金额=」和「货物名称=」（明细整行已从台账带出）；
+   - 「本次开票总金额」等于本次填入各行「金额（含税）」之和；按默认值开时，它等于 `group.totalAmount`。数值比较时 `5900.00` 与 `5900` 视为相等。
+
+   三项都满足时**不额外说明**。任一不满足时，在 `finalMarkdown` 之后**只追加一行**：`⚠️ 流程汇总的本次开票总金额为 X，与本次填写的开票金额 Y 不一致（或未带出合同明细），请在 E10 核对后再提交。`
+3. `missingFields` 非空时原样转述（提交前需补齐）；`finalMarkdown` 末尾已有这段提示时不要重复。
+4. `BROWSER_FILL`（小e 环境）只输出那段 `<browsertool>` 标签块，不做第 2 步核对。
+5. **补正开户行名称与账号**（`CREATED` 后都要做，取值规则见填单规则「创建后补正」）：
+   - `workflow.editLoad` 读草稿（`requestId` 取创建返回值），从 `currentValues` 取主表「开户行名称」「开户行银行帐号」「开户行及帐号」，以及每行「明细行id」「数量」（第 6 条要用）。
+   - 算出补正值：取 `group.purchaserBankName` / `group.purchaserBankAccount`，为空时拆「开户行及帐号」。已经相同就不提交。
+   - 有要补的：`workflow.editPrepare` **只传主表这两个字段**，不传任何明细、不传开票内容。然后向用户列出补正项，并问「要把开户行名称和账号分开补进草稿吗？」，用户确认后 `workflow.editApply`。
+   - 「开户行及帐号」格式无法拆分时不补这两项，告诉用户原值，请其在 E10 里手工拆填。
+   - `editPrepare` / `editApply` 报错时原样转述，不重试；草稿本身已建好，不受影响。
+6. **提醒用户在 E10 里改的项**：在本轮回复末尾加一段「提交前请在 E10 里改」，按填单规则「创建后补正」的提醒写法列出开票内容和需要改正的明细数量，如：
+
+   ```text
+   提交前请在 E10 里改：
+   - 开票内容：请在 E10 里选择「技术服务费」
+   - 明细第 1 行数量：联动带出的是 1201835186337538063，请在 E10 改成 1
+   ```
+
+   不要为了这两项调用 `editPrepare`。
+
+### Step 7：之后的操作
+
+- **禁止重复创建**：同一合同 `createRequest` 成功后，不要再次 `createForm` + `createRequest`；修改一律走 `workflow.editLoad` → `workflow.editPrepare` → 用户确认 → `workflow.editApply`。
+- 用户问"开出来了吗 / 发票号是多少"：说明开票在流程审批通过后由流程侧完成，请在 E10 查看该流程；CLI 已无 `invoice.issuing.result`，不要尝试用 `QYS-{formDataId}` 查开票结果。
+- 用户中途说"取消 / 不开了" → 立即停止；草稿已创建时告知可在 E10 通过链接删除。
+
+## 命令
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json invoice run invoice.issuing.qys.list --input-json '{"contractNo":"20266105586"}'
+weaver-work-cli --json workflow run workflow.createForm --input-json '{"workflow":["契约锁合同收款发票开具及快递申请(100003460000001852)"]}'
+cat > ./issuing-request.json <<'JSON'
+{
+  "context": "<createForm 返回的 continuation>",
+  "requestName": "开票申请-深圳市康哲药业有限公司-20266105586",
+  "action": "draft",
+  "data": {
+    "main": {
+      "100003720000056343": "20266105586",
+      "100003720000056262": "深圳市康哲药业有限公司2026年度维护(1327967410806063252)",
+      "100003720000056342": "契约锁",
+      "100003720000056255": "2026-10-23",
+      "100003720000056250": "2026-11-30",
+      "100003720000118915": "20266105586",
+      "100003720000056252": "合同20266105586（深圳市康哲药业有限公司2026年度维护）年度维护费全额开票，金额5900元"
+    },
+    "details": {"100003690000001811": [{
+      "100003720000118901": "5900"
+    }]}
+  }
+}
+JSON
+weaver-work-cli --json workflow run workflow.createRequest --input ./issuing-request.json
+```
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.issuing.qys.list --input-json '{"contractNo":"20266105586"}'
+weaver-work-cli --json workflow run workflow.createForm --input-json '{"workflow":["契约锁合同收款发票开具及快递申请(100003460000001852)"]}'
+Set-Content -Encoding utf8 -LiteralPath .\issuing-request.json -Value @'
+{
+  "context": "<createForm 返回的 continuation>",
+  "requestName": "开票申请-深圳市康哲药业有限公司-20266105586",
+  "action": "draft",
+  "data": {
+    "main": {
+      "100003720000056343": "20266105586",
+      "100003720000056262": "深圳市康哲药业有限公司2026年度维护(1327967410806063252)",
+      "100003720000056342": "契约锁",
+      "100003720000056255": "2026-10-23",
+      "100003720000056250": "2026-11-30",
+      "100003720000118915": "20266105586",
+      "100003720000056252": "合同20266105586（深圳市康哲药业有限公司2026年度维护）年度维护费全额开票，金额5900元"
+    },
+    "details": {"100003690000001811": [{
+      "100003720000118901": "5900"
+    }]}
+  }
+}
+'@
+weaver-work-cli --json workflow run workflow.createRequest --input .\issuing-request.json
+```
+
+## 注意
+
+- 台账里的合同号、购方、税号、金额、税率按原值使用，**不改写、不补位、不格式化**。
+- 本链路不读取、不上传任何附件或图片；用户另外提供文件要求"按文件开票"时，说明当前只支持按契约锁台账发起开票流程，需先把数据录入台账。
+- 一次只发起一组（一张流程）；用户要求多份合同一起开时，逐组走 Step 3～6，每组各调一次 `createForm`，`continuation` 不跨组复用。
+- 写请求已发出但结果不确定时按 SKILL.md「写操作失败处理」处理，**禁止重放 `createRequest`**。