Skip to content

polish: miniapp visuals, chat input UX, agent companion defaults #463

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bobleer merged 1 commit into from
Apr 19, 2026
Merged

polish: miniapp visuals, chat input UX, agent companion defaults #463

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 88 additions & 2 deletions MiniApp/Skills/miniapp-dev/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,59 @@
---
name: miniapp-dev
description: Develops and maintains the BitFun MiniApp system (Zero-Dialect Runtime). Use when working on miniapp modules, Mini Apps gallery, bridge scripts, agent tool (InitMiniApp), permission policy, or any code under src/crates/core/src/miniapp/ or src/web-ui/src/app/scenes/miniapps/. Also use when the user mentions MiniApp, miniapps, bridge, or zero-dialect.
description: Develops, maintains, and generates BitFun MiniApps (Zero-Dialect Runtime). Use when (1) working on miniapp framework code under src/crates/core/src/miniapp/ or src/web-ui/src/app/scenes/miniapps/; or (2) generating / creating / designing a NEW MiniApp for the user — including any request like "做一个小应用 / 生成 MiniApp / 写个 BitFun 小工具 / 创建 mini app". Also triggers on MiniApp, miniapps, bridge, zero-dialect, InitMiniApp, app.fs / app.shell / app.storage, or any work under MiniApp/Demo/ and MiniApp/Skills/.
---

# BitFun MiniApp V2 开发指南
# BitFun MiniApp V2 指南

> **本 Skill 服务两类工作**：
>
> - **维护框架本身** → 阅读下方"代码架构 / Bridge / 权限模型 / window.app API"等章节。
> - **生成一个新的 MiniApp** → **必读** [`design-playbook.md`](design-playbook.md)，并遵循下方"生成新 MiniApp 必读（速查）"章节的硬约束。详细 API 见 [`api-reference.md`](api-reference.md)。

---

## 生成新 MiniApp 必读（速查）

> 完整指南见 [`design-playbook.md`](design-playbook.md)。这里是**不可妥协**的硬约束，AI 在用 `InitMiniApp` 工具创建骨架后**必须**遵守。

### 流程
1. **先问，再做**：用户的目标 / 受众 / 是否需要 node mode / 权限边界 / 是否需要 Tweaks 变体 / 是否多语言 / 是否有视觉参考——任何一项含糊就用 `AskUserQuestion` 问。**不要替用户决定**。
2. **找设计上下文**：先读 `MiniApp/Demo/` 与 `src/crates/core/src/miniapp/builtin/assets/` 中**最贴近形态**的内置应用，复刻它的视觉语言（间距 / 圆角 / 卡片密度 / motif）。**从零 mock 是最后选择**。
3. **声明设计系统**：`style.css` 顶部用注释钉住 palette / typography / radius / motif（参见 playbook §1.3 模板），后续全应用复用。
4. **占位先行 → 早预览**：第一版用占位文本 / 占位图框 / fixture 数据，先在 Toolbox 里跑给用户看，再迭代。
5. **验证**：light/dark × zh/en 共 4 套截图都过；过 playbook §8 的 QA Checklist。

### 反 AI 味（默认禁用，除非用户明确要求）
- ❌ 蓝紫渐变 / "Aurora" 风背景
- ❌ Emoji 当主图标（用描边 SVG 或字母圆形容器）
- ❌ 左侧色条 + 圆角卡片组合
- ❌ 标题下加 1-2px 装饰横线
- ❌ 硬画复杂插画 SVG（用占位框，标注 "Image TBD"）
- ❌ Inter / Roboto 兜底就完事（用 `var(--bitfun-font-sans)` 优先）
- ❌ 12px 以下文字 / hit target < 32px
- ❌ 圆角混用 4/8/12/16（钉 1-2 档全应用统一）
- ❌ 用装饰性 stats / icon / sparkline 填空白（空白是排版问题，不是内容问题）

### 颜色与字体
- **首选** `var(--bitfun-*)` 系列 + fallback，与宿主主题协同（见下文"主题集成"章节的完整变量清单）。
- 一个颜色占视觉权重 60-70%（dominant），1-2 个 supporting，1 个 accent——**禁止给所有色块同等权重**。
- 字号：标题 18-22px / Section 14-15px / 正文 13-14px / Caption 11-12px。

### Tweaks 变体（推荐做法）
对外观/密度/字号/布局的多种合理选择，做成运行时可切换、写入 `app.storage('tweaks')`、右下角浮动小面板"Tweaks"——一份代码服务多种偏好是 MiniApp 的天然优势。详细约定见 playbook §4。

### 占位优于劣质实现
没图标 / 没数据 / 没素材时，用明确的占位（标注尺寸或 "TBD"），并在 README 里登记待补清单——**不要硬画一个糟糕的真实物**。

### 工具型 vs 展示型
绝大多数 BitFun MiniApp 是**工具型**——信息密集、操作短、配色冷静，仿照 `regex-playground` / `coding-selfie` / `git-graph` 的克制感。只有用户明确要"对外展示 / 灵感型 / 作品集"时才放飞视觉。

### 内容守则
- 不为填空白而加内容——空白说明结构应被简化。
- 每个元素都要能回答"为什么在这里"，回答不了就删掉。
- 加新 section / page / 功能前**先问用户**——你不比用户更懂他的目标。

---

## 核心哲学：Zero-Dialect Runtime

Expand Down Expand Up @@ -306,6 +356,42 @@ MiniApp 框架在 V2 之后内置 i18n 支持，开发者**必须**为多语言
- [ ] 注册了 `app.onLocaleChange`，切换语言时重新渲染（包括动态列表、aria-label、title）
- [ ] 持久化数据（`app.storage`）保存语言无关的索引/键，而非已翻译的字符串

## 内置小应用（builtin/assets/*）维护规范

内置小应用通过 `src/crates/core/src/miniapp/builtin/mod.rs` 中的 `BUILTIN_APPS` 数组以 `include_str!` 方式打包进 Rust 二进制；首次启动 / 升级时由 `seed_builtin_miniapps()` 把资源写入用户的 `miniapps_dir/<app_id>/`，并在该目录下写入 `.builtin-version` 标记文件。

**只有当 bundled `version` > on-disk 标记时才会重新 seed**，否则启动时会跳过、用户看到的还是旧版本。

### 修改流程（强制）

凡是修改了 `src/crates/core/src/miniapp/builtin/assets/<app>/` 下任何文件（`index.html` / `style.css` / `ui.js` / `worker.js` / `meta.json`），**都必须**同步在 `mod.rs` 的 `BUILTIN_APPS` 中把对应条目的 `version: N` → `N + 1`。

```rust
// src/crates/core/src/miniapp/builtin/mod.rs
BuiltinApp {
id: "builtin-daily-divination",
version: 14, // ← 改完资源就把这里 +1
...
}
```

未 bump 的后果：
- 已经体验过该小应用的用户（本地有 `.builtin-version` 标记）**不会**收到新版本，无法验证设计 / 修复
- QA / Release 看到的还是旧文件，会误判"代码已合但效果没出来"

### 自检清单

- [ ] 改完 `assets/<app>/*` 任何文件
- [ ] `mod.rs` 中对应 `BuiltinApp.version` 已 +1
- [ ] 本地清掉 `~/.bitfun/miniapps/<app_id>/.builtin-version` 或直接整目录删，再启动验证 reseed 生效
- [ ] meta.json 中的 `version` 字段（用户可见的元数据版本）按需同步（与 reseed 无关，但展示用）

### 提示

- `meta.json` 里的 `version`（默认 1）是给用户看的版本号，**不**驱动 reseed
- 真正驱动 reseed 的是 `mod.rs` 中的 `BuiltinApp.version` 字段（u32）
- 二者最好语义一致：资源有重大更新时同步 bump，便于排查

## 开发约定

### 新增 Agent 工具
Expand Down
256 changes: 256 additions & 0 deletions MiniApp/Skills/miniapp-dev/design-playbook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,256 @@
# MiniApp 设计与生成 Playbook

> 这份 Playbook 用于**生成一个新的 MiniApp**。AI 在使用 `InitMiniApp` 工具创建骨架后，必须遵循本指南完成实现，以避免典型的 "AI 味" 产出。
>
> 维护或修改框架本身的代码请回到 `SKILL.md`，本文件只服务于"造一个具体的小应用"。

---

## 一、生成流程（必走）

### 1. 先问，再做（不少于 4 个问题）

在动笔之前，至少确认以下几件事；任何一项含糊，**先用 AskUserQuestion 工具问清楚**，不要替用户决定：

- **目的与受众**：这个小应用解决什么具体问题？谁会反复使用？
- **形态**：偏工具型（信息密集 / 冷静）还是展示型（视觉激进）？
- **运行模式**：是否需要 `node.enabled = true`（自定义 worker.js）？还是纯前端 + `app.fs/shell/net/storage` 就够？
- **权限边界**：要读写哪些路径？要执行哪些命令？要访问哪些域名？
- **设计参考**：有没有已存在的内置应用 / 截图 / 品牌色作为视觉锚点？没有也告诉我，我会建议参考最贴近的内置应用。
- **变体诉求**：是否需要 Tweaks（运行时可调的颜色 / 密度 / 字号 / 布局）？
- **i18n**：必须 `zh-CN` + `en-US` 全套，还是只服务一种语言？
- **持久化**：哪些状态需要跨会话保留（写到 `app.storage`）？

### 2. 找设计上下文（不要从零 mock）

按优先级取上下文：

1. 用户提供的截图 / 品牌资料 / 现成代码
2. `MiniApp/Demo/` 与 `src/crates/core/src/miniapp/builtin/assets/` 中**最贴近形态**的内置应用——直接 `ls` + `Read` 拿到它的 `style.css`、`index.html`，识别它的视觉语言（间距、圆角、卡片密度、配色）
3. `--bitfun-*` 主题变量（见 SKILL.md 的"主题集成"章节）——所有颜色都优先 `var(--bitfun-xxx, fallback)`

**从零生成是最后选择**——它直接导致千篇一律的"AI 味"产出。

### 3. 先声明你的设计系统（写在 `style.css` 顶部注释中）

在写一行实际样式之前，先用注释明确以下"宪法"，并在整份 CSS 里贯彻：

```css
/* === Design System ===
* Theme: <一句话描述视觉调性，比如 "克制的工具感，深色优先">
* Palette:
* - dominant: var(--bitfun-bg) / var(--bitfun-text)
* - supporting: var(--bitfun-bg-secondary), var(--bitfun-border)
* - accent: var(--bitfun-accent) // 仅用于关键 CTA / 选中态
* Typography:
* - heading: 600, 18-22px
* - body: 400, 13-14px
* - caption: 400, 11-12px, --bitfun-text-muted
* Radius: 8px (cards) / 4px (inputs)
* Motif: <一种重复的视觉元素，例：图标统一放在 24×24 圆角容器里 / 标题左侧 3px 实心色块>
* ===================== */
```

> **一个 motif 比十个零散装饰更有价值**——选定后**全应用复用**，不要每个区块发明新的视觉元素。

### 4. 占位先行 → 早预览

第一次产出**不需要数据/不需要图标也不需要真实内容**：

- 字段用占位文本（"标题占位 / Section A / 12 项"）
- 图片用 `<div class="placeholder">` + 标注期望尺寸
- 图标用 1-2 个字母的圆形单色占位（不要硬画 SVG 插画）
- 数据用 fixture（写一个 `seed.json` 或 worker 里 mock）

完成后立即让用户在 Toolbox 里运行一次，**收反馈再迭代**——拿"junior designer 给 manager 演示"的姿态。

### 5. 验证（每次大改后跑一遍）

- `cargo build`（如果改到了 Rust 端）
- 在 Toolbox 里启动应用，分别截图 4 种状态：light + zh / light + en / dark + zh / dark + en
- 用 Task subagent fork 一个"fresh eyes" review（可以参考 `gstack-design-review` skill），让它对截图列 issue
- 检查清单见本文末"视觉 QA Checklist"

---

## 二、反 AI 味清单（强约束）

下列模式**默认禁用**，除非用户明确要求或上下文严格需要：

| 反模式 | 替代方案 |
|---|---|
| 默认蓝紫渐变 / Aurora 风背景 | 用 `var(--bitfun-bg)` 或单色 + 一处微妙强调 |
| Emoji 当主图标 | inline SVG 占位（描边图标），或 1-2 字母圆形容器 |
| 左侧色条 + 圆角卡片组合 | 整张卡片同色边框 + 顶部细条；或仅靠留白与字重区分 |
| 标题下面加 1px / 2px accent 横线 | 用字重 + 字号 + 留白做层级；横线只在 section 分隔时使用且要全局一致 |
| 硬画复杂插画 SVG | 占位框 + 显式标注 "Image: 256×160, 待用户提供素材" |
| Inter / Roboto / Arial 兜底就完事 | `var(--bitfun-font-sans)` 优先，fallback 写完整：`-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif` |
| 全部色块/字号给同等视觉权重 | dominance：一个颜色占 60-70%，1-2 个 supporting，1 个 accent |
| 文字 < 12px / hit target < 32px | 任何可点击元素 ≥ 32px；正文 ≥ 13px；caption ≥ 11px |
| 每个 section 都用一种新的卡片样式 | 一个 motif 贯穿；不同区块用相同卡片，靠内容区分 |
| 用大量 stats / 装饰性图标填空白 | 留白本身就是设计；空白说明结构应被简化，不是被填满 |
| 圆角随心所欲（4 / 8 / 12 / 16 混用） | 在设计系统里钉 1-2 个圆角档位，全应用统一 |
| 一上来就写 1500 行 ui.js | 早提交早预览；功能成型后再分模块（参考 `MiniApp/Demo/git-graph` 的拆分） |

---

## 三、配色与字体（实操指引）

### 配色

1. **首选**：直接 `var(--bitfun-*)` 系列，让小应用与宿主主题协同。
2. **fallback**：每个 `var()` 都带 fallback，用于导出为独立应用时仍可用。
3. **主题区分**：所有颜色都要在 light / dark 各测一次。可以利用 `[data-theme-type="light"]` 选择器做差异化覆写。
4. **辅助色板**（仅当用户明确需要"专属配色"时使用，否则默认走主题）——参考下方 10 套从内容出发的配色：

| 主题感觉 | 主色 | 辅助 | 强调 | 适合的小应用 |
|---|---|---|---|---|
| Midnight Executive | `#1E2761` | `#CADCFC` | `#FFFFFF` | 商务 / 报表 |
| Forest & Moss | `#2C5F2D` | `#97BC62` | `#F5F5F5` | 自然 / 笔记 |
| Coral Energy | `#F96167` | `#F9E795` | `#2F3C7E` | 营销 / 活动 |
| Warm Terracotta | `#B85042` | `#E7E8D1` | `#A7BEAE` | 文化 / 阅读 |
| Ocean Gradient | `#065A82` | `#1C7293` | `#21295C` | 监控 / 数据 |
| Charcoal Minimal | `#36454F` | `#F2F2F2` | `#212121` | 工具 / 极简 |
| Teal Trust | `#028090` | `#00A896` | `#02C39A` | 健康 / 教育 |
| Berry & Cream | `#6D2E46` | `#A26769` | `#ECE2D0` | 美食 / 生活 |
| Sage Calm | `#84B59F` | `#69A297` | `#50808E` | 冥想 / 写作 |
| Cherry Bold | `#990011` | `#FCF6F5` | `#2F3C7E` | 警示 / 任务 |

### 字体

```css
:root {
--font-heading: var(--bitfun-font-sans, -apple-system, 'Segoe UI', sans-serif);
--font-body: var(--bitfun-font-sans, -apple-system, 'Segoe UI', sans-serif);
--font-mono: var(--bitfun-font-mono, ui-monospace, SFMono-Regular, monospace);
}
```

| 元素 | 字号 | 字重 |
|---|---|---|
| 应用主标题 / 模态标题 | 18-22px | 600 |
| Section 标题 | 14-15px | 600 |
| 正文 | 13-14px | 400 |
| Caption / 辅助 | 11-12px | 400 |
| 等宽（代码 / 数字） | 12-13px | 400, `var(--font-mono)` |

### 间距与圆角

- 间距档位：`4 / 8 / 12 / 16 / 24 / 32`，挑 4 个用，不要全用。
- 圆角档位：`var(--bitfun-radius)`（卡片）+ `var(--bitfun-radius-lg)`（浮层）；输入框可固定 4-6px。
- 卡片内边距：紧凑 12px / 标准 16px / 宽松 20px——**全应用统一**。

---

## 四、变体优先：Tweaks 模式

> 灵感源：在最终用户那里，"一份代码服务多种偏好"才是 MiniApp 的天然优势。

### 何时用 Tweaks

- 颜色 / 密度 / 字号 / 圆角等"看上去合理的多种选择"——做成可切换；
- 实验性布局 A/B；
- 语义命名（"专家模式" / "新手模式"）；
- 默认 4-6 项，不要堆超过 10 项（多了用户不会用）。

### 实现约定

1. **存储**：使用 `app.storage`，key 固定为 `tweaks`，结构是扁平 JSON。

```javascript
const DEFAULT_TWEAKS = {
density: 'standard', // 'compact' | 'standard' | 'cozy'
accent: 'theme', // 'theme' | 'coral' | 'teal' | ...
mono: false, // 主标题用等宽字体
};

async function loadTweaks() {
const saved = await app.storage.get('tweaks');
return { ...DEFAULT_TWEAKS, ...(saved || {}) };
}

async function setTweak(key, value) {
const next = { ...current, [key]: value };
current = next;
await app.storage.set('tweaks', next);
applyTweaks(next);
}
```

2. **应用方式**：`applyTweaks` 把当前值写到 `<html data-tweak-density="compact">` 这种属性，CSS 用属性选择器响应——不要用 inline style 喷。

3. **UI 入口**：右下角悬浮齿轮按钮，点开一个小面板列出可调项；默认收起；面板标题就叫 "Tweaks"。

4. **i18n**：Tweak 的 label/option 文案也要进 i18n 表。

5. **不要放业务设置**：业务相关偏好（如 "过滤已读"）应放在主 UI 里，Tweaks 只服务"看起来怎么样"这一类纯外观选择。

---

## 五、占位策略（"placeholder > bad attempt"）

| 缺什么 | 怎么占位 | 何时替换 |
|---|---|---|
| 图片 | `<div class="placeholder ph-img">256×160</div>` 灰底 + 尺寸文字 | 用户提供素材，或在 README 待补清单中登记 |
| 图标 | 1-2 字母圆形 mono 容器 / 描边线性 SVG | 用户给定品牌图标后替换 |
| 真实数据 | `seed.json` fixture / `app.ai.complete` mock 一段 demo | 接入真实数据源后切换 |
| 复杂插画 | 占位框 + 文字标注 "Illustration TBD" | **不要**自己用 SVG 硬画 |
| 长文案 | "标题占位 · Headline placeholder" | 用户审过 wireframe 后再填真实文案 |

**记账**：在 `meta.json.description` 末尾或 `README.md` 顶部，列一个"待补素材清单"，让用户清楚哪些是占位。

---

## 六、内容守则

1. **不要为填空白而加内容**——空白是排版问题，不是内容问题。
2. **每个元素都要能回答"为什么在这里"**——回答不了就删掉。
3. **加新 section / 新 page / 新功能前先问用户**——你不比用户更懂他的目标。
4. **避免数据噪音**：无意义的统计数字、装饰性图标、伪造的 sparkline 都不要加。
5. **写文案要诚实**：宁可写"功能开发中"也不要伪造数据/截图骗用户。

---

## 七、与 BitFun 工具型 MiniApp 的契合度

绝大多数 BitFun 用户产出的小应用是**工具型**（regex 调试 / git 视图 / 编码自拍 / 计算器…），它们的设计调性应当：

- 信息密度高、操作路径短
- 配色冷静（首选 `--bitfun-*` 主题）
- 反对"营销页式大字 + 大图 + 渐变"
- 仿照 `regex-playground` / `coding-selfie` / `git-graph` 的克制感

只有当用户明确说"我要做一个对外展示用的 / 灵感型 / 作品集型"小应用时，才考虑放飞视觉表达。

---

## 八、视觉 QA Checklist（每次产出后逐条检查）

- [ ] light / dark 两套主题都跑过，无白底飘黑字 / 黑底飘灰字
- [ ] zh-CN / en-US 切换无文本溢出 / 截断
- [ ] 所有可点击元素 hit target ≥ 32px
- [ ] 没有 12px 以下文字
- [ ] 长标题换行后装饰元素位置仍正确
- [ ] 边距 ≥ 12px，多列对齐一致
- [ ] 没有左侧色条 + 圆角卡片
- [ ] 没有标题下细装饰线（除非全局一致设计）
- [ ] 没有未替换的 emoji 主图标
- [ ] 没有 placeholder 文字遗留在生产代码里（"Lorem ipsum" / "TODO" / "占位"）
- [ ] `meta.json` 的 `i18n.locales` 至少包含 zh-CN 和 en-US
- [ ] `permissions.fs/shell/net` 是最小可用集（不滥用 `{workspace}` 或 `*`）
- [ ] Tweaks 默认值能让小应用立刻可用，不强迫用户先去调
- [ ] README 或 description 末尾登记了待补素材

---

## 九、参考产物

完整体现以上原则的内置/示例小应用：

- `src/crates/core/src/miniapp/builtin/assets/regex-playground/` — 工具型，单 motif（"/"包裹的 pattern row），克制配色
- `src/crates/core/src/miniapp/builtin/assets/coding-selfie/` — 数据可视化，使用 worker，i18n 完整
- `src/crates/core/src/miniapp/builtin/assets/gomoku/` — 交互型，主题切换 + i18n + 持久化范例
- `MiniApp/Demo/git-graph/` — 复杂应用拆模块的范例（`ui/components`, `ui/panels`, `ui/services`）
- `MiniApp/Demo/icon-design-system/` — 设计系统型应用范例

读它们的 `style.css` 顶部注释和 `meta.json` 的 `i18n` 块，是最快理解"BitFun 味道"的方式。
Loading
Loading