API 参考 / research

调整采集能力运行配置（平台超管）

PATCH /api/v1/research/capabilities · updateResearchCapability

运行时调整 enabled、schedule、freshness、cohort、限流与 parser/policy 版本。恢复 unauthorized、policy_blocked、quarantined 或 failed 必须提供 reviewReason，写入审计； 不接受明文密钥。unsupported 能力不可启用。首次从 disabled 或阻断态启用时只进入 canaryOnly；canary 成功后才允许常规调度，失败则按能力状态机停采。

本接口要求浏览器会话。Bearer API Token 无法调用——Token 的生命周期管理必须在网页端完成。

请求体

capabilityId（必填）
string —— 要更新的 Capability Registry ID。
expectedVersion（必填）
integer —— 必须等于最近一次读取到的 Capability version；冲突返回 409。
enabled
boolean
schedule
string
freshnessSloMinutes
integer
cohort
string[]
rateLimitPerMinute
integer
parserVersion
string
policyVersion
string
reviewReason
string —— 恢复被阻断或隔离能力时必填，进入审计
complianceReviewerId
string —— 恢复被阻断或隔离能力时必填；必须是 active 平台超管，并作为独立字段进入审计。

响应字段 · 200

id（必填）
string
source（必填）
string —— 来源注册名，如 steam / taptap / apple / wechat_competitor
platform（必填）
enum；取值：steam / taptap / apple / wechat_minigame
capability（必填）
string —— 能力名，如 ccu / game_detail / reviews / ranking / rss_feed
metricKey（必填）
string —— 该能力产出的稳定指标 key
evidenceKind（必填）
enum —— metric 是结构化观测值；claim 是带出处的内容主张。本期 Claim 只锁合同，不接采集源。；取值：metric / claim
metricClass（必填）
enum —— Qualifier 决定的指标类别。旧 estimated=true 迁移为 estimate；旧 estimated=false 一律为 legacy_unclassified，禁止猜成 fact，且不可进入 V2 快照。；取值：fact / signal / estimate / legacy_unclassified
contractVersion（必填）
string —— 来源响应合同 / fingerprint 的版本
status（必填）
enum；取值：active / disabled / requires_authorization / unauthorized / policy_blocked / quarantined / rate_limited / failed / unsupported
enabled（必填）
boolean
dataScope（必填）
enum —— 数据作用域。V1 全局市场快照只允许 public_market。；取值：public_market / tenant_first_party
truthTier（必填）
enum —— 来源真值等级；等级定义由版本化 qualifier policy 管理。；取值：T0 / T1 / T2 / T3 / T4 / T5
schedule（必填）
string —— 持久化调度表达式；空调度的能力不会运行
freshnessSloMinutes（必填）
integer
cohort
string[]
rateLimitPerMinute
integer
parserVersion（必填）
string
policyVersion（必填）
string
secretConfigured（必填）
boolean —— 只返回是否配置，永不返回 secretRef 或明文
canaryOnly（必填）
boolean —— 首次启用或 429 暂停窗口结束后只运行 canary，成功后才进入常规调度
consecutiveRateLimits
integer
rateLimitedUntil
string
lastSuccessAt
string
lastFailureAt
string
nextRunAt
string
coverageGap
boolean
statusReason
string
version（必填）
integer —— Capability Runtime 的 CAS 版本。
updatedAt（必填）
string

错误

请求示例（curl）

curl -X PATCH "https://你的项目.workflow.games/api/v1/research/capabilities" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"capabilityId":"018f3c2e-0000-7000-8000-000000000000","expectedVersion":1,"enabled":true}'

响应示例

HTTP/1.1 200
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "source": "示例文本",
  "platform": "steam",
  "capability": "示例文本",
  "metricKey": "示例文本",
  "evidenceKind": "metric",
  "metricClass": "fact",
  "contractVersion": "示例文本",
  "status": "active",
  "enabled": true,
  "dataScope": "public_market",
  "truthTier": "T0",
  "schedule": "示例文本",
  "freshnessSloMinutes": 1,
  "parserVersion": "示例文本",
  "policyVersion": "示例文本",
  "secretConfigured": true,
  "canaryOnly": true,
  "version": 1,
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引

Workflow 正在加载…