乾坤先机 API 文档

在线获取与 AI 同步

文档随当前应用版本提供，使用部署站点的同一域名访问以下稳定入口：

这些文档入口无需登录；业务接口仍按本文的认证规则校验。推荐 AI 在每次开始调用接口前主动重新读取同域 /docs/api.md，以该站点当前返回的契约为准，避免长期使用对话记录或本地副本。接口变更时维护这一份 docs/API.md；线上文档随同次源码部署更新，网页和 Markdown 入口使用同一份内容。提供在线入口不代表 AI 会自动轮询，调用方应主动重新获取。

例如应用地址为 https://your-domain.example 时，AI 应先获取 https://your-domain.example/docs/api.md，再调用 https://your-domain.example/api/...。下文的 http://localhost:38810 仅为本地示例，实际调用时替换为部署地址。

概述

乾坤先机（Market Events）API 用于管理影响股市的重大事件。每个事件包含基本信息、分析和股票推荐。

设计理念： 采用两阶段API设计，将"添加事件"和"分析事件"分为两个独立的功能。

认证方式

市场事件 CRUD 和人工分析接口接受 Bearer Token、已登录的管理员 Session 或 IP 白名单。自动研究管理接口仅接受管理员 Session；任务回调使用每次尝试专用的任务 Token，不能用通用 API Token 代替。

获取 Token

在 config.ini 文件中配置：

[api]
token = your-secret-token-here

或通过环境变量设置：

export STRATEGIST_API_TOKEN="your-secret-token-here"

使用 Token

第三方调用市场事件接口时，在 HTTP 请求头中包含 Bearer Token：

Authorization: Bearer your-secret-token-here

示例

curl -X GET "http://localhost:38810/api/market-events" \
  -H "Authorization: Bearer your-secret-token-here"

IP 白名单免鉴权

在 config.ini 的 [api] 段配置 ip_whitelist，写入其中的地址调用市场事件 CRUD 和人工分析接口时 无需 Bearer Token：

[api]
ip_whitelist = 90.96.187.0/24, 10.0.0.0/8

90.96.187.0/24 表示前三段固定、最后一段任意，覆盖 90.96.187.0 到 90.96.187.255。若只需放行一个 IP，可直接写 90.96.187.244。 修改后需重启应用；若使用环境变量 STRATEGIST_API_IP_WHITELIST，应修改环境变量中的网段， 它会覆盖 config.ini 中的配置。

curl -X GET "http://localhost:38810/api/market-events"

• 支持单个 IP 与 CIDR 网段，多个条目用英文或中文逗号分隔；写错的条目会在启动时直接报错， 不会静默忽略。
• 判定地址优先取 X-Forwarded-For 最左边一段，该头不存在时回退到 TCP 对端地址。 该请求头可被客户端伪造，只有在反向代理会强制覆盖它时才是可信的。
• 白名单只覆盖市场事件 CRUD 和人工分析接口；用户管理、审计日志与自动研究管理接口始终要求登录管理员，不受白名单影响。
• 免鉴权写入的 created_by 与审计日志会记成 ip:<地址>。
• 白名单优先判定。未命中时，若提供 Bearer 请求头则先验证 Token；Token 无效时不会回退到管理员 Session。没有 Bearer 请求头时才使用管理员 Session。

认证范围

基础信息

• Base URL: http://localhost:38810/api
• 市场事件认证: Bearer Token，或浏览器管理员 Session，或 ip_whitelist 命中的来源 IP
• 数据格式: JSON
• 字符编码: UTF-8（完全支持中文）

API 端点

1. 创建事件（第一阶段）

创建事件的基本信息（日期、标题、内容）。分析和股票推荐稍后单独添加。

端点: POST /api/market-events

认证: API Bearer Token / 管理员 Session / 白名单 IP

请求示例（确切日期）:

curl -X POST "http://localhost:38810/api/market-events" \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "event_date": "2026-10-06",
    "title": "央行降息25个基点",
    "content": "中国人民银行今日宣布降息25个基点，旨在刺激经济增长。"
  }'

请求示例（连续日期）:

curl -X POST "http://localhost:38810/api/market-events" \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "event_date": "2026-10-08",
    "event_date_end": "2026-10-10",
    "date_type": "range",
    "title": "中央经济工作会议",
    "content": "为期三天的会议将讨论明年经济政策方向。"
  }'

请求示例（传言事件）:

curl -X POST "http://localhost:38810/api/market-events" \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "event_date": "2026-10-15",
    "date_type": "rumor",
    "title": "传监管层将出台新政",
    "content": "据市场传言，监管层可能在近期出台房地产调控新政策。"
  }'

请求体（确切单日事件）:

{
  "event_date": "2026-10-06",
  "title": "央行降息25个基点",
  "content": "中国人民银行今日宣布降息25个基点，旨在刺激经济增长。此次降息是今年以来第二次下调利率。"
}

请求体（连续日期事件）:

{
  "event_date": "2026-10-08",
  "event_date_end": "2026-10-10",
  "date_type": "range",
  "title": "中央经济工作会议召开",
  "content": "为期三天的中央经济工作会议于10月8日至10日在北京召开，部署2027年经济工作重点。"
}

请求体（传言事件）:

{
  "event_date": "2026-10-15",
  "date_type": "rumor",
  "title": "传监管层将出台新政",
  "content": "据市场传言，监管层可能在近期出台房地产调控新政策，具体时间未定。"
}

请求体（预估事件）:

{
  "event_date": "2026-11-01",
  "date_type": "estimated",
  "title": "预计11月公布GDP数据",
  "content": "根据惯例，国家统计局预计将在11月中旬公布第三季度GDP数据。"
}

字段说明: - event_date (string, required): 事件日期，ISO格式 (YYYY-MM-DD)，可以是未来日期 - event_date_end (string, optional): 结束日期，仅用于连续事件（date_type='range'） - date_type (string, optional): 日期类型，默认 exact - exact: 确切日期（默认） - range: 连续事件（需要 event_date_end） - rumor: 传言事件（日期为预期或传言出现时间） - estimated: 预估事件（日期为大概时间） - title (string, required): 事件标题，1-200字符 - content (string, required): 事件内容详情

注意: 创建的事件初始状态为 pending（尚无正式报告），添加分析后自动更新为 analyzed（已分析）。启用自动研究时，开始日期为今天或未来的事件会同时进入初筛队列；创建成功不代表评分或研究已经完成。

日期类型使用示例: - 确切单日: {"event_date": "2026-10-08", "date_type": "exact"} - 连续事件: {"event_date": "2026-10-08", "event_date_end": "2026-10-10", "date_type": "range"} - 传言事件: {"event_date": "2026-10-15", "date_type": "rumor"} - 预估事件: {"event_date": "2026-11-01", "date_type": "estimated"}

成功响应: 201 Created

{
  "ok": true,
  "event": {
    "id": 1,
    "event_date": "2026-10-06",
    "event_date_end": null,
    "date_type": "exact",
    "title": "央行降息25个基点",
    "content": "中国人民银行今日宣布降息25个基点...",
    "analysis": null,
    "status": "pending",
    "stocks": [],
    "created_at": "2026-10-06T13:30:00+08:00",
    "updated_at": "2026-10-06T13:30:00+08:00",
    "created_by": "api"
  }
}

连续事件响应示例:

{
  "ok": true,
  "event": {
    "id": 2,
    "event_date": "2026-10-08",
    "event_date_end": "2026-10-10",
    "date_type": "range",
    "title": "中央经济工作会议召开",
    "content": "为期三天的中央经济工作会议...",
    "analysis": null,
    "status": "pending",
    "stocks": [],
    "created_at": "2026-10-06T13:35:00+08:00",
    "updated_at": "2026-10-06T13:35:00+08:00",
    "created_by": "api"
  }
}

错误响应: - 400 Bad Request: 字段验证失败 - 401 Unauthorized: Token 无效，或没有可用的登录凭据且未命中白名单 - 403 Forbidden: Session 用户不是管理员 - 409 Conflict: 启用语义去重时检测到相似事件，code=duplicate_event - 503 Service Unavailable: 使用 Bearer 认证但服务器未配置 API Token

2. 添加分析（第二阶段）

为已创建的事件添加分析和股票推荐。这是一个独立的操作，与创建事件分离。

端点: POST /api/market-events/<event_id>/analysis

认证: API Bearer Token / 管理员 Session / 白名单 IP

请求示例:

curl -X POST "http://localhost:38810/api/market-events/1/analysis" \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "analysis": "此次降息将利好房地产和基建板块...",
    "stocks": [
      {
        "stock_symbol": "600000",
        "stock_name": "浦发银行",
        "recommendation_reason": "降息直接利好银行净息差改善"
      }
    ]
  }'

请求体:

{
  "analysis": "此次降息将利好房地产和基建板块，预计相关股票将迎来上涨机会。银行板块短期内净息差承压，但中长期有利于信贷扩张。",
  "stocks": [
    {
      "stock_symbol": "600000",
      "stock_name": "浦发银行",
      "recommendation_reason": "降息直接利好银行净息差改善，信贷扩张预期增强"
    },
    {
      "stock_symbol": "000002",
      "stock_name": "万科A",
      "recommendation_reason": "房地产龙头企业，降息降低融资成本，刺激购房需求"
    }
  ]
}

字段说明: - analysis (string, required): 事件分析文本 - stocks (array, required): 股票推荐列表，0-20个，允许空数组 - stock_symbol (string, required): 6位数字A股代码（如600000、000002） - stock_name (string, required): 股票名称，1-100字符 - recommendation_reason (string, required): 推荐原因

成功响应: 200 OK

{
  "ok": true,
  "event": {
    "id": 1,
    "event_date": "2026-10-06",
    "title": "央行降息25个基点",
    "content": "中国人民银行今日宣布降息25个基点...",
    "analysis": "此次降息将利好房地产和基建板块...",
    "stocks": [
      {
        "id": 1,
        "stock_symbol": "600000",
        "stock_name": "浦发银行",
        "recommendation_reason": "降息直接利好银行净息差改善"
      },
      {
        "id": 2,
        "stock_symbol": "000002",
        "stock_name": "万科A",
        "recommendation_reason": "房地产龙头企业，降息降低融资成本"
      }
    ],
    "created_at": "2026-10-06T13:30:00+08:00",
    "updated_at": "2026-10-06T13:35:00+08:00",
    "created_by": "admin"
  }
}

注意: - 此操作会替换事件的所有现有股票推荐 - 股票顺序按照请求中的顺序保存 - 此操作会取消该事件仍在排队或执行的自动任务，并将报告标记为人工更新；旧自动结果不能覆盖此次更新

3. 列出事件

获取所有事件列表，支持分页和搜索。

端点: GET /api/market-events

认证: API Bearer Token / 管理员 Session / 白名单 IP

请求示例:

curl -X GET "http://localhost:38810/api/market-events?status=pending&limit=10" \
  -H "Authorization: Bearer your-secret-token-here"

查询参数: - limit (integer, optional): 每页数量，1-100，默认20 - offset (integer, optional): 偏移量，默认0 - q (string, optional): 搜索关键词，在标题、内容、分析中搜索 - status (string, optional): 筛选状态，可选值: pending（待分析）或 analyzed（已分析） - date_scope (string, optional): upcoming（今天及未来，含尚未结束的连续事件）、week（含今天的7天）、month（含今天的30天）、history（已结束的历史事件）、all；默认 all - order (string, optional): date_asc（由近到远，同日按重要性排序）或 date_desc（日期倒序，兼容默认值） - outcome (string, optional): unprocessed、processing、researched、below_threshold、excluded、needs_review、failed；分别表示未开始、处理中、已出报告、未达门槛、已排除、待核实、执行失败 - min_score (integer, optional): 最低重要性分，0-100；无评分事件不满足此筛选 - screening_status (string, optional): not_screened、queued、running、scored、low_score、needs_confirmation、skipped、failed - task_status (string, optional): 当前输入版本最新任务的原始状态，queued、running、completed、needs_confirmation、skipped、failed、cancelled；retrying 是任务中心的展示状态，此参数不接受 retrying

示例请求:

# 获取所有事件
GET /api/market-events?limit=10&offset=0

# 搜索包含"降息"的事件
GET /api/market-events?q=降息

# 只获取待分析的事件
GET /api/market-events?status=pending

# 只获取已分析的事件
GET /api/market-events?status=analyzed

# 今天及未来，按最近日期升序；这是未来事件视图的推荐查询
GET /api/market-events?date_scope=upcoming&order=date_asc&limit=20&offset=0

# 含今天的未来30天内，需要核实的事件
GET /api/market-events?date_scope=month&order=date_asc&outcome=needs_review

成功响应: 200 OK

{
  "ok": true,
  "items": [
    {
      "id": 1,
      "event_date": "2026-10-06",
      "event_date_end": null,
      "date_type": "exact",
      "title": "央行降息25个基点",
      "content": "...",
      "analysis": "...",
      "status": "analyzed",
      "stocks": [],
      "display_date": "2026-10-06",
      "is_ongoing": false,
      "workflow": {
        "importance_score": null,
        "screening_status": "not_screened",
        "reason": "",
        "summary": "",
        "sources": [],
        "uncertainties": [],
        "as_of_time": null,
        "latest_task": null,
        "analysis_stale": false,
        "execution_error": "",
        "analysis_sources": [],
        "assessment": null,
        "outcome": "researched"
      },
      "created_at": "2026-10-06T13:30:00+08:00",
      "updated_at": "2026-10-06T13:35:00+08:00",
      "created_by": "admin"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0,
  "today": "2026-10-20",
  "outcome_counts": {
    "unprocessed": 0,
    "processing": 0,
    "researched": 1,
    "below_threshold": 0,
    "excluded": 0,
    "needs_review": 0,
    "failed": 0,
    "all": 1
  },
  "date_counts": {"2026-10-06": 1}
}

后台未来事件视图使用 date_scope=upcoming&order=date_asc；API 为兼容已有调用，省略参数时仍为 date_scope=all&order=date_desc。所有日期窗口以 Asia/Shanghai 的今天为准。连续事件开始日期早于今天、结束日期不早于今天时，is_ongoing=true、display_date 为今天，筛选和排序也使用该展示日期。自动研究只按开始日期判断：开始日期不早于今天可受理；已在之前开始的连续事件即使仍在进行也不受理。

total 是应用所有筛选（包括 outcome）后的事件数；items 只包含当前分页。outcome_counts 遵守日期、搜索、状态、分数等其他筛选，唯独忽略当前 outcome，包含七种结果和 all 合计。date_counts 是应用全部筛选后各 display_date 的数量。两项均在分页之前统计，同一天跨页时可显示完整数量；这里的“全局计数”不表示忽略日期或搜索条件。

事件 workflow.outcome 与结果筛选含义一致，原有 status=pending 仅表示尚无正式报告，不能用来判断任务是否执行；status=analyzed 的旧报告也可能因输入变化而过期，应同时检查 workflow.analysis_stale。字段值不合法或数值参数无法解析时返回 400，响应为 {"ok":false,"error":"..."}，此接口不保证带 code 字段。

4. 获取单个事件

获取指定事件的详细信息，包含所有股票推荐。

端点: GET /api/market-events/<event_id>

认证: API Bearer Token / 管理员 Session / 白名单 IP

请求示例:

curl -X GET "http://localhost:38810/api/market-events/1" \
  -H "Authorization: Bearer your-secret-token-here"

成功响应: 200 OK

{
  "ok": true,
  "event": {
    "id": 1,
    "event_date": "2026-10-06",
    "title": "央行降息25个基点",
    "content": "...",
    "analysis": "...",
    "stocks": [],
    "created_at": "2026-10-06T13:30:00+08:00",
    "updated_at": "2026-10-06T13:35:00+08:00",
    "created_by": "admin"
  }
}

错误响应: - 404 Not Found: 事件不存在

5. 更新事件基本信息

更新事件的基本信息（日期、标题、内容），保留已有分析和股票推荐。实际内容发生变化时会取消活动自动任务、重置评分并更新输入版本；已有报告会标记为过期，符合自动研究日期条件时重新进入初筛队列。

端点: PATCH /api/market-events/<event_id>

认证: API Bearer Token / 管理员 Session / 白名单 IP

请求示例:

curl -X PATCH "http://localhost:38810/api/market-events/1" \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "央行降息50个基点（更新）"
  }'

请求体: （只需包含要更新的字段）

{
  "title": "央行降息25个基点（更新）",
  "content": "更新后的内容..."
}

字段说明: - event_date (string, optional): 新的事件日期 - event_date_end (string, optional): 新的结束日期（仅用于 date_type='range'） - date_type (string, optional): 新的日期类型（exact/range/rumor/estimated） - title (string, optional): 新的标题 - content (string, optional): 新的内容

注意: 至少需要提供一个非 null 字段。更新后的 date_type=range 必须有有效的结束日期（可沿用已有值），且结束日期不早于开始日期。null 表示不更新；需要清空已有结束日期时可传空字符串，但仅限更新后的日期类型不是 range。

成功响应: 200 OK

{
  "ok": true,
  "event": {
    "id": 1,
    "event_date": "2026-10-06",
    "title": "央行降息25个基点（更新）",
    "content": "更新后的内容...",
    "analysis": "...",
    "stocks": [],
    "created_at": "2026-10-06T13:30:00+08:00",
    "updated_at": "2026-10-06T14:00:00+08:00",
    "created_by": "admin"
  }
}

6. 删除事件

删除事件及其所有关联的股票推荐。

端点: DELETE /api/market-events/<event_id>

认证: API Bearer Token / 管理员 Session / 白名单 IP

请求示例:

curl -X DELETE "http://localhost:38810/api/market-events/1" \
  -H "Authorization: Bearer your-secret-token-here"

成功响应: 200 OK

{
  "ok": true
}

错误响应: - 404 Not Found: 事件不存在

注意: 删除操作会同时删除所有关联的股票推荐，并取消活动自动任务；任务和运行历史仍保留，任务中心会标记事件已删除。

数据验证规则

事件字段

• event_date: 必须是有效的ISO日期格式（YYYY-MM-DD），可以是未来日期
• title: 1-200字符，不能为空
• content: 必填，不能为空
• analysis: 添加分析时必填，不能为空

股票字段

• stock_symbol: 必须是6位数字（如600000、000002、688981）
• stock_name: 1-100字符，不能为空
• recommendation_reason: 必填，不能为空
• 数量限制: 每个事件最多20只股票，允许空数组；自动深研最多5只

错误响应格式

本文业务接口可预期的 JSON 错误至少含 ok=false 和 error。其中部分验证、事件不存在和任务回调错误还含机器可读的 code，调用方应将 code 视为可选字段，并结合 HTTP 状态码处理：

{
  "ok": false,
  "error": "错误描述信息",
  "code": "error_code"
}

常见错误标识:

认证失败通常没有 code，例如 {"ok":false,"error":"not_authenticated"}。任务回调还可能返回 401/409/422，见下文的专用协议。

审计日志

所有修改操作（创建、更新、删除事件，添加分析）都会自动记录审计日志，包含： - 操作用户 - 操作类型 - 操作详情（事件ID、标题等） - IP地址 - User Agent - 时间戳

审计日志可通过 GET /api/audit-logs 查询（需要管理员权限）。

使用示例

完整工作流程

步骤1: 登录

curl -X POST http://localhost:38810/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123" \
  -c cookies.txt

步骤2: 创建事件

curl -X POST http://localhost:38810/api/market-events \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "event_date": "2026-10-06",
    "title": "央行降息25个基点",
    "content": "中国人民银行今日宣布降息25个基点，旨在刺激经济增长。"
  }'

步骤3: 添加分析和股票推荐

curl -X POST http://localhost:38810/api/market-events/1/analysis \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "analysis": "此次降息将利好房地产和基建板块。",
    "stocks": [
      {
        "stock_symbol": "600000",
        "stock_name": "浦发银行",
        "recommendation_reason": "降息直接利好银行净息差改善"
      }
    ]
  }'

步骤4: 查询所有事件

curl "http://localhost:38810/api/market-events?limit=20" -b cookies.txt

步骤5: 搜索事件

curl "http://localhost:38810/api/market-events?q=降息" -b cookies.txt

步骤6: 更新事件

curl -X PATCH http://localhost:38810/api/market-events/1 \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"title": "央行降息25个基点（已更新）"}'

技术特性

• 中文支持: 完全支持UTF-8中文文本
• 原子性操作: 股票更新在单个事务中完成，保证数据一致性
• 级联删除: 删除事件时自动删除关联的股票推荐
• 索引优化: 事件日期、创建时间、股票代码都有索引，查询效率高
• 顺序保持: 股票推荐按用户指定的顺序存储和返回

数据库架构

market_events 表

• id: 主键
• event_date: 事件日期（可为未来）
• title: 标题（1-200字符）
• content: 内容
• analysis: 分析（可为NULL）
• created_at: 创建时间
• updated_at: 更新时间
• created_by: 创建人用户名

market_event_stocks 表

• id: 主键
• event_id: 关联事件ID
• stock_symbol: 股票代码（6位数字）
• stock_name: 股票名称
• recommendation_reason: 推荐原因
• order_index: 排序索引（保持用户指定顺序）

Codex Skill 自动评分与研究

自动研究由独立 worker 调度，Skill 通过任务结果回调入库。安装说明在仓库文件 docs/EVENT_ANALYSIS.md；自动研究的结果 Schema 可直接读取 /docs/analysis-result.schema.json，内容来自仓库的 skills/moushi-event-analysis/references/output-schema.json。

管理接口

以下接口要求已登录的管理员 Session，不接受采集 Token 或 IP 白名单代替管理员身份：

管理员可在“系统配置”（/admin/settings）直接查看和修改初筛、股票分析的完整研究提示词。GET/PATCH 均返回 default_screening_prompt、default_analysis_prompt、max_prompt_length、execution_instructions、skill_instructions，分别供恢复默认及查看固定执行约束、Skill 共用规则。提示词保存在数据库，worker 每次启动任务前读取；保存后不需要重启 worker，正在执行的任务保持原配置。仅更新提示词不会重新分流、重跑或改写已有分析；历史事件需要手动重新初筛或重新研究。只有修改门槛才复用有效评分重新分流。

管理员研究提示词替代对应阶段的默认研究规范；共用规则、未来事件核验、五项评分字段和上限、最多5只股票、结果 Schema 与任务回调仍由执行器和 Skill 约束。修改需使用管理员 Session；采集 Token、任务 Token 或 IP 白名单不能修改提示词。

事件列表额外支持 min_score（0—100）、screening_status、task_status；与原有筛选共同作用于分页和 total。 事件列表和详情增加 workflow，包含 importance_score、screening_status、reason、summary、 sources、uncertainties、as_of_time、latest_task、analysis_stale、outcome、execution_error，以及当前自动报告的 analysis_sources / assessment。创建接口的即时响应不含 workflow；需要完整任务状态时再查询列表或详情。

当前自动深研报告的 stocks[] 还返回逐股说明，列表与详情保持一致：

详细说明从当前已发布且输入版本一致的研究记录恢复，不新增数据库列；已有完整自动结果无需重跑即可返回。较新但尚未发布的结果不会替换当前依据。输入变化或人工更新分析后，不把旧自动报告的业务证据拼到新内容上；既有手工接口仍接收原来的三个股票字段，手工记录至少直接展示其 recommendation_reason，缺失详情时不编造说明。

初筛状态包括 not_screened、queued、running、scored、low_score、needs_confirmation、skipped、failed； 任务状态包括 queued、running、completed、needs_confirmation、skipped、failed、cancelled。 事件原有 pending/analyzed 状态保持兼容。低分属于正常初筛完成，待确认没有评分。

重要性分衡量未来预期催化与风险研究价值，重大利空也可高分，未揭晓结果不是证据不足。五项字段、权重和60分门槛不变。深研报告可以包含受压行业和双向影响，但 stocks 仍只列潜在受益股、允许为空；分数不因没有受益股而机械降低。现有字符串字段承载影响性质，不新增JSON字段；历史结果保持原样。

任务中心用 display_status 表示面向用户的执行状态：queued/running/retrying/completed/needs_confirmation/skipped/failed/cancelled；GET /api/analysis-tasks 的 status 参数也按这些展示状态筛选。自动重试期间显示 retrying，重试耗尽显示 failed，业务证据不足显示 needs_confirmation；兼容识别旧记录中以 needs_confirmation 保存的技术失败。原始 status 保留。任务包含入队、开始、结束、更新时间和 next_retry_at，以及 attempts/error/execution_error、最近一次尝试耗时 duration_seconds、result_summary/result_reason/importance_score。任务列表额外返回 event_title/event_date/event_deleted/can_retry。

任务列表的 total 遵守当前筛选，counts 则始终按全库任务统计、不受 q/status/stage 或分页影响，包含各展示状态及 total。事件列表的 outcome_counts 按事件统计，口径见“列出事件”，两者不能互相替代。

workflow.reason 保留初筛业务理由，workflow.execution_error 单独说明执行异常。GET /api/analysis-status 返回 enabled/worker/counts/last_completed_at/recent_completed；recent_completed 是最近五条终态任务，可能包括待确认、跳过、失败和取消。worker.status 为 online/paused/offline/unknown：未收到执行服务心跳时显示未知，心跳超过 max(120秒, 3×轮询间隔) 显示离线；关闭自动分析时显示暂停。worker 同时含 heartbeat_at/reason/current_task_id。Web 的 /healthz 不代表后台执行服务在线。

任务结果回调

提交前读取当前站点的结果 JSON Schema，该 Schema 约束下列请求体中的 result 对象。

POST /api/analysis-tasks/<task_id>/result 使用该次尝试专用的 Authorization: Bearer <task-token>。 请求体为 {"attempt_id":"32位十六进制标识","result":{...}}。Cookie、采集 Token 和 IP 白名单均不能代替任务凭据。

result.stage 为 screen 或 analyze；outcome 为 completed、needs_confirmation、skipped 或 failed。 初筛分项上限依次为25/20/20/20/15，服务端求和后按门槛创建深研任务；深研允许0—5只股票。 完成结果必须带来源，event_status=upcoming，verification_status 为 confirmed 或 partially_confirmed；已开始的事件不能作为完成结果提交。服务端日期资格检查按开始日期不早于 Asia/Shanghai 的今天执行，研究端仍须核实事件实际状态。缺证据不以低分提交。

as_of_time 必须是带时区的 RFC3339 时间，不得超前服务器时间超过300秒，也不得早于本次尝试开始时间60秒以上。来源 URL 仅接受不含用户名或密码的 HTTP(S) 地址。

成功返回 {"ok":true,"task":{...},"run_id":1,"importance_score":60}。 同次尝试重复提交相同内容返回原确认；不同内容或旧任务返回409，格式错误返回422，凭据无效返回401。 历史、当前分析与任务终态原子提交，CLI正常退出不能代替回调成功。

公开只读自检 GET /healthz 返回 {"ok":true,"service":"strategist"}。

版本历史

• v1.1 (2026-10-18): 新增联网初筛、60分门槛、Skill API回写、独立worker、管理任务与运行历史；人工分析允许空股票数组。

• v1.0 (2026-10-06): 初始版本

• 实现两阶段API设计（创建事件 + 添加分析）
• 支持完整的CRUD操作
• 中文文本完全支持
• A股代码验证
• 审计日志记录

联系方式

如有问题或建议，请联系开发团队。