first commit

async-agent-lab/docs/presentation-plan.md

@@ -0,0 +1,96 @@
+# Agent 为什么能边问边做
+
+约 30 分钟的内部分享。主讲稿是本地 HTML 网页，由讲者投屏并手动翻页。四张演示页各有可运行的核心实现、任务指令、工具表和实时轨迹。讲者可以在任一页启动、操作和重跑。左侧展示这次运行走的源码，右侧展示轨迹与操作。当前订单原型的运行说明和实测结果见[原型讲稿](share.md)。
+
+## 讲述顺序
+
+| 时间 | 页面 | 投屏内容 |
+| --- | --- | --- |
+| 0–3 分钟 | Codex 为什么能边问边做 | 从问题卡还开着、Agent 已经继续查代码的现象引入，简短对照 AiWork 的阻塞提问和 OpenCode 的后台 Shell。 |
+| 3–6 分钟 | 先给 Agent 四个基础工具 | 用 `read` 展示工具的名字、参数、执行函数和结果。带过 `grep`、`write`、`bash` 各自在周报里做什么。 |
+| 6–10 分钟 | 最小 Agent 与同步 Bash | 展示完整的小 Loop，现场查单仓库的提交，看到 Bash 的结果进入下一次请求。 |
+| 10–15 分钟 | 后台 Bash | 现场后台收集跨仓库证据，跟一个 `job_id` 看回执、进程退出和模型请求。随后对照 OpenCode V2 的源码和 #63024。 |
+| 15–19 分钟 | 阻塞提问 | 用户提交答案前停在工具调用。答完之后，看下一次模型请求带上原工具结果。对照 AiWork 所用的 OpenCode 实现。 |
+| 19–26 分钟 | 异步提问 | 问题还挂着，Agent 已经在取证。答完两道题，打开真实请求和最终周报。对照 Codex 的回执和答复消息。 |
+| 26–30 分钟 | 后台工作如何回到 Loop | 用一张通信图连接本地进程、子 Agent 和远端任务，回到 AiWork 的「立即插入」与阻塞提问。 |
+
+## 基础工具页
+
+这一页先讲清楚工具契约。模型收到工具定义并返回工具名和参数，运行时查找执行函数。执行结果用原调用 ID 关联，再交回模型。投屏上用一份简短的 `read` 定义和一次调用展示这条链路。下一页再讲 Loop 怎样把它重复起来。
+
+| 工具 | 最小输入 | 周报场景中的用途 |
+| --- | --- | --- |
+| `grep` | 搜索词、目录 | 在已定位的仓库中找相关文件、符号或测试。返回路径和匹配行。 |
+| `read` | 路径，可选行范围 | 读取相关源码、文档和取证摘要。 |
+| `write` | 路径、内容 | 在本次演示的工作目录里写 `weekly-report.md` 等产物。 |
+| `bash` | 命令 | 执行实际的 `git log`、`git show` 或本地取证命令，返回退出状态和输出。 |
+
+四个工具提供给各页的 Agent。后台 Bash 页给 `bash` 增加后台执行能力，两张提问页各自注册对应的 `question`。每个场景的任务决定会用到哪些工具。最小 Agent 一页可以只调用一两项，把注意力留给工具结果如何进入下一次请求。
+
+## 四个独立的实跑场景
+
+每张演示页有自己的核心入口、系统提示词和任务。共用网关调用、基础工具执行和轨迹采集。每次启动都有干净的周报工作目录和独立的轨迹。
+
+### 最小 Agent 与同步 Bash
+
+> 查 AiWork 本周的 Git 提交，归纳几项研发进展。
+
+左侧展示消息历史、`callModel()`、工具分发和把结果追加进历史的完整小循环。右侧可以依次找到模型的 `tool_calls`、Bash 的退出结果，以及下一次请求中与 `tool_call_id` 匹配的 `tool` 消息。模型最后给出一份简短总结。
+
+### 后台 Bash
+
+> 在后台从本机 Agent 会话定位本周活跃的仓库，再核对 Git 提交。等待期间先列出周报结构。收到结果后，汇报找到了哪些仓库和工作线索。
+
+后台子进程实际运行本周证据收集命令。工具先返回 `job_id`，子进程退出后，运行时把退出码和取证摘要放进会话收件箱。Loop 忙时在下一步接收，空闲时由收件箱唤醒。投屏只跟一个 `job_id`，逐条查看**启动回执、实际退出和结果进入模型请求**。取证命令很快完成时，依然可以用这三个时点讲清回传。AiWork 的回归测试用作同机制的口头例子。
+
+### 阻塞提问
+
+> 整理本周研发周报。先问我下周优先推进什么，再开始查本周工作。
+
+工具在 `await answer` 处等待。讲者留出一段答题时间，右侧显示问题待答和请求计数。提交后，答案成为原工具调用的结果，随后才发出取证所需的模型请求。
+
+### 异步提问
+
+> 整理本周研发周报。先问我下周优先推进什么，等待期间继续收集本周工作。归纳出候选工作项后，让我选择保留哪些，最后写成周报。
+
+工具先返回 `accepted` 和 `question_id`。讲者可以晚一点答，让观众看到等待期间实际发出的取证请求。回答带问题 ID 进入会话，右侧可追到携带它的实际模型请求。候选收齐后显示可勾选的工作项，默认全选，由讲者剔除。最终用 `write` 生成 `weekly-report.md`，检查「本周工作内容」和「下周工作计划」分别使用了哪次回答。
+
+## 周报取证
+
+1. 按上海时区的本周时间窗口，从 Codex、DSH 和 OpenCode 的本地会话找活动时间和工作目录。本周继续使用的旧会话也可提供线索。
+2. 用 Git 解析目录对应的仓库，归并共享历史的 worktree。按本周和已确认的 Git 作者查看提交，需要时用 `git show` 核对实际改动。
+3. 按工作成果合并候选。已有可核对产出的调研、设计和原型也可以入选。需要补充上下文时，从相关会话或产物读取必要片段。
+4. 页面显示实际发现的仓库和候选项。由讲者确认取舍后写入周报。
+
+证据采集用一个本地命令完成会话格式解析，Agent 通过 Bash 调用，并继续用 Git、`grep` 和 `read` 核对具体工作。会话线索用于定位，成果描述以提交、产物或实际验证结果为依据。取证只读，生成文件写入本次演示的工作目录。
+
+## 运行轨迹
+
+右侧参考截图中的事件轨、事件列表和详情结构。默认优先显示当前页讲解所需的关键事件，用「发送方 → 接收方、收到什么、时间」呈现。点击事件可查看对应请求体、模型返回或工具输入输出。问题卡和操作按钮也在当前页。
+
+| 记录对象 | 采集位置和关联方式 |
+| --- | --- |
+| 模型请求与返回 | 在真正发送 HTTP 请求的位置采集实际序列化的请求体，按请求编号和发送尝试关联 HTTP 状态与返回内容。凭据留在传输层。 |
+| 工具执行和后台进程 | 按 `call_id` 关联工具参数与结果，按 `job_id` 关联启动回执、进程退出和完成通知。 |
+| 收件箱投递 | 记录答复或完成通知何时入箱、何时加入历史，以及哪一次真实模型请求携带了它。 |
+| 网页答复 | 按 `question_id` 关联发问、用户提交、工具返回或答复入箱。 |
+
+轨迹由各页的实际运行产生，按事件顺序排列。同一毫秒发生的回执和投递仍可逐条查看。共用的渲染器消费这些事件，会话正文和问答交互可沿用现有 React 组件。
+
+## 对照产品源码
+
+在对应演示后放短源码片段，围绕刚看到的轨迹定位实现。
+
+- **OpenCode V2 的后台 Bash**展示如何先返回后台回执，再通过 `sessions.synthetic` 交付退出结果。#63024 在开启实验开关时，把超过前台等待预算的同一进程转到后台，复用完成通知。 [后台分支](https://github.com/anomalyco/opencode/blob/v2.2.7/packages/core/src/tool/plugin/shell.ts#L234-L247) · [完成通知](https://github.com/anomalyco/opencode/blob/v2.2.7/packages/core/src/tool/plugin/shell.ts#L150-L173) · [#63024](https://github.com/anomalyco/opencode/pull/63024)
+- **AiWork 所用的 OpenCode 1.18.18**展示 `question.ask` 等待，以及 `question.reply` 解除等待。 [问答实现](https://github.com/anomalyco/opencode/blob/v1.18.18/packages/opencode/src/question/index.ts#L104-L131)
+- **Codex CLI 0.167.1**展示 `request_user_input_async` 先返回 `accepted`，以及之后的模型请求怎样携带带有问题 ID 的用户答复。 [工具源码](https://github.com/openai/codex/blob/rust-v0.167.1/codex-rs/core/src/tools/handlers/request_user_input_async.rs#L131-L147) · [请求快照](https://github.com/openai/codex/blob/rust-v0.167.1/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap#L38-L50)
+
+结尾用同一张通信图说明，子 Agent 可以结束自己的 Loop 后向父会话报告结果，远端任务可以通过任务 ID 轮询或回调交付。 [场景调研](../../research/async-tool-calling-survey.md)
+
+## 现场验收
+
+- 主讲稿可在浏览器投屏、手动翻页。演示页上的代码和关键轨迹能同屏读清，可在原地启动和重跑。
+- `grep`、`read`、`write` 和 `bash` 都能执行真实操作。同步场景可沿工具调用 ID 追到下一次模型请求。
+- 后台 Bash 可沿任务 ID 从回执追到进程退出，再追到携带完成通知的模型请求。
+- 两种提问用独立实跑比较。阻塞版答题前停在工具调用。异步版答题前能继续发起取证请求，提交后可找到携带答复的实际请求。
+- 最后一段从多个仓库归纳候选，实际写出周报。保留项和下周优先事项与讲者的回答一致。