104 lines
5.5 KiB
Markdown
104 lines
5.5 KiB
Markdown
# 工作区目录规范
|
||
|
||
本工作区（`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 §二` 指的是**文档库**那份）。动手前先确认路径在哪个库。
|