本项目采用「小河狸工作室非转售许可 1.0」—— 个人使用与企业内部使用免费（含内部办公、财务与会计处理、内部系统集成）； 对外销售、集成进收费产品或服务、托管 / SaaS / 代运营、以及向第三方交付成果或提供服务，须事先取得书面授权。 许可全文见 LICENSE。商业授权：https://littlebeaver.top
把金蝶云星空中的单据和报表批量导出为一个多工作表 Excel 文件。适合需要定期取数、经营分析、财务核对或给其他 AI Skill 提供数据的中文用户。
- 按日期和组织导出数据
- 一次导出多个单据或报表
- 使用中文名称或
form_id精确选择内容 - 查询全部组织编码
- 连接自检：六步定位"依赖/配置/网络/账套/登录/权限"到底卡在哪
- 账套自动发现：不用问实施商要账套 ID，只填账套名称即可
- 对象探查：列子系统 → 列业务对象（含 FormId）→ 体检能否取数，清单外的对象也能定位
- 按已保存的方案导出：金蝶列表里存好的过滤方案（条件 + 显示列 + 排序）一条命令原样复用
- 字段核对：查出某个单据在当前账套的权威字段清单，避免猜字段
- 追加官方字段说明中的字段（支持直接写中文名）
- 导出全组织数据后再按条件筛选
- 交付友好的 Excel：表头加粗、首行冻结、列宽自适应、自动筛选
- 审计日志：每次取数留一行元数据记录（时间/对象/行数），不记业务内容
依赖只有两个：
pandas+openpyxl。网络、加密、日期全部走 Python 标准库， 不需要requests/python-dateutil—— 受控内网装不上轮子时这一条很关键。
目前覆盖销售、采购、库存、应收应付、收付款、费用、资金、总账和三大财务报表等常用数据。实际清单以这条命令为准：
python data_exporter.py --show-configpython -m pip install -r requirements.txt推荐：配置向导（弹窗，明文不落盘）
python setup_credentials.py弹窗里只需填 3 项：公司名（账套名称）、用户名、密码。凭据用 Windows 系统加密（DPAPI）
保存到 ~/.workbuddy/kingdee/credentials.bin —— 绑当前 Windows 用户，同机其它用户读不出、
拷到别的机器解不开、不在任何 git 仓库内。不写明文、不进对话记录、不落日志。
只看状态不开窗：python setup_credentials.py --check；改密码：--change-key（要求输两次，避免打错撞锁号）
不需要用户装 Python 或 tkinter：当前解释器没带 tkinter 时，先找本机已装的另一个 Python，
再不行就用内置的原生 Windows 表单（win32_form.py，纯 ctypes），最后才降级成文字向导 ——
全程零安装。窗口关掉 = 没有保存（退出码 10），不会被当成配置成功。
这份凭据全系列共用：分析类技能、报销助手都读它，谁都不另存一份；发票云密钥不在这个文件里
（在 piazzone.bin，归报销助手自己管），所以两边不会互相覆盖。
从旧版明文迁移：若本机已有 ~/.workbuddy/kingdee/config.json（密码明文），跑一次向导即可 ——
读入旧值 → 加密保存 → 默认勾选删除该明文文件 → 提示到金蝶后台修改一次密码。
备选：写用户级配置文件（旧版写法，兼容保留，不推荐）
~/.workbuddy/kingdee/config.json（Windows：C:\Users\<你>\.workbuddy\kingdee\config.json）
{
"base_url": "https://你的域名/k3cloud/",
"acct_name": "账套名称",
"username": "取数账号",
"password": "密码"
}- 账套 ID 不用自己找 —— 只填
acct_name（账套名称）会自动解析；想直接填acctid就先跑--list-datacenters。 - 也可以用环境变量
KINGDEE_BASE_URL/KINGDEE_ACCTID/KINGDEE_ACCT_NAME/KINGDEE_USERNAME/KINGDEE_PASSWORD。⚠️ 环境变量不会被误提交进 git，但本地并不保密（同用户其它进程可读、会进日志与崩溃转储）； 本机保密请用上面的向导。 - 兼容旧写法：复制
config.example.py为config.py并填写。 - 需要多个账套时用
profiles结构 +KINGDEE_PROFILE切换，详见SKILL.md。
读取优先级：环境变量 > 系统加密凭据 > 明文 config.json > 技能目录 config.py。
🔐 无论哪种方式，都不要把真实账号、密码或账套 ID 提交到公开仓库。
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-configpython data_exporter.py --list-orgs生成的组织列表中：
number：组织编码，用于--orgname：组织名称
python data_exporter.py --start 2026-06-01 --end 2026-06-30 --org ORG001使用中文名称：
python data_exporter.py --start 2026-06-01 --end 2026-06-30 --org ORG001 --only 销售出库单使用 form_id：
python data_exporter.py --start 2026-06-01 --end 2026-06-30 --org ORG001 --only SAL_OUTSTOCK多个组织或多个项目使用英文逗号分隔：
python data_exporter.py --org ORG001,ORG002 --only SAL_OUTSTOCK,AR_receivablepython data_exporter.py --org all --only 应收单
⚠️ 全组织数据可能很多，建议同时使用--only缩小范围。
财务每月结账的取数条件（组织、期间、单据类型）几乎不变，把这套组合存成命名模板，下个月直接调，不用每个月重新说一遍参数。模板只存「取什么 / 给谁」，不存凭据。
# 保存当前参数组合为模板（period 用相对期间，模板才能长期有效）
python data_exporter.py --only SAL_OUTSTOCK --org 101 --period last-month --output-dir D:/月结 --save-query 月结销售出库
# 下个月直接调用，期间自动往前滚一个月
python data_exporter.py --query 月结销售出库
# 查看已保存的模板
python data_exporter.py --list-queries--period支持：last-month/this-month/last-quarter/this-quarter/last-year/this-year/YYYY-MM（该月整月）。务必用相对期间，固定日期的模板第二个月就失效。- 模板文件在
~/.workbuddy/kingdee/queries.json，可手改、可进 git 与同事共享。 - 还没填凭据、想先看「这个对象会导出哪些列」？用
--preview-fields（读本地字段说明，不联网）：
python data_exporter.py --preview-fields SAL_OUTSTOCK # 按 FormId
python data_exporter.py --preview-fields 销售出库单 # 或按中文名在金蝶列表页【过滤】→ 设好条件 →【保存方案】存下来的方案（比如应收单的「日报表」）， 可以直接拿来取数：条件、显示列、排序全套照搬，不用在命令行重复描述一遍。
# 看这个对象下有哪些方案（中文表单名也认）
python data_exporter.py --list-schemes 应收单
# 按方案导出
python data_exporter.py --form-id AR_receivable --scheme "日报表" --output-dir D:/取数
# 方案名全账套唯一时，--form-id 也可以省（自动定位表单）
python data_exporter.py --scheme "日报表"- 方案存在金蝶基础对象
BOS_FilterScheme里，<FilterSetting>的结构就是取数接口FilterString的原生结构， 所以是原样透传，不去翻译63/92/105/106这类比较符编码 —— 翻译表猜错就是静默错数。 - 同一字段的多选状态（比较符 106 = 属于）会合并成一次
IN，与界面口径一致。 - 方案里有本账套已删的列会自动跳过并提示；同名方案有多个用
--scheme-index选。 - 与
--query模板的区别：--query存的是本工具的参数组合（~/.workbuddy/kingdee/queries.json），--scheme读的是金蝶里的方案 —— 财务在金蝶改一次，下次取数立刻生效。 ⚠️ 只对单据类对象有效；报表的方案是版式方案，不能当列表过滤条件用（代码会提前拦下提示，改走--only）。
field-docs/ 保存了各类单据和报表的字段参考（每个对象一个文件，按 FormId 命名，如 AR_receivable.txt）。需要临时增加默认未导出的字段时，使用 --fields：
python data_exporter.py --only AR_receivable --fields "AR_receivable:FNOINVOICEAMOUNT"也支持直接写中文名（对照表里有的字段）：
python data_exporter.py --only 应收单 --fields "应收单:价税合计"目录用 ASCII 文件名（FormId）而不是中文名，是为了压缩包跨系统解压时不出现乱码。 2.3.x 及更早的
官方字段说明/<中文名>.txt布局仍然兼容，代码会自动回退。
Windows 控制台遇到中文参数编码问题时，优先使用字段 key。
限制银行存款流水账的银行账号时，在本地 config.py 中填写：
KINGDEE_CONFIG["bank_account_numbers"] = ["银行账号1", "银行账号2"]财务报表默认按导出期间生成月报，并拆分为资产负债表、利润表和现金流量表。需要季报、半年报或年报时，在 KINGDEE_CONFIG["financial_report"] 中调整 CycleType：
4：月报5：季报6：半年报7：年报
合并报表还需要根据本企业的云星空报表模板，补充报表编号、会计体系、会计政策和合并范围等参数。
收票单、银行存款流水账 等项目的可选字段，均可在 field-docs/ 中查看。
凭证、资产卡片、即时库存、二开单据这些不在内置清单里的对象，用 --form-id 取数即可，
前提是知道 FormId。不知道就走这条链：
python data_exporter.py --list-subsystems # ① 有哪些模块（GL / AR / STK …）
python data_exporter.py --list-objects --object-sub GL # ② 该模块下有哪些对象
python data_exporter.py --list-objects --object-kw 凭证 # ③ 只知道名字就跨模块搜
python data_exporter.py --test-form GL_Voucher # ④ 体检：元数据 + 取数两关
python data_exporter.py --form-id GL_Voucher --filter-string "FDate>='2026-09-01'" # ⑤ 取数两个容易踩的点：
- 别按 FormId 前缀猜模块。动态建模生成的对象 FormId 是数字码或 GUID，不带
GL/AR前缀， 按前缀筛会漏一大片。子系统归属存在FSubSystemId里，用--object-sub才筛得全。 - 在册 ≠ 能取数。注册表里混着单据转换规则、打印模板等非表单对象，
--form-id一定失败。 所以第 ④ 步不能省，--test-form会分开告你卡在「元数据」还是「取数」。
清单可落盘成 JSON，便于脚本化：
python data_exporter.py --list-objects --object-sub AR --json-out ar_objects.json每次导出、导出失败、登录失败都会在 ~/.workbuddy/kingdee/audit.log 追加一行 JSON：
{"ts": "2026-10-17 19:02:47", "action": "export_form", "version": "2.4.1",
"form": "BD_MATERIAL", "rows": 2908, "output": "BD_MATERIAL_BD_MATERIAL_20261017_190246.xlsx"}只记元数据（时间 / 动作 / 对象 / 组织 / 行数 / 成功与否），不记业务数据内容、不记账号密码。
目的是事后能回答「这批数据是什么时候、导了哪个对象、多少行、成功与否」。
不记录账号名 —— 按本技能的原则「真实账号不进任何日志」，要追到人请结合操作系统的登录审计。
不需要就设 KINGDEE_AUDIT=0 关掉。
按组织和单据类型筛选：
python scripts/filter_export_excel.py --input "导出文件.xlsx" --org ORG001 --bill-type "应收单"只处理一个工作表：
python scripts/filter_export_excel.py --input "导出文件.xlsx" --sheet "应付单" --org ORG001默认会在原文件旁生成带 _filtered 后缀的新文件。
仓库采用“一个仓库一个 Skill”的通用结构，SKILL.md 位于仓库根目录：
KingdeeDataExporter/
├── SKILL.md
├── README.md
├── CHANGELOG.md
├── data_exporter.py
├── setup_credentials.py
├── win32_form.py # 原生 Windows 表单（纯 ctypes，缺 tkinter 时用）
├── credstore.py
├── config.example.py
├── requirements.txt
├── scripts/
├── references/
└── field-docs/ # 字段参考，按 FormId 命名（ASCII 文件名）
支持从 GitHub 扫描 Skill 的工具，可以直接使用仓库地址：
https://github.com/LittleBeaverStudio/KingdeeDataExporter
识别后可这样发起任务：
请使用 kingdee-data-exporter，先帮我查询组织编码，再导出上个月的销售出库单。
能递归扫描 SKILL.md 的 SkillHub 或桌面管理器可以直接识别本仓库。若平台要求上传压缩包，请压缩整个仓库，并确认解压后根目录中仍有 SKILL.md。
python data_exporter.py --doctor会逐步判定 运行环境 → 配置 → 服务器连通 → 账套定位 → 登录 → 取数冒烟，哪一步失败就给哪一步的修复动作。
最常见的两种：WebAPI 白名单没配（报 MsgCode 11，与账号密码无关）和 密码大小写错。
（openpyxl 缺失会在第 0 步就报出来 —— 否则要等到最后写 Excel 才炸，最难排查。）
完整判读表见 references/error-playbook.md。
⚠️ 密码连续错约 5 次会锁账号。本工具判读为凭据问题时不自动重试，连续 2 次即中止。
python data_exporter.py --list-datacenters这个接口免账号密码，第 1 列就是 acctid。或者干脆只填 acct_name，由脚本自动解析。
python data_exporter.py --list-orgs注意区分：账套（acctid，一台服务器上的一个数据中心）≠ 组织（账套内的核算组织，--org 用的编码）。
python data_exporter.py --show-configpython data_exporter.py --inspect-fields ER_ExpReimbursement --filter 发票这是当前账套的权威字段清单，查不到就说明该字段确实不存在，不要继续猜。
本 Skill 不需要任何环境变量。 凭据在 python setup_credentials.py 的弹窗里填一次，用 Windows DPAPI 加密存到
~/.workbuddy/kingdee/，跟环境变量无关。KINGDEE_BASE_URL / KINGDEE_USERNAME 这类环境变量只是「不想写配置文件时可以代替」的可选项。
如果你在别处看到 export PATH="$HOME/.local/bin:$PATH"，那是 SkillHub 命令行工具自己的安装目录不在 PATH 里，
和取数没有关系；只有手工跑过 SkillHub 的 install.sh 才需要补，写进 ~/.bashrc 可永久生效。
用 WorkBuddy 里的一键安装不需要管这一行（Skill 会落到 ~/.workbuddy/skills/）。
python data_exporter.py --check-update版本检查默认关闭，只有 --check-update 会访问 GitHub Releases API，日常导出不产生额外网络请求。
SKILL.md AI 执行说明与触发描述
README.md 中文使用介绍
CHANGELOG.md 版本变更记录
data_exporter.py 主程序
setup_credentials.py 凭据向导（DPAPI 加密）
credstore.py 凭据存取
config.example.py 安全配置示例
requirements.txt Python 依赖（仅 pandas + openpyxl）
scripts/ Excel 二次处理脚本
field-docs/ 金蝶字段参考（按 FormId 命名）
references/ 排障手册与查询实战
error-playbook.md 错误判读与自愈（含白名单配置路径）
query-cookbook.md 载荷格式、去重口径、状态码、场景配方
agents/openai.yaml AI 客户端展示信息
本工具仅用于你有权访问的金蝶环境。使用者需要自行负责凭据保管、权限控制和数据合规。