90 lines
4.0 KiB
Markdown
90 lines
4.0 KiB
Markdown
# 三端项目内结构规范 v1（2026-08-03）
|
||
|
||
> 三端（成田server/固定电脑/华为）统一的项目内文件组织规范。
|
||
> 根目录不迁移，规范作用域 = **项目内部**。
|
||
> 配套：项目卡片 README.md 为必建件；版本化用 git tag。
|
||
|
||
## 一、核心原则
|
||
|
||
1. **根目录不动**：三端各自现有根（本机 D:\、服务器 /srv/share/、华为 D:\Agent 等）保持，
|
||
规范只约束项目内部结构
|
||
2. **业务域为顶**：项目归属 写作/科研/学习/运维/生活 五域之一，域写在项目卡片 README，
|
||
不强制建域目录
|
||
3. **code 按类型自适应**：只有代码型项目建 code/；数据/文档/创作型项目可跳过
|
||
4. **版本化 = git tag**：code/ 必须是 git 仓库，版本用 tag（v1.0/v2.0），
|
||
**不建 v1.0/ 版本目录**（工作区只留当前版）
|
||
5. **文档统一进 research/**：不设独立 docs/（设计笔记/调研/实验记录/架构说明全归 research/）
|
||
6. **存量只建骨架不搬文件**：已存在项目补 README 卡片 + 建缺失标准目录，
|
||
现有文件不物理移动（防破坏 git 历史/软链接/服务路径）
|
||
|
||
## 二、标准结构
|
||
|
||
```
|
||
<项目>/
|
||
├── code/ # 仅代码型项目（git 仓库，tag 版本化）
|
||
│ ├── src|app/ # 主代码
|
||
│ ├── tests/ # 测试
|
||
│ └── README.md # 代码说明 + 版本记录（tag 列表）
|
||
├── data/ # 数据本体（输入/中间/输出）
|
||
│ ├── raw/ processed/ output/ # 按需建，不强制
|
||
├── report/ # 报告/交付物（周报/文档/图表/PPT）
|
||
├── research/ # 文献/调研/设计笔记/实验记录/架构说明（=docs 归并处）
|
||
├── scripts/ # 一次性/工具脚本（不进 code 主仓的）
|
||
├── logs/ # 运行日志
|
||
├── archive/ # 归档（废弃版本/旧数据，如 archive/v1.0/）
|
||
└── README.md # 项目卡片（必建，见三）
|
||
```
|
||
|
||
子目录按需创建，**不强制空目录**（data/raw、data/processed 等仅在有内容时建）。
|
||
|
||
## 三、项目卡片 README.md（必建）
|
||
|
||
每个项目根必须有一个 README.md，模板：
|
||
|
||
```markdown
|
||
# <项目名>
|
||
|
||
## 基本信息
|
||
- 域: 科研 | 写作 | 学习 | 运维 | 生活
|
||
- 归属端: 服务器 | 本机 | 华为 | 多端（注明主要端）
|
||
- 关联 profile: （如 server/engineer、chuangzuo、learning…）
|
||
- 关联服务: （如 llm-wiki :8083，无则填 —）
|
||
|
||
## 结构说明
|
||
（本项目有哪些目录、各自放什么，2-3 行）
|
||
|
||
## 数据与 git
|
||
- 数据本体: <绝对路径>
|
||
- git 远端: <地址或 —>
|
||
- 版本 tag: <最新 tag 或 —>
|
||
|
||
## 状态
|
||
- 最后更新: <日期>
|
||
- 备注: <运维提示/已知问题>
|
||
```
|
||
|
||
## 四、版本化规则
|
||
|
||
- code/ 用 git 管理：`git tag v1.0` 打版，`git tag -l` 查看
|
||
- 归档旧版：`archive/v1.0/` 只放**已冻结的旧产物**（快照/导出），源码版本一律靠 git tag
|
||
- 新建版本 = 改代码 + commit + 打新 tag，**不复制整个目录**
|
||
|
||
## 五、命名约定
|
||
|
||
- 目录名：英文小写连字符（code/data/report/research/scripts/logs/archive），中文项目名仅用于根目录
|
||
- 版本 tag：`v<major>.<minor>`（v1.0/v2.0），重大破坏性变更升 major
|
||
- 一次性脚本：`scripts/` 下，命名 `<用途>.py`；临时文件用 `_` 前缀放 `data/tmp/` 或直接删
|
||
|
||
## 六、实施清单
|
||
|
||
| 项 | 动作 |
|
||
|----|------|
|
||
| 新建项目 | 按标准结构建骨架 + README 卡片 |
|
||
| 存量代码型项目 | 已有 code/ 保持；补 README + 缺失目录（data/report/research） |
|
||
| 存量非代码项目 | 补 README + 已有目录登记，不强制建 code/ |
|
||
| 全部存量 | 补 README 卡片（登记域/归属/git），建缺失标准目录骨架 |
|
||
|
||
## 七、更新记录
|
||
|
||
- 2026-08-03: v1 发布。决策: 业务域为顶(1B)/git tag 版本化(2B)/配置层登记映射(3B安全解读)/存量收编(4A)/code 自适应(细化1B)/无独立docs(细化2B)/存量骨架(细化3B)
|