diff --git a/app/server/routes/data-page.js b/app/server/routes/data-page.js new file mode 100644 index 0000000..5811e92 --- /dev/null +++ b/app/server/routes/data-page.js @@ -0,0 +1,72 @@ +// data-page 技能的服务端承载,两条通道(配套 skills/data-page/SKILL.md 的契约): +// 1. GET /app/{task_id}/... —— 静态托管任务目录的 app/ 子树(index.html 兜底,不给列目录); +// 只暴露 app/ 而非整个任务目录,其余任务文件不从 URL 泄漏。 +// 2. POST /api/db/{task_id}/query —— 任务 data.db 的 SQL API(页面前端 fetch 调):任意单语句, +// 执行核心与 db 工具共用 runTaskSql(executor.js),语义单一事实源。 +// 认证:挂在 server.js 的 auth.middleware 之后——信任模型与 files 路由一致(登录 ≈ 运维,可跨会话)。 +// 刻意不加任何 CORS 头:跨站 application/json POST 会被预检挡下,不带 cookie 的匿名页也调不动。 +// 响应契约(SKILL.md 原文):SELECT→行数组;写→{rowsAffected,lastInsertRowid};DDL→{ok:true}; +// 失败→HTTP 200 + {error}(前端统一查 error 字段)。会话/路径级错误才用 4xx。 +const express = require('express'); +const fs = require('fs'); +const path = require('path'); +const engine = require('../engine'); +const { resolveInTask, runTaskSql } = require('../tools/executor'); + +// 页面忘写 LIMIT 的服务端兜底:iterate 到量即停(不全量物化),超限报错引导分页。 +const API_MAX_ROWS = 2000; + +const router = express.Router(); + +function notFound(res, msg) { + res.status(404).json({ error: msg }); +} + +// ---------- /app/{task_id}/...:任务 app/ 子树静态托管 ---------- +router.use('/app', (req, res) => { + try { + const segs = req.path.replace(/^\/+/, '').split('/'); + const sessionId = segs[0]; + if (!sessionId) return notFound(res, '会话不存在'); + if (!engine.getSession(sessionId)) return notFound(res, '会话不存在'); + const appRoot = path.join(engine.taskDirOf(sessionId), 'app'); + let abs; + try { + abs = resolveInTask(appRoot, segs.slice(1).join('/') || 'index.html'); // 越界即挡,限 app/ 子树 + } catch (_) { + return notFound(res, '非法路径'); + } + let st; + try { st = fs.statSync(abs); } catch (_) { return notFound(res, '页面不存在'); } + if (st.isDirectory()) { + abs = path.join(abs, 'index.html'); // 目录请求补 index.html,仍无则 404 + try { st = fs.statSync(abs); } catch (_) { return notFound(res, '页面不存在'); } + } + if (!st.isFile()) return notFound(res, '页面不存在'); + res.sendFile(abs, err => { + if (err && !res.headersSent) notFound(res, '页面不存在'); + }); + } catch (err) { + if (!res.headersSent) res.status(400).json({ error: (err && err.message) || String(err) }); + } +}); + +// ---------- POST /api/db/{task_id}/query:任务 data.db 的 SQL API ---------- +router.post('/api/db/:id/query', (req, res) => { + if (!engine.getSession(req.params.id)) return notFound(res, '会话不存在'); + const body = req.body || {}; + let r; + try { + r = runTaskSql(engine.taskDirOf(req.params.id), String(body.sql || ''), body.params, 'any', API_MAX_ROWS); + } catch (err) { + // SQL 语义错误走 200 + {error}(SKILL.md 契约:前端只查 error 字段,不分状态码) + return res.json({ error: (err && err.message) || String(err) }); + } + if (r.kind === 'read') { + if (r.overflow) return res.json({ error: '结果超过 ' + API_MAX_ROWS + ' 行,请加 LIMIT/OFFSET 分页' }); + return res.json(r.rows); + } + return res.json(r.out); +}); + +module.exports = router; diff --git a/app/server/server.js b/app/server/server.js index 9fda973..72597b5 100644 --- a/app/server/server.js +++ b/app/server/server.js @@ -51,6 +51,9 @@ app.use('/api/skills', require('./routes/skills')); app.use('/api/config', require('./routes/config')); app.use('/api/platforms', require('./routes/platforms')); app.use('/api/system', require('./routes/system')); +// data-page 技能配套:任务 app/ 子树页面向导 /app/{task_id}/ + 数据 API /api/db/{task_id}/query。 +// 随其余业务路由一样挂在 auth.middleware 之后(登录态才能访问)。 +app.use(require('./routes/data-page')); // 模型池状态(前端可展示空闲/占用)+ 每模型 token 用量(今日/累计,输入/输出分开)。 // 从生效配置补齐平台维度字段(platform/mid/vision/type + 平台 key 数 key_count): diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index 4538364..9f53320 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -814,16 +814,20 @@ function toolScheduleTask(ctx, args) { // 列名先对 sqlite_master 真实列校验再 quoteIdent 转义,值全部走 ? 绑定。 // update/delete 不做结构化 op(单行 SQL 本身简单、错误率低,且 AND 等值 where 表达力 // 不够还要回退 exec):继续走 exec,入口不拦写语句,兑底通道保持全能力。 +// runTaskSql 是本工具与 routes/data-page.js(/api/db/{task_id}/query,页面前端调)共用的 +// 唯一 SQL 执行入口:prepare/读写分流/事务/DDL 判定两处同一事实源,不漂移。 const DB_MAX_ROWS = 500; // query 行数上限(docs 要求:防爆上下文) const DB_MAX_BYTES = 100 * 1024; // query 序列化字节上限 -function openTaskDb(ctx) { - fs.mkdirSync(ctx.taskDir, { recursive: true }); - const db = new Database(path.join(ctx.taskDir, 'data.db')); +function openTaskDbAt(taskDir) { + fs.mkdirSync(taskDir, { recursive: true }); + const db = new Database(path.join(taskDir, 'data.db')); db.pragma('busy_timeout = 5000'); return db; } +function openTaskDb(ctx) { return openTaskDbAt(ctx.taskDir); } + // better-sqlite3 不接受 boolean/array/object 绑定;JSON 世界 true/false ↔ SQLite 0/1 是强约定。 // 所有进入绑定位的值(params / rows / set / where)统一过这里。 function dbValue(v, label) { @@ -871,10 +875,11 @@ function jsonSafeRows(rows) { } // 500 行 / 100KB 双上限:未超限返回裸数组;超限改 {rows,...} 信封并附截断说明。 -function renderQueryResult(rows) { +// overflow 由 runTaskSql 的行数截断给出(总行数不再探得,故信封只报 returned_rows 不报 total); +// 字节线在此再收。 +function renderQueryResult(rows, overflow) { let shown = rows; - let truncated = shown.length > DB_MAX_ROWS; - if (truncated) shown = shown.slice(0, DB_MAX_ROWS); + let truncated = !!overflow; if (Buffer.byteLength(JSON.stringify(shown, null, 2)) > DB_MAX_BYTES) { truncated = true; let bytes = 4; // "[\n]" @@ -891,12 +896,58 @@ function renderQueryResult(rows) { return JSON.stringify({ rows: shown, returned_rows: shown.length, - total_rows: rows.length, truncated: true, note: '结果已截断(上限 ' + DB_MAX_ROWS + ' 行或 ' + Math.floor(DB_MAX_BYTES / 1024) + ' KB)。用 WHERE 收窄列/行,或 LIMIT/OFFSET 分页。', }, null, 2); } +// 任务库单语句执行的统一入口。mode:'read' 只许读(op=query)| 'write' 只许写(op=exec)| +// 'any' 按 stmt.reader 自动分流(HTTP API,SKILL.md 契约:任意单语句)。 +// maxRows>0 时读取走 iterate 到量即停(防大表 SELECT * 全量物化),overflow 处置交调用方: +// 工具截断成信封,API 直接报错引导分页。错误一律抛出,不在此层包装返回形态。 +function runTaskSql(taskDir, sql, params, mode, maxRows) { + const text = String(sql || '').trim(); + if (!text) throw new Error('db: sql 不能为空'); + const db = openTaskDbAt(taskDir); + try { + const stmt = db.prepare(text); // 多语句在此抛错(堆叠注入入口即挡) + const bound = sanitizeDbParams(params); + if (stmt.reader) { + if (mode === 'write') throw new Error('db: op=exec 收到只读语句,读取请用 op=query'); + const rows = []; + let overflow = false; + if (maxRows > 0) { + const it = stmt.iterate(...bound); + try { + for (const r of it) { + if (rows.length >= maxRows) { overflow = true; break; } + rows.push(r); + } + } finally { try { it.return(); } catch (_) {} } + } else { + for (const r of stmt.all(...bound)) rows.push(r); + } + return { kind: 'read', rows: jsonSafeRows(rows), overflow }; + } + if (mode === 'read') throw new Error('db: op=query 只允许读语句(SELECT 等),写操作请用 op=exec'); + db.exec('BEGIN'); + try { + const info = stmt.run(...bound); + db.exec('COMMIT'); + const verb = text.split(/\s+/)[0].toLowerCase(); + const out = (verb === 'create' || verb === 'alter' || verb === 'drop') + ? { ok: true } + : { rowsAffected: info.changes, lastInsertRowid: Number(info.lastInsertRowid) }; + return { kind: 'write', out }; + } catch (err) { + try { db.exec('ROLLBACK'); } catch (_) {} + throw err; + } + } finally { + try { db.close(); } catch (_) {} + } +} + function toolDb(ctx, args) { const op = String(args.op || '').trim().toLowerCase(); const sql = String(args.sql || '').trim(); @@ -907,28 +958,13 @@ function toolDb(ctx, args) { switch (op) { case 'exec': { if (!sql) throw new Error('db: op=exec 缺少必填参数 sql'); - db = openTaskDb(ctx); - const stmt = db.prepare(sql); // 多语句在此抛错 - if (stmt.reader) throw new Error('db: op=exec 收到只读语句,读取请用 op=query'); - const params = sanitizeDbParams(args.params); - db.exec('BEGIN'); - try { - const info = stmt.run(...params); - db.exec('COMMIT'); - const verb = sql.split(/\s+/)[0].toLowerCase(); - if (verb === 'create' || verb === 'alter' || verb === 'drop') return JSON.stringify({ ok: true }); - return JSON.stringify({ rowsAffected: info.changes, lastInsertRowid: Number(info.lastInsertRowid) }); - } catch (err) { - try { db.exec('ROLLBACK'); } catch (_) {} - throw err; - } + const r = runTaskSql(ctx.taskDir, sql, args.params, 'write', 0); + return JSON.stringify(r.out); } case 'query': { if (!sql) throw new Error('db: op=query 缺少必填参数 sql'); - db = openTaskDb(ctx); - const stmt = db.prepare(sql); - if (!stmt.reader) throw new Error('db: op=query 只允许读语句(SELECT 等),写操作请用 op=exec'); - return renderQueryResult(jsonSafeRows(stmt.all(...sanitizeDbParams(args.params)))); + const r = runTaskSql(ctx.taskDir, sql, args.params, 'read', DB_MAX_ROWS); + return renderQueryResult(r.rows, r.overflow); } case 'insert': { if (!table) throw new Error('db: op=insert 缺少必填参数 table'); @@ -1084,4 +1120,4 @@ async function executeTool(baseCtx, name, args) { return 'Error: 未知工具 ' + name; } -module.exports = { executeTool, resolveInTask, recordFile }; +module.exports = { executeTool, resolveInTask, recordFile, runTaskSql }; diff --git a/skills/data-page/SKILL.md b/skills/data-page/SKILL.md new file mode 100644 index 0000000..c0576ed --- /dev/null +++ b/skills/data-page/SKILL.md @@ -0,0 +1,221 @@ +--- +name: data-page +description: 数据页面脚手架:把 table/dashboard/kanban 模板复制到任务目录 app/templates/,配合 db 工具产出 /app/{task_id}/ 可访问、经 /api/db/{task_id}/query 读写 data.db 的查看/管理页 +input_schema: + type: object + properties: + dest: + type: string + description: 模板输出目录(相对会话任务目录,自动预转绝对路径;缺省 app/templates,已存在的文件跳过不覆盖) +--- + +# data-page + +## 何时使用 + +当用户提出以下需求时使用本技能: + +- 把数据整理到数据库 +- 生成数据查看页面 +- 生成数据管理页面 +- 数据统计展示 + +不适用:纯粹的文件读写、代码编写、信息检索。 + +## 环境约定 + +每个会话有独立的任务目录: + +- 数据库:任务目录下的 `data.db` +- 页面目录:任务目录下的 `app/` +- 页面入口:`app/index.html` +- 访问地址:`/app/{task_id}/` +- 数据 API:`/api/db/{task_id}/query` + +`{task_id}` 是任务目录的名称。页面通过 URL 动态解析,不要硬编码。 + +## 初始化 + +生成页面前,调用 `skill(name="data-page", op="run", input_args={"dest": "app/templates"})` 复制模板到任务目录的 `app/templates/`。已存在则跳过,不会覆盖修改过的文件(重跑幂等)。 + +## 数据 API + +页面通过此接口读写数据。 + +### 请求 + +``` +POST /api/db/{task_id}/query +Content-Type: application/json + +{ + "sql": "SELECT * FROM parts WHERE qty > ?", + "params": [0] +} +``` + +- `sql`:任意 SQLite 语句 +- `params`:参数化绑定的值数组,可省略 +- 必须使用参数化,不要把用户输入拼进 SQL + +### 响应 + +成功时返回 JSON: + +- SELECT:行数组 `[{"id": 1, "name": "螺丝"}, ...]` +- 写操作:`{"rowsAffected": 1, "lastInsertRowid": 3}` +- 建表等 DDL:`{"ok": true}` + +失败时返回 `{"error": "错误信息"}`,HTTP 状态码仍为 200。前端需要检查 `error` 字段。 + +### task_id 获取 + +```javascript +const taskId = location.pathname.split('/').filter(Boolean)[1]; +``` + +## 页面生成流程 + +1. **明确数据结构**:与用户确认字段。如果描述模糊,可以建议合理的结构。 +2. **创建表并录入数据**:用 `db` 工具完成。 +3. **初始化模板**:调用 `skill(name="data-page", op="run", input_args={"dest": "app/templates"})`。 +4. **生成页面**:从 `app/templates/` 选合适的模板,根据表结构调整字段和 SQL,写入 `app/index.html`。 +5. **告知用户**:访问地址为 `/app/{task_id}/`,简要说明页面功能。 + +页面必须包含: + +- HTML 骨架(``、``、UTF-8) +- 移动端友好的样式 +- 通过 `fetch` 调用数据 API +- 错误处理和加载状态 + +## 模板 + +模板位于 `app/templates/`。 + +- **table.html**:标准表格,适合清单、列表。含排序、搜索、分页。 +- **dashboard.html**:统计看板,顶部卡片 + 简单图表 + 明细表。 +- **kanban.html**:分组看板,按字段分列展示。 + +优先使用模板。模板都不合适时才从零写。 + +## 最小示例 + +```html + + + + + + 采购清单 + + + +

采购清单

+
加载中…
+ + + + +``` + +## 最佳实践 + +**前端** + +- 用原生 JS + fetch,不引入框架 +- 样式用内联 ` + + +
+

数据看板

+
+
+

分布

+
+
+
+

明细

+
+
+
+ + + + diff --git a/skills/data-page/templates/kanban.html b/skills/data-page/templates/kanban.html new file mode 100644 index 0000000..3f80172 --- /dev/null +++ b/skills/data-page/templates/kanban.html @@ -0,0 +1,147 @@ + + + + + +看板 + + + +

看板

+
加载中…
+ + + + diff --git a/skills/data-page/templates/table.html b/skills/data-page/templates/table.html new file mode 100644 index 0000000..7ae9d90 --- /dev/null +++ b/skills/data-page/templates/table.html @@ -0,0 +1,272 @@ + + + + + +数据表格 + + + +
+
+
+

数据表格

+ +
+
+ +
+
+
+
+ + +
+

新增记录

+
+
+ + +
+
+
+ + + +