fengming 0.3.10 → 0.3.12

package/docs/tools/plugin.md

@@ -1,363 +0,0 @@
----
-summary: "Install, configure, and manage FengMing plugins"
-read_when:
-  - Installing or configuring plugins
-  - Understanding plugin discovery and load rules
-  - Working with Codex/Claude-compatible plugin bundles
-title: "Plugins"
-sidebarTitle: "Getting Started"
-doc-schema-version: 1
----
-
-Plugins extend FengMing with channels, model providers, agent harnesses, tools,
-skills, speech, realtime transcription, voice, media understanding, generation,
-web fetch, web search, and other runtime capabilities.
-
-Use this page when you want to install a plugin, restart the Gateway, verify
-that the runtime loaded it, and route common setup failures. For command-only
-examples, see [Manage plugins](/plugins/manage-plugins). For the full generated
-inventory of bundled, official external, and source-only plugins, see
-[Plugin inventory](/plugins/plugin-inventory).
-
-## Requirements
-
-Before installing a plugin, make sure you have:
-
-- an FengMing checkout or installation with the `fengming` CLI available
-- network access to the selected source, such as ClawHub, npm, or a git host
-- any plugin-specific credentials, config keys, or operating-system tools named
-  by that plugin's setup docs
-- permission for the Gateway that serves your channels to reload or restart
-
-## Quick start
-
-<Steps>
-  <Step title="Find the plugin">
-    Search [ClawHub](/clawhub) for public plugin packages:
-
-    ```bash
-    fengming plugins search "calendar"
-    ```
-
-    ClawHub is the primary discovery surface for community plugins. During the
-    launch cutover, ordinary bare package specs still install from npm unless
-    they match an official plugin id. Raw `@fengming/*` package specs that match
-    bundled plugins use the bundled copy from the current FengMing build. Use an
-    explicit prefix when you need one source.
-
-  </Step>
-
-  <Step title="Install the plugin">
-    ```bash
-    # From ClawHub.
-    fengming plugins install clawhub:<package>
-
-    # From npm.
-    fengming plugins install npm:<package>
-
-    # From git.
-    fengming plugins install git:github.com/<owner>/<repo>@<ref>
-
-    # From a local development checkout.
-    fengming plugins install ./my-plugin
-    fengming plugins install --link ./my-plugin
-    ```
-
-    Treat plugin installs like running code. Prefer pinned versions when you
-    need reproducible production installs.
-
-  </Step>
-
-  <Step title="Configure and enable it">
-    Configure plugin-specific settings under `plugins.entries.<id>.config`.
-    Enable the plugin when it is not already enabled:
-
-    ```bash
-    fengming plugins enable <plugin-id>
-    ```
-
-    If your config uses a restrictive `plugins.allow` list, the installed plugin
-    id must be present there before the plugin can load.
-    `fengming plugins install` adds the installed id to an existing
-    `plugins.allow` list and removes the same id from `plugins.deny` so the
-    explicit install can load after restart.
-
-  </Step>
-
-  <Step title="Let the Gateway reload">
-    Installing, updating, or uninstalling plugin code requires a Gateway
-    restart. When a managed Gateway is already running with config reload
-    enabled, FengMing detects the changed plugin install record and restarts the
-    Gateway automatically. If the Gateway is not managed or reload is disabled,
-    restart it yourself:
-
-    ```bash
-    fengming gateway restart
-    ```
-
-    Enable and disable operations update config and refresh the cold registry.
-    A runtime inspect is still the clearest verification path for live runtime
-    surfaces.
-
-  </Step>
-
-  <Step title="Verify runtime registration">
-    ```bash
-    fengming plugins inspect <plugin-id> --runtime --json
-    ```
-
-    Use `--runtime` when you need to prove registered tools, hooks, services,
-    Gateway methods, or plugin-owned CLI commands. Plain `inspect` is a cold
-    manifest and registry check.
-
-  </Step>
-</Steps>
-
-## Configuration
-
-### Choose an install source
-
-| Source      | Use when                                                                       | Example                                                        |
-| ----------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |
-| ClawHub     | You want FengMing-native discovery, scans, version metadata, and install hints | `fengming plugins install clawhub:<package>`                   |
-| npm         | You need direct npm registry or dist-tag workflows                             | `fengming plugins install npm:<package>`                       |
-| git         | You need a branch, tag, or commit from a repository                            | `fengming plugins install git:github.com/<owner>/<repo>@<ref>` |
-| local path  | You are developing or testing a plugin on the same machine                     | `fengming plugins install --link ./my-plugin`                  |
-| marketplace | You are installing a Claude-compatible marketplace plugin                      | `fengming plugins install <plugin> --marketplace <source>`     |
-
-Bare package specs have special compatibility behavior. If the bare name matches
-a bundled plugin id, FengMing uses that bundled source. If it matches an
-official external plugin id, FengMing uses the official package catalog. Other
-ordinary bare package specs install through npm during the launch cutover. Raw
-`@fengming/*` package specs that match bundled plugins also resolve to the
-bundled copy before npm fallback. Use `npm:@fengming/<plugin>@<version>` when
-you deliberately want the external npm package instead of the image-owned
-bundled copy. Use `clawhub:`, `npm:`, `git:`, or `npm-pack:` when you need
-deterministic source selection. See [`fengming plugins`](/cli/plugins#install)
-for the full command contract.
-
-For npm installs, unpinned package specs and `@latest` choose the newest stable
-package that advertises compatibility with this FengMing build. If npm's
-current latest release declares a newer `fengming.compat.pluginApi` or
-`fengming.install.minHostVersion`, FengMing scans older stable package versions
-and installs the newest one that fits. Exact versions and explicit channel tags
-such as `@beta` stay pinned to the selected package and fail when incompatible.
-
-### Configure plugin policy
-
-The common plugin config shape is:
-
-```json5
-{
-  plugins: {
-    enabled: true,
-    allow: ["voice-call"],
-    deny: ["untrusted-plugin"],
-    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
-    slots: { memory: "memory-core" },
-    entries: {
-      "voice-call": { enabled: true, config: { provider: "twilio" } },
-    },
-  },
-}
-```
-
-Key policy rules:
-
-- `plugins.enabled: false` disables all plugins and skips plugin discovery/load
-  work. Stale plugin references are inert while this is active; re-enable
-  plugins before running doctor cleanup when you want stale ids removed.
-- `plugins.deny` wins over allow and per-plugin enablement.
-- `plugins.allow` is an exclusive allowlist. Plugin-owned tools outside the
-  allowlist stay unavailable, even when `tools.allow` includes `"*"`.
-- `plugins.entries.<id>.enabled: false` disables one plugin while preserving its
-  config.
-- `plugins.load.paths` adds explicit local plugin files or directories.
-- Workspace-origin plugins are disabled by default; explicitly enable or
-  allowlist them before using local workspace code.
-- Bundled plugins follow their built-in default-on/default-off metadata unless
-  config explicitly overrides them.
-- `plugins.slots.<slot>` chooses one plugin for exclusive categories such as
-  memory and context engines. Slot selection force-enables the selected plugin
-  for that slot by counting as explicit activation; it can load even when it
-  would otherwise be opt-in. `plugins.deny` and
-  `plugins.entries.<id>.enabled: false` still block it.
-- Bundled opt-in plugins can auto-activate when config names one of their owned
-  surfaces, such as a provider/model ref, channel config, CLI backend, or agent
-  harness runtime.
-- OpenAI-family Codex routing keeps provider and runtime plugin boundaries
-  separate: `openai-codex/*` is legacy config repaired by doctor, while the bundled
-  `codex` plugin owns Codex app-server runtime for canonical `openai/*` agent
-  refs, explicit `agentRuntime.id: "codex"`, and legacy `codex/*` refs.
-
-Run `fengming doctor` or `fengming doctor --fix` when config validation reports
-stale plugin ids, allowlist/tool mismatches, or legacy bundled plugin paths.
-
-## Understand plugin formats
-
-FengMing recognizes two plugin formats:
-
-| Format                 | How it loads                                                                 | Use when                                                               |
-| ---------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| Native FengMing plugin | `fengming.plugin.json` plus a runtime module loaded in process               | You are installing or building FengMing-specific runtime capabilities  |
-| Compatible bundle      | Codex, Claude, or Cursor plugin layout mapped into FengMing plugin inventory | You are reusing compatible skills, commands, hooks, or bundle metadata |
-
-Both formats appear in `fengming plugins list`, `fengming plugins inspect`,
-`fengming plugins enable`, and `fengming plugins disable`. See
-[Plugin bundles](/plugins/bundles) for the bundle compatibility boundary and
-[Building plugins](/plugins/building-plugins) for native plugin authoring.
-
-## Plugin hooks
-
-Plugins can register hooks at runtime, but there are two different APIs with
-different jobs.
-
-- Use typed hooks via `api.on(...)` for runtime lifecycle hooks. This is the
-  preferred surface for middleware, policy, message rewriting, prompt shaping,
-  and tool control.
-- Use `api.registerHook(...)` only when you want to participate in the internal
-  hook system described in [Hooks](/automation/hooks). This is mainly for coarse
-  command/lifecycle side effects and compatibility with existing HOOK-style
-  automation.
-
-Quick rule:
-
-- If the handler needs priority, merge semantics, or block/cancel behavior, use
-  typed plugin hooks.
-- If the handler just reacts to `command:new`, `command:reset`, `message:sent`,
-  or similar coarse events, `api.registerHook(...)` is fine.
-
-Plugin-managed internal hooks show up in `fengming hooks list` with
-`plugin:<id>`. You cannot enable or disable them through `fengming hooks`;
-enable or disable the plugin instead.
-
-## Verify the active Gateway
-
-`fengming plugins list` and plain `fengming plugins inspect` read cold config,
-manifest, and registry state. They do not prove that an already-running Gateway
-has imported the same plugin code.
-
-When a plugin appears installed but live chat traffic does not use it:
-
-```bash
-fengming gateway status --deep --require-rpc
-fengming plugins inspect <plugin-id> --runtime --json
-fengming gateway restart
-```
-
-Managed Gateways restart automatically after plugin install, update, and
-uninstall changes that alter plugin source. On VPS or container installs, make
-sure any manual restart targets the actual `fengming gateway run` child that
-serves your channels, not only a wrapper or supervisor.
-
-## Troubleshooting
-
-| Symptom                                                        | Check                                                                                                                                      | Fix                                                                                                     |
-| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| Plugin appears in `plugins list` but runtime hooks do not run  | Use `fengming plugins inspect <id> --runtime --json` and confirm the active Gateway with `gateway status --deep --require-rpc`             | Restart the live Gateway after install, update, config, or source changes                               |
-| Duplicate channel or tool ownership diagnostics appear         | Run `fengming plugins list --enabled --verbose`, inspect each suspected plugin with `--runtime --json`, and compare channel/tool ownership | Disable one owner, remove stale installs, or use manifest `preferOver` for intentional replacement      |
-| Config says a plugin is missing                                | Check [Plugin inventory](/plugins/plugin-inventory) for whether it is bundled, official external, or source-only                           | Install the external package, enable the bundled plugin, or remove stale config                         |
-| Config is invalid during install                               | Read the validation message and run `fengming doctor --fix` when it points to stale plugin state                                           | Doctor can quarantine invalid plugin config by disabling the entry and removing the invalid payload     |
-| Plugin path is blocked for suspicious ownership or permissions | Inspect the diagnostic before the config error                                                                                             | Fix filesystem ownership/permissions, then run `fengming plugins registry --refresh`                    |
-| `FENGMING_NIX_MODE=1` blocks lifecycle commands                | Confirm the install is managed by Nix                                                                                                      | Change plugin selection in the Nix source instead of using plugin mutator commands                      |
-| Dependency import fails at runtime                             | Check whether the plugin was installed through npm/git/ClawHub or loaded from a local path                                                 | Run `fengming plugins update <id>`, reinstall the source, or install local plugin dependencies yourself |
-
-When stale plugin config still names a no-longer-discoverable channel plugin,
-Gateway startup skips that plugin-backed channel instead of blocking every
-other channel. Run `fengming doctor --fix` to remove stale plugin and channel
-entries. Unknown channel keys without stale-plugin evidence still fail
-validation so typos stay visible.
-
-For intentional channel replacement, the preferred plugin should declare
-`channelConfigs.<channel-id>.preferOver` with the legacy or lower-priority
-plugin id. If both plugins are explicitly enabled, FengMing keeps that request
-and reports duplicate channel or tool diagnostics instead of silently choosing
-one owner.
-
-If an installed package reports that it `requires compiled runtime output for
-TypeScript entry ...`, the package was published without the JavaScript files
-FengMing needs at runtime. Update or reinstall after the publisher ships
-compiled JavaScript, or disable/uninstall the plugin until then.
-
-### Blocked plugin path ownership
-
-If plugin diagnostics say
-`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
-and config validation follows with `plugin present but blocked`, FengMing found
-plugin files owned by a different Unix user than the process that is loading
-them. Keep the plugin config in place; fix the filesystem ownership or run
-FengMing as the same user that owns the state directory.
-
-For Docker installs, the official image runs as `node` (uid `1000`), so the
-host bind-mounted FengMing config and workspace directories should normally be
-owned by uid `1000`:
-
-```bash
-sudo chown -R 1000:1000 /path/to/fengming-config /path/to/fengming-workspace
-```
-
-If you intentionally run FengMing as root, repair the managed plugin root to
-root ownership instead:
-
-```bash
-sudo chown -R root:root /path/to/fengming-config/npm
-```
-
-After fixing ownership, rerun `fengming doctor --fix` or
-`fengming plugins registry --refresh` so the persisted plugin registry matches
-the repaired files.
-
-### Slow plugin tool setup
-
-If agent turns appear to stall while preparing tools, enable trace logging and
-check for plugin tool factory timing lines:
-
-```bash
-fengming config set logging.level trace
-fengming logs --follow
-```
-
-Look for:
-
-```text
-[trace:plugin-tools] factory timings ...
-```
-
-The summary lists total factory time and the slowest plugin tool factories,
-including plugin id, declared tool names, result shape, and whether the tool is
-optional. Slow lines are promoted to warnings when a single factory takes at
-least 1s or total plugin tool factory prep takes at least 5s.
-
-FengMing caches successful plugin tool factory results for repeated resolutions
-with the same effective request context. The cache key includes the effective
-runtime config, workspace, agent/session ids, sandbox policy, browser settings,
-delivery context, requester identity, and ownership state, so factories that
-depend on those trusted fields are re-run when the context changes. If timings
-stay high, the plugin may be doing expensive work before returning its tool
-definitions.
-
-If one plugin dominates the timing, inspect its runtime registrations:
-
-```bash
-fengming plugins inspect <plugin-id> --runtime --json
-```
-
-Then update, reinstall, or disable that plugin. Plugin authors should move
-expensive dependency loading behind the tool execution path instead of doing it
-inside the tool factory.
-
-For dependency roots, package metadata validation, registry records, startup
-reload behavior, and legacy cleanup, see
-[Plugin dependency resolution](/plugins/dependency-resolution).
-
-## Related
-
-- [Manage plugins](/plugins/manage-plugins) - command examples for list, install, update, uninstall, and publish
-- [`fengming plugins`](/cli/plugins) - full CLI reference
-- [Plugin inventory](/plugins/plugin-inventory) - generated bundled and external plugin list
-- [Plugin reference](/plugins/reference) - generated per-plugin reference pages
-- [Community plugins](/plugins/community) - ClawHub discovery and docs PR policy
-- [Plugin dependency resolution](/plugins/dependency-resolution) - install roots, registry records, and runtime boundaries
-- [Building plugins](/plugins/building-plugins) - native plugin authoring guide
-- [Plugin SDK overview](/plugins/sdk-overview) - runtime registration, hooks, and API fields
-- [Plugin manifest](/plugins/manifest) - manifest and package metadata

package/docs/tools/reactions.md

@@ -1,100 +0,0 @@
----
-summary: "Reaction tool semantics across all supported channels"
-read_when:
-  - Working on reactions in any channel
-  - Understanding how emoji reactions differ across platforms
-title: "Reactions"
----
-
-The agent can add and remove emoji reactions on messages using the `message`
-tool with the `react` action. Reaction behavior varies by channel and transport.
-
-## How it works
-
-```json
-{
-  "action": "react",
-  "messageId": "msg-123",
-  "emoji": "thumbsup"
-}
-```
-
-- `emoji` is required when adding a reaction.
-- Set `emoji` to an empty string (`""`) to remove the bot's reaction(s).
-- Set `remove: true` to remove a specific emoji (requires non-empty `emoji`).
-- On channels that support status reactions, `trackToolCalls: true` on a
-  reaction lets the runtime use that reacted message for subsequent tool
-  progress reactions during the same turn.
-
-## Channel behavior
-
-<AccordionGroup>
-  <Accordion title="Discord and Slack">
-    - Empty `emoji` removes all of the bot's reactions on the message.
-    - `remove: true` removes just the specified emoji.
-
-  </Accordion>
-
-  <Accordion title="Google Chat">
-    - Empty `emoji` removes the app's reactions on the message.
-    - `remove: true` removes just the specified emoji.
-
-  </Accordion>
-
-  <Accordion title="Nextcloud Talk">
-    - Adding reactions only: `emoji` is required and must be non-empty.
-    - Reaction removal is not supported yet; calls with `remove: true` (or empty `emoji`) are rejected with a clear error rather than silently no-oping.
-    - Requires the Talk bot to be registered with the `reaction` feature (see [Nextcloud Talk channel docs](/channels/nextcloud-talk)).
-
-  </Accordion>
-
-  <Accordion title="Telegram">
-    - Empty `emoji` removes the bot's reactions.
-    - `remove: true` also removes reactions but still requires a non-empty `emoji` for tool validation.
-
-  </Accordion>
-
-  <Accordion title="WhatsApp">
-    - Empty `emoji` removes the bot reaction.
-    - `remove: true` maps to empty emoji internally (still requires `emoji` in the tool call).
-    - WhatsApp has one bot reaction slot per message; status reaction updates replace that slot rather than stacking multiple emoji.
-
-  </Accordion>
-
-  <Accordion title="Zalo Personal (zalouser)">
-    - Requires non-empty `emoji`.
-    - `remove: true` removes that specific emoji reaction.
-
-  </Accordion>
-
-  <Accordion title="Feishu/Lark">
-    - Use the `feishu_reaction` tool with actions `add`, `remove`, and `list`.
-    - Add/remove requires `emoji_type`; remove also requires `reaction_id`.
-
-  </Accordion>
-
-  <Accordion title="Signal">
-    - Inbound reaction notifications are controlled by `channels.signal.reactionNotifications`: `"off"` disables them, `"own"` (default) emits events when users react to bot messages, and `"all"` emits events for all reactions.
-
-  </Accordion>
-
-  <Accordion title="iMessage">
-    - Outbound reactions are iMessage tapbacks (`love`, `like`, `dislike`, `laugh`, `emphasize`, and `question`).
-    - Inbound tapback notifications are controlled by `channels.imessage.reactionNotifications`: `"off"` disables them, `"own"` (default) emits events when users react to bot-authored messages, and `"all"` emits events for all tapbacks from authorized senders.
-
-  </Accordion>
-</AccordionGroup>
-
-## Reaction level
-
-Per-channel `reactionLevel` config controls how broadly the agent uses reactions. Values are typically `off`, `ack`, `minimal`, or `extensive`.
-
-- [Telegram reactionLevel](/channels/telegram#reaction-notifications) — `channels.telegram.reactionLevel`
-- [WhatsApp reactionLevel](/channels/whatsapp#reaction-level) — `channels.whatsapp.reactionLevel`
-
-Set `reactionLevel` on individual channels to tune how actively the agent reacts to messages on each platform.
-
-## Related
-
-- [Agent Send](/tools/agent-send) — the `message` tool that includes `react`
-- [Channels](/channels) — channel-specific configuration

package/docs/tools/searxng-search.md

@@ -1,141 +0,0 @@
----
-summary: "SearXNG web search -- self-hosted, key-free meta-search provider"
-read_when:
-  - You want a self-hosted web search provider
-  - You want to use SearXNG for web_search
-  - You need a privacy-focused or air-gapped search option
-title: "SearXNG search"
----
-
-FengMing supports [SearXNG](https://docs.searxng.org/) as a **self-hosted,
-key-free** `web_search` provider. SearXNG is an open-source meta-search engine
-that aggregates results from Google, Bing, DuckDuckGo, and other sources.
-
-Advantages:
-
-- **Free and unlimited** -- no API key or commercial subscription required
-- **Privacy / air-gap** -- queries never leave your network
-- **Works anywhere** -- no region restrictions on commercial search APIs
-
-## Setup
-
-<Steps>
-  <Step title="Run a SearXNG instance">
-    ```bash
-    docker run -d -p 8888:8080 searxng/searxng
-    ```
-
-    Or use any existing SearXNG deployment you have access to. See the
-    [SearXNG documentation](https://docs.searxng.org/) for production setup.
-
-  </Step>
-  <Step title="Configure">
-    ```bash
-    fengming configure --section web
-    # Select "searxng" as the provider
-    ```
-
-    Or set the env var and let auto-detection find it:
-
-    ```bash
-    export SEARXNG_BASE_URL="http://localhost:8888"
-    ```
-
-  </Step>
-</Steps>
-
-## Config
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        provider: "searxng",
-      },
-    },
-  },
-}
-```
-
-Plugin-level settings for the SearXNG instance:
-
-```json5
-{
-  plugins: {
-    entries: {
-      searxng: {
-        config: {
-          webSearch: {
-            baseUrl: "http://localhost:8888",
-            categories: "general,news", // optional
-            language: "en", // optional
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-The `baseUrl` field also accepts SecretRef objects.
-
-Transport rules:
-
-- `https://` works for public or private SearXNG hosts
-- `http://` is only accepted for trusted private-network or loopback hosts
-- public SearXNG hosts must use `https://`
-- private/internal hosts use the self-hosted network guard; public `https://`
-  hosts stay on the strict web-search guard and cannot redirect to private
-  addresses
-
-## Environment variable
-
-Set `SEARXNG_BASE_URL` as an alternative to config:
-
-```bash
-export SEARXNG_BASE_URL="http://localhost:8888"
-```
-
-When `SEARXNG_BASE_URL` is set and no explicit provider is configured, auto-detection
-picks SearXNG automatically (at the lowest priority -- any API-backed provider with a
-key wins first).
-
-## Plugin config reference
-
-| Field        | Description                                                        |
-| ------------ | ------------------------------------------------------------------ |
-| `baseUrl`    | Base URL of your SearXNG instance (required)                       |
-| `categories` | Comma-separated categories such as `general`, `news`, or `science` |
-| `language`   | Language code for results such as `en`, `de`, or `fr`              |
-
-## Notes
-
-- **JSON API** -- uses SearXNG's native `format=json` endpoint, not HTML scraping
-- **Image result URLs** -- image-category results include `img_src` when SearXNG
-  returns a direct image URL
-- **No API key** -- works with any SearXNG instance out of the box
-- **Base URL validation** -- `baseUrl` must be a valid `http://` or `https://`
-  URL; public hosts must use `https://`
-- **Network guard** -- private/internal SearXNG endpoints opt in to
-  private-network access; public `https://` SearXNG endpoints keep strict SSRF
-  protection
-- **Auto-detection order** -- SearXNG is checked last (order 200) in
-  auto-detection. API-backed providers with configured keys run first, then
-  DuckDuckGo (order 100), then Ollama Web Search (order 110)
-- **Self-hosted** -- you control the instance, queries, and upstream search engines
-- **Categories** default to `general` when not configured
-- **Category fallback** -- if a non-`general` category request succeeds but
-  returns zero results, FengMing retries the same query once with `general`
-  before returning an empty result set
-
-<Tip>
-  For SearXNG JSON API to work, make sure your SearXNG instance has the `json`
-  format enabled in its `settings.yml` under `search.formats`.
-</Tip>
-
-## Related
-
-- [Web Search overview](/tools/web) -- all providers and auto-detection
-- [DuckDuckGo Search](/tools/duckduckgo-search) -- another key-free fallback
-- [Brave Search](/tools/brave-search) -- structured results with free tier