# Agent Visible Summary

- 类型：`engineering`
- 状态：`draft`
- 负责人：`repo`
- 基线日期：`2026-03-21`

## 1. 目标

agent 不应直接读取完整 `rules.yml` 或 `policies/*.yml`。

平台应把复杂制度状态压缩成 agent 可理解、可行动的摘要。

一句话：

**agent 读取制度摘要，不直接读取法条原文。**

当前实现状态：

- 已实现一个轻量版 `world_rules_summary`
- 当前已注入 `available_actions / policy_notices / blocked_constraints / current_risks / recent_rule_feedback`
- 当前摘要已同时暴露到 agent runtime context、agent detail API 与 director console 的 agent 面板
- 当前摘要主要来自世界效果、最近事件、活跃对话状态，以及 agent 自身的治理状态

## 2. 为什么要有这一层

如果直接把完整规则暴露给 agent，会带来几个问题：

- prompt 负载过大
- agent 行为容易退化成“逐条合规检查”
- 平台难以调整规则实现而保持 agent 接口稳定
- 很多治理参数和内部解释并不适合直接暴露

因此平台需要单独定义 agent-facing summary。

## 3. 这一层的职责

agent visible summary 负责回答：

- 我现在可以安全做什么
- 我现在做什么风险更高
- 当前有哪些环境或政策变化
- 我最近因为什么被拦、被警告或失败

它不负责回答：

- 规则引擎内部如何求值
- 具体命中了哪条内部规则
- 治理执行层使用了哪些内部阈值

## 4. 第一版建议结构

建议在 agent runtime context 中增加一段结构化摘要：

```yaml
world_rules_summary:
  available_actions: []
  blocked_constraints: []
  current_risks: []
  policy_notices: []
  recent_rule_feedback: []
```

当前实际落地的最小结构：

```yaml
world_rules_summary:
  available_actions: []
  policy_notices: []
  blocked_constraints: []
  current_risks: []
  recent_rule_feedback: []
```

## 5. 字段建议

### 5.1 `available_actions`

表示当前时刻对该 agent 来说优先可行或相对稳妥的动作。

示例：

- `move`
- `talk`
- `rest`
- `work`

说明：

- 这不是全量系统能力枚举
- 更偏“当前可行动作摘要”
- 当前实现已支持最小版推导：
  - 默认始终允许 `move`
  - 附近存在可交互对象且当前地点未关闭时允许 `talk`
  - 默认始终允许 `rest`
  - 当前地点等于 workplace 且没有停电/关闭时允许 `work`

### 5.2 `blocked_constraints`

表示当前明确不可行或应避免的约束。

示例：

- `目标地点已关闭`
- `当前地点已满员，无法进入`
- `当前处于会话流程中，不能切换其他动作`

说明：

- 可以是人类可读短句
- 也可以附带结构化 `reason_code`
- 当前已经实现基础版，来源主要是最近被 `governance_execution.decision == block` 的原因

### 5.3 `current_risks`

表示当前环境中的风险提示。

示例：

- `夜间社交会提高异常风险`
- `主体附近的异常行为更容易被注意`
- `敏感区域中的聚集行为风险较高`

说明：

- 重点是让 agent 理解“风险上升”，而不是直接禁止
- 当前已经实现基础版，主要由 `governance_attention_score` 派生三档风险提示
- 当前风险提示已经会随 attention 的跨日衰减而回落

### 5.4 `policy_notices`

表示当前正在生效的关键政策或环境变化。

示例：

- `咖啡馆临时关闭`
- `广场有活动，社交机会增加`
- `医院区域停电`

说明：

- 这层最适合承载世界变化通知
- 当前已经实现基础版，主要覆盖当前地点相关的 world effect 通知

### 5.5 `recent_rule_feedback`

表示最近与 agent 自身相关的制度反馈。

示例：

- `你刚才试图进入关闭地点，被拦下`
- `你最近的深夜社交行为提高了风险`
- `你在敏感区域的异常行为引起了注意`

说明：

- 这是 agent 学习闭环的关键
- 应尽量和最近事件、记忆形成一致
- 当前已经实现基础版，优先读取最近 `governance_execution.decision == warn` 的原因，再补 `rule_evaluation.reason`
- 显著的 `warn / block` 当前已经写入 agent 可检索记忆
- 纯 `rule_evaluation` 反馈当前也已开始写入长期记忆：
  - `soft_risk -> Rule risk: <reason>`
  - `violates_rule / impossible -> Rule block: <reason>`

## 6. 按角色暴露

建议这一层允许按角色做差异化摘要，而不是完全相同。

例如：

- 主体角色更容易看到“我感到异常”类反馈
- cast/support 更容易看到“保持自然”“避免异常引导”类风险提示
- 背景角色只看到最基础的政策通知和行动约束

这层差异化应由 scenario runtime bridge 负责组装，而不是让 rule engine 自己决定。

## 7. 与内部规则解释的边界

建议：

- agent 可以看到“为什么不合适”
- agent 不一定要看到“命中了哪条内部 rule_id”
- agent 原则上不直接看到内部优先级和执行阈值

这是为了避免 agent 过度 meta-game 平台内部机制。

## 8. 与记忆系统的关系

`recent_rule_feedback` 不应只是临时 prompt 文本。

更合理的做法是：

- 当治理执行或规则反馈对 agent 有显著影响时
- 将其中一部分写入 agent 可检索记忆

这样 agent 才能形成真正的长期策略，而不是只依赖单次上下文窗口。

当前已经把显著的治理警告、拦截结果和纯规则反馈接入长期记忆。

当前仍未完全统一的部分：

- 摘要层与记忆层仍共用 `reason` 字符串，而不是统一的结构化 feedback 对象
- 哪些 feedback 只进摘要、哪些同时进入长期记忆，仍主要依赖代码约定
- 前端当前只做摘要展示，尚未把对应 memory 与摘要做显式串联

## 9. Narrative World 的建议摘要

对 `narrative_world`，第一版建议重点暴露：

- 当前地点或附近地点的关闭/停电/活动通知
- 当前是否处于高风险时段
- 主体附近异常行为的风险提示
- 最近被拦、被警告、被注意的原因

不建议直接暴露：

- 完整治理参数
- 所有 rule_id
- 内部巡查概率

## 10. 第一版默认结论

建议默认采用：

- agent 只读取结构化制度摘要
- 摘要以 `available_actions / blocked_constraints / current_risks / policy_notices / recent_rule_feedback` 为核心
- 可按角色差异化暴露
- 近期显著反馈应与记忆系统衔接

当前代码状态下，这已经是一个可运行的第一版结构，但仍不是最终稳定接口。

## 11. 后续待展开问题

后续可继续细化：

- 摘要是纯文本还是结构化对象
- 如何控制摘要长度
- 哪些治理事件应进入摘要、哪些应只进入长期记忆
- 如何让 `current_risks` 同时吸收 policy、地点、关系与治理状态
- 如何把 `blocked_constraints` 和长期治理后果衔接
- 如何按角色做差异化可见摘要，而不是所有 agent 看到同一套字段
