SmartChart 数据服务

通过 API 接入 SmartChart 服务器，直接操作数据集（查询 / 写入 / 更新），并可生成 HTML。

运行环境

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

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

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

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

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

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

命令速查

{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 占位接口 |

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

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

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 时 |