feature/20260717/refactor local research three layer architecture

.agents/skills/run-local-quant-research/SKILL.md

@@ -5,32 +5,38 @@ description: Use when 用户或 Agent 需要基于仓库项目配置与共享行
 
 # 本地量化研究流程
 
-只编排一次通用本地研究调用。共享脚本负责校验配置、行情身份、单场景结果和摘要；Skill（技能）不解释策略字段，不复制项目逻辑，不读取复数分析计划。
+只编排一次通用本地研究调用。共享脚本负责校验配置、行情身份、单场景结果和摘要；Skill（技能）不解释策略字段，不复制项目逻辑，不读取复数分析计划。输出固定为唯一 archive-ready（可归档）结果包，不由配置声明，无需二次重算或改写。
 
 ## 执行前提
 
 - 从仓库根目录运行项目 `.venv`（虚拟环境），不回退系统 Python（编程语言），不静默安装依赖。
-- 配置必须声明项目入口、共享 `snapshot_id`（快照标识）、一个场景、仓库内路径和一份必需结果。
+- 配置必须声明共享 `snapshot_id`（快照标识）、一个场景和仓库内路径。
 - 配置或快照缺失时停止，不猜测路径、不改用旧快照、不缩减资产范围。
 
 ## 固定流程
 
 1. 校验行情快照：只读取配置声明的 `snapshot_id`，验证共享行情中心的 `market-data.parquet`、来源、范围、字段、价格口径和内容摘要；查询只使用内存 DuckDB（嵌入式分析数据库），不创建持久数据库。
-2. 校验单场景配置：拒绝候选数组、场景数组、分析计划和流程内循环，只接受一个项目场景及其必需输出声明。
-3. 运行项目入口：由通用 CLI（命令行接口）调用配置声明的项目进程；项目自行解释策略参数，并在同一全新进程内分别完成一次冷启动和一次预热执行。
+2. 校验单场景配置：拒绝候选数组、场景数组、分析计划和流程内循环，只接受一个项目场景。
+3. 运行共享场景：由通用 CLI（命令行接口）生成私有子进程协议；共享运行时在同一全新进程内分别完成一次冷启动和一次预热执行。
 4. 校验单场景结果：重新读取唯一结果目录，核对状态、运行身份、输入摘要、性能证据、临时产物清理和输出摘要。
 5. 固化运行证据：通过后原子写入不可变清单；相同输入和相同输出复用既有运行，摘要冲突则失败。
-6. 返回调用者：完整运行固定输出 `next_action=return_to_caller`。复数场景由主 agent（代理）多次调用本 Skill，不在 Skill 内聚合、分析、报告或推荐。
+6. 可选晋升：公开 `promote` 只把完整结果包逐字节复制到 `joinquant/strategies/<strategy_id>/research/archives/<analysis_id>/`；它不重算结果，也不写入聚宽正式 `backtests/` 或 `simulations/`。
+7. 返回调用者：完整运行固定输出 `next_action=return_to_caller`。复数场景由主 agent（代理）多次调用本 Skill，不在 Skill 内聚合、分析、报告或推荐。结果包内报告只复述可复核的机械执行事实，不承担策略分析、推荐或人工批准。
 
 统一公开命令：
 
 ```powershell
 .\.venv\Scripts\python.exe scripts\research\local_quant_research\cli.py run --config <path>
+
+.\.venv\Scripts\python.exe scripts\research\local_quant_research\cli.py promote `
+  --strategy-id <strategy_id> `
+  --run-id <run_id> `
+  --analysis-id <analysis_id>
 ```
 
 ## 结果判断
 
-- `complete`（完整）：配置、快照、项目进程、单场景性能门禁、唯一必需结果和证据摘要全部通过，然后返回调用者。
+- `complete`（完整）：配置、快照、项目进程、单场景性能门禁、固定结果包和证据摘要全部通过，然后返回调用者。
 - `evidence_insufficient`（证据不足）：执行前缺少身份、快照、范围或声明输入，包括缺失单场景配置。
 - `failed`（失败）：既有证据被篡改或摘要不一致，或执行、输出、180 秒门槛、确定性、清理、原子固化任一环节失败。
 

.agents/skills/run-local-quant-research/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "本地量化研究流程"
-  short_description: "编排通用本地量化研究流程并固化可复算证据与三态结论"
-  default_prompt: "使用 $run-local-quant-research 执行项目配置指定的本地量化研究并核验完整证据。"
+  short_description: "执行单场景本地量化研究并生成可归档证据包与三态结论"
+  default_prompt: "使用 $run-local-quant-research 执行配置指定的单场景本地量化研究并核验可归档证据包。"

.build-and-verify/config.json

@@ -297,8 +297,10 @@
           "-m",
           "pytest",
           "tests\\local_quant_research",
-          "-k",
-          "not test_non_strategy_project_completes_through_shared_market_and_runner"
+          "tests\\quant_analysis",
+          "--ignore=tests\\local_quant_research\\test_generic_e2e.py",
+          "--ignore=tests\\local_quant_research\\test_turtle_e2e.py",
+          "--ignore=tests\\local_quant_research\\test_local_research_v2_e2e.py"
         ],
         "paths": [
           ".agents/skills/run-local-quant-research/**",
@@ -328,7 +330,8 @@
           "requirements-dev.txt"
         ],
         "checkParallel": true,
-        "pytestXdistWorkers": 4
+        "pytestXdistWorkers": 4,
+        "timeoutSeconds": 300
       },
       {
         "id": "verify.local-quant-research-e2e",
@@ -337,7 +340,8 @@
           "-m",
           "pytest",
           "tests\\local_quant_research\\test_generic_e2e.py",
-          "tests\\local_quant_research\\test_turtle_e2e.py"
+          "tests\\local_quant_research\\test_turtle_e2e.py",
+          "tests\\local_quant_research\\test_local_research_v2_e2e.py"
         ],
         "paths": [
           ".agents/skills/run-local-quant-research/**",