kingdee-k3cloud

name kingdee-k3cloud description Use this skill whenever working with Kingdee K3Cloud ERP system (金蝶云星空). Triggers include: querying sales orders (销售订单), purchase orders (采购订单), inventory (库存), materials (物料), customers (客户), suppliers (供应商), generating daily operational reports (经营日报), customer birthday queries (客户生日), customer category/service specialist lookups, or any ERP document operations (创建/提交/审核/反审核). Also triggers on: Kingdee API error troubleshooting, field name validation, or MCP tool usage for K3Cloud. Keywords: 金蝶, 金蝶云星空, K3Cloud, ERP, 单据, 审核, 提交, 日报, 客户查询, 库存预警. 金蝶云星空 ERP 操作技能 通过 MCP 工具与金蝶云星空 API 交互的核心指南。查询前务必先查阅本文件确认表单ID和字段命名规则，避免 500 错误。 前提条件 ：本 Skill 需配合金蝶云星空 MCP Server 使用，推荐 kingdee-k3cloud-mcp 。确保 Claude Code 已配置好 MCP Server 并可访问 query_bill_json 、 view_bill 等工具。 核心原则 分步查询 ：先用 query_bill_json 查列表（关键字段），再用 view_bill 看单条详情 日期过滤 ：半开区间 FDate >= 'YYYY-MM-DD' AND FDate < 'YYYY-MM-DD+1' FDate vs FCreateDate ： FDate 是业务日期（手填）， FCreateDate 是系统创建时间。按"今天开的单"统计用 FCreateDate 单据状态码 ： Z = 暂存草稿， A = 创建， B = 审核中， C = 已审核， D = 重新审核 控制数据量 ： top_count 限制行数，只查必要字段，超过20行数据考虑创建 Excel 字段不确定时 ：先调用 query_metadata(form_id) 验证字段是否存在，避免试错浪费 token 大数据量查询流程（跨周/跨月/跨年必读） 关键限制 ：金蝶 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 < 1.2.0）： for month in 月份范围: query_bill_json(filter="FDate >= 'YYYY-MM-01' AND FDate < 'YYYY-MM+1-01'", top_count=2000) 若返回 truncated=true → 在该月内继续翻页（start_row=next_start_row） ⑤ 累计行数 > 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 < 1.2.0 或单月数据超过 2000 行） start = 0 while True : result = query_bill_json(form_id, field_keys, filter_string= "FDate >= '2025-03-01' AND FDate < '2025-04-01'" , top_count= 2000 , start_row=start) # result["rows"] → 本页数据 if not result[ "truncated" ]: break start = result[ "next_start_row" ] 时间跨度 vs 推荐策略速查 时间跨度 count_bill 估算 推荐做法 当日 ≤ 200 行 直接 top_count=200 当周 ≤ 1000 行 直接 top_count=1000 当月 可能 > 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 < '2026-03-02'", top_count=50) 查看单据详情 view_bill(form_id="SAL_SaleOrder", number="XSDD2602000001") # 替换为实际单号 创建 → 提交 → 审核 save_bill(form_id, model_data) # 1. 保存 submit_bill(form_id, numbers) # 2. 提交 audit_bill(form_id, numbers) # 3. 审核 批量审核（逗号分隔） audit_bill(form_id="SAL_SaleOrder", numbers="XSDD001,XSDD002,XSDD003") 关键避坑提醒 陷阱 说明 STK_OutStock 当销售出库用 销售出库单是 SAL_OUTSTOCK ，STK_OutStock 会报"业务对象不存在" FAllAmount 直接求和 FAllAmount 是 行级字段 ，同一订单多行会重复，需按 FBillNo 去重 FCustomerID / FCustomerId 不存在，正确写法是 FCustId SAL_OUTSTOCK 中用 FCustId.FName 该表中不存在此字段，会报 500 STK_Inventory 中用 FNumber 不存在，物料编号是 FMaterialId.FNumber STK_Inventory 中用 FAvailableQty / FAuxQty 不存在；可用量是 FAVBQty （主单位），开单可用量是自定义字段 F_JR_FHTZDKYL1 STK_Inventory 中用 FStockDate / FInboundDate 不存在；即时库存视图无入库日期，需关联 STK_InStock 按批号查 FDate BD_MATERIAL 的 FSpecification 含义 本部署中该字段实际存储"物料成分"，非通用"规格型号"；支数字段是自定义字段 F_JR_ZS 弹性字段用 FAUXPROPID__FF100001 等格式 metadata Key 格式，不可用于查询，触发 500；正确格式为 父Key.子FieldName ，如 FAuxPropId.FF100001.FName （色号名称）、 FAuxPropId.FF100002 （缸号）、 FStockLocId.FF100004.FName （仓位名称） 弹性字段直接用父键查询 FAuxPropId 和 FStockLocId 均为弹性父键（ElementType=60523），直接查询触发 500，必须展开到子字段 PUR_ReceiveBill 查采购入库 返回空，应使用 STK_InStock 查询不加 top_count 可能返回数据过大超过 1MB 限制 query_bill_json 返回正好 2000 行直接使用 必须检查 truncated 字段； true 时数据被截断，须继续翻页（ start_row=next_start_row ）或缩小时间范围 用 count_bill 探测后不检查 is_exact is_exact=false 表示实际行数 ≥ 5000，必须用 query_bill_range （mcp ≥ 1.2.0）或手动按月分片，不能一次拉取 References 指引 查询具体模块的字段时， 必须先查阅对应 reference 文件 确认字段名： 场景 参考文件 首次使用、发现自定义字段和仓库配置 references/customization-guide.md 查任意模块的已验证/禁用字段 references/verified-fields.md 生成经营日报 references/daily-report-workflow.md 查询客户信息、生日、类别 references/customer-query-guide.md 遇到 500 错误、1MB 超限、分页问题 references/common-errors.md 按客户/业务员/产品分析销售 references/sales-analysis-workflow.md 库存总览、预警、呆滞分析 references/inventory-analysis-workflow.md 订单全流程追踪、逾期预警 references/order-tracking-workflow.md 生成周报/月报、期间对比 references/periodic-report-workflow.md 自定义配置指南 每个金蝶云星空部署都有自己的业务特征，使用前需要了解： 单号规律 ：用 query_bill_json 查几条样本单据，从 FBillNo 字段识别前缀规律 仓库名称 ：查 STK_Inventory 时先确认 FStockId.FName 的实际值 内部单排除 ：如有内部采购/调拨客户，用 FCustId.FName not like '%内部客户关键词%' 过滤 自定义字段 ：用 query_metadata(form_id="BD_Customer") 找以 F_ 开头的扩展字段（见 references/verified-fields.md 中的示例） DocumentStatus 完整状态 ：Z=暂存草稿 → A=创建 → B=审核中 → C=已审核（终态），D=重新审核 首次使用时建议先调用 query_metadata 探索各表单的实际字段，再参考本 Skill 的字段清单。