DTS SDK API 文档（fdapi）

让 AI 不只回答“怎么做”，而是能够理解业务意图、选择真实接口、生成可执行代码，并驱动 DTS Cloud 中的真实三维场景。

fdapi（DigitalTwinAPI）是 DTS Cloud 的场景执行层。网页通过 DigitalTwinPlayer 接收云渲染视频流，AI 或业务代码通过 fdapi 控制相机、标注、图层、模型、天气、空间分析和行业仿真。

DTS AI 核心能力

在 DTS 的 AI 能力体系中，fdapi 是目前覆盖范围最广、执行深度最强的场景能力底座。CloudMaster MCP 负责“服务和工程能否运行”，fdapi 负责“场景里具体发生什么”。

查看 fdapi 源码与完整文档

为什么 fdapi 是 DTS AI 的核心

一般的 SDK 文档只回答“某个方法怎么调用”。fdapi 文档工程进一步为 AI 补齐了从业务语言到真实执行的完整链路：

1. 理解业务：把“园区告警”“洪水推演”“车辆巡检”等行业语言映射到 API 类和方法。
2. 检索知识：通过业务场景 Skill、行业方案和 AI 可读全文索引定位能力。
3. 约束生成：向模型注入真实方法签名、参数顺序、类型和示例。
4. 检查结果：用完整 API 白名单识别不存在的方法，拦截臆造调用。
5. 执行场景：在 DigitalTwinPlayer 的 onReady 之后调用 fdapi。
6. 闭环验收：结合回调、事件、日志和视频流检查执行结果，而不是只看代码文本。

自然语言需求
  → 行业方案 Skill
  → API 类业务场景 Skill
  → 真实签名 / 参数元数据 / 真实示例
  → AI 生成与白名单校验
  → DigitalTwinPlayer + fdapi
  → DTS Cloud 场景执行
  → 回调 / 事件 / 日志 / 视频流验收

能力规模

以下数据来自当前文档工程和生成产物的实际统计：

内容	当前规模	对 AI 的价值
fdapi 命名空间	70 个	支持按能力域检索和调用
可调用方法签名	1,242 个	为代码生成提供真实方法与参数约束
带“业务场景 Skill”的 API 类	81 个	将接口语言翻译为业务语言和行业别名
行业方案	17 个方向	将成套需求映射为多接口组合
真实示例	1,652 个	投影场景 1,014 个，球面场景 638 个
API Markdown 文档	83 个文件	类、方法、参数、类型和示例的检索语料
教程与方案文档	49 个文件	覆盖入门、数据、部署、性能和行业实践

统计用于说明当前知识覆盖规模，不代表所有接口在每个 DTS Cloud 版本、许可证和工程中都可用。运行时应以实际 SDK 版本与授权结果为准。

AI 可以驱动哪些场景能力

能力域	代表对象	可以完成的工作
场景理解	InfoTree、Settings、Coord	获取工程信息、读取图层树、识别坐标系并转换坐标
相机与叙事	Camera、CameraTour	定位、环绕、跟随、巡游、关键帧导览和视频导出
标注与交互	Marker、Marker3D、CustomTag	设备点位、告警标签、三维文字、信息弹窗和交互事件
矢量与空间表达	Polyline、Polygon、Polygon3D、ODLine	道路、轨迹、边界、地块、体块和流向关系
图层与数据接入	TileLayer、GeoJSONLayer、Cesium3DTileset、ImageryLayer	加载 3DT、GeoJSON、3D Tiles、影像和地形数据
模型与动态对象	CustomObject、CustomMesh、GaussianSplatting	加载模型、控制姿态与运动、构造网格、展示 3DGS
环境与视觉效果	Weather、HeatMap、Light、VideoProjection	雨雪雾、昼夜、热力图、灯光、视频投影和全景融合
水利与海洋	FloodFill、HydroDynamic2D、Fluid、VectorField	淹没分析、水动力回放、流体、水流场和海洋场可视化
交通与运动仿真	Vehicle、Train、Drone、TrafficSimulation	车辆、轨道交通、无人机、路径运动和交通流仿真
专业分析与推演	Tools、ExcavationAnalysis、FiniteElement、BattlefieldSimulation	量算、开挖分析、有限元结果、态势标绘和战场推演
信号与覆盖	Antenna、Beam、SignalWave	天线方向图、波束扫描和信号传播范围展示

这些能力不是静态页面组件，而是可以组合、执行并从真实视频流中观察结果的三维场景动作。

面向 AI 设计的知识结构

1. API 类业务场景 Skill

81 个 API 类文档均提供“业务场景 Skill”，不只写方法定义，还包含：

• 功能在数字孪生业务中的定位；
• 行业人员常用的别名和不同叫法；
• 适用行业与典型业务场景；
• 性能、坐标系、授权和版本注意事项；
• 可直接检索的方法、参数和示例。

它让 AI 能把“高亮事故影响区域”理解为 HighlightArea，把“车辆沿路线巡检”映射到 Vehicle 或 CustomObject，而不是要求用户先知道类名。

2. 行业方案 Skill

行业方案解决的是“一个完整业务需求需要组合哪些接口”，目前覆盖 17 个方向：

• 城市与空间：CIM 基础平台、智慧社区、智慧园区、实景三维与测绘；
• 交通出行：智慧交通、轨道交通、港口航道与海洋；
• 建筑与工程：智慧建筑、智慧工地、智慧工厂；
• 资源能源：石油化工与油气田、智慧矿山、地下综合管线；
• 水利生态：智慧水利水务；
• 公共服务：智慧校园、智慧文旅与景区、人防应急指挥。

单类 Skill 解决“这个接口是什么”，行业方案 Skill 解决“这一整套业务如何落到接口组合”。

3. AI 可直接消费的工程资产

资产	用途
llms.txt	文档导航、摘要与 AI 检索入口
llms-full.txt	单文件全文知识，适合长上下文或离线索引
dts-sdk.d.ts	TypeScript 类型声明和编辑器类型检查
api-completions.js	1,242 个真实可调用签名和补全信息
param-meta.js	参数类型、必填项和默认值元数据
real-examples.js	投影与球面两套真实示例库
API / 教程 Markdown	RAG、Agent、Skill 和人工阅读的统一知识源

防止 AI 臆造接口

fdapi 调试台内置的 AI 助手实现了三层约束：

1. 按需注入真实签名：从中文意图识别相关命名空间，只注入最相关的签名，控制上下文规模。
2. 全量白名单校验：以文档生成的 API 补全数据和真实示例为准，判断调用是否存在。
3. 生成后拦截：扫描生成代码中的 fdapi.* 调用；发现不存在的方法时，不把错误代码直接交给用户执行。

这套防幻觉机制是 fdapi 文档工程内置 AI 助手的实现。其他 AI 客户端接入 fdapi 文档时，也应复用同类约束，而不能仅靠一段通用提示词保证准确性。

从零接入 DTS Cloud

前置条件

• DTS Cloud 服务已运行，并存在可用的工程和渲染实例；
• 页面已引入与目标环境匹配的 ac.min.js 和 ac_conf.js；
• 已确认服务地址、工程 ID、实例 ID 和必要的访问参数；
• 已确认工程坐标系以及要传入的坐标类型。

创建播放器并取得 fdapi

const host = '127.0.0.1:8080';

const player = new DigitalTwinPlayer(host, {
  domId: 'player',
  // iid: 1,
  // pid: 5,
  apiOptions: {
    onReady: () => {
      const fdapi = player.getAPI();
      console.info('fdapi ready', fdapi.getVersion());
      // 只有从这里开始，才能安全调用场景 API。
    },
    onLog: (message) => console.info('[DTS]', message),
    onEvent: (event) => console.info('[DTS event]', event),
  },
});

onReady 是关键边界：播放器对象已创建不等于 API 已就绪。AI 生成的代码也必须遵守这个调用时机。

让相机定位到目标

fdapi.camera.lookAt(
  13522330.1, 3661827.7, 20,
  800, -45, 15, 2,
  () => console.info('相机定位完成'),
);

添加业务标注

fdapi.marker.add({
  id: 'alarm-001',
  groupId: 'alarms',
  coordinate: [13522330.1, 3661827.7, 35],
  coordinateType: 0,
  imageSize: [48, 48],
  imagePath: HostConfig.Path + '/locale/zh/images/tag.png',
  anchors: [-24, 48],
  text: '设备温度告警',
  fontSize: 22,
  fontColor: Color.White,
  showLine: true,
}, () => console.info('标注创建完成'));

示例中的坐标只是结构演示。实际执行前必须读取工程坐标系，并确认位置、资源路径和对象 ID。

推荐的 AI 使用层级

只读咨询

适合了解能力、查询接口、解释参数和生成实现方案：

我的工程是 EPSG:3857。请查询 fdapi 文档，说明如何添加一个可点击的设备告警标注；先不要执行。

生成可审阅代码

适合输出可复制的 JavaScript，并要求 AI 标出不确定项：

请根据真实 fdapi 签名生成车辆沿闭环路线运动并由相机跟随的代码。列出需要我确认的坐标、模型路径和对象 ID，不要臆造参数。

连接真实场景执行

适合在已经确认环境和变更范围后执行：

先读取工程坐标系和当前对象状态。执行已确认的标注与相机代码，然后检查回调、接口日志和视频画面；任何一步失败都停止后续写操作。

专业工作流应把“生成”和“执行”分开：先产出草案，明确坐标、对象 ID、资源路径和影响范围，再由用户确认写操作。

与 CloudMaster MCP 组合

DTS CloudMaster MCP 与 fdapi 不是重复能力，而是上下两层：

层级	负责内容
CloudMaster MCP	服务状态、授权、服务启停、工程注册、视频流/API 页面
DigitalTwinPlayer	建立浏览器视频流、输入和事件通道
fdapi	控制场景内相机、标注、图层、模型、天气、分析和仿真

推荐完整链路：

生成并验证 DTML
  → CloudMaster MCP 添加工程
  → 打开视频流并确认播放器就绪
  → fdapi 读取工程与坐标系
  → AI 生成并审阅场景动作
  → 明确确认后执行
  → 用回调、日志、事件和视频画面验收

这条链路让 AI 从“会回答 DTS 问题”升级为“能在安全边界内操作和验证数字孪生场景”。

版本、授权与运行边界

• fdapi 文档覆盖面很广，但具体方法是否可用取决于 DTS Cloud / SDK 版本、工程类型和授权。
• coordinateType 常见约定为：0 投影、1 WGS84、2 GCJ02、3 BD09；仍应读取工程实际坐标系。
• 大量对象更新应使用 updateBegin()、多次 update()、updateEnd(callback)，减少调用往返。
• 接口返回成功不等于业务结果正确；必须检查目标对象、回调、事件和真实画面。
• 涉及工程、场景对象和服务状态的写操作，应先说明目标、影响和恢复方式。
• 高级仿真、数据格式和导出能力可能受许可证限制，不能只凭文档名称判断可用性。

调试台与安全

fdapi 源码仓库包含基于 Docusaurus 3 的调试台，可连接 DTS Cloud 视频流、运行 JavaScript、回放 JSON 接口日志，并提供代码补全和真实示例导航。

• 调试台可配置多种 AI 提供商；密钥由浏览器直接使用并保存在本地存储，不经过该文档站服务端。
• 不要在共享电脑或公开演示环境中保存生产密钥。
• 不要分享包含 password、实例信息或内部地址的调试链接和截图。
• ac.min.js、ac_conf.js 应来自目标 DTS Cloud 安装环境，并与实际版本匹配。
• 当前 GitHub Pages 站点尚未形成可用的公开入口，因此以源码仓库和本机运行结果为准。

当前验证状态

项目	状态
GitHub 仓库	公开，可访问
当前分支	master
已核对提交	7d3b88e2fae2827619ee0d3b0d4f438b8001b419
提交日期	2026-08-08
文档完整性	源码包含 UTF-8、front matter、链接和生成产物检查
AI 防幻觉实现	已在调试台源码中核对真实签名注入、白名单和生成后拦截逻辑
全接口运行验收	未逐项执行；需在目标 DTS Cloud 版本、工程与授权环境中验证

入口

• fdapi GitHub 源码仓库
• 当前核对提交
• DTS CloudMaster MCP