cue-buddy

Files (22)

• README.md
• README.zh-CN.md
• SKILL.md
• SKILL.zh-CN.md
• 2026-05-20-gemini-cli.md · docs/verification-reports/
• corporate-credit.md · references/examples/
• earnings-review.md · references/examples/
• hard-rules.md · references/
• materials-intake.md · references/
• template-fields-spec.md · references/
• cue_api.py · scripts/
• paths.py · scripts/
• sse_report.py · scripts/
• test_capabilities_client.py · scripts/
• test_corporate_credit_coverage.py · scripts/
• test_cue_api_client_contract.py · scripts/
• test_paths.py · scripts/
• test_skill_regression.py · scripts/
• test_template.py · scripts/
• tune_template.py · scripts/
• update_skill.py · scripts/
• validate_template.py · scripts/

SKILL.md (first lines)

# cue-buddy — the buddy-template authoring tool

Lets business users **draft, validate, create, and debug** buddy templates inside their own AI agent, and submit them to their cuecue.cn template library. No code required — everything goes through the Cue production API.

> 中文版见 [`SKILL.zh-CN.md`](SKILL.zh-CN.md) — complete Chinese translation.

## What is Cue / What is a buddy

[Cue](https://cuecue.cn) is a **Deep Research Agent + Intelligence Sentinel** platform for complex finance and business workflows — the backend picks tools from **300+ professional data sources** (A-share / HK / US equity, funds, business registries, courts, regulatory feeds, sell-side research, capital flow …), cross-validates across sources, and attaches a **source link to every conclusion** — compressing "juggling ten websites for half a day" into minutes.

A **"buddy" (搭子)** is your reusable research companion in Cue: you solidify a *satisfying research path* into a template and **reuse it for the same class of scenario** (corporate-credit pre-diligence / public-record compliance snapshot / quarterly earnings review / wealth-management peer comparison / private-fund DD / sector-activity tracking / gov-procurement lead scan …). From then on you just supply the subject name or focus; the buddy gathers evidence per Cue's actual tool surface (A-share/HK/US equity / fund AMAC / business registry / courts / regulatory / capital flow / sell-side reports / procurement — all public data) and produces a structured report per the **report skeleton** you defined. Cue's product premise is *"turn satisfying research experiences into your AI companions"* — buddy templates are how that solidification happens.

> **Key mental model:** Cue's public buddy library already has **100+ ready-made buddies for common scenarios**, callable by any account — **a one-off, non-recurring research task does not need a buddy to be authored first** (just say "research X" on the [cuecue.cn](https://cuecue.cn) web side or via the sibling skill [`cue-research`](../cue-research)). **This skill (`cue-buddy`) is for "you have a class of scenario you do repeatedly and want to solidify into your own buddy"** — author once, reuse for a long time.

> **On first contact with a user, the agent must assume the user's library is NOT empty** (100+ system public buddies work for any account) — **never imply "+create is required before research can run"**; when unsure, call `search_templates(keyword="", include_system=True)` to see the real state.

> **Scope boundary (avoid stumbles when authoring a buddy):** Cue's tool surface covers **public data sources only**. Scenarios needing **private data** (real AML on bank-internal transaction flows / medical diagnosis on EHRs / tax diligence on internal ledgers) **are not suitable as Cue buddies** — the supervisor finds no matching tool in the catalog and falls back to web_search, losing Cue's research-companion value.
>
> **`+author`'s two-tier protection:**
> 1. **Hard refusal** — when the user explicitly names a **private-data** scenario ("AML", "medical diagnosis", "internal-ledger diligence"), the agent **refuses to draft** and suggests "Cue's public-data surface doesn't support this scenario; consider rewriting it as X (public regulatory + court + penalty data)" — the author either reshapes the scenario or backs off.
> 2. **Soft warn** — when a single `search_plan` dimension has no category backing (e.g. "industry-association public data" has no tool in the current catalog), the `+author` flow warns the user that dimension will fall back to web_search; creation may continue.

The product of this skill is the **4 fields** that define the research companion:

| Field | What it decides | ⚠️ Common misunderstanding |
|---|---|---|
| `title` | The buddy's **name on its card** | Concise and value-bearing (~≤8–10 chars); cut filler words (公开/全量/细项/与分析/简报/深度) but **don't over-simplify away distinguishing value** (keep 信披属实/需求匹配/海外执法 type qualifiers) |
| `input_form_spec` | **User input form spec** (required/optional variables + defaults) | One line: `需提供: [属性_主体_类型](示例: X)，可提供: [属性_主体_类型] (默认: ...)`; every 需提供 variable carries `(示例: X)` (frontend placeholder); 可提供 variables carry `(默认: X)` (prefilled, user-clearable). Example values must not contain 默认/缺省/需提供/可提供. The frontend renders `[...]` as form fields. **Not** free-text prose |
| `goal` | The buddy intro = card copy: what problem it solves / what value it delivers | Concise, one paragraph (~40–80 chars, value-first); no "how it works", no implementation leaks, no hardcoded subjects, no disclaimers, no numbered lists |
| `search_plan` | Which data sources you gather evidence from, and the strategy | Cluster by **data source**, not by report-section order |
| `report_format` | What report you deliver (sections/blueprints) | Main heading must contain three-part variables; every section carries a `[执行蓝图]` block |

The backend consumes these 4 fields in order: collect input per `input_form_spec` → research/evidence per `search_plan` → produce the report per `report_format`; the whole output's tone is set by `goal`.

Free-form copy like "buddy description/intro" is only displayed as a one-liner on the frontend workbench category card — that is **auto-derived from `goal` by the backend**, so the author never writes it separately.

## Who you are, what you do

- **Target users**: non-technical people who know a business scenario deeply (finance / banking credit / asset management / private-fund DD / compliance research / industry consulting — any domain researchable via public data)
- **What you can do**: describe a scenario in natural language, **or feed the agent sample reports / industry SOPs / regulatory documents / related links from your work**, and this skill guides you into a spec-compliant 4-field template, submits it to your library, and runs a real task to verify it
- **What you don't need**: Python / API / BuddyContract and other technical concepts. This skill hides them; you only ever see business language
- **Privacy boundary**: your local materials stay in your agent's context and are **never uploaded to the Cue server** (see [`references/materials-intake.md`](references/materials-intake.md))

## Onboarding (instructions for the agent — what the first screen says)

**Forbidden**: do **not** show the full verb menu on the first screen (`+author / +list / +capabilities / +test / +tune ...`), and **do not** push `+capabilities` on its own — it is an internal developer verb a business user will never need.

**The first screen should say**:

1. **One warm greeting line** (recognize where they are).
2. **Intent split (2 choices, natural language, brief)**:
   > What would you like to do today?
   > 1. **You have a class of research scenario you do repeatedly** and want your own buddy (a few minutes; afterwards every such question runs through it) → I'll guide you
   > 2. **You just want to research a company/topic right now** (one-off) → use the sibling skill [`cue-research`](../cue-research) (enable it per your agent's loading convention), or go straight to the [cuecue.cn](https://cuecue.cn) web side; **no need to author a buddy first** — the 100+ system public buddies run for any account
3. **One quiet reminder line**: real tasks cost credits (roughly 3–8 积分 to start; always a confirmation before running); public data only (private-data scenarios like bank flows / medical records / internal ledgers are refused).
4. **Stop.** Wait for the user to answer. Do not stuff `+author` / `+ask` / the full verb list / detailed steps into the first screen.

**Optional shortcuts** (only when the user types them, don't advertise): if the user directly types `+author` or `+ask`, treat it as an explicit trigger and run the corresponding flow. **Natural-language routing is the default** (the decision tree below is your internal reference, not a user-facing menu).

**First-screen data safety**: the agent must not call any API that **consumes credits or writes** on the first screen. If the user's library state is needed (user asks "what buddies do I have"), call `search_templates(keyword="", include_system=True)` for the real state (free, read-only) — never assume an empty or non-empty library.

## Community invite (Cue user community)

At **high-intent moments**, invite the user to the「Cue 用户社群」(Q&A + newest buddy-template sharing), presenting the group QR per the trigger + cooldown rules in [`../community-invite.md`](../community-invite.md) — **restrained, one extra line, not every session**:

- **① First use**: one quiet line on the onboarding screen (one-time).
- **② After `+create` succeeds**: "Like it? Join the group for the latest templates" (14-day cooldown).
- **③ Stuck/error**: when `+validate` fails / permission errors / user confusion, **first help the user / give next steps**, then offer the group as a **gentle fallback** ("if you're still stuck, the group can help too") — not dumping the user into the group on every error (14-day cooldown).
- **④ User explicitly asks**: "how do I join the group / community / feedback / any new templates" → **show the QR image** (**no cooldown**).

**Passive triggers (①②③) get one line of text pointing to the QR image `../assets/community-group-qr.png` — no large image rendering; the large image is only shown on ④ (user-initiated).** The only join entry is the QR code (which encodes the group link) — **never print a plaintext group link**. Cooldown `${CUE_HOME:-$HOME/.cue}/last-community-invite.json` (passive triggers at most once per session, skipped if <14 days since last; read/write failure → no more invites this session). **External groups: Feishu users (incl. other tenants) can scan to join; only pure non-Feishu users cannot** — full rules and boundaries in [`../community-invite.md`](../community-invite.md).

## A "buddy" is 4 plain answers

| Question | Field name | Example |
|---|---|---|
| What input does the user give you? | `input_form_spec` | "需提供：[目标_授信_企业]，可提供：[关注_风险_主题] (默认：通用授信审查)" |
| Who are you, what pain do you solve? | `goal` | "作为银行客户经理的预尽调助手，从公开监管披露和司法记录穿透 [目标_授信_企业] 的偿债与合规风险..." |
| How do you research? (grouped by data source) | `search_plan` | 4 clusters — 主体核验 / 财务实证 / 行业景气 / 经营动态 — each with data routing + actions + validation strategy |
| What report shape do you deliver? | `report_format` | `> **关键配置**` header + 13 sections, each with a `> **[执行蓝图]**` block (research goal / logic chain / info needs / output form) |

Detailed field spec: [`references/template-fields-spec.md`](references/template-fields-spec.md). Rule hard-codes: [`references/hard-rules.md`](references/hard-rules.md).

## Setup: one-time API key

1. Open `https://cuecue.cn/api-key` (logged into your Cue account)
2. Create an API key (format `sk...`), copy it
3. Set it as an environment variable in your shell (once):

```bash
export CUE_API_KEY=sk...
```

Or write `~/.cue/config.json`:

```json
{ "api_key": "sk...", "base": "https://cuecue.cn/api" }
```

Optional: `export CUE_API_BASE=https://cuecue.cn/api` (overrides the default).

Before any verb call, the skill auto-checks the key's validity (requests `/api/templates`, a 200 passes).

## Invocation convention (verbs)

All operations are triggered via `+<verb>`. The skill executes through Python scripts in `scripts/` (stdlib only, no dependencies).

| Verb | What it does | Costs credits? | Backend endpoint |
|---|---|---|---|
| `+author` | Guided drafting of a new template: a few business questions → call `+capabilities` for the current Cue tool surface → agent LLM drafts the 4 fields against supported categories → cross-check every search_plan dimension against `+capabilities` for category backing (warn if none) → auto-run `+validate` | No (capabilities is read-only metadata, unbilled) | (local + `GET /api/tools/capabilities`) |
| `+capabilities` | Fetch the current Cue researcher surface (~391 tools / ~56 categories / 10 presets); supports `q=<term>` / `category=<label>` probes; ETag cache + 304 short-circuit; summary when no args | No | `GET /api/tools/capabilities` |
| `+validate <file>` | Offline-lint any template JSON file for compliance | No | (local) |
| `+create` | POST a validated template to your template library | No | `POST /api/templates` |
| `+list` | List all your templates | No | `GET /api/templates` |
| `+get <template_id>` | Fetch one full template | No | `GET /api/templates/<id>` |
| `+update <template_id>` | Modify an existing template | No | `PUT /api/templates/<id>` |
| `+test <template_id> <entity>` | Run one real conversation (e.g. test subject "万科"), capture the SSE stream, run 8 parametric checks. **A single deep-research run typically takes 3–15 min (longer for complex subjects); the server hard-times-out at 60 min** — the client should wait accordingly (`--timeout` default 3600s). On long runs the live SSE stream often drops before the reporter section reaches the client (timeout or network cut); the script then automatically falls back to DB replay to fetch the full report — **no double charge; this is normal, not an error** | **Yes** (roughly **3–8 积分** to start; exact cost in the workbench) | `POST /api/chat/stream` |
| `+tune <template_id> --issues <path>` | Let the LLM optimize the template from current content + an issue list (seed: bypass path), with diff preview and human confirmation | **Yes** (roughly **1–3 积分** to start) | `POST /api/generate_template` + `PUT /api/templates/<id>` |
| `+frequent <template_id>` | Mark the template "frequent" — pins it to the cuecue.cn workbench home "常用" area | No | `POST /api/templates/frequent` |

From sensedeal/cue-skills, MIT.

More from sensedeal/cue-skills