Smithery is now a part of Arcade.dev! Read more in our announcement here
使用明道云 HAP V3 接口搭建页面和操作数据的专业技能。当用户提到"HAP V3 接口"、"HAP API"、"接口调用"、"数据接口"、"Appkey"、"Sign"、"接口鉴权"等需求时,必须使用此技能。此技能提供完整的 HAP V3 接口使用指南:鉴权配置、接口调用、筛选器使用、数据操作等。如果用户已配置 HAP MCP，AI 应该自动从 MCP 配置中提取鉴权密钥。
此技能提供使用明道云 HAP V3 接口搭建页面、实时获取数据和操作数据的完整指南。
明道云 HAP (High-performance Application Platform) 是一个超级应用平台,通过这个基座可以搭建很多应用。通过 HAP V3 接口,您可以:
核心能力:
详细文档: 参考 references/hap-api-usage-guide.md 获取完整的 API 使用规范
方法一: 从 MCP 配置中提取（推荐）
如果用户已经配置了 HAP 应用执行 MCP，AI 助手应该自动从 MCP 配置中提取鉴权密钥，而不是让用户手动输入。
读取 Cursor 全局设置文件
~/Library/Application Support/Cursor/User/settings.json%APPDATA%\Cursor\User\settings.json~/.config/Cursor/User/settings.json查找 MCP 配置
mcpServers 对象中查找以 hap-mcp- 开头的服务器配置url 字段且 URL 指向 api.mingdao.com/mcp）从 URL 中解析参数
{
"mcpServers": {
"hap-mcp-应用名": {
"url": "https://api.mingdao.com/mcp?HAP-Appkey=6802bfa5da37d75f&HAP-Sign=MWZmZWU1YmMyMzE4ZTAxYjY3NTViYjM5NzhlNTdhOTIwZWFhYTc2Y2I2YzljNWMzNDFmMjk4NTM2N2M0YTg2OA==",
"type": "http"
}
}
}
提取鉴权密钥
HAP-Appkey 的值HAP-Sign 的值// 1. 读取配置文件
const settingsPath = process.platform === 'darwin'
? `${process.env.HOME}/Library/Application Support/Cursor/User/settings.json`
: process.platform === 'win32'
? `${process.env.APPDATA}/Cursor/User/settings.json`
: `${process.env.HOME}/.config/Cursor/User/settings.json`;
const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
// 2. 查找 HAP MCP 配置
const mcpServers = settings.mcpServers || {};
const hapMcpConfig = Object.entries(mcpServers).find(
([name, config]) => name.startsWith('hap-mcp-') && config.url
);
if (hapMcpConfig) {
const [, config] = hapMcpConfig;
const url = new URL(config.url);
// 3. 提取 Appkey 和 Sign
const appkey = url.searchParams.get('HAP-Appkey');
const sign = url.searchParams.get('HAP-Sign');
// 4. 使用提取的密钥
console.log('Appkey:', appkey);
console.log('Sign:', sign);
}
当用户需要调用 HAP API 时，AI 应该：
检查是否已配置 MCP
hap-mcp-* 配置提取鉴权信息
使用提取的密钥
HAP-Appkey 和 HAP-Sign方法二: 手动获取
如果用户未配置 MCP 或需要手动提供：
所有 HAP V3 API 请求都需要以下请求头:
const headers = {
'Content-Type': 'application/json',
'HAP-Appkey': 'your-app-key',
'HAP-Sign': 'your-sign-key'
};
⚠️ 注意: 请求头使用 HAP-Appkey 和 HAP-Sign（不是 AppKey 和 Sign）
使用 Apifox MCP Server（推荐）:
{
"应用 API - API 文档": {
"command": "npx",
"args": [
"-y",
"apifox-mcp-server@latest",
"--site-id=5442569"
]
}
}
在线文档资源:
Step 1: 获取 API 凭证
Step 2: 配置 API 请求头
HAP-Appkey 和 HAP-Sign 请求头Step 3: 获取应用信息（可选）
GET /v3/app/info
Step 4: 创建工作表
POST /v3/app/worksheets
{
"name": "客户信息表",
"alias": "customers",
"fields": [
{
"name": "客户名称",
"alias": "customer_name",
"type": "Text",
"isTitle": true,
"required": true
}
]
}
详细规范: 参考 references/hap-api-usage-guide.md 第 1 节
Step 5: 准备选项字段映射
Step 6: 创建记录
POST /v3/app/worksheets/{worksheet_id}/rows
{
"fields": [
{
"id": "customer_name",
"value": "明道云科技有限公司"
},
{
"id": "customer_type",
"value": ["74c7b607-864d-4cc4-b401-28acba2636e9"] // ⚠️ 使用选项key
}
],
"triggerWorkflow": true
}
关键点:
详细规范: 参考 references/hap-api-usage-guide.md 第 3 节
Step 7: 查询记录列表
POST /v3/app/worksheets/{worksheet_id}/rows/list
{
"filter": {
"type": "group",
"logic": "AND",
"children": [
{
"type": "condition",
"field": "customer_type",
"operator": "eq",
"value": ["74c7b607-864d-4cc4-b401-28acba2636e9"] // 使用key
}
]
},
"sorts": [{
"field": "annual_budget",
"isAsc": false
}],
"pageIndex": 1,
"pageSize": 20
}
详细规范: 参考 references/hap-api-usage-guide.md 第 4 节
基础结构:
Filter = {
type: 'group' | 'condition';
// type='group' 时的字段
logic?: 'AND' | 'OR';
children?: Filter[]; // 子条件,最多两层嵌套
// type='condition' 时的字段
field?: string; // 字段ID或别名
operator?: string; // 操作符
value?: any[]; // 值数组
}
规则:
group 类型logic (AND/OR)field, operator| 操作符 | 说明 | 需要value | value格式 | 适用字段 |
|---|---|---|---|---|
eq |
等于 | ✅ | ["值"] |
所有类型 |
ne |
不等于 | ✅ | ["值"] |
所有类型 |
contains |
包含 | ✅ | ["值"] |
Text, MultipleSelect |
notcontains |
不包含 | ✅ | ["值"] |
Text, MultipleSelect |
startswith |
开头是 | ✅ | ["值"] |
Text |
endswith |
结尾是 | ✅ | ["值"] |
Text |
gt |
大于 | ✅ | ["值"] |
Number, Date |
gte |
大于等于 | ✅ | ["值"] |
Number, Date |
lt |
小于 | ✅ | ["值"] |
Number, Date |
lte |
小于等于 | ✅ | ["值"] |
Number, Date |
between |
介于之间 | ✅ | ["最小值", "最大值"] |
Number, Date |
isempty |
为空 | ❌ | 不需要 | 所有类型 |
isnotempty |
不为空 | ❌ | 不需要 | 所有类型 |
belongsto |
属于 | ✅ | ["ID1", "ID2"] |
Relation, Department |
in |
在...中 | ✅ | ["值1", "值2"] |
所有类型 |
concurrent |
同时包含 | ✅ | ["值1", "值2"] |
MultipleSelect |
示例1: 单选字段筛选（⚠️ 必须使用 key）
{
"type": "group",
"logic": "AND",
"children": [{
"type": "condition",
"field": "customer_type",
"operator": "eq",
"value": ["74c7b607-864d-4cc4-b401-28acba2636e9"] // ✅ 使用key
}]
}
// ❌ 错误: value: ["成交客户"] // 不能用显示文本!
示例2: 数值范围筛选（⚠️ value 必须是字符串数组）
{
"type": "condition",
"field": "annual_budget",
"operator": "between",
"value": ["500000", "2000000"] // ✅ 字符串数组
}
// ❌ 错误: value: [500000, 2000000] // 不能用数字!
示例3: 关联字段筛选（⚠️ 必须用 belongsto）
{
"type": "condition",
"field": "related_customer",
"operator": "belongsto", // ✅ 关联字段用 belongsto
"value": ["customer-row-id"]
}
// ❌ 错误: operator: "eq" // 关联字段不支持 eq!
详细规范: 参考 references/hap-api-usage-guide.md 第 4 节
写入: 必须传选项 key 的数组
{
"id": "customer_type",
"value": ["74c7b607-864d-4cc4-b401-28acba2636e9"] // 选项key
}
读取: 返回包含 key 和 value 的对象数组
{
"customer_type": [
{
"key": "74c7b607-864d-4cc4-b401-28acba2636e9",
"value": "成交客户"
}
]
}
⚠️ 关键点:
["key"]["成交客户"],必须用 key写入: 支持 URL 和 base64
{
"id": "attachments",
"type": "0", // 0=覆盖, 1=追加
"value": [{
"name": "产品宣传册.pdf",
"url": "https://example.com/brochure.pdf"
}]
}
读取: 返回附件对象数组
{
"attachments": [{
"file_id": "...",
"file_name": "...",
"downloadUrl": "https://...", // ⚠️ 使用 downloadUrl
"file_size": 2048576
}]
}
⚠️ 重要提示:
downloadUrl 而非 url写入: 传记录 ID 数组
{
"id": "related_customer",
"value": ["945e6503-3823-4e91-9d84-a53f8bdd6fc5"] // 记录rowid
}
读取: 返回对象数组（只包含 sid 和 name）
{
"related_customer": [{
"sid": "945e6503-3823-4e91-9d84-a53f8bdd6fc5",
"name": "明道云科技有限公司"
}]
}
获取完整关联数据:
// 方法1: 使用专用 API
GET /v3/app/worksheets/{worksheet_id}/rows/{row_id}/relations/{field_id}
// 方法2: 使用 sid 查询目标表
POST /v3/app/worksheets/{target_worksheet_id}/rows/list
{
"filter": {
"type": "group",
"logic": "AND",
"children": [{
"type": "condition",
"field": "rowid", // ⚠️ 使用系统字段 rowid
"operator": "in",
"value": ["sid1", "sid2"] // 传入关联记录的 sid
}]
}
}
详细规范: 参考 references/hap-api-usage-guide.md 第 6 节
写入: 传用户 ID 数组
{
"id": "owner",
"value": ["user-account-id-123"] // 用户ID,不是用户名
}
获取用户ID:
POST /v3/users/lookup
{
"name": "张三" // 精确匹配姓名
}
写入: 传数字类型
{
"id": "annual_budget",
"value": 1000000.50
}
读取: 返回字符串
{
"annual_budget": "1000000.50"
}
⚠️ 注意: 写入数字,读取字符串
详细规范: 参考 references/hap-api-usage-guide.md 第 2、3 节
triggerWorkflow 参数控制是否在数据操作时触发工作表相关的工作流。
适用范围:
参数说明:
| 参数值 | 说明 | 默认值 | 使用场景 |
|---|---|---|---|
true |
触发工作流 | ✅ 是 | 正常业务操作,需要执行自动化流程 |
false |
不触发工作流 | ❌ 否 | 数据迁移、批量初始化、测试数据 |
✅ 应该设置为 true 的场景:
❌ 应该设置为 false 的场景:
性能影响:
triggerWorkflow: false - API 响应快,通常 < 500mstriggerWorkflow: true - 需要等待工作流执行,可能需要 1-5 秒详细说明: 参考 references/hap-api-usage-guide.md 第 3.2 节
问题: 筛选单选/多选字段时返回空结果
错误示例:
{
"field": "customer_type",
"operator": "eq",
"value": ["成交客户"] // ❌ 使用了显示文本
}
正确做法:
{
"field": "customer_type",
"operator": "eq",
"value": ["74c7b607-864d-4cc4-b401-28acba2636e9"] // ✅ 使用选项key
}
解决方案:
问题: 数值筛选无结果或报错
错误示例:
{
"field": "annual_budget",
"operator": "gt",
"value": [1000000] // ❌ 数字类型
}
正确做法:
{
"field": "annual_budget",
"operator": "gt",
"value": ["1000000"] // ✅ 字符串数组
}
记忆口诀: 筛选条件的 value 永远是字符串数组
问题: 使用错误的操作符筛选关联字段
错误示例:
{
"field": "related_customer",
"operator": "eq", // ❌ 关联字段不支持 eq
"value": ["customer-id"]
}
正确做法:
{
"field": "related_customer",
"operator": "belongsto", // ✅ 使用 belongsto
"value": ["customer-id"]
}
问题: 在列表页逐个查询关联数据
错误示例:
// ❌ 性能灾难:100个产品 = 1 + 100 = 101次请求
const products = await getProductList(); // 1次请求
for (const product of products) {
const categoryId = product.category[0].sid;
const category = await getCategoryById(categoryId); // 100次请求!
}
正确做法: 批量查询
// ✅ 性能优化:100个产品 = 1 + 1 = 2次请求
const products = await getProductList(); // 1次请求
// 收集所有分类ID
const categoryIds = new Set();
products.forEach(p => {
if (p.category && p.category.length > 0) {
categoryIds.add(p.category[0].sid);
}
});
// 批量查询所有分类
const categories = await getRows('category-worksheet-id', {
filter: {
type: 'condition',
field: 'rowid',
operator: 'in',
value: Array.from(categoryIds)
}
}); // 1次请求
// 建立映射
const categoryMap = {};
categories.rows.forEach(cat => {
categoryMap[cat.rowid] = cat;
});
详细说明: 参考 references/hap-api-usage-guide.md 第 7 节
详细说明: 参考 references/hap-api-usage-guide.md 第 8 节
当用户需要调用 HAP V3 API 时，AI 助手应该遵循以下原则：
优先级顺序：
优先从 MCP 配置提取（推荐）
hap-mcp-* 配置HAP-Appkey 和 HAP-Sign用户手动提供
引导配置 MCP
提取到密钥后，自动配置请求头：
const headers = {
'Content-Type': 'application/json',
'HAP-Appkey': extractedAppkey, // 从 MCP 配置提取
'HAP-Sign': extractedSign // 从 MCP 配置提取
};
如果用户配置了多个 HAP MCP：
场景: 用户说"帮我调用 HAP API 查询数据"
AI 操作流程:
~/Library/Application Support/Cursor/User/settings.jsonmcpServers 中的 hap-mcp-* 配置场景: 用户提供了 MCP 配置信息
AI 操作流程:
必做事项:
示例代码:
// 1. 获取工作表结构
const structure = await getWorksheetStructure(worksheetId);
// 2. 提取选项字段映射
const optionMaps = {};
structure.fields.forEach(field => {
if (field.type === 'SingleSelect' || field.type === 'MultipleSelect') {
optionMaps[field.id] = {};
field.options.forEach(opt => {
optionMaps[field.id][opt.value] = opt.key; // value → key
});
}
});
// 3. 使用时查找key
const customerTypeKey = optionMaps['customer_type']['成交客户'];
建议:
检查清单:
常见错误码:
error_code: 1 - 成功error_code: -1 - 失败,查看 error_msgerror_code: 4 - 权限不足error_code: 10 - 参数错误建议: 所有 API 调用都要检查 error_code 和 success
详细说明: 参考 references/hap-api-usage-guide.md 第 9 节
| 场景 | API 端点 | 关键参数 |
|---|---|---|
| 创建工作表 | POST /v3/app/worksheets |
fields |
| 添加字段 | POST /v3/app/worksheets/{id} |
addFields |
| 创建记录 | POST /v3/app/worksheets/{id}/rows |
fields |
| 批量创建 | POST /v3/app/worksheets/{id}/rows/batch |
rows |
| 查询记录 | POST /v3/app/worksheets/{id}/rows/list |
filter, sorts |
| 更新记录 | POST /v3/app/worksheets/{id}/rows/{row_id} |
fields |
| 批量更新 | PUT /v3/app/worksheets/{id}/rows/batch |
rowIds, fields |
| 删除记录 | DELETE /v3/app/worksheets/{id}/rows/{row_id} |
permanent |
| 批量删除 | DELETE /v3/app/worksheets/{id}/rows/batch |
rowIds, permanent |
| 透视分析 | POST /v3/app/worksheets/{id}/rows/pivot |
rows, values |
| 查找用户 | POST /v3/users/lookup |
name |
| 查找部门 | POST /v3/departments/lookup |
name |
| 获取地区 | POST /v3/regions |
search, id |
references/hap-api-usage-guide.md - HAP V3 API 使用规范完整指南字段类型 (type):
Text, Number, Date, TimeSingleSelect, MultipleSelectRelation, Collaborator, DepartmentAttachment, Rating筛选操作符 (operator):
eq, ne, gt, gte, lt, ltecontains, startswith, endswithbetween, inbelongstoisempty, isnotemptysubType 参数:
0=单选, 1=多选1=单条, 2=多条1=时:分, 6=时:分:秒3=年月日, 6=年月日时分秒筛选无结果:
创建/更新失败:
数据异常:
技能版本: v2.0
最后更新: 2026-01-11
基于: HAP API V3
详细规范: 参考 references/hap-api-usage-guide.md
