john
e2ad3bf62b
- 新增 public share widget 与 workspace relative path 解析 - 增强 publications/chat-plaza 发布链路与缩略图 demo - 补充 schema、cover 检查脚本与回归测试 Co-authored-by: Cursor <cursoragent@cursor.com>
132 lines
8.1 KiB
Markdown
132 lines
8.1 KiB
Markdown
---
|
||
name: static-page-publish
|
||
description: 在专属 MindSpace 目录生成可公开访问的静态 HTML 报告与页面（TKMind H5 通用技能）
|
||
---
|
||
|
||
# 静态页面 / 报告发布
|
||
|
||
本技能为 **TKMind H5 多用户环境** 的通用发布流程。安装到用户工作区后，内容会按用户替换为专属目录与公网前缀。
|
||
|
||
## 何时使用
|
||
|
||
- 用户要「生成网页 / HTML 报告 / 可视化页面 / 分享链接」
|
||
- 用户提到「放到 MindSpace」「给个能打开的链接」
|
||
|
||
## 规则摘要
|
||
|
||
0. 可以用 `apps__create_app` 设计/预览页面，但那一步只是在 Apps 窗口内生成交互式 App，**还没有公网链接**；只要用户要「可访问的链接」「分享出去」，最后必须把内容 `write_file` 落到 `public/*.html`，按下方「回复格式」给出真实链接，不要停在 App 阶段就回复链接
|
||
1. 只在**当前用户工作区**（会话 `working_dir`）内读写与搜索，从 `.` 开始
|
||
2. 查找 CSV/文档时只用相对路径（如 `oa/report.csv`），**禁止**去上级目录、MindSpace 根目录、其它用户目录或主机路径搜索
|
||
3. 读 CSV/列目录：用工作区内的 `shell`（`ls oa/`、`cat file.csv`）或 `tree`；**禁止**用公网 URL 代替
|
||
4. **禁止**用 `shell` / `cat` / `heredoc` / `echo` / `cp` 写入 `public/*.html`；HTML 必须用 `write_file` / `edit_file`（shell 在容器内执行，公网链接会 404）
|
||
5. 公网链接**仅**用于让用户浏览器打开已发布的 HTML，不能用来列目录或读数据文件
|
||
6. 静态文件保存即可访问，**无需重启**
|
||
7. 默认只生成 HTML；不要在没有明确需求时强制生成 Word、PDF、长图等伴生文件
|
||
8. 只有用户明确要求 **Word/PDF 等二进制下载** 时：文件单独落盘（如 `public/方案.docx`），链接用相对路径；**禁止**在 HTML 内用 `data:...;base64,...` 嵌入 docx（易截断损坏）
|
||
9. 只有用户明确要求**长图下载**时：必须先 `load_skill` → `long-image-download`，调用 `generate_long_image` 生成同目录 `public/<页面名>.long.png`，再返回长图预览与下载链接；禁止把 `.thumbnail.svg` 当成长图
|
||
|
||
详细约束以工作区内的 `.goosehints` 与 `.agents/skills/static-page-publish/SKILL.md` 为准。
|
||
|
||
## 推荐工作流
|
||
|
||
1. 确认需求（标题、章节、视觉风格、是否需要 hero 图）
|
||
2. `write_file` 创建 `public/页面.html`（需要调整已有页面时用 `edit_file`；需要时在同目录或 `assets/` 放主图）
|
||
3. 在 `<head>` 写入 **mindspace-cover**（必须与页面主题一致，见下文）
|
||
4. 保存后服务端**立即**生成 `<文件名>.thumbnail.svg`（Agent 交互阶段即生效）
|
||
5. 按「回复格式」返回**可点击**公网链接
|
||
6. 若用户明确要求 Word/docx 下载，必须用 `generate_docx`（sandbox-fs 工具）生成 `public/<同名>.docx`，再确认链接目标已落盘
|
||
7. 若用户明确要求长图下载，必须用 `long-image-download` 生成 `public/<同名>.long.png`，并确认文件存在
|
||
|
||
## 按需伴生下载文件
|
||
|
||
- 默认不生成伴生文件；只有用户明确要求下载附件时才生成
|
||
- `<a href="report.docx" download>` 等相对下载链接，目标文件必须已在 HTML 同目录或子目录
|
||
- 推荐 `public/report.html` + `public/report.docx`；**禁止** HTML 链接名与磁盘文件名不一致
|
||
- 生成 Word 时必须调用 sandbox-fs 的 `generate_docx`；**禁止**用 `computercontroller` / shell 生成生产下载文件作为交付依据
|
||
- 从 `oa/` 引用文档时，先 **复制** 到 `public/` 再写链接
|
||
- 交付前 `list_dir public/` 自检；可跑 `npm run check:mindspace-public-links`
|
||
|
||
## 回复格式（必须）
|
||
|
||
向用户交付页面时，**必须使用 Markdown 可点击链接**：
|
||
|
||
```markdown
|
||
[马来西亚旅游攻略](https://goo.tkmind.cn/MindSpace/<用户ID>/public/malaysia-travel-guide.html)
|
||
```
|
||
|
||
要求：
|
||
|
||
- **必须**使用 `[页面标题](完整URL)`，不要只给裸 URL 或「点这里」
|
||
- 页面写入 `public/` 时，URL **必须**包含 `/public/` 路径段（与磁盘路径一致）
|
||
- 域名严格按本节模板拼接（`https://goo.tkmind.cn/MindSpace/<用户ID>/public/...`）；拿不到真实前缀时，先给相对路径 `public/xxx.html` 说明，不要自己猜一个域名
|
||
- 标题用页面真实主题名
|
||
- 可同时给出相对路径（如 `public/malaysia-travel-guide.html`）
|
||
- 说明：保存即生效，无需重启
|
||
- 若生成了长图，同时给 `[长图预览](.../public/malaysia-travel-guide.long.png)` 和 `[下载长图](.../public/malaysia-travel-guide.html?download=long-image)`
|
||
|
||
## 信息流预览图（必须）
|
||
|
||
每个 HTML 必须在 `<head>` 包含与**页面主题一致**的元数据。系统据此生成 **精美的 3:4 信息流封面**（工作区 `*.thumbnail.svg` +「我的空间」卡片 + 保存弹窗预览）：
|
||
|
||
```html
|
||
<meta name="description" content="一句话摘要，显示在预览图副标题">
|
||
<meta name="mindspace-cover" content='{"tag":"旅行","emoji":"🇲🇾","accent":"#ff6b35","accent2":"#24243e","subtitle":"马来西亚深度游","cover":"assets/hero.jpg"}'>
|
||
```
|
||
|
||
| 字段 | 要求 |
|
||
|------|------|
|
||
| `tag` | 与主题一致：旅行 / 美食 / 报告 / **运动** / **活动** 等 |
|
||
| `accent` / `accent2` | 页面主色，与 hero/背景 CSS 一致 |
|
||
| `subtitle` | 一句话卖点；未写时用 description |
|
||
| `cover` / `image` | **必须**指向高质量主图（相对 HTML 或 `https://`）；见下文 |
|
||
| `emoji` | 可选；也可写在 title 中 |
|
||
|
||
### 精美预览图（必须达标）
|
||
|
||
保存 HTML 后，系统会**立即**生成 `<文件名>.thumbnail.svg` 作为卡片封面。要产出**可在信息流中直接展示的精美封面**，必须：
|
||
|
||
1. **视觉类页面**（旅行、美食、活动、运动、品牌、产品、促销等）**必须**在 `assets/` 放置高质量 hero 主图（建议宽度 ≥1200px），并在 `cover` 字段引用（如 `assets/hero.jpg`）
|
||
2. **纯文字报告**可仅用配色 + tag，但仍须保证 `accent` / `subtitle` 与页面风格一致
|
||
3. `tag`、`accent`、`accent2`、`subtitle` 必须与页面实际视觉一致；**禁止**省略 mindspace-cover 或填无关默认值
|
||
4. 若缺少 hero 主图，封面会退化为简陋默认图，**视为未达标**
|
||
|
||
**禁止**省略 mindspace-cover 或填写与页面无关的通用配色；促销/运动/品牌页必须写明 `tag`、`accent` 和 `cover`。
|
||
|
||
本地对比示例：`npm run demo:thumbnails` → `/thumbnail-demo/`（左侧缺 cover vs 右侧方案 A）
|
||
|
||
### 交付前自检（必须）
|
||
|
||
写完 `public/*.html` 后，**必须**运行 cover 合规检查；有 error 则补全元数据后再交付链接：
|
||
|
||
```bash
|
||
npm run check:mindspace-cover
|
||
# 或指定用户：node scripts/check-mindspace-cover.mjs --user <uuid>
|
||
```
|
||
|
||
| 检查项 | 级别 | 说明 |
|
||
|--------|------|------|
|
||
| `mindspace-cover` meta | error | 缺失则缩略图为默认绿色渐变 |
|
||
| `description` | error | 副标题来源 |
|
||
| `cover` raster 主图 | warn | 缺失则无法生成照片封面 |
|
||
| `tag` / `accent` / `subtitle` | warn | 影响分类与配色 |
|
||
| 平台品牌页脚 | warn | 分享与编辑规范 |
|
||
|
||
**视觉类页面**若有 warn `missing_cover_image`，视为封面未达标，必须补 hero 图后再回复用户。
|
||
|
||
## 平台页脚标记（必须）
|
||
|
||
页脚平台品牌行**必须**使用 `data-mindspace-page-tag="platform-brand"`，显示为 **TKMind · 智趣**，**禁止**使用邮箱或 `tkmind.ai`：
|
||
|
||
```html
|
||
<p data-mindspace-page-tag="platform-brand">TKMind · 智趣</p>
|
||
```
|
||
|
||
带 `data-mindspace-page-tag` 的区域为平台固定信息：用户在编辑模式中不可见、不可改；预览与发布后正常显示。**禁止**把该行 CSS 透明度设过低（如 `opacity: 0.25`），否则页内看不见品牌。
|
||
|
||
## 按需附带文件下载（Word / PDF）
|
||
|
||
- 只有用户明确要求 Word / PDF 下载时才生成二进制文件
|
||
- 二进制文件用 `docx-generate` 脚本或平台允许的方式**单独生成**，保存到 `public/`（或 `oa/` 再复制到 `public/`）
|
||
- 下载按钮示例：`<a href="report.docx" download>下载文档</a>`（与 HTML 同目录时用文件名即可）
|
||
- **禁止** `<a href="data:application/vnd...;base64,...">` 内嵌 docx/pdf
|