From 5df49f3474fccc5d88e3d242c6c8f0e2a4fe53ed Mon Sep 17 00:00:00 2001 From: imguoguo <16666742+imguoguo@users.noreply.github.com> Date: Fri, 1 May 2026 00:36:17 +0000 Subject: [PATCH] docs: sync with upstream picoclaw v0.2.8 Synced documentation to match upstream changes since 5e44a9941023b93b3a043c729f8bbfec14275e28. Co-Authored-By: Codex --- .doc-source.json | 318 +++++++++++++++--- docs/channels/index.md | 2 + docs/channels/irc.md | 68 ++++ docs/channels/pico.md | 87 +++++ docs/configuration/config-reference.md | 111 ++++-- docs/configuration/tools.md | 26 +- .../current/channels/index.md | 2 + .../current/channels/irc.md | 68 ++++ .../current/channels/pico.md | 87 +++++ .../current/configuration/config-reference.md | 113 +++++-- .../current/configuration/tools.md | 26 +- .../current/channels/index.md | 2 + .../current/channels/irc.md | 68 ++++ .../current/channels/pico.md | 87 +++++ .../current/configuration/config-reference.md | 110 ++++-- .../current/configuration/tools.md | 26 +- sidebars.js | 2 + 17 files changed, 1090 insertions(+), 113 deletions(-) create mode 100644 docs/channels/irc.md create mode 100644 docs/channels/pico.md create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/irc.md create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/pico.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/irc.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/pico.md diff --git a/.doc-source.json b/.doc-source.json index 4ac27be..14354d6 100644 --- a/.doc-source.json +++ b/.doc-source.json @@ -1,142 +1,366 @@ { "source_repo": "https://github.com/sipeed/picoclaw", - "source_commit": "5e44a994", - "generated_at": "2026-04-09T16:30:00+08:00", + "source_commit": "6e1fab80e2f1da03605565e2dce20019d6be256f", + "generated_at": "2026-05-01T00:26:00.974Z", "docs": { "docs/intro.md": { - "source_files": ["README.md", "assets/arch.jpg"] + "source_files": [ + "README.md", + "assets/arch.jpg" + ] }, "docs/getting-started.md": { - "source_files": ["README.md", "cmd/picoclaw/internal/onboard/command.go", "pkg/config/defaults.go", "config/config.example.json"] + "source_files": [ + "README.md", + "cmd/picoclaw/internal/onboard/command.go", + "pkg/config/defaults.go", + "config/config.example.json" + ] }, "docs/installation.md": { - "source_files": ["README.md", "Makefile", "docker/Dockerfile", "docker/docker-compose.yml", ".goreleaser.yaml"] + "source_files": [ + "README.md", + "Makefile", + "docker/Dockerfile", + "docker/docker-compose.yml", + ".goreleaser.yaml" + ] }, "docs/configuration/index.md": { - "source_files": ["pkg/config/config.go", "pkg/config/config_struct.go", "pkg/config/defaults.go", "config/config.example.json", "docs/configuration.md"] + "source_files": [ + "pkg/config/config.go", + "pkg/config/config_struct.go", + "pkg/config/defaults.go", + "config/config.example.json", + "docs/guides/configuration.md" + ] }, "docs/configuration/config-reference.md": { - "source_files": ["pkg/config/config.go", "pkg/config/config_struct.go", "pkg/config/defaults.go", "config/config.example.json"] + "source_files": [ + "pkg/config/config.go", + "pkg/config/config_struct.go", + "pkg/config/defaults.go", + "config/config.example.json" + ] }, "docs/configuration/model-list.md": { - "source_files": ["pkg/config/config.go", "pkg/config/config_struct.go", "pkg/providers/factory.go", "pkg/providers/factory_provider.go", "config/config.example.json"] + "source_files": [ + "pkg/config/config.go", + "pkg/config/config_struct.go", + "pkg/providers/factory_provider.go", + "config/config.example.json" + ] }, "docs/configuration/tools.md": { - "source_files": ["pkg/config/config.go", "pkg/tools/registry.go", "pkg/tools/types.go", "pkg/tools/web.go", "pkg/tools/shell.go", "pkg/tools/filesystem.go", "pkg/tools/mcp_tool.go", "pkg/tools/cron.go", "pkg/tools/spawn.go", "pkg/tools/reaction.go", "pkg/mcp/manager.go", "docs/tools_configuration.md"] + "source_files": [ + "pkg/config/config.go", + "pkg/tools/registry.go", + "pkg/tools/shared/types.go", + "pkg/tools/integration/web.go", + "pkg/tools/shell.go", + "pkg/tools/fs/filesystem.go", + "pkg/tools/integration/mcp_tool.go", + "pkg/tools/cron.go", + "pkg/tools/spawn.go", + "pkg/tools/integration/reaction.go", + "pkg/mcp/manager.go", + "docs/reference/tools_configuration.md", + "pkg/tools/hardware/serial.go", + "pkg/tools/hardware/serial_unix.go", + "pkg/tools/hardware/serial_windows.go", + "pkg/tools/hardware/serial_darwin.go", + "pkg/tools/hardware_facade.go" + ] }, "docs/configuration/heartbeat.md": { - "source_files": ["pkg/heartbeat/service.go", "pkg/config/config.go"] + "source_files": [ + "pkg/heartbeat/service.go", + "pkg/config/config.go" + ] }, "docs/configuration/security-sandbox.md": { - "source_files": ["pkg/tools/shell.go", "pkg/tools/filesystem.go", "pkg/config/config.go", "docs/security_configuration.md"] + "source_files": [ + "pkg/tools/shell.go", + "pkg/tools/fs/filesystem.go", + "pkg/config/config.go", + "docs/security/security_configuration.md" + ] }, "docs/channels/index.md": { - "source_files": ["pkg/channels/manager.go", "pkg/channels/base.go", "pkg/channels/registry.go", "pkg/channels/interfaces.go"] + "source_files": [ + "pkg/channels/manager.go", + "pkg/channels/base.go", + "pkg/channels/registry.go", + "pkg/channels/interfaces.go" + ] }, "docs/channels/telegram.md": { - "source_files": ["pkg/channels/telegram/telegram.go", "pkg/channels/telegram/telegram_commands.go", "pkg/channels/telegram/init.go"] + "source_files": [ + "pkg/channels/telegram/telegram.go", + "pkg/channels/telegram/init.go" + ] }, "docs/channels/discord.md": { - "source_files": ["pkg/channels/discord/discord.go", "pkg/channels/discord/init.go"] + "source_files": [ + "pkg/channels/discord/discord.go", + "pkg/channels/discord/init.go" + ] }, "docs/channels/slack.md": { - "source_files": ["pkg/channels/slack/slack.go", "pkg/channels/slack/init.go"] + "source_files": [ + "pkg/channels/slack/slack.go", + "pkg/channels/slack/init.go" + ] }, "docs/channels/dingtalk.md": { - "source_files": ["pkg/channels/dingtalk/dingtalk.go", "pkg/channels/dingtalk/init.go"] + "source_files": [ + "pkg/channels/dingtalk/dingtalk.go", + "pkg/channels/dingtalk/init.go" + ] }, "docs/channels/feishu.md": { - "source_files": ["pkg/channels/feishu/feishu_64.go", "pkg/channels/feishu/feishu_32.go", "pkg/channels/feishu/common.go", "pkg/channels/feishu/feishu_reply.go", "pkg/channels/feishu/init.go"] + "source_files": [ + "pkg/channels/feishu/feishu_64.go", + "pkg/channels/feishu/feishu_32.go", + "pkg/channels/feishu/common.go", + "pkg/channels/feishu/feishu_reply.go", + "pkg/channels/feishu/init.go" + ] }, "docs/channels/wecom.md": { - "source_files": ["pkg/channels/wecom/wecom.go", "docs/channels/wecom/README.md", "docs/channels/wecom/README.zh.md"] + "source_files": [ + "pkg/channels/wecom/wecom.go", + "docs/channels/wecom/README.md", + "docs/channels/wecom/README.zh.md" + ] }, "docs/channels/qq.md": { - "source_files": ["pkg/channels/qq/qq.go", "pkg/channels/qq/init.go"] + "source_files": [ + "pkg/channels/qq/qq.go", + "pkg/channels/qq/init.go" + ] }, "docs/channels/onebot.md": { - "source_files": ["pkg/channels/onebot/onebot.go", "pkg/channels/onebot/init.go"] + "source_files": [ + "pkg/channels/onebot/onebot.go", + "pkg/channels/onebot/init.go" + ] }, "docs/channels/line.md": { - "source_files": ["pkg/channels/line/line.go", "pkg/channels/line/init.go"] + "source_files": [ + "pkg/channels/line/line.go", + "pkg/channels/line/init.go" + ] }, "docs/channels/maixcam.md": { - "source_files": ["pkg/channels/maixcam/maixcam.go", "pkg/channels/maixcam/init.go"] + "source_files": [ + "pkg/channels/maixcam/maixcam.go", + "pkg/channels/maixcam/init.go" + ] }, "docs/channels/matrix.md": { - "source_files": ["pkg/channels/matrix/matrix.go", "pkg/channels/matrix/init.go", "docs/channels/matrix/README.md", "docs/channels/matrix/README.zh.md"] + "source_files": [ + "pkg/channels/matrix/matrix.go", + "pkg/channels/matrix/init.go", + "docs/channels/matrix/README.md", + "docs/channels/matrix/README.zh.md" + ] }, "docs/channels/vk.md": { - "source_files": ["pkg/channels/vk/vk.go", "pkg/channels/vk/init.go", "docs/channels/vk/README.md"] + "source_files": [ + "pkg/channels/vk/vk.go", + "pkg/channels/vk/init.go", + "docs/channels/vk/README.md" + ] }, "docs/channels/weixin.md": { - "source_files": ["pkg/channels/weixin/weixin.go", "pkg/channels/weixin/api.go", "pkg/channels/weixin/auth.go", "pkg/channels/weixin/state.go", "docs/channels/weixin/README.md", "docs/channels/weixin/README.zh.md"] + "source_files": [ + "pkg/channels/weixin/weixin.go", + "pkg/channels/weixin/api.go", + "pkg/channels/weixin/auth.go", + "pkg/channels/weixin/state.go", + "docs/channels/weixin/README.md", + "docs/channels/weixin/README.zh.md" + ] }, "docs/channels/teams-webhook.md": { - "source_files": ["pkg/channels/teams_webhook/teams_webhook.go", "pkg/channels/teams_webhook/init.go", "pkg/config/config.go"] + "source_files": [ + "pkg/channels/teams_webhook/teams_webhook.go", + "pkg/channels/teams_webhook/init.go", + "pkg/config/config.go" + ] }, "docs/configuration/isolation.md": { - "source_files": ["pkg/isolation/README.md", "pkg/isolation/README_CN.md", "pkg/isolation/runtime.go", "pkg/isolation/platform_linux.go", "pkg/isolation/platform_windows.go", "pkg/config/config.go"] + "source_files": [ + "pkg/isolation/README.md", + "pkg/isolation/README.zh.md", + "pkg/isolation/runtime.go", + "pkg/isolation/platform_linux.go", + "pkg/isolation/platform_windows.go", + "pkg/config/config.go" + ] }, "docs/configuration/token_authentication.md": { - "source_files": ["pkg/channels/pico/pico.go", "pkg/config/config.go", "web/backend/launcherconfig/config.go", "web/backend/main.go"] + "source_files": [ + "pkg/channels/pico/pico.go", + "pkg/config/config.go", + "web/backend/launcherconfig/config.go", + "web/backend/main.go" + ] }, "docs/context-compression.md": { - "source_files": ["pkg/seahorse/short_engine.go", "pkg/seahorse/short_compaction.go", "pkg/seahorse/short_assembler.go", "pkg/seahorse/short_retrieval.go", "pkg/seahorse/short_constants.go", "pkg/seahorse/store.go", "pkg/seahorse/tool_grep.go", "pkg/seahorse/tool_expand.go", "pkg/agent/context_seahorse.go"] + "source_files": [ + "pkg/seahorse/short_engine.go", + "pkg/seahorse/short_compaction.go", + "pkg/seahorse/short_assembler.go", + "pkg/seahorse/short_retrieval.go", + "pkg/seahorse/short_constants.go", + "pkg/seahorse/store.go", + "pkg/seahorse/tool_grep.go", + "pkg/seahorse/tool_expand.go", + "pkg/agent/context_seahorse.go" + ] }, "docs/providers/index.md": { - "source_files": ["pkg/providers/factory.go", "pkg/providers/factory_provider.go", "pkg/providers/http_provider.go", "pkg/providers/openai_compat/provider.go", "pkg/providers/anthropic/provider.go", "docs/providers.md"] + "source_files": [ + "pkg/providers/factory_provider.go", + "pkg/providers/httpapi/http_provider.go", + "pkg/providers/openai_compat/provider.go", + "pkg/providers/anthropic/provider.go", + "docs/guides/providers.md" + ] }, "docs/providers/antigravity.md": { - "source_files": ["pkg/providers/antigravity_provider.go", "docs/ANTIGRAVITY_AUTH.md"] + "source_files": [ + "pkg/providers/oauth/antigravity_provider.go", + "docs/security/ANTIGRAVITY_AUTH.md" + ] }, "docs/providers/antigravity-usage.md": { - "source_files": ["pkg/providers/antigravity_provider.go", "docs/ANTIGRAVITY_USAGE.md"] + "source_files": [ + "pkg/providers/oauth/antigravity_provider.go", + "docs/guides/ANTIGRAVITY_USAGE.md" + ] }, "docs/hooks.md": { - "source_files": ["docs/hooks/README.md", "docs/hooks/hook-json-protocol.md", "docs/hooks/plugin-tool-injection.md", "pkg/agent/hooks.go", "pkg/agent/hook_process.go", "pkg/config/config.go"] + "source_files": [ + "docs/architecture/hooks/README.md", + "docs/architecture/hooks/hook-json-protocol.md", + "docs/architecture/hooks/plugin-tool-injection.md", + "pkg/agent/hooks.go", + "pkg/agent/hook_process.go", + "pkg/config/config.go" + ] }, "docs/steering.md": { - "source_files": ["docs/steering.md", "pkg/agent/steering.go", "pkg/config/config.go"] + "source_files": [ + "docs/architecture/steering.md", + "pkg/agent/steering.go", + "pkg/config/config.go" + ] }, "docs/spawn-tasks.md": { - "source_files": ["docs/spawn-tasks.md", "pkg/tools/spawn.go", "pkg/heartbeat/service.go"] + "source_files": [ + "docs/guides/spawn-tasks.md", + "pkg/tools/spawn.go", + "pkg/heartbeat/service.go" + ] }, "docs/cron.md": { - "source_files": ["docs/cron.md", "pkg/tools/cron.go", "pkg/cron/service.go"] + "source_files": [ + "docs/reference/cron.md", + "pkg/tools/cron.go", + "pkg/cron/service.go" + ] }, "docs/credential-encryption.md": { - "source_files": ["docs/credential_encryption.md", "pkg/credential/encrypt.go", "pkg/credential/decrypt.go"] + "source_files": [ + "docs/security/credential_encryption.md", + "pkg/credential/credential.go", + "pkg/credential/store.go" + ] }, "docs/sensitive-data-filtering.md": { - "source_files": ["docs/sensitive_data_filtering.md", "pkg/tools/result.go", "pkg/config/security.go"] + "source_files": [ + "docs/security/sensitive_data_filtering.md", + "pkg/tools/shared/result.go", + "pkg/config/security.go" + ] }, "docs/troubleshooting.md": { - "source_files": ["docs/troubleshooting.md"] + "source_files": [ + "docs/operations/troubleshooting.md" + ] }, "docs/docker.md": { - "source_files": ["docs/docker.md", "docker/docker-compose.yml", "docker/Dockerfile"] + "source_files": [ + "docs/guides/docker.md", + "docker/docker-compose.yml", + "docker/Dockerfile" + ] }, "docs/hardware-compatibility.md": { - "source_files": ["docs/hardware-compatibility.md", ".goreleaser.yaml"] + "source_files": [ + "docs/guides/hardware-compatibility.md", + ".goreleaser.yaml" + ] }, "docs/design/provider-refactoring.md": { - "source_files": ["docs/design/provider-refactoring.md", "pkg/providers/factory.go", "pkg/providers/fallback.go"] + "source_files": [ + "docs/design/provider-refactoring.md", + "pkg/providers/factory_provider.go", + "pkg/providers/fallback.go" + ] }, "docs/migration/model-list-migration.md": { - "source_files": ["docs/migration/model-list-migration.md", "pkg/migrate/config.go", "pkg/migrate/migrate.go"] + "source_files": [ + "docs/migration/model-list-migration.md", + "pkg/migrate/migrate.go" + ] }, "docs/contributing.md": { - "source_files": ["CONTRIBUTING.md", "CONTRIBUTING.zh.md", "Makefile"] + "source_files": [ + "CONTRIBUTING.md", + "docs/project/CONTRIBUTING.zh.md", + "Makefile" + ] }, "docs/roadmap.md": { - "source_files": ["ROADMAP.md"] + "source_files": [ + "ROADMAP.md" + ] }, "docs/changelog.md": { - "source_files": ["CHANGELOG.md"] + "source_files": [ + "README.md" + ] }, "docs/rate-limiting.md": { - "source_files": ["docs/rate-limiting.md", "pkg/providers/ratelimiter.go", "pkg/providers/fallback.go", "pkg/agent/model_resolution.go"] + "source_files": [ + "docs/reference/rate-limiting.md", + "pkg/providers/ratelimiter.go", + "pkg/providers/fallback.go", + "pkg/agent/model_resolution.go" + ] + }, + "docs/channels/irc.md": { + "source_files": [ + "pkg/channels/irc/irc.go", + "pkg/channels/irc/init.go", + "pkg/config/config.go", + "config/config.example.json" + ] + }, + "docs/channels/pico.md": { + "source_files": [ + "pkg/channels/pico/pico.go", + "pkg/channels/pico/client.go", + "pkg/channels/pico/protocol.go", + "pkg/channels/pico/init.go", + "pkg/config/config.go", + "web/backend/api/pico.go", + "config/config.example.json" + ] } } } diff --git a/docs/channels/index.md b/docs/channels/index.md index afc26a1..d92e23d 100644 --- a/docs/channels/index.md +++ b/docs/channels/index.md @@ -30,6 +30,7 @@ picoclaw gateway | **MaixCam** | Easy | Hardware-integrated AI camera. | | **VK** | Easy | VKontakte community bot via Long Poll API. | | **Pico** | Easy | Native WebSocket channel for custom clients. | +| **IRC** | Medium | IRC client connection with TLS, SASL, joins, and optional IRCv3 typing tags. | ## How It Works @@ -64,6 +65,7 @@ All channels support these optional fields: | --- | --- | | `reasoning_channel_id` | Route reasoning/thinking output to a separate channel | | `group_trigger` | Control bot behavior in group chats (mention-only, prefixes) | +| `typing` | Enable typing indicators on channels that support them | ## Shared Gateway diff --git a/docs/channels/irc.md b/docs/channels/irc.md new file mode 100644 index 0000000..44dc612 --- /dev/null +++ b/docs/channels/irc.md @@ -0,0 +1,68 @@ +--- +id: irc +title: IRC +--- + +# IRC + +The IRC channel connects PicoClaw to IRC networks through a normal IRC client connection. It supports TLS, password/SASL authentication, channel joins, group triggers, and optional IRCv3 typing tags when the server advertises `message-tags`. + +## Configuration + +```json +{ + "channels": { + "irc": { + "enabled": true, + "server": "irc.libera.chat:6697", + "tls": true, + "nick": "picoclaw-bot", + "channels": ["#mychannel"], + "allow_from": [], + "group_trigger": { + "mention_only": true + }, + "typing": { + "enabled": false + } + } + } +} +``` + +Run the gateway after saving the config: + +```bash +picoclaw gateway +``` + +## Configuration Reference + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | Enable the IRC channel | +| `server` | string | `irc.libera.chat:6697` | IRC server and port | +| `tls` | bool | `true` | Connect with TLS | +| `nick` | string | `mybot` | Bot nickname. Required. | +| `user` | string | `nick` | IRC username. Falls back to `nick` when empty. | +| `real_name` | string | `nick` | IRC real name. Falls back to `nick` when empty. | +| `password` | string | `""` | Server password, if required | +| `nickserv_password` | string | `""` | NickServ password field stored in secure config | +| `sasl_user` | string | `""` | SASL username. SASL takes priority over NickServ when configured. | +| `sasl_password` | string | `""` | SASL password kept in secure config | +| `channels` | string[] | `["#mychannel"]` | Channels to join after connecting | +| `request_caps` | string[] | `["server-time", "message-tags"]` | IRCv3 capabilities to request | +| `allow_from` | array | `[]` | Allowed IRC nicks or user IDs. Empty array allows all users. | +| `group_trigger` | object | `{ "mention_only": true }` | Require mentions or prefixes in channel messages | +| `typing.enabled` | bool | `false` | Send IRCv3 `+typing` tags when supported by the server | +| `reasoning_channel_id` | string | `""` | Route reasoning output to a separate target | + +## Authentication + +Use `sasl_user` and `sasl_password` for networks that support SASL. If SASL is not configured, you can provide `password` for server authentication. `nickserv_password` is stored as secure channel configuration, but the current IRC connector does not send NickServ commands automatically. + +Sensitive values can be stored in `.security.yml` instead of `config.json`. + +## Behavior Notes + +IRC is line-oriented, so PicoClaw sends multi-line responses as separate IRC messages. The channel uses a conservative message length limit to fit common IRC server limits. diff --git a/docs/channels/pico.md b/docs/channels/pico.md new file mode 100644 index 0000000..d392875 --- /dev/null +++ b/docs/channels/pico.md @@ -0,0 +1,87 @@ +--- +id: pico +title: Pico Protocol +--- + +# Pico Protocol + +The Pico channel is PicoClaw's native WebSocket protocol for custom clients and the web UI. It supports live messages, message edits/deletes, typing indicators, placeholders, media delivery, and tool feedback updates. + +PicoClaw can run either as the WebSocket server (`pico`) or as a client that connects to a remote Pico server (`pico_client`). + +## Server Mode + +Enable `pico` when this gateway should accept WebSocket clients. + +```json +{ + "channels": { + "pico": { + "enabled": true, + "token": "YOUR_PICO_TOKEN", + "allow_token_query": false, + "allow_origins": ["https://docs.picoclaw.io"], + "ping_interval": 30, + "read_timeout": 60, + "max_connections": 100, + "allow_from": [] + } + }, + "gateway": { + "host": "localhost", + "port": 18790 + } +} +``` + +Clients connect to the shared gateway at `/pico/ws`. Authentication uses the configured token. Query-string token authentication is disabled unless `allow_token_query` is set to `true`. + +## Client Mode + +Enable `pico_client` when this PicoClaw instance should connect outward to another Pico server. + +```json +{ + "channels": { + "pico_client": { + "enabled": true, + "url": "wss://remote-pico-server/pico/ws", + "token": "YOUR_PICO_TOKEN", + "session_id": "", + "ping_interval": 30, + "read_timeout": 60, + "allow_from": [] + } + } +} +``` + +## Server Configuration Reference + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | Enable Pico server mode | +| `token` | string | required | Shared token for client authentication | +| `allow_token_query` | bool | `false` | Allow token authentication through a query parameter | +| `allow_origins` | string[] | `[]` | Allowed browser origins. Empty array allows all origins. | +| `ping_interval` | int | `30` | WebSocket ping interval in seconds | +| `read_timeout` | int | `60` | WebSocket read timeout in seconds | +| `write_timeout` | int | `0` | Optional WebSocket write timeout in seconds | +| `max_connections` | int | `100` | Maximum active WebSocket connections | +| `allow_from` | array | `[]` | Allowed Pico session senders. Empty array allows all users. | + +## Client Configuration Reference + +| Field | Type | Default | Description | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | Enable Pico client mode | +| `url` | string | required | Remote Pico WebSocket URL | +| `token` | string | required | Shared token for remote server authentication | +| `session_id` | string | `""` | Optional fixed session ID | +| `ping_interval` | int | `30` | WebSocket ping interval in seconds | +| `read_timeout` | int | `60` | WebSocket read timeout in seconds | +| `allow_from` | array | `[]` | Allowed inbound session senders | + +## Security Notes + +Keep `token` in `.security.yml` for production deployments. If browser clients are used, configure `allow_origins` to the exact trusted origins instead of leaving it open. diff --git a/docs/configuration/config-reference.md b/docs/configuration/config-reference.md index 0b1630c..e8b2cfa 100644 --- a/docs/configuration/config-reference.md +++ b/docs/configuration/config-reference.md @@ -22,28 +22,39 @@ For day-to-day model management, Web UI is recommended. Use manual JSON editing "workspace": "~/.picoclaw/workspace", "restrict_to_workspace": true, "model_name": "gpt-5.4", - "max_tokens": 32768, - "max_tool_iterations": 50 + "max_tokens": 8192, + "context_window": 131072, + "max_tool_iterations": 20, + "summarize_message_threshold": 20, + "summarize_token_percent": 75, + "split_on_marker": false, + "tool_feedback": { + "enabled": false, + "max_args_length": 300, + "separate_messages": false + } } }, "model_list": [ - { - "model_name": "ark-code-latest", - "model": "volcengine/ark-code-latest", - "api_keys": ["sk-your-volcengine-key"] - }, { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-your-openai-key"], + "api_key": "sk-your-openai-key", "api_base": "https://api.openai.com/v1" }, { "model_name": "claude-sonnet-4.6", "model": "anthropic/claude-sonnet-4.6", - "api_keys": ["sk-ant-your-key"], - "api_base": "https://api.anthropic.com/v1" + "api_key": "sk-ant-your-key", + "api_base": "https://api.anthropic.com/v1", + "thinking_level": "high" + }, + { + "model_name": "azure-gpt5", + "model": "azure/my-gpt5-deployment", + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com" }, { "model_name": "gemini", @@ -53,18 +64,18 @@ For day-to-day model management, Web UI is recommended. Use manual JSON editing { "model_name": "deepseek", "model": "deepseek/deepseek-chat", - "api_keys": ["sk-your-deepseek-key"] + "api_key": "sk-your-deepseek-key" }, { "model_name": "loadbalanced-gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-key1"], + "api_key": "sk-key1", "api_base": "https://api1.example.com/v1" }, { "model_name": "loadbalanced-gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-key2"], + "api_key": "sk-key2", "api_base": "https://api2.example.com/v1" } ], @@ -76,6 +87,7 @@ For day-to-day model management, Web UI is recommended. Use manual JSON editing "base_url": "", "proxy": "", "allow_from": ["YOUR_USER_ID"], + "use_markdown_v2": false, "reasoning_channel_id": "" }, "discord": { @@ -93,6 +105,10 @@ For day-to-day model management, Web UI is recommended. Use manual JSON editing "app_id": "YOUR_QQ_APP_ID", "app_secret": "YOUR_QQ_APP_SECRET", "allow_from": [], + "placeholder": { + "enabled": true, + "text": ["Thinking...", "Processing...", "Typing..."] + }, "reasoning_channel_id": "" }, "maixcam": { @@ -172,29 +188,63 @@ For day-to-day model management, Web UI is recommended. Use manual JSON editing }, "placeholder": { "enabled": true, - "text": "Thinking..." + "text": ["Thinking...", "Processing...", "Typing..."] }, "reasoning_channel_id": "" + }, + "pico": { + "enabled": false, + "token": "YOUR_PICO_TOKEN", + "allow_token_query": false, + "allow_origins": [], + "ping_interval": 30, + "read_timeout": 60, + "max_connections": 100, + "allow_from": [] + }, + "irc": { + "enabled": false, + "server": "irc.libera.chat:6697", + "tls": true, + "nick": "mybot", + "channels": ["#mychannel"], + "request_caps": ["server-time", "message-tags"], + "allow_from": [], + "group_trigger": { + "mention_only": true + } } }, "tools": { + "allow_read_paths": null, + "allow_write_paths": null, "web": { + "enabled": true, + "prefer_native": true, + "fetch_limit_bytes": 10485760, + "format": "plaintext", "brave": { "enabled": false, + "api_key": "YOUR_BRAVE_API_KEY", "api_keys": ["YOUR_BRAVE_API_KEY"], "max_results": 5 }, - "duckduckgo": { + "provider": "auto", + "sogou": { "enabled": true, "max_results": 5 }, + "duckduckgo": { + "enabled": false, + "max_results": 5 + }, "perplexity": { "enabled": false, "api_keys": ["pplx-xxx"], "max_results": 5 }, - "proxy": "" + "private_host_whitelist": [] }, "mcp": { "enabled": false, @@ -221,9 +271,10 @@ For day-to-day model management, Web UI is recommended. Use manual JSON editing "exec_timeout_minutes": 5 }, "exec": { + "enabled": true, "enable_deny_patterns": true, - "custom_deny_patterns": [], - "custom_allow_patterns": [] + "custom_deny_patterns": null, + "custom_allow_patterns": null }, "skills": { "registries": { @@ -235,6 +286,9 @@ For day-to-day model management, Web UI is recommended. Use manual JSON editing "download_path": "/api/v1/download" } } + }, + "serial": { + "enabled": false } }, @@ -275,11 +329,18 @@ For day-to-day model management, Web UI is recommended. Use manual JSON editing | `model` | string | — | **Deprecated**: use `model_name` instead | | `model_fallbacks` | array | [] | Fallback model names tried in order if primary fails | | `max_tokens` | int | 32768 | Maximum tokens per response | +| `context_window` | int | 0 | Optional context window override. `0` lets the provider/model default apply. | | `temperature` | float | — | LLM temperature (omit to use provider default) | | `max_tool_iterations` | int | 50 | Maximum tool call iterations per request | +| `summarize_message_threshold` | int | 20 | Conversation message count threshold for summarization. | +| `summarize_token_percent` | int | 75 | Percentage of context usage that can trigger summarization. | | `max_media_size` | int | 20971520 | Maximum media file size in bytes (default 20MB) | | `image_model` | string | — | Model name for image generation | | `image_model_fallbacks` | array | [] | Fallback image models | +| `tool_feedback.enabled` | bool | `false` | Show visible tool progress/arguments in chat channels. | +| `tool_feedback.max_args_length` | int | 300 | Maximum visible argument preview length for tool feedback. | +| `tool_feedback.separate_messages` | bool | `false` | Send each tool feedback update as a separate message instead of editing one progress message. | +| `split_on_marker` | bool | `false` | Split outgoing messages on the `<|[SPLIT]|>` marker. | | `routing` | object | — | Intelligent model routing settings (see below) | #### `routing` @@ -299,6 +360,7 @@ When enabled, PicoClaw scores each incoming message against structural features | `model_name` | string | Yes | Alias used in `agents.defaults.model_name` | | `model` | string | Yes | `vendor/model-id` format. The leading `vendor/` is used only for protocol/API base resolution and is not sent upstream as-is. | | `api_keys` | array | Depends | API authentication keys (array; supports multiple keys for load balancing). Required for HTTP-based providers unless `api_base` points to a local server. | +| `api_key` | string | Legacy | Legacy single-key field accepted by migrations and examples; prefer `api_keys` or `.security.yml` for persisted credentials. | | `api_base` | string | No | Override default API base URL | | `enabled` | bool | No | Whether this model entry is active. Defaults to `true` during migration for models with API keys or named `local-model`. Set to `false` to disable a model without removing its configuration. | | `auth_method` | string | No | Authentication method (e.g., `oauth`) | @@ -312,6 +374,7 @@ When enabled, PicoClaw scores each incoming message against structural features | `fallbacks` | array | No | Fallback model names for failover | | `extra_body` | object | No | Additional fields to inject into the API request body | | `custom_headers` | object | No | Additional HTTP headers to inject into every request to this provider (HTTP-based providers only) | +| `user_agent` | string | No | Override the HTTP User-Agent used for provider requests | :::note API Key Behavior in Schema V2 In config schema V2, `model_list[].api_key` in `config.json` is ignored. Use `api_keys` and prefer storing real credentials in `.security.yml`. During V0/V1 migration, legacy `api_key` and `api_keys` are merged into `api_keys` automatically. API keys can use `SecureString` formats: plaintext, `enc://`, or `file://`. See [Credential Encryption](../credential-encryption.md). @@ -365,6 +428,16 @@ Supported by: Feishu, Slack, Matrix. Supported by: Slack, Matrix. +### Pico and IRC Channels + +PicoClaw v0.2.8 adds first-class configuration for the native Pico WebSocket channel and IRC: + +| Channel | Main fields | Notes | +| --- | --- | --- | +| `pico` | `token`, `allow_token_query`, `allow_origins`, `ping_interval`, `read_timeout`, `write_timeout`, `max_connections` | Native WebSocket server for custom clients and the Web UI. | +| `pico_client` | `url`, `token`, `session_id`, `ping_interval`, `read_timeout` | Outbound client mode for connecting to a remote Pico server. | +| `irc` | `server`, `tls`, `nick`, `user`, `real_name`, `password`, `nickserv_password`, `sasl_user`, `sasl_password`, `channels`, `request_caps` | IRC client connection with TLS/SASL and optional typing tags. | + ## Security Configuration ### .security.yml File @@ -381,4 +454,4 @@ When resolving credentials, PicoClaw applies values in this order: For `model_list` in schema V2, `api_key` in `config.json` is ignored; use `.security.yml` + `api_keys`. -For field-by-field `.security.yml` paths, mapping rules, and complete examples, see [`.security.yml Reference`](./security-reference.md). \ No newline at end of file +For field-by-field `.security.yml` paths, mapping rules, and complete examples, see [`.security.yml Reference`](./security-reference.md). diff --git a/docs/configuration/tools.md b/docs/configuration/tools.md index 4793aa8..3e53658 100644 --- a/docs/configuration/tools.md +++ b/docs/configuration/tools.md @@ -60,10 +60,19 @@ Get a free API key at [brave.com/search/api](https://brave.com/search/api) (2000 | Config | Type | Default | Description | |--------|------|---------|-------------| -| `enabled` | bool | true | Enable DuckDuckGo search | +| `enabled` | bool | false | Enable DuckDuckGo search | | `max_results` | int | 5 | Maximum number of results | -DuckDuckGo is enabled by default and requires no API key. +DuckDuckGo requires no API key. + +### Sogou Search + +| Config | Type | Default | Description | +|--------|------|---------|-------------| +| `enabled` | bool | true | Enable Sogou search | +| `max_results` | int | 5 | Maximum number of results | + +Sogou is enabled in the current example config and is useful for Chinese-language search. ### Baidu Search @@ -138,6 +147,7 @@ All web tools (search and fetch) can use a shared proxy: | Config | Type | Default | Description | |--------|------|---------|-------------| +| `provider` | string | `"auto"` | Search provider selection. `auto` lets PicoClaw choose an available provider. | | `prefer_native` | bool | true | Prefer provider's native search over configured search engines | | `private_host_whitelist` | string[] | `[]` | Private/internal hosts allowed for web fetching | @@ -204,6 +214,18 @@ The exec tool executes shell commands on behalf of the agent. | `custom_deny_patterns` | array | [] | Custom deny patterns (regular expressions) | | `custom_allow_patterns` | array | [] | Custom allow patterns -- matching commands bypass deny checks | +## Hardware Tools + +Hardware tools are off by default. Enable only the interfaces that the agent should be allowed to use. + +| Tool | Config | Default | Description | +| --- | --- | --- | --- | +| I2C | `tools.i2c.enabled` | `false` | Enable I2C hardware access on supported Linux systems | +| SPI | `tools.spi.enabled` | `false` | Enable SPI hardware access on supported Linux systems | +| Serial | `tools.serial.enabled` | `false` | Enable cross-platform serial port read/write access | + +The serial tool was added in v0.2.8 and includes platform-specific implementations for Linux, macOS, and Windows. It validates port names and serial settings before opening a device. + ### Disabling the Exec Tool To completely disable the `exec` tool, set `enabled` to `false`: diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/index.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/index.md index 448423f..2479fb5 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/index.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/index.md @@ -30,6 +30,7 @@ picoclaw gateway | **MaixCam** | Fácil | Câmera de IA com integração de hardware. | | **VK** | Fácil | Bot de comunidade do VKontakte via Long Poll API. | | **Pico** | Fácil | Canal WebSocket nativo para clientes personalizados. | +| **IRC** | Médio | Conexão de cliente IRC com TLS, SASL, entrada em canais e typing IRCv3 opcional. | ## Como Funciona @@ -64,6 +65,7 @@ Todos os canais suportam estes campos opcionais: | --- | --- | | `reasoning_channel_id` | Direcionar a saída de raciocínio/pensamento para um canal separado | | `group_trigger` | Controlar o comportamento do bot em chats de grupo (somente menção, prefixos) | +| `typing` | Habilitar indicadores de digitação em canais compatíveis | ## Gateway Compartilhado diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/irc.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/irc.md new file mode 100644 index 0000000..207caf8 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/irc.md @@ -0,0 +1,68 @@ +--- +id: irc +title: IRC +--- + +# IRC + +O canal IRC conecta o PicoClaw a redes IRC usando uma conexão normal de cliente IRC. Ele suporta TLS, autenticação por senha/SASL, entrada em canais, gatilhos de grupo e tags de digitação IRCv3 quando o servidor anuncia `message-tags`. + +## Configuração + +```json +{ + "channels": { + "irc": { + "enabled": true, + "server": "irc.libera.chat:6697", + "tls": true, + "nick": "picoclaw-bot", + "channels": ["#mychannel"], + "allow_from": [], + "group_trigger": { + "mention_only": true + }, + "typing": { + "enabled": false + } + } + } +} +``` + +Depois de salvar a configuração, execute o gateway: + +```bash +picoclaw gateway +``` + +## Referência de Configuração + +| Campo | Tipo | Padrão | Descrição | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | Habilita o canal IRC | +| `server` | string | `irc.libera.chat:6697` | Servidor IRC e porta | +| `tls` | bool | `true` | Conectar usando TLS | +| `nick` | string | `mybot` | Apelido do bot. Obrigatório. | +| `user` | string | `nick` | Nome de usuário IRC. Usa `nick` quando vazio. | +| `real_name` | string | `nick` | Nome real IRC. Usa `nick` quando vazio. | +| `password` | string | `""` | Senha do servidor, se necessária | +| `nickserv_password` | string | `""` | Campo de senha do NickServ mantido na configuração segura | +| `sasl_user` | string | `""` | Usuário SASL. SASL tem prioridade quando configurado. | +| `sasl_password` | string | `""` | Senha SASL, mantida na configuração segura | +| `channels` | string[] | `["#mychannel"]` | Canais para entrar após conectar | +| `request_caps` | string[] | `["server-time", "message-tags"]` | Capabilities IRCv3 solicitadas | +| `allow_from` | array | `[]` | Nicks IRC ou IDs de usuário permitidos. Array vazio permite todos. | +| `group_trigger` | object | `{ "mention_only": true }` | Exigir menção ou prefixos em mensagens de canal | +| `typing.enabled` | bool | `false` | Enviar tags IRCv3 `+typing` quando o servidor suportar | +| `reasoning_channel_id` | string | `""` | Direcionar raciocínio para um destino separado | + +## Autenticação + +Use `sasl_user` e `sasl_password` em redes que suportam SASL. Sem SASL, você pode configurar `password` para autenticação no servidor. `nickserv_password` é armazenado como configuração segura do canal, mas o conector IRC atual não envia comandos NickServ automaticamente. + +Valores sensíveis podem ficar em `.security.yml` em vez de `config.json`. + +## Observações de Comportamento + +IRC é orientado a linhas, então o PicoClaw envia respostas com múltiplas linhas como mensagens IRC separadas. O canal usa um limite conservador de tamanho de mensagem para caber nos limites comuns de servidores IRC. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/pico.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/pico.md new file mode 100644 index 0000000..f535082 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/channels/pico.md @@ -0,0 +1,87 @@ +--- +id: pico +title: Protocolo Pico +--- + +# Protocolo Pico + +O canal Pico é o protocolo WebSocket nativo do PicoClaw para clientes personalizados e para a Web UI. Ele suporta mensagens em tempo real, edição/exclusão de mensagens, indicadores de digitação, placeholders, envio de mídia e atualizações de feedback de ferramentas. + +O PicoClaw pode atuar como servidor WebSocket (`pico`) ou como cliente conectado a um servidor Pico remoto (`pico_client`). + +## Modo Servidor + +Habilite `pico` quando este gateway deve aceitar clientes WebSocket. + +```json +{ + "channels": { + "pico": { + "enabled": true, + "token": "YOUR_PICO_TOKEN", + "allow_token_query": false, + "allow_origins": ["https://docs.picoclaw.io"], + "ping_interval": 30, + "read_timeout": 60, + "max_connections": 100, + "allow_from": [] + } + }, + "gateway": { + "host": "localhost", + "port": 18790 + } +} +``` + +Os clientes se conectam ao gateway compartilhado em `/pico/ws`. A autenticação usa o token configurado. Autenticação por token em query string fica desativada, a menos que `allow_token_query` seja `true`. + +## Modo Cliente + +Habilite `pico_client` quando esta instância do PicoClaw deve se conectar para fora a outro servidor Pico. + +```json +{ + "channels": { + "pico_client": { + "enabled": true, + "url": "wss://remote-pico-server/pico/ws", + "token": "YOUR_PICO_TOKEN", + "session_id": "", + "ping_interval": 30, + "read_timeout": 60, + "allow_from": [] + } + } +} +``` + +## Referência do Servidor + +| Campo | Tipo | Padrão | Descrição | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | Habilita o modo servidor Pico | +| `token` | string | obrigatório | Token compartilhado para autenticação do cliente | +| `allow_token_query` | bool | `false` | Permitir autenticação por token em parâmetro de query | +| `allow_origins` | string[] | `[]` | Origins de navegador permitidas. Array vazio permite todas. | +| `ping_interval` | int | `30` | Intervalo de ping WebSocket em segundos | +| `read_timeout` | int | `60` | Timeout de leitura WebSocket em segundos | +| `write_timeout` | int | `0` | Timeout opcional de escrita WebSocket em segundos | +| `max_connections` | int | `100` | Máximo de conexões WebSocket ativas | +| `allow_from` | array | `[]` | Remetentes de sessão Pico permitidos. Array vazio permite todos. | + +## Referência do Cliente + +| Campo | Tipo | Padrão | Descrição | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | Habilita o modo cliente Pico | +| `url` | string | obrigatório | URL WebSocket Pico remota | +| `token` | string | obrigatório | Token compartilhado para autenticação no servidor remoto | +| `session_id` | string | `""` | ID de sessão fixo opcional | +| `ping_interval` | int | `30` | Intervalo de ping WebSocket em segundos | +| `read_timeout` | int | `60` | Timeout de leitura WebSocket em segundos | +| `allow_from` | array | `[]` | Remetentes de sessão de entrada permitidos | + +## Segurança + +Em produção, mantenha `token` em `.security.yml`. Se usar clientes de navegador, configure `allow_origins` com as origins confiáveis exatas em vez de deixar aberto. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/config-reference.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/config-reference.md index 7809ec8..7905bcb 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/config-reference.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/config-reference.md @@ -22,28 +22,39 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man "workspace": "~/.picoclaw/workspace", "restrict_to_workspace": true, "model_name": "gpt-5.4", - "max_tokens": 32768, - "max_tool_iterations": 50 + "max_tokens": 8192, + "context_window": 131072, + "max_tool_iterations": 20, + "summarize_message_threshold": 20, + "summarize_token_percent": 75, + "split_on_marker": false, + "tool_feedback": { + "enabled": false, + "max_args_length": 300, + "separate_messages": false + } } }, "model_list": [ - { - "model_name": "ark-code-latest", - "model": "volcengine/ark-code-latest", - "api_keys": ["sk-your-volcengine-key"] - }, { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-your-openai-key"], + "api_key": "sk-your-openai-key", "api_base": "https://api.openai.com/v1" }, { "model_name": "claude-sonnet-4.6", "model": "anthropic/claude-sonnet-4.6", - "api_keys": ["sk-ant-your-key"], - "api_base": "https://api.anthropic.com/v1" + "api_key": "sk-ant-your-key", + "api_base": "https://api.anthropic.com/v1", + "thinking_level": "high" + }, + { + "model_name": "azure-gpt5", + "model": "azure/my-gpt5-deployment", + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com" }, { "model_name": "gemini", @@ -53,18 +64,18 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man { "model_name": "deepseek", "model": "deepseek/deepseek-chat", - "api_keys": ["sk-your-deepseek-key"] + "api_key": "sk-your-deepseek-key" }, { "model_name": "loadbalanced-gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-key1"], + "api_key": "sk-key1", "api_base": "https://api1.example.com/v1" }, { "model_name": "loadbalanced-gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-key2"], + "api_key": "sk-key2", "api_base": "https://api2.example.com/v1" } ], @@ -76,6 +87,7 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man "base_url": "", "proxy": "", "allow_from": ["YOUR_USER_ID"], + "use_markdown_v2": false, "reasoning_channel_id": "" }, "discord": { @@ -93,6 +105,10 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man "app_id": "YOUR_QQ_APP_ID", "app_secret": "YOUR_QQ_APP_SECRET", "allow_from": [], + "placeholder": { + "enabled": true, + "text": ["Thinking...", "Processing...", "Typing..."] + }, "reasoning_channel_id": "" }, "maixcam": { @@ -108,10 +124,6 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man "use_native": false, "session_store_path": "", "allow_from": [], - "group_trigger": { - "mention_only": false, - "prefixes": [] - }, "reasoning_channel_id": "" }, "feishu": { @@ -176,29 +188,63 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man }, "placeholder": { "enabled": true, - "text": "Thinking..." + "text": ["Thinking...", "Processing...", "Typing..."] }, "reasoning_channel_id": "" + }, + "pico": { + "enabled": false, + "token": "YOUR_PICO_TOKEN", + "allow_token_query": false, + "allow_origins": [], + "ping_interval": 30, + "read_timeout": 60, + "max_connections": 100, + "allow_from": [] + }, + "irc": { + "enabled": false, + "server": "irc.libera.chat:6697", + "tls": true, + "nick": "mybot", + "channels": ["#mychannel"], + "request_caps": ["server-time", "message-tags"], + "allow_from": [], + "group_trigger": { + "mention_only": true + } } }, "tools": { + "allow_read_paths": null, + "allow_write_paths": null, "web": { + "enabled": true, + "prefer_native": true, + "fetch_limit_bytes": 10485760, + "format": "plaintext", "brave": { "enabled": false, + "api_key": "YOUR_BRAVE_API_KEY", "api_keys": ["YOUR_BRAVE_API_KEY"], "max_results": 5 }, - "duckduckgo": { + "provider": "auto", + "sogou": { "enabled": true, "max_results": 5 }, + "duckduckgo": { + "enabled": false, + "max_results": 5 + }, "perplexity": { "enabled": false, "api_keys": ["pplx-xxx"], "max_results": 5 }, - "proxy": "" + "private_host_whitelist": [] }, "mcp": { "enabled": false, @@ -225,9 +271,10 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man "exec_timeout_minutes": 5 }, "exec": { + "enabled": true, "enable_deny_patterns": true, - "custom_deny_patterns": [], - "custom_allow_patterns": [] + "custom_deny_patterns": null, + "custom_allow_patterns": null }, "skills": { "registries": { @@ -239,6 +286,9 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man "download_path": "/api/v1/download" } } + }, + "serial": { + "enabled": false } }, @@ -279,11 +329,18 @@ Para o gerenciamento diário de modelos, recomenda-se a Web UI. Use edição man | `model` | string | — | **Descontinuado**: use `model_name` no lugar | | `model_fallbacks` | array | [] | Nomes de modelos de fallback testados em ordem se o primário falhar | | `max_tokens` | int | 32768 | Máximo de tokens por resposta | +| `context_window` | int | 0 | Sobrescrita opcional da janela de contexto. `0` usa o padrão do provider/modelo. | | `temperature` | float | — | Temperatura do LLM (omita para usar o padrão do provedor) | | `max_tool_iterations` | int | 50 | Máximo de iterações de chamadas de ferramentas por requisição | +| `summarize_message_threshold` | int | 20 | Limite de quantidade de mensagens que pode acionar resumo | +| `summarize_token_percent` | int | 75 | Percentual de uso de contexto que pode acionar resumo | | `max_media_size` | int | 20971520 | Tamanho máximo de arquivo de mídia em bytes (padrão 20MB) | | `image_model` | string | — | Nome do modelo para geração de imagens | | `image_model_fallbacks` | array | [] | Modelos de fallback para imagens | +| `tool_feedback.enabled` | bool | `false` | Mostra progresso/argumentos de ferramentas nos canais de chat | +| `tool_feedback.max_args_length` | int | 300 | Tamanho máximo da prévia de argumentos no feedback de ferramentas | +| `tool_feedback.separate_messages` | bool | `false` | Envia cada atualização como mensagem separada em vez de editar uma mensagem de progresso | +| `split_on_marker` | bool | `false` | Divide mensagens de saída no marcador `<|[SPLIT]|>` | | `routing` | object | — | Configurações de roteamento inteligente de modelos (veja abaixo) | #### `routing` @@ -303,6 +360,7 @@ Quando habilitado, o PicoClaw pontua cada mensagem recebida com base em caracter | `model_name` | string | Sim | Alias usado em `agents.defaults.model_name` | | `model` | string | Sim | Formato `vendor/model-id`. O prefixo `vendor/` é usado apenas para resolução de protocolo/API base e não é enviado ao upstream como está. | | `api_keys` | array | Depende | Chaves de autenticação da API (array; suporta múltiplas chaves para load balancing). Obrigatório para provedores baseados em HTTP, a menos que `api_base` aponte para um servidor local. | +| `api_key` | string | Legado | Campo de chave única ainda aceito por migrações e exemplos; prefira `api_keys` ou `.security.yml` para credenciais persistidas. | | `api_base` | string | Não | Sobrescreve a URL base da API padrão | | `enabled` | bool | Não | Indica se esta entrada de modelo está ativa. Durante a migração, o padrão é `true` para modelos com chaves de API ou nomeados `local-model`. Defina como `false` para desabilitar um modelo sem remover sua configuração. | | `auth_method` | string | Não | Método de autenticação (ex.: `oauth`) | @@ -316,6 +374,7 @@ Quando habilitado, o PicoClaw pontua cada mensagem recebida com base em caracter | `fallbacks` | array | Não | Nomes de modelos de fallback para failover | | `extra_body` | object | Não | Campos adicionais a injetar no corpo da requisição da API | | `custom_headers` | object | Não | Cabeçalhos HTTP adicionais a injetar em toda requisição a este provider (apenas providers baseados em HTTP) | +| `user_agent` | string | Não | Sobrescrever o HTTP User-Agent usado nas requisições ao provider | :::note Comportamento de API Key no Schema V2 Na versão V2 do schema de configuração, `model_list[].api_key` em `config.json` é ignorado. Use `api_keys` e prefira armazenar credenciais reais em `.security.yml`. Durante a migração de V0/V1, os campos legados `api_key` e `api_keys` são mesclados automaticamente em `api_keys`. As chaves de API podem usar formatos `SecureString`: texto puro, `enc://`, ou `file://`. Consulte [Credential Encryption](../credential-encryption.md). @@ -345,6 +404,16 @@ Todos os canais suportam estes campos: | `placeholder` | object | Configurações de mensagem de placeholder (veja abaixo) | | `typing` | object | Configurações do indicador de digitação (veja abaixo) | +### Canais Pico e IRC + +O PicoClaw v0.2.8 adiciona configuração de primeira classe para o canal WebSocket Pico nativo e para IRC: + +| Canal | Campos principais | Observações | +| --- | --- | --- | +| `pico` | `token`, `allow_token_query`, `allow_origins`, `ping_interval`, `read_timeout`, `write_timeout`, `max_connections` | Servidor WebSocket nativo para clientes personalizados e Web UI. | +| `pico_client` | `url`, `token`, `session_id`, `ping_interval`, `read_timeout` | Modo cliente outbound para conectar a um servidor Pico remoto. | +| `irc` | `server`, `tls`, `nick`, `user`, `real_name`, `password`, `nickserv_password`, `sasl_user`, `sasl_password`, `channels`, `request_caps` | Conexão de cliente IRC com TLS/SASL e tags de digitação opcionais. | + #### `group_trigger` | Campo | Tipo | Descrição | diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/tools.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/tools.md index 5c5f1cc..32aba04 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/tools.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/configuration/tools.md @@ -60,10 +60,19 @@ Obtenha uma chave de API gratuita em [brave.com/search/api](https://brave.com/se | Config | Tipo | Padrão | Descrição | |--------|------|---------|-------------| -| `enabled` | bool | true | Habilitar busca DuckDuckGo | +| `enabled` | bool | false | Habilitar busca DuckDuckGo | | `max_results` | int | 5 | Número máximo de resultados | -O DuckDuckGo é habilitado por padrão e não requer chave de API. +O DuckDuckGo não requer chave de API. + +### Sogou Search + +| Config | Tipo | Padrão | Descrição | +|--------|------|---------|-------------| +| `enabled` | bool | true | Habilitar busca Sogou | +| `max_results` | int | 5 | Número máximo de resultados | + +Sogou vem habilitado no exemplo de configuração atual e é útil para buscas em chinês. ### Baidu Search @@ -138,6 +147,7 @@ Todas as ferramentas web (busca e fetch) podem usar um proxy compartilhado: | Config | Tipo | Padrão | Descrição | |--------|------|---------|-------------| +| `provider` | string | `"auto"` | Seleção do provedor de busca. `auto` deixa o PicoClaw escolher um provedor disponível. | | `prefer_native` | bool | true | Preferir a busca nativa do provedor sobre os search engines configurados | | `private_host_whitelist` | string[] | `[]` | Hosts privados/internos autorizados para web fetching | @@ -204,6 +214,18 @@ A ferramenta exec executa comandos shell em nome do agente. | `custom_deny_patterns` | array | [] | Padrões de negação customizados (expressões regulares) | | `custom_allow_patterns` | array | [] | Padrões de permissão customizados — comandos correspondentes ignoram as verificações de negação | +## Ferramentas de Hardware + +Ferramentas de hardware ficam desabilitadas por padrão. Habilite apenas as interfaces que o agente deve poder usar. + +| Ferramenta | Config | Padrão | Descrição | +| --- | --- | --- | --- | +| I2C | `tools.i2c.enabled` | `false` | Habilita acesso a hardware I2C em sistemas Linux compatíveis | +| SPI | `tools.spi.enabled` | `false` | Habilita acesso a hardware SPI em sistemas Linux compatíveis | +| Serial | `tools.serial.enabled` | `false` | Habilita leitura/escrita serial multiplataforma | + +A ferramenta serial foi adicionada no v0.2.8 e inclui implementações para Linux, macOS e Windows. Ela valida nomes de porta e parâmetros seriais antes de abrir o dispositivo. + ### Desabilitando a Ferramenta Exec Para desabilitar completamente a ferramenta `exec`, defina `enabled` como `false`: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/index.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/index.md index 71cc069..597c696 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/index.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/index.md @@ -30,6 +30,7 @@ picoclaw gateway | **MaixCam** | 简单 | 硬件集成 AI 摄像头。 | | **VK** | 简单 | 通过 Long Poll API 连接 VKontakte 社区机器人。 | | **Pico** | 简单 | 原生 WebSocket 通道，适用于自定义客户端。 | +| **IRC** | 中等 | IRC 客户端连接，支持 TLS、SASL、加入频道和可选 IRCv3 输入状态标签。 | ## 工作原理 @@ -64,6 +65,7 @@ picoclaw gateway | --- | --- | | `reasoning_channel_id` | 将推理/思考过程输出到单独的频道 | | `group_trigger` | 控制机器人在群聊中的触发行为（仅@、关键词前缀） | +| `typing` | 在支持的通道上启用输入状态提示 | ## 共享网关 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/irc.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/irc.md new file mode 100644 index 0000000..60afa11 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/irc.md @@ -0,0 +1,68 @@ +--- +id: irc +title: IRC +--- + +# IRC + +IRC 通道通过普通 IRC 客户端连接把 PicoClaw 接入 IRC 网络。它支持 TLS、密码/SASL 认证、加入频道、群聊触发规则，以及服务器支持 `message-tags` 时的 IRCv3 输入状态标签。 + +## 配置 + +```json +{ + "channels": { + "irc": { + "enabled": true, + "server": "irc.libera.chat:6697", + "tls": true, + "nick": "picoclaw-bot", + "channels": ["#mychannel"], + "allow_from": [], + "group_trigger": { + "mention_only": true + }, + "typing": { + "enabled": false + } + } + } +} +``` + +保存配置后启动网关： + +```bash +picoclaw gateway +``` + +## 配置参考 + +| 字段 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | 启用 IRC 通道 | +| `server` | string | `irc.libera.chat:6697` | IRC 服务器和端口 | +| `tls` | bool | `true` | 使用 TLS 连接 | +| `nick` | string | `mybot` | 机器人昵称，必填 | +| `user` | string | `nick` | IRC 用户名，留空时使用 `nick` | +| `real_name` | string | `nick` | IRC real name，留空时使用 `nick` | +| `password` | string | `""` | 服务器密码 | +| `nickserv_password` | string | `""` | 存入安全配置的 NickServ 密码字段 | +| `sasl_user` | string | `""` | SASL 用户名。配置后优先使用 SASL。 | +| `sasl_password` | string | `""` | SASL 密码，建议放入安全配置 | +| `channels` | string[] | `["#mychannel"]` | 连接后加入的频道 | +| `request_caps` | string[] | `["server-time", "message-tags"]` | 请求的 IRCv3 capability | +| `allow_from` | array | `[]` | 允许访问的 IRC 昵称或用户 ID。空数组表示允许所有用户。 | +| `group_trigger` | object | `{ "mention_only": true }` | 频道消息中是否要求 @ 或前缀触发 | +| `typing.enabled` | bool | `false` | 服务器支持时发送 IRCv3 `+typing` 标签 | +| `reasoning_channel_id` | string | `""` | 将推理输出路由到单独目标 | + +## 认证 + +支持 SASL 的网络推荐使用 `sasl_user` 和 `sasl_password`。未配置 SASL 时，可以使用 `password` 进行服务器认证。`nickserv_password` 会作为安全通道配置保存，但当前 IRC 连接器不会自动发送 NickServ 命令。 + +敏感值可以放在 `.security.yml`，避免写入 `config.json`。 + +## 行为说明 + +IRC 是按行发送的协议，因此 PicoClaw 会把多行回复拆成多条 IRC 消息发送。通道使用较保守的消息长度限制，以适配常见 IRC 服务器限制。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/pico.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/pico.md new file mode 100644 index 0000000..2a99779 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/channels/pico.md @@ -0,0 +1,87 @@ +--- +id: pico +title: Pico 协议 +--- + +# Pico 协议 + +Pico 通道是 PicoClaw 为自定义客户端和 Web UI 提供的原生 WebSocket 协议。它支持实时消息、消息编辑/删除、输入状态、占位消息、媒体传输和工具反馈更新。 + +PicoClaw 既可以作为 WebSocket 服务端（`pico`），也可以作为客户端连接到远程 Pico 服务端（`pico_client`）。 + +## 服务端模式 + +当当前网关需要接收 WebSocket 客户端连接时，启用 `pico`。 + +```json +{ + "channels": { + "pico": { + "enabled": true, + "token": "YOUR_PICO_TOKEN", + "allow_token_query": false, + "allow_origins": ["https://docs.picoclaw.io"], + "ping_interval": 30, + "read_timeout": 60, + "max_connections": 100, + "allow_from": [] + } + }, + "gateway": { + "host": "localhost", + "port": 18790 + } +} +``` + +客户端通过共享网关的 `/pico/ws` 路径连接。认证使用配置中的 token。除非设置 `allow_token_query: true`，否则不会允许通过查询参数传递 token。 + +## 客户端模式 + +当这个 PicoClaw 实例需要主动连接到另一个 Pico 服务端时，启用 `pico_client`。 + +```json +{ + "channels": { + "pico_client": { + "enabled": true, + "url": "wss://remote-pico-server/pico/ws", + "token": "YOUR_PICO_TOKEN", + "session_id": "", + "ping_interval": 30, + "read_timeout": 60, + "allow_from": [] + } + } +} +``` + +## 服务端配置参考 + +| 字段 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | 启用 Pico 服务端模式 | +| `token` | string | 必填 | 客户端认证共享 token | +| `allow_token_query` | bool | `false` | 允许通过查询参数进行 token 认证 | +| `allow_origins` | string[] | `[]` | 允许的浏览器 Origin。空数组表示允许所有 Origin。 | +| `ping_interval` | int | `30` | WebSocket ping 间隔，单位秒 | +| `read_timeout` | int | `60` | WebSocket 读取超时，单位秒 | +| `write_timeout` | int | `0` | 可选的 WebSocket 写入超时，单位秒 | +| `max_connections` | int | `100` | 最大活跃 WebSocket 连接数 | +| `allow_from` | array | `[]` | 允许的 Pico 会话发送方。空数组表示允许所有用户。 | + +## 客户端配置参考 + +| 字段 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| `enabled` | bool | `false` | 启用 Pico 客户端模式 | +| `url` | string | 必填 | 远程 Pico WebSocket URL | +| `token` | string | 必填 | 远程服务端认证共享 token | +| `session_id` | string | `""` | 可选的固定会话 ID | +| `ping_interval` | int | `30` | WebSocket ping 间隔，单位秒 | +| `read_timeout` | int | `60` | WebSocket 读取超时，单位秒 | +| `allow_from` | array | `[]` | 允许的入站会话发送方 | + +## 安全说明 + +生产部署中建议把 `token` 放入 `.security.yml`。如果使用浏览器客户端，请把 `allow_origins` 配置为可信 Origin，不要保持开放。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/config-reference.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/config-reference.md index 04e4379..9a4520f 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/config-reference.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/config-reference.md @@ -22,28 +22,39 @@ title: 完整配置参考 "workspace": "~/.picoclaw/workspace", "restrict_to_workspace": true, "model_name": "gpt-5.4", - "max_tokens": 32768, - "max_tool_iterations": 50 + "max_tokens": 8192, + "context_window": 131072, + "max_tool_iterations": 20, + "summarize_message_threshold": 20, + "summarize_token_percent": 75, + "split_on_marker": false, + "tool_feedback": { + "enabled": false, + "max_args_length": 300, + "separate_messages": false + } } }, "model_list": [ - { - "model_name": "ark-code-latest", - "model": "volcengine/ark-code-latest", - "api_keys": ["sk-your-volcengine-key"] - }, { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-your-openai-key"], + "api_key": "sk-your-openai-key", "api_base": "https://api.openai.com/v1" }, { "model_name": "claude-sonnet-4.6", "model": "anthropic/claude-sonnet-4.6", - "api_keys": ["sk-ant-your-key"], - "api_base": "https://api.anthropic.com/v1" + "api_key": "sk-ant-your-key", + "api_base": "https://api.anthropic.com/v1", + "thinking_level": "high" + }, + { + "model_name": "azure-gpt5", + "model": "azure/my-gpt5-deployment", + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com" }, { "model_name": "gemini", @@ -53,18 +64,18 @@ title: 完整配置参考 { "model_name": "deepseek", "model": "deepseek/deepseek-chat", - "api_keys": ["sk-your-deepseek-key"] + "api_key": "sk-your-deepseek-key" }, { "model_name": "loadbalanced-gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-key1"], + "api_key": "sk-key1", "api_base": "https://api1.example.com/v1" }, { "model_name": "loadbalanced-gpt-5.4", "model": "openai/gpt-5.4", - "api_keys": ["sk-key2"], + "api_key": "sk-key2", "api_base": "https://api2.example.com/v1" } ], @@ -76,6 +87,7 @@ title: 完整配置参考 "base_url": "", "proxy": "", "allow_from": ["YOUR_USER_ID"], + "use_markdown_v2": false, "reasoning_channel_id": "" }, "discord": { @@ -93,6 +105,10 @@ title: 完整配置参考 "app_id": "YOUR_QQ_APP_ID", "app_secret": "YOUR_QQ_APP_SECRET", "allow_from": [], + "placeholder": { + "enabled": true, + "text": ["Thinking...", "Processing...", "Typing..."] + }, "reasoning_channel_id": "" }, "maixcam": { @@ -172,29 +188,63 @@ title: 完整配置参考 }, "placeholder": { "enabled": true, - "text": "正在思考..." + "text": ["Thinking...", "Processing...", "Typing..."] }, "reasoning_channel_id": "" + }, + "pico": { + "enabled": false, + "token": "YOUR_PICO_TOKEN", + "allow_token_query": false, + "allow_origins": [], + "ping_interval": 30, + "read_timeout": 60, + "max_connections": 100, + "allow_from": [] + }, + "irc": { + "enabled": false, + "server": "irc.libera.chat:6697", + "tls": true, + "nick": "mybot", + "channels": ["#mychannel"], + "request_caps": ["server-time", "message-tags"], + "allow_from": [], + "group_trigger": { + "mention_only": true + } } }, "tools": { + "allow_read_paths": null, + "allow_write_paths": null, "web": { + "enabled": true, + "prefer_native": true, + "fetch_limit_bytes": 10485760, + "format": "plaintext", "brave": { "enabled": false, + "api_key": "YOUR_BRAVE_API_KEY", "api_keys": ["YOUR_BRAVE_API_KEY"], "max_results": 5 }, - "duckduckgo": { + "provider": "auto", + "sogou": { "enabled": true, "max_results": 5 }, + "duckduckgo": { + "enabled": false, + "max_results": 5 + }, "perplexity": { "enabled": false, "api_keys": ["pplx-xxx"], "max_results": 5 }, - "proxy": "" + "private_host_whitelist": [] }, "mcp": { "enabled": false, @@ -221,9 +271,10 @@ title: 完整配置参考 "exec_timeout_minutes": 5 }, "exec": { + "enabled": true, "enable_deny_patterns": true, - "custom_deny_patterns": [], - "custom_allow_patterns": [] + "custom_deny_patterns": null, + "custom_allow_patterns": null }, "skills": { "registries": { @@ -235,6 +286,9 @@ title: 完整配置参考 "download_path": "/api/v1/download" } } + }, + "serial": { + "enabled": false } }, @@ -275,11 +329,18 @@ title: 完整配置参考 | `model` | string | — | **已废弃**：请使用 `model_name` | | `model_fallbacks` | array | [] | 备用模型名列表，主模型失败时按顺序尝试 | | `max_tokens` | int | 32768 | 每次响应最大 token 数 | +| `context_window` | int | 0 | 可选上下文窗口覆盖值。`0` 表示使用 provider/模型默认值。 | | `temperature` | float | — | LLM 温度（省略则使用提供商默认值） | | `max_tool_iterations` | int | 50 | 每次请求最多工具调用次数 | +| `summarize_message_threshold` | int | 20 | 触发摘要的会话消息数量阈值 | +| `summarize_token_percent` | int | 75 | 可触发摘要的上下文使用百分比 | | `max_media_size` | int | 20971520 | 最大媒体文件大小（字节），默认 20MB | | `image_model` | string | — | 图片生成使用的模型名 | | `image_model_fallbacks` | array | [] | 图片生成备用模型 | +| `tool_feedback.enabled` | bool | `false` | 在聊天通道中显示工具进度/参数预览 | +| `tool_feedback.max_args_length` | int | 300 | 工具反馈中参数预览的最大长度 | +| `tool_feedback.separate_messages` | bool | `false` | 每次工具反馈更新发送为独立消息，而不是编辑同一条进度消息 | +| `split_on_marker` | bool | `false` | 按 `<|[SPLIT]|>` 标记拆分外发消息 | | `routing` | object | — | 智能模型路由设置（见下方） | #### `routing` @@ -299,6 +360,7 @@ title: 完整配置参考 | `model_name` | string | 是 | 别名（在 `agents.defaults.model_name` 中引用） | | `model` | string | 是 | `vendor/model-id` 格式。前导 `vendor/` 仅用于协议与默认 `api_base` 识别，不会原样发送给上游。 | | `api_keys` | array | 视情况 | API 认证密钥（数组；支持多个密钥用于负载均衡）。基于 HTTP 的提供商必填，除非 `api_base` 指向本地服务。 | +| `api_key` | string | 旧字段 | 迁移和示例仍可接受的单 key 字段；持久化配置优先使用 `api_keys` 或 `.security.yml`。 | | `api_base` | string | 否 | 覆盖默认 API 地址 | | `enabled` | bool | 否 | 该模型条目是否启用。迁移期间默认为 `true`（有 API 密钥或名为 `local-model` 的模型自动启用）。设为 `false` 可禁用模型但不删除配置。 | | `auth_method` | string | 否 | 认证方式（如 `oauth`） | @@ -312,6 +374,7 @@ title: 完整配置参考 | `fallbacks` | array | 否 | 故障转移备用模型名 | | `extra_body` | object | 否 | 注入 API 请求体的额外字段 | | `custom_headers` | object | 否 | 注入到该 provider 每次请求的额外 HTTP 头（仅 HTTP 类 provider 有效） | +| `user_agent` | string | 否 | 覆盖 provider 请求使用的 HTTP User-Agent | :::note Schema V2 中 API Key 行为 在配置 schema V2 中，`config.json` 的 `model_list[].api_key` 会被忽略。请使用 `api_keys`，并优先将真实密钥写入 `.security.yml`。从 V0/V1 迁移时，旧的 `api_key` 与 `api_keys` 会自动合并为 `api_keys`。API 密钥支持 `SecureString` 格式：明文、`enc://`、`file://`。详见[凭证加密](../credential-encryption.md)。 @@ -341,6 +404,16 @@ title: 完整配置参考 | `placeholder` | object | 占位消息设置（见下方） | | `typing` | object | 输入状态指示器设置（见下方） | +### Pico 与 IRC 通道 + +PicoClaw v0.2.8 新增了原生 Pico WebSocket 通道和 IRC 的一等配置： + +| 通道 | 主要字段 | 说明 | +| --- | --- | --- | +| `pico` | `token`, `allow_token_query`, `allow_origins`, `ping_interval`, `read_timeout`, `write_timeout`, `max_connections` | 面向自定义客户端和 Web UI 的原生 WebSocket 服务端。 | +| `pico_client` | `url`, `token`, `session_id`, `ping_interval`, `read_timeout` | 连接到远程 Pico 服务端的出站客户端模式。 | +| `irc` | `server`, `tls`, `nick`, `user`, `real_name`, `password`, `nickserv_password`, `sasl_user`, `sasl_password`, `channels`, `request_caps` | 支持 TLS/SASL 和可选输入状态标签的 IRC 客户端连接。 | + #### `group_trigger` | 字段 | 类型 | 说明 | @@ -382,4 +455,3 @@ PicoClaw 支持专用的 `.security.yml` 文件来存储敏感凭证（API 密 对于 schema V2 的 `model_list`，`config.json` 中的 `api_key` 会被忽略，请使用 `.security.yml` + `api_keys`。 关于 `.security.yml` 的字段路径、映射规则和完整示例，请参考[`.security.yml 配置参考`](./security-reference.md)。 - diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/tools.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/tools.md index 0aa7fab..d1347ca 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/tools.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/configuration/tools.md @@ -60,10 +60,19 @@ title: 工具配置 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| -| `enabled` | bool | true | 启用 DuckDuckGo 搜索 | +| `enabled` | bool | false | 启用 DuckDuckGo 搜索 | | `max_results` | int | 5 | 最大返回结果数 | -DuckDuckGo 默认启用，无需 API Key。 +DuckDuckGo 无需 API Key。 + +### 搜狗搜索 + +| 配置项 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| `enabled` | bool | true | 启用搜狗搜索 | +| `max_results` | int | 5 | 最大返回结果数 | + +当前示例配置默认启用搜狗搜索，适合中文搜索场景。 ### 百度搜索 @@ -138,6 +147,7 @@ DuckDuckGo 默认启用，无需 API Key。 | 配置项 | 类型 | 默认值 | 说明 | |--------|------|--------|------| +| `provider` | string | `"auto"` | 搜索提供方选择。`auto` 表示由 PicoClaw 选择可用 provider。 | | `prefer_native` | bool | true | 优先使用提供商的原生搜索而非配置的搜索引擎 | | `private_host_whitelist` | string[] | `[]` | 允许网页抓取的私有/内部主机列表 | @@ -204,6 +214,18 @@ Exec 工具代替 Agent 在系统上执行 Shell 命令。 | `custom_deny_patterns` | array | [] | 自定义拦截正则表达式 | | `custom_allow_patterns` | array | [] | 自定义允许规则 -- 匹配的命令可绕过拦截检查 | +## 硬件工具 + +硬件工具默认关闭。只启用确实希望 Agent 使用的接口。 + +| 工具 | 配置项 | 默认值 | 说明 | +| --- | --- | --- | --- | +| I2C | `tools.i2c.enabled` | `false` | 在支持的 Linux 系统上启用 I2C 硬件访问 | +| SPI | `tools.spi.enabled` | `false` | 在支持的 Linux 系统上启用 SPI 硬件访问 | +| Serial | `tools.serial.enabled` | `false` | 启用跨平台串口读写访问 | + +Serial 工具在 v0.2.8 中加入，包含 Linux、macOS 和 Windows 的平台实现。打开设备前会校验端口名称和串口参数。 + ### 禁用 Exec 工具 要完全禁用 `exec` 工具，将 `enabled` 设为 `false`： diff --git a/sidebars.js b/sidebars.js index c0dcc26..7750aec 100644 --- a/sidebars.js +++ b/sidebars.js @@ -74,6 +74,8 @@ const sidebars = { 'channels/vk', 'channels/weixin', 'channels/teams-webhook', + 'channels/pico', + 'channels/irc', ], }, {