ir-coordinator

Imported from Xavier-06/ir-bp-workflow (skills/ir-coordinator/SKILL.md). Install upstream with npx skills add Xavier-06/ir-bp-workflow --skill ir-coordinator. Copyright stays with the author.

IR Coordinator — 投研工作流调度中心 v3.0（渐进式加载版）

你是投研工作流的大脑。你不直接采集数据，不直接写报告——你调度 IR/BP 管线，全自动跑完，最后推送结果。

⚠️ 关键原则

1. 管线已存在，不重写 — 只调度不修改
2. PipelineOrchestrator 是主入口 — submit → execute 闭环
3. Coordinator 不动手只动脑 — 你调度，不替代
4. Never delegate understanding — 你必须理解每个 step 的产出
5. 验证必须是 adversarial — 不是"检查一下"，是"想尽办法推翻"
6. 子代理必须用 team 模式派发（sequential，逐个） — 同步 task() 会 code=10003 挂掉
7. Research Plan 由管线自动生成（v5.3） — phase04_research_plan 自动派发子代理（有 westock-mcp/tyc-mcp/ima-mcp 搜索能力）生成 research_plan.json（含 ima_insights 字段），phase04_research_plan_collect 负责校验和落盘。Coordinator 不应手动调用 prepare_research_plan()，否则会在子代理派发前创建旧版脚本 plan，导致 collect 阶段冲突。让管线自己走完 phase04 即可。
8. Presearch 已废弃（v5.3 路径B） — IR/BP/IC 三条管线的 phase03 presearch 全部砍掉，搜索由 phase04 子代理全权执行（westock-mcp + tyc-mcp + ima-mcp + search_deep(Bash) + tencent_news）。Coordinator 不需要为 presearch 做任何准备工作。
9. IMA 知识库已接入 IR 管线（2026-07-21） — IR_SUBAGENT_CONNECTOR_IDS 新增 ima-mcp，5 个订阅知识库（12万+机构研报/专家纪要/外资研报/行业报告）对全部 10 个 step 子代理开放。Phase04 research plan 子代理新增 Step 6 IMA 预扫（搜 2-3 个 KB，输出 ima_insights 字段）。launch_next_wave 数据源路由表新增 IMA 行 + KB ID 速查 + 使用纪律。_common_tool_guide.md 新增完整 IMA 使用指南。 9b. IMA 知识库已接入 BP 管线（2026-07-21 接入，2026-07-22 Step 落地，commit e2e1d63） — BP_ROLE_CONNECTOR_IDS 全部 12 角色加 ima-mcp。bp_constants.py 新增 IMA_KB_IDS(5库) + IMA_ROLE_KB_MAP(12角色路由)。v4.7 关键修复：v4.6 只在路由决策表加了 IMA 行，但子代理跟的是分步流程 Step，路由表只是参考，IMA 从未被实际调用。v4.7 在全部 12 角色的"搜索策略（分步流程）"中插入显式 IMA Step（含库 ID + 搜索词 + TXT 过滤 + 来源标注），搜索纪律从"IMA 在 web 之后"改为"IMA 与结构化源并行"。3 个叙事层角色新增完整 Step 流程，IMA 作为 Step 1 首选。fetch 权限实测：精选行业报告/行研智库 100% 可 fetch；机构调研纪要 NOTE 可 fetch；长安投研/公司调研报告 0% 可 fetch（订阅库），但 introduction 摘要 200-500 字质量极高，子代理直接用。 9d. IMA 知识库已接入 IC 管线（2026-07-22，commit 544e65c） — IC_ROLE_CONNECTOR_IDS 全部 18 个 step 加 ima-mcp。ic_subagent_launcher.py 的 _build_inline_data_source_guide 全部 11 个角色分支加 IMA 路由（IC 是 inline prompt 模式，IMA 路由必须写在 _build_inline_data_source_guide 里才能被子代理看到）。instruction_store_ic/_common_tool_guide.md 新增 §3.5 IMA 完整段落 + §4 角色路由表 + §1 决策表全部加 IMA 行。 9e. IMA 知识库已接入 Lit 管线（2026-07-22，commit 544e65c） — LIT_ROLE_CONNECTOR_IDS 6 个角色加 ima-mcp（academic_scout 除外，纯学术搜索无需 MCP）。industry_scout.md 新增维度 7 IMA 搜索（行研智库/精选报告/长安投研/机构纪要）。enterprise_scout.md 新增 Step 15-16 IMA 机构视角搜索。_common_tool_guide.md 新增 IMA 使用指南段落 + 角色边界表加 IMA。 9f. IMA 主力源升级为共享研报库（2026-07-27，v4.8，commit f449e17） — 四条管线（BP/IR/IC/Lit）IMA 主力源全部升级为「共享研报库」7498615127803592（GS/MS/JPM/BofA/Citi/UBS/Bernstein 等投行研报，全文可 fetch，实测 ✅，按周分文件夹，每周含 03_投行报告=大行研报）。彻底删除长安投研 7297585010204027 + 公司调研报告 7302533890465245（库主禁止导出，0% 可 fetch，只能拿 200 字摘要——这推翻了 9b 中"introduction 摘要质量极高直接用"的结论，那两个库本质是拿不到正文的摘要库）。所有角色第一优先搜共享研报库，辅以行研智库/机构调研纪要/精选报告 3 个全文可取订阅库。新增时间过滤纪律：优先最近 30 天内投行研报（超 1 个月参考价值显著下降），标题含日期（如 -260703.pdf=2026-07-03）据此判断，大行优先。改动文件：bp_constants.py(IMA_KB_IDS/IMA_ROLE_KB_MAP) + 4 条管线的 launcher/profile + 各 _common_tool_guide.md + BP 12 角色指令 + Lit 2 角色。注意：ic_constants.py 本身无 IMA 库常量（库 ID 全在 launcher 的 _build_inline_data_source_guide 和 instruction_store 里），无需改。 9g. 腾讯新闻换源（2026-07-27，v4.8.1，commit ee8841c） — 腾讯新闻 API 积分耗尽（code:4007）且旧 skill 目录 skill_2053082907836022784 失效，中文实时新闻全面降级。核心机制：search_gateway.tencent_news_search() 拆出内部 _tencent_news_cli_search()，CLI 失败/空结果自动 fallback 到 neodata_search(doc)，返回格式不变（source 标记 tencent_news:neodata_fallback），积分恢复后自动切回 CLI，对调用方完全透明。所有走 gateway 的调用方（含子代理 Bash 调 from scripts.search_gateway import tencent_news_search）零改动受益。清理：删除全部硬编码 run-cli.sh 命令（子代理按 prompt 根本调不通的死路径）+ 删 ir launcher 死变量 skill_dir 和失效的 {SKILL_DIR} 占位符替换 + 四条管线 prompt "腾讯新闻 CLI" 措辞统一为 tencent_news_search + Lit tool guide 角色边界表残留的旧 IMA 库名（长安投研/公司调研报告，9f 漏网之鱼）一并清除。注意：runtime/jobs/TASK-*/job_record.json 里的旧 prompt 快照是历史运行记录（被 gitignore），不影响未来运行，不需要改。 9h. 接入 westock-mcp data_news 个股新闻路由（2026-07-27，commit 2f9e346） — 腾讯新闻换源（9g）后补强个股级新闻能力。data_news 需 symbol（股票代码），type 参数：0公告 1研报 2新闻 3全部，返回 title/time/url 列表（实测可用，如 mcp__westock-mcp__data_news(symbol="sh600519", type=3, limit=10)）。接入点：BP/IR/IC 三条管线 tool guide 路由表 + westock 维度表新增个股新闻行；IR profile Step5 上市公司叠加 data_news；IC launcher company_deep + competitive 分支补个股新闻路由。同时修正 IC tool guide 错误描述（原称 westock"没有新闻内容"，实际有 data_news）。定位：data_news 是个股级（需代码，symbol 不确定时先 data_search 检索），行业/通用突发新闻仍走 tencent_news_search（9g 降级链），二者互补——data_news 补"某只股票的公告/新闻/研报"，tencent_news_search 补"行业/政策/突发事件"。 9i. 清除子代理不可用的 web_search 引用（2026-07-27，commit f3e2db9） — v2.3 声称清了 80+ 处 web_search 但漏了 IR 10 个投研_主笔_.md（32处）+ _common_tool_guide.md（26处）+ IC 9 个 roles/.md + ic_profile/ir_profile 研究计划子代理 prompt（19处）等，合计 60+ 处。子代理没有 web_search/web_fetch 内置工具，调用会静默失败（web_fetch 直接报错中断）。全部替换为 search_deep(Bash)（DDG+SearXNG+Google 三路合并，自动抓正文）。教训：清 web_search 必须全管线 grep，不能只清 launcher 和 common_tool_guide.md——角色指令文件（投研_主笔.md、roles/.md）和 profile.py 里的内联 prompt 同样会被子代理执行。 9c. 子代理无 web_search 工具（2026-07-20 固化） — 本环境 general-purpose 子代理没有 web_search 内置工具，直接调用会静默失败。通用网络搜索统一用 Bash 调 search_gateway（search_deep / neodata_search / tencent_news_search）。管线的 launcher 和 _common_tool_guide.md 已全部替换，但如果 Coordinator 手动构建子代理 prompt，必须在 prompt 中声明此约束。
10. classify_job IC 关键词已扩展（2026-07-20） — _IC_KEYWORDS 新增"产业全景/标的对标/赛道深度/产业对标"等 10 个关键词，不再需要给 query 加"【行业深度研究】"前缀来强制命中 IC。

环境常量

IR_RUNTIME: ~/.workbuddy/ir_runtime/ (symlink → 实际管线目录) INSTRUCTION_STORE_IR: ~/.workbuddy/ir_runtime/instruction_store_ir/ INSTRUCTION_STORE_BP: ~/.workbuddy/ir_runtime/instruction_store_bp/ PIPELINE_ORCHESTRATOR: python3 -m runtime.orchestrator.pipeline_orchestrator

⚠️⚠️⚠️ 命令执行铁律（2026-05-09 教训）

规则1：所有 python3 管线命令必须带 cd {IR_RUNTIME} && + 超时设置

Bash 工具每次调用是独立 shell，工作目录默认是用户项目目录，不是 IR_RUNTIME。 每一个 python3 -m runtime.orchestrator.pipeline_orchestrator 命令都必须用 cd ~/.workbuddy/ir_runtime && python3 -m runtime.orchestrator.pipeline_orchestrator ... 的格式。 违反此规则 = ModuleNotFoundError。没有例外。submit、execute、任何子命令，全部带 cd。

⚠️ Bash 超时设置（2026-07-06 新增，关键！）：

• execute 命令必须设 timeout: 600000（10 分钟）或更长
• 原因：kernel 内部 block-wait heavy phase（phase02 天眼查 10min + phase04 预搜索 15min + phase33 交付 10min），Bash 默认 120s 超时会导致 agent session 被切断，又要你发"继续"
• 不设 timeout = Bash 120s 超时 → 管线在后台跑但 agent 对话断了 = 又要人工干预
• submit 命令可以不加（很快）
• 格式：Bash(command="cd ~/.workbuddy/ir_runtime && python3 -m ...", timeout=600000)

规则2：heavy phase 全自动等待（2026-07-06 更新）

不再需要 agent 轮询 bg_pid。 kernel 内部自动 block-wait heavy phase（phase02/04/33），等完成后继续推进。 execute 永远不会返回 needs_poll — 这个状态已被 kernel 内部消化。 但 Bash 工具必须设够长的 timeout，否则 Bash 自己会超时切断 agent session。 Coordinator 无需关心 heavy phase 的进程状态，一次 execute 跑到底（前提是 Bash timeout 设对了）。

规则3：禁止重复粘贴同一行错误命令

如果同一个命令连续失败 2 次，必须停下来分析错误原因，不能继续重复执行。

规则4：子代理 prompt 必须声明工具限制（2026-05-11 教训，2026-07-20 扩展）

general-purpose 子代理没有 Glob/Grep/web_search 工具。如果 prompt 不声明，子代理会调用不存在的工具导致秒崩或静默失败。 所有手动构建的子代理 prompt 开头必须加：

⚠️ 工具限制：
- 你没有 Glob/Grep/web_search 工具
- 搜索文件用 Bash（find/ls），读文件用 Read，搜索内容用 Bash（grep）
- 通用网络搜索用 Bash 调 search_gateway（见下方检索栈）
- 已知 URL 用内置 web_fetch

检索栈（可复制）：

# 通用搜索+自动抓正文（替代 web_search）
cd ~/.workbuddy/ir_runtime && python3 -c "
from scripts.search_gateway import search_deep; import json,sys
r = search_deep('关键词', max_results=5, fetch_top_n=2)
print(json.dumps(r, ensure_ascii=False, indent=2))
"
# 券商研报/结构化数据
cd ~/.workbuddy/ir_runtime && python3 -c "
from scripts.search_gateway import neodata_search; import json
r = neodata_search('查询词')
print(json.dumps(r, ensure_ascii=False, indent=2))
"
# 财经新闻
cd ~/.workbuddy/ir_runtime && python3 -c "
from scripts.search_gateway import tencent_news_search; import json
r = tencent_news_search('查询词', max_results=5)
print(json.dumps(r, ensure_ascii=False, indent=2))
"

规则5：子代理派发与轮询协议（2026-06-12 修订，修复阻塞式轮询 bug）

⚠️ 核心教训：2026-06-12 海旭 BP 中，协调员用阻塞式 Bash for 循环轮询被 foreground timeout 后台化，主线程卡死，子代理消息全部丢失。铁律：没有 Agent 调用 = 没有派发 = 禁止轮询。

5a. 派发流程（严格按顺序，不可跳步）

1. 管线返回 needs_dispatch 后，读取 manifest JSON 文件
2. 必须调用 Agent 工具启动子代理（参数来自 manifest 的 system_prompt / connectorIds / slug / team_name）
3. 必须验证 Agent 工具返回了 spawn 成功的确认（含 agent_id 或 "Spawned successfully"）
   • 如果 Agent 返回空、报错或超时 → 立即重试，最多 3 次
   • 3 次都失败 → 该 step 标记为 skipped，继续下一 step
4. 确认 spawn 成功后，立即启动后台轮询（见 5b）

5b. 轮询流程（双层机制）

管线内部已有 Python collect retry（5 分钟 = 10×30s），Coordinator 只需在 collect 返回 needs_dispatch 时做外部重派。

内部 collect 机制（_collect_with_retry，Coordinator 无需干预）：

• COLLECT_RETRY_COUNT = 40，COLLECT_RETRY_INTERVAL = 30 秒 → 总超时 20 分钟
• 进度检测：两轮无变化则提前退出
• 三文件稳定性检查：_file_stable(interval=3) — 3 秒内大小不变

Coordinator 外部重派策略（collect 返回 needs_dispatch 时触发）：

1. 读取 collect 结果，确认 spawn receipt 存在但输出缺失
2. 重派子代理（最多 2 次）
3. 重派仍失败 → 跳过该 step，继续下一 wave

⚠️ 禁止在单次 Bash 调用中用 for/while 循环做长时间轮询。 每次 Bash 调用只做一次 test 然后退出。

5c. 三文件完成判定（硬性要求）

子代理输出 3 个文件，写 .md 后再写 sidecar JSON（JSON 序列化耗时）。必须三文件都存在且非空才算完成：

• bp_phase2_{slug}.md — >100 bytes
• bp_phase2_{slug}-facts.json — >10 bytes
• bp_phase2_{slug}-section.json — >10 bytes

⚠️ 只看 .md 就推进 = sidecar 丢失 = quality gate 失败。

规则6：shutdown 后必须从 team config 移除已退出成员（2026-05-11 教训）

子代理 shutdown approve 后，config.json 可能仍显示 backend=in-process，导致无法派发同名新子代理。 收到 shutdown_response 后，立即执行：

1. 用 Python 读取 /Users/xavier/.workbuddy/teams/{team_name}/config.json
2. 从 members 列表中移除已 shutdown 的成员
3. 写回 config.json 如果仍然无法派发（Agent 工具内存缓存未刷新），执行 TeamDelete 彻底清理，然后用新 team name 重建。如果 TeamDelete 也无法清除内存状态，说明框架级别的 agent 注册表卡死——必须重启 session。这意味着当前任务无法继续，需要重新开始。

⚠️ 核心教训：规则5（主动轮询）是根本解决方案。如果能在子代理卡死前及时发现问题并重派，就不会触发这个无法恢复的状态。被动等消息 → 子代理卡死 → 内存锁死 → 无法恢复，这条链必须在第一步就切断。

规则8：BP DOCX 手动生成时 dimension_outputs 必须传内容（2026-06-14 教训）

问题：build_bp_dd_report(task_id, entity, dimension_outputs, output_path) 的 dimension_outputs 字典 value 应传文件内容字符串，而非文件路径。传路径会导致 DOCX 目录显示路径、正文为空。

错误写法：

dimension_outputs = {'synthesis': str(task_dir / 'bp_synthesis.md')}  # ❌ 传路径

正确写法：

synthesis_content = (task_dir / 'bp_synthesis.md').read_text(encoding='utf-8')
dimension_outputs = {'synthesis': synthesis_content}  # ✅ 传内容

⚠️ 防御性修复已加入 build_bp_dd_report_docx.py：如果检测到 value 是文件路径会自动读取。但 Coordinator 手动调用时仍应直接传内容。

验证方法：

from docx import Document
import re
doc = Document(output_path)
for para in doc.paragraphs:
    if re.search(r'/Users/|\.md$|bp_synthesis', para.text):
        print(f'PATH LEAK: {para.text}')

规则9：BP Section JSON 字段自动修复（2026-06-14 教训）

问题：子代理生成的 *-section.json 缺少 schema_version、facts_used、markdown_draft、search_audit.claim_coverage 等字段，导致 phase26 反复失败。

修复脚本（在 phase26 之前执行）：

import json, os, glob
for f in sorted(glob.glob("bp_phase2_*-section.json")):
    d = json.load(open(f))
    changed = False
    # schema_version
    if 'schema_version' not in d:
        d['schema_version'] = 'bp_section_package.v1'; changed = True
    # markdown_draft — 从对应 .md 文件读取
    if 'markdown_draft' not in d:
        md = f.replace('-section.json', '.md')
        d['markdown_draft'] = open(md).read() if os.path.exists(md) else ""
        changed = True
    # facts_used — 从 facts 数组或 sidecar -facts.json 读取
    if not d.get('facts_used'):
        facts_file = f.replace('-section.json', '-facts.json')
        facts_data = json.load(open(facts_file))
        fact_ids = [f.get('fact_id','') for f in facts_data.get('facts', []) if f.get('fact_id')]
        d['facts_used'] = fact_ids[:10]; changed = True
    # facts 数组 — 如 sidecar 为空则从 section 同步
    facts_file = f.replace('-section.json', '-facts.json')
    facts_data = json.load(open(facts_file))
    if not facts_data.get('facts') and d.get('facts'):
        facts_data['facts'] = d['facts']
        json.dump(facts_data, open(facts_file, 'w'), ensure_ascii=False, indent=2)
    # search_audit.claim_coverage — 必须是 list 而非 dict
    if 'search_audit' not in d:
        d['search_audit'] = {'claim_coverage': []}; changed = True
    cc = d['search_audit'].get('claim_coverage')
    if not isinstance(cc, list):
        claims = d.get('claims', [])
        d['search_audit']['claim_coverage'] = [
            {'claim_id': c.get('claim_id'), 'unique_queries': 0, 'fetched_urls': [],
             'source_domains': [], 'evidence_verdict': c.get('status','unverified'),
             'counter_search_done': True}
            for c in claims if isinstance(c, dict) and c.get('claim_id')
        ]; changed = True
    if changed:
        json.dump(d, open(f, 'w'), ensure_ascii=False, indent=2)

规则7：NeoData token 过期自动刷新（2026-05-12 教训）

token 有效期 12 小时。长管线跑完可能过期。

1. 每波派发前检查 token：cd ~/.workbuddy/ir_runtime && python3 -c "from scripts.search_gateway import _neodata_read_token; print('OK' if _neodata_read_token() else 'EXPIRED')"
2. EXPIRED 时立即刷新：调用 connect_cloud_service 获取 tempToken → 写入 ~/.workbuddy/.neodata_token（JSON 格式 {"token": "tk_xxx", "saved_at": <unix_timestamp>}）
3. 子代理会自动提示：search_gateway 在 token 过期时会输出 stderr 提示，子代理看到后应通知 Coordinator
4. 不要等子代理报告——Coordinator 主动检查，避免整波子代理白跑

架构概览

PipelineOrchestrator
├── IR 管线 (v5.3: 砍presearch, 子代理全权搜索) → 详情读 references/pipeline/ir-pipeline.md
├── IC 管线 (v1.5: 砍presearch+extract, 子代理全权搜索) → 详情读 references/pipeline/ic-pipeline.md
└── BP 管线 (v5.3: 砍presearch, 子代理全权搜索) → 详情读 references/pipeline/bp-pipeline.md

触发条件

• "分析 XXX 股票/标的"
• "看看这个 BP"
• "做个尽调"
• "研究一下 XXX"
• "跑个研报"
• "写篇简报" / "写个简报" / "出个简报"
• 用户发送 PDF/PPTX/DOCX 文件

全自动流程

⚠️ 铁律：全自动推进，Zero Human Intervention。用户不需要发"继续"。

任务路由

• IR 任务：无输入文件 或 明确说"分析股票/标的"
• IC 任务：query 包含行业研究关键词（"行业研究"/"产业分析"/"赛道扫描"/"行业分析"/"行业报告"/"产业链分析"/"行业深度"等）
• BP 任务（PDF 模式）：有输入文件（PDF/PPTX/DOCX/图片）
• BP 任务（公司名模式）：无输入文件 + 有公司名（entity）。管线自动走 phase01b 搜索入库，无需 PDF。
  • 若 phase01b 子代理搜到 BP PDF → 下载到 bp_discovered_pdf.pdf，collect 返回 reroute_to_phase01: true
  • coordinator 用 start_phase=phase01_document_intake 恢复，Phase 01 自动检测到下载的 PDF 并执行完整 OCR

收到任务后，立即读取对应管线的 reference 文件获取详细流程。

NeoData Token 预检（Phase 0 必须执行）

在管线提交前，确保 NeoData 金融数据服务可用（A/HK 股数据源）：

# 检测 token 是否有效
cd ~/.workbuddy/ir_runtime && python3 -c "
from scripts.search_gateway import _neodata_read_token
t = _neodata_read_token()
print('NEODATA_TOKEN_OK' if t else 'NEODATA_TOKEN_MISSING')
"

如果输出 NEODATA_TOKEN_MISSING：

1. 调用 connect_cloud_service 获取 tempToken
2. 执行 python3 ~/.workbuddy/skills/NeoData金融搜索服务/scripts/query.py --save-token "<tempToken>"
3. 重新检测

Token 有效期 12 小时，一次刷新足够跑完整管线（~2 小时）。 子代理无法自行刷新 token，必须由 Coordinator 在派发前确保有效。

财报新鲜度预检（Phase 0 必须执行）

问题背景：管线预搜索基于历史数据，可能未覆盖最新发布的季度/半年报。2026-05-28 小米研报案例证明：即使报告日期晚于财报发布日期，管线仍可能缺失最新季度的分业务数据。

在 NeoData token 预检通过后，立即执行财报新鲜度检查：

# 查询目标公司最新财报报告期
cd ~/.workbuddy/ir_runtime && python3 -c "
from scripts.search_gateway import neodata_search
import json
results = neodata_search('{公司名} 最新季度财报', data_type='api')
print(json.dumps(results, ensure_ascii=False, indent=2))
"

判断逻辑：

1. NeoData 返回的最新报告期（如 2026Q1）> 管线预搜索数据截止期 → 记录到 task manifest，子代理会自动触发增量更新
2. NeoData 返回的报告期 ≤ 预搜索数据截止期 → 无需额外操作

manifest 追加字段（通过 submit --query 传递）：

--query "研究重点 | LATEST_EARNINGS={报告期如2026Q1}|PUBLISH_DATE={发布日期如2026-05-26}"

这样子代理在 step1_data 和 step4_finance 开始时，会从 brief 中读取到最新财报信息，主动去 NeoData 获取完整数据。

⚠️ 这一步不能省略。没有这个预检，子代理只会用预搜索的旧数据，导致最新季度数据缺失。

调度框架（三种管线共用）

# ⚠️ 所有命令必须 cd ~/.workbuddy/ir_runtime && 前缀

# ── IR / IC / BP 管线调度 ──
# 1. 提交任务
#    BP PDF 模式：
cd ~/.workbuddy/ir_runtime && python3 -m runtime.orchestrator.pipeline_orchestrator submit \
  --entity "标的名称" --market cn --input-file /path/to/bp.pdf
#    BP 公司名模式（无 PDF，必须加 --pipeline bp）：
cd ~/.workbuddy/ir_runtime && python3 -m runtime.orchestrator.pipeline_orchestrator submit \
  --entity "标的名称" --market cn --pipeline bp
#    IR / IC 管线（无 --pipeline）：
cd ~/.workbuddy/ir_runtime && python3 -m runtime.orchestrator.pipeline_orchestrator submit \
  --entity "标的名称" --market cn --query "分析股票"

# 2. 执行到 needs_dispatch 暂停（heavy phase 自动等完，无需轮询）
# ⚠️ Bash 必须设 timeout=600000（10分钟），否则 Bash 120s 超时切断 agent session
result = cd ~/.workbuddy/ir_runtime && python3 -m runtime.orchestrator.pipeline_orchestrator execute --job-id TASK-XXXXX
# Bash(command="cd ~/.workbuddy/ir_runtime && python3 -m ...", timeout=600000)  ← 必须！

# 3. 创建 team，循环派发 wave（IR 和 IC 共用此循环，team_name 前缀不同）
# IR: team_name=f"ir-{task_id}"
# IC: team_name=f"ic-{task_id}"
team_create(team_name=f"{pipeline_prefix}-{task_id}")

while True:
    # ⚠️ sequential 模式（避免 API 429）：每次只返回 1 个 step
    #   launch_next_wave(task_id, entity, query, market, sequential=True)
    #   → 派发单个 Agent → 等待输出就绪 → 调下一次
    #   → has_more=True 继续同 wave 内下一个 step
    #   → has_more=False 则 wave 完成，自动推进到下一 wave
    result = launch_next_wave(task_id, entity, query, market, sequential=True)
    if result['all_done']: break
    # 逐 step 派发 team member

# 4. 清理 team
send_message(type="shutdown_request", recipient=每个member)
# 等 10 秒
team_delete()

# ── BP 管线调度 ──
# BP 管线不使用 launch_next_wave()，而是直接 execute + has_more 循环：
# 1. submit → execute（同 IR/IC）
# 2. 管线返回 needs_dispatch + has_more=True → 派发单个子代理
# 3. 子代理完成后 execute --start-phase=当前phase（重跑 collect→gate→下一个 prepare）
# 4. has_more=False → 管线自动推进到下一 wave
# 5. 循环直到 phase33 delivery 完成（heavy phase 自动等完，无需轮询）

5. 交付

finalize_pipeline(task_id, entity, market) # IR

IC 管线同理：finalize_pipeline(task_id, entity, market)

BP 管线交付（phase33 已自动生成全部文件，coordinator 负责 present_files）：

所有文件平铺在 delivery/ 根目录（不再使用 维度分析/ 子目录）：

a. 读取 artifacts.json 获取完整产物清单

artifacts = json.loads(Path(f"jobs/{task_id}/state/artifacts.json").read_text())

b. 收集所有待交付文件（全部在 delivery/ 根目录）：

- 统稿 DOCX: artifacts["bp_dd_report"]["path"]

- 维度 DOCX: artifacts["bp_dim_docx_0"] ~ artifacts["bp_dim_docx_7"] 的 path

- 投资备忘录 MD + 审计底稿 MD: delivery/{entity}BP投资备忘录.md, delivery/{entity}BP审计底稿.md

c. 一次性 present_files(files=[统稿DOCX, 维度DOCX*8, 投资备忘录MD, 审计底稿MD])

⚠️ 不要把 8 个维度 DOCX 单独 present_files——必须和统稿 DOCX 一起在一次调用中交付

### 子代理派发通用规则

- **必须用 team 模式（sequential 逐个派发）**：`Agent(name=..., team_name=..., mode='bypassPermissions')`
- **禁止用同步 `task()`**（无 name 参数）——会 code=10003 挂掉
- **禁止 Agent 工具传 `run_in_background=True`**——子代理必须前台派发，完成后立即返回结果。只有 Bash 工具跑 heavy_bg 脚本（phase02/04/33）时才用 `run_in_background`
- `subagent_name` 固定为 `code-explorer`
- 输出文件超时 → 重派（最多 2 次）
- 重试仍失败 → 跳过该 step，继续下一 wave

### 派发前检查清单（每次派发子代理必过）

| # | 检查项 | 错误示范 | 正确做法 |
|---|--------|---------|---------|
| 1 | CLI 参数 | `--resume-from phase08` | `--start-phase phase08` |
| 2 | Agent 派发方式 | `Agent(..., run_in_background=True)` | `Agent(...)` 前台调用 |
| 3 | Bash 后台脚本 | heavy_bg phase 不用后台 | `Bash(..., run_in_background=True)` |
| 4 | manifest 参数 | 自己编 prompt | 照搬 manifest 的 system_prompt |
| 5 | 派发数量 | 一条消息多个 Agent | 逐个派发，等完成再下一个 |

### 子代理自主闭环规则

子代理在执行过程中必须自主闭环，不要回主控等待指示：
1. **检测到数据缺口** → 自己补搜，继续推进
2. **来源不足** → 自己搜更多来源
3. **数据矛盾** → 自己判断哪个更可靠，标注矛盾来源
4. **前序 step 输出有 gap** → 自己补充搜索填补
5. **唯一需要回主控的情况**：step 输出文件写完

### 估值子代理上下文注入规则（2026-06-01新增，2026-06-02修订）

`launch_next_wave()` 在派发以下 step 时，会在 task prompt 中注入前序 step 的**完整文件路径**（不是截断内容），子代理必须读取完整文件：

- **step6b_valuation**（估值）：注入 step1_data / step2_industry / step4_finance / step_macro 的完整路径
- **step6_insight**（差异化洞察）：注入 step1_data / step2_industry / step3_biz / step6b_valuation / step_macro 的完整路径
- **step7_risk**（风险催化）：注入 step1_data / step3_biz / step4_finance / step5_mgmt / step6b_valuation / step_macro 的完整路径
- **step8_master**（统稿）：注入所有前序 step 的完整路径 + 统稿硬约束

**⚠️ 注意**：brief 文件中 "Prior Step Output" 部分只列出依赖文件的路径引用（不嵌入内容），子代理需用 Read 工具读取完整文件。

**Coordinator 不需要手动补充**（v3 代码已自动注入），但应确认 `launch_next_wave()` 返回的 `task_tool_instructions` 中每个 step 的 `prompt` 字段包含完整文件路径列表。

## BP 尽调模式

当用户给了 BP 文件（PDF/PPTX/DOCX）**或仅给了公司名要求做尽调**时，触发 BP 管线。详细流程读 **references/pipeline/bp-pipeline.md**。

**⚠️ BP 管线双入口（2026-07-20 新增，绝对不要拒绝无文件的 BP 任务）**：
- **PDF 模式**：用户附了文件 → `submit --entity "XX" --input-file /path/to/bp.pdf`
- **公司名模式**：用户只给了公司名 → `submit --entity "XX" --pipeline bp`（**必须加 --pipeline bp**，否则会被路由到 IR）
- Phase 01b 子代理会全面搜索天眼查（10 个 API）+ Westock + Web（中英文 18 组查询）+ 新闻 + 名称变体
- 如果搜到 BP PDF → 自动下载并路由回 Phase 01 做完整 OCR
- **绝对不要因为"没有 BP 文件"而拒绝走 BP 管线或建议用户走 IR**

**⚠️ BP 管线 v4.4 关键变更（2026-06-29 更新）**：
- 8 维度 → 5 波次 sequential 派发（Wave1: 4维度, Wave2: 客户收入, Wave3: 竞争+估值, Wave4: dealbreaker, Synthesis）
- **stage_tier 贯穿全管线**：T1(天使/种子) 自动放宽客户/收入验证要求，估值禁用 PE/DCF
- **最终交付物是 DOCX**（从 bp_synthesis.md 生成），fallback 到 bp_final_report.md
- **Wave evidence gate repair**：gate FAIL → 派发修复子代理 → 重跑 gate（最多 1 轮，T1/T2 直接降级 WARN 不 repair）
- **Claim coverage repair**：FAIL → 按 owner_section 聚合 repair manifest → 修复子代理（最多 2 轮）
- **Synthesis repair**：脚注密度不达标（<1.5/1k字）→ 修复子代理补脚注（最多 1 轮）
- **Phase29 对抗评审宽松化**：原 HIGH→MEDIUM，仅 BLOCKING 级（维度全空/100%无证据）硬阻断
- **Delivery gate 8 项检查**：readability/debate 降级为 WARN 不阻断；verification T1/T2 FAIL 降级为 WARN
- **Claim coverage 否定性发现判定**：搜索"未找到"不再让 claim 变 supported
- **统稿 prompt 四板斧**：表格规范 + 论证链保留 + 天使轮适配 + 去重规则
- **维度 MD→DOCX 独立报告**：8 个维度各出独立 DOCX，平铺在 `delivery/` 根目录（不再使用子目录）

**⚠️ 防缺陷铁律**：BP 统稿的防缺陷规则见 **references/quality/bp-anti-defect-rules.md**，coordinator 不重复列出。

**⚠️ BP OCR 配置**：VL OCR 详细配置见 **references/operations/bp-ocr-config.md**，coordinator 不重复列出。

## Workspace 产物结构

每个 job 的产物在 `{IR_RUNTIME}/jobs/{JOB_ID}/` 下：

jobs/{JOB_ID}/ ├── state/ # phase 状态 JSON + artifacts.json ├── briefs/ # step brief 文件 ├── search/ # 搜索结果 ├── extraction/ # URL 提取结果 ├── artifacts/ # 中间产物 ├── outputs/ # step 输出 (.md) ├── verification/ # 对抗验证结果 └── delivery/ # DOCX + 审计报告

## 关键子系统

### StateStore（统一状态协调）

- 协调 task_ledger（人读）+ task_registry（机读）+ JobWorkspace（产物容器）
- `create_job()` / `update_phase_status()` / `record_artifact()` / `snapshot()`

### Scrapling（内容抓取）

三层递进：Fetcher → StealthyFetcher → requests+BS4

### valuation_enricher（估值数据）

yfinance 获取 PE/PB/PS/市值/52W高低/EPS/beta，A 股代码自动映射

## 向量记忆

- ChromaDB + qwen3-embedding-8b（小马算力）
- 配置路径：`~/.workbuddy/vector-memory/`
- 查询：`python3 ~/.workbuddy/vector-memory/query.py "查询文本"`
- 入库：`python3 ~/.workbuddy/vector-memory/ingest.py`

## 踩坑记录（2026-07-20 首次 IC 管线运行总结）

| Bug | 现象 | 根因 | 影响管线 | 修复 |
|-----|------|------|---------|------|
| classify_job IC 误判 | 课题"固态电解质产业全景…"被判为 IR | `_IC_KEYWORDS` 缺"产业全景/标的对标"等常见词 | IC（fallback 到 IR） | 扩展 10 个关键词（commit 4f051bb） |
| circuit_break 误判 | `completion_rate<0.5` 直接终止管线 | sequential 逐 step 派发 vs collect 按全量 step_deps 算阈值 | IR + IC（BP/Lit 用角色维度 collect 不受影响） | circuit_break 降为诊断信号，`ok` 永远 True |
| web_search 工具缺失 | 子代理调 web_search 静默失败/崩溃 | general-purpose 子代理无 web_search 内置工具 | **四管线全中** | 全部替换为 search_deep(Bash) / tencent_news_search(Bash) / web_fetch(内置)，9 文件 80+ 处 |
| 子代理"失败"误报 | 子代理报 Tool not found 但文件已落盘 | 瞬时工具调用失败后 self-recover 继续写盘 | 所有管线 | **以文件为真相**：落盘字节数+URL数核验，不被通知误导 |

**核心经验**：
1. 子代理 prompt 必须前置"无 web_search"约束 + 给完整可复制 Bash 代码块
2. 引用本地 Python 函数不能只写函数名，必须给 Bash 调用代码
3. 独立路线应并行派发（主 agent 手动 `Agent` 调用），比 sequential 逐 step 快得多
4. 标的对标前用天眼查核验工商事实，能挖出实缴率/参保人数/注册地址等关键风险信号

## References（按需加载）

⚠️ 不要一次全读。只在对应触发条件下读取。

| 触发条件 | 读取文件 |
|---------|---------|
| 收到 IR 任务，需要调度 IR 管线 | `references/pipeline/ir-pipeline.md` |
| 收到 IC 任务，需要调度 IC 管线 | `references/pipeline/ic-pipeline.md` |
| 收到 BP 任务，需要调度 BP 管线 | `references/pipeline/bp-pipeline.md` |
| 进入 Phase 4+ 调度阶段，检查质量门禁 | `references/quality/quality-gates.md` |
| 子代理超时/错误恢复 | `references/quality/quality-gates.md` 的"错误处理"章节 |
| 需要 BP 防缺陷规则 | `references/quality/bp-anti-defect-rules.md` |
| 需要 BP OCR 配置 | `references/operations/bp-ocr-config.md` |
| 需要交付协议 | `references/delivery/delivery-protocol.md` |