dsh-change-impact
Verifieddsh-change-impact · v0.1.0 · MIT
Evidence-backed change impact analysis and verification plans for DeepSeek Harness.
Install
dsh plugin add dsh-change-impact Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
dsh-change-impact
English | 简体中文
面向 DeepSeek Harness 的变更影响分析插件：把一次代码变更提升为证据支撑的影响分析与验证计划（CHANGE-IMPACT.md + change-impact.json）。
Turn a code change into an evidence-backed impact and verification plan.
定位
dsh-change-impact 处理「一次变更 → 影响、风险与验证」这一步。仓库结构、符号、依赖、入口等事实由 dsh-repo-scanner（npm 依赖，不复制 scanner 源码）提供，本插件负责变更事实解析、反向传播、风险评分与报告编排。
它回答：
- 哪些模块、入口和公共导出会受这次变更影响？
- 风险有多高，证据是什么（每条等级都携带因子与置信度）？
- 应该运行哪些验证命令，而不是盲目跑全量测试？
- 是否需要同步更新文档、迁移脚本和发布说明？
边界：
- 默认只读：不修改源码、测试、文档或配置；不自动创建 commit/branch/PR。
- 不执行仓库命令：验证命令只推荐（
requires_confirmation恒为 true）；working_tree/base_head 模式仅执行白名单只读 git 查询（rev-parse / diff / status），并在报告附录披露。 - 不编造结论：不臆测运行时调用链；无测试命令时明确标记「未识别」；任何情况下不输出 fully_covered。
输出预览
# 变更影响分析
> 基线：HEAD（工作区未提交变更）
> 工具：dsh-change-impact 0.1.0；scanner dsh-repo-scanner 0.1.2
## 1. 结论摘要
- [事实] 变更文件 1 个（纳入分析 1 个），新增 +2 / 删除 -1 行；
反向传播影响 2 个文件、2 个模块。
- [推断] 最高风险等级：high（…由 docs/risk-rules.md 固定规则计算）。
- [事实] 1 个入口受影响：`src/server.ts`。
## 2. 变更范围
| `src/auth/service.ts` | 修改（modified） | +2/-1 | 源码 | `src/auth` |
## 3. 影响传播
| `src/auth/service.ts` | … | src/auth/service.ts -> src/api/routes.ts -> src/server.ts | `src/server.ts` |
## 5. 验证计划
| P0（最少集合） | `node --test` | Web/服务入口受影响…建议补充 API/集成测试 | package.json | 是 |
完整示例见 docs/risk-rules.md 的规则边界与 test/fixtures/ 的已知影响关系夹具。
安装
作为 DSH 插件：
dsh plugin --profile web add "github:duyanta123/dsh-change-impact#v0.1.0"
或从 npm 安装（作为库或独立 CLI 使用）：
npm install dsh-change-impact
兼容性分层：独立 CLI / 库要求 Node.js >= 18；作为 DSH 0.2.1-rc.2 插件验证统一使用 Node.js >= 22.19（兼容基线由 npm run test:compat 与 CI compat job 强制）。运行 npm test（Node/平台矩阵由 CI 覆盖：Windows + Ubuntu × Node 18/20/22 + DSH compat job）。
安装后重启 dsh --profile web，通过 change-impact-runbook 技能使用。
快速开始
1. 作为 DSH 技能使用
对 Agent 说「分析 /path/to/repo 这次变更的影响」并给出基线模式，技能按 runbook 执行：输入受理 → 变更事实 → 影响传播 → 风险与验证 → 报告产出，最后给出 CHANGE-IMPACT.md 与 change-impact.json。
2. 作为独立 CLI 使用
# 工作区相对 HEAD 的未提交变更（缺省模式）
node scripts/change-impact.mjs .
# 两个 Git ref 之间的变更
node scripts/change-impact.mjs . --base origin/main --head HEAD
# 显式 unified diff 文件（非 Git 目录也可用）
node scripts/change-impact.mjs . --diff change.patch
# 手工提供变更文件列表（非 Git 项目）
node scripts/change-impact.mjs . --changed-files src/a.ts,src/b.ts
# 指定输出目录并生成 Mermaid 图，警告逐条写入 stderr
node scripts/change-impact.mjs . --output reports --mermaid --strict
3. 作为库依赖
import { analyze, writeReportFiles } from 'dsh-change-impact/core';
const result = await analyze({ repo_path: '.', base: 'origin/main' });
// result 即 change-impact.json 的内容：changed_files / propagation / risks / verification
await writeReportFiles(result, { output: 'reports' });
CLI 参数
| 参数 | 默认 | 说明 |
|---|---|---|
<repo> |
. |
目标仓库路径（第一个位置参数，可省略） |
--base <ref> / --head <ref> |
- | Git ref 区间；--head 必须与 --base 同用 |
--diff <path> |
- | unified diff 文件（显式 diff 优先于 Git ref） |
--changed-files <值> |
- | 变更文件列表：存在的文件按「每行一个路径（# 注释）」读取，否则按逗号分隔列表 |
--max-depth N |
4 | scanner 目录/依赖扫描深度 |
--max-propagation N |
3 | 反向传播层数上限 |
--max-files N |
scanner 默认（2000） | scanner 扫描文件数上限 |
--include-dirs a,b |
全部 | 仅扫描这些目录（scanner 按路径前缀匹配，建议传顶层目录；可重复） |
--exclude-dirs a,b |
无额外 | 额外排除目录（按路径中的目录名段匹配；可重复） |
--include-untracked / --no-include-untracked |
是 | 是否纳入未跟踪文件 |
--include-tests / --no-include-tests |
是 | 是否把测试文件变更纳入影响分析 |
--format json|markdown|both |
both | 输出格式 |
--output <path> |
CHANGE-IMPACT.md |
无扩展名视为目录；change-impact.md 搭配同目录 change-impact.json；.json 输出搭配同名 .md |
--mermaid |
关 | 额外生成 change-impact.mmd（图不是唯一事实来源） |
--strict |
关 | 把警告与待确认项明细写入 stderr（不改变退出码） |
--help, -h |
- | 显示帮助 |
退出码：0 分析成功；1 有警告、扫描截断或低置信度结果（由 result.flags 自动映射）；2 输入缺失、Git ref 无效或目录不存在；3 scanner schema 不兼容或报告写入失败。默认覆盖已有输出文件。
输出
| 产物 | 说明 |
|---|---|
CHANGE-IMPACT.md |
固定 8 章 + 附录：结论摘要 / 变更范围 / 影响传播 / 风险清单 / 验证计划 / 测试保护与缺口 / 文档与发布影响 / 限制与待确认；事实、推断与待确认分别标注 [事实]、[推断]、[待确认] |
change-impact.json |
机器可读的分析结果对象（schema_version 1.0）：changed_files、impact 五层对象、propagation、risks、verification、test_gaps、warnings、flags |
change-impact.mmd |
可选 Mermaid 影响图；图不是唯一事实来源，表格与证据可脱离图表独立阅读 |
安全边界
- 只读承诺：分析全程不写仓库、不执行仓库自身脚本或 run_methods 命令；working_tree/base_head 模式实际执行的只读 git 查询逐条披露在报告附录。
- 规则透明：风险等级由
docs/risk-rules.md固定规则计算，每条结论携带因子、证据与置信度；分数是决策辅助，不伪装成客观真理。 - schema 契约：scanner 报告
schema_version必须是 1.x，不满足时确定性失败（退出码 3），不静默降级。 - 不覆盖保护缺失说明：本工具默认覆盖已有输出文件（PLAN §8 未定义
--force，与部分兄弟插件不同）。
与其他插件的组合
arch-doc → 描述“现在是什么”：提供架构基线与入口说明
dsh-repo-scanner → 提供统一事实、符号与依赖（本插件的 npm 依赖）
dsh-change-impact → 描述“这次改动会影响什么”：影响传播 + 风险 + 验证计划（本插件）
dsh-refactor-insight → 描述“长期哪里需要重构”：长期技术债与结构风险
dsh-test-insight → 描述“哪些行为需要测试保护”：按影响结果生成测试计划与缺口
推荐链路：先用 arch-doc 固化架构基线，再对本仓库运行 dsh-change-impact 得到本次变更的影响与最少验证集合；把 propagation.impacted_files 与 test_gaps 交给 dsh-test-insight 生成测试计划；dsh-refactor-insight 的长期债务清单可解释为什么某处影响面大。各插件只通过产物（JSON 报告）衔接，互不执行对方命令。
排障
提示「目标目录不是可用的 Git 仓库」？
working_tree/base_head 模式需要 Git 仓库；非 Git 目录改用 --diff 或 --changed-files 模式。
退出码是 1 但报告正常生成？
退出码 1 表示有警告、扫描截断或低置信度结论（如传播达到 3 层上限、changed_paths 模式无行级事实）；用 --strict 查看逐条警告，或加大 --max-propagation 后复核。
提示「scanner 报告契约校验失败」或退出码 3？
安装的 dsh-repo-scanner 版本与本插件不兼容（要求 schema 1.x）；升级 scanner 到 package.json 声明的范围（^0.1.2）。
输出路径报「报告写入失败」？
--output 指向文件内部路径（例如把文件路径当目录用）会触发退出码 3；无扩展名路径才视为目录。
分析结果里某些变更路径显示「不在扫描结果内」？
该路径可能被 scanner 的排除规则过滤或已删除（如 --exclude-dirs、二进制/生成文件）；依赖与符号事实对它缺失，结论按文件级给出。
文档
- docs/risk-rules.md — 风险评分权威规则与 fixture 固定的边界行为
- schema/change-impact-result.v1.md —
change-impact.json结果 schema（v1.0）字段契约 - src/README.md — 核心模块导览（
src/index.mjs公开 API） - skills/change-impact-runbook/SKILL.md — DSH 技能 runbook（五阶段 + 红线）
- CHANGELOG.md — 版本变更记录
- PLUGIN-MAINTENANCE.md — 本仓维护规则
- PUBLISHING.md — 发布手册
License
MIT