skill-template/references/DATA_SOURCES.md

多数据源声明（SQLite / MySQL 云库）

本文说明技能如何向匠厂宿主声明业务数据库，以及技能 CLI / Action 如何与宿主读写同一物理库。

产品定位： 默认仍是本地 SQLite（{skill_slug}.db）。需要多用户共享、集中运维或云库时，可显式声明 MySQL。UI / API 契约不变；_jiangchang_* 展示元数据仍写在同一逻辑库中。

宿主版本： 匠厂 Host ≥ 6.9.28 才支持 data-sources.json 与 MySQL 连接器。

完整参考实现： process-work-order @ v1.0.2（工单管理 + MySQL 云库试点）。

---

何时用哪种后端

场景	推荐
单机、离线、小数据量、便携部署	SQLite（默认，不配声明文件亦可）
多用户共享、运维集中管库、与外部系统共库	MySQL 云库（显式 opt-in）

硬规则：一个 sourceId 对应一个物理库。 禁止双写、禁止 SQLite 与 MySQL 同步镜像。

---

文件位置

均在用户数据目录（不是安装包目录）：

{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/
├── data-sources.json      # 声明式数据源（可选；见下）
├── .env                   # MYSQL_DSN 等连接配置
└── {skill_slug}.db        # SQLite 模式下的本地库文件

安装/升级时，若用户目录尚无 data-sources.json 且技能包内有 assets/data-sources.example.json，宿主会复制一次示例（不覆盖已有文件）。

模板默认示例为 SQLite 显式声明（与自动扫描 {skill_slug}.db 等价）。改走 MySQL 时，请参照 assets/examples/data-sources.mysql.example.json 手工替换用户目录中的 data-sources.json，并在 .env 配置 DSN。

若不需要声明式接入，可删除用户目录中的 data-sources.json，宿主恢复自动扫描 .db 文件。

---

data-sources.json 格式

根对象：

字段	类型	说明
version	1	固定为 1
sources	数组	至少一条数据源

每条 sources[]：

字段	必填	说明
id	是	英文标识，如 primary
kind	是	sqlite 或 mysql
displayName	否	侧栏展示名；多库时建议填写
path	sqlite 必填	相对技能数据目录的路径；可用 {skillSlug} 占位
connectionEnv	mysql 必填	.env 中 DSN 的环境变量名，如 MYSQL_DSN

SQLite 示例（模板默认）

见 ../assets/data-sources.example.json。

MySQL 示例

见 ../assets/examples/data-sources.mysql.example.json。

---

.env 与 DSN

MySQL 连接串写在用户 .env（或进程环境变量），不要写进 data-sources.json：

# MySQL 云库连接（不配则走本地 SQLite）
MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database

格式：mysql:// 或 mysql2://，须含库名。注释写法须符合 ../development/CONFIG.md（配置管理会展示给用户）。

技能 Python 侧：scripts/db/backend.py 读取同一 MYSQL_DSN；有值则 resolve_backend() 为 mysql，否则 sqlite。

---

技能代码职责

宿主 UI（数据管理）

宿主读取用户目录 data-sources.json + .env，经 Host 内置连接器访问库。不依赖技能 connection.py。

CLI / Action / init-db

必须与宿主使用同一后端策略，否则会出现「UI 看云库、CLI 写本地 .db」的分裂。

模板已提供：

模块	作用
scripts/db/backend.py	resolve_backend()、parse_mysql_dsn()
scripts/db/cursor_compat.py	统一 ? 占位符与 executescript
scripts/db/connection.py	get_conn() 双分支；init_db() 幂等建 _jiangchang_*

业务表 DDL / 迁移仍在技能自己的 schema / init_db() 中按 conn.backend 分支处理（见工单参考实现）。

可选：describe_active_store() 用于 health / 排障，输出当前连的是 sqlite 还是 mysql。

---

MySQL 当前限制（Host）

• 不支持 tableAdmin（建表/改表 UI）
• 不支持 cellPresentation
• 元数据与 CRUD 与 SQLite 路径一致

表结构变更仍由技能 init-db / 迁移脚本负责。

---

开发 Checklist（云库）

复制新业务技能并选择 MySQL 时：

1. Host ≥ 6.9.28
2. 用户目录放置 data-sources.json（mysql 源 + connectionEnv）
3. .env 配置 MYSQL_DSN（或你在 json 里声明的 env 名）
4. requirements.txt 含 PyMySQL>=1.1.0（模板已声明）
5. 业务 DDL 同时支持 sqlite / mysql 分支（或仅部署 mysql）
6. 抽测：数据管理 UI 与 CLI（如 list / create）读写同一库
7. 见 ../development/CHECKLIST.md A6-16

---

与 SCHEMA / ACTIONS 的关系

• SCHEMA.md：_jiangchang_* 契约适用于已注册数据源上的表，不限于本地文件。
• ACTIONS.md：无 replaces 时宿主直写已注册数据源（默认本地 SQLite）。
• CLI.md：init-db 对当前 active backend 幂等初始化元数据。