Project Init

project-init — Java 项目脚手架生成器

> ## ⚠️ 强制前置规则（最高优先级，不可跳过） > > 生成骨架前，必须先向用户发出「初始化表单」（见第 13 节）并等待用户填写贴回。 > 禁止用默认值直接调 merge.py 生成——用户极易忽略关键变量（groupId / 模块名 / 凭据占位 / 分支 / template）。 > > 唯一例外：用户明确表达"用默认""不要问""直接生成""全自动""跳过表单"等放弃输入的意图时，才可用默认/占位直接生成。表述模糊或未表态时，一律先发表单。 > > 执行顺序：检测空目录 → 发表单 → 等用户填回 → 组装 --var → 跑 merge.py。绝不允许从"检测目录"直接跳到 merge.py。

1. 定位

把一个空目录变成可立即 mvn package + 可构建镜像 + 可被 dev-lifecycle 接管的 Java Spring Boot 单体项目骨架。前置于 dev-spec，非必需：已有骨架则 dev-spec 直接开工，本 skill 不介入。

本 skill 是 dev-lifecycle 的第 0 个 cascade 节点（项目级、一次性）：生成骨架后写项目级状态 .dev-flow/project.json（phase=scaffold:done），停留 test 分支，移交 dev-spec 开始第一个功能的需求整理（feature 级 spec:intake）。

职责边界（绝不越界）：

| 动作 | 本 skill | dev-lifecycle | dev-spec | git-flow | ci-trigger | |---|:--:|:--:|:--:|:--:|:--:| | git init + initial commit + 建 test 分支 | ✅ | | | | | | pom / SpringBoot 骨架 / Dockerfile / build.sh / run.sh / rollback.sh / Jenkinsfile | ✅ | | | | | | .dev-flow.yml 种子（含 scaffold 块 + build-credentials） | ✅ | | | | | | .dev-flow/project.json 项目级状态（scaffold:done） | ✅ | 读取 | | | | | .gitignore（含 .dev-flow/） | ✅ | | | | | | docs/specs/ + docs/specs/_sources/ 空目录 | ✅ | | | | | | docs/checklist/build-readiness.md 人工质检清单 | ✅ | | | | | | scripts/check-build-ready.sh 机器自检 | ✅ | | | | | | README | ✅ | | | | | | spec 文档 | | | ✅ | | | | .dev-flow/states/.json feature 级状态 | | | ✅(首次写) | | | | Auto Cascade 0 移交 spec:intake | | ✅(编排) | | | | | feature 分支 | | | | ✅ | | | 编排 step 开发/集成 | | ✅(编排) | | | | | 触发 CI | | ✅(编排) | | | ✅ |

2. 触发条件

• 当前项目文件夹为空（无文件或仅有 .DS_Store 等无关文件）→ 触发整骨架 init。
• 用户明确指定创建子模块 → 触发增量模块生成（merge.py --add-module ，只生成模块级文件 + 根 pom `` 追加，不覆盖根级文件/状态/git）。
• 介于之间、判断不确定 → 先提一句问用户"是否需要初始化骨架 / 新增子模块?"，不要擅自生成。

3. 核心变量体系

真正独立的输入只有三个，其余派生或固定：

| 变量 | 含义 | 来源优先级 | 固定? | |---|---|---|---| | project.name | 最外层文件夹名 = 父 POM artifactId | spec > dir_name > prompt > default | 否 | | project.groupId | 父=子共用 groupId（默认 com.own.{short}） | spec > prompt > default | 否 | | core.module.name | 核心模块文件夹名 = 子 artifactId = finalName | spec > prompt > default({project.name}-server) | 否 | | version | — | — | 固定 1.0.0-SNAPSHOT | | packaging.parent | — | — | 固定 pom | | packaging.module | — | — | 固定 jar | | branch.production | 生产分支 | spec > prompt > default | 否（默认 master） | | branch.test | 测试分支 | spec > prompt > default | 否（默认 test） | | developers | {key: {name}} 至少一个 | spec > git config > prompt | 否 |

派生关系（合并器自动算，不问用户）：

parent.artifactId = ${project.name}
module.groupId    = ${project.groupId}      # 继承父，子 pom 不显式写 groupId
module.artifactId = ${core.module.name}     # = 文件夹名
module.folder     = ${core.module.name}     # 物理目录与 artifactId 同名
finalName         = ${core.module.name}     # 供 Dockerfile ADD 稳定引用

{short} 半自动派生：从 project.name 取小写字母简写（去日期前缀如 20260708、去常见后缀），派生不出则留给 prompt 补全。

来源链最高优先级：背景实施方案文档

用户自写的 markdown，通常在当前项目内，是 dev-spec 的输入，不是 dev-spec 的产出。本 skill 只从中抽取项目结构变量（groupId/artifactId/模块名/版本/开发者/分支），绝不消费需求/功能/验收内容（那是 dev-spec 的事）。

获取与解析契约：

1. 模糊搜索当前项目 .md：命中「实施方案/项目结构/groupId/artifactId/模块」等关键词的文档为候选。
2. 候选唯一 → 直接用；候选多个 → 列给用户确认；无候选 → 提示词问"是否有实施方案文档，路径?"
3. 从确认文档按模式抽取结构字段（正则匹配 groupId/artifactId/version/module 等）。
4. 抽不到的字段 → 回退 prompt → 回退 default。抽取失败不阻断，只降级到手动输入。

4. 扩展机制：template + mixin（非继承）

产物 = java-maven-base mixin ∪ fastjson2-hutool mixin ∪ template ∪ jenkins-docker-ci mixin

每个项目类型是一个独立模板（templates//），自包含全部版本敏感件，不 extends 任何模板，零 exclude、零覆盖。共享件通过可挂载的 mixin 复用，而非继承。

• mixins/java-maven-base/：版本无关骨架（父/子 pom 骨架、logback、application 三件套、README、.gitignore、Application.java、docs 骨架、测试骨架）。所有 Java Maven 项目共享。版本敏感件（RequestIdFilter、各 template 的 pom 片段）不在 mixin，在各 template 自持。
• mixins/fastjson2-hutool/：技术偏好栈（fastjson2 + hutool + lombok + guava），跨 template 正交。P0 仅此一个。
• templates//：项目类型，独立模板。P0 两型：
• java-web（java8 + Boot2.7 + SpringMVC + javax）：自包含 javax 版 RequestIdFilter + HealthController。
• java-mcp（java21 + Boot3.5 + Spring AI 1.0.x + jakarta）：自包含 jakarta 版 RequestIdFilter + ExampleTools，自带 web/validation/actuator 依赖（不继承 java-web）。
• mixins/jenkins-docker-ci/：CI 类型。P0 仅此。未来 k8s-ci 作为扩展（替换 deploy 段，不碰 template 层）。

叠加优先级（冲突时后者覆盖前者，文件级 to 路径覆盖）：java-maven-base **禁用 maven.compiler.release**：--release 是 Java 9+ 的 javac flag，Java 8 项目（java-web，构建容器 maven:3-alpine=Java 8）的 javac 8 不识别 → Fatal error compiling: invalid flag: --release。统一用 source/target`（全版本兼容，Java 8 javac 正常）。

5. 生成流程（9 步）

1. 检测目录（入口保护，fail-fast）：空且无 project.json → 继续；已 init（.dev-flow/project.json 为 scaffold:done）或非空（排除 .DS_Store/.git）→ 直接退出拒绝覆盖，提示用 --add-module 或清空目录。防全量覆盖已有项目。
2. 收集变量（强制交互，不可跳过）：先发第 13 节「初始化表单」并等用户填回，再据此组装 --var。禁止用默认值直接调 merge.py——只有用户明确放弃输入时才用默认/占位。来源链仅用于表单默认值与 spec-doc 抽取后的回退。
3. 版本查证：跑 validators/version-check.sh，按 compat-table.yml 声明的系列（如 1.0.x）从 maven-metadata.xml 筛该系列最大 GA（不取全局 latest），填入版本变量。查不到 → fail-fast 报具体 artifact。
4. 兼容性校验：跑 compat-table.yml，按 template 校验 Spring AI↔Boot、Java 四处一致性；不过 fail-fast 报具体原因。
5. 叠加生成：lib/merge.py 按 java-maven-base ∪ fastjson2-hutool ∪ template ∪ jenkins-docker-ci 叠加，pom 走占位替换，其余文件整文件覆盖（后层覆盖前层）。
6. 占位替换：替换所有 ${var} 与 REPLACE_WITH_*；凭据只留占位或 ${ENV_VAR} 引用，绝不写明文。
7. 生成 README：顶部「项目结构」节由变量实例化填入（父/子 pom、启动类、finalName、配置加载链路、file: 绝对路径坑说明）。
8. 生成 .dev-flow.yml 种子 + 项目级状态：读 dev-lifecycle/templates/java-maven-jenkins.yml 填充变量；写顶层 scaffold 块（template/ready=true/java-version/boot-version/initialized-at/generated-by）；追加 ci.jenkins.build-credentials 段（gitee-id / maven-file-id / docker-creds-id，全部 REPLACE_WITH_* 占位）；调 dev-lifecycle resolver 写 .dev-flow/project.json（phase=scaffold:done、scaffold.ready=true）。不建 feature 级状态（由 dev-spec intake 建）。
9. 收尾：见第 6 节。

6. 收尾动作（git init + initial commit + 停 test）

1. git init
2. git branch -M master                              # 强制 production 分支名=master（新版 git 默认可能 main）
3. git add -A && git commit -m "init: 项目骨架"       # master 上 initial commit
4. git branch test                                   # 从 master 切出 test
5. git checkout test                                 # 停留在 test
6. 不 push（无远程/未配置也不报错，呼应"无远程仓库"坑）

收尾后 project.json 的 phase=scaffold:done，dev-lifecycle Auto Cascade 0 提示「骨架已就绪，停 test 分支。开始第一个功能的需求整理？」用户确认 → dev-spec intake 建 feature 级状态，进入 spec:intake。

7. 安全红线（不可覆盖）

• 凭据全托管 Jenkins：gitee/docker/maven 凭据存 jenkins credentials store，不进代码仓库、不进 agent 上下文、不进 docker 镜像。.dev-flow.yml 的 ci.jenkins.build-credentials 只存 REPLACE_WITH_* 引用标识，不存值。
• agent 唯一直接用的凭据是 jenkins 触发层 env（JENKINS_URL/USER/TOKEN），由 ci-trigger 使用，agent 不读明文。
• 新增第三方依赖需明确许可（如 logstash-logback-encoder）。
• 版本不入库硬编码：manifest 只声明系列（1.0.x），具体 patch 由 version-check 实时解析。
• 实施方案文档只抽结构不碰需求。

8. 机器自检 + 人工质检双轨

构建前两条检查互补：

• 机器自检 scripts/check-build-ready.sh（本 skill 生成到项目）：三层
• L1 复用 ci-trigger --check-env（JENKINS_URL/USER/TOKEN）+ --validate-config（.dev-flow.yml + ci.system + ci.jenkins.job）。
• L2 自写：用 jenkins env 调 GET /credentials/store/system/domain/_/api/json?tree=credentials[id]，验证 .dev-flow.yml 声明的 gitee-id / docker-creds-id 存在；maven-file-id 软检查（config-file-provider 不同插件 API，触发时 jenkins 自验）。
• L3 自写：curl registry/v2/ ping 网络可达（200 或 401 都算可达，不 login）。
• 全绿才让 ci-trigger 触发构建。
• 人工质检 docs/checklist/build-readiness.md（本 skill 生成）：机器验不了的项——jenkins UI 配凭据、run.sh/rollback.sh 复制到部署服务器、服务器 docker/目录、registry 真 push 可达、首次全链路构建。

一致性硬契约

check-build-ready.sh L2 读 .dev-flow.yml 的 build-credentials 声明去验，隐含信任"Jenkinsfile 用的 credentialsId 与声明一致"。所以 Jenkinsfile 与 .dev-flow.yml 的 build-credentials 必须由 merge.py 用同一组变量同源生成，保证两处 id 一致。这是本 skill 的硬契约。

9. 回滚

部署服务器维护 append-only 版本历史 .deploy-history（JSON lines，放外置配置目录，不入 git，与 .dev-flow/ 状态严格分离）：

• run.sh 成功部署后追加一条 deploy 记录。
• rollback.sh 从末尾回扫，跳过与当前 version 相同的条目，取第一个不同 version 作回滚目标 → pull 旧 tag → 替换容器 → 追加 rollback 记录。支持多级回滚。
• 镜像策略：registry 不删历史 version tag + 本地不 rmi（保留回滚源，呼应背景文档"不删镜像"优化）。

回滚不进 dev-lifecycle V1 cascade（V1 到 deployed-test 停），由人手动触发。.deploy-history 不入 .dev-flow/ 状态。

10. 版本基线（2026-07-09 查证，仅参考，落地以 version-check 实时解析为准）

| 依赖 | P0 选用系列 | 实测最新 GA | |---|---|---| | Spring Boot | java-web=2.7.x / java-mcp=3.5.x | 2.7.18 / 3.5.16 | | Spring AI BOM | java-mcp=1.0.x | 1.0.9 | | spring-ai-starter-mcp-server-webmvc | java-mcp=1.0.x | 1.0.9 | | fastjson2 | fastjson2-hutool=2.0.x | 2.0.62 | | hutool-all | fastjson2-hutool=5.8.x | 5.8.46 |

> Spring AI 2.0.0 / Boot 4.1.0 已 GA，但 P0 选稳定线（1.0.9 / 3.5.16 / 2.7.18）。升最新栈前需官方确认 Spring AI 2.0.0↔Boot 4.x 兼容性。

11. 实施方案文档解析的边界

只读"项目结构"段（groupId/artifactId/模块名/版本/开发者/分支），不读需求/功能/验收——后者原样留给 dev-spec 消费。抽不到不阻断，降级到 prompt/default。

12. 运行依赖

• Python 3.10+ + PyYAML（pip3 install --user pyyaml）。lib/merge.py 用 pyyaml 解析 manifest 与 dev-lifecycle 模板。
• curl（validators/version-check.sh 查 maven-metadata.xml）。
• git（收尾 init/commit）。
• 依赖 sibling skills：dev-lifecycle（.dev-flow.yml 模板与 schema、resolver）、ci-trigger（check-build-ready.sh L1 复用其 --check-env/--validate-config）。三者需安装在同级 skills 根目录（各 agent 的安装根不同，见 adapters/ 对应文件）。

13. 交互引导（强制前置，不可跳过）

生成前必须先发此表单并等用户填回（见顶部强制规则）。只有用户明确放弃输入时才跳过用默认。用户填回后据此组装 merge.py --var k=v。表单值映射：docker registry→registry、jenkins job 名→jenkins.job、gitee 凭据 id→gitee.credential.id、maven settings fileId→maven.settings.file.id、docker 凭据 id→docker.creds.id、git 仓库 url→git.repo.url、服务端口→server.port、部署根目录→deploy.root，其余同名；developers 传 JSON（zx:张三→'{"zx":{"name":"张三"}}'）。留空=走默认或占位。server.port/deploy.root 留空时回退 manifest 默认（server.port=8080(java-web)/8700(java-mcp)，deploy.root=/opt/app）；两者强烈建议显式填写——端口须与目标环境不冲突，deploy.root 须与实际服务器目录一致（/opt/app 仅为占位约定，多数服务器并非此路径）。

==== project-init 初始化表单 ====
1.  template (二选一)    : [ ] java-web   [ ] java-mcp
2.  project.name          [默认=目录名]            :
3.  project.groupId       [默认=com.own.]    :
4.  core.module.name      [默认=-server]     :
5.  developers            [默认=git config user]   :  例 zx:张三
6.  branch.production     [默认=master]            :
7.  branch.test           [默认=test]              :
8.  ci-type               [默认=jenkins-docker-ci] :
9.  tech-pref             [默认=fastjson2-hutool]  :
10. server.port          [默认=8080(web)/8700(mcp)]:  服务启动端口，须与目标环境不冲突
11. spec-doc (实施方案md路径，可选)                :
12. docker registry       : 例 registry.example.com
13. namespace.test        : 例 example-test
14. namespace.prod        : 例 example-prod
15. jenkins job 名        : 例 example-pipeline
16. gitee 凭据 id         :
17. maven settings fileId :
18. docker 凭据 id        :
19. git 仓库 url          : 例 https://gitee.com/your-org/your-repo.git
20. deploy.root           [默认=/opt/app]           :  部署根目录，须与实际服务器目录一致（run.sh/rollback.sh 的 CONFIG_DIR/LOG_DIR 前缀）

最简触发：初始化 java 项目，type=java-mcp（其余全默认/占位直接生成）。

增量模块（已有项目新增子模块）

在已 init 的 project-init 项目里新增子模块（不覆盖根级文件/状态/git）：

python3 lib/merge.py --project-dir /path/to/existing-project \
  --project-type java-mcp --add-module new-mod --var developers='{"zx":{"name":"张三"}}'

• 只生成模块级文件（/pom.xml、Application、源码、logback、application 三件套），根 pom `` 追加一行（去重）。
• 变量从现有 .dev-flow.yml（project.name/branching）+ 根 pom.xml（groupId）复用，不重新收集、不发表单。
• 不动 .dev-flow.yml / .dev-flow/project.json / git 状态（分支已在用）。
• 模块名须匹配 ^[a-z][a-z0-9-]*$；groupId 解析失败时用 --var project.groupId= 传入。

14. java 版本严格性（强制）

mixins/java-maven-base 与 templates/java-web 提供的 java 代码必须用 java8 兼容语法（java-web=java8，且 java-maven-base 的共享件被 java-web 复用——Application/ApplicationTests/HealthController/RequestIdFilter(javax) 必须在 java8 下编译通过）。禁用 java9+ 语法：Map.of/List.of/Set.of（改用 new HashMap 加 put）、var、record、文本块、switch yield。

templates/java-mcp 是独立模板（java21），不继承 java-web 的任何文件，其自有文件（RequestIdFilter(jakarta) / ExampleTools 等）可用 java21 语法。java-maven-base 的共享件（Application/ApplicationTests 等）被 java-mcp 复用时仍需 java8 兼容——这是 mixin 复用的唯一代价，可接受。

第三方依赖版本按 template 的 java/logback 选：logstash-logback-encoder java-web=6.x（logback 1.2.x / java8），java-mcp=8.x（logback 1.5.x / java21）；7.0+ 需 logback 1.3+，与 Boot2.7 不兼容（启动报 NoSuchMethodError getInstant）。Spring AI 仅 java17+，java-web 不可用。

Agent 适配

本 skill 的 SKILL.md 保持 agent-neutral。需要适配具体 agent 时，只读取对应 adapter：

• Claude Code: adapters/claude-code.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: linshidream
• Source: linshidream/skill-hub
• License: MIT

Install and usage instructions live in the source repository linked above.