尧图网页设计 
Composio Python SDK 开发指南从环境搭建到安全路径防护的工程规范【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读python/AGENTS.md 是 Composio 仓库中面向 AI Agent 与人类开发者的 Python SDK 开发规范它划定了python/目录的职责边界、技能路由规则、环境搭建与校验命令并明确了一条贯穿全仓的安全底线——API 响应的每一个字段包括 slug、ID、文件名都是不可信输入。阅读本文后你将掌握 Composio Python SDK 的开发环境初始化、格式化/类型检查/测试/构建的标准命令链、provider 包的组织纪律以及一套由源码与测试双重保障的安全路径拼接防御模型可以直接在真实开发中复现与验证。一、Scopepython/目录承载了什么从仓库目录结构看python/不是 SDK 的单一模块而是五个职责各异的子域的组合子域路径内容核心 SDKpython/composio/客户端、核心模型、工具路由、文件处理等运行时实现Provider 包python/providers/*Anthropic、OpenAI、LangChain、CrewAI 等第三方 Agent 框架适配层测试与质量python/tests/、python/noxfile.py、python/Makefilepytest 用例、nox 会话编排、Ruff/mypy 校验发布流程python/scripts/bump.py等版本号提升、构建与发布工作流Python 文档python/docs/开发与发布文档理解这个边界是遵循一切后续规范的前提改动落在哪个域就使用对应的技能路由并只在对应目录内动手。二、Skill Routing给 AI Agent 的分流规则AGENTS.md本身是写给 AI Agent 看的导航文件它定义了一套技能路由Skill Routing约定让 Agent 在收到开发任务时能快速定位正确的代码区域python-sdk核心 SDK 代码对应python/composio/python-providerspython/providers/*下的所有 provider 包python-testingRuff、mypy、pytest、nox 与 Makefile 相关的验证工作python-release构建、版本提升bump与发布流程的改动cross-sdk-parity凡是需要与 TypeScript SDK 行为对齐的场景统一走这条路由。这套路由的价值在于把模糊的意图映射为确定的目录避免 Agent 在 1000 工具包规模的仓库中漫无目的地搜索。三、Setup环境搭建的标准入口AGENTS.md明确要求所有命令从python/目录发起。初始化环境只需两条命令make env source .venv/bin/activate从 python/Makefile 的env目标第 34-49 行可以看到这一步实际做了什么若当前不在虚拟环境中使用uv venv --seed --prompt composio --python 3.12创建 Python 3.12 的虚拟环境执行uv sync与uv sync --dev同步锁定依赖与开发依赖通过make provider遍历安装providers/*/pyproject.toml中声明的所有 provider 包最后uv pip install -e .以可编辑模式安装核心 SDK。注意若你已经在某个虚拟环境中make env只会执行uv sync与可编辑安装并提示先deactivate再创建全新环境。开发依赖统一由uv锁定管理不要手动向环境里塞包。四、Commands一条完整的质量验证命令链AGENTS.md给出的六条命令是 Python SDK 开发的核心工作流全部经由 python/Makefile 转发到 python/noxfile.py 的 nox 会话make fmt # 格式化与 import 排序 make chk # Ruff lint mypy 类型检查 make tst # 完整 pytest 单元测试 make snt # 快速冒烟测试imports 与 SDK 初始化 make type_inference # provider 返回类型推断的 mypy 验证 make build # 构建核心 SDK 与所有 provider 的发行包4.1make fmt统一格式对应 nox 会话执行ruff check --select I --fiximport 排序修复与ruff format扫描范围覆盖composio/、providers/、tests/、examples/、scripts/见 python/noxfile.py。4.2make chk静态质量门禁Ruff 使用config/ruff.toml配置对composio/、providers/、tests/、examples/、scripts/做 lintmypy 使用config/mypy.ini对composio/、providers/、tests/、scripts/做类型检查为让 mypy 能解析 provider 中的类型会额外安装types-requests、anthropic、crewai、langchain、langgraph、llama-index、openai-agents等类型桩与 provider 库见 python/noxfile.py。这些依赖刻意不放进根锁文件的 dev 组避免 provider 库之间相互拖入冲突的传递依赖。4.3make tst与make snt测试与冒烟tst会话安装核心 SDK、dev 组依赖及 crewai/langchain/langgraph provider 后对tests/运行pytest -v --tbshort也可用make tst -- 路径指定测试子集。snt会话则只跑tests/test_imports.py与tests/test_sdk.py用于快速验证 import 与 SDK 初始化适合作为 CI 的第一道快筛见 python/noxfile.py。4.4make type_inferenceprovider 类型推断验证该会话安装全部 12 个 provider 包然后对tests/test_type_inference.py及各 provider 专属的类型推断测试执行 mypy。它验证的核心是当Composio.tools.get()使用overload签名时mypy 能否针对不同 provider 正确推断出工具返回类型见 python/noxfile.py。4.5make build发行包构建build目标先清理旧产物再用.venv/bin/python -m build构建核心 SDK并遍历PROVIDER_DIRS构建每个 provider将产物统一复制到dist/见 python/Makefile。五、Rules四条必须遵守的开发纪律格式与类型格式化/lint 用 Ruff类型检查用 mypy测试覆盖任何行为变更必须补充 pytest 测试改动隔离provider 相关改动必须放在对应的python/providers/provider/包内不得污染核心 SDK版本联动提升composio-client版本时必须同步更新 python/pyproject.toml、python/setup.py 与根目录 uv.lock 三处保证锁文件与声明一致。六、Trust boundary为什么每个 API 字段都是不可信输入这是AGENTS.md中技术含量最高、也最值得展开的一节。SDK 的威胁模型假设后端可能被攻破工具执行结果由远端服务返回恶意或被劫持的服务端可以返回任意内容连接可能被中间人篡改MITM传输层被劫持时返回的 slug、ID、文件名都可被改写第三方 toolkit 可以返回任何东西Composio 聚合了大量第三方工具任何一个工具包都可能成为攻击载体。因此凡是来自 API 响应的字符串在成为文件系统路径的一部分之前必须经过专门的校验而不是直接拼进Path(...)或open(...)。对应实现位于 python/composio/utils/safe_path.py异常类型为 python/composio/exceptions.py 中定义的UnsafePathComponentError——它失败即关闭fails closedSDK 直接拒绝写入而不是把危险值清洗成一个貌似安全的替身。6.1 两个核心安全助手AGENTS.md规定了两个入口from composio.utils.safe_path import secure_join, secure_basename_join # 场景一不可信的目录层级组件如 tool.toolkit.slug、tool.slug path secure_join(root, tool.toolkit.slug, tool.slug) # 场景二不可信的文件名如服务端下发的 self.name path secure_basename_join(outdir, filename, rootroot)两者的分工与实现细节如下助手适用对象底层校验对应源码secure_join多个不可信目录组件每个组件过assert_safe_path_component再整体resolve后做is_inside_dir二次确认safe_path.pysecure_basename_join单个不可信文件名先safe_basename折叠为裸文件名允许.因为真实文件名几乎都带扩展名再做包含性检查safe_path.py6.2assert_safe_path_component组件级校验secure_join对每个组件调用assert_safe_path_componentsafe_path.py它拒绝空值或非字符串含路径分隔符/、\或盘符的值——利用PureWindowsPath同时把两种分隔符都视为分隔符从而在 POSIX 构建机上也能拦截专门为 Windows 目标构造的..\x长度超过MAX_COMPONENT_LENGTH 128的组件远低于 ext4/APFS/NTFS 常见的 255 字节限制防止超长 slug 在写入中途抛OSError不匹配^[A-Za-z0-9_-]$的字符——注意用fullmatch而非match避免GMAIL\n这类带尾部换行的值蒙混过关Windows 保留设备名CON、PRN、AUX、COM1-COM9、LPT1-LPT9等且在所有平台统一拒绝保证 POSIX 开发机与 Windows 部署行为一致。正则允许的字符与 SDK 在custom_tool_types.py中SLUG_REGEX保持一致——据源码注释目录快照ts/packages/cli/src/generated/toolkit-slugs.ts中的 1070 个 toolkit slug 全部符合该模式因此正常合法 slug 不会被误伤。6.3safe_basename文件名自有其道文件名不能复用组件校验它禁止.因此单独提供safe_basenamesafe_path.py用PureWindowsPath(name).name剥掉任何路径成分只留裸文件名拒绝解析后无可用文件名的情况如.、空串——SDK 拒绝为畸形或敌意响应编造文件名因为这会掩盖问题拒绝 NUL 字节、控制字符、Windows 保留字符:|?*、以空格或点结尾、超长按os.fsencode编码后字节数计以及保留设备名NUL.tar.gz在 Windows 上依然指向空设备因此比较的是第一个点之前的部分。6.4 两次规则信任锚定与先验证后写盘AGENTS.md强调两条原则源码中的注释与测试都围绕它们展开规则 1信任锚必须是一个常量。如果把由不可信输入构建的目录当作校验参照那就是脏数据校验脏数据永远通过。典型反例root / untrusted_a / untrusted_b构建出的目录再拿去与自身比较——输入完全可以移动参照物。因此secure_join只以调用方传入的root为锚resolve_rootsafe_path.py统一负责把它规范化expanduserresolve保证所有调用点使用相同的归一化结果做比较。规则 2校验先于触碰文件系统。在最终路径被确认位于 root 之内前不执行任何mkdir或open这样被拒绝的写入不会留下攻击者可控的目录。从 python/composio/core/models/_files.py 的FileDownloadable.download实现可以看到先用secure_basename_join计算安全路径成功后再outdir.mkdir(exist_okTrue, parentsTrue)并打开文件写入——mkdir严格发生在路径校验之后。七、Guardrail用测试把规范焊死在代码里AGENTS.md指出 python/tests/test_path_join_guardrail.py 强制执行上述纪律任何右操作数不是字面量或模块常量的路径拼接都必须登记在REVIEWED_JOINS中并说明理由。这份测试不是摆设它用四层断言堵死了所有绕过路径覆盖每一种拼写静态扫描composio/与providers/下所有.py文件用 AST 识别/运算符、/、joinpath、os.path.join、Path(...)构造、open/mkdir/makedirs直连等所有路径拼接形态。表驱动的EVASIONS字典test_path_join_guardrail.py给出了 15 种已知绕过写法——包括 f-string、字符串拼接、open(tool.slug, rb)、os.makedirs(...)等——并逐一断言检测器必须命中失败即关闭不从变量名猜语义。outdir改名为base不会让检查静默失效模块级ALL_CAPS名称只有绑定字面量才被豁免SLUG os.environ[SLUG]这种运行时绑定的伪常量照样会被扫出见test_module_constant_exemption_requires_a_literal允许列表绑定证据REVIEWED_JOINS的每条记录都带requires字段测试会检查该路径所在函数确实调用了其声称依赖的校验函数如resolve_root、safe_basename、is_inside_dir防止校验被删掉后条目还在裸奔test_reviewed_joins_still_have_their_validation次数绑定每条目的occurrences与实际出现次数严格相等新出现的相同代码不会被旧条目打包批准test_reviewed_joins_occurrence_counts_match。同时test_reviewed_joins_all_still_exist保证允许列表不会腐烂成过期条目test_scan_roots_are_pinned则钉死扫描根只能是composio与providers——缩小扫描范围等于悄悄缩小保障面。当前REVIEWED_JOINS中除safe_path自身外的条目均为调用方显式选择的本地路径、本地配置、__file__或纯词法解析其余 API 派生组件必须走secure_join/secure_basename_join。八、从源码看这两个助手如何被真实调用8.1 工具文件下载secure_joinsecure_basename_join的组合拳在 python/composio/core/models/_files.py 的_download_file_value中tool.toolkit.slug与tool.slug来自 API 响应、不可信直接拼接会让响应决定下载目录。实现先用secure_join(self._outdir, tool.toolkit.slug, tool.slug)把两个 slug 作为组件校验并锚定到本地配置的self._outdir得到下载子目录随后FileDownloadable.download再对响应中的self.name调用secure_basename_join(outdir, self.name, rootself._outdir)——注意锚定的是root受信常量而非outdir这样output_evil/foo这类同前缀兄弟目录攻击也会被拒源码注释标注为 SEC-316见 _files.py。8.2 Tool Router 会话文件secure_basename_join的单文件场景python/composio/core/models/tool_router_session_files.py 的RemoteFile.save在未显式指定保存路径时会以服务端下发的mount_relative_path为文件名用secure_basename_join(default_dir, self.mount_relative_path, labelmount path)折叠并锚定到常量~/.composio/files/。注释SEC-316 defense-in-depth说明此前或.会让保存路径等于目录本身、通过路径包含自身的包含性检查最终在目录已创建后以原始IsADirectoryError失败现在safe_basename提前拒绝这类值包含性检查退居第二道防线。九、常见问题与最佳实践小结永远不要手写resolve() / is_relative_to()对AGENTS.md与 safe_path.py 的文档字符串都明确建议用secure_join取代手写包含性检查因为手写版本很容易漏掉符号链接逃逸或参照物被污染的陷阱下载路径要区分outdir与rootoutdir可能由不可信 slug 构建真正可信的锚只有本地配置的root两者必须分开传参新代码若必须拼接路径先过 guardrail 测试能走secure_join/secure_basename_join就走它们确属调用方本地路径、本地配置或__file__的才按REVIEWED_JOINS格式登记并写明依赖的校验函数行为变更必带测试provider 改动进对应包版本提升三处同步这三条纪律与安全边界共同构成 SDK 的可维护性 安全性双保险。结语python/AGENTS.md 表面是一份给 Agent 的导航说明实际浓缩了 Composio Python SDK 的开发全流程与安全基线从make env到make build的命令链、provider 包的边界纪律再到API 字段不可信威胁模型下secure_join/secure_basename_join的路径防护以及 python/tests/test_path_join_guardrail.py 用 AST 扫描焊死的防回归护栏。对任何在 Composio 生态中做 SDK 开发、provider 适配或安全审查的开发者而言这份文档既是上手手册也是代码评审时值得逐条对照的检查清单。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Composio Python SDK 开发指南：从环境搭建到安全路径防护的工程规范
Composio Python SDK 开发指南从环境搭建到安全路径防护的工程规范【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读python/AGENTS.md 是 Composio 仓库中面向 AI Agent 与人类开发者的 Python SDK 开发规范它划定了python/目录的职责边界、技能路由规则、环境搭建与校验命令并明确了一条贯穿全仓的安全底线——API 响应的每一个字段包括 slug、ID、文件名都是不可信输入。阅读本文后你将掌握 Composio Python SDK 的开发环境初始化、格式化/类型检查/测试/构建的标准命令链、provider 包的组织纪律以及一套由源码与测试双重保障的安全路径拼接防御模型可以直接在真实开发中复现与验证。一、Scopepython/目录承载了什么从仓库目录结构看python/不是 SDK 的单一模块而是五个职责各异的子域的组合子域路径内容核心 SDKpython/composio/客户端、核心模型、工具路由、文件处理等运行时实现Provider 包python/providers/*Anthropic、OpenAI、LangChain、CrewAI 等第三方 Agent 框架适配层测试与质量python/tests/、python/noxfile.py、python/Makefilepytest 用例、nox 会话编排、Ruff/mypy 校验发布流程python/scripts/bump.py等版本号提升、构建与发布工作流Python 文档python/docs/开发与发布文档理解这个边界是遵循一切后续规范的前提改动落在哪个域就使用对应的技能路由并只在对应目录内动手。二、Skill Routing给 AI Agent 的分流规则AGENTS.md本身是写给 AI Agent 看的导航文件它定义了一套技能路由Skill Routing约定让 Agent 在收到开发任务时能快速定位正确的代码区域python-sdk核心 SDK 代码对应python/composio/python-providerspython/providers/*下的所有 provider 包python-testingRuff、mypy、pytest、nox 与 Makefile 相关的验证工作python-release构建、版本提升bump与发布流程的改动cross-sdk-parity凡是需要与 TypeScript SDK 行为对齐的场景统一走这条路由。这套路由的价值在于把模糊的意图映射为确定的目录避免 Agent 在 1000 工具包规模的仓库中漫无目的地搜索。三、Setup环境搭建的标准入口AGENTS.md明确要求所有命令从python/目录发起。初始化环境只需两条命令make env source .venv/bin/activate从 python/Makefile 的env目标第 34-49 行可以看到这一步实际做了什么若当前不在虚拟环境中使用uv venv --seed --prompt composio --python 3.12创建 Python 3.12 的虚拟环境执行uv sync与uv sync --dev同步锁定依赖与开发依赖通过make provider遍历安装providers/*/pyproject.toml中声明的所有 provider 包最后uv pip install -e .以可编辑模式安装核心 SDK。注意若你已经在某个虚拟环境中make env只会执行uv sync与可编辑安装并提示先deactivate再创建全新环境。开发依赖统一由uv锁定管理不要手动向环境里塞包。四、Commands一条完整的质量验证命令链AGENTS.md给出的六条命令是 Python SDK 开发的核心工作流全部经由 python/Makefile 转发到 python/noxfile.py 的 nox 会话make fmt # 格式化与 import 排序 make chk # Ruff lint mypy 类型检查 make tst # 完整 pytest 单元测试 make snt # 快速冒烟测试imports 与 SDK 初始化 make type_inference # provider 返回类型推断的 mypy 验证 make build # 构建核心 SDK 与所有 provider 的发行包4.1make fmt统一格式对应 nox 会话执行ruff check --select I --fiximport 排序修复与ruff format扫描范围覆盖composio/、providers/、tests/、examples/、scripts/见 python/noxfile.py。4.2make chk静态质量门禁Ruff 使用config/ruff.toml配置对composio/、providers/、tests/、examples/、scripts/做 lintmypy 使用config/mypy.ini对composio/、providers/、tests/、scripts/做类型检查为让 mypy 能解析 provider 中的类型会额外安装types-requests、anthropic、crewai、langchain、langgraph、llama-index、openai-agents等类型桩与 provider 库见 python/noxfile.py。这些依赖刻意不放进根锁文件的 dev 组避免 provider 库之间相互拖入冲突的传递依赖。4.3make tst与make snt测试与冒烟tst会话安装核心 SDK、dev 组依赖及 crewai/langchain/langgraph provider 后对tests/运行pytest -v --tbshort也可用make tst -- 路径指定测试子集。snt会话则只跑tests/test_imports.py与tests/test_sdk.py用于快速验证 import 与 SDK 初始化适合作为 CI 的第一道快筛见 python/noxfile.py。4.4make type_inferenceprovider 类型推断验证该会话安装全部 12 个 provider 包然后对tests/test_type_inference.py及各 provider 专属的类型推断测试执行 mypy。它验证的核心是当Composio.tools.get()使用overload签名时mypy 能否针对不同 provider 正确推断出工具返回类型见 python/noxfile.py。4.5make build发行包构建build目标先清理旧产物再用.venv/bin/python -m build构建核心 SDK并遍历PROVIDER_DIRS构建每个 provider将产物统一复制到dist/见 python/Makefile。五、Rules四条必须遵守的开发纪律格式与类型格式化/lint 用 Ruff类型检查用 mypy测试覆盖任何行为变更必须补充 pytest 测试改动隔离provider 相关改动必须放在对应的python/providers/provider/包内不得污染核心 SDK版本联动提升composio-client版本时必须同步更新 python/pyproject.toml、python/setup.py 与根目录 uv.lock 三处保证锁文件与声明一致。六、Trust boundary为什么每个 API 字段都是不可信输入这是AGENTS.md中技术含量最高、也最值得展开的一节。SDK 的威胁模型假设后端可能被攻破工具执行结果由远端服务返回恶意或被劫持的服务端可以返回任意内容连接可能被中间人篡改MITM传输层被劫持时返回的 slug、ID、文件名都可被改写第三方 toolkit 可以返回任何东西Composio 聚合了大量第三方工具任何一个工具包都可能成为攻击载体。因此凡是来自 API 响应的字符串在成为文件系统路径的一部分之前必须经过专门的校验而不是直接拼进Path(...)或open(...)。对应实现位于 python/composio/utils/safe_path.py异常类型为 python/composio/exceptions.py 中定义的UnsafePathComponentError——它失败即关闭fails closedSDK 直接拒绝写入而不是把危险值清洗成一个貌似安全的替身。6.1 两个核心安全助手AGENTS.md规定了两个入口from composio.utils.safe_path import secure_join, secure_basename_join # 场景一不可信的目录层级组件如 tool.toolkit.slug、tool.slug path secure_join(root, tool.toolkit.slug, tool.slug) # 场景二不可信的文件名如服务端下发的 self.name path secure_basename_join(outdir, filename, rootroot)两者的分工与实现细节如下助手适用对象底层校验对应源码secure_join多个不可信目录组件每个组件过assert_safe_path_component再整体resolve后做is_inside_dir二次确认safe_path.pysecure_basename_join单个不可信文件名先safe_basename折叠为裸文件名允许.因为真实文件名几乎都带扩展名再做包含性检查safe_path.py6.2assert_safe_path_component组件级校验secure_join对每个组件调用assert_safe_path_componentsafe_path.py它拒绝空值或非字符串含路径分隔符/、\或盘符的值——利用PureWindowsPath同时把两种分隔符都视为分隔符从而在 POSIX 构建机上也能拦截专门为 Windows 目标构造的..\x长度超过MAX_COMPONENT_LENGTH 128的组件远低于 ext4/APFS/NTFS 常见的 255 字节限制防止超长 slug 在写入中途抛OSError不匹配^[A-Za-z0-9_-]$的字符——注意用fullmatch而非match避免GMAIL\n这类带尾部换行的值蒙混过关Windows 保留设备名CON、PRN、AUX、COM1-COM9、LPT1-LPT9等且在所有平台统一拒绝保证 POSIX 开发机与 Windows 部署行为一致。正则允许的字符与 SDK 在custom_tool_types.py中SLUG_REGEX保持一致——据源码注释目录快照ts/packages/cli/src/generated/toolkit-slugs.ts中的 1070 个 toolkit slug 全部符合该模式因此正常合法 slug 不会被误伤。6.3safe_basename文件名自有其道文件名不能复用组件校验它禁止.因此单独提供safe_basenamesafe_path.py用PureWindowsPath(name).name剥掉任何路径成分只留裸文件名拒绝解析后无可用文件名的情况如.、空串——SDK 拒绝为畸形或敌意响应编造文件名因为这会掩盖问题拒绝 NUL 字节、控制字符、Windows 保留字符:|?*、以空格或点结尾、超长按os.fsencode编码后字节数计以及保留设备名NUL.tar.gz在 Windows 上依然指向空设备因此比较的是第一个点之前的部分。6.4 两次规则信任锚定与先验证后写盘AGENTS.md强调两条原则源码中的注释与测试都围绕它们展开规则 1信任锚必须是一个常量。如果把由不可信输入构建的目录当作校验参照那就是脏数据校验脏数据永远通过。典型反例root / untrusted_a / untrusted_b构建出的目录再拿去与自身比较——输入完全可以移动参照物。因此secure_join只以调用方传入的root为锚resolve_rootsafe_path.py统一负责把它规范化expanduserresolve保证所有调用点使用相同的归一化结果做比较。规则 2校验先于触碰文件系统。在最终路径被确认位于 root 之内前不执行任何mkdir或open这样被拒绝的写入不会留下攻击者可控的目录。从 python/composio/core/models/_files.py 的FileDownloadable.download实现可以看到先用secure_basename_join计算安全路径成功后再outdir.mkdir(exist_okTrue, parentsTrue)并打开文件写入——mkdir严格发生在路径校验之后。七、Guardrail用测试把规范焊死在代码里AGENTS.md指出 python/tests/test_path_join_guardrail.py 强制执行上述纪律任何右操作数不是字面量或模块常量的路径拼接都必须登记在REVIEWED_JOINS中并说明理由。这份测试不是摆设它用四层断言堵死了所有绕过路径覆盖每一种拼写静态扫描composio/与providers/下所有.py文件用 AST 识别/运算符、/、joinpath、os.path.join、Path(...)构造、open/mkdir/makedirs直连等所有路径拼接形态。表驱动的EVASIONS字典test_path_join_guardrail.py给出了 15 种已知绕过写法——包括 f-string、字符串拼接、open(tool.slug, rb)、os.makedirs(...)等——并逐一断言检测器必须命中失败即关闭不从变量名猜语义。outdir改名为base不会让检查静默失效模块级ALL_CAPS名称只有绑定字面量才被豁免SLUG os.environ[SLUG]这种运行时绑定的伪常量照样会被扫出见test_module_constant_exemption_requires_a_literal允许列表绑定证据REVIEWED_JOINS的每条记录都带requires字段测试会检查该路径所在函数确实调用了其声称依赖的校验函数如resolve_root、safe_basename、is_inside_dir防止校验被删掉后条目还在裸奔test_reviewed_joins_still_have_their_validation次数绑定每条目的occurrences与实际出现次数严格相等新出现的相同代码不会被旧条目打包批准test_reviewed_joins_occurrence_counts_match。同时test_reviewed_joins_all_still_exist保证允许列表不会腐烂成过期条目test_scan_roots_are_pinned则钉死扫描根只能是composio与providers——缩小扫描范围等于悄悄缩小保障面。当前REVIEWED_JOINS中除safe_path自身外的条目均为调用方显式选择的本地路径、本地配置、__file__或纯词法解析其余 API 派生组件必须走secure_join/secure_basename_join。八、从源码看这两个助手如何被真实调用8.1 工具文件下载secure_joinsecure_basename_join的组合拳在 python/composio/core/models/_files.py 的_download_file_value中tool.toolkit.slug与tool.slug来自 API 响应、不可信直接拼接会让响应决定下载目录。实现先用secure_join(self._outdir, tool.toolkit.slug, tool.slug)把两个 slug 作为组件校验并锚定到本地配置的self._outdir得到下载子目录随后FileDownloadable.download再对响应中的self.name调用secure_basename_join(outdir, self.name, rootself._outdir)——注意锚定的是root受信常量而非outdir这样output_evil/foo这类同前缀兄弟目录攻击也会被拒源码注释标注为 SEC-316见 _files.py。8.2 Tool Router 会话文件secure_basename_join的单文件场景python/composio/core/models/tool_router_session_files.py 的RemoteFile.save在未显式指定保存路径时会以服务端下发的mount_relative_path为文件名用secure_basename_join(default_dir, self.mount_relative_path, labelmount path)折叠并锚定到常量~/.composio/files/。注释SEC-316 defense-in-depth说明此前或.会让保存路径等于目录本身、通过路径包含自身的包含性检查最终在目录已创建后以原始IsADirectoryError失败现在safe_basename提前拒绝这类值包含性检查退居第二道防线。九、常见问题与最佳实践小结永远不要手写resolve() / is_relative_to()对AGENTS.md与 safe_path.py 的文档字符串都明确建议用secure_join取代手写包含性检查因为手写版本很容易漏掉符号链接逃逸或参照物被污染的陷阱下载路径要区分outdir与rootoutdir可能由不可信 slug 构建真正可信的锚只有本地配置的root两者必须分开传参新代码若必须拼接路径先过 guardrail 测试能走secure_join/secure_basename_join就走它们确属调用方本地路径、本地配置或__file__的才按REVIEWED_JOINS格式登记并写明依赖的校验函数行为变更必带测试provider 改动进对应包版本提升三处同步这三条纪律与安全边界共同构成 SDK 的可维护性 安全性双保险。结语python/AGENTS.md 表面是一份给 Agent 的导航说明实际浓缩了 Composio Python SDK 的开发全流程与安全基线从make env到make build的命令链、provider 包的边界纪律再到API 字段不可信威胁模型下secure_join/secure_basename_join的路径防护以及 python/tests/test_path_join_guardrail.py 用 AST 扫描焊死的防回归护栏。对任何在 Composio 生态中做 SDK 开发、provider 适配或安全审查的开发者而言这份文档既是上手手册也是代码评审时值得逐条对照的检查清单。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考