505 lines
31 KiB
Markdown
505 lines
31 KiB
Markdown
|
||
# 三端统一工作区目录结构规范体系
|
||
|
||
> 适用端：服务器 `/srv/share/`、本机 `D:\`、华为端 `D:\Agent\`
|
||
> 适用对象：工作区、应用、代码项目、知识库、单项目目录及共享资产层
|
||
> 核心目标：新建时按类型套模板，存量按风险逐步收敛；不改变三端根目录，不为“看起来整齐”破坏运行路径。
|
||
|
||
|
||
## ⚡ 60 秒快速决策（新建目录时先看这里）
|
||
|
||
| 问自己一个问题 | 回答"是"→ 类型 |
|
||
|---|---|
|
||
| 给多个工作区共用？ | **W6 共享资产层** |
|
||
| 要常驻运行/开端口/监控/备份？ | **W2 服务型** |
|
||
| 长期存资料供检索，无完成日期？ | **W4 知识库** |
|
||
| 管 ≥2 个项目 + 有复用方法 + 有交付物？ | **W1 内容生产** |
|
||
| 主要产出是代码/软件包？ | **W3 工程型** |
|
||
| 以上都不是，单个任务有结束日？ | **W5 单项目** |
|
||
|
||
> 还是不确定？跑 `classify_workspace.py <目录>` 机器给建议，或直接 `project-new <名称> --workspace-type auto` 让工具判定。
|
||
> 详细判定规则见 1.3 节；每类模板见 templates/；登记卡模板见 templates/workspace.yaml.template。
|
||
|
||
## 1. 分类体系总览
|
||
|
||
### 1.1 总体原则
|
||
|
||
1. **先分类，后建目录**：任何新目录先确定主类型，再选择模板。
|
||
2. **一个目录一个主类型**：允许登记辅助属性，但不得同时套用两套顶层模板。
|
||
3. **按职责分类，不按技术名称分类**：判断它主要在“生产内容、运行服务、开发代码、保存知识、完成单项任务，还是供多个目录共享”。
|
||
4. **根目录保持不变**：服务器、本机、华为端现有根路径不统一迁移。
|
||
5. **运行稳定优先**：存量服务、Git 仓库、软链接和脚本引用未经验证不得搬动。
|
||
6. **目录按需创建**：除 `README.md` 和模板标明的必建目录外，不创建无用途的空目录。
|
||
7. **单份真身**：共享内容只保留一份权威副本，通过软链接、引用或同步规则复用。
|
||
|
||
### 1.2 六类体系
|
||
|
||
| 编号 | 类型 | 精确定义 | 典型对象 | 是否默认采用 v2 三层结构 |
|
||
|---|---|---|---|---|
|
||
| W1 | 内容生产型工作区 | 持续服务多个内容项目，并沉淀可复用方法，最终产生 PPT、文档、图表等交付物 | PPT_Agent、学术工具工作台 | **是** |
|
||
| W2 | 服务型应用 | 需要长期运行、部署、配置、监控、备份或对外提供接口的应用 | ARIS、gitea、feishu-bridge、control-api | 否 |
|
||
| W3 | 工程型代码项目 | 主要成果是代码、包、命令行工具或可构建的软件，但不以长期在线运行管理为主 | academic-downloader、data_collection_extract | 否 |
|
||
| W4 | 知识库/档案型 | 主要职责是长期积累、检索、引用、归档资料，而不是执行代码或交付单个项目 | knowledge、记忆档案、个人知识库、信息仓库 | 否 |
|
||
| W5 | 单项目目录 | 围绕一个有明确目标和结束条件的任务组织材料、数据、代码和报告 | 一次科研课题、一次写作任务、客户交付项目 | 否，直接采用 v1 |
|
||
| W6 | 共享资产层 | 为多个工作区提供公共资产、脚本、日志、仓库、迁移区或平台级资料 | `/srv/share/assets`、`docs`、`git`、`logs`、`scripts` | 否 |
|
||
|
||
### 1.3 新目录判定规则
|
||
|
||
按以下顺序判断，首个明确为“是”的结果即为主类型：
|
||
|
||
1. **是否供多个互不隶属的工作区共同使用？** 是：W6 共享资产层。
|
||
2. **是否需要常驻进程、端口、部署、健康检查、告警或备份恢复？** 是：W2 服务型应用。
|
||
3. **是否长期保存和检索知识，且没有明确完成日期？** 是：W4 知识库/档案型。
|
||
4. **是否同时管理两个以上同类项目，并存在可复用方法与集中交付物？** 是：W1 内容生产型工作区。
|
||
5. **主要成果是否为可测试、可发布的代码或软件包？** 是：W3 工程型代码项目。
|
||
6. **其余具有单一目标、负责人和完成条件的目录**：W5 单项目目录。
|
||
|
||
边界处理：
|
||
|
||
- 一个代码项目后来变成长期在线服务时，主类型由 W3 调整为 W2，但先改登记和文档，不立即搬文件。
|
||
- “学术工具”若是多个内容项目共用的方法平台，归 W1；若只维护工具源码，归 W3。
|
||
- “个人知识库”即使位于 `projects/` 下，只要主要职责是长期保存和检索知识，仍归 W4；物理位置与逻辑类型分开登记。
|
||
- W1 采用 v2 的必要条件是同时满足：至少两个项目、存在跨项目复用方法、存在独立最终交付物。缺一时优先按 W5 管理。
|
||
|
||
### 1.4 通用必建件
|
||
|
||
所有受管目录根部必须有 `README.md`。新建目录另建 `.workspace.yaml` 供自动化工具读取；存量目录可逐步补齐。
|
||
|
||
```yaml
|
||
schema_version: 1
|
||
name: example
|
||
class: W1 # W1-W6
|
||
profile: content-workspace
|
||
business_domain: 科研 # 科研/写作/学习/运维/生活
|
||
owner: user
|
||
primary_location: server # server/local/huawei/multi
|
||
status: active # active/paused/archived
|
||
created_at: 2026-08-12
|
||
last_reviewed_at: 2026-08-12
|
||
canonical_path: /srv/share/apps/example
|
||
related_services: []
|
||
git_remote: ""
|
||
```
|
||
|
||
通用 `README.md` 至少包含：名称、分类、用途、负责人、权威路径、三端位置、结构说明、数据位置、Git/服务关联、备份方式、当前状态、最后复核日期。
|
||
|
||
## 2. 各分类模板
|
||
|
||
### 2.1 W1 内容生产型工作区
|
||
|
||
**适用条件**：连续生产 PPT、文档、图表等内容；管理多个项目；需要沉淀跨项目方法。完整采用 v2。
|
||
|
||
```text
|
||
<workspace>/
|
||
├── README.md # 工作区总览，必建
|
||
├── .workspace.yaml # 类型和路径登记，新建必建
|
||
├── methods/ # 跨项目复用的方法层
|
||
│ ├── skills/ # skill 链接或说明
|
||
│ ├── scripts/ # 参数化通用脚本
|
||
│ ├── docs/ # 流程、规范、风格和方法说明
|
||
│ ├── templates/ # PPT、文档、表格模板
|
||
│ ├── assets/ # 本工作区通用素材
|
||
│ ├── charts/ # 通用图表定义
|
||
│ └── data/ # 可复用的小型公共数据
|
||
├── projects/ # 项目层
|
||
│ ├── <project-name>/ # 套用 W5/v1 项目模板
|
||
│ └── _archive/ # 已冻结项目，只读
|
||
├── deliverables/ # 最终交付层
|
||
│ ├── <project-name>/
|
||
│ │ ├── final/ # 正式交付版本
|
||
│ │ └── manifest.md # 版本、日期、来源项目、校验信息
|
||
│ └── _archive/ # 过期交付物
|
||
└── logs/ # 工作区级自动化日志，按需创建
|
||
```
|
||
|
||
命名规则：固定层使用英文小写；项目根可用中文或英文；交付物使用 `<项目>-<内容>-YYYYMMDD-vN.ext`。`methods/scripts/` 中脚本采用 `动词_对象.py` 或英文 `verb_object.py`，必须支持 `--help`，不得写死个人绝对路径。
|
||
|
||
方法提取仍执行 v2 门槛：脚本超过 50 行、被至少两个项目引用或确认未来复用时，才从项目层提取到方法层。跨层移动执行 A/B/C 三档确认及备份、引用更新、验证要求。
|
||
|
||
### 2.2 W2 服务型应用
|
||
|
||
**适用条件**：需要部署、运行、端口、配置、监控、日志、备份恢复或值班操作。服务已有固定启动路径时，以现状为准，模板用于登记和逐步补全。
|
||
|
||
```text
|
||
<service>/
|
||
├── README.md # 服务卡片，必建
|
||
├── .workspace.yaml # 类型登记，新建必建
|
||
├── src/ # 主程序；已有 app/ 等名称可保留
|
||
├── tests/ # 单元、集成、接口测试
|
||
├── config/
|
||
│ ├── examples/ # 可提交的配置样例
|
||
│ └── README.md # 配置项和密钥来源说明
|
||
├── deploy/
|
||
│ ├── compose/ # Docker Compose 等
|
||
│ ├── systemd/ # 服务单元
|
||
│ ├── containers/ # Dockerfile、镜像构建文件
|
||
│ └── migrations/ # 服务自身升级迁移
|
||
├── ops/
|
||
│ ├── runbooks/ # 启停、故障、恢复手册
|
||
│ ├── monitoring/ # 指标、告警、仪表盘配置
|
||
│ └── backup/ # 备份与恢复脚本/说明
|
||
├── scripts/ # 服务专用运维脚本
|
||
├── data/ # 运行数据；可链接到独立数据盘
|
||
├── logs/ # 本地日志；可链接到共享日志层
|
||
├── research/ # 架构、调研、变更设计
|
||
└── archive/ # 已冻结配置或旧产物，不放源码版本副本
|
||
```
|
||
|
||
服务 `README.md` 额外必填：监听地址和端口、启动方式、依赖服务、配置来源、数据权威路径、日志路径、健康检查、备份频率、恢复步骤入口、负责人。
|
||
|
||
约束：
|
||
|
||
- 密钥不得进入 Git；仅提交 `.env.example` 或 `config/examples/`。
|
||
- 源码版本使用 Git tag，部署产物使用镜像标签或发布版本，不复制 `v1/`、`v2/` 整套源码目录。
|
||
- `data/`、`logs/`、`backup/` 可为软链接，但 README 必须写明真实路径。
|
||
- W2 不套 v2 三层结构；服务中的脚本按“服务专用”与“平台通用”区分，平台通用脚本应归 W6。
|
||
|
||
### 2.3 W3 工程型代码项目
|
||
|
||
**适用条件**：主要交付代码、库、命令行工具、模型或可构建软件；不以长期在线服务运行为主。
|
||
|
||
```text
|
||
<code-project>/
|
||
├── README.md # 项目卡片和使用说明，必建
|
||
├── .workspace.yaml # 类型登记，新建必建
|
||
├── src/ # 主代码；按语言可替换为 app/、lib/
|
||
├── tests/ # 自动化测试
|
||
├── examples/ # 最小可运行示例
|
||
├── config/ # 非敏感配置样例
|
||
├── data/
|
||
│ ├── raw/ # 原始数据，只读原则
|
||
│ ├── processed/ # 可重建的中间数据
|
||
│ └── output/ # 程序输出
|
||
├── research/ # 需求、设计、实验和架构说明
|
||
├── report/ # 测试报告、发布说明、成果报告
|
||
├── scripts/ # 构建、发布、一次性辅助脚本
|
||
├── logs/ # 本地运行日志
|
||
└── archive/ # 冻结产物，不存源码版本副本
|
||
```
|
||
|
||
若 `<code-project>/` 本身已是 Git 仓库，**不得再机械增加 `code/` 包裹层**；此模板视为 v1 的“仓库根模式”。若单项目目录同时包含大量非代码材料，可采用 v1 的“容器模式”，把 Git 仓库放在 `code/` 中。
|
||
|
||
命名规则：仓库名和代码目录优先使用英文小写连字符；语言生态要求下可用下划线。发布版本统一采用语义化 Git tag，如 `v1.2.0`。README 必须给出安装、运行、测试、输入输出及版本方式。
|
||
|
||
### 2.4 W4 知识库/档案型
|
||
|
||
**适用条件**：长期积累、整理、搜索和引用资料；内容生命周期长于单个项目。
|
||
|
||
```text
|
||
<knowledge-base>/
|
||
├── README.md # 范围、入口和管理规则，必建
|
||
├── .workspace.yaml # 类型登记，新建必建
|
||
├── inbox/ # 未分类入口，定期清空
|
||
├── domains/ # 按业务域组织的知识正文
|
||
│ ├── 科研/
|
||
│ ├── 写作/
|
||
│ ├── 学习/
|
||
│ ├── 运维/
|
||
│ └── 生活/
|
||
├── references/ # 外部资料、文献和引用记录
|
||
├── attachments/ # 图片、PDF、附件等
|
||
├── indexes/ # 总索引、主题索引、标签索引
|
||
├── templates/ # 笔记、档案、复盘模板
|
||
├── exports/ # 可重建的导出物
|
||
├── archive/ # 冻结、废弃或历史内容
|
||
└── logs/ # 导入、索引、同步日志，按需创建
|
||
```
|
||
|
||
知识条目推荐命名为 `YYYYMMDD-主题.md`；已有稳定中文标题可保留。`inbox/` 只作入口，不作永久存放区。附件必须由正文或索引引用。`exports/` 可删除重建，不作为知识真身。`archive/` 中内容默认只读。
|
||
|
||
“记忆档案”现有 `_规范`、`_模板` 可分别映射为 `domains/运维/规范` 与 `templates/`；为降低风险，第一阶段只在 README 登记映射，不立即搬动。
|
||
|
||
### 2.5 W5 单项目目录
|
||
|
||
**适用条件**：一个目标、一个责任边界、有结束或冻结条件。该类直接承接 v1。
|
||
|
||
```text
|
||
<project>/
|
||
├── README.md # 项目卡片，必建
|
||
├── .workspace.yaml # 类型登记，新建必建
|
||
├── code/ # 仅代码型项目需要；内部为 Git 仓库
|
||
│ ├── src/ # 主代码
|
||
│ ├── tests/ # 测试
|
||
│ └── README.md # 代码说明
|
||
├── data/
|
||
│ ├── raw/ # 原始数据
|
||
│ ├── processed/ # 中间数据
|
||
│ └── output/ # 数据输出
|
||
├── report/ # 报告、图表、项目交付物
|
||
├── research/ # 文献、调研、设计、实验记录
|
||
├── scripts/ # 项目专用辅助脚本
|
||
├── logs/ # 项目运行日志
|
||
└── archive/ # 冻结旧产物
|
||
```
|
||
|
||
除 `README.md` 外均按需创建。项目卡片沿用 v1，并补充 `分类: W5`、`权威路径`、`父工作区`、`备份策略`、`完成条件`。源码版本使用 Git tag；`archive/vN/` 只允许保存冻结交付物，不允许保存整套源码副本。
|
||
|
||
### 2.6 W6 共享资产层
|
||
|
||
**适用条件**：资产服务于多个独立工作区；不属于某一应用或某一项目。W6 是平台级分类，不应在其中直接混放普通项目。
|
||
|
||
```text
|
||
<shared-root>/
|
||
├── README.md # 共享层地图、负责人和边界，必建
|
||
├── .workspace.yaml # 类型登记，新建必建
|
||
├── assets/ # 公共图片、字体、模板等只读资产
|
||
│ ├── README.md
|
||
│ └── <asset-domain>/
|
||
├── docs/ # 跨工作区规范、平台文档
|
||
│ ├── standards/
|
||
│ ├── runbooks/
|
||
│ └── indexes/
|
||
├── git/ # Git 仓库或镜像；不放散落文件
|
||
├── knowledge/ # 跨工作区公共知识
|
||
├── scripts/ # 平台级通用脚本
|
||
│ ├── bin/
|
||
│ ├── lib/
|
||
│ └── tests/
|
||
├── logs/ # 聚合日志
|
||
│ ├── <service-name>/
|
||
│ └── retention.md
|
||
├── migration/ # 有期限的迁移中转区
|
||
│ ├── active/
|
||
│ └── archive/
|
||
└── inventory/ # 三端目录清单和路径映射
|
||
├── workspaces.yaml
|
||
└── links.yaml
|
||
```
|
||
|
||
共享子层可以独立存在于 `/srv/share/` 顶层，不要求再包一层 `shared-root/`；上图表示其逻辑结构。每个顶层共享目录必须有自己的 README，说明准入条件、负责人、保留期限和清理规则。
|
||
|
||
`migration/` 必须给每项内容登记来源、目标、负责人和截止日期；不得成为长期堆放区。`logs/` 必须定义保留周期。`assets/` 和 `knowledge/` 的权威副本不得与各工作区复制并行维护。
|
||
|
||
## 3. 规范体系整合关系
|
||
|
||
### 3.1 规范树
|
||
|
||
```text
|
||
三端统一目录规范（总纲）
|
||
├── 分类目录（W1-W6）
|
||
│ ├── W1 内容生产型工作区模板
|
||
│ ├── W2 服务型应用模板
|
||
│ ├── W3 工程型代码项目模板
|
||
│ ├── W4 知识库/档案型模板
|
||
│ ├── W5 单项目模板
|
||
│ └── W6 共享资产层模板
|
||
├── v2 工作区子规范
|
||
│ └── 仅被 W1 引用：methods / projects / deliverables
|
||
├── v1 项目内子规范
|
||
│ ├── 被 W1 的 projects/<项目> 引用
|
||
│ └── 被 W5 直接引用
|
||
└── 类型专用补充规范
|
||
├── W2 部署、配置、监控、备份
|
||
├── W3 仓库根模式
|
||
├── W4 索引、附件、归档
|
||
└── W6 准入、保留期、路径映射
|
||
```
|
||
|
||
### 3.2 引用与优先级
|
||
|
||
规范冲突时按以下顺序处理：
|
||
|
||
1. 安全、服务运行和数据恢复要求。
|
||
2. 分类模板的专用规定。
|
||
3. v2 工作区规定。
|
||
4. v1 项目内部规定。
|
||
5. 通用命名建议。
|
||
|
||
v1 与 v2 **不删除、不并成一篇超长正文**，而是升级为总规范下的版本化子规范：
|
||
|
||
- v1 更名为“单项目内部结构子规范”，保留容器模式，并补充“Git 仓库根模式”，解决现有代码仓库不适合再套 `code/` 的问题。
|
||
- v2 更名为“多项目内容工作区子规范”，不再宣称适用于任何可复用工作区，只对满足 W1 判定条件的目录生效。
|
||
- 总规范负责分类、选型、优先级和三端实施；子规范负责具体组织规则。
|
||
|
||
### 3.3 语义一致性
|
||
|
||
不同模板中相同名称必须保持相同含义：
|
||
|
||
| 名称 | 统一含义 |
|
||
|---|---|
|
||
| `research/` | 项目或工程内部的调研、设计、实验、架构资料 |
|
||
| `docs/` | 仅用于 W1 方法文档或 W6 跨工作区平台文档 |
|
||
| `report/` | 项目报告及阶段成果 |
|
||
| `deliverables/` | W1 工作区集中管理的正式最终交付物 |
|
||
| `archive/` | 冻结、只读、非当前内容；不是备份替代品 |
|
||
| `backup/` | 可恢复副本及恢复流程，仅服务运维或平台备份使用 |
|
||
| `scripts/` | 当前层级专用脚本；跨工作区通用脚本进入 W6 |
|
||
|
||
## 4. 实施路径
|
||
|
||
### 4.1 知识主本与三端分发
|
||
|
||
建议建立一个版本化规范仓库，权威工作副本为：
|
||
|
||
```text
|
||
/srv/share/docs/standards/workspace-directory-standard/
|
||
├── README.md # 总规范，即本文
|
||
├── catalog.yaml # 分类规则机器可读版
|
||
├── templates/ # W1-W6 骨架和 README 模板
|
||
├── policies/ # v1、v2、命名、迁移规则
|
||
├── scripts/ # 校验和生成脚本
|
||
├── CHANGELOG.md
|
||
└── tests/
|
||
```
|
||
|
||
通过 Gitea 管理版本。两台 Windows 设备只保留受控工作副本：
|
||
|
||
- 本机：`D:\记忆档案\_规范\workspace-directory-standard\`
|
||
- 华为端：`D:\Agent\standards\workspace-directory-standard\`
|
||
|
||
服务器 Git/Gitea 版本为权威来源，Windows 副本不得各自演化。规范变更采用提交、评审、打 tag 的方式发布，例如 `standard-v1.0.0`。当前 v1/v2 原文进入 `policies/legacy/` 留档，生效版放入 `policies/current/`。
|
||
|
||
### 4.2 `project-new`：让新建自动查规范
|
||
|
||
建议统一入口：
|
||
|
||
```text
|
||
project-new --name <名称> --type <W1-W6|auto> --root <目标根> --domain <业务域>
|
||
```
|
||
|
||
执行流程：
|
||
|
||
1. 从权威规范仓库读取 `catalog.yaml`，检查本地规范版本。
|
||
2. 未指定类型时，只询问五个普通问题：是否长期运行、是否长期存知识、是否管理多个项目、主要成果是否为代码、是否供多个工作区共享。
|
||
3. 显示判定类型、目标路径、将创建的目录和 README 摘要。
|
||
4. 默认先 `--dry-run`；确认后创建骨架。
|
||
5. 写入 `.workspace.yaml` 和 README，不创建无用途空目录。
|
||
6. 将新目录登记到 `/srv/share/inventory/workspaces.yaml` 或三端对应清单。
|
||
7. 校验路径、重名、非法字符、Git 嵌套和共享层越界。
|
||
|
||
模板文件应由规范仓库提供，skill 本身不得复制维护另一套模板。
|
||
|
||
### 4.3 `workspace-tidy`：让存量逐步收敛
|
||
|
||
保留 v2 的五阶段流程：诊断 → 方案 → 三档确认 → 执行 → 验证，并增加“先分类”步骤。
|
||
|
||
- **A 自动**：补 README、补 `.workspace.yaml`、生成清单、创建缺失但确定需要的目录。
|
||
- **B 需确认**：普通文件归位、交付物跨层移动、建立软链接、更新非运行配置。
|
||
- **C 强确认**：移动服务目录、修改启动路径、迁移数据真身、提取通用方法、改变 Git 仓库根、删除或去重。
|
||
|
||
每次执行必须输出：变更前清单、分类结果、计划、备份证据、实际变更、引用检查、服务或脚本验证、回滚说明。默认不删除文件；软删除内容至少保留 30 天。
|
||
|
||
### 4.4 存量收敛顺序
|
||
|
||
| 波次 | 对象 | 动作 | 原因 |
|
||
|---|---|---|---|
|
||
| 0 | 全部目录 | 只盘点、分类、补 README/清单，不搬文件 | 先获得全局地图 |
|
||
| 1 | 新建目录、PPT_Agent、workspace-tidy-skill | 应用 W1/W3 模板并打通两个 skill | 使用频率高，可验证规范 |
|
||
| 2 | 个人知识库、信息仓库、记忆档案、knowledge | 套 W4，先建索引和映射 | 风险较低，整理收益明显 |
|
||
| 3 | academic-downloader 等工程项目 | 套 W3，补测试、说明和版本规则 | 可用 Git 验证，回退清晰 |
|
||
| 4 | ARIS、gitea、feishu-bridge 等服务 | 套 W2，以登记和补运维文档为主 | 路径敏感，需逐个验证 |
|
||
| 5 | `/srv/share/` 共享层和 agents 总控台 | 明确边界、保留期、权威副本和软链接 | 影响范围最大，最后处理 |
|
||
|
||
每个波次先选一个试点，连续稳定运行一周后再扩大。任何服务目录只要无法完整说明启动、数据和回滚方式，就停留在“已登记、未迁移”状态。
|
||
|
||
### 4.5 验收指标
|
||
|
||
- 新建目录 100% 有分类、README 和权威路径登记。
|
||
- W1 工作区 100% 能区分方法、项目、交付物。
|
||
- 服务型应用 100% 有端口、启动、日志、备份和恢复说明。
|
||
- 共享资产能确定唯一权威副本，不存在无人负责的长期 `migration/` 内容。
|
||
- `project-new` 与 `workspace-tidy` 使用同一 `catalog.yaml` 和模板源。
|
||
- 整理前后 Git 状态、软链接、服务健康检查及关键文件数量均有记录。
|
||
|
||
## 5. 决策点建议
|
||
|
||
### 5.1 分类粒度：4 类、6 类还是更细
|
||
|
||
| 选项 | 做法 | 优点 | 风险 |
|
||
|---|---|---|---|
|
||
| 4 类 | 工作区、应用、知识、共享 | 容易记 | 代码工程与单项目混淆，模板差异过大 |
|
||
| 6 类 | W1-W6 | 覆盖现状，边界可解释 | 需要一张判定表 |
|
||
| 8 类以上 | 再拆数据、代理、模型、媒体等 | 很精细 | 难记、难维护，新目录容易选错 |
|
||
|
||
**推荐：6 类。** 六类正好对应六种不同生命周期和管理责任。代理、数据处理、PPT 等应作为 `profile` 辅助属性，不再增加主分类。例如 `class: W2, profile: agent-service`。
|
||
|
||
### 5.2 是否需要自动分类函数/脚本
|
||
|
||
| 选项 | 做法 | 评价 |
|
||
|---|---|---|
|
||
| 不需要 | 完全查文档手工选择 | 简单，但执行容易走样 |
|
||
| 全自动扫描 | 根据文件名、端口、Dockerfile 等直接决定 | 适合盘点，不适合无确认地定类 |
|
||
| 半自动判定 | 问答为主，扫描为辅，展示依据后由人确认 | 可解释、风险可控 |
|
||
|
||
**推荐：半自动判定。** 脚本输出“建议类型 + 依据 + 置信度”，人确认后写入 `.workspace.yaml`。扫描信号可包括 `Dockerfile`、Compose、systemd、`src/`、大量 Markdown、多个子项目及交付文件，但不得仅凭目录名自动搬文件。
|
||
|
||
建议伪代码：
|
||
|
||
```text
|
||
if shared_by_independent_workspaces: W6
|
||
elif has_runtime_or_deployment: W2
|
||
elif long_term_knowledge_store: W4
|
||
elif project_count >= 2 and reusable_methods and final_deliverables: W1
|
||
elif primary_output_is_software: W3
|
||
else: W5
|
||
```
|
||
|
||
### 5.3 命名语言：全英文还是中英混合
|
||
|
||
| 选项 | 做法 | 评价 |
|
||
|---|---|---|
|
||
| 全英文 | 所有层级均英文 | 自动化友好，但存量迁移成本高 |
|
||
| 全中文 | 业务直观 | 跨平台脚本、命令和第三方工具兼容性较差 |
|
||
| 受控中英混合 | 固定结构英文，业务根和项目名可中文 | 兼顾稳定性和可读性 |
|
||
|
||
**推荐：受控中英混合。** `methods/projects/src/tests/data/logs` 等固定结构名使用英文小写；用户可见的业务根和项目名允许中文。新英文名称使用 `kebab-case`，Python 模块遵循语言要求使用 `snake_case`。禁止同级同时出现 `docs/`、`文档/`、`documentation/` 三套同义目录。
|
||
|
||
### 5.4 v1/v2 合并还是多份引用
|
||
|
||
| 选项 | 做法 | 评价 |
|
||
|---|---|---|
|
||
| 全部合并 | 一份超长总规范 | 搜索集中，但更新容易互相影响 |
|
||
| 完全分开 | 总规范、v1、v2 各自独立 | 易产生重复和冲突 |
|
||
| 总纲 + 子规范 | 总纲负责选型，v1/v2 负责各自范围 | 边界清楚，可独立版本化 |
|
||
|
||
**推荐：总纲 + 子规范。** 本文是唯一入口；v1 作为单项目子规范，v2 作为 W1 多项目工作区子规范。机器可读规则和模板集中维护，正文通过链接引用，避免复制多份。
|
||
|
||
## 6. 附录：现有工作区归类示例
|
||
|
||
> 下表为基于名称和现状信息的初步归类。带“待核实”的项目应由半自动问答确认，不据此直接搬动。
|
||
|
||
| 位置 | 现有目录 | 建议分类 | 建议 profile | 说明/下一步 |
|
||
|---|---|---|---|---|
|
||
| `/srv/share/apps` | `PPT_Agent` | W1 | content-workspace | 典型多项目内容生产工作区，采用 v2 |
|
||
| `/srv/share/apps` | `学术工具` | W1/W3 待核实 | research-content 或 tool | 多项目与复用方法成立则 W1，否则 W3 |
|
||
| `/srv/share/apps` | `ARIS` | W2 | application-service | 若有常驻进程、端口或部署即 W2 |
|
||
| `/srv/share/apps` | `aris_mvp` | W3/W5 待核实 | prototype | 独立代码原型归 W3；单次验证归 W5 |
|
||
| `/srv/share/apps` | `gitea` | W2 | infrastructure-service | 补部署、数据、备份恢复卡片 |
|
||
| `/srv/share/apps` | `feishu-bridge` | W2 | integration-service | 记录外部依赖、密钥来源、重试和日志 |
|
||
| `/srv/share/apps` | `academic-downloader` | W3 | cli-tool | 代码工具；若常驻 API 化再转 W2 |
|
||
| `/srv/share/apps` | `agent-evolution` | W3/W5 待核实 | agent-research | 按主要成果和结束条件确认 |
|
||
| `/srv/share/apps` | `data_collection_extract` | W3 | data-tool | 数据处理代码项目 |
|
||
| `/srv/share/apps` | `llm_wiki` | W2 | knowledge-service | 应用服务与其知识数据分开登记 |
|
||
| `/srv/share/apps` | `llm_wiki_release` | W2/W6 待核实 | release | 若只是发布包，应并入服务发布流程或共享发布库 |
|
||
| `/srv/share/apps` | `personal_literature` | W4/W2 待核实 | literature-base | 资料库归 W4；带长期运行系统则 W2 |
|
||
| `/srv/share/apps` | `research_crew` | W3/W2 待核实 | agent-tool | 常驻编排服务归 W2，否则 W3 |
|
||
| `/srv/share/apps` | `structure_riconoscere` | W3/W5 待核实 | research-code | 有持续开发的代码归 W3 |
|
||
| `/srv/share/agents` | `agentctl` | W2/W3 | control-service | 有总控进程/API 时归 W2 |
|
||
| `/srv/share/agents` | `control-api` | W2 | api-service | 服务型应用 |
|
||
| `/srv/share/agents` | `dashboard`、`dashboard-v2` | W2 | web-service | 两版应通过 Git/发布管理，避免长期双目录；先核实引用 |
|
||
| `/srv/share/agents` | `aris-unified` | W2 | application-service | 登记服务边界和与 ARIS 的关系 |
|
||
| `/srv/share/agents` | `codify`、`eval`、`cost` | W3/W2 待核实 | agent-tool | 根据是否常驻运行判断 |
|
||
| `/srv/share/agents` | `memory`、`info-warehouse` | W4/W2 待核实 | knowledge-store | 数据真身归 W4，访问服务可独立归 W2 |
|
||
| `/srv/share/agents` | `archive`、`backup`、`cache`、`config`、`logs` | W6 | agent-shared | 作为 agents 平台共享层，不作为独立项目 |
|
||
| `/srv/share` | `assets` | W6 | shared-assets | 建准入和权威副本说明 |
|
||
| `/srv/share` | `docs` | W6 | shared-docs | 规范主本建议位于此处 |
|
||
| `/srv/share` | `git` | W6 | repository-hosting | 只放仓库或镜像，补索引 |
|
||
| `/srv/share` | `knowledge` | W4/W6 | shared-knowledge | 内容类型 W4，平台位置属性 W6；主分类建议 W4 |
|
||
| `/srv/share` | `logs` | W6 | shared-logs | 定义按服务分区和保留周期 |
|
||
| `/srv/share` | `scripts` | W6 | shared-scripts | 通用脚本必须参数化并有测试/说明 |
|
||
| `/srv/share` | `学术数据` | W6/W4 待核实 | shared-data | 多项目共用数据归 W6，文献知识归 W4 |
|
||
| `/srv/share` | `migration` | W6 | migration-staging | 强制来源、目标、截止日期和负责人 |
|
||
| `D:\hermes\projects` | `PPT_Agent_全套` | W1 | content-workspace | 与服务器 PPT_Agent 明确唯一真身及同步关系 |
|
||
| `D:\hermes\projects` | `workspace-tidy-skill` | W3 | automation-skill | 代码工程，读取总规范模板 |
|
||
| `D:\hermes\projects` | `个人知识库` | W4 | personal-knowledge | 物理位置可暂不改，先登记逻辑分类 |
|
||
| `D:\hermes\projects` | `信息仓库` | W4 | information-archive | 建索引、入口和归档规则 |
|
||
| `D:\记忆档案` | 整体 | W4 | personal-archive | 现有中文域保留，逐步映射到 W4 |
|
||
| `D:\记忆档案` | `_规范`、`_模板` | W4 | standards/templates | 先登记映射，不立即迁移 |
|
||
| `D:\记忆档案` | `_废弃备份` | W4/W6 待核实 | archive/backup | 区分“归档”与“可恢复备份”，设置保留期 |
|
||
| `D:\Agent` | 各工作区 | 按 W1-W6 逐项判断 | huawei-copy | 标明权威端；避免形成第三份独立真身 |
|
||
|
||
### 通俗摘要（约 300 字）
|
||
|
||
这套办法像给家里的东西统一分六种柜子：做 PPT 和文章的放“内容工作台”，长期运行的软件放“服务柜”，代码工具放“工程柜”，资料笔记放“知识柜”，一次性任务放“项目盒”，大家共用的素材和脚本放“公共柜”。以后建新目录，先回答几个简单问题，再由工具自动搭好架子和说明卡。旧目录不急着搬，先贴标签、画地图、补说明；普通资料确认后再归位，正在运行的服务和重要数据必须先备份、核对引用并验证。服务器保存唯一标准，本机和华为端同步使用。原来的 v1 继续管单个项目内部，v2 只管包含多个项目、公共方法和集中交付物的内容工作区，既保留已有经验，也避免所有目录硬套同一种样子。
|
||
|