[HINT] Download the complete skill directory including SKILL.md and all related files
| name | sds-init |
| description | 项目初始化——扫描项目源码信息并自动填充 .claude/ 配置文件中的项目信息段落 |
扫描目标项目的源码，提取技术栈版本、数据库信息、中间件、目录结构、代码模式等项目信息，然后直接 Edit 替换 .claude/ 配置文件中对应的项目信息段落。替换完成后自动进行一轮评审验证。
.claude/ 配置时调用 /sds-init.claude/ 目录已存在并包含配置文件（如不存在，先提示用户复制 claudeConfig）第一步：扫描项目信息（含登录接口与鉴权检测）→ 第二步：E2E 框架自动配置 → 第三步：展示扫描结果供用户确认 → 第四步：Edit 替换 15 个配置文件 + 新建 auth.md（共 16 处变更）→ 第五步：审批通用配置文件 → 第六步：评审验证 → 第七步：最终报告
使用 Read/Glob/Grep/Bash 扫描项目源码，按以下子步骤执行：
basename 或 ls）<artifactId>/<name>/<version>/<modules>/<java.version> 和关键依赖（spring-boot、mybatis-plus、redisson、sa-token/spring-security、druid/hikari）name/version/dependencies（vue、element-ui/element-plus、vuex/pinia、typescript）和 scripts（build/test/lint/e2e）application*.yaml / application*.yml / application*.propertiesspring.datasource.url（或 spring.datasource.dynamic.datasource.master.url）characterEncoding → charsetsql/ 下各数据库子目录（sql/mysql/、sql/postgresql/ 等）ENGINE=xxx DEFAULT CHARSET=xxx COLLATE=xxxspring.redis.* / spring.data.redis.* / spring.rabbitmq.* / spring.activemq.* / spring.kafka.*<modules> → 模块列表*-framework/ 和 *-dependencies/mvn clean compile（编译）、mvn test（测试）mvn spotless:apply（格式化）npm run build:prod、npm run lint(java|xml|vue|js|sql|yaml|yml)$）这是 SDA agents 配置依赖的关键信息。用 Grep + Read 采样检测：
后端模式：
@TableName → ORM 表注解BaseDO → DO 基类名BaseMapper → Mapper 基类LambdaQueryWrapperX → 查询构建器类*SaveReqVO / *PageReqVO / *RespVO → VO 命名后缀@PreAuthorize("@ss.hasPermission") → 权限 SpEL bean 名（如 ss）xxx:create/update/delete/query/exportCommonResult / PageResult → 响应包装类ServiceException / BizException → 业务异常类#{} vs ${} → SQL 参数绑定风格（mapper XML）EncryptTypeHandler → 加密字段处理器@TableLogic → 逻辑删除注解@MapperScan → Mapper 扫描注解包路径前端模式：
v-hasPermi / 其他权限指令 → 权限指令名this.$modal.msgSuccess / this.$modal.confirm → modal 方法<ContentWrap> / <Pagination> → 自定义组件import request from '@/utils/request' → API 请求工具路径核心目标：找出系统登录接口和鉴权方式，配置测试和调试时的认证流程。所有后端接口测试都必须先调用登录接口获取 token，然后按照系统鉴权方式携带 token 请求。
spring-boot-starter-security / sa-token / jwt / jjwt 等依赖@EnableWebSecurity / @Configuration + SecurityConfig / SaTokenConfig 等配置类@PostMapping / @GetMapping + login / signin / auth 关键字login 相关 Controller 方法名/login、/auth/login）Token 类型检测：
JwtUtil / JwtHelper / Jwts → JWT 类型session.getId() / session.setAttribute() → Session 类型StpUtil / SaManager → Sa-Token 类型Token 携带方式检测：
Authorization / Bearer → Header 携带方式Cookie / addCookie → Cookie 携带方式request.getHeader → 自定义 Header 名称Token 前缀检测：
Bearer / Bearer → Bearer 前缀refresh / refreshToken / renewINSERT INTO sys_user / INSERT INTO user强制要求：测试账号是测试功能的必要条件。未检测到时必须要求用户输入；用户拒绝输入时在报告中标注"未配置测试账号，测试功能将受限"。
AI 合成以下信息：
登录接口:
路径: /login
方法: POST
参数: { username: string, password: string, captcha: string, uuid: string }
返回: { token: string, user: object }
鉴权方式:
框架: Spring Security / Sa-Token / 自定义
Token类型: JWT / Session / 其他
Token携带: Header#Authorization
Token前缀: Bearer
Token有效期: 24h
刷新接口:
路径: /refresh
方法: POST
测试账号:
- 用户名: admin, 密码: admin123, 角色: 超级管理员
- 用户名: test, 密码: test123, 角色: 普通用户
强制要求：除纯后端项目和移动端项目外，所有项目必须配置 E2E 测试框架，不允许跳过或降级。
检查项目中是否已存在 E2E 测试框架：
package.json 中是否已安装 Playwright / Cypress / Nightwatch 等playwright.config.js、cypress.config.ts）tests/e2e/、cypress/）选择理由：Playwright 是现代 Web 应用的首选 E2E 框架，支持 Vue/React 等主流框架，API 简洁，文档完善。
前置条件：项目必须有 package.json（纯后端项目跳过此步骤）
安装步骤：
安装 Playwright 依赖
cd <前端项目目录>
npm install -D @playwright/test
创建 Playwright 配置文件
创建 playwright.config.js（内容见下方模板）
创建测试目录结构
<前端项目>/
└── tests/
└── e2e/
├── pages/ # 页面对象
├── specs/ # 测试用例
├── fixtures/ # 测试数据
└── utils/ # 测试工具
添加 E2E 测试脚本到 package.json
在 scripts 中添加：
{
"test:e2e": "playwright test",
"test:e2e:ui": "playwright test --ui",
"test:e2e:headed": "playwright test --headed"
}
安装浏览器
npx playwright install chromium
创建 playwright.config.js：
const { defineConfig, devices } = require('@playwright/test');
module.exports = defineConfig({
testDir: './tests/e2e/specs',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
use: {
baseURL: process.env.BASE_URL || 'http://localhost:80',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
},
projects: [
{
name: 'chromium',
use: { ...devices['Desktop Chrome'] },
},
],
webServer: {
command: 'npm run dev',
url: 'http://localhost:80',
reuseExistingServer: !process.env.CI,
timeout: 120000,
},
});
cd <前端项目目录>
npx playwright test --version
验证输出包含 Playwright 版本号，表示安装成功。
如项目无 package.json（纯后端项目）：
/sds-init 重新初始化移动端项目（uni-app、React Native、Flutter 等）不适用 Web E2E 测试框架。
如检测到移动端项目（如 package.json 中包含 uni-app、react-native、flutter、taro、mpvue 等）：
用 AskUserQuestion 展示扫描摘要，包括：
测试账号处理流程：
如已检测到测试账号：
如未检测到测试账号：
用户确认 → 继续替换；用户调整 → 修正后继续。
强制要求：secrets.json 必须与项目数据库、中间件配置保持一致，这是 sds-dbquery 等工具正常运行的前提。
逐文件逐段落 Edit，只替换项目信息段落，不触碰规则/治理/流程内容。
此文件关系到 db-query.py 等工具能否正常运行，必须与项目配置一致。
替换字段（从 application*.yml 扫描获取）：
db_master_url → 从 spring.datasource.druid.master.url 提取完整 JDBC URL（必须保留 currentSchema、characterEncoding 等参数，db-query.py 会自动解析）db_master_host → 从 JDBC URL 解析 hostdb_master_port → 从 JDBC URL 解析 portdb_master_name → 从 JDBC URL 解析 dbname（如 digital_housing）db_master_user → 从 spring.datasource.druid.master.username 提取db_master_password → 从 spring.datasource.druid.master.password 提取db_slave_* → 从 spring.datasource.druid.slave 提取（如未启用则留空）redis_host → 从 spring.redis.cluster.nodes 或 spring.redis.host 提取redis_port → 从 spring.redis.cluster.nodes 提取（如为集群，取第一个节点的 port）redis_password → 从 spring.redis.password 提取（如无密码则留空）rabbit_host → 从 rocketmq.name-server 或 spring.rabbitmq.* 提取rabbit_port → 从 rocketmq.name-server 或 spring.rabbitmq.* 提取注意：
- secrets.json 中
real_values和placeholders的对应字段必须同步更新db_master_url必须完整保留原始参数（currentSchema、characterEncoding、serverTimezone 等），不得截断
替换段落：
替换段落：
替换段落：
替换段落：
mvn jacoco:report；否则"无"）替换段落：
替换段落：
#{} not ${}）→ 如项目用 JPA 则删除此条，改为 JPA 参数绑定安全规则@PreAuthorize("@ss.hasPermission")）→ 换为扫描结果替换段落：
yarn install && yarn build:prod → npm install && npm run build:prod）替换段落：
SET NAMES utf8mb4 → 实际 charset）替换段落：
ss）替换段落：
替换段落：
替换段落：
替换段落：
替换段落：
新建文件：存储系统登录接口和鉴权配置信息，供所有 SDA 和测试工具使用。
创建文件并写入以下内容：
# 系统认证配置
> 本文件由 /sds-init 自动生成，存储登录接口和鉴权方式信息。
## 登录接口
- **路径**：{实际路径，如 /login}
- **方法**：{实际方法，如 POST}
- **参数**：
- username: {类型，如 string}
- password: {类型，如 string}
- captcha: {类型，如 string（可选）}
- uuid: {类型，如 string（可选）}
- **返回**：
- token: {字段名，如 token}
- user: {用户信息对象}
## 鉴权方式
- **框架**：{实际框架，如 Spring Security / Sa-Token / 自定义}
- **Token 类型**：{实际类型，如 JWT / Session / 其他}
- **Token 携带方式**：{实际方式，如 Header#Authorization}
- **Token 前缀**：{实际前缀，如 Bearer}
- **Token 有效期**：{实际有效期，如 24h}
## Token 刷新
- **刷新接口**：{实际路径，如 /refresh}
- **刷新方法**：{实际方法，如 POST}
- **刷新参数**：{实际参数}
## 测试账号
> **重要提示**：测试账号由用户在初始化时手动输入，用于测试和调试。
| 用户名 | 密码 | 角色 | 说明 |
|--------|------|------|------|
| {用户输入的用户名} | {用户输入的密码} | {用户输入的角色} | {用户输入的说明} |
> 如未配置测试账号：标注"未配置测试账号，测试功能将受限"
> **安全提醒**：测试账号信息存储在本地配置文件中，不会提交到 Git。请勿使用生产环境账号密码。
## 测试认证流程
> **所有后端接口测试必须遵循此流程**
1. **登录获取 Token**
```bash
# 示例请求（使用配置的测试账号）
# 用户名密码从 .claude/knowledge/auth.md 读取
curl -X POST http://localhost:8080/login \
-H "Content-Type: application/json" \
-d "{\"username\":\"$TEST_USERNAME\",\"password\":\"$TEST_PASSWORD\"}"
# 响应示例
{"token":"eyJhbGciOiJIUzUxMiJ9...","user":{...}}
重要：命令行测试时，用户名密码应从环境变量或配置文件读取，禁止硬编码。
携带 Token 请求业务接口
# 示例请求（Header 方式）
curl -X GET http://localhost:8080/api/xxx \
-H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."
# 示例请求（Cookie 方式）
curl -X GET http://localhost:8080/api/xxx \
-H "Cookie: JSESSIONID=xxx"
测试代码示例
// 单元测试认证示例
@BeforeEach
void setUp() {
// 1. 登录获取 token（使用配置的测试账号）
// 测试账号从 .claude/knowledge/auth.md 读取
String username = getConfiguredTestUsername(); // 从配置读取
String password = getConfiguredTestPassword(); // 从配置读取
LoginRequest loginRequest = new LoginRequest(username, password);
LoginResponse loginResponse = authService.login(loginRequest);
this.token = loginResponse.getToken();
// 2. 设置到请求头
mockMvc = MockMvcBuilders.webAppContextSetup(context)
.defaultRequest(post("/api/xxx")
.header("Authorization", "Bearer " + token))
.build();
}
重要：测试代码中禁止硬编码用户名密码，必须从配置文件读取。
| 日期 | 变更内容 | 原因 |
|---|---|---|
| {日期} | 初始化认证配置 | /sds-init 自动生成 |
---
## 第五步：审批通用配置文件
审批 settings.json、hooks/*.ps1、tools/*.py、secrets.json 是否符合当前项目技术栈和项目结构，不符合则修改。
- Read: `.claude/settings.json` → 检查 allow 列表是否覆盖当前项目的命令（Bash 允许 mvn/npm/git/node/python 等）
- Glob: `.claude/hooks/*.ps1` → 读取每个 ps1 脚本，检查是否涉及项目特有的路径/命令
- Glob: `.claude/tools/*.py` → 读取每个 py 工具，检查是否涉及项目特有的路径/框架
- **Read: `.claude/tools/secrets.json` → 验证数据库类型是否与项目一致**
- 检查 `db_master_url` 的 JDBC 前缀：`jdbc:mysql://` / `jdbc:postgresql://` / `jdbc:highgo://`
- 如 db-query.py 使用 psycopg2，则 `db_master_url` 必须为 PostgreSQL 兼容格式
- 如 db-query.py 使用 pymysql，则 `db_master_url` 必须为 MySQL 格式
- 如不匹配，Edit 修正 secrets.json 并更新 db-query.py 的连接参数
- **验证中间件配置完整性**：检查 secrets.json 中的 redis/rabbit 字段是否与 application*.yml 一致，如不一致则修正
发现不符合 → Edit 修正。
### 5.1 JDBC URL 参数同步（强制）
> **问题背景**：JDBC URL 中的 `currentSchema`、`characterEncoding`、`serverTimezone` 等参数直接影响数据库连接和字符编码。db-query.py 必须完整保留这些参数，否则可能导致连接失败或中文乱码。
**强制要求**：所有项目的 db-query.py 必须支持从 JDBC URL 解析完整参数。
**处理流程**：
1. **从 JDBC URL 解析完整参数**
- 提取数据库类型（mysql/postgresql/highgo/kingbase/dm）
- 提取 `currentSchema` → schema 名称
- 提取 `characterEncoding` → 字符编码
- 提取 `serverTimezone` → 时区
- 提取其他关键参数（如 `useUnicode`、`allowMultiQueries`）
2. **询问用户提供本地数据库驱动 jar 路径**
> **重要**：不同项目的数据库驱动可能不同（如 HighGo/PostgreSQL/MySQL 等），必须询问用户提供本地的 JDBC driver jar 路径。
使用 AskUserQuestion 询问：
- 数据库驱动 jar 路径（如 `C:/Users/xxx/.m2/repository/com/highgo/hgdb-pgjdbc/42.5.0/hgdb-pgjdbc-42.5.0.jar`）
- 验证路径是否存在
3. **回退处理**：如项目无 `package.json`（纯后端项目），跳过步骤 2（询问用户提供 JDBC driver jar 路径），直接使用 Maven 本地仓库搜索 JDBC driver
4. **修改 db-query.py 支持 schema 和编码参数**
在 `get_secrets_url_config()` 函数中解析参数：
```python
def get_secrets_url_config(secrets):
real = secrets["real_values"]
full_url = real.get("db_master_url", "")
# 通用匹配：jdbc:数据库类型://host:port/database?params
match = re.match(r'jdbc:([^:]+)://([^/:]+):(\d+)/([^?]+)\??(.*)', full_url)
if not match:
return None
db_type = match.group(1) # mysql / postgresql / highgo / kingbase / dm
host = match.group(2)
port = int(match.group(3))
database = match.group(4)
params = match.group(5)
# 解析 schema 从 currentSchema 参数
schema = None
for param in params.split('&'):
if param.startswith('currentSchema='):
schema = param.split('=')[1]
break
return {
"host": host,
"port": port,
"database": database,
"schema": schema,
"user": real["db_master_user"],
"password": real["db_master_password"],
"full_url": full_url,
"db_type": db_type
}
在 build_jdbc_url() 中优先使用完整 URL：
def build_jdbc_url(config):
# 使用完整 URL（保留所有参数）
if "full_url" in config:
return config["full_url"]
# 回退：手动拼接
host = config["host"]
port = config["port"]
database = config["database"]
schema = config.get("schema")
url = f"jdbc:{config.get('db_type', 'postgresql')}://{host}:{port}/{database}"
if schema:
url += f"?currentSchema={schema}"
return url
修改 get_jdbc_jars() 支持固定驱动路径：
# Fixed JDBC driver path（从用户输入获取）
JDBC_FIXED_JAR = "<用户提供的jar路径>"
def get_jdbc_jars(db_type="postgresql"):
"""Find JDBC jar files from local Maven repository based on database type."""
# Use fixed driver if available and exists
if os.path.exists(JDBC_FIXED_JAR):
return [JDBC_FIXED_JAR]
# ... otherwise search Maven repo
根据数据库类型选择 JDBC driver class：
# 根据数据库类型选择 JDBC driver class
DRIVER_MAP = {
"mysql": "com.mysql.cj.jdbc.Driver",
"postgresql": "org.postgresql.Driver", # HighGo 也使用此驱动类名
"kingbase": "com.kingbase.Driver",
"dm": "dm.jdbc.driver.DmDriver",
}
def get_driver_class(db_type, jdbc_driver):
# 如果使用固定驱动，HighGo/PostgreSQL 都用 org.postgresql.Driver
if jdbc_driver and "highgo" in jdbc_driver.lower():
return "org.postgresql.Driver"
return DRIVER_MAP.get(db_type, "org.postgresql.Driver")
更新 secrets.json 中的配置
db_master_url 完整保留原始参数db_master_schema → 从 JDBC URL 的 currentSchema= 参数提取（如未指定则为 public）验证连接
执行测试查询验证连接正常且无乱码：
python .claude/tools/db-query.py --query "SELECT version()"
问题背景：PowerShell 在解析含中文字符的路径时存在编码问题，导致 hooks 脚本执行失败（报错：无法识别文件格式或路径不存在）。项目路径含中文（如
C:/Users/xxx/Desktop/住建厅/数据治理/）时，.claude/hooks/*.ps1的相对路径会触发此问题。
检测条件：当前系统为 Windows（platform: win32）且项目路径包含非 ASCII 字符。
处理流程：
检测项目路径是否含中文
echo $PWD | grep -P '[^\x00-\x7F]' 检测检查 hooks 脚本路径是否含中文或特殊字符
command 路径ls "<用户输入的绝对路径>" 或 test -d "<绝对路径>"如项目路径含中文且需要迁移 hooks 脚本，执行以下步骤
询问用户输入一个纯 ASCII 路径（如 C:/Users/andyh/.claude/hooks-scripts），用于存放 hooks 脚本。
提示：推荐使用
~/.claude/hooks-scripts（即C:/Users/<用户名>/.claude/hooks-scripts），这是 Claude Code 全局配置目录，不随项目路径变化。
使用 mkdir -p "<用户输入的路径>" 创建目录。
从 .claude/hooks/*.ps1 读取所有 ps1 脚本内容，复制到新目录。
关键修改：每个脚本中 $secretsPath 的相对路径引用改为绝对路径：
# 原（相对路径，会受工作目录中文影响）：
$secretsPath = Join-Path $PSScriptRoot "..\tools\secrets.json"
# 改为（绝对路径，绕过中文路径问题）：
$secretsPath = "C:/Users/<用户名>/.claude/tools/secrets.json"
注意：脚本中如有
param()声明，保留不动；仅修改路径相关变量。
将 .claude/settings.json 中所有 hooks 的 command 路径从相对路径改为绝对路径：
// 改前（相对路径，含 .claude/hooks/）
"command": "powershell -ExecutionPolicy Bypass -File .claude/hooks/post-sensitive-read.ps1"
// 改后（绝对路径，指向 ASCII 目录）
"command": "powershell -ExecutionPolicy Bypass -File \"C:/Users/xxx/.claude/hooks-scripts/post-sensitive-read.ps1\""
涉及的文件：
pre-bash-check.ps1post-sensitive-read.ps1post-sensitive-scan.ps1post-edit-check.ps1运行测试命令验证：
powershell -ExecutionPolicy Bypass -File "<新路径>/pre-bash-check.ps1" < /dev/null; echo "Exit: $?"
预期输出：Exit: 0（无错误）
如项目路径为纯 ASCII，跳过上述步骤，hooks 脚本保持在 .claude/hooks/ 原位不动。
替换完成后，自动触发评审：
Read 所有 16 个被修改的文件，逐文件验证替换内容。
发现不一致 → Edit 修正。修正后重新验证该文件。
全部验证通过 → 进入第七步。
展示完整验证报告：
=== 项目初始化报告 ===
扫描信息：
项目名称: xxx
技术栈: xxx
数据库: xxx
中间件: xxx
登录接口与鉴权：
✅ 登录接口: /login (POST)
- 参数: username, password
- 返回: token, user
✅ 鉴权方式: Spring Security + JWT
- Token携带: Header#Authorization
- Token前缀: Bearer
- 有效期: 24h
✅ 测试账号: admin/admin123 (超级管理员), test/test123 (普通用户)
⚠️ 未检测到登录接口 — 需手动配置
⚠️ 未配置测试账号 — 测试功能将受限
E2E 测试框架：
✅ Playwright — 已安装并配置完成
- 配置文件: playwright.config.js
- 测试目录: tests/e2e/
- 测试命令: npm run test:e2e
ℹ️ 纯后端项目 — 跳过 E2E 配置
ℹ️ 移动端项目 — E2E 降级为人工验收
配置文件变更（共 16 处）：
✅ secrets.json — 数据库/中间件连接配置（替换）
✅ CLAUDE.md — 项目信息区/命令/目录/红线（替换）
✅ structure.md — 目录树/导航/ADR（替换）
✅ dbinfo.md — charset/方言/DB类型（替换）
✅ testing.md — 命令/E2E（替换）
✅ frontend.md — 技术栈（替换）
✅ security.md — ORM/权限（替换）
✅ governance.md — 构建命令/端口（替换）
✅ sda-db-implementer.md — SQL规范/字段/DO/Mapper（替换）
✅ sda-backend.md — VO/Service/Controller/权限/登录接口/鉴权方式（替换）
✅ sda-frontend.md — 技术栈/组件/API（替换）
✅ sda-tester.md — 注解/stubs/命令/E2E/登录认证/测试账号（替换）
✅ sda-architect.md — 权限/菜单表（替换）
✅ sda-code-reviewer.md — ORM检查/权限（替换）
✅ sda-build-error-resolver.md — 框架/命令（替换）
✅ auth.md — 登录接口/鉴权方式/测试账号/认证流程（新建）
已审批通用配置文件：
✅ settings.json — allow 列表
✅ hooks/*.ps1 — 路径/命令适配（Windows 中文路径已迁移至 ASCII 目录）
✅ tools/*.py — 路径/框架适配
✅ secrets.json — 数据库/中间件配置一致性
评审验证：
✅ secrets.json ↔ application*.yml 数据库配置一致
✅ db-query.py 连接库 ↔ secrets.json 数据库类型一致
✅ 全部交叉验证通过
需用户手动确认的信息：
- ADR 技术选型原因（AI 推断技术，原因需人工填写）
- 已知陷阱（团队踩坑经验）
- 其他团队约定
- 测试账号（如未配置）
下一步：
1. 手动填写 ADR 原因和已知陷阱
2. 如未配置测试账号，需用户手动输入
3. 提交 Git
用 AskUserQuestion 询问用户是否需要填写 ADR 原因等手动信息。用户选择填写 → 逐项询问；用户选择跳过 → 结束初始化。
注意：测试账号是测试功能的必要条件。如果用户拒绝配置测试账号，在 auth.md 中标注"未配置测试账号"，并提示后续测试功能将受限。