dsh-issue2pr 0.1.0 → 0.3.1

package/README.md

@@ -2,6 +2,7 @@
   <img src="docs/assets/banner.svg" alt="dsh-issue2pr — 从一条 Issue 到一份被合并的 PR，中间不能跳步" width="100%">
   <p>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2A3F7A?style=flat-square" alt="License: MIT"></a>
+    <a href="https://www.npmjs.com/package/dsh-issue2pr"><img src="https://img.shields.io/npm/v/dsh-issue2pr?style=flat-square&color=506B3A" alt="npm version"></a>
     <img src="https://img.shields.io/badge/node-%E2%89%A5%2018-506B3A?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node ≥ 18">
     <img src="https://img.shields.io/badge/host-DSH%20%E6%8F%92%E4%BB%B6-A07A1F?style=flat-square" alt="DSH 插件">
     <img src="https://img.shields.io/badge/pipeline-11%20stages%20%C2%B7%204%20gates-2A3F7A?style=flat-square" alt="11 stages · 4 review gates">
@@ -22,7 +23,7 @@
 ## ✨ 特性总览
 
 - 🔗 **11 阶段全链路**：Issue 分析 → 检索 → 代码理解 → 根因假设 → 任务规划 → 编码 → 补丁管线 → 测试 → 审查 → PR 构建，一步不省。
-- 🚦 **人工复核门**：P5 / P6 / P9 / P11 四道关键门控，`approve` 放行、`reject` 带意见打回重跑；复核模式可选每阶段 / 仅关键 / 全自动。
+- 🚦 **人工复核门**：P5 / P6 / P9 / P11 四道关键门控，`approve` 放行、`reject` 带意见打回重跑；复核模式可选每阶段 / 仅关键 / 全自动。打回委托阶段会**先清空旧外部产物**（防止过期 patch 复用）；委托阶段放行前必须通过**机器验证**（拿到委外结果 + 对 HEAD 基线可应用），全自动模式下就绪后由插件**自动验证并放行**，不空手放行也不带病放行。
 - 🧾 **产物证据链**：每个阶段落盘一份编号产物（`01-*.json` … `10-pr-description.md`），输入来自上游产物、输出去往下游契约，可独立审查、可打回重做。
 - 🔁 **可回滚**：Patch Pipeline 带台账（ledger），只撤销 Agent 引入的修改，不碰用户自己的代码。
 - 🧪 **真实测试**：结果必须来自真实工具执行——在克隆的仓库里跑真实测试命令，完整输出落盘可回溯。
@@ -38,7 +39,7 @@
   <img src="docs/assets/pipeline.svg" alt="11 阶段流水线：主流程 P1→P9→P11，复核门 P5/P6/P9/P11，失败旁路 P10" width="100%">
 </div>
 
-一次 **Run** 就是一条证据链：发起时从触发源读入 Issue 原文，主流程 `P1→P9→P11` 依次推进，每步落盘产物；任何阶段失败立即停下并进入 P10 分类旁路；到达复核门时等待人工 `approve / reject`，打回的意见会传回该阶段重新执行。
+一次 **Run** 就是一条证据链：发起时从触发源读入 Issue 原文，主流程 `P1→P9→P11` 依次推进，每步落盘产物；任何阶段失败立即停下并进入 P10 分类旁路；到达复核门时等待人工 `approve / reject`，打回的意见会传回该阶段重新执行（该阶段的旧外部产物同时清场；P7 应用补丁前会把工作区重置回基线，打回重跑不会残留上一轮补丁）。
 
 ### 阶段一览
 
@@ -76,7 +77,7 @@
 | --- | --- |
 | `every` | 每个阶段完成后都进入复核门 |
 | `key-only` | 仅 P5 / P6 / P9 / P11 四道关键门停（推荐） |
-| `auto` | 全自动推进，不停留 |
+| `auto` | 全自动推进，不停留（委托阶段例外：见下方「委外产物验证」） |
 
 **P6 执行模式 `p6Mode`** —— 决定代码由谁写：
 
@@ -86,6 +87,21 @@
 | `session` | 生成任务包交给 DSH 会话执行，人工完成后通过复核门放行 |
 | `claude` | 任务包自动委托 Claude Code CLI 无人值守执行（`--add-dir` 写产物目录，停止/删除时杀进程树），失败回退等人工会话 |
 
+**委外产物验证（拿到结果 + 验证 ok 才往下流转）** —— 委托阶段（`session` / `claude` / 各阶段委托开关）的放行不看「文件存在」，看「产物可用」，验证分两层：
+
+1. **结构完整**：补丁清单与 P7 应用清单完全同口径；逐份补丁存在、非空、形如 unified diff；`coder-report.json` 可解析且清单与文件一致。
+2. **应用性演练**：用一次性 git 索引从 `HEAD` 构建基线，按应用序逐份 `git apply --cached` 演练——不碰工作区，语义与 P7（重置后顺序应用）完全一致；对基线不可应用的补丁在此拦截。
+
+三种放行路径同一验证口径：**人工门**（`every` / `key-only`）`approve` 时必须验证通过；**全自动**（`auto`）插件轮询产物就绪（默认 5s）自动验证，通过即放行并落 `auto-approve` 审计记录，连续 3 次不过（产物稳定存在但不可用）则 Run 显式失败并走 P10 归因；**advance 直通**（如 `claude` 同步执行完）验证不过就地失败，绝不把坏补丁带进 P7。
+
+### 委外智能体：多方式发现 + 测试门禁
+
+选 `claude` 模式后，项目页与配置页出现「委外智能体」绑定卡：
+
+- **多方式发现**：自动扫描五种来源并去重合并——项目配置 > 环境变量 `ISSUE2PR_CLAUDE_BIN` > 常见安装位置 > `npm config get prefix` 全局目录 > PATH 查找；也可手动指定完整路径（留空 = 自动探测）。
+- **测试门禁**：点「测试门禁」真实跑一次极小调用，三步全绿（定位 → `--version` → 认证微任务）才能保存——`403 IP access denied by API-Key restrictions`、未登录这类认证错误在**绑定时**就拦截并给出处置提示（IP 白名单 / 登录 / 代理出口），而不是等 Run 走到 P6 才失败回退。微任务仅一轮、几十 token，费用可忽略。
+- 改过绑定路径后门禁结果即失效，需重测；服务端保存时另有 `--version` 级快检兜底（拦路径写错 / 未安装）。
+
 ## 🚀 快速开始
 
 ### 环境要求
@@ -97,16 +113,22 @@
 
 ### 安装
 
-把本插件克隆进 DSH 插件目录，然后重启 DSH：
+已发布到 npm（推荐——预构建包，无需授权构建脚本）：
+
+```bash
+dsh plugin --profile web add dsh-issue2pr
+```
+
+或从源码安装——把本插件克隆进 DSH 插件目录，然后重启 DSH：
 
 ```bash
 # Windows: C:\Users\<you>\.dsh\plugins\
 # macOS / Linux: ~/.dsh/plugins/
 cd ~/.dsh/plugins
-git clone https://github.com/LONGSASASASASA/dsh-issue2PR.git dsh-issue2pr
+git clone https://github.com/LONGSASASASASA/dsh-issue2pr.git dsh-issue2pr
 ```
 
-> 也可以通过 [dsh-plugin-manager](https://github.com/LONGSASASASASA) 插件安装与管理。数据默认存放在 `~/.dsh/issue2pr/`（与插件目录分离，升级插件不丢数据）。
+> 也可以通过 [dsh-plugin-manager](https://github.com/LONGSASASASASA) 插件安装与管理；审阅源码后可用 `dsh plugin --profile web add github:LONGSASASASASA/dsh-issue2pr#<commit>` 锁定 commit 安装。数据默认存放在 `~/.dsh/issue2pr/`（与插件目录分离，升级插件不丢数据）：`projects/<slug>/repo` 是基线克隆，`projects/<slug>/worktrees/<runId>` 是每个 Run 的独立工作区（同项目并发 Run 互不污染，Run 删除时一并清理）。
 
 ### 五分钟跑通第一单
 
@@ -234,6 +256,8 @@ git clone https://github.com/LONGSASASASASA/dsh-issue2PR.git dsh-issue2pr
 | POST | `/issue2pr/api/connections/test` | 凭据探活 |
 | POST | `/issue2pr/api/connections/test-repo` | 真实仓库连通性（`git ls-remote`） |
 | GET | `/issue2pr/api/preflight` | 环境健康探测（git / claude CLI / LLM 路由来源） |
+| GET | `/issue2pr/api/agents/discover?slug=` | 委外智能体多方式发现（配置/env/常见位置/npm 前缀/PATH） |
+| POST | `/issue2pr/api/agents/test` | 委外智能体测试门禁（定位 → 版本 → 认证微任务） |
 | POST | `/issue2pr/api/check-local` | 本地触发源存在性 |
 | POST | `/issue2pr/api/assistant/ask` | 悬浮助手问答（NDJSON 流式） |
 | GET/POST | `/issue2pr/api/projects` | 项目列表 / 保存 |
@@ -255,14 +279,12 @@ npm test        # node --test，覆盖 API / 流水线 / 各阶段执行器 /
 | --- | --- |
 | `index.js` | REST API + 驱动循环（node 半，随宿主同生共死） |
 | `client.js` | 工作台 UI（web 半） |
-| `lib/pipeline.js` | 状态机核心：`advance` 推进、`applyReview` 复核 |
-| `lib/stageConfig.js` | 阶段能力表、配置合并、委托任务包 |
-| `lib/stages/p1…p11` | 11 个阶段执行器（输入契约 → 产物落盘） |
-| `lib/llm.js` | LLM 路由解析 + JSON 契约解析（失败重试一次） |
-| `lib/connections.js` | 托管连接、凭据注入与脱敏 |
-| `lib/store.js` | 目录规则与产物读写（唯一允许写盘的地方） |
+| `lib/core/` | 流水线骨架：`pipeline.js` 状态机（`advance` 推进、`applyReview` 复核）、`stageConfig.js` 阶段能力表与委托任务包、`store.js` 目录规则与产物读写（唯一允许写盘的地方） |
+| `lib/stages/` | `p1…p11` 11 个阶段执行器（输入契约 → 产物落盘） |
+| `lib/infra/` | 运行设施：`llm.js` LLM 路由与 JSON 契约解析（失败重试一次）、`connections.js` 托管连接与凭据注入脱敏、`repoState.js` 基线克隆与 per-Run worktree |
+| `lib/delegate/` | 委外体系：`agents.js` 委外智能体发现与测试门禁、`delegateVerify.js` 委外产物机器验证 |
 | `lib/assistant.js` | 智能助手上下文聚合 |
-| `tests/` | 单测 + `e2e-live.mjs` 真实链路演练 |
+| `tests/` | `unit/` 模块单测 · `stages/` 阶段执行器 · `integration/` API 与流水线装配 · `manual/` 人工演练（`e2e-live.mjs` 真实链路等，不入 npm test） |
 
 设计背后的完整调研（端到端架构、Sub-Agent 取舍、缓存与记忆边界、评测指标）见 [issue2pr-research.html](./issue2pr-research.html)。