五彩 API 执行规范 (WuCai Specification)
🚀 执行机制 (Execution Mechanism)
🚨 强制协议 (Mandatory Protocol): 本 Skill 采用“脚本代理”模式。严禁直接使用 curl, wget 或内置网络请求库。 所有 API 交互必须且只能通过执行 scripts/wucai_api.py 完成。
1.
必须使用 echo 配合管道符 | 将参数传递给脚本的
stdin。
2.
标准执行命令:
echo '<params_json>' | python3 scripts/wucai_api.py <endpoint>
-
自动处理: 脚本将自动从系统读取
$WUCAI_REGION 和
$WUCAI_API_TOKEN。
-
数据隔离: AI 必须意识到切换区域将连接到完全独立的数据库集群。
-
语言适配: AI 必须根据
$WUCAI_REGION 决定回复语言：
cn 使用中文，
eu/us 使用 English。
🛠️ 函数定义 (Functions)
1. 列表与检索 (Discovery)
- -
list_articles(range='today', status='inbox', cursor='', page_size=12, with_highlights=false): 获取文章列表。with_highlights=true 可直接返回文章划线列表。 - INLINECODE13 : 获取日记流。
with_highlights=true 可直接返回日记正文。 - INLINECODE15 : 聚合查看最新划线。
- INLINECODE16 : 搜索文章标题或页面笔记。
- INLINECODE17 : 跨文章精确搜索划线内容。
💡 Range 参数逻辑 (Global Range Logic):
所有支持 range 的接口均遵循以下严格的时间筛选逻辑：
- - 快捷键:
today, yesterday, week, 24h, 48h, 7d。 - 单日查询:
YYYY-MM-DD (如 2026-03-25)。 - 区间查询:
start:end (如 2026-03-01:2026-03-14)。 - 🚨 硬性限制: 所有查询（含快捷键及自定义区间）的跨度均不可超过 14 天。 若用户请求超出此范围，AI 应告知用户限制，或后端将自动截取最近 14 天的数据。
2. 详情与内容 (Content Intelligence)
- -
get_article_details(note_idx='', url=''): 获取单篇文章所有划线及元数据。
-
参数逻辑:
note_idx 与
url 二选一即可。用户粘贴链接时优先使用
url。
-
知识获取: 建议在回答用户关于特定网页的问题前，先调用此函数获取已有划线和笔记。
3. 操作与状态 (Action)
- -
append_diary(content): 向今日日记追加内容。 - INLINECODE34 : 修改状态 (
inbox, later, archive)。 - INLINECODE38 : 将文章移入回收站。
- INLINECODE39 : 更新页面笔记/感悟。
📋 响应解析规则
- - 成功判定: 脚本返回 JSON 且
code == 1。请从 data 字段提取内容。 - 失败判定:
code != 1 时，必须读取并直接向用户反馈 message 内容。
⚠️ 错误处理与双语话术 (Error Handling)
| 错误码 (Code) | 场景 (Scenario) | AI 引导话术 (CN / EN) |
|---|
| 10104 | 系统维护 / 降级 | “五彩系统当前正在维护中，请稍后再试。” / "WuCai system is under maintenance." |
| 10404 |
内容不存在 | “未找到相关记录。请检查链接或区域 ($WUCAI_REGION) 是否正确。” / "No records found. Please check URL or Region." |
|
10401 | 会员受限 | “此功能仅限五彩会员使用，请前往[会员中心]。” / "This feature requires VIP membership." |
|
10010 / 10016 | Token 失效 | “Token 已失效，请重新获取并配置。” / "Token expired. Please refresh your API Token." |
|
10035 | 范围/日期错误 | “查询跨度不能超过 14 天或日期格式有误。” / "Search range cannot exceed 14 days or invalid format." |
🔒 异常处理策略
- - Token 缺失: 引导用户前往相应区域的 OpenAPI 页面获取 Token。
- 链接一致性: 严禁在海外模式 (
eu/us) 下给出中文站链接，必须匹配当前 $WUCAI_REGION。
五彩 API 执行规范 (WuCai Specification)
🚀 执行机制 (Execution Mechanism)
🚨 强制协议 (Mandatory Protocol): 本技能采用“脚本代理”模式。严禁直接使用 curl、wget 或内置网络请求库。 所有 API 交互必须且只能通过执行 scripts/wucai_api.py 完成。
1.
必须使用 echo 配合管道符 | 将参数传递给脚本的标准输入。
2.
标准执行命令: echo
json> | python3 scripts/wucaiapi.py
- 自动处理: 脚本将自动从系统读取 $WUCAIREGION 和 $WUCAIAPI_TOKEN。
- 数据隔离: AI 必须意识到切换区域将连接到完全独立的数据库集群。
- 语言适配: AI 必须根据 $WUCAI_REGION 决定回复语言：cn 使用中文，eu/us 使用英文。
🛠️ 函数定义 (Functions)
1. 列表与检索 (Discovery)
- - listarticles(range=today, status=inbox, cursor=, pagesize=12, withhighlights=false): 获取文章列表。withhighlights=true 可直接返回文章划线列表。
- listdiary(range=today, status=all, cursor=, pagesize=12, withhighlights=false): 获取日记流。withhighlights=true 可直接返回日记正文。
- listhighlights(range=today, cursor=, pagesize=12): 聚合查看最新划线。
- searcharticles(query, cursor=, pagesize=12): 搜索文章标题或页面笔记。
- searchhighlights(query, cursor=, pagesize=12): 跨文章精确搜索划线内容。
💡 范围参数逻辑 (Global Range Logic):
所有支持 range 的接口均遵循以下严格的时间筛选逻辑：
- - 快捷键: today、yesterday、week、24h、48h、7d。
- 单日查询: YYYY-MM-DD (如 2026-03-25)。
- 区间查询: start:end (如 2026-03-01:2026-03-14)。
- 🚨 硬性限制: 所有查询（含快捷键及自定义区间）的跨度均不可超过 14 天。 若用户请求超出此范围，AI 应告知用户限制，或后端将自动截取最近 14 天的数据。
2. 详情与内容 (Content Intelligence)
- - getarticledetails(note_idx=, url=): 获取单篇文章所有划线及元数据。
- 参数逻辑: note_idx 与 url 二选一即可。用户粘贴链接时优先使用 url。
- 知识获取: 建议在回答用户关于特定网页的问题前，先调用此函数获取已有划线和笔记。
3. 操作与状态 (Action)
- - appenddiary(content): 向今日日记追加内容。
- setarticlestatus(noteidx, status): 修改状态 (inbox、later、archive)。
- trasharticle(noteidx): 将文章移入回收站。
- updatearticlenote(note_idx, note): 更新页面笔记/感悟。
📋 响应解析规则
- - 成功判定: 脚本返回 JSON 且 code == 1。请从 data 字段提取内容。
- 失败判定: code != 1 时，必须读取并直接向用户反馈 message 内容。
⚠️ 错误处理与双语话术 (Error Handling)
| 错误码 (Code) | 场景 (Scenario) | AI 引导话术 (CN / EN) |
|---|
| 10104 | 系统维护 / 降级 | “五彩系统当前正在维护中，请稍后再试。” / WuCai system is under maintenance. |
| 10404 |
内容不存在 | “未找到相关记录。请检查链接或区域 ($WUCAI_REGION) 是否正确。” / No records found. Please check URL or Region. |
| 10401 | 会员受限 | “此功能仅限五彩会员使用，请前往[会员中心]。” / This feature requires VIP membership. |
| 10010 / 10016 | Token 失效 | “Token 已失效，请重新获取并配置。” / Token expired. Please refresh your API Token. |
| 10035 | 范围/日期错误 | “查询跨度不能超过 14 天或日期格式有误。” / Search range cannot exceed 14 days or invalid format. |
🔒 异常处理策略
- - Token 缺失: 引导用户前往相应区域的 OpenAPI 页面获取 Token。
- 链接一致性: 严禁在海外模式 (eu/us) 下给出中文站链接，必须匹配当前 $WUCAI_REGION。
