docs: separate design reference queue
- 将不直接执行的 process-reference 文档迁入各域 reference 目录 - 更新 design/README、AGENTS 和总序文档，固定 process/draft/reference/done 目录语义 - 修正活跃文档中指向旧 process 位置的参考链接 验证：git diff --check；codegraph sync .
This commit is contained in:
lix-2026
@@ -0,0 +1,139 @@
|
||||
# Wolai-aline 对标测试流程 v1
|
||||
|
||||
> 状态：reference / active workflow
|
||||
>
|
||||
> 本流程用于所有以 Wolai 体验复刻、对标、aline/alignment 为目标的任务。目标不是只做出类似文案，而是用真实 Wolai 行为和本地 `3000` 行为做可复现对比，形成可回归的 smoke 与截图证据。
|
||||
|
||||
## 适用范围
|
||||
|
||||
凡任务描述包含以下任一意图，默认进入本流程：
|
||||
|
||||
- `wolai-aline`、`wolai-align`、`Wolai 对标`、`复刻 Wolai`、`恢复 Wolai 体验`。
|
||||
- 需要把本地 `http://127.0.0.1:3000` 的页面、Sidebar、搜索、编辑器、浮层、菜单、快捷键或交互状态对齐 Wolai。
|
||||
- 需要比较 Wolai 页面与本地实现的截图、DOM、键鼠行为或浏览器状态。
|
||||
|
||||
## 固定资源
|
||||
|
||||
- 本地入口：`http://127.0.0.1:3000/`。
|
||||
- Wolai 参考页 / 当前授权 Hermes 测试页：`https://www.wolai.com/liaibo/ikFSSM1a4GgvmHBYFCNfVd`。
|
||||
- Wolai owner 登录态 Chrome profile：`/mnt/Data1T/mnote/tmp/wolai-playwright-profile`。
|
||||
- Chrome 可执行文件：`/opt/google/chrome/chrome`。
|
||||
- 对标证据输出根目录：`/mnt/Data1T/mnote/tmp/wolai-editor-parity/`。
|
||||
- 当前可复用 smoke 示例：`/mnt/Data1T/mnote/scripts/task128-rust-web-wolai-search-modal-smoke.js`。
|
||||
|
||||
## 安全边界
|
||||
|
||||
- 默认优先对 Wolai 做只读操作：打开页面、点击入口、hover、打开/关闭菜单、截图、DOM 读取、输入搜索关键词。
|
||||
- 当前 Hermes 测试页 `https://www.wolai.com/liaibo/ikFSSM1a4GgvmHBYFCNfVd` 已授权用于 Wolai-aline 编辑器对标；当任务需要真实编辑行为时，可以执行最小范围编辑测试。
|
||||
- 编辑测试必须记录编辑前后截图、动作链、输入内容和是否已清理；测试内容优先使用唯一标记，例如 `[mnote-aline-test-时间戳]`。
|
||||
- 即使在 Hermes 测试页，也禁止未经确认地删除、移动、归档、发布、评论、改权限或批量修改既有非测试内容。
|
||||
- 其他 Wolai 页面仍默认只读；如需写入，必须先由用户提供沙盒页 URL 和明确授权。
|
||||
- 遇到登录、滑块验证或登录态失效，不绕过验证；记录阻塞并让用户介入。
|
||||
- 登录态 profile 只放在 `tmp/` 这类 git ignored 路径，不提交、复制或打印敏感 cookie/token。
|
||||
|
||||
## Codex skill
|
||||
|
||||
后续 Wolai-aline 任务必须启用本机 skill：`/home/lix/.codex/skills/wolai-aline`。该 skill 是本流程的执行入口，负责强制差异矩阵、截图复核、subagent 浏览器取证和失败模式沉淀。
|
||||
|
||||
## 标准流程
|
||||
|
||||
1. 明确小任务
|
||||
|
||||
从设计稿、缺陷反馈或用户描述中抽出一个可验证的小任务。任务必须能用具体行为描述，例如“侧栏搜索图标打开全局搜索 modal 且不跳转”“Ctrl+P 在 modal 打开时关闭 modal”。
|
||||
|
||||
2. 先取 Wolai 基线（必要时编辑）
|
||||
|
||||
浏览器测试必须交给 subagent 执行。subagent 默认只读；当任务明确需要编辑器行为时，可在当前 Hermes 测试页进入受控 editable-test mode，记录 Wolai 的真实行为、DOM 线索、截图路径、编辑内容和不可验证项。
|
||||
|
||||
Wolai 基线至少记录：
|
||||
- 打开入口：哪个按钮、菜单、快捷键或区域触发。
|
||||
- 关闭入口：快捷键、Esc、遮罩、关闭按钮、再次触发等是否有效。
|
||||
- URL 是否变化。
|
||||
- 关键控件形态和状态：开关、下拉、按钮、菜单、输入框、焦点态、选中态、disabled 态。
|
||||
- 关键文本只是辅助证据，不能替代控件形态和交互状态。
|
||||
- 截图保存到 `/mnt/Data1T/mnote/tmp/wolai-editor-parity/<task>/`。
|
||||
|
||||
3. 写 RED smoke
|
||||
|
||||
在本地实现前，先新增或扩展 `scripts/task*-smoke.js`。smoke 必须在当前实现上失败，并且失败原因要对应缺失行为。
|
||||
|
||||
smoke 断言优先级：
|
||||
- 行为断言：打开、关闭、URL 不跳转、焦点、快捷键、遮罩点击。
|
||||
- DOM 语义断言：`role`、`aria-*`、`data-testid`、`data-*` 状态。
|
||||
- 视觉状态代理断言：开关开启/关闭、下拉当前值、结果行存在、hover/active class。
|
||||
- 文案断言：作为补充，不能单独作为通过依据。
|
||||
|
||||
4. 小范围实现
|
||||
|
||||
只改当前任务直接相关的文件。涉及 `3000` 当前主入口时优先检查 `rust/crates/mnote-web/`；不要把长期语义塞进临时 compat 或前端第二份真相。
|
||||
|
||||
若修改 Rust SSR 常量或样式，需要重启 `npm run desktop:hot` 或对应 `mnote-web` 进程后再跑浏览器 smoke，避免测到旧二进制。
|
||||
|
||||
5. 本地验证
|
||||
|
||||
至少运行：
|
||||
- 当前任务 smoke，例如 `node scripts/task128-rust-web-wolai-search-modal-smoke.js`。
|
||||
- 与改动范围匹配的格式化/单测，例如 `cd rust && cargo fmt -p mnote-web --check && cargo test -p mnote-web`。
|
||||
|
||||
如有 CSS 尺寸、SSR 输出、页面入口等护栏测试失败，优先修实现或压缩新增样式，不随意放宽阈值。
|
||||
|
||||
6. subagent 对标复测
|
||||
|
||||
实现后再次派 subagent 做浏览器对标。subagent 负责：
|
||||
- 用 Wolai owner/profile 或公开态取参考截图。
|
||||
- 用本地 `3000` 执行同一动作链。
|
||||
- 记录 DOM 状态、URL、截图路径、剩余差异。
|
||||
- 不修改源码，不清理截图，不还原文件。
|
||||
|
||||
7. 主线程复核截图
|
||||
|
||||
主线程必须查看或复核 subagent 产出的 Wolai 与本地截图。不能只根据 subagent 的“通过”结论或文本断言宣布对齐。
|
||||
|
||||
复核重点：
|
||||
- 控件类型是否一致，例如 switch 不能误做成普通 pill button。
|
||||
- 开启/关闭、选中/未选中、hover/active 等状态是否一致。
|
||||
- 打开/关闭路径是否一致，例如同一入口不应跳转到另一页面。
|
||||
- 快捷键是否是 toggle 还是单向打开。
|
||||
- 结果列表、命中高亮、空态、占位符是否符合当前任务验收范围。
|
||||
|
||||
8. 汇报
|
||||
|
||||
最终汇报必须包含：
|
||||
- 改动文件。
|
||||
- RED/GREEN 验证命令。
|
||||
- Wolai 与本地截图绝对路径。
|
||||
- 已对齐项和剩余差异。
|
||||
- 未执行或受阻的验证原因。
|
||||
|
||||
## Subagent 浏览器测试模板
|
||||
|
||||
```text
|
||||
请执行 Wolai-aline 浏览器对标测试，不要修改源码。默认只读；如任务明确要求编辑器行为，可在当前 Hermes 测试页做最小编辑验证。禁止删除、移动、归档、发布、评论、改权限或批量修改既有非测试内容。
|
||||
|
||||
任务：<一句话描述当前对标行为>
|
||||
Wolai URL: https://www.wolai.com/liaibo/ikFSSM1a4GgvmHBYFCNfVd
|
||||
Wolai profile: /mnt/Data1T/mnote/tmp/wolai-playwright-profile
|
||||
本地 URL: http://127.0.0.1:3000/
|
||||
输出目录: /mnt/Data1T/mnote/tmp/wolai-editor-parity/<task>/
|
||||
|
||||
请验证：
|
||||
1. Wolai 中该行为的打开入口、关闭入口、URL 变化、关键 DOM/视觉状态。
|
||||
2. 本地 3000 中同一行为是否一致。
|
||||
3. 保存 Wolai 和本地截图。
|
||||
4. 回报截图绝对路径、通过/失败结论、剩余差异。
|
||||
|
||||
遇到登录/滑块不要绕过，直接报告需要用户介入。
|
||||
```
|
||||
|
||||
## 当前已固化样例：搜索 modal
|
||||
|
||||
当前实现已用 `task128-rust-web-wolai-search-modal-smoke.js` 固化以下行为：
|
||||
|
||||
- 顶栏搜索按钮打开同一个搜索 modal。
|
||||
- 侧栏左上搜索入口打开同一个搜索 modal，不跳转 `/search`。
|
||||
- 搜索选项包含 `仅匹配标题`、`精确匹配`、`按编辑时间`、`按创建时间`、`页面内搜索`。
|
||||
- `仅匹配标题` 和 `页面内搜索` 是 `role="switch"` 且默认 `aria-checked="true"`。
|
||||
- `Ctrl+P` 在 modal 打开时关闭 modal。
|
||||
- 结果数量、快捷键提示、空态/结果区域可被 smoke 捕获。
|
||||
|
||||
历史教训：不能只检查 modal 文案。上一次搜索 modal 先误把 Wolai 的 switch 做成普通 pill button，截图复核后才发现。因此后续 Wolai-aline 任务必须把截图复核写入验收，而不是把 subagent 文本结论当作最终证据。
|
||||
Reference in New Issue
Block a user