geo-ai-search-optimization 1.2.3 → 1.2.5

package/README.md

@@ -243,6 +243,42 @@ geo-ai-search-optimization export-pack https://example.com --out-dir ./exports/e
 - `agent-handoff-bundle`
 - `share-pack`
 
+## HTML Pack 命令
+
+如果你希望直接生成可浏览的静态 HTML 页面，而不是 Markdown 文件，现在可以用 `html-pack`：
+
+```bash
+geo-ai-search-optimization html-pack ./your-site --out-dir ./exports/your-site-html
+geo-ai-search-optimization html-pack https://example.com --out-dir ./exports/example-html
+```
+
+`html-pack` 会生成：
+
+- `index.html`
+- `pm.html`
+- `engineering.html`
+- `exec.html`
+- `agent.html`
+- `share.html`
+
+## Publish Pack 命令
+
+如果你希望直接生成一份“最终可交付包”，同时给人和 agent 使用，现在可以用 `publish-pack`：
+
+```bash
+geo-ai-search-optimization publish-pack ./your-site --out-dir ./exports/your-site-publish-pack
+geo-ai-search-optimization publish-pack https://example.com --out-dir ./exports/example-publish-pack
+```
+
+`publish-pack` 会一次生成：
+
+- `site/`: 可浏览的静态 HTML 页面
+- `documents/`: 给 PM、工程、管理层直接转发的 Markdown 文档
+- `data/`: 给 agent 或自动化流程使用的 JSON 工件
+- `START-HERE.md`: 给人的起始说明
+- `AGENT-START.md`: 给 agent 的执行入口
+- `manifest.json`: 机器可读总索引
+
 ## Fix Plan 命令
 
 如果你已经跑过 `audit`、`report` 或 `onboard-url`，下一步就可以直接把结果转成 PM 待办清单：
@@ -399,6 +435,8 @@ geo-ai-search-optimization completion-report ./my-site
 geo-ai-search-optimization handoff-bundle ./my-site
 geo-ai-search-optimization share-pack ./my-site
 geo-ai-search-optimization export-pack ./my-site --out-dir ./exports/my-site-pack
+geo-ai-search-optimization html-pack ./my-site --out-dir ./exports/my-site-html
+geo-ai-search-optimization publish-pack ./my-site --out-dir ./exports/my-site-publish-pack
 geo-ai-search-optimization exec-summary ./my-site
 geo-ai-search-optimization fix-plan ./my-site
 geo-ai-search-optimization owner-board ./my-site
@@ -414,6 +452,20 @@ geo-ai-search-optimization version
 geo-ai-search-optimization help
 ```
 
+## New in 1.2.5
+
+- 新增 `publish-pack`
+- 一次生成最终可交付目录，而不是手动拼 HTML、Markdown、JSON
+- 增加 `START-HERE.md`、`AGENT-START.md`、`manifest.json`
+- 新增 `geo-ai-search-optimization-publish-pack` skill，帮助 agent 直接接手最终交付包
+
+## New in 1.2.4
+
+- 新增 `html-pack`
+- 直接生成可浏览的静态 HTML 页面目录
+- 更适合直接分享链接或打包给不同角色查看
+- 新增 `geo-ai-search-optimization-html-pack` skill，帮助消费 HTML 包
+
 ## New in 1.2.3
 
 - 新增 `export-pack`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/resources/geo-ai-search-optimization/references/quick-start.md

@@ -48,6 +48,7 @@ geo-ai-search-optimization completion-report ./your-site --out ./reports/complet
 geo-ai-search-optimization handoff-bundle ./your-site --out ./reports/handoff-bundle.md
 geo-ai-search-optimization share-pack ./your-site --out ./reports/share-pack.md
 geo-ai-search-optimization export-pack ./your-site --out-dir ./exports/your-site-pack
+geo-ai-search-optimization html-pack ./your-site --out-dir ./exports/your-site-html
 geo-ai-search-optimization owner-board ./your-site --out ./reports/owner-board.md
 geo-ai-search-optimization meeting-pack ./your-site --out ./reports/meeting-pack.md
 geo-ai-search-optimization pm-brief ./your-site --out ./reports/pm-brief.md
@@ -67,7 +68,8 @@ geo-ai-search-optimization roadmap ./your-site --out ./reports/roadmap.md
 7. 需要完整交接包时生成 handoff-bundle
 8. 需要发给不同角色时生成 share-pack
 9. 需要一整包文件时生成 export-pack
-10. 重跑 scan / audit / report 验证是否改善
+10. 需要直接分享页面时生成 html-pack
+11. 重跑 scan / audit / report 验证是否改善
 
 ## 推荐节奏
 

package/resources/geo-ai-search-optimization-html-pack/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: geo-ai-search-optimization-html-pack
+description: Generate a static HTML share package for GEO results. Use when the user wants browsable files like index.html, pm.html, engineering.html, exec.html, and agent.html instead of plain markdown or JSON exports.
+---
+
+# GEO HTML Pack
+
+Use this skill when the user wants a visually shareable GEO output package.
+
+`GEO = Generative Engine Optimization`
+
+## What it generates
+
+- `index.html`
+- `pm.html`
+- `engineering.html`
+- `exec.html`
+- `agent.html`
+- `share.html`
+
+## Best use
+
+- send `index.html` as the landing page
+- share role-specific pages directly when needed

package/resources/geo-ai-search-optimization-publish-pack/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: geo-ai-search-optimization-publish-pack
+description: Generate a final GEO delivery package that combines HTML pages, markdown documents, JSON artifacts, and agent start files. Use when a PM or agent wants one folder that can be shared directly with humans and handed off directly to another agent.
+---
+
+# GEO Publish Pack
+
+Use this skill when the user wants a single final package instead of separate GEO artifacts.
+
+`GEO = Generative Engine Optimization`
+
+## What it generates
+
+- `site/` for browsable HTML pages
+- `documents/` for markdown files that can be sent to PM, engineering, or management
+- `data/` for machine-readable JSON artifacts
+- `START-HERE.md` for people
+- `AGENT-START.md` for the next agent
+- `manifest.json` for automation and indexing
+
+## Best use
+
+- generate one delivery folder at the end of an analysis round
+- share `site/index.html` for quick browsing
+- point the next agent to `AGENT-START.md`
+- use `manifest.json` when another tool needs to ingest the package

package/resources/geo-ai-search-optimization-publish-pack/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "GEO Publish Pack"
+  short_description: "Build a final delivery folder for humans and agents"
+  default_prompt: "Use $geo-ai-search-optimization-publish-pack to generate a final GEO delivery package with HTML, markdown, JSON, and an agent handoff entrypoint."

package/resources/geo-ai-search-optimization-usage/SKILL.md

@@ -13,7 +13,7 @@ Treat this tool as a PM-friendly GEO workflow for websites.
 
 `GEO = Generative Engine Optimization`
 
-The package is best explained as eleven layers:
+The package is best explained as twelve layers:
 
 1. `onboard-url` / `onboard`: first look
 2. `scan`: raw signal check
@@ -25,7 +25,8 @@ The package is best explained as eleven layers:
 8. `handoff-bundle`: all-in-one package
 9. `share-pack`: audience-ready delivery
 10. `export-pack`: folder export
-11. `pm-brief` / `roadmap`: stakeholder alignment
+11. `html-pack`: browsable output
+12. `pm-brief` / `roadmap`: stakeholder alignment
 
 ## Recommended command order
 
@@ -49,6 +50,7 @@ npx geo-ai-search-optimization completion-report ./your-site
 npx geo-ai-search-optimization handoff-bundle ./your-site
 npx geo-ai-search-optimization share-pack ./your-site
 npx geo-ai-search-optimization export-pack ./your-site
+npx geo-ai-search-optimization html-pack ./your-site
 npx geo-ai-search-optimization owner-board ./your-site
 npx geo-ai-search-optimization roadmap ./your-site
 ```
@@ -67,6 +69,7 @@ npx geo-ai-search-optimization roadmap ./your-site
 - `handoff-bundle`: combine handoff, execution, and closeout into one artifact
 - `share-pack`: prepare role-specific shareable outputs for PM, engineering, management, and agents
 - `export-pack`: generate a folder with multiple ready-to-send files
+- `html-pack`: generate static HTML pages for sharing and browsing
 - `owner-board`: group tasks by PM / engineering / SEO / content
 - `pm-brief`: prepare a PM summary for meetings and prioritization
 - `roadmap`: turn tasks into a 2-week / 4-week execution sequence
@@ -84,6 +87,7 @@ When explaining the tool to a user:
 - if the user wants one consolidated artifact, move them to `handoff-bundle`
 - if the user wants something ready to forward to multiple audiences, move them to `share-pack`
 - if the user wants actual files on disk for each audience, move them to `export-pack`
+- if the user wants browsable HTML pages, move them to `html-pack`
 - if the user already has a report, move them to `fix-plan`, `owner-board`, or `roadmap`
 
 Read [references/usage-patterns.md](references/usage-patterns.md) when you need response patterns and command selection examples.

package/resources/geo-ai-search-optimization-usage/references/usage-patterns.md

@@ -111,6 +111,14 @@ Recommend:
 npx geo-ai-search-optimization export-pack ./your-site --out-dir ./exports/your-site-pack
 ```
 
+## If the user says "我想直接分享 HTML 页面"
+
+Recommend:
+
+```bash
+npx geo-ai-search-optimization html-pack ./your-site --out-dir ./exports/your-site-html
+```
+
 ## If the user says "我要开会同步"
 
 Recommend:

package/src/cli.js

@@ -18,9 +18,11 @@ import { auditProject, renderAuditMarkdown, writeAuditOutput } from "./audit.js"
 import { createFixPlan, renderFixPlanMarkdown, writeFixPlanOutput } from "./fix-plan.js";
 import { createExecSummary, renderExecSummaryMarkdown, writeExecSummaryOutput } from "./exec-summary.js";
 import { renderExportPackMarkdown, writeExportPack } from "./export-pack.js";
+import { renderHtmlPackMarkdown, writeHtmlPack } from "./html-pack.js";
 import { createOwnerBoard, renderOwnerBoardMarkdown, writeOwnerBoardOutput } from "./owner-board.js";
 import { createMeetingPack, renderMeetingPackMarkdown, writeMeetingPackOutput } from "./meeting-pack.js";
 import { createPmBrief, renderPmBriefMarkdown, writePmBriefOutput } from "./pm-brief.js";
+import { renderPublishPackMarkdown, writePublishPack } from "./publish-pack.js";
 import { generateReport, writeReportOutput } from "./report.js";
 import { createRoadmap, renderRoadmapMarkdown, writeRoadmapOutput } from "./roadmap.js";
 import {
@@ -68,6 +70,8 @@ function printHelp() {
       "  geo-ai-search-optimization handoff-bundle <input> [--task <id>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization share-pack <input> [--task <id>] [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization export-pack <input> [--task <id>] [--format <markdown|json>] [--out-dir <dir>]",
+      "  geo-ai-search-optimization html-pack <input> [--task <id>] [--out-dir <dir>]",
+      "  geo-ai-search-optimization publish-pack <input> [--task <id>] [--out-dir <dir>]",
       "  geo-ai-search-optimization exec-summary <input> [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization fix-plan <input> [--format <markdown|json>] [--out <file>]",
       "  geo-ai-search-optimization owner-board <input> [--format <markdown|json>] [--out <file>]",
@@ -490,6 +494,34 @@ async function handleExportPack(args) {
   process.stdout.write(renderExportPackMarkdown(pack));
 }
 
+async function handleHtmlPack(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("html-pack 需要一个输入值，可以是项目路径、网站网址或已导出的 JSON 工件");
+  }
+
+  const pack = await writeHtmlPack(input, {
+    taskId: getFlagValue(args, "--task"),
+    outputDir: getFlagValue(args, "--out-dir")
+  });
+
+  process.stdout.write(renderHtmlPackMarkdown(pack));
+}
+
+async function handlePublishPack(args) {
+  const input = args.find((value) => !value.startsWith("-"));
+  if (!input) {
+    throw new Error("publish-pack 需要一个输入值，可以是项目路径、网站网址或已导出的 JSON 工件");
+  }
+
+  const pack = await writePublishPack(input, {
+    taskId: getFlagValue(args, "--task"),
+    outputDir: getFlagValue(args, "--out-dir")
+  });
+
+  process.stdout.write(renderPublishPackMarkdown(pack));
+}
+
 async function handleExecSummary(args) {
   const input = args.find((value) => !value.startsWith("-"));
   if (!input) {
@@ -693,6 +725,16 @@ export async function runCli(args = []) {
     return;
   }
 
+  if (command === "html-pack") {
+    await handleHtmlPack(rest);
+    return;
+  }
+
+  if (command === "publish-pack") {
+    await handlePublishPack(rest);
+    return;
+  }
+
   if (command === "exec-summary") {
     await handleExecSummary(rest);
     return;

package/src/html-pack.js

@@ -0,0 +1,177 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createExportPack } from "./export-pack.js";
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function wrapHtml(title, body) {
+  return [
+    "<!doctype html>",
+    '<html lang="zh-Hant">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<title>${escapeHtml(title)}</title>`,
+    "<style>",
+    "body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;margin:0;background:#f5f7fb;color:#16324f;}",
+    ".shell{max-width:1100px;margin:0 auto;padding:32px 20px 64px;}",
+    ".hero,.card{background:#fff;border:1px solid #d9e2ec;border-radius:16px;box-shadow:0 8px 24px rgba(15,23,42,.06);}",
+    ".hero{padding:28px;margin-bottom:24px;}",
+    ".grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:16px;}",
+    ".card{padding:20px;}",
+    "h1,h2,h3{margin-top:0;color:#102a43;}",
+    "ul{padding-left:20px;line-height:1.7;}",
+    "a{color:#0b7285;text-decoration:none;}",
+    "code,pre{background:#f4f7fb;border-radius:10px;}",
+    "pre{padding:16px;white-space:pre-wrap;overflow:auto;}",
+    ".meta{display:flex;gap:12px;flex-wrap:wrap;color:#486581;}",
+    "</style>",
+    "</head>",
+    "<body>",
+    body,
+    "</body>",
+    "</html>"
+  ].join("");
+}
+
+function buildIndexHtml(pack) {
+  const cards = pack.files
+    .map(
+      (file) => `
+      <article class="card">
+        <h3>${escapeHtml(file.label)}</h3>
+        <p>${escapeHtml(file.description)}</p>
+        <a href="./${escapeHtml(file.filename)}">打开 ${escapeHtml(file.filename)}</a>
+      </article>
+    `
+    )
+    .join("");
+
+  return wrapHtml(
+    "GEO HTML Pack",
+    `
+    <main class="shell">
+      <section class="hero">
+        <h1>GEO HTML Pack</h1>
+        <div class="meta">
+          <span>来源：${escapeHtml(pack.source)}</span>
+          <span>类型：${escapeHtml(pack.sourceType)}</span>
+          <span>目录：${escapeHtml(pack.outputDir)}</span>
+        </div>
+        <p>这是一个适合直接分享的静态 GEO 页面包，分别提供给 PM、工程、管理层和下一位 agent。</p>
+      </section>
+      <section class="grid">
+        ${cards}
+      </section>
+    </main>
+    `
+  );
+}
+
+function buildDocumentHtml(title, content) {
+  return wrapHtml(
+    title,
+    `
+    <main class="shell">
+      <section class="hero">
+        <h1>${escapeHtml(title)}</h1>
+      </section>
+      <section class="card">
+        <pre>${escapeHtml(content)}</pre>
+      </section>
+    </main>
+    `
+  );
+}
+
+export async function writeHtmlPack(input, options = {}) {
+  const baseOutputDir = path.resolve(options.outputDir || "./exports/html-pack");
+  const exportPack = await createExportPack(input, {
+    format: "markdown",
+    taskId: options.taskId,
+    outputDir: baseOutputDir
+  });
+
+  await fs.mkdir(baseOutputDir, { recursive: true });
+
+  const files = [
+    {
+      key: "pm",
+      label: "PM Brief",
+      description: "给 PM 的优先级与推进摘要。",
+      filename: "pm.html",
+      content: exportPack.files.find((file) => file.key === "pm")?.content || ""
+    },
+    {
+      key: "engineering",
+      label: "Owner Board",
+      description: "给工程与执行团队的任务视图。",
+      filename: "engineering.html",
+      content: exportPack.files.find((file) => file.key === "engineering")?.content || ""
+    },
+    {
+      key: "exec",
+      label: "Exec Summary",
+      description: "给管理层的高层摘要。",
+      filename: "exec.html",
+      content: exportPack.files.find((file) => file.key === "exec")?.content || ""
+    },
+    {
+      key: "agent",
+      label: "Agent Bundle",
+      description: "给下一位 agent 的交接入口。",
+      filename: "agent.html",
+      content: exportPack.files.find((file) => file.key === "agent")?.content || ""
+    },
+    {
+      key: "share",
+      label: "Share Pack",
+      description: "给协调者的总览页面。",
+      filename: "share.html",
+      content: exportPack.files.find((file) => file.key === "share_pack")?.content || ""
+    }
+  ];
+
+  await fs.writeFile(path.join(baseOutputDir, "index.html"), buildIndexHtml({ ...exportPack, files }), "utf8");
+
+  for (const file of files) {
+    await fs.writeFile(path.join(baseOutputDir, file.filename), buildDocumentHtml(file.label, file.content), "utf8");
+  }
+
+  return {
+    kind: "geo-html-pack",
+    source: exportPack.source,
+    sourceType: exportPack.sourceType,
+    outputDir: baseOutputDir,
+    files: [
+      { key: "index", path: path.join(baseOutputDir, "index.html") },
+      ...files.map((file) => ({ key: file.key, path: path.join(baseOutputDir, file.filename) }))
+    ]
+  };
+}
+
+export function renderHtmlPackMarkdown(pack) {
+  const lines = [
+    "# GEO HTML Pack",
+    "",
+    `- 输入来源：\`${pack.source}\``,
+    `- 来源类型：\`${pack.sourceType}\``,
+    `- 输出目录：\`${pack.outputDir}\``,
+    "",
+    "## 页面文件",
+    ""
+  ];
+
+  for (const file of pack.files) {
+    lines.push(`- ${file.key}：\`${file.path}\``);
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/index.js

@@ -10,6 +10,7 @@ export { createAgentHandoff, renderAgentHandoffMarkdown, writeAgentHandoffOutput
 export { createCompletionReport, renderCompletionReportMarkdown, writeCompletionReportOutput } from "./completion-report.js";
 export { createFixPlan, renderFixPlanMarkdown, writeFixPlanOutput } from "./fix-plan.js";
 export { createHandoffBundle, renderHandoffBundleMarkdown, writeHandoffBundleOutput } from "./handoff-bundle.js";
+export { renderHtmlPackMarkdown, writeHtmlPack } from "./html-pack.js";
 export { installSkill } from "./install-skill.js";
 export { runCli } from "./cli.js";
 export { runDoctor, renderDoctorMarkdown } from "./doctor.js";
@@ -19,6 +20,7 @@ export { createExportPack, renderExportPackMarkdown, writeExportPack } from "./e
 export { createMeetingPack, renderMeetingPackMarkdown, writeMeetingPackOutput } from "./meeting-pack.js";
 export { createOwnerBoard, renderOwnerBoardMarkdown, writeOwnerBoardOutput } from "./owner-board.js";
 export { createPmBrief, renderPmBriefMarkdown, writePmBriefOutput } from "./pm-brief.js";
+export { renderPublishPackMarkdown, writePublishPack } from "./publish-pack.js";
 export { createQuickStartPlan, renderQuickStartMarkdown, writeQuickStartOutput } from "./quick-start.js";
 export { generateReport, writeReportOutput } from "./report.js";
 export { createRoadmap, renderRoadmapMarkdown, writeRoadmapOutput } from "./roadmap.js";

package/src/publish-pack.js

@@ -0,0 +1,420 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createExecSummary, renderExecSummaryMarkdown } from "./exec-summary.js";
+import { createHandoffBundle, renderHandoffBundleMarkdown } from "./handoff-bundle.js";
+import { createOwnerBoard, renderOwnerBoardMarkdown } from "./owner-board.js";
+import { createPmBrief, renderPmBriefMarkdown } from "./pm-brief.js";
+import { createSharePack, renderSharePackMarkdown } from "./share-pack.js";
+
+function sanitizeSegment(value) {
+  return String(value)
+    .replace(/[^a-z0-9-_]+/gi, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+function buildBaseName(sourceType, source) {
+  if (sourceType === "url") {
+    try {
+      const hostname = new URL(source).hostname || "website";
+      return sanitizeSegment(hostname) || "website";
+    } catch {
+      return "website";
+    }
+  }
+
+  return sanitizeSegment(path.basename(source)) || "site";
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function wrapHtml(title, body) {
+  return [
+    "<!doctype html>",
+    '<html lang="zh-Hant">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<title>${escapeHtml(title)}</title>`,
+    "<style>",
+    "body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;margin:0;background:#f5f7fb;color:#16324f;}",
+    ".shell{max-width:1100px;margin:0 auto;padding:32px 20px 64px;}",
+    ".hero,.card{background:#fff;border:1px solid #d9e2ec;border-radius:16px;box-shadow:0 8px 24px rgba(15,23,42,.06);}",
+    ".hero{padding:28px;margin-bottom:24px;}",
+    ".grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:16px;}",
+    ".card{padding:20px;}",
+    "h1,h2,h3{margin-top:0;color:#102a43;}",
+    "ul{padding-left:20px;line-height:1.7;}",
+    "a{color:#0b7285;text-decoration:none;}",
+    "code,pre{background:#f4f7fb;border-radius:10px;}",
+    "pre{padding:16px;white-space:pre-wrap;overflow:auto;}",
+    ".meta{display:flex;gap:12px;flex-wrap:wrap;color:#486581;}",
+    "</style>",
+    "</head>",
+    "<body>",
+    body,
+    "</body>",
+    "</html>"
+  ].join("");
+}
+
+function buildDocumentHtml(title, content) {
+  return wrapHtml(
+    title,
+    `
+    <main class="shell">
+      <section class="hero">
+        <h1>${escapeHtml(title)}</h1>
+      </section>
+      <section class="card">
+        <pre>${escapeHtml(content)}</pre>
+      </section>
+    </main>
+    `
+  );
+}
+
+function buildIndexHtml(pack) {
+  const cards = pack.htmlFiles
+    .map(
+      (file) => `
+      <article class="card">
+        <h3>${escapeHtml(file.label)}</h3>
+        <p>${escapeHtml(file.description)}</p>
+        <a href="./${escapeHtml(file.filename)}">打开 ${escapeHtml(file.filename)}</a>
+      </article>
+    `
+    )
+    .join("");
+
+  return wrapHtml(
+    "GEO Publish Pack",
+    `
+    <main class="shell">
+      <section class="hero">
+        <h1>GEO Publish Pack</h1>
+        <div class="meta">
+          <span>来源：${escapeHtml(pack.source)}</span>
+          <span>类型：${escapeHtml(pack.sourceType)}</span>
+          <span>目录：${escapeHtml(pack.outputDir)}</span>
+        </div>
+        <p>这是一个适合直接交付、分发与交接的 GEO 最终发布包，覆盖 PM、工程、管理层与下一位 agent。</p>
+      </section>
+      <section class="grid">
+        ${cards}
+      </section>
+    </main>
+    `
+  );
+}
+
+function buildStartHereContent(pack) {
+  return [
+    "# GEO Publish Pack",
+    "",
+    `- 输入来源：\`${pack.source}\``,
+    `- 来源类型：\`${pack.sourceType}\``,
+    `- 生成时间：${pack.generatedAt}`,
+    "",
+    "## 这份包怎么用",
+    "",
+    "1. 人先打开 `site/index.html` 看总览。",
+    "2. PM 看 `documents/pm-brief.md` 或 `site/pm.html`。",
+    "3. 工程 / 执行团队看 `documents/owner-board.md` 或 `site/engineering.html`。",
+    "4. 管理层看 `documents/exec-summary.md` 或 `site/exec.html`。",
+    "5. 下一位 agent 从 `AGENT-START.md` 和 `data/agent-handoff-bundle.json` 开始。",
+    "",
+    "## 目录结构",
+    "",
+    "- `site/`: 可浏览的静态 HTML 页面。",
+    "- `documents/`: 可直接分享的 Markdown 文档。",
+    "- `data/`: 给 agent 或自动化流程使用的 JSON 工件。",
+    "- `START-HERE.md`: 给人看的起始说明。",
+    "- `AGENT-START.md`: 给 agent 的执行入口。",
+    "- `manifest.json`: 机器可读的总索引。",
+    "",
+    "## 快速入口",
+    "",
+    `- 总览页：\`${pack.quickLinks.indexHtml}\``,
+    `- PM：\`${pack.quickLinks.pmDocument}\``,
+    `- 工程：\`${pack.quickLinks.engineeringDocument}\``,
+    `- 管理层：\`${pack.quickLinks.execDocument}\``,
+    `- Agent：\`${pack.quickLinks.agentData}\``,
+    "",
+    "## 推荐分发顺序",
+    ""
+  ].concat(pack.sharePack.audienceOrder.map((item) => `- ${item}`)).join("\n") + "\n";
+}
+
+function buildAgentStartContent(pack) {
+  const firstPacket = pack.handoffBundle.applyPlan.packets[0];
+  const firstValidation = firstPacket?.validationCommands ?? [];
+  const nextRoundTasks = pack.handoffBundle.completionReport.nextRoundTasks.slice(0, 3);
+
+  const lines = [
+    "# AGENT START",
+    "",
+    "你现在接手这份 GEO 发布包。",
+    "",
+    `- 输入来源：\`${pack.source}\``,
+    `- 来源类型：\`${pack.sourceType}\``,
+    `- 执行模式：\`${pack.handoffBundle.summary.executionMode}\``,
+    `- 执行类型：\`${pack.handoffBundle.summary.executionType}\``,
+    "",
+    "## 先读什么",
+    "",
+    "1. `data/agent-handoff-bundle.json`",
+    "2. `documents/share-pack.md`",
+    "3. `documents/owner-board.md`",
+    "4. `documents/pm-brief.md`",
+    "",
+    "## 你现在该做什么",
+    ""
+  ];
+
+  if (firstPacket) {
+    lines.push(`- 先从任务包 \`${firstPacket.id}\` 开始：${firstPacket.title}`);
+    lines.push(`- 负责人建议：${firstPacket.owner}`);
+  } else {
+    lines.push("- 当前没有具体任务包，请先根据 share-pack 和 owner-board 重新确认优先级。");
+  }
+
+  if (pack.handoffBundle.summary.executionMode === "implementation-ready") {
+    lines.push("- 当前已有本地项目上下文，可以直接检查模板、metadata、schema 或内容文件并实施修复。");
+  } else if (pack.handoffBundle.summary.executionMode === "advice-only") {
+    lines.push("- 当前更适合先给结构化建议，不要假设你已经拥有代码仓库写入权限。");
+    lines.push("- 如果用户能提供仓库或 CMS 上下文，请在拿到后重新生成 publish-pack，再进入直接执行。");
+  } else {
+    lines.push("- 当前输入主要来自已有工件，先根据工件整理修复顺序，再等待更多上下文。");
+  }
+
+  lines.push("", "## 建议先跑的验证命令", "");
+
+  for (const command of firstValidation) {
+    lines.push(`- \`${command}\``);
+  }
+
+  if (firstValidation.length === 0) {
+    lines.push("- 当前没有额外验证命令，先检查 handoff bundle 中的任务描述。");
+  }
+
+  lines.push("", "## 下一轮任务", "");
+
+  for (const task of nextRoundTasks) {
+    lines.push(`- ${task.id}｜${task.title}｜${task.nextAction}`);
+  }
+
+  if (nextRoundTasks.length === 0) {
+    lines.push("- 暂无下一轮任务，先根据当前工件确认缺口。");
+  }
+
+  lines.push(
+    "",
+    "## 完成后怎么回报",
+    "",
+    "- 完成后更新 completion-report 风格的总结。",
+    "- 说明你检查了哪些文件、修改了什么、如何验证、还剩什么风险。",
+    "- 如果无法直接修复，要明确说明缺少哪些上下文或权限。"
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
+function buildManifest(pack) {
+  return {
+    kind: "geo-publish-pack",
+    generatedAt: pack.generatedAt,
+    source: pack.source,
+    sourceType: pack.sourceType,
+    outputDir: pack.outputDir,
+    directories: {
+      site: pack.siteDir,
+      documents: pack.documentsDir,
+      data: pack.dataDir
+    },
+    quickLinks: pack.quickLinks,
+    shareAudienceOrder: pack.sharePack.audienceOrder,
+    executionMode: pack.handoffBundle.summary.executionMode,
+    executionType: pack.handoffBundle.summary.executionType
+  };
+}
+
+export async function writePublishPack(input, options = {}) {
+  const [sharePack, pmBrief, ownerBoard, execSummary, handoffBundle] = await Promise.all([
+    createSharePack(input, { format: "json", taskId: options.taskId }),
+    createPmBrief(input, { format: "json" }),
+    createOwnerBoard(input, { format: "json" }),
+    createExecSummary(input, { format: "json" }),
+    createHandoffBundle(input, { format: "json", taskId: options.taskId })
+  ]);
+
+  const baseName = buildBaseName(sharePack.sourceType, sharePack.source);
+  const outputDir = path.resolve(options.outputDir || `./exports/${baseName}-geo-publish-pack`);
+  const documentsDir = path.join(outputDir, "documents");
+  const dataDir = path.join(outputDir, "data");
+  const siteDir = path.join(outputDir, "site");
+
+  await fs.mkdir(documentsDir, { recursive: true });
+  await fs.mkdir(dataDir, { recursive: true });
+  await fs.mkdir(siteDir, { recursive: true });
+
+  const documentFiles = [
+    { key: "share_pack", filename: "share-pack.md", content: renderSharePackMarkdown(sharePack) },
+    { key: "pm", filename: "pm-brief.md", content: renderPmBriefMarkdown(pmBrief) },
+    { key: "engineering", filename: "owner-board.md", content: renderOwnerBoardMarkdown(ownerBoard) },
+    { key: "exec", filename: "exec-summary.md", content: renderExecSummaryMarkdown(execSummary) },
+    { key: "agent", filename: "agent-handoff-bundle.md", content: renderHandoffBundleMarkdown(handoffBundle) }
+  ];
+
+  const dataFiles = [
+    { key: "share_pack", filename: "share-pack.json", content: `${JSON.stringify(sharePack, null, 2)}\n` },
+    { key: "pm", filename: "pm-brief.json", content: `${JSON.stringify(pmBrief, null, 2)}\n` },
+    { key: "engineering", filename: "owner-board.json", content: `${JSON.stringify(ownerBoard, null, 2)}\n` },
+    { key: "exec", filename: "exec-summary.json", content: `${JSON.stringify(execSummary, null, 2)}\n` },
+    { key: "agent", filename: "agent-handoff-bundle.json", content: `${JSON.stringify(handoffBundle, null, 2)}\n` }
+  ];
+
+  const htmlFiles = [
+    {
+      key: "index",
+      label: "总览页",
+      description: "适合直接打开给团队看的入口。",
+      filename: "index.html",
+      content: ""
+    },
+    {
+      key: "pm",
+      label: "PM Brief",
+      description: "给 PM 的优先级和推进摘要。",
+      filename: "pm.html",
+      content: documentFiles.find((file) => file.key === "pm")?.content || ""
+    },
+    {
+      key: "engineering",
+      label: "Owner Board",
+      description: "给工程与执行团队的任务视图。",
+      filename: "engineering.html",
+      content: documentFiles.find((file) => file.key === "engineering")?.content || ""
+    },
+    {
+      key: "exec",
+      label: "Exec Summary",
+      description: "给管理层的高层摘要。",
+      filename: "exec.html",
+      content: documentFiles.find((file) => file.key === "exec")?.content || ""
+    },
+    {
+      key: "agent",
+      label: "Agent Bundle",
+      description: "给下一位 agent 的交接入口。",
+      filename: "agent.html",
+      content: documentFiles.find((file) => file.key === "agent")?.content || ""
+    },
+    {
+      key: "share",
+      label: "Share Pack",
+      description: "给协调者的总览文档。",
+      filename: "share.html",
+      content: documentFiles.find((file) => file.key === "share_pack")?.content || ""
+    }
+  ];
+
+  const generatedAt = new Date().toISOString();
+  const quickLinks = {
+    startHere: "START-HERE.md",
+    agentStart: "AGENT-START.md",
+    manifest: "manifest.json",
+    indexHtml: "site/index.html",
+    pmDocument: "documents/pm-brief.md",
+    engineeringDocument: "documents/owner-board.md",
+    execDocument: "documents/exec-summary.md",
+    agentData: "data/agent-handoff-bundle.json"
+  };
+
+  const pack = {
+    kind: "geo-publish-pack",
+    generatedAt,
+    source: sharePack.source,
+    sourceType: sharePack.sourceType,
+    outputDir,
+    documentsDir,
+    dataDir,
+    siteDir,
+    quickLinks,
+    sharePack,
+    handoffBundle,
+    htmlFiles
+  };
+
+  await Promise.all(
+    documentFiles.map((file) => fs.writeFile(path.join(documentsDir, file.filename), file.content, "utf8"))
+  );
+  await Promise.all(dataFiles.map((file) => fs.writeFile(path.join(dataDir, file.filename), file.content, "utf8")));
+
+  const indexHtml = buildIndexHtml(pack);
+  await fs.writeFile(path.join(siteDir, "index.html"), indexHtml, "utf8");
+
+  for (const file of htmlFiles.filter((file) => file.key !== "index")) {
+    await fs.writeFile(path.join(siteDir, file.filename), buildDocumentHtml(file.label, file.content), "utf8");
+  }
+
+  await fs.writeFile(path.join(outputDir, "START-HERE.md"), buildStartHereContent(pack), "utf8");
+  await fs.writeFile(path.join(outputDir, "AGENT-START.md"), buildAgentStartContent(pack), "utf8");
+
+  const manifest = buildManifest(pack);
+  await fs.writeFile(path.join(outputDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+
+  return {
+    ...manifest,
+    files: {
+      root: [
+        path.join(outputDir, "START-HERE.md"),
+        path.join(outputDir, "AGENT-START.md"),
+        path.join(outputDir, "manifest.json")
+      ],
+      documents: documentFiles.map((file) => path.join(documentsDir, file.filename)),
+      data: dataFiles.map((file) => path.join(dataDir, file.filename)),
+      site: htmlFiles.map((file) => path.join(siteDir, file.filename))
+    }
+  };
+}
+
+export function renderPublishPackMarkdown(pack) {
+  const lines = [
+    "# GEO Publish Pack",
+    "",
+    `- 输入来源：\`${pack.source}\``,
+    `- 来源类型：\`${pack.sourceType}\``,
+    `- 输出目录：\`${pack.outputDir}\``,
+    `- 生成时间：${pack.generatedAt}`,
+    "",
+    "## 快速入口",
+    "",
+    `- 人类入口：\`${path.join(pack.outputDir, pack.quickLinks.startHere)}\``,
+    `- Agent 入口：\`${path.join(pack.outputDir, pack.quickLinks.agentStart)}\``,
+    `- 静态页面：\`${path.join(pack.outputDir, pack.quickLinks.indexHtml)}\``,
+    `- 机器索引：\`${path.join(pack.outputDir, pack.quickLinks.manifest)}\``,
+    "",
+    "## 目录",
+    "",
+    `- 文档：\`${pack.directories.documents}\``,
+    `- 数据：\`${pack.directories.data}\``,
+    `- 页面：\`${pack.directories.site}\``,
+    "",
+    "## 适合怎么用",
+    ""
+  ];
+
+  lines.push("- 先把 `site/index.html` 发给需要快速了解现状的人。");
+  lines.push("- 把 `documents/pm-brief.md`、`documents/owner-board.md`、`documents/exec-summary.md` 分别发给不同角色。");
+  lines.push("- 让下一位 agent 从 `AGENT-START.md` 和 `data/agent-handoff-bundle.json` 继续接手。");
+
+  return `${lines.join("\n")}\n`;
+}

package/src/quick-start.js

@@ -63,7 +63,8 @@ function buildSteps() {
         "geo-ai-search-optimization completion-report ./your-site --out ./reports/completion-report.md",
         "geo-ai-search-optimization handoff-bundle ./your-site --out ./reports/handoff-bundle.md",
         "geo-ai-search-optimization share-pack ./your-site --out ./reports/share-pack.md",
-        "geo-ai-search-optimization export-pack ./your-site --out-dir ./exports/your-site-pack"
+        "geo-ai-search-optimization export-pack ./your-site --out-dir ./exports/your-site-pack",
+        "geo-ai-search-optimization html-pack ./your-site --out-dir ./exports/your-site-html"
       ]
     },
     {