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
2 changes: 1 addition & 1 deletion docs/code-index/peri-acp.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
| 改待发送队列控制与执行准入 | `src/host/requests/user_input.rs` + `src/host/user_input.rs` + `src/host/prompt_dispatch.rs` | `handle_user_input`;`ensure_mailbox` / `schedule_mailbox`;`dispatch_prompt_turn_with_input` | 四短 RPC 不等 prompt_lock,session 持 Agent Mailbox;Agent ticket 经同一执行锁启动,RunStarted/done 身份配对,Stop 精确定位,MPSC/stdio 共用请求与事件链(ARC-BOUNDARY-001 / ARC-EVENT-001) |
| 改插件 marketplace 搜索 | `src/host/requests/plugin.rs` + `plugin_search_test.rs` | `handle_search` / `search_marketplace_plugins` | 经 PluginManagerPort 获取缓存目录,复用 `plugin::marketplace::find_marketplace_json` 读取根或 `.claude-plugin` 布局;名称、描述、marketplace 名均忽略大小写匹配;无匹配明确返回空数组;回归经真实 `handle_request` 读取临时磁盘目录 |
| 改 compact 后失败恢复 | `src/host/prompt.rs` + `src/host/compact_recovery_test.rs` | `finish_prompt_turn` | 不按 `ok` 丢弃可信 canonical snapshot;取消/模型或 forwarder 失败仍保留已提交 Full 摘要;persistence_inconsistent 移除热会话,冷加载恢复磁盘,ARC-COMPACT-001 |
| 验证手动 compact 跨轮与取消 | `src/host/compact_command_test.rs` + `src/session/command/compact_persistence_test.rs` + `tests/compact_command_contract_test.rs` | `run_session_loop` → `finish_prompt_turn`;`TransportEventSink` | 覆盖连续手动、自动 Full 后手动、新连接冷读后手动、摘要生成中取消;完整 canonical 历史保持,done 与 PromptResponse 在真实 MPSC 通知上同一终态;原始两项复现保留为 public API 集成回归 |
| 验证手动 compact 跨轮与取消 | `src/host/compact_command_test.rs` + `src/session/command/compact_persistence_test.rs` + `src/session/command/compact_report_test.rs` + `tests/compact_command_contract_test.rs` | `run_session_loop` → `finish_prompt_turn`;`TransportEventSink` | 覆盖连续手动、自动 Full 后手动、新连接冷读后手动、摘要生成中取消,以及完整报告输入/排除、仅 reminder 和 child 边界;完整 canonical 历史保持,done 与 PromptResponse 在真实 MPSC 通知上同一终态;原始两项复现保留为 public API 集成回归 |
| 改 System Reminder producer/ACP 投影 | `src/session/dynamic_mcp.rs` + `src/host/continuation.rs` + `src/session/event_sink.rs` + `src/dispatch/session_replay.rs` | `SessionDynamicMcpNotificationSink`;`enqueue_cron_trigger`;`push_system_reminder`;`send_system_reminder` | Dynamic MCP lifecycle/OAuth 与 Cron trigger 直接入 canonical queue;不改变 OAuth/cron 控制;ACP client 声明 `peri.systemReminder` 时收结构化 event,否则只收展示 fallback;load/replay 不伪装 user message;旧 Compact plain-text Human 经 `compact_reminder::legacy_compact_reminders` 生成 Legacy 通知,MPSC/stdio 共用出口 |
| 新增/改会话协议方法 | `src/host/requests.rs`(注册面,`handle_request` :22,按方法分派到 `host/requests/{session_lifecycle,plugin,config_options,mcp_oauth,workflow,rewind}.rs`);`src/host/server_loop.rs`(`session/prompt` 单独处理,spawn 后台 task);`src/session/frozen_snapshot.rs`(版本化 frozen owner state);`src/dispatch/session_fork.rs`(fork payload 独立复制);stdio 侧部署装配点 `src/host/stdio/mod.rs`(`run_acp_stdio` 持有进程日志初始化,`assemble_stdio_config` 只装配配置,业务处理走统一 `run_acp_server`) | `handle_new/load/resume/fork`(requests/session_lifecycle.rs);`new_session_from_prepared`(new 的发布段:消费已定格准备输入写 meta/binding/frozen 并发布,不重读配置/插件、不重建 frozen);`handle_reset_dirty`(`peri/session_reset_dirty`,需 `peri.sessionRecoveryV1` 与显式 `accept_risk`);`fork_session`;`encode_frozen_snapshot` / `decode_frozen_snapshot`;`after_new_response`;其余 plugin/config/workflow/rewind handler | new 持久化 frozen 后才发布 session;load/resume 冷恢复原快照,未绑定 legacy 根恢复经 `requests/legacy_session.rs::prepare_for_restore` 按保存 cwd 原子接纳 binding + 缺失 frozen、loser 重读 winner;已绑定缺快照保持错误,未知/损坏版本及存储错误 fail closed;fork 继承 source frozen,并以新 `MessageId` 复制 payload/compact flags,使新 thread 独立拥有可压缩历史;new/fork 写失败补偿删除。`session/load` 保持 response 前 replay/通知;load/resume 补载驻留空历史时同步 canonical payload 与消息投影,后续 prompt/fork 从同一 payload 读取;`session/prompt` 是唯一 spawn 后台执行的方法;stdio 与 TUI 共用统一 host |
| 改 prompt 执行流程(keepgoing/挂起注入/错误响应) | `src/host/prompt.rs` + `src/host/prompt_dispatch.rs` + `src/session/executor.rs` | `run_prompt`;`prompt_wire_response` / `execution_failure_to_acp_error`;`dispatch_prompt_turn`;`session/executor.rs` **仅 re-export** `peri_agent::session::exec::executor` 的执行入口(ARC-BOUNDARY-001) | 挂起时 prompt 注入 inbox;keepgoing 短路在 Agent 层;重试中的 `LlmRetrying` 是进度事件,不结束 prompt;仅 fatal `PromptResult.failure` 在历史/state/cancel-token 后处理完成后映射为 `session/prompt` JSON-RPC server error(`-32000`):message 保留脱敏限长后的 LLM/provider 原意,allowlist data 携带 `kind` 与可选 HTTP `status`、受控 diagnostic facts;ACP 不序列化完整 AgentError/ModelError/provider body;cancel/interrupted/max iterations/输出截断预算耗尽仍返回携带对应停止原因的标准 `PromptResponse`,协议成功不代表任务完成(ARC-OUTPUT-COMPLETION-001);mpsc/stdio 共用统一 host |
Expand Down
6 changes: 3 additions & 3 deletions docs/code-index/peri-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,14 +27,14 @@
| 改 Workflow agent 观测与进度 | `src/agent/workflow/agent/observation.rs` | `WorkflowObservation::{handler,report_model,snapshot}` | 单一锁持有 tool count、output usage 与最后模型;事件先累计/发送 progress,再调用 Langfuse;有效模型早报保持 None 计数;`observation_test.rs` 覆盖进度先后与关闭排空后统计 |
| 改 Workflow agent 返回值与遥测终态 | `src/agent/workflow/agent/result.rs` | `project_run_result`、`completed_result`、`ProjectedResult::telemetry_outcome` | forwarder failure 优先于 loop 终态;schema 只校验输出,成功仍返回 JSON string;无 usage 时保留字节长度 token 估算,缺模型回退有效模型;`result_test.rs` 覆盖 wire、schema、失败优先和取消 |
| 改 compact 展示事件 | `src/agent/stages/compact.rs` + `peri-acp-types/src/event_v2/{types,executor_mapping}.rs` + `src/session/exec/{compact_pipeline,events}.rs` | `ObserveEvent::CompactStarted` / `MessagesCompacted`;`observe_event_to_executor`;`emit_compact_started` / `emit_compact_completed` | 自动 compact 将 strategy、受影响消息数、估算节省 token、files/skills 映射到 `ExecutorEvent::CompactCompleted`;手动 `/compact` 从 pipeline 发送同一展示载荷;下游经 ACP 单路径投递,契约 ARC-EVENT-001 |
| 改 Micro/Full 执行细节 | `src/agent/compact_v2/{micro,projection,full}.rs` + `src/session/{transcript.rs,exec/executor_helpers/v2_execute.rs}` | `micro_compact`;`render_llm_view`;`full_compact_inner`;`re_inject_v2`;`MessageTranscript::{with_own_payloads,with_ancestor_payloads}` | Micro 不原地截断 transcript,而是持久化 message-level projection directive,后续模型视图由 `render_llm_view` 投影工具结果;普通 root Agent 与独立复制后的 ACP fork 跨 turn 历史属于可压缩 own region;显式继承上下文才使用只读 ancestor boundary;子会话以版本化 InheritedContext 冻结 payload 与 flags,load/resume 保持 ancestor/own 边界,普通 setter 与 lifecycle 拒绝改写祖先;Full 仅按本轮新 `excluded` transition 统计 affected messages,文件 re-inject 只从 Full 前可见 `Read` 来源收集,新 `Read` 同路径仍可注入更新内容;精确载荷污染风险见 `spec/issues/2026-09-09-p0-micro-compact-edit-write-context-corruption.md`,compact churn 调查见 `spec/issues/2026-09-10-p0-full-micro-compact-churn.md` |
| 改 Micro/Full 执行细节 | `src/agent/compact_v2/{micro,projection,full}.rs` + `src/session/{transcript.rs,exec/executor_helpers/v2_execute.rs}` | `micro_compact`;`render_persisted_llm_view` / `render_llm_view`;`full_compact_inner`;`re_inject_v2`;`MessageTranscript::{with_own_payloads,with_ancestor_payloads}` | Micro 不原地截断 transcript,而是持久化 message-level projection directive,后续模型视图由 `render_llm_view` 投影工具结果;普通 root Agent 与独立复制后的 ACP fork 跨 turn 历史属于可压缩 own region;显式继承上下文才使用只读 ancestor boundary;子会话以版本化 InheritedContext 冻结 payload 与 flags,load/resume 保持 ancestor/own 边界,普通 setter 与 lifecycle 拒绝改写祖先;Full 从与 Reason 共用的已提交模型视图构造结构化摘要请求,包含 canonical reminder 且无额外正文预览截断;没有可替换 own 历史时不调用摘要模型;正常完成的非空摘要与 own 非 System 历史(含 reminder)的 excluded transitions 原子提交;仅按本轮新 transition 统计 affected messages,文件 re-inject 只从 Full 前可见 `Read` 来源收集,新 `Read` 同路径仍可注入更新内容;精确载荷污染风险见 `spec/issues/2026-09-09-p0-micro-compact-edit-write-context-corruption.md`,compact churn 调查见 `spec/issues/2026-09-10-p0-full-micro-compact-churn.md` |
| 改 Goal 自动接续与状态事件 | `peri-middlewares/src/{goal_middleware,completion_reminder}.rs` + `src/middleware/capabilities.rs` + `src/agent/agent_context.rs` + `src/session/exec/stage_builder.rs` | `CompletionReminder::admit/enqueue`;`BackgroundActivity::has_active_background_tasks`;`GoalController::increment_continuation`;`emit_goal_snapshot` | active Goal 经与 todo 共用的准入后才增长主动接续/紧迫感;已有 `block_continue` 优先,后台活动复用 Receive 的 `idle_should_wait → TaskManager::active_count`(Agent/Workflow/Shell 的 Running/Completing)。`build_stage_context` 在装配前统一补齐缺省 manager,工具、SubagentHost、probe 与 registry wake 必须同源;装配回归见 `peri-middlewares/src/assembly_test.rs::test_stage_completion_reminders_share_assembled_task_manager`。Workflow 在 `WorkflowTool::start_run` 注册,`session/workflow_completion.rs::apply_workflow_task_result` 先送完成 Defer 再提交 task 终态;终态后恢复提醒。Act 每轮结束(含错误返回)发 session Goal 快照,经 ACP 单路径投影;回归见两类 middleware 测试及 `middleware/capabilities_test.rs`、`session/workflow_completion_test.rs` |
| 改循环退出 / keepgoing 判定 | `src/session/exec/executor.rs` + `src/agent/stages/mod.rs`(Receive 分支) | `executor.rs:130 is_keepgoing(&MessageContent)`;`run_session_loop`(executor.rs:221);`run_react_loop` 正常退出判断(stages/mod.rs:647 `consumed_count == 0 && !has_tool_calls`);判空底层 `peri-acp-types/src/messages/content.rs::is_empty`(:399) | 空字符串 / 空 blocks / 空 raw 内容须用 `MessageContent::is_empty()` 判空且禁止 trim 替代(纯空白字符串不算空);空历史 + 空内容 prompt 时短路 `push_done`;keepgoing 不注入 recall;cancel 与 stage error/interruption 可在 Receive 正常退出点之外终止;契约 ARC-KEEPGOING-001 |
| 改 turn fatal failure 分类/传递 | `src/session/exec/executor_helpers/v2_execute.rs` + `executor_helpers.rs` + `executor_helpers/collect.rs`;契约 DTO 在 `peri-acp-types/src/session.rs` | `classify_loop_terminal`;`internal_failure_terminal`;`ExecutionFailure::from_agent_error`;`ExecOutcome.failure` → `PromptResult.failure` | transcript flush 后只采样一次 cancel;forwarder JoinError 保留到 Phase 9,在提取 transcript/recall/compaction 后覆盖为 Internal terminal;单一终态同时决定 Prompt stop reason、`TurnEnded`、fatal failure 与 cascade;LLM/provider failure 保留脱敏限长原意和可选 HTTP status,其他内部错误使用安全文案;Completed 为已提交成功,其他非成功结果中 cancel 优先;契约 ARC-EVENT-001 / ARC-CANCEL-001 |
| 加工具(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 和顺序,再恢复 flags 选择可见内容;命令与普通执行共用 done 终态投影,取消返回及通知均为 cancelled,不确定提交仍按 Internal/reload 收尾 |
| /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 |
| 改工具执行分发 | `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 Down Expand Up @@ -64,7 +64,7 @@
| 压力计算与计划 | compact_v2/planner.rs + projection.rs | `plan_micro` 只规划 visible own history;`estimate_projection_chars` 跳过 excluded,已隐藏历史无重复收益 |
| Micro 执行(按 round 截断) | compact_v2/micro.rs | `micro_compact` |
| Smart 执行(废弃中,恒 false) | compact_v2/smart.rs | `smart_compact` |
| Full 执行 + re-inject | compact_v2/full.rs | `re_inject_v2`、`extract_file_info`、`extract_skill_names` |
| Full 执行 + re-inject | compact_v2/full.rs | `full_compact_inner`(结构化上下文摘要 + own reminder 排除)、`re_inject_v2`、`extract_file_info`、`extract_skill_names`;回归 `full_report_test.rs` |
| 配置 re-export | compact_v2/config.rs | `CompactConfig`(事实源 peri-acp-types)、`CONTINUATION_HINT` |
| 摘要 prompt 模板 | compact_v2/descriptions/ | summary_system_prompt.md / summary_user_prompt.md |

Expand Down
Loading
Loading