Kingdee K3cloud

金蝶云星空 ERP 操作技能

通过 MCP 工具与金蝶云星空 API 交互的核心指南。查询前务必先查阅本文件确认表单ID和字段命名规则，避免 500 错误。

> 前提条件：本 Skill 需配合金蝶云星空 MCP Server 使用，推荐 kingdee-k3cloud-mcp。确保 Claude Code 已配置好 MCP Server 并可访问 query_bill_json、view_bill 等工具。

---

核心原则

1. 分步查询：先用 query_bill_json 查列表（关键字段），再用 view_bill 看单条详情
2. 日期过滤：半开区间 FDate >= 'YYYY-MM-DD' AND FDate **关键限制**：金蝶 ExecuteBillQuery` 单次最多返回约 2000 行；MCP tool-result 上限 1MB。

> 查询结果中带有 "truncated": true 则说明数据被截断，必须继续翻页或分片。

决策树

① 时间跨度 > 1 周，或不确定数据量
   → 先 count_bill(form_id, filter_string) 估算行数

② estimated_rows ≤ 500（is_exact=true）
   → 一次性 query_bill_json，top_count=500

③ estimated_rows ≤ 2000（is_exact=true）
   → 一次性 query_bill_json，top_count=2000

④ estimated_rows > 2000 或 is_exact=false（≥ 5000）
   → 优先调用（mcp ≥ 1.2.0）：
       query_bill_range(
           form_id, field_keys,
           date_field="FDate", date_from="YYYY-01-01", date_to="YYYY+1-01-01",
           chunk="month", output_path="/tmp/output.ndjson"
       )
   → 兜底做法（mcp = 'YYYY-MM-01' AND FDate  20 行
   → 必须写入 Excel / CSV 文件，不要把大量数据倾倒进对话
   → 使用 query_bill_to_file 或 query_bill_range(output_path=...) 直接落盘

⑥ 查询中途出 SESSION_EXPIRED
   → 只重试当前片，已翻过的月份无需重跑

推荐做法（mcp ≥ 1.2.0）— 直接落盘，无需手动循环

# 跨年查询，按月自动分片，流式写入本地文件
query_bill_range(
    form_id="SAL_SaleOrder",
    field_keys="FBillNo,FDate,FCustId.FName,FAllAmount",
    date_field="FDate",
    date_from="2025-01-01",
    date_to="2026-01-01",
    chunk="month",
    output_path="/tmp/sales_2025.ndjson"
)
# 返回：{"path": "/tmp/sales_2025.ndjson", "row_count": N, "bytes": M, "chunks": 12}

兜底翻页示例（mcp = '2025-03-01' AND FDate 2000 | count_bill 探测，按需翻页 |

| 跨季度 | 大概率 > 2000 | query_bill_range(chunk="month", output_path=...) 落盘（mcp ≥ 1.2.0），兜底：按月手动循环 | | 跨年 | 必然 > 2000 | query_bill_range(chunk="month", output_path=...) 落盘（mcp ≥ 1.2.0），兜底：按月手动循环 |

---

表单ID速查表

基础数据

| 中文名称 | 表单ID | 备注 | |---------|--------|------| | 物料 | BD_MATERIAL | | | 客户 | BD_Customer | 详见 references/customer-query-guide.md | | 供应商 | BD_Supplier | | | 组织 | ORG_Organizations | | | 部门 | BD_Department | | | 员工 | BD_Empinfo | |

销售模块

| 中文名称 | 表单ID | 备注 | |---------|--------|------| | 销售订单 | SAL_SaleOrder | | | 销售出库单 | SAL_OUTSTOCK | 不是 STK_OutStock | | 发货通知单 | SAL_DELIVERYNOTICE | |

采购模块

| 中文名称 | 表单ID | 备注 | |---------|--------|------| | 采购订单 | PUR_PurchaseOrder | | | 采购入库单 | STK_InStock | 非 PUR_ReceiveBill（该ID返回空） | | 采购申请单 | PUR_Requisition | |

库存/财务

| 中文名称 | 表单ID | 备注 | |---------|--------|------| | 库存明细 | STK_Inventory | 非物料档案，字段不同 | | 其他入库单 | STK_InStock | | | 其他出库单 | STK_OutStock | 注意：销售出库是 SAL_OUTSTOCK | | 调拨单 | STK_TransferDirect | | | 凭证 | GL_VOUCHER | | | 收款单 | AR_receiveBill | | | 付款单 | AP_PAYBILL | |

---

字段命名规则

• 所有字段以 F 开头，区分大小写
• 关联字段加后缀获取属性：FCustId.FName（名称）、FCustId.FNumber（编码）
• 表体明细：query_bill_json 返回行级展开数据，同一 FBillNo 可能出现多行
• 自定义字段：以 F_ + 前缀开头（各部署不同），可用 query_metadata 发现，详见 references/verified-fields.md

通用字段（所有单据可用）

| 字段名 | 含义 | |--------|------| | FBillNo | 单据编号 | | FDate | 单据业务日期 | | FCreateDate | 系统创建时间 | | FDocumentStatus | 状态（Z/A/B/C/D） | | FCreatorId.FName | 创建人 | | FApproverId.FName | 审核人 | | FApproveDate | 审核日期 |

---

常用操作速查

查询元数据（验证字段名）

query_metadata(form_id="SAL_SaleOrder")

从返回结果中提取：Key = 可用字段名，MustInput=1 = 必填字段，IsViewVisible=false = 已废弃/隐藏字段，Extends = 枚举合法值。

查询列表

query_bill_json(form_id="SAL_SaleOrder", field_keys="FBillNo,FDate,FCustId.FName,FDocumentStatus", filter_string="FDate >= '2026-03-01' AND FDate  首次使用时建议先调用 `query_metadata` 探索各表单的实际字段，再参考本 Skill 的字段清单。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [adamzhang1987](https://github.com/adamzhang1987)
- **Source:** [adamzhang1987/kingdee-k3cloud-skill](https://github.com/adamzhang1987/kingdee-k3cloud-skill)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.