@gamehoo/vibe-spec 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# vibe-spec
+
+跨项目通用 AI 编程规范管理工具。
+
+把提交规范、文档规范、工作流程集中维护在一个地方，一条命令同步到所有项目。
+
+## 安装
+
+```bash
+npm install -g vibe-spec
+```
+
+## 快速开始
+
+```bash
+cd your-project
+vibe-spec init
+```
+
+默认全选所有规范，直接回车即可。项目中会生成：
+
+- `.docs/规范/` — 规范文件
+- `.vibespecrc.json` — 项目配置
+- `CLAUDE.md` 中插入规范引用区域
+
+## 命令
+
+### `vibe-spec init`
+
+在当前项目初始化，交互式选择要使用的规范和工作流。
+
+### `vibe-spec sync`
+
+将当前项目的规范同步到最新版本。
+
+### `vibe-spec sync --all`
+
+一次性同步所有已注册的项目。适合修改规范后批量推送。
+
+### `vibe-spec list`
+
+查看可用的规范、工作流和已注册的项目列表。
+
+## 内置规范
+
+| 名称 | 类型 | 说明 |
+|------|------|------|
+| 提交规范 | 规范 | 基于 Conventional Commits，类型英文 + 描述中文 |
+| 文档规范 | 规范 | CLAUDE.md / .docs/ 分类与写作规则 |
+| 文档检查 | 工作流 | 索引完整性、格式、时效性检查 |
+
+## 开发
+
+```bash
+git clone <repo>
+cd vibe-spec
+npm install
+npm link          # 全局 vibe-spec 指向本地仓库
+```
+
+`npm link` 后修改 `specs/` 下的文件立刻生效，`vibe-spec sync --all` 直接读取本地文件。

package/bin/vibe-spec.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js'
+
+run(process.argv.slice(2))

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@gamehoo/vibe-spec",
+  "version": "1.0.0",
+  "description": "跨项目通用 AI 编程规范管理工具",
+  "type": "module",
+  "bin": {
+    "vibe-spec": "./bin/vibe-spec.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "specs/",
+    "workflows/"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0"
+  }
+}

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

@@ -0,0 +1,50 @@
+# Git 提交规范
+
+基于 [Conventional Commits](https://www.conventionalcommits.org/) 规范，类型关键字使用英文，描述使用中文。
+
+## 格式
+
+```
+<类型>(范围): 简短描述
+
+可选的详细说明
+```
+
+- **类型**：必填，英文小写。
+- **范围**：可选，改动所属模块。改动范围明确时加，跨模块或杂务类可省略。
+- **简短描述**：必填，中文，不超过 50 字，不加句号。
+- **详细说明**：可选，中文，用空行与标题分隔，解释"为什么"而非"做了什么"。
+- **不添加** `Co-Authored-By` 等自动生成的尾部标记。
+
+## 类型
+
+| 类型 | 用途 |
+|------|------|
+| `feat` | 新功能 |
+| `fix` | 修复 bug |
+| `refactor` | 重构（不改变外部行为） |
+| `docs` | 文档变更 |
+| `style` | 代码格式调整（不影响逻辑） |
+| `chore` | 构建、配置、依赖等杂务 |
+| `test` | 测试相关 |
+| `perf` | 性能优化 |
+
+## 示例
+
+```
+feat(kanban): 添加任务拖拽排序
+```
+
+```
+fix(data): 修复任务删除后列排序错误
+```
+
+```
+chore: 升级 Electron 至 v33
+```
+
+```
+refactor(layout): 将面板尺寸逻辑抽取为 useResizable hook
+
+原先的 inline 计算散落在多个组件中，难以复用和测试。
+```

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

@@ -0,0 +1,72 @@
+# 文档规范
+
+## 文档分类
+
+| 位置 | 用途 | 版本控制 |
+|------|------|----------|
+| `CLAUDE.md` | AI 协作指令：项目理念、开发规范、工作流程、工具、文档索引 | 入库 |
+| `CLAUDE.local.md` | 本机特有配置：个人路径、镜像地址、本地环境变量等 | 不入库 |
+| `.docs/` | 项目知识文档，按子目录分类（见下方） | 入库 |
+
+判断原则：
+- 只对当前机器有意义 → `CLAUDE.local.md`
+- 对所有开发者有意义、指导 AI 行为 → `CLAUDE.md`
+- 需要详细展开的项目知识 → `.docs/`，并在 `CLAUDE.md` 文档索引中建立链接
+- 可以从代码或 git 历史推断的信息不写文档
+
+## .docs/ 目录结构
+
+| 子目录 | 用途 | 更新方式 | 命名规则 |
+|--------|------|----------|----------|
+| `规范/` | 开发约定，长期稳定 | 随项目迭代更新已有文档 | `<主题>.md` |
+| `概览/` | 复杂模块的抽象总结，帮助理解大局 | 随项目迭代更新已有文档 | `<主题>.md` |
+| `方案/` | 具体改动的技术方案，一事一文档 | 每次新增，写完后基本不变 | `YYYY-MM-DD <主题>.md` |
+| `测试/` | 功能的手动测试用例，发布前全量回归 | 随功能新增或变更同步更新 | `<功能名>/<子项>.md` |
+| `产品/` | 需求和产品定义 | 每次新增，写完后基本不变 | `YYYY-MM-DD <主题>.md` |
+
+- 新建文档前先确认是否可以合并到已有文档中
+- 不符合任何分类的内容不建文档
+- 单次性的调研、笔记不进 `.docs/`
+
+## 命名规范
+
+- 文档统一使用中文命名
+- 避免使用特殊字符，中文与英文、数字之间加空格
+
+## 内容格式
+
+- 语言：中文为主，专有名词保留英文原文（如 Electron、SQLite、Agent）
+
+## 方案文档写作要求
+
+方案文档（`.docs/方案/`）的读者可能不了解项目、不了解相关技术。写作时遵循两个原则：**容易理解**和**阅读高效**。
+
+### 渐进式展开
+
+文档按抽象层级组织，读者可以只看前面就理解全貌，按需深入细节：
+
+1. **摘要**（1 段话）— 做什么、怎么做、关键决策，30 秒读完
+2. **全局设计**（图 + 文字）— 架构、UI、数据流，不含代码，5 分钟读完
+3. **详细设计**（代码 + 配置）— 各模块的接口、类型、实现要点，按需查阅
+4. **验证与证据**（表格）— 可行性验证、SDK 映射等，仅在需要核查时阅读
+
+每一层都应该是自包含的——只读摘要就能决定是否继续读；只读全局设计就能参与讨论。
+
+### 术语处理
+
+- 技术术语在**首次出现**时用括号解释，例如：`IPC（进程间通信，Electron 中两个进程交换数据的方式）`
+- 之后可以直接使用缩写
+- 如果术语较多，在文档末尾附「术语表」
+
+### 全局设计不放代码
+
+架构图、UI 布局、数据流等全局设计章节只用图和文字描述，不放代码片段。代码属于详细设计层级——想看实现的读者会往下翻，只想理解方案的读者不应该被代码块打断。
+
+### 表格胜于段落
+
+当信息有多个并列维度时（如"每种消息类型的来源"、"每个组件是内置还是自定义"），优先用表格，不要用段落罗列。
+
+## 维护原则
+
+- `CLAUDE.md` 保持精简，详细内容下沉到 `.docs/` 子文档
+- 新增 `.docs/` 文档后，必须在 `CLAUDE.md` 文档索引中添加条目，包含链接和使用场景说明（告诉 AI 什么时候需要参考该文档）

package/src/commands/init.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { checkbox } from '@inquirer/prompts'
+import { getAvailableItems, getPackageVersion } from '../registry.js'
+import { registerProject } from '../projects.js'
+import { buildInjection, injectIntoClaude } from '../inject.js'
+
+const SPEC_DIR = '.docs/规范'
+
+export async function init() {
+  const cwd = process.cwd()
+  const rcPath = path.join(cwd, '.vibespecrc.json')
+
+  if (fs.existsSync(rcPath)) {
+    console.log('当前项目已初始化，使用 vibe-spec sync 同步最新规范')
+    return
+  }
+
+  const { specs, workflows } = getAvailableItems()
+  const allItems = [
+    ...specs.map((s) => ({ name: `${s.name} (规范)`, value: s, checked: true })),
+    ...workflows.map((w) => ({ name: `${w.name} (工作流)`, value: w, checked: true })),
+  ]
+
+  const selected = await checkbox({
+    message: '规范和工作流（取消选择用空格，确认用回车）',
+    choices: allItems,
+  })
+
+  if (selected.length === 0) {
+    console.log('未选择任何规范，退出')
+    return
+  }
+
+  const selectedSpecs = selected.filter((s) => s.type === 'spec')
+  const selectedWorkflows = selected.filter((s) => s.type === 'workflow')
+
+  // 复制规范文件
+  const destDir = path.join(cwd, SPEC_DIR)
+  fs.mkdirSync(destDir, { recursive: true })
+
+  for (const item of selected) {
+    const dest = path.join(destDir, path.basename(item.file))
+    fs.copyFileSync(item.file, dest)
+    console.log(`✔ 已写入 ${SPEC_DIR}/${path.basename(item.file)}`)
+  }
+
+  // 注入 CLAUDE.md
+  const specNames = selectedSpecs.map((s) => s.name)
+  const workflowNames = selectedWorkflows.map((w) => w.name)
+  const injection = buildInjection(specNames, workflowNames, SPEC_DIR)
+  injectIntoClaude(cwd, injection)
+  console.log('✔ 已注入 CLAUDE.md [vibe-spec 区域]')
+
+  // 创建 .vibespecrc.json
+  const rc = {
+    specs: specNames,
+    workflows: workflowNames,
+    specDir: SPEC_DIR,
+    version: getPackageVersion(),
+  }
+  fs.writeFileSync(rcPath, JSON.stringify(rc, null, 2) + '\n')
+  console.log('✔ 已创建 .vibespecrc.json')
+
+  // 注册项目
+  registerProject(cwd)
+  console.log('✔ 已注册项目路径（sync --all 时会同步此项目）')
+}

package/src/commands/list.js

@@ -0,0 +1,29 @@
+import { getAvailableItems } from '../registry.js'
+import { loadProjects } from '../projects.js'
+
+export async function list() {
+  const { specs, workflows } = getAvailableItems()
+  const projects = loadProjects()
+
+  console.log('规范：')
+  for (const s of specs) {
+    console.log(`  ${s.name}`)
+  }
+
+  if (workflows.length > 0) {
+    console.log('\n工作流：')
+    for (const w of workflows) {
+      console.log(`  ${w.name}`)
+    }
+  }
+
+  console.log(`\n已注册项目（${projects.length}）：`)
+  if (projects.length === 0) {
+    console.log('  （无）')
+  } else {
+    const home = process.env.HOME || ''
+    for (const p of projects) {
+      console.log(`  ${p.replace(home, '~')}`)
+    }
+  }
+}

package/src/commands/sync.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { SPECS_DIR, WORKFLOWS_DIR } from '../paths.js'
+import { getPackageVersion } from '../registry.js'
+import { loadProjects, saveProjects } from '../projects.js'
+import { buildInjection, injectIntoClaude } from '../inject.js'
+
+export async function sync(all) {
+  if (all) {
+    await syncAll()
+  } else {
+    await syncProject(process.cwd())
+  }
+}
+
+async function syncProject(projectDir) {
+  const rcPath = path.join(projectDir, '.vibespecrc.json')
+  if (!fs.existsSync(rcPath)) {
+    throw new Error('未找到 .vibespecrc.json，请先运行 vibe-spec init')
+  }
+
+  const rc = JSON.parse(fs.readFileSync(rcPath, 'utf-8'))
+  const pkgVersion = getPackageVersion()
+  const destDir = path.join(projectDir, rc.specDir)
+  const updated = []
+
+  fs.mkdirSync(destDir, { recursive: true })
+
+  // 同步 specs
+  for (const name of rc.specs) {
+    const src = path.join(SPECS_DIR, `${name}.md`)
+    const dest = path.join(destDir, `${name}.md`)
+    if (syncFile(src, dest)) {
+      updated.push(name)
+    }
+  }
+
+  // 同步 workflows
+  for (const name of rc.workflows) {
+    const src = path.join(WORKFLOWS_DIR, `${name}.md`)
+    const dest = path.join(destDir, `${name}.md`)
+    if (syncFile(src, dest)) {
+      updated.push(name)
+    }
+  }
+
+  // 注入 CLAUDE.md
+  const injection = buildInjection(rc.specs, rc.workflows, rc.specDir)
+  injectIntoClaude(projectDir, injection)
+
+  // 更新版本号
+  rc.version = pkgVersion
+  fs.writeFileSync(rcPath, JSON.stringify(rc, null, 2) + '\n')
+
+  return { updated, projectDir }
+}
+
+async function syncAll() {
+  const projects = loadProjects()
+
+  if (projects.length === 0) {
+    console.log('没有已注册的项目，请先在项目中运行 vibe-spec init')
+    return
+  }
+
+  // 过滤掉已不存在的项目
+  const valid = projects.filter((p) => fs.existsSync(p))
+  if (valid.length < projects.length) {
+    saveProjects(valid)
+  }
+
+  console.log(`同步 ${valid.length} 个项目：`)
+
+  for (const projectDir of valid) {
+    try {
+      const { updated } = await syncProject(projectDir)
+      const home = process.env.HOME || ''
+      const display = projectDir.replace(home, '~')
+      const detail = updated.length > 0 ? updated.join(', ') + ' 已更新' : '无变化'
+      console.log(`  ✓ ${display}  ${detail}`)
+    } catch (err) {
+      const home = process.env.HOME || ''
+      const display = projectDir.replace(home, '~')
+      console.log(`  ✗ ${display}  ${err.message}`)
+    }
+  }
+}
+
+function syncFile(src, dest) {
+  if (!fs.existsSync(src)) return false
+
+  const srcContent = fs.readFileSync(src, 'utf-8')
+  const destContent = fs.existsSync(dest) ? fs.readFileSync(dest, 'utf-8') : ''
+
+  if (srcContent === destContent) return false
+
+  fs.copyFileSync(src, dest)
+  return true
+}

package/src/index.js

@@ -0,0 +1,44 @@
+import { init } from './commands/init.js'
+import { sync } from './commands/sync.js'
+import { list } from './commands/list.js'
+
+const HELP = `
+vibe-spec — 跨项目通用 AI 编程规范管理工具
+
+命令：
+  vibe-spec init          新项目接入，交互式选择规范并安装
+  vibe-spec sync          同步当前项目到最新版本
+  vibe-spec sync --all    一次性推送到所有已注册项目
+  vibe-spec list          查看可用的规范、工作流和已注册项目
+  vibe-spec --help        显示帮助信息
+`.trim()
+
+export async function run(args) {
+  const command = args[0]
+
+  try {
+    switch (command) {
+      case 'init':
+        await init()
+        break
+      case 'sync':
+        await sync(args.includes('--all'))
+        break
+      case 'list':
+        await list()
+        break
+      case '--help':
+      case '-h':
+      case undefined:
+        console.log(HELP)
+        break
+      default:
+        console.error(`未知命令: ${command}`)
+        console.log(HELP)
+        process.exit(1)
+    }
+  } catch (err) {
+    console.error(`错误: ${err.message}`)
+    process.exit(1)
+  }
+}

package/src/inject.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const START_MARKER = '<!-- vibe-spec:start -->'
+const END_MARKER = '<!-- vibe-spec:end -->'
+
+/**
+ * 根据选中的 specs 和 workflows 生成注入内容
+ */
+export function buildInjection(specNames, workflowNames, specDir) {
+  const lines = [START_MARKER, '## 开发规范', '']
+
+  for (const name of specNames) {
+    lines.push(`- [${name}](./${specDir}/${name}.md)`)
+  }
+
+  if (workflowNames.length > 0) {
+    lines.push('', '## 工作流程', '')
+    for (const name of workflowNames) {
+      lines.push(`- [${name}](./${specDir}/${name}.md)`)
+    }
+  }
+
+  lines.push(END_MARKER)
+  return lines.join('\n')
+}
+
+/**
+ * 将内容注入 CLAUDE.md 的标记区域
+ * 如果标记不存在，追加到文件末尾
+ */
+export function injectIntoClaude(projectDir, content) {
+  const claudePath = path.join(projectDir, 'CLAUDE.md')
+
+  if (!fs.existsSync(claudePath)) {
+    fs.writeFileSync(claudePath, content + '\n')
+    return 'created'
+  }
+
+  const existing = fs.readFileSync(claudePath, 'utf-8')
+  const startIdx = existing.indexOf(START_MARKER)
+  const endIdx = existing.indexOf(END_MARKER)
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    const before = existing.slice(0, startIdx)
+    const after = existing.slice(endIdx + END_MARKER.length)
+    fs.writeFileSync(claudePath, before + content + after)
+    return 'updated'
+  }
+
+  fs.writeFileSync(claudePath, existing.trimEnd() + '\n\n' + content + '\n')
+  return 'appended'
+}

package/src/paths.js

@@ -0,0 +1,15 @@
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import os from 'node:os'
+
+// npm 包根目录（specs/、workflows/ 所在位置）
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+export const PKG_ROOT = path.resolve(__dirname, '..')
+
+// 全局数据目录
+export const DATA_DIR = path.join(os.homedir(), '.vibespec')
+export const PROJECTS_FILE = path.join(DATA_DIR, 'projects.json')
+
+// npm 包内的资源目录
+export const SPECS_DIR = path.join(PKG_ROOT, 'specs')
+export const WORKFLOWS_DIR = path.join(PKG_ROOT, 'workflows')

package/src/projects.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { DATA_DIR, PROJECTS_FILE } from './paths.js'
+
+export function loadProjects() {
+  if (!fs.existsSync(PROJECTS_FILE)) return []
+  return JSON.parse(fs.readFileSync(PROJECTS_FILE, 'utf-8'))
+}
+
+export function saveProjects(projects) {
+  fs.mkdirSync(DATA_DIR, { recursive: true })
+  fs.writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2) + '\n')
+}
+
+export function registerProject(projectPath) {
+  const projects = loadProjects()
+  const abs = path.resolve(projectPath)
+  if (!projects.includes(abs)) {
+    projects.push(abs)
+    saveProjects(projects)
+  }
+}

package/src/registry.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { SPECS_DIR, WORKFLOWS_DIR, PKG_ROOT } from './paths.js'
+
+/**
+ * 读取 npm 包内所有可用的 specs 和 workflows
+ */
+export function getAvailableItems() {
+  const specs = readDir(SPECS_DIR).map((file) => ({
+    name: path.basename(file, '.md'),
+    file: path.join(SPECS_DIR, file),
+    type: 'spec',
+  }))
+
+  const workflows = readDir(WORKFLOWS_DIR).map((file) => ({
+    name: path.basename(file, '.md'),
+    file: path.join(WORKFLOWS_DIR, file),
+    type: 'workflow',
+  }))
+
+  return { specs, workflows }
+}
+
+/**
+ * 获取当前包版本号
+ */
+export function getPackageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8'))
+  return pkg.version
+}
+
+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

@@ -0,0 +1,8 @@
+# 文档检查
+
+阶段性回顾时执行，检查项目文档的健康状态：
+
+1. **索引完整性** — `CLAUDE.md` 文档索引中的链接是否指向真实存在的文件；`.docs/` 下是否有文档未被索引
+2. **索引格式** — 各条目是否符合文档索引表中定义的格式（方案/产品带日期和概述，规范/概览带使用场景，测试带覆盖范围）
+3. **内容时效性** — 概览类文档（如数据模型）是否还能反映当前代码的实际状态
+4. **分类合规** — 文档是否放对了子目录、命名是否符合文档规范