Crypto News HTTP API 技能

使用此技能调用 OpenClaw 提供的 Crypto News Analyzer HTTP API。

适用场景

当您需要调用 https://news.tradao.xyz 或兼容的私有部署实例时，请使用该技能。

典型触发条件：

• 在指定时间窗口内异步执行加密货币新闻分析
• 针对自由形式的主题查询，异步执行统一语义搜索（新闻 + 情报）
• 轮询一个 API 任务直至其完成，然后获取最终结果
• 通过 HTTP API 创建、列出或删除数据源（datasource）
• 通过主题优先（topic-first）API 查询和管理情报主题（创建、修订、确认、合并发现项、查看详情、列出、归档）
• 查看并管理主题与数据源之间的关联关系（获取、设置、添加、移除），以限定主题研究范围
• 按主题或全局列出情报主题研究运行日志
• 在 API 工作流执行前或后检查服务健康状态

快速参考

认证方式为 Bearer Token：每个请求均需携带 Authorization: Bearer 头部。

POST /analyze 立即创建一个任务并返回响应，但不返回最终分析报告。需轮询任务状态，再获取结果。

标准工作流：POST /analyze → GET /analyze/{job_id} → GET /analyze/{job_id}/result

任务状态流转顺序为：queued、running、completed、failed。

POST /semantic-search 创建语义搜索任务，返回 202 Accepted，响应体中包含 status_url、result_url，以及 Retry-After 响应头。若请求参数 hours 超过服务器最大允许值（默认 720 小时），响应中将包含 warning 字段说明截断情况。语义搜索任务若在 5 分钟内未完成，将自动失败并返回超时错误。

语义搜索工作流：POST /semantic-search → GET /semantic-search/{job_id} → GET /semantic-search/{job_id}/result

统一语义搜索同时从 content_items 和 raw_intelligence_items 表中检索数据，底层基于 PostgreSQL 的 pgvector HNSW 索引（embedding vector(1536)）。SQLite 运行时不被支持。

详细指南请参阅：

• Analyze 工作流参考
• Semantic Search 参考
• Datasource 管理参考
• Intelligence 查询参考
• 运维与维护参考

OpenClaw 运行时

本技能声明了 metadata.openclaw.primaryEnv: API_KEY。在 OpenClaw 中，需通过 ~/.openclaw/openclaw.json 注入 Bearer Token：

{
  skills: {
    entries: {
      "smart-news": {
        enabled: true,
        apiKey: "YOUR_API_KEY"
      }
    }
  }
}

若 apiKey 不可用，请勿发送未认证请求；应先提示操作员配置 Token。

若您使用的是非生产环境部署，请在发起请求前将 https://news.tradao.xyz 替换为正确的基础 URL。

Analyze 工作流

向 /analyze 发送 POST 请求，并提供 hours 和 user_id 参数，即可创建分析任务。服务端返回 202 Accepted，附带 job_id、status_url 和 result_url。

持续轮询状态接口，直到任务进入 completed 或 failed 状态。初始 POST 响应中不会包含分析报告。任务完成后，请访问 result_url 获取结果。

语义搜索（Semantic Search）

统一语义搜索通过 UNION ALL 操作，在 pgvector HNSW 索引之上同时检索新闻（content_items）与情报（raw_intelligence_items）两个领域。响应中包含 source_breakdown 字段，分别给出各领域的 matched_count（匹配数）和 retained_count（保留数）。每个匹配项均携带 source_domain 标识符（取值为 "news" 或 "intelligence"）。

向 /semantic-search 发送 POST 请求，并提供 hours、query 和 user_id 参数，即可创建语义搜索任务。服务端返回 202 Accepted，附带 job_id、status_url 和 result_url。语义搜索任务 ID 均以 semantic_search_job_ 开头。

持续轮询状态接口，直到任务进入 completed 或 failed 状态，再通过 result_url 获取报告。请以响应中的 status 字段作为生命周期状态的唯一可信来源；仅当任务成功完成时，success 字段才为 true。

请求规则：

• hours 必须为正整数
• query 为必填字段，将被自动去除首尾空格，且长度上限为 300 字符
• query 不可为空或仅含空白字符
• user_id 必须匹配正则表达式 ^[A-Za-z0-9_-]{1,128}$

运行约束：

• 语义搜索仅支持 PostgreSQL；若后端不支持 pgvector，则返回 503
• content_items 与 raw_intelligence_items 表均包含 embedding vector(1536) 列，并已建立 HNSW 索引（分别为 idx_content_embedding_hnsw 和 idx_intelligence_embedding_hnsw）
• API 使用向量相似度计算对已存储的内容嵌入（embedding）进行检索，并结合确定性的本地关键词回退机制（不依赖 LLM 进行关键词扩展）
• LLM 查询分解功能默认禁用（query_planning_enabled: false）；禁用时，原始用户查询将被直接嵌入为唯一子查询。仅当显式启用查询规划时，max_subqueries 上限（4）才生效
• 合并前，每个领域最多保留 200 条唯一结果
• 嵌入向量生成需配置 OPENAI_API_KEY；报告合成需配置 KIMI_API_KEY 或 GROK_API_KEY（查询规划同样需要 LLM 密钥，但默认处于禁用状态）

响应体返回一份 Markdown 格式报告，包含以下字段：query、normalized_intent、matched_count、retained_count、time_window_hours、source_breakdown 和 report。

数据源（Datasource）管理

可通过数据源 API 配置新闻与情报来源。使用 POST /datasources 创建来源，GET /datasources 列出所有来源，DELETE /datasources/{id} 删除指定来源。所有数据源相关路由均需 Bearer 认证。

每个数据源均具有 purpose 字段，取值为：news（用于分析的 RSS/X/REST 接口）或 intelligence（用于主题研究的 Telegram 群组、V2EX 等）。GET /datasources 支持可选的 purpose 和 source_type 查询参数用于过滤。结果按 purpose、source_type、name 顺序排序。

标签（Tags）用于组织数据源。每个数据源最多支持 16 个唯一标签，每个标签长度上限为 32 字符。标签将被自动转为小写并去重。

列表与创建响应仅返回安全摘要信息。对于 rest_api 类型的数据源，敏感凭证字段将被脱敏处理，仅显示计数统计，防止在审查配置时意外泄露凭据。

情报查询（主题优先，Topic-First）

所有情报相关路由均需 Bearer 认证。在本次面向主题的重构中，已移除所有基于条目（entry）的旧版路由（如 /intelligence/entries*、/intelligence/discovery、/intelligence/labels、/intelligence/search）。主题（Topic）是唯一的一等情报对象，驱动着基于原始摄入消息的定时 LLM 研究，并支持合并研究成果。

同步主题工作流端点：

• POST /intelligence/topics —— 根据用户主题创建主题草稿（返回 AI 生成的 Prompt 草稿）
• POST /intelligence/topics/{topic_id}/revise —— 基于反馈修订 Prompt 草稿
• PUT /intelligence/topics/{topic_id}/prompt —— 手动设置/替换 Prompt 文本（上下文感知：若当前已有活跃 Prompt，则编辑之；否则创建草稿修订版）
• POST /intelligence/topics/{topic_id}/confirm —— 确认并激活主题以启动研究（需提供 prompt_version_id）
• GET /intelligence/topics —— 分页列出主题，支持 active_only 过滤器（默认为 true）
• GET /intelligence/topics/{topic_id} —— 获取主题元数据及合并可用性
• GET /intelligence/topics/{topic_id}/findings —— 分页获取活跃发现项（含引用与来源 URL）
• GET /intelligence/topics/{topic_id}/prompts —— 获取 Prompt 版本历史及当前活跃 Prompt
• POST /intelligence/topics/{topic_id}/archive —— 归档主题
• GET /intelligence/topics/{topic_id}/runs —— 列出该主题的研究运行日志
• GET /intelligence/topic-runs —— 全局列出所有主题研究运行日志

上述端点均为同步接口，无异步任务/轮询流程，响应立即返回。

异步主题合并端点：

• POST /intelligence/topics/{topic_id}/merge —— 启动异步合并任务（返回 202 Accepted，含 job_id、status_url、result_url）
• GET /intelligence/topics/{topic_id}/merge/{job_id} —— 查询合并任务状态
• GET /intelligence/topics/{topic_id}/merge/{job_id}/result —— 获取已完成的合并结果

合并工作流：POST /intelligence/topics/{id}/merge → 轮询 GET .../merge/{job_id} → GET .../merge/{job_id}/result。任务状态包括：queued、running、completed、failed。由于合并过程涉及 LLM 调用，可能耗时数分钟，因此必须轮询 —— 请勿阻塞等待 POST 响应。

主题具有如下生命周期状态：draft（草稿）、active（活跃）、archived（归档）。仅 active 状态的主题会被摄入调度器（ingestion scheduler）纳入研究。发现项（finding）合并既可通过异步 HTTP 端点触发，也可通过 Telegram 的 /topic_merge 命令执行。

Telegram Webhook

Webhook 端点专为维护人员级的 Telegram 集成而设，不是日常运营人员的主要交互路径。普通用户应通过 API 路由或 Telegram 斜杠命令进行交互。

处理 Webhook 更新时，请校验 X-Telegram-Bot-Api-Secret-Token 请求头，以确认请求确实来自 Telegram。

端点索引

当前支持的 HTTP 路由如下：

• GET /health —— 服务健康检查
• POST /analyze —— 创建分析任务（异步，返回 202）
• GET /analyze/{job_id} —— 查询任务状态
• GET /analyze/{job_id}/result —— 获取已完成任务的结果
• POST /semantic-search —— 创建语义搜索任务（异步，返回 202）
• GET /semantic-search/{job_id} —— 查询语义搜索任务状态
• GET /semantic-search/{job_id}/result —— 获取已完成语义搜索的结果
• POST /datasources —— 创建数据源
• GET /datasources —— 列出全部数据源
• DELETE /datasources/{id} —— 删除指定数据源
• POST /telegram/webhook —— Telegram Webhook 接收端点
• POST /intelligence/topics —— 创建主题草稿（同步，需 Bearer 认证）
• POST /intelligence/topics/{id}/revise —— 修订主题 Prompt
• PUT /intelligence/topics/{id}/prompt —— 手动设置主题 Prompt
• POST /intelligence/topics/{id}/confirm —— 确认并激活主题
• GET /intelligence/topics —— 列出主题（支持状态过滤）
• GET /intelligence/topics/{id} —— 获取主题元数据及合并可用性
• GET /intelligence/topics/{id}/findings —— 获取带引用的分页发现项
• GET /intelligence/topics/{id}/prompts —— 获取 Prompt 版本及当前活跃 Prompt
• POST /intelligence/topics/{id}/archive —— 归档主题
• POST /intelligence/topics/{id}/merge —— 启动异步合并任务（返回 202）
• GET /intelligence/topics/{id}/merge/{job_id} —— 查询合并任务状态
• GET /intelligence/topics/{id}/merge/{job_id}/result —— 获取已完成合并结果
• GET /intelligence/topics/{id}/datasources —— 列出某主题关联的数据源
• PUT /intelligence/topics/{id}/datasources —— 原子性地替换全部数据源关联
• POST /intelligence/topics/{id}/datasources/{datasource_id} —— 添加数据源关联（幂等）
• DELETE /intelligence/topics/{id}/datasources/{datasource_id} —— 移除数据源关联（幂等）
• GET /intelligence/topics/{id}/runs —— 列出该主题的研究运行日志
• GET /intelligence/topic-runs —— 全局列出所有主题研究运行日志

非目标范围

本技能不涵盖以下内容：

• Telegram 斜杠命令（请直接使用 Telegram Bot）
• 自动生成文档路由（/docs、/redoc、/openapi.json）
• 已弃用的兼容性别名不属于当前活跃运行时接口面
• 超出文档化命令指引范围的直接嵌入向量回填（backfill）操作

以上功能虽存在，但被有意排除在此 API 导向型技能之外。

更新说明

请保持本技能与以下最新实现保持同步：

• api_server.py 中的实时 HTTP 路由定义
• docs/AI_ANALYZE_API_GUIDE.md 中的 AI Analyze API 指南
• docs/SEMANTIC_SEARCH_API_GUIDE.md 中的语义搜索指南
• domain/repositories.py 中的领域仓库契约（domain repository contracts）

当文档与实际代码实现冲突时，请以代码和测试为准，而非文字文档。优先级顺序为：代码 > 参考文件 > 指南文档。