diff --git a/CLAUDE.md b/CLAUDE.md index eaaad78..31d9284 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -178,3 +178,24 @@ Keep SKILL.md under ~200 lines. Push detail (long field dictionaries, multi-page ## License MIT. See [LICENSE](./LICENSE). + +## Skill attribution protocol + +Every skill MUST set `LONGBRIDGE_SOURCE_SKILL=` as an env-var prefix before each `longbridge` CLI call so the backend can attribute the request to this skill. + +**Prompt layer (all skills)**: each SKILL.md `## CLI` section starts with: + +``` +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=` so the backend can attribute +> the request to this skill. +``` + +**Script layer (`longbridge-earnings`)**: `scripts/collect.py` passes `env={"LONGBRIDGE_SOURCE_SKILL": "longbridge-earnings", **os.environ}` to every `subprocess.run()` call. + +**Protocol details**: +- Env var name: `LONGBRIDGE_SOURCE_SKILL` +- Value format: `^[a-z0-9]+(-[a-z0-9]+)*$` — matches the skill's `name:` frontmatter field exactly +- HTTP header (RFC, CLI-side): `X-Lb-Skill: ` — injected by the CLI binary when the env var is set (external dependency) +- Precision: best-effort; CLI ignores the env var until the binary implements RFC §3.2 +- MCP path attribution: pending server-side support (RFC §3.3) diff --git a/docs/architecture.md b/docs/architecture.md index 0b72768..fa28847 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -92,8 +92,8 @@ The LLM reads `longbridge` stderr directly and translates the situation into the 3. Response-language directive tells the LLM: user typed zh-Hant → reply in zh-Hant ↓ - longbridge quote NVDA.US --format json (LLM may also call `static` - ↓ and `calc-index` and merge by symbol) + LONGBRIDGE_SOURCE_SKILL=longbridge-quote longbridge quote NVDA.US --format json + ↓ longbridge CLI returns a JSON array (English fields) ↓ 4. LLM uses zh-Hant + the multilingual tables in §3/§4 to compose: @@ -120,7 +120,7 @@ Every `SKILL.md` tells the LLM the same rule: **default to CLI; fall back to MCP ### Default rule ``` -1. LLM calls `longbridge --format json` directly. +1. LLM calls `LONGBRIDGE_SOURCE_SKILL= longbridge --format json` directly. 2. Shell returns `command not found` → fall back to MCP. 3. Otherwise parse the JSON output (or surface stderr verbatim if non-zero exit). 4. MCP also unconfigured → tell the user: install longbridge-terminal or run `claude mcp add ...`. diff --git a/skills/longbridge-content/SKILL.md b/skills/longbridge-content/SKILL.md index 547ce4a..887549b 100644 --- a/skills/longbridge-content/SKILL.md +++ b/skills/longbridge-content/SKILL.md @@ -39,6 +39,11 @@ Trigger when user asks about: latest news for a stock, company announcements / r ## CLI Commands +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-content` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-content longbridge news TSLA.US --format json` + Run `longbridge --help` for current flags and output fields. ### `news` — latest news articles for a symbol; fetch full article content @@ -65,6 +70,8 @@ All commands: Public — no login required. Use MCP server if CLI unavailable. Discover tools at runtime. +> **MCP attribution**: MCP 路径的 skill 归因需服务端支持(RFC §3.3),当前为 best-effort。 + ## Related skills | User wants | Use | diff --git a/skills/longbridge-derivatives/SKILL.md b/skills/longbridge-derivatives/SKILL.md index cb6be89..af9d79b 100644 --- a/skills/longbridge-derivatives/SKILL.md +++ b/skills/longbridge-derivatives/SKILL.md @@ -40,6 +40,11 @@ Trigger when user asks about: options quotes, option chains, Greeks (Delta/Gamma ## CLI Commands +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-derivatives` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-derivatives longbridge option chain TSLA.US --format json` + ### `option` — option quotes, option chain, option volume statistics Run `longbridge option --help` for subcommands (quote / chain / volume). diff --git a/skills/longbridge-earnings/SKILL.md b/skills/longbridge-earnings/SKILL.md index 0b11c0e..6361379 100644 --- a/skills/longbridge-earnings/SKILL.md +++ b/skills/longbridge-earnings/SKILL.md @@ -86,6 +86,12 @@ Read [references/full-report.md](references/full-report.md) and follow it. In sh ## Fallbacks +> **Skill attribution**: before every direct `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-earnings` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-earnings longbridge financial-report snapshot TSLA.US --format json` +> Note: `scripts/collect.py` already sets this env var automatically. + - **Partial N/A sections**: the digest marks failed sources as `N/A (reason)`. Work with what succeeded; fetch a missing critical source directly (`longbridge --format json`), checking `--help` only when a command errors. - **No Python (script-less path)**: issue the CLI calls yourself — in PARALLEL (multiple tool calls in one message), never sequentially, and keep raw output small: use `--format json` everywhere, `kline ... --count 30`, `news ... --count 10`, and SKIP the full income statement (`financial-report --kind IS` is ~100KB raw) — take revenue/NI/EPS trends from `consensus` (it carries ~6 periods of estimate + actual) and margins from `financial-report snapshot`. - **HK symbols**: leading zeros are stripped automatically (`09988.HK` → `9988.HK`); do the same when calling the CLI directly. diff --git a/skills/longbridge-earnings/scripts/collect.py b/skills/longbridge-earnings/scripts/collect.py index dd02389..04f233a 100644 --- a/skills/longbridge-earnings/scripts/collect.py +++ b/skills/longbridge-earnings/scripts/collect.py @@ -19,6 +19,7 @@ """ import json +import os import re import shutil import subprocess @@ -40,10 +41,12 @@ def die(msg, code): def fetch(out_dir, name, args): """Run one CLI call; save raw JSON to .json or error to .err.""" + env = {"LONGBRIDGE_SOURCE_SKILL": "longbridge-earnings", **os.environ} try: proc = subprocess.run( ["longbridge", *args, "--format", "json"], capture_output=True, text=True, encoding="utf-8", timeout=TIMEOUT, + env=env, ) ok = proc.returncode == 0 and proc.stdout.strip() except (subprocess.TimeoutExpired, OSError) as e: diff --git a/skills/longbridge-fundamentals/SKILL.md b/skills/longbridge-fundamentals/SKILL.md index 20b5639..2eb95fd 100644 --- a/skills/longbridge-fundamentals/SKILL.md +++ b/skills/longbridge-fundamentals/SKILL.md @@ -55,6 +55,11 @@ Trigger when user asks about: financial statements (income/balance sheet/cash fl ## CLI Commands +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-fundamentals` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-fundamentals longbridge financial-report TSLA.US --format json` + Run `longbridge --help` for current flags and output fields. ### `financial-report` — income statement, balance sheet, cash flow @@ -107,6 +112,8 @@ All commands: Public — no login required. Use MCP server if CLI unavailable. Discover tools at runtime. +> **MCP attribution**: MCP 路径的 skill 归因需服务端支持(RFC §3.3),当前为 best-effort。 + ## Related skills | User wants | Use | diff --git a/skills/longbridge-intel/SKILL.md b/skills/longbridge-intel/SKILL.md index b2fb071..6f19ba8 100644 --- a/skills/longbridge-intel/SKILL.md +++ b/skills/longbridge-intel/SKILL.md @@ -51,6 +51,11 @@ Trigger when user asks about: strategy screening, stock popularity rankings, top ## CLI Commands +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-intel` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-intel longbridge screener --format json` + Run `longbridge --help` for current flags and output fields. ### `screener` — strategy screener: browse strategies, run filters @@ -112,6 +117,8 @@ All CLI commands: Public — no login required. Use MCP server if CLI unavailable. Discover tools at runtime. +> **MCP attribution**: MCP 路径的 skill 归因需服务端支持(RFC §3.3),当前为 best-effort。 + ## Related skills | User wants | Use | diff --git a/skills/longbridge-market-data/SKILL.md b/skills/longbridge-market-data/SKILL.md index 4d321ae..040dcd1 100644 --- a/skills/longbridge-market-data/SKILL.md +++ b/skills/longbridge-market-data/SKILL.md @@ -52,6 +52,11 @@ Trigger when the user asks about: stock price / quote, K-line / candlestick char ## CLI Commands +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-market-data` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-market-data longbridge quote TSLA.US --format json` + Run `longbridge --help` to list all subcommands. Run `longbridge --help` for flags. ### `quote` — real-time quote for one or more symbols diff --git a/skills/longbridge-portfolio/SKILL.md b/skills/longbridge-portfolio/SKILL.md index 4460755..2335b76 100644 --- a/skills/longbridge-portfolio/SKILL.md +++ b/skills/longbridge-portfolio/SKILL.md @@ -53,6 +53,11 @@ Trigger when user asks about: account assets / net value, stock or fund position ## CLI Commands +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-portfolio` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-portfolio longbridge portfolio --format json` + Run `longbridge --help` for current flags and output fields. ### `assets` — account net assets, cash, buying power, margin breakdown @@ -112,6 +117,8 @@ Identify unrealised losses, suggest substitutes, track 30-day wash-sale window. Use MCP server if CLI unavailable. Discover tools at runtime. +> **MCP attribution**: MCP 路径的 skill 归因需服务端支持(RFC §3.3),当前为 best-effort。 + ## Related skills | User wants | Use | diff --git a/skills/longbridge-quant/SKILL.md b/skills/longbridge-quant/SKILL.md index 54e0480..b1beb7f 100644 --- a/skills/longbridge-quant/SKILL.md +++ b/skills/longbridge-quant/SKILL.md @@ -47,6 +47,11 @@ Trigger when user asks about: quantitative indicator scripts (running against K- ## CLI: quant +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-quant` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-quant longbridge quant --help` + The `quant` command runs user-defined indicator scripts against K-line data. ```bash @@ -109,6 +114,8 @@ Rolling walk-forward Random Forest / Gradient Boosting, feature engineering, sig Use MCP server for kline data if CLI unavailable. Discover tools at runtime. +> **MCP attribution**: MCP 路径的 skill 归因需服务端支持(RFC §3.3),当前为 best-effort。 + ## Related skills | User wants | Use | diff --git a/skills/longbridge-research/SKILL.md b/skills/longbridge-research/SKILL.md index 0c8ec45..04570ec 100644 --- a/skills/longbridge-research/SKILL.md +++ b/skills/longbridge-research/SKILL.md @@ -76,6 +76,11 @@ Trigger when user asks about: analyst ratings / price targets, EPS/revenue conse ## CLI Commands +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-research` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-research longbridge institution-rating TSLA.US --format json` + Run `longbridge --help` for current flags and output fields. ### `institution-rating` — buy/hold/sell distribution and recent rating events @@ -142,6 +147,8 @@ All CLI commands: Public — no login required. Use MCP server if CLI unavailable. Discover tools at runtime. +> **MCP attribution**: MCP 路径的 skill 归因需服务端支持(RFC §3.3),当前为 best-effort。 + ## Related skills | User wants | Use | diff --git a/skills/longbridge-technical/SKILL.md b/skills/longbridge-technical/SKILL.md index 6c62294..4670c5d 100644 --- a/skills/longbridge-technical/SKILL.md +++ b/skills/longbridge-technical/SKILL.md @@ -29,6 +29,11 @@ Trigger when user asks about: candlestick patterns, Ichimoku cloud, technical in ## Data dependency +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-technical` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-technical longbridge kline TSLA.US --period day --count 200 --format json` + ⚠️ All frameworks in this skill require OHLCV historical data. **Before running any analysis, fetch K-line data:** ```bash diff --git a/skills/longbridge-value-investing/SKILL.md b/skills/longbridge-value-investing/SKILL.md index 76ac002..4146581 100644 --- a/skills/longbridge-value-investing/SKILL.md +++ b/skills/longbridge-value-investing/SKILL.md @@ -54,6 +54,15 @@ Hard quant filter (ROE ≥ 15%, debt ≤ 50%, FCF positive, gross margin ≥ 30% All frameworks: Public — no login required. +## CLI + +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-value-investing` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-value-investing longbridge financial-report TSLA.US --format json` + +Run `longbridge --help` to discover available subcommands; `longbridge --help` for flags. + ## Error handling | Situation | Response | diff --git a/skills/longbridge-watchlist/SKILL.md b/skills/longbridge-watchlist/SKILL.md index 8e50b78..6d969dd 100644 --- a/skills/longbridge-watchlist/SKILL.md +++ b/skills/longbridge-watchlist/SKILL.md @@ -37,6 +37,11 @@ Trigger when user asks about: viewing watchlist groups, adding or removing symbo ## CLI Commands +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge-watchlist` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge-watchlist longbridge watchlist --format json` + Run `longbridge --help` for current flags and output fields. ### `watchlist` — list groups; create / rename / delete groups; add / remove symbols 🔐 ⚠️ mutating diff --git a/skills/longbridge/SKILL.md b/skills/longbridge/SKILL.md index 505ce2b..2d38ff9 100644 --- a/skills/longbridge/SKILL.md +++ b/skills/longbridge/SKILL.md @@ -21,6 +21,11 @@ For setup and authentication details, see [references/setup.md](references/setup ## Investment Analysis Workflow +> **Skill attribution**: before every `longbridge` CLI call, prefix it with +> `LONGBRIDGE_SOURCE_SKILL=longbridge` so the backend can attribute +> the request to this skill. Example: +> `LONGBRIDGE_SOURCE_SKILL=longbridge longbridge quote TSLA.US --format json` + When the user asks about stock performance, portfolio advice, or market analysis: 1. **Get live data** via CLI — quotes, positions, K-line history, intraday