agno FileSystem 运维实操从外部检查、修复与预置 Agent 文件存储quota_recovery 与 inspect_files 全解析【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno本篇技术指南聚焦 agno 的持久化文件系统FileSystem在运行期之外的运维场景当一个 Agent 的文件存储写入开始失败、需要被外部脚本检查、修复或预置时如何绕过 Agent、模型与 API Key用纯 Python 直接操作与 Agent 完全相同的存储后端。读完本文你将掌握双层配额per-file / per-namespace的触发机制与精确错误语义、两种官方推荐的恢复策略按日期分区、按保留窗口删除、以及如何用脚本读取、测量、预置 Agent 的 已处理记录从而让定时 Agent 在首次上线前就能正确去重。章节定位05_operations 在 FileSystem 教程中的角色在 agno cookbook 的 13_filesystem 体系中前几个章节如 01_getting_started解决的是如何给 Agent 挂上一个持久化文件系统02_durable_records 则讲解记录日志record log的布局与去重模式。而05_operations解决的是完全不同的一个问题存储建好之后如何从外部运维它。按 README.md 的定义本目录包含两个相互独立的操作配方且刻意没有basic.py两者都不是更简单的入门起点quota_recovery.py故意同时触发单文件上限与命名空间上限展示 Agent 会看到的确切错误字符串并按照错误提示给出的两种路径完成恢复——开启新分区、删除不再需要的分区。inspect_files.py把脚本指向 Agent 使用的同一个存储后端然后列出文件、测量用量、读取工作状态、预置记录使 Agent 在下一轮运行时能对这些记录去重。两个文件都是针对存储的纯 Python 代码全程不涉及 Agent、模型、服务器或 API Key。测试日志即本文关联文档 TEST_LOG.md在 agno 2.8.1 源码树分支feat/agent-fscommit7df2fad3a上于 2026-07-24 实测并在FileSystem(db)构造方式变更与配额提示文案改写后复跑两个文件的输出均为确定性的。FileSystem 是什么先理解被运维的对象在被运维之前先明确存储本身。agno 的FileSystem见 libs/agno/agno/fs/fs.py是Agent 私有的、持久的文件系统对 Agent 而言它看起来就是一套普通的文件系统工具底层则是一个可插拔的BaseFS后端默认是数据库。它用于存放 Agent 自己需要跨会话、跨运行保留的持久笔记带推理过程的决策、进行中的文档、下次还需要的工作状态。其核心模型如下均可从源码确认命名空间namespace隔离同一后端 同一命名空间 同一批文件不同命名空间 完全隔离。默认命名空间为default命名空间按规范化名称隔离小写、URL 安全BANK与bank指向同一存储。命名空间还可以嵌入{user_id}、{agent_id}、{team_id}模板占位符按调用时的框架注入上下文解析缺失时失败关闭fail closed匿名运行永远不会悄悄塌缩进共享命名空间。双层配额构造FileSystem时可指定max_file_bytes单文件上限与max_namespace_bytes命名空间总上限源码中的默认值分别是1,000,000 字节单文件与20,000,000 字节命名空间。本目录的两个配方将上限刻意调小200/300 字节只是为了数字可读。永不静默驱逐任何文件都不会被静默清理配额拒绝以类型化异常与工具字符串两种形式暴露详见下文。后端可插拔第一个构造参数可以是BaseFS后端也可以是 agno 的SqliteDb/PostgresDb由 db.py 的DbFileSystem包装为每(namespace, path)一行的数据库存储SQLite 用于开发、Postgres 用于生产默认使用独立的fsschema。配额拒绝在源码中的执行点fs.pywrite()先算size_bytes len(content.encode(utf-8))超过单文件上限立即抛出QuotaExceededError(scopefile)随后用**增量delta**判断命名空间上限——只在新内容比旧文件大时才计算current_usage.total_bytes delta max_namespace_bytes因此缩小文件永远合法。append()按chunk_bytes 1估算行分隔符未知按 1 字节多估而非少估检查命名空间上限单文件上限由后端在同一个加锁 upsert 语句中强制。配额字节按 UTF-8 字节计而非字符数libs/agno/tests/unit/fs/test_fs.py中test_file_cap_counts_bytes_not_chars用单个 emoji1 字符 4 字节验证了这一点。配额恢复quota_recovery.py 全流程拆解quota_recovery.py 是存储满了怎么救的完整演练。它每次运行都生成一个全新的存储tmp/agent_fs_quota_uuid.db并把两个配额都压到极小让过程可复现、数字可读from agno.db.sqlite import SqliteDb from agno.fs import FileSystem from agno.fs.errors import QuotaExceededError DB_FILE ftmp/agent_fs_quota_{uuid4().hex}.db fs FileSystem( SqliteDb(db_fileDB_FILE), max_file_bytes200, max_namespace_bytes300, )注意其中的FileSystem(db)风格把数据库句柄作为第一个参数传入由_as_backend统一分派这正是测试日志提到的FileSystem(db)变更后的推荐写法。第一层单文件上限per-file cap配方先把 8 条记录写进seen/2026-07-22.md填到单文件上限附近然后故意再追加一条触发拒绝。程序化 API 抛出的类型化错误被捕获后打印为typed error: file 209 200QuotaExceededError见 errors.py携带三个字段scopefile或namespace、current、limit均为字节数。对于scopefilecurrent是该文件将要达到的大小209 字节而非当前大小。而 Agent 通过工具看到的则是一个工具字符串错误以Error: ...字符串返回、绝不抛出由 toolkit.py 的_quota_error生成实测输出为Error: seen/2026-07-22.md would be 209 bytes (limit 200 per file). Start a new file (for record logs, partition by date, e.g. seen/2026-07-24.md) or delete files you no longer need.这条提示本身就是恢复指引要么开新文件记录日志按日期分区要么删除不再需要的文件。恢复策略 1开启新分区。配方据此把同一条记录写入seen/2026-07-23.md成功从而印证分区确实是错误提示建议的第一条出路。第二层命名空间上限namespace cap接着配方用一个while True循环向seen/2026-07-24.md追加直到整个命名空间被填满捕获到类型化错误typed error: namespace 284 of 300Agent 侧看到的工具字符串实测为Error: storage is full (284 of 300 bytes). Delete only files you are certain are obsolete (see list_files), such as an old date partition, then retry. Do not overwrite or delete records you might still need to make room; if nothing is safely disposable, stop and report that storage is full.注意这条提示中的安全约束只允许删除确定过期的文件例如旧日期分区禁止为了腾空间而覆盖或删除可能还需要的历史记录如果没有任何可安全丢弃的内容就停下来报告存储已满。这正呼应了源码中永不静默驱逐的设计哲学——容量永远不该以丢失历史为代价。恢复策略 2按保留窗口删除配方随后演示了正确的删除方式单凭文件旧不能证明记录已过期——因为最旧就删最旧正是 Agent 静默丢失历史、开始重复上报已处理事项的成因。删除需要一个保留边界retention boundary证明这些记录永远不会再被需要。配方中由任务声明了一个 1 天的保留窗口RETENTION_DAYS 1 cutoff date(2026, 7, 24) - timedelta(daysRETENTION_DAYS) disposable [ meta.path for meta in fs.list(seen) if date.fromisoformat(meta.path.removeprefix(seen/).removesuffix(.md)) cutoff ]删除前用量为3 files / 284 bytes按策略筛出的可删除项被逐条fs.delete(path)删除后为2 files / 133 bytes随后重试的追加成功。测试日志记录的实测结果与此完全一致。配方还包含一个容易被忽略的诚实结局分支如果保留策略筛不出任何可删除项就打印nothing is provably obsolete: stop and report, do not evict history并以SystemExit(0)正常退出——走到这个分支是正确结果而非失败调用方被告知存储已满且全部记录完好无损。只有任务确实允许时才应放宽保留窗口。从外部检查与预置inspect_files.py 全流程拆解inspect_files.py 演示的是反向场景Agent 的文件对任何脚本都可达。把FileSystem指向同一个后端你就持有与 Agent 完全相同的文件若 Agent 指定了命名空间这里传入同一个即可无需 Agent、模型或服务器即可检查、读取与预置。配方结构非常精简与 Agent 侧的唯一区别是后端实例的构造方式from agno.db.sqlite import SqliteDb from agno.fs import FileSystem DB_FILE ftmp/agent_fs_inspect_{uuid4().hex}.db fs FileSystem(SqliteDb(db_fileDB_FILE))由于数据库后端是每(namespace, path)一行的存储见 db.py跨进程共享是天然的任何脚本用同一个 DB 文件 同一个命名空间构造FileSystem读到的就是 Agent 写入的同一批文件。配方的四个操作及其在测试日志中的确定性输出如下列出文件含大小与版本。fs.list()返回FileMeta列表字段为path、size_bytes、version、updated_at见 types.py。实测输出seen/2026-07-23.md 39B v1 state/last-run.md 30B v1测量用量。fs.usage()返回NamespaceUsage(file_count, total_bytes)实测为{files: 2, bytes: 69}。Agent 工具侧的list_files还会在 JSON 结果中带上usagefiles/bytes_used/bytes_limit让 Agent 在上下文里就知道自己的剩余空间。读取工作状态。fs.read(state/last-run.md)实测读回2026-07-23: briefed 3 stories——这正是读 Agent 上次跑到哪里了的运维读取。预置已处理记录并用 contains() 验证。追加两条新记录后再做批量精确行成员检查fs.append(seen/2026-07-23.md, kite-os-release\nnimbus-gpu-cloud\n) result fs.contains([kite-os-release, brand-new-story], directoryseen)实测返回{found: [kite-os-release], missing: [brand-new-story]}。这正是下次运行前去重的预置手法脚本把已处理状态回填进存储定时 Agent 下次启动时用check_linescontains的工具侧形式检查directoryseen就能跳过found中的全部内容。这就是在首次上线前回填已处理状态的标准方式。测试日志中的 Gap诚实的自我审视inspect_files.py在测试日志中被评为PARTIAL部分通过原因是其演示方式并未证明其标题所宣称的能力该示例没有展示它的核心主张。它在同一个进程里铸造了一个一次性的tmp/agent_fs_inspect_uuid.db自己往里播种然后又检查自己刚写的数据。没有任何一处展示一个脚本去读取某个 Agent 写下的存储——因此即使FileSystem完全没有跨进程共享能力打印出的每一行也会一模一样。这是一个值得学习的技术写作/示例设计问题跨进程能力是真的由libs/agno/tests/中的测试覆盖例如 test_fs.py 与libs/agno/tests/integration/fs/下的test_db_concurrency.py、test_db_semantics.py但这个配方文件没有把它摆上屏幕。测试日志同时给出了明确的改进建议把脚本指向tmp/filesystem/getting_started.db——那正是本 cookbook 中 Agent 实际写入的存储由 01_getting_started 的basic.py跨两次运行复用、刻意验证进程间持久性。按此建议改造后脚本就真正演示了外部脚本直达 Agent 存储的运维场景先运行basic.py两遍让 Agent 写入存储再把inspect_files.py的DB_FILE改为同一文件就能在纯 Python 中列出、读取并预置 Agent 真实拥有的文件。这个 Gap 属于示例展示不足而非功能缺失。配额语义的测试级证据配额的精确语义并非文档自说自话而是有单元测试背书。test_fs.py 中的TestQuota类逐一验证了test_file_cap_boundary_on_write恰好压线10 字节写入成功多 1 字节11 字节拒绝且scopefile、current11、limit10与本文配方输出的file 209 200完全同一套字段语义test_file_cap_counts_bytes_not_chars配额按 UTF-8字节而非字符计数test_file_cap_on_append追加路径同样执行单文件上限test_namespace_cap_on_write命名空间上限拒绝时current是当前已用量6limit是上限10test_namespace_cap_overwrite_uses_delta覆盖写按增量计缩小永远合法、涨回恰好压线合法test_namespace_cap_on_append_overestimates_separator追加时对行分隔符按 1 字节多估6 4 1 11 10 被拒。这些测试与配方互为印证无论走程序化 API类型化异常还是工具表面Error: ...字符串配额拒绝的字节语义完全一致。运行方法与前提两个配方均无需任何环境变量不使用模型python cookbook/13_filesystem/05_operations/quota_recovery.py python cookbook/13_filesystem/05_operations/inspect_files.py适用场景摘自 README.mdAgent 的写入开始失败需要查看并修复其存储→quota_recovery.py运维脚本、测试与迁移需要在不运行 Agent 的情况下读取或预置 Agent 的文件→inspect_files.py要构建这两个配方所操作的存储从 01_getting_started 起步被检查的记录日志布局来自 02_durable_records。需要留意的一个删除前提配方通过 Python API 直接调用fs.delete(path)而Agent 侧的删除工具本身是 opt-in 的——只有fs.tools(allow_deleteTrue)时 Agent 才持有delete_file工具默认工具面是notes sevenread_file、write_file、append_file、replace_lines、list_files、search_content、move_filedelete_file与批量去重原语check_lines都需要显式启用。运维脚本不受此限因为它直接操作后端但对 Agent 而言删除始终是被刻意保守地开放的能力。小结05_operations传递的运维方法论可以浓缩为三点容量永远显式拒绝、绝不静默驱逐双层配额的字节语义与错误字符串在程序化 API、工具表面、单元测试三处保持一致恢复必须带保留边界开新分区是首选删除只能删除被保留策略证明过期的分区否则诚实报告存储已满并保全记录Agent 的存储对外部脚本完全透明同一后端 同一命名空间即同一批文件检查、修复、预置都可以在无模型、无 API Key 的纯 Python 中完成。配合测试日志中对inspect_files.py的 Gap 分析读者还能得到一个可立即落地的改进思路把配方指向 Agent 真实写入的tmp/filesystem/getting_started.db即可把外部运维从演示变成实战。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
agno FileSystem 运维实操：从外部检查、修复与预置 Agent 文件存储（quota_recovery 与 inspect_files 全解析）
agno FileSystem 运维实操从外部检查、修复与预置 Agent 文件存储quota_recovery 与 inspect_files 全解析【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno本篇技术指南聚焦 agno 的持久化文件系统FileSystem在运行期之外的运维场景当一个 Agent 的文件存储写入开始失败、需要被外部脚本检查、修复或预置时如何绕过 Agent、模型与 API Key用纯 Python 直接操作与 Agent 完全相同的存储后端。读完本文你将掌握双层配额per-file / per-namespace的触发机制与精确错误语义、两种官方推荐的恢复策略按日期分区、按保留窗口删除、以及如何用脚本读取、测量、预置 Agent 的 已处理记录从而让定时 Agent 在首次上线前就能正确去重。章节定位05_operations 在 FileSystem 教程中的角色在 agno cookbook 的 13_filesystem 体系中前几个章节如 01_getting_started解决的是如何给 Agent 挂上一个持久化文件系统02_durable_records 则讲解记录日志record log的布局与去重模式。而05_operations解决的是完全不同的一个问题存储建好之后如何从外部运维它。按 README.md 的定义本目录包含两个相互独立的操作配方且刻意没有basic.py两者都不是更简单的入门起点quota_recovery.py故意同时触发单文件上限与命名空间上限展示 Agent 会看到的确切错误字符串并按照错误提示给出的两种路径完成恢复——开启新分区、删除不再需要的分区。inspect_files.py把脚本指向 Agent 使用的同一个存储后端然后列出文件、测量用量、读取工作状态、预置记录使 Agent 在下一轮运行时能对这些记录去重。两个文件都是针对存储的纯 Python 代码全程不涉及 Agent、模型、服务器或 API Key。测试日志即本文关联文档 TEST_LOG.md在 agno 2.8.1 源码树分支feat/agent-fscommit7df2fad3a上于 2026-07-24 实测并在FileSystem(db)构造方式变更与配额提示文案改写后复跑两个文件的输出均为确定性的。FileSystem 是什么先理解被运维的对象在被运维之前先明确存储本身。agno 的FileSystem见 libs/agno/agno/fs/fs.py是Agent 私有的、持久的文件系统对 Agent 而言它看起来就是一套普通的文件系统工具底层则是一个可插拔的BaseFS后端默认是数据库。它用于存放 Agent 自己需要跨会话、跨运行保留的持久笔记带推理过程的决策、进行中的文档、下次还需要的工作状态。其核心模型如下均可从源码确认命名空间namespace隔离同一后端 同一命名空间 同一批文件不同命名空间 完全隔离。默认命名空间为default命名空间按规范化名称隔离小写、URL 安全BANK与bank指向同一存储。命名空间还可以嵌入{user_id}、{agent_id}、{team_id}模板占位符按调用时的框架注入上下文解析缺失时失败关闭fail closed匿名运行永远不会悄悄塌缩进共享命名空间。双层配额构造FileSystem时可指定max_file_bytes单文件上限与max_namespace_bytes命名空间总上限源码中的默认值分别是1,000,000 字节单文件与20,000,000 字节命名空间。本目录的两个配方将上限刻意调小200/300 字节只是为了数字可读。永不静默驱逐任何文件都不会被静默清理配额拒绝以类型化异常与工具字符串两种形式暴露详见下文。后端可插拔第一个构造参数可以是BaseFS后端也可以是 agno 的SqliteDb/PostgresDb由 db.py 的DbFileSystem包装为每(namespace, path)一行的数据库存储SQLite 用于开发、Postgres 用于生产默认使用独立的fsschema。配额拒绝在源码中的执行点fs.pywrite()先算size_bytes len(content.encode(utf-8))超过单文件上限立即抛出QuotaExceededError(scopefile)随后用**增量delta**判断命名空间上限——只在新内容比旧文件大时才计算current_usage.total_bytes delta max_namespace_bytes因此缩小文件永远合法。append()按chunk_bytes 1估算行分隔符未知按 1 字节多估而非少估检查命名空间上限单文件上限由后端在同一个加锁 upsert 语句中强制。配额字节按 UTF-8 字节计而非字符数libs/agno/tests/unit/fs/test_fs.py中test_file_cap_counts_bytes_not_chars用单个 emoji1 字符 4 字节验证了这一点。配额恢复quota_recovery.py 全流程拆解quota_recovery.py 是存储满了怎么救的完整演练。它每次运行都生成一个全新的存储tmp/agent_fs_quota_uuid.db并把两个配额都压到极小让过程可复现、数字可读from agno.db.sqlite import SqliteDb from agno.fs import FileSystem from agno.fs.errors import QuotaExceededError DB_FILE ftmp/agent_fs_quota_{uuid4().hex}.db fs FileSystem( SqliteDb(db_fileDB_FILE), max_file_bytes200, max_namespace_bytes300, )注意其中的FileSystem(db)风格把数据库句柄作为第一个参数传入由_as_backend统一分派这正是测试日志提到的FileSystem(db)变更后的推荐写法。第一层单文件上限per-file cap配方先把 8 条记录写进seen/2026-07-22.md填到单文件上限附近然后故意再追加一条触发拒绝。程序化 API 抛出的类型化错误被捕获后打印为typed error: file 209 200QuotaExceededError见 errors.py携带三个字段scopefile或namespace、current、limit均为字节数。对于scopefilecurrent是该文件将要达到的大小209 字节而非当前大小。而 Agent 通过工具看到的则是一个工具字符串错误以Error: ...字符串返回、绝不抛出由 toolkit.py 的_quota_error生成实测输出为Error: seen/2026-07-22.md would be 209 bytes (limit 200 per file). Start a new file (for record logs, partition by date, e.g. seen/2026-07-24.md) or delete files you no longer need.这条提示本身就是恢复指引要么开新文件记录日志按日期分区要么删除不再需要的文件。恢复策略 1开启新分区。配方据此把同一条记录写入seen/2026-07-23.md成功从而印证分区确实是错误提示建议的第一条出路。第二层命名空间上限namespace cap接着配方用一个while True循环向seen/2026-07-24.md追加直到整个命名空间被填满捕获到类型化错误typed error: namespace 284 of 300Agent 侧看到的工具字符串实测为Error: storage is full (284 of 300 bytes). Delete only files you are certain are obsolete (see list_files), such as an old date partition, then retry. Do not overwrite or delete records you might still need to make room; if nothing is safely disposable, stop and report that storage is full.注意这条提示中的安全约束只允许删除确定过期的文件例如旧日期分区禁止为了腾空间而覆盖或删除可能还需要的历史记录如果没有任何可安全丢弃的内容就停下来报告存储已满。这正呼应了源码中永不静默驱逐的设计哲学——容量永远不该以丢失历史为代价。恢复策略 2按保留窗口删除配方随后演示了正确的删除方式单凭文件旧不能证明记录已过期——因为最旧就删最旧正是 Agent 静默丢失历史、开始重复上报已处理事项的成因。删除需要一个保留边界retention boundary证明这些记录永远不会再被需要。配方中由任务声明了一个 1 天的保留窗口RETENTION_DAYS 1 cutoff date(2026, 7, 24) - timedelta(daysRETENTION_DAYS) disposable [ meta.path for meta in fs.list(seen) if date.fromisoformat(meta.path.removeprefix(seen/).removesuffix(.md)) cutoff ]删除前用量为3 files / 284 bytes按策略筛出的可删除项被逐条fs.delete(path)删除后为2 files / 133 bytes随后重试的追加成功。测试日志记录的实测结果与此完全一致。配方还包含一个容易被忽略的诚实结局分支如果保留策略筛不出任何可删除项就打印nothing is provably obsolete: stop and report, do not evict history并以SystemExit(0)正常退出——走到这个分支是正确结果而非失败调用方被告知存储已满且全部记录完好无损。只有任务确实允许时才应放宽保留窗口。从外部检查与预置inspect_files.py 全流程拆解inspect_files.py 演示的是反向场景Agent 的文件对任何脚本都可达。把FileSystem指向同一个后端你就持有与 Agent 完全相同的文件若 Agent 指定了命名空间这里传入同一个即可无需 Agent、模型或服务器即可检查、读取与预置。配方结构非常精简与 Agent 侧的唯一区别是后端实例的构造方式from agno.db.sqlite import SqliteDb from agno.fs import FileSystem DB_FILE ftmp/agent_fs_inspect_{uuid4().hex}.db fs FileSystem(SqliteDb(db_fileDB_FILE))由于数据库后端是每(namespace, path)一行的存储见 db.py跨进程共享是天然的任何脚本用同一个 DB 文件 同一个命名空间构造FileSystem读到的就是 Agent 写入的同一批文件。配方的四个操作及其在测试日志中的确定性输出如下列出文件含大小与版本。fs.list()返回FileMeta列表字段为path、size_bytes、version、updated_at见 types.py。实测输出seen/2026-07-23.md 39B v1 state/last-run.md 30B v1测量用量。fs.usage()返回NamespaceUsage(file_count, total_bytes)实测为{files: 2, bytes: 69}。Agent 工具侧的list_files还会在 JSON 结果中带上usagefiles/bytes_used/bytes_limit让 Agent 在上下文里就知道自己的剩余空间。读取工作状态。fs.read(state/last-run.md)实测读回2026-07-23: briefed 3 stories——这正是读 Agent 上次跑到哪里了的运维读取。预置已处理记录并用 contains() 验证。追加两条新记录后再做批量精确行成员检查fs.append(seen/2026-07-23.md, kite-os-release\nnimbus-gpu-cloud\n) result fs.contains([kite-os-release, brand-new-story], directoryseen)实测返回{found: [kite-os-release], missing: [brand-new-story]}。这正是下次运行前去重的预置手法脚本把已处理状态回填进存储定时 Agent 下次启动时用check_linescontains的工具侧形式检查directoryseen就能跳过found中的全部内容。这就是在首次上线前回填已处理状态的标准方式。测试日志中的 Gap诚实的自我审视inspect_files.py在测试日志中被评为PARTIAL部分通过原因是其演示方式并未证明其标题所宣称的能力该示例没有展示它的核心主张。它在同一个进程里铸造了一个一次性的tmp/agent_fs_inspect_uuid.db自己往里播种然后又检查自己刚写的数据。没有任何一处展示一个脚本去读取某个 Agent 写下的存储——因此即使FileSystem完全没有跨进程共享能力打印出的每一行也会一模一样。这是一个值得学习的技术写作/示例设计问题跨进程能力是真的由libs/agno/tests/中的测试覆盖例如 test_fs.py 与libs/agno/tests/integration/fs/下的test_db_concurrency.py、test_db_semantics.py但这个配方文件没有把它摆上屏幕。测试日志同时给出了明确的改进建议把脚本指向tmp/filesystem/getting_started.db——那正是本 cookbook 中 Agent 实际写入的存储由 01_getting_started 的basic.py跨两次运行复用、刻意验证进程间持久性。按此建议改造后脚本就真正演示了外部脚本直达 Agent 存储的运维场景先运行basic.py两遍让 Agent 写入存储再把inspect_files.py的DB_FILE改为同一文件就能在纯 Python 中列出、读取并预置 Agent 真实拥有的文件。这个 Gap 属于示例展示不足而非功能缺失。配额语义的测试级证据配额的精确语义并非文档自说自话而是有单元测试背书。test_fs.py 中的TestQuota类逐一验证了test_file_cap_boundary_on_write恰好压线10 字节写入成功多 1 字节11 字节拒绝且scopefile、current11、limit10与本文配方输出的file 209 200完全同一套字段语义test_file_cap_counts_bytes_not_chars配额按 UTF-8字节而非字符计数test_file_cap_on_append追加路径同样执行单文件上限test_namespace_cap_on_write命名空间上限拒绝时current是当前已用量6limit是上限10test_namespace_cap_overwrite_uses_delta覆盖写按增量计缩小永远合法、涨回恰好压线合法test_namespace_cap_on_append_overestimates_separator追加时对行分隔符按 1 字节多估6 4 1 11 10 被拒。这些测试与配方互为印证无论走程序化 API类型化异常还是工具表面Error: ...字符串配额拒绝的字节语义完全一致。运行方法与前提两个配方均无需任何环境变量不使用模型python cookbook/13_filesystem/05_operations/quota_recovery.py python cookbook/13_filesystem/05_operations/inspect_files.py适用场景摘自 README.mdAgent 的写入开始失败需要查看并修复其存储→quota_recovery.py运维脚本、测试与迁移需要在不运行 Agent 的情况下读取或预置 Agent 的文件→inspect_files.py要构建这两个配方所操作的存储从 01_getting_started 起步被检查的记录日志布局来自 02_durable_records。需要留意的一个删除前提配方通过 Python API 直接调用fs.delete(path)而Agent 侧的删除工具本身是 opt-in 的——只有fs.tools(allow_deleteTrue)时 Agent 才持有delete_file工具默认工具面是notes sevenread_file、write_file、append_file、replace_lines、list_files、search_content、move_filedelete_file与批量去重原语check_lines都需要显式启用。运维脚本不受此限因为它直接操作后端但对 Agent 而言删除始终是被刻意保守地开放的能力。小结05_operations传递的运维方法论可以浓缩为三点容量永远显式拒绝、绝不静默驱逐双层配额的字节语义与错误字符串在程序化 API、工具表面、单元测试三处保持一致恢复必须带保留边界开新分区是首选删除只能删除被保留策略证明过期的分区否则诚实报告存储已满并保全记录Agent 的存储对外部脚本完全透明同一后端 同一命名空间即同一批文件检查、修复、预置都可以在无模型、无 API Key 的纯 Python 中完成。配合测试日志中对inspect_files.py的 Gap 分析读者还能得到一个可立即落地的改进思路把配方指向 Agent 真实写入的tmp/filesystem/getting_started.db即可把外部运维从演示变成实战。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
