@khorsheed/dsh-room 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # 变更记录
 
+## 0.2.3（2026-10-26）
+
+**成员怎么协作**
+
+- **成员之间自由通信**：任何成员都能直接给另一个成员发消息（`room_message`，CLI 成员走桥接的 `member_message`）。默认是「派活」，对方做完的最终回复自动汇报回派活人；也可以只是「知会」。为防止来回打转有跳数上限（默认 10），成员页新增「协作设置」：成员消息可设为自由发或要你确认、可暂停，被拦下的消息写明原因，确认或恢复后按原样放行。
+- **汇报时机自动判断**：成员的结果是马上交给协调者还是先攒着，先按规则定（设置、失败、最后一份结果等），拿不准时问可选的快速决策服务（TypeSafe）；没装它就一到就汇报。攒着的汇报在协调者下一轮一次带上，不再一份汇报占一轮；协调者正在跑时到达的汇报并进当前这一轮。
+- **任务**：你发出的每一条引出工作的消息算一个任务，后续派出的活都记在它名下；新消息归到哪个任务，看输入框的标签，拿不准时由判断模型决定。右栏的「协作」页有「任务 / 团队」两个视图：任务列表可筛选，每个任务能看到说了什么、追问怎么归档、哪里在等你处理、正式目标、子任务树和泳道时间线，还能整条停止（就地确认）；「追问」「＋ 新任务」给主输入框打标签。它取代了原来的任务板、计划页和输入框上方的胶囊。
+- **团队视图**：把房间画成一棵树（每个成员挂在最常给它派活的人下面），节点上标派活数、汇报数和知会数，并汇总每个成员的轮次、用时和 token；成员多时改成主干加分支的连线，放不下的一行收成「+N」。成员页的「团队」按钮和每张卡片的「在团队中定位」直达。
+- **自动判断看得见**：任务归属和汇报时机统一成一张判断场景表；每次判断（按规则还是问了模型、问了什么、答了什么、用了多少 token）都记下来，时间轴上一行淡色结论，「查看判断」在 Context Lens 的「房间」页签打开那次调用。「协作设置」新增「自动判断」分组：自动归档任务、自动决定汇报时机，以及「立即汇报阈值」和最长等待。
+- **精简的成员提示与公开角色**：成员第一轮收到一份房间简报（名字、公开角色、你给它的私下说明、目标、其它成员的公开角色），之后只发变化；成员之间看不到彼此的私下说明。邀请与编辑可填公开角色（≤30 字），卡片上显示成标签。工具用法写进工具描述，简报不再每次重复。
+- **移除成员说到做到**：移除时停止它正在跑的一轮、撤回排队的消息、收尾或交接它手上的任务、告诉在等它的人，然后才离开；卡片上就地确认并列出实际后果，五秒内可撤销。
+
+**跨房间求助**
+
+- **向别的会话求助**：成员可以用 `room_help` 点名另一个会话（标题、id 或 @ 引用）请它帮忙；对方会话里出现一张标明来自哪个房间的求助卡片，回复作为汇报送回提问的成员。CLI 成员也能用。
+- **@ 菜单能选别的会话**：先列本房间成员，再列其它会话（不输入时是最近五个，输入时按匹配度和新近排序）；展开一个房间可以挑它的某个成员，搜索时也照样列出。
+- **向另一个房间或它的成员求助**：点名房间时交给它指定的成员，否则交给它的协调者；对方暂停时照常排队。
+- **求助超时变琥珀色**：求助过了提醒时间还在排队或进行中，那一行变琥珀色并显示已等多少分钟（「协作设置 → 求助提醒」，10–120 分钟，默认 30），不会自动取消。
+- **外援上团队树**：被求助的会话以虚线「外援」节点挂在提问人下面（都结束后变灰），不计入房间合计；常被求助的会话可一键「加入房间成员」。
+- 你的消息里 @ 了外部会话时，派给协调者的提示会点明这些会话并提醒用 `room_help`，入房较早、没见过这个工具的成员也知道去问。
+
+**CLI 成员**
+
+- **CLI 成员能用模式工具**：邀请 Codex / Claude Code / Kimi 成员时可以选模式，成员就能用这个模式的插件工具；简报会告诉它这些工具在 `dsh-member` MCP 服务里。需要确认的工具调用在房间里出「⚠ 成员 要你确认：调用 …」，点「允许一次 / 拒绝」，并计入「需要处理」。邀请对话框里原来的预设/模式标签合成一个「模式」下拉框，名字与宿主自己的模式选择器一致。
+- **原生 dsh 成员带模式**：邀请 `native` 成员时可选一个宿主 agent 预设，成员就是这个宿主里按该预设组合的子 agent。
+- **CLI 成员向你提问**：成员可以发选项卡问你，你点选或打字回答，答案回到成员手里；30 分钟没答或重启后卡片失效。简报引导 CLI 成员用它，而不是把问题写在回复里。外部协调者的 `room_invite` 也能带模式。
+- **子会话以成员名字标注**：宿主的子代理列表里显示「Codex：剪刀手二号」，不再一律是「Codex」。
+- **邀请不绕路**：还不是房间的会话里 `room_read` 直接给出可邀请的 harness、模式和当前模式；`room_invite` 认 harness 名或显示名（claude-code、Claude Code、kimi）。会话头部的「邀请 agent」入口也能选模式，并保留角色、类型和模式。
+
+**发言与输入**
+
+- **发言卡片带用量和明细入口**：每条发言显示这一轮计费的 token，统计行新增成员一栏（各成员的模型、轮次、token 和用时）。卡片下方的操作行与宿主消息一致：复制、打开成员会话、请求明细（在 Context Lens 里定位到这一轮）、用量（悬停看拆分）和时间；最新一条常显，旧的悬停出现。
+- **折叠更顺手**：最新一条回复房间的发言默认展开、有更新的回复时再收起，汇报和旧回复默认折叠；你自己的展开/收起按发言记在浏览器里；折叠控件换成与消息工具一致的右下角圆形箭头，点渐隐处也能展开。
+- **成员实时输出像宿主自己的流式**：思考显示成宿主的思考行，回答直接显示正文；正在跑的成员行与发言卡片同形，回复落地不跳。
+- **输入条与官方一致**：字号跟随设置（默认 14px），边距、停靠、圆角和阴影同官方输入框；协调者一行显示「● 名字 · 协调者」及其提供方，用成员的颜色。引用以标签显示在输入框上方（点开预览、× 移除），不再在文本框里摊成原始引用块。
+- **成员编辑对话框**：顶部是这个成员的卡片（随编辑实时变化），然后是邀请时定下的提供方和模式，再是可编辑字段与带标签的「模型」控件。
+
+**修复**
+
+- 输入法候选按 Enter 不再直接发送（含 Safari 结束输入时的那次按键）。
+- 重启打断的一轮不再卡住后续：你给这个成员发新消息、停止任务、或别的房间向它求助时，都会把它没收尾的普通轮次记为未完成并继续（正式目标的尝试仍需你确认）。
+- 外部协调者在场时，用消息工具就地编辑的消息会照常送到协调者，不再悄悄丢掉。
+- 用量合计按互不重叠的几部分相加（未命中输入、缓存读写、输出）：缓存多的 Claude 一轮原来只显示几千 token。
+- @ 菜单修复：房间每秒重绘时查询被取消、只剩本房间成员；候选结果解包错误导致从不显示别的会话；开头的会话标签被误当成成员 @ 而发送失败。
+- 已归档的会话不再出现在 @ 菜单里，也不会被求助（原来打开是空白页，求助石沉大海）。
+- 发言的提供方标签恢复为三级灰（误显示成错误红）；任务页的返回改用面板组件的箭头；「请求明细」图标改由本包自带（宿主 0.2.1-rc.1 起不再提供）。
+- **README 重写**：改为大白话说明，写明它为什么只在带协作间的套件模式里出现、要随套件一起装；去掉过时的验收说明与失效链接。
+
+**其它**
+- **新成员默认用房间的模式**:`room_invite` 新增 `mode`(不填则通过 inheritPreset 沿用房间会话自己的模式;`"none"` 表示只用 CLI 自带工具),回执里写明模式;邀请对话框预选当前会话的模式,模型与思考强度改成两个带标签的下拉框。
+- **卡名改为「协作间」**(原「多Agent协同」):与界面里一直使用的叫法统一,也和所在的「多Agent协作」套件卡区分开;英文卡名仍是 Room。
+- **run-state 边携带子会话关联**:`room/run-state` 在身份存在后的所有边恒带 `childSessionId`（成员首跑的 running 边早于句柄产生，终态边与后续轮次都有）；终态边（done/cancelled/failed）新增 `childTurn`（该运行写入子会话的轮次号，只读在内存的存活会话）。`room/dispatch`、`room/run-state`、`room/coordinator`、`room/member-added` 是 Context Lens 的外部读取接口（类型注释已标注）。
+
+## 0.2.2（2026-10-22）
+
+- **房间输入条草稿接入官方 input machine**：草稿不再存组件本地 state，房间接管条与官方回退输入条共享同一份草稿——「引用到当前会话」等外部写入立即在房间里可见（此前写入成功却只渲染在隐藏的回退条里，看似失效）；草稿随机器持久化，跨导航/重挂存活；首次拉取窗口期在回退条打的字在接管当选后保留。发送路径不变：仍走房间自己的 `remote.room.postMessage` 派发，`inputActions.submit` 永不调用，机器忙碌准入不会串行化并行成员派发。引用 chip 在纯 textarea 投影为剪贴板文本、编辑即摊平（接受的房间侧降级）。
+- 自隐 tab（成员 tab 等 `conversation.view` 条目）的注册/注销切换延后到下一帧（requestAnimationFrame），避开宿主 ui-conversation `refreshViews` 对已释放会话滞留绑定的 uncaught throw 窗口期——上游修复提案见 docs/upstream-proposals/2026-10-20-refreshviews-stale-binding-robustness.md。
+- 适配宿主 0.2.1 线：peer 区间加宽覆盖 0.2.1；`./tool` 子路径行 locale 重定向到包根，宿主设置清单页显示插件卡片标题而非裸模块名；退役 load 期 invariant 伴生探针并声明 `engines.dsh`。
+
 ## 0.2.1（2026-09-30）
 
 无功能变更。加宽 `@deepseek-ai/dsh-*` peer 区间以覆盖宿主 0.2.0（0.2.0 的兼容闸会禁用 peer 区间不覆盖宿主版本的已装插件）。

package/README.en.md

@@ -2,83 +2,50 @@
 
 English | [中文](README.md)
 
-One session, a whole team of agents — invite DSH, Kimi, Codex or Claude Code members in, @-name them to hand out work, and let a coordinator run the plan while the accept/rework call stays with the human.
+Turn one session into a room: bring in a few agents, @ a name to hand out work, and stay in the loop to make the calls.
 
-Getting several agents onto one piece of work today means copy-pasting between windows, or one-shot subagent calls that forget everything on return. Room makes the session itself the shared place: inviting the first member promotes the current session into a Room and seats the native DSH agent as the initial coordinator, and every member keeps its own native conversation across turns and restarts.
+Getting several agents to work on one thing used to mean copying text between windows and keeping track yourself of who had done what. With the room installed, invite the first member and the session becomes a room: dsh itself acts as coordinator, splitting the work, handing it out and collecting the results, while Kimi, Codex, Claude Code or another dsh join as members who each do their part and pass messages to one another. What you get is one place that shows who is doing what, how far along it is and what it cost — and accepting the work is still your call.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-1.png" width="640" alt="an active Room: member receipts and run rows in the chat flow, with the @-member menu open above the composer">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-1.png" width="560" alt="A room in progress: member replies and run rows in the chat, with the @ member menu open above the input">
 
-## Features
+## What it does
 
-- **Collapsible execution and plan capsules** — Background agents sits above the input, showing only its label and a green dot while work runs. Expand for execution state, duration, reported round tokens, targeted Stop and real conversation links; native descendant totals are explicitly labeled as session totals. Plans start with a compact progress list; full review and limits open in the optional host sidebar, with inline fallback.
-- **Inviting promotes the session** — no separate "create room" step: invite the first member into any session and it becomes a Room; the native DSH agent joins as the initial coordinator (named `dsh` in new rooms; existing rooms keep their recorded addressing names).
-- **@-addressing with fan-out** — leading `@name` tokens address existing members, and several names fan out at once; a mention picked from the completion menu addresses explicitly even mid-sentence, while a hand-typed mention inside prose does not (the menu never creates members). Same-member turns share one queue, different members run concurrently, and durable request identities keep retries from duplicating accepted work.
-- **Coordinator handoff** — any prepared member (DSH, Codex, Claude Code, Kimi) can take over via **Set as coordinator** in the Members tab; the handoff record carries the goal, the plan state, open tasks and recent context. A running coordinator cannot be replaced until its current turn settles.
-- **Background delegation with correlated reports** — ordinary chat needs no formal plan: the coordinator dispatches a small background task with `room_message` and receives the completion report, correlated, at a turn boundary. Peer notifications between members (`member_message`, trailing `@name` replies) stay behind a human confirm/dismiss gate that never blocks coordinator task reports.
-- **Durable goal plans with evidence review** — larger work becomes a formal goal: stages, hierarchical tasks, dependencies, execution attempts, submitted evidence, and explicit acceptance or rework. A finished generation is not accepted by default; dependent tasks unlock only after their prerequisites are accepted. Budgets bound goal-wide concurrency, total and per-task executions, and active goal time (paused time excluded); pause, resume, rebudget, cancel and complete stay human commands. After a restart, unresolved executions are marked uncertain and the plan pauses — reconciliation requires evidence, never a blind re-run.
-- **Members keep their native sessions** — the Members tab holds names, providers, roles, working-directory overrides (blank inherits the Room's directory), effective configurations and session links; breadcrumbs and task links open the member's own conversation with its tools, duration and token usage. Room statistics for the native session are not a sum of member spend.
-- **Shared model/effort controls** — coordinator and member composers share the core model/effort control; choosing a new configuration mid-run queues it for the next complete turn (tool continuations keep the current one), and frozen evaluation members reject changes. The original native DSH session keeps the host model selector and its semantics — it is not a local-agent member controller.
-- **Live output, targeted stop** — members stream native text and reasoning into both their own conversation and the Room; final messages and tool records stay authoritative. Stopping a member interrupts only that member and preserves non-empty partial output with an explicit stopped/failed label, duration and session link; long replies expand from a compact preview.
-- **Preset-gated chrome, fail-open** — the **Invite agent** header chip and the **Members** tab appear exactly when the session's preset composition grants the `@khorsheed/dsh-room/tool` row, fail open when the composition cannot be read, and always stay visible inside an existing Room.
+- **Inviting starts the room**: click "＋ Invite agent" in the session header and pick the member, mode, model and effort; once the first one joins, the session is a room — nothing else to create. New members use the room's own mode by default.
+- **@ someone and it's theirs**: @ one member or several and they start at once; their answers appear in the room as they write, and you can stop just one of them. Every member keeps its own session, one click away.
+- **Ask a session outside the room**: the @ menu also lists other sessions and other rooms — pick one and the coordinator asks it for help. Members can ask on their own too, Kimi and Codex members included. The first time a session you never @-ed is asked, it waits for your OK; the reply comes back to the room, and a request that waits too long turns amber.
+- **Members ask, you click to answer**: when a member needs a decision from you, a "someone asks you" card appears in the room — pick an option or type a line.
+- **Every task at a glance**: above the input, "N tasks running"; open it to see who is working on each task, how far it got and what it used. Anything that needs you is marked amber, and you can stop a whole task or a single step.
+- **The team on one page**: "Team" on the members page draws who hands work to whom between you, the coordinator and the members, and what each is busy with. An outside session you keep asking can be added with "Add to members", so next time you just @ it.
+- **The calls it makes for you are on record**: whether a new message is a new task or belongs to a running one, and when a member's result goes to the coordinator, the room decides itself — each decision leaves a line on the timeline, and "View decision" shows why. To turn this off, use "Automatic decisions" in the room's Collaboration settings.
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-invite.png" width="640" alt="the Members tab: the empty state that turns the session into a multi-agent collaboration room, and the session header's Invite agent entry">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-invite.png" width="560" alt="Members page: the empty state offering to turn the session into a multi-agent room, and the session header's Invite agent entry">
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-2.png" width="640" alt="the Members tab: member cards with name, provider, role and model, plus the Set-as-coordinator action">
+- **You stay in charge**: any member can take over with "Set as coordinator"; in the Collaboration settings you can have messages between members wait for your OK, or "Pause the room" so new member messages queue up and go out in order once you resume.
 
-## Install
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-2.png" width="560" alt="Members page: member cards (name, provider, role, model) with the Set as coordinator action">
 
-```sh
-dsh plugin --profile web add @khorsheed/dsh-room
-```
+## Install
 
-The package mounts its own loader row and browser contribution; restart the web instance to activate. For external CLI members, install the local-agent core and the providers you want alongside it — without them the Room still works with the native DSH coordinator. The model-facing tools (`room_invite` / `room_task` / `room_message`) ship with this package since 0.2.0: the tool row is the package's `./tool` composition entry, granted per session by an agent preset (referenced as `@khorsheed/dsh-room/tool`, row id `room-tool`; the standalone 0.1.x companion `@khorsheed/dsh-room-tool` is retired).
+In DSH, open Plugins → Add plugin, enter the package name below and click install:
 
-```sh
-dsh plugin --profile web remove @khorsheed/dsh-room
+```
+@khorsheed/dsh-dev-suite
 ```
 
-Uninstalling removes the plugin's surfaces; persisted Room journals stay in their session logs.
-
-## Compatibility
-
-- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): ✅ supported with one designed degrade — 0.1.5-rc.1 full-line boot-verified (42 packages including capture, 2026-09-25) through the three compat layers ([preset-registry dual-name probe](../../.agents/notes/implemented/bug-fix/2026-09-25-preset-registry-dual-name-probe.md), [dual-shape typert codecs](../../.agents/notes/implemented/bug-fix/2026-09-25-typert-codec-dual-shape.md), [typert faces carrying zod@4](../../.agents/notes/implemented/bug-fix/2026-09-25-typert-faces-carry-zod-v4.md)); `minHost` is pinned at 0.1.5-rc.1. External members require the local-agent family (core + providers), which is not yet published on npm: without it, member preparation, shared model/effort controls and the authenticated member tools answer unavailable, while native DSH Room functionality stays complete. Candidate-tarball fresh-install and upgrade checks on the npm host pass, retaining existing Room state.
-- source line (deepseek-harness master): ✅ (verifiedHost: 0.1.7-rc.2 — also the 3080 production-verified line) — Session V4 adaptation: the main-agent followup's source moved to the producer-owned kind `room` (V4 native admission refuses the retired `kind: 'plugin'` wrapper at the durable write; a 0.1.5 host's `user/message` admission accepts any non-empty kind, so both lines write durably), and the read side accepts `room`, `plugin:@khorsheed/dsh-room` (the V3→V4 migrated form) and the released V3 wrapper. The `conversation.chat.node` rc.1 contract re-verified (the 5 room renderers touch neither hookContext nor the disclosure factory). DSH/Kimi coordinators, delegation, two-stage review and interruption recovery are exercised end to end — see the [acceptance record](../../docs/acceptance/room-coordinator-2026-09-19.md).
-
-## Known Limitations
-
-- **Peer notifications still need a human confirm** — `member_message` relays and trailing `@name` replies journal as pending until the human confirms or dismisses; only coordinator task reports bypass the gate.
-- **External members depend on the local-agent family** — until the family is published and installed, CLI member preparation, shared controls and authenticated member tools degrade to unavailable (structured `local-agent-unavailable` at invite, journaled `failed` runs at dispatch); the native DSH member keeps working.
-- **Codex/Claude runtime acceptance is still pending** — DSH and Kimi members have been exercised end to end; Codex/Claude authenticated runs have not, and the full P95 streaming gate remains open — the transport interval alone proves nothing about P95 latency.
-- **A persisted Room needs Room to stay mounted** — the `room/*` event vocabulary is registered by the plugin into the session-event catalog (a temporary seam pending an official event-registration API), so a build without the plugin refuses the log by design.
-- **Member chrome replicates host visuals** — identity and action styling track the host's chrome and need re-checking when upstream visuals change.
-- **Cross-host paint measurement assumes a shared clock** — the local diagnostic does; remote-host measurements need clock alignment.
-- **A green model reply does not prove storage landed** — persistence failures surface diagnostically.
-
-## How it works
-
-<details>
-<summary>Internals (click to expand)</summary>
-
-**Architecture.** The host half is `RoomService`, a Typert Remote service (provided as `room`) owning promotion, roster management, the human @-intake, the notification gate, the task board and run cancellation; dispatch records and first tasks execute through the `DispatchEngine`, durable goals through the `PlanService` (one serialized writer per room). The room's entire state is the session's `room/*` custom-event journal — log-only events: persistence and reload-replay come free, the model never sees them, and a harness without this plugin replays the session safely. Every read folds the journal through a pure replay; every mutation appends and flushes. Cold reads (`isRoom`/`getState`) answer from a persistence inspection without waking an agent; a mutation on a cold room cold-resumes the agent under the preset the log records. An `agent/pre-step` guard keeps a stale client or another input surface from waking the DSH model behind an external coordinator: a native turn must carry an explicit room-sourced dispatch, and user input is rerouted through the room intake or rejected when it cannot be forwarded losslessly.
-
-**Event-vocabulary seam.** The plugin registers its `room/*` types into the session-persistence event catalog at apply time. The registration must land in the toolchain's module instance — a profile-installed plugin would otherwise resolve a second catalog copy and the read path would refuse room logs after restart — so the specifier is computed and resolved at runtime, and a top-level await lets the plugin loader block boot on it. This is a temporary seam pending an official event-registration API.
-
-**Client.** The browser half mounts the generated Remote via `ctx.remote.$mount`, registers the zh/en dictionaries, and feeds a client-side `RoomStore`. Slot entries: the **Invite agent** session-header action (`conversation.session.header.actions`, order 30), the **Members** `conversation.view` tab (order 20; hiding happens at registration level — a hidden tab is unregistered, not an empty body), the `conversation.composer` takeover (priority -10: claims exactly cached-room sessions, yields to pending approval interactions, and renders the dock capsules and stats row itself because their official seats hide with the fallback), and five `conversation.chat.node` renderers (`room-speech` / `room-run` / `room-event` / `room-relay` / `room-task-line`).
-
-**Tool row (the M4' split, folded back at 0.2.0).** The core registers no model-facing tools at the profile root: the `room_invite` / `room_task` / `room_message` factories live in the internal `./tool-definition.ts` module (not on the exports map) and ship untagged; the mountable row is this package's `./tool` composition entry (`name` / `inject = ['room']` / `apply`, zero `ctx.provide` — the preset-mount isolate-realm rule forbids only service rows, so a tool row composes bare in a preset), referenced by name from an agent preset's `agent.cordis.yml` (`name: '@khorsheed/dsh-room/tool'`, row id `room-tool`), granted per session and tagged with this package as its tool origin. The row was the standalone companion `@khorsheed/dsh-room-tool` on the 0.1.x line and folded back at 0.2.0 (the canvas `./agent` precedent); the old npm name is retired. `room_invite` and `room_message` promote the calling session into a room; `room_task` writes the shared board through the same host functions the capsule UI uses. External members reach `room_read` / `room_invite` / `room_message` / `room_plan` through the authenticated family bridge (`receiveMemberCommand`), where room and actor identity are host-owned, never tool arguments.
-
-**Family coupling.** The only coupling to the local-agent family is a probed facade — `ctx.get('localAgent')` plus method-existence duck-typing, with types as type-only imports drift-checked at compile time. An absent facade degrades CLI members (structured `local-agent-unavailable` at invite, journaled `failed` runs at dispatch) and never fails the boot. The notification gate's `receiveMemberMessage` is duck-type-called by the family bridge and runtime-validated across the untyped package boundary.
-
-**Model experience.** The current goal rides the top of the roster section in every member prompt; there is deliberately no blackboard fold — member prompts never consume the room's running log (speech/dispatch events are journaled for UI projection and replay only). Model-facing tools arrive with the session's preset grant, tagged by the package's own `./tool` row.
+The room comes with 开发套件 (the dev suite); for editing or making games, 剪辑套件 (the video suite, `@khorsheed/dsh-video-suite`) or 游戏开发套件 (the game dev suite, `@khorsheed/dsh-gamedev-suite`) carry it too. Once installed, open a session in "开发模式" (dev mode), "剪辑模式" (editing mode) or "游戏开发模式" (game dev mode) and click "＋ Invite agent" in the session header. Its tools only make sense in those modes, so they are handed only to those modes sessions and other modes don't get tools and buttons they can't use. That is also why it should be installed with its suite rather than on its own — installed alone it doesn't show up.
 
-**Identity triangle.** cordis row id `room` (`cordis.patch.yml`) = `clientBundle('@khorsheed/dsh-room')` (`tsdown.config.ts`) = `src/invariant.ts` `PACKAGE_NAME`. Exports: `.` host service, `/client` (plugin `apply`/`inject` plus the `RoomRemote` type), `/tool` the session-granted model tool row, `/types`, `/typert`, `/remote`, `/invariant`.
+## Known limitations
 
-</details>
+- To invite Kimi, Codex or Claude Code, install their command-line tools on your computer first and fill in their credentials on the 「本机 Agent 委派」 (Local Agent Delegation) card on the Plugins page; one that isn't set up shows as "(logged out)" in the invite dialog and can't be picked.
+- Archived sessions don't appear in the @ menu and can't be asked for help — unarchive one first.
+- Room sessions depend on this plugin: once it is uninstalled, earlier room sessions can't be read.
 
-## Development
+## Compatibility
 
-Part of the [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo (`packages/room`). Issues and contributions welcome there.
+Requires DSH 0.1.5 or later; verified on 0.2.1.
 
-## Changelog
+## For developers
 
-See [CHANGELOG.md](CHANGELOG.md).
+- Entry points: `src/index.ts` (the room service), `src/tool.ts` (the room tools agents use), `src/client/index.ts` (the UI). Installed on its own (`dsh plugin --profile web add @khorsheed/dsh-room`), the room tools must be granted by a mode, and the entry shows only in that mode's sessions.
+- The coordinator and dispatch flow, event journal, tools, compatibility details and internals are in the [full reference](https://github.com/Khorsheed/dsh-plugins/blob/main/packages/room/docs/reference.en.md).
+- Part of [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) — issues and contributions go there; changes are in [CHANGELOG.md](CHANGELOG.md).

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/room/README.en.md
-packages/room/README.en.md: e618b146703f23e87a1f4ad5c02b041aa9b42609
-packages/room/README.md: 50cce309cba3611d7117ddb791fabcd14b0a9ca1
+packages/room/README.en.md: 8a91662702be3e29ee27d53fd5eb033553cb18e9
+packages/room/README.md: 5f0530dece07c73e61b890518459a736cedb725f

package/README.md

@@ -2,83 +2,50 @@
 
 [English](README.en.md) | 中文
 
-一个会话，一整队 agent——把 DSH、Kimi、Codex、Claude Code 邀请进来，@ 名字派活；协调者拆目标、成员交证据，验收还是人说了算。
+把一个会话变成协作间：请几个 agent 进来，@ 名字派活，你在旁边看着、拿主意。
 
-让多个 agent 干同一件事，过去只能在几个窗口之间复制粘贴，或者靠一次性的子代理调用——返回即遗忘。Room 把会话本身变成共享的协作场所：邀请第一位成员，当前会话就升级为 Room，原生 DSH agent 入座初始协调者；每位成员跨轮次、跨重启都保留自己的原生会话。
+让几个 agent 合干一件事，以前只能在几个窗口之间来回复制粘贴，谁做到哪一步全靠你记。装上协作间，在会话里邀请第一位成员，这个会话就成了协作间：dsh 自己当协调者，帮你拆活、派活、收结果；Kimi、Codex、Claude Code 或另一个 dsh 都能当成员，各干各的、互相传话。你得到的是一个房间：谁在干什么、干到哪、花了多少，一眼看清，最后验不验收还是你说了算。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-1.png" width="640" alt="一个进行中的 Room:聊天流里的成员回执与运行行,输入框上方展开的 @ 成员菜单">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-1.png" width="560" alt="一个进行中的协作间：聊天流里的成员回复与运行行，输入框上方展开的 @ 成员菜单">
 
-## 特性
+## 能做什么
 
-- **折叠执行与计划胶囊**——输入框上沿的「后台 Agent」默认只显示名称，有执行时图标变为绿点。展开后按执行查看状态、耗时、已报告的单轮 token、中止与真实会话入口；原生后代会话累计值单独标注。正式计划先展示简短进度，完整验收与运行限制按需进入侧栏；缺少侧栏时原位展开。
-- **邀请即升级**——没有单独的「创建房间」步骤：在任意会话里邀请第一位成员，它就变成 Room；原生 DSH agent 入座初始协调者（新 Room 命名为 `dsh`，已有 Room 保留日志里记录的寻址名）。
-- **@ 寻址与并行派发**——开头的 `@name` 指向已有成员，多个名字并行派发；从补全菜单选中的提及即使位于句中也明确寻址，手写在正文里的提及则不算（菜单永不创建成员）。同一成员的轮次共用一条队列，不同成员并发执行；请求带持久化身份，重试不会重复已接受的工作。
-- **协调者交接**——任何准备好的成员（DSH、Codex、Claude Code、Kimi）都可以在成员页「设为协调者」；交接记录携带目标、计划状态、未结任务和最近上下文。协调者运行中时，必须等当前轮次落定才能替换。
-- **后台委派、回报自动对账**——普通聊天不必建立正式计划：协调者用 `room_message` 派发小型后台任务，在轮次边界自动收到带关联标识的成果回报。成员之间的普通通知（`member_message`、回答末尾的 `@name`）仍走人工确认/忽略闸门——该闸门从不阻塞协调者任务回报。
-- **耐久目标计划与证据验收**——较大工作建立正式目标：阶段、层级任务、依赖、执行尝试、提交的证据，以及明确的验收或返工。生成结束不等于验收通过；前置任务验收后，后续任务才有资格执行。预算约束整个目标的并发数、总执行次数、每项任务执行次数和目标推进时长（不含暂停时间）；暂停、继续、调整预算、取消与完成都是人的指令。重启后未确定的执行标记为待核对、计划暂停——核对必须提供证据，绝不盲目重跑。
-- **成员保留原生会话**——成员页记录名称、provider、角色、工作目录覆盖（留空继承 Room 目录）、有效配置与会话入口；面包屑与任务入口能进入成员自己的会话，查看工具、耗时与 token 用量。Room 原生会话的统计不是所有成员消耗的总和。
-- **共享模型/强度控制**——协调者与成员输入栏共用同一套 core 模型/effort 控制；运行中选择新配置会排到下一完整轮次（工具续跑沿用本轮配置），冻结的评测成员拒绝变更。原生 DSH 主会话仍使用宿主模型选择器及其语义——它不是 local-agent 成员控制器。
-- **实时输出与定向停止**——成员把原生正文与推理增量同时呈现在自己的会话和 Room 中；最终消息与工具记录仍是权威内容。定向停止只中断该成员，非空部分输出带明确的停止/失败标记、耗时与会话入口保留；长回答可从紧凑预览展开。
-- **入口随 preset 授权显隐、失败放行**——「邀请 agent」chip 与「成员」tab 只在当前会话的 preset 组合授予 `@khorsheed/dsh-room/tool` 行时出现；读不到组合时保持可见（fail-open）；已是 Room 的会话始终保留界面。
+- **邀请就开房**：点会话头部的「＋ 邀请 agent」，选好成员、模式、模型和思考强度；第一位进来，这个会话就成了协作间，不用另外建。新成员默认跟房间用同一个模式。
+- **@ 谁就派给谁**：@ 一个或几个成员，它们同时开工；回答边写边出现在房间里，想停只停那一位。每个成员留着自己的会话，点进去就能看它干了什么。
+- **找房间外的会话帮忙**：@ 菜单里也列着别的会话和别的协作间，选一个，协调者就去问它；成员自己也能去问，Kimi、Codex 这类成员也一样。第一次找你没 @ 过的会话，会先等你同意；对方的回信带回房间，等太久那一行会变黄提醒你。
+- **成员问你，点一下就答**：成员需要你拿主意时，房间里会出现一张「某某 问你」的卡片，点选项或写一句话就行。
+- **任务一眼看清**：输入框上方写着「N 个任务进行中」，点开能看到每个任务谁在做、做到哪、用了多少；需要你处理的会标黄，可以停掉整个任务，也可以只停其中一步。
+- **团队一张图**：成员页的「团队」画出你、协调者和成员之间谁给谁派活、各自在忙什么；常找的外部会话可以「加入房间成员」，下次直接 @。
+- **它替你拿的主意都留了底**：新消息算新任务还是并进旧任务、成员的结果什么时候交给协调者，房间会自己判断，每次判断都在时间线上留一行，点「查看判断」看依据；不想让它判断，就去「协作设置」的「自动判断」里关掉。
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-invite.png" width="640" alt="成员标签页：空态的「把会话变成多 agent 协作间」与会话头部的「邀请 agent」入口">
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-invite.png" width="560" alt="成员页：空态的「把会话变成多 agent 协作间」与会话头部的「＋ 邀请 agent」入口">
 
-<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-2.png" width="640" alt="成员页：成员卡片（名称、provider、角色、模型）与「设为协调者」操作">
+- **你说了算**：任何成员都能「设为协调者」接班；「协作设置」里可以让成员之间的消息先等你确认，也可以「暂停房间」，成员的新消息先排队，恢复后照顺序送达。
 
-## 安装
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/room-2.png" width="560" alt="成员页：成员卡片（名称、provider、角色、模型）与「设为协调者」操作">
 
-```sh
-dsh plugin --profile web add @khorsheed/dsh-room
-```
+## 安装
 
-本包自行挂载 loader 行与浏览器贡献；重启 web 实例后生效。需要外部 CLI 成员时，同时安装 local-agent core 和所需 provider——没有它们，Room 仍可与原生 DSH 协调者正常协作。面向模型的工具（`room_invite` / `room_task` / `room_message`）0.2.0 起随本包自带：工具行是包内 `./tool` 组合入口，由 agent preset 按会话授予（preset 组合里引 `@khorsheed/dsh-room/tool`，行 id `room-tool`；0.1.x 的独立伴生包 `@khorsheed/dsh-room-tool` 已退役）。
+在 DSH 的「插件 → 添加插件」里输入下面的包名，点安装：
 
-```sh
-dsh plugin --profile web remove @khorsheed/dsh-room
+```
+@khorsheed/dsh-dev-suite
 ```
 
-卸载移除本插件的全部界面；已持久化的 Room 日志保留在各自会话日志中。
-
-## Compatibility
-
-- npm 发布线（`@deepseek-ai/dsh@0.1.5-rc.1`）：✅ 支持、带一处设计内降级——0.1.5-rc.1 全量 boot 实证通过（42 包含 capture，2026-09-25），经三层兼容修复（[preset-registry 双名探测](../../.agents/notes/implemented/bug-fix/2026-09-25-preset-registry-dual-name-probe.md)、[typert codec 双形状](../../.agents/notes/implemented/bug-fix/2026-09-25-typert-codec-dual-shape.md)、[face 自带 zod@4](../../.agents/notes/implemented/bug-fix/2026-09-25-typert-faces-carry-zod-v4.md)）；`minHost` 钉在 0.1.5-rc.1。外部成员依赖 local-agent 家族（core + provider），该家族尚未发布到 npm：缺失时成员准备、共享模型/强度控制与认证成员工具返回不可用，原生 DSH Room 功能保持完整。候选 tarball 在 npm 宿主上的全新安装与升级检查通过，旧 Room 状态得到保留。
-- 源码线（deepseek-harness master）：✅（verifiedHost: 0.1.7-rc.2——也是 3080 生产实证线）——Session V4 适配：主 agent followup 的 source 改为生产者归属 kind `room`（V4 原生准入在落盘写入时拒收退役的 `kind: 'plugin'` 包装；0.1.5 宿主的 `user/message` 准入只查 kind 非空，两条线都能落盘），读侧兼认 `room`、`plugin:@khorsheed/dsh-room`（V3→V4 迁移形态）与 V3 包装存量。`conversation.chat.node` rc.1 契约复验通过（5 个 room 渲染器均不触 hookContext 与 disclosure 工厂）。DSH/Kimi 协调者、委派、两阶段验收与中断恢复已端到端实测——见[验收记录](../../docs/acceptance/room-coordinator-2026-09-19.md)。
+协作间会跟着「开发套件」一起装好；做剪辑、做游戏的话，装「剪辑套件」`@khorsheed/dsh-video-suite` 或「游戏开发套件」`@khorsheed/dsh-gamedev-suite` 也带着它。装完开一个「开发模式」「剪辑模式」或「游戏开发模式」的会话，点会话头部的「＋ 邀请 agent」开始。它的工具只对这几个模式有用，所以只交给这几个模式的会话，其它模式不会多出用不上的工具和按钮；这也是要连同套件一起装、不要只装本包的原因——单独装时它不会出现。
 
 ## 已知限制
 
-- **成员间通知仍需人工确认**——`member_message` 转发与回答末尾的 `@name` 先落 pending 日志，等人确认或忽略；只有协调者任务回报不经过这道闸门。
-- **外部成员依赖 local-agent 家族**——家族发布并安装之前，CLI 成员准备、共享控制与认证成员工具降级为不可用（邀请时返回结构化 `local-agent-unavailable`，派发落 `failed` 运行记录）；原生 DSH 成员不受影响。
-- **Codex/Claude 运行验收仍待完成**——DSH 与 Kimi 成员已端到端实测；Codex/Claude 认证运行尚未验收，完整 P95 流式门槛也未关闭——通道间隔本身证明不了 P95 延迟。
-- **已持久化的 Room 需要保持挂载本插件**——`room/*` 事件词汇表由插件注册进会话事件目录（等待官方注册 API 的临时 seam），未挂载的构建按设计拒读该日志。
-- **成员标识与操作样式复用宿主视觉**——跟随宿主 chrome，上游视觉变化时需要跟进复验。
-- **跨宿主绘制测量假设同钟**——本地诊断假设共享时钟；远程宿主的测量需要对齐时钟。
-- **模型回答成功不能排除存储故障**——持久化失败以诊断形式呈现。
-
-## 实现原理
-
-<details>
-<summary>内部结构（点击展开）</summary>
+- 要邀请 Kimi、Codex、Claude Code，电脑上要先装好它们的命令行工具，并在「插件」页的「本机 Agent 委派」卡片里填好凭据；没配好的那家在邀请框里标着「（未登录）」，选不了。
+- 已归档的会话不会出现在 @ 菜单里，也找不了它帮忙，要先取消归档。
+- 协作间的会话离不开这个插件：卸掉之后，以前的协作间会话读不出来。
 
-**架构。** 宿主半部分是 `RoomService`——一个 Typert Remote 服务（以 `room` 提供），掌管升级、名册管理、人类 @ 入口、通知闸门、任务板与运行取消；派发记录与首个任务由 `DispatchEngine` 执行，耐久目标由 `PlanService` 负责（每个房间一条串行写者）。房间的全部状态就是会话的 `room/*` 自定义事件日志——纯日志事件：持久化与重载回放免费获得，模型永远看不到，未挂载本插件的宿主也能安全回放该会话。每次读取把日志经纯函数回放折出状态，每次写入追加并落盘。冷读取（`isRoom`/`getState`）经持久化检视回答，不唤醒 agent；对冷房间的写入先按日志记录的 preset 冷恢复 agent。`agent/pre-step` 守卫防止过期的客户端或其他输入面在外部协调者背后唤醒 DSH 模型：原生轮次必须携带明确的 room 来源派发，用户输入改走房间入口路由，无法无损转发时直接拒绝。
-
-**事件词汇 seam。** 插件在 apply 时把 `room/*` 类型注册进会话持久化的事件目录。注册必须落在工具链的模块实例里——profile 安装的插件否则会解析出第二份目录副本，重启后读路径会拒读 room 日志——因此 specifier 在运行时拼出并解析，顶层 await 让插件加载器阻塞 boot 直到注册完成。这是等待官方事件注册 API 的临时 seam。
-
-**客户端。** 浏览器半经 `ctx.remote.$mount` 挂载生成的 Remote，注册 zh/en 词典，并驱动客户端 `RoomStore`。槽位条目：会话头部「邀请 agent」动作（`conversation.session.header.actions`，order 30）、「成员」`conversation.view` tab（order 20；隐藏发生在注册层——隐藏的 tab 是注销而非空体）、`conversation.composer` 接管（priority -10：只认领缓存判定为 Room 的会话，对挂起的审批交互让位；dock 胶囊与统计行由它自行渲染，因为它们的官方座位随被藏起的回退树一起消失），以及五个 `conversation.chat.node` 渲染器（`room-speech` / `room-run` / `room-event` / `room-relay` / `room-task-line`）。
-
-**工具行（M4' 拆分，0.2.0 回并）。** core 不在 profile 根注册任何面向模型的工具：`room_invite` / `room_task` / `room_message` 的工厂留在内部模块 `./tool-definition.ts`（不进 exports 面）且不带 origin 标签；可挂载行是本包的 `./tool` 组合入口（`name` / `inject = ['room']` / `apply`，零 `ctx.provide`——preset 挂载面的 isolate-realm 规则只拒服务行，工具行可裸放 preset），由各 agent preset 的 `agent.cordis.yml` 按名引用（`name: '@khorsheed/dsh-room/tool'`，行 id `room-tool`），按会话授予并打上归本包的 origin 标签。0.1.x 时该行是独立伴生包 `@khorsheed/dsh-room-tool`，0.2.0 起回并（canvas `./agent` 先例），旧 npm 名退役。`room_invite` 与 `room_message` 会把调用所在会话升级为 Room；`room_task` 与胶囊 UI 走同一组宿主函数写共享任务板。外部成员经认证家族桥（`receiveMemberCommand`）使用 `room_read` / `room_invite` / `room_message` / `room_plan`——房间与调用者身份由宿主持有，绝不出现在工具参数里。
-
-**家族耦合。** 与 local-agent 家族唯一的耦合是探测式门面——`ctx.get('localAgent')` 加方法存在性鸭子类型判断，类型仅作 type-only 导入、编译期漂移检查。门面缺席时 CLI 成员降级（邀请返回结构化 `local-agent-unavailable`，派发落 `failed` 运行记录），绝不影响 boot。通知闸门的 `receiveMemberMessage` 由家族桥鸭子调用，跨无类型包边界做运行时校验。
-
-**模型体验。** 当前目标随每个成员提示词的名册段顶部下发；刻意不做黑板折叠——成员提示词从不消费房间的运行日志（speech/dispatch 事件只为 UI 投影与回放落日志）。面向模型的工具随会话 preset 授予到达，由本包的 `./tool` 行打标。
-
-**身份三角。** cordis 行 id `room`（`cordis.patch.yml`）= `clientBundle('@khorsheed/dsh-room')`（`tsdown.config.ts`）= `src/invariant.ts` 的 `PACKAGE_NAME`。导出：`.` 宿主服务、`/client`（插件 `apply`/`inject` 与 `RoomRemote` 类型）、`/tool` 按会话授予的模型工具行、`/types`、`/typert`、`/remote`、`/invariant`。
-
-</details>
-
-## 开发
+## Compatibility
 
-隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo（`packages/room`）。问题与贡献请移步该仓库。
+需要 DSH 0.1.5 或更新版本，已在 0.2.1 上验证。
 
-## 变更记录
+## 给开发者
 
-见 [CHANGELOG.md](CHANGELOG.md)。
+- 入口：`src/index.ts`（房间服务）、`src/tool.ts`（agent 用的协作工具）、`src/client/index.ts`（界面）。单独安装（`dsh plugin --profile web add @khorsheed/dsh-room`）时，协作工具要由某个模式授予，入口只在那些模式的会话里出现。
+- 协调者与派活流程、事件日志、工具、兼容细节和内部结构，都在[完整参考](https://github.com/Khorsheed/dsh-plugins/blob/main/packages/room/docs/reference.md)里。
+- 隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins)，问题与贡献请到该仓库；变更见 [CHANGELOG.md](CHANGELOG.md)。