dsh-pstack 0.3.0-beta.1 → 0.3.1

package/README.md

@@ -11,7 +11,7 @@
 
   <p>
     <a href="https://npmx.dev/package/dsh-pstack"><img src="https://img.shields.io/npm/v/dsh-pstack?style=flat-square&colorA=080f12&colorB=1fa669" alt="npm version" /></a>
-    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/dsh-%3E%3D0.2.2--alpha.3-1f6feb?style=flat-square" alt="dsh >=0.2.2-alpha.3" /></a>
+    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/dsh-%3E%3D0.2.2--rc.1-1f6feb?style=flat-square" alt="dsh >=0.2.2-rc.1" /></a>
     <a href="https://github.com/cursor/plugins/tree/main/pstack"><img src="https://img.shields.io/badge/pstack-0.15.36-d97706?style=flat-square" alt="pstack 0.15.36" /></a>
     <a href="https://github.com/l246804/dsh-pstack/blob/main/LICENSE"><img src="https://img.shields.io/github/license/l246804/dsh-pstack?style=flat-square&colorA=080f12&colorB=1fa669" alt="license" /></a>
     <a href="https://www.jsdocs.io/package/dsh-pstack"><img src="https://img.shields.io/badge/jsdocs-reference-080f12?style=flat-square&colorA=080f12&colorB=1fa669" alt="JSDoc reference" /></a>
@@ -21,30 +21,33 @@
     <tr>
       <td align="center"><strong>58</strong><br /><sub>pstack skills</sub></td>
       <td align="center"><strong>23</strong><br /><sub>playbooks</sub></td>
-      <td align="center"><strong>5</strong><br /><sub>native tools</sub></td>
-      <td align="center"><strong>2</strong><br /><sub>agent presets</sub></td>
+      <td align="center"><strong>4</strong><br /><sub>native tools</sub></td>
+      <td align="center"><strong>5</strong><br /><sub>agent presets</sub></td>
       <td align="center"><strong>5</strong><br /><sub>bundled scripts</sub></td>
     </tr>
   </table>
 
   <p>
     <a href="#quick-start">🚀 Quick start</a> ·
-    <a href="#-common-commands">⌨️ Commands</a> ·
+    <a href="#️-common-commands">⌨️ Commands</a> ·
     <a href="#-capabilities">🧩 Capabilities</a> ·
     <a href="#-optional-dsh-plugins">🔌 Optional plugins</a> ·
-    <a href="#-remaining-gaps">⚠️ Limitations</a> ·
+    <a href="#️-remaining-gaps">⚠️ Limitations</a> ·
+    <a href="#-faq">❓ FAQ</a> ·
     <a href="#-compatibility">📦 Compatibility</a>
   </p>
 </div>
 
 ---
 
-`dsh-pstack` ports [pstack](https://github.com/cursor/plugins/tree/main/pstack) to [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). It includes the upstream skills, playbooks, and references, and adds skill routing, role-based model configuration, subagents, and Node.js scripts.
+`dsh-pstack` ports [pstack](https://github.com/cursor/plugins/tree/main/pstack) to [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). It includes the upstream skills, playbooks, and references, and adds skill routing, role-based model configuration, and role-routed subagents.
 
-See the [capability map](./pstack/README.md) for the complete porting review.
+See the [capability audit (in Chinese)](./port/audit.md) and [runtime mapping](./port/dsh.md) for the full porting review.
+
+The current review covers 68 Cursor-facing capabilities: 39 direct mappings, 2 official plugins, 16 plugin implementations, and 11 deliberate omissions.
 
 > [!IMPORTANT]
-> Requires DSH `>=0.2.2-alpha.3` and Node.js `>=24.21.1`. For older DSH versions, choose a release from [Compatibility](#-compatibility).
+> Requires DSH `>=0.2.2-rc.1` and Node.js `>=24.21.1`. See the [script registry (in Chinese)](./port/AGENTS.md#脚本登记) for the extra runtime requirements of bundled workflows.
 
 <a id="quick-start"></a>
 
@@ -56,36 +59,57 @@ See the [capability map](./pstack/README.md) for the complete porting review.
    dsh plugin --profile web add dsh-pstack
    ```
 
-   You can also install it through **Plugins** in Web or Desktop.
+   You can also install it from the **Plugins** page in Web or Desktop.
 
 2. **Restart the profile or open a new Session.**
 
-3. **Initialize role-based model routing.**
+## 🧭 Usage
 
-   ```text
-   /setup-pstack
-   ```
+Choose one of the two paths and expand it for the complete steps.
 
-   The command saves available routes to `$DSH_HOME/pstack-models.mdc`. Without this file, roles inherit the parent model.
+<details>
+<summary><strong>🖥️ Visual setup</strong></summary>
 
-4. **Start a workflow.**
+Use the plugin UI when you want to configure related plugins and role routes.
 
-   ```text
-   /poteto-mode
-   ```
+1. Open **Plugins → Installed plugins**, select **pstack**, then click **Configure**.
+
+   ![Configure entry](./assets/plugin-configure.png)
+
+2. In **Recommended plugins**, review the **Recommended**, **Optional**, and **Conflicts** groups. **Enable all** only enables plugins in the **Recommended** group.
+
+   ![Recommended plugins](./assets/plugin-recommended.png)
+
+3. Open **Role models**, set the provider, model, and reasoning effort for each role, then save the changed row or use **Save all**.
+
+   ![Role models](./assets/plugin-roles.png)
 
-### ⚙️ Configure role models
+4. Open **Settings → Agent presets**, select **Poteto mode** or **Poteto Creator mode**, and click **Set as default**.
 
-To view or edit routes after setup, open **Plugins → Installed plugins → dsh-pstack → Configure**.
+   ![Agent presets](./assets/agent-presets.png)
 
-<p align="center">
-  <img src="assets/pstack-config-entry.png" width="800" alt="Plugin configuration entry" />
-</p>
+5. When creating a Session, keep the default preset or select **Poteto mode** manually.
+
+   ![Session preset](./assets/session-preset.png)
+
+</details>
+
+<details>
+<summary><strong>🧠 Skill usage</strong></summary>
+
+Use pstack skills when you want to start workflows directly from a Session.
+
+1. **Initialize role routes.** Run `/setup-pstack` once. It writes the detected routes to `$DSH_HOME/pstack-models.mdc`. Without this file, roles inherit the parent model.
+2. **Start through skills.** Type `/poteto-mode` directly. A preset switch is not required first.
+3. **Use targeted commands.** Pick a command from [Common commands](#️-common-commands).
+
+</details>
 
 ## ⌨️ Common commands
 
 | Task | Commands |
 |---|---|
+| Help | `/poteto-help` |
 | Plan and build | `/poteto-mode`, `/architect`, `/arena`, `/swarm` |
 | Understand and investigate | `/how`, `/why`, `/teach` |
 | Verify | `/create-verification-skill`, `/statechart` |
@@ -97,102 +121,124 @@ To view or edit routes after setup, open **Plugins → Installed plugins → dsh
 
 | Tool | Function |
 |---|---|
-| `pstack_skill` | Loads hidden pstack skills and their relative resources by name. |
+| `pstack_skill` | Loads hidden pstack skills by name, including resources at paths relative to the skill directory. |
 | `pstack_models` | Lists available providers, models, and reasoning efforts. |
-| `pstack_roles` | Shows role shapes and automatic-panel status so delegation uses the correct parameters. |
+| `pstack_roles` | Shows each role's type and whether it is an automatic panel, so delegation uses the correct parameters. |
 | `pstack_subagent` | Applies role routing and agent presets. Supports parallel subagents. |
-| `pstack_script` | Runs `check-plan`, `watch-pr`, `worktree-audit`, `log`, or `statechart` with Node.js. |
 
-The `poteto-agent` preset handles implementation delegation. The `comment-sicko` preset handles read-only comment review.
+### 🎭 Agent presets
+
+The package ships two root presets and three child presets.
 
-> [!CAUTION]
-> `pstack_script` bypasses bash approval and the filesystem sandbox. Treat it as a trusted entry point.
+| Preset | Scope | Use |
+|---|---|---|
+| `poteto-mode` | Root | Based on Standard mode, with the same capabilities plus the persistent `poteto-mode` workflow. |
+| `poteto-mode-creator` | Root | Based on Creator mode, with the same capabilities plus the persistent `poteto-mode` workflow. |
+| `poteto-agent` | Child | Handles implementation delegation with the pstack persona and `poteto-mode` instructions. |
+| `comment-sicko` | Child | Handles read-only comment review and reports deletion targets and `MUST KILL` symbols. |
+| `readonly` | Child | Provides sandbox-enforced read-only research for inspection and evidence gathering. |
+
+Open **Settings → Agent presets** and click **Set as default** on the preset that new Sessions should use.
 
 ### 📚 Additional skills
 
-The package includes six skills maintained independently of pstack.
+These skills extend pstack with authoring, project-maintenance, and evidence-gathering workflows.
 
-| Skill | Source | Purpose |
+| Skill | Source | Use it to |
 |---|---|---|
-| `writing-for-agents` | `vendored` | Write skills and clear agent-facing documentation. |
-| `retro` | `vendored` | Review the agent environment without modifying the repository. |
-| `decision-write` | `authored` | Create, land, and supersede decision records. |
-| `decision-audit` | `authored` | Audit decision-record status and relationships. |
-| `setup-project-docs` | `authored` | Set up sustainable project documentation. |
-| `docs-drift` | `authored` | Detect documentation drift and repair approved findings. |
+| `writing-for-agents` | `vendored` | Write or review a skill, `AGENTS.md`, `CLAUDE.md`, or another agent-facing document, including the `create-skill` use case. |
+| `retro` | `vendored` | Review a coding session's environment for improvements to navigation, checks, conventions, tools, and information access. |
+| `deslop` | `vendored` | Clean unnecessary comments, defensive code, casts, and nesting from a diff without changing behavior. |
+| `control-ui` | `vendored` | Drive a local Web, IDE, or Electron interface and capture visual or accessibility evidence. |
+| `control-cli` | `vendored` | Drive an interactive CLI or TUI and capture terminal transcripts or performance evidence. |
+| `decision-write` | `authored` | Record a design choice, its rationale, and its implementation evidence through a traceable lifecycle. |
+| `decision-audit` | `authored` | Check decision-record status, scope, implementation anchors, and supersession as design history grows. |
+| `setup-project-docs` | `authored` | Establish architecture, glossary, decision conventions, and pointers for a project's documentation. |
+| `docs-drift` | `authored` | Audit maintained documentation and repair approved drift, redundancy, and unsupported claims. |
 
 [`skills/skills-lock.json`](./skills/skills-lock.json) records the sources and hashes of vendored skills.
 
 ## 🔌 Optional DSH plugins
 
-Optional plugins extend specific workflows. You do not need them to install dsh-pstack.
+Install dsh-pstack without these plugins, then enable only the capabilities you need.
 
-To enable a plugin, open **Plugins → Add plugin**, select the package, and restart the profile.
-
-| Use case | Plugin | Limits and conflicts |
+| Use case | Plugin | What it provides and its boundaries |
 |---|---|---|
-| Worktrees and GitHub PRs | `@deepseek-ai/dsh-experimental-forge-bundle` | Provides the **Change requests & worktrees** switch and `create_worktree`. GitHub status needs a logged-in `gh`. |
-| Session history | `@deepseek-ai/dsh-experimental-session-search` | Read-only. Requires exact `cwd` equality. Subagent transcript coverage is unconfirmed. |
-| Browser verification | `@deepseek-ai/dsh-browser-use` and one provider | One provider per Session. Screenshots need an image-capable model. No video recording. |
-| Desktop verification | `@deepseek-ai/dsh-cua-bundle` | macOS PTC Sessions only. Windows support is incomplete. No video recording. |
-| Persistent terminals | `@deepseek-ai/dsh-experimental-terminal-bundle` | Six persistent shell and REPL tools. No GUI control or video recording. |
-| MCP integrations | `@deepseek-ai/dsh-mcp-client` | No server configured by default. No automatic evidence-category discovery. |
-| Agent teams | `@deepseek-ai/dsh-experimental-agent-team-profile` | Conflicts with `pstack_subagent`. No pstack PR frontier, ledger, or stack verdict. |
-| Autonomous loops | `@deepseek-ai/dsh-experimental-ralph-bundle` | Starts a fresh child each round. No persistent loop or event watcher. |
-
-Most packages ship with DSH. `@deepseek-ai/dsh-cua-bundle` installs on demand. Except for the MCP client, these plugins are experimental.
-
-### 🌐 Browser providers
-
-Choose one provider for `@deepseek-ai/dsh-browser-use`:
-
-- `@deepseek-ai/dsh-experimental-browser-use-stagehand-native`: also needs Chromium and a supported non-DeepSeek model.
+| Worktrees and GitHub PRs | `@deepseek-ai/dsh-experimental-forge-bundle` | Local worktrees and GitHub PR workflows. GitHub status requires a logged-in `gh`; otherwise use `gh` and `git worktree add` through `bash`. |
+| Session history | `@deepseek-ai/dsh-experimental-session-search` | Read-only history and event inspection. Matches Sessions by exact `cwd`; whether subagent transcripts are included is unconfirmed. |
+| Browser verification | `@deepseek-ai/dsh-browser-use` plus one provider below | Browser navigation, input, and screenshots. One provider per Session; screenshots require an image-capable model. |
+| Desktop verification | `@deepseek-ai/dsh-cua-bundle` | macOS desktop control in PTC desktop-control sessions. Windows support is incomplete. |
+| Persistent terminals | `@deepseek-ai/dsh-experimental-terminal-bundle` | Persistent shell and REPL sessions for CLI and TUI verification. |
+| MCP integrations | `@deepseek-ai/dsh-mcp-client` | Tools from explicitly configured MCP servers; no server is configured by default. |
+| Autonomous loops | `@deepseek-ai/dsh-experimental-ralph-bundle` | A foreground loop that starts a fresh child each round, rather than a persistent Session loop or event watcher. |
+| Agent Teams (incompatible) | `@deepseek-ai/dsh-experimental-agent-team-profile` | Lead and teammate roles and a shared task board. Do not enable it in a profile that offers the pstack root presets; both own delegation and coordination, and the pstack root preset fails at startup while the Agent Teams service is present. |
+
+For browser verification, choose one provider:
+
+- `@deepseek-ai/dsh-experimental-browser-use-stagehand-native`: also requires Chromium and a supported non-DeepSeek model.
 - `@deepseek-ai/dsh-experimental-browser-use-playwright-mcp`
 - `@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp`
 
-Providers have different tool names and selectors. Browser and computer use share separate single-provider slots.
-
-The configuration page recommends Change requests & worktrees and session search. It never enables plugins automatically. Agent Teams is a conflict warning, not a recommendation.
+Enable packages through **Plugins → Add plugin**, then restart the profile when required. Most packages ship with DSH; `@deepseek-ai/dsh-cua-bundle` installs on demand. All except the MCP client are experimental.
 
 > [!WARNING]
-> Use either Agent Teams or `pstack_subagent`, not both. Agent Teams disables DSH's native subagent tools.
+> **Agent Teams conflicts with the pstack root presets.** Use either Agent Teams or `pstack_subagent`, not both. Enabling Agent Teams makes the pstack root preset fail at startup and disables DSH native subagent tools.
 
-When a plugin is disabled, dependent steps report skipped or blocked. They never report passed. Without the forge bundle, use `gh` and `git worktree add` through `bash`. See the [DSH adaptation guide](./pstack/harness/docs/harness/dsh.md#optional-plugins) for setup details and fallbacks.
+Steps that depend on a disabled plugin report skipped or blocked, never passed. See the [DSH adaptation guide](./pstack/docs/harness/dsh.md#optional-plugins) for setup and fallbacks.
 
 ## ⚠️ Remaining gaps
 
-These limitations remain even when every recommended plugin is enabled.
+These limitations remain even after all optional plugins that can coexist with pstack are enabled.
 
 | Area | Limitation |
 |---|---|
 | Cursor platform services | No Automations, Cursor webhooks, `SendToUser`, cloud agents, or persistent cloud Projects. |
 | Bugbot | Cannot start, configure, or wait for Bugbot. Existing Bugbot comments can still be handled as PR reviews. |
-| PR orchestration | No model-side change-request tool or Agent Teams PR frontier and ledger. `watch-pr` still provides stack verdicts. |
-| Custom Mode | No persistent root `poteto-mode` or Option+Enter toggle. Invoke `/poteto-mode` for each task. |
+| PR orchestration | No model-side change-request tool or Agent Teams-style PR tracking board and shared ledger. `watch-pr` still provides stack verdicts. |
+| Mode switching | No Option+Enter toggle or mid-session mode switch. Select `poteto-mode` or `poteto-mode-creator` at session creation; other presets invoke `/poteto-mode` for each task. |
 | Event-driven loops | No forge event subscription. Local goals, schedules, and watchers are not equivalent. |
-| Media evidence | No built-in video recording or frame-level verification. Use external recording or FFmpeg tools. |
-| Desktop coverage | Computer use is limited to macOS PTC Sessions. Windows support is incomplete. |
+| Diagram rendering | No built-in renderer. Charts return Mermaid text; render an image with your own tools when needed. |
+| Media evidence | No built-in video rendering, recording, or frame-level verification. Use external recording or FFmpeg tools. |
+| Desktop coverage | Computer use is limited to macOS PTC desktop-control sessions. Windows support is incomplete. |
 | MCP discovery | No automatic evidence-category discovery. Configure and identify MCP tools explicitly. |
 
+## ❓ FAQ
+
+<details>
+<summary><strong>Expand for questions and answers</strong></summary>
+
+1. **Agent preset names stay in English**
+
+   Set the language to Chinese in **Settings → General → Language**, then restart DSH. If the row already shows Chinese, select it again to save the preference that preset names read when the host starts.
+
+</details>
+
 ## 📦 Compatibility
 
-Each row lists the latest compatible dsh-pstack release and its included pstack version. Newer DSH boundaries appear first.
+Choose a release by its declared DSH range. Within each compatibility range, every `x.y` keeps only its latest release. The pstack column records the current port baseline, not a per-release history.
 
-| DSH version | Latest compatible dsh-pstack release | Included pstack version |
+<!-- compatibility-keys: ["dsh-0.2.2-rc.1+port-v1","dsh-0.2.1-rc.5+legacy-v1","dsh-0.2.0-0.3.0+legacy-v1"] -->
+| DSH version | dsh-pstack release | Included pstack version |
 |---|---|---|
-| `0.2.2-alpha.3` and later | Next release from this source tree | `0.15.36` |
-| `0.2.2-alpha.2` and earlier | `v0.2.1` | `0.15.36` |
+| `>=0.2.2-rc.1` | `0.3.1` | `0.15.36` |
+| `>=0.2.1-rc.5` | `0.2.2` | `0.15.36` |
+| `>=0.2.0 < 0.3.0` | `0.1.0` | `0.15.29` |
+
+A new compatibility range adds a row. Other releases update their row automatically; see [Porting](./port/AGENTS.md#破坏性变更).
+
+## 🔗 Friendly Links
 
-When a DSH breaking change creates a new compatibility boundary, add a row.
+- [LinuxDo - 新的理想型社区](https://linux.do/)
 
 ## 💛 Credits
 
-- [pstack](https://github.com/cursor/plugins/tree/main/pstack) was designed and open-sourced by Lauren Tan and the Cursor team. `poteto-mode`, the 23 playbooks, and the 24 principles come from upstream.
-- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) is provided by the DeepSeek team. Its plugin, bundle, agent preset, subagent, and tool interfaces support this port.
-- [mattpocock/skills](https://github.com/mattpocock/skills) provides the vendored `writing-for-agents` and `retro` skills.
+- [pstack](https://github.com/cursor/plugins/tree/main/pstack), designed and open-sourced by Lauren Tan and the Cursor team; the foundation of this port.
+- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), developed by the DeepSeek team; the host platform for this plugin.
+- [cursor-team-kit](https://github.com/cursor/plugins/tree/main/cursor-team-kit), the source of the vendored `deslop`, `control-ui`, and `control-cli` skills.
+- [mattpocock/skills](https://github.com/mattpocock/skills), the source of the vendored `writing-for-agents` and `retro` skills.
 
 This project is a community port, not an official Cursor or DeepSeek release.
 
 ## 📄 License
 
-Original dsh-pstack code and documentation use the [MIT license](./LICENSE) © [leiwang](https://github.com/l246804). Bundled upstream projects and vendored skills retain their licenses and notices.
+Original dsh-pstack code and documentation use the [MIT license](./LICENSE) © [leiwang](https://github.com/l246804). Bundled upstream projects and vendored skills are used under their upstream licenses; see [Credits](#-credits).

package/README.zh.md

@@ -11,7 +11,7 @@
 
   <p>
     <a href="https://npmx.dev/package/dsh-pstack"><img src="https://img.shields.io/npm/v/dsh-pstack?style=flat-square&colorA=080f12&colorB=1fa669" alt="npm version" /></a>
-    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/dsh-%3E%3D0.2.2--alpha.3-1f6feb?style=flat-square" alt="dsh >=0.2.2-alpha.3" /></a>
+    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/dsh-%3E%3D0.2.2--rc.1-1f6feb?style=flat-square" alt="dsh >=0.2.2-rc.1" /></a>
     <a href="https://github.com/cursor/plugins/tree/main/pstack"><img src="https://img.shields.io/badge/pstack-0.15.36-d97706?style=flat-square" alt="pstack 0.15.36" /></a>
     <a href="https://github.com/l246804/dsh-pstack/blob/main/LICENSE"><img src="https://img.shields.io/github/license/l246804/dsh-pstack?style=flat-square&colorA=080f12&colorB=1fa669" alt="license" /></a>
     <a href="https://www.jsdocs.io/package/dsh-pstack"><img src="https://img.shields.io/badge/jsdocs-reference-080f12?style=flat-square&colorA=080f12&colorB=1fa669" alt="JSDoc reference" /></a>
@@ -21,8 +21,8 @@
     <tr>
       <td align="center"><strong>58</strong><br /><sub>pstack 技能</sub></td>
       <td align="center"><strong>23</strong><br /><sub>playbook</sub></td>
-      <td align="center"><strong>5</strong><br /><sub>原生工具</sub></td>
-      <td align="center"><strong>2</strong><br /><sub>agent preset</sub></td>
+      <td align="center"><strong>4</strong><br /><sub>原生工具</sub></td>
+      <td align="center"><strong>5</strong><br /><sub>agent preset</sub></td>
       <td align="center"><strong>5</strong><br /><sub>随包脚本</sub></td>
     </tr>
   </table>
@@ -33,18 +33,21 @@
     <a href="#-能力">🧩 能力</a> ·
     <a href="#-可选-dsh-插件">🔌 可选插件</a> ·
     <a href="#️-仍存在的缺口">⚠️ 仍存在的缺口</a> ·
+    <a href="#-常见问题">❓ 常见问题</a> ·
     <a href="#-兼容性">📦 兼容性</a>
   </p>
 </div>
 
 ---
 
-`dsh-pstack` 将 [pstack](https://github.com/cursor/plugins/tree/main/pstack) 移植到 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH），保留其技能、playbook 与参考文档，并提供原生技能路由、按角色配置模型、子代理和 Node.js 脚本。
+`dsh-pstack` 将 [pstack](https://github.com/cursor/plugins/tree/main/pstack) 移植到 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH），保留其技能、playbook 与参考文档，并提供原生技能路由、按角色配置模型和按角色路由的子代理。
 
-完整的移植审查见[能力对照表](./pstack/README.md)。
+完整的移植审查见[能力审核](./port/audit.md)与[运行时映射](./port/dsh.zh.md)。
+
+当前审核覆盖 68 项面向 Cursor 的能力：39 项直接映射、2 项官方插件、16 项插件实现、11 项有意舍弃。
 
 > [!IMPORTANT]
-> 要求 DSH `>=0.2.2-alpha.3`、Node.js `>=24.21.1`。旧版 DSH 请根据[兼容性](#-兼容性)选择对应的插件版本。
+> 要求 DSH `>=0.2.2-rc.1`、Node.js `>=24.21.1`。部分随包工作流需要额外运行时，见[脚本登记](./port/AGENTS.md#脚本登记)。
 
 <a id="quick-start"></a>
 
@@ -60,32 +63,53 @@
 
 2. **重启对应的 profile，或新开一个 Session。**
 
-3. **初始化角色模型路由。**
+## 🧭 使用步骤
 
-   ```text
-   /setup-pstack
-   ```
+选择一种方式，点击展开查看完整步骤。
 
-   该命令将可用路由写入 `$DSH_HOME/pstack-models.mdc`。缺少此文件时，角色继承父级模型。
+<details>
+<summary><strong>🖥️ 可视化使用步骤</strong></summary>
 
-4. **开始工作流。**
+需要配置相关插件或角色路由时，使用插件界面。
 
-   ```text
-   /poteto-mode
-   ```
+1. 打开 **插件 → 已安装插件**，选择 **pstack 工作流**，然后点击 **配置**。
+
+   ![配置入口](./assets/plugin-configure.png)
+
+2. 在 **推荐插件** 中查看 **推荐**、**可选**、**冲突** 三组。**全部启用** 只会启用 **推荐** 组中的插件。
+
+   ![推荐插件](./assets/plugin-recommended.png)
+
+3. 打开 **角色模型**，为每个角色设置提供方、模型和推理强度，然后保存该行或点击 **全部保存**。
+
+   ![角色模型](./assets/plugin-roles.png)
+
+4. 打开 **设置 → Agent 预设**，选择 **Poteto 模式** 或 **Poteto 创造模式**，点击 **默认预设**。
+
+   ![Agent 预设](./assets/agent-presets.png)
+
+5. 新建会话时保留默认预设，或手动选择 **Poteto 模式**。
+
+   ![会话预设](./assets/session-preset.png)
+
+</details>
+
+<details>
+<summary><strong>🧠 技能使用步骤</strong></summary>
 
-### ⚙️ 配置角色模型
+需要从会话直接启动 pstack 工作流时，使用技能命令。
 
-初始化后，打开 **插件 → 已安装插件 → dsh-pstack → 配置**，即可查看或修改路由。
+1. **初始化角色路由。** 运行一次 `/setup-pstack`。命令会把检测到的路由写入 `$DSH_HOME/pstack-models.mdc`。缺少此文件时，角色继承父级模型。
+2. **通过技能启动。** 直接输入 `/poteto-mode`。不需要先切换预设。
+3. **使用针对性命令。** 从[常用命令](#️-常用命令)中选择。
 
-<p align="center">
-  <img src="assets/pstack-config-entry.png" width="800" alt="插件配置入口" />
-</p>
+</details>
 
 ## ⌨️ 常用命令
 
 | 工作流 | 命令 |
 |---|---|
+| 帮助 | `/poteto-help` |
 | 规划与实现 | `/poteto-mode`、`/architect`、`/arena`、`/swarm` |
 | 理解与调查 | `/how`、`/why`、`/teach` |
 | 验证 | `/create-verification-skill`、`/statechart` |
@@ -97,102 +121,124 @@
 
 | 工具 | 作用 |
 |---|---|
-| `pstack_skill` | 按名称加载隐藏的 pstack 技能及其相对资源。 |
+| `pstack_skill` | 按名称加载隐藏的 pstack 技能，以及技能目录内相对路径的资源。 |
 | `pstack_models` | 列出可用的 provider、model 和 reasoning effort。 |
-| `pstack_roles` | 展示角色 shape 与自动面板状态，确保委派时使用正确的参数。 |
+| `pstack_roles` | 展示每个角色的类型及是否为自动面板，确保委派时使用正确的参数。 |
 | `pstack_subagent` | 应用角色路由与 agent preset，支持并行子代理。 |
-| `pstack_script` | 用 Node.js 运行 `check-plan`、`watch-pr`、`worktree-audit`、`log` 或 `statechart`。 |
 
-`poteto-agent` preset 用于实现型委派，`comment-sicko` preset 用于只读评论审查。
+### 🎭 Agent preset
 
-> [!CAUTION]
-> `pstack_script` 会绕过 bash 审批和文件系统沙箱，请将其视为受信入口。
+随包提供两个根 preset 和三个子代理 preset。
+
+| 预设 | 范围 | 用途 |
+|---|---|---|
+| `poteto-mode` | 根 | 基于标准模式，能力与标准模式一致，额外常驻 `poteto-mode` 工作流。 |
+| `poteto-mode-creator` | 根 | 基于创造模式，能力与创造模式一致，额外常驻 `poteto-mode` 工作流。 |
+| `poteto-agent` | 子代理 | 实现型子代理，注入 pstack 人格和 `poteto-mode` 指令。 |
+| `comment-sicko` | 子代理 | 只读评论评审子代理，报告删除目标和 `MUST KILL` 符号。 |
+| `readonly` | 子代理 | 带只读沙箱策略的研究子代理，用于检查和取证。 |
+
+在 **设置 → Agent 预设** 中可以点击 **默认预设**，让新建会话自动使用该预设。
 
 ### 📚 额外技能
 
-随包提供六个独立于 pstack 维护的技能。
+这些技能为 pstack 补充文档编写、项目维护和证据采集工作流。
 
-| 技能 | 来源 | 作用 |
+| 技能 | 来源 | 使用场景 |
 |---|---|---|
-| `writing-for-agents` | `vendored` | 编写技能与清晰的 agent 文档。 |
-| `retro` | `vendored` | 只读复盘 agent 环境，不修改仓库。 |
-| `decision-write` | `authored` | 创建、落地和取代决策记录。 |
-| `decision-audit` | `authored` | 审计决策记录状态与关联关系。 |
-| `setup-project-docs` | `authored` | 搭建可持续维护的项目文档。 |
-| `docs-drift` | `authored` | 检查文档漂移并修复获批项。 |
+| `writing-for-agents` | `vendored` | 编写或评审技能、`AGENTS.md`、`CLAUDE.md` 等 agent 文档，覆盖 `create-skill` 的使用场景。 |
+| `retro` | `vendored` | 复盘编码会话的 agent 环境，改进导航、自动化检查、编码约定、工具效率和信息获取。 |
+| `deslop` | `vendored` | 在不改变行为的前提下，清理 diff 中多余的注释、防御性代码、类型断言和嵌套。 |
+| `control-ui` | `vendored` | 操作本地 Web、IDE 或 Electron 界面，采集视觉或可访问性证据。 |
+| `control-cli` | `vendored` | 操作交互式 CLI 或 TUI，采集终端操作记录或性能证据。 |
+| `decision-write` | `authored` | 以可追踪的生命周期记录设计取舍、理由和实现证据。 |
+| `decision-audit` | `authored` | 在设计历史累积后，检查记录状态、范围、实现锚点和取代关系。 |
+| `setup-project-docs` | `authored` | 为项目建立架构、术语、决策约定和文档指针。 |
+| `docs-drift` | `authored` | 巡检持续维护的文档，修复获批的漂移、冗余和无依据表述。 |
 
 vendored 技能的来源与哈希记录在 [`skills/skills-lock.json`](./skills/skills-lock.json)。
 
 ## 🔌 可选 DSH 插件
 
-可选插件用于扩展特定工作流，安装 dsh-pstack 时无需一并安装。
-
-要启用插件，请在 **插件 → 添加插件** 中选择对应的包，然后重启 profile。
+安装 dsh-pstack 时无需一并安装这些插件，按需启用即可。
 
-| 使用场景 | 插件 | 限制与冲突 |
+| 使用场景 | 插件 | 提供的能力与边界 |
 |---|---|---|
-| worktree 与 GitHub PR | `@deepseek-ai/dsh-experimental-forge-bundle` | 提供 **Change requests & worktrees** 开关和 `create_worktree`，GitHub 状态需要已登录的 `gh`。 |
-| 历史会话 | `@deepseek-ai/dsh-experimental-session-search` | 只读，要求 `cwd` 完全相同；子代理 transcript 覆盖范围未证实。 |
-| 浏览器验证 | `@deepseek-ai/dsh-browser-use` 与一个 provider | 每个 Session 使用一个 provider，截图需要支持图像的模型，不支持录屏。 |
-| 桌面验证 | `@deepseek-ai/dsh-cua-bundle` | 仅支持 macOS PTC Session，Windows 支持尚不完整，不支持录屏。 |
-| 持久终端 | `@deepseek-ai/dsh-experimental-terminal-bundle` | 六个持久 shell 与 REPL 工具，不支持 GUI 控制或录屏。 |
-| MCP 集成 | `@deepseek-ai/dsh-mcp-client` | 默认无 server，需要显式配置；不会自动发现证据类别。 |
-| agent team | `@deepseek-ai/dsh-experimental-agent-team-profile` | 与 `pstack_subagent` 冲突；没有 pstack 的 PR frontier、ledger 或 stack verdict。 |
-| 自主循环 | `@deepseek-ai/dsh-experimental-ralph-bundle` | 每轮使用新子代理，不提供同一 Session 的常驻循环或事件 watcher。 |
+| worktree 与 GitHub PR | `@deepseek-ai/dsh-experimental-forge-bundle` | 提供本地工作树和 GitHub PR 工作流。GitHub 状态需要已登录的 `gh`；没有此插件时通过 `bash` 使用 `gh` 与 `git worktree add`。 |
+| 历史会话 | `@deepseek-ai/dsh-experimental-session-search` | 只读检索历史会话与事件，按 `cwd` 完全匹配；是否包含子代理会话记录尚未确认。 |
+| 浏览器验证 | `@deepseek-ai/dsh-browser-use` 与下方任一 provider 搭配 | 浏览器导航、输入和截图。每个 Session 使用一个 provider，截图需要支持图像的模型。 |
+| 桌面验证 | `@deepseek-ai/dsh-cua-bundle` | 在 macOS PTC 桌面控制会话中控制桌面；Windows 支持尚不完整。 |
+| 持久终端 | `@deepseek-ai/dsh-experimental-terminal-bundle` | 为 CLI 和 TUI 验证提供持久 shell 与 REPL 会话。 |
+| MCP 集成 | `@deepseek-ai/dsh-mcp-client` | 使用显式配置的 MCP server 工具；默认不配置 server。 |
+| 自主循环 | `@deepseek-ai/dsh-experimental-ralph-bundle` | 每轮启动新子代理的前台循环，不是同一 Session 的常驻循环或事件 watcher。 |
+| Agent Teams（不兼容） | `@deepseek-ai/dsh-experimental-agent-team-profile` | 提供 lead/teammate 角色与共享任务板。不要在提供 pstack 根预设的 profile 中启用；两者都承担委派与协调，启用 Agent Teams 时 pstack 根预设会在启动时报错。 |
 
-多数包随 DSH 提供，`@deepseek-ai/dsh-cua-bundle` 按需安装。除 MCP client 外，以上插件均为实验性插件。
-
-### 🌐 浏览器 provider
-
-为 `@deepseek-ai/dsh-browser-use` 选择一个 provider：
+浏览器验证从以下 provider 中选择一个：
 
 - `@deepseek-ai/dsh-experimental-browser-use-stagehand-native`：还需要 Chromium 和受支持的非 DeepSeek 模型。
 - `@deepseek-ai/dsh-experimental-browser-use-playwright-mcp`
 - `@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp`
 
-不同 provider 的工具名与 selector 不同。浏览器和桌面控制各自使用一个 provider 槽。
-
-配置页默认推荐 Change requests & worktrees 和会话搜索，不会自动启用任何插件。Agent Teams 仅作为冲突警告，不属于推荐项。
+通过 **插件 → 添加插件** 启用对应包，必要时重启 profile。多数包随 DSH 提供，`@deepseek-ai/dsh-cua-bundle` 按需安装。除 MCP client 外，以上插件均为实验性插件。
 
 > [!WARNING]
-> Agent Teams 与 `pstack_subagent` 只能二选一。Agent Teams 会禁用 DSH 原生子代理工具。
+> **Agent Teams 与 pstack 根预设冲突。** Agent Teams 与 `pstack_subagent` 只能二选一。启用 Agent Teams 会导致 pstack 根预设启动失败，并禁用 DSH 原生子代理工具。
 
-未启用可选插件时，依赖它的步骤会标记为 skipped 或 blocked，不会标记为通过。没有 forge bundle 时通过 `bash` 使用 `gh` 与 `git worktree add`。安装与降级方案见 [DSH 适配文档](./pstack/harness/docs/harness/dsh.md#optional-plugins)。
+依赖未启用插件的步骤会标记为 skipped 或 blocked，不会标记为通过。安装与回退说明见 [DSH 适配文档](./port/dsh.zh.md#可选插件)。
 
 ## ⚠️ 仍存在的缺口
 
-即使启用所有推荐插件，以下限制仍然存在。
+即使启用所有可与 pstack 共存的可选插件，以下限制仍然存在。
 
 | 领域 | 限制 |
 |---|---|
 | Cursor 平台服务 | 不支持 Automations、Cursor webhook、`SendToUser`、云代理和持久云端 Projects。 |
 | Bugbot | 无法启动、配置或等待 Bugbot；已有 Bugbot 评论仍可作为 PR review 处理。 |
-| PR 编排 | 没有模型侧变更请求工具，也没有 Agent Teams 的 PR frontier 与 ledger；`watch-pr` 仍提供 stack verdict。 |
-| Custom Mode | 没有常驻根 `poteto-mode` 或 Option+Enter 开关；每个任务需调用 `/poteto-mode`。 |
+| PR 编排 | 没有模型侧变更请求工具，也没有 Agent Teams 式的 PR 跟踪面板与共享记录；`watch-pr` 仍提供 stack verdict。 |
+| 模式切换 | 没有 Option+Enter 开关或会话中切换模式的入口。新建会话时选择 `poteto-mode` 或 `poteto-mode-creator`；其它 preset 每个任务调用 `/poteto-mode`。 |
 | 事件驱动循环 | 不订阅 forge 事件；本地 goal、定时任务和 watcher 并非等价替代。 |
-| 视频证据 | 没有内置录屏与逐帧验证，需要外部录屏或 FFmpeg 工具。 |
-| 桌面覆盖 | computer use 仅支持 macOS PTC Session，Windows 支持尚不完整。 |
+| 图表渲染 | 不提供内置渲染器。图表以 Mermaid 文本返回，需要图片时自行用外部工具渲染。 |
+| 视频证据 | 没有内置视频渲染、录屏与逐帧验证，需要外部录屏或 FFmpeg 工具。 |
+| 桌面覆盖 | computer use 仅支持 macOS PTC 桌面控制会话，Windows 支持尚不完整。 |
 | MCP 发现 | 不会自动发现证据类别，需要显式配置并识别 MCP 工具。 |
 
+## ❓ 常见问题
+
+<details>
+<summary><strong>展开查看问题与解答</strong></summary>
+
+1. **预设名称显示为英文**
+
+   在「设置 → 通用 → 语言」中把语言切换为中文，然后重启 DSH。语言行可能已经显示中文，因为它跟随浏览器；重新选择一次中文会写入 preset 在 Host 启动时读取的语言偏好。
+
+</details>
+
 ## 📦 兼容性
 
-每行列出最新兼容的 dsh-pstack 发布版本及其包含的 pstack 版本。较新的 DSH 兼容分界排在上方。
+按发布版本声明的 DSH 范围选择。同一兼容范围内，每个 x.y 只保留最新版本。pstack 列记录当前移植基线，不逐一追溯旧插件版本。
 
-| DSH 版本 | 最新兼容的 dsh-pstack 发布版本 | 包含的 pstack 版本 |
+<!-- compatibility-keys: ["dsh-0.2.2-rc.1+port-v1","dsh-0.2.1-rc.5+legacy-v1","dsh-0.2.0-0.3.0+legacy-v1"] -->
+| DSH 版本 | dsh-pstack 发布版本 | 包含的 pstack 版本 |
 |---|---|---|
-| `0.2.2-alpha.3` 及更新版本 | 当前源码树的下一个发布版本 | `0.15.36` |
-| `0.2.2-alpha.2` 及更早版本 | `v0.2.1` | `0.15.36` |
+| `>=0.2.2-rc.1` | `0.3.1` | `0.15.36` |
+| `>=0.2.1-rc.5` | `0.2.2` | `0.15.36` |
+| `>=0.2.0 < 0.3.0` | `0.1.0` | `0.15.29` |
+
+新增兼容范围时增加一行，其他发布自动更新所属行；规则见[移植与维护](./port/AGENTS.md#破坏性变更)。
+
+## 🔗 友情链接
 
-DSH 出现破坏性更新并产生新的兼容分界时，追加一行。
+- [LinuxDo - 新的理想型社区](https://linux.do/)
 
 ## 💛 鸣谢
 
-- [pstack](https://github.com/cursor/plugins/tree/main/pstack) 由 Lauren Tan 与 Cursor 团队设计并开源。`poteto-mode`、23 个 playbook 和 24 条 principle 都来自上游。
-- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 由 DeepSeek 团队提供。DSH 的插件、bundle、agent preset、subagent 和工具宿主接口让这次移植能以原生工具落地。
-- [mattpocock/skills](https://github.com/mattpocock/skills) 提供 vendored 的 `writing-for-agents` 与 `retro`。
+- [pstack](https://github.com/cursor/plugins/tree/main/pstack)：由 Lauren Tan 与 Cursor 团队设计并开源，是本项目的工作流基础。
+- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)：由 DeepSeek 团队开发，是本插件的运行平台。
+- [cursor-team-kit](https://github.com/cursor/plugins/tree/main/cursor-team-kit)：vendored `deslop`、`control-ui` 与 `control-cli` 技能的来源。
+- [mattpocock/skills](https://github.com/mattpocock/skills)：vendored `writing-for-agents` 与 `retro` 技能的来源。
 
 本项目是社区移植，不是 Cursor 或 DeepSeek 官方发行。
 
 ## 📄 License
 
-本仓原创代码与文档采用 [MIT License](./LICENSE) © [leiwang](https://github.com/l246804)。上游项目及 vendored 技能保留各自的许可证与声明。
+本仓原创代码与文档采用 [MIT License](./LICENSE) © [leiwang](https://github.com/l246804)。上游项目及 vendored 技能按各自的许可证使用，详见[鸣谢](#-鸣谢)。