rebalance-OS

> 你的工作日 "操作系统" --- ## 适用对象 - **开发和设计机构负责人**，同时管理 5 个以上的客户仓库，散乱的笔记和连续的会议让你无暇顾及 - **自由职业者和独立开发者**，他们生活在 Obsidian 中，但却花费数小时追踪自己的注意力究竟花在哪里 - **技术创始人**，希望在不向云服务发送笔记、提交或日历的情况下，获得 AI 辅助的清晰度 如果你曾经打开笔记本电脑，早上不知道从哪里开始，这就是为你准备的 --- ## 问题 你的工作生活在多个地方，它们之间互不通信：笔记、代码仓库、最近的 git 活动、日历和围绕它们封装的提醒系统。你不断切换上下文，失去跟踪哪些项目获得太多关注（哪些没有获得足够关注），每天花费前 30 分钟重建昨天的工作 AI 助手可以帮助 — 但它们看不到你的 Obsidian 保险库、GitHub 活动或 Google 日历。而将所有这些发送到云端 LLM 对于客户工作来说不是一个选项 <img width="1882" height="1516" alt="rebalance" src="https://github.com/user-attachments/assets/eb60a254-d452-4839-a900-0ffedd72758f" /> --- ## 它做什么 **rebalance OS** 是一个本地优先的工作操作系统，它将你的 Obsidian 保险库、GitHub 活动和工件、最近的 git 历史、日历和电子邮件摄入到一个可查询的 SQLite 数据库 — 然后允许任何支持 MCP 的主机或代理（ChatGPT、Gemini、Claude、Copilot、Cursor、Continue 等）回答关于你自己的工作的问题，在项目中显示你的注意力实际花费在哪里，并在出现问题时触发自我修复的后台收集器 — 所有这些都在你的本地机器上进行，无需将私有数据发送到云服务 --- ## 用例 **晨间简报** 询问 "今天的日程是什么？"，获取今天的会议、昨天的提交活动和相关笔记的总结 — 只需在本地机器上进行一次操作 **项目平衡检查** " 我是否在项目 X 上投入过多精力？ " 显示每个项目的提交速度、PR 活动和笔记密度。当某个仓库占用了你超过 40% 的注意力时发出警告 **知识检索** " 我决定了关于项目 Alpha 嵌入管道的什么？" 在你的保险库和同步的 GitHub 数据中进行语义搜索，按相关性排序并从本地 SQLite 证据层回答 **交接准备** " 总结我对项目 Y 的所有了解 " 将笔记、最近的提交和开放问题提取到一个连贯的简报中 — 适用于客户更新、团队交接或只是重新开始 **每周平衡** " 这周我的注意力实际花在哪里了？ " — 日历小时、电子邮件线程、Slack 提及和 GitHub 活动都按项目索引。信号无关的优先级层（正在进行中）将聚合这些信息，并通过 AI 总结而不是硬编码的判决标签进行叙述 **自我修复的后台作业** 后台收集器（脉冲同步、GitHub 扫描）现在使用有限状态机修复循环（`src/rebalance/repair.py`）。当作业因可恢复的错误而失败时 — 例如，脉冲仓库上的推送冲突 — 它会自动重试并使用 `pull --rebase`。如果确定性修复用尽，Haiku 会被咨询以从有界的动作菜单中选择，然后作业会创建一个 GitHub 问题并停止。破坏性操作需要明确的操作员授权，并且永远不会自主选择 --- ## 高级架构 ``` 数据来源 Google 日历 ──┐ GitHub 活动 ──┤ GitHub 工件 ──┤ Git 脉冲历史 ──┤──▶ 调度器 / 按需同步 ──▶ SQLite + sqlite-vec Obsidian 保险库 ──┤ （launchd 在 macOS 上， （保险库块， Sleuth 提醒 ──┤ 任务调度器在 github_activity， Gmail 邮箱 ──┤ Windows 上，cron 在 Linux 上） github_artifacts， Slack [计划] ──┘ 日历事件， 电子邮件消息， git 脉冲报告， 语义文档） │ ▼ MCP 服务器 — src/rebalance/mcp/ 7 个域中 25 个工具： 项目 list_projects · github_balance 入门 onboarding_status · setup_github_token run_preflight · confirm_projects ingest_gmail_messages 检索 ask · query_notes · search_vault query_github_context github_release_readiness github_close_candidates 日历 create_calendar_event · review_timesheet classify_event · snap_calendar_edges 索引 index_status · refresh_index · diagnose_repo list_watched_repos · publish_pulse semantic_query 卫生 audit_modules Sleuth sleuth_sync_reminders │ ┌───────────────────────┼────────────────────────┐ ▼ ▼ ▼ ChatGPT/Gemini Claude/Copilot Cursor/Continue （MCP 适用） （MCP 客户端） （MCP 客户端） ``` MCP 服务器使用标准的 JSON-RPC — 没有特定的 LLM 逻辑。任何兼容 MCP 的客户端都无需修改即可使用 图表的调度部分（启动舰队：每日/每小时同步、脉冲发布、健康检查）由 [SCHEDULER.md](SCHEDULER.md) 中的策略表管理 — 作业节奏、范围、先决条件和运行手册都记录在那里 有关层角色、工具表面、服务器配置和主机适配器设置（Claude Desktop、Cursor、VS Code、Continue），请参阅 **[MCP.md](./MCP.md)** --- ## 为什么 Markdown 文件和本地 LLM 使这成为可能 Obsidian 将所有内容存储为普通的 `.md` 文件。没有专有数据库，没有同步锁定，没有所需的 API — 只需磁盘上的一个文件夹。这使得摄入成为一个简单的递归文件扫描：解析 frontmatter，按标题分块，提取标签和 wikilink，嵌入和索引。最近的工作将相同的模式扩展到保险库之外；可嵌入的 GitHub 工件现在流入同一个统一的语义文档层，而不是生活在单独的向量隔离中 本地 LLM — 例如通过 Ollama 或 LM Studio 兼容的模型提供的 Qwen3 — 闭环。你的保险库内容可以保持本地，并且可以通过默认不将笔记内容发送到托管的 LLM 进行查询。GitHub 和 Google 日历数据从其 API 拉取，然后在本地缓存和查询。模型在设备上运行（针对 Apple Silicon 通过 MLX 优化），从本地向量存储检索上下文，并在几秒内回答 结果是一个实际上了解你的工作的 AI 助手 — 因为它正在读取与你相同的文档和同步的历史 --- ## 技术栈 | 层 | 工具 | |---|---| | 笔记 | Obsidian （普通 `.md`）| | 本地活动历史 | `git-pulse` 同步仓库 + 回顾/报告层 | | 向量数据库 | SQLite + `sqlite-vec` | | 嵌入 | Qwen3-Embedding-0.6B via `mlx-embeddings` （Apple Silicon MLX）| | LLM 合成 | Qwen3-0.6B via `mlx-lm` （设备端，第 1 层）| | 日历 | Google 日历 API （直接客户端，OAuth2）| | GitHub | GitHub REST API + PAT | | 提醒 | Sleuth Web API （结构化同步）| | MCP 服务器 | Python `mcp` SDK （FastMCP，stdio）— 分解为 `src/rebalance/mcp/` （7 个域模块，25 个工具）| | 修复循环 | `src/rebalance/repair.py` — `RepairFSM` （PENDING → REPAIRED \| ESCALATED → REPAIRED \| DEAD）具有 Haiku 升级和有界动作菜单 | | LLM 客户端 | 任何 MCP 主机（Claude Code、Copilot、Cursor、Continue、Claude Desktop 等）| --- ## 路线图 - [x] 架构和设计 - [x] 项目注册 + MCP 入门工具 - [x] GitHub 活动扫描器 + 30 天 A/B/C 班级分类 - [x] GitHub 工件同步 + 本地语义查询（问题、PR、评论、审查、提交） - [x] 跨保险库和 GitHub 的统一语义索引（`semantic_documents`、`semantic_embeddings`） - [x] GitHub 就绪推断来自本地仓库信号（里程碑、链接的 PR、分支、发布） - [x] GitHub 问题 <-> PR 关闭候选人协调，具有高/中置信度推荐 - [x] Obsidian 保险库摄入（解析、块、分词、关键词、链接） - [x] Qwen3 嵌入管道（sqlite-vec，语义搜索） - [x] Google 日历集成（OAuth2，1 年保留） - [x] Git-pulse 本地仓库发现、回顾层、健康检查和同步加强 - [x] Sleuth 提醒同步（结构化摄入） - [x] `ask` 工具 — 多源自然语言查询，具有本地 LLM 合成 - [x] 时间上下文（星期几，工作/关闭/假期意识） - [x] 每日调度脚本（launchd plist，安装帮助程序） - [x] 日历每日/每周报告，具有项目聚合和时间总计 - [x] 可配置的小时格式（十进制或 h:m）用于日历报告 - [x] 日历事件的代理审查层（`review_timesheet`、`classify_event` MCP 工具） - [x] DRY 日历助手（共享日期时间解析、持续时间计算、连接设置） - [x] CI 测试套件（GitHub Actions，Python 3.12/3.13） - [x] Gmail 邮箱集成（最新的 100 条邮箱消息，通过主题 + 片段进行语义索引） - [x] MCP 服务器分解 — `src/rebalance/mcp/` 包，具有 7 个域模块，25 个工具，5 行向后兼容性桩 - [x] 显示层简化 — 删除死代码，消除注册表路径，`ingest/dashboard.py` 重命名为 `note_builder.py`，添加忽略仓库过滤器到组织活动查询 - [x] `RepairFSM` （`src/rebalance/repair.py`）— 确定性修复循环，具有有界 Haiku 升级、电路中断器和不可恢复错误短路；脉冲自我修复是第一个消费者 - [ ] 信号无关的项目优先级 — 多源属性（日历 + 电子邮件 + Slack + GitHub）馈送透明的项目计数；`GitHub Repos.md` 注释表面与 `#tag` 写回 - [ ] 每周平衡笔记生成，以多信号计数为基础，而不是硬编码的判决标签 - [ ] Slack 集成，超出提醒/任务信号 - [ ] 电子邮件 → 项目自动关联（分类器已应用于日历；扩展到 `gmail_messages`） ## 文档 | 指南 | 内容 | |-------|--------------| | [GMAIL.md](./GMAIL.md) | Gmail 邮箱摄入 — `oauth` （keyring）vs `mcp` 方法、耐用内部令牌、查询筛选器、故障排除 | | [GOOGLE_CALENDAR.md](./GOOGLE_CALENDAR.md) | Google 日历时间表 — 设置、团队配置、事件创建、项目聚合 | | [MCP.md](./MCP.md) | MCP 层 — 工具表面、服务器配置、主机适配器（Claude Desktop、Cursor、VS Code、Continue）| | [UPGRADE.md](./UPGRADE.md) | Keyring 凭证模型 + 多设备升级步骤 | | [DASHBOARD.md](./DASHBOARD.md) | 本地网络/活动仪表板 | | [ARCHITECTURE.md](./ARCHITECTURE.md) | 系统架构和数据流 | | [PROJECT/PDDA.md](./PROJECT/PDDA.md) · [ROADMAP.md](./ROADMAP.md) | 计划文档合约和指针账本索引每个活动项目 | | [AGENTS.md](./AGENTS.md) | 在此仓库中工作的 AI 代理的约定 | | [macOS/Apps/Focus5Float/README.md](./macOS/Apps/Focus5Float/README.md) | Focus 5 Float macOS 应用 — 构建、安装、二进制路径设置（`pipx`）、自我检查 | --- ## 入门指南 ### 最快路径 — `/welcome` 克隆并安装（步骤 1 以下）后，在 Claude Code 中打开仓库并输入 `/welcome`。欢迎代理从零开始引导您完成整个过程：它会检查您的当前位置（`onboarding_status` — 随时可恢复，即使几天后），运行每个步骤（GitHub PAT 验证、可选的 Google 日历/Gmail OAuth、项目发现），询问您要将哪些发现的仓库提升到受监控的项目，然后安装计划的同步舰队并打开您的第一个脉冲。您只需要点击 OAuth 同意屏幕并回答提升/跳过问题 — 机密信息从不会出现在聊天中 如果没有代理？`rebalance onboard` 是相同的引导式旅程，作为 CLI 向导，而 `rebalance onboard --status` 显示阶段地图（“我在哪里 / 下一步是什么？”）随时可用。要重新开始：`rebalance reset` （默认为 dry-run；您的 vault 永远不会被触及） 下面的手动步骤仍然作为参考和没有 MCP 主机的环境而保留 ### 先决条件 - 带有 Apple Silicon（M1+）的 macOS 以获得完整的本地堆栈（嵌入 + 设备端 LLM）— 核心是跨平台的；请参阅下面的[支持的平台和首次运行网络](#supported-platform--first-run-network) - Python 3.12+（推荐 3.13 以获取本地 MLX 嵌入堆栈） - Obsidian 保险库（本地文件夹，带有 `.md` 文件） - GitHub 个人访问令牌（[在此处创建](https://github.com/settings/tokens)）— 既可以是 **经典令牌**，具有 `repo` 范围（GitHub 不提供经典令牌的只读私有范围；`public_repo` 单独使您的私有工作对发现不可见），或者是 **细粒度令牌** — 将存储库访问权限从默认值 **“公共仓库”** 更改为 **所有仓库** （或您工作的仓库），具有只读 **内容** 和 **元数据** 权限 - Claude Code（CLI 或 VS Code 扩展） ### 支持的平台和首次运行网络 **完整体验：带有 Apple Silicon（M1+）的 macOS。** 设备端嵌入 (`mlx-embeddings`) 和 LLM 合成在 Apple 的 MLX 上运行，而 MLX 仅支持 Apple Silicon **跨平台子集。** 核心是用纯 Python 编写的，可以在 Linux、Windows 和 Intel Mac 上运行 — 只有 `embeddings` 扩展是平台相关的： | 安装 | 增加什么 | 平台 | |---|---|---| | `pip install -e .` | CLI、MCP 服务器、SQLite + `sqlite-vec`、vault 摄入（解析/分块/关键词/链接）、GitHub 扫描/同步、`doctor` | 任意（Python 3.12+）| | `+ [calendar]` | Google 日历 + Gmail OAuth 摄入 | 任意 | | `+ [server]` | 本地网络/活动仪表板 | 任意 | | `+ [embeddings]` | 语义搜索 + 嵌入（`semantic-*` 和 `ask` 背后的检索） | **仅限 Apple Silicon** | 因此，语义搜索需要 Apple Silicon；而其他功能 — 摄入、GitHub、日历、完整的 MCP 工具表面 — 只要有 Python 3.12+，就可以在任何地方运行 **首次运行网络出口（如果有出口限制 / 代理沙盒）** - 首次 `semantic-embed` / `ingest embed` 会从 **huggingface.co** 下载 **Qwen3-Embedding-0.6B** — 一次性，几百 MB，然后缓存在 `~/.cache/huggingface` 下 - `github-*` 命令使用您的 PAT 调用 **api.github.com** - 日历 / Gmail 调用 **accounts.google.com** 和 **\*.googleapis.com** 进行 OAuth 和同步 如果您在允许列表后面运行，请在首次运行前允许这些主机；模型下载是唯一的较大传输，并且一次性完成 ### 步骤 1 — 克隆并安装 ```bash git clone https://github.com/Hypercart-Dev-Tools/rebalance-OS.git cd rebalance-OS /opt/homebrew/bin/python3.13 -m venv .venv .venv/bin/pip install -e ".[embeddings,calendar]" ``` > 在 Linux / Windows / Intel Mac 上，删除 `embeddings` 额外项：`pip install -e ".[calendar]"` （语义搜索不可用；其他功能正常运行） ### 步骤 2 — 摄入您的保险库 ```bash # 解析所有 .md 文件，按标题分块，提取关键词和链接 .venv/bin/rebalance ingest notes --vault /path/to/your/vault --database rebalance.db ``` # 生成 vault 嵌入 .venv/bin/rebalance ingest embed --database rebalance.db ``` > **嵌入运行在内存保护下（GH-172）。** 嵌入是该项目中最耗资源的本地作业 — 它加载 Qwen 模型并保持向量驻留。 因此，每次嵌入操作都会获取**单个实例锁**并在**内存上限**（默认值：物理 RAM 的 35％）下运行，这样第二个运行就无法叠加到第一个运行上，导致机器资源耗尽。 默认情况下，此功能已启用，无需安装。 > 如果运行退出时提示 "job 'rebalance-embed' is already running"，则表示 guard 正在工作 — 另一个嵌入操作（通常是计划的 `daily-sync`）持有锁。 等待，或使用 `REBALANCE_JOB_GUARD_ON_CONFLICT=replace` 重新运行以获取锁。 > 验证它是否处于活动状态，并为每台机器调整参数： > > ```bash > .venv/bin/python -c "from rebalance.ingest import _job_guard as g; print(g.available(), g.enabled())" > # -> True True > ``` > > 每次受保护的运行还会将其峰值内存追加到 `temp/logs/job_rss.jsonl`，因此如果作业确实耗尽了机器资源，您可以查看**哪个**作业导致了这个问题 — 此问题的原因是 macOS 只记录进程名称 `Python`，而无法精确记录导致问题的进程。 > > 完整参考、调整变量和不可编辑安装的注意事项： [UPGRADE.md § Embedding job guard](./UPGRADE.md#embedding-job-guard-gh-172--verify-on-every-device)。 > 在内存小于 64 GB RAM 的机器上，请显式设置 `REBALANCE_JOB_GUARD_MAX_RSS_GB`，而不是依赖百分比。 > **如果您安装了计划作业**，请注意 `scripts/` 中的 plist 模板为批处理作业设置了 `Nice=5`，并使用故意冲突的计划 — 没有两个作业在同一分钟内触发。 `pulse-web-sync` 特别是不能与 `pulse-sync` 共享时间槽：它是 `pulse-sync` 写入内容的派生只读阶段，因此共享分钟可能会读取写入了一半的状态。 通过每个作业的 `scripts/install_*_scheduler.sh` 脚本安装；没有单一的安装所有作业的脚本。 详细信息： [UPGRADE.md § Re-render your launchd plists](./UPGRADE.md#re-render-your-launchd-plists-gh-175--required-on-existing-devices)。 ### 步骤 3 — 连接 GitHub ```bash # 存储您的 PAT .venv/bin/rebalance config set-github-token <github-pat> # 扫描最近的活动（提交、PR、问题，跨所有您的仓库） .venv/bin/rebalance github-scan --token <github-pat> --database rebalance.db # 将详细的 GitHub 工件同步到本地 SQLite 数据库 .venv/bin/rebalance github-sync-artifacts \ --repo owner/repo \ --database rebalance.db # 从 vault + GitHub 反向填充统一语义层 .venv/bin/rebalance semantic-backfill --source vault --source github --database rebalance.db # 嵌入统一语义层（首次运行下载 Qwen3-Embedding-0.6B） .venv/bin/rebalance semantic-embed --source vault --source github --database rebalance.db # 在不重新读取 GitHub 的情况下查询统一语义语料库 .venv/bin/rebalance semantic-query "What is close to deploy?" --source vault --source github --database rebalance.db ``` 您仍然可以使用源特定的命令： ```bash .venv/bin/rebalance github-embed --database rebalance.db .venv/bin/rebalance github-query "What changed in release readiness?" --database rebalance.db ``` ### 步骤 4 — 连接 Google 日历（可选） OAuth 桌面应用程序凭证已绑定在仓库中。 您**不需要**创建 Google Cloud 项目或下载 `client_secret.json`。 **4a. 安装时启用日历支持** ```bash .venv/bin/pip install -e ".[calendar]" ``` **4b. 授权此设备** ```bash .venv/bin/python scripts/setup_calendar_oauth.py --test ``` 一个浏览器窗口打开 — 使用您的 Google 帐户登录并点击 **允许**。 脚本打印您的可用日历及其 ID。 您的令牌保存在您的 OS 密钥环中，并以 `~/.config/rebalance-os/secrets/google-calendar-oauth` 为前缀的 JSON 文件作为后备（从不存储在仓库中）。 如果您希望 MCP 代理创建事件，请使用写入访问权限重新运行身份验证： ```bash .venv/bin/python scripts/setup_calendar_oauth.py --write-access --test ``` > **加入团队？** 如果团队成员为您发送了预先填写好的 `calendar_config.json`，请将其放在 `temp/calendar_config.json` 并跳到步骤 4d。 **4c. 创建您的配置文件** ```bash mkdir -p temp cp calendar_config.example.json temp/calendar_config.json ``` 编辑 `temp/calendar_config.json` 以适应您的偏好： | 字段 | 应填写的内容 | |-------|-----------------| | `calendar_id` | 日历 ID（步骤 4b）或 `"primary"` 表示您的主日历 | | `exclude_titles` | 要从报告中隐藏的精确事件标题（例如 `"Lunch"`、`"Check Slack"`） | | `aggregator_skip_words` | 项目分组标签中跳过的宽泛术语（例如 `"wrap"`、`"setup"`） | | `timezone` | 您当地的时区（例如 `"America/Los_Angeles"`） | | `hours_format` | `"decimal"`（默认值，例如 `4.50h`）或 `"hm"`（例如 `4h 30m`） | **4d. 同步和运行报告** ```bash # 拉取事件（使用 --days-back 365 进行初始回填） .venv/bin/rebalance calendar-sync --days-back 30 # 生成报告 .venv/bin/rebalance calendar-daily-report .venv/bin/rebalance calendar-weekly-report .venv/bin/rebalance calendar-weekly-report --vault /path/to/vault --write-week-note ``` 有关完整指南，包括团队设置、Claude Code 提示和项目定义，请参阅 [GOOGLE_CALENDAR.md](./GOOGLE_CALENDAR.md)。 ### 步骤 5 — 连接 Gmail（可选） Gmail 提取仅存储消息元数据和 Gmail 提供的摘要 — 它不解析完整的消息正文。 有两种方法可以提供它，您可以通过 `rebalance config set-gmail-method` 选择一种： | 方法 | 何时使用 | 凭证 | |---|---|---| | `oauth` *(默认)* | 自动 / 计划同步（launchd、cron） | 密钥环中的桌面 OAuth 令牌 | | `mcp` | 您从 MCP 主机（例如 Claude）驱动 rebalance | 无 — 代理调用 `ingest_gmail_messages` | **选项 A — `oauth`（自包含，适用于 launchd）** 一次性浏览器同意会将只读 Gmail 令牌存储在您的 OS 密钥环中，并使用启动服务可达的 JSON 文件作为后备，与日历相同： ```bash python scripts/setup_gmail_oauth.py # 浏览器同意；直接写入密钥环 + JSON 文件 rebalance config set-gmail-method oauth ``` > `gmail.readonly` 是 Google **限制**范围。 此流程使用**您的**桌面 OAuth 客户端，带有测试模式下的同意屏幕（添加您的帐户作为测试用户），可以在**不**进行正式应用验证的情况下请求它。 这就是为什么此方法有效，而 `gcloud auth application-default login --scopes=…gmail.readonly` 无效 — 共享的 gcloud ADC 客户端通常不允许限制 Gmail 范围，因此 ADC 令牌 403 "身份验证范围不足"。 **选项 B — `mcp`（无本地凭证）** ```bash rebalance config set-gmail-method mcp ``` 然后由代理（例如 Claude）使用 Gmail MCP 连接器调用 `ingest_gmail_messages` 工具。 计划作业**不能**触发此操作 — 代理**必须**调用。 无需本地 Gmail 凭证。 > **权衡：** `mcp` 路由您的电子邮件通过主机云（例如 claude.ai），而 `oauth`（选项 A）将邮件保留在此机器上。 它需要一个带有已连接 Gmail 帐户的主机 — 否则请使用 `oauth`。 **5c. 可选：缩小收件箱查询** 在 `temp/rbos.config` 中添加 `gmail_query_filter` 键。 示例： ```json { "gmail_query_filter": "in:inbox -category:promotions -category:social" } ``` 如果未设置，rebalance 默认使用 `in:inbox`。 **5d. 同步和验证** 运行 `rebalance refresh`（完整管道在 `oauth` 模式下同步邮件），或从 MCP 主机调用 `refresh_index(scope=["email"])`。 在 `index_status()` 中确认 `email` 块出现在 `semantic_query()` 中，并且 `rebalance doctor` 报告 `gmail — OK`。 有关完整指南，包括两种导入方法、持久（内部）令牌、查询过滤器、故障排除和 Claude Code 提示，请参阅 [GMAIL.md](./GMAIL.md)。 ### 步骤 6 — 使用 Claude Code 启动 项目根目录中的 `.mcp.json` 自动注册了 MCP 服务器。 在 Claude Code 中打开项目： ```bash cd rebalance-OS claude ``` 然后询问： ``` "今天我应该专注于什么？" "我本周是否在任何项目上投入过多？" "明天我有哪些会议，应该如何准备？" "我决定了什么关于嵌入管道的事？" ``` Claude Code 在后台调用 `ask` 工具 — 它收集您的项目注册表、GitHub 活动、vault 笔记和日历事件，通过本地 Qwen3 模型合成第一个答案，然后 Claude 审查并呈现精炼的答案。 ### Claude 桌面应用 #### 手动配置（目前推荐） 1. 打开 **Claude → 设置 → 开发者 → 编辑配置** 以打开 `~/Library/Application Support/Claude/claude_desktop_config.json`。 2. 添加 rebalance 服务器（使用绝对路径）： ```json { "mcpServers": { "rebalance": { "command": "/absolute/path/to/rebalance-OS/.venv/bin/python", "args": ["-m", "rebalance.mcp_server"], "env": { "REBALANCE_DB": "/Users/<you>/Library/Application Support/rebalance-os/rebalance.db" } } } } ``` `REBALANCE_DB` **自 0.28.0 起为可选** — `src/rebalance/paths.py` 默认使用规范应用数据路径（macOS 上为 `~/Library/Application Support/rebalance-os/rebalance.db`，Linux 上为 `$XDG_DATA_HOME/rebalance-os/rebalance.db`）。 仅当您要覆盖此默认值时才显式设置它。 如果此处未设置 `REBALANCE_DB`，则启动作业的 plist 不会设置它 — 它们依赖于相同的解析器后备，因此当规范路径移动或添加新同步作业时，无需编辑 plist。 3. 退出并重新打开 Claude 桌面应用。 rebalance 工具出现在工具选择器（锤图标）中。 4. 验证：询问 *"我今天应该处理什么？"* 以进行验证。 有关详细设置、故障排除和其他 MCP 主机，请参阅 [MCP.md — Claude Desktop](./MCP.md#claude-desktop)。 #### 扩展（`.mcpb`）— 即将推出 rebalance OS 也将作为 Claude Desktop 扩展程序发布。 扩展程序打包需要将所有 Python 依赖项捆绑到存档中。 此步骤尚未自动化 — 请使用上述手动配置进行日常使用。 有关扩展程序规范，请参见 [manifest.json](./manifest.json)。 ### 其他 MCP 主机 服务器与任何 MCP 兼容的客户端配合使用。 为以下客户端提供了配置文件： - **Claude Code** — `.mcp.json`（在 `cd rebalance-OS && claude` 时自动加载） - **VS Code（Copilot/Continue）** — `.vscode/mcp.json`（在打开工作区时自动加载） - **Claude Desktop** — 手动配置（参见上文）或扩展程序（`.mcpb`，即将推出） - **Cursor** — 参见 [MCP.md](./MCP.md) 以获取配置代码段 ### 焦点 5 浮动窗口（可选 macOS 菜单栏应用） 焦点 5 浮动窗口将您的实时焦点 5 名单显示为始终置顶的浮动卡堆栈，并具有离线缓存和一键“启动服务器”按钮。 **构建和安装：** ```bash cd macOS/Apps/Focus5Float ./make-app.sh # 发布构建 → ad-hoc 签名 → /Applications/Focus 5 Float.app ``` **二进制路径要求。** 应用启动时会启动 `rebalance serve`，但 macOS GUI 应用不会继承您的 shell `PATH`。 在系统可访问的路径上安装 `rebalance` 以使应用可以找到它： ```bash brew install pipx pipx install -e /path/to/rebalance-OS # → ~/.local/bin/rebalance ``` 应用直接检查 `~/.local/bin/rebalance` — 无需 shell。 如果未执行此步骤，应用将显示 _"找不到 `rebalance` 二进制"_。 有关完整的解析顺序和故障排除，请参阅 [macOS/Apps/Focus5Float/README.md](./macOS/Apps/Focus5Float/README.md)。 --- ## 代码智能 `ask-self` 是外部 RAG 代码和文档扫描器，用于为此仓库构建本地可查询索引，而无需在此处依赖其代码。 此仓库在**可移植模式**下运行 `ask-self`，使用**完全本地 Qwen 嵌入** — SQLite 索引提交在 [ask_self/index/rebalance-OS.sqlite](ask_self/index/rebalance-OS.sqlite)，因此全新克隆可以直接查询，无需导入且无需 API 密钥。 > 最后导入：2026-05-28 在 `fix/28-dev-install-fixes` 上进行强化可移植 `qwen-local` 刷新 ### 查询此仓库（无需设置） ```bash ./scripts/ask-self-query.sh "dashboard rendering 如何工作？" ``` 查询包装器将 `--db-path` 固定为已提交的便携式数据库，因此它在全新克隆上有效。 ### 刷新索引（仅限维护人员） ```bash ./scripts/ask-self-ingest.sh --mode all --no-architecture-md ``` 注释： - 包装器现在默认为 `--mode all`，如果省略 `--mode`，但在维护人员文档中保持显式以供参考更清晰。 - `--no-architecture-md` 是故意的：精选的 [ARCHITECTURE.md](ARCHITECTURE.md) 是手动编辑的，不应再生。 ### CLI 参考 所有工具也可用作 CLI 命令： ```bash rebalance ask "今天我应该处理什么？" --database rebalance.db rebalance ask "今天我应该处理什么？" --database rebalance.db --no-llm # 仅限原始上下文 rebalance query "嵌入管道" --database rebalance.db # 语义搜索 rebalance search "项目 alpha" --database rebalance.db # 关键字搜索 rebalance ingest notes --vault /path/to/vault --database rebalance.db # 重新导入（增量） rebalance ingest embed --database rebalance.db # 嵌入新块 rebalance github-scan --token <github-pat> --database rebalance.db # 刷新 GitHub 数据 rebalance github-close-candidates --repo owner/name --database rebalance.db # 打开的问题可能由合并的 PR 修复 rebalance calendar-sync --database rebalance.db # 刷新日历 rebalance calendar-daily-report # 今日事件 + 项目分解 rebalance calendar-weekly-report # 本周总结 + 聚合器 rebalance calendar-weekly-report --vault /path/to/vault --write-week-note # 编写 week-of-YYYY-MM-DD.md 并重新索引它 rebalance calendar-daily-totals # 每日事件计数 + 时长统计 ``` --- ## 许可证 Copyright 2025-2026 Hypercart DBA Neochrome, Inc. 在 Apache 2.0 许可证条款下许可使用。 您可以在 Apache 2.0 许可证条款下使用、复制、修改和分发此软件及其文档。 有关完整的许可证文本，请参阅 [APACHE-LICENSE-2.0.txt](./APACHE-LICENSE-2.0.txt)，或访问 https://www.apache.org/licenses/LICENSE-2.0。 --- ## 贡献 目前不开放贡献 — 先确保核心正确。 --- *由 [Hypercart](https://hypercart.com) 构建 — 面向在 WordPress 上构建的机构和独行创业者。