Merge pull request 'Annotation workspace: keyboard editing, focused layout and production slicing fixes' (#1) from feature/local-dev-toolkit into dev

Reviewed-on: longtao.wu/droboticflow#1
This commit is contained in:
longtao.wu 2026-09-18 17:59:51 +08:00
commit 883f47ff0e
201 changed files with 19611 additions and 1241 deletions

5
.gitignore vendored
View File

@ -14,3 +14,8 @@ docs.zip
__pycache__/
*.py[cod]
.operator-source-repos/
# 本地单算子调试产物
local-runs/
.venv/
local-data/

View File

@ -0,0 +1,41 @@
# 标注键盘工作流任务索引
用户已确认以下 11 票及依赖关系。每票独立发布,初始状态均为 `ready-for-agent`;该状态表示定义已就绪,只有前置票全部完成后才可领取执行。
父规格:[标注键盘工作流与连续工作模式](./spec.md)。原需求核对:[核对记录](./requirements-audit.md)。当前已进入按票顺序实施;完成状态和可复验结果见[实施报告](./implementation-report.md),各票文件记录实际验收状态。
## 任务与依赖
| 编号 | 任务 | 阶段 | 直接前置 |
| ---- | ----------------------------------------------------------------------------------- | ---- | -------- |
| 01 | [编辑保存与重新切片如实反映后端结果](./issues/01-authoritative-edit-results.md) | 1 | 无 |
| 02 | [切分后原地继续观看](./issues/02-continuous-slice-playback.md) | 1 | 无 |
| 03 | [键盘完成动作描述与字典选择](./issues/03-keyboard-description-editing.md) | 1 | 01 |
| 04 | [跨片复查、保留草稿并返回工作位置](./issues/04-review-navigation-and-drafts.md) | 1 | 02、03 |
| 05 | [切片编辑连续撤销与重做](./issues/05-slice-undo-redo.md) | 1 | 02、03 |
| 06 | [已保存动作描述也能撤销并保持服务端一致](./issues/06-persisted-description-undo.md) | 1 | 04、05 |
| 07 | [可撤销的删除与批量标无效快捷键](./issues/07-safe-delete-and-invalid-shortcuts.md) | 1 | 06 |
| 08 | [保存描述与阶段提交的两步确认](./issues/08-stage-submission-confirmation.md) | 1 | 06 |
| 09 | [独立工作页完成一条完整标注任务](./issues/09-dedicated-work-page.md) | 2 | 07、08 |
| 10 | [工作会话刷新恢复与多页面协调](./issues/10-work-session-recovery.md) | 2 | 09 |
| 11 | [送检后自动随机下一条并可可靠停止](./issues/11-continuous-random-claim.md) | 2 | 10 |
## 初始可执行任务
- 01:编辑保存与重新切片如实反映后端结果。
- 02:切分后原地继续观看。
01 和 02 没有逻辑前置;共享文件可能需要协调,但不人为增加依赖边。07 和 08 在 06 完成后分别推进。09 等待 07、08 及其所有前置验收,落实先完成第一阶段、再建设独立工作页的顺序。
## 覆盖与执行规则
- 已覆盖父规格全部 66 条用户故事与 A01–A18;每票标注自己负责的故事和验收场景,场景可以跨票组合完成。
- 第一阶段为 01–08,第二阶段为 09–11;不把前端、后端和测试拆成彼此不能演示的横向任务。
- 所需局部整理在对应功能修改前完成,并以本票可观察的行为验收;不安排独立的大范围重构。
- 主要测试边界是浏览器操作及现有公开 API 回读,接口测试补充版本冲突/幂等/处理中限制,纯函数测试仅补充精确边界。
- 各票只在本地隔离任务中进行变更验证。父规格、词汇和 ADR 为共同约束;不得因为票较窄而绕过权限、精确帧边界、留空或舍弃规则。
- 完成一票后以其全部验收标准为依据更新任务状态;未通过的票不能作为已完成前置。发布任务并不启动应用代码实施,也不推送远端。
## 实施进度
11/11票已实施并逐票审查与本地验收,详见[实施报告](./implementation-report.md)。最终全量检查与双轴审查已完成,既有失败与验证限制详见报告;本地提交未推送。

View File

@ -0,0 +1,137 @@
# 标注键盘工作流实施报告
状态:11/11 票实施完成,逐票与最终双轴审查通过;完整检查已执行,已知基线失败和验证限制详见下表。
工作分支:`feature/local-dev-toolkit`。起点:`1a5c308bdac35789998b16b4deaee89ad603482d`。所有提交保留本地,不推送;所有写入验收仅使用本地快照的独立 `keyboard-acceptance` 项目。
| 票号 | 实施提交 | 审查 | 验证 |
| ---- | ---------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 01 | `18139a00`、`61703abc` | 修正任务切换的同步隔离窗口后通过 | 25 项相关前端测试、相关 Go HTTP 测试、类型检查、前端构建及浏览器/API 回读通过 |
| 02 | `015c86de`、`4a6affea`、`d16e41b9` | 通过,无遗留问题 | 40项相关前端测试、类型检查、真实双目播放与逐帧验收通过 |
| 03 | `94ba5fa2`、`350448f2` | 修正原生按钮组合键归属后通过 | 50 项相关测试、修复 9 项键位测试、类型检查、构建和浏览器/API 保存链通过 |
| 04 | `6e95fa32`、`52263727`、`d4cd2b18` | 修正后退丢草稿后通过 | 56 项相关测试、类型检查、构建及跨片/复查/离开浏览器验收通过 |
| 05 | `e09ad03f` | 通过,无阻断问题 | 36 项聚焦测试、类型检查、构建及切片撤销/重做浏览器验收通过 |
| 06 | `e59286cb`、`55a81c55`、`9859fa8d` | 修正修订基线与批量焦点后通过 | HTTP恢复/拒绝测试、28项前端测试、类型检查、构建及真实浏览器/API故障恢复通过 |
| 07 | `37480aec`、`6db97457` | 修正空描述恢复崩溃后通过 | 32项聚焦测试、修复后44项、类型检查/构建、Mac删除/撤销与共享批量API回读通过;标准组合键工具限制见下文 |
| 08 | `b6e80de8` | 通过,无阻断问题 | 20项前端、公开HTTP异步/拒绝测试、类型检查/构建;真实生成、混合语义与全留空送检、未知恢复和产物哈希通过 |
| 09 | `acdc5427`、`ce012f8a`、`97fe6c77` | 修正入口守卫与迟到领取导航后通过 | 聚焦前端/HTTP、类型检查/构建;真实独立页全链路和30秒延迟重试通过 |
| 10 | `04d15dd8`、`d5356785` | 修正文档离开前待处理锁申请后通过 | 32项聚焦检查/类型检查/构建;真实双页、刷新、关闭恢复、账号和项目范围检查通过 |
| 11 | `fe593f8e`、`3ee1db6a` | 修正页头提示后通过 | 34项聚焦前端/公开HTTP/类型检查/构建;真实连续、响应丢失跨页恢复、停止与空池验收通过 |
## 最终交付
- [通俗操作说明书](../../docs/annotation-keyboard-guide.zh-CN.md)
- [完整验证结果](../../docs/verification/annotation-keyboard-workflow/final-validation-results.md)
- [浏览器/API证据](../../docs/verification/annotation-keyboard-workflow/acceptance-evidence.md)
- [审查及逐票记录索引](../../docs/verification/annotation-keyboard-workflow/README.md)
最终代码提交 `bad89540`。5173已恢复正常热更新并直连本地3001 API;故障代理已停止。全部提交留在个人功能分支,没有推送、合并或公司环境部署。
最终前端578项中569通过、9项旧失败;Go60个失败顶层用例全部在基线复现;Python正确环境全量643通过、27失败、3跳过,其中25个为基线失败、另2个旧缓存污染已清理并局部复验。Rust25项测试、Rust构建/静态检查、前端类型检查和Web/Go构建通过。全仓格式债务、kubectl客户端发现限制及原生键位验证边界均完整记录,未宣称全仓全绿。
## 最终交叉审查修正
最终审查发现舍弃/恢复迟到响应隔离不完整、新草稿没有截断旧重做分支、帮助文案仍称提交只用按钮,以及恢复任务筛选条件重复。一次修正并复审全部通过。前两项均先在旧页面实测复现,再在修正版按相同路径验证;文字和字典替代草稿均不再被旧重做覆盖。4条与新交互冲突的源码形状断言经审查退役,没有用新源码断言替代行为验收。
## 执行裁决与代价
1. 按implement要求沿用当前功能分支;若判断错误,需要迁移提交。
2. 每票做相关检查,最后做全量;若判断错误,集成问题会较晚暴露并需要返工。
3. 实测后退丢草稿后,最小调整路由容器以使用正式导航阻断;若判断错误,可能引入跨页面路由问题,需要回退或修正。
4. 工具不能投递Ctrl+X/Shift+Delete时,采用键位解析与共享鼠标处理器的真实API证据并披露限制;若判断错误,仍可能遗留特定OS/浏览器键位问题,需要人工复验。
## 01:保存与重新切片
- 删除开发模式下的“版本冲突仍算成功”分支,成功基线只随服务端确认更新。
- 响应丢失时回读任务;内容一致且版本确实前进才认定已保存。冲突保留当前编辑,不用新版本盲目覆盖服务器。
- 任务与账号切换同步失效旧请求,旧请求的完成与清理不修改新的工作区。
- 浏览器正常保存后版本2;丢弃成功响应后回读恢复版本3。API 模拟另一页写入版本4后,旧页面保存与重新切片均被409拒绝,服务器新内容保持不变。
- 响应延迟30秒时切换任务,迟到结果未污染当前页。重新切片的200响应被丢弃后,回读进入切片阶段,版本6、描述为空,与页面一致。
- 审查发现并修正1项同步时序问题;复审无遗留重要问题。
## 测试环境与夹具
使用5173前端、3001 API、27018本地快照。新增 `scripts/local/prepare-annotation-keyboard-fixtures.sh`,默认仅初次创建,重复运行不覆盖;仅连接本机指定Mongo容器。独立任务包含3段精确帧切片、30–60秒描述、两侧语义空白、项目字典及4条随机任务。
测试夹具发现的时长、BSON时间戳及字典关联问题已经修正,均未改动原有任务。故障注入代理只在本机对明确的测试任务路径丢弃或延迟响应;不改变生产接口。
## 02:原地切分与连续播放
C在当前硬件帧切分并暂停,选中刚完成的前半段。切片阶段空格与左右逐帧使用完整Capture范围;下一次C按播放头所在片切分。描述阶段保持当前切片边界。
浏览器曾拦截并修正“继续播放后不能再切分”“逐帧拉回旧片尾”“错误已产生但切片界面未显示”三处问题。最终验证:切点120.166667原地暂停;继续后127.566667再次切分成功;4倍速右移至127.600000、左移恢复,双目映射保持;描述播放停于120.1片尾;0秒切分被提示拒绝且覆盖不变。
测试夹具补齐右相机任务元数据,左右原视频与统一帧范围均通过公开API读取,未更改既有任务工作区。
## 03:键盘描述与字典
N/N、N/Enter 确认终点并聚焦描述编辑区;F 为主字典键,D 兼容,Enter 进入输入框,Ctrl/⌘+Enter 保存当前描述。缺终点或内容均有提示;一次 Esc 关闭字典或退出输入,草稿保留,Space 控制视频。两种阶段字典均已实测。
浏览器通过字典选词后修改文本,API 回读版本 3 与描述一致。审查发现原生按钮的 Ctrl/⌘+Enter 被错误截获,修正后复审通过;浏览器复验无写请求、版本保持 3。中文字符串输入已验证,真实系统输入法组合过程未测试;内嵌浏览器文字剪切成功但原生撤销恢复未验证成功,解析器测试仅证明不截获这些输入。后续数据历史验收还需验证文字撤销不触发数据撤销。
## 04:跨片草稿与复查
Ctrl/⌘+方向键和鼠标导航暂停到相邻片头,尾片可达且首尾不循环。文字草稿和未完成终点分别保留,不因换片保存。B 从片头播放到片尾;导航前的工作点只记一次,V 按当前切片覆盖返回该帧。
浏览器验证第一片文字草稿、第二片未完成终点、尾片导航、重复 B 与逐帧后返回原 0.2 秒;短片在 0.133333 秒自动停止。删除书签原片后,V 定位到当前合并片的 0.233333 秒。代理日志没有保存请求,API 始终保持版本 3。
离开确认统一为页面弹窗,取消后恢复工作台焦点;确认丢弃后即使复用同一任务入口也重新载入服务器内容。浏览器后退曾绕过手工监听并丢草稿,已用 React Router 的 useBlocker 修复,App 仅调整路由容器,路由和权限不变。后退取消、确认离开和前进恢复均通过复验。真实关闭/刷新所用原生 beforeunload 保留;内嵌浏览器原生确认兼容性限制单独记录。
鼠标删除移除焦点按钮后落到页面 BODY 的既有问题已明确交给 05 票,保证删除后可立即键盘撤销。
## 05:切片撤销与重做
Ctrl/⌘+Z、Ctrl/⌘+Shift+Z 使用当前任务和阶段内的同一历史:最近 100 步,每秒最多一次,长按不重复。完整边界拖动为一步;切分、删除及字典改名恢复范围、名称、状态和关联内容。跨片恢复会暂停并选中受影响片。鼠标删除后的焦点已修复,可立即按键撤销。
浏览器实测切分 3→4 片、撤销至 3 片、快速重做被节流;边界从 120.1 拖至 141.7 秒,一次撤销完整恢复;误删第二片后直接撤销,恢复第二片并暂停于 120.1 秒。新编辑使旧重做失效,导航/逐帧不占历史,字典改名可恢复。输入框撤销不动切片数据;换任务和刷新后不能恢复旧历史。测试期间 API 仍为版本 1,无本地草稿自动保存。
首次验收曾观察到构建期间整页重置、瞬时选择未同步;冻结全部构建写入后稳定复验通过,未把未复现的现象当作生产缺陷修补。阶段生成/送检边界将与 08 票综合验证。构建仍有既有弃用提示和大包警告,不影响退出状态。
## 06:动作描述撤销与服务端恢复
N起止、范围调整、拆分和完整拖动复用阶段历史;已保存描述的撤销通过原有受版本和归属保护的接口回写。局部草稿与服务器已确认内容分别记录,旧修订任务首次保存也能恢复正确基线。批量标无效或取消新增后恢复工作台焦点。
浏览器验证保存后撤销/重做、删除30–60秒描述后恢复原标识与范围、跨片恢复并保留其他片文字和待定终点。修订任务在44.6秒拆分保存后,撤销恢复服务器原30–60秒描述。批量填空后直接按Ctrl+Z,一步恢复所有空白。
请求发送失败后可再次撤销;成功响应丢失时回读确认。阻断四次回读后明确显示结果未知,再次执行原操作通过核对恢复,版本保持不变。并发页面保存后,旧版本撤销被拒绝,最新内容未被覆盖。处理中和归属变化拒绝由真实HTTP入口测试覆盖。
测试中确认开发服务器重载会清空本地历史,已使用现有DISABLE_HMR开关稳定验收,不修改产品配置。新增一条只使用修订记录的隔离夹具,原七条数据保持不变。
## 07:安全删除与批量无效
Shift+Delete及Mac Shift+Backspace只删除明确选中的切片或已保存描述;Ctrl+X复用当前片填空为无效的批量处理器,整个操作只占一步撤销。文本、字典、原生控件、输入法和长按保持各自按键归属。
Mac兼容删除实测第二切片合并到相邻片,撤销恢复三个精确范围和字典名称;选中30–60秒描述删除后API版本12只剩相邻无效区间,撤销至版本13恢复原描述。文本Ctrl+X剪切后没有数据写入。舍弃片不能删除或拆分;恢复为保留时发现后端空描述返回null,已规范为空数组并通过实际响应和刷新回归。第二片批量无效保存至版本14,一次撤销至15恢复空白,第一片数据保持。
**物理键位验证限制**:内嵌浏览器自动化对Ctrl+X、Shift+Delete直接执行原生命令,独立DOM测试页没有收到keydown;Edge控制连接不可用。因此这两组键采用公开键位解析测试+共享鼠标处理器真实浏览器/API证据,仍建议在人工浏览器中验证。Mac Shift+Backspace与原生文字剪切已实测。此限制也说明初始浏览器“未触发”不能单独作为功能RED证据,实际RED以解析器失败用例为准。
## 08:两步提交与异步恢复
当前有草稿时Ctrl/⌘+Enter只保存;缺终点或内容提示修正,其他片还有草稿则列出返回入口。全部处理后才显示生成/送检摘要,松开后独立Enter确认,Esc取消,鼠标入口相同。标注阶段帮助补齐撤销/重做。
真实生成期间重复Enter、Ctrl+Enter与Ctrl+Z未重复提交或回退。生成完成才进入描述阶段。混合任务包含第一片描述与两侧空白、第二片全无效、第三片有原因的舍弃,真实送检后版本14,quality_review/ready/pending_quality;全留空任务也正常送检版本12。产物检查两版清单各21/21文件哈希与大小一致,舍弃证据保留。
故障代理阻断提交和四次回读时显示结果未知并锁定编辑,显式核对恢复;真实成功响应丢失后回读正确确认送检,不把处理中当成功。后续原有任务提示未随切换清除的轻微问题继续交给工作页任务/最终审查。
## 09:独立工作页
选择项目点“开始工作”,在同标签页继续已有未完成任务;工作页复用原协调逻辑和完整编辑器,保留帮助、错误、阶段状态和返回保护。此票完成单条任务后暂停。
实测发现原角色守卫拒绝新路由,已修复;独立审查又发现旧领取响应可能切走新任务,已用实际30秒延迟复现后修正。复验同请求编号重试时切换并新增草稿,迟到响应只补充我的任务列表,不再跳页或打断编辑。
新页面完整经历切片撤销、离开取消、后台生成、字典与描述保存、服务器撤销版本22和重做、真实送检版本25。最终任务quality_review/ready/pending_quality,页面停留完成提示、没有自动追加领取。任务切换旧提示残留也在新入口衔接中清理。
## 10:刷新恢复与多页面协调
刷新或重新打开先显示已领取任务,点“继续工作”才激活编辑。浏览器原生锁按账号和项目保持唯一活动页;第二页给出返回指导,活动页退出或关闭后才能显式恢复。没有超时抢占,不会让后台未保存页面被另一页取代,也不改变服务端持有任务数量。
双页实测第二页不能编辑;取消离开保留草稿和锁,确认离开后另一页恢复原有三段切片,未保存切分及历史不继承。刷新再次暂停,关闭活动页后原入口恢复可用。不同授权项目只读切换不互锁;正常切换质检账号不继承标注员任务/编辑器,切回后仍需继续。整个过程API版本2、原领取人保持,未额外领取。
审查补上pagehide时待完成锁申请的失效边界。一般文档离开/浏览器返回已实测暂停;精确BFCache与原生锁回调竞态没有用私有状态注入复现,采用控制流核对与独立复审。焦点切回受浏览器策略影响,页面提供手动选择原标签的指导。
## 11:连续工作与可靠停止
显式开始后优先继续已有任务,仅真实送检完成触发下一次领取。停止不释放当前归属;未知、失败和空池暂停。领取编号在发请求前持久保存,关页重开也沿用原编号核对。
浏览器完成pool01→pool04→pool02:首次领取200响应被丢弃后暂停,关页重开没有自动请求,核对使用同一编号且未多领。pool04设置完成后停止,送检版本8后pool02仍未领取;手动恢复才开始末条。末条提交及四次回读失败时锁定并暂停,核对后不偷偷恢复连续;显式恢复后真实送检版本10,空池提示暂停。双页恢复被正确隔离。代码 `fe593f8e`、文案修正 `3ee1db6a`;逐票审查及修正复审通过。

View File

@ -0,0 +1,26 @@
# 01: 编辑保存与重新切片如实反映后端结果
**What to build:** 描述保存和重新切片遇到失败、版本冲突或结果未知时保留可恢复内容并明确提示;本地开发模式也不能伪报成功,为持久化撤销提供可靠写入边界。
**Blocked by:** None (can start immediately)
**Status:** resolved
**Phase:** 第一阶段:现有工作台操作闭环
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 36、48;验收场景 A09、A13、A18。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 先做该写入路径所需的局部整理,再统一真实成功/失败与版本回读行为;不进行整页大重构。
- [x] 描述保存和重新切片失败不会被开发模式转换成界面成功;只有后端确认才更新成功基线及当前版本。
- [x] 结果未知或冲突先核对任务的权威状态,不用旧状态覆盖更新;任务/账号切换后的旧响应不影响新工作区。
- [x] 通过真实页面与现有HTTP写入/回读验证成功、拒绝、响应不确定和迟到响应,保留原有权限及业务校验。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
完成于本地提交 `18139a00`、`61703abc`。描述保存与重新切片只接受后端确认或权威回读证明的结果,失败保留编辑;同步任务/账号隔离阻止迟到响应污染。独立审查修复 1 项时序问题后通过。类型检查、前端构建、25 项相关前端测试及相关 Go API 测试通过;真实浏览器与 API 回读覆盖成功、409、响应丢失、重新切片和跨任务迟到响应。详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,26 @@
# 02: 切分后原地继续观看
**What to build:** C 在当前精确帧切分并暂停,选中项不丢失;Space 在切片阶段跨片播放,标注阶段仍限当前片,逐帧和双目同步保持。
**Blocked by:** None (can start immediately)
**Status:** resolved
**Phase:** 第一阶段:现有工作台操作闭环
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 1、2、3、4、12、13、14;验收场景 A01、A03。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 已有多个切片时在中间片按C后,播放头停在原切点而非第一片片头,切片名称继续满足项目字典规则。
- [x] Space在切片阶段从当前帧继续并跨切片边界;标注阶段仍受所属片范围约束。
- [x] 左右逐帧在不同倍速下均保持原始帧步长及双目对应,边界非法时保持原数据并提示。
- [x] 浏览器验证实际播放位置、暂停状态、选中片和切片边界,不以源码匹配代替验收。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
完成于 `015c86de`、`4a6affea`、`d16e41b9`。切分原帧暂停并选中前半段;播放、逐帧和后续切分按当前播放位置工作。真实浏览器验证连续切分、跨片空格播放、4倍速单帧与双目对应、标注片尾停止及非法切点提示。40项相关测试与类型检查通过;独立审查无遗留问题。详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,28 @@
# 03: 键盘完成动作描述与字典选择
**What to build:** N/N 或 N/Enter 结束选区,F/D 选字典,Enter 输入,Ctrl/⌘+Enter 保存;一次 Esc 回工作台,文本和输入法不触发工作台动作。
**Blocked by:** 01:编辑保存与重新切片如实反映后端结果
**Status:** resolved
**Phase:** 第一阶段:现有工作台操作闭环
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 15、16、17、18、19、20、21、22、23、24、25、26、30、31、55;验收场景 A04、A05、A06。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] N确认起点,第二次N或Enter确认终点并聚焦描述编辑区而非直接输入框;F选字典或Enter开始手工输入。
- [x] F为主字典键,D兼容;切片名称与描述字典按阶段正确打开,选择描述模板后可继续修改并须显式保存。
- [x] 当前草稿用Ctrl/⌘+Enter保存;未完成终点或内容时仅提示,不转为阶段提交;服务端失败保留输入。
- [x] 一次Esc关闭字典/退出输入后保留草稿并让Space控制视频,不重开字典。
- [x] 文本、中文输入法、原生按钮和弹层各自处理事件,不发生双重派发;帮助随上下文更新。
- [x] 真实浏览器覆盖完整键盘输入保存链及服务器回读,键盘解析单测仅补充组合/重复边界。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
完成于 `94ba5fa2`、`350448f2`。N/N 与 N/Enter 结束选区后聚焦编辑区,F/D 字典、Enter 输入、Ctrl/⌘+Enter 显式保存和单次 Esc 返回均已通过真实浏览器验证,保存后 API 回读版本从 2 到 3。审查修正原生按钮组合键归属,复审通过。50 项相关测试、类型检查和构建通过;修复另有 9 项键位测试。系统输入法组合过程及内嵌浏览器原生文字撤销恢复未做成功实测,不以文字输入或解析器用例替代该证据。详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,28 @@
# 04: 跨片复查、保留草稿并返回工作位置
**What to build:** Ctrl/⌘+左右切换并保留各片草稿,B 从片头复查到片尾,V 回原工作位置;尾片可达、首尾不循环,离开未保存内容有提醒。
**Blocked by:** 02:切分后原地继续观看;03:键盘完成动作描述与字典选择
**Status:** resolved
**Phase:** 第一阶段:现有工作台操作闭环
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 5、6、7、8、9、10、11、27、28、29、64;验收场景 A02、A07、A18。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 方向组合键和对应鼠标导航暂停到目标片头;可进入尾部待处理片,首尾不循环。
- [x] 每片的未保存动作(包括终点选择阶段)在当前页面会话中保留,切换不写后端、不清空,返回恢复。
- [x] B从选中片头播放到片尾停;首次进入复查记录工作位置,后续B、逐帧及换片不覆盖该位置。
- [x] V回原工作点并暂停;片段编辑改变所属片时按合法帧定位当前片,不复活旧ID。
- [x] 暴露全部待保存/待取消草稿状态供阶段提交校验;刷新/离开未保存内容有保护,已保存恢复不等于未保存草稿永久化。
- [x] 浏览器实测多片多草稿、B/V复查、切分后的导航以及保存请求未发生的断言。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
完成于 `6e95fa32`、`52263727`、`d4cd2b18`。跨片文字及待选终点草稿保留,B 片头复查至片尾,V 返回原工作帧并按当前分片定位;所有草稿汇总给父页面。真实浏览器验证多片草稿、尾片不循环、片尾停止、删除原片后的返回、离开取消与确认;全程无保存请求,API 版本 3 不变。审查发现并修复浏览器后退丢草稿,改用路由器的导航阻止机制,原路由和权限保持;复审通过。56 项相关测试、类型检查和构建通过。详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,28 @@
# 05: 切片编辑连续撤销与重做
**What to build:** 切分、拖动和现有鼠标删除可跨片撤销/重做;一次拖动算一步,最近100步、每秒一次,阶段和任务变化截断历史。
**Blocked by:** 02:切分后原地继续观看;03:键盘完成动作描述与字典选择
**Status:** resolved
**Phase:** 第一阶段:现有工作台操作闭环
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 37、39、40、41、42、43、44、45、46、47、52;验收场景 A08、A11、A18。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 提供Ctrl/⌘+Z与Ctrl/⌘+Shift+Z,切片分割、边界调整和现有鼠标删除经同一历史通道恢复范围、名称和状态。
- [x] 一次已完成拖动只计一步;普通播放、步进、选片不入历史;跨片撤销定位受影响片并暂停。
- [x] 共享撤销/重做节流每秒最多受理一次,长按忽略,保留最近100步;新编辑清空重做分支。
- [x] 文本输入内撤销保留原生含义,不触发数据历史。
- [x] 遵守ADR-0001,真实开始生成、重新切片、送检或切换任务截断历史,刷新不恢复栈。
- [x] 用真实页面证明误切/误删可恢复且切片覆盖合法,公开行为测试补充容量和时钟边界。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
完成于 `e09ad03f`。统一页面会话内的 100 步切片历史,Ctrl/⌘+Z 与 Shift+Z 共用一秒节流;分割、拖动、删除和字典改名恢复完整工作区,鼠标删除后可直接键盘撤销并定位受影响片。真实浏览器验证一次拖动一次撤销、跨片恢复、新编辑替换重做、导航与逐帧不入历史、输入框不触发数据撤销、换任务和刷新清空历史。36 项聚焦测试、类型检查及构建通过,独立审查通过。实际生成/送检的历史边界随 08 票综合验收继续验证;持久化描述由 06 扩展。详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,28 @@
# 06: 已保存动作描述也能撤销并保持服务端一致
**What to build:** 扩展同一历史机制到动作起止选择、描述保存/调整/删除及已有批量无效操作;已保存内容的撤销同步后端,跨片草稿不会被覆盖。
**Blocked by:** 04:跨片复查、保留草稿并返回工作位置;05:切片编辑连续撤销与重做
**Status:** resolved
**Phase:** 第一阶段:现有工作台操作闭环
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 37、38、39、40、41、47、48、51、52;验收场景 A08、A09、A11、A18。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] N起点和终点选择可撤销;描述创建/保存、区间调整/分割、现有鼠标删除和批量无效进入一致的阶段历史。
- [x] 持久化动作撤销/重做通过现有受版本及归属保护的写入完成,随后刷新/回读一致,不能仅恢复画面。
- [x] 写入串行化并使用最新确认版本,失败不推进成功历史;冲突和结果未知先回读,不覆盖其他新状态。
- [x] 跨片历史恢复正确的片段、描述、相关状态和草稿;一次批量无效作为一步恢复全部原空白。
- [x] 已保存描述删除留下空白,不拉伸其他描述;切片/动作两种删除不混淆,历史不跨任务或业务阶段。
- [x] 浏览器结合HTTP回读验证恢复,接口层验证版本冲突、归属变更及处理中拒绝,不以内部栈结构为断言。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
已完成:`e59286cb`、`55a81c55`、`9859fa8d`。统一动作历史和服务端补偿写入,修正旧修订任务基线及批量操作焦点。两轮独立复审通过。真实浏览器/API覆盖N起止、跨片草稿、保存/删除/批量撤销、响应丢失、未知重试与版本冲突。相关HTTP、28项前端测试、类型检查和构建通过;详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,29 @@
# 07: 可撤销的删除与批量标无效快捷键
**What to build:** Shift+Delete(Mac兼容Shift+Backspace)按选中对象删除;Ctrl+X 填本片空白为无效,均可立即撤销,文字剪切及舍弃规则不受影响。
**Blocked by:** 06:已保存动作描述也能撤销并保持服务端一致
**Status:** resolved
**Phase:** 第一阶段:现有工作台操作闭环
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 49、50、51、52、53、54、55;验收场景 A05、A08、A09、A10、A14。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 切片阶段删除明确选中切片并合并范围;标注阶段仅删明确选中描述,无目标不执行,Mac兼容指定键位。
- [x] Ctrl+X只在允许的工作台上下文执行,填当前片全部空白为无效且不改已有描述,整批撤销一次恢复。
- [x] 输入框保留剪切及删除,舍弃片的拆分/删除等限制继续生效;不把无效或删除当舍弃。
- [x] 鼠标和新快捷键调用相同编辑及历史行为,服务器回读与撤销画面一致。
- [x] 更新上下文帮助;浏览器验证误触、无目标、文本焦点、多空白及既有舍弃/字典权限限制。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
完成提交`37480aec`、`6db97457`,独立审查与修复复审通过。Mac删除兼容键、切片合并/撤销、描述删除/服务器恢复、原生文字剪切、舍弃保护及共享批量保存路径已实测。另修复恢复空描述片时后端null数组导致的崩溃,实际API响应和刷新回归通过。32项聚焦测试,修复后44项,类型检查和构建通过。
验证限制:内嵌浏览器自动化在送达页面前拦截Ctrl+X和Shift+Delete,独立DOM按键探针确认未收到keydown,Edge连接不可用。这两组键由键位解析测试及其复用的鼠标处理器浏览器/API验收覆盖,未宣称物理组合键实测通过;Mac Shift+Backspace实测通过。详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,30 @@
# 08: 保存描述与阶段提交的两步确认
**What to build:** Ctrl/⌘+Enter 优先保存当前描述;无草稿才确认生成或送检,独立 Enter 二次确认,处理中锁定、成功才推进,失败可恢复。
**Blocked by:** 06:已保存动作描述也能撤销并保持服务端一致
**Status:** resolved
**Phase:** 第一阶段:现有工作台操作闭环
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 29、30、31、32、33、34、35、36、47、54、66;验收场景 A12、A13、A14、A18。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 当前有草稿只保存;当前无草稿而其他片有草稿则引导处理,不能无声丢弃或自动提交。
- [x] 全部草稿处理后按阶段打开生成/送检确认,展示相关切片/描述/留空信息,Esc取消。
- [x] 松开后新的一次Enter才能确认;按住、重复与弹层事件不穿透造成双提交。
- [x] processing仍为处理中并锁定冲突编辑;真实成功才流转,失败/结果未知保留恢复入口。
- [x] 与历史机制衔接只遵守已确认的任务/阶段边界,不用Ctrl+Z倒退已接受的业务流程。
- [x] 真实前后端验证部分/全空、无效和舍弃、字典与权限规则;浏览器及HTTP测试覆盖异步和拒绝分支。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
提交 `b6e80de8` 已独立审查通过。20项聚焦前端测试、公开HTTP异步/拒绝测试、类型检查和构建通过。真实浏览器验证当前/跨片/未完成草稿优先级、两步确认和Esc取消、处理中锁定,以及提交与四次回读同时失败后的显式恢复。成功响应丢失仍通过权威回读确认质检流转。
混合描述/留空/无效/舍弃任务实际送检版本14,全留空任务送检版本12;均为 quality_review / ready / pending_quality。生成与送检产物21/21哈希一致。详见[实施报告](../implementation-report.md)。真实系统输入法与按住事件的自动化限制保留在总报告,公开按键解析测试覆盖不穿透规则。

View File

@ -0,0 +1,30 @@
# 09: 独立工作页完成一条完整标注任务
**What to build:** 第一阶段验收通过后,选择项目进入同标签页工作页,复用完整工作台完成单条任务的领取/恢复、切片、标注和送检,不复制一套编辑器。
**Blocked by:** 07:可撤销的删除与批量标无效快捷键;08:保存描述与阶段提交的两步确认
**Status:** resolved
**Phase:** 第二阶段:独立工作页与连续任务
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 56、57、58、66;验收场景 A01、A02、A03、A04、A05、A06、A07、A08、A09、A10、A11、A12、A13、A14、A18。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 依赖07/08及其全部前置完成即构成第一阶段完成门槛,先验证完整键盘/恢复/提交链再启用独立工作页。
- [x] 选择授权项目显式进入工作;已有当前未完成任务则继续,未有任务时复用现有盲选随机领取。
- [x] 在同标签页完整经历切片、异步生成、描述、送检,角色与供应商权限不变;不另开弹窗、不复制编辑实现。
- [x] 保留阶段状态、错误、帮助、未保存离开保护和返回入口。
- [x] 本票交付单条任务闭环;自动下一条由11交付,不能将单条成功宣称连续模式已完成。
- [x] 用隔离本地任务通过浏览器完成整条流程并回读真实阶段结果,第一阶段验收在新入口继续通过。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
提交 `acdc5427`、`ce012f8a`、`97fe6c77` 已审查通过。先修正新路由被原权限守卫重定向,再修正旧领取响应切走新任务的时序问题;真实30秒延迟重试验证新任务及草稿保留,服务器已分配任务仍出现在我的任务中。
同标签页复用原工作台,优先继续已有任务。在新入口完成重新切片、C/撤销、离开保护、真实生成、N/N/F/Enter保存、服务端撤销重做及送检;最终API版本25为quality_review/ready/pending_quality,完成后暂停且无自动领取。32项聚焦测试、修复后35项相关检查、HTTP权限/领取测试、类型检查和构建通过。详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,29 @@
# 10: 工作会话刷新恢复与多页面协调
**What to build:** 刷新后恢复已领取任务并显式继续,同浏览器同账号项目只有一个活动工作页,第二页引导返回,未保存内容与既有归属受到保护。
**Blocked by:** 09:独立工作页完成一条完整标注任务
**Status:** resolved
**Phase:** 第二阶段:独立工作页与连续任务
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 58、63、64、65;验收场景 A17、A18。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 刷新/重新打开先显示已领取任务,须显式继续,不自动再领;只恢复后端已保存工作,历史不跨刷新。
- [x] 同浏览器同账号项目识别唯一活动工作页,重复开启引导回活动页面;不会改变其他设备及服务端任务持有规则。
- [x] 活动页关闭或退出后提供恢复入口;旧页/旧账号迟到状态不能覆盖当前会话。
- [x] 未保存草稿受离开提醒保护,恢复不被当作用户同意重新领取。
- [x] 浏览器用同一上下文两个页面验证互斥和恢复,并验证账号/项目范围隔离;此票为自动连续领取提供已验收的会话所有权。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
提交 `04d15dd8`、`d5356785` 已审查通过。浏览器原生独占锁按账号和项目协调,刷新/重开先显示已领取任务,必须点“继续工作”;不自动领取,历史和未保存草稿不跨恢复。
真实双页验证互斥、取消离开保留活动权、接受退出和关闭后显式恢复、仅载入服务器内容;项目只读切换及正常标注员/质检员登录切换验证范围隔离。API仍是版本2、claimed及原领取人,日志无新领取。文档离开后Back也恢复为暂停。审查发现并修正pagehide前未完成锁申请的身份失效问题;其精确原生调度竞态由控制流审查确认,未注入私有状态假装浏览器覆盖。32项聚焦检查、类型检查/构建通过,详见[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,28 @@
# 11: 送检后自动随机下一条并可可靠停止
**What to build:** 显式开始连续工作,后端确认送检成功后恰好随机领取下一条;完成当前任务后可停,空池、失败、未知结果和权限变化均暂停且可恢复。
**Blocked by:** 10:工作会话刷新恢复与多页面协调
**Status:** resolved
**Phase:** 第二阶段:独立工作页与连续任务
**Spec:** 标注键盘工作流与连续工作模式规格。用户故事 57、59、60、61、62、63、65、66;验收场景 A15、A16、A17。验收编号关联本票负责的行为,综合场景需与相关票完成结果共同验证。
- [x] 从已验收的独立工作页启用连续模式,只有持有本浏览器会话执行权的页可自动领取。
- [x] 收到processing不领取下一条,真实质检流转成功才发起一次逻辑领取;已领取未完成任务不被跳过。
- [x] 停止选项让当前任务正常完成且不再接下一条,不释放领取关系。
- [x] 空池、处理失败、网络结果未知和权限改变显示原因并暂停,保留恢复入口。
- [x] 不确定领取结果复用原请求编号核对/重试,重复响应不导致第二次分配;跨项目/供应商及不允许角色仍受限制。
- [x] 完整浏览器链覆盖连续两条、停止、失败重试、刷新/双页与HTTP幂等验证,无测试对公司环境或BOS默认写入。
- [x] 使用本地前端 5173、API 3001 和快照 Mongo 27018 的隔离任务验证;公司环境与 BOS 默认只读,不能直接运行默认指向远端的验收工具。
- [x] 完成适用于本票的类型检查、编译与行为测试,记录可复验结果;已有全量失败与本票新增回归分开报告,不用源码字符串或私有状态断言充当交互验收。
## Constraints
遵守父规格及 ADR-0001:当前任务、当前编辑阶段内纠错,不回滚生成或审核流转。保留硬件帧、字典命名、语义留空/无效/舍弃区别、角色与领取归属、审核和交付契约。只做本票交付所需的局部整理,复用现有公开交互与 API;不引入测试专用业务接口,不改变父规格或擅自扩展键位。
## Answer
实现提交 `fe593f8e`、`3ee1db6a`。独立审查通过,页头矛盾文案已修正并复审。真实浏览器覆盖已领取优先、处理期不领、送检后接续、成功响应丢失及关页后原编号恢复、停止后不多领、双页隔离、提交未知暂停及空池暂停;公开 API 回读一致。34项前端聚焦测试、HTTP幂等/处理中限制、类型检查与构建通过。最终全量检查单列于[实施报告](../implementation-report.md)。

View File

@ -0,0 +1,59 @@
# 标注键盘工作流:需求与现状核对
日期:2026-09-17。核对代码:`df851702`(包含同事 `5498892c` 及之前改动)。
状态:两轮共九项行为决策已由用户确认。完整规则与验收场景见 [设计规格](./spec.md);本文保留核对时的事实,不代表新行为已经实现。
## 证据范围
- 已核对仓库中的需求契约、相关测试、工作台代码与近期提交。
- 客户原问题表由 [9 月 4 日验收记录](../../docs/fanyu-september4-20260906-progress.md) 指向 [飞书](https://pcno45pc3jv8.feishu.cn/wiki/TImwwnFqyiIuC3kgIDHcIlHDnTc)。本次访问停在登录页,未读取客户原文,也不能断言该表就是用户指的完整需求文件。
- 本地验收记录是同事对需求的转述,不能视为客户原文。
- 下述焦点和播放问题根据代码路径推导,尚未在浏览器交互中复现。
## 现有契约及文档冲突
1. 切片覆盖统一硬件帧范围、无空洞无重叠;已有描述须属于单片、对齐帧边界且不重叠。
2. 当前描述型工作台允许部分或全部语义留空;留空、无效、舍弃有不同含义。批量标无效只能由操作者明确触发,不是提交必经步骤。
3. 新确认的切片名称来自项目启用的切片字典;描述字典是可编辑模板。
4. 描述只有显式保存成功才计入;失败保留编辑内容。切片确认和最终提交会触发异步处理,收到 `processing` 不代表已生成切片或已送检。
5. 标注员、质检员、验收员不能主动释放任务;随机领取限定项目、账号和供应商权限,领取前不能挑选候选视频。
6. 舍弃/恢复、重新切片、送检均有服务端副作用与阶段限制;撤销不能仅恢复浏览器状态。
来源:[五项规则](../../docs/annotation-five-rules.md)、[舍弃契约](../../docs/annotation-slice-discard.md)、[随机领取](../../docs/annotation-project-random-claim.md)、[持久化处理](../../docs/annotation-processing.md)。
旧 [边界文档](../../docs/annotation-boundaries.md) 中“描述必须全覆盖”和 [流程文档](../../docs/annotation-operations.md) 中“每片必须描述或确认无动作”的表述,已被较新的语义留空规则替代。[切片字典旧文档](../../docs/slice-name-dictionary.md) 的自由命名规则也与最新五项规则冲突。以新契约和对应测试为本轮依据,不在本轮擅自改写旧文档。
## 建议与实现逐项对照
| 用户建议 | 当前实现 | 需要明确的行为 |
| --- | --- | --- |
| C 后留在切点,Space 继续向后播放 | 分割后两个子片都换 ID;旧选中 ID 失效时回退第一片。播放器又限于选中片,片尾 Space 从片头重播 | 切片阶段连续播放范围、分割后暂停还是保持播放 |
| B 回选中片头审阅 | B 未绑定 | 回片头暂停还是直接播放;片尾停下还是继续 |
| V 回最后切片继续工作 | V 未绑定 | 最后一片起点、最近切点、上次工作播放头三者不同 |
| Ctrl+左右切换切片和未处理尾部 | 未绑定;普通左右键逐帧 | 当前“未切片尾部”实际属于末片;切换时保留还是处理未保存草稿 |
| Ctrl+Z 连续撤销,每秒一次 | 有切片历史栈和 undoSlice,但撤销函数未接入当前工作台;没有描述撤销 | 撤销范围、保存后的反向写入、阶段边界、文本框原生撤销、1 秒节流 |
| 删除组合键且可撤销 | 没有快捷键;删切片并入相邻片,删描述保留空白且会调用保存 | 根据阶段/选中对象确定删除目标;舍弃片限制继续生效 |
| Ctrl+Enter 确认切片,再 Enter 确认弹窗 | 当前 Ctrl/⌘+Enter 仅保存描述,不提交阶段 | 草稿保存与阶段提交的优先级、弹窗初始焦点、抑制按住连发 |
| N 开始、N 结束动作区间并进入描述框 | 当前 N 开始,Enter 确认终点并聚焦文本框;编辑时再次 N 被忽略 | 是否同时保留 Enter;取消/撤销结束点的含义 |
| F 打开字典,方向/Enter/Esc 操作 | 当前字典键是 D,已有方向/Enter/Esc;B 并非当前字典键 | F 在文本框中是输入还是命令;两种字典的阶段映射 |
| Ctrl+Enter 保存描述且可撤销 | 保存已存在,撤销缺失 | 保存中、保存失败和版本冲突后的撤销行为 |
| Ctrl+X 将本片未标注区间标无效 | 对应按钮和保存逻辑已存在,无快捷键/撤销 | 文本框保留剪切;批量填补多个空白作为一次操作 |
| 一次 Esc 后即可继续播放 | 字典关闭后焦点返回按钮,Space 留给按钮激活;再次 Esc 才回工作台 | 关闭与选中词条分别应把焦点交还何处,保持未保存内容 |
| 工作模式页面,提交后随机下一条 | 项目随机领取已实现;送检成功后返回任务池,未自动继续领取 | 独立页/原页、连续模式启停、服务端确认后领取、空池/失败处理 |
代码索引:[快捷键](../../src/lib/annotation-shortcuts.js)、[工作台](../../src/components/CaptureAnnotationWorkbench.tsx)、[任务页](../../src/pages/AnnotationOperations.tsx)、[切片名称字典](../../src/components/SliceNameDictionaryPicker.tsx)。
关键位置(以上述提交为准):任务页 1654/1785/1822/1888 是切片历史、分割、删除、未接入的撤销;工作台 304/501/593 是选中项回退和播放限制;739/811 是动作起点/终点;905/926/1051 是保存、批量无效、删除;1085/1133/1165 是焦点和快捷键派发。任务页 2098–2170 是异步提交与回任务池,2722 是随机领取。
## 同事近期方向
- `af7c405f`:字典、领取归属等业务规则;`a2ddd07c`:允许语义留空。
- `f339c3f0`、`6deb36c2`:操作延迟、时间轴缓存与源版本校验。
- `cc0202d4`:持久帧索引及可恢复处理;`cd41174d`:无损时间轴传输与固定对象版本下载。
- `b57980fd`、`5498892c`:限定范围清理旧产物、长视频产物校验。
键盘与焦点优化可补足当前方向;工作页无需重写随机领取、帧边界、审核或处理服务。
## 决策记录
两轮九项均按推荐方案确认,统一记录在 [设计规格](./spec.md),避免与现状核对混淆。阶段内撤销的边界另见 [ADR-0001](../../docs/adr/0001-annotation-undo-stage-boundary.md)。

View File

@ -0,0 +1,218 @@
# 标注键盘工作流与连续工作模式规格
Status: ready-for-agent
## Problem Statement
标注员在长 Capture 中需要反复定位切点、回看片段、填写动作描述,再继续处理后面的内容。现有工作台在切分后可能丢失选中切片,播放又受限于选中片,导致用户无法自然继续向后观看。键盘事件受焦点影响,关闭字典后 Space 可能再次激活按钮;部分操作已有能力,却没有连贯、可发现的快捷入口。
误切、误删以及错误保存描述缺少可达的连续撤销能力。切换切片时未保存的编辑也缺少明确、一致的保留规则。操作者不得不频繁使用鼠标、记住工作位置,并承担难以恢复的误操作成本。
项目随机领取已经实现,但送检后仍返回任务池,尚未形成选项目后连续完成切片、标注和下一任务的专注工作流程。
## Solution
分两阶段交付:先完善现有工作台的播放、片段复查、焦点、快捷键、跨片草稿、撤销/重做和提交确认;再复用该工作台,在同一浏览器标签页提供独立工作页面及连续随机领取。
操作者按 C 在当前精确帧切分并暂停,Space 继续观看;B 从选中片头复查,V 回到此前的工作位置。动作描述采用 N 开始、N 或 Enter 结束,随后 F 选字典或 Enter 输入文本。Ctrl/⌘+Enter 根据编辑状态保存描述或打开阶段提交确认。普通文本输入、输入法和弹层各自拥有清晰的键盘范围。
当前任务、当前编辑阶段内提供最近 100 步撤销和重做,覆盖鼠标及键盘编辑;已经保存的描述撤销须同步后端。每秒最多受理一次撤销/重做,并忽略长按重复。未保存的动作草稿在当前页面会话内按切片保留,跨片导航不会偷偷保存或清空。
独立工作页需显式开始连续工作,等待真实送检成功后才领取下一条。提供“完成当前任务后停止”;空池、失败和结果未知时暂停,刷新不会默默追加任务。整个方案保留既有硬件帧边界、字典、权限、语义留空、舍弃和审核交付规则。
## User Stories
1. As an annotator, I want to split a slice at the exact current frame without jumping backwards, so that I can evaluate the cut in place.
2. As an annotator, I want splitting to pause at the cut, so that I can inspect nearby frames before continuing.
3. As an annotator, I want Space to continue across slice boundaries during slicing, so that I can watch the remaining Capture without repeatedly changing selection.
4. As an annotator, I want selection to remain meaningful after a split, so that the workbench does not unexpectedly return to the first slice.
5. As an annotator, I want B to replay the selected slice from its beginning and stop at its end, so that I can review the whole slice deliberately.
6. As an annotator, I want V to return to my previous working position and pause, so that reviewing earlier slices does not lose my place.
7. As an annotator, I want repeated review navigation to preserve the original return position, so that intermediate review frames do not overwrite it.
8. As an annotator, I want the return position to remain valid after slice edits, so that returning does not resurrect a deleted slice.
9. As an annotator, I want Ctrl/⌘ plus Left or Right to select adjacent slices, so that I can navigate without a mouse.
10. As an annotator, I want navigation to include the remaining tail slice and stop at either end, so that I can reach unfinished material without unexpected wraparound.
11. As an annotator, I want slice navigation to pause at the destination beginning, so that I know where review will start.
12. As an annotator, I want ordinary Left and Right to step by original frames at every playback speed, so that precise boundary adjustment remains reliable.
13. As an annotator, I want both cameras to retain their synchronized frame mapping, so that keyboard navigation does not alter alignment.
14. As an annotator, I want playback during semantic annotation to stay within the current slice, so that action descriptions remain grounded in that slice.
15. As an annotator, I want N to start an action description interval, so that I can mark its beginning while watching.
16. As an annotator, I want a second N to confirm the interval end, so that I can complete the selection with the same key.
17. As an annotator familiar with the existing controls, I want Enter to remain an alternative way to confirm the end, so that my existing workflow still works.
18. As an annotator, I want interval confirmation to focus the description editing area without immediately entering a text field, so that F and Enter have predictable next actions.
19. As an annotator, I want F to open the appropriate dictionary, so that I can choose a slice name or an action description without a mouse.
20. As an annotator familiar with D, I want it retained as a dictionary shortcut, so that I do not have to relearn an existing binding immediately.
21. As an annotator, I want arrows, Enter and Esc to operate the dictionary, so that searching and choosing a term remain keyboard accessible.
22. As an annotator, I want a selected description template to remain editable, so that I can describe the actual observed action.
23. As an annotator, I want Enter in the description editing area to begin manual text entry, so that free-form editing is explicit.
24. As an annotator, I want text fields and Chinese input composition to keep their normal keys, so that typing cannot split, play or submit a task.
25. As an annotator, I want one Esc to return to the workbench while retaining my draft, so that I can resume watching without repeatedly escaping focus.
26. As an annotator, I want Space after closing the dictionary to control playback, so that it does not reopen the dictionary.
27. As an annotator, I want unfinished action drafts retained separately for each slice during navigation, so that I can inspect another slice without losing my work.
28. As an annotator, I want navigation not to save drafts automatically, so that only explicitly confirmed descriptions count as saved work.
29. As an annotator, I want all outstanding drafts identified before stage submission, so that unfinished edits cannot be silently omitted.
30. As an annotator, I want Ctrl/⌘+Enter to save the current description when a draft exists, so that saving text does not unexpectedly submit the whole task.
31. As an annotator, I want incomplete descriptions to produce a useful prompt, so that an invalid save never falls through to stage submission.
32. As an annotator, I want Ctrl/⌘+Enter without outstanding drafts to open the current stage confirmation, so that I can generate slices or submit annotation by keyboard.
33. As an annotator, I want a separate Enter press to confirm and Esc to cancel, so that a held key cannot execute both confirmation steps.
34. As an annotator, I want confirmation to show the operation and relevant slice, description and blank information, so that I understand what I am submitting.
35. As an annotator, I want pending generation or submission to remain visibly pending, so that I do not mistake request acceptance for completion.
36. As an annotator, I want failed saves and submissions to preserve recoverable content, so that retries do not require rebuilding my work.
37. As an annotator, I want Ctrl/⌘+Z to undo recent slice and description edits across slices, so that ordinary mistakes are recoverable.
38. As an annotator, I want saved-description undo to update the server as well as the screen, so that reloading does not bring the mistake back.
39. As an annotator, I want undo and redo to return me to the affected slice and pause, so that I can inspect the restored result.
40. As an annotator, I want Ctrl/⌘+Shift+Z to redo an undone edit, so that an accidental undo is recoverable.
41. As an annotator, I want a complete drag or batch invalid marking to count as one edit, so that undo follows meaningful actions rather than intermediate events.
42. As an annotator, I want at most one undo or redo each second and no held-key repetition, so that an accidental press cannot erase many steps.
43. As an annotator, I want playback, frame inspection and selection excluded from edit history, so that undo reaches the last data change.
44. As an annotator, I want the last 100 edits available within the current task stage and page session, so that I can recover multiple recent mistakes.
45. As an annotator, I want a new edit after undo to replace the redo branch, so that redo cannot reapply an incompatible future.
46. As an annotator, I want text-field undo to continue editing text, so that it does not unexpectedly change slice data.
47. As an annotator, I want undo history to stop at task and stage boundaries, so that keyboard recovery cannot reverse generation or quality handoff.
48. As an annotator, I want failed or conflicting persisted undo to be reported accurately, so that I do not trust a restoration that the server rejected.
49. As an annotator, I want Shift+Delete, and Shift+Backspace on Mac, to delete only an explicitly selected object, so that deletion has a predictable target.
50. As an annotator, I want deleting a slice to preserve coverage by merging its range into a neighbor, so that deletion does not remove source media coverage.
51. As an annotator, I want deleting an action description to leave semantic blank space, so that unrelated descriptions and video remain unchanged.
52. As an annotator, I want mouse edits and keyboard edits to share the same recovery behavior, so that undo does not depend on how I invoked an action.
53. As an annotator, I want Ctrl+X outside text input to mark all current-slice blanks invalid in one operation, so that repeated invalid intervals can be handled efficiently.
54. As an annotator, I want semantic blanks, explicit invalid intervals and discarded slices to remain distinct, so that shortcuts do not silently change delivery intent.
55. As an annotator, I want shortcut help to reflect the current editing context, so that available actions are discoverable.
56. As an annotator, I want a dedicated work page in the same browser tab, so that I can focus on annotation with fewer surrounding controls.
57. As an annotator, I want to select an authorized project and explicitly start continuous work, so that new tasks are acquired deliberately.
58. As an annotator, I want to continue my current unfinished task before acquiring another one, so that entering work mode does not abandon existing work.
59. As an annotator, I want the next random task acquired only after confirmed quality handoff, so that an unfinished submission is not hidden by navigation.
60. As an annotator, I want a stop-after-current-task option, so that I can finish cleanly without receiving another task.
61. As an annotator, I want empty pools, failures, permission changes and unknown results to pause continuous work, so that I can resolve the problem without losing task ownership.
62. As an annotator, I want a retry after an unknown claim result to reuse the same logical request, so that a network problem does not allocate a second task.
63. As an annotator, I want refresh to restore saved work and require an explicit continuation, so that reopening a page does not silently claim more tasks.
64. As an annotator, I want a warning before leaving unsaved work, so that page-session drafts are not lost unknowingly.
65. As an annotator, I want only one page per account and project in the same browser to auto-claim continuously, so that duplicate tabs do not compete for new work.
66. As a quality or acceptance reviewer, I want the existing ownership, review and evidence rules preserved, so that faster annotation does not bypass review or change what is delivered.
## Implementation Decisions
### Scope and module responsibilities
- Deliver the existing workbench improvements first, then reuse that workbench for the dedicated work page and continuous-task coordination. Do not create a second editing implementation.
- The annotation task coordinator remains responsible for ownership, project context, server writes and authoritative stage transitions. The workbench owns user-facing playback, selection, editing focus and draft interactions; shortcut resolution maps an event in its context to one action.
- Add the required session-scoped history and per-slice draft coordination at the workbench/task boundary. Its public behavior must support cross-slice undo and server-confirmed restoration; this spec does not mandate internal class names or a new public API.
- Reuse current dictionary selection, version-checked saving, slice confirmation, annotation submission, status polling and idempotent random claiming. No new database schema or server-side undo history is decided by this spec.
- A model layer or test-only backend endpoint is not a prerequisite. If implementation exposes a missing production API capability, resolve it against the existing version and ownership contract rather than bypassing that contract.
### Playback, navigation and focus
- In the slicing phase, C splits at the current precise frame and pauses in place; Space plays or pauses from the current position across slice boundaries. Selection must remain valid after a split rather than falling back to the first slice.
- B starts review from the selected slice beginning and stops at its end. In semantic annotation, ordinary playback remains within the current slice. Existing frame stepping and synchronized dual-camera mapping remain exact at all playback speeds.
- Ctrl/⌘ plus Left or Right navigates to an adjacent slice beginning and pauses, includes the remaining tail slice, and does not wrap at either end.
- Record a working-position bookmark on entry to review. Repeated B, frame inspection and review navigation do not overwrite it. V returns and pauses; if slice edits changed ownership of that time, resolve it to the current containing slice on a valid frame boundary, not a deleted slice.
- N begins an action interval; a second N or Enter confirms the end. End confirmation enters the description editing area with the text field initially unfocused. F selects a dictionary template; Enter begins manual text entry; choosing a template returns to the editing area and does not save automatically.
- F is the primary dictionary key and D remains compatible. The slicing phase uses the slice-name dictionary; description editing uses the description dictionary. New slice names must still come from the enabled project dictionary, and description templates remain editable.
- Key handling respects input composition, active dialogs/menus, text inputs, the description editing area and the workbench. A key event performs at most one action. Text input retains normal characters, Space, cut and text undo. Esc exits to the workbench while retaining drafts; closing the dictionary must not leave Space activating its old trigger.
- Existing native button activation remains available, but must not dispatch a duplicate workbench action. Shortcut help reflects context, phase and availability.
### Drafts, delete and invalid marking
- Keep an unfinished action draft per slice in the current page session. Navigating between slices neither discards nor auto-saves it; returning restores the edit. All drafts must be explicitly saved or cancelled before stage submission.
- Shift+Delete deletes only an explicitly selected object, with Shift+Backspace additionally supported on Mac. In slicing it removes the slice partition and merges its range into a neighbor; in annotation it deletes the selected action description and leaves a blank. Without a clear target the command does nothing.
- Ctrl+X outside text input explicitly marks all unannotated gaps in the current slice invalid without changing existing descriptions. The entire batch is one undoable edit; text input keeps its native cut action.
- Ordinary deletion is not slice discard. Existing restrictions on editing discarded slices continue to apply; shortcuts do not implicitly restore them or remove their audit evidence.
### History and persistence
- Follow ADR-0001: undo is limited to the current task and editing stage. Starting slice generation, re-slicing, submitting to review or switching tasks forms a history boundary; undo cannot roll back the business workflow.
- Store the most recent 100 meaningful edits for the current page session and stage. A split, completed boundary drag, saved description, deletion or invalid-marking batch is one step. Beginning and ending action interval selection are also undoable.
- Playback, stepping and selection do not create data-history entries. Mouse and keyboard mutations share history. Cross-slice undo/redo reveals the affected slice and pauses. A new edit after undo removes the redo branch.
- Ctrl/⌘+Z undoes and Ctrl/⌘+Shift+Z redoes. The shared undo/redo action accepts at most one command per second and ignores held-key repeats. Text-field undo remains local to text.
- Persisted edits require persisted compensation. Serialize server-writing edits and their undo/redo against the latest confirmed version. Do not declare success, consume the successful history transition or overwrite newer content when a write fails or its result is unknown; reconcile authoritative state before continuing after conflicts or uncertain results.
- On refresh restore only server-saved work; the undo stack is not persisted across refresh. Warn before leaving unsaved page-session drafts. Keep task, stage and ownership changes isolated from stale responses and old history.
### Save and submission contracts
- Ctrl/⌘+Enter with a current draft only saves that description. Missing endpoint or text requirements produce validation feedback rather than falling through to submission. Drafts on other slices must be resolved before submitting the stage.
- With no outstanding drafts, Ctrl/⌘+Enter opens the current stage confirmation: generate confirmed slices during slicing, or complete annotation and hand off to quality review during annotation.
- The confirmation shows the operation and relevant slice, description and blank state. A new independent Enter press confirms; Esc cancels. A held key or repeated event must not both open and confirm the dialog.
- Pending requests and processing lock conflicting mutations and repeated submission. A processing response means accepted work, not completion. Only the authoritative completed stage allows annotation to begin or the next task to be claimed.
- Failed operations preserve recoverable edits and show the actual failure. Existing role, ownership, version, dictionary, frame, overlap and coverage checks remain active.
### Dedicated work page and continuous claiming
- Provide a work page within the existing browser tab. Explicit Start Work activates continuous mode after selecting an authorized project; continue the current unfinished task when present.
- On confirmed successful quality handoff, acquire one next task through the existing project-random claim operation. Keep project/supplier scope, blind pre-claim selection and permanent request-to-result idempotency.
- Stop After Current Task allows the current task to finish without another claim and does not release ownership.
- Empty pools, processing failures, unknown network results and permission changes pause continuous operation with a recovery entry point. Do not silently skip the unresolved task; an uncertain claim retries or reconciles using its existing request identifier.
- Refresh or reopen displays owned work and requires an explicit continuation; it does not silently issue a new claim.
- Only one page in the same browser, account and project may execute automatic continuous claiming. Other pages direct the user to the active work page. This is not a new cross-device or server-wide one-task-per-user restriction; existing server authorization and idempotency remain authoritative.
### Preserved business rules
- Slices fully partition the common hardware-frame range with no overlap or hole. Descriptions stay within a slice, align to valid boundaries and do not overlap.
- Semantic annotation may be partly or wholly blank. Blank, explicitly invalid and discarded are distinct: blank kept media remains reviewed and delivered, while discarded slices retain review evidence and are excluded from delivery according to existing rules.
- Naming rules, reviewer separation, forbidden self-release, permissions, audit evidence, async generation, current-version ownership and delivery contracts remain unchanged. Existing C behavior for splitting an action during annotation must not be confused with source-slice splitting.
## Testing Decisions
### Confirmed testing boundary
The user confirmed the recommended test boundary for this spec: the primary seam is the complete workbench journey through real browser interactions and existing public API writes/readback. Add focused tests at the existing HTTP application boundary for version conflicts, idempotency and pending-operation restrictions, and use existing pure-function interfaces only for precise keyboard, frame and throttling edge cases. No new test-only business interface is planned.
A good test drives an observable action and asserts its visible or persisted outcome. It should survive changes to component internals, state variable names and storage of the undo stack. Source-string matches or private-state assertions are not acceptance evidence for these features. A rendered page title alone is not proof that playback, focus or saving works.
### Modules and prior art
- Exercise the integrated task coordinator, Capture workbench, synchronized player, dictionary pickers and dedicated work page through actual keyboard/mouse input, active focus, playback position, confirmation visibility and server readback.
- Reuse the repository's browser-acceptance pattern of staged annotation/quality/acceptance fixtures, authenticated identities, real task selection and browser-network diagnostics. Extend it for shortcut/focus and same-browser multi-page behavior; do not assume the existing layout checks already cover those interactions.
- Reuse combined-draft HTTP tests that verify version comparison, ownership and saved state without advancing the stage. Extend the external request/readback pattern to compensating undo and rejected stale restoration.
- Reuse pending-submission mutation-conflict tests and random-claim tests for processing locks, repeated logical requests, scope and uncertain results. Exercise conflicts at HTTP boundaries instead of asserting internal retry implementation.
- Reuse public keyboard-resolution and dictionary-navigation tests for composition, native control handling and repeat events. Existing playhead-draft, unified frame-boundary, optional-annotation and submission-state tests provide prior art for the relevant domain rules.
- Some existing frontend tests inspect source strings. Do not copy that approach as proof of the new user behavior, and do not expand this feature into a wholesale test-suite rewrite.
### Environment, failure coverage and completion
- Use the local replica: frontend 5173, API 3001 and snapshot Mongo 27018, with isolated local tasks and test data for mutating flows. Do not run acceptance against company services or BOS by default. Existing acceptance tooling must be explicitly pointed at local services because its defaults can target a remote environment.
- Browser tests must cover keyboard and equivalent mouse edits, editable versus noneditable focus, Chinese composition, held keys, exact frame playback, persisted undo, outstanding cross-slice drafts, two-step confirmation, duplicate pages and resumed tasks.
- HTTP tests must cover stale versions, changing ownership, write failures, processing locks and idempotent claim retries. Network fault tests assert that pending/unknown is not success and that recovery does not allocate a second task.
- Pure-function tests supplement the high-level seam for one-second boundaries, the 100-step cap, redo invalidation and precise frame behavior without prescribing internal data structures. Where clock control is needed, keep it at the existing test runner or session boundary.
- Type checking, relevant frontend/backend tests and compilation must pass. Record existing full-suite failures separately and compare against the baseline; existing failures do not excuse new regressions.
- Phase one covers A01–A14 and A18. Phase two adds A15–A17 and the full continuous-work journey. All criteria below are implementation acceptance requirements, not claims that tests have already been executed.
| 编号 | 场景 | 必须观察到的结果 |
| --- | --- | --- |
| A01 | 连续播放,在已有多个切片的中间片内按 C | 原帧切分并原地暂停,选中项不回退第一片;Space 可越过新增边界继续播放 |
| A02 | 在工作点离开复查,连续切换两片并按 B | 每次 B 都从选中片头播放到片尾;V 返回最初记录的工作点并暂停 |
| A03 | 描述编辑阶段播放和普通左右键逐帧 | 不跨当前切片;左右视频仍使用统一硬件帧范围,步长不受倍速影响 |
| A04 | N 开始,在允许的区间内再次 N 或 Enter 结束 | 两种方式确认同一终点,进入描述编辑区而非直接提交;F 选词、Enter 输入、Ctrl/⌘+Enter 保存 |
| A05 | 输入法组合、输入框内空格/F、Ctrl+X、Ctrl+Z | 输入法和文字编辑正常,不触发播放器、字典、批量无效或工作台撤销 |
| A06 | 字典打开后按一次 Esc,再按 Space | 字典关闭,草稿保留,Space 播放/暂停视频,不重开字典 |
| A07 | 本片有未保存动作,Ctrl/⌘+方向键切到另一片,再返回 | 原动作草稿仍在且未偷偷保存;首尾不循环,未处理尾片可导航 |
| A08 | 切分、边界拖动、误删切片后逐步撤销/重做 | 完整恢复对应范围及名称/状态,覆盖无缺口;跨片操作定位到受影响片,不把播放动作算进历史 |
| A09 | 描述已保存或删除后撤销,再重新读取任务 | 服务器与界面内容一致;保存失败、结果未知、版本冲突均不伪报成功或覆盖其他新状态 |
| A10 | 对多个语义空白按 Ctrl+X | 仅当前片的全部空白被明确标为无效;一次撤销恢复全部空白,已有描述不变 |
| A11 | 长按撤销、快速反复按、撤销后新编辑 | 每秒最多一个成功受理的撤销/重做动作,长按不连发;新编辑截断重做分支,保留最多 100 步 |
| A12 | 有本片草稿、其他片草稿、全部无草稿,分别按 Ctrl/⌘+Enter | 分别保存当前描述、要求处理其他草稿、打开阶段确认;一次按住 Enter 不穿透确认 |
| A13 | 确认生成或送检后返回 processing,随后成功或失败 | 等待真实状态;成功才进入下一阶段,失败保留恢复入口;不能重复提交或跨阶段撤销 |
| A14 | 语义全空、部分留空、明确无效、舍弃片段分别送检 | 保持现有区别:留空合法且仍交付,舍弃证据保留并过滤交付;快捷键不绕过字典、权限和边界校验 |
| A15 | 开始连续工作,完成当前任务后停止 | 当前任务正常送检,之后不再随机领取;已领取任务不被释放 |
| A16 | 连续模式遇空池、网络结果未知、服务端处理失败、权限改变 | 暂停并说明状态,不跳过当前任务;领取结果未知时沿用原请求编号核对/重试 |
| A17 | 刷新、重开或同账号项目打开第二个工作页 | 不静默追加领取;恢复已领取任务并显式继续,只有一个页面执行自动连续领取 |
| A18 | 新增/撤销动作、刷新或离开任务 | 刷新只恢复后端已保存内容,历史不跨刷新;未保存内容受离开提醒保护,进入新的任务/阶段不使用旧撤销栈 |
## Out of Scope
- Reversing slice generation, re-slicing effects or quality handoff through ordinary undo; changing the stage boundary defined by ADR-0001.
- Persisting undo history across refresh, devices or sessions, or offering unlimited edit history. Unsaved action drafts remain page-session data with leave protection.
- Rewriting the random-assignment service, adding a global one-task-per-account rule, exposing unclaimed candidate videos or letting annotators self-release tasks.
- Altering hardware timing, synchronized media, dictionary-only slice naming, blank/invalid/discard meaning, review roles, audit evidence, output format or delivery policy.
- Replacing the async processing architecture, changing deployment environments or claiming backend performance improvements beyond the agreed interaction work.
- Opening a separate browser popup, rebuilding unrelated administration/reviewer pages, or introducing new shortcuts beyond the approved set.
- Fixing unrelated existing test debt, deploying to company infrastructure, writing to the company BOS bucket, pushing a branch or messaging colleagues.
- Treating this specification as customer approval or claiming the protected customer source document has been read.
## Further Notes
- This is the published specification in the repository's local Markdown issue tracker. The ready-for-agent status applies to the approved scope and test boundary; it is not a claim that implementation or acceptance is complete.
- The user approved the initial four decisions and the following five recommendations, then explicitly accepted the browser/public-API testing seam. No new requirements interview is needed to act on those decisions.
- Domain terminology follows the repository glossary. ADR-0001 records why already-saved edits can be undone inside an editing stage while generation and review transitions cannot.
- The earlier requirements audit remains evidence about the old implementation, not a description of the intended new behavior. Preserve its distinction between observations inferred from code and interactions actually reproduced in a browser.
- The customer issue table is located in Feishu but required login during this session. Comparison so far used the latest local contracts, tests and colleague changes; it does not certify alignment with the unread customer original.
- Older local documents still contain superseded requirements that descriptions must cover every interval or that slice names can be freely entered. The newer five-rule and optional-annotation contracts and their tests govern those points for this spec.
- Implementation should proceed in the agreed order: complete and verify the current-workbench behavior before adding the dedicated continuous-work page. Task decomposition is separate from publication of this specification.

View File

@ -0,0 +1,31 @@
# 专注标注工作页任务索引
用户已确认拆分并授权发布,共 8 份独立任务。已按编号顺序完成实施及逐票独立审查;最终全功能双轴审查已完成,见[最终报告](../../docs/verification/annotation-workspace-layout/final-review.md)。
父规格:[专注工作页布局规格](./spec.md)。设计记录:[map.md](./map.md)。已确认的拆分及覆盖矩阵:[ticket-breakdown.md](./ticket-breakdown.md)。布局示意:[preview.html](./preview.html)。
## 任务与依赖
| 编号 | 任务 | 直接前置 | 状态 |
| --- | --- | --- | --- |
| 01 | [专注工作视图与原布局无损切换](./issues/01-focused-view-and-legacy-switch.md) | 无 | resolved |
| 02 | [切片阶段在一屏内完成操作](./issues/02-single-screen-slicing.md) | 01 | resolved |
| 03 | [动作标注阶段固定编辑与保存](./issues/03-fixed-description-editing.md) | 02 | resolved |
| 04 | [大量切片和描述的分页定位](./issues/04-paged-selection-navigation.md) | 03 | resolved |
| 05 | [固定区域内的字典和长文本编辑](./issues/05-inline-dictionaries-and-long-text.md) | 03 | resolved |
| 06 | [单路放大与视频比例适配](./issues/06-camera-inspection-and-aspect-fit.md) | 03 | resolved |
| 07 | [小窗口暂停与在途结果协调](./issues/07-undersized-viewport-recovery.md) | 01 | resolved |
| 08 | [连续工作整体验收与操作手册](./issues/08-full-workflow-acceptance-and-guide.md) | 04、05、06、07 | resolved |
## 执行顺序
初始仅 01 可执行。01 完成后 02、07 就绪;02 完成后可做 03;03 完成后 04、05、06 就绪;04、05、06、07 全部完成后进行 08。
单线执行可按 01→02→03→04→05→06→07→08;共享编辑器的改动需要协调,但不因此增加业务依赖。每票自带验收,08 负责组合验收和说明书,不能替前置票补交其必要测试。
## 覆盖与边界
- 全部 30 条用户故事和 L01–L16 均有负责票,详细映射保留在拆分记录;共 60 项独立验收检查。
- 产品入口、快捷键、草稿、撤销、真实保存及连续领取沿用现有契约。新旧布局共用编辑逻辑,切换不能丢状态或重复领任务。
- 本地原版恢复标签为 `codex/annotation-keyboard-baseline-20260918`,指向 `54a35afad95d77b1f23c955f9c4671cae83a664d`;完整 bundle 已验证。运行中布局回退已由 01 实现并验收;代码备份与页面内布局切换的恢复范围不同。
- 任务发布记录保留在本地 Markdown 目录。01–07 已实施并独立验收,08 正在整体验收;本轮没有推送远端、合并或部署。

View File

@ -0,0 +1,37 @@
# 01: 专注工作视图与原布局无损切换
Status: resolved
Type: task
Parent: [专注工作页布局规格](../spec.md)
**What to build:** 在当前标签页进入专注工作视图、收起平台导航并保留返回路径;用户可以在工作中切回原布局而不丢失编辑状态,重新进入时沿用当前账号的浏览器偏好。
**Blocked by:** None (can start immediately)
**覆盖:** 用户故事 1、2、25、26、27、28、29、30;场景 L01、L10、L11、L14、L16。
- [x] 先隔离呈现选择与已有编辑会话,保持既有播放器、请求归属、草稿和历史的生命周期;用原布局现有行为作基线验证后,再接入视图切换。
- [x] 开始工作使用已有项目和领取链路;专注视图收起平台导航,返回任务池仍有原有未保存离开保护,原任务池入口保持可用。
- [x] 无偏好账号默认新工作视图;布局偏好仅影响当前账号和浏览器,不跨账号串用。刷新依旧需要显式恢复任务,不能因读取偏好而自动领任务。
- [x] 新旧视图反复切换保留当前任务/阶段/选中项/播放帧、不同切片草稿、文本与撤销/重做;切换不提交、释放或重新领取任务。
- [x] 保存请求延迟返回时切换布局,原结果仍正确回读;不重复写入,不清空草稿,不绕过处理中限制或会话归属检查。
- [x] 切换入口在常规编辑状态始终可达;确认可回到真实原布局,而非复制出的近似界面。
- [x] 浏览器编辑及 API 回读证明状态保留;原快捷键、原任务入口和原布局常用编辑路径通过相关回归。
- [x] 核对既有恢复标签仍指向原基线,文档中区分源码恢复与业务数据恢复。
**本票边界:** 新视图先完成专注外壳和无损切换,不以此宣称两阶段新布局、免滚轮和画面尺寸全部交付;这些由 02/03 及长内容任务完成。
## Constraints
遵守父规格、已确认布局示意与 ADR-0001。保留现有快捷键、精确帧、字典命名、语义留空/无效/舍弃区别、版本与领取归属及审核流转契约;不复制第二套编辑器,不用布局切换触发任务重领、隐式保存或状态重置。只做本票所需的局部整理。
以本地 5173/3001/27018 隔离任务进行真实浏览器操作和现有 API 保存回读;适用的类型检查、构建及行为测试须通过。原有失败与新增回归分别记录,不用源码字符串断言替代交互验收。公司集群/BOS 不在写入授权范围,凭据和原始证据不进入跟踪文件。
定义就绪不代表依赖完成;所有直接前置交付并验收后才能领取。发布不启动实现,也不授权推送或部署。
## Answer
已在 `a5753731` 实现专注外壳与原布局切换,`6acc5803` 补充连续工作选择的浏览器证据,独立审查与复审均通过。真实浏览器和 API 验证了播放帧、双片草稿、延迟保存、撤销/重做、账号偏好隔离,以及连续工作和停止选择的保留。类型检查、Web 构建和 44 项定向测试通过;源码标签与 bundle 已独立核验。
参见[设计记录](../map.md#decisions-so-far)与[操作说明](../../../docs/annotation-workspace-layout.md)。

View File

@ -0,0 +1,37 @@
# 02: 切片阶段在一屏内完成操作
Status: resolved
Type: task
Parent: [专注工作页布局规格](../spec.md)
**What to build:** 在新视图的切片阶段,用固定可见的双视频、播放/逐帧/切分控制、时间轴、命名区域和确认操作完成切片,再等待真实生成结果。
**Blocked by:** 01:专注工作视图与原布局无损切换
**覆盖:** 用户故事 3、4、5、6、7、8、9、16、17、28;场景 L02、L04、L16,以及切片阶段的 L03/L15。
- [x] 先为现有视频、时间轴和编辑操作建立共用呈现区域,保持业务回调与媒体节点稳定,再实现左侧双视频、下方控制/时间轴、右侧命名和固定提交区。
- [x] 在 1280×640 内容区,590×480 基准双视频各自的有效画面不小于 400×325;完整等比显示,无自动隐藏。更大内容区继续扩大可用视频面积。
- [x] 两路视频、Space、C、逐帧、B/V、切片名称、撤销/重做、确认和返回/停止入口在正常短列表任务中可见,不依赖文档滚动。
- [x] C 切分后保留切点,原播放、精确帧定位、切片覆盖和字典命名契约继续成立。
- [x] 阶段状态、错误和处理提示不把主要按钮挤出视口;需要较长解释时从固定入口展开。
- [x] 确认仍走原两步确认及真实异步生成;收到 processing 不能提前进入已完成状态。通过 API 回读确认切片结果。
- [x] 新样式限定在新布局;切回原布局后仍符合 01 的状态保留要求。
- [x] 用五档支持的内容区进行本阶段几何与操作检查,完成类型/构建及受影响行为测试。
**本票边界:** 使用现有字典入口保持可用;固定编辑区字典由 05 完成,大列表由 04 完成,不借本票改写字典或领取规则。
## Constraints
遵守父规格、已确认布局示意与 ADR-0001。保留现有快捷键、精确帧、字典命名、语义留空/无效/舍弃区别、版本与领取归属及审核流转契约;不复制第二套编辑器,不用布局切换触发任务重领、隐式保存或状态重置。只做本票所需的局部整理。
以本地 5173/3001/27018 隔离任务进行真实浏览器操作和现有 API 保存回读;适用的类型检查、构建及行为测试须通过。原有失败与新增回归分别记录,不用源码字符串断言替代交互验收。公司集群/BOS 不在写入授权范围,凭据和原始证据不进入跟踪文件。
定义就绪不代表依赖完成;所有直接前置交付并验收后才能领取。发布不启动实现,也不授权推送或部署。
## Answer
已在 `a3c780e8` 实现切片阶段固定布局,独立审查通过。五档内容区通过验收,最小每路有效画面约 410.5×334;真实生成完成 4 片、覆盖 412 秒,服务端版本为 5。快捷键、媒体同步、历史、字典命名和二次确认均有浏览器证据,52 项定向测试、类型检查与构建通过。审查时人工检查的错误控件命中测试由 08 补入长期脚本。
参见[设计记录](../map.md#decisions-so-far)与[操作说明](../../../docs/annotation-workspace-layout.md)。

View File

@ -0,0 +1,35 @@
# 03: 动作标注阶段固定编辑与保存
Status: resolved
Type: task
Parent: [专注工作页布局规格](../spec.md)
**What to build:** 切片生成后在相同的空间骨架中填写动作描述、保存、撤销并送检;视频、编辑区和主要按钮不换位置。
**Blocked by:** 02:切片阶段在一屏内完成操作
**覆盖:** 用户故事 7、8、9、10、16、17、28、29;场景 L02、L09、L10、L15、L16。
- [x] 复用切片阶段已建立的呈现区域,将动作编辑接入右侧固定区,避免条件渲染重建播放器或丢失当前编辑会话。
- [x] 从切片到描述阶段只变更相关编辑内容;视频/时间轴/编辑/提交区保持相同方位,两阶段均满足基准画面尺寸。
- [x] N 开始、N/Enter 结束、输入文本、保存/取消及阶段提交可从固定区域完成;保留当前快捷键、焦点和中文输入法规则。
- [x] 保存按原版本/归属校验写入服务端;失败保留内容,撤销/重做已保存描述后用 API 回读确认,不以浏览器画面替代真实结果。
- [x] 跨片草稿、未完成草稿的提交拦截和 Ctrl/⌘+Enter 的保存/提交优先级保持一致。
- [x] 正常任务的帮助、舍弃原因、提交确认和失败提示可由固定入口访问,确认按钮不超出视口;低频内容按需展开。
- [x] 确认送检仍等待审核数据准备完成;只在真实送检后按原规则接续,不等待质检员判定,也不把 processing 当完成。
- [x] 在五档支持内容区完成本阶段操作检查,并在有草稿/已保存历史时切回原布局验证状态。
## Constraints
遵守父规格、已确认布局示意与 ADR-0001。保留现有快捷键、精确帧、字典命名、语义留空/无效/舍弃区别、版本与领取归属及审核流转契约;不复制第二套编辑器,不用布局切换触发任务重领、隐式保存或状态重置。只做本票所需的局部整理。
以本地 5173/3001/27018 隔离任务进行真实浏览器操作和现有 API 保存回读;适用的类型检查、构建及行为测试须通过。原有失败与新增回归分别记录,不用源码字符串断言替代交互验收。公司集群/BOS 不在写入授权范围,凭据和原始证据不进入跟踪文件。
定义就绪不代表依赖完成;所有直接前置交付并验收后才能领取。发布不启动实现,也不授权推送或部署。
## Answer
已在 `e462437a` 实现固定描述编辑、保存、取消、历史与送检,独立审查通过。五档内容区均满足每路至少 410.5×334 的实测画面。真实保存、409 冲突、草稿、取消及历史均通过 API 回读;隔离任务送检后进入 quality_review,版本为 6。56 项定向测试、类型检查、构建及 01/02 浏览器回归通过;重复动作区 CSS 留待 08 局部整理。
参见[设计记录](../map.md#decisions-so-far)与[操作说明](../../../docs/annotation-workspace-layout.md)。

View File

@ -0,0 +1,33 @@
# 04: 大量切片和描述的分页定位
Status: resolved
Type: task
Parent: [专注工作页布局规格](../spec.md)
**What to build:** 切片和描述数量超过一屏时,列表仍保持在有限空间内;鼠标与键盘导航、撤销/重做使当前项自动出现在正确页。
**Blocked by:** 03:动作标注阶段固定编辑与保存
**覆盖:** 用户故事 13、14、28;场景 L08、L10,补充大数据量下的 L02/L16。
- [x] 切片和动作描述列表使用有界区域,页码及前后页控制保持可见;提供适合现有列表的搜索/定位入口,不靠文档滚动或无限增加高度。
- [x] 保持真实时间顺序;过滤或分页不改变数据,也不把 Ctrl/⌘+左右的原相邻切片语义改成只在可见页内循环。
- [x] 跨页选中、键盘换片、B/V 复查及撤销/重做后,受影响条目所在页可见;不能出现操作成功但目标被过滤隐藏而无提示。
- [x] 新增、删除或合并导致总页数变化时,页码保持有效;选中关系遵守现有编辑规则,不引用已删除对象。
- [x] 页面导航不自动保存草稿;切片间保留草稿,返回仍可编辑。切换原布局后内容和撤销历史保持一致。
- [x] 用切片和描述均超过一页的隔离任务进行浏览器操作,覆盖跨页撤销、删除后尾页变空和 API 保存回读。
## Constraints
遵守父规格、已确认布局示意与 ADR-0001。保留现有快捷键、精确帧、字典命名、语义留空/无效/舍弃区别、版本与领取归属及审核流转契约;不复制第二套编辑器,不用布局切换触发任务重领、隐式保存或状态重置。只做本票所需的局部整理。
以本地 5173/3001/27018 隔离任务进行真实浏览器操作和现有 API 保存回读;适用的类型检查、构建及行为测试须通过。原有失败与新增回归分别记录,不用源码字符串断言替代交互验收。公司集群/BOS 不在写入授权范围,凭据和原始证据不进入跟踪文件。
定义就绪不代表依赖完成;所有直接前置交付并验收后才能领取。发布不启动实现,也不授权推送或部署。
## Answer
已在 `94b238d5` 实现分页定位,`e95adca8` 完成审查修复,独立复审通过。13 个切片、13 条描述覆盖分页、查找、序号直达、极小区间、草稿、尾页删除和跨片重做。页尾指针拖动验证了双向移动及同一横坐标不重复移动,描述边界以 API 回读核对。五档尺寸、外壳回归、56 项定向测试、类型检查与构建通过。
参见[设计记录](../map.md#decisions-so-far)与[操作说明](../../../docs/annotation-workspace-layout.md)。

View File

@ -0,0 +1,34 @@
# 05: 固定区域内的字典和长文本编辑
Status: resolved
Type: task
Parent: [专注工作页布局规格](../spec.md)
**What to build:** 切片名称字典和动作描述字典在固定编辑区内搜索、翻页、选择;长描述可局部滚动或展开编辑,保存/取消一直可见。
**Blocked by:** 03:动作标注阶段固定编辑与保存
**覆盖:** 用户故事 11、12、15、16、17、28;场景 L07、L09、L10,以及相关 L02/L16。
- [x] 先保留现有字典选择与输入契约,将同一能力接入固定编辑区;不另建与旧工作台行为不一致的字典实现。
- [x] 两类字典都支持搜索与分页,搜索框、翻页和返回入口保持可见;打开字典不改变视频位置或挤走播放控制。
- [x] F/D、方向键、Enter 与一次 Esc 保留已有语义;选描述模板后可继续编辑,不能自动保存。关闭后 Space 不重新激活字典按钮。
- [x] 长文本只在输入内容区内部滚动,提供展开编辑;保存/取消固定在滚动区外。展开与收起不触发业务保存或丢失输入。
- [x] 中文输入法组合、文本框剪切/原生撤销、工作台撤销分别按已有键盘归属处理。
- [x] 长词条、长描述和长提交摘要不把确认按钮挤出屏幕;必要内容可完整阅读,操作无需寻找滚轮下方按钮。
- [x] 用多页字典与长文本在最低内容区演示选择、编辑、保存、一次 Esc 返回和布局切换,并以 API 回读验证真实保存。
## Constraints
遵守父规格、已确认布局示意与 ADR-0001。保留现有快捷键、精确帧、字典命名、语义留空/无效/舍弃区别、版本与领取归属及审核流转契约;不复制第二套编辑器,不用布局切换触发任务重领、隐式保存或状态重置。只做本票所需的局部整理。
以本地 5173/3001/27018 隔离任务进行真实浏览器操作和现有 API 保存回读;适用的类型检查、构建及行为测试须通过。原有失败与新增回归分别记录,不用源码字符串断言替代交互验收。公司集群/BOS 不在写入授权范围,凭据和原始证据不进入跟踪文件。
定义就绪不代表依赖完成;所有直接前置交付并验收后才能领取。发布不启动实现,也不授权推送或部署。
## Answer
已在 `1de1d85b` 实现固定字典与长文本,`6c76e5d2` 修复焦点返回,独立复审通过。两类字典的搜索、分页、选词、一次 Esc 返回及长词条可读性通过五档尺寸验证;展开编辑保留同一文本框,真实保存/撤销/重做通过 API 回读。Tab 或外部点击后 Esc 与 Space 的焦点归属通过且没有写入。47 项定向测试、类型检查和构建通过。原生剪切/撤销已测,系统中文输入法未实测,组合事件检查单独标明。
参见[设计记录](../map.md#decisions-so-far)与[操作说明](../../../docs/annotation-workspace-layout.md)。

View File

@ -0,0 +1,34 @@
# 06: 单路放大与视频比例适配
Status: resolved
Type: task
Parent: [专注工作页布局规格](../spec.md)
**What to build:** 任一路视频可主动临时放大以检查细节;详细时间轴随之收成进度条,恢复双画面后原操作状态不变,不同视频比例仍完整显示。
**Blocked by:** 03:动作标注阶段固定编辑与保存
**覆盖:** 用户故事 3、4、5、18、19、20、28;场景 L04、L05、L06、L10。
- [x] 切片与描述两阶段默认双画面等大且同步;窄窗口不自动隐藏某一路。
- [x] 用户主动放大左路或右路时,将详细时间轴临时压缩为进度条,真实增加画面高度,而非只隐藏另一路。
- [x] 在 1280×640、59:48 基准素材下,单路有效画面至少 490×398;正常双画面仍符合每路 400×325 下限。度量实际图像而非容器留白。
- [x] 放大期间播放、逐帧、当前阶段标记、编辑、保存和提交仍可用;恢复双画面同时恢复详细时间轴。
- [x] 保留播放帧、同步关系、草稿、选中项和历史;不通过清空媒体源或重建编辑会话来切换。
- [x] 用真实约 1.23:1 双视频及明确标注的 16:9、9:16、左右不同比例合成样例验证等比完整显示,避免把演示数据宣称为客户素材覆盖。
- [x] 放大/恢复后验证时间轴鼠标定位与键盘逐帧仍对应正确原始帧,不能因显示尺寸变化改变时间映射。
## Constraints
遵守父规格、已确认布局示意与 ADR-0001。保留现有快捷键、精确帧、字典命名、语义留空/无效/舍弃区别、版本与领取归属及审核流转契约;不复制第二套编辑器,不用布局切换触发任务重领、隐式保存或状态重置。只做本票所需的局部整理。
以本地 5173/3001/27018 隔离任务进行真实浏览器操作和现有 API 保存回读;适用的类型检查、构建及行为测试须通过。原有失败与新增回归分别记录,不用源码字符串断言替代交互验收。公司集群/BOS 不在写入授权范围,凭据和原始证据不进入跟踪文件。
定义就绪不代表依赖完成;所有直接前置交付并验收后才能领取。发布不启动实现,也不授权推送或部署。
## Answer
已在 `ee3d6b16` 实现单路检查,`af7df833` 完成审查修复,独立复审通过。最小双路有效画面每路约 410.54×334,单路约 531×432,进度条不覆盖画面。五档尺寸、帧定位、草稿、历史、指针映射和原布局左右显示偏好恢复通过,未写入 fixture。16:9 / 9:16 为合成比例案例,单独标明。79 项定向测试、类型检查、构建与浏览器/API 检查通过。
参见[设计记录](../map.md#decisions-so-far)与[操作说明](../../../docs/annotation-workspace-layout.md)。

View File

@ -0,0 +1,35 @@
# 07: 小窗口暂停与在途结果协调
Status: resolved
Type: task
Parent: [专注工作页布局规格](../spec.md)
**What to build:** 新工作页空间低于最低要求时安全暂停,当前内容保留;已经发出的请求仍正确核对,恢复空间后由用户主动继续。
**Blocked by:** 01:专注工作视图与原布局无损切换
**覆盖:** 用户故事 6、21、22、23、24、29;场景 L03、L12、L13,补充 L11/L15。
- [x] 先将因视口不足而暂挂的状态与现有连续工作意图区分开,再将其接入原会话的播放和接续边界;不得把暂停当成释放任务或丢弃会话。
- [x] 新布局的有效内容区宽度小于 1280 或高度小于 640 即暂停播放与新的自动接续,并明确提示调整窗口/缩放;精确边界值正常可用。
- [x] 当前任务、选中片、播放帧、跨片草稿及撤销保留;不自动切旧布局、不默默挤小按钮。该限制不改变旧布局的既有行为。
- [x] 窗口恢复尺寸本身不续播或领任务。显式继续后恢复操作和此前连续工作设置,视频仍需主动播放;此前的完成本条后停止选择保持有效。
- [x] 已发出的保存、生成和送检请求继续依据原请求与版本核对;送检在暂停期间成功后只记录结果,等待显式继续才触发下一次接续。
- [x] 已发出的随机领取即使在暂停期间成功也保留该任务;结果未知时沿用同一请求号核对,不因缩放或重试再领一条。
- [x] 权限错误、结果未知、会话冲突和处理限制不会因“继续”按钮被绕过;旧/新布局切换同样保留在途请求归属。
- [x] 用真实浏览器缩放/调整窗口和可控延迟或断开响应验证播放、保存、生成、送检与领取边界,并通过 API 回读任务与版本。
## Constraints
遵守父规格、已确认布局示意与 ADR-0001。保留现有快捷键、精确帧、字典命名、语义留空/无效/舍弃区别、版本与领取归属及审核流转契约;不复制第二套编辑器,不用布局切换触发任务重领、隐式保存或状态重置。只做本票所需的局部整理。
以本地 5173/3001/27018 隔离任务进行真实浏览器操作和现有 API 保存回读;适用的类型检查、构建及行为测试须通过。原有失败与新增回归分别记录,不用源码字符串断言替代交互验收。公司集群/BOS 不在写入授权范围,凭据和原始证据不进入跟踪文件。
定义就绪不代表依赖完成;所有直接前置交付并验收后才能领取。发布不启动实现,也不授权推送或部署。
## Answer
已完成小窗口暂停、主动恢复与在途请求协调,提交为 `cb74444e`,独立审核修复为 `972721e`。保存、生成、送检和领取均通过真实浏览器与 API 验收;延迟的本人任务列表及详情不会越过暂停切换任务。连续工作选择、草稿、历史与权限限制均保留。独立 reviewer 已复审通过。
说明见 [设计记录](../map.md#decisions-so-far);完整结果将在整体验收报告汇总。

View File

@ -0,0 +1,35 @@
# 08: 连续工作整体验收与操作手册
Status: resolved
Type: task
Parent: [专注工作页布局规格](../spec.md)
**What to build:** 在新界面完成真实连续作业,并可可靠切回旧界面;形成覆盖所有规格的结果报告和标注人员能直接使用的操作说明。
**Blocked by:** 04:大量切片和描述的分页定位;05:固定区域内的字典和长文本编辑;06:单路放大与视频比例适配;07:小窗口暂停与在途结果协调
**覆盖:** 全部 30 条用户故事、L01–L16;本票负责组合验收和交付,不代替各前置任务自身的验收。
- [x] 完成开始工作→已有任务优先/随机领取→切片→真实生成→描述→保存→送检→下一条的浏览器/API 闭环,验证停止、空池及未知结果恢复。
- [x] 五档支持内容区覆盖两阶段、字典、长列表、长文本、单路放大、错误与确认弹层;主要操作无文档横向/纵向滚动即可完成。
- [x] 代表性 1366×768、1440×900、1920×1080、2560×1440 显示/窗口设置下核对 100%、125%、150% 浏览器缩放,记录真实 CSS 内容区,按是否达到底线验证正常或暂停行为。确实无法覆盖的设备/系统缩放组合必须注明限制,不能用模拟视口冒充全部物理设备实测。
- [x] 交叉验证草稿/撤销/在途请求情况下的新旧布局切换、刷新显式恢复、账号偏好隔离和单活动页规则。
- [x] 原任务池入口、原布局及既有快捷键回归通过;检查新布局样式没有意外作用于质检/验收工作台。
- [x] 完成适用的类型检查、构建与行为测试;既有失败与新增回归分开报告,前置票未通过的验收不能被最终报告掩盖。
- [x] 交付说明书覆盖进入/退出、字典与长内容、临时放大、切回旧版、小窗口恢复、保存与提交、停止接续;明确“送检成功”不同于“质检通过”。
- [x] 交付恢复说明和验证报告:确认代码标签/bundle可恢复,区分代码与数据库/视频/浏览器草稿;不进行公司集群部署或额外推送。
## Constraints
遵守父规格、已确认布局示意与 ADR-0001。保留现有快捷键、精确帧、字典命名、语义留空/无效/舍弃区别、版本与领取归属及审核流转契约;不复制第二套编辑器,不用布局切换触发任务重领、隐式保存或状态重置。只做本票所需的局部整理。
以本地 5173/3001/27018 隔离任务进行真实浏览器操作和现有 API 保存回读;适用的类型检查、构建及行为测试须通过。原有失败与新增回归分别记录,不用源码字符串断言替代交互验收。公司集群/BOS 不在写入授权范围,凭据和原始证据不进入跟踪文件。
定义就绪不代表依赖完成;所有直接前置交付并验收后才能领取。发布不启动实现,也不授权推送或部署。
## Answer
已完成整体验收与中文说明书,提交 `89c9e168`;验收脚本的审核修复为 `ab89c63a`。最终同一份脚本完整运行退出 0,真实完成三条任务的生成、保存、送检及接续、停止、空池行为;12 组实际浏览器缩放和五档布局回归通过。独立 reviewer 已复审通过。
[整体验收报告](../../../docs/verification/annotation-workspace-layout/acceptance-results.md)保留原生系统输入法、物理设备缩放及本地验收媒体缺失的覆盖限制;[操作说明书](../../../docs/annotation-workspace-layout.md)可直接交给标注人员。执行范围未包括推送、合并或部署。设计决策见[设计记录](../map.md#decisions-so-far)。

View File

@ -0,0 +1,85 @@
# 人工标注专注工作页:设计讨论
Type: grilling
日期:2026-09-18。当前状态:需求、交互示意和[正式规格](./spec.md)已确认;实施票 01–08 均已解决并分别独立审查通过。本文件保留设计阶段的讨论和示意记录,并在下方补充实施结果与验收证据。
## Notes
用户希望在项目内连续完成切片与描述标注,为同步双视频预留足够空间,适配常见显示器,并避免通过滚轮下滑寻找操作功能。要求保留当前快捷键与原界面版本的可恢复备份。
### 已有能力与本轮缺口
以下为设计讨论时的基线观察,描述的是实施前状态,不是当前工作台状态。
- 原规格 tickets 09–11 已完成同标签页独立工作路由、项目开始工作、连续接续、显式恢复和活动页面互斥。参见 [原规格](../annotation-keyboard-workflow/spec.md)、[现有使用说明](../../docs/annotation-keyboard-guide.zh-CN.md)。
- 工作路由为 `/plugins/annotation-qa/workflows/:workflowId/work`,仍共用 `AnnotationOperations` 与 `CaptureAnnotationWorkbench`。原任务池入口与工作页并非两套独立编辑器。
- 自动接续发生在审核数据准备完成、送检成功之后,不等待质检员审核通过。接续时优先本人已领取未完成任务,无待续任务才随机领取。
- 本轮新增重点是工作页空间安排:描述阶段仍为纵向文档流,双视频高度上限 240px;描述编辑区位于时间轴下方且内部可滚动,保存按钮在该区域内。切片自适应布局也允许滚动,尚无跨分辨率的免滚轮操作契约。
- 代码依据:`src/App.tsx`、`src/pages/AnnotationOperations.tsx`、`src/components/CaptureAnnotationWorkbench.tsx`、`src/styles/capture-workspace.css`。上述为只读源码核验,本轮未重新进行浏览器布局测量。
- 客户原始需求文件仍未直接读取;原审计记录表明飞书原文访问需要登录。仓库契约及同事记录是可用依据,不把它们说成客户原文。
### 基线备份(已完成)
- 基线提交:`54a35afad95d77b1f23c955f9c4671cae83a664d`,已在远端个人分支和 PR #1 中。
- 本地带注释标签:`codex/annotation-keyboard-baseline-20260918`。
- 本地独立 Git 备份:`local-data/backups/annotation-keyboard-baseline-20260918.bundle`,约 44.6 MB,未跟踪;`git bundle verify` 通过,包含完整历史。
- 该备份保存源码、已提交的快捷键行为及界面,不保存 Mongo 数据、下载视频、凭据、未提交改动或浏览器草稿。备份保留既有历史,按本地仓库访问范围管理,不另行公开上传。
- 需要回到基线开发时,先保存当时未提交的改动,再从标签创建新的恢复分支,例如 `git switch -c codex/restore-annotation-baseline codex/annotation-keyboard-baseline-20260918`;不使用强制重置覆盖后续工作。
- 若本地仓库丢失,可从 bundle 克隆代码;本地运行环境和业务数据另行恢复。设计阶段确认要在产品内支持切回旧布局;该能力现已由 [01 专注工作视图与原布局无损切换](./issues/01-focused-view-and-legacy-switch.md) 交付,不能只凭 Git 备份视为已具备。
## Decisions-so-far
- **实施状态(当前)**:01–08 均为 `resolved`,并已逐票独立审查。产品已实现专注工作布局;本地浏览器/API 验收、操作说明、全套检查结果和执行记录分别见[整体验收报告](../../docs/verification/annotation-workspace-layout/acceptance-results.md)、[操作说明](../../docs/annotation-workspace-layout.md)、[全套检查结果](../../docs/verification/annotation-workspace-layout/full-suite-results.md)及[执行记录](../../docs/verification/annotation-workspace-layout/execution-record.md)。
- [01 专注工作视图与原布局无损切换](./issues/01-focused-view-and-legacy-switch.md):`a5753731` 实现同标签页专注外壳和状态保留的原布局切换,`6acc5803` 补足连续工作选择跨布局切换验证。
- [02 单屏切片](./issues/02-single-screen-slicing.md):`a3c780e8` 实现固定切片布局和双视频单屏操作,并完成五档内容区及真实生成验收。
- [03 固定描述编辑](./issues/03-fixed-description-editing.md):`e462437a` 使描述编辑、保存、取消、历史与送检固定可达,并验证真实保存和 API 回读。
- [04 分页选择导航](./issues/04-paged-selection-navigation.md):`94b238d5` 增加分页定位与历史目标显示,`e95adca8` 修复跨切片历史定位和页边拖动稳定性。
- [05 内联字典与长文本](./issues/05-inline-dictionaries-and-long-text.md):`1de1d85b` 将字典和长描述置于固定编辑区,`6c76e5d2` 修复焦点离开后的字典关闭与按键归属。
- [06 单路放大与比例适配](./issues/06-camera-inspection-and-aspect-fit.md):`ee3d6b16` 实现单路检查和等比显示,`af7df833` 修复画面遮挡及恢复双路状态。
- [07 小窗口暂停与恢复](./issues/07-undersized-viewport-recovery.md):`cb74444e` 在低于最小内容区时暂停并协调在途请求,`972721e2` 修复本人任务晚到结果在恢复前进入工作页的问题。
- [08 连续工作整体验收与操作手册](./issues/08-full-workflow-acceptance-and-guide.md):`89c9e168` 完成组合验收和中文手册,`ab89c63a` 修复最终工作流运行器并以单次完整三任务链退出 0 复验。
- **当前已知验收限制**:未实测原生操作系统中文输入法、物理显示器与系统缩放;本地最终验收的媒体 members 为 0,因而没有宣称真实验收媒体的视频、姿态或文件完整性通过。未推送、部署或取得 QA 批准。
以下条目为设计阶段已经确认的选择;其“本轮”措辞不表示当前实施尚未开始。
- 沿用已确认的业务约束:项目内随机领取、不能领取前挑选视频、已领取任务优先、送检成功才接续;本轮尚未提出变更这些约束。
- 当前快捷键和原界面行为需要可恢复;代码恢复点已建立并验证。
- 第一轮 Q1 已确认:沿用同标签页独立工作页,进入后收起平台导航,保留原入口。
- 第一轮 Q2 已确认:视频、播放/切片操作、当前描述编辑、保存/提交固定可见;页面不整体滚动,长列表使用搜索、分页和键盘切换。
- 第一轮 Q3 已确认:完整工作布局最低有效内容区为 1280×640 CSS 像素;更小窗口明确提示调整。按实际内容区验收,不仅检查显示器物理分辨率。
- 第二轮 Q4 已确认:默认双视频等大、同步、完整等比显示,不自动隐藏一路;可主动临时放大一路并恢复双画面,播放位置保持不变。
- 第二轮 Q5 已确认:固定编辑区在描述编辑和字典之间切换;低频辅助内容按需展开,保留原有提交确认。
- 第二轮 Q6 已确认:提供运行中切回原布局;共用编辑与快捷键逻辑,保留任务、播放位置、草稿及撤销,不重新领取。
- 第二轮 Q7 已确认:长文本可在固定文本框内滚动并展开编辑;保存/取消始终可见。
- 第三轮 Q8 已确认:左侧双视频,下方播放控制和时间轴,右侧固定编辑区;切片和描述阶段保持同一骨架。
- 第三轮 Q9 已确认:低于 1280×640 时暂停播放与自动接续,保留任务、草稿及撤销;恢复尺寸后手动继续。在途服务端操作仍核对结果。
- 第三轮 Q10 已确认:按当前账号、当前浏览器记住新旧布局偏好,下次进入沿用,始终可切换;免滚轮要求仅约束新布局。
- 第四轮 Q11 已确认:首版自动分配区域空间,不加入可拖拽分栏;保留主动单路放大/恢复。
- 第四轮 Q12 已确认:先看可切换内容区尺寸、阶段和字典的交互示意,再确认最终设计。
- 视觉评审已接受:最低尺寸下视频面积和编辑区安排可用;单路放大可临时将详细时间轴收成进度条,返回双画面后恢复。
- 设计讨论当时已收敛并整理正式规格;当时尚未开始改动产品代码。
## 已确认的交互示意
设计问题已全部回答;以下为实施前示意的范围与验证证据,保留用于说明设计取舍,不替代当前产品验收。
示意保存在 [preview.html](./preview.html),作为可渲染片段;不接业务 API,不进行真实领取、保存或提交,原布局按钮也只说明回退状态,不伪装已实现原布局切换。
- 可切换内容区:1280×640、1366×680、1440×800、1920×980、2560×1320,以及低于底线的 1100×600。这些是浏览器内容区,不是显示器分辨率统计。
- 可切换切片/动作标注阶段;打开字典、搜索分页、切片分页、长描述和展开编辑、提交确认、小窗口恢复均可查看。
- 使用占位画面评审空间,不把占位示意当成真实视频可辨识性验收。
- 实测本地真实双视频均为 590×480,比例 59:48,原相机元数据为 1600×1300;本地仅定位到一组真实 Capture。另有 320×240 演示样本,不能算作客户素材覆盖。16:9 与 9:16 仅为示意适配案例。
- 该示意在最低内容区每路有效画面约 413×336,在 1920×980 内容区约 759×617;这里度量的是保持原比例后的有效画面,不含留白。
- **已接受的放大取舍**:单路放大时,临时将详细时间轴收成进度条,把高度让给视频;最低内容区的单路有效画面因此增至约 501×408,恢复双画面后还原详细时间轴。播放、当前编辑、保存/提交仍可见。只隐藏另一路而不腾出高度,当前素材不会实际放大,用户已接受这一临时模式。
- **视觉确认已完成**:用户接受最低尺寸下的视频面积、右侧编辑区宽度和按钮密度。规格以该示意为基准,将最低有效画面下限取整为双路各 400×325、单路放大 490×398(仅对 59:48 基准素材适用)。
### 示意验证范围
独立本地 Edge 无头实例检查五档内容区、两阶段、字典、三种比例、长文本、放大、确认弹层与小窗口恢复。27 个布局/状态检查通过,未见脚本异常,主要按钮未超出工作页边界,核心区域无内容溢出;截图已人工检查。
当时只验证示意,不代表正式工作台已通过浏览器验收。后续实施已采用真实浏览器操作、API 保存回读,并检查同步帧、草稿/撤销保留、原布局回退、视口变化和在途操作;当前结果见[整体验收报告](../../docs/verification/annotation-workspace-layout/acceptance-results.md)。
设计阶段的本地验证记录在未跟踪目录 `local-data/verification/annotation-workspace-layout/`。该阶段的原工作台及 5173 服务未修改;后续实现已修改产品工作台,验证期间仍只使用本地 5173/3001/27018。
未新增 ADR:已确认的布局选择可逆,且继续沿用共享编辑状态与原有业务契约,不新增难逆转架构取舍。

View File

@ -0,0 +1,169 @@
<div id="annotation-layout-preview" aria-label="人工标注工作页布局评审">
<style>
#annotation-layout-preview{--aw-bg:light-dark(#f5f6f8,#12151a);--aw-panel:light-dark(#ffffff,#1b2028);--aw-line:light-dark(#d6dce3,#39414d);--aw-text:light-dark(#17212f,#e6edf5);--aw-muted:light-dark(#526174,#abb8c8);--aw-accent:light-dark(#b54b0b,#ffad64);--aw-soft:light-dark(#fff0df,#42301f);font:14px/1.45 system-ui,sans-serif;color:var(--aw-text);width:100%}
#annotation-layout-preview *{box-sizing:border-box}
#annotation-layout-preview [hidden]{display:none!important}
#annotation-layout-preview button,#annotation-layout-preview select,#annotation-layout-preview input,#annotation-layout-preview textarea{font:inherit;color:inherit;border:1px solid var(--aw-line);background:var(--aw-panel);border-radius:6px;padding:6px 9px;min-width:0}
#annotation-layout-preview button{cursor:pointer;white-space:nowrap;min-height:32px}
#annotation-layout-preview button:hover{border-color:var(--aw-accent)}
#annotation-layout-preview button:disabled{opacity:.5;cursor:default}
#annotation-layout-preview .aw-primary,#annotation-layout-preview button[aria-pressed="true"]{background:var(--aw-soft);border-color:var(--aw-accent);color:var(--aw-accent)}
#annotation-layout-preview .aw-demo{display:flex;flex-wrap:wrap;gap:10px;align-items:center;margin-bottom:10px}
#annotation-layout-preview .aw-demo label{display:flex;align-items:center;gap:6px}
#annotation-layout-preview .aw-info{display:flex;flex-wrap:wrap;gap:6px 18px;margin:8px 0;color:var(--aw-muted)}
#annotation-layout-preview .aw-preview{position:relative;width:100%;overflow:hidden}
#annotation-layout-preview .aw-app{position:absolute;left:0;top:0;transform-origin:top left;display:grid;grid-template-rows:40px minmax(0,1fr) 44px;gap:8px;padding:8px;background:var(--aw-bg);border:1px solid var(--aw-line);overflow:hidden}
#annotation-layout-preview .aw-head,#annotation-layout-preview .aw-footer,#annotation-layout-preview .aw-player,#annotation-layout-preview .aw-camera-head,#annotation-layout-preview .aw-row{display:flex;align-items:center;gap:8px;min-width:0}
#annotation-layout-preview .aw-head{justify-content:space-between}
#annotation-layout-preview .aw-title{font-weight:500;font-size:18px}
#annotation-layout-preview .aw-muted{color:var(--aw-muted)}
#annotation-layout-preview .aw-tag{border-radius:4px;background:var(--aw-soft);color:var(--aw-accent);padding:3px 7px;white-space:nowrap}
#annotation-layout-preview .aw-body{display:grid;grid-template-columns:minmax(0,1fr) var(--aw-editor-width);gap:12px;min-height:0}
#annotation-layout-preview .aw-left{display:grid;grid-template-rows:minmax(0,1fr) 40px 104px;gap:8px;min-width:0;min-height:0}
#annotation-layout-preview .aw-left.aw-inspect{grid-template-rows:minmax(0,1fr) 40px 32px}
#annotation-layout-preview .aw-left.aw-inspect .aw-timeline{display:flex;align-items:center;padding:4px 10px}
#annotation-layout-preview .aw-left.aw-inspect .aw-timeline>:not(.aw-range){display:none}
#annotation-layout-preview .aw-videos{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px;min-height:0;min-width:0}
#annotation-layout-preview .aw-videos.aw-single{grid-template-columns:1fr}
#annotation-layout-preview .aw-camera{display:grid;grid-template-rows:24px minmax(0,1fr);min-width:0;min-height:0;background:var(--aw-panel);border:1px solid var(--aw-line);border-radius:8px;overflow:hidden}
#annotation-layout-preview .aw-camera-head{justify-content:space-between;padding:0 8px}
#annotation-layout-preview .aw-camera-head button{min-height:24px;padding:1px 7px;font-size:12px}
#annotation-layout-preview .aw-screen{min-height:0;display:flex;align-items:center;justify-content:center;overflow:hidden;background:light-dark(#e1e6eb,#080b0f)}
#annotation-layout-preview .aw-picture{display:flex;flex-direction:column;justify-content:center;align-items:center;gap:6px;border:1px solid var(--aw-line);background:repeating-linear-gradient(0deg,transparent,transparent 39px,var(--aw-line) 40px),repeating-linear-gradient(90deg,transparent,transparent 39px,var(--aw-line) 40px),var(--aw-panel);text-align:center;position:relative}
#annotation-layout-preview .aw-picture strong{font-size:22px;font-weight:500;background:var(--aw-panel);padding:5px 10px}
#annotation-layout-preview .aw-picture span{background:var(--aw-panel);padding:2px 6px}
#annotation-layout-preview .aw-player{background:var(--aw-panel);border:1px solid var(--aw-line);border-radius:6px;padding:4px 8px;justify-content:space-between}
#annotation-layout-preview .aw-timeline{display:grid;grid-template-rows:18px 26px 20px 16px;gap:3px;background:var(--aw-panel);border:1px solid var(--aw-line);border-radius:6px;padding:6px 10px;min-width:0}
#annotation-layout-preview .aw-scale{display:flex;justify-content:space-between;color:var(--aw-muted);font-size:12px}
#annotation-layout-preview .aw-track{display:flex;gap:3px;min-width:0;position:relative}
#annotation-layout-preview .aw-track button{flex:1;border-radius:3px;padding:2px 5px;min-height:26px}
#annotation-layout-preview .aw-track button:nth-child(3){flex:1.7}
#annotation-layout-preview .aw-range{width:100%;padding:0;border:0!important;accent-color:var(--aw-accent);background:transparent!important}
#annotation-layout-preview .aw-editor{display:grid;grid-template-rows:40px minmax(0,1fr) 114px 42px;gap:8px;padding:10px;background:var(--aw-panel);border:1px solid var(--aw-line);border-radius:8px;min-height:0;min-width:0}
#annotation-layout-preview .aw-editor-head{display:flex;align-items:center;justify-content:space-between;gap:4px}
#annotation-layout-preview .aw-edit-body{display:flex;flex-direction:column;gap:8px;min-height:0}
#annotation-layout-preview .aw-edit-body label{display:flex;flex-direction:column;gap:4px;min-height:0}
#annotation-layout-preview .aw-edit-body textarea{resize:none;flex:1;min-height:72px;width:100%;overflow-y:auto}
#annotation-layout-preview .aw-description{flex:1}
#annotation-layout-preview .aw-dictionary{display:grid;grid-template-rows:36px minmax(0,1fr) 32px;gap:8px;min-height:0;flex:1}
#annotation-layout-preview .aw-terms{display:grid;grid-template-rows:repeat(3,minmax(0,1fr));gap:5px;min-height:0}
#annotation-layout-preview .aw-terms button{white-space:normal;text-align:left;line-height:1.3;min-height:32px}
#annotation-layout-preview .aw-page{display:flex;align-items:center;justify-content:space-between;gap:6px}
#annotation-layout-preview .aw-slices{border-top:1px solid var(--aw-line);padding-top:8px;display:grid;grid-template-rows:24px 30px 30px;gap:5px}
#annotation-layout-preview .aw-slice-grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:5px}
#annotation-layout-preview .aw-slice-grid button{padding:2px;min-height:28px}
#annotation-layout-preview .aw-editor-actions{display:flex;gap:8px;align-items:center;justify-content:flex-end;border-top:1px solid var(--aw-line);padding-top:8px}
#annotation-layout-preview .aw-footer{justify-content:space-between;border-top:1px solid var(--aw-line);padding-top:8px}
#annotation-layout-preview .aw-shield{position:absolute;inset:0;background:color-mix(in srgb,var(--aw-bg) 95%,transparent);display:flex;align-items:center;justify-content:center;z-index:3;padding:24px}
#annotation-layout-preview .aw-modal{background:var(--aw-panel);border:1px solid var(--aw-line);border-radius:10px;padding:24px;max-width:480px;display:flex;flex-direction:column;gap:16px;box-shadow:0 16px 48px #0002}
#annotation-layout-preview .aw-modal strong{font-size:20px;font-weight:500}
#annotation-layout-preview .aw-small-note{display:none;padding:18px;background:var(--aw-panel);border:1px solid var(--aw-line);border-radius:8px}
@media(max-width:600px){#annotation-layout-preview .aw-preview{display:none}#annotation-layout-preview .aw-small-note{display:block}#annotation-layout-preview .aw-demo label{width:100%;justify-content:space-between}}
</style>
<div class="aw-demo" data-fallback-controls>
<label>内容区 <select data-viewport><option value="1280x640">1280 × 640 · 最低</option><option value="1366x680">1366 × 680</option><option value="1440x800">1440 × 800</option><option value="1920x980">1920 × 980</option><option value="2560x1320">2560 × 1320</option><option value="1100x600">1100 × 600 · 过小</option></select></label>
<label>演示阶段 <select data-phase><option value="annotate">动作标注</option><option value="slice">切片</option></select></label>
<label>素材比例 <select data-ratio><option value="590/480">约 1.23:1 · 当前实测</option><option value="16/9">16:9 · 适配示例</option><option value="9/16">9:16 · 适配示例</option></select></label>
</div>
<div class="aw-info" aria-live="polite"><span data-view-label></span><span data-size-label></span><span>布局示意 · 占位画面</span></div>
<div class="aw-small-note">请展开查看桌面布局。模拟内容区的最低尺寸为 1280 × 640。</div>
<div class="aw-preview">
<section class="aw-app" aria-label="标注工作页">
<header class="aw-head">
<div class="aw-row"><span class="aw-title">标注工作页</span><span class="aw-muted">示例项目 / 任务 014</span><span class="aw-tag" data-stage-label>动作标注</span></div>
<div class="aw-row"><button type="button" data-help>快捷键 ?</button><button type="button" data-legacy>原布局</button><button type="button" data-exit>返回任务池</button></div>
</header>
<div class="aw-body">
<div class="aw-left">
<div class="aw-videos">
<section class="aw-camera" data-camera="left"><div class="aw-camera-head"><span>左相机 · 同步</span><button type="button" data-focus="left">放大</button></div><div class="aw-screen"><div class="aw-picture"><strong>左相机</strong><span data-picture-size></span><span>完整画面 · 等比显示</span></div></div></section>
<section class="aw-camera" data-camera="right"><div class="aw-camera-head"><span>右相机 · 同步</span><button type="button" data-focus="right">放大</button></div><div class="aw-screen"><div class="aw-picture"><strong>右相机</strong><span data-picture-size></span><span>完整画面 · 等比显示</span></div></div></section>
</div>
<div class="aw-player"><div class="aw-row"><button type="button" data-play>播放 Space</button><button type="button" data-mark>开始动作 N</button><button type="button" data-replay>片头 B</button><button type="button" data-return>回工作位置 V</button></div><span data-position>00:18.400</span><div class="aw-row"><button type="button" data-step="-1">← 帧</button><button type="button" data-step="1">帧 →</button><span>1.0×</span></div></div>
<div class="aw-timeline"><div class="aw-row" style="justify-content:space-between"><span data-timeline-label>当前切片 · 动作时间轴</span><span class="aw-muted">18.400 — 31.200</span></div><div class="aw-track" aria-label="示例时间区间"><button type="button" data-segment="1">动作 1</button><button type="button" data-segment="2" aria-pressed="true">动作 2</button><button type="button" data-segment="3">未标注</button></div><input class="aw-range" type="range" min="0" max="60" step="0.04" value="18.4" aria-label="示例视频播放位置"><div class="aw-scale"><span>00:00</span><span>00:15</span><span>00:30</span><span>00:45</span><span>01:00</span></div></div>
</div>
<aside class="aw-editor" aria-label="固定编辑区">
<div class="aw-editor-head"><span data-editor-title>当前动作</span><button type="button" data-dictionary>描述字典 F</button></div>
<div class="aw-edit-body" data-edit-form><div class="aw-row"><span class="aw-tag" data-edit-state>区间已选定</span><span class="aw-muted">18.400 — 22.800</span></div><label data-name-label hidden>切片名称<input value="整理物品" readonly></label><label class="aw-description" data-description-label>动作描述<textarea aria-label="动作描述">左手扶住盒体,右手取出物品并放在桌面上。</textarea></label><div class="aw-row"><button type="button" data-long-text>长描述示例</button><button type="button" data-expand>展开编辑</button></div></div>
<div class="aw-dictionary" data-dictionary-panel hidden><input type="search" placeholder="搜索字典词条" aria-label="搜索字典词条"><div class="aw-terms"></div><div class="aw-page"><button type="button" data-term-page="-1">上一页</button><span data-term-page-label>1 / 2</span><button type="button" data-term-page="1">下一页</button></div></div>
<div class="aw-slices"><div class="aw-row" style="justify-content:space-between"><span data-slice-label>切片 03 / 24</span><span class="aw-muted">Ctrl + ← →</span></div><div class="aw-slice-grid"></div><div class="aw-page"><button type="button" data-slice-page="-1">上一页</button><span data-slice-page-label></span><button type="button" data-slice-page="1">下一页</button></div></div>
<div class="aw-editor-actions"><span class="aw-muted" data-save-label>未保存</span><button type="button" data-cancel>取消</button><button type="button" class="aw-primary" data-save>保存描述</button></div>
</aside>
</div>
<footer class="aw-footer"><div class="aw-row"><button type="button" data-undo>撤销</button><button type="button" data-redo>重做</button><span class="aw-muted" data-footer-note>草稿仅保留在当前会话</span></div><div class="aw-row"><span class="aw-tag" data-continuous-label>连续工作中</span><button type="button" data-stop>完成本条后停止</button><button type="button" class="aw-primary" data-submit>完成标注 · 提交质检</button></div></footer>
<div class="aw-shield" data-small-shield hidden><div class="aw-modal"><strong data-small-title>窗口空间不足</strong><span data-small-detail>请扩大到至少 1280 × 640。当前任务与编辑内容已保留,播放及自动接续已暂停。</span><button type="button" class="aw-primary" data-resume disabled>调整窗口后继续</button></div></div>
<div class="aw-shield" data-modal-shield hidden><div class="aw-modal" role="dialog" aria-modal="true" aria-label="布局演示弹层"><strong data-modal-title></strong><div data-modal-content></div><div class="aw-row" style="justify-content:flex-end"><button type="button" data-modal-close>返回编辑 Esc</button><button type="button" class="aw-primary" data-modal-confirm>确认</button></div></div></div>
</section>
</div>
<script>
(()=>{
const root=document.getElementById('annotation-layout-preview');
const one=s=>root.querySelector(s), all=s=>[...root.querySelectorAll(s)];
const state={viewport:'1280x640',phase:'annotate',ratio:'590/480',focus:'',dictionary:false,termPage:0,slice:3,slicePage:0,playing:false,pausedForSize:false,continuous:true,position:18.4,bookmark:18.4,saved:false,marking:false};
const terms=['取出物品并放置','双手整理桌面物品','打开包装盒','拿起并移动容器','检查物品外观','其他动作'];
let scale=1,modalAction=null,undoText=null;
function openModal(title,content,action){one('[data-modal-title]').textContent=title;one('[data-modal-content]').replaceChildren(content);modalAction=action;one('[data-modal-confirm]').hidden=!action;one('[data-modal-shield]').hidden=false;one('[data-modal-close]').focus();}
function closeModal(){one('[data-modal-shield]').hidden=true;modalAction=null;one('[data-play]').focus();}
const textNode=t=>document.createTextNode(t);
function measure(){
const [w,h]=state.viewport.split('x').map(Number);const frame=one('.aw-preview');const app=one('.aw-app');
scale=Math.min(1,(frame.clientWidth||1024)/w);app.style.width=w+'px';app.style.height=h+'px';app.style.transform=`scale(${scale})`;frame.style.height=Math.ceil(h*scale)+'px';
app.style.setProperty('--aw-editor-width',(w<1440?304:w<1920?328:360)+'px');
const [rw,rh]=state.ratio.split('/').map(Number);let sizes=[];
all('.aw-camera:not([hidden])').forEach(camera=>{const screen=camera.querySelector('.aw-screen'),pic=camera.querySelector('.aw-picture');const sw=screen.clientWidth,sh=screen.clientHeight;const pw=Math.max(0,Math.min(sw,sh*rw/rh)),ph=pw*rh/rw;pic.style.width=pw+'px';pic.style.height=ph+'px';const size=`${Math.floor(pw)} × ${Math.floor(ph)}`;camera.querySelector('[data-picture-size]').textContent=size+' 有效画面';sizes.push(size);});
one('[data-view-label]').textContent=`内容区 ${w} × ${h} · 缩览 ${Math.round(scale*100)}%`;
one('[data-size-label]').textContent=(state.focus?'放大画面:':'每路有效画面:')+(sizes[0]||'—')+' CSS px';
}
function render(){
const [w,h]=state.viewport.split('x').map(Number),small=w<1280||h<640;if(small){state.pausedForSize=true;state.playing=false;}
one('[data-small-shield]').hidden=!state.pausedForSize;
one('[data-small-title]').textContent=small?'窗口空间不足':'空间已恢复,准备继续';
one('[data-small-detail]').textContent=small?'请扩大到至少 1280 × 640。任务、草稿和撤销保留;播放及自动接续已暂停。':'点击继续恢复操作及此前的连续工作设置;视频保持暂停,按空格继续播放。';
one('[data-resume]').disabled=small;one('[data-resume]').textContent=small?'调整窗口后继续':'继续工作';
const slice=state.phase==='slice';
one('[data-stage-label]').textContent=slice?'切片':'动作标注';one('[data-editor-title]').textContent=state.dictionary?(slice?'切片名称字典':'描述字典'):(slice?'当前切片':'当前动作');
one('[data-dictionary]').textContent=state.dictionary?'返回编辑 Esc':(slice?'切片字典 F':'描述字典 F');
one('[data-edit-form]').hidden=state.dictionary;one('[data-dictionary-panel]').hidden=!state.dictionary;
one('[data-name-label]').hidden=!slice;one('[data-description-label]').hidden=slice;one('[data-long-text]').hidden=slice;one('[data-expand]').hidden=slice;
one('[data-edit-state]').textContent=slice?'切点已确定':'区间已选定';one('[data-save]').textContent=slice?'确认名称':'保存描述';
one('[data-submit]').textContent=slice?'确认全部切片':'完成标注 · 提交质检';one('[data-timeline-label]').textContent=slice?'源采集 · 切片时间轴':'当前切片 · 动作时间轴';
one('[data-mark]').textContent=slice?'切分 C':state.marking?'结束动作 N':'开始动作 N';
all('[data-segment]').forEach((b,i)=>b.textContent=slice?`切片 ${i+1}`:i===2?'未标注':`动作 ${i+1}`);
one('.aw-videos').classList.toggle('aw-single',!!state.focus);one('.aw-left').classList.toggle('aw-inspect',!!state.focus);all('[data-camera]').forEach(c=>c.hidden=!!state.focus&&c.dataset.camera!==state.focus);all('[data-focus]').forEach(b=>b.textContent=state.focus?'恢复双画面':'放大');
one('[data-play]').textContent=state.playing?'暂停 Space':'播放 Space';
const sec=state.position;one('[data-position]').textContent=`00:${sec.toFixed(3).padStart(6,'0')}`;one('.aw-range').value=String(sec);
one('[data-save-label]').textContent=state.saved?'已保存(演示)':'未保存';
one('[data-continuous-label]').textContent=state.continuous?'连续工作中':'本条完成后停止';one('[data-stop]').textContent=state.continuous?'完成本条后停止':'开启连续工作';
one('[data-slice-label]').textContent=`切片 ${String(state.slice).padStart(2,'0')} / 24`;one('[data-slice-page-label]').textContent=`${state.slicePage+1} / 6`;
one('.aw-slice-grid').replaceChildren(...Array.from({length:4},(_,i)=>{const n=state.slicePage*4+i+1,b=document.createElement('button');b.type='button';b.textContent=String(n).padStart(2,'0');b.setAttribute('aria-pressed',String(n===state.slice));b.onclick=()=>{state.slice=n;state.playing=false;render();};return b;}));
const filter=one('[aria-label="搜索字典词条"]').value.trim(),matched=terms.filter(t=>t.includes(filter));const pageCount=Math.max(1,Math.ceil(matched.length/3));state.termPage=Math.min(state.termPage,pageCount-1);
one('.aw-terms').replaceChildren(...matched.slice(state.termPage*3,state.termPage*3+3).map(t=>{const b=document.createElement('button');b.type='button';b.textContent=t;b.onclick=()=>{undoText=one('textarea').value;if(slice)one('[data-name-label] input').value=t;else one('textarea').value=t;state.saved=false;state.dictionary=false;render();};return b;}));
one('[data-term-page-label]').textContent=`${state.termPage+1} / ${pageCount}`;all('[data-term-page]').forEach(b=>b.disabled=+b.dataset.termPage<0?state.termPage===0:state.termPage>=pageCount-1);
all('[data-slice-page]').forEach(b=>b.disabled=+b.dataset.slicePage<0?state.slicePage===0:state.slicePage===5);
one('[data-viewport]').value=state.viewport;one('[data-phase]').value=state.phase;one('[data-ratio]').value=state.ratio;
measure();
}
one('[data-viewport]').onchange=e=>{state.viewport=e.target.value;render();};one('[data-phase]').onchange=e=>{state.phase=e.target.value;state.dictionary=false;render();};one('[data-ratio]').onchange=e=>{state.ratio=e.target.value;render();};
all('[data-focus]').forEach(b=>b.onclick=()=>{state.focus=state.focus?'':b.dataset.focus;render();});
one('[data-dictionary]').onclick=()=>{state.dictionary=!state.dictionary;render();};one('[aria-label="搜索字典词条"]').oninput=()=>{state.termPage=0;render();};
all('[data-term-page]').forEach(b=>b.onclick=()=>{state.termPage+=+b.dataset.termPage;render();});all('[data-slice-page]').forEach(b=>b.onclick=()=>{state.slicePage+=+b.dataset.slicePage;render();});
one('[data-play]').onclick=()=>{state.playing=!state.playing;render();};one('[data-replay]').onclick=()=>{state.bookmark=state.position;state.position=18.4;state.playing=true;render();};one('[data-return]').onclick=()=>{state.position=state.bookmark;state.playing=false;render();};
one('[data-mark]').onclick=()=>{state.marking=!state.marking;state.playing=false;render();one('[data-edit-state]').textContent=state.phase==='slice'?'已在当前帧切分(演示)':state.marking?'动作起点已记录':'区间已选定';};
all('[data-step]').forEach(b=>b.onclick=()=>{state.position=Math.min(60,Math.max(0,state.position+.04*+b.dataset.step));state.playing=false;render();});one('.aw-range').oninput=e=>{state.position=+e.target.value;render();};
all('[data-segment]').forEach(b=>b.onclick=()=>{all('[data-segment]').forEach(x=>x.setAttribute('aria-pressed',String(x===b)));});
one('textarea').oninput=()=>{state.saved=false;one('[data-save-label]').textContent='未保存';};
one('[data-save]').onclick=()=>{state.saved=true;state.dictionary=false;render();};one('[data-cancel]').onclick=()=>{state.dictionary=false;render();};
one('[data-long-text]').onclick=()=>{undoText=one('textarea').value;one('textarea').value=('左手扶住盒体,右手取出物品并放在桌面上。观察物品方向后,再用双手整理并检查。\n').repeat(12);state.saved=false;render();};
one('[data-undo]').onclick=()=>{if(undoText!==null){const current=one('textarea').value;one('textarea').value=undoText;undoText=current;state.saved=false;render();}};one('[data-redo]').onclick=()=>one('[data-undo]').click();
one('[data-expand]').onclick=()=>{const area=document.createElement('textarea');area.value=one('textarea').value;area.rows=10;area.setAttribute('aria-label','展开编辑描述');openModal('动作描述',area,()=>{undoText=one('textarea').value;one('textarea').value=area.value;state.saved=false;closeModal();render();});};
one('[data-stop]').onclick=()=>{state.continuous=!state.continuous;render();};one('[data-resume]').onclick=()=>{state.pausedForSize=false;render();};
one('[data-submit]').onclick=()=>{state.playing=false;openModal(state.phase==='slice'?'确认生成切片':'确认提交质检',textNode(state.phase==='slice'?'24 个切片将进入生成阶段。此处仅演示确认界面的空间。':'当前任务提交后,需等待审核数据准备完成,才会继续下一条。此处不会实际提交。'),()=>{closeModal();one('[data-footer-note]').textContent='确认完成(演示,无数据写入)';});render();};
one('[data-help]').onclick=()=>openModal('快捷键',textNode('Space 播放 · C 切片 · N 动作区间 · F 字典 · B 片头 · V 回工作位置 · Ctrl/⌘+Enter 保存或提交 · Ctrl/⌘+Z 撤销'),null);
one('[data-legacy]').onclick=()=>openModal('切回原布局',textNode('正式功能会保留任务、播放位置、草稿和撤销记录。本示意只评审新布局,不复制原工作台。'),null);
one('[data-exit]').onclick=()=>openModal('返回任务池',textNode('当前示意未连接业务数据。正式工作页继续使用已有的未保存内容离开保护。'),null);
one('[data-modal-close]').onclick=closeModal;one('[data-modal-confirm]').onclick=()=>modalAction?.();root.addEventListener('keydown',e=>{if(e.key==='Escape'){if(!one('[data-modal-shield]').hidden){e.preventDefault();closeModal();}else if(state.dictionary){state.dictionary=false;render();}}});
render();new ResizeObserver(measure).observe(one('.aw-preview'));
if(globalThis.Tweak){one('[data-fallback-controls]').hidden=true;const tweak=new Tweak({container:root,onChange:render});tweak.addSelect(state,'viewport',{label:'浏览器内容区',options:[{label:'1280 × 640 · 最低',value:'1280x640'},{label:'1366 × 680',value:'1366x680'},{label:'1440 × 800',value:'1440x800'},{label:'1920 × 980',value:'1920x980'},{label:'2560 × 1320',value:'2560x1320'},{label:'1100 × 600 · 过小',value:'1100x600'}]});tweak.addSelect(state,'phase',{label:'演示阶段',options:[{label:'切片',value:'slice'},{label:'动作标注',value:'annotate'}]});tweak.addSelect(state,'ratio',{label:'视频比例',options:[{label:'约 1.23:1 · 当前实测',value:'590/480'},{label:'16:9 · 适配示例',value:'16/9'},{label:'9:16 · 适配示例',value:'9/16'}]});}
})();
</script>
</div>

View File

@ -0,0 +1,158 @@
# 人工标注专注工作页布局规格
Status: resolved
设计确认:2026-09-18,四轮边界确认及交互示意均已接受。本文记录已确认的范围;实施票 01–08 已完成并独立审查,整体验收、说明书及最终双轴审核均已交付;覆盖限制与维护建议见[最终报告](../../docs/verification/annotation-workspace-layout/final-review.md)。
## Problem Statement
现有工作页已经支持选择项目后连续处理切片与动作标注,但仍沿用较多任务管理页面和旧编辑区的空间安排。描述阶段双视频高度受限,编辑区、保存按钮或切片操作可能需要滚动才能找到,切片与描述阶段的空间分配也不一致。
标注员必须持续观看同步双视频。常用控制应一直可见,切换阶段、查字典、处理长文本不能不断挤压画面或移动操作位置。改造还必须保留已经验证的快捷键、草稿、撤销和连续任务逻辑,并能回到当前原布局。
## Solution
沿用同标签页独立工作页,进入时收起平台导航,充分利用浏览器内容区。左侧并排显示两路等大视频,其下固定播放控制和时间轴;右侧固定切片命名或动作描述编辑区。切片与标注采用同一空间骨架,保存、阶段提交、返回和停止连续工作保持可达。
完整工作布局最低支持 1280×640 CSS 像素的浏览器内容区。页面不整体滚动;切片、描述和字典等长列表通过分页、搜索或键盘导航访问。长文本允许输入框内部滚动和展开编辑,保存与取消按钮始终固定。
默认显示完整、等比、同步的双画面。用户可主动临时放大一路,此时把详细时间轴收成进度条,将腾出的高度用于视频;恢复双画面后还原详细时间轴。首版自动分配空间,不提供拖拽分栏。
提供运行中切回原布局的入口,按当前账号和浏览器记住选择。布局切换保留当前任务、播放位置、未保存草稿和撤销记录,继续共用已验证的编辑与快捷键逻辑。
## User Stories
1. As an annotator, I want to enter a dedicated work page in the current tab, so that I can use the available screen for annotation.
2. As an annotator, I want platform navigation hidden during focused work, so that it does not reduce video space.
3. As an annotator, I want both camera views visible by default, so that I can compare synchronized observations.
4. As an annotator, I want each video shown at its original aspect ratio without cropping, so that scene edges remain visible.
5. As an annotator, I want video area to grow on larger windows, so that a large monitor improves viewing comfort.
6. As an annotator, I want an explicit minimum usable viewport, so that I know when the window is too small for reliable work.
7. As an annotator, I want slicing and description editing to keep the same layout, so that I do not search for controls after changing stages.
8. As an annotator, I want playback, frame stepping and current-stage marking controls always visible, so that I can work without scrolling.
9. As an annotator, I want the timeline below the videos, so that I can relate the current frame to its interval.
10. As an annotator, I want my current editing area visible beside the videos, so that I can describe what I am watching.
11. As an annotator, I want dictionaries to replace content within the fixed editing area, so that opening them does not displace the videos.
12. As an annotator, I want dictionary search, paging and keyboard selection, so that long dictionaries remain usable without scrolling for controls.
13. As an annotator, I want slice and description lists accessible through paging or keyboard navigation, so that large tasks do not grow the page.
14. As an annotator, I want selection to reveal its containing list page, so that keyboard navigation and undo keep the relevant item visible.
15. As an annotator, I want long descriptions editable within a bounded text area or expanded editor, so that text length does not push save actions off screen.
16. As an annotator, I want save, cancel and stage submission actions kept visible, so that I can complete an edit without hunting for buttons.
17. As an annotator, I want help and infrequent actions available on demand, so that they remain accessible without taking permanent video space.
18. As an annotator, I want to enlarge either camera temporarily, so that I can inspect details.
19. As an annotator, I want the detailed timeline compressed during single-camera inspection, so that the effective picture actually grows.
20. As an annotator, I want one action to restore the dual-camera layout, so that I can resume normal annotation at the same position.
21. As an annotator, I want viewport changes to preserve my task and edits, so that resizing does not lose work.
22. As an annotator, I want playback and automatic task continuation paused below the minimum viewport, so that work does not advance while controls are unavailable.
23. As an annotator, I want to explicitly resume after restoring the window, so that resizing alone does not restart work.
24. As an annotator, I want in-flight operations reconciled while the page is paused, so that a successful save or claim is not repeated.
25. As an annotator, I want to switch to the original layout during work, so that I have a usable fallback.
26. As an annotator, I want layout switching to preserve drafts, selection, playback position and undo history, so that fallback is not a task restart.
27. As an annotator, I want my layout preference remembered for my account in this browser, so that the next entry uses my chosen view.
28. As an annotator, I want the established shortcuts and focus rules to behave consistently in both layouts, so that I do not relearn annotation.
29. As an annotator, I want continuous claiming and submission recovery unchanged, so that a visual redesign does not alter task ownership.
30. As a maintainer, I want a verified source-code recovery point for the prior workbench, so that I can recover it if the redesign fails.
## Implementation Decisions
### Scope and responsibilities
- Apply the new presentation to the existing dedicated annotation work page. Keep the original task-pool/workbench entry available.
- The work-page shell owns available viewport, compact navigation and layout preference. The existing editing coordinator retains task ownership, requests, versions, stage transitions, drafts and history. Media playback and precise-frame mapping remain in the existing media/editing flow.
- New and original layouts share one editing implementation. A layout change is a presentation change; it must not create a new editing session, remount away its state, reconnect media unnecessarily or acquire another task.
- No new backend service, schema, claiming endpoint or server-side layout preference is required. Layout preference is scoped to the current account and browser; an account without a preference enters the new work-page layout. The original task-pool entry retains its original presentation.
- Do not change customer/domain contracts for frame coverage, semantic blanks, invalid intervals, discarded slices, permissions, explicit saving or ownership. The existing undo stage boundary remains authoritative.
### Stable space allocation
- In normal dual-camera mode, reserve left-side video space, playback/marking controls and detailed timeline; reserve a right-side editor with its save/cancel controls. Keep task state and the stop/submit/return entry points in fixed visible areas.
- Switch only the editing content when changing from slicing to action descriptions. Do not move the video, timeline, editor or submission areas to different sides of the page.
- Hide platform navigation in the focused work page while keeping an explicit return path. Compact processing and error messages must not introduce page scrolling or cover the primary actions. Long explanations may open an accessible detail panel.
- Allocate sizes automatically; no drag handles or stored custom split ratios in this release.
- Primary buttons must remain discoverable with visible labels or accessible, clearly explained controls. Shortcuts complement visible actions rather than replace them.
### Viewport and effective picture size
- Measure the browser's usable content area in CSS pixels. Physical display resolution alone does not establish support: browser chrome, OS scaling, browser zoom and a resized window affect the result.
- The full new layout requires width ≥1280 and height ≥640. Verify the boundary itself as well as larger content areas. Support applies to the new layout; the retained original layout preserves its existing scrolling behavior.
- Default to two equally allocated, synchronized camera views, preserving each source aspect ratio with no cropping. A layout breakpoint must not automatically hide a camera.
- Use the real 590×480 test pair (59:48) as the principal size baseline. At 1280×640, each effective picture must remain at least 400×325 CSS pixels; the accepted preview provides approximately 413×336. This rounded implementation floor preserves the accepted visual size without requiring identical decorative spacing.
- In temporary single-camera mode at the same viewport, the baseline picture must visibly grow to at least 490×398; the preview provides approximately 501×408. At larger sizes, use available space rather than keeping the previous 240px video-height ceiling.
- These dimensions refer to the image itself after aspect fitting, excluding letterbox space. They do not impose the same width on portrait media. Other ratios must remain complete and undistorted; 16:9 and 9:16 are adaptation cases, not evidence of actual customer-material coverage.
- Single-camera mode temporarily compresses the detailed timeline into a progress bar. Playback, marking, frame inspection, current editing, save and submit remain available. Restore the detailed timeline when returning to dual-camera mode without changing the current frame, task or draft.
### Lists, dictionaries and text
- The new work page must not require horizontal or vertical document scrolling to reach an operation.
- Use bounded list areas with paging/search and keyboard access. A selected slice or description reached through navigation, undo or redo must reveal its containing page. Preserve the chronological order and existing slice navigation semantics.
- Dictionaries switch into the fixed editing area. Keep search, paging, selection and return controls visible. Retain existing keyboard selection and one-Esc focus return; choosing a description template does not implicitly save it.
- Long descriptions may scroll inside the text field and use an expanded editor. Keep save/cancel outside the scrolling content. Returning from expanded editing preserves the text and the existing explicit-save contract.
- Help, discard reasons and other infrequent content may open on demand. Keep the existing two-step submission confirmation and keyboard behavior. Large summaries must not push confirmation controls outside the viewport.
### Undersized windows and in-flight work
- If the new layout becomes narrower than 1280 or shorter than 640, pause playback and suspend automatic continuation; retain the current task, selection, frame, drafts and history.
- Show an explicit resize/zoom-adjustment prompt. Do not automatically jump to the original layout or silently shrink controls below the accepted layout.
- Already dispatched save, generation, submission or claim requests remain subject to authoritative reconciliation. A resize does not cancel their server-side effects, invent a failure, discard a successful response or issue a replacement claim.
- If submission completes while undersized, keep the result and defer the next claim until explicit continuation. If a claim was already dispatched, reconcile and retain its result; do not claim again merely because the page was resized.
- Growing the window alone does not resume work. A user action restores editing and the prior continuous-work setting; video remains paused until explicitly played. A prior stop-after-current choice remains effective. Permission errors, unknown results and session conflicts continue to block inappropriate continuation.
### Original-layout fallback and recovery
- Keep an always reachable layout-switch entry. Switching retains the task, stage, current selection and frame, per-slice drafts, unsaved text, undo/redo and continuous-work intent. It is not a refresh, leave action or ownership change.
- Retain existing pending-operation restrictions and request/session guards during a switch. A delayed response must update the same authorized task and cannot reappear as a stale edit in a different task.
- Remember layout choice per account and browser; do not reuse a different account's preference. Reload still follows the original explicit task-resume rules and does not acquire work solely because a preference exists.
- Runtime fallback preserves the original layout's behavior. It is separate from the verified Git tag and bundle, which recover the entire source version and do not restore databases, downloaded media or unsaved browser state.
### Existing workflow preserved
- Start Work continues an owned unfinished task before random claiming. Random claiming remains within the selected project and supplier permissions, with no pre-claim video selection.
- Continue after authoritative completion of audit-data preparation and quality handoff, not after a `processing` response and not after a quality reviewer approves the task.
- Preserve stop-after-current, empty-pool handling, unknown-result retry with the same request identifier, refresh recovery, page-session exclusivity and leave protection.
- Retain current key bindings, IME/text-input ownership, one-Esc return, explicit draft save, per-stage undo limits and one-second undo/redo throttling.
## Testing Decisions
The main boundary is real browser interaction with the work page and existing API save/readback, following the previously accepted test strategy. Test visible outcomes and persistence, not component names, internal state variables or source-text strings.
The existing annotation browser fixtures and authoritative API recovery scenarios provide prior art. Add layout measurements to the browser checks; geometry checks alone cannot prove draft preservation, video synchronization or correct task ownership.
| ID | Scenario | Required observation |
| --- | --- | --- |
| L01 | Enter and leave the dedicated page | Navigation space is reclaimed; return path and original entry work without changing ownership. |
| L02 | Both stages at five supported viewport sizes | 1280×640, 1366×680, 1440×800, 1920×980 and 2560×1320 keep primary controls inside the viewport; no document scroll is needed. |
| L03 | Zoom and real desktop windows | Check representative 1366×768, 1440×900, 1920×1080 and 2560×1440 display/window settings with 100%, 125% and 150% browser zoom; record actual content dimensions and apply the normal or undersized behavior accordingly. |
| L04 | Real double-camera video | Effective picture size meets the accepted baseline; views remain synchronized, complete and undistorted. |
| L05 | Alternative ratios | Synthetic 16:9, 9:16 and differing left/right ratios remain contained without changing frame-to-time mapping; label these synthetic cases. |
| L06 | Single-camera inspection and return | Either camera grows, detailed timeline compresses/restores, frame and drafts remain; playback and editor actions remain reachable. |
| L07 | Dictionary and keyboard focus | Search, page, select, edit and one-Esc return work without moving video regions or implicitly saving a draft. |
| L08 | Many slices/descriptions | Use lists larger than one page; selection, Ctrl/⌘+arrows, undo and redo reveal the affected item and retain chronological navigation. |
| L09 | Long text and long names | Text may scroll internally; save/cancel and confirmations remain visible; Chinese input composition and native text undo continue to work. |
| L10 | Toggle new/original layout while editing | Task, frame, slice, draft text and undo/redo survive multiple switches; verify persisted edits by API readback. |
| L11 | Toggle with delayed responses | No duplicate write/claim or stale task overwrite; pending restrictions remain effective. |
| L12 | Resize below the boundary during playback/editing | Playback and auto-continuation pause; edits remain; enlarging alone does not resume. |
| L13 | Resize during save/generation/submission/claim | Reconcile the original operation; do not repeat a claim; defer new continuation until explicit resume. |
| L14 | Preference and refresh | Same-account preference survives re-entry, other-account preference does not leak; task recovery remains explicit. |
| L15 | Complete a continuous-work cycle | Slice, generate, describe, save, submit, reconcile and continue using the existing project/ownership contracts. Stop and empty-pool behavior remain correct. |
| L16 | Original-layout regression | Original task entry, shortcuts and common editing actions retain behavior; the new layout's no-scroll contract is not imposed on the original view. |
Use local isolated tasks on the existing 5173/3001/27018 verification stack. Company cluster or BOS writes are not part of this specification. Supplement browser checks with existing API conflict/idempotency coverage only where this change affects that behavior; do not create a new test-only backend or duplicate all prior suites.
The preview passed 27 local layout/state checks and screenshot inspection. That validates the design artifact only. Implementation acceptance evidence is now collected in the per-task reports and the final acceptance report; preview checks remain design-only evidence.
## Out of Scope
- New random-task allocation, reviewer workflow or server-side undo systems.
- New windows/popups as the main work surface, or a second independent annotation editor.
- User-draggable panels, arbitrary layout presets or server-synchronized display settings.
- Making the entire growing list/dictionary simultaneously visible, or forbidding text-field scrolling.
- Full new-layout operation below 1280×640, mobile annotation, or imposing the new layout on quality/acceptance reviewers.
- Restoring unsaved browser drafts or undo across refresh, rolling back business data via a Git backup, deployment, merge or push.
## Further Notes
- Accepted interaction preview: [preview.html](./preview.html). Decision history, source observations and recovery instructions: [map.md](./map.md).
- Existing behavior specification: [annotation keyboard workflow](../annotation-keyboard-workflow/spec.md). Undo boundary: [ADR-0001](../../docs/adr/0001-annotation-undo-stage-boundary.md).
- Recovery baseline: commit `54a35afad95d77b1f23c955f9c4671cae83a664d`, local annotated tag `codex/annotation-keyboard-baseline-20260918`, verified complete bundle under the ignored local backup directory. This is the version already published in PR #1, before the new layout discussion.
- The current implementation reuses existing browser session coordination. Its secure-context deployment requirement remains in force; the preview does not verify company-cluster HTTPS or deployment readiness.
- Client source documents were not directly accessible in the prior audit. This specification reflects the user's explicit decisions and available repository contracts, not a claimed rereading of inaccessible client originals.

View File

@ -0,0 +1,201 @@
# 专注标注工作页:已发布任务拆分
日期:2026-09-18。
依据:[已确认规格](./spec.md)、[已接受布局示意](./preview.html)。书面规格已由用户确认。用户已确认本文件中的任务边界、依赖和验收标准,并授权发布。8 份独立实施票已发布,见[任务索引](./README.md);尚未启动实现。
## 拆分原则
- 每项交付一个可演示的用户行为,包含必要的呈现、状态衔接、浏览器操作和 API 回读验证。
- 局部整理放在相应任务的功能修改之前;不安排纯重构、纯 CSS、纯后端或把全部测试推迟到最后的横向任务。
- 每项均遵守父规格、原快捷键规则及 ADR-0001。复制第二套编辑器、刷新重置状态、重新领任务,均不能作为布局切换的实现方式。
- 每项完成其对应行为验证后才算完成;第 08 项负责组合验收、分辨率/缩放矩阵和交付文档,不能代替前七项自己的测试。
- 基线 Git 标签与完整 bundle 已建立并验证。本轮不将“再做一遍备份”列成独立实施票。
## 任务与依赖
| 编号 | 任务 | 直接前置 | 独立可演示结果 |
| --- | --- | --- | --- |
| 01 | 专注工作视图与原布局无损切换 | 无 | 进入工作页收起平台导航;切回原布局时保留任务、播放位置、草稿和撤销,并记住账号偏好。 |
| 02 | 切片阶段在一屏内完成操作 | 01 | 双视频、切片时间轴、命名与确认控制固定可见;最低视口可完成切片和生成。 |
| 03 | 动作标注阶段固定编辑与保存 | 02 | 生成后沿用同一骨架,完成动作区间、描述保存、撤销与送检,不滚动找按钮。 |
| 04 | 大量切片和描述的分页定位 | 03 | 大列表不撑高页面;键盘换片、选择、撤销/重做都会展示受影响条目所在页。 |
| 05 | 固定区域内的字典和长文本编辑 | 03 | 两类字典搜索分页、一次 Esc 返回、长描述展开及固定保存按钮可完整使用。 |
| 06 | 单路放大与视频比例适配 | 03 | 主动放大任一路时画面确实增大,压缩/恢复时间轴,保持同步帧和编辑内容。 |
| 07 | 小窗口暂停与在途结果协调 | 01 | 窗口过小时暂停播放和新接续,但正确处理已发出的保存/提交/领取;恢复后显式继续。 |
| 08 | 连续工作整体验收与操作手册 | 04、05、06、07 | 全分辨率/缩放与完整工作链路验收,验证旧版回退,交付证据和通俗说明书。 |
仅将真实前提列为依赖:02 先建立供两阶段共用的布局结构,03 再用它完成动作编辑;04/05/06 使用完成的两阶段结构。07 只需要 01 的专注视图边界和现有工作会话,并不等待新视频布局。共享大组件带来的编辑冲突由执行顺序协调,不人为添加业务依赖。
## 01:专注工作视图与原布局无损切换
**交付行为:** 在当前标签页进入专注工作视图、收起平台导航并保留返回路径;用户可以在工作中切回原布局而不丢失编辑状态,重新进入时沿用当前账号的浏览器偏好。
**Blocked by:** None (can start immediately)
**覆盖:** 用户故事 1、2、25、26、27、28、29、30;场景 L01、L10、L11、L14、L16。
- [ ] 先隔离呈现选择与已有编辑会话,保持既有播放器、请求归属、草稿和历史的生命周期;用原布局现有行为作基线验证后,再接入视图切换。
- [ ] 开始工作使用已有项目和领取链路;专注视图收起平台导航,返回任务池仍有原有未保存离开保护,原任务池入口保持可用。
- [ ] 无偏好账号默认新工作视图;布局偏好仅影响当前账号和浏览器,不跨账号串用。刷新依旧需要显式恢复任务,不能因读取偏好而自动领任务。
- [ ] 新旧视图反复切换保留当前任务/阶段/选中项/播放帧、不同切片草稿、文本与撤销/重做;切换不提交、释放或重新领取任务。
- [ ] 保存请求延迟返回时切换布局,原结果仍正确回读;不重复写入,不清空草稿,不绕过处理中限制或会话归属检查。
- [ ] 切换入口在常规编辑状态始终可达;确认可回到真实原布局,而非复制出的近似界面。
- [ ] 浏览器编辑及 API 回读证明状态保留;原快捷键、原任务入口和原布局常用编辑路径通过相关回归。
- [ ] 核对既有恢复标签仍指向原基线,文档中区分源码恢复与业务数据恢复。
**本票边界:** 新视图先完成专注外壳和无损切换,不以此宣称两阶段新布局、免滚轮和画面尺寸全部交付;这些由 02/03 及长内容任务完成。
## 02:切片阶段在一屏内完成操作
**交付行为:** 在新视图的切片阶段,用固定可见的双视频、播放/逐帧/切分控制、时间轴、命名区域和确认操作完成切片,再等待真实生成结果。
**Blocked by:** 01:专注工作视图与原布局无损切换
**覆盖:** 用户故事 3、4、5、6、7、8、9、16、17、28;场景 L02、L04、L16,以及切片阶段的 L03/L15。
- [ ] 先为现有视频、时间轴和编辑操作建立共用呈现区域,保持业务回调与媒体节点稳定,再实现左侧双视频、下方控制/时间轴、右侧命名和固定提交区。
- [ ] 在 1280×640 内容区,590×480 基准双视频各自的有效画面不小于 400×325;完整等比显示,无自动隐藏。更大内容区继续扩大可用视频面积。
- [ ] 两路视频、Space、C、逐帧、B/V、切片名称、撤销/重做、确认和返回/停止入口在正常短列表任务中可见,不依赖文档滚动。
- [ ] C 切分后保留切点,原播放、精确帧定位、切片覆盖和字典命名契约继续成立。
- [ ] 阶段状态、错误和处理提示不把主要按钮挤出视口;需要较长解释时从固定入口展开。
- [ ] 确认仍走原两步确认及真实异步生成;收到 processing 不能提前进入已完成状态。通过 API 回读确认切片结果。
- [ ] 新样式限定在新布局;切回原布局后仍符合 01 的状态保留要求。
- [ ] 用五档支持的内容区进行本阶段几何与操作检查,完成类型/构建及受影响行为测试。
**本票边界:** 使用现有字典入口保持可用;固定编辑区字典由 05 完成,大列表由 04 完成,不借本票改写字典或领取规则。
## 03:动作标注阶段固定编辑与保存
**交付行为:** 切片生成后在相同的空间骨架中填写动作描述、保存、撤销并送检;视频、编辑区和主要按钮不换位置。
**Blocked by:** 02:切片阶段在一屏内完成操作
**覆盖:** 用户故事 7、8、9、10、16、17、28、29;场景 L02、L09、L10、L15、L16。
- [ ] 复用切片阶段已建立的呈现区域,将动作编辑接入右侧固定区,避免条件渲染重建播放器或丢失当前编辑会话。
- [ ] 从切片到描述阶段只变更相关编辑内容;视频/时间轴/编辑/提交区保持相同方位,两阶段均满足基准画面尺寸。
- [ ] N 开始、N/Enter 结束、输入文本、保存/取消及阶段提交可从固定区域完成;保留当前快捷键、焦点和中文输入法规则。
- [ ] 保存按原版本/归属校验写入服务端;失败保留内容,撤销/重做已保存描述后用 API 回读确认,不以浏览器画面替代真实结果。
- [ ] 跨片草稿、未完成草稿的提交拦截和 Ctrl/⌘+Enter 的保存/提交优先级保持一致。
- [ ] 正常任务的帮助、舍弃原因、提交确认和失败提示可由固定入口访问,确认按钮不超出视口;低频内容按需展开。
- [ ] 确认送检仍等待审核数据准备完成;只在真实送检后按原规则接续,不等待质检员判定,也不把 processing 当完成。
- [ ] 在五档支持内容区完成本阶段操作检查,并在有草稿/已保存历史时切回原布局验证状态。
## 04:大量切片和描述的分页定位
**交付行为:** 切片和描述数量超过一屏时,列表仍保持在有限空间内;鼠标与键盘导航、撤销/重做使当前项自动出现在正确页。
**Blocked by:** 03:动作标注阶段固定编辑与保存
**覆盖:** 用户故事 13、14、28;场景 L08、L10,补充大数据量下的 L02/L16。
- [ ] 切片和动作描述列表使用有界区域,页码及前后页控制保持可见;提供适合现有列表的搜索/定位入口,不靠文档滚动或无限增加高度。
- [ ] 保持真实时间顺序;过滤或分页不改变数据,也不把 Ctrl/⌘+左右的原相邻切片语义改成只在可见页内循环。
- [ ] 跨页选中、键盘换片、B/V 复查及撤销/重做后,受影响条目所在页可见;不能出现操作成功但目标被过滤隐藏而无提示。
- [ ] 新增、删除或合并导致总页数变化时,页码保持有效;选中关系遵守现有编辑规则,不引用已删除对象。
- [ ] 页面导航不自动保存草稿;切片间保留草稿,返回仍可编辑。切换原布局后内容和撤销历史保持一致。
- [ ] 用切片和描述均超过一页的隔离任务进行浏览器操作,覆盖跨页撤销、删除后尾页变空和 API 保存回读。
## 05:固定区域内的字典和长文本编辑
**交付行为:** 切片名称字典和动作描述字典在固定编辑区内搜索、翻页、选择;长描述可局部滚动或展开编辑,保存/取消一直可见。
**Blocked by:** 03:动作标注阶段固定编辑与保存
**覆盖:** 用户故事 11、12、15、16、17、28;场景 L07、L09、L10,以及相关 L02/L16。
- [ ] 先保留现有字典选择与输入契约,将同一能力接入固定编辑区;不另建与旧工作台行为不一致的字典实现。
- [ ] 两类字典都支持搜索与分页,搜索框、翻页和返回入口保持可见;打开字典不改变视频位置或挤走播放控制。
- [ ] F/D、方向键、Enter 与一次 Esc 保留已有语义;选描述模板后可继续编辑,不能自动保存。关闭后 Space 不重新激活字典按钮。
- [ ] 长文本只在输入内容区内部滚动,提供展开编辑;保存/取消固定在滚动区外。展开与收起不触发业务保存或丢失输入。
- [ ] 中文输入法组合、文本框剪切/原生撤销、工作台撤销分别按已有键盘归属处理。
- [ ] 长词条、长描述和长提交摘要不把确认按钮挤出屏幕;必要内容可完整阅读,操作无需寻找滚轮下方按钮。
- [ ] 用多页字典与长文本在最低内容区演示选择、编辑、保存、一次 Esc 返回和布局切换,并以 API 回读验证真实保存。
## 06:单路放大与视频比例适配
**交付行为:** 任一路视频可主动临时放大以检查细节;详细时间轴随之收成进度条,恢复双画面后原操作状态不变,不同视频比例仍完整显示。
**Blocked by:** 03:动作标注阶段固定编辑与保存
**覆盖:** 用户故事 3、4、5、18、19、20、28;场景 L04、L05、L06、L10。
- [ ] 切片与描述两阶段默认双画面等大且同步;窄窗口不自动隐藏某一路。
- [ ] 用户主动放大左路或右路时,将详细时间轴临时压缩为进度条,真实增加画面高度,而非只隐藏另一路。
- [ ] 在 1280×640、59:48 基准素材下,单路有效画面至少 490×398;正常双画面仍符合每路 400×325 下限。度量实际图像而非容器留白。
- [ ] 放大期间播放、逐帧、当前阶段标记、编辑、保存和提交仍可用;恢复双画面同时恢复详细时间轴。
- [ ] 保留播放帧、同步关系、草稿、选中项和历史;不通过清空媒体源或重建编辑会话来切换。
- [ ] 用真实约 1.23:1 双视频及明确标注的 16:9、9:16、左右不同比例合成样例验证等比完整显示,避免把演示数据宣称为客户素材覆盖。
- [ ] 放大/恢复后验证时间轴鼠标定位与键盘逐帧仍对应正确原始帧,不能因显示尺寸变化改变时间映射。
## 07:小窗口暂停与在途结果协调
**交付行为:** 新工作页空间低于最低要求时安全暂停,当前内容保留;已经发出的请求仍正确核对,恢复空间后由用户主动继续。
**Blocked by:** 01:专注工作视图与原布局无损切换
**覆盖:** 用户故事 6、21、22、23、24、29;场景 L03、L12、L13,补充 L11/L15。
- [ ] 先将因视口不足而暂挂的状态与现有连续工作意图区分开,再将其接入原会话的播放和接续边界;不得把暂停当成释放任务或丢弃会话。
- [ ] 新布局的有效内容区宽度小于 1280 或高度小于 640 即暂停播放与新的自动接续,并明确提示调整窗口/缩放;精确边界值正常可用。
- [ ] 当前任务、选中片、播放帧、跨片草稿及撤销保留;不自动切旧布局、不默默挤小按钮。该限制不改变旧布局的既有行为。
- [ ] 窗口恢复尺寸本身不续播或领任务。显式继续后恢复操作和此前连续工作设置,视频仍需主动播放;此前的完成本条后停止选择保持有效。
- [ ] 已发出的保存、生成和送检请求继续依据原请求与版本核对;送检在暂停期间成功后只记录结果,等待显式继续才触发下一次接续。
- [ ] 已发出的随机领取即使在暂停期间成功也保留该任务;结果未知时沿用同一请求号核对,不因缩放或重试再领一条。
- [ ] 权限错误、结果未知、会话冲突和处理限制不会因“继续”按钮被绕过;旧/新布局切换同样保留在途请求归属。
- [ ] 用真实浏览器缩放/调整窗口和可控延迟或断开响应验证播放、保存、生成、送检与领取边界,并通过 API 回读任务与版本。
## 08:连续工作整体验收与操作手册
**交付行为:** 在新界面完成真实连续作业,并可可靠切回旧界面;形成覆盖所有规格的结果报告和标注人员能直接使用的操作说明。
**Blocked by:** 04:大量切片和描述的分页定位;05:固定区域内的字典和长文本编辑;06:单路放大与视频比例适配;07:小窗口暂停与在途结果协调
**覆盖:** 全部 30 条用户故事、L01–L16;本票负责组合验收和交付,不代替各前置任务自身的验收。
- [ ] 完成开始工作→已有任务优先/随机领取→切片→真实生成→描述→保存→送检→下一条的浏览器/API 闭环,验证停止、空池及未知结果恢复。
- [ ] 五档支持内容区覆盖两阶段、字典、长列表、长文本、单路放大、错误与确认弹层;主要操作无文档横向/纵向滚动即可完成。
- [ ] 代表性 1366×768、1440×900、1920×1080、2560×1440 显示/窗口设置下核对 100%、125%、150% 浏览器缩放,记录真实 CSS 内容区,按是否达到底线验证正常或暂停行为。确实无法覆盖的设备/系统缩放组合必须注明限制,不能用模拟视口冒充全部物理设备实测。
- [ ] 交叉验证草稿/撤销/在途请求情况下的新旧布局切换、刷新显式恢复、账号偏好隔离和单活动页规则。
- [ ] 原任务池入口、原布局及既有快捷键回归通过;检查新布局样式没有意外作用于质检/验收工作台。
- [ ] 完成适用的类型检查、构建与行为测试;既有失败与新增回归分开报告,前置票未通过的验收不能被最终报告掩盖。
- [ ] 交付说明书覆盖进入/退出、字典与长内容、临时放大、切回旧版、小窗口恢复、保存与提交、停止接续;明确“送检成功”不同于“质检通过”。
- [ ] 交付恢复说明和验证报告:确认代码标签/bundle可恢复,区分代码与数据库/视频/浏览器草稿;不进行公司集群部署或额外推送。
## 覆盖核对
| 用户故事 | 主要负责票 |
| --- | --- |
| 1、2、25、26、27、30 | 01 |
| 3、4、5 | 02、06 |
| 6 | 02、07 |
| 7、8、9 | 02、03 |
| 10 | 03 |
| 11、12、15 | 05 |
| 13、14 | 04 |
| 16、17 | 02、03、05 |
| 18、19、20 | 06 |
| 21、22、23、24 | 07 |
| 28 | 01–06,各自负责对应操作 |
| 29 | 01、03、07,08 组合验证 |
| 验收场景 | 主要负责票 |
| --- | --- |
| L01、L10、L11、L14、L16 | 01,后续票补充其新增行为,08 组合回归 |
| L02 | 02、03;04/05/06 补充其长内容/放大状态,08 全矩阵 |
| L03 | 07 实现正常/暂停边界,08 完成缩放矩阵 |
| L04、L05、L06 | 02 基线双视频,06 完成放大与比例适配 |
| L07、L09 | 05;03 负责普通动作编辑及提交确认 |
| L08 | 04 |
| L12、L13 | 07 |
| L15 | 03/07 保持阶段与接续契约,08 完整连续作业 |
## 执行与发布边界
- 初始可执行票仅 01。01 完成后,02 和 07 分别满足其前置;02 完成后可做 03;03 完成后 04/05/06 均就绪;所有末端票完成后进行 08。
- 为减少共享编辑器冲突,单线执行可直接按 01→02→03→04→05→06→07→08;这只是调度顺序,不额外添加阻塞边。
- 执行时每票使用新鲜上下文,读取父规格与其直接依赖的交付结果;独立审查该票行为和验证证据后再认定完成。此处不创建或派遣实现 agent。
- 验证使用本地 5173/3001/27018 隔离任务;凭据和原始证据保存在未跟踪本地目录,交付文档不记录秘密。
- 已按本地 issue tracker 约定发布为 8 份独立文件,每票包含交付、Blocked by、`Status: ready-for-agent`、验收和约束;依赖未完成的票即使定义就绪也不能领取执行。
- 本轮不修改父规格,不关闭父事项,也不推送远端。拆分及发布均已获用户确认,发布本身不等于启动产品实现。

View File

@ -1,5 +1,10 @@
# Project Instructions
## Working Root
- This repository directory is the single working root; the sibling `~/Desktop/fanyu` folder is legacy and will be retired.
- Cluster kubeconfig (`fanyu.conf`), BOS credential CSV, downloaded captures, and the local workspace mount are being migrated under this repo's untracked local data path (see `docs/HANDOFF.md` § 0 for the live layout).
## Deployment Environment
- The `dev` branch uses the `poc` deployment and test environment.
@ -9,8 +14,33 @@
## Git Workflow
- Before assuming a remote target, run `git remote -v`.
- There is no Gitea upstream unless a Gitea remote is explicitly configured.
- After making code or documentation changes for the user, stage only the files changed for that task.
- Commit automatically with an English, emoji-prefixed commit message.
- Push the current branch after a successful commit.
- Commit with an English, emoji-prefixed commit message.
- **Push only when the user explicitly says push.** Default action after commit: stay local.
- When push is approved, push the user's personal feature branch only; never push `dev` or `poc` directly.
- Do not stage or commit unrelated user changes already present in the working tree.
## Credentials
- Never hardcode credentials (BOS AK/SK, Mongo, Gitea token, cluster kubeconfig) in any tracked file.
- Read secrets from untracked local files or environment variables; see `scripts/local/` for the established pattern.
## Local Environment
- Local replica stack (Vite 5173, Go API 3001, snapshot Mongo 27018) is the default verification surface before any PR.
- Verification commands and known pitfalls (upstream test debt, session auth flag, workspace mount) are documented in `docs/HANDOFF.md`.
- The company cluster and BOS bucket are read-only by default; any write requires explicit user approval.
## Agent skills
### Issue tracker
Issues and specs use local Markdown under `.scratch/`. Before reading or publishing tickets, read `docs/agents/issue-tracker.md`.
### Triage labels
Use the five default triage roles. Before triaging issues, read `docs/agents/triage-labels.md`.
### Domain docs
Use a single-context layout: root `CONTEXT.md` and `docs/adr/`. Before exploring domain concepts or decisions, read `docs/agents/domain.md`.

40
CONTEXT.md Normal file
View File

@ -0,0 +1,40 @@
# Droboticflow 领域术语
以下词汇描述人工标注与审核中的业务对象。
## 标注对象
**Capture(源采集)**:一次源采集所关联的双目视频、时间戳与传感器数据,是本流程组织人工处理和审核的对象。
**切片**:标注员在源采集的统一有效帧范围内划定的连续区间。全部切片完整覆盖该范围,互不重叠;一个切片可以包含多条动作描述。
_Avoid_:动作描述区间(两者不是同一层级)
**动作描述区间**:属于一个切片、具有起止边界和描述内容的语义区间。已有描述互不重叠,可以在切片中留下空白。
_Avoid_:切片(描述边界不等于切片边界)
## 留空与交付
**语义留空**:保留切片内未填写动作描述的时间范围,可以覆盖部分或全部切片。留空仍参与审核和媒体交付,不自动代表无效或舍弃。
**无效区间**:标注员明确标记为无效的动作描述区间。它表达语义判断,不等于从交付范围中舍弃切片。
**舍弃切片**:标注员明确选择不交付、并记录原因的切片。切片及其证据仍参与审核,舍弃本身不移动相邻边界。
## 操作含义
**删除切片**:移除一个切片划分并将其范围并入相邻切片,保持源采集的处理覆盖。
**删除动作描述**:移除一条语义描述并保留原时间范围的空白,不合并相邻动作,也不删除视频。
**切片字典**:项目启用的切片名称集合;新确认的切片名称从中选择,多个切片可以同名。
**描述字典**:用于填写动作描述草稿的模板集合;选择后允许编辑描述文本。
## 连续作业
**送检**:标注结果及其审核数据已经准备完成,任务交给质检环节等待处理。送检成功不代表质检通过。
_Avoid_:质检完成(属于后续审核结果)
**连续工作**:标注员在所选项目内连续完成任务的工作方式;当前任务送检后先续做本人尚未完成的任务,没有时再随机领取下一条。
**随机领取**:在操作者有权限的项目和供应商范围内,从可领取的标注任务中随机分配任务;操作者在领取前不能挑选视频。它不包含主动释放已领取任务。

141
docs/HANDOFF.md Normal file
View File

@ -0,0 +1,141 @@
# 项目交接手册(给接班的 AI 平台 / 新开发者)
> 项目根目录:`/Users/d-robotics/Desktop/fanyu/droboticflow`(下文所有相对路径均基于此)
> 本文档由 ZCode 维护,描述本地复刻环境的全部操作:如何测试、如何更新 5173 前端、如何跟进同事代码。
> 上一次全面核对:2026-09-17。
## 0. 一分钟速览(当前环境在跑什么)
| 服务 | 地址 | 是什么 | 怎么起的 |
|---|---|---|---|
| 前端 Vite | http://127.0.0.1:5173 | React 开发服务器(**源码实时生效,不是构建产物**) | `npx vite --port 5173 --strictPort` |
| Go API | http://127.0.0.1:3001 | 后端 REST API(`/api`),由 Vite 代理转发 | `source scripts/local/env-local-snapshot.sh && npm run dev:api` |
| 快照库 Mongo | 127.0.0.1:27018 | **公司 8/31 全库备份的本地副本**(57 集合真实业务数据) | docker 容器 `fanyu-mongo-restore`(mongo:8) |
| 空库 Mongo | 127.0.0.1:27017 | 手工构造数据用的空库 | docker 容器 `fanyu-mongo`(mongo:7) |
- 浏览器访问 http://127.0.0.1:5173 即是完整平台;数据库用快照库(27018)。
- 登录账号(使用本地自行设置的密码;密码不写入仓库,设置方法见 `docs/annotation-local-deployment.zh-CN.md` 第三步):
- 标注员 `fanyu-full-annotator@droboticflow.local`
- 质检员 `fanyu-full-qc@droboticflow.local`、验收员 `fanyu-full-acceptance@droboticflow.local`、管理员 `fanyu-admin@droboticflow.local`
- **红线**:27018/27017 都是本地容器,随便写;公司集群(kubeconfig `local-data/fanyu.conf`)和 BOS 桶默认只读,任何写操作需用户明确确认。
## 1. 前端(5173)怎么改、怎么验证
**改动即生效**:Vite dev server 直连 `src/` 源码,保存文件浏览器自动热更(HMR)。没有"重新构建前端"这一步。
```
页面源码定位规律:
浏览器 URL 路径 → src/App.tsx 里搜对应 <Route> → 路由指向的组件文件
例:/plugins/annotation-qa/.../annotate → src/pages/AnnotationOperations.tsx(页面主体)
+ src/components/CaptureAnnotationWorkbench.tsx(工作台)
快捷键定义:src/lib/annotation-shortcuts.js
前端↔后端接口封装:src/services/api/*.ts
```
**改前必跑的检查**(顺序固定):
```bash
cd /Users/d-robotics/Desktop/fanyu/droboticflow
npm run lint:web # tsc 类型检查,改 ts/tsx 后必跑
npm run test:frontend # 98 个 node 内置 runner 测试(无需浏览器),约 1 分钟
```
**针对性测试**:`node --test tests/frontend/annotation-shortcuts.test.mjs`(换你改的模块对应的测试文件;`ls tests/frontend/ | grep <关键词>` 找)。
**注意**:`vite.config.ts` 里 `DISABLE_HMR=true` 注释说明是给 AI 编辑防闪烁用的——正常人工开发不受影响;如果平台自动改文件导致页面闪烁,以 `DISABLE_HMR=true npx vite ...` 启动。
## 2. API(3001)怎么改、怎么验证
```bash
# 启动(终端 1)——必须先 source 环境变量,Go 进程不读 .env 文件
source scripts/local/env-local-snapshot.sh && npm run dev:api
# 改完 Go 代码后 Ctrl+C 重启(go run 无热更)
# 验证
curl -s http://127.0.0.1:3001/api/health # 应 200 {"status":"ok"}
curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001/api/auth/me # 应 401(匿名)
go build ./... # 编译检查
go test ./internal/api/ -run 'Test<名称>' -count=1 # 针对性测试
```
**已知坑**:
- `env-local-snapshot.sh` 里 `DROBOTICFLOW_REQUIRE_SESSION_AUTH=true` 是关键——不设它匿名会回落成默认管理员、登录面板不显示(与线上行为不一致);
- API 启动会自动对快照库执行 RunMigrations + EnsureIndexes(幂等,正常);
- 全量 `go test ./...` 有约 63 个**上游遗留失败**(旧测试测已删除的接口,405/404),不是回归信号;判断标准是"你改动前后失败数不增加"。
## 3. 如何看同事的代码 / 如何更新(rebase 流程)
同事(Gitea 唯一作者 eust-w / longtao.wu)高频提交,工作模式:**客户需求 → 消化成 docs/ 契约文档 + 代码 + 测试同一提交**。
```bash
# 1. 拉取并查看新提交
git fetch origin dev
git log --oneline HEAD..origin/dev # 看新增了哪些提交
git log --diff-filter=A --name-only --format='--- %h %s' origin/dev -- 'docs/*.md' | head -30
# ↑ 需求雷达:同事新增的 docs/*.md 就是"消化后的客户需求",必读
# 2. 合入本地分支(用户的工作分支是 feature/local-dev-toolkit,全部是本地工具提交)
git rebase origin/dev # 历史上零冲突(本地提交全是新增文件,不碰上游)
# 3. 验证更新后的代码
npm run lint:web && go build ./...
go test ./internal/api/ -run 'TestContinuous|TestAnnotation|TestDelivery' -count=1 # 他新功能相关
# 全量 go test 失败数与更新前对比,不增加即可
# 4. 重启服务生效(两个终端都要重启)
kill $(lsof -nP -iTCP:3001 -sTCP:LISTEN -t) 2>/dev/null
source scripts/local/env-local-snapshot.sh && npm run dev:api &
kill $(lsof -nP -iTCP:5173 -sTCP:LISTEN -t) 2>/dev/null; npx vite --port 5173 --strictPort &
# 5. 浏览器 Cmd+Shift+R 硬刷新
```
**读同事代码的入手顺序**(按信息密度排序):
1. `git show <hash> --stat` 看改动面 → 2. 提交信息(他用 gitmoji:📝新行为 🩹修补 🛡️防御 🗂️结构 🚀发布)→ 3. 同提交新增的 `docs/*.md` 契约文档(**最权威**,四段式:行为/保存与审核/打包与兼容/验证)→ 4. 最后才读代码,配套 `*_test.go` 读预期行为。
## 4. 真实数据链路(标注工作台看真视频的机制)
历史背景:快照库里的任务 artifact 原本指向 `bos://`(线上已清理)。本地接线方案:
- **原理**:API 的 `serveResolvedRunArtifactContent` 对本地路径 artifact 直接磁盘流式播放(含 Range);`safeMaterializationSourcePath` 只接受 `WORKSPACE_MOUNT_PATH` 挂载根下的文件(**安全设计,不能绕过**);"统一帧范围"接口从 `nodeExecutions[].inputBindings` 端口找 PTS——所以接线必须**双路改**(artifacts 数组 + inputBindings)。
- `env-local-snapshot.sh` 已导出 `WORKSPACE_MOUNT_PATH=~/Desktop/fanyu/droboticflow/local-data/workspace`,API 启动自动生效。
- 操作脚本:`scripts/local/download-capture.sh`(从 BOS 下载 Capture,已获同事放行)→ `scripts/local/wire-local-capture.sh <Capture名> <runId>`(接线+任务归属标注员)。
- **新任务没视频/帧范围加载失败的排查定式**:任务属于一个还没接线的 run → 跑 wire 脚本指定该 runId → 页面重试。已接线:`run-c1321...`、`run-f919a129...`(快照内 22 条标注任务全部覆盖)。
## 5. 本地工具箱索引(scripts/local/,全是纯新增文件)
| 脚本 | 用途 |
|---|---|
| `env-local.sh` / `env-local-snapshot.sh` | 空库/快照库环境变量(后者含 SESSION_AUTH 与 WORKSPACE_MOUNT_PATH,**日常用后者**) |
| `run-operator.sh <slug>` | 单算子直跑(worker 同款调用方式,秒级调试) |
| `download-capture.sh` / `wire-local-capture.sh` | 真实数据下载与接线 |
| `fetch-mongo-snapshot.sh` | 从集群 PVC 分块拉全库备份并恢复到 27018;本地和远端使用独立临时目录,完整 SHA-256 校验通过后才替换本地容器;成功保留的快照路径由脚本输出 |
配套文档:`docs/local-dev-guide.zh-CN.md`(环境搭建与踩坑)、`docs/annotation-local-deployment.zh-CN.md`(标注模块部署+测试用例 T1-T12)、`docs/release-checklist.zh-CN.md`(发布三道闸门+回滚)。
## 6. 网络/工具链备忘(公司网络特有,新人必读)
- Go 代理必须 `goproxy.cn`(已 `go env -w` 持久化);pip 用阿里镜像;Docker Hub 直连不通,走 `docker.m.daocloud.io` 镜像再 retag;
- colima 以 `--vm-type vz --vz-rosetta` 启动(QEMU 交叉编译会段错误);VM 内 DNS 失效时 `colima ssh` 修 `/etc/resolv.conf`(公司 DNS 202.4.130.100/101);
- BOS SDK 走 Python 时证书链失败(公司代理证书),代码里用 `ssl._create_unverified_context` 绕过;curl 不受影响;
- 本机代理 `127.0.0.1:7890`(容器内经 colima 网关 `192.168.5.2:7890`),镜像构建的 apt/pip 超时用它。
## 7. PR 与发布通道(已开通)
- Gitea 账号 `zhanghongming`(2026-09-17 开通,仓库协作者,push 已验证);remote 已带凭证(token 在 remote URL 中,若失效在 Gitea Settings→Applications 重新生成并 `git remote set-url` 更新);
- 工作流:本地 feature 分支提交 → `git push origin feature/<名字>` → Gitea 网页发 PR 到 dev → 同事审核合并。**不要直接 push dev**;
- 当前进行中的 PR:https://gitea.d-robotics.cc/longtao.wu/droboticflow/pulls/1(本地工具箱 8 个提交);
- 同事已放行:下载 Capture 调试、直接改代码提交 PR 由他审核;
- 发布(用户执行、同事确认后):只改前端/API 时仅需重建 `droboticflow-api` 一个镜像(前端打进 API 镜像),流程见 `docs/release-checklist.zh-CN.md`;
- 提交风格跟同事(gitmoji + 清晰信息 + 配套文档/测试),PR 通过率高。
## 8. 接班平台快查表
| 用户说 | 你做 |
|---|---|
| "页面有 bug" | 定位组件(§1 规律)→ 读代码 → 复现(浏览器/curl)→ 改 → lint+test → 让用户硬刷新 |
| "拉同事最新代码" | §3 流程五步 |
| "视频/帧范围加载失败" | §4 排查定式 |
| "测某个算子" | `scripts/local/run-operator.sh <slug>` |
| "改好了要发布" | 先 PR(§7);发布按 release-checklist |
| "测试报错了" | 先分辨是否上游测试债(§2 已知坑),再定位 |

View File

@ -0,0 +1,5 @@
# 标注撤销以当前任务的编辑阶段为边界
标注员需要撤销误切、误删以及已经保存的描述,但切片生成和送检会触发异步产物发布、当前版本替换及审核阶段流转。撤销因此限于当前任务、当前编辑阶段;已保存内容通过受当前版本与归属校验保护的写入恢复,开始生成、重新切片、送检或切换任务截断历史,避免把普通编辑撤销扩大为媒体版本恢复或审核流程回滚。
这一取舍保留了日常纠错能力,同时要求服务端写入成功后才宣告撤销成功;首版撤销历史仅保留在当前页面会话,刷新后从后端已保存内容恢复,不恢复撤销栈。用户于 2026-09-17 的两轮设计确认中接受此边界;详细交互与验收见 [标注键盘工作流设计](../../.scratch/annotation-keyboard-workflow/spec.md)。

27
docs/agents/domain.md Normal file
View File

@ -0,0 +1,27 @@
# Domain Docs
## Layout and reading rules
This repository uses a single-context layout:
- `CONTEXT.md` at the repository root: domain vocabulary.
- `docs/adr/`: architecture decision records.
Before exploring the codebase, read `CONTEXT.md` and ADRs relevant
to the area being explored.
If these files are absent, proceed silently. The `domain-modeling`
skill creates them lazily as terms or decisions are resolved.
## Vocabulary
Use the terms defined in `CONTEXT.md` when naming domain concepts
in issues, proposals, hypotheses, and tests.
If a needed concept is missing, check whether existing vocabulary
covers it; otherwise note the gap for `domain-modeling`.
## Decision conflicts
If a proposal contradicts an existing ADR, identify the ADR and
explain why the decision should be reconsidered.

View File

@ -0,0 +1,35 @@
# Issue tracker: Local Markdown
Issues and specs live as Markdown files in `.scratch/`.
## Conventions
- One feature per directory: `.scratch/<feature-slug>/`.
- Spec: `.scratch/<feature-slug>/spec.md`.
- One file per implementation ticket:
`.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`.
- Record triage state as a `Status:` line near the top.
Use the role strings in `triage-labels.md`.
- Append discussion under `## Comments`.
## Publish and fetch
When a skill says "publish to the issue tracker", create the appropriate
file under `.scratch/<feature-slug>/`, creating directories as needed.
When a skill says "fetch the relevant ticket", read the referenced file.
## Wayfinding operations
- Map: `.scratch/<effort>/map.md`, with Notes, Decisions-so-far, and Fog.
- Child ticket: `.scratch/<effort>/issues/NN-<slug>.md`.
- Record ticket type with `Type: research`, `prototype`, `grilling`, or `task`.
- Record dependencies with `Blocked by: NN, NN`.
- A ticket is unblocked when every listed dependency is resolved.
- Select open, unblocked, unclaimed tickets in numeric order.
- Claim a ticket by saving `Status: claimed` before starting work.
- Resolve it by appending `## Answer`, setting `Status: resolved`,
and adding a summary and link to the map's Decisions-so-far section.
The `claimed` and `resolved` statuses describe wayfinding execution;
they are separate from the five triage roles.

View File

@ -0,0 +1,13 @@
# Triage Labels
For local Markdown issues, record the tracker value in the `Status:` line.
| Canonical role | Tracker value | Meaning |
| --- | --- | --- |
| needs-triage | needs-triage | Maintainer needs to evaluate |
| needs-info | needs-info | Waiting on reporter information |
| ready-for-agent | ready-for-agent | Fully specified; ready for an autonomous agent |
| ready-for-human | ready-for-human | Requires human implementation |
| wontfix | wontfix | Will not be actioned |
When a skill mentions a triage role, use its tracker value above.

View File

@ -0,0 +1,101 @@
# 标注工作台操作说明
适用对象:切片与动作描述标注员。对应本次标注键盘工作流与连续工作模式。
## 一条任务怎么做
1. 在标注中心选择项目,点击“开始工作”。页面在当前标签页切换到“标注工作页”;有尚未完成的任务时先继续它。
2. 看视频,按 `C` 在当前帧切片。视频会暂停在切点;按空格继续往后看。
3. 给切片选择字典名称。确认划分后,按 `Ctrl/⌘+Enter` 打开生成确认,再单独按一次 `Enter` 执行。等待生成完成。
4. 进入动作描述阶段,按 `N` 标记起点,继续观看,在终点再次按 `N`(或 `Enter`)。
5. 按 `F` 选描述字典,或按 `Enter` 开始手工输入。字典模板可以修改。按 `Ctrl/⌘+Enter` 保存这一条描述。
6. 检查完所有切片后,处理完全部草稿,再按 `Ctrl/⌘+Enter` 打开送检确认,单独按 `Enter` 确认。
7. 连续工作开启时,只有当前任务确实送检成功,才会领取下一条。需要休息时选“完成当前任务后停止”。
Windows/Linux 下使用 Ctrl;macOS 下常用组合键可使用 ⌘。批量无效使用 Ctrl+X。
## 页面上最重要的几个入口
“开始工作”进入当前项目的工作页。“返回任务池”退出工作视图;有未保存修改时会先提醒,选择“继续编辑”或按 Esc 就能留下。
切片阶段的“确认全部切片”和描述阶段的“完成任务并提交质检”都会先打开摘要确认。看到“处理中”时耐心等待;“审核数据已生成,任务已提交质检”才表示该任务完成。
如果显示“结果尚未确认”,当前内容仍保留。先点“核对阶段结果”检查服务器结果,再按照提示继续;不要因为没有收到响应就把任务当作已完成。
## 常用按键
| 按键 | 作用 |
| --- | --- |
| 空格 | 播放/暂停。切片阶段可以跨片播放;描述阶段限当前片 |
| 左 / 右 | 按原始帧前后移动,倍速不改变一步的帧数 |
| C | 切片阶段在当前帧切分;描述阶段保留已有动作分割用途 |
| Ctrl/⌘ + 左 / 右 | 前一个 / 后一个切片,到片头暂停;首尾不循环 |
| B | 从选中切片片头播放,片尾停止 |
| V | 回到这轮复查前的工作位置并暂停 |
| N,再 N 或 Enter | 标记动作区间起点和终点 |
| F(兼容 D) | 打开当前所需的名称或描述字典 |
| 字典内上下 / Enter / Esc | 选择 / 确定 / 关闭 |
| 描述编辑区 Enter | 进入文字输入 |
| Esc | 回到工作台,保留未保存草稿 |
| Ctrl/⌘ + Enter | 优先保存当前描述;没有任何草稿时打开阶段提交确认 |
| Ctrl/⌘ + Z | 撤销最近编辑 |
| Ctrl/⌘ + Shift + Z | 重做 |
| Shift + Delete | 删除明确选中的切片或动作描述 |
| Mac:Shift + Backspace | 同上 |
| Ctrl + X | 将当前切片所有未标注空白一次标为无效 |
如果焦点还停留在按钮上,可以先按 Esc 回工作区,再使用工作台组合键。
在输入框中,空格、F、剪切和撤销继续编辑文字,不控制视频或切片。中文输入法选词期间不会执行工作台快捷键。
## 想回看片段,又不想丢失进度
先用 Ctrl/⌘+方向键选片,再按 B 完整复查。第一次离开当前片或按 B 时会记录工作点。可以连续复查多片;V 会回到最初离开时的位置。若切片被拆分或删除,返回按时间定位到当前有效切片。
不同切片的未保存动作草稿会分别保留,换片不会自动保存。回到原切片可继续编辑。提交前必须逐一保存或取消所有草稿。
## 切错、写错、删错怎么办
Ctrl/⌘+Z 可连续撤销,Ctrl/⌘+Shift+Z 可重做。最多保留最近 100 步,每秒最多响应一次,长按不连续执行。一次完整拖动或一次批量无效算一步;单纯播放、换片和逐帧不算编辑。撤销后开始新的编辑(包括改文字或换字典模板),旧的重做分支就会取消,避免覆盖新草稿。
已保存的描述撤销也要保存到服务器。遇到网络失败或版本冲突时,按页面提示核对恢复状态;未确认成功前不要把恢复当作完成。
撤销只作用于当前任务的当前编辑阶段。生成切片、重新切片、送检、换任务和刷新都会结束原来的撤销历史。刷新只恢复服务器已经保存的内容。
## 删除、留空、无效、舍弃有什么区别
- **删除切片**:去掉一个分界,把该片范围合入相邻片,视频覆盖仍完整。
- **删除描述**:去掉一条动作描述,原区间变为空白,不删除视频。
- **留空**:可以不写描述;视频仍参与审核和交付。
- **无效**:明确记录“这段无效”,与留空不同。
- **舍弃**:表达不交付这个切片,保留审核证据。要改它的边界,先显式恢复。
Ctrl+X 只填当前片的空白,不改变已有描述;一次撤销可撤回这一整批标无效。
## 提交与连续工作
Ctrl/⌘+Enter 有三种结果:当前有草稿就保存它;其他片还有草稿就先处理;全部没有草稿才打开生成或送检确认。缺少终点或描述时会提示修正,不会悄悄提交任务。
打开确认后,松开按键,再按一次 Enter 才执行;Esc 取消。“处理中”表示后台仍在工作,请等最终结果。
刷新或重新打开工作页后,先在“继续已领取任务”中选择任务,再点“继续工作”;这次只恢复当前任务,不会默默领取新任务。想继续自动接下一条,点“开始连续工作”或“恢复连续工作”。如果上次领取的结果还不确定,使用“核对领取结果并开始连续工作”;页面会先找回同一次领取的结果,再继续。同一浏览器的同一账号与项目只有一个活动工作页。第二页显示“返回活动工作页”,请回原标签处理。原页面退出或关闭后,再到另一页点“继续工作”。
遇到空池、网络不确定、后台失败或权限变化,连续工作会暂停。按页面提供的恢复入口处理;不确定的领取重试会沿用同一次请求,避免多领一条。“完成当前任务后停止”不会释放已经领取的任务。
## 快速排查
| 看到的情况 | 怎么处理 |
| --- | --- |
| 快捷键没有控制视频 | 先退出文字输入或字典,按一次 Esc 回工作区;弹窗内按提示操作 |
| 提交时提示其他切片还有草稿 | 点击提示中的切片,保存或取消那里的草稿,再提交 |
| 显示“处理中” | 等待完成;此时不重复保存、撤销或领取 |
| 显示领取结果不确定 | 点击“核对领取结果并开始连续工作”,不要另开页面反复领取 |
| 显示没有可领取任务 | 连续工作已暂停,稍后显式恢复 |
| 第二个页面不能继续 | 回到原活动页;原页正常退出或关闭后,再在这里继续 |
| 刷新后撤销没有效果 | 刷新不保留撤销历史,只恢复已保存数据 |
停止连续工作不等于放弃任务:已经领取的任务仍然归你,之后可以继续。
### 专注工作页字典翻页
切片名称和动作描述字典共用自适应分页:窗口越高,每页可见条目越多,上一页/下一页、页码和总数位于搜索框下方,无需滚动寻找。按 ← / → 翻页,↑ / ↓ 选择,Enter 填入,Esc 返回。搜索框已有文字时,左右键仍移动光标;先按 ↓ 进入词条再翻页。填入词条后仍须明确保存,不会自动提交。长词条可悬停查看全文,填入后也能在编辑区查看。

View File

@ -0,0 +1,244 @@
# 标注模块本地全流程部署方案(对齐集群线上环境)
> 技术栈说明:本项目是 **Go (API+worker) + React/Vite (前端) + Python (算子 runner) + MongoDB + Kubernetes**。
> 你本地 Mac 已由前几轮搭建完成全部基础环境(Go/colima/docker/venv/npm 依赖/本地 Mongo),本文在此基础上输出可照做的完整方案。
> **每一步末尾的 `✅ 校验` 就是成功的明确标识,没过就停下排查,不带病前进。**
## 第一步:前置环境校验清单
逐条执行,全部通过再继续(预计 2 分钟):
```bash
# 1. Go 工具链(≥1.24)
go version
# ✅ 校验:输出 go1.24 或更高
# 2. Node(≥20.19)与依赖已装
node --version && ls node_modules/.package-lock.json
# ✅ 校验:v2x.x 且文件存在
# 3. colima 虚拟机运行中
colima status
# ✅ 校验:输出 "colima is running"
# 4. 快照数据库容器(上一步恢复的 8/31 全库快照)
docker ps --format '{{.Names}} {{.Status}}' | grep fanyu-mongo-restore
# ✅ 校验:显示 Up
# 5. ffmpeg(本地切片物化需要——物化在 API 进程内执行,不走 K8s)
ffmpeg -version | head -1
# ✅ 校验:输出版本号
# 6. Python venv(算子调试用)
.venv/bin/python -c "import bcrypt; print('bcrypt ok')"
# ✅ 校验:输出 bcrypt ok(没有就 .venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com bcrypt)
```
## 第二步:拉取最新代码(分支/依赖/冲突处理)
```bash
cd ~/Desktop/fanyu/droboticflow
# 1. 保存本地改动(我们已有的 toolkit 提交都在 feature 分支上)
git status -sb
# ✅ 校验:## feature/local-dev-toolkit 且工作区干净(有未提交文件就先 git add -A && git commit)
# 2. 拉最新 dev(线上部署 commit 6eb21ada 已在 dev 历史内;dev 还比线上多几个标注修复提交)
git fetch origin dev
git rebase origin/dev
# ✅ 校验:git log --oneline -1 与 origin/dev 同步,且包含 "Keep owned-task selection during account initialization"
# 3. 依赖(一般无新增,跑一次确认)
npm install
# ✅ 校验:无 error 退出
# 4. 代码冲突预案:rebase 冲突时
# git status 找冲突文件 → 保留双方(上游改动 + 我们的 toolkit 都是新文件为主,几乎不会冲突)
# 解决后 git add -A && git rebase --continue
# 实在解不开:git rebase --abort 退回,把 toolkit 文件手工拷到新克隆目录(toolkit 全是新增文件,可整体搬)
```
## 第三步:标注模块轻量化快速启动(不等全量部署)
> 原理:标注模块的数据查询/任务领取/提交/审核流转全部走 **API + MongoDB**(读快照库);视频切片物化在 **API 进程内用本地 ffmpeg** 完成,不依赖 worker 和 K8s。只有"新建 Run 跑自动算子"需要 worker,标注测试不需要。
> 所以:**API + 前端 + 快照库 = 可以直接测标注**。
```bash
cd ~/Desktop/fanyu/droboticflow
# 1. 确保快照库在跑(第一次需要先执行拉取脚本)
docker ps | grep fanyu-mongo-restore || scripts/local/fetch-mongo-snapshot.sh
# ✅ 校验:容器 Up,脚本末尾输出 "集合数: 57"
# 2. 一次性操作:给快照里的泛宇全流程测试账号组重置本地密码(只改本地 27018 副本,线上无关)
# 在 bash 中隐藏输入,仅设置本地测试密码;不要提交或粘贴密码到文档中。
read -r -s -p 'Local test password: ' LOCAL_TEST_PASSWORD; printf '\n'
export LOCAL_TEST_PASSWORD
HASH=$(.venv/bin/python -c 'import bcrypt, os; print(bcrypt.hashpw(os.environ["LOCAL_TEST_PASSWORD"].encode(), bcrypt.gensalt()).decode())')
docker exec fanyu-mongo-restore mongosh --quiet 127.0.0.1:27017/drobodata-fanyu --eval "
const hash = '$HASH';
const emails = ['fanyu-admin@droboticflow.local','fanyu-full-annotator@droboticflow.local','fanyu-full-qc@droboticflow.local','fanyu-full-acceptance@droboticflow.local'];
print('重置: ' + db.users.updateMany({email: {\$in: emails}}, {\$set: {passwordHash: hash}}).modifiedCount + ' 个账号');
"
# ✅ 校验:输出 "重置: 4 个账号"
unset LOCAL_TEST_PASSWORD HASH
# 3. 启动(一个终端:API 连快照库;另一个终端:前端)
source scripts/local/env-local-snapshot.sh && npm run dev:api
# ✅ 校验:curl -s http://127.0.0.1:3001/api/health 返回 {"status":"ok"...}
# ✅ 校验:curl -o /dev/null -w '%{http_code}' http://127.0.0.1:3001/api/auth/me 返回 401(匿名不再回落默认账号——这是与线上的关键对齐项,env-local-snapshot.sh 已内置 DROBOTICFLOW_REQUIRE_SESSION_AUTH=true)
npx vite --port 5173 --strictPort
# ✅ 校验:curl -o /dev/null -w '%{http_code}' http://127.0.0.1:5173/ 返回 200
# 4. 浏览器打开 http://127.0.0.1:5173 登录
# 标注员: fanyu-full-annotator@droboticflow.local / 本地自行设置的密码
# 质检员: fanyu-full-qc@droboticflow.local / 本地自行设置的密码
# 验收员: fanyu-full-acceptance@droboticflow.local / 本地自行设置的密码
# 管理员: fanyu-admin@droboticflow.local / 本地自行设置的密码
# ✅ 校验:登录后能看到快照里的真实项目/工作流/20 个标注批次
```
## 第四步:全量服务部署(含 worker 与算子执行)
本地全量 = API + 前端 + worker + 本地迷你 K8s(算子 Job 执行)。worker 需要 kubeconfig 才能启动,算子执行需要真实集群资源。
```bash
# 1. 启动本地迷你 K8s(colima 内置 k3s)
colima start --kubernetes --cpu 4 --memory 6 --vm-type vz --vz-rosetta --dns 202.4.130.100
# ✅ 校验:kubectl get nodes 显示 Ready
# 2. 准备本地工作区 PVC + 镜像(算子 runner 用昨天构建的 localtest 镜像)
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata: {name: droboticflow-workspace, namespace: default}
spec: {accessModes: [ReadWriteMany], resources: {requests: {storage: 10Gi}}}
EOF
# ✅ 校验:kubectl get pvc droboticflow-workspace 显示 Bound
docker tag droboticflow-operator-runner:localtest localhost:5000/droboticflow-operator-runner:local
docker run -d -p 127.0.0.1:5000:5000 --restart always registry:2 # 本地 registry(镜像走本地不碰公司仓库)
docker push localhost:5000/droboticflow-operator-runner:local
# ✅ 校验:curl -s http://127.0.0.1:5000/v2/_catalog 输出包含 droboticflow-operator-runner
# 3. 启动 worker(连快照库 + 本地 K8s)
source scripts/local/env-local-snapshot.sh
OPERATOR_RUNNER_IMAGE=localhost:5000/droboticflow-operator-runner:local \
WORKSPACE_PVC_NAME=droboticflow-workspace K8S_NAMESPACE=default \
MONGO_URI=mongodb://127.0.0.1:27018/drobodata-fanyu npm run dev:worker
# ✅ 校验:curl -s http://127.0.0.1:3002/worker-api/ready 返回 ready:true
# ✅ 校验(端到端):平台上发起一条简单工作流 Run → 状态从 queued 变 running,算子 Job 在本地 k3s 创建并完成
# 4. 全量验证闸门
npm run verify:local
# ✅ 校验:lint/构建/k8s:validate 段全过;Go/Python/前端测试段见第七步说明(上游测试债,非部署问题)
```
## 第五步:标注模块与集群对齐配置
**1:1 对齐声明(哪些天然对齐、哪些有差异必须知道):**
| 维度 | 对齐方式 |
|---|---|
| 标注流程代码 | 本地代码 ⊇ 线上(dev 分支比线上 6eb21ada 多 3 个标注修复提交)。**对齐技巧**:要严格复刻线上行为就 `git checkout 6eb21ada` 跑;要测最新就留在 dev HEAD。差异仅这 3 个提交,都是标注任务领取/恢复类 bugfix,向前兼容 |
| 数据同步规则 | 快照是 8/31 只读副本,本地改动**永不回传线上**(无任何反向通道,天然单向隔离)。要新快照就重跑 `fetch-mongo-snapshot.sh`(会在覆盖前重建 27018 容器) |
| 接口地址映射 | 前端经 Vite 代理 `/api` → 127.0.0.1:3001,与线上浏览器 → 公网 LB 的路径结构完全一致(同一份前端代码、同一路由)。无 hardcoded 地址 |
| 权限配置对齐 | 快照自带线上真实账号体系(9 用户/3 组织/供应商/项目成员),角色判断逻辑走同一份 Go 代码——**权限行为 1:1**。CSRF 双提交 cookie 机制一致 |
| 视频预览/物化 | 线上从 BOS 桶读视频;本地无 BOS 凭据注入 → 快照里 `bos://` 引用的**实体视频打不开**(元数据、时间轴、PTS 数据可见)。这步的差异见下方"替代兼容方案" |
| worker/算子 | 线上用 CCR digest 镜像+GPU 节点;本地用自构建镜像+本地 k3s。**对标注测试无影响**(人工节点不占算子资源),只影响自动算子 Run |
**替代兼容方案(本地无法模拟的场景):**
- 场景 A:**标注工作台打不开真实视频**。方案:`local-samples/video_slice/sample-video.mp4` 先测 UI 交互;完整验证走第六步"数据集类"索要(1-2 个 Capture 的 BOS 原始目录下载到本地,用 `real_source` 算子 `SOURCE_PATH` 指本地路径跑)。
- 场景 B:**Qwen 预标注无结果**(AI key 未配)。方案:快照里已含历史预标注结果(headposeArtifacts/handPrelabel 等字段),查看/编辑链路可测;生成新结果才需要真 key——索要见第六步。
- 场景 C:**HeadPose/WiLoR sidecar 拉不起来**(GPU 镜像)。方案:本地跳过 pose 证据分支,只测人工环节;集群侧由同事在真环境跑(他的 91 个 v56 Job 就是干这个的)。
## 第六步:向同事索要的资源清单
**代码依赖类**
| 资源 | 用途 | 对接人 |
|---|---|---|
| Gitea 账号 + longtao.wu/droboticflow 写权限 | 推送修复分支、参与评审 | 仓库 owner (longtao.wu / eust-w) |
| dev 分支的发布节奏说明(哪天 deploy) | 避免本地基线落后太多 | 同上 |
**数据集类(最关键缺口)**
| 资源 | 用途 | 对接人 |
|---|---|---|
| 1-2 个完整 Capture 的 BOS 原始目录(左右目视频+PTS+IMU+标定,几 GB) | 本地跑通"目录读取→物化→标注工作台看真视频"全链路 | longtao.wu(桶 owner) |
| 对应这些 Capture 的最新库快照(现在的 8/31 快照里 34 条 Capture 记录对应的桶路径列表我可导出给他勾选) | 数据与库记录配套 | 同上 |
**配置密钥类**
| 资源 | 用途 | 对接人 |
|---|---|---|
| AI 生成服务 key(或确认禁用) | Qwen 工作流/算子生成本地可测 | longtao.wu(secret owner) |
| 测试账号在线上的密码(如需在**线上**测试时用) | 只读浏览线上标注页面对照 | 同上 |
**集群同步类**
| 资源 | 用途 | 对接人 |
|---|---|---|
| 独立测试项目或 namespace 的授权 | 最终在真集群验收(避免混入他 v56 正式测试) | 同上 |
| 发布窗口约定(避开 v56 批处理时段) | 你将来自己 deploy 时不撞车 | 同上 |
## 第七步:标注模块完整测试用例参考
登录标注员(fanyu-full-annotator / 本地自行设置的密码)逐条执行:
| # | 用例 | 操作 | 通过标识 |
|---|---|---|---|
| T1 | 登录与会话 | 上述账号登录 | 进入首页,用户名"泛宇全流程测试标注员" |
| T2 | 标注批次列表 | 进入标注中心/批次页 | 能看到 20 个批次(含 4 个 pending_annotation 态任务) |
| T3 | 任务池浏览 | 打开"可领取"任务 | 列表与详情一致,无报错 |
| T4 | 领取任务 | 点"领取"某 pending 任务 | 原子变为"我的任务"(409 冲突若被并发占用属正常) |
| T5 | 工作台打开 | 进入标注工作台 | 双目时间轴/切片列表渲染(无视频画面=场景A已知边界,UI/交互/批注应正常) |
| T6 | 切片批注 | 添加/修改描述批注 | 保存后重开页面批注保留(这正是 dev 分支 3 个修复提交的场景,重点测!) |
| T7 | 提交送检 | 完成切片+语义标注后提交 | 状态转 pending_quality,质检员账号可见 |
| T8 | 质检打回 | 质检员登录,打回并填原因+问题切片 | 标注员重新领取后看到打回意见(dev 修复点之一) |
| T9 | 质检通过 | 质检员通过 | 触发抽样决策(快照数据完整可观察) |
| T10 | 最终验收 | 验收员登录处理抽中条目 | HeadPose/HandPose include/exclude 决定可提交,交付包状态更新 |
| T11 | 审计追溯 | 管理员登录查看历史/审计页 | 打回-返工链路全程可追溯 |
| T12 | 回归对比 | `git checkout 6eb21ada` 重跑 T6/T8 | 线上行为基线对照,确认差异只在已知 3 个修复 |
**API 级补充用例(curl 直测,不依赖页面):**
```bash
# 会话+CSRF 通路(任何写操作的通道)
# 在当前 bash 中输入已设置的本地密码;通过 stdin 传给 curl,避免出现在命令参数中。
read -r -s -p 'Local test password: ' LOCAL_TEST_PASSWORD; printf '\n'
export LOCAL_TEST_PASSWORD
python3 -c 'import json, os; print(json.dumps({"email": "fanyu-full-annotator@droboticflow.local", "password": os.environ["LOCAL_TEST_PASSWORD"]}))' | \
curl -c /tmp/c.txt -X POST http://127.0.0.1:3001/api/auth/login -H 'Content-Type: application/json' --data-binary @-
unset LOCAL_TEST_PASSWORD
CSRF=$(grep droboticflow_csrf /tmp/c.txt | awk '{print $NF}')
curl -b /tmp/c.txt -X POST http://127.0.0.1:3001/api/human-items/<id>/claim \
-H "X-Droboticflow-CSRF-Token: $CSRF"
# ✅ 校验:返回任务详情 JSON,且 GET /api/human-items 的 assignee 变为该用户
```
**停止与重启:** Ctrl+C 停 API/前端即可;快照库容器 `--restart unless-stopped` 常驻。**绝对不要**对 27018 库之外的任何公司资源做写操作——这条红线下,本方案所有操作与公司集群零冲突。
## 附录:真实数据标注链路(同事已放行下载 Capture)
线上的产物路径已被清理(桶里只剩 `FYLX_B/` 原始数据和回收站),所以"看真视频"的路径是从**原始数据**接入:
```bash
# 1. 下载一个完整 Capture(约 235MB,左右目视频+PTS+IMU+标定)
scripts/local/download-capture.sh # 默认 FYLX_B01_AZER764007R_19700101_001838
# ✅ 校验:~/Desktop/fanyu/droboticflow/local-data/captures/ 下 10 个文件,ffprobe 能解析左目视频
# 2. 接进快照库的标注任务(改本地 27018 库里的 artifact path + 任务归属)
scripts/local/wire-local-capture.sh
# ✅ 校验:curl 登录后 GET /api/human-items/<id>/subject-content 返回 200 video/mp4
# 3. 浏览器进标注工作台
# fanyu-full-annotator@droboticflow.local 登录 → 领取的任务里双目视频真实可播、可拖进度条
```
原理(为什么这能通):API 的 `serveResolvedRunArtifactContent` 对**本地路径**的 artifact(`path` 不含 `://` 且文件存在)直接走本地文件流式输出,含 Range 支持;对 `bos://` 才去连 BOS。所以把快照库里的 artifact path 换成本地文件路径,标注工作台的视频播放就完全本地化了,且权限体系(角色/成员/供应商隔离)原样生效——这已实测验证(质检员访问标注员的任务正确返回 403)。
## 远程验收脚本的凭据配置
远程验收脚本不再内置账号密码。仅在已经获得公司环境写入授权后运行;本次文档清理并不授权执行远程验收。
- 三个 `*-workflow-acceptance.sh` 脚本(holobrain-full-training、poc-operator、wilor-operator)必须设置 `DROBOTICFLOW_ACCEPTANCE_PASSWORD`。
- `scripts/execute_remote_poc_test.py` 还必须设置 `FANYU_ANNOTATOR_PASSWORD`、`FANYU_QUALITY_PASSWORD`、`FANYU_ACCEPTANCE_PASSWORD`。
- 从环境负责人或未跟踪的本地凭据文件获取实际值,不在命令行参数、文档或提交中记录密码。缺少必需值时脚本直接停止。
- 旧版本曾包含固定密码;删除源码中的明文不会使旧密码失效,也不会删除已有 Git 历史。环境负责人应核对这些旧账号并轮换仍有效的密码。

View File

@ -0,0 +1,73 @@
# 标注工作页操作说明
选择项目后点击“开始工作”,即可在当前标签页连续标注。系统先续做本人未完成任务,没有时才在有权限的项目与供应商范围内随机领取;领取前不能挑选视频。
## 连接方式与手动模式
独立工作页和连续领取需要支持 Web Locks 的安全连接,例如 HTTPS;浏览器也将本机 localhost 视为安全上下文。普通 HTTP 连接下会显示“当前连接使用手动模式;独立工作页和连续领取需安全连接”。此时在原工作台点击“随机领取任务”,从“我的任务”继续切片、标注、保存和送检;送检后手动领取下一条。
手动模式保留服务端任务归属、版本检查和领取请求重试,但不提供多页面互斥。不要同时在多个页面编辑同一任务。直接打开 HTTP 工作页时,点击“返回手动工作台”会保留原项目和任务,不会释放或重新领取。领取结果未知时再次点击“随机领取任务”,沿用原请求编号核对结果。
浏览器支持页面锁、但锁被另一页占用或协调出错时,不会降级绕过锁;按提示返回活动页或刷新重试。
## 进入、停止与退出
首次进入默认使用专注视图:平台导航收起,左侧是同步双视频、播放控制和时间轴,右侧是当前切片或动作描述编辑区。页面顶部始终保留“切回原布局”和“返回任务池”。
连续工作中,当前任务真实送检成功后会接续下一条。准备结束时点击“完成当前任务后停止”:仍可完成手中任务,但不会再领取下一条,也不会释放已经领取的任务。需要接着做时点击“恢复连续工作”。任务池为空时连续工作暂停,不会反复领取。
“返回任务池”会执行原有离开保护。若有未保存草稿,选择继续编辑可返回当前工作;确认离开会丢弃页面中未保存的编辑。刷新、关闭标签页或重新打开后,必须显式点击“继续工作”,只恢复服务端已经保存的内容,不能恢复浏览器草稿与撤销历史。
安全连接下,同一浏览器的同源标签页中,同一账号、同一项目只能有一个活动工作页。第二个标签页提示已有活动页时,返回原页继续;原页退出或关闭后再恢复。不要通过反复开页重复领取。
## 切片:确认名称后生成
1. 观看两路视频,用播放、逐帧按钮或快捷键定位。按 `C` 或“在播放头分割切片”新增边界;切分点须位于片内,不能落在现有边界。
2. 从项目切片字典选择名称。`F` / `D` 可打开字典,搜索、分页后用鼠标或方向键选择,`Enter` 填入,按一次 `Esc` 返回工作台。选择名称仅修改当前编辑,未确认前不会保存。
3. 检查边界与名称,点击“确认全部切片”,再点击“确认生成”。系统处理完成后才进入描述阶段;收到处理中提示不代表已经生成完成。
切片保持源视频有效帧范围的完整覆盖。删除切片会把范围并入相邻切片。需要舍弃时使用“舍弃片段”并填写原因;舍弃保留审核证据,不等于删除视频,也不移动相邻边界。
## 描述:先保存,再送检
点击“新增动作描述”或按 `N` 标记起点;播放或逐帧定位后再按 `N` / `Enter` 确认结束点。进入文本框后填写描述,也可以从描述字典填入模板再修改。模板只是草稿,不会自动保存。
“确认保存描述”或 `Ctrl / ⌘ + Enter` 保存当前描述。“取消编辑”放弃当前未保存修改。切换切片可以保留各片草稿,但送检前必须处理所有未保存草稿。保存失败时先按提示核对版本、权限或网络,不要把仍显示的草稿当成已保存。
完成后点击“完成任务并提交质检”,检查切片、描述、留空和舍弃汇总,再点击“确认送检”。审核数据准备完成、任务进入待质检后才算送检成功。**送检成功不等于质检通过**;连续工作也不需要等质检员作出通过结论。
语义留空是合法的未描述范围,仍参与审核和媒体交付;“无效区间”是明确的语义判断;“舍弃切片”是不交付该切片并保留证据。这三种处理不能混用。删除动作描述会留下空白,不删除视频或合并相邻动作。
## 长列表、字典和长文本
专注视图中的切片和描述时间轴每页最多显示 4 条。使用前后页、查找或“当前”定位;输入文字查找下一匹配项,输入 `#13` 可直接定位第 13 条。查找不会筛除数据。`Ctrl / ⌘ + 左右方向键` 仍按全部切片的时间顺序导航;撤销、重做与草稿恢复会显示目标所在页。
字典在右侧固定编辑区内打开,不挤压视频。每页条目数根据编辑区剩余高度自动调整,分页按钮、页码和总条目数固定在搜索框下方。词条以单行显示,鼠标悬停可查看完整文本;返回编辑后可查看完整填入内容。字典内按 ← / → 翻页、↑ / ↓ 选择、Enter 填入、Esc 返回。有搜索文字时,← / → 保留移动光标功能,先按 ↓ 进入词条再翻页。文本输入、字典导航和中文组合输入拥有自己的按键,不应触发工作台操作。
长描述可以在文本框内滚动。“展开描述编辑”暂时收起精确边界区域,让出更多文字空间;“收起描述编辑”恢复边界。保存与取消始终在文本滚动区外。展开、收起、翻页和切换布局都不会自动保存。
## 放大画面与快捷键
默认完整、等比显示两路同步画面,不裁剪。点击“放大左相机”或“放大右相机”临时检查细节,详细时间轴会收成进度条,当前编辑、逐帧和保存仍可操作。点击“恢复双画面”回到详细时间轴,播放帧、草稿和选中项保持不变。
常用快捷键可从“快捷键帮助”查看:`Space` 播放/暂停,左右键逐帧,`B` 复查本片,`V` 返回工作点,`F` / `D` 打开字典。工作台内 `Ctrl / ⌘ + Z` 撤销、`Ctrl / ⌘ + Shift + Z` 重做;输入框内仍使用原生文本撤销。撤销/重做有一秒节流,只覆盖当前任务的当前编辑阶段;生成、重新切片、送检和换任务会截断历史。
## 小窗口、缩放和原布局
专注视图要求浏览器**内容区至少 1280×640 CSS 像素**。显示器标称分辨率不等于内容区:窗口边框、浏览器工具栏、系统缩放和浏览器缩放都会减少可用空间。
低于底线时,页面暂停播放与自动接续,保留当前任务、播放位置、草稿和历史。放大窗口或降低浏览器缩放后,必须点击“继续当前工作”;仅调整尺寸不会恢复工作,视频仍需手动播放。此前选择的“完成当前任务后停止”仍然有效。
已发出的保存、生成、送检或领取请求可能在暂停期间完成。系统会核对原请求,不能把暂停当作取消,也不会因窗口改变重复领取。提示结果未知时,使用“核对阶段结果”或“核对领取结果并开始连续工作”;领取核对沿用原请求编号。权限变化或活动页冲突须先处理,恢复窗口不会解除这些限制。
随时可点击“切回原布局”,返回旧版的滚动布局;“进入专注视图”再次收起导航。运行中切换保留任务、阶段、选中项、播放帧、各片草稿、撤销记录及连续工作选择,不会保存或重新领取。布局偏好按当前账号和当前浏览器保存,不会串到其他账号;浏览器禁止本地存储时,当前切换仍可用,但下次未必记住。
## 恢复范围与验收边界
工作中的布局切换是当前页面内的回退。源码恢复则使用本地标签 `codex/annotation-keyboard-baseline-20260918`,指向 `54a35afad95d77b1f23c955f9c4671cae83a664d`;完整备份位于忽略目录 `local-data/backups/annotation-keyboard-baseline-20260918.bundle`。标签指向及 bundle 完整历史已再次核验。恢复前应由维护人员保留当前改动并另建检出进行核对。
本轮 PR 意见修改前的新工作页另有备份:标签 `codex/annotation-workspace-pre-review-20260918` 指向 `7585b43f0c14b29015541fc3a33d914227ce4366`;完整历史包为 `local-data/backups/annotation-workspace-pre-review-20260918.bundle`,不覆盖上述旧版快捷键备份。
Git 标签和 bundle 只恢复代码,不能恢复数据库、下载的视频、浏览器未保存草稿或撤销记录。这些数据须分别备份与恢复。本次没有执行代码回退、数据库回滚、远端推送或公司环境部署。
本地验收包括真实 590×480 双视频、五档 CSS 内容区、四档窗口及真实浏览器缩放、实际保存和送检。16:9 / 9:16 使用合成素材验证比例适配;浏览器派发的组合输入检查不代表原生操作系统中文输入法验收。物理显示器、操作系统缩放、原生输入法及公司部署环境尚未全面实测。旧本地验收任务的文件产物不可用,因此该页仅核对了布局与面板隔离,未完成媒体加载验证。详细证据、已有测试债与运行方式见[整体验收报告](verification/annotation-workspace-layout/acceptance-results.md)及[全套检查结果](verification/annotation-workspace-layout/full-suite-results.md)。

View File

@ -0,0 +1,149 @@
# 本地开发调试指南(macOS / 隔离环境)
本指南描述如何在不接触公司集群的前提下,在本机完成单功能开发与调试。环境搭建背景见仓库根目录 `README.md`,业务概念见 `docs/platform-usage-manual.zh-CN.md`。
## 0. 隔离边界(先读这个)
| 事项 | 规则 |
| --- | --- |
| MongoDB | 只用本机容器 `fanyu-mongo`(`127.0.0.1:27017`),绝不指向公司实例 |
| Kubernetes | 不导出 `KUBECONFIG`、不使用 `fanyu.conf`;发布走 `docs/release-checklist.zh-CN.md` 且须同事确认 |
| BOS / AI | 本地全部留空禁用;数据源一律用本地路径(`local-samples/`) |
| 镜像仓库 | 本地构建演练不登录、不推送;推送发布见发布清单 |
## 1. 环境准备(已完成则跳过)
```bash
# 工具链(一次性)
brew install go colima docker docker-buildx ffmpeg mongosh
colima start --cpu 4 --memory 6 --vm-type vz --vz-rosetta
# 本地 MongoDB(只绑 127.0.0.1;--restart 保证 colima/VM 重启后自动跟随启动)
docker run -d --name fanyu-mongo --restart unless-stopped -p '127.0.0.1:27017:27017' -v fanyu-mongo-data:/data/db mongo:7
# Python 算子依赖(公司网络下 pip 默认源不可用,用阿里镜像)
python3 -m venv .venv
.venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com -r requirements-dev.txt
# Go 模块代理(公司网络下 proxy.golang.org 不可用)
go env -w GOPROXY=https://goproxy.cn,direct
# 前端依赖
npm install
```
注意事项(踩过的坑):
- **Go 进程不读取 `.env.local`**:仓库没有 godotenv,`MONGO_URI` 等变量必须 shell 导出。
- **colima VM 内 DNS 可能失效**(`systemd-resolved` 未安装导致 resolv.conf 指向不存在的 stub)。症状:`docker pull` 报 `lookup ... on [::1]:53: connection refused`。修复:`colima ssh -- sudo sh -c 'printf "nameserver 202.4.130.100\nnameserver 202.4.130.101\n" > /etc/resolv.conf'`。
- **Docker Hub 直连超时**:改走国内镜像 `docker pull docker.m.daocloud.io/library/mongo:7` 再 `docker tag` 回 `mongo:7`。
- **colima 每次重建 VM 后要重配两样**:VM 内 DNS(见上文修复命令)和 docker daemon 的 registry mirror(`colima ssh -- sudo sh -c 'printf ... > /etc/docker/daemon.json && systemctl restart docker'`)。建议保持 `--vm-type vz --vz-rosetta` 参数启动。
- 日常启停:`colima start` / `colima stop`。Mongo 容器已设 `--restart unless-stopped`,会随 docker daemon 自动跟随启动;只有 colima VM 被**删除重建**(`colima delete`)后容器才会丢,需要按上面命令重建。
- **API 报 `server selection timeout ... connection refused`** = 27017 没人监听:`docker start fanyu-mongo`(先确认 `colima status` 是 running)。API 进程本身不会死,Mongo 恢复后立即自愈,无需重启 `npm run dev`。
## 2. 启动本地平台(API + 前端)
```bash
source scripts/local/env-local.sh # 每个新 shell 都要先 source
npm run dev # API :3001 + Vite :5173
```
- 浏览器打开 `http://127.0.0.1:5173`,首次用「创建超管账号」入口建一个本地管理员(如 `admin@local.dev`)。
- 已验证可用:登录/会话、CSRF 双提交写保护、算子目录(111 个)、存储连接、项目、工作流(含节点)全套 CRUD。
- **预期边界**:不启动 worker(`npm run dev:full` 本地起不来——worker 启动必须有 kubeconfig)。页面上点"运行"后 Run 会停在 `queued`,这是轻量层的正常行为。如需本地端到端,需另行搭建本地迷你 K8s(kind/colima-k8s),属于后续升级项。
写接口的 curl 调试需带 CSRF(与线上一致):
```bash
curl -c /tmp/c.txt -X POST http://127.0.0.1:3001/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"admin@local.dev","password":"..."}'
csrf=$(grep droboticflow_csrf /tmp/c.txt | awk '{print $NF}')
curl -b /tmp/c.txt -X POST http://127.0.0.1:3001/api/projects \
-H 'Content-Type: application/json' -H "X-Droboticflow-CSRF-Token: $csrf" \
-d '{"name":"...","storageConnectionId":"<id>","storageBucket":"..."}'
```
## 3. 单算子一键调试(核心工作流)
```bash
scripts/local/run-operator.sh <slug> [输入artifact列表JSON文件]
```
- `<slug>` 是 `operator-repos/builtin/` 下的目录名;脚本自动读取 `operator.json` / `runtime_contract.json` 的 handler,用与 worker 在 K8S Job 里**完全相同的方式**调用 `backend/operator-runner/main.py`。
- 产物固定写入 `local-runs/<slug>/<时间戳>/`(已 .gitignore):`outputs/`、`result.json`、`stage-manifest.json`。
- 默认输入:`local-samples/<slug>/input.json`(存在时)。
- 附加超参:`OPERATOR_EXTRA_HYPERPARAMS='[{"key":"SEGMENT_DURATION_SECONDS","value":"4"}]'`。
- 已内置样例:`json_to_csv`(3 行 JSON→CSV)与 `video_slice`(本地 10 秒测试视频→3 段虚拟切片)。
**改算子源码的调试循环**(不需要任何镜像构建):
```bash
# 1. 直接改 operator-repos/builtin/<slug>/src/operator.py
# 2. run-operator.sh 默认通过 DROBOTICFLOW_OPERATOR_SOURCE 直指这份源码,立即验证
scripts/local/run-operator.sh <slug>
# 3. 验证通过后,同步镜像副本(否则 operators:manifests:check 会挂):
npm run operators:repos
```
## 4. 分层测试命令
| 层 | 命令 | 说明 |
| --- | --- | --- |
| 单算子 | `scripts/local/run-operator.sh <slug>` | 真实执行,秒级 |
| 单算子单测 | `.venv/bin/python -m pytest backend/operator-runner -k <关键词>` | 或 `tests/backend/<某算子>_test.py` |
| Go 全量 | `npm test`(= `go test ./...`) | 不需要 Mongo/集群 |
| Python 全量 | `npm run test:python` | 用系统 python3;建议先 `source .venv/bin/activate` |
| 前端 | `npm run test:frontend` | node --test,无需浏览器 |
| 总闸门 | `npm run verify:local` | lint + 全部测试 + 构建 + k8s 清单 dry-run |
## 5. 算子发布链本地演练(无 docker)
内置算子的正式发布流程是"改码 → 生成仓库清单 → 构建镜像 → digest 钉版 → 目录同步 → reconcile"。本地可以演练全部**不碰 docker** 的环节:
```bash
npm run operators:repos # 同步 operator-repos 与 backend 镜像副本
python3 scripts/update_operator_release_manifests.py --slug <slug> \
--image <registry/ref:tag> --image-id <registry/ref@sha256:digest> # 钉版(digest 来自实际构建)
npm run operators:images # 重新生成算子目录/镜像契约
npm run operators:images:check # 一致性闸门,必须通过
```
## 6. 镜像构建演练(本地、不推送)
公司网络下四个拦路虎及解法:
1. **基础镜像拉不下来**(Docker Hub 直连超时):先 `docker pull docker.m.daocloud.io/library/<镜像>` 再 `docker tag` 回标准名(golang:1.24-bookworm、node:22-alpine、debian:bookworm-slim、python:3.11-slim 都需要)。
2. **构建时 `go mod download` 超时**:Dockerfile 里默认 `GOPROXY=proxy.golang.org` 被墙,构建时必须传 `--build-arg GOPROXY=https://goproxy.cn,direct`。
3. **apt/pip 下载超时**(operator-runner 镜像重灾区):用本机代理 `127.0.0.1:7890`。colima 容器里访问宿主机代理要用 VM 网关地址(`colima ssh -- ip route | grep default`,当前为 `192.168.5.2`),以 `--build-arg http_proxy=http://192.168.5.2:7890` 注入(docker 的 http_proxy/https_proxy build-arg 无需 Dockerfile 声明即自动生效)。
4. **QEMU 交叉编译 Go 会段错误**:colima 需用 `--vm-type vz --vz-rosetta` 启动(Rosetta 模拟 amd64 接近原生速度)。
因此公司网络内的本地构建演练用 docker 原生命令(`scripts/build-and-push-images.sh` 未透传 GOPROXY/代理,直接跑会卡在 go mod download 或 pip):
```bash
PROXY=http://192.168.5.2:7890 # colima VM 看到的宿主机代理地址
docker build -f Dockerfile.worker --platform linux/amd64 \
--build-arg GOPROXY=https://goproxy.cn,direct -t droboticflow-worker:localtest .
docker build -f Dockerfile.drosync-coordinator --platform linux/amd64 \
--build-arg GOPROXY=https://goproxy.cn,direct -t drosync-coordinator:localtest .
docker build -f Dockerfile.api --platform linux/amd64 \
--build-arg GOPROXY=https://goproxy.cn,direct \
--build-arg http_proxy=$PROXY --build-arg https_proxy=$PROXY \
-t droboticflow-api:localtest .
docker build -f Dockerfile.operator-runner --platform linux/amd64 \
--build-arg http_proxy=$PROXY --build-arg https_proxy=$PROXY \
-t droboticflow-operator-runner:localtest .
# 验证产物架构
docker image inspect droboticflow-operator-runner:localtest --format '{{.Os}}/{{.Architecture}}'
```
> 注:真正推送发布时走 `scripts/build-and-push-images.sh`(见发布清单)——如果届时也卡在 go mod download / pip,可先与同事确认是否把代理 build-arg 透传进脚本,或临时在本机代理开着的状态下用上面的原生命令构建后手动 `docker push`。
## 7. 常见问题
- **`go run` 卡在下载依赖**:确认 `go env GOPROXY` 是 `https://goproxy.cn,direct`。
- **pytest 报 numpy/cv2 缺失**:用 `.venv/bin/python -m pytest` 而不是裸 `pytest`。
- **算子报"无法获取真实输入文件"**:检查 input.json 里 `items[].path`(文件级 path 是算子找源的入口,不是 artifact 顶层 path)。
- **API 起不来报 Mongo 连接失败**:`docker start fanyu-mongo`,确认 `mongosh --host 127.0.0.1` 能 ping。

View File

@ -0,0 +1,109 @@
# 发布清单与回滚预案(公司集群 droboticflow-fanyu)
> 本清单在**本地全绿 + 同事确认之后**才执行。发布顺序不可颠倒;每一步失败就停下排查,不带病前进。
## 0. 前置闸门(发布日前逐项打勾)
- [ ] `npm run verify:local` 全绿(lint + Go + Python + 前端 + 构建 + 清单 dry-run)
- [ ] 涉及的算子用 `scripts/local/run-operator.sh <slug>` 实测通过
- [ ] 改过 `operator-repos/**` 的,`npm run operators:images:check` 通过
- [ ] 代码已 push 到 Gitea(无账号时:`git format-patch origin/dev -o /tmp/` 交同事代推/评审)
- [ ] **同事已在 Gitea/补丁上评审确认**(必要条件,不满足则不发)
- [ ] 已确认目标 namespace:`droboticflow-fanyu`;已和同事约定发布时间窗口(避开采集高峰)
- [ ] 集群当前无进行中的重要 Run(平台监控页确认)
## 1. 记录回滚锚点(发布前必做)
```bash
export KUBECONFIG=/Users/d-robotics/Desktop/fanyu/droboticflow/local-data/fanyu.conf # 仅发布 shell 会话内
kubectl -n droboticflow-fanyu get deploy \
-o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .spec.template.spec.containers[*]}{" image: "}{.image}{"\n"}{end}{end}' \
| tee /tmp/rollback-images-$(date +%Y%m%d-%H%M).txt
```
> 注意:api/worker 的镜像记录在 Deployment env(`DROBOTICFLOW_IMAGE`、`OPERATOR_RUNNER_IMAGE`)里且带 digest;回滚清单要同时抓 env 里的这几项。把这份文件连同本次发布说明一起存档。
## 2. 构建并推送镜像(公网端点)
```bash
docker login ccr-29eug8s3-pub.cnc.bj.baidubce.com
# 凭据:用户 ccr$fanyu(见本地 source.md;只存在本机 docker 凭据库,绝不进代码)
REGISTRY_HOST=ccr-29eug8s3-pub.cnc.bj.baidubce.com \
REGISTRY_NAMESPACE=fanyu \
IMAGE_TAG=$(git rev-parse --short HEAD) \
./scripts/build-and-push-images.sh
```
- 产出 4 个镜像:`droboticflow-api` / `droboticflow-worker` / `drosync-coordinator` / `droboticflow-operator-runner`(自动交叉构建 linux/amd64)。
- 取 digest 备用:
```bash
for img in droboticflow-api droboticflow-worker drosync-coordinator droboticflow-operator-runner; do
docker buildx imagetools inspect \
ccr-29eug8s3-pub.cnc.bj.baidubce.com/fanyu/$img:$(git rev-parse --short HEAD) \
| grep Digest
done
```
- 只改了算子(没改平台代码)时可以只发算子镜像,其余保持旧 digest 不动——**最小变更原则**。
- 公司网络下若卡在 go mod download / pip:以 `--build-arg http_proxy=http://<colima网关>:7890` 注入本机代理构建(见 local-dev-guide 第 6 节),构建完手动 `docker push`。
## 3. 部署到公司集群(VPC 端点 + digest 钉版)
```bash
export KUBECONFIG=/Users/d-robotics/Desktop/fanyu/droboticflow/local-data/fanyu.conf
VPC=ccr-29eug8s3-vpc.cnc.bj.baidubce.com
TAG=$(git rev-parse --short HEAD)
K8S_NAMESPACE=droboticflow-fanyu \
API_IMAGE=$VPC/fanyu/droboticflow-api@sha256:<api-digest> \
WORKER_IMAGE=$VPC/fanyu/droboticflow-worker@sha256:<worker-digest> \
DROSYNC_COORDINATOR_IMAGE=$VPC/fanyu/drosync-coordinator@sha256:<drosync-digest> \
OPERATOR_RUNNER_IMAGE=$VPC/fanyu/droboticflow-operator-runner@sha256:<runner-digest> \
CREATE_REGISTRY_SECRET=false \
./scripts/deploy-k8s.sh
```
要点:
- `MONGO_URI` 不传:脚本自动从集群现有 `droboticflow-mongo-secret` 回读。
- `CREATE_REGISTRY_SECRET=false`:复用集群现有 `droboticflow-registry` 拉取密钥,命令行不出现任何明文凭据。
- 脚本内部是 `kubectl apply` + `rollout status` 等待,可安全重跑。
- GPU/Qwen 相关变量(`OPERATOR_GPU_NODE_SELECTOR` 等)当前由集群 ConfigMap 提供,不在本次发布中改动。
## 4. 发布后验证
```bash
# 1) rollout 就绪 + 健康
kubectl -n droboticflow-fanyu get pods
curl -s http://120.48.180.80/api/health && curl -s http://120.48.180.80/api/ready
# 2) 构建 commit 与预期一致
curl -s http://120.48.180.80/api/health | python3 -m json.tool | grep -i commit
# 3) 平台冒烟:登录、跑一条最小工作流(或按变更范围跑对应验收)
```
## 5. 回滚预案
症状(任一):健康检查失败、run 大面积失败、镜像拉取失败。
```bash
# 用第 1 步存档的旧 digest 重跑同一脚本即回滚(rolling update 回旧镜像)
export KUBECONFIG=/Users/d-robotics/Desktop/fanyu/droboticflow/local-data/fanyu.conf
K8S_NAMESPACE=droboticflow-fanyu \
API_IMAGE=<旧api镜像@digest> WORKER_IMAGE=<旧worker镜像@digest> \
DROSYNC_COORDINATOR_IMAGE=<旧drosync镜像@digest> \
OPERATOR_RUNNER_IMAGE=<旧runner镜像@digest> \
CREATE_REGISTRY_SECRET=false ./scripts/deploy-k8s.sh
```
- 算子级回滚:`git revert` 对应 `operator-repos/builtin/<slug>/release.json` 的提交,重跑 `npm run operators:images` + reconcile,把线上算子目录拨回旧 digest。
- 数据安全:deploy 只滚动更新 Deployment,不动 Mongo 数据与 BOS 对象;回滚后 Run 历史仍完整可查。
- 回滚后立即通知同事并在发布记录里写明原因。
## 6. 代码评审通道(Gitea 权限待定期间)
- 有推送权限:`git push origin feature/<名字>` → Gitea 上发起合并到 `dev` → 同事评审。
- 暂无权限:`git format-patch origin/dev -o /tmp/patches/`,把补丁目录交同事 `git am` 代推;或直接把分支推到个人 fork。
- 线上 `dev` 分支与集群部署版本可能存在少量提交差,发布前与同事对齐目标基线,避免把未验证提交带上线。

View File

@ -0,0 +1,35 @@
# 标注键盘工作流验收档案
实施范围为本仓`.scratch/annotation-keyboard-workflow/`的11票,代码基线`1a5c308b`至最终修正`bad89540`。全部在本地5173/3001/27018隔离项目完成;未推送或部署。
先看[最终验证结果](./final-validation-results.md)和[操作说明书](../../annotation-keyboard-guide.zh-CN.md)。逐项场景见[验收矩阵](./acceptance-matrix.md),实际步骤与API回读见[原始验收记录](./acceptance-evidence.md),全仓失败的基线对照见[测试分类报告](./final-suite-triage.md)。
## Standards
[原审查](./final-standards-review.md):无文档规则违反,1项轻微重复逻辑建议。[修正复审](./final-standards-fix-review.md):已解决,没有新的重要问题。
## Spec
[原审查](./final-spec-review.md):迟到用途响应、新草稿重做分支、帮助文案共3项。[修正报告](./final-fix-report.md)和[修正复审](./final-spec-fix-review.md):全部解决,前两项有真实浏览器RED/GREEN及公开API证据。
两轴分别报告,不互相抵销。最终无未解决的Critical/Important审查项;全仓测试仍有已复现的基线债务及明确验证边界。
## 逐票记录
- 01:[实施报告](./task-1-report.md);[审查1](./task-1-review-fix1.md)、[审查2](./task-1-review.md)。
- 02:[实施报告](./task-2-report.md);[审查1](./task-2-review.md)。
- 03:[实施报告](./task-3-report.md);[审查1](./task-3-fix1-review.md)、[审查2](./task-3-review.md)。
- 04:[实施报告](./task-4-report.md);[审查1](./task-4-fix1-review.md)、[审查2](./task-4-review.md)。
- 05:[实施报告](./task-5-report.md);[审查1](./task-5-review.md)。
- 06:[实施报告](./task-6-report.md);[审查1](./task-6-review-fix1.md)、[审查2](./task-6-review-fix2.md)、[审查3](./task-6-review.md)。
- 07:[实施报告](./task-7-report.md);[审查1](./task-7-review-fix1.md)、[审查2](./task-7-review.md)。
- 08:[实施报告](./task-8-report.md);[审查1](./task-8-review.md)。
- 09:[实施报告](./task-9-report.md);[审查1](./task-9-review-fix2.md)、[审查2](./task-9-review.md)。
- 10:[实施报告](./task-10-report.md);[审查1](./task-10-review-fix1.md)、[审查2](./task-10-review.md)。
- 11:[实施报告](./task-11-report.md);[审查1](./task-11-fix1-review.md)、[审查2](./task-11-review.md)。
## 保留范围
[执行台账](./progress.md)保留顺序派遣、修正与四项裁决;[混合语义产物核对](./materialization-actual-08.md)保留实际文件哈希证据。历史报告里的“待浏览器验收”反映其写作时间,以最终验证结果为准。
完整原始日志、退出码、差异包、夹具辅助脚本和故障注入工具保留在未跟踪目录`local-data/verification/annotation-keyboard-workflow/`。旧记录中`.superpowers/sdd/annotation-keyboard-workflow/`是执行时路径,现已归档;运行时本地故障代理已停止。归档不包含任何新硬编码凭据。

View File

@ -0,0 +1,153 @@
# Browser acceptance evidence
Baseline 1a5c308bdac35789998b16b4deaee89ad603482d; all mutations isolated local fixtures.
| Cases | Ticket gate | Evidence status |
| --- | --- | --- |
| A09, A13, A18 authoritative writes | 01 | Pending |
| A01, A03 playback/frame | 02 | Pending |
| A04–A06 descriptions/focus | 03 | Pending |
| A02, A07, A18 navigation/drafts | 04 | Pending |
| A08, A11, A18 slice history | 05 | Pending |
| A09, A11 persisted history | 06 | Pending |
| A05, A08–A10, A14 delete/invalid | 07 | Pending |
| A12–A14, A18 confirmation | 08 | Pending |
| Full single-task work page | 09 | Pending |
| A17, A18 restore/ownership | 10 | Pending |
| A15–A17 continuous next | 11 | Pending |
Primary evidence: cua_repl real keyboard/mouse, DOM-visible selection/focus and video currentTime/paused read-only observation, existing API request and readback.
Supplemental: HTTP conflict/idempotency/pending tests, keyboard/frame/history boundary unit tests. No source assertions counted as feature acceptance.
## Ticket 01 — real browser + local public API
Browser CUA tab1, 1440x1000 desktop viewport, authenticated local annotator. Vite5173 → local fault proxy3301 → API3001; proxy only exact keyboard-acceptance task paths.
- Normal description edit/save: editor closes; GET primary version2 confirms text.
- After server200, proxy destroys response: GET reconciliation closes editor, displays intended text; independent GET confirms version3.
- Public API competing write version4, stale browser description save receives409; current draft retained. Stale reset receives409, warning/dialog and descriptions remain. GET still version4/newer server text.
- Delayed task save response held30seconds after server200; same-page primary task card clicked while pending. Primary content remains own text after delayed response; GET delayed task version2 confirms only its own text.
- Primary reset200 response dropped: browser GET reconciliation enters slicing with single0–412slice/no descriptions; independent GET version6 workflow editing/slice and segments[].
- Fixture issue discovered/fixed: inherited task duration and nested BSON timestamps. These were test-data defects, not production changes. Missing dictionary binding sent to fixture owner before ticket02.
- Supplemental focused tests cover account change/ABA and unreadable reconciliation; no browser account switch claimed.
## Ticket 02 pre-change RED browser observation
Slicing fixture has 3 saved slices. Selected middle `切片002` (120.1–216.066667), advanced via Next Frame, escaped native button, pressed C. Created boundary120.166667; selection fell back to first `切片001` and displayed playback120.1 instead of cut. Four slices existed after split, proving actual split and incorrect selection/playhead. This directly reproduces A01 failure before ticket02 implementation. Browser changes unsaved; reload restores3 fixture slices.
## Ticket 03 pre-change RED browser observation
On annotate-delayed, NextFrame to0.033333 then Escape,N starts new interval. Right steps to0.066667; second N leaves status `正在确定结束点` and button `确认结束点` active, rather than completing selection. CancelNew restores original saved description; no API write. Task02 implementation does not touch this behavior.
## Ticket 02 initial browser gate
C paused exactly120.166666666667, retained left child named切片002; videos paused left120.166668/right120.133335 unchanged from pre-cut. Space continued both videos beyond new boundary. Subsequent C during127.066667 playback did nothing: split button disabled, still4slices, video continued. Root sent implementer playhead-containing target bug and misleading selected-relative elapsed text. Not accepted until corrected.
Ticket02 corrected gate: C120.166667 originalframe pause with valid leftchild; Space continued; next C at127.566667 created5thslice and paused dualleft127.566668/right127.533335. 4× Right127.600000 thenLeft127.566667 exactly one native frame beyond prior selectedleft end. Annotation current-slice playback120.066667 advanced then stopped120.1, bothvideospaused. Remaining gate illegalboundary prompt + independent review.
Ticket02 final boundary gate: C at0 now renders visible alert `当前帧位于切片边界,请移动到片段内部帧后再拆分。`;3slices and full0–412coverage unchanged. All browser gates passed; independent reviewpending.
## Ticket03 controller browser gate (2026-09-17)
- Origin is http://127.0.0.1:5173 (localhost is a separate auth origin). annotate-delayed public API baseline v2 with saved30–60 description.
- NextFrame,Esc,N,Right,N produced draft0.033333–0.066667 and active DIV aria-label动作描述编辑区, nottextarea. EmptyCtrlEnter showed 请直接填写描述,或从字典选择后修改 withoutsubmission.
- F opened22-optiondescriptiondialog;Down,Enterselected2ndtemplateandreturnededitorfocus. Enterfocusedtextarea;literal f+Space+Chinese text entered without dictionary/play action. CmdEnter saved; public API v3 contains exacttext 关东煮锅具清洁、补汤、投串、食材排布与槽位清理f 键盘验收03 plusoriginal30–60description. Real persistence proved.
- Inblanknear10.566667,N thenCtrlEnter showed 请先确认结束点,再保存描述。 Right,Enter completedend andfocusededitorarea. Dopenedcompatdict. OneEsc closed it; nextSpace playedbothvideos whileeditor/draftremained. Pause/cancel removedonlyunsaveddraft.
- Textarea actual a/b/c keystrokes stayed text; nativeSelectAll/Cut emptied text, no playback or dictionary. OneEsc frominput returnedSECTION andSpace playedbothvideos. Caveat: embedded browser native CmdZ/CtrlZ did notrestorecuttext during automation; parserreturnsnull for thesecombos, no datahistorypresent inthis ticket. Do notclaimnative undo restoration verified or realOSChinesecomposition tested; focusedparserIME/repeatcases supplement. Followup historyticket mustcheck no data-historydispatch wheneditingtext.
- Slice-primary F openedactual3nameprojectdictionary (notdescriptiondictionary);oneEsc returnedSECTION,Spaceplayedbothvideos no dialog. Dopenedcompatdialog,Down/Enterselectedcurrentnameonceandclosed. No save/submission triggered.
- Fixround1browser: validunsaveddraft0.166667–0.2, native从字典选择button ControlEnter didnotdispatchsave (embeddedbrowseralsoopenednodialog);draftremained. Cancelled. Proxyloggedno fixture-write andGETv3unchanged.
## Ticket04 controller RED
On annotate-delayed createN/Right/N validintervalaround0.233333 then text票04跨片草稿保留验收;EscCtrlRight didnotnavigate (headingstill001). Mouse002then001 losteditor/draft. NoPOSTloggedbylocalproxy; publicbaselinev3. Rootleftidle001head.
## Ticket04 stable pre-review gate (9027a79b workingtree)
- Freshreload afterimplementerfreeze; APIbaselinev3. First001draft0.166667–0.2 text第一片未保存草稿 preservedCtrlRight/Left. 002pendingendselection0–0.1 restoredafter003andback whileplayheadat002head120.1. Tail003reachable,no wrappingatend.
- B on002playsfrom120.1bothvideos; pendingendinputremained0.1. RepeatedB,Right,CtrlRighttwice,V returnedoriginal0010.2pausedbothvideoswithfirsttextdraft. NavigationbeforefirstB capturedcorrectorigin.
- Leavingcurrent003blankwithparkeddrafts via返回我的任务 hit nativewindow.confirm and blockediabtab1CDP; getJsDialogundefined,AX/closecommands timeout. CUAdeniesCodexnativeappcontrol. Newiabtab3samebrowserusable,loggedstatecontinues. Requestedimplementer useexistingnonblockingappconfirmationforin-appreturn/link/back,retainnativebeforeunloadactualrefreshclose. No writestriggered; checkproxylog/readbackafterfinalgate.
- Followupappmodal showsparkeddraftleavewarning, Esc and继续编辑 preserveactualtext. InitialcancelBODYfocusfixedbyworker; freshgate oneEsc CtrlLeft restores001text withSECTIONfocus.
- Foundacceptdiscardroute-reusegap: clickstageheaderlink then清空并切换 changesitemURLtoworkflowURL butretains sameworkbench draftsince taskIDunchanged. Workerfixrequested explicitgeneration/reset onconfirmeddiscard. NoPOSTlogged.
- At52263727 same-taskheaderlinkconfirmeddiscardPASS: editorabsent, twooriginalserversegmentsreloaded.
- ImportantBackfailureconfirmed: Dashboard/ ->标注中心 ->selectfixture ->我的任务 ->continueannotate-delayed ->validdraft后退到仪表盘保护 ->Esc ->browserBack. Source/workflows/all/annotate?projectId=fixture&taskId=...;target/; noappdialog,Dashboardrendered,draftlost. Review04blocks;workerfixround1 usesrouterlevelblocker.
- Slice-primaryCcreated0–0.133333shortslice. Bstarted0,naturallystopped0.133333left/rightpausedtimes0.133335. Vselectedrightchildatboundary0.133333.
- Newbookmark0.233333,Bthenmousedeleteoriginalsecondchild. Afterrefocus,Vreturned0.233333paused incurrentmerged0.133333–216.066667slice. No obsoleteIDresurrection. ExistingdeletebuttonremovalleftBODYfocus (Vinitiallynoop); carriedto05mouseundo requirement, explicitbriefnote.
- All04gates thusfar emitted nofixturePOST inlocalproxy; APIbaseline3unchanged. Currentbrowserid3onslice-primarywithunsavedsliceedits; don'tnativeReloadwhilependingbeforeunloadmayblockiab. Useappreturndiscardmodalorcancelwhenavailable.
- Routerfixround1realbrowserPASS: repeatDashboard->annotationfixture->ownedtask->validtextdraft后退修复验收草稿->Back restorescurrentannotationURL andshowsappmodal. EsccancelkeepsSECTIONfocus/text. Backagain+清空并切换 reachesactualDashboard/. BrowserForward openssavedtaskwithouteditor/draft. PublicGETstillv3same2segments; proxy haszerofixture-writeevents forentire04gate. No autosave.
## Ticket05 root RED
BASEa5932e80 slice-primaryC0.133333makes4slices; CtrlZstill4. Confirmedlocaldraftdiscardthroughappreturnmodal restored3persistedslices. NoPOST.
## Ticket05 first runnable gates
- C0.1333333->4slices;CtrlZ->3,immediateCtrlShiftZstays3(1ssharedthrottle). APIv1still editing/slice/noannotations.
- AfterrootAPIroundtripandworkerbuild,playheadreset0andredoempty. Workerfoundnoordinaryslicephasepoll; buildwritedist/index.htmlmaytriggerVitefullreload. Notyetprovenproductiondefect; retryafterallbuild/filesystemwritesfrozen beforeclaiming.
- Actualpointerdragfirstboundary120.1->141.7;oneCtrlZ restores120.1and3slicelegalcoverage (PASS).
- MouseDelete2ndslice while1stselected: SECTIONfocuskept,count3->2, immediateCtrlZ->3 (PASS). Butrestoredselection001/time0 ratherthanaffected002; workerfixingfocusmetadata. Don'tmarkgatecompleteuntilfixed/retested.
- Newtab3 usesdefault1280x720; oldviewportoverrideonlyoldtab1. Forpointerdragscrollmain down, thenfreshDOMgetBoundingClientRect of observed拖动切片边界. Initialoffscreen938y failed; afterscroll583y valid. No needviewportresize.
- Stablee09ad03f/allbuildwritesfrozen: mouse2nddelete+CtrlZrecovered3withSECTION/time120.1/current002; intervalredo2. Earlierreset/selectionnotreproducible, no productionfixclaimed. Newcutafterundo4; oldredo remains4; CtrlRighttwice/RightLeft thenCtrlZ3/current002120.166667, provingnavnohistory. Dictionary002->001 thenCtrlZ002. TaskswitchandreturnoldredoNOP3. DictionarysearchinputCtrlZretains4,EscCtrlZrestores3; cleanreloadthenCtrlShiftZstill3. Stagegeneration/submitgate08pendingcomposite.
## Ticket06 browser RED (BASEb913bff0)
annotate-delayedN0.166667 CtrlZ still1editor; RightNend0.2 thentext第六票撤销基线保存 CtrlEnter realAPIv3->v4 adds thirdsaveddescription0.166667–0.2. AfterfocusingrootCtrlZ stillsaveddescvisible. Baselinev4 nowthreeactions0.033333–0.066667/0.166667–0.2/30–60. Currentidleplayhead0.233333,nodraft.
## Ticket06 preliminary e59286cb
Browser N at .3 CtrlZ removes editor, redo restores; N end .333333 CtrlZ restores pending endpoint and redo ends. DirectGET v4 unchanged. Saved text 第六票保存与撤销验收 .3–.333333 -> v5 four descriptions; CtrlZ ->v6 three and editor text retained; redo->v7 four. Proxy drop-request task6-undo-no-forward confirms forwarded:false and UI502; repeatCtrlZ succeedsv8three, provingfailedhistorynotconsumed; redo restore pending finalread. Pausingforreviewbaselinefix.
## Ticket06 stable55a81c55 partialgate
Loadv9fouractions; firstslice0pendingtext第一片保留的未完成草稿 parked, second120.1–120.166667save第二片跨片撤销测试 ->v10. NavigatefirstCtrlZ ->v11removessecondserverdesc, selectsecond120.166667bothvideospaused, editorrestored; returnfirsttext+pendingendretained. Cancelbothviabuttons (BODYfocus aftercancel). Delete30–60mouse ->v12threeremainunchanged; directCtrlZ ->v13originalid/text/30–60restored. Mousebatchinvalid ->v14fiveinvalid addedinallgaps,existingfourunchanged. EscapeCtrlZ noPOST; explicitNextFrame+Escape showsSECTION thenCtrlZ stillnoPOST/version14/noalert. Originalworkerinvestigatingreadonly; donotcallcomplete.
## Ticket06 final gates (55a81c55 then9859fa8d)
Additiverevisionbaseline fixture APIv1 noannotationWorkspace/Draft,1revision30–60. Browserclicktimeline44.6,C split; savechild ->v2twoactions; CtrlZ ->v3exactoriginalid/text30–60 (labelnormalized鲜食处理); nextCtrlZlocal splitremoved,noeditor. ThusreviewP2fixed. Mousebatch ->v4twoinvalidgaps preservesoriginal;focusBODY, directCtrlZnoPOST; explicitNextFrame/EscCtrlZ ->v5originalonly. Confirmedfocusdefect fixed9859fa8d; independentreviewround2Approved. Newfrozencode browserbatchv8 thenfocusSECTION directCtrlZ ->v9originalonly.
Proxyredo200drop recoveredv6threeactions,noalert; firstattemptunknownwithoneGETdrop recoveredthrough existing4retryclient, NOTunknownproof. Properunknownredo latest9859fa8d usedPOST200drop+fourGET200drops: realv10threeactions,UIoneaction/unknownalert. SameCtrlShiftZretry stalePOST+matchingGET ->UIthree/noalert, serverstillv10(noextra mutation). Publiccompetingwritev11changedoriginaltext另一页面保存的最新描述;UICtrlZstale409 leavesv11newtextandinvalids,visibleconflict; repeatCtrlZattempt alsofails nooverwrite. Failedhistorynotconsumed. Earlierdroppedrequestgatev7->failurethenretryv8provedwritefailretainsundo.
Devbrowserunexpectedreloads evidencedviteconnecting14:31:24/14:32:21confoundedinitialbatchhistoryobservation. RestartedusingexistingDISABLE_HMR=true, no configsourcechange. VitePID38124/session2651; mustmanualreloadaftercommits. Newworkingtab4; tab3stuckonconnectionerrorafterrestart (do notwastegoto/reload, errorpageURLpolicyrejectsdataURI). Tab1nativeconfirmblocked.
Controllerreviewcannotverifyitems resolved: historycapacity/throttle inherited05pure+browser; crosssliceparkeddraftsactual06passed; actualtask/accountdelay covered01sameauthorityscope; stageprocessing/interfaceguards06HTTP plus integrated08pending. No unresolved06Important findings.
## Ticket07 partialgate37480aec
ResolverTDDREDvalid, but initialrootShiftDelete/CtrlXREDobservationsinvalidatedbytoolinterception. MinimalindependentDOMkeyprobe .superpowers/.../key-probe.html documentsrealkeydown: ctrl+x/Control+x andShiftDelete produceNOevent,ShiftBackspace produces{key:Backspace,shift:true}. EdgecreatedtabfailsCodexauth tokenunavailable. Keepstandardchords limitationexplicit; notproductionbugguess.
ActualMacShiftBackspace savedtargetrevisionbaseline30–60 removesonlyidv11->12 (invalidneighborsremain), CtrlZ->v13originalexact. NotargetShiftDelete notmeaningfulbecauseintercepted; selectionenforcedresolver+code. Textdraftsecond002 CtrlXcuttexttoempty(noPOST/version13). CancelnewfocusSECTION. Sliceprimaryselect002Macdelete3->2merges002rangeintofollowing003120.1–412,CtrlZrestores3originalranges. Discard002reason本地快捷键保护验收 ->v2; C/Macdeleteblocked andall3ranges/namesunchanged. Restorekeepconfirm ->v3workspace.segments:null thenrendercrashfilterinannotationSegmentsForSlice->deriveSliceStatuses->AnnotationOperationsmemo. Originalworkerfixing, rootmustreloadUIafterfreezeandreprodiscardrestore.
Ticket07fix6db97457realGREEN: sliceprimarydiscard002v4segments[] restorekeepv5segmentsnull; UI3slices/generateenabled/noerror; actualreload3slices/noerror. Revisionbaseline002emptysharedmousebatchv14adds120.1–216.066667invalidpreservesfirstthree, directCtrlZ v15restoresblankpreservesfirstthree. IndependentfixreviewApproved. NativeCtrlX/ShiftDelete notdelivery-tested perRuling4; parserRED/GREEN+exactsharedhandleractualAPI evidence, nofalseclaimphysicalkeys.
## Ticket08 browser gate in progress (b6e80de8)
Fresh exact slice-primary route after CODE-FROZEN. CtrlEnter at SECTION opened generation modal with3keep/noPOST; Escclosed. Selectedthirdslice, explicitdiscardreason savedthroughnormalUI. Reopenedmodal accurately3total/2keep/1discard +per-slice blankcounts. IndependentReturn generatedonePOST slice-confirmations (proxytime1789658129697); publicstatusv7processing/validating at2026-09-17T15:15:29Z, UIprocessing0/3. RepeatedReturn/CtrlEnter/CtrlZ inprocessing leftonlyread-onlyprocessingpanel and核对生成状态, noextraPOST. Generationstillpending; notclaimedcomplete.
Ticket08 actualgenerationcompleted,annotatephase3lockedranges. CtrlZdidnotrevertslicephase. N.033333+CtrlEnterkeptpending/no modal; parkingfirstdraft thenCtrlRight/CtrlEnter opened affected-slice guide. Clickguide restoredpending, Right+N locked .066667; missingtextCtrlEnter showedvalidation/no stage. Filled第八票两步提交实测:保留前后语义空白,CtrlEntersavedonly(v11stageannotation_combined). Secondfullslice batchinvalidv12. QAmodal3total2keep1discard,2saved1invalid,first2semanticgaps/second0gaps/thirdreason. Escandmouseentryparitypass.
Faultproxy POSTcombined-submissions drop-request and4readGETdrop-request =>UIunknown/read-onlywith核对阶段结果. Manual核对 recoverededitablewithclearfailuremessage, unchangedstage. RealretryPOSTsuccessresponse dropped =>readback quality_review/ready/pending_qualityv14; UIreturnedpooland显示审核数据已生成,任务已提交质检; noextraPOSTonCtrlZ. Publicsavedstatepreservesmeaning. Fullblankannotate-primaryone412sslice generationnowrunning via mouseconfirmation; do notclaimitscompletionyet.
Allblankbrowsergate: annotate-primarygeneratedone0–412dictionarynamedslice; QAmodal0descriptions/0invalid/1blankkeep. IndependentEnterthenactualpublicstatusv12quality_review/ready/pending_quality. Noauto-invalid/no forceddescription. Materializationfiles08supportverified21/21hashesrev2andrev3for mixedtask; see materialization-actual-08.md. Ticket08allprimarygatespass. IME/heldrepeatsemanticcoveredpublicparser; actualOScompositionremainsdisclosedlimitation.
Task09browserRED onb6e80de8: selectedauthorizedisolatedproject, finishedownedtask atpool, exact开始工作buttoncount0. Existingflowonlytaskpool/editor, no dedicatedentry. No mutations.
Task09acdc5427firstGREENfailed: exactslice-primaryitemroutefreshreload, authorizedprojectselected, 开始工作visibleenabled. Clicknavigates /plugins/annotation-qa/workflows/all/annotate(noquery), heading真实切分与语义标注, project请选择, no dedicatedview. Workerfixrequested. No fixturemutations.
Task09ce012f8a entryGREEN: selectauthorizedproject then开始工作 ->samelocalTabid4 URL /plugins/annotation-qa/workflows/all/work?projectId=project-keyboard-acceptance&taskId=annotation-task-keyboard-acceptance-revision-baseline. Heading标注工作页, 完成本条任务后暂停, no poolsidebar, restoresownedrework withsaved3actions; no randomclaimPOST inproxylog. Normal重新切片warning+confirm ->one412sdictionaryslice. NextFrame/Esc/C createsdirtycut; header返回任务池blockedwithleavewarning; Escpreservesworkpage; CtrlZonewholeagain, CtrlEntermodal1keep0description. IndependentEnter triggeredrealgeneration (1789659231795); noAPIrestart. Formalreviewcandidate asyncclaimstalenavigation underinvestigation; browserpausedforfix.
Task09fixround2actualREDce012f8a: ordinaryrandomclaimrequestId8bb22e0cfb569533ef21b61591d23f5c200dropresponse; StartWorkreplayedSAMEID with30sdelay. Clickedannotate-delayed taskcardduringwait, observednormalannotateroute+taskIdannotate-delayed. Onceoldresponsearrivedbrowserforcedworkroute+taskIdpool-03withoutdialog. ExactreviewP2confirmedandoriginalworkerreleasedtofix. Pool03nowlegitimatelyowned, remainingpool3. Revision-baselinegenerationcompletedversion20/annotate, no mutationwhiletest.
Task09fixround2GREEN97fe6c77: newlogicalclaim a3c994365423bd3db9445dd757577659drop-request(noallocation), StartWorkreplaySAMEID30sresponse delayallocatedpool01. Duringdelay switchedannotate-delayedandNstartsecond-slicedraft. Afterresponse URLstillannotate-delayed, no dialog, exactpendingendpointretained; pool01addedMyTasks. No staleerrors. Cancelleddisposablependingdraft, selectedrevision-baseline thenStartWork openedcorrectworkpage.
Task09fulljourneycompleted: sameworkpagerevision-baselinenormalreset->C/undo+leaveEsc->generationv20annotate. N.033333/Right/Nend.066667,Fdialog,oneEsc+Spacebothvideosplaying; pausethenF/Down/Entertemplate,Entertext+CtrlEnter explicitsavev21. CtrlZv22serverempty,CtrlShiftZrestored; CtrlEnterQAsummary1description2blanks; independentEnteractualquality_review/ready/pending_qualityv25. Pagekept标注工作页/本条任务已完成送检,可返回任务池, noautomaticclaim. FormalreviewP2fixedandscopedreviewApproved; firstentryguardfixverifiedactualbrowser.
Remainingowned: annotate-delayed, pool03, pool01. Remainingready:pool02,pool04. OldclaimIDsconfirmed/cleared. No pendingjob.
Task10browserREDon97fe6c77:pool03sameworkURLtab4/tab6sameiabcontextboth确认全部切片enabledtrue. tab6reloadstillenablededitor, no继续工作button. NoAPIwrites/claims. Closedoldtab6beforeworkerchanges; tab4pool03noedits.
Task10GREEN04d15dd8+d5356785: fresh/reloadworkpagepaused恢复工作会话/继续工作, editorabsent. Selectownedpool03Continueactivates. Samecontexttab7sameprojectblockedreturnactivity+continuedisabled, firstenabled. DirtyC3->4thenheaderreturnEsc keeps4andsecondblocked; acceptleave->pool,secondcontinueenabled thenexplicitcontinue3serversavedslices; CtrlZdoesnotrestore4. Refreshsecondpagepausedagain,explicitcontinueworks. NormalpoolStartdisabledwhileotheractive; closeactivetab7 ->poolStartenabledwithinquerycycle; explicitStartreturnsowned03. Noextra claimPOST acrosswholegate.
Projectscope readonly: tab8ordinarypool isolatedshowsotherowner; selectexistingauthorizedproject-d84a938560a792c16c2d72e8468e7563 ->noownerwarning/Startenabledwhileoriginaleditorstillenabled; didNOTstart/claim/mutateotherproject; switchbackisolatedblockedagain. Closedtab8.
Accountscope viaactualnormalUIlogout/login: activeprimary->localQCaccount (projectrolequality_reviewer) =>noauthorizedannotationprojects,noownedrecoverabletask, noeditor/no oldownerwarning; Continuecausesnoeditororclaim. Logout/loginprimary ->pausedownedpool01/03, explicitcontinueworks. Nodataloss/mutation; assignedUserId primary preservedpublicAPIpool03v2claimed3originalslices. Accountcredentiallocaltestdocs only; noaccount/role/credentialchanges.
Finalfixd5356785pagehidependingacquire identityinvalidated independentreviewApproved. ActualdocumentnavigationtoDashboardandbrowserBackreturnedpausedworkpage/Continuepresent/editor0. DeterministicpendingnativeWebLock/BFCachecallbackinterleavingnotinjected; publiclifecyclecontrolflowproof+scopedreviewrecorded, notclaimedphysicalracecoverage. NativeOSIME/inputundo/nativebeforeunloadlimitationsunchanged.
Fixtureprogressduring11implementationfrozen10: pool03normalgenerate3keep/allblankthenQAcompletedv8quality_review/ready/pending_quality. Noforcedrelease. Onlypool01ownedv2slicing, pool02/pool04ready. Rootno11GREENclaimed yet.
## Task11 browser/API acceptance — 2026-09-18
Frozen fe593f8e; text-only fix3ee1db6a seen on duplicate newpage. Explicit recovery starts pool01 alreadyowned; generation processing causes no claim. Actual QA v8 triggers one request a0ecba265c7c5c2b6a3d79fe3d6e1a0f; proxy forwards200 and dropsresponse, UIpauses retaining QA result. Closed tab4, openedtab10: paused, pool04owned listed, noautomaticPOST. Plain Continue refuses unresolvedreceipt. Explicit recovery replays SAME ID, openspool04v2; pool02remainsreadyv1. Stop-after-current preservesowner/editability; pool04generated+actualQA v8, noextra claim. Secondtab11 cannotcontinue/recover whileprimaryactive; closed. Explicitresume then claimsremainingpool02. ItsQA POST and4GETblocked: readonlyunknown+continuouspause, noadditionalclaim. Explicit核对阶段结果 restoreseditableunchangedtask butcontinuitystillpaused. Explicitresume+retry actualQA v10; oneempty-poolclaim87296793726ae6dcb84c2832d2d25c38, UIshows本项目暂无您可领取的标注任务;连续工作已暂停,可稍后恢复。 No privateReact/storageinjection; allactions CUA UI, truth publicAPI; read-only fixtureverify confirmscounts. All8isolatedtasks legitimatelycompleted throughQA, noforcedrelease/company/BOSwrites.
Unknown/stop/empty primarygates pass; permission/accountscope actualTask10 and task11HTTP+review supplement. ActualsystemIME/nativeundo and physicalCtrlX/ShiftDelete limitations remain as documented.
## Final review fixes — primary RED/GREEN
Two additive LOCAL revision fixtures disposition-race-a/b were created using ignored copies of the existing whitelist-constrained fixture script (revision-baseline slug substituted). Existing8completedtasks unchanged; no forcedrelease/ownershiprewrite.
P1 RED old472c2447loadedpage: A keepv3→discardv4 response60sdelay; Esc closespendingmodal, selectBthenA, serverdiscardv4read; restorekeepv5. Olddiscardresponse flipsUIbackdiscard0desc whileAPIv5keep1desc. GREEN frozenfinalfix reload: discardv6response45sdelay, sameEsc/B/A, restorev7. At72.3seconds afterdelayedrequest, UIkeep1desc/APIv7keep1desc unchanged. FaultIDs final-disposition-aba-red/green. Initialmodalblockedattempt and routeBack-only attempt were exploratory, notclaimedRED.
P2 RED race-b: saveBv2,undov3,typenewC/Esc/Redo→serverv4B,editorclosed/C lost. GREEN: saveDv5,Undov6(serverB),typeE/Esc/Redo→Eeditorpreserved,noPOST,APIstillv6B. Publichistorytestalso verifiesredo invalidationwithoutper-characterundoentries.
Finalfrontendrecheckaftersharedfixes:578tests569pass9fail, exactsame9baselinefailures. Type/build/focused64allpass; finalscopedreviewpending.
P2 dictionary variant GREEN: savedE v7,Undo v8, F/Down/Enter fills关东煮template,Esc/CtrlShiftZ leaveseditor23charstemplate, noextraPOST; APIv8 unchanged. Newdraftnotautopersisted.

View File

@ -0,0 +1,24 @@
# 最终验收跟踪
逐票证据在 acceptance-evidence.md;下表只标完整场景状态,不能把解析器测试等同真实输入法验收。
| 场景 | 操作 | 预期 | 状态 |
|---|---|---|---|
| A01 | 连续播放,在已有多个切片的中间片内按 C | 原帧切分并原地暂停,选中项不回退第一片;Space 可越过新增边界继续播放 | 票02共享编辑器通过;票09独立工作页切分/撤销与生成链通过 |
| A02 | 在工作点离开复查,连续切换两片并按 B | 每次 B 都从选中片头播放到片尾;V 返回最初记录的工作点并暂停 | 票03/04共享编辑器通过;票09独立页复用同一编辑器,字典Esc/Space与保存链回归通过 |
| A03 | 描述编辑阶段播放和普通左右键逐帧 | 不跨当前切片;左右视频仍使用统一硬件帧范围,步长不受倍速影响 | 票02共享编辑器通过;票09独立工作页切分/撤销与生成链通过 |
| A04 | N 开始,在允许的区间内再次 N 或 Enter 结束 | 两种方式确认同一终点,进入描述编辑区而非直接提交;F 选词、Enter 输入、Ctrl/⌘+Enter 保存 | 票03真实浏览器/API通过;票09独立页N/F/Enter保存及服务器撤销回归通过 |
| A05 | 输入法组合、输入框内空格/F、Ctrl+X、Ctrl+Z | 输入法和文字编辑正常,不触发播放器、字典、批量无效或工作台撤销 | 文字剪切/工作台隔离实测,解析器IME不截获通过;真实系统IME与原生文字撤销恢复未验证 |
| A06 | 字典打开后按一次 Esc,再按 Space | 字典关闭,草稿保留,Space 播放/暂停视频,不重开字典 | 票03/04共享编辑器通过;票09独立页复用同一编辑器,字典Esc/Space与保存链回归通过 |
| A07 | 本片有未保存动作,Ctrl/⌘+方向键切到另一片,再返回 | 原动作草稿仍在且未偷偷保存;首尾不循环,未处理尾片可导航 | 票03/04共享编辑器通过;票09独立页复用同一编辑器,字典Esc/Space与保存链回归通过 |
| A08 | 切分、边界拖动、误删切片后逐步撤销/重做 | 完整恢复对应范围及名称/状态,覆盖无缺口;跨片操作定位到受影响片,不把播放动作算进历史 | 票05切分、完整拖动、删除撤销实测通过;独立页C/Undo与离开保护已回归 |
| A09 | 描述已保存或删除后撤销,再重新读取任务 | 服务器与界面内容一致;保存失败、结果未知、版本冲突均不伪报成功或覆盖其他新状态 | 票06真实API保存/删除/跨片/未知重试/并发拒绝通过 |
| A10 | 对多个语义空白按 Ctrl+X | 仅当前片的全部空白被明确标为无效;一次撤销恢复全部空白,已有描述不变 | 票07共享鼠标处理器+API批量/撤销通过;物理CtrlX工具不投递keydown,见Ruling4 |
| A11 | 长按撤销、快速反复按、撤销后新编辑 | 每秒最多一个成功受理的撤销/重做动作,长按不连发;新编辑截断重做分支,保留最多 100 步 | 票05实际快速撤销/重做及新编辑分支通过;100步/长按规则由公开历史与键位测试补充 |
| A12 | 有本片草稿、其他片草稿、全部无草稿,分别按 Ctrl/⌘+Enter | 分别保存当前描述、要求处理其他草稿、打开阶段确认;一次按住 Enter 不穿透确认 | 票08当前/其他/无草稿、Esc、独立Enter实测通过;长按/IME解析器补充 |
| A13 | 确认生成或送检后返回 processing,随后成功或失败 | 等待真实状态;成功才进入下一阶段,失败保留恢复入口;不能重复提交或跨阶段撤销 | 票08真实生成和送检、处理中锁、未知恢复/丢响应回读通过;后端异步失败由HTTP测试覆盖 |
| A14 | 语义全空、部分留空、明确无效、舍弃片段分别送检 | 保持现有区别:留空合法且仍交付,舍弃证据保留并过滤交付;快捷键不绕过字典、权限和边界校验 | 票08混合语义与全留空实际送检通过,21/21产物哈希核对;字典/角色/CAS公开HTTP通过 |
| A15 | 开始连续工作,完成当前任务后停止 | 当前任务正常送检,之后不再随机领取;已领取任务不被释放 | 票11真实连续、停止、未知跨页原编号恢复与空池暂停通过;处理失败/角色由公开HTTP补充 |
| A16 | 连续模式遇空池、网络结果未知、服务端处理失败、权限改变 | 暂停并说明状态,不跳过当前任务;领取结果未知时沿用原请求编号核对/重试 | 票11真实连续、停止、未知跨页原编号恢复与空池暂停通过;处理失败/角色由公开HTTP补充 |
| A17 | 刷新、重开或同账号项目打开第二个工作页 | 不静默追加领取;恢复已领取任务并显式继续,只有一个页面执行自动连续领取 | 票10/11实际刷新、关页重开、双页、账号/项目范围检查通过;无静默领取 |
| A18 | 新增/撤销动作、刷新或离开任务 | 刷新只恢复后端已保存内容,历史不跨刷新;未保存内容受离开提醒保护,进入新的任务/阶段不使用旧撤销栈 | 票04–08SPA离开/刷新savedonly/任务阶段历史边界通过;原生beforeunload工具兼容限制保留,独立页初步回归通过 |

View File

@ -0,0 +1,80 @@
# Final review fix wave
Base: `472c2447`. Scope: three Spec findings, the shared recoverable-task predicate Minor, four newly failing legacy tests, and formatting of the task-modified workbench test. No backend contract, company cluster/BOS, service process, or unrelated formatting changes.
## Changes
- P1: disposition success checks full token/task/account ownership before any response-derived state write. The error path checks ownership before reconciliation and again after its await before propagating the error to the editor. Cleanup retains `endAnnotationMutation(token)`, whose `scope.end(token)` refuses invalidated or superseded identities.
- P2: added `invalidateRedo()` to the existing history boundary; it removes the redo branch and advances the history revision without adding undo entries. The workbench reports substantive draft patches through `onAnnotationDraftEdit`, and both text input and dictionary templates use that path. Equal-value patches, reopening and focus changes do not invalidate history. Existing keyboard, IME, textarea and input handlers are unchanged.
- P3: removed the claim that final submission is button-only. The shortcut help continues to document its existing keyboard stage action; reslicing and release remain button-only.
- Standards Minor: extracted one file-local `isOwnedRecoverableAnnotationItem(item, projectId, userId)` predicate, shared by entry/resume selection and recovery-card eligibility. Conditions are unchanged.
- Retired only obsolete clauses in four old source-shape tests: moved inline split-name expression (real split-name coverage already exists in `annotation-workbench.test.mjs`), forbidden previous/next navigation, exact previous combined-submission guard, and the unrelated blanket ban on title descriptions. In the same capture-workbench test, the `保存草稿` substring ban also matched the approved `未保存草稿` warning, so it was retired too. Other domain checks remain; no replacement source/private assertions were added.
- Formatted the already task-modified `annotation-workbench.test.mjs` with Prettier, including its pre-existing unformatted sections.
## Verification so far
The public mutation-scope test was strengthened to return to task A, start a newer mutation, then verify the old response is stale and old cleanup leaves the newer mutation active. This is supplemental seam evidence; the controller subsequently reproduced the actual P1 browser defect on the original loaded page, as recorded below.
Root owns the primary browser/API RED→GREEN checks and the final full-suite evidence. No new full-suite run is part of this fix wave.
Supplemental public history seam RED:
```sh
bash .superpowers/sdd/annotation-keyboard-workflow/run-final-check.sh final-fix-history-red node --test tests/frontend/annotation-history.test.mjs
```
Result: 8 passed, 1 failed. The new behavior test invokes the planned `invalidateRedo` method, absent before the fix (`TypeError: history.invalidateRedo is not a function`). It checks that new draft input removes stale redo, preserves prior meaningful undo, and creates no per-character undo entries. This missing-API result is supplemental; the controller's actual browser RED is the behavior gate.
Retired-clause check:
```sh
bash .superpowers/sdd/annotation-keyboard-workflow/run-final-check.sh final-fix-legacy-green node --test --test-name-pattern='slice names are selection-only|Capture workbench follows the confirmed two-phase interaction|v5.8 submits a combined revision|only pages with real internal views render secondary navigation' tests/frontend/annotation-five-rules.test.mjs tests/frontend/capture-annotation-workbench.test.mjs tests/frontend/fanyu-comment-followup.test.mjs tests/frontend/plugin-page-subnav.test.mjs
```
Result: 4 passed, 0 failed. First focused attempt exposed the additional `保存草稿` false positive noted above; the final log records the passing rerun.
## Controller browser RED
P2 was reproduced on the original loaded `472c2447` page with HMR disabled and local `disposition-race-b`: initial revision A; save `最终复审保存描述B` (server v2); Ctrl+Z (server v3; editor restored); enter `最终复审新草稿C应保留`; Esc; Ctrl+Shift+Z. The stale redo sent a new POST and saved B at v4, closed the editor and lost C. Controller reported this evidence before the P2 production edits.
P1 was reproduced on the original loaded page with HMR disabled and local `disposition-race-a`: keep at v3; submit discard at v4 with its response delayed 60 seconds; Esc closes the pending modal; select task B then A; the authoritative GET shows discarded v4; a normal restore commits keep at v5. When the old discard response arrives, the UI incorrectly switches back to discarded with 0 descriptions while the public API remains v5, keep, with 1 description. Proxy record `final-disposition-aba-red`, delayed request timestamp `1789663009053`, newer restore timestamp `1789663029438`. The original modal-blocked attempt was superseded by this actual sequence. The controller had authorized the minimal fence repair from static review before completing this RED, but deliberately retained the original loaded page until RED was captured; GREEN uses a manual reload of the frozen fix.
## Final focused checks
All run through the existing clean-environment launcher; output is saved under `final-checks/` with corresponding `.exit` files.
```sh
bash .superpowers/sdd/annotation-keyboard-workflow/run-final-check.sh final-fix-focused-green node --test tests/frontend/annotation-history.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs tests/frontend/annotation-workbench.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-five-rules.test.mjs tests/frontend/capture-annotation-workbench.test.mjs
bash .superpowers/sdd/annotation-keyboard-workflow/run-final-check.sh final-fix-web-lint npm run lint:web
bash .superpowers/sdd/annotation-keyboard-workflow/run-final-check.sh final-fix-web-build npm run build:web
bash .superpowers/sdd/annotation-keyboard-workflow/run-final-check.sh final-fix-format node node_modules/prettier/bin/prettier.cjs --check src/lib/annotation-history.js src/components/CaptureAnnotationWorkbench.tsx src/pages/AnnotationOperations.tsx tests/frontend/annotation-authoritative-mutation.test.mjs tests/frontend/annotation-history.test.mjs tests/frontend/annotation-workbench.test.mjs tests/frontend/annotation-five-rules.test.mjs tests/frontend/capture-annotation-workbench.test.mjs tests/frontend/fanyu-comment-followup.test.mjs tests/frontend/plugin-page-subnav.test.mjs
```
Results: **64 tests passed, 0 failed**; TypeScript exit 0; web build exit 0 (existing chunk-size warning for >500 kB bundle); all 10 touched files pass formatting. The 4 legacy cases also passed in the focused name-filter run above. `git diff --check` is clean. No full suite was repeated. No backend or deployment surface changed.
## Self-review
- Full disposition ownership check precedes every response-derived write; no await occurs among those writes. A stale error before or during reconciliation cannot be propagated into the current editor. Old cleanup cannot unlock a newer mutation.
- Draft invalidation is a separate operation from recording a meaningful edit, retains prior undo and keeps the existing shared one-second command window. It runs outside React's state-updater callback, avoiding side effects during updater replay.
- Template and textarea changes share the same substantive-patch check; no-op template selection preserves redo. The existing helper also covers invalid/valid toggles and explicit boundary patches.
- Recovery entry and cards use precisely the same unchanged eligibility terms.
- The formatter-only workbench test changes alter no inputs or expected values. Existing split-child name assertions remain executable domain coverage.
- Existing full-suite failures and untouched formatting debt remain with the controller's final-suite triage; no broad repairs were attempted.
## Controller browser GREEN
P1: after manually reloading the frozen fix, repeat the same ABA sequence: discard v6 with a 45-second response delay; Esc; task B then A; restore keep v7. At 72.3 seconds after the delayed request, the UI still shows keep with 1 description and the public API remains v7, keep, 1 description. The late response no longer overwrites the current workspace.
P2 text: fixed page on `disposition-race-b`; save D at v5; Undo produces v6 with server B; type E; Esc; Ctrl+Shift+Z. The E editor stays visible, the server remains v6 with B, and no additional POST is sent. This is the primary text draft RED→GREEN gate. The controller is also checking the dictionary-template variant; its result will be recorded in the controller acceptance evidence.
Controller-owned full frontend rerun after the frozen fixes: `frontend-after-final-fixes.log`, **578 total, 569 passed, 9 failed**. All 9 failures exactly match the baseline debt; the 4 newly failing legacy cases are resolved. This suite was run by the controller, not redundantly by this implementer.
## Commit and handoff
Commit: `bad89540` — `🐛 Guard annotation sessions and invalidate stale draft redo`.
The commit includes only the 10 task-owned code/test files listed by `git show --stat bad89540`. The unrelated controller-created `docs/annotation-keyboard-guide.zh-CN.md` was left untracked and unstaged. `git diff --cached --check` was clean immediately before the commit. No push was performed. The ignored report/evidence files remain local. Code and tests remained frozen throughout the browser GREEN checks.
No open implementation findings from self-review. Remaining controller work: record template variant, conduct the single scoped re-review, and assemble the final user report. Existing OS physical-key/IME verification limits and unrelated baseline suite debt remain in controller records.

View File

@ -0,0 +1,13 @@
- **P1 disposition response fence — ADDRESSED.** `src/pages/AnnotationOperations.tsx:2139` verifies mutation-token ownership before updating the item, workspace, baseline or history. Lines 2162–2164 fence both error reconciliation and subsequent editor error propagation. This satisfies spec line 127: “Keep task, stage and ownership changes isolated from stale responses and old history.” The supplied primary browser evidence reproduces the old A→B→A corruption and shows the fixed delayed response leaves UI/API consistently at keep/v7.
- **P2 new draft edit retains stale redo — ADDRESSED.** `src/components/CaptureAnnotationWorkbench.tsx:886–897` notifies substantive draft changes, including dictionary selection; equal-value changes return early. `src/pages/AnnotationOperations.tsx:4432` connects that notification to `src/lib/annotation-history.js:35–37`, clearing future history without adding character-level undo entries. This satisfies spec line 124: “A new edit after undo removes the redo branch.” Supplied primary browser evidence covers both typed E and the selected dictionary template surviving attempted redo without an extra POST or server version change.
- **P3 contradictory final-submit help — ADDRESSED.** `src/components/CaptureAnnotationWorkbench.tsx:1657` now limits the button-only statement to reslicing and release, removing its contradiction with keyboard stage submission. This satisfies spec line 111: “Shortcut help reflects context, phase and availability.”
- **New breakage in the fix diff: None found.** The shared recoverable-item predicate preserves both callers’ previous conditions. Test changes remove obsolete source-shape constraints while retaining current behavioral coverage; history and authority regressions cover the repaired seams.
- **Evidence checked:** supplied diff `472c2447..bad89540`, fix report and primary acceptance records. Reported focused results: 64 passing, including history 9 and authority 9; lint/build pass. Reported final frontend results: 569 passing, 9 failures matching the documented baseline. No tests, git, browser or API commands were rerun in this review.
- **Out-of-scope observations: None.** Previously disclosed native-input, IME and precise BFCache-interleaving coverage limits remain unchanged.
- **Fix round: All three findings addressed; no new Critical/Important breakage found.**

View File

@ -0,0 +1,13 @@
# Spec review — 1a5c308bdac35789998b16b4deaee89ad603482d..472c2447
Reviewed the supplied 35-commit diff package against the parent specification, issues 01–11, task reports, four recorded rulings and controller acceptance evidence. Read-only review; no tests, browser/API operations, git commands or implementation edits were performed for this review.
1. **[P1] Fence discard/restore success by mutation identity.** `src/pages/AnnotationOperations.tsx:2129–2143` checks only the selected task ID after `setSliceDisposition` returns, then installs the response workspace, replaces the confirmed baseline and clears history. With a delayed response and A→B→A navigation (or account replacement on the same task), the old token has been invalidated but this branch still applies. Even `setDetail` rejecting an older version does not prevent the subsequent workspace writes; newer edits can be erased and later saved against the newer retained version. Apply the existing `scope.owns(token, currentContext)` fence before every success-side write. Spec §History: “Keep task, stage and ownership changes isolated from stale responses and old history.”
2. **[P2] Draft edits after undo leave stale redo available.** `src/components/CaptureAnnotationWorkbench.tsx:884–895` changes dictionary/text draft content without notifying history; the textarea uses this path at line 3167. After saving description B, undoing that save, and typing/replacing it with C, Esc then Ctrl/⌘+Shift+Z still restores B through `AnnotationOperations.tsx:2170–2198`, overwrites the server and closes the C draft. Only `record()` clears the redo branch (`src/lib/annotation-history.js:33–37`); neither draft path calls it or another invalidation operation. Invalidate redo on a substantive new draft change while retaining native text undo. Spec §History: “A new edit after undo removes the redo branch.”
3. **[P3] Remove contradictory button-only submission guidance.** `src/components/CaptureAnnotationWorkbench.tsx:1653` still says “重新切片、释放任务和最终提交只使用按钮。” This contradicts the newly displayed Ctrl/⌘+Enter stage action and makes the keyboard workflow misleading. Spec §Playback: “Shortcut help reflects context, phase and availability”; §Submission explicitly requires keyboard stage confirmation.
No additional scope creep identified. Existing disclosed physical-key, OS IME/native-beforeunload and precise BFCache-interleaving verification limits remain limitations, not newly inferred implementation failures. Final full-suite results are controller-owned.
**Result:** changes requested — 3 Spec findings (1 P1, 1 P2, 1 P3).

View File

@ -0,0 +1,23 @@
**Minor duplicated recovery eligibility — ADDRESSED.** `src/pages/AnnotationOperations.tsx:243` defines `isOwnedRecoverableAnnotationItem`; both entry/resume selection and recovery-card eligibility now call it, preserving the original project, account, task, status, and stage conditions.
## Critical
None.
## Important
None.
## Minor
None remaining within this fix scope.
The disposition changes consistently use the existing mutation ownership boundary before response-derived writes and before propagating an error after reconciliation. Draft redo invalidation extends the existing history module without adding per-character undo records; textarea patches and dictionary templates share the same change path. The help correction removes the obsolete button-only submission claim.
The retired tests remove obsolete source-shape or wording assertions; the retained executable split-name case still checks both resulting names. The workbench test formatting changes preserve inputs and expectations. These changes introduce no documented-standard breach or additional baseline smell warranting a finding.
Evidence bounds: read-only review of the supplied `472c2447..bad89540` fix package, implementation report, and recorded primary browser RED/GREEN evidence. No implementation edits, test execution, browser/API interaction, or expansion into a second whole-change review. Controller-reported focused/type/build results and the frontend rerun (578 total, 569 passed; 9 failures matching baseline) were considered as supplied evidence, not independently rerun. Template-variant browser completion remains owned by the controller and is not presumed here.
Out-of-scope observations: none added.
**Fix round: All findings addressed, no new Critical/Important breakage.** Standards: 0 remaining findings in the scoped fix; previous Minor resolved.

View File

@ -0,0 +1,21 @@
# Final Standards review
The change introduces useful boundaries for authoritative writes, stage history, and browser ownership. The local fixture script constrains its database target, and the recorded acceptance work respects the repository's local-only verification rule.
## Critical
None found.
## Important
None found on the Standards axis.
## Minor
- **Possible Duplicated Code — judgement call, not a documented-rule violation.** `src/pages/AnnotationOperations.tsx:3311` and `:3445` duplicate the owned, unfinished annotation-task predicate. Both contain `item.legacyTaskId && ["claimed", "in_progress", "rework"].includes(item.status) && ["annotation_combined", "semantic_annotation"].includes(item.currentStageId)`, with the same project and account conditions. One controls entry; the other controls recovery cards. A future eligibility change can make the displayed recovery choice disagree with the task actually resumed. Consider one local predicate with explicit project/user arguments; no wider restructuring is needed.
No documented-standard breach found against `AGENTS.md`, `CONTEXT.md`, `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, or ADR-0001. Domain distinctions and session/stage history boundaries are preserved in the reviewed design.
Evidence bounds: static review of the supplied fixed-baseline package (`1a5c308b...472c2447`), relevant repository rules, recorded acceptance evidence, and four execution rulings. No tests, browser interactions, API calls, implementation edits, or remote mutations performed. Full-suite results belong to the coordinating task. Potential stale disposition-response handling was referred to the Spec-axis coordinator rather than duplicated here. Physical-key/IME limits remain as already documented.
Standards: 0 hard breaches; 1 Minor heuristic finding.

View File

@ -0,0 +1,96 @@
# Final suite triage
Date: 2026-09-18. Baseline: `1a5c308bdac35789998b16b4deaee89ad603482d`, archived at `/tmp/droboticflow-keyboard-baseline-1a5c308b`. All commands used the repository's clean final/baseline launchers. No product code, tests, fixtures, Git state, services, company cluster, or BOS objects were changed by this triage. A single confirmed ignored generated Python cache file was later removed on explicit root authorization, as documented below.
## Frontend
The final full frontend suite ran once: **577 tests, 564 passed, 13 failed**. The eight files containing failures were then run once on the archived baseline: **45 tests, 36 passed, 9 failed**. All eight test files themselves are byte-identical between current checkout and baseline. Logs: `final-checks/frontend.log`, `final-checks/baseline-frontend-failed-files.log`.
```bash
bash .superpowers/sdd/annotation-keyboard-workflow/run-baseline-check.sh frontend-failed-files node --test tests/frontend/annotation-five-rules.test.mjs tests/frontend/capture-annotation-workbench.test.mjs tests/frontend/capture-automation.test.mjs tests/frontend/challenger-m5-empirical.test.mjs tests/frontend/fanyu-comment-followup.test.mjs tests/frontend/object-storage-reference-picker.test.mjs tests/frontend/plugin-page-subnav.test.mjs tests/frontend/project-ui-regressions.test.mjs
```
Four newly failing source-string assertions were reported to the root worker for review. This comparison establishes new **test failures**, not behavioral regressions; none of these source-string assertions is accepted as new behavior evidence. They have not been edited or retired by this triage.
| Test | Current failure and baseline result | Inspection |
|---|---|---|
| `annotation-five-rules.test.mjs:13`, slice names are selection-only and splits no longer append invented names | Baseline passes; current expects `name: current.name || ""` inside AnnotationOperations | Split logic moved to `src/lib/annotation-workbench.js`, where both children still use the exact name-preservation expression. Current page calls `splitSliceAtBoundary`; executable split tests cover child names. |
| `capture-annotation-workbench.test.mjs:85`, Capture workbench follows the confirmed two-phase interaction | Baseline passes; current blanket forbidden-copy regex matches 上一片 / 下一片 | Explicit review navigation introduces these controls. Worker must assess the obsolete assertion against the approved review workflow. |
| `fanyu-comment-followup.test.mjs:62`, v5.8 submits a combined revision and uses strict whole-package acceptance | Baseline passes; current old exact submit guard no longer matches | Current `submitCombined` retains owner/nonempty-slice checks, uses `combinedSubmissionLocked`, and adds draft/phase guards. A source-text guard match does not verify authoritative submission behavior. |
| `plugin-page-subnav.test.mjs:25`, only pages with real internal views render secondary navigation | Baseline passes; current global regex forbids h1 followed by paragraph | The new dedicated work-page header at AnnotationOperations line 3503 includes an h1 and project/status paragraph. PageSubnav remains present; this is **not** missing navigation. Worker must review this layout assertion. |
Nine original failures reproduced on baseline:
- `capture-automation.test.mjs:5`: automation keeps advanced settings collapsed and separates saving from listener activation.
- `capture-automation.test.mjs:22`: project workflow exposes complete Capture automatic processing without a scan node.
- `capture-automation.test.mjs:65`: project exposes only its selected dictionary descriptions.
- `challenger-m5-empirical.test.mjs:42`: ProjectDetail.tsx has 运行历史 tab and resets pagination cursors on modeFilter change.
- `fanyu-comment-followup.test.mjs:55`: workflow run input renders a per-run automatic HandPose switch.
- `object-storage-reference-picker.test.mjs:33`: workflow default and run input surfaces use the reusable BOS browser.
- `plugin-page-subnav.test.mjs:91`: layout removes the redundant product header and keeps only a compact health control.
- `plugin-page-subnav.test.mjs:108`: project detail separates released and debug workflows and opens released run history.
- `project-ui-regressions.test.mjs:5`: creation exposes Capture mode and projects can reference released templates.
## Formatting and Go lint
Full Prettier check reports **54 files**. Of those, **53 are untouched and byte-identical to the baseline**. The sole task-modified flagged file is `tests/frontend/annotation-workbench.test.mjs`; a focused baseline check also reports that file unformatted. Thus all 54 are pre-existing file-level formatting failures, although the edited file's new content should still be reviewed/formatted by its owner. No broad formatter was run.
```bash
bash .superpowers/sdd/annotation-keyboard-workflow/run-baseline-check.sh format-changed-file node node_modules/prettier/bin/prettier.cjs --check tests/frontend/annotation-workbench.test.mjs
```
`gofmt -l cmd internal` reports only `internal/api/annotation_operations_test.go`. This file is untouched by the task and byte-identical to the baseline. The `lint:go` failure is original formatting debt. The root worker owns Go test coverage and environment rerun; this triage did not rerun Go.
## Python environment and run
Initial `python.log` failed before collection because `/usr/local/bin/python3` has no pytest. The existing repository `.venv/bin/python3` is Python **3.13.2** and has **pytest 9.1.1**, **PyYAML 6.0.3**, **cv2 5.0.0**, and **numpy 2.5.2**. No installation was required. The root worker was promptly given this interpreter path for Go subprocesses as well.
The first collected Python attempt used the sandbox after resolving the interpreter blocker:
```bash
bash .superpowers/sdd/annotation-keyboard-workflow/run-final-check.sh python-venv env PATH="/Users/d-robotics/Desktop/fanyu/droboticflow/.venv/bin:$PATH" npm run test:python -- -p no:cacheprovider
```
It collected **650 tests**, but sandbox denial of temporary localhost HTTP servers contaminated the result: **45 failed, 625 passed, 3 skipped** in 199.07s. The 23 extra results are unittest subtest failure records. This is **not a valid final regression comparison** and those 45 failures are not labeled baseline debt. Logs: `final-checks/python-venv.log` and `.exit`.
The root worker authorized a corrected environment run outside the sandbox, with the same cleared credentials and existing virtual environment; automatic approval accepted local loopback access. **Corrected full result: 27 failed, 643 passed, 3 skipped in 105.26s**. All 18 localhost-related failures disappeared. The seven failed methods were then run once on the archived baseline with the same virtual environment and permissions: **25 failed, 3 passed in 2.04s**. Subtest reporting explains why these totals exceed the collected method count. Logs: `python-venv-local.*`, `baseline-python-failed-tests.*`; exact failed node IDs: `python-failed-nodeids.txt`.
The 25 identical baseline failures comprise:
- WiLoR full-video chunk test: mocked splitting does not create `_video_chunks`, but cleanup calls `shutil.rmtree` on it (1).
- Acceptance partial-chunk-body test: retry exhausts the one-response FakeOpener (1).
- Generated video-face-blur documentation mismatch (1 subtest).
- Existing release/source-tree hash drift for ten operator directories across repository-manifest and release-manifest checks (20 subtests).
- Generated image-contract and repository-manifest checks blocked by that existing release hash drift (2).
The only current-only failures are the two `json_to_csv` source-hash subtests. They are **local cache contamination, not changed source**: current `operator-repos/builtin/json_to_csv/src/__pycache__/operator.cpython-313.pyc` is absent from the archive; all other files in that directory are byte-identical. That cache's modification time is **2026-09-15 08:25:14**, before this task. The hash helper recursively includes all files except release.json/repository.json, so it includes this cache. Recomputing the current and baseline hash with only `__pycache__` excluded gives the same expected release digest: `5592e84105f53b945cc743d0c4f7f3419257c40d19e4830878d4602107efad7f`. On explicit root authorization, this single generated cache file was verified untracked (`git ls-files --error-unmatch` fails) and ignored (`.gitignore:14:__pycache__/`), then removed. Its path, timestamp, and SHA-256 were preserved in `final-checks/json-to-csv-cache-evidence.txt`; all initial failure logs remain intact. Only the two affected test methods were rerun under the corrected clean environment: **20 failed, 2 passed in 0.53s**, with the exact same 20 subtest failures as those methods on baseline and **no json_to_csv failures**. Log: `final-checks/python-cache-cleaned-hashes.log`. This proves the two additional failures were local cache contamination. No full suite was rerun after cleanup. No Python product regression was identified.
Baseline command: `run-baseline-check.sh python-failed-tests env PATH="/Users/d-robotics/Desktop/fanyu/droboticflow/.venv/bin:$PATH" /Users/d-robotics/Desktop/fanyu/droboticflow/.venv/bin/python3 -m pytest -p no:cacheprovider`, followed by exactly the seven node IDs in `final-checks/python-failed-nodeids.txt`. These are the WiLoR and acceptance methods, docs-generation method, two operator hash-check methods, and two generated-contract methods above. No Python suite source or operator-runner source differs from baseline; only the task-specific local fixture preparation shell script changed under scripts.
## Kubernetes validation
The original `k8s:validate` returned exit 1 because even `kubectl create --dry-run=client --validate=false` attempted resource discovery at `http://localhost:8080/api`, which was unavailable. The clean environment used `KUBECONFIG=/dev/null` and `DROBOTICFLOW_DEPLOY_ENV_LOADED=local-validation`. The earlier readiness statement that this kubectl invocation required no server was incorrect on the installed client. **The kubectl validation remains blocked**, not passed.
A separate fully local structural alternative passed: render with the same four `*:validate` image inputs and deployment-loader sentinel, then `.venv/bin/python3` with `yaml.safe_load_all`. It checked each document is a map, has nonempty apiVersion/kind/metadata.name, and has a unique resource identity. **22 documents** parsed: 1 Namespace, 3 ServiceAccounts, 2 Roles, 2 RoleBindings, 1 ClusterRole, 1 ClusterRoleBinding, 1 ConfigMap, 4 Services, 4 Deployments, 3 PodDisruptionBudgets. Log: `final-checks/k8s-structural.log`, exit 0.
This alternative does not perform Kubernetes schema validation, discovery, admission checks, or any cluster access. No real kubeconfig was used.
## Remaining final checks owned by root
Checked against the completed logs, not rerun by this triage:
| Gate | Result |
|---|---|
| Corrected Go package suite (`go-with-local-python`) | 13 tested packages pass, 2 packages have no tests; internal/api has 60 top-level failures. |
| Focused baseline Go failures (`baseline-go-failed-cases`) | Exact same 60 failure names, no current-only or baseline-only names. Original debt. |
| Rust workspace tests | 25 tests pass, zero failures; exit 0. |
| Rust formatting, Clippy, release build | All exit 0. |
| Web + Go build | Exit 0. |
| Web type check and script syntax checks | Both exit 0. |
The initial Go run had an ignored Rust-target traversal race and used system Python lacking cv2/numpy. Root corrected its environment and covered all actual Go source packages under cmd/internal; use the corrected logs above as evidence.
## Outstanding decisions
The four newly failing frontend source-string assertions require root/worker review; no source assertion may replace browser or executable behavior acceptance. The changed frontend test file remains flagged by Prettier as it was on baseline. The original kubectl validation is still blocked; the local YAML structural check is a narrower successful alternative. This report does not claim the entire repository suite is green.

View File

@ -0,0 +1,40 @@
# 最终验证结果(2026-09-18)
代码最终修正:`bad89540`;实施前基线:`1a5c308bdac35789998b16b4deaee89ad603482d`。11票按顺序完成实施、逐票审查与本地验收;最终双轴审查发现的问题已一次修正并分别复审通过。**不是全仓测试全绿**,既有失败按相同用例在基线复现并单列。
| 检查 | 最终结果 | 解释 |
| --- | --- | --- |
| 前端全量 | 578项:569通过、9失败 | 失败名称集合与基线完全一致;本次新增4条过时源码断言已审查退役,相关行为由浏览器/API与公开函数测试覆盖 |
| Go全部实际源码包 | 13个有测试包通过、2个无测试包;internal/api失败 | 60个失败顶层用例在基线逐一复现,名称集合完全一致;本次新增HTTP测试通过 |
| Python全量 | 正确环境下643通过、27失败、3跳过 | 25个失败记录在基线复现;另外2项来自既有未跟踪pyc缓存,移除唯一确认缓存后,仅重跑受影响方法,2项消失,其余与基线一致;未将局部复验冒充新全量结果 |
| Rust工作区测试 | 25通过,0失败 | 离线锁定依赖 |
| Rust格式、Clippy、release构建 | 全部通过 | 没有修改Rust代码 |
| TypeScript类型检查 | 通过 | 最终修正后再验 |
| Web及Go程序构建 | 通过 | 最终修正只涉及前端,再次Web构建通过 |
| 脚本语法 | 通过 | 本次夹具脚本另做bash语法检查 |
| 全仓Prettier | 初次54文件告警 | 53文件未修改且与基线相同;本次修改的第54文件已格式化,最终10个修正文件检查通过 |
| Go格式 | 1个旧文件不合规 | internal/api/annotation_operations_test.go 未被本次修改,基线相同 |
| Kubernetes原命令 | 未通过 | 即使客户端dry-run也尝试localhost:8080资源发现;未使用真实集群配置。替代本地YAML结构检查22份文档通过,不等价于集群验证 |
初次系统Python没有pytest,初次Go缺少cv2/numpy且扫描并行Rust临时产物,另一次Python沙箱禁止本机临时HTTP服务器;均记录为环境失败。纠正为现有.venv、清洁环境与允许本机回环后复验。所有真实数据库操作只在本地keyboard-acceptance项目;不连接公司集群或BOS进行写入。
## 浏览器与API证据
- C原地切分及跨片继续播放;双目硬件逐帧;B复查、V回工作点、跨片草稿与首尾导航。
- N/N或Enter、F/D字典、一次Esc返回、显式保存;输入框不触发数据快捷键。
- 切片/描述撤销重做、拖动一步、批量无效一步、删除恢复、CAS拒绝、成功响应丢失与未知回读。
- 生成/送检两步确认,processing不跳阶段;混合留空/无效/舍弃与全留空实际送检。两版产物清单各21/21哈希与大小核对。
- 独立工作页完整链路,刷新显式继续,双页单活,账号/项目隔离。
- 连续pool01→pool04→pool02,原编号跨关页恢复,停止后不领取,未知提交暂停,空池暂停。此前8条隔离任务均真实送检;最后额外2条回归任务保留已保存状态供检查。
- 最终P1真实RED:迟到舍弃覆盖较新恢复;GREEN:旧响应到达后UI/API保持v7保留状态。
- 最终P2真实RED:撤销后新草稿被旧重做覆盖;GREEN:文字与字典替代草稿均保留且无新增POST。
## 验证边界
内嵌浏览器无法直接投递Ctrl+X和Shift+Delete的keydown,使用公开键位解析测试及相同鼠标处理器的浏览器/API证据;Mac Shift+Backspace已实测。真实系统中文输入法组合、原生文字撤销恢复和部分原生beforeunload交互未完整验证。精确Web Lock待处理回调/BFCache竞态采用控制流审查及补充测试,一般离开/返回已实测。不将这些覆盖限制写成产品已失败,也不宣称所有OS组合都已实测。
既有DEP0205及大于500kB包警告仍在。全仓基线债务未在本任务范围内修复。详细用例对照见final-suite-triage.md,逐票行为见acceptance-evidence.md和acceptance-matrix.md。
## 原始记录
清洁环境启动器、原始日志、退出码、差异包与故障代理记录归档在本仓未跟踪目录 `local-data/verification/annotation-keyboard-workflow/`;本目录保留可提交的结果、审查和验收说明。原始前端失败日志较大,含源码断言展开,未纳入版本控制。

View File

@ -0,0 +1,144 @@
# Local annotation keyboard acceptance fixtures
Prepared on 2026-09-17 for the localhost replica only.
## Scope and safety
- Creator: `scripts/local/prepare-annotation-keyboard-fixtures.sh`
- Target guard: the script accepts only Docker container `fanyu-mongo-restore`, database `drobodata-fanyu`, with Mongo published exactly at `127.0.0.1:27018`.
- The default `apply` action creates the fixture once and leaves an existing fixture unchanged. `--verify` is read-only. `--repair-metadata` updates only the isolated project's dictionary selection, three local slice labels, and isolated task metadata: action-label snapshots plus right-video references. The older `--repair-dictionaries` spelling remains an alias. `--recreate` is the only reset action and deletes only records with the `keyboard-acceptance` IDs or the fixture project ID.
- Source snapshot records are read and cloned. The script never updates source projects, tasks, runs, users, media, company services, or BOS.
- The cloned run retains the already-wired local workspace paths under `local-data/workspace`; its project, workflow, run, batch, task, item, attempt, membership, and workflow-instance IDs are isolated.
Commands:
```bash
scripts/local/prepare-annotation-keyboard-fixtures.sh
scripts/local/prepare-annotation-keyboard-fixtures.sh --verify
# Repair dictionaries and dual-video task metadata without touching human items:
scripts/local/prepare-annotation-keyboard-fixtures.sh --repair-metadata
# Intentional fixture-only reset:
scripts/local/prepare-annotation-keyboard-fixtures.sh --recreate
```
## Shared fixture graph
| Record | ID |
| --- | --- |
| Project | `project-keyboard-acceptance` |
| Workflow | `workflow-keyboard-acceptance` |
| Run | `run-keyboard-acceptance` |
| Human batch | `human-batch-keyboard-acceptance` |
The project clones the source project's four role memberships, including annotator, quality reviewer, and acceptance reviewer access. It reuses the published production annotation template and links all 22 active organization action labels to the project. Each isolated task carries the corresponding 22-entry label snapshot, matching the worker's normal task-creation contract for the description picker.
The project also owns three local active slice labels through the existing `annotationLabels` and `projectAnnotationLabels` schema: `切片 001`, `切片 002`, and `切片 003`. These entries use `keyboard-acceptance` IDs and are enabled only for the isolated project.
Every isolated annotation task also carries `rightArtifactId` and `rightSourceVideo` derived from the cloned run's actual locally wired right-camera artifact. This lets the browser select the authorized human-item right stream and render both camera players.
## Direct browser and API fixtures
All browser URLs are relative to `http://127.0.0.1:5173`. All API URLs are relative to `http://127.0.0.1:3001`.
| Purpose | Human item | Annotation task | Browser URL |
| --- | --- | --- | --- |
| Primary annotation editing | `human-item-keyboard-acceptance-annotate-primary` | `annotation-task-keyboard-acceptance-annotate-primary` | `/plugins/annotation-qa/items/human-item-keyboard-acceptance-annotate-primary` |
| Delayed-response/task-switch isolation | `human-item-keyboard-acceptance-annotate-delayed` | `annotation-task-keyboard-acceptance-annotate-delayed` | `/plugins/annotation-qa/items/human-item-keyboard-acceptance-annotate-delayed` |
| Slicing workflow | `human-item-keyboard-acceptance-slice-primary` | `annotation-task-keyboard-acceptance-slice-primary` | `/plugins/annotation-qa/items/human-item-keyboard-acceptance-slice-primary` |
| Random pool 1 | `human-item-keyboard-acceptance-pool-01` | `annotation-task-keyboard-acceptance-pool-01` | `/plugins/annotation-qa/items/human-item-keyboard-acceptance-pool-01` after claim |
| Random pool 2 | `human-item-keyboard-acceptance-pool-02` | `annotation-task-keyboard-acceptance-pool-02` | `/plugins/annotation-qa/items/human-item-keyboard-acceptance-pool-02` after claim |
| Random pool 3 | `human-item-keyboard-acceptance-pool-03` | `annotation-task-keyboard-acceptance-pool-03` | `/plugins/annotation-qa/items/human-item-keyboard-acceptance-pool-03` after claim |
| Random pool 4 | `human-item-keyboard-acceptance-pool-04` | `annotation-task-keyboard-acceptance-pool-04` | `/plugins/annotation-qa/items/human-item-keyboard-acceptance-pool-04` after claim |
Useful readback endpoints:
```text
/api/human-items/<human-item-id>
/api/plugins/annotation-qa/tasks/<annotation-task-id>?view=summary
/api/plugins/annotation-qa/tasks/<annotation-task-id>/frame-timeline?camera=left&encoding=compact
/api/human-items/<human-item-id>/subject-content
/api/human-items/<human-item-id>/subject-content?side=right
```
The annotation fixtures are owned, claimed `annotation_combined` tasks in the `annotate` phase. Each has three contiguous exact-frame slices covering `0–120.1`, `120.1–216.06666666666666`, and `216.06666666666666–412` seconds. One saved `鲜食处理` description covers exact frame boundaries `30–60` seconds inside the first slice, leaving gaps at `0–30` and `60–120.1` for interval creation and multi-gap invalid-marking checks.
The slicing fixture is owned and claimed in the `slice` phase with the same three partitions and no saved descriptions. The four pool fixtures are unowned `ready` slicing tasks for later random-claim and continuous-work flows.
Project-scoped annotation page:
```text
/plugins/annotation-qa/workflows/workflow-keyboard-acceptance/annotate?projectId=project-keyboard-acceptance&workflowId=workflow-keyboard-acceptance&runId=run-keyboard-acceptance
```
## Verification evidence
- `bash -n scripts/local/prepare-annotation-keyboard-fixtures.sh`: passed.
- `scripts/local/prepare-annotation-keyboard-fixtures.sh --verify`: one project, workflow, run, batch, and workflow instance; seven tasks, items, and stage attempts; four project members.
- Re-running default `apply`: reported `fixture already exists; left unchanged`.
- Authenticated public API item readback: primary item is `claimed`, stage `annotation_combined`, version `1`, phase `annotate`, with three slices and one saved description at `30–60` seconds.
- Authenticated task summary: `clipStart=0`, `clipEnd=412`, `sourceDurationSeconds=412`, and `coverageEndSecond=412`.
- Local `ffprobe`: left media duration `412.000000`; right media duration `411.966667`.
- Public frame-timeline readback: hardware-frame contract, range `0–412`, 12,360 left frames, 12,359 right frames, origin timestamp `1123001701`, common coverage end timestamp `1535002108`.
- Uncompressed public frame-timeline readback proved description boundaries: `30` seconds maps to timestamp `1153001731`; `60` seconds maps to `1183001746`; first slice end `120.1` maps to `1243101829`.
- Public media range readback through the human-item endpoint returned HTTP `206` with 1,024 bytes for both left and right video.
- The fixture project appears in the annotator's public claim-project list, and public claim-count readback returns four ready tasks.
- The original fixture creator stored the saved description timestamps using mongosh's displayed `{high,low,unsigned}` form. A browser confirmation correctly exposed that these were invalid JSON for the API's `int64` fields. The creator and both annotation fixture records were corrected in place to numeric timestamps without a reset or version change. A normal browser confirmation then succeeded, and recovery after a deliberately dropped successful response also reconciled correctly.
- Browser confirmations advanced the primary item's version. Conflict helper verification read authoritative version `4`; an otherwise-valid request using version `3` returned HTTP `409` with `code=version_conflict`, without changing the item. A later intentional public API slice reset advanced the live primary item to version `6`, phase `slice`, with one workspace slice.
- Dictionary repair preserved that live primary state exactly: version `6`, phase `slice`, one workspace slice, and no saved descriptions.
- Authenticated project API readback reports 22 enabled action IDs and three enabled slice items named `切片 001`, `切片 002`, and `切片 003`. Authenticated task-summary readback reports a 22-entry description `labelSnapshot`.
- Metadata repair populated right-video fields on all seven isolated tasks while a full EJSON comparison proved the primary human item was byte-for-byte unchanged at version `6`.
- Authenticated task-summary readback exposes the cloned run's actual right artifact and run-content URL. Public compact right-frame-timeline readback reports camera `right`, 12,359 right frames, 12,360 left frames, and common range `0–412`. Authorized right subject-content range readback returned HTTP `206` with 1,024 bytes.
The run-artifact content URL itself returns `403` to an annotator, as expected for run-level access. Browser playback uses the authorized human-item subject-content endpoints above; both were verified.
## Credential-silent authenticated API helper
This helper derives the local annotator identity from the fixture and the local-only password from `docs/HANDOFF.md`; it does not print either value. Login sets both the session cookie and the CSRF cookie. Mutating requests must echo the CSRF cookie in `X-Droboticflow-CSRF-Token`.
```bash
KB_COOKIE=$(mktemp)
KB_ITEM=human-item-keyboard-acceptance-annotate-primary
KB_TASK=annotation-task-keyboard-acceptance-annotate-primary
KB_UID=$(docker exec fanyu-mongo-restore mongosh --quiet 127.0.0.1:27017/drobodata-fanyu \
--eval "print(db.humanItems.findOne({id:'$KB_ITEM'}).assignedUserId)" | tail -1)
KB_EMAIL=$(docker exec fanyu-mongo-restore mongosh --quiet 127.0.0.1:27017/drobodata-fanyu \
--eval "print(db.users.findOne({id:'$KB_UID'}).email)" | tail -1)
KB_PASSWORD=$(sed -n 's/.*全部 `\([^`]*\)`.*/\1/p' docs/HANDOFF.md | head -1)
jq -nc --arg email "$KB_EMAIL" --arg password "$KB_PASSWORD" \
'{email:$email,password:$password}' | \
curl -fsS -o /dev/null -c "$KB_COOKIE" -H 'Content-Type: application/json' \
--data-binary @- http://127.0.0.1:3001/api/auth/login
KB_CSRF=$(awk '$6=="droboticflow_csrf"{print $7}' "$KB_COOKIE")
# Read the authoritative item/version.
KB_GET=$(mktemp)
curl -fsS -b "$KB_COOKIE" "http://127.0.0.1:3001/api/human-items/$KB_ITEM" -o "$KB_GET"
jq '{version:.item.version,segments:.item.subject.payload.annotationWorkspace.segments}' "$KB_GET"
# Build an otherwise-valid request using the previous version and prove 409.
KB_STALE=$(mktemp)
jq '.item as $i | $i.subject.payload.annotationWorkspace as $w |
{version:($i.version-1),sliceSegments:$w.sliceSegments,operations:($w.operations//[]),
segments:$w.segments,statuses:$w.statuses}' "$KB_GET" > "$KB_STALE"
curl -sS -w '\nHTTP %{http_code}\n' -b "$KB_COOKIE" \
-H "X-Droboticflow-CSRF-Token: $KB_CSRF" -H 'Content-Type: application/json' \
--data-binary "@$KB_STALE" \
"http://127.0.0.1:3001/api/plugins/annotation-qa/tasks/$KB_TASK/annotation-confirmations"
rm -f "$KB_COOKIE" "$KB_GET" "$KB_STALE"
unset KB_PASSWORD KB_EMAIL KB_CSRF
```
## Slice generation and worker requirements
The two annotation fixtures already contain server-saved slice and annotation workspaces, so ticket acceptance can begin without generating slices. The slicing fixture is intentionally before generation so submission behavior remains testable.
With the normal local environment, leave `ANNOTATION_PROCESSOR_MODE` unset. The API then starts slice materialization in its in-process background goroutine after the public confirmation request returns `202`. It requires:
- API started from `scripts/local/env-local-snapshot.sh` so Mongo is `127.0.0.1:27018` and `WORKSPACE_MOUNT_PATH` is the repository's local workspace;
- local left/right video, PTS CSV, and IMU CSV paths already wired in the cloned run;
- local `ffprobe`/`ffmpeg` and workspace write access.
If the API is explicitly started with `ANNOTATION_PROCESSOR_MODE=external`, a second process must run the same binary with `ANNOTATION_PROCESSOR_MODE=processor`; its readiness endpoint is port `3003` at `/ready`. The processor must receive the same snapshot Mongo and workspace environment. No external worker is needed in the current default local setup.
Generation/handoff was not invoked while preparing fixtures because it would consume or advance the slicing fixture. The public frame-timeline and both local media streams were read back successfully, which verifies the source inputs needed before that mutation.

View File

@ -0,0 +1,95 @@
# Ticket 08 actual local materialization evidence
Read-only observation on 2026-09-17. The controller triggered the real `slice-primary` generation through the browser; the initial observed API state was item version `7` in `processing/validating` at `2026-09-17T15:15:29Z`. The controller subsequently completed annotation submission and confirmed the terminal public state: item version `14`, stage `quality_review`, item status `ready`, and task status `pending_quality`. This observer did not call any task or stage API, mutate fixture state, or run tests.
## Terminal filesystem result
The expected revision appeared at:
```text
local-data/workspace/system/runs/run-keyboard-acceptance/human-materializations/
human-item-keyboard-acceptance-slice-primary/
annotation-task-keyboard-acceptance-slice-primary/
revision-000002/
```
The final `revision-manifest.json` was present by `2026-09-17T15:16:01Z` and declares:
- schema `droboticflow.slice-materialization/v3`
- status `materialized`
- revision `2`
- task `annotation-task-keyboard-acceptance-slice-primary`
- item `human-item-keyboard-acceptance-slice-primary`
- three slices with contiguous full-common-range coverage from `0` to `412` seconds
- no gaps or overlaps
- reconstructed totals of 12,360 left frames, 12,359 right frames, and 821,928 IMU rows
The revision directory occupies approximately 338 MiB. It contains one manifest plus 21 payload files: each of the three slice directories has `annotation.json`, left/right MP4, left/right PTS CSV, IMU CSV, and `synchronized-slice.json`.
## Integrity verification
The actual manifest is 7,944 bytes with SHA-256:
```text
14a677ff780dcc40c58c4eb54d51118969362df2207e7c77fae3386d2371bd25
```
A local read-only verifier loaded every manifest `files` entry, read the corresponding file, recomputed its SHA-256 and byte count, and compared both values to the manifest. Results:
```text
manifest payload entries checked: 21
actual payload files: 21
missing or extra files: 0
SHA-256 mismatches: 0
byte-count mismatches: 0
```
This verifies the real files rather than only the manifest metadata. Each slice's `annotation.json` is valid JSON using `hardware-frame-v1`, half-open timestamp windows, and empty action/description arrays, as expected immediately after slicing materialization.
## Delivery semantics
The manifest preserves the requested keep/discard decision exactly:
| Slice | Range (seconds) | Disposition | Evidence |
| --- | ---: | --- | --- |
| `切片 001` | `0–120.1` | `keep` | no discard evidence |
| `切片 002` | `120.1–216.06666666666666` | `keep` | no discard evidence |
| `切片 003` | `216.06666666666666–412` | `discard` | reason `本地键盘验收:保留舍弃审核证据`, recorded at `2026-09-17T15:15:14.203804Z` |
The aggregate delivery selection is two kept slices covering `216.06666666666666` seconds and one discarded slice covering `195.93333333333334` seconds.
Read-only `ffprobe` confirmed all six generated videos are H.264 and readable:
| Slice | Left duration / frames | Right duration / frames |
| --- | --- | --- |
| `001` | `120.100000s` / 3,603 | `120.100000s` / 3,603 |
| `002` | `95.966667s` / 2,879 | `95.933333s` / 2,878 |
| `003` | `195.933333s` / 5,878 | `195.933333s` / 5,878 |
The left/right difference in slice 002 matches the source's one-frame camera-count difference and the manifest's PTS row counts.
## Final annotation-submission revision
The completed submission produced a second real terminal directory, `revision-000003`, with its final manifest written by `2026-09-17T15:18:25Z`. It remains a three-slice `materialized` manifest with the same two-kept/one-discarded delivery selection.
The actual revision 3 manifest is 7,945 bytes with SHA-256:
```text
1f8c2a06a8b6c9d906b2fd7bac9675a6658b44c63927ac70d82c192081f2a14c
```
The same read-only verifier checked all 21 revision 3 payload entries against the corresponding files: zero missing/extra files, SHA-256 mismatches, or byte-count mismatches. Comparing revisions 2 and 3 showed that all media, PTS, IMU, and synchronization hashes are identical for every slice. Only annotation evidence changed for slices 001 and 002; slice 003's annotation hash and discard evidence remained identical.
Final semantic evidence:
- `切片 001` is kept. It contains one valid manual description, `第八票两步提交实测:保留前后语义空白`, from `0.03333333333333333` to `0.06666666666666667` seconds relative to the slice. The surrounding `0–0.033333...` and `0.066666...–120.1` gaps are the two controller-confirmed blank ranges.
- `切片 002` is kept. Its single `无效片段` entry spans the entire slice window, timestamp `1243101829–1339068597`, with confidence `0`.
- `切片 003` remains discarded, has no actions/descriptions, and retains reason `本地键盘验收:保留舍弃审核证据` from the slicing revision.
This final file evidence agrees with the controller's terminal API readback of `quality_review / ready / pending_quality` at item version 14.
## Runtime observation
After the final manifest appeared, the read-only process list had no active `ffmpeg` or `ffprobe` worker. The local API remained alive: the `go run ./cmd/api` parent was present and the compiled API process was still listening on TCP port 3001. No restart or signal was issued.
Both filesystem revisions are terminal and internally consistent. The controller independently supplied the final browser/API status confirmation.

View File

@ -0,0 +1,165 @@
# SDD ledger — plan: /Users/d-robotics/Desktop/fanyu/droboticflow/.superpowers/sdd/annotation-keyboard-workflow/annotation-keyboard-workflow.md
Baseline: 1a5c308bdac35789998b16b4deaee89ad603482d
Branch: feature/local-dev-toolkit
Ruling: Keep current clean feature checkout — implement explicitly requires current branch and local replica uses it — cost if wrong: changes require relocation.
Ruling: Focused tests per ticket; full suite once at end — implement requirement overrides generic per-agent full checks — cost if wrong: unrelated integration failure found later.
| Task | Self consistency |
| --- | --- |
| 1 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 2 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 3 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 4 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 5 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 6 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 7 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 8 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 9 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 10 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| 11 | Public behavior criteria consistent with implementation; composite scenario limited to this ticket scope. |
| Shared tasks | Producer / consumer | Finding |
| --- | --- | --- |
| 1 → 2 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 3 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 4 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 5 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 6 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 7 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 8 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 9 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 1 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 3 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 4 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 5 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 6 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 7 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 8 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 9 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 2 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 3 → 4 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 3 → 5 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 3 → 6 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 3 → 7 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 3 → 8 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 3 → 9 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 3 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 3 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 4 → 5 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 4 → 6 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 4 → 7 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 4 → 8 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 4 → 9 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 4 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 4 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 5 → 6 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 5 → 7 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 5 → 8 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 5 → 9 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 5 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 5 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 6 → 7 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 6 → 8 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 6 → 9 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 6 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 6 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 7 → 8 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 7 → 9 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 7 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 7 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 8 → 9 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 8 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 8 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 9 → 10 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 9 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
| 10 → 11 | Existing task/workbench coordination evolves in numeric order; later task consumes committed interface. | Sequential edits; no contradictory requirement. |
Task 1: starting; BASE 1a5c308bdac35789998b16b4deaee89ad603482d
Task 1: implementer /root/implement_01 (gpt-5.6-sol high).
Support: /root/local_fixture owns local fixture setup only; no commits until coordinated.
Task 1: implemented commit18139a00; /root/review_01 reviewing spec and quality.
Task 1 browser: normal save version2, dropped200 response reconciled version3, concurrent public API write version4 preserved after409 description and reset rejection. All local.
Task 1: fix round1/5 dispatched /root/implement_01; Important passive-effect invalidation gap; FIX_BASE18139a00. Browser ordinary/long-delay gates passed, integration same-turn gap must close.
Task 1: fix round1/5 (1 addressed,0 open; commits18139a00..61703abc).
Task 1: complete (commits1a5c308b..61703abc, review clean). Browser/API gate recorded in acceptance-evidence.md.
Task 2: starting; BASE9b0fdd419f6ff3c46e31dd723894697096e64235. Task01 acceptance/docs fixture commit9b0fdd41.
Task 2 implementer: /root/implement_02 (gpt-5.6-sol high).
Task2 code commits015c86de,4a6affea,d16e41b9. Root browser found and worker fixed continued-C target, frameclamp, hiddenboundaryerror before formal review. Reviewer /root/review_02 reviewing9b0fdd41..d16e41b9.
Task 2: complete (commits9b0fdd41..d16e41b9, review clean). All browser gatespassed;40focused+lint.
Task 3: starting; BASEc8957121246ac52091a721a2c46f6c546b95ebde. Task02 metadata commitc8957121.
Task3 code commit94ba5fa2; root browser/API coregates passed. Reviewer /root/review_03 evaluating c8957121..94ba5fa2. NativeOSIME and embedded nativeundo restoration unverified, parser noninterception covered; carry into final limitations.
Task3 fixround1/5 dispatched originalimplementer; nativeControlCtrl/CommandEnter interceptedassave beforeguard. FIX_BASE94ba5fa2. Coveringtest annotation-shortcuts.test.mjs+lint:web.
Task3 fixround1/5 (1 addressed,0 open;94ba5fa2..350448f2).
Task 3: complete (commitsc8957121..350448f2, review clean). BrowsernativeControlCtrlEnter noPOST, publicAPIv3unchanged.
Task 4: starting; BASE9027a79b9b1e3c79f3b62b5e4c4de178eda6b587.
Task4 implementer /root/implement_04 (gpt6astrahigh; architecture/per-slice coordination). RootREDconfirmcombinationnavmissing/draftlost recorded.
Support materializationreadiness complete: publicAPIgeneration canproceed localinprocessffmpeg withoutfixturerepair. See materialization-readiness.md.
Task4 rootbrowser found BackthroughDashboard->Annotation workflow losesdraft withoutconfirmation at52263727; reviewer04 confirmsImportant. Originalworkerfixing.
Ruling: Use supported router-level navigation blocking with a minimal createBrowserRouter/RouterProvider wrapper conversion — page-level popstate interception failed real Back draft protection and BrowserRouter provides no blocker — cost if wrong: app-wide route integration regressions require rework/revert; focused routing checks and final full suite must assess.
Task4 formalreviewreportsoneImportantBackdraftloss. Fixround1/5 active originalworker, FIX_BASE52263727; router-levelblocker Rulingabove.
Task4 browserBnaturalendstop0.133333bothpaused; Vcurrentpartitionafterdelete resolves0.233333correctly. Existingmouse-deletefocusBODY carried toTask05 explicitly, notsilentdiscard.
Task4 fixround1/5 (1 addressed,0 open;52263727..d4cd2b18).
Task 4: complete (commits9027a79b..d4cd2b18, review clean). Browser/APIgatesrecorded; nativebeforeunloadlimitationexplicit.
Task 5: starting; BASEa5932e8050358328ea60e7a2070e9a8d06e4089a.
Task5 implementer /root/implement_05 (gpt6astrahigh, shared stagehistory architecture).
Task5 minor(deferred): inherited build DEP0205/chunkwarnings; finalreviewretainasbaselineverificationdebt.
Task 5: complete (commitsa5932e80..e09ad03f, review clean). Alllocalbrowsergatespassed; actualstagegeneration/submitboundary integrated08. Asyncpersistedrestoreauthorityfence delegated06.
Task 6: starting; BASEb913bff0c73712d9548a3a68df9de4d660ff7e6b.
Task6 implementer /root/implement_06 (gpt6astrahigh). RootRED Nstartundo+savedundomissing, APIbaselineadvancev4fromapprovedtestsave. Seeacceptance-evidence.
Task6 fixround1/5 originalworker; Important revision-backed confirmedbaseline falls back to mutable local workspace. FIX_BASEe59286cb. Rootbrowserpausedforfix.
Task6 fixround1/5 (1 addressed,0 open; e59286cb..55a81c55). Revision-backed browser firstsaveundo v2->v3original30–60 PASS.
Task6 fixround2/5 (1 addressed,0 open;55a81c55..9859fa8d). MousebatchBODYfocus fixed;directCtrlZv8->v9 PASS.
Task 6: complete (commitsb913bff0..9859fa8d, review clean). Browser/API localN/save/delete/crossslice/batch/responseunknown/retry/concurrentconflict allpassed; details acceptance-evidence.md.
Task 7: starting; BASE9947631b. Task06metadata9947631b.
Task7 implementer /root/implement_07 (gpt5.6solhigh), active; rootRED ShiftDelete leaves3slices onloaded9859fa8d.
Task6 minor(deferred): prior conflict alert remained visible after explicit taskcard switch to slice-primary; no late response or data contamination observed. FinalreviewtriageUIerrorreset.
Task7 code37480aec, initialindependentreviewApproved; browserfoundImportantrestorekeepemptydescriptionnullcrash, originalworkerfixround1activeBASE37480aec.
Ruling: For Ctrl+X and Shift+Delete, accept the approved public key-resolver tests plus the exact shared mouse handler's browser/API behavior, and disclose physical-key verification as unavailable — a minimal DOM key probe proved the embedded browser delivers no keydown for these two chords and the alternate Edge connector lacks its auth token; actual Mac Shift+Backspace and native text cut are browser-tested — cost if wrong: an OS/browser shortcut integration defect may remain for manual verification.
Task7 minor(deferred): annotation-stage shortcut help omits undo/redo inheritedfrom05 phasefilter; finalreviewtriage helpaccuracy.
Task7 fixround1/5 (1 addressed,0 open;37480aec..6db97457). Browserdiscardv4restorev5nullsegments noerror+reload3slices PASS.
Task 7: complete (commits9947631b..6db97457, review clean). Macdelete/undo,sliceprotection,textcut,sharedmousebatchv14undo15actualAPI pass; directCtrlX/ShiftDelete physicaldeliveryunavailableRuling4 explicit.
Task 8: starting; BASE6a1e415d. Task07metadata6a1e415d.
Task8 implementer /root/implement_08 gpt6astrahigh active. RootRED noeditorCtrlEnter yieldsnomodal/noPOST onannotationphase.
Task8 codeb6e80de8 independentreviewApproved, livebrowser/API actualgeneration/QAunknownrecovery/mixedandallblanksemanticspass; artifacts21/21hashesverified. AnnotationhelpUndoRedo minorresolved.
Task 8: complete (commits6a1e415d..b6e80de8, review clean). Phase1gatepassed;09maystart.
Task 9: starting; BASEc2058c920c8b6c8c0460e8d81b189fed3a2fe68d. Task08metadatac2058c92.
Task9 implementer /root/implement_09 gpt6astrahigh active. RootbrowserRED exact开始工作count0.
Task9 rootbrowserImportant: actual开始工作clickfromauthorizedprojectitemroutesbacktoordinary/all/annotate/noquery,projectdeselected. Originalworkerfixround1/5activeBASEacdc5427; formalreviewfullrangeafterfix.
Task9 fixround1/5 acdc5427..ce012f8a routeguardaddressed/rootentryGREEN. FormalreviewImportant asyncclaimcontinuationandcatch stalecontext; fixround2/5 originalworkeractiveBASEce012f8a. Rootfullgenerationrunning/awaitstage; delayedreplayactualgateplannedafterfix.
Task9 fixround2/5(1addressed0open;ce012f8a..97fe6c77), scopedreviewApproved+real30sdelayGREEN withtaskchange+dirtydraft preserved. Fullworkpagejourneyv25qualitypass.
Task 9: complete (commitsc2058c92..97fe6c77, review clean). Task6stalebannerminorresolvedandobservedno olderroronswitch.
Task 10: starting; BASEa1d141da7947ca38f3f4a32411c629382fe71cef. Task09metadataa1d141da.
Task10 implementer/root/implement_10gpt6astrahighactive; realtwotab+reloadREDsupplied. WebLocks+explicitresume designunderimplementation.
Task10fixround1/5(1addressed0open;04d15dd8..d5356785), scopedreviewApproved. Rootlivefresh/reload/dirtycancel/acceptedexit/actualclose/twopage/read-onlyproject/accountlogin/documentBack allpassed; preciseBFCachependinglockracecontrolflowreviewexplicitnotinjected.
Task 10: complete (commitsa1d141da..d5356785, review clean).
Task 11: starting; BASEc8027d7daf60393e9d08c4d6b58b93f0d9a300cd. Task10metadatac8027d7d.
Task11 /root/implement_11gpt6astrahighactive; RootbrowserRED no连续/完成后停止controls,09actualQAnext0. Rootnormalpool03generationstartedtofinishownedfixturewithoutrelease.
Task10minor(deferred): recoverycards display full backendtaskId besidecapturetitle; finalStandardsreview toassess whethernecessarydisambiguation or implementationdetail inoperatorflow. No behaviorfailure.
Task11 complete: fe593f8e+3ee1db6a; independentreviewApproved, headerMinorfixscopedApproved. Primarycontinuous/unknowncrossclose/sameID/stop/empty/dualpage gatesPASS. Finalfullsuitesrunning; fullreviewpending.
Finalwhole-review Standards0hard+1Minor;SpecP1staledisposition/P2draftredo/P3help. ONEfinalfixwave /root/final_fixes on472c2447. BothP1/P2actualbrowserRED/GREENcomplete,64focused/type/buildgreen; frontend578/569/9 exactbaseline9. Scopedreviewpending.
Finalfixbad89540: StandardsMinor+Spec3alladdressed; scopedtwoaxisreviewsApproved,noCriticalImportantresidual. P2templateGREENv8noPOST. Finaltype/build+Rust25green;frontend578/569/9baseline,Go60baseline,Python25baseline+2cachecleared. Vite97816/session34553 restarted5173direct3001 normalHMR; proxy51557stopped. Finaldocsarchive/commitcleanupremaining.
Delivery finalized: all11resolved, finaldualreview+scopedfixapproved; userguide/docsverificationpublished. NormalVite5173PID97816 direct3001/HMR enabled, faultproxy3301stopped, browserviewportreset/keyprobeclosed, project-selectionlandingkept. Finalrawarchive local-data/verification/annotation-keyboard-workflow. No push/merge/deploy. Onlyfinaldoccommitandownworkspacecleanup remain.

View File

@ -0,0 +1,84 @@
# Private Rust toolchain readiness
Prepared on 2026-09-17 for the repository-local test run. No Rust build or test was run.
## Result
The previous missing-Cargo blocker is resolved. A private Rust toolchain and the complete locked dependency cache are installed under the ignored path:
```text
local-data/toolchains/rust/
├── cargo/ # rustup proxies plus Cargo registry/cache
├── rustup/ # installed toolchain and components
└── downloads/ # downloaded rustup-init binary
```
`local-data/` is ignored by `.gitignore:21`; `git check-ignore -v` confirmed the rustup binary, Cargo registry index, installed toolchain, and downloaded installer are all covered. No shell profile, home-directory toolchain, system package, project source, manifest, or lockfile was changed.
## Project constraints and installed versions
- Workspace: `tools/drosync/Cargo.toml`, nine members.
- MSRV: `rust-version = "1.89"` and edition 2024 (`tools/drosync/Cargo.toml:15-19`).
- Exact pin: Rust `1.89.0`, minimal profile, with `clippy` and `rustfmt` (`tools/drosync/rust-toolchain.toml:1-4`).
- Lockfile: Cargo lock format 4. Every external `source` entry is the crates.io registry; there are no git dependencies.
- Host: `aarch64-apple-darwin`, macOS 26.6.2, Apple clang 21 command-line tools already present.
- `rustup 1.29.1 (d95a37b6a 2026-08-13)`.
- `rustc 1.89.0 (29483883e 2025-08-04)`, LLVM 20.1.7.
- `cargo 1.89.0 (c24e10642 2025-06-23)`.
- `clippy 0.1.89 (29483883ee 2025-08-04)`.
- `rustfmt 1.8.0-stable (29483883ee 2025-08-04)`.
The official Rustup documentation confirms that `RUSTUP_HOME` selects the toolchain root, `CARGO_HOME` contains Cargo's cache and installed proxies, and `--no-modify-path` avoids profile edits: [Rustup installation](https://rust-lang.github.io/rustup/installation/) and [Rustup environment variables](https://rust-lang.github.io/rustup/environment-variables.html).
## Provisioning evidence
The official arm64 macOS installer was downloaded directly from:
```text
https://static.rust-lang.org/rustup/dist/aarch64-apple-darwin/rustup-init
```
The downloaded file is an arm64 Mach-O executable. macOS `codesign --verify` reported it valid and satisfying its designated requirement. Its SHA-256 is recorded locally as:
```text
ec1b9233e7f72990ecd8e62063fa7f6c3dfc2bec8e97f88bff165f9100ac696a
```
Rustup was initialized with `--no-modify-path --profile minimal --default-toolchain none`, then installed exact toolchain `1.89.0` plus `clippy` and `rustfmt`. Downloads came from Rustup's official `static.rust-lang.org` distribution service. `cargo fetch --locked --manifest-path tools/drosync/Cargo.toml` populated the private cache from the crates.io registry.
Fresh verification:
- A second `cargo fetch --locked` with `CARGO_NET_OFFLINE=true` exited successfully with no downloads.
- `cargo metadata --locked --offline --no-deps` parsed all nine workspace members.
- `git diff --exit-code` passed for `Cargo.toml`, `Cargo.lock`, and `rust-toolchain.toml`.
- Private toolchain plus cache size after fetch: approximately 1.6 GiB; the Cargo registry portion is approximately 1.0 GiB.
- Network errors: none.
## Exact environment for the final suite
Run from the repository root. This affects only the current shell and also keeps future build output under ignored `local-data` rather than `tools/drosync/target`:
```bash
DROBOTICFLOW_RUST_ROOT="$PWD/local-data/toolchains/rust"
export CARGO_HOME="$DROBOTICFLOW_RUST_ROOT/cargo"
export RUSTUP_HOME="$DROBOTICFLOW_RUST_ROOT/rustup"
export CARGO_TARGET_DIR="$DROBOTICFLOW_RUST_ROOT/target"
export PATH="$CARGO_HOME/bin:$PATH"
```
Optional read-only preflight:
```bash
rustc --version
cargo --version
CARGO_NET_OFFLINE=true cargo fetch --locked --manifest-path tools/drosync/Cargo.toml
```
The authorized final command remains:
```bash
npm run test:drosync
```
The dependency cache is complete for the lockfile, so the final runner may add `CARGO_NET_OFFLINE=true` to guarantee that `test:drosync` performs no registry network access. Compilation can still reveal platform or source-level failures; this preparation deliberately did not run the build or suite ahead of the root worker's single final run.

View File

@ -0,0 +1,137 @@
# Task 1 implementation report
## Status
Implementation, focused automated verification, controller-owned browser/API acceptance, and read-only review are complete. The fix review approved the task with no Critical or Important findings.
## Changes
- Added `src/lib/annotation-authoritative-mutation.js` with a generation-scoped task/account mutation fence, authoritative write settlement, semantic workspace matching, and reset reconciliation.
- Updated `confirmAnnotationDescription` so only a successful response or matching authoritative reread advances the item version and saved baseline. Removed the development-mode conflict success fallback.
- Updated `resetToSliceEditing` so only a successful response or an authoritative reset workspace clears descriptions and enters slice editing. Removed the development-mode conflict success fallback.
- Failed writes reread the task. Mismatched or unreadable authority remains failed/unknown, retains editable content, and does not import a newer version for a blind overwrite retry.
- Task/account switches invalidate the mutation generation. Late responses and late `finally` blocks cannot update or unlock a newer workspace operation, including same-context ABA.
## TDD evidence
RED:
```text
node --test tests/frontend/annotation-authoritative-mutation.test.mjs
exit 1: ERR_MODULE_NOT_FOUND for src/lib/annotation-authoritative-mutation.js
```
GREEN cycle 1:
```text
node --test tests/frontend/annotation-authoritative-mutation.test.mjs
6 passed, 0 failed
```
RED cycle 2:
```text
node --test tests/frontend/annotation-authoritative-mutation.test.mjs
exit 1: module did not provide annotationWorkspaceMatches
```
GREEN cycle 2:
```text
node --test tests/frontend/annotation-authoritative-mutation.test.mjs
8 passed, 0 failed
```
The regression tests exercise confirmed responses, response-loss recovery through GET, conflict/mismatch, unreadable authority, task/account switches, same-context ABA, server timing metadata, and reset-state proof. They assert behavior of the executable helper rather than source strings or private React state.
## Verification evidence
```text
node --test tests/frontend/annotation-authoritative-mutation.test.mjs tests/frontend/annotation-submission-state.test.mjs tests/frontend/annotation-operation-latency.test.mjs tests/frontend/annotation-operations.test.mjs
24 passed, 0 failed
go test ./internal/api -run 'Test(SliceResetClearsDescriptionsAndReturnsToEditing|AnnotationConfirmationRequiresMaterializedSlicesAndAcceptsSparseDescriptions|PendingCombinedSubmissionBlocksWorkspaceMutations|SliceResetPreservesRevisionFence)$' -count=1
ok droboticflow/internal/api
npm run lint:web
exit 0
npm run build:web
exit 0; Vite built 3,202 modules. Existing large-chunk advisory only.
npx prettier --check src/pages/AnnotationOperations.tsx src/lib/annotation-authoritative-mutation.js tests/frontend/annotation-authoritative-mutation.test.mjs tests/frontend/annotation-submission-state.test.mjs
exit 0
```
No full test suite was run, per ticket instructions.
## Browser and HTTP evidence
Controller fixture:
- project `project-keyboard-acceptance`
- primary task `annotation-task-keyboard-acceptance-annotate-primary`
- delayed-response task `annotation-task-keyboard-acceptance-annotate-delayed`
- local frontend/API/Mongo only (`5173` / `3001` / `27018`)
The first normal-save attempt exercised the real page and HTTP endpoint but was rejected because the isolated fixture stored segment timestamp fields as BSON Long-shaped objects (`{high,low,unsigned}`), which Go correctly rejected for `int64`. The captured request otherwise contained the expected version, three hardware-aligned slices, description, operations, and statuses. This was repaired only in the local fixture data.
After fixture repair, the real page successfully saved `键盘验收01:正常保存`. A second save used the local fault proxy: the real API returned HTTP 200, the proxy destroyed the browser response, the page reread the task, matched the authoritative workspace, closed the editor, and displayed persisted text `键盘验收01:响应丢失后核对保存`. Independent API readback returned version 3 and the intended text.
Conflict evidence: a public competing write advanced the primary item to version 4 with `键盘验收01:另一页面的新内容`. The stale page description save returned HTTP 409, displayed the retained local draft, and did not report success. A stale reset also returned HTTP 409; its warning remained open and neither slices nor descriptions were cleared. API readback remained version 4 with the competing text.
Late-response evidence: the proxy held the primary save response for 30 seconds while the controller opened the delayed task and saved its own description. Releasing the old response did not inject the delayed task's content into the primary workspace or unlock the wrong operation. API readback showed the primary at version 5 with `键盘验收01:迟到保存应隔离` and the delayed task at version 2 with its own intended text.
Reset result-unknown evidence: primary reset reached the real API with HTTP 200 and the proxy destroyed the response. The page reread authority and reconciled to one full-range `0–412` slice with no descriptions. Independent API readback showed primary version 6, `sliceWorkflow` status `editing`, phase `slice`, and an empty descriptions array.
All browser actions used the real page through `cua_repl`; all writes targeted the isolated local fixture and local API/Mongo only.
## Self-review
- The mutation fence compares task and account and also carries a monotonically increasing ID, so a late completion cannot own a newer operation after invalidation.
- Failed conflict reconciliation deliberately does not install the reread item version. Retrying with retained stale edits therefore cannot overwrite newer server content; explicit refresh is required.
- A response-loss recovery counts as success only when the reread version advanced and the authoritative semantic workspace matches the attempted write. Server-added hardware timestamp metadata does not affect the semantic match.
- Reset recovery requires a newer item version, `sliceWorkflow` in reset editing state with `resetAt`, nonempty slices, and empty operations/descriptions.
- Existing permissions, claim checks, dictionary fields, slice disposition, blank/invalid/discard semantics, and hardware-aligned boundaries remain in the original API handlers.
- The task-status edit and fixture preparation script are unrelated controller/fixture changes and are not staged.
## Remaining gaps
- No ticket 01 implementation gaps remain. The controller repaired and API-verified the fixture project's dictionary linkage separately for later tickets; no application change was required.
## Commit
`18139a00` — `🛡️ Make annotation edit results authoritative`
## Fix round 1: synchronous context invalidation
The first read-only review found that task invalidation relied on a passive React effect. A response could theoretically settle after `setSelectedTaskId` was scheduled but before the effect ran. The fix adds a live authoritative mutation context that invalidates the generation synchronously before every selected-task state update. All task select, close, claim, automatic selection, pending-discard selection, and prepackage-preview paths now use that seam. Account identity is compared and switched during render, before passive account cleanup effects.
RED:
```text
node --test tests/frontend/annotation-authoritative-mutation.test.mjs
exit 1: module did not provide createAuthoritativeMutationContext
```
GREEN and covering verification:
```text
node --test tests/frontend/annotation-authoritative-mutation.test.mjs
9 passed, 0 failed
node --test tests/frontend/annotation-authoritative-mutation.test.mjs tests/frontend/annotation-submission-state.test.mjs tests/frontend/annotation-operation-latency.test.mjs tests/frontend/annotation-operations.test.mjs
25 passed, 0 failed
npm run lint:web
exit 0
npm run build:web
exit 0; existing large-chunk advisory only
```
The revised regression resolves a deferred response immediately after `context.switchTo`, without manually invalidating the scope or waiting for an effect. Separate task and account cases both settle as `stale`; the page calls that same context switch before scheduling selected-task state.
Fix commit: `61703abc` — `🐛 Invalidate stale annotation writes synchronously`.
The follow-up reviewer marked the original finding **ADDRESSED**, spec compliance **Compliant**, and task quality **Approved**, with no new Critical or Important issues. Review: `.superpowers/sdd/annotation-keyboard-workflow/task-1-review-fix1.md`.

View File

@ -0,0 +1,27 @@
### Fix Verdict
- ✅ **ADDRESSED.** `createAuthoritativeMutationContext` changes the live task/account identity and invalidates the active generation synchronously (`src/lib/annotation-authoritative-mutation.js:110`). The page now calls that seam before scheduling selected-task state (`src/pages/AnnotationOperations.tsx:586`), including close, direct selection, claim, pending-discard selection, URL/path selection, and prepackage preview paths (`src/pages/AnnotationOperations.tsx:861`, `src/pages/AnnotationOperations.tsx:926`, `src/pages/AnnotationOperations.tsx:2433`, `src/pages/AnnotationOperations.tsx:2630`, `src/pages/AnnotationOperations.tsx:2756`, `src/pages/AnnotationOperations.tsx:2778`, `src/pages/AnnotationOperations.tsx:2851`, `src/pages/AnnotationOperations.tsx:3232`). Account identity is switched before passive cleanup (`src/pages/AnnotationOperations.tsx:512`).
### Strengths
- Mutation settlement now reads the same live context used by synchronous selection/account switching (`src/pages/AnnotationOperations.tsx:1499`, `src/pages/AnnotationOperations.tsx:1673`, `src/pages/AnnotationOperations.tsx:2052`).
- The regression resolves a deferred response immediately after `switchTo`, without manually calling `scope.invalidate()` (`tests/frontend/annotation-authoritative-mutation.test.mjs:116`); account switching has an equivalent case (`tests/frontend/annotation-authoritative-mutation.test.mjs:136`).
- The fix preserves monotonic generation ownership and does not alter write reconciliation or backend semantics.
### Issues Introduced by Fix
#### Critical
None.
#### Important
None.
### Assessment
**Spec compliance:** ✅ Compliant for the reviewed stale-response requirement.
**Task quality:** Approved.
**Reasoning:** The fix closes the passive-effect window at the page integration seam and tests the exact immediate-settlement boundary from the original finding. No new Critical or Important breakage appears in the scoped fix diff; previously reported browser gates remain applicable.

View File

@ -0,0 +1,32 @@
### Spec Compliance
- ❌ Issues found: stale task/account responses are not unconditionally isolated. The fence is invalidated only from passive effects (`src/pages/AnnotationOperations.tsx:825`, `src/pages/AnnotationOperations.tsx:842`), while task selection itself only schedules state (`src/pages/AnnotationOperations.tsx:2751`). A write that settles after the click but before those effects still sees the old `selectedTaskDetailIDRef`/account context and can advance the old operation's success path.
- ⚠️ Controller evidence now covers normal save, dropped-200 save plus GET reconciliation, stale-version 409 retention, reset 409 retention, dropped-200 reset reconciliation, and a 30-second delayed task-A response after selecting task B. The controller should additionally check the same-turn boundary: switch task/account and settle the deferred response before passive effects flush. That is the interval the current implementation leaves open.
### Strengths
- `src/pages/AnnotationOperations.tsx:1652` and `src/pages/AnnotationOperations.tsx:2031` remove the development conflict-as-success behavior and advance state only after a fulfilled write or a matching authoritative reread.
- `src/pages/AnnotationOperations.tsx:1669` retains rejected/unknown description edits without installing a newer conflicting server version; `src/pages/AnnotationOperations.tsx:2040` does the same for re-slicing.
- `src/lib/annotation-authoritative-mutation.js:9` compares the persisted semantic workspace while deliberately excluding server-generated frame/audit timing. This matches the API handlers' canonicalization of statuses, hardware timestamps, disposition audit fields, and reset workspaces.
- `src/lib/annotation-authoritative-mutation.js:83` uses monotonic tokens, so an invalidated operation's `finally` cannot unlock a newer same-context operation; `tests/frontend/annotation-authoritative-mutation.test.mjs:136` covers that ABA case.
- Existing permission, claim, dictionary, frame, blank/invalid/discard, and review checks stay in the existing API/UI paths; this diff does not bypass them.
### Issues
#### Critical (Must Fix)
None.
#### Important (Should Fix)
- `src/pages/AnnotationOperations.tsx:842`, `src/pages/AnnotationOperations.tsx:2751`: task/account fence invalidation is deferred to `useEffect`. The task-card selector is clickable while saving, so a response can resolve between `setSelectedTaskId(...)` and the effect, still pass `scope.owns(...)`, update the old task's version/baseline, and report success. Invalidate the mutation scope and update the live context synchronously in task-close/task-select paths; use an equally immediate account identity source. Add an integration test that resolves a deferred response immediately after selection changes. The current helper test changes context and explicitly calls `invalidate()` itself (`tests/frontend/annotation-authoritative-mutation.test.mjs:129`), so it proves the helper contract rather than the page wiring.
#### Minor (Nice to Have)
None.
### Assessment
**Task quality:** Needs fixes
**Reasoning:** Authoritative reconciliation and recoverable failure handling are well designed and the reported browser gate covers the expected long-delay flows. The passive-effect invalidation window still violates the task's unconditional stale-response isolation requirement.

View File

@ -0,0 +1,98 @@
# Task 10 implementation report — work session recovery and page ownership
## Status
CODE-FROZEN at `04d15dd8` (`🔒 Add explicit work session recovery and browser ownership`). Controller may reload the HMR-disabled frontend. Browser GREEN is controller-owned and is **not claimed by this report**. No live fixture, browser, API process, company service, BOS object, push or deployment was changed by this implementer.
## Changes and public entry
- Existing `/plugins/annotation-qa/workflows/:workflowId/work` and `AnnotationOperations workPage` remain the sole dedicated work page, sharing the existing workbench, authorization and router blocker.
- A freshly loaded or reopened work page shows the **恢复工作会话** region, heading **继续已领取任务**, owned unfinished task cards, and exact button **继续工作**. It does not mount the editor or execute a claim. Cards select an owned task using the normal task selection coordinator.
- **继续工作** first acquires browser page ownership and then reads current owned tasks through the existing public API. It opens the selected unfinished owned task, or the first remaining owned unfinished task, after reading its task summary. This resume-only path never calls random claim, including when an unresolved claim request ID exists. If no owned work remains it reports that fact without allocating.
- Explicit **开始工作** on the pool retains task09's owned-first entry and unknown-claim reconciliation behavior, now reserving browser ownership before the first request. All existing task/account/project/location/draft identity checks remain; ownership-token validity is an additional condition. A stale confirmed claim still reconciles the owned pool without navigating.
- The duplicate page shows **此账号在本项目已有活动工作页。请切换回该页面继续,避免同时编辑。** and exact **返回活动工作页**. Its editor is absent and continuation/start entry is disabled while the owner remains present. The return action requests focus in the owning tab; visible guidance says to select the original browser tab manually if the browser blocks focus.
- **返回任务池** still goes through the existing dirty leave blocker. Cancelling leave preserves the editor and ownership. Accepted exit/close releases browser ownership without releasing any backend task. A waiting page detects availability and still requires **继续工作**.
- Saved-only recovery resets the editor/history before continuation. Native reload creates fresh state. Accepted document leave also clears ephemeral drafts/history and invalidates in-flight authoritative mutations so a browser back/forward-cache restore follows the same saved-only recovery contract.
## Coordination protocol and ticket11 interface
`src/hooks/useAnnotationWorkSession.ts` owns a browser-local exclusive Web Lock named from the JSON tuple `[userId, projectId]`, under `droboticflow.annotation-work:`. The browser supplies origin/context isolation; no backend assignment count or cross-device restriction is introduced.
1. `acquire()` requests the exclusive lock with `ifAvailable`. Competing pages cannot race a localStorage write or both succeed. Acquisition returns an identity-bearing `AnnotationWorkSession` object in document memory; a URL, duplicated history entry or refreshed document cannot recreate that object.
2. `owns(session)` checks the current account/project and exact owner identity. `activate(session)` opens editing only after the existing owned-task / confirmed-claim entry has succeeded. `active` is presentation state; ticket11 should retain the token and use `owns(token)` at asynchronous continuation boundaries before claiming/navigating.
3. `release(session)` can release only that exact current owner. An old request/finally cannot release a later session. Account/project identity objects fence pending lock acquisition; disposed effects fence lock-query callbacks.
4. A document-memory owner bridges pool-to-work routing. Effect cleanup defers release until the end of the turn so a same-scope route mount can adopt it. Leaving the coordinator, changing scope, returning to the pool or accepted `pagehide` releases it. Browser document destruction/crash releases Web Locks independently of JS cleanup.
5. A scoped BroadcastChannel carries only `changed` and `return` notifications. It is advisory: Web Locks remain the authority. A lock query on mount/focus/pageshow and every 2 seconds finds closed owners even when their notification could not be delivered. Querying never acquires or resumes work.
6. There is deliberately **no lease expiry**. Timer throttling, a sleeping laptop or a background dirty editor must not permit another page to take over. The recovery route for an unresponsive owner is to close that page; the browser releases the native lock. Unsupported/failed lock APIs fail closed with a visible browser capability message.
The existing unresolved random-claim request IDs remain in their original account/project sessionStorage keys. No new allocation occurs on refresh; recovery is separate from explicit new-work entry. This ticket adds no next-task automation.
## TDD evidence at the approved seam
The approved primary seam is actual browser interactions plus existing public API reads/writes. No new source-string assertion, private React inspection, storage injection or test-only business interface was added.
Controller supplied RED before production edits, against frozen `97fe6c77`:
- Opened owned `pool-03` in tab4 at the existing `/all/work?...taskId=...` route.
- Opened the same URL in tab6 in the same browser context/account/project. Both pages had **确认全部切片** enabled.
- Reloaded tab6: the editor was immediately enabled; exact **继续工作** button count was 0. No new claim/data write was needed to reproduce the missing recovery and mutual exclusion.
That browser RED, rather than a new invented unit seam, drove the production change. Controller has been notified of CODE-FROZEN and owns browser GREEN. The checks below supplement but do not replace that acceptance.
## Verification commands and results
```text
node --test tests/frontend/annotation-random-claim.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-submission-state.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs
```
Final run: 32 tests, 32 pass, 0 fail, 0 skipped, 0 cancelled. Covers existing request IDs, shortcuts, authoritative mutation identity, stale responses and stage results. Existing source-shape assertions in the random-claim file remain prior test debt; they are not acceptance evidence for page coordination.
```text
npx prettier --check src/hooks/useAnnotationWorkSession.ts src/pages/AnnotationOperations.tsx
npm run lint:web
npm run build
git diff --check
```
All exit 0 on the final source. Final build transformed 3204 modules and built all three Go executables; it did not restart the API. Existing Node module.register deprecation and >500 kB chunk notices remain. No full suite or new backend test was run: no backend behavior changed, and the controller owns the final full-suite comparison.
## Files and commit
- `src/hooks/useAnnotationWorkSession.ts` — scoped native lock lifecycle and explicit session ownership interface.
- `src/pages/AnnotationOperations.tsx` — recovery UI, reserved entry, additional mutation fence and saved-only document recovery.
- Commit `04d15dd8` contains only those two task implementation files. The controller's `.scratch/.../10-work-session-recovery.md` edit was left unstaged. This report is in the existing ignored `.superpowers` report path.
## Self-review and remaining acceptance
Self-review checked no automatic acquisition on load/query, reserve-before-request with no navigation gap, identity checks on all new asynchronous callbacks, atomic same-scope acquisition, no timed eviction, dirty router/native leave behavior, unknown request ID preservation, and no new backend policy. BFCache ephemeral state cleanup was added during self-review and the focused tests/typecheck/build were rerun afterward.
Still requires controller browser evidence: pool-to-work route continuity, refresh explicit continuation, two-page exclusion, accepted exit and actual tab-close recovery, account/project isolation using authorized local fixture scopes, and retained drafts on cancelled leave. Focus switching is subject to browser policy and has explicit manual guidance. Unsupported Web Locks intentionally prevent dedicated work activation. No claim is made that the full browser acceptance already passed.
## Review fix round 1 — pending acquisition across document leave
Final source is CODE-FROZEN at `d5356785` (`🛡️ Fence pending work session acquisition on document leave`). The fix changes only `src/hooks/useAnnotationWorkSession.ts` (one identity replacement plus an explanatory comment).
The Important finding in `task-10-review.md` was confirmed: pagehide released an existing owner but did not invalidate a requested lock whose asynchronous callback had not run. Authoritative mutation invalidation is a separate fence and does not change that acquisition identity. `pageHidden` now replaces the identity **before** releasing any owner. A callback issued before accepted leave therefore returns null at its existing identity comparison and cannot create a session after BFCache restore.
Lifecycle proof by control-flow review (not a claimed automated/browser race reproduction):
1. Explicit Continue captures identity A and submits the browser lock request.
2. Accepted document leave emits pagehide, synchronously replacing identity A with B. If the callback already created a session before pagehide, the following owner release invalidates that exact session instead.
3. A delayed callback compares its captured A against B, resolves null, and returns without constructing an owner or activating the editor. Restoring via pageshow only queries locks; it never replaces B with A or acquires ownership.
4. A new explicit Continue after restore captures B and may acquire normally. Account/project and effect-cleanup fencing remain unchanged. The single-threaded callback cannot be interleaved with pagehide between its identity check and synchronous owner construction.
No private React access, source-string test, storage injection or alternate business seam was introduced. Controller stated the pending-acquisition race cannot be deterministically injected through the approved CUA surface; its exact timing case is therefore covered by this lifecycle analysis/review, not overstated as a browser test.
Verification after the fix:
```text
node --test tests/frontend/annotation-random-claim.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-submission-state.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs
npm run lint:web
npx prettier --check src/hooks/useAnnotationWorkSession.ts
git diff --check
npm run build
```
All commands exit 0; focused regression result is 32/32 pass, 0 fail/skip/cancel. Final build succeeds (3204 modules; three Go binaries), with the same previously documented deprecation/chunk-size warnings. No browser/API/fixture mutation, service restart or full suite was performed in this fix round.
Controller browser evidence reported before this fix: fresh/reloaded pages remain paused; duplicate page blocks; dirty exit cancellation retains ownership; accepted exit releases ownership; the other page restores the 3 saved slices with no old history; actual tab closure makes the pool's Start Work available. Those are controller observations, not implementer-run tests. Account/project scope verification remains controller-owned and may proceed after this freeze.

View File

@ -0,0 +1,18 @@
### Finding Verdicts
- **Pending acquisition can reactivate a restored document after pagehide** — **ADDRESSED**. `src/hooks/useAnnotationWorkSession.ts:83` replaces the acquisition identity synchronously before releasing any existing owner. A callback holding the pre-leave identity now fails the existing identity comparison (line 119) and returns null before constructing a session. If acquisition completed first, pagehide releases that exact owner. A subsequent explicit Continue captures the new identity normally; pageshow only refreshes observation.
### New Breakage in the Fix Diff
- None. The three-line addition preserves the same scope value and existing owner-release path, so it invalidates pending callbacks without preventing normal post-restore acquisition (`src/hooks/useAnnotationWorkSession.ts:80`).
### Out-of-Scope Observations
- None newly identified. Controller account-scope browser acceptance remains outstanding; this scoped review does not claim that acceptance is complete.
### Verdict
**Fix round:** All findings addressed, no new Critical/Important breakage.
- Checks performed: read the supplied fix diff once (`04d15dd8..d5356785`) and appended fix report. Confirmed the lifecycle proof against the identity comparison already reviewed; no additional source inspection, diff regeneration, or test rerun.
- Verification evidence checked: appended report names the four focused frontend test files and reports 32/32 pass, zero fail/skip/cancel, plus successful lint, formatting, diff check, and build. Existing deprecation/chunk-size notices remain acknowledged. The exact delayed-acquisition/pagehide race is supported by control-flow review, not claimed as an automated or browser reproduction.

View File

@ -0,0 +1,36 @@
### Spec Compliance
- ❌ Issues found: pending acquisition is not invalidated on accepted document leave, so an old Continue callback can reactivate a BFCache-restored page without a fresh explicit Continue (`src/hooks/useAnnotationWorkSession.ts:80`, `src/hooks/useAnnotationWorkSession.ts:116`; Important issue below).
- ✅ Recovery has a separate resume-only entry that bypasses unresolved/new random claims, displays owned unfinished work, and gates the editor on an active browser session (`src/pages/AnnotationOperations.tsx:3225`, `src/pages/AnnotationOperations.tsx:3323`, `src/pages/AnnotationOperations.tsx:3712`).
- ⚠️ Cannot verify from diff: real saved-only refresh/history reset, actual tab-close recovery, account/project isolation, and complete browser interaction acceptance. Controller reports fresh paused/select/continue, duplicate blocking, cancelled dirty leave retaining ownership, and accepted exit passing; remaining gates must be supplied by the controller. No new automatic-next behavior is present; ticket11 acceptance remains separate.
- ⚠️ Cannot verify unchanged hardware-frame, dictionary, roles/review/CAS, and semantic distinctions from this task's two-file diff; the changes do not alter their implementations.
### Strengths
- Native exclusive Web Locks provide atomic browser-context ownership without imposing a backend task limit; scope uses an unambiguous account/project tuple (`src/hooks/useAnnotationWorkSession.ts:28`, `src/hooks/useAnnotationWorkSession.ts:109`).
- Identity-specific release protects a later owner from an earlier request's finally cleanup, and scope/effect cleanup invalidates pending acquisition identities (`src/hooks/useAnnotationWorkSession.ts:16`, `src/hooks/useAnnotationWorkSession.ts:93`, `src/hooks/useAnnotationWorkSession.ts:152`).
- Existing entry identity fences remain in place, with session ownership added before activation and authoritative mutations (`src/pages/AnnotationOperations.tsx:1625`, `src/pages/AnnotationOperations.tsx:3108`, `src/pages/AnnotationOperations.tsx:3209`).
### Issues
#### Critical (Must Fix)
- None found.
#### Important (Should Fix)
- `src/hooks/useAnnotationWorkSession.ts:80`: `pageHidden` releases an existing owner but leaves the acquisition identity unchanged. If explicit Continue calls `navigator.locks.request()` and an accepted document navigation occurs before its asynchronous callback runs, there is no owner yet to release. After a BFCache restore the callback at line 116 still accepts the original identity and creates a new owner; `startWork` can then activate it. The page's `pagehide` handler only invalidates the authoritative mutation scope (`src/pages/AnnotationOperations.tsx:544`), which does not replace the task context compared at line 3209, and does not invalidate the entry's claim context. This violates explicit recovery and the old-session callback fence. Replace the hook's acquisition identity on pagehide, as cleanup already does, so any pre-leave acquisition resolves null; cover the delayed-acquire/pagehide/restore sequence at the public lifecycle seam.
#### Minor (Nice to Have)
- `.superpowers/sdd/annotation-keyboard-workflow/task-10-report.md` (Verification commands and results): reported build output retains existing Node module.register deprecation and >500 kB chunk notices. These are acknowledged pre-existing warning debt, not a new task10 regression; verification output is not pristine.
### Assessment
**Task quality:** Needs fixes.
**Reasoning:** The main recovery and mutual exclusion design is appropriately scoped, and preserves owned-task reconciliation. The pending-acquisition document-lifecycle gap must be closed before claiming late-session callbacks are fenced.
- Checks performed: read the supplied brief/report/full review package; the first combined tool output was truncated, so the omitted report and hook portion were retrieved separately. No diff was regenerated and no tests were rerun.
- Named focused risk check — pending entry across pagehide: inspected `createAuthoritativeMutationScope.invalidate()` and `createAuthoritativeMutationContext.current()` in `src/lib/annotation-authoritative-mutation.js`, plus claim-context cleanup at `src/pages/AnnotationOperations.tsx:702`. Confirmed mutation invalidation does not replace either entry identity, while claim identity changes only on scope/location change or component cleanup.
- Named focused risk check — initial-render pagehide closures clearing saved-only state: inspected stable `setDetail`, ref-based `clearEditHistory`, and task-detail reload/reset paths at `src/pages/AnnotationOperations.tsx:575`, `src/pages/AnnotationOperations.tsx:610`, `src/pages/AnnotationOperations.tsx:1090`, and `src/pages/AnnotationOperations.tsx:1208`. No additional closure defect found; actual saved-only browser behavior remains controller-owned acceptance.

View File

@ -0,0 +1,19 @@
### Finding Verdicts
- **Contradictory stop-after-current header** — ADDRESSED. `src/pages/AnnotationOperations.tsx:3505–3506` now uses neutral guidance, “连续工作状态与停止选项见下方”, rather than incorrectly promising to pause after the current task. The live continuous controls remain the source of state information.
### New Breakage in the Fix Diff
- None. The only change is subtitle text and JSX wrapping.
### Out-of-Scope Observations
- None.
### Checks
- Read `review-11-fix1.diff` once for `fe593f8e..3ee1db6a` and the appended fix report. The report records successful lint, Prettier and whitespace checks; this text-only fix does not introduce behavior requiring a new test. No tests, Git commands, browser operations or broader source inspection were run.
### Verdict
**Fix round:** All findings addressed, no new Critical/Important breakage.

View File

@ -0,0 +1,97 @@
# Task 11 implementation report — continuous work and durable claim recovery
## Status
CODE-FROZEN at `fe593f8e` (`🔁 Add continuous annotation work with durable claim recovery`). Controller owns actual-browser GREEN and fixture mutations; this report does not claim that the complete browser chain already passed. Implementation touched no live browser, fixture, API process, company service or BOS object. No push or deployment.
## Behavior and integration
- Document-memory work sessions now carry explicit continuous intent and a pause reason. The existing pool **开始工作** enables continuous mode after acquiring its scoped Web Lock. Active work pages offer **开始连续工作** or **恢复连续工作** and **完成当前任务后停止**. A reload/closed page does not persist or automatically enable continuous intent.
- Only the current owner can execute continuation. Existing task/account/project/router-origin mutation and claim fences remain; role and current authorization also fence entry. Enabling continuity while editing preserves the current drafts/history.
- The two existing authoritative quality-handoff branches queue continuation only after `combinedSubmissionFinished(next)`. `processing` remains locked and polls without claiming. Each task/revision handoff queues at most one entry. That entry runs after mutation completion and uses the existing authoritative owned-first read before random allocation.
- A work page retains the completed task's authoritative result while continuation is pending or paused. My Tasks no longer clearing that completed selection prevents list refresh from losing the handoff before its continuation runs. Ordinary pool completion still uses the old return-to-pool path.
- **完成当前任务后停止** synchronously disables future continuation, keeps the editor usable, and never releases server assignment. The stop control is disabled during next-task entry/claim because that request may already have committed.
- Processing failure, failed readback, unknown transport result, failed project reload and permission changes pause continuous intent with a visible reason. Existing read-only polling/reconciliation continues; successful late readback does not silently re-enable continuity. Unknown stage results keep their existing edit locks and **核对阶段结果** entry.
- Pending random-claim request IDs are persisted in localStorage under the existing account/project key before sending HTTP. Existing sessionStorage receipts are supported for compatibility. Storage failure prevents sending a request. Receipt deletion checks the logical request ID so an older completion cannot delete a different pending request.
- The ordinary random-claim button now reserves the same scoped browser lock for its request. This serializes shared receipt access with dedicated work pages; it does not create a backend assignment quota. A confirmed stale response still reconciles My Tasks without navigating its superseded origin.
- On recovery, **继续工作** restores owned work only when there is no unresolved claim receipt. When a receipt exists, it explains that **核对领取结果并开始连续工作** must be used. That explicit action acquires ownership and replays the original ID before proceeding, preventing the stale receipt from being replayed only after its task was already completed. Initial load/reopen never POSTs a claim.
- Definitive server `claim_result_unavailable` / `claim_candidate_taken` responses clear only their matching receipt and pause; a new attempt requires another explicit action. Unknown/network/authorization failures retain the receipt. A replay that returns an already-finished or differently assigned item pauses instead of reopening it as editable work.
- No backend behavior, role rule, supplier/project boundary, assignment limit, stage contract, frame boundary or dictionary rule was changed.
## Exact UI entry and states
- Region label: **连续工作**.
- Running: **连续工作中:真实送检成功后继续下一条;处理期间不会领取。**
- Start / resume: **开始连续工作** / **恢复连续工作**.
- Stop: **完成当前任务后停止**.
- Stopped reason: **已设置完成当前任务后停止;不会再领取下一条,已领取任务仍归您处理。**
- Empty pool: existing server message, followed by **;连续工作已暂停,可稍后恢复。**
- Unknown claim: action error, followed by **连续工作已暂停;恢复时沿用原请求编号核对。**
- Fresh/reopened page retains **恢复工作会话** and **继续工作**, adding **核对领取结果并开始连续工作**. The added explanation says prior unknown claims are reconciled first, existing owned tasks are continued, and only when none remain does random acquisition occur.
## TDD evidence at the approved seam
Controller supplied primary RED before production edits, against frozen task10 `d5356785`: active pool03 work page had no button matching continuous/stop-after-current; earlier real QA completion returned the completion/pause view without auto-claim. This is the missing integrated behavior that drove implementation. The controller is responsible for primary GREEN through the real local frontend/API/Mongo journey; no private React state, storage injection, alternate test seam or source-string assertion was added as acceptance for task11.
New HTTP tests supplement that journey and verify existing public API contracts without backend changes:
- `TestContinuousClaimLostResponseReplaysWithoutConsumingNextTask`: discard the first response, replay the same logical request three times, assert returned ownership/replayed flag and public remaining pool count of one.
- `TestContinuousPendingSubmissionReadbackRetainsCurrentTask`: seed a queued durable submission fixture, reject draft/reset/confirmation writes, then read the public task endpoint and assert unchanged owner, pending ID, version and annotation stage.
The new tests are contract coverage, not a claimed frontend RED. Initial test setup failed because a bare pending token without an active durable job correctly triggered interrupted-job recovery; the fixture was corrected to include a queued submit job. A subsequent invalid combined-submission payload returned schema validation 400 before the pending guard; that case was replaced with the established annotation-confirmations endpoint. No production code was changed to accommodate either fixture correction.
One existing source-shape assertion required `closeTaskAndReturnToPool` after QA, contrary to task11. Running its file produced 1 pass / 1 fail at that exact regex. Removed that obsolete assertion only, retaining the other existing polling assertions and pointing to browser acceptance for the transition. Did not replace it with another private/source assertion.
## Final verification
```sh
node --test tests/frontend/annotation-random-claim.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-submission-state.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs
```
32/32 pass, 0 fail/skip/cancel. Existing source-shape checks in the random-claim file are prior debt and not new-behavior acceptance.
```sh
node --test tests/frontend/annotation-operation-latency.test.mjs
```
2/2 pass after retiring its outdated return-to-pool assertion. Total focused frontend checks: 34 pass.
```sh
go test ./internal/api -run 'TestContinuous(ClaimLostResponse|PendingSubmission)|TestRandomClaim(Atomically|Concurrent|Rejects|Skips|TwoAnnotators|Disabled)|TestPendingCombinedSubmissionBlocksWorkspaceMutations|TestCombinedSubmissionSupportsImmediateAsynchronousResponse' -count=1
```
Exit 0: `ok droboticflow/internal/api 0.607s`. Covers the new HTTP readbacks plus existing idempotency, concurrent claims, scope/roles/supplier checks, processing mutation guards and accepted async response behavior. The successful run emitted no failure output.
```sh
npm run lint:web
npx prettier --check src/hooks/useAnnotationWorkSession.ts src/pages/AnnotationOperations.tsx tests/frontend/annotation-operation-latency.test.mjs
git diff --check
GOCACHE=/private/tmp/droboticflow-task11-go-cache npm run build
```
All final commands exit 0. Final build transformed 3204 modules and built API, worker and sync-coordinator binaries without restarting any service. Existing module.register deprecation and >500 kB chunk warnings remain. Initial default-cache build failed on a sandbox-denied system Go cache file; rerunning with the task-specific writable temporary cache passed. Final build log: `/private/tmp/task11-build.log`.
No full test suite was run; controller owns the once-at-end full-suite comparison. `git add/commit` initially hit the read-only `.git` sandbox; the same explicit four-file commit succeeded through the approved escalation, with no unrelated files staged.
## Files and commit
Commit `fe593f8e` contains only:
- `src/hooks/useAnnotationWorkSession.ts`
- `src/pages/AnnotationOperations.tsx`
- `internal/api/annotation_continuous_recovery_test.go`
- `tests/frontend/annotation-operation-latency.test.mjs`
Controller's task ticket edit remained unstaged. This report lives in the existing ignored `.superpowers` path.
## Self-review and remaining gate
Reviewed stop-before-handoff ordering, deduplication, authoritative processing/QA distinction, owned-first selection, role/scope fences, stale navigation suppression, compare-by-ID receipt cleanup, durable-before-HTTP ordering, normal-entry lock participation, refresh/BFCache behavior, and no server release/quota change. The existing large coordinator remains large; changes stay local to its existing stage and entry boundaries.
Controller still needs browser evidence for actual initial task -> next claim (including dropped successful response) -> tab closure/reopen original-ID reconciliation -> recovered second task -> stop-after-current -> later explicit restart -> empty pause, and duplicate-page exclusion. HTTP tests establish the replay and pending-stage contracts but do not prove frontend timing. The root was notified of CODE-FROZEN before this report was written.
## Review fix — neutral header guidance
CODE-FROZEN at `3ee1db6a` (`📝 Clarify annotation work page continuity guidance`). Controller's browser reproduction and `task-11-review.md` confirmed the static header **完成本条任务后暂停** contradicted active continuous mode. Replaced only that subtitle with **连续工作状态与停止选项见下方**, leaving the live continuous region as the authority for running/stopped/paused behavior.
Verification: `npm run lint:web`, `npx prettier --check src/pages/AnnotationOperations.tsx`, and `git diff --check` all exit 0. Prettier wrapped the longer subtitle over two lines. Self-review diff contains only that text/wrapping change; only `src/pages/AnnotationOperations.tsx` was staged and committed. No build, browser reload, HMR control, service action, fixture write or full suite was performed during the ongoing controller browser gate. The report of actual QA -> dropped successful claim -> close/reopen verification remains controller-owned.

View File

@ -0,0 +1,39 @@
### Spec Compliance
- ✅ Spec compliant in the reviewed implementation: explicit continuous intent and owner checks (`src/hooks/useAnnotationWorkSession.ts:171–196`); authoritative quality handoff queues continuation, while processing returns without entry (`src/pages/AnnotationOperations.tsx:2531–2536`, `2550–2598`, `3122–3137`); entry reconciles a pending receipt or owned work before allocating (`3291–3337`). No backend authorization or assignment contract was changed.
- ⚠️ Browser acceptance remains the controller's gate: the implementer explicitly leaves continuous two-task completion, dropped-response/close/reopen recovery, stop, empty pool and duplicate-page acceptance pending (`.superpowers/sdd/annotation-keyboard-workflow/task-11-report.md`, “Self-review and remaining gate”). This code review does not replace A15–A17 evidence.
### Strengths
- Durable receipt storage precedes HTTP, and cleanup compares the request identifier; success from a superseded origin can reconcile owned tasks without moving navigation (`src/pages/AnnotationOperations.tsx:705–714`, `3166–3243`).
- Entry binds account/project/router identity, mutation-context identity, current permission and browser owner; unfinished owned tasks are preferred over new allocation (`src/pages/AnnotationOperations.tsx:3276–3286`, `3307–3337`).
- Stop changes only continuous intent and leaves the current assignment intact; failed/unknown operations pause while retaining stage reconciliation (`src/hooks/useAnnotationWorkSession.ts:182–190`; `src/pages/AnnotationOperations.tsx:2290–2298`, `2582–2590`, `3656–3670`).
- Public HTTP tests assert replayed ownership and remaining pool count, plus retained pending-stage/version/ownership after rejected mutations (`internal/api/annotation_continuous_recovery_test.go:13–46`, `49–78`). Removal of the obsolete return-to-pool source assertion does not substitute another source-shape claim for browser acceptance (`tests/frontend/annotation-operation-latency.test.mjs:24–25`).
### Issues
#### Critical (Must Fix)
- None found.
#### Important (Should Fix)
- None found in the reviewed implementation; integrated browser acceptance is still pending, as noted above.
#### Minor (Nice to Have)
- `src/pages/AnnotationOperations.tsx:3505`: the work-page header always says “完成本条任务后暂停”, including when the new continuous region says “连续工作中”. The controller observed the contradiction in the real browser, and a focused source check confirms the static text. Condition this subtitle on continuous/paused state, or use neutral guidance, so users can trust whether another task will be claimed.
- `.superpowers/sdd/annotation-keyboard-workflow/task-11-report.md`, “Final verification”: DEP0205/module.register and large-chunk warnings remain inherited build noise. They are recorded, not introduced by this task, and are not blockers here.
### Checks Performed
- Read `review-11.diff` once in bounded chunks for base `c8027d7daf60393e9d08c4d6b58b93f0d9a300cd` through `fe593f8e`; compared with task brief, issue 11, spec, CONTEXT and ADR-0001. No suites, Git operations, UI/API actions or fixture mutations were performed.
- Named risk: async entry after ownership loss. The diff cuts off hook acquisition/lifecycle and owned-first entry functions; inspected their bounded surrounding code. Scope/pagehide/unmount invalidate pending acquisition, ownership gates entry, and inactive temporary sessions are released (`src/hooks/useAnnotationWorkSession.ts:85–124`; `src/pages/AnnotationOperations.tsx:3281–3286`, `3345–3348`).
- Named risk: stale submission polling after account/project changes. The diff cuts off the polling effect and callback dependencies; checked their bounded context plus account-reset and detail guards. Poll disposal/task guard, account-dependent project callback, and account reset invalidate old flow (`src/pages/AnnotationOperations.tsx:2558`, `2568`, `2594–2598`, `954–981`, `575–588`). No additional blocker identified.
- Named risk: contradictory operator guidance reported by the controller. One focused search confirmed the static subtitle at `src/pages/AnnotationOperations.tsx:3505`.
### Assessment
**Task quality:** Approved, subject to the controller completing the already-required browser gate.
**Reasoning:** The implementation preserves authoritative stage boundaries, durable logical claim recovery and single-browser ownership without changing backend scope rules. One minor operator-guidance inconsistency remains; no blocking implementation defect was found in this task-scoped review.

View File

@ -0,0 +1,115 @@
# Task 2 implementation report
## Status
Implementation, focused automated verification, controller-owned browser acceptance, and read-only review are complete. The reviewer approved the task with no Critical, Important, or Minor findings.
## Changes
- The parent slicing entry point now creates fresh IDs for both children and returns the left child ID. The workbench keeps that just-completed slice selected after `C` instead of falling back to the first slice.
- `C` explicitly pauses transport before applying the split, then seeks to the exact frame boundary without resuming playback.
- Playback bounds are phase-aware: slicing uses the whole Capture range, so Space crosses slice boundaries; annotation and materialization use the selected slice range.
- Time updates, end restart, ordinary frame stepping, and the range-clamp effect use the same phase-aware bounds. Slicing frame steps traverse the whole Capture; annotation frame steps remain selected-slice bounded and independent of playback speed.
- A later `C` resolves the slice containing the continuously advanced playhead instead of assuming the retained review selection still owns that time.
- Slicing displays Capture-relative progress once playback leaves the selected slice. Invalid boundary cuts preserve the partition and show a visible alert.
- Production split children retain the existing dictionary name and source lineage. The synchronized left/right hardware-frame mapping is unchanged.
## TDD evidence
RED:
```text
node --test tests/frontend/annotation-workbench.test.mjs
12 passed, 2 failed
splitting a selected slice returns two fresh children and keeps the completed child selected:
expected split result, received undefined
playback spans the Capture while slicing and the selected slice while annotating:
expected phase bounds, received undefined
```
GREEN:
```text
node --test tests/frontend/annotation-workbench.test.mjs
14 passed, 0 failed
```
Browser-gate regression RED and GREEN cycles:
```text
node --test tests/frontend/annotation-workbench.test.mjs
14 passed, 1 failed: sliceIndexAtPlayhead was undefined
node --test tests/frontend/annotation-workbench.test.mjs
15 passed, 0 failed
node --test tests/frontend/annotation-workbench.test.mjs
15 passed, 1 failed: boundary rejection returned no message
node --test tests/frontend/annotation-workbench.test.mjs
16 passed, 0 failed
```
The tests call executable production helpers and assert returned slice topology, fresh child IDs, selected child, input immutability, phase playback ranges, playhead ownership after continuous playback, and invalid-cut feedback. They do not inspect source strings or private React state.
## Verification evidence
Fresh post-commit verification:
```text
node --test tests/frontend/annotation-workbench.test.mjs tests/frontend/capture-annotation-workbench.test.mjs tests/frontend/unified-annotation-boundaries.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-playhead-draft.test.mjs
40 passed, 0 failed
npm run lint:web
tsc --noEmit; exit 0
git show --format= --check HEAD
exit 0
```
No full suite was run, per ticket instructions.
## Browser evidence
All browser checks used the real page with local frontend/API/Mongo only (`5173` / `3001` / `27018`) and the isolated `slice-primary` / `annotate-delayed` fixtures.
Initial RED: splitting the middle slice at frame `120.166667` selected the first slice and moved the playhead to `120.1`. The detailed initial capture is in `acceptance-evidence.md`.
The first implementation kept the new left child selected and paused both cameras at the exact cut (`left 120.166668`, `right 120.133335`); Space crossed the new boundary. That gate exposed two further selection couplings: a later `C` did nothing because it still targeted the retained left child, and at 4× ordinary Right jumped backward from `134.166667` to the selected child's end `120.166667`.
After the follow-up, continuous playback reached `127.566667`; a second `C` created the next split, selected its new left child, and paused at `left 127.566668` / `right 127.533335`. At 4×, Right advanced to `127.6` and Left returned to `127.566667`, one original hardware-frame step with dual-camera correspondence preserved. In annotation, Space near the selected end stopped at `120.1` with both cameras paused instead of crossing slices.
Boundary RED: `C` at Capture start preserved all three slices but the component only rendered its error inside annotation UI, so no prompt was visible. Final GREEN: the slicing `role=alert` displayed `当前帧位于切片边界,请移动到片段内部帧后再拆分。`; slice count stayed 3 and full `0–412` coverage remained unchanged.
## Files
- `src/lib/annotation-workbench.js`
- `src/pages/AnnotationOperations.tsx`
- `src/components/CaptureAnnotationWorkbench.tsx`
- `src/dev/CaptureAnnotationWorkbenchPreview.tsx`
- `tests/frontend/annotation-workbench.test.mjs`
## Self-review
- The left child is selected intentionally: it is the segment just completed by the cut and is the meaningful target for later review, while slicing playback is independent of selection and continues forward from the cut.
- Both child IDs are produced by the owning parent before state replacement, so the workbench never depends on a deleted source ID.
- The cut path pauses before both the parent update and exact seek, avoiding the transport queue's retained play intent.
- Annotation playback, time updates, ordinary frame stepping, and selection changes remain clamped to the selected slice. Slicing playback and ordinary stepping use the Capture bounds. The unified frame-boundary conversion and right-camera mapping were not changed.
- The production split copies the valid project-dictionary name to both children. Blank/invalid/discard meanings, ownership, review, persistence, and delivery behavior are untouched.
- Controller-owned changes in `.scratch/annotation-keyboard-workflow/issues/02-continuous-slice-playback.md` and `scripts/local/prepare-annotation-keyboard-fixtures.sh` were excluded from the commit.
## Commit
- `015c86de` — `🐛 Keep slice playback continuous after cuts`
- `4a6affea` — `🐛 Keep continuous slicing on the playhead`
- `d16e41b9` — `🐛 Show rejected slice cut feedback`
## Review
The read-only reviewer marked the task spec compliant and approved. The review found no Critical, Important, or Minor issues. Review: `task-2-review.md`.
## Concerns
- The full frontend suite was intentionally not run by this task agent.

View File

@ -0,0 +1,31 @@
### Spec Compliance
- ✅ Spec compliant. `C` pauses before mutation, cuts on the snapped frame, seeks back to that boundary, and selects the returned left-child ID (`src/components/CaptureAnnotationWorkbench.tsx:698`, `src/pages/AnnotationOperations.tsx:1832`). Slicing playback/steps use Capture bounds while annotation playback/steps use the selected slice (`src/components/CaptureAnnotationWorkbench.tsx:312`, `src/components/CaptureAnnotationWorkbench.tsx:507`, `src/components/CaptureAnnotationWorkbench.tsx:629`). Later cuts resolve the slice containing the playhead rather than the retained selection (`src/components/CaptureAnnotationWorkbench.tsx:313`, `src/components/CaptureAnnotationWorkbench.tsx:1121`).
- ✅ Boundary behavior is coherent: an exact shared boundary belongs to the right-hand slice under the half-open lookup, then is rejected as that slice's start; Capture start/end are likewise rejected without mutation and surface the slicing alert (`src/lib/annotation-workbench.js:33`, `src/lib/annotation-workbench.js:43`, `src/components/CaptureAnnotationWorkbench.tsx:1619`).
- ✅ Reported real-browser evidence covers the required integrated behavior: first and repeated cuts pause in place, Space crosses a new slicing boundary, 4× arrows move one hardware frame with dual mapping, annotation stops at the selected end, and boundary `C` preserves three slices with a visible alert (`.superpowers/sdd/annotation-keyboard-workflow/task-2-report.md:55`).
### Strengths
- Split construction is a small pure helper with fresh child IDs, unchanged dictionary name, explicit lineage, immutable input, and a meaningful selected child (`src/lib/annotation-workbench.js:9`, `tests/frontend/annotation-workbench.test.mjs:24`).
- One phase-aware bounds value drives time updates, restart, clamping, and ordinary stepping, avoiding divergent playback rules (`src/components/CaptureAnnotationWorkbench.tsx:312`, `src/components/CaptureAnnotationWorkbench.tsx:507`, `src/components/CaptureAnnotationWorkbench.tsx:603`, `src/components/CaptureAnnotationWorkbench.tsx:652`).
- Focused risk check: `applySliceChange` rejects edits to discarded slices before replacing state, preserves descriptions, and recomputes statuses (`src/pages/AnnotationOperations.tsx:1714`); the existing synchronized seek mapping remains unchanged (`src/components/CaptureAnnotationWorkbench.tsx:495`).
### Issues
#### Critical (Must Fix)
- None.
#### Important (Should Fix)
- None.
#### Minor (Nice to Have)
- None.
### Assessment
**Task quality:** Approved
**Reasoning:** The implementation satisfies A01/A03 and the ticket constraints with consistent phase bounds, correct playhead ownership at interior and boundary positions, and direct browser evidence for transport, selection, frame-step, dual-camera, and rejection behavior. Reported verification is clean: 40 focused tests and web type/lint checks passed.

View File

@ -0,0 +1,19 @@
### Finding Verdicts
- **Ctrl/Command+Enter on a focused native button is resolved as a description save instead of remaining owned by the native control** — ADDRESSED. The resolver now returns `null` for modified Enter when `nativeControl` is true unless the target is the description textarea (`src/lib/annotation-shortcuts.js:15`). The description textarea still returns `save`, and the focused description editor remains able to save (`tests/frontend/annotation-shortcuts.test.mjs:70`). The reported RED-to-GREEN run names this focused test and records 9 passing tests after the change.
### New Breakage in the Fix Diff
- None. The guard is limited to the modified-Enter branch and preserves existing editable-input rejection, textarea save, editor-area save, composition suppression, and unmodified native Space/Enter handling (`src/lib/annotation-shortcuts.js:12`, `src/lib/annotation-shortcuts.js:14`, `src/lib/annotation-shortcuts.js:20`).
### Out-of-Scope Observations
- None. The previously reported OS IME and native textarea undo items remain explicit browser-evidence limits, not coded defects established by this fix review.
### Verdict
**Fix round:** All findings addressed, no new Critical/Important breakage.
**Final spec status:** ✅ Spec compliant for the task-scoped implementation.
**Final task quality:** Approved.

View File

@ -0,0 +1,149 @@
# Task 3 implementation report
## Status
Implementation, focused automated verification, and the controller-owned real-browser/API gate are complete. Independent read-only review is pending.
## Changes
- `N` starts a new action interval. While the end is being selected, a second `N` now resolves to the same end-confirmation action as Enter.
- End confirmation pauses on the selected hardware-frame boundary and focuses the visible action-description editing area instead of entering the textarea. Enter from that area begins manual text input.
- `F` is the primary dictionary shortcut and `D` remains compatible in both slice naming and action-description contexts.
- Description template selection fills editable text, returns focus to the editing area, and does not save. `Ctrl/⌘+Enter` is still the only keyboard save action for the current description.
- Incomplete end selection and empty content use the existing visible error messages. Save failure paths retain the editor and draft through the existing ticket 01 authoritative mutation flow.
- One `Esc` from a description input or either dictionary returns focus to the workbench. The following Space controls playback instead of reactivating the old dictionary trigger.
- Text inputs, IME composition, native Space/Enter activation, key repeats, and open dialogs keep their existing event ownership. Shortcut help now changes between idle annotation, end selection, description editing, and slice naming contexts.
## TDD evidence
RED cycle 1:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs
4 passed, 3 failed
F returned null instead of dictionary; repeated F returned null instead of consume;
the second N returned new instead of confirm-end.
```
GREEN cycle 1:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs
7 passed, 0 failed
```
RED cycle 2:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs
7 passed, 1 failed
Context help did not expose F / D or change its end-selection/editing labels.
```
GREEN and context-filter refinement:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs
8 passed, 0 failed
```
The shortcut tests exercise the exported production resolver and context-help function. They cover F/D, N/N, editing-area Enter, Ctrl/⌘+Enter, IME/keyCode 229, editable inputs, native controls, modal dictionary ownership, and repeat suppression. They supplement rather than replace the real-browser interaction gate.
## Verification evidence
Fresh pre-commit verification:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs tests/frontend/slice-dictionary.test.mjs tests/frontend/capture-annotation-workbench.test.mjs tests/frontend/annotation-workbench.test.mjs tests/frontend/annotation-playhead-draft.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs
50 passed, 0 failed
npm run lint:web
tsc --noEmit; exit 0
npm run build:web
exit 0; Vite built 3,202 modules. Existing large-chunk advisory only.
npx prettier --check src/lib/annotation-shortcuts.js src/components/CaptureAnnotationWorkbench.tsx src/components/SliceNameDictionaryPicker.tsx tests/frontend/annotation-shortcuts.test.mjs
exit 0
```
No full test suite was run, per ticket instructions.
## Browser and API evidence
The controller ran the gate on the real annotation page with the isolated `annotate-delayed` fixture and local frontend/API/Mongo only (`5173` / `3001` / `27018`). Detailed captures are recorded in `acceptance-evidence.md`.
- `N`, Right, `N` selected `0.033333–0.066667` and focused the `DIV` labeled `动作描述编辑区`. The textarea was not focused.
- The `N`/Enter variant also confirmed the end and focused the editing area.
- `Ctrl/⌘+Enter` before a valid end displayed the incomplete-end alert; saving an empty confirmed interval displayed the empty-description alert. Neither action submitted the stage.
- `F` opened the description dictionary. ArrowDown/Enter inserted an editable template and returned focus to the editing area. `D` opened the same dictionary.
- Enter focused the textarea; typed `f` and Space remained literal text. `Cmd+Enter` saved through the real API, advanced the item from version 2 to 3, and independent API readback returned the expected Chinese/template plus typed text.
- One Esc closed the dictionary, retained the draft, and returned focus to the workbench. The next Space played both synchronized videos and did not reopen the dictionary.
- In slicing, `F` opened the actual three-entry project slice-name dictionary. One Esc returned focus to the workbench and the next Space played both videos. `D`, ArrowDown, and Enter selected the current valid dictionary name once and closed without saving or submitting.
All browser/API evidence above was collected and reported by the controller; this task agent did not create a separate browser harness.
## Files
- `src/lib/annotation-shortcuts.js`
- `src/components/CaptureAnnotationWorkbench.tsx`
- `src/components/SliceNameDictionaryPicker.tsx`
- `tests/frontend/annotation-shortcuts.test.mjs`
## Self-review
- The shortcut resolver remains the single public keyboard seam. State-sensitive meanings are passed explicitly (`selectingEnd`, `descriptionEditor`) rather than inferred from DOM source or duplicated in tests.
- End confirmation still uses `endSelectionRef` and the existing frame-boundary/playhead machinery. Ticket 02 capture-wide slicing bounds, annotation slice bounds, step behavior, and stereo mapping were not changed.
- Description persistence still calls `confirmAnnotation` and the parent `onConfirmAnnotations` contract. Ticket 01 mutation fencing, reconciliation, failure retention, versions, ownership, and server authority were not changed.
- Dictionary selection only fills existing slice names or editable description text. It does not alter boundaries or save. Semantic blank, explicit invalid, and discarded-slice behavior remains distinct.
- The interaction performs at most one workbench action per event: composing/default-prevented events return early, repeats are consumed except frame stepping, editable inputs own ordinary keys, native controls own Space/Enter, and open dialogs stop workbench dispatch.
- The visible editing region has programmatic focus and a focus-visible ring. Incomplete and empty save errors are rendered with `role=alert`.
- The controller-owned issue status change was left unstaged and excluded from the implementation commit.
## Remaining gaps
- Independent read-only review is pending at report time.
- Native textarea cut was exercised after actual `a`/`b`/`c` keypresses: SelectAll/Cut emptied only the textarea and did not dispatch playback, dictionary, or data-history actions. The embedded browser did not restore the cut text with either Cmd+Z or Ctrl+Z, so native undo restoration is not claimed. Resolver tests confirm those input combinations return no workbench action; the later history ticket must verify they never dispatch data-history undo.
- Chinese text entry was browser-verified, but an actual operating-system IME composition session was not exercised. The focused resolver tests cover `isComposing` and keyCode 229 suppression.
## Commit
`94ba5fa2` — `⌨️ Complete keyboard description editing`
No push.
## Fix round 1: native modified-Enter ownership
The first read-only review found that the resolver handled Ctrl/⌘+Enter before its native-control guard. A focused button could therefore bubble `save` to the workbench, have its native event prevented, and save the current draft.
The fix returns no workbench action for modified Enter on a native control unless the target is the action-description textarea. Ctrl/⌘+Enter from the textarea and the focused description editing area still resolves to `save`.
RED:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs
8 passed, 1 failed
native controls own modified Enter while description editing still saves:
expected null, received save
```
GREEN and covering verification:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs
9 passed, 0 failed
npm run lint:web
tsc --noEmit; exit 0
npx prettier --check src/lib/annotation-shortcuts.js tests/frontend/annotation-shortcuts.test.mjs
exit 0
git show --format= --check HEAD
exit 0
```
Fix commit: `350448f2` — `🐛 Preserve native modified-Enter ownership`.

View File

@ -0,0 +1,32 @@
### Spec Compliance
- ❌ Issues found: the requested N/N and N/Enter endpoint confirmation, editing-area focus, F-primary/D-compatible dictionaries, explicit template save, incomplete/empty-draft feedback, one-Esc workbench return, contextual help, and persisted browser/API save are implemented (`src/components/CaptureAnnotationWorkbench.tsx:832`, `src/components/CaptureAnnotationWorkbench.tsx:858`, `src/components/CaptureAnnotationWorkbench.tsx:1158`, `src/components/CaptureAnnotationWorkbench.tsx:2397`, `src/components/CaptureAnnotationWorkbench.tsx:2670`; `src/lib/annotation-shortcuts.js:22`). However, a focused native button does not retain ownership of Ctrl/Command+Enter: the resolver returns `save` before consulting `nativeControl`, and the workbench then prevents the native event and calls `confirmAnnotation` (`src/lib/annotation-shortcuts.js:14`, `src/components/CaptureAnnotationWorkbench.tsx:1185`, `src/components/CaptureAnnotationWorkbench.tsx:1210`).
- ⚠️ Cannot verify from the supplied browser evidence: an actual operating-system IME composition session and native textarea undo restoration. The code suppresses workbench dispatch for composition/keyCode 229 and returns no action for ordinary Ctrl/Command+Z in editables (`src/lib/annotation-shortcuts.js:12`, `src/lib/annotation-shortcuts.js:17`), and focused tests cover parser ownership (`tests/frontend/annotation-shortcuts.test.mjs:37`), but `acceptance-evidence.md` explicitly says real OS composition was not exercised and embedded-browser Cmd/Ctrl+Z did not restore the cut text. The later history gate should also verify that text-editing undo never reaches data-history dispatch.
### Strengths
- Endpoint confirmation validates the interval, pauses/seeks on the existing frame-aware path, and focuses a programmatically focusable editing region rather than the textarea (`src/components/CaptureAnnotationWorkbench.tsx:832`, `src/components/CaptureAnnotationWorkbench.tsx:851`, `src/components/CaptureAnnotationWorkbench.tsx:855`, `src/components/CaptureAnnotationWorkbench.tsx:2397`).
- Incomplete endpoint and empty description saves stop with visible feedback before the existing authoritative write callback; no stage-submit path was added (`src/components/CaptureAnnotationWorkbench.tsx:858`, `src/components/CaptureAnnotationWorkbench.tsx:869`, `src/components/CaptureAnnotationWorkbench.tsx:897`, `src/components/CaptureAnnotationWorkbench.tsx:926`).
- Template selection changes only editable description state, closes the dialog, and returns focus to the editing area without persisting (`src/components/CaptureAnnotationWorkbench.tsx:711`). Both dictionary components route Esc through a single close path that returns focus to the workbench (`src/components/CaptureAnnotationWorkbench.tsx:1108`, `src/components/CaptureAnnotationWorkbench.tsx:2688`; `src/components/SliceNameDictionaryPicker.tsx:35`).
- The production resolver keeps IME/default-prevented/repeat handling centralized and makes N and Enter meanings explicit from context (`src/lib/annotation-shortcuts.js:2`, `src/lib/annotation-shortcuts.js:12`, `src/lib/annotation-shortcuts.js:27`). The focused tests exercise F/D, N/N, editing-area Enter, repeat suppression, dictionary ownership, and contextual help (`tests/frontend/annotation-shortcuts.test.mjs:12`, `tests/frontend/annotation-shortcuts.test.mjs:58`, `tests/frontend/annotation-shortcuts.test.mjs:70`, `tests/frontend/annotation-shortcuts.test.mjs:77`, `tests/frontend/annotation-shortcuts.test.mjs:138`).
- The supplied real-browser evidence covers the complete local N-to-save journey and API readback, both dictionary contexts, draft-preserving Esc followed by playback, incomplete/empty validation, and literal text entry. Reported focused tests, typecheck/lint, build, and formatting are clean; no reported warning indicates a task regression.
### Issues
#### Critical (Must Fix)
- None.
#### Important (Should Fix)
- `src/lib/annotation-shortcuts.js:14` — Ctrl/Command+Enter is resolved before native-control ownership is checked. With any focused button in the description editor, the ancestor handler receives `save`, calls `preventDefault`, and invokes `confirmAnnotation` (`src/components/CaptureAnnotationWorkbench.tsx:1185`, `src/components/CaptureAnnotationWorkbench.tsx:1210`) instead of leaving the event with the button. This violates the explicit native-control ownership rule and can save a draft when the user acts on a focused button with the modifier held. Guard modified Enter on native controls other than the description textarea, and add a resolver test beside `tests/frontend/annotation-shortcuts.test.mjs:58` for Ctrl/Command+Enter with `nativeControl: true`.
#### Minor (Nice to Have)
- None.
### Assessment
**Task quality:** Needs fixes
**Reasoning:** The state-sensitive workflow, validation, focus transfer, and real-browser persistence evidence are strong, and the change preserves the existing frame and authoritative-save paths. The native-button Ctrl/Command+Enter ownership hole is an explicit task requirement and an unintended-save risk, so the task should not pass until it is guarded and tested; OS IME and native undo remain stated evidence gaps rather than hidden claims.

View File

@ -0,0 +1,29 @@
### Spec Compliance
- ✅ Spec compliant for task 04 at `d4cd2b18`, with the original Important Back-protection finding **ADDRESSED**.
### Per-finding Recheck
- **ADDRESSED — Browser Back bypasses unsaved protection and loses the draft.** `src/pages/AnnotationOperations.tsx:1228` now uses the router's supported blocker for dirty pathname/search navigation. The confirmation modal observes the blocked state (`:2906`), cancellation resets the blocker and restores workbench focus (`:2853–2856`), and confirmed discard clears the session editor before proceeding (`:2859–2871`). The custom popstate/index and link interception is removed.
- **Controller browser confirmation:** the exact prior Dashboard → annotation center → project/task → valid draft → Back failure now restores the task URL and shows the modal; Escape retains the text and SECTION focus. A second Back with confirmed discard reaches Dashboard, and Forward loads saved server state without the discarded editor. Controller reports API version 3 unchanged and zero fixture POST requests.
### Cross-cutting Routing Check
- `src/App.tsx:162–263`: the new singleton data router wraps the existing application route tree with a wildcard root. Comparing the removed and added tree in the supplied diff shows the same routes, plugin guards, role guard, Layout, error boundary and Suspense nesting. User/plugin/theme/time-zone providers retain their previous outer placement. This supplies the required data-router context for `useBlocker`; no route or permission change was introduced by this fix.
- `src/pages/AnnotationOperations.tsx:1373–1381`: native beforeunload protection remains for document departure. Its OS/browser-native confirmation was not directly verified by the controller; that limitation is explicit and does not reopen the fixed SPA Back failure.
### New Fix Breakage
- None identified in the scoped `52263727..d4cd2b18` diff.
- The controller separately confirmed natural B end-stop, V resolution after deleting the original slice, and same-task accepted discard. The pre-existing mouse-delete focus loss is carried to task 05 and is outside this fix.
### Checks
- Read the fix diff and updated implementation report. Reviewed the App wrapper as the named cross-cutting routing risk. No broader source crawl, nested agents, Git mutation or reported-test rerun.
- Reported validation: 56/56 focused tests, web lint, production build and diff check passed; existing deprecation/chunk warnings remain unchanged. Real browser evidence supplies the Back/cancel/accept/Forward behavioral gate.
### Assessment
**Task quality:** Approved.
**Reasoning:** The fix replaces the unreliable manual history guard with supported router blocking, preserves the existing route tree, and passes the controller's exact failing navigation sequence plus cancellation and accepted-discard checks. No new blocking issue was found.

View File

@ -0,0 +1,80 @@
# Task 04 implementation report
Status: implementation committed; remaining controller browser gates continue independently.
Commit: `6e95fa32b7503cffe232fc6047a1736413c82362` — ✨ Preserve slice drafts and add review navigation bookmarks.
Follow-up: `52263727` — 🩹 Reset discarded drafts when navigation reuses the task.
Fix round 1: `d4cd2b18` — 🛡️ Use router blockers to protect annotation drafts on navigation.
## Scope and interfaces
- Ctrl/Meta + left/right and matching mouse buttons pause at adjacent slice heads, including tail; endpoints do not wrap.
- Workbench keeps parked per-slice editor drafts plus unfinished end selections in page memory. Navigation never calls save APIs.
- B reviews selected slice with explicit slice playback bounds; V resolves the first recorded work frame against the current partition. Navigation captures that frame before the first B; repeated review does not overwrite it.
- Optional `onDraftsChange(drafts: AnnotationDraft[])` exposes `sliceId`, `annotation`, `selectingEnd`, and `isNew` to the parent. Parent includes drafts in leave protection. Workbench identity includes task, editing phase, review stage, and account; reset does not depend on unstable arrays/callback props.
- `capturePlaybackBounds` gains optional fifth `reviewing` argument, false by default. Existing callers retain phase semantics.
- In-app task/return/link/history departure uses the existing page confirmation modal. Cancel/one Escape restores workbench focus; the parent host ref scopes that focus target. Native `beforeunload` remains for refresh/close. After a controller-reproduced Back failure, the final implementation uses React Router's `useBlocker` reset/proceed API; manual link and popstate interception was removed.
- Open blank split descriptions also count as outstanding even if their interval already exists in local parent segments. Drafts remain in memory only; no storage persistence was introduced.
## Red / green evidence
1. `node --test tests/frontend/annotation-shortcuts.test.mjs`: RED, 9 passed / 1 failed; Ctrl-arrow returned null instead of `navigate-slice`. Added approved keys with editable/composition/repeat guards. GREEN: 10/10.
2. `node --test --test-name-pattern='explicit slice review' tests/frontend/annotation-workbench.test.mjs`: RED, expected review bounds 2–6, actual Capture bounds 0–9. Added review bounds to existing public frame/playback seam.
3. `node --test tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-workbench.test.mjs`: 27/27 GREEN. Initial run exposed an obsolete source-string assertion prohibiting previous/next slice labels; removed only that now-conflicting assertion. No new source-string assertions or private-state tests added.
4. `node --test tests/frontend/annotation-playhead-draft.test.mjs tests/frontend/annotation-timeline-initialization.test.mjs tests/frontend/annotation-timeline-wire.test.mjs`: 14/14 GREEN.
5. `npm run lint:web`: passed, exit 0. Initial implementation check identified an `Object.entries` inference issue; explicit record type fixed it.
6. `npm run build:web`: passed, exit 0, 3202 modules transformed. Existing Node module.register deprecation and bundle >500 kB warnings.
7. Final verification after the focus-restoration patch: combined five-file command below passed 41/41; `npm run lint:web`, `npm run build:web`, and `git diff --check` all exited 0.
```
node --test tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-workbench.test.mjs tests/frontend/annotation-playhead-draft.test.mjs tests/frontend/annotation-timeline-initialization.test.mjs tests/frontend/annotation-timeline-wire.test.mjs
```
No full frontend/backend suite, no company/BOS mutation, no remote operation, no push. Browser and existing public API acceptance are owned by controller. Controller reproduced initial RED: Ctrl+Right did not navigate, mouse switching lost unsaved editor, no save request occurred. Do not treat focused pure tests as browser acceptance.
## Files
- src/components/CaptureAnnotationWorkbench.tsx
- src/App.tsx (fix round 1: supported router wrapper, existing route tree preserved)
- src/pages/AnnotationOperations.tsx
- src/lib/annotation-shortcuts.js
- src/lib/annotation-workbench.js
- tests/frontend/annotation-shortcuts.test.mjs
- tests/frontend/annotation-workbench.test.mjs
## Browser evidence (controller-reported)
- Initial RED on the preimplementation build: Ctrl+Right did not navigate; mouse switching lost the unsaved draft; navigation made no save request.
- Stable core gate passed: slice 001 text draft at 0.166667–0.2 survived Ctrl navigation; slice 002 unfinished end point restored at 0.1; tail 003 was reachable with no wrap. B began selected-slice playback without altering the pending endpoint. Repeated B, frame stepping and two navigations followed by V restored slice 001 at 0.2, paused, with its text draft intact.
- An initial native in-app confirmation blocked the browser automation connection; replaced all newly added in-app native confirmations with the existing modal. Controller subsequently observed the new modal, cancel retaining parked drafts, and no writes.
- Controller caught Escape leaving focus on BODY after modal dismissal. Fixed both Escape and Continue Editing to focus the live workbench. Controller confirmed one Escape followed immediately by Ctrl+Left restored slice 001 with its text draft and SECTION focus.
- Controller then caught accepted header-link discard reusing the same task/component and retaining the old draft despite clearing the aggregate dirty flag. Follow-up explicitly unmounts detail and requests authoritative data through the existing task GET; same-task route reuse now gets a fresh workbench and saved parent data. This is a browser RED driven correction; focused 41/41, lint and build all passed again. Controller owns final browser GREEN.
- Controller subsequently confirmed same-task accepted discard cleared the editor and reloaded the two server-saved segments; B on a short 0–0.133333 slice stopped naturally with both cameras paused; after deleting the bookmarked slice V resolved the current merged slice at 0.233333 correctly.
## Fix round 1: browser Back protection (base 52263727)
- Browser RED: Dashboard → annotation center → fixture project → My Tasks → annotate-delayed → valid text draft → Escape → browser Back. Actual URL became `/`, Dashboard rendered and the workbench/draft disappeared without confirmation. Reviewer classified this Important. This result supersedes earlier claims about the manual popstate guard.
- Investigation read installed React Router 7.17.0 source (package range ^7.14.0) and the [official useBlocker documentation](https://reactrouter.com/api/hooks/useBlocker). The page guard depended on a dirty effect and numeric, distinct browser history indexes and could return without protecting navigation. The exact bypass condition from the failing browser was not instrumented, so no claim that listener order caused the loss is made.
- Root explicitly approved the bounded router integration: `createBrowserRouter` / `RouterProvider` wraps the existing route tree, Layout and guards; no route definitions or permissions changed. `useBlocker` owns all SPA route/history blocking, and the page modal calls reset or proceed. Beforeunload remains for document unload. Dirty ref is cleared synchronously only on already-confirmed discard/completed close, preventing a second confirmation for the same authorized navigation.
- Scope risk: App.tsx router integration affects all routes. Existing route/navigation focused tests and compilation supplement the required real browser Back/cancel/accept checks; they are not treated as proof of browser behavior.
- Fresh focused command with the two existing routing files plus the prior five files passed 56/56; `npm run lint:web`, `npm run build:web` and `git diff --check` passed. Build retains existing deprecation and large-chunk warnings.
- Controller browser GREEN repeated the exact Dashboard → annotation/project/task → valid draft → Back flow: current task URL was restored and app modal shown; Escape restored SECTION focus with text intact. Back again and confirmed discard reached Dashboard `/`; Forward reloaded the task with no unsaved editor/draft. No POST logs occurred; controller's API readback and scoped reviewer recheck continue.
```
node --test tests/frontend/plugin-navigation.test.mjs tests/frontend/annotation-operations.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-workbench.test.mjs tests/frontend/annotation-playhead-draft.test.mjs tests/frontend/annotation-timeline-initialization.test.mjs tests/frontend/annotation-timeline-wire.test.mjs
```
## Self-review and limitations
- Reviewed immutable parked snapshots and captured the leaving end-selection ref before restoring the target. This avoids mixing the target selection into the departing draft through a deferred state updater.
- Review playback bounds remain explicit; normal Space and C resume the task02 Capture slicing behavior. Bookmark return resolves its legal frame against the current partition and never selects a stored obsolete slice ID.
- Draft/bookmark reset depends on task and phase; parent identity also includes stage/account. Confirm callbacks and task01 authoritative API fence remain unchanged. No save call is introduced by navigation.
- In-app leave guards account for current and parked drafts. SPA Back/Forward now uses the supported router blocker; cross-document refresh/close relies on native beforeunload. Replacement Back/cancel/accept/Forward, review end-stop, edited/deleted bookmark ownership, same-task accepted discard and modal focus have passed controller gates as detailed above.
- No new history, undo/redo or stage-confirmation behavior. No full-suite run; only 41 focused frontend tests. No backend changes.
- Prettier applied to touched code; unrelated preexisting test formatting was restored. The controller's `.scratch` ticket modification remains unstaged. This report is local coordination output, not part of the code commit.
## Handoff
- Code is committed and stable for controller's remaining browser/public-API gates and formal review.
- Final task range ends at `d4cd2b18`; scoped navigation fix range is `52263727..d4cd2b18`. Reviewer must include App.tsx router wrapper plus AnnotationOperations blocker changes. Last scoped check was 56/56 focused frontend tests, lint and production build passing.
- Postcommit `git status --short` showed only the controller-owned task 04 issue file modified. No push.

View File

@ -0,0 +1,40 @@
### Spec Compliance
- ❌ Issues found: the required unsaved-leave protection fails on actual browser Back; an unsaved description is lost when Back reaches Dashboard without confirmation (`src/pages/AnnotationOperations.tsx:1398–1410`).
- ✅ Navigation parks complete editor/end-selection snapshots without a save call, includes adjacent tail slices without wrapping, and records the original review position before navigation (`src/components/CaptureAnnotationWorkbench.tsx:634–680`). V resolves the saved frame against the current partition (`src/components/CaptureAnnotationWorkbench.tsx:681–689`).
- ✅ Outstanding current and parked drafts are exposed through the optional parent callback; task/phase and task/stage/account identities reset session state (`src/components/CaptureAnnotationWorkbench.tsx:300–319`, `src/components/CaptureAnnotationWorkbench.tsx:361–384`, `src/pages/AnnotationOperations.tsx:3728–3729`).
- ⚠️ Cannot verify from diff: controller browser gates for B reaching the slice end, V after slice ownership changes, accepted same-task discard after the follow-up fix, and browser Back cancel/accept remain required. Hardware-frame/dictionary/ownership authority is largely unchanged; no claim that this task independently revalidates every existing contract.
### Strengths
- `src/components/CaptureAnnotationWorkbench.tsx:641–658`: the departing end-selection ref is copied before restoring the target, preserving its live pending endpoint rather than a stale state snapshot.
- `src/components/CaptureAnnotationWorkbench.tsx:671–689`: review playback bounds are explicit and the return bookmark stores a frame, then finds its surviving slice, avoiding restoration of obsolete slice IDs.
- `src/components/CaptureAnnotationWorkbench.tsx:361–381`: aggregate dirty state includes parked drafts and unchanged-but-blank split descriptions that still require explicit completion.
- `src/pages/AnnotationOperations.tsx:2898–2908`: confirmed link discard explicitly unmounts the editor and reloads authoritative data, addressing same-task component reuse.
### Issues
#### Critical (Must Fix)
- None identified in the scoped diff.
#### Important (Should Fix)
- **Browser Back bypasses unsaved protection and loses the draft** — `src/pages/AnnotationOperations.tsx:1398–1410`. The guard only intercepts nonzero deltas between numeric history indices. Controller browser evidence at HEAD `52263727`: Dashboard → 标注中心 → fixture project → 我的任务 → continue `annotate-delayed`; create a valid N/Right/N description, enter text, Escape, then browser Back. The URL changes from the annotation workflow/task URL to `/`, Dashboard renders, and the workbench/draft disappears without a confirmation dialog. This is an actual loss, not merely an equivalent URL change. Make same-document route departure reliably block until discard is accepted, including this navigation path. Verify Back cancellation preserves URL/editor/text and accepted discard exits once. The exact index/listener failure mechanism is not established by the browser observation.
#### Minor (Nice to Have)
- **Reported build output is not pristine (pre-existing)** — `.superpowers/sdd/annotation-keyboard-workflow/task-4-report.md`, Red / green evidence item 6: build passed with the existing Node module.register deprecation and >500 kB bundle warnings. These are acknowledged existing warnings, not a newly introduced task regression.
### Checks and scope
- Read the task brief, report, and full `9027a79b..52263727` review package; the first tool output was truncated, so the missing middle diff span was fetched separately. No reported tests were rerun and no Git operation was performed.
- Named outside-diff risk — navigation seeking a different slice could clamp to the old selected slice: inspected the otherwise omitted `publishSeekTarget`/`seek` implementation at `src/components/CaptureAnnotationWorkbench.tsx:578–592`; it clamps to Capture bounds, so the new call does not introduce that issue.
- Named outside-diff risk — history interception could race React Router or rely on incompatible history state: inspected the installed router implementation at `node_modules/react-router/dist/production/chunk-RTRY3JFT.js:273–345`; missing indices initialize to 0, push increments, replace preserves, and popstate listens without capture. The task guard uses capture. Source inspection alone does not explain or negate the controller's reproduced Back data loss.
- Browser evidence was read from `acceptance-evidence.md` and supplemented by the controller's direct Back reproduction at HEAD `52263727`; no private application-state assertions were used.
### Assessment
**Task quality:** Needs fixes.
**Reasoning:** Draft parking and review navigation are narrowly implemented, with useful controller browser evidence for the core workflow. The reproduced unsaved-draft loss on browser Back violates a binding task requirement and blocks approval until fixed and rechecked.

View File

@ -0,0 +1,60 @@
# Ticket 05 implementation report
## Scope and commit
Implemented the approved current-task/current-stage slice edit history on the existing workbench, replacing the disconnected `sliceHistory`/`undoSlice` path.
- Commit: `e09ad03f` — `↩️ Add stage-scoped slice undo and redo history`
- Base: `a5932e8050358328ea60e7a2070e9a8d06e4089a`
- Current branch preserved; local commit only. No push, deploy, remote/BOS writes, fixture mutations or worktree switch by this implementer.
- `.scratch` issue/report modifications owned by controller were left unstaged.
## Files and production contract
- `src/lib/annotation-history.js`: session history with `record({ before, after })`, `undo(restore)`, `redo(restore)`, and `clear()`. The public restoration callback receives a cloned snapshot; only explicit `true` (sync or async) advances history. `false`/throw leaves it recoverable. Both commands share the one-second acceptance window; a pending restoration excludes further commands. Last 100 entries retained; edits replace the redo branch; clear invalidates delayed completion.
- `src/pages/AnnotationOperations.tsx`: records complete slice workspace snapshots (slices including names/disposition fields, operations, touching description segments, statuses, affected location). Boundary drag has one before/after transaction and one operation even across many pointer moves; unchanged boundary/name edits do not record. Existing name changes also record to prevent undo of an older split silently erasing later naming. Restores through one coordinator callback gated by ownership, authoritative mutation busy state, saving/submission lock, frame readiness and slice phase. Existing disposition-save history clear retained. Task/account/stage/phase changes and generation/reset/submission request dispatch clear history; local validation/confirmation dialogs do not.
- `src/components/CaptureAnnotationWorkbench.tsx`: adds `onHistoryCommand`, `historyReveal`, `onSliceBoundaryEditStart`, `onSliceBoundaryEditEnd` props. Revealing a restored snapshot selects its affected slice/time, pauses and focuses the workbench without altering the review bookmark. Mouse delete immediately returns focus to workbench so keyboard undo works after its button unmounts. Completed drag returns focus too.
- `src/lib/annotation-shortcuts.js`: Ctrl/Command+Z and Ctrl/Command+Shift+Z, ignoring held repeats and preserving text/IME native behavior. Slice-phase help lists shortcuts.
- `tests/frontend/annotation-history.test.mjs` and `tests/frontend/annotation-shortcuts.test.mjs`: public restoration outcomes, capacity, clock edge, invalidation, confirmation/failure and key contexts. No private-stack or source-string acceptance assertions added.
Ticket06 can reuse the history callback for server-confirmed restores and extend the snapshot/command union for saved descriptions and N start/end. It must retain the coordinator's authoritative mutation token fencing; the history revision fence protects history itself, not arbitrary async callback side effects. This ticket intentionally does not implement persisted-description undo.
## Red → green evidence
1. `node --test tests/frontend/annotation-shortcuts.test.mjs`
- RED: 10 passed, 1 failed; expected `undo`, actual `null` for Ctrl+Z.
- GREEN after resolver implementation: 11 passed, 0 failed.
2. `node --test tests/frontend/annotation-history.test.mjs`
- Initial RED: public creator absent (`undefined` vs `function`). Added minimal record/undo/redo with restoration output test; GREEN 1/1.
- Shared clock RED: redo at 999 ms returned true instead of false. Added shared acceptance clock; GREEN 2/2.
- Capacity RED: 101st undo returned true instead of false. Retained latest 100; GREEN 3/3.
- Boundary RED: `history.clear is not a function`. Added revision invalidation/clear; GREEN 4/4.
- Pending restoration RED: second undo at 1000 ms accepted while prior callback unresolved. Added pending exclusion/finally; GREEN 5/5.
- Added public regression coverage for redo-branch replacement, snapshot isolation, rejected restoration recovery, and empty fresh page session; final history suite 8/8.
3. Controller-owned real-page RED on baseline, communicated by controller: slice-primary C at 0.133333 produced 4 slices; Ctrl+Z still left 4. Controller reset through the app; persisted 3-slice fixture remained unchanged, no POST.
## Final verification
- `node --test tests/frontend/annotation-history.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-workbench.test.mjs`: **36 passed, 0 failed**. The unchanged workbench file contains legacy structural coverage; it is not claimed as this ticket's browser acceptance evidence.
- `npm run lint:web`: **exit 0** (`tsc --noEmit`).
- `npm run build:web`: **exit 0**, Vite built 3203 modules. Existing Node DEP0205 deprecation and >500 kB chunk warnings were emitted.
- `git diff --check`: **exit 0** before commit.
- Full frontend/Go suite deliberately not run; controller owns final broad gate.
## Browser evidence and limitations
Controller owns all real-browser/API acceptance, including legal coverage/name/status restoration, deletion focus, cross-slice pause/location, drag-one-entry behavior, shared throttle/native text behavior and stage/task boundaries. Code-ready notification sent before build/self-review; production files frozen throughout controller gate. This implementer has not independently run the browser and does not claim those cases passed until controller confirms.
Self-review confirms normal playback, stepping and selection do not record history, all history data remains session-local, existing parked per-slice drafts/bookmark and leave guards are preserved, no server contract is bypassed, and discard writes cannot be undone through local history. Starting an actual generation/reset/submission request conservatively clears history once local guards pass and mutation scope is acquired, even if that request later fails; edits remain in the workspace. Existing save paths are unchanged.
## Controller stable browser evidence (gate HEAD e09ad03f)
Controller confirmed on the local real page after all build writes stopped:
- C at 0.133333: 3 → 4 slices; Ctrl+Z restores 3; immediate Ctrl+Shift+Z stays at 3 (shared throttle).
- Actual pointer drag of first boundary 120.1 → 141.7: one Ctrl+Z restores 120.1 (one meaningful drag entry).
- Fresh stable deletion of the second slice while the first was selected: mouse deletion restores SECTION focus; immediate Ctrl+Z restores 3 slices and paused playhead 120.1. Follow-up DOM explicitly shows current slice 002 with original range 120.1–216.066666.
- Ctrl+Shift+Z after the interval reapplies deletion: 2 slices, paused at 120.1.
- Initial delayed-redo/selection observations occurred while build/report verification was still completing and did not reproduce on the frozen commit. No production defect established; no speculative fix applied.
Further naming/new-edit/traversal/boundary coverage and formal review remain controller-owned. No HTML/build writes after stable gate notification.

View File

@ -0,0 +1,33 @@
### Spec Compliance
- ✅ Spec compliant for the implementation visible in `review-5.diff` (`a5932e80..e09ad03f`): shared session history, 100-entry capacity and one-second undo/redo clock (`src/lib/annotation-history.js:3`); native text/IME and held-repeat guards (`src/lib/annotation-shortcuts.js:12`); complete workspace restoration and affected-slice reveal (`src/pages/AnnotationOperations.tsx:2004`); task/account/phase/stage invalidation and actual generation/reset/submission dispatch invalidation (`src/pages/AnnotationOperations.tsx:575`, `:2077`, `:2119`, `:2233`).
- ⚠️ Integrated acceptance remains controller-owned: naming restoration, new-edit redo invalidation on the real page, traversal without recording, task/stage boundaries, and native input behavior. The public history/shortcut tests verify their isolated contracts; they do not prove coordinator/UI wiring (`tests/frontend/annotation-history.test.mjs:127`, `tests/frontend/annotation-shortcuts.test.mjs:210`; `task-5-report.md:60`).
- ⚠️ Persisted-description restore and async authoritative write fencing are task06 integration responsibilities. This task's production restore callback performs local state updates synchronously (`src/pages/AnnotationOperations.tsx:2017`). The shared module invalidates stack completion after clear but cannot cancel arbitrary callback side effects (`src/lib/annotation-history.js:17`); the report accurately states this boundary.
### Strengths
- Complete snapshots restore slices, operations, descriptions, statuses and reveal location together; a meaningful drag records once on completion and a drag returning to its initial workspace restores the original operations (`src/pages/AnnotationOperations.tsx:1746`, `:1757`, `:1798`, `:2017`).
- The public history contract requires explicit successful restoration, clones snapshots, rejects overlapping commands, and preserves recoverability after false/throw. Tests observe callback-visible restored values instead of private stack state (`src/lib/annotation-history.js:9`, `tests/frontend/annotation-history.test.mjs:77`, `:104`, `:153`).
- Mouse deletion and drag completion return focus to the workbench, enabling immediate keyboard recovery; the controller's stable browser evidence confirms delete/undo selection, paused location, throttle and one-drag undo (`src/components/CaptureAnnotationWorkbench.tsx:801`, `:1874`; `task-5-report.md:52`).
### Issues
#### Critical (Must Fix)
- None identified in this task diff.
#### Important (Should Fix)
- None identified in this task diff.
#### Minor (Nice to Have)
- `task-5-report.md:40`: the successful production build still emits existing DEP0205 and chunk-size warnings. These are inherited tooling/performance noise rather than an established regression from this task; retain them as existing verification debt rather than describing the build output as pristine.
### Assessment
- **Task quality: Approved.** The implementation has a clear coordinator-owned restore boundary, appropriate guards, and focused public behavior coverage; final integrated acceptance remains subject to the controller gates listed above.
- **Check performed:** reviewed the supplied diff once, recovering only its tool-truncated middle from the same diff file; no tests or git commands rerun.
- **Focused outside-diff check — pointer transaction termination:** inspected `CaptureAnnotationWorkbench.tsx:784` and `:1789`; pointer capture and pointer-up/cancel/lost-capture/leave handlers all reach the single drag completion path. No missing completion wiring identified.
- **Focused outside-diff check — reveal revision reuse after a task/phase boundary:** inspected `AnnotationOperations.tsx:3754`; the workbench key includes task, phase, stage and account, so the applied-revision ref remounts with those boundaries. No revision collision regression identified.
- **Focused outside-diff check — pause semantics on reveal:** inspected `CaptureAnnotationWorkbench.tsx:642`; `selectSlice` pauses playback, seeks the requested location and restores focus, and history passes `rememberPosition=false` (`:685`).

View File

@ -0,0 +1,69 @@
# Ticket 06 implementation report
Commit: `e59286cb` — `↩️ Restore saved annotation edits through stage history`.
Base: `b913bff0c73712d9548a3a68df9de4d660ff7e6b`. Current branch retained; local commit only.
## Implementation and integration contract
- `src/components/CaptureAnnotationWorkbench.tsx`: exports `AnnotationEditState` (affected slice/time, local segments, affected editor including complete end-selection) and `SliceEditor`. `onAnnotationEdit(before, after)` records local meaningful edits through the parent's same history. N start/end, end-adjustment entry, explicit start adjustment, split and completed shared-boundary drag record; intermediate playback/scrubbing does not. Existing saves, mouse deletion and batch-invalid pass the pre-edit state to `onConfirmAnnotations`. Deletion returns focus to workbench. History reveal restores only the affected editor; outgoing editor is parked, unrelated parked drafts remain intact. It pauses and focuses workbench or description editor. An in-progress annotation drag cannot dispatch keyboard history.
- `src/pages/AnnotationOperations.tsx`: extends the existing stage history snapshot union with annotation state plus a separate confirmed server workspace. This separation is necessary for undoing a save after a local split: incomplete local editor/segments are recoverable without misrepresenting them as saved server content. Local-only restoration performs no HTTP write. A differing confirmed workspace restores through the existing annotation confirmation endpoint, current confirmed version and task01 mutation token. Only confirmation (direct or exact next-version + matching workspace/owner/stage readback) advances history. Failed/unknown/conflicting writes keep recovery available, preserve local content and do not adopt competing versions. Save/delete/batch entries are recorded only after success. Existing task/account/stage/phase boundaries, 100-entry capacity and shared one-second command clock remain unchanged.
- `internal/api/annotation_history_http_test.go`: existing HTTP POST + GET seam verifies save/delete/restore with monotonic versions and sparse ranges, stale version refusal, changed ownership refusal, active processing refusal, and server content retained. Fixture setup uses MemoryStore; assertions observe responses/GET only. No business endpoint/schema added.
## Red → green and verification
Controller real-browser RED on base b913bff0 (reported before implementation gate): N at 0.166667 then Ctrl+Z left one editor; N end at 0.2, text `第六票撤销基线保存`, Ctrl+Enter saved v3→v4; root-focus Ctrl+Z left saved description visible and public API unchanged at v4.
HTTP characterization already had production support. Initial test fixture attempts failed because annotator GET is correctly forbidden after ownership changes, and because GET correctly recovers an orphaned submission reservation. The fixture was corrected to use authorized admin readback and a durable queued processing job. Exact ownership rejection is HTTP 409 `human_item_claim_required`; processing rejection is HTTP 409 `combined_submission_in_progress`. These fixture corrections are not claimed as production fixes or TDD feature RED.
Final commands:
- `node --test tests/frontend/annotation-history.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs`: 28 passed, 0 failed.
- `go test ./internal/api -run '^(TestAnnotationHistoryRestoresSavedDescriptionsThroughHTTP|TestAnnotationConfirmationRequiresMaterializedSlicesAndAcceptsSparseDescriptions|TestPendingCombinedSubmissionBlocksWorkspaceMutations)$' -count=1`: PASS, `ok droboticflow/internal/api 3.570s` after final assertion edits. One intermediate invocation was sandbox-blocked on Go cache access; approved cache access allowed final run.
- `npm run lint:web`: exit 0.
- `npm run build:web`: exit 0, 3203 modules, existing DEP0205 and >500 kB chunk warnings.
- `git diff --check`: exit 0 before commit.
- Full suites deliberately not run; root owns final broad verification.
## Self-review and gate limitations
No company/BOS writes, push, deployment, worktree switch or local live-fixture mutations by this implementer. Root owns browser/API fault proxy and live fixture acceptance. The implementer has not independently exercised a browser and does not claim browser GREEN yet. Existing drag/split remain local until explicit save, matching the previous workflow; history can separately recover both local edits and their later confirmation. Draft text continues to use native text undo; history records explicit interval edits and confirmed saves rather than every keystroke. No next-task, stage-confirmation or work-page shortcuts added.
All production/build writes stopped after the completed lint/build and commit, before the code-ready message. Await controller gate; any fixes require coordinated unfreeze.
## Review fix round 1 — authoritative revision baseline
Review Important P2 verified: absent stored workspaces are supported by the loader's revision fallback, but the first implementation used mutable local state as that path's saved-history baseline.
Commit `55a81c55` — `🩹 Preserve revision-backed annotation history baseline` (fix base `e59286cb`). Only `src/pages/AnnotationOperations.tsx` and `internal/api/annotation_history_http_test.go` committed.
The coordinator now retains a separate task-scoped confirmed workspace. The accepted load initializes it from the same authoritative slices, operations, annotations and statuses that initialize the page, including revision-backed data. Local splits/drags/editor changes never update it. Confirmed saves/reconciled success, disposition writes and reset success update it. Task clearing/switching invalidates it; a missing baseline blocks save/history rather than guessing from local edits. Exact `submittedVersion + 1` reconciliation and owner/stage/content checks are unchanged. Failed/unknown/conflicting operations do not adopt competing state or versions.
Added `TestAnnotationHistoryFirstSaveRestoresRevisionBackedDescriptionsThroughHTTP`: public GET returns one original 2–4 action from revisions with no stored workspace; first confirmation saves two split children; restoration with the original GET data restores precisely one 2–4 original action through the same public confirmation/GET endpoints. This characterizes supported server behavior; the frontend regression remains covered by the controller's real-browser gate, not falsely claimed as an HTTP-only RED.
Verification:
- `go test ./internal/api -run '^TestAnnotationHistoryFirstSaveRestoresRevisionBackedDescriptionsThroughHTTP$' -count=1`: PASS, `ok droboticflow/internal/api 0.512s`.
- `node --test tests/frontend/annotation-history.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs`: 28 passed, 0 failed.
- `go test ./internal/api -run '^(TestAnnotationHistory.*ThroughHTTP|TestAnnotationConfirmationRequiresMaterializedSlicesAndAcceptsSparseDescriptions|TestPendingCombinedSubmissionBlocksWorkspaceMutations)$' -count=1`: PASS, `ok droboticflow/internal/api 0.540s`. Initial sandbox invocation could not access Go build cache; approved cache access rerun passed.
- `npm run lint:web`: final exit 0.
- `npm run build:web`: final exit 0, 3203 modules, inherited deprecation/chunk-size warnings. An initial successful build preceded the final explicit null guard; the final build was repeated before freezing to cover that guard.
- `git diff --check`: exit 0 before commit.
Root has reported ordinary N undo/redo, saved undo/redo, failed undo and retry browser/API gates passing on the original implementation. Revision-backed browser gate remains root-owned and pending. No live fixture/proxy writes by implementer. All source/build/report writes frozen after this addendum for the next gate.
## Browser fix round 2 — batch/cancel focus
Commit `9859fa8d` — `🎯 Restore workbench focus after batch annotation actions`, base `55a81c55`. Only four added lines in `src/components/CaptureAnnotationWorkbench.tsx`.
Controller isolated the original apparent history failure by disabling HMR with the existing environment flag (no source configuration changes): revision-backed first split/save/undo restored exact 30–60 original server action; local undo removed the split. Batch fill saved two invalid gaps but its disappearing button left focus on BODY, so Escape/Ctrl+Z did not dispatch. Explicit next-frame/Escape/Ctrl+Z restored the original server action (v4→v5), proving history was present. Earlier unexplained Vite reconnects/time resets were environment interference, not used as evidence for a speculative history change.
Fix returns focus to the mounted workbench after batch success or reported failure, and after mouse cancel-new. A false confirmation result (including task01 stale identity result) returns before focusing; an unmounted component's ref is null. The history and write paths are unchanged.
Verification:
- `node --test tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs`: 20 passed, 0 failed.
- `npm run lint:web`: exit 0.
- `npm run build:web`: exit 0, 3203 modules, inherited warnings only.
- `git diff --check`: exit 0.
No fixture/proxy mutations by implementer. New focus behavior awaits controller browser GREEN after its manual reload. All writes frozen after this addendum.

View File

@ -0,0 +1,21 @@
### Finding Verdicts
- **P2: Preserve an authoritative baseline when no stored workspace exists — ADDRESSED.** The load path now clones its authoritative revision/workspace-derived values into `confirmedAnnotationWorkspaceRef` (`src/pages/AnnotationOperations.tsx:1134`). The getter reads only that task-scoped baseline instead of mutable local state (`src/pages/AnnotationOperations.tsx:1719`); confirmed save/reconciliation updates it, while missing state blocks the operation (`src/pages/AnnotationOperations.tsx:1743`, `:1798`). Local split/drag edits therefore cannot become the prior persisted state of the first save.
### New Breakage in the Fix Diff
- None found. Task clearing/switching invalidates the baseline; disposition and reset success update it alongside authoritative page state (`src/pages/AnnotationOperations.tsx:1058`, `:1065`, `:2058`, `:2251`).
### Out-of-Scope Observations
- None.
### Checks
- Read `review-6-fix1.diff` once and the appended fix report. No suites rerun and no git mutations.
- The new HTTP test confirms revision-backed GET data can restore the original description through the existing endpoint (`internal/api/annotation_history_http_test.go:96`). The report accurately treats this as server characterization; the controller's revision-backed browser regression gate remains pending.
- The appended report names passing focused HTTP/frontend checks and final lint/build results; inherited build warnings remain outside this ticket's scope (`.superpowers/sdd/annotation-keyboard-workflow/task-6-report.md`).
### Verdict
**Fix round:** All findings addressed, no new Critical/Important breakage. Static spec and quality review approved; browser/API acceptance remains controller-owned.

View File

@ -0,0 +1,21 @@
### Finding Verdicts
- **Batch action leaves focus on BODY, preventing immediate keyboard undo — ADDRESSED.** Batch success now calls the existing `focusWorkbench()` after applying the saved result (`src/components/CaptureAnnotationWorkbench.tsx:1148`); reported failure also returns focus (`:1151`). A false/stale confirmation still returns before focusing (`:1145`). Mouse cancel-new likewise focuses the surviving workbench after clearing the editor (`:3082`).
### New Breakage in the Fix Diff
- None. The four added lines preserve persistence/history behavior and reuse the existing mounted-workbench ref.
### Out-of-Scope Observations
- None.
### Checks
- Read `review-6-fix2.diff` once and the appended round-2 report. No test suites rerun, no git mutations, and no broader code crawl.
- The report records 20 passing focused shortcut/mutation checks, successful lint/build and inherited warnings. New focus behavior still awaits the controller's browser confirmation (`.superpowers/sdd/annotation-keyboard-workflow/task-6-report.md`).
- Controller reports the preceding revision-backed first-save undo now passes browser/API validation: two children at v2 restore the original 30–60 action at v3, followed by local split undo.
### Verdict
**Fix round:** All findings addressed, no new Critical/Important breakage. Scoped spec and quality review approved; final focus acceptance remains controller-owned.

View File

@ -0,0 +1,38 @@
### Spec Compliance
- ❌ Issues found: the confirmed/local separation is incomplete for supported revision-backed tasks without an annotation workspace; the first saved undo can restore unsaved local changes as server state (`src/pages/AnnotationOperations.tsx:1705`).
- ⚠️ Cannot verify from diff: controller-owned browser/API acceptance, particularly cross-slice parked drafts, end-selection undo, delayed responses across identity/stage changes, and failed/unknown restore recovery. The implementer explicitly reports no browser GREEN (`.superpowers/sdd/annotation-keyboard-workflow/task-6-report.md`). Shared 100-entry capacity and one-second throttling are inherited; this diff correctly reuses their existing history instance (`src/pages/AnnotationOperations.tsx:1711`, `:2069`).
### Strengths
- Saved edits are recorded after authoritative confirmation, and restoration uses the existing confirmation endpoint with the latest confirmed version rather than a UI-only rollback (`src/pages/AnnotationOperations.tsx:1726`, `:1757`, `:1780`, `:2069`). Exact next-version reconciliation additionally checks ownership and stage.
- N start/end and local split use the same history; completed drag records once, and deletion continues filtering just the selected description so it leaves a blank (`src/components/CaptureAnnotationWorkbench.tsx:959`, `:1018`, `:1249`, `:1258`).
- History reveal restores only the affected editor and parks the outgoing one rather than replacing the parked-draft collection (`src/components/CaptureAnnotationWorkbench.tsx:702`).
- New HTTP coverage exercises the production POST/GET contract for restoration, stale versions, ownership and processing rejection without a test-only business API (`internal/api/annotation_history_http_test.go:15`).
### Issues
#### Critical (Must Fix)
- None.
#### Important (Should Fix)
- **[P2] Preserve an authoritative baseline when no stored workspace exists — `src/pages/AnnotationOperations.tsx:1705`.** `confirmedAnnotationWorkspace()` falls back to mutable local `segments`, `sliceSegments` and statuses. The existing loader supports annotation content sourced from revisions when `annotationDraftFromHumanItem()` returns null (`src/pages/AnnotationOperations.tsx:1089`), so this is a reachable input, not an impossible state. Open such a task, locally drag an existing description boundary (or split a description), then save: `previousWorkspace` at line 1726 now captures the already modified local data as the previously confirmed server data. Undo therefore retains/persists the unsaved boundary change, or attempts to persist the split's unfinished child, instead of restoring the original server description. Keep a distinct confirmed workspace initialized from the authoritative load result, and update it only on confirmed saves/readback. Cover first-save undo on a revision-backed task through browser/public API readback.
#### Minor (Nice to Have)
- None. Reported build warnings are inherited and outside this ticket's scope.
### Assessment
**Task quality:** Needs fixes.
**Reasoning:** The main integration is coherent and preserves the existing history and authoritative write APIs. The mutable fallback undermines the central persisted-versus-draft contract for a supported loading path; fix that before approval, then complete the controller-owned browser gate.
### Checks performed
- Read the supplied review diff once; no git mutations and no test-suite reruns. The renderer elided only a small unchanged drag-handler signature/guard, which was not material to any finding.
- Named risk: first-save baseline availability. Checked `annotationDraftFromHumanItem()` in `src/lib/annotation-workbench.js:388` and the loader's revision fallback in `src/pages/AnnotationOperations.tsx:1078`; these confirm absent workspaces are supported and produce the finding above.
- Named risk: parked editor loss while revealing history. Checked existing `selectSlice()` and end-selection state handling in `src/components/CaptureAnnotationWorkbench.tsx:650` and `:297`; functional parked-editor updates preserve unrelated drafts.
- Named risk: async mutation identity and stage boundaries. Checked `src/lib/annotation-authoritative-mutation.js` and the existing mutation context/history reset call sites in `src/pages/AnnotationOperations.tsx:533`, `:595`, `:629`, `:1552`; task/account scope fencing is inherited, while real delayed-response stage behavior remains part of the controller gate.

View File

@ -0,0 +1,190 @@
# Task 7 implementation report — safe delete and batch invalid shortcuts
## Status
Implementation is code-frozen and committed locally after focused verification. The controller owns the post-freeze browser/API gates, ticket status, and aggregate implementation report.
## Implemented behavior
- `Shift+Delete` and `Shift+Backspace` resolve to `delete-selected` only at the workbench boundary.
- The safe-delete shortcut ignores composition, held-key repeats, editable elements, and native controls. Plain Delete/Backspace and modified variants remain unbound.
- Slice-stage deletion uses `selectedSliceIndex`, never `playheadSliceIndex`. It calls the same guarded `deleteSliceAtIndex` function as the mouse trash button, preserves full coverage through the parent `onDeleteSlice` merge path, and selects the surviving neighbor when the selected slice is removed.
- Annotation-stage deletion requires an explicit `editingAnnotation` whose id exists in the selected slice's saved `annotationSegments`. No selection, an unsaved draft, or a playhead over a description does not infer a delete target. The keyboard and mouse both use `deleteAnnotationLeavingBlank`, which persists through `onConfirmAnnotations` and the shared annotation history.
- `Ctrl+X` resolves to `mark-invalid` outside editable/native controls only. It calls the existing `markUnannotatedInvalid` mouse handler, which creates invalid descriptions only for `annotationCoverageGaps`, leaves existing descriptions intact, saves the entire batch once, and records one shared history transition through `onConfirmAnnotations`.
- Existing discarded-slice, read-only, reviewer, media-only, saving, exact-frame/alignment, and active-editor restrictions remain in the reused handlers.
- Shortcut help now documents safe delete for both edit phases and `Ctrl+X` for annotation. The obsolete statement that delete is button-only was removed.
## Interfaces and integration contract
- Shortcut seam: `annotationShortcut(event, context)` in `src/lib/annotation-shortcuts.js` returns `delete-selected`, `mark-invalid`, `consume`, or `null` without touching React state.
- Slice mutation seam: `deleteSliceAtIndex(index)` in `CaptureAnnotationWorkbench` is shared by keyboard and mouse and delegates to the existing `onDeleteSlice` parent callback. Parent `applySliceChange` continues to create the slice history edit and enforce discarded-slice coverage restrictions.
- Persisted annotation seam: `deleteAnnotationLeavingBlank` and `markUnannotatedInvalid` both delegate to existing `onConfirmAnnotations(next, selectedSlice.id, annotationEditState())`. Parent `confirmAnnotationDescription` performs the guarded, versioned server write and records the confirmed before/after snapshots in `createAnnotationHistory`.
- Focus/selection ruling: Esc only returns focus to the workbench and retains `editingAnnotation`; this lets an explicitly selected saved description remain the delete target outside the textarea. The playhead is never used as a delete target.
- No new history, HTTP path, test-only business interface, fixture/proxy mutation, stage-confirmation behavior, or ticket 08 behavior was introduced.
## TDD evidence
### RED — resolver behavior
Command:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs
```
Result before implementation: 13 tests total, 11 passed, 2 failed.
- `safe delete resolves only for an unfocused workbench selection` expected `delete-selected`, received `null`.
- `Ctrl+X owns batch invalid only outside native editing controls` expected `mark-invalid`, received `null`.
These were expected failures because neither shortcut existed in the public resolver.
### GREEN — resolver behavior
Same command after the minimal resolver branches: 13/13 passed, 0 failed.
### RED — help discoverability
Command:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs
```
Result after adding the help expectation and before adding help rows: 14 tests total, 13 passed, 1 failed. The safe-delete help row was absent (`phases` was `undefined`).
### GREEN — final focused verification
Command:
```text
node --test tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-history.test.mjs tests/frontend/optional-annotations.test.mjs tests/frontend/annotation-playhead-draft.test.mjs
```
Result: 32/32 passed, 0 failed, 0 skipped, pristine test output.
This covers shortcut ownership/repeats/IME, shared history semantics, blank/invalid/discard distinctions, and playhead-versus-draft behavior at the approved pure public seams.
## Static and build verification
```text
npm run lint:web
```
Result: exit 0 (`tsc --noEmit`).
```text
npx prettier --check src/components/CaptureAnnotationWorkbench.tsx src/lib/annotation-shortcuts.js tests/frontend/annotation-shortcuts.test.mjs
```
Result: exit 0; all matched files use Prettier style.
```text
npm run build
```
Result: exit 0. Vite transformed 3203 modules and built in 981 ms; all three Go binaries compiled. Vite emitted the existing large-chunk warning and Node emitted the existing `module.register()` deprecation warning; neither failed the build.
Per task instructions, no full test suite was run.
## Browser evidence
The controller initially observed against the pre-change revision (`9859fa8d`) that `Shift+Delete` left three selected slices unchanged and `Ctrl+X` left an empty slice unchanged. A later minimal DOM key probe showed that these observations are **not independent feature RED evidence**: the native automation path delivered no `keydown` event at all for `Ctrl+X` or `Shift+Delete`. The valid implementation RED evidence remains the public resolver tests recorded above.
Post-freeze controller validation on the local stack:
- The minimal probe at `.superpowers/sdd/annotation-keyboard-workflow/key-probe.html` received the expected `Shift+Backspace` event, but CUA/native automation produced no DOM event for `Ctrl+X` or `Shift+Delete`. Native Ctrl+X instead performed the platform cut directly.
- On macOS, `Shift+Backspace` deleted an explicitly selected saved description. The guarded API revision advanced from v11 to v12; undo advanced it to v13 and restored the original description exactly.
- On macOS, the selected second slice was deleted from a three-slice workspace, producing two merged slices; undo restored all three slices.
- Ctrl+X in a text input emptied the selected text through native cut behavior and caused no annotation API write.
- The shared mouse batch-invalid path and API persistence provide the callable mutation path used by the keyboard action; the controller records that verification in the aggregate manual report because the available automation cannot deliver a physical Ctrl+X event to the workbench.
- Edge/browser cross-checking was unavailable because the Codex authentication token for that surface was unavailable.
- Ticket 07 review was approved after these gates.
All validation used local frontend `5173`, API `3001`, and snapshot Mongo `27018`. No company/BOS write or fixture/proxy mutation was performed by this implementer.
## Files changed
- `src/lib/annotation-shortcuts.js`
- `src/components/CaptureAnnotationWorkbench.tsx`
- `tests/frontend/annotation-shortcuts.test.mjs`
## Self-review
- Confirmed slice deletion uses explicit selection rather than the playhead and shares the mouse path.
- Confirmed annotation deletion requires a selected saved description and cannot target an unsaved draft or infer from playback position.
- Confirmed text inputs, contenteditable controls, native buttons/controls, Chinese composition, and repeated keys keep their prior ownership.
- Confirmed `Ctrl+X` is Control-only as specified; Command+X remains unbound at the workbench resolver.
- Confirmed batch invalid and description delete persist through the existing guarded callback and become one shared-history step only after server confirmation.
- Confirmed discard is neither removed nor converted to invalid, and existing discard restrictions remain active.
- Confirmed task 08 stage-confirmation behavior was not touched.
- Reviewed the final diff for unrelated changes. Controller-owned `.scratch` status/report edits remain unstaged and uncommitted by this task.
## Limits and follow-up evidence
- Native automation could not synthesize workbench `Ctrl+X` or `Shift+Delete`: the minimal page received no DOM key event for either combination. This is an automation interception limitation, not a product event-handler result. `Shift+Backspace` supplied the required macOS safe-delete browser/API evidence.
- The focused Node tests validate both unresolved physical combinations at the public shortcut resolver and cover their native-input, IME, repeat, and modifier rules. The real browser/API gates validate the shared mutation paths and macOS alternate delete binding as described above.
- Build warnings are existing toolchain/bundle warnings, not new test failures.
## Commit
- `37480aec` — `⌨️ Add safe delete and invalid shortcuts`
## Fix round 1 — nullable empty workspace after discard restore
### Browser/API RED and root cause
The controller reproduced a blocking render crash on the local stack after discarding an empty slice and restoring it to keep. The restore response advanced the item to v3 and returned `workspace.segments: null`; `setSliceDisposition` assigned that raw value to React state. The next render called `annotationSegmentsForSlice`, which attempted `segments.filter` and crashed. The same persisted `annotationWorkspace` was rejected by `annotationDraftFromHumanItem`, so reload could also lose valid empty-workspace metadata.
The API response shape comes from an empty Go slice serializing as JSON `null`. A nullish segment collection represents zero annotations here; a non-null non-array remains malformed and must fail closed.
### Regression RED
Command:
```text
node --test tests/frontend/annotation-workbench.test.mjs
```
Result before the fix: 18 tests total, 17 passed, 1 failed. `empty annotation collections from disposition responses remain a valid workspace` failed because `normalizeAnnotationWorkspace` was absent. The controller's real browser/API discard→restore crash is the primary RED; this pure public-seam test is focused supplemental coverage for the captured response shape.
### Fix
- Added `normalizeAnnotationWorkspace` at the existing workspace parsing seam.
- Normalized missing/null `segments` to `[]` and missing/null/non-array operations to the existing `[]` default.
- Preserved required `sliceSegments` validation and rejected non-null malformed segment collections.
- Reused the normalizer in `annotationDraftFromHumanItem` for persisted readback.
- Normalized the immediate slice-disposition response before setting React state, history baseline, or confirmed-workspace state.
No rendering fallback, fixture mutation, API restart, database write, or unrelated schema change was added.
### Fix verification
```text
node --test tests/frontend/annotation-workbench.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-history.test.mjs tests/frontend/optional-annotations.test.mjs
```
Result: 44/44 passed, 0 failed, 0 skipped.
```text
npm run lint:web
```
Result: exit 0 (`tsc --noEmit`).
```text
npx prettier --check src/lib/annotation-workbench.js src/pages/AnnotationOperations.tsx
git diff --check -- src/lib/annotation-workbench.js src/pages/AnnotationOperations.tsx tests/frontend/annotation-workbench.test.mjs
```
Result: both exit 0. The complete legacy test file has unrelated pre-existing Prettier drift outside this change, so it was not mechanically reformatted.
```text
npm run build
```
Result: exit 0; Vite transformed 3203 modules and all three Go binaries compiled. Existing Node deprecation and Vite chunk-size warnings remain non-fatal.
The controller owns the exact post-freeze discard→restore browser/API GREEN rerun. Fix round 1 was code-frozen before that gate.
Fix commit: `6db97457` — `🐛 Normalize empty annotation workspaces`.

View File

@ -0,0 +1,15 @@
### Finding Verdicts
- **Discard restore can return `workspace.segments: null`, crash rendering through `segments.filter`, and lose the valid empty workspace on reload** — ADDRESSED. `normalizeAnnotationWorkspace` maps nullish `segments` and `operations` to empty arrays while rejecting non-array non-null `segments` (`src/lib/annotation-workbench.js:388-401`); `annotationDraftFromHumanItem` now uses that normalizer for persisted readback (`src/lib/annotation-workbench.js:403-407`). The slice-disposition response is normalized before confirmed-state, React state, and history-baseline updates (`src/pages/AnnotationOperations.tsx:2054-2072`). The focused regression test covers null collections, malformed segment rejection, and persisted-item restoration (`tests/frontend/annotation-workbench.test.mjs:236-258`). The appended report records 44/44 focused tests, successful type checking/build, and the controller's exact discard→restore browser GREEN; the reload browser gate remains controller-owned.
### New Breakage in the Fix Diff
None. The normalizer preserves the previous required `sliceSegments` validation, status defaults, timestamp/user fields, and fail-closed behavior for malformed non-null segment collections (`src/lib/annotation-workbench.js:388-401`). Immediate response state and persisted readback now share one normalized shape.
### Out-of-Scope Observations
None.
### Verdict
**Fix round:** All findings addressed, no new Critical/Important breakage.

View File

@ -0,0 +1,35 @@
### Spec Compliance
- ✅ Spec compliant. `Shift+Delete` and Mac `Shift+Backspace` are guarded for IME, repeats, editable elements, native controls, and modifier variants in `src/lib/annotation-shortcuts.js:24-30`; dispatch requires the selected slice or an explicitly selected saved annotation in `src/components/CaptureAnnotationWorkbench.tsx:1428-1436`.
- ✅ Slice keyboard and mouse deletion share `deleteSliceAtIndex`, including edit-authority and discard-neighbor guards, in `src/components/CaptureAnnotationWorkbench.tsx:1295-1317` and `src/components/CaptureAnnotationWorkbench.tsx:1972-1979`.
- ✅ `Ctrl+X` is Control-only, is ignored by text/native controls, and dispatches only in annotation phase in `src/lib/annotation-shortcuts.js:24-26` and `src/components/CaptureAnnotationWorkbench.tsx:1436`.
- ✅ Context help documents safe deletion in both edit phases and batch invalid only in annotation phase in `src/lib/annotation-shortcuts.js:94-99`.
- ⚠️ Cannot verify from diff: real-browser server readback, visible undo restoration, and isolated local frontend/API/Mongo acceptance remain controller-owned post-freeze gates. The implementer reports only pre-change browser RED evidence; the controller should retain the Mac selected-description delete, no-target no-change, multi-gap one-undo, discard/dictionary/authority, and persistence/readback checks.
### Strengths
- The resolver change is narrow and preserves native cut/delete, IME composition, held-key repeat, and unrequested modifier behavior; focused public-seam tests cover these cases in `tests/frontend/annotation-shortcuts.test.mjs:222-249`.
- Explicit-target semantics are clear: slice deletion uses `selectedSliceIndex`, while annotation deletion requires `editingAnnotation` to match a saved segment before calling the existing delete handler (`src/components/CaptureAnnotationWorkbench.tsx:1428-1435`).
- Named-risk check — reused mutation/history path: `markUnannotatedInvalid` computes all current `annotationCoverageGaps`, preserves existing segments, and calls `onConfirmAnnotations` once (`src/components/CaptureAnnotationWorkbench.tsx:378`, `src/components/CaptureAnnotationWorkbench.tsx:1119-1153`); description deletion uses the same confirmation seam and retains read-only, review, saving, and discard guards (`src/components/CaptureAnnotationWorkbench.tsx:1259-1274`).
- Named-risk check — disallowed shortcut ownership: the workbench listener returns while dialogs/dictionaries own focus, passes editable/native/IME state to the resolver, prevents default only for resolved workbench commands, and gates mutation by phase and `canEdit` (`src/components/CaptureAnnotationWorkbench.tsx:1368-1436`).
- The tests inspect exported resolver/help behavior rather than source strings and include both positive and negative shortcut cases (`tests/frontend/annotation-shortcuts.test.mjs:222-258`).
### Issues
#### Critical (Must Fix)
None.
#### Important (Should Fix)
None.
#### Minor (Nice to Have)
None.
### Assessment
**Task quality:** Approved
**Reasoning:** The change is small, reuses the established mouse mutation and shared confirmation/history paths, and preserves the required target, text-input, IME, repeat, discard, and authority guards. The only unverified requirements are explicitly assigned to the controller's post-freeze browser/API acceptance gates.

View File

@ -0,0 +1,70 @@
# Task 8 implementation report — two-step stage confirmation
## Status and scope
Implementation is code-frozen after focused tests, type checking and the web/Go build. The controller owns the post-freeze real browser/API materialization and quality-handoff gates, ticket status and aggregate report. No live fixture, proxy, company service, BOS, push or deployment mutation was performed by this implementer.
## Implemented behavior and interfaces
- Ctrl/Command+Enter first saves an outstanding current-slice draft through the existing `confirmAnnotation` / `onConfirmAnnotations` path. Incomplete endpoints/text remain validation failures and cannot fall through to submission.
- All parked drafts, including unfinished endpoint selections, prevent stage confirmation. A page dialog lists each affected slice and lets the operator return to its retained editor. No implicit saves or cancellations occur.
- Without drafts, keyboard and existing stage buttons open a native in-page dialog for generating slices or submitting annotation. It shows slice/keep/discard totals, saved description and invalid counts, per-slice semantic blank counts, and the history/stage boundary. No `window.confirm` was added.
- `stageConfirmationShortcut(event, { enterReleased })` is a pure keyboard helper. The workbench arms confirmation only after releasing the opening Enter; a separate unmodified Enter confirms, Esc cancels, repeat/IME/modifier events are consumed. A synchronous dispatch guard prevents double submission. Focus returns to the workbench after closing.
- Existing `onConfirmSlices` and `onSubmitTask` callbacks remain unchanged. The coordinator independently checks outstanding drafts, phase, ownership and mutation locking before submitting.
- Stage request errors and non-processing submission responses are reconciled by the existing task GET API. Only authoritative quality-stage completion returns to the pool. Processing remains locked and polls; transient poll failures continue read-only recovery. If readback also fails, the page keeps content and locks conflicting edits with an explicit `核对阶段结果` action.
- Rejected readback preserves the editor and its original CAS version instead of silently adopting a newer version with stale local content. The error directs the user to load authoritative content if version/ownership changed.
- Generation processing replaces the conflicting reset action with `核对生成状态`; reset is guarded during materialization. History remains bounded by the existing stage boundary and cannot reverse generation or quality handoff.
- Shortcut help now exposes stage confirmation in both phases, draft/end validation priority, and annotation Undo/Redo (the minor help omission from the brief).
- Existing backend frame, dictionary, owner, optional-description, invalid/discard and review rules are reused unchanged. No backend production change or new API was required.
## TDD evidence
Approved primary seam: controller-owned real browser journey plus existing public APIs. Supplement: existing pure keyboard seam and existing HTTP handler tests.
1. RED: `node --test tests/frontend/annotation-shortcuts.test.mjs` after adding the independent Enter test failed because `stageConfirmationShortcut` was not exported. This was expected before the new keyboard gate existed.
2. GREEN: same command after implementation: 15/15 passed.
3. RED: added contextual help expectations; same command: 14 passed, 2 failed. The old help advertised only saving, and slicing had no stage shortcut row.
4. GREEN: same command after contextual help update: 16/16 passed.
5. Controller supplied browser RED against baseline `6db97457`: SECTION focused, no current editor, Ctrl+Return yielded no dialog and no POST on the isolated annotation task. This is controller evidence, not a browser run by this implementer.
## Final focused verification
```text
node --test tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-submission-state.test.mjs
```
20/20 passed, 0 failed, no test warnings. Removed obsolete source-string assertions for the exact old processing-only lock expression; source inspection is not used as new interaction evidence. The unchanged dashboard source assertions in that older test file remain upstream debt.
```text
go test ./internal/api -run 'TestPendingCombinedSubmissionBlocksWorkspaceMutations|TestCombinedSubmissionSupportsImmediateAsynchronousResponse|TestCombinedSubmissionAcceptsOptionalDescriptions|TestBlankSubmissionHandsOffToQualityWithEmptyRevision|TestCombinedSubmissionStillRequiresCompleteSliceCoverage|TestCombinedSubmissionCannotBypassDescriptionOverlapChecks|TestCombinedAnnotationDraftRejectsNonAnnotatorEvenWhenTaskIsVisible|TestCombinedAnnotationDraftRejectsAnnotatorWhoDidNotClaimTheItem|TestCombinedSubmissionFinalCASFailureDoesNotPublishQualityTask' -count=1
```
Passed (`ok droboticflow/internal/api 0.557s`). Existing focused tests cover processing mutation refusal, asynchronous acceptance, blank/optional descriptions, overlap/coverage rejection, owner/role denial and final-CAS failure. They use isolated in-memory fixtures and do not contact local live fixtures or company services. No new HTTP test was necessary for a production HTTP change because no backend behavior changed.
```text
npm run lint:web
npm run build
git diff --check
```
All exit 0. Vite transformed 3203 modules; all three Go binaries compiled. Existing Node `module.register()` deprecation and >500 kB chunk warnings remain. Per controller instruction, no full test suite was run.
## Files
- `src/components/CaptureAnnotationWorkbench.tsx`
- `src/lib/annotation-shortcuts.js`
- `src/pages/AnnotationOperations.tsx`
- `tests/frontend/annotation-shortcuts.test.mjs`
- `tests/frontend/annotation-submission-state.test.mjs`
The controller-owned modified ticket was excluded from staging. This report is an untracked/ignored task artifact, following prior task reports.
## Self-review and remaining gates
Reviewed modal focus/key ownership, current-versus-parked draft priority, pending/unknown locks, stale mutation identity guards, original CAS retention after rejected readback, and history boundaries. Existing large workbench/coordinator files remain large; changes were kept local rather than introducing a parallel editor or task model.
Root must complete browser GREEN and real API gates after manually reloading the HMR-disabled frontend: current/parked/incomplete drafts; held/repeated Enter and Esc; mouse parity; actual generation processing/completion; actual quality handoff; failure/unknown recovery; blank/invalid/discard distinctions and no cross-stage undo. No browser GREEN or live materialization result is claimed here.
## Commit
`b6e80de8` — ✨ Add draft-aware two-step stage confirmation. Committed only the five implementation/test files on `feature/local-dev-toolkit`; no push. Initial sandbox git-index denial was resolved via the authorized elevated local git operation.

View File

@ -0,0 +1,39 @@
### Spec Compliance
- ✅ Spec compliant for the implementation visible in this task: current draft save has priority, every reported outstanding draft blocks submission, and stage dispatch requires a separate confirmation (`src/components/CaptureAnnotationWorkbench.tsx:1137`, `:1162`, `:1524`). Both coordinator entry points independently reject outstanding drafts and an incorrect editing phase (`src/pages/AnnotationOperations.tsx:2242`, `:2419`).
- ⚠️ Cannot verify from diff: actual browser draft retention, key release/repeat/IME behavior, mouse parity, processing-to-completion, failure/unknown recovery, and stage-boundary undo. The implementer explicitly leaves these live browser/API gates to the controller; complete those before ticket acceptance. The added pure shortcut tests are supplemental, not substitutes (`tests/frontend/annotation-shortcuts.test.mjs:255`).
- ⚠️ Cannot verify from diff: unchanged server hardware-frame mapping, dictionary/ownership/CAS/review rules and partial/all-blank, invalid/discard semantics. The report lists focused public HTTP tests, but the controller's real API acceptance remains the primary integration gate (`.superpowers/sdd/annotation-keyboard-workflow/task-8-report.md:42`).
### Strengths
- Current/incomplete drafts cannot fall through into stage submission; parked drafts receive explicit navigation controls rather than implicit saves (`src/components/CaptureAnnotationWorkbench.tsx:1140`, `:1145`, `:1550`).
- Confirmation consumes held/modified/IME Enter and uses a synchronous dispatch guard; the summary distinguishes kept/discarded slices and semantic gaps (`src/lib/annotation-shortcuts.js:149`; `src/components/CaptureAnnotationWorkbench.tsx:1163`, `:1572`).
- Transport errors use authoritative readback; unknown readback retains content and a visible locked recovery action. Submission returns to the pool only after authoritative completion (`src/pages/AnnotationOperations.tsx:2184`, `:2220`, `:3301`).
- Mutation responses now use task/account ownership tokens; reset cannot compete with generation in progress (`src/pages/AnnotationOperations.tsx:2281`, `:2314`, `:2459`).
### Issues
#### Critical (Must Fix)
- None identified.
#### Important (Should Fix)
- None identified in the reviewed changes; browser/API acceptance is still pending.
#### Minor (Nice to Have)
- The verification report records existing Node `module.register()` deprecation and Vite chunk-size warnings (`.superpowers/sdd/annotation-keyboard-workflow/task-8-report.md:50`). They are not introduced regressions or merge blockers for this ticket, but the build output is not warning-free; track their cleanup separately.
### Assessment
**Task quality:** Approved, subject to the controller-owned browser/API acceptance gates above.
**Reasoning:** The stage coordinator reuses public APIs, distinguishes request acceptance from completion, preserves recovery after ambiguous failures, and keeps modal and mutation guards local. No actionable correctness defect was established in this task diff.
### Focused checks
- Read the complete supplied diff in bounded chunks after the initial combined tool output was truncated; did not regenerate a git diff or rerun tests.
- Named risk — refresh might unlock an unknown operation without authoritative data: inspected the task-detail loader around `src/pages/AnnotationOperations.tsx:1048`. Recovery is cleared only after accepted task readback; mutation-busy and request-generation guards reject competing/stale reads (`:1085`, `:1151`).
- Named risk — continued submission polling might apply an old account/task response: the diff cuts off the polling function, so inspected its complete body at `src/pages/AnnotationOperations.tsx:2478`, plus account reset and `loadProject` dependencies at `:895` and `:907`. Poll responses check disposal/task identity, and account changes recreate the effect through `loadProject` and clear detail.
- Named risk — a pending-end draft could bypass the new save-first branch: inspected `outstandingDrafts` and `confirmAnnotation` at `src/components/CaptureAnnotationWorkbench.tsx:399` and `:1043`. Pending endpoints are included; save validates the endpoint and returns without submitting. Inspected the unchanged shortcut resolver at `src/lib/annotation-shortcuts.js:20` to confirm description-input Ctrl/Command+Enter routes through this command.

View File

@ -0,0 +1,146 @@
# Task 9 implementation report — dedicated single-task work page
## Status and scope
CODE-FROZEN at `acdc5427`. The controller may reload the HMR-disabled frontend and perform the real browser/API journey. No live fixture, browser, local API process, proxy, company service, BOS, push or deployment mutation was performed by this implementer. Browser GREEN remains controller-owned; implementation completion is not a claim that the full acceptance gate has passed.
## Implemented behavior and composition
- Added `/plugins/annotation-qa/workflows/:workflowId/work`, guarded by the same annotation plugin guard, rendering `AnnotationOperations workPage`. The existing coordinator, `CaptureAnnotationWorkbench`, media, keyboard handling, dictionaries, write/version fencing, recovery dialogs and submission callbacks are reused without a second editor.
- Authorized annotators select a project and explicitly click **开始工作** from the existing annotation page. The action performs a fresh public `GET /api/human-items?pluginId=annotation-qa&projectId=...&pool=mine`, prioritizes the currently selected owned unfinished annotation task, then another owned unfinished annotation task. Owned quality-review tasks are excluded. If no such task exists, it uses the existing blind project-random claim operation.
- An unresolved random-claim request reuses the existing account/project request ID before considering another allocation. Existing session storage, response fencing, empty-pool notices and random-claim error behavior are retained. Entry loading is guarded against repeated clicks; changed account/project/task or new dirty edits cancel the read-side entry action.
- Work is entered through same-tab navigation to `/plugins/annotation-qa/workflows/all/work?projectId=...&taskId=...`. The dedicated presentation removes pool/sidebar controls while retaining task status, errors, materialization/recovery states, complete shared workbench/help and an explicit return link. Layout uses the full editor row, including smaller-width row sizing.
- Header and workbench return actions use the existing router blocker. Native reload protection remains unchanged. Completion keeps the existing authoritative quality-handoff notice and pauses on the page; there is no automatic next claim.
- Selecting another task clears prior task error, submission success, processing, stage recovery and claim notices. Completion's new success notice is still set after the old task is closed.
- Existing global/project role handling and all backend ownership/supplier/review contracts remain unchanged. No production backend change was needed.
## TDD evidence and approved boundary
Primary seam remains real browser interaction plus existing public API readback, as approved in the parent spec. The controller supplied RED before implementation: on the actual authorized project pool after task08 QA, the exact **开始工作** button count was **0**, and only the existing inline editor entry existed. The production change addresses that missing action and its complete task journey.
No new pure business module or test-only seam was introduced. No new source-string assertion was added. One obsolete source-shape test for the exact bookmarked-task effect was removed from `annotation-random-claim.test.mjs`; the behavior now also includes work-page selection and is covered by the controller's browser gate. The other pre-existing source assertions in that file remain upstream debt and are not claimed as new interaction proof.
Browser GREEN has not been run by this implementer. The controller must record it after the final build, using the instructions below. Passing supplemental tests is not a substitute for this gate.
## Focused verification
```text
node --test tests/frontend/annotation-random-claim.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-submission-state.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs
```
32/32 pass, 0 failures, no test warnings. This supplements the browser gate with existing claim-ID, keyboard, stage-completion and authoritative mutation behavior.
```text
go test ./internal/api -run 'TestRandomClaim|TestAnnotatorCannotReleaseOrSelectUnclaimedTaskButAdminStillCanRelease|TestPendingCombinedSubmissionBlocksWorkspaceMutations|TestCombinedAnnotationDraftRejectsNonAnnotatorEvenWhenTaskIsVisible|TestCombinedAnnotationDraftRejectsAnnotatorWhoDidNotClaimTheItem' -count=1
```
Passed: `ok droboticflow/internal/api 3.689s`. Existing isolated HTTP fixtures cover random claim replay/concurrency, role/project/supplier restrictions, no self-release/named claim, ownership and processing mutation restrictions. No live fixture writes occur in these unit tests.
```text
npm run lint:web
npm run build
npx prettier --check src/pages/AnnotationOperations.tsx src/App.tsx src/styles/capture-workspace.css tests/frontend/annotation-random-claim.test.mjs
git diff --check
```
All exit 0. Vite transformed 3203 modules, and all three Go binaries built. Existing Node `module.register()` deprecation and >500 kB chunk warnings remain. No full suite was run, as instructed; controller owns that final comparison against upstream debt.
## Controller browser / public API acceptance
Use only frontend `http://127.0.0.1:5173`, API `http://127.0.0.1:3001`, and isolated snapshot Mongo27018 fixtures. Reload after CODE-FROZEN because HMR is disabled. Do not run defaults that point at company services.
1. On the authorized annotation project's existing pool, verify **开始工作** exists and is enabled after project loading. Preserve existing owned fixtures. Select one current unfinished task if a particular fixture should be resumed, then click Start Work. Observe the same browser tab, the new `/work` URL with the same task, no pool sidebar, videos/editor/help/stage state present. Network should show owned-task GET/summary/detail reads and **no random-claims POST** while a resumable owned task exists.
2. For the full slice-stage journey, use the selected isolated owned fixture's normal **重新切片** action if it starts in annotation. Exercise slice split/frame mapping/dictionary naming, keyboard undo/redo, two-step generate confirmation, actual processing state, and read back completed `sliceWorkflow` via `GET /api/plugins/annotation-qa/tasks/<id>` before annotating. Do not reload or rebuild during history checks.
3. Exercise description draft selection/navigation, dictionary/text save, persisted undo/readback, Ctrl+X blank-invalid behavior, separate stage confirmation and actual quality handoff in this new presentation. Verify keep/blank/invalid/discard semantics remain distinct through the same public task/item reads used for phase1. Confirm completion stays paused, shows a success notice, clears the editor and performs **no next random claim**.
4. Create an unsaved draft or slice edit; use the work-page header **返回任务池** or the workbench return action. Verify the existing leave dialog, Esc/continue preservation, and discard/return. Verify native reload retains the existing unsaved warning. Refresh/multipage continuation protocol beyond these existing protections is ticket10, not claimed here.
5. Only after owned tasks are legitimately completed, or with a controller-approved clean isolated annotator fixture, exercise Start Work without resumable work: exactly one existing random claim, returned task/item readback, same-tab complete shared editor. Empty and unknown outcomes show notices. Unknown replay retains the same request identifier. Do not release pre-existing owned work merely to force this branch.
6. Switch tasks after a conflict or completed-task success banner. Verify the prior banner is cleared; no old task error/recovery state leaks into the selected task. Unauthorized projects/reviewer roles continue to use the existing guards and public API enforcement.
## Files and commit
- `src/App.tsx`
- `src/pages/AnnotationOperations.tsx`
- `src/styles/capture-workspace.css`
- `tests/frontend/annotation-random-claim.test.mjs`
`acdc5427` — ✨ Add dedicated single-task annotation work page
Only those four task files were committed on `feature/local-dev-toolkit`. The controller-owned modified ticket was excluded. Initial sandbox denial creating `.git/index.lock` was resolved by the authorized elevated local git operation. This report is an ignored task artifact, matching previous task reports.
## Self-review and limits
Reviewed route guarding, shared composition, owned-task preference, completed-stage exclusion, ambiguous claim replay, repeated entry locking, account/project/task fences, dirty departure handling, success-banner reset ordering, no next-task effect, desktop/mobile row sizing, and exact staged file list. Most textual diff size is Prettier indentation from conditional wrappers around existing header/pool markup; no editor copy or business model rewrite occurred.
The existing large coordinator remains large; only local composition and entry behavior changed. No new backend permission or assignment algorithm was added. Browser GREEN, actual slice materialization/quality handoff, clean no-owned random entry, and role/leave regression acceptance remain the controller's gates. Ticket10 refresh/multipage protocol and ticket11 automatic next-task behavior are intentionally not delivered or claimed complete.
## Fix round 1 — application role guard rejected the work route
The controller's first browser GREEN attempt against `acdc5427` exposed a real missed integration: after a fresh reload and authorized project selection on completed slice-primary's item route, **开始工作** was enabled, but clicking it ended at `/plugins/annotation-qa/workflows/all/annotate` without query parameters. The ordinary heading and unselected project confirmed that entry failed. This observed public browser case is the regression RED; the original implementation was not accepted.
Systematic tracing found the exact cause in `src/App.tsx`'s outer `RoleRouteGuard`: annotators were allowed only the `/annotate` stage path, item paths and dashboard. The added `/work` route therefore hit the existing `<Navigate to="/plugins/annotation-qa/workflows/all/annotate" replace />` fallback before its plugin guard/coordinator rendered. The fallback's exact URL explains both the ordinary page and lost query. The initial self-review checked the inner plugin/coordinator guards but missed this outer gate.
The smallest fix adds `/work` alongside `/annotate` to that existing annotator condition. Reviewer/acceptance/supplier-manager conditions are unchanged. There is no new public helper, test-only seam, copied editor or unrelated change. The browser regression procedure is step 1 above, specifically starting from the same completed item route and asserting the `/work` URL retains projectId and an unfinished owned taskId, the workbench/media actually operate, and no random claim occurs while owned unfinished work exists. Controller owns that GREEN rerun.
Verification after the one-line fix:
```text
node --test tests/frontend/annotation-random-claim.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-submission-state.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs tests/frontend/fanyu-v5-four-stage.test.mjs
```
35/35 pass, 0 failures. Existing source-shape checks are supplementary upstream tests, not proof of the browser fix. No new source assertion was added.
```text
npm run lint:web
npm run build
npx prettier --check src/App.tsx
git diff --check
```
All exit 0. Vite transformed 3203 modules; all three Go binaries compiled; the same existing Node deprecation and chunk-size warnings remain. No full suite, browser, live fixture or service restart was run by this implementer.
Fix commit: `ce012f8a` — 🐛 Allow annotators to enter the dedicated work route. Only `src/App.tsx` was staged. CODE-FROZEN again after all checks/build; controller may reload and retry. Real browser GREEN and complete task-stage acceptance remain pending until controller evidence confirms them.
## Fix round 2 — delayed claim continuation and stale entry notices
Read and verified the Important P2 finding in `task-9-review.md`. The new owned-task entry reads checked task/account/project/dirty state, but both random-claim branches omitted that predicate; the random claim handler checked only actor/project before navigation and notices. This allowed a response from the earlier Start Work action to take over a newly selected task or interrupt new edits.
### Browser RED before production changes
The controller reproduced against `ce012f8a`: an ordinary random claim with request ID `8bb22e0cfb569533ef21b61591d23f5c` returned HTTP200 but its response was dropped by the local proxy. Start Work replayed the **same ID** with its response delayed 30 seconds. During the delay the controller selected `annotate-delayed`, observing the normal `/all/annotate?...taskId=...annotate-delayed` page. When the replay resolved, the old response forced `/all/work?...taskId=...pool-03`, without a leave dialog. This is the public browser RED for the actual stale-navigation defect, not a source assertion. One isolated pool item was genuinely claimed; the controller retains ownership and controls all fixture/network operations.
### Change and preservation
- Both Start Work claim paths now pass their origin predicate into `randomClaimTask`. Dedicated entry is fail-closed without that predicate.
- Navigation, pool-view changes, loading/error resets and success/empty/error notices occur only while the originating entry session is current and there are no current dirty edits.
- The entry captures the existing authoritative task/account context **identity**, not just the task ID. A switch A → B → A cannot revive the earlier action. Stable account/project/router-location context identity additionally invalidates account/project/route round trips, and cleanup invalidates a pending entry when the page unmounts.
- A confirmed claim is still merged into My Tasks for the current matching account/project before a stale continuation exits. This preserves the real allocated task without changing selection, focus, page, or current editor. Authoritative success and existing terminal errors clear their request receipt; network/unknown errors continue to retain the same request ID for retry.
- Owned-task read errors now use the same entry predicate. No stale entry error replaces another task's notice.
The changes stay in `AnnotationOperations.tsx`; no new business/test-only interface, backend change, release, fixture mutation, service restart, or auto-next behavior was introduced.
### Verification
Before editing, the existing focused claim + authoritative mutation tests passed 12/12. After editing:
```text
node --test tests/frontend/annotation-random-claim.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-submission-state.test.mjs
```
32/32 pass, 0 failures and no test warnings. These are supplemental existing tests; controller browser GREEN below is required to verify the new async UI continuation. No new source-string assertion was added.
```text
npm run lint:web
npm run build
npx prettier --check src/pages/AnnotationOperations.tsx
git diff --check
```
All exit 0. Vite transformed 3203 modules; all three Go binaries compiled. Existing Node deprecation and >500 kB chunk warnings remain. No full test suite was run.
Self-review checked both claim callsites, successful/empty/error outcomes, current dirty state, task/account/project/route switch-back invalidation, unmount, preserved unresolved IDs, and reconciliation without selection or global-notice changes. The ordinary existing random-claim button behavior is otherwise unchanged.
Fix commit: `97fe6c77` — 🐛 Fence delayed work entry to its originating task session. Only the coordinator file was staged; controller ticket changes remain untouched. CODE-FROZEN after compilation and checks.
### Controller GREEN required
After reload, repeat the actual same-ID delayed replay; switch to another clean task and verify URL/editor/selection remain on that task when the result arrives, while the genuinely claimed item remains in My Tasks. Repeat while creating a dirty description draft: no stale automatic navigation or leave dialog, draft retained. A delayed error or empty result should likewise leave the new task's notices alone; unknown failure must retain its request ID. Replaying a confirmed receipt can reuse the already claimed isolated pool-03 task rather than consume another task. Also check an unswitched clean entry still opens the returned task normally, and task/account/project/route round trips cannot restore an old continuation. Controller owns the final public API readback and scoped review.

View File

@ -0,0 +1,17 @@
### Finding Verdicts
- **P2 — Fence delayed claim navigation and entry notices to the originating task session — ADDRESSED.** Both Start Work claim paths now pass `entryStillCurrent` (`src/pages/AnnotationOperations.tsx:3195`, `:3219`). The predicate captures task-context identity plus account/project/router-context identity and checks current dirty state (`:3178`); context replacement and unmount cleanup invalidate obsolete entries (`:680`). Random-claim success, empty/error notices, and navigation honor that predicate, while a confirmed allocation remains reconciled in the matching account/project pool (`:3091`, `:3127`, `:3129`). Owned-read errors now use the same predicate (`:3222`). The specific prior defect—late replay navigating away from a subsequently selected task—no longer exists in the reviewed code.
### New Breakage in the Fix Diff
- None identified.
### Out-of-Scope Observations
- None added. Previously disclosed Node/build-size warnings remain unchanged verification debt.
### Verdict
- **Fix round: All findings addressed, no new Critical/Important breakage.** Controller browser GREEN remains required and is not claimed by this static re-review.
- **Checks performed:** read the supplied `ce012f8a..97fe6c77` fix package and appended fix report once. The report names the four covering frontend test files and records 32/32 passing, zero failures/warnings, plus successful lint/build/format/diff checks. No repeated tests or git commands.
- **Focused contract check:** the fix newly relies on reference equality for the authoritative task context. Inspected only `src/lib/annotation-authoritative-mutation.js:110`: `current()` returns its stable stored object, and `switchTo` replaces it on a different task/account, so A → B → A cannot revive the captured session. No implementation, index, branch, browser or fixture mutation; only this requested review artifact was written.

View File

@ -0,0 +1,30 @@
### Spec Compliance
- ❌ Issues found: the new random-claim entry continuation is not fenced to the task context captured by Start Work. A late result can navigate after the user has selected another task (`src/pages/AnnotationOperations.tsx:3115`, `:3172`, `:3196`). See Important finding below.
- ✅ The final outer annotator guard admits `/work`, and the new plugin-guarded route renders the existing coordinator (`src/App.tsx:142`, `:218`). Explicit entry prioritizes freshly read owned unfinished work and otherwise invokes the existing random claim (`src/pages/AnnotationOperations.tsx:3138`, `:3178`, `:3196`).
- ⚠️ Cannot verify from diff: actual full slice/materialization/description/quality-handoff journey, phase-one keyboard/frame/dictionary/blank-invalid-discard acceptance, role/supplier/CAS enforcement in unchanged backend code, and native/browser leave behavior. Controller owns those browser/public-API gates. The implementer explicitly leaves these pending (`.superpowers/sdd/annotation-keyboard-workflow/task-9-report.md:23`, `:74`). Ticket10 refresh/multipage and ticket11 automatic next are not delivered or claimed by this change.
### Strengths
- Shared composition preserves one editor and coordinator instead of duplicating their state or mutation paths (`src/App.tsx:218`, `src/pages/AnnotationOperations.tsx:4235`). The dedicated return action uses router navigation, which remains subject to the existing dirty-state blocker (`src/pages/AnnotationOperations.tsx:1299`).
- Owned-task entry checks account, project, selection and dirty state after both reads, excludes downstream stages, and preserves unresolved logical claim replay (`src/pages/AnnotationOperations.tsx:3156`, `:3172`, `:3178`, `:3190`).
- Task changes clear prior error/success/processing/recovery notices at the existing selection boundary; completion retains its newly supplied notice after closing the old task (`src/pages/AnnotationOperations.tsx:652`, `:3034`).
### Issues
#### Critical (Must Fix)
- None identified in this task diff.
#### Important (Should Fix)
- **P2 — Fence the claim continuation and entry errors to the originating task session.** `src/pages/AnnotationOperations.tsx:3115` unconditionally calls `openWorkTask` after checking only account/project. Both Start Work branches call this continuation (`:3172`, `:3196`) without carrying their `entryStillCurrent` guard (`:3156`). Reproduce with an unresolved random claim: click Start Work to replay it, select another clean owned task while the response is delayed (task cards remain enabled at `:3748`), then resolve the replay. The old response navigates away from the newly selected task. A newly dirty editor instead receives a leave prompt caused by the stale response. Related error paths at `:3129` and `:3199` also publish stale entry notices after task changes. Preserve/reconcile the actual claim result, but gate navigation and entry notices with the captured task/account context and current dirty state; invalidate the entry on task-session changes. Add a focused delayed-response browser check for task switching and editing during replay, alongside existing account/project fencing checks.
#### Minor (Nice to Have)
- Build output is not pristine: the report records existing Node deprecation and large-chunk warnings (`.superpowers/sdd/annotation-keyboard-workflow/task-9-report.md:46`, `:99`). These are disclosed pre-existing verification debt, not an additional blocker introduced by ticket09.
### Assessment
- **Task quality: Needs fixes.** Route integration and shared composition are sound in the final two-commit package, but the new async navigation continuation misses the task-context fence already used for the read path. Approval also remains conditional on controller-owned browser/API acceptance.
- **Checks performed:** reviewed the supplied `c2058c92..ce012f8a` package and implementer report; recovered sections omitted by initial tool-output truncation. No git diff regeneration or test reruns. Focused extra inspection addressed one named risk: stale random-claim navigation after task/dirty changes. The random-claim function was cut off between diff hunks, so its full implementation and the existing selection/leave-blocker contract were inspected (`src/pages/AnnotationOperations.tsx:3077`, `:1299`, `:3052`, `:3212`); a narrow error-banner check confirmed project load errors remain displayed (`:3472`). Exact-reference searches located cited lines. No code, index, branch, browser, API fixture or service was mutated; only this requested review artifact was written.

View File

@ -0,0 +1,59 @@
# 标注时间轴与动作导航调整(2026-09-18)
## 用户要求与实现
专注模式与原布局共用工作台,统一完成以下修改:
- 移除切片/标注页的“原始数据人工版”提示,不改变视频处理配置。
- 移除两条时间轴的分页、查找和“当前”导航栏。切片轴始终使用完整 Capture 范围,动作轴始终使用当前切片范围,滑块、色块和蓝色播放线使用同一时间比例;消除动作滑块单独缩短 400px 的样式。统一 16px 滑块圆心、蓝线、区间色块和鼠标定位的坐标,拖动边界也使用同一换算。
- 专注模式中的切片色块由 20px 加高至 48px,动作色块加高至 42px;原布局切片、动作色块均为 64px。短动作的时间文字不再换行挤出边框,超长文字截断;完整内容仍可通过编辑区及悬浮详情查看。保留边界拖动手柄。
- ↑/↓:按时间顺序切换当前切片内的上一个/下一个动作,暂停并定位到目标动作结束时间;到首尾不循环,不跨切片。无选中动作时,从播放头附近开始。
- Ctrl/⌘ + ↑/↓:暂停并定位到当前动作的开始/结束时间。文本输入、中文输入法、字典弹层保留自身按键行为;按住按键不会连续触发切换。
- 未保存动作编辑先保存或取消后再切换;确定结束点时不允许导航悄悄改变正在编辑的边界。导航不会自动保存或提交任务,键盘切换不会把视频滚出视野。
- 快捷键帮助按切片/逐片标注分别展示分割、删除、字典与阶段提交含义,标注阶段增加动作导航说明。
## 验证与发布边界
用户明确要求跳过本地测试,提交后直接部署公司集群验证。本次执行静态类型检查和构建,不运行本地测试套件或本地浏览器工作台。为后续 CI 补充快捷键、动作邻接选择的回归用例;未运行的用例不记为通过。
仅部署 `droboticflow-fanyu` 的 API 前端镜像,以已发布的心跳修复镜像为基础,保持后端二进制不变;保留回退镜像和配置版本信息。代码提交在个人功能分支本地保存,本次未获 Git push 请求。
线上验证覆盖真实已存在任务、两种布局、不同窗口尺寸、键盘导航、文本/字典隔离、布局和视频加载,不保存或提交测试业务数据。
## 发布记录
- 最终功能代码:`64118cad183d6bb4eb89c1ac8b78ff01e95eaab6`。此前两次任务内提交为 `0ab57b67`(布局及快捷键)和 `3cf94299`(滑块圆心对齐)。
- 目标:`http://120.48.180.80`,命名空间 `droboticflow-fanyu`,仅更新 `deployment/droboticflow-api`。
- 最终镜像:`ccr-29eug8s3-vpc.cnc.bj.baidubce.com/fanyu/droboticflow-api@sha256:e95f9613156c6448b92edeee5c1392cbe52497e785ee632a95e30ef860b454bc`。
- 上线完成,API 1 个副本就绪,检查时重启次数为 0。公开就绪接口返回本次提交及镜像,61 个前端文件的 SHA-256 与提交后构建产物逐一一致。
- API 后端二进制 SHA-256 为 `7d823fc765b334f980a2701d7b903e3dd5ed1fc445fb52e879cd86a24b527876`,与此前心跳修复版本一致;切片处理器镜像未变。本次未重启 worker 或切片处理器。
- 静态类型检查 `npm run lint:web`、干净源码构建通过。按用户要求未运行本地测试套件,也未启动本地浏览器验收。新增的回归用例留待后续 CI 执行。
本地证据目录:`local-data/verification/annotation-navigation-final-20260918/`,包含镜像记录、资源校验、后端校验、线上浏览器结果、局部时间轴截图和回滚配置,均不随 Git 提交。
## 公司环境验收结果
使用现有已领取任务在公司网站实际操作,浏览器脚本退出码为 0:
| 检查项 | 结果 |
| --- | --- |
| 专注模式尺寸 | 1280×640、1440×900、1920×1080、2560×1440 均通过;页面无需整体滚动,两条时间轴均在视口内 |
| 原布局尺寸 | 1280×640、1440×900、1920×1080 均通过;保留原布局原有滚动方式 |
| 播放线对齐 | 7 组布局测量中,蓝线与滑块圆心理论位置误差最大约 0.012px |
| 文字及占用空间 | 两种布局切片/动作文字均限制在卡片边界内;已查看实际截图;原始数据提示及两行查找/当前导航均不存在 |
| ↑ / ↓ | 在当前切片的两个真实动作间切换,双视频均暂停并到达所选动作结束点 |
| Ctrl / ⌘ + ↑ / ↓ | 双视频均暂停并到达当前动作起点/终点 |
| 输入与弹层 | 文本框方向键、中文输入法事件、长按重复事件不会误切换;字典继续响应自己的方向键,一次 Esc 退出 |
| 未保存编辑 | 临时编辑后尝试切换会被阻止并提示先保存或取消;取消后恢复,未发送保存请求 |
| 分阶段帮助 | 两种布局分别验证切片/逐片标注帮助;动作导航仅在标注阶段出现,分割说明与阶段一致 |
| 数据与页面错误 | 标注任务版本保持 11,工作区内容回读前后相同;无保存、提交或领取业务请求,无页面脚本异常;测试后退出登录 |
浏览器覆盖为 Edge(Chromium)。公司站点仍是 HTTP,独立工作页验收沿用此前获准的、仅限该站点的临时安全来源例外;普通浏览器检查仍为非安全上下文、无 Web Locks,并保留登录要求。本次未修改浏览器默认安全策略或网站的连接模式。
质检布局的空间和未保存评论保护经过代码审查,本轮未执行质检账号的浏览器验收。切片生成、任务提交等后端业务流程未在本轮重复执行,避免改变真实业务任务。
## 回退与使用
上线前记录了原镜像及公开构建元数据;最终版本的回滚补丁已经服务端 dry-run 验证通过,未实际回滚。完整任务前的基线镜像和中间版本记录也保留在同级验证目录,部署失败时可选择对应记录恢复。本次临时构建 Job、ConfigMap 及校验过的上传包已清理,线上镜像、回退记录与业务数据保留。
刷新公司网页即可加载本次版本。标注时先选中切片,再使用 ↑/↓ 选择动作;若焦点在描述输入框,先按 Esc 回到工作台。未保存内容需要先保存或取消,才可切换动作。Mac 可用 ⌘ 替代 Ctrl 定位动作起止点。

View File

@ -0,0 +1,162 @@
# 专注标注工作页整体验收
日期:2026-09-18。实施票 01–08 已经逐票独立审查通过;本报告为 08 的组合验收,不代替前置验收。最终[双轴审查](./final-review.md)已完成,无未解决的阻断项。产品范围以[父规格](../../../.scratch/annotation-workspace-layout/spec.md)为准,操作说明见[中文手册](../../annotation-workspace-layout.md)。
所有实际业务写入仅发生在本机 Vite 5173、API 3001、snapshot Mongo 27018 的隔离任务。使用 Microsoft Edge / Playwright,`--no-proxy-server`;没有公司集群、BOS 写入、部署、合并或推送。认证文件、视频、截图、原始日志与隔离浏览器配置均在忽略的 `local-data/` 内,不进入版本库。
## 证据如何阅读
“本轮”指 08 新跑的浏览器/API 或命令结果;“前置”指已经独立审核的 01–07 原始记录,不宣称重新执行。逐票报告与复审记录已归档至[证据索引](./task-evidence/README.md)。验收以可见交互、媒体几何、公共 API 回读和请求次数为边界,没有新增内部状态或源码字符串验收。
本轮补入长期错误状态命中测试时发现真实问题:无效切分提示在 1920×980 遮挡“上一帧”。固定 `bottom:128px` 与随视口变化的播放区不匹配。提示现置于专注切片编辑区内,原布局保持原来的提示位置;五档尺寸下提示可见、操作命中和无文档滚动均通过。重复描述操作 CSS 已按最终计算值合并,Layout.tsx 已格式化。
## L01–L16 覆盖矩阵
| 场景 | 证据与结果 | 限制 |
| --- | --- | --- |
| L01 进入/离开 | 本轮真实 Start Work 同标签页、本人任务优先且无 claim;前置 01 原任务入口、导航回退和离开保护通过 | 未部署公司环境 |
| L02 五档两阶段 | 前置 02/03 普通编辑、04 长列表、05 长文本、06 放大;本轮字典、错误控件、两阶段确认弹层及双路/单路尺寸通过 | CSS 内容区测试,不等于五台物理设备 |
| L03 窗口/缩放 | 本轮真实 Edge 四档窗口×三档缩放 12 组通过,见下表 | 非物理显示器/OS 缩放矩阵 |
| L04 双视频 | 真实 590×480 两路,最小每路 410.54×334;前置同步/帧操作与本轮媒体回归通过 | 使用本地真实媒体副本 |
| L05 不同比例 | 前置及本轮 16:9、9:16、左右不同比例完整 contain 显示通过 | 明确为 12 秒合成素材,不是客户覆盖 |
| L06 放大/恢复 | 本轮五档、左右放大、进度条零覆盖、逐帧、草稿、原布局隐藏路恢复通过;零业务写入 | 原布局保持自己的显示偏好 |
| L07 字典/焦点 | 本轮两阶段搜索/分页/长词条/键盘、Tab/外部点击后一次 Esc 与 Space、原字典点击和键盘通过 | 不以旧 portal 属性字符串作为证明 |
| L08 大量条目 | 前置 04:13 切片/13 描述、序号、极小区间、跨页历史、双向边界与 API 回读通过 | 本轮不重复消耗已保存历史 fixture |
| L09 长文本/名称 | 前置 05 五档长文本展开、固定保存/取消、原生 cut/undo、模板及提交草稿拦截通过;本轮长字典复验 | 中文组合事件是合成派发,原生系统 IME 未通过实测 |
| L10 布局切换 | 前置 01/03/05/06 已证实帧、选择、跨片草稿、历史及 API 保存;本轮闭环草稿切换和媒体回归通过 | 刷新不恢复草稿/撤销栈 |
| L11 延迟响应 | 前置 01 延迟保存、07 在途保存/生成/提交/领取与原布局切换通过 | 延迟/断开只发生在真实 API 完成后的交付侧 |
| L12 低于底线 | 本轮 viewport 回归和实际缩放暂停通过;草稿/停止选择保留,长大不自动恢复 | 完整专注编辑不支持底线以下 |
| L13 在途尺寸变化 | 前置 07 所有请求边界、同 ID 未知领取恢复、403、未知生成核对通过;972721e 补充本人列表/详情晚到保护 | 不重复领取已完成的 unknown fixture |
| L14 偏好/刷新 | 前置 01 同一浏览器两真实账号切换、账号偏好隔离、刷新显式恢复与零 claim 通过 | 本地存储不可用时偏好不保证持久化 |
| L15 连续闭环 | 本轮真实生成、保存、送检→下一条;停止、显式恢复和空池,详见下方流水 | 送检成功仅代表进入待质检 |
| L16 原布局/审核隔离 | 原入口和原字典本轮通过;原快捷键、布局、媒体偏好有 01/06 与本轮回归;审核页隔离见下方 | 不把审核壳页当成完整审核流程验收 |
## 全部 30 条用户故事
| 故事 | 对应证据 |
| --- | --- |
| 1 当前标签页 | L01,真实 Start Work |
| 2 收起平台导航 | L01,01 浏览器 |
| 3 默认双画面 | L04,06 与本轮 |
| 4 等比完整显示 | L04/L05,真实及合成分开 |
| 5 大窗口增大画面 | L02/L04,五档测量 |
| 6 明确最小视口 | L03/L12,1280×640 边界 |
| 7 阶段共用骨架 | L02,02/03 与真实生成切换 |
| 8 固定播放/逐帧/标记 | L02,02/03/06,本轮错误命中 |
| 9 视频下方时间轴 | L02,双路/放大回归 |
| 10 视频旁编辑 | L02,03/05 |
| 11 固定编辑区字典 | L07,本轮两阶段 |
| 12 字典搜索/分页/键盘 | L07,本轮两阶段 |
| 13 长列表分页导航 | L08,04 |
| 14 选择/历史显示目标页 | L08,04 |
| 15 长文本有界/展开 | L09,05 |
| 16 保存/取消/提交可达 | L02/L09,03/05、本轮闭环 |
| 17 帮助与低频入口 | L02,02/03 |
| 18 任一路主动放大 | L06,06 与本轮 |
| 19 放大压缩时间轴 | L06,零画面覆盖 |
| 20 一键恢复双路 | L06,帧与草稿保持 |
| 21 尺寸改变保留编辑 | L12,07 与本轮 |
| 22 小窗口暂停/不接续 | L12/L13,07 与本轮 |
| 23 显式恢复 | L03/L12,12 组真实缩放 |
| 24 在途结果核对 | L13,07 |
| 25 原布局回退 | L10/L16,01 与本轮 |
| 26 回退保留草稿/历史 | L10,01/03/05/06 |
| 27 账号/浏览器偏好 | L14,01 |
| 28 快捷键与焦点 | L07/L09/L16,浏览器交互与定向测试;原生 OS IME 限制保留 |
| 29 领取与送检恢复 | L11/L13/L15,01/07 与本轮 |
| 30 可核验源码恢复 | 本轮标签与完整 bundle 只读核验 |
## 五档 CSS 内容区与有效画面
真实素材为 590×480;测量的是等比适配后的有效图像,不包含留黑。数字来自 06 原始记录,本轮 camera runner 再次得到相同结果。双画面和单路放大均无文档横向/纵向滚动,主要操作可达。
| 内容区 | 每路双画面 | 单路画面 |
| --- | --- | --- |
| 1280×640 | 410.54×334 | 531×432 |
| 1366×680 | 459.71×374 | 580.17×472 |
| 1440×800 | 529×430.37 | 727.67×592 |
| 1920×980 | 769×625.63 | 948.92×772 |
| 2560×1320 | 1089×885.97 | 1366.83×1112 |
最低双路要求 400×325、单路要求 490×398 均满足。文本框和字典长内容可内部滚动,不属于文档滚动。
## 真实浏览器缩放矩阵
使用隔离的 Edge persistent profile、`viewport:null` 和真实窗口 `--window-size`;在浏览器设置页通过 settingsPrivate 修改默认缩放,并读取缩放值、innerWidth/innerHeight 与 devicePixelRatio。没有 CSS zoom、模拟 viewport 或 deviceScaleFactor 替代。每组最后恢复 100%,配置目录不使用用户的个人 profile。
| 外部窗口 | 缩放 | 实际 CSS 内容区 | DPR | 行为 |
| --- | --- | --- | --- | --- |
| 1366×768 | 100% | 1358×684 | 1 | 正常 |
| 1366×768 | 125% | 1086×547 | 1.25 | 暂停 |
| 1366×768 | 150% | 905×456 | 1.5 | 暂停 |
| 1440×900 | 100% | 1432×816 | 1 | 正常 |
| 1440×900 | 125% | 1146×653 | 1.25 | 暂停 |
| 1440×900 | 150% | 955×544 | 1.5 | 暂停 |
| 1920×1080 | 100% | 1912×996 | 1 | 正常 |
| 1920×1080 | 125% | 1530×797 | 1.25 | 正常 |
| 1920×1080 | 150% | 1275×664 | 1.5 | 暂停 |
| 2560×1440 | 100% | 2552×1356 | 1 | 正常 |
| 2560×1440 | 125% | 2042×1085 | 1.25 | 正常 |
| 2560×1440 | 150% | 1701×904 | 1.5 | 正常 |
正常组检查固定按钮命中和无文档滚动;暂停组检查提示、视频暂停及恢复按钮在不足尺寸时禁用。恢复尺寸后提示仍在,点击继续才恢复编辑,草稿保留。全部零写入。这是实际浏览器引擎窗口/缩放测试,**不是多物理显示器或 OS 缩放实测**。
## 连续流水与隔离数据
本轮及审查修复使用五组唯一前缀 fixture,所有中间结果保留,未重置完成任务。初次组合证据链在 `project-workspace-full-workflow3`,最终提交候选脚本已在 `project-workspace-full-workflow5` 完整一次运行并退出 0(见下方复验)。Start Work 从原入口在当前标签页优先继续 owned slice-primary,没有随机领取。主任务 v1→5 完成真实 4 片生成(412 秒有效范围,连续覆盖,无间隙/重叠)→6 保存描述→8 审核数据准备完成并进入 quality_review,然后随机领取 pool-02 v2。
最初 `workspace-full-workflow` 主任务已生成和保存,但脚本误用确认弹层标题而超时;修正后从当前权威阶段恢复,送检至 v8。已领取 pool-02 完成原有 3 片生成至 v6;脚本在自动切换瞬间未等切片界面就绪,预期 4 片的断言失败。`workspace-full-workflow2` 主任务真实 4 片生成至 v5,期间页面回到显式恢复。最初把它归因于 Layout.tsx 格式整理,但当时没有导航事件证据,不能确认具体触发文件;后续受控复现证实普通 Markdown 写入也会触发此 Vite 实例的 full-reload。这些均是测试设置/开发环境中断,不是产品 RED,也未通过重置数据隐藏。
第三组主任务完整通过后,下一条 URL 已更新但旧描述控件尚未替换,计数断言过早采样。增加等待“确认全部切片”和实际删除切片按钮,再显式恢复已领取、仍为 v2 的 pool-02 接续;没有补发领取或重置。随后 pool-02 v2→6 生成→7 保存→9 quality_review;停止选择下等待 3.5 秒没有新 claim,显式恢复才随机领取 pool-01 v2,后者 v2→6→7→9 完成。最终一次空池 claim 后再等 2.5 秒没有循环请求。
最终链合计 3 次生成、3 次描述保存、3 次送检、2 次成功随机领取与 1 次空池请求。续跑部分的请求计数为 2/2/2、1 次成功领取与 1 次空池,各 requestId 不重复。两次送检后没有等待质检员审批。完整版本链与中断说明共同构成证据,不宣称脚本一次从头到尾无中断运行。
### 审查修复后的最终脚本复验
独立审查发现 `89c9e168` 中最后一次清理临时恢复分支破坏了脚本作用域:切片循环误断言 annotate,后续使用了已离开作用域的变量。历史服务端证据仍真实,但该提交的脚本不能据此声称可运行。使用全新第四组 owned primary 安全复现,运行在任何业务写入前失败,公共 API 确认仍为 v1/slice。修正仅删除 8 行残留结构,把生成、保存、送检及接续恢复到同一个任务循环。
修正版首次在第四组真实生成 4 片至 v4 后,页面被开发服务器刷新。随后在这条已生成任务上做零业务写入诊断:只向验收 Markdown 追加临时注释,Vite WebSocket 发出 `full-reload`,接着出现 beforeunload、pagehide、导航与 pageshow,页面从活动工作转为显式恢复;恢复 Markdown 原字节也触发相同刷新。因此最终运行冻结所有仓库写入,包括文档、归档和执行记录,不只冻结产品代码。第四组 v4 及全部此前结果保留。
最终未再修改的脚本在第五组一次完整运行,退出码 **0**:
| 第五组任务 | 初始 | 真实生成 | 描述保存 | 真实送检完成 |
| --- | --- | --- | --- | --- |
| slice-primary | v1 | v5,4 片 | v6 | v8,quality_review |
| pool-02 | v2 | v6,4 片 | v7 | v9,quality_review |
| pool-01 | v2 | v6,4 片 | v7 | v9,quality_review |
准确请求总数为 3 次生成、3 次保存、3 次送检、2 次成功随机领取和 1 次空池请求;停止后不领取、显式恢复及空池不循环全部通过。执行前后脚本 SHA-256 均为 `a20779d7c1187106f1f01e441574094bc19bc507964e82f9a78f5b8a14fa9f56`。最终复验没有以早期脚本日志代替最终文件执行;语法检查之外,TypeScript 的未定义标识符检查为 0,且完整真实浏览器运行通过。
精确命令:`WORKFLOW_PREFIX=workspace-full-workflow5 WORKFLOW_LABEL='整体第五轮验收切片 001' node tests/browser/annotation-workspace-full-workflow.mjs`。日志为忽略目录中的 `task08-runner-review-green5.log`。请勿重跑或重置这些已完成的任务;后续有状态复验需新隔离 fixture,并在整个运行期间冻结仓库写入。
未知结果恢复采用前置 07 已审核的实际 API 证据:unknown3 的两个传输请求沿用同一 requestId,只领取同一任务 v2;真实成功生成的响应丢失后,显式核对阶段结果恢复至 annotate,未重复生成;403 权限失败保持版本不变并阻止自动恢复。详见 task-7-report.md,不重复消耗这些任务。
## 质检与最终验收布局隔离
本轮使用主任务新建的隔离 reviewer 账号和已有素材的独立任务副本。质检 `human-item-workspace-layout-review-qc` 在两个内容区(1280×640、1920×980)显示原平台导航、真实双视频及原审核按钮;没有专注切换、单路检查或小窗口暂停入口,允许原来的滚动访问。最终验收 `human-item-workspace-layout-review-acceptance` 同样保留原平台、验收内容与意见面板;两个 item 均保持 v1,浏览器观测零业务写入。没有领取或审核决定。
最终验收的加载媒体覆盖受本地 snapshot 限制:其既有 `prepackage_acceptance` 数据引用产物 `run-d635f13bd89fa9fd50c0665181d884ae-fanyu-v56-human-materialized-revision-000003`。实际 evidence members API 返回 HTTP 200、recognized=true、dataSource=FILESYSTEM,但 items=[]、total=0、contentAvailableCount=0。严格等待媒体就绪超时,因此只计入实际验收面板与样式隔离,不宣称视频、姿态或文件完整性通过;没有替换、合成或改写该 payload 来获得通过。测试脚本明确输出 COVERAGE LIMIT。
## 定向检查与全套已有问题
本轮 `npm run lint:web`、`npm run build:web` 通过。Vite 保留现有 module.register 废弃提示及大于 500 kB chunk 提示。54 项定向前端测试通过,其中 `capture-responsive-layout.test.mjs` 剩余 3 项通过。仅在真实浏览器验证旧 portal 和新 inline 字典后,删除已失效的源码字符串测试及未使用的 import,未改写正则去镜像实现。
全套检查由主任务只跑一次:前端初始 578 项,568 通过、10 失败,其中 9 项与基线一致,1 项为上述过时断言;本轮仅定向修正,不把结果说成第二次完整套件通过。Go、Python 等基线失败及环境限制详见[主任务维护的全套结果](full-suite-results.md)。Layout.tsx 的原有格式警告已修正,其余 52 个未触及文件的警告未批量处理。
源码恢复点再次核验为 `54a35afad95d77b1f23c955f9c4671cae83a664d`,`git bundle verify local-data/backups/annotation-keyboard-baseline-20260918.bundle` 返回 okay、完整历史。它不能恢复数据库、视频或浏览器草稿;本次未执行恢复。
## 运行入口
浏览器脚本使用 ignored auth.json;有状态生成/送检脚本需要新隔离 fixture,不得重置旧任务。精确命令及消耗版本见 task-8-report.md。
| 脚本(tests/browser/) | 作用与写入范围 |
| --- | --- |
| annotation-workspace-full-workflow.mjs | 单次真实连续作业;只允许 full-workflow 前缀,本地生成/保存/送检/领取 |
| annotation-workspace-zoom-matrix.mjs | 12 组真实缩放,零业务写入 |
| annotation-workspace-errors-and-legacy.mjs | 五档真实错误控件、两阶段确认弹层及旧字典操作,零业务写入 |
| annotation-workspace-review-isolation.mjs | 真实质检/验收工作台隔离与公共版本不变,零业务写入 |
| annotation-workspace-dictionaries.mjs | `ANNOTATION_DICTIONARY_READ_ONLY=1` 复验字典,跳过长文本保存;默认模式会保存/撤销/重做 |
| annotation-workspace-camera-inspection.mjs | 两阶段五档画面和合成比例,零业务写入 |
| annotation-workspace-viewport.mjs | 草稿、暂停恢复、原布局、确认层级和单活动页,零业务写入 |
尚未宣称覆盖:原生操作系统中文输入法、所有物理显示器和系统缩放、所有浏览器/操作系统、客户全部素材、公司 HTTPS/部署就绪、数据库/媒体恢复、真实质检通过及最终验收通过。现有失败和这些限制不会被局部浏览器通过所覆盖。

View File

@ -0,0 +1,112 @@
# SDD ledger — plan: local-data/verification/annotation-workspace-layout/annotation-workspace-layout-plan.md
Implementation baseline: ee2e355b. Current branch: feature/local-dev-toolkit. Full final review compares this baseline to final HEAD.
Ruling: Implement the eight newly published workspace-layout tickets, not repeat the eleven completed keyboard tickets — the user referenced the previous count while asking to execute the current tickets — if wrong, a separately scoped additional task may be needed.
Ruling: Work in the current clean feature checkout — the explicitly invoked implement skill requires commits on the current branch and this checkout owns the local verification stack — if wrong, later isolation would require moving local commits.
Ruling: Use ee2e355b as the final code-review fixed point — it is the recorded implementation-start HEAD immediately after all eight tickets were published — if wrong, a broader historical review would need a different baseline.
## Preflight: individual tickets
| Task | Internal consistency |
|---|---|
| 1 | Published behavior, dependency and browser/API acceptance agree; no source-string tests required. |
| 2 | Published behavior, dependency and browser/API acceptance agree; no source-string tests required. |
| 3 | Published behavior, dependency and browser/API acceptance agree; no source-string tests required. |
| 4 | Published behavior, dependency and browser/API acceptance agree; no source-string tests required. |
| 5 | Published behavior, dependency and browser/API acceptance agree; no source-string tests required. |
| 6 | Published behavior, dependency and browser/API acceptance agree; no source-string tests required. |
| 7 | Published behavior, dependency and browser/API acceptance agree; no source-string tests required. |
| 8 | Published behavior, dependency and browser/API acceptance agree; no source-string tests required. |
## Preflight: shared surfaces
| Pair | Producer / consumer and finding |
|---|---|
| 1 / 2 | Task 1 supplies focused/legacy presentation identity and stable session boundary; later layout changes must not remount editing state. No conflicting requirement found. |
| 1 / 3 | Task 1 supplies focused/legacy presentation identity and stable session boundary; later layout changes must not remount editing state. No conflicting requirement found. |
| 1 / 4 | Task 1 supplies focused/legacy presentation identity and stable session boundary; later layout changes must not remount editing state. No conflicting requirement found. |
| 1 / 5 | Task 1 supplies focused/legacy presentation identity and stable session boundary; later layout changes must not remount editing state. No conflicting requirement found. |
| 1 / 6 | Task 1 supplies focused/legacy presentation identity and stable session boundary; later layout changes must not remount editing state. No conflicting requirement found. |
| 1 / 7 | Task 1 supplies focused/legacy presentation identity and stable session boundary; later layout changes must not remount editing state. No conflicting requirement found. |
| 1 / 8 | Task 1 produces behavior and evidence; task 8 consumes it for full workflow verification, not deferred implementation. No conflicting requirement found. |
| 2 / 3 | Task 2 establishes shared video/timeline/editor regions; later changes consume this stable geometry without replacing media/session state. No conflicting requirement found. |
| 2 / 4 | Task 2 establishes shared video/timeline/editor regions; later changes consume this stable geometry without replacing media/session state. No conflicting requirement found. |
| 2 / 5 | Task 2 establishes shared video/timeline/editor regions; later changes consume this stable geometry without replacing media/session state. No conflicting requirement found. |
| 2 / 6 | Task 2 establishes shared video/timeline/editor regions; later changes consume this stable geometry without replacing media/session state. No conflicting requirement found. |
| 2 / 7 | Task 2 establishes shared video/timeline/editor regions; later changes consume this stable geometry without replacing media/session state. No conflicting requirement found. |
| 2 / 8 | Task 2 produces behavior and evidence; task 8 consumes it for full workflow verification, not deferred implementation. No conflicting requirement found. |
| 3 / 4 | Existing task/session state and presentation identity remain shared; execute sequentially and retain prior task regressions. No conflicting requirement found. |
| 3 / 5 | Existing task/session state and presentation identity remain shared; execute sequentially and retain prior task regressions. No conflicting requirement found. |
| 3 / 6 | Existing task/session state and presentation identity remain shared; execute sequentially and retain prior task regressions. No conflicting requirement found. |
| 3 / 7 | Viewport suspension wraps existing play/continuation boundaries independently of panel contents; delayed results must still reconcile. No conflicting requirement found. |
| 3 / 8 | Task 3 produces behavior and evidence; task 8 consumes it for full workflow verification, not deferred implementation. No conflicting requirement found. |
| 4 / 5 | Existing task/session state and presentation identity remain shared; execute sequentially and retain prior task regressions. No conflicting requirement found. |
| 4 / 6 | Existing task/session state and presentation identity remain shared; execute sequentially and retain prior task regressions. No conflicting requirement found. |
| 4 / 7 | Viewport suspension wraps existing play/continuation boundaries independently of panel contents; delayed results must still reconcile. No conflicting requirement found. |
| 4 / 8 | Task 4 produces behavior and evidence; task 8 consumes it for full workflow verification, not deferred implementation. No conflicting requirement found. |
| 5 / 6 | Existing task/session state and presentation identity remain shared; execute sequentially and retain prior task regressions. No conflicting requirement found. |
| 5 / 7 | Viewport suspension wraps existing play/continuation boundaries independently of panel contents; delayed results must still reconcile. No conflicting requirement found. |
| 5 / 8 | Task 5 produces behavior and evidence; task 8 consumes it for full workflow verification, not deferred implementation. No conflicting requirement found. |
| 6 / 7 | Viewport suspension wraps existing play/continuation boundaries independently of panel contents; delayed results must still reconcile. No conflicting requirement found. |
| 6 / 8 | Task 6 produces behavior and evidence; task 8 consumes it for full workflow verification, not deferred implementation. No conflicting requirement found. |
| 7 / 8 | Task 7 produces behavior and evidence; task 8 consumes it for full workflow verification, not deferred implementation. No conflicting requirement found. |
## Tasks
- Task 1: complete; base ee2e355b, implementation a5753731, fix6acc5803. /root/review_workspace_01 approved scoped re-review. Browser/API+44 focused tests+typecheck/build pass.
- Task 2: complete; base304fbca5, heada3c780e8; /root/review_workspace_02 approved. Five-sizebrowser52tests/typecheck/buildpass; generationversion5 four slices412s. Reviewer actualerror-control hit-testpass; Minor durableassertion to08. Fixturepool01ownedslice.
- Task 3: complete; base9fae45f4, heade462437a; /root/review_workspace_03 approved. Browser5size/N/N/drafts/save409/history/cancel+56tests/type/buildpass. Realannotate-delayedquality_reviewv6 independentlyread. Minor CSSactionrowduplicate970vs882/887 tofinalcleanup.
- Task 4: complete; base2c242df5, implementation94b238d5, fixe95adca8; /root/review_workspace_04 re-review approved. Manybrowser/tinyordinal/crossscopehistory/frozenpointer/API +shell56tests/type/buildpass. Finalmanyannov47,slicev1.
- Task 5: complete; base64397225 impl1de1d85b fix6c76e5d2; /root/review_workspace_05 re-reviewapproved. Inline/longtext+47tests/type/buildpass; focusfixrealbrowserbothdict+typepass. Primaryv61; nativeOSIMEunverifiedlimit.
- Task 6: complete; base db5e6d23 impl ee3d6b16 fix af7df833; /root/review_workspace_06 approved. Corrected real minimum dual410.54x334/single531x432,0occlusion; hidden camera recovery preservesframe/nodes/prefs;79tests/type/build/browserpass.
- Task 7: complete; base39bed0fc, implcb74444e, fix972721e. /root/review_workspace_07 scoped re-review approved; actual browser/API,35tests,type/build pass; owned lookup race fixed with real RED/GREEN.
- Task 8: complete; basec0d344bf, impl89c9e168, fixab89c63a. /root/review_workspace_08 scoped re-review approved. Exactfinalrunner full3taskchain exit0,12zoom,5size,error/dict/reviewercases,54tests/type/build pass within documented limits.
## Final gates
- Full tests: complete with documented baseline failures; full-suite-results.md
- Standards review: a313b22a reviewed; map violation fixed b83e810e and scoped review approved;3 advisory smells deferred with reasons/costs.
- Spec review: /root/workspace_final_spec no actionable findings, documented coverage limits retained.
- Final report/manual: delivered; task reports,finalreviews,ledger archived under docs/verification/annotation-workspace-layout.
Task 1 fix round 1: reviewer requests behavioral stop-after-current preservation across toggles; /root/workspace_01 assigned scoped test addition. Controller independently verified baseline tag54a35afa and complete bundle (git bundle verify okay).
Ruling: Keep proportional timeline entries within each bounded four-item page and provide exact ordinal search/selection — the spec requires bounded accessible navigation, while existing duration/drag mapping must remain meaningful — if wrong, equal-width list cards would need an additional presentation surface; tiny entries must still be selectable through search and editable in the fixed editor.
Task 4 fix round 1: /root/review_workspace_04 found twoImportant: destination scope resets crossslice history target; pageedge drag clamp/rescale drift. /root/workspace_04 assigned reproduce/fix/browserregression before nextticket.
Task 4 fix round 1 delivered e95adca8, re-review /root/review_workspace_04. Both actualbrowserREDs reproduced; crossscope nulleditorpage4 and frozenpointerbothdirections/samexstable pass; sharedframepublicAPI persistence verified. manyannov47, slicev1. Existing56tests/type/build/shell+five-size pass.
Task 5 fix round 1: reviewer reproduced Tabfromdictpager tooutsideUndo followedEsc leavesdictopen andglobalkeysblocked. /root/workspace_05 assigned focusedfix+bothdict outsidefocus browserregression.
Task5fixround1 delivered6c76e5d2, /root/review_workspace_05 scopedre-review. BothdictTab/outsideclick→EscSpace noPOST/draftloss/geometrychange; selectiontextfocusretained; typecheckpass.
Native OS IME supplemental attempt: separate headed Edge draft-only window prepared; cua.getApp tool blocked for an abnormally long time and returned unrelated existing browser window. No native typing/input-source changes were performed. Own runner stopped; its browser had already closed. No native IME pass claimed. Avoid further desktop tool calls for this attempt.
Task6 fixround1: reviewer identifies inspection progress overlay atvideo bottom and original camera flags trapping hidden camera on return focused. /root/workspace_06 assigned reproduce/fix, realpicture occlusion checks and successful screenshots.
Task6 fixround1 delivered af7df833, scopedreview /root/review_workspace_06. Corrected single531x432 with reserved28px progress and0occlusion; nonzero frame6 original hide-left/right recovery retains nodes/draft/prefs/sync;79tests/type/build/browserpass. Rootviewed successfulleft/right screenshots.
Browser zoom readiness independently proven in isolated persistent Edge profile via actual setDefaultZoom; see ignored zoom-readiness.md. No user browser profile modified.
Final verification started for unchanged backend surfaces: full Go source packages, Python in .venv, Rust offline. Logs and exit codes in local-data/verification/annotation-workspace-layout/final-checks. Sessions Go60933/Python48131/Rust84597. Frontend suite awaits Task07 product completion.
Additional create-once local fixtures: workspace-viewport-unknown (two unowned ready slices), workspace-viewport-generation (owned slice-primary), workspace-full-workflow (owned slice-primary plus two ready pool tasks, reserved for Task08). No previous task/evidence reset.
Root final backend checks completed: Go13 packages pass/2 no tests/60 existing API failures exact name set; Python648pass25fail3skip, no new failures vs prior25 (old json_to_csv cache failures absent); Rust25tests/lint/release pass; Go builds/script syntax pass; Go formatting existing single-file debt; K8s client discovery localhost8080 blocked,22 local YAML structures pass. Full-suite-status.md and final-checks comparison JSON retain evidence. Backup tag and complete bundle reverified successfully.
Task07 implemented cb74444e; review package39bed0fc..cb74444e dispatched /root/review_workspace_07. Root visually checked actual1100×600 pause prompt, screenshot root-pause-visual.png; no task writes. Full frontend initial578/568/10:9baseline plusobsolete dictionary portal source assertion, assigned08 behavioral verification/retirement. Fullformat53warnings:Layout.tsx only touchedwarning, assigned08 formatting;52untoucheddebt.
Task07 fix round1 dispatched /root/workspace_07: /root/review_workspace_07 actual browser RED delayed owned-pool GET switches completed annotate-primary to owned pool-01 while viewport suspended (no writes). Root agrees Important: owned lookup is not an allocated claim; defer opening next owned task until explicit Continue, retaining handoff intent. Existing in-flight actual claim reconciliation unchanged. Reviewer final report pending.
Task07 fix1 delivered972721e; scoped re-review /root/review_workspace_07. Real pool and summary delays independently RED→GREEN, both continuous/resume-only;0writes/claims,versions3/2 unchanged. Prior viewport suite/type/build pass after fix.
Task08 runtime assistance: fresh workspace-full-workflow2 created after runner seek-timing consumed initial fixtures; prior generated/submitted effects retained. Added two new local reviewer users with correct global quality_reviewer / acceptance_reviewer roles and copied12project memberships each, since snapshot fanyu-full-qc/acceptance are globally annotators. New ignored qc-reviewer-auth.json / acceptance-reviewer-auth.json mode0600; existing users/tasks untouched. Original QA/acceptance login200 but route redirects; opsadmin single known-password login401, no password changes.
Task08 implementation89c9e168, review /root/review_workspace_08. Important committed test-runner cleanup error independently confirmed: wrong annotate assertion before mutation, loop closed early and out-of-scope names. Fixround1 /root/workspace_08; fresh full-workflow4 prepared for runtimeRED(no writes,verifyv1) then finalcandidate completeGREEN. Earlier authoritative3-task evidence retained, never reset. Root archive initial20reports prepared; refresh after fixes/reviews.
Task08 fix1 runtime investigation: finalcandidate runner hash a20779d7c1187106f1f01e441574094bc19bc507964e82f9a78f5b8a14fa9f56; committedRED on fresh4 beforewrites verifiedv1. Generation later interrupted despite unchangedproductsource. Actual controlled Markdown append/restore each emitted ViteWSfull-reload→pagehide/navigation→explicitrecovery,0POST; rootonlydocwrites caused interference. API99553/Vite97816 unchanged, no restart. Coordinated ALL-file-write freeze; freshfull-workflow5 exactcandidate complete exit0,3generate/3save/3handoff/2successclaims/1empty, primaryv8 pools v9QA. Freeze ended afterexit; previousfull4v4 preserved. Fixcommit/report pending.
Ruling: Defer shared browser reachability-helper extraction — current independent acceptance runners passed and extraction would broaden final test changes without a product defect — if wrong, duplicated helpers may drift and need coordinated future updates.
Ruling: Defer centralized four-entry pagination policy — both current consumers agree on the accepted fixed page size, with actual cross-page evidence — if wrong, a future page-size change could miss a consumer until refactoring.
Ruling: Defer shared viewport-size predicate extraction — all current checks match and fresh dispatch-time reads protect races; no behavior defect was found — if wrong, a future minimum-size change could diverge until the checks are centralized.
Final whole-feature fixed HEADa313b22a, Standards1docviolation+3lowheuristics,Spec0. /root/workspace_final_docs_fix assigned sole documented violation.
Final root APIreadback: full-workflow5 primaryv8, pool02/pool01v9, allquality_review/ready. FinalSpec0,Standardsdocviolationclosed+3nonblockingadvisories. Localfeaturebranch preserved; no push/deploy/merge. Plan execution complete.

View File

@ -0,0 +1,53 @@
# 实施与审核记录
本轮实施基线为 `ee2e355b`,分支为 `feature/local-dev-toolkit`。按票号顺序派遣独立实现者,每票完成后由另一位 reviewer 审核,发现问题先修复并复审,再开始下一票。
| 任务 | 实现提交 | 审核修复 | 状态 |
| --- | --- | --- | --- |
| 01 专注工作页与原布局切换 | a5753731 | 6acc5803 | 独立复审通过 |
| 02 单屏切片 | a3c780e8 | — | 独立审核通过 |
| 03 固定描述编辑 | e462437a | — | 独立审核通过 |
| 04 分页与定位 | 94b238d5 | e95adca8 | 独立复审通过 |
| 05 内嵌字典与长文本 | 1de1d85b | 6c76e5d2 | 独立复审通过 |
| 06 单路放大与比例适配 | ee3d6b16 | af7df833 | 独立复审通过 |
| 07 小窗口暂停与请求协调 | cb74444e | 972721e | 独立复审通过 |
| 08 整体验收与说明书 | 89c9e168 | ab89c63a | 独立复审通过 |
## 执行裁决
以下是执行过程中采用的可逆裁决,没有额外要求用户批准:
| 裁决 | 原因 | 若判断错误的代价 |
| --- | --- | --- |
| 执行新发布的 8 张工作页布局票,不重复此前已完成的 11 张快捷键票 | 当前任务目录与已确认的拆分是 8 张;本次请求沿用了上次的数量表述 | 如另有未包含任务,需要另行确定范围并补做 |
| 在现有个人功能分支完成并本地提交 | 明确调用的 implement 流程要求当前分支提交;本检出关联现有本地验证环境 | 如需隔离,可将这些本地提交迁移到另一检出 |
| 最终全量代码审查以 ee2e355b 为固定点 | 这是 8 张票发布后的实施起点 | 若要审查更早历史,需要另选更早基线扩大审查范围 |
| 每页最多 4 项的时间轴仍保持时长比例,并提供精确序号查找 | 既满足有限空间下访问全部条目,也保留时间长度与拖动映射的意义 | 若改成等宽卡片,需要增加另一种呈现;极短条目仍必须可搜索并在固定编辑区修改 |
## 最终审查的维护建议处理
三项均为低优先级的代码结构判断,不是已发现的功能故障;本轮保留现状:
| 裁决 | 原因 | 后续代价 |
| --- | --- | --- |
| 暂不抽取浏览器控件可达性公共测试助手 | 各场景已有独立的成功验收;交付前抽取会扩大测试代码变动 | 重复助手可能漂移,未来修改需同步或再抽取 |
| 暂不统一每页 4 项的常量入口 | 当前两处值一致,跨页导航已实测 | 未来调整页大小时可能漏改一处,应届时集中策略 |
| 暂不抽取小窗口判断公共谓词 | 当前阈值一致,并保留请求发出时读取最新窗口大小的竞态保护 | 未来改变支持底线时需要同步修改或集中判断 |
## 已发现并修复的主要问题
- 跨切片重做后目标页被重置;页边缘拖动被当前页限制且移动比例漂移。
- 字典焦点移到外部后,Esc 无法正确退出。
- 单路放大的进度条遮住有效画面;原布局隐藏相机后进入专注视图不能恢复该路。
- 窗口恢复可能清除未知领取结果的暂停;暂停层遮挡离开确认或被原生提交弹窗覆盖;主动继续后键盘焦点丢失。
- 迟到的本人任务列表或详情在暂停期间切到下一任务。
- 大窗口中切片错误提示遮住逐帧按钮。
- 最终验收脚本在清理临时分支时破坏循环作用域,语法检查无法发现;独立审核发现后要求以最终脚本完整重跑。
产品问题均有针对性的真实浏览器回归或持久化 API 回读;验收脚本修正版完成一轮完整真实流程。详细证据见[整体验收](./acceptance-results.md)与[最终审查](./final-review.md)。完整测试中的既有失败单列于 [全仓测试结果](./full-suite-results.md)。
## 最终关口
全部 8 票已独立审核通过;全功能 Standards/Spec 两轴审核完成,文档问题经 b83e810e 修复并复审关闭。3 项低优先级维护建议按上表记录;没有未解决的阻断项。逐票记录见[归档索引](./task-evidence/README.md),最终结论见[双轴审查](./final-review.md)。
主任务再次通过公共 API 回读最终隔离项目:slice-primary 为 v8,pool-02 与 pool-01 为 v9,三者均为 quality_review / ready,与最终浏览器日志一致。所有改动保留在本地 feature/local-dev-toolkit;没有推送、合并或部署。

View File

@ -0,0 +1,24 @@
# Final documentation fix report
## Commit
`b83e810e` — `📋 Record resolved annotation workspace decisions`
The commit contains only `.scratch/annotation-workspace-layout/map.md`.
## Changes
- Marked tickets 01–08 as resolved and independently reviewed.
- Added one linked, concise result for each ticket, including its implementation and review-fix commit where applicable.
- Linked the operator manual, combined acceptance report, full-suite result, and execution record.
- Preserved the design and preview observations while labeling them as historical, and replaced obsolete present-tense claims about implementation, browser verification, the original workbench, and local 5173.
- Recorded the retained limits: native OS IME, physical display/OS-scale coverage, zero final-acceptance media members, and no push, deployment, or QA approval.
## Checks
- `git diff --check` passed before the commit.
- A local Markdown-link check verified all 18 links in `map.md` resolve.
- `git diff --cached --check` passed immediately before the commit.
- No browser run, company-service access, push, deployment, or QA approval was performed.
`docs/verification/annotation-workspace-layout/execution-record.md` was already modified in the working tree and was left unstaged and uncommitted.

View File

@ -0,0 +1,15 @@
# 最终双轴审查结果
固定基线 `ee2e355ba1838578b0611628bc764abbbeec6eef`,完整功能审查 HEAD 为 `a313b22a`。两位独立 reviewer 并行审查 Standards 与 Spec,不以逐票通过代替组合审查。
## Standards
[原始规范审查](./final-standards-review.md)提出 1 项文档规范问题及 3 项低优先级维护判断。设计 map 的当前状态及 8 票结果链接已在 `b83e810e` 修复,[针对性复审](./final-standards-fix-review.md)确认问题关闭,18 个链接与 8 个已解决任务引用有效。没有未解决的规范违规或生产代码规范问题。
3 项维护建议仍然保留:抽取浏览器可达性测试助手、集中每页 4 项的策略、集中小窗口阈值判断。它们不是功能缺陷,未伪称已修复;保留现状的原因与后续代价见[执行裁决](./execution-record.md)。
## Spec
[原始需求审查](./final-spec-review.md)没有发现可确认的缺失实现、范围扩张或错误行为。reviewer 独立核对了最终脚本哈希与三条完整业务链路日志。原生 OS 输入法、全部物理设备/系统缩放及本地缺失验收媒体仍是明示覆盖限制。
两轴分别结论:Standards 的 1 项违规已关闭,剩余 3 项低优先级维护建议;Spec 为 0 项可确认的问题。没有未解决的阻断项,也没有全仓测试全绿、质检通过或已部署的声明。

View File

@ -0,0 +1,17 @@
# Final whole-feature Spec review
Reviewed `ee2e355ba1838578b0611628bc764abbbeec6eef...a313b22ae824208feb9fc6ac30103b36c3325e65` against the layout specification, tickets 01–08, retained keyboard contract, CONTEXT.md and ADR-0001. Read the production diff, relevant browser runners, acceptance/manual/execution records and task evidence. No product, index or HEAD mutations; no browser or broad-suite rerun.
**Result: no confirmed actionable Spec findings.**
- **Missing/partial implementation:** none established. The shared mounted editor/session/media, account-local preference, original fallback, bounded timelines/dictionaries, fixed actions, camera inspection and undersized-window recovery implement the requested boundaries. Pending claim reconciliation remains distinct from deferred owned-task reads; explicit viewport continuation preserves stop/hard-pause intent.
- **Unrequested behavior/scope creep:** none established. No backend/schema/allocation changes; reviewer layout is excluded. Four-item proportional timelines and ordinal lookup follow the recorded execution decision.
- **Implemented-but-wrong behavior:** none established after independently checking interactions among history reveal, layout switching, media visibility, viewport suspension, in-flight responses and post-handoff continuation.
**Coverage limits, not proven defects:**
- Spec L09 says “Chinese input composition and native text undo continue to work” (`.scratch/annotation-workspace-layout/spec.md:130`). Native cut/undo and synthetic composition checks exist; native OS IME remains unverified, explicitly recorded at `docs/verification/annotation-workspace-layout/acceptance-results.md:25`.
- Spec L03 requests representative windows with “100%, 125% and 150% browser zoom” (`spec.md:124`). Twelve actual browser-window/zoom cases satisfy that matrix; physical monitor/OS scaling coverage remains limited (`acceptance-results.md:19`).
- L16 original/reviewer isolation has real panel/style evidence, but the old acceptance artifact exposes zero media members. This does not establish loaded-media or end-to-end acceptance success; the report explicitly limits that claim.
Independent corroboration: final runner SHA-256 matches the documented `a20779d7…fa9f56`; raw `task08-runner-review-green5.log` records three generation/save/handoff cycles, two successful claims and one empty claim. Earlier interruptions remain disclosed. Baseline frontend/Go/Python failures are not new feature defects; no full-suite-green, quality approval or deployment claim is warranted.

View File

@ -0,0 +1,11 @@
# Standards correction review
Reviewed only documentation correction `b83e810e` and its report.
**Documented violation closed.** `.scratch/annotation-workspace-layout/map.md:34–41` now contains a linked resolution summary for each of tickets 01–08 within Decisions-so-far, satisfying `docs/agents/issue-tracker.md:31–32`. Current implementation status is explicit at lines 5 and 33; earlier design observations are clearly historical at lines 13, 44, 61, 65 and 81–83. Coverage limitations remain explicit at line 42. No residual finding in this correction.
Read-only verification confirmed all 18 local Markdown links resolve and all 8 tickets linked from Decisions-so-far contain `Status: resolved` and `## Answer`. No browser or test suites rerun; no Git mutations.
**Three low-priority advisories remain deferred, not fixed:** duplicated browser reachability helpers; page-size policy duplicated between pagination and the workbench; repeated viewport threshold predicates. The execution record documents separate reasons and future maintenance costs. These remain judgment calls, not documented-standard violations or demonstrated current functional failures.
Final Standards disposition: 0 open documented-standard violations; 3 deferred low-priority smell advisories. This scoped re-review does not replace the independent Spec-axis assessment.

View File

@ -0,0 +1,15 @@
# Standards review
Reviewed `git diff ee2e355ba1838578b0611628bc764abbbeec6eef...a313b22a`, including production, browser-test, ticket and evidence changes. No browser or broad test suites rerun. Findings below distinguish documented requirements from maintainability judgments.
**Documented-standard violation**
- **Resolution map omitted.** The new resolved-ticket hunks, e.g. `.scratch/annotation-workspace-layout/issues/01-focused-view-and-legacy-switch.md:33` and `issues/08-full-workflow-acceptance-and-guide.md:31`, add Answers and link *to* the map, but add no resolution summaries or ticket links *in* its Decisions-so-far section. `docs/agents/issue-tracker.md:31–32` explicitly requires all three resolution steps. `.scratch/annotation-workspace-layout/map.md:29–46` remains unchanged and still ends “没有开始改动产品代码”. Add concise resolution summaries and links there, and distinguish historical design statements from current implementation status. This is a documentation/workflow issue; no production standards breach found.
**Smell baseline — judgment calls, low priority**
- **Possible Duplicated Code:** `tests/browser/annotation-workspace-annotation.mjs:26`, `annotation-workspace-navigation.mjs:36`, `annotation-workspace-dictionaries.mjs:25` and `annotation-workspace-camera-inspection.mjs:62` copy viewport/hit-test assertions, including `e.contains(document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2))`. Copies already differ in positive-width/height checks. Share the reachability measurement/assertion so acceptance improvements apply consistently; retain scenario-specific assertions locally.
- **Possible Shotgun Surgery:** `src/components/TimelinePageNavigation.tsx:5` defines `const pageSize = 4`, while `src/components/CaptureAnnotationWorkbench.tsx:777` independently uses `pageContaining(slices, slice.id, 4)`. Changing the list policy requires coordinated edits outside its owner. Expose a reveal-by-ID operation on the pagination hook, or share the policy constant.
- **Possible Duplicated Code:** `src/pages/AnnotationOperations.tsx:522,529,533` repeats the focused-layout minimum predicate, including `window.innerWidth < 1280 || window.innerHeight < 640`. Extract the dimension predicate/constants while retaining fresh window reads at dispatch boundaries; otherwise render, suspension and dispatch eligibility can drift during future threshold changes.
Totals: 1 documented-standard violation; 3 low-priority smell judgments. No tooling-enforced findings or unrelated baseline cleanup requested.

View File

@ -0,0 +1,30 @@
# 全仓测试结果
本报告记录专注工作页实现的完整测试,基线为 `ee2e355b`。全流程验收与最终双轴审查已完成。本报告保留完整测试的原始结果,并将后续局部复验分开列出,不以既有失败掩盖新增回归。
| 检查 | 当前结果 | 对照说明 |
| --- | --- | --- |
| Go 实际源码包 | 13 个有测试包通过、2 个无测试包;internal/api 失败 | 60 个失败的顶层用例与此前完整本地测试名称集合一致,没有新增;后端源码与本轮基线相同 |
| Python 全量 | 648 通过、25 失败、3 跳过 | 25 条失败及子用例失败均已存在,没有新增;此前原始全量中的两条 json_to_csv 缓存失败本次不再出现 |
| Rust 工作区测试 | 25 通过 | 使用本地缓存依赖,离线运行 |
| Rust 格式、Clippy、release 构建 | 通过 | 没有修改 Rust 代码 |
| Go 程序构建 | 通过 | 未部署构建产物 |
| 脚本语法检查 | 通过 | 使用现有虚拟环境 |
| Go 格式 | 1 个既有文件不合规 | internal/api/annotation_operations_test.go 未被本轮修改 |
| Kubernetes 原客户端 dry-run | 环境限制,未通过 | 没有真实 kubeconfig;命令仍尝试 localhost:8080 资源发现,被本地沙箱阻止 |
| Kubernetes 本地结构检查 | 22 份 YAML 文档通过 | 仅验证解析及 apiVersion、kind、metadata;不等同于公司集群验收 |
| 前端全量 | 578 项:568 通过、10 失败 | 9 条与基线一致;1 条字典弹层源码断言与新设计冲突;经真实新旧字典浏览器验证后退役,局部复验见下文 |
| 全仓 Prettier | 53 文件告警 | 52 文件未被本轮修改;本轮涉及的 Layout.tsx 已格式化;其余 52 文件保持原状 |
| 类型检查、Web 构建 | 第 7 项最终修复后通过 | 后续若有修改,再按影响范围复验;既有弃用及大包警告仍存在 |
Go 使用 `go test ./cmd/... ./internal/...`,覆盖全部实际源码包,避免 `./...` 扫描本仓忽略目录中的 Rust 临时构建目录。Python 使用 `.venv/bin/python3 -m pytest backend/operator-runner tests/backend -p no:cacheprovider`。检查均采用清洁环境,不继承公司集群或对象存储配置。
原始日志、退出码及失败集合对照保留在忽略目录 `local-data/verification/annotation-workspace-layout/final-checks/`。既有失败的此前基线复现见 [原快捷键版本的测试对照](../annotation-keyboard-workflow/final-suite-triage.md)。本次后台源码与 `ee2e355b` 无差异;失败集合比较包括 Python 的 `SUBFAILED`,并非仅比较汇总数量。
## 完整运行后的局部修正与复验
- 字典旧测试要求切片字典必须使用 portal,无法表达已确认的专注视图内嵌字典。真实浏览器已验证原布局弹层的指针、搜索、键盘选择、一次 Esc 与 Space,以及两阶段专注字典在五档尺寸的行为,随后只退役这条过时源码断言。该文件剩余 3 项通过;相关组合测试 54/54 通过。没有重跑全量,也不把局部结果改写成新的全量计数。
- 大窗口错误提示遮挡逐帧按钮的问题已通过真实浏览器复现并局部修复,五档尺寸回归通过。类型检查与 Web 构建在修正后通过。构建仍有原有的 module.register 弃用与大于 500kB 包警告。
- 本轮触及的 Layout.tsx 已格式化;全仓格式检查没有重复运行,52 个未改动文件的既有格式债务仍单独保留。
- 第 8 项交付脚本的临时分支清理错误由独立 reviewer 发现,运行时失败在写入前复现。修正后的同一份最终脚本在全新隔离项目完整退出 0,完成 3 次生成、保存与送检、2 次成功领取和 1 次空池请求。期间冻结所有仓库写入:实验证明本地 Vite 也会因 Markdown 修改整页重载,此前显式恢复不能作为产品故障归因。

View File

@ -0,0 +1,49 @@
# 逐票实施与审核证据
这些记录保留原始提交、检查、发现的问题及修复结果。local-data 路径指本机忽略的原始证据,不包含认证文件内容。
## 任务 01
- [task-1-fix1-review.md](task-1-fix1-review.md)
- [task-1-report.md](task-1-report.md)
- [task-1-review.md](task-1-review.md)
## 任务 02
- [task-2-report.md](task-2-report.md)
- [task-2-review.md](task-2-review.md)
## 任务 03
- [task-3-report.md](task-3-report.md)
- [task-3-review.md](task-3-review.md)
## 任务 04
- [task-4-fix1-review.md](task-4-fix1-review.md)
- [task-4-report.md](task-4-report.md)
- [task-4-review.md](task-4-review.md)
## 任务 05
- [task-5-fix1-review.md](task-5-fix1-review.md)
- [task-5-report.md](task-5-report.md)
- [task-5-review.md](task-5-review.md)
## 任务 06
- [task-6-fix1-review.md](task-6-fix1-review.md)
- [task-6-report.md](task-6-report.md)
- [task-6-review.md](task-6-review.md)
## 任务 07
- [task-7-fix1-review.md](task-7-fix1-review.md)
- [task-7-report.md](task-7-report.md)
- [task-7-review.md](task-7-review.md)
## 任务 08
- [task-8-fix1-review.md](task-8-fix1-review.md)
- [task-8-report.md](task-8-report.md)
- [task-8-review.md](task-8-review.md)

View File

@ -0,0 +1,31 @@
### Spec Compliance
- ✅ Spec compliant for the scoped review fix. The previously missing behavioral evidence now exercises active continuous work and stop-after-current in the recovered session across both focused → original and original → focused switches (`tests/browser/annotation-workspace-shell.mjs:70`, `tests/browser/annotation-workspace-shell.mjs:75`, `tests/browser/annotation-workspace-shell.mjs:86`).
- ✅ Each direction asserts the same task URL and zero task writes/claims, while the stopped state additionally proves that layout switching does not silently re-enable continuous work (`tests/browser/annotation-workspace-shell.mjs:78`, `tests/browser/annotation-workspace-shell.mjs:89`, `tests/browser/annotation-workspace-shell.mjs:94`). Consuming the task to test post-completion continuation is outside this scoped fix and is not required for closing the original finding.
- ✅ The controller independently verified the recovery tag target and complete-history bundle, closing the prior diff-external warning.
### Strengths
- The fix changes only the browser acceptance test and places the checks immediately after explicit session recovery, avoiding the navigation flaw in the earlier evidence.
- It verifies both possible intent states, both layout directions, visible user-facing status/control changes, task identity, and mutation absence rather than inferring preservation from component structure.
- The recorded focused browser run contains the new `recovered-session continuous intent and stop-after-current survive both layout directions without claims` PASS group and all seven existing PASS groups.
### Issues
#### Critical (Must Fix)
None.
#### Important (Should Fix)
None.
#### Minor (Nice to Have)
None.
### Assessment
**Task quality:** Approved
**Reasoning:** The scoped fix directly and behaviorally proves the continuous-work intent property that was missing from the original review. The prior Important finding is resolved without expanding production scope or consuming the isolated task.

View File

@ -0,0 +1,110 @@
# Task 01 — focused shell and lossless original-layout switch
Status: implementation complete; awaiting controller review. Ticket status remains controller-owned. No push/deployment or worktree created.
## Delivered behavior and boundaries
- Dedicated `/plugins/annotation-qa/workflows/:workflowId/work` defaults to focused presentation for an account without a browser preference. Platform sidebar/status header disappear and outer padding reduces. Existing task-pool `/annotate` presentation stays original.
- The existing work-page heading gains `切回原布局` / `进入专注视图`; it and the existing return link remain sticky while the current editor scrolls. Original mode restores the actual existing application chrome and work-page structure, not a second editor.
- `Layout` owns account-scoped browser preference; the editing coordinator consumes only the preference/toggle. The same coordinator, workbench and media DOM remain mounted. No task/session key, claim/save/release callback, asynchronous mutation fence or editor lifecycle changed.
- Layout storage keys include actual current user ID. Reads of missing/invalid values default focused; storage access exceptions keep live switching usable. Preference reads never activate a work session. Reload still requires explicit continuation and shows no editor beforehand.
- Current task/stage, selection, frame, independent per-slice drafts, unsaved text, persisted and in-memory undo/redo, and pending-save restrictions remain intact across toggles.
- Ticket 01 is only the focused shell/fallback. No claim of two-stage left/right layout, minimum-picture dimensions, no-scroll contract, pagination or undersized-window handling: these belong to subsequent tickets.
## Files
- `src/context/AnnotationWorkspaceLayoutContext.tsx`: minimal presentation-only preference/context, scoped by current account.
- `src/components/Layout.tsx`: dedicated-route chrome visibility and padding; stable provider around route children.
- `src/pages/AnnotationOperations.tsx`: consume presentation preference; render visible mode switch alongside original return link. No changes to editing/ownership logic.
- `src/styles/capture-workspace.css`: focused header hiding and sticky dedicated-page heading only.
- `tests/browser/annotation-workspace-shell.mjs`: real local browser/public API integration gate, configurable authenticated session files. No private React state or source-string acceptance.
- `docs/annotation-workspace-layout.md`: user behavior, delivery boundary, runtime fallback versus source/business recovery.
## TDD and browser evidence
Initial browser test ran against unmodified production source. Original `/annotate` entry successfully mounted the workbench and displayed platform chrome. Then `/work` explicit recovery screen still displayed platform chrome, failing the assertion `default focused layout hides platform chrome` (actual true, expected false). This is the feature RED; earlier setup failures (system proxy and a nested header's semantic role) were test/environment fixes, not feature RED.
RED command, before production changes:
```sh
ANNOTATION_STORAGE_STATE=local-data/verification/annotation-workspace-layout/auth.json node tests/browser/annotation-workspace-shell.mjs
```
Final GREEN command:
```sh
ANNOTATION_STORAGE_STATE=local-data/verification/annotation-workspace-layout/auth.json \
ANNOTATION_SECOND_STORAGE_STATE=local-data/verification/annotation-workspace-layout/secondary-auth.json \
ANNOTATION_EVIDENCE_DIR=local-data/verification/annotation-workspace-layout \
node tests/browser/annotation-workspace-shell.mjs
```
The runner uses installed Microsoft Edge headless with `--no-proxy-server`, needed for this machine's localhost browser connectivity. Browser operations require the authorized unsandboxed local networking surface. All service URLs are hardcoded localhost:5173, backed by 3001/27018; there is no remote target option.
Checks exercised:
1. Original task-pool entry keeps platform chrome, the actual workbench and no dedicated-page toggle.
2. Existing Start Work opens the same browser tab, resumes an already-owned task without claim, and exposes the existing stop-after-current control.
3. Default focused shell hides chrome; original restores it. Original choice survives refresh; editor remains absent until explicit Continue, with no write/claim from preference or refresh.
4. Both real local video elements reach playable readiness. One-frame keyboard step is retained exactly across six toggles; original video and workbench DOM nodes remain connected.
5. Existing first-slice description is edited without saving; second-slice draft created/parked through normal controls. Ctrl-arrow navigation and toggles preserve both texts. Dirty return opens the real leave modal and Continue Editing preserves the draft. Switch remains visibly in viewport while editing lower content.
6. Ctrl+Enter performs a real server save; the response is held only after `route.fetch()` reaches the real API successfully. Switch to original while response is held: save button stays disabled, text remains, and exactly one POST exists. Releasing response completes the same session normally.
7. Public `GET /api/human-items/:id` confirms version increment exactly one and the saved description. Ctrl+Z after another toggle restores prior persisted description via real API; Ctrl+Shift+Z in original mode reapplies it. Total task writes exactly three: save, undo, redo. No claim/release or duplicate save.
8. Original slicing UI: six frame steps and C split; toggle; Ctrl+Z removes split; toggle back; Ctrl+Shift+Z restores split. No task writes from local slice history/toggles.
9. Two actual local annotator sessions are exchanged by authenticated cookies in the SAME browser context, retaining origin localStorage. First account's original preference does not affect new peer's focused default; peer's original choice remains original after first account changes to focused. No task mutation during account tests.
Raw ignored evidence: `local-data/verification/annotation-workspace-layout/task01-browser-green.log`, `task01-focused.png`, `task01-original.png`. Both screenshots visually inspected: real paired video, original sidebar restored, sticky switch/return accessible. Screens show current original editor; they do not establish later-layout acceptance.
## Local fixture/auth scope
Controller prepared isolated project `project-workspace-layout-acceptance`. Main browser tasks: `annotation-task-workspace-layout-acceptance-annotate-primary` and `annotation-task-workspace-layout-acceptance-slice-primary`. Public save/undo/redo deliberately leave the final test description saved in the isolated annotation task; slice changes and second-slice drafts are unsaved and discarded with browser close.
Existing platform admin is super-admin and correctly receives organization console instead of work-page editing. Controller explicitly authorized a new localhost-only peer for account isolation: `user-workspace-layout-acceptance-peer`, fixture member `project-member-workspace-layout-acceptance-peer`; copied only primary local user/password hash and this new project's annotator membership to unique IDs, without modifying existing user/member records. Guarded helper verifies Mongo is published exactly at 127.0.0.1:27018. Peer never claims/edits tasks. Helper and auth state are ignored local data, session files chmod 0600. No secrets in tracked files/report.
## Focused verification
```sh
npm run lint:web
node --test tests/frontend/annotation-shortcuts.test.mjs tests/frontend/annotation-history.test.mjs tests/frontend/annotation-authoritative-mutation.test.mjs tests/frontend/annotation-playhead-draft.test.mjs tests/frontend/annotation-submission-state.test.mjs
npm run build:web
npx prettier --check src/context/AnnotationWorkspaceLayoutContext.tsx src/pages/AnnotationOperations.tsx tests/browser/annotation-workspace-shell.mjs
git diff --check
```
Typecheck, 44/44 focused frontend tests, Vite web build, scoped formatting and diff check pass. Existing >500 kB build chunk notice remains. No backend behavior changed; broad/full suites are controller-owned. Layout's pre-existing formatting was preserved to avoid whole-file churn; only new blocks were formatted reasonably.
## Source recovery verification
`git rev-parse 'codex/annotation-keyboard-baseline-20260918^{}'` returns `54a35afad95d77b1f23c955f9c4671cae83a664d`. `git bundle verify local-data/backups/annotation-keyboard-baseline-20260918.bundle` reports okay, complete history, SHA-1 bundle. The annotated tag object is `a5ac806e5677975d125f2069cb289e2218af6b93`. These recover source only, never database/media/unsaved browser state. No restore operation was performed.
## Self-review
Checked route isolation, first-render account separation, localStorage exception fallback, stable editor reconciliation, no layout-mode dependency in request/session state, no new backend API/schema, unchanged stage history boundaries, unchanged return blocker and account/session guards. Delayed-save experiment proves the original result reconciles after switching. Original schema, media paths, task versions and ownership contracts unchanged. No broader refactor or later ticket implemented.
## Commit
Commit `a5753731` — `✨ Add focused annotation shell with lossless layout fallback`. Final browser gate exits 0 with all seven PASS groups. Only the six task implementation/documentation/test paths listed above are committed; controller's ticket claim edit remains unstaged. No push or deployment.
## Review fix 1 — continuous-work intent evidence
The Important review finding was confirmed: the prior Start Work stop click was followed by a fresh navigation before the layout-toggle assertions, so it did not establish intent retention in the active recovered session. Added a focused browser check immediately after explicit Continue, before draft editing:
- Click Start Continuous Work on the current owned task, switch focused → original → focused, and after EACH switch assert the visible continuous-work status, the Stop After Current button, identical task URL, and zero task writes/claims.
- Click Stop After Current, switch focused → original → focused, and after EACH switch assert the explicit stop-selected/no-next-claim status, visible Resume Continuous Work button, absent Stop After Current button, identical task URL, and zero task writes/claims.
- Continue through the existing real-media/draft/delayed-save/API/undo/redo/account regression gate.
Only `tests/browser/annotation-workspace-shell.mjs` changed. No production code change, no additional task completion/consumption, and no new fixture/account. This test establishes live intent retention and no claims caused by switching. It deliberately does not claim verification of post-completion continuation; full continuous-work completion remains a later acceptance task.
Command:
```sh
ANNOTATION_STORAGE_STATE=local-data/verification/annotation-workspace-layout/auth.json \
ANNOTATION_SECOND_STORAGE_STATE=local-data/verification/annotation-workspace-layout/secondary-auth.json \
ANNOTATION_EVIDENCE_DIR=local-data/verification/annotation-workspace-layout \
node tests/browser/annotation-workspace-shell.mjs \
> local-data/verification/annotation-workspace-layout/task01-browser-review-fix.log 2>&1
```
Syntax (`node --check`) and `git diff --check` pass; the test file was formatted with Prettier. No typecheck/build rerun needed for a browser-test-only evidence change. Review-fix browser result and commit recorded below after completion.
Review-fix GREEN: exit 0, all eight PASS groups including `recovered-session continuous intent and stop-after-current survive both layout directions without claims`. Commit `6acc5803` — `🧪 Verify continuous-work intent across layout switches`. Controller ticket edit remains unstaged; no push/deployment.

View File

@ -0,0 +1,31 @@
### Spec Compliance
- ❌ Issues found: the implementation and browser evidence cover the focused shell, real original-layout fallback, account/browser preference, explicit refresh recovery, editor/media identity, frame and per-slice draft retention, delayed save reconciliation, API readback, and undo/redo. However, the required continuous-work intent preservation is not behaviorally verified: the test clicks “完成当前任务后停止” at `tests/browser/annotation-workspace-shell.mjs:46`, immediately performs a fresh navigation at `tests/browser/annotation-workspace-shell.mjs:49`, and never asserts that choice after the repeated layout toggles at `tests/browser/annotation-workspace-shell.mjs:96`. This leaves one of the task’s explicit session/continuation guards supported only by structural inference.
- ⚠️ Cannot verify from diff: the local tag actually resolving to `54a35afad95d77b1f23c955f9c4671cae83a664d` and the bundle containing complete history. The documentation records both claims at `docs/annotation-workspace-layout.md:15`, and the report gives the verification commands/results, but those repository-local recovery artifacts are outside the review diff. The controller should retain or inspect the `git rev-parse` and `git bundle verify` evidence.
### Strengths
- Preference state is narrowly scoped to presentation and keyed by actual user ID, including same-render account changes and storage-failure fallback (`src/context/AnnotationWorkspaceLayoutContext.tsx:11`, `src/context/AnnotationWorkspaceLayoutContext.tsx:23`, `src/context/AnnotationWorkspaceLayoutContext.tsx:32`).
- The shell hides/restores the real sidebar and header while keeping one stable provider around the existing route children, so toggling does not create a second editor tree (`src/components/Layout.tsx:52`, `src/components/Layout.tsx:185`, `src/components/Layout.tsx:190`, `src/components/Layout.tsx:306`).
- The browser test checks observable behavior rather than source strings: same-account refresh recovery (`tests/browser/annotation-workspace-shell.mjs:56`), connected editor/media nodes and zero toggle writes (`tests/browser/annotation-workspace-shell.mjs:101`, `tests/browser/annotation-workspace-shell.mjs:111`), a held real API response with exactly one write and version readback (`tests/browser/annotation-workspace-shell.mjs:157`, `tests/browser/annotation-workspace-shell.mjs:171`, `tests/browser/annotation-workspace-shell.mjs:176`), persisted undo/redo (`tests/browser/annotation-workspace-shell.mjs:191`, `tests/browser/annotation-workspace-shell.mjs:205`), and two-account preference isolation (`tests/browser/annotation-workspace-shell.mjs:248`, `tests/browser/annotation-workspace-shell.mjs:260`). The named browser log contains all seven PASS groups, and the screenshots visibly show both the focused shell and restored original chrome.
- The documentation states the ticket boundary and correctly separates runtime layout fallback from source and business-data recovery (`docs/annotation-workspace-layout.md:7`, `docs/annotation-workspace-layout.md:13`, `docs/annotation-workspace-layout.md:17`).
### Issues
#### Critical (Must Fix)
None.
#### Important (Should Fix)
- `tests/browser/annotation-workspace-shell.mjs:46` — The browser gate does not prove that `stop-after-current`/continuous-work intent survives a layout switch. The click is followed by a page navigation before the toggle sequence, and no later assertion inspects the continuation setting or proves that completion will not trigger another claim. This matters because preserving continuous-work intent and the associated claim guard is an explicit Task 01 requirement, and the review constraints require behavioral evidence rather than reasoning from unchanged source. Exercise the choice in the recovered work session, toggle both ways, and assert its visible state remains selected; ideally complete the isolated current task and verify that no next claim is issued.
#### Minor (Nice to Have)
None.
### Assessment
**Task quality:** Needs fixes
**Reasoning:** The implementation is small, clean, and strongly evidenced for nearly every required lifecycle property. Approval is blocked only by the missing behavioral proof for continuous-work intent, a claim/session guard explicitly included in this task.

Some files were not shown because too many files have changed in this diff Show More