@fastgpt-plugin/cli 0.1.0-beta.9 → 0.2.0-alpha.1

package/README.en.md

@@ -0,0 +1,71 @@
+## @fastgpt-plugin/cli
+
+Language: [简体中文](./README.md) | [English](./README.en.md)
+
+Command-line tool for FastGPT plugin development. It is used to create, build, test, debug, and package FastGPT tools and tool suites.
+
+### Features
+
+- **Unified build flow**
+  - Uses `tsdown` to build TypeScript source into Node 22-compatible `dist` artifacts with one command.
+  - Automatically generates d.ts type declarations for references from other packages.
+- **Tool and tool-suite specific build**
+  - Supports a tool directory as the entry, including files such as `config.ts` and `index.ts`.
+  - Applies AST transforms to `config.ts` in a temporary directory and automatically injects required metadata such as `toolId` and version.
+  - Recursively copies source directories while skipping `node_modules`, `dist`, `.build-*`, and similar folders.
+- **Safe build behavior**
+  - Does not call `process.exit` during build. Errors are thrown as exceptions so upper-level scripts can handle them uniformly.
+  - Automatically creates a temporary build directory and cleans it after build.
+- **Test-friendly**
+  - Includes Vitest configuration for unit-testing build logic.
+  - Skips bundling some dependencies in the test environment, making builds faster and more stable.
+- **Plugin scaffolding**
+  - Provides the `create` command for generating single-tool or tool-suite projects.
+  - Templates include `index.ts`, `package.json`, `tsconfig.json`, `vitest.config.ts`, `README.md`, and `logo.svg`.
+- **Local debugging**
+  - Provides the `debug` command to inspect plugin and child-tool information.
+  - Supports running tools directly, passing input/secrets/systemVar files, and simulating `uploadFile` with a local directory.
+- **Integrated development sessions**
+  - Provides the `dev` command to create a Connection Gateway WSS remote-debug channel.
+  - Supports mounting multiple local plugins on one channel for FastGPT test environments.
+- **Packaging**
+  - Provides the `pack` command to package `dist` artifacts into an uploadable `.pkg`.
+
+### Remote Debugging
+
+Local plugins can connect to a test-environment plugin-server through a long-lived FastGPT connection key. The recommended path is for FastGPT to authenticate the user and enable the debug channel, while the CLI exchanges the connection key for a short-lived WSS connect token.
+
+```bash
+fastgpt-plugin dev
+```
+
+After startup, paste the FastGPT-generated connection key into the TUI. Scripts and Agents can pass it explicitly:
+
+```bash
+fastgpt-plugin dev --no-interactive \
+  --connect "fpg_dbg_..."
+```
+
+When passing a raw connection key, set `FASTGPT_PLUGIN_DEBUG_CONNECT_URL`, or set `FASTGPT_PLUGIN_SERVER_URL` so the CLI can request `/api/plugin/debug-sessions/connection-key:exchange`. Full connect links remain supported for compatibility. The exchange result returns the gateway WSS endpoint, `debug:tmbId:{tmbId}` source, and scoped connect token. The CLI does not need `CONNECTION_GATEWAY_AUTH_TOKEN` or `JWT_SECRET`.
+
+When no plugin directories are passed, `dev` auto-discovers plugins from the current directory. If the current directory has `index.ts`, it is used as the plugin entry; otherwise, the CLI scans one level of child directories for `index.ts`. You can still pass multiple plugin directories explicitly.
+
+```bash
+fastgpt-plugin dev ./plugins/getTime ./plugins/dbops --watch
+```
+
+One CLI process creates one WSS channel and mounts all discovered or passed plugin entries. Reconnect is enabled by default. Use `--no-reconnect` to disable reconnect. Add `--watch` during development to reload local plugins and recreate the remote debug session when files change.
+
+`debug --connect` remains as a compatibility entrypoint, but new remote integration debugging should use `dev`. `debug` stays focused on single-plugin local inspection and one-shot runs.
+
+### TODO
+
+- **Publish capabilities**
+  - Provide `cli publish` to publish built tool packages to npm or an internal artifact registry.
+  - Read versions from `config.ts` / `package.json` and validate duplicate versions.
+  - Integrate changelog generation and git tag flow.
+  - Provide an optional dry-run mode that only prints planned operations.
+  - Support custom npm registry and token configuration through environment variables or config files.
+- **Developer experience improvements**
+  - `watch` mode: rebuild automatically when source files change.
+  - Friendlier build logs and error messages.

package/README.md

@@ -1,5 +1,7 @@
 ## @fastgpt-plugin/cli
 
+语言：[简体中文](./README.md) | [English](./README.en.md)
+
 FastGPT 插件开发的命令行工具，用于创建、构建和测试 FastGPT 工具 / 工具集。
 
 ### Features
@@ -17,6 +19,44 @@ FastGPT 插件开发的命令行工具，用于创建、构建和测试 FastGPT
 - **测试友好**
   - 内置 Vitest 配置，支持对构建逻辑进行单元测试
   - 在测试环境下跳过对部分依赖的打包，构建更快更稳定
+- **插件脚手架**
+  - 提供 `create` 命令生成单工具或工具集项目
+  - 模板包含 `index.ts`、`package.json`、`tsconfig.json`、`vitest.config.ts`、`README.md` 和 `logo.svg`
+- **本地调试**
+  - 提供 `debug` 命令查看插件和子工具信息
+  - 支持直接运行工具、传入 input/secrets/systemVar 文件，并用本地目录模拟 `uploadFile`
+- **集成开发会话**
+  - 提供 `dev` 命令通过 Connection Gateway 建立 WSS 远程调试通道
+  - 支持在一个通道内挂载多个本地插件，适合接入 FastGPT 测试环境
+- **打包**
+  - 提供 `pack` 命令把 `dist` 产物打成可上传的 `.pkg`
+
+### 远程调试
+
+本地插件可以通过 FastGPT 生成的长期 connection key 接入测试环境的 plugin-server。推荐路径是由 FastGPT 完成用户鉴权并开启 debug channel，CLI 使用 connection key 换取短期 WSS connect token。
+
+```bash
+fastgpt-plugin dev
+```
+
+启动后把 FastGPT 页面生成的 connection key 粘贴到 TUI 中即可。脚本或 Agent 场景可以显式传入：
+
+```bash
+fastgpt-plugin dev --no-interactive \
+  --connect "fpg_dbg_..."
+```
+
+使用裸 connection key 时，需要设置 `FASTGPT_PLUGIN_DEBUG_CONNECT_URL`，或设置 `FASTGPT_PLUGIN_SERVER_URL` 让 CLI 默认请求 `/api/plugin/debug-sessions/connection-key:exchange`。兼容场景仍可传入完整 connect link。exchange 结果会返回 gateway WSS 地址、`debug:tmbId:{tmbId}` source 和 scoped connect token。CLI 不需要 `CONNECTION_GATEWAY_AUTH_TOKEN` 或 `JWT_SECRET`。
+
+`dev` 未传插件目录时会自动探测当前目录：如果当前目录有 `index.ts`，则把当前目录作为插件；否则扫描当前目录下一层子目录中的 `index.ts`。也可以手动传入多个插件目录。
+
+```bash
+fastgpt-plugin dev ./plugins/getTime ./plugins/dbops --watch
+```
+
+同一个 CLI 进程会建立 1 个 WSS 通道并挂载所有发现或传入的插件。断线后默认自动重连；如需关闭自动重连，可加 `--no-reconnect`。开发时可加 `--watch`，文件变化后会自动重载本地插件并重新建立远程调试会话。
+
+`debug --connect` 仍作为兼容入口保留，但新的远程集成调试应使用 `dev`。`debug` 会继续聚焦单插件本地查看和一次性运行。
 
 ### 待实现 / TODO
 
@@ -26,9 +66,6 @@ FastGPT 插件开发的命令行工具，用于创建、构建和测试 FastGPT
   - 集成变更日志（changelog）生成和打 tag 流程
   - 可选的 dry-run 模式（仅输出将要执行的操作，不真正发布）
   - 支持自定义 npm registry / token 配置（环境变量或配置文件）
-- **项目脚手架**
-  - 新建单工具模板（含 `config.ts`、`src/index.ts`、测试和示例）
-  - 新建工具集模板（含 children 目录、共享配置示例）
 - **更多开发体验优化**
-  - `watch` 模式：监听源码变化自动重新构建
+  - 构建 `watch` 模式：监听源码变化自动重新构建
   - 输出更友好的构建日志和错误提示