用途:初始化或更新基于 dev-config-template 的多仓库工作区。触发场景包括:刚用该模板创建仓库并想完成配置;用户说“初始化工作区”“设置项目”“配置工作区”;提到 dev-config-template 并寻求入门帮助;或想把现有工作区更新到最新模板。
依赖工具:git、jq(brew install jq 或 sudo apt install jq)、openspec(npm install -g openspec)。技能加载时不校验,而是在第 2 阶段开始前检查,缺失则给出安装说明并等待确认。
初始化流程分 5 个阶段:1)交互收集信息,逐个询问项目名称、描述、角色、经验水平、语言偏好、技术栈(Python/TypeScript/mixed)及对应的格式化、lint、类型检查、测试工具,再循环收集子仓库(名称、Git URL、描述),最后汇总确认。2)搭建结构:校验依赖后生成 repos.json,替换 CLAUDE.md 占位符,运行 ./script/setup 克隆子仓库。3)执行 openspec init 并生成 openspec/config.yaml。4)为每个子仓库配置环境:Python 用 python3 -m venv venv、source venv/bin/activate、pip install -e ".[dev]" 或 pip install -e .;TypeScript 按 bun.lockb 选择 bun install 或 npm install;存在 .pre-commit-config.yaml 则 pre-commit install;并生成 {project-name}.code-workspace。5)写入模板版本 .workspace-init-version、提交(不自动 push)、运行 scripts/validate.py 校验,并提示后续步骤。
更新模式:读取本地版本 SHA,获取远端 HEAD 对比,展示变更文件与不会被改动的自定义文件,确认后应用更新(CLAUDE.md 保留用户已填值再套用新模板),更新版本文件并提交。永不改动 repos.json、openspec/、repos/、.claude/。
限制与注意:需要 git、jq、openspec 等前置工具;克隆失败多因 SSH 未配置;venv 创建失败可能因 Python 版本低于 3.10;gh 不可用时版本可写 unknown,更新会显示全部模板变更。