134 lines
6.6 KiB
Markdown
134 lines
6.6 KiB
Markdown
# 三端工作区结构规范 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 结对。
|