@dsh-workbench/core 0.3.5 → 0.3.6

package/skills/workbench-module-diy/TOOLS.md

@@ -87,9 +87,27 @@
 
 ## 9 长任务：跑一会儿的事
 
-跑几十秒的事（构建、发布、批量删）做成**长任务**。宿主半侧用 `mount` deps 里的 `longTasks` 建注册表并挂回返回值：`longTasks.create({ key, run, step, outcome, view })` —— `run({ payload, onStep })` 里用 `onStep({ kind: 'start', text })` 报步骤、`return` 结果；`step`/`outcome`/`view` 各映射一段给界面；返回里带上 `longTasks: runs`。
+跑几十秒的事（构建、发布、批量删）做成**长任务**。宿主半侧用 `mount` deps 里的 `longTasks` 建注册表并挂回返回值：`longTasks.create({ key, run, step, outcome, view, stopped })` —— `run({ payload, onStep, signal })` 里用 `onStep({ kind: 'start', text })` 报步骤、`return` 结果；`step`/`outcome`/`view` 各映射一段给界面；返回里带上 `longTasks: runs`。
 
-浏览器半侧用 kit 现成的 `useLongTask`（→ `feed.runs`），画用 `LongTaskRow` 或 `longTaskDot`（每条的字段与四种状态见 `.d.ts`）；**契约里没有"停止"**，用户要中途停得自己在 `run` 里看信号。判据（`check --only contracts`）：注册表五个方法要全、`create` 的 `key`/`run`/`view` 不能缺、产物里必须有 `useLongTask`/`LongTaskRow`/`longTaskDot` 之一。
+**来源要记**（起这一趟的是谁）：在起它的那把工具里用 `execute(args, exec)` 给的现场，`runs.start({ …, session: sessionIdOf(exec) ?? undefined })`（`sessionIdOf` 从 `@dsh-workbench/shared/host` 取）。**不记 = 用户在界面上按的**（或这一版之前起的）—— 保守的那一侧：停它要走审批。
+
+浏览器半侧用 kit 现成的 `useLongTask`（→ `feed.runs` / `feed.stop(id)` / `feed.stopping` / `feed.stopFailed`），画用 `LongTaskRow` 或 `longTaskDot`（每条的字段与**五种**状态 —— `running` 进行中 / `needs-login` 要登录 / `stopped` 停下的（灰点）/ `ok` 完成 / `failed` 出错 —— 见 `.d.ts`）。`stopped` 是后加的第五态：自己穷举过四态的地方（`switch` 没 `default`）会 tsc 报错，那是提醒你把它补上。
+
+**要给用户那颗「停止」钮，两半都得做**：
+
+- **认信号**：`run` 收到的 `signal` 被 abort = **有人按了停止**（用户在卡片上按的，或 agent 用 `workbench_long_tasks_stop` 停的）。在你能收手的地方（每轮循环、每条子命令前后）看一眼 `signal.aborted` 就收工。**不认就别画那颗钮** —— 画了就是骗人：外壳只会把这一趟标成 `stopped`，你的活儿还在跑（内部是 opencli 子进程那类编排，今天最多做到"我们不再等它"，平台侧那趟照旧跑完）。
+- **画钮**：给那一行的 `LongTaskRow` 传 `stop`（`onStop: () => feed.stop(run.id)`、`busy: feed.stopping === run.id`、`failed: feed.stopFailed`、`label` 用 dsh 那句 `停止任务 {label}`（`{label}` = 这一趟的名字）、`askLabel: '确认停止'`）。**词与取值照 dsh 任务列表那行来**：没上膛的 aria `停止任务 {label}` → 上膛后可见字 `确认停止`、aria `再次点击确认停止`，3 秒自己落膛。**失败那半是我们自己的口径**：不往钮里写"停止失败"四个字（那是 dsh 词表里的一项），而是把这次请求失败的**原话**画在那一行下面 —— `failed: feed.stopFailed` 给什么就画什么（例如 `网络不通，停止请求没发出去`），不给就不画。两按确认（第一次只上膛、再按才真发、请求在飞时按不动）归组件，调用点只管上面这几样；**没传 `stop` 的行一个像素都不变**。
+- **多行同时在跑要留意**：`feed.stopping` 与 `feed.stopFailed` 都只有**一格**（"最后一次"），不分行 —— 停 A 再停 B，`stopping` 变成 B，A 那行**提前解禁**（再按一下只是再发一发，外壳回 `{ ok: true, stopped: false }`：无害但白费）；某一次停止失败，那句原文会画在**每一个**你传了 `failed: feed.stopFailed` 的行下面（`LongTaskRow` 只认 `failed` 这个字符串，不认 id）。**要分行报成败、要精确禁用就自己按 id 记**（比如 `useState` 记"在飞的那趟 id"与"那趟失败的话"）；单行卡片用现成这一格就够，嫌它糊就别把 `stopFailed` 传给所有行。
+
+**外壳自带两把通用工具，你不用自己写**：`workbench_long_tasks_list`（读）看**当前工作区**跑着什么、**谁起的**（`我起的` / `用户按的` / `别的会话起的`），`workbench_long_tasks_stop`（写）停一趟。审批口径：**自己起的免审批**（这一趟记的 `session` 就是调用方那个会话）；**别人的 / 用户按的 / 没记来源的要审批**（那一屏外壳自己认领，画"要停哪一趟"+ 一句"停了只是让外壳发出中断信号"）；**不在你当前工作区的直接拒绝**（工作区是边界，仓内 ADR-0018）。
+
+**被停时会通知发起那次运行的会话**：用户（或别的会话）停下你起的这一趟，外壳给**起它的那个会话**发一条 notice —— 那会话正在跑就 inject 一条，闲着就跳过；**跑完 / 失败不发**（那是你自己那把工具的活，它起的那趟它自己报）。你不用在模块里自己发。
+
+**为什么不走 `ctx.jobs`**：dsh 的 job 归**一次 agent 会话**（teardown 主动取消、读口按会话围栏），我们的长跑归**工作区的一个目标**（`dispose` 刻意不取消）—— 归属轴不同；换过去要改归属口径，而它的 `JobStatus` 里没有 `needs-login`、`JobView` 里也没有工作区字段。理由、代价与"只借形状"那四件见仓内 ADR-0069（这里不链仓内路径）。
+
+判据（`check --only contracts`）：注册表**六个**方法要全（含 `stop`）、`create` 的 `key`/`run`/`view` 不能缺、产物里必须有 `useLongTask`/`LongTaskRow`/`longTaskDot` 之一。**它只查形状与"画得出来"** —— "你真认了 signal 吗、真收得住手吗"不在它的射程里（那只有你自己知道，见上面第一条）。
+
+**要用 `stop` 这个新 prop / 新返回字段，就得装带这次改动的那份外壳**：把自己 `peerDependencies['@dsh-workbench/core']` 的下限抬到那一版 —— `check --only kit` 盯着这条（产物实际取的 kit 成员 ⊆ 你 peer 下限那份外壳的 kit）。**同理**：`start` 收 `session`、外壳那两把 `workbench_long_tasks_*` 工具，也都是这一版才有的。
 
 ## 10 用户自己按的那个入口 / 范例