@gamehoo/vibe-spec 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamehoo/vibe-spec",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "跨项目通用 AI 编程规范管理工具",
   "type": "module",
   "bin": {

package/specs//346/217/220/344/272/244/350/247/204/350/214/203.md

@@ -1,33 +1,52 @@
+---
+description: 每次 git commit 时遵循此规范
+---
+
 # Git 提交规范
 
-基于 [Conventional Commits](https://www.conventionalcommits.org/) 规范，类型关键字使用英文，描述使用中文。
+类型关键字使用英文，描述使用中文。
 
 ## 格式
 
 ```
-<类型>(范围): 简短描述
+<类型>[可选的范围]: 简短描述
+
+[可选的正文]
 
-可选的详细说明
+[可选的脚注]
 ```
 
 - **类型**：必填，英文小写。
-- **范围**：可选，改动所属模块。改动范围明确时加，跨模块或杂务类可省略。
+- **范围**：可选，描述改动所属模块的名词，用圆括号包围。改动范围明确时加，跨模块或杂务类可省略。
+- **`!`**：可选，紧跟在类型/范围后、冒号前，表示包含破坏性变更。
 - **简短描述**：必填，中文，不超过 50 字，不加句号。
-- **详细说明**：可选，中文，用空行与标题分隔，解释"为什么"而非"做了什么"。
+- **正文**：可选，中文，用空行与简短描述分隔，解释"为什么"而非"做了什么"，可包含多个段落。
+- **脚注**：可选，用空行与正文分隔，每条脚注格式为 `令牌: 值` 或 `令牌 #值`，令牌中的空格用 `-` 替代。
 - **不添加** `Co-Authored-By` 等自动生成的尾部标记。
 
 ## 类型
 
 | 类型 | 用途 |
 |------|------|
-| `feat` | 新功能 |
-| `fix` | 修复 bug |
+| `feat` | 新功能（对应语义化版本 MINOR） |
+| `fix` | 修复 bug（对应语义化版本 PATCH） |
 | `refactor` | 重构（不改变外部行为） |
 | `docs` | 文档变更 |
 | `style` | 代码格式调整（不影响逻辑） |
-| `chore` | 构建、配置、依赖等杂务 |
-| `test` | 测试相关 |
 | `perf` | 性能优化 |
+| `test` | 测试相关 |
+| `build` | 构建系统或外部依赖变更 |
+| `ci` | 持续集成配置变更 |
+| `chore` | 其他杂务 |
+
+## 破坏性变更
+
+当提交包含破坏性变更时（对应语义化版本 MAJOR），必须通过以下方式之一标记：
+
+1. **在类型/范围后加 `!`**：`feat(api)!: 移除已废弃的用户列表接口`
+2. **在脚注中声明**：以 `BREAKING CHANGE: 描述` 开头（必须大写）
+
+两种方式可同时使用。使用 `!` 时，脚注中的 `BREAKING CHANGE` 可省略，但简短描述应说明破坏性内容。
 
 ## 示例
 
@@ -48,3 +67,11 @@ refactor(layout): 将面板尺寸逻辑抽取为 useResizable hook
 
 原先的 inline 计算散落在多个组件中，难以复用和测试。
 ```
+
+```
+feat(api)!: 重构认证模块为 OAuth2 流程
+
+旧的 session-based 认证方式不再支持。
+
+BREAKING CHANGE: /api/login 接口签名变更，客户端需迁移至 /api/oauth/authorize
+```

package/specs//346/226/207/346/241/243/350/247/204/350/214/203.md

@@ -1,18 +1,15 @@
-# 文档规范
+---
+description: 新建或维护 .docs/ 目录下的项目文档时参考
+---
 
-## 文档分类
+# 文档规范
 
-| 位置 | 用途 | 版本控制 |
-|------|------|----------|
-| `CLAUDE.md` | AI 协作指令：项目理念、开发规范、工作流程、工具、文档索引 | 入库 |
-| `CLAUDE.local.md` | 本机特有配置：个人路径、镜像地址、本地环境变量等 | 不入库 |
-| `.docs/` | 项目知识文档，按子目录分类（见下方） | 入库 |
+## 基本原则
 
-判断原则：
-- 只对当前机器有意义 → `CLAUDE.local.md`
-- 对所有开发者有意义、指导 AI 行为 → `CLAUDE.md`
-- 需要详细展开的项目知识 → `.docs/`，并在 `CLAUDE.md` 文档索引中建立链接
 - 可以从代码或 git 历史推断的信息不写文档
+- 新建文档前先确认是否可以合并到已有文档中
+- 不符合任何分类的内容不建文档
+- 单次性的调研、笔记不进 `.docs/`
 
 ## .docs/ 目录结构
 
@@ -24,9 +21,21 @@
 | `测试/` | 功能的手动测试用例，发布前全量回归 | 随功能新增或变更同步更新 | `<功能名>/<子项>.md` |
 | `产品/` | 需求和产品定义 | 每次新增，写完后基本不变 | `YYYY-MM-DD <主题>.md` |
 
-- 新建文档前先确认是否可以合并到已有文档中
-- 不符合任何分类的内容不建文档
-- 单次性的调研、笔记不进 `.docs/`
+## 文档索引
+
+项目应在 AI 指令文件（如 `CLAUDE.md`、`AGENTS.md`）中维护 `.docs/` 的文档索引，让 AI 知道有哪些文档、什么时候该看。
+
+- 新增 `.docs/` 文档后，必须在索引中添加条目
+- 每条索引包含链接和使用场景说明（告诉 AI 什么时候需要参考该文档）
+- 索引格式按子目录区分：
+
+| 子目录 | 索引格式 |
+|--------|----------|
+| `规范/` | `<主题>` — 使用场景 |
+| `概览/` | `<主题>` — 使用场景 |
+| `方案/` | `YYYY-MM-DD <主题>` — 方案概述 |
+| `测试/` | `<功能名>/` — 覆盖范围 |
+| `产品/` | `YYYY-MM-DD <主题>` — 产品概述 |
 
 ## 命名规范
 
@@ -66,7 +75,3 @@
 
 当信息有多个并列维度时（如"每种消息类型的来源"、"每个组件是内置还是自定义"），优先用表格，不要用段落罗列。
 
-## 维护原则
-
-- `CLAUDE.md` 保持精简，详细内容下沉到 `.docs/` 子文档
-- 新增 `.docs/` 文档后，必须在 `CLAUDE.md` 文档索引中添加条目，包含链接和使用场景说明（告诉 AI 什么时候需要参考该文档）

package/src/commands/clean.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { loadProjects, saveProjects } from '../projects.js'
+
+const START_MARKER = '<!-- vibe-spec:start -->'
+const END_MARKER = '<!-- vibe-spec:end -->'
+
+export async function clean() {
+  const cwd = process.cwd()
+  const rcPath = path.join(cwd, '.vibespecrc.json')
+
+  if (!fs.existsSync(rcPath)) {
+    console.log('当前项目未接入 vibe-spec，无需清理')
+    return
+  }
+
+  const rc = JSON.parse(fs.readFileSync(rcPath, 'utf-8'))
+  const specDir = path.join(cwd, rc.specDir)
+
+  // 删除同步过来的规范文件
+  const allNames = [...(rc.specs || []), ...(rc.workflows || [])]
+  for (const name of allNames) {
+    const file = path.join(specDir, `${name}.md`)
+    if (fs.existsSync(file)) {
+      fs.unlinkSync(file)
+      console.log(`✔ 已删除 ${rc.specDir}/${name}.md`)
+    }
+  }
+
+  // 如果规范目录为空则删除
+  if (fs.existsSync(specDir) && fs.readdirSync(specDir).length === 0) {
+    fs.rmdirSync(specDir)
+    console.log(`✔ 已删除空目录 ${rc.specDir}/`)
+  }
+
+  // 移除 CLAUDE.md 中的注入块
+  const claudePath = path.join(cwd, 'CLAUDE.md')
+  if (fs.existsSync(claudePath)) {
+    const content = fs.readFileSync(claudePath, 'utf-8')
+    const startIdx = content.indexOf(START_MARKER)
+    const endIdx = content.indexOf(END_MARKER)
+    if (startIdx !== -1 && endIdx !== -1) {
+      const before = content.slice(0, startIdx).replace(/\n+$/, '')
+      const after = content.slice(endIdx + END_MARKER.length).replace(/^\n+/, '')
+      const result = after ? before + '\n' + after : before
+      fs.writeFileSync(claudePath, result + '\n')
+      console.log('✔ 已移除 CLAUDE.md 中的 vibe-spec 注入块')
+    }
+  }
+
+  // 删除 .vibespecrc.json
+  fs.unlinkSync(rcPath)
+  console.log('✔ 已删除 .vibespecrc.json')
+
+  // 从全局项目列表中移除
+  const projects = loadProjects()
+  const abs = path.resolve(cwd)
+  const filtered = projects.filter((p) => p !== abs)
+  if (filtered.length < projects.length) {
+    saveProjects(filtered)
+    console.log('✔ 已从全局项目列表中移除')
+  }
+}

package/src/commands/init.js

@@ -46,16 +46,14 @@ export async function init() {
   }
 
   // 注入 CLAUDE.md
-  const specNames = selectedSpecs.map((s) => s.name)
-  const workflowNames = selectedWorkflows.map((w) => w.name)
-  const injection = buildInjection(specNames, workflowNames, SPEC_DIR)
+  const injection = buildInjection(selectedSpecs, selectedWorkflows, SPEC_DIR)
   injectIntoClaude(cwd, injection)
   console.log('✔ 已注入 CLAUDE.md [vibe-spec 区域]')
 
   // 创建 .vibespecrc.json
   const rc = {
-    specs: specNames,
-    workflows: workflowNames,
+    specs: selectedSpecs.map((s) => s.name),
+    workflows: selectedWorkflows.map((w) => w.name),
     specDir: SPEC_DIR,
     version: getPackageVersion(),
   }

package/src/commands/sync.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { SPECS_DIR, WORKFLOWS_DIR } from '../paths.js'
-import { getPackageVersion } from '../registry.js'
+import { getAvailableItems, getPackageVersion } from '../registry.js'
 import { loadProjects, saveProjects } from '../projects.js'
 import { buildInjection, injectIntoClaude } from '../inject.js'
 
@@ -44,8 +44,17 @@ async function syncProject(projectDir) {
     }
   }
 
-  // 注入 CLAUDE.md
-  const injection = buildInjection(rc.specs, rc.workflows, rc.specDir)
+  // 注入 CLAUDE.md（从源文件读取 description）
+  const available = getAvailableItems()
+  const specItems = rc.specs.map((name) => {
+    const found = available.specs.find((s) => s.name === name)
+    return { name, description: found?.description || '' }
+  })
+  const workflowItems = rc.workflows.map((name) => {
+    const found = available.workflows.find((w) => w.name === name)
+    return { name, description: found?.description || '' }
+  })
+  const injection = buildInjection(specItems, workflowItems, rc.specDir)
   injectIntoClaude(projectDir, injection)
 
   // 更新版本号

package/src/index.js

@@ -1,6 +1,7 @@
 import { init } from './commands/init.js'
 import { sync } from './commands/sync.js'
 import { list } from './commands/list.js'
+import { clean } from './commands/clean.js'
 
 const HELP = `
 vibe-spec — 跨项目通用 AI 编程规范管理工具
@@ -10,6 +11,7 @@ vibe-spec — 跨项目通用 AI 编程规范管理工具
   vibe-spec sync          同步当前项目到最新版本
   vibe-spec sync --all    一次性推送到所有已注册项目
   vibe-spec list          查看可用的规范、工作流和已注册项目
+  vibe-spec clean         移除当前项目的 vibe-spec 接入（删除规范文件、注入块和配置）
   vibe-spec --help        显示帮助信息
 `.trim()
 
@@ -27,6 +29,9 @@ export async function run(args) {
       case 'list':
         await list()
         break
+      case 'clean':
+        await clean()
+        break
       case '--help':
       case '-h':
       case undefined:

package/src/inject.js

@@ -6,25 +6,43 @@ const END_MARKER = '<!-- vibe-spec:end -->'
 
 /**
  * 根据选中的 specs 和 workflows 生成注入内容
+ * @param {Array<{name: string, description?: string}>} specs
+ * @param {Array<{name: string, description?: string}>} workflows
+ * @param {string} specDir
  */
-export function buildInjection(specNames, workflowNames, specDir) {
-  const lines = [START_MARKER, '## 开发规范', '']
+export function buildInjection(specs, workflows, specDir) {
+  const lines = [
+    START_MARKER,
+    '## 共享规范',
+    '',
+    '以下是跨项目共享的开发规范和工作流，通过 `vibe-spec sync` 命令同步更新。',
+    '',
+  ]
 
-  for (const name of specNames) {
-    lines.push(`- [${name}](./${specDir}/${name}.md)`)
+  if (specs.length > 0) {
+    lines.push('**开发规范：**')
+    for (const { name, description } of specs) {
+      lines.push(formatItem(name, description, specDir))
+    }
   }
 
-  if (workflowNames.length > 0) {
-    lines.push('', '## 工作流程', '')
-    for (const name of workflowNames) {
-      lines.push(`- [${name}](./${specDir}/${name}.md)`)
+  if (workflows.length > 0) {
+    if (specs.length > 0) lines.push('')
+    lines.push('**工作流程：**')
+    for (const { name, description } of workflows) {
+      lines.push(formatItem(name, description, specDir))
     }
   }
 
-  lines.push(END_MARKER)
+  lines.push('', END_MARKER)
   return lines.join('\n')
 }
 
+function formatItem(name, description, specDir) {
+  const link = `[${name}](./${specDir}/${name}.md)`
+  return description ? `- ${link} — ${description}` : `- ${link}`
+}
+
 /**
  * 将内容注入 CLAUDE.md 的标记区域
  * 如果标记不存在，追加到文件末尾

package/src/registry.js

@@ -10,12 +10,14 @@ export function getAvailableItems() {
     name: path.basename(file, '.md'),
     file: path.join(SPECS_DIR, file),
     type: 'spec',
+    description: parseFrontmatter(path.join(SPECS_DIR, file)).description || '',
   }))
 
   const workflows = readDir(WORKFLOWS_DIR).map((file) => ({
     name: path.basename(file, '.md'),
     file: path.join(WORKFLOWS_DIR, file),
     type: 'workflow',
+    description: parseFrontmatter(path.join(WORKFLOWS_DIR, file)).description || '',
   }))
 
   return { specs, workflows }
@@ -29,6 +31,24 @@ export function getPackageVersion() {
   return pkg.version
 }
 
+/**
+ * 解析 Markdown 文件的 YAML frontmatter
+ */
+function parseFrontmatter(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8')
+  const match = content.match(/^---\n([\s\S]*?)\n---/)
+  if (!match) return {}
+  const result = {}
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':')
+    if (idx === -1) continue
+    const key = line.slice(0, idx).trim()
+    const value = line.slice(idx + 1).trim()
+    result[key] = value
+  }
+  return result
+}
+
 function readDir(dir) {
   if (!fs.existsSync(dir)) return []
   return fs.readdirSync(dir).filter((f) => f.endsWith('.md'))

package/workflows//346/226/207/346/241/243/346/243/200/346/237/245.md

@@ -1,3 +1,7 @@
+---
+description: 阶段性回顾时执行，检查项目文档的索引完整性、格式合规和内容时效性
+---
+
 # 文档检查
 
 阶段性回顾时执行，检查项目文档的健康状态：