数据页面目录 app/ 改名 .app/(带点目录,任务文件面板默认隐藏,files 路由本就以 ?hidden=1 才列点文件);对外 URL 保持 /app/{task_id}/ 不变——目录名与路由路径在 routes/data-page.js 解耦,访问地址/visit_url/FAB 深链全不受影响;run.py 目标目录/SKILL.md 契约(环境约定+流程+常见错误:目录带点 URL 不带点别写反)同步;线上会话目录 mv,顺手发现并收纳任务根下 4 个 23:28 的陈旧页面副本(无 FAB 版)进 .app/_stale 待用户确认清理

This commit is contained in:
2026-09-24 00:02:13 +08:00
parent 04a2e436d6
commit 8a9944a622
3 changed files with 22 additions and 20 deletions
+6 -5
View File
@@ -1,6 +1,7 @@
// data-page 技能的服务端承载,两条通道(配套 skills/data-page/SKILL.md 的契约):
// 1. GET /app/{task_id}/... —— 静态托管任务目录的 app/ 子树(index.html 兜底,不给列目录);
// 只暴露 app/ 而非整个任务目录,其余任务文件不从 URL 泄漏。
// 1. GET /app/{task_id}/... —— 静态托管任务目录的 .app/ 子树(index.html 兑底,不给列目录);
// 目录名刻意带点:任务文件面板默认隐藏(?hidden=1 才列);
// 只暴露 .app/ 而非整个任务目录,其余任务文件不从 URL 泄漏。
// 2. POST /api/db/{task_id}/query —— 任务 data.db 的 SQL API(页面前端 fetch 调):任意单语句,
// 执行核心与 db 工具共用 runTaskSql(executor.js),语义单一事实源。
// 认证:挂在 server.js 的 auth.middleware 之后——信任模型与 files 路由一致(登录 ≈ 运维,可跨会话)。
@@ -22,17 +23,17 @@ function notFound(res, msg) {
res.status(404).json({ error: msg });
}
// ---------- /app/{task_id}/...:任务 app/ 子树静态托管 ----------
// ---------- /app/{task_id}/...:任务 .app/ 子树静态托管(URL 路径与目录名解耦)----------
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');
const appRoot = path.join(engine.taskDirOf(sessionId), '.app');
let abs;
try {
abs = resolveInTask(appRoot, segs.slice(1).join('/') || 'index.html'); // 越界即挡,限 app/ 子树
abs = resolveInTask(appRoot, segs.slice(1).join('/') || 'index.html'); // 越界即挡,限 .app/ 子树
} catch (_) {
return notFound(res, '非法路径');
}
+11 -11
View File
@@ -1,6 +1,6 @@
---
name: data-page
description: 数据页面脚手架:把 table/dashboard/kanban 模板复制到任务目录 app/templates/,配合 db 工具产出 /app/{task_id}/ 可访问、经 /api/db/{task_id}/query 读写 data.db 的查看/管理页
description: 数据页面脚手架:把 table/dashboard/kanban 模板复制到任务目录 .app/templates/,配合 db 工具产出 /app/{task_id}/ 可访问、经 /api/db/{task_id}/query 读写 data.db 的查看/管理页
visit_url: /app/{task_id}/
---
@@ -22,16 +22,16 @@ visit_url: /app/{task_id}/
每个会话有独立的任务目录:
- 数据库:任务目录下的 `data.db`
- 页面目录:任务目录下的 `app/`
- 页面入口:`app/index.html`
- 访问地址:`/app/{task_id}/`(完整 URL = 站点地址 + 该路径;run 输出末尾的「访问地址」已拼好,直接转发)
- 页面目录:任务目录下的 `.app/`(带点目录,任务文件面板默认隐藏;URL 路径与目录名在路由层解耦)
- 页面入口:`.app/index.html`
- 访问地址:`/app/{task_id}/`(注意:URL 无点、目录有点,别写错路径;完整 URL = 站点地址 + 该路径,run 输出末尾的「访问地址」已拼好,直接转发)
- 数据 API:`/api/db/{task_id}/query`
`{task_id}` 是任务目录的名称。页面通过 URL 动态解析,不要硬编码。
## 初始化
生成页面前,调用 `skill(name="data-page", op="run")`(无需参数,模板固定复制到 `app/templates/`)。已存在则跳过,不会覆盖修改过的文件(重跑幂等)。
生成页面前,调用 `skill(name="data-page", op="run")`(无需参数,模板固定复制到 `.app/templates/`)。已存在则跳过,不会覆盖修改过的文件(重跑幂等)。
## 数据 API
@@ -74,7 +74,7 @@ const taskId = location.pathname.split('/').filter(Boolean)[1];
1. **明确数据结构**:与用户确认字段。如果描述模糊,可以建议合理的结构。
2. **创建表并录入数据**:用 `db` 工具完成。
3. **初始化模板**:调用 `skill(name="data-page", op="run")`(无参数)。
4. **生成页面**:从 `app/templates/` 选合适的模板,根据表结构调整字段和 SQL,写入 `app/index.html`。
4. **生成页面**:从 `.app/templates/` 选合适的模板,根据表结构调整字段和 SQL,写入 `.app/index.html`。
5. **告知用户**:把 run 输出末尾「访问地址」那行的**完整 URL**(含域名)发给用户——只给 `/app/...` 相对路径用户打不开;再简要说明页面功能。
页面必须包含:
@@ -83,11 +83,11 @@ const taskId = location.pathname.split('/').filter(Boolean)[1];
- 桌面优先、移动兼容的样式:容器宽度按页面类型给足(表格类 1200px、看板类 1400px 或不设、统计类 1080px),不要照搬 800px 级别的移动端尺寸
- 通过 `fetch` 调用数据 API
- 错误处理和加载状态
- **返回应用入口**:右下角 FAB(房子图标),`backToApp()` 跳主界面深链 `/?s=<task_id>`——数据页面的 task_id 就是会话 id,一点直达发起本页的对话;若未来 APK 提供 JS 桥,只需替换 `backToApp()` 一处。**每一个 `app/*.html` 页面(含 index.html)都要带**——用户可能从任意子页直入,缺出口即被困住
- **返回应用入口**:右下角 FAB(房子图标),`backToApp()` 跳主界面深链 `/?s=<task_id>`——数据页面的 task_id 就是会话 id,一点直达发起本页的对话;若未来 APK 提供 JS 桥,只需替换 `backToApp()` 一处。**每一个 `.app/*.html` 页面(含 index.html)都要带**——用户可能从任意子页直入,缺出口即被困住
## 模板
模板位于 `app/templates/`。
模板位于 `.app/templates/`。
- **table.html**:标准表格,适合清单、列表。含排序、搜索、分页。
- **dashboard.html**:统计看板,顶部卡片 + 简单图表 + 明细表。
@@ -205,16 +205,16 @@ const taskId = location.pathname.split('/').filter(Boolean)[1];
3. 没检查 `error` 字段 —— API 错误时仍返回 200
4. 表名或字段名拼错
5. 引入 CDN 外部库 —— 容器可能无网络,优先纯原生
6. 页面文件不在 `app/` 下 —— 无法通过 `/app/{task_id}/` 访问
6. 页面文件不在 `.app/` 下 —— 无法通过 `/app/{task_id}/` 访问(目录带点、URL 不带点,两者别写反)
7. SQL 占位符与参数数量不匹配 —— 优先用结构化 insert,避免手写
## 检查清单
- [ ] 数据库表已创建
- [ ] 数据已录入
- [ ] `app/index.html` 已写入
- [ ] `.app/index.html` 已写入
- [ ] 页面动态解析 task_id
- [ ] 包含错误处理和加载状态
- [ ] 用户输入渲染时已转义
- [ ] 每个 `app/*.html` 页面右下角都有「返回会话」FAB(backToApp → `/?s=<task_id>` 深链)
- [ ] 每个 `.app/*.html` 页面右下角都有「返回会话」FAB(backToApp → `/?s=<task_id>` 深链)
- [ ] 已告知用户完整访问 URL(run 输出「访问地址」那行,含域名,非相对路径)
+5 -4
View File
@@ -1,6 +1,7 @@
#!/usr/bin/env python3
# data-page 技能入口:把技能自带 templates/*.html 复制到会话任务目录的 app/templates/。
# 目标目录固定(SKILL.md 环境约定:页面必须在 app/ 下才能被 /app/{task_id}/ 访问)。
# data-page 技能入口:把技能自带 templates/*.html 复制到会话任务目录的 .app/templates/。
# 目标目录固定(SKILL.md 环境约定:页面必须在 .app/ 下才能被 /app/{task_id}/ 访问;
# 带点是为了任务文件面板默认隐藏,URL 路径与目录名已在路由层解耦)。
# 不开 dest 参数:manager 对已是绝对路径的参数不做沙箱校验,开放 dest = 开放任意目录写入;
# 且路径写死在文档流程里,可配置只会造成漂移。
# 已存在的同名文件跳过不覆盖(AI 改过的模板要能经受重跑);纯 stdlib,无 requirements。
@@ -20,7 +21,7 @@ def main():
if not isinstance(args, dict):
raise ValueError('input_args 必须是 JSON 对象')
if args:
print('本技能无参数(模板固定复制到任务目录 app/templates/),收到:'
print('本技能无参数(模板固定复制到任务目录 .app/templates/),收到:'
+ json.dumps(args, ensure_ascii=False), file=sys.stderr)
return 1
except (ValueError, json.JSONDecodeError) as e:
@@ -37,7 +38,7 @@ def main():
print('templates/ 下没有 .html 模板', file=sys.stderr)
return 1
dest = (Path.cwd() / 'app' / 'templates').resolve()
dest = (Path.cwd() / '.app' / 'templates').resolve()
if str(dest) == str(skill_dir) or str(dest).startswith(str(skill_dir) + os.sep):
print('当前工作目录不是会话任务目录(本地直跑 cwd=技能目录会污染技能;'
'生产经 executor 运行天然正确,手动调试请 cd 到任务目录再跑)', file=sys.stderr)