CLAUDE.md

本文件面向在本仓库中工作的 AI Agent，例如 Claude Code、Codex 以及读取 AGENTS.md / CLAUDE.md 的同类代理。它是执行手册，不是产品介绍页；人类用户入口在 README.md，完整使用说明在 docs/user-manual.md。

项目速览

• 项目：Code Manager，基于 Tauri 2 的 Claude Code 本地配置管理桌面应用。
• 版本号同时维护在 package.json、src-tauri/Cargo.toml 与 src-tauri/tauri.conf.json 三处，需保持一致。
• 前端：React 19 + TypeScript + Vite + Tailwind CSS v4 + shadcn/ui。
• 后端：Rust + Tauri commands + tauri-specta 类型化 IPC。
• 表单与校验：react-hook-form + Zod + JSON Schema。
• 编辑、预览与可视化：CodeMirror、react-markdown、@pierre/diffs、@pierre/trees、Recharts、@tanstack/react-virtual。
• 本地缓存与日志：sqlx + SQLite、tauri-plugin-log。
• 包管理器：pnpm，项目声明 pnpm@12.4.2；不要改用 npm。
• 应用标识符：com.gotobeta.app.code-manager。

会话工作流

1. 判断改动范围，读取命中的规则文件，再打开相关代码。
2. 方向偏离时停下重新规划，不在错误方向上继续推进。
3. 改动前检查 git status --short；工作区可能是脏的，不要回退你没创建的改动。
4. 保持最小影响面，沿用现有模式；先找根因，不用临时绕过方案。
5. 完成前运行与改动范围匹配的验证命令，并检查 diff；没有新鲜验证证据，不要声称完成。

硬约束

• 代码注释使用中文。
• 所有用户可见文本必须走 useI18n() 的 t() 函数，不要硬编码中英文字符串。
• 所有前端通知优先走 useToast()，不要把 console.error 当作用户反馈。
• pnpm check 会执行 biome check --write . 并修改文件，make fmt 同样改写，都别当只读验证；只读前端检查用 make lint-frontend，只读格式检查用 make fmt-check。
• 新增有层叠关系或浮层的样式时，使用 shadcn 语义变量和 shadcn 原子组件内置层级，不要硬编码十六进制色值或 z-index 数字。
• 前端视觉默认采用“均衡管理台”风格：克制、紧凑、可扫描，不做营销式 hero、大字号展示或装饰性卡片堆叠。
• Rust 新增文件读写、锁、时间、JSON 工具时，优先复用 src-tauri/src/utils.rs。
• package.json 的 prepare 脚本会自动安装 lefthook git hooks；本地门禁分三层：.claude/settings.json 做会话级提醒和绕过拦截，lefthook 做 pre-commit / commit-msg / pre-push 快反馈，GitHub Actions 做远端权威检查。
• 提交信息遵守 Conventional Commits，commit-msg 与 CI 都通过 commitlint 检查；本地分支 pre-push 会运行 make verify，tag-only push 交给 release workflow 的 quality job。

规则索引

按修改范围阅读对应规则。多个路径命中时，全部适用。

快速入口

前端：

• 应用壳与页面编排：src/App.tsx
• React 入口、全局 Provider 与错误日志：src/main.tsx
• 国际化：src/i18n.ts
• 类型契约：src/types.ts
• IPC 包装与生成契约：src/ipc.ts、src/bindings.ts
• 共享 schema 与表单定义：src/schemas/
• 公共 hooks：src/hooks/
• 配置编辑器与结构化分区：src/components/profile-editor/（供应商均为内置只读，无供应商编辑器）
• ~/.claude 共享树预览组件：src/components/claude-overview/
• Token 用量抽屉、骨架与格式化工具：src/components/usage/
• 主题与 UI token：src/components/theme-provider.tsx、src/components/typography-classes.ts、src/components/surface-classes.ts
• 编辑器退出保护：src/components/editor-exit-guard.ts、src/components/UnsavedChangesAlertDialog.tsx
• Vitest setup：src/test/setup.ts（配套 vitest.config.ts）

后端：

• Tauri 命令注册：src-tauri/src/lib.rs
• Rust 公共工具：src-tauri/src/utils.rs
• 配置系统核心：src-tauri/src/config.rs
• ~/.claude 目录：src-tauri/src/claude_directory.rs、src-tauri/src/claude_directory_watcher.rs
• 记忆与 Skills：src-tauri/src/memory.rs、src-tauri/src/skills.rs
• 历史、统计、用量：src-tauri/src/history.rs、src-tauri/src/stats.rs、src-tauri/src/usage.rs
• 项目、打开本机应用、托盘：src-tauri/src/project.rs、src-tauri/src/native_open.rs、src-tauri/src/tray.rs
• 会话终端聚焦：src-tauri/src/terminal_focus.rs（AppleScript）、src-tauri/src/herdr.rs（herdr 两跳聚焦）
• 日志与诊断：src-tauri/src/logging.rs
• 内置 provider、模型价格和状态行脚本：src-tauri/resources/
• Tauri capability：src-tauri/capabilities/default.json

架构同步点

• IPC 权威链：Rust command 使用 #[tauri::command] + #[specta::specta]，在 src-tauri/src/lib.rs::build_specta_builder() 的 tauri_specta::collect_commands![] 注册，src/bindings.ts 由 make bindings 生成。
• 前端业务代码统一通过 src/ipc.ts 的 ipc 包装调用生成 bindings；只有自动生成的 src/bindings.ts 直接导入 @tauri-apps/api/core 的 invoke()。
• 新增或修改 Tauri command 时，同步 Rust command、Specta 注册、make bindings / make bindings-check、src/ipc.ts 兼容包装（如需）、src/types.ts、i18n、测试；涉及插件 API 时检查 src-tauri/capabilities/default.json。
• JSON Schema 是配置系统的前后端共享契约锚点。
• 配置预览、配置应用、模型测试、Provider、Skills、Memory 的真实持久化规则都在 Rust；前端负责调用与展示，不要复制后端业务逻辑。
• ProjectsPage 读取 ~/.claude/history.jsonl；StatsPage 读取 ~/.claude.json；UsagePage 扫描 ~/.claude/projects/**/*.jsonl。三者数据源不同，不要混用。
• 用量 watcher 与 SQLite 初始化由 usage::start_usage_runtime(app) 在 lib.rs::setup 中启动；新增用量字段需要同步 usage.rs 的 schema / 初始化逻辑、UsageRecord struct、前端 useUsage.ts 与 src/types.ts。

关键数据目录

macOS 上同时使用三个目录，互不混用：

macOS 上应用数据刻意复用 ~/.config/code-manager/，便于跨平台备份和脚本访问；解析逻辑见 src-tauri/src/utils.rs::get_app_data_dir()。SQLite 走 Tauri app_config_dir()，日志走 Tauri 插件默认路径，不要迁回应用数据目录。

其它已知输入路径与覆盖：~/.claude/、~/.codex/skills/、~/.claude/history.jsonl、~/.claude/projects/、~/.claude.json、CODE_MANAGER_HOME_OVERRIDE、CODE_MANAGER_APP_DATA_DIR_OVERRIDE。

测试与验证

按改动范围选最小充分集；没有运行的命令不要在最终回复里说“已通过”。

本地启动桌面应用优先用 make dev（底层是 pnpm tauri dev）；pnpm dev 只启动 Vite。生产包优先用 make build。

已知陷阱

• CodeMirror 多版本冲突会导致空白页或配置预览渲染崩溃（@codemirror/state 必须全局单例）。排查：grep "'@codemirror/state@" pnpm-lock.yaml，预期只有一个版本；如出现多个版本，在 pnpm-workspace.yaml 的 overrides 段统一（pnpm 11 起已不再读取 package.json 的 pnpm.overrides）。
• 不要自实现浮层：抽屉、设置面板、模态框、下拉菜单和 Toast 都用 shadcn Sheet / Dialog / DropdownMenu / Popover / sonner。
• 不要把日志当成配置数据：日志目录由 Tauri 的 app_log_dir() 解析。
• 当前配置 schema 是 src/schemas/claude-settings.schema.json。
• Tauri 事件监听器必须在组件卸载时清理；使用 useTauriEvent hook 而非直接调用 listen()。

参考阅读顺序

1. 本文件
2. 命中路径对应的 .claude/rules/*.md
3. 目标模块入口文件
4. src/App.tsx、src/main.tsx、src-tauri/src/lib.rs、src-tauri/src/utils.rs
5. 需要人类产品背景时再读 README.md 或 docs/user-manual.md
6. 涉及发版流程时阅读 .claude/skills/release-new-version/SKILL.md（手动触发，模型不得自动调用）

Agent skills

本章节由 agent skills 配置流程维护。除非用户明确指示修改此章节，否则不要改动、重排或删减其中内容（包括 CLAUDE.md 精简、文档同步等顺带修改）。

Issue tracker

Issues 追踪在仓库的 GitHub Issues，通过 gh CLI 操作；外部 PR 不作为 triage 队列来源。详见 docs/agents/issue-tracker.md。

Triage labels

采用默认标签词汇：needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix。详见 docs/agents/triage-labels.md。

Domain docs

单上下文布局：根目录 GLOSSARY.md + docs/adr/。详见 docs/agents/domain.md。