Cue Research

cue-research — 让 Cue 在你的 agent 里直接干活

让你在自己的 AI agent 里用自然语言把一个调研问题交给 Cue：自动从你的搭子库里匹配 ≤2 个候选(或无合适搭子时改走"带后端 rewrite 的自由式深研")，确认 credits 后执行，跑完满意可以一键沉淀为搭子。本 skill 是 [cue-buddy](../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](../cue-buddy/SKILL.md) 的"准备"段。

调用约定(verbs)

| Verb | 做什么 | 耗 credits | |---|---|---| | +ask | 主入口：解析 → 匹配 ≤2 个搭子 → 用户选 1/2/0/n → 跑 → 交付 → 可选沉淀。也接受隐式自然语言触发 | 跑前显式确认；不跑不收 | | +match | 只匹配候选搭子，不跑 | 否 | | +rewrite | 只调 /api/rewrite 看 userconfirmation + rewrittenmandate，不跑 | 否 | | +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) `(如 `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. —
2. —
3. 都不合适 → 走自由式深度调研(会先经过 /api/rewrite 做隐私脱敏 + 公开信源约束)

n. 取消

确切 credits 跑完才知道(后端不提供 pre-run 估算，前几次主要用于校准；可在 cuecue.cn 工作台核对)。

耗时：单次深研通常 3-15 分钟，复杂主体更久；服务端 60 分钟硬超时。客户端/agent 等待应按此设置（不要按几十秒的常规 API 超时去掐），跑的过程中保持耐心、不要因为"久"就判定失败。 请输入:

**弱匹配兜底:** 若 agent 判断列出的候选都跟用户问题**只在边角关键词上沾边**(标题/类目蹭到但 angle 对不上),在上面列表**后面**额外打一句:

> 匹配都不强——要不做个新搭子?

- 用户答"做" / "好" / "建" / "+author" 等正向回应 → **路由到 [`cue-buddy`](../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 后缀从不纯数字。

```bash
python3 /scripts/research_run.py \
  --template-id  \
  --query "" \
  --output ~/cue-reports/$(date +%Y-%m-%d-%H%M)-.md
# 续跑(Stage 5 不满意补充澄清时复用上下文,省 credits):再加 --conversation-id 

⚠️ --output 路径必须可写: 默认 ~/cue-reports/。沙箱/受限环境若写不了(常见卡点:runner mkdir -p 父目录或写文件被权限拒),换 agent 可写目录(如 /tmp/、~/.cue/reports/、agent 工作目录)。起跑前先确认目录可写(如 mkdir -p ~/cue-reports && touch ~/cue-reports/.wtest && rm ~/cue-reports/.wtest),别等落盘失败才发现——落盘失败会丢报告,只剩 stdout 的 RESULT 行。

起跑后确认启动(不等结果,只等启动信号): 后台 stdout 出现 [cue-research] STARTED conv_id=…(通常 2-5 秒内,第一个 SSE 事件到达=后端已接受)再让出回合。若出现 [cue-research] chat_stream failed(启动失败,参数/鉴权问题),立即按诊断处理,不对用户说"已开跑"。

让出前对用户说(人话): "已成功开跑(约 3-15 分钟),跑完我直接把报告贴出来,并存到 ~/cue-reports/…。" 不要把 STARTED conv_id= / ▶ agent= 这些 stdout 行转给用户(见上 ⚠️)。

起跑后必须消费 researchrun.py 的流式 stdout(进度 + 完成都靠它): researchrun.py 的 stdout 是流式实时输出(flush=True):STARTED → ▶ agent=… task=…(研究步骤) → ✓ report finalized → RESULT ok|empty。这个流是你的进度 + 完成的唯一来源——必须消费它,不让出后睡等回叫(回叫不可靠,.workbuddy 等平台通知常不来)。

完成检测(必须): 起跑时把 stdout 重定向到文件,再起第二个 background Bash 流式等 RESULT(带超时,防 research_run.py 崩溃不写 RESULT 时无限等):

# 起跑(stdout 重定向到文件,两个 Bash 看同一文件):
# ⚠️ 用 ./cue-run.log(agent 工作目录,跨平台+沙箱可写);别用 /tmp/(Windows 不存在)也别用 ~/（home 根,沙箱拦截）→ 文件不一致 → background Bash 等 RESULT 永不匹配 → agent 卡
python3 /scripts/research_run.py --template-id … --query … --output … > ./cue-run.log 2>&1
# 第二个 background Bash(流式等 RESULT,61min 超时):
timeout 3660 tail -F ./cue-run.log | grep -m1 "RESULT"
# tail -F 跟随新行(不轮询),grep -m1 匹配 RESULT 退出;timeout 3660 防 research_run.py 崩溃(OOM/SIGKILL/未捕获异常)不写 RESULT 时无限等(61min 超 60min hard timeout)
# Bash 完成(RESULT 或超时)→ agent 被通知 → 读 ./cue-run.log 末行 → RESULT ok 读 --output 交付;empty/超时 → 诊断/告诉用户失败

进度展示: 消费 stdout 进度行(▶ agent=… task=…)翻译研究步骤给用户:

• Claude Code: Monitor 工具(tail -F ./cue-run.log | grep "▶\|✓\|RESULT"),每行通知 → 翻译报用户。
• 无 Monitor 的 agent(.workbuddy 等): 用户问进度时读 ./cue-run.log 最新行翻译(不是定期轮询——你让出后不醒,定期读不可行;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 until grep -q RESULT ; do sleep 5; done 等 RESULT 再由完成通知触发。长间歇无输出是正常现象(深研某步可能跑几分钟无进度行),不要反复 Read 同一个 stdout 文件等事件(浪费回合 + 上下文 overflow 风险)。

记住 convid: 起跑后从 stdout STARTED conv_id=… 行取 convid(或起跑时用 --conversation-id 指定),后续检查/replay 都用它。绝不重复起跑:已有 convid 在跑/已完成时,用户问进度检查该 convid(stdout/replay),不要重新 research_run.py(烧新 credits + 丢上下文);只有用户要换主体/换搭子才新起跑。

主动检查完成(持续定时查,别等回叫/别等用户问/别等 5 分钟): 回叫不可靠——你不是被动等通知,而是持续定时查 stdout 末行(每 1-2 分钟,直到 RESULT 出现)(同上"起跑后立即主动跟踪"的定期查机制;不是查一次就完)。查到 RESULT ok → 交付;没 RESULT → replay(conv_id) 取报告:

1. 读后台 stdout 末行。RESULT ok → 读 --output 交付;RESULT empty → 按诊断给下一步。
2. stdout 没 RESULT(任务跑很久/回叫没来)→ 用 conv_id 主动 replay 取报告(不耗 credits,后端若已完成必有报告):

``python 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 非空 → 后端已完成,落盘交付;空 → 还在跑,等一会再查 ``

1. 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)

1. 先调 rewrite(input=)(已自动 unwrap DataResponse 包装),拿到 dict,顶层就是 thinking / user_confirmation / task_node / rewritten_mandate / safety_flag。
2. 展示 user_confirmation(它会说明:要从什么视角调研、脱敏了哪些隐私)+ safety_flag.pii_masked 列表,问:

> 这样调研行吗? > 1. 按此跑 > 2. 我要改一下 query 重 rewrite > 3. 取消

1. 用户选 1,把 rewritten_mandate 作为 --query 喂同一个 research_run.py,不带 --template-id(自由式走 deepresearch_team;选 2 回 Stage 1 拿新 query 重走;选 3 退出):

python3 /scripts/research_run.py \
  --query "" \
  --output ~/cue-reports/$(date +%Y-%m-%d-%H%M)-.md
# 不传 --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? chatstream 本身不调 rewriteprompt(只有 /api/rewrite 端点会),跳过会丢隐私脱敏 + 公开信源约束 + 意图增强。runner 只负责「跑 + 取报告 + 落盘」。

可选——仿写风格(mimic,仅自由式)。 自由式跑时可让报告模仿一篇参考的写作风格/结构。在 Stage 4b 确认前顺带问一句(非必问,用户没需求就别打扰):

> 想让报告模仿某篇的风格/结构吗?给个链接或一份样本文档(可选,不要就直接跑)。

• 给链接 → 加 --mimic-url "";给文档 → 加 --mimic-file ""(runner 会先上传换 file_hash,支持类型以服务端 /api/file_server/accept_type 为准)。
• 仅自由式:--mimic-* 不可与 --template-id 同用(搭子已有 reportformat,后端会让 templateid 压过 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 为准,单文件约 ≤50MB(超限/不支持类型由服务端拒绝并报错);fileid 单次绑定(后端行为:一个 fileid 只能用于一次会话,续跑/换会话需重传)。据后端:上传只校验余额、不单独扣费,跑 chat 才扣 credits。
• query 写法上明确请 agent 检索上传的文档(如"请基于我上传的素材回答…"),让它真去调 file_retrieval;别写"不要检索/只读"之类把工具禁掉的话。

python3 /scripts/research_run.py \
  --query "" \
  --material "~/Downloads/某公司年报.pdf" \
  --output ~/cue-reports/$(date +%Y-%m-%d-%H%M)-.md
# 自由式带素材如上(仍先 rewrite);搭子带素材则再加 --template-id 。同样 run_in_background:true。

Stage 5: 交付 + 满意度

展示报告(reporter content)。问: > 这份报告满意吗? > 1. 满意 > 2. 不满意

• 用户选 1 (满意) → 若刚才是 4b 自由式跑,转 Stage 6;若是 4a 搭子跑,直接结束。
• 用户选 2 (不满意) → 给后续选项,继续 1/2/3 风格:

> 1. 换另一个候选搭子重跑(若 Stage 3 有多个候选还没用过) > 2. 补充澄清后重跑(回 Stage 1 改 query / 改主体 / 改时间窗) > 3. 改路径重跑(刚才是搭子 → 改自由式;刚才是自由式 → 改搭子,回 Stage 2 再匹配)

Stage 6: 沉淀为搭子(可选 handoff 给 cue-buddy)

Stage 5 满意且是 4b 自由式跑时,问用户(对外文案不出现 verb 名): > 这次调研有用,要不要存成一个新搭子?下次同类问题就有现成的可以用。 > 1. 存 > 2. 不用

用户选 1 后,agent 内部路由(以下是给 agent 看的,不出现在跟用户的对话里):

• 把成功跑的 conversation_id + 原问题 + reporter 报告交给 cue-buddy 的 +author 流(后端按 conversation_id 取本次跑的历史用于生成模板)。
• 走 cue-buddy 的 +validate → 用户确认 → +create 落库。
• 这是显式的、用户确认的一步,不自动。对用户文案只说"存""帮你存""做成搭子",不要说"+author"/"+validate"/"+create"。

社区邀请（Cue 用户社群）

在高意图时刻邀请用户加入「Cue 用户社群」（答疑 + 最新搭子模板分享），按 [../community-invite.md](../community-invite.md) 的触发 + 冷却规则呈现群二维码——克制、一行附加、不每次弹：

• ① 首次使用：首次 +ask 的呈现里低调一行（一次性）。
• ② 跑完一次调研后：报告 + 满意度/下一步问题都给完之后附一行（不得插在交付中间）："好用?进群拿最新搭子模板"（14 天冷却）。
• ③ 卡住/报错：匹配不到搭子 / 权限错 / 用户困惑时，先帮用户处理 / 给下一步，再把群作为温和兜底——不是报错就甩去群里（14 天冷却）。
• ④ 用户显式问："怎么加群 / 社区 / 反馈 / 有没有新模板" → 展示二维码图片（不冷却）。

被动触发（①②③）只给一行文字 + 指向二维码 ../assets/community-group-qr.png，不渲染大图；大图仅在 ④（用户主动要）时展示。 加群入口只有二维码（已编码加群链接），不发明文加群链接。 冷却 ~/.cue/last-community-invite.json（被动每会话最多一次、距上次 → cue-skills/cue-buddy/scripts sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "cue-buddy" / "scripts"))

from cueapi import searchtemplates, 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 仅"应可用(共享脚本+同加载约定)",未实证。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sensedeal](https://github.com/sensedeal)
- **Source:** [sensedeal/cue-skills](https://github.com/sensedeal/cue-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.