From f0bdd26b087a4b506d37a5d893639557d06d942d Mon Sep 17 00:00:00 2001
From: Liu Zhicong <waterflier@gmail.com>
Date: Sat, 28 Mar 2026 11:08:58 -0700
Subject: [PATCH] build first real PRD for v1.0

---
 doc/opendan-data-scraping-dev-guide.md | 231 +++++++++++++++++++++++++
 1 file changed, 231 insertions(+)
 create mode 100644 doc/opendan-data-scraping-dev-guide.md

diff --git a/doc/opendan-data-scraping-dev-guide.md b/doc/opendan-data-scraping-dev-guide.md
new file mode 100644
index 0000000..cefda9d
--- /dev/null
+++ b/doc/opendan-data-scraping-dev-guide.md
@@ -0,0 +1,231 @@
+# Building Data Scraping Skills for OpenDAN
+
+> 为 OpenDAN Agent 开发数据抓取能力：第三方开发者指南
+
+---
+
+## 0. 为什么在 OpenDAN 上做，而不是自己写脚本？
+
+你当然可以自己写一个 Python 爬虫跑在 crontab 里。但你大概已经发现了这些问题：
+
+| 你遇到的问题 | 自己写脚本 | n8n / Make 等自动化平台 | OpenDAN |
+|---|---|---|---|
+| 页面结构变了，脚本挂了 | 手动修 selector，重新部署 | 同上，workflow 断掉需要人工介入 | Agent 有上下文理解能力，可以根据 Skill 里的判断标准自行调整抓取策略 |
+| 需要过登录墙 / 验证码 | 自己集成 Playwright + 各种 hack | 平台提供的浏览器能力有限 | Agent 可以调用浏览器能力，像人一样操作页面 |
+| 抓到的数据只有自己能用 | 数据格式随意，换个项目又得重新写 | 平台内部闭环，数据导出麻烦 | 统一 Schema，本地所有 Agent 共享同一份数据 |
+| 想加 AI 处理（摘要/分类/理解） | 自己对接 API，管 token、管 key | 需要额外付费接 AI 节点 | AICC 统一模型调用，开发者不用管供应商差异 |
+| 多个抓取任务需要协同 | 自己写调度逻辑 | 平台限制了组合方式 | 多个 Skill 天然可组合，Agent 按目标自主调度 |
+| 想让别人也能用你的能力 | 发个 GitHub repo，用户自行部署 | 发布到平台 marketplace，但受平台规则约束 | 发布 Skill + Tool 即可，其他用户的 Agent 直接调用 |
+
+**一句话：你写的不是一个跑一次就扔的脚本，而是一个可以被任何 Agent 反复使用的能力。**
+
+传统爬虫是"写死的流程"——一旦目标网站变化，流程就断。
+OpenDAN Skill 是"给 Agent 的操作说明"——Agent 根据说明自主决策，遇到异常可以自行调整。
+
+这意味着你的工作成果有更长的生命周期，也有更大的复用面。
+
+---
+
+## 1. 你要做的三件事
+
+为 OpenDAN Agent 提供数据抓取能力，只需要准备三样东西：
+
+**Tool** — 真正执行抓取的程序。CLI 工具、脚本、小程序都行。
+
+**Skill** — 告诉 Agent 怎么用这些 Tool 的操作说明。不是自动化脚本，是"目标 + 工具 + 判断标准"的组合。
+
+**Schema** — 抓取结果的数据格式。保证不同开发者、不同 Agent 之间的数据可以互通。
+
+---
+
+## 2. 从 Tool 开始，先跑通一个最小抓取
+
+### 选语言
+
+推荐 **TypeScript / tsx**，Python 也可以。
+
+### 写什么
+
+你的 Tool 就是一个普通 CLI 程序，做的事情和你过去写爬虫一样：
+
+- 调 API
+- 跑 Playwright / 无头浏览器
+- 解析页面
+- 输出结构化 JSON
+
+### 怎么发布
+
+第一版完全不需要学习 OpenDAN / BuckyOS 的包管理体系。
+你过去怎么发 npm 包，现在就怎么发：
+
+- `npx`
+- `pnpm`
+- 或者就是本地脚本
+
+等跑通以后，再考虑正式打包。
+
+---
+
+## 3. 写 Skill：给 Agent 的操作说明书
+
+Skill 不是"严格一步不差的自动化脚本"。
+它更像是你写给一个聪明但不了解具体业务的同事的操作指南。
+
+一个好的 Skill 要写清楚以下内容：
+
+### 目标
+
+> 给定一个用户账号，抓取其公开资料、帖子、媒体内容。
+
+或者：
+
+> 给定一个商品链接，抓取其标题、价格、评论、历史价格。
+
+### 可用工具
+
+列出 Agent 可以调用的 Tool，例如：
+
+- `fetch-x-profile` — 抓取 X 用户资料
+- `fetch-x-posts` — 抓取 X 用户帖子
+- `fetch-instagram-media` — 抓取 Instagram 媒体
+
+### 判断标准
+
+Agent 需要知道每一步"做对了"是什么样子：
+
+- profile 拿到了且字段完整 → 第一步成功
+- 帖子列表为空 → 需要判断是"真的没有"还是"抓取失败"
+- 页面返回登录墙 → 切换到浏览器模式重试
+
+### 常见错误和修正建议
+
+- 账号不存在 → 停止，返回明确错误
+- 页面结构变化 → 尝试用浏览器模式重新抓取
+- 请求频率过高 → 降速重试
+- 需要登录 → 提示用户提供凭据或切换策略
+
+**核心原则：给方向、给工具、给判断方法。** Agent Loop 自身有纠错能力，Skill 的重点不是"零错误执行"，而是让 Agent 知道目标在哪、手里有什么、怎么判断是否在逼近目标。
+
+---
+
+## 4. 定义数据格式：目录结构就是数据库
+
+抓取结果必须有统一结构，否则不同 Skill、不同 Agent 之间没法复用。
+
+推荐用目录结构直接组织数据：
+
+```
+data/
+  x/
+    alice/
+      profile.json          # 用户资料
+      posts/
+        post_001.json
+        post_002.json
+      media/
+        img_001.jpg
+  instagram/
+    alice/
+      profile.json
+      posts/
+      media/
+  bindings/
+    person_alice.json        # 跨平台身份绑定
+```
+
+**规则很简单：**
+
+- `{platform}/{account_id}/` 是基本单元
+- `profile.json` 存用户资料
+- `posts/` 存帖子
+- `media/` 存媒体文件
+- `bindings/` 把同一个人在不同平台的账号关联起来
+
+### 统一格式带来的两个直接好处
+
+**多 Skill 协同补数据。** 一个 Skill 抓 profile，一个 Skill 抓 posts，一个 Skill 抓 comments——最终都落到同一个目录结构里，互不干扰。
+
+**不同 Agent 复用结果。** Agent A 已经抓过的数据，Agent B 直接读取就行，不用重复抓。在 OpenDAN / BuckyOS 体系里，Agent 可以暴露服务接口，这意味着同一套 Skill 不只是"教 Agent 怎么抓"，还会自然形成**抓取结果的共享网络**。
+
+---
+
+## 5. 什么时候需要用 OpenDAN 的平台能力
+
+不是所有场景都需要学额外的东西。按你的需求分三档：
+
+### 情况 A：普通抓取 → 不需要任何平台能力
+
+如果你的 Tool 只做 HTTP 请求、页面解析、Playwright 抓取、文件处理，就按普通程序写，不用学任何额外概念。
+
+### 情况 B：Tool 内部需要 AI → 接入 AICC
+
+如果你想在工具内部做语义解析、内容摘要、评论分类、图像理解，接入 AICC 即可。
+
+AICC 的作用是统一模型调用。你给模型名、给 prompt、拿结果。不用自己折腾不同模型供应商的接入。
+
+**只有 Tool 里需要 AI 时，才需要了解 AICC。**
+
+### 情况 C：必须操作浏览器 / 桌面 → 使用 AgentPC
+
+有些网站没有 API 或反爬很强，需要浏览器自动化：获取页面截图、点击、输入、滚动、观察结果、循环执行。
+
+这时使用 OpenDAN 的 AgentPC / 浏览器能力。如果流程特别复杂，建议把浏览器操作任务交给专门的 Agent 处理，而不是全塞进一个 Tool。
+
+---
+
+## 6. 最小可用交付物
+
+你的第一版只需要做到这样：
+
+```
+my-scraping-skill/
+  skill.md                    # 操作说明书
+  tools/
+    fetch-x-profile.ts        # CLI 工具
+    fetch-x-posts.ts
+  schemas/
+    profile.schema.json        # 数据结构定义
+    post.schema.json
+  data-example/                # 实际结果示例
+    x/
+      alice/
+        profile.json
+        posts/
+          post_001.json
+```
+
+各部分职责：
+
+- **`skill.md`** — 适用范围、输入参数、推荐工具、成功判断、常见错误、输出目录
+- **`tools/`** — 你的 CLI 工具或脚本
+- **`schemas/`** — 你约定的数据结构（JSON Schema）
+- **`data-example/`** — 给其他开发者看的实际结果示例
+
+---
+
+## 7. 推荐上手顺序
+
+不要一开始做"大而全"。按这个顺序最容易跑通：
+
+1. **选一个网站** — 比如 X、Instagram、Amazon 其中一个
+2. **先定义结果格式** — 想清楚 profile、post、media 怎么存
+3. **写一个最小 Tool** — 先抓到最核心的一种数据
+4. **写一个最小 Skill** — 把目标、工具、判断标准写清楚
+5. **跑通一次完整流程** — 输入一个账号，输出一套目录
+6. **再补充能力** — 评论、图片、视频、跨平台绑定
+
+---
+
+## 8. 总结
+
+为 OpenDAN Agent 提供数据抓取能力，本质上就是：
+
+> **写一个抓取工具，写一份 Agent 能看懂的使用说明，再把结果按统一格式存下来。**
+
+三条核心原则：
+
+- **Tool 负责执行** — 做具体的抓取动作
+- **Skill 负责说明** — 告诉 Agent 怎么用、怎么判断
+- **Schema 负责复用** — 保证结果能被任何 Agent 直接使用
+
+和传统爬虫的本质区别在于：你写的不是一个只能自己用的脚本，而是一个**可以被整个 Agent 生态复用的能力模块**。