project-initializer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Initializer

项目初始化工具

A skill for scaffolding new projects with consistent README.md, AGENTS.md, and CI/CD pipelines — all wired together with an SDD (Spec-Driven Development) framework.

一款用于快速搭建新项目的技能，可生成格式统一的README.md、AGENTS.md文件及CI/CD流水线，并与SDD（规范驱动开发）框架深度集成。

Overview

概述

The skill does five things:

Interview — Understand the project's goals, tech stack, coding standards, quality requirements, CI platform(s), and preferred SDD workflow.
Generate — Create README.md, AGENTS.md, and CI pipeline file(s) from templates.
Integrate — Install SDD framework tools and initialize project structure; wire coding standards and quality checks into the CI pipeline.
Tag — Embed a machine-readable project identity tag in AGENTS.md so server-side CI can verify the project was properly initialized.
Verify consistency — Make sure all generated files agree with each other (same tech stack, same quality gates, same SDD expectations).

本技能主要完成五项核心工作：

需求访谈 — 了解项目目标、技术栈、编码规范、质量要求、CI平台偏好及SDD工作流。
文件生成 — 基于模板创建README.md、AGENTS.md及CI流水线配置文件。
框架集成 — 安装SDD框架工具并初始化项目结构，将编码规范与质量检查逻辑接入CI流水线。
身份标记 — 在AGENTS.md中嵌入机器可读的项目身份标签，供服务端CI验证项目是否完成合规初始化。
一致性校验 — 确保所有生成文件的信息一致（如技术栈、质量门槛、SDD预期等）。

Phase 1: Interview

第一阶段：需求访谈

使用

AskUserQuestion

与用户进行访谈，了解项目情况。逐个问题与用户交互 — 不要跳过问题或代表用户做出决定。在进入第2阶段（文件生成）前，总结他们的答案并确认理解。

根据已有的上下文信息，可以一次性提出所有问题，也可以在自然对话中分散提问 — 根据情况自行判断。

必需信息：

对于以下每个问题，使用

AskUserQuestion

与用户交互式提问。不要跳过问题，不要代替用户做决定。当提供建议或默认值时，请通过

AskUserQuestion

确认用户同意后再继续。

项目名称和一句话描述 — 使用
```
AskUserQuestion
```
。这个项目是什么？它解决了什么问题？
项目类型 — 使用
```
AskUserQuestion
```
确认项目属于哪一类，以便在 Phase 2 执行对应的初始化流程（见下方「按项目类型生成」）：
- 通用 — 仅生成 README、AGENTS.md、CI 与 SDD，不生成框架骨架
- Flask 后端 — 在本技能内直接生成 Flask API 项目骨架（应用工厂、Blueprint、Service/Model 分层、uv、测试等），参考
```
references/flask-backend.md
```
  与
```
assets/flask-backend/
```
- React 前端 — 在本技能内直接生成 React 前端骨架（Vite + Rolldown、React + TypeScript、Ant Design、Vitest、目录与配置等），见下方「React 前端初始化」
- Taro 小程序 — 在本技能内按 Taro 官方 CLI 初始化、目录、代理、README/AGENTS，见下方「Taro 小程序初始化」
- 其他 — 仅通用文件选择后，Phase 2 在生成通用文件之外，按类型执行对应骨架生成，不引用、不调用任何独立 init-* 技能。
技术栈 — 编程语言、框架、包管理工具、数据库、部署目标等。使用
```
AskUserQuestion
```
提示用户。用户表示不确定或要求建议时，根据问题领域提供合理的默认值 — 但通过
```
AskUserQuestion
```
获得用户确认后再继续。
质量等级 — 使用
```
AskUserQuestion
```
提问：这是演示/原型项目还是生产项目？
- 演示：最小化CI、无覆盖率门槛、无安全扫描、轻量级SDD
- 生产：完整CI、覆盖率门槛、安全扫描、严格的SDD对齐检查

SDD框架 — 使用

AskUserQuestion

展示所有三个选项，询问团队将使用哪一个。包括下面的描述以帮助他们做出决定。

框架	风格	适用于
OpenSpec	流畅、棕地优先、增量规范	现有代码库、个人开发者、迭代工作
SpecKit	宪法强制、分阶段	团队、企业、严格的质量标准
GSD	基于阶段的路线图、上下文工程	想让AI做主力工作的个人开发者

选择后，阅读相应的参考文件了解更多细节：
OpenSpec →
references/openspec.md
SpecKit →
references/speckit.md
GSD →
references/gsd.md

CI平台 — 使用
```
AskUserQuestion
```
提问：应该配置哪些CI系统？
- GitLab CI — 生成
```
.gitlab-ci.yml
```
- GitHub Actions — 生成
```
.github/workflows/ci.yml
```
- 两者 — 生成两个文件，保持一致
主分支名称 — 使用
```
AskUserQuestion
```
提问哪个分支会触发发布流程。建议用
```
main
```
作为默认值，但要向用户确认。
编码规范 — 使用
```
AskUserQuestion
```
提问：团队是否有现有的编码规范、风格指南或代码检查配置？
- 直接粘贴内容 — 用户将规范粘贴到对话中
- 文件路径 — 用户提供现有文件的路径（如
```
docs/coding-standards.md
```
  、
```
.eslintrc.json
```
  ）
- 无 — 如果没有，使用技术栈的合理默认值
如果提供了规范，请阅读并总结。规范将被注入到AGENTS.md中，并用于配置CI代码检查命令。
额外质量要求（生产项目）— 使用
```
AskUserQuestion
```
提问：
- 最小测试覆盖率百分比（如 80%）
- 静态分析工具（如 ESLint、Pylint、SonarQube）— 可能已被编码规范涵盖
- 安全扫描（Trivy、Semgrep、Bandit等）
文档语言 — 使用
```
AskUserQuestion
```
提问：README.md和AGENTS.md应该用什么语言编写？默认为中文（中文），除非用户指定其他语言。
Python + GitLab CI 规范（仅当技术栈含 Python 且选择了 GitLab CI 时）— 使用
```
AskUserQuestion
```
询问：是否采用 backend-python-cicd 规范？若选是，则生成/校验
```
.gitlab-ci.yml
```
、Dockerfile、部署脚本时须遵循本技能
```
references/backend-python-cicd.md
```
与
```
assets/backend-python-cicd/
```
（私有镜像源、多阶段构建、分支 develop/bugfix/hotfix/master、dev→prod K8s 部署、先本地 Docker 构建再 Git 推送）。
QA/测试规范 — 使用
```
AskUserQuestion
```
询问：是否在 AGENTS.md 中引用 QA/测试规范（测试计划、用例、自动化与报告、缺陷根因分析）？若选是，在 AGENTS 中增加「测试与根因分析」说明或引用本技能
```
references/qa-testing.md
```
。
多角色/子代理 — 使用
```
AskUserQuestion
```
询问：是否需要 多角色规划与子代理（.cursor/agents/*.md）？若选是，在 Phase 2 后按本技能
```
references/agent-roles.md
```
与
```
assets/agent-roles/
```
执行角色规划与子代理文件生成。

使用

AskUserQuestion

根据已有的上下文信息，可以一次性提出所有问题，也可以在自然对话中分散提问 — 根据情况自行判断。

必需信息：

对于以下每个问题，使用

AskUserQuestion

与用户交互式提问。不要跳过问题，不要代替用户做决定。当提供建议或默认值时，请通过

AskUserQuestion

确认用户同意后再继续。

项目名称和一句话描述 — 使用
```
AskUserQuestion
```
。这个项目是什么？它解决了什么问题？
项目类型 — 使用
```
AskUserQuestion
```
确认项目属于哪一类，以便在第二阶段执行对应的初始化流程（见下方「按项目类型生成」）：
- 通用 — 仅生成 README、AGENTS.md、CI 与 SDD 相关文件，不生成框架骨架
- Flask 后端 — 在本技能内直接生成 Flask API 项目骨架（应用工厂、Blueprint、Service/Model 分层、uv、测试等），参考
```
references/flask-backend.md
```
  与
```
assets/flask-backend/
```
- React 前端 — 在本技能内直接生成 React 前端骨架（Vite + Rolldown、React + TypeScript、Ant Design、Vitest、目录与配置等），见下方「React 前端初始化」
- Taro 小程序 — 在本技能内按 Taro 官方 CLI 初始化、目录、代理、README/AGENTS，见下方「Taro 小程序初始化」
- 其他 — 仅生成通用文件选择后，第二阶段在生成通用文件之外，按类型执行对应骨架生成，不引用、不调用任何独立 init-* 技能。
技术栈 — 编程语言、框架、包管理工具、数据库、部署目标等。使用
```
AskUserQuestion
```
提示用户。用户表示不确定或要求建议时，根据问题领域提供合理的默认值 — 但通过
```
AskUserQuestion
```
获得用户确认后再继续。
质量等级 — 使用
```
AskUserQuestion
```
提问：这是演示/原型项目还是生产项目？
- 演示：最小化CI配置、无覆盖率门槛、无安全扫描、轻量级SDD
- 生产：完整CI流程、覆盖率门槛、安全扫描、严格的SDD对齐检查

SDD框架 — 使用

AskUserQuestion

展示所有三个选项，询问团队将使用哪一个。包括下面的描述以帮助他们做出决定。

框架	风格	适用于
OpenSpec	流畅、棕地优先、增量规范	现有代码库、个人开发者、迭代工作
SpecKit	强制约束、分阶段推进	团队、企业、严格的质量标准
GSD	基于阶段的路线图、上下文工程	希望让AI主导开发工作的个人开发者

选择后，阅读相应的参考文件了解更多细节：
OpenSpec →
references/openspec.md
SpecKit →
references/speckit.md
GSD →
references/gsd.md

CI平台 — 使用
```
AskUserQuestion
```
提问：应该配置哪些CI系统？
- GitLab CI — 生成
```
.gitlab-ci.yml
```
- GitHub Actions — 生成
```
.github/workflows/ci.yml
```
- 两者 — 生成两个文件，保持配置一致
主分支名称 — 使用
```
AskUserQuestion
```
提问哪个分支会触发发布流程。建议用
```
main
```
作为默认值，但要向用户确认。
编码规范 — 使用
```
AskUserQuestion
```
提问：团队是否有现有的编码规范、风格指南或代码检查配置？
- 直接粘贴内容 — 用户将规范粘贴到对话中
- 文件路径 — 用户提供现有文件的路径（如
```
docs/coding-standards.md
```
  、
```
.eslintrc.json
```
  ）
- 无 — 如果没有，使用技术栈的合理默认值
如果提供了规范，请阅读并总结。规范将被注入到AGENTS.md中，并用于配置CI代码检查命令。
额外质量要求（生产项目）— 使用
```
AskUserQuestion
```
提问：
- 最小测试覆盖率百分比（如 80%）
- 静态分析工具（如 ESLint、Pylint、SonarQube）— 可能已被编码规范涵盖
- 安全扫描（Trivy、Semgrep、Bandit等）
文档语言 — 使用
```
AskUserQuestion
```
提问：README.md和AGENTS.md应该用什么语言编写？默认为中文，除非用户指定其他语言。
Python + GitLab CI 规范（仅当技术栈含 Python 且选择了 GitLab CI 时）— 使用
```
AskUserQuestion
```
询问：是否采用 backend-python-cicd 规范？若选是，则生成/校验
```
.gitlab-ci.yml
```
、Dockerfile、部署脚本时须遵循本技能
```
references/backend-python-cicd.md
```
与
```
assets/backend-python-cicd/
```
（私有镜像源、多阶段构建、分支 develop/bugfix/hotfix/master、dev→prod K8s 部署、先本地 Docker 构建再 Git 推送）。
QA/测试规范 — 使用
```
AskUserQuestion
```
询问：是否在 AGENTS.md 中引用 QA/测试规范（测试计划、用例、自动化与报告、缺陷根因分析）？若选是，在 AGENTS 中增加「测试与根因分析」说明或引用本技能
```
references/qa-testing.md
```
。
多角色/子代理 — 使用
```
AskUserQuestion
```
询问：是否需要 多角色规划与子代理（.cursor/agents/*.md）？若选是，在第二阶段后按本技能
```
references/agent-roles.md
```
与
```
assets/agent-roles/
```
执行角色规划与子代理文件生成。

Phase 2: File Generation

第二阶段：文件生成

CRITICAL — Template Fidelity: Reproduce every CI pipeline template verbatim. Substitute only the
{{PLACEHOLDER}}
tokens. Do not remove, merge, rename, or omit any stages, jobs, or comment blocks. The complete job set in each template is the minimum viable pipeline; dropping any job will break SDD checks, project-tag validation, or coverage gates. For demo projects, dial down strictness through placeholder values (e.g., set
{{COVERAGE_THRESHOLD}}
to
0
,
{{SECURITY_SCAN_CMD}}
to
echo "skipped"
) — never by removing jobs.

After gathering information, generate files. Use the templates in

assets/templates/

as starting points and fill in the placeholders.

Path resolution — read this before running any script:
<skill_dir>
= the directory that contains this SKILL.md file (e.g.
.agents/skills/project-initializer
). All script paths below are relative to
<skill_dir>
.
<project_root>
= the root of the project being initialized — pass
.
if you are already inside it, or the absolute path if not. Never pass a path outside the project the user is working on.

File locations:

```
README.md
```
— project root
```
AGENTS.md
```
— project root
```
.gitlab-ci.yml
```
— project root (if GitLab CI selected)
```
.github/workflows/ci.yml
```
— project root (if GitHub Actions selected)

Placeholder convention used in templates:

{{VARIABLE_NAME}}

After creating all files, do a consistency pass:

The tech stack in README.md must match AGENTS.md and the CI environment images
Quality gates in CI files must reflect what's specified in AGENTS.md
The SDD check script path must match the framework chosen
Both CI files (if both selected) must use the same quality thresholds, check scripts, and branch names

关键要求 — 模板保真度： 严格完整地复现每个CI流水线模板，仅替换
{{PLACEHOLDER}}
标记。禁止删除、合并、重命名或省略任何阶段、任务或注释块。每个模板中的完整任务集是最小可行流水线；删除任何任务都会破坏SDD检查、项目标记验证或覆盖率门槛。对于演示项目，可通过占位符值降低严格性（例如将
{{COVERAGE_THRESHOLD}}
设置为
0
，
{{SECURITY_SCAN_CMD}}
设置为
echo "skipped"
）—— 绝不要通过删除任务来实现。

收集完信息后，生成文件。以

assets/templates/

中的模板为起点，填充占位符。

路径解析 — 运行脚本前请阅读：
<skill_dir>
= 包含本SKILL.md文件的目录（例如
.agents/skills/project-initializer
）。以下所有脚本路径均相对于
<skill_dir>
。
<project_root>
= 待初始化项目的根目录 — 若已在项目目录内则传入
.
，否则传入绝对路径。绝不要传入用户当前工作项目之外的路径。

文件位置：

```
README.md
```
— 项目根目录
```
AGENTS.md
```
— 项目根目录
```
.gitlab-ci.yml
```
— 项目根目录（若选择GitLab CI）
```
.github/workflows/ci.yml
```
— 项目根目录（若选择GitHub Actions）

模板中使用的占位符约定：

{{VARIABLE_NAME}}

创建所有文件后،执行一致性检查：

README.md中的技术栈必须与AGENTS.md和CI环境镜像一致
CI文件中的质量门槛必须与AGENTS.md中指定的一致
SDD检查脚本路径必须与所选框架匹配
若同时生成了两个CI文件，必须使用相同的质量阈值、检查脚本和分支名称

README.md

Read

assets/templates/README.template.md

. Fill in:

```
{{PROJECT_NAME}}
```
— project name
```
{{PROJECT_DESCRIPTION}}
```
— one-paragraph description
```
{{TECH_STACK_LIST}}
```
— bulleted list of stack components
```
{{SDD_FRAMEWORK}}
```
— name of chosen SDD framework
```
{{SDD_DOCS_PATH}}
```
— where SDD documents live (see framework reference)
```
{{GETTING_STARTED_STEPS}}
```
— installation and run steps appropriate for the tech stack

Language: Generate this file in the language chosen in Phase 1 (default: Chinese/中文).

读取

assets/templates/README.template.md

，填充以下内容：

```
{{PROJECT_NAME}}
```
— 项目名称
```
{{PROJECT_DESCRIPTION}}
```
— 一段描述文字
```
{{TECH_STACK_LIST}}
```
— 技术栈组件的无序列表
```
{{SDD_FRAMEWORK}}
```
— 所选SDD框架的名称
```
{{SDD_DOCS_PATH}}
```
— SDD文档的存放位置（见框架参考文件）
```
{{GETTING_STARTED_STEPS}}
```
— 适合该技术栈的安装与运行步骤

语言：按第一阶段选择的语言生成（默认：中文）。

AGENTS.md

Read

assets/templates/AGENTS.template.md

. Fill in:

```
{{PROJECT_NAME}}
```
— project name
```
{{PROJECT_DESCRIPTION}}
```
— concise single-sentence summary
```
{{TECH_STACK_DETAILS}}
```
— structured tech stack list with versions if known
```
{{SDD_FRAMEWORK}}
```
— framework display name (e.g., "OpenSpec")
```
{{SDD_FRAMEWORK_ID}}
```
— framework lowercase id:
```
openspec
```
,
```
speckit
```
, or
```
gsd
```
```
{{SDD_WORKFLOW_SUMMARY}}
```
— 3-5 bullet points describing the team's SDD workflow from the reference doc
```
{{QUALITY_LEVEL}}
```
— "demo" or "production" (display)
```
{{QUALITY_LEVEL_ID}}
```
— "demo" or "production" (machine-readable, same as display)

{{CI_PLATFORMS_ID}}

—

gitlab

github

, or

gitlab,github

(no spaces)

```
{{COVERAGE_THRESHOLD}}
```
— number (e.g., "80") or "N/A" for demo
```
{{LINT_TOOL}}
```
— linter/formatter names (from coding standards or tech stack defaults)
```
{{SECURITY_TOOLS}}
```
— security scan tools or "N/A"
```
{{IGNORE_TAG_DOCS}}
```
— the git commit ignore tag reference for the chosen framework (see reference docs)
```
{{CODING_STANDARDS_SUMMARY}}
```
— see Coding Standards Composition section above
```
{{INITIALIZED_DATE}}
```
— today's date in
```
YYYY-MM-DD
```
format
```
{{MAIN_BRANCH}}
```
— release branch name

Language: Generate this file in the language chosen in Phase 1 (default: Chinese/中文).

Important: AGENTS.md is a living document. Keep it minimal at creation time. Agents should append to it during development but never remove existing entries. The initial version is just the skeleton — it will grow.

读取

assets/templates/AGENTS.template.md

，填充以下内容：

```
{{PROJECT_NAME}}
```
— 项目名称
```
{{PROJECT_DESCRIPTION}}
```
— 简洁的一句话摘要
```
{{TECH_STACK_DETAILS}}
```
— 结构化的技术栈列表（若已知版本则包含版本信息）
```
{{SDD_FRAMEWORK}}
```
— 框架显示名称（例如 "OpenSpec"）
```
{{SDD_FRAMEWORK_ID}}
```
— 框架小写ID：
```
openspec
```
、
```
speckit
```
或
```
gsd
```
```
{{SDD_WORKFLOW_SUMMARY}}
```
— 3-5个要点，描述团队的SDD工作流（来自参考文档）
```
{{QUALITY_LEVEL}}
```
— "demo" 或 "production"（显示用）
```
{{QUALITY_LEVEL_ID}}
```
— "demo" 或 "production"（机器可读，与显示值相同）

{{CI_PLATFORMS_ID}}

—

gitlab

、

github

或

gitlab,github

（无空格）

```
{{COVERAGE_THRESHOLD}}
```
— 数字（例如 "80"），演示项目填 "N/A"
```
{{LINT_TOOL}}
```
— 代码检查/格式化工具名称（来自编码规范或技术栈默认值）
```
{{SECURITY_TOOLS}}
```
— 安全扫描工具或 "N/A"
```
{{IGNORE_TAG_DOCS}}
```
— 所选框架的Git提交忽略标签参考（见参考文档）
```
{{CODING_STANDARDS_SUMMARY}}
```
— 见上方「编码规范整合」部分
```
{{INITIALIZED_DATE}}
```
— 当前日期，格式为
```
YYYY-MM-DD
```
```
{{MAIN_BRANCH}}
```
— 发布分支名称

语言：按第一阶段选择的语言生成（默认：中文）。

重要提示：AGENTS.md是一份动态文档。创建时保持简洁即可，开发过程中Agent可向其中追加内容，但绝不要删除现有条目。初始版本仅为骨架 — 后续会逐步完善。

Coding Standards Composition

编码规范整合

If the user provided coding standards:

Read the content (from the pasted text or the file path).
Extract the key rules relevant to: naming conventions, file structure, formatting, forbidden patterns, and required patterns.
Summarize them into the
```
## Coding Standards
```
section of AGENTS.md (concise bullet-point form — the full doc lives separately).
If the standards specify a linter/formatter config, reference it in the
```
{{LINT_CMD}}
```
for CI (e.g.,
```
eslint --config .eslintrc.json
```
,
```
ruff check --config pyproject.toml
```
).
If the user provided a file path, also add a reference to that file in AGENTS.md so agents know where the canonical source is.

If no standards were provided, write a minimal placeholder in the Coding Standards section appropriate for the tech stack (e.g., "Follow PEP 8" for Python, "Follow Airbnb JavaScript Style Guide" for JS).

若用户提供了编码规范：

读取内容（来自粘贴文本或文件路径）。
提取与命名约定、文件结构、格式要求、禁用模式、强制模式相关的关键规则。
将其总结为AGENTS.md中「## 编码规范」部分的简洁要点列表 — 完整文档存放在别处。
若规范指定了代码检查/格式化工具配置，在CI的
```
{{LINT_CMD}}
```
中引用（例如
```
eslint --config .eslintrc.json
```
、
```
ruff check --config pyproject.toml
```
）。
若用户提供了文件路径，在AGENTS.md中添加该文件的引用，以便Agent知道规范的权威来源。

若未提供规范，则为该技术栈编写最小化的占位内容（例如Python项目写「遵循PEP 8规范」，JS项目写「遵循Airbnb JavaScript风格指南」）。

按项目类型生成（Flask 后端 / React 前端 / Taro 小程序）

以下流程内置于本技能，不调用、不引用任何独立 init-* 技能。

当项目类型 = Flask 后端

在生成 README、AGENTS、CI 等通用文件之后，在

<project_root>

下按本技能

references/flask-backend.md

与

assets/flask-backend/

生成完整 Flask API 骨架。

目录结构
按

assets/flask-backend/project-structure.txt

创建目录树：

app/

（含

__init__.py

、

config.py

、

extensions.py

）、

app/routes/

（

main_api.py

及至少一个业务模块如

user_api.py

）、

app/models/

、

app/service/

、

app/schemas/

、

app/utils/

（含

api_util.py

）、可选

app/permission/

、

tests/

（含

conftest.py

）、

scripts/

、

docs/

或

context/

，根目录

.env.example

、

pyproject.toml

。

核心文件要点
- app/init.py：
```
create_app(config_name)
```
  应用工厂；初始化扩展、加载配置、注册 Blueprint（可调用
```
register_all_blueprints(app)
```
  ）；注册
```
before_request
```
  /
```
after_request
```
  /
```
teardown_request
```
  /
```
teardown_appcontext
```
  及全局
```
errorhandler
```
  。可参考
```
assets/flask-backend/create_app_snippet.py
```
  。
- app/config.py：按环境（development/test/production）加载配置，敏感项从环境变量读取。
- app/extensions.py：集中定义 Flask-SQLAlchemy、Redis、JWT、Casbin 等扩展实例（在 create_app 中 init_app）。
- app/utils/api_util.py：统一响应格式（如
```
AppResponse
```
  、
```
{code, message, data}
```
  ）、自定义 Api、统一异常处理。
- app/routes/main_api.py：健康检查等通用接口；Blueprint 命名与
```
*_api.py
```
  约定一致，导出
```
*_app
```
  （如
```
main_app
```
  ）供自动注册。
- 业务路由：至少一个示例模块（如
```
user_api.py
```
  ），Blueprint + Api，Resource 仅做「解析参数 → 调 Service → 返回 AppResponse/字典」。
- register_all_blueprints：扫描
```
app/routes
```
  下
```
*_api.py
```
  ，导出变量名为文件名去
```
_api
```
  加
```
_app
```
  ，实现见
```
create_app_snippet.py
```
  。
依赖与配置
- 使用 uv：以
```
pyproject.toml
```
  +
```
uv.lock
```
  为准；参考
```
assets/flask-backend/pyproject-uv.example.toml
```
  填写依赖（flask、flask-restful、flask-sqlalchemy、python-dotenv、pytest 等）。
- ```
.env.example
```
  参考
```
assets/flask-backend/env-example.txt
```
  。
- README 中可纳入或引用「用户如何使用 uv」：见
```
assets/flask-backend/uv-usage.md
```
  。
交付物
完整目录与占位
```
__init__.py
```
；
```
app/__init__.py
```
（create_app + register_all_blueprints + 钩子）；
```
app/config.py
```
、
```
app/extensions.py
```
；
```
app/utils/api_util.py
```
；
```
app/routes/main_api.py
```
及至少一个业务模块示例；占位或示例的
```
app/models/
```
、
```
app/service/
```
、
```
app/schemas/
```
；
```
.env.example
```
、
```
pyproject.toml
```
；
```
tests/conftest.py
```
及至少一个 API 测试示例。可选：
```
scripts/validate_flask_structure.py
```
可从本技能复制为
```
scripts/validate_flask_structure.py
```
供用户校验结构。
与通用 Phase 2 的衔接
若选择了 CI，
```
.gitlab-ci.yml
```
/ GitHub Actions 中的
```
{{DOCKER_IMAGE}}
```
、
```
{{INSTALL_CMD}}
```
等按 Python/Flask 填写（如
```
uv sync
```
、
```
uv run pytest
```
）。README 的
```
{{GETTING_STARTED_STEPS}}
```
写入 uv 安装与
```
uv sync
```
、
```
uv run flask run
```
等步骤。
后续开发：在 AGENTS 或开发约定中注明「新增 API/资源时按本技能
```
references/flask-backend-codegen.md
```
与
```
assets/flask-backend-codegen/
```
（路由、Service、Model、Schema、权限、测试、.env.example）」。

在生成 README、AGENTS、CI 等通用文件之后，在

<project_root>

下按本技能

references/flask-backend.md

与

assets/flask-backend/

生成完整 Flask API 骨架。

目录结构
按

assets/flask-backend/project-structure.txt

创建目录树：

app/

（含

__init__.py

、

config.py

、

extensions.py

）、

app/routes/

（

main_api.py

及至少一个业务模块如

user_api.py

）、

app/models/

、

app/service/

、

app/schemas/

、

app/utils/

（含

api_util.py

）、可选

app/permission/

、

tests/

（含

conftest.py

）、

scripts/

、

docs/

或

context/

，根目录

.env.example

、

pyproject.toml

。

核心文件要点
- app/init.py：
```
create_app(config_name)
```
  应用工厂；初始化扩展、加载配置、注册 Blueprint（可调用
```
register_all_blueprints(app)
```
  ）；注册
```
before_request
```
  /
```
after_request
```
  /
```
teardown_request
```
  /
```
teardown_appcontext
```
  及全局
```
errorhandler
```
  。可参考
```
assets/flask-backend/create_app_snippet.py
```
  。
- app/config.py：按环境（development/test/production）加载配置，敏感项从环境变量读取。
- app/extensions.py：集中定义 Flask-SQLAlchemy、Redis、JWT、Casbin 等扩展实例（在 create_app 中 init_app）。
- app/utils/api_util.py：统一响应格式（如
```
AppResponse
```
  、
```
{code, message, data}
```
  ）、自定义 Api、统一异常处理。
- app/routes/main_api.py：健康检查等通用接口；Blueprint 命名与
```
*_api.py
```
  约定一致，导出
```
*_app
```
  （如
```
main_app
```
  ）供自动注册。
- 业务路由：至少一个示例模块（如
```
user_api.py
```
  ），Blueprint + Api，Resource 仅做「解析参数 → 调 Service → 返回 AppResponse/字典」。
- register_all_blueprints：扫描
```
app/routes
```
  下
```
*_api.py
```
  ，导出变量名为文件名去
```
_api
```
  加
```
_app
```
  ，实现见
```
create_app_snippet.py
```
  。
依赖与配置
- 使用 uv：以
```
pyproject.toml
```
  +
```
uv.lock
```
  为准；参考
```
assets/flask-backend/pyproject-uv.example.toml
```
  填写依赖（flask、flask-restful、flask-sqlalchemy、python-dotenv、pytest 等）。
- ```
.env.example
```
  参考
```
assets/flask-backend/env-example.txt
```
  。
- README 中可纳入或引用「用户如何使用 uv」：见
```
assets/flask-backend/uv-usage.md
```
  。
交付物
完整目录与占位
```
__init__.py
```
；
```
app/__init__.py
```
（create_app + register_all_blueprints + 钩子）；
```
app/config.py
```
、
```
app/extensions.py
```
；
```
app/utils/api_util.py
```
；
```
app/routes/main_api.py
```
及至少一个业务模块示例；占位或示例的
```
app/models/
```
、
```
app/service/
```
、
```
app/schemas/
```
；
```
.env.example
```
、
```
pyproject.toml
```
；
```
tests/conftest.py
```
及至少一个 API 测试示例。可选：
```
scripts/validate_flask_structure.py
```
可从本技能复制为
```
scripts/validate_flask_structure.py
```
供用户校验结构。
与通用第二阶段的衔接
若选择了 CI，
```
.gitlab-ci.yml
```
/ GitHub Actions 中的
```
{{DOCKER_IMAGE}}
```
、
```
{{INSTALL_CMD}}
```
等按 Python/Flask 填写（如
```
uv sync
```
、
```
uv run pytest
```
）。README 的
```
{{GETTING_STARTED_STEPS}}
```
写入 uv 安装与
```
uv sync
```
、
```
uv run flask run
```
等步骤。
后续开发：在 AGENTS 或开发约定中注明「新增 API/资源时按本技能
```
references/flask-backend-codegen.md
```
与
```
assets/flask-backend-codegen/
```
（路由、Service、Model、Schema、权限、测试、.env.example）」。

当项目类型 = React 前端

在生成通用文件之后，在

<project_root>

下生成 React 前端骨架；不调用外部 init-react-frontend 技能。

脚手架
使用官方 Vite 创建项目：在目标目录执行
```
npm create vite@latest <project-name> -- --template react-ts
```
（或当前 create-vite 支持时选择 Rolldown、React、TypeScript）。若未提供 Rolldown 选项，则在生成
```
package.json
```
时在 devDependencies 中设置
```
"vite": "npm:rolldown-vite@<resolved-latest-version>"
```
，并在 Vite 配置中启用 React Compiler。
默认技术栈
React、React Compiler（在 Vite 中启用）、TypeScript、Ant Design、react-router-dom、Zustand、Vitest + jsdom、Tailwind CSS、Axios、Vite（Rolldown）。依赖版本在生成时解析为当时最新稳定版，并写入
```
package.json
```
精确版本（不用
```
^
```
/
```
~
```
）。
目录结构
在
```
src/
```
下创建：
```
src/utils/
```
、
```
src/consts/
```
、
```
src/route/
```
（路由配置，与 consts 分离）、
```
src/components/
```
、
```
src/pages/
```
、
```
src/store/
```
、
```
src/api/
```
或
```
src/services/
```
；以及
```
test/
```
或
```
src/test/
```
（Vitest 全局 setup、fixtures、mocks）。单元测试可放在源码旁
```
**/*.test.{ts,tsx}
```
。
文件清单
- ```
package.json
```
  ：scripts（dev、build、preview、test）；依赖为解析后的精确版本；Vite 使用 Rolldown 时 devDependencies 中
```
"vite": "npm:rolldown-vite@<version>"
```
  。
- ```
vite.config.ts
```
  ：React 插件、React Compiler、path alias（如
```
@/
```
  →
```
src/
```
  ）、build 输出；dev proxy：
```
server.proxy
```
  将
```
/api
```
  等转发到后端，默认 target 端口 5000。
- ```
tsconfig.json
```
  /
```
tsconfig.node.json
```
  、
```
tailwind.config.js
```
  +
```
postcss.config.js
```
  、
```
index.html
```
  （入口为
```
src/main.tsx
```
  ）。
- ```
src/main.tsx
```
  ：React 根入口、Ant Design 样式、mount。
- ```
src/App.tsx
```
  ：BrowserRouter 与最小路由列表。
- ```
src/utils/
```
  、
```
src/consts/
```
  、
```
src/route/
```
  、
```
src/components/
```
  、
```
src/pages/
```
  、
```
src/store/
```
  、
```
src/api/
```
  或
```
src/services/
```
  的占位或示例。
- ```
vitest.config.ts
```
  ：Vitest + jsdom，匹配
```
**/*.test.{ts,tsx}
```
  。
- 至少一个示例测试
```
src/**/*.test.tsx
```
  。
- ```
.gitignore
```
  （Node、dist、env、IDE）。
- AGENTS.md：使用本技能模板
```
assets/templates/AGENTS.react.template.md
```
  填充
```
{{PROJECT_NAME}}
```
  、
```
{{PROJECT_DESCRIPTION}}
```
  、
```
{{TECH_STACK_TABLE}}
```
  、
```
{{DIR_STRUCTURE}}
```
  、
```
{{SCRIPTS}}
```
  、
```
{{INITIALIZED_DATE}}
```
  ；语言与项目约定一致（默认中文）。
与通用 Phase 2 的衔接
若选择了 CI，CI 中的
```
{{INSTALL_CMD}}
```
为
```
npm ci
```
，
```
{{TEST_CMD}}
```
为
```
npm run test
```
等。README 的
```
{{GETTING_STARTED_STEPS}}
```
写入
```
npm install
```
、
```
npm run dev
```
、后端端口与 dev proxy 说明。
生成完成后提示用户执行
```
npm install
```
（或所选包管理器），并可选择执行
```
npm run build
```
、
```
npm run test
```
做验证。
后续开发：在 AGENTS 或开发规范中注明「功能/页面/组件开发按本技能
```
references/frontend-codegen.md
```
（复用优先、UI/业务分层、数据化路由、测试先行、函数组件）」。

在生成通用文件之后，在

<project_root>

下生成 React 前端骨架；不调用外部 init-react-frontend 技能。

脚手架创建
使用官方 Vite 创建项目：在目标目录执行
```
npm create vite@latest <project-name> -- --template react-ts
```
（或当前 create-vite 支持时选择 Rolldown、React、TypeScript）。若未提供 Rolldown 选项，则在生成
```
package.json
```
时在 devDependencies 中设置
```
"vite": "npm:rolldown-vite@<resolved-latest-version>"
```
，并在 Vite 配置中启用 React Compiler。
默认技术栈
React、React Compiler（在 Vite 中启用）、TypeScript、Ant Design、react-router-dom、Zustand、Vitest + jsdom、Tailwind CSS、Axios、Vite（Rolldown）。依赖版本在生成时解析为当时最新稳定版，并写入
```
package.json
```
精确版本（不用
```
^
```
/
```
~
```
）。
目录结构
在
```
src/
```
下创建：
```
src/utils/
```
、
```
src/consts/
```
、
```
src/route/
```
（路由配置，与 consts 分离）、
```
src/components/
```
、
```
src/pages/
```
、
```
src/store/
```
、
```
src/api/
```
或
```
src/services/
```
；以及
```
test/
```
或
```
src/test/
```
（Vitest 全局 setup、fixtures、mocks）。单元测试可放在源码旁
```
**/*.test.{ts,tsx}
```
。
文件清单
- ```
package.json
```
  ：scripts（dev、build、preview、test）；依赖为解析后的精确版本；Vite 使用 Rolldown 时 devDependencies 中
```
"vite": "npm:rolldown-vite@<version>"
```
  。
- ```
vite.config.ts
```
  ：React 插件、React Compiler、path alias（如
```
@/
```
  →
```
src/
```
  ）、build 输出；dev proxy：
```
server.proxy
```
  将
```
/api
```
  等转发到后端，默认 target 端口 5000。
- ```
tsconfig.json
```
  /
```
tsconfig.node.json
```
  、
```
tailwind.config.js
```
  +
```
postcss.config.js
```
  、
```
index.html
```
  （入口为
```
src/main.tsx
```
  ）。
- ```
src/main.tsx
```
  ：React 根入口、Ant Design 样式、mount。
- ```
src/App.tsx
```
  ：BrowserRouter 与最小路由列表。
- ```
src/utils/
```
  、
```
src/consts/
```
  、
```
src/route/
```
  、
```
src/components/
```
  、
```
src/pages/
```
  、
```
src/store/
```
  、
```
src/api/
```
  或
```
src/services/
```
  的占位或示例。
- ```
vitest.config.ts
```
  ：Vitest + jsdom，匹配
```
**/*.test.{ts,tsx}
```
  。
- 至少一个示例测试
```
src/**/*.test.tsx
```
  。
- ```
.gitignore
```
  （Node、dist、env、IDE）。
- AGENTS.md：使用本技能模板
```
assets/templates/AGENTS.react.template.md
```
  填充
```
{{PROJECT_NAME}}
```
  、
```
{{PROJECT_DESCRIPTION}}
```
  、
```
{{TECH_STACK_TABLE}}
```
  、
```
{{DIR_STRUCTURE}}
```
  、
```
{{SCRIPTS}}
```
  、
```
{{INITIALIZED_DATE}}
```
  ；语言与项目约定一致（默认中文）。
与通用第二阶段的衔接
若选择了 CI，CI 中的
```
{{INSTALL_CMD}}
```
为
```
npm ci
```
，
```
{{TEST_CMD}}
```
为
```
npm run test
```
等。README 的
```
{{GETTING_STARTED_STEPS}}
```
写入
```
npm install
```
、
```
npm run dev
```
、后端端口与 dev proxy 说明。
生成完成后提示用户执行
```
npm install
```
（或所选包管理器），并可选择执行
```
npm run build
```
、
```
npm run test
```
做验证。
后续开发：在 AGENTS 或开发规范中注明「功能/页面/组件开发按本技能
```
references/frontend-codegen.md
```
（复用优先、UI/业务分层、数据化路由、测试先行、函数组件）」。

当项目类型 = Taro 小程序

在生成通用文件之后，在

<project_root>

下按 Taro 官方方式初始化并做仅允许的后续操作；不调用外部 init-taro-miniapp 技能。

初始化（必须）
在项目所在父目录执行：
```
npx @tarojs/cli init <projectName>
```
。仅用此命令创建项目；交互中可选择框架（React/Vue3）、TypeScript、CSS 预处理器、打包工具、包管理器。不得用其他脚手架替代。
安装依赖（必须）
进入项目根目录执行
```
npm install
```
（若 init 时选了 pnpm/yarn 则用
```
pnpm install
```
或
```
yarn
```
）。不可省略。
在 src 下创建目录
仅新增以下目录（缺失则创建，不修改已有文件）：
```
src/apis
```
（API 封装）、
```
src/utils
```
、
```
src/components
```
、
```
src/consts
```
；可选
```
src/hooks
```
、
```
src/services
```
。目录可为空，不强制添加文件。
配置 H5 开发代理
仅修改项目配置中的 H5 dev proxy，使前端能请求后端。配置文件一般为
```
config/index.js
```
或
```
config/dev.js
```
。在 h5 → devServer 下增加或合并 proxy，例如将
```
/api
```
转发到后端（默认端口 5000）：
javascript
```
h5: { devServer: { proxy: { '/api': { target: 'http://localhost:5000', changeOrigin: true, pathRewrite: { '^/api': '/api' } } } } }
```
后端端口非 5000 时修改
```
target
```
；除 proxy 外不修改配置其他项。
README 与 AGENTS.md
使用本技能模板
```
assets/templates/AGENTS.taro.template.md
```
在项目根目录生成或覆盖
```
AGENTS.md
```
，填充
```
{{PROJECT_NAME}}
```
、
```
{{PROJECT_DESCRIPTION}}
```
、
```
{{TECH_STACK_TABLE}}
```
、
```
{{DIR_STRUCTURE}}
```
（含 src/apis、utils、components、consts 及 config/、dist/）、
```
{{SCRIPTS}}
```
、
```
{{INITIALIZED_DATE}}
```
。可酌情新增或更新 README（项目名、运行方式、代理/端口说明），保持简洁。
禁止
不修改
```
package.json
```
、依赖或脚本（仅允许执行上述 install）；不修改已有源码、应用入口或其他配置（如
```
app.config.ts
```
、
```
babel.config.js
```
），仅允许上述 proxy 配置块。

在生成通用文件之后，在

<project_root>

下按 Taro 官方方式初始化并做仅允许的后续操作；不调用外部 init-taro-miniapp 技能。

初始化（必须）
在项目所在父目录执行：
```
npx @tarojs/cli init <projectName>
```
。仅用此命令创建项目；交互中可选择框架（React/Vue3）、TypeScript、CSS 预处理器、打包工具、包管理器。不得用其他脚手架替代。
安装依赖（必须）
进入项目根目录执行
```
npm install
```
（若 init 时选了 pnpm/yarn 则用
```
pnpm install
```
或
```
yarn
```
）。不可省略。
在 src 下创建目录
仅新增以下目录（缺失则创建，不修改已有文件）：
```
src/apis
```
（API 封装）、
```
src/utils
```
、
```
src/components
```
、
```
src/consts
```
；可选
```
src/hooks
```
、
```
src/services
```
。目录可为空，不强制添加文件。
配置 H5 开发代理
仅修改项目配置中的 H5 dev proxy，使前端能请求后端。配置文件一般为
```
config/index.js
```
或
```
config/dev.js
```
。在 h5 → devServer 下增加或合并 proxy，例如将
```
/api
```
转发到后端（默认端口 5000）：
javascript
```
h5: { devServer: { proxy: { '/api': { target: 'http://localhost:5000', changeOrigin: true, pathRewrite: { '^/api': '/api' } } } } }
```
后端端口非 5000 时修改
```
target
```
；除 proxy 外不修改配置其他项。
README 与 AGENTS.md
使用本技能模板
```
assets/templates/AGENTS.taro.template.md
```
在项目根目录生成或覆盖
```
AGENTS.md
```
，填充
```
{{PROJECT_NAME}}
```
、
```
{{PROJECT_DESCRIPTION}}
```
、
```
{{TECH_STACK_TABLE}}
```
、
```
{{DIR_STRUCTURE}}
```
（含 src/apis、utils、components、consts 及 config/、dist/）、
```
{{SCRIPTS}}
```
、
```
{{INITIALIZED_DATE}}
```
。可酌情新增或更新 README（项目名、运行方式、代理/端口说明），保持简洁。
禁止操作
不修改
```
package.json
```
、依赖或脚本（仅允许执行上述 install）；不修改已有源码、应用入口或其他配置（如
```
app.config.ts
```
、
```
babel.config.js
```
），仅允许上述 proxy 配置块。

.gitlab-ci.yml

Read

assets/templates/gitlab-ci.template.yml

. Fill in:

```
{{DOCKER_IMAGE}}
```
— appropriate base image for the tech stack

{{INSTALL_CMD}}

— dependency install command (e.g.,

npm ci

pip install -r requirements.txt

)

```
{{LINT_CMD}}
```
— lint/format check command
```
{{TEST_CMD}}
```
— test run command
```
{{COVERAGE_CMD}}
```
— coverage report command
```
{{COVERAGE_THRESHOLD}}
```
— minimum coverage (skip/set to 0 for demo)
```
{{SECURITY_SCAN_CMD}}
```
— security scan command or
```
echo "skipped"
```
for demo

{{SDD_CHECK_SCRIPT}}

— path to framework check script: one of:

```
scripts/check_sdd_openspec.sh
```
```
scripts/check_sdd_speckit.sh
```
```
scripts/check_sdd_gsd.sh
```

```
{{MAIN_BRANCH}}
```
— release branch name (default:
```
main
```
)

当用户选择 Python + GitLab CI + backend-python-cicd 规范时：生成或校验

.gitlab-ci.yml

、Dockerfile、部署脚本与分支文档时，须遵循本技能

references/backend-python-cicd.md

与

assets/backend-python-cicd/

。要点：先本地 Docker 构建测试再 Git 推送；私有镜像

docker.dic.hillstonenet.com/library/python:3.12-slim

与 pip/uv 镜像源（见

assets/backend-python-cicd/dockerfile-python-base.md

）；多阶段构建（requirement + project）；分支 develop/bugfix/hotfix/master；dev→prod K8s 部署（dev_deploy.sh、prod_deploy.sh）；私有镜像仓库 registry.dic.hillstonenet.com；Runner tags

grunner

。可生成 Dockerfile、

scripts/dev_deploy.sh

、

scripts/prod_deploy.sh

、

k8s/dev_deployment.yaml.tpl

、

docs/GITLAB-CICD.md

及 Git 操作说明（见

assets/backend-python-cicd/git-operations.md

）。

Run the install script to copy all required check scripts into the project:

python <skill_dir>/scripts/install_scripts.py <project_root> --framework <fw>

This installs the appropriate runtime variant (

.sh

on Linux/macOS,

.js

as fallback,

.ps1

on Windows) of

check_project_tag

and

check_sdd_<framework>

into

<project_root>/scripts/

. Do not manually recreate or copy-paste script files — the install script guarantees the exact asset versions are used without modification. Pass

--dry-run

first to verify what will be copied.

读取

assets/templates/gitlab-ci.template.yml

，填充以下内容：

```
{{DOCKER_IMAGE}}
```
— 适合该技术栈的基础镜像

{{INSTALL_CMD}}

— 依赖安装命令（例如

npm ci

、

pip install -r requirements.txt

）

```
{{LINT_CMD}}
```
— 代码检查/格式校验命令
```
{{TEST_CMD}}
```
— 测试运行命令
```
{{COVERAGE_CMD}}
```
— 覆盖率报告命令
```
{{COVERAGE_THRESHOLD}}
```
— 最小覆盖率要求（演示项目可跳过/设为0）
```
{{SECURITY_SCAN_CMD}}
```
— 安全扫描命令，演示项目填
```
echo "skipped"
```

{{SDD_CHECK_SCRIPT}}

— 框架检查脚本路径：以下之一：

```
scripts/check_sdd_openspec.sh
```
```
scripts/check_sdd_speckit.sh
```
```
scripts/check_sdd_gsd.sh
```

```
{{MAIN_BRANCH}}
```
— 发布分支名称（默认：
```
main
```
）

当用户选择 Python + GitLab CI + backend-python-cicd 规范时：生成/校验

.gitlab-ci.yml

、Dockerfile、部署脚本与分支文档时，须遵循本技能

references/backend-python-cicd.md

与

assets/backend-python-cicd/

。要点：先本地 Docker 构建测试再 Git 推送；私有镜像

docker.dic.hillstonenet.com/library/python:3.12-slim

与 pip/uv 镜像源（见

assets/backend-python-cicd/dockerfile-python-base.md

）；多阶段构建（依赖安装 + 项目构建）；分支 develop/bugfix/hotfix/master；dev→prod K8s 部署（dev_deploy.sh、prod_deploy.sh）；私有镜像仓库 registry.dic.hillstonenet.com；Runner tags

grunner

。可生成 Dockerfile、

scripts/dev_deploy.sh

、

scripts/prod_deploy.sh

、

k8s/dev_deployment.yaml.tpl

、

docs/GITLAB-CICD.md

及 Git 操作说明（见

assets/backend-python-cicd/git-operations.md

）。

运行安装脚本，将所有必要的检查脚本复制到项目中：

python <skill_dir>/scripts/install_scripts.py <project_root> --framework <fw>

此脚本会将

check_project_tag

和

check_sdd_<framework>

的对应运行时版本（Linux/macOS 用

.sh

， fallback 用

.js

，Windows 用

.ps1

）安装到

<project_root>/scripts/

。请勿手动创建或复制粘贴脚本文件 — 安装脚本可确保使用的是精确的资产版本且未被修改。先传入

--dry-run

预览将复制的内容。

.github/workflows/ci.yml (if GitHub Actions selected)

.github/workflows/ci.yml（若选择GitHub Actions）

Read

assets/templates/github-actions.template.yml

. Fill in the same placeholders as the GitLab template — the values must be identical to ensure both pipelines enforce the same standards.

读取

assets/templates/github-actions.template.yml

，填充与GitLab模板相同的占位符 — 值必须完全一致，以确保两个流水线执行相同的标准。

当用户选择 QA/测试规范（Phase 1 问题 12）

当用户选择 QA/测试规范（第一阶段问题12）

在 AGENTS.md 中增加「测试与根因分析」小节，或引用本技能

references/qa-testing.md

：测试计划、用例格式、自动化约定、测试报告；缺陷与测试失败时采用系统性排错与根因分析（先根因、后修复，禁止只治标）。可摘录要点或写「详见项目所用 project-initializer 技能之 references/qa-testing.md」。

在 AGENTS.md 中增加「测试与根因分析」小节，或引用本技能

references/qa-testing.md

：测试计划、用例格式、自动化约定、测试报告；缺陷与测试失败时采用系统性排错与根因分析（先找根因、再修复，禁止只治标）。可摘录要点或写「详见项目所用 project-initializer 技能之 references/qa-testing.md」。

当用户选择多角色/子代理（Phase 1 问题 13）

当用户选择多角色/子代理（第一阶段问题13）

在 Phase 2 生成与 Phase 3 SDD 之后，按本技能

references/agent-roles.md

与

assets/agent-roles/

执行：(1) 确认场景与约束（系统开发、数据分析、运维等；串行/并行；规模与规定）；(2) 规划角色清单（从

references/agent-roles.md

常见场景与角色映射选取并裁剪）；(3) 为每个角色填规范（使用

assets/agent-roles/role-template.json

结构，产出

roles/<role-id>.md

或

roles/<role-id>.json

）；(4) 若用户要求创建子代理，从角色定义生成

.cursor/agents/<name>.md

（YAML frontmatter：name、description、model 等；正文：scope、inputExpectation、constraints、outputSpec、handoff），格式参考

assets/agent-roles/subagent-cursor-template.md

。子代理目录默认项目级

.cursor/agents/

。可选：将

scripts/validate_roles.py

复制到项目中用于校验角色 JSON。

在第二阶段文件生成与第三阶段SDD初始化之后，按本技能

references/agent-roles.md

与

assets/agent-roles/

执行：(1) 确认场景与约束（系统开发、数据分析、运维等；串行/并行；规模与规定）；(2) 规划角色清单（从

references/agent-roles.md

常见场景与角色映射选取并裁剪）；(3) 为每个角色填充规范（使用

assets/agent-roles/role-template.json

结构，产出

roles/<role-id>.md

或

roles/<role-id>.json

）；(4) 若用户要求创建子代理，从角色定义生成

.cursor/agents/<name>.md

（YAML frontmatter：name、description、model 等；正文：scope、inputExpectation、constraints、outputSpec、handoff），格式参考

assets/agent-roles/subagent-cursor-template.md

。子代理目录默认项目级

.cursor/agents/

。可选：将

scripts/validate_roles.py

复制到项目中用于校验角色 JSON。

Phase 3: SDD Framework Installation

第三阶段：SDD框架安装

MANDATORY — do not skip or substitute manually. You MUST run the script below. Do NOT create SDD framework directories or documents by hand. Manually created files will be incomplete, wrongly structured, and will fail CI checks. If the script encounters an error, report it to the user — do not work around it by creating files yourself.

Resolve

<skill_dir>

(the directory containing this SKILL.md) and run:

python <skill_dir>/scripts/initialize_sdd.py <project_root> --framework <fw> --ai-provider <agent> [--script-shell sh|ps]

If you are already inside the project directory,

<project_root>

Determining the
--ai-provider
value: Use the name of the AI agent currently running this skill (e.g.

claude

copilot

gemini

opencode

codex

). You know this from your own identity — pass it as-is.

For SpecKit only —
--script-shell
parameter: Choose the shell for generated scripts:

```
sh
```
(default): Unix/shell scripts — use for Linux/macOS CI runners
```
ps
```
: PowerShell scripts — use for Windows CI runners

This script runs all frameworks non-interactively:

OpenSpec:

openspec init --tools <tool_id>

—

--ai-provider

mapped to OpenSpec's tool ID:

claude

opencode

codex

gemini

windsurf

qwen

codebuddy

kilocode

use the same name;

copilot

→

github-copilot

;

cursor-agent

→

cursor

;

roo

→

roocode

; all others→

all

SpecKit:

specify init . --ai <provider> --here --force --script <shell>

— passes the provider name and shell choice directly

GSD:

npx -y get-shit-done-cc@latest --<runtime> --local

—

--ai-provider

is mapped to a runtime flag:

claude

→

--claude

opencode

→

--opencode

codex

→

--codex

, all others→

--claude

The script also:

Installs the framework CLI tool (
```
npm
```
,
```
uv
```
, or
```
npx
```
as appropriate) if not found
Initializes framework-specific directories
For OpenSpec: initializes
```
openspec/specs/
```
and
```
openspec/changes/
```
For SpecKit: initializes
```
specs/
```
(auto-numbered) and
```
memory/constitution.md
```
For GSD: initializes
```
.planning/
```
with PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json

SpecKit

--ai-provider

supported values: claude, gemini, copilot, cursor-agent, windsurf, opencode, codex, qwen, amp, shai, agy, bob, qodercli, roo, codebuddy, jules, kilocode, generic.

Pass

--dry-run

to preview without installing.

强制要求 — 请勿跳过或手动替代 必须运行以下脚本。请勿手动创建SDD框架目录或文档。手动创建的文件会不完整、结构错误，并导致CI检查失败。若脚本执行出错，请向用户报告 — 不要自行创建文件绕过错误。

确定

<skill_dir>

（包含本SKILL.md文件的目录）并运行：

python <skill_dir>/scripts/initialize_sdd.py <project_root> --framework <fw> --ai-provider <agent> [--script-shell sh|ps]

若已在项目目录内，

<project_root>

为

。

确定
--ai-provider
的值：使用当前运行本技能的AI Agent名称（例如

claude

、

copilot

、

gemini

、

opencode

、

codex

）。根据自身身份传入即可。

仅针对SpecKit —
--script-shell
参数：选择生成脚本的shell类型：

```
sh
```
（默认）：Unix/shell脚本 — 用于Linux/macOS CI运行器
```
ps
```
：PowerShell脚本 — 用于Windows CI运行器

此脚本以非交互式方式运行所有框架：

OpenSpec：

openspec init --tools <tool_id>

—

--ai-provider

映射为OpenSpec的工具ID：

claude

、

opencode

、

codex

、

gemini

、

windsurf

、

qwen

、

codebuddy

、

kilocode

使用原名；

copilot

→

github-copilot

；

cursor-agent

→

cursor

；

roo

→

roocode

；其他→

all

SpecKit：

specify init . --ai <provider> --here --force --script <shell>

— 直接传入provider名称和shell选择

GSD：

npx -y get-shit-done-cc@latest --<runtime> --local

—

--ai-provider

映射为运行时标志：

claude

→

--claude

，

opencode

→

--opencode

，

codex

→

--codex

，其他→

--claude

此脚本还会：

若未找到框架CLI工具，则安装（根据情况使用
```
npm
```
、
```
uv
```
或
```
npx
```
）
初始化框架特定的目录
OpenSpec：初始化
```
openspec/specs/
```
和
```
openspec/changes/
```
SpecKit：初始化
```
specs/
```
（自动编号）和
```
memory/constitution.md
```
GSD：初始化
```
.planning/
```
，包含PROJECT.md、REQUIREMENTS.md、ROADMAP.md、STATE.md、config.json

SpecKit支持的

--ai-provider

值：claude, gemini, copilot, cursor-agent, windsurf, opencode, codex, qwen, amp, shai, agy, bob, qodercli, roo, codebuddy, jules, kilocode, generic.

传入

--dry-run

预览安装内容而不实际安装。

Prerequisites

前置依赖

Framework	Requires
OpenSpec	`npm` (Node.js)
SpecKit	`uv` (Python tool installer) + `git`
GSD	`npx` + Node.js ≥18

If a required tool is not installed, the script will exit with an error message indicating what needs to be installed.

框架	所需依赖
OpenSpec	`npm` (Node.js)
SpecKit	`uv` (Python工具安装器) + `git`
GSD	`npx` + Node.js ≥18

若缺少必需工具，脚本会退出并显示错误消息，说明需要安装的内容。

Phase 4: SDD Check Script

第四阶段：SDD检查脚本

The check script reads the latest git commit message and the project's SDD documents. It enforces documentation consistency.

检查脚本读取最新的Git提交消息和项目的SDD文档，强制确保文档一致性。

Ignore Tag System

忽略标签系统

Agents and developers can place structured tags in commit messages to suppress specific checks:

feat: implement user login [ignore:spec_sync]
fix: typo in variable name [ignore:all_sdd]

Universal tags (all frameworks):

Tag	What it suppresses
`[ignore:all_sdd]`	All SDD process checks

Framework-specific tags — see the relevant reference file for the complete list. They follow the pattern

[ignore:<check_name>]

Agent和开发者可在提交消息中添加结构化标签，以跳过特定检查：

feat: 实现用户登录 [ignore:spec_sync]
fix: 修复变量名拼写错误 [ignore:all_sdd]

通用标签（所有框架）：

标签	跳过的检查
`[ignore:all_sdd]`	所有SDD流程检查

框架特定标签 — 详见相关参考文件。格式为

[ignore:<check_name>]

。

When checks fail

检查失败时的处理

The script exits non-zero and prints a message explaining:

What was found (e.g., "3 tasks incomplete in openspec/changes/add-auth/tasks.md")

What the developer should do (e.g.,

Run /opsx:sync add-auth to sync delta specs

)

How to suppress the check if appropriate (e.g.,

Add [ignore:spec_sync] to commit message if this is a bug fix not tied to a feature

)

脚本会返回非零退出码并打印说明消息：

发现的问题（例如 "openspec/changes/add-auth/tasks.md 中有3项任务未完成"）

开发者应采取的行动（例如

Run /opsx:sync add-auth 以同步增量规范

）

如何跳过检查（例如

若此为与功能无关的bug修复，可在提交消息中添加 [ignore:spec_sync]

）

Phase 5: Project Identity Tag

第五阶段：项目身份标记

Every project initialized by this skill must have a machine-readable identity tag embedded at the top of

AGENTS.md

. This tag allows server-side CI to:

Confirm the project was properly initialized (not just a hand-crafted AGENTS.md)
Know which SDD framework and CI platforms are in use
Enforce version-specific checks appropriate for the project's configuration

The tag takes the form of a structured HTML comment block (the first thing in the file, before any Markdown):

<!-- @project-initializer
version: 1
initialized_at: YYYY-MM-DD
sdd_framework: openspec|speckit|gsd
quality_level: demo|production
ci_platforms: gitlab|github|gitlab,github
project_initializer_version: 1.0.0
-->

Rules:

Always place it as the very first content in
```
AGENTS.md
```
(before the
```
#
```
heading)
Use the actual initialization date (today)
```
sdd_framework
```
— lowercase identifier:
```
openspec
```
,
```
speckit
```
, or
```
gsd
```
```
ci_platforms
```
— comma-separated, no spaces:
```
gitlab
```
,
```
github
```
, or
```
gitlab,github
```
Do not modify this block after creation except through a deliberate re-initialization

The CI check script (

assets/scripts/check_project_tag.sh

) reads this tag and exits non-zero if it is missing or malformed. It is installed automatically by the

install_scripts.py

step described in Phase 2 —

check_project_tag

is always included regardless of the chosen SDD framework. The framework's initialize script (Phase 3) must complete successfully before this tag is validated.

所有通过本技能初始化的项目，必须在AGENTS.md顶部嵌入机器可读的身份标记。此标记供服务端CI使用，以：

确认项目已完成合规初始化（而非手动编写的AGENTS.md）
了解项目使用的SDD框架和CI平台
执行与项目配置匹配的版本特定检查

标记采用结构化HTML注释块的形式（位于文件最开头，在任何Markdown内容之前）：

<!-- @project-initializer
version: 1
initialized_at: YYYY-MM-DD
sdd_framework: openspec|speckit|gsd
quality_level: demo|production
ci_platforms: gitlab|github|gitlab,github
project_initializer_version: 1.0.0
-->

规则：

必须始终放在AGENTS.md的最开头（在
```
#
```
标题之前）
使用实际初始化日期（当前日期）
```
sdd_framework
```
— 小写标识符：
```
openspec
```
、
```
speckit
```
或
```
gsd
```
```
ci_platforms
```
— 逗号分隔，无空格：
```
gitlab
```
、
```
github
```
或
```
gitlab,github
```
创建后除非刻意重新初始化，否则不要修改此块

CI检查脚本（

assets/scripts/check_project_tag.sh

）会读取此标记，若标记缺失或格式错误则返回非零退出码。此脚本会在第二阶段的

install_scripts.py

步骤中自动安装 — 无论选择哪种SDD框架，

check_project_tag

都会被包含。第三阶段的框架初始化脚本必须执行成功，此标记才会被验证。

Phase 6: Consistency Verification

第六阶段：一致性验证

After generating all files, perform this checklist:

```
AGENTS.md
```
starts with a valid
```
<!-- @project-initializer
```
tag
```
sdd_framework
```
in tag matches chosen framework
```
ci_platforms
```
in tag matches files actually generated
Docker/runner image in CI file(s) matches tech stack
```
AGENTS.md
```
tech stack section matches
```
README.md
```
Coverage threshold in CI file(s) matches
```
AGENTS.md
```
→ Quality Standards
SDD framework name consistent across all generated files
The correct SDD check script is referenced (OpenSpec/SpecKit/GSD)
Both CI platform files (if both generated) use identical quality thresholds
Branch name in CI rules matches the stated main branch
SDD framework initialized successfully (Phase 3)
- OpenSpec:
```
openspec/specs/
```
  and
```
openspec/changes/
```
  exist
- SpecKit:
```
specs/
```
  and
```
memory/constitution.md
```
  exist
- GSD:
```
.planning/
```
  contains PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json
```
scripts/
```
directory was populated by running
```
install_scripts.py
```
(not manually recreated or copy-pasted)
The correct single variant (
```
.sh
```
on Linux/macOS,
```
.ps1
```
on Windows,
```
.js
```
as fallback) is present in
```
scripts/
```

.gitlab-ci.yml

(if generated) contains all required jobs:

lint

unit-tests

commit-format

full-test-suite

coverage-gate

security-scan

project-tag-check

sdd-process-check

deploy

.github/workflows/ci.yml

(if generated) contains all required jobs:

lint

unit-tests

commit-format

full-test-suite

security-scan

project-tag-check

sdd-process-check

No jobs were removed or merged compared to the template; only
```
{{PLACEHOLDER}}
```
tokens were substituted
```
AGENTS.md
```
starts with a valid
```
<!-- @project-initializer
```
tag
First commit includes: README.md, AGENTS.md, CI files, scripts/, and framework directories

Report any inconsistencies to the user before finishing.

生成所有文件后，执行以下检查清单：

```
AGENTS.md
```
开头包含有效的
```
<!-- @project-initializer
```
标记
标记中的
```
sdd_framework
```
与所选框架一致
标记中的
```
ci_platforms
```
与实际生成的文件一致
CI文件中的Docker/运行器镜像与技术栈匹配
```
AGENTS.md
```
中的技术栈部分与
```
README.md
```
一致
CI文件中的覆盖率阈值与
```
AGENTS.md
```
→ 质量标准一致
SDD框架名称在所有生成文件中保持一致
引用了正确的SDD检查脚本（OpenSpec/SpecKit/GSD）
若同时生成了两个CI平台文件，使用完全相同的质量阈值
CI规则中的分支名称与指定的主分支一致
SDD框架初始化成功（第三阶段）
- OpenSpec：
```
openspec/specs/
```
  和
```
openspec/changes/
```
  存在
- SpecKit：
```
specs/
```
  和
```
memory/constitution.md
```
  存在
- GSD：
```
.planning/
```
  包含PROJECT.md、REQUIREMENTS.md、ROADMAP.md、STATE.md、config.json
```
scripts/
```
目录是通过运行
```
install_scripts.py
```
填充的（而非手动创建或复制粘贴）
```
scripts/
```
中存在正确的单一版本（Linux/macOS用
```
.sh
```
，Windows用
```
.ps1
```
， fallback用
```
.js
```
）

.gitlab-ci.yml

（若生成）包含所有必需任务：

lint

、

unit-tests

、

commit-format

、

full-test-suite

、

coverage-gate

、

security-scan

、

project-tag-check

、

sdd-process-check

、

deploy

.github/workflows/ci.yml

（若生成）包含所有必需任务：

lint

、

unit-tests

、

commit-format

、

full-test-suite

、

security-scan

、

project-tag-check

、

sdd-process-check

与模板相比，未删除或合并任何任务；仅替换了
```
{{PLACEHOLDER}}
```
标记
```
AGENTS.md
```
开头包含有效的
```
<!-- @project-initializer
```
标记
首次提交包含：README.md、AGENTS.md、CI文件、scripts/ 及框架目录

完成检查后，若发现不一致，向用户报告。

Reference files

参考文件

```
references/openspec.md
```
— OpenSpec document structure, sync workflow, ignore tags
```
references/speckit.md
```
— SpecKit spec lifecycle, constitution, phase gates, ignore tags
```
references/gsd.md
```
— GSD phase workflow, document set, planning structure, ignore tags
```
references/flask-backend.md
```
— Flask 后端目录结构、分层、Blueprint、UV、钩子（项目类型 = Flask 后端时使用）
```
references/backend-python-cicd.md
```
— Python + GitLab CI：多阶段 Docker、分支、K8s、私有镜像（用户选择该规范时使用）
```
references/frontend-codegen.md
```
— React 功能/页面/组件开发：复用优先、UI/业务分层、数据化路由、测试先行（React 项目后续开发）
```
references/flask-backend-codegen.md
```
— Flask 新增 API/资源：路由、Service、Model、Schema、权限、测试（Flask 项目后续开发）
```
references/qa-testing.md
```
— 测试计划、用例、自动化、报告与系统性根因分析（用户选择引用 QA 时使用）
```
references/agent-roles.md
```
— 多角色规划与 Cursor 子代理（.cursor/agents/*.md）（用户选择多角色/子代理时使用）

```
references/openspec.md
```
— OpenSpec文档结构、同步工作流、忽略标签
```
references/speckit.md
```
— SpecKit规范生命周期、约束规则、阶段门槛、忽略标签
```
references/gsd.md
```
— GSD阶段工作流、文档集、规划结构、忽略标签
```
references/flask-backend.md
```
— Flask后端目录结构、分层、Blueprint、UV、钩子（项目类型=Flask后端时使用）
```
references/backend-python-cicd.md
```
— Python + GitLab CI：多阶段Docker构建、分支策略、K8s部署、私有镜像（用户选择该规范时使用）
```
references/frontend-codegen.md
```
— React功能/页面/组件开发：复用优先、UI/业务分层、数据化路由、测试先行（React项目后续开发）
```
references/flask-backend-codegen.md
```
— Flask新增API/资源：路由、Service、Model、Schema、权限、测试（Flask项目后续开发）
```
references/qa-testing.md
```
— 测试计划、用例、自动化、报告与系统性根因分析（用户选择引用QA时使用）
```
references/agent-roles.md
```
— 多角色规划与Cursor子代理（.cursor/agents/*.md）（用户选择多角色/子代理时使用）

Installation scripts

安装脚本

All script paths are relative to

<skill_dir>

(the directory containing this SKILL.md).

<project_root>

is the project's root — use

if already inside it.

scripts/install_scripts.py

— copies check scripts into

<project_root>/scripts/

Usage:

python <skill_dir>/scripts/install_scripts.py <project_root> --framework <openspec|speckit|gsd>

Always run this instead of manually copying scripts. Add

--dry-run

to preview.

```
scripts/initialize_sdd.py
```
— installs SDD framework tools and initializes project structure
Usage:
```
python <skill_dir>/scripts/initialize_sdd.py <project_root> --framework <openspec|speckit|gsd> --ai-provider <agent>
```
Must be run — do not manually create SDD directories. Installs the framework CLI non-interactively, sets up directories. Add
```
--dry-run
```
to preview.

所有脚本路径均相对于

<skill_dir>

（包含本SKILL.md文件的目录）。

<project_root>

。

scripts/install_scripts.py

— 将检查脚本复制到

<project_root>/scripts/

使用方式：

python <skill_dir>/scripts/install_scripts.py <project_root> --framework <openspec|speckit|gsd>

请始终运行此脚本，而非手动复制脚本。添加

--dry-run

预览操作。

```
scripts/initialize_sdd.py
```
— 安装SDD框架工具并初始化项目结构
使用方式：
```
python <skill_dir>/scripts/initialize_sdd.py <project_root> --framework <openspec|speckit|gsd> --ai-provider <agent>
```
必须运行 — 请勿手动创建SDD目录。以非交互式方式安装框架CLI，设置目录。添加
```
--dry-run
```
预览操作。

Template files

模板文件

```
assets/templates/README.template.md
```

assets/templates/AGENTS.template.md

— 通用项目；项目类型 = React 前端时改用

assets/templates/AGENTS.react.template.md

assets/templates/AGENTS.react.template.md

— React 前端项目 AGENTS 模板

assets/templates/AGENTS.taro.template.md

— Taro 小程序项目 AGENTS 模板

```
assets/templates/gitlab-ci.template.yml
```

assets/templates/github-actions.template.yml

Flask 后端：
```
assets/flask-backend/
```
（project-structure.txt、create_app_snippet.py、env-example.txt、pyproject-uv.example.toml、uv-usage.md）
Python GitLab CI/K8s：
```
assets/backend-python-cicd/
```
（dockerfile-python-base.md、docker-build-commands.md、git-operations.md、k8s/、scripts/、gitlab-ci-example.yml、pipeline-overview.md）
Flask 代码生成：
```
assets/flask-backend-codegen/
```
（response-format.json、code-snippets.md）；可选
```
scripts/check_route_layer.py
```
角色与子代理：
```
assets/agent-roles/
```
（role-template.json、scenario-roles-example.json、subagent-cursor-template.md、config-template.json）；可选
```
scripts/validate_roles.py
```

```
assets/templates/README.template.md
```

assets/templates/AGENTS.template.md

— 通用项目；项目类型=React前端时改用

assets/templates/AGENTS.react.template.md

assets/templates/AGENTS.react.template.md

— React前端项目AGENTS模板

assets/templates/AGENTS.taro.template.md

— Taro小程序项目AGENTS模板

```
assets/templates/gitlab-ci.template.yml
```

assets/templates/github-actions.template.yml

Flask后端：
```
assets/flask-backend/
```
（project-structure.txt、create_app_snippet.py、env-example.txt、pyproject-uv.example.toml、uv-usage.md）
Python GitLab CI/K8s：
```
assets/backend-python-cicd/
```
（dockerfile-python-base.md、docker-build-commands.md、git-operations.md、k8s/、scripts/、gitlab-ci-example.yml、pipeline-overview.md）
Flask代码生成：
```
assets/flask-backend-codegen/
```
（response-format.json、code-snippets.md）；可选
```
scripts/check_route_layer.py
```
角色与子代理：
```
assets/agent-roles/
```
（role-template.json、scenario-roles-example.json、subagent-cursor-template.md、config-template.json）；可选
```
scripts/validate_roles.py
```

Check scripts

检查脚本

Each check is available in three runtime variants, stored in the skill's

assets/scripts/

directory. The install_scripts.py command copies these into the target project's

scripts/

directory — which variant gets invoked in CI depends on the runner OS and what's available.

Script	Shell (Linux/macOS)	PowerShell (Windows/cross-platform)	Node.js (any platform)
Project tag	`check_project_tag.sh`	`check_project_tag.ps1`	`check_project_tag.js`
OpenSpec	`check_sdd_openspec.sh`	`check_sdd_openspec.ps1`	`check_sdd_openspec.js`
SpecKit	`check_sdd_speckit.sh`	`check_sdd_speckit.ps1`	`check_sdd_speckit.js`
GSD	`check_sdd_gsd.sh`	`check_sdd_gsd.ps1`	`check_sdd_gsd.js`

每个检查都有三种运行时版本，存储在技能的

assets/scripts/

目录中。install_scripts.py命令会将这些脚本复制到目标项目的

scripts/

目录 — CI中使用哪个版本取决于运行器OS和可用环境。

脚本	Shell（Linux/macOS）	PowerShell（Windows/跨平台）	Node.js（任意平台）
项目标记检查	`check_project_tag.sh`	`check_project_tag.ps1`	`check_project_tag.js`
OpenSpec检查	`check_sdd_openspec.sh`	`check_sdd_openspec.ps1`	`check_sdd_openspec.js`
SpecKit检查	`check_sdd_speckit.sh`	`check_sdd_speckit.ps1`	`check_sdd_speckit.js`
GSD检查	`check_sdd_gsd.sh`	`check_sdd_gsd.ps1`	`check_sdd_gsd.js`

Selecting which variant to use in CI

在CI中选择使用的版本

When generating CI pipeline files, choose the invocation command based on the project's runner environment:

Runner environment	CI invocation
Linux / macOS (bash available)	`bash scripts/check_sdd_<fw>.sh`
Windows (PowerShell 7+ available)	`pwsh scripts/check_sdd_<fw>.ps1`
Any (Node.js ≥ 18 available)	`node scripts/check_sdd_<fw>.js`
Unknown / mixed	Use Node.js — it works everywhere Node.js is installed

The Node.js variants are the most portable choice if the runner environment is uncertain. They require no npm dependencies — only the Node.js built-in modules (

fs

path

child_process

The GitLab CI and GitHub Actions templates default to the shell variant. If the user's CI runners are Windows-based or they prefer Node.js, update the

script:

run:

lines accordingly. All three variants implement identical logic and exit codes.

undefined

生成CI流水线文件时，根据项目的运行器环境选择调用命令：

运行器环境	CI调用命令
Linux / macOS（bash可用）	`bash scripts/check_sdd_<fw>.sh`
Windows（PowerShell 7+可用）	`pwsh scripts/check_sdd_<fw>.ps1`
任意（Node.js ≥18可用）	`node scripts/check_sdd_<fw>.js`
未知/混合环境	使用Node.js版本 — 只要安装了Node.js，在任何环境都能运行

若不确定运行器环境，Node.js版本是最便携的选择。它们不需要npm依赖 — 仅使用Node.js内置模块（

fs

、

path

、

child_process

）。

GitLab CI和GitHub Actions模板默认使用Shell版本。若用户的CI运行器是Windows系统或偏好Node.js，请相应更新

script:

run:

行。三个版本实现的逻辑和退出码完全相同。