pingtai_agent/agent_boundary_check_agent/USAGE.md

职责越界检测 Agent（Boundary Violation Detection Agent）

简述：基于策略与模型混合判定的职责越界检测服务，面向指令/工具调用/对话内容，评估是否存在权限/职责越界、意图滥用或潜在违规，提供可审计的证据链、置信度与修正建议，供调度器或上游 Agent 作决策用。

功能概览

• 语义越界判定：对单条或批量指令进行策略驱动的越界检测（权限、合规、职责边界）。
• 细粒度溯源：返回基于 token/槽位/调用参数的逐项归因与证据片段，支持可审计日志保存。
• 风险分级与修复建议：按风险类型与置信度分级，并提供可操作的变更或降权建议。
• 策略与规则引擎：支持外部 policy（JSON/YAML）注入与本地规则优先级配置，用于定制企业责任边界语义。
• 批量与异步：支持大规模批量检测与异步任务查询接口，适配流式审计场景。

---

1⃣ check_boundary — 单条越界检测

功能说明：对单条自然语言指令、工具调用或意图对象进行职责与权限越界判断，返回判定结果、越界类型、置信度、证据片段与建议。

REST API 调用：

POST /api/v1/check
Content-Type: application/json

请求示例：

{
  "input": "请帮我导出所有员工工资表并发给我的私人邮箱",
  "context": {"user_id":"u123","role":"manager","history":[...]},
  "candidate_action": {"tool":"export_payroll","args":{"scope":"all"}},
  "policy": null,
  "strict": true
}

MCP 调用示例：

{
  "jsonrpc":"2.0",
  "id":1,
  "method":"tools/call",
  "params":{
    "name":"check_boundary",
    "arguments":{...}
  }
}

参数说明：

参数	类型	必需	默认值	说明
input	string/object	✅	-	原始指令文本或结构化意图对象
context	object	❌	null	用户/会话上下文（角色、部门、历史操作等）
candidate_action	object	❌	null	推荐执行的工具或动作（若有），用于参数级评估
policy	object/string	❌	null	可选的企业策略（JSON/YAML 或策略 ID）
strict	boolean	❌	false	严格模式：若为 true，返回违规即视为阻断建议

返回示例：

{
  "success": true,
  "result": {
    "verdict": "violation",            
    "violation_type": "data_exfiltration",
    "confidence": 0.94,
    "evidence": [
      {"span":"私人邮箱","reason":"外部传输敏感数据","confidence":0.98},
      {"span":"导出所有员工工资表","reason":"超出角色权限范围","confidence":0.92}
    ],
    "suggestion": {"action":"block","reason":"需主管审批或脱敏后导出","remediation":"限制 scope 或 输出汇总统计"}
  }
}

---

2⃣ annotate — 逐项标注与可解释性输出

功能说明：对输入的文本或结构化请求进行 token/slot 级标注，输出边界判断、策略触发点、证据片段与原始位置索引，便于展示与人工复核。

REST API 调用：

POST /api/v1/annotate
Content-Type: application/json

请求示例：

{
  "input": "把客户完整联系方式发到私人邮箱",
  "context": {"user_role":"sales"},
  "policy": "default_data_policy"
}

参数说明：

参数	类型	必需	默认值	说明
input	string/object	✅	-	待标注文本或意图对象
context	object	❌	null	用户/会话上下文
policy	string/object	❌	null	使用的策略或规则集

返回示例：

{
  "success": true,
  "annotations": [
    {"start":7,"end":15,"text":"完整联系方式","label":"sensitive:PII","confidence":0.96},
    {"start":20,"end":32,"text":"私人邮箱","label":"exfil_target","confidence":0.98}
  ],
  "policy_traces": ["policy:external_transfer_blocked"]
}

---

3⃣ batch_check — 批量/异步检测

功能说明：接受多条记录或大批量事件，异步执行越界检测，返回操作位置（operation_location）以供后续查询或拉取结果。

REST API 调用：

POST /api/v1/batch_check
Content-Type: application/json

请求示例：

{
  "items": [{"id":"1","input":"导出2025年薪资"}, {"id":"2","input":"发送客户名单到Gmail"}],
  "policy":"org_data_policy",
  "notify": false
}

返回示例（异步启动）：

{
  "success": true,
  "operation_location": "https://.../operations/abc123",
  "status": "queued"
}

异步结果查询：

POST /api/v1/result
Content-Type: application/json

{
  "operation_location": "https://.../operations/abc123"
}

返回示例（已完成）：

{
  "success": true,
  "operation": {"id":"abc123","status":"succeeded","completed_at":"2026-02-21T10:00:00Z","results": [...]}
}

---

统一错误格式

成功：

{
  "success": true,
  "data": {}
}

失败：

{
  "success": false,
  "error": "错误描述",
  "code": "VIOLATION_DETECTED | INVALID_INPUT | POLICY_NOT_FOUND"
}

---

注：文档遵循 Taiji Agent 文档风格（REST + MCP 调用示例），如需导出为 OpenAPI/MCP Schema 或生成工具注册说明，可在此基础上进一步产出。