KingdeeExpenseFlowSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

python --version   # 需要 3.8 或更高

python data_exporter.py --doctor

{
"base_url": "https://你的域名/k3cloud/",
"acct_name": "账套名称",
"username": "集成账号",
"password": "密码"
}

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: kingdee-expense-flow
slug: kingdee-expense-flow
displayName: 金蝶云星空报销助手
version: 2.1.0
summary: 小河狸工作室出品:金蝶云星空费用/差旅报销全流程提交,员工不登录金蝶也能报销。
description: 小河狸工作室出品。金蝶云星空「费用/差旅报销全流程」提交 Skill:员工无需登录金蝶,在对话里把发票交上来,agent 用纯 WebAPI 完成「费用申请单 → 下推报销单 → 挂收票信息/传附件 → 提交审批」,差旅线结构同构。内置发票 OCR 清晰度与抬头校验、收票信息 vs 附件分流(行程单双算预警)、跨组织挂票硬拦截、收票池账号可见性隔离、**提交硬闸门(v2.0.11 起:收票 0 行 / 无发票云流水号 / 跨组织 / 发票合计 < 报销额,四条硬拦,无任何绕过参数)**、按发票金额调低报销额(fit,唯一的合规出路)、**agent 服务端上传发票并建收票单(v2.1.0:替代界面「发票导入单据」,员工零操作)**、单一登录入口(ValidateUser)、收票单权限配置指引、提交前体检、报销制度提醒。
license: 小河狸非转售许可 1.0(企业内部使用免费,转售收费需授权)
tags: [金蝶云星空, 费用报销, 差旅报销, 财务自动化, WebAPI, 发票]
metadata:
  version: 2.1.0
  author: 小河狸工作室
  tags:
    - 金蝶云星空
    - 费用报销
    - 差旅报销
    - 财务自动化
    - WebAPI
    - 发票
---

## 许可与使用范围

本 Skill 采用「小河狸工作室非转售许可 1.0」,完整条款见本目录 `LICENSE` 文件。

- ✅ **免费使用**:
  - 个人学习、研究或个人事务;
  - **企业内部使用**——某一组织(无论是否为营利单位)为**其自身**业务运营而使用,包括内部办公、内部财务与会计处理、内部管理与报表、内部系统集成;同一控股关联实体使用视同内部使用。
- ✅ 可为上述用途自行修改本 Skill。
- ❌ **须另行取得书面授权**:对外销售、出租、许可;集成进对外收费的产品或服务;托管 / SaaS / 代运营;打包进收费课程、付费社群或付费安装包;收费的实施与咨询培训;**以及利用本 Skill 向任何第三方交付成果或提供服务**(含代理记账、为客户提供账目或报表服务等)。
- 📌 **区分标准只有一条**:**是否以本 Skill 向本组织之外的第三方交付成果或提供服务**。仅为自身业务使用 → 免费;向第三方交付或服务 → 需授权。
- 📌 再分发须保留本许可、版权声明与来源:小河狸工作室 LittleBeaverStudio · https://littlebeaver.top

**商业授权申请**:https://littlebeaver.top (邮箱 [email protected])


> ⚠️ 字段说明:`slug` / `displayName` / `version` / `summary` / `tags` 是 **SkillHub(skillhub.cn)发布**要求的顶层字段
> (CLI 校验必须有 `slug`+`version`+`displayName`,否则 `skillhub publish` 直接 die);
> `name` + `metadata` 是 **agentskills** 规范要求的。两套并存,互不影响。

# 金蝶云星空报销助手

> 小河狸工作室出品 | 覆盖「费用 / 差旅」两条报销线的**全流程提交**:申请单 → 下推报销单 → 挂发票 → 提交审批。

> **关于平台「需配置 API Key」标签**:本 Skill **不需要申请任何 API Key**。
> 它使用**你自己的金蝶云星空账号**提交单据,只填一次连接信息即可;
> 若已安装 `kingdee-data-exporter`,**两者共用同一份配置,不需要重复填写**,
> 也不必去任何开放平台申请密钥。只填**账套名称**即可,账套 ID 会自动解析。
> 配置方法与自检见下方「安装与配置」。

本 skill 处理**写操作**(提交单据、下推、创建收票单、上传附件、提交审批),与只读导出的 `kingdee-data-exporter` 互补。

## 安装与配置

### 1. 依赖

```bash
python -m pip install -r requirements.txt
```

本 skill 的 `helpers/` 全部是**纯标准库**(含 `recvin_link.py`),核心写票功能无需第三方包。

### 2. 连接配置:通常**不需要你做任何事**

本 skill **不单独保存账号密码**,也没有独立的配置项。只要机器上已经装好并配置过
[`kingdee-data-exporter`](https://github.com/LittleBeaverStudio/KingdeeDataExporter),
本 skill 会**自动复用它的连接配置**,不需要重复填写。

确认是否已就绪 —— 在导出技能目录执行(五步全绿即可):

```bash
python data_exporter.py --doctor
```

> 为什么本 skill 自己也要读一次凭据?因为它要做**写操作**(提交单据、下推、挂传附件),
> 而导出技能是**只读**的、不提供写接口。所以连接动作必须自己完成,
> 但读的是**同一份配置**,用户不需要多填任何东西。

### 3. 只有这几种情况才需要自己配

| 情况 | 做法 |
|---|---|
| 没装导出技能,想单独用本 skill | 写 `~/.workbuddy/kingdee/config.json`(见下方),只填账套名称即可 |
| CI / 无人值守环境 | 用环境变量 `KINGDEE_BASE_URL` / `KINGDEE_ACCTID`(或 `KINGDEE_ACCT_NAME`)/ `KINGDEE_USERNAME` / `KINGDEE_PASSWORD` |
| 已经在用导出技能的 `config.py` 旧写法 | **无需操作**,本 skill 同样兼容 |

自己配的话,写这个(`~/.workbuddy/kingdee/config.json`,技能目录之外,升级不覆盖):

```json
{
  "base_url": "https://你的域名/k3cloud/",
  "acct_name": "账套名称",
  "username": "集成账号",
  "password": "密码"
}
```

不需要自己找账套 ID —— 只填账套名称,脚本会自动解析;想列出来看看就跑一次
(这个接口**免账号密码**):

```bash
python data_exporter.py --list-datacenters
```

### 4. 连不上时

优先跑导出技能的 `--doctor`,它会逐步定位是配置、网络、账套、登录还是权限问题。

**WebAPI 白名单未配**是最常见的(报 `MsgCode 11`,**与账号密码无关**):
让金蝶管理员在「基础管理 → 公共设置 → 参数设置 → 基础管理 → BOS平台 → WebAPI →
「允许调用WebAPI接口用户」」加入取数账号。

> ⚠️ 密码连续错约 5 次会锁账号,本 skill 不做自动重试。

## 四种单据与下推关系(formid 已实测/已确认)

| 单据 | formid | 下推目标 | 状态 |
|---|---|---|---|
| 费用申请单 | `ER_ExpenseRequest` | → 费用报销单 `ER_ExpReimbursement` | ✅ 已跑通 |
| 费用报销单 | `ER_ExpReimbursement` | (终态,提交审批后付款) | ✅ 已跑通 |
| 出差申请单 | `ER_ExpenseRequest_Travel` | → 差旅费报销单 `ER_ExpReimbursement_Travel` | ✅ 创建→提交→审核 已跑通 |
| 差旅费报销单 | `ER_ExpReimbursement_Travel` | (终态,提交审批后付款) | 🟡 实体结构与费用单**完全同构**;下推→挂票→改明细→写联动→传附件→体检**全通过**,仅 Submit 待实跑 |

> ⚠️ formid 拼写极敏感:`ER_ExpReimbursement`(正确,无多余 s)vs `ER_ExpenseReimbursement`(错误,曾因此误判"单据不存在")。ExecuteBillQuery 查不到某单据时,先怀疑 formid 拼错或账号无该表单权限,不要直接认定"没部署"。

## 核心概念:报销单上"收票信息"与"附件"是两个位置(最易踩坑)

| 位置 | 单据体/接口 | 用途 | 参与金额校验? |
|---|---|---|---|
| **收票信息** | 报销单 `RecInvInfo` 单据体 → 链接收票单 `IV_ReceivedInvoice` | **上传发票**(上传完自动进收票单) | ✅ 是,"发票金额≥报销金额"校验读这里 |
| **附件** | `AttachmentUpLoad`(一步挂单)/ `UploadFile`+`BOS_Attachment` Save | 行程单、补充说明等 | ❌ 否 |
| **联动表** | 报销单 `FReimbAndRecInvInfo` 单据体 | 「明细 ↔ 发票分录」对应关系(= UI「合并生成费用明细」的底层) | ❌ 否,但决定明细是否"与发票一致" |

- 校验报错"发票金额不允许小于报销金额" = 收票信息里**没有**有效的收票单(发票没传对位置,或被传到了附件)。
- `FEInvoiceEntity` 是报销单另一个发票子表,**不是**收票信息,历史单多为空,不要往这里填发票来绕过校验。

## 标准流程(费用申请单 → 报销单)

1. **提交费用申请单**:Save `ER_ExpenseRequest`(模板见 `references/field_cookbook.md`,含 F_TJKT_Base_qtr 项目必填等坑)。默认"仅保存暂存",确认后再 Submit。
2. **下推报销单**:Push `ER_ExpenseRequest` → `ER_ExpReimbursement`(`TargetFormId` 必填,启用默认规则)。生成报销单(草稿 Z,BillNo 空)。
3. **发票先"找"再"建"**(顺序很重要):
   - **优先查**:`helpers/recvin_link.py find <发票号码>` 在金蝶收票池 `IV_ReceivedInvoice` 里找收票单。
     ⚠️ **池子里有没有票,取决于"这张票有没有被采集过一次"** —— 别假设系统会自动把它收进来
     (每日"下载"要**电子税务局手机验证码**,无法自动化)。查不到就走下面第 5 条。
   - **查不到 → 直接服务端上传建票**(v2.1.0 起,**员工零操作**):
     `python helpers/recvin_link.py create-recvin <发票文件> --bill-fid <FID> --org 101 --item-name "..." --link <FID>`
     (上传 → 拿到真流水号 → 建收票单 → 挂单,一步到位;详见「📥 发票从哪来」)。
     ⛔ **不要"手工建票兜底"**:凭空建的票没有发票云流水号,v2.0.11 起会被提交硬闸门拦住。
4. **把发票挂进「收票信息」**(**已打通,纯金蝶 WebAPI**,不必用发票云/客户端):
   ```bash
   python helpers/recvin_link.py link <报销单FID> <收票单号>            # 追加
   python helpers/recvin_link.py link <报销单FID> <收票单号> --replace  # 覆盖
   python helpers/recvin_link.py clear <报销单FID>                     # 清空
   python helpers/recvin_link.py precheck <报销单FID>                  # 提交前体检
   python helpers/recvin_link.py set-contact <报销单FID> <员工号>       # 补往来单位
   python helpers/recvin_link.py submit <报销单FID>                    # 提交(带体检)
   python helpers/recvin_link.py verify <报销单FID> <收票单号>          # 一键自检
   ```
   写法要点:`Model = {"FID":.., "FRecInvInfo":[{"FRecInv":{"FBillNo":"<收票单号>"}}]}`
   —— 字段**必须放在 `FRecInvInfo[]` 数组行内**,放单据头会报 `实体不存在此属性![EntityType:BillHead]`。
   详见 cookbook §4.2。
   - ⚠️ **防抢关联**:一张收票单只能属于一张报销单,挂到第二张会静默抢走原单的关联。
     `recvin_link.py` 已内置拦截(`--allow-steal` 才放行)。
   - ⚠️ 已审核单据同样可写,操作前先看单据状态,别误改历

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

declared (5 observation(s))

Shell

none-observed

Dependencies

not all pinned

Secrets in source

none-found

Findings (8)

.clawhubignore

same = hashlib.md5(got).hexdigest() == hashlib.md5(raw).hexdigest()

link_code = hashlib.md5(f"{fid}-{recv_fid}".encode()).hexdigest()[:16]

return hashlib.md5(payload.encode("utf-8")).hexdigest()

return hashlib.md5(payload.encode("utf-8")).hexdigest()

return base64.b64decode(fp), res.get("FileSize"), res.get("FileName")

text = gzip.decompress(base64.b64decode(text)).decode("utf-8", "replace")

requests

Gates applied: no_behavioural_pass.