patchwarden 1.5.0 → 1.6.1

package/docs/evidence-pack-schema.md

@@ -0,0 +1,215 @@
+# Evidence Pack v2 文件结构
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。（Evidence Pack v2）
+> 相关页面：`export_task_evidence_pack` MCP 工具、Lineage 与 Evidence Pack 工作流
+
+## 概述
+
+`export_task_evidence_pack` 导出 8 个有界文件到
+`.patchwarden/evidence-packs/<lineage_id>/`。每个文件只包含有界摘要，
+**不**包含完整 stdout/stderr/diff/secrets/.env/token/cookie/凭据路径。
+
+## 文件清单
+
+| 文件 | 用途 |
+| --- | --- |
+| `evidence.json` | 完整有界证据包（机器可读），含 lineage、policy、catalog 摘要。 |
+| `EVIDENCE.md` | 人类可读的 Markdown 证据摘要。 |
+| `risk.json` | 聚合的风险项与严重度（high/medium/low）。 |
+| `verify.json` | 每轮迭代和 direct session 的结构化验证记录。 |
+| `diffstat.json` | 文件级增删统计（路径、增删行数），不含完整 diff。 |
+| `lineage.json` | lineage 有界摘要（goal、final_status、stop_reason、task 计数）。 |
+| `attestation.json` | 版本、commit、Node/OS、tool profile、schema epoch 等溯源信息。 |
+| `redactions.json` | 本次导出中脱敏的类别与计数（不存原始隐藏值）。 |
+
+## risk.json
+
+从 lineage 的 rounds（`fail_checks` / `warn_checks`）和 `warnings` 聚合风险项。
+
+```json
+{
+  "risks": [
+    {
+      "source": "round",
+      "task_id": "task-main",
+      "severity": "high",
+      "category": "fail_check",
+      "detail": "verification failed: npm test exited with code 1"
+    },
+    {
+      "source": "round",
+      "task_id": "task-main",
+      "severity": "medium",
+      "category": "warn_check",
+      "detail": "minor scope drift"
+    },
+    {
+      "source": "lineage",
+      "severity": "low",
+      "category": "warning",
+      "detail": "diff.patch was truncated"
+    }
+  ],
+  "count": 3,
+  "by_severity": { "high": 1, "medium": 1, "low": 1 }
+}
+```
+
+**严重度映射**：
+
+- `high` — round 的 `fail_checks`
+- `medium` — round 的 `warn_checks`
+- `low` — lineage 的 `warnings`
+
+如果 lineage 无风险信息，写 `{"risks": [], "count": 0, "by_severity": {"high": 0, "medium": 0, "low": 0}}`。
+
+## verify.json
+
+从 lineage 的 rounds 和 direct_sessions 提取结构化验证记录。
+
+```json
+{
+  "records": [
+    {
+      "source": "round",
+      "task_id": "task-main",
+      "role": "main",
+      "verification_status": "passed",
+      "audit_verdict": "pass",
+      "passed": true
+    },
+    {
+      "source": "direct_session",
+      "session_id": "direct-one",
+      "verification_status": "passed",
+      "audit_verdict": "pass",
+      "passed": true,
+      "command_count": 3,
+      "passed_commands": 3,
+      "failed_commands": 0
+    }
+  ],
+  "count": 2,
+  "summary": { "total": 2, "passed": 2, "failed": 0 },
+  "latest_status": "passed",
+  "overall_passed": true
+}
+```
+
+**有界规则**：不含 stdout_tail/stderr_tail/完整验证日志，只保留状态与计数摘要。
+
+如果 lineage 无验证信息，写空 records 数组。
+
+## diffstat.json
+
+从 lineage 引用的 task 目录（`<tasksDir>/<task_id>/file-stats.json`）聚合文件级增删统计。
+
+```json
+{
+  "files": [
+    {
+      "path": "src/index.ts",
+      "status": "modified",
+      "additions": 12,
+      "deletions": 3,
+      "task_id": "task-main"
+    }
+  ],
+  "count": 1,
+  "totals": { "additions": 12, "deletions": 3 }
+}
+```
+
+**有界规则**：只存文件路径与行级增删计数，**不**含完整 diff 内容。所有路径经过
+`redactSensitiveValue` 脱敏处理。如果 task 目录不存在或 file-stats.json 缺失，写空数组。
+
+## lineage.json
+
+lineage 的有界摘要，不含完整 rounds 详情或 warnings/errors 原文。
+
+```json
+{
+  "lineage_id": "lineage_20260709_120000_a1b2c3d4",
+  "goal": "Fix authentication bug",
+  "final_status": "accepted",
+  "stop_reason": "success",
+  "iterations_count": 1,
+  "task_counts": {
+    "main": 1,
+    "fix": 0,
+    "cleanup": 0,
+    "direct_sessions": 1
+  },
+  "verification": { "latest_status": "passed", "passed": true },
+  "worktree": { "isolation_mode": "worktree", "status": "active" },
+  "agent_routing": { "selected_agent": "codex" },
+  "warnings_count": 0,
+  "errors_count": 0,
+  "truncated": false
+}
+```
+
+## attestation.json
+
+记录生成此证据包时的环境与版本溯源信息。
+
+```json
+{
+  "patchwarden_version": "1.6.1",
+  "package_version": "1.6.1",
+  "commit": "bc950a2",
+  "node_version": "v20.11.0",
+  "os": { "platform": "win32", "arch": "x64" },
+  "tool_profile": "full",
+  "schema_epoch": "2026-07-19-v15",
+  "generated_at": "2026-07-09T12:00:00.000Z"
+}
+```
+
+**字段说明**：
+
+- `patchwarden_version` — `src/version.ts` 中的 `PATCHWARDEN_VERSION`
+- `package_version` — `package.json` 中的 version（与 patchwarden_version 一致）
+- `commit` — `git rev-parse --short HEAD` 获取的 short hash；非 Git 环境为 `"unknown"`
+- `node_version` — `process.version`
+- `os` — `process.platform` 与 `process.arch`
+- `tool_profile` — 当前工具目录快照的 profile
+- `schema_epoch` — `TOOL_SCHEMA_EPOCH`
+
+## redactions.json
+
+记录本次导出中脱敏的类别、原因与计数。**不存原始隐藏值**。
+
+```json
+{
+  "redactions": [
+    {
+      "category": "known_token_format",
+      "reason": "matched known token format",
+      "count": 1
+    }
+  ],
+  "total_redacted": 1,
+  "bounded": true,
+  "note": "Only categories and counts are recorded; original secret values are never persisted."
+}
+```
+
+**脱敏类别**：
+
+| category | 匹配内容 |
+| --- | --- |
+| `private_key` | PEM 私钥块 |
+| `bearer_token` | `Bearer <token>` 格式 |
+| `npm_token` | npm `_?authToken=` 赋值 |
+| `credential_assignment` | `api_key=` / `secret=` / `password=` 等凭据赋值 |
+| `known_token_format` | `sk_` / `ghp_` / `github_pat_` 前缀的 token |
+
+## 安全边界
+
+- 所有 v2 文件经过 `redactSensitiveValue` 处理后才写入磁盘。
+- `redactions.json` 只记录类别 + 原因 + 计数，**永不**持久化原始密钥值。
+- `diffstat.json` 只存文件路径与行级计数，不含 diff 正文。
+- `verify.json` 只存状态摘要，不含 stdout/stderr tail。
+- `.patchwarden/evidence-packs/` 不进入 npm 包（package.json `files` 已排除）。
+- MCP 工具 `export_task_evidence_pack` 的输入参数无破坏性变更，只是输出多了文件。

package/docs/lineage-evidence-pack-workflow.md

@@ -0,0 +1,127 @@
+# Lineage 与 Evidence Pack 工作流
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 相关页面：Dashboard（Lineage / Evidence Pack 卡片）、Lineage Detail 模态框
+
+## 目的
+
+`run_task_loop` 是 PatchWarden 的受守护循环（guarded loop）：在 watcher、命令
+白名单、workspace 隔离、敏感路径拦截下，自动执行“主任务 → 修复 → 清理”迭代。
+Lineage 记录整条循环的因果链，Evidence Pack 把通过验收的 lineage 导出为可归档的
+证据文件，整个过程不泄露完整日志或密钥。
+
+## 核心概念
+
+- **Lineage**：一次 `run_task_loop` 的完整记录，包含 goal、final_status、
+  stop_reason、iterations、main/fix/cleanup 各角色的 task 计数、
+  direct_verification、warnings_count。
+- **Iteration**：循环中的单次迭代，按角色（main / fix / cleanup）分组，记录
+  status、acceptance_status、verification、audit、stop_reason、
+  final_recommended_next_action。
+- **Evidence Pack**：与 lineage 绑定的证据包，写入
+  `.patchwarden/evidence-packs/<lineage_id>/`，包含 `evidence.json` 与
+  `EVIDENCE.md` 两个文件（v2 额外包含 6 个结构化文件，见下文）。
+- **export_status**：证据包的导出状态，`pending` / `exported` / `failed`。
+
+## 工作流
+
+### 1. 启动受守护循环
+
+通过 MCP 工具 `run_task_loop` 启动循环，可指定：
+
+- `agent="auto"` — 让 PatchWarden 自动路由到合适的 agent
+- `scope_files` — 路由提示
+- `isolation_mode="worktree"` — 可选的 git worktree 隔离
+
+循环结束后会生成一条 lineage 记录。
+
+### 2. 在 Dashboard 查看 Lineage 状态
+
+Dashboard 的 Lineage 卡片区分空/已填充两种状态：
+
+- **空状态**：显示 “No loop lineage yet”，提供 “Start guarded loop” 和
+  “View recent loop runs” 入口。
+- **已填充状态**：显示 lineage_id、goal、final_status、stop_reason、iterations、
+  main/fix/cleanup task 计数、direct_verification、warnings_count。
+
+### 3. 打开 Lineage Detail 排查成功/失败原因
+
+点击 lineage 卡片可打开 Lineage Detail 模态框，按角色（main / fix / cleanup）
+分组展示每次迭代的：
+
+- status、acceptance_status
+- verification 摘要
+- audit 摘要
+- stop_reason
+- final_recommended_next_action
+
+如果 `final_status` 为 `failed`，先看最后一个迭代的 `stop_reason` 和
+`final_recommended_next_action`，再决定是重建任务还是人工介入。
+
+### 4. 验收通过后导出 Evidence Pack
+
+只有 lineage 存在且验收通过后，Evidence Pack 卡片才会进入可导出状态：
+
+- **空状态**：显示 “Evidence pack is available after run_task_loop.”
+- **已填充状态**：显示 lineage_id、export_status、evidence_json_exists、
+  evidence_md_exists、exported_at。
+
+点击 **Export evidence pack** 调用 `POST /api/evidence-packs/:lineageId/export`，
+PatchWarden 会把有界摘要写入：
+
+```text
+.patchwarden/evidence-packs/<lineage_id>/evidence.json
+.patchwarden/evidence-packs/<lineage_id>/EVIDENCE.md
+```
+
+### 4.1 Evidence Pack v2 结构化文件（基于 v1.5.1 源码）
+
+v2 在原有 `evidence.json` 与 `EVIDENCE.md` 基础上额外导出 6 个有界文件：
+
+```text
+.patchwarden/evidence-packs/<lineage_id>/risk.json
+.patchwarden/evidence-packs/<lineage_id>/verify.json
+.patchwarden/evidence-packs/<lineage_id>/diffstat.json
+.patchwarden/evidence-packs/<lineage_id>/lineage.json
+.patchwarden/evidence-packs/<lineage_id>/attestation.json
+.patchwarden/evidence-packs/<lineage_id>/redactions.json
+```
+
+| 文件 | 用途 |
+| --- | --- |
+| `risk.json` | 聚合的风险项与严重度（high/medium/low），来源为 rounds 的 fail_checks/warn_checks 与 lineage warnings。 |
+| `verify.json` | 每轮迭代和 direct session 的结构化验证记录（状态、audit、command 计数）。 |
+| `diffstat.json` | 文件级增删统计（路径、增删行数），不含完整 diff。 |
+| `lineage.json` | lineage 有界摘要（goal、final_status、stop_reason、task 计数）。 |
+| `attestation.json` | 版本、commit short hash、Node/OS、tool profile、schema epoch。 |
+| `redactions.json` | 本次导出中脱敏的类别与计数（不存原始隐藏值）。 |
+
+每个文件都经过 `redactSensitiveValue` 脱敏处理。详细字段结构与示例见
+[Evidence Pack v2 文件结构](./evidence-pack-schema.md)。
+
+### 5. 查看与归档证据文件
+
+导出后可使用卡片上的按钮：
+
+- **Open EVIDENCE.md** — 打开人类可读的 Markdown 证据
+- **Open evidence.json** — 打开机器可读的 JSON 证据
+- **Copy lineage_id** — 复制 lineage_id 用于后续追溯
+
+## 安全边界
+
+- Evidence Pack 只包含有界摘要，**不**包含完整日志、stdout/stderr tail、
+  完整 diff、verification 日志或密钥内容。
+- worktree 模式不会自动 merge 或删除 worktree，需要人工确认。
+- 导出操作只写本地文件，不执行 `npm publish` / `git push` / `git tag` /
+  `gh release` 等远程写。
+- direct_verification 仅作为独立验证通道，不会自动 patch 文件。
+
+## 相关 API 端点
+
+- `GET /api/lineages` — lineage 列表（含 goal / final_status / stop_reason /
+  iterations / task counts / direct_verification / warnings_count）
+- `GET /api/lineages/:id` — 单条 lineage 详情
+- `GET /api/evidence-packs` — 证据包列表（含 export_status /
+  evidence_json_exists / evidence_md_exists / exported_at）
+- `GET /api/evidence-packs/:lineage_id` — 单个证据包详情
+- `POST /api/evidence-packs/:lineageId/export` — 触发证据包导出

package/docs/mcp-inspector-testing.md

@@ -0,0 +1,200 @@
+# 用 MCP Inspector 测试 PatchWarden
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 说明：本文以 PatchWarden 为例介绍通用的 MCP server 调试方法，
+> MCP Inspector 是 modelcontextprotocol 社区维护的独立工具。
+
+## MCP Inspector 是什么
+
+MCP Inspector（`modelcontextprotocol/inspector`）是用于调试 MCP server 的官方工具，
+主要能力包括：
+
+- 连接到本地或远程 MCP server。
+- 列出 server 暴露的 tools、resources、prompts。
+- 交互式调用 tool 并查看结构化响应。
+- 检查 server 的 capabilities 声明。
+
+对于 PatchWarden 这类本地 MCP server，Inspector 是验证工具行为、
+确认 safe 输出不含敏感内容的最直接手段。
+
+## 前置准备
+
+### 1. 安装 MCP Inspector
+
+```powershell
+# 全局安装（Node.js 环境）
+npm.cmd install -g @modelcontextprotocol/inspector
+
+# 或直接通过 npx 临时运行
+npx @modelcontextprotocol/inspector
+```
+
+### 2. 确认 PatchWarden 可启动
+
+在 PatchWarden 仓库下确认构建产物存在：
+
+```powershell
+# 在 PatchWarden 仓库根目录
+npm.cmd run build
+# 确认 dist/ 目录存在 MCP server 入口
+```
+
+### 3. 准备测试 workspace
+
+准备一个独立的测试 workspace，避免在生产仓库上直接调试：
+
+```powershell
+# 示例：创建测试用 workspace
+New-Item -ItemType Directory -Path "D:\test-workspace\demo-repo" -Force
+```
+
+并在该 workspace 下放置最小化的 `.patchwarden/config.json` 与 `project-policy.json`。
+
+## 连接 PatchWarden
+
+### 方式一：Inspector GUI
+
+```powershell
+# 启动 Inspector
+npx @modelcontextprotocol/inspector
+
+# Inspector 默认在 http://localhost:6274 提供 Web UI
+```
+
+在 Inspector UI 中：
+
+1. Transport 选择 `STDIO`。
+2. Command 填写 PatchWarden server 启动命令（如 `node` ）。
+3. Args 填写 PatchWarden dist 入口路径。
+4. 点击 Connect。
+
+### 方式二：直接通过 Inspector CLI
+
+```powershell
+# Inspector CLI 模式，连接 PatchWarden 并列出 tools
+npx @modelcontextprotocol/inspector cli `
+  --transport stdio `
+  --command node `
+  --args "D:\ai_agent\Reasonix\reasonix_program\PatchWarden\dist\index.js"
+```
+
+## 调用工具并验证响应
+
+### 列出可用工具
+
+连接成功后，在 Inspector 中调用 `tools/list`，确认 PatchWarden 暴露的工具清单，
+例如：
+
+- `list_agents`
+- `run_safe_task`
+- `export_task_evidence_pack`
+- `get_safe_audit`
+- 其他 safe-first 工具
+
+### 调用一个 safe 工具
+
+在 Inspector UI 中选择 `run_safe_task`，填入参数：
+
+```json
+{
+  "agent": "opencode",
+  "task": "echo hello",
+  "declaredFiles": ["README.md"]
+}
+```
+
+查看返回的 `safe_result`，确认：
+
+- 返回内容是有界摘要（字节数受 `safeResult.maxBytes` 约束）。
+- 不包含完整 stdout / stderr。
+- 不包含敏感路径或凭据信息。
+
+### 验证 safe 输出不含敏感内容
+
+PatchWarden 的安全契约要求 safe 输出不得包含 token、cookie、`.env` 内容等。
+可用以下方法验证：
+
+```powershell
+# 导出 evidence pack 后检查文件内容
+$pack = "D:\test-workspace\demo-repo\.patchwarden\evidence-packs"
+Select-String -Path "$pack\*\evidence.json" -Pattern "token|secret|password|api_key|cookie" -CaseSensitive:$false
+# 期望：无匹配，或仅匹配 redactions.json 中已脱敏的占位符
+```
+
+```powershell
+# 检查 redactions.json 确认脱敏记录
+Get-Content "$pack\*\redactions.json" | ConvertFrom-Json
+```
+
+## CLI smoke testing 示例
+
+以下为通用的 MCP server smoke test 方法，PatchWarden 作为示例之一。
+
+### 启动 PatchWarden 并发送 initialize 请求
+
+```powershell
+# 通过 Inspector 的 CLI 模式发送 initialize
+npx @modelcontextprotocol/inspector cli `
+  --transport stdio `
+  --command node `
+  --args "D:\ai_agent\Reasonix\reasonix_program\PatchWarden\dist\index.js" `
+  --method initialize `
+  --params '{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{}}'
+```
+
+确认响应中包含 PatchWarden 的 serverInfo 与 capabilities。
+
+### 列出工具并保存清单
+
+```powershell
+# 将 tools/list 结果保存到文件便于审查
+npx @modelcontextprotocol/inspector cli `
+  --transport stdio `
+  --command node `
+  --args "D:\ai_agent\Reasonix\reasonix_program\PatchWarden\dist\index.js" `
+  --method tools/list `
+  | Out-File -FilePath "D:\test-workspace\tools-list.json" -Encoding utf8
+```
+
+### 调用工具并检查响应边界
+
+```powershell
+# 调用一个 safe 工具，将响应保存后检查字节数
+npx @modelcontextprotocol/inspector cli `
+  --transport stdio `
+  --command node `
+  --args "D:\ai_agent\Reasonix\reasonix_program\PatchWarden\dist\index.js" `
+  --method tools/call `
+  --params '{\"name\":\"get_safe_audit\",\"arguments\":{}}' `
+  | Out-File -FilePath "D:\test-workspace\safe-audit.json" -Encoding utf8
+
+# 检查响应字节数是否在有界范围内
+(Get-Item "D:\test-workspace\safe-audit.json").Length
+```
+
+## 常见验证清单
+
+测试 PatchWarden 时建议覆盖以下项：
+
+- [ ] `tools/list` 返回的均为 safe-first 工具。
+- [ ] `run_safe_task` 返回的 `safe_result` 字节数在 `maxBytes` 范围内。
+- [ ] 调用涉及敏感文件名的工具时被阻断（如尝试读取 `.env`）。
+- [ ] 越出 workspace 的路径请求被拒绝。
+- [ ] 未在 `allowedCommands` 中的命令被拒绝执行。
+- [ ] `export_task_evidence_pack` 产出 8 个有界文件。
+- [ ] evidence 文件中不含 token、cookie、secret 明文。
+
+## 注意事项
+
+- Inspector 是调试工具，不应作为生产客户端长期运行。
+- 调试时使用独立测试 workspace，不要在生产仓库上执行破坏性任务。
+- 若 Inspector 报告连接失败，先确认 PatchWarden 的 dist 产物已构建。
+- safe 输出的有界范围由 `.patchwarden/config.json` 中的 `safeResult.maxBytes` 控制，
+  调试时可适当调小以验证边界行为。
+
+## 相关文档
+
+- `docs/threat-model.md`：PatchWarden 安全契约与敏感文件清单。
+- `docs/evidence-pack-schema.md`：Evidence Pack v2 文件结构。
+- `docs/dashboard-overview.md`：Control Center 与 safe-first 概念。
+- 上游草稿 PR：https://github.com/modelcontextprotocol/inspector/pull/1635