把 iterate 技能跑成自主闭环:规划、并行审查、原子修复、验证、循环、自动停止,并支持纯评审的 dry-run 模式与元评审最终报告。
安装
# npm 包(预构建)
dsh plugin --profile web add iterate-plugin
# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)
dsh plugin --profile web add github:jingzhao-l/iterate-plugin
装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。
README
dsh 桌面端的 iterate 质量指挥中心 + 经验银行插件(v3.6)。把 iterate 生态的同一套 review/fix loop 直接搬进 dsh 界面,新增质量门禁、经验银行、防御事件流与原生指挥操作。
开发与评审在 iterate-skill 主仓库 完成:插件代码由主仓库统一维护,通过
git subtree同步到本仓库;版本发版与 npm 发布在本仓库(插件仓库)进行,作为 dsh 生态的正式发布位。欢迎 star / fork 主仓库 并在 主仓库 Issues 反馈问题。
⭐ 如果这个插件对你的 dsh 工作流有帮助,欢迎为主仓库点亮 Star,这是对开源维护最大的支持!
iterate 生态一览 / The iterate Ecosystem
iterate 不是一个独立的工具,而是一套附着在现有 AI 助手之上的技能生态。 它不会替换你的 IDE 或 AI 工具,而是在你已有的工作流里,叠加一层"严格的代码收尾与把关"。整个生态由三个可互换组件构成,共用同一套 iterate.config.yaml 与同一套 9 维度审查体系:
- Core Skill + CLI / 核心技能与命令行 — 可移植 AI 技能
/iterate+iterateCLI。在 Trae / Claude Code / Cursor / Copilot / Codex 等 25+ 助手中以对话方式进行多轮迭代。 - iterate-harness / 无头引擎 — 独立无头引擎,命令
ih(npm:iterate-harness)。在终端 / CI / Git 钩子里脱离对话式助手,运行同一套闭环。 - iterate-plugin / dsh 桌面插件(本仓库) — dsh 桌面客户端插件(npm:
iterate-plugin)。把 harness 运行时直接接入 dsh 界面:收敛看板、分诊面板、轮次进度,均以原生 dsh 控件形式展示。
三者关系:Core Skill 是最通用的跨助手审查/修复引擎("大脑");iterate-harness 是同一引擎封装为无头 CLI + WebUI,适合跑在无需交互的场景;iterate-plugin(本仓库)把 harness 运行时进一步封装为 dsh 插件,直接在 dsh 桌面客户端内渲染分诊 UI 与收敛看板。配置(iterate.config.yaml)与 9 维度审查体系三者完全一致——理解其一,即可举一反三。
生态其余组件的快速安装/入口:
# Core Skill + CLI(一键安装到 25+ AI 编程助手)
npx iterate-skill-installer
# iterate-harness:无头引擎(npm 包装器,最简)
npm install -g iterate-harness
curl -fsSL https://raw.githubusercontent.com/jingzhao-l/iterate-harness/main/scripts/install.sh | bash
ih iterate init && ih iterate review
# iterate-plugin:dsh 桌面插件(本仓库,安装命令在下文「安装」一节重复列出)
dsh plugin --profile web add iterate-plugin
本文档从下一节开始聚焦 iterate-plugin(本仓库)。核心技能文档见 iterate-skill 主仓库,无头引擎文档见 iterate-harness 独立仓库。
这是什么 / About This Plugin
iterate 是一个让 AI 编程助手具备多轮自主代码审查与修复能力的开源项目。它解决很具体的痛点:
AI 助手往往"说得多、做得浅":一次对话只改几行、看过一个文件就不再管全局,也很少回头复核自己改坏的东西。iterate 把这些收尾工作——逐项审查、分维度排查、修复、验证、再迭代——自动化,让 AI 真正像资深工程师一样把改动做完、做对。
iterate-plugin 是 iterate 项目在 DeepSeek Harness (dsh) 桌面客户端中的落地插件。它把 iterate 的审查闭环(review → triage → fix → validate → 收敛)直接带进 dsh 的界面:提供自治闭环代码迭代(normal 模式)与 dry-run 纯多轮审查(只读)两种能力。
v3.2 质量指挥中心:插件已从"被动观察面板"升级为"主动指挥中心 + 知识库"。新增质量门禁读取与可写计算(compute)、经验银行(检索 / 采纳 / 新增 add)、防御事件流(记录 + 中英双语标签)、原生命令按钮与 task_mode 指示器。
除 19 个纯函数工具外,还内置一套免构建的 Web UI 层(收敛看板、分诊面板、统计卡片、12 页签运行时观测台——实时活动流 + F1–F11——、主题皮肤等),直接挂在 dsh 客户端的既有 UI 槽位上。配置方式(iterate.config.yaml 与审查维度)与迭代生态的另外两个组件(技能 / 无头引擎)完全一致,迁移零成本。
📑 目录
✨ 特性
两种运行模式
插件与生态其他组件运行同一套 iterate 引擎,要么完全只读、要么作为自治修复闭环:
- dry-run(只读) — 反复多维度审查直到收敛,零文件修改。
- normal(自治) — 审查 → 原子修复 → 每轮验证 → 失败回滚 → 循环直到收敛。
两种模式共通:
- 多轮收敛反复审查
- 并行维度评审
- 确定性聚合 / 去重 / 排序
- meta-review 报告一致性审计
- 达标自停
- 断点保存 / 恢复(长迭代续跑)
normal 模式额外提供:
- 只修改 atomic 问题(architectural 问题保留待后续批准)
- 每轮修复后验证
- 修复失败自动回滚
UI 层(客户端免构建槽位,v3.12:12 个页签,双语)
- 收敛看板
ConvergenceDashboard(conversation.input.dock)— 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图;normal 模式另显示修复计数徽章;还有运行阶段芯片(当前工作流阶段 + 运行中/已结束)与 task_mode 指示器(code / iterate)。运行期间看板切换为"运行中"状态(显示轮次与阶段),并隐藏启动按钮。 - 运行时观测台
ObservatoryPanel(conversation.input.dock)— 输入框下方十二个页签运行时观测台:实时活动流(默认页,支持按活动类型筛选)+ F1 审查线程(全部展开/全部收起)、F2 收敛趋势(含跨轮对比表:每轮 findings / fixed / 严重度分布 / 验证结果;v3.16 新增跨会话对比:把当前运行存为对比基准,下次运行一键与基准对比,逐项并排 + 带方向的差值着色,v3.17 新增「复制对比表」:把并排表复制成 Markdown 表格,可直接粘贴进 PR / issue / CI 注释)、F3 发现定位(按严重度/维度/关键词筛选)、F4 修复与回滚、F5 断点恢复、F6 运行控制台、F7 决策时间线(按类型/轮次筛选与关键词搜索)、F8 质量门禁(查询 / v3.17 一键重算——compute载荷里每维度每轮的收敛序列直接从当前会话 transcript 推导,无需再手写findingsByRoundJSON)、F9 经验银行、F10 防御事件、F11 开跑预检。数字键快捷键:1–9跳到 F1–F9,0到 F10,-回实时活动流(F11 仅点击进入)。F8/F9/F10 为实时数据——扫描会话流中最近一次iterate_quality_gate/iterate_experience/iterate_defense_events结果并渲染真实数据(PASS/FAIL 徽章 + 分维度评分条、经验条目(含采纳按钮 + 客户端搜索)、防御类型计数芯片 + 筛选后的事件流);会话流中没有数据时区分"磁盘无数据"与"尚未拉取",并提供拉取磁盘快照指令(让模型调用只读工具、把.iterate/产物回显进会话流)。一键导出全部观测数据为 JSON——manifest + live +qualityGate/experienceBank/defenseEvents/report(优先下载,失败回退复制)。v3.9 新增报告导出按钮(导出报告 / 导出 SARIF,v3.11 新增导出 JSON 报告),与iterate_report工具共用同一份数据模型——分别产出可直接粘贴进 PR 的 Markdown 运行报告、供 CI / GitHub Code Scanning 消费的 SARIF 2.1.0 日志,以及(v3.11)完整的归一化运行模型 JSON(无损格式)。v3.5.3 新增重置操作:F5 复制iterate_checkpoint clear、F8 复制iterate_quality_gate clear、F10 复制iterate_defense_events clear指令。v3.12 新增开跑预检(Preflight)——F11 渲染会话流中最近一次iterate_preflight清单(验证命令是否配置 / 是否 Git 仓库 / 脏工作区 / 陈旧 FAIL 门禁 / 中断断点),每个 warn/fail 行都给出精确的修复指令(配置validation.commands、清除陈旧门禁、恢复断点),让环境在花掉一轮之前就被修好;空态提供运行预检指令(让模型调用iterate_preflight)。v3.13:阻断的验证命令行自动检测项目 manifest,提供一键「应用建议」(复制iterate_config的operation:"write"指令,携带完整validation.commands.default载荷)。 - Findings 分诊面板
TriagePanel(conversation.chat.turnTail)— 逐条分诊,键盘快捷键y(保留→修复)、n(跳过)、a(已知有意)与↑/↓移动(焦点守卫:仅面板内焦点时生效),支持筛选、批量(含一键全选所有 findings)、localStorage 持久化。写回闭环:主按钮复制已标记条目的iterate_triage apply指令(工具负责校验、去重、备份、失败回滚);次按钮复制裸known_intentionalYAML;回读已写入条目复制iterate_triage list指令核对实际落盘内容。复制载荷与目标工具 schema 对齐。v3.2:原生命令按钮(批准架构修复、触发新一轮、回滚到断点)。 - 收敛统计卡片
StatsCard(conversation.chat.turnTail)— 无 findings 时显示收敛统计、历史轮次、趋势图、完成摘要。 - iterate 主题皮肤(
theme.overrideTokens)— 暖琥珀配色的 13 个--dsw-*token 覆盖,明暗双模式,可在设置页开关。 - 进度胶囊
ProgressCapsule(shell.overlay)— 每轮完成 / 收敛时右下角弹出通知(含收敛确认)。 - iterate 设置区
SettingsPanel(settings.section)— 主题开关、分诊持久化说明、配置管理指引(覆盖validation.commands/language/personalization.known_intentional,并显式警告"validation.commands 为空 = 本轮不受任何测试保护";字段选择器可生成对应的iterate_config write指令),v3.7:新增「回读当前配置」补齐写入 → 回读闭环——复制iterate_config read指令,模型把结果回显进会话后,卡片就地展示所选字段的当前值;运行时状态概览(产物布局 + 查看/清理工具指引 + 磁盘快照拉取)、一键清空分诊数据。v3.18:新增设置页导航图标(settings.section.icon,dsh 0.2.2-rc.1 插件面能力)——与设置面板同id,dsh 壳层在设置导航以 iterate 循环箭头替换默认字形,卸载自动恢复。 - 移动端合规响应式(v3.18,官方
dsh-responsive-ui)——面板在触屏/窄屏不再破:hover 效果全部门控到@media (hover: hover)(触屏点击无残留高亮)、粗指针下文本输入/文本域 16px 地板(防 iOS 聚焦缩放)、超长 mono 载荷overflow-wrap: anywhere、480px 以下松弛最小宽度并收紧内边距(满足 390px 最小视口不溢出)。 - 双语 UI(v3.7)——所有界面文案(面板、空态、页签、徽标、设置、停止原因与完成汇总)均提供简体中文与 English。在设置 → 界面语言 / Interface language切换;选择持久化在
localStorage(iterate-ui-lang),否则按navigator.language自动探测(已保存的选择始终优先,且自动探测不会写入偏好)。面向模型的文案有意保持中文——build*Instruction指令与可粘贴指引是与SKILL.md对齐的契约文本,因此两处展开的指引带「中文(粘贴给模型的契约文案)」标签,避免被误当成漏翻。 - 右键菜单(v3.14,dsh ≥ 0.2.2-alpha.3)——iterate 入口现在也挂在原生统一右键菜单上:右键侧边栏的会话可
打开 iterate 质量指挥中心(展开停靠观测台并跳到实时流)、复制预检 / dry-run / 断点恢复 / 磁盘快照指令;右键文件(带行号)/ 目录可复制定向 dry-run 审查指令(仅审查该文件/目录)。双语标签、复制失败的自救指引、共享成功 toast;宿主无contextMenus时降级为无菜单项(停靠面板仍是入口)。 - 键盘快捷键(v3.15,dsh ≥ 0.2.2-rc.1)——iterate 指挥中心现在一键可达:任意会话内按 Cmd/Ctrl+Shift+O 即可打开停靠观测台(dsh 新增的统一键盘命令能力)。快捷键注册在 dsh 的
shortcuts服务上,与右键「打开指挥中心」动作共用同一命令 id,因此右键菜单会显示实时键帽、dsh 自身的快捷键设置页也会将其列为可编辑绑定。宿主早于shortcuts服务时降级为无键盘命令(停靠面板与右键菜单仍是入口);默认绑定冲突时仅记录并跳过,绝不拖垮插件。
UI 层为防御式设计:slots / theme / React 任一不可用时自动降级,不会崩溃客户端。
工具之外的闭环行为
除 19 个注册工具(完整参考见下文)外,插件还端到端打通了几条关键闭环:
- findings 分诊闭环 — 审查 → UI 分诊(y/n/a)→
iterate_triage写回known_intentional→ 下一轮自动过滤 - 结构化修复系统 — 每次修复先备份、写注册表、记录 diff,验证失败可
iterate_rollback还原 - 断点续跑 — 长迭代在每轮开头保存 checkpoint,中断后可恢复进度
- 历史审计 —
iterate_history读取决策日志(可按type/since/round/ 修复文件file/limit过滤,默认取最新 50 条,上限 200 条)与修复注册表汇总(各轮 fixed/failed 计数,按同一 round/file 过滤收窄),审查运行过程与修复明细 - 运行时清理 —
iterate_prune清理过期的决策日志条目、陈旧断点、孤儿修复备份、空轮次与原子写入崩溃残留的临时文件;默认 dry-run 只报告不删除,显式dryRun:false才真正清理,每次清理写入决策日志 - 配置读写 —
iterate_config支持带校验、备份、回滚的局部写入;v3.7 起设置页还能回读生效配置(指令 + 就地展示当前值) - 跟随会话的工作目录(v3.7) — 在 dsh ≥
0.2.1-alpha.2上,插件通过宿主的WorkingDirectoryService解析项目根,而不是不可变的Session.header.cwd:会话中途切换目录后,.iterate/下的一切(配置、决策日志、断点、修复备份、审批策略)都会跟着当前工作区走。该服务按特性探测,任何失败路径(服务缺失/抛错/敌意 getter/非字符串结果)都回退到header.cwd,旧宿主行为完全不变。 - v3.2 经验银行 —
iterate_experience以检索 / 过滤 / 采纳查阅历史修复与模式,并可add持久化新的已验证修复——重复添加同一 pattern + dimension 时累加命中次数而非重复写入 - v3.2 质量门禁 —
iterate_quality_gate读取质量门禁状态(各维度收敛率 + PASS/FAIL),并可基于本轮 findings / 验证结果compute重新计算并持久化一份新的质量凭证(收敛率来自findingsByRound的真实收敛序列) - v3.2 防御事件流 —
iterate_defense_events查询防御事件(前置条件失败、回滚、不变量违反、假设证伪),并可record记录新事件;可读标签跟随项目语言(en / zh)
📦 安装
从 npm 安装
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 独立仓库 维护仓库根即插件的发布位,由主仓库通过 git subtree 同步,内容与 npm 包一致:
dsh plugin --profile web add "github:jingzhao-l/iterate-plugin#main"
安装完成后需重启 dsh 服务(建议 dsh web --patch)并刷新页面,宿主与客户端 UI 层才会加载。
本地开发 / 源码挂载
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 添加:
- insert:
- id: iterate-plugin
name: 'iterate-plugin'
插件包自带
dsh.bundle.patch(即cordis.patch.yml),npm 包内files已白名单化(src/lib/dist/cordis.patch.yml/README.md/README.zh-CN.md/LICENSE)。其中dist/为 TypeScript 服务端逻辑的编译产物,随包分发以兼容 dsh 的github:owner/repo#refgit-clone 安装方式(Node 不擦除node_modules下的 TS 类型)。
🧭 在 dsh 中使用 UI
浏览器客户端没有文件系统访问权限——所有面板渲染的都是 dsh 会话流里的数据(模型回显的工具结果)。因此本插件的 UI 围绕一个交互范式构建:从按钮复制指令 → 粘贴回对话 → 模型调用对应工具 → 面板自动填充。客户端按钮从不启动任何进程。
启动一次迭代(空态仪表盘)
还没有任何 report 时,收敛看板显示两个按钮——「完整迭代」与「仅评审」——各自把一段自然语言指令复制到剪贴板。这些不是 slash 命令:插件没有注册 /iterate 之类的命令;把文本粘贴进对话即可,模型会通过 dsh 的 workflow 工具运行 iterate 工作流。完整迭代指令还要求模型先预检 validation.commands——若未配置则停下来提示你写入(与工作流自身的 fail-closed 规则一致),不受测试保护的迭代绝不会看起来"全绿"。
运行期间,看板切换为运行中状态(显示轮次与工作流阶段芯片),并隐藏启动按钮。
分诊面板快捷键
快捷键只在分诊面板内焦点时生效(在别处输入时处理器会忽略):
y— 保留该 finding(进入修复);n— 跳过;a— 标记为已知有意(写回候选)↑/↓— 在 findings 之间移动(判定后自动前进)- 批量按钮
y/n/a一次性对全部 findings 应用同一判定
要写回配置,用 a 标记条目后点击生成应用指令——它会为这些条目复制一条 iterate_triage apply 指令(工具负责校验、按 file|dimension|line 去重、备份、失败回滚)。粘贴回会话后,点击回读已写入条目复制 iterate_triage list 指令核对实际落盘内容——写回 → 回读闭环。
观测台页签与快捷键
输入框下方的观测台共 12 个页签:实时活动流(默认页)+ F1–F11:
F1 审查线程 · F2 收敛趋势(含跨轮对比)· F3 发现定位 · F4 修复与回滚 · F5 断点恢复 · F6 运行控制台 · F7 决策时间线 · F8 质量门禁 · F9 经验银行 · F10 防御事件 · F11 开跑预检
跨会话对比(v3.16)——F2 页签还带一个跨会话对比块:存为对比基准把当前运行摘要(轮次 / 发现 / critical+high / 修复成功 / 修复失败 / 验证通过率 / 门禁得分,持久化到 localStorage)保存下来,与基准对比把下一次运行与它并排对比,差值按「更好 / 更差」方向着色。这取代了以前「导出两份 JSON 手工并排对比」的繁琐做法;损坏 / 过期的已存基准读作「无基准」,绝不变成幽灵运行。
按 1–9 跳到 F1–F9,0 到 F10,- 回实时活动流。
磁盘快照拉取与导出
- 拉取磁盘快照——新会话(或刷新后)面板是空的,哪怕磁盘上
.iterate/早有产物。拉取按钮复制一条指令,让模型调用只读工具(iterate_status、iterate_transcriptread、iterate_quality_gateread、iterate_experiencelist、iterate_defense_eventslist、iterate_history)并把完整结果回显进会话流;会话扫描器随之填充看板、F2、F5、F8、F9、F10。空态文案区分"磁盘无数据"与"尚未拉取"。 - 导出 JSON——一键把整个观测台序列化为 JSON:manifest + 实时流 +
qualityGate+experienceBank+defenseEvents+report(优先下载,失败回退复制到剪贴板)。
从设置页管理配置
设置区复制一份配置编辑指引,列出支持的 iterate.config.yaml 字段——包括 validation.commands(并显式警告:留空意味着每一轮迭代都不受任何测试保护)——并提供字段选择器:选中字段后,按钮会生成对应的 iterate_config write 指令(schema 校验、自动备份、失败自动回滚)供你粘贴回会话。
回读实际写入的结果——配套的**「回读当前配置」**按钮复制 iterate_config 的 { operation: "read" } 指令;模型把结果回显进会话后,卡片会在选择器下方展示所选字段的当前值(数组内联展示,如 ["npm test","npm run lint"])。三种状态被诚实区分:尚未回读、当前值、已回读但没有该字段(说明走的是内置默认值)。若剪贴板被拒绝,回读指令会在面板中展开供手动复制——按钮不会成为死路。
💬 使用
dry-run 模式(纯反复审查,不修改文件)
当你想要"只是反复审查,不修改文件",prompt 示例:
dry-run review this project, find all issues across all dimensions
插件会自动触发 iterate 工作流:
plan→ 读取配置,生成评审计划loop→ 每轮并行评审,只找新问题 → 确定性聚合去重 → 统计收敛 → 无新问题则停止meta-review→ 审计报告一致性report→ 输出最终结果
normal 模式(自治闭环迭代)
当你想要"iterate this project / fix the issues found",prompt 示例:
iterate on this project, fix all atomic issues
工作流:
plan→ 读取配置loop→ 并行评审 → 聚合去重 → 原子问题并行修复 → 执行验证命令 → 验证失败则回滚 → 记录日志 → 无新问题则停止report→ 输出修复统计
⚙️ 项目配置
在项目根目录放 iterate.config.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工具读取与校验式局部写入(自动备份,写入失败自动回滚)。
🔧 注册工具(19 个)
iterate_config— 读取 / 写入iterate.config.yaml。operation=read返回完整配置或指定 section;operation=write做 schema 校验、备份后局部合并写入,失败自动回滚;v3.13 新增operation=detect——读取项目 manifest(package.json 脚本 / pytest / Cargo / Go / Make),自动提出一份可直接应用的validation.commands.default命令集(apply:true一键写入,已配置时需force:true才覆盖)iterate_validate— 运行白名单验证命令,返回结果iterate_decision_log— 追加决策日志(只追加,不改旧),存储于.iterate/decision-log.jsonliterate_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读回,resume加载并累加恢复计数(中断恢复),clear清除(findings 载荷有上限,强制round ≤ maxRounds)。长迭代可中断续跑iterate_status— 汇总当前迭代状态:模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint;v3.4:同时返回持久化的质量门禁快照、经验银行摘要与防御事件摘要(qualityGate/experienceBank/defenseEvents)iterate_history— 读取迭代历史(只读):决策日志条目(可按type/since/round/ 修复文件file/limit过滤,默认取最新 50 条,上限 200 条)+ 修复注册表汇总(各轮 fixed/failed 计数,按同一 round/file 过滤收窄;file过滤时按保留的记录重算计数)。用于审查运行过程、审计日志、盘点修复iterate_prune— 清理运行时产物:过期决策日志条目(按retainDays,默认 30 天)、陈旧断点、孤儿修复备份、空轮次、崩溃原子写入残留的临时文件。默认 dry-run 只报告不删除;dryRun:false才真正清理,每次清理写入决策日志iterate_transcript— 运行时观测台:把审查转录、线程、修复与 nudge 指令持久化到.iterate/transcript.json,供客户端观测台读取。v3.9:read在文件丢失/损坏时从会话日志的运行记录恢复出一份摘要 manifest(recovered:true);capture把本次运行关联到 dsh 会话(sessionRecord);recall列出本会话的运行记录(最新在前)iterate_experience— v3.2 查询经验银行(list / search / get),或add一条新的已验证修复:重复添加同一 pattern + dimension 累加命中次数而非重复写入。v3.5 新增remove:按id删除过时或错误的经验条目。持久化到.iterate/experience.jsoniterate_quality_gate— v3.2 读取质量凭证(read),或基于 findings、验证结果、findingsByRound与fixedByDimension重新计算并持久化一份新凭证(compute)。真实的逐维度收敛率。v3.5 新增clear:删除持久化的质量凭证,用于新一轮迭代前重置陈旧的门禁iterate_defense_events— v3.2 查询防御事件(list / counts),record记录一条新事件,或 v3.5.3clear清除持久化事件流,让新一轮迭代不带陈旧防御数据起跑。可读标签跟随项目语言(en / zh)iterate_report— v3.9 把本次运行导出为可移植报告。format:"markdown"(默认)产出可直接粘贴进 PR 的报告(运行头部、质量门禁、发现、修复、验证、防御事件、经验银行);format:"sarif"产出 SARIF 2.1.0 日志供 CI / GitHub Code Scanning 消费(每个审查维度一条规则,严重度 → error/warning/note,携带文件+行号位置与建议修复)。v3.11:format:"json"产出完整归一化运行模型为机器可读 JSON(发现、修复、验证、收敛率、质量门禁、经验银行、防御事件——供 CI 仪表盘 / PR 机器人消费的无损格式)。write:true持久化到.iterate/report.md/.iterate/report.sarif/.iterate/report.json;lang(zh | en)选择报告语言。除可选的报告文件外均为只读iterate_preflight— v3.12 开跑前只读预检。返回结构化清单:validation.commands是否已配置(为空意味着本轮无法证明修复——阻断项)、是否 Git 仓库、多少个未提交文件、磁盘上是否残留 FAIL 质量门禁、是否有中断断点在等待。每项都携带结构化事实({ id, status: pass|warn|fail, detail }),观测台 F11 面板据此本地化为一句话并给出精确修复指令。v3.13:未配置时自动检测项目 manifest,把suggestedCommands/ecosystem/detectedFrom附到阻断项,F11 据此提供一键「应用建议」。绝不修改配置、文件或产物
📁 运行时产物布局
所有运行时状态都落在项目根目录的 .iterate/ 下(可由 .gitignore 排除):
.iterate/
decision-log.jsonl # 追加式决策日志(plan/review/fix/revert…)
checkpoint.json # 迭代断点(断点续跑)
transcript.json # 运行时观测台清单(各 reviewer 线程、趋势、修复、时间线、nudge)
transcript-live.ndjson # 追加式近实时 reviewer 活动流(read/fix/rollback/validate…),带字节上限
experience.json # v3.2:经验银行(跨会话积累的历史修复与模式)
quality-gate.json # v3.2:质量门禁快照(维度收敛率、验证通过率、PASS/FAIL)
defense-events.json # v3.2:防御事件流(前置条件失败、回滚、不变量违反、假设证伪)
fixes/
registry.json # 修复注册表(FixRecord 列表,按轮次组织)
<fix-id>_<ts>.bak # 每次修复前的原文件备份
🔐 权限、依赖与兼容性
Node.js / DSH 兼容范围
- Node.js:
>=20(package.json的engines.node)。 - DSH:
package.json的dsh.compatibility.dshReleases字段是发布兼容性的唯一真源(本 README 逐字镜像该字段;两者需同步更新)。以下官方版本声明为compatible:0.1.1-rc.1、0.1.2-alpha.4、0.1.2-alpha.5、0.1.2-rc.1、0.1.3-alpha.1、0.1.5-alpha.1、0.1.5-alpha.2、0.1.5-rc.1、0.1.5-rc.2、0.1.6-alpha.1、0.1.6-alpha.2、0.1.7-alpha.1、0.1.7-alpha.2、0.1.7-rc.1、0.1.7-rc.2、0.2.0-rc.1、0.2.0-rc.2、0.2.1-alpha.1、0.2.1-alpha.2、0.2.1-alpha.3、0.2.1-alpha.4、0.2.1-alpha.5、0.2.1-rc.1、0.2.1-rc.2、0.2.1-rc.3、0.2.1-rc.4、0.2.1-rc.5、0.2.2-alpha.2、0.2.2-alpha.3、0.2.2-rc.1(共 30 个版本,0.1.1-rc.1…0.2.2-rc.1)。插件基于@deepseek-ai/dsh-tools/@deepseek-ai/dsh-util-values0.2.2-rc.1构建,只使用公开契约(工具注册、客户端 slots + theme、bundle patch,以及 v3.9 起的会话状态记录接口)。插件同时声明engines.dsh(>=0.1.1-rc.1),使 dsh ≥ 0.2.2-rc.1 运行时只依据该范围判断兼容性(更早的运行时仍回退校验package.json中列出的@deepseek-ai/dsh-*peer 版本)。 - 一次性 Profile 证据(真实,
dshCLI0.1.1-rc.1):在临时$DSH_HOME下dsh plugin --profile <p> add <本仓库>约 449ms 完成安装;dsh --profile <p> --dump-config正确合成iterate-pluginbundle patch;dsh plugin --profile <p> remove iterate-plugin约 602ms 卸载完成、合成配置中不存在残留引用。完整运行时 启动未在此环境演练(一次性 Profile 无模型提供方),故dshOperations的 start/rollback 证据为unknown/partial——确切命令与耗时见CHANGELOG.md。
运行时权限(保守披露)
插件与 DSH 宿主共享同一进程能力,涉及以下能力;具备高权限意味着 DSH Profile
安装仍需 user-reviewed/守卫,不会自动放行:
- 文件(files) — 读写
<projectRoot>/.iterate/下的项目本地状态(决策日志、 检查点、transcript、修复备份/注册表、质量门禁、经验银行、防御事件)。iterate_fix/iterate_triage还会就地修改用户源码(路径遍历防护限定在解析后 的项目根目录内,每次修复前备份、失败回滚)。客户端侧把分诊判定持久化到localStorage。 - 命令(commands) — 插件的工具本身只执行一个严格受限的命令面、且仅在模型调用时
于 dsh 宿主进程内运行:
iterate_validate运行iterate.config.yamlvalidation.commands中逐条精确匹配白名单的命令(是的,经由node:child_process执行,超时上限 600 秒);iterate_review(changed-only 范围) 在项目根目录运行git diff --name-only -z <branch>。除此之外不启动任何进程。 客户端"指挥按钮"只复制可粘贴的指令文本,不启动任何进程。 - 凭据(credentials) — 本插件运行时不读取或传输凭据。同生态的 iterate-skill / iterate-harness 组件在用户自行执行 Git/API 操作时可能读取 git 凭据 / GitHub token;它们是独立包,本插件从不加载它们。
- 网络(network) — 运行时无任何网络访问(全部本地)。
依赖
运行时依赖:js-yaml(精确锁版)。本插件构建所依赖的三个 DSH 宿主模块——
@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-util-values
——已声明为可选 peerDependencies,直接复用宿主自带的那一份,避免插件内
再打包一份造成双模块实例(由 dsh 提供);同时在 devDependencies 中精确锁版,
供本地构建与测试,并与 dsh.compatibility.dshReleases 的最新条目保持一致。
上游采纳记录(v3.8.0 → dsh 0.2.1-alpha.4)
- 已采纳——
engines.dsh兼容契约。 自0.2.1-alpha.4起,dsh 运行时在声明了engines.dsh时只依据该字段(一个含预发布版本的 semver 范围)判断第三方插件兼容性, 忽略peerDependencies;未声明时才回退逐个校验精确的@deepseek-ai/dsh-*peer 版本。 插件现已声明engines.dsh: ">=0.1.1-rc.1"(与最早的dshReleases条目同下界), 使当前运行时加载时不再因精确锁版的 peer 列表被判不兼容;而所有宿主相关能力依旧 特性探测(缺少WorkingDirectoryService、ask.displayReason、ctx.jobs等一律 降级到安全回退)。更早的运行时仍走@deepseek-ai/dsh-*peer 版本,已扩展至0.2.1-alpha.4。 0.2.1-alpha.3/0.2.1-alpha.4其余均为宿主级变更——Web 登录、密钥/令牌脱敏、 极简模式读图、/compact、插件热重载、自定义插件索引源、按模型配置推理等级 UI。 都未暴露本插件消费的 tool/agent/session API(defineTool、JsonValue、exec.*、tools/pre-execute、presentCall),本轮无需进一步采纳。- 五个
@deepseek-ai/*包全部精确锁到0.2.1-alpha.4(@deepseek-ai/cordis保持4.0.5-alpha.2)。
上游采纳记录(v3.7.0 → dsh 0.2.1-alpha.2)
- 已采纳——可变的会话工作目录。
src/working-directory.ts通过ctx.get('workingDirectory').get(session)解析项目根(特性探测;服务缺失、 抛错、敌意 getter 或非字符串结果一律回退header.cwd)。必须采纳的原因: 自0.2.1-alpha.2起,不可变的 header 按设计保留原始项目,切换目录后再读它 会把评审锚定到错误的检出。 - 已评估、未采纳:
- Session 状态记录接口(实验插件读写自己的会话记录)——依赖 shell 内部记录结构,
跨 alpha 版本极脆弱;iterate 的跨会话状态本就存放在
.iterate/。 - 共享 agents 目录的
AGENTS.md(DSH_AGENTS_HOME)——属于宿主的全局指令机制, 插件注入的是自己的工作流提示词。 - 实验性 Git Worktrees 插件——上游的 agent 工作流特性;插件自己的
git.use_worktree配置早于它,且是另一回事(iterate 循环的逐轮 git 卫生)。 - 移除
both混合展示模式——插件从未设置展示模式(用的是presentCall卡片), 无需迁移。 - 从插件全局安装 dsh CLI——运行时从不 shell 调用,纯占磁盘。
- Session 状态记录接口(实验插件读写自己的会话记录)——依赖 shell 内部记录结构,
跨 alpha 版本极脆弱;iterate 的跨会话状态本就存放在
- 五个
@deepseek-ai/*包全部精确锁到0.2.1-alpha.2(@deepseek-ai/cordis保持4.0.5-alpha.1)。无安装期生命周期脚本 (preinstall/install/postinstall/prepare);仅prepublishOnly(构建)在发布时运行。
失败边界
- 所有写入都是原子的(临时文件 + rename),且限定在
.iterate/下;写入中途崩溃 不会损坏 checkpoint / transcript。 - 持久化失败以结构化
{ ok: false, error }返回,而不是静默成功。 - 修复编辑先备份再应用,验证失败自动回滚。
- 某个 slot / 服务不可用时 UI 优雅降级。
🎨 设计
插件遵循 dsh "everything-is-a-plugin" 架构:
- 只做两件事 — 注入系统 prompt 教模型写 iterate workflow + 注册 19 个纯函数工具
- 所有 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-*令牌,缺服务自动降级 - v3.2 质量指挥中心 — 把插件从"被动观察面板"升级为"主动指挥中心 + 知识库"——质量门禁(读 + compute)、经验银行(读 + add)、防御事件(读 + record)与原生指挥按钮
- 遵循 iterate 原技能的设计原则:确定性收敛,可审计,最小权限
🧪 运行测试
cd harness/iterate-plugin
npm install
npm run typecheck
npm test
所有测试通过:
- 全量单元测试 + 类型检查通过(
npm test、npm run typecheck——此处刻意不写具体数量以根除文档漂移,各版本量级见CHANGELOG.md) - 覆盖:去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制、配置读写与回滚、triage 合并、diff 计算、checkpoint 校验、修复注册表、历史读取与过滤、prune 清理报告与 dry-run 语义、UI 纯函数(select-all 键、运行时状态指引)、v3.2:经验银行、质量门禁、防御事件、审批门禁 fail-open 路径、v3.9:可移植报告(markdown + SARIF)、**v3.11:无损 JSON 报告(完整归一化运行模型 +
.iterate/report.json持久化)**等
⚠️ 免责声明与许可
免责声明
本项目按「现状」(AS IS)提供,不附带任何明示或暗示的担保,包括但不限于对适销性、特定用途适用性及不侵权性的担保。
自动化的代码审查与修复存在固有风险。 normal 模式下产生的改动均由 AI 模型生成,可能引入缺陷、回归或非预期行为。在合并改动前,你应当:
- 在应用到主分支或推送前,逐条 review 每一处 diff。
- 确保项目处于 git 版本控制之下,并可随时回滚(
git restore、revert 或从备份恢复)。 - 在每轮修复后运行项目自身的测试与构建检查。
- 切勿在密钥、凭证、
.env或任何不允许修改的文件上运行本项目;请在配置中设置protected_paths予以保护。
使用者需为本项目使用过程中所产生、修改或提交的代码负全部责任。使用本项目即表示你同意:维护者与贡献者不对因使用本项目而导致的任何损失、损害或法律后果承担责任。
License
MIT
链接
同类插件
loopx-project/loopx#dsh-loopx-plugin★ 6581
LoopX——面向长周期 Agent 的提供商中立、本地优先状态内核与控制平面:在 DeepSeek Harness 执行层之上持久化 Goal、Todo、门禁、证据、配额、恢复与交接状态;插件负责引导安装 CLI 与技能、准入有界的同会话续跑,并为精确绑定的工作循环提供本地 GoalBar。
Q00/ouroboros#integrations/dsh-plugin★ 6361
通过 DSH MCP 客户端挂载 Ouroboros 的纯配置包,在 DSH 中提供 36 个涵盖需求访谈、Seed、执行、评估与演化流程的工具。
chuspeeism/dashi-taskboard#deepseek-harness★ 3485
把当前已安装并运行中的 Codex Taskboard 嵌入 DeepSeek Harness 侧边栏,并通过 Launcher 运行时描述文件连接,而不是使用固定端口。
NanmiCoder/dsh-agent-teams★ 2927
AgentTeams 多智能体团队。
EthanYoQ/AI-Novel-Writer#dsh-ai-novel-writer★ 2621
安装专用 AI 小说创作预设与工作台:提供带修订号的本地项目资产、紧凑侧边工作台,以及需要原生审批的逐文件变更。
shanliuling/dsh-image-gen★ 1479
为 DeepSeek Harness 提供原生对话生图能力:直接让 Agent 画图,插件自动完成生成并把结果保留在当前会话中。
社区评论
评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。