Skip to content

jnMetaCode/superpowers-zh / skills/brainstorming

brainstorming

Verified

在任何创造性工作之前必须使用此技能——创建功能、构建组件、添加功能、修改行为,或筹划任何新东西,无论是软件还是软件之外(一场分享、一门生意、一次装修)。

FileKindSize
SKILL.mdskill md15.6 KB
builder-check-prompt.mdmarkdown911 B
scripts/frame-template.htmlother7.9 KB
scripts/helper.jsscript5.5 KB
scripts/server.cjsscript25.1 KB
scripts/start-server.shexecutablescript7.1 KB
scripts/stop-server.shexecutablescript3.2 KB
visual-companion.mdmarkdown12.6 KB

visual-companion.md

View on GitHub
# 视觉伴侣指南

基于浏览器的视觉头脑风暴伴侣,用于展示原型、图表和选项。

## 何时使用

逐问题决定,而非按会话决定。判断标准:**用户看到它是否比读到它更容易理解?**

**使用浏览器** 当内容本身是视觉的:

- **UI 原型** — 线框图、布局、导航结构、组件设计
- **架构图** — 系统组件、数据流、关系图
- **并排视觉对比** — 对比两种布局、两种配色方案、两种设计方向
- **设计细节打磨** — 当问题涉及外观感受、间距、视觉层次
- **空间关系** — 状态机、流程图、实体关系图

**使用终端** 当内容是文字或表格的:

- **需求和范围问题** — "X 是什么意思?"、"哪些功能在范围内?"
- **概念性 A/B/C 选择** — 在用文字描述的方案之间做选择
- **权衡列表** — 优缺点、对比表
- **技术决策** — API 设计、数据建模、架构方案选择
- **澄清问题** — 任何回答是文字而非视觉偏好的问题

*关于* UI 主题的问题不一定是视觉问题。"你想要什么样的向导?"是概念性的——使用终端。"这些向导布局中哪个感觉对?"是视觉性的——使用浏览器。

## 工作原理

服务器监视一个目录中的 HTML 文件,将最新的文件提供给浏览器。你把 HTML 内容写入 `screen_dir`,用户在浏览器中看到它,并可以点击选择选项。选择结果被记录到 `state_dir/events`,你在下一轮读取它。

**内容片段 vs 完整文档:** 如果你的 HTML 文件以 `<!DOCTYPE` 或 `<html` 开头,服务器会原样提供(仅注入辅助脚本)。否则,服务器会自动将你的内容包裹在框架模板中——添加头部、CSS 主题、连接状态和所有交互基础设施。**默认写内容片段即可。** 只有当你需要完全控制页面时才写完整文档。

## 启动会话

```bash
# 在用户同意使用视觉伴侣之后再启动。--open 会在推送第一个屏幕时自动打开浏览器;
# --project-dir 让原型持久化,并支持用同一端口重启。
bash scripts/start-server.sh --project-dir /path/to/project --open

# 返回:{"type":"server-started","port":52341,
#           "url":"http://localhost:52341/?key=ab12…",
#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
```

保存响应中的 `screen_dir` 和 `state_dir`。使用 `--open` 时,你推送第一个屏幕时浏览器会自己打开——不需要请用户去打开,但仍要把 URL 发给他们作为兜底(无头/远程环境不会自动打开)。

**URL 里带有会话密钥(`?key=…`)。** 服务器会拒绝任何不带它的请求,
所以永远要把 `url` 字段里的**完整** URL 交给用户——
绝不去掉查询字符串,也绝不给出一个光秃秃的 `http://host:port`。这个
密钥守着 HTTP 和 WebSocket 访问,让误开的浏览器标签页或网络上的其他机器
无法读取屏幕内容或注入事件。首次加载后浏览器会通过 cookie 记住密钥,
所以刷新页面和 `/files/*` 资源都无需再带上它。

**查找连接信息:** 服务器将其启动 JSON 写入 `$STATE_DIR/server-info`。如果你在后台启动了服务器且没有捕获 stdout,读取该文件以获取 URL 和端口。使用 `--project-dir` 时,检查 `<project>/.superpowers/brainstorm/` 获取会话目录。

**注意:** 传入项目根目录作为 `--project-dir`,这样原型会持久化在 `.superpowers/brainstorm/` 中,不会因服务器重启而丢失。不传的话,文件会保存到 `/tmp` 并在清理时被删除。提醒用户将 `.superpowers/` 添加到 `.gitignore`(如果尚未添加)。

**按平台启动服务器:**

**Claude Code:**
```bash
# 默认模式即可——脚本会自己把服务器放到后台。
bash scripts/start-server.sh --project-dir /path/to/project --open
```

在 Windows 上,脚本会自动检测并切换到前台模式(这会阻塞工具调用)。在 Bash 工具调用上设置 `run_in_background: true`,让服务器在会话轮次之间存活,然后在下一轮读取 `$STATE_DIR/server-info` 获取 URL 和端口。

**Codex:**
```bash
# Codex 会回收后台进程。脚本会自动检测 CODEX_CI 并
# 切换到前台模式。正常运行即可——不需要额外标志。
bash scripts/start-server.sh --project-dir /path/to/project --open
```

**Gemini CLI:**
```bash
# 使用 --foreground 并在 shell 工具调用上设置 is_background: true,
# 让进程在轮次之间存活
bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
```

**Copilot CLI:**
```bash
# 用 Copilot CLI 的非阻塞 / 后台 shell 机制启动,让服务器能跨会话轮次存活。
# 保留 --foreground —— 由 harness 而不是脚本来负责放到后台。
# 启动器是 .sh,所以要通过 bash 调用(Windows 上用 Git Bash 的 bash.exe,
# 从 PowerShell 工具里调)。
bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
```

**其他环境:** 服务器必须在会话轮次之间持续在后台运行。如果你的环境会回收分离的进程,使用 `--foreground` 并通过平台的后台执行机制启动命令。

如果浏览器无法访问该 URL(在远程/容器化环境中常见),绑定一个非回环主机:

```bash
bash scripts/start-server.sh \
  --project-dir /path/to/project \
  --host 0.0.0.0 \
  --url-host localhost
```

使用 `--url-host` 控制返回的 URL JSON 中显示的主机名。

## 工作循环

1. **检查服务器存活**,然后**将 HTML 写入** `screen_dir` 中的新文件:
   - **必须:在提及 URL 或推送屏幕之前,先确认服务器还活着。** 检查 `$STATE_DIR/server-info` 存在且 `$STATE_DIR/server-stopped` 不存在。如果服务器已关闭,用 `start-server.sh` 以**相同的 `--project-dir`** 重启——它会复用同一端口,用户开着的标签页会自己重新连上(服务器停机期间页面会显示"已暂停"遮罩),你不需要发新的 URL。服务器空闲 4 小时后会自动退出(可用 `--idle-timeout-minutes` 配置)。
   - 使用语义化文件名:`platform.html`、`visual-style.html`、`layout.html`
   - **绝不复用文件名** — 每个屏幕用一个新文件
   - 使用你的文件创建工具 — **绝不使用 cat/heredoc**(会在终端产生噪音)
   - 服务器自动提供最新的文件

2. **告诉用户预期内容并结束你的回合:**
   - 每一步都提醒他们 URL(不仅仅是第一次)
   - 简要文字说明屏幕上的内容(例如"展示了 3 个首页布局选项")
   - 请他们在终端中回复:"看一下,告诉我你的想法。如果你愿意,可以点击选择一个选项。"

3. **在你的下一轮** — 用户在终端回复后:
   - 如果存在 `$STATE_DIR/events`,读取它——其中包含用户的浏览器交互(点击、选择),格式为 JSON 行
   - 将终端文字和事件合并以获得完整信息
   - 终端消息是主要反馈;`state_dir/events` 提供结构化的交互数据

4. **迭代或推进** — 如果反馈要求修改当前屏幕,写入新文件(例如 `layout-v2.html`)。只有当前步骤验证通过后才进入下一个问题。

5. **回到终端时卸载** — 当下一步不需要浏览器时(例如澄清问题、权衡讨论),推送一个等待屏幕以清除过时内容:

   ```html
   <!-- 文件名:waiting.html(或 waiting-2.html 等)-->
   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
     <p class="subtitle">在终端中继续...</p>
   </div>
   ```

   这样可以防止用户盯着一个已经解决的选择,而对话已经继续了。当下一个视觉问题出现时,照常推送新的内容文件。

6. 重复直到完成。

## 编写内容片段

只写放在页面内部的内容。服务器会自动用框架模板包裹它(头部、主题 CSS、连接状态和所有交互基础设施)。

**最简示例:**

```html
<h2>哪种布局更好?</h2>
<p class="subtitle">考虑可读性和视觉层次</p>

<div class="options">
  <div class="option" data-choice="a" onclick="toggleSelect(this)">
    <div class="letter">A</div>
    <div class="content">
      <h3>单栏</h3>
      <p>简洁、专注的阅读体验</p>
    </div>
  </div>
  <div class="option" data-choice="b" onclick="toggleSelect(this)">
    <div class="letter">B</div>
    <div class="content">
      <h3>双栏</h3>
      <p>侧边栏导航加主内容区</p>
    </div>
  </div>
</div>
```

就这些。不需要 `<html>`,不需要 CSS,不需要 `<script>` 标签。服务器会提供这一切。

## 可用的 CSS 类

框架模板为你的内容提供以下 CSS 类:

### 选项(A/B/C 选择)

```html
<div class="options">
  <div class="option" data-choice="a" onclick="toggleSelect(this)">
    <div class="letter">A</div>
    <div class="content">
      <h3>标题</h3>
      <p>描述</p>
    </div>
  </div>
</div>
```

**多选:** 在容器上添加 `data-multiselect` 让用户选择多个选项。每次点击切换该项的选中样式。

```html
<div class="options" data-multiselect>
  <!-- 相同的选项标记——用户可以选择/取消选择多个 -->
</div>
```

### 卡片(视觉设计)

```html
<div class="cards">
  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
    <div class="card-image"><!-- 原型内容 --></div>
    <div class="card-body">
      <h3>名称</h3>
      <p>描述</p>
    </div>
  </div>
</div>
```

### 原型容器

```html
<div class="mockup">
  <div class="mockup-header">预览:仪表盘布局</div>
  <div class="mockup-body"><!-- 你的原型 HTML --></div>
</div>
```

### 分屏视图(并排)

```html
<div class="split">
  <div class="mockup"><!-- 左侧 --></div>
  <div class="mockup"><!-- 右侧 --></div>
</div>
```

### 优缺点

```html
<div class="pros-cons">
  <div class="pros"><h4>优点</h4><ul><li>好处</li></ul></div>
  <div class="cons"><h4>缺点</h4><ul><li>不足</li></ul></div>
</div>
```

### 模拟元素(线框图构建块)

```html
<div class="mock-nav">Logo | 首页 | 关于 | 联系我们</div>
<div style="display: flex;">
  <div class="mock-sidebar">导航</div>
  <div class="mock-content">主内容区域</div>
</div>
<button class="mock-button">操作按钮</button>
<input class="mock-input" placeholder="输入框">
<div class="placeholder">占位区域</div>
```

### 排版和区块

- `h2` — 页面标题
- `h3` — 章节标题
- `.subtitle` — 标题下方的辅助文字
- `.section` — 带底部边距的内容块
- `.label` — 小号大写标签文字

## 浏览器事件格式

当用户在浏览器中点击选项时,交互记录会保存到 `$STATE_DIR/events`(每行一个 JSON 对象)。推送新屏幕时文件会自动清空。

```jsonl
{"type":"click","choice":"a","text":"选项 A - 简单布局","timestamp":1706000101}
{"type":"click","choice":"c","text":"选项 C - 复杂网格","timestamp":1706000108}
{"type":"click","choice":"b","text":"选项 B - 混合方案","timestamp":1706000115}
```

完整的事件流展示了用户的探索路径——他们可能在确定之前点击了多个选项。最后一个 `choice` 事件通常是最终选择,但点击模式可以揭示犹豫或值得询问的偏好。

如果 `$STATE_DIR/events` 不存在,说明用户没有与浏览器交互——仅使用他们的终端文字。

## 设计技巧

- **保真度匹配问题** — 布局问题用线框图,细节打磨问题用精细设计
- **在每个页面上解释问题** — "哪种布局看起来更专业?"而不仅仅是"选一个"
- **推进前先迭代** — 如果反馈修改了当前屏幕,写入新版本
- 每个屏幕最多 **2-4 个选项**
- **必要时使用真实内容** — 对于摄影作品集,使用实际图片(Unsplash)。占位内容会掩盖设计问题。
- **保持原型简洁** — 专注于布局和结构,而非像素级精确的设计

## 文件命名

- 使用语义化名称:`platform.html`、`visual-style.html`、`layout.html`
- 绝不复用文件名——每个屏幕必须是新文件
- 迭代版本:添加版本后缀如 `layout-v2.html`、`layout-v3.html`
- 服务器按修改时间提供最新文件

## 清理

```bash
bash scripts/stop-server.sh $SESSION_DIR
```

如果会话使用了 `--project-dir`,原型文件会持久化在 `.superpowers/brainstorm/` 中以供日后参考。只有 `/tmp` 会话会在停止时被删除。

## 参考

- 框架模板(CSS 参考):`scripts/frame-template.html`
- 辅助脚本(客户端):`scripts/helper.js`
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall