企业官网建设流程全解析

1. 背景与核心概念

1.1 从一次“正常调用”引发的安全思考

在最近的 Agent 项目迭代中，我遇到一个值得警惕的现象：某个业务 Agent 在正常处理用户请求时，意外读取到了一个本应“隐藏”的技能文件，并将其中包含的内部 API 地址、Prompt 模板甚至数据库连接串信息一并带到了日志和会话上下文中。

这个文件不是公开资源，也没有在任何文档里被引用，却在被模型动态加载技能时“顺理成章”地被读取并使用。整个过程没有任何异常告警，代码逻辑看起来也完全正常——因为它走的正是 Agent 本身的技能加载机制。问题不在于机制有漏洞，而在于我们对“技能文件”的安全边界缺少了足够的定义和约束。

这就引出了本文要讨论的主题：隐藏的 Agent 技能文件可被正常使用窃取。

1.2 Agent 技能文件是什么

在 AI Agent 的开发体系中，技能文件（Skill File）指的是为 Agent 提供特定能力描述、Prompt 模板、工具调用说明、示例数据等内容的文件。

从工程实践来看，技能文件通常包括以下几类：

这些文件不直接参与模型推理，但它们决定了模型“如何调用工具”“如何构造 Prompt”“如何处理异常”。正因为如此，技能文件往往包含了比核心代码更敏感的信息——Prompt 设计思路、内部 API 定义、业务规则、甚至未经脱敏的测试配置。

1.3 为什么“隐藏的”技能文件更容易泄露

很多团队在管理技能文件时，采用的是“目录隐藏 + 不引用”策略，也就是：

• 把敏感技能文件放在一个不显眼的目录下；
• 不在 README 或索引文档中直接引用；
• 依赖开发者之间的口头约定来避免误用。

这种做法的假设是：既然没人知道这个文件，自然不会有人去读取它。但在 Agent 的运行机制下，这个假设可能不成立。Agent 在加载技能时存在两种常见方式：

1. 全量索引：Agent 框架会扫描整个技能目录，建立索引，以便在对话中匹配用户意图。
2. 动态检索：模型根据用户输入，通过向量检索或关键词匹配选择技能文件。

也就是说，即使文件路径不公开，只要它位于技能扫描目录内，就可能在“正常使用”的过程中被模型主动选中并加载。对于模型来说，它不知道这个文件“不应该被使用”，它只知道这个文件中的内容与当前任务高度相关。

这就是所谓“正常使用窃取”的根源：不是攻击者绕过了权限，而是系统在设计上就没有划分技能文件的敏感级别。

1.4 哪些场景最容易触发这个问题

从实际项目经验看，以下场景最容易触发技能文件被意外读取：

• 多 Agent 协作场景：主 Agent 在调度 Sub Agent 时，会传递上下文信息，如果某个 Sub Agent 的技能目录包含了其他业务线的敏感文件，就可能发生越权读取。
• 动态技能注册场景：Agent 在运行时动态加载新增技能文件，如果新增文件没有经过安全审查，会直接进入候选池。
• 日志与调试场景：开发者在调试 Agent 调用链时，经常会打印完整上下文，技能文件中的内容会随之写入日志。
• 第三方技能包引入：从网上下载或内部共享的技能包，如果没有校验文件清单，可能包含隐藏的敏感数据。

1.5 本文适合哪些读者

如果你正在做以下工作，本文值得仔细阅读：

• Agent 应用开发工程师，需要设计技能文件的加载与权限机制。
• AI 平台后端开发，负责 Agent 运行环境的文件管理。
• 安全工程师，需要对 Agent 技能文件做安全评估。
• 技术负责人，需要制定 Agent 开发规范。

本文会重点讲解技能文件被“正常使用窃取”的技术原理、典型的泄露路径、防御性检测方法、访问控制设计思路，以及工程上如何建立可落地的技能文件安全机制。

2. 技能文件被“正常使用窃取”的技术原理

2.1 Agent 技能加载机制的链路分析

要理解技能文件如何被“正常使用窃取”，首先得了解 Agent 加载技能文件的完整链路。下面是一个简化的流程：

用户输入 ↓ 意图识别（Intent Recognition） ↓ 技能检索（Skill Retrieval） ↓ 技能文件加载（Skill Loading） ↓ 上下文组装（Context Building） ↓ 模型推理（LLM Inference） ↓ 工具调用（Tool Invocation） ↓ 输出生成（Response Generation）

在这条链路上，技能检索尤为关键。常见的技能检索策略包括：

• 关键词匹配：根据用户输入中的关键词，查找技能目录中的文件名和描述文本。
• 向量相似度检索：将用户输入和技能描述分别向量化，计算相似度，返回 Top-K 结果。
• 语义路由：由一个轻量级模型判断该使用哪个技能，类似于意图分类。

问题在于，这些检索策略都不会主动区分“业务正式技能”和“内部隐藏技能”。只要文件内容与用户输入有足够的匹配度，就会被选中。

2.2 技能文件为什么会被模型“主动”读取

大语言模型在推理时，会根据上下文决定是否调用某个工具或读取某个文件。当技能文件通过检索机制进入上下文后，模型会将其中的内容视作合法信息，并据此决定下一步动作。

举个例子：假设技能目录中有一个文件internal_config.yaml，内容包含了某个内部服务的 API 地址和鉴权方式。用户输入是“帮我查询订单状态”，Agent 的检索模块发现internal_config.yaml中包含了订单服务的 API 路径，于是将该文件内容拼接到上下文中。模型读取后，按照其中的 API 格式发起请求。从代码逻辑看，一切正常；但从安全角度看，这个文件本不应该被任何模型读取。

这里面的核心问题是：技能文件的读取权限和业务权限是分离的。文件系统层面可能设置了 ACL，但 Agent 框架在加载技能时往往是以服务账号身份统一读取，不会逐文件判断是否允许被当前会话的模型引用。

2.3 技能文件中的敏感信息类型

为了后续做好防护，需要先明确技能文件中哪些信息属于敏感信息。

这些信息一旦被模型读取并进入上下文，就可能通过以下路径泄露出去：

1. 模型输出：模型在回答问题时可能直接引用技能文件中的内容。
2. 日志记录：开发框架记录每次调用的请求和响应，包含完整上下文。
3. 外部工具调用：如果技能文件中的 API 地址被模型直接调用，请求会发送到对应服务。
4. 上下文传递：在多 Agent 协作中，主 Agent 可能会把技能内容传递给其他子 Agent。

3. 典型泄露路径与攻击场景分析

3.1 内部开发者的无意识泄露

这是最高频的场景，但往往最容易被忽视。

开发者 A 在调试一个 Agent 技能时，为了快速验证，把包含敏感配置的config.yaml直接放在了技能目录下，并注释掉了其中一些字段。之后，开发者 B 在优化技能检索时，增加了全量索引功能，于是这个文件被索引并进入了候选池。某个用户提问与该文件中的关键字匹配，模型加载了该文件，其中敏感信息随之进入上下文。

整个过程没有任何恶意行为，但泄露已经发生。

3.2 供应链与第三方技能包

现在很多团队会直接从社区或内部共享平台下载技能包。这些技能包大多以目录形式存在，包含技能描述、Prompt 模板、脚本等文件。如果技能包的开发者不小心将.env或包含真实密钥的配置文件打进包中，下载方在加载技能时就会将这些密钥引入自己的环境。

更危险的是，第三方技能包可能主动包含“窃取型”技能文件，即专门用于读取本地其他文件的 Prompt 指令。虽然这属于恶意行为，但对于下载方来说很难在第一时间察觉。

3.3 多 Agent 协作中的上下文传递

多 Agent 协作是当前 Agent 开发的热门方向，主从模式（Supervisor + Sub Agent）下，主 Agent 会将任务拆解并分配给多个子 Agent。如果某个子 Agent 的技能目录中包含敏感文件，该子 Agent 在完成任务时可能会将敏感信息写入中间结果，主 Agent 收集中间结果时会一并将敏感信息整合到最终上下文中。

这种场景的特殊之处在于：即使每个子 Agent 的技能检索都正常，权限控制也都正常，单一环节没有异常，但组合之后仍然会发生敏感信息聚合。

3.4 日志与监控系统的“被动泄露”

在开发调试阶段，工程师往往会在 Agent 调用链路中加入详细日志，包括检索到的技能文件内容、模型接收的完整 Prompt、工具调用的入参和返回结果。这些日志会写入日志平台，而日志平台通常有较宽的访问权限，比如公司内部所有开发人员都能查询。

一旦技能文件内容进入日志，就等于扩大了敏感信息的暴露面。更关键的是，日志通常是永久保留的，这就意味着即使后续删除了技能文件，日志中的敏感内容仍然存在。

3.5 攻击者的主动利用思路

从攻击者视角来看，如果想要窃取某个 Agent 的技能文件，常见的利用路径包括：

1. 社工或供应链投毒：将恶意技能文件投递到目标 Agent 的技能目录中，等待模型自动加载。
2. Prompt 注入：构造特殊用户输入，诱导 Agent 检索并读取特定技能文件，然后让模型将文件内容原样返回。
3. 利用日志泄露：如果目标 Agent 的日志系统配置不当，攻击者可以直接从日志中检索敏感技能内容。
4. API 接口探测：如果 Agent 暴露了技能管理 API，攻击者可以尝试未授权访问或越权遍历。

需要特别说明的是，从防御角度，我们更应关注前两种路径，因为它们在攻击链中的位置最靠前，一旦阻断，后续攻击很难展开。

4. 防御性检测实战：如何发现技能文件风险

下面进入实操环节。在真实项目中，我们可以通过自动化脚本对技能文件目录进行定期扫描，发现其中包含的敏感信息，提前降低泄露风险。

4.1 检测目标

我们需要实现一个简单的技能文件安全扫描器，具备以下能力：

• 递归扫描指定技能目录下的所有文件。
• 识别常见敏感信息模式：API Key、Token、私钥、数据库连接串、内网 IP 等。
• 输出风险文件清单及风险类型。
• 可作为 CI/CD 的一个检查步骤。

4.2 项目结构

skill-scan/ ├── scanner.py ├── rules/ │ └── sensitive_patterns.yaml ├── requirements.txt └── README.md

4.3 敏感信息检测规则

创建一个 YAML 规则文件，用于定义需要检测的敏感信息模式：

# 文件路径：skill-scan/rules/sensitive_patterns.yaml patterns: - name: API Key regex: "sk-[a-zA-Z0-9]{16,}" description: "OpenAI 风格 Key" - name: AWS Access Key regex: "AKIA[0-9A-Z]{16}" description: "AWS 访问密钥" - name: 私钥块 regex: "-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----" description: "PEM 私钥" - name: 数据库连接串 regex: "(jdbc:[a-z]+://|mongodb://|postgresql://|mysql://)" description: "数据库 JDBC 或 URI" - name: 内网 IP regex: "(10\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}|172\\.(1[6-9]|2[0-9]|3[01])\\.\\d{1,3}\\.\\d{1,3}|192\\.168\\.\\d{1,3}\\.\\d{1,3})" description: "RFC1918 内网地址" - name: 密码占位符 regex: "(password|passwd|pwd)\\s*[:=]\\s*[^\\s]{6,}" description: "显式密码赋值"

4.4 扫描器核心代码

# 文件路径：skill-scan/scanner.py import os import re import sys import yaml from pathlib import Path from dataclasses import dataclass, field from typing import List @dataclass class ScanResult: file_path: str line_number: int match_text: str rule_name: str description: str @dataclass class ScanReport: results: List[ScanResult] = field(default_factory=list) @property def has_risk(self) -> bool: return len(self.results) > 0 def print_report(self) -> None: if not self.has_risk: print("[安全] 未发现敏感信息，技能目录检查通过。") return print(f"[风险] 发现 {len(self.results)} 处敏感信息：\n") current_file = None for item in self.results: if item.file_path != current_file: print(f"\n文件: {item.file_path}") current_file = item.file_path print(f" 行 {item.line_number}: [{item.rule_name}] {item.description}") print(f" 匹配内容: {item.match_text[:80]}..." if len(item.match_text) > 80 else f" 匹配内容: {item.match_text}") def load_rules(rules_path: str) -> List[dict]: """加载敏感信息检测规则。""" with open(rules_path, "r", encoding="utf-8") as f: data = yaml.safe_load(f) return data.get("patterns", []) def scan_file(file_path: Path, rules: List[dict], report: ScanReport) -> None: """扫描单个文件，匹配敏感信息规则。""" try: with open(file_path, "r", encoding="utf-8", errors="ignore") as f: for line_no, line in enumerate(f, start=1): for rule in rules: pattern = re.compile(rule["regex"]) match = pattern.search(line) if match: report.results.append(ScanResult( file_path=str(file_path), line_number=line_no, match_text=match.group().strip(), rule_name=rule["name"], description=rule["description"] )) except PermissionError: print(f"[跳过] 无权限读取: {file_path}") def scan_directory(skill_dir: str, rules_path: str) -> ScanReport: """扫描技能目录下所有文件。""" rules = load_rules(rules_path) report = ScanReport() # 排除常见无需检查的目录 exclude_dirs = {"node_modules", ".git", "__pycache__", ".venv", "target", "build"} for root, dirs, files in os.walk(skill_dir): dirs[:] = [d for d in dirs if d not in exclude_dirs] for filename in files: file_path = Path(root) / filename scan_file(file_path, rules, report) return report def main() -> None: if len(sys.argv) != 3: print("用法: python scanner.py <技能目录> <规则文件>") sys.exit(1) skill_dir = sys.argv[1] rules_path = sys.argv[2] if not os.path.isdir(skill_dir): print(f"[错误] 技能目录不存在: {skill_dir}") sys.exit(2) if not os.path.isfile(rules_path): print(f"[错误] 规则文件不存在: {rules_path}") sys.exit(2) report = scan_directory(skill_dir, rules_path) report.print_report() # 在 CI 环境中，发现风险直接以非零退出码结束 if report.has_risk: sys.exit(1) sys.exit(0) if __name__ == "__main__": main()

依赖清单：

# 文件路径：skill-scan/requirements.txt pyyaml>=6.0

4.5 运行与验证

假设我们有如下技能目录结构：

skills/ ├── order_query/ │ ├── SKILL.md │ └── template.j2 ├── payment_callback/ │ ├── SKILL.md │ └── internal_config.yaml # 包含内部 API 地址 └── data_prep/ ├── prompt.md └── sample_db_uri.txt # 包含数据库连接串

执行扫描：

cd skill-scan pip install -r requirements.txt python scanner.py ../skills ./rules/sensitive_patterns.yaml

预期输出：

[风险] 发现 2 处敏感信息： 文件: ../skills/payment_callback/internal_config.yaml 行 5: [内网 IP] RFC1918 内网地址 匹配内容: http://10.0.0.15:8080/api 文件: ../skills/data_prep/sample_db_uri.txt 行 2: [数据库连接串] 数据库 JDBC 或 URI 匹配内容: postgresql://admin:password@db.internal:5432/ops

4.6 在 CI 中加入技能文件扫描

为了让扫描器发挥持续作用，可以将其配置到 GitLab CI 或 GitHub Actions 中。这里给出一个 GitLab CI 的简单示例：

# 文件路径：.gitlab-ci.yml（片段） skill-security-scan: stage: test script: - pip install -r skill-scan/requirements.txt - python skill-scan/scanner.py skills skill-scan/rules/sensitive_patterns.yaml only: changes: - skills/**/*

这样，每次技能目录中的文件发生变更时，都会自动触发敏感信息扫描。一旦发现风险，流水线会失败，开发者需要修复后才能合并。

5. 访问控制与最小权限设计

扫描器解决的是“发现已有风险”的问题，但更关键的是从设计层面避免风险产生。下面从技能文件的全生命周期来讨论访问控制。

5.1 技能文件分级管理

在 Agent 工程中，建议将技能文件划分为三个级别：

在目录结构上，可以这样组织：

skills/ ├── public/ # L1 公开技能 ├── internal/ # L2 内部技能 ├── confidential/ # L3 机密技能 └── .metadata/ └── access_control.yaml

5.2 技能文件注册与访问令牌

为了实现精细化的访问控制，可以为每个技能文件（或技能包）建立注册信息，并与具体的 Agent 授权关联。

# 文件路径：skills/.metadata/access_control.yaml skills: - name: order_query path: internal/order_query level: L2 allowed_agents: - order_agent - support_agent allowed_users: - zhangsan - lisi require_context: true description: "订单查询技能，仅限订单与客服 Agent 使用"

在 Agent 框架加载技能时，通过一个统一的授权中间件进行判断：

# 文件路径：skill_loader.py（核心片段） from dataclasses import dataclass @dataclass class AgentContext: agent_name: str user_id: str session_id: str roles: list[str] class SkillAccessController: """技能访问控制器，负责技能加载前的权限校验。""" def __init__(self, access_config: dict): self.access_config = access_config def check_access(self, skill_name: str, ctx: AgentContext) -> bool: """检查当前 Agent 是否有权加载指定技能。""" skill_info = self._find_skill(skill_name) if skill_info is None: return False # L1 公开技能，默认放行 if skill_info.get("level") == "L1": return True # L3 机密技能，默认拒绝（除非显式授权） if skill_info.get("level") == "L3": return False # L2 内部技能，检查 Agent 白名单 allowed_agents = skill_info.get("allowed_agents", []) if ctx.agent_name not in allowed_agents: return False # 检查用户白名单 allowed_users = skill_info.get("allowed_users", []) if ctx.user_id not in allowed_users: return False return True def _find_skill(self, skill_name: str) -> dict | None: """在访问配置中查找技能信息。""" for item in self.access_config.get("skills", []): if item.get("name") == skill_name: return item return None

这个控制器的关键在于：将技能加载从“目录可用”提升为“显式授权可用”，从源头降低技能文件被正常使用窃取的风险。

5.3 技能文件中的密钥隔离

很多技能文件之所以包含敏感信息，是因为开发者图方便，将密钥直接写死在配置中。实际上，Agent 运行时同样可以支持密钥的间接引用。

# 不推荐：直接在技能文件中写密钥 api_key: sk-1234567890abcdef

# 推荐：使用占位符，由运行环境注入 api_key: ${ORDER_SERVICE_API_KEY}

具体来说，可以在技能加载流程中增加一个“变量替换层”，在技能文件内容进入模型上下文之前，将环境变量占位符替换为实际值。这样技能文件本身不包含敏感信息，即使文件被意外读取，也不会泄露密钥。

# 文件路径：variable_resolver.py（核心片段） import os import re def resolve_env_variables(content: str) -> str: """将技能内容中的 ${ENV_VAR} 占位符替换为环境变量值。 如果环境变量不存在，保留原始占位符，避免直接注入空值。 """ pattern = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}") def replace_match(match): env_key = match.group(1) return os.getenv(env_key, match.group(0)) return pattern.sub(replace_match, content)

6. 常见问题与排查清单

6.1 常见问题对照表

6.2 排查 checklist

当怀疑技能文件被“正常使用窃取”时，可以按以下顺序排查：

1. 确认泄露信息的内容和等级：是密钥、内部地址、还是 Prompt 模板？泄露面有多大？
2. 定位泄露信息所属文件：在技能目录中搜索泄露信息的片段，找到对应文件。
3. 检查技能加载日志：确认该文件是否在某个会话中被检索和加载。
4. 检查会话上下文：查看模型接收的完整 Prompt 中是否包含了该文件内容。
5. 检查日志平台：搜索泄露信息是否已经进入日志系统，评估泄露范围。
6. 检查多 Agent 调用链：如果有多 Agent 协作，需要确认中间结果是否将敏感信息传递到了其他模块。
7. 评估影响：如果泄露了密钥，立即轮换密钥；如果泄露了内部地址，需要确认该地址是否已被外部访问。
8. 修复并防止复发：移动敏感文件、增加访问控制、加入扫描器、更新开发规范。

6.3 典型误判分析

在使用扫描器时，也可能出现误判。例如：

匹配内容: password = "admin123"

这个可能只是代码中的一个测试变量，并非真实密码。处理这类误判时，建议：

• 不立即删除文件，而是先确认上下文。
• 在规则中增加白名单机制，对已知测试文件放行。
• 将疑似敏感字段改为环境变量引用，而不是直接删除。

7. 最佳实践与工程建议

7.1 将技能文件视为代码管理

技能文件是 Agent 行为逻辑的一部分，应当像代码一样管理。具体来说：

• 纳入 Git 版本管理，所有变更可追溯；
• Code Review 时关注技能文件内容，而不只是代码文件；
• 使用分支管理和标签发布的流程来管理技能文件版本。

7.2 建立技能文件安全清单

每个技能文件都应该有一个安全清单，随文件一起维护：

# 安全清单 - [ ] 文件是否包含密钥或 Token？（若是，改为环境变量引用） - [ ] 文件是否包含内网地址？（若是，确认是否需要脱敏） - [ ] 文件中的 Prompt 是否可能诱导模型输出系统提示？（若是，进行 Prompt 安全测试） - [ ] 文件是否被不相关的 Agent 可见？（若是，配置访问白名单） - [ ] 文件变更是否需要安全审查？（若是，加入安全 Review 流程）

7.3 运行时安全边界

在 Agent 运行环境中，建议做到以下几点：

• 最小权限原则：Agent 服务账号只拥有技能目录的最小读权限，而不是整个项目目录的读权限。
• 沙箱隔离：如果技能文件需要执行脚本，应在沙箱中运行，禁止直接访问宿主机文件系统。
• 会话隔离：不同用户会话之间的技能加载上下文需要隔离，避免用户 A 的上下文泄露给用户 B。
• 审计日志：记录技能文件的加载记录，包括文件路径、加载时间、触发会话、调用者等。

7.4 定期安全演练

建议每隔一段时间进行一次技能文件安全演练，模拟以下场景：

• 在技能目录中放入一个“诱饵”文件，验证是否会进入日志；
• 构造一个能触发隐藏技能检索的用户输入，验证是否会被模型读取；
• 模拟第三方技能包投递，验证现有校验机制是否有效。

安全演练不是为了制造恐慌，而是为了确保在真实攻击发生前，防护机制是可用的。

7.5 结合 MCP 场景的延伸思考

在 Agent 开发中，技能文件（Skills）和 MCP（Model Context Protocol）是经常被放在一起讨论的概念。简单来说，技能文件更像是 Agent 内部的静态能力描述，而 MCP 是模型与外部工具之间的一种标准化接口协议。

在实际项目中，技能文件和 MCP 经常会同时出现。开发者可以将技能文件作为“能力定义层”，通过 MCP 协议将能力暴露给不同的 Agent 客户端。需要注意的是，技能文件的访问控制设计不应因为引入了 MCP 而弱化。MCP 解决的是协议标准化问题，并不天然解决授权问题。在使用 MCP 时，同样需要在服务端实现鉴权与访问控制。

8. 从安全视角重新审视 Agent 开发

“隐藏的 Agent 技能文件可被正常使用窃取”这个问题的本质，不是某个框架或某个库的漏洞，而是 Agent 开发中普遍存在的“能力开放”与“安全边界”失衡。

在实际项目中，我们不能假设“文件是隐藏的就安全”，更不能认为“模型不会读不相关的文件”。模型的行为逻辑是概率性的，它的检索和选择机制决定了它会根据内容相关性去读取文件，而不会像人类开发者一样理解“这个文件不应该出现在这里”。

要想从根本上降低风险，建议从三个维度同时发力：

• 工程维度：技能文件分级、访问控制、变量注入、自动扫描。
• 管理维度：技能文件变更审查、安全清单、开发规范。
• 运行维度：加载审计、沙箱隔离、会话隔离、定期演练。

本文提供的扫描器代码、访问控制示例和排查清单，都是可以直接在项目中落地的基础工具。如果你正在搭建 Agent 应用，建议把技能文件的安全管理纳入到第一版设计里，而不是等问题暴露后再补。毕竟，Agent 的能力边界越清晰、技能文件的权限划分越明确，整个系统的稳定性和安全性才会越可靠。