观潮家 Theme 生成

这是观潮家 AI 分析师的 Codex 项目空间。项目只消费 Tidewise 的正式投研事实，执行四层 推理，并生成 Research Theme 与 Reason Tree。

目标职责边界：Event Semantic 到 accepted Entity Link 与 Event-native Variable Signal 为止；Theme Analyst 在 L2 结合正式实体、变量定义和图谱关系生成 Analysis Direct Impact， 再执行整体传导与结论推理。

入口：$generate-research-themes

当前状态：

• 已接入 Data Service 修正后的 research-analysis-context.v1 页级闭包实时分页查询；
• 已实现本地/远端不一致后的单次整轮重查、共享总超时、429 失败关闭，以及 Codex 显式 Research Graph Search 查询计划；
• 已冻结新的 Analysis Direct Impact 职责；investment-analysis-v1 Schema/Validator 已增加本地分析血缘，并已适配 Data Service 的任一关系存储方向与连续多跳 analyst_inference 发布合同；
• 已增加 theme-analyst-analysis-plan-v2：在保持 V1 四层推理不变的前提下，要求 Codex 在产品投影前按 theme-formation-policy-v1 保存 Theme 合并/拆分决策；Runner 负责补齐 运行身份，Validator 负责 Formation 引用、Signal、Variable、Entity、Graph Edge、 Evidence 和路径连续性；历史 V1 Plan 继续可读；
• 真实 codex_four_layer 不再调用模拟构建器；校验通过且状态为 publishable 时支持 prepare-only 与用户明确授权的 publish；
• 已实现的 formal-path 四层基线、零/多 Theme、冲突降级和多产业链拆树仍使用遗留 DirectImpact 输入，只作为工程基线；
• 已将节点变量方向与投资判断分离，节点投资判断统一为机会、风险或不确定；
• 已实现 Theme 关注节点与 Reason Tree 节点判断一致性校验，Theme 不复制节点 Signal；
• 已实现 Context-aware 强血缘校验；
• 已实现发布请求准备、原子发布、幂等重放和发布后回读；
• 已接入 Data Service V3 analyst_snapshot Provider：Codex 完成四层推理和展示准备后， 可以发布不依赖 formal Entity、VariableSignal、IndustryChain 或 Graph ID 的不可变报告 快照；正式 Event 必填、Evidence 可选，V2 formal 路径保持不变；
• analyst_snapshot 发布前强制使用 theme-analyst-snapshot-quality-v2：冻结当前 TBox 与 Event Semantic 优先使用身份，产业链经济节点与 KPI/ 财务结果/研究结论分离，Investment Target 与价值机制必填，探索/监测候选、 候选替换和未通过独立语义复核的结果在 HTTP 前失败关闭；
• 已冻结专业投研分析师身份和金融/中国股票市场行业专家表达方式： generate-research-themes 为主方法，serenity-skill 只在 L3/L4 补充产业链卡点、 稀缺性、扩产难度、价值捕获、证据分级和反方检验；Prompt V3、Narrative 身份和 Snapshot Quality 方法身份共同保证新发布运行使用该配置；
• 已成功跑通首个模拟 Theme + Reason Tree；
• 尚未完成面向真实 Event 的独立模型服务反方复核；当前 Runner 要求计划内结构化反方 复核通过后才能发布。

中间合同：

• docs/architecture/investment-analysis-contract-v1.md
• docs/architecture/theme-analyst-analysis-plan-v2.md
• schemas/investment-analysis-v1.schema.json
• schemas/theme-analyst-analysis-plan-v2.schema.json
• docs/architecture/theme-analyst-professional-investment-voice-v1.md
• prompts/theme-analyst-investment-semantic-v3.md

模拟验收入口：

DATA_SERVICE_TOKEN=<local service token> \
python3 -m theme_analysis.cli \
  --mode prepare-only \
  --base-url http://127.0.0.1:9011 \
  --run-id <unique-run-id> \
  --discovery-window-start <RFC3339> \
  --discovery-window-end <RFC3339> \
  --analysis-as-of <RFC3339> \
  --graph-query-file <codex-selected-graph-queries.json>

运行包保存在 runs/<run_id>/。input.json 是实时响应的本地审计副本，不是系统快照。 图查询文件是 JSON object 数组；每项必须由 Codex 显式给出 seed、relation、direction、 depth、可选产业链 scope 和预算，Data Service 不替分析师选择研究范围。 CLI 已开放 publish，但只有本地校验通过、状态为 publishable、NarrativePlan 与反方 复核全部通过的结果才会调用 Data Service。正式 Relation/Graph Edge 可按任一存储方向 连接相邻节点；连续 Analysis Inference Step 必须共享同一 accepted 根 Signal，并为每跳 保留实际相邻关系血缘。非相邻关系仍会在 HTTP 前失败关闭。

真实分析在 Codex 完成 Graph 查询和结构化计划后运行：

DATA_SERVICE_TOKEN=<local service token> \
python3 -m theme_analysis.cli \
  --mode prepare-only \
  --data-nature real \
  --base-url http://127.0.0.1:9011 \
  --run-id <unique-run-id> \
  --discovery-window-start <RFC3339> \
  --discovery-window-end <RFC3339> \
  --analysis-as-of <RFC3339> \
  --graph-query-file <codex-selected-graph-queries.json> \
  --analysis-plan-file <codex-analysis-plan.json>

分析师拥有的临时对象、变量和传导路径使用 V3 snapshot Provider。Codex 必须先完成四层推理、 反方复核、Theme Formation 和 Miniapp 展示字段准备，再生成 canonical request；程序不会从 旧分析结果自动补写研究语义：

DATA_SERVICE_TOKEN=<service token> \
python3 -m theme_analysis.cli \
  --mode prepare-only \
  --publication-mode analyst_snapshot \
  --base-url <data-service-base-url> \
  --run-id <must-equal-analysis-batch-id> \
  --snapshot-request-file <canonical-analyst-snapshot-request.json> \
  --snapshot-quality-file <theme-analyst-snapshot-quality-v2.json>

用户明确授权发布后，把 --mode prepare-only 改为 --mode publish。运行包保存 canonical request、quality evidence、receipt 与完整 Theme/全部 Reason Tree readback；相同结果未知时只重放同一请求， 不得重新推理或修改 payload 规避幂等冲突。