# thingx-ai-composite-chart

**Repository Path**: ai-chart/thingx-ai-composite-chart

## Basic Information

- **Project Name**: thingx-ai-composite-chart
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-04
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# thingx-composite-chart

`thingx-ai-composite-chart` 目前是一个依赖外部 assets + runtime 工作区的独立工作区，但对外部仓库的访问已经收口到 `src/chart-core/` 这个历史命名的桥接层。

## 桥接层

业务目录：

- `src/consumer`
- `src/planner`
- `examples/chart-ai-mvp`
- `review`

这些目录现在只允许通过 `src/chart-core/` 访问外部 assets/runtime 依赖，不再直接引用外部仓库内部文件路径。目录名虽然仍叫 `chart-core`，但当前语义已经收敛为 `runtime + assets` 接线层。

当前桥接入口：

- `src/chart-core/paths.js`
  - `resolveAssetsRoot()`
  - `resolveRuntimeRoot()`
  - `resolveCatalogPath()`
  - `resolveCatalogInputPath()`
  - `resolveExistingCatalogPath()`
  - `resolveChartResourcesPath()`
  - `resolveAssetRuntimeManifestPath()`
  - `resolveConchRuntimePath()`
  - `resolveEnvLabLocalCandidatePaths()`
- `src/chart-core/resource-ai-engine.js`
  - 桥接 `packages/resource-ai-engine/index.js`
- `src/chart-core/toolchain-preview-legacy.js`
  - 桥接 `packages/toolchain/src/legacy/preview-cht.js`

## UI Facade

当前仓库已提供一层面向 future `thingx-ai-composite-chart-ui` 的最小 facade，位置在 `src/facade/`。

当前 facade 只暴露这几类能力：

- `generateComposite`
  - 组合生成入口
- `getLastCompositeResult`
  - 最近一次组合结果读取
- `getCompositeSnapshot`
  - 当前组合状态快照
- `types`
  - 面向 UI 的结果 DTO / 状态门面

当前 UI 可稳定依赖的结果语义收口为：

- `runId`
- `status`
- `phase`
- `summary`
- `template`
- `selectedModules`
- `panes`
- `diagnostics`
- `selectionHints`
- `aiSelectionHints`
- `aiSelectionApplied`

这层 facade 不包含：

- preview 结果
- export bundle
- 下载地址
- 预览页 URL
- server/static host 协议
- runtime / assets 路径细节

也就是说，future UI 应优先依赖 `src/facade/`，而不是直接依赖 example adapter / orchestrator / server。

## 联调公开输入

当前新工程联调时优先识别这一组环境变量：

- `THINGX_AI_CHART_ASSETS_ROOT`
  - assets 仓库根目录
- `THINGX_AI_CHART_RUNTIME_ROOT`
  - runtime 仓库根目录
- `CATALOG_PATH`
  - catalog 文件路径
- `ASSET_RUNTIME_MANIFEST_PATH`
  - assets manifest 文件路径
- `CHART_RESOURCES_PATH`
  - assets 的 `chartResources/`
- `CONCH_RUNTIME_PATH`
  - runtime 的 `packages/toolchain/runtime/conch.js`
- `.env.lab.local`
  - 仅作为 AI MVP 的环境变量来源，候选位置由桥接层统一提供

## 默认行为

- `CATALOG_PATH` 未设置时，默认从 `THINGX_AI_CHART_ASSETS_ROOT` 推导 `scripts/chart-catalog/output/chartResources.catalog.json`。
- `ASSET_RUNTIME_MANIFEST_PATH` 未设置时，默认从 `THINGX_AI_CHART_ASSETS_ROOT` 推导 `scripts/chart-catalog/output/asset-runtime-manifest.json`。
- `CHART_RESOURCES_PATH` 未设置时，默认从 `THINGX_AI_CHART_ASSETS_ROOT` 推导 `chartResources/`。
- `CONCH_RUNTIME_PATH` 未设置时，默认从 `THINGX_AI_CHART_RUNTIME_ROOT` 推导 `packages/toolchain/runtime/conch.js`。
- `THINGX_AI_CHART_ASSETS_ROOT` 未设置时，桥接层优先尝试当前工作区同级目录 `../thingx-ai-chart-assets`。
- `THINGX_AI_CHART_RUNTIME_ROOT` 未设置时，桥接层优先尝试当前工作区同级目录 `../thingx-ai-chart-runtime`。
- AI MVP 启动时会按桥接层给出的候选顺序尝试加载 `.env.lab.local`：
  1. 当前工作区根目录
  2. `THINGX_AI_CHART_RUNTIME_ROOT` 对应的 runtime 根目录
  3. `THINGX_AI_CHART_ASSETS_ROOT` 对应的 assets 根目录

如果你希望避免任何隐式定位，直接显式设置上面这组六个环境变量即可。

## 最小运行命令

```bash
npm run mvp:start
```

如果 assets/runtime 不在当前工作区同级目录，先显式设置依赖输入：

```bash
THINGX_AI_CHART_ASSETS_ROOT='/path/to/thingx-ai-chart-assets' \
THINGX_AI_CHART_RUNTIME_ROOT='/path/to/thingx-ai-chart-runtime' \
CATALOG_PATH='/path/to/thingx-ai-chart-assets/scripts/chart-catalog/output/chartResources.catalog.json' \
ASSET_RUNTIME_MANIFEST_PATH='/path/to/thingx-ai-chart-assets/scripts/chart-catalog/output/asset-runtime-manifest.json' \
CHART_RESOURCES_PATH='/path/to/thingx-ai-chart-assets/chartResources' \
CONCH_RUNTIME_PATH='/path/to/thingx-ai-chart-runtime/packages/toolchain/runtime/conch.js' \
npm run mvp:start
```

## 最小验证命令

桥接健康检查：

```bash
npm run validate:bridge
```

选材验证：

```bash
npm run validate:selection
```

如果默认同级 repo 定位不可用，`validate:selection` 与 `validate:e2e` 一样需要显式提供这组环境变量。

```bash
THINGX_AI_CHART_ASSETS_ROOT='/path/to/thingx-ai-chart-assets' \
THINGX_AI_CHART_RUNTIME_ROOT='/path/to/thingx-ai-chart-runtime' \
CATALOG_PATH='/path/to/thingx-ai-chart-assets/scripts/chart-catalog/output/chartResources.catalog.json' \
ASSET_RUNTIME_MANIFEST_PATH='/path/to/thingx-ai-chart-assets/scripts/chart-catalog/output/asset-runtime-manifest.json' \
CHART_RESOURCES_PATH='/path/to/thingx-ai-chart-assets/chartResources' \
CONCH_RUNTIME_PATH='/path/to/thingx-ai-chart-runtime/packages/toolchain/runtime/conch.js' \
npm run validate:selection
```

端到端验证：

```bash
THINGX_AI_CHART_ASSETS_ROOT='/path/to/thingx-ai-chart-assets' \
THINGX_AI_CHART_RUNTIME_ROOT='/path/to/thingx-ai-chart-runtime' \
CATALOG_PATH='/path/to/thingx-ai-chart-assets/scripts/chart-catalog/output/chartResources.catalog.json' \
ASSET_RUNTIME_MANIFEST_PATH='/path/to/thingx-ai-chart-assets/scripts/chart-catalog/output/asset-runtime-manifest.json' \
CHART_RESOURCES_PATH='/path/to/thingx-ai-chart-assets/chartResources' \
CONCH_RUNTIME_PATH='/path/to/thingx-ai-chart-runtime/packages/toolchain/runtime/conch.js' \
npm run validate:e2e
```

## 维护约束

- 业务代码不要直接引用 runtime / assets 内部 `packages/*` 路径。
- 新增外部依赖时，先在 `src/chart-core/` 这个接线层增加桥接，再让业务代码依赖桥接层。
- 用 `npm run validate:bridge` 检查是否重新引入旧绝对路径、旧 `THINGX_CHART_CORE_ROOT` 或直连外部内部路径。