cue-research — 让 Cue 在你的 agent 里直接干活
让你在自己的 AI agent 里用自然语言把一个调研问题交给 Cue：自动从你的搭子库里匹配 ≤2 个候选(或无合适搭子时改走"带后端 rewrite 的自由式深研")，确认 credits 后执行，跑完满意可以一键沉淀为搭子。本 skill 是 cue-buddy 的兄弟 skill——cue-buddy 负责做搭子，cue-research 负责用搭子。
范围边界(避免起调用前踩坑)
Cue 工具面仅含公开数据源(工商/司法/监管/财报/资金流/招投标等)。需要私有数据的场景(真·反洗钱看银行流水、医疗诊断、企业内账)agent 拒绝执行，提示用户改写成公开数据形态或去 cuecue.cn 网页端。
准备
依赖:本 skill 只有一个薄运行时脚本 scripts/research_run.py(跑+取报告+落盘),它和其余调用都从 sibling ../cue-buddy/scripts 导入共享原语(见下文"导入约定")。因此 cue-buddy 必须与本 skill 同级目录并装(例如都在 ~/.claude/skills/ 下)——只装 cue-research 会在 import 时失败。
跟 cue-buddy 共用一套 API key 配置(CUE_API_KEY env 或 ~/.cue/config.json)。详见 ../cue-buddy/SKILL.md 的"准备"段。
调用约定(verbs)
| Verb | 做什么 | 耗 credits |
|---|
+ask <问题> | 主入口：解析 → 匹配 ≤2 个搭子 → 用户选 1/2/0/n → 跑 → 交付 → 可选沉淀。也接受隐式自然语言触发 | 跑前显式确认；不跑不收 |
+match <问题> | 只匹配候选搭子，不跑 | 否 |
+rewrite <问题> | 只调 /api/rewrite 看 user_confirmation + rewritten_mandate，不跑 | 否 |
+save | 把一次成功的 free-form 跑沉淀为搭子(handoff 给 cue-buddy 的 +author/+create) | 否(模板生成本身不消耗，跑测试才会) |
+upgrade | 检查并(经确认后)升级 skill 自身到 GitHub main 最新版。git clone 装的走 git pull --ff-only,copy 装的给手动指引。session 启动时 agent 应 silent 跑 update_skill.py --silent-check --skill cue-research(24h 冷却,落后时只在 stderr 打一行,不弹问) | 否 |
决策树
用户说什么(中/英文/口语) → 走哪条
─────────────────────────────────────────────────────────────────────────
"帮我查/调研/研究 <主体或话题>" → +ask
"ask Cue about X" / "用 Cue 跑一下 Y" → +ask
"看看哪个搭子能查 X"(只匹配不跑) → +match
"先帮我把这个问题改写成结构化的(不跑)" → +rewrite
"把刚才那次调研存成搭子" / "save this run as a buddy" → +save
"更新一下 skill" / "check for updates" / "升级搭子工具本身" → +upgrade
─────────────────────────────────────────────────────────────────────────
主流程 +ask(最常用)
Stage 1: 解析 + 轻澄清
agent 从用户提问里抽：
- 核心实体(公司/人物/产品/行业)
- 时间窗口(若用户没说，问 1 句确认)
- 角度(投资/合规/竞品/舆情；若明显歧义，问 1 句)
只问 ≤1 个澄清问题。不重写深研逻辑——那是后端 rewrite_prompt 的活，留给 Stage 4。
Stage 2: 匹配候选搭子(单阶段,看完整目录直接选)
agent 一次性拉取所有可见模板(用户自建 + 系统公开搭子),按 secondary_category 在心里分组,然后用自己的语义理解直接挑 top ≤2 个——不走后端关键词搜索。后端 search 只匹配 title + primary/secondary category 字面,中文不分词,把「投资价值」/「业绩超预期」/「兆易创新」等都打回 0 命中(实测验证);agent LLM 的语义理解远强于这种字面匹配。
实现:
from cue_api import search_templates
# 拉全集:keyword=" " + include_system=True,分页直到拿完(后端 page_size 上限 100)
pool, page = [], 1
while True:
batch = search_templates(keyword=" ", include_system=True, page=page, page_size=100)
if not batch: break
pool.extend(batch)
if len(batch) < 100: break
page += 1
每个模板带 template_id / title / primary_category / secondary_category / goal 字段。template_id 是字符串 template_(如 template_fnig0i),Stage 4 跑搭子用它——必须取这个字段的值,绝不是数字 id 字段(搭子同时有数字 DB id 和字符串 template_id,易混)或列表序号;裸数字如 142 不是有效 id。 agent 按 secondary_category 分组扫读(深度核查 / 投资研究 / 信贷尽调 / 市值管理 / 财富投顾 / 私募尽调 / 融资融券 / 法律与行研 / 资本运作 / 行业研究 / 商机挖掘 / 保险营销 ...top 12 个 secondary cat 覆盖 ~80% 模板),拿 query 跟每个候选的 goal 做语义匹配,挑出最相关的 ≤2 个候选。
关键原则——主体 vs 意图分离:
| 信息类型 | 例子 | 用法 |
|---|
| 主体 (entity) | 兆易创新 / 万科 / 比亚迪 / 某监管文件名 | 留到 Stage 4 跑搭子时填 task_input,绝不进模板匹配的任何环节 |
| 意图 (intent) | 投资价值 / 合规风险 / 财报点评 / 竞品对标 | agent 语义理解去匹模板的 goal/title/category |
为什么必须分:模板是通用调研框架,title/category/goal 永远不会含具体主体名。把「兆易创新」当 query 跟模板匹配相当于让 agent 在通用框架里找具体主体——必然不知道选什么。agent 必须先在心里把 entity 剥出来给 task_input,只用 intent 做匹配。详见 Hard Rule 6。
worked examples(实测验证 6 个真实 query,4 优于后端 keyword search,1 持平,1 诚实承认无匹配触发 weak-match):
| 用户 query | 主体 (→ task_input) | 命中 secondary_cat → 候选 |
|---|
| 「兆易创新为什么值得投资」 | 兆易创新 | 投资研究 → 个股估值与股价分析 + 个股基本面与风险体检 |
| 「万科最近合规风险」 | 万科 | 法律与行研 + 深度核查 → 企业合规风险体检 + 监管处罚与问询全景 |
| 「调研一下宁德时代财报」 | 宁德时代 | 投资研究 + 财报点评 → 财报分析 + 财务质量与供应链核查 |
| 「这家公司毛利在变」 | (无显式主体) | 投资研究 + 财报点评 → 财务质量与供应链核查 + 个股基本面与风险体检 |
| 「比亚迪 vs 长城混动竞争」 | 比亚迪、长城 | 没完美匹配 → 触发 weak-match nudge |
Context cost: 今天 ~106 模板,~2.8K tokens,完全可控。
未来扩展(标注 follow-up,今天不动): 库膨胀到 200+ 模板 后 context cost 跨过 ~6K tokens 阈值,需切换为两阶段:Stage A 只看 secondary_category + 模板数列表(~500 tokens)让 agent 选 1-3 个 cat,Stage B 只看那几个 cat 内的模板(~1-2K tokens)细选。今天单阶段最简单。
仍要保留的低置信兜底: agent 选完 top ≤2 后若自己判断匹配度都弱(query 跟选出来的搭子 angle 不一致),走下文 Stage 3 的 weak-match nudge 提示用户「要不做个新搭子?」。
Stage 3: 呈现 + 用户确认
向用户展示，例如：
找到这些可能合适的搭子(关键词匹配，仅供参考)：
1. <搭子A 标题> — <一句价值>
2. <搭子B 标题> — <一句价值>
0. 都不合适 → 走自由式深度调研(会先经过 /api/rewrite 做隐私脱敏 + 公开信源约束)
n. 取消
确切 credits 跑完才知道(后端不提供 pre-run 估算，前几次主要用于校准；可在 cuecue.cn 工作台核对)。
**耗时**：单次深研**通常 3-15 分钟**，复杂主体更久；**服务端 60 分钟硬超时**。客户端/agent 等待应按此设置（不要按几十秒的常规 API 超时去掐），跑的过程中保持耐心、不要因为"久"就判定失败。
请输入:
弱匹配兜底: 若 agent 判断列出的候选都跟用户问题只在边角关键词上沾边(标题/类目蹭到但 angle 对不上),在上面列表后面额外打一句:
匹配都不强——要不做个新搭子?
- 用户答"做" / "好" / "建" / "+author" 等正向回应 → 路由到
cue-buddy 的 +author 流(注意:对用户文案绝口不提 +author 这个 verb 名,内部路由用;用户面只说"做个新搭子")。
- 用户答"不用" / "直跑" / 选 0 → 走 Stage 4b 自由式深研。
这条提示只在弱匹配时给——强/中匹配时正常展示 1/2/0/n,不要打扰用户。
Stage 4a: 用户选 1/2 — 跑搭子(后台跑 + 落盘,跑完再取)
别在 agent 回合里死守一小时的 live 流。 深研单次 3-15 分钟(服务端 60min 硬超时),同步阻塞既浪费回合又脆弱(live 流常丢 reporter 段)。改用 fire-and-retrieve:research_run.py 在后台跑完整流程(发起 chat_stream → live 取报告 → 空则 replay 兜底 → 落盘),agent 回合立即让出;后台任务完成后 agent 被回叫(回叫机制因平台而异、并非总可靠——别干等,见下"主动检查完成"),再读 --output 文件交付。对用户别说"完成后自动通知我"——主动检查完成,别把希望寄托在回叫上。
⚠️ stdout 是 agent 内部信号,不转用户: research_run.py 的 [cue-research] … 行(STARTED conv_id= / ▶ agent=… / 🔧 tool=… / ✓ report finalized / RESULT)是给 agent 内部判断启动/进度/完成用的,绝不直接贴给用户。agent 对用户说人话(起跑确认 / 进度翻译 / 完成交付);用户不该看到 conv_id / agent= / tool= 这些技术行。
起跑(Bash,run_in_background: true):
--template-id 取 Stage 2 候选搭子的 template_id 字段值(形如 template_fnig0i)。别传数字 id 或序号——runner 会对纯数字后缀(如 142→template_142)fail-fast 拒绝(不烧 credits),因 Cue id 后缀从不纯数字。
python3 /scripts/research_run.py \
--template-id <选中的 template_id> \
--query "<原问题或澄清后问题>"
# --output/--log 留空 -> runner 用默认唯一日志/报告路径;起跑后 log= 行打日志路径、RESULT 行打报告路径(都是绝对路径字面值,见下"完成检测")
⚠️ 路径可写性: cue_api.py root 已探测可写根并建好 reports/ logs/(~/.cue 不可写时自动回落到 agent cwd 或 temp,跨平台无 /tmp 依赖)。别再自己 mkdir 或 touch .wtest--runner 起跑时 cue_root() 会再探一次,不可写直接早失败(烧 credits 前)。--output 指别处时 runner 也会探该目录。
起跑后确认启动(不等结果,只等启动信号): 后台 stdout 出现 [cue-research] STARTED conv_id=…(通常 2-5 秒内,第一个 SSE 事件到达=后端已接受)再让出回合。若出现 [cue-research] chat_stream failed(启动失败,参数/鉴权问题),立即按诊断处理,不对用户说"已开跑"。
让出前对用户说(人话): "已成功开跑(约 3-15 分钟),跑完我直接把报告贴出来,并存到你的 cue 目录下(跑完会给全路径)。" 不要把 STARTED conv_id= / ▶ agent= 这些 stdout 行转给用户(见上 ⚠️)。
起跑后必须消费 research_run.py 的流式 stdout(进度 + 完成都靠它): research_run.py 的 stdout 是流式实时输出(flush=True):STARTED → ▶ agent=… task=…(研究步骤) → ✓ report finalized → RESULT ok|empty。这个流是你的进度 + 完成的唯一来源——必须消费它,不让出后睡等回叫(回叫不可靠,.workbuddy 等平台通知常不来)。
完成检测(必须): runner 自带 --log(默认 /logs/cue-run-.log,每 run 唯一),把进度同时 tee 到该文件与 stdout--不用再 shell > 重定向(老 ./cue-run.log 那套的坑:两个 Bash 得共用同一写死路径,沙箱/Windows 一变就失配)。唯一日志名消两类竞态:stale RESULT(新文件无旧内容,tail -F 不会匹上次结果)+ miss RESULT(tail -F 读新文件已有内容,即使 RESULT 在 watcher attach 前已写;tail -n 0 会漏掉秒级失败的 RESULT,watcher 干等 61min)。
⚠️ 跨 Bash 不共享 shell 变量:起跑(Bash1)和等 RESULT(Bash2)是两个独立 Bash 调用,$root/$log 不会带过去。别用变量,用字面绝对路径--runner 起跑后第一行打 [cue-research] log=<绝对路径>,agent 本来就要读 Bash1 stdout 确认 STARTED,顺手记下这行的路径字面值给 Bash2 用:
# Bash1 起跑(run_in_background;--output/--log 都留空,runner 用默认唯一日志,RESULT 行会打 output 全路径):
python3 /scripts/research_run.py --template-id … --query …
# -> 首行 [cue-research] log=/logs/cue-run-.log <- 记下这个绝对路径
# -> STARTED conv_id=… ;进度行 ;末行 RESULT ok|empty output=<报告绝对路径>
# Bash2 第二个 background Bash(tail -F 读新文件内容,不漏 RESULT;用上面记下的 log 字面路径):
timeout 3660 tail -F "" | grep -m1 "RESULT"
# grep -m1 匹配 RESULT 退出;timeout 3660 防 runner 崩溃(OOM/SIGKILL/未捕获异常)不写 RESULT 时无限等(61min 超 60min hard timeout)
# Bash 完成 -> 读 RESULT 行:ok 读其 output=<路径> 报告交付;empty/超时 -> 诊断/告诉用户失败
进度展示: 消费 stdout 进度行(▶ agent=… task=…)翻译研究步骤给用户:
- Claude Code:
Monitor 工具(tail -F | grep "▶\|✓\|RESULT"),每行通知 → 翻译报用户。
- 无 Monitor 的 agent(.workbuddy 等): 用户问进度时读 `` 最新行翻译(不是定期轮询——你让出后不醒,定期读不可行;background Bash 完成通知是唯一主动触发)。
- 翻译:
▶ agent=researcher task=查… → "研究步骤:查…";✓ report finalized → "报告已生成,正在取回";RESULT → 交付。绝不贴原始 ▶ agent= 行(见上 ⚠️)。
绝不告诉用户"完成后会自动通知我"——你消费流式 stdout 主动检测进度 + 完成,不把希望寄托在回叫上。
翻译:把 ▶ agent=… task= 的 task_requirement 作为研究步骤告诉用户,不贴 agent 名(coordinator/supervisor/researcher 是内部角色,用户不关心):
▶ agent=researcher task=查半导体细分景气度 → "研究步骤:查半导体细分景气度"▶ agent=reporter task=撰写半导体景气度报告 → "研究步骤:撰写半导体景气度报告"- 多个 task 整理成步骤列表(1. 2. 3. …),已完成的标 ✅、进行中的标 🔄、未到的标 ⏳
▶ agent=coordinator/supervisor(无 task_requirement):跳过,不报用户(内部协调)✓ report finalized → "报告已生成,正在取回";RESULT ok → 读 --output 报告交付- 绝不贴原始
▶ agent= 行(见上 ⚠️)。整个进度流从 STARTED 到 RESULT 都在 stdout 一个文件里。
⚠️ 别高频 Read stdout 轮询: 进度是事件驱动的——要么用 Monitor 被动收推送(每行进度主动通知你),要么起一个 background Bash tail -F | grep -m1 "RESULT" 等 RESULT 再由完成通知触发。长间歇无输出是正常现象(深研某步可能跑几分钟无进度行),不要反复 Read 同一个 stdout 文件等事件(浪费回合 + 上下文 overflow 风险)。
记住 conv_id: 起跑后从 stdout STARTED conv_id=… 行取 conv_id(或起跑时用 --conversation-id <自定义> 指定),后续检查/replay 都用它。绝不重复起跑:已有 conv_id 在跑/已完成时,用户问进度检查该 conv_id(stdout/replay),不要重新 research_run.py(烧新 credits + 丢上下文);只有用户要换主体/换搭子才新起跑。
主动检查完成(持续定时查,别等回叫/别等用户问/别等 5 分钟): 回叫不可靠——你不是被动等通知,而是持续定时查 stdout 末行(每 1-2 分钟,直到 RESULT 出现)(同上"起跑后立即主动跟踪"的定期查机制;不是查一次就完)。查到 RESULT ok → 交付;没 RESULT → replay(conv_id) 取报告:
- 读后台 stdout 末行。
RESULT ok → 读 --output 交付;RESULT empty → 按诊断给下一步。
- stdout 没
RESULT(任务跑很久/回叫没来)→ 用 conv_id 主动 replay 取报告(不耗 credits,后端若已完成必有报告):
import sys; sys.path.insert(0, "/cue-buddy/scripts")
from cue_api import replay
from sse_report import extract_reporter_content
events = list(replay("", max_seconds=60))
report = extract_reporter_content(events)
# report 非空 → 后端已完成,落盘交付;空 → 还在跑,等一会再查
- replay 有报告 → 落盘
--output 交付(同 research_run 的落盘格式);replay 空 → 后端还没完成,等 1-2 分钟再查(别立刻重复 replay)。
完成回叫后(或主动检查拿到 RESULT): 读 stdout 末行 [cue-research] RESULT ok conv_id=… chars=… output=…(失败是 RESULT empty …),ok 则读 --output 文件 → Stage 5 交付;empty 则按文件里/stdout 的诊断给下一步(多半去 cuecue.cn 网页端看该 conversation)。
为什么这套是对的(背景,别自己重写): research_run.py 是 cue_api + sse_report 共享原语的薄编排(不复制、不漂移),内部把 replay 当主取报告路径:live 客户端流长跑常在 reporter 段到达前断连(server 仍跑完写 DB),所以 extract_reporter_content(live_events) 返回空是常态不是 bug——chat_stream 与 replay SSE 解析逐字节同款、共用同一 extract,replay 读 DB 完整 workflow_events 几乎总能拿到。这套 L1 诊断(diagnose_empty_report 的三种 kind)+ L2 replay 的硬化逻辑与 cue-buddy/scripts/test_template.py 同源、已跑通 ≥9 主体。注意 stream_cut_before_reporter 是 diagnose_empty_report 返回的 kind 字符串,不是可 import 的函数。前台调试需要时(--foreground 语义)直接去掉 run_in_background 即可,但默认走后台。
Stage 4b: 用户选 0 — 自由式深度调研(经过 /api/rewrite)
- 先调
rewrite(input=<用户问题>)(已自动 unwrap DataResponse 包装),拿到 dict,顶层就是 thinking / user_confirmation / task_node / rewritten_mandate / safety_flag。
- 展示
user_confirmation(它会说明:要从什么视角调研、脱敏了哪些隐私)+ safety_flag.pii_masked 列表,问:
这样调研行吗?
- 按此跑
- 我要改一下 query 重 rewrite
- 取消
- 用户选 1,把
rewritten_mandate 作为 --query 喂同一个 research_run.py,不带 --template-id(自由式走 deepresearch_team;选 2 回 Stage 1 拿新 query 重走;选 3 退出):
python3 /scripts/research_run.py \
--query ""
# 不传 --template-id = 自由式深研。同样 run_in_background:true(起跑后等 STARTED 信号确认启动 + 中途可读 stdout 查进度,见 Stage 4a),完成回叫后读 --output。
rewrite 仍由 agent 在前台先做、runner 不碰(Hard Rule 3/4:不在 runner 里重写后端 rewrite 逻辑;且要先把 user_confirmation + pii_masked 给用户确认)。为什么必须先 rewrite? chat_stream 本身不调 rewrite_prompt(只有 /api/rewrite 端点会),跳过会丢隐私脱敏 + 公开信源约束 + 意图增强。runner 只负责「跑 + 取报告 + 落盘」。
可选——仿写风格(mimic,仅自由式)。 自由式跑时可让报告模仿一篇参考的写作风格/结构。在 Stage 4b 确认前顺带问一句(非必问,用户没需求就别打扰):
想让报告模仿某篇的风格/结构吗?给个链接或一份样本文档(可选,不要就直接跑)。
- 给链接 → 加
--mimic-url "";给文档 → 加 --mimic-file "<本地路径>"(runner 会先上传换 file_hash,支持类型以服务端 /api/file_server/accept_type 为准)。
- 仅自由式:
--mimic-* 不可与 --template-id 同用(搭子已有 report_format,后端会让 template_id 压过 mimic → 静默失效,runner 直接拒绝)。两个 mimic 参数也互斥。
- 一次跑完、不中途确认(
need_confirm=False):后端按样本自动生成风格模板并直接往下跑,不为「审模板」停下来等输入——这是为了不破坏后台一次跑完。代价:你没机会在烧 credits 前先看那个自动模板;若风格推歪了就重给样本再跑。(交互式审模板是 Phase 2,暂未做。)
可选——文档接地(素材,搭子与自由式都可用)。 当用户想让调研基于自己的文档(合同/年报/PDF/会议纪要…)而不只是公开信源时,把文档作为素材传进去:研究 agent 会用内置 file_retrieval 工具对其做全文语义检索(真 RAG,不是只看开头预览)。与 mimic(仿风格)正交、也能与 --template-id 同用。
- 加
--material "<本地路径>",可重复多个文件:--material a.pdf --material b.docx。runner 先把每个文件上传(SSE 走完 …→completed 才拿到 file_id),再随 conversation_file_ids 绑进这次跑。
- 要先经用户确认再上传(见安全规则:默认不上传本地材料)。问一句:"要把这份文档作为调研素材上传吗?它会用于检索,会占用本次 credits。"
- 类型/大小(均为服务端约束,runner 不在本地预检大小):支持类型与精确上限以
/api/file_server/accept_type 为准,单文件最大 256 MiB(超限/不支持类型由服务端拒绝并报错);file_id 单次绑定(后端行为:一个 file_id 只能用于一次会话,续跑/换会话需重传)。据后端:上传只校验余额、不单独扣费,跑 chat 才扣 credits。
- query 写法上明确请 agent 检索上传的文档(如"请基于我上传的素材回答…"),让它真去调
file_retrieval;别写"不要检索/只读"之类把工具禁掉的话。
python3 /scripts/research_run.py \
--query "<问题;明确要求基于上传素材调研>" \
--material "~/Downloads/某公司年报.pdf"
# 自由式带素材如上(仍先 rewrite);搭子带素材则再加 --template-id 。同样 run_in_background:true。
Stage 5: 交付 + 满意度
展示报告(reporter content)。问:
这份报告满意吗?
- 满意
- 不满意
- 用户选 1 (满意) → 若刚才是 4b 自由式跑,转 Stage 6;若是 4a 搭子跑,直接结束。
- 用户选 2 (不满意) → 给后续选项,继续 1/2/3 风格:
- 换另一个候选搭子重跑(若 Stage 3 有多个候选还没用过)
- 补充澄清后重跑(回 Stage 1 改 query / 改主体 / 改时间窗)
- 改路径重跑(刚才是搭子 → 改自由式;刚才是自由式 → 改搭子,回 Stage 2 再匹配)
Stage 6: 沉淀为搭子(可选 handoff 给 cue-buddy)
Stage 5 满意且是 4b 自由式跑时,问用户(对外文案不出现 verb 名):
这次调研有用,要不要存成一个新搭子?下次同类问题就有现成的可以用。
- 存
- 不用
用户选 1 后,agent 内部路由(以下是给 agent 看的,不出现在跟用户的对话里):
- 把成功跑的
conversation_id + 原问题 + reporter 报告交给 cue-buddy 的 +author 流(后端按 conversation_id 取本次跑的历史用于生成模板)。
- 走 cue-buddy 的
+validate → 用户确认 → +create 落库。
- 这是显式的、用户确认的一步,不自动。对用户文案只说"存""帮你存""做成搭子",不要说"+author"/"+validate"/"+create"。
社区邀请（Cue 用户社群）
在高意图时刻邀请用户加入「Cue 用户社群」（答疑 + 最新搭子模板分享），按 ../community-invite.md 的触发 + 冷却规则呈现群二维码——克制、一行附加、不每次弹：
- ① 首次使用：首次
+ask 的呈现里低调一行（一次性）。
- ② 跑完一次调研后：报告 + 满意度/下一步问题都给完之后附一行（不得插在交付中间）："好用?进群拿最新搭子模板"（14 天冷却）。
- ③ 卡住/报错：匹配不到搭子 / 权限错 / 用户困惑时，先帮用户处理 / 给下一步，再把群作为温和兜底——不是报错就甩去群里（14 天冷却）。
- ④ 用户显式问："怎么加群 / 社区 / 反馈 / 有没有新模板" → 展示二维码图片（不冷却）。
被动触发（①②③）只给一行文字 + 指向二维码 ../assets/community-group-qr.png，不渲染大图；大图仅在 ④（用户主动要）时展示。 加群入口只有二维码（已编码加群链接），不发明文加群链接。 冷却 ${CUE_HOME:-$HOME/.cue}/last-community-invite.json(与 config 同目录;设 CUE_HOME 则随迁)（被动每会话最多一次、距上次 <14 天跳过；读写失败则本会话不再弹）。外部群：飞书用户（含其它租户）可扫码加入；仅纯非飞书用户加不进——完整规则与边界见 ../community-invite.md。
Hard rules(铁律)
- 不自动选搭子。永远让用户从 ≤2 候选 + "0 直跑" + "n 取消" 中选。
- 每次真跑都显式确认 credits。哪怕是用户选了"0 直跑"作为 fallback，也要再确认一次("自由式深研可能比有模板的更费 credits，确认继续？")。
- free-form 路径(Stage 4b)必须先调 /api/rewrite。不要直接把用户原问题塞进 chat_stream。
- 不在 agent 侧重写后端的 rewrite 逻辑。要 rewrite 就调 /api/rewrite，要澄清 ≤1 句就好。
- 不实现
+delete(防误删；删搭子去网页工作台)。
- 主体名(具体公司/人物/产品/事件名)只能进
task_input,绝不进模板匹配的任何环节。模板是通用调研框架,title/category/goal 永远不含具体主体名——混进去会让 agent 把不该匹的硬匹上(或干脆无所适从)。匹配靠 agent 语义理解 query 的「意图」维度(投资/合规/财报/竞品...),主体名留给 Stage 4 跑搭子时填 task_input。这条规则与具体匹配机制无关,无论今天的全单选还是未来切两阶段都成立。详见 Stage 2。
安全规则
跟 cue-buddy 同源：API key 不出现在输出/日志/提交；用户粘了 key → 提醒去 cuecue.cn/api-key 立即轮换。默认不上传本地材料;仅当用户明确要求做文档接地(--material)时,经用户确认后才上传其指定的素材文件(用于 file_retrieval 检索),其余情况一律不碰用户本地文件。
脚本到 verb 映射
| Verb | 走哪条路径 | 用到的脚本/函数 |
|---|
+ask (主入口) | Stage 1-5 编排 | Stage 2-3 匹配:cue_api.search_templates;Stage 4 跑+取报告:scripts/research_run.py(后台跑,落盘);Stage 4b 先 cue_api.rewrite |
+match | 只跑 Stage 2-3 | cue_api.search_templates |
+rewrite | 只跑 /api/rewrite | cue_api.rewrite |
+save | Stage 6 handoff | 交给 cue-buddy 的 generate_template + validate_template + cue_api.create_template |
+upgrade | 升级 skill 自身 | python3 ../cue-buddy/scripts/update_skill.py --skill cue-research(交互式) / 加 --silent-check(session 启动轻量版) |
本 skill 唯一的运行时脚本是 scripts/research_run.py——它是 ../cue-buddy/scripts/ 共享原语(cue_api + sse_report)的薄编排,只负责「发起 chat_stream → live 取报告 → 空则 replay 兜底 → 落盘」,不复制任何原语(避免与 cue-buddy 版本漂移)。scripts/test_skill_regression.py 只做结构/import 自检。别让 agent 在 prose 里手写 chat_stream 事件循环——那正是早期 reporter-content 取不到、误诊为「解析器坏」的根因;固定走 research_run.py。
导入约定(运行时 bootstrap)
跑/取报告固定走 research_run.py(它内部已处理 sys.path + chat_stream + replay + 落盘),agent 不手写 chat_stream/replay 循环。agent 真正会直接 import 的只有 Stage 2-3 的匹配 + Stage 4b 的 rewrite(只读、快、前台跑)。cue_api / sse_report 不在默认 import 路径(在 sibling cue-buddy/scripts/),这两类调用起手:
import sys
from pathlib import Path
# cue-research/<...> → cue-skills/cue-buddy/scripts
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "cue-buddy" / "scripts"))
from cue_api import search_templates, rewrite # Stage 2-3 匹配 / Stage 4b 自由式前的 rewrite
如果是 agent 直接通过 Bash 跑 python3 -c "...",改成绝对路径:sys.path.insert(0, "/cue-buddy/scripts")。规避点:不要在 cue-research/ 下复制粘贴 cue_api.py——会跟 cue-buddy 的版本漂移。
兼容性
| Platform | 状态 |
|---|
| Claude Code | 同 cue-buddy(SKILL.md 自动加载) |
| Gemini CLI / Codex CLI | 同 cue-buddy 加载约定 |
| Hermes / OpenClaw / Kimi | ✅ v0.2.0 cross-agent 已验证(真实任务 live API;同 cue-buddy 加载约定 + 共享脚本) |
v0.3.0 新增面的验证状态(诚实标注):后台 runner(research_run.py)、replay 主路径、仿写(mimic URL+文档)均在 Claude Code 上以真实 live API 跑通(2026-06-08:replay 双路径对照、mimic PDF 端到端);但这些 v0.3.0 新 surface 尚未在 Hermes/OpenClaw/Kimi 等做 cross-agent 复跑——上面那行的 cross-agent 结论是 v0.2.0 面的。新面跨 agent 仅"应可用(共享脚本+同加载约定)",未实证。