workspace-directory-standard/policies/current/content-workspace-v2.md

三端工作区结构规范 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 第三节）：

# <项目名>
## 基本信息
- 域: 科研 | 写作 | 学习 | 运维 | 生活
- 归属端: 服务器 | 本机 | 华为 | 多端（注明主要端）
- 关联 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 结对。