release: v1.0.117 沉淀多数据源契约（SQLite 默认 + 可选 MySQL 云库）
All checks were successful
技能自动化发布 / release (push) Successful in 9s
All checks were successful
技能自动化发布 / release (push) Successful in 9s
新增 DATA_SOURCES.md、data-sources 示例与双后端 connection 骨架；CLI 与宿主 UI 可读写同一库。要求匠厂 Host ≥ 6.9.28。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -84,7 +84,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
|
||||
| 字段 / 层 | 只决定什么 | 不决定什么 |
|
||||
|-----------|------------|------------|
|
||||
| **`placements`** | Action **出现在哪里**（toolbar / row / batch / cron / agent / skill-detail；`row`=行级入口，壳由宿主呈现） | 不决定 sync/async，不决定点了是否弹窗，不决定行级用操作列还是右键，不决定谁能点 |
|
||||
| **`replaces`** | **可选**：接管数据管理默认「新增 / 编辑 / 删除 / **导入**」 | 不强制；无配置时宿主仍直写 SQLite；**import 时 UI 仍用宿主「导入数据」面板** |
|
||||
| **`replaces`** | **可选**：接管数据管理默认「新增 / 编辑 / 删除 / **导入**」 | 不强制；无配置时宿主仍直写**已注册数据源**（默认本地 SQLite）；**import 时 UI 仍用宿主「导入数据」面板** |
|
||||
| **`bind.tables`** | 数据管理里出现在**哪些业务表** | 不决定业务实现 |
|
||||
| **`executionProfile`** | 宿主是**同步等待**还是**异步 Job** | 不限制可展示入口，不决定是否弹窗 |
|
||||
| **`interaction`** | 可点击入口（数据管理 toolbar/row/batch、默认 CRUD 接管、未来 skill-detail）**点了怎么交互** | 不决定 sync/async；**cron 触发与 agent 忽略** |
|
||||
@@ -231,7 +231,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
|
||||
|
||||
## `replaces`（可选：接管默认新增 / 编辑 / 删除 / 导入）
|
||||
|
||||
有领域副作用的表（归一化字段、建目录、加密、级联清理）不要依赖宿主直写 SQLite。此时可为该表声明 `replaces`，**用户仍点宿主默认按钮**，由技能 CLI 完成写入。
|
||||
有领域副作用的表（归一化字段、建目录、加密、级联清理）不要依赖宿主直写默认 CRUD。此时可为该表声明 `replaces`，**用户仍点宿主默认按钮**，由技能 CLI 完成写入。
|
||||
|
||||
### 怎么选
|
||||
|
||||
@@ -250,7 +250,7 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
|
||||
2. **写库**按表能力分流：
|
||||
- 有 `replaces: import` → 把选中文件路径 + 出错规则交给该 Action（技能解析并写入）
|
||||
- 仅有 `replaces: create` → 宿主按行调用 create（兼容）
|
||||
- 都没有 → 宿主直写 SQLite
|
||||
- 都没有 → 宿主直写已注册数据源（默认 SQLite）
|
||||
|
||||
**不要**再做一张技能自己的「开始执行」导入表单来冒充导入体验。`placements` 对 import 保持 `[]`；`description` 写明「由宿主导入面板调用」。
|
||||
|
||||
|
||||
@@ -44,7 +44,7 @@ python {baseDir}/scripts/main.py init-db
|
||||
- **`health`**：只读 runtime 诊断，**不下载、不修复 media-assets，不执行业务动作**；不输出敏感值。
|
||||
- **`config-path`**：输出 JSON，包含 `skill`、`env_path`、`example_path`。
|
||||
- **`version`**：输出 JSON（`version`、`skill`）。
|
||||
- **`init-db`**：幂等创建/迁移本地 SQLite（含 `_jiangchang_*` 展示元数据）。成功输出一行 JSON（`ok` / `skill` / `db_path`），退出码 `0`。宿主可在技能安装或更新成功后静默调用；不要并入 `health`。
|
||||
- **`init-db`**：幂等创建/迁移当前 active 后端（默认本地 SQLite；配 `MYSQL_DSN` 时为 MySQL 云库，见 `references/DATA_SOURCES.md`），含 `_jiangchang_*` 展示元数据。成功输出一行 JSON（`ok` / `skill` / `db_path` 或等价字段），退出码 `0`。宿主可在技能安装或更新成功后静默调用；不要并入 `health`。
|
||||
- **`policy`（可选）**：仅当 `actions.json` 顶层启用 Data Policy 时需要；向 stdout 输出 Snapshot JSON（见 `references/POLICY.md`）。模板默认不实现；多数技能保持 L0 即可。
|
||||
- **`run` / RPA / 长任务**：CLI 仍是同一内核；**Agent 禁止**用 bash 干等长任务结束。须走宿主 Skill Action（`run_skill_action`），且该 Action 一般为 `executionProfile: "async"` → **任务中心**。长时间无 stdout **不代表卡死**；进度看任务中心 / Run Journal。
|
||||
- **排查顺序**（由快到慢）：
|
||||
|
||||
139
references/DATA_SOURCES.md
Normal file
139
references/DATA_SOURCES.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# 多数据源声明（SQLite / MySQL 云库）
|
||||
|
||||
本文说明技能如何向匠厂宿主**声明**业务数据库，以及技能 CLI / Action 如何与宿主读写**同一物理库**。
|
||||
|
||||
**产品定位：** 默认仍是本地 SQLite（`{skill_slug}.db`）。需要多用户共享、集中运维或云库时，可显式声明 **MySQL**。UI / API 契约不变；`_jiangchang_*` 展示元数据仍写在同一逻辑库中。
|
||||
|
||||
**宿主版本：** 匠厂 Host **≥ 6.9.28** 才支持 `data-sources.json` 与 MySQL 连接器。
|
||||
|
||||
**完整参考实现：** [`process-work-order`](https://git.jc2009.com/client-commons/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`](../assets/data-sources.example.json)。
|
||||
|
||||
### MySQL 示例
|
||||
|
||||
见 [`../assets/examples/data-sources.mysql.example.json`](../assets/examples/data-sources.mysql.example.json)。
|
||||
|
||||
---
|
||||
|
||||
## `.env` 与 DSN
|
||||
|
||||
MySQL 连接串写在用户 `.env`（或进程环境变量），**不要**写进 `data-sources.json`：
|
||||
|
||||
```env
|
||||
# MySQL 云库连接（不配则走本地 SQLite）
|
||||
MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database
|
||||
```
|
||||
|
||||
格式：`mysql://` 或 `mysql2://`，须含库名。注释写法须符合 [`../development/CONFIG.md`](../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`](../development/CHECKLIST.md) A6-16
|
||||
|
||||
---
|
||||
|
||||
## 与 SCHEMA / ACTIONS 的关系
|
||||
|
||||
- [`SCHEMA.md`](SCHEMA.md)：`_jiangchang_*` 契约适用于**已注册数据源**上的表，不限于本地文件。
|
||||
- [`ACTIONS.md`](ACTIONS.md)：无 `replaces` 时宿主直写**已注册数据源**（默认本地 SQLite）。
|
||||
- [`CLI.md`](CLI.md)：`init-db` 对当前 active backend 幂等初始化元数据。
|
||||
@@ -18,10 +18,11 @@
|
||||
| [`SKILL.md`](../SKILL.md) | LLM / OpenClaw 平台技能入口与触发摘要 |
|
||||
| [`CLI.md`](CLI.md) | 共享 Python、命令行入口、参数与短操作契约 |
|
||||
| [`ACTIONS.md`](ACTIONS.md) | Skill Action、sync/async、任务中心、多入口、按钮中文名 `label` 参考（按入口定位表挂载；先读 `development/PRODUCT_SURFACES.md`） |
|
||||
| [`SCHEMA.md`](SCHEMA.md) | 本地 SQLite 与数据管理展示契约 |
|
||||
| [`SCHEMA.md`](SCHEMA.md) | 业务表与数据管理展示契约（SQLite / MySQL） |
|
||||
| [`DATA_SOURCES.md`](DATA_SOURCES.md) | 多数据源声明：SQLite 默认、可选 MySQL 云库（Host ≥ 6.9.28） |
|
||||
| [`POLICY.md`](POLICY.md) | Data Policy：可选身份授权、Snapshot、行 scope（多数技能 L0 不配） |
|
||||
| [`CELL_PRESENTATION.md`](CELL_PRESENTATION.md) | 数据管理呈现：格子 / 整行 / 整列 / 区域语义 tone（用途不限；多数技能 P0 不配） |
|
||||
| [`WORK_ITEM_STATUS.md`](WORK_ITEM_STATUS.md) | 业务行生命周期：处理队列的可操作/进行中/终态角色与重做规则（有处理行 Action 时适用） |
|
||||
| [`../development/`](../development/) | 开发、测试、RPA 深度规范（给人 / 编码助手） |
|
||||
|
||||
按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；权限 opt-in 读 `POLICY.md`；格子/行/列标色读 `CELL_PRESENTATION.md`；队列处理状态机读 `WORK_ITEM_STATUS.md`。
|
||||
按需阅读：短操作优先 `CLI.md`；Action / 任务中心读 `ACTIONS.md`；结构化字段读 `SCHEMA.md`；云库 / 声明式数据源读 `DATA_SOURCES.md`；权限 opt-in 读 `POLICY.md`；格子/行/列标色读 `CELL_PRESENTATION.md`；队列处理状态机读 `WORK_ITEM_STATUS.md`。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 数据存储与数据管理展示规范
|
||||
|
||||
本文是 skill 本地 SQLite 与匠厂宿主「数据管理」页面展示契约的**权威说明**。
|
||||
本文是 skill **已注册数据源**（默认本地 SQLite 文件；可选 MySQL 云库，见 [`DATA_SOURCES.md`](DATA_SOURCES.md)）与匠厂宿主「数据管理」页面展示契约的**权威说明**。
|
||||
|
||||
**产品定位：** 数据管理既是业务数据与过程的可见面，也是与对话**平级**的 **UI 执行面**（表上 Action 走同一 CLI 闭环）。何时挂执行入口见 [`../development/PRODUCT_SURFACES.md`](../development/PRODUCT_SURFACES.md)；本文管表结构与展示元数据。
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
### 技能负责
|
||||
|
||||
- 定义真实 SQLite 表结构
|
||||
- 定义真实业务表结构（SQLite 或 MySQL，按技能所选后端）
|
||||
- 使用英文 `snake_case` 表名和字段名
|
||||
- 使用 `_jiangchang_tables` 提供表级展示元数据
|
||||
- 使用 `_jiangchang_columns` 提供字段级展示元数据（含可选 `description` 表单说明、可选 `grid_help` 表格说明）
|
||||
|
||||
Reference in New Issue
Block a user