auto-sync: 2026-05-30 10:21:15

docs/design/03-prompt-evolution.md

@@ -2,7 +2,7 @@
 
 **日期**: 2026-05-30
 **作者**: 庞统
-**状态**: 待评审
+**状态**: 已修订 v1.1（根据司马懿 2026-05-30 评审意见）
 **前置**: `02-main-session-delegation.md`（#02 统一走 main session）
 **来源**: architecture-v3.0.md §10.4 Prompt 进化
 
@@ -134,6 +134,17 @@ Mail 路径的 prompt 不变（inform/request 模板已精简）。
 - 产出物 handoff comment ≥ 50 字符（用于系统验证）
 - 禁止使用 sessions_send 直接发消息（用 Mail API 或黑板 comment）
 - 安全红线: {guardrails_summary}
+
+### API 请求体示例
+写产出: POST .../outputs
+```json
+{{"agent": "{agent_id}", "content_type": "code", "title": "产出标题", "content_path": "/path/to/file", "summary": "简要说明"}}
+```
+
+写评论: POST .../comments
+```json
+{{"author": "{agent_id}", "body": "评论内容（≥50字符）", "comment_type": "handoff"}}
+```
 ```
 
 **关键变化**：
@@ -271,7 +282,82 @@ CAPABILITY_LABELS = {
 
 ---
 
-## 五、改动范围
+## 五、兜底机制
+
+### 5.1 无人认领兜底（已实现）
+
+广播认领路径已有兜底：
+
+```
+_broadcast_claim():
+  for task in pending:
+    if retry_count >= 3:
+      → escalated（升级庞统）
+    else:
+      → 广播给 idle agents
+```
+
+3 轮广播无人认领 → 任务标 `escalated` → 庞统接手（走 delegate 路径）。
+
+### 5.2 Claim 并发保护（已实现）
+
+`claim_task()` 是原子 CAS 操作：
+
+```sql
+UPDATE tasks SET status='claimed', assignee=? WHERE id=? AND status='pending'
+```
+
+多个 Agent 同时 claim 同一个任务，只有第一个成功（`rowcount=1`），其余返回 False。Agent 在 prompt 中被告知：「如果 claim 失败说明已被别人认领，NO_REPLY 退出」。
+
+**不需要两步**（claim + working）。claim 成功即标 `claimed`，Agent 再标 `working` 时黑板校验 `status=claimed`，不存在竞态窗口。
+
+---
+
+## 六、占位符定义
+
+### 6.1 `{guardrails_summary}`
+
+**来源**: `GuardrailEngine.rules` 中的 6 条红线摘要。
+
+**注入方式**: spawner 在构建 prompt 时从 `GuardrailEngine.rules` 提取 `rule_name`，拼接为逗号分隔的字符串。
+
+```python
+def _get_guardrails_summary(self) -> str:
+    if not self.guardrails:
+        return "无特殊限制"
+    return "、".join(r["name"] for r in self.guardrails.rules[:6])
+```
+
+**当前 6 条红线**（PRD §10.1）：
+1. 禁止操作生产环境数据库
+2. 禁止执行未审核的外部代码
+3. 禁止绕过风控规则
+4. 禁止修改系统配置
+5. 单次交易不得超过限额
+6. 禁止未授权的资金操作
+
+**没有 guardrails 时**: 填 "无特殊限制"。
+
+### 6.2 `{retry_context}`
+
+**来源**: `tasks.retry_count` 字段 + 上次执行的 outputs/comments。
+
+**注入逻辑**（复用现有 `_build_retry_context`，增强）：
+
+```python
+def _build_retry_context(self, task) -> str:
+    if (task.retry_count or 0) == 0:
+        return ""
+    parts = ["⚠️ 这是重试（第 {} 次尝试），之前的执行失败了。".format(task.retry_count + 1)]
+    # 可选：注入上次失败原因（从 comments 中取 system 写的失败记录）
+    return "\n".join(parts)
+```
+
+**首次执行时**: 填空字符串，不渲染重试段。
+
+---
+
+## 七、改动范围
 
 | 文件 | 改动点 | 改动量 |
 |------|--------|--------|
@@ -290,7 +376,7 @@ CAPABILITY_LABELS = {
 
 ---
 
-## 六、收益
+## 八、收益
 
 | 维度 | 改善 |
 |------|------|
@@ -302,7 +388,7 @@ CAPABILITY_LABELS = {
 
 ---
 
-## 七、风险
+## 九、风险
 
 | 风险 | 缓解 |
 |------|------|
@@ -313,7 +399,7 @@ CAPABILITY_LABELS = {
 
 ---
 
-## 八、实施计划
+## 十、实施计划
 
 ### Phase 1：Task 执行模板 + 身份注入