patchwarden 1.5.1 → 1.6.1

package/docs/control-center/control-center-mvp.md

@@ -1,205 +0,0 @@
-# PatchWarden Control Center MVP
-
-> 本地 Web 控制中心，统一管理 PatchWarden Core 与 PatchWarden Direct 两个 MCP profile。
-> 不合并工具，不发布到 npm，不打 git tag。
-
-## 概述
-
-Control Center 是一个绑定 `127.0.0.1:8090` 的本地 HTTP 服务，提供静态 UI 页面和一组容错 JSON API。
-所有进程生命周期操作（start/stop/restart）均委托 `scripts/control/manage-patchwarden.ps1` 执行，
-Control Center 自身不直接 kill 进程，也不读取任意 PID 文件。
-
-- **Core profile**: `chatgpt_core`，17 个工具，HTTP 端口 8080
-- **Direct profile**: `chatgpt_direct`，10 个工具，HTTP 端口 8081
-
-## 新增文件
-
-| 文件 | 说明 |
-| --- | --- |
-| `src/controlCenter.ts` | Control Center HTTP 服务主程序（TypeScript 源） |
-| `scripts/checks/control-center-smoke.js` | 测试模式冒烟测试（ESM，仅用 Node 内置模块） |
-| `scripts/control/start-control-center.ps1` | PowerShell 启动脚本（含构建检查、端口轮询、浏览器自动打开；支持 `-NoBrowser`） |
-| `PatchWarden-Control.cmd` | 根目录 CMD 入口，调用上述 PowerShell 脚本 |
-| `ui/pages/dashboard.html` | 总控首页（真实状态，7 个工具栏按钮，两张服务卡） |
-| `ui/pages/tasks.html` | 任务列表页（接 `/api/tasks`） |
-| `ui/pages/task-detail.html` | 任务详情页（接 `/api/tasks/:taskId`） |
-| `ui/pages/workspace.html` | 工作区页（接轻量 `/api/workspace`） |
-| `ui/pages/audit.html` | 审计历史页（接 `/api/audit`） |
-| `ui/partials/project-shell.html` | 页面外壳（CDN 引用已替换为本地 `/vendor/`） |
-| `ui/colors_and_type.css` | 颜色与字体样式 |
-| `ui/vendor/tailwindcss-browser.js` | Tailwind v4.3.1 browser build（本地副本，离线可用） |
-| `ui/vendor/lucide.js` | Lucide v1.8.0 UMD（本地副本，离线可用） |
-| `docs/control-center/control-center-mvp.md` | 本文档 |
-
-## 改动文件
-
-| 文件 | 改动 |
-| --- | --- |
-| `package.json` | 新增 `start:control` 脚本（`node dist/controlCenter.js`）；`files` 数组新增 `ui/`；`test` 脚本末尾追加 `&& node scripts/checks/control-center-smoke.js` |
-| `.gitignore` | 新增 `/CODE_WIKI.md`、`/PatchWarden-UI.zip`、`/patchwarden-v0.6.1-SHA256SUMS.txt`（避免 brand-check 误报） |
-
-## 启动方式
-
-### 方式一：CMD 入口（推荐用户使用）
-
-```powershell
-.\PatchWarden-Control.cmd
-```
-
-### 方式二：PowerShell 脚本
-
-```powershell
-# 正常启动（构建检查 + 打开浏览器）
-powershell -ExecutionPolicy Bypass -File scripts\control\start-control-center.ps1
-
-# 测试模式（不打开浏览器）
-powershell -ExecutionPolicy Bypass -File scripts\control\start-control-center.ps1 -NoBrowser
-```
-
-### 方式三：npm 脚本（需先 `npm run build`）
-
-```powershell
-npm.cmd run build
-npm.cmd run start:control
-```
-
-启动后自动打开 `http://127.0.0.1:8090`。
-
-端口可通过环境变量覆盖（仅用于测试）：
-
-```powershell
-$env:PATCHWARDEN_CONTROL_PORT=18090; node dist/controlCenter.js
-```
-
-## 控制 Token 校验
-
-- 服务启动时通过 `crypto.randomUUID()` 生成 token，**仅保存在内存中**，不写入任何文件。
-- 前端通过 `GET /control-token.json` 从内存获取 token，响应头 `Cache-Control: no-store`。
-- **所有 POST 接口**（含 `/api/start-all`、`/api/stop-all`、`/api/restart-all`、`/api/core/*`、`/api/direct/*`、`/api/open-logs-folder`）必须携带 `X-PatchWarden-Control-Token` 请求头。
-- token 缺失或错误时返回 `403`，不执行任何进程控制或本地系统动作。
-- GET 接口（status、tasks、logs 等）不需要 token。
-- `git status --porcelain` 不会出现 `ui/control-token.json`。
-
-## API 清单
-
-### GET 接口（免 token）
-
-| 路径 | 说明 |
-| --- | --- |
-| `GET /` | 返回 `ui/pages/dashboard.html` |
-| `GET /control-token.json` | 从内存返回控制 token，`Cache-Control: no-store` |
-| `GET /colors_and_type.css` | 静态 CSS |
-| `GET /pages/*` | 静态 HTML 页面 |
-| `GET /partials/*` | 静态 HTML 片段 |
-| `GET /vendor/*` | 本地化的 Tailwind / Lucide |
-| `GET /api/status` | 聚合状态（容错，永不 500） |
-| `GET /api/tasks` | 任务列表（复用 `listTasks`） |
-| `GET /api/tasks/:taskId` | 任务详情（status/runtime/result/audit/diff_patch/test_log） |
-| `GET /api/logs/core` | Core runtime 日志尾部 100 行（脱敏） |
-| `GET /api/logs/direct` | Direct runtime 日志尾部 100 行（脱敏） |
-| `GET /api/logs/watcher` | Watcher 日志尾部 100 行（脱敏） |
-| `GET /api/workspace` | 轻量工作区信息（workspace_root、directories、agents、config 摘要；**不做 git 扫描**） |
-| `GET /api/audit` | 审计历史（扫描 tasks 目录下含 audit.json 的任务，最多 50 条） |
-| `GET /api/tunnel-ui-url` | 读取 Core/Direct 的 tunnel-health-url.txt |
-
-### POST 接口（必须校验 token）
-
-| 路径 | 委托命令 | 说明 |
-| --- | --- | --- |
-| `POST /api/start-all` | `manage-patchwarden.ps1 start all` | 启动全部 |
-| `POST /api/stop-all` | `manage-patchwarden.ps1 stop all` | 停止全部 |
-| `POST /api/restart-all` | `manage-patchwarden.ps1 restart all` | 重启全部 |
-| `POST /api/core/start` | `manage-patchwarden.ps1 start core` | 启动 Core |
-| `POST /api/core/stop` | `manage-patchwarden.ps1 stop core` | 停止 Core |
-| `POST /api/direct/start` | `manage-patchwarden.ps1 start direct` | 启动 Direct |
-| `POST /api/direct/stop` | `manage-patchwarden.ps1 stop direct` | 停止 Direct |
-| `POST /api/open-logs-folder` | 系统命令打开 runtime 目录 | 打开日志文件夹 |
-
-### `/api/status` 返回结构（容错）
-
-```json
-{
-  "core": { "available": false, "reason": "...", "healthz": null, "readyz": null },
-  "direct": { "available": false, "reason": "...", "healthz": null, "readyz": null },
-  "watcher": { "status": "missing|healthy|stale|unreadable", "available": false, "reason": "..." },
-  "tunnel": { "core": { "observed": false }, "direct": { "observed": false } },
-  "tools": {
-    "core": { "tool_profile": null, "tool_count": null, "schema_epoch": null, "tool_manifest_sha256": null, "tool_names": null },
-    "direct": { "tool_profile": null, "tool_count": null, "schema_epoch": null, "tool_manifest_sha256": null, "tool_names": null }
-  },
-  "agents": [],
-  "workspace_root": "string | null",
-  "tasks": { "tasks": [], "total": 0, "active": 0, "stale": 0, "reason": null }
-}
-```
-
-容错保证：
-- core/direct health 探测失败 → `{ available: false, reason: "..." }`，接口仍 200
-- runtime 文件（tunnel-status.json、tool-manifest.json）缺失 → 返回 null 或 `{ observed: false }`，接口仍 200
-- 日志文件缺失 → `{ stdout: "", stderr: "", reason: "..." }`，接口仍 200
-- tasks 目录缺失 → `{ tasks: [], total: 0, reason: "..." }`，接口仍 200
-- Core/Direct 未启动时 `/api/status` 仍返回 200 JSON，不报 500
-
-## 进程安全
-
-- Control Center **不直接 kill 进程**，所有 start/stop/restart 均委托 `scripts/control/manage-patchwarden.ps1`。
-- `manage-patchwarden.ps1` 的 `Test-TunnelProcessForMode` 在 stop/restart 前校验进程命令行属于 `tunnel-client.exe --profile` 模式，仅停止匹配的进程。
-- **不根据任意 PID 文件 kill 进程**。
-- Control Center 仅在自身服务关闭时退出自己启动的 HTTP server。
-
-## CDN 本地化
-
-- 所有 HTML 无 `https://cdn` 或 `https://unpkg` 引用。
-- `ui/vendor/tailwindcss-browser.js`（Tailwind v4.3.1）和 `ui/vendor/lucide.js`（Lucide v1.8.0）为本地副本。
-- 断网后页面样式和图标正常渲染。
-
-## 冒烟测试（测试模式）
-
-`scripts/checks/control-center-smoke.js` 严格遵循测试模式：
-
-- 不打开浏览器
-- 不真正 start/stop Core 或 Direct
-- 不 kill 任何进程（仅关闭自己 spawn 的 controlCenter 子进程）
-- 使用测试端口 `18090`（通过 `PATCHWARDEN_CONTROL_PORT`），避免 8090 冲突
-- 测试结束关闭 server，释放端口
-
-测试覆盖（10 项）：
-
-1. 静态文件服务（`/`、`/vendor/*`、`/colors_and_type.css` 返回 200 + 正确 Content-Type）
-2. `/api/status` 返回有效 JSON 且容错（core/direct 未启动时仍 200）
-3. `/api/tasks` 返回有效 JSON
-4. `/control-token.json` 返回 token + `Cache-Control: no-store`
-5. POST `/api/start-all` 不带 token → 403
-6. POST `/api/start-all` 带错误 token → 403
-7. POST `/api/open-logs-folder` 不带 token → 403
-8. token 不污染 Git（`git status --porcelain` 不含 `ui/control-token.json`）
-9. 无 CDN 引用（HTML 文件无 `https://cdn` / `https://unpkg`）
-10. 其他 GET API 可达（`/api/workspace`、`/api/audit`、`/api/logs/core`、`/api/tunnel-ui-url`）
-
-## 测试结果
-
-`npm test` 全量通过（`FINAL_EXIT_CODE: 0`）：
-
-| 测试链 | 结果 |
-| --- | --- |
-| smoke-test | OK |
-| unit-tests | 139 total（136 pass，0 fail，1 skipped） |
-| lifecycle-smoke | 22 passed, 0 failed |
-| doctor-smoke | OK |
-| tunnel-supervisor-smoke | OK |
-| watcher-supervisor-smoke | OK |
-| control-smoke | OK |
-| mcp-manifest-check | 17 tools, chatgpt_core profile |
-| brand-check | OK: 144 tracked files checked |
-| control-center-smoke | 10 passed, 0 failed |
-
-未发布 npm、未打 git tag、未上传 npm。
-
-## 已知限制
-
-1. **`/api/workspace` 轻量版**：第一版只返回 workspace_root、项目列表（一级子目录）、agents、config 摘要。不做 git 扫描，不返回 repo clean 状态。workspace.html 中 "Repo Clean 状态" 显示为"按需接口待实现"占位。
-2. **task-detail / workspace / audit 为基础接入**：能加载数据并渲染，但未实现全部高级功能（如 diff 高亮、审计证据深度展示）。diff/test-log 仅做文本预览。
-3. **进程控制仅支持 Windows**：`manage-patchwarden.ps1` 为 PowerShell 脚本，POST 控制接口在非 Windows 环境下不可用。`/api/open-logs-folder` 在 macOS/Linux 下会尝试 `open`/`xdg-open`。
-4. **Health 探测端口固定**：Core 探测 `127.0.0.1:8080`，Direct 探测 `127.0.0.1:8081`，暂不支持配置覆盖。
-5. **Control token 生命周期**：token 在服务进程内存中，服务重启后 token 会变化（前端通过 `/control-token.json` 重新获取）。
-6. **日志读取**：仅返回各日志文件尾部 100 行，并对敏感内容脱敏（复用 `redactSensitiveContent`）。

package/docs/control-center/control-center-phase2.md

@@ -1,159 +0,0 @@
-# PatchWarden Control Center Phase 2
-
-> v0.6.3 在 v0.6.2 MVP 基础上增强任务、工作区、Direct session 和日志体验。
-> 不重构架构，不合并 Core/Direct MCP，不改现有 MCP 工具注册逻辑。
-> 不发布 npm，不打 git tag。
-
-## 概述
-
-Phase 2 完全在 Control Center HTTP 层增强，未触动 MCP 工具注册、watcher 核心循环或
-Direct session 写入逻辑。新增的 API 全部沿用既有 token 校验、路径围栏和脱敏机制。
-
-- **Stale Task 管理**：4 条规则识别僵死任务，reconcile 只标注不删除
-- **task-detail 增强**：变更文件、验证摘要、警告/错误、stale 横幅 + 4 个动作按钮
-- **工作区按需 git 状态**：仅在用户点击时对单个 repo 执行 `git status --short`
-- **Direct Sessions 页面**：浏览 `.patchwarden/direct-sessions` 下的会话产物
-- **Logs 页面**：core/direct/watcher/control-center 四类日志，支持 tail 100/300/1000
-
-## 启动方式
-
-启动方式与 MVP 完全一致，无新增入口：
-
-```powershell
-.\PatchWarden-Control.cmd
-# 或
-npm.cmd run build
-npm.cmd run start:control
-```
-
-启动后访问 `http://127.0.0.1:8090`，左侧导航新增「Direct 会话」和「日志」两项。
-
-## 改动文件
-
-| 文件 | 改动 |
-| --- | --- |
-| `src/version.ts` | `PATCHWARDEN_VERSION` 0.6.2 → 0.6.3 |
-| `package.json` | `version` 0.6.2 → 0.6.3 |
-| `src/controlCenter.ts` | 新增 stale/reconcile/task-detail 增强/workspace repo status/direct sessions/logs 分类等 API |
-| `ui/pages/dashboard.html` | 侧边栏新增 Direct 会话 + 日志导航 |
-| `ui/pages/tasks.html` | 侧边栏新增 Direct 会话 + 日志导航 |
-| `ui/pages/task-detail.html` | 新增变更文件卡、验证摘要卡、警告/错误卡、stale 横幅、Refresh/Copy task_id/Open folder/Run audit/Reconcile 按钮 |
-| `ui/pages/workspace.html` | 每个 repo 新增「检查」按钮，按需调用 `/api/workspace/:repo/status`，渲染 git 状态面板 |
-| `ui/pages/audit.html` | 侧边栏新增 Direct 会话 + 日志导航 |
-| `ui/pages/direct-sessions.html` | 新页面：会话列表 + 会话详情（summary.md / audit.md / audit.json / diff.patch / changed-files.json） |
-| `ui/pages/logs.html` | 新页面：分类选择 + tail 选择 + 自动刷新开关 |
-| `scripts/checks/control-center-smoke.js` | 新增 Test 11–15 覆盖 Phase 2 API |
-| `docs/control-center/control-center-phase2.md` | 本文档 |
-
-## 新增 API
-
-### GET 接口（免 token）
-
-| 路径 | 说明 |
-| --- | --- |
-| `GET /api/tasks/stale` | 返回当前判定为 stale 的任务列表（含 stale_reasons） |
-| `GET /api/tasks/:taskId` | 增强详情：新增 `changed_files`、`file_stats`、`verification_summary`、`warnings`、`errors`、`stale`、`reconcile`、`task_dir`、`independent_review`、`verify_log` |
-| `GET /api/workspace/:repo/status` | 对单个 repo 执行 `git status --short`，返回 changed_files_count/untracked_count/modified_count/is_clean/short_status |
-| `GET /api/direct-sessions` | 列出 `.patchwarden/direct-sessions` 下所有会话摘要 |
-| `GET /api/direct-sessions/:sessionId` | 返回会话详情：summary/session/summary_md/diff_patch/audit_json/audit_md/changed_files |
-| `GET /api/logs/:category?tail=<100\|300\|1000>` | 四类日志（core/direct/watcher/control-center），支持 tail 行数 |
-
-### POST 接口（必须校验 token）
-
-| 路径 | 说明 |
-| --- | --- |
-| `POST /api/tasks/:taskId/reconcile` | 标注 stale/archived，写入 `reconcile.json`，不删除任务 |
-| `POST /api/tasks/:taskId/audit` | 仅当任务处于终态时委托 `auditTask` 运行独立审计 |
-| `POST /api/tasks/:taskId/open-folder` | 通过系统命令打开任务目录 |
-
-## Stale Task 判定规则
-
-`classifyStaleTask` 仅对 `pending` / `running` 状态任务判定（终态任务直接返回非 stale）。
-判定使用 `config.watcherStaleSeconds` 作为阈值，4 条规则任一命中即标记 stale：
-
-| 规则 | 字段值 | 说明 |
-| --- | --- | --- |
-| `heartbeat_stale` | status=running 且 last_heartbeat_at 超过阈值 | 运行中但心跳长时间未更新 |
-| `collecting_artifacts_stale` | phase=collecting_artifacts 且心跳超过阈值 | 卡在产物收集阶段 |
-| `running_no_command_watcher_healthy` | status=running 且 current_command 为空且 watcher healthy | 运行中无命令但 watcher 在工作，疑似僵死 |
-| `heartbeat_far_behind_watcher` | 任务心跳比 watcher 心跳早 2× 阈值以上且 watcher healthy | 任务明显落后于 watcher |
-
-`/api/status` 和 `/api/tasks` 返回的任务对象均带 `is_stale: boolean` 和
-`stale_reasons: string[]`。`/api/status.tasks` 还聚合了 `stale` 计数和
-`stale_task_ids` 列表。
-
-## Reconcile 行为
-
-`POST /api/tasks/:taskId/reconcile` 的安全契约：
-
-- **不删除任务**，不修改 `status` 枚举值
-- 读取 `status.json` / `runtime.json` 重建 `TaskEntry`，重新调用 `classifyStaleTask`
-- 决策（`decision` 字段）：
-  - `marked_archived`：任务已处于终态 → 标注归档
-  - `marked_stale`：stale 且 watcher 未在驱动（无 current_command 或 watcher 非 healthy）→ 标注僵死
-  - `no_action`：不满足上述条件 → 仅记录，不标注
-- 写入 `tasks/<taskId>/reconcile.json`（完整决策记录）
-- 仅当 `safe=true` 时，在 `status.json` 追加 `reconcile_state`（`"stale"` 或 `"archived"`）和 `reconciled_at`，**原 status 字段保持不变**
-- 返回 reconcile 记录 JSON
-
-## 路径围栏（workspace repo status）
-
-`GET /api/workspace/:repo/status` 的安全约束：
-
-- `repo` 参数经 `decodeURIComponent` 后若包含 `..` 或 `\0` → 直接 400
-- 通过 `guardWorkspacePath(repo, workspaceRoot)` 解析为绝对路径，任何逃逸 `workspaceRoot` 的路径 → 400
-- 仅对解析后的目录执行 `git status --short`，超时 8 秒，maxBuffer 1MB
-- 非 git 仓库或 git 不可用时返回 200 + `is_git_repo: false` + error 字段，不返回 500
-- smoke test 用 `encodeURIComponent("../secret")` 验证穿越被拒（400）
-
-## Direct Sessions 数据来源
-
-- 会话目录：`getDirectSessionsDir(config)` → `<runtime>/.patchwarden/direct-sessions/`
-- 每个会话子目录读取：`session.json`、`summary.json`、`audit.json`、`summary.md`、`diff.patch`、`audit.md`、`changed-files.json`
-- `DirectSessionSummary` 字段：`session_id`、`repo_path`、`resolved_repo_path`、`created_at`、`expires_at`、`finalized`、`finalized_at`、`audited`、`changed_files_total`、`verification_summary`、`audit_decision`、`audit_checked_at`、`title`
-- 目录不存在时返回 `{ sessions: [], total: 0, reason: null }`，**不返回 500**
-- 会话按 `created_at` 降序排列
-
-## 日志脱敏
-
-- 所有 `/api/logs/:category` 响应均经 `redactSensitiveContent` 脱敏
-- tail 行数限制在 `ALLOWED_LOG_TAILS = {100, 300, 1000}`，非法值回退到 100
-- 日志文件缺失时返回 `{ stdout: "", stderr: "", reason: "log file not found" }`
-
-## 冒烟测试
-
-`scripts/checks/control-center-smoke.js` 在原 10 项基础上新增 5 项（共 16 项）：
-
-| # | 测试 |
-| --- | --- |
-| 11 | `GET /api/tasks/stale` 返回有效 JSON（`stale_tasks` 数组、`total` 数字、`stale_threshold_seconds` 数字） |
-| 12 | `GET /api/workspace/<traversal>/status` 被拒绝（400，error 含 "traversal"） |
-| 13 | `POST /api/tasks/:taskId/reconcile` 无 token → 403 |
-| 14 | `GET /api/direct-sessions` 目录缺失时返回空列表（200，非 500） |
-| 15 | `GET /api/logs/core?tail=300` 响应包含 `tail: 300` |
-
-## 测试结果
-
-```
-npm.cmd run build         # tsc 编译通过
-node scripts/checks/control-center-smoke.js
-  # Summary: 16 passed, 0 failed
-```
-
-全量 `npm test` 链路（security 139 + unit 136 + lifecycle 22 + control-center 16）
-全部通过，0 失败。
-
-> 注：在 TRAE IDE 沙盒内运行 `npm test` 时，control-center-smoke spawn 的子进程退出
-> 后 Windows 会尝试更新 jump list 临时文件，被沙盒拒绝并打印
-> "TRAE Sandbox Error: hit restricted …CustomDestinations…"。该错误与测试逻辑无关，
-> 所有测试用例均报告 PASS。直接运行 `node scripts/checks/control-center-smoke.js` 退出码为 0。
-
-## 已知限制
-
-- `/api/workspace/:repo/status` 仅运行 `git status --short`，不返回 diff 或 stash 信息
-- reconcile 不会清理任务文件，需人工后续处理或由 watcher 在下个周期自然覆盖
-- `/api/tasks/:taskId/audit` 仅在任务处于终态（done/failed/failed_verification/
-  failed_scope_violation/failed_policy_violation/canceled/timeout）时才执行，否则返回 409
-- Direct Sessions 页面只读，不提供 finalize 或 audit 触发入口（这些操作仍需通过 MCP 工具完成）
-- Logs 页面的自动刷新间隔固定为 5 秒，不读取 watcher 实时事件
-- task-detail 的「Open task folder」按钮通过 `explorer.exe` / `open` / `xdg-open` 打开，需要本地图形环境