SiloBrief 这个项目解决的是 air-gapped network物理隔离网络里的代码上下文导出问题。先把结论放前面这类工具最值得关注的不是“能不能导出”而是“能不能只导出该导出的部分”。在隔离环境下完整拷贝一个代码库往往不现实也不安全把经过筛选、精简、脱敏的上下文整理成一份结构化 Brief才是真正能落地的用法。这几年 AI 编程工具越来越普及不管是 Claude Code、Codex还是 VS Code 里的各种智能插件它们都依赖“代码上下文”来理解项目。可一旦代码在隔离网络里上下文怎么安全地送出去就成了一个很现实的问题。这篇文章按实际落地顺序拆先讲为什么需要它再讲跑通最小链路需要什么条件然后重点说筛选逻辑、输出格式、常见坑和排错顺序。适合在金融、能源、工业制造、涉密研发等有网络隔离要求的团队也适合想给 AI 工具喂上下文、但又不愿意整包拷贝代码的开发者。1. 隔离网络里的代码为什么还需要“导出来”1.1 隔离网络不是“一个文件夹”而是一套约束air-gapped network 直译是“空气间隙网络”意思是这台机器、这套系统在物理层面和互联网隔开不能直接访问外部网络。它常见于工业控制系统、金融核心交易、能源调度、涉密研发这类对数据安全要求极高的环境。代码可以通过审批流程进入隔离网络但想出来通常只能走人工审核后的移动介质、专用摆渡通道或者单向传输设备过程相当严格。这就带来一个现实矛盾。AI 工具大多运行在联网侧你手里有一段在隔离网络里写了很久的业务代码想让它帮忙梳理模块关系、生成接口文档、做代码结构分析首先得把“代码的上下文”送出去。注意这里说的上下文不是把整个仓库打成一个压缩包。压缩包体积大、审批难而且大部分内容其实没必要出去。一个几十万行的老项目真正需要被外部工具理解的核心文件可能只有几十个。1.2 SiloBrief 解决的是“双向都难”的问题难在哪从隔离网络往外带东西难在审批和安全从 AI 工具的角度看难在上下文窗口和可用性。你把 50 万行代码全带出去大多数 AI 编程工具根本吃不下或者还没开始分析就已经把上下文窗口撑爆了。近期不少人用 AI 编程工具时会遇到类似 “context is too large and auto-compaction could not recover” 或者 “this models maximum context length is 1048576 tokens” 这类报错原因往往不是模型能力不够而是喂进去的东西太多太杂导致工具在长上下文里丢失了真正重要的信息。SiloBrief 的思路是“selectively export”也就是按需筛选导出。它先扫描代码库再根据规则过滤最后生成一份结构化的代码简报。这份简报可以带出隔离网络进入联网侧的 AI 工具、文档系统或者评审流程。整个过程把“整库复制”拆成“定向摘要”既降低审批风险也减少上下文浪费。这个定位听起来简单但真正落地时会发现很多细节必须在动手前想清楚。2. 先明确要导出的是什么再谈怎么导2.1 代码上下文不是源码本身很多第一次接触这个场景的人会问导出上下文为什么不直接把源码拷出来因为“代码上下文”和“源码”用途不同。源码是项目运行的完整基础上下文是别人理解项目时需要的那部分信息。上下文更接近一份经过组织的技术简报至少应该包含项目的整体结构和模块边界核心入口、接口定义、数据模型关键函数的实现逻辑可以带少量代码片段依赖关系、构建方式、运行环境说明最近变更的文件和变更原因打个比方源码是一整座城市上下文是城市地图。AI 工具拿到地图之后才能针对性地提问或生成代码而不是被海量文件淹没。直接丢源码给 AI 工具就像把一整箱城市档案扔过去让它自己考古效率很低。2.2 导出内容要有颗粒度分级我实际使用时会按三个颗粒度控制导出内容不同任务选不同级别颗粒度内容适合场景项目级README、目录树、模块说明、技术栈、构建脚本让 AI 先理解项目全貌文件级选中的关键文件和它们的简要注释代码评审、接口梳理函数级特定函数、类、数据结构的实现与签名改 Bug、补测试、局部重构默认建议先做项目级确认方向后再往文件级、函数级深入。不要一上来就导出所有文件的完整内容那不是上下文是新的负担。2.3 从使用场景反推过滤条件过滤条件不是拍脑袋定的要从使用场景反推。先想清楚这份 Brief 要干什么如果给 AI 助手梳理整体架构把构建产物、依赖缓存、二进制文件、日志全部排除。如果用于安全审计每处敏感配置出现的路径都要保留但内容要做脱敏。如果用于新人接手旧项目导出重点放在 README、接口文档、测试用例和数据模型上。过滤规则应该写在配置文件里保证可重复执行。这样每次导出的口径一致审核人也更容易核对。规则散落在命令行参数里时间一长自己都说不清上次到底导出了什么。3. 最小可用链路从扫描到生成 Brief3.1 搭建一个可重复验证的测试环境我在测试这类工具时不会直接拿生产代码去试而是先在本地准备一个模拟目录。目录里故意放一些不该被导出的内容等会好验证过滤规则是否真的生效。demo-repo/ README.md src/ main.py service/ user_service.py order_service.py models/ user.py order.py config/ settings.yaml secrets.example.yaml tests/ test_user.py dist/ build.log .git/这个目录里放着 README 和核心代码也放着 dist、日志、示例配置正好用来测试过滤能力。如果条件允许建议用一台不联网的虚拟机模拟隔离网络把从“扫描”到“生成 Brief”再到“跨机器传输”的完整流程走一遍。第一次测试不要追求大项目选一个小仓库跑通整条链路再逐步放大。3.2 扫描、过滤、生成三步走这类工具的基本流程我归纳成三步扫描遍历目录识别文件类型、语言、大小、行数生成文件清单。过滤按配置文件规则决定哪些文件进入候选列表哪些排除再在候选列表内部做敏感信息检测。生成把候选文件整理成结构化 Brief包含文件路径、说明、关键片段和依赖关系。生成 Brief 的输出格式可以近似这样# Project Brief: demo-repo ## Overview - 项目用途用户与订单服务 - 技术栈Python 3.11FastAPI - 构建方式poetry install uvicorn main:app ## Entry Points - src/main.py应用启动入口 ## Key Files ### src/service/user_service.py - 职责用户注册、登录、资料查询 - 接口create_user, authenticate, get_user - 依赖src/models/user.py ## Sensitive Findings - config/settings.yaml 中可能存在数据库连接串建议人工确认这份 Brief 可以直接保存成 Markdown也可以转成 JSON 或固定文本格式。格式统一很重要因为后面接 AI 工具时稳定的结构比花哨的展示有用得多。3.3 导出前要做一次人工复核生成之后别急着把文件拷贝出去。先在工具里生成一份“导出清单”写明这次导出了哪些文件、哪些片段、检测到哪些敏感项然后对照清单做人工复核。这一步不是浪费时间。隔离网络里的每一次数据外传最终都要有人负责。工具生成的清单就是负责人做判断的依据。没有清单的导出等于盲人摸象出了问题很难追溯。4. 选择性导出本质是安全边界问题4.1 敏感信息过滤不该是可选功能在联网环境里做代码工具漏掉一个密钥可能只是小事故在隔离网络里漏掉一个密钥可能直接影响整个项目的合规性。所以敏感信息过滤必须是默认开启的而不是事后插件。至少需要覆盖这些模式各类 API Key、Token、密码占位符包括看起来像真实值的内容数据库连接串、私钥、证书内网主机名、真实 IP、内部域名员工姓名、手机号、邮箱等个人信息合同、订单、客户相关的业务敏感字段过滤可以分两级先自动正则扫描并删除再给疑似项打标让人类确认。不要指望一条规则解决所有问题。4.2 从“不导出什么”反推过滤规则写过滤规则时我习惯先列“绝对不能出去的东西”再列“可以出去的默认范围”。下面是一份示意配置具体语法以你使用的工具为准# 示例过滤配置 exclude_paths [ .git, node_modules, dist, build, *.log, *.lock, *.png, *.jpg, *.bin, data/, secrets/, ] include_patterns [ *.py, *.md, *.yaml, *.yml, *.json, ] sensitive_patterns [ AKIA[0-9A-Z]{16}, # 云厂商密钥示例 password\\s*\\s*., BEGIN (RSA|PRIVATE|OPENSSH) KEY, \\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}, # IP 示例 ]注意IP 正则很容易把无关内容标出来建议只在特定配置文件中启用。黑白名单规则要能随时调整否则会因为误报导致整个导出流程卡住。4.3 人工复核仍然是必要的最后一道关口自动化过滤做得再好也要保留人工确认。我见过不少工具把“自动脱敏”当成万能药结果生成文件里还是会出现硬编码的测试账号、内网路径甚至注释里的敏感信息。尤其是注释、文档、截图说明这些地方最容易漏。一个稳妥做法导出文件生成后先自动扫描一遍并给出风险等级风险等级高的文件默认不进入最终包需要人工手动确认后才能加入。这样可以减少“无声漏出”的概率也让每次导出的责任人心里有数。5. 输出格式如何和 AI 编程工具真正对接5.1 上下文窗口是硬约束不管 Brief 做得多精致最终都要交给某个工具消费。现在主流的 AI 编程工具都有上下文窗口限制不同模型从十几万到上百万 token 不等但“能用窗口”不等于“塞满窗口”。窗口塞得太满工具在回复时连基础指令都可能执行不好严重的会直接报 context 相关错误整轮对话报废。所以 Brief 默认要控制体积。我给一个参考值不涉及标准项目级 Brief 控制在 5000 到 10000 token 以内文件级 Brief 控制在 2000 到 5000 token 以内函数级片段控制在 500 到 2000 token 以内。实际跑的时候更推荐分步喂。第一次只喂项目级 Brief让 AI 先出结论再按需补充文件级内容。这种做法对工具更友好也更容易定位问题。5.2 给 AI 工具一份“可导航”的 Brief所谓可导航是指 AI 工具拿到 Brief 之后能知道“该看哪个文件、哪个函数、哪条依赖”。因此 Brief 里应该保留稳定的文件路径和符号名而不是把代码片段打散后随意堆在一起。另外建议在 Brief 头部写清项目背景和技术栈。AI 工具的判断在很大程度上依赖这些元信息。你告诉它“这是一个 FastAPI 项目main.py 是入口”后续分析质量会明显好于只丢一堆代码片段。生成 Brief 时保留原始文件路径后面的追问和补导出都会方便很多。5.3 接入时报错先看密钥和网络策略接入 AI 工具时很多人会看到 401 unauthorized、api_key_required、invalid_api_key 这类错误通常有三个原因API Key 没配置或配置了错误的环境变量调用方所在网络的出口策略不允许访问目标接口中间层把请求拦了。排查顺序是先确认 API Key 是否正确写入配置文件和日志。再确认运行环境的网络访问策略是否允许该请求这一步要遵循公司网络规范。最后检查是否有本地代理或网关在中间拦截。这里多说一句如果 Brief 是给人工阅读的这部分基本不用管如果是给自动化工具用的把密钥配置和网络策略提前整理好能省大量排错时间。6. 容易踩的坑和排查顺序6.1 启动失败先看路径、权限再看依赖版本工具跑不起来时不要第一时间怀疑代码有问题按顺序排查检查是否使用了绝对路径可执行文件是否有运行权限。检查运行时版本和依赖清单是否匹配。查看启动日志里有没有模块缺失、端口占用。如果是从源码构建的确认是否完成了安装步骤。隔离网络里还有一个特殊问题联网侧可以直接用包管理器装依赖隔离侧往往要用离线包。建议把依赖版本锁定提前准备离线依赖包避免因为版本不一致导致运行结果不同。6.2 输出为空或内容不全时按输入、过滤、格式顺序排查如果生成的 Brief 缺失文件或者导出结果为空不要急着调整工具参数按这个顺序查现象优先检查次要检查启动即报错路径、权限、依赖版本运行时版本、端口占用输出为空输入目录、文件编码过滤规则、输出模板上限内容不全排除规则、符号链接二次过滤、文件大小限制Brief 过大过滤范围输出模板、上下文预算值得特别关注的是文件编码。很多老项目是 GBK 或者特殊编码扫描工具默认按 UTF-8 读取就会出现“文件存在但内容乱码或为空”的情况。这类问题与工具本身无关却最容易浪费排查时间。6.3 内容太多时优先缩小范围而不是扩大窗口遇到“上下文太大”的问题正确的方向是减少输入范围而不是换一个更大窗口的模型。你可以删掉 node_modules、dist、log 等目录。按模块导出每次只处理一个服务。用版本管理工具的 diff 只看最近变更。让工具先生成摘要再对摘要做二次筛选。我自己测试时经常把一次导出的文件数从默认的上百个降到二三十个效果反而更好。AI 工具处理几十个关键文件比处理几百个无关文件靠谱得多。7. 增量导出与日常维护思路7.1 增量导出只带变更部分出去代码是持续更新的如果每次都要全量重新扫描、过滤、生成不仅慢审批压力也大。很多团队会在工具里加“增量模式”记录上次导出的基线只处理最近变更的文件。增量模式至少要处理三个问题变更来源基于版本管理工具的 diff、文件修改时间还是目录监控事件。变更范围哪些文件进入增量 Brief哪些仍属于全量范围。依赖联动一个接口改动了依赖它的消费方要不要一起导出。只导出“改动的文件”有时候不够。比如接口签名变了消费方代码没改但 AI 工具要看两侧关系才能给出正确建议。所以增量模式最好支持按依赖关系扩展一般扩展到一层或两层就够用。7.2 版本命名、日志和审批记录隔离网络的导出往往需要审计。每次导出的 Brief 建议带上这些信息生成时间、工具版本、配置版本。导出的文件清单和过滤规则摘要。敏感信息扫描结果。导出人、审批人和审批结果。这些信息可以写进 Brief 文件头部也可以单独生成一份 manifest。长期维护时这份记录的价值比 Brief 本身还大因为它决定了整个流程是否可追溯、可复盘。没有记录的导出就等于没有发生过。8. 什么场景不建议用这类方案8.1 它是上下文打包工具不是代码迁移工具如果目标是“把整个代码库完整搬到另一个网络环境”SiloBrief 这类工具并不合适。它强调的是 selectively 和 brief也就是有筛选、有精简、面向理解场景。真要迁移完整代码库应该走团队正式的代码摆渡和版本库同步流程而不是靠生成 Brief 来实现。工具用错场景结果通常不如不做。8.2 需要明确边界什么时候该人工安全敏感度极高的项目哪怕 Brief 已经做了脱敏外发前也要走人工评审。自动化工具可以减少遗漏但不应该替代制度。尤其是涉密等级高的环境任何内容外传都要有明确的审批单和责任人。工具能做的是让决策过程更透明让审批人能看到“这次导出了什么、为什么是这些”。如果团队还没有明确的导出审批机制建议先补制度再上工具。否则工具越自动化失控的风险反而越大。8.3 小团队和临时任务要控制成本最后说一点务实的。小团队偶尔需要把一两个文件带出隔离网络给 AI 工具看没必要先搭建一套完整的导出系统。手动写一份 Markdown把关键文件路径、代码片段、上下文背景整理清楚可能更快。只有当你需要频繁、重复、多人协作地做这件事时SiloBrief 这类工具才值得投入时间评估和部署。先跑通单次任务再谈自动化先满足当前需求再扩展批量。这是我做工具选型时反复提醒自己的原则也是验证这类方案最稳妥的路径。