@devflow-core/dsh-devflow 0.1.0 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@ npx @deepseek-ai/dsh plugin --profile web add @devflow-core/dsh-devflow
 
 重启后：
 
-1. 新建会话，预设选择器可选 **DevFlow 2.0 (Anchored)**（两阶段锚定 + Code Mode）。
+1. 新建会话，预设选择器可选 **DevFlow 2.0**（两阶段锚定 + Code Mode）。
 2. 会话内 `devflow-*` skills 出现在技能目录，按任务措辞自动触发。
 3. `~/.dsh/commands/` 出现 `devflow*.toml` 斜杠命令，`~/.dsh/scripts/` 出现
    `devflow-*.js` 验证脚本（`node scripts/devflow-plan.js <plan>` 等）。
@@ -73,10 +73,14 @@ devflow-2 预设的 `custom-bash.mjs` 需要 Git Bash 可解析：默认自动
 的 custom-bash 行显式配置 `bashPath` 指向本机 Git（参照
 `docs/dsh-plugins-guide.md` 7.1 节）。
 
-## 发布
+## 发布与更新
+
+完整维护者流程（前置条件、版本 bump、发布命令、错误对照表、git 备选）见
+[RELEASE.md](RELEASE.md)。简版：
 
 ```sh
 cd dsh/plugins/dsh-devflow
 node scripts/sync-assets.js   # 发布前必须重跑，保证资产与仓库根一致
-npm publish
+# bump package.json 版本号
+npm publish --access public --//registry.npmjs.org/:_authToken=<TOKEN>
 ```

package/RELEASE.md

@@ -0,0 +1,128 @@
+# @devflow-core/dsh-devflow — 发布与更新流程
+
+维护者指南：如何发布新版本、用户如何升级、常见错误与修复。用户安装/使用说明见
+[README.md](README.md)。
+
+## 前置条件
+
+| 项 | 要求 |
+|---|---|
+| npm 账号 | 拥有 `@devflow-core` 组织（org）的写权限（创建于 npmjs.com/org/create，免费 public 方案） |
+| npm token | Granular Access Token，**Read and write** + **勾选 "Bypass 2FA for publish"**（或 Automation token）。生成地址：https://www.npmjs.com/settings/<账号>/tokens |
+| Node / pnpm | Node ≥22；pnpm ≥10（发布由 npm CLI 完成，但 `dsh plugin` 安装链路依赖 pnpm） |
+| 仓库 | DevFlow-Core 仓库可写，`dsh/plugins/dsh-devflow/` 子包为发布源 |
+
+> token 不要写进仓库或 .npmrc。发布时用命令行参数临时注入（见下），用完即弃；
+> token 一旦在聊天/日志中暴露，发布后立即到 npm 设置页 revoke 并重新生成。
+
+## 一次完整发布（改代码 → 发布 → 用户升级）
+
+### 1. 修改源码或资产
+
+需要更新的内容都在仓库根：
+
+- 预设：`dsh/agent-presets/devflow-2/`（agent.cordis.yml / preset.yml / tool-bootstrap.mjs / custom-bash.mjs / NOTICE）
+- 技能：`skills/devflow-*/`（SKILL.md 与 references/）
+- 命令：`commands/devflow*.toml`
+- 验证脚本：`scripts/devflow-*.js`（spec/plan/review/debt/audit/doctor）
+- 插件代码：`dsh/plugins/dsh-devflow/lib/`（同步引擎 / 挂载 / announce）
+
+### 2. 根仓库验证不回归
+
+```sh
+npm run verify:all        # 必须全绿（exit 0）
+```
+
+### 3. 刷新子包资产（防漂移）
+
+子包 assets/ 是自包含副本，发布前必须从仓库根重新复制：
+
+```sh
+node dsh/plugins/dsh-devflow/scripts/sync-assets.js
+```
+
+预期输出四行 `synced N entries`；重复运行应幂等（第二次仍成功且无新文件）。
+
+### 4. 子包自测
+
+```sh
+node dsh/plugins/dsh-devflow/test/sync.test.js
+# 预期: DevFlow DSH plugin sync test passed（五场景: 创建/幂等/覆盖/隔离/prune）
+```
+
+### 5. 版本 bump
+
+```sh
+# 编辑 dsh/plugins/dsh-devflow/package.json 的 "version"
+# 语义: patch=缺陷修复, minor=资产/功能更新, major=不兼容变更
+```
+
+发布时使用 CLI 参数临时注入 token（不落盘）：
+
+```sh
+cd dsh/plugins/dsh-devflow
+node scripts/sync-assets.js   # 发布前再跑一次，保证资产最新
+npm publish --access public --//registry.npmjs.org/:_authToken=<TOKEN>
+```
+
+- `--access public` 必须显式给出：scoped 包默认按私有发布，会报 `E402 Payment Required`。
+- `--//registry.npmjs.org/:_authToken=` 是 npm 的 per-registry 参数注入，token 不写入 .npmrc。
+
+### 6. 发布后验证
+
+```sh
+npm view @devflow-core/dsh-devflow version dist-tags.latest
+# 预期输出: 0.1.x 与 latest: 0.1.x
+```
+
+> 新包首次发布后 registry 有约 5 分钟传播延迟，期间 `npm view` 可能 404 属正常；
+> 用 `--prefer-online` 绕过本地缓存。若发布命令报 "cannot publish over the
+> previously published versions"，说明该版本已存在，bump 版本号再发。
+
+### 7. 提交并推送仓库
+
+```sh
+git add -A
+git commit -m "chore(dsh-devflow): release v<新版本>"
+git push origin master
+```
+
+## 用户升级
+
+已安装用户升级到新版本：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web update @devflow-core/dsh-devflow
+# 或 remove + add 后重启
+```
+
+重启 web 后插件启动时自动把新资产同步到 `~/.dsh/`：
+
+- 字节相同的文件跳过（不覆盖用户 mtime）
+- 不同的文件覆盖（devflow-* 权威）
+- 源不再包含的 devflow-* 残留 prune
+- 非 devflow 资产（atlassian、rtk 等）永不触碰
+- `~/.dsh/.agent-presets/devflow-2/` 整目录归插件管理，目录内非包内文件会被清理
+
+## 常见错误对照表
+
+| 报错 | 原因 | 修复 |
+|---|---|---|
+| `E403 Two-factor authentication or granular access token with bypass 2fa` | token 未勾选 Bypass 2FA | 重新生成 token，勾选 "Bypass 2FA for publish" 或改用 Automation token |
+| `E402 Payment Required - You must sign up for private packages` | scoped 包按私有发布 | 加 `--access public` |
+| `E404 Scope not found` | `@devflow-core` 组织不存在或无权 | 先在 npmjs.com 创建 `devflow-core` org，或改用账号 scope |
+| `E403 You cannot publish over the previously published versions: x.y.z` | 该版本已发布 | bump 版本号再发 |
+| `npm view` 404 但 publish 成功 | registry 传播延迟 / 本地缓存 | 等 5 分钟；`npm view --prefer-online` |
+| `E404 Not found`（view 时） | 包不存在或 scope 无权 | 确认发布成功（`npm view --prefer-online`），或检查 org 归属 |
+
+## 备选：git 分发（不用 npm）
+
+仓库已推送到 GitHub 时，用户也可以不经 npm registry 直接安装：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add github:huangwen-changdu/DevFlow-Core#path:dsh/plugins/dsh-devflow
+```
+
+- `dsh plugin` 是 pnpm 转发器，git URL 直接透传；`#path:` 指定仓库内子目录。
+- 无需 npm token/org；更新 = 推送仓库后用户重装。
+- 与 npm 发布二选一即可；npm 发布提供版本化与 `dsh plugin update` 升级路径。

package/assets/commands/devflow-adversarial.toml

@@ -7,5 +7,6 @@ Identify the review target from the request and available task materials. Ask on
 This command is manual and independent: it does not require, read, modify, or hand off to devflow-prove, PUA, Build, Learn, or any completion state.
 Cover requirement coverage, reachability, boundaries and regressions, evidence strength, and user-visible outcome.
 Report only the skill's required findings, five-angle coverage, context limitations, and suggested manual next action.
+On DeepSeek Harness (DSH), dispatch a fresh subagent and run the review in bounded rounds, one round per review angle; the subagent returns each round's findings and the main agent aggregates them into the final report.
 Do not edit files, invoke another skill, create a task, or declare global task status.
 '''

package/assets/commands/devflow-find-fault.toml

@@ -7,5 +7,6 @@ This command is manual and independent: it does not require, read, modify, or ha
 Answer the biggest omission, unrecognized blind spot, and least certain point, plus every explicit user question.
 When reviewing implemented work, also run a post-implementation unease check: find business decisions encoded by the implementation but not explicitly confirmed, classify their risk, and state the confirmation needed.
 Separate facts, inference, and unknowns; give every answer confidence and a next step, then report finding levels, unease decisions, limitations, and suggested manual action.
+On DeepSeek Harness (DSH), dispatch a fresh subagent and run the review in bounded rounds, one round per question and one round for the post-implementation unease check; the subagent returns each round's findings and the main agent aggregates them into the final report.
 Do not edit files, invoke another skill, create a task, or declare global task status.
 '''

package/assets/presets/devflow-2/README.md

@@ -1,4 +1,4 @@
-# DevFlow 2.0 (Anchored) — DeepSeek Harness Agent Preset
+# DevFlow 2.0 — DeepSeek Harness Agent Preset
 
 A DSH agent preset that anchors the FIRST model request on the Minimal
 surface, then promotes into a full DevFlow session: Code Mode (PTC) on the
@@ -19,7 +19,7 @@ wire, the complete DevFlow persona, and the DevFlow lifecycle guaranteed.
   `xiaobright/dsh-anchored-standard`, MIT, extended by `dsh-liangshen`),
   with a `phase1Persona` swap so the DevFlow persona only appears after
   promotion.
-- `preset.yml` — picker metadata (name: DevFlow 2.0 (Anchored)).
+- `preset.yml` — picker metadata (name: DevFlow 2.0).
 
 Skills are NOT bundled: the preset's `skill-filesystem` row uses the default
 user root (`$DSH_HOME/skills`), which is exactly where `npm run install:user`
@@ -46,7 +46,7 @@ cp dsh/agent-presets/devflow-2/NOTICE                ~/.dsh/.agent-presets/devfl
 
 ## Use
 
-Start a new session in the web UI and pick **DevFlow 2.0 (Anchored)** in the
+Start a new session in the web UI and pick **DevFlow 2.0** in the
 preset picker. The roster may need a refresh or restart to show a newly added
 preset. Existing sessions keep their old phase; the two-phase behavior applies
 to new sessions.

package/assets/presets/devflow-2/preset.yml

@@ -1,3 +1,3 @@
-name: DevFlow 2.0 (Anchored)
+name: DevFlow 2.0
 description: DevFlow 开发工作流 + 梁神式两阶段锚定：首个请求只暴露一行 persona（You are a helpful software engineer assistant.）+ 最小工具对（持久 bash + str_replace_editor），无运行时上下文与任何注入；anchorGate 门控（首个 minimal-like 推理块或 4 步兜底）+ 1024 输出预算稳定锚定后，晋升为 Code Mode（单一 run_code），恢复完整 DevFlow 人设并自动激活 devflow-core 生命周期（Brainstorm → Spec/Cut → Plan → Build → Prove）与验证完成闭环；workspace 指令与技能目录延迟一步注入。
 order: 6

package/assets/skills/devflow-adversarial/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: devflow-adversarial
-description: "Use when a user explicitly asks for an independent deep adversarial review, upgraded adversarial review, red-team review, 对抗审查, 升级版对抗审查, or a five-angle challenge of current work. It can run at any task stage and does not read, require, modify, or hand off to devflow-prove, PUA, Build, Learn, or any completion state."
+description: "Use when a user explicitly asks for an independent deep adversarial review, upgraded adversarial review, red-team review, 对抗审查, 升级版对抗审查, 红队审查, 五角度挑战, or a five-angle challenge of current work. It can run at any task stage and does not read, require, modify, or hand off to devflow-prove, PUA, Build, Learn, or any completion state."
 ---
 
 # DevFlow Adversarial Review
 
 Run an independent, user-requested challenge of the current task materials. This skill does not declare global task status or perform work beyond review.
 
+Use this skill when the user asks to challenge whether the current result holds. When the user asks what is missing or uncertain instead, use `devflow-find-fault`.
+
 ## Entry Gate
 
 1. Confirm the user explicitly requested this review.
@@ -14,7 +16,9 @@ Run an independent, user-requested challenge of the current task materials. This
 3. If the target is unclear, ask one smallest question to identify it.
 4. As an independent manual review, do not read, require, or alter `devflow-prove`, PUA, Build, Learn, or any lifecycle state.
 
-On DeepSeek Harness (DSH), run this review as a fresh `subagent` with no conversation seed so the challenge is genuinely independent of the main agent's reasoning; the subagent returns findings only and never declares lifecycle status, edits files, or invokes another skill.
+On DeepSeek Harness (DSH), dispatch a fresh `subagent` so the challenge stays independent of the main agent's reasoning. Call the `subagent` tool once with `run_in_background: false` and a complete standalone prompt that names the review target and the material paths, and instructs the subagent to read those materials and return evidence-backed findings (the subagent has no conversation seed and cannot see this conversation). Then run the review in bounded rounds, one review unit per round: after each round the subagent returns that unit's findings, you aggregate them and report progress, then continue the same subagent conversation with the `send_message` tool. After the final unit, assemble the complete `Required Output` below from the aggregated findings. The subagent returns findings only — it never declares lifecycle status, edits files, or invokes another skill. If a round returns nothing usable (timeout, truncation, or failure), record it under `Context limitations`, retry that unit once with a narrower instruction, and continue with the remaining units; never silently drop a unit.
+
+Review units: one of the five angles per round, five rounds in total.
 
 ## Five-Angle Review
 
@@ -37,6 +41,7 @@ Findings:
 - Critical: <finding or none>; evidence: <facts>; confidence: high/medium/low
 - Important: <finding or none>; evidence: <facts>; confidence: high/medium/low
 - Observation: <finding or none>; evidence: <facts>; confidence: high/medium/low
+Repeat one bullet per finding; order findings by severity, then confidence; write none when a level has no finding.
 Five-angle coverage:
 - Requirement coverage: <challenge and result>
 - Reachability: <challenge and result>

package/assets/skills/devflow-find-fault/SKILL.md

@@ -7,6 +7,8 @@ description: "Use when a user explicitly asks to find faults, identify the bigge
 
 Run an independent, user-requested critique of the current task materials. This skill identifies gaps and uncertainty without declaring global task status.
 
+Use this skill when the user asks what is missing, unrecognized, or uncertain. When the user asks a five-angle challenge of whether the result holds instead, use `devflow-adversarial`.
+
 ## Entry Gate
 
 1. Confirm the user explicitly requested find-fault review.
@@ -14,12 +16,16 @@ Run an independent, user-requested critique of the current task materials. This
 3. Ask one smallest question when the target is unclear.
 4. As an independent manual review, do not read, require, or alter `devflow-prove`, PUA, Build, Learn, or any lifecycle state.
 
-On DeepSeek Harness (DSH), run this review as a fresh `subagent` with no conversation seed so the critique is genuinely independent of the main agent's reasoning; the subagent returns findings only and never declares lifecycle status, edits files, or invokes another skill.
+On DeepSeek Harness (DSH), dispatch a fresh `subagent` so the critique stays independent of the main agent's reasoning. Call the `subagent` tool once with `run_in_background: false` and a complete standalone prompt that names the review target and the material paths, and instructs the subagent to read those materials and return evidence-backed findings (the subagent has no conversation seed and cannot see this conversation). Then run the review in bounded rounds, one review unit per round: after each round the subagent returns that unit's findings, you aggregate them and report progress, then continue the same subagent conversation with the `send_message` tool. After the final unit, assemble the complete `Required Output` below from the aggregated findings. The subagent returns findings only — it never declares lifecycle status, edits files, or invokes another skill. If a round returns nothing usable (timeout, truncation, or failure), record it under `Context limitations`, retry that unit once with a narrower instruction, and continue with the remaining units; never silently drop a unit.
+
+Review units: one question per round — the three default questions and every user-supplied question — plus one final round for the unease check when the target contains implementation material.
 
 ## Post-Implementation Unease Check
 
 When target materials include an implemented feature, diff, or completion-ready result, also inspect whether the implementation has silently decided business behavior the user never confirmed. This check is for requirement-confidence gaps, not code quality or test coverage.
 
+When the target contains no implementation material (no diff, no new code, no completion-ready result), skip the unease check and report `Unease check: not applicable` with the reason; do not invent business decisions from requirements text alone.
+
 1. Compare explicit requirements, conversation evidence, acceptance criteria, and current behavior against the implementation.
 2. List every material decision with no direct confirmation, especially: ordering, filtering, defaults, empty states, pagination, permissions, state transitions, exceptions, retries, boundary inputs, and conflicting actor outcomes.
 3. For each decision, state the encoded behavior or implicit assumption, plausible alternative interpretations, impact if wrong, the confirmation question, and a temporary recommendation.
@@ -78,6 +84,7 @@ Findings:
 - Critical: <finding or none>; evidence: <facts>; confidence: high/medium/low
 - Important: <finding or none>; evidence: <facts>; confidence: high/medium/low
 - Observation: <finding or none>; evidence: <facts>; confidence: high/medium/low
+Repeat one bullet per finding; order findings by severity, then confidence; write none when a level has no finding.
 Context limitations: <unavailable material or none>
 Suggested next action: <manual action for the user, or none>
 ```

package/assets/skills/devflow-prove/references/flow-self-test.md

@@ -219,6 +219,8 @@ Expected behavior:
 - Must begin after the explicit review request without a separate confirmation prompt. Must not add a second confirmation gate after the explicit review request.
 - Must ask one smallest question only when the review target is unclear.
 - Must cover all five fixed dimensions: requirement coverage, reachability, boundaries and regressions, evidence strength, and user-visible outcome.
+- Must run on DSH in bounded rounds, one round per review angle, with the subagent returning each round's findings to the main agent for aggregation.
+- Must dispatch a fresh subagent.
 - Findings must use `Critical`, `Important`, or `Observation` and include evidence, confidence, and context limitations.
 - Must not read, require, modify, or hand off to `devflow-prove`, PUA, Build, Learn, or any completion state.
 - Must not edit code, create a task, invoke another skill, or declare global task status.
@@ -249,6 +251,8 @@ Expected behavior:
 - Must run only because the user explicitly requested it; it may inspect materials from any task stage.
 - Must answer biggest omission, unrecognized blind spot, and least certain point, plus every explicit user follow-up question.
 - When target material contains implemented work, a diff, or a completion-ready result, must also run the post-implementation unease check: find materially unconfirmed business decisions, show the encoded assumption and alternatives, then classify high/medium/low risk with rationale, a user confirmation question, and temporary recommendation.
+- Must run on DSH in bounded rounds, one round per question or unease-check block, with the subagent returning each round's findings to the main agent for aggregation.
+- Must dispatch a fresh subagent.
 - High-risk unease decisions must prevent a claim that the feature fully meets requirements; medium-risk decisions must be marked `pending confirmation`.
 - Each answer must separate facts, inference, and unknowns, then state confidence and a next step; findings must use `Critical`, `Important`, or `Observation` with evidence and context limitations.
 - Must not read, require, modify, or hand off to `devflow-prove`, PUA, Build, Learn, or any completion state.

package/lib/index.js

@@ -29,7 +29,7 @@ export function bundledAssetsRoot() {
 
 /** Model-facing announcement: plugin presence, preset, and conflict policy. */
 export const DEVFLOW_GUIDANCE =
-  '本机已安装 @devflow-core/dsh-devflow 插件（DevFlow agent preset 分发）：新建会话的预设选择器中可选「DevFlow 2.0 (Anchored)」（两阶段锚定 + Code Mode）。插件启动时把 devflow-2 预设、devflow-* skills、devflow*.toml 命令与 devflow-*.js 验证脚本同步到 ~/.dsh/（.agent-presets/skills/commands/scripts）；冲突策略为 devflow-* 权威覆盖（字节相同跳过），非 devflow 资产永不触碰；升级插件后重启即自动更新。用户提到「DevFlow / devflow-2 / 锚定模式」时即指本插件，请据此协作。'
+  '本机已安装 @devflow-core/dsh-devflow 插件（DevFlow agent preset 分发）：新建会话的预设选择器中可选「DevFlow 2.0」（两阶段锚定 + Code Mode）。插件启动时把 devflow-2 预设、devflow-* skills、devflow*.toml 命令与 devflow-*.js 验证脚本同步到 ~/.dsh/（.agent-presets/skills/commands/scripts）；冲突策略为 devflow-* 权威覆盖（字节相同跳过），非 devflow 资产永不触碰；升级插件后重启即自动更新。用户提到「DevFlow / devflow-2 / 锚定模式」时即指本插件，请据此协作。'
 
 /**
  * Mount the plugin: sync bundled DevFlow assets into the harness-home

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-core/dsh-devflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DevFlow for DeepSeek Harness: devflow-2 agent preset + skills + commands + verification scripts, synced into ~/.dsh on host startup.",
   "type": "module",
   "engines": {
@@ -22,6 +22,7 @@
     "assets",
     "cordis.patch.yml",
     "README.md",
+    "RELEASE.md",
     "NOTICE"
   ],
   "license": "Apache-2.0",