# 🍷 dsh-palate — 会长大的眼

[![ci](https://github.com/guo6x/dsh-palate/actions/workflows/ci.yml/badge.svg)](https://github.com/guo6x/dsh-palate/actions/workflows/ci.yml) [English](README.md) · [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件

> **设计审查工具量的是固定的尺；dsh-palate 练的是会长大的眼。**

大多数设计评审插件带一套静态规则，用到天荒地老也一样——用一次和用一万次，判断没区别。dsh-palate 相反：它维护一个**会积累的品味语料库**。你喂进去的每个例子、提炼的每条原则，都会让你 agent 的判断更准。**用得越多，眼越毒。**

## 为什么做这个

品味不是天赋，是**看多了练出来的模式识别**。看好的看坏的看够了，规律自己浮出来。dsh-palate 把这件事变成 agent 真能用的机制：

1. **观察** —— 看截图、URL 或设计稿，写下可核对的视觉证据
2. **暂存** —— 把分析变成可审阅的案例/原则候选，而不是直接写入品味库
3. **确认** —— 只有明确的接纳/拒绝决定才会改变语料；被拒绝的想法仍保留，不会污染品味
4. **评审** —— 拿积累下来的品味去评新设计，而不是套通用清单
5. **校正** —— 评审后记录哪些建议真有用；只强化被确认有效的原则，品味才会复利滚起来

## agent 得到的工具

| 工具 | 作用 |
|---|---|
| `palate_intake` | 暂存结构化视觉分析，生成**待确认**的案例/原则候选；它本身绝不改变品味 |
| `palate_candidates` | 查看待确认、已接纳、已拒绝的训练候选及其来源会话 |
| `palate_decide` | 执行用户明确的接纳/拒绝决定；这是候选真正进入品味库的唯一入口 |
| `palate_review` | 把积累的品味（原则 + 相关过往例子）组装成上下文，让 agent 基于*学到的*判断做评审 |
| `palate_feedback` | 用 `review_id` 记录用户是否觉得评审有用、哪些原则被采纳或拒绝；只强化被采纳的原则 |
| `palate_add` | 喂一个例子（好/坏/备注 + 原因 + 标签）进语料库——品味长大 |
| `palate_learn` | 从经验里提炼一条新原则，加进编码品味 |
| `palate_packs` | 查看可选的参考风格包，以及它们是否已经启用 |
| `palate_seed` | 精确启用一个或多个参考风格包，不覆盖现有品味 |
| `palate_list` | 浏览积累的语料库 |
| `palate_principles` | 列出编码原则，按证据数排序 |
| `palate_effectiveness` | 查看哪些原则在真实评审反馈中被采纳或拒绝 |
| `palate_stats` | 积累了多少品味：学了多少例子、提炼了多少原则 |

自带 **12 条基础原则 + 4 个透明的教学案例**作为起始品味（好/坏仪表盘、可读数据表、套路化落地页），第一次评审就有具体证据，开箱即用——然后从这里开始长。

这 4 个起始案例只会在本地品味数据库为空时写入。安装或升级插件不会覆盖已有的品味库。

## 参考风格包：Apple 与 X

`dsh-palate` 还内置两套**按需启用**的视觉参考风格包：

- `apple-product-storytelling` —— 每屏一个产品主体、以产品证据驱动视觉、克制的 CTA 选择，以及安静分段的产品叙事。
- `x-direct-utility` —— 高对比品牌识别、果断的主路径、有序的次级动作，以及几乎不打扰任务的辅助信息。

它们是对 2026-08-27 公开页面观察的透明抽象，不抓取素材、不复用品牌文案，也不是照抄模板。先调用 `palate_packs`，再用 `palate_seed` 明确启用一个或两个包。评审时传 `tag: "apple"` 或 `tag: "x"`：标签会同时过滤**案例**和对应风格的**原则**，而通用原则仍会保留，因此两种风格不会串味。

可以直接让 agent 做：

> 先查看 `palate_packs`，再用 `palate_seed` 启用 `apple-product-storytelling` 和 `x-direct-utility`。分别用 `apple` 标签评审我们的产品发布页、用 `x` 标签评审登录入口；引用实际证据，但不要复制两个品牌的素材、文案或身份识别。

## 视觉品味训练台：观察 → 对照 → 确认

`palate_intake` 故意被设计成**暂存工具**，不是一个偷偷自动学习的按钮。先让 agent 用浏览器或视觉能力真实看过截图/页面，再记录简洁且结构化的分析：层级、字体、色彩、间距、交互，以及其他相关维度。一次 intake 会创建一个案例候选和若干原则候选；在确认前，它们都不会进入语料库。

它还能记录与 Apple、X 或未来参考包的明确对照：

- `aligned` —— 看到的证据支持指定的抽象参考原则
- `conflicts` —— 看到的证据和指定参考原则相冲突
- `insufficient_evidence` —— 截图/页面没有展示足够内容，不能下结论

即使没有启用某个风格包，也可以拿它做研究对照；记录会清楚标成**仅参考**，不会自动启用或注入该包。这样，分析和风格采纳是两件分开的事。

用 `palate_candidates` 把证据和候选 ID 展示给用户。只有用户明确说接纳或拒绝后，agent 才应该调用 `palate_decide`。被接纳的记录会保留训练会话来源；被拒绝的记录仍会留在 `training.md`，团队之后可以复盘当时的判断。

## 原理

```
先用视觉工具或浏览器看截图 / URL
        │
        ▼
palate_intake（结构化观察 + 风格包对照）
        │
        ▼
待确认案例 / 原则候选 ──▶ palate_candidates ──▶ 用户明确接纳或拒绝
        │                                                   │
        └──────────────── palate_decide ◀──────────────────┘
                                  │
              只接纳才写入 ──────┼────── 被拒绝仍留在 training.md 可审计
                                  ▼
                         品味语料库 + 编码原则
                                  │
palate_review（一个设计）──▶ review_id + 已学证据 ──▶ agent 写有据评审
        ▲                                                   │
        └── palate_feedback（采纳/拒绝 + 原因）──▶ 有效性统计 + 强化被采纳原则 ─┘
```

- **存储**：`node:sqlite`（Node ≥ 22 内置），存 `$DSH_HOME/palate/`，外加人可读的 `taste.md` / `principles.md` / `feedback.md` / `training.md` 镜像。零运行时依赖。
- **检索**：评审时按当前设计描述中的词、标签与中文词组对案例排序；没有足够相关的先例时，会明确留空而不是拿最新案例凑数。
- **反馈闭环**：每次 `palate_review` 会保留当时的原则和案例快照；`palate_feedback` 记录结果，`feedback.md` 镜像与面板展示真实采纳/拒绝情况。
- **面板**：可拖拽浮窗展示成长故事——学了多少例子、提炼了多少原则、视觉训练候选队列、最近评审主题、每次评审实际引用的案例，以及最近的判断。
- **配视觉**：先用视觉工具（如 `modlens_read_image`）看截图，或用浏览器看页面，再把证据交给 `palate_intake` 或 `palate_review`。插件本身不会抓 URL、截图，也不会假装看到了原始页面。

## 说实话

这是**积累式检索 + 编码原则 + 显式决定与反馈**，不是模型微调。插件提供学到的品味当上下文，*模型*来写真正的评审；`palate_intake` 不等于学习：只有用户确认后调用 `palate_decide` 才会接纳候选，只有用户/agent 用 `palate_feedback` 明确确认后，原则才获得额外有效性证据。这让判断保持可审计（你能直接读 `taste.md`、`principles.md`、`feedback.md` 和 `training.md`），不用重训任何东西。

## 安装——复制、粘贴、验收

```sh
# GitHub 是当前受支持的发布渠道。
dsh plugin --profile web add github:guo6x/dsh-palate
```

如果 `dsh web` 正在运行，重启它再刷新页面。**当侧边栏底部出现 👁️ 按钮时，安装就完成了。**点开即可看到起始品味、原则、反馈历史和已暂存的训练候选。

要求：DSH web profile、Node ≥ 22。插件本身只用本地 SQLite 存储，不需要账号、API key 或 embedding 服务；但下面的自然语言聊天演示会使用 Harness 当前配置的模型，因此该模型提供方必须有有效凭据。

从本地 checkout 开发？在仓库目录执行 `dsh plugin --profile web add .`。仓库提交了 `lib/` 构建产物，GitHub 安装和本地路径安装都可以直接启动，不需要在安装时执行构建脚本。

## 60 秒确认第一次安装真的生效

先用这条最短路径确认插件已经接入，再开始喂品味：

1. 用上面的命令安装，重启 `dsh web`，新开一个对话。如果输入框要求选择工作区，点击 **选择工作区**，选中或创建一个工作区；如果出现一次性的内测声明，也先继续。
2. 确认当前选中的 Harness 模型有有效的提供方凭据，然后粘贴这段任务：

   > 调用 `palate_stats`，然后用 `palate_review` 评审“一个有 12 张等权 KPI 卡、一个主要营收指标和一张小趋势图的分析仪表盘”。告诉我用了哪些已存的原则和案例，并返回 `review_id`。

3. 确认回复里有起始原则、带依据的证据和 `review_id`。再打开 👁️ 面板，应该也能看到这次评审。

这一步验证插件的有效路径：宿主发现、本地存储、相关案例检索和 Web 展示。插件本身不会发起远程模型请求，但聊天回复依赖 Harness 当前配置的模型；如果回复报告鉴权失败，先检查 👁️ 面板和本地计数，插件可能已经正确安装，只是模型凭据无效。想看到语料真正长大，再继续下面的 90 秒闭环；只有你确实判断建议有用后，才记录 `palate_feedback`。

要看可复制的无密钥运行记录、面板成功信号和排障对照表，请看[首次成功体验说明](docs/first-run-demo.zh.md)。

## 90 秒看见成长闭环

新开一个对话，直接粘贴这个安全、纯本地的任务：

> 给一个信息密集的分析仪表盘建立第一条品味记录。用 `palate_add` 记一个**反例**：“12 张 KPI 卡片视觉权重完全相同，真正的决策信号被淹没”；标签用 `dashboard, hierarchy`。然后用 `palate_review` 评审“一个有 12 张等权 KPI 卡、一个主要营收指标和一张小趋势图的分析仪表盘”，并说明你用了哪些已学原则。

回答应点出匹配到的记录和起始原则，而不是套泛泛的检查清单。打开 👁️ 面板，可以看到案例数增加和新评审出现。如果你真的采纳了一条建议，再让 agent 为该评审记录 `palate_feedback`；只有被确认有用的原则才会增加证据。

### 90 秒安全试训练台

让 agent 已经真实看过一个截图或页面后，直接粘贴：

> 用 `palate_intake` 分析刚刚看过的产品落地页。至少记录层级、字体、色彩、间距、交互五类观察；暂存一个案例候选和最多两条具体原则候选。用 `apple-product-storytelling` 做 `aligned`、`conflicts` 或 `insufficient_evidence` 对照，并引用精确的参考原则。把待确认候选展示给我，**在我明确选择接纳或拒绝前不要调用 `palate_decide`**。

👁️ 面板应出现新的训练会话和待确认数，但案例/原则总数不会变化。等你明确作出决定后，agent 才能调用 `palate_decide`；`training.md` 会保留分析和最终决定。

### 如果看不到 👁️ 按钮

- 确认插件安装在 **web** profile：`dsh plugin --profile web list dsh-palate`。
- 安装后必须重启 `dsh web`；仅刷新浏览器不会加载新的宿主代码。
- 确认 Node 为 22 或更新版本。插件没有其他运行时依赖需要安装。

## 开发

```sh
pnpm install
node build.mjs        # esbuild → lib/index.js（宿主 ESM）+ lib/client.js（ModuleLoader 包）
node tests/smoke.mjs  # 纯逻辑检查（无需浏览器）
```

MIT 协议。欢迎提想法和例子，开 issue。

## 已知限制

- **插件本身不做 embedding 语义匹配** —— 它在本地按标签、关键词与中文词组检索案例；更深的推理由模型基于组装好的上下文完成。
- **反馈需要显式记录** —— 插件不会猜测用户是否采纳了建议；评审完成后调用 `palate_feedback` 才会形成有效性数据。
- **训练决定需要显式确认** —— `palate_intake` 只暂存证据，不会看原始 URL/图片或自动学习；`palate_decide` 必须有清楚的人类接纳/拒绝决定。
- **Markdown 镜像是只读导出**（人工编辑后合并回库在计划中）。
- **视觉靠外援** —— 配一个视觉工具看截图，或用浏览器看 URL，再暂存证据。
- **参考风格包不是克隆包** —— 它保存可观察的布局与层级经验，不包含受保护素材、文案，也不代表参考品牌的每个页面都适合你的产品。