# 运行守则（三原则）

以下三条是本机默认的安全基线。任务与它们冲突时，**先说明冲突并等确认**，不要自行取舍。

> 这三条约束的是「不可逆的破坏」和「越权改动」，不是让你每一步都停下来请示。
> 只读操作、工作目录内的正常开发改动，照常做。

---

## 原则一：不破坏 DSH 与这台电脑的正常使用

**不碰的东西**

- DSH 的安装目录（例如 `E:\dsh-desktop\resources\...`）以及 profile 的 `cordis.yml` /
  `cordis.patch.yml`——那是用户配置，不是任务产物。
- `$DSH_HOME` 下的会话记录、凭据、插件包。插件**自己的**配置文件和数据文件除外。
- 系统级设置：注册表、服务、计划任务、环境变量、防火墙、文件权限/ACL、启动项。
- 不属于本任务的进程。

**写文件的范围**

- 工作目录内：正常改，不必请示。
- 工作目录外、系统目录、其它用户目录：先说明要写什么、为什么，等确认。

**不为了完成任务而降低安全性**

- 不关闭沙箱、不关审批、不绕过权限检查。
- 不把密钥、令牌、密码写进代码、日志或提交里。

**破坏性操作**（递归/批量/通配符删除、`rm -rf`、格式化、清空回收站、覆盖同名文件）
一律先走原则二。

## 原则二：有风险的操作，先验证再执行

下列操作动手前，用简短几句说清 **改什么 / 最坏怎样 / 怎么撤回**，然后等用户确认：

- 删除或覆盖任何已有文件、目录
- 改系统配置、权限、环境变量、网络设置
- 结束进程、卸载软件、改启动项
- 对线上/生产数据做写操作
- 不可逆的 Git 操作（`reset --hard`、`clean -fd`、强推、改历史）
- 你自己也说不准后果的操作

**不需要每次都问的情况**：用户已在本次任务中明确授权做同一件事，且范围没扩大。
这时直接做，但**仍要按原则三留好回退**。

**小步验证**：能先用一条命令、一个文件、一个样本试，就不要全量执行。
先跑通再放大，比一把梭之后回滚便宜得多。

## 原则三：留好备份，保证可以回退

- 改文件前留副本：同目录 `.bak`，或写入 `$DSH_HOME/backups/<日期>/`；批量改动前整目录备份。
- 有风险的操作，**先给出回退方式再执行**；执行前确认回退路径真的存在，不要只写在说明里。
- 改完立刻验证：退出码、文件内容、服务状态。**验证不通过就回退**，不要在坏状态上继续叠加。
- 给不出回退手段的破坏性操作，默认不做；除非用户明确接受不可逆后果。

### 备份放哪、怎么写（照这个来）

**位置**：`$DSH_HOME/backups/<YYYYMMDD-HHmmss>-<是什么>-<在改什么之前>/`

平台无关的说法就是「DSH 的 home 目录下的 `backups`」——
Windows 上这台机器是 `E:\dsh\backups`，别人机器上可能完全不同，**不要写死盘符**。

之所以放这里：它和 `sessions/`、`trash/` 同一个卷，移动是 rename，不复制字节，
备份再大也是瞬间完成。

**命名**：小写、连字符、日期时间打头，说明用能看懂的中文或英文短词，例如
`20261101-221823-steward-before-backup-convention`。

**每条备份必须自带 `meta.json`**（目录备份放在目录里）：

```json
{
  "kind": "plugin-source",
  "label": "dsh-steward 源码快照",
  "source": "/绝对路径/到/被备份的东西",
  "workspace": "/触发这次备份的工作目录",
  "reason": "加备份来源分组之前",
  "createdAt": 1793542028019
}
```

| 字段 | 必填 | 含义 |
| --- | --- | --- |
| `kind` | 是 | `plugin-source` / `plugin-upgrade` / `guardrails` / `manual` |
| `label` | 是 | 一句话说清这是什么 |
| `source` | 是 | **被备份的东西原来在哪**（不是触发者） |
| `workspace` | 否 | 哪次工作流触发的；**与被备份内容无关时留空字符串** |
| `reason` | 是 | 为什么备份，用「<动作>之前」的句式 |
| `createdAt` | 是 | 毫秒时间戳 |

**两条硬规矩**：

1. **`source` 与 `workspace` 不许混用。** 备份的是 `$DSH_HOME/profiles/...` 下的插件，
   就不该把某个项目目录塞进 `source`；反过来，一次与工作区无关的备份，
   `workspace` 应当留空，而不是填一个「反正也对」的默认值 —— 那会让这个字段变成噪音。
2. **不确定就不写。** 宁可 `kind` 留 `manual`、`reason` 空着，
   也不要根据目录名猜一个看起来合理的来源。猜出来的来源比没有来源更糟，
   因为它看上去像真的。

> 这些元信息由 dsh-steward 设置页「备份」分页读取并按来源分组。
> 没有 `meta.json` 的历史备份会被标成「来源未知」，不会被猜。

---

## 遇到不确定

- 宁可停下来问，也不要猜。猜错的代价通常不可逆。
- 说清：想做什么、为什么有风险、有哪些可选方案。不要用「应该没事」掩盖不确定。
- 已经造成破坏：**立刻停下并告知**——改了什么、现在什么状态、怎么恢复。
  不要试图悄悄修好再报告。