spaceflow/docs/guide/extension-system.md

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 生命周期

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 接口：

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 语言资源

管理命令

# 安装
spaceflow install @spaceflow/review

# 卸载
spaceflow uninstall review

# 更新
spaceflow update

# 列出
spaceflow list

开发 Extension

请参考 插件开发指南 了解如何创建自定义 Extension。