# Project Init

> Initialize a Java Maven Spring Boot project scaffold into an empty directory (or add a new child module to an existing one). Generates parent/child POM, logback, layered application config, README, docs/ skeleton, test skeleton, Dockerfile/build.sh/run.sh/rollback.sh, Jenkinsfile, build-readiness checklist, and a .dev-flow.yml seed (with scaffold block + build-credentials) plus project-level stat…

- **Type:** Skill
- **Install:** `agentstack add skill-linshidream-skill-hub-project-init`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [linshidream](https://agentstack.voostack.com/s/linshidream)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [linshidream](https://github.com/linshidream)
- **Source:** https://github.com/linshidream/skill-hub/tree/master/skills/dev/project-init

## Install

```sh
agentstack add skill-linshidream-skill-hub-project-init
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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**）：

```bash
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](https://github.com/linshidream)
- **Source:** [linshidream/skill-hub](https://github.com/linshidream/skill-hub)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-linshidream-skill-hub-project-init
- Seller: https://agentstack.voostack.com/s/linshidream
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.