截图任务板 · dsh-screenshot-board

把截图批注整理成可执行、可澄清、可验收的修改任务。版本 0.2.0。

本轮沿用原插件，交付源码与 npm tarball。0.2.0 已安装到 DSH 0.2.x 桌面版的 desktop profile 并在实机试用通过：插件入口、工作台打开、收起与恢复、交接流程均已确认。0.1.0 期间亦在同一 profile 上验证过 Host API 与任务板读写。验证范围限于 Windows 与单一 profile，未做跨版本、跨平台回归；独立预览、HTTP 测试、Client 模拟注册与真实 Agent 交接分别记录于 docs/VALIDATION.md。

本轮改进

• 可复用的项目背景：用途、启动方式、访问地址、页面入口、操作条件、文件线索、允许修改范围及未知信息。全部可选，支持逐步补充；插件只记录用户输入，不运行命令或自动读取项目。
• 交接范围预览：逐任务选择本次执行、待澄清、仅供参考或不包含。资料齐全且用户确认的待处理、处理中、需修改任务默认执行；待验收、已通过默认参考。草稿及信息不足的任务先澄清。
• 交互故障证据：按需填写复现步骤、实际结果、预期结果、环境条件。外观任务保持轻便。交互任务缺少前三项时不能加入执行清单。
• 轻量需求引导：保留原始批注，提供位置、现状、期望和验收条件示例。不擅自补尺寸、颜色或行为。修改期望、验收或复现后需要重新确认；待澄清问题未解决时不能执行。
• 收起与恢复：DSH 中「收起到聊天」隐藏工作台，保留实例、所选任务、截图、视图、缩放、筛选、对话框草稿及未提交讨论。原有保存继续工作，保存失败仍可收起恢复。关闭工作台会结束实例，二者分开。

原有多任务板、框选/重画/排序、状态与讨论历史、修改后截图对比、明暗主题、图片上传/拖入/粘贴、完整备份及保存冲突保护继续保留。

推荐流程

1. 新建或打开任务板，在「项目背景」填写已知信息。项目路径可选，通常填真实、完整的项目根目录；仅写进交接材料，不检查目录。填错不影响批注，但可能使 Agent 找错项目。
2. 添加截图并框选，保留原始批注，补充期望修改及可判断的验收条件。交互故障再填操作过程与结果。
3. 内容仍有歧义时保留草稿或填写待澄清问题；清楚后勾选「需求已由我确认」。此确认与最终「验收通过」是不同阶段。
4. 在「交接与导出」逐项检查范围和说明。待验收默认交给用户验证；如需 Agent 再改，可在资料齐全时显式选择执行。
5. 将 ZIP 交给新的 Agent，并明确实际项目权限。执行者先看 tasks.md，不把背景快照里的历史当成追加任务。
6. Agent 按编号交回修改文件、验证结果、修改后截图和遗留问题，用户操作验证并逐项人工验收。交互问题不能仅凭截图证明修复。

旧板读取时补充可选字段，不删任务、批注或历史。旧任务的需求确认状态保守设为待确认；旧的待验收/已通过状态仍保留，默认只作参考。

导出与备份

• tasks.md：项目背景、执行清单、待澄清与参考章节、回交要求。
• handoff.json：板 ID、修订号、更新时间、UTC 导出时间，以及执行/澄清/参考/未选任务 ID。
• board.json：完整背景快照与图片索引；执行范围以 handoff.json 为准，未选任务不执行。
• images/：原图、编号图和已有修改后截图。「截图号.批注号」对应图片编号，不随范围选择重新编号。

可单独下载或复制说明。实际下载时生成时间；ZIP 由 Host 校验保存修订号及任务选择，旧窗口不能静默导出新版本。

「备份 JSON」始终保留完整板与图片，恢复为独立副本；交接选择不会裁掉备份内容。保存冲突时也可备份尚未写入的编辑。ZIP 不用于恢复。

独立预览与开发

在源码目录运行 node scripts/preview.mjs，打开 本地预览。仅监听本机，数据在 .preview-data/，不加载 DSH。示例板明确标为虚构，不是 Agent 修改结果。

node --test tests/*.test.mjs
node scripts/build.mjs --esbuild-root D:/NodeGlobal/node_modules/vercel
node scripts/check-package.mjs
npm pack --pack-destination dist

构建需要 esbuild 0.27.0，也可准备标准开发依赖后运行 npm run build。浏览器脚本通过 --playwright-root、--browser、--url 使用已有 Playwright/Chromium，不会自动下载安装。完整命令与证据见 docs/VALIDATION.md。

DSH 包结构与入口

dsh.bundle.patch 指向 cordis.patch.yml，挂载项 id/name 均为 dsh-screenshot-board。Host 为 lib/index.js；exports["./client"] 暴露预打包的单个自包含 ESM Client，并声明所需客户端依赖。运行包无需现场构建。

用户自行安装后可从设置页「截图任务板」或悬浮入口打开。DSH API 的本地源码依据及未验证事项见 docs/API-EVIDENCE.md。本轮只产出包，不运行安装命令。

数据与限制

• DSH 数据目录沿用 resolveDshHome()/dsh-screenshot-board/，不读写关联项目。预览使用独立目录。
• schemaVersion 和备份 version 仍为 1，采用可选字段扩展；支持旧板和备份。新字段需本版本保存，不支持降级客户端编辑新字段。
• 单图最多 8 MiB、16000px 单边、6400 万像素；每板最多 12 张原图、300 个任务，原图与修改后图总量最多 48 MiB。
• JPEG 在浏览器规范化方向后保存；PNG 保留上传字节。编号图也受 8 MiB 限制。
• 图片只保存在本地 Host，没有第三方上传或 AI 调用。Host 沿用 DSH 访问边界，写操作另校验插件会话令牌。
• 未保存内容仅留当前页面；收起保留页面，重载、关闭或应用退出不等同收起。保存失败先备份，再显式重新载入，不要在没有备份时退出。
• 删除板会删除板 JSON；图片可能多板共享，暂不自动清理。不可读板记录 Host 告警并从列表跳过。
• 本插件不调度 Agent，不自动执行命令、修改关联项目或 Git，也不自动判断验收通过。