@deepseek-harness-tui/dsh-tui 0.11.2 → 0.12.0

package/guide/dsh-tui-guide/migrate.en.md

@@ -0,0 +1,166 @@
+# Session migration: import conversations from other coding agents
+
+[Documentation index](README.md) · [简体中文](migrate.md)
+
+Bring Claude Code, Codex, OMP, zcode, and Grok Build conversation histories
+into the DSH session store. After importing, `/resume` browses and restores
+them by their original working directory — switching agents no longer costs
+your history.
+
+```sh
+dsh-tui migrate                # list per-agent scannable file counts (writes nothing)
+dsh-tui migrate claude-code    # import every Claude Code conversation
+dsh-tui migrate codex --dry-run  # preview what would land, write nothing
+```
+
+In-TUI equivalent: `/migrate`. Bare `/migrate` opens a **multi-select source
+picker** — one row per agent (checkbox + scannable file count + an "active X
+min ago" badge, most recently active first): Space toggles, `a` selects
+all/none, Enter opens the **confirmation layer** (one line per checked
+source with its count and the "existing sessions are skipped automatically,
+safe to re-run" note; Enter imports / `d` dry-runs / Esc returns to the
+picker), Esc closes. `/migrate <agent>` passes through the same layer (single
+source); `/migrate <agent> --dry-run` previews directly since it writes
+nothing. The completion notification carries per-source real counters
+("imported X · already present Y"). The CLI stays direct for scripts. The import
+runs in a child process so the interface never freezes; results arrive
+through the notification flow and the output lands in a `/migrate` local
+row. Both entry points share the same import logic and idempotency rules.
+
+## Supported sources
+
+| Source | Local store | Notes |
+| --- | --- | --- |
+| `claude-code` | `~/.claude/projects/` | Lines split from one response (sharing `message.id`) merge into one step; thinking, tool calls and results, compaction summaries, `/rename` and generated titles all migrate; `isMeta` context joins the next step; `subagents/` and auxiliary transcripts are not sessions |
+| `codex` | `~/.codex/sessions/` | Tool calls with all three output shapes, reasoning summaries (the readable part), `compacted` summaries, interrupted turns and sub-agent reports migrate; the model is recorded per step from `turn_context`; injected blocks and sub-agent rollouts do not |
+| `omp` | `~/.omp/agent/sessions/` | DSH-lineage store, a near-direct mapping (text and thinking) |
+| `zcode` | `~/.zcode/v2/sessions/` | Single-JSON-object format; only user/assistant text is mapped, `meta.title` becomes the title |
+| `grok-build` | `~/.grok/sessions/` (relocatable via `GROK_HOME`) | Reasoning rows attach to the assistant step that follows; tool calls and results (images as placeholders), compaction summaries, interrupted turns and the `session_summary` title migrate; `<user_query>` and similar wrappers keep only the body; synthetic rows and `<user_info>` do not migrate |
+
+## Behavior contract
+
+- **Read-only source**: migration only reads the foreign agent's local store;
+  artifacts are written through the official `JsonlSessionPersistence` into
+  `$DSH_HOME/sessions` — imported sessions are first-class (openable,
+  continuable, rewindable).
+- **Idempotent**: one deterministic UUID (v5) per source conversation.
+  Re-importing skips what is already present instead of stacking duplicates
+  or rewriting existing logs. Both entry points derive identical session ids
+  from the same source data.
+- **Structure preserved**: rebuilt turn by turn, one step per model call in
+  the source: thinking, text, tool calls and their results sit in the step
+  that produced them, so an imported session can pick the work straight up.
+- **Wire-legal tool traffic**: each result pairs back by call id to the step
+  that made the call (never to the newest step), in call order within the
+  step; an unanswered call gets an empty result, a result with no call is
+  dropped and counted, and a call id reused across steps is renamed. On
+  resume every tool_call is followed by its tool message. One result keeps
+  at most 64KB (the rest is cut and noted); images always become an
+  `[image]` placeholder.
+- **Compaction checkpoints**: a context-compaction boundary in the source is
+  written as the same native compaction transaction `/compact` produces. The
+  raw events stay in the log; the model sees "summary + what followed", the
+  context the source agent itself continued with.
+- **Injection filtering**: machine text a harness writes into the user role
+  (environment blocks, AGENTS.md instructions, system reminders, local-command
+  echoes) opens no turn and never titles a session; `<user_query>`, pasted
+  envelopes and similar wrappers keep only their body. Model-visible machine
+  context mid-turn (Claude's `isMeta`, Codex sub-agent reports) is kept as
+  the next step's input.
+- **Titles**: a title the source owns (`/rename`, generated titles,
+  `session_summary`, `meta.title`) is written as `session/title`; without
+  one the first real prompt serves as a fallback but is not written, so DSH
+  derives it from the first user message itself. Titles are collapsed to one
+  line and capped at 80 characters.
+- **Ready to continue**: like a native session, an imported log reserves an
+  empty system head in its first step; on resume the system prompt replaces
+  it instead of landing after the imported history.
+- **Not migrated**: per-message original timestamps (event times are
+  import-time; the session start keeps the source record); the encrypted
+  part of Codex reasoning; Grok's provider-side tools
+  (`backend_tool_call`).
+- **Robustness**: malformed lines, legal JSON `null` (whole-line or nested),
+  and files over 64MB are skipped safely; one failed conversation never
+  aborts the batch — failures are listed and reported with exit code 1.
+
+## Measured reference (real data, for scale expectations)
+
+| Operation | Scale | Time |
+| --- | --- | --- |
+| List counts, five sources | ~3000 files | 0.7s (name matching, zero parsing) |
+| Import zcode | 60 conversations | 2.3s |
+| Import claude-code | 163 conversations (heavy thinking) | 39s |
+| Import codex + omp | 728 + 1366 conversations | ~2.5 min |
+| Re-import (idempotency) | any | < 1s, all already present |
+
+Browse afterwards with `/resume`: sessions land in per-cwd directories
+(named by the official encoding rules); titles and start times are readable;
+conversations with thinking render as collapsible reasoning blocks in the
+TUI.
+
+## Source tabs on the session screen
+
+When you do not want a bulk import, browse by source on the session screen
+(`/resume`, `/home`, `/agentview`): the title row shows a tab for every source
+with conversations, and selecting one **imports just that conversation** and
+opens it.
+
+- Parsing is exactly `/migrate`'s, and the session id is derived from the source conversation the same way: both entries land a conversation on the same DSH session, and one already imported simply opens.
+- Opening the session screen only checks whether each source has any conversation (each source's walk stops at its first candidate); a source's list is read when its tab is opened, from a summary scan (file heads/tails only). Within one run an unchanged conversation is not read again; no cache file is written.
+- A conversation whose working directory no longer exists is not imported; the screen says so, and `/migrate` still imports it in bulk.
+- The tabs do not change how `/migrate` or `dsh-tui migrate` behave.
+
+## Smart migration hint
+
+About 12 seconds after the TUI starts, one background pass checks whether any
+source saw file writes within the last 20 minutes (newest file mtime per
+source) and surfaces a single notification: "Just came from <agent>?
+/migrate imports it quickly". The scan is off the render path (sub-second)
+and fires at most once per session; a source with no data stays silent. While
+the hint is up, Enter (with an empty prompt) jumps straight into the picker
+with that source pre-checked; any other key dismisses it.
+
+## Troubleshooting
+
+- **`unknown agent`**: the authoritative source list is what bare
+  `dsh-tui migrate` prints.
+- **`needs the profile's compiled copy`**: the profile's compiled output is
+  missing or too old — run `dsh-tui update` first.
+- **Imports fewer than the scan count**: the scan count matches candidate
+  files by name; import additionally filters unreadable and empty
+  conversations, so landing slightly lower is expected.
+- **Fresh `DSH_HOME` first run reports installation rejected**: profile
+  bootstrap hit a stale npm tarball; upgrading dsh heals it, or use an
+  existing profile meanwhile.
+- **Nothing found at all**: confirm the foreign agent's data directory
+  exists under the current home; set `GROK_HOME` when grok-build lives
+  elsewhere.
+
+## Design notes (for maintainers and contributors)
+
+- Parsing is separate from IO: `adapters/<source>.parse.ts` are pure
+  functions (raw text → turn model) over shared rules in `parse/` (jsonl
+  bad-line counting, injection recognition and unwrapping, title
+  normalization, tool-call pairing); adapters only discover files. OMP still
+  produces a role list, folded into turns mechanically by `fromRoleTurns`.
+- grok's `synthetic_reason` filter: only default and explicitly `human`
+  user rows migrate; the summary row among `compaction_meta` becomes a
+  compaction checkpoint.
+- Claude's legacy (2.0.x) `summary` record is a one-line leaf title at the
+  head of a file: it is treated as a title, not a compaction boundary.
+- Codex `custom_tool_call` input is free-form (a patch, a JS snippet); it
+  migrates wrapped as `{"input": …}` so call arguments stay JSON.
+- zcode: no sample with tool traffic or reasoning has been available, so
+  only the text roles are mapped and no field is guessed at.
+- Timestamp boundary: grok rows carry no per-row time; the session start
+  comes from `summary.json`.
+- Terminology: "migrate" here means this feature; it is unrelated to the
+  package-rename migration from `dsh-cc-tui` (see
+  [Getting started](getting-started.en.md)).
+
+Implementation and verification live in `src/dsh-adapter/migrate/`,
+`scripts/verify-migrate-parse.mjs` (per-source parsing rules over synthetic
+fixtures), `scripts/verify-migrate.mjs` (event synthesis and the round trip
+through the official read chain, wire legality and compaction checkpoints
+included) and `scripts/verify-migrate-command.tsx` (the `/migrate` interaction
+regression, mounted against the real Chat screen).

package/guide/dsh-tui-guide/migrate.md

@@ -0,0 +1,132 @@
+# 会话迁移：从其他编程代理导入对话
+
+[文档索引](README.md) · [English](migrate.en.md)
+
+把 Claude Code、Codex、OMP、zcode、Grok Build 的本地对话历史导入 DSH
+会话库。迁移后 `/resume` 按原工作目录浏览并恢复这些对话——换代理不丢
+历史上下文。
+
+```sh
+dsh-tui migrate                # 列出各源可扫描的会话文件数（不写入）
+dsh-tui migrate claude-code    # 导入 Claude Code 的全部对话
+dsh-tui migrate codex --dry-run  # 只预览将落盘的内容，不写入
+```
+
+TUI 内等效入口：`/migrate`。裸 `/migrate` 弹出**多选源选择器**——每行一个代理
+（勾选框 + 可扫描文件数 + 「X 分钟前刚活动过」标记，最近活跃排最前）：
+空格勾选/取消、`a` 全选/全不选、Enter 进入**二次确认层**（逐行列出将导入
+的源与数量，注明「已存在的自动跳过，可重复执行」；Enter 导入 / `d` 干跑
+预览 / Esc 返回选择）、Esc 关闭。`/migrate <agent>` 同样经过确认层（单源）；
+`/migrate <agent> --dry-run` 因不写盘直接预览。完成通知带逐源真实计数
+（「导入 X · 已存在 Y」）。CLI 形态保持直达（脚本场景）。导入在
+子进程中运行，界面不会卡顿；结果经通知流汇报，输出汇入 `/migrate`
+本地行。两个入口走同一套导入逻辑与同一套幂等规则。
+
+## 支持的源
+
+| 源 | 本地存储 | 说明 |
+| --- | --- | --- |
+| `claude-code` | `~/.claude/projects/` | 同一次响应拆成的多行（共用 `message.id`）合并为一步；thinking、工具调用与结果、压缩摘要、`/rename` 与生成标题都迁移；`isMeta` 上下文并入下一步；`subagents/` 与辅助 transcript 不成会话 |
+| `codex` | `~/.codex/sessions/` | 工具调用与三种输出形态、reasoning 摘要（明文部分）、`compacted` 摘要、中断轮、子代理报告都迁移；模型按 `turn_context` 逐步记录；注入块与子代理 rollout 不迁移 |
+| `omp` | `~/.omp/agent/sessions/` | 与 DSH 同源的近直接映射（文本与思考过程） |
+| `zcode` | `~/.zcode/v2/sessions/` | 单 JSON 对象格式；只映射 user/assistant 文本，`meta.title` 作为标题 |
+| `grok-build` | `~/.grok/sessions/`（可用 `GROK_HOME` 重定位） | reasoning 行附着到其后的 assistant 步；工具调用与结果（图片换占位）、压缩摘要、中断轮、`session_summary` 标题都迁移；`<user_query>` 等包装只留正文；合成注入行与 `<user_info>` 不迁移 |
+
+## 行为契约
+
+- **只读源**：迁移只读取源代理的本地存储，绝不修改；产物经官方
+  `JsonlSessionPersistence` 写入 `$DSH_HOME/sessions`——导入的会话是
+  一等公民（可打开、可续聊、可 rewind）。
+- **幂等**：同一源对话命中同一确定性 UUID（v5）。重复导入跳过已存在
+  项，不堆叠重复、不重写已有日志。两个入口（CLI 与 TUI）对同一源数据
+  生成完全相同的会话 id。
+- **结构保留**：按轮次还原，一步对应源里的一次模型调用：思考过程、正文、
+  工具调用及其结果都在所属的步里，导入的会话可以直接接着做事。
+- **工具调用 wire 合法**：结果按调用 id 挂回发起调用的那一步（不挂最近一步），
+  同一步内按调用顺序排列；没有结果的调用补空结果，找不到调用的结果丢弃并
+  计数，跨步复用的调用 id 改名。续聊时每个 tool_call 都紧跟它的 tool 消息。
+  单条结果上限 64KB（超出截断并注明），图片一律换成 `[image]` 占位。
+- **压缩检查点**：源里的上下文压缩边界写为与 `/compact` 同形的原生压缩事务。
+  原始事件仍在日志里，模型只看到「摘要 + 之后的对话」，与源代理压缩后实际
+  使用的上下文一致。
+- **注入过滤**：harness 写进 user 角色的机器文本（环境块、AGENTS.md 说明、
+  system-reminder、本地命令回显等）不开轮、不当标题；`<user_query>` 与粘贴
+  信封等包装只保留正文。轮中途模型可见的机器上下文（Claude 的 `isMeta`、
+  Codex 的子代理报告）作为下一步的输入保留。
+- **标题**：源自带的标题（`/rename`、生成标题、`session_summary`、
+  `meta.title`）写为 `session/title`；没有时以首个真实提问兜底，但不写入
+  日志，由 DSH 按首条 user 文本自行回退。标题统一折叠空白、截断到 80 字符。
+- **续聊就绪**：导入日志与原生会话一样，在首步预留空的 system head；续聊时
+  系统提示词替换进这个位置，而不是追加在导入历史之后。
+- **不迁移的内容**：逐条消息的原始时间戳（事件时间取导入时刻，会话起始
+  时间保留源记录）；Codex reasoning 的加密部分；Grok 的提供方侧工具
+  （`backend_tool_call`）。
+- **健壮性**：单条坏行、合法 JSON `null`（整行或子对象）、超 64MB 的
+  文件均安全跳过；单个会话失败不中断整批，失败清单随退出码 1 汇报。
+
+## 实测参考（真实数据，供量级预期）
+
+| 操作 | 规模 | 耗时 |
+| --- | --- | --- |
+| 列出五源计数 | ~3000 个文件 | 0.7 秒（名字匹配，零解析） |
+| 导入 zcode | 60 会话 | 2.3 秒 |
+| 导入 claude-code | 163 会话（含大量 thinking） | 39 秒 |
+| 导入 codex + omp | 728 + 1366 会话 | 约 2.5 分钟 |
+| 重复导入（幂等） | 任意 | < 1 秒，全部 already present |
+
+导入后用 `/resume` 浏览：会话按原工作目录分目录存放（目录名按官方
+编码规则生成），标题、起始时间可读；含思考过程的会话在 TUI 中以
+推理块呈现，可折叠查看。
+
+## 会话管理界面的来源标签
+
+不想整批导入时，在会话管理界面（`/resume`、`/home`、`/agentview`）里按来源浏览：
+标题栏右侧为每个有会话的源显示一个标签，选中一条会话即**只导入这一条**并直接打开。
+
+- 解析与 `/migrate` 完全相同，会话 id 同样按源会话确定性生成：两个入口导入同一条会话得到同一个 DSH 会话，已导入的直接打开。
+- 打开会话管理界面只探测各来源是否有会话（每个来源找到第一个候选即停）；列表在点进标签时才读取，来自摘要扫描（只读文件头/尾）。同一次运行里没有变化的会话不重读；不写任何缓存文件。
+- 会话原工作目录已不存在时不导入，界面给出提示；这时仍可用 `/migrate` 整批导入。
+- 标签页不改变 `/migrate` 与 `dsh-tui migrate` 的行为。
+
+## 智能迁移提示
+
+TUI 启动约 12 秒后做一次后台检测：任一源在最近 20 分钟内有文件写入
+（以各源会话文件的最新修改时间为信号）时，弹出一次通知「刚刚从xx过来？
+/migrate 来快速迁移」。检测在后台运行（亚秒级），每会话只提示一次；
+`grok-build` 数据缺失时静默跳过。提示显示期间按 Enter（输入框为空时）
+直达选择器并自动勾选该源，其他按键照常。
+
+## 故障排查
+
+- **`unknown agent`**：源名以 `dsh-tui migrate` 无参输出的名单为准。
+- **`needs the profile's compiled copy`**：profile 内编译产物缺失或过旧，
+  先运行 `dsh-tui update`。
+- **导入数低于扫描计数**：扫描计数是候选文件数（按文件名匹配），
+  导入会过滤解析失败与空对话，略低属正常。
+- **全新 `DSH_HOME` 首跑报 installation rejected**：profile 自举撞上
+  npm 上陈旧的 tarball 版本，升级 dsh 后自愈；或先用已有 profile。
+- **一个会话都没找到**：确认源代理的数据目录存在于当前用户家目录；
+  `grok-build` 用 `GROK_HOME` 重定位时需在环境变量中设置。
+
+## 设计取舍（维护者与贡献者参考）
+
+- 解析与 IO 分离：`adapters/<源>.parse.ts` 是纯函数（原始文本 → 轮模型），
+  共享规则在 `parse/`（jsonl 坏行计数、注入识别与包装剥离、标题归一、
+  工具调用配对）；adapter 只做文件发现。OMP 仍产出角色列表，经
+  `fromRoleTurns` 机械折成轮。
+- grok 的 `synthetic_reason` 过滤：只迁缺省与显式 `human` 的用户行；
+  `compaction_meta` 中的摘要行转为压缩检查点。
+- Claude 旧格式（2.0.x）的 `summary` 记录是写在文件头的一行叶子标题，
+  按标题处理，不当作压缩边界。
+- Codex 的 `custom_tool_call` 输入是自由格式（patch、JS 片段），迁移时包成
+  `{"input": …}`，保证调用参数是 JSON。
+- zcode：没有带工具调用或 reasoning 的样本，只映射文本角色，不猜测字段。
+- 时间戳边界：grok 行内无逐条时间，会话起始时间取 `summary.json`。
+- 术语：迁移（migrate）指本功能；与「从 dsh-cc-tui 更名迁移」
+  （见[安装与快速开始](getting-started.md)）无关。
+
+实现与验证细节见 `src/dsh-adapter/migrate/`、
+`scripts/verify-migrate-parse.mjs`（逐源解析规则，合成 fixture）、
+`scripts/verify-migrate.mjs`（事件合成与官方读取链往返，含 wire 合法性与
+压缩检查点）与
+`scripts/verify-migrate-command.tsx`（挂真实 Chat 的 `/migrate` 交互回归）。

package/guide/dsh-tui-guide/plugins.en.md

@@ -0,0 +1,68 @@
+# Plugin Development Guide (merged into spec)
+
+[Documentation index](README.md) · [简体中文](plugins.md)
+
+> This document has been merged with the ecosystem admission specification:
+> [Plugin Admission and Development Guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+
+The ecosystem entry points and seam stability reference below are kept here
+for quick reference; the authoritative status and compatibility agreement
+live in the admission & development guide.
+
+## Ecosystem entry points
+
+- **Interface & compatibility agreement / Plugin development guide**:
+  [Terminal Interactive Ecosystem Plugin Admission and Development Guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+  (admission spec, seams, contracts, verification checklist).
+- **Organization**:
+  [dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem)
+  (home of community plugins and templates).
+- **Template repository**:
+  [plugin-template](https://github.com/dsh-tui-ecosystem/plugin-template)
+  (start from the template and ship a plugin in minutes).
+- **Reference implementation**: `dsh-working-activity` (live working-status
+  line with dual outlets: TUI prompt slot + `workingActivity` session
+  projection).
+
+## Seam stability reference
+
+An **informal** maturity grading to help plugin authors gauge investment;
+the authoritative status and compatibility agreement live in the
+[admission & development guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md):
+
+| Tier | Seams |
+| --- | --- |
+| Stable candidate (shape frozen; breaking changes go through a minor-version deprecation warning before removal) | VI settings sections · VIII full-screen scenes · X managed dialogs · XI status line · XII keyboard shortcuts · XIII entry renderers |
+| Experimental (may still shift with dsh-std / admission-spec evolution) | IX decision events · toast notifications (`ctx.tuiToast`, new) |
+| Upstream-tracked (stability owned by the cordis / dsh mechanisms underneath) | I session events · II official prompt slots · III bundled skills · IV themes · V system-prompt sections · VII profile composition |
+
+Also an experimental public surface:
+
+- `@deepseek-harness-tui/dsh-tui/api` (types-only entry).
+- The `@deepseek-harness-tui/dsh-tui/test-utils` subpath and
+  `ctx.tuiPluginHost.grants.corrupt` were removed in the adapter layering
+  refactor (#705).
+- `grants` is now the narrower `HostGrantFacade`; see that PR for migration
+  details.
+- On `TuiSceneProps.channel` (`ChannelUi`), `minimal` / `setMinimal()` were
+  renamed to `minimalUi` / `setMinimalUi()`; the old names stay as
+  **deprecated aliases** reading and writing the same Minimal UI switch, so
+  existing full-screen scene plugins keep working. That switch only trims
+  interface decoration and is unrelated to the kernel `minimal` agent preset
+  (极简模式).
+  **Removal condition (decidable): v0.13** — the rename and deprecated aliases
+  first ship in v0.12.0, leaving one released minor-version deprecation window.
+  At that cut, scan the scene-plugin consumption surface (this repo's `src/**`
+  re-exports and every plugin on the dsh-tui-ecosystem org that reaches the
+  port through `TuiSceneProps.channel`) for `.minimal` / `.setMinimal(`: zero
+  callers means both aliases and the `'setMinimal': 'mutate'` row in
+  `ui-policy.ts` are deleted in v0.13; any remaining caller is migrated within
+  that same release rather than postponing the removal again.
+
+- The core repository remains independent; community plugins live in their own
+  repos.
+- The organization only maintains the listing and admission rules — it does
+  not endorse or warrant the functionality, quality, or safety of community
+  plugins.
+- Plugin authors keep full ownership of their repositories and are responsible
+  for their maintenance and security.

package/guide/dsh-tui-guide/plugins.md

@@ -0,0 +1,56 @@
+# 插件开发指南（已并入 spec）
+
+[文档索引](README.md) · [English](plugins.en.md)
+
+> 本文档已与 dsh-ecosystem-spec 的准入规范整合，请阅读：
+> [终端交互生态插件准入与开发指南](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+
+以下生态入口与接缝稳定性分级仅为速览保留；正式状态与兼容性协定
+以准入与开发指南为准。
+
+## 生态入口
+
+- **接口与兼容性协定 / 插件开发指南**：
+  [终端交互生态插件准入与开发指南](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+  （准入规范、接缝、契约、验证清单）。
+- **生态组织**：
+  [dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem)
+  （社区插件与模板的家）。
+- **模板仓库**：
+  [plugin-template](https://github.com/dsh-tui-ecosystem/plugin-template)
+  （从模板起步，5 分钟出一个插件）。
+- **参考实现**：`dsh-working-activity`（实时工作状态行：TUI 槽位 +
+  `workingActivity` 会话投影双出口）。
+
+## 接缝稳定性参考
+
+按当前实现成熟度给出的**非正式**分级，帮助插件作者评估投入；正式
+状态与兼容性协定以[准入与开发指南](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)为准：
+
+| 分级 | 接缝 |
+| --- | --- |
+| 稳定候选（形态冻结；如有破坏性变更，先在次版本弃用告警再移除） | 六 设置区块 · 八 全屏场景 · 十 托管对话框 · 十一 状态行 · 十二 键盘快捷键 · 十三 条目渲染器 |
+| 实验性（仍可能随 dsh-std / 准入规范演进调整） | 九 决策事件 · toast 通知（`ctx.tuiToast`，新增） |
+| 跟随上游（稳定性由 cordis / dsh 官方机制决定） | 一 会话事件 · 二 官方 prompt 槽位 · 三 技能打包 · 四 主题 · 五 system prompt 段 · 七 profile 组合 |
+
+另：
+
+- `@deepseek-harness-tui/dsh-tui/api`（纯类型入口）为实验性公开面。
+- `@deepseek-harness-tui/dsh-tui/test-utils` 子路径与
+  `ctx.tuiPluginHost.grants.corrupt` 已随 adapter 分层重构（#705）移除。
+- `grants` 收窄为 `HostGrantFacade`，迁移细节见该 PR。
+- `TuiSceneProps.channel`（`ChannelUi`）上的 `minimal` / `setMinimal()` 已更名为
+  `minimalUi` / `setMinimalUi()`；旧名保留为 **deprecated 别名**，读写同一个
+  「极简界面」开关，既有全屏场景插件不受影响。该开关只精简界面装饰，与内核
+  Agent preset `minimal`（极简模式）无关。
+  **移除条件（可判定）：v0.13**——更名与弃用别名首次随 v0.12.0 发布，
+  因此先保留一个已发布的次版本弃用窗口。届时对场景插件消费面
+  （本仓库 `src/**` 的再导出，以及 dsh-tui-ecosystem 组织下经
+  `TuiSceneProps.channel` 取用该端口的插件）做一次 `.minimal` / `.setMinimal(`
+  扫描：零调用方即在 v0.13 删除这两个别名与 `ui-policy.ts` 里的
+  `'setMinimal': 'mutate'` 行；仍有调用方则在同一版本内完成迁移，不再顺延。
+
+核心仓库保持独立，社区插件各居其位。
+生态组织只维护收录与准入规则——不对社区插件的功能、质量或安全性
+作任何背书或担保。
+插件作者对自己的仓库保有完全所有权，并负责其维护与安全。

package/guide/dsh-tui-guide/themes.en.md

@@ -0,0 +1,192 @@
+# Themes
+
+[Documentation index](README.md) · [简体中文](themes.md)
+
+## Built-in themes
+
+dsh-TUI provides three Gentle Mist Blue palettes, plus an `auto` pseudo-theme:
+
+| Name | Purpose |
+| --- | --- |
+| `auto` | Pseudo-theme: follows the system/terminal background, resolving to `light` or `dark` |
+| `light` | White panels, ink body text, and mist-blue interaction color |
+| `dark` | Dark-terminal adaptation with warm-gray text and soft blue accents |
+| `dark-ansi` | Compatibility fallback using only the 16 ANSI colors |
+
+Without an explicit choice, the TUI queries the terminal background with OSC
+11 and selects `light` or `dark`. It falls back to `dark` when the terminal
+does not answer.
+
+Light-theme panels, tool cards, and image previews use white (`#FFFFFF`)
+surfaces by default; image previews use neutral borders. Dark palettes and
+accent colors are unchanged. This does not modify the terminal's own
+background or wallpaper.
+
+`auto` turns that one-shot startup detection into a standing choice:
+
+- A valid value for `/theme`, `DSH_TUI_THEME`, and `~/.dsh-tui/theme.json`.
+- Selecting `auto` applies the last detected base immediately and re-queries
+  OSC 11 in the background.
+- On terminals that follow the system theme, picking `auto` again (or
+  restarting) catches up after a system light/dark switch.
+- `/theme status` shows which palette `auto` currently resolves to.
+- `getTheme('auto')` serves that palette to every consumer.
+- A user theme named `auto` is shadowed by the built-in pseudo-theme (not
+  listed in the picker).
+
+Selection precedence is:
+
+```text
+DSH_TUI_THEME
+  > persisted choice in ~/.dsh-tui/theme.json
+  > OSC 11 background detection
+  > dark fallback
+```
+
+## Switching themes
+
+- `/theme` opens the picker, with `auto` and the built-ins before static JSON
+  and plugin themes.
+- `/theme <name>` switches directly to a static or runtime plugin theme.
+- `/theme status` shows the current theme and persistence location.
+
+Confirming a choice hot-switches immediately and writes it to
+`~/.dsh-tui/theme.json`. `DSH_TUI_THEME`, when set, still wins on the next
+launch.
+
+## Custom themes
+
+Place JSON files under `~/.dsh-tui/themes/`. Each file starts from one
+built-in palette and overrides a subset of its colors:
+
+```json
+{
+  "name": "sakura",
+  "displayName": "Sakura",
+  "base": "dark",
+  "colors": {
+    "accent": "#FF9EC7",
+    "accentShimmer": "#FFC0D5",
+    "activity": "#7DA1DE",
+    "activityShimmer": "#ABC2EC",
+    "mascotBody": "#D98A63",
+    "inputBackground": "#000000",
+    "permission": "#FFB3CC",
+    "promptBorder": "#B08B99",
+    "text": "#E8E6E0",
+    "inactive": "#A99BA0",
+    "subtle": "#8A7A80",
+    "selectionBg": "#5C3A44",
+    "success": "#9CC7A8",
+    "error": "#E08591",
+    "warning": "#E0C08A"
+  }
+}
+```
+
+Fields:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `base` | Yes | `light`, `dark`, or `dark-ansi`; source for every non-overridden color |
+| `colors` | Yes | Partial override of Theme color keys |
+| `name` | No | Theme ID; defaults to the filename |
+| `displayName` | No | Picker label; defaults to `name` |
+
+Available color keys by purpose:
+
+- Brand/focus/activity: `accent`, `accentShimmer`, `activity`, `activityShimmer`, `suggestion`, `remember`
+- Panels/borders: `permission`, `permissionShimmer`, `promptBorder`, `promptBorderShimmer`, `bashBorder`, `planMode`, `ide`, `background`
+- Body text: `text`, `inverseText`, `inactive`, `inactiveShimmer`, `subtle`
+- Tool names & status dots: `toolNameMutate`, `toolNameExec`, `toolDotExec`, `toolDotRead`, `toolDotWrite`, `toolDotWeb`, `toolDotTask`
+- Tool card surfaces: `toolCardBackground`, `toolCardBackgroundDim`
+- Status: `autoAccept`, `success`, `error`, `warning`, `warningShimmer`, `merged`
+- Diff: `diffAdded`, `diffRemoved`, `diffAddedDimmed`, `diffRemovedDimmed`, `diffAddedWord`, `diffRemovedWord`
+- Diff syntax highlighting: `syntaxKeyword`, `syntaxString`, `syntaxComment`, `syntaxNumber`, `syntaxFunction`, `syntaxType`
+- Diff syntax highlighting (cont.): `syntaxVariable`, `syntaxOperator`, `syntaxPunctuation`, `syntaxConstant`
+- Badges/accents: `mascotBody`, `inputBackground`, `professionalBlue`, `chromeYellow`
+- Messages & input: `userMessageBackground`, `userMessageBackgroundHover`, `messageActionsBackground`, `selectionBg`, `bashMessageBackgroundColor`
+- Messages & input (cont.): `memoryBackgroundColor`, `rate_limit_fill`, `rate_limit_empty`, `fastMode`, `fastModeShimmer`, `userPromptLabel`
+- Subagent messages: `subagentBullet`, `subagentDescription`, `subagentModel`, `subagentElapsed`, `subagentToolName`, `subagentStatusRunning`
+- Subagent messages (cont.): `subagentStatusCompleted`, `subagentStatusFailed`
+
+When the file declares `name`, its filename remains a loading alias. See the
+`Theme` type in [`src/theme.ts`](../src/theme.ts) for every color key.
+
+## npm plugin themes
+
+An npm plugin registers a runtime theme through the `tuiThemes` service,
+without writing to `~/.dsh-tui/themes/`. Minimal example:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+
+export function apply(ctx: Context): void {
+  ctx.get('tuiThemes', false)?.register({
+    name: 'my-plugin:night',
+    base: 'dark',
+    colors: { accent: '#88AAFF' },
+  }, ctx)
+}
+```
+
+- Use a lowercase safe ID such as `plugin-id:theme-id`.
+- `auto`, built-in names, and `status` are reserved.
+- Registrations are removed with the plugin activation; the returned disposer
+  can remove one early.
+- Plugin themes appear in the `/theme` picker and completion; their names use
+  the existing `~/.dsh-tui/theme.json` persistence.
+- Priority: built-ins > static JSON > same-name plugin theme.
+- On an older profile without `tuiThemes`, the plugin degrades silently and
+  static themes remain unaffected.
+
+See the [Plugin Admission and Development Guide](https://github.com/T-Auto/dsh-ecosystem-spec/blob/main/docs/plugin-admission-and-development.md)
+for the full key list, legacy-key mapping, and registration contract.
+
+## Color formats
+
+Accepted forms:
+
+- `#rgb`
+- `#rrggbb`
+- `#rrggbbaa`
+- `rgb(r,g,b)`
+- `ansi256(n)`
+- 16-color names such as `ansi:black` and `ansi:redBright`
+
+Colors must be concrete values. CSS variables, gradients, and arbitrary CSS
+color names are not accepted.
+
+## Validation and failure behavior
+
+- Unknown Theme key: skip that key with a warning and keep the rest.
+- Invalid color: skip that value with a warning.
+- Invalid `base`, malformed JSON, or non-object `colors`: skip the whole file.
+- Missing theme referenced by the environment or preference file: warn and
+  continue with background detection.
+- One bad theme never blocks TUI startup or other themes.
+
+Theme names are user input. The loader verifies that the resolved path
+remains inside `~/.dsh-tui/themes/`, preventing names from escaping the theme
+directory. Preserve that containment check when changing the implementation.
+
+## Design guidance
+
+- Use color keys instead of changing only `text` and `background`. Check at
+  least body, inactive, focus, selection, success, warning, error, and diff
+  colors.
+- Test light themes in a real light terminal and dark themes in a dark one.
+- Check 16-color, 256-color, and truecolor fallback behavior.
+- Verify narrow layouts, tool diffs, questionnaires, multiline input, and
+  selection contrast.
+- Theme files should contain display metadata and color only, never credentials
+  or other user data.
+
+When developing the theme subsystem, run:
+
+```sh
+node --import tsx/esm scripts/verify-themes.mjs
+```
+
+See [Architecture and limitations](architecture.en.md) for terminal capability
+and renderer details.