diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 5334996f6c..21b9e6e90a 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -182,6 +182,7 @@ export default defineConfig({ collapsed: true, items: [ { text: '项目架构', link: '/architecture' }, + { text: 'BTW 双循环设计（提案）', link: '/btw-dual-loop' }, { text: '源码开发', link: '/development' }, { text: 'Linux 开发环境', link: '/linux' }, { @@ -443,6 +444,10 @@ export default defineConfig({ collapsed: true, items: [ { text: 'Architecture', link: '/architecture' }, + { + text: 'BTW Dual-Loop Design (Proposal)', + link: '/btw-dual-loop', + }, { text: 'Source Development', link: '/development' }, { text: 'Linux Development', link: '/linux' }, { diff --git a/docs/en/dev/btw-dual-loop.md b/docs/en/dev/btw-dual-loop.md new file mode 100644 index 0000000000..aa7243c85f --- /dev/null +++ b/docs/en/dev/btw-dual-loop.md @@ -0,0 +1,105 @@ +--- +outline: deep +--- + +# BTW Dual-Loop Design + +This page records the direction and capability breakdown for [PR #28](https://github.com/Xero-Team/AstrBot/pull/28). That PR delivers documentation only. The loops, commands, and settings described below are proposed follow-up work, not features available in the current release. + +## Goal and Responsibilities + +BTW aims to let users keep talking while a longer task runs, check its status, and receive its result. Conversation and work reuse the existing Agent execution path with different responsibilities. + +| Loop | Responsibility | Intended capabilities | +| ------------ | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| Conversation | Understand requests, clarify requirements, handle requests within its abilities, and keep the interaction going | The model, tools, and Skills actually available to the current request | +| Work | Accept explicitly submitted tasks or future handoffs from conversation, track execution, and return results | Capabilities assigned to work, subject to existing authorization | + +The work loop is not a new permission level, and a handoff grants no additional permissions. Capability assignment determines what each loop can see. Task routing determines which loop handles a particular request. These concerns can progress separately. + +## Current Decisions + +- PR #28 retains this design document only. The prototype remains historical reference material; the parent Issue and Sub-issues link separate PRs for implementation and acceptance of each capability. +- Follow-up implementation starts from current master and reuses its message pipeline, Agent runners, tool catalog, and Skill snapshots. Superseded assembly and authorization logic from the prototype must not be copied back. +- The initial direction retains explicit entry and disabled defaults: `/work ` submits work. The prototype rule classifier is a reference candidate tested in its own experimental PR, not a predetermined production default. +- The intended later direction is: **routing belongs inside the conversation loop. The loop knows its available capabilities, handles requests it can fulfill, and hands requests that need work capabilities to the work loop.** +- Product integration of that routing direction is deferred. **Different classifiers belong in separate PRs, starting from the same baseline and tested separately under one evaluation protocol.** Results will inform the handoff contract and approach to adopt; these experiments do not block the other capability slices. + +The reference prototype is commit [`33ee103a62937db3e930c89ba47a648b75cc7772`](https://github.com/Xero-Team/AstrBot/commit/33ee103a62937db3e930c89ba47a648b75cc7772). In that version, `ConversationLoop.process()` applies rules or accepts an explicit work marker before the model call. It does not implement a conversation model deciding to hand off based on its own capabilities. + +## Capability Breakdown + +[Parent issue #122](https://github.com/Xero-Team/AstrBot/issues/122) tracks the following capabilities and dependencies. B1–B10 each have a non-draft feature PR; R1–R3 each have a separate draft classifier PR. B/R identifiers remain design indices, with links to the actual Issues and PRs. Each slice includes its settings, Dashboard interactions, tests, and bilingual documentation instead of splitting all frontend and backend work into separate tickets. This PR neither implements nor validates the acceptance requirements in the table. + +| Issue | PR | Sub-issue scope | Acceptance focus | +| ------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [B1 / #123](https://github.com/Xero-Team/AstrBot/issues/123) | [#136](https://github.com/Xero-Team/AstrBot/pull/136) (non-draft) | Opt-in dual-loop entry and ordinary conversation | Disabled mode preserves the current Agent path and capabilities; enabled mode admits ordinary requests to conversation; automatic-classifier experiments are not a prerequisite. | +| [B2 / #124](https://github.com/Xero-Team/AstrBot/issues/124) | [#139](https://github.com/Xero-Team/AstrBot/pull/139) (non-draft) | Explicit task entry with `/work ` | A registered built-in command receives the full task text; submission works with classification off; disabled work returns a clear message; command permissions and session LLM switches remain effective. | +| [B3 / #125](https://github.com/Xero-Team/AstrBot/issues/125) | [#137](https://github.com/Xero-Team/AstrBot/pull/137) (non-draft) | Background execution, concurrency, and lifecycle | Acknowledge receipt before background execution while conversation remains available; bound concurrency; verify pending, running, completed, failed, and cancelled states; reclaim tasks at runtime shutdown. | +| [B4 / #126](https://github.com/Xero-Team/AstrBot/issues/126) | [#138](https://github.com/Xero-Team/AstrBot/pull/138) (non-draft) | Result delivery and event resource release | Return results to the originating request through reply checks, decoration, and delivery; the acknowledgement must not prematurely end a WebChat request; release temporary files and event registrations at completion. | +| [B5 / #127](https://github.com/Xero-Team/AstrBot/issues/127) | [#140](https://github.com/Xero-Team/AstrBot/pull/140) (non-draft) | Work status and retention | `/work` and `/work status` report the latest task for the current profile and session; empty, terminal, and expired states are defined; profiles remain isolated and group-chat query scope is explained. | +| [B6 / #128](https://github.com/Xero-Team/AstrBot/issues/128) | [#141](https://github.com/Xero-Team/AstrBot/pull/141) (non-draft) | Model selection per loop | Conversation and work may choose different models; empty selections inherit the current choice; invalid or unavailable selections have defined behavior; disabling BTW preserves ordinary model selection. | +| [B7 / #129](https://github.com/Xero-Team/AstrBot/issues/129) | [#142](https://github.com/Xero-Team/AstrBot/pull/142) (non-draft) | Computer Use boundaries per loop | Conversation does not mount Computer Use; work may inherit or select `none`, `local`, or `sandbox`; handoffs retain the same restrictions and loop selection does not alter permissions. | +| [B8 / #130](https://github.com/Xero-Team/AstrBot/issues/130) | [#143](https://github.com/Xero-Team/AstrBot/pull/143) (non-draft) | Assign plugin LLM tools to loops | Select conversation, work, or both per plugin; the prototype defaults to work; main Agent and handoff behavior agree. Only LLM tools are affected, not plugin event handlers or the execution destination of explicit commands. | +| [B9 / #131](https://github.com/Xero-Team/AstrBot/issues/131) | [#144](https://github.com/Xero-Team/AstrBot/pull/144) (non-draft) | Assign MCP tools to loops by server | Tools from one MCP server follow a shared assignment; the prototype defaults to work; saved settings, main Agent, and handoff behavior agree while preserving MCP connection and authorization boundaries. | +| [B10 / #132](https://github.com/Xero-Team/AstrBot/issues/132) | [#145](https://github.com/Xero-Team/AstrBot/pull/145) (non-draft) | Skill visibility per loop | Ordinary Skills defaulted to both in the prototype; workspace Skills retain the work-loop and local-runtime boundary; prompts, `read_skill`, and declared tools use consistent filtering; reading a Skill does not require Shell permission. | +| [R1 / #133](https://github.com/Xero-Team/AstrBot/issues/133) | [#146](https://github.com/Xero-Team/AstrBot/pull/146) (draft) | Rule-classifier experiment PR | Use prototype keywords and deterministic rules as a reference; test boundaries, everyday queries, and mistakes when capabilities change; report results independently. | +| [R2 / #134](https://github.com/Xero-Team/AstrBot/issues/134) | [#147](https://github.com/Xero-Team/AstrBot/pull/147) (draft) | Separate model-classifier experiment PR | Call a model before conversation execution to choose a destination; measure classification quality and the latency and cost of the additional call without presuming this is the final architecture. | +| [R3 / #135](https://github.com/Xero-Team/AstrBot/issues/135) | [#148](https://github.com/Xero-Team/AstrBot/pull/148) (draft) | Capability-aware decision inside conversation, in its own PR | Let the conversation model handle or hand off requests based on available capabilities; measure unnecessary and missed handoffs and context continuity. This is the currently preferred direction to investigate. | + +### Dependencies and Delivery Order + +B1 defines the enablement boundary. B2–B5 together provide “submit → execute in the background → return results → inspect status.” An intermediate state that can acknowledge a task but cannot return its result is not a usable feature. These slices can be reviewed separately, but the first usable version needs the complete path. + +B6 and B7 define each loop's model and runtime. B8–B10 deliver capability assignment separately. Shared catalog filtering or configuration controls belong to the first slice that needs them. Acceptance covers BTW enabled and disabled, and both main Agent and handoff paths. + +R1–R3 are parallel alternatives with no dependency on one another; they are not a sequence of classifier implementations stacked on each other. Agree on a common baseline and evaluation protocol, then implement, test, and review each separately. Move all candidates to the same updated baseline when integration testing needs real work execution. Product integration remains a later decision after the comparison and after execution, delivery, and capability-assignment contracts are clear. + +## Routing Experiment Boundaries + +### Separate PRs and a Shared Evaluation Protocol + +R1–R3 are initial candidates whose scope can be refined in their Sub-issues. Each completed experiment is expected to contain one classifier implementation and its tests, recording the baseline commit, dataset version, capability fixtures, model, and parameters. R2/R3 currently contain experiment plans only. Establish common cases and the evaluation harness first so implementations do not select different datasets to demonstrate success. + +Run the same offline cases in each PR, followed by the same integration scenarios on a shared working dual-loop baseline. Deterministic tests check contracts; model trials separately report variation across repeated runs. Report both forms of evidence separately. Explicit `/work` entry is a control baseline for every approach, not a fourth classifier. + +The parent Issue collects results, costs, and trade-offs from each PR. Do not merge all candidates together before comparison or add a production framework for switching classifiers in advance. Review integration of the selected approach separately; retain unselected implementations as experiment records. + +### Capability Visibility + +Conversation should see the resolved capabilities of the current request, not merely the names of every installed tool. Experiment inputs include the current model, the tool catalog after configuration and Persona filtering, the Skill snapshot, runtime restrictions, and the range of tasks that work can accept. + +Use current `astrbot/core/tool_catalog.py`, main-agent catalog assembly, and Skill snapshots as the sources of truth. Avoid maintaining another capability list that can drift. Appearance in a catalog or Skill does not grant execution permission; the existing authorization service still decides at execution time. + +### Questions to Resolve + +- Can conversation make a different handling or handoff decision for the same request when its available capabilities change? +- Can it distinguish “needs work capabilities,” “lacks authorization,” “needs clarification,” and “neither loop can complete this,” instead of handing off every failure? +- Should handoff happen before the first action, or also after execution reveals a capability gap? If the latter is useful, how will it avoid repeating steps that already produced side effects? +- Which context, completed steps, and expected results must accompany a handoff for work to continue the same task? + +These are experiment questions. This document does not prescribe a new tool interface, prompt format, or routing service. + +### Cases and Measurements + +Cases should cover ordinary chat, queries solvable with available tools, workspace or external execution, mixed requests, incomplete requirements, unavailable tools, insufficient permissions, and requests neither loop can fulfill. Pair the same request with different capability sets to test whether decisions actually depend on capability availability. + +Measure unnecessary and missed handoffs, task completion, appropriate clarification and refusal, added latency, model calls and token cost, repeated handoffs, and duplicate execution. Start with fixed data and simulated tools rather than enabling routing in production as an experiment. State acceptance thresholds before evaluation; retaining explicit entry is a valid outcome. + +## Implementation and Acceptance Constraints + +- **Current path:** Reuse `AgentRequestSubStage`, the current tool catalog, and Skill snapshots. Assess external Agent runners separately: local-runner control over models and tools does not automatically apply to a remote service. +- **Authorization:** Preserve current configuration scope, role, and entry rules. BTW markers, routing decisions, and Skill declarations are not authorization credentials. This design does not restore the prototype's proposed BTW-specific elevation mechanism. +- **Request identity:** WebChat acknowledgements, `run_started`, per-model-call `agent_stats`, streamed results, completion, and interrupts stay attached to the original `message_id`. Concurrent tasks must not collapse into a session-wide busy flag. +- **Lifecycle:** Runtime owns background tasks and cancellation propagates. Verify cancellation while queued, execution and delivery failure, configuration reload, and shutdown cleanup. Terminal-state retention must not expire active tasks. +- **Configuration:** Use the current profile-save path and one configuration shape, with disabled defaults. Do not add compatibility for old prototype dictionaries. The UI must explain that ordinary Skills default to both while plugin and MCP tools default to work. +- **Verification:** Use the nearest existing backend and Dashboard tests and add regressions for each observable behavior. Background integration requires the real scheduler and WebChat protocol; a successful mock-dispatcher test does not establish end-to-end behavior. +- **Docs and interfaces:** Update command, configuration, and topic documentation in both languages as features land. Synchronize OpenAPI and generated artifacts only when the HTTP contract actually changes; this design does not require new HTTP endpoints. + +## Parent Issue and Non-goals + +[Parent issue #122](https://github.com/Xero-Team/AstrBot/issues/122) uses native Sub-issues to track B1–B10, dependencies, acceptance, and the R1–R3 experiment PRs and results. Feature PRs are stacked by dependency so each diff contains one capability. The three classifier drafts use the same feature baseline and are tested separately. R1 extracts the prototype's existing rules; the prototype contains no R2/R3 model classifier implementation, so those drafts initially provide experiment plans and explicit outstanding validation. Product integration of classification remains deferred. + +This increment excludes persistent or resumable work, cross-device scheduling, an automatic retry or rollback platform, a multi-task management page, and enabling automatic routing by default in production. The prototype's `pyupgrade` adjustment is separate repository maintenance, outside the BTW feature scope. + +Current behavior is documented in [Architecture](./architecture.md), [Computer Use](../use/computer.md), and [Skills](../use/skills.md). Implementation and acceptance are tracked in the linked Issues and PRs; this overview does not replace implementation review. diff --git a/docs/zh/dev/btw-dual-loop.md b/docs/zh/dev/btw-dual-loop.md new file mode 100644 index 0000000000..f8af0d3f8d --- /dev/null +++ b/docs/zh/dev/btw-dual-loop.md @@ -0,0 +1,105 @@ +--- +outline: deep +--- + +# BTW 双循环设计说明 + +本文记录 [PR #28](https://github.com/Xero-Team/AstrBot/pull/28) 的设计方向和功能拆分。该 PR 仅交付文档；下文中的循环、命令和配置是后续开发范围，不代表当前版本已经提供这些功能。 + +## 目标与职责 + +BTW 希望让用户在较长的工作任务执行期间继续对话，并能查询任务状态、接收结果。对话和工作复用现有 Agent 执行路径，各自承担不同职责。 + +| 循环 | 职责 | 预期能力范围 | +| -------- | -------------------------------------------------------------- | ---------------------------------------- | +| 对话循环 | 理解请求、澄清需求、完成自身能力范围内的请求，保持交互连续 | 当前请求实际可用的模型、工具与 Skill | +| 工作循环 | 承接显式提交或未来经对话循环转交的任务，管理执行状态并回送结果 | 配置分配给工作的能力，继续受现有授权约束 | + +工作循环不是新的权限级别，转交也不授予额外权限。能力按循环分配，决定模型可以看见什么；任务路由决定某次请求交给哪个循环处理。这两个问题分别推进。 + +## 当前决策 + +- PR #28 只保留这份设计说明，原型代码作为历史参考；总 Issue 与 Sub-issues 已关联独立 PR，分别跟踪各项能力的实现与验收。 +- 后续实现从当前主干出发，复用现有消息流水线、Agent runner、工具目录和 Skill 快照；不直接搬回原型中已经过时的装配或授权逻辑。 +- 初期保持显式入口与默认关闭原则：通过 `/work ` 提交工作。原型规则分类器保留为对照方案，在独立实验 PR 中测试，不预先选为产品默认路由。 +- 期望的后续方向是：**路由判断并入对话循环；对话循环知道自身实际可用的能力，能完成的自行处理，需要工作能力的再转交工作循环。** +- 上述路由方向暂缓产品接入。**不同分类器分别提交独立 PR，从相同基线出发，按同一评估约定分开测试。** 根据结果再确定转交契约与采用方案；这些实验不阻塞其余能力的拆分。 + +原型参考为提交 [`33ee103a62937db3e930c89ba47a648b75cc7772`](https://github.com/Xero-Team/AstrBot/commit/33ee103a62937db3e930c89ba47a648b75cc7772)。该版本由 `ConversationLoop.process()` 在模型调用前执行规则分类或接收显式工作标记，并没有实现由对话模型根据自身能力作出转交判断。 + +## 功能拆分 + +[总 Issue #122](https://github.com/Xero-Team/AstrBot/issues/122) 汇总以下功能与依赖。B1–B10 各有一个普通功能 PR；R1–R3 分别对应独立的分类器草稿 PR。表中的 B/R 标识保留为设计索引，链接指向真实 Issue 与 PR。每项同时包含相应配置、Dashboard 交互、测试与中英文说明，不另拆一组纯前端或纯后端任务。表中的验收要求尚未在本 PR 中实现或验证。 + +| Issue | PR | 子 Issue 范围 | 独立验收重点 | +| ------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| [B1 / #123](https://github.com/Xero-Team/AstrBot/issues/123) | [#136](https://github.com/Xero-Team/AstrBot/pull/136) (普通 PR) | 默认关闭的双循环接入与普通对话 | 关闭时保持当前 Agent 路径和能力；开启后普通请求进入对话循环；自动分类器实验不成为本项的前置条件。 | +| [B2 / #124](https://github.com/Xero-Team/AstrBot/issues/124) | [#139](https://github.com/Xero-Team/AstrBot/pull/139) (普通 PR) | 显式工作任务入口 `/work ` | 使用正式内置命令身份接收完整任务文本；分类器关闭仍可提交；工作关闭时给出明确提示；遵守命令权限和会话 LLM 开关。 | +| [B3 / #125](https://github.com/Xero-Team/AstrBot/issues/125) | [#137](https://github.com/Xero-Team/AstrBot/pull/137) (普通 PR) | 后台工作执行、并发与生命周期 | 先确认接收，再后台执行，期间可以继续对话；限制并发；排队、运行、完成、失败、取消状态可验证；关闭运行时会收回任务。 | +| [B4 / #126](https://github.com/Xero-Team/AstrBot/issues/126) | [#138](https://github.com/Xero-Team/AstrBot/pull/138) (普通 PR) | 工作结果回送与事件资源释放 | 结果回到原请求，经过回复内容检查、装饰和发送；确认消息不提前结束 WebChat 请求；最终清理临时文件和事件注册。 | +| [B5 / #127](https://github.com/Xero-Team/AstrBot/issues/127) | [#140](https://github.com/Xero-Team/AstrBot/pull/140) (普通 PR) | 工作状态查询与保留 | `/work` 与 `/work status` 查询当前配置、当前会话的最新任务；空状态、终态和过期行为明确；配置之间不串状态，界面说明群聊查询范围。 | +| [B6 / #128](https://github.com/Xero-Team/AstrBot/issues/128) | [#141](https://github.com/Xero-Team/AstrBot/pull/141) (普通 PR) | 每个循环独立选择模型 | 对话与工作可选择不同模型，空值继承当前选择；选错或不可用时的行为明确；关闭 BTW 不改变普通模型选择。 | +| [B7 / #129](https://github.com/Xero-Team/AstrBot/issues/129) | [#142](https://github.com/Xero-Team/AstrBot/pull/142) (普通 PR) | 每个循环的 Computer Use 边界 | 对话循环不挂载 Computer Use；工作循环可继承或选择 `none`、`local`、`sandbox`；handoff 保持相同限制，循环选择不改变权限。 | +| [B8 / #130](https://github.com/Xero-Team/AstrBot/issues/130) | [#143](https://github.com/Xero-Team/AstrBot/pull/143) (普通 PR) | 插件 LLM 工具按循环分配 | 按插件配置对话、工作或两者；原型默认工作；主 Agent 与 handoff 一致。只影响 LLM 工具，不改变插件事件处理器或显式命令的执行归属。 | +| [B9 / #131](https://github.com/Xero-Team/AstrBot/issues/131) | [#144](https://github.com/Xero-Team/AstrBot/pull/144) (普通 PR) | MCP 工具按服务器分配循环 | 同一 MCP 服务器的工具遵循统一分配；原型默认工作；配置保存、主 Agent 与 handoff 一致，沿用 MCP 连接和授权边界。 | +| [B10 / #132](https://github.com/Xero-Team/AstrBot/issues/132) | [#145](https://github.com/Xero-Team/AstrBot/pull/145) (普通 PR) | Skill 按循环可见 | 普通 Skill 原型默认两者；工作区 Skill 保留工作循环与本地运行时边界；提示词、`read_skill` 和声明工具使用一致的筛选结果；读取 Skill 不要求 Shell 权限。 | +| [R1 / #133](https://github.com/Xero-Team/AstrBot/issues/133) | [#146](https://github.com/Xero-Team/AstrBot/pull/146) (草稿) | 规则分类器实验 PR | 以原型关键词和确定性规则为对照，验证词边界、日常查询和能力变化时的误判；独立记录结果。 | +| [R2 / #134](https://github.com/Xero-Team/AstrBot/issues/134) | [#147](https://github.com/Xero-Team/AstrBot/pull/147) (草稿) | 独立模型分类器实验 PR | 在对话执行前单独调用模型判断去向，测量分类效果及额外调用的时延、成本；不预设它是最终架构。 | +| [R3 / #135](https://github.com/Xero-Team/AstrBot/issues/135) | [#148](https://github.com/Xero-Team/AstrBot/pull/148) (草稿) | 对话循环内能力感知实验 PR | 对话模型基于当前可用能力自行处理或转交，验证误转交、遗漏和上下文延续；这是当前倾向重点验证的方向。 | + +### 依赖与交付顺序 + +B1 定义启用边界。B2–B5 共同完成“提交 → 后台执行 → 回送结果 → 查询状态”的体验，不能把仅能确认接收、无法回送结果的中间状态作为可用功能交付。它们可以分别评审，首个可用版本需要完成这条链路。 + +B6、B7 明确每个循环的模型与运行环境。B8–B10 分别交付可用能力的分配；共享的目录筛选或配置控件随首个使用它的切片引入。每项验收同时覆盖 BTW 开启与关闭、主 Agent 与 handoff。 + +R1–R3 是平行方案，互不依赖，不串成前一个分类器改完再开发下一个的提交链。先约定共同基线和评估方法，各自实现、测试和评审；需要真实工作循环的集成评估，再共同更新到同一个基线。产品接入须等实验结论及工作执行、结果回送、能力分配契约明确后另行决定。 + +## 路由实验的边界 + +### 独立 PR 与共同评估约定 + +R1–R3 是首轮候选拆法，可在各子 Issue 中调整。每项完成的实验应包含一种分类器实现及其测试，写明基线提交、样例版本、能力集合、模型与参数。R2/R3 目前仅包含实验方案。共同样例和评估脚手架应先固定，避免每个实现选择不同的数据证明自己有效。 + +各 PR 分别执行相同的离线样例，随后在共同的可用双循环基线上执行相同的集成场景。确定性测试用于验证契约，模型试验另行记录重复运行的波动；两类结果分别报告。显式 `/work` 是所有方案的控制基线，不作为第四种分类器。 + +总 Issue 汇总各 PR 的结果、成本和取舍。完成比较前不把多个候选整包合入，也不先增加生产环境的多分类器切换框架。选型后的产品接入单独评审，未采用的实现保留为实验记录。 + +### 能力可见性 + +对话循环应看到本次请求实际解析出的能力，而不是所有已安装工具的名称。研究输入包括当前模型、配置与 Persona 筛选后的工具目录、Skill 快照、运行环境限制，以及工作循环可承接的范围。 + +实现时以当前的 `astrbot/core/tool_catalog.py`、主 Agent 的目录装配和 Skill 快照为事实来源，避免维护另一份容易漂移的能力清单。工具出现在目录或 Skill 中不等于获得执行授权；执行时仍由现有授权服务判断。 + +### 要回答的问题 + +- 同一个请求在能力配置不同的情况下，对话循环能否作出相应的处理或转交判断？ +- 能否区分“需要工作能力”“缺少授权”“需要用户澄清”和“两边都无法完成”，避免把所有失败都转交？ +- 转交发生在首次执行前，还是允许处理过程中发现能力缺口后转交？后一种方式如何避免重复执行已经产生副作用的步骤？ +- 转交需要携带哪些上下文、已完成步骤和结果期望，才能让工作循环继续完成同一个任务？ + +这些是实验问题，不在本文中预先固定新的工具接口、提示词格式或路由服务。 + +### 样例与指标 + +样例至少覆盖纯聊天、可用工具即可完成的查询、需要工作区或外部执行的任务、混合请求、需求不完整、工具离线、权限不足，以及两边都不能完成的请求。相同请求需要搭配不同能力集合，检验判断是否真的依赖能力。 + +记录误转交、漏转交、任务完成率、澄清与拒绝是否合适、额外时延、模型调用和 token 成本、重复转交与重复执行。先使用固定数据和模拟工具验证，不以线上默认开启作为实验方法。门槛应在评估前说明，实验结论可以是继续保持显式入口。 + +## 实现与验收约束 + +- **当前路径：** 复用 `AgentRequestSubStage`、当前工具目录与 Skill 快照。第三方 Agent runner 的模型、工具可控范围需单独确认，不宣称本地 runner 的能力隔离自动覆盖外部服务。 +- **授权：** 沿用当前配置范围、角色和入口规则。BTW 标记、路由结果或 Skill 声明都不能充当授权凭证；本设计不恢复原型曾讨论的 BTW 专用提权机制。 +- **请求身份：** WebChat 的确认、`run_started`、每次模型调用的 `agent_stats`、流式结果、最终结束与中断始终归属原 `message_id`；并发任务不能退化为会话级忙碌标志。 +- **生命周期：** 后台任务由运行时拥有；取消继续传播。验证排队期间取消、执行失败、投递失败、配置重载和关闭时的状态与清理；活跃任务不能按终态保留时间过期。 +- **配置：** 采用当前配置档保存路径和单一配置形状，默认关闭；不为原型旧字典格式增加兼容层。普通 Skill 默认两者与插件/MCP 默认工作的差异必须在界面中可见。 +- **验证：** 每项使用最接近的现有单测和 Dashboard 测试，并为其可观察行为补回归覆盖。后台集成必须验证真实调度器和 WebChat 协议，不能仅凭模拟 dispatcher 的成功路径宣称整链可用。 +- **文档与接口：** 功能落地时同步更新命令、配置及专题的中英文文档。只有确实改变 HTTP 契约时才同步 OpenAPI 和生成物；当前设计不要求新增 HTTP 接口。 + +## 总 Issue 与非目标 + +[总 Issue #122](https://github.com/Xero-Team/AstrBot/issues/122) 通过原生 Sub-issues 汇总 B1–B10 的进度、依赖和验收，以及 R1–R3 的实验 PR 与结果。功能 PR 按依赖叠放，每个 PR 的差异仅包含本项功能；三个分类器草稿使用同一功能基线，分别测试。R1 提取原型已有规则实现；原型没有 R2/R3 的模型分类器实现，因此这两个草稿先承载实验方案与未完成的验证要求。分类器产品接入仍暂缓。 + +本轮不包含工作任务持久化与断点续跑、跨设备工作调度、自动重试或回滚平台、多任务管理页面，以及生产环境默认开启自动路由。原型中的 `pyupgrade` 调整属于独立仓库维护，也不属于本文的 BTW 功能范围。 + +当前运行行为仍以[项目架构](./architecture.md)、[Computer Use](../use/computer.md)与 [Skills](../use/skills.md) 为准。实现与验收通过已关联的 Issue 和 PR 跟踪；本文不替代实现评审。