Skip to content

V1 Safety and Evaluation

weego edited this page Nov 15, 2026 · 3 revisions

安全、观测与评测

简体中文 | English

适用版本:v1.0.0。安全边界由可信应用和运行环境共同实施。模型输出、工具结果、检索结果、MCP 描述、Skill 指令和外部产物都不能自行授予权限。

哪一层负责什么

层 入口 职责
业务身份与授权 SecurityContext、PermissionSet、CapabilityGate 绑定用户、租户、项目及资源。子任务只能收窄能力、风险、网络和截止时间。
组件与策略 CapabilityRegistry、CapabilitySpec、PolicyEngine 注册、选择和调用受信 Provider;声明 scope、读写、网络、风险、超时与审批需求。
生命周期 HookContext、HookDecision、PolicyHook 在指定阶段观察、改写或阻断;权限判定应在错误或超时时拒绝。
内容规则 input/tool/output Guardrails 输入、解析后的工具参数、最终非流式输出;不是 OS 沙箱。
人工核对 HumanApprovalHook、ApprovalDecision、ApprovalToken 核对实际操作;审批应过期、受范围约束,并要求可靠的审核人身份。
运行隔离 WorkspaceExecutionProvider、ExecutionRequirements 由执行环境实施,不能用提示词、签名或目录名代替。

ToolProviderAdapter、MemoryProviderAdapter、SkillProviderAdapter、MCPProviderAdapter、WorkflowProviderAdapter 可将现有组件接进注册表。选择最小能力集,按租户限制资源;同级冲突用 registry.conflicts() 诊断。授权应在实际调用边界再次检查,不只在模型选工具时检查。需要审批的 Capability 请求应使用绑定操作、参数、资源和身份的 ApprovalToken,而不是通用口令。

Hooks 与 Guardrails:离线拒绝示例

下面的权限服务用异常模拟不可用,PolicyHook 会在请求模型之前拒绝。代码故意使用本机占位端点,不需要密钥或真实服务:

from LightAgent import LightAgent, PolicyHook

def authorize(context):
    raise RuntimeError("授权服务暂不可用")

agent = LightAgent(
    name="policy-demo", model="offline-fixture", api_key="offline",
    base_url="http://127.0.0.1:1/v1",
    auto_discover_skills=False,
    hooks=[PolicyHook(authorize, phases={"before_run"}, timeout=1.0)],
)
result = agent.run("读取示例数据", result_format="object", trace=True, max_retry=1)
assert result.error and "LA-HOOK" in result.error
print(result.error)

普通观测 Hook 隔离自己的异常;策略必须显式选择 fail-closed 的 PolicyHook。阶段包括 run 前后及错误、模型请求与响应、工具前后、记忆读取/写入/晋升、Swarm handoff,以及 LightFlow 步骤、审批、resume/rerun。Codex 外部后端的策略阶段只支持 run 前后和错误,不观察 CLI 内部工具。调试时用 HookDecision.continue_()、replace() 或 block() 明确表达结果;不允许改写的阶段不能当作路由入口。

privacy_input_guardrail()、sensitive_tool_confirmation_guardrail()、high_risk_parameter_guardrail()、output_redaction_guardrail() 是可组合模板,不是自动合规方案。输出规则不能撤回已经流式发送的内容。旧任意 Python 工具不应暴露给不受信输入,模型与工具调度会阻止旧执行器;safe_expression 仅适合受限表达式。参考 Guardrails、Hooks 与配方。

人工审批与反馈

给受保护的工具或 handoff 配置 HumanApprovalHook(store=..., tools={...})。没有同步审核人时,先生成待处理请求并阻止动作。可信审核端从 InMemoryReviewStore 或 JsonReviewStore 读取请求、校验实际参数,再调用 resolve(request_id, ApprovalDecision.approve(...));重跑对应动作时显式传 approval_id,不把内部审批标识传给模型。拒绝、编辑、批量处理和 HumanFeedback 由业务层挂接;格式见 人工审核。固定流程的持久审批示例见 LightFlow;后台任务交互见 持久执行。三类接口不应互换 ID。

Trace、日志与回归评测

要读取用量、按 token 估算费用或区分缺失数据,请先看用量统计与预算。

用 agent.run(..., result_format="object", trace=True) 读取 trace_id 与事件。常见事件包括 run 开始/结束、模型请求、工具调用/结果、审批、Hook 决策、Guardrail 阻断和错误;用 parent_trace_id / run_group_id 串联委托与子流程。用 agent.summarize_trace() 汇总延迟、重试、工具、审批和 token;JsonlTraceExporter 适合输出本地审计文件。原始工具参数和输出可能是敏感数据,对外导出前先脱敏并配置访问和保留策略。Langfuse 是可选 langfuse extra;本地 Trace 不要求 SDK。详见 Trace 参考 和 Langfuse 配置。

下面用稳定的本地 target 做一条不依赖模型的回归。应用可以换成真实 Agent、LightFlow 或测试替身,加上必须/禁止的工具、指定事件、延迟、恢复与业务断言。

from LightAgent import EvaluationCase, LightEvaluator, RunResult

class LocalTarget:
    def run(self, query, **kwargs):
        return RunResult(content="验收:" + query)

report = LightEvaluator().run(LocalTarget(), [
    EvaluationCase(name="输出契约", query="数据格式", expected_output_contains=("验收", "数据格式"))
])
assert report.passed == 1
print(report.to_dict())

用 评测参考 配置自定义断言和费用估算。费用估算不是账单,缺少 usage 不能推断没有产生费用。

Provider 验签与宿主批准

安装 signing extra 后,在 v1.0.0 源码目录运行以下离线示例。它使用临时 Ed25519 密钥、审查指定摘要,演示修改后旧批准失效:

python example/17.signed_providers.py

宿主从可信渠道配置发布者公钥;ProviderAttestation 绑定文件树、发布者、发行序号、版本、能力/配置摘要和有效期;ProviderTrustStore 保存明确批准和撤销;AttestedProvider 在启用和调用时核对。新内容和动态绑定发生变化需重新签名与批准,不能静默复用旧信任。签名不代替用户授权、运行隔离、操作审批,也不证明远端实现安全。演示密钥不用于生产。完整生命周期见 Provider 供应链与重授信。

Clone this wiki locally