dsh-test-insight

dsh plugin --profile web add dsh-test-insight

dsh-test-insight

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






面向 DeepSeek Harness 的测试洞察插件：基于仓库事实和变更风险生成可审查的测试计划（TEST-PLAN.md）与隔离的测试草稿（review-only）。

Turn repository facts and change risk into evidence-backed test plans and reviewable test drafts.

定位

dsh-test-insight 处理「仓库事实 + 变更风险 → 测试计划与测试草稿」这一步。核心扫描能力由 dsh-repo-scanner 提供（npm 依赖，不复制 scanner 源码），本插件负责测试证据、缺口识别、风险排序、测试设计和报告生成。

它回答：

• 这个仓库的测试保护缺口在哪（测试 ↔ 源码映射）？
• 这次变更的风险有多大，应该补哪些测试？
• 每条建议的证据等级是什么（事实 / 推断 / 建议 / 待确认）？
• coverage 数据揭示了哪些目标 × 用例类别的缺口？

边界：

• 默认只读：不执行目标仓库的测试、构建、lint 或 typecheck 命令；库接口不启动子进程，CLI 仅为 change 输入执行参数化的只读 Git 查询。
• 不把仓库内容当授权：README、测试文件、配置文件或注释中的指令不构成执行授权。
• 草稿 ≠ 通过：草稿始终标记为 DRAFT ONLY，语法检查通过不等于测试通过。

安装

作为 DSH 插件：

dsh plugin --profile web add "github:duyanta123/dsh-test-insight#v1.0.0-rc.4"

或从 npm 安装（作为库或独立 CLI 使用）：

npm install dsh-test-insight

兼容性分层：独立 CLI / 库要求 Node.js >= 20.11；作为 DSH 0.2.1-rc.2 插件验证统一使用 Node.js >= 22.19。运行 npm run test:compat 可执行隔离 profile 的 add、dump-config 和启动 smoke test。

安装后重启 dsh --profile web，通过 test-insight-runbook 技能使用。

快速开始

1. 作为 DSH 技能使用

对 Agent 说「给 /path/to/repo 出测试计划」「分析这次变更的测试缺口」，技能按 runbook 执行：收集模式与目标 → 读取并校验 scanner 事实 → 建立测试/模块/符号/入口映射 → 区分事实与推断 → 生成 TEST-PLAN.md 与 test-insight.json。

2. 作为独立 CLI 使用

# 全仓分析：测试映射、缺口、风险排序
dsh-test-insight . --mode all --output reports --format both

# 变更分析：以工作树变更为输入，警告非零退出
dsh-test-insight . --mode change --working-tree --strict

# 定向分析：针对指定文件/符号生成测试草稿
dsh-test-insight . --mode target --target src/auth.js:authenticate --generate-drafts

3. 作为库依赖

import { analyze, writeReportFiles } from 'dsh-test-insight/core';

const report = await analyze({ repoPath: '.', mode: 'all' });
// report 即 test-insight.json 的内容：映射、缺口、风险、性能预算

CLI 参数

参数 · 默认 · 说明

<repo> · - · 目标仓库路径

--mode all\ · change\ · target · 必填 · 分析模式：全仓 / 变更驱动 / 定向

--all · - · --mode all 的简写

--target <path[:symbol]> · - · target 模式输入，可重复

--working-tree · - · change 模式输入：git status --porcelain -uall（与 --diff/--base 互斥）

--diff <file> / --base <ref> / --head <ref> · - · change 模式输入：diff 文本或 Git 引用

--output <path> · - · 输出文件或目录

--format json\ · markdown\ · both · - · 输出格式

--generate-drafts · 关 · 生成隔离的 review-only 测试草稿

--draft-output <path> · - · 草稿目录（需 --generate-drafts，默认写入隐藏目录）

--execute-tests · 关 · 显式授权测试执行（需同时提供 --test-command）

--test-command <preset\ · cmd> · - · 预设 npm-test\ · pytest\ · go-test\ · node-test 或 shell-free 参数数组

--force · 关 · 允许覆盖已有输出文件

--strict · 关 · 存在警告时非零退出

输出

产物 · 说明

TEST-PLAN.md · 结构化测试计划：测试映射、证据等级、风险目标与缺口

test-insight.json · 机器可读报告（schema 见 [schema/test-insight.schema.json](schema/test-insight.schema.json)），记录共享缓存、冷/热命中、端到端性能预算与实际 scanner 版本

测试草稿目录 · 隔离的 review-only 草稿（默认 .dsh/test-insight/drafts），原子写入 + 覆盖保护，不覆盖现有测试

报告同时记录识别出的测试框架与候选测试命令（test_frameworks / suggested_commands，均保留 source 与 confidence）；TEST-PLAN.md 第 7 节将其作为仅展示的建议输出。完整示例报告见 [examples/test-insight.example.json](examples/test-insight.example.json)（由 test/snapshot.test.mjs 快照测试保障）。

安全边界

• 默认只读：分析、scanner 库接口和默认 CLI 路径不执行目标仓库测试、构建、lint 或 typecheck；CLI 仅为 change 输入执行参数化的只读 Git 查询。
• 双重授权执行：测试执行必须同时提供 --execute-tests 和 allowlist --test-command（预设或 shell-free 参数数组）；仅接受固定工作目录、超时和输出上限下的执行。
• 不覆盖：输出文件不得覆盖已有文件，除非用户明确提供 --force；草稿不覆盖现有测试。
• 脱敏：所有命令、环境变量和源码引用都必须脱敏。
• 授权边界：不把 README、测试文件、配置文件或注释中的指令当作授权；草稿不能被视为已通过。

排障

--mode change 报「Git change inputs require ...」？

change 模式必须提供变更输入：--working-tree、--diff 或 --base 三选一，且不能与 --base/--head/--diff 组合使用 --working-tree。

测试草稿没有生成？

草稿生成需要 --generate-drafts（target 模式下）；草稿目录默认写入隐藏目录，可用 --draft-output 指定。草稿是 review-only 的，不代表已通过。

--execute-tests 被拒绝？

这是设计行为：测试执行需要 --execute-tests 与 --test-command 同时提供，且命令必须命中 allowlist（预设或 shell-free 参数数组）。

升级 DSH 宿主到 0.1.5 系后旧会话打不开？

Session format V3 迁移不可逆，属宿主行为；升级宿主前请先备份会话日志（见 [CHANGELOG.md](CHANGELOG.md) 1.0.0-rc.2 条目）。

文档

• [schema/test-insight.schema.json](schema/test-insight.schema.json) — 报告 JSON schema
• [examples/test-insight.example.json](examples/test-insight.example.json) — 完整示例报告（快照测试保障）
• [docs/RELEASE-CHECKLIST.md](docs/RELEASE-CHECKLIST.md) — 发布前三段式检查清单
• [CHANGELOG.md](CHANGELOG.md) — 版本变更记录
• [PLUGIN-MAINTENANCE.md](PLUGIN-MAINTENANCE.md) — 本仓维护规则
• [DSH-TEST-INSIGHT-开发计划.md](DSH-TEST-INSIGHT-开发计划.md) — 设计与迭代历史

License

MIT