chore: 初始化仓库

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` | 代码审查规范文件 |