# 三端工作区结构规范 v2（2026-08-11）

> 由「三端项目内结构规范 v1」升级而来。
> 升级动因：2026-08-11 PPT-Agent 工作区「方法层/项目层分离」整理实践沉淀。
> 配套：project-new（新建骨架）/ workspace-tidy（存量整理）两兄弟共用本规范；
> 知识主本：本文件（三端同步）；project-new.sh / workspace-tidy 均从此读取。

## 〇、核心原则（v2 总纲）

1. **工作区三层结构**：任何可复用工作区（如 PPT-Agent）顶层分为
   `methods/`（方法层）、`projects/`（项目层）、`deliverables/`（交付层），
   加 README.md 总览卡片。
2. **层内不动，跨层才搬**：项目内部只补骨架不搬文件（继承 v1）；
   只有跨层资产归位（方法↔项目↔交付）才允许物理迁移。
3. **搬必有据**：跨层迁移必须满足「备份就绪 + 对应档位确认 + 引用已更新」。
4. **单份真身，软链复用**：同一资产多处需要时用软链，不复制（避免版本分裂）。
5. **方法提取纪律**：项目内验证成功的新方法必须参数化后进方法层，
   不得只留在项目内。
6. **自动发现零维护**：诊断/整理全部靠「扫描 + 阈值判断」，不维护预置清单。

---

## 一、工作区三层结构（v2 新增）

```
<工作区>/
├── README.md              # 总览卡片（必建）
├── methods/               ★ 方法层：跨项目可复用资产
│   ├── skill/             # → 软链到 skill 本体（如 ~/.hermes/skills/xxx）
│   ├── scripts/           # 通用脚本（转换器/门禁/生成器，参数化）
│   ├── docs/              # 方法文档（流程/规范/风格）
│   ├── <素材库>/          # 素材（图标库/布局/配色/模板）
│   └── charts/  data/  ...# 通用图表/数据资产
├── projects/              ★ 项目层：一个项目一个目录
│   ├── <项目名>/          # 项目内结构见 v1（第二章）
│   └── _archive/          # 历史试验/冻结项目归档
└── deliverables/          ★ 交付层：最终交付物（final pptx/docx 等）
```

- 目录名约定：英文小写（methods/projects/deliverables），中文仅用于项目名根目录
- 方法层 scripts/ 内脚本统一 `动词_对象.py` 命名，全部参数化、带 `--help`
- 项目层 `_archive/` 内项目不改内容只改位置

---

## 二、项目内结构规范（继承 v1 全文）

> v1 内容原样保留，作用域 = 单个项目内部。

1. 根目录不迁移；规范只约束项目内部
2. 业务域为顶：写作/科研/学习/运维/生活，写在项目卡片 README
3. code 按类型自适应：仅代码型项目建 code/（git 仓库，tag 版本化）
4. 版本化 = git tag，不建版本目录
5. 文档统一进 research/（=docs 归并处）
6. 存量只建骨架不搬文件（**层内**原则）

```
<项目>/
├── code/                # 仅代码型（git，tag 版本化）
├── data/                # 数据本体 raw/processed/output
├── report/              # 报告/交付物
├── research/            # 文献/调研/设计笔记（=docs）
├── scripts/             # 项目专属脚本（只放本项目微调）
├── logs/                # 运行日志
├── archive/             # 归档（软删除源文件 30 天）
└── README.md            # 项目卡片（必建）
```

项目卡片 README 模板（v1 第三节）：

```markdown
# <项目名>
## 基本信息
- 域: 科研 | 写作 | 学习 | 运维 | 生活
- 归属端: 服务器 | 本机 | 华为 | 多端（注明主要端）
- 关联 profile: （如 server/engineer…）
- 关联服务: （如 llm-wiki :8083，无则 —）
## 结构说明
（本项目有哪些目录、各自放什么，2-3 行）
## 数据与 git
- 数据本体: <绝对路径>
- git 远端: <地址或 —>
- 版本 tag: <最新 tag 或 —>
## 状态
- 最后更新: <日期>
- 备注: <运维提示/已知问题>
```

---

## 三、整理决策规则（v2 新增，跨层迁移的权威条款）

| 场景 | 层级 | 处置 | 确认档位 |
|------|------|------|----------|
| 项目内部结构不完整 | 层内 | 只建骨架 + 补 README，不搬文件 | A 自动 |
| 方法脚本在项目内（判定为通用） | 跨层（项目→方法层） | 复制 + 参数化 + 原文件软删（进项目 archive/） | C 强确认 |
| 交付物在项目内 | 跨层（项目→交付层） | mv | B 需确认 |
| 素材/数据混放 | 同层归位 | mv | B 需确认 |
| 历史试验项目 | 层内（项目→_archive） | mv（不改内容只改位置） | A 自动 |
| 一份资产多处需要 | 跨层 | 软链，不复制（单份真身） | B 需确认 |
| 配置/路径错误 | 配置层 | 修改 + 备份 .bak | B 需确认 |
| 散落文件（根目录松散文件/文档/脚本） | 归位 | mv 到对应层 | B 需确认 |

三档确认：A 自动（方案中列明即可）／ B 需确认（逐条或 --yes）／ C 强确认（永不跳过，须展示备份证据）。

---

## 四、方法提取纪律（v2 新增）

项目内开发的新方法（脚本/流程），在本项目交付后必须：

1. 判定通用性（5 维打分：路径耦合/参数化/引用/命名/主题；≥+4 提取，≤-3 留项目，中间灰色带逐条确认）
2. 提取流程：复制进 methods/scripts/ → 参数化（硬编码路径→参数/环境变量）→ 重命名（动词_对象.py）→ 补 argparse + --help → 验证 → 写方法文档（methods/docs/xxx.md）→ 更新引用 → 原文件软删进项目 archive/
3. 完成检查清单：无项目名残留 / 无绝对路径残留 / 有 --help / 参数有默认值 / 依赖可声明 / 方法文档已写 / 无旧路径引用 / 原文件已归档
4. 经济性门槛：脚本 >50 行 或 被 ≥2 项目引用 或 预计未来复用，否则只归位不提取

---

## 五、新项目自动遵循（v2 新增）

- project-new 生成的项目：README 卡片注明归属工作区三层结构
- ppt-master 的 generate-pptx.md Step 2：项目根 = `$PPT_MASTER_PROJECTS_ROOT`（环境变量），
  项目内新方法一律参数化后进方法层
- workspace-tidy 整理后：工作区 README 更新为新结构树

---

## 六、更新记录

- 2026-08-03: v1 发布（业务域为顶/git tag 版本化/配置层登记映射/存量收编/code 自适应/无独立 docs/存量骨架）
- 2026-08-11: v2 发布。新增工作区三层结构（methods/projects/deliverables）；
  层内不动跨层才搬；搬必有据；单份真身软链复用；方法提取纪律；
  整理决策规则表；与 workspace-tidy 结对。