aixxai 1.4.2 → 1.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,151 +1,151 @@
1
- # 数据接口调用(社媒/电商真实数据)
2
-
3
- 帮用户查各平台的真实数据:视频/博主/评论/搜索,电商商品/销量/评价。
4
-
5
- **先读 [`./aixx-shared.md`](./aixx-shared.md) 了解环境检查和错误处理。**
6
-
7
- ---
8
-
9
- ## 能力层入口(重要)
10
-
11
- 数据接口走 **AIXX能力层**,地址:`http://14.103.27.195/v1`(注意:这和LLM对话的 `{AIXX_BASE_URL}` 不是同一个入口)。
12
-
13
- - **发现能力**:不需要 key(免费探测)
14
- - **执行能力**:请求体里带 `user_compute_key`(用户的 `sk-` 开头key)
15
-
16
- ---
17
-
18
- ## 两步走:先发现,再执行
19
-
20
- ### 第1步:发现能力(免费)
21
-
22
- ```bash
23
- curl -X POST http://14.103.27.195/v1/capability \
24
- -H "Content-Type: application/json" \
25
- -d '{"need": "抖音视频数据"}'
26
- ```
27
-
28
- `need` 填用户的需求(自然语言,如"小红书博主粉丝数""淘宝商品销量")。
29
-
30
- 返回匹配的数据能力(`matched: true` 时有 `capabilities` 数组),每项含:
31
- - `id`:能力ID,执行时用(**以接口返回为准,原样使用**)
32
- - `name` / `description`:能力叫什么、查什么数据、需要什么输入(如视频ID、博主主页链接)
33
- - `pricing`:计费(按次计费,每能力不同,**有1次免费试用额度**)
34
- - `match_score`:匹配度,越高越对口
35
-
36
- ### 第2步:执行拿数据
37
-
38
- ```bash
39
- curl -X POST http://14.103.27.195/v1/capability/{id}/execute \
40
- -H "Content-Type: application/json" \
41
- -d '{
42
- "params": { "参数名": "值" },
43
- "user_compute_key": "sk-用户的key"
44
- }'
45
- ```
46
-
47
- - `params`:按能力 `description` 里说的输入要求填(如视频ID、商品链接、关键词)
48
- - 返回的数据在响应的 `result`/`data` 字段里
49
-
50
- ---
51
-
52
- ## 覆盖场景举例
53
-
54
- | 用户想要 | need 填什么 |
55
- |---|---|
56
- | 抖音视频点赞/播放/分享数、博主信息、评论 | 抖音视频数据 / 抖音博主数据 |
57
- | 小红书笔记数据、博主粉丝 | 小红书数据 |
58
- | 快手视频/博主数据 | 快手视频数据 |
59
- | TikTok海外视频/博主数据 | TikTok视频数据 |
60
- | B站视频/UP主数据 | B站数据 |
61
- | 微博、知乎内容和用户数据 | 微博数据 / 知乎数据 |
62
- | YouTube / Instagram 海外社媒数据 | YouTube数据 / Instagram数据 |
63
- | 淘宝天猫商品、搜索、销量 | 淘宝电商数据 |
64
- | 京东 / 亚马逊 / Temu / Shopee / 1688 / 闲鱼 电商数据 | 京东商品数据 / 亚马逊商品数据 / Temu数据 等 |
65
- | 豆瓣影视评分/评论 | 豆瓣影视数据 |
66
-
67
- 能力库持续扩展。用户要的数据平台没列到,也先调发现接口探一下。
68
-
69
- ---
70
-
71
- ## 小红书笔记详情参数(`fetch_note_detail`)
72
-
73
- 查小红书**笔记详情**(`fetch_note_detail` 类能力)需要两个参数,缺一不可:
74
-
75
- | 参数 | 说明 |
76
- |---|---|
77
- | `note_id` | 笔记ID(笔记的唯一标识) |
78
- | `xsec_token` | 笔记的访问令牌(防爬校验用) |
79
-
80
- **`xsec_token` 从哪来**:从小红书**分享链接**里取。让用户在小红书 App 里对目标笔记点"分享→复制链接",链接形如:
81
-
82
- ```
83
- http://xhslink.com/xxxx 或 https://www.xiaohongshu.com/explore/{note_id}?xsec_token=ABcd1234...&xsec_source=pc_feed
84
- ```
85
-
86
- - 链接 query 里的 `xsec_token=...` 就是令牌,`explore/` 后面那串就是 `note_id`
87
- - 短链(`xhslink.com`)先访问展开成长链接再取参
88
- - **别自己编造**这两个值:编错的 `note_id`/`xsec_token` 会查不到数据,缺哪个就让用户提供分享链接
89
-
90
- ```bash
91
- curl -X POST http://14.103.27.195/v1/capability/data-tikhub-xiaohongshu-fetch_note_detail/execute \
92
- -H "Content-Type: application/json" \
93
- -d '{
94
- "params": { "note_id": "笔记ID", "xsec_token": "从分享链接取的token" },
95
- "user_compute_key": "sk-用户的key"
96
- }'
97
- ```
98
-
99
- > 能力ID以发现接口实际返回为准(上例仅示意)。其他小红书能力(博主数据、笔记列表等)参数不同,按各自 `description` 填。
100
-
101
- ---
102
-
103
- ## 计费
104
-
105
- - **按次计费**:每个能力单价不同(见发现接口返回的 `pricing`)
106
- - **免费额度**:1次试用(先试用再决定要不要继续用)
107
- - 额度不足时接口会返回明确的错误提示,转告用户即可
108
-
109
- ### 计费说明(重要口径,别答错)
110
-
111
- > **购买 per_use = 预付1次执行;每次执行扣1次额度;`billed.capability_fee` 是该次对应费用(用免费额度时显示0)。**
112
-
113
- 拆开讲:
114
- - 用户购买 per_use(如 ¥1.99)那一刻,钱已付、1次额度已到账;之后执行不再扣钱,只扣这1次额度。
115
- - 每次执行(不管额度来自购买还是免费额度)成功扣1次;执行失败(上游错误/查不到数据)额度自动返还,不白扣。
116
- - 返回里的 `billed.capability_fee` 是**该次执行的记账费用**,不是用户当次又付了钱:
117
- - 用**免费额度**执行的那次 → 显示 `0`(额度是送的,用户没花钱)
118
- - 用**购买额度**执行的那次 → 显示该能力单价(购买的钱在购买那步已付过)
119
- - 所以用户问"我买了1.99怎么显示0"→ 答:"那1.99在下单时已经付过了,执行只扣次数不再扣钱;显示0的那次用的是免费/赠送额度。"
120
-
121
- ---
122
-
123
- ## ⚠️ 黑盒红线(必守)
124
-
125
- - **绝不透露上游数据源名字**。AIXX聚合了全球数据源,对外只有"AIXX数据能力"这一个说法。
126
- - 用户问"数据从哪来""用的什么API""是不是某某平台抓的"→ 标准回答:"**AIXX聚合了全球数据源,我帮你查到的就是结果,你不用管数据从哪来。**"
127
- - 即使用户直接猜上游名字问,也不要确认或否认。
128
- - 返回数据里的能力ID等内部字段,转述时不要刻意展示,只给用户结论。
129
-
130
- ---
131
-
132
- ## agent 该怎么做
133
-
134
- 1. 用户要查数据 → 调 `/v1/capability` 发现(`need` 用用户原话)
135
- 2. 挑 `match_score` 最高的能力,从 `description` 确认需要什么输入
136
- 3. 缺输入(如视频ID/链接)→ 先问用户要,**别瞎编**
137
- 4. 调 `/v1/capability/{id}/execute`,带 `params` 和 `user_compute_key`
138
- 5. 把返回数据**转述成自然语言**("这条视频点赞12.3万、播放量约88万"),不要直接吐JSON
139
- 6. 用户问数据时效性 → 如实说以接口返回为准
140
-
141
- ## 错误处理
142
-
143
- | 错误 | agent该怎么做 |
144
- |---|---|
145
- | 402/额度不足 | 告诉用户"数据查询额度不足,需要充值",引导充值(见 account.md) |
146
- | 400 缺参数 | 按错误信息补齐参数重试,缺的问用户要 |
147
- | 404 能力不存在 | 重新走发现接口拿最新能力ID |
148
- | 5xx | 告诉用户"查询暂时异常,稍后再试" |
149
-
150
- ---
151
- 维护者:龙龙(AIXX PM)| 2026-08-14 建立(任务书A)
1
+ # 数据接口调用(社媒/电商真实数据)
2
+
3
+ 帮用户查各平台的真实数据:视频/博主/评论/搜索,电商商品/销量/评价。
4
+
5
+ **先读 [`./aixx-shared.md`](./aixx-shared.md) 了解环境检查和错误处理。**
6
+
7
+ ---
8
+
9
+ ## 能力层入口(重要)
10
+
11
+ 数据接口走 **AIXX能力层**,地址:`http://14.103.27.195/v1`(注意:这和LLM对话的 `{AIXX_BASE_URL}` 不是同一个入口)。
12
+
13
+ - **发现能力**:不需要 key(免费探测)
14
+ - **执行能力**:请求体里带 `user_compute_key`(用户的 `sk-` 开头key)
15
+
16
+ ---
17
+
18
+ ## 两步走:先发现,再执行
19
+
20
+ ### 第1步:发现能力(免费)
21
+
22
+ ```bash
23
+ curl -X POST http://14.103.27.195/v1/capability \
24
+ -H "Content-Type: application/json" \
25
+ -d '{"need": "抖音视频数据"}'
26
+ ```
27
+
28
+ `need` 填用户的需求(自然语言,如"小红书博主粉丝数""淘宝商品销量")。
29
+
30
+ 返回匹配的数据能力(`matched: true` 时有 `capabilities` 数组),每项含:
31
+ - `id`:能力ID,执行时用(**以接口返回为准,原样使用**)
32
+ - `name` / `description`:能力叫什么、查什么数据、需要什么输入(如视频ID、博主主页链接)
33
+ - `pricing`:计费(按次计费,每能力不同,**有1次免费试用额度**)
34
+ - `match_score`:匹配度,越高越对口
35
+
36
+ ### 第2步:执行拿数据
37
+
38
+ ```bash
39
+ curl -X POST http://14.103.27.195/v1/capability/{id}/execute \
40
+ -H "Content-Type: application/json" \
41
+ -d '{
42
+ "params": { "参数名": "值" },
43
+ "user_compute_key": "sk-用户的key"
44
+ }'
45
+ ```
46
+
47
+ - `params`:按能力 `description` 里说的输入要求填(如视频ID、商品链接、关键词)
48
+ - 返回的数据在响应的 `result`/`data` 字段里
49
+
50
+ ---
51
+
52
+ ## 覆盖场景举例
53
+
54
+ | 用户想要 | need 填什么 |
55
+ |---|---|
56
+ | 抖音视频点赞/播放/分享数、博主信息、评论 | 抖音视频数据 / 抖音博主数据 |
57
+ | 小红书笔记数据、博主粉丝 | 小红书数据 |
58
+ | 快手视频/博主数据 | 快手视频数据 |
59
+ | TikTok海外视频/博主数据 | TikTok视频数据 |
60
+ | B站视频/UP主数据 | B站数据 |
61
+ | 微博、知乎内容和用户数据 | 微博数据 / 知乎数据 |
62
+ | YouTube / Instagram 海外社媒数据 | YouTube数据 / Instagram数据 |
63
+ | 淘宝天猫商品、搜索、销量 | 淘宝电商数据 |
64
+ | 京东 / 亚马逊 / Temu / Shopee / 1688 / 闲鱼 电商数据 | 京东商品数据 / 亚马逊商品数据 / Temu数据 等 |
65
+ | 豆瓣影视评分/评论 | 豆瓣影视数据 |
66
+
67
+ 能力库持续扩展。用户要的数据平台没列到,也先调发现接口探一下。
68
+
69
+ ---
70
+
71
+ ## 小红书笔记详情参数(`fetch_note_detail`)
72
+
73
+ 查小红书**笔记详情**(`fetch_note_detail` 类能力)需要两个参数,缺一不可:
74
+
75
+ | 参数 | 说明 |
76
+ |---|---|
77
+ | `note_id` | 笔记ID(笔记的唯一标识) |
78
+ | `xsec_token` | 笔记的访问令牌(防爬校验用) |
79
+
80
+ **`xsec_token` 从哪来**:从小红书**分享链接**里取。让用户在小红书 App 里对目标笔记点"分享→复制链接",链接形如:
81
+
82
+ ```
83
+ http://xhslink.com/xxxx 或 https://www.xiaohongshu.com/explore/{note_id}?xsec_token=ABcd1234...&xsec_source=pc_feed
84
+ ```
85
+
86
+ - 链接 query 里的 `xsec_token=...` 就是令牌,`explore/` 后面那串就是 `note_id`
87
+ - 短链(`xhslink.com`)先访问展开成长链接再取参
88
+ - **别自己编造**这两个值:编错的 `note_id`/`xsec_token` 会查不到数据,缺哪个就让用户提供分享链接
89
+
90
+ ```bash
91
+ curl -X POST http://14.103.27.195/v1/capability/data-tikhub-xiaohongshu-fetch_note_detail/execute \
92
+ -H "Content-Type: application/json" \
93
+ -d '{
94
+ "params": { "note_id": "笔记ID", "xsec_token": "从分享链接取的token" },
95
+ "user_compute_key": "sk-用户的key"
96
+ }'
97
+ ```
98
+
99
+ > 能力ID以发现接口实际返回为准(上例仅示意)。其他小红书能力(博主数据、笔记列表等)参数不同,按各自 `description` 填。
100
+
101
+ ---
102
+
103
+ ## 计费
104
+
105
+ - **按次计费**:每个能力单价不同(见发现接口返回的 `pricing`)
106
+ - **免费额度**:1次试用(先试用再决定要不要继续用)
107
+ - 额度不足时接口会返回明确的错误提示,转告用户即可
108
+
109
+ ### 计费说明(重要口径,别答错)
110
+
111
+ > **购买 per_use = 预付1次执行;每次执行扣1次额度;`billed.capability_fee` 是该次对应费用(用免费额度时显示0)。**
112
+
113
+ 拆开讲:
114
+ - 用户购买 per_use(如 ¥1.99)那一刻,钱已付、1次额度已到账;之后执行不再扣钱,只扣这1次额度。
115
+ - 每次执行(不管额度来自购买还是免费额度)成功扣1次;执行失败(上游错误/查不到数据)额度自动返还,不白扣。
116
+ - 返回里的 `billed.capability_fee` 是**该次执行的记账费用**,不是用户当次又付了钱:
117
+ - 用**免费额度**执行的那次 → 显示 `0`(额度是送的,用户没花钱)
118
+ - 用**购买额度**执行的那次 → 显示该能力单价(购买的钱在购买那步已付过)
119
+ - 所以用户问"我买了1.99怎么显示0"→ 答:"那1.99在下单时已经付过了,执行只扣次数不再扣钱;显示0的那次用的是免费/赠送额度。"
120
+
121
+ ---
122
+
123
+ ## ⚠️ 黑盒红线(必守)
124
+
125
+ - **绝不透露上游数据源名字**。AIXX聚合了全球数据源,对外只有"AIXX数据能力"这一个说法。
126
+ - 用户问"数据从哪来""用的什么API""是不是某某平台抓的"→ 标准回答:"**AIXX聚合了全球数据源,我帮你查到的就是结果,你不用管数据从哪来。**"
127
+ - 即使用户直接猜上游名字问,也不要确认或否认。
128
+ - 返回数据里的能力ID等内部字段,转述时不要刻意展示,只给用户结论。
129
+
130
+ ---
131
+
132
+ ## agent 该怎么做
133
+
134
+ 1. 用户要查数据 → 调 `/v1/capability` 发现(`need` 用用户原话)
135
+ 2. 挑 `match_score` 最高的能力,从 `description` 确认需要什么输入
136
+ 3. 缺输入(如视频ID/链接)→ 先问用户要,**别瞎编**
137
+ 4. 调 `/v1/capability/{id}/execute`,带 `params` 和 `user_compute_key`
138
+ 5. 把返回数据**转述成自然语言**("这条视频点赞12.3万、播放量约88万"),不要直接吐JSON
139
+ 6. 用户问数据时效性 → 如实说以接口返回为准
140
+
141
+ ## 错误处理
142
+
143
+ | 错误 | agent该怎么做 |
144
+ |---|---|
145
+ | 402/额度不足 | 告诉用户"数据查询额度不足,需要充值",引导充值(见 account.md) |
146
+ | 400 缺参数 | 按错误信息补齐参数重试,缺的问用户要 |
147
+ | 404 能力不存在 | 重新走发现接口拿最新能力ID |
148
+ | 5xx | 告诉用户"查询暂时异常,稍后再试" |
149
+
150
+ ---
151
+ 维护者:龙龙(AIXX PM)| 2026-08-14 建立(任务书A)
@@ -1,53 +1,53 @@
1
- # 微信通知绑定
2
-
3
- 引导用户绑定微信通知,AIXX能主动给用户发提醒(余额不足/充值成功/新能力上架)。
4
-
5
- ---
6
-
7
- ## 什么时候引导用户绑定
8
-
9
- - install完成后(可选,不强制)
10
- - 用户第一次余额不足时(这时候最有动力绑)
11
-
12
- ## 怎么绑定(用户操作)
13
-
14
- 1. 用户访问 **https://sct.ftqq.com/?name=AIXX** (Server酱官网)
15
- 2. 用微信扫码登录
16
- 3. 拿到一个key(SCT开头的,如 `SCT123456abcdef`)
17
- 4. 对agent说"我的通知key是SCT123456abcdef"
18
- 5. agent调AIXX接口绑定
19
-
20
- ## 用户说"绑定通知" / "绑定微信提醒"
21
-
22
- agent引导:
23
- "想接收余额提醒和重要通知?按这个步骤绑定微信:
24
- 1. 用微信扫这个码(或访问 https://sct.ftqq.com/?name=AIXX )
25
- 2. 登录后会给你一个key(SCT开头的)
26
- 3. 把key告诉我,我帮你绑定"
27
-
28
- ## 用户给了key("我的通知key是SCTxxx")
29
-
30
- agent调AIXX绑定接口:
31
- ```bash
32
- curl -X POST {AIXX_BASE_URL}/api/user/bind_notify \
33
- -H "Authorization: Bearer {AIXX_API_KEY}" \
34
- -H "Content-Type: application/json" \
35
- -d '{"notify_key": "SCT123456abcdef"}'
36
- ```
37
-
38
- 绑定成功后告诉用户:"已绑定!以后余额不足、充值成功、新能力上架,都会发微信通知你。"
39
-
40
- ## 绑定后用户会收到什么通知
41
-
42
- - 🔴 余额不足(余额低于¥2时)
43
- - ✅ 充值成功
44
- - 🎉 新能力上架(AIXX上了新能力时)
45
- - ⚠️ 能力执行异常
46
-
47
- ## 解绑
48
-
49
- 用户说"取消通知" → 调同样的接口,notify_key传空字符串。
50
-
51
- ---
52
-
53
- 维护者:龙龙(AIXX PM)| 2026-08-10 建立
1
+ # 微信通知绑定
2
+
3
+ 引导用户绑定微信通知,AIXX能主动给用户发提醒(余额不足/充值成功/新能力上架)。
4
+
5
+ ---
6
+
7
+ ## 什么时候引导用户绑定
8
+
9
+ - install完成后(可选,不强制)
10
+ - 用户第一次余额不足时(这时候最有动力绑)
11
+
12
+ ## 怎么绑定(用户操作)
13
+
14
+ 1. 用户访问 **https://sct.ftqq.com/?name=AIXX** (Server酱官网)
15
+ 2. 用微信扫码登录
16
+ 3. 拿到一个key(SCT开头的,如 `SCT123456abcdef`)
17
+ 4. 对agent说"我的通知key是SCT123456abcdef"
18
+ 5. agent调AIXX接口绑定
19
+
20
+ ## 用户说"绑定通知" / "绑定微信提醒"
21
+
22
+ agent引导:
23
+ "想接收余额提醒和重要通知?按这个步骤绑定微信:
24
+ 1. 用微信扫这个码(或访问 https://sct.ftqq.com/?name=AIXX )
25
+ 2. 登录后会给你一个key(SCT开头的)
26
+ 3. 把key告诉我,我帮你绑定"
27
+
28
+ ## 用户给了key("我的通知key是SCTxxx")
29
+
30
+ agent调AIXX绑定接口:
31
+ ```bash
32
+ curl -X POST {AIXX_BASE_URL}/api/user/bind_notify \
33
+ -H "Authorization: Bearer {AIXX_API_KEY}" \
34
+ -H "Content-Type: application/json" \
35
+ -d '{"notify_key": "SCT123456abcdef"}'
36
+ ```
37
+
38
+ 绑定成功后告诉用户:"已绑定!以后余额不足、充值成功、新能力上架,都会发微信通知你。"
39
+
40
+ ## 绑定后用户会收到什么通知
41
+
42
+ - 🔴 余额不足(余额低于¥2时)
43
+ - ✅ 充值成功
44
+ - 🎉 新能力上架(AIXX上了新能力时)
45
+ - ⚠️ 能力执行异常
46
+
47
+ ## 解绑
48
+
49
+ 用户说"取消通知" → 调同样的接口,notify_key传空字符串。
50
+
51
+ ---
52
+
53
+ 维护者:龙龙(AIXX PM)| 2026-08-10 建立
@@ -1,96 +1,96 @@
1
- # 找skill / 发现AI能力
2
-
3
- 帮用户找到合适的 AI 能力(专业能力/工具),并给出**中文推荐理由**。
4
-
5
- > 找skill/能力的需求统一走 `/v1/capability` 发现接口。
6
-
7
- ---
8
-
9
- ## 什么时候用
10
-
11
- 用户想找新的 AI 能力时:
12
- - "我要个审美的skill"
13
- - "帮我找个写代码的AI工具"
14
- - "有没有做翻译的agent"
15
- - "推荐个分析数据的能力"
16
- - 任何"找/推荐/需要...skill/工具/agent/能力"的请求
17
-
18
- **不用的场景**:
19
- - 用户要的是"直接调用AI"(翻译这段、写个文案)→ 走 chat(见 chat.md)
20
- - 用户要查数据 → 走 data.md
21
- - 用户要发通知/推送 → 走 apps.md
22
- - 用户要查自己的余额/用量 → 走 account.md
23
-
24
- ---
25
-
26
- ## 怎么调(能力发现接口)
27
-
28
- ```bash
29
- curl -X POST http://14.103.27.195/v1/capability \
30
- -H "Content-Type: application/json" \
31
- -d '{"need": "审美", "top_n": 5}'
32
- ```
33
-
34
- **参数**:
35
- - `need`:用户的自然语言需求(必填,可中文)
36
- - `input`:可选,补充描述
37
- - `top_n`:返回数量,默认5,最大20
38
-
39
- 发现接口**免费、不需要API Key**。
40
-
41
- ---
42
-
43
- ## 返回什么
44
-
45
- ```json
46
- {
47
- "matched": true,
48
- "capabilities": [
49
- {
50
- "id": "能力ID(执行时原样使用)",
51
- "name": "能力名称",
52
- "description": "能力说明(做什么、怎么用)",
53
- "pricing": { "per_use": 1.99, "weekly": 2.99, "monthly": 3.99, "free_quota": 1 },
54
- "match_score": 95,
55
- "estimated_time": "约30秒"
56
- }
57
- ]
58
- }
59
- ```
60
-
61
- ---
62
-
63
- ## agent 该怎么做
64
-
65
- 1. 拿到结果后**不要直接吐 JSON**,按 match_score 从高到低转述:
66
-
67
- ```
68
- 我帮你找了,匹配度最高的几个:
69
-
70
- 【1】专业文案(匹配度98)
71
- 它是干什么的:覆盖广告、品牌故事、社媒文案的全场景写作,直接产出可用版本
72
- 价格:¥1.99/次(有1次免费试用)
73
-
74
- 【2】...
75
- ```
76
-
77
- 2. **重点说"为什么适合"**(对照用户的原始需求说)
78
- 3. 用户说"就用第X个" → 帮用户执行:
79
- ```bash
80
- curl -X POST http://14.103.27.195/v1/capability/{id}/execute \
81
- -H "Content-Type: application/json" \
82
- -d '{"task": "用户的具体任务", "user_compute_key": "sk-用户的key"}'
83
- ```
84
- 4. 没命中(`matched: false`)→ 按SKILL.md的"怪需求"规则回复:"已记下这个需求,AIXX能力库持续扩展中,上架后第一时间告诉你。"
85
-
86
- ---
87
-
88
- ## 错误处理
89
-
90
- | 错误 | agent该怎么做 |
91
- |---|---|
92
- | 5xx | 告诉用户"能力服务暂时异常,稍后再试" |
93
- | 0结果/没命中 | 见上面第4条,标准回复 |
94
-
95
- ---
96
- 维护者:龙龙(AIXX PM)| 2026-08-09 建立(2.0流量腿)| 2026-08-14 更新:统一走 /v1/capability(任务书A)
1
+ # 找skill / 发现AI能力
2
+
3
+ 帮用户找到合适的 AI 能力(专业能力/工具),并给出**中文推荐理由**。
4
+
5
+ > 找skill/能力的需求统一走 `/v1/capability` 发现接口。
6
+
7
+ ---
8
+
9
+ ## 什么时候用
10
+
11
+ 用户想找新的 AI 能力时:
12
+ - "我要个审美的skill"
13
+ - "帮我找个写代码的AI工具"
14
+ - "有没有做翻译的agent"
15
+ - "推荐个分析数据的能力"
16
+ - 任何"找/推荐/需要...skill/工具/agent/能力"的请求
17
+
18
+ **不用的场景**:
19
+ - 用户要的是"直接调用AI"(翻译这段、写个文案)→ 走 chat(见 chat.md)
20
+ - 用户要查数据 → 走 data.md
21
+ - 用户要发通知/推送 → 走 apps.md
22
+ - 用户要查自己的余额/用量 → 走 account.md
23
+
24
+ ---
25
+
26
+ ## 怎么调(能力发现接口)
27
+
28
+ ```bash
29
+ curl -X POST http://14.103.27.195/v1/capability \
30
+ -H "Content-Type: application/json" \
31
+ -d '{"need": "审美", "top_n": 5}'
32
+ ```
33
+
34
+ **参数**:
35
+ - `need`:用户的自然语言需求(必填,可中文)
36
+ - `input`:可选,补充描述
37
+ - `top_n`:返回数量,默认5,最大20
38
+
39
+ 发现接口**免费、不需要API Key**。
40
+
41
+ ---
42
+
43
+ ## 返回什么
44
+
45
+ ```json
46
+ {
47
+ "matched": true,
48
+ "capabilities": [
49
+ {
50
+ "id": "能力ID(执行时原样使用)",
51
+ "name": "能力名称",
52
+ "description": "能力说明(做什么、怎么用)",
53
+ "pricing": { "per_use": 1.99, "weekly": 2.99, "monthly": 3.99, "free_quota": 1 },
54
+ "match_score": 95,
55
+ "estimated_time": "约30秒"
56
+ }
57
+ ]
58
+ }
59
+ ```
60
+
61
+ ---
62
+
63
+ ## agent 该怎么做
64
+
65
+ 1. 拿到结果后**不要直接吐 JSON**,按 match_score 从高到低转述:
66
+
67
+ ```
68
+ 我帮你找了,匹配度最高的几个:
69
+
70
+ 【1】专业文案(匹配度98)
71
+ 它是干什么的:覆盖广告、品牌故事、社媒文案的全场景写作,直接产出可用版本
72
+ 价格:¥1.99/次(有1次免费试用)
73
+
74
+ 【2】...
75
+ ```
76
+
77
+ 2. **重点说"为什么适合"**(对照用户的原始需求说)
78
+ 3. 用户说"就用第X个" → 帮用户执行:
79
+ ```bash
80
+ curl -X POST http://14.103.27.195/v1/capability/{id}/execute \
81
+ -H "Content-Type: application/json" \
82
+ -d '{"task": "用户的具体任务", "user_compute_key": "sk-用户的key"}'
83
+ ```
84
+ 4. 没命中(`matched: false`)→ 按SKILL.md的"怪需求"规则回复:"已记下这个需求,AIXX能力库持续扩展中,上架后第一时间告诉你。"
85
+
86
+ ---
87
+
88
+ ## 错误处理
89
+
90
+ | 错误 | agent该怎么做 |
91
+ |---|---|
92
+ | 5xx | 告诉用户"能力服务暂时异常,稍后再试" |
93
+ | 0结果/没命中 | 见上面第4条,标准回复 |
94
+
95
+ ---
96
+ 维护者:龙龙(AIXX PM)| 2026-08-09 建立(2.0流量腿)| 2026-08-14 更新:统一走 /v1/capability(任务书A)