Copy

Qoder Agent SDK 内置代码安全能力，让 Agent 在生成和修改代码的同时检查自身产出，并可按需审计整个仓库，在自动化流程中守住安全底线。三个开关默认全部关闭。安全扫描会额外消耗轮次和积分，因此不会自动开启，需由应用按会话显式启用。两种语言均支持该选项：TypeScript 为 securityScan，开关名采用驼峰式；Python 为 security_scan，开关名采用下划线式。

三个级别

三个级别相互独立，按需开启。

开关（TypeScript / Python）	作用范围	触发时机
`l1StaticCheck` / `l1_static_check`	Agent 刚修改的文件	在受支持的文件编辑后自动执行
`l2LightweightScan` / `l2_lightweight_scan`	仓库级，浅层扫描	由 Agent 判断需要扫描时执行
`l3DeepScan` / `l3_deep_scan`	仓库级，深度扫描	由 Agent 判断需要深度审计时执行

l1StaticCheck 针对 Agent 自身改动做兜底检查，开销最小。l2LightweightScan 和 l3DeepScan 是授予 Agent 扫描仓库的能力，并非每轮强制执行。

开启扫描

import { query } from '@qoder-ai/qoder-agent-sdk';

for await (const message of query({
  prompt: '实现密码重置接口',
  options: {
    securityScan: {
      l1StaticCheck: true,
      l2LightweightScan: true,
    },
  },
})) {
  console.log(message);
}

一种常见的分级策略：

功能开发：仅开启 l1StaticCheck，让 Agent 检查自身改动，同时不明显拉长单轮耗时。
合并前评审：追加 l2LightweightScan。
定时审计：追加 l3DeepScan，交由时间预算充足的任务执行。

该选项覆盖设置，而非合并

一旦传入 securityScan，本次会话即以其为准：设置文件或 settings 对象中的 securityScan 配置块整体失效，未显式列出的开关一律置为 false。

// settings.json 中含有：{ "securityScan": { "l1StaticCheck": true } }

options: {
  settings: './settings.json',
  securityScan: { l3DeepScan: true },
}

// 实际生效结果 —— l1StaticCheck 已被关闭：
// { l1StaticCheck: false, l2LightweightScan: false, l3DeepScan: true }

Python 侧使用 security_scan 时规则相同。设置中的其他键不受影响，仅 securityScan 这一块被替换。若需某个开关继续生效，应在选项中重新声明。完全不传 securityScan 时，由设置文件决定。

校验在进程启动前完成

非法取值会立即报错，且发生在 Qoder CLI 启动之前——开关拼写错误会当场暴露，而非被静默忽略。

options: { securityScan: { l2LightweightScann: true } }
// TypeError: securityScan contains unknown option: l2LightweightScann

options: { securityScan: { l1StaticCheck: 'yes' } }
// TypeError: securityScan.l1StaticCheck must be a boolean

验证是否生效

开启任一开关后，会话即暴露内置的 security-scan 能力。可从初始化结果中读回：

const q = query({ prompt: userMessages(), options: { securityScan: { l2LightweightScan: true } } });

const init = await q.initializationResult();
const enabled = init.skills?.some(
  (skill) => skill.name === 'security-scan' && skill.source === 'built-in',
);
console.log(enabled); // true

不传 securityScan 时，该项不会出现。

扫描不等于权限控制

这两套机制解决的是不同问题，不能相互替代：

机制	解决的问题
`securityScan`	Agent 能否检查代码中的漏洞
权限控制	Agent 是否被允许执行某个工具、访问某个路径

安全扫描负责发现代码中的问题，并不限制 Agent 的行为。仅开启 l3DeepScan 而未配置权限策略的 Agent，仍可执行任意命令。两者需同时配置。

下一步

权限控制 —— 限制 Agent 可访问的工具与路径
Hooks —— 在工具调用执行前拦截或改写
Skills —— 控制会话向模型暴露哪些能力

​三个级别

​开启扫描

​该选项覆盖设置，而非合并

​校验在进程启动前完成

​验证是否生效

​扫描不等于权限控制