dsh-compat Compatibility Contract v1

August 14, 2026 · View on GitHub

1. CLI Contract

Inspect

dsh-compat inspect <source> \
  [--target-dsh package:<version>|commit:<sha>] \
  --format text|json \
  [--strict]

只读；
不启动 package manager、MCP、LSP、hook 或 binary；
默认输出摘要到 stdout；JSON 模式输出稳定 schema；
--strict 将 UNSUPPORTED 视为 policy failure。

Convert

dsh-compat convert <source> \
  --out ./generated-plugin \
  [--target-dsh package:<version>|commit:<sha>]

先完成 inspect；存在 BLOCKED 时不生成；
不覆盖未知文件；
只写 --out 与显式 --report；
不执行生成产物或源插件代码。

Test

dsh-compat test ./generated-plugin \
  [--format text|json]

当前实现只执行确定性静态校验，不启动 DSH、MCP、LSP 或源插件；
DSH --dump-config 与 headless behavior 属于独立 M3 验证流程；
CI 可非交互运行。

2. Exit Codes

Code	含义
0	命令完成，满足当前 policy
1	CLI 使用错误或内部错误
2	兼容 policy 未通过，例如 strict 模式出现 UNSUPPORTED
3	安全阻塞，例如路径逃逸、凭据或权限放宽
4	保留给未来的来源 ref 或目标 DSH revision 解析失败

同一错误类别不得在小版本中改变 exit code。

3. Report Schema

顶层：

{
  "schemaVersion": "1",
  "tool": {
    "name": "dsh-compat",
    "version": "0.1.0",
    "ruleSetVersion": "2026-08-14.1"
  },
  "source": {
    "kind": "local|git",
    "displayLocator": "<source-root>",
    "ref": "optional",
    "resolvedCommit": "optional",
    "contentDigest": "sha256:...",
    "license": "optional"
  },
  "target": {
    "kind": "dsh",
    "requested": "commit:<sha>",
    "resolvedRevision": "commit:<full-sha>",
    "resolvedAdapter": "dsh-developer-preview-2026-08",
    "capabilityFingerprint": "sha256:..."
  },
  "summary": {
    "overall": "DIRECT|ADAPTED|UNSUPPORTED|BLOCKED",
    "counts": {
      "direct": 0,
      "adapted": 0,
      "unsupported": 0,
      "blocked": 0
    }
  },
  "components": [],
  "diagnostics": [],
  "generatedFiles": []
}

4. Component Decision

{
  "id": "hook:hooks/hooks.json#PreToolUse[0]",
  "kind": "hook",
  "name": "security-check",
  "sourceRef": {
    "path": "hooks/hooks.json",
    "pointer": "/hooks/PreToolUse/0"
  },
  "state": "ADAPTED",
  "ruleId": "hook.claude.pre-tool-use.bridge.v1",
  "reason": "Target DSH adapter supports this event through the official bridge.",
  "transformations": [],
  "risks": [],
  "manualActions": [],
  "targetArtifacts": []
}