本地 HTML 工作台 → 资料库建表 + 部署
适用于「一个自包含单页 HTML（数据层用 window.__SMART_PAGE__.database，databaseId 硬编码在文件里）+ 一份字段 schema.json」的工具包交付。
0. 读材料时不要走重通道
.docx/.xlsx只做内容提取时，用 stdlib 解 zip 读word/document.xml/xl/sharedStrings.xml最快，不必起 editor_sdk：
python xml = zipfile.ZipFile(p).read('word/document.xml').decode('utf-8','ignore') xml = xml.replace('</w:p>', '\n</w:p>'); xml = re.sub(r'<[^>]+>', '', xml); html.unescape(xml)- Windows 上
/tmp不可靠（会被解析成c:\tmp）；临时脚本写到会话工作目录。
1. 资料库鉴权（客户端模式）
python "<PLUGIN>/skills/library/runtime_context.py" # KS_LIBRARY_RUNTIME {"mode":"client"}
mode=client 时：ToolSearch {"tool_names":["connect_open_platform"]} → DeferExecuteTool {"toolName":"connect_open_platform","params":{"skill_id":"library"}} 拿 token（op_...，30 分钟）。token 只作 stdin 首行、串 --token-stdin，不落盘、不回显。
> --help 也要求 token，别指望先看帮助。
2. 建表（空表）
database/create_database.py 支持 --stdin，payload 是完整建表 dict：{"title":..., "properties":[{"name":..., "config":{...}}]}。
{ printf '%s\n' "$TOKEN"; cat create_schema.json; } | python "$L/database/create_database.py" --stdin --token-stdin
config 是 oneof 包裹（不是 schema.json 里的 type+config）：
| 源 type | 建表 config |
|---|---|
| text | {"text": ""} |
| number | {"number": {"decimalPlaces":0,"useSeparate":false}} |
| date | {"date": {"format":"yyyy-mm-dd"}} |
| select / multi_select | {t:{"options":[{"text":..,"style":..}]}} |
select/multi_select 的 option id 建议丢掉，让服务端生成；页面若按选项文本写入（{select:'待处理'}），id 完全不参与，可安全重建。产出 {"database_id": ...}。
3. 打补丁 → 校验 → 导入
- 复制原 html 成工作副本再替换占位符（别改工具包原文件），替换处数要核对：
python n = s.count("PUT_YOUR_DATABASE_ID_HERE"); s = s.replace(..., DBID)
典型 2 处：data-sp-database-id="..."与var DATABASE_ID='...'。 - SDK 调用 lint：
page/lint_database_sdk_usage.py --schema-file <get_database_schema 输出> --html <html>，期望MINDX_DBSDK_LINT_OK。 - 在线 page 图片硬门（无输出=合格）：
bash grep -Eoi '<img[^>]+>' x.html | grep -Eoi "(src|srcset)[[:space:]]*=[[:space:]]*[\"'][^\"']*(https?:)?//[^\"']+" | grep -Eoi "(https?:)?//[^/\"')[:space:]]+" | grep -Eiv 'codebuddy|workbuddy' - 导入并写关联：
bash printf '%s' "$TOKEN" | python "$L/page/import_html.py" <abs.html> --token-stdin --databases '[{"id":"<DBID>"}]'
成功输出KS_IMPORT_OK {"node_block_id":"...","url":"https://www.workbuddy.cn/space/d/..."}。
页面只有导入资料库后才有__SMART_PAGE__，本地直接打开一定db=null，别拿本地打开当验收。
4. 记录读写脚本的 stdin 协议（最大坑）
batch_add_database_records / batch_delete_database_records / query_database_record 都支持 --stdin，但 _read_input 会把整段 stdin 当 dict 读：
- ✅
{"database_id":"...","records":[{...}]} - ✅
{"database_id":"...","record_ids":["rec_1"]} - ❌ 只传
[{...}]数组 →{"error":"输入 JSON 为空或格式非法"}（isinstance(data, dict)不通过） - ❌ 多行 pretty JSON 经
--records传 → 同样报错；必须单行紧凑或走--stdin
query_database_record 用 --database-id 即可，不需要 --stdin。
字段值一律 oneof：{"字段名":{"select":"文本"}}、{"multi_select":["A","B"]}、{"date":"2026-09-23"}、{"number":95}、{"text":"..."}。
5. 冒烟测试（无浏览器时）
写 1–2 条覆盖 select/multi_select/date/number/text 的测试记录 → query_database_record 回读确认字段值落地 → batch_delete_database_records 删除 → 再查确认 results: []。JS 侧另跑 node --check（抽出 <script> 内容）。
agent-browser 未安装时不要 npm install -g（违反本机隔离约定），用上面这条数据通道冒烟替代。
6. 交付
- 默认交付协作态链接
/space/d/<nodeId>；publish_page.py只在用户明确说「发布 / 部署为网站」时才调。 - 留档三件套：页面链接、数据表 id、页面节点 id（=链接末尾那串）。
- 只读验收：
page/page_database_relation.py --token-stdin --action list --page-id <nodeId>应返回 page↔database 关联。
