金蝶云星空连接器 maxwell-feng/dsh-kingdee

dsh-kingdee

英文 | 中文

面向 DeepSeek Harness（DSH）的金蝶云星空二次开发插件。

dsh-kingdee 让 DSH agent 通过金蝶云星空的 WebAPI 对账套做一等公民、凭据安全的操作：提供一套类型化工具，用于查询、保存、提交、审核、反审核、查看、删除单据与基础资料，以及调用 BOS 自定义服务。配套的领域技能（kingdee-bos）讲解字段/枚举/状态机约定，以及数据层与平台插件层的边界。

- 凭据安全 —— 密钥以环境变量引用存放，经 DSH 凭据缝解析，绝不写在明文配置里。
- 全面适配金蝶云·星空 V9.1 企业版 —— 深度适配金蝶云·星空 V9.1 企业版（向下兼容 V9.0 / V8.x）：官方 kdservice-sessionid 会话同时以请求头与 Cookie 双通道发出；大表防扫表稳定游标分页（orderString、limit、startRow）；单据编号（numbers）直接驱动审批/反审/删除/反提交业务流程；保存时自动提审（isAutoSubmitAndAudit）。
- 两条真实登录链路 —— 账套用户名/密码走 AuthService.ValidateUser；第三方应用走 AuthService.LoginByAppSecret（金蝶对 2022-11-29 之后开通的公有云账套要求该模式）。两者建立同一个 kdservice-sessionid 会话，不使用任何伪造的认证请求头；登录响应按其自身的 LoginResultType 结构单独判定，而非业务信封。
- SSRF 深度安全基线 —— 纯 TypeScript 实现严格的协议白名单（仅限 http: / https:）与网络边界拦截，自动屏蔽 localhost、环回及私有保留网段请求。
- 类型化工具 —— 通过 kingdee_ 工具完成查询、保存、提交、审核、反审核、查看、删除与调用 BOS 自定义服务，具体见下方工具表。
- 完整状态机 —— 创建/更新 → 提交 → 审核 → 反审核，开箱即用。
- 离线 Mock —— 配置 mock: true 即切换到本地固化传输，无需可连通账套即可演示与测试。
- 双语文档 —— 英文与简体中文。

🧩 边界说明。 本插件覆盖金蝶云星空二次开发的数据/服务层。平台插件层（服务器端 C# 表单/列表插件、界面布局、后台事件）需使用 BOS 集成开发环境，无法经 WebAPI 触达。kingdee-bos 技能记录了这一边界。

安装

把 bundle 加进 DSH profile 并启用
dsh plugin add dsh-kingdee

面向 DeepSeek Harness 0.2.0-rc.1，旧版本必须升级。 0.11.1 完成对 DeepSeek Harness 0.2.0-rc.1 的适配。此前的 0.10.0 在 0.2.0-rc.1 上会在加载阶段被拒绝：它把 @deepseek-ai/dsh-credentials 与 @deepseek-ai/dsh-tools 两个 peer 声明为 ^0.1.7-alpha.2，该区间不含 0.2.x；而 0.2.0-rc.1 会在插件行加载之前，用唯一的运行时版本校验每一处名为 @deepseek-ai/dsh / @deepseek-ai/dsh- 的 peer 依赖，且预发行版参与区间匹配（闸门读取的不是 engines.dsh）。不兼容的行会被拒绝，不兼容的 bundle 会被跳过。0.11.1 把两个 peer 区间放宽为 >=0.1.7-alpha.2 被拒时宿主会打印的补救方式是 dsh plugin allow-version --dsh-version --accept-risk（或使用插件管理器），它会在 profile 的 compatibility.json 中记录一条确切版本豁免。这是风险确认，而不是兼容性修复；且它只对一个确切插件版本、一个确切运行时生效：插件升级或宿主升级都不会继承该授权。

已在 deepseek-harness 0.2.0-rc.1 上、以插件 0.11.1 验证：pnpm run typecheck 零错误、pnpm run build 构建干净、15 项单元测试通过（pnpm test）、pnpm install 通过 pnpm 的供应链闸门，且宿主自带的兼容性校验在运行时 0.2.0-rc.1 上准入 dsh-kingdee@0.11.1。未进行真实账套联调验证。

详细配置见 CONFIG.zh.md，安装步骤见 INSTALL.zh.md，工具说明见 USAGE.zh.md，升级/卸载见 UPDATE.zh.md 与 UNINSTALL.zh.md。版本历史见 CHANGELOG.zh.md / CHANGELOG.md。

快速开始

1. 注册插件，在 Plugins → kingdee 设置卡片（或 cordis.yml）里填连接信息：WebAPI 地址、acctId、认证方式。
2. 把密钥放进环境变量（或凭据库），引用指向配置的引用名。所有系统使用相同的引用名，只是设置方式不同：

Linux / macOS (sh)
export DSH_KINGDEE_USER=your_username
export DSH_KINGDEE_PASSWORD=your_password
app 模式：DSH_KINGDEE_USER 存集成用户，且为必填
export DSH_KINGDEE_APP_SECRET=your_app_secret

Windows — PowerShell（当前会话） $env:DSH_KINGDEE_USER = "your_username" $env:DSH_KINGDEE_PASSWORD = "your_password" $env:DSH_KINGDEE_APP_SECRET = "your_app_secret" # app 模式（USER 即集成用户）

REM Windows — 命令提示符（当前会话）
set DSH_KINGDEE_USER=your_username
set DSH_KINGDEE_PASSWORD=your_password
set DSH_KINGDEE_APP_SECRET=your_app_secret

或者不用 shell 环境变量，而把值存进 DSH 凭据库：在 DSH 设置界面里填一次即可（凭据值只写不读 —— 页面只能看到脱敏描述符），也可直接编辑 $DSH_HOME/.credentials.yaml。插件配置里携带的是引用名，值永远不会进入配置文件。

各系统的详细设置（含持久化 setx / [Environment]::SetEnvironmentVariable）见 INSTALL.zh.md。

3. 让 agent 查询：

在金蝶云星空查询销售订单 SO-20260701。

agent 会加载 kingdee-bos 技能，并以 formId=SAL_SaleOrder 调用 kingdee_query。

在没有真实账套时，把插件配置设为 mock: true —— 工具会返回固化的金蝶信封。设置卡片会暴露非机密的连接字段，但不含 mock，因此该项请在配置中设置：

config:
mock: true

完整片段见 INSTALL.zh.md。

工具

| 工具 | 作用 | 关键入参 |
| kingdee_query | ExecuteBillQuery —— 查单据/基础资料 | formId、fieldKeys[]、filter?、topCount?、organization? |
| kingdee_query_business_data | 结构化查询（QueryBusinessData） | formId、fieldKeys[]、filter?、topCount?、organization? |
| kingdee_save | 保存（新增/更新）单据或基础资料 | formId、data、interaction? |
| kingdee_batch_save | 单次批量保存多条 | formId、records[]、interaction? |
| kingdee_submit | 提交一条或多条 | formId、ids[]、numbers? |
| kingdee_unsubmit | 反提交 | formId、ids[] |
| kingdee_audit | 审核 | formId、ids[] |
| kingdee_unaudit | 反审核 | formId、ids[] |
| kingdee_view | 按 id 查看单条 | formId、id |
| kingdee_delete | 按 id 删除 | formId、ids[] |
| kingdee_delete_draft | 删除草稿（暂存） | formId、ids[] |
| kingdee_invoke | 调用 BOS 自定义服务 | serviceName、payload?、formId? |
| kingdee_logout | 退出当前会话 | — |
| kingdee_list_datacenters | 列出该地址可达的数据中心/账套 | — |

表格顺序与 USAGE.zh.md 的逐工具参考章节顺序一致。

每个工具返回规范化的规范值；金蝶 IsSuccess=false 的消息会转成类型化错误（kd/business-error、kd/auth-failed 等），而不是让模型去解析文本。

金蝶 V9.1 符合性

dsh-kingdee 面向 金蝶云·星空 V9.1 企业版（补丁 PT-163015 → 产品版本 9.1.0.20250807），并向下兼容 V9.0 / V8.x。

V9.1 没有破坏性 WebAPI 变更。 没有重命名或移除的操作、没有 Cookie 改名、没有 URL 约定变化、也没有新增必填请求头。本插件使用的经典 {baseUrl}/{stub path}.common.kdsvc + kdservice-sessionid 会话协议保持不变。

V9.1 在接口层真正发生的变化：

- Delete 现在返回正确的 FNumber —— 自 9.1.0.20250807 起 SuccessEntitys[].Number 可直接采信。
- 多文件附件（文件服务）字段可仅凭文件 ID 赋值。
- 服务端新增了 WebAPI 请求体日志。
- 在线文档补充了幂等性校验指引。
- WebAPI 限流增加了白名单。
- 报表 Stub / API 自定义接口做了安全加固。
- 外部用户访问控制被收紧。

由此带来的运维影响：

- 由于服务端会记录请求体，请尽可能优先使用 app（第三方）模式，而不是账号密码模式。
- 由于权限被收紧，缺少查询权限可能表现为空结果而不是报错 —— 请针对每个 FormId 先跑一次探针查询验证，而不要直接相信空结果集。
- 请把插件所在主机的出口 IP 加入 WebAPI 限流白名单。

证据诚实性说明。 登录服务所用的具名请求键（acctID / username / appid / appsecret / lcid）、Limit 行数上限（约 2000）以及 listDataCenterService 默认服务名，均为社区验证结论，并非金蝶官方发布的契约。每个账套的权威来源是产品本身：以管理员登录 → 公共设置 → 动态服务定义 → WebAPI，选择业务对象与操作，直接查看该操作的参数说明与示例调用。

架构

src/
├─ kd-core/ 无框架依赖的金蝶 WebAPI 客户端（纯逻辑） │ ├─ auth.ts user / app 两种认证 │ ├─ client.ts 业务操作集 + 会话管理 │ ├─ envelope.ts 信封解析与规范化 │ ├─ errors.ts 类型化错误映射 │ ├─ transport.ts 传输留缝（真实 HTTP 用 fetch） │ └─ mock.ts 离线 mock 传输 ├─ index.ts DSH host 插件：注册 kingdee_* 工具 + 导出 Config schema ├─ tools.ts 类型化工具包装（defineTool） ├─ config.ts 插件配置 schema + 凭据解析 └─ client/ └─ settings-card.ts 浏览器设置卡片（脚手架） skills/ └─ kingdee-bos/ 领域技能：字段/枚举/状态机约定 + 边界

kd-core 以 dsh-kingdee/kd-core 发布，不依赖 DSH，将来可被薄 MCP server 复用同一份逻辑。

构建与测试

无框架核心由 15 项单元测试验证，使用 Node 内置测试运行器（Node ≥ 22，TS 类型剥离）运行，核心无需 DSH 安装：

pnpm test # node --test "test//.test.ts"

DSH host/插件半区（src/index.ts、tools.ts、config.ts、client/）引用 @deepseek-ai/ peer 包，需在 DSH profile 内编译，那里这些 peer 才能解析。因此构建与 typecheck 使用 DSH 工具链：

pnpm install && pnpm run typecheck # 需 deepseek-harness 单仓（或 DSH profile）提供 peers

仓库全量使用 TypeScript，没有需要同步维护的 JavaScript 源码。双语文档闸门为 scripts/check-docs-language.ts，CI 在安装依赖之前用裸 Node 直接运行它（无需任何依赖）：

node scripts/check-docs-language.ts

已知限制

- 尚未实现公有云 OpenAPI 网关。 越来越多的金蝶公有云账套要求走 OpenAPI 网关（https://api.kingdee.com/galaxyapi/）并使用 API 签名认证（LoginByApiSignHeaders）。本插件未实现该链路，只支持经典 kdsvc 会话协议。在这类账套上经典会话根本无法建立，因此所有操作都会在登录环节失败；必须使用仍然开放经典 WebAPI 的账套/网关。
- 平台插件层无法触达。 服务器端 C# 表单/列表插件、界面布局与后台事件属于 BOS 集成开发环境，无法经 WebAPI 访问（见上文的边界说明）。
- ./client 产物由本包自行复现。 共享的 clientBundle tsdown preset 位于 harness 仓库内部且未发布，因此本包自行输出文档化的 factory 格式。
- 未做真实账套联调。 本文档的所有内容均以类型检查、构建、单元测试套件与宿主自带的插件兼容性校验为依据，而非在运行中的金蝶账套上验证。

文档

- INSTALL.zh.md —— 安装与配置
- CONFIG.zh.md —— 配置参考：字段、认证模式、凭据与 SSRF 基线
- USAGE.zh.md —— 工具说明（含入参与示例）
- UPDATE.zh.md —— 升级
- UNINSTALL.zh.md —— 卸载
- CHANGELOG.zh.md —— 版本历史
- docs/RELEASE.zh.md —— 当前版本发行说明

许可证

本仓库采用专有许可证（保留所有权利），仅供阅读/评估。未经所有者书面许可，禁止在整体或部分上复制、复刻/fork、再托管、再发布、修改或制作衍生作品。详见 LICENSE。