Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/code-index/peri-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
| 改输出截断恢复与未完成终态 | `src/agent/stages/{mod,act}.rs` + `src/agent/{model_bridge,react}.rs` + `src/session/exec/executor_helpers/{v2_execute,event_pump}.rs` | `run_react_loop`(mod.rs:677)、`enqueue_truncation_continuation`、`enqueue_stream_interruption_continuation`(:573)、`run_act`、`classify_loop_terminal` | 无工具 MaxTokens 保留响应并跳过完成 hook,经 Defer 最多续跑两次;连续第三次截断映射 PromptStopReason::MaxTokens。流中断保留部分正文与流式 message_id,不回灌未签名思考/半截工具、不重发文本;同样跳过完成 hook,经可信 stream_interrupted Defer 续跑;正文为空时不写空 assistant 消息(provider 拒收空 text block,判空用 `MessageContent::is_empty`)。中断预算取事件的 RetryConfig::max_attempts(含首次,累计不重置),耗尽返回 StreamRecoveryExhausted,ACP 保留底层 allowlist diagnostic;完整工具照常执行。`truncation_test.rs` 覆盖两类恢复、工具不重放、预算及取消,契约 ARC-OUTPUT-COMPLETION-001 |
| 改 Full 后预算恢复判定 | `src/agent/stages/compact_progress.rs` + `src/agent/stages/reason.rs` | `CompactBudgetRecovery::{record_full_applied,begin_request,observe_response}` | 无新 Human/Tool 工作时,两次成功 Full 后的对应实际请求 usage 仍高压则返回 `CompactBudgetUnrecovered`;Reminder/AI 不重置次数,缺失/零/过期 usage 不作证据;cancel 优先;ARC-COMPACT-001 |
| 改 compact 触发阈值 | `peri-acp-types/src/compact.rs`(`CompactConfig` 事实源,`apply_env_overrides` 实现在 :325;`peri-agent/src/agent/compact_v2/config.rs` 仅 re-export;`peri-acp/src/host/compact_config.rs` 是配置加载调用方) | `CompactConfig` 字段:`auto_compact_threshold`(默认 0.95)、`micro_compact_threshold`(默认 0.75)、`smart_compact_enabled`(deprecated、默认 false,但运行时仍尊重 true) | budget < `micro_compact_threshold` 跳过;达到该阈值后默认走 Micro,显式启用 deprecated Smart 时走 Smart;Micro 收益不足且 budget ≥ `auto_compact_threshold` 时升级 Full;force=true 直接 Full。注意:调低 Full 阈值时 micro 阈值必须更低,否则先走 Skip |
| 改 compact 策略选择 | `src/agent/compact_v2/mod.rs` + `src/agent/stages/compact.rs` + `src/agent/token.rs` | `determine_compact_action(budget, config)`(mod.rs:102,Skip/Micro/Smart 选择);`run_compact`(mod.rs:125 编排);阶段入口 `stages/compact.rs::run_compact`;`TokenTracker::pressure_sample_key` | Micro 计划收益不足且 `budget_pct >= auto_compact_threshold`、`reclaim_target > 0` 时先提交 Micro 再尝试 Full;自动 Compact 以有效 provider usage generation + tool-growth generation 标识压力样本,同一样本只尝试一次,新 usage 或工具增长可重新评估;LLM 缺失由 Full 执行阶段报 `CompactNoLlm`;cache-aware 仅是 Micro 分支的提前跳过条件;`planner.rs::CompactPolicy::force_full_threshold` 无消费点(遗留) |
| 改 compact 策略选择 | `src/agent/compact_v2/mod.rs` + `src/agent/stages/{compact,context_pressure}.rs` + `src/agent/token.rs` | `determine_compact_action(budget, config)`(mod.rs:102,Skip/Micro/Smart 选择);`run_compact`(mod.rs:125 编排);阶段入口 `stages/compact.rs::run_compact`;`TokenTracker::pressure_sample_key` | Micro 计划收益不足且 `budget_pct >= auto_compact_threshold`、`reclaim_target > 0` 时先提交 Micro 再尝试 Full;自动 Compact 以有效 usage、工具增长、可见请求增长标识压力样本,同一样本只评估一次;冷启动用已提交请求视图估算,Reason 准备阶段新增压力后复用无 hooks 核心补检;Full 空摘要在同次评估内有界重试,必要的 Full 失败阻止 Reason,耗尽空摘要预算返回 `CompactRetriesExhausted`;回归见 `stages/compact_retry_test.rs` 与 `tests/compact_*_adversarial_test.rs`;LLM 缺失由 Full 执行阶段报 `CompactNoLlm`;cache-aware 仅是 Micro 分支的提前跳过条件;`planner.rs::CompactPolicy::force_full_threshold` 无消费点(遗留) |
| 改事件契约、通道和协议转换 | `peri-acp-types/src/event_v2/{types,bus,executor_mapping}.rs`;`src/agent/events_v2.rs` | EventBus / 三层事件 / `*_event_to_executor` | 事实源及纯契约测试在 types crate,Agent 仅 re-export;`src/agent/events_v2_test.rs` 保留公共路径和 prelude 类型 identity 检查;消费者顺序与收尾仍归各 forwarder(ARC-EVENT-001) |
| 改子 Agent 事件转发与关闭排空 | `src/agent/subagent_event_forwarder.rs` | `spawn_subagent_event_forwarder`;session 使用 `spawn_subagent_event_forwarder_for_completion` | session 的 Stop 交由 lifecycle owner 在 join 后提交;observe → render → state 的 biased 优先级保持;observe Closed 只停用自身分支,三通道全部关闭且排空才退出;保留 child source 注入与生命周期事件去重;`subagent_event_forwarder_test.rs` 覆盖 producer 先关闭后的缓冲交付(ARC-EVENT-001) |
| 改 Workflow agent 装配与收尾 | `src/agent/workflow/agent.rs` | `WorkflowAgentExecutor::execute`、`await_workflow_forwarder` | public Context/API 与 frozen/tool 注入入口保留;loop → drop EventBus → await forwarder → 最终统计/结果 → telemetry terminal;编排回归在 `agent/agent_test.rs` |
Expand All @@ -34,8 +34,8 @@
| 加工具(direct/deferred) | trait 事实源 `peri-acp-types/src/tools.rs`;注册面 = middleware 的 `collect_tools()`;组装 `src/session/exec/stage_builder/tools.rs::build_session_tool_view` | `BaseTool::is_direct()`(默认 **false** = deferred);Reason publication 在 `src/agent/stages/reason.rs`,专用 hook runner 在 `middleware_runner.rs::run_before_reason_catalog`;Dynamic MCP projection holder 由 `StageBuildInput::dynamic_mcp_projection` 从 session owner 透传;启动期候选经 `middleware_runner.rs::run_before_react_start`(:84)→ `SessionToolCatalog::replace_static_mcp_tools`(`session/tool_catalog.rs:260`)替换 static base | 每 turn 先应用 middleware disabled 与 agent allow/disallow filter 构造 session-local 视图;动态 refresh 后按 working map swap → `before_reason_catalog` → `before_model` → pin 发布,ToolSearch 在专用 hook 内重绑 Search index 与 Execute resolver;Discover/resource 的 projection lease 跨 stage build 复用并由 session close 释放;startup 提交只更新 static base,不替代 Reason boundary、不混入 dynamic overlay;不得使用静态核心白名单或等待下一 turn;契约 ARC-TOOLS-001 |
| 改 PTC effective-target dispatch | `src/agent/stages/tool_dispatch/{effective_dispatcher,execution}.rs` + `peri-acp-types/src/tools.rs` | `StageEffectiveToolDispatcher::dispatch` / `dispatch_output`;`collect_tool_results` | canonical `RunPtcCode` 是 deferred-only,经 `SearchExtraTools → ExecuteExtraTool` 进入执行;从当前 pinned catalog canonical resolve,policy/HITL/event/tool card 投影 effective target,并复用 timeout/cancel;typed execution evidence 经 canonical direct/deferred wrapper 透传;嵌套调用不写 transcript 或重复执行外层 batch hook/失败计数;模型 assistant raw wrapper call 仅保留协议配对;direct tools 不受影响;PTC JavaScript tools API 仍为 string projection;旧 `run_code` 仅作搜索迁移关键词,不可执行 |
| 改 cancel 链路 | `src/agent/stages/mod.rs` + `src/session/exec/executor_helpers/v2_execute.rs` + `peri-acp-types/src/session.rs` | `run_stage`(stage-local `AgentError::Interrupted` 规范化);`build_and_execute_agent_v2` / `classify_loop_terminal`;`cancel_cascade_agents` / `cancel_all_agents`;`CancelRequest` 在 `peri-acp-types/src/identity.rs` | stage 仍成对发射 `StageEnded(Error)`,loop 终态统一为 Interrupted;按 (session_id, turn_id, attempt_id) 三元组定位;幂等判定与终态归 Agent 层;clear_queue 默认 false;契约 ARC-CANCEL-001 |
| /compact 命令路径 | `src/session/exec/compact_pipeline.rs` + `src/session/exec/executor_helpers/{intercept,event_pump}.rs` | `run_compact(force=true)` → Full + re-inject;`executor_helpers::done_stop_reason` | 输入与 Host 同为 canonical 消息历史:普通消息 ID/顺序与持久化快照一致性校验后,恢复完整 payload(含 reminder)、flags 和 ancestor/own 边界选择可见内容;仅 reminder 历史也可压缩;命令与普通执行共用 done 终态投影,取消返回及通知均为 cancelled,不确定提交仍按 Internal/reload 收尾 |
| 改 LLM 调用链路 | `src/agent/stages/reason.rs` + `src/agent/model_bridge.rs` | `run_reason`;`AgentModelBridge::build_request`;model_bridge 流式事件 v2 直发 | Reason:snapshot → LlmCallStart → before_model → generate(与 cancel 竞争)→ after_model → LlmCallEnd;bridge 每个 ModelRequest 同步读取一次当前 middleware prompt contribution,与 frozen base request-local 组合且不累加;事件契约 ARC-EVENT-001 |
| /compact 命令路径 | `src/session/exec/compact_pipeline.rs` + `src/session/exec/executor_helpers/{intercept,event_pump}.rs` | `run_compact(force=true)` → Full + re-inject;`executor_helpers::done_stop_reason` | 输入与 Host 同为 canonical 消息历史:普通消息 ID/顺序与持久化快照一致性校验后,恢复完整 payload(含 reminder)、flags 和 ancestor/own 边界选择可见内容;仅 reminder 历史也可压缩;命令与普通执行共用 done 终态投影,取消返回及通知均为 cancelled,Full 失败保留脱敏的类型诊断,不确定提交仍按 Internal/reload 收尾 |
| 改 LLM 调用链路 | `src/agent/stages/reason.rs` + `src/agent/model_bridge.rs` | `run_reason`;`AgentModelBridge::build_request`;model_bridge 流式事件 v2 直发 | Reason:catalog → before_model → 压力补检 → snapshot → LlmCallStart → generate(与 cancel 竞争)→ LlmCallEnd → after_model;bridge 每个 ModelRequest 同步读取一次当前 middleware prompt contribution,与 frozen base request-local 组合且不累加;事件契约 ARC-EVENT-001 |
| 改工具执行分发 | `src/agent/stages/act.rs` + `src/agent/stages/tool_dispatch.rs` + `tool_dispatch/execution.rs` | `run_act`;`dispatch_tools`;`collect_tool_results`;`ToolResult::execution`;`ToolOutput::projected_text` | 外层一次 staging/commit 后计入含解析失败结果的 tool-growth,再执行 after_tools_batch;typed execution evidence 随统一 bounded projection 进入 live `ToolEnded`、`ToolResult` 与 `BaseMessage::Tool` 持久化;`SubagentFailure` 经 boxed error downcast 保留 child identity 与 SafeSubagentFailure,诊断 facts 同步进入模型可见 tool content;cancel/timeout error 保留 typed status,普通 legacy error 保持 unknown;PTC 内部调用不重复结算;私有执行管线保持审批 → yield → 并发完成即发 ToolEnded → after_tool → 后处理顺序,after_tool 看不到本轮待提交消息;ToolStarted 与实际执行均使用审批后参数,transcript 保留模型原始调用用于配对 |
| 改 middleware 状态能力 / 消息修改 | `src/middleware/{capabilities,state}.rs` + `src/agent/agent_context.rs` + `src/agent/stages/middleware_runner.rs` | `BeforeAgentState` / `BeforeInputState` / `InputBatchState::input_message_ids` / `BeforeToolState` / `AfterToolState` / `AfterAgentState`;`MiddlewareState::replace_message`;`AgentContext::from_stage` / `reconcile_to_transcript`;`run_before_agent` / `run_before_input` | hook 不再暴露 cwd/step setter、store/thread 或无法回写的 token/context 快照;首次 Receive 按链序交错执行 before_agent / before_input,后续用户批次只执行 before_input;空批次不重读历史;替换按稳定 MessageId 查找,不增删/重排,输入准备成功或 Err 后均 reconcile;StateView 无可变 queue/catalog;队列和目录分别由 QueueState/CatalogState 提供,before_model 保留消息追加,其他 hook 无输入替换能力 |

Expand All @@ -48,7 +48,7 @@
| 阶段循环入口/StageContext | stages/mod.rs | `run_react_loop`;`run_stage`;`StageContext::builder()`;`append_messages_to_transcript`。`run_stage` 先成对发射 `StageEnded`,再将 stage-local `AgentError::Interrupted` 规范化为 `LoopResult::Interrupted`;其他错误保持 `LoopResult::Error` |
| Receive(排空队列 + 退出判定) | stages/receive.rs | `run_receive`;`drain_all` + `consumed_count` |
| Compact(预算检查 + 触发压缩) | stages/compact.rs | `run_compact`;PreCompact/PostCompact hook |
| Reason(LLM 推理) | stages/reason.rs | `run_reason`;只恢复已提交 projection(与自动 compact 开关独立),无 directive 使用 canonical;验证 Full 后真实 usage |
| Reason(LLM 推理) | stages/reason.rs | `run_reason`;只恢复已提交 projection(与自动 compact 开关独立),无 directive 使用 canonical;准备阶段新增压力时补检 Compact,绑定最终请求预算;验证 Full 后真实 usage |
| Act(工具执行或回答) | stages/act.rs | `run_act`;emit TurnCompleted |
| 工具批次提交 | stages/tool_dispatch.rs | `dispatch_tools`(:73);ID/target 解析、原子转录、batch hook 与错误收敛 |
| 共享调用执行 | stages/tool_dispatch/execution.rs | `collect_tool_results`(:51);审批/并发/结算,参数复用 `tools::normalize_params` |
Expand Down
Loading
Loading