From d9c0e4c4529923bcdd2f1bb7a2ea7ddba6a9f920 Mon Sep 17 00:00:00 2001 From: Jason Date: Sat, 4 Apr 2026 12:20:13 +0800 Subject: [PATCH] docs: update user manual to v3.12.3 with new features coverage (en/zh/ja) Add documentation for features introduced since v3.12.0: New docs: - 3.4 Session Manager: browse, search, resume, delete sessions - 3.5 Workspace & Daily Memory: OpenClaw workspace file editing Updated docs: - Add Lightweight Mode to interface overview and FAQ - Add tray submenu structure (providers grouped by app) - Add API Format selection (Anthropic/OpenAI Chat/OpenAI Responses) - Add Auto-Fetch Models button documentation - Add Claude Common Config quick toggles - Add Codex 1M Context Window toggle - Add Skill backup/restore lifecycle - Expand Backup Management panel documentation - Update WebDAV sync to v2 protocol with dual-layer versioning - Add OpenCode/OpenClaw to quickstart activation table - Update README version to v3.12.3 All changes synced across en, zh, and ja locales. --- .../en/1-getting-started/1.3-interface.md | 19 ++- .../en/1-getting-started/1.4-quickstart.md | 10 ++ .../en/1-getting-started/1.5-settings.md | 67 +++++++-- docs/user-manual/en/2-providers/2.1-add.md | 55 ++++++++ docs/user-manual/en/2-providers/2.2-switch.md | 4 +- docs/user-manual/en/2-providers/2.3-edit.md | 14 ++ .../user-manual/en/3-extensions/3.3-skills.md | 23 ++- .../en/3-extensions/3.4-sessions.md | 131 ++++++++++++++++++ .../en/3-extensions/3.5-workspace.md | 85 ++++++++++++ docs/user-manual/en/4-proxy/4.1-service.md | 14 ++ docs/user-manual/en/5-faq/5.1-config-files.md | 9 +- docs/user-manual/en/5-faq/5.2-questions.md | 10 ++ docs/user-manual/en/README.md | 12 +- .../ja/1-getting-started/1.3-interface.md | 19 ++- .../ja/1-getting-started/1.4-quickstart.md | 12 +- .../ja/1-getting-started/1.5-settings.md | 67 +++++++-- docs/user-manual/ja/2-providers/2.1-add.md | 55 ++++++++ docs/user-manual/ja/2-providers/2.2-switch.md | 4 +- docs/user-manual/ja/2-providers/2.3-edit.md | 14 ++ .../user-manual/ja/3-extensions/3.3-skills.md | 23 ++- .../ja/3-extensions/3.4-sessions.md | 131 ++++++++++++++++++ .../ja/3-extensions/3.5-workspace.md | 85 ++++++++++++ docs/user-manual/ja/4-proxy/4.1-service.md | 14 ++ docs/user-manual/ja/5-faq/5.1-config-files.md | 9 +- docs/user-manual/ja/5-faq/5.2-questions.md | 10 ++ docs/user-manual/ja/README.md | 12 +- .../zh/1-getting-started/1.3-interface.md | 19 ++- .../zh/1-getting-started/1.4-quickstart.md | 12 +- .../zh/1-getting-started/1.5-settings.md | 81 ++++++++--- docs/user-manual/zh/2-providers/2.1-add.md | 55 ++++++++ docs/user-manual/zh/2-providers/2.2-switch.md | 6 +- docs/user-manual/zh/2-providers/2.3-edit.md | 14 ++ .../user-manual/zh/3-extensions/3.3-skills.md | 23 ++- .../zh/3-extensions/3.4-sessions.md | 131 ++++++++++++++++++ .../zh/3-extensions/3.5-workspace.md | 85 ++++++++++++ docs/user-manual/zh/4-proxy/4.1-service.md | 14 ++ docs/user-manual/zh/5-faq/5.1-config-files.md | 9 +- docs/user-manual/zh/5-faq/5.2-questions.md | 10 ++ docs/user-manual/zh/README.md | 12 +- 39 files changed, 1282 insertions(+), 97 deletions(-) create mode 100644 docs/user-manual/en/3-extensions/3.4-sessions.md create mode 100644 docs/user-manual/en/3-extensions/3.5-workspace.md create mode 100644 docs/user-manual/ja/3-extensions/3.4-sessions.md create mode 100644 docs/user-manual/ja/3-extensions/3.5-workspace.md create mode 100644 docs/user-manual/zh/3-extensions/3.4-sessions.md create mode 100644 docs/user-manual/zh/3-extensions/3.5-workspace.md diff --git a/docs/user-manual/en/1-getting-started/1.3-interface.md b/docs/user-manual/en/1-getting-started/1.3-interface.md index df78b84b..70a26a13 100644 --- a/docs/user-manual/en/1-getting-started/1.3-interface.md +++ b/docs/user-manual/en/1-getting-started/1.3-interface.md @@ -100,10 +100,13 @@ CC Switch displays an icon in the system tray, providing quick access to operati | Menu Item | Function | |-----------|----------| | Open Main Window | Show and focus the main window | -| App Groups | Providers grouped by Claude/Codex/Gemini/OpenCode/OpenClaw | -| Provider List | Click to switch; currently active one shows a checkmark | +| App Submenus | Collapsible submenus grouped by Claude/Codex/Gemini (e.g., "Claude · PackyCode") | +| Provider List | Inside each submenu, click to switch; currently active shows a checkmark | +| Lightweight Mode | Toggle checkbox to enter/exit tray-only mode | | Quit | Fully exit the application | +> **Note**: Each app submenu title shows the current provider name (e.g., "Claude · PackyCode"). Apps with no configured providers show a disabled "(no providers)" entry. App visibility is controlled by the App Visibility setting. + ### Multi-language Support The tray menu supports three languages, automatically switching based on settings: @@ -114,6 +117,17 @@ The tray menu supports three languages, automatically switching based on setting | English | Open main window | Quit | | Japanese | Open main window | Quit | +### Lightweight Mode + +The tray menu includes a **Lightweight Mode** toggle (checkbox). When enabled: + +- The main window is closed to free up resources +- The app continues running in the system tray only +- You can still switch providers via the tray submenus +- On macOS, the Dock icon is also hidden + +To exit Lightweight Mode, uncheck the toggle or click "Open main window" — the main window will be rebuilt and shown. + ### Use Cases Switching providers via the tray menu doesn't require opening the main window, suitable for: @@ -121,6 +135,7 @@ Switching providers via the tray menu doesn't require opening the main window, s - Frequently switching providers - Quick operations when the main window is minimized - Managing configurations while running in the background +- Running in Lightweight Mode for minimal resource usage ## Settings Page diff --git a/docs/user-manual/en/1-getting-started/1.4-quickstart.md b/docs/user-manual/en/1-getting-started/1.4-quickstart.md index 37ab305f..23ec4725 100644 --- a/docs/user-manual/en/1-getting-started/1.4-quickstart.md +++ b/docs/user-manual/en/1-getting-started/1.4-quickstart.md @@ -35,6 +35,8 @@ After switching providers, each CLI tool activates differently: | Claude Code | Instant effect (supports hot reload) | | Codex | Requires closing and reopening the terminal | | Gemini | Instant effect (re-reads config on each request) | +| OpenCode | Requires closing and reopening the terminal | +| OpenClaw | Requires closing and reopening the terminal | ### Claude Code First Launch Prompt @@ -64,6 +66,14 @@ codex # Gemini - enter a test question after launching gemini > Hello, please briefly introduce yourself + +# OpenCode - enter a test question after launching +opencode +> Hello, please briefly introduce yourself + +# OpenClaw - enter a test question after launching +openclaw +> Hello, please briefly introduce yourself ``` If the AI responds normally, the configuration is successful. diff --git a/docs/user-manual/en/1-getting-started/1.5-settings.md b/docs/user-manual/en/1-getting-started/1.5-settings.md index 3d29bf3c..99b5032a 100644 --- a/docs/user-manual/en/1-getting-started/1.5-settings.md +++ b/docs/user-manual/en/1-getting-started/1.5-settings.md @@ -167,37 +167,74 @@ Import/export configuration backups. See the "Data Management" section above for ### Backup & Restore -Manage automatic backups: +The Backup Management panel provides full control over database backups. -| Setting | Description | -|---------|-------------| -| Backup Interval | Time interval for automatic backups (hours) | -| Retention Count | Number of backups to retain | +#### Auto-Backup Settings -Supports viewing the backup list and restoring from backups. +| Setting | Options | Default | +|---------|---------|---------| +| Backup Interval | Disabled, 6h, 12h, 24h, 48h, 7d | 24 hours | +| Retention Count | 3, 5, 10, 15, 20, 30, 50 | 10 backups | + +When an interval is set, CC Switch automatically backs up the database on schedule. Older backups beyond the retention count are automatically removed. + +#### Backup List + +The panel displays all existing backups with: +- **Display name** (auto-generated from timestamp, e.g., `db_backup_20260315_143000`) +- **Creation time** +- **File size** (e.g., "1.5 MB") + +#### Backup Operations + +| Action | Description | +|--------|-------------| +| **Backup Now** | Create a backup immediately | +| **Restore** | Restore the database from a selected backup. A safety backup of the current database is created automatically before restoring | +| **Rename** | Change the backup's display name | +| **Delete** | Permanently remove a backup (with confirmation) | + +> **Important**: Restoring a backup overwrites the current database. A safety backup is always created before the restore operation, so you can recover if needed. ### Cloud Sync (WebDAV) -Sync configurations across multiple devices via the WebDAV protocol. +Sync configurations across multiple devices via the WebDAV protocol. Uses **v2 protocol** with dual-layer versioning for improved reliability. | Setting | Description | |---------|-------------| | Service Preset | Jianguoyun / Nextcloud / Synology / Custom | | Server URL | WebDAV server URL | | Username | Login username | -| Password | Login password (app-specific password) | +| Password | Login password (app-specific password; saved credentials are preserved if left unchanged) | | Remote Directory | Remote storage path (default: `cc-switch-sync`) | | Profile Name | Device profile name (default: `default`) | -| Auto Sync | Automatically upload changes when enabled | +| Auto Sync | Enable automatic synchronization on a configurable interval | -Operations: +#### Operations -- **Test Connection**: Verify WebDAV configuration is correct -- **Save**: Save configuration and auto-test -- **Upload**: Upload local data to the remote server -- **Download**: Download data from the remote server to local +| Action | Description | +|--------|-------------| +| **Test Connection** | Verify WebDAV URL, username, and password are valid | +| **Upload** | Upload local database to remote. Shows progress spinner | +| **Download** | Download remote database. Shows remote snapshot info (protocol version, DB version, timestamp, size) before confirming. A safety backup of the local database is created automatically before overwriting | -> **Note**: Upload will overwrite remote data, and download will overwrite local data. Please confirm before proceeding. +#### Auto-Sync + +When **Auto Sync** is enabled: +- A confirmation dialog is shown on first activation +- CC Switch automatically syncs the database to WebDAV at the configured interval +- Sync status is displayed in the panel + +#### Remote Snapshot Info + +Before downloading, CC Switch displays details about the remote snapshot: +- Protocol version (v2) +- Database compatibility version +- Timestamp of the remote backup +- File size +- Compatibility status (warning if incompatible) + +> **Note**: Upload overwrites remote data, and download overwrites local data. A safety backup is always created before downloading. ### Log Configuration diff --git a/docs/user-manual/en/2-providers/2.1-add.md b/docs/user-manual/en/2-providers/2.1-add.md index 76d0f368..2fa07ce6 100644 --- a/docs/user-manual/en/2-providers/2.1-add.md +++ b/docs/user-manual/en/2-providers/2.1-add.md @@ -152,6 +152,22 @@ Presets are pre-configured provider templates that only require an API Key to us | AWS Bedrock | AWS Bedrock service | | OpenAI Compatible | OpenAI-compatible interface | +## Auto-Fetch Models + +When adding or editing a provider, you can auto-fetch available models from the provider's endpoint: + +1. Ensure the **API Key** and **Endpoint URL** are filled in +2. Click the **Fetch Models** button (download icon) next to the model input field +3. CC Switch calls the provider's `/v1/models` endpoint to retrieve the model list +4. Select a model from the dropdown, grouped by vendor + +This feature works for any provider that supports the OpenAI-compatible `/v1/models` API. It is available for Claude, Codex, Gemini, OpenCode, and OpenClaw providers. + +**Common errors:** +- **Authentication failed (401/403)**: Check your API Key +- **Endpoint not supported (404/405)**: The provider does not expose a `/v1/models` endpoint +- **Timeout**: The endpoint is slow to respond; try again later + ## Custom Configuration After selecting the "Custom" preset, you need to manually edit the JSON configuration. @@ -316,6 +332,45 @@ Batch import from SQL backup files: ## Advanced Options +### API Format (Claude Only) + +When adding a Claude provider that uses a third-party API, you may need to select the correct **API Format** in the Advanced Options section: + +| Format | Description | When to Use | +|--------|-------------|-------------| +| **Anthropic Messages** | Native Anthropic API format (default) | Direct Anthropic API or compatible proxies | +| **OpenAI Chat Completions** | OpenAI Chat API format, auto-converted by proxy | Provider only supports OpenAI Chat format | +| **OpenAI Responses API** | OpenAI Responses API format, auto-converted by proxy | Provider only supports OpenAI Responses format | + +> **Note**: API format conversion is handled by the proxy service. When using non-Anthropic formats, the proxy must be running with takeover enabled for correct request/response conversion. See [4.1 Proxy Service](../4-proxy/4.1-service.md) for details. + +The Advanced Options section auto-expands when a non-default API format is configured. + +### Claude Common Config Toggles + +When editing Claude providers, a set of **quick toggles** is available above the JSON editor: + +| Toggle | Effect | Config Change | +|--------|--------|---------------| +| **Hide Attribution** | Clears commit/PR attribution metadata | Sets `attribution: {commit: "", pr: ""}` | +| **Enable Teammates** | Enables the agent teams feature | Sets `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"` | +| **Enable Tool Search** | Enables tool search functionality | Sets `env.ENABLE_TOOL_SEARCH = "true"` | +| **High Effort** | Sets effort level to high | Sets `effortLevel = "high"` | +| **Disable Auto Upgrade** | Prevents Claude Code auto-updates | Sets `env.DISABLE_AUTOUPDATER = "1"` | + +When a toggle is unchecked, its corresponding config entry is removed entirely. Changes are reflected in the JSON editor in real-time. + +Additionally, the **Write Common Config** checkbox enables merging a global config snippet into the provider. Click **Edit Common Config** to customize the shared snippet. + +### Codex 1M Context Window + +When adding a Codex provider, an **Enable 1M Context Window** toggle is available: + +- **When enabled**: Sets `model_context_window = 1000000` and auto-fills `model_auto_compact_token_limit = 900000` in config.toml +- **When disabled**: Removes both fields + +The auto-compact limit can be customized in the text field that appears when the toggle is on. + ### Custom Icon Click the icon area to the left of the name to: diff --git a/docs/user-manual/en/2-providers/2.2-switch.md b/docs/user-manual/en/2-providers/2.2-switch.md index 7dced221..5b131ac7 100644 --- a/docs/user-manual/en/2-providers/2.2-switch.md +++ b/docs/user-manual/en/2-providers/2.2-switch.md @@ -26,10 +26,12 @@ Quickly switch providers via the system tray without opening the main interface. ### Steps 1. Right-click the CC Switch icon in the system tray -2. Find the corresponding app (Claude/Codex/Gemini/OpenCode) in the menu +2. Hover over the corresponding app submenu (e.g., "Claude · CurrentProvider") 3. Click the provider name you want to switch to 4. Switching completes with a brief tray notification +> Providers are organized into collapsible submenus by app type (Claude/Codex/Gemini). The submenu title shows the currently active provider name. + ### Tray Menu Structure ![image-20260108004348993](../../assets/image-20260108004348993.png) diff --git a/docs/user-manual/en/2-providers/2.3-edit.md b/docs/user-manual/en/2-providers/2.3-edit.md index 9f148266..82e4693b 100644 --- a/docs/user-manual/en/2-providers/2.3-edit.md +++ b/docs/user-manual/en/2-providers/2.3-edit.md @@ -52,6 +52,20 @@ When editing the currently active provider, a special "backfill" mechanism appli This ensures CC Switch and CLI tool configurations stay in sync. +## Auto-Fetch Models + +When editing a provider, you can auto-fetch the available model list from the provider's endpoint: + +1. Ensure the API Key and endpoint URL are filled in +2. Click the **Fetch Models** button (download icon) next to the model input field +3. Select a model from the grouped dropdown + +See [2.1 Add Provider — Auto-Fetch Models](./2.1-add.md#auto-fetch-models) for full details. + +## Common Config Toggles (Claude) + +When editing a Claude provider, quick toggle switches are available above the JSON editor for common settings like Tool Search, Disable Auto Upgrade, Teammates, and High Effort. See [2.1 Add Provider — Claude Common Config Toggles](./2.1-add.md#claude-common-config-toggles) for details. + ## Modify API Key When editing a provider, you can modify the key directly in the **API Key** input field: diff --git a/docs/user-manual/en/3-extensions/3.3-skills.md b/docs/user-manual/en/3-extensions/3.3-skills.md index 43dd8485..80736c57 100644 --- a/docs/user-manual/en/3-extensions/3.3-skills.md +++ b/docs/user-manual/en/3-extensions/3.3-skills.md @@ -118,8 +118,27 @@ Installation copies the skill folder to your local machine: ### Uninstall Effect -- Deletes the local skill folder -- Updates installation status +- **Automatic backup**: Before deletion, the skill is backed up to `~/.cc-switch/skill-backups/` +- Removes the skill from all app directories (Claude, Codex, Gemini, OpenCode) +- Removes the skill from the SSOT directory (`~/.cc-switch/skills/`) +- Deletes the skill record from the database + +### Restore from Backup + +If you need to restore a previously uninstalled skill: + +1. Open the Skills page +2. Click the **Restore from Backup** button +3. Select the backup you want to restore from the list (shows skill name and backup date) +4. The skill is restored and enabled for the current app + +### Delete Backups + +To remove old skill backups: + +1. In the restore dialog, find the backup you want to remove +2. Click the **Delete** button next to the backup entry +3. Confirm deletion — this cannot be undone ## Repository Management diff --git a/docs/user-manual/en/3-extensions/3.4-sessions.md b/docs/user-manual/en/3-extensions/3.4-sessions.md new file mode 100644 index 00000000..73afde0b --- /dev/null +++ b/docs/user-manual/en/3-extensions/3.4-sessions.md @@ -0,0 +1,131 @@ +# 3.4 Session Manager + +The Session Manager lets you browse, search, and manage conversation sessions from all supported CLI tools in one place. + +## Supported Applications + +| Application | Session Storage Location | +|-------------|--------------------------| +| Claude Code | `~/.cache/claude/projects/*.jsonl` | +| Codex | Codex config sessions directory | +| OpenCode | `~/.local/share/opencode/` (JSON or SQLite) | +| OpenClaw | `~/.openclaw/agents//sessions/*.jsonl` | +| Gemini CLI | `~/.cache/gemini/tmp//chats/` | + +## Opening the Session Manager + +Click the **Sessions** button in the main navigation bar toolbar. + +> **Note**: The Sessions button is visible for all five supported applications. + +## Interface Layout + +The Session Manager uses a **two-column layout**: + +- **Left panel**: Session list with search and filter toolbar +- **Right panel**: Selected session details with conversation history + +### Session List (Left Panel) + +Each session entry displays: +- Provider icon +- Session title +- Last active time (relative format, e.g., "5 min ago") + +### Session Details (Right Panel) + +When a session is selected, the right panel shows: +- **Title**: Derived from session title, project directory name, or session ID +- **Last active date/time**: Full timestamp +- **Project directory**: Clickable to copy full path (shows basename with tooltip for full path) +- **Resume command**: Displayed in monospace style when available +- **Conversation history**: Full message transcript + +## Search & Filtering + +### Full-Text Search + +Use the search box at the top of the left panel to search across: +- Session ID +- Title +- Summary +- Project directory +- Source file path + +The search supports prefix matching and filters results in real-time. Press **Esc** to clear the search. + +### Provider Filtering + +Click the provider filter dropdown (top-right of left panel) to filter by application: +- **All** — Show sessions from all providers +- **Claude Code** +- **Codex** +- **OpenCode** +- **OpenClaw** +- **Gemini CLI** + +The filter can be combined with search. + +### Refresh + +Click the refresh button (circular arrow icon) to re-scan all provider directories for new or deleted sessions. + +## Session Actions + +### Resume Session + +Click the **Resume** button (play icon) on a selected session to continue the conversation. + +**On macOS:** +- CC Switch launches your preferred terminal with the resume command +- The terminal opens in the session's project directory +- If terminal launch fails, the command is copied to your clipboard instead + +**Supported terminals (macOS):** Terminal.app, iTerm2, Ghostty, Kitty, WezTerm, Alacritty + +**On other platforms:** +- The resume command is copied to your clipboard +- Paste it into your terminal to resume + +> The Resume button is disabled if the session has no resume command available. + +### Delete Session + +Click the **Delete** button (trash icon) to permanently remove a session file. A confirmation dialog is shown before deletion. + +> Sessions without a local source path (e.g., immutable sessions) cannot be deleted. + +### Batch Operations + +For managing multiple sessions at once: + +1. Click the **Batch Mode** button (checkbox icon) in the left panel toolbar +2. Select sessions using the checkboxes that appear +3. Use **Select All** to select all filtered results, or **Clear** to deselect +4. Click **Batch Delete** (red trash icon) to delete all selected sessions + +A confirmation dialog shows the count before deletion. Results report the number of successful deletions and any failures. + +## Conversation History + +### Message Display + +Messages are color-coded by role: +- **User** messages: Green, left-aligned +- **AI** (Assistant) messages: Blue, right-aligned +- **System** messages: Amber +- **Tool** messages: Purple + +### Table of Contents + +For longer conversations, a Table of Contents is available: +- **Desktop (XL+ screens)**: Sidebar on the right showing user message previews +- **Smaller screens**: Floating button (list icon) at bottom-right that opens a dialog + +Click any entry to scroll to that message, which is briefly highlighted. + +## Tips + +- Sessions are sorted by last activity time (newest first) +- The session count badge updates as you search and filter +- OpenCode sessions may come from both JSON files and SQLite database — duplicates are automatically deduplicated diff --git a/docs/user-manual/en/3-extensions/3.5-workspace.md b/docs/user-manual/en/3-extensions/3.5-workspace.md new file mode 100644 index 00000000..4ebae8a9 --- /dev/null +++ b/docs/user-manual/en/3-extensions/3.5-workspace.md @@ -0,0 +1,85 @@ +# 3.5 Workspace Files & Daily Memory + +## Overview + +The Workspace panel provides file management and daily memory features for **OpenClaw**. It allows you to edit workspace configuration files and maintain a daily memory journal. + +> This feature is specific to OpenClaw. The Workspace button appears in the navigation bar when OpenClaw is the selected application. + +## Workspace Files + +### File Location + +All workspace files are stored in `~/.openclaw/workspace/`. + +Click the directory path at the top of the panel to open it in your file manager. + +### Available Files + +CC Switch manages 9 workspace files, each serving a specific purpose: + +| File | Description | +|------|-------------| +| **AGENTS.md** | Agents definition and configuration | +| **SOUL.md** | System soul/personality settings | +| **USER.md** | User profile information | +| **IDENTITY.md** | Identity and role definition | +| **TOOLS.md** | Available tools configuration | +| **MEMORY.md** | System memory | +| **HEARTBEAT.md** | Heartbeat configuration | +| **BOOTSTRAP.md** | Bootstrap sequence | +| **BOOT.md** | Boot configuration | + +### File Status + +Each file shows a status indicator: +- **Green checkmark**: File exists on disk +- **Empty circle**: File does not exist yet (will be created on first save) + +### Editing Files + +1. Click any file card to open the Markdown editor +2. Edit the content +3. Click **Save** to write changes to disk + +If the file doesn't exist yet, it will be created on first save. + +## Daily Memory + +The Daily Memory feature provides a date-organized journal system stored in `~/.openclaw/workspace/memory/`. + +### Accessing Daily Memory + +Click the **Daily Memory** card in the Workspace Files grid to open the memory panel. + +### File List + +The panel displays all daily memory files sorted by date (newest first). Each entry shows: +- **Date** (formatted from filename, e.g., `2026-04-01.md`) +- **File size** +- **Preview** (first 2 lines of content) + +### Create Today's Note + +Click the **Create Today** button to: +- Open a new note with today's date (`YYYY-MM-DD.md`) +- If today's note already exists, it opens for editing +- The file is persisted only after you click Save + +### Search + +Search across all daily memory files: + +1. Press **Cmd/Ctrl+F** or click the search icon +2. Enter your search term +3. Results show matching files with: + - Match count per file + - Snippet preview from the matching line + - File date and size + +Press **Esc** to close the search. + +### Edit & Delete + +- **Edit**: Click a file entry to open it in the Markdown editor +- **Delete**: Hover over a file entry and click the delete icon. A confirmation dialog is shown — deletion cannot be undone. diff --git a/docs/user-manual/en/4-proxy/4.1-service.md b/docs/user-manual/en/4-proxy/4.1-service.md index 05b99597..7b01ad9f 100644 --- a/docs/user-manual/en/4-proxy/4.1-service.md +++ b/docs/user-manual/en/4-proxy/4.1-service.md @@ -150,6 +150,20 @@ base_url = "http://127.0.0.1:15721/v1" GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721 ``` +## API Format Conversion + +The proxy supports automatic API format conversion for providers configured with non-Anthropic formats. This allows you to use providers that only support OpenAI-compatible APIs with Claude Code. + +| Provider API Format | Proxy Behavior | +|---------------------|----------------| +| **Anthropic Messages** | Pass-through (no conversion) | +| **OpenAI Chat Completions** | Converts Anthropic requests to OpenAI Chat format and responses back | +| **OpenAI Responses API** | Converts Anthropic requests to OpenAI Responses format and responses back | + +The API format is configured per-provider in the [Advanced Options](../2-providers/2.1-add.md#api-format-claude-only) when adding or editing a Claude provider. + +> **Note**: Format conversion requires the proxy to be running with app takeover enabled. The conversion handles both streaming and non-streaming requests. + ## Stop the Proxy ### Option 1: Main Interface Toggle diff --git a/docs/user-manual/en/5-faq/5.1-config-files.md b/docs/user-manual/en/5-faq/5.1-config-files.md index 4ca20f3f..4f1dfe04 100644 --- a/docs/user-manual/en/5-faq/5.1-config-files.md +++ b/docs/user-manual/en/5-faq/5.1-config-files.md @@ -12,12 +12,11 @@ Customizable location in settings (for cloud sync). ``` ~/.cc-switch/ -├── cc-switch.db # SQLite database +├── cc-switch.db # SQLite database (SSOT) ├── settings.json # Device-level settings -└── backups/ # Automatic backups - ├── backup-20251230-120000.json - ├── backup-20251229-180000.json - └── ... +├── skills/ # Skill SSOT directory +├── skill-backups/ # Skill backups (created on uninstall) +└── db_backup_*.db # Database backups ``` ### Database Contents diff --git a/docs/user-manual/en/5-faq/5.2-questions.md b/docs/user-manual/en/5-faq/5.2-questions.md index 624950be..7695aebe 100644 --- a/docs/user-manual/en/5-faq/5.2-questions.md +++ b/docs/user-manual/en/5-faq/5.2-questions.md @@ -183,6 +183,16 @@ chmod +x CC-Switch-*.AppImage 2. Manually download and install the latest version 3. If using Homebrew: `brew upgrade --cask cc-switch` +## Lightweight Mode + +### How to Enter Lightweight Mode? + +Toggle "Lightweight Mode" from the system tray menu. The main window closes, and CC Switch runs as a tray-only app. Toggle again or click "Open main window" to exit. + +### App Uses Less Memory in Lightweight Mode? + +Yes. Lightweight Mode destroys the main window and its web view, reducing memory usage significantly while keeping tray menu functionality available. + ## Getting Help ### Submit an Issue diff --git a/docs/user-manual/en/README.md b/docs/user-manual/en/README.md index 228c77b4..8c786f11 100644 --- a/docs/user-manual/en/README.md +++ b/docs/user-manual/en/README.md @@ -24,7 +24,9 @@ CC Switch User Manual ├── 3. Extensions │ ├── 3.1 MCP Server Management │ ├── 3.2 Prompts Management -│ └── 3.3 Skills Management +│ ├── 3.3 Skills Management +│ ├── 3.4 Session Manager +│ └── 3.5 Workspace & Memory │ ├── 4. Proxy & High Availability │ ├── 4.1 Proxy Service @@ -69,6 +71,8 @@ CC Switch User Manual | [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP protocol, add servers, app binding | | [3.2-prompts.md](./3-extensions/3.2-prompts.md) | Create presets, activate/switch, smart backfill | | [3.3-skills.md](./3-extensions/3.3-skills.md) | Discover skills, install/uninstall, repository management | +| [3.4-sessions.md](./3-extensions/3.4-sessions.md) | Session Manager: browse, search, resume, delete sessions | +| [3.5-workspace.md](./3-extensions/3.5-workspace.md) | Workspace files and daily memory (OpenClaw) | ### 4. Proxy & High Availability @@ -99,9 +103,9 @@ CC Switch User Manual ## Version Information -- Documentation version: v3.12.0 -- Last updated: 2026-03-09 -- Applicable to CC Switch v3.12.0+ +- Documentation version: v3.12.3 +- Last updated: 2026-04-04 +- Applicable to CC Switch v3.12.3+ ## Contributing diff --git a/docs/user-manual/ja/1-getting-started/1.3-interface.md b/docs/user-manual/ja/1-getting-started/1.3-interface.md index cbd07094..c177bc55 100644 --- a/docs/user-manual/ja/1-getting-started/1.3-interface.md +++ b/docs/user-manual/ja/1-getting-started/1.3-interface.md @@ -100,10 +100,13 @@ CC Switch はシステムトレイにアイコンを表示し、クイック操 | メニュー項目 | 機能 | |--------|------| | メインウィンドウを開く | メインウィンドウを表示してフォーカス | -| アプリグループ | Claude/Codex/Gemini/OpenCode/OpenClaw ごとにプロバイダーを表示 | -| プロバイダーリスト | クリックで切り替え、現在有効なものにはチェックマークを表示 | +| アプリサブメニュー | Claude/Codex/Gemini/OpenCode/OpenClaw ごとの折りたたみサブメニュー（例：「Claude · PackyCode」） | +| プロバイダーリスト | 各サブメニュー内でクリックして切り替え、現在有効なものにはチェックマークを表示 | +| ライトウェイトモード | トグルチェックボックスでトレイ専用モードの開始/終了 | | 終了 | アプリを完全に終了 | +> **注意**：各アプリのサブメニュータイトルには現在のプロバイダー名が表示されます（例：「Claude · PackyCode」）。プロバイダーが設定されていないアプリでは、無効化された「(プロバイダーなし)」エントリが表示されます。アプリの表示はアプリの表示設定で制御されます。 + ### 多言語対応 トレイメニューは 3 つの言語に対応し、設定に応じて自動的に切り替わります： @@ -114,6 +117,17 @@ CC Switch はシステムトレイにアイコンを表示し、クイック操 | English | Open main window | Quit | | 日本語 | メインウィンドウを開く | 終了 | +### ライトウェイトモード + +トレイメニューには **ライトウェイトモード** のトグル（チェックボックス）があります。有効にすると： + +- メインウィンドウが閉じられ、リソースが解放される +- アプリはシステムトレイのみで動作を継続 +- トレイのサブメニューからプロバイダーの切り替えが可能 +- macOS では Dock アイコンも非表示になる + +ライトウェイトモードを終了するには、トグルのチェックを外すか「メインウィンドウを開く」をクリックします。メインウィンドウが再構築されて表示されます。 + ### 使用シーン トレイからのプロバイダー切り替えはメイン画面を開く必要がなく、以下の場面に適しています： @@ -121,6 +135,7 @@ CC Switch はシステムトレイにアイコンを表示し、クイック操 - 頻繁にプロバイダーを切り替える場合 - メインウィンドウが最小化されているときの素早い操作 - バックグラウンド実行中の設定管理 +- ライトウェイトモードでリソース使用量を最小化 ## 設定ページ diff --git a/docs/user-manual/ja/1-getting-started/1.4-quickstart.md b/docs/user-manual/ja/1-getting-started/1.4-quickstart.md index 024f0e85..ef5d060d 100644 --- a/docs/user-manual/ja/1-getting-started/1.4-quickstart.md +++ b/docs/user-manual/ja/1-getting-started/1.4-quickstart.md @@ -33,8 +33,10 @@ | アプリ | 反映方法 | |------|----------| | Claude Code | 即時反映（ホットリロード対応） | -| Codex | ターミナルを閉じて再度開く必要あり | +| Codex | ターミナルの再起動が必要 | | Gemini | 即時反映（リクエストごとに設定を再読み込み） | +| OpenCode | ターミナルの再起動が必要 | +| OpenClaw | ターミナルの再起動が必要 | ### Claude Code の初回インストール時の注意 @@ -64,6 +66,14 @@ codex # Gemini - 起動後にテスト質問を入力 gemini > こんにちは、簡単に自己紹介してください + +# OpenCode - 起動後にテスト質問を入力 +opencode +> こんにちは、簡単に自己紹介してください + +# OpenClaw - 起動後にテスト質問を入力 +openclaw +> こんにちは、簡単に自己紹介してください ``` AI が正常に回答すれば、設定は成功です。 diff --git a/docs/user-manual/ja/1-getting-started/1.5-settings.md b/docs/user-manual/ja/1-getting-started/1.5-settings.md index 2630b6ca..fa2f9e46 100644 --- a/docs/user-manual/ja/1-getting-started/1.5-settings.md +++ b/docs/user-manual/ja/1-getting-started/1.5-settings.md @@ -167,37 +167,74 @@ CC Switch の送信 HTTP/HTTPS プロキシを設定します。外部 API に ### バックアップと復元 -自動バックアップの管理： +バックアップ管理パネルでは、データベースバックアップを完全に管理できます。 -| 設定 | 説明 | -| -------- | -------------------------- | -| バックアップ間隔 | 自動バックアップの時間間隔（時間） | -| 保持数量 | 保持するバックアップの数 | +#### 自動バックアップ設定 -バックアップリストの表示とバックアップからの復元をサポートします。 +| 設定 | オプション | デフォルト | +|------|---------|---------| +| バックアップ間隔 | 無効、6時間、12時間、24時間、48時間、7日 | 24時間 | +| 保持数 | 3、5、10、15、20、30、50 | 10件 | + +間隔を設定すると、CC Switch はスケジュールに従って自動的にデータベースをバックアップします。保持数を超えた古いバックアップは自動的に削除されます。 + +#### バックアップリスト + +パネルには既存のすべてのバックアップが以下の情報とともに表示されます： +- **表示名**（タイムスタンプから自動生成、例：`db_backup_20260315_143000`） +- **作成日時** +- **ファイルサイズ**（例：「1.5 MB」） + +#### バックアップ操作 + +| 操作 | 説明 | +|------|------| +| **今すぐバックアップ** | 即座にバックアップを作成 | +| **復元** | 選択したバックアップからデータベースを復元。復元前に現在のデータベースの安全バックアップが自動的に作成される | +| **名前変更** | バックアップの表示名を変更 | +| **削除** | バックアップを完全に削除（確認あり） | + +> **重要**：バックアップの復元は現在のデータベースを上書きします。復元前に安全バックアップが自動作成されるため、必要に応じて元に戻すことができます。 ### クラウド同期（WebDAV） -WebDAV プロトコルを使用して複数のデバイス間で設定を同期します。 +WebDAV プロトコルを使用して複数のデバイス間で設定を同期します。信頼性の向上のため、デュアルレイヤーバージョニングを備えた **v2 プロトコル** を使用しています。 | 設定項目 | 説明 | | -------- | ------------------------------------- | | サービスプリセット | 坚果云 / Nextcloud / Synology / カスタム | | サーバー URL | WebDAV サーバー URL | | ユーザー名 | ログインユーザー名 | -| パスワード | ログインパスワード（アプリ専用パスワード） | +| パスワード | ログインパスワード（アプリ専用パスワード、保存済みの場合は未変更で保持） | | リモートディレクトリ | リモート保存パス（デフォルト `cc-switch-sync`） | | プロファイル名 | デバイスプロファイル名（デフォルト `default`） | -| 自動同期 | 有効にすると変更を自動アップロード | +| 自動同期 | 設定可能な間隔で自動同期を有効化 | -操作： +#### 操作 -- **接続テスト**：WebDAV 設定が正しいか確認 -- **保存**：設定を保存して自動テスト -- **アップロード**：ローカルデータをリモートにアップロード -- **ダウンロード**：リモートからローカルにデータをダウンロード +| 操作 | 説明 | +|------|------| +| **接続テスト** | WebDAV の URL、ユーザー名、パスワードが有効か確認 | +| **アップロード** | ローカルデータベースをリモートにアップロード。進捗スピナーを表示 | +| **ダウンロード** | リモートデータベースをダウンロード。確認前にリモートスナップショット情報（プロトコルバージョン、DB バージョン、タイムスタンプ、サイズ）を表示。上書き前にローカルデータベースの安全バックアップを自動作成 | -> **注意**：アップロードはリモートデータを、ダウンロードはローカルデータを上書きします。操作前にご確認ください。 +#### 自動同期 + +**自動同期** を有効にすると： +- 初回有効化時に確認ダイアログが表示される +- CC Switch は設定された間隔で自動的にデータベースを WebDAV に同期 +- 同期ステータスがパネルに表示される + +#### リモートスナップショット情報 + +ダウンロード前に、CC Switch はリモートスナップショットの詳細を表示します： +- プロトコルバージョン（v2） +- データベース互換バージョン +- リモートバックアップのタイムスタンプ +- ファイルサイズ +- 互換性ステータス（非互換の場合は警告） + +> **注意**：アップロードはリモートデータを、ダウンロードはローカルデータを上書きします。ダウンロード前に安全バックアップが自動作成されます。 ### ログ設定 diff --git a/docs/user-manual/ja/2-providers/2.1-add.md b/docs/user-manual/ja/2-providers/2.1-add.md index d7d42b18..1dfc096d 100644 --- a/docs/user-manual/ja/2-providers/2.1-add.md +++ b/docs/user-manual/ja/2-providers/2.1-add.md @@ -152,6 +152,22 @@ | AWS Bedrock | AWS Bedrock サービス | | OpenAI Compatible | OpenAI 互換インターフェース | +## モデル自動取得 + +プロバイダーの追加や編集時に、プロバイダーのエンドポイントから利用可能なモデルを自動取得できます： + +1. **API Key** と **エンドポイントアドレス** が入力されていることを確認 +2. モデル入力フィールドの横にある **モデル取得** ボタン（ダウンロードアイコン）をクリック +3. CC Switch がプロバイダーの `/v1/models` エンドポイントを呼び出してモデルリストを取得 +4. ベンダー別にグループ化されたドロップダウンからモデルを選択 + +この機能は、OpenAI 互換の `/v1/models` API をサポートするすべてのプロバイダーで動作します。Claude、Codex、Gemini、OpenCode、OpenClaw のプロバイダーで利用可能です。 + +**よくあるエラー：** +- **認証失敗（401/403）**：API Key を確認してください +- **エンドポイント未対応（404/405）**：プロバイダーが `/v1/models` エンドポイントを公開していません +- **タイムアウト**：エンドポイントの応答が遅いです。後ほど再試行してください + ## カスタム設定 「カスタム」プリセットを選択した場合、JSON 設定を手動で編集する必要があります。 @@ -316,6 +332,45 @@ SQL バックアップファイルから一括インポート： ## 高度なオプション +### API フォーマット（Claude のみ） + +サードパーティ API を使用する Claude プロバイダーを追加する際、高度なオプションセクションで正しい **API フォーマット** を選択する必要がある場合があります： + +| フォーマット | 説明 | 使用場面 | +|------|------|------| +| **Anthropic Messages** | ネイティブ Anthropic API フォーマット（デフォルト） | Anthropic API に直接接続、または互換プロキシ | +| **OpenAI Chat Completions** | OpenAI Chat API フォーマット、プロキシが自動変換 | プロバイダーが OpenAI Chat フォーマットのみ対応 | +| **OpenAI Responses API** | OpenAI Responses API フォーマット、プロキシが自動変換 | プロバイダーが OpenAI Responses フォーマットのみ対応 | + +> **注意**：API フォーマットの変換はプロキシサービスが担当します。Anthropic 以外のフォーマットを使用する場合、リクエスト/レスポンスの正しい変換のためにプロキシが接管有効の状態で稼働している必要があります。詳しくは [4.1 プロキシサービス](../4-proxy/4.1-service.md) をご覧ください。 + +デフォルト以外の API フォーマットが設定されている場合、高度なオプションセクションが自動展開されます。 + +### Claude 共通設定クイックトグル + +Claude プロバイダーの編集時、JSON エディタの上部に **クイックトグル** が利用できます： + +| トグル | 効果 | 設定変更 | +|------|------|------| +| **帰属情報を非表示** | コミット/PR の帰属メタデータをクリア | `attribution: {commit: "", pr: ""}` を設定 | +| **チームメイトを有効化** | エージェントチーム機能を有効化 | `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"` を設定 | +| **ツール検索を有効化** | ツール検索機能を有効化 | `env.ENABLE_TOOL_SEARCH = "true"` を設定 | +| **高強度** | エフォートレベルを高に設定 | `effortLevel = "high"` を設定 | +| **自動アップグレードを無効化** | Claude Code の自動更新を防止 | `env.DISABLE_AUTOUPDATER = "1"` を設定 | + +トグルのチェックを外すと、対応する設定エントリが完全に削除されます。変更は JSON エディタにリアルタイムで反映されます。 + +また、**共通設定を書き込み** チェックボックスを有効にすると、グローバル設定スニペットをプロバイダーにマージできます。**共通設定を編集** をクリックして共有スニペットをカスタマイズできます。 + +### Codex 1M コンテキストウィンドウ + +Codex プロバイダーの追加時、**1M コンテキストウィンドウを有効化** トグルが利用できます： + +- **有効時**：config.toml に `model_context_window = 1000000` を設定し、`model_auto_compact_token_limit = 900000` を自動入力 +- **無効時**：両方のフィールドを削除 + +トグルがオンの場合に表示されるテキストフィールドで、自動コンパクト制限をカスタマイズできます。 + ### カスタムアイコン 名前の左側にあるアイコンエリアをクリックすると： diff --git a/docs/user-manual/ja/2-providers/2.2-switch.md b/docs/user-manual/ja/2-providers/2.2-switch.md index 60525875..fda323cd 100644 --- a/docs/user-manual/ja/2-providers/2.2-switch.md +++ b/docs/user-manual/ja/2-providers/2.2-switch.md @@ -26,10 +26,12 @@ ### 操作手順 1. システムトレイの CC Switch アイコンを右クリック -2. メニューで対応するアプリ（Claude/Codex/Gemini/OpenCode）を見つける +2. 対応するアプリのサブメニュー（例：「Claude · 現在のプロバイダー」）にマウスを合わせる 3. 切り替えたいプロバイダー名をクリック 4. 切り替え完了、トレイに短い通知が表示 +> プロバイダーはアプリタイプ（Claude/Codex/Gemini）ごとに折りたたみサブメニューに整理されています。サブメニューのタイトルには現在有効なプロバイダー名が表示されます。 + ### トレイメニュー構造 ![image-20260108004348993](../../assets/image-20260108004348993.png) diff --git a/docs/user-manual/ja/2-providers/2.3-edit.md b/docs/user-manual/ja/2-providers/2.3-edit.md index 1f80f72e..68eb675c 100644 --- a/docs/user-manual/ja/2-providers/2.3-edit.md +++ b/docs/user-manual/ja/2-providers/2.3-edit.md @@ -52,6 +52,20 @@ JSON 形式の設定内容（以下を含む）： これにより、CC Switch と CLI ツールの設定が常に同期されます。 +## モデル自動取得 + +プロバイダーの編集時に、プロバイダーのエンドポイントから利用可能なモデルリストを自動取得できます： + +1. API Key とエンドポイントアドレスが入力されていることを確認 +2. モデル入力フィールドの横にある **モデル取得** ボタン（ダウンロードアイコン）をクリック +3. グループ化されたドロップダウンからモデルを選択 + +詳しくは [2.1 プロバイダーの追加 - モデル自動取得](./2.1-add.md#モデル自動取得) をご覧ください。 + +## 共通設定クイックトグル（Claude） + +Claude プロバイダーの編集時、JSON エディタの上部にツール検索、自動アップグレード無効化、チームメイト、高強度などの共通設定のクイックトグルスイッチが利用できます。詳しくは [2.1 プロバイダーの追加 - Claude 共通設定クイックトグル](./2.1-add.md#claude-共通設定クイックトグル) をご覧ください。 + ## API Key の変更 プロバイダーの編集時に、**API Key** 入力ボックスから直接変更できます： diff --git a/docs/user-manual/ja/3-extensions/3.3-skills.md b/docs/user-manual/ja/3-extensions/3.3-skills.md index 79c2abe4..1045ea8e 100644 --- a/docs/user-manual/ja/3-extensions/3.3-skills.md +++ b/docs/user-manual/ja/3-extensions/3.3-skills.md @@ -118,8 +118,27 @@ CC Switch は強力な検索とフィルタリング機能を提供していま ### アンインストールの効果 -- ローカルのスキルフォルダを削除 -- インストール状態を更新 +- **自動バックアップ**：削除前にスキルが `~/.cc-switch/skill-backups/` にバックアップされる +- すべてのアプリディレクトリ（Claude、Codex、Gemini、OpenCode）からスキルを削除 +- SSOT ディレクトリ（`~/.cc-switch/skills/`）からスキルを削除 +- データベースからスキルレコードを削除 + +### バックアップから復元 + +以前アンインストールしたスキルを復元する場合： + +1. Skills ページを開く +2. **バックアップから復元** ボタンをクリック +3. リスト（スキル名とバックアップ日が表示）から復元したいバックアップを選択 +4. スキルが復元され、現在のアプリで有効化される + +### バックアップの削除 + +古いスキルバックアップを削除するには： + +1. 復元ダイアログで削除したいバックアップを見つける +2. バックアップエントリの横にある **削除** ボタンをクリック +3. 削除を確認（この操作は取り消せません） ## リポジトリ管理 diff --git a/docs/user-manual/ja/3-extensions/3.4-sessions.md b/docs/user-manual/ja/3-extensions/3.4-sessions.md new file mode 100644 index 00000000..7290fbee --- /dev/null +++ b/docs/user-manual/ja/3-extensions/3.4-sessions.md @@ -0,0 +1,131 @@ +# 3.4 セッションマネージャー + +セッションマネージャーでは、対応するすべての CLI ツールの会話セッションを一か所で閲覧、検索、管理できます。 + +## 対応アプリ + +| アプリ | セッション保存場所 | +|------|----------| +| Claude Code | `~/.cache/claude/projects/*.jsonl` | +| Codex | Codex 設定のセッションディレクトリ | +| OpenCode | `~/.local/share/opencode/`（JSON または SQLite） | +| OpenClaw | `~/.openclaw/agents//sessions/*.jsonl` | +| Gemini CLI | `~/.cache/gemini/tmp//chats/` | + +## セッションマネージャーを開く + +メインナビゲーションバーの **セッション** ボタンをクリックします。 + +> **注意**：セッションボタンは対応する 5 つのアプリすべてで表示されます。 + +## インターフェースのレイアウト + +セッションマネージャーは **2 カラムレイアウト** を採用しています： + +- **左パネル**：検索とフィルターツールバー付きのセッションリスト +- **右パネル**：選択したセッションの詳細と会話履歴 + +### セッションリスト（左パネル） + +各セッションエントリには以下が表示されます： +- プロバイダーアイコン +- セッションタイトル +- 最終アクティブ時間（相対形式、例：「5分前」） + +### セッション詳細（右パネル） + +セッションを選択すると、右パネルに以下が表示されます： +- **タイトル**：セッションタイトル、プロジェクトディレクトリ名、またはセッション ID から取得 +- **最終アクティブ日時**：完全なタイムスタンプ +- **プロジェクトディレクトリ**：クリックでフルパスをコピー（ベース名とツールチップでフルパスを表示） +- **再開コマンド**：利用可能な場合、モノスペースフォントで表示 +- **会話履歴**：メッセージの全文記録 + +## 検索とフィルタリング + +### 全文検索 + +左パネル上部の検索ボックスを使用して、以下の項目を横断的に検索できます： +- セッション ID +- タイトル +- サマリー +- プロジェクトディレクトリ +- ソースファイルパス + +前方一致検索に対応し、リアルタイムで結果をフィルタリングします。**Esc** で検索をクリアできます。 + +### プロバイダーフィルター + +左パネル右上のプロバイダーフィルタードロップダウンをクリックして、アプリ別にフィルタリングします： +- **すべて** — すべてのプロバイダーのセッションを表示 +- **Claude Code** +- **Codex** +- **OpenCode** +- **OpenClaw** +- **Gemini CLI** + +フィルターは検索と組み合わせて使用できます。 + +### 更新 + +更新ボタン（循環矢印アイコン）をクリックすると、すべてのプロバイダーディレクトリを再スキャンして新しいセッションや削除済みセッションを検出します。 + +## セッション操作 + +### セッションの再開 + +選択したセッションの **再開** ボタン（再生アイコン）をクリックして、会話を続行します。 + +**macOS の場合：** +- CC Switch は設定済みのターミナルで再開コマンドを起動します +- ターミナルはセッションのプロジェクトディレクトリで開きます +- ターミナルの起動に失敗した場合、コマンドがクリップボードにコピーされます + +**対応ターミナル（macOS）：** Terminal.app、iTerm2、Ghostty、Kitty、WezTerm、Alacritty + +**その他のプラットフォーム：** +- 再開コマンドがクリップボードにコピーされます +- ターミナルに貼り付けてセッションを再開してください + +> 再開コマンドが利用できないセッションでは、再開ボタンは無効になります。 + +### セッションの削除 + +**削除** ボタン（ゴミ箱アイコン）をクリックすると、セッションファイルが完全に削除されます。削除前に確認ダイアログが表示されます。 + +> ローカルソースパスのないセッション（不変のセッションなど）は削除できません。 + +### 一括操作 + +複数のセッションを一度に管理するには： + +1. 左パネルツールバーの **一括モード** ボタン（チェックボックスアイコン）をクリック +2. 表示されるチェックボックスでセッションを選択 +3. **すべて選択** でフィルタリング結果をすべて選択、または **クリア** で選択解除 +4. **一括削除**（赤いゴミ箱アイコン）をクリックして選択したすべてのセッションを削除 + +削除前に件数を表示する確認ダイアログが表示されます。結果には成功した削除件数と失敗件数が報告されます。 + +## 会話履歴 + +### メッセージの表示 + +メッセージは役割ごとに色分けされます： +- **ユーザー** メッセージ：緑、左寄せ +- **AI**（アシスタント）メッセージ：青、右寄せ +- **システム** メッセージ：アンバー +- **ツール** メッセージ：パープル + +### 目次 + +長い会話の場合、目次機能が利用できます： +- **デスクトップ（XL+ 画面）**：右側のサイドバーにユーザーメッセージのプレビューを表示 +- **小さい画面**：右下のフローティングボタン（リストアイコン）をクリックするとダイアログが開く + +エントリをクリックすると該当メッセージにスクロールし、一時的にハイライト表示されます。 + +## ヒント + +- セッションは最終アクティブ時間の新しい順にソートされます +- セッション数バッジは検索やフィルタリングに応じて更新されます +- OpenCode のセッションは JSON ファイルと SQLite データベースの両方から取得される場合があります（重複は自動的に除去されます） diff --git a/docs/user-manual/ja/3-extensions/3.5-workspace.md b/docs/user-manual/ja/3-extensions/3.5-workspace.md new file mode 100644 index 00000000..ae31a17c --- /dev/null +++ b/docs/user-manual/ja/3-extensions/3.5-workspace.md @@ -0,0 +1,85 @@ +# 3.5 ワークスペースファイルとデイリーメモリー + +## 概要 + +ワークスペースパネルは、**OpenClaw** 向けのファイル管理とデイリーメモリー機能を提供します。ワークスペース設定ファイルの編集やデイリーメモリージャーナルの管理が可能です。 + +> この機能は OpenClaw 専用です。ワークスペースボタンは、OpenClaw が選択されている場合にナビゲーションバーに表示されます。 + +## ワークスペースファイル + +### ファイルの保存場所 + +すべてのワークスペースファイルは `~/.openclaw/workspace/` に保存されます。 + +パネル上部のディレクトリパスをクリックすると、ファイルマネージャーで開きます。 + +### 利用可能なファイル + +CC Switch は 9 つのワークスペースファイルを管理しており、それぞれ特定の役割を持っています： + +| ファイル | 説明 | +|------|------| +| **AGENTS.md** | エージェントの定義と設定 | +| **SOUL.md** | システムのソウル/パーソナリティ設定 | +| **USER.md** | ユーザープロファイル情報 | +| **IDENTITY.md** | アイデンティティとロールの定義 | +| **TOOLS.md** | 利用可能なツールの設定 | +| **MEMORY.md** | システムメモリー | +| **HEARTBEAT.md** | ハートビート設定 | +| **BOOTSTRAP.md** | ブートストラップシーケンス | +| **BOOT.md** | ブート設定 | + +### ファイルステータス + +各ファイルにはステータスインジケーターが表示されます： +- **緑のチェックマーク**：ファイルがディスク上に存在 +- **空の円**：ファイルがまだ存在しない（初回保存時に作成） + +### ファイルの編集 + +1. ファイルカードをクリックして Markdown エディタを開く +2. コンテンツを編集 +3. **保存** をクリックしてディスクに書き込み + +ファイルがまだ存在しない場合は、初回保存時に作成されます。 + +## デイリーメモリー + +デイリーメモリー機能は、`~/.openclaw/workspace/memory/` に保存される日付別のジャーナルシステムを提供します。 + +### デイリーメモリーへのアクセス + +ワークスペースファイルグリッドの **デイリーメモリー** カードをクリックして、メモリーパネルを開きます。 + +### ファイルリスト + +パネルには日付の新しい順にすべてのデイリーメモリーファイルが表示されます。各エントリには以下が表示されます： +- **日付**（ファイル名から変換、例：`2026-04-01.md`） +- **ファイルサイズ** +- **プレビュー**（コンテンツの最初の 2 行） + +### 今日のノートを作成 + +**今日のノートを作成** ボタンをクリックすると： +- 今日の日付（`YYYY-MM-DD.md`）で新しいノートを開く +- 今日のノートがすでに存在する場合は、編集用に開く +- ファイルは保存をクリックした後に保存される + +### 検索 + +すべてのデイリーメモリーファイルを横断検索できます： + +1. **Cmd/Ctrl+F** を押すか、検索アイコンをクリック +2. 検索語を入力 +3. 結果には以下が表示されます： + - ファイルごとのマッチ数 + - マッチした行のスニペットプレビュー + - ファイルの日付とサイズ + +**Esc** で検索を閉じます。 + +### 編集と削除 + +- **編集**：ファイルエントリをクリックして Markdown エディタで開く +- **削除**：ファイルエントリにマウスをホバーして削除アイコンをクリック。確認ダイアログが表示されます（削除は取り消せません）。 diff --git a/docs/user-manual/ja/4-proxy/4.1-service.md b/docs/user-manual/ja/4-proxy/4.1-service.md index 32b217ba..35169c63 100644 --- a/docs/user-manual/ja/4-proxy/4.1-service.md +++ b/docs/user-manual/ja/4-proxy/4.1-service.md @@ -150,6 +150,20 @@ base_url = "http://127.0.0.1:15721/v1" GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721 ``` +## API フォーマット変換 + +プロキシは、Anthropic 以外のフォーマットが設定されたプロバイダーに対して、API フォーマットの自動変換をサポートします。これにより、OpenAI 互換 API のみをサポートするプロバイダーを Claude Code で使用できます。 + +| プロバイダー API フォーマット | プロキシの動作 | +|------|------| +| **Anthropic Messages** | パススルー（変換なし） | +| **OpenAI Chat Completions** | Anthropic リクエストを OpenAI Chat フォーマットに変換し、レスポンスを逆変換 | +| **OpenAI Responses API** | Anthropic リクエストを OpenAI Responses フォーマットに変換し、レスポンスを逆変換 | + +API フォーマットはプロバイダーごとに、Claude プロバイダーの追加・編集時の[高度なオプション](../2-providers/2.1-add.md#api-フォーマットclaude-のみ)で設定します。 + +> **注意**：フォーマット変換にはプロキシがアプリ接管有効の状態で稼働している必要があります。変換はストリーミングと非ストリーミングの両方のリクエストに対応しています。 + ## プロキシの停止 ### 方法 1：メイン画面のスイッチ diff --git a/docs/user-manual/ja/5-faq/5.1-config-files.md b/docs/user-manual/ja/5-faq/5.1-config-files.md index 135a0fc5..09df32ee 100644 --- a/docs/user-manual/ja/5-faq/5.1-config-files.md +++ b/docs/user-manual/ja/5-faq/5.1-config-files.md @@ -12,12 +12,11 @@ ``` ~/.cc-switch/ -├── cc-switch.db # SQLite データベース +├── cc-switch.db # SQLite データベース（SSOT） ├── settings.json # デバイスレベルの設定 -└── backups/ # 自動バックアップ - ├── backup-20251230-120000.json - ├── backup-20251229-180000.json - └── ... +├── skills/ # スキル SSOT ディレクトリ +├── skill-backups/ # スキルバックアップ（アンインストール時に作成） +└── db_backup_*.db # データベースバックアップ ``` ### データベースの内容 diff --git a/docs/user-manual/ja/5-faq/5.2-questions.md b/docs/user-manual/ja/5-faq/5.2-questions.md index 71eb74b4..313348b5 100644 --- a/docs/user-manual/ja/5-faq/5.2-questions.md +++ b/docs/user-manual/ja/5-faq/5.2-questions.md @@ -183,6 +183,16 @@ chmod +x CC-Switch-*.AppImage 2. 最新版を手動でダウンロードしてインストール 3. Homebrew を使用する場合：`brew upgrade --cask cc-switch` +## ライトウェイトモード + +### ライトウェイトモードに入るには？ + +システムトレイメニューから「ライトウェイトモード」をトグルします。メインウィンドウが閉じ、CC Switch はトレイ専用アプリとして動作します。再度トグルするか「メインウィンドウを開く」をクリックすると終了します。 + +### ライトウェイトモードではメモリ使用量が少なくなる？ + +はい。ライトウェイトモードではメインウィンドウとその Web ビューを破棄するため、トレイメニュー機能を維持しながらメモリ使用量を大幅に削減します。 + ## ヘルプの入手 ### Issue の提出 diff --git a/docs/user-manual/ja/README.md b/docs/user-manual/ja/README.md index 7c5f11af..f6a73844 100644 --- a/docs/user-manual/ja/README.md +++ b/docs/user-manual/ja/README.md @@ -24,7 +24,9 @@ CC Switch ユーザーマニュアル ├── 3. 拡張機能 │ ├── 3.1 MCP サーバー管理 │ ├── 3.2 Prompts プロンプト管理 -│ └── 3.3 Skills スキル管理 +│ ├── 3.3 Skills スキル管理 +│ ├── 3.4 セッションマネージャー +│ └── 3.5 ワークスペースとメモリー │ ├── 4. プロキシと高可用性 │ ├── 4.1 プロキシサービス @@ -69,6 +71,8 @@ CC Switch ユーザーマニュアル | [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP プロトコル、サーバーの追加、アプリバインド | | [3.2-prompts.md](./3-extensions/3.2-prompts.md) | プリセットの作成、有効化の切り替え、スマートバックフィル | | [3.3-skills.md](./3-extensions/3.3-skills.md) | スキルの発見、インストール・アンインストール、リポジトリ管理 | +| [3.4-sessions.md](./3-extensions/3.4-sessions.md) | セッションマネージャー：閲覧、検索、再開、削除 | +| [3.5-workspace.md](./3-extensions/3.5-workspace.md) | ワークスペースファイルとデイリーメモリー（OpenClaw） | ### 4. プロキシと高可用性 @@ -99,9 +103,9 @@ CC Switch ユーザーマニュアル ## バージョン情報 -- ドキュメントバージョン：v3.12.0 -- 最終更新：2026-03-09 -- CC Switch v3.12.0+ 対応 +- ドキュメントバージョン：v3.12.3 +- 最終更新：2026-04-04 +- CC Switch v3.12.3+ 対応 ## コントリビュート diff --git a/docs/user-manual/zh/1-getting-started/1.3-interface.md b/docs/user-manual/zh/1-getting-started/1.3-interface.md index 11554a1a..e7a1eb25 100644 --- a/docs/user-manual/zh/1-getting-started/1.3-interface.md +++ b/docs/user-manual/zh/1-getting-started/1.3-interface.md @@ -100,10 +100,13 @@ CC Switch 在系统托盘显示图标，提供快速操作入口。 | 菜单项 | 功能 | |--------|------| | 打开主界面 | 显示主窗口并聚焦 | -| 应用分组 | 按 Claude/Codex/Gemini/OpenCode/OpenClaw 分组显示供应商 | -| 供应商列表 | 点击切换，当前启用的显示勾选标记 | +| 应用子菜单 | 按 Claude/Codex/Gemini/OpenCode/OpenClaw 分组的折叠子菜单（如 "Claude · PackyCode"） | +| 供应商列表 | 在每个子菜单内，点击切换，当前启用的显示勾选标记 | +| 轻量模式 | 勾选框切换，进入/退出仅托盘运行模式 | | 退出 | 完全退出应用 | +> **注意**：每个应用子菜单的标题会显示当前供应商名称（如 "Claude · PackyCode"）。没有配置供应商的应用会显示禁用的"(无供应商)"条目。应用可见性由设置中的"应用可见性"选项控制。 + ### 多语言支持 托盘菜单支持三种语言，根据设置自动切换： @@ -114,6 +117,17 @@ CC Switch 在系统托盘显示图标，提供快速操作入口。 | English | Open main window | Quit | | 日本語 | メインウィンドウを開く | 終了 | +### 轻量模式 + +托盘菜单包含 **轻量模式** 切换开关（勾选框）。启用后： + +- 主窗口关闭以释放资源 +- 应用仅在系统托盘中运行 +- 你仍可通过托盘子菜单切换供应商 +- 在 macOS 上，Dock 图标也会隐藏 + +要退出轻量模式，取消勾选该选项或点击"打开主界面" — 主窗口将被重建并显示。 + ### 使用场景 托盘切换供应商无需打开主界面，适合： @@ -121,6 +135,7 @@ CC Switch 在系统托盘显示图标，提供快速操作入口。 - 频繁切换供应商 - 主窗口最小化时快速操作 - 后台运行时管理配置 +- 使用轻量模式以最小化资源占用 ## 设置页面 diff --git a/docs/user-manual/zh/1-getting-started/1.4-quickstart.md b/docs/user-manual/zh/1-getting-started/1.4-quickstart.md index 63c4b3f6..f79b6a04 100644 --- a/docs/user-manual/zh/1-getting-started/1.4-quickstart.md +++ b/docs/user-manual/zh/1-getting-started/1.4-quickstart.md @@ -33,8 +33,10 @@ | 应用 | 生效方式 | |------|----------| | Claude Code | ✅ 即时生效（支持热重载） | -| Codex | 需关闭并重新打开终端 | +| Codex | 需要关闭并重新打开终端 | | Gemini | ✅ 即时生效（每次请求重新读取配置） | +| OpenCode | 需要关闭并重新打开终端 | +| OpenClaw | 需要关闭并重新打开终端 | ### Claude Code 首次安装提示 @@ -64,6 +66,14 @@ codex # Gemini - 启动后输入测试问题 gemini > 你好，请简单介绍一下自己 + +# OpenCode - 启动后输入测试问题 +opencode +> 你好，请简单介绍一下自己 + +# OpenClaw - 启动后输入测试问题 +openclaw +> 你好，请简单介绍一下自己 ``` 如果 AI 能正常回复，说明配置成功。 diff --git a/docs/user-manual/zh/1-getting-started/1.5-settings.md b/docs/user-manual/zh/1-getting-started/1.5-settings.md index 3f9a591c..2ac4748b 100644 --- a/docs/user-manual/zh/1-getting-started/1.5-settings.md +++ b/docs/user-manual/zh/1-getting-started/1.5-settings.md @@ -167,37 +167,74 @@ CC Switch 自身数据的存储位置，默认为 `~/.cc-switch/`。 ### 备份与恢复 -管理自动备份： +备份管理面板提供对数据库备份的全面控制。 -| 配置 | 说明 | -| -------- | -------------------------- | -| 备份间隔 | 自动备份的时间间隔（小时） | -| 保留数量 | 保留的备份份数 | +#### 自动备份设置 -支持查看备份列表和从备份恢复。 +| 配置 | 选项 | 默认值 | +| -------- | ---------------------------------- | --------- | +| 备份间隔 | 禁用、6h、12h、24h、48h、7d | 24 小时 | +| 保留数量 | 3、5、10、15、20、30、50 | 10 个备份 | + +设置间隔后，CC Switch 会按计划自动备份数据库。超出保留数量的旧备份会自动删除。 + +#### 备份列表 + +面板显示所有现有备份，包含： +- **显示名称**（根据时间戳自动生成，如 `db_backup_20260315_143000`） +- **创建时间** +- **文件大小**（如 "1.5 MB"） + +#### 备份操作 + +| 操作 | 说明 | +| ------------ | ------------------------------------------------------------------------ | +| **立即备份** | 立即创建一个备份 | +| **恢复** | 从选定的备份恢复数据库。恢复前会自动创建当前数据库的安全备份 | +| **重命名** | 修改备份的显示名称 | +| **删除** | 永久删除备份（需确认） | + +> ⚠️ **重要**：恢复备份会覆盖当前数据库。恢复操作前始终会自动创建安全备份，以便在需要时恢复。 ### 云同步（WebDAV） -通过 WebDAV 协议在多台设备间同步配置。 +通过 WebDAV 协议在多台设备间同步配置。使用 **v2 协议**，支持双层版本控制，提高可靠性。 -| 配置项 | 说明 | -| -------- | ------------------------------------- | -| 服务预设 | 坚果云 / Nextcloud / 群晖 / 自定义 | -| 服务地址 | WebDAV 服务器 URL | -| 用户名 | 登录用户名 | -| 密码 | 登录密码（应用专用密码） | -| 远程目录 | 远程存储路径（默认 `cc-switch-sync`） | -| 配置名称 | 设备配置文件名（默认 `default`） | -| 自动同步 | 开启后自动上传变更 | +| 配置项 | 说明 | +| -------- | ---------------------------------------------------------------------------- | +| 服务预设 | 坚果云 / Nextcloud / 群晖 / 自定义 | +| 服务地址 | WebDAV 服务器 URL | +| 用户名 | 登录用户名 | +| 密码 | 登录密码（应用专用密码；已保存的凭据在未修改时会被保留） | +| 远程目录 | 远程存储路径（默认 `cc-switch-sync`） | +| 配置名称 | 设备配置文件名（默认 `default`） | +| 自动同步 | 开启后按配置的间隔自动同步 | -操作： +#### 操作 -- **测试连接**：验证 WebDAV 配置是否正确 -- **保存**：保存配置并自动测试 -- **上传**：将本地数据上传到远程 -- **下载**：从远程下载数据到本地 +| 操作 | 说明 | +| ------------ | -------------------------------------------------------------------------------------------- | +| **测试连接** | 验证 WebDAV URL、用户名和密码是否有效 | +| **上传** | 将本地数据库上传到远程，显示进度指示器 | +| **下载** | 下载远程数据库。下载前显示远程快照信息（协议版本、数据库版本、时间戳、大小）供确认。覆盖本地数据库前会自动创建安全备份 | -> ⚠️ **注意**：上传会覆盖远程数据，下载会覆盖本地数据。操作前请确认。 +#### 自动同步 + +启用 **自动同步** 后： +- 首次激活时会显示确认对话框 +- CC Switch 按配置的间隔自动将数据库同步到 WebDAV +- 面板中显示同步状态 + +#### 远程快照信息 + +下载前，CC Switch 会显示远程快照的详细信息： +- 协议版本（v2） +- 数据库兼容版本 +- 远程备份的时间戳 +- 文件大小 +- 兼容性状态（不兼容时显示警告） + +> ⚠️ **注意**：上传会覆盖远程数据，下载会覆盖本地数据。下载前始终会自动创建安全备份。 ### 日志配置 diff --git a/docs/user-manual/zh/2-providers/2.1-add.md b/docs/user-manual/zh/2-providers/2.1-add.md index dec61e12..56347683 100644 --- a/docs/user-manual/zh/2-providers/2.1-add.md +++ b/docs/user-manual/zh/2-providers/2.1-add.md @@ -152,6 +152,22 @@ | AWS Bedrock | AWS Bedrock 服务 | | OpenAI Compatible | OpenAI 兼容接口 | +## 自动获取模型 + +添加或编辑供应商时，可以自动从供应商端点获取可用模型列表： + +1. 确保已填写 **API Key** 和 **端点地址** +2. 点击模型输入框旁的 **获取模型** 按钮（下载图标） +3. CC Switch 调用供应商的 `/v1/models` 端点获取模型列表 +4. 从按供应商分组的下拉菜单中选择模型 + +此功能适用于所有支持 OpenAI 兼容 `/v1/models` API 的供应商。Claude、Codex、Gemini、OpenCode 和 OpenClaw 供应商均可使用。 + +**常见错误**： +- **认证失败（401/403）**：检查你的 API Key +- **端点不支持（404/405）**：该供应商未提供 `/v1/models` 端点 +- **超时**：端点响应缓慢，请稍后重试 + ## 自定义配置 选择「自定义」预设后，需要手动编辑 JSON 配置。 @@ -316,6 +332,45 @@ CC Switch 支持两种方式导入供应商配置： ## 高级选项 +### API 格式（仅 Claude） + +添加使用第三方 API 的 Claude 供应商时，可能需要在高级选项中选择正确的 **API 格式**： + +| 格式 | 说明 | 适用场景 | +|------|------|----------| +| **Anthropic Messages** | 原生 Anthropic API 格式（默认） | 直接 Anthropic API 或兼容代理 | +| **OpenAI Chat Completions** | OpenAI Chat API 格式，由代理自动转换 | 供应商仅支持 OpenAI Chat 格式 | +| **OpenAI Responses API** | OpenAI Responses API 格式，由代理自动转换 | 供应商仅支持 OpenAI Responses 格式 | + +> **注意**：API 格式转换由代理服务处理。使用非 Anthropic 格式时，需要开启代理并启用应用接管才能正确转换请求/响应。详见 [4.1 代理服务](../4-proxy/4.1-service.md)。 + +当配置了非默认 API 格式时，高级选项区域会自动展开。 + +### Claude 通用配置快捷开关 + +编辑 Claude 供应商时，JSON 编辑器上方提供一组 **快捷开关**： + +| 开关 | 效果 | 配置变更 | +|------|------|----------| +| **隐藏署名** | 清除提交/PR 的署名元数据 | 设置 `attribution: {commit: "", pr: ""}` | +| **启用 Teammates** | 启用 Agent 团队功能 | 设置 `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"` | +| **启用工具搜索** | 启用工具搜索功能 | 设置 `env.ENABLE_TOOL_SEARCH = "true"` | +| **高效能模式** | 将 effort 级别设为 high | 设置 `effortLevel = "high"` | +| **禁用自动更新** | 阻止 Claude Code 自动更新 | 设置 `env.DISABLE_AUTOUPDATER = "1"` | + +取消勾选开关时，对应的配置项会被完全移除。更改会实时反映在 JSON 编辑器中。 + +此外，**写入通用配置** 复选框可将全局配置片段合并到供应商中。点击 **编辑通用配置** 可自定义共享的配置片段。 + +### Codex 1M 上下文窗口 + +添加 Codex 供应商时，提供 **启用 1M 上下文窗口** 开关： + +- **启用时**：在 config.toml 中设置 `model_context_window = 1000000` 并自动填充 `model_auto_compact_token_limit = 900000` +- **禁用时**：移除这两个字段 + +开关开启后显示的文本框可自定义自动压缩限制值。 + ### 自定义图标 点击名称左侧的图标区域，可以： diff --git a/docs/user-manual/zh/2-providers/2.2-switch.md b/docs/user-manual/zh/2-providers/2.2-switch.md index e61998f6..fcc79a27 100644 --- a/docs/user-manual/zh/2-providers/2.2-switch.md +++ b/docs/user-manual/zh/2-providers/2.2-switch.md @@ -26,10 +26,12 @@ ### 操作步骤 1. 右键点击系统托盘的 CC Switch 图标 -2. 在菜单中找到对应应用（Claude/Codex/Gemini/OpenCode） -3. 点击要切换的供应商名称 +2. 将鼠标悬停在对应应用的子菜单上（如 "Claude · 当前供应商"） +3. 点击要切换到的供应商名称 4. 切换完成，托盘会短暂提示 +> 供应商按应用类型（Claude/Codex/Gemini）组织到折叠子菜单中。子菜单标题显示当前激活的供应商名称。 + ### 托盘菜单结构 ![image-20260108004348993](../../assets/image-20260108004348993.png) diff --git a/docs/user-manual/zh/2-providers/2.3-edit.md b/docs/user-manual/zh/2-providers/2.3-edit.md index cc8c494a..4909c7a4 100644 --- a/docs/user-manual/zh/2-providers/2.3-edit.md +++ b/docs/user-manual/zh/2-providers/2.3-edit.md @@ -52,6 +52,20 @@ JSON 格式的配置内容，包括： 这确保了 CC Switch 和 CLI 工具的配置始终同步。 +## 自动获取模型 + +编辑供应商时，可以自动从供应商端点获取可用模型列表： + +1. 确保已填写 API Key 和端点地址 +2. 点击模型输入框旁的 **获取模型** 按钮（下载图标） +3. 从分组下拉菜单中选择模型 + +详细说明请参阅 [2.1 添加供应商 — 自动获取模型](./2.1-add.md#自动获取模型)。 + +## 通用配置快捷开关（Claude） + +编辑 Claude 供应商时，JSON 编辑器上方提供常用设置的快捷开关，包括工具搜索、禁用自动更新、Teammates、高效能模式等。详见 [2.1 添加供应商 — Claude 通用配置快捷开关](./2.1-add.md#claude-通用配置快捷开关)。 + ## 修改 API Key 编辑供应商时，可以直接在 **API Key** 输入框中修改： diff --git a/docs/user-manual/zh/3-extensions/3.3-skills.md b/docs/user-manual/zh/3-extensions/3.3-skills.md index ce48fdb0..5354f923 100644 --- a/docs/user-manual/zh/3-extensions/3.3-skills.md +++ b/docs/user-manual/zh/3-extensions/3.3-skills.md @@ -118,8 +118,27 @@ CC Switch 提供强大的搜索和过滤功能： ### 卸载效果 -- 删除本地技能文件夹 -- 更新安装状态 +- **自动备份**：删除前，技能会被备份到 `~/.cc-switch/skill-backups/` +- 从所有应用目录（Claude、Codex、Gemini、OpenCode）移除技能 +- 从 SSOT 目录（`~/.cc-switch/skills/`）移除技能 +- 从数据库删除技能记录 + +### 从备份恢复 + +如需恢复之前卸载的技能： + +1. 打开 Skills 页面 +2. 点击 **从备份恢复** 按钮 +3. 从列表中选择要恢复的备份（显示技能名称和备份日期） +4. 技能将被恢复并为当前应用启用 + +### 删除备份 + +如需删除旧的技能备份： + +1. 在恢复对话框中，找到要删除的备份 +2. 点击备份条目旁的 **删除** 按钮 +3. 确认删除 — 此操作不可撤销 ## 仓库管理 diff --git a/docs/user-manual/zh/3-extensions/3.4-sessions.md b/docs/user-manual/zh/3-extensions/3.4-sessions.md new file mode 100644 index 00000000..ecd4c775 --- /dev/null +++ b/docs/user-manual/zh/3-extensions/3.4-sessions.md @@ -0,0 +1,131 @@ +# 3.4 会话管理器 + +会话管理器可让你在一处浏览、搜索和管理所有支持的 CLI 工具的对话会话。 + +## 支持的应用 + +| 应用 | 会话存储位置 | +|------|-------------| +| Claude Code | `~/.cache/claude/projects/*.jsonl` | +| Codex | Codex 配置会话目录 | +| OpenCode | `~/.local/share/opencode/`（JSON 或 SQLite） | +| OpenClaw | `~/.openclaw/agents//sessions/*.jsonl` | +| Gemini CLI | `~/.cache/gemini/tmp//chats/` | + +## 打开会话管理器 + +点击主导航栏中的 **会话** 按钮。 + +> **注意**：会话按钮在所有五种应用模式下均可见。 + +## 界面布局 + +会话管理器采用 **双栏布局**： + +- **左侧面板**：会话列表，包含搜索和过滤工具栏 +- **右侧面板**：选中会话的详情和对话历史 + +### 会话列表（左侧面板） + +每个会话条目显示： +- 供应商图标 +- 会话标题 +- 最后活跃时间（相对格式，如"5 分钟前"） + +### 会话详情（右侧面板） + +选中会话后，右侧面板显示： +- **标题**：来自会话标题、项目目录名称或会话 ID +- **最后活跃日期/时间**：完整时间戳 +- **项目目录**：可点击复制完整路径（显示目录名，完整路径以提示框显示） +- **恢复命令**：以等宽字体显示（如可用） +- **对话历史**：完整消息记录 + +## 搜索与过滤 + +### 全文搜索 + +使用左侧面板顶部的搜索框，可搜索以下内容： +- 会话 ID +- 标题 +- 摘要 +- 项目目录 +- 源文件路径 + +搜索支持前缀匹配，实时过滤结果。按 **Esc** 清除搜索。 + +### 供应商过滤 + +点击左侧面板右上角的供应商过滤下拉菜单，按应用过滤： +- **全部** — 显示所有供应商的会话 +- **Claude Code** +- **Codex** +- **OpenCode** +- **OpenClaw** +- **Gemini CLI** + +过滤可与搜索组合使用。 + +### 刷新 + +点击刷新按钮（圆形箭头图标），重新扫描所有供应商目录以发现新增或已删除的会话。 + +## 会话操作 + +### 恢复会话 + +点击选中会话上的 **恢复** 按钮（播放图标）继续对话。 + +**macOS 上**： +- CC Switch 使用你偏好的终端启动恢复命令 +- 终端会在会话的项目目录中打开 +- 如果终端启动失败，命令会被复制到剪贴板 + +**支持的终端（macOS）**：Terminal.app、iTerm2、Ghostty、Kitty、WezTerm、Alacritty + +**其他平台**： +- 恢复命令会被复制到剪贴板 +- 在终端中粘贴即可恢复会话 + +> 如果会话没有可用的恢复命令，恢复按钮将被禁用。 + +### 删除会话 + +点击 **删除** 按钮（垃圾桶图标）永久删除会话文件。删除前会显示确认对话框。 + +> 没有本地源路径的会话（如不可变会话）无法删除。 + +### 批量操作 + +批量管理多个会话： + +1. 点击左侧面板工具栏中的 **批量模式** 按钮（复选框图标） +2. 使用出现的复选框选择会话 +3. 使用 **全选** 选择所有过滤结果，或使用 **清除** 取消选择 +4. 点击 **批量删除**（红色垃圾桶图标）删除所有选中的会话 + +删除前会显示确认对话框并展示数量。结果会报告成功删除的数量和失败的数量。 + +## 对话历史 + +### 消息显示 + +消息按角色以颜色区分： +- **用户** 消息：绿色，左对齐 +- **AI**（助手）消息：蓝色，右对齐 +- **系统** 消息：琥珀色 +- **工具** 消息：紫色 + +### 目录导航 + +对于较长的对话，提供目录导航功能： +- **桌面端（XL+ 屏幕）**：右侧边栏显示用户消息预览 +- **较小屏幕**：右下角浮动按钮（列表图标），点击打开对话框 + +点击任意条目可滚动到对应消息，消息会短暂高亮显示。 + +## 提示 + +- 会话按最后活跃时间排序（最新在前） +- 会话数量徽章会随搜索和过滤实时更新 +- OpenCode 会话可能来自 JSON 文件和 SQLite 数据库 — 重复项会自动去重 diff --git a/docs/user-manual/zh/3-extensions/3.5-workspace.md b/docs/user-manual/zh/3-extensions/3.5-workspace.md new file mode 100644 index 00000000..679f88ae --- /dev/null +++ b/docs/user-manual/zh/3-extensions/3.5-workspace.md @@ -0,0 +1,85 @@ +# 3.5 工作区文件与每日记忆 + +## 概述 + +工作区面板为 **OpenClaw** 提供文件管理和每日记忆功能。你可以编辑工作区配置文件并维护每日记忆日志。 + +> 此功能为 OpenClaw 专属。当 OpenClaw 为当前选中的应用时，导航栏中会显示工作区按钮。 + +## 工作区文件 + +### 文件位置 + +所有工作区文件存储在 `~/.openclaw/workspace/`。 + +点击面板顶部的目录路径可在文件管理器中打开。 + +### 可用文件 + +CC Switch 管理 9 个工作区文件，每个文件有特定用途： + +| 文件 | 说明 | +|------|------| +| **AGENTS.md** | Agent 定义与配置 | +| **SOUL.md** | 系统灵魂/性格设置 | +| **USER.md** | 用户资料信息 | +| **IDENTITY.md** | 身份与角色定义 | +| **TOOLS.md** | 可用工具配置 | +| **MEMORY.md** | 系统记忆 | +| **HEARTBEAT.md** | 心跳配置 | +| **BOOTSTRAP.md** | 引导序列 | +| **BOOT.md** | 启动配置 | + +### 文件状态 + +每个文件显示状态指示器： +- **绿色对勾**：文件已存在 +- **空心圆圈**：文件尚未创建（首次保存时创建） + +### 编辑文件 + +1. 点击任意文件卡片打开 Markdown 编辑器 +2. 编辑内容 +3. 点击 **保存** 将更改写入磁盘 + +如果文件尚不存在，将在首次保存时创建。 + +## 每日记忆 + +每日记忆功能提供按日期组织的日志系统，存储在 `~/.openclaw/workspace/memory/`。 + +### 访问每日记忆 + +点击工作区文件网格中的 **每日记忆** 卡片，打开记忆面板。 + +### 文件列表 + +面板显示所有每日记忆文件，按日期排序（最新在前）。每个条目显示： +- **日期**（从文件名格式化，如 `2026-04-01.md`） +- **文件大小** +- **预览**（内容的前 2 行） + +### 创建今日笔记 + +点击 **创建今日** 按钮： +- 打开以今日日期命名的新笔记（`YYYY-MM-DD.md`） +- 如果今日笔记已存在，则打开进行编辑 +- 文件仅在点击保存后才会持久化 + +### 搜索 + +搜索所有每日记忆文件： + +1. 按 **Cmd/Ctrl+F** 或点击搜索图标 +2. 输入搜索词 +3. 结果显示匹配的文件，包含： + - 每个文件的匹配数量 + - 匹配行的片段预览 + - 文件日期和大小 + +按 **Esc** 关闭搜索。 + +### 编辑与删除 + +- **编辑**：点击文件条目在 Markdown 编辑器中打开 +- **删除**：将鼠标悬停在文件条目上，点击删除图标。会显示确认对话框 — 删除操作不可撤销。 diff --git a/docs/user-manual/zh/4-proxy/4.1-service.md b/docs/user-manual/zh/4-proxy/4.1-service.md index 7da91844..0dd12b6e 100644 --- a/docs/user-manual/zh/4-proxy/4.1-service.md +++ b/docs/user-manual/zh/4-proxy/4.1-service.md @@ -150,6 +150,20 @@ base_url = "http://127.0.0.1:15721/v1" GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721 ``` +## API 格式转换 + +代理支持为配置了非 Anthropic 格式的供应商自动进行 API 格式转换。这使你可以将仅支持 OpenAI 兼容 API 的供应商用于 Claude Code。 + +| 供应商 API 格式 | 代理行为 | +|-----------------|----------| +| **Anthropic Messages** | 透传（不转换） | +| **OpenAI Chat Completions** | 将 Anthropic 请求转换为 OpenAI Chat 格式，响应反向转换 | +| **OpenAI Responses API** | 将 Anthropic 请求转换为 OpenAI Responses 格式，响应反向转换 | + +API 格式在添加或编辑 Claude 供应商时于[高级选项](../2-providers/2.1-add.md#api-格式仅-claude)中按供应商配置。 + +> **注意**：格式转换需要代理运行并启用应用接管。转换同时支持流式和非流式请求。 + ## 停止代理 ### 方式一：主界面开关 diff --git a/docs/user-manual/zh/5-faq/5.1-config-files.md b/docs/user-manual/zh/5-faq/5.1-config-files.md index 83ec2e74..5d19c842 100644 --- a/docs/user-manual/zh/5-faq/5.1-config-files.md +++ b/docs/user-manual/zh/5-faq/5.1-config-files.md @@ -12,12 +12,11 @@ ``` ~/.cc-switch/ -├── cc-switch.db # SQLite 数据库 +├── cc-switch.db # SQLite 数据库（SSOT） ├── settings.json # 设备级设置 -└── backups/ # 自动备份 - ├── backup-20251230-120000.json - ├── backup-20251229-180000.json - └── ... +├── skills/ # 技能 SSOT 目录 +├── skill-backups/ # 技能备份（卸载时创建） +└── db_backup_*.db # 数据库备份 ``` ### 数据库内容 diff --git a/docs/user-manual/zh/5-faq/5.2-questions.md b/docs/user-manual/zh/5-faq/5.2-questions.md index 150038af..3f0a5e82 100644 --- a/docs/user-manual/zh/5-faq/5.2-questions.md +++ b/docs/user-manual/zh/5-faq/5.2-questions.md @@ -183,6 +183,16 @@ chmod +x CC-Switch-*.AppImage 2. 手动下载最新版本安装 3. 如使用 Homebrew：`brew upgrade --cask cc-switch` +## 轻量模式 + +### 如何进入轻量模式？ + +从系统托盘菜单切换"轻量模式"。主窗口关闭，CC Switch 仅作为托盘应用运行。再次切换或点击"打开主界面"即可退出。 + +### 轻量模式下应用占用更少内存？ + +是的。轻量模式会销毁主窗口及其 Web 视图，显著减少内存占用，同时保留托盘菜单功能。 + ## 获取帮助 ### 提交 Issue diff --git a/docs/user-manual/zh/README.md b/docs/user-manual/zh/README.md index 02e31240..918194bd 100644 --- a/docs/user-manual/zh/README.md +++ b/docs/user-manual/zh/README.md @@ -24,7 +24,9 @@ ├── 3. 扩展功能 │ ├── 3.1 MCP 服务器管理 │ ├── 3.2 Prompts 提示词管理 -│ └── 3.3 Skills 技能管理 +│ ├── 3.3 Skills 技能管理 +│ ├── 3.4 会话管理器 +│ └── 3.5 工作区文件与每日记忆 │ ├── 4. 代理与高可用 │ ├── 4.1 代理服务 @@ -69,6 +71,8 @@ | [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP 协议、添加服务器、应用绑定 | | [3.2-prompts.md](./3-extensions/3.2-prompts.md) | 创建预设、激活切换、智能回填 | | [3.3-skills.md](./3-extensions/3.3-skills.md) | 发现技能、安装卸载、仓库管理 | +| [3.4-sessions.md](./3-extensions/3.4-sessions.md) | 会话浏览、搜索过滤、恢复与删除 | +| [3.5-workspace.md](./3-extensions/3.5-workspace.md) | OpenClaw 工作区文件、每日记忆 | ### 4. 代理与高可用 @@ -99,9 +103,9 @@ ## 版本信息 -- 文档版本：v3.12.0 -- 最后更新：2026-03-09 -- 适用于 CC Switch v3.12.0+ +- 文档版本：v3.12.3 +- 最后更新：2026-04-04 +- 适用于 CC Switch v3.12.3+ ## 贡献