wolai API Skill
通过 wolai Open API（RESTful）操作 wolai 的块、页面、数据库。
Base URL：https://openapi.wolai.com/v1
Setup
1. 创建应用并获取 Token
- 1. 前往 https://www.wolai.com/dev 创建应用（需空间管理员权限）
- 选择所需应用能力（最小权限原则）：
- 读取页面内容
- 插入页面内容
- 更新页面内容
- 3. 创建后得到
App ID 和 INLINECODE2 - 调用
POST /token 换取 INLINECODE4 - 将 Token 告知 AI 助手，由 AI 负责完成后续配置
⚠️ Token 安全须知
wolai App Token 设计为永久有效（expire_time: -1），这是 wolai 平台的设计。使用时请勿将 Token 泄露给他人或公开到代码库/聊天记录中。如泄露：在 wolai 应用管理页面重置 App Secret，然后重新调用 POST /token 获取新 Token（旧 Token 立即失效）。
2. 工作空间权限说明
| 空间类型 | 权限规则 |
|---|
| 个人空间 | 默认拥有全部页面权限，无需额外操作 |
| 团队空间 |
每个页面需单独添加应用：页面右上角 → 页面协作 → 应用权限 → 添加应用 |
凭证预检
每次调用前先检查 Token：
CODEBLOCK0
API 调用封装
所有请求统一使用 PowerShell（Windows 环境），Token 放在 Authorization Header：
CODEBLOCK1
解决中文乱码的两种方式：
CODEBLOCK2
频率控制（5次/秒限制保护）：
CODEBLOCK3
接口决策表
| 用户意图 | 接口 | 说明 |
|---|
| 读取页面/块信息 | INLINECODE8 | id 为页面 ID 或块 ID |
| 读取页面下所有子块 |
GET /blocks/{id}/children | 支持分页
?page_size=&start_cursor= |
| 向页面写入/追加内容 |
POST /blocks | 需指定
parent_id，一次最多 20 个块 |
| 读取数据库（表格） |
GET /databases/{id} | 支持分页，每次最多 200 行 |
| 向数据库插入行 |
POST /databases/{id}/rows | 字段名需与列名完全匹配，一次最多 20 行 |
| 获取 Token |
POST /token | 需要
appId +
appSecret |
| 刷新 Token（泄露时） |
PUT /token | 旧 Token 立即失效 |
接口限制
一次最多 200 条，超出用分页 |
|
批量创建/更新 | 一次最多 20 条 |
|
删除 | 每次只能删除 1 条 |
|
附件上传 | 每次 1 个，最大 1024MB |
每小时/每月用量限制（按套餐）：
500次 | 10,000次 |
| 家庭版 | 800次 | 20,000次 |
| 小组版 | 1,000次 | 30,000次 |
| 团队版 | 1,500次 | 60,000次 |
| 企业版 | 3,000次 | 200,000次 |
常用工作流
读取页面/块信息
CODEBLOCK4
返回的块对象字段说明：
| 字段 | 类型 | 说明 |
|---|
| INLINECODE19 | string | 块唯一 ID |
| INLINECODE20 |
string | 块类型（见块类型表） |
|
content | array | 富文本内容数组 |
|
parent_id | string | 父块 ID |
|
page_id | string | 所在页面 ID |
|
children.ids | array | 子块 ID 列表 |
|
created_at | number | 创建时间戳（ms） |
|
edited_at | number | 最后编辑时间戳（ms） |
分页遍历所有子块
当页面内容较多时，需要循环分页：
CODEBLOCK5
向页面写入内容（创建块）
CODEBLOCK6
创建富文本内容
INLINECODE27 字段（CreateRichText）支持三种写法：
CODEBLOCK7
RichText 可用样式属性：
| 属性 | 类型 | 说明 |
|---|
| INLINECODE28 | string | 文本内容（必填） |
| INLINECODE29 |
boolean | 加粗 |
|
italic | boolean | 斜体 |
|
underline | boolean | 下划线 |
|
highlight | boolean | 高亮 |
|
strikethrough | boolean | 删除线 |
|
inline_code | boolean | 行内代码 |
|
front_color | BlockFrontColors | 文字颜色 |
|
back_color | BlockBackColors | 背景色 |
⚠️ 注意：创建块时 RichText 的 type 字段暂只支持 "text" 和 "equation"（纯文本可不传 type）
各类块的完整创建示例
CODEBLOCK8
❌ 不支持在创建块接口中使用的类型：file、database、meeting、reference、simple_table、template_button、row、 INLINECODE47
页面设置（page_setting）
创建子页面时可配置页面属性：
| 属性 | 类型 | 默认值 | 说明 |
|---|
| INLINECODE48 | boolean | false | 自适应宽度（取消默认左右边距） |
| INLINECODE49 |
boolean | false | 小字体模式 |
|
has_floating_catalog | boolean | false | 显示浮动标题目录 |
|
font_family | string |
"default" | 字体：
"default" /
"simsun"（宋体）/
"kaiti"（楷体） |
|
line_spacing | string |
"default" | 行距：
"default" /
"loose"（宽松）/
"compact"（紧凑） |
示例：创建一个有特殊设置和封面的子页面
CODEBLOCK9
图标（icon）格式
页面块和着重文字块支持两种图标类型：
| 类型 | 格式 | 示例 |
|---|
| emoji 图标 | INLINECODE61 | INLINECODE62 |
| 网络图标 |
{ type = "fontAwesome"; icon = "fa-github" } | FontAwesome 图标名称 |
|
链接图标 |
{ type = "link"; icon = "https://..." } | 图片 URL 作为图标 |
代码块（code）完整属性
| 属性 | 类型 | 说明 |
|---|
| INLINECODE65 | INLINECODE66 | 必填 |
| INLINECODE67 |
CodeLanguage | 必填，代码语言（支持 90+ 种，含
mermaid 流程图） |
|
content | string | 代码内容 |
|
caption | string | 代码块说明文字 |
|
code_setting | object | 代码显示设置 |
code_setting 子属性：
| 属性 | 类型 | 说明 |
|---|
| INLINECODE72 | boolean | 显示行号 |
| INLINECODE73 |
boolean | 自动换行 |
|
ligatures | boolean | 启用连字符 |
|
preview_format | string | 预览格式：
"both" /
"code" /
"mermaid"（仅 mermaid/ybsz 有效） |
代码语言（language）
wolai 支持 90+ 种代码语言，常用值：
| 类别 | 语言 |
|---|
| 主流 | INLINECODE79 、javascript、typescript、java、go、rust、c、cpp、 INLINECODE87 |
| Web |
html、
css、
scss、
json、
xml、
yaml、
markdown |
|
脚本 |
powershell、
bash、
dart、
lua、
perl、
ruby |
|
数据 |
sql、
graphql、
protobuf |
|
可视化 |
mermaid（流程图/时序图）、
ybsz（仪表数字） |
|
其他 |
swift、
kotlin、
scala、
matlab、
r、
dockerfile、
nginx |
块的颜色值
文字颜色（front_color / block_front_color）：
INLINECODE115 | "gray" | "dark_gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "indigo" | "purple" | "pink" | INLINECODE126
背景色（back_color / block_back_color）：
INLINECODE129 | "cultured_background" | "light_gray_background" | "apricot_background" | "vivid_tangerine_background" | "blond_background" | "aero_blue_background" | "uranian_blue_background" | "lavender_blue_background" | "pale_purple_background" | "pink_lavender_background" | "light_pink_background" | "fluorescent_yellow_background" | "fluorescent_green_background" | "fluorescent_green2_background" | "fluorescent_blue_background" | "fluorescent_purple_background" | INLINECODE146
文字对齐（text_alignment）：
INLINECODE148 （居中）
块对齐（block_alignment）：
INLINECODE150 | "center" | "right"
读取数据库（表格）
CODEBLOCK10
数据库响应结构：
| 字段 | 类型 | 说明 |
|---|
| INLINECODE153 | array | 行数据数组，每行是一个键值对对象 |
| INLINECODE154 |
string | 下一页游标，
has_more=true 时存在 |
|
has_more | boolean | 是否还有更多数据 |
每行数据示例：
CODEBLOCK11
数据库限制：单个数据表最多支持 10,000 行、100 列、10 个视图。
数据库高级查询
根据 API 规范和常见需求，可能支持的查询方式：
CODEBLOCK12
⚠️ 注意：API 文档中关于数据库查询的具体筛选/排序参数说明有缺失。如需筛选特定条件（如按状态筛选、按日期排序），请参考 wolai 官方开发者中心最新文档或通过 Apifox 测试接口。
数据库 ID 获取方式
数据库（表格）本质上也是一种块，可通过以下方式获取 ID：
| 方式 | 说明 |
|---|
| 从 URL 获取 | 打开数据库所在页面，URL 中 / 后的部分即为页面 ID（数据库通常嵌入在页面中） |
| 从页面子块中查找 |
调用
GET /blocks/{pageId}/children，在返回的块中找到
type="database" 的块，其
id 即为数据库 ID |
示例：从页面中查找数据库块
$pageId = "your_page_id"
$children = Invoke-WolaiApi -Method GET -Path "/blocks/$pageId/children"
# 查找类型为 database 的块
$databaseBlock = $children.data | Where-Object { $_.type -eq "database" }
$dbId = $databaseBlock.id
Write-Host "数据库 ID: $dbId"
向数据库插入行
CODEBLOCK14
插入数据注意事项：
| 注意事项 | 说明 |
|---|
| 列名匹配 | 字段名必须与数据库中定义的列名完全一致（包括空格、大小写） |
| 必填字段 |
数据库中标记为必填的列必须在插入时提供值 |
|
字段类型 | 确保插入的数据类型与列类型匹配（文本/数字/日期/选项等） |
|
选项字段 | 选项类型的列，值必须是预定义的选项之一 |
|
批量限制 | 一次最多插入 20 行，超出需分批调用 |
数据库常见操作示例
场景1：从 CSV 批量导入数据到 wolai 数据库
CODEBLOCK15
场景2：根据条件查询数据库
CODEBLOCK16
场景3：数据统计分析
$dbId = "your_database_id"
# 获取所有数据（分页）
$allRows = @()
$cursor = $null
do {
$query = @{ page_size = 200 }
if ($cursor) { $query["start_cursor"] = $cursor }
$resp = Invoke-WolaiApi -Method GET -Path "/databases/$dbId" -Query $query
$allRows += $resp.data
$cursor = $resp.next_cursor
} while ($resp.has_more)
# 按状态分组统计
$byStatus = $allRows | Group-Object "状态" | ForEach-Object {
[PSCustomObject]@{
状态 = $_.Name
数量 = $_.Count
占比 = [Math]::Round($_.Count * 100 / $allRows.Count, 2)
}
}
Write-Host "任务状态分布："
$byStatus | Format-Table -AutoSize
# 按负责人统计任务数
$byAssignee = $allRows | Group-Object "负责人" | Sort-Object Count -Descending
Write-Host "`n各负责人任务数："
$byAssignee | ForEach-Object {
Write-Host "$($_.Name): $($_.Count) 个任务"
}
获取 Token（首次配置）
CODEBLOCK18
返回结构：
CODEBLOCK19
Token 永久有效（expire_time: -1），泄露后调用 PUT /token 刷新，旧 Token 立即失效。
刷新 Token（泄露时使用）
CODEBLOCK20
错误处理
| 错误码 | HTTP状态码 | 含义 | 建议处理 |
|---|
| 17001 | 400 | 缺少参数 | 检查必填字段 |
| 17002 |
400 | 参数错误 | 检查参数格式和类型 |
| 17003 | 401 | 无效 Token | 检查 WOLAI_TOKEN 是否正确，或重新获取 |
| 17004 | 404 | 获取资源失败 | 检查 ID 是否正确 |
| 17005 | 404 | 资源未找到 | 检查页面/块 ID 是否存在 |
| 17006 | 500 | 服务器内部错误 | 稍后重试 |
| 17007 | 429 | 请求过于频繁 | 降低调用频率（≤5次/秒） |
| 17008 | 413 | 请求体过大 | 拆分为多次请求（每次≤20条） |
| 17009 | 415 | 不支持的媒体类型 | 检查 Content-Type Header |
| 17010 | 400 | 暂不支持的块类型 | 检查 type 字段，见块类型说明 |
| 17011 | 403 | 权限不足 | 团队空间需在页面添加应用权限 |
错误响应统一格式：
{
"message": "错误描述（含解决建议）",
"error_code": 17003,
"status_code": 401
}
注意事项
- - 页面 ID：从 URL 获取，
wolai.com/ 后面的部分即为 ID（如 wolai.com/oaBQLq... → ID 为 oaBQLq...） - 块 ID：从块菜单内「复制块 ID」获取
- Token 永久有效（
expire_time: -1），泄露后调用 PUT /token 刷新，旧 Token 立即失效 - App Secret 泄露：在应用管理页面重置 App Secret，然后重新调用
POST /token 获取新 Token - 团队空间每个页面都需单独添加应用，个人空间无需此操作
- UTF-8 编码：PowerShell 默认编码可能导致中文乱码，封装函数已处理，直接使用 Invoke-WolaiApi 即可
- 创建块后：接口返回新块的可访问链接（
data 字段），格式为 INLINECODE170
wolai API 技能
通过 wolai Open API（RESTful）操作 wolai 的块、页面、数据库。
基础 URL：https://openapi.wolai.com/v1
设置
1. 创建应用并获取 Token
- 1. 前往 https://www.wolai.com/dev 创建应用（需空间管理员权限）
- 选择所需应用能力（最小权限原则）：
- 读取页面内容
- 插入页面内容
- 更新页面内容
- 3. 创建后得到 App ID 和 App Secret
- 调用 POST /token 换取 app_token
- 将 Token 告知 AI 助手，由 AI 负责完成后续配置
⚠️ Token 安全须知
wolai App Token 设计为永久有效（expire_time: -1），这是 wolai 平台的设计。使用时请勿将 Token 泄露给他人或公开到代码库/聊天记录中。如泄露：在 wolai 应用管理页面重置 App Secret，然后重新调用 POST /token 获取新 Token（旧 Token 立即失效）。
2. 工作空间权限说明
| 空间类型 | 权限规则 |
|---|
| 个人空间 | 默认拥有全部页面权限，无需额外操作 |
| 团队空间 |
每个页面需单独添加应用：页面右上角 → 页面协作 → 应用权限 → 添加应用 |
凭证预检
每次调用前先检查 Token：
powershell
if (-not $env:WOLAI_TOKEN) {
Write-Error 缺少 WOLAI_TOKEN，请按 Setup 步骤配置
exit 1
}
API 调用封装
所有请求统一使用 PowerShell（Windows 环境），Token 放在 Authorization Header：
powershell
function Invoke-WolaiApi {
param(
[string]$Method = GET,
[string]$Path,
[hashtable]$Body = $null,
[hashtable]$Query = $null,
[switch]$RawJson # 新增：返回原始 JSON 字符串而非对象（避免中文乱码）
)
# ⚠️ 必须强制 UTF-8，否则中文内容会变成问号
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
$headers = @{
Authorization = $env:WOLAI_TOKEN
Content-Type = application/json; charset=utf-8
}
$uri = https://openapi.wolai.com/v1$Path
# 拼接 Query 参数（用于分页等）
if ($Query) {
$qs = ($Query.GetEnumerator() | ForEach-Object {
# URL 编码值（防止特殊字符问题）
$($.Key)=$([System.Web.HttpUtility]::UrlEncode($($.Value)))
}) -join &
$uri = $uri?$qs
}
try {
if ($RawJson) {
# 返回原始 JSON 字符串（适合中文内容）
$resp = Invoke-WebRequest -Method $Method -Uri $uri -Headers $headers
if ($Body) {
$bodyBytes = [System.Text.Encoding]::UTF8.GetBytes(($Body | ConvertTo-Json -Depth 10))
$resp = Invoke-WebRequest -Method $Method -Uri $uri -Headers $headers -Body $bodyBytes
}
return $resp.Content
} else {
# 返回解析后的对象
if ($Body) {
$bodyBytes = [System.Text.Encoding]::UTF8.GetBytes(($Body | ConvertTo-Json -Depth 10))
$response = Invoke-RestMethod -Method $Method -Uri $uri -Headers $headers -Body $bodyBytes
} else {
$response = Invoke-RestMethod -Method $Method -Uri $uri -Headers $headers
}
return $response
}
} catch {
# 解析 wolai API 错误响应
$errBody = $_.ErrorDetails.Message | ConvertFrom-Json
if ($errBody.error_code) {
Write-Error wolai API 错误 [$($errBody.error_code)]: $($errBody.message)
} else {
Write-Error 请求失败: $($_.Exception.Message)
}
return $null
}
}
解决中文乱码的两种方式：
powershell
方式1：写入文件（推荐，完美支持中文）
$json = Invoke-WolaiApi -Method GET -Path /databases/p4NEGH7dgHEvKZDBzaKuRh -RawJson
[System.IO.File]::WriteAllText(D:\output.json, $json, [System.Text.UTF8Encoding]::new($false))
方式2：通过对象属性访问（适合程序处理）
$db = Invoke-WolaiApi -Method GET -Path /databases/p4NEGH7dgHEvKZDBzaKuRh
$db.data.rows[0].data # 直接访问嵌套属性，控制台可能乱码但值正确
频率控制（5次/秒限制保护）：
powershell
在连续多次调用 API 时，加入间隔避免触发频率限制
wolai 限制：同一用户 5次/秒，即每次调用至少间隔 200ms
$script:lastWolaiCall = [DateTime]::MinValue
function Wait-WolaiRateLimit {
param([int]$MinIntervalMs = 250) # 留 50ms 余量
$elapsed = ((Get-Date) - $script:lastWolaiCall).TotalMilliseconds
if ($elapsed -lt $MinIntervalMs) {
Start-Sleep -Milliseconds ($MinIntervalMs - $elapsed)
}
$script:lastWolaiCall = Get-Date
}
使用示例：在循环中调用
do {
Wait-WolaiRateLimit
$resp = Invoke-WolaiApi -Method GET -Path /blocks/$pageId/children -Query $query
# ...
} while ($resp.has_more)
接口决策表
| 用户意图 | 接口 | 说明 |
|---|
| 读取页面/块信息 | GET /blocks/{id} | id 为页面 ID 或块 ID |
| 读取页面下所有子块 |
GET /blocks/{id}/children | 支持分页 ?page
size=&startcursor= |
| 向页面写入/追加内容 | POST /blocks | 需指定 parent_id，一次最多 20 个块 |
| 读取数据库（表格） | GET /databases/{id} | 支持分页，每次最多 200 行 |
| 向数据库插入行 | POST /databases/{id}/rows | 字段名需与列名完全匹配，一次最多 20 行 |
| 获取 Token | POST /token | 需要 appId + appSecret |
| 刷新 Token（泄露时） | PUT /token | 旧 Token 立即失效 |
接口限制
一次最多 200 条，超出用分页 |
|
批量创建/更新 | 一次最多 20 条 |
|
删除 | 每次只能删除 1 条 |
|
附件上传 | 每次 1 个，最大 1024MB |
每小时/每月用量限制（按套餐）：
500次 | 10,000次 |
| 家庭版 | 800次 | 20,000次 |
| 小组版 | 1,000次 | 30,000次 |
| 团队版 | 1,500次 | 60,000次 |
| 企业版 | 3,000次 | 200,000次 |
常用工作流
读取页面/块信息
powershell
页面 ID 从 URL 获取：wolai.com/ 后面的部分即为页面 ID
$pageId = oaBQLqSBaMbS6S4NX4fJU7
获取页面块基本信息（标题、类型等）
$page = Invoke-WolaiApi -Method GET -Path /blocks/$pageId
$page.data
获取页面第一层子块列表（默认最多 200 条）
$children = Invoke-WolaiApi -Method GET -Path /blocks/$pageId/children
$children.data
