@gong-ym/ai-spec-auto 0.2.3

package/.agents/skills/common/project-init/evals/evals.json

@@ -0,0 +1,16 @@
+{
+  "skill_name": "project-init",
+  "evals": [
+    {
+      "id": "project-init-output-1",
+      "prompt": "对一个前端仓库执行 project-init，要求生成 01/03/context 并补齐缺失规则。",
+      "files": [],
+      "expected_output": "输出应明确写入清单、技术栈识别结果和缺失规则补齐范围，不允许只分析不落盘。",
+      "assertions": [
+        "包含固定产物 01/03/context/PROJECT",
+        "说明缺失规则的生成条件",
+        "强调不能只分析、不落盘"
+      ]
+    }
+  ]
+}

package/.agents/skills/common/project-init/evals/train_queries.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "初始化当前项目规范，补 01、03 和缺失规则",
+    "should_trigger": true
+  },
+  {
+    "query": "根据项目自动生成自定义规则",
+    "should_trigger": true
+  },
+  {
+    "query": "给我新建一个技能",
+    "should_trigger": false
+  },
+  {
+    "query": "执行下一条 tasks.md 任务",
+    "should_trigger": false
+  }
+]

package/.agents/skills/common/project-init/evals/validation_queries.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "分析这个仓库的技术栈并刷新项目概述",
+    "should_trigger": true
+  },
+  {
+    "query": "把 04/05/06/07/09 按项目事实补齐",
+    "should_trigger": true
+  },
+  {
+    "query": "帮我做 UI 验收",
+    "should_trigger": false
+  },
+  {
+    "query": "归档当前变更",
+    "should_trigger": false
+  }
+]

package/.agents/skills/common/project-init/references/custom-rule-generation.md

@@ -0,0 +1,89 @@
+# 自定义规则生成要求
+
+仅对 `待生成列表` 中的规则执行本文件中的要求。每个规则都要基于仓库事实生成，不得照搬通用模板。
+
+## 04-组件规范.md
+
+必须覆盖：
+
+- 当前组件结构写法
+- 组件目录组织方式
+- 页面专属组件与通用组件的放置规则
+- Props / Emits / 回调 / 事件的现状约定
+- 拆分边界和不可违背的规则
+
+若项目当前没有独立组件目录，也要明确写清：
+
+- 当前不存在
+- 推荐落点
+- 后续新增约束
+
+## 05-API规范.md
+
+必须覆盖：
+
+- 接口目录和请求封装入口
+- API 与类型文件的推荐落点
+- 函数命名模式
+- 错误处理模式
+- 页面/组件禁止直接请求的约束（若项目已有这类惯例）
+
+若项目还没有统一 API 层，要写清：
+
+- 当前现状
+- 推荐落点
+- 后续统一约束
+
+## 06-路由规范.md
+
+必须覆盖：
+
+- 路由入口
+- 路由模块或文件路由组织方式
+- 页面目录与路由目录的对应关系
+- 懒加载要求
+- `meta` / 守卫现状与约束
+
+若项目当前没有路由骨架，要明确写清：
+
+- 当前不存在
+- 推荐骨架
+- 新增页面时的落点约束
+
+## 07-状态管理.md
+
+必须覆盖：
+
+- 当前状态库
+- store 目录与命名约定
+- 模块拆分方式
+- 在组件中使用 store 的方式
+- 持久化现状
+
+若项目没有全局状态目录，要明确写清：
+
+- 当前无全局状态层
+- 何时才需要新增
+- 推荐落点
+
+## 09-样式规范.md
+
+必须覆盖：
+
+- 当前样式方案
+- 主题变量或主题 token 的现状
+- 全局样式入口
+- scoped / CSS Modules / Tailwind / Less / Sass 的实际使用规则
+- 禁止硬编码颜色值或主题偏离的约束（若项目有主题体系）
+
+若项目暂无主题变量，也要写清：
+
+- 当前现状
+- 推荐入口
+- 后续新增样式时的基本约束
+
+## 通用约束
+
+- 每条规则都必须基于项目实际代码、目录和依赖归纳
+- 严禁照搬通用模板
+- “当前不存在” 也属于需要写清的现状

package/.agents/skills/common/project-init/references/deep-scan-rules.md

@@ -0,0 +1,67 @@
+# 待生成规则的深度扫描
+
+## 目标
+
+只对 `待生成列表 + 待刷新列表` 对应的能力域做深度扫描，避免全量重扫仓库。
+
+## 若待生成 `04-组件规范`
+
+- 扫描 `src/components/`、`src/views/*/components/`、`src/pages/*/components/`
+- 随机读取 2-3 个组件文件，确认：
+  - Vue：`<script setup>` / `lang="ts"` / `defineProps` / `defineEmits`
+  - React：函数组件 / Props 接口 / JSX/TSX
+- 归纳：
+  - 组件目录组织方式
+  - 页面专属组件与通用组件的边界
+  - 组件库使用方式
+
+## 若待生成 `05-API规范`
+
+- 扫描 `src/api/`、`src/services/`、`src/request/`
+- 读取 2-3 个接口文件或请求封装文件
+- 归纳：
+  - 请求库与统一封装入口
+  - 命名模式
+  - 类型落点
+  - 错误处理模式
+
+## 若待生成 `06-路由规范`
+
+- 扫描 `src/router/`、`src/routes/` 或文件路由目录
+- 读取现有路由配置
+- 归纳：
+  - 路由入口与模块拆分
+  - 懒加载写法
+  - `meta` 使用情况
+  - 导航守卫
+  - 页面目录与路由的映射关系
+
+## 若待生成 `07-状态管理`
+
+- 扫描 `src/store/`、`src/stores/`
+- 从 `package.json` 与现有代码确认状态库
+- 读取 2-3 个 store 文件
+- 归纳：
+  - 编写方式
+  - 命名约定
+  - 模块拆分方式
+  - 是否使用持久化
+
+## 若待生成 `09-样式规范`
+
+- 统计样式文件后缀分布
+- 检测 Vue SFC 的 `<style scoped>` / `module` / 无限定
+- 检测是否存在 `src/styles/` 或全局样式入口
+- 归纳：
+  - CSS 变量
+  - 主题 token
+  - 组件库主题覆盖
+  - Tailwind / Less / Sass 的实际使用规则
+- 检测：
+  - 硬编码颜色
+  - 主题变量使用倾向
+
+## 约束
+
+- 只扫描本轮需要生成或刷新的规则
+- 所有归纳必须基于样本文件，而不是目录名猜测

package/.agents/skills/common/project-init/references/output-contracts.md

@@ -0,0 +1,71 @@
+# 核心产物写入合同
+
+## 01-项目概述.md
+
+要求：
+
+- 项目定位一句话描述必须来自可确认事实
+- 技术栈表只写项目实际安装和实际使用的技术
+- TypeScript / JavaScript 分支必须按项目实际依赖区分
+- 私有包或公司内部包需单独标注用途
+- 不得把未经确认的业务背景写成既定事实
+
+## 03-项目结构.md
+
+要求：
+
+- 目录树必须反映 `src/` 下的实际目录
+- 每个目录用途需根据 2-3 个样本文件归纳，而不是猜测
+- 如果项目存在路由目录、页面组件目录、Mock 策略，写清对应放置规则
+- 所有示例文件扩展名必须跟仓库实际一致，不要写死 `.ts`
+
+## context/PROJECT.md
+
+只保留稳定项目上下文：
+
+- 项目定位
+- 技术栈摘要
+- 关键规范入口
+- 业务目标
+- 核心术语
+- 架构概览
+- 非目标
+
+填写要求：
+
+- `项目定位` 与 `01-项目概述.md` 保持一致
+- `技术栈摘要` 只写可确认事实
+- `业务目标 / 核心术语 / 非目标` 无法确认时明确写 `待补充`
+- 不把某次任务的默认假设、页面落点、登录方式等运行态信息写进来
+
+## openspec/project.md
+
+若项目存在 `openspec/`：
+
+- 若 `openspec/project.md` 已存在，只更新其中 `## 项目概述` 段落，使其与 `01-项目概述.md` 的项目定位一致
+- 若 `openspec/project.md` 缺失，可创建最小 `project.md`，至少包含：
+  - `# Project`
+  - `## 项目概述`
+  - 与 `01-项目概述.md` 一致的一句话定位
+- 不修改 `project.md` 中其他无关章节
+
+若不存在 `openspec/`，跳过此步骤。
+
+## 用户确认摘要
+
+真正写入前，向用户给出最小确认摘要，至少包含：
+
+1. 检测到的技术栈
+2. 检测到的目录结构
+3. `PROJECT.md` 中的项目定位和关键规范入口
+4. 若存在自定义规则待生成，逐项说明将补哪些规则
+5. 若存在 OpenSpec，同步到 `openspec/project.md` 的项目定位描述
+
+确认问题建议：
+
+> 以上信息是否准确？若无异议，我将写入 01/03、PROJECT，以及当前缺失的自定义规则。
+
+## 约束
+
+- 一旦用户确认，必须按 `本轮写入清单` 一次性完成全部写入
+- 不要只写 `01/03` 后提前结束

package/.agents/skills/common/project-init/references/repo-fact-gathering.md

@@ -0,0 +1,83 @@
+# 项目事实采集
+
+## 目标
+
+采集足够稳定的仓库事实，用于生成：
+
+- `01-项目概述.md`
+- `03-项目结构.md`
+- `context/PROJECT.md`
+- 按需自定义规则
+
+如果本 skill 所带的 `scripts/inspect-project.js` 可用，可先跑它收集一版摘要，再人工补读关键文件。
+
+## 1. 读取 `package.json`
+
+至少提取：
+
+- UI 框架：`react` / `vue` / `angular`
+- 类型系统：`typescript`
+- 构建工具：`vite` / `webpack` / `next` / `nuxt`
+- 路由：`react-router*` / `vue-router`
+- 状态管理：`zustand` / `pinia` / `redux` / `mobx`
+- 组件库：`antd` / `element-plus` / `@mui/*`
+- 样式方案：`tailwind` / `sass` / `less` / CSS Modules / scoped 线索
+- 请求方案：`axios` / `fetch` / 自有 request 封装
+- 常用工具：`ahooks` / `@vueuse/core` / `lodash*` / `dayjs`
+
+## 2. 检查后端标记文件
+
+若仓库同时存在后端工程标记文件，也要补读后端线索，用于完善 `01-项目概述.md` 和 `context/PROJECT.md`：
+
+- Java / JVM：`pom.xml`、`build.gradle`、`build.gradle.kts`
+- Python：`pyproject.toml`、`requirements.txt`、`setup.py`
+
+能确认时写清：
+
+- 是否为前后端混合仓库
+- 后端技术栈大类
+- 前后端目录的基本分工
+
+## 3. 读取 `README.md` 与已有项目说明
+
+只提取稳定背景：
+
+- 项目定位
+- 业务目标
+- 核心术语
+- 架构关键词
+- 明确的边界或非目标
+
+若仓库没有稳定说明，只保留已确认事实，不编造背景。
+
+## 4. 扫描 `src/` 或等价源码目录
+
+至少确认：
+
+- 顶层目录列表及用途推断
+- 入口文件，如 `main.ts`、`main.tsx`、`App.vue`、`App.tsx`
+- 页面目录模式，如 `views/`、`pages/`
+- 路由组织模式：文件路由 / 配置路由 / 当前无骨架
+
+## 5. 判定项目类型
+
+根据现状判断：
+
+- SPA
+- SSR / SSG
+- 微前端
+- 前后端混合仓库
+- 组件库 / 工具库
+- Monorepo
+
+## 6. 判定 TS / JS
+
+- 若 `package.json` 中存在 `typescript`
+- 则视为 TypeScript 项目
+- 否则按 JavaScript 项目处理
+
+## 约束
+
+- 只记录稳定事实
+- 不把任务期默认假设写成项目长期事实
+- 无法确认的内容必须明确标成“待补充”

package/.agents/skills/common/project-init/references/scope-resolution.md

@@ -0,0 +1,76 @@
+# 规则生成范围与写入清单
+
+## 目标
+
+在真正扫描项目之前，先确定本轮必须写入哪些文件，避免只做分析不落盘，或只写 `01/03` 就提前结束。
+
+## 固定写入
+
+以下产物每次 `project-init` 都要生成或刷新：
+
+- `.agents/rules/01-项目概述.md`
+- `.agents/rules/03-项目结构.md`
+- `context/PROJECT.md`
+
+## 条件写入
+
+### OpenSpec 项目说明
+
+- 若存在 `openspec/`，同步 `openspec/project.md`
+- 若不存在 `openspec/`，跳过，不强制创建 OpenSpec
+
+### 自定义规则
+
+以下规则只在“缺失”或“manifest 要求刷新”时进入本轮写入清单：
+
+| 编号 | 文件名 | 说明 |
+|------|--------|------|
+| 04 | `04-组件规范.md` | 组件结构、目录组织、编写约定 |
+| 05 | `05-API规范.md` | 接口目录、请求封装、命名、错误处理 |
+| 06 | `06-路由规范.md` | 路由配置、懒加载、守卫、目录结构 |
+| 07 | `07-状态管理.md` | Store 目录、模块划分、编写规范 |
+| 09 | `09-样式规范.md` | 样式方案、主题变量、全局样式 |
+
+## 判断逻辑
+
+### 第一步：看 manifest
+
+检查 `.ai-spec/manifest.json`：
+
+- 若存在 `local_preferences.project_init.custom_rules`
+- 则其中列出的规则进入 `待刷新列表`
+
+### 第二步：看规则文件是否缺失
+
+检查 `.agents/rules/`：
+
+- 若 `04/05/06/07/09` 中某项不存在
+- 则该项进入 `待生成列表`
+
+### 第三步：合并成本轮写入清单
+
+- 若某条规则同时出现在 `待刷新列表` 和 `待生成列表`
+- 按“生成或刷新”统一处理
+- 若文件已存在且不在 `待刷新列表`
+- 默认视为已落盘或已人工维护，不覆盖
+
+## 本轮写入清单模板
+
+执行前必须形成一份明确清单：
+
+- 固定写入：
+  - `.agents/rules/01-项目概述.md`
+  - `.agents/rules/03-项目结构.md`
+  - `context/PROJECT.md`
+- 条件写入：
+  - `openspec/project.md`（仅当 `openspec/` 存在）
+  - `待生成列表` 中缺失的 `04/05/06/07/09`
+  - `待刷新列表` 中需要按项目事实重写的 `04/05/06/07/09`
+
+后续执行必须以这份清单为准，逐项落盘，不得遗漏。
+
+## 约束
+
+- 只要 `待生成列表` 非空，只写 `01/03 + PROJECT` 视为未完成
+- 不允许把“后续再补 04/05/06/07/09”写进摘要后直接结束
+- 不允许只分析、不写文件

package/.agents/skills/common/project-init/scripts/inspect-project.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+function exists(root, relPath) {
+  return fs.existsSync(path.join(root, relPath));
+}
+
+function readJson(root, relPath) {
+  const target = path.join(root, relPath);
+  if (!fs.existsSync(target)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(target, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function listDir(root, relPath) {
+  const target = path.join(root, relPath);
+  if (!fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+    return [];
+  }
+  return fs.readdirSync(target).filter((name) => name !== '.DS_Store').sort();
+}
+
+function detectFrontendStack(packageJson) {
+  const allDeps = {
+    ...(packageJson?.dependencies || {}),
+    ...(packageJson?.devDependencies || {}),
+  };
+  const keys = Object.keys(allDeps);
+  const has = (name) => keys.some((key) => key === name || key.startsWith(`${name}/`));
+
+  return {
+    ui_framework: has('react') ? 'react' : has('vue') ? 'vue' : has('@angular/core') ? 'angular' : null,
+    typescript: has('typescript'),
+    build_tool: has('vite') ? 'vite' : has('next') ? 'next' : has('nuxt') ? 'nuxt' : has('webpack') ? 'webpack' : null,
+    routing: has('react-router') || has('react-router-dom') ? 'react-router' : has('vue-router') ? 'vue-router' : null,
+    state: has('zustand') ? 'zustand' : has('pinia') ? 'pinia' : has('@reduxjs/toolkit') || has('redux') ? 'redux' : has('mobx') ? 'mobx' : null,
+    ui_library: has('antd') ? 'antd' : has('element-plus') ? 'element-plus' : has('@mui/material') ? '@mui/material' : null,
+    style_signals: ['tailwindcss', 'sass', 'less'].filter((name) => has(name)),
+    http: has('axios') ? 'axios' : null,
+    utilities: keys.filter((key) => ['ahooks', '@vueuse/core', 'lodash', 'lodash-es', 'dayjs'].includes(key)),
+  };
+}
+
+function detectBackendMarkers(root) {
+  const javaMarkers = ['pom.xml', 'build.gradle', 'build.gradle.kts'].filter((name) => exists(root, name));
+  const pythonMarkers = ['pyproject.toml', 'requirements.txt', 'setup.py'].filter((name) => exists(root, name));
+  return {
+    java: javaMarkers,
+    python: pythonMarkers,
+  };
+}
+
+function detectRuleWriteSet(root, manifest) {
+  const customRules =
+    manifest?.local_preferences?.project_init?.custom_rules &&
+    Array.isArray(manifest.local_preferences.project_init.custom_rules)
+      ? manifest.local_preferences.project_init.custom_rules.map(String)
+      : [];
+  const candidates = ['04', '05', '06', '07', '09'];
+  const missing = [];
+  for (const code of candidates) {
+    const targetDir = path.join(root, '.agents', 'rules');
+    if (!fs.existsSync(targetDir)) continue;
+    const existing = fs.readdirSync(targetDir).some((name) => name.startsWith(`${code}-`));
+    if (!existing) {
+      missing.push(code);
+    }
+  }
+  return {
+    custom_rules: customRules,
+    missing_rules: missing,
+  };
+}
+
+function detectSourceLayout(root) {
+  const srcEntries = listDir(root, 'src');
+  const entryCandidates = ['src/main.ts', 'src/main.tsx', 'src/App.vue', 'src/App.tsx'].filter((relPath) => exists(root, relPath));
+  return {
+    src_entries: srcEntries,
+    entry_files: entryCandidates,
+    page_dirs: ['src/views', 'src/pages'].filter((relPath) => exists(root, relPath)),
+    route_dirs: ['src/router', 'src/routes'].filter((relPath) => exists(root, relPath)),
+    styles_dir: exists(root, 'src/styles'),
+    component_dirs: ['src/components'].filter((relPath) => exists(root, relPath)),
+    store_dirs: ['src/store', 'src/stores'].filter((relPath) => exists(root, relPath)),
+    api_dirs: ['src/api', 'src/services', 'src/request'].filter((relPath) => exists(root, relPath)),
+  };
+}
+
+function main() {
+  const targetRoot = path.resolve(process.argv[2] || process.cwd());
+  const packageJson = readJson(targetRoot, 'package.json');
+  const manifest = readJson(targetRoot, '.ai-spec/manifest.json');
+  const summary = {
+    root: targetRoot,
+    package_json: Boolean(packageJson),
+    openspec: exists(targetRoot, 'openspec'),
+    readme: exists(targetRoot, 'README.md'),
+    frontend_stack: detectFrontendStack(packageJson || {}),
+    backend_markers: detectBackendMarkers(targetRoot),
+    layout: detectSourceLayout(targetRoot),
+    rules: detectRuleWriteSet(targetRoot, manifest),
+  };
+
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+}
+
+main();