openfeel 1.2.4 → 1.3.0

package/README.en.md

@@ -2,9 +2,11 @@
 
 [中文](README.zh-CN.md) | [Changelog](CHANGELOG.md) | [npm](https://www.npmjs.com/package/openfeel) | [Getting Started](docs/GETTING_STARTED.md)
 
+> 📚 Version capability overview (Chinese with English highlights): [docs/VERSIONS.md](docs/VERSIONS.md) | Per-version details: [CHANGELOG.md](CHANGELOG.md)
+
 OpenFeel is a TypeScript CLI tool for end-to-end process governance in AI Agent development. Core philosophy: **"Slim prompts, process in tools"** — agents understand workflows by reading `flow.json` state, not long text documents.
 
-> **Current adapter harness**: **opencode (default)** ｜ **Claude Code** (`--tools claude`, since v1.1.6); the framework targets multi-harness support (other adapters reserved).  
+> **Current adapter harness**: **opencode (default)** ｜ **Claude Code** (`--tools claude`, since v1.1.6) ｜ **DSH** (`--tools dsh`, since v1.3.0); the framework targets multi-harness support (other adapters reserved).  
 > **Default Model Config**: DeepSeek V4 (primary reasoning) + GLM-5.3-flash (cross-review) + DeepSeek-flash (multimodal vision).  
 > `openfeel init` auto-detects registered models and guides configuration.
 >
@@ -60,6 +62,23 @@ openfeel plan scheme create stage-01 "Implement core features"
 openfeel flow status
 ```
 
+## Recommended Usage: Requirement-driven + Fast Iteration
+
+> Use **fast** by default for day-to-day work: one plan review and one code review, skipping scheme/test. Use **full** for large or architectural changes.
+
+```bash
+openfeel req add "Add a feature" --workflow-mode fast            # 1. Publish a requirement
+openfeel req claim REQ-NNN                                       # 2. Claim it
+openfeel plan stage add vX.Y.Z-stage-NN --workflow-mode fast     # 3. Create a fast stage
+openfeel req link --stage vX.Y.Z-stage-NN --requirement REQ-NNN  # 4. Link them
+openfeel flow next                                               # 5. Iterate as scheduled
+```
+
+- **fast (recommended)**: daily iteration; keeps plan review and code review, skips scheme/test;
+- **full**: large / architectural changes, all six gates;
+- **general**: pipeline-free ad-hoc work, requirement-level only;
+- requirements auto-close once every linked stage is done.
+
 ## Claude Code Adapter (since v1.1.6)
 
 > Coexists with the opencode adapter; **disabled by default** (requires explicit `--tools claude`).
@@ -69,92 +88,39 @@ openfeel flow status
 - **Upgrade**: `npm i -g openfeel@latest` → `openfeel setup --tools claude`; **after the first creation of `~/.claude/{agents,skills}`, restart the session or run `/reload-skills`** to load new skills/agents; `CLAUDE.md` takes effect on the **next session**. `npm i -g` alone does not refresh global assets.
 - **Zero-touch by default**: without `--tools`, `~/.claude/` is **unchanged**.
 
+## DSH Adapter (since v1.3.0)
+
+> Coexists with the opencode / Claude Code adapters; **not deployed by default**. The adapter ships inside the single `openfeel` package.
+
+```bash
+npm i -g openfeel@latest      # 1. Install/upgrade (single package, includes dsh/)
+openfeel setup --tools dsh    # 2. Deploy into DSH profiles (all by default; use --dsh-profile web)
+# 3. Restart the DSH host
+```
+
+- Writes `<DSH_HOME>/profiles/<name>/package.json`: `dependencies["openfeel-dsh"] = "link:<openfeelRoot>/dsh"` plus `dsh.profile.bundles += "openfeel-dsh"`, and runs `pnpm install` when needed (skipped when the dependency is unchanged and the link is valid).
+- Requires DSH `0.2.0-rc.2`, Node ≥ 20.17, an existing DSH profile, and a global `openfeel` on PATH.
+- Upgrade: `npm i -g openfeel@latest` → restart DSH; the `link:` points at the same path and follows the package.
+- For development you can `link:` the repository `dsh/` directly; see [dsh/README.md](dsh/README.md) and [dsh/ADAPTER.md](dsh/ADAPTER.md).
+- `openfeel update --tools dsh` does not apply (DSH is a global deployment).
+
 ## Fast Iteration Mode (since v1.1.7)
 
 > **Coexists** with the full pipeline; new deployments default to **fast** (`config.yaml defaults.workflow_mode`), overridable per stage.
 
 - **Fast line**: `plan_pending → plan_review → plan_passed → exec_running → review_pending → review_passed → archiving → done` (skips 6 phases: `scheme_*` / `test_*`; **plan review and code review each keep a single round**; `review_failed` loops back for retries).
-- **Choose and switch**: `openfeel plan stage add <name> --workflow-mode full|fast|general` (new stage); `openfeel stage set <stage> --workflow-mode full|fast|general` (per-stage switch); `openfeel config set defaults.workflow_mode full|fast|general` (project-level default memory). **`general` is requirement-level only** (since v1.2.1; see "What's New in v1.2.1").
+- **Choose and switch**: `openfeel plan stage add <name> --workflow-mode full|fast|general` (new stage); `openfeel stage set <stage> --workflow-mode full|fast|general` (per-stage switch); `openfeel config set defaults.workflow_mode full|fast|general` (project-level default memory). **`general` is requirement-level only** (since v1.2.1; see [docs/VERSIONS.md](docs/VERSIONS.md)).
 - **Inspect (read-only)**: `openfeel flow mode [--stage <id>] [--json]` (current mode + source); `openfeel flow phases [--mode full|fast|general] [--stage <id>]` (view the transition table per mode).
 - **Auto-advance enabled by default**: new deployments default to `auto_advance: enabled` (since v1.1.7); to disable: `openfeel config set auto_advance disabled`.
 
 Upgrade/migration notes: see [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) ("工作流模式（full / fast）与自动推进" section, Chinese) and [CHANGELOG.md](CHANGELOG.md) `[1.1.7]`.
 
-## What's New in v1.2.4 (Patch)
-
-> Stage covered: **stage-100**. This patch closes `dsh/ACTION-GUIDE.md` A1~A5; the JSON contract now counts **40 successful exports / 41 registered options**, and exit-code semantics 0/1/2/3 are unchanged. This repository's closure baseline: **75 test files / 1941 cases / 21 stages**.
-
-- **A1 archive overwrite protection (data safety)**: `openfeel archive <stage>` refuses to overwrite an existing archive file (`ARCHIVE_EXISTS` / `refusal` / exit 1 with **zero writes**: archive content hash, `flow.json` revision, `log[]` length and KB entry count all unchanged); explicit `--force` is required to overwrite. Protection is **per archive file** (short/full aliases derive different files and do not trigger each other).
-- **A2 `plan stage list --json` (#34)**: `{schemaVersion,stages,count}`; each stage has seven keys `id,phase,status,deps,workflowMode,opsTotal,opsDone` (flow.json registered-stage scheduling view).
-- **A3 `model list|get --json` (#35/#36)**: list `{schemaVersion,scope,agents:[{agent,provider,model,source}]}`; get returns six keys; `provider`/`model` split at the first `/`, `source` is the effective layer (default > project > global).
-- **A4 three command surfaces (#37~#40)**: `flow retry --op <id> --json`, `lint i18n|kb --json` (`ok:false` is still a success document plus exit 1), and `roadmap show [version] --json` (header-driven milestones, 3/4-column compatible).
-- **A5 `config get --all --json`**: read all project defaults at once (`defaults` with four keys); `key-required` no longer applies; conflicting combinations return `INVALID_ARGUMENT`.
-- **Contract**: error table grows to **13 rows** (adds `ARCHIVE_EXISTS`); existing exports keep their keys/order and human output is unchanged; `dsh/` untouched.
-
-## Fixes in v1.2.3 (Patch)
-
-> Stage covered: **stage-99**. This patch closes the items carried out of v1.2.2 and adds no new features; the 33 successful exports / 34 registered options contract and exit-code semantics are unchanged. This repository's closure baseline: **75 test files / 1911 cases / 21 stages**.
-
-- **Unified concurrent JSON exit (REV-95-009)**: the `handleConcurrentConflict` JSON branch now emits the `FLOW_CONCURRENT_CONFLICT` envelope, sets `process.exitCode=2`, and returns (same mechanism as `failCli`, avoiding stdout truncation on Windows pipes); the non-JSON branch is unchanged verbatim; all 10 call sites return without fallthrough.
-- **`--review-tier` help-text correction (REV-98-003 item 6)**: `flow advance --help` and the zh/en i18n entries now say "default = full (zero pruning)" instead of "derived from the workflow mode"; the mode-derived value is the `flow phases --json.reviewTier` display value; default advance behavior is unchanged.
-- **`req` filter single-sourcing (REV-97-006)**: `req show` / `req set --workflow-mode` reuse `listLinkedStages`; `req split` and the core done primitives remain unchanged; behavior is identical.
-- **Lock-timeout E2E test hook (REV-98-006①, test-only)**: an env seam active only when `OPENFEEL_TEST_MODE=1` makes the timeout path assert `INTERNAL_ERROR/internal/3` deterministically; production defaults remain 5000/3000ms.
-
-## What's New in v1.2.2
-
-> Stages covered: **stage-95 ~ 98**. All capabilities below are **available since v1.2.2**; `docs/json-contract.md` is the single authority for the JSON contract (33 successful exports / 34 registered options). This repository's closure baseline: 74 test files / 1894 cases / 21 stages.
-
-- **`openfeel flow next [--json]` (decision authority, read-only)**: 12 keys in fixed order (`schemaVersion,stage,phase,phaseLabel,responsibleAgent,workflowMode,reviewTier,effectiveReviewTier,legalNextPhases,suggestedCommand,guards,blockingReviews`); `responsibleAgent` shares the same source as `mapPhaseToAgent`; every element of `legalNextPhases` is accepted by `flow advance`; zero writes.
-- **Global `--project <path>`**: leading/trailing/`=` forms before or after any command; semantically equivalent to cwd; language resolves from the target project while `--log-file` relative paths resolve from the original cwd; `knowledge dedup` keeps its local declaration (syntactically compatible).
-- **Full read-command `--json` coverage**: 13 command surfaces (`stage status` / `flow recover` / `flow checkpoint list` / `flow log` / `project overview` / `knowledge search|list|index|dedup` / `config get|effective` / `view list` / `plan scheme list`) plus `archive <stage> --json`; **33 successful exports / 34 registered options** in total.
-- **Machine-readable error envelope**: `{schemaVersion:1,error:{code,kind,message,detail}}`; exit codes **0 success / 1 expected refusal / 2 concurrent conflict / 3 internal error (new)**; legacy `{error:'...'}` keeps the string type and key order, appending `errorKind` at the end; 12-row `code→kind→exitCode` mapping.
-- **`--version --json`**: `{schemaVersion:1,version,node}` (three keys; listed separately, not counted among the 33 exports/34 options).
-- **`flow archive --dry-run --json` criteria details + `archive <stage> --json`**: `eligible` / `unfinishedStages` / `blockingReviews`; `archivePath` / counts; `--dry-run` writes nothing.
-- **`reviewTier` disambiguation**: `flow phases --json` / `flow status.stages[]` / `flow next` now expose both the display value `reviewTier`/`displayReviewTier` and the effective value `effectiveReviewTier` (always `full`). **Correction**: when `flow advance` is not given an explicit `--review-tier`, the effective tier is always **`full`** (not derived from the mode); the mode-derived value is `flow phases --json.reviewTier` (display only). Source help-text correction moves to v1.2.3.
-- **Compatibility promise**: the existing 19 successful export field sets are unbroken (additive only); human output is unchanged verbatim; exit codes 0/1/2 keep their semantics while 3 is new only; the 15-phase enum / `advanceAccepted` / full-fast behavior are unchanged; existing `flow.json` files need zero migration and receive zero injection; REQ-001 L80 ("2 = internal or usage error") is registered as a requirement-text erratum (authoritative wording in contract §2/§10).
-
-## What's New in v1.2.1
-
-> Stages covered: **stage-86 ~ 93 + 94** (94 = out-of-table supplementary stage: model defaults and non-destructive deployment). All capabilities below are **available since v1.2.1**.
-
-- **Three-mode architecture (`full` / `fast` / `general`)**: the `workflow_mode` value domain grows from 2 to 3 values (default remains `fast`). `general` (no pipeline) is **requirement-level only** — stage-level / deployment-level write surfaces reject it (explicit command-layer gates in `plan stage add` / `stage set` / `config set`; wizard offers no such option); the resolution chain gains a "requirement" layer (`status.md > requirement > config.yaml > builtin`); **upgrades only, never implicit downgrades**.
-- **Requirement intake and splitting (`openfeel req split`)**: **splitting publishes** — children enter `scheduled` in one shot; `parent_id` is traceability-only (**not in aggregation / not in the done gate / not in `PATCH_WHITELIST`**); parallel intake (`claim` never blocks); **requirements are decoupled from versions** (`target_version` is display / filter / sort only, never a gate). The `req` command group grows **10 → 11 subcommands**.
-- **Direct dispatch of general workers (two dialects)**: opencode = nested `task` tool; Claude Code = direct Handoff. In general mode any Agent can accept **directly dispatched** execution work.
-- **New agent `openfeel-explorer` (read-only)**: dedicated "research / exploration" route — 4 read-only tools (Read / Glob / Grep / Bash); agent count **9 → 10**.
-- **Observability**: `metrics.json` wired via `recordRun`; CLI logs carry `duration_ms` / `project` / `session_id`; op-level timestamps; cross-session resume marker (`resumed`).
-- **Review tiers (`--review-tier <full|lean|skip>`)**: an axis **orthogonal** to workflow mode — the mode picks the base table, the tier prunes review gates (`full` prunes nothing / `lean` prunes `scheme_review` / `skip` prunes `plan_review + scheme_review`; code review, test and archiving gates are always kept). Defaults derive from the mode (`full`→`full` / `fast`→`lean` / `general`→`full`). `flow phases --json` appends `reviewTier` last (existing 6 keys unchanged verbatim, **7 keys total**).
-- **Parallel orchestration contract + lightweight archiving**.
-- **Unified model defaults + non-destructive deployment (user-sovereign `model` key)**: deployment (`setup` / `update`) **creates the user's `model` key when absent and never overwrites it**.
-
-### Bug Fixes (v1.2.1)
-
-- **`req/BUG-002`**: the **completion path for `general` requirements** — a `general` requirement always has zero linked stages (bidirectional carrier gate) while the done gate demands all linked stages done; the two crossed and left `general` requirements **permanently unable to reach `done`**. A **dual completion path** is now provided (criterion = the requirement's own `workflow_mode` field, same source as the carrier gate), so `req advance --to done` / `req set --status done` **succeed** for stage-less `general` requirements; the single-source rule for non-`general` requirements is unchanged; done-gate rejections use dedicated copy.
-- **`cli/BUG-011`**: tier pruning left a stage **with no transition targets when sitting exactly on a pruned phase**. Pruning now **applies to incoming edges / targets only**, so pruned phases keep their outgoing edges; **entering** a pruned gate remains unreachable.
-- **`templates/BUG-007`**: the en archiver pointer dangled → switched to the Chinese section name, plus a "named § pointer literal hit" assertion to prevent recurrence.
-
-## What's New in v1.2.0
-
-- **flow.json version-shard archiving (`flow archive`)**: three entry points — `openfeel flow archive <version>` (perform archiving; gate = all stages of that version are done and no blocking open REV; **no `--force`**), `openfeel flow archive list`, `openfeel flow archive show <version> [--json]`; archives land at `.openfeel/flow-archive/{version}.json`. **Distinct from the top-level `openfeel archive <stage>` (stage-summary archiving)**; regular commands do not read archives.
-- **Requirement flow (`openfeel req`)**: 10 subcommands (11 since v1.2.1, +`split`) (add / list / show / claim / release / set / link / advance / board / next) + 7 statuses (`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`); requirement progress is aggregated from linked stage phases (**auto-closes once all linked stages are done**); claim protocol = `owner` + `claimed_at` (no TTL). Authoritative usage source: the `openfeel-req` skill.
-- **Compatibility**: legacy flow.json (without `requirements` / `archived_versions`) raises no errors; upgrading **requires no migration**.
-
-## What's New in v1.1.2
-
-- **Self-description**: `flow phases [--json]` lists all valid phases and the transition table (6 top-level JSON keys: `schemaVersion` / `phases` / `transitions` / `advanceAccepted` / `transitionsDiff` / `workflowMode` (added in v1.1.7; existing five keys unchanged verbatim); **7 keys since v1.2.1**, appending `reviewTier` last).
-- **Stage governance**: `flow stage remove` / `plan stage add --deps` / `stageId` validation and directory-conflict detection.
-- **Effective config**: `config effective` prints the resolved value plus its source (`status.md > config.yaml > profile.yaml > builtin`).
-- **Structured output**: `flow status/current/health/metrics/overview --json` (pure JSON + `schemaVersion`).
-- **Correction/cleanup CLI surface**: `plan scheme remove/rename/publish`, `flow ops list`, `flow health --fix`, `knowledge dedup`, `lint` non-zero exit on findings.
-- **Deployment & backup**: automatic backup before overwrite at `~/.openfeel/backup/{ts}/`; new skill `openfeel-cli-usage` (skills 16 → 17).
-- **Output encoding adaptation (stage-58 / stage-61 fix)**: `auto` passes through **UTF-8** on Windows non-TTY (pipe-friendly); TTY / POSIX pass through UTF-8; **GBK requires explicit** `--encoding gbk` / `OPENFEEL_ENCODING`; `--json` is **always UTF-8**; unencodable chars degrade to `?` without warning.
-- **Runtime log (stage-58)**: written by default to `~/.openfeel/cli/logs/openfeel-YYYY-MM-DD.log` (UTF-8, one file per day); `--log-file <path>` changes the path, `--no-log` / `OPENFEEL_LOG=0` disables it, `--debug` enables debug-level entries.
-
 ## Command Reference
 
 | Command | Purpose |
 |---------|---------|
 | `openfeel init [path]` | Initialize new project with `.openfeel/` workspace and platform adapter (current: opencode) |
-| `openfeel update` | Incrementally deploy platform adapter to existing projects; `--tools <list>` explicitly enables the Claude Code adapter |
+| `openfeel update` | Incrementally deploy platform adapter to existing projects; `--tools <list>` explicitly enables the Claude Code adapter; **`--tools dsh` is not supported** (use `setup`) |
 | `openfeel flow` | Pipeline state management (status / phases / overview / current / advance / attempt / ops list / health [--fix] / checkpoint / migrate; status·current·health·metrics·overview support --json) |
 | `openfeel roadmap` | Version roadmap management (create / show) |
 | `openfeel plan` | Stage and scheme management (stage add/list [--deps/--tasks], scheme create [--draft] / publish / rename / remove / list) |
@@ -164,7 +130,7 @@ Upgrade/migration notes: see [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)
 | `openfeel archive <stage>` | Stage archiving with knowledge extraction (**stage-summary archiving** — distinct from `flow archive` version-shard archiving) |
 | `openfeel flow archive` | flow.json version-shard archiving (`<version>` / `list` / `show`; distinct from `openfeel archive` stage-summary archiving) |
 | `openfeel req` | Requirement flow (add / list / show / claim / release / set / link / advance / board / next) |
-| `openfeel setup` | Global-only deployment (global AGENTS.md + agents + skills + adapter config); no project `.openfeel/`; `--tools <list>` explicitly enables the Claude Code adapter |
+| `openfeel setup` | Global-only deployment (global AGENTS.md + agents + skills + adapter config); no project `.openfeel/`; `--tools <list>` explicitly enables the Claude Code adapter; **`--tools dsh`** deploys into DSH profiles (`--dsh-profile <name>` to narrow) |
 | `openfeel migrate` | Migrate legacy-layout projects (detect / backup / rollback) |
 | `openfeel model` | Three-tier agent model config (set / get / list, `--scope`) |
 | `openfeel stage` | Work stage status (status / set / task / create [deprecated]) |
@@ -260,7 +226,7 @@ Core Layer
 ```bash
 npm install        # Install dependencies
 npm run build      # Compile TypeScript
-npm test           # Run tests (1894 cases / 74 test files; Linux CI skips 1 Windows-only case)
+npm test           # Run tests (77 files / 1978 cases; Linux CI skips 1 Windows-only case)
 ```
 
 ## Acknowledgments

package/README.md

@@ -2,13 +2,15 @@
 
 [English](README.en.md) | [更新日志](CHANGELOG.md) | [npm](https://www.npmjs.com/package/openfeel) | [入门指南](docs/GETTING_STARTED.md)
 
-> ⚡ **当前适配 harness**：**opencode（默认）** ｜ **Claude Code**（`--tools claude`，v1.1.6 起） ｜ **默认模型**：DeepSeek V4（主力推理）+ GLM-5.3-flash（交叉审查）+ DeepSeek-flash（多模态视觉）
+> 📚 版本能力概览：[docs/VERSIONS.md](docs/VERSIONS.md) ｜ 逐版本明细：[CHANGELOG.md](CHANGELOG.md)
+
+> ⚡ **当前适配 harness**：**opencode（默认）** ｜ **Claude Code**（`--tools claude`，v1.1.6 起） ｜ **DSH**（`--tools dsh`，v1.3.0 起） ｜ **默认模型**：DeepSeek V4（主力推理）+ GLM-5.3-flash（交叉审查）+ DeepSeek-flash（多模态视觉）
 
 > ⚠️ 下文示例命令 `openfeel <cmd>` 为**安装后的一般使用者用法**；若在**本仓库源码**中开发/执行，请改用 `node bin/openfeel.js <cmd>`（全局 `openfeel` 可能滞后于本仓——未随本仓库源码同步更新）。
 
 OpenFeel 是一个 TypeScript CLI 工具，为 AI Agent 开发提供端到端的流程治理。核心理念：**「提示词瘦身，流程入工具」** —— Agent 不靠读长文本理解流程，而是通过 `flow.json` 获取当前状态和下一步指令。
 
-> 📦 **最新版本 v1.2.4**（DSH ACTION-GUIDE A1~A5 收口 · 补丁） — `archive <stage>` 覆盖保护（`ARCHIVE_EXISTS` + `--force` + 零写盘）+ 7 个新增 `--json` 命令面（`plan stage list` / `model list|get` / `flow retry` / `lint i18n|kb` / `roadmap show`）+ `config get --all`。**40 个成功出口 / 41 个注册选项**；退出码 0/1/2/3 语义不变。
+> 📦 **最新版本 v1.3.0**（DSH 适配器单包分发 + README 重构） — `openfeel` 包内置 `dsh/`；`openfeel setup --tools dsh` 一键部署到 DSH profile；修复适配器 6 处位置参数空值问题；版本能力概览见 [docs/VERSIONS.md](docs/VERSIONS.md)。
 
 > 📌 本项目基于 [AI_Prompt](https://github.com/Liuary/AI_Prompt) 开发，参考了 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 等工具的设计思路。
 
@@ -30,6 +32,23 @@ npm install -g openfeel@latest # 更新到最新版本
 
 > 💡 `init` 用于新项目首次部署，`update` 为已有项目增量更新（适用于 `init` 之后再引入 OpenFeel 的项目）。存量旧布局项目（opencode 适配器：项目内 `.opencode/agents|skills|instructions`）用 `openfeel migrate` 迁移到全局部署。框架资产（agents/skills/AGENTS.md）经 `openfeel setup` 全局部署，项目内不再生成 `.opencode/agents|skills`。
 
+## 推荐用法：需求驱动 + 快速迭代（fast）
+
+> 日常开发默认推荐 **fast**：计划审查 + 代码审查各单轮，跳过方案/测试相位；大改动或架构变更再用 **full**。
+
+```bash
+openfeel req add "接入 DSH 适配器" --workflow-mode fast          # 1. 发布需求
+openfeel req claim REQ-NNN                                       # 2. 认领
+openfeel plan stage add vX.Y.Z-stage-NN --workflow-mode fast     # 3. 建 fast 阶段
+openfeel req link --stage vX.Y.Z-stage-NN --requirement REQ-NNN  # 4. 关联
+openfeel flow next                                               # 5. 按调度迭代
+```
+
+- **fast（默认推荐）**：日常迭代；保留计划审查与代码审查，跳过 scheme/test；
+- **full**：大改动 / 架构变更，完整六关；
+- **general**：无流水线的零散任务，仅需求级合法；
+- 需求关联阶段后，全部关联阶段 done 时自动收口需求。
+
 ## Claude Code 适配器（v1.1.6 起）
 
 > 与 opencode 适配器**并存**，**默认不启用**（须显式 `--tools claude`）。
@@ -39,71 +58,29 @@ npm install -g openfeel@latest # 更新到最新版本
 - **升级**：`npm i -g openfeel@latest` → `openfeel setup --tools claude`；**首次创建 `~/.claude/{agents,skills}` 后须重启会话或 `/reload-skills`** 使新 skill/agent 生效；`CLAUDE.md` 于**下次会话**生效。仅 `npm i -g` 不刷新全局资产。
 - **默认零触**：不带 `--tools` 时 `~/.claude/` **零变化**。
 
+## DSH 适配器（v1.3.0 起）
+
+> 与 opencode / Claude Code 适配器**并存**，默认不部署；适配器随 `openfeel` 单包分发。
+
+```bash
+npm i -g openfeel@latest      # 1. 安装/升级（单包，已含 dsh/）
+openfeel setup --tools dsh    # 2. 部署到 DSH profile（默认全部；可 --dsh-profile web）
+# 3. 重启 DSH 宿主
+```
+
+- 写入 `<DSH_HOME>/profiles/<name>/package.json`：`dependencies["openfeel-dsh"] = "link:<openfeelRoot>/dsh"` + `dsh.profile.bundles += "openfeel-dsh"`，并在需要时执行 `pnpm install`（依赖未变化且链接有效时跳过）。
+- 前提：DSH `0.2.0-rc.2`、Node ≥ 20.17、存在 DSH profile、全局 `openfeel` 可用。
+- 升级：`npm i -g openfeel@latest` → 重启 DSH；`link:` 指向同一路径，随包更新。
+- 开发态可直接 `link:` 仓库 `dsh/`；详见 [dsh/README.md](dsh/README.md) 与 [dsh/ADAPTER.md](dsh/ADAPTER.md)。
+- `openfeel update --tools dsh` 不适用（DSH 是全局部署）。
+
 ## 快速迭代模式（v1.1.7 起）
 
 > 与完整流水线（full）**并存**；新部署默认 **fast**（`config.yaml defaults.workflow_mode`），可逐阶段覆盖与切回。
 
 - **快线链**：`plan_pending → plan_review → plan_passed → exec_running → review_pending → review_passed → archiving → done`（跳过 6 项 `scheme_*` / `test_*`；**计划审查与代码审查保留单轮**，`review_failed` 可回环重试）。
-- **选择与切换**：`openfeel plan stage add <name> --workflow-mode full|fast|general`（新建阶段）；`openfeel stage set <stage> --workflow-mode full|fast|general`（单阶段切回）；`openfeel config set defaults.workflow_mode full|fast|general`（项目默认记忆）。**`general` 仅需求级合法**（v1.2.1 起，见下「v1.2.1 新增能力」）。
+- **选择与切换**：`openfeel plan stage add <name> --workflow-mode full|fast|general`（新建阶段）；`openfeel stage set <stage> --workflow-mode full|fast|general`（单阶段切回）；`openfeel config set defaults.workflow_mode full|fast|general`（项目默认记忆）。**`general` 仅需求级合法**（v1.2.1 起，见 [docs/VERSIONS.md](docs/VERSIONS.md)）。
 - **查看（只读）**：`openfeel flow mode [--stage <id>] [--json]`（当前模式 + 来源）；`openfeel flow phases [--mode full|fast|general] [--stage <id>]`（按模式查看转移表）。
 - **默认自动推进开启**：新部署默认 `auto_advance: enabled`（v1.1.7 起）；如需关闭：`openfeel config set auto_advance disabled`。
 
-## v1.2.4 新增能力（补丁）
-
-> 对应阶段：**stage-100**。本版收口 `dsh/ACTION-GUIDE.md` A1~A5；JSON 契约口径升级为 **40 成功出口 / 41 注册选项**，退出码 0/1/2/3 语义不变。本仓收口基线：**75 文件 / 1941 用例 / 21 阶段**。
-
-- **A1 归档覆盖保护（数据安全）**：`openfeel archive <stage>` 目标归档文件已存在时拒绝覆盖（`ARCHIVE_EXISTS` / `refusal` / exit 1，**零写盘**：归档内容哈希、`flow.json` revision、`log[]` 长度、KB 条目数均不变）；显式 `--force` 才覆盖。保护为**归档文件级**（短名/全名别名派生不同文件、互不触发）。
-- **A2 `plan stage list --json`（#34）**：`{schemaVersion,stages,count}`；`stages[]` 七键 `id,phase,status,deps,workflowMode,opsTotal,opsDone`（flow.json 注册阶段调度视图；人类输出保持计划目录清单）。
-- **A3 `model list|get --json`（#35/#36）**：list `{schemaVersion,scope,agents:[{agent,provider,model,source}]}`；get 六键；`provider`/`model` 按首个 `/` 切分，`source` 取生效层（default > project > global）。
-- **A4 三命令面（#37~#40）**：`flow retry --op <id> --json`（六键）、`lint i18n|kb --json`（`{target,ok,issues:[{path,message}]}`，`ok:false` 仍为成功文档 + exit 1）、`roadmap show [version] --json`（`version` + 表头驱动的 `milestones[{title,theme,stage,deliverable}]`，兼容 3/4 列）。
-- **A5 `config get --all --json`**：项目模式一次取全量 `{scope:"project",defaults:{execution_mode,auto_advance,merge_mode,workflow_mode}}`，不再报 `key-required`；与 `--global` 或位置 key 组合 → `INVALID_ARGUMENT`。
-- **契约**：错误码表 **13 行**（新增 `ARCHIVE_EXISTS`）；既有 33 个成功出口字段零破坏、人类输出逐字不变；`dsh/` 零改动。
-
-## v1.2.3 修复（补丁）
-
-> 对应阶段：**stage-99**。本版为 v1.2.2 转出项收口，不新增功能；JSON 契约 33 成功出口 / 34 注册选项与退出码语义不变。本仓收口基线：**75 文件 / 1911 用例 / 21 阶段**。
-
-- **并发 JSON 退出机制统一（REV-95-009）**：`handleConcurrentConflict` JSON 分支改为「输出 `FLOW_CONCURRENT_CONFLICT` envelope → 置 `process.exitCode=2` → return」（与 `failCli` 同机制，规避 Windows 管道 stdout 截断）；非 JSON 分支 `console.error + process.exit(2)` 逐字不变；10 个调用点无 fallthrough。
-- **`--review-tier` help 文案订正（REV-98-003 第 6 项）**：`flow advance --help` 与 i18n zh/en 由「缺省=按模式派生」改为「缺省=full（零裁剪）」；按模式派生的是 `flow phases --json.reviewTier` 展示值；缺省推进行为不变。
-- **`req` 过滤单点化（REV-97-006）**：`req show` / `req set --workflow-mode` 复用 `listLinkedStages`；`req split` 与 core 引擎层 done 判定原语保留；行为零变化。
-- **锁等待超时 E2E 测试钩子（REV-98-006①，test-only）**：仅 `OPENFEEL_TEST_MODE=1` 生效的 env seam 使超时路径可稳定断言 `INTERNAL_ERROR/internal/3`；生产默认 5000/3000ms 不变。
-
-## v1.2.2 新增能力
-
-> 对应阶段：**stage-95 ~ 98**。以下能力**v1.2.2 起提供**；JSON 契约单一权威见 docs/json-contract.md（33 个成功出口 / 34 个注册选项）。本仓收口基线：74 文件 / 1894 用例 / 21 阶段。
-
-- **`openfeel flow next [--json]`（决策权威，只读）**：12 键固定序（`schemaVersion,stage,phase,phaseLabel,responsibleAgent,workflowMode,reviewTier,effectiveReviewTier,legalNextPhases,suggestedCommand,guards,blockingReviews`）；`responsibleAgent` 与 `mapPhaseToAgent` 同源；`legalNextPhases` 每个元素均被 `flow advance` 接受；零写盘。
-- **全局 `--project <path>`**：任意命令前置/后置/`=` 形态；语义等效 cwd；语言按目标项目、`--log-file` 相对路径按原始 cwd；`knowledge dedup` 保留本地声明（语法兼容）。
-- **读命令 `--json` 全量补全**：13 个命令面（`stage status` / `flow recover` / `flow checkpoint list` / `flow log` / `project overview` / `knowledge search|list|index|dedup` / `config get|effective` / `view list` / `plan scheme list`）+ `archive <stage> --json`；累计 **33 个成功出口 / 34 个注册选项**。
-- **机器可读错误封装**：`{schemaVersion:1,error:{code,kind,message,detail}}`；退出码 **0 成功 / 1 预期拒绝 / 2 并发冲突 / 3 内部错误（新增）**；legacy `{error:'...'}` 保留 string 类型与键序、末尾追加 `errorKind`；12 行 `code→kind→exitCode` 映射表。
-- **`--version --json`**：`{schemaVersion:1,version,node}`（三键；单列，不计入 33 出口/34 选项）。
-- **`flow archive --dry-run --json` 判据明细 + `archive <stage> --json`**：`eligible` / `unfinishedStages` / `blockingReviews`；`archivePath` / 计数；`--dry-run` 零写盘。
-- **`reviewTier` 消歧**：`flow phases --json` / `flow status.stages[]` / `flow next` 同时给出展示值 `reviewTier`/`displayReviewTier` 与生效值 `effectiveReviewTier`（恒 `full`）。**订正**：`flow advance` 未显式传 `--review-tier` 时生效档位恒 **`full`**（不是按模式派生）；按模式派生的是 `flow phases --json.reviewTier` 展示值。源码 help 文案订正转 v1.2.3。
-- **兼容承诺**：既有 19 个成功出口字段零破坏（只增不改）；人类输出逐字不变；退出码 0/1/2 语义不变、3 仅新增；phase 枚举 15 项 / `advanceAccepted` / full-fast 行为不变；存量 `flow.json` 零迁移零注入；REQ-001 L80「2=内部错误或用法错误」登记为需求文本勘误（权威口径见契约 §2/§10）。
-
-## v1.2.1 新增能力
-
-> 对应阶段：**stage-86 ~ 93 + 94**（94 = 表外补阶段：模型默认值与部署非破坏性）。以下能力**v1.2.1 起提供**。
-
-- **三模式架构（`full` / `fast` / `general`）**：`workflow_mode` 值域由 2 值扩为 3 值（默认仍 `fast`）。`general`（无流水线）**仅需求级合法**——阶段级 / 部署级写入面拒绝（`plan stage add` / `stage set` / `config set` 命令层显式门 + wizard 不提供选项）；模式解析链增「需求级」一层（`status.md > 需求级 > config.yaml > builtin`）；**升级不降级**（可 `general` → `fast` / `full`，反向无隐式动作）。
-- **需求接取与拆分（`openfeel req split`）**：**拆分即发布**——子需求一次入 `scheduled`；`parent_id` 仅溯源（**不入聚合 / 不入 done 门 / 不参与 `PATCH_WHITELIST`**）；并行接取（`claim` 互不阻塞）；**需求与版本解绑**（`target_version` 为纯展示 / 过滤 / 排序维度，非门）。`req` 命令组 **10 → 11 子命令**（`split` = 首个 repeatable option、首个带 `--json` 的写命令）；`req advance --to done` 语义见下「缺陷修复」。
-- **通用工作者直接调度（双口径）**：opencode 侧 = 嵌套 `task` 工具；Claude Code 侧 = Handoff 直发。通用模式下可承接任意 Agent **直接调度**的执行任务（不限于流水线 op）。
-- **新 agent `openfeel-explorer`（只读）**：专职「调研 / 探索」路由——只读 4 工具（Read / Glob / Grep / Bash），不产出源码变更；agent 数 **9 → 10**。
-- **可观测性**：`metrics.json` 经 `recordRun` 接线；CLI 日志含 `duration_ms` / `project` / `session_id` 三字段；op 级时间戳；跨会话恢复标注（`resumed`）。
-- **审查档位（`--review-tier <full|lean|skip>`）**：与工作流模式**分属两轴**——模式定基表，档位裁审查关（`full` = 零裁剪 / `lean` 裁 `scheme_review` / `skip` 裁 `plan_review + scheme_review`；恒保留代码审查关 / 测试关 / 归档关）。缺省按模式派生（`full`→`full` / `fast`→`lean` / `general`→`full`）；显式 `lean` / `skip` 打印一行非阻断警告。`flow phases --json` 末位追加 `reviewTier`（既有 6 键逐字保留，**共 7 键**）。
-- **并行编排契约 + 归档轻量化**：阶段并行互不阻塞；归档段与轻量化步骤分离。
-- **模型默认值统一 + 部署非破坏性（用户主权键 `model`）**：opencode 侧显式默认收敛为 `deepseek/deepseek-flash`；部署（`setup` / `update`）对用户既有 `model` 键**无则创建、有则不覆盖**——不与用户既有值双写漂移。
-
-### 缺陷修复（v1.2.1）
-
-- **`req/BUG-002`**：`general` 需求**完成路径**——`general` 恒零关联阶段（载体制双向门）而 done 门要求全部关联阶段 done，两者交叉曾致 `general` 需求**永远无法 `done`**（死锁）。现开辟**载体制对偶完成路径**（判据 = 需求自身 `workflow_mode` 字段直判，与载体制门同源），`openfeel req advance --to done` / `req set --status done` 对零关联 `general` 需求**放行**；非 `general` 需求判定单源不变；done 门拒绝改用专用文案。
-- **`cli/BUG-011`**：审查档位裁剪致**当前相位无跳转目标**——阶段恰停于被裁剪相位时该档位无可达目标。现**裁剪只作用于入边 / 目标侧**，被裁剪相位保留出边（可正常向该档位下游推进）；「进入被裁剪关」仍不可达。
-- **`templates/BUG-007`**：en 归档官指针悬空（`§Archive Mechanical Checklist` → 目标节仅中文）→ 改中文节名，并补「具名 § 指针字面命中」断言防再犯。
-
-## v1.2.0 新增能力
-
-- **flow.json 版本分片归档（`flow archive`）**：三个入口——`openfeel flow archive <version>`（执行归档；判据门 = 该版本全部阶段 done 且无 blocking open REV，**不设 `--force`**）、`openfeel flow archive list`、`openfeel flow archive show <version> [--json]`；归档落点 `.openfeel/flow-archive/{version}.json`。**与顶层 `openfeel archive <stage>`（阶段摘要归档）区分**；常规命令不读归档。
-- **需求流转（`openfeel req`）**：10 子命令（v1.2.1 起 11，+`split`）（`add` / `list` / `show` / `claim` / `release` / `set` / `link` / `advance` / `board` / `next`）+ 7 状态（`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`）；需求进度由关联阶段 phase 聚合（**全部关联阶段 done 时自动收口**）；认领协议 = `owner` + `claimed_at`（无 TTL）。用法权威源见 `openfeel-req` skill。
-- **兼容**：旧 flow.json（无 `requirements` / `archived_versions`）零报错，升级**无需迁移**。
-
-完整中文文档：[README.zh-CN.md](README.zh-CN.md)（详见其中的「Claude Code 适配器」小节）
+完整中文文档：[README.zh-CN.md](README.zh-CN.md)（含 Claude Code / DSH 适配器、命令参考与核心概念）

package/README.zh-CN.md

@@ -2,11 +2,13 @@
 
 [English](README.en.md) | [更新日志](CHANGELOG.md) | [npm](https://www.npmjs.com/package/openfeel) | [入门指南](docs/GETTING_STARTED.md)
 
+> 📚 版本能力概览：[docs/VERSIONS.md](docs/VERSIONS.md) ｜ 逐版本明细：[CHANGELOG.md](CHANGELOG.md)
+
 > ⚠️ 下文示例命令 `openfeel <cmd>` 为**安装后的一般使用者用法**；若在**本仓库源码**中开发/执行，请改用 `node bin/openfeel.js <cmd>`（全局 `openfeel` 可能滞后于本仓——未随本仓库源码同步更新）。
 
 OpenFeel 是一个 TypeScript CLI 工具，为 AI Agent 开发提供端到端的流程治理。
 
-> **当前适配 harness**：**opencode（默认）** ｜ **Claude Code**（`--tools claude`，v1.1.6 起）；框架面向多 harness 适配（其余适配器预留）。  
+> **当前适配 harness**：**opencode（默认）** ｜ **Claude Code**（`--tools claude`，v1.1.6 起） ｜ **DSH**（`--tools dsh`，v1.3.0 起）；框架面向多 harness 适配（其余适配器预留）。  
 > **默认模型配置**：DeepSeek V4（主力推理） + GLM-5.3-flash（交叉审查） + DeepSeek-flash（多模态视觉）。  
 > 首次 `openfeel init` 时会自动检测用户已注册的模型并引导配置。
 
@@ -60,6 +62,23 @@ openfeel plan scheme create stage-01 "实现核心功能"
 openfeel flow status
 ```
 
+## 推荐用法：需求驱动 + 快速迭代（fast）
+
+> 日常开发默认推荐 **fast**：计划审查 + 代码审查各单轮，跳过方案/测试相位；大改动或架构变更再用 **full**。
+
+```bash
+openfeel req add "接入 DSH 适配器" --workflow-mode fast          # 1. 发布需求
+openfeel req claim REQ-NNN                                       # 2. 认领
+openfeel plan stage add vX.Y.Z-stage-NN --workflow-mode fast     # 3. 建 fast 阶段
+openfeel req link --stage vX.Y.Z-stage-NN --requirement REQ-NNN  # 4. 关联
+openfeel flow next                                               # 5. 按调度迭代
+```
+
+- **fast（默认推荐）**：日常迭代；保留计划审查与代码审查，跳过 scheme/test；
+- **full**：大改动 / 架构变更，完整六关；
+- **general**：无流水线的零散任务，仅需求级合法；
+- 需求关联阶段后，全部关联阶段 done 时自动收口需求。
+
 ## Claude Code 适配器（v1.1.6 起）
 
 > 与 opencode 适配器**并存**，**默认不启用**（须显式 `--tools claude`）。
@@ -69,92 +88,39 @@ openfeel flow status
 - **升级**：`npm i -g openfeel@latest` → `openfeel setup --tools claude`；**首次创建 `~/.claude/{agents,skills}` 后须重启会话或 `/reload-skills`** 使新 skill/agent 生效；`CLAUDE.md` 于**下次会话**生效。仅 `npm i -g` 不刷新全局资产。
 - **默认零触**：不带 `--tools` 时 `~/.claude/` **零变化**。
 
+## DSH 适配器（v1.3.0 起）
+
+> 与 opencode / Claude Code 适配器**并存**，默认不部署；适配器随 `openfeel` 单包分发。
+
+```bash
+npm i -g openfeel@latest      # 1. 安装/升级（单包，已含 dsh/）
+openfeel setup --tools dsh    # 2. 部署到 DSH profile（默认全部；可 --dsh-profile web）
+# 3. 重启 DSH 宿主
+```
+
+- 写入 `<DSH_HOME>/profiles/<name>/package.json`：`dependencies["openfeel-dsh"] = "link:<openfeelRoot>/dsh"` + `dsh.profile.bundles += "openfeel-dsh"`，并在需要时执行 `pnpm install`（依赖未变化且链接有效时跳过）。
+- 前提：DSH `0.2.0-rc.2`、Node ≥ 20.17、存在 DSH profile、全局 `openfeel` 可用。
+- 升级：`npm i -g openfeel@latest` → 重启 DSH；`link:` 指向同一路径，随包更新。
+- 开发态可直接 `link:` 仓库 `dsh/`；详见 [dsh/README.md](dsh/README.md) 与 [dsh/ADAPTER.md](dsh/ADAPTER.md)。
+- `openfeel update --tools dsh` 不适用（DSH 是全局部署）。
+
 ## 快速迭代模式（v1.1.7 起）
 
 > 与完整流水线（full）**并存**；新部署默认 **fast**（`config.yaml defaults.workflow_mode`），可逐阶段覆盖与切回。
 
 - **快线链**：`plan_pending → plan_review → plan_passed → exec_running → review_pending → review_passed → archiving → done`（跳过 6 项 `scheme_*` / `test_*`；**计划审查与代码审查保留单轮**，`review_failed` 可回环重试）。
-- **选择与切换**：`openfeel plan stage add <name> --workflow-mode full|fast|general`（新建阶段）；`openfeel stage set <stage> --workflow-mode full|fast|general`（单阶段切回）；`openfeel config set defaults.workflow_mode full|fast|general`（项目默认记忆）。**`general` 仅需求级合法**（v1.2.1 起，见下「v1.2.1 新增能力」）。
+- **选择与切换**：`openfeel plan stage add <name> --workflow-mode full|fast|general`（新建阶段）；`openfeel stage set <stage> --workflow-mode full|fast|general`（单阶段切回）；`openfeel config set defaults.workflow_mode full|fast|general`（项目默认记忆）。**`general` 仅需求级合法**（v1.2.1 起，见 [docs/VERSIONS.md](docs/VERSIONS.md)）。
 - **查看（只读）**：`openfeel flow mode [--stage <id>] [--json]`（当前模式 + 来源）；`openfeel flow phases [--mode full|fast|general] [--stage <id>]`（按模式查看转移表）。
 - **默认自动推进开启**：新部署默认 `auto_advance: enabled`（v1.1.7 起）；如需关闭：`openfeel config set auto_advance disabled`。
 
 升级迁移提示见 [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)「工作流模式（full / fast）与自动推进」小节与 [CHANGELOG.md](CHANGELOG.md) `[1.1.7]`。
 
-## v1.2.4 新增能力（补丁）
-
-> 对应阶段：**stage-100**。本版收口 `dsh/ACTION-GUIDE.md` A1~A5；JSON 契约口径升级为 **40 成功出口 / 41 注册选项**，退出码 0/1/2/3 语义不变。本仓收口基线：**75 文件 / 1941 用例 / 21 阶段**。
-
-- **A1 归档覆盖保护（数据安全）**：`openfeel archive <stage>` 目标归档文件已存在时拒绝覆盖（`ARCHIVE_EXISTS` / `refusal` / exit 1，**零写盘**：归档内容哈希、`flow.json` revision、`log[]` 长度、KB 条目数均不变）；显式 `--force` 才覆盖。保护为**归档文件级**（短名/全名别名派生不同文件、互不触发）。
-- **A2 `plan stage list --json`（#34）**：`{schemaVersion,stages,count}`；`stages[]` 七键 `id,phase,status,deps,workflowMode,opsTotal,opsDone`。
-- **A3 `model list|get --json`（#35/#36）**：list `{schemaVersion,scope,agents:[{agent,provider,model,source}]}`；get 六键；按首个 `/` 切分 provider/model，`source` 取生效层（default > project > global）。
-- **A4 三命令面（#37~#40）**：`flow retry --op <id> --json`、`lint i18n|kb --json`（`ok:false` 仍为成功文档 + exit 1）、`roadmap show [version] --json`（表头驱动里程碑，兼容 3/4 列）。
-- **A5 `config get --all --json`**：项目模式一次取全量 `defaults` 四键，不再报 `key-required`；冲突组合 → `INVALID_ARGUMENT`。
-- **契约**：错误码表 **13 行**（新增 `ARCHIVE_EXISTS`）；既有出口字段零破坏、人类输出逐字不变；`dsh/` 零改动。
-
-## v1.2.3 修复（补丁）
-
-> 对应阶段：**stage-99**。本版为 v1.2.2 转出项收口，不新增功能；JSON 契约 33 成功出口 / 34 注册选项与退出码语义不变。本仓收口基线：**75 文件 / 1911 用例 / 21 阶段**。
-
-- **并发 JSON 退出机制统一（REV-95-009）**：`handleConcurrentConflict` JSON 分支改为「输出 envelope → 置 `process.exitCode=2` → return」；非 JSON 分支逐字不变；10 个调用点无 fallthrough。
-- **`--review-tier` help 文案订正（REV-98-003 第 6 项）**：源码 help 与 i18n zh/en 改为「缺省=full（零裁剪）」；缺省推进行为不变。
-- **`req` 过滤单点化（REV-97-006）**：`req show` / `req set --workflow-mode` 复用 `listLinkedStages`；`req split` 与 core 引擎层 done 判定原语保留。
-- **锁等待超时 E2E 测试钩子（REV-98-006①，test-only）**：仅 `OPENFEEL_TEST_MODE=1` 生效；生产默认 5000/3000ms 不变；E2E 断言 `INTERNAL_ERROR/internal/3`。
-
-## v1.2.2 新增能力
-
-> 对应阶段：**stage-95 ~ 98**。以下能力**v1.2.2 起提供**；JSON 契约单一权威见 docs/json-contract.md（33 个成功出口 / 34 个注册选项）。本仓收口基线：74 文件 / 1894 用例 / 21 阶段。
-
-- **`openfeel flow next [--json]`（决策权威，只读）**：12 键固定序（`schemaVersion,stage,phase,phaseLabel,responsibleAgent,workflowMode,reviewTier,effectiveReviewTier,legalNextPhases,suggestedCommand,guards,blockingReviews`）；`responsibleAgent` 与 `mapPhaseToAgent` 同源；`legalNextPhases` 每个元素均被 `flow advance` 接受；零写盘。
-- **全局 `--project <path>`**：任意命令前置/后置/`=` 形态；语义等效 cwd；语言按目标项目、`--log-file` 相对路径按原始 cwd；`knowledge dedup` 保留本地声明（语法兼容）。
-- **读命令 `--json` 全量补全**：13 个命令面（`stage status` / `flow recover` / `flow checkpoint list` / `flow log` / `project overview` / `knowledge search|list|index|dedup` / `config get|effective` / `view list` / `plan scheme list`）+ `archive <stage> --json`；累计 **33 个成功出口 / 34 个注册选项**。
-- **机器可读错误封装**：`{schemaVersion:1,error:{code,kind,message,detail}}`；退出码 **0 成功 / 1 预期拒绝 / 2 并发冲突 / 3 内部错误（新增）**；legacy `{error:'...'}` 保留 string 类型与键序、末尾追加 `errorKind`；12 行 `code→kind→exitCode` 映射表。
-- **`--version --json`**：`{schemaVersion:1,version,node}`（三键；单列，不计入 33 出口/34 选项）。
-- **`flow archive --dry-run --json` 判据明细 + `archive <stage> --json`**：`eligible` / `unfinishedStages` / `blockingReviews`；`archivePath` / 计数；`--dry-run` 零写盘。
-- **`reviewTier` 消歧**：`flow phases --json` / `flow status.stages[]` / `flow next` 同时给出展示值 `reviewTier`/`displayReviewTier` 与生效值 `effectiveReviewTier`（恒 `full`）。**订正**：`flow advance` 未显式传 `--review-tier` 时生效档位恒 **`full`**（不是按模式派生）；按模式派生的是 `flow phases --json.reviewTier` 展示值。源码 help 文案订正转 v1.2.3。
-- **兼容承诺**：既有 19 个成功出口字段零破坏（只增不改）；人类输出逐字不变；退出码 0/1/2 语义不变、3 仅新增；phase 枚举 15 项 / `advanceAccepted` / full-fast 行为不变；存量 `flow.json` 零迁移零注入；REQ-001 L80「2=内部错误或用法错误」登记为需求文本勘误（权威口径见契约 §2/§10）。
-
-## v1.2.1 新增能力
-
-> 对应阶段：**stage-86 ~ 93 + 94**（94 = 表外补阶段：模型默认值与部署非破坏性）。以下能力**v1.2.1 起提供**。
-
-- **三模式架构（`full` / `fast` / `general`）**：`workflow_mode` 值域由 2 值扩为 3 值（默认仍 `fast`）。`general`（无流水线）**仅需求级合法**——阶段级 / 部署级写入面拒绝（`plan stage add` / `stage set` / `config set` 命令层显式门 + wizard 不提供选项）；模式解析链增「需求级」一层（`status.md > 需求级 > config.yaml > builtin`）；**升级不降级**。
-- **需求接取与拆分（`openfeel req split`）**：**拆分即发布**——子需求一次入 `scheduled`；`parent_id` 仅溯源（**不入聚合 / 不入 done 门 / 不参与 `PATCH_WHITELIST`**）；并行接取（`claim` 互不阻塞）；**需求与版本解绑**（`target_version` 为纯展示 / 过滤 / 排序维度，非门）。`req` 命令组 **10 → 11 子命令**。
-- **通用工作者直接调度（双口径）**：opencode 侧 = 嵌套 `task` 工具；Claude Code 侧 = Handoff 直发。通用模式下可承接任意 Agent **直接调度**的执行任务。
-- **新 agent `openfeel-explorer`（只读）**：专职「调研 / 探索」路由——只读 4 工具（Read / Glob / Grep / Bash）；agent 数 **9 → 10**。
-- **可观测性**：`metrics.json` 经 `recordRun` 接线；CLI 日志含 `duration_ms` / `project` / `session_id` 三字段；op 级时间戳；跨会话恢复标注（`resumed`）。
-- **审查档位（`--review-tier <full|lean|skip>`）**：与工作流模式**分属两轴**——模式定基表，档位裁审查关（`full` 零裁剪 / `lean` 裁 `scheme_review` / `skip` 裁 `plan_review + scheme_review`；恒保留代码审查关 / 测试关 / 归档关）。缺省按模式派生（`full`→`full` / `fast`→`lean` / `general`→`full`）。`flow phases --json` 末位追加 `reviewTier`（既有 6 键逐字保留，**共 7 键**）。
-- **并行编排契约 + 归档轻量化**。
-- **模型默认值统一 + 部署非破坏性（用户主权键 `model`）**：部署（`setup` / `update`）对用户既有 `model` 键**无则创建、有则不覆盖**。
-
-### 缺陷修复（v1.2.1）
-
-- **`req/BUG-002`**：`general` 需求**完成路径**——`general` 恒零关联阶段（载体制双向门）而 done 门要求全部关联阶段 done，两者交叉曾致 `general` 需求**永远无法 `done`**。现开辟**载体制对偶完成路径**（判据 = 需求自身 `workflow_mode` 字段直判，与载体制门同源），`req advance --to done` / `req set --status done` 对零关联 `general` 需求**放行**；非 `general` 判定单源不变；done 门拒绝改用专用文案。
-- **`cli/BUG-011`**：审查档位裁剪致**当前相位无跳转目标**。现**裁剪只作用于入边 / 目标侧**，被裁剪相位保留出边；「进入被裁剪关」仍不可达。
-- **`templates/BUG-007`**：en 归档官指针悬空 → 改中文节名 + 补「具名 § 指针字面命中」断言。
-
-## v1.2.0 新增能力
-
-- **flow.json 版本分片归档（`flow archive`）**：三个入口——`openfeel flow archive <version>`（执行归档；判据门 = 该版本全部阶段 done 且无 blocking open REV，**不设 `--force`**）、`openfeel flow archive list`、`openfeel flow archive show <version> [--json]`；归档落点 `.openfeel/flow-archive/{version}.json`。**与顶层 `openfeel archive <stage>`（阶段摘要归档）区分**；常规命令不读归档。
-- **需求流转（`openfeel req`）**：10 子命令（v1.2.1 起 11，+`split`）（`add` / `list` / `show` / `claim` / `release` / `set` / `link` / `advance` / `board` / `next`）+ 7 状态（`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`）；需求进度由关联阶段 phase 聚合（**全部关联阶段 done 时自动收口**）；认领协议 = `owner` + `claimed_at`（无 TTL）。用法权威源见 `openfeel-req` skill。
-- **兼容**：旧 flow.json（无 `requirements` / `archived_versions`）零报错，升级**无需迁移**。
-
-## v1.1.2 新增能力
-
-- **自描述**：`flow phases [--json]` 输出全部合法 phase 与转移表（JSON 顶层 6 键：`schemaVersion` / `phases` / `transitions` / `advanceAccepted` / `transitionsDiff` / `workflowMode`（v1.1.7 追加，既有五键语义逐字不变）；v1.2.1 起 7 键，末位追加 `reviewTier`）。
-- **阶段治理**：`flow stage remove` / `plan stage add --deps` / `stageId` 校验与目录冲突检测。
-- **配置有效值**：`config effective` 输出有效值 + 生效来源（`status.md > config.yaml > profile.yaml > builtin`）。
-- **结构化输出**：`flow status/current/health/metrics/overview --json`（纯 JSON + `schemaVersion`）。
-- **纠正/清理侧命令面**：`plan scheme remove/rename/publish`、`flow ops list`、`flow health --fix`、`knowledge dedup`、`lint` 发现问题非 0 退出。
-- **部署与备份**：部署覆盖前自动备份 `~/.openfeel/backup/{ts}/`；新增 skill `openfeel-cli-usage`（skill 16 → 17）。
-- **输出编码自适应（stage-58 / stage-61 修正）**：`auto` 在 Windows 非 TTY（管道/重定向）下**直通 UTF-8**（管道/CI 友好）；TTY / POSIX 直通 UTF-8；**GBK 需 `--encoding gbk` / `OPENFEEL_ENCODING` 显式**；`--json` **恒 UTF-8**；不可编码字符降 `?` 不告警。
-- **运行日志（stage-58）**：默认写入 `~/.openfeel/cli/logs/openfeel-YYYY-MM-DD.log`（UTF-8，按日一文件）；`--log-file <path>` 改路径，`--no-log` / `OPENFEEL_LOG=0` 关闭，`--debug` 记录 debug 级。
-
 ## 命令参考
 
 | 命令 | 用途 |
 |------|------|
 | `openfeel init [path]` | 初始化新项目，创建 `.openfeel/` 目录结构和平台适配器（当前：opencode） |
-| `openfeel update` | 为已有项目增量部署平台适配器（适用于 `init` 之后再引入 OpenFeel 的项目）；`--tools <list>` 显式启用 Claude Code 适配器 |
+| `openfeel update` | 为已有项目增量部署平台适配器（适用于 `init` 之后再引入 OpenFeel 的项目）；`--tools <list>` 显式启用 Claude Code 适配器；**`--tools dsh` 不适用**（请用 `setup`） |
 | `openfeel flow` | 流水线状态管理（status / phases / overview / current / advance / attempt / ops list / health [--fix] / checkpoint / migrate；status·current·health·metrics·overview 支持 --json） |
 | `openfeel roadmap` | 分期大纲管理（create / show） |
 | `openfeel plan` | 工作阶段与操作方案管理（stage add/list [--deps/--tasks]、scheme create [--draft] / publish / rename / remove / list） |
@@ -164,7 +130,7 @@ openfeel flow status
 | `openfeel archive <stage>` | 阶段归档，汇总产出、生成摘要、提取知识（**阶段摘要归档**——与 `flow archive` 版本分片归档区分） |
 | `openfeel flow archive` | flow.json 版本分片归档（`<version>` / `list` / `show`；与 `openfeel archive` 阶段摘要归档区分） |
 | `openfeel req` | 需求流转（add / list / show / claim / release / set / link / advance / board / next） |
-| `openfeel setup` | 纯全局部署（全局 AGENTS.md + agent + skill + 平台适配器配置），不建项目 `.openfeel/`；`--tools <list>` 显式启用 Claude Code 适配器 |
+| `openfeel setup` | 纯全局部署（全局 AGENTS.md + agent + skill + 平台适配器配置），不建项目 `.openfeel/`；`--tools <list>` 显式启用 Claude Code 适配器；**`--tools dsh`** 部署到 DSH profile（`--dsh-profile <name>` 窄化） |
 | `openfeel migrate` | 存量旧布局项目迁移（检测 / 备份 / 回滚） |
 | `openfeel model` | 三层级 agent 模型配置（set / get / list，`--scope`） |
 | `openfeel stage` | 阶段状态（status / set / task / create［已弃用］） |
@@ -260,7 +226,7 @@ Core 层
 ```bash
 npm install        # 安装依赖
 npm run build      # 编译 TypeScript
-npm test           # 运行测试（1894 用例 / 74 个测试文件；Linux CI 跳过 1 个 Windows 专属用例）
+npm test           # 运行测试（77 文件 / 1978 用例；Linux CI 跳过 1 个 Windows 专属用例）
 ```
 
 ## 致谢

package/dist/commands/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwE3D"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4CpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoH3D"}