docs: clarify optional publish attachments

2026-07-02 19:18:56 +08:00
parent bb7b82173d
commit 2d777ef394
4 changed files with 36 additions and 28 deletions
@@ -111,10 +111,10 @@ export function buildChatSkillPrompt(promptKey, skillName) {
    case 'generate-page':
      return (
        `请使用 ${skillName ?? PUBLISH_SKILL_NAME} 技能：在我的专属 MindSpace 发布目录生成静态 HTML 页面，并给出可公网访问的完整链接。` +
-        '必须先 load_skill，再用 write_file/edit_file 写入 public/页面.html；完成后直接返回 Markdown 可点击公网链接 `[页面标题](URL)`。' +
+        '默认只生成 HTML：必须先 load_skill，再用 write_file/edit_file 写入 public/页面.html；完成后直接返回 Markdown 可点击公网链接 `[页面标题](URL)`。' +
        '禁止只给本地路径（如 hello/index.html），禁止询问是否还要发布，除非写文件工具实际失败。' +
-        '如果页面里还需要提供 Word / docx 下载，必须先 `load_skill` → `docx-generate`，生成 `public/*.docx` 并确认文件已存在，再写 HTML 并用同目录相对路径链接该文档。' +
-        '如果用户要求长图下载，必须先 `load_skill` → `long-image-download`，调用 `generate_long_image` 生成 `public/*.long.png` 并确认文件已存在，再给长图预览链接和 `?download=long-image` 下载链接。'
+        '只有用户明确要求 Word / docx 下载时，才先 `load_skill` → `docx-generate`，生成 `public/*.docx` 并确认文件已存在，再写 HTML 并用同目录相对路径链接该文档。' +
+        '只有用户明确要求长图下载时，才先 `load_skill` → `long-image-download`，调用 `generate_long_image` 生成 `public/*.long.png` 并确认文件已存在，再给长图预览链接和 `?download=long-image` 下载链接。不要在没有明确需求时强制生成伴生文件。'
      );
    default:
      return '';
@@ -21,9 +21,9 @@ description: 在专属 MindSpace 目录生成可公开访问的静态 HTML 报
 4. **禁止**用 `shell` / `cat` / `heredoc` / `echo` / `cp` 写入 `public/*.html`；HTML 必须用 `write_file` / `edit_file`（shell 在容器内执行，公网链接会 404）
 5. 公网链接**仅**用于让用户浏览器打开已发布的 HTML，不能用来列目录或读数据文件
 6. 静态文件保存即可访问，**无需重启**
-7. 页面需提供 **Word/PDF 等二进制下载** 时：文件单独落盘（如 `public/方案.docx`），链接用相对路径；**禁止**在 HTML 内用 `data:...;base64,...` 嵌入 docx（易截断损坏）
-8. 页面若提供 **Word/PDF/附件下载**，相对链接指向的文件必须与 HTML **同目录（或子目录）且真实存在**；改 HTML 文件名时同步 **rename/copy** 伴生文件
-9. 页面需提供**长图下载**时：必须先 `load_skill` → `long-image-download`，调用 `generate_long_image` 生成同目录 `public/<页面名>.long.png`，再返回长图预览与下载链接；禁止把 `.thumbnail.svg` 当成长图
+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` 为准。

@@ -34,11 +34,12 @@ description: 在专属 MindSpace 目录生成可公开访问的静态 HTML 报
 3. 在 `<head>` 写入 **mindspace-cover**（必须与页面主题一致，见下文）
 4. 保存后服务端**立即**生成 `<文件名>.thumbnail.svg`（Agent 交互阶段即生效）
 5. 按「回复格式」返回**可点击**公网链接
-6. 若页面含下载按钮，必须用 `generate_docx`（sandbox-fs 工具）生成 `public/<同名>.docx`，再确认链接目标已落盘
-7. 若用户要求长图下载，必须用 `long-image-download` 生成 `public/<同名>.long.png`，并确认文件存在
+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 生成生产下载文件作为交付依据
@@ -103,8 +104,9 @@ description: 在专属 MindSpace 目录生成可公开访问的静态 HTML 报

 带 `data-mindspace-page-tag` 的区域为平台固定信息：用户在编辑模式中不可见、不可改；预览与发布后正常显示。

-## 附带文件下载（Word / PDF）
+## 按需附带文件下载（Word / PDF）

+- 只有用户明确要求 Word / PDF 下载时才生成二进制文件
 - 二进制文件用 `docx-generate` 脚本或平台允许的方式**单独生成**，保存到 `public/`（或 `oa/` 再复制到 `public/`）
 - 下载按钮示例：`<a href="report.docx" download>下载文档</a>`（与 HTML 同目录时用文件名即可）
 - **禁止** `<a href="data:application/vnd...;base64,...">` 内嵌 docx/pdf
@@ -157,18 +157,20 @@ description: 在专属 MindSpace 目录生成可公开访问的静态 HTML 报
 3. 在 \`<head>\` 写入 **mindspace-cover** 元数据（见下文，必须与页面主题一致）
 4. 页面内资源使用**相对路径**（\`assets/foo.png\`），不要用磁盘绝对路径
 5. 保存 HTML 后，服务端会**立即**生成同名预览图 \`<文件名>.thumbnail.svg\`（Agent 交互阶段即生效，无需等用户保存到「我的空间」）
-6. 下载按钮的相对链接目标（如 \`public/report.docx\`）必须通过 \`generate_docx\` 落盘，且 basename 与 HTML 一致
-7. 若用户要求长图下载，必须先 \`load_skill\` → \`long-image-download\`，调用 \`generate_long_image\` 生成并确认 \`public/<页面名>.long.png\` 已存在
-8. 完成后按「回复格式」返回可点击链接
+6. 默认只生成 HTML；不要在没有明确需求时强制生成 Word、PDF、长图等伴生文件
+7. 若用户明确要求 Word / docx 下载，下载按钮的相对链接目标（如 \`public/report.docx\`）必须通过 \`generate_docx\` 落盘，且 basename 与 HTML 一致
+8. 若用户明确要求长图下载，必须先 \`load_skill\` → \`long-image-download\`，调用 \`generate_long_image\` 生成并确认 \`public/<页面名>.long.png\` 已存在
+9. 完成后按「回复格式」返回可点击链接

-## 伴生下载文件（必须）
+## 按需伴生下载文件

+- 默认不生成伴生文件；只有用户明确要求下载附件时才生成
 - 相对路径下载链接（\`.docx\` / \`.pdf\` 等）必须在 HTML 同目录或子目录真实存在
 - Word 文档必须用 sandbox-fs 的 \`generate_docx\` 生成；禁止用 \`computercontroller\` / shell 生成生产下载文件作为交付依据
 - 改 HTML 文件名时同步 rename/copy 伴生文件；从 \`oa/\` 复制到 \`public/\` 再链接
 - 可跑 \`node scripts/check-mindspace-public-links.mjs\` 自检

-## Word 下载页（必须）
+## Word 下载页（按需）

 - 如果用户明确要求页面里**可下载 Word / docx**，必须先 \`load_skill\` → \`docx-generate\`
 - 用 \`.agents/skills/docx-generate/generate_docx.py\` 生成 \`public/文件名.docx\`
@@ -290,7 +292,7 @@ ${renderBrandingBlock(addressName)}

 ## 长图下载

- 若用户要求长图下载：必须先 \`load_skill\` → \`long-image-download\`
+- 若用户明确要求长图下载：必须先 \`load_skill\` → \`long-image-download\`
 - 调用 \`generate_long_image\` 生成 \`public/<页面名>.long.png\`
 - 先确认 \`public/*.long.png\` 已存在，再回复 \`[长图预览](...long.png)\` 和 \`[下载长图](...html?download=long-image)\`
 - \`.thumbnail.svg\` 只是信息流封面，不能当成长图
@@ -333,14 +335,15 @@ export function buildSandboxSessionConstraints({ baseConstraints, developerTools
    '## 生成 / 发布 HTML 页面',
    '- 你有 write_file/edit_file 工具：**必须由你**写入 `public/xxx.html`（或工作区根目录 `.html`）',
    '- 开始前执行 load_skill → `static-page-publish`，按技能说明写入 mindspace-cover 元数据',
-    '- 如果用户要求 Word / docx 下载：先 `load_skill` → `docx-generate`，生成并确认 `public/*.docx` 已存在，再写 HTML 用相对路径链接',
-    '- 如果用户要求长图下载：先 `load_skill` → `long-image-download`，调用 `generate_long_image` 生成并确认 `public/*.long.png` 已存在，再回复长图预览与下载链接',
+    '- 默认只生成 HTML；不要在没有明确需求时强制生成 Word、PDF、长图等伴生文件',
+    '- 只有用户明确要求 Word / docx 下载时：先 `load_skill` → `docx-generate`，生成并确认 `public/*.docx` 已存在，再写 HTML 用相对路径链接',
+    '- 只有用户明确要求长图下载时：先 `load_skill` → `long-image-download`，调用 `generate_long_image` 生成并确认 `public/*.long.png` 已存在，再回复长图预览与下载链接',
    '- **禁止**用 shell / cat / heredoc / echo / cp 写入 HTML；shell 在容器内执行，文件不会出现在公网 MindSpace 路径',
    '- 用 `apps__create_app` 设计页面时，最后仍要按 `static-page-publish` skill 把内容 write_file 落到 `public/`，才有公网链接',
    '- **禁止**让用户手动保存到 public 或说无法生成页面（除非 write_file 调用失败）',
    '- 完成后回复 `[页面标题](公网URL)` 可点击链接；写入 `public/` 时 URL 必须含 `/public/` 路径段；按本会话给出的公网前缀模板拼接真实地址',
-    '- 下载附件：Word 用 `generate_docx` 写入 `public/*.docx`，相对链接文件必须已在 `public/` 落盘，basename 与 HTML 一致',
-    '- 长图附件：用 `generate_long_image` 写入 `public/*.long.png`，不要把 `.thumbnail.svg` 当成长图',
+    '- 按需下载附件：Word 用 `generate_docx` 写入 `public/*.docx`，相对链接文件必须已在 `public/` 落盘，basename 与 HTML 一致',
+    '- 按需长图附件：用 `generate_long_image` 写入 `public/*.long.png`，不要把 `.thumbnail.svg` 当成长图',
  );
  return lines.join('\n');
 }
@@ -359,8 +362,9 @@ export function buildPublishConstraints({ slug, username, publicBaseUrl, publish
    '- **禁止**：访问 `assets/` 内部路径、其它用户目录、主机绝对路径；禁止用公网 URL 列目录或读 CSV',
    '- **路径规则**：只用相对路径；禁止 `../`；工作区外的路径会被系统拒绝（OS 层强制，非软约束）',
    '- **生成页面（必须亲自完成）**：先 `load_skill` → `static-page-publish`，再用 `write_file`/`edit_file` 写入 `public/页面.html`',
-    '- **Word 下载页（必须亲自完成）**：若用户要求 Word / docx 下载，必须先 `load_skill` → `docx-generate`，生成并确认 `public/*.docx` 已存在，再在 HTML 中用相对路径链接',
-    '- **长图下载（必须亲自完成）**：若用户要求长图下载，必须先 `load_skill` → `long-image-download`，调用 `generate_long_image` 生成并确认 `public/*.long.png` 已存在',
+    '- **默认只生成 HTML**：不要在没有明确需求时强制生成 Word、PDF、长图等伴生文件',
+    '- **Word 下载页（按需亲自完成）**：若用户明确要求 Word / docx 下载，必须先 `load_skill` → `docx-generate`，生成并确认 `public/*.docx` 已存在，再在 HTML 中用相对路径链接',
+    '- **长图下载（按需亲自完成）**：若用户明确要求长图下载，必须先 `load_skill` → `long-image-download`，调用 `generate_long_image` 生成并确认 `public/*.long.png` 已存在',
    '- **用户可见回复**：不要向用户复述 load_skill、技能更新、页脚标记、mindspace-cover 等内部实现；完成后直接给出页面链接或结果',
    '- **禁止**用 shell 写入 HTML；**禁止**让用户「手动保存到 public 目录」或说「我无法生成页面」——除非 write_file 已失败并报告错误',
    '- 完成后给出 Markdown 可点击公网链接 `[标题](URL)`；写入 `public/页面.html` 时 URL 为 `.../MindSpace/<用户ID>/public/页面.html`',
@@ -368,8 +372,8 @@ export function buildPublishConstraints({ slug, username, publicBaseUrl, publish
    '- **需要查实时/真实世界信息时**：先 `load_skill` → `web`，优先 `web_search`/`fetch_url`；国内 google.com 不可达，多次无果时改走 Bing/360 等可达搜索源',
    '- **禁止**让用户「手动保存到 public 目录」或说「我无法生成页面」——除非 write_file 已失败并报告错误',
    '- 完成后给出 Markdown 可点击公网链接 `[标题](URL)`；写入 `public/页面.html` 时 URL 为 `.../MindSpace/<用户ID>/public/页面.html`，按模板拼真实地址',
-    '- 下载链接（如 `report.docx`）必须与 HTML 同目录且文件名一致；Word 必须用 sandbox-fs `generate_docx` 生成，不要用 `computercontroller` / shell 作为交付依据',
-    '- 长图链接：生成 `report.long.png` 后给 `[长图预览](.../report.long.png)`，下载用 `[下载长图](.../report.html?download=long-image)`',
+    '- 按需下载链接（如 `report.docx`）必须与 HTML 同目录且文件名一致；Word 必须用 sandbox-fs `generate_docx` 生成，不要用 `computercontroller` / shell 作为交付依据',
+    '- 按需长图链接：生成 `report.long.png` 后给 `[长图预览](.../report.long.png)`，下载用 `[下载长图](.../report.html?download=long-image)`',
    `- 发布技能：\`${PUBLISH_SKILL_NAME}\`（生成页面前应 load_skill）`,
  ].join('\n');
 }
@@ -100,8 +100,9 @@ ${zoneLines.join('\n')}

 - 用户要网页 / HTML / 报告 / 分享链接时：**你必须亲自完成**，不要推给用户手动操作
 - 先 \`load_skill\` → \`static-page-publish\`，再使用 \`write_file\` 创建 \`public/页面名.html\`（需要调整已有页面时用 \`edit_file\`）
- 如果页面里还要提供 Word / docx 下载：必须先 \`load_skill\` → \`docx-generate\`，生成 \`public/文件名.docx\` 并确认文件存在，再写 HTML 用相对路径链接该文档
- 页面需要 Word / docx 下载时，必须用 sandbox-fs 的 \`generate_docx\` 写入 \`public/*.docx\`，不要用 shell/computercontroller 生成生产下载文件
+- 默认只生成 HTML；不要在没有明确需求时强制生成 Word、PDF、长图等伴生文件
+- 只有用户明确要求 Word / docx 下载时：必须先 \`load_skill\` → \`docx-generate\`，生成 \`public/文件名.docx\` 并确认文件存在，再写 HTML 用相对路径链接该文档
+- 用户明确要求 Word / docx 下载时，必须用 sandbox-fs 的 \`generate_docx\` 写入 \`public/*.docx\`，不要用 shell/computercontroller 生成生产下载文件
 - 若用 \`apps__create_app\` 设计/预览页面：这一步只是在 Apps 窗口内创建交互式 App，**还没有公网链接**；必须紧接着按 \`static-page-publish\` skill 把最终内容 \`write_file\` 落到 \`public/*.html\`，才能给出真实可访问的链接
 - 写入 \`<head>\` 的 **mindspace-cover** 元数据（详见 \`.agents/skills/static-page-publish/SKILL.md\`）
 - 保存后立即给出 Markdown 可点击公网链接 \`[标题](URL)\`；写入 \`public/页面.html\` 时 URL 为 \`.../MindSpace/<用户ID>/public/页面.html\`
@@ -131,10 +132,11 @@ export function buildUserSpaceConstraints({ username, workspaceRoot, publicBaseU
    '- **禁止**：访问其它用户目录、MindSpace 根目录、data/mindspace 内部路径、主机绝对路径',
    '- **禁止**用公网 URL 列目录或读 CSV；生成 HTML 写入 `public/` 并给出公网链接',
    '- **生成页面**：先 `load_skill` → `static-page-publish`，再用 `write_file` / `edit_file` 写入 `public/*.html`；**禁止**让用户手动保存文件',
-    '- **Word 下载页**：若用户要求 Word / docx 下载，必须先 `load_skill` → `docx-generate` 生成 `public/*.docx` 并确认文件存在，再在 HTML 里用相对路径链接该文档',
+    '- **默认只生成 HTML**：不要在没有明确需求时强制生成 Word、PDF、长图等伴生文件',
+    '- **Word 下载页**：若用户明确要求 Word / docx 下载，必须先 `load_skill` → `docx-generate` 生成 `public/*.docx` 并确认文件存在，再在 HTML 里用相对路径链接该文档',
    '- 用 `apps__create_app` 设计页面时，最后一步仍要按 `static-page-publish` skill 把内容 `write_file` 落到 `public/*.html`，再给出下方前缀拼出的真实链接，不要停在 App 阶段就回复链接',
    '- **需要查实时/真实世界信息（如机构名单、新闻、行情）时**：先 `load_skill` → `web`，优先用其 `web_search`/`fetch_url`；国内环境下 google.com 不可达，`web_search` 多次无果时改走 Bing/360 等可达搜索源，避免对反爬站点反复硬抓',
-    '- **Word 下载页**：若用户要求 Word / docx 下载，必须先 `load_skill` → `docx-generate` 生成 `public/*.docx` 并确认文件存在，再在 HTML 里用相对路径链接该文档；不要用 shell/computercontroller 生成生产下载文件',
+    '- **Word 下载页**：若用户明确要求 Word / docx 下载，必须先 `load_skill` → `docx-generate` 生成 `public/*.docx` 并确认文件存在，再在 HTML 里用相对路径链接该文档；不要用 shell/computercontroller 生成生产下载文件',
    publicBaseUrl && slug
      ? `- 公网 HTML 前缀（公开区）：\`${publicBaseUrl}/${PUBLISH_ROOT_DIR}/${slug}/public/\`（写入 \`public/页面.html\` 时分享链接必须含 \`public/\`）`
      : null,