dsh-worktable: Instructions file for Codex

dsh-worktable 项目规则

工作台容器插件：侧边栏里收纳 agent 级项目的「应用抽屉」。纯增量，不替换官方插件。

协作方式（用户定案，最高优先级）

与全局 ~/.dsh/AGENTS.md 同步；外部 Agent（如 Codex）不加载全局文件，故此处保留全文。

• 设计先给最小版：任何 UI/文案/方案先交「最少元素」版本给用户拍板，确认后再增量； 默认克制——没有存在理由的元素不放；不一次搭「完整版」再返工。
• 长任务拆 checkpoint：每个可验收阶段完成后停下汇报，等用户确认再进下一段； 不一口气跑完长任务。
• 对外动作永远先审：发布、评论、给观众的内容、任何公开操作，一律先给用户过目， 用户不点头不执行。
• 改完必读回：每次编辑后读回改动处的完整行/段落，确认无残留、无断尾 （教训：改一半的 URL 留下旧尾巴，被复审抓为发布阻断）。
• 验收用最终产物，不用中间信号：任何交付物（tgz、命令、文档、UI）的验收动作必须是 「解包 / 复制 / 实跑用户路径」；「构建成功」「bundle 里有字符串」「退出码 0」不算验收。
• 发布前自跑最终产物清单：干净目录安装、最终包逐文件核对、双资产哈希、关键行逐字 grep —— 先自查再报告，不等外部复审来抓。
• 发布包验收=结构检查 + 真实安装，两道都保留：npm pack 标准格式（package/ 前缀 + files 白名单精确 7 文件，不含 src/、不含 .map）与「独立目录 npm install + import() 断言」 缺一不可。教训：v0.3.0 手工 tar 出无前缀平铺包且误卷源码树，「解包核对（文件都在）」发现不了， 只有 npm install 复现失败；「文件都在」 ≠ 「消费方（npm/dsh plugin add）能装」。
• 声明可证伪，不许写满：验收结论只写已验证范围。「通知全覆盖」「等价端到端」这类表述会被 反向检查打脸——只写「版本比较逻辑上重新激活」「验证了安装与服务端模块导入」。
• 同 tag 资产不可覆盖（用户已拍板）：坏包处理 = 发新版本号 + 旧 Release 正文标注问题， 默认不替换旧资产；仅经用户明确批准的紧急补救例外，且须：不改名（保持原 URL 名）、 用已验证包、不删不盖现有资产、上传后从完整 URL 下载核对、旧 Release 注明补救经过。

边界

• 插件包根目录 = 01_content/；本仓库其余目录是项目文档与本地工具。
• 不替换、不禁用任何官方插件（ui-sidebar / ui-workspace / ui-layout）。
• 所有状态只存 localStorage（键 dsh.worktable.view.v1），不读写工作区文件。
• dsh-travelatlas 是入驻项目而非本仓库的一部分；协议见 02_process/PRD.md §5.3/5.4。
• 平台边界：Windows 是当前完整验证平台；macOS 为实验性支持（核心文件路径代码已做跨平台适配， 尚未真机端到端验证）。路径拼接必须走 pathutil.ts helper 或 Node path API，不手写分隔符。

构建与验证

cd 01_content
npm install
npm run build     # lib/index.js + lib/client.js
node --check lib/index.js

• 客户端 bundle 必须保持 window.__ModuleLoader__.load 握手与 external react/@deepseek-ai/*。
• 变更视图状态结构时同步更新 PRD 的持久化说明。
• 构建必须 cd 01_content 后执行：误在仓库根跑会把 lib 写到仓库根 lib/，宿主仍加载 01_content/lib 旧 bundle，出现「改完不生效」假象（已有教训，见工作日志）。
• 发布打包唯一入口 = npm run pack（01_content/release-prep.mjs）：身份断言（package/manifest/cordis.patch.yml 严格结构）→ 版本一致性 → 构建（cwd 固定 01_content）→ node --check → npm pack → 结构清单断言（package/ 前缀 + 精确 7 文件， 无 src/、无 .map）→ 独立临时目录 npm install + import() 断言（apply 函数/inject 含 webServer+sessions/name/ HEALTH_PATH/包内双 bundle 版本）→ 客户端工厂求值门禁（ModuleLoader 恰好注册一次 + ID 校验 + 精确外部依赖 白名单 react/react/jsx-runtime + apply/inject 断言）→ 分栏锚点 DOM 回归（8 场景，评估安装产物 lib/client.js； 测试接受包路径参数）→ 服务端数据目录回归（3 组场景，评估安装产物 lib/index.js）→ dist/v版本号/ 双资产（终态恰好 2 文件 + 双 SHA 同源）。 脚本零 git/gh 动作，发布上传由 gh 手动完成。 发布禁止裸 npm pack 或手工 tar 生成发布包；脚本从仓库任意目录调用均安全（以自身位置解析）。
• 配套检查入口：npm run test:gate = 工厂门禁 10 个失败/正向用例； node 04_test/anchor-dom.test.mjs [lib/client.js 路径] = 分栏锚点 8 场景（缺省用工作目录构建产物）； node 04_test/server-home.test.mjs [lib/index.js 路径] = 数据目录解析 3 组场景（子进程隔离夹具； 突变体验证法：把 loadPkg 兜底的 baseDshHome() 故意改回 resolveDshHomeSafe() 恢复循环，测试必须红）。 npm run verify:remote -- --expect-sha <release-prep 输出的 SHA> [tag] = 发布后只读核对 （远端固定名+版本化双资产文件名/结构/版本/双 SHA 同源且等于本地验收 SHA/安装/导入； 远端只读，本地仅临时目录）。上传后必须跑 verify:remote 并用 --expect-sha 比对， 防「双资产同错」；tag 模式断言 tag==='v'+包内版本。