chore: 初始化仓库

docs/.gitignore

@@ -0,0 +1,3 @@
+.vitepress/dist
+.vitepress/cache
+node_modules

docs/.vitepress/config.ts

@@ -0,0 +1,147 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+  title: "Spaceflow",
+  description: "可扩展的 AI 工作流引擎，统一 CI/CD 管理与 AI 代码审查",
+  lang: "zh-CN",
+
+  head: [["link", { rel: "icon", type: "image/svg+xml", href: "/logo.svg" }]],
+
+  themeConfig: {
+    nav: [
+      { text: "指南", link: "/guide/introduction", activeMatch: "/guide/" },
+      {
+        text: "参考",
+        items: [
+          { text: "配置", link: "/reference/config" },
+          { text: "CLI 命令", link: "/reference/cli" },
+          { text: "Review Spec", link: "/reference/review-spec" },
+        ],
+      },
+      {
+        text: "进阶",
+        items: [
+          { text: "插件开发", link: "/advanced/plugin-development" },
+          { text: "核心模块", link: "/advanced/core-modules" },
+          { text: "GitHub Actions", link: "/advanced/github-actions" },
+        ],
+      },
+    ],
+
+    sidebar: {
+      "/guide/": [
+        {
+          text: "入门",
+          items: [
+            { text: "简介", link: "/guide/introduction" },
+            { text: "快速开始", link: "/guide/getting-started" },
+            { text: "项目结构", link: "/guide/project-structure" },
+          ],
+        },
+        {
+          text: "核心概念",
+          items: [
+            { text: "配置文件", link: "/guide/configuration" },
+            { text: "Extension 系统", link: "/guide/extension-system" },
+            { text: "编辑器集成", link: "/guide/editor-integration" },
+          ],
+        },
+        {
+          text: "内置命令",
+          collapsed: false,
+          items: [
+            { text: "install — 安装 Extension", link: "/guide/commands/install" },
+            { text: "uninstall — 卸载 Extension", link: "/guide/commands/uninstall" },
+            { text: "update — 更新依赖", link: "/guide/commands/update" },
+            { text: "list — 列出 Extension", link: "/guide/commands/list" },
+            { text: "build — 构建", link: "/guide/commands/build" },
+            { text: "dev — 开发模式", link: "/guide/commands/dev" },
+            { text: "create — 创建模板", link: "/guide/commands/create" },
+            { text: "commit — 智能提交", link: "/guide/commands/commit" },
+            { text: "setup — 初始化配置", link: "/guide/commands/setup" },
+            { text: "schema — 生成 Schema", link: "/guide/commands/schema" },
+            { text: "mcp — MCP 服务", link: "/guide/commands/mcp" },
+            { text: "runx — 运行命令", link: "/guide/commands/runx" },
+            { text: "clear — 清理缓存", link: "/guide/commands/clear" },
+          ],
+        },
+        {
+          text: "外部命令",
+          collapsed: false,
+          items: [
+            { text: "review — 代码审查", link: "/guide/commands/review" },
+            { text: "publish — 版本发布", link: "/guide/commands/publish" },
+            { text: "ci-scripts — 脚本执行", link: "/guide/commands/ci-scripts" },
+            { text: "ci-shell — Shell 执行", link: "/guide/commands/ci-shell" },
+            { text: "period-summary — 周期总结", link: "/guide/commands/period-summary" },
+          ],
+        },
+      ],
+      "/reference/": [
+        {
+          text: "参考",
+          items: [
+            { text: "配置参考", link: "/reference/config" },
+            { text: "CLI 命令参考", link: "/reference/cli" },
+            { text: "Review Spec 规范", link: "/reference/review-spec" },
+            { text: "环境变量", link: "/reference/env-variables" },
+          ],
+        },
+      ],
+      "/advanced/": [
+        {
+          text: "进阶",
+          items: [
+            { text: "插件开发指南", link: "/advanced/plugin-development" },
+            { text: "核心模块", link: "/advanced/core-modules" },
+            { text: "GitHub Actions", link: "/advanced/github-actions" },
+            { text: "i18n 国际化", link: "/advanced/i18n" },
+          ],
+        },
+      ],
+    },
+
+    socialLinks: [{ icon: "github", link: "https://github.com/nicepkg/spaceflow" }],
+
+    footer: {
+      message: "基于 UNLICENSED 许可发布",
+      copyright: "Copyright © 2024-present Spaceflow Contributors",
+    },
+
+    outline: {
+      label: "页面导航",
+      level: [2, 3],
+    },
+
+    docFooter: {
+      prev: "上一页",
+      next: "下一页",
+    },
+
+    lastUpdated: {
+      text: "最后更新于",
+    },
+
+    search: {
+      provider: "local",
+      options: {
+        translations: {
+          button: { buttonText: "搜索文档", buttonAriaLabel: "搜索文档" },
+          modal: {
+            noResultsText: "无法找到相关结果",
+            resetButtonTitle: "清除查询条件",
+            footer: { selectText: "选择", navigateText: "切换" },
+          },
+        },
+      },
+    },
+
+    returnToTopLabel: "回到顶部",
+    sidebarMenuLabel: "菜单",
+    darkModeSwitchLabel: "主题",
+    lightModeSwitchTitle: "切换到浅色模式",
+    darkModeSwitchTitle: "切换到深色模式",
+  },
+
+  lastUpdated: true,
+});

docs/advanced/core-modules.md

@@ -0,0 +1,200 @@
+# 核心模块
+
+`@spaceflow/core` 提供的共享模块，所有 Extension 都可以导入使用。
+
+## 模块总览
+
+| 模块 | 导出 | 说明 |
+|------|------|------|
+| Git Provider | `GitProviderModule`, `GitProviderService` | Git 平台适配（GitHub / Gitea） |
+| Git SDK | `GitSdkModule`, `GitSdkService` | Git 命令封装 |
+| LLM Proxy | `LlmProxyModule`, `LlmProxyService` | 多 LLM 统一代理 |
+| Feishu SDK | `FeishuSdkModule`, `FeishuSdkService` | 飞书 API |
+| Storage | `StorageModule`, `StorageService` | 本地存储 |
+| Parallel | `ParallelModule`, `ParallelService` | 并行执行工具 |
+| Logger | `Logger` | 日志系统 |
+| i18n | `t()`, `initI18n()`, `addLocaleResources()` | 国际化 |
+| Config | `loadSpaceflowConfig()` | 配置加载 |
+
+## Git Provider
+
+Git 平台适配器，支持 GitHub 和 Gitea。
+
+```typescript
+import { GitProviderModule, GitProviderService } from "@spaceflow/core";
+
+@Module({
+  imports: [GitProviderModule.forFeature()],
+})
+export class MyModule {}
+
+@Injectable()
+export class MyService {
+  constructor(private readonly gitProvider: GitProviderService) {}
+
+  async createComment(prNumber: number, body: string): Promise<void> {
+    await this.gitProvider.createPRComment(prNumber, body);
+  }
+
+  async listFiles(prNumber: number): Promise<string[]> {
+    const files = await this.gitProvider.getPRFiles(prNumber);
+    return files.map((f) => f.filename);
+  }
+}
+```
+
+### 支持的平台
+
+| 平台 | 适配器 | 检测方式 |
+|------|--------|----------|
+| GitHub | `GithubAdapter` | `GITHUB_TOKEN` 环境变量 |
+| Gitea | `GiteaAdapter` | `GITEA_TOKEN` 环境变量 |
+
+默认使用 GitHub。可通过 `GIT_PROVIDER_TYPE` 环境变量显式指定。
+
+## Git SDK
+
+封装常用 Git 命令操作。
+
+```typescript
+import { GitSdkModule, GitSdkService } from "@spaceflow/core";
+
+@Injectable()
+export class MyService {
+  constructor(private readonly gitSdk: GitSdkService) {}
+
+  async getChanges(): Promise<string> {
+    return this.gitSdk.diff("main", "HEAD");
+  }
+
+  async getCurrentBranch(): Promise<string> {
+    return this.gitSdk.currentBranch();
+  }
+}
+```
+
+## LLM Proxy
+
+多 LLM 统一代理，支持 OpenAI、Claude、Claude Code、OpenCode 等。
+
+```typescript
+import { LlmProxyModule, LlmProxyService } from "@spaceflow/core";
+
+@Injectable()
+export class MyService {
+  constructor(private readonly llm: LlmProxyService) {}
+
+  async analyze(code: string): Promise<string> {
+    const result = await this.llm.chat({
+      messages: [
+        { role: "system", content: "你是一个代码分析助手" },
+        { role: "user", content: `分析以下代码:\n${code}` },
+      ],
+    });
+    return result.content;
+  }
+}
+```
+
+## Logger
+
+日志系统，支持 Plain 模式（CI/管道）和 TUI 模式（终端交互）。
+
+```typescript
+import { Logger } from "@spaceflow/core";
+
+const logger = new Logger("my-extension");
+await logger.init(); // 加载 TUI 渲染器
+
+// 基础日志
+logger.info("信息");
+logger.success("成功");
+logger.warn("警告");
+logger.error("错误");
+
+// Spinner
+const spinner = logger.spin("处理中...");
+spinner.update("仍在处理...");
+spinner.succeed("处理完成");
+
+// 进度条
+const progress = logger.progress({ total: 100, label: "下载" });
+progress.update(50);
+progress.finish();
+
+// 子 Logger
+const child = logger.child("compile");
+child.info("编译中..."); // 输出: [my-extension:compile] 编译中...
+```
+
+### 日志级别
+
+| 级别 | 说明 |
+|------|------|
+| `silent` | 不输出任何日志 |
+| `info` | 默认级别 |
+| `verbose` | 详细日志（`-v`） |
+| `debug` | 调试日志（`-vv`） |
+
+## Feishu SDK
+
+飞书 API 封装，支持发送消息。
+
+```typescript
+import { FeishuSdkModule, FeishuSdkService } from "@spaceflow/core";
+
+@Injectable()
+export class MyService {
+  constructor(private readonly feishu: FeishuSdkService) {}
+
+  async notify(chatId: string, message: string): Promise<void> {
+    await this.feishu.sendMessage(chatId, message);
+  }
+}
+```
+
+需要配置环境变量 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`。
+
+## Storage
+
+本地存储服务。
+
+```typescript
+import { StorageModule, StorageService } from "@spaceflow/core";
+
+@Injectable()
+export class MyService {
+  constructor(private readonly storage: StorageService) {}
+
+  async saveData(key: string, data: unknown): Promise<void> {
+    await this.storage.set(key, data);
+  }
+
+  async loadData<T>(key: string): Promise<T | undefined> {
+    return this.storage.get<T>(key);
+  }
+}
+```
+
+## Parallel
+
+并行执行工具，支持并发控制。
+
+```typescript
+import { ParallelModule, ParallelService } from "@spaceflow/core";
+
+@Injectable()
+export class MyService {
+  constructor(private readonly parallel: ParallelService) {}
+
+  async processFiles(files: string[]): Promise<void> {
+    await this.parallel.run(
+      files,
+      async (file) => {
+        // 处理单个文件
+      },
+      { concurrency: 10 },
+    );
+  }
+}
+```

docs/advanced/github-actions.md

@@ -0,0 +1,179 @@
+# GitHub Actions
+
+Spaceflow 提供预配置的 GitHub Actions，可以在 CI 中自动执行各种命令。
+
+## 官方 Action
+
+### 基本用法
+
+```yaml
+- uses: nicepkg/spaceflow/actions@main
+  with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    command: review
+```
+
+### 输入参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `github-token` | ✅ | GitHub Token |
+| `github-server-url` | ❌ | GitHub Server URL（默认自动检测） |
+| `command` | ✅ | 要执行的 spaceflow 命令 |
+
+## 预配置工作流
+
+### 自动 PR 审查
+
+在 PR 创建或更新时自动执行 AI 代码审查：
+
+```yaml
+# .github/workflows/pr-review.yml
+name: PR Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: nicepkg/spaceflow/actions@main
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          command: review
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```
+
+### 手动触发 PR 审查
+
+通过 PR 评论触发审查（如输入 `/review`）：
+
+```yaml
+# .github/workflows/pr-review-command.yml
+name: PR Review Command
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  review:
+    if: >
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/review')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: nicepkg/spaceflow/actions@main
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          command: review
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```
+
+### 自动版本发布
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - run: pnpm install --frozen-lockfile
+
+      - uses: nicepkg/spaceflow/actions@main
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          command: publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### 执行自定义命令
+
+```yaml
+# .github/workflows/test-command.yml
+name: Run Command
+
+on:
+  workflow_dispatch:
+    inputs:
+      command:
+        description: "要执行的 spaceflow 命令"
+        required: true
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: nicepkg/spaceflow/actions@main
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          command: ${{ github.event.inputs.command }}
+```
+
+## 环境变量配置
+
+在 GitHub 仓库的 Settings → Secrets and variables → Actions 中配置：
+
+| Secret | 说明 |
+|--------|------|
+| `OPENAI_API_KEY` | OpenAI API Key（review 命令需要） |
+| `ANTHROPIC_API_KEY` | Anthropic API Key（可选） |
+| `NPM_TOKEN` | npm 发布 Token（publish 命令需要） |
+| `FEISHU_APP_ID` | 飞书 App ID（通知需要） |
+| `FEISHU_APP_SECRET` | 飞书 App Secret（通知需要） |
+
+::: tip
+`GITHUB_TOKEN` 由 GitHub Actions 自动注入，无需手动配置。
+:::
+
+## 权限配置
+
+根据使用的命令，需要配置不同的权限：
+
+| 命令 | 需要的权限 |
+|------|-----------|
+| `review` | `contents: read`, `pull-requests: write` |
+| `publish` | `contents: write`, `packages: write` |
+| `ci-scripts` | `contents: read` |
+| `ci-shell` | `contents: read` |

docs/advanced/i18n.md

@@ -0,0 +1,156 @@
+# i18n 国际化
+
+Spaceflow 基于 [i18next](https://www.i18next.com/) 实现国际化，采用纯函数式设计，不依赖 NestJS DI。
+
+## 语言检测优先级
+
+1. 环境变量 `SPACEFLOW_LANG`
+2. `spaceflow.json` 中的 `lang` 字段
+3. 系统 locale（`process.env.LANG` / `process.env.LC_ALL`）
+4. 回退到 `zh-CN`
+
+## 核心 API
+
+### `initI18n(lang?: string)`
+
+同步初始化 i18next。必须在 NestJS 模块加载前调用。
+
+```typescript
+import { initI18n } from "@spaceflow/core";
+
+initI18n();      // 自动检测语言
+initI18n("en");  // 手动指定
+```
+
+### `t(key: string, options?: Record<string, unknown>)`
+
+全局翻译函数，装饰器和运行时均可使用。
+
+```typescript
+import { t } from "@spaceflow/core";
+
+// 公共 key（默认命名空间）
+t("common.executionFailed", { error: msg });
+
+// Extension 命名空间（用 : 分隔）
+t("build:description");
+t("review:options.dryRun");
+```
+
+### `addLocaleResources(ns: string, resources: Record<string, Record<string, string>>)`
+
+注册 Extension 的语言资源到指定命名空间。
+
+```typescript
+import { addLocaleResources } from "@spaceflow/core";
+
+addLocaleResources("hello", {
+  "zh-CN": { description: "打招呼命令" },
+  en: { description: "Say hello" },
+});
+```
+
+## 命名空间规则
+
+| 类型 | 命名空间 | 示例 |
+|------|----------|------|
+| 公共 key | 默认（`translation`） | `common.*`, `config.*`, `extensionLoader.*` |
+| 内部 Extension | Extension 名称 | `build:`, `dev:`, `commit:`, `install:` 等 |
+| 外部 Extension | Extension 名称 | `review:`, `publish:`, `ci-scripts:` 等 |
+
+## 语言包结构
+
+### core 公共语言包
+
+```text
+core/src/locales/
+├── zh-cn/
+│   └── translation.json    # 公共 key
+└── en/
+    └── translation.json
+```
+
+### Extension 语言包
+
+```text
+cli/src/commands/<name>/locales/
+├── zh-cn/
+│   └── <name>.json
+├── en/
+│   └── <name>.json
+└── index.ts                # 导入并注册资源
+```
+
+## Extension 中使用 i18n
+
+### 1. 创建语言包文件
+
+```json
+// locales/zh-cn/hello.json
+{
+  "description": "打招呼命令",
+  "options.name": "名字",
+  "greeting": "你好，{{name}}！"
+}
+```
+
+### 2. 注册语言资源
+
+```typescript
+// locales/index.ts
+import zhCN from "./zh-cn/hello.json";
+import en from "./en/hello.json";
+import { addLocaleResources } from "@spaceflow/core";
+
+export const helloLocales = { "zh-CN": zhCN, en };
+
+// Side-effect: 立即注册
+addLocaleResources("hello", helloLocales);
+```
+
+### 3. 在命令中使用
+
+```typescript
+import { t } from "@spaceflow/core";
+
+// 必须在命令模块 import 之前导入 locales（side-effect）
+import "./locales";
+
+@Command({
+  name: "hello",
+  description: t("hello:description"),
+})
+export class HelloCommand extends CommandRunner {
+  // ...
+}
+```
+
+### 4. 在 Extension 入口声明
+
+```typescript
+export class HelloExtension implements SpaceflowExtension {
+  getMetadata(): SpaceflowExtensionMetadata {
+    return {
+      name: "hello",
+      commands: ["hello"],
+      locales: helloLocales, // 加载时自动注册
+    };
+  }
+}
+```
+
+## 插值语法
+
+使用 i18next 默认的 `{{variable}}` 语法：
+
+```typescript
+t("hello:greeting", { name: "World" });
+// → "你好，World！"
+```
+
+## 注意事项
+
+- **同步初始化** — `initI18n()` 使用 `initSync`，确保装饰器执行时语言包已加载
+- **装饰器时机** — `@Command` / `@Option` 在 import 时执行，`initI18n()` 必须在所有命令模块 import 之前调用
+- **Side-effect import** — 每个 Extension 的 `locales/index.ts` 在导入时立即调用 `addLocaleResources`
+- **key 不存在时** — i18next 默认返回 key 本身，不会报错

docs/advanced/plugin-development.md

@@ -0,0 +1,286 @@
+# 插件开发指南
+
+本指南介绍如何开发自定义 Spaceflow Extension。
+
+## 前置知识
+
+- [NestJS](https://nestjs.com/) 基础（Module、Injectable、依赖注入）
+- [nest-commander](https://docs.nestjs.com/recipes/nest-commander) CLI 命令定义
+- TypeScript
+
+## 快速开始
+
+### 使用模板创建
+
+```bash
+spaceflow create my-extension
+```
+
+这会在当前目录下创建一个标准的 Extension 模板。
+
+### 手动创建
+
+```bash
+mkdir spaceflow-plugin-hello
+cd spaceflow-plugin-hello
+pnpm init
+pnpm add @spaceflow/core
+pnpm add -D typescript @types/node
+```
+
+## 目录结构
+
+```text
+spaceflow-plugin-hello/
+├── src/
+│   ├── hello.command.ts       # 命令定义
+│   ├── hello.service.ts       # 业务逻辑
+│   ├── hello.module.ts        # NestJS 模块
+│   ├── locales/               # i18n 资源
+│   │   ├── zh-cn/
+│   │   │   └── hello.json
+│   │   ├── en/
+│   │   │   └── hello.json
+│   │   └── index.ts
+│   └── index.ts               # Extension 入口
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Extension 入口
+
+每个 Extension 必须实现 `SpaceflowExtension` 接口：
+
+```typescript
+// src/index.ts
+import type {
+  SpaceflowExtension,
+  SpaceflowExtensionMetadata,
+} from "@spaceflow/core";
+import { HelloModule } from "./hello.module";
+import { helloLocales } from "./locales";
+
+export class HelloExtension implements SpaceflowExtension {
+  getMetadata(): SpaceflowExtensionMetadata {
+    return {
+      name: "hello",
+      commands: ["hello"],
+      configKey: "hello",
+      description: "示例 Extension",
+      locales: helloLocales,
+    };
+  }
+
+  getModule() {
+    return HelloModule;
+  }
+}
+
+export default HelloExtension;
+```
+
+## 命令定义
+
+使用 `@Command` 装饰器定义 CLI 命令：
+
+```typescript
+// src/hello.command.ts
+import { Command, CommandRunner, Option } from "@spaceflow/core";
+import { t } from "@spaceflow/core";
+import { HelloService } from "./hello.service";
+
+interface HelloOptions {
+  readonly name?: string;
+}
+
+@Command({
+  name: "hello",
+  description: t("hello:description"),
+})
+export class HelloCommand extends CommandRunner {
+  constructor(private readonly helloService: HelloService) {
+    super();
+  }
+
+  async run(_params: string[], options: HelloOptions): Promise<void> {
+    const name = options.name ?? "World";
+    console.log(this.helloService.greet(name));
+  }
+
+  @Option({
+    flags: "-n, --name <name>",
+    description: t("hello:options.name"),
+  })
+  parseName(val: string): string {
+    return val;
+  }
+}
+```
+
+## 业务逻辑
+
+```typescript
+// src/hello.service.ts
+import { Injectable } from "@spaceflow/core";
+
+@Injectable()
+export class HelloService {
+  greet(name: string): string {
+    return `Hello, ${name}!`;
+  }
+}
+```
+
+## NestJS 模块
+
+```typescript
+// src/hello.module.ts
+import { Module } from "@spaceflow/core";
+import { HelloCommand } from "./hello.command";
+import { HelloService } from "./hello.service";
+
+@Module({
+  providers: [HelloCommand, HelloService],
+})
+export class HelloModule {}
+```
+
+## 使用核心能力
+
+Extension 可以导入 `@spaceflow/core` 提供的共享模块：
+
+```typescript
+import { Module } from "@spaceflow/core";
+import { GitSdkModule } from "@spaceflow/core";
+import { LlmProxyModule } from "@spaceflow/core";
+
+@Module({
+  imports: [
+    GitSdkModule,       // Git 命令封装
+    LlmProxyModule,     // 多 LLM 代理
+  ],
+  providers: [MyCommand, MyService],
+})
+export class MyModule {}
+```
+
+在 Service 中注入使用：
+
+```typescript
+import { Injectable } from "@spaceflow/core";
+import { GitSdkService } from "@spaceflow/core";
+
+@Injectable()
+export class MyService {
+  constructor(private readonly gitSdk: GitSdkService) {}
+
+  async getDiff(): Promise<string> {
+    return this.gitSdk.diff("HEAD~1", "HEAD");
+  }
+}
+```
+
+### 可用的核心模块
+
+| 模块 | 说明 |
+|------|------|
+| `GitProviderModule` | Git 平台适配器（GitHub / Gitea） |
+| `GitSdkModule` | Git 命令封装 |
+| `LlmProxyModule` | 多 LLM 统一代理 |
+| `FeishuSdkModule` | 飞书 API |
+| `StorageModule` | 本地存储 |
+| `ParallelModule` | 并行执行工具 |
+
+## package.json 规范
+
+```json
+{
+  "name": "@spaceflow/plugin-hello",
+  "version": "1.0.0",
+  "description": "Spaceflow Hello Extension",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "@spaceflow/core": "^0.17.0"
+  },
+  "spaceflow": {
+    "commands": ["hello"],
+    "configKey": "hello"
+  }
+}
+```
+
+## i18n 支持
+
+在 `locales/` 目录下管理翻译资源：
+
+```typescript
+// src/locales/index.ts
+import zhCN from "./zh-cn/hello.json";
+import en from "./en/hello.json";
+import { addLocaleResources } from "@spaceflow/core";
+
+export const helloLocales: Record<string, Record<string, string>> = {
+  "zh-CN": zhCN,
+  en,
+};
+
+// Side-effect: 立即注册资源
+addLocaleResources("hello", helloLocales);
+```
+
+```json
+// src/locales/zh-cn/hello.json
+{
+  "description": "打招呼命令",
+  "options.name": "名字"
+}
+```
+
+```json
+// src/locales/en/hello.json
+{
+  "description": "Say hello",
+  "options.name": "Name"
+}
+```
+
+## 构建与发布
+
+### 构建
+
+```bash
+spaceflow build
+```
+
+### 本地测试
+
+在 `spaceflow.json` 中使用 `link:` 引用本地 Extension：
+
+```json
+{
+  "dependencies": {
+    "@spaceflow/plugin-hello": "link:./path/to/plugin-hello"
+  }
+}
+```
+
+### 发布到 npm
+
+```bash
+npm publish
+```
+
+用户安装：
+
+```bash
+spaceflow install @spaceflow/plugin-hello
+```

docs/guide/commands/build.md

@@ -0,0 +1,47 @@
+# build — 构建
+
+构建 Extension 包，将 TypeScript 源码编译为可发布的 JavaScript。
+
+## 基本用法
+
+```bash
+# 构建所有 Extension
+spaceflow build
+
+# 构建指定 Extension
+spaceflow build review
+
+# 监听模式（文件变化时自动重新构建）
+spaceflow build --watch
+```
+
+## 构建流程
+
+1. **扫描 Extension** — 查找 `commands/` 目录下的所有 Extension 包
+2. **读取配置** — 读取每个包的 `rspack.config.mjs` 或默认配置
+3. **编译打包** — 使用 Rspack 将 TypeScript 编译为单文件 JavaScript
+4. **输出结果** — 生成到各包的 `dist/` 目录
+
+## 监听模式
+
+使用 `--watch` 或 `dev` 命令进入监听模式，文件变化时自动重新构建：
+
+```bash
+spaceflow build --watch
+# 等价于
+spaceflow dev
+```
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--watch` | `-w` | 监听模式，文件变化自动重新构建 |
+| `--verbose` | `-v` | 详细日志 |
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| `0` | 所有 Extension 构建成功 |
+| `1` | 至少一个 Extension 构建失败 |

docs/guide/commands/ci-scripts.md

@@ -0,0 +1,34 @@
+# ci-scripts — 脚本执行
+
+`ci-scripts` 命令用于在 CI 环境中执行仓库中的自定义脚本。
+
+## 安装
+
+```bash
+spaceflow install @spaceflow/ci-scripts
+```
+
+## 基本用法
+
+```bash
+# 执行指定脚本
+spaceflow ci-scripts --script ./scripts/deploy.sh
+
+# CI 模式
+spaceflow ci-scripts --script ./scripts/test.sh --ci
+```
+
+## 使用场景
+
+- 在 PR 合并后执行部署脚本
+- 在 CI 中运行自定义检查脚本
+- 批量执行仓库中的自动化任务
+
+## 命令行选项
+
+| 选项 | 说明 |
+|------|------|
+| `--script <path>` | 脚本文件路径 |
+| `--ci` | CI 模式 |
+| `--dry-run` | 试运行 |
+| `--verbose` | 详细日志 |

docs/guide/commands/ci-shell.md

@@ -0,0 +1,34 @@
+# ci-shell — Shell 执行
+
+`ci-shell` 命令用于在 CI 环境中执行自定义 Shell 命令。
+
+## 安装
+
+```bash
+spaceflow install @spaceflow/ci-shell
+```
+
+## 基本用法
+
+```bash
+# 执行 Shell 命令
+spaceflow ci-shell --command "npm test"
+
+# CI 模式
+spaceflow ci-shell --command "npm run build" --ci
+```
+
+## 使用场景
+
+- 在 CI 中执行任意 Shell 命令
+- 通过 GitHub Actions 触发自定义命令
+- 配合飞书机器人远程执行命令
+
+## 命令行选项
+
+| 选项 | 说明 |
+|------|------|
+| `--command <cmd>` | 要执行的 Shell 命令 |
+| `--ci` | CI 模式 |
+| `--dry-run` | 试运行 |
+| `--verbose` | 详细日志 |

docs/guide/commands/clear.md

@@ -0,0 +1,55 @@
+# clear — 清理缓存
+
+清理所有已安装的 Extension 依赖和编辑器关联文件。
+
+## 基本用法
+
+```bash
+# 清理本地安装的所有内容
+spaceflow clear
+
+# 清理全局安装的所有内容
+spaceflow clear -g
+```
+
+## 清理范围
+
+执行以下清理操作：
+
+1. **删除依赖目录** — 清空 `.spaceflow/deps/` 下的所有已安装依赖
+2. **清理编辑器 skills** — 删除各编辑器配置目录下的 skills 关联文件
+3. **清理编辑器 commands** — 删除各编辑器配置目录下生成的 `.md` 命令文件
+
+### 影响的目录
+
+| 目录 | 说明 |
+|------|------|
+| `.spaceflow/deps/` | 本地依赖安装目录 |
+| `.claude/skills/` | Claude Code 技能文件 |
+| `.windsurf/skills/` | Windsurf 技能文件 |
+| `.cursor/skills/` | Cursor 技能文件 |
+
+::: warning
+清理操作不可撤销。清理后需要重新运行 `spaceflow install` 恢复依赖。
+:::
+
+## 全局清理
+
+使用 `-g` 清理全局目录 `~/.spaceflow/`：
+
+```bash
+spaceflow clear -g
+```
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--global` | `-g` | 清理全局安装 |
+| `--verbose` | `-v` | 详细日志 |
+
+## 使用场景
+
+- Extension 安装出现异常，需要重新安装
+- 切换项目配置后，清理旧的关联文件
+- 排查问题时，从干净状态重新开始

docs/guide/commands/commit.md

@@ -0,0 +1,145 @@
+# commit — 智能提交
+
+基于 AI 自动生成符合 [Conventional Commits](https://www.conventionalcommits.org/) 规范的 commit message，并执行 `git commit`。
+
+## 基本用法
+
+```bash
+# 自动生成 commit message 并提交
+spaceflow commit
+
+# 试运行，仅生成不提交
+spaceflow commit --dry-run
+
+# 智能拆分提交（按模块/功能自动拆分为多个 commit）
+spaceflow commit --split
+
+# 跳过 git hooks
+spaceflow commit --no-verify
+```
+
+## 工作流程
+
+### 普通模式
+
+1. **检查暂存区** — 确认有 `git add` 过的文件
+2. **获取上下文** — 读取暂存文件列表、diff、所属包信息、最近 commit 历史
+3. **构建 Prompt** — 将上下文和 Conventional Commits 类型规范发送给 LLM
+4. **解析响应** — 从 AI 响应中提取 `type`、`scope`、`subject`、`body`
+5. **执行提交** — 格式化为 `type(scope): subject` 并执行 `git commit`
+
+### Split 模式（`--split`）
+
+1. **收集文件** — 获取暂存区或工作区的所有变更文件
+2. **分组策略** — 根据配置的 scope 策略对文件分组：
+   - `package` — 按 `package.json` 所属包分组（默认）
+   - `rules` — 按自定义 glob 规则分组
+   - `rules-first` — 优先规则匹配，未匹配的按包分组
+3. **AI 分析** — 单组时让 AI 进一步分析是否需要拆分
+4. **并行生成** — 并行为每个组生成 commit message
+5. **顺序提交** — 子包优先、根目录最后，逐个 `git add` + `git commit`
+
+## Scope 自动推断
+
+Spaceflow 会自动根据文件所属的 `package.json` 推断 scope：
+
+```text
+cli/src/commands/build/build.service.ts  → scope: cli
+core/src/shared/logger/logger.ts         → scope: core
+commands/review/src/review.service.ts    → scope: review
+package.json                             → scope: (空，根目录)
+```
+
+## Commit 类型
+
+类型列表从 `spaceflow.json` 的 `publish.changelog.preset.type` 读取，默认值：
+
+| 类型 | 含义 |
+|------|------|
+| `feat` | 新特性 |
+| `fix` | 修复 BUG |
+| `perf` | 性能优化 |
+| `refactor` | 代码重构 |
+| `docs` | 文档更新 |
+| `style` | 代码格式 |
+| `test` | 测试用例 |
+| `chore` | 其他修改 |
+
+## Scope 配置
+
+在 `spaceflow.json` 中配置 `commit` 字段自定义 scope 策略：
+
+```json
+{
+  "commit": {
+    "strategy": "rules-first",
+    "rules": [
+      { "pattern": "docs/**", "scope": "docs" },
+      { "pattern": ".github/**", "scope": "ci" },
+      { "pattern": "*.config.*", "scope": "config" }
+    ]
+  }
+}
+```
+
+### 策略说明
+
+| 策略 | 说明 |
+|------|------|
+| `package` | 按 `package.json` 所属包推断 scope（默认） |
+| `rules` | 仅使用自定义 glob 规则匹配 |
+| `rules-first` | 优先规则匹配，未匹配的回退到包推断 |
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--dry-run` | `-d` | 试运行，仅生成 message 不提交 |
+| `--split` | `-s` | 智能拆分为多个 commit |
+| `--no-verify` | `-n` | 跳过 git hooks |
+| `--verbose` | `-v` | 详细日志（`-v` 基本，`-vv` 详细） |
+
+## 示例
+
+```bash
+# 普通提交
+git add .
+spaceflow commit
+
+# 预览生成的 message
+git add .
+spaceflow commit --dry-run
+
+# 智能拆分（自动 git add 工作区文件）
+spaceflow commit --split
+
+# 拆分 + 预览
+spaceflow commit --split --dry-run
+
+# 详细日志查看 AI 交互过程
+spaceflow commit -vv
+```
+
+## 输出示例
+
+### 普通模式
+
+```text
+正在生成 commit message...
+──────────────────────────────────────────────────
+feat(core): 添加 Logger 模块支持 TUI 和 Plain 两种渲染模式
+──────────────────────────────────────────────────
+提交成功
+```
+
+### Split 模式
+
+```text
+按包目录分组策略分组...
+检测到 3 个分组
+并行生成 3 个 commit message...
+✅ Commit 1: feat(core): 添加 Logger 模块
+✅ Commit 2: feat(cli): 集成 Logger 到 build 命令
+✅ Commit 3: docs: 更新 Logger 文档
+分批提交完成，共 3 个 commit
+```

docs/guide/commands/create.md

@@ -0,0 +1,90 @@
+# create — 创建模板
+
+基于模板创建新的 Extension 项目。支持本地模板和远程 Git 仓库模板。
+
+## 基本用法
+
+```bash
+# 创建命令型 Extension
+spaceflow create command my-cmd
+
+# 创建技能型 Extension
+spaceflow create skills my-skill
+
+# 查看可用模板
+spaceflow create --list
+
+# 指定输出目录
+spaceflow create command my-cmd -d ./plugins/my-cmd
+
+# 使用远程模板仓库
+spaceflow create --from https://github.com/user/templates command my-cmd
+
+# 使用远程模板仓库的指定分支/标签
+spaceflow create --from git@github.com:org/tpl.git --ref v1.0 api my-api
+```
+
+## 模板类型
+
+模板动态读取自项目的 `templates/` 目录。内置模板包括：
+
+| 模板 | 说明 |
+|------|------|
+| `command` | 命令型 Extension，提供 CLI 命令 |
+| `skills` | 技能型 Extension，提供编辑器 AI 技能文件 |
+
+## 远程模板
+
+使用 `--from` 指定远程 Git 仓库作为模板来源：
+
+```bash
+# GitHub 仓库
+spaceflow create --from https://github.com/user/templates command my-cmd
+
+# Gitea 仓库
+spaceflow create --from https://git.example.com/org/templates command my-cmd
+
+# SSH + 指定 ref
+spaceflow create --from git@github.com:org/tpl.git --ref v1.0 api my-api
+```
+
+远程模板会被下载到本地缓存，后续使用时优先使用缓存。
+
+## 生成的文件结构
+
+以 `command` 模板为例：
+
+```text
+my-cmd/
+├── src/
+│   ├── my-cmd.command.ts      # 命令定义
+│   ├── my-cmd.service.ts      # 业务逻辑
+│   ├── my-cmd.module.ts       # NestJS 模块
+│   └── index.ts               # Extension 入口
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--directory <dir>` | `-d` | 指定输出目录 |
+| `--list` | `-l` | 列出可用模板 |
+| `--from <repo>` | `-f` | 远程模板仓库 URL |
+| `--ref <ref>` | `-r` | 远程仓库的分支/标签/commit |
+| `--verbose` | `-v` | 详细日志 |
+
+## 示例
+
+```bash
+# 查看所有可用模板
+spaceflow create --list
+
+# 查看远程仓库的可用模板
+spaceflow create --from https://github.com/org/templates --list
+
+# 创建并指定目录
+spaceflow create command my-review -d ./commands/my-review
+```

docs/guide/commands/dev.md

@@ -0,0 +1,33 @@
+# dev — 开发模式
+
+以监听模式构建 Extension，文件变化时自动重新编译。等价于 `spaceflow build --watch`。
+
+## 基本用法
+
+```bash
+# 监听并构建所有 Extension
+spaceflow dev
+
+# 监听并构建指定 Extension
+spaceflow dev review
+```
+
+## 与 build --watch 的关系
+
+`dev` 命令是 `build --watch` 的快捷方式，内部调用相同的 `BuildService.watch()` 方法。
+
+```bash
+spaceflow dev          # 等价于 spaceflow build --watch
+spaceflow dev review   # 等价于 spaceflow build review --watch
+```
+
+## 使用场景
+
+- 开发新 Extension 时，实时编译查看效果
+- 调试 Extension 代码，修改后自动重新构建
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--verbose` | `-v` | 详细日志 |

docs/guide/commands/install.md

@@ -0,0 +1,79 @@
+# install — 安装 Extension
+
+安装外部 Extension 到当前项目或全局环境。
+
+## 基本用法
+
+```bash
+# 安装指定 Extension（npm 包）
+spaceflow install @spaceflow/review
+
+# 安装本地路径
+spaceflow install ./commands/my-plugin
+
+# 安装 git 仓库
+spaceflow install git@github.com:org/plugin.git
+
+# 安装所有 spaceflow.json 中的 dependencies
+spaceflow install
+
+# 全局安装
+spaceflow install @spaceflow/review -g
+```
+
+## 支持的 source 类型
+
+| 类型 | 示例 | 说明 |
+|------|------|------|
+| npm 包 | `@spaceflow/review` | 执行 `pnpm add <package>` |
+| 本地路径 | `./commands/my-plugin` | 注册 `link:` 引用到 `spaceflow.json` |
+| git 仓库 | `git@github.com:org/plugin.git` | 克隆到 `.spaceflow/deps/` |
+
+## 安装流程
+
+1. **解析 source** — 判断是 npm 包、本地路径还是 git 仓库
+2. **安装依赖** — 根据类型执行对应的安装操作
+3. **更新配置** — 将 Extension 注册到 `spaceflow.json` 的 `dependencies` 字段
+4. **关联编辑器** — 将 Extension 的 skills 关联到 `support` 中配置的编辑器目录
+
+## 无参数模式
+
+不传 source 时，会读取 `spaceflow.json` 中的 `dependencies` 字段，安装所有已注册的 Extension：
+
+```bash
+spaceflow install
+```
+
+等价于遍历 `dependencies` 中的每一项并逐个安装。
+
+## 全局安装
+
+使用 `-g` 标志安装到全局目录 `~/.spaceflow/`：
+
+```bash
+spaceflow install @spaceflow/review -g
+```
+
+全局安装的 Extension 在所有项目中可用。
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--name <name>` | `-n` | 自定义 Extension 名称 |
+| `--global` | `-g` | 全局安装 |
+| `--verbose` | `-v` | 详细日志 |
+| `--ignore-errors` | | 忽略错误，不退出进程 |
+
+## 示例
+
+```bash
+# 安装并指定名称
+spaceflow install @spaceflow/review --name review
+
+# 安装本地开发中的 Extension
+spaceflow install ./commands/review
+
+# CI 中安装所有依赖（忽略错误）
+spaceflow install --ignore-errors
+```

docs/guide/commands/list.md

@@ -0,0 +1,37 @@
+# list — 列出 Extension
+
+列出当前项目中已安装的所有 Extension 及其信息。
+
+## 基本用法
+
+```bash
+spaceflow list
+```
+
+## 输出示例
+
+```text
+已安装的 Extension:
+
+  review        @spaceflow/review          [link]
+    命令: review
+
+  publish       @spaceflow/publish         [link]
+    命令: publish
+
+  ci-shell      @spaceflow/ci-shell        [npm]
+    命令: ci-shell
+```
+
+输出包含：
+
+- **Extension 名称** — 注册名
+- **包名** — npm 包名或路径
+- **安装类型** — `[link]`（本地路径）、`[npm]`（npm 包）、`[git]`（git 仓库）
+- **提供的命令** — 该 Extension 注册的 CLI 命令
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--verbose` | `-v` | 显示更多详细信息 |

docs/guide/commands/mcp.md

@@ -0,0 +1,100 @@
+# mcp — MCP 服务
+
+启动 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，聚合所有已安装 Extension 提供的 MCP 工具。
+
+## 基本用法
+
+```bash
+# 启动 MCP Server
+spaceflow mcp
+
+# 启动 MCP Inspector（调试模式）
+spaceflow mcp --inspector
+```
+
+## 工作原理
+
+1. **扫描 Extension** — 加载所有已安装的 Extension
+2. **收集工具** — 查找带有 `@McpServer` 装饰器的类，提取其 MCP 工具定义
+3. **启动服务** — 通过 stdio 传输协议启动 MCP Server
+4. **注册工具** — 将所有工具注册到 MCP Server，支持 JSON Schema 参数校验
+
+## MCP Inspector
+
+使用 `--inspector` 启动 MCP Inspector，提供 Web UI 调试界面：
+
+```bash
+spaceflow mcp --inspector
+```
+
+Inspector 会自动下载并启动 `@modelcontextprotocol/inspector`，提供：
+
+- 工具列表查看
+- 工具调用测试
+- 请求/响应日志
+
+## 在编辑器中配置
+
+### Claude Desktop
+
+在 `claude_desktop_config.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "spaceflow": {
+      "command": "spaceflow",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+在 `.cursor/mcp.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "spaceflow": {
+      "command": "spaceflow",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## 开发 MCP 工具
+
+Extension 可以通过 `@McpServer` 和 `@McpTool` 装饰器暴露 MCP 工具：
+
+```typescript
+import { McpServer, McpTool, Injectable } from "@spaceflow/core";
+
+@McpServer({ name: "my-tools", description: "我的工具集" })
+@Injectable()
+export class MyMcpTools {
+  @McpTool({
+    name: "hello",
+    description: "打招呼",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "名字" },
+      },
+      required: ["name"],
+    },
+  })
+  async hello(args: { name: string }): Promise<string> {
+    return `Hello, ${args.name}!`;
+  }
+}
+```
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--inspector` | `-i` | 启动 MCP Inspector 调试模式 |
+| `--verbose` | `-v` | 详细日志（`-v` 基本，`-vv` 详细，`-vvv` 调试） |

docs/guide/commands/period-summary.md

@@ -0,0 +1,37 @@
+# period-summary — 周期总结
+
+`period-summary` 命令用于生成周期性工作总结，支持飞书消息推送。
+
+## 安装
+
+```bash
+spaceflow install @spaceflow/period-summary
+```
+
+## 基本用法
+
+```bash
+# 生成周总结
+spaceflow period-summary --period week
+
+# 生成月总结
+spaceflow period-summary --period month
+
+# 推送到飞书
+spaceflow period-summary --period week --notify feishu
+```
+
+## 功能特性
+
+- **Git 日志分析** — 自动分析指定周期内的 Git 提交记录
+- **AI 总结** — 使用 LLM 生成结构化的工作总结
+- **飞书推送** — 支持将总结推送到飞书群聊
+
+## 命令行选项
+
+| 选项 | 说明 |
+|------|------|
+| `--period <period>` | 总结周期（week / month） |
+| `--notify <channel>` | 通知渠道（feishu） |
+| `--dry-run` | 试运行 |
+| `--verbose` | 详细日志 |

docs/guide/commands/publish.md

@@ -0,0 +1,70 @@
+# publish — 版本发布
+
+`publish` 命令提供自动化版本发布能力，基于 [release-it](https://github.com/release-it/release-it) 实现版本管理和变更日志生成。
+
+## 安装
+
+```bash
+spaceflow install @spaceflow/publish
+```
+
+## 基本用法
+
+```bash
+# 发布版本
+spaceflow publish
+
+# 试运行
+spaceflow publish --dry-run
+
+# 指定版本号
+spaceflow publish --version 1.2.0
+```
+
+## 功能特性
+
+- **自动版本号** — 基于 Conventional Commits 自动计算版本号
+- **变更日志** — 自动生成 CHANGELOG.md
+- **Monorepo 支持** — 支持 pnpm workspace 的多包发布
+- **npm 发布** — 自动发布到 npm registry
+- **Git 标签** — 自动创建 Git tag 并推送
+
+## 配置
+
+```json
+{
+  "publish": {
+    "monorepo": {
+      "enabled": true,
+      "propagateDeps": true
+    },
+    "changelog": {
+      "preset": {
+        "type": [
+          { "type": "feat", "section": "新特性" },
+          { "type": "fix", "section": "修复BUG" },
+          { "type": "perf", "section": "性能优化" },
+          { "type": "refactor", "section": "代码重构" }
+        ]
+      }
+    },
+    "npm": {
+      "publish": true,
+      "packageManager": "pnpm",
+      "tag": "latest"
+    },
+    "git": {
+      "pushWhitelistUsernames": ["github-actions[bot]"]
+    }
+  }
+}
+```
+
+## 命令行选项
+
+| 选项 | 说明 |
+|------|------|
+| `--dry-run` | 试运行，不实际发布 |
+| `--version <version>` | 指定版本号 |
+| `--verbose` | 详细日志 |
+| `--ci` | CI 模式 |

docs/guide/commands/review.md

@@ -0,0 +1,113 @@
+# review — 代码审查
+
+`review` 是 Spaceflow 的核心命令，提供基于 LLM 的自动化代码审查能力。
+
+## 安装
+
+```bash
+spaceflow install @spaceflow/review
+```
+
+## 基本用法
+
+```bash
+# 审查指定 PR
+spaceflow review -p <pr-number>
+
+# 审查两个分支之间的差异
+spaceflow review -b <base-branch> --head <head-branch>
+
+# 使用指定 LLM 模式
+spaceflow review -p 123 -l openai
+```
+
+## 功能特性
+
+### AI 代码审查
+
+- 自动分析 PR 中的代码变更
+- 基于审查规范（Review Spec）生成结构化审查意见
+- 支持行内评论，直接在 PR 的代码行上添加审查意见
+
+### PR 描述生成
+
+启用 `generateDescription` 后，自动根据代码变更生成 PR 描述：
+
+```bash
+spaceflow review -p 123 --generate-description
+```
+
+### 删除代码分析
+
+分析删除代码的潜在影响：
+
+```bash
+spaceflow review -p 123 --analyze-deletions
+```
+
+### 修复验证
+
+验证 AI 提出的修复建议是否正确：
+
+```bash
+spaceflow review -p 123 --verify-fixes
+```
+
+## 支持的 LLM
+
+| 模式 | 说明 | 环境变量 |
+|------|------|----------|
+| `openai` | OpenAI API（GPT-4o 等） | `OPENAI_API_KEY`, `OPENAI_BASE_URL` |
+| `claude` | Anthropic Claude API | `ANTHROPIC_API_KEY` |
+| `claude-code` | Claude Code Agent | `CLAUDE_CODE_BASE_URL`, `CLAUDE_CODE_AUTH_TOKEN` |
+| `open-code` | OpenCode SDK | `OPENCODE_API_KEY` |
+
+## 审查规范
+
+Review 命令会加载 `references` 配置中指定的审查规范文件，用于指导 AI 审查。
+
+```json
+{
+  "review": {
+    "references": [
+      "./references",
+      "https://github.com/your-org/review-spec"
+    ]
+  }
+}
+```
+
+支持本地目录和远程 Git 仓库 URL。详见 [Review Spec 规范](/reference/review-spec)。
+
+## 配置
+
+```json
+{
+  "review": {
+    "references": ["./references"],
+    "includes": ["*/**/*.ts", "!*/**/*.spec.*"],
+    "generateDescription": true,
+    "lineComments": true,
+    "verifyFixes": true,
+    "analyzeDeletions": false,
+    "concurrency": 10,
+    "retries": 3
+  }
+}
+```
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--pr <number>` | `-p` | PR 编号 |
+| `--base <branch>` | `-b` | 基准分支 |
+| `--head <branch>` | | 目标分支 |
+| `--llm-mode <mode>` | `-l` | LLM 模式 |
+| `--generate-description` | | 生成 PR 描述 |
+| `--line-comments` | | 生成行内评论 |
+| `--analyze-deletions` | | 分析删除代码 |
+| `--verify-fixes` | | 验证修复建议 |
+| `--dry-run` | | 试运行，不实际提交评论 |
+| `--concurrency <n>` | | 并发数 |
+| `--verbose` | `-v` | 详细日志 |

docs/guide/commands/runx.md

@@ -0,0 +1,67 @@
+# runx — 运行命令
+
+全局安装并运行 Extension 命令，类似于 `npx`。别名为 `x`。
+
+## 基本用法
+
+```bash
+# 运行指定 Extension 的命令
+spaceflow x @spaceflow/review --help
+
+# 运行本地路径的 Extension
+spaceflow x ./commands/ci-scripts -- --script ./deploy.sh
+
+# 使用完整命令名
+spaceflow runx @spaceflow/review -- -p 123
+```
+
+## 工作流程
+
+1. **全局安装** — 如果 Extension 未全局安装，先执行全局安装
+2. **运行命令** — 执行该 Extension 提供的命令，透传所有参数
+
+## 参数传递
+
+使用 `--` 分隔 `runx` 自身的选项和传递给 Extension 的参数：
+
+```bash
+spaceflow x <source> [runx选项] -- [Extension参数]
+```
+
+示例：
+
+```bash
+# 传递 --help 给 review 命令
+spaceflow x @spaceflow/review -- --help
+
+# 传递 -p 123 给 review 命令
+spaceflow x @spaceflow/review -- -p 123
+
+# 指定名称并传递参数
+spaceflow x ./commands/ci-scripts -n ci-scripts -- --script ./test.sh
+```
+
+## 与 install 的区别
+
+| 特性 | `install` | `runx` |
+|------|-----------|--------|
+| 安装位置 | 本地项目（默认） | 全局 |
+| 持久化 | 写入 `spaceflow.json` | 不修改配置 |
+| 用途 | 长期使用的 Extension | 临时运行 |
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--name <name>` | `-n` | 自定义 Extension 名称 |
+| `--verbose` | `-v` | 详细日志 |
+
+## 示例
+
+```bash
+# 临时运行 review
+spaceflow x @spaceflow/review -- -p 42
+
+# 临时运行本地 Extension
+spaceflow x ./commands/my-tool -- --config custom.json
+```

docs/guide/commands/schema.md

@@ -0,0 +1,44 @@
+# schema — 生成 Schema
+
+生成 `spaceflow.json` 的 JSON Schema 文件，用于编辑器自动补全和校验。
+
+## 基本用法
+
+```bash
+spaceflow schema
+```
+
+## 功能说明
+
+执行后会在 `.spaceflow/` 目录下生成 `config-schema.json` 文件。
+
+该 Schema 文件：
+
+- 描述 `spaceflow.json` 的完整结构
+- 包含所有已安装 Extension 的配置字段
+- 提供字段类型、默认值、枚举值等元信息
+
+## 在配置文件中引用
+
+在 `spaceflow.json` 中添加 `$schema` 字段即可启用编辑器补全：
+
+```json
+{
+  "$schema": "./.spaceflow/config-schema.json",
+  "support": ["claudeCode"],
+  "review": {
+    "references": ["./references"]
+  }
+}
+```
+
+支持的编辑器：
+
+- **VS Code** — 自动识别 `$schema` 字段，提供补全和校验
+- **WebStorm / IntelliJ** — 自动识别 `$schema` 字段
+- **其他支持 JSON Schema 的编辑器**
+
+## 使用场景
+
+- 安装新 Extension 后，重新生成 Schema 以获取新配置项的补全
+- 项目初始化时，`spaceflow setup` 会自动调用此命令

docs/guide/commands/setup.md

@@ -0,0 +1,87 @@
+# setup — 初始化配置
+
+初始化 Spaceflow 项目配置，创建必要的目录和配置文件。
+
+## 基本用法
+
+```bash
+# 本地初始化
+spaceflow setup
+
+# 全局初始化
+spaceflow setup -g
+```
+
+## 本地初始化
+
+在当前项目中创建 Spaceflow 配置：
+
+```bash
+spaceflow setup
+```
+
+执行以下操作：
+
+1. **创建 `.spaceflow/` 目录** — 包含 `package.json`（用于管理 Extension 依赖）
+2. **生成 JSON Schema** — 创建 `config-schema.json`，提供编辑器自动补全
+3. **创建 `spaceflow.json`** — 默认配置文件（如果不存在）
+
+生成的默认配置：
+
+```json
+{
+  "$schema": "./config-schema.json",
+  "support": ["claudeCode"]
+}
+```
+
+::: tip
+如果已存在 `spaceflow.json` 或 `.spaceflowrc`，不会覆盖。
+:::
+
+## 全局初始化
+
+创建全局配置，合并本地配置和环境变量：
+
+```bash
+spaceflow setup -g
+```
+
+执行以下操作：
+
+1. **创建 `~/.spaceflow/` 目录** — 全局配置目录
+2. **读取本地配置** — 读取当前项目的 `spaceflow.json`
+3. **读取 `.env` 文件** — 解析 `SPACEFLOW_` 前缀的环境变量
+4. **合并配置** — 本地配置 < 实例配置 < 环境变量配置
+5. **写入全局配置** — 保存到 `~/.spaceflow/spaceflow.json`
+
+### 环境变量映射
+
+`.env` 文件中以 `SPACEFLOW_` 开头的变量会自动转换为配置项：
+
+```bash
+# .env
+SPACEFLOW_REVIEW_CONCURRENCY=20
+SPACEFLOW_REVIEW_RETRIES=5
+```
+
+转换为：
+
+```json
+{
+  "review": {
+    "concurrency": "20",
+    "retries": "5"
+  }
+}
+```
+
+::: warning
+敏感信息（包含 `token`、`secret`、`password`、`key` 的字段）在输出时会显示为 `***`。
+:::
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--global` | `-g` | 全局初始化 |

docs/guide/commands/uninstall.md

@@ -0,0 +1,36 @@
+# uninstall — 卸载 Extension
+
+从当前项目或全局环境中卸载已安装的 Extension。
+
+## 基本用法
+
+```bash
+# 卸载指定 Extension
+spaceflow uninstall @spaceflow/review
+
+# 全局卸载
+spaceflow uninstall @spaceflow/review -g
+```
+
+## 卸载流程
+
+1. **移除依赖** — npm 包执行 `pnpm remove`；git 仓库执行 `git submodule deinit` 并删除目录
+2. **更新配置** — 从 `spaceflow.json` 的 `dependencies` 中移除
+3. **清理关联** — 移除编辑器目录中的关联文件
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--global` | `-g` | 卸载全局安装的 Extension |
+| `--verbose` | `-v` | 详细日志 |
+
+## 示例
+
+```bash
+# 卸载本地 Extension
+spaceflow uninstall @spaceflow/review
+
+# 卸载全局 Extension
+spaceflow uninstall @spaceflow/review -g
+```

docs/guide/commands/update.md

@@ -0,0 +1,44 @@
+# update — 更新依赖
+
+更新已安装的 Extension 或 CLI 自身。
+
+## 基本用法
+
+```bash
+# 更新所有已安装的 Extension
+spaceflow update
+
+# 更新指定 Extension
+spaceflow update @spaceflow/review
+
+# 更新 CLI 自身
+spaceflow update --self
+```
+
+## 更新策略
+
+| 类型 | 行为 |
+|------|------|
+| npm 包 | 获取最新版本并安装 |
+| git 仓库 | 拉取最新代码 |
+| `--self` | 更新 `spaceflow` CLI 到最新版本 |
+
+## 命令行选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--self` | | 更新 CLI 自身 |
+| `--verbose` | `-v` | 详细日志 |
+
+## 示例
+
+```bash
+# 更新所有依赖
+spaceflow update
+
+# 仅更新 review Extension
+spaceflow update @spaceflow/review
+
+# 更新 spaceflow CLI
+spaceflow update --self
+```

docs/guide/configuration.md

@@ -0,0 +1,163 @@
+# 配置文件
+
+Spaceflow 使用 `spaceflow.json` 作为项目配置文件，统一存放在 `.spaceflow/` 目录下。也支持 `.spaceflowrc` 格式的 RC 文件。
+
+## 配置文件位置
+
+按以下优先级查找配置文件（从低到高，后者覆盖前者）：
+
+1. `~/.spaceflow/spaceflow.json`（全局配置）
+2. `~/.spaceflowrc`（全局 RC 文件）
+3. `.spaceflow/spaceflow.json`（项目配置）
+4. `.spaceflowrc`（项目 RC 文件，最高优先级）
+
+## 基本结构
+
+```json
+{
+  "$schema": "./.spaceflow/config-schema.json",
+  "review": { ... },
+  "publish": { ... },
+  "dependencies": { ... },
+  "support": ["claudeCode"]
+}
+```
+
+## 配置项
+
+### `review`
+
+AI 代码审查相关配置。
+
+```json
+{
+  "review": {
+    "references": ["./references"],
+    "includes": ["*/**/*.ts", "!*/**/*.spec.*", "!*/**/*.config.*"],
+    "generateDescription": true,
+    "autoUpdatePrTitle": true,
+    "lineComments": true,
+    "verifyFixes": true,
+    "analyzeDeletions": false,
+    "deletionAnalysisMode": "open-code",
+    "concurrency": 10,
+    "retries": 3,
+    "retryDelay": 1000
+  }
+}
+```
+
+| 字段                  | 类型       | 默认值       | 说明                                         |
+| --------------------- | ---------- | ------------ | -------------------------------------------- |
+| `references`          | `string[]` | `[]`         | 审查规范文件目录，支持本地路径和远程仓库 URL |
+| `includes`            | `string[]` | `["*/**/*"]` | 审查文件匹配模式（glob）                     |
+| `generateDescription` | `boolean`  | `false`      | 是否自动生成 PR 描述                         |
+| `autoUpdatePrTitle`   | `boolean`  | `false`      | 是否自动更新 PR 标题                         |
+| `lineComments`        | `boolean`  | `true`       | 是否生成行内评论                             |
+| `verifyFixes`         | `boolean`  | `false`      | 是否验证修复建议                             |
+| `analyzeDeletions`    | `boolean`  | `false`      | 是否分析删除代码的影响                       |
+| `concurrency`         | `number`   | `10`         | 并发审查文件数                               |
+| `retries`             | `number`   | `3`          | 失败重试次数                                 |
+| `retryDelay`          | `number`   | `1000`       | 重试间隔（毫秒）                             |
+
+### `publish`
+
+版本发布相关配置，基于 [release-it](https://github.com/release-it/release-it)。
+
+```json
+{
+  "publish": {
+    "monorepo": { "enabled": true, "propagateDeps": true },
+    "changelog": {
+      "preset": {
+        "type": [
+          { "type": "feat", "section": "新特性" },
+          { "type": "fix", "section": "修复BUG" },
+          { "type": "perf", "section": "性能优化" },
+          { "type": "refactor", "section": "代码重构" }
+        ]
+      }
+    },
+    "npm": {
+      "publish": true,
+      "packageManager": "pnpm",
+      "tag": "latest"
+    },
+    "git": {
+      "pushWhitelistUsernames": ["github-actions[bot]"]
+    }
+  }
+}
+```
+
+### `dependencies`
+
+已安装的外部 Extension 注册表。由 `spaceflow install` 命令自动管理。
+
+```json
+{
+  "dependencies": {
+    "@spaceflow/review": "link:./commands/review",
+    "@spaceflow/publish": "link:./commands/publish",
+    "@spaceflow/ci-shell": "link:./commands/ci-shell"
+  }
+}
+```
+
+支持的值格式：
+
+| 格式            | 类型     | 示例                                    |
+| --------------- | -------- | --------------------------------------- |
+| `link:./path`   | 本地链接 | `link:./commands/review`                |
+| `^1.0.0`        | npm 版本 | `^1.0.0`                                |
+| `git+ssh://...` | Git 仓库 | `git+ssh://git@github.com/org/repo.git` |
+
+### `support`
+
+配置需要关联的 AI 编辑器。安装 Extension 时，会在对应编辑器目录下创建符号链接。
+
+```json
+{
+  "support": ["claudeCode", "windsurf", "cursor"]
+}
+```
+
+| 值           | 编辑器目录   |
+| ------------ | ------------ |
+| `claudeCode` | `.claude/`   |
+| `windsurf`   | `.windsurf/` |
+| `cursor`     | `.cursor/`   |
+| `opencode`   | `.opencode/` |
+
+### `lang`
+
+界面语言设置。
+
+```json
+{
+  "lang": "zh-CN"
+}
+```
+
+## 配置优先级
+
+1. **命令行参数**（最高优先级）
+2. **环境变量**
+3. **`spaceflow.json` 配置**
+4. **Extension 默认值**（最低优先级）
+
+## JSON Schema
+
+运行以下命令生成配置的 JSON Schema，获得编辑器自动补全支持：
+
+```bash
+spaceflow schema
+```
+
+生成的 Schema 文件位于 `.spaceflow/config-schema.json`，在配置文件中通过 `$schema` 字段引用：
+
+```json
+{
+  "$schema": "./.spaceflow/config-schema.json"
+}
+```

docs/guide/editor-integration.md

@@ -0,0 +1,96 @@
+# 编辑器集成
+
+Spaceflow 支持将 Extension 的资源自动关联到多个 AI 编程工具的配置目录中。
+
+## 支持的编辑器
+
+| 编辑器      | 配置目录     | 配置值       |
+| ----------- | ------------ | ------------ |
+| Claude Code | `.claude/`   | `claudeCode` |
+| Windsurf    | `.windsurf/` | `windsurf`   |
+| Cursor      | `.cursor/`   | `cursor`     |
+| OpenCode    | `.opencode/` | `opencode`   |
+
+## 配置
+
+在 `spaceflow.json` 中通过 `support` 字段指定需要关联的编辑器：
+
+```json
+{
+  "support": ["claudeCode", "windsurf", "cursor"]
+}
+```
+
+默认值为 `["claudeCode"]`。
+
+## Extension 的四种导出类型
+
+Extension 在 `package.json` 的 `exports` 中声明导出类型，Spaceflow 根据类型执行不同的关联操作：
+
+| 类型       | 说明                     | 关联行为                                           |
+| ---------- | ------------------------ | -------------------------------------------------- |
+| `flows`    | CLI 子命令               | 不关联到编辑器目录，仅注册为 `spaceflow <command>` |
+| `skills`   | 技能文件（`.md` 规范等） | **复制**到编辑器的 `skills/` 目录                  |
+| `commands` | 编辑器命令               | 生成 `.md` 文件到编辑器的 `commands/` 目录         |
+| `mcps`     | MCP Server               | 注册到编辑器的 `mcp.json` 配置                     |
+
+## 自动关联逻辑
+
+当你运行 `spaceflow install` 时，系统会：
+
+1. 通过 `pnpm add` 将 Extension 安装到 `.spaceflow/node_modules/`
+2. 读取 Extension 的 `package.json` 中的导出配置
+3. 根据 `support` 配置，将资源关联到对应编辑器目录：
+   - **skills** — 将文件**复制**到 `.claude/skills/`、`.windsurf/skills/` 等目录
+   - **commands** — 生成 `.md` 命令文件到 `.claude/commands/` 等目录
+   - **mcps** — 将 MCP Server 配置写入 `.claude/mcp.json` 等文件
+4. 自动更新编辑器目录的 `.gitignore`，避免生成文件被提交
+
+全局安装（`-g`）时，关联到家目录下的对应编辑器目录（如 `~/.claude/`）。
+
+## 目录结构示例
+
+配置 `support: ["claudeCode", "windsurf"]` 后，安装一个包含 skills 和 mcps 的 Extension 会生成如下结构：
+
+```text
+project/
+├── .claude/
+│   ├── skills/
+│   │   └── review-spec/          # 从 .spaceflow/node_modules/ 复制
+│   │       ├── js&ts.nest.md
+│   │       └── vue.base.md
+│   └── mcp.json                  # 自动注册 MCP Server
+├── .windsurf/
+│   ├── skills/
+│   │   └── review-spec/          # 从 .spaceflow/node_modules/ 复制
+│   │       ├── js&ts.nest.md
+│   │       └── vue.base.md
+│   └── mcp.json
+└── .spaceflow/
+    ├── node_modules/              # 所有 Extension 的安装位置
+    │   └── @spaceflow/review/
+    ├── package.json
+    └── spaceflow.json
+```
+
+## MCP Server 注册
+
+当 Extension 声明了 `mcps` 导出时，`spaceflow install` 会自动将其注册到编辑器的 `mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "my-mcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/.spaceflow/node_modules/my-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+如果 Extension 声明了需要的环境变量，会在 `env` 中生成占位符供用户填写。
+
+## 清理与卸载
+
+- `spaceflow uninstall <name>` — 删除编辑器目录中对应的 skills/commands 文件
+- `spaceflow clear` — 清理所有编辑器目录中的 skills 和 commands

docs/guide/extension-system.md

@@ -0,0 +1,103 @@
+# Extension 系统
+
+Spaceflow 的所有功能命令都以 Extension 形式组织。Extension 分为**内置命令**和**外部 Extension** 两类。
+
+## Extension 类型
+
+### 内置命令
+
+内置在 `@spaceflow/cli` 中，无需安装即可使用：
+
+| 命令 | 说明 |
+|------|------|
+| `install` | 安装 Extension |
+| `uninstall` | 卸载 Extension |
+| `update` | 更新 Extension |
+| `build` | 构建 Extension |
+| `dev` | 开发模式 |
+| `create` | 创建 Extension 模板 |
+| `list` | 列出已安装 Extension |
+| `clear` | 清理缓存 |
+| `commit` | Git 提交辅助 |
+| `setup` | 编辑器配置 |
+| `schema` | 生成 JSON Schema |
+| `mcp` | MCP 服务 |
+| `runx` | 运行外部命令 |
+
+### 外部 Extension
+
+独立的 npm 包，需要通过 `spaceflow install` 安装：
+
+| Extension | 包名 | 说明 |
+|-----------|------|------|
+| review | `@spaceflow/review` | AI 代码审查 |
+| publish | `@spaceflow/publish` | 版本发布 |
+| ci-scripts | `@spaceflow/ci-scripts` | 自定义脚本执行 |
+| ci-shell | `@spaceflow/ci-shell` | Shell 命令执行 |
+| period-summary | `@spaceflow/period-summary` | 周期总结 |
+
+## Extension 生命周期
+
+```text
+install → 注册到 spaceflow.json → CLI 启动时加载 → 注入 NestJS 模块 → 可用
+```
+
+1. **安装** — `spaceflow install <package>` 下载并注册
+2. **注册** — 写入 `spaceflow.json` 的 `dependencies` 字段
+3. **加载** — CLI 启动时，`ExtensionLoaderService` 扫描并加载所有已注册 Extension
+4. **注入** — Extension 的 NestJS Module 被动态注入到 CLI 应用中
+5. **执行** — 用户通过 `spaceflow <command>` 调用
+
+## Extension 接口
+
+每个 Extension 必须实现 `SpaceflowExtension` 接口：
+
+```typescript
+import type { SpaceflowExtension, SpaceflowExtensionMetadata } from "@spaceflow/core";
+
+export class ReviewExtension implements SpaceflowExtension {
+  getMetadata(): SpaceflowExtensionMetadata {
+    return {
+      name: "review",
+      commands: ["review"],
+      configKey: "review",
+      description: "AI 代码审查",
+    };
+  }
+
+  getModule() {
+    return ReviewModule;
+  }
+}
+```
+
+### SpaceflowExtensionMetadata
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | `string` | ✅ | Extension 名称 |
+| `commands` | `string[]` | ✅ | 提供的命令列表 |
+| `configKey` | `string` | ❌ | 对应 `spaceflow.json` 中的配置 key |
+| `description` | `string` | ❌ | Extension 描述 |
+| `version` | `string` | ❌ | 版本号 |
+| `locales` | `Record<string, Record<string, string>>` | ❌ | i18n 语言资源 |
+
+## 管理命令
+
+```bash
+# 安装
+spaceflow install @spaceflow/review
+
+# 卸载
+spaceflow uninstall review
+
+# 更新
+spaceflow update
+
+# 列出
+spaceflow list
+```
+
+## 开发 Extension
+
+请参考 [插件开发指南](/advanced/plugin-development) 了解如何创建自定义 Extension。

docs/guide/getting-started.md

@@ -0,0 +1,121 @@
+# 快速开始
+
+## 安装
+
+### 全局安装
+
+```bash
+npm install -g @spaceflow/cli
+# 或
+pnpm add -g @spaceflow/cli
+```
+
+安装完成后，你可以通过 `spaceflow` 或简写 `space` 来调用命令。
+
+### 验证安装
+
+```bash
+spaceflow --help
+```
+
+## 初始化项目
+
+运行 `spaceflow setup` 初始化项目，或手动创建 `.spaceflow/spaceflow.json` 配置文件：
+
+```json
+{
+  "review": {
+    "references": ["./references"],
+    "includes": ["*/**/*.ts", "!*/**/*.spec.*"],
+    "generateDescription": true,
+    "lineComments": true,
+    "concurrency": 10
+  },
+  "support": ["claudeCode"]
+}
+```
+
+## 安装 Extension
+
+使用 `install` 命令安装外部 Extension：
+
+```bash
+# 安装 review Extension
+spaceflow install @spaceflow/review
+
+# 安装 publish Extension
+spaceflow install @spaceflow/publish
+```
+
+安装后，Extension 会被注册到 `spaceflow.json` 的 `dependencies` 字段中。
+
+## 常用命令
+
+### 代码审查
+
+```bash
+# 审查指定 PR
+spaceflow review -p 123
+
+# 审查两个分支之间的差异
+spaceflow review -b main --head feature/xxx
+
+# 使用指定 LLM 模式
+spaceflow review -p 123 -l openai
+```
+
+### 版本发布
+
+```bash
+# 发布版本
+spaceflow publish
+
+# 试运行（不实际发布）
+spaceflow publish --dry-run
+```
+
+### 查看已安装的 Extension
+
+```bash
+spaceflow list
+```
+
+### 构建 Extension
+
+```bash
+# 构建所有 Extension
+spaceflow build
+
+# 监听模式
+spaceflow build --watch
+```
+
+## 在 CI 中使用
+
+Spaceflow 提供了预配置的 GitHub Actions，可以在 PR 中自动执行代码审查：
+
+```yaml
+# .github/workflows/pr-review.yml
+name: PR Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: nicepkg/spaceflow/actions@main
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          command: review
+```
+
+详细的 CI 配置请参考 [GitHub Actions](/advanced/github-actions)。
+
+## 下一步
+
+- 了解 [项目结构](/guide/project-structure)
+- 配置 [spaceflow.json](/guide/configuration)
+- 探索 [Extension 系统](/guide/extension-system)

docs/guide/introduction.md

@@ -0,0 +1,45 @@
+# 简介
+
+## 什么是 Spaceflow？
+
+Spaceflow 是一个**可扩展的 AI 工作流引擎**，为团队提供统一的 CI/CD 管理和 AI 代码审查能力。它基于 NestJS + nest-commander 构建，采用插件化架构，命令以 Extension 形式分发和管理。
+
+## 核心特性
+
+- **AI 代码审查** — 基于 LLM 的自动化代码审查，支持 OpenAI、Claude 等多种模型
+- **Extension 插件系统** — 命令以插件包形式分发，支持 npm 包和本地链接
+- **多编辑器集成** — 自动将技能关联到 Claude Code、Windsurf、Cursor 等 AI 编程工具
+- **CI/CD 自动化** — 预配置 GitHub Actions，支持自动 PR 审查、版本发布
+- **国际化** — 基于 i18next，每个 Extension 自管理翻译资源
+
+## 技术栈
+
+| 技术 | 用途 |
+|------|------|
+| [NestJS](https://nestjs.com/) | 核心框架，依赖注入和模块化 |
+| [nest-commander](https://docs.nestjs.com/recipes/nest-commander) | CLI 命令系统 |
+| [Rspack](https://rspack.dev/) | 构建打包 |
+| [i18next](https://www.i18next.com/) | 国际化 |
+| [Zod](https://zod.dev/) | 配置校验 |
+| [pnpm](https://pnpm.io/) | 包管理（Monorepo） |
+
+## 包结构
+
+Spaceflow 采用 Monorepo 结构，主要包含以下包：
+
+| 包名 | 说明 |
+|------|------|
+| `@spaceflow/core` | 核心能力库，提供 Git Provider、LLM Proxy、Logger 等基础模块 |
+| `@spaceflow/cli` | CLI 入口，包含所有内置命令 |
+| `@spaceflow/review` | AI 代码审查 Extension |
+| `@spaceflow/publish` | 版本发布 Extension |
+| `@spaceflow/ci-scripts` | 自定义脚本执行 Extension |
+| `@spaceflow/ci-shell` | Shell 命令执行 Extension |
+| `@spaceflow/period-summary` | 周期总结 Extension |
+
+## 适用场景
+
+- 需要在 CI 中集成 AI 代码审查的团队
+- 需要统一管理多个仓库 CI/CD 流程的组织
+- 希望将 AI 编程工具的技能和规范标准化分发的团队
+- 需要自动化版本发布和变更日志生成的项目

docs/guide/project-structure.md

@@ -0,0 +1,102 @@
+# 项目结构
+
+Spaceflow 采用 pnpm Monorepo 结构，以下是主要目录说明。
+
+## 目录概览
+
+```text
+spaceflow/
+├── core/                  # @spaceflow/core — 核心能力库
+│   └── src/
+│       ├── config/        # 配置加载与校验
+│       ├── extension-system/  # Extension 加载系统
+│       └── shared/        # 共享模块
+│           ├── git-provider/  # Git 平台适配器（GitHub / Gitea）
+│           ├── git-sdk/       # Git 命令封装
+│           ├── llm-proxy/     # 多 LLM 统一代理
+│           ├── feishu-sdk/    # 飞书 SDK
+│           ├── logger/        # 日志系统（Plain / TUI）
+│           ├── i18n/          # 国际化
+│           ├── storage/       # 本地存储
+│           ├── parallel/      # 并行执行工具
+│           └── ...
+│
+├── cli/                   # @spaceflow/cli — CLI 入口
+│   └── src/
+│       ├── commands/      # 内置命令
+│       │   ├── install/   # 安装 Extension
+│       │   ├── uninstall/ # 卸载 Extension
+│       │   ├── build/     # 构建 Extension
+│       │   ├── dev/       # 开发模式
+│       │   ├── create/    # 创建 Extension 模板
+│       │   ├── list/      # 列出已安装 Extension
+│       │   ├── commit/    # Git 提交辅助
+│       │   ├── setup/     # 编辑器配置
+│       │   ├── schema/    # JSON Schema 生成
+│       │   ├── mcp/       # MCP 服务
+│       │   ├── runx/      # 运行外部命令
+│       │   ├── update/    # 更新 Extension
+│       │   └── clear/     # 清理缓存
+│       ├── extension-loader/  # Extension 加载器
+│       └── locales/       # CLI i18n 资源
+│
+├── commands/              # 外部 Extension（独立 npm 包）
+│   ├── review/            # @spaceflow/review — AI 代码审查
+│   ├── publish/           # @spaceflow/publish — 版本发布
+│   ├── ci-scripts/        # @spaceflow/ci-scripts — 脚本执行
+│   ├── ci-shell/          # @spaceflow/ci-shell — Shell 执行
+│   └── period-summary/    # @spaceflow/period-summary — 周期总结
+│
+├── actions/               # GitHub Actions
+│   ├── src/
+│   └── action.yml
+│
+├── references/            # 代码审查规范文件
+│   ├── js&ts.base.md
+│   ├── js&ts.nest.md
+│   └── ...
+│
+├── templates/             # Extension 模板
+│   ├── command/           # 命令型 Extension 模板
+│   └── skills/            # 技能型 Extension 模板
+│
+├── .spaceflow/            # Spaceflow 工作目录
+│   ├── spaceflow.json     # 项目配置
+│   └── package.json       # Extension 依赖管理
+│
+├── pnpm-workspace.yaml    # pnpm Monorepo 配置
+└── package.json           # 根 package.json
+```
+
+## 核心包
+
+### `@spaceflow/core`
+
+核心能力库，提供所有 Extension 共享的基础模块。作为 npm 包发布，Extension 通过 `peerDependencies` 依赖它。
+
+主要导出：
+
+- **Git Provider** — GitHub / Gitea 平台适配器
+- **Git SDK** — Git 命令封装
+- **LLM Proxy** — 多 LLM 统一代理（OpenAI、Claude 等）
+- **Logger** — 日志系统（Plain 模式 + TUI 模式）
+- **i18n** — 国际化工具函数
+- **Config** — 配置加载与校验
+- **Extension System** — Extension 接口定义
+
+### `@spaceflow/cli`
+
+CLI 入口包，包含所有内置命令和 Extension 加载器。通过 `bin` 字段注册 `spaceflow` 和 `space` 两个命令。
+
+### 外部 Extension
+
+位于 `commands/` 目录下，每个 Extension 是独立的 npm 包，拥有自己的 `package.json`、构建配置和测试。
+
+## 配置文件
+
+| 文件 | 说明 |
+|------|------|
+| `spaceflow.json` / `.spaceflow/spaceflow.json` | 项目配置 |
+| `.spaceflow/package.json` | Extension 依赖管理 |
+| `pnpm-workspace.yaml` | Monorepo 工作区配置 |
+| `references/*.md` | 代码审查规范文件 |

docs/index.md

@@ -0,0 +1,35 @@
+---
+layout: home
+
+hero:
+  name: Spaceflow
+  text: 可扩展的 AI 工作流引擎
+  tagline: 统一 CI/CD 管理、AI 代码审查、多编辑器插件分发
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /guide/getting-started
+    - theme: alt
+      text: 查看 GitHub
+      link: https://github.com/nicepkg/spaceflow
+
+features:
+  - icon: 🤖
+    title: AI 代码审查
+    details: 基于 LLM 的自动化代码审查，支持 OpenAI、Claude 等多种模型，自动生成行内评论和 PR 描述。
+  - icon: 🔌
+    title: Extension 插件系统
+    details: 命令以 Extension 形式分发，支持 npm 包和本地链接，通过 spaceflow.json 统一管理。
+  - icon: 🛠️
+    title: 丰富的内置命令
+    details: 提供 install、build、dev、commit、review、publish 等开箱即用的命令。
+  - icon: 🖥️
+    title: 多编辑器集成
+    details: 一键将技能和命令关联到 Claude Code、Windsurf、Cursor、OpenCode 等 AI 编程工具。
+  - icon: 📦
+    title: CI/CD 自动化
+    details: 预配置 GitHub Actions 工作流，支持自动 PR 审查、版本发布、自定义脚本执行。
+  - icon: 🌐
+    title: 国际化支持
+    details: 基于 i18next 的完整 i18n 方案，每个 Extension 自管理翻译资源，默认中文。
+---

docs/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@spaceflow/docs",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.3",
+    "vue": "^3.5.13"
+  }
+}

docs/reference/cli.md

@@ -0,0 +1,185 @@
+# CLI 命令参考
+
+所有 Spaceflow CLI 命令的完整参考。
+
+## 全局选项
+
+| 选项 | 简写 | 说明 |
+|------|------|------|
+| `--help` | `-h` | 显示帮助信息 |
+| `--version` | `-V` | 显示版本号 |
+| `--verbose` | `-v` | 详细日志（`-v` 基本日志，`-vv` 详细日志） |
+| `--dry-run` | | 试运行，不实际执行 |
+| `--ci` | | CI 模式 |
+
+## 内置命令
+
+### `install`
+
+安装 Extension。
+
+```bash
+spaceflow install <package>        # 安装指定 Extension
+spaceflow install                  # 安装 spaceflow.json 中所有 dependencies
+spaceflow install <package> -g     # 全局安装
+```
+
+### `uninstall`
+
+卸载 Extension。
+
+```bash
+spaceflow uninstall <name>
+```
+
+### `update`
+
+更新已安装的 Extension。
+
+```bash
+spaceflow update                   # 更新所有
+spaceflow update <name>            # 更新指定 Extension
+```
+
+### `list`
+
+列出已安装的 Extension。
+
+```bash
+spaceflow list
+```
+
+输出示例：
+
+```text
+已安装的 Extension:
+
+  review        @spaceflow/review          [link]
+    命令: review
+
+  publish       @spaceflow/publish         [link]
+    命令: publish
+```
+
+### `build`
+
+构建 Extension。
+
+```bash
+spaceflow build                    # 构建所有
+spaceflow build --watch            # 监听模式
+spaceflow build <name>             # 构建指定 Extension
+```
+
+### `dev`
+
+开发模式，监听文件变化并自动重新构建。
+
+```bash
+spaceflow dev
+spaceflow dev <name>
+```
+
+### `create`
+
+创建新的 Extension 模板。
+
+```bash
+spaceflow create <name>            # 创建命令型 Extension
+spaceflow create <name> --skill    # 创建技能型 Extension
+```
+
+### `commit`
+
+Git 提交辅助，基于 Conventional Commits 规范。
+
+```bash
+spaceflow commit
+```
+
+### `setup`
+
+同步编辑器配置。
+
+```bash
+spaceflow setup                    # 同步所有已配置编辑器
+```
+
+### `schema`
+
+生成 `spaceflow.json` 的 JSON Schema。
+
+```bash
+spaceflow schema
+```
+
+### `mcp`
+
+启动 MCP（Model Context Protocol）服务。
+
+```bash
+spaceflow mcp
+```
+
+### `runx`
+
+运行外部命令，透传参数。
+
+```bash
+spaceflow runx <source> -- <args>
+# 简写
+spaceflow x <source> -- <args>
+```
+
+### `clear`
+
+清理缓存和临时文件。
+
+```bash
+spaceflow clear
+```
+
+## 外部命令
+
+以下命令需要先安装对应的 Extension。
+
+### `review`
+
+AI 代码审查。详见 [review 命令](/guide/commands/review)。
+
+```bash
+spaceflow review -p <pr-number> [-l <llm-mode>]
+spaceflow review -b <base> --head <head> [-l <llm-mode>]
+```
+
+### `publish`
+
+版本发布。详见 [publish 命令](/guide/commands/publish)。
+
+```bash
+spaceflow publish [--dry-run]
+```
+
+### `ci-scripts`
+
+脚本执行。详见 [ci-scripts 命令](/guide/commands/ci-scripts)。
+
+```bash
+spaceflow ci-scripts --script <path>
+```
+
+### `ci-shell`
+
+Shell 执行。详见 [ci-shell 命令](/guide/commands/ci-shell)。
+
+```bash
+spaceflow ci-shell --command <cmd>
+```
+
+### `period-summary`
+
+周期总结。详见 [period-summary 命令](/guide/commands/period-summary)。
+
+```bash
+spaceflow period-summary --period <week|month>
+```

docs/reference/config.md

@@ -0,0 +1,150 @@
+# 配置参考
+
+`spaceflow.json` 完整配置项参考。
+
+## 配置文件位置
+
+按优先级从低到高排列，后者覆盖前者：
+
+| 优先级    | 路径                          | 说明         |
+| --------- | ----------------------------- | ------------ |
+| 1（最低） | `~/.spaceflow/spaceflow.json` | 全局配置     |
+| 2         | `~/.spaceflowrc`              | 全局 RC 文件 |
+| 3         | `.spaceflow/spaceflow.json`   | 项目配置     |
+| 4（最高） | `.spaceflowrc`                | 项目 RC 文件 |
+
+## 完整配置示例
+
+```json
+{
+  "$schema": "./.spaceflow/config-schema.json",
+  "lang": "zh-CN",
+  "support": ["claudeCode", "windsurf", "cursor"],
+  "review": {
+    "references": ["./references", "https://github.com/org/review-spec"],
+    "includes": ["*/**/*.ts", "!*/**/*.spec.*", "!*/**/*.config.*"],
+    "generateDescription": true,
+    "autoUpdatePrTitle": true,
+    "lineComments": true,
+    "verifyFixes": true,
+    "analyzeDeletions": false,
+    "deletionAnalysisMode": "open-code",
+    "concurrency": 10,
+    "retries": 3,
+    "retryDelay": 1000
+  },
+  "publish": {
+    "monorepo": { "enabled": true, "propagateDeps": true },
+    "changelog": {
+      "preset": {
+        "type": [
+          { "type": "feat", "section": "新特性" },
+          { "type": "fix", "section": "修复BUG" },
+          { "type": "perf", "section": "性能优化" },
+          { "type": "refactor", "section": "代码重构" },
+          { "type": "docs", "section": "文档更新" },
+          { "type": "style", "section": "代码格式" },
+          { "type": "test", "section": "测试用例" },
+          { "type": "chore", "section": "其他修改" }
+        ]
+      }
+    },
+    "npm": {
+      "publish": true,
+      "packageManager": "pnpm",
+      "tag": "latest",
+      "ignoreVersion": true,
+      "versionArgs": ["--workspaces false"]
+    },
+    "git": {
+      "pushWhitelistUsernames": ["github-actions[bot]"]
+    }
+  },
+  "dependencies": {
+    "@spaceflow/review": "link:./commands/review",
+    "@spaceflow/publish": "link:./commands/publish",
+    "@spaceflow/ci-shell": "link:./commands/ci-shell",
+    "@spaceflow/ci-scripts": "link:./commands/ci-scripts"
+  }
+}
+```
+
+## 顶层字段
+
+### `$schema`
+
+- **类型**：`string`
+- **说明**：JSON Schema 路径，用于编辑器自动补全
+- **示例**：`"./.spaceflow/config-schema.json"`
+
+### `lang`
+
+- **类型**：`string`
+- **默认值**：`"zh-CN"`
+- **说明**：界面语言。支持 `zh-CN`、`en`
+
+### `support`
+
+- **类型**：`string[]`
+- **默认值**：`["claudeCode"]`
+- **说明**：需要关联的 AI 编辑器列表
+- **可选值**：`"claudeCode"` | `"windsurf"` | `"cursor"` | `"opencode"`
+
+### `dependencies`
+
+- **类型**：`Record<string, string>`
+- **说明**：已安装的外部 Extension 注册表，由 `spaceflow install` 自动管理
+
+## review 配置
+
+| 字段                   | 类型       | 默认值        | 说明                                   |
+| ---------------------- | ---------- | ------------- | -------------------------------------- |
+| `references`           | `string[]` | `[]`          | 审查规范来源（本地目录或远程仓库 URL） |
+| `includes`             | `string[]` | `["*/**/*"]`  | 审查文件匹配模式（glob）               |
+| `generateDescription`  | `boolean`  | `false`       | 自动生成 PR 描述                       |
+| `autoUpdatePrTitle`    | `boolean`  | `false`       | 自动更新 PR 标题                       |
+| `lineComments`         | `boolean`  | `true`        | 生成行内评论                           |
+| `verifyFixes`          | `boolean`  | `false`       | 验证修复建议                           |
+| `analyzeDeletions`     | `boolean`  | `false`       | 分析删除代码影响                       |
+| `deletionAnalysisMode` | `string`   | `"open-code"` | 删除分析模式                           |
+| `concurrency`          | `number`   | `10`          | 并发审查文件数                         |
+| `retries`              | `number`   | `3`           | 失败重试次数                           |
+| `retryDelay`           | `number`   | `1000`        | 重试间隔（毫秒）                       |
+
+### `references` 支持的格式
+
+| 格式        | 示例                                                 |
+| ----------- | ---------------------------------------------------- |
+| 本地目录    | `"./references"`                                     |
+| GitHub 仓库 | `"https://github.com/org/review-spec"`               |
+| GitHub 目录 | `"https://github.com/org/repo/tree/main/references"` |
+| Gitea 仓库  | `"https://git.example.com/org/review-spec"`          |
+| SSH         | `"git+ssh://git@github.com/org/repo.git"`            |
+
+## publish 配置
+
+### `publish.monorepo`
+
+| 字段            | 类型      | 默认值  | 说明               |
+| --------------- | --------- | ------- | ------------------ |
+| `enabled`       | `boolean` | `false` | 启用 Monorepo 模式 |
+| `propagateDeps` | `boolean` | `false` | 传播依赖版本更新   |
+
+### `publish.changelog`
+
+变更日志配置，基于 [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)。
+
+### `publish.npm`
+
+| 字段             | 类型      | 默认值     | 说明           |
+| ---------------- | --------- | ---------- | -------------- |
+| `publish`        | `boolean` | `true`     | 是否发布到 npm |
+| `packageManager` | `string`  | `"pnpm"`   | 包管理器       |
+| `tag`            | `string`  | `"latest"` | npm tag        |
+| `ignoreVersion`  | `boolean` | `false`    | 忽略版本检查   |
+
+### `publish.git`
+
+| 字段                     | 类型       | 说明                   |
+| ------------------------ | ---------- | ---------------------- |
+| `pushWhitelistUsernames` | `string[]` | 允许推送的用户名白名单 |

docs/reference/env-variables.md

@@ -0,0 +1,94 @@
+# 环境变量
+
+Spaceflow 使用的所有环境变量参考。
+
+## 通用
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `SPACEFLOW_LANG` | 界面语言 | `zh-CN` |
+| `CI` | 是否在 CI 环境中运行 | — |
+
+## Git Provider
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `GIT_PROVIDER_TYPE` | Git 平台类型（`github` / `gitea`） | 自动检测 |
+| `GITHUB_TOKEN` | GitHub API Token | — |
+| `GITHUB_SERVER_URL` | GitHub Server URL | `https://github.com` |
+| `GITEA_TOKEN` | Gitea API Token（向后兼容） | — |
+| `GITEA_SERVER_URL` | Gitea Server URL | — |
+
+::: tip 自动检测逻辑
+- 提供 `GITHUB_TOKEN` → 识别为 `github`
+- 提供 `GITEA_TOKEN` → 识别为 `gitea`
+- 都未提供 → 默认 `github`
+- 可通过 `GIT_PROVIDER_TYPE` 显式覆盖
+:::
+
+## LLM 配置
+
+### OpenAI
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `OPENAI_API_KEY` | OpenAI API Key | — |
+| `OPENAI_BASE_URL` | OpenAI API Base URL | `https://api.openai.com/v1` |
+| `OPENAI_MODEL` | 模型名称 | `gpt-4o` |
+
+### Claude
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `ANTHROPIC_API_KEY` | Anthropic API Key | — |
+
+### Claude Code
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `CLAUDE_CODE_BASE_URL` | Claude Code Agent Base URL | — |
+| `CLAUDE_CODE_AUTH_TOKEN` | Claude Code Auth Token | — |
+| `CLAUDE_CODE_MODEL` | 模型名称 | `ark-code-latest` |
+
+### OpenCode
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `OPENCODE_API_KEY` | OpenCode API Key | — |
+
+## 飞书
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `FEISHU_APP_ID` | 飞书应用 App ID | — |
+| `FEISHU_APP_SECRET` | 飞书应用 App Secret | — |
+
+## GitHub Actions
+
+在 GitHub Actions 中使用时，以下变量会自动注入：
+
+| 变量 | 说明 |
+|------|------|
+| `GITHUB_TOKEN` | GitHub 自动注入的 Token |
+| `GITHUB_SERVER_URL` | GitHub Server URL |
+| `GITHUB_REPOSITORY` | 仓库全名（`owner/repo`） |
+| `GITHUB_EVENT_NAME` | 事件类型 |
+| `GITHUB_REF` | 触发分支/标签 |
+
+## 使用示例
+
+### 本地开发
+
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+export OPENAI_API_KEY=sk-xxxxxxxxxxxx
+spaceflow review -p 123
+```
+
+### CI 环境
+
+```yaml
+env:
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```

docs/reference/review-spec.md

@@ -0,0 +1,215 @@
+# Review Spec 规范
+
+Review Spec 是 Spaceflow 中用于定义代码审查规则的 Markdown 格式文档。AI 审查系统会读取这些规范，并据此对代码进行自动化审查。
+
+## 文件命名规则
+
+规范文件名必须遵循以下格式：
+
+```text
+<扩展名>.<类型>.md
+```
+
+| 部分 | 说明 | 示例 |
+|------|------|------|
+| 扩展名 | 适用的文件扩展名，多个用 `&` 连接 | `js&ts`, `vue`, `tsx` |
+| 类型 | 规范类型，可多级，用 `.` 分隔 | `nest`, `test-code`, `file-name` |
+| 后缀 | 必须是 `.md` | `.md` |
+
+示例：
+
+```text
+js&ts.nest.md           # JS/TS NestJS 项目规范
+js&ts.file-name.md      # JS/TS 文件命名规范
+js&ts.test-code.md      # JS/TS 测试代码规范
+vue.base.md             # Vue 基础规范
+```
+
+## 文件结构
+
+### 文件级配置
+
+位于文件开头，使用 blockquote 语法：
+
+```markdown
+> - includes `*.controller.ts` `*.service.ts`
+> - severity `warn`
+> - override `[JsTs.FileName]`
+```
+
+### 规则定义
+
+使用二级标题定义规则：
+
+````markdown
+## 规则标题 `[规则ID]`
+
+规则描述...
+
+### Good
+
+```typescript
+// 推荐代码示例
+```
+
+### Bad
+
+```typescript
+// 不推荐代码示例
+```
+````
+
+## 文件级配置项
+
+### `includes`
+
+指定规范适用的文件路径模式（glob）。
+
+```markdown
+> - includes `**/*.controller.ts` `**/*.service.ts`
+```
+
+- 支持 `*`（任意字符）和 `**`（任意层级）
+- 多个模式用空格分隔，包裹在反引号中
+
+### `severity`
+
+指定规则的默认严重程度。
+
+```markdown
+> - severity `warn`
+```
+
+| 值 | 含义 | 显示 | 阻止合并 |
+|----|------|------|----------|
+| `error` | 错误 | 🔴 红色 | 通常阻止 |
+| `warn` | 警告 | 🟡 黄色 | 通常不阻止 |
+| `off` | 关闭 | 不显示 | 否 |
+
+### `override`
+
+排除其他规范文件中的规则，支持前缀匹配。
+
+```markdown
+> - override `[JsTs.FileName]`
+```
+
+排除所有以 `JsTs.FileName` 开头的规则（包括 `JsTs.FileName.UpperCamel` 等子规则）。
+
+## 规则级配置
+
+可以在规则内容中使用 blockquote 覆盖文件级配置：
+
+```markdown
+## 服务规范 `[JsTs.Nest.Service]`
+
+服务文件包含业务逻辑...
+
+> - severity `warn`
+```
+
+## 规则 ID 命名
+
+规则 ID 支持多级命名，使用 `.` 分隔：
+
+```markdown
+## 主规则 `[JsTs.Nest]`
+## 控制器规范 `[JsTs.Nest.Controller]`
+## 服务规范 `[JsTs.Nest.Service]`
+```
+
+## 远程规范仓库
+
+支持从 Git 仓库加载规范文件：
+
+```json
+{
+  "review": {
+    "references": [
+      "./references",
+      "https://github.com/your-org/review-spec"
+    ]
+  }
+}
+```
+
+### 支持的 URL 格式
+
+| 格式 | 示例 |
+|------|------|
+| GitHub 仓库 | `https://github.com/org/repo` |
+| GitHub 目录 | `https://github.com/org/repo/tree/main/references` |
+| Gitea 仓库 | `https://git.example.com/org/repo` |
+| Gitea 目录 | `https://git.example.com/org/repo/src/branch/main/references` |
+| SSH | `git@host:owner/repo.git` |
+| SSH（完整） | `git+ssh://git@host/owner/repo.git` |
+
+远程规范会缓存到 `~/.spaceflow/review-spec-cache/`，TTL 为 5 分钟（CI 环境中每次拉取最新）。
+
+## 完整示例
+
+````markdown
+# NestJS 项目规范 `[JsTs.Nest]`
+
+> - includes `*.controller.ts` `*.service.ts` `*.module.ts`
+> - severity `error`
+> - override `[JsTs.FileName]`
+
+## 控制器规范 `[JsTs.Nest.Controller]`
+
+控制器文件不能包含业务逻辑，只能调用 service 方法。
+
+### Good
+
+```typescript
+@Controller("user")
+export class UserController {
+  constructor(private readonly userService: UserService) {}
+
+  @Get()
+  async getUser(@Param("id") id: string) {
+    return this.userService.findById(id);
+  }
+}
+```
+
+### Bad
+
+```typescript
+@Controller("user")
+export class UserController {
+  @Get()
+  async getUser(@Param("id") id: string) {
+    const user = await db.query("SELECT * FROM users WHERE id = ?", [id]);
+    return user;
+  }
+}
+```
+
+## 服务规范 `[JsTs.Nest.Service]`
+
+服务文件包含业务逻辑，必须通过 model 访问数据库。
+
+> - severity `warn`
+
+### Good
+
+```typescript
+@Injectable()
+export class UserService {
+  constructor(private readonly userModel: UserModel) {}
+
+  async getUser(id: string) {
+    return this.userModel.findById(id);
+  }
+}
+```
+````
+
+## 最佳实践
+
+- **规则 ID 命名** — 使用有意义的层级结构，如 `语言.类型.规则名`
+- **代码示例** — 提供清晰的 Good/Bad 示例
+- **严重程度** — 合理设置 severity，避免过多 error 阻塞开发
+- **文件组织** — 按功能或类型组织规则文件，避免单个文件过大
+- **includes 精确** — 使用精确的文件路径匹配，避免误匹配