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

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

# 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（封装上述脚本，离线只读）。

测试

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