# 技能与规则安装

[← 文档导航](README.md)

技能用于复用工作方法，规则用于描述项目约定。打开工作台后，先选择目标工作区，再进入“技能”或“规则”。

## 安装四步

1. **选择资源**：点“安装技能”选择文件夹；点“安装规则”选择一个 `.md` 文件。
2. **检查预览**：查看名称、正文、文件数、体积、目标路径与同名冲突。
3. **选择范围**：选择项目或个人，改变范围后会重新预览。
4. **确认安装**：成功后列表刷新，再到“流程配置”把资源挂到对应阶段。

预览不写入目标目录。已有同名资源时拒绝覆盖；请先检查现有内容，或给新资源使用不同名称。

## 准备文件

技能文件夹中需要 UTF-8 编码的 `SKILL.md`，frontmatter 包含单行 `name` 和 `description`。名称使用小写字母、数字和连字符，例如 `code-check`。脚本、模板和二进制附件可与清单一同安装。

规则是一个 UTF-8 编码的 Markdown 文件，名称来自文件名，使用同样的命名规则，例如 `code-check.md`。支持 BOM 与 CRLF；其他编码请先转换。安装不会执行脚本。

## 选择存放位置

| 范围 | 技能 | 规则 |
| :--- | :--- | :--- |
| 项目 | 工作区 `.dsh/skills` | 工作区 `.dsh/rules` |
| 个人 | `$DSH_HOME/skills` | `$DSH_HOME/rules` |

`DSH_HOME` 默认是用户主目录下的 `.dsh`。删除确认框显示实际路径；确认删除后不经过回收站。内置资源只读，项目和个人资源可以查看、编辑和删除。

## 格式与大小限制

| 项目 | 上限 |
| :--- | ---: |
| 技能文件数量 | 1,000 |
| 总体积 | 100 MB |
| 单文件 | 20 MB |
| 相对目录深度 | 20 层 |
| SKILL.md 或规则正文 | 1 MB |

常见缓存目录会自动排除，包括 `node_modules`、`.git`、`__pycache__`、`.venv`、`venv`、`.cache` 和 `.DS_Store`。不接受越级路径、Windows ADS、保留名称、大小写重名以及文件/目录冲突。

## 安装失败时

| 提示或现象 | 处理方式 |
| :--- | :--- |
| 缺少 SKILL.md 或有多个技能 | 直接选择一个技能的根文件夹。 |
| 名称无效 | 修改源清单的 name 或规则文件名，再重新选择。 |
| 同名冲突 | 取消安装，检查现有资源；需要共存时使用不同名称。 |
| 超过限制 | 移除不需要的构建产物与大文件，再重新选择。 |
| 预览后内容或目标变化 | 重新预览后再确认。 |

确认时会重新校验内容和目标摘要，并使用独占创建避免覆盖。技能写入中途失败时，会清理本次新建的技能目录。

<details>
<summary>高级：主机目录模式与上传限制</summary>

系统选择器读取浏览器所在电脑的文件；高级目录模式读取 Harness 进程所在电脑的目录。本机个人使用时通常是同一台电脑。主机扫描拒绝符号链接、junction 和特殊文件；浏览器文件 API 不提供源链接元数据。

上传内容在内存中编码、校验。100 MB 是代码限制，不是已经完成大包和并发压力测试的容量承诺；分块、进度和取消见[功能规划](roadmap.md)。

</details>