# 设计套件（Kit）的分享、定制与项目维护

[English](kit-sharing.en.md)

本页用于分享和接收语构设计系统（Yugoo Design）的设计套件（Kit）。可直接复制
[社区工作坊示例](../../examples/community-workshop-delivery/README.md)，
创作规则见[扩展开发](extending.md)。Kit 内容与 Design Project 是两类材料：
分享 Kit 不包含用户项目、会话、模型凭据或宿主安装。

**适用版本：** 下文的 Studio 原地编辑、直接源码导入和项目内 `design_kit` 文件说明对应 `0.2.3` 发行版。Studio 完整创作流程的验证仍在进行；使用前核对[宿主范围](hosts.md)与[发行状态](preview-status.md)，了解实测范围与已知问题。下方历史记录保留其当时版本与范围，旧版入口按对应说明操作。

选择与目标安装版相符的交付方式：Studio 通过源码导入入口接收文件，完整内容目录通过宿主 loader 接入，npm 包由发行与宿主登记路径安装。首次接收先在独立项目验证，避免覆盖正在使用的内容。

## Official Kits

官方设计套件（Official Kits）的用途、交付状态与实际接入范围如下。

选择前可先读[官方 Kit 用户指南](official-kits.md)，了解各类面板帮助你判断什么，以及如何开始一个小场景。本节继续集中维护版本、获取方式与接入范围。

**先安装主插件，再选择套件。** Web App 是默认随主插件交付的官方设计套件，
无需用户另行安装它的内部 npm 模块。Companion 在 payload 中携带完整 Web App
内容；DSH 整套发行通过依赖和包入口加载它。随装是内容可用，不代表自动为所有
项目选择套件；首次使用通过当前宿主的 `yugoo` 入口创建项目并选择 `web_app`，
已有项目继续使用自己的 Kit 文件。旧格式项目的恢复规则见下方[原内容恢复](#更新与恢复项目内容)。主插件获取步骤见[安装指南](getting-started.md)。

| 官方套件 | 用途与方法 | 获取与适用范围 |
| --- | --- | --- |
| Web App（`web_app`） | 软件应用的需求、流程、规则、数据、页面、AI 能力及交接；见[方法与内容](../../packages/skills-web-app/README.md) | 随主插件 `yugoo-design` 提供，无需单独安装内部内容模块；按[安装指南](getting-started.md)取得所需发行版本。 |

npm 产品版本与 Kit/Bundle 内容版本分别管理。当前默认套件之外，可参考下方公开社区示例并定制自己的方法；其他领域的探索不表示已随产品交付。发行与宿主支持情况见[发行状态](preview-status.md)和[宿主范围](hosts.md)。

### 让当前 Agent 安装并选择默认套件

复制下面的请求给当前宿主的 Agent，并一并提供[通用安装提示词](../../packages/companion/HOSTS.md#default-prompt-any-supported-host)：

```text
请按通用安装提示词，为当前宿主安装语构设计系统（Yugoo Design），
保留现有模型、凭据、插件和项目配置。优先使用我明确指定的版本；
未指定时，将 npm latest 解析为精确已发布的稳定版本。
若 latest 指向预发布版或所需版本不可用，说明情况并停止，不自行改选。
获取并核对精确发行版本；
Web App 应随主插件提供，不让我逐个安装内部模块。
完成宿主要求的启用或新会话后，检查实际可用套件中的 web_app。
为我创建一个新的设计项目并选择它，说明实际使用的 Kit 身份与内容来源。
人工导入、授权或启用确有需要时再给出具体步骤；安装失败时报告具体缺项。
```

### 让当前 Agent 接入已交付的独立套件

安装包、导入到本地内容库、被宿主发现和被项目选择是不同结果。以下请求适用于你已从作者
取得的独立 Kit。
不要把 `npm install` 成功当作自动注册，也不要覆盖已有项目来试用新套件：

```text
我已取得作者交付的独立 Kit，想在新项目中试用。
请读取交付的 README，了解 Kit 用途、内容来源、已有许可说明、
Bundle 依赖和宿主兼容；若以 npm 交付，同时核对作者提供的精确包入口。
先查看当前安装实际提供的内容导入或完整内容包加载入口。
用 Studio 导入时保留原文件；缺少辅助定义时，打开编辑器说明并补全具体缺项，
不要把导入成功当作已可运行。没有可用接入路径时先报告，不编造命令。
不要覆盖已有套件或项目，也不要自动安装外部执行依赖。
在新项目中选择准备好的 Kit，核对项目自己的 Kit 与 Bundle 文件，
验证非空面板、保存与重开，分别说明取包、加载、保存和原生 Agent 使用的结果。
```

完整内容包的目录接入见[DSH 发现与选择](#dsh目录发现与显式选择)和
[Companion 显式入口](#companion显式目录与项目选择)；Studio 源码导入见下一节。
本地内容库中，同一身份只有当前保存的内容（current）；编辑原地保存，复制才产生独立身份。
新项目首次选择 Kit 时取得完整内容副本，已有项目不会随内容库修改而变化。
要更新既有项目，请让 Agent 对比文件并保留定制，见[更新与恢复](#更新与恢复项目内容)。

## 通过 Studio 内容归档分享

Studio 在 Kit 和 Bundle 的现有工作区提供导入、编辑与导出入口；具体呈现按宿主版本核对。它们都使用同一份当前保存的源码，没有“准备导入后再采用”或本地版本发布步骤。

作者分享当前内容：

1. 打开要分享的 Kit 或 Bundle，保存希望交付的修改。
2. 导出当前源码 ZIP。Kit 导出包含已挂载 Bundle 的文件和资源，Bundle 也可单独导出；未完成的定义可以导出给别人协作补全。来源与许可证不是导出必填项，文件中已有的 LICENSE、NOTICE 和来源说明仍会保留。
3. 同时交付简短 README：适用任务、宿主/插件版本、可选或必需的外部环境、一个合成请求，以及实际验证范围。遵守下方许可和原署名要求。

接收者导入并试用：

1. 在现有导入入口选择源码 ZIP、文件夹或单个 `SKILL.md`。独立 Bundle 至少需要 `SKILL.md`；Kit 至少需要 `mindset.md` 与 `kit.yaml`。旧版归档 JSON 可由同一入口解析后导入其中的文件。
2. 导入创建一个独立身份并保留原始文件。同名显示名称会自动区分；它不会覆盖原内容。其他辅助文件缺失或定义尚未完整时，仍可进入编辑器保存和补全，诊断会指出具体缺项。
3. 在原始文件和挂载管理中完成所需内容；也可请当前宿主的 Agent 协助补全，经同一差异查看与保存路径保留修改。来源与许可证不需要另行填写或通过审核才能编辑。
4. 在独立新项目中选择准备好的 Kit，核对生成到项目中的完整 Kit 与 Bundle 文件，再完成下方[接收者验证](#作者与接收者的最小验证)。独立 Bundle 需先明确挂载到 Kit。

导入只接收源码，不执行脚本、不安装模型或 Provider，也不改变已有项目。导入成功、定义可加载、面板预览通过和原生 Agent 真正使用是不同结果。已有源码版本与归档摘要用于来源追溯和文件完整性检查，不是本地版本选择器。传输格式及资源边界见[归档契约](../../packages/studio/docs/content-archive.md)。

## 交付格式与依赖说明

可运行的 Kit 交付应保留 **Kit 与它挂载的完整 Bundle 内容**。当前文件布局将 `kits/` 与 `bundles/`
分开；可用内容包组织这些文件，由 `package.json.designSystem.kit` 声明入口。加载这种包时，
将包根目录交给支持包解析的入口；仅提供 Kit 目录还需配置与声明对应的 Bundle resolver。
不能只凭目录中存在 `mindset.md` 就认定依赖完整。结构见[扩展开发](extending.md#当前内容组织)。

ZIP 和 Git 可以运送完整文件。使用目录 loader 时，ZIP 先解压，再按包入口或目录入口加载；使用 Studio 时，直接交给其源码导入入口。Studio 的归档包装保留文件摘要，以安装版本和[归档契约](../../packages/studio/docs/content-archive.md)为准。不要只分享 Panel 或用户项目的 Design Files 来代替完整 Kit。

每份交付应包含或在 README 中列明：

- Kit 的稳定 `name`，各 Bundle 的身份及已有来源版本；保留对应 manifest、
  方法、schema、validation、Panel、摘要声明、语言资源和方法引用的文件。声明式摘要使用 `skill.yaml.summary`。
- 自有 LICENSE/NOTICE 及复制内容必要的原署名、第三方材料。压缩和 Git 分享
  不改变原许可；不要把运行时组件的许可归到 Kit 自有代码名下。
- 兼容要求：实际使用的宿主/插件版本，以及必需的声明式组件、资源协议或
  native Provider。只有实际验证过的版本可以称为已支持；未知版本先验证，
  不因 loader 能读 manifest 就声称所有交互兼容。
- 脚本与外部依赖：列出方法会调用的脚本、运行环境及外部包/服务；说明它们
  是随目录交付还是需独立安装。目录 loader 不执行安装脚本，也不会自动解析
  npm 依赖或下载外部 Kit。缺少依赖时停在具体缺项，不让 Agent 临时编造实现。
- 可恢复原件与更新说明：分享精确目录版本，并可附文件摘要；明确是否涉及
  schema/语义变化；版本号或来源记录本身不能代替完整内容备份。

社区工作坊示例是无需外部服务或求解器的内容 Kit，复用已安装的通用 Panel
组件；其目录/ZIP 使用结果见下方适用边界。带 native Provider、额外脚本环境
或外部包的 Kit 必须另外给出对应依赖的安装入口，不能沿用这个无额外依赖
示例的结果宣称解压即可运行。

### npm 内容包的选择

npm 用于分发插件和可独立更新的内容包，GitHub 提供公开源码。分享 Kit 时，可以提供 npm 包、Studio 内容归档或完整目录（可压缩为 ZIP）；接收者使用对应的安装、导入或加载入口。选择前先说明交付格式。

现有 Kit loader 没有通用 npm 安装、依赖解析或自动注册入口；`npm install`
成功并不意味着 Kit 已被选择。发行接入仍须约定包内 Kit 根目录、身份/版本
与许可证保留，并由宿主明确把已安装目录接入 loader。带运行时代码的包
仍需独立满足宿主注册、依赖及安全要求。统一产品包名为 `yugoo-design`；
`@yugoo-design` 下的内部模块与历史 `beta` 记录不构成另一个产品安装入口。
当前可用发行版见[发行状态](preview-status.md)。
npm 发布仍按发行版本管理；本地内容保存不等于 npm 发布，也不要求因此修改上游版本。要发布自己的包，需确认账号权限，并按独立发布流程操作。获取官方内容时查上方清单；获取其他 Kit 时，由作者提供准确的包名、版本和宿主接入说明。

## 先保存可恢复的原件

1. 保存完整内容包或等价的完整文件集合：Kit 的 `mindset.md`、`kit.yaml`、可选关系声明，
   以及各独立 Bundle 的方法与资源、LICENSE 和 NOTICE。记录 Kit、Mindset 与 Bundle 的身份和已有来源版本。
   旧示例的 `skills/` 布局仅按其兼容 loader 使用，不作为新内容的目录规范。
2. 将未修改的原件或完整 ZIP 保存在发现目录之外。试用和定制使用独立副本，
   不覆盖收件方已有内容；目录名本身不改变 Kit 身份。
3. 交付格式与入口保持对应：Studio 接收源码 ZIP、文件夹和上述最小方法文件；
   目录 loader 接收解压后的内容包，裸 Kit 目录还需能解析其 Bundle 引用。
4. 首次使用创建新项目，核对实际 Kit 身份，再生成、编辑和保存。

支持当前契约的运行时会在项目首次选择 Kit 时复制完整文件：

```text
design_kit/
  source.json
  kit/                 # 领域主提示词、kit.yaml 和 Kit 自有资源
  bundles/<identity>/  # 挂载 Bundle 的完整方法、定义与资源
```

项目内这些文件供 Agent、schema、校验、Panel、摘要和资源读取共同使用。之后修改或删除内容库中的 Kit/Bundle，不影响已有项目；新项目使用首次选择时的当前内容。项目备份应保留整个项目及 Git 历史，包括 `design_kit`，不能只备份 `design_files`。

这不包含独立安装的 native Provider、外部服务或执行环境；复制内容也不获得运行时代码的信任。旧格式项目尚无 `design_kit` 时，只能从它真实记录并保留的原 Kit/Bundle 内容初始化。固定版本引用（pin）或内容摘要不能代替原件，缺失时应恢复实际原内容，不静默改用新版。

## 独立定制：复制新身份

需要修改现有方法时，在 Studio 选择“编辑”并原地保存即可；同一身份不会因此增加一个本地版本，也不需要确认发布或重新挂载。若要保留原方法并长期维护自己的变体，再明确选择“复制”：

1. 为副本使用独立稳定身份，并调整面向用户的名称、说明、方法与例子。只改目录名不会产生新内容身份。
2. 核对 Bundle manifest、资源及身份引用；有 `relations.yaml` 时同步当前 Kit 的命名空间和领域引用。不要盲目批量替换用户数据或 canonical 字段。
3. Kit 副本继续挂载内容库中的 Bundle 身份，读取它们当前保存的内容，不自动获得每个 Bundle 的独立副本。需要单独定制某个 Bundle 时，也明确复制该 Bundle，再调整 Kit 挂载。
4. 使用文件来源时，新 Bundle 目录与 `skill.yaml.identity` 对应独立身份，`kit.yaml` 挂载项的 `name` 指向它；运行时 `skill.yaml.name` 与挂载 `bindingKey` 保持原有约定和 canonical 数据路径。`<design_skills>` 是挂载清单的模型侧投影，不另立第二份成员权威。
5. 保留来源署名和许可材料。新身份不继承 native Provider 信任，同一 Kit 的运行时绑定不得重复。在新项目中选择副本并验证；旧项目继续运行自己的文件。

DSH 已加载的目录来源不应在运行中直接改 Kit `name`。先在新目录准备独立副本，再按实际发现入口接入。项目初始化复制完整 Kit 与 Bundle，是与库内“复制 Kit”不同的操作，见上方文件布局。

<a id="dsh发现冲突与显式版本切换"></a>

## DSH：目录发现与显式选择

安装版默认发现根为 `$DSH_HOME/design-system/kits`；未设置 DSH_HOME 时为
`~/.dsh/design-system/kits`。把 Kit 放到该根的一个直接子目录；额外根使用
loader 的 `discoveryRoots` 配置。不会递归扫描所有工作区，也不会执行 Kit 脚本。
先确认当前安装版本包含该发现能力；源码修改不会更新旧安装。

开启内容监视的 DSH loader 可以在进程内重新校验并加载合法修改。若修改非法或来源暂时被移走，进程会保留上一次成功加载的内容并报告诊断；因此“目录里仍能选到”不能证明新修改已加载。先核对实际显示的身份、版本与来源，再在独立项目验证修改结果。

上一次有效内容只是进程内保留，不是完整备份。源目录被删除时，原处的脚本可能已不可用；重启后只能重新读取实际存在的来源。恢复应使用先前保存的完整原件，不能依靠进程缓存找回丢失文件。合法内容重载会影响后续新项目取得的内容，不会改写已有项目的 `design_kit`。

在新版 DSH 当前会话中，新项目的操作入口为（旧安装候选按随包指南）：

```text
/yugoo new workshop-copy
/yugoo kit community_workshop_delivery
```

也可通过实际宿主的 Design 选择界面或 Agent 选择；核对显示的 Kit 身份与来源，并检查新项目中的实际内容。

**两个目录同名时**，不会按版本号自动合并。显式来源先加载；默认发现根优先于
额外根，额外根按配置顺序、根内按目录名顺序处理。同名异源会诊断并保留已注册
来源，即使两个目录声明不同版本。处理步骤是：保留两份备份，将不使用的同名
目录移出发现根，或把独立定制副本改为新身份，然后正常重启宿主并确认目录。
不要依赖目录排序来选择升级版本。

**新项目首次选择套件时**，运行时校验完整 Kit，并复制它和全部挂载 Bundle 的文件。尚未完成的库内容可以继续保存，但缺少运行所需定义时应先补全，不能用“已导入”代替可加载检查。

已有项目再次选择同名 Kit，不会把内容库中的修改覆盖进项目；要改用另一身份或更新内容，应先说明目标，保留项目定制并对比文件。具体见下方[更新与恢复](#更新与恢复项目内容)，不要只改版本字符串或项目元数据来替换内容。

<a id="companion显式目录与升级限制"></a>

## Companion：显式目录与项目选择

Codex、Claude Code、Qoder CLI 的 Companion 使用已安装插件的实际入口，
通过 `--kit /absolute/content-entry` 指定安装版支持的内容入口。结构化内容包使用包根目录；
裸 Kit 目录必须能解析所挂载的完整 Bundle 定义，不能只移动 `mindset.md` 后期待自动寻找依赖。
项目命令、MCP 和 Panel 服务必须指向同一目录及同一项目管理状态；沿用该宿主
已有的 session/thread 绑定和启动指引，见[Companion 文档](../../packages/companion/README.md)。
不要照搬 DSH 的发现根来期待 Companion 自动发现，或虚构通用安装命令。

### 使用完整内容包创建新项目

以下 Bash 示例使用目标 npm 安装内的项目运行入口。先确认该安装包含
`payload/shared/scripts/design.mjs`，并按[内容包入口](extending.md#当前内容组织)
交付完整 Kit 与 Bundle。`yugoo-design` 是产品安装器命令，不代替这里的项目命令。
由当前 Codex Agent 填入真实安装目录、完整内容包根目录及当前会话 ID；
状态和项目目录使用单独的新目录，不借用已有项目的配置：

```bash
YUGOO_RUNTIME="/absolute/npm-install/node_modules/yugoo-design"
YUGOO_KIT="/absolute/my-content-package"
YUGOO_STATE="/absolute/new-companion-state"
YUGOO_PROJECTS="/absolute/new-design-projects"
YUGOO_THREAD="当前 Codex 会话的真实 ID"
yugoo_args=(--kit "$YUGOO_KIT" --state-root "$YUGOO_STATE"
  --projects-root "$YUGOO_PROJECTS" --host codex --thread "$YUGOO_THREAD")
node "$YUGOO_RUNTIME/payload/shared/scripts/design.mjs" command \
  --input "new Workshop" "${yugoo_args[@]}"
node "$YUGOO_RUNTIME/payload/shared/scripts/design.mjs" command \
  --input "kit my_kit" "${yugoo_args[@]}"
```

`my_kit` 必须与交付包的 Mindset `name` 一致。核对返回的可用 Kit、项目根目录
和复制到项目中的 Kit 文件，然后按目标宿主指南让 MCP 与 Panel 服务使用同一个 `--kit`、
项目管理状态和真实会话绑定，并连接到新服务。Claude Code、Qoder CLI 使用各自
的 `--host` 值和原生会话参数，不沿用示例里的 Codex 会话。

此步骤使用作者交付的完整包，不是 Studio 内容库的存储目录。不要把单个本地 Kit 记录的 `sourceRoot` 当成含全部 Bundle 的包根目录传给 `--kit`。通过 Studio 导入的内容使用同一状态目录的现有内容库选择入口，缺少挂载时回编辑器补全，无需重新拼装库的内部存储文件。

Companion 的 `kit <kit>` 选择当前服务提供的套件。新项目得到完整内容副本；已有项目继续使用自己的文件，不因库内保存而更换。另建项目试用时使用实际新目录与对应服务连接，保留原项目；不要将仍绑定旧目录的连接文件当作新连接。命令、MCP 和 Panel 是否都已接入这一契约，以目标安装版验证为准。

<a id="缺失版本与恢复原内容"></a>

## 更新与恢复项目内容

修改内容库是为后续项目准备方法；更新已有项目则修改该项目自己的 Kit 文件：

Agent 直接修改项目文件时，沿用当前宿主的写入权限。若项目位于当前工作区之外，先按宿主提供的访问设置或授权提示，确认允许写入目标目录，再继续操作。在 Studio 界面编辑时，按原有保存操作进行。

1. 先保存未保存的编辑，保留完整项目和 Git 历史。明确要采用的来源及目标，不以库中出现新文件或新上游版本作为自动更新授权。
2. 请当前宿主 Agent 对比项目 `design_kit` 与目标内容，解释有意义的变化，并保留项目已有的定制、资源与标识。需要修改 schema 或方法时，同时检查受影响的设计文件、跨 Bundle 引用和真实缺失的业务决策。
3. 通过现有校验、保存和项目 Git 流程验证并记录修改。涉及设计事实的修订仍走所属 Bundle 的既有校验与发布路径；本地内容更新不另建候选、采用事务、页面观察门禁或升级状态机。
4. 打开受影响的 Panel，检查读取、编辑、保存与重开，确认 Agent 使用项目中的新文件。执行中的真实项目定义改变会产生冲突，应基于当前文件重新处理，不能混用新旧定义。内容库改动本身不应使已有执行失效。

已有 `design_kit` 的项目加载报错时，先按具体路径修复，或从该项目备份和 Git 历史恢复需要的原文件。运行时不会因项目文件无效而静默回退到内容库。恢复方法或 Panel 不会自动撤销已经保存的设计数据，检查两者的语义是否仍一致。

旧格式项目没有该文件树时，保留项目文件、Git 历史和原 Kit 备份，恢复它实际引用的完整 Kit/Bundle 内容，包括记录过的 Bundle 覆盖与资源，再由对应运行时初始化。若原内容已缺失，应明确报告并恢复原件，或由用户明确选择更新；不能把最新库内容换上旧版本字符串冒充原件。进程内 last-good 不是完整备份。

`migrate` 项目命令是在保留原件的前提下，将已有设计项目的 Design Files 迁移到新项目并校验、适配；它不是上述同一项目内容维护流程，也不负责下载或找回缺失 Kit、原样复制完整历史。参数见[命令参考](commands.md)，文件保留范围见[项目文件管理](project-files.md)。Git 仓库、市场安装及外部依赖自动安装都不是本页步骤隐含的能力。技术契约见[项目内容维护](../project-content-upgrade.md)。

## 已验证与适用边界

<a id="采用后选择的验证范围"></a>

### 旧版采用后选择的验证范围

以下记录属于旧版归档准备与采用流程，保留用于说明当时的真实结果，不是上文简化导入、原地编辑或项目内 Kit 文件契约的验收。当前开发版本的源码检查、浏览器操作、原生 Agent 使用和安装包验证须分别记录。

导入材料、选择 Kit、运行方法、保存修改和 Agent 继续使用是不同结果。先在独立新项目中确认精确 Kit/Bundle、完整方法与资源可用，再执行下面的作者/接收者检查。需要模型或外部工具的内容必须在目标宿主实际运行；一次无外部依赖的示例结果不能证明其他 Kit 或宿主兼容。

### 作者与接收者的最小验证

一个可分享的 Kit 不只要能导入。作者和独立接收者分别记录插件版本、Kit/Bundle 身份与实际源文件、已有来源版本、合成材料与实际结果：

| 检查 | 作者 | 独立接收者 |
| --- | --- | --- |
| 资源完整 | 从运行期入口读到完整方法、契约和引用资源 | 仅凭交付材料和公开指南完成读取 |
| 装载与校验 | 非空合法样例通过，错误输入被拒绝 | 在干净的独立配置中加载对应内容 |
| 原生设计 | 生成一个有价值的设计结果 | 不依赖作者原会话或私有文件生成结果 |
| 交互与续作 | 编辑、正常保存、重开并让 Agent 基于修改继续 | 独立重复相同闭环 |
| 外部执行 | 按需实际运行并保留输入、结果和限制 | 核实依赖可取得；未运行的能力明确记录 |

运筹建模 Kit 若声称可求解，还须实际求解、解释结果，修改约束或参数后重算。仅生成模型、读取 manifest、预览面板或导入样例不能证明求解完成。接收者不能依赖作者机器上的私有绝对路径、源码工作区或未交付依赖。

这些是交付验证要求。普通声明式 Kit 的验证不代替运筹 Kit 的真实求解与修改后重算，
也不替代其他含执行依赖的扩展测试。不承诺所有历史内容
格式自动迁移；`migrate` 保留已有设计项目原件，并在新项目中按当前契约校验、适配，
与恢复缺失的精确 Kit 原件分别处理。

### 既有示例记录

公开社区工作坊示例采用旧兼容布局，其完整目录和 ZIP 曾在对应安装图的作者及独立收件方
profile 中实际完成加载、生成、Panel 编辑保存继续和重开。这是对应旧安装图的历史记录，不代表当前简化内容维护流程的每项步骤都做过新的端到端运行，也不外推所有宿主或第二台机器。实际使用以目标安装版本的能力与错误
提示为准；该历史示例不证明新的独立内容组合已完成相同验收。本指引不需要重新构建声明式 Kit 的运行时。