aixxai 1.5.0 → 1.5.2

package/templates/references/chat.md

@@ -1,135 +1,135 @@
-# LLM 对话调用
-
-翻译、写作、改写、总结、分析、问答、代码生成等**需要LLM能力**的请求。
-
-**先读 [`./aixx-shared.md`](./aixx-shared.md) 了解环境检查和调用方式。**
-
----
-
-## 调用方式（OpenAI 兼容）
-
-```bash
-curl -X POST {AIXX_BASE_URL}/chat/completions \
-  -H "Authorization: Bearer {AIXX_API_KEY}" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "deepseek-chat",
-    "messages": [
-      {"role": "user", "content": "用户的实际需求"}
-    ]
-  }'
-```
-
-返回标准 OpenAI 格式，结果在 `choices[0].message.content`。
-
----
-
-## 默认模型选择（重要）
-
-AIXX 会自动选最优模型，但 agent 也可以按任务指定。
-
-> **模型列表持续更新，调 `GET /v1/models` 获取最新，下表仅场景参考。**
-
-| 任务类型 | 推荐模型 | 理由 |
-|---|---|---|
-| 翻译/简单问答/日常 | `deepseek-chat` | 最便宜，日常首选 |
-| 复杂推理/数学 | `kimi-k2.6` | 带思考过程（deepseek-reasoner 已下架） |
-| 中文写作/文案 | `deepseek-chat` | 中文能力够用且便宜（glm渠道维护中，文案任务先用deepseek-chat） |
-| 长文档分析 | `moonshot-v1-128k` | 超长上下文 |
-| 复杂任务/最强 | `claude-opus-4-8` | 能力最强 |
-| 通用旗舰 | `gpt-5.5` | 通用 |
-| 审美/UI/设计 | （先搜索skill，见 search.md） | 专门skill比通用模型强 |
-| 轻量免费任务 | `glm-4-flash` | 免费，但不支持工具调用(function calling)；需工具调用用 `deepseek-chat` |
-
-> ⚠️ **推理类模型（kimi-k2.6 / claude系思考模型等）**：max_tokens 要给足（≥2000）。思考token计入max_tokens预算，给小了会返回空内容。
-
-**不指定 model 时**：用 `deepseek-chat`（最便宜，省用户额度）。
-
----
-
-## 用户常见请求怎么处理
-
-### "帮我翻译这段"
-1. 用 `deepseek-chat`（翻译最便宜够用）
-2. messages 里放：`把下面的内容翻译成英文：{用户的内容}`
-
-### "用Claude分析这个"
-1. 用户指定了Claude，用 `claude-opus-4-8` 或 `claude-sonnet-4-20250514`
-2. 如果用户额度不够用Claude（402错误），提示用户"额度不足，要不要用deepseek-chat代替（更便宜）"
-
-### "用最便宜的模型做"
-1. 直接用 `deepseek-chat`
-
-### "写个中文文案"
-1. 用 `deepseek-chat`（中文能力够用且便宜；glm渠道维护中，恢复后可用 `glm-4-plus`）
-
----
-
-## agent 该怎么做
-
-1. 判断任务类型 → 选模型（或让AIXX自动选）
-2. 把用户需求组织成 messages
-3. 调 `/chat/completions`
-4. 把 `choices[0].message.content` 转述给用户
-5. **不要直接吐 JSON**，用自然语言回复
-
----
-
-## ⚠️ 敏感问题处理（重要·诚信红线）
-
-有些问题**不要直接转给模型**，agent 要自己判断处理。否则模型会瞎编、损害信誉。
-
-### 必须拦截的问题（别转给模型，agent 自己处理）
-
-| 用户问 | ❌ 错误做法 | ✅ 正确做法 |
-|---|---|---|
-| "我账户还有多少钱""余额""额度" | 转给模型（模型会瞎说"无法查看"） | **调 balance 接口**（见 account.md），用真实数据回答 |
-| "我花了多少""用量" | 转给模型 | 调 billing/usage 接口 |
-| "有哪些模型可用" | 转给模型 | 调 /v1/models 接口 |
-| "怎么充值" | 转给模型 | 引导用 `aixx recharge` 命令 |
-
-**原则**：凡是 AIXX 有接口能查到的事实，**必须调接口拿真实数据**，不能让模型猜。
-
-### 身份/来源问题（转给模型，但要加 system 引导）
-
-用户可能问："你是哪家公司""你是DeepSeek吗""源头是哪里""是不是中转站""官方认证吗"。
-
-**处理方式**：调模型时**必须加 system prompt 引导**，避免模型瞎编或撒谎：
-
-```
-messages: [
-  {"role": "system", "content": "你是通过AIXX平台调用的AI助手。回答身份问题时遵守：
-    1. 如实说明自己的模型身份（是DeepSeek就说DeepSeek，是Claude就说Claude，不冒充别的）
-    2. 不编造'通过官网/APP/官方认证'等不实信息（你实际是通过AIXX统一平台调用的）
-    3. 被问到'是不是官方直连/中转站'时，如实回答：你是通过AIXX这个统一AI平台调用的，AIXX聚合了多家官方模型能力
-    4. 不主动暴露过多技术细节，但绝不撒谎"},
-  {"role": "user", "content": "用户的身份问题"}
-]
-```
-
-**这样模型会**：
-- 是DeepSeek就说DeepSeek（真话）
-- 不再编"官网/APP/官方认证"（去掉幻觉）
-- 被直接问中转时说"通过AIXX统一平台调用"（诚实但不生硬）
-
-### 绝对不能做的事（诚信红线）
-
-- ❌ 冒充别的模型（DeepSeek冒充Claude、套壳）—— 这是 apiyi 式造假，AIXX 永不做
-- ❌ 说"官方认证""官方直连"等不实信息
-- ❌ 把查得到的事实（余额/模型列表）让模型瞎猜
-
-**AIXX 的信誉根基是：模型是真的，账本是实的。** 宁可少说，绝不撒谎。
-
----
-维护者：龙龙（AIXX PM）| 2026-08-09 建立（2.0流量腿）
-
----
-
-## 错误处理
-
-见 [`./aixx-shared.md`](./aixx-shared.md) 的错误表。常见：
-- 402 额度不足：提示用户充值（"您额度不足，可以充值或用更便宜的deepseek-chat"）
-- 404 模型不存在：换用 `deepseek-chat`
-
----
-维护者：龙龙（AIXX PM）| 2026-08-09 建立
+# LLM 对话调用
+
+翻译、写作、改写、总结、分析、问答、代码生成等**需要LLM能力**的请求。
+
+**先读 [`./aixx-shared.md`](./aixx-shared.md) 了解环境检查和调用方式。**
+
+---
+
+## 调用方式（OpenAI 兼容）
+
+```bash
+curl -X POST {AIXX_BASE_URL}/chat/completions \
+  -H "Authorization: Bearer {AIXX_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "deepseek-chat",
+    "messages": [
+      {"role": "user", "content": "用户的实际需求"}
+    ]
+  }'
+```
+
+返回标准 OpenAI 格式，结果在 `choices[0].message.content`。
+
+---
+
+## 默认模型选择（重要）
+
+AIXX 会自动选最优模型，但 agent 也可以按任务指定。
+
+> **模型列表持续更新，调 `GET /v1/models` 获取最新，下表仅场景参考。**
+
+| 任务类型 | 推荐模型 | 理由 |
+|---|---|---|
+| 翻译/简单问答/日常 | `deepseek-chat` | 最便宜，日常首选 |
+| 复杂推理/数学 | `kimi-k2.6` | 带思考过程（deepseek-reasoner 已下架） |
+| 中文写作/文案 | `deepseek-chat` | 中文能力够用且便宜（glm渠道维护中，文案任务先用deepseek-chat） |
+| 长文档分析 | `moonshot-v1-128k` | 超长上下文 |
+| 复杂任务/最强 | `claude-opus-4-8` | 能力最强 |
+| 通用旗舰 | `gpt-5.5` | 通用 |
+| 审美/UI/设计 | （先搜索skill，见 search.md） | 专门skill比通用模型强 |
+| 轻量免费任务 | `glm-4-flash` | 免费，但不支持工具调用(function calling)；需工具调用用 `deepseek-chat` |
+
+> ⚠️ **推理类模型（kimi-k2.6 / claude系思考模型等）**：max_tokens 要给足（≥2000）。思考token计入max_tokens预算，给小了会返回空内容。
+
+**不指定 model 时**：用 `deepseek-chat`（最便宜，省用户额度）。
+
+---
+
+## 用户常见请求怎么处理
+
+### "帮我翻译这段"
+1. 用 `deepseek-chat`（翻译最便宜够用）
+2. messages 里放：`把下面的内容翻译成英文：{用户的内容}`
+
+### "用Claude分析这个"
+1. 用户指定了Claude，用 `claude-opus-4-8` 或 `claude-sonnet-4-20250514`
+2. 如果用户额度不够用Claude（402错误），提示用户"额度不足，要不要用deepseek-chat代替（更便宜）"
+
+### "用最便宜的模型做"
+1. 直接用 `deepseek-chat`
+
+### "写个中文文案"
+1. 用 `deepseek-chat`（中文能力够用且便宜；glm渠道维护中，恢复后可用 `glm-4-plus`）
+
+---
+
+## agent 该怎么做
+
+1. 判断任务类型 → 选模型（或让AIXX自动选）
+2. 把用户需求组织成 messages
+3. 调 `/chat/completions`
+4. 把 `choices[0].message.content` 转述给用户
+5. **不要直接吐 JSON**，用自然语言回复
+
+---
+
+## ⚠️ 敏感问题处理（重要·诚信红线）
+
+有些问题**不要直接转给模型**，agent 要自己判断处理。否则模型会瞎编、损害信誉。
+
+### 必须拦截的问题（别转给模型，agent 自己处理）
+
+| 用户问 | ❌ 错误做法 | ✅ 正确做法 |
+|---|---|---|
+| "我账户还有多少钱""余额""额度" | 转给模型（模型会瞎说"无法查看"） | **调 balance 接口**（见 account.md），用真实数据回答 |
+| "我花了多少""用量" | 转给模型 | 调 billing/usage 接口 |
+| "有哪些模型可用" | 转给模型 | 调 /v1/models 接口 |
+| "怎么充值" | 转给模型 | 引导用 `aixx recharge` 命令 |
+
+**原则**：凡是 AIXX 有接口能查到的事实，**必须调接口拿真实数据**，不能让模型猜。
+
+### 身份/来源问题（转给模型，但要加 system 引导）
+
+用户可能问："你是哪家公司""你是DeepSeek吗""源头是哪里""是不是中转站""官方认证吗"。
+
+**处理方式**：调模型时**必须加 system prompt 引导**，避免模型瞎编或撒谎：
+
+```
+messages: [
+  {"role": "system", "content": "你是通过AIXX平台调用的AI助手。回答身份问题时遵守：
+    1. 如实说明自己的模型身份（是DeepSeek就说DeepSeek，是Claude就说Claude，不冒充别的）
+    2. 不编造'通过官网/APP/官方认证'等不实信息（你实际是通过AIXX统一平台调用的）
+    3. 被问到'是不是官方直连/中转站'时，如实回答：你是通过AIXX这个统一AI平台调用的，AIXX聚合了多家官方模型能力
+    4. 不主动暴露过多技术细节，但绝不撒谎"},
+  {"role": "user", "content": "用户的身份问题"}
+]
+```
+
+**这样模型会**：
+- 是DeepSeek就说DeepSeek（真话）
+- 不再编"官网/APP/官方认证"（去掉幻觉）
+- 被直接问中转时说"通过AIXX统一平台调用"（诚实但不生硬）
+
+### 绝对不能做的事（诚信红线）
+
+- ❌ 冒充别的模型（DeepSeek冒充Claude、套壳）—— 这是 apiyi 式造假，AIXX 永不做
+- ❌ 说"官方认证""官方直连"等不实信息
+- ❌ 把查得到的事实（余额/模型列表）让模型瞎猜
+
+**AIXX 的信誉根基是：模型是真的，账本是实的。** 宁可少说，绝不撒谎。
+
+---
+维护者：龙龙（AIXX PM）| 2026-08-09 建立（2.0流量腿）
+
+---
+
+## 错误处理
+
+见 [`./aixx-shared.md`](./aixx-shared.md) 的错误表。常见：
+- 402 额度不足：提示用户充值（"您额度不足，可以充值或用更便宜的deepseek-chat"）
+- 404 模型不存在：换用 `deepseek-chat`
+
+---
+维护者：龙龙（AIXX PM）| 2026-08-09 建立

package/templates/references/data.md

@@ -1,151 +1,151 @@
-# 数据接口调用（社媒/电商真实数据）
-
-帮用户查各平台的真实数据：视频/博主/评论/搜索，电商商品/销量/评价。
-
-**先读 [`./aixx-shared.md`](./aixx-shared.md) 了解环境检查和错误处理。**
-
----
-
-## 能力层入口（重要）
-
-数据接口走 **AIXX能力层**，地址：`http://14.103.27.195/v1`（注意：这和LLM对话的 `{AIXX_BASE_URL}` 不是同一个入口）。
-
-- **发现能力**：不需要 key（免费探测）
-- **执行能力**：请求体里带 `user_compute_key`（用户的 `sk-` 开头key）
-
----
-
-## 两步走：先发现，再执行
-
-### 第1步：发现能力（免费）
-
-```bash
-curl -X POST http://14.103.27.195/v1/capability \
-  -H "Content-Type: application/json" \
-  -d '{"need": "抖音视频数据"}'
-```
-
-`need` 填用户的需求（自然语言，如"小红书博主粉丝数""淘宝商品销量"）。
-
-返回匹配的数据能力（`matched: true` 时有 `capabilities` 数组），每项含：
-- `id`：能力ID，执行时用（**以接口返回为准，原样使用**）
-- `name` / `description`：能力叫什么、查什么数据、需要什么输入（如视频ID、博主主页链接）
-- `pricing`：计费（按次计费，每能力不同，**有1次免费试用额度**）
-- `match_score`：匹配度，越高越对口
-
-### 第2步：执行拿数据
-
-```bash
-curl -X POST http://14.103.27.195/v1/capability/{id}/execute \
-  -H "Content-Type: application/json" \
-  -d '{
-    "params": { "参数名": "值" },
-    "user_compute_key": "sk-用户的key"
-  }'
-```
-
-- `params`：按能力 `description` 里说的输入要求填（如视频ID、商品链接、关键词）
-- 返回的数据在响应的 `result`/`data` 字段里
-
----
-
-## 覆盖场景举例
-
-| 用户想要 | need 填什么 |
-|---|---|
-| 抖音视频点赞/播放/分享数、博主信息、评论 | 抖音视频数据 / 抖音博主数据 |
-| 小红书笔记数据、博主粉丝 | 小红书数据 |
-| 快手视频/博主数据 | 快手视频数据 |
-| TikTok海外视频/博主数据 | TikTok视频数据 |
-| B站视频/UP主数据 | B站数据 |
-| 微博、知乎内容和用户数据 | 微博数据 / 知乎数据 |
-| YouTube / Instagram 海外社媒数据 | YouTube数据 / Instagram数据 |
-| 淘宝天猫商品、搜索、销量 | 淘宝电商数据 |
-| 京东 / 亚马逊 / Temu / Shopee / 1688 / 闲鱼 电商数据 | 京东商品数据 / 亚马逊商品数据 / Temu数据 等 |
-| 豆瓣影视评分/评论 | 豆瓣影视数据 |
-
-能力库持续扩展。用户要的数据平台没列到，也先调发现接口探一下。
-
----
-
-## 小红书笔记详情参数（`fetch_note_detail`）
-
-查小红书**笔记详情**（`fetch_note_detail` 类能力）需要两个参数，缺一不可：
-
-| 参数 | 说明 |
-|---|---|
-| `note_id` | 笔记ID（笔记的唯一标识） |
-| `xsec_token` | 笔记的访问令牌（防爬校验用） |
-
-**`xsec_token` 从哪来**：从小红书**分享链接**里取。让用户在小红书 App 里对目标笔记点"分享→复制链接"，链接形如：
-
-```
-http://xhslink.com/xxxx 或 https://www.xiaohongshu.com/explore/{note_id}?xsec_token=ABcd1234...&xsec_source=pc_feed
-```
-
-- 链接 query 里的 `xsec_token=...` 就是令牌，`explore/` 后面那串就是 `note_id`
-- 短链（`xhslink.com`）先访问展开成长链接再取参
-- **别自己编造**这两个值：编错的 `note_id`/`xsec_token` 会查不到数据，缺哪个就让用户提供分享链接
-
-```bash
-curl -X POST http://14.103.27.195/v1/capability/data-tikhub-xiaohongshu-fetch_note_detail/execute \
-  -H "Content-Type: application/json" \
-  -d '{
-    "params": { "note_id": "笔记ID", "xsec_token": "从分享链接取的token" },
-    "user_compute_key": "sk-用户的key"
-  }'
-```
-
-> 能力ID以发现接口实际返回为准（上例仅示意）。其他小红书能力（博主数据、笔记列表等）参数不同，按各自 `description` 填。
-
----
-
-## 计费
-
-- **按次计费**：每个能力单价不同（见发现接口返回的 `pricing`）
-- **免费额度**：1次试用（先试用再决定要不要继续用）
-- 额度不足时接口会返回明确的错误提示，转告用户即可
-
-### 计费说明（重要口径，别答错）
-
-> **购买 per_use = 预付1次执行；每次执行扣1次额度；`billed.capability_fee` 是该次对应费用（用免费额度时显示0）。**
-
-拆开讲：
-- 用户购买 per_use（如 ¥1.99）那一刻，钱已付、1次额度已到账；之后执行不再扣钱，只扣这1次额度。
-- 每次执行（不管额度来自购买还是免费额度）成功扣1次；执行失败（上游错误/查不到数据）额度自动返还，不白扣。
-- 返回里的 `billed.capability_fee` 是**该次执行的记账费用**，不是用户当次又付了钱：
-  - 用**免费额度**执行的那次 → 显示 `0`（额度是送的，用户没花钱）
-  - 用**购买额度**执行的那次 → 显示该能力单价（购买的钱在购买那步已付过）
-- 所以用户问"我买了1.99怎么显示0"→ 答："那1.99在下单时已经付过了，执行只扣次数不再扣钱；显示0的那次用的是免费/赠送额度。"
-
----
-
-## ⚠️ 黑盒红线（必守）
-
-- **绝不透露上游数据源名字**。AIXX聚合了全球数据源，对外只有"AIXX数据能力"这一个说法。
-- 用户问"数据从哪来""用的什么API""是不是某某平台抓的"→ 标准回答："**AIXX聚合了全球数据源，我帮你查到的就是结果，你不用管数据从哪来。**"
-- 即使用户直接猜上游名字问，也不要确认或否认。
-- 返回数据里的能力ID等内部字段，转述时不要刻意展示，只给用户结论。
-
----
-
-## agent 该怎么做
-
-1. 用户要查数据 → 调 `/v1/capability` 发现（`need` 用用户原话）
-2. 挑 `match_score` 最高的能力，从 `description` 确认需要什么输入
-3. 缺输入（如视频ID/链接）→ 先问用户要，**别瞎编**
-4. 调 `/v1/capability/{id}/execute`，带 `params` 和 `user_compute_key`
-5. 把返回数据**转述成自然语言**（"这条视频点赞12.3万、播放量约88万"），不要直接吐JSON
-6. 用户问数据时效性 → 如实说以接口返回为准
-
-## 错误处理
-
-| 错误 | agent该怎么做 |
-|---|---|
-| 402/额度不足 | 告诉用户"数据查询额度不足，需要充值"，引导充值（见 account.md） |
-| 400 缺参数 | 按错误信息补齐参数重试，缺的问用户要 |
-| 404 能力不存在 | 重新走发现接口拿最新能力ID |
-| 5xx | 告诉用户"查询暂时异常，稍后再试" |
-
----
-维护者：龙龙（AIXX PM）| 2026-08-14 建立（任务书A）
+# 数据接口调用（社媒/电商真实数据）
+
+帮用户查各平台的真实数据：视频/博主/评论/搜索，电商商品/销量/评价。
+
+**先读 [`./aixx-shared.md`](./aixx-shared.md) 了解环境检查和错误处理。**
+
+---
+
+## 能力层入口（重要）
+
+数据接口走 **AIXX能力层**，地址：`http://14.103.27.195/v1`（注意：这和LLM对话的 `{AIXX_BASE_URL}` 不是同一个入口）。
+
+- **发现能力**：不需要 key（免费探测）
+- **执行能力**：请求体里带 `user_compute_key`（用户的 `sk-` 开头key）
+
+---
+
+## 两步走：先发现，再执行
+
+### 第1步：发现能力（免费）
+
+```bash
+curl -X POST http://14.103.27.195/v1/capability \
+  -H "Content-Type: application/json" \
+  -d '{"need": "抖音视频数据"}'
+```
+
+`need` 填用户的需求（自然语言，如"小红书博主粉丝数""淘宝商品销量"）。
+
+返回匹配的数据能力（`matched: true` 时有 `capabilities` 数组），每项含：
+- `id`：能力ID，执行时用（**以接口返回为准，原样使用**）
+- `name` / `description`：能力叫什么、查什么数据、需要什么输入（如视频ID、博主主页链接）
+- `pricing`：计费（按次计费，每能力不同，**有1次免费试用额度**）
+- `match_score`：匹配度，越高越对口
+
+### 第2步：执行拿数据
+
+```bash
+curl -X POST http://14.103.27.195/v1/capability/{id}/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "params": { "参数名": "值" },
+    "user_compute_key": "sk-用户的key"
+  }'
+```
+
+- `params`：按能力 `description` 里说的输入要求填（如视频ID、商品链接、关键词）
+- 返回的数据在响应的 `result`/`data` 字段里
+
+---
+
+## 覆盖场景举例
+
+| 用户想要 | need 填什么 |
+|---|---|
+| 抖音视频点赞/播放/分享数、博主信息、评论 | 抖音视频数据 / 抖音博主数据 |
+| 小红书笔记数据、博主粉丝 | 小红书数据 |
+| 快手视频/博主数据 | 快手视频数据 |
+| TikTok海外视频/博主数据 | TikTok视频数据 |
+| B站视频/UP主数据 | B站数据 |
+| 微博、知乎内容和用户数据 | 微博数据 / 知乎数据 |
+| YouTube / Instagram 海外社媒数据 | YouTube数据 / Instagram数据 |
+| 淘宝天猫商品、搜索、销量 | 淘宝电商数据 |
+| 京东 / 亚马逊 / Temu / Shopee / 1688 / 闲鱼 电商数据 | 京东商品数据 / 亚马逊商品数据 / Temu数据 等 |
+| 豆瓣影视评分/评论 | 豆瓣影视数据 |
+
+能力库持续扩展。用户要的数据平台没列到，也先调发现接口探一下。
+
+---
+
+## 小红书笔记详情参数（`fetch_note_detail`）
+
+查小红书**笔记详情**（`fetch_note_detail` 类能力）需要两个参数，缺一不可：
+
+| 参数 | 说明 |
+|---|---|
+| `note_id` | 笔记ID（笔记的唯一标识） |
+| `xsec_token` | 笔记的访问令牌（防爬校验用） |
+
+**`xsec_token` 从哪来**：从小红书**分享链接**里取。让用户在小红书 App 里对目标笔记点"分享→复制链接"，链接形如：
+
+```
+http://xhslink.com/xxxx 或 https://www.xiaohongshu.com/explore/{note_id}?xsec_token=ABcd1234...&xsec_source=pc_feed
+```
+
+- 链接 query 里的 `xsec_token=...` 就是令牌，`explore/` 后面那串就是 `note_id`
+- 短链（`xhslink.com`）先访问展开成长链接再取参
+- **别自己编造**这两个值：编错的 `note_id`/`xsec_token` 会查不到数据，缺哪个就让用户提供分享链接
+
+```bash
+curl -X POST http://14.103.27.195/v1/capability/data-tikhub-xiaohongshu-fetch_note_detail/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "params": { "note_id": "笔记ID", "xsec_token": "从分享链接取的token" },
+    "user_compute_key": "sk-用户的key"
+  }'
+```
+
+> 能力ID以发现接口实际返回为准（上例仅示意）。其他小红书能力（博主数据、笔记列表等）参数不同，按各自 `description` 填。
+
+---
+
+## 计费
+
+- **按次计费**：每个能力单价不同（见发现接口返回的 `pricing`）
+- **免费额度**：1次试用（先试用再决定要不要继续用）
+- 额度不足时接口会返回明确的错误提示，转告用户即可
+
+### 计费说明（重要口径，别答错）
+
+> **购买 per_use = 预付1次执行；每次执行扣1次额度；`billed.capability_fee` 是该次对应费用（用免费额度时显示0）。**
+
+拆开讲：
+- 用户购买 per_use（如 ¥1.99）那一刻，钱已付、1次额度已到账；之后执行不再扣钱，只扣这1次额度。
+- 每次执行（不管额度来自购买还是免费额度）成功扣1次；执行失败（上游错误/查不到数据）额度自动返还，不白扣。
+- 返回里的 `billed.capability_fee` 是**该次执行的记账费用**，不是用户当次又付了钱：
+  - 用**免费额度**执行的那次 → 显示 `0`（额度是送的，用户没花钱）
+  - 用**购买额度**执行的那次 → 显示该能力单价（购买的钱在购买那步已付过）
+- 所以用户问"我买了1.99怎么显示0"→ 答："那1.99在下单时已经付过了，执行只扣次数不再扣钱；显示0的那次用的是免费/赠送额度。"
+
+---
+
+## ⚠️ 黑盒红线（必守）
+
+- **绝不透露上游数据源名字**。AIXX聚合了全球数据源，对外只有"AIXX数据能力"这一个说法。
+- 用户问"数据从哪来""用的什么API""是不是某某平台抓的"→ 标准回答："**AIXX聚合了全球数据源，我帮你查到的就是结果，你不用管数据从哪来。**"
+- 即使用户直接猜上游名字问，也不要确认或否认。
+- 返回数据里的能力ID等内部字段，转述时不要刻意展示，只给用户结论。
+
+---
+
+## agent 该怎么做
+
+1. 用户要查数据 → 调 `/v1/capability` 发现（`need` 用用户原话）
+2. 挑 `match_score` 最高的能力，从 `description` 确认需要什么输入
+3. 缺输入（如视频ID/链接）→ 先问用户要，**别瞎编**
+4. 调 `/v1/capability/{id}/execute`，带 `params` 和 `user_compute_key`
+5. 把返回数据**转述成自然语言**（"这条视频点赞12.3万、播放量约88万"），不要直接吐JSON
+6. 用户问数据时效性 → 如实说以接口返回为准
+
+## 错误处理
+
+| 错误 | agent该怎么做 |
+|---|---|
+| 402/额度不足 | 告诉用户"数据查询额度不足，需要充值"，引导充值（见 account.md） |
+| 400 缺参数 | 按错误信息补齐参数重试，缺的问用户要 |
+| 404 能力不存在 | 重新走发现接口拿最新能力ID |
+| 5xx | 告诉用户"查询暂时异常，稍后再试" |
+
+---
+维护者：龙龙（AIXX PM）| 2026-08-14 建立（任务书A）