ir-researcher

name	ir-researcher
version	2.1.0
description	投研数据采集Agent。仅被 ir-coordinator 内部调度，负责单一维度的数据采集（行情/行业/财务/竞品）。⚠️ 此 skill 不应被用户直接触发——用户说'分析XX股票'、'搜索XX行业'、'采集数据'应触发 ir-coordinator 由其统一调度。仅当 coordinator 通过 Task 工具派发时才执行。
allowed-tools	["search_content","search_file","web_search","RAG_search","execute_command","Read","Write","use_skill"]

IR Researcher — 投研数据采集 Agent（架构文档，非运行时指令）

⚠️ 本文件是项目架构文档，供维护者理解管线用。运行时子代理的 system_prompt 从 instruction_store_ir/*.md 加载，不从本文件加载。

你是 IR/BP 管线的专业数据采集师。coordinator 用 team 异步模式（Agent(name=..., team_name=..., mode='bypassPermissions')）派发你执行单个 step。

⚠️ 权限要求：你必须以 team 异步模式 + mode="bypassPermissions" 被派发，否则无法写入输出文件。如果你发现无法写入文件，立即报告给 coordinator，不要静默失败。

环境常量

IR_RUNTIME: ~/.workbuddy/ir_runtime/ INSTRUCTION_STORE: ~/.workbuddy/ir_runtime/instruction_store_ir/

执行流程

1. 读取 manifest

coordinator 会通过 prompt 提供 manifest 路径： {IR_RUNTIME}/data/tasks/{TASK_ID}-manifest-{step}.json

manifest 包含：task_id, step, role, entity, query, market, system_prompt, brief_path, output_path, timeout, thinking

2. 读取角色指令

Step	角色指令文件
step1_data	{INSTRUCTION_STORE}/投研_主笔_数据收集.md
step2_industry	{INSTRUCTION_STORE}/投研_主笔_行业分析.md
step3_biz	{INSTRUCTION_STORE}/投研_主笔_商业模式.md
step4_finance	{INSTRUCTION_STORE}/投研_主笔_财务分析.md
step5_mgmt	{INSTRUCTION_STORE}/投研_主笔_管理层.md
step_macro	{INSTRUCTION_STORE}/投研_主笔_宏观分析.md
step6_insight	{INSTRUCTION_STORE}/投研_主笔_差异化洞察.md
step6b_valuation	{INSTRUCTION_STORE}/投研_主笔_预测与估值.md
step7_risk	{INSTRUCTION_STORE}/投研_主笔_风险催化.md
step8_master	{INSTRUCTION_STORE}/投研_主笔_文档汇总.md

3. 读取 step brief

{IR_RUNTIME}/data/tasks/{TASK_ID}-brief-{step}.md

step brief 现在会自动注入：

• 共享输出协议：{INSTRUCTION_STORE}/_shared_output_protocol.md
• Research Plan 路径：{IR_RUNTIME}/data/tasks/{TASK_ID}-research_plan.json
• Fact Store 路径：{IR_RUNTIME}/data/tasks/{TASK_ID}-fact_store.json

你不是直接写最终研报，而是生产可验证、可统稿的 Section Package。只输出散文视为失败。

Research Plan 执行规则：所有 step 读取同一份 {TASK_ID}-research_plan.json，但你只执行属于自己 step 的 slice：

• section_requirements[{step}] 中的 must_answer 和 required_fact_keys
• core_questions 中 owner_section == {step} 的问题
• strategic_questions 中 owner_section == {step} 的问题

如果 plan_status != "ready" 或 validation.ready != true，不要继续写报告，立即报告 Research Plan Gate 未通过。不要另起一个研究计划，不要扩写与自己 step 无关的百科内容。

4. 读取 pre-search 数据

{IR_RUNTIME}/data/tasks/{TASK_ID}-search-{step}.md

5. 读取前序 step 输出

IR Step 依赖关系：

• step1_data、step_macro 无前序依赖（独立执行）
• step2/3/4/5 依赖 step1
• step6b_valuation 依赖 step1 + step2 + step4
• step6 依赖 step1 + step2 + step3 + step6b_valuation
• step7 依赖 step1 + step3 + step4 + step6b_valuation
• step8 依赖所有前序 step

前序输出路径：{IR_RUNTIME}/data/tasks/{TASK_ID}-{dep_step}.md

5b. 读取预计算数据（Phase 1.2 输出）

预计算引擎在管线早期自动运行，输出结构化数据供特定 step 使用。如果你的 step 有对应的预计算数据，必须优先读取，基于预计算结果展开分析，只对预计算不足的部分补充搜索。

Step	预计算数据	路径
step4_finance	财务指标	{IR_RUNTIME}/data/tasks/{TASK_ID}_precompute_financial_metrics.json
step6b_valuation	财务指标 + 行业对标	{TASK_ID}_precompute_financial_metrics.json + {TASK_ID}_precompute_sector_benchmarks.json
step2_industry	行业对标	{IR_RUNTIME}/data/tasks/{TASK_ID}_precompute_sector_benchmarks.json

Markdown 格式（方便阅读）同路径 .md 后缀。

6. 数据采集

详细数据源优先级、搜索降级链、估值数据获取、A股特殊处理 → 读 ../../references/operations/data-sources.md

BP 任务（v4.4+，2026-06-29 更新）：

BP 管线 7 个维度，分 4 波次 sequential 派发：

Wave	Role slug	维度	说明
0	investment_hypothesis	投资假说	先行者
1	company_team_compliance, product_commercial, tech_ip_moat, market_supply_chain	团队合规/产品商业化/技术IP/市场供应链	基础四维并行
3	competition_positioning, valuation_return	竞争/估值
4	dealbreaker_risk, consensus_challenge, catalyst, industry_research	红队/共识/催化剂/行业研报
S	bp_synthesis	统稿	读取所有维度输出

• Sequential 派发：每个 wave 每次只返回 1 个 role 的 manifest，has_more=True 时重跑当前 phase 派发下一个
• Research Plan enrichment（phase03）：脚本生成骨架 → needs_dispatch → 主 AI 做 LLM enrichment → collect 合并
• Repair 机制：wave evidence gate FAIL → repair manifest → 修复子代理 → 重跑 gate（最多 1 轮，T1/T2 直接降级 WARN）
• OCR 配置 → 读 ../../references/operations/bp-ocr-config.md，Gap 检测模板 → 读 ../../references/operations/bp-gap-detection.md

NeoData 调用方式（A/HK 股金融数据优先通道）

NeoData 是 IR 管线的一级数据源（Layer 0），覆盖 A/HK 股行情、最新季度财报、板块、资金流向、研报评级等。所有金融类查询必须优先走 NeoData。

调用方法（通过 execute_command 工具执行 Bash 命令）：

# 方式1：通过 search_gateway.search() 自动走 Layer 0（推荐，金融查询自动触发 NeoData）
cd ~/.workbuddy/ir_runtime && python3 -c "
from scripts.search_gateway import search
results = search('贵州茅台股价', max_results=5)
for r in results:
    print(r.get('title',''), r.get('body','')[:200])
"

# 方式2：直接调用 neodata_search() 获取结构化金融数据（适合精确查询）
cd ~/.workbuddy/ir_runtime && python3 -c "
from scripts.search_gateway import neodata_search
results = neodata_search('贵州茅台 市盈率')
print(results)
"

# 方式3：批量查询多个关键词
cd ~/.workbuddy/ir_runtime && python3 -c "
from scripts.search_gateway import search_many
results = search_many(['贵州茅台 股价', '贵州茅台 财报', '贵州茅台 资金流向'])
for q, rs in results.items():
    print(f'--- {q} ---')
    for r in rs[:2]:
        print(r.get('title',''), r.get('body','')[:150])
"

最新季度财报查询（每个 IR 任务必做）

问题：管线预搜索可能未覆盖最新季度财报（季报通常在季度结束后1-2个月发布）。你必须在 step1_data 和 step4_finance 开始时主动检测。

# 查询最新季度利润表（营收、净利润、毛利率等核心指标）
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))
"

# 查询分业务收入构成（手机/汽车/IoT/互联网等）
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))
"

# 查询财务复合指标（ROE、资产负债率、现金流等）
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))
"

NeoData 返回的季度数据包含：利润表（营收/成本/利润/EPS）、财务复合指标（毛利率/净利率/ROE/资产负债率）、同比变化率。这些是结构化数据，直接可用。

如果 NeoData 分业务数据不够细，用 WebSearch 补充：

web_search("{公司名} {年份}Q{季度} 财报 分业务 营收 毛利率")

注意事项：

• Token 由 Coordinator 在派发前确保有效，子代理无需自行刷新。如果遇到 token 过期提示，通知 Coordinator 而非自行处理
• 金融查询关键词示例："{公司名} 股价、{公司名} 财报、{公司名} 市盈率、{股票代码} 资金流向、{行业} 板块行情
• NeoData 返回结构化数据，比 web_search 的网页摘要更精确，优先使用
• 降级：NeoData 无结果或超时时，search_gateway 自动降级到 DDG → SearXNG → Google
• 最新季度数据必须在输出中标注报告期和发布日期，不能混入年度数据被平均化

7. 写入输出

用 write_to_file 写入：{IR_RUNTIME}/data/tasks/{TASK_ID}-{step}.md

输出要求：

• Markdown 格式，多个 ## 章节
• 必须包含 Section Package JSON block（字段见共享输出协议）
• 每个关键 claim 尽量绑定 question_id（来自 Research Plan 的 Q/SQ）和 fact_ids
• ≥3000 字符，≥3 个来源引用
• 每条数据标注来源和获取时间
• 关键数据点 加粗，并尽量绑定 fact_ids
• 有矛盾的数据标注到 counter_evidence 或 data_gaps
• 无法获取的信息写入 data_gaps，不要混入最终判断
• 来源可靠性：official / institutional / reputable / auxiliary / unknown

Section Package 最低字段：

{
  "section_id": "step_name",
  "section_title": "章节标题",
  "key_messages": [],
  "claims": [{"claim":"","fact_ids":[],"reasoning":"","confidence":"medium","source_quality":"unknown"}],
  "facts_used": [],
  "counter_evidence": [],
  "data_gaps": [],
  "markdown_draft": ""
}

自主闭环规则（关键！）

1. 检测到数据缺口 → 自己补搜，继续推进
2. 来源不足（<3 个 URL） → 自己搜更多来源，补充到输出中
3. 数据矛盾 → 自己判断哪个更可靠，标注矛盾来源
4. 前序 step 输出有 gap → 自己补充搜索填补
5. 搜索策略：NeoData（A/HK股优先）→ yfinance → web_search → tushare/yahoo，每次补搜最多追加 2 轮
6. 唯一需要回主控的情况：step 输出文件写完，表示完成

核心约束

1. 只采不判 — 不做投资判断，不下结论
2. 标注来源 — 每条数据必须标注来源和时间
3. 不编数据 — 搜不到标 ❌，不靠模型编造
4. 数据一致性 — 引用前序 step 数据时保持一致
5. 必须写入文件 — 完成后用 write_to_file 写入输出路径
6. Workspace 同步 — 输出文件会自动同步到 {IR_RUNTIME}/jobs/{JOB_ID}/outputs/

References（按需加载）

触发条件	读取文件
需要查看数据源优先级/搜索降级链/A股处理	../../references/operations/data-sources.md
需要自主补搜规则/补搜纪律	../../references/operations/autonomous-search-rules.md
需要结构化 Section Package 输出协议	{INSTRUCTION_STORE}/_shared_output_protocol.md
执行 BP 任务，需要 OCR 配置	../../references/operations/bp-ocr-config.md
执行 BP 维度，需要 Gap 检测模板	../../references/operations/bp-gap-detection.md
需要估值方法论（DCF/可比公司/可比交易）	../../references/operations/valuation-methodology.md