# Kingdee K3cloud

> 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:…

- **Type:** Skill
- **Install:** `agentstack add skill-adamzhang1987-kingdee-k3cloud-skill-kingdee-k3cloud`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [adamzhang1987](https://agentstack.voostack.com/s/adamzhang1987)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [adamzhang1987](https://github.com/adamzhang1987)
- **Source:** https://github.com/adamzhang1987/kingdee-k3cloud-skill/tree/main/kingdee-k3cloud

## Install

```sh
agentstack add skill-adamzhang1987-kingdee-k3cloud-skill-kingdee-k3cloud
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 金蝶云星空 ERP 操作技能

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

> **前提条件**：本 Skill 需配合金蝶云星空 MCP Server 使用，推荐 [kingdee-k3cloud-mcp](https://github.com/adamzhang1987/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）— 直接落盘，无需手动循环

```python
# 跨年查询，按月自动分片，流式写入本地文件
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-adamzhang1987-kingdee-k3cloud-skill-kingdee-k3cloud
- Seller: https://agentstack.voostack.com/s/adamzhang1987
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.