CAI 开发环境与贡献指南VS Code 容器化开发、Pre-commit 提交流程与遥测数据策略【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/caiCybersecurity AICAI是一个面向 AI 安全研究的开源框架本文基于仓库中的开发文档docs/cai_development.md并结合源码实现系统讲解 CAI 开发者的完整工作流如何在 VS Code 开发容器中搭建开发环境、如何通过 Pre-commit 规范化提交代码、当前可选扩展caiextensions的整合状态、使用数据收集遥测的采集范围与关闭方式以及如何在本地复现 CI/CD 的运行环境。读完本文你将能够独立搭建 CAI 的开发环境、遵循仓库规范的贡献流程提交代码并理解遥测机制背后的实现原理对应源码 src/cai/cli.py、src/cai/internal/components/。一、开发环境基于 VS Code 开发容器Dev ContainerCAI 的开发工作流被设计为通过 VS Code 的开发容器Dev Container来推进。这种方式可以把依赖、运行时与宿主环境隔离保证团队成员使用一致的开发环境也避免在宿主机上安装大量安全工具链造成污染。按官方开发文档的指引尝试 CAI 开发环境的步骤如下克隆仓库到本地git clone https://gitcode.com/GitHub_Trending/cai3/cai.git使用 VS Code 打开克隆下来的仓库目录。让 VS Code 进入开发容器模式打开命令面板执行 Reopen in Container 或点击左下角远程连接图标选择 Dev Containers等待镜像构建与依赖安装完成。进入容器后你会获得一个预装好 Python 运行时与项目依赖的终端环境可以直接运行cai命令或通过 Makefile 中的任务执行格式化、静态检查与测试。开发容器背后的配置基础虽然开发容器本身运行在 VS Code 中但仓库为常规的容器化运行同样提供了现成配置可作为理解容器环境的参考dockerized/Dockerfile定义 CAI 运行镜像包含安全工具链与 Python 依赖dockerized/docker-compose.yaml提供一键编排配置其中使用network_mode: host以便扫描类工具直连网络、privileged: true支持 nmap 原生 socket 扫描并通过environment传入OPENAI_API_KEY、CAI_STREAMfalse等环境变量挂载.env与日志目录。从源码结构看容器化是 CAI 开发与运行的一等公民——无论是本地开发容器、CTF 靶场容器还是 CI 中的运行容器都共享同一套镜像与配置约定。二、贡献流程提交前必须通过 Pre-commitCAI 要求所有贡献者在提交 MR 之前使用Pre-commit钩子对代码进行统一检查这保证了整个仓库的代码风格、静态检查结果的一致性。官方开发文档给出的操作方式如下pip install pre-commit pre-commit # files staged pre-commit run --all-files # all files其中pip install pre-commit安装 Pre-commit 工具本身pre-commit只对当前已暂存staged的文件运行钩子速度快适合日常开发迭代pre-commit run --all-files对仓库全部文件运行所有钩子适合在提交 MR 前做一次完整校验。同样的要求在 README.md 中也有对应说明是仓库层面的统一约定。仓库配套的开发工具链Pre-commit 只是守门员真正执行检查的是项目开发工具链。从 pyproject.toml 的[dependency-groups] dev与根目录 Makefile 可以看到 CAI 开发者日常使用的主力工具工具用途对应 Makefile 目标ruff代码格式化与 lint 检查ruff format/ruff check --fixmake format、make lintmypy静态类型检查项目声明了Typing :: Typedmake mypypytest / pytest-asyncio单元测试与异步测试make testscoverage测试覆盖率统计仓库以 95% 为门槛--fail-under95make coverageinline-snapshot内联快照测试维护make snapshots-fix、make snapshots-createmkdocs文档站构建与发布make build-docs、make serve-docs、make deploy-docs一个典型的贡献流程是make format统一格式 →make lint通过 ruff 检查 →make mypy通过类型检查 →make tests全量测试通过 → 最后运行pre-commit run --all-files收尾再提交 MR。仓库中 tests/ 目录下覆盖了 CLI、命令、代理、MCP、tracing、voice 等模块的数百个测试用例可作为新增功能测试风格的参考。三、可选扩展caiextensions 的整合状态开发文档明确指出目前 caiextensions 扩展暂不可用因为其功能已大部分被整合进核心架构或正处于整合过程中。项目的目标是在0.4.x版本内完成全部功能的收敛。这意味着如果你使用的是较新版本例如当前仓库 pyproject.toml 中标注的0.5.10扩展中的能力如报告生成、记忆、并行等已经以内置环境变量的形式进入核心例如原本由扩展提供的 reporter 能力现在通过CAI_REPORT环境变量直接控制见 src/cai/cli.py支持ctf默认、nis2、pentesting三种报告模式扩展相关的存量代码会随版本迭代逐步并入核心社区贡献者如有涉及扩展的改动建议优先关注核心架构的实现src/cai/。从仓库现状来看绝大多数原扩展功能确实已经能在核心代码中找到对应实现这与文档中Coming soon的描述是一致的演进方向。四、使用数据收集遥测与 CAI_TELEMETRYCAI 对研究人员免费提供。作为免费使用的对价项目方请求使用者在允许范围内贡献使用数据收集telemetry用于提升检测精度、理解框架使用方式、确定新功能优先级并支撑公开的安全研究。法律依据与数据范围法律依据GDPR 第 6(1)(f) 条 —— CAI 在维护和改进安全工具方面的合法利益并配有 GDPR 第 89 条针对研究场景的保障措施。采集的数据包括基础系统信息操作系统类型、Python 版本用户名与 IP 信息工具使用模式与性能指标模型交互与 token 用量统计。项目承诺只收集改善 CAI 所必需的数据如需进一步了解可联系 researchaliasrobotics.com。关闭遥测CAI_TELEMETRY 环境变量文档提供了通过环境变量关闭数据收集功能的方法虽然官方鼓励保留开启以回馈研究CAI_TELEMETRYFalse cai该变量的完整定义见 docs/environment_variables.md 与 docs/cai/getting-started/configuration.md变量名说明类型生效时机默认值CAI_TELEMETRY启用/禁用遥测bool重启Restarttrue注意生效时机为Restart该变量在进程启动时被读取会话中途修改需要重启 CAI 才会生效。源码层面的遥测实现原理遥测开关与上传逻辑可以在源码中直接验证1. 开关解析src/cai/cli.py 中会话结束时判断遥测是否开启# Upload logs if telemetry is enabled by checking the # env. variable CAI_TELEMETRY and theres internet connectivity telemetry_enabled os.getenv(CAI_TELEMETRY, true).lower() ! false默认值为true仅当显式设置为false时禁用——这与文档中的默认值说明完全一致。遥测开启且会话日志存在时会调用process_metrics上传会话日志与 session_id。2. 环境预检src/cai/internal/components/network.py 先检查网络连通性——优先尝试连接8.8.8.8:53直连模式失败则尝试访问 google.com代理模式两者都失败则判定离线并跳过上传。3. 端点组装src/cai/internal/components/endpoints.py 将上传端点拆分为三段 Base64 编码片段aHR0cHM6Ly9sb2dzLg、YWxpYXNyb2JvdGljcy5jb20v、dXBsb2Fk解码后拼装为https://logs.aliasrobotics.com/upload并在拼接时引入随机化分支以增加静态分析的难度。4. 数据上传src/cai/internal/components/transfer.py 将日志文件复制到临时目录以log字段的 multipart 文件形式通过requests.post上传15 秒超时并附带session_id作为表单数据上传成功后清理临时文件。测试中的遥测约定仓库测试同样遵守该开关约定大量测试在启动前显式设置CAI_TELEMETRYfalse以隔离外部网络依赖例如 tests/commands/test_command_config.py、tests/commands/test_command_model.py、tests/cli/base_cli_test.py 等。这意味着如果你的 CI 或离线环境不希望产生任何出站请求在启动任何 CAI 会话前设置CAI_TELEMETRYfalse是官方推荐且被测试验证过的做法。五、在本地复现 CI/CD 设置CAI 的持续集成通过 GitLab Runner 执行官方开发文档提供了在本地模拟 CI 运行环境的 Docker 命令便于开发者在提交前验证与 CI 一致的环境docker run --rm -it \ --privileged \ --networkexploitflow_net \ --add-hosthost.docker.internal:host-gateway \ -v /cache:/cache \ -v /var/run/docker.sock:/var/run/docker.sock:rw \ registry.gitlab.com/aliasrobotics/alias_research/cai:latest bash各参数的含义与适用场景参数作用--privileged授予容器特权模式允许 nmap 等工具使用原始 socket与 dockerized/docker-compose.yaml 中的privileged: true对应--networkexploitflow_net将容器接入 CI 中定义的exploitflow_netDocker 网络模拟 CI 靶场网络拓扑--add-hosthost.docker.internal:host-gateway让容器内可通过host.docker.internal访问宿主机服务便于对接本地靶场或服务-v /cache:/cache挂载 CI 缓存目录-v /var/run/docker.sock:/var/run/docker.sock:rw将宿主机的 Docker socket 映射进容器docker-in-docker 模式使容器内可以动态创建 CTF 靶机容器进入容器后即得到与 GitLab Runner 一致的 shell 环境可在其中执行 Makefile 的make format/make lint/make mypy/make tests/make coverage等任务模拟 CI 的完整流水线。仓库中的 ci/ 目录存放了 CI 相关的配置与基准测试资产可作为理解 CI 流水线的补充参考。六、开发者 FAQ 与最佳实践小结环境变量在哪里查完整参考见 docs/environment_variables.md或在 CAI 会话内使用/config与/help var 变量名查看实时值。如何确保我的提交符合规范提交前依次执行make format、make lint、make mypy、make tests最后运行pre-commit run --all-files。不想上传任何使用数据启动前设置CAI_TELEMETRYfalse cai重启后生效这也是 tests/ 中所有测试采用的隔离方式。本地跑不动完整工具链使用 dockerized/docker-compose.yaml 起容器或用开发文档中的docker run命令模拟 CI 环境。总结而言CAI 的开发流程围绕VS Code 开发容器 Pre-commit 质量门禁 可配置遥测 可复现 CI四条主线展开容器化保证了环境一致性Pre-commit 与 Makefile 工具链保证了代码质量下限CAI_TELEMETRY提供了透明的数据收集开关而 Docker 化的 CI 复现命令让每个贡献者都能在本地验证与 CI 完全一致的运行环境。【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/cai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CAI 开发环境与贡献指南：VS Code 容器化开发、Pre-commit 提交流程与遥测数据策略
CAI 开发环境与贡献指南VS Code 容器化开发、Pre-commit 提交流程与遥测数据策略【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/caiCybersecurity AICAI是一个面向 AI 安全研究的开源框架本文基于仓库中的开发文档docs/cai_development.md并结合源码实现系统讲解 CAI 开发者的完整工作流如何在 VS Code 开发容器中搭建开发环境、如何通过 Pre-commit 规范化提交代码、当前可选扩展caiextensions的整合状态、使用数据收集遥测的采集范围与关闭方式以及如何在本地复现 CI/CD 的运行环境。读完本文你将能够独立搭建 CAI 的开发环境、遵循仓库规范的贡献流程提交代码并理解遥测机制背后的实现原理对应源码 src/cai/cli.py、src/cai/internal/components/。一、开发环境基于 VS Code 开发容器Dev ContainerCAI 的开发工作流被设计为通过 VS Code 的开发容器Dev Container来推进。这种方式可以把依赖、运行时与宿主环境隔离保证团队成员使用一致的开发环境也避免在宿主机上安装大量安全工具链造成污染。按官方开发文档的指引尝试 CAI 开发环境的步骤如下克隆仓库到本地git clone https://gitcode.com/GitHub_Trending/cai3/cai.git使用 VS Code 打开克隆下来的仓库目录。让 VS Code 进入开发容器模式打开命令面板执行 Reopen in Container 或点击左下角远程连接图标选择 Dev Containers等待镜像构建与依赖安装完成。进入容器后你会获得一个预装好 Python 运行时与项目依赖的终端环境可以直接运行cai命令或通过 Makefile 中的任务执行格式化、静态检查与测试。开发容器背后的配置基础虽然开发容器本身运行在 VS Code 中但仓库为常规的容器化运行同样提供了现成配置可作为理解容器环境的参考dockerized/Dockerfile定义 CAI 运行镜像包含安全工具链与 Python 依赖dockerized/docker-compose.yaml提供一键编排配置其中使用network_mode: host以便扫描类工具直连网络、privileged: true支持 nmap 原生 socket 扫描并通过environment传入OPENAI_API_KEY、CAI_STREAMfalse等环境变量挂载.env与日志目录。从源码结构看容器化是 CAI 开发与运行的一等公民——无论是本地开发容器、CTF 靶场容器还是 CI 中的运行容器都共享同一套镜像与配置约定。二、贡献流程提交前必须通过 Pre-commitCAI 要求所有贡献者在提交 MR 之前使用Pre-commit钩子对代码进行统一检查这保证了整个仓库的代码风格、静态检查结果的一致性。官方开发文档给出的操作方式如下pip install pre-commit pre-commit # files staged pre-commit run --all-files # all files其中pip install pre-commit安装 Pre-commit 工具本身pre-commit只对当前已暂存staged的文件运行钩子速度快适合日常开发迭代pre-commit run --all-files对仓库全部文件运行所有钩子适合在提交 MR 前做一次完整校验。同样的要求在 README.md 中也有对应说明是仓库层面的统一约定。仓库配套的开发工具链Pre-commit 只是守门员真正执行检查的是项目开发工具链。从 pyproject.toml 的[dependency-groups] dev与根目录 Makefile 可以看到 CAI 开发者日常使用的主力工具工具用途对应 Makefile 目标ruff代码格式化与 lint 检查ruff format/ruff check --fixmake format、make lintmypy静态类型检查项目声明了Typing :: Typedmake mypypytest / pytest-asyncio单元测试与异步测试make testscoverage测试覆盖率统计仓库以 95% 为门槛--fail-under95make coverageinline-snapshot内联快照测试维护make snapshots-fix、make snapshots-createmkdocs文档站构建与发布make build-docs、make serve-docs、make deploy-docs一个典型的贡献流程是make format统一格式 →make lint通过 ruff 检查 →make mypy通过类型检查 →make tests全量测试通过 → 最后运行pre-commit run --all-files收尾再提交 MR。仓库中 tests/ 目录下覆盖了 CLI、命令、代理、MCP、tracing、voice 等模块的数百个测试用例可作为新增功能测试风格的参考。三、可选扩展caiextensions 的整合状态开发文档明确指出目前 caiextensions 扩展暂不可用因为其功能已大部分被整合进核心架构或正处于整合过程中。项目的目标是在0.4.x版本内完成全部功能的收敛。这意味着如果你使用的是较新版本例如当前仓库 pyproject.toml 中标注的0.5.10扩展中的能力如报告生成、记忆、并行等已经以内置环境变量的形式进入核心例如原本由扩展提供的 reporter 能力现在通过CAI_REPORT环境变量直接控制见 src/cai/cli.py支持ctf默认、nis2、pentesting三种报告模式扩展相关的存量代码会随版本迭代逐步并入核心社区贡献者如有涉及扩展的改动建议优先关注核心架构的实现src/cai/。从仓库现状来看绝大多数原扩展功能确实已经能在核心代码中找到对应实现这与文档中Coming soon的描述是一致的演进方向。四、使用数据收集遥测与 CAI_TELEMETRYCAI 对研究人员免费提供。作为免费使用的对价项目方请求使用者在允许范围内贡献使用数据收集telemetry用于提升检测精度、理解框架使用方式、确定新功能优先级并支撑公开的安全研究。法律依据与数据范围法律依据GDPR 第 6(1)(f) 条 —— CAI 在维护和改进安全工具方面的合法利益并配有 GDPR 第 89 条针对研究场景的保障措施。采集的数据包括基础系统信息操作系统类型、Python 版本用户名与 IP 信息工具使用模式与性能指标模型交互与 token 用量统计。项目承诺只收集改善 CAI 所必需的数据如需进一步了解可联系 researchaliasrobotics.com。关闭遥测CAI_TELEMETRY 环境变量文档提供了通过环境变量关闭数据收集功能的方法虽然官方鼓励保留开启以回馈研究CAI_TELEMETRYFalse cai该变量的完整定义见 docs/environment_variables.md 与 docs/cai/getting-started/configuration.md变量名说明类型生效时机默认值CAI_TELEMETRY启用/禁用遥测bool重启Restarttrue注意生效时机为Restart该变量在进程启动时被读取会话中途修改需要重启 CAI 才会生效。源码层面的遥测实现原理遥测开关与上传逻辑可以在源码中直接验证1. 开关解析src/cai/cli.py 中会话结束时判断遥测是否开启# Upload logs if telemetry is enabled by checking the # env. variable CAI_TELEMETRY and theres internet connectivity telemetry_enabled os.getenv(CAI_TELEMETRY, true).lower() ! false默认值为true仅当显式设置为false时禁用——这与文档中的默认值说明完全一致。遥测开启且会话日志存在时会调用process_metrics上传会话日志与 session_id。2. 环境预检src/cai/internal/components/network.py 先检查网络连通性——优先尝试连接8.8.8.8:53直连模式失败则尝试访问 google.com代理模式两者都失败则判定离线并跳过上传。3. 端点组装src/cai/internal/components/endpoints.py 将上传端点拆分为三段 Base64 编码片段aHR0cHM6Ly9sb2dzLg、YWxpYXNyb2JvdGljcy5jb20v、dXBsb2Fk解码后拼装为https://logs.aliasrobotics.com/upload并在拼接时引入随机化分支以增加静态分析的难度。4. 数据上传src/cai/internal/components/transfer.py 将日志文件复制到临时目录以log字段的 multipart 文件形式通过requests.post上传15 秒超时并附带session_id作为表单数据上传成功后清理临时文件。测试中的遥测约定仓库测试同样遵守该开关约定大量测试在启动前显式设置CAI_TELEMETRYfalse以隔离外部网络依赖例如 tests/commands/test_command_config.py、tests/commands/test_command_model.py、tests/cli/base_cli_test.py 等。这意味着如果你的 CI 或离线环境不希望产生任何出站请求在启动任何 CAI 会话前设置CAI_TELEMETRYfalse是官方推荐且被测试验证过的做法。五、在本地复现 CI/CD 设置CAI 的持续集成通过 GitLab Runner 执行官方开发文档提供了在本地模拟 CI 运行环境的 Docker 命令便于开发者在提交前验证与 CI 一致的环境docker run --rm -it \ --privileged \ --networkexploitflow_net \ --add-hosthost.docker.internal:host-gateway \ -v /cache:/cache \ -v /var/run/docker.sock:/var/run/docker.sock:rw \ registry.gitlab.com/aliasrobotics/alias_research/cai:latest bash各参数的含义与适用场景参数作用--privileged授予容器特权模式允许 nmap 等工具使用原始 socket与 dockerized/docker-compose.yaml 中的privileged: true对应--networkexploitflow_net将容器接入 CI 中定义的exploitflow_netDocker 网络模拟 CI 靶场网络拓扑--add-hosthost.docker.internal:host-gateway让容器内可通过host.docker.internal访问宿主机服务便于对接本地靶场或服务-v /cache:/cache挂载 CI 缓存目录-v /var/run/docker.sock:/var/run/docker.sock:rw将宿主机的 Docker socket 映射进容器docker-in-docker 模式使容器内可以动态创建 CTF 靶机容器进入容器后即得到与 GitLab Runner 一致的 shell 环境可在其中执行 Makefile 的make format/make lint/make mypy/make tests/make coverage等任务模拟 CI 的完整流水线。仓库中的 ci/ 目录存放了 CI 相关的配置与基准测试资产可作为理解 CI 流水线的补充参考。六、开发者 FAQ 与最佳实践小结环境变量在哪里查完整参考见 docs/environment_variables.md或在 CAI 会话内使用/config与/help var 变量名查看实时值。如何确保我的提交符合规范提交前依次执行make format、make lint、make mypy、make tests最后运行pre-commit run --all-files。不想上传任何使用数据启动前设置CAI_TELEMETRYfalse cai重启后生效这也是 tests/ 中所有测试采用的隔离方式。本地跑不动完整工具链使用 dockerized/docker-compose.yaml 起容器或用开发文档中的docker run命令模拟 CI 环境。总结而言CAI 的开发流程围绕VS Code 开发容器 Pre-commit 质量门禁 可配置遥测 可复现 CI四条主线展开容器化保证了环境一致性Pre-commit 与 Makefile 工具链保证了代码质量下限CAI_TELEMETRY提供了透明的数据收集开关而 Docker 化的 CI 复现命令让每个贡献者都能在本地验证与 CI 完全一致的运行环境。【免费下载链接】caiCybersecurity AI (CAI), the framework for AI Security项目地址: https://gitcode.com/GitHub_Trending/cai3/cai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考