This commit is contained in:
@@ -801,28 +801,55 @@ HINT: <next step>
|
||||
| **同步数据**（sync / refresh / collect） | 外部来源 → 技能本地数据库 | 技能 Action / domain service |
|
||||
| **导出当前数据表** | 技能本地数据库 → CSV/Excel 等 | 数据管理页**宿主统一导出** |
|
||||
| **生成特殊业务报告（文件）** | 多表合并、特殊排版或附加计算的 **xlsx/csv/json 等文件** | 仅当系统导出无法满足时，才提供独立 `export-*` Action；文件落 `output/` |
|
||||
| **HTML 页面报告** | 可在数据管理侧栏预览的整页 HTML | 技能写入 `{skill_data}/html/*.html` + Action id **`render-html`**（见下节） |
|
||||
| **HTML 页面报告** | 可在数据管理侧栏预览的整页 HTML | 壳子页放安装包 `assets/html/pages/`；快照写入 `{skill_data}/html/*.html` + Action id **`render-html`**（见下节） |
|
||||
|
||||
同步型 Action 默认：读外部数据、写技能自己的库、**不**生成 CSV/Excel/JSON 文件、不重复实现宿主表导出。兼容旧 export 命令若需要刷新数据，必须调用同一个 sync 业务内核。通用同步语义见 [`SCHEMA.md`](SCHEMA.md) 与 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
|
||||
|
||||
## HTML 页面报告（数据管理预览）
|
||||
|
||||
> 一句话：**技能负责生成并覆盖 `html/*.html`；宿主负责发现、预览、用 `render-html` 触发重新生成。**
|
||||
> 一句话：**壳子页跟安装包走，装完就在侧栏；快照由技能写入 `html/*.html`，宿主用 `render-html` 重新生成。** 页面上的按钮通过宿主调用本技能已声明的命令，不自己起 Python。
|
||||
|
||||
### 何时用
|
||||
|
||||
- 需要**可浏览的整页报告**（KPI + 表格 + 自带样式），而不是再导出一张表
|
||||
- 与 `export-*` / 宿主表导出**并列**：HTML 走 `html/`；文件型特殊报告仍走 `output/` + `export-*`
|
||||
- 需要**可浏览的整页**（KPI + 表格 + 自带样式），而不是再导出一张表
|
||||
- **壳子页**：样式和脚本随技能安装就有，数字在打开后向宿主要。不要为了让它出现而点「生成 HTML」，也不要在 `init-db` 里拷进数据目录
|
||||
- **快照**：把算好的报告烘进文件（往来对账单一类）。与 `export-*` / 宿主表导出**并列**：快照走 `html/`；文件型特殊报告仍走 `output/` + `export-*`
|
||||
|
||||
### 目录与发现（宿主契约）
|
||||
|
||||
| 项 | 约定 |
|
||||
|----|------|
|
||||
| 路径 | `{skill_data}/html/*.html`，**只扫一层**（子目录忽略） |
|
||||
| helper | `util.runtime_paths.get_html_dir()`；写入用 `service.html_page_service.write_html_page` |
|
||||
| 壳子页 | 安装包 `assets/html/pages/*.html`，**只扫一层**（子目录忽略）。装完即进侧栏，不经 `render-html` |
|
||||
| 快照 | `{skill_data}/html/*.html`，**只扫一层**。helper：`get_html_dir()` / `write_html_page` |
|
||||
| 侧栏名 | 取文件内 `<title>`（缺省则用文件名） |
|
||||
| 预览 | 宿主 iframe 预览；右键：重新生成 / 浏览器打开 / 刷新 |
|
||||
| 模板资源 | 建议放 `assets/html/*.html`（安装包内），渲染后**写出**到数据目录 `html/` |
|
||||
| 预览 | 宿主 iframe 预览。壳子页右键：打开 / 打开目录 / 刷新，**没有**「重新生成」。快照右键另有「重新生成」 |
|
||||
| 同名 | 壳子和快照文件名相同则留下快照。两边不要用同一个文件名 |
|
||||
| 快照模板 | `assets/html/example-report.html` 是写出快照时用的壳，**不要**放进 `pages/` |
|
||||
|
||||
### 壳子页
|
||||
|
||||
1. 把自包含 HTML 放到 `assets/html/pages/`（一层，不要子目录）。`<title>` 就是侧栏名字。
|
||||
2. 布局底线与下面「宿主预览布局」相同：铺满、禁横向滚动、禁外链 CSS/JS。
|
||||
3. 不要在初始化数据库时把这些文件拷进 `{skill_data}/html/`。升级技能后宿主读的是新安装包里的文件。
|
||||
|
||||
### 页面调用
|
||||
|
||||
宿主在数据管理预览里注入 `jiangchang.call`。页面脚本把它当成普通函数调用；宿主只在**当前技能** `actions.json` 已声明的方法里查找，命中后走和表按钮同一条 Python CLI，把 CLI 打出的 JSON 交回。
|
||||
|
||||
```javascript
|
||||
const data = await jiangchang.call("方法名", { date: "2026-09-19" });
|
||||
```
|
||||
|
||||
| 项 | 约定 |
|
||||
|----|------|
|
||||
| 方法名 | `actions.json` 里该条的 `id`。没声明则调用失败。不能传任意命令，也不能调别的技能 |
|
||||
| 参数 | 一个 JSON 对象，字段必须落在该条 `inputSchema` 里 |
|
||||
| 入口 | 可以不挂 `toolbar`。页面调用不要求表按钮。`placements` 仍不能为空（例如只挂 `agent`） |
|
||||
| 成功 | CLI 退出码 0，并打印**一个** JSON 对象。页面拿到的就是这个对象 |
|
||||
| 失败 | 退出码非 0，JSON 里带可读的 `message`（`type` 为 `result`、`status` 为 `failed` 时宿主会把 `message` 交给页面） |
|
||||
| 范围 | 只在数据管理预览里有这个函数。用浏览器单独打开该文件时没有，页面应说明「请在数据管理中打开」 |
|
||||
|
||||
异步命令当场只返回任务号，不在这一节展开。写入和只读是同一种调用，差在技能声明了哪条命令。
|
||||
|
||||
### Action：`render-html`（固定 id）
|
||||
|
||||
@@ -844,7 +871,7 @@ HINT: <next step>
|
||||
|
||||
### 宿主预览布局
|
||||
|
||||
数据管理在 **iframe** 内预览 `html/*.html`；宿主 iframe 已占满右侧预览区，**技能页不应再人为收窄正文**（尤其数据管理窗口通常较窄）。
|
||||
数据管理在 **iframe** 内预览壳子页和快照；宿主 iframe 已占满右侧预览区，**技能页不应再人为收窄正文**（尤其数据管理窗口通常较窄）。
|
||||
|
||||
| 级别 | 约定 |
|
||||
|------|------|
|
||||
@@ -870,7 +897,9 @@ HINT: <next step>
|
||||
|
||||
### 验收（复制后自测）
|
||||
|
||||
- [ ] `html/` 下出现 `.html`，数据管理侧栏能看到报告项，预览正常
|
||||
- [ ] 壳子页：安装后侧栏能看到 `assets/html/pages/` 里的标题，无需点生成；右键没有「重新生成」
|
||||
- [ ] 页面调用：`jiangchang.call` 能拿到 CLI 的 JSON；未声明的方法名失败且有可读错误
|
||||
- [ ] 快照：`html/` 下出现 `.html`，数据管理侧栏能看到报告项，预览正常
|
||||
- [ ] 预览区**横向铺满**、**无横向滚动条**；拖窄侧栏后内容自适应（见上节「宿主预览布局」）
|
||||
- [ ] 表顶栏（若声明 toolbar）或报告右键「重新生成」能跑通；成功后预览刷新
|
||||
- [ ] 未登录/无权限用户被拒绝，且有可读错误
|
||||
|
||||
@@ -27,7 +27,7 @@ python {baseDir}/scripts/main.py <command> …
|
||||
| **短 CLI 白名单** | （例）`health` / `version` / `render-html` / `<your-read-or-prep>` | 可用 bash/exec + 共享 `python` |
|
||||
| **Action 强制黑名单** | （例）`<your-long-or-rpa-command>` | **禁止** bash + `process poll`；必须 `run_skill_action` |
|
||||
|
||||
细节与 Action 清单见 [`ACTIONS.md`](ACTIONS.md)。若提供 HTML 报告，「重新生成」须有 Action id **`render-html`**（可同时进短 CLI 白名单）；见 ACTIONS.md「HTML 页面报告」。
|
||||
细节与 Action 清单见 [`ACTIONS.md`](ACTIONS.md)。快照「重新生成」须有 Action id **`render-html`**；壳子页与页面调用 `jiangchang.call` 见 ACTIONS.md「HTML 页面报告」。
|
||||
|
||||
## 最小命令
|
||||
|
||||
|
||||
@@ -143,7 +143,7 @@ metadata:
|
||||
| **同步数据** | 外部来源 → 技能本地数据库 | 技能 Action / domain service |
|
||||
| **导出当前数据表** | 本地库 → CSV/Excel 等 | 数据管理页**宿主统一导出** |
|
||||
| **生成特殊业务报告（文件）** | 多表合并、特殊排版或附加计算的文件 | 仅当系统导出无法满足时，才提供独立 `export-*`；落 `output/` |
|
||||
| **HTML 页面报告** | 侧栏可预览的整页 HTML | 写入 `html/` + Action id **`render-html`**（见 [`ACTIONS.md`](ACTIONS.md)） |
|
||||
| **HTML 页面报告** | 侧栏可预览的整页 HTML | 壳子页 `assets/html/pages/`；快照写入 `html/` + Action id **`render-html`**（见 [`ACTIONS.md`](ACTIONS.md)） |
|
||||
|
||||
同步型 Action 默认只写库、不生成导出文件。兼容旧 export 命令需要刷新时，必须调用同一 sync 内核。可复用测试范式见 `tests/samples/test_sync_contract.py.sample`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user