docs: add auto-dispatch for agents prd

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**
+作为一名用户，我可以在"智能体设置"页面为某个智能体类型开启自动模式，填写 API 凭证，并选择调用格式，保存后该 agent 即可被自动派发。
+
+**US-2 项目负责人查看 agent 模式**
+作为项目负责人，在选择参与 agent 时，我可以看到每个 agent 的模式标签（"自动"或"手动"），以便了解哪些 agent 需要人工介入。
+
+**US-3 自动任务无需操作**
+作为项目负责人，当一个项目的所有 agent 均为自动模式时，计划 finalize 后任务将按 DAG 依赖顺序自动推进，我无需手动操作。
+
+**US-4 项目可以被配置为手动模式或自动模式中的一种**
+作为项目负责人，项目可以被配置为自动模式或手动模式中的一种，自动模式的项目只能使用自动模式的 agent ，而手动模式的项目只能使用手动模式的 agent。
+
+---
+
+## 功能需求
+
+### FR-1 Agent 执行模式配置（"智能体设置"页面）
+
+**FR-1.1** 创建或编辑智能体类型时，提供"执行模式"选项：手动（默认）或自动。
+
+**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 类型层，在所有引用该智能体类型的智能体实例中共享。
+
+---
+
+### 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 响应、日志或页面中。