trading-skills-navigator

交易技能导航器

此仓库的交互式入门工具。它会将用户的目标转化为具体建议：运行哪个工作流、属于哪个技能集（skills-index 类别）、需要哪些 API，以及适用于 Claude Web App 或 Claude Code 的设置路径。

新用户面对 74 个技能和 12 个工作流，却没有导航工具。此技能就是这个导航工具。它是确定性的——Python 推荐器（scripts/recommend.py）会读取仓库元数据；此 SKILL.md 则以对话方式讲述推荐结果。

使用时机

• 用户表达了交易或投资目标，并询问从哪里开始或该使用哪个技能/工作流（“该用哪个”“从哪里开始”）。
• 用户询问不使用付费 API 密钥能做什么。
• 用户希望区分无 API 和 API 路径，或需要入门路径。
• 用户描述了某种身份（“兼职波段交易者”“股息投资者”“我想做空”“我想回测想法”），并需要推荐相应路径。

不要使用此技能执行交易、下单或自动运行其他技能。它只提供建议和说明。

工作流

第 1 步 — 了解目标和限制条件

从用户的消息中提取：

• 自然语言目标（可直接引用原文）。
• 可选限制条件：是否仅限无 API？每日时间预算 （15m/30m/60m/90m）？经验水平（初级/中级/高级）？

只有在目标为空或无法辨别意图时，才最多提出一个简短的澄清问题。否则继续操作——推荐器能够从容处理不完整信息。

第 2 步 — 运行推荐器

python3 skills/trading-skills-navigator/scripts/recommend.py \
  --query "<the user's goal, verbatim>" \
  --format json
  # optional: --no-api  --time-budget 15m|30m|60m|90m|any
  #           --experience beginner|intermediate|advanced

• 在 Claude Code 中，脚本会自动读取仓库根目录的 SSoT （skills-index.yaml + workflows/*.yaml）。
• 在 Claude Web App 中没有仓库根目录；脚本会透明地回退到打包的 assets/metadata_snapshot.json。两种环境中的推荐结果完全一致——用户的使用行为不会发生变化。

第 3 步 — 以对话方式说明结果

解析 JSON，并用用户的语言进行说明：

• 主要工作流 — display_name、cadence、~estimated_minutes、 api_profile。清楚说明它的作用以及何时运行。
• 路由诊断 — 读取 routing_diagnostics.status。如果是 ambiguous，列出每个 candidate_personas 条目，并说明系统选择了按顺序匹配到的第一个结果；但如果 no-api-path 是对另一个已匹配目标的限制，则不适用此说明。对于 fallback，说明没有匹配到任何 persona，并请用户换一种说法；绝不能把 beginner fallback 描述为精确的意图匹配。unavailable 表示匹配到的目标受阻；在说明中保留原始 persona。
• 目标可用性 — 在描述推荐方案之前，读取 goal_match.workflow、runnability 和 missing_requirements。eligible 表示元数据和指定约束允许使用该工作流；这并不代表数据或输入文件已准备就绪。如果存在 alternative_workflow，请将其标记为通往不同目标的入门途径。
• 次要工作流 — 如有，请说明它们之间的关系（例如：“先运行市场状态检查，只有在允许承担风险时再运行此工作流”）。如果 dropped_secondary_workflows 非空，说明在 no-API 模式下省略了哪些后续工作流，以及原因；它们绝不会导致目标受阻。
• 技能集 — skillset.id（skills-index 类别）。 manifest_status: active 表示此类别附带了精选的 skillsets/<id>.yaml 套件（market-regime、core-portfolio、swing-opportunity、trade-memory、strategy-research）——请说明它是推荐工作流的安装套件。manifest_status: deferred 表示目前还没有清单（例如，诚实说明缺口的类别）；此时推荐仅基于工作流。
• No-API 与 API — 读取 no_api_path：true → 推荐的完整路径无需付费 API 密钥（请明确说明）；false → 告知用户该路径需要哪些付费密钥；null → 对于所请求的目标，没有可用路径。（no_api 是请求标志——表示是否启用了 no-API 模式——而不是路径是否免费；始终根据 no_api_path 进行说明。）如果某个工作流因 --no-api 被排除，请指出 rationale 条目中提到的付费集成（例如，“swing-opportunity-daily 需要 FMP”）。
• 诚实说明缺口 — honest_gap: true 表示此目标没有可用路径。如果 goal_match.runnability 为 unshipped，则不存在专用工作流，suggested_skills 可能会有所帮助。如果为 blocked，则表示存在匹配的工作流，但当前不可用：请解释每项缺失要求。尚未提供 CSV 投资组合审查功能；将 CSV 作为投资组合来源并不会使该功能变得可运行。除非明确指明 CSV 是输出（导出/保存/发送；CSV に出力），且没有任何关于输入的表述，否则任何提及 CSV 都应视为来源。仅提及 Alpaca 永远不能消除这一缺口。
• 回测执行请求 — 如果用户的请求包含回测相关用语，且推荐了研究工作流，请转述 note。该工作流可以评估单独测得的指标，但不会执行回测。它的 no_api_path 不描述单独的回测工具或数据。
• 操作角色 — 说明设置套件或诚实缺口建议中每项技能对应的 operational_roles 条目。如有独立说明原因，也请一并说明；枚举值保持不变。
• 始终读取 rationale 数组，并解释推荐该方案的原因。

步骤 4 — 说明设置路径

阅读 references/setup_paths.md，并引导用户安装 setup_bundle——推荐器针对主要技能集 和每个次要工作流 计算出的确定性安装并集（因此，多工作流推荐不会遗漏任何内容）。依次列出 setup_bundle.required → recommended → optional，引用 setup_bundle.sources 解释每项技能的用途，并说明如何运行该套件：skillset.manifest.related_workflows。将 skillset.manifest（若存在）描述为“推荐的技能集是什么”。如果确实存在缺口，则安装 suggested_skills。根据用户所在环境进行说明（Claude Web App 上传 .skill 文件，或 Claude Code 复制文件夹）；指出这些技能需要哪些付费 API 密钥。

步骤 5 — 指向学习循环

最后引导用户使用 trader-memory-core 和 trade-memory-loop / monthly-performance-review 工作流，确保每条推荐路径都能融入“计划 → 交易 → 记录 → 复盘 → 改进”循环。

输出格式

推荐器输出的 JSON（稳定、幂等、sort_keys）：

字段	含义
primary_workflow	推荐的工作流对象；如果确实存在缺口，则为 null
secondary_workflows	辅助工作流（按顺序排列，并根据时间预算筛选）
skillset	{id, source: skills-index.category, manifest_status, manifest}。如果提供了 skillsets/<id>.yaml，则 manifest_status 为 active，否则为 deferred。如果处于活动状态，manifest 为 5 个键的视图 {display_name, required_skills, recommended_skills, optional_skills, related_workflows}，否则为 null。仅描述主要技能集，而非安装列表
setup_bundle	{required, recommended, optional, sources}——主要技能集 和每个次要工作流 的可执行安装并集（确定性地按层级去重）。这是要安装的内容。 如果确实存在缺口，则所有字段均为空（改用 suggested_skills）
suggested_skills	没有已提供工作流时要使用的技能（确实存在缺口时）；否则为 []
operational_roles	对于每项 setup bundle 技能，或确实存在缺口时的每项 suggested_skills，提供技能 ID → {type, rationale?}
no_api	请求侧：是否启用了无 API 约束模式（通过标志或 persona）
no_api_path	路径侧：整个推荐（主要工作流 + 每个次要工作流）是否无需付费 API 密钥即可运行？true / false；若确实存在缺口，则为 null。这是 DoD 中 API 与无 API 的区分——请明确说明
honest_gap	当没有可用工作流能满足匹配目标（unshipped 或 blocked）时为 true
goal_match	原始 {persona, workflow, runnability, missing_requirements}；eligible 仅表示元数据/约束符合条件
alternative_workflow	单独的 {workflow, relationship: different_goal, no_api_path, explanation}，或 null；绝不会替代目标工作流
dropped_secondary_workflows	[{id, reason}]——在 --no-api 下因需要付费 API 而移除的次要工作流；其他情况下为 []。这不是阻塞因素：请说明这一点，让用户知道后续步骤有所省略
note	对缺口 / 未映射输入的通俗解释
rationale	有序列表，列出推荐理由
routing_diagnostics	{status, selected_persona, candidate_personas, explanation}。status 为 exact、ambiguous、fallback 或 unavailable；候选项是所有约束筛选前的 persona 匹配项，顺序确定
setup_path_ref	设置路径参考的指针

资源

• scripts/recommend.py — 确定性推荐器（路由的唯一事实来源）。
• scripts/build_snapshot.py — 从 SSoT 重新生成 assets/metadata_snapshot.json；--check 用于防止内容偏差（pre-commit + CI）。
• scripts/intent_benchmark.py — 验证故障关闭式双语路由语料、角色影子契约和变形不变量。
• references/intent_routing.md — 角色表、10 个问题的契约、--no-api 凭证规则和评分平局判定规则。
• references/setup_paths.md — Claude Web App 与 Claude Code 的设置步骤。
• assets/metadata_snapshot.json — 为 Web App 备用方案生成的 SSoT 摘要。切勿手动编辑；请运行 build_snapshot.py。
• assets/intent_benchmark_v1.json — 211 个明确标注的 EN/JA 路由案例，精确率/召回率均为 1.0，并设有针对各角色/工作流的覆盖率门槛。