dsh-change-impact

dsh plugin --profile web add dsh-change-impact

dsh-change-impact

[English](README.md) | 简体中文






面向 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）。

**

…(truncated)