看到这个标题，可能不少正在做RAG（检索增强生成）的同学都会愣一下：27个脚本，还“不进上下文”，一句话就能触发文档扫描？我刚开始接触这个玩法的时候也觉得玄乎，但把我手头那个知识库项目里堆积的入库前扫描需求一个个列出来之后，我反而觉得“27个”这个数字太真实了。真到了RAG入库这个环节，你会发现自己面对的不是“需不需要扫描”的问题，而是“怎么让扫描在Agent的上下文里塞得下、跑得动、还能说得清”。这篇文章不聊理论，就是把我自己实际搭建“文档扫描Agent技能”的经验拆开讲清楚。内容包括：为什么入库前扫描非做不可，Agent Skills到底是怎么省上下文的，27个脚本怎么拆怎么编排，以及我从零搭起这个扫描技能时踩过的一堆坑。如果你正在做RAG数据治理、文档清洗、或者想把一批脚本变成Agent可调用的能力，这篇文章应该能给你省掉不少弯路。1. 先搞明白：入库前扫描到底在防什么1.1 RAG的“垃圾进垃圾出”魔咒RAG的检索质量，很大程度上取决于你喂进向量库的“原料”干不干净。我见过很多项目，线上问答答得离谱，查到最后根本不是模型的问题，而是源文档本身就是一堆“地雷”：PDF解析出来是一整页乱码、扫描件OCR识别出了错别字、正文里混着身份证号、同一篇文章被上传了十几个重复版本、Markdown标题层级乱七八糟导致切片逻辑直接崩溃。这些脏数据一旦进了向量库，就会被切块、向量化、编入索引。等用户提问时，检索结果把这些坏块返回给模型，模型再聪明也只能基于坏内容一本正经地胡说八道。而且入库之后你再想去修，得把索引里的对应块找出来删除、重新切分、重新向量化，成本和风险比入库前做一次扫描高得多。所以我一直坚持：入库前加一道“文档扫描”做质量闸门，能拦截的错误绝不拖到检索阶段。这道闸门要看的不是单一指标，而是格式、编码、内容质量、敏感信息、结构完整性等多个维度。它不像是跑一个“能跑就行”的脚本，更像是给文档做一次全面体检。1.2 27个脚本背后的分类逻辑刚开始我以为把几个检查规则写进一个大脚本就完事了。后来发现，不同来源的文档出问题的模式完全不同：从某系统导出的PDF经常是编码错乱，从网页抓下来的Markdown经常是空段落和重复标题，而扫描件则要面对OCR置信度和敏感信息泄漏问题。于是我把扫描需求拆成了四类，一共积累了27个独立脚本：类别扫描重点代表性脚本脚本数量格式与编码乱码检测、编码识别、空白页、截断文件detect_garbled_text.py、check_truncated_pdf.py8内容质量空段落、低信息密度、相似重复、标题层级异常simhash_duplicate.py、empty_section_scanner.py9安全合规手机号、身份证、银行卡、API密钥、内部标记pii_regex_scanner.py、secret_key_detector.py6结构解析图片引用断裂、语言检测、元数据完整性markdown_link_checker.py、lang_detector.py4为什么拆这么细？因为每个脚本都是独立单元，可以单独调试、单独更新，某类规则误报了不会影响其他检查；更重要的是，Agent 在调用时可以根据文档类型“按需组合”，而不是每次把所有规则都跑一遍。比如内部技术文档可以跳过敏感信息扫描（或只跑API密钥检测），而对外资料则必须全量过合规检查。1.3 为什么必须赶在“入库前”很多人会问：能不能等检索结果有问题再修复？我的回答是：等出了问题再去定位，根本不知道是哪个源文档哪一段造成的。向量检索是相关性匹配，不是你改了源文件索引就会自动更新的。如果脏数据早就进了库，你会面临“检索命中了一堆坏块，但用户的问题本身没有问题”的尴尬局面。把扫描前置到入库前，核心好处有三点：第一，污染面可控，坏文档压根没机会进入索引；第二，修复成本低，重新处理原始文件比清理向量库便宜太多；第三，审计上有据可查，每次入库都有一条“扫描报告”，哪些文件通过、哪些被拦截、拦截原因是什么，清清楚楚。这也是我后来坚持做扫描报告归档的原因。2. Agent Skills：让27个脚本待在工具箱里，而不是口袋里2.1 先理解Agent Skills和普通脚本调用的区别常见的Agent工具调用方式，是把一堆函数直接注册成可调用接口。你当然可以把27个脚本封装成27个函数，然后告诉Agent“你有这么多工具可以用”。但问题来了：这些函数的描述、参数说明、使用示例都要写进系统提示词里（也就是上下文里）。一个精确定义的函数描述动辄一两百个token，27个下来就是几千token，而且Agent在理解一大批工具时，很容易在选择上“犯迷糊”。Agent Skills更像是一种“可被按需加载的技能包”。它的核心不是把脚本内容塞给Agent，而是只给Agent一份精简的技能清单。清单里包含技能名称、一句话说明、参数Schema。Agent看到用户需求后，根据技能描述判断该调用哪个技能，然后框架从外部加载真正的脚本并执行。脚本代码、依赖逻辑都在Agent上下文之外，跑完之后只把结果摘要回传。我用一个比喻来理解这件事：你是一个主厨，掌握27道菜的做法，但你不能把这27道菜谱全背在身上；你只需要知道每道菜叫什么、适合什么场景，下单时喊一句“做那道红烧肉”，身后的助手就会去仓库取对应菜谱并按步骤执行。Agent Skills就是这套“菜谱仓库+助手取菜”机制。2.2 为什么“不进上下文”反而是性能关键这是我最想强调的一点：省上下文不只是为了省钱，更是为了稳定性。我实测过，如果把27个脚本的完整说明都塞进系统提示词，Agent在做文档扫描任务时会出现三个明显问题：一是响应速度变慢，每次请求都会把这些工具定义重新编码一遍；二是工具选择准确率下降，脚本多了之后模型容易选错，比如把“内容质量扫描”当成“敏感信息扫描”；三是上下文可用空间被压缩，真正需要的用户指令、文件摘要、扫描结果反而放不下。把脚本本体移出上下文后，每个技能在上下文里只占一行描述加上参数定义，大概几十个token。27个技能总共不到一千token，对当前模型来说几乎可以忽略。扫描执行时，真正跑的是外部进程，不占用模型推理资源。整个过程中的思维链更清晰，Agent也不会因为工具列表太杂而“选择困难”。2.3 一句话触发的核心：技能名加自然语言参数映射“一句话触发”并不是搞什么神奇魔法，本质上是Agent意图识别加参数提取。用户说“扫描一下这批PDF”，Agent识别出意图是执行document_scanner技能，然后从自然语言里提取出路径参数/data/uploads，文件类型参数pdf。这里需要明确一点：参数的准确度取决于技能描述写得好不好。我一开始把描述写得很宽泛：“对文档执行扫描并返回问题列表”。结果Agent老是漏传strict等关键参数。后来我把描述改成：“对指定路径下的文档执行入库前质量扫描，支持PDF/Markdown/纯文本，返回问题列表、严重级别和建议操作。当用户提到‘严格模式’时，将strict设置为true。”改完之后，参数正确率明显上升。技能名本身是触发点，描述和参数定义才是触发质量的核心。3. 27个扫描脚本的完整规划与拆解3.1 第一梯队：格式与编码扫描格式与编码问题是最容易被忽略却又最致命的。特别是从老旧系统导出的PDF或TXT，经常会出现整个文档是乱码、一段文字里夹杂着大量控制字符、或者明明是中文内容却用错误编码打开后变成“锟斤拷”一类的内容。我常用的第一个脚本是乱码检测脚本。原理不复杂：先尝试用UTF-8、GB18030等编码解码，再统计解码后文本中替换字符（�）的占比，超过阈值就判定为乱码。再配合“可打印字符比例”和“常见中文字符覆盖率”两个辅助指标，基本能覆盖大多数编码场景。import sys def detect_garbled(text: str) -> dict: replacement_count = text.count("\ufffd") printable_ratio = sum(c.isprintable() for c in text) / max(len(text), 1) if replacement_count / max(len(text), 1) > 0.01: return {"error": "garbled", "level": "blocker", "detail": "含有大量替换字符"} if printable_ratio < 0.5: return {"error": "low_printable", "level": "warning", "detail": "可打印字符比例过低"} return {"error": None, "level": "pass", "detail": "ok"}check_truncated_pdf.py则负责检查PDF页数异常和文件尾部是否残缺。实践中最常见的情况是上传工具断了流，导致PDF在文件中断位置出现不完整的对象结构。这类文件直接解析往往会崩溃，所以要提前拦截。3.2 第二梯队：内容质量与去重内容质量扫描解决的是“文档虽然能打开，但里面根本没有料”的问题。空段落、只有标题没有正文的区块、信息密度过低的页面，都会污染RAG的切片效果。我用一个empty_section_scanner.py，输入Markdown或TXT，输出所有标题下正文字符数小于阈值（比如50字）的区块清单。去重是我重点想聊的地方。直接用MD5只能去掉字节级完全相同的文件，但真实场景里更多是“相近重复”：同一份报告改了几个数字、同一篇文章在不同平台转换导致空白差异。我用SimHash做相似度检测，通过分词、哈希加权、降维得到64位指纹，再计算两篇文档之间的汉明距离。汉明距离小于3时，就标记为疑似重复。def simhash(text: str) -> int: tokens = text.split() v = [0] * 64 for token in tokens: h = hash(token) for i in range(64): if h & (1 << i): v[i] += 1 else: v[i] -= 1 fingerprint = 0 for i in range(64): if v[i] >= 0: fingerprint |= (1 << i) return fingerprint这里有个实际心得：不要只看全文档相似度，最好把文档按章节切块后分别计算，因为长文档里可能只有一段是重复内容，全局SimHash值反而不敏感。3.3 第三梯队：敏感信息与合规红线对于对外知识库来说，敏感信息扫描是刚需。我的pii_regex_scanner.py维护了一套正则库，覆盖中国大陆手机号、身份证号、银行卡号、常见邮箱、IPv4地址，以及几类内部工件编号。正则匹配只是第一步，难点在误报处理。我踩过一次坑：把“身份证号正则”写得比较宽松，结果把文档里的条形码数字串全匹配出来了。后来我加了校验位校验，身份证号必须通过GB 11643-1999的校验规则才标记，手机号必须匹配前三位号段为常见运营商号段。全量正则有几十条，但每个脚本只负责一个类型，方便单独调整。密钥检测我用的是secret_key_detector.py，重点不是找形如“sk-”开头的字符串，而是找高熵字符串：长度在20位以上、字符集包含大小写字母和数字、并且连续出现多个疑似密钥上下文关键词。没有上下文提示的随机字符串，就算匹配到了也不敢标记为密钥，否则误报会多到没法看。3.4 第四梯队：结构解析与元数据补全这一类脚本不直接“拦截”文档，而是为后续切片做准备。markdown_link_checker.py检查所有图片引用链接是否指向存在的相对路径，避免入库后前端渲染满屏裂图；lang_detector.py判断文档主语言，方便向量化时选择合适的分词和Embedding模型；metadata_completer.py检查文档是否包含标题、创建日期、作者、来源URL等元数据，缺失的话打上missing_metadata标签。结构扫描最容易被省略，但我觉得恰恰不能省。RAG的切块逻辑依赖标题层级，如果一个文档的标题全是#一级大标题，没有二级三级，切片出来的块会非常粗。markdown_heading_tree.py会把标题树打印出来，超过N层断层就提示“结构扁平，建议重新组织”。3.5 组合编排：如何保证27个脚本不乱跑27个脚本如果让Agent在每份文档上把全部跑一遍，不仅慢，而且没必要。我的做法是给每个脚本定义一个“适用文档类型”和“触发条件”，在编排层用一个Pipeline来管理依赖关系：格式类脚本永远最先跑，因为如果格式都错了，后面内容质量类脚本拿到的文本本身就是废的；安全合规类脚本在文本清洗后、但在写入向量库前跑；结构解析类脚本和内容质量类可以并行。配置片段我放在一个YAML文件里，看起来大概是这样的：pipeline: - stage: format scripts: - detect_garbled_text - check_truncated_pdf - stage: content scripts: - empty_section_scanner - simhash_duplicate - stage: security scripts: - pii_regex_scanner - secret_key_detectorAgent拿到一批文件后，先读配置，按阶段调度。不需要我手动写“先跑这个再跑那个”的指令，自然语言一句话就能让Agent遵循这个编排。4. 实操：从零搭建一个可用的文档扫描Agent Skill4.1 第一步：定义技能清单与Manifest我现在使用的框架支持自定义Skill，一个技能对应一个Manifest文件。Manifest本质上是一个JSON文档，包含技能名、描述、参数定义和调用入口。下面是我给扫描技能写的精简版：{ "name": "document_scanner", "description": "对指定路径下的文档执行入库前质量扫描，支持PDF/Markdown/纯文本，返回问题列表、严重级别和建议操作。当用户提到严格模式时，将strict设置为true。", "parameters": { "path": {"type": "string", "description": "待扫描文件或目录的绝对路径"}, "file_type": {"type": "string", "enum": ["pdf", "markdown", "text"]}, "strict": {"type": "boolean", "description": "是否启用严格模式，会拦截更多低严重级别问题"} } }Manifest里的描述千万不能写得太“文学”。我最初写过“对文档进行健康检查并报告潜在问题”，Agent根本猜不到要传什么参数。后来改成包含文件类型、返回内容、参数含义的描述之后，调用成功率提升了一大截。4.2 第二步：把扫描逻辑封装成可独立运行的脚本每个脚本要保持统一入口：入参可以是路径和参数，出参必须是标准JSON。这样Agent拿到结果后直接解析，不用关心每个脚本的不同返回值。我推荐脚本内部不直接操作Agent运行时，而是通过标准输入输出通信。下面是一个典型脚本骨架：import argparse, json def scan_file(file_path: str, strict: bool) -> dict: # 实际扫描逻辑 return {"file": file_path, "issues": []} if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--path", required=True) parser.add_argument("--strict", action="store_true") args = parser.parse_args() result = scan_file(args.path, args.strict) print(json.dumps(result, ensure_ascii=False))统一输出格式时，我约定每个issues元素至少包含error类型、level（blocker/warning/pass）、detail描述、suggestion建议。后续所有脚本都遵守这个约定，Agent才能把多个脚本的结果汇总成一份连贯报告。4.3 第三步：注册技能并设置参数约束在框架的Agent配置里，把document_scanner注册为可用技能，指向Manifest文件。同时还可以注册辅助技能：report_generator用于生成扫描汇总报告，file_fetcher用于从上传队列拉取文件。参数约束用JSON Schema实现。我特意在file_type里加了enum约束，避免Agent传入“docx”这种没有定义的类型。加约束之后，即使模型幻觉把参数传错，框架也会在校验阶段直接拦截，而不是把错误参数传给脚本导致“文件不存在”。4.4 第四步：一句话触发全流程一切就绪后，我测试时输入这样一句话：“请扫描 /data/incoming 下的新文件，先跑格式和敏感信息扫描，质量扫描用严格模式，最后输出一份汇总报告。”Agent的实际处理链路大概是这样的：理解意图：用户要执行文档扫描，且指定了多个阶段；调用document_scanner，参数path="/data/incoming"，strict=true；框架按Pipeline配置，先运行格式类脚本，再运行安全类脚本，最后运行内容质量类脚本；每个脚本实例都是独立进程，逐份文件处理并返回JSON；调用report_generator，把所有问题按严重程度汇总成Markdown表格。最终我看到的模拟输出长这样：扫描报告（共扫描 34 个文件） - blocker: 3 个文件存在乱码，已阻止入库 - warning: 5 个文件疑似重复，建议合并 - warning: 1 个文件包含疑似API密钥，需人工确认 通过 25 个文件，已进入向量化队列从输入一句话到拿到报告，整个过程用户可以完全不感知中间跑了多少个脚本。4.5 第五步：把扫描结果接入RAG入库管道扫描结果不能只是“看一眼”，它必须成为入库流水线里的一个硬门禁。我写了一个guardian模块，读取扫描结果后做三个动作：blocker级别问题：直接拒绝入库，文件被移动到/quarantine目录；warning级别问题：允许入库，但把警告信息写入文档元数据，检索时可以做降权或提示；全部通过：文件进入下一阶段切块和向量化。有了这个硬门禁之后，我再也不用担心脏文件“漏”进库里。而且每条入库记录都有对应的扫描报告链接，出问题时可以直接追溯。5. 实战中踩过的坑与排查清单5.1 技能串行执行，扫描一批文件要半小时我第一次跑批量扫描时，27个脚本是Agent挨个调用的，每个脚本都要等待前一个的结果，整个目录跑下来花了半个多小时。后来我在编排层做了三个优化：把不依赖彼此的脚本分组放到同一阶段并行执行；单个脚本内部按文件数做多进程并发；对于超时超过120秒的脚本，直接标记为失败并继续执行后续脚本，避免单点卡死。优化后同样的一批文件，扫描时间从半小时降到了三四分钟。“并行编排”不是把27个脚本一起扔出去，而是根据依赖关系控制并发度。5.2 Agent把“严格模式”参数理解错了有一次我在工人那边明确说“严格模式”，结果Agent返回的strict字段是false，导致一批低级别重复根本没被拦截。排查后发现是Manifest描述里缺少“当用户提到严格模式时设置为true”这句话。模型不会猜你到底想要什么，它只会依据描述来推断。解决方式有两个：一是在描述里显式写出触发词；二是在参数Schema里加默认值提示。我把strict参数的描述改成“默认false，当用户要求严格/从严/加大拦截时设置为true”，之后这类错误基本消失。5.3 脚本拿到的文件路径始终报“文件不存在”Agent在执行环境里的当前工作目录可能和脚本预期不一致，尤其是通过调度器运行时，相对路径会直接失效。我后来在全局配置里统一约定：所有传入路径必须是/data/raw前缀的绝对路径，脚本内部再做一层os.path.abspath规范化。还要注意一个问题：如果Agent运行在容器或沙箱里，宿主机路径和容器路径往往不一样。我踩过之后，就在调度层加了一个路径映射函数，把用户可见路径转换成容器内实际路径，然后传给脚本。5.4 正则误杀严重：身份证校验被短信验证码误匹配我用单纯正则匹配手机号和身份证号时，出现过大量误报。尤其是文档里如果包含“验证码为123456789012345678”这类演示数据，就会被当成身份证号。后来我给敏感信息脚本加了三层判定：第一层正则粗筛，第二层校验位算法验证，第三层上下文关键词判断。只有连续通过至少两层的候选字段才标记为“疑似敏感信息”。并且给每个命中结果附上匹配位置和前后文本片段，方便人工复核。5.5 怎么确认扫描结果真的可靠直接上线风险不小。我准备了一套“黄金文档集”，包含20份故意注入各种问题的测试文档，以及10份干净文档。每次调整脚本或修改正则后，都跑一遍黄金集，看各类脚本的精确率和召回率有没有下降。如果某个脚本的精确率低于95%，我就调高判定阈值或增加上下文判断。这个方法帮我发现了不少“脚本自己写high了”的情况：比如空段落扫描器把只包含换行符的文件全部标记为严重，后来我加入“正文有效字符”逻辑，才把误报压下来。6. 一点个人体会在做这套文档扫描Agent技能的过程中，我最直观的感受是：Agent开发的重心正在从“写提示词”转向“设计能力边界”。27个脚本各司其职，Agent的角色更像是调度员和翻译官，而不是执行者。你要做的不是把所有规则塞给模型，而是把规则封装成模型可以随时调用的外部能力，同时把调用方式设计得足够明确。如果让我给后来者一个建议，我会说：不要一上来就追求27个脚本，先搭好5个核心扫描技能跑通流程，再根据实际文档暴露的问题持续补脚本。“27”不是目标，是积累的结果。技能描述一定要写到自己愿意读三遍的程度，因为模型能清晰理解技能的前提，是你自己先把这个技能想清楚。这套东西后续还能扩展：把扫描结果反馈给生成模型，让它自动修复一些简单问题；或者把不同团队的扫描规则做成可共享的技能市场，避免重复开发。项目迭代一段时间后，你会发现真正有价值的不只是扫描能力本身，而是围绕文档质量建立起来的这套可插拔、可演进的管理机制。
看到这个标题，可能不少正在做RAG（检索增强生成）的同学都会愣一下：27个脚本，还“不进上下文”，一句话就能触发文档扫描？我刚开始接触这个玩法的时候也觉得玄乎，但把我手头那个知识库项目里堆积的入库前扫描需求一个个列出来之后，我反而觉得“27个”这个数字太真实了。真到了RAG入库这个环节，你会发现自己面对的不是“需不需要扫描”的问题，而是“怎么让扫描在Agent的上下文里塞得下、跑得动、还能说得清”。这篇文章不聊理论，就是把我自己实际搭建“文档扫描Agent技能”的经验拆开讲清楚。内容包括：为什么入库前扫描非做不可，Agent Skills到底是怎么省上下文的，27个脚本怎么拆怎么编排，以及我从零搭起这个扫描技能时踩过的一堆坑。如果你正在做RAG数据治理、文档清洗、或者想把一批脚本变成Agent可调用的能力，这篇文章应该能给你省掉不少弯路。1. 先搞明白：入库前扫描到底在防什么1.1 RAG的“垃圾进垃圾出”魔咒RAG的检索质量，很大程度上取决于你喂进向量库的“原料”干不干净。我见过很多项目，线上问答答得离谱，查到最后根本不是模型的问题，而是源文档本身就是一堆“地雷”：PDF解析出来是一整页乱码、扫描件OCR识别出了错别字、正文里混着身份证号、同一篇文章被上传了十几个重复版本、Markdown标题层级乱七八糟导致切片逻辑直接崩溃。这些脏数据一旦进了向量库，就会被切块、向量化、编入索引。等用户提问时，检索结果把这些坏块返回给模型，模型再聪明也只能基于坏内容一本正经地胡说八道。而且入库之后你再想去修，得把索引里的对应块找出来删除、重新切分、重新向量化，成本和风险比入库前做一次扫描高得多。所以我一直坚持：入库前加一道“文档扫描”做质量闸门，能拦截的错误绝不拖到检索阶段。这道闸门要看的不是单一指标，而是格式、编码、内容质量、敏感信息、结构完整性等多个维度。它不像是跑一个“能跑就行”的脚本，更像是给文档做一次全面体检。1.2 27个脚本背后的分类逻辑刚开始我以为把几个检查规则写进一个大脚本就完事了。后来发现，不同来源的文档出问题的模式完全不同：从某系统导出的PDF经常是编码错乱，从网页抓下来的Markdown经常是空段落和重复标题，而扫描件则要面对OCR置信度和敏感信息泄漏问题。于是我把扫描需求拆成了四类，一共积累了27个独立脚本：类别扫描重点代表性脚本脚本数量格式与编码乱码检测、编码识别、空白页、截断文件detect_garbled_text.py、check_truncated_pdf.py8内容质量空段落、低信息密度、相似重复、标题层级异常simhash_duplicate.py、empty_section_scanner.py9安全合规手机号、身份证、银行卡、API密钥、内部标记pii_regex_scanner.py、secret_key_detector.py6结构解析图片引用断裂、语言检测、元数据完整性markdown_link_checker.py、lang_detector.py4为什么拆这么细？因为每个脚本都是独立单元，可以单独调试、单独更新，某类规则误报了不会影响其他检查；更重要的是，Agent 在调用时可以根据文档类型“按需组合”，而不是每次把所有规则都跑一遍。比如内部技术文档可以跳过敏感信息扫描（或只跑API密钥检测），而对外资料则必须全量过合规检查。1.3 为什么必须赶在“入库前”很多人会问：能不能等检索结果有问题再修复？我的回答是：等出了问题再去定位，根本不知道是哪个源文档哪一段造成的。向量检索是相关性匹配，不是你改了源文件索引就会自动更新的。如果脏数据早就进了库，你会面临“检索命中了一堆坏块，但用户的问题本身没有问题”的尴尬局面。把扫描前置到入库前，核心好处有三点：第一，污染面可控，坏文档压根没机会进入索引；第二，修复成本低，重新处理原始文件比清理向量库便宜太多；第三，审计上有据可查，每次入库都有一条“扫描报告”，哪些文件通过、哪些被拦截、拦截原因是什么，清清楚楚。这也是我后来坚持做扫描报告归档的原因。2. Agent Skills：让27个脚本待在工具箱里，而不是口袋里2.1 先理解Agent Skills和普通脚本调用的区别常见的Agent工具调用方式，是把一堆函数直接注册成可调用接口。你当然可以把27个脚本封装成27个函数，然后告诉Agent“你有这么多工具可以用”。但问题来了：这些函数的描述、参数说明、使用示例都要写进系统提示词里（也就是上下文里）。一个精确定义的函数描述动辄一两百个token，27个下来就是几千token，而且Agent在理解一大批工具时，很容易在选择上“犯迷糊”。Agent Skills更像是一种“可被按需加载的技能包”。它的核心不是把脚本内容塞给Agent，而是只给Agent一份精简的技能清单。清单里包含技能名称、一句话说明、参数Schema。Agent看到用户需求后，根据技能描述判断该调用哪个技能，然后框架从外部加载真正的脚本并执行。脚本代码、依赖逻辑都在Agent上下文之外，跑完之后只把结果摘要回传。我用一个比喻来理解这件事：你是一个主厨，掌握27道菜的做法，但你不能把这27道菜谱全背在身上；你只需要知道每道菜叫什么、适合什么场景，下单时喊一句“做那道红烧肉”，身后的助手就会去仓库取对应菜谱并按步骤执行。Agent Skills就是这套“菜谱仓库+助手取菜”机制。2.2 为什么“不进上下文”反而是性能关键这是我最想强调的一点：省上下文不只是为了省钱，更是为了稳定性。我实测过，如果把27个脚本的完整说明都塞进系统提示词，Agent在做文档扫描任务时会出现三个明显问题：一是响应速度变慢，每次请求都会把这些工具定义重新编码一遍；二是工具选择准确率下降，脚本多了之后模型容易选错，比如把“内容质量扫描”当成“敏感信息扫描”；三是上下文可用空间被压缩，真正需要的用户指令、文件摘要、扫描结果反而放不下。把脚本本体移出上下文后，每个技能在上下文里只占一行描述加上参数定义，大概几十个token。27个技能总共不到一千token，对当前模型来说几乎可以忽略。扫描执行时，真正跑的是外部进程，不占用模型推理资源。整个过程中的思维链更清晰，Agent也不会因为工具列表太杂而“选择困难”。2.3 一句话触发的核心：技能名加自然语言参数映射“一句话触发”并不是搞什么神奇魔法，本质上是Agent意图识别加参数提取。用户说“扫描一下这批PDF”，Agent识别出意图是执行document_scanner技能，然后从自然语言里提取出路径参数/data/uploads，文件类型参数pdf。这里需要明确一点：参数的准确度取决于技能描述写得好不好。我一开始把描述写得很宽泛：“对文档执行扫描并返回问题列表”。结果Agent老是漏传strict等关键参数。后来我把描述改成：“对指定路径下的文档执行入库前质量扫描，支持PDF/Markdown/纯文本，返回问题列表、严重级别和建议操作。当用户提到‘严格模式’时，将strict设置为true。”改完之后，参数正确率明显上升。技能名本身是触发点，描述和参数定义才是触发质量的核心。3. 27个扫描脚本的完整规划与拆解3.1 第一梯队：格式与编码扫描格式与编码问题是最容易被忽略却又最致命的。特别是从老旧系统导出的PDF或TXT，经常会出现整个文档是乱码、一段文字里夹杂着大量控制字符、或者明明是中文内容却用错误编码打开后变成“锟斤拷”一类的内容。我常用的第一个脚本是乱码检测脚本。原理不复杂：先尝试用UTF-8、GB18030等编码解码，再统计解码后文本中替换字符（�）的占比，超过阈值就判定为乱码。再配合“可打印字符比例”和“常见中文字符覆盖率”两个辅助指标，基本能覆盖大多数编码场景。import sys def detect_garbled(text: str) -> dict: replacement_count = text.count("\ufffd") printable_ratio = sum(c.isprintable() for c in text) / max(len(text), 1) if replacement_count / max(len(text), 1) > 0.01: return {"error": "garbled", "level": "blocker", "detail": "含有大量替换字符"} if printable_ratio < 0.5: return {"error": "low_printable", "level": "warning", "detail": "可打印字符比例过低"} return {"error": None, "level": "pass", "detail": "ok"}check_truncated_pdf.py则负责检查PDF页数异常和文件尾部是否残缺。实践中最常见的情况是上传工具断了流，导致PDF在文件中断位置出现不完整的对象结构。这类文件直接解析往往会崩溃，所以要提前拦截。3.2 第二梯队：内容质量与去重内容质量扫描解决的是“文档虽然能打开，但里面根本没有料”的问题。空段落、只有标题没有正文的区块、信息密度过低的页面，都会污染RAG的切片效果。我用一个empty_section_scanner.py，输入Markdown或TXT，输出所有标题下正文字符数小于阈值（比如50字）的区块清单。去重是我重点想聊的地方。直接用MD5只能去掉字节级完全相同的文件，但真实场景里更多是“相近重复”：同一份报告改了几个数字、同一篇文章在不同平台转换导致空白差异。我用SimHash做相似度检测，通过分词、哈希加权、降维得到64位指纹，再计算两篇文档之间的汉明距离。汉明距离小于3时，就标记为疑似重复。def simhash(text: str) -> int: tokens = text.split() v = [0] * 64 for token in tokens: h = hash(token) for i in range(64): if h & (1 << i): v[i] += 1 else: v[i] -= 1 fingerprint = 0 for i in range(64): if v[i] >= 0: fingerprint |= (1 << i) return fingerprint这里有个实际心得：不要只看全文档相似度，最好把文档按章节切块后分别计算，因为长文档里可能只有一段是重复内容，全局SimHash值反而不敏感。3.3 第三梯队：敏感信息与合规红线对于对外知识库来说，敏感信息扫描是刚需。我的pii_regex_scanner.py维护了一套正则库，覆盖中国大陆手机号、身份证号、银行卡号、常见邮箱、IPv4地址，以及几类内部工件编号。正则匹配只是第一步，难点在误报处理。我踩过一次坑：把“身份证号正则”写得比较宽松，结果把文档里的条形码数字串全匹配出来了。后来我加了校验位校验，身份证号必须通过GB 11643-1999的校验规则才标记，手机号必须匹配前三位号段为常见运营商号段。全量正则有几十条，但每个脚本只负责一个类型，方便单独调整。密钥检测我用的是secret_key_detector.py，重点不是找形如“sk-”开头的字符串，而是找高熵字符串：长度在20位以上、字符集包含大小写字母和数字、并且连续出现多个疑似密钥上下文关键词。没有上下文提示的随机字符串，就算匹配到了也不敢标记为密钥，否则误报会多到没法看。3.4 第四梯队：结构解析与元数据补全这一类脚本不直接“拦截”文档，而是为后续切片做准备。markdown_link_checker.py检查所有图片引用链接是否指向存在的相对路径，避免入库后前端渲染满屏裂图；lang_detector.py判断文档主语言，方便向量化时选择合适的分词和Embedding模型；metadata_completer.py检查文档是否包含标题、创建日期、作者、来源URL等元数据，缺失的话打上missing_metadata标签。结构扫描最容易被省略，但我觉得恰恰不能省。RAG的切块逻辑依赖标题层级，如果一个文档的标题全是#一级大标题，没有二级三级，切片出来的块会非常粗。markdown_heading_tree.py会把标题树打印出来，超过N层断层就提示“结构扁平，建议重新组织”。3.5 组合编排：如何保证27个脚本不乱跑27个脚本如果让Agent在每份文档上把全部跑一遍，不仅慢，而且没必要。我的做法是给每个脚本定义一个“适用文档类型”和“触发条件”，在编排层用一个Pipeline来管理依赖关系：格式类脚本永远最先跑，因为如果格式都错了，后面内容质量类脚本拿到的文本本身就是废的；安全合规类脚本在文本清洗后、但在写入向量库前跑；结构解析类脚本和内容质量类可以并行。配置片段我放在一个YAML文件里，看起来大概是这样的：pipeline: - stage: format scripts: - detect_garbled_text - check_truncated_pdf - stage: content scripts: - empty_section_scanner - simhash_duplicate - stage: security scripts: - pii_regex_scanner - secret_key_detectorAgent拿到一批文件后，先读配置，按阶段调度。不需要我手动写“先跑这个再跑那个”的指令，自然语言一句话就能让Agent遵循这个编排。4. 实操：从零搭建一个可用的文档扫描Agent Skill4.1 第一步：定义技能清单与Manifest我现在使用的框架支持自定义Skill，一个技能对应一个Manifest文件。Manifest本质上是一个JSON文档，包含技能名、描述、参数定义和调用入口。下面是我给扫描技能写的精简版：{ "name": "document_scanner", "description": "对指定路径下的文档执行入库前质量扫描，支持PDF/Markdown/纯文本，返回问题列表、严重级别和建议操作。当用户提到严格模式时，将strict设置为true。", "parameters": { "path": {"type": "string", "description": "待扫描文件或目录的绝对路径"}, "file_type": {"type": "string", "enum": ["pdf", "markdown", "text"]}, "strict": {"type": "boolean", "description": "是否启用严格模式，会拦截更多低严重级别问题"} } }Manifest里的描述千万不能写得太“文学”。我最初写过“对文档进行健康检查并报告潜在问题”，Agent根本猜不到要传什么参数。后来改成包含文件类型、返回内容、参数含义的描述之后，调用成功率提升了一大截。4.2 第二步：把扫描逻辑封装成可独立运行的脚本每个脚本要保持统一入口：入参可以是路径和参数，出参必须是标准JSON。这样Agent拿到结果后直接解析，不用关心每个脚本的不同返回值。我推荐脚本内部不直接操作Agent运行时，而是通过标准输入输出通信。下面是一个典型脚本骨架：import argparse, json def scan_file(file_path: str, strict: bool) -> dict: # 实际扫描逻辑 return {"file": file_path, "issues": []} if __name__ == "__main__": parser = argparse.ArgumentParser() parser.add_argument("--path", required=True) parser.add_argument("--strict", action="store_true") args = parser.parse_args() result = scan_file(args.path, args.strict) print(json.dumps(result, ensure_ascii=False))统一输出格式时，我约定每个issues元素至少包含error类型、level（blocker/warning/pass）、detail描述、suggestion建议。后续所有脚本都遵守这个约定，Agent才能把多个脚本的结果汇总成一份连贯报告。4.3 第三步：注册技能并设置参数约束在框架的Agent配置里，把document_scanner注册为可用技能，指向Manifest文件。同时还可以注册辅助技能：report_generator用于生成扫描汇总报告，file_fetcher用于从上传队列拉取文件。参数约束用JSON Schema实现。我特意在file_type里加了enum约束，避免Agent传入“docx”这种没有定义的类型。加约束之后，即使模型幻觉把参数传错，框架也会在校验阶段直接拦截，而不是把错误参数传给脚本导致“文件不存在”。4.4 第四步：一句话触发全流程一切就绪后，我测试时输入这样一句话：“请扫描 /data/incoming 下的新文件，先跑格式和敏感信息扫描，质量扫描用严格模式，最后输出一份汇总报告。”Agent的实际处理链路大概是这样的：理解意图：用户要执行文档扫描，且指定了多个阶段；调用document_scanner，参数path="/data/incoming"，strict=true；框架按Pipeline配置，先运行格式类脚本，再运行安全类脚本，最后运行内容质量类脚本；每个脚本实例都是独立进程，逐份文件处理并返回JSON；调用report_generator，把所有问题按严重程度汇总成Markdown表格。最终我看到的模拟输出长这样：扫描报告（共扫描 34 个文件） - blocker: 3 个文件存在乱码，已阻止入库 - warning: 5 个文件疑似重复，建议合并 - warning: 1 个文件包含疑似API密钥，需人工确认 通过 25 个文件，已进入向量化队列从输入一句话到拿到报告，整个过程用户可以完全不感知中间跑了多少个脚本。4.5 第五步：把扫描结果接入RAG入库管道扫描结果不能只是“看一眼”，它必须成为入库流水线里的一个硬门禁。我写了一个guardian模块，读取扫描结果后做三个动作：blocker级别问题：直接拒绝入库，文件被移动到/quarantine目录；warning级别问题：允许入库，但把警告信息写入文档元数据，检索时可以做降权或提示；全部通过：文件进入下一阶段切块和向量化。有了这个硬门禁之后，我再也不用担心脏文件“漏”进库里。而且每条入库记录都有对应的扫描报告链接，出问题时可以直接追溯。5. 实战中踩过的坑与排查清单5.1 技能串行执行，扫描一批文件要半小时我第一次跑批量扫描时，27个脚本是Agent挨个调用的，每个脚本都要等待前一个的结果，整个目录跑下来花了半个多小时。后来我在编排层做了三个优化：把不依赖彼此的脚本分组放到同一阶段并行执行；单个脚本内部按文件数做多进程并发；对于超时超过120秒的脚本，直接标记为失败并继续执行后续脚本，避免单点卡死。优化后同样的一批文件，扫描时间从半小时降到了三四分钟。“并行编排”不是把27个脚本一起扔出去，而是根据依赖关系控制并发度。5.2 Agent把“严格模式”参数理解错了有一次我在工人那边明确说“严格模式”，结果Agent返回的strict字段是false，导致一批低级别重复根本没被拦截。排查后发现是Manifest描述里缺少“当用户提到严格模式时设置为true”这句话。模型不会猜你到底想要什么，它只会依据描述来推断。解决方式有两个：一是在描述里显式写出触发词；二是在参数Schema里加默认值提示。我把strict参数的描述改成“默认false，当用户要求严格/从严/加大拦截时设置为true”，之后这类错误基本消失。5.3 脚本拿到的文件路径始终报“文件不存在”Agent在执行环境里的当前工作目录可能和脚本预期不一致，尤其是通过调度器运行时，相对路径会直接失效。我后来在全局配置里统一约定：所有传入路径必须是/data/raw前缀的绝对路径，脚本内部再做一层os.path.abspath规范化。还要注意一个问题：如果Agent运行在容器或沙箱里，宿主机路径和容器路径往往不一样。我踩过之后，就在调度层加了一个路径映射函数，把用户可见路径转换成容器内实际路径，然后传给脚本。5.4 正则误杀严重：身份证校验被短信验证码误匹配我用单纯正则匹配手机号和身份证号时，出现过大量误报。尤其是文档里如果包含“验证码为123456789012345678”这类演示数据，就会被当成身份证号。后来我给敏感信息脚本加了三层判定：第一层正则粗筛，第二层校验位算法验证，第三层上下文关键词判断。只有连续通过至少两层的候选字段才标记为“疑似敏感信息”。并且给每个命中结果附上匹配位置和前后文本片段，方便人工复核。5.5 怎么确认扫描结果真的可靠直接上线风险不小。我准备了一套“黄金文档集”，包含20份故意注入各种问题的测试文档，以及10份干净文档。每次调整脚本或修改正则后，都跑一遍黄金集，看各类脚本的精确率和召回率有没有下降。如果某个脚本的精确率低于95%，我就调高判定阈值或增加上下文判断。这个方法帮我发现了不少“脚本自己写high了”的情况：比如空段落扫描器把只包含换行符的文件全部标记为严重，后来我加入“正文有效字符”逻辑，才把误报压下来。6. 一点个人体会在做这套文档扫描Agent技能的过程中，我最直观的感受是：Agent开发的重心正在从“写提示词”转向“设计能力边界”。27个脚本各司其职，Agent的角色更像是调度员和翻译官，而不是执行者。你要做的不是把所有规则塞给模型，而是把规则封装成模型可以随时调用的外部能力，同时把调用方式设计得足够明确。如果让我给后来者一个建议，我会说：不要一上来就追求27个脚本，先搭好5个核心扫描技能跑通流程，再根据实际文档暴露的问题持续补脚本。“27”不是目标，是积累的结果。技能描述一定要写到自己愿意读三遍的程度，因为模型能清晰理解技能的前提，是你自己先把这个技能想清楚。这套东西后续还能扩展：把扫描结果反馈给生成模型，让它自动修复一些简单问题；或者把不同团队的扫描规则做成可共享的技能市场，避免重复开发。项目迭代一段时间后，你会发现真正有价值的不只是扫描能力本身，而是围绕文档质量建立起来的这套可插拔、可演进的管理机制。