skill-multi-branch v0.1.0: 沟通/执行分层编排——任务书协议+派发器+四态上报+执行层纪律(0912课纲违规案例沉淀)+故障对策表

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+*.log
+.env

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fmodecn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,54 @@
+# skill-multi-branch · 沟通/执行分层编排
+
+> **Hermes 负责沟通，专业任务派发给执行层（Claude Code / Codex / Agent profile），状态全程上报**——数字生命的多任务工作框架。
+> 本技能内含一条被真实事故验证的**执行层纪律**（ Orchestrator 亲自干活=框架失效），是它的灵魂章节。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## 解决什么
+
+单 Agent 既当沟通者又当执行者时必然出现：用户问话没人答、长任务静默死亡、"以为在跑其实在躺"、Orchestrator 亲自干专业活导致质量与纪律双输。本技能把三层职责显式分开：
+
+```
+用户 ⇄ 沟通层(Hermes) —— 有问必答、先回执后派发
+              ↓ 任务书(落盘)
+        调度层(multi-branch) —— ack→running→done/failed + 心跳
+              ↓
+        执行层(Claude Code / Codex / profile) —— 专业产出，会话痕迹可查
+```
+
+## 快速用
+
+```bash
+bash skills/fmode-multi-branch/scripts/dispatch.sh <项目目录> <任务书.md> [模型] [DONE标记]
+```
+
+状态日志：`/tmp/mb-status.log`（ack/done/failed 时间线）。
+
+## 执行层纪律（详见 SKILL.md 〇章）
+
+- 专业工作必须派发，Orchestrator 只出任务书+验收
+- "任务琐碎/CLI 慢"不是绕过理由
+- 验收先查**执行痕迹**（项目 `.claude/projects/` 会话 jsonl），无痕迹=违规产出，重做
+
+## 各工具安装
+
+### Hermes Agent
+```bash
+git clone https://git.fmode.cn/fmode/skill-multi-branch.git
+cp -r skill-multi-branch/skills/fmode-multi-branch ~/.hermes/skills/
+```
+
+### Claude Code / Codex
+本技能主要服务 Hermes 侧调度；Claude Code 侧只需任务书规范（SKILL.md 一章）——可直接把 SKILL.md 并入项目 CLAUDE.md。
+
+### WorkBuddy / 其他
+复制 `skills/fmode-multi-branch` 到对应技能目录。
+
+## 凭据
+
+`FMODE_API_KEY` 环境变量 或 `~/.fmode/config.json`（与家族其他技能同链）。
+
+## License
+
+MIT

package.json

@@ -0,0 +1,5 @@
+{
+  "name": "fmode-multi-branch",
+  "version": "0.1.0",
+  "license": "MIT"
+}

skills/fmode-multi-branch/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: fmode-multi-branch
+description: "多分支任务编排：Hermes（沟通层）把专业任务派发 Claude Code / Codex / 子 Agent profile 执行，含任务书落盘、执行层纪律、状态上报（ack→running→done/failed + 心跳）、中断续跑与完成验收。适用：(1) 多任务并行调度 (2) 专业内容生产必须走执行层的团队 (3) 需要\"先沟通后派发\"响应模式的 Agent 协作。"
+description_en: "Multi-branch orchestration: Hermes (communication layer) dispatches professional tasks to Claude Code / Codex / agent profiles, with task briefs, execution-layer discipline, status reporting (ack→running→done/failed + heartbeat), resume-after-interrupt, and acceptance checks."
+---
+
+# Fmode Multi Branch — 沟通/执行分层编排技能
+
+## 〇、执行层纪律（★ 本技能的灵魂，违反=框架失效）
+
+> 教训来源（2026-09-12 实例）：课纲修订任务被 Orchestrator 以"任务琐碎/CLI 慢"为由亲手完成——用户复查发现项目目录下**无 Claude Code 会话痕迹**，判定违规，产出重做。
+
+**分层铁则**：
+
+1. **内容/课件/措辞/方案/代码类专业工作 → 必须派发执行层**（Claude Code / Codex / profile），Orchestrator 只做：任务书 + 验收
+2. **允许亲自处理的例外**：单点字符串替换、配置文件行级修改、纯机械部署命令（无创作成分）——判断标准：**这活需要"判断"吗？需要判断就必须派发**
+3. **"任务琐碎"“CLI 慢”“上次中断过”都不是绕过的理由**——那是框架要防的人因缺陷；正确动作是派发+监控，不是自己上
+4. **验收必查执行痕迹**：`ls ~/.claude/projects/-opt-data-<项目路径>/ | 近时段 jsonl`——**没有会话痕迹的"CC 产出"= 违规产出，重做**
+5. **违规产出处理**：不辩论、不降级接受——出任务书让执行层重做（如 1.0.5→1.0.6 实例），并沉淀教训
+
+## 一、任务派发协议
+
+### 1.1 接任务（沟通层职责）
+
+- **先回执后派发**：收到任务先一句话回应用户（"收到，派发执行层做 X，预计 N 分钟"），再 spawn
+- 任务书**落盘**（防止超长与上下文丢失）：写到项目 `docs/task-*.md` 或 `/tmp/task-*.md`
+
+### 1.2 任务书模板（要素齐全才可派发）
+
+```markdown
+# <任务名> 任务书
+你是<角色>。仓库/输入路径：...
+## 你要做的（编号清单，逐条可验收）
+## 纪律（不可动项/措辞口径/品牌规则）
+## 交付（文件+部署+commit push）
+完成后只输出一行：<DONE-标记> <关键字段>
+```
+
+### 1.3 派发（执行层）
+
+```bash
+cd <项目目录>   # 会话痕迹落在该项目的 .claude/projects/ 下（验收依据）
+export ANTHROPIC_BASE_URL=<api> ANTHROPIC_AUTH_TOKEN=$FMODE_API_KEY
+<claude|codex> -p "$(cat 任务书路径摘要指令)" --model <model> --dangerously-skip-permissions
+```
+
+- **后台运行 + notify_on_complete**（完成通知挂钩）
+- 派发时附带：`先检查现状再续做，勿重复已完成部分`（中断续跑保险）
+
+### 1.4 状态上报（与 reporter 同表）
+
+| 状态 | 触发 | 记录 |
+|---|---|---|
+| ack | 接任务回执时 | 任务名/执行层/预计时长 |
+| running | spawn 成功 | PID/会话目录 |
+| done | DONE-标记 收到+验收过 | 交付物/commit |
+| failed | 进程退出无标记/超时/验收不过 | 根因/重试次数 |
+
+**心跳**：running 状态 30s 无心跳 = 疑似死亡 → 主动查进程与产物，不靠"以为还在跑"。
+
+## 二、验收协议
+
+1. **执行痕迹**（见 〇-4）
+2. **DONE 标记核对**：输出行是否符合任务书格式
+3. **产物独立验证**：线上 URL 逐个 curl / 文件字节级抽查 / diff 对照（内容类：只许更好不许丢内容）
+4. **不过关处理**：定点问题回执执行层修；结构性问题重出任务书
+
+## 三、已知故障与对策
+
+| 故障 | 症状 | 对策 |
+|---|---|---|
+| API 403/中断 | CLI 中途死 | 充值确认后**续跑指令**（先查现状续做勿重复） |
+| gateway 重启连带 | CLI 子进程全灭+notify 丢失 | 重启前盘点在跑任务；重启后巡检+补 spawn |
+| 自报 200 假阳性 | hash MATCH 但内容旧/缺 | 验收永远独立 curl+内容特征词 |
+| obsutil 目录 cp 嵌套 | lib/lib/ 双层目录 | **逐文件指定目标键**，禁目录递归 cp |
+| CDN 缓存顽固 | 改完还回旧版 | 带 ?v= 参数验证 + OBS 源字节级核对 |
+| 中文 URL 不可点 | 用户点不开 | 发送前 encodeURI；线上文件名用英文 |
+
+## 四、脚本
+
+`scripts/dispatch.sh`：标准派发器（任务书路径+项目目录+模型 → 后台 spawn+状态记录）
+`scripts/status-reporter.mjs`：四态+心跳写 reporter 同表（AgentTaskStatus）

skills/fmode-multi-branch/scripts/dispatch.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# dispatch.sh — multi-branch 标准派发器
+# 用法: dispatch.sh <项目目录> <任务书路径> [模型] [DONE标记]
+# 职责: ack 记录 → 后台 spawn 执行层 → 状态可查
+set -euo pipefail
+PROJECT_DIR="${1:?用法: dispatch.sh <项目目录> <任务书路径> [模型] [DONE标记]}"
+BRIEF="${2:?缺任务书路径}"
+MODEL="${3:-deepseek-v4-flash}"
+DONE_TAG="${4:-DONE}"
+TS=$(date +%Y%m%d-%H%M%S)
+LOG="/tmp/mb-${TS}.log"
+
+cd "$PROJECT_DIR"
+
+echo "[ack] $(date '+%F %T') 任务书=$BRIEF 执行层=claude 模型=$MODEL" >> /tmp/mb-status.log
+
+export ANTHROPIC_BASE_URL="${ANTHROPIC_BASE_URL:-https://api.fmode.cn}"
+export ANTHROPIC_AUTH_TOKEN="${ANTHROPIC_AUTH_TOKEN:-$FMODE_API_KEY}"
+
+/opt/data/npm-global/bin/claude -p "$(cat "$BRIEF")" --model "$MODEL" --dangerously-skip-permissions 2>&1 | tee "$LOG" | tail -3
+
+if grep -q "$DONE_TAG" "$LOG"; then
+  echo "[done] $(date '+%F %T') $BRIEF" >> /tmp/mb-status.log
+  exit 0
+else
+  echo "[failed] $(date '+%F %T') $BRIEF (无DONE标记, 需续跑: 加'先检查现状续做勿重复'重派)" >> /tmp/mb-status.log
+  exit 1
+fi