mdye-apis

封装开放接口的 npm 包

相关文档

• 🤖 智能体 / Agent 说明入口 - 任意 AI 助手可先读此文件，再打开 skills/mdye-apis/SKILL.md

文档在包里的位置

• 发布到 npm 的包：文档在包根目录（与 dist 平级），例如安装后 node_modules/mdye-apis/README.md、AGENTS.md、skills/、CHANGELOG.md。它们由 package.json 的 files 字段打进 tarball，不会只出现在 dist/ 里。
• 本地执行 pnpm build 后：同一份文档会再复制到 dist/docs/，方便只打开 dist 目录时也能看到说明。

查看发布内容是否含文档：npm pack 或 pnpm pack，在输出列表里应能看到上述路径。

安装

npm install mdye-apis
# 或
pnpm install mdye-apis
# 或
yarn add mdye-apis

环境配置

本包支持两种配置方式，你可以根据项目需求选择：

方式一：工厂函数

使用 createMdyeApis() 工厂函数创建配置好的 API 实例。也可 无参调用 createMdyeApis()：在浏览器内从 window.env 读取配置；非浏览器或 window.env 无效时会抛错，须改为传入对象。

明道云公有云：host 可省略，默认 https://api.mingdao.com。私有部署：必须传入你们环境的开放接口 host。

import { createMdyeApis } from 'mdye-apis'

// 插件内：宿主已注入 window.env 时可无参
// const { appApis, worksheetApis } = createMdyeApis()

// 公有云：只传 appKey、sign 即可
const { appApis, worksheetApis } = createMdyeApis({
  appKey: 'your-app-key',
  sign: 'your-sign',
})

// 私有部署：显式传入 host
const api = createMdyeApis({
  host: 'https://your-private-gateway.example.com',
  appKey: 'your-app-key',
  sign: 'your-sign',
})

// 使用 App 接口
const appInfo = await appApis.getAppInfo()

// 使用工作表接口
const rows = await worksheetApis.getFilterRows({
  worksheetId: 'worksheet-id',
  // ... 其他参数
})

方式二：明道云插件视图使用

插件宿主会把开放接口环境挂在 window.env（字段与方式一相同：appKey、sign 必填；host 可选，私有部署时填写网关）。配置好后直接导入即可。

// 由宿主注入，业务侧通常无需手写；以下为字段示意
// window.env = { appKey: '...', sign: '...' }
// 私有部署示例：window.env.host = 'https://your-private-gateway.example.com'

// 导入
import { appApis, worksheetApis } from 'mdye-apis'

// 使用 App 接口
const appInfo = await appApis.getAppInfo()

// 使用工作表接口
const rows = await worksheetApis.getFilterRows({
  worksheetId: 'worksheet-id',
  // ... 其他参数
})

配置参数说明

• host（可选）：开放接口根地址。省略时默认为明道云公有云 https://api.mingdao.com；私有部署须设为实际网关地址。末尾斜杠会被自动去掉。
• appKey：密钥（必填）
• sign：签名（必填）

常量 DEFAULT_MINGDAO_OPEN_API_HOST 可从包根导出，与默认值一致。

优先级

如果同时使用两种方式，工厂函数传入的配置优先级更高，会覆盖 window.env 的配置。

智能体可读说明（通用）

本包附带 Agent Skill 格式说明（YAML frontmatter + Markdown），不绑定某一 IDE；安装后位于包根目录，便于工具或助手直接打开：

| 路径（仓库内） | 安装后（node_modules/mdye-apis/ 下） | |----------------|----------------------------------------| | AGENTS.md | AGENTS.md — 入口索引 | | skills/mdye-apis/SKILL.md | skills/mdye-apis/SKILL.md — 主说明 | | skills/mdye-apis/reference.md | skills/mdye-apis/reference.md — 方法表 |

package.json 中 agentSkill 字段指向主技能文件路径，便于脚本解析。

若你使用的环境支持 Agent Skills 类目录约定，可将 skills/mdye-apis 复制或链接到该工具要求的技能目录（例如部分编辑器使用 .cursor/skills/），内容与包内 skills/ 一致即可。

注意事项

• 所有接口方法会自动获取 appKey 和 sign，无需在每次调用时手动传入
• 请求基址为 {host}/v2/open/...；公有云未传 host 时与默认开放接口一致
• 请确保在使用任何接口之前完成环境配置（至少 appKey 与 sign）