iterate-plugin 2.5.0 → 2.6.0

package/README.md

@@ -2,10 +2,12 @@
 
 > **开发与评审在 [iterate-skill 主仓库](https://github.com/jingzhao-l/iterate-skill) 完成**：插件代码由主仓库统一维护，通过 `git subtree` 同步到本仓库；**版本发版与 npm 发布在本仓库（插件仓库）进行**，作为 dsh 生态的正式发布位。欢迎 **star / fork 主仓库** 并在 [主仓库 Issues](https://github.com/jingzhao-l/iterate-skill/issues) 反馈问题。
 
-`iterate-plugin` 是 [iterate](https://github.com/iterate-skill/iterate-skill) 技能的 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件，提供**自治闭环代码迭代**和**dry-run 纯多轮审查**能力。
+`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 槽位上。
 
 ## 特性
 
+### 两种运行模式
+
 | 功能 | dry-run 模式 | normal 模式 |
 |------|-------------|------------|
 | 多轮收敛反复审查 | ✅ | ✅ |
@@ -15,12 +17,37 @@
 | 零文件修改（只读） | ✅ | ❌ |
 | 原子问题自动修复 | ❌ | ✅ |
 | 每轮修复后验证 | ❌ | ✅ |
+| 修复失败回滚 | ❌ | ✅ |
 | 达标自停 | ✅ | ✅ |
 | 只修改 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 安装（发布后）
+### 从 npm 安装
 
 ```bash
 dsh plugin --profile web add iterate-plugin
@@ -31,7 +58,7 @@ pnpm add iterate-plugin
 ### 本地开发 / 源码挂载
 
 ```bash
-dsh plugin --profile web add /Volumes/Eng-Dev/iterate-skill/harness/iterate-plugin
+dsh plugin --profile web add /path/to/iterate-skill/harness/iterate-plugin
 # 或
 pnpm add /path/to/iterate-skill/harness/iterate-plugin
 ```
@@ -44,6 +71,8 @@ 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`）。
+
 ## 使用
 
 ### dry-run 模式（纯反复审查，不修改文件）
@@ -55,6 +84,7 @@ dry-run review this project, find all issues across all dimensions
 ```
 
 插件会自动触发 iterate 工作流：
+
 1. `plan` → 读取配置，生成评审计划
 2. `loop` → 每轮并行评审，只找新问题 → 确定性聚合去重 → 统计收敛 → 无新问题则停止
 3. `meta-review` → 审计报告一致性
@@ -69,8 +99,9 @@ iterate on this project, fix all atomic issues
 ```
 
 工作流：
+
 1. `plan` → 读取配置
-2. `loop` → 并行评审 → 聚合去重 → 原子问题并行修复 → 执行验证命令 → 记录日志 → 无新问题则停止
+2. `loop` → 并行评审 → 聚合去重 → 原子问题并行修复 → 执行验证命令 → 验证失败则回滚 → 记录日志 → 无新问题则停止
 3. `report` → 输出修复统计
 
 ## 项目配置
@@ -92,6 +123,9 @@ max_rounds: 3
 # 评审范围
 review:
   scope: full  # full = 全项目，changed-only = 只看变更文件
+# 原子修复阈值（单次修复允许改动的最大行数，超过需 force）
+atomic:
+  max_lines: 20
 # 已知故意不修复的问题（评审会过滤掉，不再重复报告）
 personalization:
   known_intentional:
@@ -106,24 +140,48 @@ validation:
     - npm run typecheck
 ```
 
-## 注册工具
+> 配置可通过 `iterate_config` 工具读取与**校验式局部写入**（自动备份，写入失败自动回滚）。
 
-插件注册了 5 个工具：
+## 注册工具（13 个）
 
 | 工具 | 功能 |
 |------|------|
-| `iterate_config` | 读取并验证 `iterate.config.yaml` |
+| `iterate_config` | 读取 / 写入 `iterate.config.yaml`。`operation=read` 返回完整配置或指定 section；`operation=write` 做 schema 校验、备份后局部合并写入，失败自动回滚 |
 | `iterate_validate` | 运行白名单验证命令，返回结果 |
-| `iterate_decision_log` | 追加决策日志（只追加，不改旧） |
+| `iterate_decision_log` | 追加决策日志（只追加，不改旧），存储于 `.iterate/decision-log.jsonl` |
 | `iterate_context` | 读取 `SKILL.md` / `ITERATE.md` 上下文 |
-| `iterate_review` | 确定性评审引擎：`plan` 生成计划，`aggregate` 聚合结论，`meta-review` 审计报告 |
+| `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 + 注册 5 个纯函数工具
-- 所有 orchestration 通过 dsh 原生 `workflow` + `agent` + `parallel` 完成
-- 核心逻辑（去重/过滤/排序/收敛/meta-audit）全部纯函数，可单元测试，无 I/O
+
+- **只做两件事**：注入系统 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 原技能的设计原则：确定性收敛，可审计，最小权限
 
 ## 运行测试
@@ -136,9 +194,9 @@ npm test
 ```
 
 所有测试通过：
-- 63 个单元测试全绿
-- 覆盖去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制
-- 类型检查通过
+
+- **212 个单元测试全绿**，类型检查通过
+- 覆盖：去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制、配置读写与回滚、triage 合并、diff 计算、checkpoint 校验、修复注册表、历史读取与过滤、prune 清理报告与 dry-run 语义、UI 纯函数（select-all 键、运行时状态指引）等
 
 ## License
 

package/lib/client.js

@@ -47,6 +47,8 @@ import {
   buildCompletionSummary,
   buildConfigEditGuide,
   keyToVerdict,
+  allVerdictKeys,
+  buildRuntimeStatusGuide,
   SEVERITY_LABEL,
   SEVERITY_COLOR,
 } from './parse.js'
@@ -194,6 +196,9 @@ const ITERATE_CSS = `
 .iterate-completion[data-warn] { border: 1px solid var(--dsw-alias-state-warn-primary); color: var(--dsw-alias-state-warn-primary); background: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 10%, transparent); }
 .iterate-capsule[data-ok] { border-color: var(--dsw-alias-state-success-primary); color: var(--dsw-alias-state-success-primary); }
 .iterate-settings-guide { white-space: pre-wrap; padding: 8px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 8px; background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-label-primary); font-family: var(--dsw-font-mono, ui-monospace, monospace); font-size: 11px; max-height: 180px; overflow: auto; }
+.iterate-chip[data-ok] { border-color: var(--dsw-alias-state-success-primary); color: var(--dsw-alias-state-success-primary); background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 10%, transparent); }
+.iterate-batch-check { display: inline-flex; align-items: center; gap: 4px; padding: 3px 8px; border-radius: 6px; border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-label-secondary); font-size: 11px; cursor: pointer; }
+.iterate-batch-check input { margin: 0; cursor: pointer; }
 `
 
 // ─── Small helpers ───────────────────────────────────────────────────────────
@@ -225,6 +230,7 @@ function createStorage() {
       get(key) { return window.localStorage.getItem(key) },
       set(key, value) { window.localStorage.setItem(key, value) },
       remove(key) { window.localStorage.removeItem(key) },
+      keys() { return Object.keys(window.localStorage) },
     }
   } catch {
     const mem = new Map()
@@ -232,10 +238,31 @@ function createStorage() {
       get(key) { return mem.has(key) ? mem.get(key) : null },
       set(key, value) { mem.set(key, value) },
       remove(key) { mem.delete(key) },
+      keys() { return [...mem.keys()] },
     }
   }
 }
 
+/**
+ * Remove every stored key with the given prefix (e.g. all triage verdicts).
+ * Returns how many keys were removed.
+ */
+function removeStorageByPrefix(prefix) {
+  if (!storage) return 0
+  let removed = 0
+  try {
+    for (const key of storage.keys()) {
+      if (key.startsWith(prefix)) {
+        storage.remove(key)
+        removed++
+      }
+    }
+  } catch (err) {
+    log('failed to clear storage prefix', prefix, err)
+  }
+  return removed
+}
+
 /** Copy text to the clipboard, returning whether it succeeded. */
 function copyText(text) {
   if (typeof navigator !== 'undefined' && navigator.clipboard && typeof navigator.clipboard.writeText === 'function') {
@@ -357,6 +384,17 @@ function ConvergenceDashboard(props) {
     ),
   )
 
+  // Fix-count badge: show when the report has a fixes summary.
+  const mode = report.mode
+  const summary = report.summary
+  const isNormal = mode === 'normal'
+  const fixCount = isNormal && summary && typeof summary.fixedCount === 'number' ? summary.fixedCount : null
+  const fixBadge = fixCount !== null
+    ? React.createElement('span', { className: 'iterate-metric', key: 'fixes' },
+        '\u{1F527} ' + String(fixCount) + ' fixes',
+      )
+    : null
+
   return React.createElement(
     'div',
     { 'data-iterate-root': '', 'data-iterate': 'dashboard', className: 'iterate-dashboard' },
@@ -380,6 +418,7 @@ function ConvergenceDashboard(props) {
       React.createElement('span', { className: 'iterate-sev-dot', style: { background: SEVERITY_COLOR.medium } }),
       stats.medium,
     ),
+    fixBadge,
     React.createElement(TrendChart, { points: trend.points }),
     ...dimBadges,
   )
@@ -484,6 +523,7 @@ function TriagePanel(props) {
   const [copied, setCopied] = React.useState(false)
   const [filter, setFilter] = React.useState({ severities: [], dimensions: [], search: '' })
   const [selected, setSelected] = React.useState(null)
+  const [selectAll, setSelectAll] = React.useState(false)
 
   /** Persist + return the next verdicts state. */
   const persistVerdicts = (next) => {
@@ -506,13 +546,20 @@ function TriagePanel(props) {
   const setSearchFilter = (value) => setFilter((f) => ({ ...f, search: value }))
   const clearFilter = () => setFilter({ severities: [], dimensions: [], search: '' })
 
-  // ── Batch operations (apply to the currently VISIBLE findings) ───────────
+  // ── Batch operations (apply to the currently VISIBLE findings, or to ALL
+  //    findings when the select-all toggle is on) ──────────────────────────
+  const allIndices = allVerdictKeys(verdicts)
+  const batchTarget = selectAll ? allIndices : indices
   const applyBatch = (verdict) => {
-    setVerdicts((prev) => persistVerdicts(batchSetVerdict(prev, indices, verdict)))
+    setVerdicts((prev) => persistVerdicts(batchSetVerdict(prev, batchTarget, verdict)))
   }
   const applyBatchAll = (verdict) => {
     setVerdicts((prev) => persistVerdicts(setAllVerdicts(prev, verdict)))
   }
+  const doResetVerdicts = () => {
+    setVerdicts((prev) => persistVerdicts(setAllVerdicts(prev, 'keep')))
+    setSelectAll(false)
+  }
 
   // ── Keyboard shortcuts (y / n / a on the selected finding, ↑/↓ to move) ──
   React.useEffect(() => {
@@ -637,7 +684,11 @@ function TriagePanel(props) {
       ),
     ),
     React.createElement('div', { className: 'iterate-batch' },
-      React.createElement('span', { className: 'iterate-batch-label' }, '批量（当前可见）：'),
+      React.createElement('span', { className: 'iterate-batch-label' }, '批量：'),
+      React.createElement('label', { className: 'iterate-batch-check', title: '勾选后批量按钮作用于全部 findings，否则仅当前可见' },
+        React.createElement('input', { type: 'checkbox', checked: selectAll, onChange: (e) => setSelectAll(e.target.checked) }),
+        selectAll ? `全部 ${allIndices.length}` : '全选',
+      ),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatch('keep') }, '全部 y'),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatch('skip') }, '全部 n'),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatch('ignore') }, '全部 a'),
@@ -645,6 +696,7 @@ function TriagePanel(props) {
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatchAll('keep') }, 'y'),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatchAll('skip') }, 'n'),
       React.createElement('button', { className: 'iterate-batch-btn', onClick: () => applyBatchAll('ignore') }, 'a'),
+      React.createElement('button', { className: 'iterate-batch-btn', onClick: doResetVerdicts, title: '把所有判定恢复为默认 y（修复）' }, '重置'),
     ),
     ...rows,
     React.createElement('div', { className: 'iterate-triage-foot' },
@@ -712,7 +764,10 @@ function SettingsPanel() {
   const [enabled, setEnabled] = React.useState(themeEnabled)
   const [copied, setCopied] = React.useState(false)
   const [showGuide, setShowGuide] = React.useState(false)
+  const [clearedCount, setClearedCount] = React.useState(null)
+  const [showStatus, setShowStatus] = React.useState(false)
   const guide = buildConfigEditGuide()
+  const statusGuide = buildRuntimeStatusGuide()
 
   const toggleTheme = () => {
     const next = !enabled
@@ -726,6 +781,12 @@ function SettingsPanel() {
     setTimeout(() => setCopied(false), 1600)
   }
 
+  const doClearTriage = () => {
+    const count = removeStorageByPrefix(TRIAGE_STORAGE_PREFIX)
+    setClearedCount(count)
+    setTimeout(() => setClearedCount(null), 3000)
+  }
+
   return React.createElement('div', { 'data-iterate-root': '', 'data-iterate': 'settings', className: 'iterate-settings' },
     React.createElement('div', { className: 'iterate-settings-title' }, 'iterate 设置'),
     React.createElement('div', { className: 'iterate-settings-row' },
@@ -744,7 +805,16 @@ function SettingsPanel() {
         React.createElement('div', { className: 'iterate-settings-title' }, '分诊持久化'),
         React.createElement('div', { className: 'iterate-settings-desc' }, '分诊面板的 y/n/a 判定保存在本地浏览器（localStorage），刷新会话后仍保留。'),
       ),
-      React.createElement('span', { className: 'iterate-chip' }, '本地保存'),
+      React.createElement('span', { style: { display: 'flex', gap: 6, alignItems: 'center' } },
+        React.createElement('span', { className: 'iterate-chip' }, '本地保存'),
+        React.createElement('button', {
+          className: 'iterate-btn',
+          onClick: doClearTriage,
+          title: '清除所有分诊判定记录',
+          'data-primary': clearedCount !== null ? '' : undefined,
+          'data-copied': clearedCount !== null ? '' : undefined,
+        }, clearedCount !== null ? `已清除 ${clearedCount} 条` : '清除分诊'),
+      ),
     ),
     React.createElement('div', { className: 'iterate-settings-row' },
       React.createElement('div', {},
@@ -759,6 +829,16 @@ function SettingsPanel() {
     showGuide
       ? React.createElement('div', { className: 'iterate-settings-guide' }, guide)
       : null,
+    React.createElement('div', { className: 'iterate-settings-row' },
+      React.createElement('div', {},
+        React.createElement('div', { className: 'iterate-settings-title' }, '状态概览'),
+        React.createElement('div', { className: 'iterate-settings-desc' }, '运行时产物布局与清理指引。iterate_status / iterate_history / iterate_prune 工具用于查看和管理。'),
+      ),
+      React.createElement('button', { className: 'iterate-btn', onClick: () => setShowStatus((v) => !v) }, showStatus ? '收起' : '查看'),
+    ),
+    showStatus
+      ? React.createElement('div', { className: 'iterate-settings-guide' }, statusGuide)
+      : null,
   )
 }
 

package/lib/parse.js

@@ -787,4 +787,72 @@ export const VERDICT_SHORTCUTS = {
  */
 export function keyToVerdict(key) {
   return VERDICT_SHORTCUTS[key] ?? null
+}
+
+// ─── Select-all keys ────────────────────────────────────────────────────────
+
+/**
+ * Every finding index in a triage state, sorted ascending.
+ * Used by the select-all toggle so batch operations can target ALL findings
+ * (not just the currently visible/filtered ones).
+ *
+ * @param {Record<string, 'keep' | 'skip' | 'ignore'> | null | undefined} triageState
+ * @returns {number[]}
+ */
+export function allVerdictKeys(triageState) {
+  const state = triageState && typeof triageState === 'object' ? triageState : {}
+  return Object.keys(state)
+    .map(Number)
+    .filter((n) => Number.isInteger(n) && n >= 0)
+    .sort((a, b) => a - b)
+}
+
+// ─── Runtime status guide ────────────────────────────────────────────────────
+
+/**
+ * Runtime artifacts produced under `<projectRoot>/.iterate/`.
+ * @type {Array<{ key: string, label: string, hint: string }>}
+ */
+export const RUNTIME_ARTIFACTS = [
+  {
+    key: 'decision-log.jsonl',
+    label: '决策日志',
+    hint: '追加式 JSONL，记录每轮 plan / review / fix / revert / validation 决策',
+  },
+  {
+    key: 'checkpoint.json',
+    label: '迭代断点',
+    hint: '长迭代的进度快照，中断后可恢复（iterate_checkpoint）',
+  },
+  {
+    key: 'fixes/registry.json',
+    label: '修复注册表',
+    hint: '每个原子修复的 id / diff / 备份路径（iterate_fix / iterate_diff）',
+  },
+  {
+    key: 'fixes/*.bak',
+    label: '修复备份',
+    hint: '每次修复前的原文件备份，回滚依赖（iterate_rollback）',
+  },
+]
+
+/**
+ * Copy-paste guide for inspecting / pruning the runtime state. Shown in the
+ * settings "状态概览" card so the user knows exactly where artifacts live and
+ * which tools inspect them.
+ *
+ * @returns {string}
+ */
+export function buildRuntimeStatusGuide() {
+  const lines = [
+    'iterate 运行时状态概览',
+    '----------------------',
+    '所有运行时产物位于项目根目录 .iterate/ 下：',
+    '',
+    ...RUNTIME_ARTIFACTS.map((a) => `- ${a.key}（${a.label}）：${a.hint}`),
+    '',
+    '查看状态：让模型调用 iterate_status（汇总）或 iterate_history（明细）。',
+    '清理状态：让模型调用 iterate_prune（默认 dry-run，只报告不删除，显式 dryRun:false 才真正清理）。',
+  ]
+  return lines.join('\n')
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -30,6 +30,8 @@ import { registerReviewTool } from './tools/review.ts'
 import { registerTriageTool } from './tools/triage.ts'
 import { registerFixTool, registerDiffTool, registerRollbackTool } from './tools/fix.ts'
 import { registerCheckpointTool, registerStatusTool } from './tools/checkpoint.ts'
+import { registerHistoryTool } from './tools/history.ts'
+import { registerPruneTool } from './tools/prune.ts'
 import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
 
 export const name = 'iterate-plugin'
@@ -48,6 +50,8 @@ export function apply(ctx: Context): void {
   registerRollbackTool(ctx)
   registerCheckpointTool(ctx)
   registerStatusTool(ctx)
+  registerHistoryTool(ctx)
+  registerPruneTool(ctx)
 
   // 2. Inject the iterate skill prompt as a system prompt section
   // This teaches the model how to write iterate workflow scripts using the tools.

package/src/tools/fix.ts

@@ -26,6 +26,11 @@ import { fixBackupPath, fixRegistryPath, fixesDir } from '../paths.ts'
 import { appendDecisionEntry } from './decision-log.ts'
 import type { FileDiffHunk, FixRecord, FixRegistry, ReviewFinding } from '../types.ts'
 
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Upper bound for a single fix `content` payload (characters). */
+export const MAX_FIX_CONTENT_CHARS = 1_000_000
+
 // ─── Pure helpers (exported for unit tests) ─────────────────────────────────
 
 /**
@@ -288,6 +293,12 @@ export function registerFixTool(ctx: { tools: { register: (def: ReturnType<typeo
         const file = typeof args.file === 'string' ? args.file : ''
         if (!file) return { ok: false, error: 'file is required' }
         if (typeof args.content !== 'string') return { ok: false, error: 'content must be a string' }
+        if (args.content.length > MAX_FIX_CONTENT_CHARS) {
+          return {
+            ok: false,
+            error: `content exceeds the ${MAX_FIX_CONTENT_CHARS}-character limit (got ${args.content.length})`,
+          }
+        }
         if (typeof args.round !== 'number' || !Number.isInteger(args.round) || args.round < 1) {
           return { ok: false, error: 'round must be a positive integer' }
         }

package/src/tools/history.ts

@@ -0,0 +1,162 @@
+/**
+ * src/tools/history.ts — iteration history reader.
+ *
+ *   iterate_history — read the decision-log entries (with optional filters)
+ *                     plus a summary of the fix registry, so the user or the
+ *                     orchestrator can review exactly what the run did.
+ *
+ * Complements `iterate_status` (compact summary) with the actual detail.
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { resolveProjectRoot } from '../config-loader.ts'
+import { readDecisionEntries } from './decision-log.ts'
+import { readRegistry } from './fix.ts'
+import type { DecisionLogEntry, FixRegistry } from '../types.ts'
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 200
+
+/** Clamp a caller-supplied `limit` to a sane range. */
+export function clampHistoryLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
+    return DEFAULT_LIMIT
+  }
+  return Math.min(limit, MAX_LIMIT)
+}
+
+/**
+ * Filter + cap decision-log entries. Pure, unit-tested.
+ * Returns the newest `limit` matching entries plus the total match count
+ * (before the cap), so callers can tell when the result was truncated.
+ */
+export function filterDecisionEntries(
+  entries: DecisionLogEntry[],
+  opts: { type?: unknown; since?: unknown; limit?: unknown },
+): { entries: DecisionLogEntry[]; filteredCount: number; limit: number } {
+  const type = typeof opts.type === 'string' && opts.type ? opts.type : undefined
+  const since = typeof opts.since === 'string' && opts.since ? opts.since : undefined
+  const limit = clampHistoryLimit(opts.limit as number | undefined)
+
+  const matching = (Array.isArray(entries) ? entries : []).filter((e) => {
+    if (type && e.type !== type) return false
+    if (since && e.timestamp <= since) return false
+    return true
+  })
+  return {
+    entries: matching.slice(-limit),
+    filteredCount: matching.length,
+    limit,
+  }
+}
+
+/** Per-round fix counts + totals from a fix registry. Pure, unit-tested. */
+export function summarizeFixRegistry(registry: FixRegistry): {
+  totalFixed: number
+  totalFailed: number
+  roundCount: number
+  rounds: { round: number; fixedCount: number; failedCount: number }[]
+} {
+  const rounds = (registry.rounds ?? []).map((r) => ({
+    round: r.round,
+    fixedCount: r.fixedCount,
+    failedCount: r.failedCount,
+  }))
+  return {
+    totalFixed: rounds.reduce((s, r) => s + r.fixedCount, 0),
+    totalFailed: rounds.reduce((s, r) => s + r.failedCount, 0),
+    roundCount: rounds.length,
+    rounds,
+  }
+}
+
+/**
+ * Register the `iterate_history` tool.
+ * Reads the decision log (optionally filtered by type / since / limit) and a
+ * fix-registry summary. Read-only; never modifies the filesystem.
+ */
+export function registerHistoryTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_history',
+      description:
+        'Read the iteration history: decision-log entries (optionally filtered by entry `type`, `since` ' +
+        'timestamp, and a `limit`) plus a summary of the fix registry (per-round fixed/failed counts). ' +
+        'Read-only — use it to review what the run did, audit a log, or inspect fixes.',
+      parameters: {
+        type: {
+          type: 'string',
+          description:
+            'Optional entry-type filter: round_start, review_result, atomic_fix, architectural_fix, ' +
+            'revert, validation, decision, report.',
+        },
+        since: {
+          type: 'string',
+          description: 'Optional ISO timestamp; only entries AFTER this timestamp are returned.',
+        },
+        limit: {
+          type: 'integer',
+          description: `Max entries to return (default: ${DEFAULT_LIMIT}, cap: ${MAX_LIMIT}). Newest first.`,
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            kind: { type: 'string' },
+            count: { type: 'integer' },
+            filteredCount: { type: 'integer' },
+            limit: { type: 'integer' },
+            log: { type: 'json' },
+            fixes: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `history failed: ${value.error}` }]
+          const log = (value.log as DecisionLogEntry[] | undefined) ?? []
+          const fixes = (value.fixes as { totalFixed: number; totalFailed: number; roundCount: number } | undefined)
+          const lines = [
+            `Decision-log entries: ${value.count} (filtered to ${value.limit})`,
+            fixes
+              ? `Fixes: ${fixes.totalFixed} applied · ${fixes.totalFailed} failed · across ${fixes.roundCount} round(s)`
+              : 'Fixes: none',
+            '',
+            ...log.map((e) => `[${e.timestamp}] r${e.round} ${e.type}: ${JSON.stringify(e.data ?? {})}`),
+          ]
+          return [{ type: 'text', text: lines.join('\n') }]
+        },
+      },
+
+      async execute(args) {
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) return { ok: false, kind: 'history', error: resolved.reason }
+        const projectRoot = resolved.root
+
+        const { entries, filteredCount, limit } = filterDecisionEntries(
+          readDecisionEntries(projectRoot),
+          { type: args.type, since: args.since, limit: args.limit },
+        )
+        const fixes = summarizeFixRegistry(readRegistry(projectRoot))
+
+        return {
+          ok: true,
+          kind: 'history',
+          count: entries.length,
+          filteredCount,
+          limit,
+          log: entries as unknown as JsonValue,
+          fixes: fixes as unknown as JsonValue,
+        }
+      },
+    }),
+  )
+}

package/src/tools/prune.ts

@@ -0,0 +1,313 @@
+/**
+ * src/tools/prune.ts — runtime artifact cleanup for the iterate loop.
+ *
+ *   iterate_prune — inspect or remove stale runtime artifacts (.iterate/).
+ *                   Defaults to dry-run (report-only); set `dryRun: false` to
+ *                   actually delete.
+ *
+ * Artifacts managed:
+ *   - Decision-log entries older than `retainDays` (default 30, via since).
+ *   - Stale checkpoint files (checkpoint.json).
+ *   - Fix backups left over from old rounds (backups whose fix-id no longer
+ *     appears in the registry).
+ *   - Empty fix rounds (rounds with 0 records).
+ *
+ * Security model:
+ *   - Only operates under the resolved project `.iterate/` directory.
+ *   - dryRun=true by default — the caller must explicitly opt into deletion.
+ *   - Each deletion is logged to the decision log (when not dry-run).
+ */
+
+import { existsSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { resolveProjectRoot } from '../config-loader.ts'
+import { readDecisionEntries, appendDecisionEntry } from './decision-log.ts'
+import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'
+import { iterateDir, fixesDir, checkpointPath, fixRegistryPath } from '../paths.ts'
+import type { FixRegistry } from '../types.ts'
+
+/** Default retention for decision-log entries (in days). */
+const DEFAULT_RETAIN_DAYS = 30
+const MIN_RETAIN_DAYS = 1
+const MAX_RETAIN_DAYS = 365
+
+/** Clamp retainDays to a sane range. */
+export function clampRetainDays(days: number | undefined): number {
+  if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
+    return DEFAULT_RETAIN_DAYS
+  }
+  return Math.min(Math.max(days, MIN_RETAIN_DAYS), MAX_RETAIN_DAYS)
+}
+
+/** Build the cutoff timestamp for a given retainDays. */
+export function cutoffTimestamp(retainDays: number): string {
+  const d = new Date()
+  d.setDate(d.getDate() - retainDays)
+  return d.toISOString()
+}
+
+/**
+ * Inspect the runtime state and report what would be pruned.
+ * Pure (no deletions). Returns a structured report.
+ */
+export function inspectPrune(
+  projectRoot: string,
+  retainDays: number,
+): {
+  oldLogEntries: number
+  hasCheckpoint: boolean
+  staleBackups: string[]
+  emptyRounds: number[]
+  totalLogEntries: number
+  registryRounds: number
+} {
+  const cutoff = cutoffTimestamp(retainDays)
+
+  // 1. Decision-log entries older than retainDays.
+  const entries = readDecisionEntries(projectRoot)
+  const oldLogEntries = entries.filter((e) => e.timestamp < cutoff).length
+
+  // 2. Checkpoint presence.
+  const hasCheckpoint = existsSync(checkpointPath(projectRoot))
+
+  // 3. Stale fix backups: .bak files whose fix-id prefix is not in the registry.
+  const registry = readRegistry(projectRoot)
+  const activeIds = new Set<string>()
+  for (const r of registry.rounds) {
+    for (const rec of r.records) {
+      activeIds.add(rec.id)
+    }
+  }
+  const staleBackups: string[] = []
+  const fixDir = fixesDir(projectRoot)
+  if (existsSync(fixDir)) {
+    for (const entry of readdirSync(fixDir)) {
+      if (!entry.endsWith('.bak')) continue
+      // Extract the fix-id prefix (up to the first underscore after the id).
+      // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
+      const match = entry.match(/^(fix-[a-z0-9]+)_/)
+      const id = match?.[1]
+      if (id && !activeIds.has(id)) {
+        staleBackups.push(entry)
+      }
+    }
+  }
+
+  // 4. Empty rounds (rounds with 0 records).
+  const emptyRounds = registry.rounds
+    .filter((r) => r.records.length === 0)
+    .map((r) => r.round)
+
+  return {
+    oldLogEntries,
+    hasCheckpoint,
+    staleBackups,
+    emptyRounds,
+    totalLogEntries: entries.length,
+    registryRounds: registry.rounds.length,
+  }
+}
+
+/**
+ * Actually prune the runtime artifacts (only called when dryRun=false).
+ * Returns a detailed report of what was deleted.
+ */
+export function executePrune(
+  projectRoot: string,
+  retainDays: number,
+  report: ReturnType<typeof inspectPrune>,
+): {
+  deletedLogEntries: number
+  deletedCheckpoint: boolean
+  deletedBackups: string[]
+  trimmedEmptyRounds: number
+  errors: string[]
+} {
+  const cutoff = cutoffTimestamp(retainDays)
+  const result = {
+    deletedLogEntries: 0,
+    deletedCheckpoint: false,
+    deletedBackups: [] as string[],
+    trimmedEmptyRounds: 0,
+    errors: [] as string[],
+  }
+
+  // 1. Rewrite the decision log, keeping only recent entries.
+  try {
+    const entries = readDecisionEntries(projectRoot)
+    const kept = entries.filter((e) => e.timestamp >= cutoff)
+    result.deletedLogEntries = entries.length - kept.length
+    if (result.deletedLogEntries > 0) {
+      writeFileSync(
+        join(iterateDir(projectRoot), 'decision-log.jsonl'),
+        kept.map((e) => JSON.stringify(e)).join('\n') + '\n',
+        'utf-8',
+      )
+    }
+  } catch (err) {
+    result.errors.push(`failed to rewrite decision log: ${String(err)}`)
+    result.deletedLogEntries = 0
+  }
+
+  // 2. Remove checkpoint.
+  if (report.hasCheckpoint) {
+    try {
+      rmSync(checkpointPath(projectRoot), { force: true })
+      result.deletedCheckpoint = true
+    } catch (err) {
+      result.errors.push(`failed to remove checkpoint: ${String(err)}`)
+    }
+  }
+
+  // 3. Delete stale backups.
+  for (const bak of report.staleBackups) {
+    try {
+      unlinkSync(join(fixesDir(projectRoot), bak))
+      result.deletedBackups.push(bak)
+    } catch (err) {
+      result.errors.push(`failed to delete backup ${bak}: ${String(err)}`)
+    }
+  }
+
+  // 4. Trim empty rounds from the registry.
+  if (report.emptyRounds.length > 0) {
+    try {
+      let registry = readRegistry(projectRoot)
+      for (const round of report.emptyRounds) {
+        for (const rec of [...registry.rounds.find((r) => r.round === round)?.records ?? []]) {
+          registry = removeRecord(registry, rec.id)
+        }
+      }
+      registry = recomputeRoundCounts(registry)
+      writeFileSync(fixRegistryPath(projectRoot), JSON.stringify(registry, null, 2), 'utf-8')
+      result.trimmedEmptyRounds = report.emptyRounds.length
+    } catch (err) {
+      result.errors.push(`failed to trim empty rounds: ${String(err)}`)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Register the `iterate_prune` tool.
+ * Defaults to dry-run: inspects the runtime state and reports what would be
+ * cleaned up. Pass `dryRun: false` to actually delete.
+ */
+export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_prune',
+      description:
+        'Inspect or clean up old iterate runtime artifacts (.iterate/). ' +
+        'Defaults to dry-run (report-only, no deletion). Pass `dryRun: false` to actually prune. ' +
+        'Manages: old decision-log entries, stale checkpoints, orphaned fix backups, empty fix rounds. ' +
+        'Each deletion is logged to the decision log.',
+      parameters: {
+        dryRun: {
+          type: 'boolean',
+          description: 'When true (default), only report what would be pruned without deleting anything.',
+        },
+        retainDays: {
+          type: 'integer',
+          description: `Keep entries newer than this many days (default: ${DEFAULT_RETAIN_DAYS}, range: ${MIN_RETAIN_DAYS}-${MAX_RETAIN_DAYS}).`,
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            dryRun: { type: 'boolean', required: true },
+            retainDays: { type: 'integer' },
+            report: { type: 'json' },
+            result: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `prune failed: ${value.error}` }]
+          const report = value.report as Record<string, unknown> | undefined
+          const result = value.result as Record<string, unknown> | undefined
+          if (value.dryRun) {
+            const lines = [
+              `[dry-run] prune report (retainDays=${value.retainDays}):`,
+              `  Decision-log entries to remove: ${report?.oldLogEntries ?? '?'} (of ${report?.totalLogEntries ?? '?'})`,
+              `  Checkpoint to delete: ${report?.hasCheckpoint ? 'yes' : 'none'}`,
+              `  Stale backups to delete: ${(report?.staleBackups as string[] | undefined)?.length ?? 0}`,
+              `  Empty rounds to trim: ${(report?.emptyRounds as number[] | undefined)?.length ?? 0}`,
+              '',
+              'Pass dryRun:false to execute the prune.',
+            ]
+            return [{ type: 'text', text: lines.join('\n') }]
+          }
+          const lines = [
+            `Prune complete (retainDays=${value.retainDays}):`,
+            `  Deleted ${result?.deletedLogEntries ?? 0} old log entries.`,
+            `  Checkpoint deleted: ${result?.deletedCheckpoint ? 'yes' : 'no'}`,
+            `  Deleted ${(result?.deletedBackups as string[] | undefined)?.length ?? 0} stale backups.`,
+            `  Trimmed ${result?.trimmedEmptyRounds ?? 0} empty rounds.`,
+          ]
+          const errs = (result?.errors as string[] | undefined) ?? []
+          if (errs.length > 0) {
+            lines.push('', '  Warnings:')
+            for (const e of errs) lines.push(`    - ${e}`)
+          }
+          return [{ type: 'text', text: lines.join('\n') }]
+        },
+      },
+
+      async execute(args) {
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) return { ok: false, dryRun: true, error: resolved.reason }
+        const projectRoot = resolved.root
+        const retainDays = clampRetainDays(args.retainDays as number | undefined)
+        const dryRun = args.dryRun !== false
+
+        const report = inspectPrune(projectRoot, retainDays)
+
+        if (dryRun) {
+          return {
+            ok: true,
+            dryRun: true,
+            retainDays,
+            report: report as unknown as JsonValue,
+          }
+        }
+
+        const result = executePrune(projectRoot, retainDays, report)
+
+        // Log the prune to the decision log.
+        appendDecisionEntry(projectRoot, {
+          timestamp: new Date().toISOString(),
+          round: 0,
+          type: 'decision',
+          data: {
+            action: 'prune',
+            retainDays,
+            deletedLogEntries: result.deletedLogEntries,
+            deletedCheckpoint: result.deletedCheckpoint,
+            deletedBackups: result.deletedBackups.length,
+            trimmedEmptyRounds: result.trimmedEmptyRounds,
+          },
+        })
+
+        return {
+          ok: true,
+          dryRun: false,
+          retainDays,
+          report: report as unknown as JsonValue,
+          result: result as unknown as JsonValue,
+        }
+      },
+    }),
+  )
+}

package/src/tools/triage.ts

@@ -12,6 +12,9 @@ const CONFIG_FILE = 'iterate.config.yaml'
 const PERSONALIZATION_KEY = 'personalization'
 const KNOWN_INTENTIONAL_KEY = 'known_intentional'
 
+/** Max entries per single `apply` call. */
+const MAX_ENTRIES = 500
+
 /** Whole-file marker line (matches review.ts filterKnownIntentional semantics). */
 const WHOLE_FILE_LINE = 0
 
@@ -45,6 +48,10 @@ export function validateTriageEntries(entries: unknown): string[] {
     errors.push('entries must be an array')
     return errors
   }
+  if (entries.length > MAX_ENTRIES) {
+    errors.push(`entries must not exceed ${MAX_ENTRIES} items (got ${entries.length})`)
+    return errors
+  }
   for (let i = 0; i < entries.length; i++) {
     const prefix = `entries[${i}]`
     const e = entries[i]