dsh-modernize-code

Readme

# dsh-modernize-code

> [!IMPORTANT]
> **依赖前置：相邻 `dsh-src` 检出（`link:` 依赖）**
> 本项目在开发形态下使用 `link:` 依赖指向相邻的 DeepSeek Harness 源码检出（`dsh-src`），
> 与当前仓库保持同一父目录布局（`<parent>/dsh-src`）。克隆本仓库后：
> 1. 先把官方 `deepseek-ai/deepseek-harness` 检出到与本仓库同级的 `dsh-src/` 目录，并执行其 `pnpm install && pnpm run build`；
> 2. 再按下方「安装」一节执行本仓库的 `pnpm install --offline && pnpm build` 与测试。
> 发布到 npm 的版本会尽量把 `link:` 依赖替换为 registry 真实版本；无法替换的内部包保持 `link:`，见各包 README 说明。


> DeepSeek Harness 技能包：**遗留代码评估 → 现代化路线图 → 分步迁移** 完整工作流。
> 行为对齐 anthropics code-modernization 的 preflight（环境就绪检查）与多角色 agent 分工；
> 上游 license Proprietary，本实现为独立撰写、**MIT**。

## 工作流

```
preflight ──► assess ──► map ──► transform（逐块循环）
```

| 阶段 | 做什么 | 产物 | 产出工具 |
| --- | --- | --- | --- |
| preflight | 5 个不阻塞问题 + 6 项自动检查 | `PREFLIGHT.md`（就绪/未就绪 + open items） | `scripts/preflight.py` / 工具 `modernize-preflight` |
| assess | 遗留模式静态扫描 + 模型热区清单 | `legacy-hotspots.md`（影响面×风险÷成本排序） | `scripts/detect-patterns.py` / 工具 `modernize-assess` |
| map | 阶段化迁移路线图 | `MIGRATION_ROADMAP.md` | `references/modernization-map.md` 模板 |
| transform | 逐块增量迁移（禁止大爆炸，改码交用户确认） | 每阶段的回滚点 + 验证记录 | SKILL.md 纪律 |

核心行为要求（与上游同款）：**问了不阻塞、报告不漏项**——Check 0 的 5 个问题
提出后立即继续跑 Check 1–6；未答问题原样列为 open items，绝不悄悄丢弃、绝不替答。

## 目录结构

```
dsh-modernize-code/
├── cordis.yml                  # 独立组合：插入 src/*.ts 两个插件行
├── cordis.patch.yml            # dsh.bundle patch 层（package.json 声明）
├── package.json                # dsh.bundle → ./cordis.patch.yml；peerDeps 由宿主提供
├── src/
│   ├── skill-mount.ts          # 以隔离 provider 把 skills/ 注册进 ctx.skills
│   └── modernize-tools.ts      # 工具：modernize-preflight / modernize-assess
├── skills/dsh-modernize-code/
│   ├── SKILL.md                # 工作流技能（frontmatter name+description，DSH 可列出加载）
│   ├── references/
│   │   ├── legacy-patterns.md      # 遗留模式清单
│   │   ├── modernization-map.md    # 评估→路线图模板（每阶段含回滚点+验证命令）
│   │   └── preflight-checklist.md  # Check 0 五问原文 + Check 1–6 判定标准
│   └── scripts/
│       ├── preflight.py            # 就绪检查（离线，stdlib only）
│       └── detect-patterns.py      # 遗留模式静态扫描（离线，stdlib only）
├── tests/
│   ├── fixtures/legacy-app/        # 故意含回调嵌套/全局状态/魔法数/巨型函数/重复代码等
│   ├── fixtures/answers.json       # 5 问答案样例
│   └── smoke.e2e.ts                # 离线冒烟测试
└── LICENSE                        # MIT
```

## 快速使用（不需要挂载插件）

```bash
# preflight：环境就绪预检
python3 skills/dsh-modernize-code/scripts/preflight.py <project-dir> \
  --answers answers.json --targets ts,container

# assess：遗留模式扫描（markdown 报告 / JSON 明细）
python3 skills/dsh-modernize-code/scripts/detect-patterns.py <project-dir> \
  --out legacy-hotspots.md
python3 skills/dsh-modernize-code/scripts/detect-patterns.py <project-dir> --json
```

`--answers` 的 JSON 键见 `references/preflight-checklist.md`（business_critical /
build_method / deploy_method / team_constraints / success_metrics）；
不提供 answers 时 5 问原样列为 PREFLIGHT.md 的 open items（不阻塞、不替答）。

## 作为 DSH 插件挂载

插件遵循 DSH Cordis 规范（`name` / `inject` / `apply`，工具用 `defineTool`）：

- **独立组合**：在宿主组合中以 `- insert: [{ name: '<本项目>/cordis.yml' }]` 挂载，
  或直接引用 `src/skill-mount.ts` / `src/modernize-tools.ts`；
- **bundle 方式**：`package.json` 声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`，
  作为 profile bundle 层叠加（行 id：`modernize-skill-mount` / `modernize-tools`）；
- 运行依赖（peerDependencies）由宿主提供：`@deepseek-ai/cordis`、
  `@deepseek-ai/dsh-skill-filesystem`、`@deepseek-ai/dsh-tools`、
  `@deepseek-ai/dsh-subprocess`——本包不捆绑这些包体。

挂载后：
- `skill` 工具能列出并加载 `dsh-modernize-code`（frontmatter 合法）；
- 新增模型工具 `modernize-preflight` / `modernize-assess`（封装上述脚本，离线只读）。

## 测试

```bash
npm run test:smoke        # 等价于 node --experimental-strip-types tests/smoke.e2e.ts
```

冒烟测试**完全离线**（只 spawn 本地 `python3` 与文件读写），覆盖：
preflight 带/不带 answers（5 问不阻塞 + 6 检查全输出 + open items 原样保留）、
detect-patterns 对 9 个已布种子模式的命中率、SKILL.md frontmatter 合法性、
路线图模板的回滚点+验证命令要素。要求 `python3`（≥3.9）与 `node`（≥22.6，支持
type stripping）在 PATH 中。

## 许可证

MIT。参考项目 anthropics/claude-plugins-official#code-modernization 为
Proprietary license：本项目仅参考其**流程骨架与 preflight 行为**，全部文本、
脚本与实现均为独立撰写。
## 权限、失败边界与 DSH STORE 状态

- **权限/失败边界**：见 [PERMISSIONS.md](./PERMISSIONS.md)——运行时仅读取被扫描项目
  目录、经宿主 `ctx.subprocess` 以非 shell 固定 argv 执行本地 `python3` 包内脚本、
  在项目目录写入 `PREFLIGHT.md` / `legacy-hotspots.md`；无网络、无凭据、无外部服务；
  超时/非零退出/JSON 解析失败均为结构化错误。
- **DSH STORE 一次性 Profile 证据**：见 [docs/store-evidence.md](./docs/store-evidence.md)
  （安装/启动/卸载步骤 + 已完成的离线证据；真实 Profile 运行记录在宿主上执行该文档补全）。