cue-research

Files (10)

• README.md
• README.zh-CN.md
• SKILL.md
• SKILL.zh-CN.md
• cue_api.py · scripts/
• paths.py · scripts/
• research_run.py · scripts/
• sse_report.py · scripts/
• test_skill_regression.py · scripts/
• update_skill.py · scripts/

SKILL.md (first lines)

# cue-research — let Cue do the work inside your agent

Lets you hand a research question to Cue **in natural language from inside your own AI agent**: it auto-matches ≤2 candidates from your buddy library (or falls back to **free-form deep research through the backend `/api/rewrite`** when nothing fits), runs after you confirm the credits, and can optionally solidify a satisfying run into a buddy. This skill is the **sibling of [`cue-buddy`](../cue-buddy)** — cue-buddy is for **authoring** buddies, cue-research is for **using** them.

## Scope boundary (before invoking)

Cue's tool surface covers **public data sources only** (business registry / courts / regulators / filings / capital flows / procurement …). Scenarios needing **private data** (real AML on bank flows, medical diagnosis, internal accounting) are **refused** by the agent, which suggests rewriting the scenario in public-data terms or using the cuecue.cn web side.

## Setup

**Dependency**: this skill is **self-contained**. `scripts/research_run.py` (run + fetch report + save to disk) and all other calls import shared primitives from **this skill's own `scripts/`** — the shared Cue client (`cue_api` / `sse_report` / `paths`) is vendored locally, so **no sibling `cue-buddy` is required** (see "Import convention" below).

It shares the Cue API-key configuration (`CUE_API_KEY` env or `~/.cue/config.json`). See the "Setup" section of the Cue API's docs.

## Invocation convention (verbs)

| Verb | What it does | Costs credits? |
|---|---|---|
| `+ask <question>` | Main entry: parse → match ≤2 buddies → user picks 1/2/0/n → run → deliver → optionally solidify. **Also accepts implicit natural-language triggers** | Explicit confirmation before running; nothing charged if you don't run |
| `+match <question>` | Only match candidate buddies, don't run | No |
| `+rewrite <question>` | Only call /api/rewrite to see `user_confirmation` + `rewritten_mandate`, don't run | No |
| `+save <conversation_id>` | Solidify a successful free-form run into a buddy (handoff to cue-buddy's `+author`/`+create`) | No (template generation itself is free; only test runs consume) |
| `+upgrade` | Check and (after confirmation) upgrade the skill itself to the latest GitHub `main`. git-clone installs use `git pull --ff-only`; copy installs get manual instructions. On session start the agent should silently run `update_skill.py --silent-check --skill cue-research` (24h cooldown; prints one stderr line when behind, no dialog) | No |

## Decision tree

```
User says (Chinese/English/casual)                               → route
─────────────────────────────────────────────────────────────────────────
"帮我查/调研/研究 <subject or topic>"                              → +ask
"ask Cue about X" / "用 Cue 跑一下 Y"                               → +ask
"看看哪个搭子能查 X" (match only, don't run)                       → +match
"先帮我把这个问题改写成结构化的(不跑)"                               → +rewrite
"把刚才那次调研存成搭子" / "save this run as a buddy"               → +save
"更新一下 skill" / "check for updates" / "升级搭子工具本身"          → +upgrade
─────────────────────────────────────────────────────────────────────────
```

## Main flow `+ask` (most used)

### Stage 1: parse + light clarification

Extract from the user's question:
- **Core entity** (company / person / product / industry)
- **Time window** (if not stated, ask one question to confirm)
- **Angle** (investment / compliance / competitor / sentiment; ask one question if clearly ambiguous)

Ask **≤1 clarification question**. **Do not rewrite the deep-research logic yourself** — that is the backend `rewrite_prompt`'s job, left for Stage 4.

### Stage 2: match candidate buddies (single-stage — read the full catalog, pick directly)

The agent **pulls all visible templates at once** (user-created + system public buddies), groups them mentally by `secondary_category`, and **picks top ≤2 directly from its own semantic understanding — no backend keyword search**. Backend search only matches title + primary/secondary category literally; Chinese isn't tokenized, so 「投资价值」「业绩超预期」「兆易创新」all come back 0 hits (verified in practice); agent LLM semantic understanding is far stronger than such literal matching.

**Implementation:**

```python
from cue_api import search_templates
# pull the full set: keyword=" " + include_system=True, page until done (backend page_size cap 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
```

Each template carries `template_id / title / primary_category / secondary_category / goal`. **`template_id` is a string `template_<base62-suffix>` (e.g. `template_fnig0i`) — Stage 4 running uses this field's value, never the numeric `id` field (templates have both a numeric DB `id` and the string `template_id`, easy to confuse) or a list index; a bare number like `142` is not a valid id.** The agent groups by **`secondary_category`** and scans (`深度核查` / `投资研究` / `信贷尽调` / `市值管理` / `财富投顾` / `私募尽调` / `融资融券` / `法律与行研` / `资本运作` / `行业研究` / `商机挖掘` / `保险营销` … top-12 secondary cats cover ~80% of templates), semantically matching the query against each candidate's `goal`, and picks the most relevant **≤2** candidates.

**Key principle — entity vs intent separation:**

| Info type | Examples | How to use |
|---|---|---|
| **Entity** | 兆易创新 / 万科 / 比亚迪 / a regulatory document name | Left for **Stage 4** to fill `task_input` — **never enters any template-matching step** |
| **Intent** | investment value / compliance risk / earnings review / competitor benchmarking | Agent semantic understanding matches the template's goal/title/category |

**Why separation is mandatory**: templates are **generic research frameworks**; title/category/goal **never** contain specific entity names. Matching 「兆易创新」 as a query against templates is like asking the agent to find a specific subject inside generic frameworks — it can't. The agent must first peel the entity out for `task_input` and match with intent only. See Hard Rule 6.

**Worked examples (6 real queries verified, 4 beat backend keyword search, 1 tied, 1 honestly admitted no match → weak-match):**

| User query | Entity (→ task_input) | Hit secondary_cat → candidates |
|---|---|---|
| 「兆易创新为什么值得投资」 | 兆易创新 | 投资研究 → `个股估值与股价分析` + `个股基本面与风险体检` |
| 「万科最近合规风险」 | 万科 | 法律与行研 + 深度核查 → `企业合规风险体检` + `监管处罚与问询全景` |
| 「调研一下宁德时代财报」 | 宁德时代 | 投资研究 + 财报点评 → `财报分析` + `财务质量与供应链核查` |
| 「这家公司毛利在变」 | (no explicit entity) | 投资研究 + 财报点评 → `财务质量与供应链核查` + `个股基本面与风险体检` |
| 「比亚迪 vs 长城混动竞争」 | 比亚迪、长城 | no perfect match → weak-match nudge |

**Context cost**: ~106 templates today ≈ 2.8K tokens, fully manageable.

**Future extension (labeled follow-up, not done today)**: when the library grows past **200+ templates** and the context cost crosses ~6K tokens, switch to **two-stage**: Stage A shows only `secondary_category` + per-cat template counts (~500 tokens) for the agent to pick 1–3 cats; Stage B shows only the templates inside those cats (~1–2K tokens) for the fine pick. Single-stage is simplest today.

**Low-confidence fallback to keep**: after picking top ≤2, if the agent judges the match weak (query angle diverges from the chosen buddies'), follow the Stage 3 **weak-match nudge** below to suggest "maybe make a new buddy?".

### Stage 3: present + user confirmation

Present, e.g.:

```
Found these possibly-suitable buddies (keyword match, for reference only):
  1. <Buddy A title> — <one-line value>
  2. <Buddy B title> — <one-line value>
  0. None fit → free-form deep research (goes through /api/rewrite for privacy masking + public-source constraints first)
  n. Cancel

The exact credits are only known after the run (the backend offers no pre-run estimate; the first few runs calibrate it — cross-check in the cuecue.cn workbench).

**Duration**: a single deep-research run **usually takes 3–15 minutes**, longer for complex subjects; **the server hard-timeouts at 60 minutes**. The client/agent wait must be set accordingly (don't cut it off at the usual tens-of-seconds API timeout) — stay patient while it runs, don't judge "failed" just because it's slow.
Please enter:
```

**Weak-match fallback:** if the agent judges the listed candidates as only **tangential keyword overlap** with the user's question (titles/categories brush against it but the angle doesn't line up), append one extra line after the list:

> Matching is weak — maybe make a new buddy?

- User answers "做"/"好"/"建"/"+author" or any positive reply → **route to the [`cue-buddy`](../cue-buddy) `+author` flow** (note: **never mention the verb name `+author` to the user in external copy** — internal routing only; to the user just say "make a new buddy").
- User answers "不用"/"直跑"/or picks 0 → go to Stage 4b free-form deep research.

**This nudge only appears on weak match** — on strong/medium match, show the normal 1/2/0/n list and **don't bother the user**.

From sensedeal/cue-skills, MIT.

More from sensedeal/cue-skills