如果你已经开始用 Cursor、Claude Code、GitHub Copilot 这类 AI 编程代理大概率体会过这种纠结代理写业务逻辑很顺但一碰到第三方库就暴露出“热情但不懂规矩”的问题。它会帮你装一个依赖然后在代码里用出一个自带安全风险的 API它会假设你项目里的依赖都是最新版却完全不知道你已经锁定了生产基线它甚至可能为了让代码“看起来简洁”把数据库连接串直接写进配置文件。这个现象不是某个模型的“智商问题”而是当前大多数 AI 编程代理的工作方式决定的它从训练数据里总结出“大多数人怎么写”而不是“这个项目应该怎么写”。所以在库的选择和使用上它天然缺少项目上下文更缺少安全约束。最近在 Hacker News 上看到一个很值得展开的项目标题“Show HN: Guide AI coding agents on how to use libraries securely”。拆开看这句话其实包含了两个关键判断。第一它不是要“阻止”或“审核” AI coding agents而是要“指导”它们。第二指导的目标不是“选择安全库”这么简单而是“如何安全地使用库”。这个说法很短但做起来要复杂得多。所以这篇文章我先把结论放在前面让 AI 编程代理安全地使用第三方库不能靠“在提示词里多加一句请使用安全库”也不能靠人工事后审查代码。真正可落地的做法是把安全规则变成一种结构化输入让代理在生成代码时就能读取同时让 CI 在合并代码时能做强制校验。这套组合我把它称为“代理安全用库指南”。文章会从问题拆解、规则设计、完整示例、验证方法和最佳实践五个方向来展开。如果读完后你想在自己的项目里复刻基本上不需要改太多个性化配置照着第 5 部分的示例搭一套最小流程即可。1. 这篇文章真正要解决的问题1.1 不是“代理写错代码”而是“代理用错库”先区分一个容易被混淆的点。传统意义上的 AI 生成代码问题大多指逻辑错误、类型错误、边界条件不完整。这些问题在单元测试里通常能暴露一部分。但“用错库”是另一类问题它往往不会立刻让程序崩溃却在运行时把安全边界打开。举个例子一个 Python 项目需要读取用户上传的 YAML 文件。代理很自然地生成yaml.load(file)本地测试也完全正常。但yaml.load在历史上是反序列化安全风险的重灾区一旦 YAML 内容来自不可信来源攻击者可以构造特定 payload 触发任意对象构造。这类问题不会在功能测试里出现只会在生产环境被攻击时暴露。这就是本文要解决的问题核心AI 编程代理在引入库、调用库 API、配置库参数时缺少安全的“默认行为”。我们需要找到一种机制让代理在“use libraries”这一层就遵守安全约束。1.2 哪些团队最需要关心这件事个人开发者一个人同时写业务、管依赖、做运维没有专职安全人员审查代理生成的代码。小团队Agent 可能贡献了 30% 以上的代码但安全资源几乎为零。大团队多个成员、多个 Agent 并行开发如果没有统一规则每个 Agent 的“安全口味”都不一样。别等到依赖审计工具在 CI 里跑出一堆 CVE 告警才开始补救。CVE 修起来固然直接但代理在开发阶段反复生成不安全的库调用才是更隐蔽的生产力损耗。1.3 核心判断从项目标题看“Guide AI coding agents on how to use libraries securely”指向的是主动治理而不是被动扫描。我们可以把这件事做成一个工程化的三件套规则文件描述项目允许使用哪些库、必须满足什么版本、禁止调用哪些 API。Agent 上下文把规则文件作为项目上下文的强制部分让代理先读规则再写代码。CI 检查即使代理没遵守规则合并代码前也会被脚本拦下来。2. AI 编程代理为什么会在“用库”上失控2.1 代理的决策依据不等于安全依据AI 编程代理生成代码时本质是在做“基于上下文的概率预测”。它判断“这里该用什么库”依据的是训练语料里这种场景最常出现的写法而不是你项目的安全基线。举个例子当代理面对“加密一段文本”的任务时它可能会选择底层的 AES 代码片段把密钥直接硬编码进函数里。从模型的角度它确实完成了任务。但从工程角度这是一种既难维护又容易泄露密钥的写法。训练语料里的“高概率写法”并不等于“安全的写法”。2.2 上下文窗口有限规则被“稀释”现在很多代理工具支持把项目文档、README、架构说明放入上下文但真实项目的上下文空间是有限的。如果代理同时要理解业务逻辑、文件结构、测试代码、数据库 schema安全规则很容易被挤到“模糊记忆区”。一旦上下文超过有效范围代理就可能退回“最常见写法”模式。结果就是你明明在系统提示词里写过“不要使用 yaml.load”但代理生成完整工具函数时仍然可能为了一致性或简洁性写出旧 API。这不是代理故意作对而是规则没有进入它生成每个 token 时的强约束区。2.3 训练语料里的不安全示例太多AI 编程模型的训练语料来自公开代码库公开代码里存在大量历史遗留的不安全写法。比如 PHP 里直接拼接 SQL、Python 里用pickle.loads处理外部输入、JavaScript 里用eval解析 JSON。模型从这些语料里学到的是“这些写法在现实中被使用”而不是“这些写法应该被禁止”。2.4 缺少项目层面的“库治理记忆”团队里老成员知道这个项目不用 lodash因为包体积敏感那个服务不用subprocess.run(shellTrue)因为输入来自用户上传文件。这些都是项目特有的规则AI 编程代理不会自动知道除非我们显式提供。代理在“用库”上失控本质上不是模型不够聪明而是我们还没有把项目库治理规则变成它可读取、可执行、可被检查的信息。3. 重新理解“安全使用库”的三个层次在动手设计规则之前先把“安全使用库”这个概念拆成三个层次。任何一个层次掉链子最终都会表现为安全漏洞。3.1 依赖层次用不用、用什么版本这一层回答的是“代理应该引入哪个库引入后需要满足什么版本约束”。常见问题包括代理为了完成一个小功能引入一个二三十个传递依赖的重型库代理安装库时不锁版本导致第二次构建拉取到不一致的版本代理使用了某个库但这个库已经长时间不维护且存在公开安全通告。这一层适合用“规则文件 依赖审计”解决白名单、版本下限、禁止项。3.2 API 层次用哪个函数、怎么传参这一层回答的是“代理调用库的 API 时是否使用了安全写法”。典型例子同样操作 YAMLyaml.load和yaml.safe_load的安全等级完全不同同样执行系统命令subprocess.run(shellTrue)与列表参数方式的风险完全不同同样发起 HTTP 请求是否校验 HTTPS 证书、是否跟随重定向都有安全含义。这一层适合写在“代理规则说明”里并且在代码审查时重点检查。因为 API 调用是代码里最细颗粒度的地方通用扫描器不一定能理解你的上下文但明确的规则说明可以。3.3 配置与上下文层次密钥、端点、运行环境这一层回答的是“代理生成的代码是否会在运行时把敏感信息暴露出去”。例如把数据库密码写进config.py、把 JWT 密钥放进application.yml、把第三方 API Key 直接写在环境变量初始化的默认值里。这些隐患不会导致编译失败但会在仓库提交后扩散到所有能访问代码的人。这一层的规则应该和“环境变量注入”“密钥管理”这类工程规范放在一起让代理在生成配置类文件时优先读取占位符。理解这三个层次之后我们才能设计对路的规则。4. 方案设计规则文件 Agent 上下文 CI 门禁4.1 为什么“在提示词里多说一句”不够你可能会想那我写系统提示词的时候多写一句“请确保你使用的库是安全的不要使用不安全的 API不要硬编码密钥”不就行了吗不行。原因是自然语言提示有两个问题一是“安全”这个词太宽泛代理无法把它映射成具体的 API 禁用清单二是提示词默认没有“可检查性”。提示词说不能做的事代理可能这次遵守下次不遵守而且你无法在 CI 里验证。所以更靠谱的做法是把规则从“人类阅读的自然语言”升级成“代理可读取 脚本可检查”的结构化规则。4.2 三件套的组成整个方案可以分为三个部分rules规则文件存放依赖版本约束、禁用 API 清单、代理行为要求。Agent 启动上下文在项目级的AGENTS.md或工具对应的 rules 文件中强制代理先读取规则文件再开始生成代码。CI 门禁脚本在 pull request 阶段自动检查依赖声明、lockfile 和关键 API 调用不符合规则就阻断合并。这套组合的价值在于规则既能影响代理生成过程又能作为硬性门禁兜底。代理的“主观能动性”不一定可靠但 CI 检查是确定性的。4.3 规则文件应该写什么类别规则项示例作用依赖约束允许使用的库白名单cryptography允许自研加密算法禁止防止代理引入不必要的重型依赖版本约束最低版本要求PyYAML6.0.1防止代理选择有已知安全问题的旧版本禁用库禁止引入的库pickle处理外部数据时禁止阻断高风险依赖API 约束禁用 API 与推荐替代用yaml.safe_load替代yaml.load防止安全反模式进入代码配置约束禁止硬编码密钥密钥必须从环境变量读取防止敏感信息提交进代码库流程约束修改依赖必须更新 lockfile依赖变更后提交package-lock.json保证构建可复现4.4 规则要“少而准”不要写成一部法律代理的上下文空间是有限的。如果你把规则文件写成一份几千行的安全手册代理在生成代码时反而抓不住重点。建议只维护三类规则高风险 API 的禁用清单。依赖版本的红线。与当前项目强相关的密钥处理约定。其它通用安全知识交给团队的安全规范文档去承载不必都塞给 Agent。5. 完整示例给项目接一套“代理安全用库指南”下面用一个最小 Python 项目演示完整接入过程。这个项目的输入很简单提供一个 YAML 解析接口并需要处理用户上传的文件。项目结构如下your-project/ ├─ AGENTS.md ├─ requirements.txt ├─ security-rules/ │ ├─ python-deps.yaml │ └─ api-safety.md ├─ scripts/ │ └─ check_secure_library.py └─ .github/workflows/ └─ library-security.yml5.1 依赖规则文件python-deps.yaml文件路径security-rules/python-deps.yamllanguage: python dependency_rules: PyYAML: min_version: 6.0.1 reason: 项目安全基线 cryptography: min_version: 41.0.0 reason: 项目安全基线 requests: min_version: 2.31.0 reason: 项目安全基线 api_rules_file: api-safety.md这个文件的目的是给两方阅读一份给 Agent让它知道当前项目在依赖版本上不能低于多少一份给 CI 脚本让它自动检查requirements.txt是否符合版本下限。5.2 API 安全规则说明api-safety.md文件路径security-rules/api-safety.md# Python API 安全使用规则 ## YAML - 禁止使用 yaml.load(input, LoaderLoader) 形式。 - 必须使用 yaml.safe_load 解析来自外部输入的内容。 - 不要自定义 YAML Tag Loader除非经过安全评审。 ## requests - 默认必须校验 HTTPS 证书关闭证书校验只允许在测试环境使用。 - 禁止将 token 直接拼进 URL优先使用 headers 中的 Authorization 字段。 ## subprocess - 禁止使用 shellTrue 配合字符串拼接命令。 - 参数必须通过列表传递例如 subprocess.run([ls, -l])。 ## 数据库 - 禁止通过字符串拼接 SQL。 - 必须使用参数化查询或 ORM 的参数绑定机制。 ## 密钥 - 禁止在代码中硬编码密钥、Token、数据库连接串。 - 配置值必须从环境变量或密钥管理服务读取。这份文件对 Agent 来说是一份“编译期提示”对审查者来说是一份检查清单。实际项目中可以根据需要增加更多 API 条目。5.3 Agent 上下文文件AGENTS.md文件路径AGENTS.md# AGENTS.md 本仓库使用 AI 编程代理辅助开发。代理在执行任何需要修改依赖、新增第三方库、 调用外部 API 的任务前必须阅读并遵守以下规则 1. 新增或修改第三方依赖前先查看 security-rules/python-deps.yaml。 依赖版本不得低于该文件中的 min_version 要求。 2. 所有涉及外部输入的解析操作必须遵守 security-rules/api-safety.md。 3. 禁止通过 pip install xxx 直接安装依赖后把结果提交必须同步更新 requirements.txt并尽量生成可复现的锁定文件。 4. 禁止在代码中硬编码密钥、Token、数据库连接串。 5. 如果规则文件与训练数据中的常见写法冲突以规则文件为准。这里的关键词是“先阅读规则文件”。因为 Agent 工具普遍支持在项目根目录读取AGENTS.md这类约定文件所以这条规则会成为代理进入仓库后的第一个输入。5.4 依赖检查脚本check_secure_library.py文件路径scripts/check_secure_library.py#!/usr/bin/env python3 检查 requirements.txt 是否满足代理安全用库规则。 用法: python scripts/check_secure_library.py 返回值: 0 表示通过1 表示失败。 import re import sys from pathlib import Path import yaml RULES_FILE Path(security-rules/python-deps.yaml) REQ_FILES [requirements.txt] # 简单解析 requirements.txt支持以下格式 # package1.2.3 # package1.2.3 # package1.2.3,2.0 def parse_requirements(text: str) - dict[str, str]: deps {} for raw_line in text.splitlines(): line raw_line.strip() if not line: continue if line.startswith(#): continue if line.startswith(-): continue # 忽略 URL 或 git 依赖这里只做简单演示 if :// in line or line.startswith(git): continue # 提取包名和版本约束 match re.match(r([A-Za-z0-9_.-])\s*([!~])?\s*(.*), line) if not match: continue name match.group(1) operator match.group(2) or version match.group(3).strip() deps[name.lower()] f{operator}{version} return deps def extract_min_version(constraint: str) - str: 从约束中提取最小版本简化处理只支持 和 。 constraint constraint.strip() if constraint.startswith(): return constraint[2:].split(,)[0].strip() if constraint.startswith(): return constraint[2:].split(,)[0].strip() return 0 def version_tuple(version: str) - tuple: 把版本字符串粗略转成可比较的元组。 parts re.findall(r\d, version) return tuple(int(p) for p in parts) def main() - int: if not RULES_FILE.exists(): print([check] 未找到规则文件跳过检查) return 0 rules yaml.safe_load(RULES_FILE.read_text(encodingutf-8)) dependency_rules rules.get(dependency_rules, {}) deps {} for req_file in REQ_FILES: path Path(req_file) if path.exists(): deps.update(parse_requirements(path.read_text(encodingutf-8))) if not deps: print([check] 未发现依赖文件跳过检查) return 0 errors [] for package, rule in dependency_rules.items(): package_lower package.lower() min_version rule.get(min_version, 0) if package_lower not in deps: continue constraint deps[package_lower] current_min extract_min_version(constraint) if current_min 0: errors.append(f{package}: 未锁定明确版本当前约束: {constraint or 无}) continue if version_tuple(current_min) version_tuple(str(min_version)): errors.append( f{package}: 版本过低要求 {min_version}当前约束为 {constraint} ) if errors: print([check] 依赖安全检查未通过) for error in errors: print(f - {error}) return 1 print([check] 依赖安全检查通过) return 0 if __name__ __main__: sys.exit(main())这个脚本不追求上百个包管理器的完整兼容它的定位是“最小可用检查器”。如果你的项目使用的是requirements.txt它可以直接工作。如果项目更大建议在它基础上接各语言的官方 audit 工具。5.5 CI 门禁library-security.yml文件路径.github/workflows/library-security.ymlname: library-security on: pull_request: paths: - **/requirements*.txt - security-rules/** - scripts/check_secure_library.py jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.12 - name: 安装检查依赖 run: pip install pyyaml - name: 检查依赖安全规则 run: | python scripts/check_secure_library.py - name: 依赖审计补充信息 run: | pip install pip-audit pip-audit -r requirements.txt --strict这个 workflow 会在每次 Pull Request 变更依赖文件时自动运行。如果代理改了requirements.txt但版本低于安全基线check_secure_library.py会返回 1PR 就会被阻断。5.6 代理工具接入的通用做法不同工具读取项目规则的方式不完全一致但思路相同把AGENTS.md和security-rules作为项目的一部分提交到仓库并在工具的 rules 配置中引用项目根目录。Cursor 等支持 Rules 的编辑器在项目根目录或.cursor/rules下提供规则文件。Claude Code、Codex CLI 等命令行工具直接使用项目根目录的AGENTS.md。GitHub Copilot可以引用.github/copilot-instructions.md。无论哪种方式核心都是一件事让规则文件存在于代理能够读取的路径中。如果代理不读取规则就只是给人看的文档。6. 运行与效果验证6.1 最小验证场景建议用两个场景对比验证这套机制是否生效。场景 A不加载规则直接提问“写一段代码解析用户上传的 YAML 文件并返回 dict”。预期行为代理大概率生成yaml.load(file)或yaml.load(file, Loaderyaml.FullLoader)虽然有风险但能完成任务。场景 B让代理先读取AGENTS.md再提问同样的问题。预期行为代理应该使用yaml.safe_load(file)并且在生成代码时避免把密钥硬编码进同一段代码。6.2 如何判断成功可以按下面四个标准来判断代理是否使用了api-safety.md中推荐的替代 API。代理生成的依赖版本是否满足python-deps.yaml的最低版本要求。代理是否主动修改了 lockfile 或requirements.txt而不是只执行安装命令。代码中是否仍然出现硬编码密钥或明显的命令拼接。如果以上任意一条不满足先检查规则文件是否进入了代理上下文再检查规则本身是否写得太模糊。6.3 本地运行检查脚本在本地运行以下命令模拟 CI 的检查过程pip install pyyaml python scripts/check_secure_library.py echo $?如果requirements.txt中有低于规则的版本会看到输出[check] 依赖安全检查未通过 - PyYAML: 版本过低要求 6.0.1当前约束为 5.4.1此时返回码是 1。这样的测试不用等 Pull Request本地就能提前发现规则是否被绕过。7. 常见问题与排查思路问题现象可能原因排查方式解决方案代理还是生成 yaml.load规则文件没有进入上下文检查当前会话是否读取了 AGENTS.md在会话中显式引用security-rules/api-safety.md代理忽略版本下限只有描述没有可检查机制运行 check 脚本查看返回码确保 CI 里执行python scripts/check_secure_library.py规则文件太大量生成变慢上下文被规则占满查看工具使用的 token 统计精简规则只保留高风险 API 和版本红线代理修改了 requirements 但没生成 lockfile代理工具依赖安装行为默认不写 lock检查 diff 中是否存在 lockfile 变化在 AGENTS.md 中加一条“必须提交 lockfile”CI 中检查CI 里没有跑脚本workflow 路径过滤写错查看 Actions 运行记录去掉 paths 过滤先默认全量执行项目用别的包管理器脚本只支持 requirements.txt查看包管理器的锁文件格式扩展脚本或直接调用官方 audit 命令这里比较常见的一个误区是以为只要把规则文件放在仓库里代理“应该”会自动读。实际上很多工具需要你显式打开规则引用或者把文件放在特定目录。排查时先确认工具的 rules 配置有没有生效再看规则内容。8. 最佳实践与工程建议8.1 规则当作代码来管理安全规则文件要交给团队评审、要记录变更历史、要写清楚“为什么”。例如dependency_rules: PyYAML: min_version: 6.0.1 reason: 2023 年维护版本修复已知序列化与加载器问题加reason字段不只是给代理看更是给团队成员看的。半年后有人问“这个版本下限能不能降”可以直接翻到规则文件的理由。8.2 规则要能被脚本消费而不只是被人类阅读写规则时尽量使用结构化格式比如 YAML、JSON。纯 Markdown 适合给人读但脚本解析起来很脆弱。结构化格式的好处是Agent 可以读CI 脚本也可以读规则因此变成“机器可执行的知识”。如果必须用 Markdown也尽量保持固定的小节标题方便脚本做简单的 keyword 检查。8.3 把审计工具接入 CI但不要只靠审计工具pip-audit、npm audit、Trivy这类工具能发现“已知漏洞的依赖”但它们解决不了“代理使用了错误 API”这类问题。安全用库的最小组合应该是规则文件约束“能不能用这个库”。Agent 上下文指导“怎么用这个库”。CI 脚本检查“依赖版本是否达标”。代码评审时查看有没有违反 API 安全规则。审计工具是辅助不是兜底。8.4 给 Agent 的“可执行样例”比说教更有效规则里可以附带安全代码片段。例如api-safety.md中直接写明# 安全写法 import yaml with open(user.yaml, encodingutf-8) as f: data yaml.safe_load(f)代理对“示例”的遵循度通常高于对“禁令”的遵循度。给它一个正确的样例比反复写“不要做某事”更有效。8.5 不要把所有安全知识都塞进 Agent 上下文上下文窗口是宝贵的资源。Agent 是生成代码的助手不是安全合规系统。团队的安全规范手册、威胁建模文档、历史漏洞复盘适合放在知识库或 Wiki 里不适合塞进每次生成任务都读取的上下文。放进 Agent 上下文的只保留最直接影响代码产出的规则。8.6 先做最小闭环再逐步扩展第一次接入时不建议一次性配置十几条规则。先做最小闭环只针对当前项目最常用的两个库建立版本下限。只写一条最重要的 API 禁用规则。跑通一个 CI 检查任务。等这套流程稳定再逐步扩展其他语言、其他库、更多规则项。这样迭代规则质量会更高。9. 总结与后续学习方向回头看标题中的这句话——“Guide AI coding agents on how to use libraries securely”——它其实点明了这个阶段 AI 编程代理真正需要补上的一块短板。代理不缺写代码的能力缺的是项目自身的约束信息。而我们给代理提供什么样的上下文决定了它交付代码的安全水位。本文用一个最小 Python 项目演示了这套思路的具体落地方案把安全规则写成结构化 YAML 和 Markdown放到项目根目录通过AGENTS.md强制代理在编码前阅读再用一个 Python 脚本在 CI 里检查依赖版本是否达标同时配合pip-audit、npm audit这类工具做漏洞底数排查。如果你希望继续深入下面几个方向值得关注给规则文件增加“许可证明细”让代理在引入新库前核对许可证是否与当前项目兼容。引入更完整的依赖锁定方案例如pip-tools或uv让锁文件成为依赖管理的唯一事实来源。把安全规则接入公司的统一 Agent 平台让不同项目共享同一套基础安全规则。尝试让 Agent 在生成代码时自动附带“安全自查结果”减少人工审查成本。安全用库这件事不会因为换了更强的模型就自动解决。模型变强生成代码的质量上限会提高但“项目约束”始终要由人来提供。给 Agent 一套清晰、结构化、可检查的规则是现阶段最值得做的工程投入。建议把这套流程作为你项目规范的一部分尽早落地。
如果你已经开始用 Cursor、Claude Code、GitHub Copilot 这类 AI 编程代理大概率体会过这种纠结代理写业务逻辑很顺但一碰到第三方库就暴露出“热情但不懂规矩”的问题。它会帮你装一个依赖然后在代码里用出一个自带安全风险的 API它会假设你项目里的依赖都是最新版却完全不知道你已经锁定了生产基线它甚至可能为了让代码“看起来简洁”把数据库连接串直接写进配置文件。这个现象不是某个模型的“智商问题”而是当前大多数 AI 编程代理的工作方式决定的它从训练数据里总结出“大多数人怎么写”而不是“这个项目应该怎么写”。所以在库的选择和使用上它天然缺少项目上下文更缺少安全约束。最近在 Hacker News 上看到一个很值得展开的项目标题“Show HN: Guide AI coding agents on how to use libraries securely”。拆开看这句话其实包含了两个关键判断。第一它不是要“阻止”或“审核” AI coding agents而是要“指导”它们。第二指导的目标不是“选择安全库”这么简单而是“如何安全地使用库”。这个说法很短但做起来要复杂得多。所以这篇文章我先把结论放在前面让 AI 编程代理安全地使用第三方库不能靠“在提示词里多加一句请使用安全库”也不能靠人工事后审查代码。真正可落地的做法是把安全规则变成一种结构化输入让代理在生成代码时就能读取同时让 CI 在合并代码时能做强制校验。这套组合我把它称为“代理安全用库指南”。文章会从问题拆解、规则设计、完整示例、验证方法和最佳实践五个方向来展开。如果读完后你想在自己的项目里复刻基本上不需要改太多个性化配置照着第 5 部分的示例搭一套最小流程即可。1. 这篇文章真正要解决的问题1.1 不是“代理写错代码”而是“代理用错库”先区分一个容易被混淆的点。传统意义上的 AI 生成代码问题大多指逻辑错误、类型错误、边界条件不完整。这些问题在单元测试里通常能暴露一部分。但“用错库”是另一类问题它往往不会立刻让程序崩溃却在运行时把安全边界打开。举个例子一个 Python 项目需要读取用户上传的 YAML 文件。代理很自然地生成yaml.load(file)本地测试也完全正常。但yaml.load在历史上是反序列化安全风险的重灾区一旦 YAML 内容来自不可信来源攻击者可以构造特定 payload 触发任意对象构造。这类问题不会在功能测试里出现只会在生产环境被攻击时暴露。这就是本文要解决的问题核心AI 编程代理在引入库、调用库 API、配置库参数时缺少安全的“默认行为”。我们需要找到一种机制让代理在“use libraries”这一层就遵守安全约束。1.2 哪些团队最需要关心这件事个人开发者一个人同时写业务、管依赖、做运维没有专职安全人员审查代理生成的代码。小团队Agent 可能贡献了 30% 以上的代码但安全资源几乎为零。大团队多个成员、多个 Agent 并行开发如果没有统一规则每个 Agent 的“安全口味”都不一样。别等到依赖审计工具在 CI 里跑出一堆 CVE 告警才开始补救。CVE 修起来固然直接但代理在开发阶段反复生成不安全的库调用才是更隐蔽的生产力损耗。1.3 核心判断从项目标题看“Guide AI coding agents on how to use libraries securely”指向的是主动治理而不是被动扫描。我们可以把这件事做成一个工程化的三件套规则文件描述项目允许使用哪些库、必须满足什么版本、禁止调用哪些 API。Agent 上下文把规则文件作为项目上下文的强制部分让代理先读规则再写代码。CI 检查即使代理没遵守规则合并代码前也会被脚本拦下来。2. AI 编程代理为什么会在“用库”上失控2.1 代理的决策依据不等于安全依据AI 编程代理生成代码时本质是在做“基于上下文的概率预测”。它判断“这里该用什么库”依据的是训练语料里这种场景最常出现的写法而不是你项目的安全基线。举个例子当代理面对“加密一段文本”的任务时它可能会选择底层的 AES 代码片段把密钥直接硬编码进函数里。从模型的角度它确实完成了任务。但从工程角度这是一种既难维护又容易泄露密钥的写法。训练语料里的“高概率写法”并不等于“安全的写法”。2.2 上下文窗口有限规则被“稀释”现在很多代理工具支持把项目文档、README、架构说明放入上下文但真实项目的上下文空间是有限的。如果代理同时要理解业务逻辑、文件结构、测试代码、数据库 schema安全规则很容易被挤到“模糊记忆区”。一旦上下文超过有效范围代理就可能退回“最常见写法”模式。结果就是你明明在系统提示词里写过“不要使用 yaml.load”但代理生成完整工具函数时仍然可能为了一致性或简洁性写出旧 API。这不是代理故意作对而是规则没有进入它生成每个 token 时的强约束区。2.3 训练语料里的不安全示例太多AI 编程模型的训练语料来自公开代码库公开代码里存在大量历史遗留的不安全写法。比如 PHP 里直接拼接 SQL、Python 里用pickle.loads处理外部输入、JavaScript 里用eval解析 JSON。模型从这些语料里学到的是“这些写法在现实中被使用”而不是“这些写法应该被禁止”。2.4 缺少项目层面的“库治理记忆”团队里老成员知道这个项目不用 lodash因为包体积敏感那个服务不用subprocess.run(shellTrue)因为输入来自用户上传文件。这些都是项目特有的规则AI 编程代理不会自动知道除非我们显式提供。代理在“用库”上失控本质上不是模型不够聪明而是我们还没有把项目库治理规则变成它可读取、可执行、可被检查的信息。3. 重新理解“安全使用库”的三个层次在动手设计规则之前先把“安全使用库”这个概念拆成三个层次。任何一个层次掉链子最终都会表现为安全漏洞。3.1 依赖层次用不用、用什么版本这一层回答的是“代理应该引入哪个库引入后需要满足什么版本约束”。常见问题包括代理为了完成一个小功能引入一个二三十个传递依赖的重型库代理安装库时不锁版本导致第二次构建拉取到不一致的版本代理使用了某个库但这个库已经长时间不维护且存在公开安全通告。这一层适合用“规则文件 依赖审计”解决白名单、版本下限、禁止项。3.2 API 层次用哪个函数、怎么传参这一层回答的是“代理调用库的 API 时是否使用了安全写法”。典型例子同样操作 YAMLyaml.load和yaml.safe_load的安全等级完全不同同样执行系统命令subprocess.run(shellTrue)与列表参数方式的风险完全不同同样发起 HTTP 请求是否校验 HTTPS 证书、是否跟随重定向都有安全含义。这一层适合写在“代理规则说明”里并且在代码审查时重点检查。因为 API 调用是代码里最细颗粒度的地方通用扫描器不一定能理解你的上下文但明确的规则说明可以。3.3 配置与上下文层次密钥、端点、运行环境这一层回答的是“代理生成的代码是否会在运行时把敏感信息暴露出去”。例如把数据库密码写进config.py、把 JWT 密钥放进application.yml、把第三方 API Key 直接写在环境变量初始化的默认值里。这些隐患不会导致编译失败但会在仓库提交后扩散到所有能访问代码的人。这一层的规则应该和“环境变量注入”“密钥管理”这类工程规范放在一起让代理在生成配置类文件时优先读取占位符。理解这三个层次之后我们才能设计对路的规则。4. 方案设计规则文件 Agent 上下文 CI 门禁4.1 为什么“在提示词里多说一句”不够你可能会想那我写系统提示词的时候多写一句“请确保你使用的库是安全的不要使用不安全的 API不要硬编码密钥”不就行了吗不行。原因是自然语言提示有两个问题一是“安全”这个词太宽泛代理无法把它映射成具体的 API 禁用清单二是提示词默认没有“可检查性”。提示词说不能做的事代理可能这次遵守下次不遵守而且你无法在 CI 里验证。所以更靠谱的做法是把规则从“人类阅读的自然语言”升级成“代理可读取 脚本可检查”的结构化规则。4.2 三件套的组成整个方案可以分为三个部分rules规则文件存放依赖版本约束、禁用 API 清单、代理行为要求。Agent 启动上下文在项目级的AGENTS.md或工具对应的 rules 文件中强制代理先读取规则文件再开始生成代码。CI 门禁脚本在 pull request 阶段自动检查依赖声明、lockfile 和关键 API 调用不符合规则就阻断合并。这套组合的价值在于规则既能影响代理生成过程又能作为硬性门禁兜底。代理的“主观能动性”不一定可靠但 CI 检查是确定性的。4.3 规则文件应该写什么类别规则项示例作用依赖约束允许使用的库白名单cryptography允许自研加密算法禁止防止代理引入不必要的重型依赖版本约束最低版本要求PyYAML6.0.1防止代理选择有已知安全问题的旧版本禁用库禁止引入的库pickle处理外部数据时禁止阻断高风险依赖API 约束禁用 API 与推荐替代用yaml.safe_load替代yaml.load防止安全反模式进入代码配置约束禁止硬编码密钥密钥必须从环境变量读取防止敏感信息提交进代码库流程约束修改依赖必须更新 lockfile依赖变更后提交package-lock.json保证构建可复现4.4 规则要“少而准”不要写成一部法律代理的上下文空间是有限的。如果你把规则文件写成一份几千行的安全手册代理在生成代码时反而抓不住重点。建议只维护三类规则高风险 API 的禁用清单。依赖版本的红线。与当前项目强相关的密钥处理约定。其它通用安全知识交给团队的安全规范文档去承载不必都塞给 Agent。5. 完整示例给项目接一套“代理安全用库指南”下面用一个最小 Python 项目演示完整接入过程。这个项目的输入很简单提供一个 YAML 解析接口并需要处理用户上传的文件。项目结构如下your-project/ ├─ AGENTS.md ├─ requirements.txt ├─ security-rules/ │ ├─ python-deps.yaml │ └─ api-safety.md ├─ scripts/ │ └─ check_secure_library.py └─ .github/workflows/ └─ library-security.yml5.1 依赖规则文件python-deps.yaml文件路径security-rules/python-deps.yamllanguage: python dependency_rules: PyYAML: min_version: 6.0.1 reason: 项目安全基线 cryptography: min_version: 41.0.0 reason: 项目安全基线 requests: min_version: 2.31.0 reason: 项目安全基线 api_rules_file: api-safety.md这个文件的目的是给两方阅读一份给 Agent让它知道当前项目在依赖版本上不能低于多少一份给 CI 脚本让它自动检查requirements.txt是否符合版本下限。5.2 API 安全规则说明api-safety.md文件路径security-rules/api-safety.md# Python API 安全使用规则 ## YAML - 禁止使用 yaml.load(input, LoaderLoader) 形式。 - 必须使用 yaml.safe_load 解析来自外部输入的内容。 - 不要自定义 YAML Tag Loader除非经过安全评审。 ## requests - 默认必须校验 HTTPS 证书关闭证书校验只允许在测试环境使用。 - 禁止将 token 直接拼进 URL优先使用 headers 中的 Authorization 字段。 ## subprocess - 禁止使用 shellTrue 配合字符串拼接命令。 - 参数必须通过列表传递例如 subprocess.run([ls, -l])。 ## 数据库 - 禁止通过字符串拼接 SQL。 - 必须使用参数化查询或 ORM 的参数绑定机制。 ## 密钥 - 禁止在代码中硬编码密钥、Token、数据库连接串。 - 配置值必须从环境变量或密钥管理服务读取。这份文件对 Agent 来说是一份“编译期提示”对审查者来说是一份检查清单。实际项目中可以根据需要增加更多 API 条目。5.3 Agent 上下文文件AGENTS.md文件路径AGENTS.md# AGENTS.md 本仓库使用 AI 编程代理辅助开发。代理在执行任何需要修改依赖、新增第三方库、 调用外部 API 的任务前必须阅读并遵守以下规则 1. 新增或修改第三方依赖前先查看 security-rules/python-deps.yaml。 依赖版本不得低于该文件中的 min_version 要求。 2. 所有涉及外部输入的解析操作必须遵守 security-rules/api-safety.md。 3. 禁止通过 pip install xxx 直接安装依赖后把结果提交必须同步更新 requirements.txt并尽量生成可复现的锁定文件。 4. 禁止在代码中硬编码密钥、Token、数据库连接串。 5. 如果规则文件与训练数据中的常见写法冲突以规则文件为准。这里的关键词是“先阅读规则文件”。因为 Agent 工具普遍支持在项目根目录读取AGENTS.md这类约定文件所以这条规则会成为代理进入仓库后的第一个输入。5.4 依赖检查脚本check_secure_library.py文件路径scripts/check_secure_library.py#!/usr/bin/env python3 检查 requirements.txt 是否满足代理安全用库规则。 用法: python scripts/check_secure_library.py 返回值: 0 表示通过1 表示失败。 import re import sys from pathlib import Path import yaml RULES_FILE Path(security-rules/python-deps.yaml) REQ_FILES [requirements.txt] # 简单解析 requirements.txt支持以下格式 # package1.2.3 # package1.2.3 # package1.2.3,2.0 def parse_requirements(text: str) - dict[str, str]: deps {} for raw_line in text.splitlines(): line raw_line.strip() if not line: continue if line.startswith(#): continue if line.startswith(-): continue # 忽略 URL 或 git 依赖这里只做简单演示 if :// in line or line.startswith(git): continue # 提取包名和版本约束 match re.match(r([A-Za-z0-9_.-])\s*([!~])?\s*(.*), line) if not match: continue name match.group(1) operator match.group(2) or version match.group(3).strip() deps[name.lower()] f{operator}{version} return deps def extract_min_version(constraint: str) - str: 从约束中提取最小版本简化处理只支持 和 。 constraint constraint.strip() if constraint.startswith(): return constraint[2:].split(,)[0].strip() if constraint.startswith(): return constraint[2:].split(,)[0].strip() return 0 def version_tuple(version: str) - tuple: 把版本字符串粗略转成可比较的元组。 parts re.findall(r\d, version) return tuple(int(p) for p in parts) def main() - int: if not RULES_FILE.exists(): print([check] 未找到规则文件跳过检查) return 0 rules yaml.safe_load(RULES_FILE.read_text(encodingutf-8)) dependency_rules rules.get(dependency_rules, {}) deps {} for req_file in REQ_FILES: path Path(req_file) if path.exists(): deps.update(parse_requirements(path.read_text(encodingutf-8))) if not deps: print([check] 未发现依赖文件跳过检查) return 0 errors [] for package, rule in dependency_rules.items(): package_lower package.lower() min_version rule.get(min_version, 0) if package_lower not in deps: continue constraint deps[package_lower] current_min extract_min_version(constraint) if current_min 0: errors.append(f{package}: 未锁定明确版本当前约束: {constraint or 无}) continue if version_tuple(current_min) version_tuple(str(min_version)): errors.append( f{package}: 版本过低要求 {min_version}当前约束为 {constraint} ) if errors: print([check] 依赖安全检查未通过) for error in errors: print(f - {error}) return 1 print([check] 依赖安全检查通过) return 0 if __name__ __main__: sys.exit(main())这个脚本不追求上百个包管理器的完整兼容它的定位是“最小可用检查器”。如果你的项目使用的是requirements.txt它可以直接工作。如果项目更大建议在它基础上接各语言的官方 audit 工具。5.5 CI 门禁library-security.yml文件路径.github/workflows/library-security.ymlname: library-security on: pull_request: paths: - **/requirements*.txt - security-rules/** - scripts/check_secure_library.py jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.12 - name: 安装检查依赖 run: pip install pyyaml - name: 检查依赖安全规则 run: | python scripts/check_secure_library.py - name: 依赖审计补充信息 run: | pip install pip-audit pip-audit -r requirements.txt --strict这个 workflow 会在每次 Pull Request 变更依赖文件时自动运行。如果代理改了requirements.txt但版本低于安全基线check_secure_library.py会返回 1PR 就会被阻断。5.6 代理工具接入的通用做法不同工具读取项目规则的方式不完全一致但思路相同把AGENTS.md和security-rules作为项目的一部分提交到仓库并在工具的 rules 配置中引用项目根目录。Cursor 等支持 Rules 的编辑器在项目根目录或.cursor/rules下提供规则文件。Claude Code、Codex CLI 等命令行工具直接使用项目根目录的AGENTS.md。GitHub Copilot可以引用.github/copilot-instructions.md。无论哪种方式核心都是一件事让规则文件存在于代理能够读取的路径中。如果代理不读取规则就只是给人看的文档。6. 运行与效果验证6.1 最小验证场景建议用两个场景对比验证这套机制是否生效。场景 A不加载规则直接提问“写一段代码解析用户上传的 YAML 文件并返回 dict”。预期行为代理大概率生成yaml.load(file)或yaml.load(file, Loaderyaml.FullLoader)虽然有风险但能完成任务。场景 B让代理先读取AGENTS.md再提问同样的问题。预期行为代理应该使用yaml.safe_load(file)并且在生成代码时避免把密钥硬编码进同一段代码。6.2 如何判断成功可以按下面四个标准来判断代理是否使用了api-safety.md中推荐的替代 API。代理生成的依赖版本是否满足python-deps.yaml的最低版本要求。代理是否主动修改了 lockfile 或requirements.txt而不是只执行安装命令。代码中是否仍然出现硬编码密钥或明显的命令拼接。如果以上任意一条不满足先检查规则文件是否进入了代理上下文再检查规则本身是否写得太模糊。6.3 本地运行检查脚本在本地运行以下命令模拟 CI 的检查过程pip install pyyaml python scripts/check_secure_library.py echo $?如果requirements.txt中有低于规则的版本会看到输出[check] 依赖安全检查未通过 - PyYAML: 版本过低要求 6.0.1当前约束为 5.4.1此时返回码是 1。这样的测试不用等 Pull Request本地就能提前发现规则是否被绕过。7. 常见问题与排查思路问题现象可能原因排查方式解决方案代理还是生成 yaml.load规则文件没有进入上下文检查当前会话是否读取了 AGENTS.md在会话中显式引用security-rules/api-safety.md代理忽略版本下限只有描述没有可检查机制运行 check 脚本查看返回码确保 CI 里执行python scripts/check_secure_library.py规则文件太大量生成变慢上下文被规则占满查看工具使用的 token 统计精简规则只保留高风险 API 和版本红线代理修改了 requirements 但没生成 lockfile代理工具依赖安装行为默认不写 lock检查 diff 中是否存在 lockfile 变化在 AGENTS.md 中加一条“必须提交 lockfile”CI 中检查CI 里没有跑脚本workflow 路径过滤写错查看 Actions 运行记录去掉 paths 过滤先默认全量执行项目用别的包管理器脚本只支持 requirements.txt查看包管理器的锁文件格式扩展脚本或直接调用官方 audit 命令这里比较常见的一个误区是以为只要把规则文件放在仓库里代理“应该”会自动读。实际上很多工具需要你显式打开规则引用或者把文件放在特定目录。排查时先确认工具的 rules 配置有没有生效再看规则内容。8. 最佳实践与工程建议8.1 规则当作代码来管理安全规则文件要交给团队评审、要记录变更历史、要写清楚“为什么”。例如dependency_rules: PyYAML: min_version: 6.0.1 reason: 2023 年维护版本修复已知序列化与加载器问题加reason字段不只是给代理看更是给团队成员看的。半年后有人问“这个版本下限能不能降”可以直接翻到规则文件的理由。8.2 规则要能被脚本消费而不只是被人类阅读写规则时尽量使用结构化格式比如 YAML、JSON。纯 Markdown 适合给人读但脚本解析起来很脆弱。结构化格式的好处是Agent 可以读CI 脚本也可以读规则因此变成“机器可执行的知识”。如果必须用 Markdown也尽量保持固定的小节标题方便脚本做简单的 keyword 检查。8.3 把审计工具接入 CI但不要只靠审计工具pip-audit、npm audit、Trivy这类工具能发现“已知漏洞的依赖”但它们解决不了“代理使用了错误 API”这类问题。安全用库的最小组合应该是规则文件约束“能不能用这个库”。Agent 上下文指导“怎么用这个库”。CI 脚本检查“依赖版本是否达标”。代码评审时查看有没有违反 API 安全规则。审计工具是辅助不是兜底。8.4 给 Agent 的“可执行样例”比说教更有效规则里可以附带安全代码片段。例如api-safety.md中直接写明# 安全写法 import yaml with open(user.yaml, encodingutf-8) as f: data yaml.safe_load(f)代理对“示例”的遵循度通常高于对“禁令”的遵循度。给它一个正确的样例比反复写“不要做某事”更有效。8.5 不要把所有安全知识都塞进 Agent 上下文上下文窗口是宝贵的资源。Agent 是生成代码的助手不是安全合规系统。团队的安全规范手册、威胁建模文档、历史漏洞复盘适合放在知识库或 Wiki 里不适合塞进每次生成任务都读取的上下文。放进 Agent 上下文的只保留最直接影响代码产出的规则。8.6 先做最小闭环再逐步扩展第一次接入时不建议一次性配置十几条规则。先做最小闭环只针对当前项目最常用的两个库建立版本下限。只写一条最重要的 API 禁用规则。跑通一个 CI 检查任务。等这套流程稳定再逐步扩展其他语言、其他库、更多规则项。这样迭代规则质量会更高。9. 总结与后续学习方向回头看标题中的这句话——“Guide AI coding agents on how to use libraries securely”——它其实点明了这个阶段 AI 编程代理真正需要补上的一块短板。代理不缺写代码的能力缺的是项目自身的约束信息。而我们给代理提供什么样的上下文决定了它交付代码的安全水位。本文用一个最小 Python 项目演示了这套思路的具体落地方案把安全规则写成结构化 YAML 和 Markdown放到项目根目录通过AGENTS.md强制代理在编码前阅读再用一个 Python 脚本在 CI 里检查依赖版本是否达标同时配合pip-audit、npm audit这类工具做漏洞底数排查。如果你希望继续深入下面几个方向值得关注给规则文件增加“许可证明细”让代理在引入新库前核对许可证是否与当前项目兼容。引入更完整的依赖锁定方案例如pip-tools或uv让锁文件成为依赖管理的唯一事实来源。把安全规则接入公司的统一 Agent 平台让不同项目共享同一套基础安全规则。尝试让 Agent 在生成代码时自动附带“安全自查结果”减少人工审查成本。安全用库这件事不会因为换了更强的模型就自动解决。模型变强生成代码的质量上限会提高但“项目约束”始终要由人来提供。给 Agent 一套清晰、结构化、可检查的规则是现阶段最值得做的工程投入。建议把这套流程作为你项目规范的一部分尽早落地。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
