16. 安全体系

Security 描述 FlowNex 在身份、租户、权限、知识、工具、文件和审计方面的安全边界。

企业级 Agent 平台的安全目标不是简单限制模型能力，而是确保 Agent 在正确身份、正确权限、正确上下文和正确审计范围内执行任务。

16.1 身份认证

FlowNex 的所有入口都应绑定可信用户身份。

身份来源可以包括：

  1. Web 登录态。
  2. 企业 SSO。
  3. 飞书 / Lark 用户身份。
  4. 内部业务系统调用身份。
  5. 管理员服务账号。

身份认证后，需要在请求链路中传递：

  1. tenantCode。
  2. userId。
  3. traceId。
  4. 渠道类型。
  5. 必要时传递角色或权限快照。

用户身份不能只停留在网关层。Dubbo、MQ、runtime callback 等内部链路也需要保留足够身份上下文，避免异步处理时丢失审计主体。

16.2 租户隔离

租户隔离是 FlowNex 的基础安全边界。

需要隔离的对象包括：

  1. 用户。
  2. Agent。
  3. Conversation。
  4. Message。
  5. Task。
  6. Skill。
  7. Tool 授权。
  8. Knowledge Asset。
  9. AGFS Space。
  10. 文件对象。
  11. 运行时配置。

所有领域表和查询接口都应显式携带 tenantCode。跨租户查询、更新和运行时能力混用应被禁止。

AGFS 中也不应将租户逻辑硬编码到路径字符串，而应通过 Space、Mount、rootFileId 和权限模型实现隔离。

16.3 用户、角色与权限

权限模型建议采用 RBAC 为主，并在关键资源上叠加资产级授权。

权限范围包括：

  1. 页面访问权限。
  2. 管理操作权限。
  3. Skill 使用权限。
  4. Tool 使用权限。
  5. 知识库访问权限。
  6. AGFS 文件访问权限。
  7. 多 Agent 操作权限。

运行时能力必须从服务端计算，不应相信前端传入的 Skill、Tool 或知识库范围。

用户可见范围应遵守最小权限原则：

  1. 没有安装或授权的 Skill 不进入本轮 skillCodes。
  2. 没有授权的 Tool 不进入本轮 toolCodes。
  3. 没有权限的知识不进入 knowledgeAccess。
  4. 没有权限的文件不允许 AGFS 读取。

16.4 知识库越权防护

知识库越权是 Agent 平台的高风险问题。

防护原则：

  1. 检索前裁剪，而不是检索后过滤。
  2. 运行时只接收可检索资源 ID。
  3. Provider 凭证不下发给 runtime 和模型。
  4. 用户手选知识库仍需本地 ACL 校验。
  5. Skill 绑定知识库不代表用户自动拥有访问权限。
  6. FORBIDDEN 绑定范围必须从本轮检索范围中移除。

错误示例：

先用全租户知识库检索，再把用户无权限结果过滤掉。

正确做法：

先计算用户授权范围，再在授权范围内发起检索。

16.5 Tool 执行安全

Tool 是 Agent 执行动作的入口，必须严格治理。

高风险 Tool 包括：

  1. Shell 执行。
  2. 外部 HTTP 请求。
  3. 数据库写操作。
  4. 飞书审批操作。
  5. 文件删除。
  6. AGFS checkpoint rollback。
  7. 发送消息或邮件。

Tool 安全策略：

  1. Tool 必须注册。
  2. Tool 必须有明确入参 schema。
  3. Tool 必须按用户和租户授权。
  4. Tool 调用必须记录审计。
  5. 高风险 Tool 需要 HITL 或二次确认。
  6. Tool 输出必须裁剪和脱敏。
  7. Tool 超时和异常需要映射为可解释错误。

16.6 AGFS 文件权限

AGFS 文件权限需要覆盖人和 Agent。

权限维度：

  1. 租户。
  2. 用户。
  3. 角色。
  4. 部门。
  5. 项目。
  6. Agent 角色。
  7. Task Graph 节点。
  8. 文件路径。
  9. 文件标签。

AGFS 权限操作包括：

  1. read。
  2. write。
  3. delete。
  4. list。
  5. checkpoint。
  6. rollback。
  7. share。
  8. promote_to_knowledge_candidate。

默认策略：

  1. 用户只能访问自己授权空间。
  2. Agent 只能访问当前任务授权空间。
  3. 子 Agent 默认继承根任务文件权限，但可被进一步收窄。
  4. rollback 是高风险操作，需要额外权限或任务级授权。

16.7 敏感信息与凭证管理

敏感信息包括：

  1. 模型 API Key。
  2. OpenViking Provider 凭证。
  3. 飞书 App Secret。
  4. 用户访问 token。
  5. 数据库连接串。
  6. 内部系统 token。
  7. 用户上传敏感文件。
  8. 知识库中的敏感制度或业务数据。

处理原则：

  1. 凭证只保存引用，不在日志中打印明文。
  2. runtime 请求中只传必要的短期 token。
  3. 模型上下文中不注入凭证明文。
  4. 日志、事件、错误信息必须脱敏。
  5. 前端响应不返回 endpointConfig、credentialRef 等内部字段。
  6. 敏感文件需要文件级权限和审计。

16.7.1 跨业务线能力接入的安全边界

业务线 AI 应用和原子化 AI 能力接入后，FlowNex 会成为跨业务线能力调用入口，因此必须新增能力级安全边界。

核心原则：

  1. 能力先注册，再调用。
  2. 授权先计算，再下发。
  3. 凭证由平台托管，不进入模型上下文。
  4. 输入输出按 Schema 校验和脱敏。
  5. 高风险动作必须有人机确认或审批。
  6. 所有能力调用必须可审计、可追踪、可回放。

能力级权限至少需要覆盖：

权限对象 说明
租户 哪些租户可开通该能力
部门 / 角色 哪些组织范围可使用该能力
Agent 哪些 Agent 能力包可注入该能力
Skill 哪些 Skill 可调用该能力
Tool 哪些 Tool 映射到该能力
用户 是否存在用户级白名单或黑名单

跨业务线数据安全需要关注：

  1. 输入文件是否允许传给外部 Provider。
  2. Provider 返回内容是否包含敏感字段。
  3. 调用摘要是否需要脱敏后进入日志。
  4. 能力输出是否允许进入模型上下文。
  5. 能力输出是否允许沉淀为知识候选。
  6. 业务线 Provider 是否允许保存调用数据。

禁止模式：

Skill 直接读取业务线密钥并调用外部 AI 服务。

推荐模式：

Skill / Tool
  -> Capability Gateway
  -> 平台托管凭证
  -> Provider Adapter
  -> 业务线能力

这样可以保证业务线能力接入后仍然满足租户隔离、最小权限、凭证安全和审计可追踪要求。

16.8 审计与合规

审计日志应记录：

  1. 谁发起了任务。
  2. 使用了哪些 Skill。
  3. 调用了哪些 Tool。
  4. 检索了哪些知识。
  5. 读取或修改了哪些文件。
  6. 是否触发了 checkpoint 或 rollback。
  7. 是否发送了外部消息。
  8. 管理员修改了哪些配置。

审计对象包括：

  1. 普通用户行为。
  2. 管理员行为。
  3. Agent 行为。
  4. Runtime 行为。
  5. 多 Agent 子任务行为。

审计数据既服务合规，也服务 badcase 复盘和能力演进。