图表工具核心包（@quantdo/tv-tool-core）

本包把 AI 可用的图表操作定义成受限的语义工具，负责工具定义、JSON Schema、参数验证、统一错误、Chart Adapter 接口和 TradingView-compatible 适配。宿主必须显式注入 Widget 或自己的 Adapter；本包不连接 MCP/WebSocket，不持有行情源，也不操作页面 DOM。可独立安装，页面可替换为自研图表宿主。

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

安装

npm install @quantdo/tv-tool-core@^0.2.0

当前只提供 ESM 入口，不承诺 CommonJS require。本包的 Core API 与宿主接入 随 npm tarball 一起发布。

最小接入

import {
  createTradingViewChartAdapter,
  createTvToolCore,
  type ChartContext,
  type ChartSnapshot,
  type DrawingSummary,
} from "@quantdo/tv-tool-core";

const adapter = createTradingViewChartAdapter(widget, {
  title: document.title,
  getVisibleBars: readVisibleBars,
});
const core = createTvToolCore(adapter);

const context = await core.execute("get_chart_context") as ChartContext;
const snapshot = await core.execute("get_chart_snapshot") as ChartSnapshot;
const first = snapshot.bars.at(-2);
const last = snapshot.bars.at(-1);
if (!first || !last) throw new Error("可见 K 线不足，无法计算趋势线锚点");
const drawing = await core.execute("create_drawing", {
  expectedSymbol: context.symbol,
  expectedResolution: context.resolution,
  expectedSnapshotId: snapshot.snapshotId,
  shape: "trend_line",
  points: [
    { time: first.time, price: first.low },
    { time: last.time, price: last.high },
  ],
  text: "趋势线",
}) as DrawingSummary;
console.log(drawing.id);

示例只是展示从同一快照提取锚点的格式，不代表这两个点具有趋势意义。真实分析必须按用户任务定义计算规则。readVisibleBars 由宿主实现；时间是 Unix 秒，价格为有限正数，不能传屏幕像素坐标。

能力与边界

| 领域 | 当前能力 | |---|---| | 图表状态 | 上下文、运行时能力、可见 K 线、短时效快照、可见区间设置 | | 合约 | 宿主可注入搜索与精确切换；Core 不连接具体行情源 | | 绘图 | 激活交互工具；创建、列表、修改、删除指定图形 | | 指标 | 查询宿主目录；创建、列表、更新、临时聚焦和删除宿主已注册的 study |

支持的绘图白名单包括趋势线、射线、水平/垂直线、箭头、旗标、文字、价格标签、矩形、斐波那契回撤、平行通道及多空仓位，共 15 种。可用样式包括颜色、线宽/线型、填充、透明度、文字、锁定与层级。未验证的形状和任意脚本执行不开放。

get_study_catalog 优先通过当前 Widget 的 getStudiesList() 返回运行时支持的全部指标，可选 query 按名称搜索；没有此 API 的宿主仍可显式注入目录。当前 Demo 实测返回 106 项，其中 MA、EMA、RSI、MACD、成交量、布林带、ATR、随机指标、CCI、OBV 共 10 项附带经过创建与回读的标签、默认输入和窗格提示；其他项按 Widget 的原名列出，pane: auto 表示由图表决定位置，不代表已逐项验证其参数。create_study 接受宿主支持的指标名称，目录不是强制白名单。focus_study 确保目标指标可见、前置，并在宿主支持 selection API 时临时选中；否则安全降级。Adapter 从 live study 的 getInputsInfo() 映射 length、period 等友好字段到真实 input ID，并在写入后回读；无法解析时返回错误并尝试撤销新建指标。Core 不执行 Pine、JavaScript 或任意代码。

get_chart_snapshot 在读取可见 K 线前后核对合约、周期和范围，返回 context、bars、snapshotId、观测/过期时间等。数据派生写入可传 expectedSnapshotId；数据、可见范围变化或超过 60 秒时会拒绝旧点位。此指纹是数据一致性保护，不是授权凭据。创建后回读或层级设置失败时会尝试移除新对象；更新过程的完全原子性仍在完善。

价格标签兼容性

当前 TradingView 宿主的 price_label 使用 createMultipointShape([point], options)，原生显示价格。向它传自定义 text 会抛 Value is undefined，所以 Adapter 不把自定义文字转发给该形状；语义名称由宿主的分析图例展示。其他形状的原生文字由 Adapter 按类型映射。换图表宿主时应重新验证具体能力，不应照搬 TradingView 的行为。

新图表宿主接入

自研图表可实现公开的 TvChartAdapter 接口，然后传给 createTvToolCore(adapter)；不要把图表 API 写进 MCP 网关。Node.js 开发测试可从 @quantdo/tv-tool-core/contract 导入 verifyAdapterContract(createCore, adapterFactory)，复用当前内存宿主与 TradingView-compatible 模拟宿主运行的语义契约。工厂需返回隔离实例及契约规定的固定数据；该子路径只供 Node.js 测试，不要打入浏览器运行时。

开发验证

cd tv-tool-core
npm install
npm test
npm pack --dry-run
npm run release:check

npm test 包含 TypeScript 构建与契约测试；prepack 确保真实打包前先构建。npm pack --dry-run 只预览包内容，npm run release:check 还会安装三个实际 tarball 并检查 ESM、类型和浏览器打包。当前采用 MIT 许可证；包内完整 API 见 docs/API.md。本仓库发布清单不包含在 npm 包内。