fengming 0.3.9 → 0.3.11

package/docs/plugins/building-plugins.md

@@ -1,335 +0,0 @@
----
-summary: "Create your first FengMing plugin in minutes"
-title: "Building plugins"
-sidebarTitle: "Getting Started"
-doc-schema-version: 1
-read_when:
-  - You want to create a new FengMing plugin
-  - You need a quick-start for plugin development
-  - You are choosing between channel, provider, CLI backend, tool, or hook docs
----
-
-Plugins extend FengMing without changing core. A plugin can add a messaging
-channel, model provider, local CLI backend, agent tool, hook, media provider,
-or another plugin-owned capability.
-
-You do not need to add an external plugin to the FengMing repository. Publish
-the package to [ClawHub](/clawhub) and users install it with:
-
-```bash
-fengming plugins install clawhub:<package-name>
-```
-
-Bare package specs still install from npm during the launch cutover. Use the
-`clawhub:` prefix when you want ClawHub resolution.
-
-## Requirements
-
-- Use Node 22.19 or newer and a package manager such as `npm` or `pnpm`.
-- Be familiar with TypeScript ESM modules.
-- For in-repo bundled plugin work, clone the repository and run `pnpm install`.
-  Source-checkout plugin development is pnpm-only because FengMing loads bundled
-  plugins from `extensions/*` workspace packages.
-
-## Choose the plugin shape
-
-<CardGroup cols={2}>
-  <Card title="Channel plugin" icon="messages-square" href="/plugins/sdk-channel-plugins">
-    Connect FengMing to a messaging platform.
-  </Card>
-  <Card title="Provider plugin" icon="cpu" href="/plugins/sdk-provider-plugins">
-    Add a model, media, search, fetch, speech, or realtime provider.
-  </Card>
-  <Card title="CLI backend plugin" icon="terminal" href="/plugins/cli-backend-plugins">
-    Run a local AI CLI through FengMing model fallback.
-  </Card>
-  <Card title="Tool plugin" icon="wrench" href="/plugins/tool-plugins">
-    Register agent tools.
-  </Card>
-</CardGroup>
-
-## Quickstart
-
-Build a minimal tool plugin by registering one required agent tool. This is the
-shortest useful plugin shape and shows the package, manifest, entry point, and
-local proof.
-
-<Steps>
-  <Step title="Create package metadata">
-    <CodeGroup>
-
-```json package.json
-{
-  "name": "@myorg/fengming-my-plugin",
-  "version": "1.0.0",
-  "type": "module",
-  "fengming": {
-    "extensions": ["./index.ts"],
-    "compat": {
-      "pluginApi": ">=2026.3.24-beta.2",
-      "minGatewayVersion": "2026.3.24-beta.2"
-    },
-    "build": {
-      "fengmingVersion": "2026.3.24-beta.2",
-      "pluginSdkVersion": "2026.3.24-beta.2"
-    }
-  }
-}
-```
-
-```json fengming.plugin.json
-{
-  "id": "my-plugin",
-  "name": "My Plugin",
-  "description": "Adds a custom tool to FengMing",
-  "contracts": {
-    "tools": ["my_tool"]
-  },
-  "activation": {
-    "onStartup": true
-  },
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false
-  }
-}
-```
-
-    </CodeGroup>
-
-    Published external plugins should point runtime entries at built JavaScript
-    files. See [SDK entry points](/plugins/sdk-entrypoints) for the full entry
-    point contract.
-
-    Every plugin needs a manifest, even when it has no config. Runtime tools
-    must appear in `contracts.tools` so FengMing can discover ownership without
-    eagerly loading every plugin runtime. Set `activation.onStartup`
-    intentionally. This example starts on Gateway startup.
-
-    For every manifest field, see [Plugin manifest](/plugins/manifest).
-
-  </Step>
-
-  <Step title="Register the tool">
-    ```typescript index.ts
-    import { Type } from "typebox";
-    import { definePluginEntry } from "fengming/plugin-sdk/plugin-entry";
-
-    export default definePluginEntry({
-      id: "my-plugin",
-      name: "My Plugin",
-      description: "Adds a custom tool to FengMing",
-      register(api) {
-        api.registerTool({
-          name: "my_tool",
-          description: "Echo one input value",
-          parameters: Type.Object({ input: Type.String() }),
-          async execute(_id, params) {
-            return {
-              content: [{ type: "text", text: `Got: ${params.input}` }],
-            };
-          },
-        });
-      },
-    });
-    ```
-
-    Use `definePluginEntry` for non-channel plugins. Channel plugins use
-    `defineChannelPluginEntry`.
-
-  </Step>
-
-  <Step title="Test the runtime">
-    For an installed or external plugin, inspect the loaded runtime:
-
-    ```bash
-    fengming plugins inspect my-plugin --runtime --json
-    ```
-
-    If the plugin registers a CLI command, run that command too. For example,
-    a demo command should have an execution proof such as
-    `fengming demo-plugin ping`.
-
-    For a bundled plugin in this repository, FengMing discovers source-checkout
-    plugin packages from the `extensions/*` workspace. Run the closest targeted
-    test:
-
-    ```bash
-    pnpm test -- extensions/my-plugin/
-    pnpm check
-    ```
-
-  </Step>
-
-  <Step title="Publish">
-    Validate the package before publishing:
-
-    ```bash
-    clawhub package publish your-org/your-plugin --dry-run
-    clawhub package publish your-org/your-plugin
-    ```
-
-    The canonical ClawHub snippets live in `docs/snippets/plugin-publish/`.
-
-  </Step>
-
-  <Step title="Install">
-    Install the published package through ClawHub:
-
-    ```bash
-    fengming plugins install clawhub:your-org/your-plugin
-    ```
-
-  </Step>
-</Steps>
-
-<a id="registering-agent-tools"></a>
-
-## Registering tools
-
-Tools can be required or optional. Required tools are always available when the
-plugin is enabled. Optional tools require user opt-in.
-
-```typescript
-register(api) {
-  api.registerTool(
-    {
-      name: "workflow_tool",
-      description: "Run a workflow",
-      parameters: Type.Object({ pipeline: Type.String() }),
-      async execute(_id, params) {
-        return { content: [{ type: "text", text: params.pipeline }] };
-      },
-    },
-    { optional: true },
-  );
-}
-```
-
-Every tool registered with `api.registerTool(...)` must also be declared in the
-plugin manifest:
-
-```json
-{
-  "contracts": {
-    "tools": ["workflow_tool"]
-  },
-  "toolMetadata": {
-    "workflow_tool": {
-      "optional": true
-    }
-  }
-}
-```
-
-Users opt in with `tools.allow`:
-
-```json5
-{
-  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for all tools from one plugin
-}
-```
-
-Optional tools control whether a tool is exposed to the model. Use
-[plugin permission requests](/plugins/plugin-permission-requests) when a tool
-or hook should ask for approval after the model selects it and before the
-action runs.
-
-Use optional tools for side effects, unusual binaries, or capabilities that
-should not be exposed by default. Tool names must not conflict with core tools;
-conflicts are skipped and reported in plugin diagnostics. Malformed
-registrations, including tool descriptors without `parameters`, are skipped and
-reported the same way. Registered tools are typed functions the model can call
-after policy and allowlist checks pass.
-
-Tool factories receive a runtime-supplied context object. Use `ctx.activeModel`
-when a tool needs to log, display, or adapt to the active model for the current
-turn. The object can include `provider`, `modelId`, and `modelRef`. Treat it as
-informational runtime metadata, not as a security boundary against the local
-operator, installed plugin code, or a modified FengMing runtime. Sensitive local
-tools should still require an explicit plugin or operator opt-in and fail closed
-when active-model metadata is missing or unsuitable.
-
-The manifest declares ownership and discovery; execution still calls the live
-registered tool implementation. Keep `toolMetadata.<tool>.optional: true`
-aligned with `api.registerTool(..., { optional: true })` so FengMing can avoid
-loading that plugin runtime until the tool is explicitly allowlisted.
-
-## Import conventions
-
-Import from focused SDK subpaths:
-
-```typescript
-import { definePluginEntry } from "fengming/plugin-sdk/plugin-entry";
-import { createPluginRuntimeStore } from "fengming/plugin-sdk/runtime-store";
-```
-
-Do not import from the deprecated root barrel:
-
-```typescript
-import { definePluginEntry } from "fengming/plugin-sdk";
-```
-
-Within your plugin package, use local barrel files such as `api.ts` and
-`runtime-api.ts` for internal imports. Do not import your own plugin through an
-SDK path. Provider-specific helpers should stay in the provider package unless
-the seam is truly generic.
-
-Custom Gateway RPC methods are an advanced entry point. Keep them on a
-plugin-specific prefix; core admin namespaces such as `config.*`,
-`exec.approvals.*`, `operator.admin.*`, `wizard.*`, and `update.*` stay reserved
-and resolve to `operator.admin`. The
-`fengming/plugin-sdk/gateway-method-runtime` bridge is reserved for plugin HTTP
-routes that declare `contracts.gatewayMethodDispatch: ["authenticated-request"]`.
-
-For the full import map, see [Plugin SDK overview](/plugins/sdk-overview).
-
-## Pre-submission checklist
-
-<Check>**package.json** has correct `fengming` metadata</Check>
-<Check>**fengming.plugin.json** manifest is present and valid</Check>
-<Check>Entry point uses `defineChannelPluginEntry` or `definePluginEntry`</Check>
-<Check>All imports use focused `plugin-sdk/<subpath>` paths</Check>
-<Check>Internal imports use local modules, not SDK self-imports</Check>
-<Check>Tests pass (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
-<Check>`pnpm check` passes (in-repo plugins)</Check>
-
-## Test against beta releases
-
-1. Watch for GitHub release tags on [fengming/fengming](https://github.com/fengming/fengming/releases) and subscribe via `Watch` > `Releases`. Beta tags look like `v2026.3.N-beta.1`. You can also turn on notifications for the official FengMing X account [@fengming](https://x.com/fengming) for release announcements.
-2. Test your plugin against the beta tag as soon as it appears. The window before stable is typically only a few hours.
-3. Post in your plugin's thread in the `plugin-forum` Discord channel after testing with either `all good` or what broke. If you do not have a thread yet, create one.
-4. If something breaks, open or update an issue titled `Beta blocker: <plugin-name> - <summary>` and apply the `beta-blocker` label. Put the issue link in your thread.
-5. Open a PR to `main` titled `fix(<plugin-id>): beta blocker - <summary>` and link the issue in both the PR and your Discord thread. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation. Blockers with a PR get merged; blockers without one might ship anyway. Maintainers watch these threads during beta testing.
-6. Silence means green. If you miss the window, your fix likely lands in the next cycle.
-
-## Next steps
-
-<CardGroup cols={2}>
-  <Card title="Channel Plugins" icon="messages-square" href="/plugins/sdk-channel-plugins">
-    Build a messaging channel plugin
-  </Card>
-  <Card title="Provider Plugins" icon="cpu" href="/plugins/sdk-provider-plugins">
-    Build a model provider plugin
-  </Card>
-  <Card title="CLI Backend Plugins" icon="terminal" href="/plugins/cli-backend-plugins">
-    Register a local AI CLI backend
-  </Card>
-  <Card title="SDK Overview" icon="book-open" href="/plugins/sdk-overview">
-    Import map and registration API reference
-  </Card>
-  <Card title="Runtime Helpers" icon="settings" href="/plugins/sdk-runtime">
-    TTS, search, subagent via api.runtime
-  </Card>
-  <Card title="Testing" icon="test-tubes" href="/plugins/sdk-testing">
-    Test utilities and patterns
-  </Card>
-  <Card title="Plugin Manifest" icon="file-json" href="/plugins/manifest">
-    Full manifest schema reference
-  </Card>
-</CardGroup>
-
-## Related
-
-- [Plugin hooks](/plugins/hooks)
-- [Plugin architecture](/plugins/architecture)

package/docs/plugins/bundles.md

@@ -1,310 +0,0 @@
----
-summary: "Install and use Codex, Claude, and Cursor bundles as FengMing plugins"
-read_when:
-  - You want to install a Codex, Claude, or Cursor-compatible bundle
-  - You need to understand how FengMing maps bundle content into native features
-  - You are debugging bundle detection or missing capabilities
-title: "Plugin bundles"
----
-
-FengMing can install plugins from three external ecosystems: **Codex**, **Claude**,
-and **Cursor**. These are called **bundles** — content and metadata packs that
-FengMing maps into native features like skills, hooks, and MCP tools.
-
-<Info>
-  Bundles are **not** the same as native FengMing plugins. Native plugins run
-  in-process and can register any capability. Bundles are content packs with
-  selective feature mapping and a narrower trust boundary.
-</Info>
-
-## Why bundles exist
-
-Many useful plugins are published in Codex, Claude, or Cursor format. Instead
-of requiring authors to rewrite them as native FengMing plugins, FengMing
-detects these formats and maps their supported content into the native feature
-set. This means you can install a Claude command pack or a Codex skill bundle
-and use it immediately.
-
-## Install a bundle
-
-<Steps>
-  <Step title="Install from a directory, archive, or marketplace">
-    ```bash
-    # Local directory
-    fengming plugins install ./my-bundle
-
-    # Archive
-    fengming plugins install ./my-bundle.tgz
-
-    # Claude marketplace
-    fengming plugins marketplace list <marketplace-name>
-    fengming plugins install <plugin-name>@<marketplace-name>
-    ```
-
-  </Step>
-
-  <Step title="Verify detection">
-    ```bash
-    fengming plugins list
-    fengming plugins inspect <id>
-    ```
-
-    Bundles show as `Format: bundle` with a subtype of `codex`, `claude`, or `cursor`.
-
-  </Step>
-
-  <Step title="Restart and use">
-    ```bash
-    fengming gateway restart
-    ```
-
-    Mapped features (skills, hooks, MCP tools, LSP defaults) are available in the next session.
-
-  </Step>
-</Steps>
-
-## What FengMing maps from bundles
-
-Not every bundle feature runs in FengMing today. Here is what works and what
-is detected but not yet wired.
-
-### Supported now
-
-| Feature       | How it maps                                                                                       | Applies to     |
-| ------------- | ------------------------------------------------------------------------------------------------- | -------------- |
-| Skill content | Bundle skill roots load as normal FengMing skills                                                 | All formats    |
-| Commands      | `commands/` and `.cursor/commands/` treated as skill roots                                        | Claude, Cursor |
-| Hook packs    | FengMing-style `HOOK.md` + `handler.ts` layouts                                                   | Codex          |
-| MCP tools     | Bundle MCP config merged into embedded FengMing settings; supported stdio and HTTP servers loaded | All formats    |
-| LSP servers   | Claude `.lsp.json` and manifest-declared `lspServers` merged into embedded FengMing LSP defaults  | Claude         |
-| Settings      | Claude `settings.json` imported as embedded FengMing defaults                                     | Claude         |
-
-#### Skill content
-
-- bundle skill roots load as normal FengMing skill roots
-- Claude `commands` roots are treated as additional skill roots
-- Cursor `.cursor/commands` roots are treated as additional skill roots
-
-This means Claude markdown command files work through the normal FengMing skill
-loader. Cursor command markdown works through the same path.
-
-#### Hook packs
-
-- bundle hook roots work **only** when they use the normal FengMing hook-pack
-  layout. Today this is primarily the Codex-compatible case:
-  - `HOOK.md`
-  - `handler.ts` or `handler.js`
-
-#### MCP for embedded FengMing
-
-- enabled bundles can contribute MCP server config
-- FengMing merges bundle MCP config into the effective embedded FengMing settings as
-  `mcpServers`
-- FengMing exposes supported bundle MCP tools during embedded FengMing agent turns by
-  launching stdio servers or connecting to HTTP servers
-- the `coding` and `messaging` tool profiles include bundle MCP tools by
-  default; use `tools.deny: ["bundle-mcp"]` to opt out for an agent or gateway
-- project-local embedded agent settings still apply after bundle defaults, so workspace
-  settings can override bundle MCP entries when needed
-- bundle MCP tool catalogs are sorted deterministically before registration, so
-  upstream `listTools()` order changes do not thrash prompt-cache tool blocks
-
-##### Transports
-
-MCP servers can use stdio or HTTP transport:
-
-**Stdio** launches a child process:
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "my-server": {
-        "command": "node",
-        "args": ["server.js"],
-        "env": { "PORT": "3000" }
-      }
-    }
-  }
-}
-```
-
-**HTTP** connects to a running MCP server over `sse` by default, or `streamable-http` when requested:
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "my-server": {
-        "url": "http://localhost:3100/mcp",
-        "transport": "streamable-http",
-        "headers": {
-          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
-        },
-        "connectionTimeoutMs": 30000
-      }
-    }
-  }
-}
-```
-
-- `transport` may be set to `"streamable-http"` or `"sse"`; when omitted, FengMing uses `sse`
-- `type: "http"` is a CLI-native downstream shape; use `transport: "streamable-http"` in FengMing config. `fengming mcp set` and `fengming doctor --fix` normalize the common alias.
-- only `http:` and `https:` URL schemes are allowed
-- `headers` values support `${ENV_VAR}` interpolation
-- a server entry with both `command` and `url` is rejected
-- URL credentials (userinfo and query params) are redacted from tool
-  descriptions and logs
-- `connectionTimeoutMs` overrides the default 30-second connection timeout for
-  both stdio and HTTP transports
-
-##### Tool naming
-
-FengMing registers bundle MCP tools with provider-safe names in the form
-`serverName__toolName`. For example, a server keyed `"vigil-harbor"` exposing a
-`memory_search` tool registers as `vigil-harbor__memory_search`.
-
-- characters outside `A-Za-z0-9_-` are replaced with `-`
-- fragments that would start with a non-letter get a letter prefix, so numeric
-  server keys such as `12306` become provider-safe tool prefixes
-- server prefixes are capped at 30 characters
-- full tool names are capped at 64 characters
-- empty server names fall back to `mcp`
-- colliding sanitized names are disambiguated with numeric suffixes
-- final exposed tool order is deterministic by safe name to keep repeated embedded-agent
-  turns cache-stable
-- profile filtering treats all tools from one bundle MCP server as plugin-owned
-  by `bundle-mcp`, so profile allowlists and deny lists can include either
-  individual exposed tool names or the `bundle-mcp` plugin key
-
-#### Embedded FengMing settings
-
-- Claude `settings.json` is imported as default embedded FengMing settings when the
-  bundle is enabled
-- FengMing sanitizes shell override keys before applying them
-
-Sanitized keys:
-
-- `shellPath`
-- `shellCommandPrefix`
-
-#### Embedded FengMing LSP
-
-- enabled Claude bundles can contribute LSP server config
-- FengMing loads `.lsp.json` plus any manifest-declared `lspServers` paths
-- bundle LSP config is merged into the effective embedded FengMing LSP defaults
-- only supported stdio-backed LSP servers are runnable today; unsupported
-  transports still show up in `fengming plugins inspect <id>`
-
-### Detected but not executed
-
-These are recognized and shown in diagnostics, but FengMing does not run them:
-
-- Claude `agents`, `hooks.json` automation, `outputStyles`
-- Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules`
-- Codex inline/app metadata beyond capability reporting
-
-## Bundle formats
-
-<AccordionGroup>
-  <Accordion title="Codex bundles">
-    Markers: `.codex-plugin/plugin.json`
-
-    Optional content: `skills/`, `hooks/`, `.mcp.json`, `.app.json`
-
-    Codex bundles fit FengMing best when they use skill roots and FengMing-style
-    hook-pack directories (`HOOK.md` + `handler.ts`).
-
-  </Accordion>
-
-  <Accordion title="Claude bundles">
-    Two detection modes:
-
-    - **Manifest-based:** `.claude-plugin/plugin.json`
-    - **Manifestless:** default Claude layout (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)
-
-    Claude-specific behavior:
-
-    - `commands/` is treated as skill content
-    - `settings.json` is imported into embedded FengMing settings (shell override keys are sanitized)
-    - `.mcp.json` exposes supported stdio tools to embedded FengMing
-    - `.lsp.json` plus manifest-declared `lspServers` paths load into embedded FengMing LSP defaults
-    - `hooks/hooks.json` is detected but not executed
-    - Custom component paths in the manifest are additive (they extend defaults, not replace them)
-
-  </Accordion>
-
-  <Accordion title="Cursor bundles">
-    Markers: `.cursor-plugin/plugin.json`
-
-    Optional content: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`
-
-    - `.cursor/commands/` is treated as skill content
-    - `.cursor/rules/`, `.cursor/agents/`, and `.cursor/hooks.json` are detect-only
-
-  </Accordion>
-</AccordionGroup>
-
-## Detection precedence
-
-FengMing checks for native plugin format first:
-
-1. `fengming.plugin.json` or valid `package.json` with `fengming.extensions` — treated as **native plugin**
-2. Bundle markers (`.codex-plugin/`, `.claude-plugin/`, or default Claude/Cursor layout) — treated as **bundle**
-
-If a directory contains both, FengMing uses the native path. This prevents
-dual-format packages from being partially installed as bundles.
-
-## Runtime dependencies and cleanup
-
-- Third-party compatible bundles do not get startup `npm install` repair. They
-  should be installed through `fengming plugins install` and ship everything
-  they need in the installed plugin directory.
-- FengMing-owned bundled plugins are either shipped lightweight in core or
-  downloadable through the plugin installer. Gateway startup never runs a
-  package manager for them.
-- `fengming doctor --fix` removes legacy staged dependency directories and can
-  recover downloadable plugins that are missing from the local plugin index when
-  config references them.
-
-## Security
-
-Bundles have a narrower trust boundary than native plugins:
-
-- FengMing does **not** load arbitrary bundle runtime modules in-process
-- Skills and hook-pack paths must stay inside the plugin root (boundary-checked)
-- Settings files are read with the same boundary checks
-- Supported stdio MCP servers may be launched as subprocesses
-
-This makes bundles safer by default, but you should still treat third-party
-bundles as trusted content for the features they do expose.
-
-## Troubleshooting
-
-<AccordionGroup>
-  <Accordion title="Bundle is detected but capabilities do not run">
-    Run `fengming plugins inspect <id>`. If a capability is listed but marked as
-    not wired, that is a product limit — not a broken install.
-  </Accordion>
-
-  <Accordion title="Claude command files do not appear">
-    Make sure the bundle is enabled and the markdown files are inside a detected
-    `commands/` or `skills/` root.
-  </Accordion>
-
-  <Accordion title="Claude settings do not apply">
-    Only embedded FengMing settings from `settings.json` are supported. FengMing does
-    not treat bundle settings as raw config patches.
-  </Accordion>
-
-  <Accordion title="Claude hooks do not execute">
-    `hooks/hooks.json` is detect-only. If you need runnable hooks, use the
-    FengMing hook-pack layout or ship a native plugin.
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-- [Install and Configure Plugins](/tools/plugin)
-- [Building Plugins](/plugins/building-plugins) — create a native plugin
-- [Plugin Manifest](/plugins/manifest) — native manifest schema