# https://github.com/wenjiazhu1980/deepcode-macos 项目说明书

生成时间：2026-07-31 07:45:06 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-packages-cli-src)
- [Src 模块](#page-packages-core-src)
- [Src 模块](#page-packages-vscode-ide-companion-src)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-packages-cli-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/README.md)
- [apps/macos-menubar/DeepCode/Resources/sidecar/package.json](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/apps/macos-menubar/DeepCode/Resources/sidecar/package.json)
- [apps/macos-menubar/README.md](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/apps/macos-menubar/README.md)
- [package.json](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/package.json)
- [packages/cli/package.json](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/cli/package.json)
- [packages/core/package.json](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/core/package.json)
</details>

# 项目概览

## 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/sidecar` | Node.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. 核心子系统与运行机制

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

```mermaid
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` 字段正是该入口的来源。

---

<a id='page-packages-cli-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-packages-core-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cli/src/cli-args.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/cli/src/cli-args.ts)
- [packages/cli/src/cli.tsx](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/cli/src/cli.tsx)
- [packages/cli/src/clientFactory.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/cli/src/clientFactory.ts)
- [packages/cli/src/common/update-check.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/cli/src/common/update-check.ts)
- [packages/cli/src/exec-input.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/cli/src/exec-input.ts)
- [packages/cli/src/exec-runner.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/cli/src/exec-runner.ts)
</details>

# 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.tsx` | UI 入口与顶层组件 | 进程启动 |
| `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` | 版本检测 | 启动阶段 |

## 数据流概览

```mermaid
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]()

---

<a id='page-packages-core-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-packages-cli-src), [Src 模块](#page-packages-vscode-ide-companion-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/src/common/bash-timeout.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/core/src/common/bash-timeout.ts)
- [packages/core/src/common/debug-logger.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/core/src/common/debug-logger.ts)
- [packages/core/src/common/error-logger.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/core/src/common/error-logger.ts)
- [packages/core/src/common/file-history.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/core/src/common/file-history.ts)
- [packages/core/src/common/file-utils.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/core/src/common/file-utils.ts)
- [packages/core/src/common/llm-error.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/core/src/common/llm-error.ts)
</details>

# Src 模块

## 模块定位与目录结构

`packages/core/src` 是 deepcode-macos 核心包（`@deepcode/core`）的源码根目录，承载与 macOS 平台 UI 无关的领域逻辑、工具函数与基础设施实现。该目录按职责划分为若干子目录，其中 `common/` 子目录集中放置跨模块复用的通用工具与基础设施实现，向上层（会话管理、Agent、LLM 调用、文件操作等）提供可组合的 API。

```mermaid
graph TD
    A[packages/core/src] --> B[common/]
    A --> C[session/]
    A --> D[agent/]
    A --> E[llm/]
    A --> F[file/]
    B --> B1[bash-timeout.ts]
    B --> B2[debug-logger.ts]
    B --> B3[error-logger.ts]
    B --> B4[file-history.ts]
    B --> B5[file-utils.ts]
    B --> B6[llm-error.ts]
```

`common/` 目录的设计目标是解耦"通用横切关注点"与"领域功能"——任何上层模块都可以按需引入而不携带具体业务副作用。资料来源：[packages/core/src/common/bash-timeout.ts:1-30]()

## 核心职责

### Shell 与超时控制

`bash-timeout.ts` 抽象了 shell 命令执行的超时与取消语义，使上层 Agent 在执行 `Bash` 工具调用时能够基于统一的超时策略挂起或终止子进程，避免 macOS 上长任务阻塞会话主循环。该模块通常与进程句柄、AbortSignal 协作，对外暴露"限时执行 + 可取消"的能力。资料来源：[packages/core/src/common/bash-timeout.ts:1-50]()

### 日志与错误体系

`debug-logger.ts` 与 `error-logger.ts` 分别提供分级调试输出与错误聚合能力。调试日志通常以命名空间（namespace）粒度开启，便于在排查 LLM 流式响应、文件 diff 等场景时定位问题；错误日志则将异常统一格式化后写入诊断通道，是 v0.4.x 系列反复迭代稳定性改进时的重要观测面。资料来源：[packages/core/src/common/debug-logger.ts:1-40]()；[packages/core/src/common/error-logger.ts:1-40]()

### 文件操作与历史

`file-utils.ts` 提供对工作区文件的安全读取、写入与编码探测等原子工具，屏蔽 Node.js `fs` 在不同平台上的行为差异；`file-history.ts` 则记录每次写入对应的原始内容，用于实现"撤销修改 / 还原到上一步"以及在 Agent 误改后由用户回滚，是会话交互安全性的关键保障。资料来源：[packages/core/src/common/file-utils.ts:1-60]()；[packages/core/src/common/file-history.ts:1-60]()

### LLM 错误归一化

`llm-error.ts` 将上游模型供应商返回的异构错误（限流、上下文超长、内容过滤、网络中断等）归一化为内部错误类型，使上层 UI 能以一致的方式展示重试、降级或切换模型的提示。资料来源：[packages/core/src/common/llm-error.ts:1-50]()

## 与上层模块的协作

`common/` 中的工具被会话层（如 v0.4.5 中提到的 `session.ts`）直接复用：会话在接收用户消息时通过 `file-utils` 预处理粘贴图片，并在调用 LLM 之前借助 `llm-error` 的类型守卫决定是否触发 fallback MCP 工具或内置 vision API 流程。日志与错误工具则为整条调用链提供可观测性，使社区反馈的"图片被误送文本模型""⌘V 粘贴失效"等问题能被快速定位与修复。资料来源：[packages/core/src/common/file-utils.ts:1-30]()；[packages/core/src/common/llm-error.ts:1-30]()

## 演进观察

从 v0.4.5 → v0.4.15 的多次发布看，`common/` 层的能力密度持续提升：错误归一化与日志分级伴随着 LLM 调用策略的调整而迭代；`file-history` 与 `file-utils` 在涉及文件改动与图片粘贴的修复（v0.4.5）中起到基础设施作用。该目录因此被视为核心包的"稳定基座"，其变更通常以小步快跑方式推进，以保证上层 Agent 与 UI 的兼容性。资料来源：[packages/core/src/common/error-logger.ts:1-20](); [packages/core/src/common/debug-logger.ts:1-20]()

---

<a id='page-packages-vscode-ide-companion-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-packages-core-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/vscode-ide-companion/src/extension.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/vscode-ide-companion/src/extension.ts)
- [packages/vscode-ide-companion/src/provider.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/vscode-ide-companion/src/provider.ts)
- [packages/vscode-ide-companion/src/utils.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/vscode-ide-companion/src/utils.ts)
- [packages/vscode-ide-companion/src/session.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/vscode-ide-companion/src/session.ts)
- [packages/vscode-ide-companion/src/commands.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/vscode-ide-companion/src/commands.ts)
- [packages/vscode-ide-companion/src/auth.ts](https://github.com/wenjiazhu1980/deepcode-macos/blob/main/packages/vscode-ide-companion/src/auth.ts)
</details>

# Src 模块

## 概述与定位

`packages/vscode-ide-companion/src/` 是 deepcode-macos 项目中 VS Code 配套扩展（IDE Companion）的核心源码目录，承载与编辑器交互的 TypeScript 实现。它作为宿主编排层与编辑器协议层之间的桥梁，通过 VS Code Extension API 注册命令、提供侧边栏视图、维护会话状态，并将视图相关消息以结构化载荷推送给外部 CLI 进程。

资料来源：[packages/vscode-ide-companion/src/extension.ts:1-30]()

该模块遵循典型的 VS Code 扩展结构：单一 `activate` 入口注册 `commands`、Tree/View、提供者与事件订阅；其职责范围聚焦于「编辑器侧集成」，而非 LLM 推理或聊天 UI 的渲染（后者由主应用层承担）。

## 关键文件与职责分工

| 文件 | 职责范围 |
|------|---------|
| `extension.ts` | 扩展激活/停用生命周期、注册命令、绑定 Provider |
| `provider.ts` | 实现 TreeDataProvider/WebviewViewProvider，向上层暴露数据 |
| `session.ts` | 会话状态机、消息预处理（含图像始终预处理） |
| `utils.ts` | 通用辅助方法（路径处理、URI 转换、剪贴板解析） |
| `commands.ts` | 命令 ID 常量与命令执行的薄封装 |
| `auth.ts` | 与外部 CLI 的鉴权握手与令牌刷新 |

资料来源：[packages/vscode-ide-companion/src/session.ts:1-20](), [packages/vscode-ide-companion/src/utils.ts:1-15]()

社区版本演进反映了该模块的关注点：v0.4.5 在 `session.ts` 中加入「always 预处理图片」逻辑，防止原始图像被误发至纯文本模型，并在 `extension.ts` 中新增 `onPasteCommand` 处理器，使 ⌘V 真正支持粘贴图片。资料来源：[packages/vscode-ide-companion/src/session.ts:120-160](), [packages/vscode-ide-companion/src/extension.ts:80-110]()

## 核心工作流

扩展激活时，`extension.ts` 调用 `registerCommands` 注册命令，并通过 `vscode.window.registerWebviewViewProvider` 绑定 `provider.ts` 中的数据源；用户触发粘贴或选择文件时，`session.ts` 介入进行载荷标准化——文本直接透传，图像则转为 base64/数据结构并打上 `processed` 标记，确保下游始终以 vision 友好的格式对外发出。

```mermaid
flowchart LR
  A[VS Code 事件] --> B[extension.ts]
  B --> C[commands.ts]
  B --> D[provider.ts]
  C --> E[session.ts]
  E --> F{载荷类型}
  F -->|文本| G[直接序列化]
  F -->|图像| H[预处理+标记]
  G --> I[下游 CLI]
  H --> I
```

资料来源：[packages/vscode-ide-companion/src/extension.ts:30-90](), [packages/vscode-ide-companion/src/session.ts:40-120]()

## 鉴权与外部通信

`auth.ts` 负责与本地 CLI 守护进程建立信任关系：在 `activate` 阶段读取本地 socket 或文件中的短期令牌，并在令牌过期前通过 `refresh` 流程换取新凭证。`utils.ts` 提供与 VS Code URI、文件系统路径互转的纯函数，使扩展在不同操作系统（macOS 为主要目标平台）下保持行为一致。

资料来源：[packages/vscode-ide-companion/src/auth.ts:1-50](), [packages/vscode-ide-companion/src/utils.ts:20-60]()

## 已知演进与社区关注点

从 v0.4.5 到 v0.4.15 的多次小版本迭代中，`src/` 模块持续围绕「图像识别可靠性」打磨：v0.4.5 引入内置 vision API 调用，避免依赖 Python/MCP；后续版本不断调整 `session.ts` 中的预处理顺序与 `provider.ts` 的刷新策略。社区反馈集中在粘贴图片失败、文本模型收到图像数据等场景，相关修复均落在 `session.ts` 与 `extension.ts` 的命令处理路径上。

资料来源：[packages/vscode-ide-companion/src/session.ts:1-200](), [packages/vscode-ide-companion/src/extension.ts:1-200]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: wenjiazhu1980/deepcode-macos; human_manual_source: deepwiki_human_wiki -->