dsh-super-code 0.3.8 → 0.3.10

package/docs/UsageGuide.md

@@ -1,326 +1,321 @@
-# 使用 Super Code · Using Super Code
+# 使用说明
 
-[README 的三步说明](../README.md)适合第一次上手。这里补充模型设置、找不到预设时的处理方法，以及执行树和预设管理的细节。
+中文 · [English](en/UsageGuide.md)
 
-The [three steps in the README](../README.md) will get you started. This page covers model settings, missing presets, the Agent tree, and preset management in more detail.
+首次使用请先阅读 [README](../README.md) 的安装与使用部分。本文说明各项功能的细节。
 
-## 模型怎么选 · Choosing a Model
+- [模型](#模型)
+- [找不到预设](#找不到预设)
+- [设置页](#设置页)
+- [预设版本与重装](#预设版本与重装)
+- [侧边栏](#侧边栏)
+- [批量工具调用](#批量工具调用)
+- [运行预算](#运行预算)
+- [Windows 命令环境](#windows-命令环境)
+- [删除保护](#删除保护)
+- [MCP 连接](#mcp-连接)
+- [前端 Skill](#前端-skill)
 
-已有可用模型时，不用为插件再配一遍。如果还没设置，在 Harness“设置”→“模型”添加提供方，再从对话输入框下方选择模型和推理等级。Super Code 跟随当前会话的选择，不另设模型池；子 Agent 默认继承父 Agent 的模型，权限和工具也由 Harness 管理。
+## 模型
 
-If you already have a working model, there is nothing extra to configure for the plugin. Otherwise, add a provider under Harness “Settings” → “Models”, then choose a model and reasoning effort below the message input. Super Code uses the current session's choice rather than a separate model pool. Child Agents inherit the parent Agent's model by default, while Harness manages permissions and tools.
+插件不单独配置模型。已有可用模型时直接使用；若没有，请在 Harness「设置 → 模型」中添加提供方，再在输入框下方选择模型和推理等级。
 
-## 批量工具调用 · Batched Tool Calls
+子 Agent 默认使用父 Agent 的模型。权限和工具由 Harness 管理。
 
-0.3.0 的 Super Code 预设使用 Harness 原生 PTC。Agent 可以在一次模型调用里组合几个工具操作，例如同时读取互不依赖的文件，拿到结果后再决定下一步。它不需要额外的 Agent，也不用另选模式。
+## 找不到预设
 
-The Super Code preset in 0.3.0 uses Harness-native PTC. An Agent can compose several tool operations in one model call—for example, read independent files together before deciding what to do next. It needs neither an extra Agent nor a separate mode selection.
+请先确认插件已启用，再对照[兼容性](Compatibility.md)核实宿主版本，然后按宿主版本处理：
 
-默认指导要求独立读取按需并行，写入、测试、状态变更和依赖步骤依次执行；失败时保留已成功的结果，只重试失败或过期的读取。插件向宿主声明任务和记忆工具中哪些动作可以并行，未知动作默认独占。其他工具是否允许并行，由它们在 Harness 中的声明决定。权限确认、取消、结果保存和部分失败都由宿主管理。
+**Harness 0.1.7 及以后（声明式预设）**：预设由插件声明、宿主加载。请在「设置 → Super Code 模式」中点击「安装预设」。宿主未开放管理接口时，页面会直接提示。
 
-The default guidance calls for parallel reads when useful, ordered writes, tests, state changes, and dependent steps, and retries limited to failed or stale reads while retaining successful results. The plugin declares which task and memory actions are safe to overlap; unknown actions remain exclusive. Other tools use their own Harness concurrency declarations. Harness handles permissions, cancellation, result persistence, and partial failures.
+**Harness 0.1.5 / 0.1.6（目录预设）**：插件首次加载时会自动安装一份用户预设。若未出现，请在「设置 → Super Code 模式」中手动安装。
 
-批量调用减少的是模型与工具之间的来回，不保证每项操作都会更快，也不改变模型、权限或记忆的设置。
+- 默认标识符 `super-code` 被占用时，可改用其他标识符，原有预设不会被覆盖。
+- 主动删除该副本后，重启不会自动重新安装，需要再次手动安装。
 
-Batching reduces round trips between the model and tools. It does not guarantee that every operation runs faster or change model, permission, or memory settings.
+插件 0.2.0 以前，设置入口位于「插件 → 插件配置」。
 
-## 任务状态 · Task Status
+## 设置页
 
-Super Code 侧边栏依次显示“任务状态”“协作执行”“记忆库”。任务状态默认展开，三项互斥且始终保留一项展开；原圆圈 Agent 执行树保留在“协作执行”中。每个 Agent 的任务树根节点显示其名字，步骤、动作、文件条目不重复标注名字。
+「设置 → Super Code 模式」包含五个标签页：
 
-The Super Code sidebar contains Task status, Agent execution, and Memory library in that order. Task status opens by default; exactly one section stays open. The original circular Agent graph remains under Agent execution. Each Agent's name appears at its task-tree root only.
+| 标签页 | 内容 |
+|---|---|
+| 首页 | 预设状态与版本、删除保护等级、MCP 开关、在线与历史对话数 |
+| 预设配置 | 安装、重装、重命名、Windows 命令环境 |
+| 上下文配置 | [运行预算](#运行预算) |
+| 删除保护 | [删除保护](#删除保护) |
+| 连接 | [MCP 连接](#mcp-连接) |
 
-任务状态只读取已有会话记录：目标取已有任务/目标记录，缺少时展示用户原文；步骤取模型已经写入的待办，进度显示已完成数/总数；动作与结果取工具日志。运行结束不会被当作任务完成。没有步骤时不会补造计划、百分比或阶段说明。
+切换标签页不会丢失未保存的输入。
 
-This view reads existing journal facts: recorded objectives or the user's original request, existing todos and their completed/total counts, and tool activity and results. A stopped run is not treated as a completed objective. Missing plans or progress are not invented.
+### 名称与语言
 
-任务、步骤、已加载动作和补充要求都直接展开，不需要逐项点击。任务状态使用单一虚拟滚动列表，只渲染视口附近的行；长文本按实际高度显示，滚动即可查看所有已加载记录和文件，无需点击“更多”。切换侧栏区块后保留阅读位置。运行环遵循系统的“减少动态效果”设置。
+- 标识符用于选择预设；显示名称可单独修改，支持中文和空格，最多 120 字。
+- 默认名称和描述跟随 Harness 的中英文设置。用户修改过的字段，插件不会改动。
+- 切换语言只影响显示字段，不改变预设内容和版本。
+- 旧版 Harness 会缓存预设列表，因此文案变化后页面会自动刷新一次。
+- 同一宿主的预设文件只能使用一种语言，多个客户端无法同时显示不同语言。
+- 安装目录只读或 YAML 无法安全识别时可能同步失败，可在设置页刷新后重试。
 
-Tasks, steps, loaded activity, and follow-up requests are fully expanded. One virtualized list renders rows near the viewport and measures wrapped text at its actual height. Scroll through every loaded record and file without a More button. Switching sections retains the reading position, and running indicators respect reduced-motion preferences.
+## 预设版本与重装
 
-文件变更记录列出已成功执行并能从工具参数或结果 diff 元数据确认的文件操作，包含普通和 PTC 嵌套调用。它不是当前工作区的完整 Git diff：终端或外部脚本的间接修改可能缺失，历史操作也不代表文件当前仍有净修改。未完成、失败、只读操作及子 Agent 继承的历史不会被计作本次成功修改。
+设置页分别显示**插件版本**和**预设版本**。
 
-File operations show successful mutations identifiable from tool arguments or result diff metadata, including native and nested PTC calls. This is not a complete current Git diff: indirect terminal/script changes may be absent, and historical operations do not establish a current net change. Pending, failed, read-only, and fork-inherited operations are not counted as that Agent's successful changes.
+- 两者一致：表示预设与已安装的插件同步，不代表 npm 上没有更新版本。
+- 旧预设未记录版本：显示「未记录版本」，不视为最新。
+- 插件升级不会自动更新已安装的预设。如需使用新预设，请重新安装。
 
-此功能不增加提示词、模型请求、工具定义或执行钩子，也不向模型上下文写入界面内容；不要求使用特定模型、预设、Skill 或固定步骤。未知工具仍显示其调用与结果，缺少结构化记录时只减少相应展示，不影响模型继续工作。记录有显示上限，未加载或超出范围时会提示；完整执行内容可打开详情查看。
+**重装流程**：点击「重新安装预设」→ 确认框列出将被替换的预设及新名称、标识符 → 核对后确认。
 
-This feature adds no instructions, model requests, tool definitions, or execution hooks, and never writes display data into model context. It requires no specific model, preset, Skill, or workflow. Unknown tools retain their activity and results; absent structured facts reduce the displayed detail only. Bounded or unloaded records are labeled, with full execution content available in details.
+- 可从列表中移除条目，但不能在列表清空后确认。取消或按 Esc 不会产生任何改动。
+- 重装会覆盖旧预设内容，请先自行备份自定义内容。
+- 已有会话继续使用旧预设，新会话使用新预设。
 
-## 删除保护 · Deletion Protection
+**安全措施**：
 
-“上下文配置”中的“删除保护”支持三种模式，**默认宽松**。
+- 只替换能够核实由本插件安装的预设（目录式核对安装记录、UUID、路径和目录身份；声明式核对来源标记或安装记录）。未标记的旧副本和同名声明不会被改动。
+- 旧内容备份在 `.super-code-backup-*`：目录式位于用户预设根目录下，声明式位于当前 profile 下（安装记录为 `.super-code-presets.json`）。
+- 安装失败时自动恢复；进程意外中断时，可从备份手动恢复。
 
-| 模式 / Mode | 行为 / Behavior |
-| --- | --- |
-| 关闭 / Off | 不添加删除保护提示，不额外拦截命令。No deletion instructions or extra command interception. |
-| 宽松 / Relaxed（默认 / default） | 默认使用 `trash`，脚本中也建议使用；用户明确要求时可使用 `rm`，无需本插件额外二次确认。Prefer recoverable trash, including in scripts; explicit user requests may use `rm` without additional plugin confirmation. |
-| 严格 / Strict | 脚本也禁止直接使用 `rm`；识别到永久删除命令时，仅临时文件或构建产物清理可经用户逐次二次确认放行。Scripts must also avoid `rm`; recognized permanent deletion requires one-time confirmation for each temporary-file or build-artifact cleanup. |
+## 侧边栏
 
-宽松模式保留指令：**删除文件或目录默认用 `trash <path>`（可恢复）；仅清理临时文件、构建产物且我已确认时才用 `rm`。** 脚本、内联脚本和间接调用中也建议使用回收站。用户明确说明使用 `rm` 时，该要求可作为确认，并按用户指定范围执行；宽松依靠指令引导，不增加命令拦截，宿主原有权限检查仍然有效。
+在右侧边栏选择「Super Code」，三个部分互斥展开，默认展开任务；点击当前标题可全部收起。切换后保留阅读位置、筛选条件和草稿。界面跟随 Harness 的中英文设置。
 
-Relaxed mode instructs Agents to use recoverable `trash <path>` by default and prefer it in scripts and indirect calls. An explicit request to use `rm` counts as confirmation within the requested scope. Guidance is prompt-based; host permission checks still apply.
+### 任务
 
-默认只保护 Super Code。“同时应用到官方预设”开关默认关闭，与预算的同名开关独立；开启后，所选模式也应用到标准、PTC、极简、创造预设。关闭模式时保留此开关的选择。保存后作用于后续命令。旧配置 `true` 保留为严格，`false` 保留为关闭；缺省配置及恢复默认使用宽松。
+只读，展示会话中已有的记录：
 
-Only Super Code is protected by default. “Also apply to official presets” defaults off, independently of official-preset budgets, and applies the chosen mode to Standard, PTC, Minimal, and Create. Off retains this preference. Saved changes affect subsequent calls. Legacy `true` maps to Strict and `false` to Off; missing settings and reset use Relaxed.
+- **目标**：已记录的任务目标；未记录时显示用户原话。
+- **步骤**：模型记录的待办事项，显示「已完成/总数」。没有步骤时不会生成计划或进度。
+- **工具调用**：按工具汇总成功、失败与运行状态。
+- **文件**：已成功执行、且能从工具参数或 diff 确认的文件改动，包括 PTC 中的嵌套调用。
 
-极简预设通过可记录、可回放的插件消息接收规则，模式变化时明确替代先前规则，兼容 v4 会话日志。
+注意事项：
 
-Minimal receives rules through logged, replayable plugin messages compatible with v4 session logs; mode changes explicitly replace earlier rules.
+- 运行停止不等于任务完成。
+- 文件列表并非完整的 Git diff：终端或外部脚本造成的间接修改可能未被记录；历史改动也不代表文件当前仍有差异。失败、未完成、只读操作以及子 Agent 继承的历史均不计入。
+- 列表全部展开并采用虚拟滚动，长列表也能流畅显示。超出显示上限时会提示，完整内容可在详情中查看。
+- 不修改提示词、模型请求或工具定义，也不向模型上下文写入内容。
 
-严格模式在终端执行前识别 `rm`、常见包装、内联 shell 脚本及 PowerShell 删除别名（如 `Remove-Item`），PTC 内的终端调用也适用。宿主对当前命令和工作目录请求一次性确认；拒绝、取消、确认不可用或出错均拦截。此确认不授予后续调用权限，也不代替宿主其他权限检查。缺少 `trash` 时应使用其他可恢复方式或停止。
+### 协作执行
 
-Strict mode checks terminal calls, including those nested in PTC, for `rm`, common wrappers, inline shell scripts, and PowerShell deletion aliases such as `Remove-Item`. Only a real one-time host approval for the current command and working directory proceeds. Rejection, cancellation, unavailable approval, and errors block execution. If trash is unavailable, use another recoverable mechanism or stop.
+Agent 执行树，显示每个 Agent 的状态、用量和缓存率。
 
-严格模式的命令识别并非操作系统沙箱：不解析外部脚本文件或任意混淆程序，不覆盖所有语言的文件删除 API；脚本仍须遵守指令，需要进程级隔离时继续使用宿主沙箱。
+- 拖动空白处可平移，使用滚轮或按钮可缩放。
+- 点击节点会在侧边栏新标签页中打开详情，主对话不切换。
+- 详情按对话展示：用户任务、Agent 回复、可展开的工具调用及结果。顶部显示状态、Token 和缓存，展开「详情」可查看更多用量、任务记录和记忆使用记录。
+- 运行动画遵循系统的「减少动态效果」设置。
 
-Strict command recognition is not an OS sandbox: it does not inspect external script files, arbitrary obfuscated programs, or every language's deletion API. Scripts must follow the instructions; use the host sandbox for process-level isolation.
+[任务](images/task-status.png)和[执行树截图](images/agent-tree.png)使用当前插件、官方前端组件及演示数据渲染，仅展示界面，不代表模型效果。
 
-## 运行预算 · Runtime Budgets
+### 记忆库
 
-打开设置中的“Super Code 模式”（部分版本位于“插件”→“插件配置”）。顶部“预设状态”用于查看和安装预设；“上下文配置”用于调整预算。插件默认已使用此前 Pro 测试中的旧预算，无需手动填写。界面使用百分数和秒；括号内仍显示当前宿主的默认值，便于与输入框中的实际配置比较。
+先选择「当前项目」或「全局偏好」，再按主题浏览或搜索（主题、摘要、标识符），点击条目可查看详情和来源。支持新增、编辑和删除（需确认）。手动修改的条目标记为「手动维护」，只保留当前内容，不保留版本历史。
 
-Open “Super Code” in Settings (under “Plugins” → “Plugin configuration” in some versions). “Preset status” shows and installs the preset; “Context settings” contains the budgets. The plugin already uses the older Pro-test budgets without manual setup. The form uses percentages and seconds; parentheses still show the current host defaults for comparison with the effective values in the inputs.
+记忆分为三层：
 
-| 类型 / Type | 配置 / Settings | 生效范围 / Applies to |
+| 层级 | 内容 | 范围 |
 |---|---|---|
-| 通用预算 / Common budgets | 压缩比例、摘要上限、PTC 时限及重试次数 / Compression ratios, summary limit, PTC deadlines, and retries | 默认仅 Super Code；打开“同时应用到官方预设”后，也用于标准、PTC、极简、创造模式 / Super Code by default; also Standard, PTC, Minimal, and Create when “Also apply to official presets” is enabled |
-| Super Code 专属预算 / Super Code budgets | 活跃任务记录上限、任务记忆上下文容量 / Active task record limit and task-memory context capacity | 始终仅 Super Code / Always Super Code only |
-
-官方预设开关默认关闭，不影响自定义预设；开启后也只修改通用预算，不改变官方预设的工具和提示词。修改保存后对新建 Agent 生效，运行中的 Agent 保留原配置。切换顶部标签不会丢失尚未保存的输入。
-
-The official-preset switch is off by default and leaves custom presets untouched. When enabled, it changes only common budgets, preserving official tools and prompts. Saved changes apply to new Agents; running Agents keep their configuration. Switching tabs retains unsaved input.
-
-留空沿用插件默认预算；“恢复默认”会清除界面的覆盖，回到插件加载配置，未配置的字段使用旧预算。用户已保存的配置优先生效。保存失败时保留输入，若提示预算已在别处修改，先重新读取再调整。
-
-Leave fields blank to inherit plugin defaults. “Reset to defaults” clears UI overrides and restores the plugin configuration, using the older budgets for unconfigured fields. Saved user values take precedence. Failed saves retain your input. If budgets changed elsewhere, reload before editing again.
-
-也可以通过插件的 `budgets` 配置调整通用预算；将 `applyToOfficialPresets` 设为 `true` 可同时应用到上述四种官方预设。保存预算不会重启 Agent。
-
-You can also set common budgets in the plugin's `budgets` configuration. Set `applyToOfficialPresets: true` to include the four official presets above. Saving budgets does not restart Agents.
-
-旧宿主未提供 `ptcRuntime` 时，“批量工具执行”的时限输入框会禁用；压缩预算和任务记忆容量仍可设置。
-
-On older hosts without `ptcRuntime`, batch-tool deadline inputs are disabled; compression and task-memory budgets remain configurable.
-
-下面是插件已默认使用的旧预算，无需再将它手动添加到 `name: dsh-super-code` 的加载配置中。需要自定义时，可以在界面或加载项的 `config.budgets` 中修改对应字段。
-
-The plugin already uses these older budgets by default; there is no need to add them manually to the `dsh-super-code` entry. Customize individual fields in the UI or the entry's `config.budgets` when needed.
-
-```yaml
-budgets:
-  pressureBasis: window
-  thresholdRatio: 0.8
-  retainRatio: 0.16
-  summaryMaxTokens: 8192
-  compactionRetries: 1
-  maxOverflowRetries: 1
-  ptcTimeoutMs: 600000
-  ptcMaxTimeoutMs: 600000
-```
-
-`pressureBasis: window` 为插件默认，按完整上下文窗口计算；选择 `host` 则按当前宿主策略计算。`retainRatio` 必须小于 `thresholdRatio`。PTC 两项的单位是毫秒，包含工具等待时间；显式更短的调用期限仍然生效，上限不会超过宿主允许值。PTC 时间覆盖需要提供 `ptcRuntime` 的新版宿主；旧版的 CPU 忙碌计时与新版总耗时计时不能等同。这些配置不改变执行后端、权限或取消行为。
-
-`pressureBasis: window` is the plugin default and uses the full context window; choose `host` to follow the current host budget policy. `retainRatio` must be lower than `thresholdRatio`. PTC values are milliseconds, including tool waits; explicit shorter call deadlines still apply, and the host ceiling remains authoritative. PTC overrides require a newer host with `ptcRuntime`. The old busy-CPU timer and the new elapsed timer are different. These settings preserve the host execution backend, permissions, and cancellation.
-
-Super Code 专属的 `maxTasks`（默认 32）和 `maxContextBytes`（默认 32,768），分别控制会话中活跃任务记录数量和任务记忆上下文的字节预算。增加预算会占用更多上下文；通常保持默认即可。
-
-Super Code also has `maxTasks` (default 32) and `maxContextBytes` (default 32,768), which bound the active task records and task-memory context bytes per conversation. Larger budgets use more context; the defaults are usually sufficient.
-
-## 找不到预设 · Can't Find the Preset?
-
-先确认插件已启用，并按[兼容矩阵](Compatibility.md)核对宿主版本与实际依赖。插件按宿主提供的预设机制选择以下两条路径。
-
-First confirm the plugin is enabled and check the host version and installed dependencies against the [compatibility matrix](Compatibility.md). The plugin uses the preset mechanism provided by the host.
-
-### Harness 0.1.7 / 0.2.0 / 0.2.1：声明式预设 · Declarative Presets
-
-Super Code 由插件 bundle 声明，宿主负责加载。从 0.3.1 起，未安装时可以在“设置”→ **Super Code** 安装预设；已安装时提供“重新安装预设”，确认后按所填名称和标识符替换。声明保存在当前 profile 的补丁层，通过宿主公开接口加载，不需要用户预设目录。宿主未开放管理接口时，页面会明确提示。
-
-The plugin bundle declares Super Code and the host loads it. From 0.3.1, use “Settings” → **Super Code** to install a missing preset or confirm reinstallation of an installed preset with the entered name and identifier. Declarations persist in the current profile's patch layer and load through public host APIs; no user preset directory is needed. Hosts without management APIs show an explicit notice.
-
-声明式预设的默认名称和描述从 0.3.1 起跟随中英文设置，已自定义的字段保留。语言变化只调整展示字段，不更新旧预设的内容或版本；确认重装才使用当前插件随包的组合。
-
-From 0.3.1, default declarative preset names and descriptions follow Chinese/English settings while custom fields remain intact. Language changes update display fields only, retaining the older preset's content and version. Confirmed reinstallation uses the composition shipped with the current plugin.
-
-插件管理中的展示信息独立于预设声明：0.2.1 通过导出的语言资源提供 `Super Code 模式` / `Super Code` 和对应描述，支持新版宿主读取根路径及子路径的展示信息。
-
-Plugin management metadata is separate from the preset declaration. Version 0.2.1 exports locale resources for `Super Code 模式` / `Super Code` and their descriptions, allowing newer hosts to read metadata for the root and plugin subpaths.
+| 任务状态 | 当前目标、约束、进展、验证记录 | 当前会话 |
+| 项目记忆 | 有来源的项目事实、经验和约定 | 同一工作区路径，按主题划分 |
+| 全局偏好 | 用户明确要求跨项目遵守的偏好 | 同一 Harness 存储目录 |
 
-### Harness 0.1.5/0.1.6：目录预设 · Directory Presets
+- 如需长期保留某项约定，可直接告知 Agent。是否保存成功，以工具返回成功且记忆库中可见为准。
+- Agent 保存项目记忆时必须关联真实的工具结果；保存全局偏好时必须有用户原话和跨项目意图。
+- 不同路径的项目或 Git worktree 不共享项目记忆。
+- 记忆保存在本机宿主中，不写入项目文件，也不会整库发送给模型。每次最多自动带入当前主题的 4 条摘要（≤2 KiB）和全局偏好的 4 条摘要（≤1 KiB），详情需由 Agent 主动读取。
+- 记忆不能覆盖当前指令，不能用于授权，也不能证明代码仍与记录时一致。
+- 历史会话的记忆可直接查看，无需恢复 Agent 或调用模型。
 
-如果 Harness 没发现插件自带的 `super-code`，插件首次加载时会尝试安装一份用户预设。仍然没看到时，打开“设置”→ **Super Code**，查看状态并手动安装；0.3.1 起此页始终展开。默认标识符 `super-code` 若已被占用，换一个即可；原有预设不会被覆盖。之后若主动删除这份用户副本，重启也不会自动重装，需要再次手动安装。0.2.0 以前的插件设置入口在“插件”→“插件配置”中。
+### Agent 的记忆使用记录
 
-If Harness doesn't find the bundled `super-code` preset, the plugin tries to install a user copy on first load. If it still isn't listed, open “Settings” → **Super Code** to check its status or install it manually; this page stays expanded from 0.3.1 onward. If the default identifier `super-code` is taken, choose another; the existing preset won't be overwritten. If you later delete this copy, a restart won't reinstall it automatically. Plugin versions before 0.2.0 place this page under “Plugins” → “Plugin configuration”.
+在执行树中点击节点 → 展开「详情」→ 展开「记忆使用记录」。记录区分带入上下文、读取摘要、读取详情、保存和删除，点击记录可跳转到记忆库中的对应条目。
 
-## 查看预设版本 · Checking the Preset Version
+- 这是宿主记录的动作，不代表模型已理解或遵守。
+- 子 Agent 继承的父会话历史不计为其自身的读取；失败的调用不计为成功读取。
+- 最多显示最近 100 条，完整记录见会话日志。
+- 条目之后被修改或删除时，记录仍保留，但记忆库只显示当前内容。
 
-0.3.1 起，“设置”→ **Super Code** 分别显示已加载的插件版本和当前预设版本。预设版本来自实际加载的预设组合；两者一致时表示预设与当前安装的插件同步，不代表 npm 上没有更新版本。旧预设没有版本记录时，会显示“未记录版本”，不会自动视为最新版。修改名称或切换语言不改变预设版本。
+## 批量工具调用
 
-From 0.3.1 onward, “Settings” → **Super Code** shows the loaded plugin version and the current preset version separately. The preset version comes from its actual composition. Matching versions mean the preset is in sync with the installed plugin, not that no newer npm release exists. Older presets without version metadata show “Version not recorded”. Renaming a preset or changing the language does not change its version.
+Super Code 使用 Harness 原生 PTC：在一次模型调用中组合多个工具操作，例如同时读取多个互不相关的文件，获得结果后再决定下一步。无需另选模式。
 
-若版本不一致，先保留需要的自定义内容，再通过确认清单重装。目录式宿主替换用户副本，声明式宿主替换本插件拥有的声明，均保留恢复备份。重装后刷新仍不一致时，检查插件更新是否生效及宿主日志。
+- 相互独立的读取并行执行；写入、测试、状态变更和存在依赖的步骤按顺序执行。
+- 部分失败时保留成功的结果，只重试失败或过期的读取。
+- 插件声明自身任务和记忆工具中可并行的动作，未识别的动作默认不并行。其他工具以其在 Harness 中的声明为准。
+- 权限确认、取消和结果保存由宿主管理。
 
-If versions differ, save the custom content you need, then confirm reinstallation. Directory hosts replace the user copy; declarative hosts replace this plugin's owned declaration. Both retain recovery backups. If refreshed versions still differ, check that the plugin update took effect and inspect host logs.
+批量调用减少的是模型与工具之间的往返次数，不保证每个操作都更快。
 
-## 内嵌前端 Skill · Bundled Frontend Skill
+## 运行预算
 
-插件携带 `super-code-frontend`，用于页面/组件开发、视觉调整、响应式布局、交互状态和浏览器验证。特别覆盖共同对齐轴、视觉与点击边界、控制位置稳定、操作距离和输入负担；通过空间关系与实际命中检查定位错位和难操作的问题，沿用产品自己的视觉语言。宿主向模型提供名称与短描述，匹配任务时由原生 `skill` 工具按需加载入口；视觉设计、状态交互和浏览器验证的参考文件再按需读取。也可以在请求中明确指定使用 `super-code-frontend`。它不依赖固定框架或新增工具，不把全文加入每轮提示。
+位于「上下文配置」标签页。插件默认已使用效果更好的旧预算，通常无需修改。括号内显示宿主自身的默认值，便于对比。
 
-The plugin includes `super-code-frontend` for pages/components, visual refinement, responsive layout, interaction states, and browser validation. Guidance covers shared alignment anchors, painted and interactive boundaries, stable control positions, reach, and input effort. Geometry and real hit-area checks help diagnose misalignment and awkward interaction within the product's own visual language. Harness exposes its name and short description; the native `skill` tool loads the entry point when applicable, followed by only the references needed. You can explicitly ask to use `super-code-frontend`. It requires no particular framework or added tools and does not insert its full text into every turn.
-
-从 0.3.3 起，新安装或重装的 Super Code 预设包含此接入。已有用户副本或自定义声明需要先保留自己的调整，再通过“设置”→ **Super Code** 的重装流程更新；插件升级不会自动更新旧预设，设置页会显示其原有版本并提示差异。没有自动改写现有预设，也没有安装到全局 skills 目录。项目/用户同名 skill 仍按宿主原有优先级覆盖内置版本。
-
-From 0.3.3 onward, newly installed or reinstalled Super Code presets include this integration. Existing user copies or custom declarations need reinstallation through “Settings” → **Super Code** after saving any customizations. Updating the plugin preserves the old preset version, and Settings flags any mismatch. Existing presets and global skill directories are not rewritten automatically. Project/user skills with the same name retain their normal host precedence.
-
-浏览器验证方法会指导 Agent 复用可用会话，保留已完成步骤，并从实际失败阶段恢复。它是方法指导；本身不实现强制防循环，也不会自动写入长期记忆。是否提升前端成品质量需要单独的实际任务评测，不能用安装测试或 SWE 成绩代替。
-
-Browser guidance reuses working sessions and confirmed progress, recovering at the actual failed stage. It is workflow guidance, with no enforced loop detector or automatic long-term memory writes. Frontend quality improvements require separate real-task evaluation; installation checks or SWE scores do not establish them.
-
-## 名称与语言 · Names and Language
-
-0.3.1 的名称同步和自定义安装名称同时支持目录式与声明式预设。
-
-Version 0.3.1 supports display-language synchronization and custom installation names for directory and declarative presets.
-
-标识符和显示名称是两回事：标识符用于选择预设，显示名称可以单独修改。默认名称会跟随 Harness 的中英文语言设置；自定义名称可以包含中文和空格，例如 `Super Code 模式`，最多 120 个字符。插件只更新仍保持默认值的名称和描述，不会改动你的自定义内容。
-
-The identifier selects the preset, while its display name can be changed separately. The default name follows Harness's Chinese/English language setting. Custom names can include Chinese characters and spaces, such as `Super Code 模式`, up to 120 characters. The plugin updates a name or description only while it still has the default value; your custom text stays as it is.
-
-旧版 Harness 会缓存预设列表，因此文案改变后页面会自动刷新一次，没有变化就不会刷新。同一宿主的预设文件共用一种展示语言，多个客户端不能同时显示不同语言的预设名称。只读安装目录或无法安全识别的 YAML 可能导致同步失败；可以在插件配置中刷新重试。
-
-Older Harness versions cache the preset list, so the page refreshes once if the wording changes, but not otherwise. Preset files on one host share one display language: multiple clients can't show preset names in different languages at the same time. A read-only installation directory or YAML the plugin can't safely recognize may prevent synchronization; retry from the plugin configuration.
-
-## 重装与备份 · Reinstallation and Backup
-
-目录副本与声明式预设均支持此流程；插件只替换能够核实归属的预设。
-
-This workflow supports directory copies and declarative presets. The plugin replaces only presets whose ownership can be verified.
-
-已安装用户预设时，可以点“重新安装预设”。确认框会列出将被替换的预设及新名称、标识符，先核对再确认。可以从列表中移除条目，但全部移除后不能确认；取消或按 Escape 不会改动预设。重装会重置旧副本的内容，所以自定义内容请先自行留存。
-
-If a user preset is already installed, you can choose “Reinstall preset”. The confirmation dialog shows which preset will be replaced, along with its new name and identifier. Check the list before confirming. You can remove entries, but can't confirm an empty list; Cancel or Escape leaves everything unchanged. Reinstallation resets the old copy's contents, so save any custom changes you want to keep.
-
-为避免误删，插件只会替换安装记录、目录内 UUID、路径及目录身份都能核对上的副本，不会自动删除旧版无标记副本。重装前的目录会保留在用户预设根目录的 `.super-code-backup-*/<旧标识符>` 下，且不会出现在预设列表中。安装失败时会自动恢复旧目录；若进程意外中断，也可从备份手动恢复。
-
-To avoid removing the wrong files, the plugin replaces only copies whose installation record, UUID, path, and directory identity all match. It never automatically deletes unmarked legacy copies. The previous directory stays under `.super-code-backup-*/<old-id>` in the user preset root and won't appear in the preset list. An installation failure restores the old directory; after an unexpected interruption, you can recover it manually from the backup.
-
-声明式宿主通过 bundle 来源标记，或匹配的安装记录、声明标识符和 UUID 核实归属；同名的无标记声明不会自动认领。旧声明及原 profile 补丁保存在当前 profile 的 `.super-code-backup-*` 中，安装记录位于 `.super-code-presets.json`。失败时尝试恢复原补丁和记录；若进程中断，可从备份恢复。已有会话继续使用宿主保留的旧预设组合，新会话使用重装后的版本。
-
-Declarative hosts verify a bundle source marker or matching installation record, entry identity and UUID. Unmarked same-name declarations are not adopted automatically. The previous declaration and profile patch stay in `.super-code-backup-*` under the current profile; `.super-code-presets.json` stores ownership records. Failures attempt to restore the original patch and record; backups allow recovery after interruption. Existing sessions retain their old composition through the host; new sessions use the reinstalled version.
-
-## Agent 执行树 · Agent Execution Tree
+| 类型 | 包含 | 作用范围 |
+|---|---|---|
+| 通用预算 | 压缩比例、摘要上限、PTC 时限、重试次数 | 默认仅 Super Code；开启「同时应用到官方预设」后也作用于标准、PTC、极简和创造预设 |
+| Super Code 专属 | 活跃任务记录上限、任务记忆容量 | 仅 Super Code |
 
-打开右侧栏，选择“Super Code”，同一页面包含执行树和记忆库，默认展开执行树。点击任一区域的标题切换展开内容；两者互斥，始终保持一个展开，切换后保留阅读位置、筛选和编辑草稿。执行树显示当前会话中各 Agent 的状态、用量和缓存率。拖动空白处平移，滚轮或按钮缩放；点一个节点，就能在侧栏新标签查看详情，主对话不会切换。界面跟随 Harness 的中英文语言设置。
+- 「同时应用到官方预设」默认关闭，只修改预算，不修改官方预设的工具和提示词，也不影响自定义预设。
+- 保存后对新建的 Agent 生效，运行中的 Agent 不受影响，也不会重启。
+- 留空即使用插件默认值；「恢复默认」会清除界面上的覆盖值。
+- 保存失败时保留输入；若提示预算已在别处修改，请先重新读取。
+- 旧宿主没有 `ptcRuntime` 时，PTC 时限输入框不可用，其他预算仍可设置。
 
-Open the right sidebar and choose “Super Code” for the Agent tree and memory library on one page. The tree is expanded by default. Click either section heading to switch; exactly one section stays expanded, while reading positions, filters, and edit drafts are retained. The tree shows status, usage, and cache hit rate for each Agent in the current session. Drag empty space to pan, zoom with the wheel or buttons, and click a node to open its details in a new sidebar tab. The main conversation stays put. The interface follows Harness's Chinese/English language setting.
+插件默认值如下（无需手动写入配置，仅填写需要修改的项）：
 
-[执行树截图](images/agent-tree.png)来自安装 0.3.2 包的隔离 Harness 网页宿主，展示主 Agent 和记忆读取子 Agent 的真实会话记录。模型响应由本地确定性验收程序提供，用于检查界面与记忆功能，不代表外部模型效果或评测成绩。
+```yaml
+budgets:
+  pressureBasis: window      # 按完整上下文窗口计算；host 表示沿用宿主策略
+  thresholdRatio: 0.8        # 用量达到 80% 时开始压缩
+  retainRatio: 0.16          # 保留最近 16% 的原文，必须小于 thresholdRatio
+  summaryMaxTokens: 8192     # 摘要上限
+  compactionRetries: 1       # 压缩追加尝试次数
+  maxOverflowRetries: 1      # 溢出重试次数
+  ptcTimeoutMs: 600000       # PTC 默认时限（毫秒，含工具等待）
+  ptcMaxTimeoutMs: 600000    # PTC 时限上限，不超过宿主上限
+applyToOfficialPresets: false
+maxTasks: 32                 # Super Code：活跃任务记录数
+maxContextBytes: 32768       # Super Code：任务记忆上下文字节数
+```
 
-The [execution tree screenshot](images/agent-tree.png) comes from an isolated Harness web host with the 0.3.2 package installed. It shows real journal records for a lead Agent and a memory-reading child Agent. A local deterministic fixture supplies model responses for UI and memory checks; this is not an external-model result or benchmark score.
+- 调用中显式指定的更短时限仍然有效。
+- 旧宿主的 PTC 按 CPU 忙碌时间计时，新宿主按总耗时计时，两者不可直接比较。
+- 调大 `maxTasks`、`maxContextBytes` 会占用更多上下文，一般保持默认即可。
 
-0.3.2 保留圆形节点，将顶部操作集中一行；“已收起”和“自动整理”有可见名称。历史的创建时间与排序使用自定义下拉，支持方向键、Home/End、Enter 和 Escape；所有插件按钮的名称气泡都在上方。
+## Windows 命令环境
 
-Version 0.3.2 retains circular nodes and groups actions in one row with visible Collapsed/Organize labels. Custom creation-time and sort dropdowns support arrow keys, Home/End, Enter, and Escape. All plugin button name bubbles appear above the control.
+验证范围见[兼容性记录](Compatibility.md)。
 
-Agent 详情采用对话列表：用户任务、Agent 回复分开呈现，真实工具调用和结果可展开查看。顶部先显示状态、Token 与缓存，展开“详情”可看更多用量、任务档案与记忆使用记录。翻页、返回最新内容和滚动位置保留现有行为。
+Windows 宿主默认在 Super Code 预设中使用内置 GNU Bash、BusyBox 和 GNU grep，运行常见 Bash 命令无需额外安装 Git。Git、Node、Python 等开发工具仍需自行安装。macOS、Linux 沿用宿主原有环境。
 
-Agent details use a chat list with distinct user tasks, replies, and expandable real tool calls/results. The compact header shows status, tokens, and cache; open Details for additional usage, task records, and memory activity. Pagination, latest-content navigation, and scroll restoration retain their existing behavior.
+在「预设配置 → 命令环境」关闭「使用内置 Bash（Windows）」，新启动的会话将改用宿主的 PowerShell。设置自动保存，运行中的 Agent 保留原有环境，子 Agent 继承会话环境和工具限制；已安装的旧预设需要先重新安装，才能使用新的命令环境入口。判断依据是 DSH 服务端系统，浏览器所在系统不影响选择。仅检测为 Windows 时可修改这里的开关；其他平台显示为灰色，悬浮提示「仅 Windows 生效」。
 
-## 记忆库 · Memory Library
+开启同一位置的「同时应用到官方预设」，也可让官方标准、PTC、创建模式使用内置 Bash，默认关闭。此选项与预算和删除保护的适用范围独立；关闭 Bash 总开关后，官方预设也使用原有 Shell，已保存的适用范围选择会保留。极简模式保留原有持久终端，自定义预设不自动修改。官方预设无需安装 Super Code 副本即可使用此设置。
 
-在“Super Code”页面点击“记忆库”标题展开。先选“当前项目”或“全局偏好”，再从主题目录选择主题，或搜索主题、摘要与标识符；点一条记忆查看详情与来源。返回列表时会保留搜索和滚动位置。主题筛选与搜索可以同时使用，详情列出同主题条目。列表采用虚拟滚动，详情按需加载。
+运行时随插件提供，首次使用时离线准备到 `%LOCALAPPDATA%\dsh-super-code\shell`，不更改系统 PATH。设置页显示准备状态；准备失败时显示原因，关闭开关后可用宿主环境。命令失败不会换 Shell 重放。审批、删除保护和进程管理继续使用 DSH 的工具链。
 
-Click the “Memory library” heading on the “Super Code” page to expand it. Select “This project” or “Global preferences”, choose a topic or search by topic, summary, or identifier, and open an entry for its details and source. Search and scroll position are retained when you return. Topic filtering and search can be combined; details include related entries from the same topic. The list is virtualized; details load on demand.
+官方 Windows 限权沙箱会阻止 MSYS 创建内部命名管道，因此 `read-only`、`workspace-write` 下的 Bash 调用会在命令执行前明确报错。确需运行时，Agent 可为**同一条命令**请求 DSH 的 `sandbox_permissions="danger-full-access"` 单次审批，并说明原因。只有批准的这次调用可以执行；拒绝、取消或禁用审批时不执行，也不会自动修改会话权限或切换 Shell。PTC 的 `run_code` 本身若需更大权限，仍须经过宿主对该程序的独立审批，Bash 的批准不授予外层程序权限。
 
-记忆分三层，各管一件事：
+这仍是 Windows 环境：BusyBox 不包含所有 GNU 选项，`.cmd` 的引号及原生程序的 `/` 参数也不等同于 Linux。MSYS 会自动转换部分路径；确需传递原样参数时，可仅对该次调用设置 `MSYS2_ARG_CONV_EXCL`，不要全局关闭转换。内置工具不包含 `trash`，也不会把永久删除伪装成回收站操作。ARM64 Windows 上的 Bash、grep 和 MSYS DLL 使用 x64 兼容执行。验证范围见[兼容性](Compatibility.md)，组件来源与许可证见[运行时说明](../runtime/windows/README.md)。
 
-Memory has three distinct roles:
+## 删除保护
 
-| 层级 / Layer | 保存什么 / What it keeps | 范围 / Scope |
-|---|---|---|
-| 任务状态 / Task state | 当前目标、约束、进展与验证记录 / Goal, constraints, progress, and checks | 当前会话 / Current conversation |
-| 项目记忆 / Project memory | 有来源的项目事实、经验与约定 / Sourced facts, experience, and agreements | 同一规范化工作区路径，并按任务主题区分 / Canonical workspace path, organized by task topic |
-| 全局偏好 / Global preferences | 用户明确要求跨项目遵守的偏好 / Explicit cross-project user preferences | 同一 Harness 存储根目录 / Same Harness storage root |
+位于「删除保护」标签页，默认为**宽松**模式。
 
-想长期保留某个约定，直接告诉 Agent 即可；是否保存以工具成功结果和记忆库为准。Agent 保存的项目事实与经验必须关联真实工具结果和记录时版本，全局偏好必须有用户原文和明确的跨项目意图；在记忆库中直接维护的条目使用“手动维护”来源。不同路径的项目或 Git worktree 不会自动共享项目记忆。
+| 模式 | 行为 |
+|---|---|
+| 关闭 | 不提示，不拦截 |
+| 宽松（默认） | 提示 Agent 删除时默认使用可恢复的 `trash`，脚本中同样适用。用户明确要求使用 `rm` 时允许使用，插件不再二次确认 |
+| 严格 | 脚本中也不允许直接使用 `rm`。识别到永久删除命令时，每次都需用户确认，仅放行临时文件或构建产物的清理 |
 
-Tell the Agent when an agreement should be kept. Check the successful tool result or memory library to confirm it was saved. Agent-saved facts and experience require a real tool-result source and recorded version; global preferences require a user quote and explicit cross-project intent. Entries edited directly in the library use a manual source. Different project or Git worktree paths do not automatically share project memory.
+宽松模式提供给 Agent 的规则原文：**删除文件或目录默认用 `trash <path>`（可恢复）；仅清理临时文件、构建产物且我已确认时才用 `rm`。**
 
-记忆存储在宿主本地，不写入项目文件，也不会整库送给模型。当前任务主题和全局偏好各最多自动带入 4 条摘要，分别受 2 KiB、1 KiB 上限约束；详情需要主动读取。记忆不代替当前指令、不授予权限，也不能证明代码仍然保持记录时的状态。
+- 默认仅保护 Super Code。「同时应用到官方预设」默认关闭（与预算中的同名开关相互独立）。
+- 保存后对之后的命令生效。
+- 旧配置 `true` 视为严格，`false` 视为关闭。
 
-Memory lives in local host storage, not project files, and the full library is never injected into the model. The active task topic and global preferences each contribute at most four summaries, bounded by 2 KiB and 1 KiB respectively; details require an explicit read. Memory cannot override the current request, grant permission, or establish that code is unchanged.
+严格模式在终端命令执行前检查 `rm`、常见包装命令、内联 shell 脚本和 PowerShell 删除命令（如 `Remove-Item`），PTC 中的终端调用同样检查。
 
-## 每个 Agent 用了什么 · Per-Agent Memory Activity
+- 只有用户同意宿主弹出的一次性确认后才会放行；拒绝、取消或出错均会拦截。每次确认仅对当次有效。
+- 没有 `trash` 时，Agent 应改用其他可恢复的方式或停止操作。
+- 它不是系统沙箱：不检查外部脚本文件、混淆过的程序或各语言的删除 API。如需进程级隔离，请使用宿主沙箱。
 
-在执行树中点一个节点，展开顶部“详情”，再展开“记忆使用记录”。这里区分“带入上下文”“读取摘要”“读取详情”“保存”和“删除”，并标明项目/全局与主题；点记录会回到同一个“Super Code”页面并打开记忆条目，不新增记忆库页，也不切换主对话。
+宽松模式仅通过提示引导，不拦截命令，宿主原有的权限检查照常生效。
 
-Click an Agent node, then open “Details”, then expand “Memory activity” at the top of its details. Actions distinguish context inclusion, summary reads, detail reads, saves, and removals, with scope and topic. Click a record to return to the same “Super Code” page and open the current entry without creating another memory tab or switching the main conversation.
+## MCP 连接
 
-这些是宿主实际记录的动作，不代表模型一定理解或遵守了记忆。子 Agent 不会把继承的父会话历史算成自己的读取；失败调用也不显示为成功读取。界面最多显示最近 100 条不同动作，原始完整记录仍在会话日志中。条目后来修改或删除时，历史使用记录仍保留，但记忆库展示当前内容，不伪装成旧版本快照。
+允许外部 MCP 客户端（如其他 AI 编码工具）将任务委派给 DSH 执行。默认关闭，仅监听本机 `127.0.0.1`，使用 Streamable HTTP 和凭证认证。
 
-These are recorded host actions, not proof that the model understood or followed the memory. Inherited parent history is not counted as a child's own read, and failed calls are not shown as successful reads. The UI keeps the latest 100 distinct actions; full history stays in the session log. Activity survives later edits or removals, but the library shows the current entry—not a reconstructed snapshot of an older revision.
+### 开启
 
-历史会话的记忆可直接查看，不需要恢复 Agent 或再次调用模型。记忆库支持新增、编辑、取消、保存和删除。编辑时可修改类型、标题和内容；取消不保存，删除需要确认。手动保存的条目标为“手动维护”，仅保留当前内容，不保留版本历史。
+在「连接」标签页中：
 
-You can browse memory from stored conversations without resuming an Agent or making another model call. The library supports Add, Edit, Cancel, Save, and Delete. Edit the type, title, and content; Cancel discards the draft, and Delete asks for confirmation. Manually saved entries are marked accordingly. Only current content is kept, with no version history.
+1. 勾选允许的工作目录（含子目录）。
+2. 按需修改端口和最大连接数。
+3. 打开开关。修改会自动保存。
 
+「允许 MCP 新增对话」默认开启；关闭后只能明确复用已有对话。新对话归入已有工作区，目录尚未登记时创建无后缀的同名工作区，标题以 `[MCP]` 开头。
 
-## MCP 连接 · MCP Connection
+「允许调用方审批」默认关闭。开启后，指定 MCP 任务的一次工具审批可交给调用方，通过交互表单或 `dsh_approve` 决定；宿主权限策略和目录申请的用户确认保持有效。
 
-设置 → Super Code 模式默认打开“首页”，集中显示预设状态与版本、保护等级、MCP 开关，以及正在连接和历史对话的数量。客户端和关联会话详情、打开会话及断开操作位于“连接”标签。预设、上下文、删除保护、连接分别配置；预设配置页直接展示表单。MCP 默认关闭，在“连接”标签中勾选允许的工作目录、调整本机端口和最大连接数；修改会自动保存，无需确认按钮。服务只监听 `127.0.0.1`，地址以页面显示为准；端口冲突会显示错误。
+目录说明：
 
-Settings → Super Code opens **Home**, with preset status and versions, protection level, the MCP switch, and counts of connected and past conversations. Client and linked-session details, opening conversations and disconnect actions are in **Connection**. Preset, context, deletion protection and connection settings have separate tabs. Preset configuration shows its form directly. MCP is disabled by default. In **Connection**, select allowed working directories and adjust the local port and maximum connections. Changes save automatically without a confirmation button. The service listens on `127.0.0.1` only; use the displayed URL. Port conflicts are reported explicitly.
+- 每次进入连接页都会重新读取 DSH 工作区。首次配置时会预选已有工作区，之后新增的工作区**不会**自动获得授权。
+- 可通过目录选择器添加目录。取消勾选即撤销授权；取消最后一个目录会同时关闭 MCP。
 
-工作目录以勾选列表展示，每次进入连接页会重新读取 DSH 工作区。首次配置时预选已有有效工作区，修改后自动保存并保留用户选择；后来新增的工作区不会静默获得访问权限。可以通过目录选择器添加目录，取消勾选会撤销该目录的入口授权，取消最后一个允许目录时会同时关闭 MCP。手动添加但未勾选的目录仍保留在列表中。允许目录包含其子目录。
+连接数说明：
 
-Directories appear as a checkbox list refreshed from DSH workspaces when opening Connection. Existing valid workspaces are initially selected in the first configuration draft; edits save automatically and later workspaces are never silently granted access. Add directories with the directory picker. Unchecking revokes that directory's admission grant; removing the last grant also turns MCP off. Unchecked manually added directories remain listed. Each grant includes descendants.
+- 最大连接数默认为 3，最多 32，同时也是任务并发上限。
+- 可在连接页断开客户端；空闲 10 分钟后自动断开。断开不会取消已接收的任务。
+- 首页的「在线对话」表示关联的 MCP 连接仍在线，与任务是否完成无关；断开后计为历史对话。
 
-最大连接数限制真实 MCP 协议会话（默认 3，上限 32），并同时作为任务执行并发上限。在连接页可以断开客户端，空闲 10 分钟也会释放连接；断开不会取消已接收任务。正在连接的对话按其关联 MCP 连接是否在线统计，断开后计入历史；与任务是否执行完成无关。连接凭证默认展开，离开连接页后隐藏，再次进入时重新读取。
+端口冲突时会直接报错。地址以页面显示为准。
 
-Maximum connections counts MCP protocol sessions (default 3, maximum 32) and is also the task execution concurrency limit. Disconnect clients from Connection; idle connections also expire after 10 minutes. Disconnecting does not cancel accepted tasks. Conversations count as connected while their linked MCP connection is online, regardless of task completion; after disconnect they count as past conversations. The token is expanded by default in Connection, cleared when leaving the tab and reloaded on return.
+### 配置客户端
 
-### 连接 Prompt · Connection Prompt
+1. 复制连接页中的「连接 Prompt」，提供给支持 Streamable HTTP MCP 的客户端。其中包含地址、认证方式和工具说明，**不含**真实凭证。
+2. 单独复制凭证，在客户端中配置为 `Authorization: Bearer <凭证>`。请勿将凭证写入仓库或共享的提示词。
+3. 保持 DSH 运行。更换凭证后旧凭证立即失效，请同步更新客户端。
 
-1. 在连接页复制“连接 Prompt”，交给支持 Streamable HTTP MCP 的客户端配置连接。提示词包含页面当前地址、认证方式、六项工具与任务状态约定，不包含真实凭证，也不绑定特定客户端。连接后先调用 `dsh_sessions` 按工作目录查看最近对话、状态和连接额度，再由调用方选择传 `taskId` 复用历史或传 `newConversation: true` 新建；不会默认复用最新对话。
-2. 单独复制连接凭证，在客户端安全保存并配置为 `Authorization: Bearer <连接凭证>`。不要把实际凭证写进仓库或共享提示词。
-3. 保持提供连接的 DSH Web 服务或桌面应用运行。更换凭证后同步更新客户端；旧凭证立即失效。客户端是否允许由提示词自动配置 MCP，取决于客户端自身能力；也可以使用页面地址和认证方式手动配置。
+客户端能否根据提示词自动配置 MCP 取决于客户端本身，也可手动填写地址和认证信息。凭证在连接页默认展开，离开页面后隐藏。
 
-Copy **Connection Prompt** from the Connection tab and give it to a client that supports Streamable HTTP MCP. It contains the current URL, authentication method, six tools and task-state conventions, without an actual token or client-specific command. After connecting, call `dsh_sessions` for the working directory to see recent conversations, statuses and connection capacity. Let the caller choose whether to pass `taskId` to reuse history or `newConversation: true` to create a new root; `dsh_run` never defaults to the latest conversation. Copy the token separately and securely configure `Authorization: Bearer <connection token>` in the client. Keep the serving DSH process running, and update the client after token rotation. Whether a prompt can configure MCP automatically depends on the client; manual setup using the shown URL and authentication is also supported. Never put actual credentials in repository files or shared prompts.
+### 工具
 
-| 工具 / Tool | 用途 / Behavior |
+| 工具 | 用途 |
 |---|---|
-| `dsh_sessions` | 连接后按允许的工作目录返回最近对话、状态、可复用标记、每条对话的连接数，以及当前/最大/剩余连接数和任务并发占用。调用方据此选择复用或新建。 / After connecting, list recent conversations for an allowed working directory with status, reuse availability, per-conversation connection count, current/maximum/available connections, and active task capacity. Use it to choose reuse or a new root. |
-| `dsh_run` | 传 `taskId` 精确复用历史根会话；传 `newConversation: true` 明确新建，未传时为兼容旧客户端也新建。相同 `requestId` 与相同输入不会重复提交，输入不同会报冲突。 / Pass `taskId` to reuse an exact history entry; pass `newConversation: true` to make a new root explicit. Omitting both also creates a new root for backward compatibility. Retrying identical input with the same request ID does not dispatch again; conflicting input is rejected. |
-| `dsh_wait` | 提供任务 ID 时读取状态、输出、工作区观察及游标后的事件，最长等待 30 秒；省略任务 ID 时分页列出本服务持有的任务。 / Read task state, output, workspace observations and events after a cursor, with waits bounded to 30 seconds; omit the task ID to list owned tasks. |
-| `dsh_send` | 在同一根会话补充要求或明确继续，使用新的请求 ID；不会代替用户批准宿主权限。 / Queue a follow-up or explicitly continue the same root session with a new request ID. Does not approve host permissions. |
-| `dsh_request_directory` | 申请新增工作目录，由 DSH 用户明确批准；重复请求查询审批状态。 / Request additional directory access with explicit consent in DSH; repeat to poll the decision. |
-| `dsh_cancel` | 请求取消根会话及受管理后代；需继续观察真实状态，不能把取消请求当成全部停止。 / Request cancellation of the root and managed descendants; observe the resulting state to confirm execution stopped. |
-
-### 新增目录申请 · Additional Directory Requests
+| `dsh_status` | 查看允许目录、开关、连接与任务额度、阻塞任务和恢复提示 |
+| `dsh_models` | 查询模型与思考强度 ID，供 `dsh_run`、`dsh_send` 指定；省略时沿用会话当前或默认选择 |
+| `dsh_read` | 分页读取所属会话及受管子会话的公开消息、工具结果与失败详情，不返回推理和私有配置 |
+| `dsh_approve` | 仅在允许调用方审批时，批准或拒绝一个精确的待审批操作，仅生效一次 |
+| `dsh_sessions` | 连接后应首先调用：按目录列出最近的对话、状态、是否可复用，以及连接额度和任务并发占用 |
+| `dsh_run` | 发起任务。传入 `taskId` 复用指定对话；传入 `newConversation: true` 新建对话（两者均未传入时也新建）。**不会**自动复用最新对话。同一 `requestId` 搭配相同输入不会重复提交，输入不同则报冲突 |
+| `dsh_wait` | 查询任务状态、输出、工作区变化和新事件，最多等待 30 秒。未传入任务 ID 时分页列出所有任务 |
+| `dsh_send` | 在同一对话中补充要求或继续执行，需使用新的 `requestId`。不会代为批准权限 |
+| `dsh_request_directory` | 申请新的工作目录，需用户在 DSH 中批准 |
+| `dsh_cancel` | 请求取消对话及其子任务。之后应继续查询状态，确认任务已实际停止 |
 
-外部会话可调用 `dsh_request_directory`，提交稳定的 `requestId`、已存在的绝对 `path` 和 `reason`。DSH 会在全局弹出确认对话框，显示客户端名称、实际目录和申请理由，不需要先打开设置。只有用户点击“允许访问”，才会将该目录加入列表并勾选；审批沿用最新配置，不覆盖同时发生的其他设置修改，也不会断开已有 MCP 连接。申请不会触发模型调用，且不能由模型的自动审批策略代为同意。
+### 申请新目录
 
-重复相同输入可查询 `pending` / `approved` / `rejected` / `expired` 状态；相同 ID 改变输入会报冲突。批准前不能在该目录委派任务。待审批请求最多 8 条，5 分钟过期；拒绝、关闭服务或重启均不自动授权。请求历史为有界的进程内记录（最多 100 条），已批准的目录配置会保存。客户端名称和理由来自客户端，仅供辨认。
+客户端调用 `dsh_request_directory`，并提供 `requestId`、已存在的绝对路径 `path` 和理由 `reason`。DSH 会弹出全局确认框（无需打开设置），显示客户端名称、目录和理由。
 
-External sessions call `dsh_request_directory` with a stable `requestId`, an existing absolute `path` and a `reason`. A global DSH dialog shows the client name, canonical directory and reason even when settings is closed. Only the user's **Allow access** action adds and selects the directory. Approval merges into the latest configuration without overwriting concurrent changes or disconnecting clients. It does not invoke a model and cannot be approved by a model's automatic permission policy.
+- 只有用户点击「允许访问」后才会授权，模型的自动审批无法替代。
+- 使用相同输入重复调用可查询状态：`pending` / `approved` / `rejected` / `expired`。
+- 批准前不能在该目录发起任务。
+- 最多 8 个待审批请求，5 分钟后过期。拒绝、关闭服务或重启均不会自动授权。
+- 客户端名称和理由由客户端自行填写，仅供参考。
 
-Repeat identical input to read `pending`, `approved`, `rejected` or `expired`; changing input under the same ID conflicts. Delegation is blocked until access is approved. At most eight pending requests are allowed, expiring after five minutes. Rejection, service shutdown and restart never grant access. Request history is in memory and bounded to 100 entries; approved directory settings persist. Client names and reasons are supplied by the caller for identification.
+### 任务状态与恢复
 
-### 状态、权限与恢复 · State, Permissions and Recovery
+- 任务使用会话当前或明确指定的模型、Super Code 预设和用户的权限设置，不会自动放行权限。模型与思考强度选择保留在该会话中。
+- 客户端的沙箱不会延续到 DSH。允许目录只控制能否在该目录发起任务，并非文件沙箱。
+- 同一工作区的任务不并行执行。如需并行，请自行准备独立的 worktree，插件不会创建、删除或合并 worktree。
+- `waiting_confirmation`：仅开启调用方审批且存在对应请求时可由调用方处理，否则由用户在 DSH 中确认。
+- `finished`：执行已结束，但 `acceptance` 始终为 `not-verified`，结果是否正确需由调用方自行验证。
+- 返回的文件信息是对 Git 工作区的观察结果，包括任务开始前已有的改动，不能证明全部由本任务产生。非 Git 目录或超出观察上限时标记为不可用。
+- 等待超时或客户端断线均不会取消任务。关闭连接仅表示不再接收新请求。
+- 重启后不会自动重新发送提示词。请通过 `dsh_sessions` 或任务列表找回任务 ID，确认状态后再明确继续。无法确认状态时显示 `interrupted` 或 `unavailable`；未确认停止的任务会继续占用并发额度。
 
-任务沿用当前宿主的默认模型、Super Code 预设和权限；不修改普通会话的提示词或执行策略，也不会自动放行权限。调用方的沙箱不会自动传播到 DSH。允许目录限制用于任务入口，不构成文件系统沙箱；实际工具权限由 DSH 管理。同一工作区不会并行委派，可由调用方自行准备独立 worktree；插件不创建、删除或合并 worktree。
+遇到上限时，保留原 `requestId` 和输入，通过 `dsh_status`、`dsh_wait` 等待空位，不要取消其他客户端的任务或改动提供服务的 DSH 应用。结束 SDK 会话时，先调用 `transport.terminateSession()` 发送 DELETE，再关闭客户端；仅 `client.close()` 不会释放服务端额度。没有原生 MCP 工具时可使用包内 `super-code-mcp` 命令，JSON 参数从标准输入读取，凭证由私密环境变量 `DSH_MCP_TOKEN` 提供。
 
-Tasks use the host’s default model, Super Code preset and permissions without changing ordinary conversation prompts or execution strategy. Caller sandbox restrictions do not automatically propagate to DSH. Allowed directories govern task admission, not filesystem isolation; DSH controls tool permissions. Delegations in the same workspace do not run concurrently. Callers may supply separate worktrees; the plugin does not create, delete or merge them.
+### 存储与上限
 
-`waiting_confirmation` 表示需要在 DSH 处理权限确认或受阻的回合。`finished` 仅表示根会话和已观测的受管理后代执行结束，返回的 `acceptance` 始终为 `not-verified`，需要调用方验证结果。文件信息来自执行前基线与当前 Git 工作区的有界观察，会保留原有脏文件列表，不能证明全部变化均由本任务产生；非 Git 目录、超出观察上限或读取失败时会标记不可用。
+- 任务记录、配置和凭证保存在当前 profile 的 `super-code-connection` 目录中，目录权限为 0700，文件权限为 0600。每个 profile 只能运行一个服务实例。
+- 上限：200 条任务记录、每个任务 128 次补充、最近 200 条事件、输出保留最后 12,000 字符。目录申请历史最多 100 条，仅保存在内存中。
+- 任务记录已满时会明确拒绝新任务，不会自动删除旧记录。
 
-`waiting_confirmation` requires action in DSH. `finished` means the root and observed managed descendants have settled; it does not certify acceptance. Results carry `acceptance: not-verified`. File information is a bounded Git workspace observation relative to the starting baseline, including pre-existing dirty files, and does not establish exclusive attribution. Non-Git directories, exceeded observation limits and read failures are reported as unavailable.
+## 前端 Skill
 
-等待超时或客户端断线不会取消执行。关闭连接停止接收请求，已接收任务继续由 DSH 管理。重启或热重载后不自动重发 prompt；可通过 `dsh_sessions` 或任务列表找回 ID，先观察会话，再明确继续。无法确认状态时保留 `interrupted` 或 `unavailable`，避免误报完成；未确认停止的任务会继续占用并发额度。
+插件内置 `super-code-frontend`，用于页面、组件、视觉调整、响应式布局、交互状态和浏览器验证。重点检查：
 
-Wait timeouts and client disconnections do not cancel execution. Disabling the connection stops accepting requests while DSH continues managing accepted work. Restart and hot reload never automatically replay prompts. Recover task IDs through `dsh_sessions` or the task listing, inspect the session, then explicitly continue. Unconfirmed tasks remain interrupted or unavailable and retain their concurrency reservation.
+- 元素是否对齐到同一基准线
+- 可见范围与可点击范围是否一致
+- 控件位置是否稳定，操作距离和输入负担是否合理
 
-任务记录、配置和凭证保存在当前 profile 的 `super-code-connection` 目录中，目录权限为 0700，文件为 0600；同一配置目录只允许一个服务实例持有。当前上限为 200 个任务记录、每任务 128 个补充操作和最近 200 条状态事件，输出保留最后 12,000 个字符。达到记录上限会明确拒绝新任务，不会悄悄丢弃幂等记录并重跑。
+它沿用项目自身的视觉风格，不限定框架，也不新增工具。平时只向模型提供名称和简介，任务匹配时才加载正文和相关参考。也可在请求中直接说明「用 super-code-frontend」。
 
-State, configuration and credentials are stored in the profile’s `super-code-connection` directory, with directory mode 0700 and file mode 0600. A profile has one service owner. Limits are 200 task records, 128 follow-up operations per task, the latest 200 state events, and the last 12,000 output characters. Reaching the history limit explicitly rejects new tasks rather than silently discarding idempotency records and redispatching work.
+- 0.3.3 起新安装或重装的预设才包含该 Skill。已有预设请先备份自定义内容，再重新安装。
+- 项目或用户目录中存在同名 Skill 时，按宿主优先级覆盖内置版本。
+- 浏览器验证部分仅为方法指导，不强制防止循环，也不会自动写入长期记忆。
+- 能否提升前端成品质量需通过单独的实际任务评测验证，安装测试和 SWE 成绩无法证明这一点。