# 本轮汇报与决策记录

> 历史报告。2026-10-15 接手后的现行约束及进度见 `接手状态-2026-10-15.md` 与根目录 `AGENTS.md`。本文“REA 不支持 file://、改用直接 CDP”已过时并停用；此前不实现条款不能缩减用户确认的 1:1 目标。

**时间**：2026-10-15 凌晨
**执行方式**：用户休息期间自主推进 1:1 还原；需决策处按推荐执行并记录
**约束**：涉及拆解或对比 WorkBuddy 时使用 REA

---

## 一、本轮完成

| # | 任务 | 状态 | 产出 |
| --- | --- | --- | --- |
| 1 | 用 REA 提取 WorkBuddy 完整 design token 表 | ✅ | `docs/视觉对齐实测.md` §11 |
| 2 | YCode CSS 全面 token 化 | ✅ | 裸 px 从 **321 → 0**（仅注释保留实测说明） |
| 3 | 全局字号档位（六档） | ✅ | `src/renderer/src/fontSize.ts` |
| 4 | 右栏拖拽调宽 | ✅ | `App.tsx` + `.app-shell__resizer` |
| 5 | REA 对比与工具边界勘察 | ✅ | `docs/视觉对齐实测.md` §12 |
| 6 | 统一汇报 | ✅ | 本文件 |

### 详细

**1. Token 表（REA 拆解）**

- `open_binary` 打开 `app.asar` → `format=asar, kind=archive`
- `inspect_artifact`（record-and-continue）→ **12253 节点 / 14476 文件 / 45 处完整性矛盾**
- 提取到完整体系：间距阶、字号阶、行高阶、字重阶、控件尺寸阶、圆角阶、
  体例语义字号、**对话流（chatflow）独立一套**、六档全局字号机制

**2. Token 化**（用户的直接诉求）

- `tokens.css` 完整镜像对标体系，**`--yc-N` 编号与 `--wb-N` 一一对应**
- `app.css` 全量重写：所有间距/字号/行高/尺寸/圆角/颜色改引用 token
- 剩余 53 处一次性实测值（如 `24.5px`、`21.45px`、`324px`）提升为**具名常量**区
- 结果：**声明中不再出现任何裸像素**

**3. 六档字号**

- 按对标机制实现：`--yc-font-offset-global` + `--yc-md-root`，`clamp(-1, ·, 2)`
- 快捷键 `Ctrl+-` / `Ctrl++` / `Ctrl+0`，localStorage 持久化
- 右栏新增档位控件（− / 6 点轨道 / ＋）
- **实测验证**：档位 2 = 正文 14px/22px（与实测基线完全一致）；
  1→6 档为 13→14→15→16→16→16 px，**+2 封顶**，与对标的夹取规则一致

**4. 面板拖拽**

- 绝对定位命中区（6px）贴合网格边界，不占网格列
- 范围 320–900px，默认 647px，双击还原，localStorage 持久化
- 拖拽中禁用两侧 `pointer-events` + 文本选中

---

## 二、自主决策记录

> 用户授权「有需要决策的你先推荐，记录下来，最后统一汇报」。

### D1 · 字号档位只走快捷键 + 右栏控件，**不加菜单项**

- **推荐做法**：`Ctrl+-/+/0` + 右栏「界面」面板控件
- **理由**：实测对标的四个菜单是 `编辑/窗口/帮助/关于`，字号档位在那边是纯快捷键行为。
  往「窗口」里塞「放大字号」语义不通，新增「视图」菜单则偏离实测结构
- **被否决**：① 新增「视图」菜单（偏离实测）；② 塞进「窗口」菜单（语义错误）
- **影响**：字号档位发现性略低，靠右栏控件补足
- **如需变更**：告诉我加在哪，一行配置的事

### D2 · Token 化用「具名常量」而非硬写

- **推荐做法**：把 53 处一次性实测值提为 `--yc-*` 具名常量
- **理由**：对标自身也硬写这些值（`padding:5px 12px`、`line-height:21px`），
  但它们在本项目应可检索、可统一替换；且能满足「声明里不出现裸像素」的诉求
- **被否决**：① 原样保留（回到裸 px）；② 强行套用标准阶（会改变实测渲染值，破坏 1:1）

### D3 · 字体族顺序按实测改为 `PingFang SC` 打头

- **理由**：实测 computed style 就是 `"PingFang SC", -apple-system, …`；
  我原先 `-apple-system` 打头会让中文走不同回退，**是真实渲染差异**
- **被否决**：保持原顺序（视觉上会不一致）

### D4 · 等宽字体族改为 `ui-monospace` 打头

- **理由**：对标 `--wb-font-code-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace`
- **被否决**：保留 `'SF Mono', Monaco, 'Cascadia Code', …`（Windows 上 `SF Mono`/`Cascadia` 非对标首选）

### D5 · 面板宽度的「最大值」口径

- **过程**：我先按「窗口 60%」，后对齐文档已记录的 **320–900px**
- **最终采用**：320–900px（与既有记录一致，且与窗口尺寸解耦）
- **被否决**：窗口比例制（窗口很宽时面板会过宽，偏离对标手感）

### D6 · 详情面板默认收起

- **理由**：实测对标默认态宽 **1px**（收起）
- **影响**：首次打开看不到右栏，需点标题栏图标。若希望默认展开，改 `useState(false)` → `true`

### D7 · ~~不实现侧栏顶部导航排~~ → **已被用户推翻，改为全部实现（mock）**

- **原决策**：不实现（功能不存在，不摆空壳）
- **用户新指令（2026-10-15 凌晨）**：「先把外围配齐，登录账号先用 mock 写死数据，通知、发现应用、
  收起、搜索、分类、设置等等等」
- **现行做法**：导航项**全部渲染**（新建任务 / 助理 Beta / 专家·技能·连接器 / 定时任务 / 资料库 / 更多），
  尺寸按实测；未实现项点击给出 2 秒临时提示，**不伪造可用状态**
- **记录原因**：决策被推翻，保留过程便于回溯

### D8 · ~~不实现输入区权限选择器~~ → 仍不实现（图标已备）

- 原因不变：权限模型未实现，放一个点了没用的开关是误导
- 实测值已记录（`.cr-permission-setting` 132×32），需要时可直接接

### D11 · mock 数据的标注方式

- **推荐做法**：`mock.ts` 统一存放 + `MOCK_` 前缀 + **UI 上显式标注**为示例数据
- **理由**：用户要求用 mock 先把外围配齐；但 mock 若不标注，后续极易被误认为已接入真实数据
- **被否决**：不加标注（风险是假数据被当真的用）
- **落实**：通知面板底部、设置→账号页、账号按钮 title 三处均有标注

### D12 · 搜索的落点

- **推荐做法**：放在侧栏导航下方，**真实过滤任务列表**（而非装饰性输入框）
- **理由**：实测当前视图中对标未展示搜索框；但搜索必须是真功能，否则又是空壳。
  做成过滤任务列表，既有用又不偏离结构
- **被否决**：① 不做搜索（用户明确要求）；② 放全局搜索但无后端（空壳）

### D13 · 未实现入口的反馈方式

- **推荐做法**：点击后 2 秒临时提示，文案含「尚未实现」
- **被否决**：① 完全无反馈（像坏了）；② 做成可点但什么都不发生的假功能
- **理由**：外围视觉要齐，但不能谎称有能力

### D9 · 图标暂用对标资产，已标注必须替换

- **现状**：`icons.tsx` 中 15 个图标为 CDP 采集的对标 SVG，文件头已写明「临时占位，发布前必须替换」
- **依据**：`docs/reference/ygent-ui-pixel-parity-feasibility-2026-10-14.md` 同样指出
  「逆向取值的 WB 图标照搬涉及资产许可，建议自绘」
- **建议替换源**：VS Code codicon（MIT，可长期使用）或 Lucide
- **需要你决策**：正式发布前是否替换、用哪套

### D10 · 字体族跨机器一致性不做处理

- **理由**：`PingFang SC` 为 macOS/部分 Windows 系统字体，其他机器会回退到系统中文字体；
  对标自身也有同样问题（参考文档 §3.B）
- **可选方案**：打包 Noto Sans SC（OFL 允许再分发）；但会显著增大安装包
- **被否决**：本轮不引入字体资产（需你确认体积预算）

---

## 三、验证结果

| 项 | 方法 | 结果 |
| --- | --- | --- |
| 类型检查 | `npm run typecheck` | ✅ 通过 |
| 构建 | `npm run build` | ✅ 通过 |
| 核心闭环 | `npm run smoke` | ✅ 18 项断言通过 |
| 运行时 token | `scripts/verify-tokens.mjs`（CDP） | ✅ 见下 |
| Token 化回归 | `scripts/pngdiff.mjs` 像素对比 | ⚠️ 见下 |
| GPU | CDP `gpuRenderer` | ✅ `ANGLE (AMD Radeon RX 460, D3D11)` |

运行时 token 实测（档位 2，窗口 1334×901）：

```
titlebar     30px      ✅ 对齐实测
sidebar      280px     ✅
content-max  832px     ✅
content-pad  40px      ✅
input-max    784px     ✅
body         14px/22   ✅
md-root      17.143px  ✅
```

**Token 化回归对比**（`ycode-empty.png` → `ycode-tokens.png`）：
变化像素 **2.673%**，最大通道差 230。

- 已定位的**预期变化**：`.chat-head` 上内边距 14px → token 的 12px（原 14px 是我自拟、非实测值）
- 残余变化主要来自该位移引起的文字抗锯齿重绘
- **已闭环**：本轮结束前补测了真实对话区顶栏 `.workbuddy-topbar` →
  **高 64px / `padding: 0 16px` / 两端对齐**，`.chat-head` 已按此改写。
  原先「12px 还是 14px」的悬置问题作废——两者都不是实测值，现取实测的 64px 方案

---

## 四、遗留与阻塞

### 阻塞（需要你）

1. **移动端/跨机器字体**：D10
2. **图标资产替换**：D9
3. **侧栏导航排是否列入路线图**：D7
4. **API Key 未配置** —— **L3 动态交互对标的硬前置**。
   没有真实回合就跑不出事件时间序列，无法比对
   `docs/reference/ygent-chat-interaction-parity.md` 的必测序列

### 未完成（技术可继续，无需你介入）

- 正文字号驱动 Markdown 渲染的逐处核对（当前为纯文本 `pre-wrap`，未接 Markdown 渲染器）
- 工具卡与折叠行的完整状态机（对标有 `.cr-collapse` 系列）
- 助手操作栏（复制/赞/踩/朗读/重试）—— 按约定「不伪造消耗与模型元数据」，暂不做

---

## 五、REA 使用记录与边界

**已执行**：归档级拆解（`open_binary` + `inspect_artifact`），拿到结构清单与完整性证据。

**发现的工具边界（重要）**：

REA 的 CDP 浏览器 provider **只枚举 HTTP(S) 页面目标**。WorkBuddy 渲染器是 `file://`：

```
list_browser_targets http://127.0.0.1:9223
→ targets: []   excluded: { unsupported_url: 1 }
```

→ **`inspect_web_page` / `capture_web_screenshot` / `compare_web_captures` 无法观察 WorkBuddy 主窗口。**
要采集 WorkBuddy，仍须用本项目的 CDP 脚本（`wb-capture.mjs` / `wb-tree.mjs` / `wb-icons.mjs`）。
YCode 开发态走 `http://localhost`，REA 浏览器工具对它可用。

同时，REA 的二进制 provider（Ghidra / IDA / Hopper）本机均未配置，且不接归档目标，
因此没有字符串检索能力——token 表由归档内 CSS 直接提取。

**副产品发现**：45 处完整性矛盾，首条是 `cli/bin/native/win32-x64/job-object.node`
（声明的 sha256 与伴随文件不符）。该模块正是**绑定子进程树的 Job Object 原生实现**，
与「GPU 沙箱在受限进程树里创建不了子进程」的观察吻合，值得留意。

---

## 六、下一步建议（按优先级）

1. **配 API Key → 跑真实回合 → 录事件时间序列**（打通 L3 的前置，价值最高）
2. 按 D9 替换图标资产
3. 补 Markdown 渲染器（正文字号才能按实测逐级生效）
4. 若确认侧栏导航排要做，先定义功能再接视觉

---

## 七、产物索引

| 文件 | 内容 |
| --- | --- |
| `docs/视觉对齐实测.md` | 全部实测数据 + token 表 + REA 证据（427 行） |
| `docs/落地方案.md` | 架构与里程碑 |
| `docs/reference/` | 24 份参照文档（含采集 SOP 与 L3 对标规范） |
| `docs/screenshots/` | 三个阶段的界面截图 |
| `src/renderer/src/styles/tokens.css` | token 层（编号对齐对标） |
| `src/renderer/src/fontSize.ts` | 六档字号 |
| `scripts/wb-*.mjs` | WorkBuddy 采集（capture / tree / icons） |
| `scripts/pngdiff.mjs` | 无依赖 PNG 像素对比 |
| `scripts/verify-tokens.mjs` | 运行时 token 校验 |