Kingdee Data Exporter

许可与使用范围

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

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

商业授权申请：https://littlebeaver.top （邮箱 yk.niu@outlook.com）

金蝶云星空数据导出

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

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

🚀 首次使用：三步跑通

第 1 步：安装依赖

python -m pip install -r requirements.txt

第 2 步：配置连接（推荐方式一）

方式一：写用户级配置文件（技能升级/重装不会覆盖，也不会被误打包分发）

创建 ~/.workbuddy/kingdee/config.json（Windows 为 C:\Users\<你>\.workbuddy\kingdee\config.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 切换：

{
  "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 步：连接自检

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 时打印完整异常堆栈。
• 不启动子进程；除上述范围外不访问其他网络与文件；本技能只读，不写回金蝶任何数据。

常用命令

推荐流程

1. 查看支持内容

python data_exporter.py --show-config

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

2. 获取组织编码

python data_exporter.py --list-orgs

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

3. 按条件导出

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

只导出一种单据或报表：

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

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

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

全组织导出：

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

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

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

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

追加官方字段

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

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

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

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 靠它复用本技能，不必各自实现取数逻辑：

# 取全字段（自动读取该对象的完整字段清单）
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

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

⛔ 能力边界与已知限制

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

🔧 排障：一表定位

首选动作永远是：python data_exporter.py --doctor

需要完整判读表与查询实战（去重口径、状态码字典、分页）时，读：

• references/error-playbook.md
• references/query-cookbook.md

💬 常见对话示例

结果检查

导出完成后：

1. 向用户说明生成文件的完整路径。
2. 检查所需工作表是否存在、是否有数据。
3. 若结果为空，依次核对日期、组织权限、单据状态和 --only 名称。
4. 不读取或展示超出用户请求范围的敏感业务数据。