AI 接入说明与方法

1. 三档 AI 用量对比

下表逐项列出「看读量」与「AI 用量」。AI 用量每日重置；看读量为订阅期内永久解锁。

2. 免费档：没有 AI，怎么用？

免费用户没有 Agent API、没有 AI 问答，但仍可用「人工检索」把这套语料用起来。

• 网页原话搜索：每站每天 3 次原话搜索（按 IP 计）。直接在子站「原话检索」框输入关键词即可，结果带视频秒数 / 文章段落溯源。
• 结构化浏览：免费额度内可看每站 20 条完整中英对照、5 个核心观点簇、3 张技能卡、第 1 周学习路径——这些是人工整理好的「现成答案」，不需要 AI。
• 判断是否值得订阅：先用免费额度把一位大佬的观点簇和学习路径跑一遍，再决定升级。

3. 基础版（¥199/年）：AI 问答 3 次/天怎么用

基础版解锁全部看读内容 + 笔记/进度/导出，并赠送每天 3 次网页内 AI 问答。

1. 微信小店付款后自动收到 KV-B- 开头的兑换码。
2. 在任意子站或归集页输入兑换码激活（见 第 6 节）。
3. 进入任意大佬站点，在「AI 问答」框用自然语言提问（如"Naval 怎么讲杠杆？"），每天 3 次。

4. 专业版（¥299/年）：完整 Agent API / MCP 用法

专业版在基础版之上，额外获得每天 15 次 AI 问答 + Agent API Key + MCP Server，可把整套大佬语料接进你自己的 AI 工作流。

5. 专业版比基础版多出的 AI 接入

每项一句话说明价值与入口。

6. 如何激活 & 领取 Agent API Key

第一步：购买并拿到兑换码

1. 在微信小店（爱迪创思小店）购买基础版 ¥199/年 或 专业版 ¥299/年。
2. 付款后微信小店自动发货，收到 KV-B-（基础版）或 KV-P-（专业版）开头的兑换码。

第二步：激活（任选其一）

• 归集页：icons.ideatrace.cn →「订阅套餐」→「已有兑换码？」→ 输入。
• 任意子站：点右上角「订阅套餐」→「已有兑换码？」→ 输入。

第三步（仅专业版）：领取 Agent API Key

激活成功后，专业版会在激活结果里直接返回 api_key。也可以随时用兑换码幂等重领：

# 专业版兑换码换 Key（幂等，重复调用返回同一 Key）
curl -X POST https://icons.ideatrace.cn/api/agent/v1/key \
  -H "Content-Type: application/json" \
  -d '{"code":"KV-P-你的兑换码"}'

{
  "schema": "ideatrace.agent.v1",
  "ok": false,
  "error": { "code": "INVALID_CODE", "message": "兑换码不存在" }
}

7. 用 curl 调 Agent API

Base URL：https://icons.ideatrace.cn。除 /stats 外，数据接口均需 Authorization: Bearer <KEY>。

curl "https://icons.ideatrace.cn/api/agent/v1/stats?person=naval"

{
  "schema": "ideatrace.agent.v1",
  "ok": true,
  "data": {
    "person": "naval",
    "stats": { "videos": 237, "chunks": 14398, "distillations": 227, "viewpoints": 30, "skills": 5, ... }
  }
}

curl "https://icons.ideatrace.cn/api/agent/v1/search?person=naval&q=leverage&limit=5" \
  -H "Authorization: Bearer 你的KEY"

# 视频：分段 en/zh 成对，带 start_sec 可跳播
curl "https://icons.ideatrace.cn/api/agent/v1/bilingual?person=naval&video_id=001" \
  -H "Authorization: Bearer 你的KEY"

# 文章：按 slug 取中英对照
curl "https://icons.ideatrace.cn/api/agent/v1/bilingual?person=pg&essay_slug=powerful" \
  -H "Authorization: Bearer 你的KEY"

8. 用 MCP 接入 Claude Code / 豆包 / Codex

MCP Server 地址：https://icons.ideatrace.cn/mcp（streamable-http，JSON-RPC 2.0）。

握手（实测 2026-09-29）

curl -X POST https://icons.ideatrace.cn/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "ideatrace-agent", "version": "3.0.0" }
  }
}

可用工具（tools/list 实测）

在 MCP 客户端里配置

{
  "mcpServers": {
    "ideatrace": {
      "url": "https://icons.ideatrace.cn/mcp"
    }
  }
}

9. 次数与配额说明

• 每日额度：免费原话搜索 3 次/天（按 IP）；基础版网页 AI 问答 3 次/天；专业版网页 AI 问答 15 次/天 + Agent API/MCP 数据工具合计 15 次/天。
• 重置：每日自然日重置。本次只读实测无法验证服务器采用 UTC 还是北京时间（UTC+8），以 quota_config.json 与服务器配置为准；如发现跨日不重置，请反馈客服。
• 用完后行为：接口返回 429，设计上错误码 QUOTA_EXCEEDED 并附中文提示。本次实测 429 响应体为空（见「服务器端待办」），客户端应把 429 统一解释为「今日额度已用完，明日重置」。
• 不占额度的接口：/stats、MCP 的 initialize 与 tools/list 握手与枚举不计数。

10. 错误处理速查表

11. 常见问题 FAQ

12. 实测确认（2026-09-29 公网只读）

以下为当日实际请求/响应片段，作为本页接口行为的事实依据。

13. 服务器端待办（部署阶段由组织者处理）

1. 兑换端点 404：POST /api/redeem 与 POST /auth/redeem 公网实测返回 404，但 openapi.json 声明它们、归集页前端 doRedeem() 调用 /api/redeem。需确认兑换路由是否上线 / 是否走其他路径，否则前端兑换弹窗会失败。
2. MCP/Agent 覆盖站点不全：MCP person 枚举仅 8 站（koeverse/naval/pg/jc/ds/altman/andreessen/dalio），归集页已有 12 站（多 hormozi/diaryceo/seths/munger）。需为后 4 站补齐 search/stats/bilingual 数据管道与枚举。
3. 错误响应 schema 缺失：openapi.json 所有 responses 只写「200 OK」，未定义 401/403/429/5xx 的错误体结构。实际错误信封为 {"ok":false,"error":{"code","message"}}（实测 INVALID_CODE），需补进契约。
4. 429/401 响应体为空：实测 429（Content-Length 167）与 401（Content-Length 108）有长度但无可读 JSON body。需确认是否应返回 error.code=QUOTA_EXCEEDED 与中文提示，便于客户端展示。
5. 每日重置时区：只读实测无法验证计数窗口是 UTC 还是北京时间（UTC+8），需与 quota_config.json 对齐后在本页补注。
6. MCP 鉴权：initialize / tools/list 可匿名完成，但数据工具匿名会撞 429。需确认 MCP 是否支持在 streamable-http 层接收 Bearer 并计入专业版额度（本页已提示客户端配置 header）。