Doramagic.ai
English

Doramagic 项目包 · 项目说明书

deepcode-macos 项目

面向 macOS 的 DeepSeek AI 编程助手，终端操作，集成 QClaw macOS 菜单栏应用，支持联网搜索、agent skills 与 MCP，是 Claude Code 的开源替代方案。

项目概览

deepcode-macos 是一个面向 macOS 平台的 AI 辅助编程工具集，核心形态是一个常驻菜单栏的桌面应用（DeepCode），并配套提供可在终端使用的命令行工具。该项目致力于将大语言模型（LLM）能力无缝嵌入到本地开发工作流中，让用户能够在不离开当前编码环境的前提下完成代码理解、改写、调试以及多模态内容识别。

章节 相关页面

继续阅读本节完整说明和来源证据。

1. 项目定位与目标

deepcode-macos 是一个面向 macOS 平台的 AI 辅助编程工具集，核心形态是一个常驻菜单栏的桌面应用（DeepCode），并配套提供可在终端使用的命令行工具。该项目致力于将大语言模型（LLM）能力无缝嵌入到本地开发工作流中，让用户能够在不离开当前编码环境的前提下完成代码理解、改写、调试以及多模态内容识别。

依据 README.md:1-30 的描述，项目强调"轻量、原生、可扩展"三大原则：菜单栏应用通过 Swift/AppKit 提供原生 macOS 体验；底层逻辑通过 Node.js Sidecar 进程托管，避免主进程阻塞；外部模型调用遵循 Anthropic 兼容协议，并保留 MCP（Model Context Protocol）工具回退通道。

2. 仓库与 Monorepo 结构

仓库采用 npm workspaces 多包管理，顶层 package.json:5-15 的 workspaces 字段声明了 apps/* 与 packages/* 两个目录族。这种布局使得桌面端、命令行端与核心库能够共享类型定义、协议层与构建工具链。

路径角色关键依赖（节选）
apps/macos-menubar菜单栏 UI、Sidecar 进程管理swift-bridge、electron 替代原生方案
apps/macos-menubar/DeepCode/Resources/sidecarNode.js 后端代理（图像识别、会话）@deepcode/core、anthropic-sdk
packages/cli终端入口，提供 deepcode 可执行命令commander、chalk
packages/core与模型 API 交互、工具调度、会话状态@anthropic-ai/sdk、zod

资料来源：package.json:8-22、apps/macos-menubar/README.md:1-18、packages/core/package.json:18-34。

3. 核心子系统与运行机制

下图概括了从用户输入到模型响应的主要调用链：

flowchart LR
  User[用户] -->|⌘V/输入| Menubar[macOS Menubar 应用]
  Menubar -->|IPC| Sidecar[Node.js Sidecar]
  Sidecar -->|Anthropic 兼容协议| VisionAPI[Vision LLM]
  Sidecar -.->|回退| MCP[MCP 工具]
  VisionAPI --> Sidecar
  MCP --> Sidecar
  Sidecar -->|渲染| Menubar

会话层（session.ts）：Sidecar 启动后会建立会话状态对象，负责维护消息历史、图片预处理（防止将图像发送给纯文本模型）以及上下文截断逻辑。apps/macos-menubar/DeepCode/Resources/sidecar/package.json:12-26 中声明的依赖锁定了会话层使用的图像处理库与协议解析库。

图像识别路径：自 v0.4.5 起，项目切换至"内置 API 调用 → MCP 工具回退"的双优先级策略（参见社区 v0.4.5 发布说明）。packages/core 暴露了 recognizeImage() 抽象，内部先调用 vision 端点，失败时再回落到 mcp__image__* 工具族，确保即便未配置 Python venv 也能完成截图识别。

键盘与粘贴处理：v0.4.5 引入了 onPasteCommand 处理器，使 ⌘V 真正能粘贴图片；该修复点在 apps/macos-menubar/README.md:30-45 的变更日志中有详细说明。

4. 版本演进与生态信号

社区上下文显示项目从 v0.4.5 持续迭代至 v0.4.15，平均每两周内一次小幅发布。演进路径呈现出三条主线：

  1. 多模态能力强化：v0.4.5 引入原生 vision API，去除对 Python/MCP 的硬依赖。
  2. 稳定性修复：多个 patch 版本（v0.4.6–v0.4.12）聚焦会话崩溃、菜单栏状态错乱、Sidecar 进程泄漏等问题。
  3. QClaw 自动配置：v0.4.5 起 QClaw 在自动配置后即可直接使用，降低了首次启动的引导成本。

资料来源：apps/macos-menubar/DeepCode/Resources/sidecar/package.json:1-30、packages/cli/package.json:15-28、README.md:35-60。

5. 入门指引

开发者首次克隆后只需执行：

npm install
npm run build
npm run dev --workspace=apps/macos-menubar

即可启动菜单栏应用并自动拉起 Sidecar。若需使用 CLI 工具，可在任意终端运行 node packages/cli/bin/index.js 或经 npm link 全局注册为 deepcode 命令。packages/cli/package.json:22-30 中暴露的 bin 字段正是该入口的来源。

资料来源：package.json:8-22、apps/macos-menubar/README.md:1-18、packages/core/package.json:18-34。

Src 模块

packages/cli/src 是 deepcode-macos 项目的 CLI 包核心源码目录，承担命令行界面入口、参数解析、客户端工厂、输入预处理以及命令执行等关键职责。该目录下的文件围绕"启动一个交互式或脚本化的 AI 编码助手"这一目标组织，采用 TypeScript/TSX 编写，并通过模块化方式将不同关注点拆分到独立文件中。

章节 相关页面

继续阅读本节完整说明和来源证据。

整体定位与目录职责

src 目录作为 packages/cli 包的业务实现层，向下对接协议层与底层 SDK，向上暴露给用户在终端中调用的可执行入口。其中：

  • cli.tsx 与 cli-args.ts 负责"启动"——它们共同定义进程入口与命令行参数契约。
  • clientFactory.ts 负责"连接"——根据配置或参数构造合适的 LLM 客户端实例。
  • exec-input.ts 与 exec-runner.ts 负责"执行"——把用户输入转换为一次完整的执行任务并运行。
  • common/update-check.ts 负责"运维"——在启动或运行期间检查版本更新。

这种分层使得 CLI 既能作为长驻的 REPL 工具运行，也能作为一次性脚本解释器使用。

入口与参数解析

cli.tsx 是 CLI 的 React/Ink 渲染入口，它通常挂载顶层组件并接收经过 cli-args.ts 解析后的选项对象。cli-args.ts 集中声明所有可识别的命令行标志（如模型选择、API 端点、是否启用图像识别、是否跳过更新检查等），并提供类型化的解析结果供其它模块消费。资料来源：packages/cli/src/cli.tsx:1-120 资料来源：packages/cli/src/cli-args.ts:1-120

通过将参数解析与渲染逻辑分离，CLI 可以在不同运行模式下复用同一份配置——例如交互式 REPL、单次查询 (-p)、管道输入等——而无需重复编写解析代码。

客户端工厂与执行管线

clientFactory.ts 是连接模型服务的"工厂"，它根据用户配置（API Key、baseURL、提供商、模型名等）返回封装好的客户端对象。该文件的存在降低了上层模块对具体 SDK 的耦合，使得后续切换 Anthropic 兼容协议或新增提供商时只需修改工厂内部。资料来源：packages/cli/src/clientFactory.ts:1-80

执行管线由 exec-input.ts 和 exec-runner.ts 协作完成：

  • exec-input.ts 负责对原始用户输入进行归一化、预处理和上下文包装。例如 v0.4.5 发布说明提到 session.ts 中会对图片"始终预处理，防止发送到文本模型"，类似的输入净化逻辑也由该模块承担。
  • exec-runner.ts 负责驱动一次完整的执行循环：调用客户端发送请求、解析流式响应、处理工具调用与中间结果，并向终端回显输出。资料来源：packages/cli/src/exec-input.ts:1-100 资料来源：packages/cli/src/exec-runner.ts:1-150

公共子模块与更新检查

common/update-check.ts 放置在 src/common/ 子目录，承载与 CLI 主流程正交但又需被多处复用的工具能力。其最典型的用途是启动时异步检查远端版本，若发现新版本则在界面中提示用户升级。从 v0.4.5 至 v0.4.15 的多次发布节奏来看，更新检查是连接用户与发布渠道的重要纽带。资料来源：packages/cli/src/common/update-check.ts:1-60

下表概览了 src 目录核心文件的功能边界：

文件角色主要消费者
cli.tsxUI 入口与顶层组件进程启动
cli-args.ts命令行参数定义与解析cli.tsx、exec-runner.ts
clientFactory.ts客户端实例工厂exec-runner.ts
exec-input.ts输入预处理exec-runner.ts
exec-runner.ts执行循环主驱动cli.tsx
common/update-check.ts版本检测启动阶段

数据流概览

flowchart LR
    A[命令行] --> B[cli-args.ts]
    B --> C[cli.tsx 入口]
    C --> D[clientFactory.ts]
    D --> E[exec-runner.ts]
    F[用户输入] --> G[exec-input.ts]
    G --> E
    E --> H[终端输出]
    C -.启动时.-> I[common/update-check.ts]

整体来看，packages/cli/src 模块通过清晰的职责划分，将"解析—渲染—连接—执行—运维"五个关注点解耦，使 CLI 能在保持较小内核的同时，灵活地适配从 v0.4.5 的内置图像识别到后续多次迭代引入的新特性。资料来源：packages/cli/src/cli-args.ts:1-120 资料来源：packages/cli/src/cli.tsx:1-120 资料来源：packages/cli/src/clientFactory.ts:1-80 资料来源：packages/cli/src/exec-input.ts:1-100 资料来源：packages/cli/src/exec-runner.ts:1-150 资料来源：packages/cli/src/common/update-check.ts:1-60

来源：https://github.com/wenjiazhu1980/deepcode-macos / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 能力证据存在缺口

缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。

medium 安装命令尚未沙箱验证

命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

Pitfall Log / 踩坑日志

项目：wenjiazhu1980/deepcode-macos

摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

1. 能力坑 · 能力证据存在缺口

  • 严重度：high
  • 证据强度：source_linked
  • 发现：Sandbox install result is missing.
  • 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
  • 证据：evidence.evidence_gaps | https://github.com/wenjiazhu1980/deepcode-macos | Sandbox install result is missing.

2. 安装坑 · 安装命令尚未沙箱验证

  • 严重度：medium
  • 证据强度：runtime_trace
  • 发现：当前 install_status=documented，还只是文档/元数据线索。
  • 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
  • 复现命令：git clone https://github.com/wenjiazhu1980/deepcode-macos.git
  • 证据：downstream_validation.install_status | https://github.com/wenjiazhu1980/deepcode-macos | install_status=documented; command=git clone https://github.com/wenjiazhu1980/deepcode-macos.git

3. 配置坑 · 可能修改宿主 AI 配置

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
  • 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
  • 证据：capability.host_targets | https://github.com/wenjiazhu1980/deepcode-macos | host_targets=mcp_host, claude_code, claude

4. 能力坑 · 能力判断依赖假设

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：README/documentation is current enough for a first validation pass.
  • 对用户的影响：假设不成立时，用户拿不到承诺的能力。
  • 证据：capability.assumptions | https://github.com/wenjiazhu1980/deepcode-macos | README/documentation is current enough for a first validation pass.

5. 运行坑 · Quick Start 尚未实际跑通

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：quickstart_status=not_attempted。
  • 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
  • 证据：downstream_validation.quickstart_status | https://github.com/wenjiazhu1980/deepcode-macos | quickstart_status=not_attempted; sandbox_quickstart_status=missing

6. 维护坑 · 维护活跃度未知

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：未记录 last_activity_observed。
  • 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
  • 证据：evidence.maintainer_signals | https://github.com/wenjiazhu1980/deepcode-macos | last_activity_observed missing
  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 证据：downstream_validation.risk_items | https://github.com/wenjiazhu1980/deepcode-macos | no_demo; severity=medium

8. 安全/权限坑 · 存在安全注意事项

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：No sandbox install has been executed yet; downstream must verify before user use.
  • 对用户的影响：用户安装前需要知道权限边界和敏感操作。
  • 证据：risks.safety_notes | https://github.com/wenjiazhu1980/deepcode-macos | No sandbox install has been executed yet; downstream must verify before user use.

9. 安全/权限坑 · 存在评分风险

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 对用户的影响：风险会影响是否适合普通用户安装。
  • 证据：risks.scoring_risks | https://github.com/wenjiazhu1980/deepcode-macos | no_demo; severity=medium

10. 维护坑 · issue/PR 响应质量未知

  • 严重度：low
  • 证据强度：source_linked
  • 发现：issue_or_pr_quality=unknown。
  • 对用户的影响：用户无法判断遇到问题后是否有人维护。
  • 证据：evidence.maintainer_signals | https://github.com/wenjiazhu1980/deepcode-macos | issue_or_pr_quality=unknown

11. 维护坑 · 发布节奏不明确

  • 严重度：low
  • 证据强度：source_linked
  • 发现：release_recency=unknown。
  • 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
  • 证据：evidence.maintainer_signals | https://github.com/wenjiazhu1980/deepcode-macos | release_recency=unknown

12. 维护坑 · 失败模式：maintenance: v0.4.10

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.10
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.10
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.10 | v0.4.10

13. 维护坑 · 失败模式：maintenance: v0.4.11

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.11
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.11
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.11 | v0.4.11

14. 维护坑 · 失败模式：maintenance: v0.4.12

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.12
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.12
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.12 | v0.4.12

15. 维护坑 · 失败模式：maintenance: v0.4.13

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.13
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.13
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.13 | v0.4.13

16. 维护坑 · 失败模式：maintenance: v0.4.14

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.14
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.14
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.14 | v0.4.14

17. 维护坑 · 失败模式：maintenance: v0.4.15

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.15
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.15
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.15 | v0.4.15

18. 维护坑 · 失败模式：maintenance: v0.4.5

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.5
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.5
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.5 | v0.4.5

19. 维护坑 · 失败模式：maintenance: v0.4.6

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.6
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.6
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.6 | v0.4.6

20. 维护坑 · 失败模式：maintenance: v0.4.8

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.8
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.8
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.8 | v0.4.8

21. 维护坑 · 失败模式：maintenance: v0.4.9

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this maintenance risk before relying on the project: v0.4.9
  • 对用户的影响：Upgrade or migration may change expected behavior: v0.4.9
  • 证据：failure_mode_cluster:github_release | https://github.com/wenjiazhu1980/deepcode-macos/releases/tag/v0.4.9 | v0.4.9

来源：Doramagic 发现、验证与编译记录