变更影响分析 baidd1011/dsh-code-impact

dsh-code-impact

dsh-code-impact 是一个独立的 DeepSeek Harness 插件，只做一件事：对 TypeScript/JavaScript 变更做只读影响分析。它对比一次具体的 Git 变更，临时构建反向模块依赖图，返回变更声明、受影响文件、传播路径、证据位置和排序后的候选测试。0.2.0 版本能识别 JSONC 项目配置、tsconfig.json/jsconfig.json、extends、项目引用、路径别名、package exports/imports，并在一次调用内复用未变化的快照内容。它不维护仓库索引。

dsh-code-impact 是一个独立的 DeepSeek Harness 社区插件，用于对一次具体的 TS/JS Git 变更执行只读影响分析。它临时构建反向模块依赖图，返回变更声明、受影响文件、完整传播路径、文件行号证据和排序后的候选测试。0.2.0 支持 JSONC 项目配置、tsconfig.json/jsconfig.json、extends、项目引用、路径别名、package exports/imports，并在一次调用内复用未变化快照内容。不维护长期代码地图。

Install / 安装

npm install dsh-code-impact
dsh plugin --profile demo add dsh-code-impact
dsh --profile demo --dump-config

该包通过 dsh.bundle.patch 清单字段导出 cordis.patch.yml。补丁要求配置档提供 DSH 的 tools、fs 和 subprocess 服务。它不会安装 Git 服务商或文件系统服务商。

该包通过 dsh.bundle.patch 暴露 cordis.patch.yml。补丁要求 profile 已提供 DSH 的 tools、fs 和 subprocess 服务，不会安装 Git provider 或文件系统 provider。

Tool calls / 工具调用

注册的工具是 code_impact。

已注册的工具名为 code_impact。

{"mode":"workspace"}

比较 HEAD 与当前工作树，包含已暂存的改动、未暂存的改动和未被忽略的未跟踪文件。

比较 HEAD 与当前工作树，包含已暂存、未暂存和未被忽略的未跟踪文件。

{"mode":"staged"}

比较 HEAD 与 Git index。

比较 HEAD 与 Git index。

{"mode":"refs","base_ref":"origin/main","head_ref":"feature/payment"}

校验两个引用，再比较 merge-base 到 head_ref，与常见的 Pull Request 比较语义一致。其他模式下传入 base_ref 和 head_ref 会被拒绝；引用无效时绝不会静默回退到其他版本。

插件会校验两个引用，并比较 merge-base 到 head_ref，符合常见 Pull Request 比较语义。其他模式携带引用会直接报错；无效引用不会静默回退到其他版本。

Configuration / 配置

插件加载时，所有字段都由 Schemastery 校验。

所有字段在插件加载时通过 Schemastery 校验。

gitCommand: git
maxSourceFiles: 10000
maxTotalSourceBytes: 100000000
maxFileBytes: 2000000
maxChangedFiles: 200
maxImpactedFiles: 500
maxTraversalDepth: 5
maxCausesPerImpact: 3
maxResultChars: 24000
timeoutMs: 120000
testPatterns:
- '/.test.'
- '/.spec.'
- '/__tests__/'
- '/test/'
- '/tests/'
excludePatterns:
- '/node_modules/'
- '/dist/'
- '/build/'
- '/coverage/'
- '/.git/'
maxSourceFiles 和 maxTotalSourceBytes 保护仓库级扫描。超过限制时返回 CODE_IMPACT_REPOSITORY_TOO_LARGE，不会给出部分报告。maxFileBytes 阻止单个源码文件进入解析器；报告会带上警告，并标记为不完整。maxChangedFiles、maxImpactedFiles、maxCausesPerImpact 和 maxResultChars 限制返回的呈现结果。报告保留总数，并在结果数组或传播原因被缩短时包含 truncation。

maxSourceFiles 和 maxTotalSourceBytes 保护仓库级扫描；超过时返回 CODE_IMPACT_REPOSITORY_TOO_LARGE，不会伪造部分完整结果。maxFileBytes 阻止单个超大源码进入解析，报告会包含 warning 并标记不完整。maxChangedFiles、maxImpactedFiles、maxCausesPerImpact 和 maxResultChars 限制返回结果；截断时保留总数并返回 truncation。

Result / 结果

规范结果包含 kind: "code-impact-report"、complete、comparison、summary、changes、impacts、tests 和 warnings 字段。每个 impact 包含路径、关系、遍历距离，以及至少一个证据位置，位置带从一开始计数的行号。V0.2 新增 impacts[].causes，每个 cause 记录其变更文件来源，以及有界的逐边传播路径。对不需要完整追踪的调用方，现有的顶层 impact 字段仍是最短主路径。测试候选现在包含变更的测试文件，以及确定性的 reason，例如 changed-test、direct-symbol、direct-module 或 transitive。

关系类型只有：changed、symbol-import、module-import、reexport、dynamic-import 和 transitive。工具不会生成没有规则依据的风险分数。

解析器使用 TypeScript Compiler API，支持 .ts、.tsx、.mts、.cts、.js、.jsx、.mjs 和 .cjs 扩展名。它能识别静态 import/export、字符串字面量动态 import、CommonJS require、声明范围、常见 tsconfig 路径别名、仓库配置表示的项目引用，以及快照中可见的包元数据。基线和目标快照分别解析，因此删除的声明和旧引用位置仍可检查。

解析器使用 TypeScript Compiler API 支持上述八种扩展名，识别静态 import/export、type-only import/export、默认和 namespace import、字符串形式的动态 import、CommonJS require、声明范围、JSONC 配置、extends、references、项目归属、路径别名和快照中可见的 package exports/imports 元数据。基线和目标快照分别建图，因此删除的声明和旧引用者仍可被定位；未变化 blob 的解析结果在同一次调用内复用。

Safety and limitations / 安全边界与限制

- 工具只通过 DSH 服务读取 Git 元数据/对象和文件。它从不检出、写入索引、创建工作树、运行测试、编辑文件，也不访问网络。
- Git 通过 argv 调用，从不经过 shell。Ref 用 rev-parse --verify --end-of-options 校验。
- 非 TS/JS 文件仍保留在 changes 中，但不会得到编造的符号级 impact。
- 解析到工作区之外的符号链接、二进制文件、子模块、未解析的相关 import、格式错误的项目配置，以及遍历限制，都会变成显式警告，并将 complete 置为 false。
- 0.2 版本仍不包含 LSP、调用图、跨语言分析、持久化索引、PR 平台 API、测试执行、风险评分或专用 Web 面板。

- 工具只通过 DSH service 读取 Git 元数据、Git 对象和文件，不 checkout、不写 index、不创建 worktree、不执行测试、不修改文件、不访问网络。
- Git 使用 argv 调用，不经过 Shell；引用通过 rev-parse --verify --end-of-options 校验。
- 非 TS/JS 文件仍出现在 changes，但不会伪造符号级影响。
- 越界符号链接、二进制文件、子模块、相关路径上未解析的 import、无法解析的项目配置和传播深度限制都会形成显式 warning，并令 complete: false。
- 0.2 版本仍不包含 LSP、调用图、跨语言分析、持久化索引、PR 平台 API、测试执行、风险评分或专用 Web 面板。

Compatibility / 兼容版本

初始包的目标版本：

- Node ^22.19.0 || >=24.0.0
- @deepseek-ai/cordis 4.0.1
- @deepseek-ai/dsh-fs 0.0.1-rc.1
- @deepseek-ai/dsh-subprocess 0.0.1-rc.1
- @deepseek-ai/dsh-tools 0.0.1-rc.1

这些 DSH peer 版本刻意固定为精确版本。升级 DSH 时必须更新 peer 版本并运行兼容性矩阵，然后才能发布新插件版本。

本版本目标兼容 Node ^22.19.0 || >=24.0.0、Cordis 4.0.1 以及 npm 当前发布的 DSH 0.0.1-rc.1 的 fs、subprocess、tools 接口。DSH peer 版本刻意固定；升级 DSH 时必须先更新 peer 版本并运行兼容性矩阵，再发布新插件版本。

Development / 开发

npm run typecheck
npm test
npm run build
npm pack --dry-run

仓库 CI 在 Windows、Linux 和 macOS 上运行同样的检查，使用 Node 22.19 和 Node 24。发布前应把 tarball 安装到临时 DSH profile，执行 dsh --profile <name> --dump-config，真实调用一次 code_impact，并验证 dsh plugin add/remove。

发布前应把 tarball 安装到临时 DSH profile，执行 dsh --profile <name> --dump-config，真实调用一次 code_impact，并验证 dsh plugin add/remove。

Model Experience

Code impact tool result

What the model sees

工具返回一份紧凑摘要，后面跟着 changes、带证据的受影响文件，以及候选测试。规范 JSON 结果仍可供 Code Mode 调用方使用。

Token effect

结果受 maxResultChars 限制；被省略的数组计入 truncation，complete 变为 false。

KV Cache effect

每个工具结果的内容相互独立；不会改动会话系统提示词。

Migration from 0.1 / 从 0.1 迁移

工具参数和已有顶层报告字段保持不变。自行构造报告 fixture 的调用方需要为 impact 增加 causes、为测试候选增加 reason、为 warning 增加 severity。TestCandidate.relationship 现在允许 changed，因此变更中的测试可以被明确推荐。maxCausesPerImpact 默认值为 3。

工具参数和已有顶层报告字段保持不变。自行构造报告 fixture 的调用方需要为 impact 增加 causes、为测试候选增加 reason、为 warning 增加 severity。TestCandidate.relationship 现在允许 changed，因此变更中的测试可以被明确推荐。maxCausesPerImpact 默认值为 3。

Known Limitations and Deferred Work

- Repository semantics — TypeScript 解析基于快照，偏保守；不常见的自定义 loader 或生成的虚拟模块可能仍无法解析。
- Scale — 实现受配置限制，刻意不设上限，也不复用跨调用的持久化索引。
- 语言覆盖范围 — 初始版本只分析 TS/JS 模块关系。