@spaceflow/core 0.8.0 → 0.10.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@spaceflow/core?color=blue)](https://www.npmjs.com/package/@spaceflow/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> Spaceflow 核心能力库，提供共享模块、扩展系统基础设施和平台适配层。
+> Spaceflow 核心运行时，包含 CLI 运行时引擎、13 个内置命令、扩展系统和共享模块。
 
 ## 安装
 
@@ -11,71 +11,96 @@
 pnpm add @spaceflow/core
 ```
 
-## 共享模块
+## 核心职责
 
-核心库导出以下共享模块，供扩展开发使用：
-
-| 模块              | 导入路径                          | 说明                                      |
-| ----------------- | --------------------------------- | ----------------------------------------- |
-| `git-provider`    | `@spaceflow/core`                 | Git 平台适配器（GitHub / Gitea / GitLab） |
-| `git-sdk`         | `@spaceflow/core`                 | Git 命令操作封装                          |
-| `llm-proxy`       | `@spaceflow/core/llm-proxy`       | 多 LLM 适配器（OpenAI、Claude、Gemini）   |
-| `llm-jsonput`     | `@spaceflow/core/llm-jsonput`     | LLM JSON 结构化输出                       |
-| `feishu-sdk`      | `@spaceflow/core`                 | 飞书 API 操作封装                         |
-| `storage`         | `@spaceflow/core`                 | 通用存储服务                              |
-| `logger`          | `@spaceflow/core`                 | 日志系统（TUI / Plain 双模式）            |
-| `parallel`        | `@spaceflow/core/parallel`        | 并行执行工具                              |
-| `verbose`         | `@spaceflow/core/verbose`         | 日志级别控制                              |
-| `editor-config`   | `@spaceflow/core/editor-config`   | 编辑器配置管理                            |
-| `source-utils`    | `@spaceflow/core/source-utils`    | 源码工具                                  |
-| `package-manager` | `@spaceflow/core/package-manager` | 包管理器抽象                              |
-| `rspack-config`   | `@spaceflow/core/rspack-config`   | Rspack 构建配置                           |
+- **CLI 运行时** — `exec()` 入口函数，初始化 i18n、ServiceContainer、ExtensionLoader，构建 Commander 命令树
+- **13 个内置命令** — install、uninstall、build、dev、create、update、list、clear、runx、schema、commit、setup、mcp
+- **扩展系统** — `defineExtension()` 纯函数式 API、类型定义（`ExtensionDefinition`、`CommandDefinition`、`SpaceflowContext`）
+- **共享模块** — Git、LLM、Logger、Storage 等服务
 
 ## 快速上手
 
 ```typescript
+// 扩展开发 — 使用 defineExtension 定义扩展
+import { defineExtension, t } from "@spaceflow/core";
+
+export default defineExtension({
+  name: "my-extension",
+  commands: [
+    {
+      name: "hello",
+      description: "Say hello",
+      run: async (args, options, ctx) => {
+        ctx.output.info("Hello from my extension!");
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// 共享模块 — 直接导入使用
 import {
   GitProviderService,
   GitSdkService,
   LlmProxyService,
   FeishuSdkService,
-  StorageService,
-  Logger,
-
-  // NestJS 重导出
-  Command,
-  CommandRunner,
-  Module,
-  Injectable,
+  LoggerService,
+  ParallelService,
 } from "@spaceflow/core";
 ```
 
+## 共享模块
+
+| 模块         | 说明                                      |
+| ------------ | ----------------------------------------- |
+| Git Provider | Git 平台适配器（GitHub / Gitea / GitLab） |
+| Git SDK      | Git 命令操作封装                          |
+| LLM Proxy    | 多 LLM 统一代理（OpenAI、Claude）         |
+| Logger       | 日志系统（TUI / Plain 双模式）            |
+| Feishu SDK   | 飞书 API 操作封装                         |
+| Storage      | 通用存储服务（支持 TTL）                  |
+| Parallel     | 并行执行工具                              |
+| i18n         | 国际化（i18next）                         |
+
 ## 目录结构
 
 ```text
 core/
 ├── src/
+│   ├── cli-runtime/         # CLI 运行时引擎
+│   │   ├── exec.ts          # exec() 入口
+│   │   ├── service-container.ts  # DI 容器
+│   │   ├── extension-loader.ts   # 扩展加载器
+│   │   └── internal-extensions.ts # 内置扩展注册
+│   ├── commands/            # 13 个内置命令
+│   │   ├── build/
+│   │   ├── clear/
+│   │   ├── commit/
+│   │   ├── create/
+│   │   ├── dev/
+│   │   ├── install/
+│   │   ├── list/
+│   │   ├── mcp/
+│   │   ├── runx/
+│   │   ├── schema/
+│   │   ├── setup/
+│   │   ├── uninstall/
+│   │   └── update/
 │   ├── config/              # 配置管理（Zod Schema）
 │   ├── extension-system/    # 扩展系统核心
-│   ├── locales/             # 国际化资源（i18next）
-│   ├── shared/              # 共享模块
-│   │   ├── git-provider/    # Git 平台适配器
-│   │   │   └── adapters/    # GitHub / Gitea / GitLab 实现
-│   │   ├── git-sdk/         # Git 命令封装
-│   │   ├── llm-proxy/       # LLM 统一代理
-│   │   ├── llm-jsonput/     # JSON 结构化输出
-│   │   ├── feishu-sdk/      # 飞书 SDK
-│   │   ├── logger/          # 日志系统（TUI/Plain）
-│   │   ├── parallel/        # 并行执行工具
-│   │   ├── storage/         # 通用存储服务
-│   │   ├── editor-config/   # 编辑器配置管理
-│   │   ├── verbose/         # 日志级别控制
-│   │   ├── source-utils/    # 源码工具
-│   │   ├── package-manager/ # 包管理器抽象
-│   │   └── rspack-config/   # Rspack 构建配置
-│   ├── app.module.ts        # NestJS 根模块
-│   └── index.ts             # 库导出入口
-└── test/                    # E2E 测试
+│   │   ├── types.ts         # ExtensionDefinition 等类型
+│   │   ├── define-extension.ts  # defineExtension 工厂函数
+│   │   └── extension.interface.ts # package.json spaceflow 字段解析
+│   ├── locales/             # 国际化资源（en + zh-cn）
+│   └── shared/              # 共享模块
+│       ├── git-provider/    # Git 平台适配器
+│       ├── git-sdk/         # Git 命令封装
+│       ├── llm-proxy/       # LLM 统一代理
+│       ├── feishu-sdk/      # 飞书 SDK
+│       ├── logger/          # 日志系统（TUI/Plain）
+│       ├── parallel/        # 并行执行工具
+│       └── storage/         # 通用存储服务
 ```
 
 ## 开发
@@ -84,20 +109,14 @@ core/
 # 构建
 pnpm run build
 
-# 测试
-pnpm run test
-
-# 代码检查
-pnpm run lint
-
-# 代码格式化
-pnpm run format
+# 类型检查
+pnpm run type-check
 ```
 
 ## 技术栈
 
-- **NestJS** — 依赖注入框架
-- **nest-commander** — CLI 命令框架
+- **Commander.js** — CLI 命令框架
+- **ServiceContainer** — 自定义 DI 容器
 - **Rspack** — 构建工具
 - **i18next** — 国际化
 - **Zod** — 配置校验