iterate-plugin 2.7.0 → 2.7.2

package/README.md

@@ -1,79 +1,92 @@
 # iterate-plugin for DeepSeek Harness (dsh)
 
-> **开发与评审在 [iterate-skill 主仓库](https://github.com/jingzhao-l/iterate-skill) 完成**：插件代码由主仓库统一维护，通过 `git subtree` 同步到本仓库；**版本发版与 npm 发布在本仓库（插件仓库）进行**，作为 dsh 生态的正式发布位。欢迎 **star / fork 主仓库** 并在 [主仓库 Issues](https://github.com/jingzhao-l/iterate-skill/issues) 反馈问题。
+<p align="center">
+  <a href="README.md"><strong>English</strong></a> ·
+  <a href="README.zh-CN.md"><strong>简体中文</strong></a>
+</p>
 
-`iterate-plugin` 是 [iterate](https://github.com/jingzhao-l/iterate-skill) 技能的 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件，提供**自治闭环代码迭代**和 **dry-run 纯多轮审查**能力。除 13 个纯函数工具外，还内置一套**免构建的 Web UI 层**（分诊面板、收敛看板、统计卡片、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。
+> **Developed and reviewed in the [iterate-skill monorepo](https://github.com/jingzhao-l/iterate-skill)**: the plugin code is maintained in the main repository and synced here via `git subtree`; **releases and npm publishing happen in this (plugin) repository**, which is the canonical publish point for the dsh ecosystem. Please **star / fork the main repository** and file issues at the [main repository Issues](https://github.com/jingzhao-l/iterate-skill/issues).
 
-## 特性
+## About This Plugin
 
-### 两种运行模式
+**iterate** is an open-source project that gives AI coding assistants the ability to review and fix code in multi-round autonomous loops. It targets a concrete pain point:
 
-| 功能 | dry-run 模式 | normal 模式 |
-|------|-------------|------------|
-| 多轮收敛反复审查 | ✅ | ✅ |
-| 并行维度评审 | ✅ | ✅ |
-| 确定性聚合去重/排序 | ✅ | ✅ |
-| meta-review 报告一致性审计 | ✅ | ✅ |
-| 零文件修改（只读） | ✅ | ❌ |
-| 原子问题自动修复 | ❌ | ✅ |
-| 每轮修复后验证 | ❌ | ✅ |
-| 修复失败回滚 | ❌ | ✅ |
-| 达标自停 | ✅ | ✅ |
-| 只修改 atomic 问题，保留 architectural 留待后续 | ❌ | ✅ |
-| 断点保存 / 恢复（长迭代续跑） | ✅ | ✅ |
+> AI assistants tend to "talk a lot but do little": a single conversation only touches a few lines, stops caring about the rest of the repo after seeing one file, and rarely double-checks what they broke. iterate automates these closing chores — itemized review, per-dimension triage, fix, validate, and iterate again — so AI actually finishes changes and gets them right.
 
-### 工具层
+`iterate-plugin` is the [iterate](https://github.com/jingzhao-l/iterate-skill) integration for the [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) desktop client. It brings iterate's review loop (review → triage → fix → validate → converge) directly into the dsh UI, offering **autonomous closed-loop code iteration** (normal mode) and **dry-run read-only multi-round review**.
 
-- **13 个注册工具**：`iterate_config` / `iterate_validate` / `iterate_decision_log` / `iterate_context` / `iterate_review` / `iterate_triage` / `iterate_fix` / `iterate_diff` / `iterate_rollback` / `iterate_checkpoint` / `iterate_status` / `iterate_history` / `iterate_prune`
-- **findings 分诊闭环**：审查 → UI 分诊（y/n/a）→ `iterate_triage` 写回 `known_intentional` → 下一轮自动过滤
-- **结构化修复系统**：每次修复先备份、写注册表、记录 diff，验证失败可 `iterate_rollback` 还原
-- **断点续跑**：长迭代在每轮开头保存 checkpoint，中断后可恢复进度
-- **历史审计**：`iterate_history` 读取决策日志（按类型/时间/数量过滤）与修复注册表汇总，审查运行过程与修复明细
-- **运行时清理**：`iterate_prune` 清理过期的决策日志条目、陈旧断点、孤儿修复备份与空轮次；默认 dry-run 只报告不删除，显式 `dryRun:false` 才真正清理，每次清理写入决策日志
-- **配置读写**：`iterate_config` 支持带校验、备份、回滚的局部写入
+Besides 13 pure-function tools, it ships a **build-free Web UI layer** (triage panel, convergence dashboard, stats card, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem (skill / headless engine) — zero migration cost.
 
-### UI 层（客户端免构建槽位）
+## Features
 
-| UI 组件 | 挂载槽位 | 功能 |
-|---------|---------|------|
-| 收敛看板 `ConvergenceDashboard` | `conversation.input.dock` | 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图，normal 模式另显示修复计数徽章 |
-| Findings 分诊面板 `TriagePanel` | `conversation.chat.turnTail` | 逐条 y/n/a 判定，支持筛选、批量（含一键全选所有 findings）、键盘快捷键、localStorage 持久化、复制 YAML/应用指令 |
-| 收敛统计卡片 `StatsCard` | `conversation.chat.turnTail` | 无 findings 时显示收敛统计、历史轮次表、趋势图、完成摘要 |
-| iterate 主题皮肤 | `theme.overrideTokens` | 暖琥珀配色的 13 个 dsw token 覆盖，明暗双模式，可在设置页开关 |
-| 进度胶囊 `ProgressCapsule` | `shell.overlay` | 每轮完成/收敛时右下角弹出通知（含收敛确认） |
-| iterate 设置区 `SettingsPanel` | `settings.section` | 主题开关、分诊持久化说明、配置管理指引、运行时状态概览（产物布局 + 查看/清理工具指引）、一键清空分诊数据 |
+### Two modes
 
-UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自动降级，不会崩溃客户端。
+| Capability | dry-run | normal |
+| --- | --- | --- |
+| Repeated review until convergence | ✅ | ✅ |
+| Parallel dimension review | ✅ | ✅ |
+| Deterministic aggregation / dedupe / sort | ✅ | ✅ |
+| meta-review report consistency audit | ✅ | ✅ |
+| Zero file modification (read-only) | ✅ | ❌ |
+| Automatic atomic fix | ❌ | ✅ |
+| Validation after each round's fixes | ❌ | ✅ |
+| Rollback on failed fixes | ❌ | ✅ |
+| Self-stop when converged | ✅ | ✅ |
+| Fix atomic findings only, keep architectural for later | ❌ | ✅ |
+| Breakpoint save / resume (long iterations) | ✅ | ✅ |
 
-## 安装
+### Tool layer
 
-### 从 npm 安装
+- **13 registered tools**: `iterate_config` / `iterate_validate` / `iterate_decision_log` / `iterate_context` / `iterate_review` / `iterate_triage` / `iterate_fix` / `iterate_diff` / `iterate_rollback` / `iterate_checkpoint` / `iterate_status` / `iterate_history` / `iterate_prune`
+- **Findings triage loop**: review → UI triage (y/n/a) → `iterate_triage` writes back `known_intentional` → auto-filtered next round
+- **Structured fix system**: each fix backs up first, writes a registry entry, records the diff; a failed validation can be reverted with `iterate_rollback`
+- **Breakpoint resume**: checkpoints saved at the start of each round; interrupted long iterations can resume
+- **History audit**: `iterate_history` reads the decision log (filtered by type / time / count) and the fix registry summary to audit run process and fix details
+- **Runtime cleanup**: `iterate_prune` removes stale decision-log entries, stale checkpoints, orphaned fix backups and empty rounds; dry-run by default (report-only), real cleanup requires `dryRun:false`, and every cleanup is logged
+- **Config read / write**: `iterate_config` supports validated, backed-up, rollback-capable partial writes
+
+### UI layer (build-free client slots)
+
+| UI component | Mounted slot | Function |
+| --- | --- | --- |
+| ConvergenceDashboard | `conversation.input.dock` | Live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges |
+| TriagePanel | `conversation.chat.turnTail` | Per-finding y/n/a triage, filtering, batch (incl. select-all), keyboard shortcuts, localStorage persistence, copy-YAML / apply-instruction |
+| StatsCard | `conversation.chat.turnTail` | When no findings remain: convergence stats, round history table, trend chart, completion summary |
+| iterate theme skin | `theme.overrideTokens` | Warm-amber 13-dsw-token override, light/dark modes, togglable in settings |
+| ProgressCapsule | `shell.overlay` | Popup notification on each round completion / convergence (incl. convergence confirm) |
+| SettingsPanel | `settings.section` | Theme toggle, triage-persistence notes, config-management guide, runtime status overview (artifact layout + view/cleanup tool guide), one-click triage data reset |
+
+The UI layer is **defensive by design**: it degrades gracefully if any of `slots` / `theme` / `React` is unavailable — it never crashes the client.
+
+## Installation
+
+### From npm
 
 ```bash
 dsh plugin --profile web add iterate-plugin
-# 或
+# or
 pnpm add iterate-plugin
 ```
 
-### 从 GitHub 安装（dsh 生态第三方安装方式）
+### From GitHub (dsh ecosystem third-party install)
 
-dsh 官方支持从 GitHub 插件仓库直接安装：`dsh plugin --profile web add "github:owner/repo#ref"`（仓库根即插件，声明 `dsh.bundle` 后自动启用）。本插件在 [iterate-plugin 独立仓库](https://github.com/jingzhao-l/iterate-plugin) 维护仓库根即插件的发布位，由主仓库通过 `git subtree` 同步，内容与 npm 包一致：
+dsh officially supports installing plugins directly from a GitHub repo: `dsh plugin --profile web add "github:owner/repo#ref"` (repo root is the plugin, auto-enabled once `dsh.bundle` is declared). This plugin's standalone [iterate-plugin repository](https://github.com/jingzhao-l/iterate-plugin) has the repo-root-is-plugin publish point, synced from the main repo via `git subtree`, content identical to the npm package:
 
 ```bash
 dsh plugin --profile web add "github:jingzhao-l/iterate-plugin#main"
 ```
 
-安装完成后需重启 dsh 服务（建议 `dsh web --patch`）并刷新页面，宿主与客户端 UI 层才会加载。
+After installation, restart the dsh service (recommended `dsh web --patch`) and refresh the page so both the host and the client UI layer load.
 
-### 本地开发 / 源码挂载
+### Local development / source mount
 
 ```bash
 dsh plugin --profile web add /path/to/iterate-skill/harness/iterate-plugin
-# 或
+# or
 pnpm add /path/to/iterate-skill/harness/iterate-plugin
 ```
 
-然后在你的 profile `cordis.patch.yml` 添加：
+Then add to your profile `cordis.patch.yml`:
 
 ```yaml
 - insert:
@@ -81,120 +94,120 @@ pnpm add /path/to/iterate-skill/harness/iterate-plugin
     name: 'iterate-plugin'
 ```
 
-> 插件包自带 `dsh.bundle.patch`（即 `cordis.patch.yml`），npm 包内 `files` 已白名单化（`src` / `lib` / `cordis.patch.yml` / `README.md` / `LICENSE`）。
+> The package carries its own `dsh.bundle.patch` (i.e. `cordis.patch.yml`); the npm package's `files` whitelist is `src` / `lib` / `dist` / `cordis.patch.yml` / `README.md` / `LICENSE`. `dist/` is the compiled output of the TypeScript server-side logic, shipped with the package so it works with dsh's `github:owner/repo#ref` git-clone install (Node does not strip TS types under `node_modules`).
 
-## 使用
+## Usage
 
-### dry-run 模式（纯反复审查，不修改文件）
+### dry-run mode (read-only review, no file changes)
 
-当你想要 "只是反复审查，不修改文件"，prompt 示例：
+When you want "just review repeatedly, modify nothing", an example prompt:
 
 ```
 dry-run review this project, find all issues across all dimensions
 ```
 
-插件会自动触发 iterate 工作流：
+The plugin auto-triggers the iterate workflow:
 
-1. `plan` → 读取配置，生成评审计划
-2. `loop` → 每轮并行评审，只找新问题 → 确定性聚合去重 → 统计收敛 → 无新问题则停止
-3. `meta-review` → 审计报告一致性
-4. `report` → 输出最终结果
+1. `plan` → read config, generate the review plan
+2. `loop` → review dimensions in parallel each round, only new findings → deterministic aggregation / dedupe → convergence stats → stop when no new findings
+3. `meta-review` → audit report consistency
+4. `report` → output final result
 
-### normal 模式（自治闭环迭代）
+### normal mode (autonomous closed-loop iteration)
 
-当你想要 "iterate this project / fix the issues found"，prompt 示例：
+When you want "iterate this project / fix the issues found", an example prompt:
 
 ```
 iterate on this project, fix all atomic issues
 ```
 
-工作流：
+Workflow:
 
-1. `plan` → 读取配置
-2. `loop` → 并行评审 → 聚合去重 → 原子问题并行修复 → 执行验证命令 → 验证失败则回滚 → 记录日志 → 无新问题则停止
-3. `report` → 输出修复统计
+1. `plan` → read config
+2. `loop` → parallel review → aggregate / dedupe → parallel atomic fixes → run validation commands → rollback on failure → log → stop when no new findings
+3. `report` → output fix statistics
 
-## 项目配置
+## Project configuration
 
-在项目根目录放 `iterate.config.yaml`：
+Put `iterate.config.yaml` at the project root:
 
 ```yaml
-# 评审目标（例如 "提高代码质量，修复潜在bug，改善可维护性"）
+# Review goal (e.g. "Improve code quality of the project")
 goal: "Improve code quality of the project"
-# 评审维度（从本插件预定义维度选或自定义）
+# Review dimensions (pick from the plugin's predefined set or customize)
 dimensions:
   - correctness
   - security
   - performance
   - maintainability
   - code-style
-# 最大评审轮次
+# Max review rounds
 max_rounds: 3
-# 评审范围
+# Review scope
 review:
-  scope: full  # full = 全项目，changed-only = 只看变更文件
-# 原子修复阈值（单次修复允许改动的最大行数，超过需 force）
+  scope: full  # full = whole project, changed-only = only changed files
+# Atomic fix threshold (max lines a single fix may change; beyond requires force)
 atomic:
   max_lines: 20
-# 已知故意不修复的问题（评审会过滤掉，不再重复报告）
+# Known intentionally-unfixed issues (filtered out, never re-reported)
 personalization:
   known_intentional:
     - file: src/example.ts
       line: 42
       dimension: security
       reason: "Intentional for demonstration"
-# 验证命令（修复后自动跑，结果记入日志）
+# Validation commands (run after fixes; results logged)
 validation:
   commands:
     - npm test
     - npm run typecheck
 ```
 
-> 配置可通过 `iterate_config` 工具读取与**校验式局部写入**（自动备份，写入失败自动回滚）。
+> The config can be read and **validated-partially-written** via `iterate_config` (auto backup, auto rollback on write failure).
 
-## 注册工具（13 个）
+## Registered tools (13)
 
-| 工具 | 功能 |
-|------|------|
-| `iterate_config` | 读取 / 写入 `iterate.config.yaml`。`operation=read` 返回完整配置或指定 section；`operation=write` 做 schema 校验、备份后局部合并写入，失败自动回滚 |
-| `iterate_validate` | 运行白名单验证命令，返回结果 |
-| `iterate_decision_log` | 追加决策日志（只追加，不改旧），存储于 `.iterate/decision-log.jsonl` |
-| `iterate_context` | 读取 `SKILL.md` / `ITERATE.md` 上下文 |
-| `iterate_review` | 确定性评审引擎：`plan` 生成计划，`aggregate` 聚合去重 + 收敛统计，`meta-review` 审计报告一致性。纯计算，不触碰文件系统 |
-| `iterate_triage` | 管理 `personalization.known_intentional`：`apply` 校验、去重（file\|dimension\|line）、备份后写回配置；`list` 读回当前条目。是浏览器分诊面板写回配置的唯一通道 |
-| `iterate_fix` | 应用**一个原子修复**：校验相对路径、备份原文件、按 `atomic.max_lines` 强制原子性（可 `force` 跳过）、写入新内容、记录 FixRecord 与 `atomic_fix` 日志。normal 模式唯一合法的改文件入口 |
-| `iterate_diff` | 查看修复累积变更：指定 `file` 返回相对首个备份的 unified diff；省略则返回每个已修复文件的汇总 |
-| `iterate_rollback` | 回滚一个已应用的修复：从备份还原文件、从注册表移除该 FixRecord、追加 `revert` 日志。用于某轮验证失败后 |
-| `iterate_checkpoint` | 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`clear` 清除。长迭代可中断续跑 |
-| `iterate_status` | 汇总当前迭代状态：模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint |
-| `iterate_history` | 读取迭代历史（只读）：决策日志条目（可按 `type` / `since` / `limit` 过滤，默认取最新 50 条，上限 200 条）+ 修复注册表汇总（各轮 fixed/failed 计数）。用于审查运行过程、审计日志、盘点修复 |
-| `iterate_prune` | 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志 |
+| Tool | Function |
+| --- | --- |
+| `iterate_config` | Read / write `iterate.config.yaml`. `operation=read` returns the full config or a named section; `operation=write` schema-validates, backs up, then merges and writes — auto rollback on failure |
+| `iterate_validate` | Run a whitelisted validation command, return the result |
+| `iterate_decision_log` | Append a decision log entry (append-only, never edits old ones), stored in `.iterate/decision-log.jsonl` |
+| `iterate_context` | Read the `SKILL.md` / `ITERATE.md` context |
+| `iterate_review` | Deterministic review engine: `plan` builds the plan, `aggregate` dedupes + converges, `meta-review` audits report consistency. Pure computation, no filesystem access |
+| `iterate_triage` | Manage `personalization.known_intentional`: `apply` validates, dedupes (file\|dimension\|line), backs up and writes back to config; `list` reads back the current entries. The only channel for the browser triage panel to write back to config |
+| `iterate_fix` | Apply **one atomic fix**: validates the relative path, backs up the original file, enforces atomicity via `atomic.max_lines` (skippable with `force`), writes new content, records a FixRecord and an `atomic_fix` log. The only legal file-modifying entry in normal mode |
+| `iterate_diff` | View accumulated fix changes: with `file`, returns the unified diff against the first backup; without it, a per-fixed-file summary |
+| `iterate_rollback` | Roll back an applied fix: restore the file from backup, remove that FixRecord from the registry, append a `revert` log. Used after a failed round validation |
+| `iterate_checkpoint` | Iteration breakpoint: `save` persists progress to `.iterate/checkpoint.json`, `load` reads it back, `clear` removes it. Resumable interrupted long iterations |
+| `iterate_status` | Summarize current iteration state: mode, current/last round, fixes applied, remaining architectural, decision-log entry count, whether a checkpoint exists |
+| `iterate_history` | Read iteration history (read-only): decision-log entries (filter by `type` / `since` / `limit`, default latest 50, cap 200) + fix-registry summary (per-round fixed/failed counts). For auditing the run, tracing logs, and inventorying fixes |
+| `iterate_prune` | Clean runtime artifacts: stale decision-log entries (by `retainDays`, default 30), stale checkpoints, orphaned fix backups, empty rounds. Dry-run by default (report-only); real cleanup with `dryRun:false`, each cleanup logged |
 
-## 运行时产物布局
+## Runtime artifact layout
 
-所有运行时状态都落在项目根目录的 `.iterate/` 下（可由 `.gitignore` 排除）：
+All runtime state lives under `.iterate/` at the project root (can be excluded via `.gitignore`):
 
 ```
 .iterate/
-  decision-log.jsonl      # 追加式决策日志（plan/review/fix/revert…）
-  checkpoint.json         # 迭代断点（断点续跑）
+  decision-log.jsonl      # append-only decision log (plan/review/fix/revert…)
+  checkpoint.json         # iteration breakpoint (resume)
   fixes/
-    registry.json         # 修复注册表（FixRecord 列表，按轮次组织）
-    <fix-id>_<ts>.bak     # 每次修复前的原文件备份
+    registry.json         # fix registry (list of FixRecords, grouped by round)
+    <fix-id>_<ts>.bak     # original file backup before each fix
 ```
 
-## 设计
+## Design
 
-插件遵循 dsh "everything-is-a-plugin" 架构：
+The plugin follows dsh's "everything-is-a-plugin" architecture:
 
-- **只做两件事**：注入系统 prompt 教模型写 iterate workflow + 注册 13 个纯函数工具
-- **所有 orchestration 通过 dsh 原生 `workflow` + `agent` + `parallel` 完成**
-- **核心逻辑全部纯函数**（去重/过滤/排序/收敛/meta-audit/diff 计算/历史过滤/清理报告），可单元测试，无 I/O
-- **安全模型**：文件写入限定在解析后的项目根目录内（路径遍历防护）；写文件前必备份，失败回滚；配置写入同样备份 + 回滚；`iterate_prune` 默认 dry-run、只清理 `.iterate/` 下产物、每次清理写日志；`iterate_fix` 对 content 设字符上限、`iterate_triage` 对 entries 设数量上限，防止异常超大负载
-- **UI 免构建**：`lib/client.js` 用 `React.createElement` 树 + 注入 `<style>` 标签，全部颜色走 `--dsw-*` 令牌，缺服务自动降级
-- 遵循 iterate 原技能的设计原则：确定性收敛，可审计，最小权限
+- **Does exactly two things**: injects the system prompt teaching the model the iterate workflow + registers 13 pure-function tools
+- **All orchestration runs through dsh native `workflow` + `agent` + `parallel`**
+- **Core logic is entirely pure functions** (dedupe / filter / sort / converge / meta-audit / diff computation / history filtering / cleanup reporting) — unit-testable, no I/O
+- **Security model**: file writes confined to the resolved project root (path-traversal protection); always back up before writing, roll back on failure; config writes also back up + roll back; `iterate_prune` is dry-run by default and only clears artifacts under `.iterate/` with every cleanup logged; `iterate_fix` caps content length and `iterate_triage` caps entry count to fend off abnormal oversized payloads
+- **Build-free UI**: `lib/client.js` uses a `React.createElement` tree + injected `<style>` tags, all colors via `--dsw-*` tokens, degrading gracefully when a service is missing
+- Follows the iterate skill's design principles: deterministic convergence, auditable, least privilege
 
-## 运行测试
+## Running the tests
 
 ```bash
 cd harness/iterate-plugin
@@ -203,11 +216,11 @@ npm run typecheck
 npm test
 ```
 
-所有测试通过：
+All tests pass:
 
-- **212 个单元测试全绿**，类型检查通过
-- 覆盖：去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制、配置读写与回滚、triage 合并、diff 计算、checkpoint 校验、修复注册表、历史读取与过滤、prune 清理报告与 dry-run 语义、UI 纯函数（select-all 键、运行时状态指引）等
+- **212 unit tests green**, type-check clean
+- Coverage: dedupe, filter, sort, multi-round convergence, meta-review audit, path safety, timeout clamping, config read/write + rollback, triage merge, diff computation, checkpoint validation, fix registry, history read + filter, prune cleanup report + dry-run semantics, UI pure functions (select-all key, runtime status guide).
 
 ## License
 
-MIT
+MIT

package/README.zh-CN.md

@@ -0,0 +1,226 @@
+# iterate-plugin for DeepSeek Harness (dsh)
+
+<p align="center">
+  <a href="README.md"><strong>English</strong></a> ·
+  <a href="README.zh-CN.md"><strong>简体中文</strong></a>
+</p>
+
+> **开发与评审在 [iterate-skill 主仓库](https://github.com/jingzhao-l/iterate-skill) 完成**：插件代码由主仓库统一维护，通过 `git subtree` 同步到本仓库；**版本发版与 npm 发布在本仓库（插件仓库）进行**，作为 dsh 生态的正式发布位。欢迎 **star / fork 主仓库** 并在 [主仓库 Issues](https://github.com/jingzhao-l/iterate-skill/issues) 反馈问题。
+
+## 这是什么 / About This Plugin
+
+**iterate** 是一个让 AI 编程助手具备多轮自主代码审查与修复能力的开源项目。它解决很具体的痛点：
+
+> AI 助手往往"说得多、做得浅"：一次对话只改几行、看过一个文件就不再管全局，也很少回头复核自己改坏的东西。iterate 把这些收尾工作——逐项审查、分维度排查、修复、验证、再迭代——自动化，让 AI 真正像资深工程师一样把改动做完、做对。
+
+`iterate-plugin` 是 [iterate](https://github.com/jingzhao-l/iterate-skill) 项目在 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 桌面客户端中的落地插件。它把 iterate 的开环审查闭环（review → triage → fix → validate → 收敛）直接带进 dsh 的界面：提供**自治闭环代码迭代**（normal 模式）与 **dry-run 纯多轮审查**（只读）两种能力。
+
+除 13 个纯函数工具外，还内置一套**免构建的 Web UI 层**（分诊面板、收敛看板、统计卡片、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。配置方式（`iterate.config.yaml` 与审查维度）与迭代生态的另外两个组件（技能 / 无头引擎）完全一致，迁移零成本。
+
+## 特性
+
+### 两种运行模式
+
+| 功能 | dry-run 模式 | normal 模式 |
+|------|-------------|------------|
+| 多轮收敛反复审查 | ✅ | ✅ |
+| 并行维度评审 | ✅ | ✅ |
+| 确定性聚合去重/排序 | ✅ | ✅ |
+| meta-review 报告一致性审计 | ✅ | ✅ |
+| 零文件修改（只读） | ✅ | ❌ |
+| 原子问题自动修复 | ❌ | ✅ |
+| 每轮修复后验证 | ❌ | ✅ |
+| 修复失败回滚 | ❌ | ✅ |
+| 达标自停 | ✅ | ✅ |
+| 只修改 atomic 问题，保留 architectural 留待后续 | ❌ | ✅ |
+| 断点保存 / 恢复（长迭代续跑） | ✅ | ✅ |
+
+### 工具层
+
+- **13 个注册工具**：`iterate_config` / `iterate_validate` / `iterate_decision_log` / `iterate_context` / `iterate_review` / `iterate_triage` / `iterate_fix` / `iterate_diff` / `iterate_rollback` / `iterate_checkpoint` / `iterate_status` / `iterate_history` / `iterate_prune`
+- **findings 分诊闭环**：审查 → UI 分诊（y/n/a）→ `iterate_triage` 写回 `known_intentional` → 下一轮自动过滤
+- **结构化修复系统**：每次修复先备份、写注册表、记录 diff，验证失败可 `iterate_rollback` 还原
+- **断点续跑**：长迭代在每轮开头保存 checkpoint，中断后可恢复进度
+- **历史审计**：`iterate_history` 读取决策日志（按类型/时间/数量过滤）与修复注册表汇总，审查运行过程与修复明细
+- **运行时清理**：`iterate_prune` 清理过期的决策日志条目、陈旧断点、孤儿修复备份与空轮次；默认 dry-run 只报告不删除，显式 `dryRun:false` 才真正清理，每次清理写入决策日志
+- **配置读写**：`iterate_config` 支持带校验、备份、回滚的局部写入
+
+### UI 层（客户端免构建槽位）
+
+| UI 组件 | 挂载槽位 | 功能 |
+|---------|---------|------|
+| 收敛看板 `ConvergenceDashboard` | `conversation.input.dock` | 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图，normal 模式另显示修复计数徽章 |
+| Findings 分诊面板 `TriagePanel` | `conversation.chat.turnTail` | 逐条 y/n/a 判定，支持筛选、批量（含一键全选所有 findings）、键盘快捷键、localStorage 持久化、复制 YAML/应用指令 |
+| 收敛统计卡片 `StatsCard` | `conversation.chat.turnTail` | 无 findings 时显示收敛统计、历史轮次表、趋势图、完成摘要 |
+| iterate 主题皮肤 | `theme.overrideTokens` | 暖琥珀配色的 13 个 dsw token 覆盖，明暗双模式，可在设置页开关 |
+| 进度胶囊 `ProgressCapsule` | `shell.overlay` | 每轮完成/收敛时右下角弹出通知（含收敛确认） |
+| iterate 设置区 `SettingsPanel` | `settings.section` | 主题开关、分诊持久化说明、配置管理指引、运行时状态概览（产物布局 + 查看/清理工具指引）、一键清空分诊数据 |
+
+UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自动降级，不会崩溃客户端。
+
+## 安装
+
+### 从 npm 安装
+
+```bash
+dsh plugin --profile web add iterate-plugin
+# 或
+pnpm add iterate-plugin
+```
+
+### 从 GitHub 安装（dsh 生态第三方安装方式）
+
+dsh 官方支持从 GitHub 插件仓库直接安装：`dsh plugin --profile web add "github:owner/repo#ref"`（仓库根即插件，声明 `dsh.bundle` 后自动启用）。本插件在 [iterate-plugin 独立仓库](https://github.com/jingzhao-l/iterate-plugin) 维护仓库根即插件的发布位，由主仓库通过 `git subtree` 同步，内容与 npm 包一致：
+
+```bash
+dsh plugin --profile web add "github:jingzhao-l/iterate-plugin#main"
+```
+
+安装完成后需重启 dsh 服务（建议 `dsh web --patch`）并刷新页面，宿主与客户端 UI 层才会加载。
+
+### 本地开发 / 源码挂载
+
+```bash
+dsh plugin --profile web add /path/to/iterate-skill/harness/iterate-plugin
+# 或
+pnpm add /path/to/iterate-skill/harness/iterate-plugin
+```
+
+然后在你的 profile `cordis.patch.yml` 添加：
+
+```yaml
+- insert:
+  - id: iterate-plugin
+    name: 'iterate-plugin'
+```
+
+> 插件包自带 `dsh.bundle.patch`（即 `cordis.patch.yml`），npm 包内 `files` 已白名单化（`src` / `lib` / `dist` / `cordis.patch.yml` / `README.md` / `LICENSE`）。其中 `dist/` 为 TypeScript 服务端逻辑的编译产物，随包分发以兼容 dsh 的 `github:owner/repo#ref` git-clone 安装方式（Node 不擦除 `node_modules` 下的 TS 类型）。
+
+## 使用
+
+### dry-run 模式（纯反复审查，不修改文件）
+
+当你想要 "只是反复审查，不修改文件"，prompt 示例：
+
+```
+dry-run review this project, find all issues across all dimensions
+```
+
+插件会自动触发 iterate 工作流：
+
+1. `plan` → 读取配置，生成评审计划
+2. `loop` → 每轮并行评审，只找新问题 → 确定性聚合去重 → 统计收敛 → 无新问题则停止
+3. `meta-review` → 审计报告一致性
+4. `report` → 输出最终结果
+
+### normal 模式（自治闭环迭代）
+
+当你想要 "iterate this project / fix the issues found"，prompt 示例：
+
+```
+iterate on this project, fix all atomic issues
+```
+
+工作流：
+
+1. `plan` → 读取配置
+2. `loop` → 并行评审 → 聚合去重 → 原子问题并行修复 → 执行验证命令 → 验证失败则回滚 → 记录日志 → 无新问题则停止
+3. `report` → 输出修复统计
+
+## 项目配置
+
+在项目根目录放 `iterate.config.yaml`：
+
+```yaml
+# 评审目标（例如 "提高代码质量，修复潜在bug，改善可维护性"）
+goal: "Improve code quality of the project"
+# 评审维度（从本插件预定义维度选或自定义）
+dimensions:
+  - correctness
+  - security
+  - performance
+  - maintainability
+  - code-style
+# 最大评审轮次
+max_rounds: 3
+# 评审范围
+review:
+  scope: full  # full = 全项目，changed-only = 只看变更文件
+# 原子修复阈值（单次修复允许改动的最大行数，超过需 force）
+atomic:
+  max_lines: 20
+# 已知故意不修复的问题（评审会过滤掉，不再重复报告）
+personalization:
+  known_intentional:
+    - file: src/example.ts
+      line: 42
+      dimension: security
+      reason: "Intentional for demonstration"
+# 验证命令（修复后自动跑，结果记入日志）
+validation:
+  commands:
+    - npm test
+    - npm run typecheck
+```
+
+> 配置可通过 `iterate_config` 工具读取与**校验式局部写入**（自动备份，写入失败自动回滚）。
+
+## 注册工具（13 个）
+
+| 工具 | 功能 |
+|------|------|
+| `iterate_config` | 读取 / 写入 `iterate.config.yaml`。`operation=read` 返回完整配置或指定 section；`operation=write` 做 schema 校验、备份后局部合并写入，失败自动回滚 |
+| `iterate_validate` | 运行白名单验证命令，返回结果 |
+| `iterate_decision_log` | 追加决策日志（只追加，不改旧），存储于 `.iterate/decision-log.jsonl` |
+| `iterate_context` | 读取 `SKILL.md` / `ITERATE.md` 上下文 |
+| `iterate_review` | 确定性评审引擎：`plan` 生成计划，`aggregate` 聚合去重 + 收敛统计，`meta-review` 审计报告一致性。纯计算，不触碰文件系统 |
+| `iterate_triage` | 管理 `personalization.known_intentional`：`apply` 校验、去重（file\|dimension\|line）、备份后写回配置；`list` 读回当前条目。是浏览器分诊面板写回配置的唯一通道 |
+| `iterate_fix` | 应用**一个原子修复**：校验相对路径、备份原文件、按 `atomic.max_lines` 强制原子性（可 `force` 跳过）、写入新内容、记录 FixRecord 与 `atomic_fix` 日志。normal 模式唯一合法的改文件入口 |
+| `iterate_diff` | 查看修复累积变更：指定 `file` 返回相对首个备份的 unified diff；省略则返回每个已修复文件的汇总 |
+| `iterate_rollback` | 回滚一个已应用的修复：从备份还原文件、从注册表移除该 FixRecord、追加 `revert` 日志。用于某轮验证失败后 |
+| `iterate_checkpoint` | 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`clear` 清除。长迭代可中断续跑 |
+| `iterate_status` | 汇总当前迭代状态：模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint |
+| `iterate_history` | 读取迭代历史（只读）：决策日志条目（可按 `type` / `since` / `limit` 过滤，默认取最新 50 条，上限 200 条）+ 修复注册表汇总（各轮 fixed/failed 计数）。用于审查运行过程、审计日志、盘点修复 |
+| `iterate_prune` | 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志 |
+
+## 运行时产物布局
+
+所有运行时状态都落在项目根目录的 `.iterate/` 下（可由 `.gitignore` 排除）：
+
+```
+.iterate/
+  decision-log.jsonl      # 追加式决策日志（plan/review/fix/revert…）
+  checkpoint.json         # 迭代断点（断点续跑）
+  fixes/
+    registry.json         # 修复注册表（FixRecord 列表，按轮次组织）
+    <fix-id>_<ts>.bak     # 每次修复前的原文件备份
+```
+
+## 设计
+
+插件遵循 dsh "everything-is-a-plugin" 架构：
+
+- **只做两件事**：注入系统 prompt 教模型写 iterate workflow + 注册 13 个纯函数工具
+- **所有 orchestration 通过 dsh 原生 `workflow` + `agent` + `parallel` 完成**
+- **核心逻辑全部纯函数**（去重/过滤/排序/收敛/meta-audit/diff 计算/历史过滤/清理报告），可单元测试，无 I/O
+- **安全模型**：文件写入限定在解析后的项目根目录内（路径遍历防护）；写文件前必备份，失败回滚；配置写入同样备份 + 回滚；`iterate_prune` 默认 dry-run、只清理 `.iterate/` 下产物、每次清理写日志；`iterate_fix` 对 content 设字符上限、`iterate_triage` 对 entries 设数量上限，防止异常超大负载
+- **UI 免构建**：`lib/client.js` 用 `React.createElement` 树 + 注入 `<style>` 标签，全部颜色走 `--dsw-*` 令牌，缺服务自动降级
+- 遵循 iterate 原技能的设计原则：确定性收敛，可审计，最小权限
+
+## 运行测试
+
+```bash
+cd harness/iterate-plugin
+npm install
+npm run typecheck
+npm test
+```
+
+所有测试通过：
+
+- **212 个单元测试全绿**，类型检查通过
+- 覆盖：去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制、配置读写与回滚、triage 合并、diff 计算、checkpoint 校验、修复注册表、历史读取与过滤、prune 清理报告与 dry-run 语义、UI 纯函数（select-all 键、运行时状态指引）等
+
+## License
+
+MIT

package/dist/index.js

@@ -2,11 +2,13 @@
  * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
  *
  * Architecture:
- * - The plugin registers 6 tools (config, validate, decision-log, context, review, triage)
+ * - The plugin registers 13 tools (config, validate, decision-log, context, review,
+ *   triage, fix, diff, rollback, checkpoint, status, history, prune)
  * - The plugin injects a system prompt section teaching the iterate workflow pattern
  * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
  * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
- * - Subagents use the 6 tools to do real work (read config, run validation, log decisions, review, triage)
+ * - Subagents use the 13 tools to do real work (read config, run validation, log decisions,
+ *   review, triage, apply/rollback/fixing, checkpoint, status, history, prune)
  *
  * Tool invocation model:
  * - Workflow script CANNOT call tools directly (sandboxed vm, no Node API)
@@ -16,7 +18,7 @@
  *
  * Key files:
  * - src/index.ts      — Plugin entry: register tools + inject skill prompt
- * - src/tools/        — 6 tool implementations + meta-review/review engines
+ * - src/tools/        — 13 tool implementations + meta-review/review engines
  * - src/config-loader.ts — YAML config loading
  * - src/types.ts     — Shared types
  */
@@ -34,7 +36,7 @@ import { ITERATE_SKILL_PROMPT } from "./skill-prompt.js";
 export const name = 'iterate-plugin';
 export const inject = ['tools', 'systemPrompt'];
 export function apply(ctx) {
-    // 1. Register the 11 tools
+    // 1. Register the 13 tools
     registerConfigTool(ctx);
     registerValidateTool(ctx);
     registerDecisionLogTool(ctx);

package/dist/review.js

@@ -208,6 +208,11 @@ export function buildReviewReport(input) {
     const lastRound = filteredRounds.length > 0 ? filteredRounds[filteredRounds.length - 1].round : 0;
     const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
     const converged = filteredRounds.length > 0 && lastRoundCount === 0;
+    // Attach the normal-mode fix count to the summary (dry-run leaves it absent).
+    const computed = summarize(sorted);
+    if (input.mode === 'normal' && typeof input.fixedCount === 'number' && Number.isInteger(input.fixedCount)) {
+        computed.fixedCount = input.fixedCount;
+    }
     return {
         mode: input.mode,
         goal: input.goal,
@@ -225,7 +230,7 @@ export function buildReviewReport(input) {
                     ? 'converged'
                     : 'max_rounds_reached',
         },
-        summary: summarize(sorted),
+        summary: computed,
     };
 }
 /**