fengming 0.3.9 → 0.3.11

package/docs/providers/perplexity-provider.md

@@ -1,123 +0,0 @@
----
-summary: "Perplexity web search provider setup (API key, search modes, filtering)"
-title: "Perplexity"
-read_when:
-  - You want to configure Perplexity as a web search provider
-  - You need the Perplexity API key or OpenRouter proxy setup
----
-
-The Perplexity plugin provides web search capabilities through the Perplexity
-Search API or Perplexity Sonar via OpenRouter.
-
-<Note>
-This page is the Perplexity **provider** setup. For the Perplexity **tool** (how the agent uses it), see [Perplexity tool](/tools/perplexity-search).
-</Note>
-
-| Property    | Value                                                                  |
-| ----------- | ---------------------------------------------------------------------- |
-| Type        | Web search provider (not a model provider)                             |
-| Auth        | `PERPLEXITY_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter) |
-| Config path | `plugins.entries.perplexity.config.webSearch.apiKey`                   |
-
-## Getting started
-
-<Steps>
-  <Step title="Set the API key">
-    Run the interactive web-search configuration flow:
-
-    ```bash
-    fengming configure --section web
-    ```
-
-    Or set the key directly:
-
-    ```bash
-    fengming config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"
-    ```
-
-  </Step>
-  <Step title="Start searching">
-    The agent will automatically use Perplexity for web searches once the key is
-    configured. No additional steps are required.
-  </Step>
-</Steps>
-
-## Search modes
-
-The plugin auto-selects the transport based on API key prefix:
-
-<Tabs>
-  <Tab title="Native Perplexity API (pplx-)">
-    When your key starts with `pplx-`, FengMing uses the native Perplexity Search
-    API. This transport returns structured results and supports domain, language,
-    and date filters (see filtering options below).
-  </Tab>
-  <Tab title="OpenRouter / Sonar (sk-or-)">
-    When your key starts with `sk-or-`, FengMing routes through OpenRouter using
-    the Perplexity Sonar model. This transport returns AI-synthesized answers with
-    citations.
-  </Tab>
-</Tabs>
-
-| Key prefix | Transport                    | Features                                         |
-| ---------- | ---------------------------- | ------------------------------------------------ |
-| `pplx-`    | Native Perplexity Search API | Structured results, domain/language/date filters |
-| `sk-or-`   | OpenRouter (Sonar)           | AI-synthesized answers with citations            |
-
-## Native API filtering
-
-<Note>
-Filtering options are only available when using the native Perplexity API
-(`pplx-` key). OpenRouter/Sonar searches do not support these parameters.
-</Note>
-
-When using the native Perplexity API, searches support the following filters:
-
-| Filter         | Description                            | Example                             |
-| -------------- | -------------------------------------- | ----------------------------------- |
-| Country        | 2-letter country code                  | `us`, `de`, `jp`                    |
-| Language       | ISO 639-1 language code                | `en`, `fr`, `zh`                    |
-| Date range     | Recency window                         | `day`, `week`, `month`, `year`      |
-| Domain filters | Allowlist or denylist (max 20 domains) | `example.com`                       |
-| Content budget | Token limits per response / per page   | `max_tokens`, `max_tokens_per_page` |
-
-## Advanced configuration
-
-<AccordionGroup>
-  <Accordion title="Environment variable for daemon processes">
-    If the FengMing Gateway runs as a daemon (launchd/systemd), make sure
-    `PERPLEXITY_API_KEY` is available to that process.
-
-    <Warning>
-    A key exported only in an interactive shell will not be visible to a
-    launchd/systemd daemon unless that environment is explicitly imported. Set
-    the key in `~/.fengming/.env` or via `env.shellEnv` to ensure the gateway
-    process can read it.
-    </Warning>
-
-  </Accordion>
-
-  <Accordion title="OpenRouter proxy setup">
-    If you prefer to route Perplexity searches through OpenRouter, set an
-    `OPENROUTER_API_KEY` (prefix `sk-or-`) instead of a native Perplexity key.
-    FengMing will detect the prefix and switch to the Sonar transport
-    automatically.
-
-    <Tip>
-    The OpenRouter transport is useful if you already have an OpenRouter account
-    and want consolidated billing across multiple providers.
-    </Tip>
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Perplexity search tool" href="/tools/perplexity-search" icon="magnifying-glass">
-    How the agent invokes Perplexity searches and interprets results.
-  </Card>
-  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
-    Full configuration reference including plugin entries.
-  </Card>
-</CardGroup>

package/docs/providers/pixverse.md

@@ -1,165 +0,0 @@
----
-summary: "PixVerse video generation setup in FengMing"
-title: "PixVerse"
-read_when:
-  - You want to use PixVerse video generation in FengMing
-  - You need the PixVerse API key/env setup
-  - You want to make PixVerse the default video provider
----
-
-FengMing provides `pixverse` as an official external plugin for hosted PixVerse video generation. The plugin registers the `pixverse` provider against the `videoGenerationProviders` contract.
-
-| Property           | Value                                                                |
-| ------------------ | -------------------------------------------------------------------- |
-| Provider id        | `pixverse`                                                           |
-| Plugin package     | `@fengming/pixverse-provider`                                        |
-| Auth env var       | `PIXVERSE_API_KEY`                                                   |
-| Onboarding flag    | `--auth-choice pixverse-api-key`                                     |
-| Direct CLI flag    | `--pixverse-api-key <key>`                                           |
-| API                | PixVerse Platform API v2 (`video_id` submission plus result polling) |
-| Default model      | `pixverse/v6`                                                        |
-| Default API region | International                                                        |
-
-## Getting started
-
-<Steps>
-  <Step title="Install the plugin">
-    ```bash
-    fengming plugins install clawhub:@fengming/pixverse-provider
-    fengming gateway restart
-    ```
-  </Step>
-  <Step title="Set the API key">
-    ```bash
-    fengming onboard --auth-choice pixverse-api-key
-    ```
-
-    The wizard asks whether to use the International endpoint
-    (`https://app-api.pixverse.ai/openapi/v2`) or the CN endpoint
-    (`https://app-api.pixverseai.cn/openapi/v2`) before writing `region` and
-    `baseUrl` into the provider config.
-
-  </Step>
-  <Step title="Set PixVerse as the default video provider">
-    ```bash
-    fengming config set agents.defaults.videoGenerationModel.primary "pixverse/v6"
-    ```
-  </Step>
-  <Step title="Generate a video">
-    Ask the agent to generate a video. PixVerse will be used automatically.
-  </Step>
-</Steps>
-
-## Supported modes and models
-
-The provider exposes PixVerse generation models through FengMing's shared video tool.
-
-| Mode           | Models               | Reference input         |
-| -------------- | -------------------- | ----------------------- |
-| Text-to-video  | `v6` (default), `c1` | None                    |
-| Image-to-video | `v6` (default), `c1` | 1 local or remote image |
-
-Local image references are uploaded to PixVerse before the image-to-video request. Remote image URLs are passed through the PixVerse image upload endpoint as `image_url`.
-
-| Option          | Supported values                                                            |
-| --------------- | --------------------------------------------------------------------------- |
-| Duration        | 1-15 seconds                                                                |
-| Resolution      | `360P`, `540P`, `720P`, `1080P`                                             |
-| Aspect ratio    | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `2:3`, `3:2`, `21:9` for text-to-video |
-| Generated audio | `audio: true`                                                               |
-
-<Note>
-PixVerse image template generation is not exposed through `image_generate` yet. That API is template-id driven, while FengMing's shared image-generation contract does not currently have a PixVerse-specific typed option bag.
-</Note>
-
-## Provider options
-
-The video provider accepts these optional provider-specific keys:
-
-| Option                               | Type   | Effect                            |
-| ------------------------------------ | ------ | --------------------------------- |
-| `seed`                               | number | Deterministic seed when supported |
-| `negativePrompt` / `negative_prompt` | string | Negative prompt                   |
-| `quality`                            | string | PixVerse quality such as `720p`   |
-| `motionMode` / `motion_mode`         | string | Image-to-video motion mode        |
-| `cameraMovement` / `camera_movement` | string | PixVerse camera movement preset   |
-| `templateId` / `template_id`         | number | Activated PixVerse template id    |
-
-## Configuration
-
-```json5
-{
-  agents: {
-    defaults: {
-      videoGenerationModel: {
-        primary: "pixverse/v6",
-      },
-    },
-  },
-}
-```
-
-## Advanced configuration
-
-<AccordionGroup>
-  <Accordion title="API region">
-    FengMing defaults to the international PixVerse API. Set `models.providers.pixverse.region`
-    manually when your key belongs to a specific PixVerse platform region, or use
-    `fengming onboard --auth-choice pixverse-api-key` to choose one in the setup wizard:
-
-    | Region value    | PixVerse API base URL                         |
-    | --------------- | --------------------------------------------- |
-    | `international` | `https://app-api.pixverse.ai/openapi/v2`      |
-    | `cn`            | `https://app-api.pixverseai.cn/openapi/v2`    |
-
-    ```json5
-    {
-      models: {
-        providers: {
-          pixverse: {
-            region: "cn", // "international" or "cn"
-            baseUrl: "https://app-api.pixverseai.cn/openapi/v2",
-            models: [],
-          },
-        },
-      },
-    }
-    ```
-
-  </Accordion>
-
-  <Accordion title="Custom base URL">
-    Set `models.providers.pixverse.baseUrl` only when routing through a trusted compatible proxy.
-    `baseUrl` takes precedence over `region`.
-
-    ```json5
-    {
-      models: {
-        providers: {
-          pixverse: {
-            baseUrl: "https://app-api.pixverse.ai/openapi/v2",
-          },
-        },
-      },
-    }
-    ```
-
-  </Accordion>
-
-  <Accordion title="Task polling">
-    PixVerse returns a `video_id` from the generation request. FengMing polls
-    `/openapi/v2/video/result/{video_id}` until the task succeeds, fails,
-    or times out.
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Video generation" href="/tools/video-generation" icon="video">
-    Shared tool parameters, provider selection, and async behavior.
-  </Card>
-  <Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
-    Agent default settings including video generation model.
-  </Card>
-</CardGroup>

package/docs/providers/qianfan.md

@@ -1,132 +0,0 @@
----
-summary: "Use Qianfan's unified API to access many models in FengMing"
-read_when:
-  - You want a single API key for many LLMs
-  - You need Baidu Qianfan setup guidance
-title: "Qianfan"
----
-
-Qianfan is Baidu's MaaS platform, providing a **unified API** that routes requests to many models behind a single
-endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
-
-| Property | Value                             |
-| -------- | --------------------------------- |
-| Provider | `qianfan`                         |
-| Auth     | `QIANFAN_API_KEY`                 |
-| API      | OpenAI-compatible                 |
-| Base URL | `https://qianfan.baidubce.com/v2` |
-
-## Getting started
-
-<Steps>
-  <Step title="Create a Baidu Cloud account">
-    Sign up or log in at the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey) and ensure you have Qianfan API access enabled.
-  </Step>
-  <Step title="Generate an API key">
-    Create a new application or select an existing one, then generate an API key. The key format is `bce-v3/ALTAK-...`.
-  </Step>
-  <Step title="Run onboarding">
-    ```bash
-    fengming onboard --auth-choice qianfan-api-key
-    ```
-  </Step>
-  <Step title="Verify the model is available">
-    ```bash
-    fengming models list --provider qianfan
-    ```
-  </Step>
-</Steps>
-
-## Built-in catalog
-
-| Model ref                            | Input       | Context | Max output | Reasoning | Notes         |
-| ------------------------------------ | ----------- | ------- | ---------- | --------- | ------------- |
-| `qianfan/deepseek-v3.2`              | text        | 98,304  | 32,768     | Yes       | Default model |
-| `qianfan/ernie-5.0-thinking-preview` | text, image | 119,000 | 64,000     | Yes       | Multimodal    |
-
-<Tip>
-The default bundled model ref is `qianfan/deepseek-v3.2`. You only need to override `models.providers.qianfan` when you need a custom base URL or model metadata.
-</Tip>
-
-## Config example
-
-```json5
-{
-  env: { QIANFAN_API_KEY: "bce-v3/ALTAK-..." },
-  agents: {
-    defaults: {
-      model: { primary: "qianfan/deepseek-v3.2" },
-      models: {
-        "qianfan/deepseek-v3.2": { alias: "QIANFAN" },
-      },
-    },
-  },
-  models: {
-    providers: {
-      qianfan: {
-        baseUrl: "https://qianfan.baidubce.com/v2",
-        api: "openai-completions",
-        models: [
-          {
-            id: "deepseek-v3.2",
-            name: "DEEPSEEK V3.2",
-            reasoning: true,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 98304,
-            maxTokens: 32768,
-          },
-          {
-            id: "ernie-5.0-thinking-preview",
-            name: "ERNIE-5.0-Thinking-Preview",
-            reasoning: true,
-            input: ["text", "image"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 119000,
-            maxTokens: 64000,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-<AccordionGroup>
-  <Accordion title="Transport and compatibility">
-    Qianfan runs through the OpenAI-compatible transport path, not native OpenAI request shaping. This means standard OpenAI SDK features work, but provider-specific parameters may not be forwarded.
-  </Accordion>
-
-  <Accordion title="Catalog and overrides">
-    The bundled catalog currently includes `deepseek-v3.2` and `ernie-5.0-thinking-preview`. Add or override `models.providers.qianfan` only when you need a custom base URL or model metadata.
-
-    <Note>
-    Model refs use the `qianfan/` prefix (for example `qianfan/deepseek-v3.2`).
-    </Note>
-
-  </Accordion>
-
-  <Accordion title="Troubleshooting">
-    - Ensure your API key starts with `bce-v3/ALTAK-` and has Qianfan API access enabled in the Baidu Cloud console.
-    - If models are not listed, confirm your account has the Qianfan service activated.
-    - The default base URL is `https://qianfan.baidubce.com/v2`. Only change it if you use a custom endpoint or proxy.
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
-    Choosing providers, model refs, and failover behavior.
-  </Card>
-  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
-    Full FengMing configuration reference.
-  </Card>
-  <Card title="Agent setup" href="/concepts/agent" icon="robot">
-    Configuring agent defaults and model assignments.
-  </Card>
-  <Card title="Qianfan API docs" href="https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb" icon="arrow-up-right-from-square">
-    Official Qianfan API documentation.
-  </Card>
-</CardGroup>

package/docs/providers/qwen-oauth.md

@@ -1,115 +0,0 @@
----
-summary: "Use the Qwen Portal provider id with FengMing"
-read_when:
-  - You want to configure the qwen-oauth provider id
-  - You previously used Qwen Portal OAuth credentials
-  - You need the Qwen Portal endpoint or migration guidance
-title: "Qwen OAuth / Portal"
----
-
-`qwen-oauth` is the Qwen Portal provider id. It targets the Qwen Portal endpoint
-and keeps older Qwen OAuth / portal setups addressable through a distinct
-provider id.
-
-Use this provider when you specifically have a current Qwen Portal token for
-`https://portal.qwen.ai/v1`, or when you are migrating an older Qwen Portal /
-Qwen CLI setup and want to keep those credentials separate from the canonical
-Qwen Cloud provider. It is not the recommended first choice for new Qwen users.
-
-For new Qwen Cloud setups, prefer [Qwen](/providers/qwen) with the Standard
-ModelStudio endpoint unless you specifically have a current Qwen Portal token.
-
-## Setup
-
-Provide your portal token through onboarding:
-
-```bash
-fengming onboard --auth-choice qwen-oauth
-```
-
-Or set:
-
-```bash
-export QWEN_API_KEY="<your-qwen-portal-token>" # pragma: allowlist secret
-```
-
-## Defaults
-
-- Provider: `qwen-oauth`
-- Aliases: `qwen-portal`, `qwen-cli`
-- Base URL: `https://portal.qwen.ai/v1`
-- Env var: `QWEN_API_KEY`
-- API style: OpenAI-compatible
-- Default model: `qwen-oauth/qwen3.5-plus`
-
-## How this differs from Qwen
-
-FengMing has two Qwen-facing provider ids:
-
-| Provider     | Endpoint family                                          | Best for                                                                               |
-| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `qwen`       | Qwen Cloud / Alibaba DashScope and Coding Plan endpoints | New API-key setups, Standard pay-as-you-go, Coding Plan, multimodal DashScope features |
-| `qwen-oauth` | Qwen Portal endpoint at `portal.qwen.ai/v1`              | Existing Qwen Portal tokens and legacy Qwen OAuth / CLI setups                         |
-
-Both providers use OpenAI-compatible request shapes, but they are separate auth
-surfaces. A token stored for `qwen-oauth` should not be treated as a DashScope
-or ModelStudio key, and a new DashScope key should use the canonical `qwen`
-provider instead.
-
-## When to choose Qwen OAuth / Portal
-
-- You already have a working Qwen Portal token.
-- You are preserving a legacy Qwen OAuth or Qwen CLI workflow while moving to
-  FengMing's provider model.
-- You need to test compatibility with the Qwen Portal endpoint specifically.
-
-Choose [Qwen](/providers/qwen) for new setup, broader endpoint choices, Standard
-ModelStudio, Coding Plan, and the full bundled Qwen catalog.
-
-## Models
-
-The bundled catalog seeds the Qwen Portal default:
-
-- `qwen-oauth/qwen3.5-plus`
-
-Availability depends on the current Qwen Portal account and token. If your
-account uses ModelStudio / DashScope API keys instead, configure the canonical
-`qwen` provider:
-
-```bash
-fengming onboard --auth-choice qwen-standard-api-key
-fengming models set qwen/qwen3-coder-plus
-```
-
-## Migration
-
-Legacy Qwen Portal OAuth profiles may not be refreshable. If a portal profile
-stops working, re-authenticate with a current token or switch to the Standard
-Qwen provider:
-
-```bash
-fengming onboard --auth-choice qwen-standard-api-key
-```
-
-Standard global ModelStudio uses:
-
-```text
-https://dashscope-intl.aliyuncs.com/compatible-mode/v1
-```
-
-## Troubleshooting
-
-- Portal OAuth refresh failures: legacy Qwen Portal OAuth profiles may not be
-  refreshable. Re-run onboarding with a current token.
-- Wrong endpoint errors: confirm the model ref starts with `qwen-oauth/` when
-  using a portal token. Use `qwen/` refs only for the canonical Qwen provider.
-- `QWEN_API_KEY` confusion: both Qwen pages mention this env var, but onboarding
-  stores credentials under the selected provider id. Prefer onboarding when you
-  keep both `qwen` and `qwen-oauth` available on the same machine.
-
-## Related
-
-- [Qwen](/providers/qwen)
-- [Alibaba Model Studio](/providers/alibaba)
-- [Model providers](/concepts/model-providers)
-- [All providers](/providers/index)