HAP 开发指南

适用：明道云 SaaS、私有部署（HAP Server）

本页是 HAP 开放能力的总览入口：帮你判断该用哪种能力，并用最短路径完成第一次调用。完整参数和配置细节，请看各能力的独立文档。

你想做什么？

让 AI 帮我操作 HAP用 MCP（+ Skills）→在支持 MCP 的 AI 工具里，用对话查询、分析和更新业务数据在终端或脚本里批量处理用 CLI →用 hap 命令做可重复的批量操作和自动化写代码对接应用数据用应用 API V3 →从自有系统读写工作表记录、触发工作流同步成员、部门等组织数据用组织 API →与 HR、企业微信、钉钉等系统做组织架构同步

01 开发方式与能力选型

HAP 有四种接入方式和一种配套能力。MCP、CLI、应用 API、组织 API 是可以直接调用 HAP 的方式；Skills 不是独立的接口或鉴权方式，它给 AI 提供使用说明和操作规范，叠加在 MCP、CLI 或 API 之上使用。

能力	一句话说明	适合	使用的凭证
MCP	让支持 MCP 的 AI 工具直接调用 HAP 能力	对话式实时操作：了解应用结构、查询分析数据、新增或更新记录	个人访问令牌，或应用密钥
CLI	通过 `hap` 命令执行操作	脚本、批量任务、自动化；也可由 AI 驱动	CLI 登录令牌
应用 API	通过 HTTP 接口读写应用数据与结构	自有系统与 HAP 应用集成	AppKey + Sign、PAT 或 OAuth 2.0
组织 API	通过 HTTP 接口管理组织级数据	成员、部门、汇报关系同步，流程待办与日志	组织密钥（AppKey + SecretKey）
Skills（配套）	告诉 AI 何时用哪种能力、如何传参，高风险操作前先确认	使用 AI 工具时提高准确性	无单独凭证，沿用所配合能力的凭证

选型路径 · 各能力的用途见上表

02 快速开始

四条路径相互独立，选一条即可。每条都写明前提、步骤和「如何确认成功」。

用 AI 操作 HAP（MCP）

前提 AI 工具支持远程 MCP（Streamable HTTP）；用个人访问令牌时，还需支持自定义 HTTP 请求头凭证个人访问令牌或应用密钥

在工作台右上角点击【连接 AI】，打开【MCP】页签，选择安装方式：对话安装或手动安装。
选择要连接的 Agent 工具；列表中没有时选【其他】。
选择权限范围：【个人】选择个人访问令牌；【应用】选择目标应用和授权密钥。
按需勾选【同时安装配套 Skills】，然后完成安装：对话安装点击【安装】，在客户端确认执行；手动安装复制页面生成的命令到终端执行。

如何确认成功　先确认客户端已启用 HAP MCP 并加载了工具列表，再依次发送：
「列出当前 HAP MCP 可用的工具，并简要说明用途。先不要修改任何数据。」
「查询『客户管理』应用的工作表结构，只返回工作表名称和主要字段，不修改数据。」（换成你有权限的应用）
两次都返回预期结果即连接成功。不能只用浏览器打开 MCP 地址来判断。

用命令行操作 HAP（CLI）

前提 Python 环境；组织已开启 CLI 访问策略凭证 CLI 登录令牌

bash

# 1. 安装
pip install hap-cli

# 2. 登录（默认明道云 SaaS，会打开浏览器）
hap auth login
# 私有部署：hap auth login https://hap.example.com

# 3. 确认身份和组织，CLI 列应显示 on
hap auth whoami
hap auth list-my-orgs

# 4. 选择组织和默认应用
hap auth set-current-org ORG_ID
hap app select APP_ID

# 5. 执行第一条命令
hap worksheet list

如何确认成功　hap worksheet list 返回该应用的工作表列表。若命令被拦截，说明组织未开启 CLI 访问策略，见组织级开关。

想让 AI 用自然语言驱动 CLI：在【连接 AI】>【CLI】安装时勾选配套 Skills。

代码读写应用数据（应用 API V3）

前提你是应用管理员，或管理员已提供密钥凭证 AppKey + Sign

在应用【API 开发文档】>【应用授权】>【新建授权密钥】，记下 AppKey 和 Sign。
调用 POST /v3/app/worksheets/list 找到目标工作表，记下 id。
调用 GET /v3/app/worksheets/{worksheet_id} 获取结构，记下要写入字段的 ID。

新建一条记录（把 {worksheet_id}、YOUR_FIELD_ID 换成实际值）：

bash

curl -X POST "https://api.mingdao.com/v3/app/worksheets/{worksheet_id}/rows" \
  -H "HAP-Appkey: YOUR_APP_KEY" \
  -H "HAP-Sign: YOUR_SIGN" \
  -H "Content-Type: application/json" \
  -d '{
    "triggerWorkflow": true,
    "fields": [
      { "id": "YOUR_FIELD_ID", "value": "First API record" }
    ]
  }'

读取记录：

bash

curl -X POST "https://api.mingdao.com/v3/app/worksheets/{worksheet_id}/rows/list" \
  -H "HAP-Appkey: YOUR_APP_KEY" \
  -H "HAP-Sign: YOUR_SIGN" \
  -H "Content-Type: application/json" \
  -d '{ "pageSize": 20, "pageIndex": 1, "includeTotalCount": true }'

如何确认成功　新建记录返回 "success": true 和新记录的 data.id；读取记录能在 data.rows 中看到它。

如果调用失败：同时检查 HTTP 状态码和响应体中的 success、error_code、error_msg，再按按现象排查定位是鉴权、权限还是请求参数问题。

示例中的工作表 ID、字段 ID 必须换成实际值；字段值要符合该字段的类型和必填规则。私有部署把 https://api.mingdao.com 换成 {YOUR_HOST}/api。按条件筛选见应用 API 使用指南。

代码同步组织数据（组织 API）

前提你是组织管理员凭证组织密钥（AppKey + SecretKey）

在组织管理 >【集成】>【其他】>【组织密钥】获取 AppKey 和 SecretKey。
在组织管理 >【组织信息】>【编号(ID)】获取（projectId）。

生成签名，并调用「获取应用列表」接口验证：

python

import base64, hashlib, time
import requests

APP_KEY = "YOUR_APP_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
PROJECT_ID = "YOUR_PROJECT_ID"

ts = int(time.time() * 1000)  # 毫秒
raw = f"AppKey={APP_KEY}&SecretKey={SECRET_KEY}&Timestamp={ts}"
sign = base64.b64encode(hashlib.sha256(raw.encode("utf-8")).hexdigest().encode("utf-8")).decode("utf-8")

resp = requests.get(
    "https://api.mingdao.com/v1/open/app/getByProject",
    params={"appKey": APP_KEY, "sign": sign, "timestamp": ts, "projectId": PROJECT_ID},
    timeout=10,
)
print(resp.status_code, resp.json())

如何确认成功　按接口文档，成功时返回 "error_code": 1、"success": true，data 中是组织下的应用列表。

如果调用失败：先看 error_code 和 error_msg。鉴权失败时依次检查：时间戳是否为毫秒、请求中的 timestamp 是否与签名所用一致、签名是否超过 1 小时、AppKey 与 SecretKey 是否来自同一组织。

03 凭证与权限

创建凭证不等于能访问所有数据。一次调用能否成功，要同时通过三层检查：

组织级访问策略

组织管理员是否开启了 CLI 访问、API 访问等策略。未开启时请求直接被拦截。

凭证自身的范围

凭证属于哪个组织或应用、能调用哪些接口、是否过期。例如 PAT 创建时会设定组织、应用范围、接口范围和有效期。

身份的实际权限

凭证所代表的身份在 HAP 中能做什么。个人身份受用户角色权限约束；应用身份按应用管理员权限操作。

凭证一览

凭证	代表谁	权限依据	谁能创建 · 入口	什么时候选它
个人访问令牌（PAT）	当前用户	用户本人的权限 + 令牌设定的组织、应用、接口范围；到期失效	任意用户 · 头像 >【授权与访问】>【添加】	MCP 个人模式；需要按具体用户权限调用应用 API
应用授权密钥（AppKey + Sign）	应用管理员（不代表具体用户）	密钥所属应用 + 密钥的 API 权限范围；长期有效	应用管理员 · 应用【API 开发文档】>【应用授权】>【新建授权密钥】	服务端集成、定时同步；MCP 应用模式
OAuth 2.0 访问令牌	授权的用户	用户权限 + 授权时申请的 scope；短效，可用刷新令牌续期	由用户授权第三方应用 · 见应用 API 文档	第三方应用代表用户访问
CLI 登录令牌	登录的用户	用户本人的权限 + 组织是否开启 CLI 访问策略。这是 HAP 登录令牌，不是 PAT	任意用户 · `hap auth login` 浏览器登录后自动获取，或从登录成功页复制	使用 CLI
组织密钥（AppKey + SecretKey）	组织	组织级接口权限，读取权限较高；签名 1 小时内有效	仅组织管理员 · 组织管理 >【集成】>【其他】>【组织密钥】	成员、部门同步等组织级集成

组织级开关

以下两项策略都在组织管理 >【安全】>【数据与访问】中，由组织管理员开启：

CLI 访问策略：未开启时，hap 命令无法访问该组织数据。运行 hap auth list-my-orgs 可查看各组织的开启状态（CLI:on 或 CLI:off）。
API 访问策略：未开启时，无法使用个人访问令牌（PAT）或应用授权密钥访问该组织数据，依赖这两种凭证的 MCP 连接也会失败。

环境与地址

环境	应用 API	组织 API	CLI 登录
明道云 SaaS	`https://api.mingdao.com/v3/...`	主机 `https://api.mingdao.com`，路径前缀因接口分类而异（见组织 API）	`hap auth login`
私有部署	`{YOUR_HOST}/api/v3/...`	在组织管理中打开的文档会自动使用部署域名	`hap auth login https://YOUR_HOST`

本页示例基于明道云 SaaS。其他环境（如 Nocoly）请参考对应环境的开发文档。

凭证安全

只在可信服务端保存密钥和令牌，不要写进浏览器前端、客户端或公开仓库。

为不同系统分别创建凭证，按需授予最小范围；PAT 设置有效期。凭证疑似泄露时，立即停用并重新创建。

04 能力使用指南

本节是各能力的要点速查。完整说明以对应的独立文档为准。

MCP

HAP MCP 是远程服务，把明道云的业务能力提供为可调用的工具。支持远程 MCP 的客户端可直接连接，无需本地部署或安装 Node.js。推荐通过【连接 AI】安装，见快速开始；完整配置示例和排错见 MCP 文档。

要点	说明
服务地址	明道云 SaaS：`https://api.mingdao.com/mcp`，Streamable HTTP。私有部署使用本环境生成的完整地址，保留路径前缀
个人访问令牌	以个人身份协助日常业务；请求头 `Authorization: Bearer <TOKEN>`，客户端需支持自定义请求头
应用密钥	围绕指定应用做业务集成；URL 参数 `HAP-Appkey`、`HAP-Sign`，直接复制应用管理 >【API 文档】>【应用授权】>【MCP】生成的完整 URL
手动配置	优先使用界面生成的对应客户端配置；各客户端字段不同，按客户端说明填写
权限	连接 MCP 不会扩大凭据权限；工具可见不代表有数据操作权限。授权变化后刷新工具列表
验证	以客户端成功加载工具并完成一次读取为准，不能只用浏览器打开地址判断

CLI

HAP CLI（hap）覆盖三类场景：协作沟通（通讯录、消息、动态、日程）、应用数据（记录增删改查、工作流、审批、自定义页面、角色、文件上传）、应用修改（加字段、改视图、调整流程等局部修改）。

要点	说明
命令组	`auth` `app` `worksheet` `worksheet record` `workflow` `approval` `custom-page` `contact` `department` `post` `calendar` `chat` `upload` `config`；每层可用 `hap <group> --help` 查看
脚本输出	所有命令都支持 `--json`
交互模式	`hap repl`，可省略 `hap` 前缀
登录令牌	CLI 使用的是 HAP 登录令牌，不是个人访问令牌（PAT）。三种登录方式用的是同一种令牌： · 浏览器登录：自动获取并保存 · 回调失败：中断命令，粘贴登录成功页显示的令牌 · 脚本 / 无界面服务器：`hap auth login <SERVICE_URL> --token YOUR_TOKEN`，令牌同样来自登录成功页
支持的服务地址	`mingdao`（默认）、`nocoly` 或私有部署地址
多环境 / 多账号	`--profile NAME` 保存具名档案；优先级 `--profile` > `HAP_PROFILE` > 当前档案
默认应用	`--app-id` 未传时使用 `hap app select` 的默认应用；切换组织会清除默认应用

Skills

Skills 是给 AI 的能力说明书：帮 AI 判断何时用哪种能力、如何传参，并在删除、修改等高风险操作前确认。它沿用所配合能力的凭证和权限，不会扩大权限。

技能	配合	前提
MCP 技能（智能搭建应用）	MCP	已配置 MCP
CLI 技能（命令行操作）	CLI	已安装并登录 CLI
API 技能（接口开发）	应用 API	已完成 API 鉴权配置

安装入口：【连接 AI】>【Skills】，或参考 hap-skills。安装 MCP 或 CLI 时已勾选配套 Skills 的，无需重复安装。

应用 API（V3）

入口：应用名称旁的按钮 >【API 开发文档】。V3 遵循 REST 语义，路径以 /v3 开头且对所有应用统一。相比 V2，V3 路径和参数命名更清晰，并新增工作表增删改、工作流、数据聚合和公共查询等能力，新项目建议优先使用 V3。

鉴权请求头

方式	请求头
AppKey + Sign	`HAP-Appkey: <AppKey>`、`HAP-Sign: <Sign>`
PAT / OAuth 2.0	`Authorization: Bearer <token>`；部分接口还需 `HAP-Appid`

请求与响应

GET 参数拼在 URL 后；POST / PUT / PATCH / DELETE 的请求体为 JSON，Content-Type: application/json。
命名：路径 ID 用 snake_case（{worksheet_id}），参数与响应字段用 camelCase，系统字段以 _ 开头（_createdAt、_owner）。批量操作用 /batch。
业务结果看响应体：success 为 true、error_code 为 1 表示成功，0 表示失败，其他值见错误码。

常用接口

分类	代表接口
工作表	`POST /v3/app/worksheets/list`、`POST /v3/app/worksheets`、`GET /v3/app/worksheets/{worksheet_id}`
行记录	`POST .../rows/list`、`POST .../rows`、`PATCH .../rows/{row_id}`、`POST .../rows/batch`、`POST .../rows/pivot`
应用	`GET /v3/app`、`POST /v3/app/items/batch`
视图 / 统计图	`POST .../views/batch`、`POST .../charts`
工作流	获取触发流程列表、触发流程、获取触发流程详情
角色 / 选项集	`GET /v3/app/roles`、`POST /v3/app/roles/{role_id}/members`、`GET /v3/app/optionsets`
知识库 / 对话机器人	`POST /v3/app/knowledge/search`、`POST /v3/app/chatbots`
公共查询	`GET /v3/users/lookup`、`GET /v3/departments/lookup`、`GET /v3/regions/lookup`

... 代表 /v3/app/worksheets/{worksheet_id}。完整列表见应用 API 文档。

筛选记录

filter 由 group（logic 为 AND / OR）和 condition（field、operator、value）组成。最多两层嵌套；同一 group 的 children 只能全是 group 或全是 condition。field 可用字段 ID 或别名。

json

{
  "pageSize": 20,
  "pageIndex": 1,
  "filter": {
    "type": "group",
    "logic": "AND",
    "children": [
      { "type": "condition", "field": "YOUR_FIELD_ID", "operator": "contains", "value": "API" }
    ]
  }
}

各字段支持的运算符见文档「字段类型对照表」；字段表中的「筛选生成器」可直接生成 filter。返回结果给大模型使用时，可加 "responseFormat": "md" 返回更省 token 的 Markdown。

组织 API

组织 API 用于人员组织管理、汇报关系、应用管理和流程待办等组织级数据。密钥仅组织管理员可见。

签名

取当前 Unix 时间戳，单位毫秒。
按 AppKey、SecretKey、Timestamp 的顺序（即按键名字母排序）拼接：AppKey=<AppKey>&SecretKey=<SecretKey>&Timestamp=<TIMESTAMP>。
对字符串做 SHA256，取十六进制摘要字符串，再对该字符串做 Base64 编码，得到 sign。
请求中的 timestamp 必须与签名所用的一致。签名 1 小时内有效。

以上步骤与组织 API 文档中的 Python、Node.js、Java 签名示例一致；文档另提供 C#、Go、PHP 示例。

基础参数

每个请求携带 appKey、sign、timestamp、projectId（组织编号）。GET 放在 Query 中，POST 放在 JSON 请求体中。个别接口（如流程待办）不需要 projectId，以接口说明为准。

地址与返回结构

主机为 https://api.mingdao.com，路径前缀和返回结构因接口分类而不同：

分类	示例地址	成功判断
用户、部门、职位、组织角色、汇报关系	`/generalintegrate/v2/user/getUsers`	`code` 为 1
应用	`/v1/open/app/getByProject`	`error_code` 为 1，`success` 为 true
流程待办	`/workflow/v1/instance/getTodoCount`	`status` 为 1

表中为抽样核对结果，其他分类以各接口文档的地址和响应说明为准。

注意

/v2/department/syncAllDepartments 是全量同步，会重置整个部门关系，慎用。
/v2/user/upsertUsers 单次最多同步 500 个用户。
部分用户同步接口在公有云或平台版不可用，或仅限企业微信、钉钉等集成场景。

05 最佳实践与故障排查

调用规范

先查结构再写数据：确认字段 ID、选项 key、关联字段类型后再写入；关联字段先拿到目标记录 rowId。
先建目标表：关联字段和子表字段依赖 dataSource，必须先创建被关联的工作表。
按需触发工作流：triggerWorkflow 默认为 true；批量导入历史数据前评估是否需要触发。
附件：支持 URL 和 base64；更新时用 updateType 控制覆盖（0）、追加（1）或移除（2）。
AI 接入用最小权限：MCP 优先用应用模式并限定接口范围；先在测试应用中试用。

按现象排查

从上往下逐项检查，大多数问题在前三步就能定位。

现象	先检查	相关错误码
1. 无法连接、超时	域名是否正确（SaaS / 私有部署 `/api` 后缀）、网络和代理、服务地址能否访问	—
2. 鉴权失败	凭证是否完整；请求头名称（`HAP-Appkey`、`HAP-Sign`、`Authorization`）；组织 API 的签名步骤、毫秒时间戳、签名是否超过 1 小时	10101、10102、10105
3. 无权访问	按三层检查：组织策略是否开启 → 凭证范围是否包含该应用和接口 → 身份是否有该操作权限；IP 是否受限	10000、10005、10106、430014
4. 请求失败	参数名和类型、字段 ID、选项值、必填字段、业务规则、子表数据；同时查看 HTTP 状态码	10001、10002、430019、430020、430021
5. 过频或超限	降低频率并加重试与间隔（如 200 ms）；拆小批次、去掉不必要字段	51、90000；HTTP 503、413

限流与请求大小

限流按来源 IP 计算，V2 和 V3 规则不同。

应用 API V3

所有接口统一限流：每 IP 50 QPS。

应用 API V2

接口	每 IP QPS	请求体上限
记录新增、编辑、删除（addRow、addRows、editRow、editRows、deleteRow）	50	16 MB
记录查询（getFilterRows、getFilterRowsTotalNum）	50	—
其他接口	不限	—
私有部署（HAP Server）	不限	25 MB

触发限流时降低请求频率，并加入重试与间隔（如 200 ms）；请求体过大时拆小批次，或去掉不必要的字段。超出限流返回 HTTP 503，请求体过大返回 HTTP 413。

常见错误码

错误码	含义	处理
10101	令牌不存在	检查是否带上凭证、请求头名称是否正确
10102	签名不合法	核对 Sign；组织 API 检查拼接顺序、时间戳是否一致、是否超过 1 小时
10105	用户访问令牌失效	重新创建 PAT 或刷新 OAuth 令牌
10005	数据操作无权限	检查凭证范围和身份权限
10000	IP 受限	检查 IP 白名单
430019	必填字段值为空	补齐必填字段
430021	数据不满足业务规则	对照工作表业务规则调整数据
51 / 90000	请求限流 / 超出次数	降低频率并重试

完整错误码（含 OAuth 错误码）见应用 API 文档。

常见问题

CLI 命令被拦截：组织未开启 CLI 访问策略，请管理员开启后重跑。
CLI 登录收不到回调：中断命令，粘贴登录成功页显示的令牌，或改用 --token 登录。
切换组织后提示缺少 --app-id：切换组织会清除默认应用，用 hap app select 重新选择。
看不到【应用授权】页：只有应用管理员可以创建授权密钥，开发者和运营者角色不可见。
MCP 能连上但操作被拒绝：确认用的是个人访问令牌还是应用密钥、对应哪个应用，检查实际授权范围并刷新工具列表。更多见 MCP 文档的常见问题。

06 相关资源

资源	说明
MCP	访问方式、服务地址、客户端配置、权限与排错
CLI	`hap` 安装、登录与全部命令
应用 API 文档（V3）	鉴权、筛选器、字段类型对照表、API 使用指南
应用 API 文档（PAT 版）	以个人访问令牌调用应用 API
组织 API 文档	组织签名、全部接口与多语言签名示例
API接口列表	在线接口定义
hap-skills	HAP Skills 集合
Model Context Protocol	MCP 官方介绍

HAP 开发指南

适用：明道云 SaaS、私有部署（HAP Server）

本页是 HAP 开放能力的总览入口：帮你判断该用哪种能力，并用最短路径完成第一次调用。完整参数和配置细节，请看各能力的独立文档。

你想做什么？

01 开发方式与能力选型

能力	一句话说明	适合	使用的凭证
MCP	让支持 MCP 的 AI 工具直接调用 HAP 能力	对话式实时操作：了解应用结构、查询分析数据、新增或更新记录	个人访问令牌，或应用密钥
CLI	通过 `hap` 命令执行操作	脚本、批量任务、自动化；也可由 AI 驱动	CLI 登录令牌
应用 API	通过 HTTP 接口读写应用数据与结构	自有系统与 HAP 应用集成	AppKey + Sign、PAT 或 OAuth 2.0
组织 API	通过 HTTP 接口管理组织级数据	成员、部门、汇报关系同步，流程待办与日志	组织密钥（AppKey + SecretKey）
Skills（配套）	告诉 AI 何时用哪种能力、如何传参，高风险操作前先确认	使用 AI 工具时提高准确性	无单独凭证，沿用所配合能力的凭证

选型路径 · 各能力的用途见上表

02 快速开始

四条路径相互独立，选一条即可。每条都写明前提、步骤和「如何确认成功」。

用 AI 操作 HAP（MCP）

前提 AI 工具支持远程 MCP（Streamable HTTP）；用个人访问令牌时，还需支持自定义 HTTP 请求头凭证个人访问令牌或应用密钥

在工作台右上角点击【连接 AI】，打开【MCP】页签，选择安装方式：对话安装或手动安装。
选择要连接的 Agent 工具；列表中没有时选【其他】。
选择权限范围：【个人】选择个人访问令牌；【应用】选择目标应用和授权密钥。
按需勾选【同时安装配套 Skills】，然后完成安装：对话安装点击【安装】，在客户端确认执行；手动安装复制页面生成的命令到终端执行。

用命令行操作 HAP（CLI）

前提 Python 环境；组织已开启 CLI 访问策略凭证 CLI 登录令牌

bash

# 1. 安装
pip install hap-cli

# 2. 登录（默认明道云 SaaS，会打开浏览器）
hap auth login
# 私有部署：hap auth login https://hap.example.com

# 3. 确认身份和组织，CLI 列应显示 on
hap auth whoami
hap auth list-my-orgs

# 4. 选择组织和默认应用
hap auth set-current-org ORG_ID
hap app select APP_ID

# 5. 执行第一条命令
hap worksheet list

如何确认成功　hap worksheet list 返回该应用的工作表列表。若命令被拦截，说明组织未开启 CLI 访问策略，见组织级开关。

想让 AI 用自然语言驱动 CLI：在【连接 AI】>【CLI】安装时勾选配套 Skills。

代码读写应用数据（应用 API V3）

前提你是应用管理员，或管理员已提供密钥凭证 AppKey + Sign

在应用【API 开发文档】>【应用授权】>【新建授权密钥】，记下 AppKey 和 Sign。
调用 POST /v3/app/worksheets/list 找到目标工作表，记下 id。
调用 GET /v3/app/worksheets/{worksheet_id} 获取结构，记下要写入字段的 ID。

新建一条记录（把 {worksheet_id}、YOUR_FIELD_ID 换成实际值）：

bash

curl -X POST "https://api.mingdao.com/v3/app/worksheets/{worksheet_id}/rows" \
  -H "HAP-Appkey: YOUR_APP_KEY" \
  -H "HAP-Sign: YOUR_SIGN" \
  -H "Content-Type: application/json" \
  -d '{
    "triggerWorkflow": true,
    "fields": [
      { "id": "YOUR_FIELD_ID", "value": "First API record" }
    ]
  }'

读取记录：

bash

curl -X POST "https://api.mingdao.com/v3/app/worksheets/{worksheet_id}/rows/list" \
  -H "HAP-Appkey: YOUR_APP_KEY" \
  -H "HAP-Sign: YOUR_SIGN" \
  -H "Content-Type: application/json" \
  -d '{ "pageSize": 20, "pageIndex": 1, "includeTotalCount": true }'

如何确认成功　新建记录返回 "success": true 和新记录的 data.id；读取记录能在 data.rows 中看到它。

如果调用失败：同时检查 HTTP 状态码和响应体中的 success、error_code、error_msg，再按按现象排查定位是鉴权、权限还是请求参数问题。

代码同步组织数据（组织 API）

前提你是组织管理员凭证组织密钥（AppKey + SecretKey）

在组织管理 >【集成】>【其他】>【组织密钥】获取 AppKey 和 SecretKey。
在组织管理 >【组织信息】>【编号(ID)】获取（projectId）。

生成签名，并调用「获取应用列表」接口验证：

python

import base64, hashlib, time
import requests

APP_KEY = "YOUR_APP_KEY"
SECRET_KEY = "YOUR_SECRET_KEY"
PROJECT_ID = "YOUR_PROJECT_ID"

ts = int(time.time() * 1000)  # 毫秒
raw = f"AppKey={APP_KEY}&SecretKey={SECRET_KEY}&Timestamp={ts}"
sign = base64.b64encode(hashlib.sha256(raw.encode("utf-8")).hexdigest().encode("utf-8")).decode("utf-8")

resp = requests.get(
    "https://api.mingdao.com/v1/open/app/getByProject",
    params={"appKey": APP_KEY, "sign": sign, "timestamp": ts, "projectId": PROJECT_ID},
    timeout=10,
)
print(resp.status_code, resp.json())

如何确认成功　按接口文档，成功时返回 "error_code": 1、"success": true，data 中是组织下的应用列表。

03 凭证与权限

创建凭证不等于能访问所有数据。一次调用能否成功，要同时通过三层检查：

组织级访问策略

组织管理员是否开启了 CLI 访问、API 访问等策略。未开启时请求直接被拦截。

凭证自身的范围

凭证属于哪个组织或应用、能调用哪些接口、是否过期。例如 PAT 创建时会设定组织、应用范围、接口范围和有效期。

身份的实际权限

凭证所代表的身份在 HAP 中能做什么。个人身份受用户角色权限约束；应用身份按应用管理员权限操作。

凭证一览

凭证	代表谁	权限依据	谁能创建 · 入口	什么时候选它
个人访问令牌（PAT）	当前用户	用户本人的权限 + 令牌设定的组织、应用、接口范围；到期失效	任意用户 · 头像 >【授权与访问】>【添加】	MCP 个人模式；需要按具体用户权限调用应用 API
应用授权密钥（AppKey + Sign）	应用管理员（不代表具体用户）	密钥所属应用 + 密钥的 API 权限范围；长期有效	应用管理员 · 应用【API 开发文档】>【应用授权】>【新建授权密钥】	服务端集成、定时同步；MCP 应用模式
OAuth 2.0 访问令牌	授权的用户	用户权限 + 授权时申请的 scope；短效，可用刷新令牌续期	由用户授权第三方应用 · 见应用 API 文档	第三方应用代表用户访问
CLI 登录令牌	登录的用户	用户本人的权限 + 组织是否开启 CLI 访问策略。这是 HAP 登录令牌，不是 PAT	任意用户 · `hap auth login` 浏览器登录后自动获取，或从登录成功页复制	使用 CLI
组织密钥（AppKey + SecretKey）	组织	组织级接口权限，读取权限较高；签名 1 小时内有效	仅组织管理员 · 组织管理 >【集成】>【其他】>【组织密钥】	成员、部门同步等组织级集成

组织级开关

以下两项策略都在组织管理 >【安全】>【数据与访问】中，由组织管理员开启：

CLI 访问策略：未开启时，hap 命令无法访问该组织数据。运行 hap auth list-my-orgs 可查看各组织的开启状态（CLI:on 或 CLI:off）。
API 访问策略：未开启时，无法使用个人访问令牌（PAT）或应用授权密钥访问该组织数据，依赖这两种凭证的 MCP 连接也会失败。

环境与地址

环境	应用 API	组织 API	CLI 登录
明道云 SaaS	`https://api.mingdao.com/v3/...`	主机 `https://api.mingdao.com`，路径前缀因接口分类而异（见组织 API）	`hap auth login`
私有部署	`{YOUR_HOST}/api/v3/...`	在组织管理中打开的文档会自动使用部署域名	`hap auth login https://YOUR_HOST`

本页示例基于明道云 SaaS。其他环境（如 Nocoly）请参考对应环境的开发文档。

凭证安全

只在可信服务端保存密钥和令牌，不要写进浏览器前端、客户端或公开仓库。

为不同系统分别创建凭证，按需授予最小范围；PAT 设置有效期。凭证疑似泄露时，立即停用并重新创建。

04 能力使用指南

本节是各能力的要点速查。完整说明以对应的独立文档为准。

MCP

要点	说明
服务地址	明道云 SaaS：`https://api.mingdao.com/mcp`，Streamable HTTP。私有部署使用本环境生成的完整地址，保留路径前缀
个人访问令牌	以个人身份协助日常业务；请求头 `Authorization: Bearer <TOKEN>`，客户端需支持自定义请求头
应用密钥	围绕指定应用做业务集成；URL 参数 `HAP-Appkey`、`HAP-Sign`，直接复制应用管理 >【API 文档】>【应用授权】>【MCP】生成的完整 URL
手动配置	优先使用界面生成的对应客户端配置；各客户端字段不同，按客户端说明填写
权限	连接 MCP 不会扩大凭据权限；工具可见不代表有数据操作权限。授权变化后刷新工具列表
验证	以客户端成功加载工具并完成一次读取为准，不能只用浏览器打开地址判断

CLI

要点	说明
命令组	`auth` `app` `worksheet` `worksheet record` `workflow` `approval` `custom-page` `contact` `department` `post` `calendar` `chat` `upload` `config`；每层可用 `hap <group> --help` 查看
脚本输出	所有命令都支持 `--json`
交互模式	`hap repl`，可省略 `hap` 前缀
登录令牌	CLI 使用的是 HAP 登录令牌，不是个人访问令牌（PAT）。三种登录方式用的是同一种令牌： · 浏览器登录：自动获取并保存 · 回调失败：中断命令，粘贴登录成功页显示的令牌 · 脚本 / 无界面服务器：`hap auth login <SERVICE_URL> --token YOUR_TOKEN`，令牌同样来自登录成功页
支持的服务地址	`mingdao`（默认）、`nocoly` 或私有部署地址
多环境 / 多账号	`--profile NAME` 保存具名档案；优先级 `--profile` > `HAP_PROFILE` > 当前档案
默认应用	`--app-id` 未传时使用 `hap app select` 的默认应用；切换组织会清除默认应用

Skills

技能	配合	前提
MCP 技能（智能搭建应用）	MCP	已配置 MCP
CLI 技能（命令行操作）	CLI	已安装并登录 CLI
API 技能（接口开发）	应用 API	已完成 API 鉴权配置

安装入口：【连接 AI】>【Skills】，或参考 hap-skills。安装 MCP 或 CLI 时已勾选配套 Skills 的，无需重复安装。

应用 API（V3）

鉴权请求头

方式	请求头
AppKey + Sign	`HAP-Appkey: <AppKey>`、`HAP-Sign: <Sign>`
PAT / OAuth 2.0	`Authorization: Bearer <token>`；部分接口还需 `HAP-Appid`

请求与响应

GET 参数拼在 URL 后；POST / PUT / PATCH / DELETE 的请求体为 JSON，Content-Type: application/json。
命名：路径 ID 用 snake_case（{worksheet_id}），参数与响应字段用 camelCase，系统字段以 _ 开头（_createdAt、_owner）。批量操作用 /batch。
业务结果看响应体：success 为 true、error_code 为 1 表示成功，0 表示失败，其他值见错误码。

常用接口

分类	代表接口
工作表	`POST /v3/app/worksheets/list`、`POST /v3/app/worksheets`、`GET /v3/app/worksheets/{worksheet_id}`
行记录	`POST .../rows/list`、`POST .../rows`、`PATCH .../rows/{row_id}`、`POST .../rows/batch`、`POST .../rows/pivot`
应用	`GET /v3/app`、`POST /v3/app/items/batch`
视图 / 统计图	`POST .../views/batch`、`POST .../charts`
工作流	获取触发流程列表、触发流程、获取触发流程详情
角色 / 选项集	`GET /v3/app/roles`、`POST /v3/app/roles/{role_id}/members`、`GET /v3/app/optionsets`
知识库 / 对话机器人	`POST /v3/app/knowledge/search`、`POST /v3/app/chatbots`
公共查询	`GET /v3/users/lookup`、`GET /v3/departments/lookup`、`GET /v3/regions/lookup`

... 代表 /v3/app/worksheets/{worksheet_id}。完整列表见应用 API 文档。

筛选记录

json

{
  "pageSize": 20,
  "pageIndex": 1,
  "filter": {
    "type": "group",
    "logic": "AND",
    "children": [
      { "type": "condition", "field": "YOUR_FIELD_ID", "operator": "contains", "value": "API" }
    ]
  }
}

组织 API

组织 API 用于人员组织管理、汇报关系、应用管理和流程待办等组织级数据。密钥仅组织管理员可见。

签名

取当前 Unix 时间戳，单位毫秒。
按 AppKey、SecretKey、Timestamp 的顺序（即按键名字母排序）拼接：AppKey=<AppKey>&SecretKey=<SecretKey>&Timestamp=<TIMESTAMP>。
对字符串做 SHA256，取十六进制摘要字符串，再对该字符串做 Base64 编码，得到 sign。
请求中的 timestamp 必须与签名所用的一致。签名 1 小时内有效。

以上步骤与组织 API 文档中的 Python、Node.js、Java 签名示例一致；文档另提供 C#、Go、PHP 示例。

基础参数

地址与返回结构

主机为 https://api.mingdao.com，路径前缀和返回结构因接口分类而不同：

分类	示例地址	成功判断
用户、部门、职位、组织角色、汇报关系	`/generalintegrate/v2/user/getUsers`	`code` 为 1
应用	`/v1/open/app/getByProject`	`error_code` 为 1，`success` 为 true
流程待办	`/workflow/v1/instance/getTodoCount`	`status` 为 1

表中为抽样核对结果，其他分类以各接口文档的地址和响应说明为准。

注意

/v2/department/syncAllDepartments 是全量同步，会重置整个部门关系，慎用。
/v2/user/upsertUsers 单次最多同步 500 个用户。
部分用户同步接口在公有云或平台版不可用，或仅限企业微信、钉钉等集成场景。

05 最佳实践与故障排查

调用规范

先查结构再写数据：确认字段 ID、选项 key、关联字段类型后再写入；关联字段先拿到目标记录 rowId。
先建目标表：关联字段和子表字段依赖 dataSource，必须先创建被关联的工作表。
按需触发工作流：triggerWorkflow 默认为 true；批量导入历史数据前评估是否需要触发。
附件：支持 URL 和 base64；更新时用 updateType 控制覆盖（0）、追加（1）或移除（2）。
AI 接入用最小权限：MCP 优先用应用模式并限定接口范围；先在测试应用中试用。

按现象排查

从上往下逐项检查，大多数问题在前三步就能定位。

现象	先检查	相关错误码
1. 无法连接、超时	域名是否正确（SaaS / 私有部署 `/api` 后缀）、网络和代理、服务地址能否访问	—
2. 鉴权失败	凭证是否完整；请求头名称（`HAP-Appkey`、`HAP-Sign`、`Authorization`）；组织 API 的签名步骤、毫秒时间戳、签名是否超过 1 小时	10101、10102、10105
3. 无权访问	按三层检查：组织策略是否开启 → 凭证范围是否包含该应用和接口 → 身份是否有该操作权限；IP 是否受限	10000、10005、10106、430014
4. 请求失败	参数名和类型、字段 ID、选项值、必填字段、业务规则、子表数据；同时查看 HTTP 状态码	10001、10002、430019、430020、430021
5. 过频或超限	降低频率并加重试与间隔（如 200 ms）；拆小批次、去掉不必要字段	51、90000；HTTP 503、413

限流与请求大小

限流按来源 IP 计算，V2 和 V3 规则不同。

应用 API V3

所有接口统一限流：每 IP 50 QPS。

应用 API V2

接口	每 IP QPS	请求体上限
记录新增、编辑、删除（addRow、addRows、editRow、editRows、deleteRow）	50	16 MB
记录查询（getFilterRows、getFilterRowsTotalNum）	50	—
其他接口	不限	—
私有部署（HAP Server）	不限	25 MB

常见错误码

错误码	含义	处理
10101	令牌不存在	检查是否带上凭证、请求头名称是否正确
10102	签名不合法	核对 Sign；组织 API 检查拼接顺序、时间戳是否一致、是否超过 1 小时
10105	用户访问令牌失效	重新创建 PAT 或刷新 OAuth 令牌
10005	数据操作无权限	检查凭证范围和身份权限
10000	IP 受限	检查 IP 白名单
430019	必填字段值为空	补齐必填字段
430021	数据不满足业务规则	对照工作表业务规则调整数据
51 / 90000	请求限流 / 超出次数	降低频率并重试

完整错误码（含 OAuth 错误码）见应用 API 文档。

常见问题

CLI 命令被拦截：组织未开启 CLI 访问策略，请管理员开启后重跑。
CLI 登录收不到回调：中断命令，粘贴登录成功页显示的令牌，或改用 --token 登录。
切换组织后提示缺少 --app-id：切换组织会清除默认应用，用 hap app select 重新选择。
看不到【应用授权】页：只有应用管理员可以创建授权密钥，开发者和运营者角色不可见。
MCP 能连上但操作被拒绝：确认用的是个人访问令牌还是应用密钥、对应哪个应用，检查实际授权范围并刷新工具列表。更多见 MCP 文档的常见问题。

06 相关资源

资源	说明
MCP	访问方式、服务地址、客户端配置、权限与排错
CLI	`hap` 安装、登录与全部命令
应用 API 文档（V3）	鉴权、筛选器、字段类型对照表、API 使用指南
应用 API 文档（PAT 版）	以个人访问令牌调用应用 API
组织 API 文档	组织签名、全部接口与多语言签名示例
API接口列表	在线接口定义
hap-skills	HAP Skills 集合
Model Context Protocol	MCP 官方介绍