feat(acp-bridge): 事件驱动真流式 + 新版协议方法对齐#2
Merged
Conversation
与 ZCode 3.1.4 (CLI 0.14.8) 新版事件推送机制对齐, 解决 ACP bridge 的「伪流式」痛点, 并暴露新版协议方法。 核心改造: - ZCodeBackend: 从同步 readline 改为后台 reader 线程分发消息 (响应 → Queue; session/event → listener; notification → 通用队列) - 新增 EventStreamListener: 订阅 session/subscribe 事件流, 维护 seq 游标 - 新增 EventTranslator: model.streaming → TextDelta (真流式逐段推送), tool.updated → ToolCallNew/Update (实时工具状态) - _on_session_prompt 双模式: 优先事件驱动 (真流式), subscribe 失败 自动降级轮询 session/read (伪流式兼容旧版) - 5 个扩展方法 (非标准 ACP): session/fork, rewind, goal, compact, steer 测试: - test_event_translator.py: 15 项 EventTranslator 翻译逻辑单测 - test_projection_differ.py: 14 项 (现有, 不受影响) - 端到端验证: 真流式文本分 2-5 段到达, 工具调用实时状态推送 文档: - README: 双模式说明 + 扩展方法表 + 限制更新 - agent-help: acp_methods/events 同步标注 - CI: 增加 event translator 测试 job
测试发现 session/goal action=set 会启动内部 AI turn (异步), 它在 request() 返回后仍在后台运行。后续的 show/compact 会报 'Cannot manage goals while a prompt is running'。 修复: 新增 _wait_for_turn_idle() 方法, 在 goal set/replace 后用探测调用 (session/goal show) 重试直到 prompt lock 释放。实测内部 turn 耗时 10-45s+, 需要 60s 超时。 关键发现: projection.status=idle 不等于 prompt lock 释放 — status 很快 变 idle 但 lock 持续更久。必须用探测调用 (而非轮询 status) 来确认。 验证: Round 5 扩展方法 4/4 通过 (goal set+show, compact, steer)
新增 skills/zcode-bridge-guide/SKILL.md — 驱动 ZCode 的通用说明书: - 三种接入模式 (CLI/ACP/MCP) 完整使用指南 - 凭证配置 + 非交互 shell 坑 - 真流式 vs 伪流式双模式说明 - 扩展协议方法 (fork/rewind/goal/compact/steer) - 任务书模板、独立复核、成功判定、自检脚本 - 兼容 0.14.5 ~ 0.14.8+, 旧版自动降级说明 README 更新: - 新增「版本兼容性」章节: 三版本支持矩阵 + 降级行为 - 新增「Skill」章节: 安装方法 - 项目结构补充 skills/ 和 test_event_translator.py
P0 (必须修复): - 事件订阅时序竞态: 原代码先 session/send 再 subscribe+register, 导致 send→register 之间的 session/event (含 turn.completed) 被丢弃, 短 turn 会卡 120s 超时。修复: 改为先 subscribe+register 再 send。 P1 (强烈建议修复): - 事件停滞无降级: 原代码事件流停滞只打日志不收尾。修复: 连续 15s 无事件时用 session/read 确认 turn 状态, 若已 idle 则轮询收尾。 - _wait_for_turn_idle 超时伪装成功: 超时返回 False 但调用方忽略, 日志写'lock 已释放'。修复: 检查返回值, 超时时诚实记录警告。 - 文档错误码描述不准: 声称旧版扩展方法报 -32601, 实际 bridge 自己 实现了这些方法, 后端旧版错误会被包装为 -32603。修复文档描述。 - skill Python 示例 toolCall 字段错误: 用 update['toolCall'] 但实际 是扁平字段 toolCallId/status。修复示例。 P2 (可选改进): - CI 改 unittest discover, 避免手写测试文件列表
修复 Codex re-review 发现的 2 个 P1: 1. 停滞降级重复发事件: differ.diff() 不知道事件路径已发过 TextDelta/ tool 事件 (differ 的 _seen_message_ids 未在事件模式下更新), 会把完整 assistant message 当新内容重发。修复: 停滞收尾时不调 differ.diff(), 只做 _fetch_last_reply 兜底 (emitted_text 标记已覆盖去重)。 2. 停滞检查只做一次: stall_checked=True 后不再检查, 长 turn 完成但 turn.completed 丢失时仍卡 120s。修复: 改为每 15s 可重复检查 (last_stall_check 时间戳节流)。
P1.1: reader 线程死后 fail-fast - 原问题: reader 线程退出后无标志位, 后续 request() 全部卡满 timeout (慢速假死) - 修复: 新增 _reader_dead 标志, reader 退出时设 True + 清理等待中的响应队列; request() 入口检查标志快速失败; send() 的 BrokenPipe 也设标志 P1.2: batch 工具事件处理 - 原问题: tool.updated kind=batch 无处理, 若 zcode 只发 batch 不逐个发 result, 工具会永远卡在 in_progress - 修复: batch 分支遍历 toolCallIds, 为 scheduled 过的 id 补发 completed/failed P2 改进: - 文件头 docstring 更新 (旧的'MVP 非流式'描述改为'事件驱动真流式+双模式') - compact handler 补充注释说明不启动内部 turn - 新增 4 项测试: batch 完成/失败/未知ID过滤 + turn.completed totalTokens 优先 - 总测试数 29→33 审查来源: Claude Opus 4.8 (effort max) deep review
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
改动概述
与 ZCode 3.1.4 (CLI 0.14.8) 新版事件推送机制对齐，解决 ACP bridge 的「伪流式」痛点。
核心改造
解决的问题
测试
文档
不做（明确排除）