# 工作区目录规范

本工作区（`E:\ProgramData\AIProject\aliyun-dsh-server`）的文件落位规则。新增任何文件前，先按本文决定放哪；根目录**不再新增散落文件**。

---

## 一、根目录白名单（只允许这几类）

| 留在根的条目 | 移走会出什么事 |
|---|---|
| `CODEBUDDY.md` | 会话启动靠它加载项目指令，移走 = 每次会话失忆 |
| `state.py` | 状态快照入口，`CODEBUDDY.md §2` 写死引用该路径 |
| `接续入口_*.md` | **`state.py` 用 `os.listdir(工作区根)` 扫描**，移走即扫不到 ⇒ 新会话第一个信号就错 |
| `README.md` | 本规范 |
| `scripts/` | 运维脚本（`docs-sync-check.sh` 等） |
| `.workbuddy/` `.codebuddy/` | 记忆 / 钩子 / 条件规则，工具自管 |
| `.wbapp_*.genie` | WorkBuddy 宿主应用状态文件 |
| 结构目录 | `docs/`、`交接单/`、`tmp/`、`待清理/`、`归档/` |

⛔ **线目录不进根** —— 一条工作线的多份配套方案，放 `docs/<线名>/`（同级引用天然有效）；该线彻底冷却后再整体移入 `归档/`。

## 二、目录结构与职责

```
aliyun-dsh-server/
├── CODEBUDDY.md                  项目指令（自动加载）
├── README.md                     本规范
├── state.py                      状态快照（1 次调用代替十几轮探索）
├── 接续入口_*.md                  工作线唯一入口（必须留在根）
├── docs/                         正式文档，按主题分 8 类
│   ├── 覆盖网络/     ├── 集群与实例/    ├── 客户端与桌面/
│   ├── 会话与接续/   ├── 插件与平台/    ├── 外部接入/
│   ├── 调研与审计/   └── 分布式数据链路/
├── 交接单/                        交接单_*.md、接续包_*.md
├── scripts/                      运维脚本
├── tmp/                          临时产物（本工作区专用）
│   ├── 历史过程目录/               一次性过程目录（_tmp_seqNN 等）
│   ├── 散落临时文件/               一次性脚本与命令输出
│   └── 本次整理-20260919/          本次规整的对照表 / 回滚脚本 / 备份
├── 待清理/                        删除候选，等确认（确认后才真删）
│   └── 中间产物-20260919/
├── 归档/                          保留但不再用
│   ├── poc-dsh-local/  ├── office生成样例/
│   ├── 域名迁移_ai1net_20260919/  └── 积分图发布物/
└── .workbuddy/  .codebuddy/      工具目录（记忆 / 钩子 / 条件规则）
```

## 三、按性质决定落点

| 手上是什么 | 放哪 |
|---|---|
| 方案 / 报告 / 规范 / 复盘（正式文档） | `docs/<主题>/` |
| 交给下一棒的单子 | `交接单/` |
| 工作线入口（每个会话第一个读的） | **根**，命名 `接续入口_<线名>_<日期>.md` |
| 一次性脚本、探针输出、中间证据 | `tmp/<任务名>-<日期>/` |
| 过程目录（一个任务一整个目录） | `tmp/历史过程目录/` |
| 不再引用但需留痕 | `归档/` |
| 疑似可删 | `待清理/`，**列清单等确认** |

## 四、命名

| 类型 | 规则 | 例 |
|---|---|---|
| 正式文档 | `<主题>_<YYYYMMDD>.md` | `集群化改造方案_20260914.md` |
| 交接单 / 接续包 | `交接单_<主题>_<日期>.md` | `交接单_组密钥加密_20260918.md` |
| 线入口 | `接续入口_<线名>_<日期>.md` | 放根 |
| 临时脚本 / 输出 | `_<用途>.<ext>` | `_probe_instance_mem.sh` |
| 过程目录 | `_tmp_<序号或主题>/` | `_tmp_seq41/` |

日期一律 **8 位 `YYYYMMDD`**，不加分隔符。

## 五、临时文件

- `tmp/` 是**本工作区自己的**临时区；`.workbuddy/tmp/` 由工具自管，两者不混用。
- 一个任务一个子目录：`tmp/<任务名>-<YYYYMMDD>/`。
- ⛔ 临时文件不进根、不散进 `docs/`。
- 任务收尾时清掉不用的，只留正式产物。

## 六、归档与待清理

- **线收官** ⇒ 该线文档归入 `docs/<主题>/`；多文件方案目录移入 `归档/`。
- **删除一律不可逆** ⇒ 先移入 `待清理/`，出清单，**确认后才真删**。
- `待清理/` 非空时，收尾报告需提一句它还剩什么。

## 七、路径变更怎么查

本次规整（2026-09-19）把 119 项从根目录归位：

- **旧路径 → 新路径的权威对照**：`tmp/本次整理-20260919/移动对照表.md`
- **一键回滚**：`python tmp/本次整理-20260919/rollback.py`
- 归位后，同族文档已并入同一目录，**同级引用天然仍有效**；跨目录引用按对照表查。
- 唯一活跃入口 `接续入口_覆盖网络线_20260916.md` 内的 163 处引用已同步改为新路径。

## 八、别和文档库搞混（两个「交接单」）

| | 本工作区 | 文档库 |
|---|---|---|
| 路径 | `E:\ProgramData\AIProject\aliyun-dsh-server\` | `D:\github\dsh_shenxian\dsh-server-docs\` |
| 性质 | **工作现场**：过程文档、临时产物、线入口 | **正式档案库**：编号档案 `调整方案/01–141`、`BRIEF.md`、UI 规范、`INDEX.md` |
| 版本控制 | 非 git 仓 | git 仓（单一来源，改动只从本机推送） |
| 改动前 | 抢全局执行锁（`handoff-guard.sh --claim-exec`） | 抢锁 ＋ 双端对账 |

⛔ 两个库**都有** `交接单/` 目录，内容不同：本工作区的是「工作线交接单 / 接续包」，文档库的是「正式归档交接单」（`CODEBUDDY.md` 里 `交接单/README.md §二` 指的是**文档库**那份）。动手前先确认路径在哪个库。