anian0/workspace-setup

Workspace Setup Skill

本 skill 管理所有项目都复用的工作区入口，并初始化项目独立维护的规则和知识库骨架。

三层结构

项目根目录/
├── AGENTS.md              ← 第 1 层：通用 AI 入口，所有项目内容一致
├── CLAUDE.md              ← 第 1 层：Claude 入口，通常只写 @AGENTS.md
├── PROJECT_RULES.md       ← 第 2 层：项目规则，每个项目独立维护
├── project-kb/            ← 第 3 层：项目知识库，每个项目独立维护
│   ├── README.md
│   └── code/              ← 按源码相对路径镜像的代码文件说明
│       └── README.md
├── workplace/             ← 需求、方案、计划、测试等过程文档
│   ├── 1.0/
│   └── archive/
├── skillconfig.json
└── skills/
    └── workspace-setup/

第 1 层：通用入口

AGENTS.md 和 CLAUDE.md 必须在所有项目保持一致，适合通过配置包统一同步。

职责：

• 声明通用协作、编码、验证和文档同步规则。
• 固定要求读取同级 PROJECT_RULES.md。
• 固定要求修改代码前读取 project-kb/code/ 中对应的代码文件说明。

不应包含：

• 某个项目的目录说明。
• 某个项目的测试命令。
• 某个项目的业务、架构、依赖或部署规则。

第 2 层：项目规则

PROJECT_RULES.md 是每个项目独立维护的必读文档。

职责：

• 列出当前项目修改代码前必须知道的规则。
• 说明重要文件、重要目录和修改风险。
• 链接到第 3 层项目知识库。
• 记录项目级验证命令和定向测试策略。

第 3 层：项目知识库

project-kb/ 是每个项目独立维护的知识库，由 personal-kb skill 负责维护规则。

关键约定：

• project-kb/code/ 按代码文件结构镜像。
• 每个代码文件对应一份说明文档。
• 说明文档记录功能点、相关文件、重要逻辑、测试文件和修改注意事项。
• 相关文件使用 Obsidian 双向链接。

skillconfig.json

{
  "workspace": {
    "config_pack": "config-1",
    "current_version": "1.0",
    "workplace_dir": "workplace",
    "project_rules_file": "PROJECT_RULES.md",
    "project_kb_dir": "project-kb"
  },
  "filebrowser": {
    "instance_url": "http://your-server:8080",
    "username": "admin",
    "password": "your-password",
    "remote_base_path": "/config"
  }
}

| 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | config_pack | string | 是 | 云端通用配置包名称 | | current_version | string | 是 | 当前过程文档版本号 | | workplace_dir | string | 否 | 过程文档目录，默认 workplace | | project_rules_file | string | 否 | 项目规则文件，默认 PROJECT_RULES.md | | project_kb_dir | string | 否 | 项目知识库目录，默认 project-kb | | instance_url | string | 是 | FileBrowser 服务地址 | | username | string | 是 | 登录用户名 | | password | string | 是 | 登录密码 | | remote_base_path | string | 否 | 云端顶层目录，默认 /config |

配置包同步边界

云端配置包只同步第 1 层通用入口和通用 skills：

/config/config-1/
├── AGENTS.md
├── CLAUDE.md
└── skills/

项目独立文件不进入通用配置包：

• PROJECT_RULES.md
• project-kb/
• workplace/

这样可以让所有项目使用相同的入口命令，同时保留各项目独立规则和知识。

脚本工具

| 脚本 | 文档 | 功能 | |---|---|---| | init_workspace.py | references/init-workspace.md | 初始化三层入口、过程文档目录，可下载通用配置 | | sync_config.py | references/sync-config.md | 同步第 1 层通用入口和可选 skills | | version_manager.py | references/version-manager.md | 创建版本、归档版本 | | skills_manager.py | references/skills-manager.md | 管理 npx skills 命令 |

快速命令

# 初始化工作区
python skills/workspace-setup/scripts/init_workspace.py --config skillconfig.json

# 从配置包下载通用 AGENTS.md/CLAUDE.md
python skills/workspace-setup/scripts/sync_config.py download --config skillconfig.json

# 上传通用 AGENTS.md/CLAUDE.md
python skills/workspace-setup/scripts/sync_config.py upload --config skillconfig.json

# 同步通用配置和 skills
python skills/workspace-setup/scripts/sync_config.py sync --config skillconfig.json --sync-skills

初始化流程

1. 读取 skillconfig.json。
2. 创建或保留 workplace/{current_version}/ 过程文档目录。
3. 下载或创建通用 AGENTS.md、CLAUDE.md。
4. 创建项目独立 PROJECT_RULES.md，如果已存在则不覆盖。
5. 创建项目独立 project-kb/README.md 和 project-kb/code/README.md，如果已存在则不覆盖。
6. 更新 skillconfig.json 中的当前版本号。

日常维护规则

• 修改通用入口规则后，使用 sync_config.py upload 上传到配置包。
• 修改项目规则或项目知识库时，不要上传到通用配置包。
• 如果某条规则多个项目都需要，迁移到 AGENTS.md。
• 如果某条规则只对当前项目有效，保留在 PROJECT_RULES.md。
• 修改代码后，使用 personal-kb 的代码镜像知识库规则同步更新 project-kb/code/。

过程文档目录

workplace/ 继续用于需求、方案、计划、测试和归档，不承担项目规则或代码知识库职责。

| 目录 | 用途 | |---|---| | requirements/ | 需求文档 | | references/ | 参考文档 | | prototypes/ | 原型设计 | | tech-design/ | 技术方案 | | plan/ | 实施计划 | | tests/ | 测试文件和测试计划 |