为你的 DSH 项目接入 dsh-distribution

September 5, 2026 · View on GitHub

接入的目标：让支持 dsh-distribution 的工具，能用统一方式了解你的整套环境，而不必专门猜测和适配它。

你不需要先理解仓库里的包怎么划分。对作者而言，这是一次环境接入：整理项目的真实信息，生成环境说明，检查并随项目提供。编码助手可以完成格式转换和校验，你负责确认它无法判断的事实。

1. 让 AI 先了解你的项目

不需要你填写协议选择表。让 AI 读取项目，并用普通话整理以下信息供你确认：

要了解的事情	例如	需要注意
项目身份和版本	Alice 的 DSH 工作台，版本 1.0.0	项目标识应保持稳定，不与别人的项目混淆。
环境的组成	DSH 运行时、桌面界面、已安装插件	使用真实来源和现有组件信息，不另造一套插件格式。
配置与数据位置	设置、聊天记录、扩展、缓存、用户资料	区分环境自己的内容、共享内容和外部数据；不能只看目录名字猜。
安装和管理方式	本地整合包、容器、在线服务；怎样找到某次安装	同一项目装两份，不应被认成同一个安装实例。
状态和迁移条件	状态从哪里取得，哪些数据可复制，哪些需要停机或重新登录	没有真实实现或证据时，不声明“已支持”或“可安全迁移”。

这些是同一个环境的不同信息，不是几套独立的接入任务。项目没有某类数据或操作时，AI 应按规范处理“不适用”，不让你为了接入新造一个服务。

项目 ID 可以使用 urn:dsh:distribution:alice:my-dsh 这样的写法，换成自己的用户名和项目名即可，建议用英文字母、数字和连字符。无需申请域名或注册，但你仍需避免 ID 冲突。版本可以是 1.0.0，不要包含空格。

让 AI 参考环境说明示例和现行规范，将确认后的事实写入项目的说明文件。对于本地整合包，可以保存为 dsh-distribution.json；文件名不是强制规定。容器或在线服务也可以使用适合自己的提供方式。

你审阅时只需要先看懂这些事情：

不必照搬示例中的目录、组件或功能声明。 示例用于展示同一套说明如何容纳这些信息，不是让你的项目假装与示例一模一样。不同环境填写不同的真实内容，遵循的格式和含义保持一致。

公共说明描述的是这款项目。用户每次安装产生的实例身份、机器路径、当前状态及迁移记录，由管理工具结合实际安装维护；不要在公共说明中硬编码某位用户的安装 ID 或私有路径。

如果某类信息无法确认，让 AI 在交付报告中列出问题，不往 JSON 里编造 pending 等字段，也不要用“留空后格式通过”替代对项目的实际检查。

下面的命令供编码助手或熟悉开发工具的人使用。在 dsh-distribution 仓库根目录运行，不是在你的整合包里安装开发依赖。

需要 Node.js ^22.19.0 || >=24.0.0、pnpm 11.21.0：

pnpm install --frozen-lockfile
pnpm build
node packages/conformance/lib/cli.js "你的说明文件的绝对路径"

把引号内容换成实际路径。检查器只读取说明文件，不启动项目、不安装插件、不复制或删除数据。npm 包尚未发布，不要假定可以直接从 npm 安装它们。

结果可以这样理解：

校验器只能检查你写进去的信息，不能替你调查项目，也不能证明管理操作已经实现。 还需要对照前面整理的项目事实，确认没有写错、漏掉适用信息或虚报能力。未实际运行校验器时，AI 应明确说“未验证”。

把说明随整合包或源码提供，并在项目 README 中告诉使用者在哪里找到它。支持此协议的工具可以据此读取信息；工具是否能真正备份、切换或迁移环境，取决于它实现了哪些操作。

以后发布新版时，同步维护版本、组件和数据位置等变化。通常保留固定项目 ID，不要因为用户装在另一台电脑上就修改公共项目身份。

交付时可以用下面这段话说明接入结果，但只填写已有证据的内容：

本项目已提供 dsh-distribution 环境说明。环境身份、组成和数据管理信息见［文件位置］；校验结果为［实际结果］。具体管理操作由支持该协议的工具提供，当前已验证的工具和操作为［如实列出；没有则说明尚未验证］。

你接入的是一套共同语言，不是在给项目换运行框架。 无需改成指定目录，也不应为了接入重写插件或安装一套不需要的运行库。

说明文件不保存密码或密钥；“可迁移”不等于“可以公开”。实际文件操作需要权限、完整性和恢复保障，不能因为说明合法就直接开始复制或删除。

工具开发细节见开发指南，精确规则见规范提案。