# dsh-compat

[![CI](https://github.com/Simidas/dsh-compat/actions/workflows/ci.yml/badge.svg)](https://github.com/Simidas/dsh-compat/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/dsh-compat)](https://www.npmjs.com/package/dsh-compat)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

把 Claude Code 和 Codex 插件安全地迁移到 DeepSeek Harness（DSH）。

`dsh-compat` 会先逐项检查插件，再生成可审计的 DSH Bundle：哪些能力可以直接使用、哪些需要适配、哪些不支持、哪些必须阻断，都会写入机器可读报告。它不会执行源插件脚本，也不会假装宿主专有 Hook、Agent 或权限语义可以无损转换。

## 30 秒开始

需要 Node.js 22+。

```bash
npx dsh-compat inspect ./my-claude-plugin
npx dsh-compat convert ./my-claude-plugin --out ./generated-plugin
npx dsh-compat test ./generated-plugin
```

审阅生成物后，再按你的 DSH Profile 安装：

```bash
dsh plugin --profile demo add -w ./generated-plugin
dsh --profile demo --dump-config
```

![dsh-compat demo](docs/demo.gif)

## 支持范围

| 组件 | 检查 | 转换 | 结果 |
|---|---:|---:|---|
| Agent Skills | 是 | 是 | 通过 `ctx.skills` 注册，保留静态文件供审计 |
| Markdown Commands | 是 | 适配 | 转为用户可调用的 DSH Skill |
| MCP stdio | 是 | 适配 | 生成 `@deepseek-ai/dsh-mcp-client` 配置，凭据值不落盘 |
| MCP HTTP | 是 | 适配 | 规范化为 streamable HTTP，Header 值不落盘 |
| Resources | 是 | 是 | 以惰性、可审计资源复制 |
| Hooks | 是 | 否 | 在 DSH 行为等价得到验证前保持 UNSUPPORTED |
| Agents/Subagents | 是 | 否 | 在模型、工具、隔离和权限等价得到验证前保持 UNSUPPORTED |
| LSP | 是 | 否 | 只做清单检查 |
| Settings/Permissions | 是 | 否 | fail-closed，不自动扩大权限 |

## 真实插件报告

首批报告来自 Anthropic 官方插件仓库的固定公开 commit，仓库只保存摘要、哈希、兼容结论和人工动作，不复制第三方源码：

- [`commit-commands`](reports/real/commit-commands.md)：3 个 Commands 均为 ADAPTED
- [`hookify`](reports/real/hookify.md)：Skill 为 DIRECT，Commands 为 ADAPTED，Hooks/Agent 保持 UNSUPPORTED
- [`feature-dev`](reports/real/feature-dev.md)：Command 可适配，3 个 Agents 保持 UNSUPPORTED
- [`pr-review-toolkit`](reports/real/pr-review-toolkit.md)：Review Command 可适配，6 个 Agents 保持 UNSUPPORTED
- [`security-guidance`](reports/real/security-guidance.md)：5 个安全 Hooks 保持 UNSUPPORTED

完整索引见 [`reports/real/README.md`](reports/real/README.md)。

## 安全边界

源插件是不可信输入。转换器不会运行 `install`、`prepare`、`postinstall`、Hook、MCP、LSP 或二进制程序；路径穿越、外部符号链接、内联凭据和权限放宽会被报告或阻断。生成 Bundle 仍然需要你在安装前审阅。

## 开发

```bash
pnpm install
pnpm test:all
```

新增适配规则必须同时提供规则 ID、fixture、兼容报告和必要的安全测试。详细合同见 [`docs/COMPATIBILITY-CONTRACT.md`](docs/COMPATIBILITY-CONTRACT.md)。

## 状态

当前版本是 Developer Preview，目标适配器固定为 DSH `0.1.0-rc.6`。DSH 本身仍可能发生兼容性破坏，报告不能替代目标版本上的行为验证。

## 许可证

Apache-2.0。第三方源插件和生成物仍受其各自许可证约束，见 [`NOTICE`](NOTICE)。