omni-orchestrator

name	omni-orchestrator
description	Nexus 统一入口。意图识别 + 模式路由 + 首次引导 + Autopilot 模式。当用户提出任何学术研究相关请求时触发（调研、找论文、构思 idea、写论文、审稿、做实验等）。

omni-orchestrator

Nexus 的总调度 Skill。负责意图识别、模式路由、首次使用引导和 Autopilot 模式管理。

Step 0 — 平台检测（T9，新会话首次进入时执行一次）

NeXus 只支持两个 harness：Claude Code 和 Codex。它们能力对等 （MCP / subagent / hooks / 项目记忆），但 hook 配置文件路径、slash command 命名、 平台独有 env var 有差异。会话开始时先确定当前 harness，把检测结果写到 project_state.platform_profile，让下游技能选对配置。

自动检测路径

1. 调用 pipeline-orchestrator.advance_pipeline() 时，若 project_state.json 首次 创建（不存在），server 内部会自动调 platform_detection.detect_platform_profile()， 把结果写进 platform_profile 字段。LLM 不需要手动做这一步。
2. 检测优先级：
   • env vars：CLAUDECODE / CLAUDE_PROJECT_DIR → Claude Code； CODEX_HOME / OPENAI_CODEX_HOME → Codex。
   • home 目录：~/.claude/ 单独存在 → Claude Code；~/.codex/ 单独存在 → Codex。
   • 两个 env 家族都设了、或两个 home 目录都存在 → raise PlatformDetectionError， 要求用户设 NEXUS_PLATFORM_PROFILE=claude_code 或 NEXUS_PLATFORM_PROFILE=codex 明确指定。
3. 用户也可在 project_state.json 里显式覆盖 platform_profile，自动检测不会覆盖 已有值——尊重用户配置优先级最高。

检测后该做什么

• Claude Code 用户：hooks 走 nexus_hooks/rendered/claude_code/.claude/settings.json； agent 项目记忆读 CLAUDE.md；并行分发用原生 Task tool；SDP 切换时打开 Codex 插件调 GPT 5.4。
• Codex 用户：hooks 走 nexus_hooks/rendered/codex/.codex/config.yaml； 项目记忆读 AGENTS.md（或 .codex/AGENTS.md，是根 AGENTS.md 的代理）； 并行分发用 Codex 原生 task dispatch；SDP 切换时打开 Claude Code 调 Opus / Sonnet。

跨平台契约（包括 AssuranceContract JSON、nexus_hooks/ hook 规范源、所有 MCP 工具） 对两个 harness 完全一致——任何技能跑到 complete_stage() 时吐的契约 不依赖平台，下游消费方读 JSON 即可。

首次使用引导

检查 ~/.nexus/global_config.json 是否存在：

• 不存在 → 触发引导流程（见下方）
• 存在 → 直接进入意图识别

引导流程

🔬 Nexus — 首次配置

欢迎！我需要做一次简单配置（1 分钟，仅此一次）。

❶ [必填] 请提供一个邮箱（用于学术 API 访问，不会收到任何邮件）：

❷ [可选] 远程 GPU 服务器：
   — AutoDL 用户：粘贴 SSH 登录指令即可
   — 自建服务器：提供 host + user，需已配置 SSH key 免密登录

❸ [可选] 模型偏好配置（参见 rules/model-routing.md）：
   — 不同阶段使用不同模型可提升质量
   — 默认推荐：Idea→Gemini, 架构→Opus, Debug→Codex, 起草→双模型, 润色→GPT
   — 可自定义，也可稍后在 global_config.json 中修改

❹ [可选] 论文写作环境：
   — 如已有 Overleaf 账号，推荐安装 Overleaf Workshop 插件
   — 详见 paper-writing/overleaf_setup.md

✅ 配置完成后展示所有服务状态。

💡 [可选] Semantic Scholar API Key 申请链接。

将配置写入 ~/.nexus/global_config.json。

意图识别 + 路由

用户意图关键词	路由到	模式
调研、综述、找论文、search、survey	literature-survey	Survey
idea、想法、brainstorm、研究方向	idea-brainstorm	Ideate
精读、细读、分析这篇论文、deep dive	deep-dive	Deep Dive
读论文、解析 PDF、arxiv 链接、DOI	paper-ingestion	工具
检查证据质量、audit evidence	evidence-auditor	工具
写论文、draft、write、paper	paper-writing	Write
做实验、跑代码、build、experiment	experiment-runner	Build
审稿、review、打分、评估论文质量	multi-reviewer	Review
修改论文、revise、被拒、resubmit、优化论文、草稿升级	revise-paper workflow	Revise
做PPT、做汇报、academic slides	提示使用 frontend-slides skill	工具
总结经验、保存规则、evolution memory	evolution-memory	管理
追踪、monitor、跟进、新论文	(Phase 3+)	Monitor
验证引用、check citation	citation-verifier	工具
查看配置/状态	展示当前配置和项目状态	管理
自动完成、全自动、autopilot、auto、vibe research、帮我搞定剩下的	设置 autopilot=true，继续当前 pipeline	Autopilot
暂停、停、我来看看、manual	设置 autopilot=false，恢复手动控制	Manual

MCP Pipeline 强制规则

在 pipeline 模式下（project_state.json 存在时）：

1. 每次对话开始时必须先调用 pipeline-orchestrator.advance_pipeline() 获取当前阶段指令
2. 不要自行判断当前应该执行哪个 skill — 以 MCP tool 返回值为准
3. 每个 stage 完成后必须调用 pipeline-orchestrator.complete_stage() 验证并推进
4. 如果返回值中 parallel=true，在单条消息中通过平台的并行 Task 工具一次性 dispatch 整份 subagent_tasks 列表——不要迭代发送（参考 dispatching-parallel-agents skill）。这是 T10：消除串行 dispatch 的隐性开销。每个 subagent 启动前必须注册 TodoWrite/等价任务追踪（每个 subagent 一条 todo），完成时标记 completed。
5. Wave C.2 — Spec Compliance Gate（强制）：所有 subagent 全部返回后、调用 complete_stage() 之前，必须先调用 pipeline-orchestrator.verify_subagent_output(stage_name, subagent_outputs, max_retries=2) 用同一份 stage_contract 校验 subagent 输出。不合规不得 advance——详见下方 "Spec Compliance Gate" 节。
6. 如果返回值中 requires_model_switch=true，遵循 sdp-protocol 的 handoff 模板
7. 硬卡点（is_hard_checkpoint=true）无论 autopilot 状态如何，都必须暂停等待用户确认
8. 如果返回值中 rollback.enabled=true，在条件满足时调用 complete_stage(result="rollback") 触发回退
9. 读取 user_level 字段，按 Expert/Intermediate/Novice 调整行为

Spec Compliance Gate（Wave C.2）

目的：在 parallel=true stage 中，subagent 派完任务后不能立刻调 complete_stage() 推进 pipeline——必须先做一道 "spec 合规检查"，确认每个 subagent 的输出真的符合 stage_contract 的契约。否则 subagent 的瑕疵会 直接污染下游 stage，且事后排查只能翻 raw logs。

强制流程（适用于所有 parallel=true stage）：

advance_pipeline()           → 拿到 subagent_tasks + stage_contract
        ↓
并行 dispatch（单条消息）    → subagents 各自返回 {task_id,status,summary,artifacts,...}
        ↓
verify_subagent_output(...)  ← ★ Spec Compliance Gate（不能跳过）
        ↓
   ┌────┴────┐
compliant?   not compliant?
   ↓             ↓
complete_stage   redispatch_failed_tasks（最多 max_retries=2 次）
                 ↓
                 重派后再次 verify_subagent_output
                 ↓
                 仍不合规 + 超 budget → escalate_to_user（人工介入或 rollback）

检查规则（verify_subagent_output 内部实现，使用 get_stage_contract(stage)）：

#	规则	触发条件
1	输出 schema	缺少 task_id / status / summary / artifacts 任一字段 → FAIL
2	status 枚举	status 不在 {PASS, WARN, FAIL, BLOCKED} 中 → FAIL
3	自报 FAIL/BLOCKED	subagent 自己报 status=FAIL 或 BLOCKED → FAIL（不算 spec-compliant）
4	artifacts 存在性	声明的每条 artifact 路径必须真实存在（相对 project_dir 或绝对路径）
5	allowed_tools 子集	若 subagent 自报 tools_used: [...], 必须 ⊆ stage_contract.allowed_tools
6	prohibited_actions	若 subagent 自报 prohibited_violations: [...] 非空 → FAIL

返回值结构：

{
  "compliant": false,
  "stage_name": "review_round1",
  "total_tasks": 6,
  "passed_tasks": ["review_round1_sub_0", "review_round1_sub_1", ...],
  "failed_tasks": [
    {"task_id": "review_round1_sub_3", "reasons": ["status='FAIL' ..."], "retry_count": 1}
  ],
  "retry_recommended": true,
  "retry_budget_exceeded": [],
  "max_retries": 2,
  "next_action": "redispatch_failed_tasks"
}

重派逻辑：

• 每次 verify_subagent_output 调用都会把每个失败的 task_id 在 artifacts/subagent_compliance.json 中 +1
• 一个 task 累计失败次数超过 max_retries（默认 2，即最多重派 2 次后第 3 次失败 即超 budget）→ 该 task 进入 retry_budget_exceeded
• next_action="escalate_to_user"：必须暂停 pipeline，人工介入或触发 rollback
• 通过 spec 的 task 会清空对应计数（task 可在后续 stage 复用同名 ID）
• 所有失败都会自动 log_decision 写入 decision_log，rationale 包含 失败原因 + 重试次数；retry budget 超限的 decision verb 是 subagent_retry_budget_exceeded，普通失败是 subagent_retry_requested

与 check_stage_compliance 的区别：

• check_stage_compliance 检查 stage 级别的 artifact 落盘（如 corpus_ledger.json 存在且非空）
• verify_subagent_output 检查 subagent 级别的输出契约（每个 subagent 的返回是否合规）
• 两者互补：subagent 输出合规 ≠ stage 整体合规。Spec Compliance Gate 位于 dispatch 之后、complete_stage 之前；stage compliance 由 complete_stage 内部触发。两道闸门都必须过。

autopilot 行为：Autopilot ON 时 spec gate 仍执行——但只要 retry budget 没耗尽，会自动重派（无需用户确认）；超 budget 必须暂停（视同硬卡点）。

用户水平自适应（v2）

Pipeline 首次运行时（insight_interview stage）评估用户水平：

水平	判断标准	Pipeline 行为差异
Expert	发过 3+ 篇顶会	提取用户直觉，鼓励 Tier 3 idea，Exemplar Analysis 可选
Intermediate	发过 1-2 篇	平衡风险，AI 给推荐 + 理由
Novice	零经验/跨领域	AI 主导选题（Direction Recommendation），偏保守 idea，强制 Exemplar + Fresh Eyes

决策点行为差异：

• Expert: 展示信息 + 选项，用户自行判断
• Intermediate: 展示信息 + AI 推荐 + 理由，用户可覆盖
• Novice: AI 给出有倾向性的推荐，附 "为什么推荐这个" + "如果不选这个的风险"

Autopilot 模式

开启

用户在任意阶段说 "自动完成" / "autopilot" / "vibe research" 时：

1. 将 project_state.json 的 "autopilot" 设为 true
2. 回复用户：

✅ Autopilot 已开启。后续卡点将自动通过，每个卡点仍会输出简要 summary。
随时说"暂停"可恢复手动控制。

3. 继续执行当前 pipeline，普通卡点自动 approve（硬卡点仍需用户确认，见安全护栏）

关闭

用户说 "暂停" / "停" / "我来看看" / "manual" 时：

1. 将 project_state.json 的 "autopilot" 设为 false
2. 回复用户：⏸️ Autopilot 已暂停，恢复手动控制。

安全护栏

即使 Autopilot ON，以下操作仍需用户确认：

• SDP 硬卡点：Idea 终审、Novelty Risk Gate（overall_risk: unknown/high）、架构终审、QG3 实验设计审批、审稿终审（见 sdp-protocol）
• 删除已有文件
• 大规模代码重构
• git commit / push / 发布
• 涉及 API 费用的大批量请求（>50 次）
• Attempt Budget 耗尽时的暂停决策

卡点行为

在每个人机卡点（Scope Freeze / Corpus Freeze / Idea Approval / Novelty Risk Gate / Architecture Approval / QG3 / Review Arena）：

1. 读取 project_state.json 的 "autopilot" 字段
2. autopilot=true 且非硬卡点：输出 1-2 行 summary → 自动继续下一步
3. autopilot=true 且是硬卡点：输出详情 → 等待用户确认（不可跳过）
4. autopilot=false（默认）：展示详情 → 等待用户确认

项目管理

每次对话开始时：

1. 检查是否存在进行中的项目（workspace/*/project_state.json）
2. 如果有，询问用户"继续之前的项目还是新建？"
3. 如果没有，根据意图创建新项目目录

创建新项目

workspace/{project_name}/
├── project_state.json    # 初始化，含 "autopilot": false
├── corpus_ledger.json    # {"entries": []}
├── evidence_graph.json   # {"claims": []}
├── knowledge_graph.json  # {"nodes": [], "edges": []}
├── hypothesis_board.json # {"hypotheses": []}
├── raw_pdfs/
├── parsed_mds/
├── artifacts/
└── bib/

S2 Key 后补识别

如果用户在任何时候说以下内容，自动识别并写入配置：

• "我拿到了 Semantic Scholar key"
• "S2 key: xxx"
• "API key: xxx"

配置状态查询

用户说"查看配置"或"status"时，展示：

• 全局配置状态（email、S2 key、shadow 开关）
• 当前项目状态（phase、corpus 统计、autopilot 开关）
• 各数据源就绪状态