金蝶云星空 ERP Skill

Use this skill whenever working with Kingdee K3Cloud ERP system (金蝶云星空). Triggers include: querying sales orders (销售订单), purchase orders (采购订单), inventory (库...

Security Scan

This instruction-only Kingdee K3Cloud ERP skill is internally consistent with its stated purpose, but it assumes access to an external MCP server/tools and will read/write local files — verify the MCP endpoint, credentials, and any local config before installing.

Purpose & Capability

The skill is a documentation/instruction bundle for interacting with Kingdee K3Cloud via an MCP toolset (query_bill_json, view_bill, query_bill_range, save/submit/audit operations). That matches the name/description. One minor inconsistency: the SKILL.md requires an MCP Server and refers to a recommended repo, yet the skill metadata declares no required env vars/credentials or binaries — the skill relies on platform-provided MCP tools but does not declare or request the credentials the MCP server may need.

Instruction Scope

Runtime instructions are explicit and scoped to ERP queries/operations (list/detail queries, pagination, file export, save/submit/audit). The guide instructs creating/reading local files (e.g., writing ndjson/xlsx to /tmp, recommending a CLAUDE.md in project root for config that 'Claude Code will read'), which means the agent will read project files and write to disk. This is expected for an ERP data workflow, but users should be aware the skill expects access to local files and the platform's MCP tool invocation.

Install Mechanism

No install spec and no code files — lowest-risk model. The skill is instruction-only and does not download or install external binaries. It does recommend an external MCP project but does not attempt to install it automatically.

Credentials

The skill declares no environment variables or primary credential. However, its instructions assume an MCP Server and tools that in practice require authentication/credentials. The absence of declared env vars is not necessarily malicious, but you should confirm where MCP credentials live (agent config, platform tool tokens, or external server) before use.

Persistence & Privilege

Flags: always=false, user-invocable=true, disable-model-invocation=false. The skill does not request permanent or elevated platform privileges and does not indicate it will modify other skills or global agent settings.

Assessment

This skill is a documentation-only helper for Kingdee K3Cloud and appears coherent, but take these precautions before installing: - Confirm how your environment's MCP Server is configured: the skill assumes an external MCP toolset (query_bill_json, view_bill, etc.). Verify the MCP endpoint URL and that its authentication tokens/credentials are stored securely and are not being exposed by the skill. - Verify CLAUDE.md and other local config files: the guide recommends placing config in project files that the agent may read automatically. Don't put secrets (passwords, API keys) in files the agent will read. - Review where exported files will be written (examples use /tmp). Ensure writing to those paths is acceptable and that sensitive exports are handled securely (not sent to third-party endpoints). - Audit the MCP server code/repo you plan to use (the README links to a GitHub repo). Because this skill relies on that external component, its security is critical. - If you need stronger assurance, ask the skill author to declare where credentials are stored and whether any network calls go to endpoints other than your MCP server/Kingdee instance. If those checks are satisfactory, the skill is coherent for ERP querying and reporting workflows. If you cannot verify the MCP server or credential handling, treat installation as higher risk.

金蝶云星空 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 < 'YYYY-MM-DD+1'
3. FDate vs FCreateDate：FDate 是业务日期（手填），FCreateDate 是系统创建时间。按"今天开的单"统计用 FCreateDate
4. 单据状态码：Z = 暂存草稿，A = 创建，B = 审核中，C = 已审核，D = 重新审核
5. 控制数据量：top_count 限制行数，只查必要字段，超过20行数据考虑创建 Excel
6. 字段不确定时：先调用 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
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 的字段清单。