AI 分析编排包（@quantdo/tv-ai-orchestrator）

声明式、可取消、可整体清理的 MyTV AI 分析演示运行时。它只依赖宿主注入的工具执行器，不依赖 TradingView、MCP、WebSocket、DOM 或 UI 框架。页面可将它与 @quantdo/tv-tool-core 组合使用。

项目文档与问题反馈：GitHub · quantdo-tradingview-mcp · Issues。

安装

npm install @quantdo/tv-ai-orchestrator@^0.2.0

当前只提供 ESM 入口；随包提供 分析计划与 Orchestrator API。

步骤与对象

支持步骤：focus_range、create_drawing、create_study、focus_study、show_message、wait、focus_entity、emphasize_entity、restore_entity、reveal_drawing。单次分析默认最多 30 步，等待和步骤间隔最长 3 秒，不支持任意工具名或脚本执行。每个 create_drawing 必须包含 label；图上显示 A1/A2… 编号短标签，近价位进一步缩为编号，status.annotations/status.entities 保留完整语义。show_message.entityKeys 可引用前面创建的绘图或指标 key，show_message.metricKeys 可引用本计划携带的数值指标；状态中的 evidenceEntityIds / evidenceMetricKeys 供宿主突出结论证据。计划在播放前校验所有 key。绘图动画步骤仍只接受绘图 key；focus_study 只接受先前创建的指标 key。TradingView 原生 price_label 只能显示价格，其语义留在图例。

一键速览与数据依据

get_indicator_metrics 是只读关键数据入口：编排器通过注入的 get_chart_snapshot 取得可见 K 线，独立计算 EMA20/50、均线结构、RSI14、MACD 柱、随机指标 K/D、CCI20、ATR14、布林位置、布林带宽、量比和 OBV 趋势。每项结果包含 category（trend / momentum / volatility / volume）、数值、状态和方向；不输出买卖建议或综合评分。analyze_chart 是简化的可视速览入口，复用同一批计算结果写入 status.metrics，并在开始播放前复核短时效 snapshotId。status.sourceObservedAt 表明分析依据的时间；播放开始后的 Tick 不会自动重算历史锚点。自定义计划可选传 expectedSnapshotId，但由外部 AI 负责在失效后重新计算点位。传 awaitCompletion: true 可等待最终状态；MCP 一键入口默认采用此模式，后续步骤失败会返回错误。少于 10 根有效 K 线时明确报错，不猜测点位；高低点标注只表示历史观察，不是已确认支撑/阻力。

focus_range 和 focus_entity 可传 transitionMs（0–1800，默认 600；0 表示立即切换）。编排器只传递镜头意图，具体缓动、减少动画和手动接管由图表宿主实现；独立 Tool Core 的原子 set_visible_range 不受影响。

指标知识与专业组合

get_indicator_knowledge 提供 25 项常用指标知识，覆盖趋势、动能、波动和量能四类，包含别名、用途、默认参数、解读规则、风险提示、宿主指标名称和可关联的计算 metric key。它是受限知识元数据，不取代宿主实时 get_study_catalog。

list_indicator_combinations 返回六套组合：趋势跟随、动能反转、波动突破、量价确认、均值回归和多因子结构。present_indicator_combination 会先核对宿主指标目录，再创建组合指标、逐项执行 focus_study，最后把结论的 entityKeys 绑定到全部已创建指标。宿主可将焦点步骤实现为副图选中、图例高亮、转场暗角和减少动画兼容；不支持的宿主可保留显示/前置和页面高亮，不应伪造原生副图能力。

模板与播放控制

内置 trend、range、breakout、volume 四类模板。调用 list_analysis_templates 查看列表，preview_analysis_template 校验参数并返回计划，present_analysis_template 播放。必须提供 analysisId、from、to、support、resistance；MCP 还要求 expectedSymbol、expectedResolution。播放器另支持暂停/继续、单步、跳过、调速、重播、从指定步骤重播、取消和清理。自定义播放先返回 running，可调用一次 await_analysis 等待最终结果。若图表合约/周期改变，旧计划不再写入新图表，也不在新图表盲目清理旧对象；切回原目标后可清理。其他失败时自动尝试清理。

宿主接入示例

import { createAnalysisOrchestrator } from "@quantdo/tv-ai-orchestrator";

const orchestrator = createAnalysisOrchestrator({
  tools: core,
  onEvent(event) {
    renderAnalysisProgress(event.status);
  }
});

await orchestrator.execute("present_analysis", {
  analysisId: "ag-demo-1",
  title: "白银趋势分析",
  expectedSymbol: "SHFE:AG2610",
  expectedResolution: "60",
  steps: [
    { type: "focus_range", from: 1790000000, to: 1790100000 },
    { type: "show_message", text: "正在标记压力区域" },
    {
      type: "create_drawing",
      label: "关键阻力区 15,600–15,800",
      drawing: {
        shape: "rectangle",
        points: [
          { time: 1790000000, price: 15600 },
          { time: 1790100000, price: 15800 }
        ],
        style: { color: "#f2c94c", backgroundColor: "#3a3214", transparency: 82 }
      }
    }
  ]
});

宿主还需用 onEvent 渲染进度、图例和结论，用自己的图表能力实现镜头与动效；本包仅传递语义步骤。示例时间/价格只展示参数格式，不是可直接用于实盘分析的点位。

开发验证与限制

cd tv-ai-orchestrator
npm install
npm test
npm pack --dry-run
npm run release:check

npm test 包含 TypeScript 构建与播放器、模板、清理和失败路径测试。prepack 在真实打包前构建；release:check 检查三个包的实际 tarball 安装、ESM 导入、类型和浏览器打包。当前使用 MIT 许可证；完整 API 见 docs/API.md。分析状态目前仅在当前页面内存中，刷新后不恢复；未来自研图表的跨宿主呈现尚未验收。不要把本包的演示步骤、动效或已观察高低点描述成自动交易建议。