@spaceflow/core 0.9.0 → 0.11.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** — 配置校验

package/dist/index.js

@@ -5471,9 +5471,9 @@ var list_namespaceObject = JSON.parse('{"description":"列出已安装的技能
 ;// CONCATENATED MODULE: ./src/locales/en/list.json
 var en_list_namespaceObject = JSON.parse('{"description":"List installed skill packages","extensionDescription":"List installed plugins/skills","noSkills":"📦 No skill packages installed","installHint":"Install skill packages with:","installedExtensions":"📦 Installed extensions ({{installed}}/{{total}}):","commands":"Commands: {{commands}}"}')
 ;// CONCATENATED MODULE: ./src/locales/zh-cn/mcp.json
-var zh_cn_mcp_namespaceObject = JSON.parse('{"description":"启动 MCP Server，提供所有已安装扩展的 MCP 工具","options.inspector":"启动 MCP Inspector 进行交互式调试","inspectorStarting":"🔍 启动 MCP Inspector...","inspectorDebugCmd":"   调试命令: pnpm space mcp","inspectorFailed":"❌ 启动 MCP Inspector 失败: {{error}}","extensionDescription":"启动 MCP Server，提供所有已安装扩展的 MCP 工具","scanning":"🔍 扫描已安装的扩展...","foundExtensions":"   发现 {{count}} 个扩展","checkingExport":"     检查 {{key}}: __mcp_server__={{hasMcpServer}}","containerSuccess":"     ✅ 从容器获取 {{key}} 实例成功","containerFailed":"     ⚠️ 从容器获取 {{key}} 失败: {{error}}","loadToolsFailed":"   ⚠️ {{name}}: 加载 MCP 工具失败","noToolsFound":"❌ 没有找到任何 MCP 工具","noToolsHint":"   提示: 确保已安装支持 MCP 的扩展，并导出 mcpService 或 getMcpTools","toolsFound":"✅ 共发现 {{count}} 个 MCP 工具","ttyHint":"💡 MCP Server 需要由 MCP 客户端（如 Cursor、Claude Desktop）通过管道启动。\\n   请将以下配置添加到你的 MCP 客户端中：\\n\\n   \\"spaceflow\\": {\\n     \\"command\\": \\"pnpm\\",\\n     \\"args\\": [\\"space\\", \\"mcp\\"]\\n   }","serverStarted":"🚀 MCP Server 已启动，共 {{count}} 个工具"}')
+var zh_cn_mcp_namespaceObject = JSON.parse('{"description":"启动 MCP Server，提供所有已安装扩展的 MCP 工具","options.inspector":"启动 MCP Inspector 进行交互式调试","inspectorStarting":"🔍 启动 MCP Inspector...","inspectorDebugCmd":"   调试命令: pnpm space mcp","inspectorFailed":"❌ 启动 MCP Inspector 失败: {{error}}","extensionDescription":"启动 MCP Server，提供所有已安装扩展的 MCP 工具","cwdInfo":"📂 工作目录: {{cwd}}","cwdEnvHint":"   💡 可通过环境变量 SPACEFLOW_CWD 指定工作区路径","scanning":"🔍 扫描已安装的扩展...","foundExtensions":"   发现 {{count}} 个扩展","checkingExport":"     检查 {{key}}: __mcp_server__={{hasMcpServer}}","containerSuccess":"     ✅ 从容器获取 {{key}} 实例成功","containerFailed":"     ⚠️ 从容器获取 {{key}} 失败: {{error}}","loadToolsFailed":"   ⚠️ {{name}}: 加载 MCP 工具失败","noToolsFound":"❌ 没有找到任何 MCP 工具","noToolsHint":"   提示: 确保已安装支持 MCP 的扩展，并导出 mcpService 或 getMcpTools\\n   如果工作目录不正确，请在 MCP 配置中设置环境变量:\\n   \\"env\\": { \\"SPACEFLOW_CWD\\": \\"/path/to/your/project\\" }","toolsFound":"✅ 共发现 {{count}} 个 MCP 工具","ttyHint":"💡 MCP Server 需要由 MCP 客户端（如 Cursor、Claude Desktop）通过管道启动。\\n   请将以下配置添加到你的 MCP 客户端中：\\n\\n   \\"spaceflow\\": {\\n     \\"command\\": \\"npx\\",\\n     \\"args\\": [\\"@spaceflow/cli\\", \\"mcp\\"],\\n     \\"env\\": { \\"SPACEFLOW_CWD\\": \\"/path/to/your/project\\" }\\n   }","serverStarted":"🚀 MCP Server 已启动，共 {{count}} 个工具"}')
 ;// CONCATENATED MODULE: ./src/locales/en/mcp.json
-var en_mcp_namespaceObject = JSON.parse('{"description":"Start MCP Server with all installed extension tools","options.inspector":"Start MCP Inspector for interactive debugging","inspectorStarting":"🔍 Starting MCP Inspector...","inspectorDebugCmd":"   Debug command: pnpm space mcp","inspectorFailed":"❌ Failed to start MCP Inspector: {{error}}","extensionDescription":"Start MCP Server with all installed extension tools","scanning":"🔍 Scanning installed extensions...","foundExtensions":"   Found {{count}} extensions","checkingExport":"     Checking {{key}}: __mcp_server__={{hasMcpServer}}","containerSuccess":"     ✅ Got {{key}} instance from container","containerFailed":"     ⚠️ Failed to get {{key}} from container: {{error}}","loadToolsFailed":"   ⚠️ {{name}}: Failed to load MCP tools","noToolsFound":"❌ No MCP tools found","noToolsHint":"   Hint: Make sure you have installed MCP-enabled extensions that export mcpService or getMcpTools","toolsFound":"✅ Found {{count}} MCP tools","ttyHint":"💡 MCP Server must be started by an MCP client (e.g. Cursor, Claude Desktop) via pipe.\\n   Add the following config to your MCP client:\\n\\n   \\"spaceflow\\": {\\n     \\"command\\": \\"pnpm\\",\\n     \\"args\\": [\\"space\\", \\"mcp\\"]\\n   }","serverStarted":"🚀 MCP Server started with {{count}} tools"}')
+var en_mcp_namespaceObject = JSON.parse('{"description":"Start MCP Server with all installed extension tools","options.inspector":"Start MCP Inspector for interactive debugging","inspectorStarting":"🔍 Starting MCP Inspector...","inspectorDebugCmd":"   Debug command: pnpm space mcp","inspectorFailed":"❌ Failed to start MCP Inspector: {{error}}","extensionDescription":"Start MCP Server with all installed extension tools","cwdInfo":"📂 Working directory: {{cwd}}","cwdEnvHint":"   💡 Set SPACEFLOW_CWD environment variable to specify workspace path","scanning":"🔍 Scanning installed extensions...","foundExtensions":"   Found {{count}} extensions","checkingExport":"     Checking {{key}}: __mcp_server__={{hasMcpServer}}","containerSuccess":"     ✅ Got {{key}} instance from container","containerFailed":"     ⚠️ Failed to get {{key}} from container: {{error}}","loadToolsFailed":"   ⚠️ {{name}}: Failed to load MCP tools","noToolsFound":"❌ No MCP tools found","noToolsHint":"   Hint: Make sure you have installed MCP-enabled extensions that export mcpService or getMcpTools\\n   If the working directory is incorrect, set the environment variable in your MCP config:\\n   \\"env\\": { \\"SPACEFLOW_CWD\\": \\"/path/to/your/project\\" }","toolsFound":"✅ Found {{count}} MCP tools","ttyHint":"💡 MCP Server must be started by an MCP client (e.g. Cursor, Claude Desktop) via pipe.\\n   Add the following config to your MCP client:\\n\\n   \\"spaceflow\\": {\\n     \\"command\\": \\"npx\\",\\n     \\"args\\": [\\"@spaceflow/cli\\", \\"mcp\\"],\\n     \\"env\\": { \\"SPACEFLOW_CWD\\": \\"/path/to/your/project\\" }\\n   }","serverStarted":"🚀 MCP Server started with {{count}} tools"}')
 ;// CONCATENATED MODULE: ./src/locales/zh-cn/runx.json
 var runx_namespaceObject = JSON.parse('{"description":"全局安装依赖并运行命令","options.name":"指定命令名称（默认从 source 自动提取）","noSource":"❌ 请指定要运行的依赖源","usage":"   用法: spaceflow x <source> [args...]","runFailed":"❌ 运行失败: {{error}}","extensionDescription":"执行插件提供的脚本命令","runningCommand":"▶️  运行命令: {{command}}","npxExitCode":"npx {{package}} 退出码: {{code}}","commandNotInstalled":"命令 {{name}} 未安装","commandNotBuilt":"命令 {{name}} 未构建，缺少 dist/index.js","pluginNoExport":"插件 {{name}} 没有默认导出"}')
 ;// CONCATENATED MODULE: ./src/locales/en/runx.json
@@ -9906,6 +9906,13 @@ class McpService {
             return;
         }
         if (shouldLog(verbose, 1)) {
+            const cwd = process.env.SPACEFLOW_CWD || process.cwd();
+            console.error(i18n_t("mcp:cwdInfo", {
+                cwd
+            }));
+            if (!process.env.SPACEFLOW_CWD) {
+                console.error(i18n_t("mcp:cwdEnvHint"));
+            }
             console.error(i18n_t("mcp:scanning"));
         }
         // 获取所有扩展（已在 exec() 阶段通过 registerExtension 注册完毕）
@@ -11239,12 +11246,7 @@ class UpdateService {
 
 
 
-/**
- * Core.exec() — CLI 运行时入口
- * 接收外部扩展列表，结合内部扩展，构建并执行 commander 程序
- *
- * @param extensions 外部扩展定义列表（来自 .spaceflow/bin/index.js 的静态导入）
- */ async function exec(extensions = []) {
+async function exec(extensions = [], options = {}) {
     // 1. 初始化 i18n（如果尚未初始化，由生成的 bin/index.js 提前调用）
     initCliI18n();
     // 2. 创建并初始化服务容器
@@ -11263,7 +11265,10 @@ class UpdateService {
     }
     // 6. 创建 CLI 程序
     const program = new Command();
-    program.name("spaceflow").description("Spaceflow CLI").version("1.0.0");
+    const cliVersion = options.cliVersion || "0.0.0";
+    const coreVersion =  true ? "0.11.0" : 0;
+    const versionOutput = `spaceflow/${cliVersion} core/${coreVersion}`;
+    program.name("spaceflow").description("Spaceflow CLI").version(versionOutput, "-V, --version", "显示版本信息");
     // 定义全局 verbose 选项（支持计数：-v, -vv, -vvv）
     program.option("-v, --verbose", "详细输出（可叠加：-v, -vv, -vvv）", (_, prev)=>prev + 1, 0);
     // 全局选项列表