openmobius-skill

OpenMobius-skill — 多流派交易知识技能

一项统一技能，支持四种交互意图，并配备精选的多流派知识库（726 张概念卡片 + 1282 张案例卡片），内容提炼自 12 个精选来源合集中的 300 多个交易视频和直播课程。

核心原则：每项交易分析结论都必须基于 (a) 可见的图表证据，或 (b) 检索到的知识库规则。能力声明必须基于已安装的清单和声明的配置文件契约。 不得捏造——如有不确定之处，请明确说明。

时效性要求 — 绝不凭记忆回答市场问题

任何提及资产 + 时间周期的用户消息——即使没有出现“现在” / “now”一词——都必须在当前轮次调用一次 kb_klines.py indicators 或 kb_klines.py chart。例如：

• “BTC 1h 怎么样”——是的，现在调用 API
• “ETH 现在怎么样”——是的
• “茅台日线分析下”——是的
• “金子 4 小时”——是的
• “BTC 还在跌吗”——是的，即使没有给出时间周期（默认采用用户暗示的周期，或询问用户），仍然适用时效性规则

此实时获取要求适用于当前市场请求。如果用户明确要求分析其提供的 OHLCV，则保留该快照，不要用实时数据替换；使用 workflows/klines.md 中解析数据来源说明的页脚，并说明其时效性未经独立验证。

控制面例外：关于已安装技能支持哪些分析模型 / School / 模式，或某个指定 School 能否分析某个市场的问题，属于能力发现，而非分析该市场的请求。应用资产 / 时间周期规则前，应先将其路由到问答能力发现分支；即使问题提及资产或时间周期，也不要获取市场数据。

能力门控例外：首先确定请求的市场分析路由。如果该路由所需的原生分析器 / 过滤器不受支持，则在任何网络调用或产物生成前停止，报告能力缺口，不要添加捏造的时效性页脚。以下时效性要求仅在市场路由通过该门控后适用。

硬性规则：

1. 不要引用训练数据中的价格、价位、摆动枢轴点、BOS/CHoCH 事件或结构（“BTC 曾在 60K-100K 左右”→禁止）。
2. 不要在同一对话中复用超过 60 秒的较早轮次价格数据——重新获取。
3. 不要编造时间戳、“数据截至”标签，或 API 响应的 freshness 区块及用户提供的数据集中没有明确出现的“实时”声明。
4. 对于基于 API 的当前市场分析，唯一可信来源是本轮 API 调用返回的 freshness 区块。如果本轮尚未调用 API，必须说： "我需要先拉一下最新数据"，并在回答前调用 API。

所有通过能力门控的市场分析回复都必须使用匹配的页脚：基于 API 的分析使用时效性页脚；分析用户粘贴的 OHLCV 使用解析数据来源说明页脚（见 workflows/klines.md 第 5 步）。回复缺少适用的页脚即为不完整。

如果 API 响应中的 freshness.is_stale == true（最新 K 线早于 2 × 周期），请明确告知用户市场可能已休市，或 API 可能存在延迟——不要默默将过时数据报告为实时数据。

---

数据来源披露（标准答复）

当用户询问数据来源时——包括：“数据从哪来 / 数据源 / data source / where is this data from / 你用什么数据 / 是实时吗 / real-time? / 怎么取的数据”——请使用下方的标准披露内容作答。替换为最近一次 API 调用的 freshness 区块及任何可见的 exchange / market / symbol 字段中的实时值。

标准答复模板（双语）

**Data source / 数据来源**: Mobius Quant API (api.mobiusquant.ai)

Current request / 本次请求:
- exchange = `<exchange from response>`
- market   = `<market from response>` (spot / perp / cn / hk / us / forex)
- symbol   = `<symbol from response>`
- fetched_at (UTC)      = `<freshness.fetched_at>`
- last_bar_open (UTC)   = `<freshness.last_bar_open_time_utc>`
- last_bar_age_seconds  = `<freshness.last_bar_age_seconds>` (is_stale=<is_stale>)

**About upstream sources / 关于上游来源**: Mobius Quant exposes OHLCV,
technical indicators, and SMC structural signals as an aggregator. Which
underlying exchanges or data vendors it connects to upstream, and
whether direct-feed vs aggregated — **this skill cannot verify**. See
https://www.mobiusquant.ai/ for details.

硬性规则——关于数据源，绝对不能这样说

• 不得提及具体的上游供应商，除非该字符串原样出现在 API 响应的 exchange 字段中。允许使用的值是 symbols_search / klines / indicators 实际返回的值（例如，加密货币的 binance、bybit、okx、hyperliquid；股票的 cn / hk / us）。
• 不得提及网络数据提供商（新浪财经 / Yahoo Finance / TradingView / 东方财富 / 同花顺 / Bloomberg 等）——你无法验证这些信息。
• 不得描述上游数据处理流程（“Mobius 通过 WebSocket 从 Binance 获取数据” / “tick 级数据流” / “延迟 15 分钟”）——你无法验证此类说法。
• 不得作出超出 freshness.is_stale 报告内容的时效性声明。请使用 last_bar_age_seconds 字段中的原始数字。

可以说的内容

• API 端点（api.mobiusquant.ai）
• 返回的确切 JSON 字段（exchange / market / symbol / count / current_price / freshness.*）
• Mobius 在服务端计算 SMC 结构指标
• 指向 https://www.mobiusquant.ai/ 以了解上游详情

---

与主机无关的运行时和产物路径

运行工作流前，请为当前主机解析这些占位符。它们是文档标记，不是字面路径或 shell 变量：

• <SKILL_ROOT> — 包含已加载 SKILL.md 的目录。所有命令都应以此目录作为工作目录运行，以便相对 scripts/ 路径能够解析，而不依赖用户当前目录。
• <PYTHON> — 为此已安装技能选择的 Python 可执行文件。请从平台或安装程序管理的运行时中解析此路径；Windows 和 POSIX 的可执行文件路径不同，受管理的主机也可能提供自己的运行器。不要假设 PATH 中有 python 或 python3。
• <TEMP_DIR> — 通过当前主机的临时目录功能创建的、可写且专用于当前任务的临时目录。不要假设某个特定的 POSIX 或 Windows 系统路径存在。
• <USER_OUTPUT_DIR> — 用户选择或主机提供的可写目录，用于存放必须返回给用户的持久化产物。不要默认将仓库检出目录或开发者机器上的路径用作输出位置。
• <INPUT_IMAGE> — 主机解析后的用户所附图表路径。

切勿直接执行尖括号占位符。路径解析后，若路径包含空格，请根据当前命令运行器的要求为其加引号。命令块使用逻辑参数列表，避免使用仅适用于 shell 的管道、here-doc 和续行语法。使用主机的文件写入工具或 JSON 序列化器创建 JSON / 文本输入，然后将生成的文件路径传递给脚本。

为兼容 WorkBuddy 打包，以 kb_retrieve.py 开头的命令行仅是与启动器无关的简写形式。执行前必须将其展开为 <PYTHON> scripts/kb_retrieve.py；不得假设 PATH 中有 kb_retrieve.py。

始终先从知识库检索

知识库包含通用训练数据中缺少的基于规则的识别标准和已记录的注意事项。先解析路由并确认其功能，然后在该路由内检索，再进行综合——不要仅凭记忆回答交易问题，也不要在不明示的情况下扩大已选学校 / 来源的范围。

语义卡片检索要求适用于交易知识问答，不适用于控制平面能力发现。能力发现会检查已安装的 School 清单和声明的配置文件契约，不会运行常规查询 / Top-K 搜索；请遵循 workflows/qna.md 中的特殊情况。

分析配置编排

首先识别有关已安装技能可用模型／配置、分析视角、学派、模式、支持的意图，或某个指定学派对市场分析的支持情况的能力发现问题。这些问题仍属于 intent=qna，但优先级高于默认的 strict ICT/SMC 路由，以及任何资产／时间范围或图表路由。阅读 workflows/qna.md 和 workflows/analysis_profiles.md，使用 kb_retrieve.py --layer school --list-schools --format json 检查已安装的清单（按上述与启动器无关的规则展开），然后立即根据该清单和声明的配置契约作答。这是一项有意限定范围的单 Agent 控制平面操作：不得委派给子 Agent／后台任务，不得递归调用此技能，不得运行 Git、扫描源代码／卡片／清单文件，或验证分析器实现。此分支不得构建或继承分析学派路由，并须在能力答复后停止。

对于所有常规分析和知识请求，必须在检索、调用指标、分析或绘图之前确定路由：

route = {intent, mode, primary_lens, secondary_lenses, schools, sources, capabilities}

• intent 必须恰好为 qna、analyze、annotate 或 klines 之一。不得输出 kline_analysis 之类的别名。
• capabilities 必须始终为对象，不能是列表或字符串。使用 workflows/analysis_profiles.md 中定义的规范字段和值。
• 对于纯默认路由，设置 exact_primary_school_filter=true、source_filter=not_requested、intent_supported=true 和 reason=null；对于问答，将 native_market_analyzer 设为 not_required，对于市场意图则设为 supported。此默认路由无需加载配置参考。
• lens（也称为 profile）是 ict_smc 或 chanlun 之类的分析方法；source 是 Teach-Wuyuan 之类的语料库／教师集合。来源不会自动选择分析视角。
• 未明确指定分析视角、学派、来源或组合选择器时，使用 mode=strict、primary_lens=ict_smc 和 schools=[ICT, SMC]；使用 --layer school --schools ICT SMC 检索。
• 默认情况下，单个明确选择器采用 strict 模式。第一阶段仅支持问答的 compare；市场分析、图表和标注比较会在网络或产物操作开始前安全失败。augment 赋予一个主分析视角对偏向判断和交易水平的决定权，次要分析视角仅用于确认、质疑或补充风险背景。
• 学派范围内的依据使用 school_knowledge_v2，该层会省略无法归属的跨学派融合规则。任何指定来源都使用 source_evidence_v2 和 --layer evidence --sources ...；如需精确交集，将其与 --schools ... 结合使用。绝不得使用融合后的规范层来声称实现了严格的学派／来源隔离。
• 默认情况下，学派／证据查询使用硬过滤混合检索（基于独立嵌入的范围内文档进行 BM25 + 语义 RRF）。除非是在诊断检索，否则保持 --search-mode auto；精确术语／别名始终优先，且绝不扩大硬性学派／来源边界。
• 绝不得在未说明的情况下回退：不得从明确指定的分析视角／来源回退到 ict_smc 或未过滤搜索。执行工作前检查 capabilities，并明确报告不受支持或为空的路由。
• 支持 ChanLun 知识问答，但此技能目前没有原生的 ChanLun 市场结构分析器或叠加层。绝不得将 SMC 指标输出描述为 ChanLun 分析。

每当用户指定分析视角／学派／来源、请求比较或扩充、排除某个配置，或所选能力不确定时，都要阅读 workflows/analysis_profiles.md。纯默认的 ict_smc 请求可直接进入下方的意图工作流。

市场分析输出格式为必填项

Analyze 和 Kline 工作流会以一个综合分析步骤结束，并要求使用 ## 节标题。这些标题必须逐字出现，且顺序必须符合规定。Q&A 和 Annotate 使用各自工作流文档中定义的输出结构。若能力缺口响应在分析前就结束，则不受市场分析模板和时效性页脚的约束。

场景路由器

根据用户输入选择正确的子工作流。每个工作流的详细步骤均见其对应文档：

用户输入	工作流	要阅读的文档
关于已安装技能能力的问题（“当前有哪些分析模型”“which Schools are available”“缠论能分析 BTC 1h 吗”）——即使包含资产／时间周期或图表引用	Q&A 能力发现	workflows/qna.md + workflows/analysis_profiles.md
概念问题，没有图表、数据或资产名称（“什么是 FVG”“how to identify OB”“止损放哪里”）	Q&A	workflows/qna.md
附有图表 + 任何关于图表的问题（“分析”“看一下”“走势”“where to enter”“what's happening”）	Analyze（自动获取真实 OHLCV + 标注）	workflows/analyze.md
用户明确要求在图像上绘制／标注，或分析后跟进说“把这个标在图上”	Annotate	workflows/annotate.md
用户粘贴 OHLCV 数据，或在没有图表的情况下明确提及资产 + 时间周期（“BTC 1h 怎么样”／粘贴 CSV／“茅台日线”）	Kline 分析（自动生成新的图表 PNG）	workflows/klines.md

图表输出是 Analyze 和 Kline 分析工作流标准回复的一部分——渲染 PNG，并在输出中包含其路径。仅当用户明确表示不需要图表时，才跳过图表步骤（“只要文字”／“skip chart”／“no image”／“不用画图”）。对于用户粘贴的 OHLCV 数据，请遵循 workflows/klines.md 中的 Path B 例外情况，切勿仅为满足图表输出要求而获取其他实时数据序列。

路由方式：

1. 首先检测能力发现；若匹配，则遵循其 Q&A 控制平面特殊情况并停止，不再应用分析路由
2. 否则，按上述路由确定工作流；若满足触发条件，则加载 analysis_profiles.md
3. 在场景表中识别用户的意图
4. 使用 Read 工具加载相关工作流文档（相对于此 SKILL.md 的路径：workflows/<name>.md）
5. 遵循该工作流，同时保留路由所规定的分析视角／数据来源边界

重要——Analyze 工作流现在会自动获取数据：如果附有图表，且能从图表中识别资产／时间周期，analyze.md 将通过 Mobius API 获取真实 OHLCV，用精确价格补充视觉分析。此功能默认启用；用户可通过“只看图不拉数据”／“skip data fetch”选择退出。

注意：Analyze 工作流已在最后一步自动生成带标注的图像。除非用户希望使用不同参数重新渲染（不同颜色、新的 bbox、仅输出 JSON 等），否则无需在 Analyze 之后单独调用 Annotate。

两种图表生成方式

用户需要可视化图表时，请选择合适的工具：

情况	工具	输出
用户上传了自己的图表图像，并希望在该图像上进行标记	scripts/kb_draw_annotation.py（PIL）	原始图像的带标注副本
没有图表图像，或用户想要一张干净的新图表	scripts/kb_klines.py chart + render	全新 TradingView 级别图表：K 线 + 结构叠加层（FVG／OB 矩形、扫单线、摆动点标记、交易设置线）

对于方式 #2，典型流程如下：

# 1. Pull K-lines + auto-filled SMC structural overlay for an ict_smc route
<PYTHON> scripts/kb_klines.py chart --query "BTC" --interval 1h --limit 200 --output <TEMP_DIR>/chart.json

# 2. Optionally create a separate trade-setup JSON containing only entry/SL/
#    target hlines; do not duplicate the structural items already auto-filled.

# 3. Render PNG (add --trade-setup <TEMP_DIR>/setup.json only when one exists)
<PYTHON> scripts/kb_klines.py render --input <TEMP_DIR>/chart.json --output <USER_OUTPUT_DIR>/chart.png --theme dark --width 1400 --height 900

指标获取

默认 ict_smc 配置：SMC 结构指标

对于分析视角为 ict_smc 的市场分析分支，请先获取 SMC 结构指标。未指定选择器的请求会创建此默认分支。对于严格的非 ict_smc 分支，不要获取或将 SMC 用作结构证据；在 augment 中，应将其证据限制在分配给该分支的已标注次要角色内。

<PYTHON> scripts/kb_klines.py indicators --query "BTC" --interval 1h --limit 200 --format compact

未使用 --inds 标志时，默认使用 SMC。一次调用的响应包含：

• 每根 K 线的状态：摆动／内部趋势偏向、活动的摆动和内部枢轴、追踪极值（自上一个枢轴以来的运行最大值／最小值）、SMC 指标的内部波动率基线（smc_atr200）
• objects 侧车数据：包含完整几何信息的结构事件，可直接用于图表叠加
  • swing_pivots（HH/HL/LH/LL）、swing_structures 和 internal_structures（BOS / CHoCH 事件，包含 pivot_time + confirm_time + bias）
  • equal_highs / equal_lows（流动性池水平）
  • order_blocks_swing / order_blocks_internal（每项都包含 top/bottom/anchor_time/bias/status: active|mitigated）
  • fair_value_gaps（字段结构与 OB 相同）
  • trailing_extremes：{top, top_label, bottom, bottom_label}，其中标签为 Strong High / Strong Low / Weak High / Weak Low 之一
  • premium_zone / equilibrium_zone / discount_zone（{top, bottom} 价格区间，分别对应摆动区间的顶部／中部／底部）
  • alerts_last_bar：布尔值字典，用于标记最近一根 K 线上触发的事件（例如 swing_bullish_choch、equal_highs、bullish_fair_value_gap）

SMC 字段语义（据此组织分析）

5 个部分输出的参考顺序：

1. 趋势偏向：比较 smc_swing_trend 和 smc_internal_trend。 同号 = 强趋势；异号 = 可能反转或处于区间震荡。
2. 最近的结构事件（查看 swing_structures / internal_structures 的最后一项）：它是 kind: BOS（趋势延续）还是 kind: CHoCH（趋势反转）？作为前瞻信号，CHoCH 的优先级高于 BOS。
3. 追踪极值标签：Strong High + Weak Low 同时出现 = 已确认的看跌结构（高点守住，低点易被跌破）；Strong Low + Weak High = 已确认的看涨结构。突破 Strong 枢轴是反转的结构确认信号。
4. 活动订单块：筛选 objects.order_blocks_*，仅保留 status: active。价格下方的看涨 OB = 潜在支撑。价格上方的看跌 OB = 潜在阻力。越接近当前价格，相关性越高。
5. 活动公平价值缺口（使用相同筛选条件）：由三根 K 线构成的不平衡区域，价格往往会回访／回补。
6. 相等高点／相等低点：止损集中的流动性区域，聪明资金往往会在反转前扫取这些区域。
7. 溢价／均衡／折价位置：当前价格处于哪个区域？看涨倾向的入场位于 discount；看跌倾向的入场位于 premium；处于 equilibrium 时则应观望。

注意事项（使用 SMC 分支时务必披露）

• 摆动枢轴仅在形成后经过 swing_size 根 K 线才会确认 （通常约为 50 根）；近期枢轴仍可能调整。
• 订单块是根据后续价格走势反向推断得出的；新形成的 OB 可能会因后续 K 线而修订。
• 在低波动率环境中，FVG 阈值更容易触发——应谨慎看待低波动率下的 FVG 数量。
• 所有事件都是结构信号，而非入场触发条件。它们可作为风险管理的补充，但不能取代风险管理。

交叉引用 ICT/SMC 知识库

每个 SMC 字段都直接映射到一张知识库概念卡。识别结构模式后，检索对应的概念卡以引用规则：

SMC 字段 / 事件	知识库概念
swing_structures with kind: BOS	break_of_structure
swing_structures with kind: CHoCH	change_of_character
order_blocks_*	order_block
fair_value_gaps	fair_value_gap
equal_highs / equal_lows	equal_highs / equal_lows
premium_zone / discount_zone / equilibrium_zone	premium_and_discount、equilibrium
trailing_extremes with Strong/Weak labels	strong_and_weak_highs_and_lows、protected_high_low
smc_atr200、smc_volatility、high_vol_bar	displacement

用户明确指定某个指标时

当且仅当用户消息中包含某个具体指标名称（无论缩写为何），才将该名称通过 --inds 传入：

<PYTHON> scripts/kb_klines.py indicators --query "BTC" --interval 1h --inds "<exact-name-user-said>" --format compact

对于多参数指标，使用紧凑格式 name:p1:p2（例如，名称后跟一个位置参数）；其余部分由服务端解析。

严格规则：

1. 不要预先获取用户未指定的任何指标。 不要主动用其他指标来“补充 SMC 解读”。
2. 不要向用户推荐具体的指标名称。 如果用户没有询问指标，就不要提及任何指标。在 ict_smc 分支中，SMC 指标足以作为结构层面的事实依据；它不能替代其他分析视角的原生分析器。
3. 仅限文本：指标输出以文字 / 表格形式呈现；图表渲染仅展示结构（来自 SMC objects sidecar 的 FVG/OB/Sweep 叠加层）。不要绘制振荡指标式的子面板。

图表编写（LLM 的职责很少）

对于 ict_smc 分支，kb_klines.py chart 会自动将 SMC 指标的结构叠加层填入 panels[0].items（BOS/CHoCH 标记、尾随极值标签、有效订单块、有效公允价值缺口、相等高点 / 低点、内部订单块和已缓解历史）。溢价 / 均衡 / 折价带为可选项，需使用 --include-zones。你无需编写矩形、标记或结构性水平线。

LLM 唯一需要编写的内容是交易设置水平线（入场 / 止损 / 目标位），在渲染时通过 --trade-setup PATH 传入：

{"items": [
  {"type": "hline", "value": 78500, "label": "Short 78500",
   "style": {"role": "entry_short", "width": 2}},
  {"type": "hline", "value": 80000, "label": "SL 80000",
   "style": {"role": "stop_loss", "dash": "dashed", "width": 2}},
  {"type": "hline", "value": 77000, "label": "T1 77000",
   "style": {"role": "target", "width": 2}}
]}

标签规则：最多 12 个字符，价格也计入其中。将理由（"entry at FVG mid"、"SL above 4h OB"）写在文字回复中，不要放在图表标签里。

交易设置的 style.role 值：entry_long、entry_short、stop_loss、target。

如果没有具体的交易价位需要绘制，就跳过交易设置文件——仅使用 SMC 结构叠加层也是有效的市场图表。

通用规则（适用于所有工作流）

1. 不得捏造 — 引用的每个价位都必须在图表中清晰可见，或通过将检索到的规则应用于可见价格计算得出。

2. 引用知识库 — 每个确认的形态都必须引用检索到的卡片。格式："Rule N of <concept>: '<rule text>' — visible at <evidence>"。

3. 语言规则：

   • 叙述语言应与用户输入一致：中文问题 → 中文叙述；英文问题 → 英文叙述
   • 无论叙述语言为何，技术术语均保留英文：FVG、Order Block、Breaker、CISD、OTE、Liquidity Sweep、Killzone、IFVG、MSS、BOS、CHoCH、Displacement 等。切勿翻译为“公允价值缺口”——保留“Fair Value Gap”或“FVG”
   • 数字／价格／百分比：保留原始格式

4. 明确说明不确定性 — 与其猜测，不如使用 null 或“uncertain — ”。

5. 可进行多次检索 — 对于复杂图表或涉及多个概念的问题，可使用不同的关键词组合多次运行 kb_retrieve.py。

6. 概率等级（5 个级别，仅用于语义表达） — 必须使用以下名称；不得向用户透露内部百分比：

   等级	中文	含义
   very_high	很高	主导情景；有强有力的规则依据确认
   high	较高	主要的合理情景；大多数规则均予以确认
   medium	中等	合理，但规则确认不完整
   low	较低	边缘情况；推测性较强
   very_low	很低	尾部风险；仅为完整起见而提及

7. 非交易内容 — 如果图像或问题与交易无关，请说明这一点并停止。

工具

使用上文定义的与宿主无关的占位符。OpenClaw 可从 {baseDir} 解析 <SKILL_ROOT>，Hermes 可从 ${HERMES_SKILL_DIR} 解析；在其他宿主上，从已加载的 SKILL.md 中解析。不要执行未定义的 ${SKILL_DIR} 变量，也不要假设虚拟环境位于 PATH 中。

工具	用途
scripts/kb_retrieve.py "<query>" --layer school --schools ICT SMC --top-k 5	默认／限定 School 的检索，从可溯源的 School 投影中检索
scripts/kb_retrieve.py "<query>" --layer evidence --sources <SOURCE>	精确的来源证据检索；可选与 --schools 和 --type 组合使用
scripts/kb_klines.py resolve "<name>"	自然语言名称 → 规范资产规格
scripts/kb_klines.py fetch --query "<name>" --interval <tf> --with-htf	从 Mobius API 获取真实 OHLCV（含 HTF）
scripts/kb_klines.py parse --input <file>	解析粘贴的 CSV／JSON／Markdown → 标准 OHLCV
scripts/kb_klines.py analyze --input <ohlcv.json>	提取特征（摆动／FVG／OB／扫流动性／位移／结构）。添加 --format json 可获取结构化特征和 suggested_overlay_items
scripts/kb_klines.py chart --query <name> --interval <tf>	获取 K 线，并为 ict_smc 路由自动填充 SMC 结构叠加层；使用 --no-auto-overlay 可创建空叠加层
scripts/kb_klines.py render --input <panels.json> --output <png>	通过 Playwright + lightweight-charts 将面板 JSON 渲染为 PNG（TradingView 级图表）
scripts/kb_klines.py indicators --query <name> --interval <tf>	默认：获取 SMC 结构指标（BOS／CHoCH、Order Blocks、FVG、等高／等低点、溢价／折价区、移动枢轴标签）。仅当用户明确指定某个指标时，才传入 --inds <exact-name>。仅输出文本，不会渲染到图表上。
scripts/kb_draw_annotation.py --json <path>	将注释 JSON 渲染到图表上（PIL，适用于用户上传的图像）
scripts/kb_phase_b_to_c.py --input <analysis.json> --image <png> --output <annotated.png>	将分析 JSON 转换为已注释图像（一步完成）
scripts/build_knowledge_v2.py	审核／导出确定性的 School 投影和精确来源证据
scripts/build_index.py	构建规范集合和独立嵌入的 v2 集合；未更改的 v2 文档会复用本地内容缓存
scripts/kb_doctor.py	环境健康检查（出现故障时运行）

scripts/kb_retrieve.py 的常用选项：

• --top-k N（默认值为 5）
• --type concept|case（按卡片类型筛选）
• --layer canonical|school|evidence（严格路由时，canonical 仅用于兼容）
• --schools <NAME...>（多值 OR 筛选；默认路由使用 --layer school --schools ICT SMC）
• --school <NAME>（单学校兼容形式）
• --sources <NAME...>（精确 OR 筛选；仅适用于 evidence 层）
• --exclude-schools <NAME...>（强制排除）
• --all-schools（显式执行不限范围的检索；绝不会自动回退使用）
• --search-mode auto|hybrid|semantic|lexical（v2 中，auto 使用 hybrid； lexical 不会加载嵌入模型）
• --max-per-canonical N（v2 默认值为 2；0 会禁用多样性限制）
• --list-schools / --explain-scope（不加载嵌入模型）
• --format markdown|json|compact