名称： netpad
描述： "管理 NetPad 的表单、提交、用户和基于角色的访问控制（RBAC）。适用于以下场景：(1) 创建包含自定义字段的表单，(2) 向表单提交数据，(3) 查询表单提交记录，(4) 管理用户/群组/角色（RBAC），(5) 从应用市场安装 NetPad 应用。使用 API 需要 NETPAD_API_KEY，使用 CLI 需要执行 netpad login。"
元数据： {"clawdbot":{"emoji":"📋","requires":{"bins":["curl","jq","netpad"]},"install":[{"id":"cli","kind":"node","package":"@netpad/cli","bins":["netpad"],"label":"安装 NetPad CLI (npm)"}],"author":{"name":"Michael Lynn","github":"mrlynn","website":"https://mlynn.org","linkedin":"https://linkedin.com/in/mlynn"}}}

NetPad

通过命令行界面（CLI）和 REST API 管理表单、提交、用户和基于角色的访问控制（RBAC）。

两种工具

身份验证

export NETPAD_API_KEY="np_live_xxx"  # 生产环境
export NETPAD_API_KEY="np_test_xxx"  # 测试环境（可向草稿表单提交）

所有请求均使用 Bearer 令牌：

curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/..."

快速参考

项目

表单归属于项目。创建表单前需要先获取项目 ID。

# 列出项目
curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/projects" | jq '.data[] | {projectId, name}'

表单

列出表单

curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms?status=published&pageSize=50"

创建表单

curl -X POST -H "Authorization: Bearer $NETPAD_API_KEY" \
  -H "Content-Type: application/json" \
  "https://www.netpad.io/api/v1/forms" \
  -d '{
    "name": "联系表单",
    "description": "简单的联系表单",
    "projectId": "proj_xxx",
    "fields": [
      {"path": "name", "label": "姓名", "type": "text", "required": true},
      {"path": "email", "label": "邮箱", "type": "email", "required": true},
      {"path": "phone", "label": "电话", "type": "phone"},
      {"path": "message", "label": "留言", "type": "textarea"}
    ]
  }'

获取表单详情

curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms/{formId}"

发布表单

curl -X PATCH -H "Authorization: Bearer $NETPAD_API_KEY" \
  -H "Content-Type: application/json" \
  "https://www.netpad.io/api/v1/forms/{formId}" \
  -d '{"status": "published"}'

更新表单字段

curl -X PATCH -H "Authorization: Bearer $NETPAD_API_KEY" \
  -H "Content-Type: application/json" \
  "https://www.netpad.io/api/v1/forms/{formId}" \
  -d '{
    "fields": [
      {"path": "name", "label": "全名", "type": "text", "required": true},
      {"path": "email", "label": "邮箱地址", "type": "email", "required": true},
      {"path": "company", "label": "公司", "type": "text"},
      {"path": "role", "label": "角色", "type": "select", "options": [
        {"value": "dev", "label": "开发者"},
        {"value": "pm", "label": "产品经理"},
        {"value": "exec", "label": "高管"}
      ]}
    ]
  }'

删除表单

curl -X DELETE -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms/{formId}"

提交

提交数据

curl -X POST -H "Authorization: Bearer $NETPAD_API_KEY" \
  -H "Content-Type: application/json" \
  "https://www.netpad.io/api/v1/forms/{formId}/submissions" \
  -d '{
    "data": {
      "name": "张三",
      "email": "zhangsan@example.com",
      "message": "通过 API 发送问候！"
    }
  }'

列出提交

# 最近的提交
curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms/{formId}/submissions?pageSize=50"

# 使用日期筛选
curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms/{formId}/submissions?startDate=2026-01-01T00:00:00Z"

# 升序排序
curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms/{formId}/submissions?sortOrder=asc"

获取单个提交

curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms/{formId}/submissions/{submissionId}"

删除提交

curl -X DELETE -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms/{formId}/submissions/{submissionId}"

字段类型

字段模式

{
  "path": "fieldName",
  "label": "显示标签",
  "type": "text",
  "required": true,
  "placeholder": "提示文本",
  "helpText": "额外指导信息",
  "options": [{"value": "a", "label": "选项 A"}],
  "validation": {
    "minLength": 1,
    "maxLength": 500,
    "pattern": "^[A-Z].*",
    "min": 0,
    "max": 100
  }
}

常用模式

创建并发布表单

# 1. 创建草稿
RESULT=$(curl -s -X POST -H "Authorization: Bearer $NETPAD_API_KEY" \
  -H "Content-Type: application/json" \
  "https://www.netpad.io/api/v1/forms" \
  -d '{"name":"调查问卷","projectId":"proj_xxx","fields":[...]}')
FORM_ID=$(echo $RESULT | jq -r '.data.id')

# 2. 发布
curl -X PATCH -H "Authorization: Bearer $NETPAD_API_KEY" \
  -H "Content-Type: application/json" \
  "https://www.netpad.io/api/v1/forms/$FORM_ID" \
  -d '{"status":"published"}'

导出所有提交

curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms/{formId}/submissions?pageSize=1000" \
  | jq '.data[].data'

批量提交

for row in $(cat data.json | jq -c '.[]'); do
  curl -s -X POST -H "Authorization: Bearer $NETPAD_API_KEY" \
    -H "Content-Type: application/json" \
    "https://www.netpad.io/api/v1/forms/{formId}/submissions" \
    -d "{\"data\":$row}"
done

搜索表单

curl -H "Authorization: Bearer $NETPAD_API_KEY" \
  "https://www.netpad.io/api/v1/forms?search=contact&status=published"

辅助脚本

使用 scripts/netpad.sh 执行常见操作：

# 赋予执行权限
chmod +x scripts/netpad.sh

# 使用方法
./scripts/netpad.sh projects list
./scripts/netpad.sh forms list published
./scripts/netpad.sh forms create "联系表单" proj_xxx
./scripts/netpad.sh forms publish frm_xxx
./scripts/netpad.sh submissions list frm_xxx
./scripts/netpad.sh submissions create frm_xxx '{"name":"张三","email":"zhangsan@example.com"}'
./scripts/netpad.sh submissions export frm_xxx > data.jsonl
./scripts/netpad.sh submissions count frm_xxx

速率限制

响应头：X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

响应格式

成功

{
  "success": true,
  "data": { ... },
  "pagination": {"total": 100, "page": 1, "pageSize": 20, "hasMore": true},
  "requestId": "uuid"
}

错误

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "描述",
    "details": {}
  },
  "requestId": "uuid"
}

环境变量

# REST API 必需
export NETPAD_API_KEY="np_live_xxx"

# 可选（用于本地/暂存环境）
export NETPAD_BASE_URL="https://staging.netpad.io/api/v1"

NetPad 命令行工具 (@netpad/cli)

安装：npm i -g @netpad/cli

身份验证

netpad login              # 打开浏览器登录
netpad whoami             # 检查认证状态
netpad logout             # 清除凭证

应用市场与包管理

# 搜索应用
netpad search "helpdesk"

# 安装应用
netpad install @netpad/helpdesk-app

# 列出已安装应用
netpad list

# 创建新应用脚手架
netpad create-app my-app

# 提交到应用市场
netpad submit ./my-app

RBAC - 用户管理

# 列出组织成员
netpad users list -o org_xxx

# 添加用户
netpad users add user@example.com -o org_xxx --role member

# 更改角色
netpad users update user@example.com -o org_xxx --role admin

# 移除用户
netpad users remove user@example.com -o org_xxx

RBAC - 群组管理

# 列出群组
netpad groups list -o org_xxx

# 创建群组
netpad groups create "工程部" -o org_xxx

# 将用户加入群组
netpad groups add-member grp_xxx user@example.com -o org_xxx

# 删除群组
netpad groups delete grp_xxx -o org_xxx

RBAC - 角色管理

# 列出角色（内置 + 自定义）
netpad roles list -o org_xxx

# 创建自定义角色
netpad roles create "审核员" -o org_xxx --base viewer --description "可以审核提交"

# 查看角色详情
netpad roles get role_xxx -o org_xxx

# 删除自定义角色
netpad roles delete role_xxx -o org_xxx

RBAC - 权限分配

# 为用户分配角色
netpad assign user user@example.com role_xxx -o org_xxx

# 为群组分配角色
netpad assign group grp_xxx role_xxx -o org_xxx

# 移除分配
netpad unassign user user@example.com role_xxx -o org_xxx

RBAC - 权限检查

# 列出所有权限
netpad permissions list -o org_xxx

# 检查用户的有效权限
netpad permissions check user@example.com -o org_xxx

参考文档

• references/api-endpoints.md — 完整的 REST API 端点文档
• references/cli-commands.md — 完整的 CLI 命令参考

作者

Michael Lynn — MongoDB 首席开发布道师

• 🌐 个人网站: mlynn.org
• 🐙 GitHub: @mrlynn
• 💼 LinkedIn: linkedin.com/in/mlynn