前言¶
在 DeepSeek Harness（DSH）里让智能体读写 ERP，常见做法是手写 HTTP 调用、自己拼 session、再把单据状态机（保存、提交、审核）拆成多段脚本。金蝶云星空（Kingdee Cloud Starry Sky）对外提供 WebAPI，但字段名、表单 ID、登录方式与公有云策略并不直观，密钥也不适合写进配置文件。
下面介绍社区插件 dsh-kingdee（维护者 maxwell-feng），它在 DSH 侧提供一组带类型的 kingdee_* 工具，经官方 WebAPI 完成单据与基础资料的查询、保存、提交、审核、反审核、查看、删除，以及 BOS 自定义服务调用；并附带领域技能 kingdee-bos，说明字段/枚举/状态约定与「数据层 / 平台插件层」边界。插件归类为联网工具，当前 GitHub 星标为 0。
这是什么¶
dsh-kingdee 是金蝶云星空二次开发与 DeepSeek Harness 之间的桥接插件：智能体通过 DSH 工具调用租户 WebAPI，而不是在对话里粘贴账号密码。README 明确其覆盖范围是 数据/服务层；服务端 C# 表单/列表插件、UI 布局、后台事件等 平台插件层 需在 BOS 集成开发环境中完成，不能经 WebAPI 触达，kingdee-bos 技能文档说明了这一边界。
实现上为纯 TypeScript，带双语 README/配置说明，并符合 DSH 0.2.1-rc.2 的插件展示约定（含 icon.svg 与中英文 manifest 资源）。
核心功能¶
凭证与连接¶
- credential-safe：密钥通过 DSH 凭证机制解析为环境变量引用，配置里只写引用名，不写明文。
- 两种登录路径：账套用户名/密码走
AuthService.ValidateUser；第三方应用走AuthService.LoginByAppSecret（README 注明 2022-11-29 之后开通的公有云租户通常需要此模式）。两种方式均使用官方kdservice-sessionid（同时作为请求头与 Cookie），不按业务信封臆造鉴权头；登录结果按LoginResultType判定。 - 版本适配：面向金蝶云星空 V9.1 企业版 完整适配，并向后兼容 V9.0 / V8.x；支持稳定游标分页（
orderString、limit、startRow）、按单据编号（numbers）流转，以及isAutoSubmitAndAudit等能力（细节见仓库 CONFIG/USAGE 文档）。 - SSRF 防护：仅允许 http/https，并对主机做边界校验，拦截 localhost、环回、私网与保留网段。
单据状态与工具面¶
README 提供开箱即用的状态机：创建/更新 → 提交 → 审核 → 反审核。下列为文档 Tools 表中列出的工具及主要参数（其余能力以 README 功能描述为准，命名均为 kingdee_* 前缀）：
| 工具 | 说明 | 关键参数 |
|---|---|---|
kingdee_query |
ExecuteBillQuery，查询单据/基础资料 |
formId、fieldKeys[]、filter?、topCount?、organization? |
kingdee_query_business_data |
结构化查询 QueryBusinessData |
同上 |
kingdee_save |
保存（新建/更新） | formId、data、interaction? |
kingdee_batch_save |
批量保存 | formId、records[]、interaction? |
kingdee_submit |
提交 | formId、ids[]、numbers? |
kingdee_unsubmit |
撤销提交 | formId、ids[] |
另支持审核、反审核、查看、删除及调用 BOS 自定义服务；完整参数见仓库 USAGE.md。
离线 Mock¶
配置 mock: true 时改用本地传输层，返回预置的金蝶风格信封，便于在无可用租户时演示或跑通流水线。设置卡片不暴露 mock，需在配置文件中写入，例如：
config:
mock: true
安装与启用¶
在 DSH profile 中加入 bundle 并启用（命令来自官方 README）：
# Add the bundle to a DSH profile and enable it
dsh plugin --profile web add dsh-kingdee
与 DSH 版本的对应关系（摘自 README）： 插件在 engines.dsh 上声明 >=0.1.7-alpha.2 <0.3.0；0.15.0 已在 DeepSeek Harness 0.2.1-rc.2 上验证（typecheck/build 通过，15 个单元测试通过；未对真实租户做联调验证）。较旧的 0.10.0 声明 ^0.1.7-alpha.2，在 0.2.x 上会在加载时被拒绝。在 0.2.x 上可执行 dsh plugin --profile web add dsh-kingdee@0.15.0 升级；package.json 当前版本为 0.15.1。
CLI 语法注意：自 DSH 0.2.1-alpha.1 起，--profile <name> 须写在 add、remove、update 等子命令之前，否则 flag 会被转发给 pnpm 导致失败。
若版本被拒绝，Harness 可能提示使用 dsh plugin allow-version <package@version> --dsh-version <runtime> --accept-risk 记录精确版本豁免；这是风险确认，不是兼容性修复。
典型用法¶
1、配置连接与认证模式¶
在 Plugins → kingdee 设置卡片（或 cordis.yml）中填写 WebAPI 基址、acctId 及认证模式。
2、注入密钥（引用名，非明文）¶
Linux / macOS 示例：
export DSH_KINGDEE_USER=your_username
export DSH_KINGDEE_PASSWORD=your_password
# app 模式：DSH_KINGDEE_USER 为集成用户，且必填
export DSH_KINGDEE_APP_SECRET=your_app_secret
也可在 DSH 凭证库或 $DSH_HOME/.credentials.yaml 中写入值；配置里只保留引用名。各操作系统持久化方式见 INSTALL.md。
3、用自然语言驱动查询¶
向智能体描述任务，例如：
Query sales order number SO-20260701 on Kingdee Cloud.
智能体会加载 kingdee-bos 技能，并调用 kingdee_query，例如 formId=SAL_SaleOrder（以实际表单 ID 为准）。
更完整的配置字段、升级与卸载步骤见仓库 CONFIG.md、INSTALL.md、UPDATE.md、UNINSTALL.md。
适用场景与注意¶
适合谁： 已在 DSH 中开发智能体、需要按金蝶云星空 WebAPI 规范查改单据/基础资料、或调用 BOS 自定义服务的二次开发人员；希望把登录 session、分页与单据流转封装成稳定工具而非临时脚本时。
务必知晓：
- 插件以当前 DSH 进程权限访问你配置的 WebAPI 地址；安装前请自行审阅 源码与许可证，确认租户网络策略与账号权限范围。
- 社区目录 SkillHub 插件页 与 GitHub 仓库由维护者发布，与 DeepSeek / 幻方无官方从属关系；DSH 生态遵循「一切皆插件」，目录站是独立社区索引，并非官方应用商店。
- README 已声明：未对真实租户做联调验证；生产使用前应在自有环境完成认证、表单 ID 与权限测试。
结尾¶
dsh-kingdee 把金蝶云星空 WebAPI 封装为 DSH 可编排的类型化工具，并配合 kingdee-bos 技能约束领域知识边界，适合在 Harness 里做凭证安全、可审计的 ERP 数据层自动化。
