KingdeeDataExporterSAFE

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

python data_exporter.py --show-config

python -m pip install -r requirements.txt

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

python data_exporter.py --doctor      # 先确认接通(配置→连通→账套→登录→取数冒烟)
python data_exporter.py               # 再导出

python data_exporter.py --help-config

云星空经营数据_2026年07月_20260715_120000.xlsx

python data_exporter.py --output-dir "D:/secure/kingdee-exports"

python data_exporter.py --show-config

python data_exporter.py --list-

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-data-exporter
slug: kingdee-data-exporter
displayName: 金蝶云星空数据导出
version: 2.2.1
description: 金蝶云星空经营数据导出技能。仅当用户明确要求从金蝶云星空或 K3 Cloud 查询、导出经营数据时使用;支持配置账号、自动发现账套、连接自检、查询组织与可用单据/报表,按期间、组织及单据或报表类型导出多工作表 Excel,也支持追加官方字段、全组织导出、字段核对与结果二次筛选。
license: 小河狸非转售许可 1.0(企业内部使用免费,转售收费需授权)
---

## 许可与使用范围

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

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

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


# 金蝶云星空数据导出

把金蝶云星空中的单据和报表批量导出为一个多工作表 Excel 文件。

> **关于平台「需配置 API Key」标签**:本 Skill **不需要申请任何 API Key**。
> 它使用**你自己的金蝶云星空账号**登录取数,只需填一次连接信息(服务器地址 + 账号 + 密码),
> 不必去任何开放平台申请密钥。配置放在技能目录之外
> (`~/.workbuddy/kingdee/config.json`),升级技能不会覆盖;只填**账套名称**即可,
> 账套 ID 会自动解析。配置方法与自检见下方「首次使用」。

---

## 🚀 首次使用:三步跑通

### 第 1 步:安装依赖

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

### 第 2 步:配置连接(推荐方式一)

**方式一:写用户级配置文件**(技能升级/重装不会覆盖,也不会被误打包分发)

创建 `~/.workbuddy/kingdee/config.json`(Windows 为 `C:\Users\<你>\.workbuddy\kingdee\config.json`):

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

- **账套 ID(acctid)不用自己找** —— 只填 `acct_name`(账套名称),脚本会自动解析成 acctid。
- 想直接填 acctid:先跑 `python data_exporter.py --list-datacenters`,第 1 列就是。
- 需要多个账套时用 `profiles` 结构,并用环境变量 `KINGDEE_PROFILE` 切换:

```json
{
  "default": "公司A",
  "profiles": {
    "公司A": {"base_url": "https://a.ik3cloud.com/k3cloud/", "acct_name": "账套A", "username": "u1", "password": "p1"},
    "公司B": {"base_url": "https://b.ik3cloud.com/k3cloud/", "acct_name": "账套B", "username": "u2", "password": "p2"}
  }
}
```

**方式二:环境变量**(不落盘,适合分发/CI)

`KINGDEE_BASE_URL` / `KINGDEE_ACCTID`(或 `KINGDEE_ACCT_NAME`)/ `KINGDEE_USERNAME` / `KINGDEE_PASSWORD`

**方式三:技能目录内 `config.py`**(早期写法,继续兼容)

复制 `config.example.py` 为 `config.py` 并填写。⚠️ 该文件含明文凭据,**禁止**提交到任何仓库或打进分享包。

### 第 3 步:连接自检

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

五步逐步判定「配置 → 服务器连通 → 账套定位 → 登录 → 取数冒烟」,哪一步失败就给出**具体到操作**的修复建议。**配置完先跑这一步**,比直接导出后猜报错快得多。不确定怎么配时跑 `python data_exporter.py --help-config`。

---

## 工作原则

1. 先确认用户拥有目标金蝶环境和数据的合法访问权限。
2. 不在对话、日志或公开仓库中展示真实账号、密码、账套 ID 或业务数据。
3. 遇到任何"连不上/查不到",先跑 `--doctor` 定位,**不要连续重试登录**(见下方防锁号)。
4. 不确定组织编码时,先运行 `--list-orgs`。
5. 不确定单据或报表名称时,先运行 `--show-config`。
6. 数据量可能较大时,优先使用 `--org` 和 `--only` 缩小范围。

## 权限与行为声明

运行本技能前请知悉其能力范围:

- **网络访问**:
  - 连接 `base_url` 指定的金蝶云星空服务器 —— 登录、取数、以及**免认证的账套列表接口**(`GetDataCenterList`,用于 `--list-datacenters` 与 `acct_name` 自动解析),全部发往同一台用户自己配置的服务器;
  - 仅显式传入 `--check-update` 时访问 GitHub Releases API 查询新版本,**默认不检查、不访问任何第三方服务**。
- **本地文件读写**:
  - 读取配置(环境变量 → `~/.workbuddy/kingdee/config.json` → 技能目录 `config.py`,按此优先级取第一个可用的);
  - 读取 `官方字段说明/` 目录;
  - 默认在当前目录写入导出的 Excel,可用 `--output-dir` 指定;`--inspect-fields --json-out` 时写入指定的元数据 JSON。
- **环境变量**:`KINGDEE_BASE_URL` / `KINGDEE_ACCTID` / `KINGDEE_ACCT_NAME` / `KINGDEE_USERNAME` / `KINGDEE_PASSWORD` / `KINGDEE_PROFILE`;`KINGDEE_DEBUG=1` 时打印完整异常堆栈。
- 不启动子进程;除上述范围外不访问其他网络与文件;**本技能只读**,不写回金蝶任何数据。

## 常用命令

| 命令 | 用途 |
|---|---|
| `--doctor` | 连接自检(配置→连通→账套→登录→取数冒烟),首次配置后必跑 |
| `--help-config` | 打印配置方法 |
| `--list-datacenters` | 列出服务器上的全部**账套**(acctid 来源),免账号密码 |
| `--list-orgs` | 导出**组织**列表(账套内的核算组织,`--org` 用的编码) |
| `--show-config` | 列出可导出的单据与报表(19 单据 + 10 报表) |
| `--inspect-fields <FormId>` | 列出某业务对象的实体与字段全清单(核对字段/排障) |
| `--form-id <FormId>` | 通用取数:导出**任意**业务对象,不限于内置清单 |
| `--check-update` | 检查新版本(**唯一**会访问 GitHub 的选项) |

## 推荐流程

### 1. 查看支持内容

```bash
python data_exporter.py --show-config
```

输出中的 `form_id` 或中文名称都可以传给 `--only`。

### 2. 获取组织编码

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

生成的组织列表中,`number` 是后续 `--org` 使用的组织编码。

### 3. 按条件导出

```bash
python data_exporter.py --start 2026-01-01 --end 2026-01-31 --org ORG001
```

只导出一种单据或报表:

```bash
python data_exporter.py --start 2026-01-01 --end 2026-01-31 --org ORG001 --only 销售出库单
```

多个组织或多个项目使用英文逗号分隔:

```bash
python data_exporter.py --org ORG001,ORG002 --only SAL_OUTSTOCK,AR_receivable
```

全组织导出:

```bash
python data_exporter.py --org all --only 应收单
```

将敏感经营数据保存到用户确认的目录:

```bash
python data_exporter.py --org ORG001 --output-dir "D:/secure/kingdee-exports"
```

不传日期时的默认口径:**每月 1–6 号导出上月整月,7 号及以后导出当月 1 号到今天**。

## 追加官方字段

先在 `官方字段说明/` 中查找字段,再用 `--fields` 追加默认未导出的字段:

```bash
python data_exporter.py --only AR_receivable --fields "AR_receivable:FNOINVOICEAMOUNT"
```

字段不确定是否存在时,用 `--inspect-fields <FormId>` 核对当前账套的**权威**字段清单:

```bash
python data_exporter.py --inspect-fields ER_ExpReimbursement --filter 发票
python data_exporter.py --inspect-fields AR_receivable --json-out meta_AR_receivable.json
```

Windows 控制台出现中文参数编码问题时,优先使用字段 key。

## 通用取数:任意业务对象

内置清单之外的业务对象(凭证 `GL_Voucher`、资产卡片 `FA_Card`、即时库存 `STK_Inventory` 等),
用 `--form-id` 直接取,**不需要改代码**——下游分析类 Skill 靠它复用本技能,不必各自实现取数逻辑:

```bash
# 取全字段(自动读取该对象的完整字段清单)
python data_exporter.py --form-id GL_Voucher --filter-string "FDate>='2026-09-01' and FDate<='2026-09-30'"

# 只取指定字段(先用 --inspect-fields 核对标识)
python data_exporter.py --form-id FA_Card --fields "FNumber,FName,FAssetOrgID"

# 不带过滤条件 = 导出该对象全部数据(注意数据量)
python data_exporter.py --form-id STK_Inventory
```

- 输出仍是 Excel,工作表名自动取该对象的中文名。
- 日期等过滤条件直接写金蝶 `FilterString`,用 `--filter-string` 传入。
- ⚠️ **报表类对象不支持**(如 `GL_RPT_AccountBalance`、`AR_SumReport`)——
  它们不是业务对象,走的是报表接口,请用 `--only` 从内置清单取。

## 二次筛选 Excel

```bash
python scripts/filter_export_excel.py --input "导出文件.xlsx" --org ORG001 --bill-type "应收单"
python scripts/filter_export_excel.py --input "导出文件.xlsx" --sheet "应付单" --org ORG001
```

---

## ⛔ 能力边界与已知限制

> 以下条目均在真实账套实测确认。碰到墙时先对照此表 —— 多数情况是**已知边界**,不是技能坏了。

| 边界 | 说明 |
|---|---|
| **「多级审核信息 / 当前处理人」查不到** 

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 (3 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

.clawhubignore

text = _gzip.decompress(_b64.b64decode(text)).decode("utf-8", "replace")

Gates applied: no_behavioural_pass.