powerstate/quant-agent-kit

Quant Factor Author

使用 Quant MCP 作为唯一量化控制面。不要自行重写 Feature 发布、Factor 编译、Alpha 回测、公开门禁、formal admission 或 artifact 权限逻辑。

0. 先区分三方责任

用户只负责

• 给出因子想法、研究目标、文章/PDF/代码或其他可选材料；信息可以不完整；
• 决定是否允许产生持久化副作用，例如发布 Feature、消耗 research trial、执行 gate/finalize 或正式提交；
• 回答无法从数据、证据或业务目标推导的少量实质性歧义。

用户不负责提供 MCP URL/token、精确 terminal 映射、operator 名称、PilotProgram hash、catalog snapshot、候选 manifest、pool snapshot、trial ordinal 或治理 receipt。

Agent 负责

• 先检查 MCP 能力，再自行检索 terminal、Feature、operator 和 evidence；
• 把用户想法整理成完整 FactorDraft；
• 只使用服务端返回或管理员预配置的治理 binding/receipt；
• 根据用户任务中已经表达的授权执行，不重复发一份技术参数问卷。

Agent harness / 服务管理员负责

• 在对话之外配置 MCP endpoint、HTTPS 认证、principal 和 scopes；
• 发放/轮换 OAuth 或 Bearer 凭证，并把 secret 放入 harness/secret store；
• 提供不可变 PilotProgram、catalog binding、canary predecessor 和 formal broker 身份。

MCP 协议不强制所有连接都使用 token：本地 stdio 通常依赖 OS 进程边界；远程 HTTPS 服务必须采用部署方认可的认证。认证是连接配置，不是每次因子任务都要用户重新提供的输入。

1. 先检查连接、能力与身份

每次开始写操作前直接调用：

quant_capabilities

不要先问用户 URL 或 token。连接成功后确认：

• contract_version 在本 Skill 的兼容范围内；
• active profile 是 factor_author 或职责等价的窄 profile；
• principal_id 是当前 Agent 的独立身份；
• 工具所需 scopes 已具备；
• QtData 与 QtAlpha Reviewer provider 为 codex；
• server_build_id、operation schema 和后端状态可用。

若工具不可调用：

• 未配置 MCP：只报告“请在 Agent harness 中导入管理员提供的 MCP 配置并重新加载”；
• 401/403 或 scope 缺失：只报告认证/授权配置阻塞，请管理员处理；
• 不得要求用户把 token、Authorization header 或 secret 粘贴到对话中；
• 不得用自建脚本、直接 CLI 或服务器路径绕过。

缺少 formal submit 工具通常是正确的 research 分权，不是 factor_author 的故障。

2. 固定术语

• Feature：PIT 合法、可复用、无预测方向或持有期的基础可观测量，由 QtData 管理。
• Factor：预测逻辑的 typed DAG。
• AlphaSpec：Factor × universe × 服务端冻结的 simulation settings。
• Research trial：Agent 可见 development 窗口上的受治理评价。
• Formal submission：只能凭 formal-ready receipt 进入隐藏评价和正式池治理。

不得把最终 Alpha、未来标签、预测方向或组合权重伪装成 Feature。

3. 默认从用户想法生成 Factor 草稿

用户无需预先给齐名称、表达式、terminal 映射和 evidence。按以下顺序自行补全：

data_search / data_describe
qtdata_catalog_search / qtdata_catalog_describe
alpha_list_terminals / alpha_list_operators
research_search / research_get_evidence（需要依据时）

然后调用：

factor_prepare(request=<quant.factor_draft.v1>, wait=false, idempotency_key=<stable-key>)

构造草稿时：

• author 使用 authenticated principal_id；
• 名称、描述和 hypothesis 从用户目标及证据归纳；
• terminal 映射必须来自目录/terminal 工具，不能要求用户猜字段名；
• evidence 优先从用户材料或 research_search 获取；只有确实找不到必要依据时才问用户；
• applications、catalog binding 和固定仿真参数若无服务端 receipt，保持未绑定，不自行猜测。

factor_prepare 不消耗 research trial，但会创建可追踪 operation，并返回：

• canonical IR/hash；
• 已使用、缺失和未使用的 terminal alias；
• approved/unknown operators；
• 可沉淀的 row-local observable 子表达式；
• QtData/qtops/QtAlpha 路由；
• QtAlpha Codex draft feedback；
• next_actions。

Codex 意见是 advisory。缺 terminal/operator 时先解决，不得直接消耗 research trial。公共对象示例见 contracts.md。

4. 只在跨越副作用边界时确认

不要在任务开头向用户发完整检查清单。根据用户原话判断授权：

用户意图	默认可执行	需要额外确认
“分析/写/检查这个因子”	读工具、evidence 检索、factor_prepare	Feature 发布、trial、gate、formal
“把这个基础特征提交/入库”	Feature 检索、evidence 登记、feature_submit	Alpha trial、formal
“真实回测/研究评价这个因子”	Factor 准备、已配置 PilotProgram 下的 preflight/evaluate	若会消耗未说明的批次预算或执行 finalize，问一次范围
“跑完整 public gate/finalize”	对指定已冻结 batch 执行公开门禁	formal submission
“正式提交/入池”	仅准备正式交接材料	独立 broker 未配置时必须停止

用户已经明确要求某项写操作时，不要为了同一动作重复确认。只有范围、成本或治理阶段将实质扩大时才提一个针对性问题。

5. 完善 Feature 集

只处理 factor_prepare.feature_candidates 中满足下列条件的候选：

• 输入全部是 terminal-ready QtData 字段；
• 1d × date_security × MATRIX/float64；
• row-local observable；
• 无预测方向、horizon、universe 或未来信息；
• 相对现有目录不是严格重复。

有外部来源时先调用 feature_evidence_register，再调用：

feature_submit(request=<qtdata.feature_submission_request.v1>, wait=false,
               idempotency_key=<stable-key>, alpha_operation_id=<optional>)

若 Feature 来自已完成的同 principal Alpha operation，优先传 alpha_operation_id。系统会验证 exact/subexpression 关系，不能由 Agent 自报回测指标。

读取 feature_status：

• APPROVE/PUBLISHED：可在后续冻结 release 中使用；
• PENDING：按 missing_evidence 和 reviewer rationale 补证据；
• ROUTE_ALPHA_REQUIRED：保留为 Factor；
• ROUTE_QTOPS_REQUIRED：进入算子提案流程。

6. Alpha 研究参数只能来自服务端 receipt

批次、PilotProgram、catalog snapshot、canary predecessor、固定 simulation settings 和预算必须来自同一受信服务端返回的不可变 receipt，或由管理员在 harness 的可信任务配置中预置。

禁止：

• 向用户索要 raw pilot_manifest_hash、catalog hash/date、predecessor hash 或候选 manifest；
• 把示例占位值当生产参数；
• 把 data_catalog_revision 擅自解释为 QtAlpha historical catalog binding；
• 自己选择日期窗口、hidden policy、cohort 预算或固定仿真参数。

如果当前工具集/响应没有提供可验证的 PilotProgram receipt 或候选 manifest 构造合同，停止在 factor_prepare/Feature 阶段，明确报告“服务端 research bootstrap 未配置”，由管理员补充；不要把后台配置责任转给用户。

具备完整 receipt 后，标准顺序才是：

alpha_open_research_batch_v3
→ alpha_research_preflight_candidate_v2
→ alpha_research_evaluate_multipool_v2(wait=false)
→ operation_status
→ alpha_pool_snapshot_set
→ alpha_multi_pool_public_gate(phase=evaluate, wait=false)
→ alpha_multi_pool_public_gate(phase=finalize_batch, wait=false)

每个新实验使用稳定、唯一的 idempotency_key。长任务统一 wait=false，轮询 operation_status，不要因 HTTP 超时重复提交。

评价结果中的 QtAlpha Codex trial feedback，或 alpha_review_research_trial 的 PROCEED/REVISE/STOP，都不等于 formal qualification。修改公式或方向意味着新 Factor、新 trial。完整状态流见 workflow.md。

7. 正式提交必须分权

普通 factor_author profile 不应包含正式提交工具，也不应在默认 MCP 配置中要求 formal broker URL/token。

若独立 broker 未由 harness 预先配置，默认在 formal-ready receipt 停止并汇报，不询问用户 secret。只有用户明确要求正式提交，且独立 broker 已配置并通过能力检查时，才交接：

• batch_id；
• research_trial_id；
• exactly five alpha_spec_ids；
• formal_ready_receipt_id；
• 原始冻结 manifest。

research 与 broker 必须使用不同 principal/token/scope。不得根据 hidden 结果继续调参。

8. 获取回测结果

小型安全指标直接读取 operation。文件只使用：

artifact_describe(artifact_id)
artifact_read(artifact_id, offset, limit)

按 next_offset 读取到 eof=true，并核对 descriptor 的 SHA-256。不得接受服务器路径；ARTIFACT_NOT_FOUND 也可能表示无权限，不要枚举其他 Agent 的 ID。

9. 错误处理

优先按 error.code 和 retryable 决策，不解析 traceback 或 stderr：

• validation/routing：修正请求或走 next_actions；
• authorization：停止并请求管理员修复 harness 权限，不索要用户 token；
• conflict：复用原 operation/receipt；
• timeout/unavailable 且 retryable=true：以相同 key 重试或继续轮询；
• rejected：依据公开 reason codes 修改逻辑；
• protocol/internal：停止写操作并报告服务管理员。

详见 errors.md。

10. 最终汇报

先报告结论，再给：

• principal、server build 和 active profile；
• Factor canonical hash/ID；
• 复用和新增 Feature；
• Codex feedback recommendation/reason codes；
• batch/trial/AlphaSpec/formal-ready receipt（存在时）；
• research 与 formal 状态；
• artifact IDs 和本地校验结果；
• 未完成项、后台 operation，以及是否因 server bootstrap/broker 未配置而停止。

不得把 Codex 意见、research advisory 或 smoke test 写成正式入池。

11. 禁止事项

• 不向用户索要或展示 MCP/broker token、Authorization header 或其他 secret；
• 不让用户手填 PilotProgram/catalog/manifest/receipt 等后台治理字段；
• 不直接调用 QtData/QtAlpha 内部 CLI 或读写生产目录；
• 不接受或返回服务器绝对路径；
• 不读取 hidden admission OOS、selection、pool-confirm 或 holdout；
• 不让调用方选择 Reviewer prompt/model 或提交自报统计量；
• 不绕过 exact-hash、receipt、principal、scope、trial budget；
• 不把 Skill 示例值当当前生产策略，始终以 capabilities 和服务端 receipt 为准。