dsh-pstack 0.2.0-beta.1 → 0.2.0-beta.3

package/LICENSE

@@ -1,7 +1,6 @@
 MIT License
 
-Copyright (c) 2026 dsh-pstack contributors
-Copyright (c) 2026 Lauren Tan (upstream pstack, https://github.com/cursor/plugins)
+Copyright (c) 2026-PRESENT leiwang <leiwang2000@foxmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,134 +1,185 @@
-# dsh-pstack
+<p align="center">
+  <img src="./assets/logo.png" width="144" alt="dsh-pstack logo" />
+</p>
 
-<img src="static/icon.png" alt="pstack logo" width="96" height="96">
+<h1 align="center">dsh-pstack</h1>
 
-pstack 的 DeepSeek Harness 移植。它把 Cursor pstack 的技能、playbook、原则和角色化子代理工作流带到 DSH。
+<p align="center">
+  <strong>Bring pstack's rigorous agent workflows to DeepSeek Harness</strong>
+</p>
 
-安装后，`/poteto-mode` 启动一次严谨任务，`/setup-pstack` 配置各角色使用的模型和推理预算，`/poteto-help` 帮助选择技能或排查用法。
+<p align="center">
+  English · <a href="./README.zh.md">中文</a>
+</p>
 
-## 支持的 DSH 版本
+<p align="center">
+  <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://npmx.dev/package/dsh-pstack"><img src="https://img.shields.io/npm/dm/dsh-pstack?style=flat-square&colorA=080f12&colorB=1fa669" alt="npm downloads" /></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/dsh-0.2.2--alpha.2-1f6feb?style=flat-square" alt="dsh 0.2.2-alpha.2" /></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>
+</p>
 
-支持 `0.2.1-rc.3`。安装包在 `engines.dsh` 声明支持的 DSH 版本，其他版本未经验证。新版本验证通过后补充到本节。
+<p align="center">
+  <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://bundlephobia.com/result?p=dsh-pstack"><img src="https://img.shields.io/bundlephobia/minzip/dsh-pstack?style=flat-square&colorA=080f12&colorB=1fa669&label=minzip" alt="minzip size" /></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="JSDocs" /></a>
+</p>
 
-## 实现原理
+<div align="center">
+  <table>
+    <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>4</strong><br /><sub>native tools</sub></td>
+      <td align="center"><strong>2</strong><br /><sub>agent presets</sub></td>
+      <td align="center"><strong>5</strong><br /><sub>bundled scripts</sub></td>
+    </tr>
+  </table>
+</div>
 
-上游 pstack 对 Claude Code 的适配保留技能原文，生成独立的宿主资产，再用一份宿主适配说明处理工具、路径、模型和能力差异。
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#capabilities">Capabilities</a> ·
+  <a href="#skills-directory">Skills directory</a> ·
+  <a href="#optional-dsh-plugins">Optional DSH plugins</a> ·
+  <a href="#compatibility">Compatibility</a>
+</p>
 
-dsh-pstack 沿用这个思路。上游技能是内容源，DSH 专用资产单独生成，宿主差异集中说明。上游更新可以持续同步，DSH 特有的行为不会散落在每个技能里。
+`dsh-pstack` ports [pstack](https://github.com/cursor/plugins/tree/main/pstack) to [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). It keeps the upstream pstack skills, playbooks, and reference documents. Four native tools replace the interfaces that DSH lacks, while an adaptation layer maps Cursor's tool names, subagent fields, model slugs, and paths to DSH.
 
-## 必要依赖
+Most upstream pstack skills declare `disable-model-invocation: true`. `poteto-mode` routes to those hidden skills by name, but DSH's `skill` tool only exposes the model-visible catalog. DSH also has no equivalents for Cursor's model slugs, `subagent_type`, `readonly`, and Bun scripts. dsh-pstack handles those differences in the plugin layer. You can start with `/poteto-mode` after installation.
 
-- worktree 插件。并行写入和隔离工作目录需要它。未启用时插件自动启用，已启用时不会重复启用。
-- DSH 的 skills 和 subagents 能力，由支持的 DSH 版本提供。
-- Node.js `>=22.19`。仅 npm CLI 部署需要它出现在 `PATH` 上；Desktop（Electron）部署走 Host 自己的运行时。
-- Git。worktree 需要 Git 仓库。
+See [`pstack/README.md`](./pstack/README.md) for the full capability map, gaps, and acceptance status.
 
-随包的编排、PR watcher、计划检查、worktree 审计和决策日志脚本已构建为单文件 Node 产物，依赖全部内联。运行时通过 `pstack_script` 工具以宿主进程启动它们，因此**不需要 Bun，也不需要 bash，更不需要安装任何依赖**。Desktop 用户不在 `PATH` 上放 `node` 也能用：工具用 Electron 自带的 Node 运行时执行，并在需要时自动附加 `ELECTRON_RUN_AS_NODE`。脚本从**会话目录**启动，所以参数里的相对路径落在当前工作区或 worktree 内。
+> [!IMPORTANT]
+> This release targets DSH `0.2.2-alpha.2` or newer and requires Node.js `>=24.21.1`. `engines.dsh` is the range `>=0.2.2-alpha.2`: newer DSH versions are assumed compatible, and the requirement is only raised after a fix to the port is needed. See [Compatibility](#compatibility) before installing or upgrading.
 
-`pstack_script` 直接 `spawn` 子进程，因此**不经过命令审批，也不受 DSH 的 sandbox policy 约束**：它只能执行本包随附、由封闭 `id` 枚举选中的脚本，但脚本实际读了什么、写了哪里，Host 不会拦。这是为了在没有 `PATH` `node` 的部署里仍能运行为此付出的代价。需要审批与沙箱约束的命令请用 DSH 自己的 bash 工具。
+## Quick start
 
-worktree 只隔离工作目录和分支，不提供 VM、网络、凭据或端口隔离。需要独立机器或云端执行时，worktree 不是替代品。
+1. Install the plugin:
 
-Linux 和 macOS 是主要验证目标，Windows 未在实机验证。脚本本身已不含 shell 依赖，但 Windows 上的真实行为仍未验收。
+   ```sh
+   dsh plugin --profile web add dsh-pstack
+   ```
 
-## 与 Agent Team 的兼容性
+   You can also install it from the Plugins page in Web or Desktop.
 
-> **兼容性警告**
->
-> 当前版本禁止与 Agent Team 同时启用。Agent Team 会用同名工具遮蔽 `send_message`、`interrupt_agent` 和 `list_agents`，pstack 无法再用它们 steer、列出或中断自己的子代理。两者还共享子代理激活容量。`pstack_subagent` 的角色路由和 reasoning effort 计算本身不受影响，但同一 profile 中的 Team 工具会改变可见工具面。
->
-> 需要同时使用时，请使用两个独立 profile。
+2. Restart the profile or open a new Session.
 
-决策记录见 [docs/decisions/2026-10-24-no-agent-team-coexistence.md](https://github.com/l246804/dsh-pstack/blob/main/docs/decisions/2026-10-24-no-agent-team-coexistence.md)：`docs/` 不在发布包的文件清单里，所以这里用绝对 URL，避免 npm 页面上的相对链接指向不存在的路径。
+3. Before first use, run:
 
-## 安装
+   ```text
+   /setup-pstack
+   ```
 
-通过 npm 包 `dsh-pstack` 安装。`<profile>` 换成目标 profile，例如 `web`。
+   This command reads the providers, models, and reasoning efforts available in the current deployment. It writes them to `$DSH_HOME/pstack-models.mdc`. Without this file, every role inherits the parent's routing.
 
-```bash
-dsh plugin --profile <profile> add dsh-pstack
-```
+### Common entry points
 
-安装会启用 bundle。DSH 提示重启时按提示操作。
+| Command | Purpose |
+|---|---|
+| `/poteto-mode` | Main workflow entry: matches a playbook to the task and maintains todos and evidence. |
+| `/setup-pstack` | Configures role models and initializes the pstack environment. |
+| `/how`, `/why`, `/teach` | Architecture walkthrough, evidence investigation, and progressive explanation. |
+| `/architect`, `/arena`, `/swarm` | Multi-option design, parallel candidates, and slice-parallel implementation. |
+| `/create-verification-skill` | Generates a verification skill for a real project. |
+| `/statechart` | Checks state models with TLA+ and TLC, and outputs a Mermaid state diagram. |
+| `/show-me-your-work` | Maintains a TSV decision log and audits the current work. |
+| `/retro` | Reviews a coding session's environment. |
 
-## 快速开始
+## Capabilities
 
-1. 安装插件，进入目标 profile。
-2. 运行 `/setup-pstack`，选择推理预算和每个角色的模型。
-3. 用 `/poteto-mode` 加任务开始一次严谨工作流。
-4. 不确定用哪个技能时，运行 `/poteto-help`。
+### Native tools
 
-`/poteto-mode` 会匹配 playbook，把步骤写进 todo，并按需读取其他技能。小改动可以直接做，不必使用它。
+| Tool | Purpose |
+|---|---|
+| `pstack_skill` | Loads a hidden skill registered by this plugin by name, and reads relative resources inside the skill directory. |
+| `pstack_models` | Read-only list of the providers, models, and efforts DSH actually offers, used by `/setup-pstack`. |
+| `pstack_subagent` | Reads `$DSH_HOME/pstack-models.mdc` per role, parses `provider/model [effort]`, selects a preset by `agent`, and can start several subagents at once. |
+| `pstack_script` | Runs bundled Node scripts by fixed id without Bun or shell scripts. |
 
-## 角色配置
+The `poteto-agent` and `comment-sicko` presets handle implementation delegation and read-only comment review. `pstack_script` can run five bundled scripts: `check-plan`, `watch-pr`, `worktree-audit`, `log`, and `statechart`. The script ids form a closed enum and cannot be used to build arbitrary paths.
 
-`/setup-pstack` 写入 `$DSH_HOME/pstack-models.md`，一行一个角色。`$DSH_HOME` 是 DSH 的用户目录。值可以是 `inherit-parent`，也可以是 `provider/model` 加推理档位。
+## Skills directory
 
-- `inherit-parent` 使用父会话的模型和推理档位。
-- panel 角色的值是列表，每一项启动一个子代理。
-- 删除某个角色的行，该角色回落到父路由。
-- 重新运行 `/setup-pstack` 会更新配置，不会叠加旧值。
+`skills/` is not an upstream pstack directory. It contains skills that pstack does not provide but real projects need. The source directories are `skills/authored/` and `skills/.agents/skills/`. The build publishes them to `dist/skills/authored/` and `dist/skills/vendored/`. `vendored` preserves open-source upstreams verbatim, while this repository maintains `authored`. References from pstack skills do not change these inclusion criteria.
 
-模型必须出现在当前 DSH 的 provider 和模型列表中。
+| Source | Skill | Purpose | Engineering capability added |
+|---|---|---|---|
+| `vendored` | `writing-for-agents` | Writes skills, `AGENTS.md`, `CLAUDE.md`, and documents referenced by pointers, covering context pointers, information hierarchy, and progressive disclosure. | Makes an agent document's trigger words, load order, and context cost predictable, and adds the writing path that Cursor's `create-skill` provides. |
+| `vendored` | `retro` | Reviews a coding session's environment, checking navigation, automation, coding conventions, tool economy, and information access. | Adds the environment check that pstack `/reflect` and `/correct` do not cover; it only reports and does not modify the repository. |
+| `authored` | `decision-write` | Writes, lands, and supersedes decision records in Draft and Land modes, requiring `Status` and `Implemented-by` to appear together. | Adds the decision lifecycle that real projects often lack. |
+| `authored` | `decision-audit` | Read-only audit of decision-record routing, status, scope, anchors, and supersession relationships. | Keeps decision records searchable and reviewable over time. |
+| `authored` | `setup-project-docs` | Sets up architecture, glossary, decisions, and the root `AGENTS.md` pointers, and can be run repeatedly to fill gaps. | Gives a new project a sustainable documentation entry point. |
 
-### 推理档位
+`vendored` skills come from `mattpocock/skills@59db609eb1e18aaf59b63284d0e52255aff0c63c`. [`skills/skills-lock.json`](./skills/skills-lock.json) records their sources, paths, and hashes. Both skill trees ship with the package, but they do not correspond to upstream pstack versions.
 
-角色行里的档位是那个角色**起步**用的档位。实际档位随任务难度双向浮动：
+## Optional DSH plugins
 
-- 调用 `pstack_subagent` 时传 `reasoningEffort`，覆盖本次派发中每个 panel 项的档位。难任务调高，机械活调低。
-- 子代理自己可以调 `set_reasoning_effort`，从下一步生效，已在飞行中的请求不受影响。
+DSH ships with the following plugins, which are disabled by default. dsh-pstack does not require them during installation. Some pstack flows need these plugins to run end to end. To enable a plugin, enter its package name in **Add plugin** on the Plugins page. Alternatively, run `dsh plugin --profile <profile> add <package>`, then restart the profile. Except for `@deepseek-ai/dsh-mcp-client`, the bundles and providers here are experimental.
 
-合法档位由目标模型自己广告。本包不假设通用阶梯，所以参数是自由字符串而不是枚举。值不被支持时，调用在启动任何子代理**之前**失败，并在错误里列出该模型真实支持的档位。panel 中任一项不支持时整次失败，不会只启动一半。
+> [!NOTE]
+> Without an optional plugin, the pstack skills still load. Steps that need the plugin print `Skipped in DeepSeek Harness: <step>. <reason>.` and continue. Missing `gh`, Java/TLC, or video tools also cause the corresponding steps to report blocked or degrade to screenshots. dsh-pstack never marks an unrun step as passed.
 
+### Sessions and isolation
 
-## 功能范围与已知限制
+| Plugin | Capability when enabled | Boundaries and conflicts |
+|---|---|---|
+| `@deepseek-ai/dsh-experimental-session-search` | Five read-only tools search and trace historical Sessions for `/recall`, `/reflect`, and `/show-me-your-work`: `session_search`, `session_event_search`, `session_trace`, `session_event_trace`, and `session_event_read`. | Matches only Sessions with the same `cwd`; use `session_event_search` for the current Session; there is no Cursor `.jsonl` transcript path. |
+| `@deepseek-ai/dsh-experimental-worktree`<br />`@deepseek-ai/dsh-experimental-tool-worktree` | `create_worktree` creates a local branch and worktree and switches the current Session directory, isolating parallel candidates for `/arena`, `/swarm`, and `/architect`. | `from` reads only local refs and does not fetch; there is no cloud VM; creating worktrees repeatedly changes `cwd`; it does not automatically give each subagent its own tree. |
+| `@deepseek-ai/dsh-experimental-forge-bundle` | PR panel, checks, review, mark ready, merge, and Session binding, plus starting a Session from the composer with a new worktree, serving `/babysit`, `/shipping`, and `/autopilot-*`. | GitHub only, requires `gh` login; there is no take tool on the model side; there is no stack verdict or `origin` CLI; it can coexist with the worktree bundle. |
 
-包含 55 个技能、23 个 playbook、24 个原则和两个子代理人格。
+### Verification and evidence
 
-- `make-bot-ui` 不在支持范围。它依赖 Cursor 的 webhook routine 和 secret request，DSH 没有等价闭环。
-- Cursor 专属能力没有等价物，包括 Automations、cloud agents、Custom Modes 和 Bugbot 配置。相关技能会在需要它们的步骤说明不支持，不伪造替代。
-- `/loop` 没有同名命令，也没有事件订阅，属于降级映射。能覆盖的是目标与定时输入：`create_goal` 记录目标和相位，`schedule_create` 只能作定时心跳，它把一条消息投回创建它的会话，不能盯着 PR 或 CI，子代理也无法自己布置。不能覆盖的是事件唤醒和云端存活：goal 不会自己感知外部事件，自动续跑还取决于 profile 是否挂载 goal round driver，未挂载时长时间任务只是同一个会话里被监督的运行。
-- `typescript-best-practices` 的 `paths` 自动触发不支持，需要时显式调用 `/typescript-best-practices`。
-- worktree 只隔离工作目录，不是 VM。schedule 是定时提醒，不是事件订阅。
-- 多模型评审需要配置真实不同的 route。只有同一 route 时，评审会标为同模型复核。
-- 子代理和 panel 会增加 token 消耗，只在需要严谨流程的任务上使用 `/poteto-mode`。
+Choose one of three browser providers: `@deepseek-ai/dsh-experimental-browser-use-stagehand-native`, `@deepseek-ai/dsh-experimental-browser-use-playwright-mcp`, or `@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp`.
 
-## 更新与卸载
+| Plugin | Capability when enabled | Boundaries and conflicts |
+|---|---|---|
+| `@deepseek-ai/dsh-browser-use` + one provider | Navigation, clicking, typing, screenshots, and ARIA snapshots; Stagehand also provides act, find, and extract, for verification skills and UI reproduction. | The base package does nothing without a provider; one provider per Session; screenshots need an image model; no video; Stagehand needs Chromium and a non-DeepSeek model. |
+| `@deepseek-ai/dsh-cua-bundle` | macOS app clicking, typing, screenshots, and permission pages, for desktop app verification. | macOS PTC only; Windows is incomplete; no video. |
+| `@deepseek-ai/dsh-experimental-terminal-bundle` | Six global terminal tools that keep a shell or REPL alive across calls and support background send, for CLI and TUI verification. | Terminal only; added to every Agent; persistent state must be cleaned up; switching invalidates the KV cache. |
+| `@deepseek-ai/dsh-mcp-client` | Mounts MCP servers; tools appear as `mcp__<server>__<tool>`, and `mcp-resources` lists servers with resources, serving evidence investigation for `/why` and `/teach`. | No default server; configuration is per server; no automatic category discovery. |
 
-升级：
+### Multi-agent
 
-```bash
-dsh plugin --profile <profile> add dsh-pstack@latest
-```
+| Plugin | Capability when enabled | Boundaries and conflicts |
+|---|---|---|
+| `@deepseek-ai/dsh-experimental-agent-team-profile` | Lead and teammate roles, a shared task board, nine team tools, and a Web roster, serving `/orchestrate` and `/autopilot-*`. | Disables `subagent` and `subagent_fork`. Conflicts with `pstack_subagent`. See the warning below. |
+| `@deepseek-ai/dsh-experimental-ralph-bundle` | Global `ralph`, a foreground loop with a fresh child each round, serving `/autonomous-run`. | Not a persistent loop in the same Session; no event watcher; does not replace goals, heartbeats, or the decision log. |
 
-卸载：
+> [!WARNING]
+> Do not enable `@deepseek-ai/dsh-experimental-agent-team-profile` and `pstack_subagent` in the same profile. The agent team plugin disables `subagent` and `subagent_fork`, and provides a second delegation entry point. Use only one subagent system per profile.
 
-```bash
-dsh plugin --profile <profile> remove dsh-pstack
-```
+## Compatibility
 
-角色文件在 DSH 用户目录，卸载不会删除它。不再使用时自行删除 `$DSH_HOME/pstack-models.md`。升级或卸载后按 DSH 提示重启会话。
+| Item | Version | Notes |
+|---|---|---|
+| DSH | `>=0.2.2-alpha.2` | Baseline `0.2.2-alpha.2`; newer versions are assumed compatible until the port needs a fix |
+| pstack | `0.15.36` | Upstream baseline commit `4dd1d05` |
+| Node.js | `>=24.21.1` | Runtime requirement |
+| Cordis | `~4.0.6-alpha.1` | Peer dependency |
 
-## 安全与数据
+Before upgrading DSH, verify experimental plugin package names, tool names, and configuration in a test profile. Upgrading upstream pstack requires regenerating the tree and rechecking the adaptation table.
 
-- 代理在 DSH 权限模型下读写文件、执行命令，子代理继承调用方的策略和权限边界。
-- 需要审批的操作按 DSH 配置请求确认。不要在无人值守任务中放宽不理解的权限。
-- 不要把 API key、token 或密码写进角色文件、prompt 或仓库。
-- 会话记录保存在 DSH 的会话存储中，pstack 不另建云端记录。
-- 上游技能可能要求访问网络或代码托管平台。是否允许由 DSH 的审批和沙箱配置决定。
+> [!CAUTION]
+> `pstack_script` runs on the Host's Node and bypasses bash approval and the filesystem sandbox. Treat it as a trusted entry point.
 
-## 故障排查
+A worktree Session has a different `cwd` from the original Session. The session-search plugin only matches the exact `cwd`, so search for old Sessions from their original directory.
 
-按顺序检查。
+## How it works
 
-1. 确认 DSH 版本在支持范围内。
-2. 确认 worktree 插件可用，必要时先手动启用一次。
-3. 确认当前 profile 没有同时启用 Agent Team。
-4. 运行 `/setup-pstack` 检查角色配置。
-5. 仍有问题时在 [GitHub Issues](https://github.com/l246804/dsh-pstack/issues) 提交，附 DSH 版本、profile 名、复现步骤和错误信息。不要贴密钥或私有会话内容。
+Upstream pstack adapts Claude Code with `docs/harness/claude-code.md`. It preserves the skill bodies. A separate host adaptation table maps `Task`, `AskQuestion`, todo, model slugs, and paths to the target host. The generator adds a one-line Claude Code adaptation note to skills that use Cursor names. Unsupported capabilities report `Skipped in Claude Code: <step>. <reason>.`
 
-## 许可证与上游归属
+dsh-pstack follows the same approach. The main adaptation document is [`pstack/harness/docs/harness/dsh.md`](./pstack/harness/docs/harness/dsh.md). It covers Tools, Subagent fields, Models, setup-pstack, Paths, and Cursor-only features. The `pstack_*` tools, agent presets, and Node scripts replace fields that DSH lacks. At build time, upstream pstack and the local adaptation tree are rendered into `pstack/pstack/`, then packaged with `src/*.ts` and `skills/` into `dist/`.
 
-MIT，见 [LICENSE](LICENSE)。
+## Credits
 
-上游 pstack 版权归 Lauren Tan，使用 MIT 许可证。技能、playbook 和代理文本来自 [cursor/plugins](https://github.com/cursor/plugins/tree/main/pstack)。
+- [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 all come from upstream.
+- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) is provided by the DeepSeek team. DSH's plugin, bundle, agent preset, subagent, and tool host interfaces let this port land as native tools.
+- [mattpocock/skills](https://github.com/mattpocock/skills) provides the vendored `writing-for-agents` and `retro` skills.
+
+This project is a community port, not an official Cursor or DeepSeek release. Upstream pstack and DSH are both MIT licensed.
+
+## License
+
+[MIT](./LICENSE) License © [leiwang](https://github.com/l246804)

package/README.zh.md

@@ -0,0 +1,185 @@
+<p align="center">
+  <img src="./assets/logo.png" width="144" alt="dsh-pstack logo" />
+</p>
+
+<h1 align="center">dsh-pstack</h1>
+
+<p align="center">
+  <strong>把 pstack 的严格代理工作流带进 DeepSeek Harness</strong>
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> · 中文
+</p>
+
+<p align="center">
+  <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://npmx.dev/package/dsh-pstack"><img src="https://img.shields.io/npm/dm/dsh-pstack?style=flat-square&colorA=080f12&colorB=1fa669" alt="npm downloads" /></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/dsh-0.2.2--alpha.2-1f6feb?style=flat-square" alt="dsh 0.2.2-alpha.2" /></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>
+</p>
+
+<p align="center">
+  <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://bundlephobia.com/result?p=dsh-pstack"><img src="https://img.shields.io/bundlephobia/minzip/dsh-pstack?style=flat-square&colorA=080f12&colorB=1fa669&label=minzip" alt="minzip size" /></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="JSDocs" /></a>
+</p>
+
+<div align="center">
+  <table>
+    <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>4</strong><br /><sub>原生工具</sub></td>
+      <td align="center"><strong>2</strong><br /><sub>agent preset</sub></td>
+      <td align="center"><strong>5</strong><br /><sub>随包脚本</sub></td>
+    </tr>
+  </table>
+</div>
+
+<p align="center">
+  <a href="#快速开始">快速开始</a> ·
+  <a href="#能力">能力</a> ·
+  <a href="#skills-目录">skills 目录</a> ·
+  <a href="#可选-dsh-插件">可选 DSH 插件</a> ·
+  <a href="#兼容性">兼容性</a>
+</p>
+
+`dsh-pstack` 是 [pstack](https://github.com/cursor/plugins/tree/main/pstack) 的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）移植。它保留上游 pstack 的技能、playbook 与参考文档。4 个原生工具替代 DSH 缺少的接口，适配层则把 Cursor 的工具名、子代理字段、模型 slug 和路径映射到 DSH。
+
+上游 pstack 的技能大多声明 `disable-model-invocation: true`。`poteto-mode` 按名称路由到这些隐藏技能，但 DSH 的 `skill` 工具只暴露模型可见目录。DSH 也没有与 Cursor 的模型 slug、`subagent_type`、`readonly` 和 Bun 脚本对等的接口。dsh-pstack 在插件层处理这些差异，安装后可以从 `/poteto-mode` 开始工作。
+
+完整能力映射、缺口和验收状态见 [`pstack/README.md`](./pstack/README.md)。
+
+> [!IMPORTANT]
+> 此版本以 DSH `0.2.2-alpha.2` 为基准、要求 Node.js `>=24.21.1`。`engines.dsh` 为 `>=0.2.2-alpha.2` 范围：默认认为更高版本兼容，只有移植内容需要修复时才提高版本要求。安装或升级前请先查看 [兼容性](#兼容性)。
+
+## 快速开始
+
+1. 安装插件：
+
+   ```sh
+   dsh plugin --profile web add dsh-pstack
+   ```
+
+   也可以在 Web 或 Desktop 的 Plugins 页面安装。
+
+2. 重启对应的 profile，或新开一个 Session。
+
+3. 首次使用前运行：
+
+   ```text
+   /setup-pstack
+   ```
+
+   该命令读取当前部署提供的 provider、model 与 reasoning effort，并写入 `$DSH_HOME/pstack-models.mdc`。缺少这个文件时，所有角色继承父级路由。
+
+### 常用入口
+
+| 命令 | 用途 |
+|---|---|
+| `/poteto-mode` | 主工作流入口，按任务匹配 playbook，维护 todo 与证据 |
+| `/setup-pstack` | 配置角色模型，初始化 pstack 使用环境 |
+| `/how`、`/why`、`/teach` | 架构走查、证据调查、渐进式讲解 |
+| `/architect`、`/arena`、`/swarm` | 多方案设计、并行候选、切片并行实现 |
+| `/create-verification-skill` | 为真实项目生成验证技能 |
+| `/statechart` | 用 TLA+ 与 TLC 检查状态模型，输出 Mermaid 状态图 |
+| `/show-me-your-work` | 维护 TSV 决策日志，审计当前工作 |
+| `/retro` | 对一次编码会话做环境复盘 |
+
+## 能力
+
+### 原生工具
+
+| 工具 | 作用 |
+|---|---|
+| `pstack_skill` | 按名称加载本插件注册的隐藏技能，也能读取技能目录内的相对资源。 |
+| `pstack_models` | 只读列出 DSH 实际提供的 provider、model 和 effort，供 `/setup-pstack` 使用。 |
+| `pstack_subagent` | 按角色读取 `$DSH_HOME/pstack-models.mdc`，解析 `provider/model [effort]`，按 `agent` 选择 preset，一次可启动多个子代理。 |
+| `pstack_script` | 用固定 id 运行随包 Node 脚本，不依赖 Bun 或 shell 脚本。 |
+
+`poteto-agent` 和 `comment-sicko` 两个 preset 分别负责实现型委派与只读评论审查。`pstack_script` 可以运行 `check-plan`、`watch-pr`、`worktree-audit`、`log`、`statechart` 五个随包脚本，脚本 id 是封闭枚举，不能拼任意路径。
+
+## skills 目录
+
+`skills/` 不是 pstack 上游目录。它只收 pstack 没提供、真实项目开发中又需要的技能。源目录是 `skills/authored/` 和 `skills/.agents/skills/`，构建后分别发布到 `dist/skills/authored/` 和 `dist/skills/vendored/`。`vendored` 逐字保留开源上游，`authored` 由本仓维护。pstack 技能对它们的引用只是使用关系，不改变收录标准。
+
+| 来源 | 技能 | 作用 | 补充的工程能力 |
+|---|---|---|---|
+| `vendored` | `writing-for-agents` | 写技能、`AGENTS.md`、`CLAUDE.md` 与被指针引用的文档，覆盖 context pointer、信息层级和渐进披露。 | 让 agent 文档的触发词、加载顺序和上下文成本可预测，也补上 Cursor `create-skill` 的写作路径。 |
+| `vendored` | `retro` | 对一次编码会话做环境复盘，检查导航、自动化检查、编码规范、工具经济与信息获取。 | 补上 pstack `/reflect`、`/correct` 没覆盖的环境体检，只出报告，不改仓库。 |
+| `authored` | `decision-write` | 决策记录的写入、落地和取代，Draft 与 Land 两种模式，`Status` 与 `Implemented-by` 必须成对。 | 补上真实项目常缺的决策生命周期。 |
+| `authored` | `decision-audit` | 只读审计决策记录的路由、状态、Scope、锚点与取代关系。 | 让决策记录持续可检索、可复核。 |
+| `authored` | `setup-project-docs` | 搭建 architecture、glossary、decisions 与根 `AGENTS.md` 指针，可重复补齐。 | 给新项目一套可持续的项目文档入口。 |
+
+`vendored` 技能来自 `mattpocock/skills@59db609eb1e18aaf59b63284d0e52255aff0c63c`，来源、路径和哈希记录在 [`skills/skills-lock.json`](./skills/skills-lock.json)。两棵技能树都随包发布，但和 pstack 上游版本没有对应关系。
+
+## 可选 DSH 插件
+
+以下插件随 DSH 提供，默认关闭。安装 dsh-pstack 时不要求安装这些插件，但部分 pstack 流程需要它们才能完整执行。要启用插件，在 Plugins 页面用 **Add plugin** 输入包名。也可以运行 `dsh plugin --profile <profile> add <package>`，然后重启 profile。除 `@deepseek-ai/dsh-mcp-client` 外，本节列出的 bundle 与 provider 都是实验性的。
+
+> [!NOTE]
+> 未启用可选插件时，pstack 技能仍可加载。需要插件的步骤会输出 `Skipped in DeepSeek Harness: <step>. <reason>.` 后继续。缺少 `gh`、Java/TLC 或视频工具时，对应步骤会报告 blocked 或降级为截图。dsh-pstack 不会把未运行的步骤标记为通过。
+
+### 会话与隔离
+
+| 插件 | 打开后的能力 | 边界与冲突 |
+|---|---|---|
+| `@deepseek-ai/dsh-experimental-session-search` | 5 个只读工具：`session_search`、`session_event_search`、`session_trace`、`session_event_trace`、`session_event_read`，搜索和追踪历史会话，服务 `/recall`、`/reflect`、`/show-me-your-work`。 | 只匹配同一 `cwd` 的会话；当前会话用 `session_event_search`；没有 Cursor 的 `.jsonl` 转写路径。 |
+| `@deepseek-ai/dsh-experimental-worktree`<br />`@deepseek-ai/dsh-experimental-tool-worktree` | `create_worktree` 建本地分支和工作树，切换当前 Session 目录，用于 `/arena`、`/swarm`、`/architect` 的并行候选隔离。 | `from` 只读本地 ref，不 fetch；无云 VM；连续建树会改 `cwd`；不会自动给每个子代理分树。 |
+| `@deepseek-ai/dsh-experimental-forge-bundle` | PR 面板、checks、review、mark ready、merge、Session 绑定，也能从 composer 用新 worktree 启动 Session，服务 `/babysit`、`/shipping`、`/autopilot-*`。 | 仅 GitHub，需 `gh` 登录；模型侧没有 take 工具；没有 stack verdict，也没有 `origin` CLI；可与 worktree bundle 共存。 |
+
+### 验证与证据
+
+浏览器 provider 三选一：`@deepseek-ai/dsh-experimental-browser-use-stagehand-native`、`@deepseek-ai/dsh-experimental-browser-use-playwright-mcp`、`@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp`。
+
+| 插件 | 打开后的能力 | 边界与冲突 |
+|---|---|---|
+| `@deepseek-ai/dsh-browser-use` + 一个 provider | 导航、点击、输入、截图和 ARIA snapshot；Stagehand 另有 act、find、extract，用于验证技能和 UI 复现。 | 基础包没有 provider 时不生效；每个 Session 一个 provider；截图要图像模型；无视频；Stagehand 需要 Chromium 和非 DeepSeek 模型。 |
+| `@deepseek-ai/dsh-cua-bundle` | macOS 应用点击、输入、截图和权限页，用于桌面应用验证。 | 仅 macOS PTC；Windows 未完成；无视频。 |
+| `@deepseek-ai/dsh-experimental-terminal-bundle` | 6 个全局终端工具，跨调用保持 shell / REPL，支持后台 send，用于 CLI / TUI 验证。 | 只覆盖终端；会加到所有 Agent；持久状态要清理；切换会失效 KV cache。 |
+| `@deepseek-ai/dsh-mcp-client` | 挂载 MCP server，工具以 `mcp__<server>__<tool>` 出现，`mcp-resources` 列出带资源的 server，服务 `/why`、`/teach` 的证据调查。 | 无默认 server；需逐项配置；无自动类别发现。 |
+
+### 多代理
+
+| 插件 | 打开后的能力 | 边界与冲突 |
+|---|---|---|
+| `@deepseek-ai/dsh-experimental-agent-team-profile` | Lead / teammate、共享任务板、9 个团队工具和 Web roster，服务 `/orchestrate`、`/autopilot-*`。 | 禁用 `subagent` 和 `subagent_fork`，与 `pstack_subagent` 冲突。见下方警告。 |
+| `@deepseek-ai/dsh-experimental-ralph-bundle` | 全局 `ralph`，每轮 fresh child 的 foreground 循环，服务 `/autonomous-run`。 | 不是同一 Session 常驻循环；无事件 watcher；不替代 goal、心跳和 decision log。 |
+
+> [!WARNING]
+> 不要在同一 profile 中同时启用 `@deepseek-ai/dsh-experimental-agent-team-profile` 和 `pstack_subagent`。agent team 插件会禁用 `subagent` 和 `subagent_fork`，并提供另一套委派入口。每个 profile 只使用一套子代理系统。
+
+## 兼容性
+
+| 项目 | 版本 | 说明 |
+|---|---|---|
+| DSH | `>=0.2.2-alpha.2` | 基准 `0.2.2-alpha.2`；默认认为更高版本兼容，移植内容需要修复时再提高要求 |
+| pstack | `0.15.36` | 上游基线提交 `4dd1d05` |
+| Node.js | `>=24.21.1` | 运行时要求 |
+| Cordis | `~4.0.6-alpha.1` | peer dependency |
+
+升级 DSH 前，先在测试 profile 中验证实验性插件的包名、工具名和配置。升级上游 pstack 需要重新生成树并复核适配表。
+
+> [!CAUTION]
+> `pstack_script` 使用 Host 的 Node 运行，会绕过 bash 审批和文件系统沙箱。请将其视为受信入口。
+
+worktree Session 的 `cwd` 与原 Session 不同。session-search 插件只匹配完全相同的 `cwd`，因此要在原目录搜索旧 Session。
+
+## 实现方式
+
+上游 pstack 用 `docs/harness/claude-code.md` 适配 Claude Code。它保留技能正文，另用宿主适配表把 `Task`、`AskQuestion`、todo、模型 slug 和路径映射到目标宿主。生成器为使用 Cursor 名称的技能添加一行 Claude Code 适配提示。不支持的能力会报告 `Skipped in Claude Code: <step>. <reason>.`
+
+dsh-pstack 沿用这套做法。主适配文档是 [`pstack/harness/docs/harness/dsh.md`](./pstack/harness/docs/harness/dsh.md)，覆盖 Tools、Subagent fields、Models、setup-pstack、Paths 和 Cursor-only features。`pstack_*` 工具、agent preset 和 Node 脚本替代 DSH 缺少的字段。构建时，上游 pstack 与本地适配树被渲染到 `pstack/pstack/`，再与 `src/*.ts`、`skills/` 一起打包到 `dist/`。
+
+## 鸣谢
+
+- [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`。
+
+本项目是社区移植，不是 Cursor 或 DeepSeek 官方发行。上游 pstack 与 DSH 均为 MIT License。
+
+## License
+
+[MIT](./LICENSE) License © [leiwang](https://github.com/l246804)

package/cordis.patch.yml

@@ -1,39 +1,109 @@
 # dsh-pstack bundle patch.
 #
-# `pstack` registers the bundled skill provider. `pstack-subagent` registers
-# `pstack_subagent`, which starts one child per activation and re-reads the role
-# file on every delegation. `pstack-history` registers `pstack_history`, the
-# restricted read-only history tool; it reads raw events through `sessionQuery`
-# and authorizes the caller and its direct children only.
+# `pstack` registers the bundled skill provider and `pstack_skill`, the trusted loader
+# that can reach skills hidden with `disable-model-invocation`.
+# `pstack-models` registers the read-only model/effort directory used by `/setup-pstack`.
+# `pstack-subagent` registers `pstack_subagent`, which re-reads the role file on every
+# delegation and selects one of the pstack agent presets below.
+# `pstack-script` registers `pstack_script`, the only supported way to run the bundled
+# Node artefacts under both the npm CLI and the Desktop (Electron) runtime.
 #
-# The two worktree rows carry the README promise that worktree support ships as a
-# necessary dependency: the bundle turns the official integration on when the
-# profile does not have it, and mounts nothing when it does. `disabled: !!js` is
-# evaluated by the Loader at every mount decision, and each expression reads the
-# composed row list rather than a startup snapshot. The row handle is
-# `ctx[Symbol.for('cordis.entry')]` (this entry), not `ctx.fiber.entry`, which
-# resolves to the enclosing `include` row and therefore never sees these siblings.
-# `scripts/worktree-mount.ts` owns the text of both expressions and `check:assets`
-# fails when this file drifts from it. See
-# docs/decisions/2026-10-26-worktree-guard-reads-own-entry.md.
-#
-# `pstack-history` is appended after the unit-4 rows so no delivered line moves.
-# Row order is not part of the history contract; the two worktree guards, by
-# contrast, stay adjacent and byte-identical to their generator.
+# The two presets are ordinary `@deepseek-ai/dsh-agent-preset` declarations. They own the
+# child persona and tool composition; `pstack_subagent` only passes `agentPreset`. Keeping
+# the tool list here is what makes `comment-sicko` read-only without a per-call field:
+# `dsh-tool-fs` registers `read` but not `write` or `edit`.
 - insert:
     - id: pstack
       name: dsh-pstack
+    - id: pstack-models
+      name: dsh-pstack/models
     - id: pstack-subagent
       name: dsh-pstack/subagent
       config:
         maxDepth: 2
-    - id: pstack-worktree
-      name: '@deepseek-ai/dsh-experimental-worktree'
-      disabled: !!js "(() => { const own = ctx[Symbol.for('cordis.entry')]; const rows = own && own.parent && own.parent.data; if (!Array.isArray(rows)) return false; return rows.some((row) => row !== null && typeof row === 'object' && row.id !== 'pstack-worktree' && row.name === '@deepseek-ai/dsh-experimental-worktree' && row.disabled !== true) })()"
-    - id: pstack-tool-worktree
-      name: '@deepseek-ai/dsh-experimental-tool-worktree'
-      disabled: !!js "(() => { const own = ctx[Symbol.for('cordis.entry')]; const rows = own && own.parent && own.parent.data; if (!Array.isArray(rows)) return false; return rows.some((row) => row !== null && typeof row === 'object' && row.id !== 'pstack-tool-worktree' && row.name === '@deepseek-ai/dsh-experimental-tool-worktree' && row.disabled !== true) })()"
-    - id: pstack-history
-      name: dsh-pstack/history
     - id: pstack-script
       name: dsh-pstack/script
+    - id: preset-poteto-agent
+      name: "@deepseek-ai/dsh-agent-preset"
+      config:
+        id: poteto-agent
+        name: pstack poteto-agent
+        description: pstack implementation delegate. Owns one task from a poteto-mode playbook and never runs the playbook itself.
+        order: 100
+        plugins:
+          - id: persona
+            name: "@deepseek-ai/dsh-persona"
+            config:
+              prefix: |
+                You are operating as poteto-mode's full agent style. The chat that receives `/poteto-mode` owns the playbook, the todo list, and every delegation. You are one of its delegates. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Use the absolute path your parent gave you. Your skill catalog hides this skill, so a missing catalog entry does not mean pstack is absent. Navigate to a leaf `principle-*` skill whenever you apply that principle.
+          - id: tool-bash
+            name: "@deepseek-ai/dsh-tool-bash"
+            disabled: !!js process.platform === 'win32'
+          - id: tool-pwsh
+            name: "@deepseek-ai/dsh-tool-pwsh"
+            disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: "@deepseek-ai/dsh-tool-fs"
+          - id: tool-fs-search
+            name: "@deepseek-ai/dsh-tool-fs-search"
+          - id: tool-todo
+            name: "@deepseek-ai/dsh-tool-todo"
+            config:
+              allowParallelInProgress: true
+          - id: tool-jobs
+            name: "@deepseek-ai/dsh-tool-jobs"
+          - id: tool-web
+            name: "@deepseek-ai/dsh-tool-web"
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+    - id: preset-comment-sicko
+      name: "@deepseek-ai/dsh-agent-preset"
+      config:
+        id: comment-sicko
+        name: pstack comment-sicko
+        description: Read-only comment reviewer. Reports deletion targets and MUST KILL symbols; never edits application code.
+        order: 101
+        plugins:
+          - id: persona
+            name: "@deepseek-ai/dsh-persona"
+            config:
+              prefix: |
+                My first output when spawned is exactly this.
+
+                Yes... Ha ha ha... Yes!
+
+                I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
+
+                Only these exceptions get to crawl away.
+
+                - Legal or license headers.
+                - Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
+                - `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
+                - Doc comments that define a public API contract.
+                - Issue or RFC links that explain a constraint code cannot express.
+
+                That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
+
+                `eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
+
+                `IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
+
+                A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
+
+                Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
+
+                Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.
+          - id: tool-bash
+            name: "@deepseek-ai/dsh-tool-bash"
+            disabled: !!js process.platform === 'win32'
+          - id: tool-pwsh
+            name: "@deepseek-ai/dsh-tool-pwsh"
+            disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: "@deepseek-ai/dsh-tool-fs"
+            config:
+              write: false
+              edit: false
+          - id: tool-fs-search
+            name: "@deepseek-ai/dsh-tool-fs-search"