kingdee-query

# 金蝶云星空 查询与操作助手 (kingdee-query) > 本技能**不自己连接金蝶**，它只是"导航员"：依赖名为 `kingdee` 的 MCP 服务器已在 WorkBuddy 中连接，并把用户的自然语言翻译成 kingdee-mcp 的工具调用。 ## 一、前置条件（务必先确认） - 入口：WorkBuddy 左侧 **插件 → MCP 服务器 → 配置 MCP**，确认 `kingdee` 已添加且状态为已连接（工具列表正常加载）。 - 必需环境变量： - `KINGDEE_SERVER_URL`：金蝶服务器地址，**必须包含 `/k3cloud/`** 后缀 - `KINGDEE_ACCT_ID`：账套 ID - `KINGDEE_USERNAME`：金蝶账号（建议专用集成账号，不要 Administrator） - `KINGDEE_PASSWORD`：账号密码（ValidateUser 登录，**必填**） - 可选： - `KINGDEE_LCID`：语言区，默认 `2052`（简体中文） - `MCP_SQLSERVER_*`：SQL Server 主机/端口/库/账号，启用数据库探查工具 - 认证方式：金蝶 WebAPI **账号密码(ValidateUser)**，无需 AppID / AppSecret。 - 若尚未配置，请把仓库 `examples/workbuddy-mcp-config.example.json` 中的 `kingdee` 片段加入用户级 `~/.workbuddy/mcp.json`（替换占位符），重启 WorkBuddy 后再用本技能。 ## 二、触发示例 - "查一下本月已审核的销售订单" - "物料 MAT001 的即时库存是多少" - "显示客户 C001 的所有销售订单" - "帮我新建一张采购订单，供应商 S001，物料 MAT001，数量 100，单价 10.5" - "审核这几张采购入库单：12345, 12346, 12347" - "采购订单在数据库里对应哪张表"（需配置 MCP_SQLSERVER_*） ## 三、可用工具（kingdee-mcp，共 86 个，按业务域） | 业务域 | 代表性工具 | 说明 | |--------|-----------|------| | 通用单据 | `kingdee_save_bill` · `kingdee_submit_bills` · `kingdee_audit_bills` · `kingdee_validate_bill` · `kingdee_push_and_audit` | 新建/提交/审核/下推 | | 生产制造 | `kingdee_query_production_orders` · `kingdee_save_production_order` · `kingdee_query_mrp_result` | 生产订单、MRP | | 成本核算 | `kingdee_query_material_cost` · `kingdee_query_cost_calculation` · `kingdee_save_cost_adjustment` | 材料成本、成本计算 | | 固定资产 | `kingdee_query_fixed_asset` · `kingdee_save_asset` · `kingdee_query_asset_depreciation` | 资产卡片、折旧 | | 库存 | `kingdee_query_inventory` · `kingdee_query_stock_bills` · `kingdee_push_stock_transfer` | 即时库存、出入库 | | 审计合规 | `kingdee_query_operation_logs` · `kingdee_query_change_log` · `kingdee_create_and_audit` | 操作/变更日志 | | 采购 | `kingdee_query_purchase_orders` · `kingdee_query_purchase_requisitions` | 采购订单/申请 | | 销售 | `kingdee_query_sale_orders` · `kingdee_query_sale_quotations` | 销售订单/报价 | | 工作流 | `kingdee_query_pending_approvals` · `kingdee_workflow_approve` | 待审/审批 | | 基础资料 | `kingdee_query_materials` · `kingdee_query_partners` · `kingdee_query_user` | 物料/往来/用户 | | 元数据探查 | `kingdee_list_forms` · `kingdee_get_fields` · `kingdee_get_bill_template` · `kingdee_discover_tables` | 表单/字段/库表 | | 系统/统计 | `kingdee_query_system_config` · `kingdee_usage_stats` · `kingdee_usage_report` | 配置/用量 | > 完整 86 个工具见 `src/kingdee_mcp/server.py`。元数据探查含 4 个 SQL Server 工具（`kingdee_discover_tables` / `kingdee_discover_columns` / `kingdee_describe_table` / `kingdee_discover_metadata_candidates`），需配置 `MCP_SQLSERVER_*`。 ## 四、使用约定 1. **先探查后查询**：不知道 `form_id` 时，用 `kingdee_list_forms` 搜索表单、用 `kingdee_get_fields` 取字段；通用查询用 `kingdee_query_bills`（需传 `form_id`）。 2. **只读优先**：查询用 `kingdee_query_*` 系列；看单据全貌用 `kingdee_view_bill`。 3. **写操作谨慎**：`kingdee_save_bill` / `kingdee_submit_bills` / `kingdee_audit_bills` / `kingdee_push_and_audit` 等会改动 ERP 数据，执行前必须与用户确认关键参数（单据类型、数量/金额、目标单号），必要时二次确认。 4. **中文呈现**：结果用中文结构化输出（表格/要点），金额、数量、日期等保留原值并注明单位。 5. **错误处理**：登录失败多为账号无权限或密码错误；连接超时先检查 `KINGDEE_SERVER_URL` 是否含 `/k3cloud/`。 ## 五、常见 form_id 速查 `PUR_PurchaseOrder` 采购订单 · `SAL_SaleOrder` 销售订单 · `STK_InStock` 采购入库单 · `SAL_OUTSTOCK` 销售出库单 · `STK_TransferDirect` 直接调拨单 · `STK_Inventory` 即时库存 · `BD_Material` 物料 · `BD_Customer` 客户 · `BD_Supplier` 供应商 ## 六、依赖 - 本技能依赖 **kingdee-mcp** MCP 服务器（PyPI：`pip install kingdee-mcp`，或 `uvx kingdee-mcp`）。 - 安装与配置见仓库根目录 `README.md` 与 `PUBLISH.md`。