init: 三端统一工作区目录结构规范 (W1-W6 catalog + templates + scripts + policies)

2026-08-12 00:44:42 +08:00
commit 3a48a1f408
14 changed files with 1541 additions and 0 deletions
@@ -0,0 +1,42 @@
+# W1 内容生产型工作区模板
+
+> 来源：三端统一目录规范（README.md）2.1 节
+> 适用：连续生产 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/                        # 工作区级自动化日志，按需创建
+```
+
+## 命名
+
+- 固定层：英文小写（methods/projects/deliverables）
+- 项目根：中文或英文均可
+- 交付物：`<项目>-<内容>-YYYYMMDD-vN.ext`
+- methods/scripts/ 脚本：`动词_对象.py`，必须支持 `--help`，不得写死个人绝对路径
+
+## 方法提取门槛（v2 纪律）
+
+- 脚本 >50 行 或 被 ≥2 项目引用 或 预计未来复用 → 提取到方法层
+- 提取流程：复制 → 参数化 → 重命名 → 补 --help → 验证 → 写文档 → 更新引用 → 原文件软删归档
+- 跨层移动执行 A/B/C 三档确认 + 备份 + 引用更新 + 验证
@@ -0,0 +1,43 @@
+# W2 服务型应用模板
+
+> 来源：三端统一目录规范（README.md）2.2 节
+> 适用：需要部署、运行、端口、配置、监控、日志、备份恢复或值班操作的应用。
+> 服务已有固定启动路径时以现状为准，模板用于登记和逐步补全。
+
+## 结构
+
+```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 必填项（服务卡片额外）
+
+监听地址和端口、启动方式、依赖服务、配置来源、数据权威路径、日志路径、健康检查、备份频率、恢复步骤入口、负责人。
+
+## 约束
+
+- 密钥不得进 Git；仅提交 `.env.example` 或 `config/examples/`
+- 源码版本用 Git tag；部署产物用镜像标签/发布版本，不复制 v1/v2 整套源码目录
+- data/ logs/ backup/ 可为软链接，但 README 必须写明真实路径
+- W2 不套 v2 三层结构；服务专用脚本与平台通用脚本分开，平台通用脚本归 W6
@@ -0,0 +1,36 @@
+# W3 工程型代码项目模板
+
+> 来源：三端统一目录规范（README.md）2.3 节
+> 适用：主要交付代码、库、命令行工具、模型或可构建软件；不以长期在线服务运行为主。
+
+## 结构
+
+```text
+<code-project>/
+├── README.md                    # 项目卡片和使用说明，必建
+├── .workspace.yaml              # 类型登记，新建必建
+├── src/                         # 主代码；按语言可替换为 app/、lib/
+├── tests/                       # 自动化测试
+├── examples/                    # 最小可运行示例
+├── config/                      # 非敏感配置样例
+├── data/
+│   ├── raw/                     # 原始数据，只读原则
+│   ├── processed/               # 可重建的中间数据
+│   └── output/                  # 程序输出
+├── research/                    # 需求、设计、实验和架构说明
+├── report/                      # 测试报告、发布说明、成果报告
+├── scripts/                     # 构建、发布、一次性辅助脚本
+├── logs/                        # 本地运行日志
+└── archive/                     # 冻结产物，不存源码版本副本
+```
+
+## 仓库根模式 vs 容器模式
+
+- **仓库根模式**：项目本身就是 Git 仓库时，src/tests 直接在根下，**不得再机械增加 code/ 包裹层**
+- **容器模式**：单项目目录同时包含大量非代码材料时，把 Git 仓库放在 code/ 中（即 v1 模式）
+
+## 命名与版本
+
+- 仓库名/代码目录：英文小写连字符（kebab-case），语言生态要求下可用下划线
+- 发布版本：语义化 Git tag（v1.2.0）
+- README 必须给出：安装、运行、测试、输入输出及版本方式
@@ -0,0 +1,40 @@
+# W4 知识库/档案型模板
+
+> 来源：三端统一目录规范（README.md）2.4 节
+> 适用：长期积累、整理、搜索和引用资料；内容生命周期长于单个项目。
+
+## 结构
+
+```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 登记映射，不立即搬动
@@ -0,0 +1,55 @@
+# W5 单项目目录模板
+
+> 来源：三端统一目录规范（README.md）2.5 节
+> 适用：一个目标、一个责任边界、有结束或冻结条件。该类直接承接 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/ 只保存冻结交付物，不保存整套源码副本
+
+## 项目卡片 README 模板
+
+```markdown
+# <项目名>
+## 基本信息
+- 分类: W5
+- 域: 科研 | 写作 | 学习 | 运维 | 生活
+- 归属端: 服务器 | 本机 | 华为 | 多端（注明主要端）
+- 父工作区: <如有>
+- 关联 profile: （如 server/engineer…）
+- 关联服务: （如 llm-wiki :8083，无则 —）
+## 结构说明
+（本项目有哪些目录、各自放什么，2-3 行）
+## 数据与 git
+- 数据本体: <绝对路径>
+- git 远端: <地址或 —>
+- 版本 tag: <最新 tag 或 —>
+## 状态
+- 最后更新: <日期>
+- 完成条件: <何时可冻结/归档>
+- 备份策略: <备份方式或 —>
+- 备注: <运维提示/已知问题>
+```
@@ -0,0 +1,43 @@
+# W6 共享资产层模板
+
+> 来源：三端统一目录规范（README.md）2.6 节
+> 适用：资产服务于多个独立工作区；不属于某一应用或某一项目。平台级分类。
+
+## 结构
+
+```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
+```
+
+## 规则
+
+- 共享子层可独立存在于顶层，不要求再包一层 shared-root/；上图表示逻辑结构
+- 每个顶层共享目录必须有自己的 README：准入条件、负责人、保留期限、清理规则
+- migration/ 必须登记来源、目标、负责人、截止日期；不得成为长期堆放区
+- logs/ 必须定义保留周期
+- assets/ 和 knowledge/ 的权威副本不得与各工作区复制并行维护
+- W6 中不直接混放普通项目
@@ -0,0 +1,17 @@
+# .workspace.yaml — 工作区/目录登记卡（schema_version: 1）
+# 每个受管目录根部必建。由 project-new 自动生成，存量由 workspace-tidy 波次0 补齐。
+# 规范来源：/srv/share/docs/standards/workspace-directory-standard/
+
+schema_version: 1
+name: example
+class: W5                # W1-W6，见 catalog.yaml
+profile: ""              # 辅助属性（如 content-workspace / agent-service / knowledge-store）
+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: []     # 如 ["llm-wiki:8083"]
+git_remote: ""           # 如 gitea 地址或 —