OpenProgram Docs
Proactive Layer 接入代码 — 设计#
Proactive 本身的设计在
../proactive/。本文只讲那套设计 与现有 OpenProgram 代码的交界：复用了哪些机制、事件从哪里发出、gate 挂在哪里、 它的强制力实际覆盖到什么程度。有冲突以设计文档为准。
1. 代码落点#
事件层是 openprogram/events/bus.py 的就地升级：Event、按事件类型订阅、
进程级单例。taps 加在各个本来就知道「刚才发生了什么」的源文件里，而不是集中到一个
收集器。openprogram/proactive/ 包装规则层，等第一个规则消费者出现时才建；在那之前
事件层本身已经有用。
事件模型是核心三样加一个开放的 metadata 口袋（设计 event-layer.md §1）。
turn 和 session 走 metadata 而不是固定字段，这样没有 turn 概念的源不必硬造一个。
2. 复用而非重建的机制#
设计里描述的每个角色，代码库里都已经有一份能用的实现：
| 设计中的角色 | 现有机制 | 位置 |
|---|---|---|
| 进程内事件扇出 | EventBus——已实现但闲置，dispatcher 和 agent_loop 用直接回调绕过了它 |
openprogram/events/bus.py |
gate 的 ask 路径 |
ApprovalRegistry + _wrap_with_approval：发起请求、阻塞等待、批准或拒绝，拒绝时回一个 is_error 的 tool result |
openprogram/agent/permissions/approval.py |
observer 的 Prepare 后台 task |
JobRunner.spawn_job——ThreadPoolExecutor、状态机、job_status 广播 |
openprogram/agent/job/runner.py |
Inject 的落地槽位 |
注入 system prompt 的 memory prefetch，以及 steering messages | openprogram/agent/agent_loop.py |
| 事件因果、rewind、分支 | session git DAG，节点带 parent_id / caller | openprogram/context/git/ |
| gate 的强制点 | 所有 chat tool 调用都要过的那一个点 | agent_loop.py _execute_tool_calls |
3. 事件 tap#
事件从本来就能察觉到相应事实的位置发出。多数 tap 是把现有回调或内部事件转成规范事件， 而不是新增一套探测：
| Event | 来源 | tap 的性质 |
|---|---|---|
user.prompt_submitted |
dispatcher/__init__.py，持久化用户消息处 |
加在已有的 chat_ack / chat_response 广播旁；放在持久化分支之外，两条路径都会发 |
model.response_started |
agent_loop.py 的 AgentEventMessageStart |
转换现有事件 |
model.response_completed |
agent_loop.py 的 AgentEventMessageEnd |
转换现有事件 |
tool.before |
agent_loop.py，每次 tool.execute() 之前 |
一份事件同时喂 notify emit 与 gate 问询 |
tool.after |
agent_loop.py，每次工具调用结束之后 |
notify emit，附结果文本通道 |
subagent.started / completed |
task/runner.py 的 job_status 广播 |
转换，经 _broadcast_job_status 汇总 |
permission.requested |
permissions/approval.py 的 approval_request 信封 |
新增 tap |
artifact.file.changed |
file_backup.backup_before_edit 与 project_commit |
写成功后新增发送 |
4. gate 的挂载点与如实声明的覆盖率#
gate 挂在两个地方，两处的保证强度确实不同，这个差别是明说的，不掩盖。
chat 路径——强制。 gate 串在 agent_loop.py 的 _execute_tool_calls 里、
tool.execute 之前。所有 chat tool 调用都过这一个点，绕不过去。
agentic 嵌套路径——可选挂载。 function.py 的 _pre_invocation_hooks，
cancel 检查已经挂在这里。它是一个挂载点而非咽喉点；覆盖率如实声明，不对嵌套调用
宣称全覆盖。
gate 对 subagent turn 生效，且独立于 permission_mode。特别地，它不会被
sub_agent_run.py 里设的 permission_mode="bypass" 关掉——那个 bypass 是本设计
要堵的现有漏洞（设计 invariants.md 与 execution-model.md §2）。
5. Prepare 的执行#
Prepare 复用 JobRunner.spawn_job，但注入一个不含 bash、write、network 的受限
tool allowlist。它跑在一个独立小池里，并发 1–2，可被用户任务抢占，遇 429 让路
（设计 execution-model.md §3）。
6. 一个已知缺口，但不阻塞#
@function 的 tool 执行不写 DAG 节点，只有 Agent method 写，因此 DAG 树作为
因果记录是不完整的。如果审计必须靠 DAG 做因果回溯，就得先补上这一块。本设计改为在
events.jsonl 里独立记录全量事件，于是 DAG 的缺口成了一个已知项，而不是前置条件。
7. 验证方式#
每一处接线改动都按同一套查：py_compile、相关单测、仓库规定的本地刷新流程、
/healthz 正常，以及经 web UI 发一条真实消息（前端改动要先 npm --prefix apps/web run build）。
事件顺序的验证方式是跑一个带工具调用的 turn，读该会话的 events.jsonl
（事件日志常开）。日志必须依序出现 user.prompt_submitted → model.response_started → tool.before → tool.after → model.response_completed，且每条的
metadata 里带 session 和 turn。
附录：实现状态#
总线、源头 tap、外部源桥接、订阅式 web UI，以及 openprogram/proactive/ 包都已在当前
源码中存在。规则层入口是 openprogram/proactive/engine.py::install_proactive，Policy
位于 openprogram/proactive/policies/。包和 Policy 已实现，但当前
openprogram/worker/runner.py 没有在 worker 启动时调用 install_proactive()；worker
启动时安装的是另一个独立的 event bridge。因此 worker 生命周期接线仍是明确的未实现边界。
原五步顺序作为设计历史保留；当前状态以源码路径和测试为准。
已落地的各部分位置：
| 件 | 位置 |
|---|---|
Event / make_event / emit_safe / subscribe(types=) / get_event_bus / 事件日志订阅者 |
openprogram/events/bus.py |
同步问询点：register_tool_gate / decide_tool_gate / ToolGateDenied |
openprogram/events/tool_gate.py |
tool.before 观察与问询、tool.after、model.* taps |
openprogram/agent/agent_loop.py |
user.prompt_submitted |
openprogram/agent/dispatcher/__init__.py |
subagent.started / ended |
openprogram/agent/job/runner.py _broadcast_job_status |
file.changed，写成功后经懒 import 发出 |
write / edit / apply_patch 三个工具中的五处 |
| 外部源桥，worker 启动时幂等安装 | openprogram/events/bridges.py + worker/runner.py |
| 外部源头 taps | context/engine.py（compaction ×2）、channels/_conversation.py、memory/session_watcher.py（×2）、webui/server.py（skills / plugins） |
emit_ws_frame 透传信封 + _subscribe_event_bus 订阅转发 |
openprogram/events/bus.py、webui/server.py |
| 外部源不再 import web UI | task/runner.py、sub_agent_run.py、worktree/manager.py、functions/watcher.py、channels/_broadcast.py |
| 单测（30 个） | tests/agent/test_event_bus.py、test_tool_gate.py、test_event_bridges.py |
单测覆盖事件总线、tool gate、事件桥和 proactive policies。Installed-App 与实时
WebSocket 验收属于独立检查，本设计记录不宣称已经完成。有一条环境注意事项要带下去：
worker 的工作目录是 home，因此项目 skills 目录解析成 ~/skills。