ui-designer/html-prototype

可交互 HTML 原型

适用场景

当设计方案需要用户直观看到才能决策时，生成可交互的 HTML 原型页面，在浏览器中展示并让用户点击选择。

适用：

• 多设计变体需要用户对比选择
• 布局/视觉方向需要用户确认
• 复杂交互流程需要走查

不适用：

• 纯后端/API 项目
• 用户已明确指定设计方向
• 简单页面无需可视化确认

核心流程

1. 征求同意 → 2. 生成原型 HTML → 3. 启动本地服务 → 4. 用户查看/选择 → 5. 读取选择 → 6. 清理

步骤 1：征求同意

在开始设计前，单独发一条消息询问用户：

接下来的设计方案如果能在浏览器里直观看到，会比纯文字描述更容易决策。我可以生成可交互的 HTML 原型页面，你打开本地链接就能看到效果并点击选择方案。需要开启吗？

这条消息必须独立发送，不要和其他内容混在一起。等待用户回复。

• 用户同意 → 继续步骤 2
• 用户拒绝 → 跳过 HTML 原型，用文字描述 + JSON 交付

步骤 2：生成原型 HTML

在 .boss/<feature>/prototype/ 目录下生成原型文件。

文件结构：

.boss/<feature>/prototype/
├── index.html          # 主页面：展示所有变体，可点击选择
├── server.cjs          # 本地服务脚本（由 Agent 写入）
└── selections.json     # 用户选择记录（服务运行时生成）

2.1 写入服务脚本

将以下代码原样写入 .boss/<feature>/prototype/server.cjs：

const http = require('http');
const fs = require('fs');
const path = require('path');

const DIR = __dirname;
const PORT = process.env.PROTO_PORT || 0;

const MIME = {
  '.html': 'text/html; charset=utf-8',
  '.css': 'text/css',
  '.js': 'application/javascript',
  '.json': 'application/json',
  '.svg': 'image/svg+xml',
  '.png': 'image/png',
  '.jpg': 'image/jpeg',
};

let selections = [];
const selFile = path.join(DIR, 'selections.json');
try {
  selections = JSON.parse(fs.readFileSync(selFile, 'utf-8'));
} catch (e) {}

function saveSelections() {
  fs.writeFileSync(selFile, JSON.stringify(selections, null, 2));
}

const clients = new Set();

const server = http.createServer((req, res) => {
  if (req.method === 'POST' && req.url === '/select') {
    let body = '';
    req.on('data', (c) => (body += c));
    req.on('end', () => {
      try {
        const sel = JSON.parse(body);
        sel.timestamp = Date.now();
        selections.push(sel);
        saveSelections();
        for (const c of clients) {
          try {
            c.write(`data: ${JSON.stringify(sel)}\n\n`);
          } catch (e) {}
        }
        res.writeHead(200, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ ok: true }));
      } catch (e) {
        res.writeHead(400);
        res.end('Bad request');
      }
    });
    return;
  }

  if (req.url === '/selections') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(selections));
    return;
  }

  if (req.url === '/events') {
    res.writeHead(200, {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      Connection: 'keep-alive',
    });
    clients.add(res);
    req.on('close', () => clients.delete(res));
    return;
  }

  let relPath = req.url === '/' ? '/index.html' : req.url.split('?')[0];
  let filePath = path.join(DIR, relPath);
  if (!filePath.startsWith(DIR)) {
    res.writeHead(403);
    res.end('Forbidden');
    return;
  }
  if (!fs.existsSync(filePath)) {
    res.writeHead(404);
    res.end('Not found');
    return;
  }
  const ext = path.extname(filePath).toLowerCase();
  res.writeHead(200, { 'Content-Type': MIME[ext] || 'application/octet-stream' });
  res.end(fs.readFileSync(filePath));
});

server.listen(PORT, '127.0.0.1', () => {
  const port = server.address().port;
  console.log(JSON.stringify({ url: `http://localhost:${port}`, port }));
});