build first real PRD for v1.0
This commit is contained in:
Liu Zhicong
@@ -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 生态复用的能力模块**。
|
||||
Reference in New Issue
Block a user