From 263df6d5a9d5bab904c476994b5de7f0a999364a Mon Sep 17 00:00:00 2001 From: maguowei Date: Sat, 10 Oct 2026 22:01:29 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs(readme):=20=E4=BC=98=E5=8C=96=E4=B8=AD?= =?UTF-8?q?=E8=8B=B1=E6=96=87=E8=87=AA=E8=BF=B0=E6=96=87=E6=A1=A3=E6=8E=92?= =?UTF-8?q?=E7=89=88=E4=B8=8E=E5=8F=AF=E8=AF=BB=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 134 ++++++++++++++++++++++++++---------------------- README.zh-CN.md | 128 ++++++++++++++++++++++++--------------------- 2 files changed, 143 insertions(+), 119 deletions(-) diff --git a/README.md b/README.md index 358bf79..ec229e9 100644 --- a/README.md +++ b/README.md @@ -4,24 +4,26 @@ [![CI](https://github.com/maguowei/code-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/maguowei/code-manager/actions/workflows/ci.yml) [![Release](https://github.com/maguowei/code-manager/actions/workflows/release.yml/badge.svg)](https://github.com/maguowei/code-manager/actions/workflows/release.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) ![Code Manager profile editor](docs/assets/readme-hero.webp) -Code Manager is a local desktop management app for Claude Code users. It brings profiles, providers, the `~/.claude` directory, memories, Skills, history, stats, token usage, project status, the system tray, and diagnostic logs together in a single Tauri 2 app, making your local configuration more visible, previewable, and verifiable. +**Code Manager** is a cross-platform desktop management application for Claude Code users, built with Tauri 2. It unifies your profiles, providers, `~/.claude` directory, memories, Skills, session history, token usage, project status, system tray, and diagnostic logs into a single interface — making local configuration visible, previewable, and verifiable. -This document is for human users and project visitors. Execution rules for AI agents are in [CLAUDE.md](./CLAUDE.md), the full usage guide is in [docs/user-manual.md](./docs/user-manual.md), and platform differences are in [docs/platform-support.md](./docs/platform-support.md). +> [!NOTE] +> This document is for human users and project visitors. AI agent execution rules live in [CLAUDE.md](./CLAUDE.md), full usage documentation is in [docs/user-manual.md](./docs/user-manual.md), and platform differences are documented in [docs/platform-support.md](./docs/platform-support.md). ## The Problem It Solves -Over long-term use of Claude Code, local configuration and session data tend to scatter across many files: +As you use Claude Code across different projects, configuration and session data quickly scatter across various local files: -- Different projects need different models, API endpoints, tokens, permissions, hooks, and plugin combinations. -- `~/.claude/settings.json`, `CLAUDE.md`, `rules/*.md`, and Skills are hard to review as a whole. -- Provider / model configuration is repetitive, and switching profiles easily misses environment variables or overrides user settings. -- History, stats, token spend, project Git status, and worktree information lack a single entry point. -- Troubleshooting requires quickly viewing redacted application logs instead of hunting for log files everywhere. +- **Fragmented settings**: Different projects require distinct models, API endpoints, tokens, permissions, hooks, and plugins. +- **Hidden state**: `~/.claude/settings.json`, `CLAUDE.md`, `rules/*.md`, and Skills are difficult to inspect as a whole. +- **Configuration friction**: Switching providers or models is repetitive, with the risk of missing environment variables or accidentally overwriting user settings. +- **Scattered telemetry**: Session history, token expenditure, project Git status, and worktrees lack a unified entry point. +- **Cumbersome troubleshooting**: Resolving issues often requires hunting down system log files rather than inspecting structured, sanitized logs. -Code Manager does not replace Claude Code; it provides a management layer for local configuration, session data, and diagnostic information. +Code Manager does not replace Claude Code; it provides a dedicated control plane for managing local configurations, session data, and diagnostics. ## Core Capabilities @@ -29,27 +31,27 @@ Code Manager does not replace Claude Code; it provides a management layer for lo | Capability | Description | | --- | --- | -| `~/.claude` Overview | Browse, preview, edit, and locate the Claude Code user directory. | -| Profiles / Built-in Providers | Manage the profile layer ultimately written to `~/.claude/settings.json`, picking connection endpoints and model mappings from built-in (read-only) providers. Edit models, environment variables, permissions, Sandbox, hooks, plugins, and the status line; preview, copy, test models, apply in one click, import / export (optionally with secrets, with a pre-save preview), compare diffs, and sync common options / marketplaces / plugins to other profiles in one click. | -| Memory Management | Manage user-level `CLAUDE.md` and `rules/*.md`, with support for the Karpathy behavior guide preset, import, enable, disable, copy, preview, and path validation. | -| Skills Management | Create, edit, delete, enable, and disable Claude Code Skills, and sync them as `~/.codex/skills/` symlinks. | -| History & Sessions | Read `~/.claude/history.jsonl` and view history details by project and session. | -| Stats & Recent Sessions | Read a local stats snapshot from `~/.claude.json`. | -| Token Usage & Cost | Scan `~/.claude/projects/**/*.jsonl`, aggregate tokens and cost by date, project, session, and model, with incremental SQLite caching. | -| Project Management | Show project paths, remotes, branches, worktrees, project-level `.claude/`, `AGENTS.md` / `CLAUDE.md`, and `.agents/skills` status, with support for opening a terminal/editor, jumping to history/usage, branch and worktree cleanup, and clearing local project data. | -| System Tray & Session Focus | Show the current profile and active Claude Code sessions in the menu bar, with session-count styles and a pending-session breathing indicator, attempt to focus existing terminal sessions on supported platforms, and (macOS only) mirror session state to ANTICATER USB device LED effects. | -| Desktop Usage Widget | An always-on-top, translucent mini-window that shows today's token spend, usage, and cache-hit metrics in real time, with drag support, customizable metrics, and adjustable opacity, toggleable in settings. | -| Settings & Diagnostics | Support language, theme, default-collapsed sidebar, menu-bar session display, system notifications, third-party model pricing, launch at login, default terminal and editor, session-focus shortcut and LED effects (macOS only), desktop usage widget toggle and metric customization, redacted log viewing, system info copy, and log rotation. | +| **`~/.claude` Overview** | Browse, preview, edit, and quickly locate files in the Claude Code user directory. | +| **Profiles & Providers** | Manage configuration layers written to `~/.claude/settings.json`. Select connection endpoints and model mappings from built-in (read-only) providers. Visually edit models, environment variables, permissions, Sandbox, hooks, plugins, and the status line. Supports connectivity testing, pre-apply diffs, secret-safe import/export, and one-click sync across profiles. | +| **Memory Management** | Manage user-level `CLAUDE.md` and `rules/*.md` files with path validation. Includes Karpathy behavior guide presets, toggle switches (enable/disable), previewing, and cloning. | +| **Skills Management** | Create, edit, toggle, and organize Claude Code Skills, with automatic symlink syncing to `~/.codex/skills/`. | +| **History & Sessions** | Parse `~/.claude/history.jsonl` to explore session timelines, prompts, and summaries filtered by project. | +| **Stats & Insights** | Read local activity snapshots from `~/.claude.json` to monitor usage trends and recent sessions. | +| **Token Usage & Cost** | Scan `~/.claude/projects/**/*.jsonl` with an incremental SQLite engine. Aggregate token counts and costs by date, project, session, and model. | +| **Project Workspace** | Track Git branches, remotes, worktrees, project-level `.claude/`, rules (`AGENTS.md` / `CLAUDE.md`), and skills. Quickly launch a terminal or code editor. | +| **System Tray & Focus** | Monitor active sessions from the system menu bar with pending-session breathing indicators, jump to active terminals via shortcuts, and mirror session state to ANTICATER USB LEDs (macOS only). | +| **Desktop Usage Widget** | An always-on-top, translucent mini-window displaying today's token spend, usage, and cache-hit metrics in real time, with drag support and customizable metrics. | +| **Settings & Diagnostics** | Customize theme, language, default terminal/editor, model pricing overrides, and launch-at-login. Built-in log viewer with automatic secret redaction and one-click system info export. | ## Download and Install -On macOS, installing via Homebrew (own tap) is recommended: +On macOS, installing via Homebrew is recommended: ```bash brew install --cask maguowei/tap/code-manager ``` -Or go to [Releases](https://github.com/maguowei/code-manager/releases) to download the installer for your platform. +Alternatively, download the installer for your platform from [Releases](https://github.com/maguowei/code-manager/releases): | Platform | Installer | | --- | --- | @@ -57,36 +59,41 @@ Or go to [Releases](https://github.com/maguowei/code-manager/releases) to downlo | Windows | `.msi` / `.exe` | | Linux | `.deb` / `.rpm` / `.AppImage` | -The current macOS release packages are not notarized by Apple. Homebrew installs automatically remove the quarantine attribute; if you manually download the `.dmg` and the first launch is blocked by the system, run the following in a terminal: - -```bash -xattr -rd com.apple.quarantine /Applications/code-manager.app -``` +> [!TIP] +> Current macOS releases are not notarized by Apple. Homebrew installations automatically clear quarantine attributes. If you manually download the `.dmg` and the first launch is blocked by Gatekeeper, run: +> ```bash +> xattr -rd com.apple.quarantine /Applications/code-manager.app +> ``` ### Nightly Builds -Want to try the latest features before they are released? Nightly installers for macOS (`dmg`), Linux (`deb` / `AppImage`), and Windows (`setup.exe`) are built automatically on every `main` merge and published as a rolling prerelease at [releases/download/nightly](https://github.com/maguowei/code-manager/releases/download/nightly). The version includes the commit short SHA (e.g. `1.6.0-nightly.ga1b2c3d`) so you can tell exactly which build you have. +Want to test the latest features before an official release? Nightly builds for macOS (`.dmg`), Linux (`.deb` / `.AppImage`), and Windows (`setup.exe`) are generated on every merge to `main` and published at [releases/download/nightly](https://github.com/maguowei/code-manager/releases/download/nightly). Versions include the commit short SHA (e.g. `1.6.0-nightly.ga1b2c3d`) for precise tracking. -Nightly builds are **not signed or notarized**: macOS will block the first launch (right-click → Open, or `xattr -rd com.apple.quarantine /Applications/code-manager.app`), and Windows may show a SmartScreen warning. Nightly builds roll forward on each merge (older ones are overwritten) and do **not** self-update — install a stable release to get automatic updates. +Nightly builds are **not signed or notarized**: +- **macOS**: Right-click → Open, or run `xattr -rd com.apple.quarantine /Applications/code-manager.app`. +- **Windows**: Windows SmartScreen may display an unrecognized app notice. +- **Updates**: Nightly releases roll forward on each merge and do **not** self-update. Install a stable release for automatic update support. ### Automatic Updates -The app has built-in automatic updates: it silently checks for new versions on startup, and once one is found you can download and install it with one click in "Settings - App Update", after which it restarts automatically. Users who installed via Homebrew can also keep upgrading with `brew upgrade`; both paths work, and after an in-app update the version Homebrew records will automatically align on the next `brew upgrade`. +The app includes built-in update checks on launch: +- When an update is detected, download and install with one click under **Settings → App Update**, followed by an automatic restart. +- Homebrew users can continue using `brew upgrade`; in-app updates automatically align with Homebrew on the next upgrade. ## Quick Start -1. After launch, Code Manager reads your local `~/.claude`, `~/.claude.json`, and `~/.claude/projects/`. -2. In settings, choose the interface language, theme, default terminal, and default editor. -3. On the profiles page, import an existing `~/.claude/settings.json`, or create a new profile, pick a built-in provider in the "Provider" option, and fill in the auth secret and model configuration. -4. Click "Test Model" to confirm the configuration works. -5. Click enable to apply the profile to `~/.claude/settings.json`. -6. Go to the `~/.claude` overview to confirm the final configuration is as expected. +1. **Auto-Discovery**: On launch, Code Manager reads your local `~/.claude`, `~/.claude.json`, and `~/.claude/projects/`. +2. **General Preferences**: In **Settings**, choose your preferred interface language, theme, default terminal, and editor. +3. **Configure Profile**: On the **Profiles** page, import an existing `~/.claude/settings.json` or create a new profile. Choose a built-in provider, then enter your API credentials and model configuration. +4. **Test Connectivity**: Click **Test Model** to verify API communication. +5. **Apply Configuration**: Click **Enable** to write the active profile safely into `~/.claude/settings.json`. +6. **Verify Overview**: Switch to the **`~/.claude` Overview** page to confirm the updated directory and configuration state. -For more detailed page descriptions, cost accounting rules, common workflows, and FAQ, see [docs/user-manual.md](./docs/user-manual.md). +For detailed page descriptions, cost calculation rules, common workflows, and FAQ, see [docs/user-manual.md](./docs/user-manual.md). ## Local Data and Privacy -Code Manager mainly reads and writes local files. Profile merging, directory scanning, usage aggregation, and log viewing all happen locally; model pricing prefers the local cache and built-in fallback data, and attempts to refresh from official models.dev providers after startup. +Code Manager operates primarily on your local file system. Profile merging, directory scanning, token usage calculation, and log inspection run entirely offline on your machine. Model pricing prefers the local cache and built-in fallbacks, attempting to refresh from official models.dev providers after startup. | Purpose | macOS | Linux | Windows | | --- | --- | --- | --- | @@ -94,7 +101,7 @@ Code Manager mainly reads and writes local files. Profile merging, directory sca | Usage SQLite | `~/Library/Application Support/com.gotobeta.app.code-manager/usage.db` | `$XDG_CONFIG_HOME/com.gotobeta.app.code-manager/usage.db` or `~/.config/com.gotobeta.app.code-manager/usage.db` | `%APPDATA%\com.gotobeta.app.code-manager\usage.db` | | Log directory | `~/Library/Logs/com.gotobeta.app.code-manager/` | `$XDG_DATA_HOME/com.gotobeta.app.code-manager/logs/` or `~/.local/share/com.gotobeta.app.code-manager/logs/` | `%LOCALAPPDATA%\com.gotobeta.app.code-manager\logs\` | -The application data directory contains `config-registry.json`, `memories.json`, `model-pricing.json`, and `skills-disabled/`. On macOS, application data deliberately reuses `~/.config/code-manager/` for easier cross-platform backup and script access. +The application data directory contains `config-registry.json`, `memories.json`, `model-pricing.json`, and `skills-disabled/`. On macOS, application data deliberately uses `~/.config/code-manager/` for easier cross-platform backup and scripting access. ## Local Development @@ -105,28 +112,33 @@ Stack overview: Tauri 2 + React 19 + TypeScript + Vite + Tailwind CSS v4 + Rust. ### Prerequisites - Node.js LTS -- `pnpm`, the project currently declares `pnpm@12.4.2` +- `pnpm` (the project currently declares `pnpm@12.4.2`) - Rust stable -- The system dependencies required to run Tauri 2 +- System dependencies required to run Tauri 2 ### Common Commands ```bash -make init # Install dependencies and check the Rust toolchain +# --- Development & Build --- +make init # Install dependencies and verify Rust toolchain make dev # Start Tauri desktop dev mode -make build # Build the installer for the current platform -make build-frontend # TypeScript check and build the frontend +make build # Build production installer for current platform +make build-frontend # TypeScript check and build frontend + +# --- Verification & Testing --- +make verify # Comprehensive local verification (runs before push) +make lint # Biome (frontend) + Clippy (Rust) static checks +make test # Run all tests (Rust backend + frontend Vitest) +make check # Quick Rust compiler check (cargo check) +make fmt-check # Read-only formatting check (frontend + Rust) +make lint-frontend # Frontend-only static check +make test-frontend # Run frontend test suite + +# --- Contracts & Security --- make bindings # Regenerate Tauri IPC TypeScript bindings -make bindings-check # Check that Rust command contracts and src/bindings.ts are in sync -make lint # Frontend Biome + Rust clippy -make test # Rust tests + frontend tests -make check # Rust cargo check -make fmt-check # Read-only format check for frontend + Rust -make verify # Local CI-like verification entry point -make gitleaks # Scan current project files for secrets +make bindings-check # Verify Rust command signatures match src/bindings.ts +make gitleaks # Scan working tree for secrets make gitleaks-history # Scan Git history for secrets -make lint-frontend # Read-only static check for the frontend -make test-frontend # Run frontend tests ``` `pnpm install` triggers the `prepare` script and installs lefthook git hooks. Before a commit it runs staged Biome auto-fix, Gitleaks secret scanning, Rust format check, and commitlint; before a branch push it runs `make verify`; tag-only pushes are gated remotely by the release workflow's quality job. `make fmt` and `pnpm check` rewrite files; for read-only checks use `make lint`, `make lint-frontend`, or `make fmt-check`. @@ -137,25 +149,25 @@ Build artifacts are located by default in `src-tauri/target/release/bundle/`. - `src/`: React frontend pages, components, hooks, schemas, and tests. - `src-tauri/`: Rust backend, Tauri commands, built-in resources, and permission declarations. -- `docs/`: user manual, platform differences, and extended documentation. +- `docs/`: User manual, platform differences, and extended documentation. For fine-grained component entry points, module responsibilities, and path navigation for AI agents, see [CLAUDE.md](./CLAUDE.md). ## Contributing and Feedback -When filing an issue, please include as much as possible: +When filing an issue, please include: - Operating system, Code Manager version, and Claude Code use case - Reproduction steps, expected result, and actual result -- Relevant redacted log snippets from "Settings -> Diagnostics -> View Logs" -- For development changes, the verification commands you have run +- Relevant redacted log snippets from **Settings → Diagnostics → View Logs** +- For development changes, verification commands you have run and test results ## Further Reading -- [docs/user-manual.md](./docs/user-manual.md): the complete user manual -- [docs/platform-support.md](./docs/platform-support.md): platform support differences -- [CLAUDE.md](./CLAUDE.md): the repository execution manual for AI agents -- [LICENSE](./LICENSE): license +- [docs/user-manual.md](./docs/user-manual.md): Comprehensive user manual +- [docs/platform-support.md](./docs/platform-support.md): Platform support differences +- [CLAUDE.md](./CLAUDE.md): Repository execution manual for AI agents +- [LICENSE](./LICENSE): MIT License ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index cec3744..6cf8aaa 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -4,24 +4,26 @@ [![CI](https://github.com/maguowei/code-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/maguowei/code-manager/actions/workflows/ci.yml) [![Release](https://github.com/maguowei/code-manager/actions/workflows/release.yml/badge.svg)](https://github.com/maguowei/code-manager/actions/workflows/release.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) ![Code Manager 配置编辑界面](docs/assets/readme-hero.zh-CN.webp) -Code Manager 是面向 Claude Code 用户的本地桌面管理应用。它把配置、供应商、`~/.claude` 目录、记忆、Skills、历史、统计、Token 用量、项目状态、系统托盘和诊断日志集中到一个 Tauri 2 应用里，让本地配置更可见、可预览、可验证。 +**Code Manager** 是面向 Claude Code 用户的跨平台本地桌面管理应用，基于 Tauri 2 构建。它将配置、供应商、`~/.claude` 目录、记忆、Skills、会话历史、Token 用量、项目状态、系统托盘和诊断日志集中到统一界面中，让本地配置更可见、可预览、可验证。 -本文件面向人类用户和项目访问者。AI Agent 的执行规则见 [CLAUDE.md](./CLAUDE.md)，完整使用说明见 [docs/user-manual.zh-CN.md](./docs/user-manual.zh-CN.md)，平台差异见 [docs/platform-support.zh-CN.md](./docs/platform-support.zh-CN.md)。 +> [!NOTE] +> 本文件面向人类用户和项目访问者。AI Agent 的执行规则见 [CLAUDE.md](./CLAUDE.md)，完整使用说明见 [docs/user-manual.zh-CN.md](./docs/user-manual.zh-CN.md)，平台差异见 [docs/platform-support.zh-CN.md](./docs/platform-support.zh-CN.md)。 ## 解决的问题 -长期使用 Claude Code 时，本地配置和会话数据容易散落在多个文件里： +在长期与多项目中使用 Claude Code 时，本地配置和会话数据容易散落在多个文件中： -- 不同项目需要不同模型、API 地址、Token、权限、Hooks 和插件组合。 -- `~/.claude/settings.json`、`CLAUDE.md`、`rules/*.md` 与 Skills 不容易整体检查。 -- Provider / model 配置重复，切换配置时容易漏写环境变量或覆盖用户设置。 -- 历史记录、统计、Token 花费、项目 Git 状态和 worktree 信息缺少统一入口。 -- 排障时需要快速查看脱敏后的应用日志，而不是到处找日志文件。 +- **配置碎片化**：不同项目往往需要不同的模型、API 地址、Token、权限、Hooks 和插件组合。 +- **状态不透明**：`~/.claude/settings.json`、`CLAUDE.md`、`rules/*.md` 与 Skills 缺乏全局审查视角。 +- **配置摩擦大**：切换 Provider 或模型操作繁琐，容易漏填环境变量或意外覆盖已有配置。 +- **数据无聚合**：历史记录、统计数据、Token 花费、项目 Git 状态与 worktree 信息缺少统一看板。 +- **排障路径长**：遇到问题时需要四处定位系统日志文件，难以快速获取已脱敏的应用诊断信息。 -Code Manager 不替代 Claude Code，而是提供一个本机配置、会话数据和诊断信息的管理层。 +Code Manager 并不替代 Claude Code，而是为其提供一个专注本地配置、会话数据与诊断信息的管控层。 ## 核心能力 @@ -29,64 +31,69 @@ Code Manager 不替代 Claude Code，而是提供一个本机配置、会话数 | 能力 | 说明 | | --- | --- | -| `~/.claude` 总览 | 浏览、预览、编辑和定位 Claude Code 用户目录。 | -| 配置 / 内置供应商 | 管理最终写入 `~/.claude/settings.json` 的配置层，从内置供应商（只读）选择连接地址与模型映射。可编辑模型、环境变量、权限、Sandbox、Hooks、插件与状态行；支持预览、复制、模型测试、一键应用、导入 / 导出（可选含密钥、落盘前预览）、差异对比，以及把常用选项 / 市场 / 插件一键同步到其他配置。 | -| 记忆管理 | 管理用户级 `CLAUDE.md` 与 `rules/*.md`，支持 Karpathy 行为指南预设、导入、启用、禁用、复制、预览和路径校验。 | -| Skills 管理 | 新建、编辑、删除、启用、禁用 Claude Code Skills，并可同步为 `~/.codex/skills/` 软链接。 | -| 历史与会话 | 读取 `~/.claude/history.jsonl`，按项目和会话查看历史详情。 | -| 统计与最近会话 | 从 `~/.claude.json` 读取本地统计快照。 | -| Token 用量与费用 | 扫描 `~/.claude/projects/**/*.jsonl`，按日期、项目、会话和模型聚合 Token 与费用，并使用 SQLite 增量缓存。 | -| 项目管理 | 展示项目路径、远程地址、分支、worktree、项目级 `.claude/`、`AGENTS.md` / `CLAUDE.md` 与 `.agents/skills` 状态，支持打开终端/编辑器、跳转历史/用量、分支与 worktree 清理和清理本地项目数据。 | -| 系统托盘与会话聚焦 | 菜单栏显示当前配置和 Claude Code 活跃会话，支持会话计数样式与待处理呼吸灯，在支持的平台尝试聚焦已有终端会话，并可（仅 macOS）把会话状态镜像到 ANTICATER USB 设备灯效。 | -| 桌面用量浮窗 | 置顶半透明小窗，实时展示今日 Token 花费、用量与缓存命中等指标，支持拖拽、自定义展示指标与不透明度，可在设置中开关。 | -| 设置与诊断 | 支持语言、主题、默认收起侧边栏、菜单栏会话显示、系统通知、第三方模型计价、登录启动、默认终端和编辑器、会话聚焦快捷键与 LED 灯效（仅 macOS）、桌面用量浮窗开关与指标自定义、脱敏日志查看、系统信息复制和日志轮转。 | +| **`~/.claude` 总览** | 集中浏览、预览、编辑与快速定位 Claude Code 用户目录下的关键文件。 | +| **配置 / 内置供应商** | 管理最终写入 `~/.claude/settings.json` 的配置层。从内置供应商（只读）快速选择连接地址与模型映射；可视化配置模型、环境变量、权限、Sandbox、Hooks、插件与状态行；支持连通性测试、落盘前 Diff 对比、安全导入/导出（密钥脱敏可选）以及跨 Profile 一键同步。 | +| **记忆管理** | 集中管理用户级 `CLAUDE.md` 与 `rules/*.md` 文件并执行路径校验；内置 Karpathy 行为指南预设，支持一键启用/禁用、复制与实时预览。 | +| **Skills 管理** | 创建、编辑、删除、启用与禁用 Claude Code Skills，并自动同步为 `~/.codex/skills/` 软链接。 | +| **历史与会话** | 解析 `~/.claude/history.jsonl`，按项目与会话维度探索会话时间线、输入提示与历史详情。 | +| **统计与概览** | 从 `~/.claude.json` 读取本地统计快照，跟踪会话活跃度与最近会话。 | +| **Token 用量与费用** | 基于 SQLite 增量扫描 `~/.claude/projects/**/*.jsonl`，按日期、项目、会话与模型多维度聚合 Token 用量与成本支出。 | +| **项目管理** | 跟踪项目路径、Git 远程分支、worktree、项目级 `.claude/`、规则（`AGENTS.md` / `CLAUDE.md`）与 Skills 状态；支持一键唤起终端或编辑器。 | +| **系统托盘与终端聚焦** | 在菜单栏实时展示当前活跃会话与待处理呼吸灯；支持通过快捷键尝试聚焦已有终端会话，并可将状态镜像至 ANTICATER USB 硬件灯效（仅 macOS）。 | +| **桌面用量浮窗** | 置顶半透明桌面小窗，实时展示今日 Token 花费、用量与缓存命中率；支持拖拽吸附与展示指标自定义。 | +| **设置与诊断** | 支持界面语言、主题风格、默认终端/编辑器、模型自定义计价与开机自启；内置日志查看器（自动脱敏密钥）并支持一键导出系统诊断信息。 | ## 下载安装 -macOS 推荐用 Homebrew 安装（自有 tap）： +macOS 推荐使用 Homebrew 安装（自有 tap）： ```bash brew install --cask maguowei/tap/code-manager ``` -或前往 [Releases](https://github.com/maguowei/code-manager/releases) 下载对应平台的安装包。 +或前往 [Releases](https://github.com/maguowei/code-manager/releases) 下载对应平台的安装包： | 平台 | 安装包 | | --- | --- | -| macOS (Apple Silicon / Intel) | `.dmg`（或 `brew install --cask maguowei/tap/code-manager`） | +| macOS（Apple Silicon / Intel） | `.dmg`（或使用 Homebrew 安装） | | Windows | `.msi` / `.exe` | | Linux | `.deb` / `.rpm` / `.AppImage` | -macOS 当前发布包未经过 Apple 公证。Homebrew 安装会自动移除隔离属性；若手动下载 `.dmg` 后首次打开被系统拦截，可在终端执行： +> [!TIP] +> macOS 当前发布包未经过 Apple 公证。Homebrew 安装会自动移除隔离属性；若手动下载 `.dmg` 后首次打开被 Gatekeeper 拦截，可在终端执行： +> ```bash +> xattr -rd com.apple.quarantine /Applications/code-manager.app +> ``` -```bash -xattr -rd com.apple.quarantine /Applications/code-manager.app -``` - -### 每夜构建(Nightly) +### 每夜构建（Nightly） -想提前体验尚未发布的新功能？每次 `main` 合并后会自动构建 macOS(`dmg`)、Linux(`deb`/`AppImage`)、Windows(`setup.exe`) 的每夜构建安装包,以滚动预发布形式发布在 [releases/download/nightly](https://github.com/maguowei/code-manager/releases/download/nightly)。版本号含 commit 短 sha(如 `1.6.0-nightly.ga1b2c3d`),可精确定位你正在使用哪次构建。 +想提前体验尚未发布的最新功能？每次 `main` 分支合并后都会自动构建适用于 macOS（`.dmg`）、Linux（`.deb` / `.AppImage`）和 Windows（`setup.exe`）的每夜构建包，以滚动预发布形式发布在 [releases/download/nightly](https://github.com/maguowei/code-manager/releases/download/nightly)。版本号包含 commit 短 SHA（如 `1.6.0-nightly.ga1b2c3d`），方便精确定位构建版本。 -每夜构建**未签名/未公证**:macOS 首次打开会被拦截(右键 → 打开,或 `xattr -rd com.apple.quarantine /Applications/code-manager.app`),Windows 可能触发 SmartScreen 提示。每夜构建随每次合并向前滚动(旧构建被覆盖),并且**不参与自更新** —— 需要自动更新请安装正式版。 +每夜构建**未签名与未公证**： +- **macOS**：首次打开会被系统拦截（右键 → 打开，或运行上述命令清除隔离属性）。 +- **Windows**：可能触发 SmartScreen 未知应用提示。 +- **更新说明**：每夜构建随每次合并向前滚动覆盖，且**不参与应用内自更新**；如需自动更新请安装正式版本。 ### 自动更新 -应用内置自动更新：启动时会静默检查新版本，发现后在「设置 - 应用更新」中可一键下载并安装，安装完成后自动重启。通过 Homebrew 安装的用户也可继续用 `brew upgrade` 升级；两种方式都可用，应用内更新后 Homebrew 记录的版本号会在下次 `brew upgrade` 时自动对齐。 +应用内置启动检查更新机制： +- 启动时静默检查新版本，发现后可在「设置 → 应用更新」中一键下载并安装，安装后自动重启。 +- 通过 Homebrew 安装的用户可继续使用 `brew upgrade` 升级；应用内更新后，Homebrew 记录的版本会在下一次升级时自动对齐。 ## 快速使用 -1. 启动应用后，Code Manager 会读取本机 `~/.claude`、`~/.claude.json` 和 `~/.claude/projects/`。 -2. 在设置中选择界面语言、主题、默认终端和默认编辑器。 -3. 在配置页导入现有 `~/.claude/settings.json`，或新建配置，在「供应商」选项处选择内置供应商并填写认证密钥与模型配置。 -4. 点击“测试模型”确认配置可用。 -5. 点击启用，将配置应用到 `~/.claude/settings.json`。 -6. 到 `~/.claude` 总览确认最终配置符合预期。 +1. **环境发现**：启动应用后，Code Manager 会自动读取本机 `~/.claude`、`~/.claude.json` 和 `~/.claude/projects/`。 +2. **基础偏好**：在「设置」中选择界面语言、外观主题、默认终端与默认编辑器。 +3. **配置 Profile**：在「配置」页导入现有的 `~/.claude/settings.json`，或新建配置、从下拉列表中选择内置供应商，并填入 API 密钥与模型参数。 +4. **验证连通性**：点击“测试模型”确认接口通信与模型可用。 +5. **一键应用生效**：点击“启用”，将当前配置安全写入 `~/.claude/settings.json`。 +6. **总览核对**：前往「`~/.claude` 总览」页面，确认最终生成的配置与目录结构符合预期。 更完整的页面说明、费用统计口径、常见工作流和 FAQ 见 [docs/user-manual.zh-CN.md](./docs/user-manual.zh-CN.md)。 ## 本地数据与隐私 -Code Manager 主要读写本机文件。配置合并、目录扫描、用量聚合和日志查看都在本地完成；模型价格会优先使用本地缓存和内置兜底数据，并在启动后尝试从 models.dev 官方 provider 刷新。 +Code Manager 主要读写本机文件。配置合并、目录扫描、用量聚合和日志查看都在本地离线完成；模型价格优先使用本地缓存和内置兜底数据，并在启动后尝试从 models.dev 官方接口刷新。 | 用途 | macOS | Linux | Windows | | --- | --- | --- | --- | @@ -105,28 +112,33 @@ Code Manager 主要读写本机文件。配置合并、目录扫描、用量聚 ### 前置要求 - Node.js LTS -- `pnpm`，项目当前声明 `pnpm@12.4.2` +- `pnpm`（项目当前声明 `pnpm@12.4.2`） - Rust stable - 满足 Tauri 2 运行所需的系统依赖 ### 常用命令 ```bash +# --- 开发与构建 --- make init # 安装依赖并检查 Rust 工具链 make dev # 启动 Tauri 桌面开发模式 -make build # 构建当前平台安装包 -make build-frontend # TypeScript 检查并构建前端 +make build # 构建当前平台生产安装包 +make build-frontend # 前端类型检查与构建 + +# --- 验证与测试 --- +make verify # 本地完整门禁（模拟 CI 校验，分支推送前执行） +make lint # 前端 Biome + Rust Clippy 静态检查 +make test # 运行全部测试（Rust 后端 + 前端 Vitest） +make check # Rust 快速编译检查（cargo check） +make fmt-check # 前端与 Rust 只读格式检查 +make lint-frontend # 前端专属静态检查 +make test-frontend # 运行前端测试套件 + +# --- 契约与安全 --- make bindings # 重新生成 Tauri IPC TypeScript bindings -make bindings-check # 检查 Rust command 契约与 src/bindings.ts 是否同步 -make lint # 前端 Biome + Rust clippy -make test # Rust 测试 + 前端测试 -make check # Rust cargo check -make fmt-check # 前端 + Rust 只读格式检查 -make verify # 本地 CI-like 验证入口 -make gitleaks # 扫描当前项目文件中的密钥 -make gitleaks-history # 扫描 Git 历史中的密钥 -make lint-frontend # 前端只读静态检查 -make test-frontend # 运行前端测试 +make bindings-check # 检查 Rust command 契约与 src/bindings.ts 是否一致 +make gitleaks # 扫描当前工作区文件中的密钥 +make gitleaks-history # 扫描 Git 提交历史中的密钥 ``` `pnpm install` 会触发 `prepare` 脚本并安装 lefthook git hooks。提交前会运行 staged Biome 自动修复、Gitleaks 密钥扫描、Rust 格式检查与 commitlint，分支推送前会运行 `make verify`；tag-only push 由 release workflow 的 quality job 执行远端门禁。`make fmt` 与 `pnpm check` 会改写文件；只想做只读检查时使用 `make lint`、`make lint-frontend` 或 `make fmt-check`。 @@ -143,19 +155,19 @@ make test-frontend # 运行前端测试 ## 贡献与反馈 -提交问题时，请尽量附上： +提交 Issue 时，请尽量附上以下信息： -- 操作系统、Code Manager 版本和 Claude Code 使用场景 -- 复现步骤、期望结果和实际结果 -- “设置 -> 诊断 -> 查看日志”中相关的脱敏日志片段 -- 如果是开发改动，请说明已运行的验证命令 +- 操作系统环境、Code Manager 版本与 Claude Code 使用场景 +- 清晰的复现步骤、预期表现与实际结果 +- 「设置 → 诊断 → 查看日志」中相关的脱敏日志片段 +- 提交代码改动时，请说明已运行的验证命令及测试结果 ## 进一步阅读 - [docs/user-manual.zh-CN.md](./docs/user-manual.zh-CN.md)：完整用户说明书 - [docs/platform-support.zh-CN.md](./docs/platform-support.zh-CN.md)：平台支持差异 - [CLAUDE.md](./CLAUDE.md)：面向 AI Agent 的仓库执行手册 -- [LICENSE](./LICENSE)：许可证 +- [LICENSE](./LICENSE)：MIT 许可证 ## License From d200da33e0d928c41430d08792bc9d8ef6ceadd2 Mon Sep 17 00:00:00 2001 From: maguowei Date: Sat, 10 Oct 2026 22:13:34 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs(manual):=20=E4=BC=98=E5=8C=96=E4=B8=AD?= =?UTF-8?q?=E8=8B=B1=E6=96=87=E7=94=A8=E6=88=B7=E6=89=8B=E5=86=8C=E6=8E=92?= =?UTF-8?q?=E7=89=88=E4=B8=8E=E5=8F=AF=E8=AF=BB=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/user-manual.md | 462 ++++++++++++++++++++----------------- docs/user-manual.zh-CN.md | 467 +++++++++++++++++++++----------------- 2 files changed, 513 insertions(+), 416 deletions(-) diff --git a/docs/user-manual.md b/docs/user-manual.md index 65a91fd..c811bc7 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -2,7 +2,8 @@ [English](./user-manual.md) | [中文](./user-manual.zh-CN.md) -> This document is intended for end users. The execution handbook for coding agents such as Claude Code / Codex is in `CLAUDE.md` at the repository root. +> [!NOTE] +> This document is intended for end users. The execution handbook for coding agents such as Claude Code / Codex is in [CLAUDE.md](../CLAUDE.md) at the repository root. Code Manager is a local desktop management tool for Claude Code users. It brings the `~/.claude` directory, configurations, providers, memories, Skills, history, statistics, token usage, project status, the system tray, and diagnostic logs together into a single Tauri application, helping you maintain your local Claude Code configuration in a more visible, previewable, and verifiable way. @@ -32,327 +33,365 @@ Code Manager is a local desktop management tool for Claude Code users. It brings ### Configuration -A configuration is the user settings that can ultimately be applied to `~/.claude/settings.json`. It typically includes fields such as authentication keys, the API endpoint, the default model, permissions, Sandbox, Hooks, plugins, and the status line. A configuration can reference a built-in provider; when the configuration is applied, Code Manager merges the provider's `env` (endpoint and model mapping) with the configuration's own settings, generates the final JSON, and writes it to `~/.claude/settings.json`. +A configuration is the set of user preferences that can be applied to `~/.claude/settings.json`. It includes authentication keys, API endpoints, default models, permissions, Sandbox settings, Hooks, plugins, and the status line. -If `~/.claude/settings.json` already exists on this machine, the Configurations page can detect it when no configuration has been created yet and import it as a managed configuration. After a configuration has been applied, if the real `settings.json` is modified externally, the page shows a difference notice; you can review the diff and then choose to accept the actual settings or re-apply the managed configuration. +- **Provider Integration**: A configuration can reference a built-in provider. When applied, Code Manager merges the provider's preset environment variables (endpoints and model mappings) with the configuration's own settings, generates standard JSON, and writes it safely to `~/.claude/settings.json`. +- **Automatic Takeover**: If `~/.claude/settings.json` already exists on your machine and no configurations have been created yet, Code Manager detects it and offers to import it as a managed profile in place. +- **External Change Detection**: When the active configuration differs from the actual file on disk (e.g. modified by an external editor), a difference notice appears. You can review the diff and choose to either **Accept actual settings** or **Re-apply** your managed configuration. ### Provider -A provider carries only objective provider information (connection endpoint, model mapping, and optional additional environment variables). It contains no authentication keys and is built-in and read-only, with no custom providers. After a configuration references a provider, fields with the same name in the configuration override the provider's `env` (except the endpoint: the endpoint uses the provider as the single source of truth). See the [Providers](#providers) section for the full built-in list. +A provider carries objective endpoint information (API URL, official model mappings, and optional environment variables). It contains no private authentication keys and is built-in and read-only. + +- **Override Rules**: When a configuration references a provider, matching keys in the configuration override the provider's `env` (except for the API endpoint: the provider's endpoint remains the single source of truth). +- See the [Providers](#providers) section for the complete list of built-in providers. ### Memory -Memories correspond to the Claude Code user-level `CLAUDE.md` and `~/.claude/rules/*.md`. When enabled, they are written to the real Claude Code directory. +Memories correspond to Claude Code's user-level system instruction files: `~/.claude/CLAUDE.md` and `~/.claude/rules/*.md`. Files are only written to disk once enabled in the UI. -- `CLAUDE.md`: only one can be enabled at a time, suitable as a long-term primary memory. -- Rules: multiple can be enabled at the same time, saved to `~/.claude/rules/`, and can use the `paths` frontmatter for path matching. +- **`CLAUDE.md`**: The primary memory file. Only one can be active at a time, making it ideal as a long-term baseline instruction set. +- **Rules**: Modular rule files located in `~/.claude/rules/`. Multiple rules can be active simultaneously and support `paths` glob frontmatter for targeted file matching. ### Skills -Skills correspond to `~/.claude/skills//SKILL.md`. Enabled Skills are stored in `~/.claude/skills/`; disabled Skills are moved to Code Manager's `skills-disabled/` directory. Symlinked Skills can be imported and toggled on or off, but their content is read-only and must be maintained in the source directory. +Skills correspond to Claude Code custom capabilities located under `~/.claude/skills//SKILL.md`. + +- **Enable / Disable**: Active skills reside in `~/.claude/skills/`. Disabled skills are safely moved to `skills-disabled/` in the application data directory to keep your Claude workspace clean. +- **Symlinked Skills**: Symlinked skills can be imported and toggled on or off. However, because their source files reside outside the managed directory, their content is read-only and must be edited in their original location. ### The Difference Between Stats and Usage -- The Usage Statistics page reads `~/.claude.json` and shows the local Claude Code statistics snapshot (startup count, tool calls, Skill usage, the most recent session per project). -- The Token Usage page scans `~/.claude/projects/**/*.jsonl` and `subagents/*.jsonl`, aggregates tokens and cost by date, project, session, and model, and uses SQLite for incremental caching. +These two pages serve different purposes and draw from different data sources: + +- **Usage Statistics (Stats)**: Reads the local snapshot from `~/.claude.json`, showing aggregate launch counts, tool calls, skill invocation numbers, and the most recent session summary per project. +- **Token Usage Statistics (Usage)**: Performs an incremental scan of `~/.claude/projects/**/*.jsonl` and `subagents/*.jsonl` log files, computing token counts and costs across dates, projects, sessions, and models via an embedded SQLite cache. -The two have different data sources and metrics. When investigating cost or tokens, prefer the Token Usage page. +> [!TIP] +> Always use the **Token Usage Statistics** page when auditing actual token expenditure and accurate cost breakdowns. ## Quick Start -1. Download the installer for your platform from the project Release page, then install and launch it. -2. After the first launch, the application reads the local `~/.claude`, `~/.claude.json`, and `~/.claude/projects/`. -3. On macOS, if the first launch is blocked by the system, run `xattr -rd com.apple.quarantine /Applications/code-manager.app` to remove the quarantine attribute. +1. **Download and Install**: Download the installer for your operating system from the GitHub Releases page, install, and open the app. +2. **Initial Detection**: On launch, Code Manager automatically inspects existing local `~/.claude`, `~/.claude.json`, and `~/.claude/projects/` paths. +3. **macOS Quarantine Bypass (if needed)**: If Gatekeeper blocks the app on first launch, run: + ```bash + xattr -rd com.apple.quarantine /Applications/code-manager.app + ``` -Recommended order for the first setup: +Recommended initial setup order: -1. Open Settings in the lower-left corner and choose the interface language, theme, default terminal, and default editor. -2. Go to the Configurations page, create a configuration, and select a suitable built-in provider under the "Provider" option. -3. Fill in the authentication key and model configuration. -4. Click Test Model to confirm that the API endpoint, token, and model are available. -5. Click Enable to apply the configuration to `~/.claude/settings.json`. -6. Open the Directory Overview to confirm that the write to `settings.json` matches your expectations. +1. **General Preferences**: Open Settings (lower-left corner) to configure your preferred interface language, theme, default terminal, and editor. +2. **Create a Profile**: Go to Configurations and click **New Configuration**. Select a matching provider from the **Provider** dropdown. +3. **Fill Credentials**: Enter your API key and verify default model options. +4. **Test Connectivity**: Click **Test Model** to verify that endpoints, keys, and model mappings communicate properly. +5. **Apply Configuration**: Click **Enable** to apply the configuration directly to `~/.claude/settings.json`. +6. **Verify Overview**: Open the **`~/.claude` Directory Overview** to confirm the generated files and settings. ## Main Navigation | Entry | Purpose | | --- | --- | -| `AI` | Open or collapse the `~/.claude` Directory Overview | -| Configurations | Manage configurations, generate and apply Claude Code user settings | -| Memory | Manage `CLAUDE.md` and `rules/*.md` | -| Skills | Manage Claude Code Skills | -| Projects | View Claude project paths, Git status, worktrees, project-level `.claude/`, and AGENTS / Skills pairing status | -| History | View historical inputs and session details in `~/.claude/history.jsonl` | -| Stats | View the local statistics snapshot in `~/.claude.json` | -| Usage | View the token and cost aggregation in `~/.claude/projects/` | -| Cheat Sheet | Entry at the bottom of the sidebar; quick reference for Claude Code shortcuts, slash commands, settings, and environment variables | -| Settings | Adjust language, theme, tray, default terminal, default editor, and diagnostic entries | - -On most pages, the add or edit action opens a drawer on the right that supports control mode, JSON mode, or preview. When the configuration, memory, or Skill editor has unsaved changes, closing or switching prompts you to save, discard, or continue editing. +| `AI` | Toggle the `~/.claude` directory tree overview and file preview workspace | +| **Configurations** | Manage configuration profiles; generate and apply Claude Code user settings | +| **Memory** | Manage user-level `CLAUDE.md` and modular `rules/*.md` files | +| **Skills** | Create, edit, toggle, and organize Claude Code Skills | +| **Projects** | View Claude projects, Git branch/worktree status, project-level `.claude/`, and rule pairings | +| **History** | Explore historical prompts, commands, and session replays from `~/.claude/history.jsonl` | +| **Stats** | Inspect local aggregate activity snapshots from `~/.claude.json` | +| **Usage** | Scan session logs in `~/.claude/projects/` to analyze token usage and cost metrics | +| **Cheat Sheet** | Located at the bottom of the sidebar; quick reference for shortcuts, slash commands, and flags | +| **Settings** | Configure app preferences, tray behavior, default tools, and diagnostics | + +On most pages, adding or editing opens a dedicated right-side drawer supporting form controls, JSON mode, and live preview. When an editor has unsaved changes, closing the drawer or switching pages triggers an exit guard dialog to prevent accidental data loss. ## `~/.claude` Directory Overview -Click the `AI` entry in the upper-left corner to open it. After you select a file in the directory tree on the right, the preview area on the left opens a tab: Markdown shows the rendered preview by default (you can switch to source), other text files show their source, and binary files show only metadata. The bottom of the preview shows file size, modification time, encoding, and truncation status. +Click the `AI` badge in the upper-left corner to access the directory overview: -The file preview toolbar lets you copy the absolute path, reveal it in the file browser, and open it with the default editor; right-clicking in the directory tree lets you create a new file, create a new folder, rename, or delete. Deletion cannot be undone, so make sure you have a copy before handling `settings.json`, `CLAUDE.md`, `rules/`, or `skills/`. - -The Directory Overview lists paths under `~/.claude` (including symlinks). Symlink entries are labeled and can be opened read-only—directory symlinks expand, and file previews may follow targets outside `~/.claude`. Create, rename, and delete stay disabled on any path that crosses a symlink. The scan still skips `node_modules`, and shows a notice when the entry count or depth limit is reached. Binary preview uses a known-extension denylist; other files open as UTF-8 / lossy text. +- **File Browsing & Preview**: Selecting any file in the tree opens a preview tab. Markdown files display rich formatting (with a raw source toggle), source code files render with syntax highlighting, and binary files display metadata. File size, modification time, encoding, and truncation status remain visible at the bottom. +- **Toolbar & Actions**: Copy absolute paths, reveal files in your system file manager, or open them in your default code editor. Right-click any tree item to create files, create folders, rename, or delete. + > [!WARNING] + > File deletions cannot be undone. Always verify backups before modifying or deleting `settings.json`, `CLAUDE.md`, `rules/`, or `skills/`. +- **Symlink Protection**: Symlinks are visually tagged and open in read-only mode. To prevent accidental modification of external workspaces, create, rename, and delete actions are strictly disabled on any path traversing a symlink. Scans ignore `node_modules` and warn if file count or depth limits are reached. ## Configurations -The Configurations page is the main entry point for managing Claude Code settings. +The Configurations page is your central control plane for managing Claude Code profiles. ### Configuration List -Each card shows the name, description, whether it is applied, the primary model, the effort level, the permission mode, the Sandbox status, a plugin summary, and the result of the most recent model test. Available actions include create, enable (writing to `~/.claude/settings.json`), copy environment variables (generating `export KEY="value"` text), export the configuration file (optionally including or excluding the authentication key, with a preview of the final JSON before it is written to disk), duplicate, edit, delete, test all configurations at once, and drag to reorder. An enabled configuration also offers a one-click "sync common options and plugins to other configurations" action, which copies the current configuration's common options, plugin marketplaces, and enabled plugins to the remaining configurations, making it easy to unify a team baseline. +Each profile card highlights essential information: name, description, active status, primary model, effort level, permission mode, Sandbox state, plugin summary, and recent connectivity test results. -When the Configurations page finds an unmanaged `~/.claude/settings.json` and no configuration exists yet, it shows an import card. Importing takes over the current settings content in place and does not immediately rewrite the file. When a bound configuration is inconsistent with the real settings, the card shows a difference entry: choosing "Accept actual settings" writes the current file content back into the configuration; choosing "Re-apply" overwrites `settings.json` with the configuration's parsed result. +- **Comprehensive Actions**: Create, enable (writes to `~/.claude/settings.json`), copy environment variables (`export KEY="value"` syntax), export profiles (with optional secret inclusion and pre-save JSON preview), duplicate, edit, delete, and drag-and-drop to reorder. +- **Batch Model Testing**: Test connectivity for all managed profiles with a single click. +- **Baseline Sync**: In an active profile, click **Sync common options and plugins to other configurations** to propagate common switches, plugin marketplaces, and enabled plugins across all other profiles. +- **External Diff Tracking**: Detects unmanaged `~/.claude/settings.json` files on first launch. If an active file is modified externally, diff indicators let you choose between **Accept actual settings** or **Re-apply** to overwrite. ### Create or Edit a Configuration -The configuration editor on the right is divided into several sections. - -- **Basic information**: name (required), description, optional provider (selecting one automatically fills in the connection endpoint and model mapping). -- **Authentication**: the authentication key is written to `env.ANTHROPIC_AUTH_TOKEN`; the API endpoint is written to `env.ANTHROPIC_BASE_URL`, and when it is not set, the model test uses the official Anthropic endpoint. -- **Models and behavior**: the default model (an editable dropdown whose candidates come from the current provider's models, or you can type a custom model), the effort level (`auto`/`low`/`medium`/`high`/`xhigh`/`max`), the Opus / Sonnet / Haiku default models (also editable dropdowns), the Subagent model, the reply language, and the output style. -- **Common options**: override common Claude Code switches such as deep thinking, thinking summaries, Fast Mode, disable Hooks, disable AI attribution, LSP tools, Tool Search, the new Init, no flicker, subprocess credential scrubbing, and Agent Teams. See the editor for the full list. -- **Environment variables**: maintain `env` keys other than authentication and common options. Duplicate keys, invalid JSON, or an unsaved row edit will block saving. -- **Permissions**: default mode, disable `bypassPermissions`, allow / deny / ask rules, additional directories, and recommended rule presets. -- **Sandbox**: can be enabled or disabled, with recommended presets to add; complex configurations can switch to JSON mode. -- **Hooks**: maintain Claude Code hooks with a summary view, add the built-in garbled-text check preset, and switch complex structures to JSON mode. -- **Plugin marketplaces**: maintain `extraKnownMarketplaces` with built-in presets for the official marketplace (`claude-plugins-official`) and community marketplace (`claude-community`, repository `anthropics/claude-plugins-community`), available from both marketplace settings and Browse Marketplaces; each marketplace must fully specify the ID, source, repository or URL, path, package name, and install location. -- **Plugins**: maintain `enabledPlugins`, split into two tabs, "Configured" and "Browse marketplace". Browsing the marketplace currently supports only the `github` source; you can filter by marketplace / enabled status / category / source, and clicking enable immediately syncs it to the configured list. Refresh requests and the install-count refresh each time out after 30 seconds. Failed sources are reported separately; a local cache write failure does not prevent the downloaded list from being displayed. -- **Status line**: configure a custom status line command, and optionally enable the default status line preset (non-Windows writes `~/.claude/statusline.sh`; Windows writes `~/.claude/statusline.ps1` and automatically sets the PowerShell invocation command), and also sets a 60-second refresh interval so countdowns such as the prompt cache expiry keep updating while idle; if the target already exists with different content, you are prompted whether to overwrite. -- **Final configuration**: preview the final JSON after merging the provider with the configuration; the source JSON mode lets you maintain the entire settings object directly, and the preview automatically adds the schema URL. +The configuration drawer is organized into clean, functional sections: + +- **Basic Information**: Profile name (required), description, and optional provider selection (which auto-populates endpoints and model mappings). +- **Authentication**: Authentication key (written to `env.ANTHROPIC_AUTH_TOKEN`) and API base URL (written to `env.ANTHROPIC_BASE_URL`; defaults to official Anthropic endpoints when omitted). +- **Models & Behavior**: Default model (editable dropdown with provider recommendations or custom text input), effort level (`auto`/`low`/`medium`/`high`/`xhigh`/`max`), Opus / Sonnet / Haiku model mappings, subagent models, preferred reply language, and output style. +- **Common Options**: Visual toggles for deep thinking, thinking summaries, Fast Mode, disable Hooks, disable AI attribution, LSP tools, Tool Search, new Init, no-flicker mode, subprocess credential scrubbing, and Agent Teams. +- **Environment Variables**: Manage custom `env` key-value pairs with duplicate key detection and JSON syntax validation. +- **Permissions**: Default permission mode, disable `bypassPermissions` toggle, allow / deny / ask rules, trusted directories, and recommended security presets. +- **Sandbox**: Toggle sandbox isolation with recommended presets; switch to JSON mode for advanced configurations. +- **Hooks**: Maintain lifecycle hooks with an interactive summary view; includes built-in presets and JSON mode support. +- **Plugin Marketplaces**: Manage `extraKnownMarketplaces` with built-in templates for official (`claude-plugins-official`) and community (`claude-community`) marketplaces. +- **Plugins**: Manage `enabledPlugins` across **Configured** and **Browse marketplace** tabs. Filter by marketplace, status, and category with real-time toggle syncing. +- **Status Line**: Configure custom status line commands. Includes presets for macOS/Linux (`~/.claude/statusline.sh`) and Windows (`~/.claude/statusline.ps1` with PowerShell invocation), complete with a 60-second idle refresh interval to keep prompt cache countdowns accurate. +- **Final Configuration**: Live preview of the merged JSON output; includes a raw JSON mode to directly edit the underlying settings document. ### Model Test -After you click Test Model, a request is sent based on the current edits. The result dialog shows whether it succeeded, the model used and the returned model, the request endpoint, the status code, the elapsed time, the request ID, the stop reason, the input prompt, the returned content, the request / response headers, the request body, and the raw response, along with the ability to copy cURL and to modify the prompt and retest. +Clicking **Test Model** sends an immediate verification request using the currently edited configuration: -Model testing requires a valid `ANTHROPIC_AUTH_TOKEN` and an accessible model API. Some gateways (for example OpenCode Go) require clients to declare a session header per conversation; model tests generate and send it automatically for every request, so no manual configuration is needed. +- **Detailed Diagnostics**: View connection status, request and response model names, endpoint URL, HTTP status code, response latency, Request ID, stop reason, prompts, output tokens, headers, request payload, and raw responses. +- **Practical Utilities**: Copy full cURL commands to test directly in your terminal, or modify the test prompt on the fly. +- **Gateway Compatibility**: For API gateways requiring per-session identification headers (e.g. OpenCode Go), the test runner generates and injects them automatically. ### Deep Link Import -You can send a Claude settings document into Code Manager via a system URL for preview-and-import. The scheme/path is `code-manager://profiles/import`. - -- **Two mutually exclusive sources**: embedded `payload=` (base64url-encoded bare settings JSON, about 16KB decoded), or remote `url=` (HTTPS only; the app fetches then imports, with SSRF protections and size/redirect limits). -- **Optional query params**: `name` and `description` only prefill the import dialog. -- **Does not auto-enable**: after a successful resolve, the app switches to the Configurations page and opens the same preview dialog as file import. Confirming **creates a new configuration** with an empty `providerId` and **does not** automatically write or bind `~/.claude/settings.json`. -- **Secrets**: if the payload contains authentication-like fields, you must acknowledge the risk before import. “Copy Deep Link” from an existing profile excludes secrets by default; including secrets requires the same acknowledgement. -- **Queue**: multiple links are queued. Closing the preview or finishing an import continues with the next item. Leaving the Configurations page and returning restores unconfirmed links (the authoritative queue lives in the app backend). +Import Claude configurations directly into Code Manager via custom system URLs using the `code-manager://profiles/import` scheme. -The scheme is registered for packaged installs on macOS / Windows / Linux; Linux/Windows may need extra registration in some development setups. +- **Two Mutual Exclusive Sources**: + - **Embedded Payload**: `payload=` (base64url-encoded raw settings JSON; ~16KB decoded limit). + - **Remote URL**: `url=` (HTTPS only; fetched securely by the app with SSRF protections and size limits). +- **Prefilled Metadata**: Optional `name` and `description` parameters prefill the import dialog. +- **Safe by Default**: Resolving a link opens the configuration preview dialog. Confirming **creates a new profile** with an empty `providerId` and **never** automatically applies or overwrites `~/.claude/settings.json`. +- **Secret Protection**: Payloads containing sensitive credentials require explicit user confirmation before importing. Copying deep links from existing profiles excludes secrets by default. +- **Queueing**: Opening multiple deep links queues them sequentially, ensuring unconfirmed imports remain available across navigation. ## Providers -Providers are all built-in and read-only. They carry only objective provider information (the connection endpoint `ANTHROPIC_BASE_URL`, the model mapping, and optional additional environment variables) and contain no authentication keys. They currently cover Anthropic, DeepSeek, Zhipu GLM Coding Plan, Kimi Code Plan, MiniMax Token Plan, Xiaomi MiMo Token Plan, OpenRouter, Volcengine Ark Coding Plan, Wanjie Ark, OpenCode Go, and Ollama. +Providers are strictly **built-in and read-only**. They carry objective service endpoint configurations (`ANTHROPIC_BASE_URL`, model mappings, and default environment variables) without storing private credentials. -Custom providers are not supported. After you select a built-in provider under the "Provider" option in the configuration editor, its connection endpoint and model mapping are filled in automatically; you only need to add the authentication key and behavior settings. Clicking "View built-in providers" below that option opens a read-only overview where you can see each provider's name, ID, API endpoint, official documentation link, recommended models, and the client session header (if that gateway requires one). +- **Supported Ecosystems**: Covers Anthropic, DeepSeek, Zhipu GLM Coding Plan, Kimi Code Plan, MiniMax Token Plan, Xiaomi MiMo Token Plan, OpenRouter, Volcengine Ark Coding Plan, Wanjie Ark, OpenCode Go, and local Ollama deployments. +- **Usage**: Select any provider from the dropdown to automatically populate connection URLs and recommended model mappings. Click **View built-in providers** below the dropdown to inspect official docs, endpoint specs, and gateway headers. ## Memory Management -The Memory page is used to manage user-level Claude Code instructions. +The Memory page manages user-level Claude Code instruction files. -When there is no primary memory, the top of the page shows the Karpathy behavior guide preset, which you can create and enable as `CLAUDE.md` with one click. When editing an existing `CLAUDE.md`-type memory, you can also append this preset to the bottom of the current content; Code Manager uses a preset marker to prevent duplicate insertion and provides a link to the original repository so you can check the source. - -**Add a memory**: click Add Memory, fill in the name, choose the type (`CLAUDE.md` is written to `~/.claude/CLAUDE.md`, and only one can be enabled at a time; Rules are written to `~/.claude/rules/.md`, multiple can be enabled at once, and `paths` glob matching is supported), write the Markdown content, and save. The real file is written to `~/.claude` only after you enable it in the list. - -**Edit, duplicate, and delete**: editing updates the managed content and, when enabled, syncs the change to the real file; duplicating creates a disabled copy; deleting removes the managed record and cleans up rule directories that are no longer needed. - -**Import local memories**: Code Manager detects files in `~/.claude/CLAUDE.md` and `~/.claude/rules/*.md` that have not yet been imported; clicking "Import to management" takes them over in place without immediately rewriting the content. Symlinked memories cannot be imported, and a path that is already occupied requires resolving the conflict first. - -**Import from a directory**: click Import Memory and choose a directory containing `CLAUDE.md` or `rules/`; imported items are disabled by default. Common reasons for skipping: a duplicate `CLAUDE.md`, a Rule already exists at the same path, an invalid path, a read failure, or symlinks not being supported. +- **Karpathy Behavior Guide Preset**: When no primary memory exists, a banner offers to create and enable Karpathy's guidelines as `CLAUDE.md` with one click. When editing existing memories, the preset can be appended to the bottom (protected against duplicate insertions). +- **Creating Memories**: Enter a name, select a type (`CLAUDE.md` written to `~/.claude/CLAUDE.md`, strictly single-active; Rules written to `~/.claude/rules/.md`, multiple active with `paths` glob matching), and edit the Markdown content. Files are only written to disk when enabled. +- **Maintenance**: Edit content, clone disabled duplicates, or delete obsolete rule files and folders. +- **Importing**: + - **Local Detection**: Automatically discovers unmanaged `CLAUDE.md` and `rules/*.md` files in `~/.claude` for in-place takeover. + - **Directory Import**: Select an external folder to batch-import instruction files in disabled state; duplicates and invalid symlinks are skipped automatically. ## Skills Management -The Skills page manages Claude Code Skills under `~/.claude/skills/`. - -**Add a Skill**: click Add Skill, fill in the Skill name (the directory name / slash command, which allows only lowercase letters, digits, and hyphens), the display name, and the description, then write the `SKILL.md` body. You can set "manual trigger only" (writing `disable-model-invocation`) and "allow manual invocation". +The Skills page organizes custom capabilities stored under `~/.claude/skills/`. -**List operations**: each Skill supports enable / disable, edit `SKILL.md`, delete, open the directory in an external editor, and sync to `~/.codex/skills`. Enabled corresponds to `~/.claude/skills//`, and disabled corresponds to `skills-disabled//` under the application data directory. - -**Import Skills**: you can select a single Skill directory, a Skill symlink, or a collection directory containing multiple Skills. Reasons for skipping include a name that does not match the rules, an item with the same name already exists, a missing valid `SKILL.md`, or an invalid symlink target. Symlinked Skills show a read-only notice and can be toggled and have their source directory opened, but their content cannot be modified inside the app. - -**Supporting files**: the editor shows a tree of supporting files other than `SKILL.md`. It currently only shows the directory tree; to make changes, open the Skill directory in an external editor. +- **Create a Skill**: Provide an ID (directory and slash command name; lowercase letters, numbers, and hyphens only), display name, description, and `SKILL.md` body. Optionally configure manual invocation restrictions (`disable-model-invocation`). +- **State Management & Archival**: + - **Enabled**: Stored in `~/.claude/skills//`. + - **Disabled**: Moved to `skills-disabled//` in the application data directory to keep your Claude workspace uncluttered. + - One-click symlink syncing to `~/.codex/skills`. +- **Importing Skills**: Import individual skill directories, symlinks, or multi-skill parent folders. Symlinked skills display a read-only tag; they can be toggled and opened, but editing must take place in the source directory. +- **Supporting Assets**: Browse auxiliary scripts, prompts, and templates within the skill directory; launch external editors for complex multi-file edits. ## Project Management -The Projects page extracts the project list from `~/.claude/history.jsonl`, sorted by most recent activity. Project details also read the project's real directory and show Git, worktrees, project-level Claude configuration, and local cleanup entries. +The Projects page extracts project history from `~/.claude/history.jsonl`, ordered by recent activity. Selecting a project inspects its working directory for Git state, worktrees, and project-level Claude configurations. ### Project List and Details -The list on the left shows the project short name, path, last active time, session and input counts, and the most recent session ID. After you click a project, details are shown on the right. +The left-side list shows project basenames, paths, last active timestamps, session and prompt counts, and the latest Session ID. Clicking any project loads its details on the right. ### Quick Actions -- Open the project in a terminal: uses the default terminal from Settings, with options filtered by the current platform and what is installed locally. -- Open the project in an editor: requires selecting a default editor in Settings first, with options filtered by platform and installation status. -- Open the source repository: uses the project's Git remote URL. +- **Open in Terminal**: Launches your default terminal configured in Settings, tailored to your operating system. +- **Open in Editor**: Launches your selected code editor. +- **Open Remote Repository**: Resolves the Git remote URL and opens it in your default web browser. ### Editor and Terminal Support Matrix -| Application | macOS | Linux | Windows | +| Tool | macOS | Linux | Windows | | --- | --- | --- | --- | -| VS Code | Supported | Requires `code` CLI | Requires `code` CLI | -| Zed | Supported | Requires `zed` CLI | Requires `zed` CLI | -| Terminal | Terminal.app | Tries `$TERMINAL`, `xdg-terminal-exec`, `x-terminal-emulator`, etc. in order | Tries Windows Terminal, PowerShell, cmd in order | -| iTerm | Supported | Not supported | Not supported | -| Ghostty | Supported | Requires `ghostty` CLI | Not yet supported | +| VS Code | Native application | Requires `code` CLI | Requires `code` CLI | +| Zed | Native application | Requires `zed` CLI | Requires `zed` CLI | +| Terminal | Terminal.app | Falls back: `$TERMINAL`, `xdg-terminal-exec`, `x-terminal-emulator` | Falls back: Windows Terminal, PowerShell, cmd | +| iTerm2 | Fully supported | Not supported | Not supported | +| Ghostty | Fully supported | Requires `ghostty` CLI | Not yet supported | ### Status Checks -The details page shows: whether the directory exists, whether it is a Git repository, the `CLAUDE.md` / `AGENTS.md` pairing status, the `.claude/skills` / `.agents/skills` pairing status, the project-level `.claude/` overview, local branches and recent commits, worktree paths and status, the last active time, session and input counts, the most recent session ID, the Git root directory, and the 5 most recent sessions (clickable to view details). Quick actions support opening a terminal, opening an editor, opening the source repository, jumping to this project's history, and jumping to this project's token usage. +Project details provide health checks and diagnostics: +- Directory existence, Git repository detection, current branch, recent commits, and active worktrees. +- `CLAUDE.md ↔ AGENTS.md` pairing status and `.claude/skills ↔ .agents/skills` directory pairing status. +- Recent session timelines (clickable to inspect full message replays). +- Quick navigation to project-specific history or token usage. ### Project-Level Claude Configuration -Project-level Claude management is divided into three groups: - -- Memory files: `CLAUDE.md ↔ AGENTS.md` two-way pairing. When either side is a real file, you can create a relative symlink for the other side; when neither side exists, when a regular file conflicts, or when there is an orphan symlink, no automatic handling is performed. -- Project-level Skills: `.claude/skills ↔ .agents/skills` two-way pairing. When either side is a real directory, you can create a relative symlink for the other side; when both sides are real directories, you must merge them manually. -- The project `.claude/` directory: open the Sheet on the right to browse, preview, and open project-level Claude files in an external editor. `settings.json` and `settings.local.json` support one-click creation; other project-level files can be previewed or opened externally, but cannot be created, deleted, or renamed in the project drawer. +Provides three core integration tools for project-level workflows: +- **Instruction Pairing**: Bidirectional relative symlink creation between `CLAUDE.md ↔ AGENTS.md` ensures cross-agent compatibility. +- **Skill Pairing**: Bidirectional symlinking between `.claude/skills ↔ .agents/skills`. +- **Project `.claude/` Drawer**: Browse project-level Claude files in a slide-out drawer, with one-click creation of `settings.json` and `settings.local.json`. ### Branch and Worktree Cleanup -Project details can detect local branches and worktrees that have been merged or deleted on the remote and can be safely cleaned up. Cleanup always takes two steps: first a preview list is generated for you to select from, and deletion is performed only after confirmation; the backend only cleans up the entries listed in the preview. +Scans for local branches and worktrees that have already been merged or deleted on remote repositories. +- **Safe Two-Step Operation**: Generates an interactive preview list; deletion only executes after user confirmation, ensuring unlisted items are never touched. ### Clear Project Local Data -Right-click a project list item and choose Clear local data. The application first generates a dry-run deletion plan and only executes it after confirmation. This operation calls the Claude CLI to clear the project's saved local state, so review the plan carefully before executing it. +Right-click any project item to initiate local data cleanup. The app runs a dry-run plan via the Claude CLI, prompting for user confirmation before clearing local project state. ## Usage History -The History page reads `~/.claude/history.jsonl` and is used to review historical inputs and sessions. +The History page parses `~/.claude/history.jsonl` to review past prompts and complete interaction sessions. -The left side groups by project, the heatmap at the top shows recent history density, the search box filters by displayed text, and clicking a session opens the details drawer. The URL syncs the `project`, `q`, and `session` parameters so you can preserve filter state. - -Session details show user messages, assistant messages, thinking summaries, tool calls and returns, commands, images, plan content, and system events. You can copy the project path, the session ID, or a single message, or open the raw session record file in an editor. +- **Filtering & Search**: Grouped by project on the left; displays interaction density heatmaps; text search filters history entries; URLs sync `project`, `q`, and `session` query parameters. +- **Session Replay**: The detail drawer reconstructs the interaction timeline, displaying user prompts, assistant replies, thinking summaries, tool invocations, shell commands, images, plans, and system events. +- **Utilities**: Copy paths, session IDs, or individual messages, or launch the raw `.jsonl` log file in your external editor. ## Usage Statistics -The Stats page reads `~/.claude.json` and shows the local statistics snapshot (not a real-time computed result). - -The page provides the startup count, the first-use date, the number of projects, the last Plan Mode usage time, the `btw` usage count, a tool call count chart, a Skill usage count list, and a list of each project's most recent session. Each project's most recent session shows the latest cost, session duration, lines added / removed, the various token types, the number of web searches, model details, the first prompt, frame, and Hook performance metrics. +The Stats page displays the static telemetry snapshot stored in `~/.claude.json` (not real-time computed runtime figures). -The top of the page lets you refresh the data or open `~/.claude.json` in the default editor. +- **High-Level Metrics**: Cumulative launches, first-use date, total projects, last Plan Mode timestamp, and `btw` invocation count. +- **Charts & Rankings**: Tool invocation frequency charts and skill usage rankings. +- **Recent Project Sessions**: Lists the most recent session per project, including estimated cost, duration, lines added/removed, token breakdowns, web search counts, and initial prompts. ## Token Usage Statistics -The Usage page scans `~/.claude/projects/**/*.jsonl` and `subagents/*.jsonl`, extracts the usage field from assistant messages, and estimates cost based on the price table. +The Usage page analyzes `~/.claude/projects/**/*.jsonl` and `subagents/*.jsonl` log files, extracting `usage` payloads from assistant messages and pricing them against standard pricing tables. ### Data Metrics -- Deduplicated globally by `message.id`; when the same message appears multiple times, the snapshot with the larger token usage is kept. -- Tokens include input, output, cache creation, and cache read; cost is estimated in units of USD / 1M tokens. -- Price table loading order: the local cache `model-pricing.json` → the built-in Anthropic fallback table → an update from models.dev on startup or manual refresh. -- models.dev only imports official provider prices: Anthropic, Moonshot / MoonshotAI, Z.ai / Zhipu / BigModel, MiniMax, Xiaomi / MiMo, DeepSeek. Among these, Kimi, MiMo, GLM, MiniMax, and DeepSeek are controlled by the "third-party model pricing" switch on the Settings page; when it is off, their cost is counted as 0. -- Tokens for other models whose price cannot be matched are still counted, but their cost is counted as 0 and they enter the unknown models list. +- **Deduplication**: Deduplicated globally by `message.id`; when duplicates occur, the snapshot with higher token counts is preserved. +- **Token Composition**: Covers Input, Output, Cache Creation, and Cache Read tokens; costs are normalized in USD / 1M tokens. +- **Pricing Resolution**: Local cache `model-pricing.json` → Built-in Anthropic fallback table → Live models.dev updates on startup or manual refresh. +- **Official Providers**: models.dev imports pricing for official providers (Anthropic, Moonshot/Kimi, Zhipu GLM, MiniMax, Xiaomi MiMo, DeepSeek). Third-party Chinese models can be toggled via the **Third-party model pricing** switch in Settings (costs count as 0 when disabled). +- **Unrecognized Models**: Models not found in pricing tables still track token counts, but costs are registered as 0 and categorized under unknown models. ### Top Status and Actions -The top shows the price source (built-in / local cache / models.dev live). Action buttons: refresh prices, view the model price list (you can search by model to see input, output, cache write / read prices, and current usage), and rescan. +Displays the current price table source (built-in, local cache, or models.dev live), with buttons to refresh prices, view the model pricing table, or trigger a full rescan. ### Filtering -Supports filtering by date range, quick range (today, last 7 days, last 30 days, this week, this month, this year, all), project, and model (including `claude-*` aggregation). Reset returns to today. +Filter by custom date ranges, quick presets (Today, Last 7 Days, Last 30 Days, This Week, This Month, This Year, All Time), target projects, and models (including `claude-*` wildcards). ### Charts and Tables -The page includes total spend, total tokens, session count, message count, cache savings, spend trend, token trend, model cost share, token composition, and detail tables by date, project, session, and model. The trend charts support splitting by model or token type, curve or bar style, and day / hour / 5-minute granularity; you can click a legend item to toggle its display, or double-click a legend item to show only that item. Clicking a session in the by-session table opens the message-level usage details. +- **Summary Cards**: Total spend, total tokens, session counts, message counts, and prompt cache savings. +- **Trend Charts**: Spend and token trends split by model or token type, rendered as curves or bars across daily, hourly, or 5-minute granularities. +- **Breakdown Tables**: Comprehensive tables grouped by date, project, session, and model; click any session to inspect message-level token waterfall charts. ## Desktop Usage Widget -The desktop usage widget is a small, always-on-top, semi-transparent, borderless window that lets you keep an eye on today's usage without opening the main interface. Once enabled, it stays present across all virtual desktops (macOS Spaces), does not appear in the taskbar, first appears in the lower-right corner of the screen, and remembers its position after you drag it. It is available on all three platforms. +An always-on-top, translucent, borderless desktop mini-window that tracks today's usage without keeping the main application open. -- **Displayed metrics**: shows today's usage KPIs in real time, optionally cost, total tokens, cache hit rate, message count, session count, and top model. By default it shows the first three (cost, total tokens, cache hit rate), and you can customize the selection and order in Settings. -- **Data refresh**: the data shares the same source as the Usage page and refreshes automatically when records or prices change. -- **Quick jump**: clicking the body of the widget jumps to the Usage page in the main interface. -- **Appearance and toggle**: the opacity is adjustable, and the enable toggle along with the metrics and opacity settings are all in the settings drawer (see the "Desktop Usage Widget" settings subsection below). +- **Desktop Integration**: Persists across all macOS Spaces, bypasses the taskbar, initializes in the lower-right corner, remembers drag coordinates, and runs across all three platforms. +- **Customizable KPIs**: Displays today's essential metrics (cost, total tokens, cache hit rate, message count, session count, top model) with custom selection and ordering in Settings. +- **Real-Time Sync**: Shares the analytics engine cache and refreshes automatically when logs or pricing tables update. +- **Instant Access**: Click the widget body to launch Code Manager directly to the Usage page. +- **Appearance**: Adjust overall opacity from 30% to 100% in Settings. ## Cheat Sheet -The Cheat Sheet entry at the bottom of the sidebar opens a Claude Code quick-reference page that follows the interface language (Chinese / English). It covers keyboard shortcuts, MCP servers, slash commands, memory and files, workflows and tips, configuration and environment variables, skills and agents, CLI flags, and permission modes. The table of contents on the right jumps to each section. +Accessible at the bottom of the sidebar, the Cheat Sheet provides a quick-reference guide that adapts to your active interface language: +- Covers keyboard shortcuts, MCP server setups, slash commands, memory rules, best practices, configuration and environment variables, subagents, CLI flags, and permission modes. +- Includes an anchor table of contents on the right for navigation. ## System Tray and Session Focus -Code Manager stays in the system tray (menu bar), with a menu divided into two parts: +Code Manager stays accessible in the system tray / menu bar with two primary sections: -- Main tray: switch the current configuration, quickly jump to each page, and quit the application. Switching the configuration is equivalent to enabling the corresponding configuration on the Configurations page. -- Session tray: reads `~/.claude/sessions/*.json` and summarizes the current Claude sessions by status (awaiting input / working / idle). Whether it is shown, the character limit, the session count style, and the pending breathing indicator are all adjusted in Settings (see below). +- **Main Menu**: Switch active configuration profiles, jump to application pages, or exit the app. Switching profiles here is identical to enabling them in the Configurations page. +- **Session Menu**: Monitors `~/.claude/sessions/*.json`, summarizing active sessions by operational state (waiting for input, busy/thinking, idle). -**Session focus**: on supported platforms, clicking a session entry or using the session focus shortcut returns you to the corresponding terminal tab. This capability is **macOS only**; it focuses Terminal.app and iTerm2 via `pid → tty → AppleScript`, and Ghostty first matches its `tty` property before using a unique working-directory fallback on older versions or when tty matching misses. Linux and Windows do not support automatic focus, and clicking a session will not switch the terminal. See [Platform Support Differences](./platform-support.md) for details. +### Session Focus (macOS only) -**LED light effect integration (macOS only)**: once enabled, the red/green status of the session tray is mirrored to the light effects of an external ANTICATER USB device, which is handy for getting a hardware light cue about session status when you are not watching the menu bar. The configuration entry is the LED light effect card in Settings. +On supported setups, clicking any session entry or pressing the **Session Focus Shortcut** brings the target terminal window and tab directly into focus: +- **Terminal.app & iTerm2**: Leverages `pid → tty → AppleScript` for terminal tab matching. +- **Ghostty**: Matches the `tty` property, falling back to unique working directories. +- **Platform Limits**: Linux and Windows do not support automatic terminal focusing. See [Platform Support Differences](./platform-support.md). + +### LED Hardware Integration (macOS only) + +Mirrors session tray status (red/green) directly to external ANTICATER USB device LEDs, providing hardware ambient cues when working away from your screen. ## Settings and Diagnostics -The Settings entry is in the lower-left corner. The settings drawer is a single column of cards; the groups below follow the order of the cards in the drawer. Cards or options marked "macOS only" are not shown on Linux and Windows. +Located in the lower-left corner, Settings presents a card-based drawer organized into clean sections: ### Interface -- Interface language: Chinese / English. -- Theme appearance: light / dark / follow system. -- Collapse sidebar by default: after startup the sidebar shows only the menu icons; it still collapses automatically on narrow screens. +- **Interface Language**: English / Simplified Chinese. +- **Theme Appearance**: Light / Dark / Follow System. +- **Collapse Sidebar by Default**: Starts with a collapsed, icon-only sidebar to maximize screen space. ### Menu Bar and Session Status -- Show current configuration in the menu bar: shows the name of the currently active configuration next to the tray icon; the character limit can be set to off, up to N characters, or fully expanded. -- Show current session in the menu bar: shows the current Claude session and its status in a separate menu bar area. -- Session count style: number (`🔴 1 🟢 1`), superscript (`🔴¹ 🟢¹`), or compact (`🔴¹🟢¹`). -- Pending session breathing indicator (macOS only): when there is a session awaiting input, the menu bar status shows a breathing-style pulse cue. -- Session focus shortcut (macOS only): registers a global shortcut for "focus the session that most needs attention". Click to record and press the key combination (which must include at least one modifier key ⌘/⌃/⌥/⇧); you can restore the default at any time. +- **Show Active Configuration in Menu Bar**: Displays the active profile name alongside the tray icon (off, truncated to N characters, or full width). +- **Show Current Session in Menu Bar**: Shows Claude session indicators in a separate menu bar item. +- **Session Count Style**: Standard numbers (`🔴 1 🟢 1`), superscripts (`🔴¹ 🟢¹`), or compact badges (`🔴¹🟢¹`). +- **Pending Session Breathing Indicator (macOS only)**: Displays a pulsating animation when sessions require user attention. +- **Session Focus Shortcut (macOS only)**: Register a custom global hotkey to jump immediately to the session requiring attention. ### Desktop Usage Widget -- Enable the desktop usage widget: when enabled, creates an always-on-top semi-transparent small window that shows today's usage metrics in real time (see "Desktop Usage Widget" above). -- Displayed metrics: multi-select the metrics to show in the widget (cost, total tokens, cache hit rate, message count, session count, top model), keeping at least one. -- Opacity: a slider adjusts the overall opacity of the widget, ranging from 30% to 100%, defaulting to 92%. +- **Enable Desktop Widget**: Toggle the floating usage window. +- **Displayed Metrics**: Choose and order the metrics displayed on the widget. +- **Opacity Slider**: Smoothly adjust widget transparency from 30% to 100% (default 92%). ### LED Light Effects (macOS only) -- LED light effect integration: mirrors the tray session status to the light effects of an ANTICATER USB device. When you open Settings, the device is detected automatically, showing connected / no device detected / detecting status. The three states—awaiting your input, working / thinking, and done / idle—can each be assigned a light effect mode (off / clockwise / counterclockwise / alternating / jumping / blinking), and the test button next to each mode lights it up immediately for verification. The configuration can still be saved when no device is connected, and it takes effect once a device is attached. - -> The LED light effect card is shown only on macOS. +Automatically discovers connected ANTICATER USB hardware: +- Assign lighting patterns (off, clockwise, counterclockwise, alternating, jumping, blinking) to three session states: waiting for input, working/thinking, and done/idle. +- Test buttons provide instant hardware verification. ### Prevent Sleep (macOS only) -When Claude Code sessions need to run for a long time, you can stop the Mac from entering idle sleep. - -- **Mode (one of three)**: - - **Off**: do not interfere with system sleep. - - **While active**: stay awake while there is a running Claude Code session; idle sleep is allowed again when all sessions end. - - **Always**: stay awake unconditionally (still subject to the display option below). -- **Keep display awake**: orthogonal to the mode. By default only **system idle sleep** is blocked and the display may still dim per system policy; enabling this keeps the display on as well. -- **Live status**: when the mode is not Off, Settings shows a status dot such as “Keeping awake” or “Idle, may sleep”; the tray menu can also switch modes. -- **Limits**: macOS only; hardware policies such as closing the lid may still sleep the machine; quitting the app releases the power assertion. +Prevents system sleep during long-running tasks: +- **Sleep Prevention Mode**: + - **Off**: Standard system sleep behavior. + - **While active**: Prevents sleep only while Claude Code sessions are actively running. + - **Always**: Keeps system awake unconditionally. +- **Keep Display Awake**: Independently controls whether displays stay awake or dim according to system policies. +- **Live Indicators**: Displays power assertion indicators in Settings and tray menus. ### System Notifications, Sounds, and Pricing -- System notifications: used when a Claude session enters the pending state, when clicking a session to jump but terminal location fails, and when the cache hit rate in the last 5 minutes falls below the configured threshold (default 90%, adjustable from 10% to 99%). When enabled, system notification permission is requested first; if permission is denied, the setting stays off. -- Waiting sound: plays a system sound when a session starts waiting for input; choose and preview Glass, Submarine, Hero, Ping, Sosumi, or Tink. The option is shown on every platform but only plays on macOS. -- Third-party model pricing: controls whether Kimi, MiMo, GLM, MiniMax, and DeepSeek are estimated using models.dev prices; when off, the cost of these models is counted as 0. +- **System Notifications**: Alerts when sessions need attention, when terminal jumps fail, or when cache hit rates drop below thresholds (default 90%, adjustable from 10% to 99%). +- **Notification Sounds**: Plays audio cues when input is needed (Glass, Submarine, Hero, Ping, Sosumi, Tink). +- **Third-Party Model Pricing**: Controls whether Chinese model costs are calculated using models.dev pricing tables. ### System Integration -- Launch at startup: automatically launches Code Manager after you log in to the system. -- Default terminal, default editor: used by the "open in terminal / editor" actions on the Projects page and in the Directory Overview. - -The available items come from a built-in support list and system detection; they do not automatically list every application on your computer, ensuring that each option has a clear open command and project path parameter. Editors on Linux and Windows require the corresponding CLI to be accessible in `PATH`; the default terminal on Windows prefers Windows Terminal and falls back to PowerShell and cmd on failure. +- **Launch at Startup**: Automatically launches Code Manager upon system login. +- **Default Terminal & Editor**: Configures preferred applications for external launching actions across projects and file trees. ### Log Viewer -Click View Logs to open the log window, which supports filtering by level (all / error / warn / info / debug / trace), searching, refreshing, opening the log directory, and clearing logs. By default it shows the 500 most recent matching results, switchable to 1000 / 2000 / 5000, and indicates when results are truncated. +Click **View Logs** to open the dedicated log viewer: +- Filter by log level (All / Error / Warn / Info / Debug / Trace), perform text search, refresh, or clear logs. +- Secrets and tokens are redacted before logs are written to disk. +- Direct button to open the log directory in your system file explorer. ### System Information -The System Information window shows the Code Manager version, the operating system type / platform / version / family, the CPU architecture, the hostname, and the locale. Clicking Copy copies the information as a Markdown table, which is convenient for filing an issue or troubleshooting. +Collects application versions, OS distribution/kernel/family, CPU architecture, hostname, and locale settings. Includes a **Copy Markdown** button for issue reporting and troubleshooting. ### Application Update -The application update card shows the current version and provides a "Check for updates" button: when a new version is found, clicking "Download and install" automatically downloads, installs, and restarts into the new version. The application also checks silently once on startup, and when a new version is found it only shows a Toast notice, leaving the decision to update up to you. Update packages are verified with an official minisign signature and pulled from GitHub Releases. Users who installed via Homebrew can also continue to upgrade with `brew upgrade`; both methods work. +The update card displays the current version and release channel: +- Manual **Check for Updates** button to download, verify, and restart with one click. +- Silent startup checks notify you via non-intrusive toast messages. +- Packages are verified against official minisign cryptographic signatures. +- Homebrew users can continue using `brew upgrade`; in-app and Homebrew versions automatically align on subsequent checks. ## Local Data and Privacy -Code Manager mainly reads and writes local files. Configuration merging, directory scanning, usage aggregation, and log viewing are all done locally. +Code Manager follows a strict **Local-First** privacy architecture. Configuration merging, directory scanning, token calculation, and log inspection execute entirely offline on your machine. No user code, prompts, or configurations are transmitted to remote servers. ### Application-Managed Data @@ -362,33 +401,34 @@ Code Manager mainly reads and writes local files. Configuration merging, directo | Linux | `$XDG_CONFIG_HOME/code-manager/` or `~/.config/code-manager/` | | Windows | `%APPDATA%\code-manager\` | -> This application deliberately reuses `~/.config/code-manager/` instead of the macOS-standard `~/Library/Application Support/...`, to make cross-platform sync backups and unified script access easier. +> [!NOTE] +> On macOS, the app uses `~/.config/code-manager/` instead of `~/Library/Application Support/...` to facilitate unified script access and cross-platform backup workflows. ```text / - config-registry.json - memories.json - model-pricing.json - skills-disabled/ + config-registry.json # Managed configuration registry + memories.json # Managed memories and rules + model-pricing.json # Local model pricing cache + skills-disabled/ # Disabled skills archive ``` ### Claude Code User Directory and Inputs ```text ~/.claude/ - settings.json - CLAUDE.md - rules/ - skills/ - projects/ # input for the Usage page - history.jsonl # input for the Projects and History pages - statusline.sh -~/.claude.json # input for the Stats page + settings.json # Active Claude Code settings + CLAUDE.md # Active primary memory + rules/ # Active modular rules + skills/ # Active custom skills + projects/ # Log inputs for Token Usage page + history.jsonl # Input for Projects and History pages + statusline.sh # Custom status line script +~/.claude.json # Telemetry input for Stats page ``` ### Usage SQLite Cache -Maintained by the backend usage runtime via `sqlx`. The database is named `usage.db` and is located in the Tauri default application configuration directory (which is not the same location as the "application data directory"). When SQLite uses WAL mode, `usage.db-wal` and `usage.db-shm` may also appear in the same directory. +Maintained by the backend runtime via `sqlx` in the default application data directory (isolated from the application data directory above): | Platform | Path | | --- | --- | @@ -398,7 +438,7 @@ Maintained by the backend usage runtime via `sqlx`. The database is named `usage ### Log Directory -The file name is usually `code-manager.log`, and rotated files look like `code-manager_2026-04-29_09-13-00.log`. +Primary logs are named `code-manager.log`, with rotated archives formatted as `code-manager_2026-04-29_09-13-00.log`: | Platform | Path | | --- | --- | @@ -410,72 +450,82 @@ The file name is usually `code-manager.log`, and rotated files look like `code-m ### Create and Enable a Provider Configuration -1. Go to the Configurations page, create a configuration, select a built-in provider under the "Provider" option, and fill in the authentication key. -2. Adjust the default model, effort level, and common options as needed, then open the final configuration preview to confirm the `env` and permissions. -3. Click Test Model, and save once it succeeds. -4. Go back to the list and click Enable, then open the Directory Overview to check `settings.json`. +1. **Create Profile**: Go to Configurations, click **New Configuration**, pick a built-in provider, and enter your API credentials. +2. **Fine-Tune Options**: Adjust default models and common toggles, then inspect the **Final Configuration Preview** to confirm your `env` and permissions. +3. **Test Connectivity**: Click **Test Model**; once verified, save the profile. +4. **Activate & Verify**: Click **Enable** in the profile list, then switch to the **`~/.claude` Directory Overview** to confirm `settings.json` has been updated. ### Take Over an Existing `CLAUDE.md` and Rules -1. Go to the Memory page and click "Import to management" for the files you want to manage in the not-yet-imported group. -2. Check that the content and path match, and enable or disable them as needed. +1. **Discover Files**: Navigate to the Memory page and locate discovered unmanaged files in the **Not Imported** section. +2. **Import & Enable**: Click **Import to management** to take over files in place, reviewing paths and toggling active status as needed. ### Create a Skill and Sync It to Codex -1. Go to the Skills page, add a Skill, and fill in a valid id, display name, and description. -2. Write `SKILL.md`, set whether automatic / manual invocation is allowed, and save it as enabled. -3. Click sync to `~/.codex/skills`. +1. **Define Skill**: Go to Skills, click **Add Skill**, and enter a valid ID, display name, and description. +2. **Draft Content**: Write your `SKILL.md` body, configure invocation triggers, and save in the enabled state. +3. **Establish Symlink**: In the skill card menu, click **Sync to `~/.codex/skills`** to link the skill across tools. ### Troubleshoot a Model That Cannot Be Called -1. Edit the target configuration and confirm the authentication key, API endpoint, and model. -2. Click Test Model and check the status code, request endpoint, request body, and raw response in the result. -3. If necessary, copy the cURL to a terminal to reproduce it; if the failure is in the app's own save or invocation, go to Settings to view the logs. +1. **Verify Credentials**: Edit the active profile to confirm your API key, endpoint Base URL, and model identifier. +2. **Run Diagnostics**: Click **Test Model** and inspect the returned HTTP status code, error messages, and raw responses. +3. **Reproduce**: Copy the generated cURL command to verify directly in your terminal. For app-level errors, inspect **Settings → Diagnostics → View Logs**. ### Troubleshoot Abnormal Cost or Tokens -1. Go to the Usage page, select the date range, project, and model, and check the total spend and composition. -2. Open the model price list and confirm whether the target model has a complete price; switch to the by-session table and click the abnormal session to view the message-level details. -3. A model appearing in the unrecognized list means its cost is counted as 0; you can try refreshing prices, and for third-party models confirm whether the pricing switch on the Settings page is on. +1. **Isolate Scope**: On the Token Usage page, filter by date range, project, and model to pinpoint spending anomalies. +2. **Audit Unit Rates**: Open the model pricing table to verify that pricing data exists for the model. Drill down into individual sessions in the session table to review message-level token waterfalls. +3. **Zero-Cost Models**: If a model appears under unknown models, click **Refresh Prices**. For third-party Chinese models, check that third-party pricing is enabled in Settings. ## Frequently Asked Questions ### Where is a configuration written after I enable it? -It is written to `~/.claude/settings.json`. The content is the final JSON after merging the provider `env` with the configuration's own settings, and it includes the Claude Code settings schema. +**Written directly to `~/.claude/settings.json`.** +The file contains the merged result of provider presets and custom profile settings, formatted as standard JSON with schema references for IDE autocompletion. ### Does deleting a configuration delete `settings.json`? -No. Deleting a configuration only removes the managed record and binding status; it does not clean up the `~/.claude/settings.json` that has already been written out. +**No.** +Deleting a configuration only removes the managed profile from Code Manager's internal registry. It will never delete or wipe existing files on disk. ### Why does the model test report a missing `ANTHROPIC_AUTH_TOKEN`? -The current configuration's final configuration has no usable authentication key. Fill it in the Authentication section, or confirm whether `env.ANTHROPIC_AUTH_TOKEN` in the JSON has been overridden to empty. +**No valid credentials were found in the active configuration.** +Ensure you entered an API key under Authentication, or verify that `env.ANTHROPIC_AUTH_TOKEN` has not been overridden with an empty value in JSON mode. ### Why are there no projects on the Projects page? -The Projects page comes from `~/.claude/history.jsonl`. After you use Claude Code and produce history records, the projects will appear in Code Manager. +**No Claude Code history exists yet on your machine.** +The Projects page indexes `~/.claude/history.jsonl`. Once you conduct your first Claude Code session in any terminal, projects will populate automatically. ### Why are the costs on the Stats page and the Usage page inconsistent? -The Stats page reads the local statistics snapshot from `~/.claude.json`; the Usage page scans `~/.claude/projects/**/*.jsonl` and re-estimates based on the current price table. The two have different data sources and calculation metrics. +**They use different data sources and accounting methods.** +The Stats page reads the static telemetry snapshot from `~/.claude.json`, whereas the Usage page scans raw `.jsonl` session files across all projects and prices them against active pricing tables. ### Why is the cost of some models 0? -The model is not in the price table, so the tokens are still counted but the cost is counted as 0. Kimi, MiMo, GLM, MiniMax, and DeepSeek are also counted as 0 when third-party model pricing is off. You can try refreshing prices, or enable third-party model pricing on the Settings page. +**The model lacks pricing data or third-party pricing is disabled.** +When a model is not indexed by models.dev, token counts are tracked but unit prices default to 0. Similarly, Chinese models register as 0 if the third-party pricing toggle is turned off in Settings. ### How do I update Claude Code plugins? -Code Manager only manages `enabledPlugins` and `extraKnownMarketplaces` in your settings; it does not install or upgrade plugins. To update plugins, run `claude plugin update @` for a single plugin, or `/plugin marketplace update ` inside Claude Code to refresh the catalog and upgrade the installed plugins from that marketplace. You can also set `extraKnownMarketplaces..autoUpdate` to `true` in the configuration's JSON mode so Claude Code updates them on startup. See the official docs: [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins). +**Run update commands in your terminal.** +Code Manager manages `enabledPlugins` and `extraKnownMarketplaces` in your configuration, but does not download or build plugin files. In your terminal, run `claude plugin update @` or `/plugin marketplace update `. You can also set `autoUpdate: true` in your profile settings. See official documentation: [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins). ### Why can't I edit a symlinked Skill? -The source directory of a symlinked Skill is not within Code Manager's direct management scope. The application only allows toggling, importing, and opening the directory; the content must be maintained in the source directory. +**Symlink source targets reside outside the managed directory.** +To prevent unintended modifications to external repositories, Code Manager only supports toggling, importing, and opening symlinked skills. Edit the files directly in their original source directories. ### Is clearing project local data safe? -This operation first generates a dry-run deletion plan and only executes it after confirmation; it is used to clear the project local state saved by the Claude CLI. You must review the deletion plan before executing it to avoid accidentally deleting data you still need. +**It includes dry-run planning, but should be used with care.** +This action clears local context caches saved by the Claude CLI for the project. Code Manager displays a dry-run preview of files scheduled for deletion before requiring your explicit confirmation. ### Why don't I see the LED light effect integration or the session focus shortcut? -Both are provided on **macOS only** and are not shown in the Settings on Linux and Windows. The LED light effect also requires connecting an ANTICATER USB device: when the LED light effect card in Settings shows "No device detected", the light effect will not light up, so confirm that the device is connected, turn on the switch in that card, and choose a non-"off" light effect mode for the corresponding status. +**Both capabilities are exclusive to macOS.** +These settings cards are automatically hidden on Linux and Windows. Additionally, LED effects require a physically connected ANTICATER USB device with enabled status modes. diff --git a/docs/user-manual.zh-CN.md b/docs/user-manual.zh-CN.md index bf28851..5a36ae1 100644 --- a/docs/user-manual.zh-CN.md +++ b/docs/user-manual.zh-CN.md @@ -2,7 +2,8 @@ [English](./user-manual.md) | [中文](./user-manual.zh-CN.md) -> 本文档面向终端用户。面向 Claude Code / Codex 等编程代理的执行手册见仓库根目录的 `CLAUDE.md`。 +> [!NOTE] +> 本文档面向终端用户。面向 Claude Code / Codex 等编程代理的执行手册见仓库根目录的 [CLAUDE.md](../CLAUDE.md)。 Code Manager 是面向 Claude Code 用户的本地桌面管理工具。它把 `~/.claude` 目录、配置、供应商、记忆、Skills、历史、统计、Token 用量、项目状态、系统托盘和诊断日志集中到一个 Tauri 应用中，帮助你用更可见、可预览、可验证的方式维护 Claude Code 本地配置。 @@ -32,327 +33,362 @@ Code Manager 是面向 Claude Code 用户的本地桌面管理工具。它把 `~ ### 配置 -配置是最终可以应用到 `~/.claude/settings.json` 的用户配置，通常包含认证密钥、API 地址、默认模型、权限、Sandbox、Hooks、插件、状态行等字段。配置可以引用一个内置供应商；应用配置时，Code Manager 会把供应商的 `env`（地址与模型映射）和配置自身配置合并，生成最终 JSON 并写入 `~/.claude/settings.json`。 +配置是最终可以应用到 `~/.claude/settings.json` 的用户配置集，包含认证密钥、API 连接地址、默认模型、权限控制、Sandbox、Hooks、插件列表以及状态行等完整选项。 -如果本机已有 `~/.claude/settings.json`，配置页可在未创建配置时识别并导入为托管配置。已应用配置后，如果真实 `settings.json` 被外部修改，页面会显示差异提示，可查看 diff 后选择接受实际配置或重新应用托管配置。 +- **供应商联动**：配置可以引用一个内置供应商。应用配置时，Code Manager 会将供应商的预置环境变量（服务地址与模型映射）与配置自身的选项合并，生成标准 JSON 并安全写入 `~/.claude/settings.json`。 +- **自动接管**：如果本机已存在现有的 `~/.claude/settings.json`，在尚未创建任何配置时，配置页会自动识别并支持一键导入为受管配置。 +- **外部变更感知**：当激活的配置被外部编辑器修改导致内容不一致时，配置页会弹出差异提示，你可以对比 Diff 后选择「接受实际配置」写回托管记录，或选择「重新应用」覆盖外部改动。 ### Provider（供应商） -供应商只承载供应商客观信息（连接地址、模型映射与可选附加环境变量），不含认证密钥，且均为内置只读、不可自定义。配置引用供应商后，配置中的同名字段会覆盖供应商的 `env`（地址除外：地址以供应商为单一事实源）。完整内置清单见 [供应商 Provider](#供应商-provider) 章节。 +供应商承载客观的服务端点信息（API 连接地址、官方模型映射及附加环境变量），不包含任何私有认证密钥，且全部为内置只读，不支持自定义新增。 + +- **覆盖规则**：配置引用供应商后，配置中定义的同名字段会覆盖供应商的预置环境变量（连接地址除外：连接地址以供应商预置为单一事实源）。 +- 完整内置供应商清单参见 [供应商 Provider](#供应商-provider) 章节。 ### 记忆 -记忆对应 Claude Code 用户级 `CLAUDE.md` 和 `~/.claude/rules/*.md`，启用后写入真实 Claude Code 目录。 +记忆对应 Claude Code 的用户级系统指令文件 `~/.claude/CLAUDE.md` 与规则目录 `~/.claude/rules/*.md`，启用后才会同步写入到真实磁盘目录。 -- `CLAUDE.md`：同一时间只能启用一条，适合长期主记忆。 -- Rules：可同时启用多条，保存到 `~/.claude/rules/`，可配置 `paths` frontmatter 做路径匹配。 +- **`CLAUDE.md`**：主记忆文件，全局同一时间只能启用一份，适合作为长期稳定的主指令基线。 +- **Rules 规则**：模块化规则文件，可同时启用多份，保存在 `~/.claude/rules/` 下，支持在文件头配置 `paths` glob 进行路径匹配过滤。 ### Skills -Skills 对应 `~/.claude/skills//SKILL.md`。启用的 Skill 保存在 `~/.claude/skills/`；禁用的 Skill 移到 Code Manager 的 `skills-disabled/` 目录。软链接 Skill 可以导入和启停，但内容只读，需要在源目录维护。 +Skills 对应 Claude Code 的自定义技能扩展，位于 `~/.claude/skills//SKILL.md`。 + +- **启停机制**：启用的 Skill 保存在 `~/.claude/skills/`；禁用的 Skill 会安全移至 Code Manager 应用数据目录下的 `skills-disabled/` 归档。 +- **软链接管理**：支持导入软链接形式的 Skill，可以正常启停切换，但由于源目录位于外部，其正文内容为只读，需在源目录中进行编辑。 ### Stats 与 Usage 的区别 -- 使用统计页读取 `~/.claude.json`，展示 Claude Code 本地统计快照（启动次数、工具调用、Skill 使用、各项目最近一次会话）。 -- Token 用量页扫描 `~/.claude/projects/**/*.jsonl` 与 `subagents/*.jsonl`，按日期、项目、会话、模型聚合 Token 与费用，并用 SQLite 做增量缓存。 +两者的数据源与统计口径截然不同： + +- **使用统计（Stats）**：直接读取 `~/.claude.json` 中的本地统计快照，呈现累计启动次数、工具调用频次、Skill 使用量以及各项目最近一次会话概要。 +- **Token 用量（Usage）**：增量扫描 `~/.claude/projects/**/*.jsonl` 与 `subagents/*.jsonl` 会话日志，基于 SQLite 缓存按日期、项目、会话与模型多维度聚合 Token 用量与成本支出。 -两者数据源与口径不同。排查费用或 Token 时，优先使用 Token 用量页。 +> [!TIP] +> 排查费用消耗或准确 Token 统计时，请优先参考「Token 用量」页面。 ## 快速开始 -1. 从项目 Release 页面下载当前平台安装包，安装并启动。 -2. 首次启动后，应用会读取本机 `~/.claude`、`~/.claude.json` 和 `~/.claude/projects/`。 -3. macOS 首次打开如果被系统拦截，可执行 `xattr -rd com.apple.quarantine /Applications/code-manager.app` 移除隔离属性。 +1. **获取安装包**：从 GitHub Release 页面下载当前平台的安装包，安装并启动。 +2. **首次启动检测**：启动后，应用会自动读取本机现存的 `~/.claude`、`~/.claude.json` 和 `~/.claude/projects/`。 +3. **macOS 隔离放行（可选）**：若首次打开遇到 Gatekeeper 拦截，可在终端执行 `xattr -rd com.apple.quarantine /Applications/code-manager.app` 移除隔离属性。 -建议首次配置顺序： +推荐的首次配置流： -1. 打开左下角设置，选择界面语言、主题、默认终端和默认编辑器。 -2. 进入配置页新建配置，在「供应商」选项处选择合适的内置供应商。 -3. 填写认证密钥和模型配置。 -4. 点击测试模型确认 API 地址、Token 和模型可用。 -5. 点击启用将配置应用到 `~/.claude/settings.json`。 -6. 进入目录总览确认 `settings.json` 写入符合预期。 +1. **基础环境偏好**：打开左下角「设置」，选择界面语言、主题风格、默认终端与编辑器。 +2. **创建 Profile**：进入「配置」页新建配置，在「供应商」选项中选择匹配的内置服务商。 +3. **填入 API 凭据**：填入对应的 API 密钥并确认模型参数。 +4. **测试连通性**：点击「测试模型」，验证连接地址、Token 密钥与模型是否通信正常。 +5. **一键生效应用**：点击「启用」，将当前配置安全写入 `~/.claude/settings.json`。 +6. **目录总览核验**：进入「`~/.claude` 目录总览」，确认文件生成与内容符合预期。 ## 主界面导航 -| 入口 | 用途 | +| 入口 | 说明 | | --- | --- | -| `AI` | 打开或收起 `~/.claude` 目录总览 | -| 配置 | 管理配置，生成并应用 Claude Code 用户设置 | -| 记忆 | 管理 `CLAUDE.md` 与 `rules/*.md` | -| Skills | 管理 Claude Code Skills | -| 项目 | 查看 Claude 项目路径、Git 状态、worktree、项目级 `.claude/` 与 AGENTS / Skills 配对状态 | -| 历史 | 查看 `~/.claude/history.jsonl` 中的历史输入与会话详情 | -| 统计 | 查看 `~/.claude.json` 中的本地统计快照 | -| 用量 | 查看 `~/.claude/projects/` 中的 Token 与费用聚合 | -| 速查表 | 侧边栏底部入口，查看 Claude Code 快捷键、斜杠命令、配置与环境变量等速查内容 | -| 设置 | 调整语言、主题、托盘、默认终端、默认编辑器和诊断入口 | - -多数页面的新增或编辑操作会打开右侧抽屉，支持控件模式、JSON 模式或预览。配置、记忆和 Skill 编辑器存在未保存更改时，关闭或切换会提示保存、丢弃或继续编辑。 +| `AI` | 打开或收起 `~/.claude` 目录树总览与文件预览 | +| **配置** | 管理配置 Profiles，生成并一键应用 Claude Code 用户设置 | +| **记忆** | 集中管理用户级 `CLAUDE.md` 与 `rules/*.md` 规则 | +| **Skills** | 管理 Claude Code 自定义技能扩展 | +| **项目** | 查看 Claude 项目路径、Git 分支、Worktree、项目级 `.claude/` 与规则配对状态 | +| **历史** | 查看 `~/.claude/history.jsonl` 中的历史交互输入与会话详情 | +| **统计** | 读取 `~/.claude.json` 本地统计快照 | +| **用量** | 扫描 `~/.claude/projects/` 聚合计算 Token 消耗与费用趋势 | +| **速查表** | 位于侧边栏底部，提供 Claude Code 快捷键、斜杠命令、配置与环境变量速查 | +| **设置** | 调整界面语言、主题、托盘会话显示、默认终端/编辑器与系统诊断 | + +多数页面的新增或编辑操作会拉出右侧抽屉，支持表单控件模式、JSON 模式与实时预览。当编辑器存在未保存更改时，关闭或切换页面均会弹出退出保护提示，避免误丢改动。 ## `~/.claude` 目录总览 -点击左上角 `AI` 入口进入。右侧目录树选择文件后，左侧预览区会打开标签页：Markdown 默认显示渲染预览（可切换源码），其他文本显示源码，二进制只显示元信息。预览底部展示文件大小、修改时间、编码与截断状态。 +点击左上角的 `AI` 入口即可打开目录总览： -文件预览工具栏可复制绝对路径、在文件浏览器中定位、用默认编辑器打开；目录树右键可新建文件、新建文件夹、重命名、删除。删除不可撤销，处理 `settings.json`、`CLAUDE.md`、`rules/` 或 `skills/` 前请确认副本。 - -目录总览列出 `~/.claude` 下的路径（含软链接）。软链条目有明确标记且可只读打开：目录软链可展开，文件预览可跟随指向 `~/.claude` 外的目标。新建、重命名、删除在任何经过软链的路径上均不可用。扫描仍会跳过 `node_modules`；达到条目数或深度上限时显示提示。二进制预览按已知扩展名黑名单判定，其余文件以 UTF-8 / 有损 UTF-8 文本打开。 +- **文件浏览与预览**：在右侧目录树选择文件后，左侧工作区将打开对应预览标签页。Markdown 文件默认展示排版渲染（支持切换查看源码），代码文本展示高亮源码，二进制文件展示格式与元数据。预览底部常驻文件大小、修改时间、字符编码与截断状态。 +- **快捷工具与文件操作**：工具栏支持一键复制绝对路径、在系统文件浏览器中定位、调用默认编辑器打开。在目录树中右键可新建文件、新建文件夹、重命名或删除。 + > [!WARNING] + > 目录删除操作不可逆。在操作 `settings.json`、`CLAUDE.md`、`rules/` 或 `skills/` 时，请务必提前确认已有安全备份。 +- **软链接保护机制**：目录总览完整列出 `~/.claude` 下的文件与软链接。软链接带有明显标签且支持只读查看；为防止误改外部目录，任何经过软链接的路径均禁用新建、重命名与删除操作。扫描自动忽略 `node_modules`，并在超出深度或条目上限时给出提示。 ## 配置 -配置页是管理 Claude Code settings 的主入口。 +配置页是统一管理 Claude Code 配置项的核心控制台。 ### 配置列表 -卡片展示名称、描述、是否已应用、主要模型、努力级别、权限模式、Sandbox 状态、插件摘要和最近一次模型测试结果。可执行新建、启用（写入 `~/.claude/settings.json`）、复制环境变量（生成 `export KEY="value"` 文本）、导出配置文件（可选含 / 排除认证密钥，落盘前预览最终 JSON）、复制副本、编辑、删除、一键测试所有配置、拖拽排序。已启用的配置还可一键"同步常用选项与插件到其他配置"，把当前配置的常用选项、插件市场和已启用插件复制到其余配置，便于团队统一基线。 +卡片集中呈现每个 Profile 的核心状态：名称、描述、生效状态、主力模型、思考程度（Effort）、权限模式、Sandbox 状态、已启用插件摘要以及最近一次连通性测试结果。 -当配置页发现未托管的 `~/.claude/settings.json` 且尚无配置时，会显示导入卡片。导入会原地接管当前 settings 内容，不会立即改写文件。已绑定配置与真实 settings 不一致时，卡片会显示差异入口：选择"接受实际配置"会把当前文件内容写回配置；选择"重新应用"会用配置解析结果覆盖 `settings.json`。 +- **丰富操作**：支持新建、启用（写入 `~/.claude/settings.json`）、复制环境变量文本（生成标准的 `export KEY="value"` 格式）、导出配置（可选是否携带认证密钥，并在落盘前预览最终 JSON）、克隆副本、编辑、删除以及拖拽排序。 +- **一键测试全量配置**：支持对所有托管配置执行批量连通性检测。 +- **团队基线同步**：在已启用的配置上，支持一键「同步常用选项与插件到其他配置」，快速将基线开关、市场配置与插件状态同步给其余 Profile。 +- **外部变更与差异比对**：当检测到未托管的 `~/.claude/settings.json` 时会引导一键导入。若已绑定的文件被外部程序修改，卡片会提示 Diff 差异，支持选择「接受实际配置」反向更新托管数据，或选择「重新应用」强行覆写。 ### 新建或编辑配置 -右侧配置编辑器分多块。 - -- **基础信息**：名称（必填）、描述、可选供应商（选择后自动带入连接地址与模型映射）。 -- **认证**：认证密钥写入 `env.ANTHROPIC_AUTH_TOKEN`;API 地址写入 `env.ANTHROPIC_BASE_URL`，未设置时模型测试使用 Anthropic 官方地址。 -- **模型与行为**：默认模型（可输入下拉框，候选取自当前供应商的模型，也可手工输入自定义模型）、努力级别（`auto`/`low`/`medium`/`high`/`xhigh`/`max`）、Opus / Sonnet / Haiku 默认模型（同为可输入下拉框）、Subagent 模型、回复语言、输出风格。 -- **常用选项**：覆盖深度思考、Thinking 摘要、Fast Mode、禁用 Hooks、禁用 AI 署名、LSP 工具、Tool Search、新版 Init、无闪烁、子进程凭据清理、Agent Teams 等 Claude Code 常用开关。具体可在编辑器内查看。 -- **环境变量**：维护除认证和常用选项外的 `env` 键。重复键、非法 JSON 或未保存的行编辑会阻止保存。 -- **权限**：默认模式、禁用 `bypassPermissions`、允许 / 拒绝 / 询问规则、附加目录、推荐规则预设。 -- **Sandbox**：可启用或关闭，可添加推荐预设；复杂配置可切换 JSON 模式。 -- **Hooks**：维护 Claude Code hooks，支持摘要展示，可添加内置乱码检查预设，复杂结构可切 JSON 模式。 -- **插件市场**：维护 `extraKnownMarketplaces`，支持官方市场（`claude-plugins-official`）与社区市场（`claude-community`，仓库 `anthropics/claude-plugins-community`）内置预设，可从市场配置或浏览市场一键添加；每个 Marketplace 需完整填写 ID、来源、仓库或 URL、路径、包名、安装位置。 -- **插件**：维护 `enabledPlugins`，分"已配置"和"浏览市场"两个 Tab。浏览市场目前仅支持 `github` 来源，可按 Marketplace / 启用状态 / 类别 / 来源筛选，点击启用会立即同步到已配置列表。列表请求和安装数刷新分别在 30 秒后超时；来源失败会单独提示，本地缓存写入失败仍会展示已下载的列表。 -- **状态行**：配置自定义状态行命令，可启用默认状态行预设（非 Windows 写入 `~/.claude/statusline.sh`,Windows 写入 `~/.claude/statusline.ps1` 并自动设置 PowerShell 调用命令），同时写入 60 秒刷新间隔，使缓存有效期等倒计时在空闲时也能更新；目标已存在且内容不同时会提示是否覆盖。 -- **最终配置**：预览供应商与配置合并后的最终 JSON；源 JSON 模式可直接维护整个 settings 对象，预览自动加入 schema 地址。 +右侧配置抽屉按职责拆分为结构化模块： + +- **基础信息**：配置名称（必填）、描述说明、关联供应商（选择后自动注入服务地址与模型映射）。 +- **认证凭据**：填写认证密钥（写入 `env.ANTHROPIC_AUTH_TOKEN`）与服务 Base URL（写入 `env.ANTHROPIC_BASE_URL`，留空时默认走 Anthropic 官方端点）。 +- **模型与行为**：默认模型（提供可输入下拉框，预置当前供应商推荐模型，也支持手动输入任意模型）、思考程度（Effort，可选 `auto`/`low`/`medium`/`high`/`xhigh`/`max`）、Opus / Sonnet / Haiku 映射模型、Subagent 子代理模型、回复语言偏好与输出样式。 +- **常用功能开关**：可视化开关深度思考（Deep Thinking）、Thinking 摘要展示、Fast Mode、禁用 Hooks、禁用 AI 署名、LSP 工具支持、Tool Search、新版 Init、无闪烁模式、子进程凭据脱敏以及 Agent Teams 等核心参数。 +- **环境变量**：集中维护自定义 `env` 键值对。内置防重校验与 JSON 格式检查，编辑未保存时会阻断提交。 +- **权限控制**：默认权限模式、禁用 `bypassPermissions` 开关、设置允许/拒绝/确认规则清单，支持添加目录信任与一键载入推荐规则预设。 +- **Sandbox 沙箱**：沙箱启闭开关，支持载入推荐预设，复杂需求可无缝切换至高级 JSON 模式。 +- **Hooks 钩子**：维护各阶段钩子脚本并展示摘要，内置常见乱码排查预设，支持切换 JSON 模式。 +- **插件市场**：维护 `extraKnownMarketplaces`，预置官方插件市场（`claude-plugins-official`）与社区市场（`claude-community`）配置模板，支持从界面一键导入。 +- **插件管理**：管理 `enabledPlugins`，包含「已配置」和「浏览市场」双标签页。支持按市场、启用状态、分类多维检索，开启后即时同步；网络请求与安装计数均设超时保护。 +- **状态行（Statusline）**：配置自定义状态栏输出脚本，内置默认状态行预设（macOS/Linux 写入 `~/.claude/statusline.sh`，Windows 写入 `~/.claude/statusline.ps1` 并自动配置 PowerShell 执行指令），附带 60 秒定时刷新保证缓存倒计时准确。 +- **最终配置预览**：实时预览供应商预置与配置选项合并后的完整 JSON；同时提供源码编辑模式直接修改完整 settings 对象。 ### 模型测试 -点击测试模型后，会按当前编辑内容发起请求。结果对话框展示是否成功、使用模型与返回模型、请求地址、状态码、耗时、请求 ID、停止原因、输入提示词、返回内容、请求 / 响应 Headers、请求体、原始响应，以及复制 cURL 和修改提示词重测。 +点击「测试模型」会基于当前编辑内容即时向模型端点发起验证请求： -模型测试需要有效的 `ANTHROPIC_AUTH_TOKEN` 和可访问的模型 API。部分网关（如 OpenCode Go）要求客户端按会话声明标识头，模型测试会为每次请求自动生成并带上，无需手工配置。 +- **全面诊断**：测试结果弹窗详细展示连通状态、实际调用与返回模型名称、服务端点、HTTP 状态码、请求耗时、Request ID、停止原因、输入/输出文本、完整 Header 标头、请求 Body 及原始响应报文。 +- **实用操作**：支持一键复制等价 cURL 命令在终端重现，或现场修改 Prompt 快速复测。 +- **网关兼容**：对于要求按会话声明标识头的网关（如 OpenCode Go），测试器会自动生成并注入合法标头，无需繁琐的手动配置。 ### 深度链接导入 -可用系统 URL 把一份 Claude settings 送进 Code Manager 做预览导入，scheme为 `code-manager://profiles/import`。 - -- **两种来源（互斥）**：内嵌 `payload=`（base64url 编码的裸 settings JSON，解码后约 16KB 上限），或远端 `url=`（仅 HTTPS，应用拉取后导入；有 SSRF 防护与体积/跳转限制）。 -- **可选参数**：`name`、`description` 仅用于预填导入对话框。 -- **不自动启用**：解析成功后会切到配置页并打开与文件导入相同的预览对话框；确认后**新建配置**，`providerId` 为空，且**不会**自动写入或绑定 `~/.claude/settings.json`。 -- **密钥**：若载荷含认证类字段，须勾选风险确认后才能导入。从已有配置「复制 Deep Link」时默认不含密钥；显式包含密钥时同样需勾选确认。 -- **多条排队**：连续打开多条链接会排队处理；关闭预览或导入成功后继续下一条。离开配置页再回来，未确认的链接仍会恢复（权威队列在应用后端）。 +支持通过系统自定义 URL Scheme 将 Claude 配置直接拉起并导入 Code Manager，格式为 `code-manager://profiles/import`。 -macOS / Windows / Linux 在安装包场景下均可注册 scheme；开发态下 Linux/Windows 可能需额外注册。 +- **两种数据源（互斥）**： + - **内嵌载荷**：`payload=`（base64url 编码的纯 settings JSON，限制解码后约 16KB 上限）。 + - **远端获取**：`url=`（仅限 HTTPS 地址，应用拉取后导入，内置 SSRF 防护与重定向限制）。 +- **预填参数**：可选附带 `name` 与 `description` 预填导入弹窗。 +- **安全不自动激活**：链接解析成功后进入配置预览对话框；用户确认后**创建新 Profile**（`providerId` 为空），**绝对不会**自动覆写或直接生效至 `~/.claude/settings.json`。 +- **敏感密钥防护**：若导入载荷中包含鉴权凭据，必须由用户显式勾选安全风险确认后才允许导入。从已有配置复制 Deep Link 时默认排除密钥。 +- **可靠排队机制**：连续调起多条链接时自动进入后台队列排队，页面切换不会丢失未确认的导入请求。 ## 供应商 Provider -供应商均为内置且只读，只承载供应商客观信息（连接地址 `ANTHROPIC_BASE_URL`、模型映射与可选附加环境变量），不含认证密钥。当前覆盖 Anthropic、DeepSeek、智谱 GLM Coding Plan、Kimi Code Plan、MiniMax Token Plan、小米 MiMo Token Plan、OpenRouter、火山方舟 Coding Plan、万界方舟、OpenCode Go 和 Ollama。 +所有供应商均为**内置只读**设计，仅包含标准的服务端点信息（`ANTHROPIC_BASE_URL`、模型名映射及必要的基础环境变量），不包含任何私有 API 密钥。 -不支持自定义供应商。在配置编辑器的「供应商」选项处选择一个内置供应商后，其连接地址与模型映射会自动带入；你只需补充认证密钥与行为设置。点击该选项下方的「查看内置供应商」可打开只读一览，查看每个供应商的名称、ID、API 地址、官方文档链接、推荐模型和客户端会话标识头（若该网关要求）。 +- **生态覆盖**：涵盖 Anthropic、DeepSeek、智谱 GLM Coding Plan、Kimi Code Plan、MiniMax Token Plan、小米 MiMo Token Plan、OpenRouter、火山方舟 Coding Plan、万界方舟、OpenCode Go 以及 Ollama 本地部署。 +- **使用方式**：在配置抽屉的「供应商」下拉框中直接选择，端点与推荐模型将自动填入；点击选项下方的「查看内置供应商」可打开只读速查抽屉，查看各厂商文档、端点及推荐模型。 ## 记忆管理 -记忆页用于管理用户级 Claude Code 指令。 +记忆页面专用于集中维护 Claude Code 用户级系统指令。 -页面顶部会在没有主记忆时显示 Karpathy 行为指南预设，可一键创建并启用为 `CLAUDE.md`。在编辑现有 `CLAUDE.md` 类型记忆时，也可把该预设追加到当前内容底部；Code Manager 会通过预设 marker 防止重复插入，并提供原仓库入口便于查看来源。 - -**新增记忆**：点击添加记忆，填写名称，选择类型（`CLAUDE.md` 写入 `~/.claude/CLAUDE.md`，同时只能启用一个；Rules 写入 `~/.claude/rules/.md`，可同时启用多个，支持 `paths` glob 匹配），编写 Markdown 内容并保存。在列表中启用后，真实文件才会写入 `~/.claude`。 - -**编辑、复制和删除**：编辑会更新管理内容，启用状态下同步写真实文件；复制会创建未启用副本；删除会移除管理记录并清理不再需要的 rule 目录。 - -**导入本地记忆**：Code Manager 会识别 `~/.claude/CLAUDE.md` 和 `~/.claude/rules/*.md` 中尚未导入的文件，点击"导入管理"原地接管，不立即改写内容。软链接记忆不支持导入，路径已被占用需要先处理冲突。 - -**从目录导入**：点击导入记忆后选择包含 `CLAUDE.md` 或 `rules/` 的目录，导入后默认未启用。常见跳过原因：重复 `CLAUDE.md`、同路径 Rule 已存在、路径无效、读取失败、软链接不支持。 +- **Karpathy 行为指南预设**：当尚未配置主记忆时，页面顶部会呈现 Karpathy 行为指南推荐卡片，支持一键创建并启用为 `CLAUDE.md`。在编辑已有的 `CLAUDE.md` 时，亦支持将该指南一键追加至文末（内置防重复追加标记）。 +- **新增记忆**：填写记忆名称，选择类型（`CLAUDE.md` 写入 `~/.claude/CLAUDE.md`，全局单例启用；Rules 写入 `~/.claude/rules/.md`，可多选同时启用并支持 `paths` glob），编写 Markdown 正文后保存。只有在列表中点击「启用」，文件才会真正写入磁盘。 +- **日常维护**：支持更新内容、克隆禁用副本、安全删除无用规则目录。 +- **接管与导入**： + - **本地识别**：自动探测 `~/.claude` 下未受管的 `CLAUDE.md` 与 `rules/*.md`，支持一键原地接管。 + - **批量目录导入**：选择外部包含指令文件的目录进行批量导入，默认以禁用状态存入；自动跳过重复项或无效软链接。 ## Skills 管理 -Skills 页管理 `~/.claude/skills/` 下的 Claude Code Skill。 - -**新增 Skill**：点击添加 Skill，填写 Skill 名称（目录名 / slash command，只允许小写字母、数字和连字符）、显示名称、描述，编写 `SKILL.md` 正文。可设置"仅手动触发"（写入 `disable-model-invocation`）和"允许手动调用"。 +Skills 页面统一管理 `~/.claude/skills/` 下的 Claude Code 技能包。 -**列表操作**：每个 Skill 支持启用 / 禁用、编辑 `SKILL.md`、删除、用外部编辑器打开目录、同步到 `~/.codex/skills`。启用对应 `~/.claude/skills//`，禁用对应应用数据目录下的 `skills-disabled//`。 - -**导入 Skills**：可选择单个 Skill 目录、Skill 软链接或包含多个 Skill 的集合目录。跳过原因包括名称不符合规则、同名已存在、缺少有效 `SKILL.md` 或软链接目标无效。软链接 Skill 显示只读提示，可启停和打开源目录，但不能在应用内修改内容。 - -**支持文件**：编辑器会展示 `SKILL.md` 以外的支持文件树。目前只展示目录树，需要修改时请用外部编辑器打开 Skill 目录。 +- **新增技能**：录入 Skill 唯一标识符（目录名 / slash 命令名，仅允许小写字母、数字和中划线）、显示名称、功能描述，并编写 `SKILL.md` 正文。支持按需开启「仅手动触发」（写入 `disable-model-invocation`）或「允许手动调用」。 +- **状态维护与归档**： + - **启用**：存放在 `~/.claude/skills//`。 + - **禁用**：安全移至应用数据目录的 `skills-disabled//` 隔离保存，不污染 Claude 工作区。 + - 支持一键同步软链接至 `~/.codex/skills`。 +- **导入技能**：支持导入单个 Skill 目录、Skill 软链接或包含多个技能的集合目录。软链接技能带有只读提示，可在应用内启停或打开源目录，但不允许直接修改内容。 +- **辅助资源树**：编辑器支持查看 `SKILL.md` 之外的脚本与模板资源树；修改辅助文件支持一键唤起外部编辑器。 ## 项目管理 -项目页从 `~/.claude/history.jsonl` 中提取项目列表，按最近活跃排序。项目详情同时读取项目真实目录，展示 Git、worktree、项目级 Claude 配置和本地清理入口。 +项目页从 `~/.claude/history.jsonl` 中自动提取项目索引，按最近活跃时间倒序排列。进入项目详情时会结合本地实际工作区读取 Git 仓库、Worktree、项目级 Claude 配置与状态。 ### 项目列表与详情 -左侧列表展示项目短名称、路径、最近活跃时间、会话与输入数量、最近会话 ID。点击项目后，右侧展示详情。 +左侧列表展示项目缩写、磁盘路径、最近活跃时间、会话与交互总数及最近 Session ID。点击即可进入右侧详情视图。 ### 快捷操作 -- 用终端打开项目：使用设置中的默认终端，选项会按当前平台和本机已安装情况过滤。 -- 用编辑器打开项目：需要先在设置中选择默认编辑器，选项会按平台和安装情况过滤。 -- 打开源码仓库：使用项目 Git 远程地址。 +- **终端打开**：根据「设置」中配置的默认终端唤起，智能结合当前操作系统与本地已安装程序。 +- **编辑器打开**：调用「设置」中预设的默认代码编辑器打开工作区。 +- **访问远端仓库**：解析 Git Remote URL 并在默认浏览器中打开对应代码托管页。 ### 编辑器与终端支持矩阵 -| 应用 | macOS | Linux | Windows | +| 工具类型 | macOS | Linux | Windows | | --- | --- | --- | --- | -| VS Code | 支持 | 需 `code` CLI | 需 `code` CLI | -| Zed | 支持 | 需 `zed` CLI | 需 `zed` CLI | -| Terminal | Terminal.app | 依次尝试 `$TERMINAL`、`xdg-terminal-exec`、`x-terminal-emulator` 等 | 依次尝试 Windows Terminal、PowerShell、cmd | -| iTerm | 支持 | 不支持 | 不支持 | -| Ghostty | 支持 | 需 `ghostty` CLI | 暂不支持 | +| VS Code | 原生应用打开 | 需安装 `code` CLI | 需安装 `code` CLI | +| Zed | 原生应用打开 | 需安装 `zed` CLI | 需安装 `zed` CLI | +| 系统终端 | Terminal.app | 依次回退 `$TERMINAL`、`xdg-terminal-exec`、`x-terminal-emulator` | 依次回退 Windows Terminal、PowerShell、cmd | +| iTerm2 | 完整支持 | 不支持 | 不支持 | +| Ghostty | 完整支持 | 需安装 `ghostty` CLI | 暂不支持 | ### 状态检查 -详情页展示：目录是否存在、是否 Git 仓库、`CLAUDE.md` / `AGENTS.md` 配对状态、`.claude/skills` / `.agents/skills` 配对状态、项目级 `.claude/` 概览、本地分支与最近提交、Worktree 路径与状态、最近活跃时间、会话与输入数量、最近会话 ID、Git 根目录，以及最近 5 个会话（可点击查看详情）。快捷操作支持打开终端、打开编辑器、打开源码仓库、跳转该项目历史和跳转该项目 Token 用量。 +项目详情页提供全面的健康状态诊断： +- 目录与 Git 仓库状态、当前分支与最近提交记录、Worktree 路径与检出状态。 +- `CLAUDE.md ↔ AGENTS.md` 互联状态、`.claude/skills ↔ .agents/skills` 技能目录配对状态。 +- 最近会话列表（支持点击直接下钻查看交互回放）。 +- 快速跳转：一键直达该项目的历史记录页或该项目的 Token 用量页。 ### 项目级 Claude 配置 -项目级 Claude 管理分三组： - -- Memory 文件：`CLAUDE.md ↔ AGENTS.md` 双向配对。任一端是真文件时，可创建另一端的相对软链接；两端都不存在、普通文件冲突或孤儿软链时不会自动处理。 -- 项目级 Skills:`.claude/skills ↔ .agents/skills` 双向配对。任一端是真目录时，可创建另一端相对软链接；两端都是真目录时需手动合并。 -- 项目 `.claude/` 目录：可打开右侧 Sheet 浏览、预览和用外部编辑器打开项目级 Claude 文件。`settings.json` 与 `settings.local.json` 支持一键创建；其它项目级文件可预览或外部打开，不在项目抽屉中创建、删除或重命名。 +针对多 Agent 协同与项目级配置提供三大能力： +- **记忆配对**：`CLAUDE.md ↔ AGENTS.md` 双向相对软链接配对，保证不同 AI 工具均能读取规范约定。 +- **技能配对**：`.claude/skills ↔ .agents/skills` 技能目录软链接互联。 +- **项目级 `.claude/` 管理**：在右侧抽屉中浏览与预览项目级 Claude 文件，支持一键新建 `settings.json` 与 `settings.local.json`。 ### 分支与 Worktree 清理 -项目详情可检测已合并或远端已删除且可安全清理的本地分支与 worktree。清理始终分两步：先生成 preview 列表并由用户选择，确认后才执行删除；后端只会清理 preview 中列出的条目。 +自动扫描本地已合并或远端已删除的无用分支与孤立 Worktree。 +- **安全两阶段操作**：先生成可供勾选的待删除预览清单，用户确认后才会执行物理删除，后端绝不清理未在清单中的条目。 ### 清除项目本地数据 -在项目列表项右键选择清除本地数据。应用会先生成 dry-run 删除计划，确认后才执行。该操作调用 Claude CLI 清除项目保存的本地状态，执行前请仔细检查计划。 +在项目列表右键选择「清除本地数据」，应用会先展示由 Claude CLI 评估的 Dry-run 删除规划，经过用户确认后才执行，安全清理 Claude CLI 遗留的本地会话状态缓存。 ## 使用历史 -历史页读取 `~/.claude/history.jsonl`，用于回看历史输入和会话。 +历史页直接解析 `~/.claude/history.jsonl`，用于快速复盘历史输入提示与完整交互会话。 -左侧按项目分组，顶部热力图展示最近历史密度，搜索框按展示文本过滤，点击会话打开详情抽屉。URL 同步 `project`、`q` 和 `session` 参数，便于保留筛选状态。 - -会话详情展示用户消息、助手消息、思考摘要、工具调用与返回、命令、图片、计划内容和系统事件。可复制项目路径、会话 ID、单条消息，或用编辑器打开原始会话记录文件。 +- **检索与过滤**：左侧按项目聚合归类；顶部展示近期交互密度的热力图；搜索框支持按文本全文检索；URL 同步维护 `project`、`q` 与 `session` 参数，方便随时收藏与分享过滤状态。 +- **会话交互回放**：会话详情抽屉完整还原交互时序，清晰标注用户 Prompt、助手响应、Thinking 深度思考摘要、工具调用与执行返回、Shell 命令、附带图片、Plan 规划步骤及系统通知事件。 +- **实用操作**：支持复制路径、Session ID、单条消息正文，或直接在外部编辑器中打开原始 `.jsonl` 文件。 ## 使用统计 -统计页读取 `~/.claude.json`，展示本地统计快照（不是实时计算结果）。 - -页面提供启动次数、首次使用日期、项目数、上次 Plan Mode 使用时间、`btw` 使用次数、工具调用次数图表、Skill 使用次数列表、项目最近会话列表。每个项目最近会话展示最近费用、会话时长、新增 / 删除行数、各类 Token、Web 搜索次数、模型明细、首条 Prompt、frame 和 Hook 性能指标。 +统计页直接读取 `~/.claude.json` 中的本地统计快照（非实时运行时计算结果）。 -顶部可刷新数据，或用默认编辑器打开 `~/.claude.json`。 +- **概览数据**：呈现累计启动次数、首次使用日期、管理项目总数、上次 Plan Mode 运行时间与 `btw` 调用次数。 +- **图表与排行**：内置工具调用频次柱状图、Skill 使用热度排行。 +- **最近活跃记录**：列出每个项目最近一次会话的详细指标，包括费用估算、会话时长、增删代码行数、各项 Token 构成、Web 搜索次数、调用模型及首条 Prompt。 ## Token 用量统计 -用量页扫描 `~/.claude/projects/**/*.jsonl` 和 `subagents/*.jsonl`，提取 assistant 消息的 usage 字段，按价格表估算费用。 +用量页深入扫描 `~/.claude/projects/**/*.jsonl` 与 `subagents/*.jsonl`，提取助手响应中的 `usage` 载荷，结合权威价格表核算 Token 与实际费用支出。 ### 数据口径 -- 按 `message.id` 全局去重；同一消息出现多次时保留 Token 用量更大的快照。 -- Token 包含输入、输出、缓存创建和缓存读取；成本按 USD / 1M tokens 单位估算。 -- 价格表加载顺序：本地缓存 `model-pricing.json` → 内置 Anthropic 兜底表 → 启动或手动刷新时从 models.dev 更新。 -- models.dev 只导入官方 provider 价格：Anthropic、Moonshot / MoonshotAI、Z.ai / Zhipu / BigModel、MiniMax、Xiaomi / MiMo、DeepSeek。其中 Kimi、MiMo、GLM、MiniMax、DeepSeek 受设置页"第三方模型计价"开关控制，关闭后费用按 0 计入。 -- 其他无法匹配价格的模型 Token 仍会统计，但成本按 0 计，并进入未知模型列表。 +- **去重逻辑**：按 `message.id` 全局去重；若同一消息在日志中多次出现，优先保留 Token 用量更高的记录。 +- **Token 构成**：涵盖输入（Input）、输出（Output）、缓存写入（Cache Creation）与缓存读取（Cache Read）；费用按 USD / 1M tokens 标准统一折算。 +- **价格加载顺序**：本地缓存 `model-pricing.json` → 内置 Anthropic 官方兜底表 → 启动或手动刷新时从 models.dev 拉取最新行情。 +- **官方厂商收录**：models.dev 仅收录官方 Provider 定价（Anthropic、Moonshot/Kimi、智谱 GLM、MiniMax、小米 MiMo、DeepSeek）。其中国产模型受「设置」中的「第三方模型计价」开关控制，关闭后费用按 0 计入。 +- **未识别模型**：无法匹配价格的模型 Token 正常累计，但费用计为 0 并归入未识别模型列表。 ### 顶部状态与操作 -顶部显示价格来源（内置 / 本地缓存 / models.dev 实时）。操作按钮：刷新价格、查看模型价目表（可按模型搜索查看输入、输出、缓存写入 / 读取价格和当前用量）、重新扫描。 +顶部常驻当前价格表来源指示（内置 / 本地缓存 / models.dev 实时），提供一键刷新行情、查看模型单价表（可检索各模型输入、输出及缓存读写单价）与强制重新扫描按钮。 ### 筛选 -支持按日期范围、快捷范围（今日、最近 7 天、最近 30 天、本周、本月、今年、全部）、项目、模型（含 `claude-*` 聚合）筛选。重置回到今日。 +支持按自定义日期范围、常用快捷周期（今日、最近 7 天、最近 30 天、本周、本月、今年、全部历史）、关联项目以及模型名称（支持 `claude-*` 通配聚合）组合过滤。 ### 图表与表格 -页面包含总花费、总 Token、会话数、消息数、缓存节省、花费趋势、Token 趋势、模型成本占比、Token 构成，以及按日期、项目、会话、模型的明细表格。趋势图支持按模型或 Token 类型拆分、曲线或柱状、天 / 小时 / 5 分钟粒度，可点击图例切换显示，双击图例只显示当前项。在按会话表格中点击会话可打开消息级用量明细。 +- **统计看板**：呈现总支出、总 Token、会话数、交互消息数与 Prompt 缓存节省成本。 +- **多维趋势**：支出趋势图与 Token 趋势图支持按模型或 Token 类型拆分，支持曲线/柱状图切换，提供日 / 小时 / 5 分钟三级粒度，图例支持单选与隔离查看。 +- **明细下钻**：提供按日期、项目、会话、模型汇总的数据明细表；在会话明细中点击特定 Session 可展开单条消息级别的 Token 消耗瀑布流。 ## 桌面用量浮窗 -桌面用量浮窗是一个置顶、半透明、无边框的小窗，在不打开主界面时也能盯住今日用量。开启后它跨所有虚拟桌面（macOS Spaces）常驻、不进任务栏，首次出现在屏幕右下角，拖动后位置会被记住。三个平台均可使用。 +桌面用量浮窗是一个常驻置顶、半透明、无系统边框的轻量桌面小窗，方便在专注编码时不打开主程序即可实时掌控消耗。 -- **展示指标**：实时显示今日用量 KPI，可选成本、Token 总量、缓存命中率、消息数、会话数、Top 模型，默认显示前三项（成本、Token 总量、缓存命中率），可在设置中自定义选择与顺序。 -- **数据刷新**：数据与用量页同源，记录或价格变化时自动刷新。 -- **快捷跳转**：点击浮窗主体可跳转到主界面的用量页。 -- **外观与开关**：不透明度可调，启用开关与指标、不透明度设置都在设置抽屉（见下文「桌面用量浮窗」设置小节）。 +- **系统融合**：跨所有虚拟桌面（macOS Spaces）无缝常驻，不占用任务栏空间，初始位于屏幕右下角，拖拽后自动记忆停靠坐标，全面兼容三大平台。 +- **指标自由定制**：实时刷新今日核心 KPI，可在设置中自由勾选与排序（今日费用、Token 总量、缓存命中率、消息数、会话数、主力模型）。 +- **实时同步**：与用量分析引擎共享同一数据源，日志变动或价格更新时静默刷新。 +- **一键跳转**：点击浮窗主体即刻唤起 Code Manager 并直达用量统计页面。 +- **外观定制**：可在设置中自由调节浮窗整体透明度（30%–100%）。 ## 速查表 -侧边栏底部的「速查表」入口打开 Claude Code 速查页，内容随界面语言切换中文 / 英文，覆盖键盘快捷键、MCP 服务器、斜杠命令、记忆与文件、工作流与技巧、配置与环境变量、技能与代理、CLI 参数和权限模式。右侧目录可跳转到对应章节。 +位于侧边栏底部的「速查表」提供一站式 Claude Code 官方技能与配置速查手册，随系统语言自动适配中英文： +- 涵盖键盘快捷键、MCP 服务器配置、常用斜杠命令（Slash Commands）、记忆规则与文件结构、最佳实践技巧、配置与环境变量、Subagent 协同、CLI 运行参数以及权限模式说明。 +- 侧边附带锚点目录，方便快速跳转查询。 ## 系统托盘与会话聚焦 -Code Manager 常驻系统托盘（菜单栏），菜单分两部分： +Code Manager 默认常驻系统托盘（macOS 菜单栏），分为两大区域： -- 主托盘：切换当前配置、快速跳转到各页面、退出应用。切换配置等价于在配置页启用对应配置。 -- 会话托盘：读取 `~/.claude/sessions/*.json`，按状态汇总当前 Claude 会话（等待输入 / 工作中 / 空闲）。是否显示、字符限制、会话计数样式和待处理呼吸灯都在设置中调整（见下文）。 +- **主菜单区**：快速切换当前激活的 Profile 配置、直达各个功能页面、优雅退出应用。在此处切换配置等价于在配置页点击「启用」。 +- **会话状态区**：实时监控 `~/.claude/sessions/*.json`，按运行状态汇总活跃会话（等待用户输入 / 思考执行中 / 任务完成空闲）。 -**会话聚焦**：在支持的平台点击会话条目，或使用会话聚焦快捷键，可回到对应终端 tab。该能力**仅 macOS** 可用，Terminal.app 与 iTerm2 走 `pid → tty → AppleScript` 精确聚焦，Ghostty 优先按 `tty` 属性匹配，旧版本或 tty 未命中时再按工作目录做唯一兜底。Linux 与 Windows 不支持自动聚焦，点击会话不会切换终端。详见 [平台支持差异](./platform-support.zh-CN.md)。 +### 会话精准聚焦（仅 macOS） -**LED 灯效联动（仅 macOS）**：启用后，会话托盘的红绿状态会镜像到外接 ANTICATER USB 设备灯效，适合不盯着菜单栏时用硬件灯提示会话状态。配置入口在设置的 LED 灯效卡片。 +在支持的平台上，直接点击菜单栏的会话条目或触发「会话聚焦全局快捷键」，即可自动激活并切换至对应的终端 Tab： +- **Terminal.app 与 iTerm2**：基于 `pid → tty → AppleScript` 链路实现 100% 精确的标签页聚焦。 +- **Ghostty**：优先匹配 `tty` 属性，在未命中时按唯一工作目录兜底切换。 +- **平台限制**：Linux 与 Windows 暂不支持自动终端切换。详见 [平台支持差异](./platform-support.zh-CN.md)。 + +### LED 硬件灯效联动（仅 macOS） + +支持将托盘的会话红绿状态实时镜像至外接的 ANTICATER USB 硬件呼吸灯，无需频繁抬头看屏幕即可获得外设光效提醒。 ## 设置与诊断 -设置入口位于左下角。设置抽屉由一列设置卡片组成，以下按卡片在抽屉中的顺序分组说明；标注「仅 macOS」的卡片或选项在 Linux 和 Windows 上不显示。 +设置入口位于主界面左下角，抽屉式单列卡片布局，按顺序包含以下核心设置项： ### 界面 -- 界面语言：中文 / 英文。 -- 主题外观：浅色 / 深色 / 跟随系统。 -- 默认收起侧边栏：启动后侧边栏仅显示菜单图标，窄屏仍会自动收起。 +- **界面语言**：简体中文 / English。 +- **主题外观**：浅色模式 / 深色模式 / 跟随系统设置。 +- **默认收起侧边栏**：启动后侧边栏默认保持紧凑图标模式，提升小屏可用面积。 ### 菜单栏与会话状态 -- 在菜单栏显示当前配置：在托盘图标旁显示当前激活的配置名称；字符数限制可设为关闭、最多 N 字或全展示。 -- 在菜单栏显示当前会话：在独立菜单栏区域显示 Claude 当前会话及状态。 -- 会话计数样式：数字（`🔴 1 🟢 1`）、上标（`🔴¹ 🟢¹`）或紧凑（`🔴¹🟢¹`）。 -- 待处理会话呼吸灯（仅 macOS）：有等待输入的会话时，菜单栏状态做呼吸灯式脉动提示。 -- 会话聚焦快捷键（仅 macOS）：为「聚焦最需处理的会话」注册全局快捷键。点击录制后按下组合键（需包含至少一个修饰键 ⌘/⌃/⌥/⇧），可随时恢复默认。 +- **菜单栏展示配置名称**：在托盘图标旁常驻当前 Profile 名称，可设为关闭、截断至前 N 字或完全展示。 +- **菜单栏展示会话状态**：在独立菜单栏区域显示当前 Claude 会话状态指示。 +- **计数样式**：支持标准数字（`🔴 1 🟢 1`）、上标样式（`🔴¹ 🟢¹`）或紧凑角标（`🔴¹🟢¹`）。 +- **待处理呼吸灯（仅 macOS）**：存在需要人工回复的会话时，托盘状态图标呈现脉动呼吸光效。 +- **会话聚焦全局快捷键（仅 macOS）**：自定义全局热键，一键将焦点拉回最急需关注的终端会话。 ### 桌面用量浮窗 -- 启用桌面用量浮窗：开启后创建置顶半透明小窗，实时显示今日用量指标（详见上文「桌面用量浮窗」）。 -- 展示指标：多选要在浮窗显示的指标（成本、Token 总量、缓存命中率、消息数、会话数、Top 模型），至少保留一项。 -- 不透明度：滑块调节浮窗整体不透明度，范围 30%–100%，默认 92%。 +- **浮窗总开关**：开启或关闭桌面独立用量小窗。 +- **展示指标多选**：在费用、Token 总量、缓存命中率、消息数、会话数与主力模型中多选排序。 +- **透明度调节**：通过滑块在 30%–100% 间平滑调节浮窗透明度（默认 92%）。 ### LED 灯效联动（仅 macOS） -- LED 灯效联动：把托盘会话状态镜像到 ANTICATER USB 设备灯效。打开设置时会自动探测设备，展示已连接 / 未检测到设备 / 检测中状态。等待你的输入、工作中 / 思考中、已完成 / 空闲三种状态可分别指定灯效模式（关闭 / 顺时针 / 逆时针 / 交替 / 跳跃 / 闪烁），每种模式旁的测试按钮可即时点亮验证。未连接设备时配置仍可保存，接入后生效。 - -> LED 灯效卡片仅在 macOS 显示。 +自动探测已连接的 ANTICATER USB 外设硬件： +- 为「等待输入」、「处理中/思考中」、「已完成/空闲」三种状态分别绑定光效模式（常闭、顺时针跑马灯、逆时针跑马灯、交替闪烁、跳跃、脉冲等）。 +- 提供现场测试按钮，点击即可实时点亮验证。 ### 防止休眠（仅 macOS） -在 Claude Code 会话需要长时间运行时，可阻止电脑因空闲进入休眠。 - -- **模式（三选一）**: - - **关闭**：不干预系统休眠。 - - **仅活动时**：有运行中的 Claude Code 会话时保持唤醒；会话全部结束后可正常休眠。 - - **始终**：无条件保持唤醒（仍受「屏幕常亮」开关约束）。 -- **同时保持屏幕常亮**：与模式正交。默认只阻止**系统空闲休眠**，屏幕仍可按系统策略熄灭；开启后连显示器一起保持点亮。 -- **实时状态**：模式非关闭时，设置区会显示「正在保持唤醒」或「空闲，可休眠」等状态点；托盘菜单也可切换模式。 -- **边界**：仅 macOS 生效；合盖等硬件策略可能仍导致睡眠；退出应用会释放电源断言。 +针对耗时较长的大型会话任务，防止系统进入睡眠状态中断执行： +- **防休眠模式（三选一）**： + - **关闭**：遵循系统默认睡眠策略。 + - **仅活动时**：仅在有进行中的 Claude Code 会话时阻止系统休眠，任务完成后自动恢复系统休眠。 + - **始终保持**：无论会话状态如何，始终阻止系统休眠。 +- **同时保持屏幕常亮**：独立开关。默认仅阻止系统核心休眠（允许屏幕按设定熄灭），开启后连同显示器一并保持常亮。 +- **状态指示**：设置卡片与托盘菜单中均会显示当前电源断言的实时状态点。 ### 系统通知、提示音与计价 -- 系统通知：用于 Claude 会话进入待处理状态、点击会话跳转但终端定位失败，以及最近 5 分钟缓存命中率低于设定阈值（默认 90%，支持在 10%–99% 间调节）等场景。开启时会先请求系统通知权限；权限被拒绝时设置保持关闭。 -- 等待提示音效：会话进入等待输入状态时播放系统提示音，可在 Glass、Submarine、Hero、Ping、Sosumi、Tink 中选择并试听。该选项在各平台都会显示，但只在 macOS 上发声。 -- 第三方模型计价：控制 Kimi、MiMo、GLM、MiniMax、DeepSeek 是否按 models.dev 价格估算，关闭后这些模型费用按 0 计入。 +- **系统通知**：在会话进入等待输入状态、会话定位失败或最近 5 分钟缓存命中率偏低（默认低于 90% 预警，支持 10%–99% 调节）时触发系统级通知。 +- **等待提示音效**：会话进入等待输入状态时播放提示音（支持试听 Glass、Submarine、Hero、Ping、Sosumi、Tink）。 +- **第三方模型计价**：控制国产厂商模型是否按 models.dev 行情进行成本测算。 ### 系统集成 -- 开机自启动：登录系统后自动启动 Code Manager。 -- 默认终端、默认编辑器：供项目页和目录总览的"用终端 / 编辑器打开"使用。 - -可用项来自内置支持清单和系统检测，不会自动列出电脑里所有应用，以保证每个选项都有明确的打开命令和项目路径参数。Linux 和 Windows 的编辑器需要对应 CLI 在 `PATH` 中可访问；Windows 的默认终端会优先使用 Windows Terminal，失败后回退 PowerShell 和 cmd。 +- **开机自启动**：跟随操作系统登录自动在后台启动运行。 +- **默认终端与编辑器**：为项目详情和文件总览中的外部调起动作指定首选工具。应用基于已验证的支持矩阵检测系统环境，确保调起指令完全准确。 ### 日志查看 -点击查看日志可打开日志窗口，支持按级别（all / error / warn / info / debug / trace）筛选、搜索、刷新、打开日志目录、清空日志。默认展示最近 500 条匹配结果，可切换为 1000 / 2000 / 5000 条；被截断时会提示。 +点击「查看日志」呼出专用日志审计器： +- 支持按级别过滤（All / Error / Warn / Info / Debug / Trace）、关键词全文检索、一键刷新与清空。 +- 敏感凭证与 Token 在进入日志系统前均已在内存中完成自动脱敏。 +- 支持一键打开本地日志存储目录。 ### 系统信息 -系统信息窗口展示 Code Manager 版本、操作系统类型 / 平台 / 版本 / 家族、CPU 架构、Hostname、Locale。点击复制会把信息复制为 Markdown 表格，便于提交 issue 或排障。 +集中抓取应用版本号、OS 发行版/内核/家族、CPU 指令架构、设备主机名与当前 Locale 环境，提供一键「复制 Markdown 表格」功能，极大简化 Issue 提交与技术支持流程。 ### 应用更新 -应用更新卡片展示当前版本并提供「检查更新」按钮：发现新版本后点击「下载并安装」即可自动下载、安装并重启进入新版本。应用启动时也会静默检查一次，发现新版仅以 Toast 提示，是否更新由你决定。更新包通过官方 minisign 签名校验，从 GitHub Releases 拉取。通过 Homebrew 安装的用户也可继续用 `brew upgrade` 升级，两种方式都可用。 +内置应用更新卡片展示当前版本与更新渠道： +- 提供手动「检查更新」按钮，发现新版支持一键下载、安全替换并自动重启。 +- 启动时执行静默检测，发现更新时仅通过温和的 Toast 弹窗提醒，不打扰当前工作。 +- 全量更新包基于 minisign 签名技术确保分发安全。 +- 通过 Homebrew 安装的用户可继续沿用 `brew upgrade`，应用内升级与 Homebrew 元数据在下次更新时自动保持同步。 ## 本地数据与隐私 -Code Manager 主要读写本机文件。配置合并、目录扫描、用量聚合和日志查看都在本地完成。 +Code Manager 严格践行**本地优先（Local-First）**与隐私保护原则。配置合并、本地扫描、用量计算与日志审计均 100% 在本机离线执行，除由用户主动触发的模型连通性测试与公开定价获取外，绝不上报任何私有代码或配置信息。 ### 应用管理数据 @@ -362,33 +398,34 @@ Code Manager 主要读写本机文件。配置合并、目录扫描、用量聚 | Linux | `$XDG_CONFIG_HOME/code-manager/` 或 `~/.config/code-manager/` | | Windows | `%APPDATA%\code-manager\` | -> 本应用刻意复用 `~/.config/code-manager/` 而不是 macOS 标准的 `~/Library/Application Support/...`，便于跨平台同步备份与统一脚本访问。 +> [!NOTE] +> 在 macOS 上，本应用特意使用 `~/.config/code-manager/` 替代传统的 `~/Library/Application Support/...`，方便跨平台脚本管理与统一配置同步。 ```text <应用数据目录>/ - config-registry.json - memories.json - model-pricing.json - skills-disabled/ + config-registry.json # 托管的配置注册表 + memories.json # 托管的指令与规则库 + model-pricing.json # 本地模型价目表缓存 + skills-disabled/ # 禁用的技能归档目录 ``` ### Claude Code 用户目录与输入 ```text ~/.claude/ - settings.json - CLAUDE.md - rules/ - skills/ - projects/ # 用量页输入 - history.jsonl # 项目页与历史页输入 - statusline.sh -~/.claude.json # 统计页输入 + settings.json # 最终生效的用户配置 + CLAUDE.md # 激活的主记忆 + rules/ # 激活的模块规则 + skills/ # 激活的自定义技能 + projects/ # 用量页分析日志源 + history.jsonl # 项目与历史页数据源 + statusline.sh # 自定义状态行脚本 +~/.claude.json # 统计页快照数据源 ``` ### 用量 SQLite 缓存 -由后端用量 runtime 通过 `sqlx` 维护，数据库名为 `usage.db`，位于 Tauri 默认应用配置目录（与"应用数据目录"不是同一位置）。SQLite 使用 WAL 模式时，同目录可能同时出现 `usage.db-wal` 与 `usage.db-shm`。 +用量引擎通过 `sqlx` 驱动嵌入式 SQLite 进行增量索引，数据库文件名为 `usage.db`，存放在系统标准的应用支持路径下（与「应用数据目录」相互隔离）： | 平台 | 路径 | | --- | --- | @@ -398,7 +435,7 @@ Code Manager 主要读写本机文件。配置合并、目录扫描、用量聚 ### 日志目录 -文件名通常是 `code-manager.log`，轮转文件形如 `code-manager_2026-04-29_09-13-00.log`。 +常规日志命名为 `code-manager.log`，轮转归档文件命名形如 `code-manager_2026-04-29_09-13-00.log`： | 平台 | 路径 | | --- | --- | @@ -410,72 +447,82 @@ Code Manager 主要读写本机文件。配置合并、目录扫描、用量聚 ### 创建并启用一个供应商配置 -1. 进入配置页新建配置，在「供应商」选项处选择一个内置供应商，填写认证密钥。 -2. 按需调整默认模型、努力级别和常用选项，打开最终配置预览确认 `env` 与权限。 -3. 点击测试模型，成功后保存。 -4. 回到列表点击启用，进入目录总览检查 `settings.json`。 +1. **新建配置**：进入「配置」页新建配置，在「供应商」中选定对应的内置服务商，填入对应的 API 密钥。 +2. **调优参数**：在模型和常用选项中微调参数，在「最终配置预览」中核对生成的 `env` 与权限规则。 +3. **连通性测试**：点击「测试模型」，测试通过后点击保存。 +4. **生效验证**：在配置列表中点击「启用」，随后切换至「`~/.claude` 目录总览」确认 `settings.json` 已正确写入。 ### 接管已有 `CLAUDE.md` 和 Rules -1. 进入记忆页，在未导入分组中对需要管理的文件点击"导入管理"。 -2. 检查内容和路径匹配，按需启用或禁用。 +1. **识别接管**：进入「记忆」页，在「未导入」区域找到本地现存的规则文件，点击「导入管理」就地接管。 +2. **审核状态**：检查正文内容与目标路径映射，在列表中根据项目需求开启或禁用。 ### 创建 Skill 并同步给 Codex -1. 进入 Skills 页添加 Skill，填写合法 id、显示名称和描述。 -2. 编写 `SKILL.md`，设置是否允许自动 / 手动调用并保存启用。 -3. 点击同步到 `~/.codex/skills`。 +1. **编写技能**：进入「Skills」页点击添加技能，填入合法标识符、名称与描述。 +2. **正文编写**：编写 `SKILL.md` 正文，设定调用触发机制并勾选启用。 +3. **建立软链**：在卡片菜单中点击「同步到 `~/.codex/skills`」，完成双环境联动。 ### 排查模型无法调用 -1. 编辑目标配置，确认认证密钥、API 地址和模型。 -2. 点击测试模型，在结果中查看状态码、请求地址、请求体和原始响应。 -3. 必要时复制 cURL 到终端复现；如是应用自身保存或调用失败，进入设置查看日志。 +1. **排查凭据**：编辑当前激活的配置，仔细核对 API 密钥、端点 Base URL 与模型名称是否匹配。 +2. **现场复测**：点击「测试模型」，重点查看返回的 HTTP 状态码、报错信息与原始响应报文。 +3. **定位原因**：若需要脱离应用排查，可直接复制 cURL 命令在终端独立复现；若是应用自身报错，可在「设置 → 诊断 → 查看日志」中检索系统错误日志。 ### 排查费用或 Token 异常 -1. 进入用量页，选择日期范围、项目和模型，查看总花费与构成。 -2. 打开模型价目表，确认目标模型是否有完整价格；切到按会话表格点击异常会话查看消息级明细。 -3. 模型出现在未识别列表说明成本按 0 计，可尝试刷新价格；第三方模型确认设置页计价开关是否开启。 +1. **圈定范围**：进入「Token 用量」页，将时间范围、目标项目与模型进行筛选，查看费用占比与明细构成。 +2. **核对单价**：打开模型价目表，确认该模型是否已获取到正确单价；在会话明细表中定位到异常 Session，展开单条消息瀑布流分析消耗根因。 +3. **排查归零**：若模型出现在未识别列表，尝试点击刷新价格；若为国产模型，确认「设置」中的第三方计价开关是否开启。 ## 常见问题 ### 启用配置后写到哪里？ -写入 `~/.claude/settings.json`，内容是供应商 `env` 与配置自身 settings 合并后的最终 JSON，并带 Claude Code settings schema。 +**写入 `~/.claude/settings.json`。** +写入内容是所选供应商的预置环境变量与用户在配置中定制的选项合并后的完整 JSON，并自动带入官方 Schema 定义以保证编辑校验。 ### 删除配置会删除 `settings.json` 吗？ -不会。删除配置只移除管理记录和绑定状态，不会清理已经写出的 `~/.claude/settings.json`。 +**不会。** +删除配置操作仅从 Code Manager 的内部注册表中移除该条管理记录，绝不会擅自删除或清空磁盘上已经生效的 `~/.claude/settings.json`。 -### 为什么模型测试提示缺少 `ANTHROPIC_AUTH_TOKEN`? +### 为什么模型测试提示缺少 `ANTHROPIC_AUTH_TOKEN`？ -当前配置最终配置中没有可用的认证密钥。请在认证区填写，或确认 JSON 中的 `env.ANTHROPIC_AUTH_TOKEN` 是否被覆盖为空。 +**当前配置未解析出可用的鉴权凭据。** +请检查是否在「认证」区域填入了 API 密钥，或者在高级 JSON 模式中确认 `env.ANTHROPIC_AUTH_TOKEN` 是否被意外覆盖为空值。 ### 为什么项目页没有项目？ -项目页来自 `~/.claude/history.jsonl`。使用 Claude Code 产生历史记录后，项目会显示在 Code Manager 中。 +**本地尚未生成 Claude Code 历史记录。** +项目页的数据源是 `~/.claude/history.jsonl`。当你在终端中使用 Claude Code 开展过任何会话后，项目就会自动索引并呈现在列表中。 ### 为什么统计页和用量页费用不一致？ -统计页读取 `~/.claude.json` 的本地统计快照；用量页扫描 `~/.claude/projects/**/*.jsonl` 并按当前价格表重新估算。两者数据源和计算口径不同。 +**两者的数据源与计算逻辑不同。** +「使用统计」页呈现的是 `~/.claude.json` 中的静态统计快照；而「Token 用量」页则是遍历扫描所有项目的 `.jsonl` 原始日志，并按当前最新价目表重新精确复核的结果。 -### 为什么某些模型费用为 0? +### 为什么某些模型费用为 0？ -模型不在价格表中，Token 仍统计但费用按 0 计。Kimi、MiMo、GLM、MiniMax、DeepSeek 在第三方模型计价关闭时也会按 0 计入。可尝试刷新价格，或在设置页开启第三方模型计价。 +**模型未命中价格表或第三方计价开关已关闭。** +当调用模型未收录在 models.dev 价目表中时，其 Token 会被正常统计但单价按 0 处理；此外，若国产模型计价开关处于关闭状态，Kimi、GLM、DeepSeek 等模型也会计为 0。请尝试刷新价格或前往设置开启开关。 ### 如何更新 Claude Code 插件？ -Code Manager 只管理设置中的 `enabledPlugins` 与 `extraKnownMarketplaces`，不负责安装或升级插件。更新插件请在 Claude Code 中执行：`claude plugin update <插件名>@` 更新单个插件，或 `/plugin marketplace update ` 刷新目录并升级该 marketplace 下已安装的插件。也可以在配置的 JSON 模式中把 `extraKnownMarketplaces.<名称>.autoUpdate` 设为 `true`，让 Claude Code 启动时自动更新。详见官方文档 [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins)。 +**在 Claude Code 终端中执行更新命令。** +Code Manager 仅负责管理配置文件中的 `enabledPlugins` 与 `extraKnownMarketplaces`，本身不执行插件文件的拉取或构建。请在终端执行 `claude plugin update <插件名>@` 或在会话中使用 `/plugin marketplace update ` 进行更新；亦可在配置中将对应市场的 `autoUpdate` 属性设为 `true`。详见官方文档 [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins)。 -### 为什么不能编辑软链接 Skill? +### 为什么不能编辑软链接 Skill？ -软链接 Skill 的源目录不属于 Code Manager 直接管理范围。应用只允许启停、导入和打开目录，内容需要在源目录维护。 +**软链接指向的源文件位于外部目录。** +为了防止越权篡改外部代码库，Code Manager 对软链接技能仅提供启停开关与目录定位能力，正文编辑请在源目录中进行。 ### 清除项目本地数据安全吗？ -该操作会先生成 dry-run 删除计划，确认后才执行，用于清除 Claude CLI 保存的项目本地状态。执行前必须检查删除计划，避免误删仍需要的数据。 +**具有二次确认与 Dry-run 机制，但仍需谨慎。** +该操作调用 Claude CLI 清除该项目保存的本地会话历史与上下文缓存。应用会首先展示待删除文件规划清单，确认无误后再执行，避免误伤其他数据。 ### 为什么看不到 LED 灯效联动或会话聚焦快捷键？ -这两项都**仅 macOS** 提供，Linux 和 Windows 的设置中不会显示。LED 灯效还需要接入 ANTICATER USB 设备：设置的 LED 灯效卡片显示"未检测到设备"时灯效不会亮，请确认设备已连接并在该卡片开启开关、为对应状态选择非"关闭"的灯效模式。 +**这两项功能专属于 macOS 平台。** +在 Linux 与 Windows 系统的设置中会自动隐藏这些选项。此外，LED 灯效还需物理连接兼容的 ANTICATER USB 外设硬件，并在设置卡片中开启开关且配置相应的有效光效模式。 From 3b72c84e81e3b575a8ec8b127af496fc52fd37d0 Mon Sep 17 00:00:00 2001 From: maguowei Date: Sat, 10 Oct 2026 22:18:39 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(site):=20=E4=BC=98=E5=8C=96=E9=9D=99?= =?UTF-8?q?=E6=80=81=E4=B8=BB=E9=A1=B5=E6=96=87=E6=A1=88=E3=80=81=E7=89=88?= =?UTF-8?q?=E6=9C=AC=E5=8F=B7=E4=B8=8E=E5=8F=8C=E8=AF=AD=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E9=93=BE=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- site/index.html | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/site/index.html b/site/index.html index ee6208b..cb9a839 100644 --- a/site/index.html +++ b/site/index.html @@ -17,7 +17,7 @@ @@ -81,8 +81,8 @@
- 开源 · MIT · v0.20.1 - Open Source · MIT · v0.20.1 + 开源 · MIT · v1.10.1 + Open Source · MIT · v1.10.1

把 Claude Code 的本地配置管起来 @@ -540,7 +540,7 @@

cc-switch 横向广度 许可License - ✓ 开源 (MIT)Open source (MIT) + ✓ 开源（MIT）Open source (MIT) 开源Open source @@ -577,8 +577,8 @@

设置基础项Set the basi

在「设置」中选择界面语言、主题、默认终端和默认编辑器。In Settings, pick language, theme, default terminal and default editor.

  • -

    查看供应商Browse providers

    -

    在配置编辑器的「供应商」选项处选择内置供应商（内置 Anthropic、DeepSeek、智谱 GLM、Kimi、火山方舟、阿里云百炼等十余个），点「查看内置供应商」可打开只读一览。Pick a built-in provider from the provider option in the profile editor (Anthropic, DeepSeek, GLM, Kimi, Volcengine, Bailian and 10+ more); the "view built-in providers" link opens a read-only list.

    +

    选择供应商Select a provider

    +

    在配置编辑器的「供应商」选项中选择内置服务商（内置 Anthropic、DeepSeek、智谱 GLM、Kimi、MiniMax、小米 MiMo、火山方舟等十余个），点击「查看内置供应商」可打开只读一览。Pick a built-in provider in the profile editor (Anthropic, DeepSeek, GLM, Kimi, MiniMax, Xiaomi MiMo, Volcengine and more); click "view built-in providers" to inspect full details.

  • 新建或导入配置Create or import a profile

    @@ -632,9 +632,11 @@

    新建 Skill 并同步 Codex 更完整的页面说明、费用统计口径与 FAQ 见 For full page docs, cost methodology and FAQ, see - docs/user-manual.md + docs/user-manual.zh-CN.md + docs/user-manual.md · - 平台差异platform support + 平台差异 + platform support

    • @@ -685,8 +687,8 @@

    Linux

    - 下载按钮指向 Releases / latest，会自动解析到最新版本的各平台安装包；需要历史版本时可前往 全部 Releases。macOS 发布包未经过 Apple 公证：用 Homebrew 安装会自动移除隔离属性，手动下载 .dmg 首次打开被拦截时执行下方的 xattr 命令即可。 - Download buttons point to Releases / latest and resolve to the newest per-platform installers automatically; for older versions, see all releases. macOS builds aren't Apple-notarized: installing via Homebrew removes the quarantine attribute automatically; for a manual .dmg, run the xattr command below if the first launch is blocked. + 下载按钮指向 Releases / latest，自动解析各平台最新正式版安装包。想提前体验最新特性可获取 每夜构建（Nightly）；需要历史版本可前往 全部 Releases。macOS 发布包未经过 Apple 公证：Homebrew 安装会自动移除隔离属性，手动下载 .dmg 首次打开被 Gatekeeper 拦截时执行下方命令即可。 + Download buttons point to Releases / latest and resolve to the newest stable installers automatically. To try bleeding-edge features, grab the Nightly Builds; for older versions, see all releases. macOS builds aren't Apple-notarized: Homebrew removes quarantine flags automatically; for manual .dmg installs blocked by Gatekeeper, run the command below.
    @@ -716,7 +718,7 @@

    支持哪些 Provider？Which providers are supported? -
    内置十余个供应商(只读、不可自定义)，包括 Anthropic、DeepSeek、智谱 GLM、Kimi、MiniMax、小米 MiMo、OpenRouter、火山方舟、阿里云百炼、万界方舟、Ollama；在配置编辑器的供应商选项处选择即用。A dozen+ built-in, read-only providers (no custom providers): Anthropic, DeepSeek, GLM, Kimi, MiniMax, Xiaomi MiMo, OpenRouter, Volcengine, Bailian, Wanjie, Ollama — pick one from the provider option in the profile editor.
    +
    内置十余个供应商（只读、不可自定义），包括 Anthropic、DeepSeek、智谱 GLM、Kimi、MiniMax、小米 MiMo、OpenRouter、火山方舟、万界方舟、OpenCode Go、Ollama；在配置编辑器的「供应商」选项处选择即用。A dozen+ built-in, read-only providers (no custom providers): Anthropic, DeepSeek, GLM, Kimi, MiniMax, Xiaomi MiMo, OpenRouter, Volcengine, Wanjie, OpenCode Go, Ollama — select one from the provider option in the profile editor.
    macOS 提示「已损坏 / 无法打开」怎么办？macOS says the app is "damaged / can't be opened"? @@ -724,7 +726,7 @@

    各平台功能一致吗？Is functionality the same on every platform? -
    核心配置管理在三平台对等，状态行预设也三平台都支持（Windows 用 PowerShell 版，免 jq）。差异集中在系统集成层：终端会话聚焦、可点击通知、LED 灯效目前仅 macOS。详见平台差异文档。Core config management is at parity, and statusline presets work on all three platforms (PowerShell on Windows, no jq). Differences sit in system integration: terminal focus, clickable notifications and LED are macOS-only for now. See the platform-support doc.
    +
    核心配置管理在三平台完全对等，状态行预设也在三平台均可使用（Windows 采用 PowerShell 版，免安装 jq）。系统集成层存在部分平台差异：终端会话聚焦、系统提示音效、ANTICATER LED 硬件灯效目前仅支持 macOS。详见平台差异文档。Core configuration governance is at full parity across all three platforms, and statusline presets work on all platforms (PowerShell on Windows, no jq required). System integration differences: terminal session focus, sound effects, and ANTICATER LED hardware lighting are macOS-exclusive for now. See the platform support guide for details.
    是开源的吗？Is it open source? @@ -783,15 +785,17 @@

    产品Product

    文档Docs

    - 用户手册User manual - 平台差异Platform support + 用户手册 + User manual + 平台差异 + Platform support FAQ

    项目Project

    GitHub Releases - 许可 (MIT)License (MIT) + 许可（MIT）License (MIT)