From 1b97dff3cac1b6369fae8c4f3b07e051da24a116 Mon Sep 17 00:00:00 2001 From: Wenchi Pan Date: Sun, 17 May 2026 15:49:28 +0800 Subject: [PATCH 1/3] docs: add auto-dispatch for agents prd --- docs/prd/auto-dispatch-agents.md | 157 +++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 docs/prd/auto-dispatch-agents.md diff --git a/docs/prd/auto-dispatch-agents.md b/docs/prd/auto-dispatch-agents.md new file mode 100644 index 0000000..6c9b256 --- /dev/null +++ b/docs/prd/auto-dispatch-agents.md @@ -0,0 +1,157 @@ +# PRD: 智能体自动派发模式（Auto-Dispatch for Agents） + +> 对应 GitHub Issue：[keting/half#109](https://github.com/keting/half/issues/109) + +## 背景 + +当前 HALF 平台的任务派发完全依赖人工操作：系统生成 prompt 后，由操作人手动复制、粘贴给 agent，再等待 agent 将结果写回 git 仓库。这种 Human-in-the-Loop 模式对于必须通过订阅 UI 使用的 agent 是合理的，但对于支持 API 调用的 agent，每次手动介入会显著降低效率，无法实现无人值守的连续执行。 + +--- + +## 目标 + +在不破坏现有手动派发流程的前提下，为 HALF 引入**自动派发**能力，使配置了 API 凭证的 agent 能够在任务就绪时无需人工干预地自动执行。 + +--- + +## 核心概念 + +### 智能体执行模式 + +每个 agent 实例（非 agent 类型）拥有一个**执行模式**字段： + +| 模式 | 含义 | 默认行为 | +|---|---|---| +| **手动模式**（Manual） | 沿用现有流程，系统生成 prompt，操作人手动复制粘贴 | 默认 | +| **自动模式**（Auto） | 系统在任务就绪时自动调用外部 AI API 执行，无需人工介入 | 需配置 API 凭证后方可激活 | + +--- + +## 用户故事 + +**US-1 管理员/用户配置自动模式 agent** +作为一名用户，我可以在"智能体"页面为某个 agent 开启自动模式，填写 API 凭证，并选择调用格式，保存后该 agent 即可被自动派发。 + +**US-2 项目负责人查看 agent 模式** +作为项目负责人，在选择参与 agent 时，我可以看到每个 agent 的模式标签（"自动"或"手动"），以便了解哪些 agent 需要人工介入。 + +**US-3 自动任务无需操作** +作为项目负责人，当一个项目的所有 agent 均为自动模式时，计划 finalize 后任务将按 DAG 依赖顺序自动推进，我无需手动操作。 + +**US-4 混合模式项目** +作为项目负责人，项目中可以同时存在自动模式和手动模式的 agent。自动 agent 的任务由系统自动执行，手动 agent 的任务仍然在界面上等待我手动派发，两者互不干扰。 + +--- + +## 功能需求 + +### FR-1 Agent 执行模式配置（"智能体"页面） + +**FR-1.1** 创建或编辑 agent 时，提供"执行模式"选项：手动（默认）或自动。 + +**FR-1.2** 当选择"自动"时，需展示并要求填写以下字段： + +| 字段 | 说明 | 必填 | +|---|---|---| +| API Base URL | API 服务地址，如 `https://api.openai.com/v1` | 是 | +| API Key | 鉴权密钥 | 是 | +| API 格式 | 单选：OpenAI Chat Completions / Anthropic Messages | 是 | + +**FR-1.3** API Key 在界面上以密码框形式展示（`****`），不允许明文回显。编辑时可选择"重新设置"以覆盖，或留空以保持原值不变。 + +**FR-1.4** agent 列表卡片上以标签形式展示执行模式：自动模式显示 `自动` 标签，手动模式不显示（沿用当前样式）。 + +**FR-1.5** 切换模式时需要确认提示：从自动切换回手动时，提示"切换后现有 API 凭证将被清除，确认继续？"。 + +**FR-1.6** API 凭证（base_url、api_key）存储在 Agent 实例层，在所有引用该 agent 的项目中共享。 + +--- + +### FR-2 项目页面 agent 选择 + +**FR-2.1** 项目选择参与 agent 的界面中，在 agent 名称旁以标签展示其执行模式（"自动"/"手动"），仅供查看，不可在项目页面修改。 + +**FR-2.2** 无需其他改动，项目页面的 agent 选择逻辑保持不变。 + +--- + +### FR-3 自动派发执行行为 + +**FR-3.1** 当一个任务进入 `pending` 状态，且其 assignee agent 为自动模式时，系统后台服务自动触发该任务的执行，无需操作人点击任何按钮。 + +**FR-3.2** 自动派发遵循 DAG 依赖顺序：仅当一个任务的所有前置依赖任务已 `completed` 时，该任务才会被自动派发。 + +**FR-3.3** 对于混合模式项目，自动 agent 的任务正常自动执行；手动 agent 的任务继续在界面上等待人工操作，两者可并行推进。 + +**FR-3.4** 自动派发的任务在界面上标记为"自动执行中"，区别于人工派发后的"运行中"状态（视觉上可保持一致，语义上需可区分，便于后续扩展）。 + +**FR-3.5** 同一 agent 支持并发执行多个任务，并发数量不作限制。 + +**FR-3.6** API 调用失败时（网络错误、鉴权失败、超时等），任务进入 `needs_attention` 状态，记录错误原因，不自动重试（与现有手动任务出错行为一致）。 + +--- + +### FR-4 外部 API 格式支持 + +系统以 task prompt 作为输入，通过调用外部 AI 服务的 API 来执行任务。支持以下两种主流接口协议： + +**FR-4.1 OpenAI Chat Completions 格式** +- 系统向 `POST {base_url}/chat/completions` 发送请求 +- 请求体包含 `model`、`messages`（将 task prompt 作为 user message） +- 支持流式（`stream: true`）和非流式两种响应 + +**FR-4.2 Anthropic Messages 格式** +- 系统向 `POST {base_url}/messages` 发送请求 +- 请求体包含 `model`、`messages`（将 task prompt 作为 user message）、`max_tokens` +- 鉴权使用 `x-api-key` header + +**FR-4.3** 两种格式下，task prompt 作为整条 user message 发送给外部服务。系统不维护跨任务的 conversation history（每次调用均为独立对话）。 + +--- + +## 非功能需求 + +**NFR-1 安全性** +- API Key 在数据库中加密存储（或以其他安全方式保存），不以明文存储于 SQLite 中。 +- API Key 在任何 API 响应中均不返回明文，仅在提交时单向写入。 + +**NFR-2 向后兼容** +- 所有已有 agent 默认为手动模式，现有功能和行为不受影响。 +- 自动派发为新增功能，已有工作流不变。 + +**NFR-3 可观测性** +- 自动派发的每次调用需记录事件日志（`TaskEvent`），包括：发起时间、API 格式、成功/失败、错误信息（不含 API Key）。 + +--- + +## 超出范围（Out of Scope） + +- 跨任务的会话上下文维护（多轮对话） +- 项目级别覆盖 agent 执行模式 +- API 调用失败后的自动重试机制 +- 用量统计和费用追踪（可作为后续功能扩展） +- 对现有 `claude_runner.py` / `copilot_runner.py`（SDK 模式）的整合，本次仅引入 REST API 模式 + +--- + +## 界面变更概要 + +### 智能体页面（/agents） + +- Agent 卡片：自动模式 agent 展示 `自动` 标签 +- 创建/编辑 agent 表单：新增"执行模式"切换 + 自动模式下的凭证配置区域 + +### 项目创建/编辑页面 + +- Agent 选择列表：在 agent 名称旁展示模式标签（只读） + +--- + +## 验收标准 + +1. 创建一个自动模式 agent，填写有效的 OpenAI 兼容 API 凭证，将其加入项目并 finalize 计划后，对应任务无需人工操作即可进入执行状态，完成后任务状态变为 `completed`。 +2. 创建一个自动模式 agent，填写无效的 API Key，任务触发后进入 `needs_attention` 状态，错误信息显示鉴权失败，且响应中不包含 API Key 明文。 +3. 一个项目中同时包含手动和自动 agent：自动 agent 的任务自动执行，手动 agent 的任务在界面上等待人工派发，两者正常并行推进，互不影响。 +4. 同一自动模式 agent 被分配多个就绪任务时，这些任务可并发执行，无需等待其中一个完成。 +5. 所有现有手动模式 agent 的行为与改动前完全一致。 +6. API Key 不出现在任何 API 响应、日志或页面中。 From 80611772e1098ddfd3c6857602e081ac11b7c55e Mon Sep 17 00:00:00 2001 From: Wenchi Pan Date: Mon, 18 May 2026 19:29:53 +0800 Subject: [PATCH 2/3] docs: update auto-dispatch for agents prd --- docs/prd/auto-dispatch-agents.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/prd/auto-dispatch-agents.md b/docs/prd/auto-dispatch-agents.md index 6c9b256..c907a8c 100644 --- a/docs/prd/auto-dispatch-agents.md +++ b/docs/prd/auto-dispatch-agents.md @@ -38,16 +38,16 @@ **US-3 自动任务无需操作** 作为项目负责人，当一个项目的所有 agent 均为自动模式时，计划 finalize 后任务将按 DAG 依赖顺序自动推进，我无需手动操作。 -**US-4 混合模式项目** -作为项目负责人，项目中可以同时存在自动模式和手动模式的 agent。自动 agent 的任务由系统自动执行，手动 agent 的任务仍然在界面上等待我手动派发，两者互不干扰。 +**US-4 项目可以被配置为手动模式或自动模式中的一种** +作为项目负责人，项目可以被配置为自动模式或手动模式中的一种，自动模式的项目只能使用自动模式的 agent ，而手动模式的项目只能使用手动模式的 agent。 --- ## 功能需求 -### FR-1 Agent 执行模式配置（"智能体"页面） +### FR-1 Agent 执行模式配置（"智能体设置"页面） -**FR-1.1** 创建或编辑 agent 时，提供"执行模式"选项：手动（默认）或自动。 +**FR-1.1** 创建或编辑智能体类型时，提供"执行模式"选项：手动（默认）或自动。 **FR-1.2** 当选择"自动"时，需展示并要求填写以下字段： @@ -63,7 +63,7 @@ **FR-1.5** 切换模式时需要确认提示：从自动切换回手动时，提示"切换后现有 API 凭证将被清除，确认继续？"。 -**FR-1.6** API 凭证（base_url、api_key）存储在 Agent 实例层，在所有引用该 agent 的项目中共享。 +**FR-1.6** API 凭证（base_url、api_key）存储在 Agent 类型层，在所有引用该智能体类型的智能体实例中共享。 --- From a017f6e77900d27bbe0a984916004b34a89df152 Mon Sep 17 00:00:00 2001 From: Wenchi Pan Date: Mon, 18 May 2026 20:51:19 +0800 Subject: [PATCH 3/3] docs: update auto-dispatch for agents prd --- docs/prd/auto-dispatch-agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/prd/auto-dispatch-agents.md b/docs/prd/auto-dispatch-agents.md index c907a8c..6cd5616 100644 --- a/docs/prd/auto-dispatch-agents.md +++ b/docs/prd/auto-dispatch-agents.md @@ -30,7 +30,7 @@ ## 用户故事 **US-1 管理员/用户配置自动模式 agent** -作为一名用户，我可以在"智能体"页面为某个 agent 开启自动模式，填写 API 凭证，并选择调用格式，保存后该 agent 即可被自动派发。 +作为一名用户，我可以在"智能体设置"页面为某个智能体类型开启自动模式，填写 API 凭证，并选择调用格式，保存后该 agent 即可被自动派发。 **US-2 项目负责人查看 agent 模式** 作为项目负责人，在选择参与 agent 时，我可以看到每个 agent 的模式标签（"自动"或"手动"），以便了解哪些 agent 需要人工介入。