Lydanne/spaceflow
1
0
Fork 0
mirror of https://github.com/Lydanne/spaceflow.git synced 2026-03-09 18:52:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 更新文档以反映新架构和扩展系统重构

Browse Source 
- 将"插件"术语统一改为"扩展"
- 更新项目结构说明，新增 @spaceflow/shared 包
- 调整核心模块文档：移除 NestJS 依赖注入示例，改为直接实例化和 SpaceflowContext 用法
- 更新包列表和内置命令说明
- 调整文档导航结构，将环境变量文档提前
- 更新站点描述为"可扩展的 AI 工程化工作流平台"
- 补充扩展系统支持 npm 包、本地路径和 Git 仓库安装的
This commit is contained in:
Lyda
2026-02-26 19:05:44 +08:00
parent 8ea0f8bebe
commit 828c436bdb
18 changed files with 947 additions and 662 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
README.md
View File

@@ -8,7 +8,7 @@
- **AI 代码审查**：基于 LLM（OpenAI、Claude、Gemini）的自动化 PR 审查，支持行级评论和增量审查
- **自动化发布**：基于 Conventional Commits 的版本管理，支持 Monorepo 拓扑排序发布
- **扩展系统**：通过 NestJS 模块化架构，支持自定义命令扩展
- **扩展系统**：基于 `defineExtension` 的纯函数式扩展体系，支持 npm 包、本地路径和 Git 仓库安装
- **多编辑器集成**：自动关联扩展到 Claude Code、Windsurf、Cursor、OpenCode 等编辑器
- **多平台适配**：支持 GitHub、Gitea、GitLab 等 Git 托管平台
- **CI 流程编排**：分支锁定保护下执行 Shell 命令或 JS 脚本
@@ -32,43 +32,45 @@ pnpm spaceflow install @spaceflow/publish
```text
spaceflow/
├── packages/
│ ├── cli/ # CLI 入口（@spaceflow/cli）
│ └── core/ # 核心能力库（@spaceflow/core）
│ └── src/
│ ├── config/ # 配置管理
│ ├── extension-system/ # 扩展系统
│ ├── locales/ # 国际化资源
│ └── shared/ # 共享模块
│ ├── git-provider/ # Git 平台适配器
│ ├── git-sdk/ # Git 命令封装
│ ├── llm-proxy/ # LLM 统一代理
│ ├── llm-jsonput/ # JSON 结构化输出
│ ├── feishu-sdk/ # 飞书 SDK
│ ├── logger/ # 日志系统（TUI/Plain）
│ ├── parallel/ # 并行执行工具
│ └── storage/ # 通用存储服务
├── extensions/ # 扩展
│ ├── review/ # AI 代码审查（@spaceflow/review）
│ ├── publish/ # 自动化发布（@spaceflow/publish）
│ ├── scripts/ # 脚本执行（@spaceflow/scripts）
│ ├── shell/ # Shell 执行（@spaceflow/shell）
│ └── review-summary/ # 审查统计（@spaceflow/review-summary）
├── actions/ # GitHub Actions
├── docs/ # 文档站点（VitePress）
└── templates/ # 扩展模板
│ ├── cli/ # @spaceflow/cli — CLI 壳子
│ ├── core/ # @spaceflow/core — 核心运行时
│ │ └── src/
│ │ ├── cli-runtime/ # DI 容器、ExtensionLoader、exec() 入口
│ │ ├── commands/ # 13 个内置命令
│ │ ├── config/ # 配置管理
│ │ ├── extension-system/ # 扩展类型定义与 defineExtension
│ │ ├── locales/ # 国际化资源
│ │ └── shared/ # 共享模块
│ │ ├── git-provider/ # Git 平台适配器
│ │ ├── git-sdk/ # Git 命令封装
│ │ ├── llm-proxy/ # LLM 统一代理
│ │ ├── logger/ # 日志系统（TUI/Plain）
│ │ ├── parallel/ # 并行执行工具
│ │ └── storage/ # 通用存储服务
│ └── shared/ # @spaceflow/shared — 公共工具库
├── extensions/ # 扩展
│ ├── review/ # @spaceflow/review — AI 代码审查
│ ├── publish/ # @spaceflow/publish — 自动化发布
│ ├── scripts/ # @spaceflow/scripts — 脚本执行
│ ├── shell/ # @spaceflow/shell — Shell 执行
│ └── review-summary/ # @spaceflow/review-summary — 审查统计
├── actions/ # GitHub Actions
├── docs/ # 文档站点（VitePress）
└── templates/ # 扩展模板（command / mcp / skills）
```
## 包一览
| 包名 | 说明 |
| --------------------------- | ------------------------------------------ |
| `@spaceflow/cli` | CLI 工具，提供 `spaceflow` / `space` 命令 |
| `@spaceflow/core` | 核心能力库，提供共享模块和扩展系统基础设施 |
| `@spaceflow/review` | AI 代码审查扩展 |
| `@spaceflow/publish` | 自动化版本发布扩展 |
| `@spaceflow/scripts` | CI 环境下执行 JS 脚本 |
| `@spaceflow/shell` | CI 环境下执行 Shell 命令 |
| `@spaceflow/review-summary` | PR 贡献审查统计 |
| 包名 | 说明 |
| --------------------------- | ------------------------------------------------------------ |
| `@spaceflow/cli` | CLI 壳子入口，负责引导和启动 |
| `@spaceflow/core` | 核心运行时 + 13 个内置命令 + 共享模块（Git、LLM、Logger 等） |
| `@spaceflow/shared` | 轻量公共工具库，CLI 和 core 共同依赖 |
| `@spaceflow/review` | AI 代码审查扩展 |
| `@spaceflow/publish` | 自动化版本发布扩展 |
| `@spaceflow/scripts` | CI 环境下执行 JS 脚本 |
| `@spaceflow/shell` | CI 环境下执行 Shell 命令 |
| `@spaceflow/review-summary` | PR 贡献审查统计 |
## 内置命令
@@ -79,17 +81,18 @@ spaceflow/
| `build` | 构建扩展 |
| `dev` | 开发模式运行 |
| `create` | 创建新扩展 |
| `update` | 更新扩展 |
| `mcp` | 启动 MCP Server |
| `list` | 列出已安装扩展 |
| `clear` | 清理缓存 |
| `runx` / `x` | 执行扩展命令 |
| `schema` | 生成配置 JSON Schema |
| `commit` | AI 智能提交 |
| `setup` | 初始化项目配置 |
| `mcp` | 启动 MCP Server |
## 配置
在项目根目录创建 `spaceflow.json`：
在项目根目录创建 `.spaceflowrc` 或 `.spaceflow/spaceflow.json`：
```json
{

12
docs/.vitepress/config.ts
View File

@@ -2,7 +2,7 @@ import { defineConfig } from "vitepress";
export default defineConfig({
title: "Spaceflow",
description: "可扩展的 AI 工作流引擎，统一 CI/CD 管理与 AI 代码审查",
description: "可扩展的 AI 工程化工作流平台",
lang: "zh-CN",
base: "/spaceflow/",
@@ -16,15 +16,17 @@ export default defineConfig({
items: [
{ text: "配置", link: "/reference/config" },
{ text: "CLI 命令", link: "/reference/cli" },
{ text: "环境变量", link: "/reference/env-variables" },
{ text: "Review Spec", link: "/reference/review-spec" },
],
},
{
text: "进阶",
items: [
{ text: "插件开发", link: "/advanced/plugin-development" },
{ text: "扩展开发", link: "/advanced/plugin-development" },
{ text: "核心模块", link: "/advanced/core-modules" },
{ text: "GitHub Actions", link: "/advanced/github-actions" },
{ text: "i18n 国际化", link: "/advanced/i18n" },
],
},
],
@@ -67,7 +69,7 @@ export default defineConfig({
],
},
{
text: "外部命令",
text: "扩展命令",
collapsed: false,
items: [
{ text: "review — 代码审查", link: "/guide/commands/review" },
@@ -84,8 +86,8 @@ export default defineConfig({
items: [
{ text: "配置参考", link: "/reference/config" },
{ text: "CLI 命令参考", link: "/reference/cli" },
{ text: "Review Spec 规范", link: "/reference/review-spec" },
{ text: "环境变量", link: "/reference/env-variables" },
{ text: "Review Spec 规范", link: "/reference/review-spec" },
],
},
],
@@ -93,7 +95,7 @@ export default defineConfig({
{
text: "进阶",
items: [
{ text: "插件开发指南", link: "/advanced/plugin-development" },
{ text: "扩展开发指南", link: "/advanced/plugin-development" },
{ text: "核心模块", link: "/advanced/core-modules" },
{ text: "GitHub Actions", link: "/advanced/github-actions" },
{ text: "i18n 国际化", link: "/advanced/i18n" },

268
docs/advanced/core-modules.md
View File

@@ -1,179 +1,183 @@
# 核心模块
`@spaceflow/core` 提供的共享模块，所有 Extension 都可以导入使用。
`@spaceflow/core` 提供了一系列共享模块，Extension 可以直接导入使用。在新架构中，不再使用 NestJS 依赖注入，而是直接实例化或通过 `SpaceflowContext` 获取服务。
## 模块总览
| 模块 | 导出 | 说明 |
|------|------|------|
| 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 / GitLab） |
| Git SDK | Git 命令封装 |
| LLM Proxy | 多 LLM 统一代理 |
| Logger | 日志系统（Plain / TUI） |
| 飞书 SDK | 飞书开放平台 API |
| Storage | 本地存储（支持 TTL） |
| Parallel | 并行执行工具 |
| i18n | 国际化 |
## Git Provider
Git 平台适配器，支持 GitHub 和 Gitea。
Git 平台适配器，支持 GitHub、Gitea 和 GitLab。
```typescript
import { GitProviderModule, GitProviderService } from "@spaceflow/core";
import { GitProviderService } from "@spaceflow/core";
@Module({
imports: [GitProviderModule.forFeature()],
})
export class MyModule {}
const gitProvider = new GitProviderService();
@Injectable()
export class MyService {
constructor(private readonly gitProvider: GitProviderService) {}
// 获取 PR diff
const diff = await gitProvider.getPullRequestDiff(prNumber);
async createComment(prNumber: number, body: string): Promise<void> {
await this.gitProvider.createPRComment(prNumber, body);
}
// 创建 PR 评论
await gitProvider.createPullRequestComment(prNumber, body);
async listFiles(prNumber: number): Promise<string[]> {
const files = await this.gitProvider.getPRFiles(prNumber);
return files.map((f) => f.filename);
}
}
// 创建行内审查评论
await gitProvider.createReviewComment(prNumber, {
path: "src/index.ts",
line: 42,
body: "建议优化此处逻辑",
});
// 更新 PR 信息
await gitProvider.updatePullRequest(prNumber, { title, body });
```
### 支持的平台
| 平台 | 适配器 | 检测方式 |
|------|--------|----------|
| GitHub | `GithubAdapter` | `GITHUB_TOKEN` 环境变量 |
| Gitea | `GiteaAdapter` | `GITEA_TOKEN` 环境变量 |
| 平台 | 环境变量 | 说明 |
| ------ | ----------------------------------- | ---------- |
| GitHub | `GITHUB_TOKEN` | GitHub API |
| Gitea | `GITEA_TOKEN`, `GITEA_SERVER_URL` | Gitea API |
| GitLab | `GITLAB_TOKEN`, `GITLAB_SERVER_URL` | GitLab API |
默认使用 GitHub。可通过 `GIT_PROVIDER_TYPE` 环境变量显式指定。
平台类型通过 `GIT_PROVIDER_TYPE` 环境变量或配置文件的 `gitProvider.provider` 指定。
## Git SDK
封装常用 Git 命令操作。
Git 命令封装，提供常用 Git 操作。
```typescript
import { GitSdkModule, GitSdkService } from "@spaceflow/core";
import { GitSdkService } from "@spaceflow/core";
@Injectable()
export class MyService {
constructor(private readonly gitSdk: GitSdkService) {}
const gitSdk = new GitSdkService();
async getChanges(): Promise<string> {
return this.gitSdk.diff("main", "HEAD");
}
async getCurrentBranch(): Promise<string> {
return this.gitSdk.currentBranch();
}
}
const diff = await gitSdk.diff("HEAD~1", "HEAD");
const log = await gitSdk.log({ maxCount: 10 });
const status = await gitSdk.status();
```
### 主要方法
| 方法 | 说明 |
| ---------- | -------------- |
| `diff()` | 获取代码差异 |
| `log()` | 获取提交历史 |
| `status()` | 获取工作区状态 |
| `add()` | 暂存文件 |
| `commit()` | 提交更改 |
| `push()` | 推送到远程 |
| `fetch()` | 获取远程更新 |
## LLM Proxy
多 LLM 统一代理，支持 OpenAI、Claude、Claude Code、OpenCode 等。
多 LLM 统一代理，支持 OpenAI 和 Claude。
```typescript
import { LlmProxyModule, LlmProxyService } from "@spaceflow/core";
import { LlmProxyService } from "@spaceflow/core";
@Injectable()
export class MyService {
constructor(private readonly llm: LlmProxyService) {}
const llm = new 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;
}
}
const result = await llm.chat({
messages: [
{ role: "system", content: "你是一个代码分析助手" },
{ role: "user", content: "分析以下代码..." },
],
});
console.log(result.content);
```
### 支持的模型
| 模式 | 环境变量 | 说明 |
| -------- | --------------------------------------- | ---------- |
| `openai` | `OPENAI_API_KEY`, `OPENAI_API_BASE_URL` | OpenAI API |
| `claude` | `ANTHROPIC_API_KEY` | Claude API |
通过 `LLM_PROVIDER` 环境变量或命令行 `-l` 参数指定模式。
## Logger
日志系统，支持 Plain 模式（CI/管道）和 TUI 模式（终端交互）。
日志系统，支持 Plain 和 TUI 两种模式。
```typescript
import { Logger } from "@spaceflow/core";
import { LoggerService } from "@spaceflow/core";
const logger = new Logger("my-extension");
await logger.init(); // 加载 TUI 渲染器
const logger = new LoggerService();
// 基础日志
logger.info("信息");
logger.success("成功");
logger.info("操作开始");
logger.debug("调试信息");
logger.warn("警告");
logger.error("错误");
```
// Spinner
const spinner = logger.spin("处理中...");
spinner.update("仍在处理...");
spinner.succeed("处理完成");
也可通过 `SpaceflowContext` 使用内置的输出服务：
// 进度条
const progress = logger.progress({ total: 100, label: "下载" });
progress.update(50);
progress.finish();
// 子 Logger
const child = logger.child("compile");
child.info("编译中..."); // 输出: [my-extension:compile] 编译中...
```typescript
run: async (args, options, ctx) => {
ctx.output.info("信息");
ctx.output.success("成功");
ctx.output.warn("警告");
ctx.output.error("错误");
ctx.output.debug("调试");
};
```
### 日志级别
| 级别 | 说明 |
|------|------|
| `silent` | 不输出任何日志 |
| `info` | 默认级别 |
| `verbose` | 详细日志（`-v`） |
| `debug` | 调试日志（`-vv`） |
| 级别 | 说明 |
| ------- | ---------------------- |
| `error` | 错误，始终显示 |
| `warn` | 警告，始终显示 |
| `info` | 信息，默认显示 |
| `debug` | 调试，`-v` 时显示 |
| `trace` | 详细跟踪，`-vv` 时显示 |
## Feishu SDK
## 飞书 SDK
飞书 API 封装，支持发送消息。
飞书开放平台 API 封装。
```typescript
import { FeishuSdkModule, FeishuSdkService } from "@spaceflow/core";
import { FeishuSdkService } from "@spaceflow/core";
@Injectable()
export class MyService {
constructor(private readonly feishu: FeishuSdkService) {}
const feishu = new FeishuSdkService();
async notify(chatId: string, message: string): Promise<void> {
await this.feishu.sendMessage(chatId, message);
}
}
await feishu.sendMessage({
chatId: "oc_xxx",
content: message,
});
```
需要配置环境变量 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`。
### 环境变量
| 变量 | 说明 |
| ------------------- | ------------ |
| `FEISHU_APP_ID` | 飞书应用 ID |
| `FEISHU_APP_SECRET` | 飞书应用密钥 |
## Storage
本地存储服务。
本地存储，支持 TTL（过期时间）。通过 `SpaceflowContext` 使用：
```typescript
import { StorageModule, StorageService } from "@spaceflow/core";
run: async (args, options, ctx) => {
// 存储数据，TTL 1小时
await ctx.storage.set("cache-key", { data: "value" }, 3600);
@Injectable()
export class MyService {
constructor(private readonly storage: StorageService) {}
// 读取数据
const cached = await ctx.storage.get<MyData>("cache-key");
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);
}
}
// 删除数据
await ctx.storage.del("cache-key");
};
```
## Parallel
@@ -181,20 +185,34 @@ export class MyService {
并行执行工具，支持并发控制。
```typescript
import { ParallelModule, ParallelService } from "@spaceflow/core";
import { ParallelService } from "@spaceflow/core";
@Injectable()
export class MyService {
constructor(private readonly parallel: ParallelService) {}
const parallel = new ParallelService();
async processFiles(files: string[]): Promise<void> {
await this.parallel.run(
files,
async (file) => {
// 处理单个文件
},
{ concurrency: 10 },
);
}
}
const results = await parallel.run(
files,
async (file) => {
return processFile(file);
},
{ concurrency: 5 },
);
```
## i18n
国际化工具函数。
```typescript
import { t, addLocaleResources } from "@spaceflow/core";
// 注册翻译资源
addLocaleResources("my-ext", {
"zh-CN": { greeting: "你好" },
en: { greeting: "Hello" },
});
// 使用翻译
const message = t("my-ext:greeting"); // "你好" 或 "Hello"
```
详细说明请参考 [i18n 国际化](/advanced/i18n)。

43
docs/advanced/i18n.md
View File

@@ -13,7 +13,7 @@ Spaceflow 基于 [i18next](https://www.i18next.com/) 实现国际化，采用纯
### `initI18n(lang?: string)`
同步初始化 i18next。必须在 NestJS 模块加载前调用。
同步初始化 i18next。必须在命令模块加载前调用（CLI 运行时会自动调用）。
```typescript
import { initI18n } from "@spaceflow/core";
@@ -73,7 +73,7 @@ core/src/locales/
### Extension 语言包
```text
packages/cli/src/commands/<name>/locales/
packages/core/src/commands/<name>/locales/
├── zh-cn/
│ └── <name>.json
├── en/
@@ -108,35 +108,26 @@ export const helloLocales = { "zh-CN": zhCN, en };
addLocaleResources("hello", helloLocales);
```
### 3. 在命令中使用
### 3. 在扩展中使用
```typescript
import { t } from "@spaceflow/core";
import { defineExtension, t } from "@spaceflow/core";
// 必须在命令模块 import 之前导入 locales（side-effect）
// 必须在 defineExtension 之前导入 locales（side-effect）
import "./locales";
@Command({
export default defineExtension({
name: "hello",
description: t("hello:description"),
})
export class HelloCommand extends CommandRunner {
// ...
}
```
### 4. 在 Extension 入口声明
```typescript
export class HelloExtension implements SpaceflowExtension {
getMetadata(): SpaceflowExtensionMetadata {
return {
commands: [
{
name: "hello",
commands: ["hello"],
locales: helloLocales, // 加载时自动注册
};
}
}
description: t("hello:description"),
run: async (args, options, ctx) => {
ctx.output.info(t("hello:greeting", { name: args[0] || "World" }));
},
},
],
});
```
## 插值语法
@@ -150,7 +141,7 @@ t("hello:greeting", { name: "World" });
## 注意事项
- **同步初始化** — `initI18n()` 使用 `initSync`，确保装饰器执行时语言包已加载
- **装饰器时机** — `@Command` / `@Option` 在 import 时执行，`initI18n()` 必须在所有命令模块 import 之前调用
- **同步初始化** — `initI18n()` 使用 `initSync`，确保模块加载时语言包已就绪
- **加载时机** — `initI18n()` 由 CLI 运行时的 `exec()` 自动调用，无需手动处理
- **Side-effect import** — 每个 Extension 的 `locales/index.ts` 在导入时立即调用 `addLocaleResources`
- **key 不存在时** — i18next 默认返回 key 本身，不会报错

351
docs/advanced/plugin-development.md
View File

@@ -1,22 +1,27 @@
# 插件开发指南
# 扩展开发指南
本指南介绍如何开发自定义 Spaceflow Extension。
## 前置知识
- [NestJS](https://nestjs.com/) 基础（Module、Injectable、依赖注入）
- [nest-commander](https://docs.nestjs.com/recipes/nest-commander) CLI 命令定义
- TypeScript
- TypeScript 基础
- [Commander.js](https://github.com/tj/commander.js) CLI 命令概念（可选）
- [Zod](https://zod.dev/) Schema 定义（可选，用于配置校验）
## 快速开始
### 使用模板创建
```bash
spaceflow create my-extension
```
# 创建命令型 Extension
spaceflow create command my-extension
这会在当前目录下创建一个标准的 Extension 模板。
# 创建 MCP Server 型 Extension
spaceflow create mcp my-mcp
# 创建技能型 Extension
spaceflow create skills my-skill
```
### 手动创建
@@ -24,8 +29,7 @@ spaceflow create my-extension
mkdir spaceflow-plugin-hello
cd spaceflow-plugin-hello
pnpm init
pnpm add @spaceflow/core
pnpm add -D typescript @types/node
pnpm add -D @spaceflow/cli typescript @types/node
```
## 目录结构
@@ -33,16 +37,8 @@ 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 入口
│ └── index.ts # Extension 入口（defineExtension）
├── package.json
├── tsconfig.json
└── README.md
@@ -50,147 +46,189 @@ spaceflow-plugin-hello/
## Extension 入口
每个 Extension 必须实现 `SpaceflowExtension` 接口：
使用 `defineExtension()` 定义扩展，这是一个纯函数式 API：
```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 { defineExtension } from "@spaceflow/core";
import { HelloService } from "./hello.service";
interface HelloOptions {
readonly name?: string;
}
@Command({
export default defineExtension({
name: "hello",
description: t("hello:description"),
})
export class HelloCommand extends CommandRunner {
constructor(private readonly helloService: HelloService) {
super();
}
version: "1.0.0",
description: "示例 Extension",
configKey: "hello",
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;
}
}
commands: [
{
name: "hello",
description: "打招呼命令",
arguments: "[name]",
options: [
{
flags: "-g, --greeting <greeting>",
description: "自定义问候语",
default: "Hello",
},
{
flags: "-v, --verbose",
description: "详细输出",
},
],
run: async (args, options, ctx) => {
const helloService = new HelloService();
const name = args[0] || "World";
const greeting = (options.greeting as string) || "Hello";
ctx.output.info(helloService.greet(greeting, name));
},
},
],
});
```
## 业务逻辑
```typescript
// src/hello.service.ts
import { Injectable } from "@spaceflow/core";
@Injectable()
export class HelloService {
greet(name: string): string {
return `Hello, ${name}!`;
greet(greeting: string, name: string): string {
return `${greeting}, ${name}!`;
}
}
```
## NestJS 模块
## 使用 SpaceflowContext
命令的 `run` 函数接收 `SpaceflowContext`，提供运行时能力：
```typescript
// src/hello.module.ts
import { Module } from "@spaceflow/core";
import { HelloCommand } from "./hello.command";
import { HelloService } from "./hello.service";
run: async (args, options, ctx) => {
// 读取配置
const config = ctx.config.getPluginConfig<MyConfig>("hello");
@Module({
providers: [HelloCommand, HelloService],
})
export class HelloModule {}
// 输出
ctx.output.info("信息");
ctx.output.success("成功");
ctx.output.warn("警告");
ctx.output.error("错误");
// 存储
await ctx.storage.set("key", { data: "value" });
const data = await ctx.storage.get<MyData>("key");
// 获取其他已注册的服务
if (ctx.hasService("myService")) {
const svc = ctx.getService<MyService>("myService");
}
};
```
## 使用核心能力
## 注册服务
Extension 可以导入 `@spaceflow/core` 提供的共享模块：
Extension 可以通过 `services` 字段注册可被其他扩展使用的服务：
```typescript
import { Module } from "@spaceflow/core";
import { GitSdkModule } from "@spaceflow/core";
import { LlmProxyModule } from "@spaceflow/core";
@Module({
imports: [
GitSdkModule, // Git 命令封装
LlmProxyModule, // 多 LLM 代理
export default defineExtension({
name: "hello",
commands: [
/* ... */
],
providers: [MyCommand, MyService],
})
export class MyModule {}
services: [
{
key: "hello.service",
factory: (ctx) => new HelloService(ctx),
},
],
});
```
在 Service 中注入使用：
其他扩展可通过 `ctx.getService("hello.service")` 获取。
## 配置 Schema
使用 Zod 定义配置 Schema，提供类型校验和 JSON Schema 自动生成：
```typescript
import { Injectable } from "@spaceflow/core";
import { GitSdkService } from "@spaceflow/core";
import { defineExtension, z } from "@spaceflow/core";
@Injectable()
export class MyService {
constructor(private readonly gitSdk: GitSdkService) {}
async getDiff(): Promise<string> {
return this.gitSdk.diff("HEAD~1", "HEAD");
}
}
export default defineExtension({
name: "hello",
configKey: "hello",
configSchema: () =>
z.object({
greeting: z.string().default("Hello").describe("默认问候语"),
maxRetries: z.number().default(3).describe("最大重试次数"),
}),
commands: [
{
name: "hello",
description: "打招呼命令",
run: async (args, options, ctx) => {
const config = ctx.config.getPluginConfig<{ greeting: string }>(
"hello",
);
ctx.output.info(config?.greeting || "Hello");
},
},
],
});
```
### 可用的核心模块
运行 `spaceflow schema` 后，`hello` 的配置会自动出现在 JSON Schema 中。
| 模块 | 说明 |
|------|------|
| `GitProviderModule` | Git 平台适配器（GitHub / Gitea） |
| `GitSdkModule` | Git 命令封装 |
| `LlmProxyModule` | 多 LLM 统一代理 |
| `FeishuSdkModule` | 飞书 API |
| `StorageModule` | 本地存储 |
| `ParallelModule` | 并行执行工具 |
## 生命周期钩子
```typescript
export default defineExtension({
name: "hello",
commands: [
/* ... */
],
// 所有服务注册完毕后调用
onInit: async (ctx) => {
ctx.output.debug("hello extension initialized");
},
// CLI 退出前调用
onDestroy: async (ctx) => {
ctx.output.debug("hello extension destroyed");
},
});
```
## MCP 工具
Extension 可以同时提供 CLI 命令和 MCP 工具：
```typescript
import { defineExtension, z } from "@spaceflow/core";
export default defineExtension({
name: "hello",
commands: [
/* ... */
],
mcp: {
name: "hello-tools",
version: "1.0.0",
description: "Hello MCP 工具集",
tools: [
{
name: "greet",
description: "生成问候语",
inputSchema: z.object({
name: z.string().describe("名字"),
}),
handler: async (input, ctx) => {
const { name } = input as { name: string };
return { content: [{ type: "text", text: `Hello, ${name}!` }] };
},
},
],
},
});
```
## package.json 规范
@@ -200,56 +238,41 @@ export class MyService {
"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"
}
"scripts": {
"build": "spaceflow build",
"dev": "spaceflow dev"
},
"devDependencies": {
"@spaceflow/cli": "workspace:*"
},
"peerDependencies": {
"@spaceflow/core": "^0.17.0"
"@spaceflow/core": "workspace:*"
},
"spaceflow": {
"commands": ["hello"],
"configKey": "hello"
"type": "flow",
"entry": "."
}
}
```
## 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);
```
如果 Extension 同时提供命令、技能和 MCP：
```json
// src/locales/zh-cn/hello.json
{
"description": "打招呼命令",
"options.name": "名字"
}
```
```json
// src/locales/en/hello.json
{
"description": "Say hello",
"options.name": "Name"
"spaceflow": {
"exports": {
"hello": { "type": "flow", "entry": "." },
"hello-skills": { "type": "skill", "entry": "./skills" },
"hello-mcp": {
"type": "mcp",
"entry": ".",
"mcp": { "command": "node", "args": ["dist/mcp.js"] }
}
}
}
}
```
@@ -261,9 +284,11 @@ addLocaleResources("hello", helloLocales);
spaceflow build
```
Extension 使用 Rspack 构建，默认配置会自动处理 TypeScript 编译和打包。
### 本地测试
在 `spaceflow.json` 中使用 `link:` 引用本地 Extension：
在配置文件中使用 `link:` 引用本地 Extension：
```json
{
@@ -273,6 +298,8 @@ spaceflow build
}
```
然后运行 `spaceflow install` 即可加载。
### 发布到 npm
```bash

6
docs/guide/commands/create.md
View File

@@ -31,6 +31,7 @@ spaceflow create --from git@github.com:org/tpl.git --ref v1.0 api my-api
| 模板 | 说明 |
| --------- | ---------------------------------------- |
| `command` | 命令型 Extension，提供 CLI 命令 |
| `mcp` | MCP Server 型 Extension |
| `skills` | 技能型 Extension，提供编辑器 AI 技能文件 |
## 远程模板
@@ -57,10 +58,7 @@ spaceflow create --from git@github.com:org/tpl.git --ref v1.0 api my-api
```text
my-cmd/
├── src/
│ ├── my-cmd.command.ts # 命令定义
│ ├── my-cmd.service.ts # 业务逻辑
│ ├── my-cmd.module.ts # NestJS 模块
│ └── index.ts # Extension 入口
│ └── index.ts # Extension 入口（defineExtension）
├── package.json
├── tsconfig.json
└── README.md

16
docs/guide/commands/install.md
View File

@@ -14,7 +14,7 @@ spaceflow install ./extensions/my-plugin
# 安装 git 仓库
spaceflow install git@github.com:org/plugin.git
# 安装所有 spaceflow.json 中的 dependencies
# 安装配置文件中所有 dependencies
spaceflow install
# 全局安装
@@ -23,22 +23,22 @@ spaceflow install @spaceflow/review -g
## 支持的 source 类型
| 类型 | 示例 | 说明 |
| -------- | ------------------------------- | ------------------------------------ |
| npm 包 | `@spaceflow/review` | 执行 `pnpm add <package>` |
| 本地路径 | `./extensions/my-plugin` | 注册 `link:` 引用到 `spaceflow.json` |
| git 仓库 | `git@github.com:org/plugin.git` | 克隆到 `.spaceflow/deps/` |
| 类型 | 示例 | 说明 |
| -------- | ------------------------------- | --------------------------- |
| npm 包 | `@spaceflow/review` | 执行 `pnpm add <package>` |
| 本地路径 | `./extensions/my-plugin` | 注册 `link:` 引用到配置文件 |
| git 仓库 | `git@github.com:org/plugin.git` | 克隆到 `.spaceflow/deps/` |
## 安装流程
1. **解析 source** — 判断是 npm 包、本地路径还是 git 仓库
2. **安装依赖** — 根据类型执行对应的安装操作
3. **更新配置** — 将 Extension 注册到 `spaceflow.json` 的 `dependencies` 字段
3. **更新配置** — 将 Extension 注册到配置文件的 `dependencies` 字段
4. **关联编辑器** — 将 Extension 的 skills 关联到 `support` 中配置的编辑器目录
## 无参数模式
不传 source 时，会读取 `spaceflow.json` 中的 `dependencies` 字段，安装所有已注册的 Extension：
不传 source 时，会读取配置文件中的 `dependencies` 字段，安装所有已注册的 Extension：
```bash
spaceflow install

54
docs/guide/commands/mcp.md
View File

@@ -15,9 +15,9 @@ spaceflow mcp --inspector
## 工作原理
1. **扫描 Extension** — 加载所有已安装的 Extension
2. **收集工具** — 查找带有 `@McpServer` 装饰器的类，提取其 MCP 工具定义
2. **收集工具** — 查找 `ExtensionDefinition` 中的 `mcp` 字段，提取 MCP 工具定义
3. **启动服务** — 通过 stdio 传输协议启动 MCP Server
4. **注册工具** — 将所有工具注册到 MCP Server，支持 JSON Schema 参数校验
4. **注册工具** — 将所有工具注册到 MCP Server，支持 Zod Schema 参数校验
## MCP Inspector
@@ -67,34 +67,38 @@ Inspector 会自动下载并启动 `@modelcontextprotocol/inspector`，提供：
## 开发 MCP 工具
Extension 可以通过 `@McpServer` 和 `@McpTool` 装饰器暴露 MCP 工具：
Extension 通过 `defineExtension` 的 `mcp` 字段声明 MCP 工具：
```typescript
import { McpServer, McpTool, Injectable } from "@spaceflow/core";
import { defineExtension, z } from "@spaceflow/core";
@McpServer({ name: "my-tools", description: "我的工具集" })
@Injectable()
export class MyMcpTools {
@McpTool({
name: "hello",
description: "打招呼",
inputSchema: {
type: "object",
properties: {
name: { type: "string", description: "名字" },
export default defineExtension({
name: "my-tools",
commands: [],
mcp: {
name: "my-tools",
version: "1.0.0",
description: "我的工具集",
tools: [
{
name: "hello",
description: "打招呼",
inputSchema: z.object({
name: z.string().describe("名字"),
}),
handler: async (input, ctx) => {
const { name } = input as { name: string };
return { content: [{ type: "text", text: `Hello, ${name}!` }] };
},
},
required: ["name"],
},
})
async hello(args: { name: string }): Promise<string> {
return `Hello, ${args.name}!`;
}
}
],
},
});
```
## 命令行选项
| 选项 | 简写 | 说明 |
|------|------|------|
| `--inspector` | `-i` | 启动 MCP Inspector 调试模式 |
| `--verbose` | `-v` | 详细日志（`-v` 基本，`-vv` 详细，`-vvv` 调试） |
| 选项 | 简写 | 说明 |
| ------------- | ---- | ---------------------------------------------- |
| `--inspector` | `-i` | 启动 MCP Inspector 调试模式 |
| `--verbose` | `-v` | 详细日志（`-v` 基本，`-vv` 详细，`-vvv` 调试） |

8
docs/guide/commands/setup.md
View File

@@ -24,7 +24,7 @@ spaceflow setup
1. **创建 `.spaceflow/` 目录** — 包含 `package.json`（用于管理 Extension 依赖）
2. **生成 JSON Schema** — 创建 `config-schema.json`，提供编辑器自动补全
3. **创建 `spaceflow.json`** — 默认配置文件（如果不存在）
3. **创建配置文件** — 创建 `.spaceflowrc`（如果不存在）
生成的默认配置：
@@ -50,7 +50,7 @@ spaceflow setup -g
执行以下操作：
1. **创建 `~/.spaceflow/` 目录** — 全局配置目录
2. **读取本地配置** — 读取当前项目的 `spaceflow.json`
2. **读取本地配置** — 读取当前项目的配置文件
3. **读取 `.env` 文件** — 解析 `SPACEFLOW_` 前缀的环境变量
4. **合并配置** — 本地配置 < 实例配置 < 环境变量配置
5. **写入全局配置** — 保存到 `~/.spaceflow/spaceflow.json`
@@ -82,6 +82,6 @@ SPACEFLOW_REVIEW_RETRIES=5
## 命令行选项
| 选项 | 简写 | 说明 |
|------|------|------|
| 选项 | 简写 | 说明 |
| ---------- | ---- | ---------- |
| `--global` | `-g` | 全局初始化 |

165
docs/guide/configuration.md
View File

@@ -1,6 +1,6 @@
# 配置文件
Spaceflow 使用 `spaceflow.json` 作为项目配置文件，统一存放在 `.spaceflow/` 目录下。也支持 `.spaceflowrc` 格式的 RC 文件。
Spaceflow 支持 `spaceflow.json` 和 `.spaceflowrc` 两种配置文件格式，内容完全一致。
## 配置文件位置
@@ -15,19 +15,88 @@ Spaceflow 使用 `spaceflow.json` 作为项目配置文件，统一存放在 `.s
```json
{
"$schema": "./.spaceflow/config-schema.json",
"$schema": ".spaceflow/config-schema.json",
"support": ["claudeCode"],
"dependencies": {
"@spaceflow/review": "latest"
},
"review": { ... },
"publish": { ... },
"dependencies": { ... },
"support": ["claudeCode"]
"publish": { ... }
}
```
## 配置项
### `support`
配置需要关联的 AI 编辑器。安装 Extension 时，会将资源关联到对应编辑器目录。
```json
{
"support": ["claudeCode", "windsurf", "cursor"]
}
```
| 值 | 编辑器目录 |
| ------------ | ------------ |
| `claudeCode` | `.claude/` |
| `windsurf` | `.windsurf/` |
| `cursor` | `.cursor/` |
| `opencode` | `.opencode/` |
默认值为 `["claudeCode"]`。
### `dependencies`
已安装的外部 Extension 注册表。由 `spaceflow install` 命令自动管理。
```json
{
"dependencies": {
"@spaceflow/review": "latest",
"@spaceflow/publish": "workspace:*",
"@spaceflow/shell": "link:./extensions/shell"
}
}
```
支持的值格式：
| 格式 | 类型 | 示例 |
| ----------------- | -------- | ----------------------------------------- |
| `latest` / `^1.0` | npm 版本 | `"latest"`, `"^1.0.0"` |
| `workspace:*` | 工作区 | `"workspace:*"` |
| `link:./path` | 本地链接 | `"link:./extensions/review"` |
| `git+ssh://...` | Git 仓库 | `"git+ssh://git@github.com/org/repo.git"` |
### `lang`
界面语言设置。
```json
{
"lang": "zh-CN"
}
```
支持 `zh-CN`（默认）和 `en`。
### `gitProvider`
Git 平台配置。
```json
{
"gitProvider": {
"provider": "github",
"serverUrl": "https://api.github.com"
}
}
```
### `review`
AI 代码审查相关配置。
AI 代码审查相关配置（需安装 `@spaceflow/review`）。
```json
{
@@ -47,22 +116,23 @@ AI 代码审查相关配置。
}
```
| 字段 | 类型 | 默认值 | 说明 |
| --------------------- | ---------- | ------------ | -------------------------------------------- |
| `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` | 重试间隔（毫秒） |
| 字段 | 类型 | 默认值 | 说明 |
| ---------------------- | ---------- | ------------- | ---------------------------------------- |
| `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` | 重试间隔（毫秒） |
### `publish`
版本发布相关配置，基于 [release-it](https://github.com/release-it/release-it)。
版本发布相关配置（需安装 `@spaceflow/publish`），基于 [release-it](https://github.com/release-it/release-it)。
```json
{
@@ -84,67 +154,36 @@ AI 代码审查相关配置。
"tag": "latest"
},
"git": {
"lockBranch": false,
"pushWhitelistUsernames": ["github-actions[bot]"]
}
}
}
```
### `dependencies`
### `commit`
已安装的外部 Extension 注册表。由 `spaceflow install` 命令自动管理。
AI 智能提交相关配置。
```json
{
"dependencies": {
"@spaceflow/review": "link:./extensions/review",
"@spaceflow/publish": "link:./extensions/publish",
"@spaceflow/shell": "link:./extensions/shell"
"commit": {
"strategy": "rules-first",
"rules": [
{ "pattern": "docs/**", "scope": "docs" },
{ "pattern": ".github/**", "scope": "ci" }
]
}
}
```
支持的值格式：
| 格式 | 类型 | 示例 |
| --------------- | -------- | --------------------------------------- |
| `link:./path` | 本地链接 | `link:./extensions/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 默认值**（最低优先级）
3. **项目配置文件**（`.spaceflowrc` > `.spaceflow/spaceflow.json`）
4. **全局配置文件**（`~/.spaceflowrc` > `~/.spaceflow/spaceflow.json`）
5. **Extension 默认值**（最低优先级）
## JSON Schema
@@ -158,6 +197,6 @@ spaceflow schema
```json
{
"$schema": "./.spaceflow/config-schema.json"
"$schema": ".spaceflow/config-schema.json"
}
```

33
docs/guide/editor-integration.md
View File

@@ -13,7 +13,7 @@ Spaceflow 支持将 Extension 的资源自动关联到多个 AI 编程工具的
## 配置
在 `spaceflow.json` 中通过 `support` 字段指定需要关联的编辑器：
在配置文件中通过 `support` 字段指定需要关联的编辑器：
```json
{
@@ -25,32 +25,32 @@ Spaceflow 支持将 Extension 的资源自动关联到多个 AI 编程工具的
## Extension 的四种导出类型
Extension 在 `package.json` 的 `exports` 中声明导出类型，Spaceflow 根据类型执行不同的关联操作：
Extension 在 `package.json` 的 `spaceflow` 字段中声明导出类型，Spaceflow 根据类型执行不同的关联操作：
| 类型 | 说明 | 关联行为 |
| ---------- | ------------------------ | -------------------------------------------------- |
| `flows` | CLI 子命令 | 不关联到编辑器目录，仅注册为 `spaceflow <command>` |
| `skills` | 技能文件（`.md` 规范等） | **复制**到编辑器的 `skills/` 目录 |
| `commands` | 编辑器命令 | 生成 `.md` 文件到编辑器的 `commands/` 目录 |
| `mcps` | MCP Server | 注册到编辑器的 `mcp.json` 配置 |
| 类型 | 说明 | 关联行为 |
| --------- | ------------------------ | -------------------------------------------------- |
| `flow` | CLI 子命令（默认） | 不关联到编辑器目录，仅注册为 `spaceflow <command>` |
| `skill` | 技能文件（`.md` 规范等） | **复制**到编辑器的 `skills/` 目录 |
| `command` | 编辑器命令 | 生成 `.md` 文件到编辑器的 `commands/` 目录 |
| `mcp` | MCP Server | 注册到编辑器的 `mcp.json` 配置 |
## 自动关联逻辑
当你运行 `spaceflow install` 时，系统会：
1. 通过 `pnpm add` 将 Extension 安装到 `.spaceflow/node_modules/`
2. 读取 Extension 的 `package.json` 中的导出配置
2. 读取 Extension 的 `package.json` 中的 `spaceflow` 配置
3. 根据 `support` 配置，将资源关联到对应编辑器目录：
- **skills** — 将文件**复制**到 `.claude/skills/`、`.windsurf/skills/` 等目录
- **commands** — 生成 `.md` 命令文件到 `.claude/commands/` 等目录
- **mcps** — 将 MCP Server 配置写入 `.claude/mcp.json` 等文件
- **skill** — 将文件**复制**到 `.claude/skills/`、`.windsurf/skills/` 等目录
- **command** — 生成 `.md` 命令文件到 `.claude/commands/` 等目录
- **mcp** — 将 MCP Server 配置写入 `.claude/mcp.json` 等文件
4. 自动更新编辑器目录的 `.gitignore`，避免生成文件被提交
全局安装（`-g`）时，关联到家目录下的对应编辑器目录（如 `~/.claude/`）。
## 目录结构示例
配置 `support: ["claudeCode", "windsurf"]` 后，安装一个包含 skills 和 mcps 的 Extension 会生成如下结构：
配置 `support: ["claudeCode", "windsurf"]` 后，安装一个包含 skill 和 mcp 导出的 Extension 会生成如下结构：
```text
project/
@@ -62,20 +62,19 @@ project/
│ └── mcp.json # 自动注册 MCP Server
├── .windsurf/
│ ├── skills/
│ │ └── review-spec/ # 从 .spaceflow/node_modules/ 复制
│ │ └── review-spec/
│ │ ├── js&ts.nest.md
│ │ └── vue.base.md
│ └── mcp.json
└── .spaceflow/
├── node_modules/ # 所有 Extension 的安装位置
│ └── @spaceflow/review/
├── package.json
└── spaceflow.json
└── package.json
```
## MCP Server 注册
当 Extension 声明了 `mcps` 导出时，`spaceflow install` 会自动将其注册到编辑器的 `mcp.json`：
当 Extension 声明了 `mcp` 导出类型时，`spaceflow install` 会自动将其注册到编辑器的 `mcp.json`：
```json
{

158
docs/guide/extension-system.md
View File

@@ -1,12 +1,12 @@
# Extension 系统
Spaceflow 的所有功能命令都以 Extension 形式组织。Extension 分为**内置命令**和**外部 Extension** 两类。
Spaceflow 的所有功能命令都以 Extension 形式组织。Extension 分为**内置命令**和**外部扩展**两类，但都使用相同的 `defineExtension()` API 定义。
## Extension 类型
### 内置命令
内置在 `@spaceflow/cli` 中，无需安装即可使用：
内置在 `@spaceflow/core` 中，无需安装即可使用：
| 命令 | 说明 |
| ----------- | -------------------- |
@@ -18,13 +18,13 @@ Spaceflow 的所有功能命令都以 Extension 形式组织。Extension 分为*
| `create` | 创建 Extension 模板 |
| `list` | 列出已安装 Extension |
| `clear` | 清理缓存 |
| `commit` | Git 提交辅助 |
| `setup` | 编辑器配置 |
| `commit` | AI 智能提交 |
| `setup` | 初始化配置 |
| `schema` | 生成 JSON Schema |
| `mcp` | MCP 服务 |
| `runx` | 运行外部命令 |
### 外部 Extension
### 外部扩展
独立的 npm 包，需要通过 `spaceflow install` 安装：
@@ -39,51 +39,131 @@ Spaceflow 的所有功能命令都以 Extension 形式组织。Extension 分为*
## Extension 生命周期
```text
install → 注册到 spaceflow.json → CLI 启动时加载 → 注入 NestJS 模块 → 可用
install → 注册到配置文件 → CLI 启动时 dynamic import → ExtensionLoader 注册 → Commander 构建 → 可用
```
1. **安装** — `spaceflow install <package>` 下载并注册
2. **注册** — 写入 `spaceflow.json` 的 `dependencies` 字段
3. **加载** — CLI 启动时，`ExtensionLoaderService` 扫描并加载所有已注册 Extension
4. **注入** — Extension 的 NestJS Module 被动态注入到 CLI 应用中
5. **执行** — 用户通过 `spaceflow <command>` 调用
1. **安装** — `spaceflow install <package>` 下载依赖并注册
2. **注册** — 写入配置文件的 `dependencies` 字段
3. **加载** — CLI 壳子生成 `.spaceflow/bin/index.js`，动态 import 所有扩展
4. **注册** — `ExtensionLoader` 接收 `ExtensionDefinition`，注册命令和服务
5. **构建** — `exec()` 函数将所有命令添加到 Commander.js 程序
6. **执行** — 用户通过 `spaceflow <command>` 调用
## Extension 接口
## 定义 Extension
每个 Extension 必须实现 `SpaceflowExtension` 接口：
使用 `defineExtension()` 函数定义扩展，这是一个纯函数式 API：
```typescript
import type {
SpaceflowExtension,
SpaceflowExtensionMetadata,
} from "@spaceflow/core";
import { defineExtension } from "@spaceflow/core";
export class ReviewExtension implements SpaceflowExtension {
getMetadata(): SpaceflowExtensionMetadata {
return {
name: "review",
commands: ["review"],
configKey: "review",
description: "AI 代码审查",
};
}
export default defineExtension({
name: "hello",
version: "1.0.0",
description: "示例扩展",
configKey: "hello",
commands: [
{
name: "hello",
description: "打招呼命令",
arguments: "[name]",
options: [
{
flags: "-g, --greeting <greeting>",
description: "自定义问候语",
default: "Hello",
},
],
run: async (args, options, ctx) => {
const name = args[0] || "World";
ctx.output.info(`${options.greeting}, ${name}!`);
},
},
],
});
```
getModule() {
return ReviewModule;
### ExtensionDefinition
| 字段 | 类型 | 必填 | 说明 |
| -------------------- | --------------------- | ---- | ------------------------ |
| `name` | `string` | ✅ | 扩展名称 |
| `commands` | `CommandDefinition[]` | ✅ | 命令列表 |
| `version` | `string` | ❌ | 版本号 |
| `description` | `string` | ❌ | 扩展描述 |
| `configKey` | `string` | ❌ | 对应配置文件中的配置路径 |
| `configSchema` | `() => ZodSchema` | ❌ | 配置 Schema 工厂函数 |
| `configDependencies` | `string[]` | ❌ | 依赖的其他扩展配置 key |
| `services` | `ServiceDefinition[]` | ❌ | 服务定义列表 |
| `mcp` | `McpServerDefinition` | ❌ | MCP 服务器定义 |
| `onInit` | `(ctx) => Promise` | ❌ | 初始化钩子 |
| `onDestroy` | `(ctx) => Promise` | ❌ | 销毁钩子 |
### CommandDefinition
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ------------------------------ | ---- | ------------------------------------- |
| `name` | `string` | ✅ | 命令名称 |
| `description` | `string` | ✅ | 命令描述 |
| `run` | `(args, opts, ctx) => Promise` | ✅ | 执行函数 |
| `aliases` | `string[]` | ❌ | 命令别名 |
| `arguments` | `string` | ❌ | 位置参数，如 `"<name>"` 或 `"[file]"` |
| `options` | `OptionDefinition[]` | ❌ | 命令选项 |
| `subcommands` | `CommandDefinition[]` | ❌ | 子命令 |
### SpaceflowContext
命令的 `run` 函数接收 `SpaceflowContext` 作为第三个参数，提供运行时服务访问：
```typescript
interface SpaceflowContext {
readonly config: IConfigReader; // 配置读取
readonly output: IOutputService; // 输出服务（info/success/warn/error/debug）
readonly storage: IStorageService; // 存储服务
getService<T>(key: string): T; // 获取已注册的服务
hasService(key: string): boolean; // 检查服务是否存在
registerService(key: string, service: unknown): void; // 注册服务
}
```
## package.json 中的 spaceflow 配置
Extension 的 `package.json` 中通过 `spaceflow` 字段声明导出类型：
```json
{
"spaceflow": {
"type": "flow",
"entry": "."
}
}
```
### SpaceflowExtensionMetadata
多导出格式：
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ---------------------------------------- | ---- | ---------------------------------- |
| `name` | `string` | ✅ | Extension 名称 |
| `commands` | `string[]` | ✅ | 提供的命令列表 |
| `configKey` | `string` | ❌ | 对应 `spaceflow.json` 中的配置 key |
| `description` | `string` | ❌ | Extension 描述 |
| `version` | `string` | ❌ | 版本号 |
| `locales` | `Record<string, Record<string, string>>` | ❌ | i18n 语言资源 |
```json
{
"spaceflow": {
"exports": {
"review": { "type": "flow", "entry": "." },
"review-rules": { "type": "skill", "entry": "./skills" },
"review-mcp": {
"type": "mcp",
"entry": ".",
"mcp": { "command": "node", "args": ["dist/mcp.js"] }
}
}
}
}
```
导出类型：
| 类型 | 说明 | 安装行为 |
| --------- | ------------------ | ------------------------------------------ |
| `flow` | CLI 子命令（默认） | 注册为 `spaceflow <command>` |
| `skill` | 技能文件 | 复制到编辑器的 `skills/` 目录 |
| `command` | 编辑器命令 | 生成 `.md` 文件到编辑器的 `commands/` 目录 |
| `mcp` | MCP Server | 注册到编辑器的 `mcp.json` 配置 |
## 管理命令
@@ -92,7 +172,7 @@ export class ReviewExtension implements SpaceflowExtension {
spaceflow install @spaceflow/review
# 卸载
spaceflow uninstall review
spaceflow uninstall @spaceflow/review
# 更新
spaceflow update
@@ -103,4 +183,4 @@ spaceflow list
## 开发 Extension
请参考 [插件开发指南](/advanced/plugin-development) 了解如何创建自定义 Extension。
请参考 [扩展开发指南](/advanced/plugin-development) 了解如何创建自定义 Extension。

53
docs/guide/getting-started.md
View File

@@ -2,6 +2,12 @@
## 安装
### 项目内安装（推荐）
```bash
pnpm add -D @spaceflow/cli
```
### 全局安装
```bash
@@ -20,34 +26,38 @@ spaceflow --help
## 初始化项目
运行 `spaceflow setup` 初始化项目，或手动创建 `.spaceflow/spaceflow.json` 配置文件：
```bash
spaceflow setup
```
这会创建 `.spaceflow/` 目录和默认配置文件。你也可以手动创建 `.spaceflowrc` 配置文件：
```json
{
"review": {
"references": ["./references"],
"includes": ["*/**/*.ts", "!*/**/*.spec.*"],
"generateDescription": true,
"lineComments": true,
"concurrency": 10
},
"support": ["claudeCode"]
"$schema": ".spaceflow/config-schema.json",
"support": ["claudeCode"],
"dependencies": {
"@spaceflow/review": "latest"
}
}
```
## 安装 Extension
使用 `install` 命令安装外部 Extension：
使用 `install` 命令安装扩展：
```bash
# 安装 review Extension
# 安装 review 扩展
spaceflow install @spaceflow/review
# 安装 publish Extension
# 安装 publish 扩展
spaceflow install @spaceflow/publish
# 安装配置文件中的所有依赖
spaceflow install
```
安装后，Extension 会被注册到 `spaceflow.json` 的 `dependencies` 字段中。
安装后，Extension 会被注册到配置文件的 `dependencies` 字段，并自动关联到 `support` 中指定的编辑器目录。
## 常用命令
@@ -74,6 +84,16 @@ spaceflow publish
spaceflow publish --dry-run
```
### AI 智能提交
```bash
# 自动生成 commit message
spaceflow commit
# 智能拆分为多个 commit
spaceflow commit --split
```
### 查看已安装的 Extension
```bash
@@ -104,12 +124,19 @@ on:
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 }}
```
详细的 CI 配置请参考 [GitHub Actions](/advanced/github-actions)。

50
docs/guide/introduction.md
View File

@@ -2,40 +2,45 @@
## 什么是 Spaceflow？
Spaceflow 是一个**可扩展的 AI 工作流引擎**，为团队提供统一的 CI/CD 管理和 AI 代码审查能力。它基于 NestJS + nest-commander 构建，采用插件化架构，命令以 Extension 形式分发和管理。
Spaceflow 是一个**可扩展的 AI 工程化工作流平台**，为团队提供插件化的 CI/CD 管理、AI 代码审查和多编辑器集成能力。
它采用**三层架构**：轻量 CLI 壳子 → 核心运行时（Commander.js + ServiceContainer） → 可插拔的 Extension 扩展。所有命令（内置 + 外部）统一通过 `defineExtension()` 定义，以纯函数式的方式声明命令、服务和 MCP 工具。
## 核心特性
- **AI 代码审查** — 基于 LLM 的自动化代码审查，支持 OpenAI、Claude 等多种模型
- **Extension 插件系统** — 命令以插件包形式分发，支持 npm 包和本地链接
- **多编辑器集成** — 自动将技能关联到 Claude Code、Windsurf、Cursor 等 AI 编程工具
- **AI 代码审查** — 基于 LLM 的自动化代码审查，支持 OpenAI、Claude、Claude Code、OpenCode 等多种模型
- **Extension 扩展系统** — 基于 `defineExtension` 的纯函数式扩展，支持 npm 包、本地路径和 Git 仓库安装
- **多编辑器集成** — 自动将技能、命令和 MCP 服务关联到 Claude Code、Windsurf、Cursor、OpenCode 等 AI 编程工具
- **MCP 支持** — 内置 Model Context Protocol 服务器，聚合所有扩展的 MCP 工具
- **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） |
| 技术 | 用途 |
| -------------------------------------------------------- | --------------------------- |
| [Commander.js](https://github.com/tj/commander.js) | CLI 命令解析 |
| [ServiceContainer](https://github.com/Lydanne/spaceflow) | 轻量 DI 容器（自研） |
| [Rspack](https://rspack.dev/) | 构建打包 |
| [i18next](https://www.i18next.com/) | 国际化 |
| [Zod](https://zod.dev/) | 配置校验与 JSON Schema 生成 |
| [MCP SDK](https://modelcontextprotocol.io/) | Model Context Protocol 服务 |
| [pnpm](https://pnpm.io/) | 包管理（Monorepo） |
## 包结构
Spaceflow 采用 Monorepo 结构，主要包含以下包：
Spaceflow 采用 pnpm Monorepo 结构，主要包含以下包：
| 包名 | 说明 |
| --------------------------- | ----------------------------------------------------------- |
| `@spaceflow/core` | 核心能力库，提供 Git Provider、LLM Proxy、Logger 等基础模块 |
| `@spaceflow/cli` | CLI 入口，包含所有内置命令 |
| `@spaceflow/review` | AI 代码审查 Extension |
| `@spaceflow/publish` | 版本发布 Extension |
| `@spaceflow/scripts` | 自定义脚本执行 Extension |
| `@spaceflow/shell` | Shell 命令执行 Extension |
| `@spaceflow/review-summary` | 审查总结 Extension |
| 包名 | 说明 |
| --------------------------- | ------------------------------------------------------------ |
| `@spaceflow/cli` | CLI 壳子入口，负责引导和启动 |
| `@spaceflow/core` | 核心运行时 + 13 个内置命令 + 共享模块（Git、LLM、Logger 等） |
| `@spaceflow/shared` | 轻量公共工具库，CLI 和 core 共同依赖 |
| `@spaceflow/review` | AI 代码审查扩展 |
| `@spaceflow/publish` | 自动化版本发布扩展 |
| `@spaceflow/scripts` | CI 环境下执行 JS 脚本 |
| `@spaceflow/shell` | CI 环境下执行 Shell 命令 |
| `@spaceflow/review-summary` | PR 贡献审查统计 |
## 适用场景
@@ -43,3 +48,4 @@ Spaceflow 采用 Monorepo 结构，主要包含以下包：
- 需要统一管理多个仓库 CI/CD 流程的组织
- 希望将 AI 编程工具的技能和规范标准化分发的团队
- 需要自动化版本发布和变更日志生成的项目
- 需要通过 MCP 将工具能力暴露给 AI 编辑器的开发者

177
docs/guide/project-structure.md
View File

@@ -6,88 +6,136 @@ 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/ # 并行执行工具
│ └── ...
│
├── packages/
│ ├── cli/ # @spaceflow/cli — CLI 入口
│ ├── 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 资源
│ │ └── cli.ts # 唯一入口：引导 → 生成 bin → 执行
│ │
│ ├── core/ # @spaceflow/core — 核心运行时
│ │ └── src/
│ │ ├── cli-runtime/ # DI 容器、ExtensionLoader、exec() 入口
│ │ ├── commands/ # 13 个内置命令（defineExtension 定义）
│ │ │ ├── build/
│ │ │ ├── clear/
│ │ │ ├── commit/
│ │ │ ├── create/
│ │ │ ├── dev/
│ │ │ ├── install/
│ │ │ ├── list/
│ │ │ ├── mcp/
│ │ │ ├── runx/
│ │ │ ├── schema/
│ │ │ ├── setup/
│ │ │ ├── uninstall/
│ │ │ └── update/
│ │ ├── config/ # 配置加载与 Schema 生成
│ │ ├── extension-system/# 扩展类型定义与 defineExtension
│ │ ├── locales/ # CLI 命令翻译文件（en + zh-cn）
│ │ └── shared/ # 共享模块
│ │ ├── git-provider/ # Git 平台适配器（GitHub / Gitea / GitLab）
│ │ ├── git-sdk/ # Git 命令封装
│ │ ├── llm-proxy/ # 多 LLM 统一代理
│ │ ├── llm-jsonput/ # JSON 结构化输出
│ │ ├── feishu-sdk/ # 飞书 SDK
│ │ ├── logger/ # 日志系统（Plain / TUI）
│ │ ├── mcp/ # MCP 装饰器与工具
│ │ ├── parallel/ # 并行执行工具
│ │ ├── storage/ # 通用存储服务
│ │ └── ...
│ │
│ └── shared/ # @spaceflow/shared — 公共工具库
│ └── src/
│ ├── config/ # 配置读写工具
│ ├── editor-config/ # 编辑器目录映射
│ ├── package-manager/ # 包管理器检测
│ ├── source-utils/ # 源类型判断
│ ├── spaceflow-dir/ # .spaceflow 目录管理
│ └── verbose/ # 日志级别工具
│
├── extensions/ # 外部 Extension（独立 npm 包）
│ ├── review/ # @spaceflow/review — AI 代码审查
│ ├── publish/ # @spaceflow/publish — 版本发布
│ ├── scripts/ # @spaceflow/scripts — 脚本执行
│ ├── shell/ # @spaceflow/shell — Shell 执行
│ └── review-summary/ # @spaceflow/review-summary — 审查总结
├── extensions/ # 扩展（独立 npm 包）
│ ├── review/ # @spaceflow/review — AI 代码审查
│ ├── publish/ # @spaceflow/publish — 版本发布
│ ├── scripts/ # @spaceflow/scripts — 脚本执行
│ ├── shell/ # @spaceflow/shell — Shell 执行
│ └── review-summary/ # @spaceflow/review-summary — 审查总结
│
├── actions/ # GitHub Actions
├── actions/ # GitHub Actions
│ ├── src/
│ └── action.yml
│
├── references/ # 代码审查规范文件
├── templates/ # Extension 模板
│ ├── command/ # 命令型 Extension 模板
│ ├── mcp/ # MCP Server 模板
│ └── skills/ # 技能型 Extension 模板
│
├── references/ # 代码审查规范文件
│ ├── js&ts.base.md
│ ├── js&ts.nest.md
│ └── ...
│
├── templates/ # Extension 模板
│ ├── command/ # 命令型 Extension 模板
│ └── skills/ # 技能型 Extension 模板
├── docs/ # 文档站点（VitePress）
│
├── .spaceflow/ # Spaceflow 工作目录
│ ├── spaceflow.json # 项目配置
│ └── package.json # Extension 依赖管理
├── .spaceflow/ # Spaceflow 工作目录（运行时生成）
│ ├── package.json # Extension 依赖管理
│ └── bin/index.js # 生成的入口文件
│
├── pnpm-workspace.yaml # pnpm Monorepo 配置
└── package.json # 根 package.json
├── .spaceflowrc # 项目配置文件
├── pnpm-workspace.yaml # pnpm Monorepo 配置
└── package.json # 根 package.json
```
## 架构概览
Spaceflow 采用三层架构：
```text
┌─────────────────────────────────────────────┐
│ @spaceflow/cli（壳子） │
│ 职责：确保 .spaceflow 目录 → 安装依赖 │
│ → 生成 bin/index.js → spawn 子进程执行 │
└──────────────────┬──────────────────────────┘
│ spawn node .spaceflow/bin/index.js
┌──────────────────▼──────────────────────────┐
│ @spaceflow/core（运行时） │
│ exec() → ServiceContainer → ExtensionLoader │
│ → Commander.js 程序构建 → 执行命令 │
└──────────────────┬──────────────────────────┘
│ defineExtension()
┌──────────────────▼──────────────────────────┐
│ Extension（内置 + 外部） │
│ commands[] + services[] + mcp? + hooks │
└─────────────────────────────────────────────┘
```
## 核心包
### `@spaceflow/cli`
CLI 壳子入口。只使用 Node.js 内置模块（`fs`/`path`/`child_process`/`os`）和 `@spaceflow/shared`。通过 `bin` 字段注册 `spaceflow` 和 `space` 两个命令。
职责：
1. 确保 `.spaceflow/` 目录和 `package.json` 存在
2. 确保依赖已安装（`pnpm install`）
3. 读取配置文件中的外部扩展列表
4. 生成 `.spaceflow/bin/index.js`（动态 import 所有扩展）
5. `execSync` 执行生成的入口文件
### `@spaceflow/core`
核心能力库，提供所有 Extension 共享的基础模块。作为 npm 包发布，Extension 通过 `peerDependencies` 依赖它。
核心运行时 + 全部 13 个内置命令 + 共享基础模块。作为 npm 包发布，外部 Extension 通过 `peerDependencies` 依赖它。
主要导出：
- **Git Provider** — GitHub / Gitea 平台适配器
- **Git SDK** — Git 命令封装
- **LLM Proxy** — 多 LLM 统一代理（OpenAI、Claude 等）
- **Logger** — 日志系统（Plain 模式 + TUI 模式）
- **i18n** — 国际化工具函数
- **Config** — 配置加载与校验
- **Extension System** — Extension 接口定义
- **cli-runtime** — `exec()` 入口、`ServiceContainer` DI 容器、`ExtensionLoader` 加载器
- **extension-system** — `defineExtension()`、`ExtensionDefinition` 类型、`SpaceflowContext` 接口
- **commands** — 13 个内置命令（build/clear/commit/create/dev/install/list/mcp/runx/schema/setup/uninstall/update）
- **shared** — Git Provider、Git SDK、LLM Proxy、Logger、MCP、Storage、Parallel 等模块
- **config** — 配置加载、Zod Schema 校验、JSON Schema 生成
### `@spaceflow/cli`
### `@spaceflow/shared`
CLI 入口包，包含所有内置命令和 Extension 加载器。通过 `bin` 字段注册 `spaceflow` 和 `space` 两个命令。
轻量公共工具库，CLI 和 core 共同依赖。提供配置读写、包管理器检测、编辑器目录映射、日志级别等基础工具函数。
### 外部 Extension
@@ -95,9 +143,10 @@ CLI 入口包，包含所有内置命令和 Extension 加载器。通过 `bin`
## 配置文件
| 文件 | 说明 |
| ---------------------------------------------- | ------------------- |
| `spaceflow.json` / `.spaceflow/spaceflow.json` | 项目配置 |
| `.spaceflow/package.json` | Extension 依赖管理 |
| `pnpm-workspace.yaml` | Monorepo 工作区配置 |
| `references/*.md` | 代码审查规范文件 |
| 文件 | 说明 |
| ------------------------------------------------ | ------------------- |
| `.spaceflowrc` / `.spaceflow/spaceflow.json` | 项目配置 |
| `~/.spaceflowrc` / `~/.spaceflow/spaceflow.json` | 全局配置 |
| `.spaceflow/package.json` | Extension 依赖管理 |
| `pnpm-workspace.yaml` | Monorepo 工作区配置 |
| `references/*.md` | 代码审查规范文件 |

14
docs/index.md
View File

@@ -3,8 +3,8 @@ layout: home
hero:
name: Spaceflow
text: 可扩展的 AI 工作流引擎
tagline: 统一 CI/CD 管理、AI 代码审查、多编辑器插件分发
text: 可扩展的 AI 工程化工作流平台
tagline: 插件化 CI/CD 管理、AI 代码审查、多编辑器集成
actions:
- theme: brand
text: 快速开始
@@ -18,11 +18,11 @@ features:
title: AI 代码审查
details: 基于 LLM 的自动化代码审查，支持 OpenAI、Claude 等多种模型，自动生成行内评论和 PR 描述。
- icon: 🔌
title: Extension 插件系统
details: 命令以 Extension 形式分发，支持 npm 包和本地链接，通过 spaceflow.json 统一管理。
title: Extension 扩展系统
details: 基于 defineExtension 的纯函数式扩展体系，支持 npm 包、本地路径和 Git 仓库安装。
- icon: 🛠️
title: 丰富的内置命令
details: 提供 install、build、dev、commit、review、publish 等开箱即用的命令。
details: 提供 install、build、dev、commit、setup、mcp 等 13 个开箱即用的内置命令。
- icon: 🖥️
title: 多编辑器集成
details: 一键将技能和命令关联到 Claude Code、Windsurf、Cursor、OpenCode 等 AI 编程工具。
@@ -30,6 +30,6 @@ features:
title: CI/CD 自动化
details: 预配置 GitHub Actions 工作流，支持自动 PR 审查、版本发布、自定义脚本执行。
- icon: 🌐
title: 国际化支持
details: 基于 i18next 的完整 i18n 方案，每个 Extension 自管理翻译资源，默认中文。
title: MCP 支持
details: 内置 Model Context Protocol 服务器，聚合所有扩展的 MCP 工具，一键接入 AI 编辑器。
---

79
docs/reference/cli.md
View File

@@ -1,27 +1,29 @@
# CLI 命令参考
所有 Spaceflow CLI 命令的完整参考。
所有 Spaceflow CLI 命令的完整参考。命令通过 `spaceflow` 或简写 `space` 调用。
## 全局选项
| 选项 | 简写 | 说明 |
| ----------- | ---- | ----------------------------------------- |
| `--help` | `-h` | 显示帮助信息 |
| `--version` | `-V` | 显示版本号 |
| `--verbose` | `-v` | 详细日志（`-v` 基本日志，`-vv` 详细日志） |
| `--dry-run` | | 试运行，不实际执行 |
| `--ci` | | CI 模式 |
| 选项 | 简写 | 说明 |
| ----------- | ---- | ------------------------------------------------------ |
| `--help` | `-h` | 显示帮助信息 |
| `--version` | `-V` | 显示版本号 |
| `--verbose` | `-v` | 详细日志（可叠加：`-v` 基本，`-vv` 详细，`-vvv` 调试） |
## 内置命令
以下命令内置于 `@spaceflow/core`，无需安装即可使用。
### `install`
安装 Extension。
安装 Extension。别名 `i`。
```bash
spaceflow install <package> # 安装指定 Extension
spaceflow install # 安装 spaceflow.json 中所有 dependencies
spaceflow install <package> -g # 全局安装
spaceflow install [source] # 安装指定 Extension
spaceflow install # 安装配置文件中所有 dependencies
spaceflow install <source> -g # 全局安装
spaceflow install <source> -n name # 指定安装名称
spaceflow install <source> -r tag # 指定版本/分支/tag
```
### `uninstall`
@@ -29,7 +31,8 @@ spaceflow install <package> -g # 全局安装
卸载 Extension。
```bash
spaceflow uninstall <name>
spaceflow uninstall <name> # 本地卸载
spaceflow uninstall <name> -g # 全局卸载
```
### `update`
@@ -39,6 +42,7 @@ spaceflow uninstall <name>
```bash
spaceflow update # 更新所有
spaceflow update <name> # 更新指定 Extension
spaceflow update --self # 更新 CLI 自身
```
### `list`
@@ -67,47 +71,53 @@ spaceflow list
```bash
spaceflow build # 构建所有
spaceflow build --watch # 监听模式
spaceflow build <name> # 构建指定 Extension
spaceflow build --watch # 监听模式
```
### `dev`
开发模式，监听文件变化并自动重新构建。
开发模式，等价于 `build --watch`。
```bash
spaceflow dev
spaceflow dev <name>
spaceflow dev # 监听并构建所有
spaceflow dev <name> # 监听并构建指定 Extension
```
### `create`
创建新的 Extension 模板。
基于模板创建新的 Extension 项目。
```bash
spaceflow create <name> # 创建命令型 Extension
spaceflow create <name> --skill # 创建技能型 Extension
spaceflow create command <name> # 创建命令型 Extension
spaceflow create mcp <name> # 创建 MCP Server Extension
spaceflow create skills <name> # 创建技能型 Extension
spaceflow create --list # 查看可用模板
spaceflow create --from <repo> command <name> # 使用远程模板
```
### `commit`
Git 提交辅助，基于 Conventional Commits 规范。
AI 智能提交，基于 Conventional Commits 规范自动生成 commit message。
```bash
spaceflow commit
spaceflow commit # 自动生成 commit message
spaceflow commit --split # 智能拆分为多个 commit
spaceflow commit --scope <scope> # 指定 scope
```
### `setup`
同步编辑器配置。
初始化 Spaceflow 项目配置。
```bash
spaceflow setup # 同步所有已配置编辑器
spaceflow setup # 本地初始化
spaceflow setup -g # 全局初始化
```
### `schema`
生成 `spaceflow.json` 的 JSON Schema。
生成配置文件的 JSON Schema。
```bash
spaceflow schema
@@ -115,31 +125,32 @@ spaceflow schema
### `mcp`
启动 MCP（Model Context Protocol）服务。
启动 MCP（Model Context Protocol）服务器。
```bash
spaceflow mcp
spaceflow mcp # 启动 MCP Server
spaceflow mcp --inspector # 启动 MCP Inspector 调试模式
```
### `runx`
运行外部命令，透传参数。
全局安装并运行 Extension 命令。别名 `x`。
```bash
spaceflow runx <source> -- <args>
# 简写
spaceflow x <source> -- <args>
spaceflow x <source> -- <args> # 运行并透传参数
spaceflow runx <source> -n name -- <args>
```
### `clear`
清理缓存和临时文件。
清理缓存、依赖和编辑器关联文件。
```bash
spaceflow clear
spaceflow clear # 清理本地
spaceflow clear -g # 清理全局
```
## 外部命令
## 扩展命令
以下命令需要先安装对应的 Extension。

47
docs/reference/config.md
View File

@@ -1,6 +1,6 @@
# 配置参考
`spaceflow.json` 完整配置项参考。
`spaceflow.json` / `.spaceflowrc` 完整配置项参考。
## 配置文件位置
@@ -17,9 +17,19 @@
```json
{
"$schema": "./.spaceflow/config-schema.json",
"$schema": ".spaceflow/config-schema.json",
"lang": "zh-CN",
"support": ["claudeCode", "windsurf", "cursor"],
"gitProvider": {
"provider": "github",
"serverUrl": "https://api.github.com"
},
"dependencies": {
"@spaceflow/review": "latest",
"@spaceflow/publish": "workspace:*",
"@spaceflow/shell": "link:./extensions/shell",
"@spaceflow/scripts": "link:./extensions/scripts"
},
"review": {
"references": ["./references", "https://github.com/org/review-spec"],
"includes": ["*/**/*.ts", "!*/**/*.spec.*", "!*/**/*.config.*"],
@@ -57,14 +67,16 @@
"versionArgs": ["--workspaces false"]
},
"git": {
"lockBranch": false,
"pushWhitelistUsernames": ["github-actions[bot]"]
}
},
"dependencies": {
"@spaceflow/review": "link:./extensions/review",
"@spaceflow/publish": "link:./extensions/publish",
"@spaceflow/shell": "link:./extensions/shell",
"@spaceflow/scripts": "link:./extensions/scripts"
"commit": {
"strategy": "rules-first",
"rules": [
{ "pattern": "docs/**", "scope": "docs" },
{ "pattern": ".github/**", "scope": "ci" }
]
}
}
```
@@ -75,7 +87,7 @@
- **类型**：`string`
- **说明**：JSON Schema 路径，用于编辑器自动补全
- **示例**：`"./.spaceflow/config-schema.json"`
- **示例**：`".spaceflow/config-schema.json"`
### `lang`
@@ -95,8 +107,17 @@
- **类型**：`Record<string, string>`
- **说明**：已安装的外部 Extension 注册表，由 `spaceflow install` 自动管理
## gitProvider 配置
| 字段 | 类型 | 默认值 | 说明 |
| ----------- | -------- | ---------- | ------------------------------------------------- |
| `provider` | `string` | `"github"` | Git 平台类型：`"github"` / `"gitea"` / `"gitlab"` |
| `serverUrl` | `string` | 自动检测 | 平台 API 地址 |
## review 配置
需安装 `@spaceflow/review`。
| 字段 | 类型 | 默认值 | 说明 |
| ---------------------- | ---------- | ------------- | -------------------------------------- |
| `references` | `string[]` | `[]` | 审查规范来源（本地目录或远程仓库 URL） |
@@ -123,6 +144,8 @@
## publish 配置
需安装 `@spaceflow/publish`。
### `publish.monorepo`
| 字段 | 类型 | 默认值 | 说明 |
@@ -147,4 +170,12 @@
| 字段 | 类型 | 说明 |
| ------------------------ | ---------- | ---------------------- |
| `lockBranch` | `boolean` | 发布时是否锁定分支 |
| `pushWhitelistUsernames` | `string[]` | 允许推送的用户名白名单 |
## commit 配置
| 字段 | 类型 | 默认值 | 说明 |
| ---------- | ---------- | --------------- | ----------------------------- |
| `strategy` | `string` | `"rules-first"` | Scope 策略 |
| `rules` | `object[]` | `[]` | Scope 规则（pattern + scope） |