From 4ab0414d43c0dc047405b4c9bfaef64a086a0aba Mon Sep 17 00:00:00 2001 From: kris Date: Sat, 4 Apr 2026 12:22:23 +0800 Subject: [PATCH] docs: describe thread status sync runtime --- README.md | 3 +++ .../architecture/api_and_service_inventory_cn.md | 16 ++++++++++++++++ .../current_runtime_and_deploy_status_cn.md | 6 ++++++ 3 files changed, 25 insertions(+) diff --git a/README.md b/README.md index a8539ef..c3f414a 100644 --- a/README.md +++ b/README.md @@ -135,6 +135,8 @@ Android APK： - 当前新设备导入前台已经接通：Web `添加设备` 成功后会直接进入“导入项目”步骤；设备页详情里也可再次打开导入草稿。原生 Android 端同样已补 `DeviceImportDraftActivity`，可完成 `勾选 -> 预览决议 -> 应用导入` - 当前设备导入前台文案与状态卡已收口：会明确显示 `等待候选线程 / 等待勾选 / 建议已生成 / 已导入`，并在导入后回显真正落到会话首页的线程名 - 当前已导入设备也支持自动同步项目理解：绑定设备 heartbeat 发现活跃线程有新活动、或线程本身刚回写新结果时，都会自动排隐藏的主 Agent 理解任务，把项目目标、当前进度和技术架构回写到项目理解和项目记忆 +- 当前主 Agent 对活跃线程的同步已经升级成“线程状态文档 + 最近进展事件 + 关键时刻深拉”：heartbeat / thread reply 平时优先追加轻量进展事件，只有在线程首次理解、状态变薄、长时间未全量刷新或主 Agent 真正接手时，才重新触发全量理解 +- 当前 Web 和 Android 都已经提供线程状态只读入口：Web 可直接打开 `/conversations/[projectId]/thread-status`，Android 可在单线程 `会话信息` 中进入 `ThreadStatusActivity`，查看当前目标、阶段、进度、架构、阻塞、建议下一步，以及最近 5 条进展事件 - 当前 `dispatch_execution` 完成回写已补幂等：同一个执行单重复完成，不会再向群聊重复追加线程原始回复和主 Agent 汇总 - 当前当 heartbeat 同时携带旧 `projects` 和新 `projectCandidates` 时，服务端会优先走 `import draft`，不再绕过勾选/应用阶段直接把旧项目目录导入为聊天窗口 - 当前设备导入 `review` 已补 owner/admin 鉴权，并改成真正的异步审核链：`review` 只负责排队 `device_import_resolution` 任务并返回 queued 状态，等 local-agent 完成回写后才把决议写回草稿和会话账本 @@ -218,6 +220,7 @@ device-agent 当前职责： - `local-agent` 对 `conversation_reply` 当前会优先使用 `codex exec resume `，只有缺失真实线程引用时才退回 `--ephemeral` - `local-agent` 对 `dispatch_execution` 当前会按 `orchestrationBackendId` 分流：默认继续走 `codex exec resume`；当任务显式选择 `omx-team` 且本机 `omxEnabled + omxCommand/omxArgs` 可用时，会改走 `OMX Team Runtime` JSON 协议执行 - `local-agent` 当前的任务完成回写已通过 `RemoteRuntimeAdapter` 标准化，`conversation_reply / dispatch_execution` 的完成结果都会先归一到统一远程执行结果结构，再进入主 Agent 完成路由 +- `RemoteRuntimeAdapter` 当前还会拦截固定模式的线程内部环境提示（如“当前会话环境只读 / cwd 我可以在命令里指向 …”），并改写成系统失败提示，不再把这类脏文本直接回写到单聊或群聊 - `local-agent` 当前会先启动本地 `4317` 健康监听，再异步执行首次 heartbeat 和 task poll，避免控制面短暂阻塞时本地健康检查一起挂死 - Codex 项目/线程扫描当前已搬到 worker 线程执行，避免 `.codex/logs_1.sqlite` 和 `state_5.sqlite` 的同步扫描阻塞主线程 HTTP 响应 - 如果某个历史群聊里已经没有真实线程成员，当前不会再表现成“发了没反应”，而是会在群里追加一条 `system_notice`，提示用户先重新整理群成员 diff --git a/docs/architecture/api_and_service_inventory_cn.md b/docs/architecture/api_and_service_inventory_cn.md index 79dcaba..7b1ca6b 100644 --- a/docs/architecture/api_and_service_inventory_cn.md +++ b/docs/architecture/api_and_service_inventory_cn.md @@ -28,6 +28,7 @@ - `MainActivity` - `ProjectDetailActivity` - `ConversationInfoActivity` + - `ThreadStatusActivity` - `GroupInfoActivity` - `GroupCreateActivity` - `ProjectGoalsActivity` @@ -51,6 +52,7 @@ - 脏群会在主消息流上方直接显示 `去修复` 入口，并跳转到 `GroupInfoActivity` - 单线程会话支持按微信最新逻辑改线程名 - 当前已经支持从单线程会话发起独立群聊，群聊创建后作为新会话保留，原会话不升级 + - 当前单线程会话已经支持打开 `线程状态` 只读页，查看主 Agent 当前掌握的线程状态文档和最近进展事件 - 当前已经支持微信式消息转发：长按消息可直接 `转发 / 多选 / 复制 / 删除` - 当前多选模式会切换成微信式 `取消 + 已选数量 + 底部转发` 状态 - 当前统一使用 `ForwardTargetActivity` 选择目标会话，替换旧的备注转发主链 @@ -92,6 +94,7 @@ - 当前新增职责：递归扫描本机 `~/.codex/skills` 并同步到设备 Skill 接口 - 当前完成回写：`conversation_reply / dispatch_execution` 会先标准化成统一远程执行结果，再调用 `/api/v1/master-agent/tasks/[taskId]/complete` - 当前 `dispatch_execution` 会按 `orchestrationBackendId` 分流：默认走 `codex exec resume`，显式选择 `omx-team` 且本机配置可用时改走 `OMX Team Runtime` JSON 协议 +- 当前 `RemoteRuntimeAdapter` 还负责拦截固定模式的线程内部环境提示；命中后会直接改写成失败，避免把只读/cwd 这类脏文本写进聊天记录 ### 1.4 Caddy @@ -133,6 +136,7 @@ - `GET /conversations/[projectId]` - `GET /conversations/[projectId]/forward` - `GET /conversations/[projectId]/goals` +- `GET /conversations/[projectId]/thread-status` - `GET /conversations/[projectId]/versions` - `GET /threads/[threadId]` - `GET /devices/add` @@ -184,6 +188,18 @@ - 当前已最小接入 `OmxTeamBackendAdapter`，但默认关闭；Web 群聊详情页和原生群资料页已经可以在 `Boss Native` 与 `OMX Team` 间切换编排后端，OMX 不可用时会自动回退到默认后端并返回明确原因 - 当前仓库自带 `scripts/omx-team-smoke.mjs`，可用于本地和服务器验证 `OmxTeamBackendAdapter` 的 `dispatch_execution` JSON 协议 +### 3.1.2 线程状态文档与进展事件 + +- 状态字段： + - `threadStatusDocuments` + - `threadProgressEvents` +- 当前用途： + - 让主 Agent 优先读取线程状态文档和最近进展事件，而不是常态重复深问线程 + - 让 Web / Android 前台能直接查看线程的当前目标、阶段、进度、架构、阻塞、建议下一步 +- 当前同步策略： + - `heartbeat / thread reply` 平时优先写轻量进展事件 + - 首次理解、状态变薄、长时间未刷新或主 Agent 真正接手时，才补排隐藏全量理解任务 + ### 3.2 认证相关 #### `POST /api/auth/send-code` diff --git a/docs/architecture/current_runtime_and_deploy_status_cn.md b/docs/architecture/current_runtime_and_deploy_status_cn.md index 5a08db7..22798c2 100644 --- a/docs/architecture/current_runtime_and_deploy_status_cn.md +++ b/docs/architecture/current_runtime_and_deploy_status_cn.md @@ -33,6 +33,11 @@ - 当前仓库已自带 `scripts/claw-runtime-smoke.mjs` 作为本地 smoke runtime；在没有真实 `claw-code` 可执行文件时，可先用 `BOSS_CLAW_COMMAND=node` 与 `BOSS_CLAW_ARGS=scripts/claw-runtime-smoke.mjs` 验证整条链 - 当前 `oh-my-codex` 已以最小 `OmxTeamBackendAdapter` 形式接入执行底座，但默认关闭；当前已经接到 Web 群聊详情页 / 原生群资料页的编排后端选择卡，可在 `Boss Native` 与 `OMX Team` 间切换，OMX 不可用时会自动回退到默认后端并明确提示原因 - 当前仓库已自带 `scripts/omx-team-smoke.mjs` 作为本地 OMX smoke runtime；在没有真实 `oh-my-codex` 可执行文件时，可先用 `BOSS_OMX_COMMAND=node` 与 `BOSS_OMX_ARGS=scripts/omx-team-smoke.mjs` 验证 `dispatch_execution` 的真实执行 contract +- 当前主 Agent 对活跃线程的理解已经升级成“线程状态文档 + 最近进展事件 + 关键时刻深拉”：`projectUnderstanding` 不再是唯一输入，`threadStatusDocuments / threadProgressEvents` 已进入主 Agent prompt 主链 +- 当前 Web 和 Android 都已经有线程状态只读入口： + - Web：`GET /conversations/[projectId]/thread-status` + - Android：`ThreadStatusActivity` +- 当前 `conversation_reply / dispatch_execution` 的线程执行结果会先经过 `RemoteRuntimeAdapter` 标准化；如果线程返回的是固定模式的内部环境提示（如“当前会话环境只读 / cwd …”），会直接转成失败，不再把原文写回会话消息 本地已知运行方式： @@ -130,6 +135,7 @@ cd /Users/kris/code/boss - Web 与原生 Android 当前都已补上“新设备导入草稿 -> 勾选 -> 决议预览 -> 应用导入”的前台流程；已绑定生产设备继续保留 heartbeat 自动导入主链 - 当前设备导入前台的状态表达已经统一为：`等待候选线程 / 等待勾选 / 建议生成中 / 建议已生成 / 已导入`，并会回显最终导入的线程名 - 当前已导入设备也支持自动同步项目理解：绑定设备 heartbeat 发现活跃线程有新活动、或线程刚回写了新的执行结果时，系统会直接为这台设备上已导入的线程排隐藏的 `conversation_reply` 主 Agent 任务，回写最新的项目目标、当前进度、技术架构和下一步建议 +- 当前自动同步链路已经拆成两层：heartbeat / thread reply 默认只追加轻量 `threadProgressEvent`；只有在线程首次理解、文档信息过薄、距离上次全量刷新太久或主 Agent 真的要接手时，才补排隐藏的全量理解任务并更新 `ThreadStatusDocument` - 当前群资料页已补上“修复群成员”入口：当群里存在失效线程引用、`master-agent` 这类不可下发成员，或真实线程成员少于 2 个时，前台会明确提示并允许重新选择真实线程成员 - 当前原生聊天页也已前移“修复群成员”入口：脏群会在消息流上方直接显示 `去修复` 按钮，并跳转到群资料页完成成员替换 - 当前当 heartbeat 同时携带旧 `projects` 和新 `projectCandidates` 时，服务端会优先走 `deviceImportDraft`，不再绕过勾选/审核阶段直接自动导入聊天窗口