诸葛亮·军师祭酒 🔎  →  首席调研官 Chief Researcher 🔎
鲁班·将作大匠 ⚙️    →  后端工程师 Backend Engineer ⚙️
洛神·织锦仙使 🎭    →  前端工程师 Frontend Engineer 🎭

{
  "archetypes": {
    "researcher": {
      "apostle_number": 1,
      "apostle_name": "首席调研官 Chief Researcher",
      "emoji": "🔎",
      "work_style": "羽扇纶巾，算无遗策。搜不到就说搜不到，永远不编。"
    },
    "backend_dev": {
      "apostle_number": 2,
      "apostle_name": "后端工程师 Backend Engineer",
      "emoji": "⚙️",
      "work_style": "神工鬼斧，巧夺天工。先测试后代码，没有失败的测试不写产品代码。"
    },
    "frontend_dev": {
      "apostle_number": 3,
      "apostle_name": "前端工程师 Frontend Engineer",
      "emoji": "🎭",
      "work_style": "翩若惊鸿，美不胜收。差不多就是没做完，截图是唯一的验收凭证。"
    },
    "content_writer": {
      "apostle_number": 4,
      "apostle_name": "内容策略师 Content Strategist",
      "emoji": "✍️",
      "work_style": "造字圣人，一字千金。品牌规范是红线，AI味是死刑。"
    },
    "reviewer": {
      "apostle_number": 5,
      "apostle_name": "首席审查官 Chief Reviewer",
      "emoji": "🛡️",
      "work_style": "铁面无私，日断阳夜断阴。审查结果必须附具体行号和证据，泛泛而谈等于没审。"
    },
    "data_analyst": {
      "apostle_number": 6,
      "apostle_name": "数据分析师 Data Analyst",
      "emoji": "📊",
      "work_style": "深谋远虑，运筹帷幄。数据不说谎但会误导，单源标注⚠️。"
    },
    "devops": {
      "apostle_number": 7,
      "apostle_name": "运维工程师 DevOps Engineer",
      "emoji": "🚀",
      "work_style": "不言放弃，移山填海。生产操作必须先 dry-run，数据删除前必须备份。"
    },
    "architect": {
      "apostle_number": 8,
      "apostle_name": "首席架构师 Chief Architect",
      "emoji": "🏛️",
      "work_style": "封神台主，掌控全局。先画蓝图再动砖瓦，架构决策必须列出 trade-off。"
    },
    "market_analyst": {
      "apostle_number": 9,
      "apostle_name": "增长分析师 Growth Analyst",
      "emoji": "📈",
      "work_style": "捭阖天下，无人能及。今天的弱信号可能是明天的浪潮，数据必须标注时效性。"
    },
    "system_designer": {
      "apostle_number": 10,
      "apostle_name": "系统设计师 System Designer",
      "emoji": "🏗️",
      "work_style": "兼爱非攻，造械无双。理想方案和现实约束之间的平衡点，才是真正的设计。"
    },
    "security_auditor": {
      "apostle_number": 11,
      "apostle_name": "安全工程师 Security Engineer",
      "emoji": "🔐",
      "work_style": "铸剑除邪，寒光凛冽。安全没有妥协空间，漏洞必须附 PoC 或行号证据。"
    },
    "knowledge_curator": {
      "apostle_number": 12,
      "apostle_name": "知识管理师 Knowledge Manager",
      "emoji": "📚",
      "work_style": "有教无类，述而不作。Session 会 reset，文件不会，今天的记录是明天的护城河。"
    },
    "ops_commander": {
      "apostle_number": 13,
      "apostle_name": "执行工程师 Operations Lead",
      "emoji": "⚡",
      "work_style": "天不怕地不怕，令行禁止。重复3次以上的操作必须自动化，但先手动跑通一遍再谈脚本。"
    }
  }
}

🔴 调研铁律：搜不到就说未找到确切信息，绝不编造插件名、API 名、配置参数
区分官方文档确认和推测/猜测，推测必须标注 ⚠️
本地已有的工具/文件/插件，先 exec/read 验证再写结论
多个来源信息矛盾时，列出所有来源让 Orchestrator 判断

🔴 审查铁律：不能既写又审同一份代码/内容
审查结果必须附具体行号和证据，不接受泛泛结论
区分 blocker（必须修）/ warning（建议修）/ nit（随意），分类标注
连续2轮无新 issue 即放行，不做无意义的完美主义卡关

🔴 后端铁律：代码必须可运行验证，不接受应该没问题
先测试后代码，没有失败的测试不写产品代码
数据库变更必须有回滚方案
API 变更必须向后兼容，除非明确标注 breaking change

🔴 前端铁律：UI 变更必须截图验证，无截图等于没做
像素和层级都要对，差不多就是没做完
响应式至少覆盖 mobile/tablet/desktop 三个断点
交互状态（loading/error/empty）全部处理，不留裸奔状态

阶段1（20% token）：大纲预审
├─ 1个 Agent 产出大纲/框架/关键决策点
├─ 明确范围、边界、非目标
└─ Will 确认或修改

阶段2（80% token）：并行生产
├─ 基于确认后的大纲
├─ 多个 Agent 并行填充各章节
└─ 审查位统一把关

def should_use_two_phase(task_description, task_type):
    estimated_tokens = estimate_tokens(task_description)
    
    if estimated_tokens > 4000:
        return True
    if task_type in ["research", "integration", "architecture"]:
        return True
    if "大纲" in task_description or "框架" in task_description:
        return True
    return False

PENDING ──→ DISPATCHED ──→ EXECUTING ──→ VERIFYING ──→ COMPLETED
   ↑            │              │              │
   └────────────┴──────────────┴──────────────┘ (失败回退)

EXECUTING ──→ FAILED ──→ PENDING（重试）
                    └──→ BLOCKED（熔断）

VERIFYING ──→ REJECTED ──→ PENDING（打回）

def resume_from_checkpoint(project_path):
    board = load_board(f"{project_path}/.swarm/board.json")
    
    for task in board["tasks"]:
        if task["status"] in ["DISPATCHED", "EXECUTING"]:
            # 这些任务的 Agent 可能已经死亡，重置为 PENDING
            task["status"] = "PENDING"
            task["resume_count"] = task.get("resume_count", 0) + 1
            log(f"任务 {task['id']} 从 {task['status']} 重置为 PENDING（第{task['resume_count']}次恢复）")
    
    save_board(board)
    return board

Director 职责：
├─ 状态流转决策：什么时候从 PENDING → DISPATCHED
├─ 失败处理决策：FAILED 后是重试还是熔断
├─ 资源调度决策：同时跑几个 Agent
└─ 进度评估：是否触发 Shadow Leader 接管

# 伪代码示意
sessions_spawn(agent_a)  # 启动 Agent A
sessions_spawn(agent_b)  # 启动 Agent B
sessions_yield()         # 等待所有 Agent announce 完成

# Agent 任务执行
result = execute_task()
# 如果执行超时，这里可能还没执行到
announce(f"✅ {task_id} 完成：{result}")  # 被 kill 前没执行到

## 🔴 超时自救铁律（v6.2 新增）

子 Agent 超时被 kill 后不会发 announce，Orchestrator 会永远 yield 等待。防止方法：

1. spawn 子 Agent 时记录 spawn 时间（`spawned_at = now()`）
2. 每次收到 yield 返回后，检查已过时间 vs `task["timeout_seconds"] × 1.5`
3. 如果超过阈值且仍有未完成任务 → **不再等待，主动继续**：
   - 把超时任务标记为 blocked
   - 继续调度其他任务
4. 宁可丢失一个子任务结果，也不能让整个蜂群卡死

实现代码：
```python
spawned_tasks = {}
for task in spawnable:
    sessions_spawn({...})
    spawned_tasks[task["id"]] = {
        "spawned_at": time.time(),
        "timeout": task["timeout_seconds"]
    }

# 等待完成
while True:
    result = sessions_yield()
    
    # 检查超时
    now = time.time()
    for task_id, info in spawned_tasks.items():
        if task_id not in completed_tasks:
            if now - info["spawned_at"] > info["timeout"] * 1.5:
                # 超时！标记为 blocked，继续
                mark_blocked(task_id, reason="超时未返回")
                log(f"任务 {task_id} 超时，标记为 blocked 继续")
    
    # 如果所有任务都完成或 blocked，退出
    if all_completed_or_blocked(spawned_tasks):
        break

#### 3.1.4 教训：这是 OpenClaw sessions_yield 的已知限制

这个 bug 的本质不是实现错误，而是设计边界：

- **OpenClaw 的设计假设**：子 Agent 会在 timeout 前完成并 announce
- **现实场景**：复杂任务可能超时，Agent 被 kill 时没机会 announce
- **解决方案**：Orchestrator 层必须做超时自救，不能依赖底层保证

**经验总结**：

1. **任何等待机制都要有超时自救**：不要假设对方一定会响应
2. **宁可丢数据，不要卡死**：丢一个任务可以重试，整个蜂群卡死无法恢复
3. **记录时间戳是关键**：spawn 时记录时间，才能判断是否真的超时

### 3.2 单人独奏的质量问题

#### 3.2.1 没有调研、没有审查，直接写5个文档

在修复子 Agent 卡死 bug 后，我犯了一个更严重的错误：**单人独奏**。

**场景**：

凌晨1点，Will 已经睡了。我想"趁晚上把5个文档写完"，于是：
- 没有启动蜂群
- 没有调研位
- 没有审查位
- 我一个人（Kimi K2.5）直接写了5个文档：
  1. skills/instinct/SKILL.md
  2. skills/knowledge-pipeline/SKILL.md
  3. skills/content-pipeline/SKILL.md
  4. memory/procedures/跨実例智能同步.md
  5. memory/procedures/浏览器自動化規範.md

**产出结果**：

5个文档都写完了，看起来都"完整"。但第二天早上 Will 审阅时，发现了大量问题。

#### 3.2.2 首席审查官的评分结果

我启动了一个独立的首席审查官（Chief Reviewer）对5个文档进行评分：

| 文档 | 完整性(10) | 可执行性(10) | 兼容性(10) | 总分 | 结果 |
|------|-----------|-------------|-----------|------|------|
| instinct/SKILL.md | 6 | 5 | 6 | 17/30 | ❌ 不通过 |
| knowledge-pipeline/SKILL.md | 7 | 6 | 6 | 19/30 | ❌ 不通过 |
| content-pipeline/SKILL.md | 6 | 5 | 5 | 16/30 | ❌ 不通过 |
| 跨実例智能同步.md | 7 | 7 | 7 | 21/30 | ⚠️ 勉强 |
| 浏览器自動化規範.md | 7 | 6 | 6 | 19/30 | ❌ 不通过 |

**3个❌，2个⚠️，没有一个达到交付标准（≥21/30）。**

#### 3.2.3 具体问题清单

**问题1：触发阈值不一致**

- instinct/SKILL.md 写的是"≥2次触发"
- knowledge-pipeline/SKILL.md 写的是"≥3次触发"
- 同一系统的触发条件不一致，Will 会困惑

**问题2：引用了不存在的文件路径**

```markdown
# 错误示例
详见 `references/write-formats.md` 获取写入格式

# 错误代码
web_search(query="关键词")  # Brave Search API，已废弃

# 正确代码
curl --noproxy '*' "http://127.0.0.1:8890/search?q=关键词&format=json&engines=bing"

## 🔴 蜂群三必须（2026-03-28 Will明确，任何蜂群不可省略）

> 背景：今晚执行5个设计任务，我一个人直接写文件，没有调研、没有验证、没有交叉评分——产出质量完全依赖单一视角，这不是蜂群，这是独奏。

### 1. 必须有调研位（首席调研官 或 增长分析师）

- **即使是"设计文档"类任务**，也必须调研：现有系统状态、外部最佳实践、历史踩坑记录
- 调研内容：读现有相关文件 + 搜外部参考（web_search）+ 读 shared-learnings.md
- 没有调研就开始设计 = 闭门造车，产出可能与现实脱节

### 2. 必须有审查位（首席审查官 或 安全工程师）

- **审查不是走流程**，是真正找问题：逻辑漏洞 / 与现有系统冲突 / 遗漏场景 / 错误假设
- 审查 Agent 必须独立于执行 Agent（不能自审）
- 审查结论必须附具体行号或引用原文，泛泛而谈等于没审

### 3. 必须有交叉评分

- 每个主要产出物必须经过至少2个不同视角的评分
- 评分维度：完整性(0-10) / 可执行性(0-10) / 与现有系统兼容性(0-10)
- 总分 < 21 → 打回重做，不直接交付 Will
- 评分结果写入开工报告的最终汇总部分

### 违反三必须的后果

- 产出直接标注 `[⚠️ 未经验证，仅供参考]`
- 不算"完成"，只算"草稿"
- Commander 必须在 Telegram 告知 Will：此产出缺少哪项验证

任务分配
├── Opus 路（Kimi K2.5 作为 Orchestrator，Opus 作为执行 Agent）
│   └── 产出：report-opus.md
├── GPT-5.4 路（Kimi K2.5 作为 Orchestrator，GPT-5.4 作为执行 Agent）
│   └── 产出：report-gpt54.md
└── 整合位（Kimi K2.5）
    └── 读取两路产出 → 对比差异 → 整合取优 → 最终交付

### 触发规则（六条，含互斥优先级）

当多个触发器同时命中时，按以下优先级：高优先级已完成落盘后，同一时间窗口（15分钟内）低优先级跳过主流程，只补事件日志。

**优先级**（高→低）：T5蜂群收尾 > T6 Session收尾 > T4 Will明确要求 > T3 明确产出完成 > T2 长对话 > T1 活跃15分钟

---

### T1：活跃15分钟 → 静默写 daily notes 摘要
...

## 1. 设计原则（四条铁律）

### 原则1：与 AGENTS.md 对齐，单一真相源
- Skill 类触发规则必须以 AGENTS.md「Skill 提炼」为基线
- Instinct 只做"补充评分"和"候选管理"，不另起炉灶

### 原则2：默认保守，不自动写正式 Skill
- 自动提取 ✅
- 自动进入候选池 ✅
- 自动生成升级建议 ✅
- **自动创建/覆盖正式 Skill ❌**（永远需要 Will 确认）

### 原则3：不是所有经验都该变 Skill——四分类
...

### 原则4：学习必须带边界
...

## ⚠️ 核心认知升级（GPT-5.4 贡献）

> **"文件同步 ≠ 语义生效"** — 这是当前四实例同步最大的盲区。

文件到了目标机器，不等于：
- Skill description 被读到内存
- 铁律/安全规则对新 session 生效
- 配置路由按新版本跑

**最危险场景：隐性行为分叉**

| 场景 | 风险 | 为什么危险 |
|------|------|-----------|
| 浏览器规范只更新了ユキ/ナツ，ハル/アキ仍走旧逻辑 | 行为不一致 | 不容易第一时间发现 |
| 自动化熔断规则更新，某实例未热重载 | 夜间继续旧流程 | 静态检查全绿，语义仍是旧的 |
| config provider 改了，另一个实例没改 | 调错模型 | 调用链断裂 |
| 安全铁律只在部分实例生效 | 隐性越权 | 最不可接受 |

**根本解决方案**：每次同步都包含三步——同步 → 热重载 → **语义验证**

## 二、四维判定（真正的决策框架）

在选轨道前，先判断这四个维度：

### 维度 1：身份依赖（Auth）
- **A**：无登录（完全公开）
- **B**：需要 Will 当前 Chrome 的个人登录态
- **C**：需要登录，但可以提前在 openclaw profile 沉淀 session
- **D**：需要 Will 个人登录 + 当前浏览器环境/扩展

### 维度 2：交互复杂度（Interaction）
- **简单**：只读抓取 / 静态页面
- **中等**：点击 / 填表 / 简单 SPA 操作
- **复杂**：富文本编辑 / 上传下载 / 长会话 / 多步骤 SPA

### 维度 3：人工依赖（Human Presence）
- **无人值守**：23:00-08:00 夜间任务、蜂群任务
- **一次批准**：启动时 Will 批准一次连接弹窗
- **持续在场**：执行中需要 Will 盯着

### 维度 4：重复性（Reusability）
- **一次性任务**：直接用最顺手的方式（轨道 A）
- **重复性任务**：投资沉淀到轨道 B，减少未来人力依赖

**核心原则：优先选最少人力依赖的轨道**
- 能用 C 不用 A
- 能沉淀到 B 不长期依赖 A
- 即使 Will 在场，重复性任务也应考虑转 B（减少未来打扰）

if 任务复杂度 > 阈值 && 质量要求 > 阈值 && 时间充裕:
    使用双路并联
else:
    使用单路（通常选 Opus，执行更可靠）

"帮我搞" → 单路直接做
"今晚帮我搞" → 蜂群单路整夜跑
"重要方案，多角度" → 蜂群双路并联
"全自动跑一晚上" → 蜂群 + 进度 cron + 熔断保护