总体架构

DeepSec 采用 monorepo 形式组织，核心逻辑位于 packages/core 库内，命令行入口位于 packages/deepsec 包中。CLI 负责解析参数、加载配置、并把任务派发给 core 库中的运行器；core 库则负责与底层代理后端交互、控制批处理节奏、管理产物落盘。资料来源：README.md:1-40 资料来源：docs/architecture.md:1-60 资料来源：packages/deepsec/src/cli.ts:1-120

这种分层让 DeepSec 可以在不同代理后端之间切换，而不必改动 CLI 的使用方式。

核心组件

• CLI 入口 (packages/deepsec/src/cli.ts)：负责子命令（如 process、scan）的派发、参数校验，以及调用 core 库的运行接口。
• 运行器 (packages/core/src/run.ts)：负责把一次扫描任务拆分为多个批次（batch）、在每个批次内调度若干分析项（analysis），并驱动代理循环。
• 代理抽象层：在运行器之下，存在针对不同 LLM/CLI 后端的适配（如 Claude Code、Codex），社区已在 #21、#80 中请求增加 GitHub Copilot 与 Cursor CLI 适配。
• 导出器：将结果落盘为 md-dir 或 json 格式；社区 #40 提出增加 SARIF 2.1.0 导出以对接 GitHub Code Scanning 等 SAST 平台。资料来源：docs/data-layout.md:1-80

流水线阶段

一次完整的 DeepSec 运行大致经历四个阶段：

1. 发现与切分：扫描目标目录，把待分析的代码单元组织成批次。批次大小可配置，运行器会按批次推进。资料来源：packages/core/src/run.ts:1-100
2. 代理调查（investigation）：对批次内每个分析项，运行器调用代理后端进入 turn 循环；每一轮代理可使用工具查询代码，循环直到代理声明"investigation complete"。资料来源：packages/core/src/run.ts:100-200
3. 结果回收与汇总：将每轮代理的输出、工具调用统计、token 用量与费用回传，并写入中间状态。#33 中提到的"Turn 1 (5s, 0 tool calls) / Investigation complete (7.4s, 1 turns, 0 tool calls $0.000 0 tokens) / Batch 233/239 complete: 5 analyses"即来源于此阶段的日志格式。
4. 导出与落盘：最终结果按 data-layout.md 中定义的结构写入磁盘，CLI 再以 md-dir 或 json 形式呈现。

数据流与状态

下图概括了从 CLI 触发到结果产出的主要数据流向。

flowchart LR
  A[CLI 参数解析] --> B[core/run.ts 启动]
  B --> C[批次切分]
  C --> D[代理后端]
  D --> E[Turn 循环 / 工具调用]
  E --> F[结果回收]
  F --> G[中间状态落盘]
  G --> H[导出 md-dir / json]

已知限制与社区关注点

• 代理后端多样性：当前仅官方适配 Claude Code 与 Codex，#21、#80 反映用户希望把 Copilot、Cursor CLI/SDK 作为低成本替代纳入。资料来源：docs/architecture.md:60-120
• 速率限制处理：#33 中报告在 20x Max 计划下，因触发速率限制而中断批次执行，提示运行器需要更稳健的重试与退避策略。资料来源：packages/core/src/run.ts:200-260
• 进程生命周期：deepsec process 在 Codex 后端曾因二进制被外部删除导致 SIGKILL 后 ENOENT（#100），说明运行器对子进程异常退出需要更明确的恢复路径。
• 导出格式：当前 md-dir / json 与主流 SAST 生态存在集成缺口，#40 提议补齐 SARIF 输出以接入 GitHub Code Scanning、GitLab SAST、DefectDojo 等平台。资料来源：docs/data-layout.md:80-160

小结

DeepSec 的整体形态可概括为"CLI 调度 + core 库流水线 + 代理后端适配 + 结构化导出"。CLI 负责交互面，core 库的 run.ts 是流水线的真正主轴：它把扫描拆成批次，驱动代理 turn 循环，回收 token / 费用 / 调用统计，并按 data-layout.md 定义的布局落盘。社区关注点集中在代理可替换性、运行韧性（速率限制、进程崩溃）与行业标准导出（SARIF）三个方向，也是后续架构演进的主要着力点。资料来源：README.md:40-120 资料来源：docs/getting-started.md:1-80

概述

deepsec 通过统一的智能体层接入多种 AI 服务，使安全分析任务可在不同模型后端之间灵活切换。当前实现内置三种后端：Claude Code、Codex 与 Pi，分别对应 claude-agent-sdk.ts、codex-sdk.ts 与 pi-sdk.ts 三个适配器。社区中已有用户请求扩展 GitHub Copilot（#21）与 Cursor CLI（#80）作为新的后端选项，因此本模块在设计上需要具备良好的可扩展性。

资料来源：packages/processor/src/agents/types.ts:1-40

智能体架构

注册表与接口契约

agents/registry.ts 是所有可用后端的注册中心，processor 调度器通过名称查找并实例化对应的适配器。agents/types.ts 定义了所有智能体必须实现的统一契约，包括：

• 输入提示与上下文的标准化格式
• 流式事件（token、工具调用、状态变更）的输出协议
• 终止、取消与错误传播规则

由于不同后端的 SDK API 差异较大（Anthropic SDK、OpenAI Codex CLI、Pi API），每个适配器都负责将自身协议转换为统一接口，从而让上层调度逻辑与具体厂商解耦。

资料来源：packages/processor/src/agents/registry.ts:1-60 资料来源：packages/processor/src/agents/types.ts:1-80

架构流程图

graph TD
    P[Processor 调度器] --> R[Agent Registry]
    R --> C[claude-agent-sdk.ts]
    R --> X[codex-sdk.ts]
    R --> M[pi-sdk.ts]
    C --> A1[Claude 模型]
    X --> A2[Codex 模型]
    M --> A3[Pi 模型]
    A1 --> Q[统一事件流]
    A2 --> Q
    A3 --> Q
    Q --> P

支持的后端

Claude Code SDK

由 claude-agent-sdk.ts 实现，封装 Anthropic 官方 SDK，适用于 Claude Opus 与 Sonnet 系列。该后端在社区反馈 #33 中被报告：在 20x Max 套餐下进行大规模批处理时容易触发速率限制，导致批量任务（Batch 233/239）出现中断。

资料来源：packages/processor/src/agents/claude-agent-sdk.ts:1-80

Codex SDK

由 codex-sdk.ts 实现，依赖打包的 codex 可执行文件。该后端在 macOS 上曾出现稳定性问题：捆绑的二进制被系统标记并被 SIGKILL，随后再次启动时报 ENOENT（社区 #100）。需要在外层增加进程守护与重新拉起逻辑以提高可靠性。

资料来源：packages/processor/src/agents/codex-sdk.ts:1-80

Pi SDK

由 pi-sdk.ts 实现，提供第三种模型选择，作为 Claude 与 Codex 之外的备用路径，降低对单一供应商的依赖。

资料来源：packages/processor/src/agents/pi-sdk.ts:1-80

配置与模型选择

docs/models.md 是模型与配置的总览文档，列出了每个后端所支持的模型 ID、上下文窗口、推荐参数以及所需的环境变量（API Key、CLI 凭据等）。配置方式通常通过环境变量或 CLI 参数注入到 processor 中，再由 registry 转发给对应适配器。

速率限制与稳定性

由于 Claude Code 在大批量分析（数百 Batch）下容易触发平台速率限制（#33），建议在调度层加入指数退避与重试策略。Codex 后端则需要额外处理捆绑二进制的存活检测，避免因 macOS 安全策略误杀导致后续启动失败（#100）。当未来新增 GitHub Copilot（#21）或 Cursor CLI（#80）后端时，只需实现 types.ts 中定义的契约并在 registry.ts 中注册即可，无需改动核心调度逻辑。

资料来源：docs/models.md:1-60 资料来源：packages/processor/src/agents/registry.ts:60-120

概述

扫描器与匹配器生态系统是 DeepSec 项目中负责对目标仓库进行技术栈识别与安全模式匹配的核心子系统。该子系统位于 packages/scanner/src/ 目录下，由若干职责清晰的模块组成：入口文件 index.ts 负责串联整个扫描流程，detect-tech.ts 提供技术栈自动识别能力，matcher-registry.ts 管理可插拔的匹配器集合，而 matchers/ 子目录则承载具体的匹配器实现及其共享工具函数。该生态的设计目标是让 DeepSec 能够在不绑定特定 AI 智能体（Agent）的前提下，对任意代码仓库执行可复现的安全审计。

资料来源：packages/scanner/src/index.ts:1-1

技术栈检测

技术栈检测模块 detect-tech.ts 在扫描流程初期运行，用于推断目标仓库使用的语言、框架与运行时环境。该模块的输出将作为后续匹配器选择与提示词构造的依据，从而保证匹配器只针对相关的文件扩展名、依赖声明或代码结构生效，避免在无关文件上浪费分析预算。

技术栈识别的结果还会影响 DeepSec 与不同 Agent 后端（如 Claude Code、Codex 等）的协作方式。当扫描阶段将仓库判定为某种主流栈时，DeepSec 可以选择对应更擅长该语言的模型后端，这也间接关联到社区讨论 #21（GitHub Copilot）与 #80（Cursor CLI）所提出的"替换或扩展 Agent"诉求——新增 Agent 通常需要重新校验其对各技术栈的指令遵从能力。

资料来源：packages/scanner/src/detect-tech.ts:1-1

匹配器注册表

matcher-registry.ts 是整个匹配器生态的中枢。它负责加载、注册并对外暴露所有可用匹配器，使上层调用方能够以统一接口遍历匹配器列表，并将单个匹配结果聚合成最终的扫描报告。注册表的存在让匹配器具备了可插拔特性：新增一条安全检测规则只需实现匹配器接口并在注册表中登记，无需修改核心扫描逻辑。

下表展示了匹配器生态中关键模块的职责划分：

匹配器注册表同时承担了结果聚合的角色。在实际运行中（如社区讨论 #33 所反映的 rate limit 场景），当某一轮 Agent 调用受限导致匹配器输出截断，注册表能够保留已完成的中间结果，便于后续批次继续推进。

资料来源：packages/scanner/src/matcher-registry.ts:1-1、packages/scanner/src/matchers/index.ts:1-1

匹配器实现与编写指南

所有内置匹配器通过 matchers/index.ts 统一导出，并依赖 matchers/utils.ts 中封装的工具函数，例如模式匹配、上下文提取与敏感度分级等。匹配器的实现遵循统一的接口约定，从而保证它们能够被注册表透明地加载与执行。

官方文档 docs/writing-matchers.md 对如何开发新的匹配器提供了完整指引，覆盖匹配器签名、输入输出格式、单元测试要求以及与扫描流程的集成方式。该文档是扩展 DeepSec 检测能力的首选参考，使贡献者能够在不深入理解 Agent 后端的前提下，专注于安全规则的定义。

关于输出格式，社区讨论 #40 提出希望增加 SARIF 2.1.0 导出能力以对接 GitHub Code Scanning、Sonar 等 SAST 平台。这一扩展不会改动匹配器本身，但需要在 matcher-registry.ts 的结果聚合阶段增加 SARIF 转换逻辑，这意味着匹配器生态需要保持输出结构稳定，以便后续对接不同的报告格式。

资料来源：packages/scanner/src/matchers/utils.ts:1-1、docs/writing-matchers.md:1-1

社区反馈与扩展方向

从社区上下文来看，匹配器生态与 Agent 层的解耦是 DeepSec 当前设计上的关键优势。Issue #100 报告的 Codex 进程 SIGKILL 与 ENOENT 故障、以及 #33 中提到的速率限制问题，均位于 Agent 执行层而非匹配器层，说明匹配器本身具备良好的隔离性。后续若要引入 GitHub Copilot（#21）或 Cursor CLI（#80）作为新 Agent，只需保证匹配器输出契约不变即可平滑接入。

对于希望贡献匹配器的开发者，推荐路径是：阅读 docs/writing-matchers.md 了解接口约定 → 在 packages/scanner/src/matchers/ 下新增实现 → 通过 matchers/index.ts 注册 → 在 matcher-registry.ts 中验证加载逻辑。这一流程确保新增规则能够立即纳入 DeepSec 的扫描流水线。

资料来源：docs/writing-matchers.md:1-1、packages/scanner/src/matcher-registry.ts:1-1

1. 概览与核心职责

deepsec 在日常工程运维中承担「扫描 → 处理 → 复核 → 导出 → PR 评论」的链路角色。该链路覆盖三类用户场景：一次性安全扫描、增量复扫（CI/夜间任务）、以及通过 Pull Request 评论反馈到代码托管平台。

• scan.ts 负责发现阶段，在仓库中识别可疑点并生成分析批（batch）
• process.ts 驱动批处理循环，按预设预算调用 LLM Agent 执行深度分析
• revalidate.ts 在已有结论基础上做增量复核，适合在改动后快速回看
• export.ts 将内部结果转换为可选的下游格式
• preflight.ts 在命令运行前执行环境检查
• pr-comment.ts 负责把结果回写到 PR/MR 评论流

资料来源：packages/deepsec/src/commands/scan.ts:1-40

2. 典型运维工作流

2.1 阶段顺序

各阶段默认通过文件落盘解耦：scan 输出供 process 消费，process 输出供 revalidate/export 消费 资料来源：packages/deepsec/src/commands/process.ts:1-60。

2.2 数据流示意

flowchart LR
  A[scan] --> B[process]
  B --> C[(本地状态目录)]
  C --> D[revalidate]
  C --> E[export]
  C --> F[pr-comment]
  E --> G[下游平台]
  F --> H[Pull Request]

3. 常见故障与 preflight 处理

preflight.ts 是所有命令运行前的统一闸口，它负责验证：可执行 Agent (claude/codex) 是否就位、认证态是否过期、磁盘是否有足够空间、目录权限是否正确。一旦 preflight 失败，命令会提前退出，避免在错误状态下消耗 token 资料来源：packages/deepsec/src/preflight.ts:1-80。

3.1 高频失败模式

• Agent 后端不可用或被替换：用户在 issue #21 中希望支持 GitHub Copilot，在 #80 中询问 Cursor CLI/Composer 2.5。当前默认 Agent 为 Claude Code 或 Codex；当其他 CLI 缺失或不在 PATH 时，preflight 会直接失败，建议在切换前先以 --agent 或环境变量显式选择 资料来源：packages/deepsec/src/preflight.ts:40-90。
• Codex 进程异常终止：issue #100 报告当捆绑的 codex 二进制被移除或被 macOS 标记为隔离状态（"blocked because it contains malware"）时，process 会先记录 Codex Exec exited with signal SIGKILL，随后抛出 ENOENT。运维侧处理顺序：先清理隔离属性 xattr -d com.apple.quarantine，再确认 PATH 中存在可执行文件；preflight 应在此之前拦截 资料来源：packages/deepsec/src/commands/process.ts:60-140。
• 速率限制与预算耗尽：issue #33 反馈在 20x Max 套餐下仍会发生 rate limit，导致批次 233/239 后被截断。process.ts 每轮都会累加 token 与费用预算；当命中上限时会终止当前批次，但不会破坏已完成的结果文件——这意味着运维可以直接进入 revalidate 续跑，而非整体重头开始 资料来源：packages/deepsec/src/commands/process.ts:140-220。

4. 导出与外部系统集成

4.1 内置导出目标

export.ts 当前内置至少两种格式：md-dir（按文件目录组织的 Markdown）与 json（结构化原始数据）。两者的取舍如下：

• md-dir：适合人工审阅、归档、邮件附件
• json：适合二次处理、对接内部仪表盘

资料来源：packages/deepsec/src/commands/export.ts:1-120。

4.2 缺失的 SARIF 集成

issue #40 明确指出当前没有 SARIF 2.1.0 导出，因此无法直接接入 GitHub Code Scanning、GitLab SAST、Sonar、DefectDojo 等标准 SAST 平台。从仓库结构看，export.ts 是扩展的合适位置：增加一个新 writer 即可复用 process 与 revalidate 已经规范化好的结果模型，而不需要改动扫描或处理逻辑 资料来源：packages/deepsec/src/commands/export.ts:60-160。

4.3 PR 评论回写

pr-comment.ts 负责把导出结果裁剪为可读评论投递到代码托管平台。它通常消费 md-dir 的产物，避免在评论流中暴露 JSON 原始字段。如果需要同时投递 SARIF，建议在 pr-comment.ts 中加入对 SARIF artifact 的间接引用，而非重新实现一遍 资料来源：packages/deepsec/src/pr-comment.ts:1-90。

5. 运维建议清单

1. 在 CI 中把 preflight 与主命令串接，使环境问题提前暴露 资料来源：packages/deepsec/src/preflight.ts:1-40
2. 长任务启用增量模式：使用 revalidate 续跑而非 process 全量 资料来源：packages/deepsec/src/commands/revalidate.ts:1-60
3. 监控 token 与费用预算增长曲线，在接近 20x 套餐上限时切换为更低成本的 Agent（如未来支持 Copilot 后的轻量模型）
4. 在 macOS 上预先执行 xattr -d com.apple.quarantine 处理隔离标签，避免 Codex 进程被 SIGKILL
5. 若需要企业 SAST 集成，跟踪 SARIF 写入器的进展，必要时本地基于 export.ts 私有扩展

Pitfall Log / 踩坑日志

项目：vercel-labs/deepsec

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Codex process fails with SIGKILL then ENOENT after bundled codex binary is removed。

1. 安装坑 · 来源证据：Codex process fails with SIGKILL then ENOENT after bundled codex binary is removed

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex process fails with SIGKILL then ENOENT after bundled codex binary is removed
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/vercel-labs/deepsec/issues/100 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

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

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

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48964215 | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48964215 | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48964215 | no_demo; severity=medium

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

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

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

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