工具百宝箱

把用户随手转发的一个工具链接，沉淀成一条结构化、可读、可检索的记录，并同步进飞书多维表格。

固定五步，一步都不能省：

核心红线：不编造。 地址抓不到就如实写"未提供"，功能看不出来就写"页面信息不足，未能确认"，绝不补写没见过的能力。

> v1.1 变更：第 7 个字段由「使用教程网址」改为「使用教程」，内容从 URL 改为教程正文。
> 原因：本地 file:// 链接在飞书里跨设备点不开，等于废字段。现在直接把教程写进单元格，不生成 HTML 文件。
> 仅当用户明确要"网页版/HTML 教程"时，才走 gen_tutorial.py（见第四节末）。
> v1.2 变更（最终修正）："本地电脑关机也能收录"的真正通道是「飞书连接器」——你在 WorkBuddy 平台已连接的飞书授权，平台托管 token，本地用 lark-cli、云端/自动化由平台直接提供，完全不需要你手动提供 app_id/secret。OpenAPI 脚本（sync_feishu.py，需自建应用凭证）降为可选高级通道。早期版本误把 OpenAPI 当唯一跨端通道，但自建应用凭证在云端沙箱读不到、你也无需提供，故以连接器为准。

〇、环境约定

PY="C:/Users/HP/.workbuddy/binaries/python/envs/default/Scripts/python.exe"
SK="C:/Users/HP/.workbuddy/skills/toolbox"

脚本依赖 requests（该 venv 已装）。本技能默认不产出文件，只往飞书写文本。

写入通道说明（重要：本地 / 云端都能用）

飞书写入有两条互不依赖的通道，五步产出的字段内容完全一致，只是"怎么写进去"不同：

> 原则：优先用「飞书连接器」——它在你已连接的 WorkBuddy 飞书授权下工作，平台托管 token，本地和云端都不需要你提供任何密钥，是"本机开关机都无影响、手机关机也能收录"的最简通道。
> 只有在你明确有自建应用、想绕过连接器时，才走开放 API 脚本（B 通道，需 app_id/secret）。
> PY / SK 两个变量在两条通道里都用（Python 解释器 + 技能目录）。

一、识别下载地址 / 使用地址

输入可能是：一段含链接的文字、一个裸网址、或视频号视频链接。

1. 抽链接：用正则从文本里取所有 URL。若整段没有 URL，把文字当"工具名/描述"去搜索确认，再让用户补链接。
2. 解短链：t.cn / sourl.cn / dwz.cn / b23.tv / 微信短链等，用 WebFetch 或 curl -sIL 跟随跳转取最终 URL。
3. 判定地址性质（决定第②步类型，也决定字段填什么）：

4. 判不清就抓页面：用 WebFetch 打开，找"下载 / Download / 立即使用 / 开始使用 / Get Started / 免费试用"的真实链接。
5. 视频号链接特殊处理（无公开下载地址接口，不要伪造）：
   - 把转发来的视频号链接原样作为"地址"存入；
   - 视频号页面/文案/评论区里若出现工具的真实官网或下载页，优先用那个真实地址；
   - 若视频只演示了工具但没给地址，在功能介绍末尾注明"来源：视频号分享，官方地址未提供"，并向用户追问。

6. 归一：去掉 ?utm_*、# 之后的无关追踪参数，保留必要的 ?id= 之类。

7. 地址失效（404）必须矫正后再收录（GitHub 地址高频踩坑，口述/视频口播常抄错）：

命名差异高发点：- 与 _ 混用、是否带 -AI / -Lab 后缀、owner 与 repo 名互换。
例：Audio8/Audio8-TTS(404) → 真 Audio8-AI/Audio8_TTS → 301 到 Edge0-AI/Audio8_TTS(200)。
再例：benjaminwong/gods-eye-view(404) → 真 bilawalsidhu/gods-eye-view(200)；
anthropics/agent-skills(404) → 真 anthropics/skills(200)。

8. 批量拿 star 与协议用 GitHub API，别逐个抓页面：WebFetch 抓 GitHub 页面经常截断，
   且几乎拿不到 star 数。批量收录时先跑一次 API，几秒拿到全部元数据：
   （本机有 curl 用下方脚本；云端/无 curl 时改用 WebFetch 直接拉 https://api.github.com/repos/<owner>/<repo>，从 JSON 取 stargazers_count / license.spdx_id / homepage——WebFetch 是云端工具，本机关机也能用）

bash for r in owner1/repo1 owner2/repo2; do curl -s --max-time 25 "https://api.github.com/repos/$r" | python -c \ "import sys,json;d=json.load(sys.stdin);print('%-30s %7s %-14s %s'%(d.get('full_name'),d.get('stargazers_count'),(d.get('license') or {}).get('spdx_id'),(d.get('description') or '')[:70]))" done

拿到 NOASSERTION / None 不等于没有协议（多为含第三方数据条款或徽章未识别），
此时去仓库根目录确认 LICENSE 文件，不要直接写"无协议"。

产出：地址 字段 = 一个 canonical URL。

二、归类类型（三选一，只填一个值）

边界处理：
- 既有网页版又有客户端（如 Notion、飞书）→ 按用户给的链接形态判定：给网页链接判网页，给下载页链接判应用；另一种形态在功能介绍里补一句说明。
- 实在分不清 → 默认 网页（在线可用是最大公约数），并在功能介绍中注明。

三、功能介绍 + 功能类别

功能介绍（写进 功能介绍，80–150 字，一段话）

固定句式，务必覆盖领域 / 输入 / 输出三要素：

> <工具名>是面向<领域·人群>的<类型>工具。输入<输入形态>，输出<输出形态>，用于<核心用途·解决什么问题>。关键能力：<2–3 个要点>。

示例：
> removebg 是面向设计与电商从业者的网页工具。输入一张含主体的图片，输出去除背景的透明 PNG，用于快速抠图与商品图制作。关键能力：自动识别主体、批量处理、提供 API 接入。

功能类别（写进 功能类别，单选，取最主要一项）

次要属性可以写在功能介绍里，但 功能类别 字段只写一个值。

四、编写使用教程（一段话，纯文本）

直接写进 使用教程 单元格，不生成文件、不填网址。飞书里点开记录就能读完。

写法模板

用 ①②③… 串起 3–6 个步骤，末尾加一句"注意："带 1–2 条坑。全文 80–200 字，一气读完。

> ① <准备/打开>；② <关键操作1>；③ <关键操作2>；④ <拿到结果>；⑤ <可选分支>。注意：<最该提醒的 1–2 点>。

示例

• 网页类（remove.bg）：
  > ① 浏览器打开 remove.bg 官网，无需注册即可试用；② 点击 Upload 上传图片，或直接把图片拖到页面上；③ 数秒后自动完成抠图，右侧预览满意后点 Download 保存透明 PNG。注意：免费版有分辨率限制，批量处理需登录，商用需留意图片授权。

• 应用/开源项目类（Audio8 TTS）：
  > ① 准备 Python 3.10+ 环境，推荐 CUDA GPU；② git clone 仓库后 pip install -r requirements.txt；③ 从 Hugging Face 下载 0.6B 权重放入 model/ 目录；④ 可选：上传 0.5–30 秒参考音频 + 逐字准确转写注册音色；⑤ 运行推理脚本，传入文本与音色名，输出 44.1 kHz WAV；无 GPU 可改用 onnx_runtime/ 的 CPU 版（约 1 GiB 内存）。注意：参考音频转写须与说话内容完全一致，预览版优先使用 11 种推荐语言。

内容要求

• 步骤要可执行：写得出具体动作（点哪个按钮、跑哪条命令），不要写"根据需要进行设置"这种空话；
• 命令要真实：从 README / 官方文档里抄，不要凭印象编命令；
• 必须带输入→输出：读者要知道喂什么进去、拿到什么出来；
• 注意事项挑最痛的：额度限制、环境要求、许可/合规风险；
• 信息不足就如实写"官方未提供详细步骤，建议参考其 README"，不要编。

（可选）用户明确要 HTML 网页版教程时

才用 scripts/gen_tutorial.py：

"$PY" "$SK/scripts/gen_tutorial.py" --data "C:/.../record.json" --out-dir "C:/.../工具百宝箱/教程"

JSON 里 steps / tips 每条用 @@ 分隔「标题@@说明」。生成后用 present_files 预览。
注意：产出的 file:// 路径不要写进飞书字段——跨设备打不开。要公网链接得先用「发布为应用」发布（属对外动作，须用户确认）。

五、同步到飞书多维表格「工具百宝箱」

目标多维表格：app_token = A7wJbnGriadAfCs7KGhcR3lundb
数据表：工具百宝箱（字段顺序即列序，时间为索引列）

通道选择（每次写入前先定）

1. 飞书连接器（默认首选）：只要运行环境能调用飞书（本机有 lark-cli 且已连接飞书 Connector，或云端/自动化里平台提供了飞书能力）→ 一律走它。它不依赖本机开机、不需要你提供任何凭证，是手机关机后也能收录的唯一零配置通道。本地用法见 A 通道，云端用法由平台自动提供。
2. 飞书开放 API 脚本（可选）：仅当你有自建应用、明确想绕过平台连接器时，用 sync_feishu.py + app_id/app_secret（见 B 通道）。

> 两条通道写入的字段内容完全一致，只是"怎么写进去"不同；优先连接器，无需任何手动密钥。

C. 飞书开放 API 通道（可选高级 · 需自建应用凭证）

这是可选通道，仅当你有飞书自建应用、想不依赖平台连接器时使用。它直接调用飞书开放平台 HTTPS 接口
（https://open.feishu.cn/open-apis/...），由 scripts/sync_feishu.py 实现，
需要你提供 app_id / app_secret（环境变量或 config/feishu_config.json）。
本地 PC 开机能跑，云端会话 / 自动化任务（在 WorkBuddy 云端执行）也能跑——但它要求你自备并注入凭证，
而「飞书连接器」通道无需任何凭证即可达成同样效果，所以默认不推荐。

> 为什么普通场景不用它当首选？它需要你在云端/自动化环境注入自建应用密钥（你也无需提供、云端沙箱也读不到本机文件），
> 而「飞书连接器」由平台托管授权、零手动凭证即跨端通用，明显更省事。

坐标（已建好，不要重建）：base_token = A7wJbnGriadAfCs7KGhcR3lundb，table_id = tblWoldVMkfCjWnG。

凭证（一次配置，永久生效）——需要你自己的飞书企业自建应用的 app_id / app_secret：
1. 飞书开放平台 → 创建企业自建应用 → 拿 app_id / app_secret；
2. 应用「权限管理」开通 bitable:app（多维表格读写）；
3. 把该应用加为多维表格的协作者（表格右上角「…」→ 添加文档应用），否则报 91402 无权限；
4. 二选一提供凭证：
- 写进 config/feishu_config.json 的 app_id / app_secret 字段；或
- 设置环境变量 FEISHU_APP_ID / FEISHU_APP_SECRET（云端 / 自动化场景推荐，便于做密钥隔离）。

用法（字段与五步完全一致，不生成文件）：

"$PY" "$SK/scripts/sync_feishu.py" \
  --name "remove.bg" --type "网页" --url "https://www.remove.bg/" \
  --intro "面向…输入…输出…" --category "效率类" \
  --tutorial "① 打开官网；② 上传图片；③ 下载透明 PNG。注意：免费版有分辨率限制。"

脚本会按名称找表 → 找不到就新建并建好 7 个字段 → 追加一条记录（已内置按「工具名称」查重，重复会自动跳过）；已有表只补缺失字段。--dry-run 只预览不写。

查重（红线，每次必做）：脚本已默认在写入前比对「工具名称」并跳过重复；若你手动改过脚本或想二次确认，可拉全表核验——本地有 lark-cli 时 lark-cli base +record-list；云端无 lark-cli 时用同步脚本的只读校验（见下）。发现同名重复，删多余条：
DELETE /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/{record_id}。
无论单条还是批量，写完必须查重——开放 API 同样出现过"一次落两条"的双写。

首次启用建议：先跑一次 scripts/setup_openapi.py（只做只读校验：拿 token → 列该 base 的表 → 确认「工具百宝箱」可见、应用有读写权），不写任何数据，确认通道通了再正式收录。

A. 本地 lark-cli 通道（兜底，需本机开机）

飞书 Connector 的命令行形态，多维表格走 base 子命令：

LARK="C:/Users/HP/.workbuddy/binaries/node/cli-connector-packages/lark-cli.cmd"

已建好的坐标，直接用，不要重复建表：

字段与 CellValue 写法（已建好；类型决定是否要数组）：

写入命令（用文件传 JSON，避免命令行中文转义问题）：

"$LARK" base +record-batch-create --base-token A7wJbnGriadAfCs7KGhcR3lundb \
  --table-id tblWoldVMkfCjWnG --json "@C:/.../record.json" --as user

{"create_records":[{
  "时间":"2026-09-17 09:00","工具名称":"remove.bg","类型":["网页"],
  "地址":"https://www.remove.bg/","功能介绍":"面向…输入…输出…",
  "功能类别":["效率类"],
  "使用教程":"① 打开官网；② 点 Upload 上传图片；③ 预览后点 Download 保存透明 PNG。注意：免费版有分辨率限制。"
}]}

改表结构（字段增删改）

# 读字段定义（用 --field-id 传字段名也能查）
"$LARK" base +field-get  --base-token <BT> --table-id <TID> --field-id "使用教程" --as user

# 改名 / 改样式：完整 PUT 语义，--json 给目标状态
"$LARK" base +field-update --base-token <BT> --table-id <TID> --field-id <field_id> \
  --json '{"name":"使用教程","type":"text"}' --yes --as user

• 同类型转换（text→text）安全；跨类型转换按官方允许列表，不确定就新建字段 + 迁移，别硬改；
• 改完响应会提示跑一次 +field-get 复核。
• 改字段后记得回填存量记录：用 +record-batch-update，JSON 形如
  {"update_records":{"recA":{"字段":"值"},"recB":{"字段":"值"}}}。
  响应里的 record_not_found 说明该 record_id 已不存在（被删或记错），不要当成写入失败。

写入要点与坑（实测）

• select 必须传数组，且选项必须是表里已存在的，否则写入失败；
• 统一加 --as user（用户身份优先）；
• 写入后必须查重（血泪教训，三次踩坑，前两次归因都错了）：
  +record-batch-create 即使只执行一次也可能落两条，与批量条数无关——
  2026-09-21 一次写 10 条没重复（当时误判为"批量安全"），
  2026-09-22 只写 1 条照样双写，两条内容完全一致、时间戳相同（链路内部重试/双写）。
  结论：不存在"安全批次"，单次 1 条也会中招，查重每次必做。
  bash "$LARK" base +record-list --base-token <BT> --table-id <TID> --limit 50 --format json --as user > list.json # 用 python 解析 list.json 做查重（别用 jq，--jq 在 .cmd 下会被转义破坏，且 --jq 与 --format markdown 互斥） # 实测返回结构：d["data"]["data"] 是「记录的列表」，每条记录仍是「位置列表」而非字段名 keyed dict： # 索引 0=时间, 1=功能类别, 2=类型, 3=功能介绍, 4=使用教程, 5=地址, 6=工具名称 # 所以按「工具名称」查重要取 r[6]；删重复时用 d["data"]["record_id_list"]（与 recs 同序对齐）： "$PY" - <<'EOF' import json from collections import Counter d=json.load(open("list.json",encoding="utf-8")) ids=d["data"]["record_id_list"]; recs=d["data"]["data"] names=[r[6] for r in recs] dup={k:v for k,v in Counter(names).items() if v>1} print("总记录:",len(names),"重复:",dup if dup else "无") for i,n in enumerate(names): if "目标关键词" in n: print("命中:",ids[i],n) EOF # 删重复：把重复记录的 record_id 多次传 --record-id（逗号分隔会报错 800010701）
  发现重复就用 +record-delete --record-id X --record-id Y --yes 删掉多余的
  （多次传 --record-id，不能用逗号分隔；+record-get 同样不支持逗号）。
• 同一 Table 串行写入，并行可能触发 1254291 并发冲突；单批上限 200 条；
• 中文参数经 Git Bash 传给 .cmd 是正确的（终端显示的"乱码"只是 Git Bash 用 GBK 渲染 UTF-8 造成的错觉）。不放心就重定向到文件再用 Read 读，或走 --json @file；
• 表若不存在需重建：+table-create --name 工具百宝箱 --fields '<数组>'，第一个字段会成为主字段（所以把"时间"放第一个）。

B. 飞书开放 API 脚本通道（可选高级 · 需自建应用凭证）

"$PY" "$SK/scripts/sync_feishu.py" \
  --name "工具名" --type "网页" --url "https://..." \
  --intro "面向…领域，输入…，输出…" --category "效率类" \
  --tutorial "① 打开…；② 上传…；③ 下载…。注意：…"

脚本行为：按名称找表 工具百宝箱 → 找不到就新建并建好 7 个字段 → 追加一条记录。已有表则只补缺失字段，不覆盖。
--tutorial 现在收的是教程正文，不是网址。

一次性凭证配置（仅 OpenAPI 通道需要；「飞书连接器」A 通道不需要任何凭证）

1. 打开飞书开放平台 → 创建企业自建应用 → 拿 app_id / app_secret；
2. 该应用「权限管理」开通 bitable:app（多维表格读写）；
3. 把该应用加为多维表格的协作者（表格右上角「…」→ 添加文档应用），否则会报 91402 无权限；
4. 二选一提供凭证：
   - 写进 config/feishu_config.json 的 app_id / app_secret 字段；或
   - 设置环境变量 FEISHU_APP_ID / FEISHU_APP_SECRET（云端 / 自动化场景推荐，便于做密钥隔离）。

也可以已有 token 时直接 --token xxx。先用 --dry-run 确认字段内容再真写。

把它做成自动化（本地关机也能自动收录）

想让"本地电脑关机后依然能收录"，就把本技能配置成 WorkBuddy 自动化（定时触发或在手机云端模式触发）：

• 自动化在 WorkBuddy 云端运行，优先走「飞书连接器」（平台已连接的飞书授权，云端由平台直接提供，无需注入任何凭证），完全不依赖本机开机；
• 若云端环境无连接器能力，再降级 B/C. 飞书开放 API 通道（需在自动化环境注入自建应用 app_id/app_secret）；
• 注意：平台自动化是定时触发，不是"转发链接即触发"。若想自动收录，触发时把工具链接 / 视频描述作为 automation prompt 传入，五步照常执行；
• 无头执行注意：遇到"视频号无地址"等需要追问的情况，改为写入一条"待补充地址"的占位记录并留痕，不要卡住。

六、验收（写完后自查）

• [ ] 地址是真实的、能打开的，不是猜的
• [ ] 类型三选一，没有出现第四种值
• [ ] 功能介绍覆盖了领域 / 输入 / 输出
• [ ] 功能类别是五个标准值之一
• [ ] 使用教程是正文不是网址；步骤 ≥3 步、带注意事项、命令/按钮真实可照做
• [ ] 飞书写入成功（有 record_id）或已明确告知失败原因
• [ ] 已核验表里没有重复记录（终端不回显≠写入失败，别急着补写）
• [ ] 通道选择正确：优先用了「飞书连接器」（零凭证）；仅在有自建应用诉求时才走 OpenAPI 脚本

七、故障排查

Resources

scripts/

• sync_feishu.py —— 建表 / 补字段 / 追加记录到飞书多维表格；支持 --dry-run
• gen_tutorial.py —— 可选。生成自包含 HTML 使用教程；仅在用户明确要网页版教程时才用

config/

• feishu_config.example.json —— 飞书凭证配置模板

references/

• classification.md —— 类型与功能类别的判定细则与边界案例