---
name: smartchart
description: SmartChart 数据平台统一入口。当用户需要查询数据集、写入数据、更新数据、列出可用数据集、生成仪表盘或报表 HTML、生成可拖拽布局页面、生成需求系统页面，在本机安装 / 部署 / 启动 / 升级 SmartChart，把生成的 HTML 同步到本地仪表盘。触发词：SmartChart、数据集查询、数据写入、数据更新、仪表盘、报表 HTML、可拖拽大屏、拖拽布局、系统页面、需求系统、安装 smartchart、同步到本地仪表盘、更新本地报表、改本地仪表盘、基于 smartchart 建项目、Django 项目初始化。
---

# SmartChart 数据服务

通过 API 接入 SmartChart 服务器，直接操作数据集（查询 / 写入 / 更新），并可生成 HTML；必要时还可在用户本机安装并托管一份本地 SmartChart。

## 先分流：用户到底要什么

| 用户诉求 | 走哪条 |
|---|---|
| 查数据 / 写数据 / 建看板 HTML / 做系统页面 | 下面「命令速查」「HTML 生成」 |
| 在本机装一份 SmartChart、离线版、本地部署、启停 / 升级 | **读 `references/local-install.md`**（脚本 `scripts/local_setup.py`） |
| 把生成的 HTML 同步进仪表盘（本地实例，或自建项目） | **读 `references/local-dashboard.md`**（脚本 `scripts/local_dashboard.py`） |
| 基于 SmartChart 开发 / 初始化一个自己的 Django 项目 | **读 `references/project-init.md`**（脚本 `scripts/init_project.py`） |

> 本机安装、仪表盘同步、项目初始化都不在本文件展开，**动手前先读对应的 references**。

## 运行环境

脚本仅依赖 Python 3 标准库。占位符（`{SKILL_DIR}` = 本 skill 根目录）：

- `{PY}` → `python3`
- `{SCRIPT}` → `{SKILL_DIR}/scripts/smartchart_client.py`

## 首次使用（配置缺失时才引导）

配置与注册表**分层存储**：用户级 `~/.smartchart/`（默认，跨项目），项目级 `<项目根>/.smartchart/`（覆盖）。
解析优先级：**显式 `--config`/`--datasets` > 项目级 > 用户级**。

1. **配置** `config.json`：`base_url`、`visitor`、`secret_key`（均必填）。缺失则询问用户写入用户级，再 `{PY} {SCRIPT} ping` 验证。
2. **注册表** `datasets.json`：`{"datasets":[{"id":123,"name":"","description":"","operation":"query","params":{},"fields":[],"notes":""}]}`，`operation` ∈ `query`/`write`/`update`。缺失则逐个引导注册（ID、名称、用途、描述、参数、字段）。

**使用流程**：读注册表 → 按 `description`/`operation` 匹配意图 → 按 `params` 补齐参数 → 调对应 API。数据集不在注册表时询问是否新增。

## 命令速查

```bash
{PY} {SCRIPT} ping                                                  # 连通性
{PY} {SCRIPT} list-datasets                                          # 列出数据集
{PY} {SCRIPT} query-post --dataset <ID> --param '{"参数A":"值"}'      # 查询：返回二维数组，首行表头
{PY} {SCRIPT} write  --dataset <ID> --ds '[["__字段A","B"],["a1","b1"]]'  # 写入：二维数组 + __表头
{PY} {SCRIPT} update --dataset <ID> --ds '[{"id":1,"name":"新值"}]'   # 更新：字典数组 + 主键
{PY} {SCRIPT} ask --dataset <路由ID> --prompt "自然语言问题"           # 智能问数（自动二次调用）
{PY} {SCRIPT} add-dataset --id <ID> --name "名" --desc "描述" --operation query
{PY} {SCRIPT} remove-dataset --id <ID>
```

**大数据**：行数 > `--threshold`（默认 100）自动落盘到 `smartchart_results/`，只输出「摘要 + 路径」。**绝不把数据行复制回对话**，分析时用 Read 读文件或脚本统计。

> 分页、落盘选项、`ask` 路由、Python 模块、返回格式、数据集管理 → 见 **`references/api-reference.md`**。

## HTML 生成

**先判断用户要哪一类**：

| 用户诉求 | 产物 | 数据怎么来 |
|---|---|---|
| 看板 / 报表 / 仪表盘 / 分析 | 看板 demo（纯展示） | 数据内嵌 `ds` 变量 |
| 系统 / 需求系统 / 页面 / 功能 | 系统页面（有查询 + 提交，可直接复制进 SmartChart 跑） | `ds_refresh` / `ds_save` 占位接口 |
| 任一类中出现「可拖拽 / 拖拽布局 / 自由布局 / 大屏可编辑」 | 在上面任一类基础上叠加**拖拽布局模式**（`smtdrag` + `start_drag` 回写块） | 同对应类型 |

**两类通用禁止**：不做后端 / 代理；**浏览器端不写 `fetch` 调 API**；密钥绝不进前端。

**系统页面接入层只有两个同步占位函数**（业务代码只调这两个）：

```js
const DS = { orders: 601, workers: 602 };             // 数据集 ID 集中管理
let data = ds_refresh(id, param, 'list');             // 查询：同步返回二维数组；无参时 param 传 null
let res  = ds_save(id, content, mode);                // 提交：mode 0=写入(__表头二维数组) / 1=更新(主键字典数组)
```

> 完整规范、代码模板、渲染 → 见 **`references/html-guide.md`**。

## 参考文件（按需读取）

| 文件 | 何时读 |
|---|---|
| `references/api-reference.md` | 需要分页 / 落盘 / 路由 / Python 调用 / 返回格式等 API 细节时 |
| `references/html-guide.md` | 要生成看板 demo 或系统页面 HTML 时 |
| `references/drag-layout.md` | 用户要求组件可拖拽 / 自由布局 / 大屏可编辑时（必读，含硬性结构约定） |
| `references/local-install.md` | **在本机安装 / 部署 / 启动 / 升级 SmartChart，或要桌面一键启动方式时（必读）** |
| `references/local-dashboard.md` | **要把生成的 HTML 写进本地仪表盘，或要修改本地已有仪表盘时（必读）** |
| `references/project-init.md` | **要基于 SmartChart 新建 / 初始化一个 Django 项目（要自己的 app、settings、urls）时（必读）** |