airail 0.1.6 → 0.1.7

package/dist/cli/add.js

@@ -75,13 +75,6 @@ async function cmdAdd(arg) {
     (0, utils_1.writeAirailJson)(claudeDir, config);
 }
 function readPackName(dir) {
-    const p = path.join(dir, 'pack.json');
-    if (fs.existsSync(p)) {
-        try {
-            return JSON.parse(fs.readFileSync(p, 'utf-8')).name || path.basename(dir);
-        }
-        catch { }
-    }
     return path.basename(dir);
 }
 async function installGitPack(url, claudeDir, config) {
@@ -121,7 +114,14 @@ async function installPackFromConfigCenter(packNameWithVersion, claudeDir, confi
         console.log((0, colors_1.info)(`可用规范包: ${packs.map(p => p.name).join(', ')}`));
         throw new Error('');
     }
-    // 使用用户指定的版本，如果没有指定则使用配置仓库的版本
+    // 本地规范包（gitUrl 为空）
+    if (!pack.gitUrl) {
+        console.log((0, colors_1.ok)(`找到本地规范包: ${pack.name} v${pack.version}`));
+        console.log((0, colors_1.info)(`${pack.description}`));
+        await installLocalPackFromConfigRepo(packName, claudeDir, config, rc);
+        return;
+    }
+    // 第三方规范包
     const gitRef = userVersion || pack.gitRef;
     const gitUrl = gitRef ? `${pack.gitUrl}#${gitRef}` : pack.gitUrl;
     const versionInfo = userVersion
@@ -134,3 +134,26 @@ async function installPackFromConfigCenter(packNameWithVersion, claudeDir, confi
     console.log((0, colors_1.info)(`正在从 Git 仓库安装...`));
     await installGitPack(gitUrl, claudeDir, config);
 }
+async function installLocalPackFromConfigRepo(packName, claudeDir, config, rc) {
+    const configRepoDir = path.join(os.homedir(), '.airail', 'config-repo');
+    // 确保配置仓库已克隆
+    if (!fs.existsSync(configRepoDir)) {
+        console.log((0, colors_1.info)('正在克隆配置仓库...'));
+        const cloneCmd = rc.configToken
+            ? `git clone https://oauth2:${rc.configToken}@${rc.configServer.replace(/^https?:\/\//, '')} ${configRepoDir}`
+            : `git clone ${rc.configServer} ${configRepoDir}`;
+        (0, child_process_1.execSync)(cloneCmd, { stdio: 'pipe' });
+    }
+    else {
+        console.log((0, colors_1.info)('正在更新配置仓库...'));
+        (0, child_process_1.execSync)('git pull', { cwd: configRepoDir, stdio: 'pipe' });
+    }
+    const packDir = path.join(configRepoDir, 'packs', packName);
+    if (!fs.existsSync(packDir)) {
+        console.error((0, colors_1.err)(`配置仓库中不存在本地规范包: packs/${packName}/`));
+        throw new Error('');
+    }
+    (0, utils_1.installPackFromDir)(packDir, packName, claudeDir);
+    config.pack = packName;
+    console.log((0, colors_1.ok)(`已安装本地规范包: ${packName} (来自配置仓库)`));
+}

package/dist/cli/config.js

@@ -203,7 +203,33 @@ async function useConfig(name) {
     if (!fs.existsSync(globalClaudeDir)) {
         fs.mkdirSync(globalClaudeDir, { recursive: true });
     }
-    fs.writeFileSync(path.join(globalClaudeDir, 'settings.json'), content);
+    const settingsFilePath = path.join(globalClaudeDir, 'settings.json');
+    const settings = JSON.parse(content);
+    // 检查 ANTHROPIC_AUTH_TOKEN，为空时强制输入，有值时可选修改
+    if (settings?.env?.ANTHROPIC_AUTH_TOKEN !== undefined) {
+        const currentToken = settings.env.ANTHROPIC_AUTH_TOKEN;
+        if (!currentToken) {
+            console.log((0, colors_1.warn)('配置中 ANTHROPIC_AUTH_TOKEN 为空，需要设置 API Key 才能正常使用。'));
+            const apiKey = await (0, prompts_1.input)({
+                message: '请输入 API Key:',
+                validate: (v) => v.trim().length > 0 || '不能为空',
+            });
+            settings.env.ANTHROPIC_AUTH_TOKEN = apiKey.trim();
+            content = JSON.stringify(settings, null, 2);
+        }
+        else {
+            const masked = currentToken.slice(0, 8) + '****' + currentToken.slice(-4);
+            const newKey = await (0, prompts_1.input)({
+                message: `API Key (当前: ${masked}，直接回车保留，输入新值则替换):`,
+            });
+            if (newKey.trim()) {
+                settings.env.ANTHROPIC_AUTH_TOKEN = newKey.trim();
+                content = JSON.stringify(settings, null, 2);
+                console.log((0, colors_1.ok)('API Key 已更新'));
+            }
+        }
+    }
+    fs.writeFileSync(settingsFilePath, content);
     console.log((0, colors_1.ok)(`已应用配置 "${chosen}" → ~/.claude/settings.json`));
     // 检查并处理 config.json
     const configPath = path.join(globalClaudeDir, 'config.json');

package/dist/cli/init.js

@@ -52,7 +52,7 @@ async function cmdInit() {
     fs.mkdirSync(path.join(claudeDir, 'hooks'), { recursive: true });
     fs.mkdirSync(path.join(claudeDir, 'skills'), { recursive: true });
     (0, utils_1.copyHooks)(claudeDir);
-    (0, utils_1.copyBuiltinSkills)('universal', claudeDir);
+    (0, utils_1.copyBuiltinSkills)(claudeDir);
     (0, utils_1.copyTemplateDir)('commands', claudeDir);
     (0, utils_1.copyTemplateDir)('agents', claudeDir);
     (0, utils_1.copyTemplateDir)('templates', claudeDir);

package/dist/utils.js

@@ -43,7 +43,7 @@ exports.writeRc = writeRc;
 exports.installPackFromDir = installPackFromDir;
 exports.installSkillsFromDir = installSkillsFromDir;
 exports.copyBuiltinSkills = copyBuiltinSkills;
-exports.removeNonUniversalSkills = removeNonUniversalSkills;
+exports.removePackSkills = removePackSkills;
 exports.copyDir = copyDir;
 exports.copyHooks = copyHooks;
 exports.copyTemplateDir = copyTemplateDir;
@@ -121,7 +121,7 @@ function writeRc(patch) {
  */
 function installPackFromDir(packDir, packName, claudeDir) {
     // 删除旧 pack 的 skills
-    removeNonUniversalSkills(claudeDir);
+    removePackSkills(claudeDir);
     // 安装新 pack 的 skills
     installSkillsFromDir(packDir, packName, claudeDir);
     // 覆盖 commands / agents / hooks / templates
@@ -135,7 +135,7 @@ function installPackFromDir(packDir, packName, claudeDir) {
     }
 }
 // ─── skills ───────────────────────────────────────────────────────────────────
-/** 将 pack/skills/ 平铺复制到 .claude/skills/（universal 不加前缀） */
+/** 将 pack/skills/ 平铺复制到 .claude/skills/（带 packName 前缀） */
 function installSkillsFromDir(packDir, packName, claudeDir) {
     const skillsSrc = path.join(packDir, 'skills');
     if (!fs.existsSync(skillsSrc)) {
@@ -147,14 +147,14 @@ function installSkillsFromDir(packDir, packName, claudeDir) {
     for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
         if (!entry.isDirectory())
             continue;
-        const destName = packName === 'universal' ? entry.name : `${packName}-${entry.name}`;
-        copyDir(path.join(skillsSrc, entry.name), path.join(skillsDest, destName));
+        copyDir(path.join(skillsSrc, entry.name), path.join(skillsDest, `${packName}-${entry.name}`));
     }
 }
-function copyBuiltinSkills(packName, claudeDir) {
-    const src = path.join(exports.PKG_ROOT, 'src/templates/skills', packName);
+/** 复制内置 skills（templates/skills/ 下的所有子目录）到 .claude/skills/ */
+function copyBuiltinSkills(claudeDir) {
+    const src = path.join(exports.PKG_ROOT, 'src/templates/skills');
     if (!fs.existsSync(src)) {
-        console.warn(`内置规范包 "${packName}" 不存在。`);
+        console.warn('内置技能目录不存在。');
         return;
     }
     const skillsDest = path.join(claudeDir, 'skills');
@@ -162,12 +162,11 @@ function copyBuiltinSkills(packName, claudeDir) {
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
         if (!entry.isDirectory())
             continue;
-        const destName = packName === 'universal' ? entry.name : `${packName}-${entry.name}`;
-        copyDir(path.join(src, entry.name), path.join(skillsDest, destName));
+        copyDir(path.join(src, entry.name), path.join(skillsDest, entry.name));
     }
 }
-/** 删除所有非 universal 的 skills（即带 - 前缀的） */
-function removeNonUniversalSkills(claudeDir) {
+/** 删除所有 pack 安装的 skills（即带 - 前缀的） */
+function removePackSkills(claudeDir) {
     const skillsDir = path.join(claudeDir, 'skills');
     if (!fs.existsSync(skillsDir))
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airail",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "AI coding assistant framework - enforce coding standards via Claude hooks & skills",
   "bin": {
     "airail": "./bin/airail.js"

package/src/templates/agents/bugfix-verify.md

@@ -1,6 +1,6 @@
 ---
 name: bugfix-verify
-description: Bug 修复质量验证者。独立评估修复质量，只读代码库，不做任何修改。由 /bugfix 命令调用。
+description: Read-only bug fix quality verifier. Use proactively after bugfix agent completes a fix to independently evaluate fix quality. Also use when user says "验证修复", "检查修复质量".
 tools: Read, Grep, Glob
 ---
 

package/src/templates/agents/bugfix.md

@@ -1,6 +1,6 @@
 ---
 name: bugfix
-description: Bug 修复执行者，分析根本原因并实现修复。由 /bugfix 命令调用，或用户说"修复bug"、"fix bug"时触发。
+description: Bug fix specialist that analyzes root causes and implements fixes. Use when encountering bugs, errors, test failures, or when user says "修复bug", "fix bug", "修复问题".
 tools: Read, Edit, Write, Bash, Grep, Glob
 ---
 

package/src/templates/agents/code-reviewer.md

@@ -1,16 +1,22 @@
 ---
 name: code-reviewer
-description: 自动代码审查助手，在完成功能开发后自动检查代码是否符合项目规范。当使用 /dev 命令完成代码生成后，或用户说"审查代码"、"检查代码"时自动调用。
+description: Expert code review specialist. Use proactively after writing or modifying code, especially after /dev completes. Also use when user says "审查代码", "检查代码", or "review".
 model: opus
 tools: Read, Grep, Glob
 ---
 
 # 代码审查专家
 
-## 角色定位
-
 你是一位严格的代码审查专家，熟悉本项目的所有规范。你的职责是在代码合并前发现问题，而不是帮助实现功能。
 
+## 执行工作流
+
+当被调用时，按以下步骤执行：
+
+1. **查看最近变更** - 运行 `git diff` 查看最近修改的文件
+2. **聚焦修改文件** - 只审查新增或修改的文件
+3. **立即开始审查** - 不需要等待，直接分析代码
+
 ## 核心职责
 
 在以下场景自动执行代码审查：

package/src/templates/agents/debug.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: 系统化调试协调器，通过多维度分析和验证方法进行问题诊断和修复
+description: Systematic debugging coordinator for multi-dimensional problem diagnosis and resolution. Use when encountering complex issues requiring structured analysis, or when user says "调试", "debug", "排查问题".
 tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, TodoWrite
 ---
 

package/src/templates/agents/optimize.md

@@ -1,6 +1,6 @@
 ---
 name: optimize
-description: 性能优化协调员，领导优化专家团队进行系统性能改进。由 /optimize 命令调用，或用户说"性能优化"、"优化性能"时触发。
+description: Performance optimization coordinator for systematic performance improvement. Use when user says "性能优化", "优化性能", "optimize", or when performance bottlenecks are identified.
 tools: Read, Edit, Write, Bash, Grep, Glob
 ---
 

package/src/templates/agents/refactor.md

@@ -1,6 +1,6 @@
 ---
 name: refactor
-description: 重构协调员，领导重构专家团队改善代码质量和架构。由 /refactor 命令调用，或用户说"重构代码"、"代码重构"时触发。
+description: Refactoring coordinator for improving code quality and architecture. Use when user says "重构代码", "代码重构", "refactor", or when code smells and technical debt are identified.
 tools: Read, Edit, Write, Bash, Grep, Glob
 ---
 

package/src/templates/commands/bugfix.md

@@ -27,10 +27,11 @@
 
 ### 2️⃣ 修复执行（bugfix agent）
 
-调用 bugfix agent，传入：
-- Bug 描述：$ARGUMENTS
-- 收集到的上下文信息
-- 上轮验证反馈（迭代时）
+使用 Agent 工具委托 `bugfix` agent：
+
+```
+Agent(subagent_type="bugfix", prompt="修复以下 bug：<bug描述>。上下文信息：<收集到的信息>。[迭代时]上轮验证反馈：<反馈内容>")
+```
 
 期望输出：
 - 根本原因分析
@@ -41,10 +42,11 @@
 
 ### 3️⃣ 质量验证（bugfix-verify agent）
 
-调用 bugfix-verify agent，传入：
-- 修复后的代码
-- 原始 bug 描述
-- bugfix agent 的输出
+使用 Agent 工具委托 `bugfix-verify` agent：
+
+```
+Agent(subagent_type="bugfix-verify", prompt="验证以下 bug 修复的质量。原始 bug：<bug描述>。修复方案：<bugfix agent 输出>。修复后的代码：<变更文件列表>")
+```
 
 期望输出：
 - 总体评估（通过/有条件通过/需要改进/失败）

package/src/templates/commands/debug.md

@@ -16,11 +16,20 @@
    - 记录关键假设和未知因素
    - 生成 5-7 个可能的问题来源
 
-2. **多维度调研**：
+2. **多维度调研（debug agent）**：
+
+使用 Agent 工具委托 `debug` agent：
+
+```
+Agent(subagent_type="debug", prompt="调试以下问题：<问题描述>。复现步骤：<步骤>。相关日志：<日志信息>")
+```
+
+期望输出：
    - 架构层面：分析系统设计和模块交互
    - 代码层面：检查相关代码逻辑和数据流
    - 环境层面：检查配置、依赖和运行环境
    - 历史层面：查看相关代码变更历史
+   - 综合分析：精炼为 1-2 个最可能的原因
 
 3. **假设验证**：
    - 整合所有分析结果

package/src/templates/commands/dev-frontend.md

@@ -19,7 +19,8 @@
    - 支持格式：Swagger/OpenAPI、Apifox、手写文档、接口截图
 4. **方案设计**：列出要创建/修改的文件清单（组件、页面、路由、状态），等待确认
 5. **代码生成**：逐层实现（技能会根据开发内容自动激活）
-6. **完成报告**：列出所有变更文件，提示测试和联调事项
+6. **代码审查**：代码生成完成后，使用 Agent 工具委托 `code-reviewer` agent 对所有变更文件进行审查
+7. **完成报告**：列出所有变更文件，提示测试和联调事项
 
 ## AI 执行规则
 
@@ -33,6 +34,16 @@
 - 遵循项目的状态管理方案（Vuex/Pinia/Redux 等）
 - 禁止修改框架核心代码和公共组件库
 
+## Agent 委托
+
+代码生成完成后，**必须**调用 Agent 工具，按以下方式委托审查：
+
+```
+Agent(subagent_type="code-reviewer", prompt="审查以下前端变更文件：<变更文件列表>。检查是否符合项目规范，是否有安全漏洞、代码重复、性能问题等。")
+```
+
+审查未通过的问题需在当前流程中修复后，再输出完成报告。
+
 ## 技能自动激活说明
 
 开发过程中，AI 会根据触发词自动激活相关技能：

package/src/templates/commands/dev.md

@@ -14,7 +14,8 @@
 3. **数据库分析**：检查是否需要新建表或修改现有表
 4. **方案设计**：列出要创建/修改的文件清单，等待确认
 5. **代码生成**：逐层实现（技能会根据开发内容自动激活）
-6. **完成报告**：列出所有变更文件，提示下一步操作
+6. **代码审查**：代码生成完成后，使用 Agent 工具委托 `code-reviewer` agent 对所有变更文件进行审查
+7. **完成报告**：列出所有变更文件，提示下一步操作
 
 ## AI 执行规则
 
@@ -26,6 +27,16 @@
 - 优先复用项目中已有的工具类和组件
 - 禁止修改框架核心代码
 
+## Agent 委托
+
+代码生成完成后，**必须**调用 Agent 工具，按以下方式委托审查：
+
+```
+Agent(subagent_type="code-reviewer", prompt="审查以下变更文件：<变更文件列表>。检查是否符合项目规范，是否有安全漏洞、代码重复等问题。")
+```
+
+审查未通过的问题需在当前流程中修复后，再输出完成报告。
+
 ## 技能自动激活说明
 
 开发过程中，AI 会根据触发词自动激活相关技能：

package/src/templates/commands/gen-pytest.md

@@ -0,0 +1,147 @@
+# /gen-pytest - 根据测试用例文档生成 pytest 代码
+
+根据测试用例文档（由 `/gen-testcase` 生成或手动编写）生成模块化的 pytest 测试代码，每个测试函数与用例编号一一对应。
+
+## 使用方法
+
+```bash
+/gen-pytest <测试用例文档路径>
+```
+
+## 执行流程
+
+### 0. 读取测试用例文档
+
+- 解析测试用例文档，提取所有用例（编号、步骤、预期结果、测试数据、pytest 编写提示）
+- 定位关联代码，理解被测模块的接口和依赖
+- 识别项目已有的测试基础设施（conftest.py、fixture、工具函数）
+
+### 1. 规划测试结构
+
+根据用例文档的模块和场景划分，规划 pytest 文件结构：
+
+```
+tests/
+└── test_<模块名>/
+    ├── conftest.py              # 模块级 fixture 和共享工具
+    ├── test_<场景1>.py          # 对应文档中的 "1. 场景名称"
+    ├── test_<场景2>.py          # 对应文档中的 "2. 场景名称"
+    └── ...
+```
+
+每个场景一个测试文件，文件内的测试函数与用例编号对应。列出文件清单，等待用户确认。
+
+### 2. 生成 conftest.py
+
+分析所有用例的前置条件和共享依赖，提取公共部分：
+
+- 数据库连接、测试客户端等共享 fixture
+- 测试数据工厂函数
+- 通用的 mock 对象和辅助函数
+- setup/teardown 逻辑（数据清理、状态重置）
+
+### 3. 逐场景生成测试文件
+
+对每个场景文件，按用例编号生成对应的测试函数：
+
+```python
+"""
+测试场景：[场景名称]
+对应测试用例文档：[文档路径]
+"""
+import pytest
+
+
+class Test场景名称:
+    """对应文档：1. [场景名称]"""
+
+    def test_tc_mod_001_用例描述(self, fixture1, fixture2):
+        """
+        用例编号：TC-MOD-001
+        优先级：P0
+        验证：[预期结果概述]
+        """
+        # Arrange - 准备测试数据
+        ...
+
+        # Act - 执行被测操作
+        ...
+
+        # Assert - 验证结果
+        ...
+
+    @pytest.mark.parametrize("input_val,expected", [
+        ("正常值", "预期结果"),
+        ("边界值", "预期结果"),
+        ("异常值", "预期结果"),
+    ])
+    def test_tc_mod_002_多数据验证(self, input_val, expected):
+        """
+        用例编号：TC-MOD-002
+        优先级：P1
+        验证：[预期结果概述]
+        """
+        ...
+```
+
+### 4. 标记与分组
+
+根据用例优先级添加 pytest mark，方便按优先级运行：
+
+```python
+@pytest.mark.p0
+def test_tc_auth_001_核心登录流程(self):
+    ...
+
+@pytest.mark.p2
+def test_tc_auth_010_特殊字符用户名(self):
+    ...
+```
+
+在 `conftest.py` 或 `pyproject.toml` 中注册自定义 mark：
+
+```python
+# conftest.py
+def pytest_configure(config):
+    config.addinivalue_line("markers", "p0: 必测 - 核心业务流程")
+    config.addinivalue_line("markers", "p1: 重要 - 主要功能路径")
+    config.addinivalue_line("markers", "p2: 补充 - 边界条件和兼容性")
+```
+
+### 5. 验证与输出
+
+- 检查生成的代码语法是否正确
+- 确认每个用例编号都有对应的测试函数
+- 输出用例覆盖对照表
+
+## 用例对照表格式
+
+生成完成后输出对照表，确认覆盖情况：
+
+```markdown
+| 用例编号 | 优先级 | 测试函数 | 所在文件 |
+|---------|--------|---------|---------|
+| TC-AUTH-001 | P0 | test_tc_auth_001_登录成功 | test_login.py |
+| TC-AUTH-002 | P1 | test_tc_auth_002_密码错误 | test_login.py |
+```
+
+## AI 执行规则
+
+- 生成前必须先列出文件结构，等待用户确认
+- 每个测试函数的 docstring 中标注用例编号和优先级，保持与文档的可追溯性
+- 测试函数命名格式：`test_tc_模块_编号_简述`，编号与用例文档严格一致
+- 测试数据来自用例文档中的"测试数据建议"，用 parametrize 组织多组数据
+- 公共逻辑提取到 conftest.py，测试文件之间不互相导入
+- 使用 Arrange-Act-Assert 模式组织测试函数内部结构
+- mock 外部依赖（数据库、第三方 API、文件系统），保证测试可独立运行
+- 如果项目已有 conftest.py，追加内容而非覆盖
+
+## 示例
+
+```bash
+# 从 gen-testcase 生成的文档创建 pytest
+/gen-pytest docs/testcases/用户认证模块测试用例.md
+
+# 指定手写的测试用例文档
+/gen-pytest requirements/test-cases/payment.md
+```

package/src/templates/commands/gen-testcase.md

@@ -0,0 +1,128 @@
+# /gen-testcase - 生成测试用例文档
+
+为软件测试人员生成结构化的测试用例文档。根据需求文档和/或代码功能，自动分析并输出完整的测试用例，供 QA 测试人员参考编写 pytest 自动化测试脚本。
+
+## 使用方法
+
+```bash
+/gen-testcase <模块名或文件路径>
+```
+
+## 执行流程
+
+### 0. 信息收集
+
+- 定位用户指定的模块或文件，阅读代码理解功能
+- 询问用户是否有相关的需求文档，如有则一并阅读
+- 追踪调用链，理解上下游依赖
+
+### 1. 需求与代码分析
+
+**有需求文档时：**
+- 从需求文档提取功能点、业务规则和验收标准
+- 将需求描述和代码实现交叉比对，识别差异和遗漏
+
+**只有代码时：**
+- 分析函数签名、参数校验、返回值、异常处理
+- 从代码注释、变量命名和业务逻辑中推断需求意图
+
+### 2. 确定测试范围
+
+根据代码特征判断需要的测试类型，只选择相关的类型：
+
+| 代码特征 | 建议的测试类型 |
+|---------|-------------|
+| API 接口 / 路由 | 接口测试（参数、响应、状态码、鉴权） |
+| 表单 / 用户输入 | 输入验证测试（边界值、非法输入、XSS） |
+| 数据库操作 | 数据持久化测试（CRUD、事务、并发） |
+| 业务流程 / 状态机 | 流程测试（正常流、异常流、状态转换） |
+| 文件处理 | 文件测试（格式兼容、大文件、编码） |
+| 权限控制 | 权限测试（越权访问、角色切换） |
+| 第三方集成 | 集成测试（超时、重试、降级） |
+| 纯计算逻辑 | 功能测试（正常值、边界值、异常值） |
+
+列出测试范围，等待用户确认后再生成。
+
+### 3. 生成测试用例文档
+
+按以下结构输出：
+
+```markdown
+# [模块名] 测试用例文档
+
+## 概述
+- **测试目标**：要测试什么
+- **关联代码**：涉及的关键文件/类/函数
+- **关联需求**：（如有）需求文档名称或编号
+- **测试类型**：本文档覆盖的测试类型
+
+---
+
+## 1. [功能场景名称]
+
+### 1.1 [具体测试点]
+
+**用例编号**：TC-模块缩写-001
+**优先级**：P0 / P1 / P2
+**前置条件**：
+- 条件 1
+- 条件 2
+
+**测试步骤**：
+1. 步骤描述
+2. 步骤描述
+
+**预期结果**：
+- 结果 1
+- 结果 2
+
+**测试数据建议**：
+- 正常值：`示例数据`
+- 边界值：`示例数据`
+- 异常值：`示例数据`
+
+**pytest 编写提示**：
+> 建议的 fixture、mock 对象、assert 断言点等。
+```
+
+### 4. 质量自检
+
+- 正常流程和主要异常场景是否都有用例
+- 测试步骤是否足够具体，能直接执行
+- 预期结果是否明确，不会引起歧义
+- 每个测试点是否有具体的测试数据
+- P0 用例是否确实是最关键的场景
+
+### 5. 输出文档
+
+将测试用例文档保存到用户指定位置（默认为项目根目录下的 `docs/testcases/` 目录）。
+
+## AI 执行规则
+
+- 生成前必须先列出测试范围，等待用户确认
+- 测试用例的目标读者是 QA 测试人员，语言要直白、步骤要可执行
+- 不要把所有边界情况堆到一个用例里，拆分成独立用例
+- 给出具体的测试数据示例，不要写"输入异常数据"这样模糊的描述
+- 如果代码中发现潜在 bug 或设计问题，在文档中标注出来
+- 同一功能的相关用例放在一起，方便按场景批量执行
+
+## 优先级定义
+
+- **P0（必测）**：核心业务流程、数据安全、资金相关
+- **P1（重要）**：主要功能路径、常见异常场景
+- **P2（补充）**：边界条件、兼容性、性能基准
+
+## 用例编号规则
+
+格式：`TC-{模块缩写}-{三位数字}`
+示例：`TC-AUTH-001`（认证模块）、`TC-PAY-012`（支付模块）
+
+## pytest 编写提示规范
+
+每个用例附带给测试人员的实操建议：
+- 建议使用的 pytest 特性（fixture、parametrize、mark 等）
+- 需要 mock 的外部依赖
+- 关键的 assert 断言点
+- 测试隔离注意事项（数据库清理、状态重置）
+
+保持简洁，提供方向而非完整代码。

package/src/templates/commands/optimize.md

@@ -28,10 +28,11 @@
 
 ### 2️⃣ 瓶颈分析（optimize agent）
 
-调用 optimize agent，传入：
-- 性能目标：$ARGUMENTS
-- 收集到的性能数据
-- 相关代码文件
+使用 Agent 工具委托 `optimize` agent：
+
+```
+Agent(subagent_type="optimize", prompt="分析以下性能问题：<性能目标>。当前性能数据：<收集到的性能数据>。相关代码文件：<文件列表>")
+```
 
 期望输出：
 - 性能基线报告

package/src/templates/commands/refactor.md

@@ -29,11 +29,11 @@
 
 ### 2️⃣ 重构策略设计（refactor agent）
 
-调用 refactor agent，传入：
-- 重构目标：$ARGUMENTS
-- 目标代码文件
-- 现有测试覆盖情况
-- 依赖关系分析
+使用 Agent 工具委托 `refactor` agent：
+
+```
+Agent(subagent_type="refactor", prompt="分析以下代码的重构需求：<重构目标>。目标代码文件：<文件列表>。测试覆盖情况：<测试信息>。依赖关系：<依赖分析>")
+```
 
 期望输出：
 - 当前状态分析（四位专家视角）

package/src/templates/skills/skill-add/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: add-skill
+name: skill-add
 description: |
   当需要为框架增加新技能、为新的模块功能编写技能文档时自动使用此 Skill。
 

package/src/templates/agents/project-manager.md

@@ -1,45 +0,0 @@
----
-name: project-manager
-description: 项目管理助手，负责跟踪项目进度、管理待办事项、生成进度报告。当用户需要了解项目状态、规划下一步工作时调用。
----
-
-# 项目管理助手
-
-## 角色定位
-
-你是项目管理助手，专注于跟踪进度和规划任务，不参与具体代码实现。
-
-## 核心职责
-
-1. **进度跟踪**：读取 `.claude/templates/项目状态.md`，分析当前完成情况
-2. **任务规划**：根据待办清单和代码现状，给出优先级建议
-3. **风险识别**：发现可能阻塞进度的问题，提前预警
-
-## 常用操作
-
-### 查看项目状态
-
-读取以下文件综合分析：
-- `.claude/templates/项目状态.md`
-- `.claude/templates/待办清单.md`
-- 项目目录结构（判断各模块完成度）
-
-### 更新进度
-
-当用户完成某个功能后：
-1. 在待办清单中标记对应任务为完成
-2. 更新项目状态文档的完成度
-3. 追加变更记录
-
-### 规划下一步
-
-根据以下因素给出建议：
-- 未完成的高优先级任务
-- 当前阻塞项
-- 模块间的依赖关系
-
-## 输出风格
-
-- 简洁直接，用数字和百分比量化进度
-- 高优先级问题用 🔴 标注
-- 已完成用 ✅，进行中用 🔄，待开始用 ⬜

package/src/templates/skills/code-quality/SKILL.md

@@ -1,39 +0,0 @@
----
-name: code-quality
-description: |
-  通用代码质量规范，DRY/KISS/命名规范。
-
-  触发场景：
-  - 代码质量检查和改进
-  - 代码重构和优化
-  - 命名规范检查
-  - DRY 原则应用
-  - 重复代码消除
-
-  触发词：代码质量、重构、命名、DRY、重复代码、KISS、YAGNI、代码规范、代码优化、命名规范
----
-
-# 代码质量规范
-
-## 核心原则
-
-**KISS**：能简单就不复杂，三行能解决的不写十行。
-
-**DRY**：发现重复代码立即提取，零容忍 copy-paste。
-
-**YAGNI**：不为假设的未来需求写代码，只解决当前问题。
-
-## 命名规范
-
-- 变量/函数：描述"做什么"，不描述"怎么做"
-- 布尔值：用 `is/has/can/should` 前缀
-- 函数：动词开头（`getUser`, `createOrder`, `validateInput`）
-- 常量：全大写下划线（`MAX_RETRY_COUNT`）
-
-## 禁止事项
-
-- 禁止魔法数字，提取为命名常量
-- 禁止注释掉的废弃代码，直接删除
-- 禁止无意义的注释（`// 循环遍历数组`）
-- 禁止超过 3 层的嵌套，提前 return 或提取函数
-- 函数超过 30 行考虑拆分

package/src/templates/skills/code-review/SKILL.md

@@ -1,30 +0,0 @@
----
-name: code-review
-description: 代码审查清单。触发场景：代码审查和检查、功能正确性验证、代码质量评审、安全性检查、性能审查。触发词：code review、代码审查、检查代码、review、代码检查、审查、质量检查、代码评审、CR
----
-
-# 代码审查清单
-
-## 功能正确性
-
-- [ ] 逻辑是否正确，边界条件是否处理
-- [ ] 错误路径是否有处理
-- [ ] 是否有遗漏的业务场景
-
-## 代码质量
-
-- [ ] 有无重复代码（DRY）
-- [ ] 命名是否清晰
-- [ ] 函数是否单一职责
-- [ ] 是否有不必要的复杂度
-
-## 安全
-
-- [ ] 用户输入是否验证
-- [ ] 是否有硬编码密钥
-- [ ] 权限控制是否正确
-
-## 性能
-
-- [ ] 是否有 N+1 查询
-- [ ] 大数据量是否有分页

package/src/templates/skills/development-workflow/SKILL.md

@@ -1,307 +0,0 @@
----
-name: development-workflow
-description: |
-  项目开发工作流和最佳实践。包含开发流程建议、编码最佳实践、技术选型建议。
-
-  触发场景：
-  - 询问开发流程和工作流
-  - 询问最佳实践和开发规范
-  - 询问如何组织开发工作
-  - 询问技术选型建议
-  - 询问命令使用顺序
-
-  触发词：开发流程、工作流、最佳实践、开发规范、如何开发、开发建议、技术选型、命令使用、开发顺序、项目管理
----
-
-# 项目开发工作流和最佳实践
-
-## 概述
-
-本技能提供项目开发的工作流建议、编码最佳实践和技术选型指导，帮助开发者高效、规范地完成项目开发。
-
----
-
-## 开发流程建议
-
-### 标准开发流程（6步法）
-
-1. **明确需求** → 使用 `/start` 快速了解项目
-   - 了解项目结构和技术栈
-   - 查看现有功能和代码组织
-   - 确认开发环境和依赖
-
-2. **检查规范** → 使用 `/check` 检查代码质量
-   - 检查现有代码规范
-   - 发现潜在问题
-   - 了解项目编码标准
-
-3. **分析进度** → 使用 `/progress` 了解完成情况
-   - 查看项目完成度
-   - 了解待办事项
-   - 评估工作量
-
-4. **开始开发** → 使用 `/dev` 或 `/crud` 快速生成代码
-   - 表已存在：使用 `/crud` 快速生成
-   - 从零开始：使用 `/dev` 完整开发
-   - 遵循项目规范和架构
-
-5. **添加待办** → 使用 `/add-todo` 跟踪任务
-   - 记录新发现的任务
-   - 标记优先级
-   - 设置截止日期
-
-6. **获取建议** → 使用 `/next` 确定下一步方向
-   - 分析当前状态
-   - 获取优先级建议
-   - 规划下一步工作
-
-### 定期维护流程
-
-- **每日**：使用 `/add-todo` 记录新任务
-- **每周**：使用 `/check` 检查代码质量
-- **每周**：使用 `/progress` 查看进度
-- **每周**：使用 `/sync` 生成综合报告
-- **每月**：使用 `/next` 规划下一阶段工作
-
----
-
-## 编码最佳实践
-
-### 1. 单一职责原则
-
-**原则**：每个模块、类、方法只负责一件事
-
-**实践**：
-- 业务层负责业务逻辑
-- 接口层负责请求处理和参数验证
-- 数据层负责数据访问
-- 工具类负责通用功能
-
-**反例**：
-```
-❌ Controller 中包含复杂的业务逻辑
-❌ Service 中直接操作 HTTP 请求
-❌ 一个方法做多件不相关的事
-```
-
-**正例**：
-```
-✅ Controller 只做参数验证和调用 Service
-✅ Service 专注业务逻辑
-✅ 每个方法职责清晰
-```
-
----
-
-### 2. 查询优化
-
-**原则**：规范构建查询条件，避免性能问题
-
-**实践**：
-- 使用规范的查询条件构建方式
-- 避免 N+1 查询问题
-- 合理使用索引
-- 分页查询大数据量
-
-**查询条件规范**：
-- 精确匹配：ID、状态、类型等
-- 模糊搜索：名称、标题、内容等
-- 范围查询：日期、金额等
-- 关联查询：使用 JOIN 而非多次查询
-
----
-
-### 3. 权限管理
-
-**原则**：所有公开接口必须有权限控制
-
-**实践**：
-- 所有接口添加权限注解
-- 按模块划分权限
-- 按操作类型划分权限（查看、新增、修改、删除）
-- 敏感操作增加二次验证
-
-**权限分类**：
-- 查看权限：list、query
-- 操作权限：add、edit、remove
-- 特殊权限：export、import、approve
-
----
-
-### 4. 注释完整
-
-**原则**：关键方法必须有完整注释
-
-**实践**：
-- 公开接口必须有注释
-- 复杂业务逻辑必须有注释
-- 工具方法必须有注释
-- 注释说明用途、参数、返回值
-
-**注释内容**：
-- 方法用途和功能
-- 参数说明（类型、含义、约束）
-- 返回值说明
-- 异常说明
-- 使用示例（如需要）
-
----
-
-### 5. 定期检查
-
-**原则**：每周至少一次运行代码检查和进度查看
-
-**实践**：
-- 每周运行 `/check` 检查代码质量
-- 每周运行 `/progress` 查看进度
-- 每周运行 `/sync` 生成综合报告
-- 及时修复发现的问题
-
-**检查内容**：
-- 代码规范问题
-- TODO/FIXME 标记
-- 代码重复
-- 性能问题
-- 安全问题
-
----
-
-## 技术选型建议
-
-### 场景 1：快速生成 CRUD
-
-**推荐方案**：`/crud` 命令
-
-**适用条件**：
-- 数据库表已存在
-- 只需标准 CRUD 功能
-- 无复杂业务逻辑
-
-**优势**：
-- 生成速度快
-- 代码规范统一
-- 减少重复工作
-
----
-
-### 场景 2：从零开发功能
-
-**推荐方案**：`/dev` 命令
-
-**适用条件**：
-- 表结构尚未设计
-- 需要完整的开发流程
-- 包含业务逻辑设计
-
-**优势**：
-- 包含表设计指导
-- 完整的开发流程
-- 考虑业务逻辑
-
----
-
-### 场景 3：代码规范检查
-
-**推荐方案**：`/check` 命令
-
-**适用条件**：
-- 开发完成后
-- 定期检查
-- 发现代码问题
-
-**优势**：
-- 及时发现问题
-- 统一代码规范
-- 提升代码质量
-
----
-
-### 场景 4：项目进度追踪
-
-**推荐方案**：`/progress` 命令
-
-**适用条件**：
-- 定期了解完成情况
-- 评估工作量
-- 规划下一步工作
-
-**优势**：
-- 清晰的进度展示
-- 待办事项统计
-- 完成率分析
-
----
-
-### 场景 5：全量同步
-
-**推荐方案**：`/sync` 命令
-
-**适用条件**：
-- 每周整理
-- 发现数据不一致
-- 生成综合报告
-
-**优势**：
-- 全量扫描
-- 综合分析
-- 生成报告
-
----
-
-## 常见问题
-
-### Q1：什么时候使用 /crud，什么时候使用 /dev？
-
-**A1**：
-- 表已存在 → 使用 `/crud`
-- 从零开始 → 使用 `/dev`
-- 只需标准 CRUD → 使用 `/crud`
-- 需要复杂业务逻辑 → 使用 `/dev`
-
----
-
-### Q2：如何保证代码质量？
-
-**A2**：
-1. 开发前：使用 `/check` 了解项目规范
-2. 开发中：遵循最佳实践
-3. 开发后：使用 `/check` 检查代码
-4. 定期：每周运行 `/check` 和 `/sync`
-
----
-
-### Q3：如何管理待办事项？
-
-**A3**：
-1. 发现任务：使用 `/add-todo` 立即记录
-2. 查看进度：使用 `/progress` 查看待办
-3. 获取建议：使用 `/next` 确定优先级
-4. 定期整理：每周清理已完成任务
-
----
-
-### Q4：如何规划下一步工作？
-
-**A4**：
-1. 使用 `/next` 获取建议
-2. 根据优先级排序
-3. 先处理高优先级任务
-4. 定期使用 `/progress` 查看进度
-
----
-
-## 注意事项
-
-1. **遵循项目规范**：每个项目可能有特定的规范，优先遵循项目规范
-2. **保持代码一致性**：与现有代码保持一致的风格
-3. **及时记录待办**：发现问题立即记录，避免遗忘
-4. **定期检查代码**：每周至少一次代码检查
-5. **持续学习改进**：根据项目经验不断优化工作流
-
----
-
-## 相关技能
-
-- 如果是后端开发规范 → 使用 backend-development 技能
-- 如果是数据库设计规范 → 使用 database-design 技能
-- 如果是 API 设计规范 → 使用 api-design 技能

package/src/templates/skills/error-handling/SKILL.md

@@ -1,43 +0,0 @@
----
-name: error-handling
-description: |
-  错误处理规范，异常捕获和错误传递。
-
-  触发场景：
-  - 错误处理和异常捕获
-  - Try-catch 块编写
-  - 错误信息传递
-  - 异常处理规范
-  - 错误恢复策略
-
-  触发词：错误处理、异常、try catch、error、异常捕获、错误传递、异常处理、错误恢复、throw、catch
----
-
-# 错误处理规范
-
-## 核心原则
-
-- 只在系统边界处理错误（HTTP 入口、外部 API 调用、文件 IO）
-- 内部函数抛出错误，不要吞掉
-- 错误信息要有上下文，不要只写 "error occurred"
-
-## 模式
-
-**不要吞掉错误：**
-```js
-// 错误
-try { ... } catch (e) {}
-
-// 正确
-try { ... } catch (e) { throw new Error(`Failed to process order ${id}: ${e.message}`); }
-```
-
-**区分可恢复和不可恢复错误：**
-- 可恢复（用户输入错误、网络超时）：返回错误响应
-- 不可恢复（数据库连接失败）：让程序崩溃，由进程管理器重启
-
-## 禁止事项
-
-- 禁止空 catch 块
-- 禁止对不可能发生的场景加错误处理（过度防御）
-- 禁止在日志中打印完整堆栈到生产环境

package/src/templates/skills/performance/SKILL.md

@@ -1,24 +0,0 @@
----
-name: performance
-description: 性能优化原则。触发场景：性能优化和改进、慢查询问题解决、数据库查询优化、缓存策略设计、N+1 查询问题。触发词：性能、慢查询、优化、N+1、性能优化、缓存、数据库优化、查询优化、性能问题、性能调优
----
-
-# 性能优化规范
-
-## 数据库
-
-- 查询必须走索引，避免全表扫描
-- 禁止 N+1 查询，用 JOIN 或批量查询
-- 分页查询必须有 LIMIT，禁止无限制查询
-
-## 缓存
-
-- 热点数据加缓存，设置合理 TTL
-- 缓存 key 要有命名空间，避免冲突
-- 写操作后主动失效相关缓存
-
-## 代码层面
-
-- 循环内禁止数据库查询
-- 大数据量用流式处理，不要一次性加载到内存
-- 先测量再优化，不要凭感觉优化

package/src/templates/skills/testing/SKILL.md

@@ -1,32 +0,0 @@
----
-name: testing
-description: 测试策略规范。触发场景：单元测试编写、测试策略设计、Mock 对象使用、测试用例设计、测试覆盖率提升。触发词：测试、单元测试、test、mock、测试用例、测试策略、TDD、测试覆盖、集成测试、测试框架
----
-
-# 测试规范
-
-## 测试原则
-
-- 测试行为，不测实现细节
-- 一个测试只验证一件事
-- 测试名称描述场景：`should return 404 when user not found`
-
-## 测试结构（AAA）
-
-```
-Arrange - 准备数据
-Act     - 执行操作
-Assert  - 验证结果
-```
-
-## 什么值得测试
-
-- 业务逻辑（核心价值）
-- 边界条件（空值、最大值、负数）
-- 错误路径
-
-## 禁止事项
-
-- 禁止测试框架本身的行为
-- 禁止在测试中使用真实数据库/网络（用 mock）
-- 禁止测试私有方法（通过公共接口测试）