材料模板说明

这份模板是「我应该准备什么材料」这个问题的最小答案。它提供了一个最简单的 Agent + Tool 示例（ae1_minimal_material.json），你可以直接复制后修改成自己的内容。

1. 这是什么

AI安全评估引擎是一个静态材料初步评估工具。

它评估的是你提供的材料，而不是直接判断你的 AI 系统本身是否安全。

它不会连接你的系统、不会扫描、不会运行任何东西。它只做一件事：读你交给它的文字和配置，找出其中值得关注的安全事实，并告诉你这些事实来自哪一行。

所以，你需要给它的不是「一份安全报告」，而是你系统里本来就存在的配置和说明。

这份模板是最小的一份示例：一个 Agent，带一个工具。把它复制出来，改成你自己的内容，就是一份可以被评估引擎评估的最小材料。

2. 我应该准备什么

准备一份你系统里本来就有的配置或说明文字就行，不需要专门写一份安全报告。

在最小的情况下，一份 JSON 文件里说清楚「有哪些 Agent、每个 Agent 能用哪些工具」，就足够开始。

3. 最少需要填写什么

必须填写

Agent 名称（agent.name）你的 Agent 叫什么。随便起一个能认出来的名字就行。
Tool 名称（agent.tools[].name）这个 Agent 能用哪些工具 / 函数 / 能力。

这两项缺了，评估引擎就没有可以分析的主体。

建议填写

使用的模型（agent.model）例如你用的模型名字。这一项当前不会产生安全规则命中，但它是架构事实，会让评估范围更完整。
Tool 的目标范围（agent.tools[].target_scope）这个工具被允许作用于什么对象 / 范围。例如：只能访问某个知识库、某个域名、某个数据库。
Tool 是否可能产生副作用（agent.tools[].side_effect）这个工具只是"读"，还是可能"改 / 删 / 发"。常见的写法：READ_ONLY（只读）、DESTRUCTIVE（会破坏或删除）。

4. 有更多资料还能提供什么

如果你还有下面这些配置，可以放在同一个 JSON 文件里的顶层：

{
  "agent": { "...": "见上面的模板" },

  "agents": [
    { "name": "另一个 Agent", "tools": [ { "name": "...", "side_effect": "..." } ] }
  ],

  "mcp_servers": [
    { "name": "某个 MCP Server", "trusted": false, "authorization_required": false }
  ],

  "rag": {
    "sources": [
      { "name": "某个知识库", "retrieval_scope": "*" }
    ]
  }
}

agents 是多个 Agent 的列表（每个 Agent 内部结构和 agent 一样）。
mcp_servers 描述你用到的 MCP 服务。MCP（让 AI 连接外部工具或服务的方式）。其中 trusted 表示"是否声明为受信"，authorization_required 表示"是否声明需要鉴权"。
rag.sources 描述你用到的 RAG 数据源。RAG（让 AI 从知识库等资料中检索信息的方式）。其中 retrieval_scope 表示"检索范围"。

不写这些也没关系，评估引擎会把它当作"材料未提供"处理。

5. 哪些东西不要提供

不要在材料里放下面这些信息：

密钥 / API Key
口令 / 密码
生产环境凭据
真实客户数据

这些信息既不需要，也没有必要为了评估而提供。评估引擎只读你文字里描述的结构，不需要这些敏感内容。

6. 字段是什么意思

字段	位置	含义	一句话解释
`name`	`agent.name`	Agent 名称	这是谁
`model`	`agent.model`	使用的模型	它背后是什么模型
`tools`	`agent.tools`	工具清单	它能调用什么
`name`	`agent.tools[].name`	工具名称	这个工具叫什么
`target_scope`	`agent.tools[].target_scope`	目标范围	它能对谁做这件事
`side_effect`	`agent.tools[].side_effect`	副作用类别	它只是看，还是会改

注意：target_scope 和 side_effect 都是"材料里是怎么声明的"，不是评估引擎猜测出来的。评估引擎只会陈述"材料声明了什么"，不会判断"实际有没有发生"。

7. 为什么 `target_scope` 很重要

因为「这个工具能做什么」和「这个工具能对谁做」是两件不同的事。

一个会发 HTTP 请求的工具，听起来只是"发一个请求"。但如果它的目标范围是 "*"（任意目标），它实际可能接触到的外部对象，就比设计时预想的多得多。

所以 target_scope 写具体，是最有价值的一件事：

"target_scope": ["internal-kb"]     ← 清楚：只能访问内部知识库
"target_scope": ["*"]               ← 没有边界：等于没说清只能访问哪里

评估引擎目前有一条规则专门看这件事：target_scope 里出现 * 时，它会记录下来。

8. 为什么 `side_effect` 很重要

因为「查询」和「删除」的安全含义完全不同。

"side_effect": "READ_ONLY" → 只是读取，不会改变系统状态
"side_effect": "DESTRUCTIVE" → 可能删除、覆盖、破坏数据

如果一个 Agent 被授予了会破坏数据的工具，那值得关注的就不是"能不能调用"，而是"这个能力有没有必要给它、调用前后有没有控制"。

评估引擎目前有一条规则专门看这件事：side_effect 为 DESTRUCTIVE 时，它会记录下来。

9. 如果我不知道某个字段应该怎么填

就直接不写。

不要为了"看起来完整"随便填一个值。评估引擎会如实记录"这项信息你没提供"，并且不会替你猜。

也不要写 "unknown" / "n/a" 之类的占位字符串 ——那看起来像是一个"声明的值"，会让评估引擎误以为你真的声明了什么。不写，比写一个假值更诚实、也更有用。

10. 不知道 ≠ 安全

这一条非常重要：

评估引擎不会因为你没有写某一项，就认为那一项是安全的。

报告里会明确区分几种结果：

已评估（evaluated）：你已经提供了信息，评估引擎评估过了
信息不足，无法判断（insufficient_information）：你给的信息不够，评估引擎判断不了
材料中没有提供相关信息（not_provided）：材料里根本没提这件事
当前评估规则不覆盖这一项（unsupported）：当前规则集不覆盖这个主题

这四种状态都不等于「安全」，也不等于「有风险」。

Coverage 表示当前材料和规则能够覆盖到哪些评估主题，并不代表系统的安全程度，也不是安全评分。

11. 缺失信息会带来什么结果

如果你只写了 Agent 和 Tool，没有写 MCP、没有写 RAG，那么：

MCP 和 RAG 这两个主题会显示为 「材料中没有提供相关信息」
如果某个工具缺 target_scope，评估引擎无法判断它的目标范围，会显示 「信息不足，无法判断」

这是正常且正确的结果，不是报错。它的意思是"评估引擎诚实地告诉你它不知道"，而不是"这一项没问题"。

这一点也是评估引擎和普通扫描器最大的区别：它不会因为没看到问题，就说你没问题。

12. 支持哪些文件 / 第一次应该使用什么

可以直接评估

.json

目前 .json 是最适合第一次使用的格式，可以直接识别其中的 Agent、Tool 等结构化安全信息。

可以提交，但信息处理方式有限

.md / .txt

可以读取其中的文字材料，但目前不会像 JSON 一样直接识别出完整的结构化安全对象。

可以接收，但需要转换

.yaml / .yml / .pdf / .docx / 图片等

这些格式可以先提交，但目前不会直接识别为结构化信息，需要经过转换；转换后的结构化内容才能进入完整的结构化评估。

当前无法处理

其他无法识别的格式。

当前无法处理，提交后会被跳过或提示无法识别。

第一次使用，建议直接准备一份 .json 材料。

13. 它不会做什么

这几条是评估引擎的硬边界：

不会执行你上传材料中的代码。材料会被当作内容读取，而不是作为程序运行。不会 import、不会运行、不会因为材料里写了什么就去执行什么。

不会替你猜测。如果材料没有提供某项信息，评估引擎不会自行猜测一个答案。

不会把「没发现」当成「安全」。一份材料没有产生值得关注的安全发现，只能说明当前材料没有命中当前规则，并不代表实际系统一定安全。

不会做完整安全测试。这是基于你提供材料的初步分析，不等同于完整安全测试、安全认证，也不代表对实际运行环境进行了全面验证。

所以你不需要"为了让它能跑"而准备任何可执行的东西。

14. 下一步怎么做

把 ae1_minimal_material.json 复制出来（随便叫什么名字，.json 结尾即可）。
把 my-agent 改成你 Agent 的名字。
把 tools 列表改成你真实的工具清单（可以多个）。
给每个工具尽量写上 target_scope 和 side_effect。
如果你还有 MCP Server 或 RAG 数据源的配置，也一起放进去（见第 4 节）。

这份模板本身（保持原样不动）跑出来的结果会是这样：它会产生 Agent / Tool 对象和对应的证据定位，但因为示例里的目标范围是具体值、副作用是只读，很可能不会产生任何值得关注的安全发现（Finding）。

这不代表你的系统安全，只代表这份示例材料没有命中当前规则。真实材料里如果出现 "*" 或 "DESTRUCTIVE"，就会命中对应规则。