From 9c351b08d3219fae47272e14d1fb23973c9827b6 Mon Sep 17 00:00:00 2001 From: qiaoqichao Date: Thu, 1 Oct 2026 09:39:08 +0800 Subject: [PATCH] =?UTF-8?q?docs(v2):=20=E8=AE=B0=E5=BD=95=E6=B5=8F?= =?UTF-8?q?=E8=A7=88=E5=99=A8=E9=AA=8C=E8=AF=81=E7=AC=AC=E4=BA=8C=E7=AF=87?= =?UTF-8?q?=E4=B8=8E=20F11=20=E5=89=A9=E4=BD=99=E9=83=A8=E5=88=86=E7=9A=84?= =?UTF-8?q?=E6=94=B6=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 17 新增「浏览器验证（第二篇）：AI 预审 / 历史经验加工」：覆盖的交互、 点通过程中发现并修掉的 2 个缺陷（预审面板不刷新、候选行同 id 连开多行）、 写演示库的副作用清单，以及本数据集下仍点不到的 3 处（沙盘勾选联动、 来源事件勾选、reviewer 视角的审核发布）与 2 处口径待确认项。 15 第 7 节改为本轮交接：F11 三个表面均已由真实 Chrome 走过；F27/F29/F30 与新证据路径；下一任务只剩需要用户或外部输入的部分。 Co-Authored-By: Claude Code --- docs/v2/15-development-handoff.md | 78 ++++++++++++++++------------ docs/v2/17-batch-delivery-records.md | 73 ++++++++++++++++++++++++-- 2 files changed, 115 insertions(+), 36 deletions(-) diff --git a/docs/v2/15-development-handoff.md b/docs/v2/15-development-handoff.md index ab2b8d3..f89157f 100644 --- a/docs/v2/15-development-handoff.md +++ b/docs/v2/15-development-handoff.md @@ -105,23 +105,24 @@ docs/project-process/README.md、XINGBANG-ADAPTATION.md，执行 git status --sh > 交付定义与四批顺序以 [16 交付纠偏规格](16-delivery-corrections.md) 为准； > 下表的"已交付"只表示该任务包的代码与测试存在，不再表示产品功能可用。 -- 日期：2026-10-01（**纠偏第四批实施轮**；第三批见 `ae89462`/`3e15bda`， - 第二批见 `2e7e194`/`01c88af`，第一批见更早提交）。 +- 日期：2026-10-01（**F11 剩余部分实施轮**；纠偏第四批见 `f775c6c`/`4720d72`， + 第三批见 `ae89462`/`3e15bda`，第二批见 `2e7e194`/`01c88af`，第一批见更早提交）。 - 仓库：`F:/mini-OpenClaw-v2`；远程 `http://192.168.10.111:3000/qiaoqichao/mini-openclaw-v2.git` （OQ-06 Q2 的远程归属已定案；端口/资源/CI 三问仍 open；**本轮未推送**）。 -- 完成范围：**纠偏第四批「接通评审反馈与改进发布」**——会议结果从页面录入并与材料版本对照； - 改进候选接上**真实知识发布入口**，发布后新运行用新版本、旧运行仍可回放。 - 界面并入「轨迹复盘」模块（`/trajectory-center`），**不新增第四个导航入口**。 - 本轮另**首次做了真实浏览器端到端验证**（新增可选脚本 `scripts/browser-e2e.cjs`）， - 并因此发现并修掉 5 个源码守卫与生产构建都看不出的缺陷——其中一个是**三个模块页 - 在浏览器里根本渲染不出面板**（`/projects` 读错字段），见 17「浏览器验证发现的问题」。 - `scripts/verify.py` **14 项检查**全通过（新增 `improvement-panel-ui` 源码守卫）。 +- 完成范围：把 **F11 剩下的两个表面**在真实 Chrome 里逐项点完——`/prescreen-workbench` + （点「开始 AI 预审」走完真实执行链、依据抽屉与焦点回位、概率口径、沙盘空态）与 + `/experience-center`（重建时间线、请求提炼的拒绝与失败路径、候选卡与修订入口、身份门禁）。 + 新增可选脚本 `scripts/browser-e2e-modules.cjs`（**42 项检查全通过** + 4 张截图）。 + 点通过程中发现并修掉 **2 个源码守卫与生产构建都看不见的缺陷**： + ① 发起预审后结果面板不重载（新运行与结果都读不到，而徽标写着"结果会自动刷新"）； + ② 候选行只用 `card.id` 作 key 与展开标记（React key 冲突，点一行连开 4 行面板）。 + 见 [17 四批交付记录](17-batch-delivery-records.md)「浏览器验证（第二篇）」。 - 验证入口：`cd F:/mini-OpenClaw-v2 && backend/venv/Scripts/python.exe scripts/verify.py`； - 本轮证据：`test-evidence/20261001-030127-ff59d7e/`（14/14 PASS，backend-unit 572 项）。 - 浏览器验证证据：`node scripts/browser-e2e.cjs` → `test-evidence/e2e-batch4/`（19/19 PASS + 截图）。 - **该脚本刻意不接入 verify.py**（verify 不应依赖浏览器），需手动跑。 -- 测试规模：全量 **572 项** unittest 无回归（新增 `test_improvement_release.py` 4 项 + - `test_improvements.py` 1 项）。 + 本轮证据：`test-evidence/20261001-093541-c880f40/`（**14/14 PASS**，`backend-unit` 全量 572 项， + 证据绑定代码提交 `c880f40`）。 + 浏览器验证证据：`node scripts/browser-e2e-modules.cjs` → `test-evidence/browser-e2e-modules/` + （42/42 PASS + 截图）；`node scripts/browser-e2e.cjs` 仍走轨迹复盘表面。 + **两个脚本都刻意不接入 verify.py**（verify 不应依赖浏览器），需手动跑。 - 卡片验收对照（详见 [17 四批交付记录](17-batch-delivery-records.md) 第四批）： - **AC-57**：端点把 `_knowledge_publisher` 注入 `improvements.transition`；publisher 用候选声明的 `proposed_revision_ref` **精确**定位草稿（`组件id@版本`），调 `knowledge_cards.publish` @@ -136,20 +137,33 @@ docs/project-process/README.md、XINGBANG-ADAPTATION.md，执行 git status --sh 需端点后按 17 的操作步骤补一次真实调用；在此之前不得宣称"真实提炼已跑通"。 - **F18** 例外边界未进入可求值条件语言；**F19** 卡片适用条件不参与运行内逐项判定。 （同第二批，本批未动。） - - **F11 部分关闭**：`/trajectory-center`（含本批的会议结果录入与改进面板）已在**真实 Chrome** - 里端到端走过并通过（`scripts/browser-e2e.cjs`，19/19，有截图）。**仍开放的部分**： - ① `/experience-center`、`/prescreen-workbench` 只验到"能渲染"，交互没有逐项点过； - ② 该脚本不在 `verify.py` 里，需手动跑（本机 Chrome + 一次性 `--no-save puppeteer-core`）； - ③ 无视觉基线比对、无多分辨率、无键盘/读屏检查。 + - **F11 更新（本轮）**：三个模块表面现在都在**真实 Chrome** 里走过—— + `/trajectory-center`（第四批，`browser-e2e.cjs` 19/19）、`/prescreen-workbench` 与 + `/experience-center`（本轮，`browser-e2e-modules.cjs` 42/42）。**仍开放的部分**： + ① **推进沙盘的勾选联动**：演示方案的维度不含假设动作目标维度（`DC-CASH`/`DC-TITLE`）， + 服务端返回 0 个动作，界面按设计给诚实空态（基线演示值 42% 已渲染并断言）； + ② **来源事件勾选**：演示项目没有结构化问询/决定记录，时间线为 0 个事件； + ③ **reviewer 视角的「审核发布」**：reviewer 的 `/projects` 只授权到 DEMO-C， + 而 DEMO-C 没有知识候选，已用 admin 作对照（有「隔离评测」、无「审核发布」）； + ④ 该脚本不在 `verify.py` 里，需手动跑（本机 Chrome + 一次性 `--no-save puppeteer-core`）； + ⑤ 无视觉基线比对、无多分辨率、无键盘/读屏检查。 深色底对比度仍是守卫内按 WCAG 实算，不是实测。 - **F27（新）浏览器验证暴露的缺陷已修但防线不全**：本批靠浏览器发现并修了 5 个缺陷 （见 17「浏览器验证发现的问题」）。其中只有"导航名折行"补进了源码守卫； 其余 4 个（读错 `/projects` 字段、漏传 `identity`、重复 React key、JSX 里的字面量 `**`） 目前只有 `browser-e2e.cjs` 覆盖，而它不在强制门禁里——**这类回归没有自动防线**。 是否把浏览器 E2E 接进 `verify.py`、是否把 `puppeteer-core` 写进 `package.json`，需人决策。 - - **F28（新）模拟/演示数据随验证累积**：`scripts/xingbang_batch4_smoke.py` 与 - `scripts/browser-e2e.cjs` 都**真的写演示库**（新建卡片、会议结果），重复运行会累积脏数据。 - 两者都在脚本头注明了这一点。 + - **F28（新）模拟/演示数据随验证累积**：`scripts/xingbang_batch4_smoke.py`、 + `scripts/browser-e2e.cjs` 与 `scripts/browser-e2e-modules.cjs` 都**真的写演示库** + （新建卡片、会议结果、预审运行、时间线、失败提炼记录），重复运行会累积脏数据。 + 三者都在脚本头注明了这一点；本轮新增 6 条 DEMO-B 预审运行与 3 条失败提炼记录。 + - **F29（新）候选列表把同一卡片的多个版本行都按"已发布"列出**： + `knowledge_cards.list_cards` 同时返回 `component_draft` 与 `component_version` 行， + 同一 `card.id` 出现 3–4 行（v1.0.0 与 v1.0.1 都标"已发布"），界面不显示 `release` + 指针当前指向哪一版。"一行 = 一个存储记录"还是"一行 = 一张卡片的当前状态"需产品确认后再改。 + - **F30（新）「请求提炼」在"没有来源也没有要求"时按钮仍可点**：服务端按契约 422 并给出理由、 + 界面如实显示；但同文件里「形成草稿修订」「保存样本到草稿」都按必填项禁用，口径不一致。 + 按最小改动只验证未改。 - **F20** 新旧经验入口并存（工作台旧「评审经验」页签）；**F21** 首页默认路由已变更 `/` → `/assistant`。两者都需确认后处理。 - **F23（新）改进端点仍无角色门禁**：既有候选/方案端点对评测与发布有 `role()` 门禁， @@ -167,17 +181,15 @@ docs/project-process/README.md、XINGBANG-ADAPTATION.md，执行 git status --sh - **F8** Docker 运行时冒烟未实测（本机 Docker Desktop 守护进程不可达）。 - **F6** OQ-06 Q3–Q5：端口冲突核验、运行资源、Gitea CI 是否启用仍 open。 - **F12/F14/F16** 仍有效；**F13** 已由第一批关闭。 -- 下一任务：四批纠偏已全部有交付（均记**部分完成**）。**F11 已可自行推进** - （本机有 Chrome，脚本已入库，无需外部环境）；继续推进前需你定的两件事： - ① 是否把浏览器 E2E 接进 `verify.py` / 写进 `package.json`（F27）； - ② 是否继续用真实浏览器把 `/experience-center`、`/prescreen-workbench` 也逐项点完（F11 剩余部分）。 - 补 **F17** 仍需要你提供模型端点与调用时机。不要为了推进而把演示当验收。 +- 下一任务：四批纠偏已全部有交付（均记**部分完成**），F11 的可自行推进部分**本轮已做完**。 + 剩下的都需要你或外部输入：① 是否把浏览器 E2E 接进 `verify.py` / 写进 `package.json`（F27）； + ② F29/F30 的产品口径；③ F17 的模型端点与调用时机。 + 不要为了推进而把演示当验收。 - 待输入：模型端点与调用时机（F17）；真实数据/制度/会议标签映射与客户身份权限（M5/M6）； Laya 硬件与中文效果需实机探测；Jev 端点与凭据。 -- Git：本轮在 `codex/xingbang-v2-model-field-fix` 分支有 **3 个提交**，**均未推送**： - - `f775c6c` —— `feat(v2): 纠偏第四批——会议结果录入与改进发布接真实知识发布入口` - - `ff59d7e` —— `docs(v2): 第四批交接记录补记本轮提交号` - - `4720d72` —— `fix(v2): 浏览器端到端验证——修掉模块页在浏览器里渲染不出内容的缺陷` - 核对命令 `git log --oneline -6`。**不在这里写死 HEAD**：交接文档自身的提交会成为新的 - HEAD，写死必然过期；以上三个是本轮的实质提交，其后可能还有仅改文档的提交。 +- Git：本轮在 `codex/xingbang-v2-model-field-fix` 分支的实质提交是 + **`c880f40`（fix：面板不刷新 + 候选行同 id 连开多行，含新脚本与 2 组源码断言）**， + 其后还有仅改文档的提交（本文件与 17）。**本轮与之前各轮一样均未推送**。 + 第四批的提交仍为 `f775c6c`/`ff59d7e`/`4720d72`。核对命令 `git log --oneline -12`。 + **不在这里写死 HEAD**：交接文档自身的提交会成为新的 HEAD，写死必然过期。 不得从旧恢复点 4d5a420 推断最新版本已备份。 diff --git a/docs/v2/17-batch-delivery-records.md b/docs/v2/17-batch-delivery-records.md index 9b679b0..92c955a 100644 --- a/docs/v2/17-batch-delivery-records.md +++ b/docs/v2/17-batch-delivery-records.md @@ -254,8 +254,9 @@ XINGBANG_LOCAL_MODEL_KEY=<你的 DeepSeek API Key> ### 剩余缺口 -- **界面仍未经浏览器验证（F11 未变）**：深色导航与三个模块都只有"源码守卫 + 生产构建 + 代码走查" - 三层证据，**没有浏览器点击或截图**；原型本身也没有视觉门禁（04-ui-spec §7 已声明不以原型替代验收）。 +- **界面仍未经浏览器验证（F11 未变；后由文末「浏览器验证（第二篇）」补齐）**：深色导航与三个模块都 + 只有"源码守卫 + 生产构建 + 代码走查"三层证据，**没有浏览器点击或截图**； + 原型本身也没有视觉门禁（04-ui-spec §7 已声明不以原型替代验收）。 深色导航的文字对比度已改为**机械断言**（守卫内按 WCAG 公式实算，阈值 AA 4.5:1）： 未选中 12.03:1、选中 9.49:1、muted 8.37:1、品牌 13.91:1，全部达标——但这证明的是配色可用， 不等于版面在实机上的观感已验收。 @@ -369,7 +370,8 @@ AC-53 又要求恰好三个模块入口。`AgentNav.tsx` 未改动。 - **F11 对本批两个表面已关闭，但未全面关闭**：`/trajectory-center` 已由 `scripts/browser-e2e.cjs` 在真实 Chrome 里走过（19/19），有截图；`/experience-center` 与 `/prescreen-workbench` - 只验证到"能被本次路由改动修好、能渲染"，其自身交互没有逐项点过，**仍记 F11 未闭合**。 + 当时只验证到"能被本次路由改动修好、能渲染"，其自身交互没有逐项点过，**当时仍记 F11 未闭合** + （这两个表面已在文末「浏览器验证（第二篇）」里逐项点过，并因此修掉 2 个缺陷）。 另外该脚本**不在 `verify.py` 里**，也就是说这条证据不会随强制门禁自动重跑—— 它需要本机 Chrome 与一次性 `npm i --no-save puppeteer-core`。 - **浏览器验证只覆盖到"能走通"这一层**：没有做视觉回归（无基线截图比对）、没有多分辨率、 @@ -386,3 +388,68 @@ AC-53 又要求恰好三个模块入口。`AgentNav.tsx` 未改动。 - **题库/编排无真实发布入口**：已按 409 诚实拒绝，非假接通；需要时另行设计。 - **浏览器 E2E 尚未固化为项目门禁**：是否把它接进 `verify.py`、是否把 `puppeteer-core` 写进 `package.json`，是产品/工程决策，本批**没有替用户决定**，只提供可选脚本。 + +--- + +## 浏览器验证（第二篇）：AI 预审 / 历史经验加工 + +状态：**F11 剩下的两个表面已在真实 Chrome 里逐项点过**（第四批只走过 `/trajectory-center`）。 +脚本 `scripts/browser-e2e-modules.cjs`，**42 项检查全通过、0 失败**，截图与 `result.json` 在 +`test-evidence/browser-e2e-modules/`。断言全部来自**真实点击与真实执行链**，没有接口 mock。 + +### 覆盖的交互 + +| 表面 | 真实动作 | 断言 | +|---|---|---| +| `/prescreen-workbench` | 打开 `?project=DEMO-B` | 标题、项目下拉真的有项目、方案下拉有方案 | +| 同上 | 点「开始 AI 预审」 | 入队提示 → 运行跑到终态 → **不刷新页面**面板自己出现本次运行 → 刷新后仍可读到、输入快照已换 | +| 同上 | 点核查结果的「查看依据」→「关闭依据」 | 抽屉打开且含"依据与版本"；关闭后抽屉消失、**焦点回到触发按钮**（键盘可达） | +| 同上 | 概率区与降级记录 | 概率数字必须紧邻"演示值/人工设定"；未完成项带错误码；"证据阶段 ≠ 审批概率"在页面上 | +| 同上 | 推进沙盘 | 没有可用动作时给诚实空态，不给"点了必然失败"的选项 | +| `/experience-center` | 点「从项目材料重建时间线」 | 徽标给出状态与事件数；无结构化记录时明确标"过程材料不完整 · 0 个事件" | +| 同上 | 空来源、空要求点「请求提炼」 | 服务端 422，界面如实显示拒绝理由（不假装成功、不静默无反应） | +| 同上 | 填提炼要求后点「请求提炼」 | 记录渲染为"提炼未完成"＋E-28；**候选行数 30→30 不变**（BR-48：不产生草稿） | +| 同上 | 点候选卡的「自然语言修改适用范围」 | **只展开被点的那一行**；未填要求时「形成草稿修订」保持禁用 | +| 同上 | 换 admin 身份重载 | 出现「隔离评测」（30 个），仍不出现「审核发布」（发布限 reviewer） | + +两处修复的全量验证：`test-evidence/20261001-093541-c880f40/`（`scripts/verify.py` **14/14 PASS**， +`backend-unit` 全量 **572 项**；证据绑定提交 `c880f40`，`summary.json` 的 `status=passed`）。 + +### 浏览器验证发现的问题（第二篇） + +两个都属于"源码守卫 + 生产构建都看不出"的那一类：构建通过、守卫全绿，只有真渲染会暴露。 + +| # | 问题 | 归属 | 处理 | +|---|---|---|---| +| 1 | `/prescreen-workbench` 点「开始 AI 预审」、运行结束后**结果面板不重载**：新运行进不了"查看哪一次运行"，面板继续显示上一次运行，而徽标写着"结果会自动刷新"——AC-46 的**界面路径**因此不成立（此前只有接口驱动能证明）。根因：`PrescreenPanel` 的 `load()` 只依赖 `project.id`。补修时又发现 worker 是**先更新 `run.status`、再另写 `prescreen_run` 视图**（`assistant_worker.process_next` 的 `put(run)` 与 `save_prescreen_view`），两者不在同一事务，只在状态变化时读一次会读到"视图还没落库"的中间态 | 第一批（面板重载时机） | 改为依赖项目里的运行集合，并在最新运行进入视图列表前短时重试（上限 5 次，不做无限轮询）；`test_prescreen_ui.cjs` 补 5 条源码断言 | +| 2 | `/experience-center` 候选区：`key={card.id}` 撞 React key，且「自然语言修改适用范围」「补充独立测试样本」按 `card.id` 开合——点一行**连开 4 行**面板（同一 card.id 的草稿行与各版本行共享 id）。浏览器控制台同时报 React 重复 key 错误 | 第二批 | 引入行级 `rowKey`（`组件id@版本@状态`），key 与两个展开标记都用它；`test_experience_center_ui.cjs` 补 4 条源码断言 | + +### 副作用（真的写演示库，如实列出） + +本脚本每次运行会**新建一次预审运行**（点「开始 AI 预审」）、**重建一次 DEMO-B 时间线**（同 id 递增 +revision）、并在未配置模型时留下**一条 `status=failed`、`candidate_id=null` 的提炼记录**。 +本轮验证（含中途重跑与核对环境）在 `backend/xingbang_data/project_assistant.sqlite3` 里新增了 +**6 条 DEMO-B 预审运行**、**3 条失败提炼记录**，并为 DEMO-A/B/C 各重建过一次时间线。 +与 F28 同类，重复运行会累积；这些是演示库里的可见数据，需要时可删。 + +### 剩余缺口（本轮未闭合） + +- **推进沙盘的勾选联动没点到**：演示方案的维度里没有假设动作的目标维度（`DC-CASH`/`DC-TITLE`）， + 服务端 `available_assumptions` 因此返回 0 个动作，界面按设计给"当前方案没有可推演的假设动作"空态。 + 基线的演示值（42%，带"演示值"标注）已实际渲染并断言，但"勾选 → 重算 → 返回基线"这条链 + 在本数据集下无法用浏览器走通。 +- **来源事件勾选没点到**：演示项目没有结构化的问询/决定记录，`case-timeline` 恢复出 0 个事件， + 勾选框不存在；本轮因此用"提炼要求"满足服务端的前置条件走通提炼链路。 +- **reviewer 视角的「审核发布」没点到**：演示身份里 reviewer 的 `/projects` 只授权到 DEMO-C， + 而 DEMO-C 没有知识候选，浏览器里点不到该按钮。已用 admin 作对照（有「隔离评测」、无「审核发布」）。 +- **「请求提炼」在"没有来源也没有要求"时按钮仍可点**：服务端按契约 422 并给出理由、界面如实显示； + 但同文件里「形成草稿修订」「保存样本到草稿」都会按必填项禁用，口径不一致。按最小改动只验证、未改。 +- **候选列表把同一卡片的多个版本行都按"已发布"列出**：`knowledge_cards.list_cards` 同时返回 + `component_draft` 与 `component_version` 行，同一 `card.id` 出现 3–4 行（v1.0.0 与 v1.0.1 都标"已发布"）， + 界面不显示 `release` 指针当前指向哪一版。"一行 = 一个存储记录"还是"一行 = 一张卡片的当前状态" + 需产品确认后再改，本轮未动。 +- **视觉回归（无基线截图比对）、多分辨率、键盘可达性与屏幕阅读器仍未做**； + 深色导航对比度仍是守卫内按 WCAG 实算，不是实测。 +- **脚本仍不在 `verify.py` 里**（F27 未决）：需本机 Chrome 与一次性 `npm i --no-save puppeteer-core`， + 手动 `node scripts/browser-e2e-modules.cjs`。现在共有**两个**可选脚本 + （`browser-e2e.cjs` 走轨迹复盘，`browser-e2e-modules.cjs` 走这两个表面）。