.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`（共 29 个版本，`0.1.1-rc.1` … `0.2.2-alpha.3`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.2-alpha.3` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch，以及 v3.9 起的会话状态记录接口）。插件同时声明 `engines.dsh`（`>=0.1.1-rc.1`），使 dsh ≥ 0.2.2-alpha.3 运行时只依据该范围判断兼容性（更早的运行时仍回退校验 `package.json` 中列出的 `@deepseek-ai/dsh-*` peer 版本）。
- **一次性 Profile 证据（真实，`dsh` CLI `0.1.1-rc.1`）**：在临时 `$DSH_HOME` 下
`dsh plugin --profile add <本仓库>` 约 449ms 完成安装；`dsh --profile
--dump-config` 正确合成 `iterate-plugin` bundle patch；`dsh plugin --profile
remove iterate-plugin` 约 602ms 卸载完成、合成配置中不存在残留引用。完整运行时
启动未在此环境演练（一次性 Profile 无模型提供方），故 `dshOperations` 的
start/rollback 证据为 `unknown`/`partial`——确切命令与耗时见 `CHANGELOG.md`。
### 运行时权限（保守披露）
插件与 DSH 宿主共享同一进程能力，涉及以下能力；具备高权限意味着 DSH Profile
安装仍需 `user-reviewed`/守卫，不会自动放行：
- **文件（files）** — 读写 `/.iterate/` 下的项目本地状态（决策日志、
检查点、transcript、修复备份/注册表、质量门禁、经验银行、防御事件）。
`iterate_fix` / `iterate_triage` 还会就地修改用户源码（路径遍历防护限定在解析后
的项目根目录内，每次修复前备份、失败回滚）。客户端侧把分诊判定持久化到 `localStorage`。
- **命令（commands）** — 插件的工具本身只执行一个严格受限的命令面、且仅在模型调用时
于 dsh 宿主进程内运行：`iterate_validate` 运行 `iterate.config.yaml`
`validation.commands` 中**逐条精确匹配白名单**的命令（是的，经由
`node:child_process` 执行，超时上限 600 秒）；`iterate_review`（changed-only 范围）
在项目根目录运行 `git diff --name-only -z `。除此之外不启动任何进程。
客户端"指挥按钮"只复制可粘贴的指令文本，不启动任何进程。
- **凭据（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 调用，纯占磁盘。
- 五个 `@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` 树 + 注入 `
