|
|
@@ -0,0 +1,212 @@
|
|
|
+---
|
|
|
+name: fmodecode-task-delegation
|
|
|
+description: "触发词:CC派发、Claude Code执行、claude -p、长任务。Git级项目五步流程+并行CC+图文并茂增强+图片验证。"
|
|
|
+version: 2.0.0
|
|
|
+author: Yuyang001 (FmodeAgent), Hermes Agent
|
|
|
+license: MIT
|
|
|
+platforms: [linux]
|
|
|
+tags: [FmodeCode, claude-code, delegation, course-dev, image-vrf]
|
|
|
+related_skills: [task-dispatch, fmode-brand-naming, skill-image]
|
|
|
+---
|
|
|
+
|
|
|
+# FmodeCode 任务委派 v2 (fcode-task-delegation)
|
|
|
+
|
|
|
+## 何时用
|
|
|
+
|
|
|
+- 需把专业任务（课件创作/论文/开发/重构）委派给 FmodeCode CLI（`claude` 命令）非交互执行
|
|
|
+- 长任务（>10分钟）后台运行、需验收产出
|
|
|
+- 复盘"任务跑了很久却没产出"类事故
|
|
|
+
|
|
|
+不要用于: 简单单轮问答（直接 `claude -p "q"` 即可）。
|
|
|
+
|
|
|
+## 五步流程总纲（用户钦点，2026-09-21 固化）
|
|
|
+
|
|
|
+```
|
|
|
+调研素材 → 写计划 → 写任务书(含资源索引) → 派CC执行 → 验收部署上线
|
|
|
+```
|
|
|
+
|
|
|
+① **调研素材**：项目现状（仓库结构/代码风格/已用库/线上效果）+ 权威参考源 + 盘点 PRD/架构文档
|
|
|
+② **写计划**：定方向、列模块、分阶段、标依赖风险 → `docs/task/<name>-plan.md`
|
|
|
+③ **写任务书**：**inline 所有参考素材**，资源索引用绝对路径且事前验证，写明工作目录/模型/超时/验收
|
|
|
+④ **派 CC 执行**：绝对路径调 claude，启动后 60s 健康检查确认真在跑
|
|
|
+⑤ **验收部署上线**：本地验证 → git commit+push → OBS 上传 → CDN 刷新 → curl 全路由 200+内容验证
|
|
|
+
|
|
|
+**禁止 shortcut**：❌ 跳调研直接写任务书 ❌ 调研后跳计划直接派 ❌ 计划后自己手工改
|
|
|
+**例外**：纯机械操作（改配置行/单文件批量替换/纯部署命令）可跳步
|
|
|
+
|
|
|
+## 保留框架增量增强（2026-09-22 V6 实证，图文并茂专用）
|
|
|
+
|
|
|
+用户说"内容不错了，需要加图、图文并茂"时触发：
|
|
|
+- 框架/content 结构不动
|
|
|
+- 自绘 SVG 全部保留（宝贵素材）
|
|
|
+- 只在对应位置补充：CDN 案例图 + skill-image 生成场景图
|
|
|
+- 技术架构图用 skill-image 升级为含人/场景的版本（让非技术老板看懂）
|
|
|
+- 每屏或每加图后 verify Content-Type
|
|
|
+
|
|
|
+## 同仓多 CC 并行的 git 索引污染（2026-09-21 四主题并行实证）
|
|
|
+
|
|
|
+1. **提交用显式 pathspec**：`git add <本次任务确切文件路径>`，**禁 `git add .` / `git add <大目录>`**——后者连带提交兄弟会话暂存改动
|
|
|
+2. **被污染立即纠错**：`git reset --soft HEAD~1` + 显式 pathspec 重提，纠错追加进记录（不删历史）
|
|
|
+3. **共享外壳文件不抢提交**（index/manifest）：交批次收口统一提交或事先分工
|
|
|
+4. CC 报告"未纳入提交（避免带走并发会话改动）"= **正确行为**，收口时补提共享文件
|
|
|
+5. **收口前先 `git pull --rebase`**——push 前先拉，冲突就地合，合完**必须重新发布上线**
|
|
|
+
|
|
|
+## 长任务后台启动与监控两坑（2026-09-21 实测）
|
|
|
+
|
|
|
+1. **后台进程不继承交互 shell 的 PATH**——`terminal(background=true)` 里 `export PATH=... && claude` 报 `bash: claude: command not found`(exit 127)。用**绝对路径** `/opt/data/npm-global/bin/claude`，PATH export 只作保险。派发后 `process list` 确认 running 而非 exited
|
|
|
+2. **不要 foreground `sleep` 等任务**——等待一律 `background=true + notify_on_complete`，靠完成通知回收
|
|
|
+3. **每任务独立 log**：`> /tmp/cc-<task>.log 2>&1`
|
|
|
+4. **四连发验证可行**：同仓并发 4 个 CC 实测全一次跑通，但按上节纪律防 git 污染
|
|
|
+
|
|
|
+## 图片验证铁律（2026-09-22 用户新增钦点）
|
|
|
+
|
|
|
+```bash
|
|
|
+# ❌ 不足：只查 HTTP 200（404 首页替代可能返回 200）
|
|
|
+curl -s -m 10 -o /dev/null -w "%{http_code}" <URL>
|
|
|
+
|
|
|
+# ✅ 必须检查 Content-Type
|
|
|
+CT=$(curl -s -m 10 -o /dev/null -w "%{content_type}" <URL>)
|
|
|
+if [[ "$CT" != image/* ]]; then echo "❌ 不是真图片: $CT"; fi
|
|
|
+```
|
|
|
+
|
|
|
+## skill-image 集成模式（2026-09-22 新增）
|
|
|
+
|
|
|
+```bash
|
|
|
+# --scene: 场景图（插图/含人的架构图/业务流程）
|
|
|
+node /opt/data/skills/skill-image/lib/fmode-image.mjs --scene \
|
|
|
+ "蓝紫色科技风, 办公室场景, 具体内容描述" output.png
|
|
|
+
|
|
|
+# --app: 应用界面（白底UI图）
|
|
|
+node ... --app "APP界面描述" output.png
|
|
|
+
|
|
|
+# --product/--architecture: 爆炸图/架构分层图
|
|
|
+node ... --product "分层架构描述" output.png
|
|
|
+```
|
|
|
+生成后上传 OBS + CDN 刷新 + 验证 Content-Type。
|
|
|
+
|
|
|
+## 启动前三要素（缺一即失败）
|
|
|
+
|
|
|
+```bash
|
|
|
+export PATH="/opt/data/npm-global/bin:$PATH" # claude 二进制
|
|
|
+export ANTHROPIC_AUTH_TOKEN=$FMODE_API_KEY # 必设,否则 Not logged in
|
|
|
+export ANTHROPIC_BASE_URL=https://api.fmode.cn
|
|
|
+which claude && claude --version
|
|
|
+
|
|
|
+# 后台启动用绝对路径（见上节），启动后 pgrep -f claude 确认真在跑
|
|
|
+```
|
|
|
+
|
|
|
+## Prompt 传参：stdin 是唯一安全方式（2026-08-30 事故铁律）
|
|
|
+
|
|
|
+```bash
|
|
|
+# ✅ 标准：长任务书走 stdin 重定向
|
|
|
+claude -p "执行任务书全部内容,完成后git commit(不push)" \
|
|
|
+ --permission-mode bypassPermissions < task.md > run.log 2>&1
|
|
|
+
|
|
|
+# ❌ 禁止：claude -p "$(cat task.md)"
|
|
|
+# 反引号/$(/括号被 shell 命令替换吃掉 → 模型收到残缺 prompt → 3分钟假完成(exit 0)
|
|
|
+```
|
|
|
+
|
|
|
+## 模型选择（settings.json 是唯一正确配置点）
|
|
|
+
|
|
|
+```json
|
|
|
+{ "model": "deepseek-flash[1m]",
|
|
|
+ "env": { "ANTHROPIC_MODEL": "deepseek-flash[1m]", "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-flash[1m]" },
|
|
|
+ "permissions": { "defaultMode": "bypassPermissions" } }
|
|
|
+```
|
|
|
+- 配置后**不需要也不应该**传 `--model`；网关自行路由，渠道故障 failover 到 glm 系
|
|
|
+- ⚠️ 网关把模型动态映射到其它上游模型是**正常 failover 行为**
|
|
|
+- `unrecognized_model` 警告可静默：`export CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`
|
|
|
+- 每次会话首次派发前 `cat settings.json` 确认 model 字段在位
|
|
|
+
|
|
|
+## 启动后 60 秒健康检查
|
|
|
+
|
|
|
+启动后 60 秒内必查（任一成立才算真运行中）：
|
|
|
+1. run.log 出现模型回复或工具调用
|
|
|
+2. 进程 CPU 时间在增长（`ps -o time= -p <pid>`）
|
|
|
+3. 目标仓库出现新改动（`git status --short`）
|
|
|
+
|
|
|
+`command not found` / 空日志 + exit=0 = 启动失败，禁止上报"运行中"。
|
|
|
+
|
|
|
+## 接任务秒回执 + 看板同源状态
|
|
|
+
|
|
|
+1. **接任务即秒回执**：第一条回复必须是一句话回执（收到+拆解成几件事+哪几件派后台+预计何时通知），先发回执再 spawn
|
|
|
+2. **任务状态与看板插件同源**：后台 CLI 任务生命周期四态 `ack→running→done/failed` + 30s 心跳，写入 reporter/看板 AgentTaskStatus 同源表——CLI 死亡（心跳停）= 看板与主 Agent 同刻可见
|
|
|
+3. **复盘基线**：9/9-9/10 实测 10 单，40% 静默率（死 4）是这套机制要消灭的数字
|
|
|
+
|
|
|
+## 交付验收三级穿透（Web/App 类交付强制）
|
|
|
+
|
|
|
+1. **源码层**：改动特征词在 src/ 里（`grep -c` > 0）
|
|
|
+2. **产物层**：dist 产物里 grep 同一特征词
|
|
|
+3. **线上层**：拉线上 URL 的 JS 产物再 grep（CDN 刷新后带 ?t=）
|
|
|
+
|
|
|
+**⚠️ 产物 grep 中文假阴性**：esbuild/Angular 产物把中文转成 `\uXXXX` 十六进制转义（大写十六进制）。直接 `grep 按时间` 恒为 0。正确姿势：先 `replace(/\\u([0-9A-Fa-f]{4})/g, ...)` 解码再统计。判别：产物中文密度 0 且转义 0 = 构建真坏；转义形态命中 = 构建正常只是 grep 姿势错。
|
|
|
+
|
|
|
+### 内容级复核（文档/方案类交付强制）
|
|
|
+
|
|
|
+CLI 自报 DONE 后，除产物/线上穿透外还要**内容级复核**：
|
|
|
+1. 敏感细节残留 grep：每条"删除/降级/提名化"指令逐项验收
|
|
|
+2. 署名/称呼在位：`grep 雨飏|袁`（袁=0、雨飏≥1）
|
|
|
+3. 措辞替换全链：本地/OBS源对象/线上三层字节级确认（CDN 缓存顽固，`curl ?v=参数`+刷新+等待60s复验）
|
|
|
+4. 修复动作主 Agent 亲手做（小补丁不值再派 CLI）
|
|
|
+
|
|
|
+## 通道熔断 / 账级故障
|
|
|
+
|
|
|
+- `403 Account is suspended due to billing` = **Fmode API 账号因账单被暂停**，只有用户充值能解，第一时间报告充值入口
|
|
|
+- `Invalid token` 401 = token/凭据问题（换 token）
|
|
|
+- `The response stopped arriving...` = API 响应中途断流，先盘点产物（可能已生成只差部署），收尾机械工作主 Agent 亲手做
|
|
|
+- **通道熔断 vs 单次偶发**：同通道连续 2-3 派、连最小任务都死 = 通道熔断停止重派；偶发单败 = 重试
|
|
|
+
|
|
|
+## delegate_task 子代理超时盘点与接管
|
|
|
+
|
|
|
+长任务子代理常以 timeout 结束（Fmode API 稳定性 + 3600s 上限）。**超时≠失败，先盘点再接管**：
|
|
|
+1. 盘点三处落盘：进度日志、git log（CC 常已完成大量 commit 只差报告）、目标产物文件
|
|
|
+2. 子代理统计数字必须亲验（`wc -c` 是字节不是字数，中文场景字节≈字数1.5倍）
|
|
|
+3. 部分完成分级：全落盘→直接验收；核心完成缺报告→自己补；关键步骤缺→主 Agent 接管补完
|
|
|
+4. 防丢设计进任务书：每件完成立即 commit push、进度每20分钟落盘
|
|
|
+
|
|
|
+## CC 失败形态全谱
|
|
|
+
|
|
|
+1. **静默死亡**：进程消失、无通知、零产物 → 盘点后原子重派或主Agent亲手
|
|
|
+2. **空手退出**：exit0 但无 DONE、只建空骨架 → 同静默死亡
|
|
|
+3. **乱码退出**：完成通知尾部是语义破碎乱码且无 DONE → 同静默死亡，产物重验
|
|
|
+4. **回执被吞**（benign）：无 DONE 但产物完整 → 先盘点别当失败重派
|
|
|
+5. **model catalog 拒绝**：模型名加 `[1m]` 后缀解
|
|
|
+6. **衍生保护**：CC 退出但产物完整只差 commit → 主 Agent 代为 commit 保护
|
|
|
+
|
|
|
+**五连败铁律**：同域任务连续 ≥5 次失败 = 该形态与 CC CLI 不兼容，停止重派，主 Agent + 底层协议完成。
|
|
|
+**单会话边界**：长文创作按"一课一派/一节一棒"拆，每棒一份 MD/HTML 即收工；素材阅读消耗预算，任务书里素材要么已提取摘要要么指明只读不自由探索。
|
|
|
+
|
|
|
+## Web 会话自动化是 CC 派发高危区
|
|
|
+
|
|
|
+"登录第三方 Web→多页表单/翻页→状态保持"类任务**不要整包派 CC CLI**（无头浏览器/SSO/反自动化是 CC 弱点）。拆到底层协议（requests 会话+CSRF+cookie）主 Agent 直接跑。派数据整合前先 grep 仓内已有数据（很多"采集任务"实为"整合任务"）。
|
|
|
+
|
|
|
+## 执行层纪律与合规复查
|
|
|
+
|
|
|
+用户会复查产出是不是 CC 做的——**拿会话痕迹自证**：
|
|
|
+1. `find ~/.claude/projects/-opt-data-<项目>/ -name "*.jsonl" -mmin <窗口> | wc -l`——近窗口零痕迹 = Orchestrator 违规亲手
|
|
|
+2. 违规处理：不辩论，出增量任务书让执行层重做，验收加"会话痕迹存在"维度
|
|
|
+3. "任务琐碎/CLI慢/中断过"都不是亲自干的理由
|
|
|
+4. **允许亲手例外**（判据=这活需要"判断"吗）：单点字符串替换、配置行级修改、纯机械部署、批量正则补丁
|
|
|
+
|
|
|
+## 权威事实喂料模式
|
|
|
+
|
|
|
+派发涉及**事实性内容**的任务，任务书必须内联第一手权威事实并明令"禁止编造"：
|
|
|
+- vision 解析结果喂料 / 全量数据源喂料 / 既有实现仓喂料 / session_search 挖历史喂料
|
|
|
+- 验收对照喂料事实逐项 grep，防 CC 换个名字编造
|
|
|
+
|
|
|
+## 交付铁律
|
|
|
+
|
|
|
+- 任务完成必须随回复附可点开交付物（URL/MEDIA），光说"完成"不算交付；主动交付=数字生命默认行为
|
|
|
+- 报告/文档禁交付 MD 原文，转浅色阅读版 HTML 发公开链接
|
|
|
+- **Web 应用交付必须给直连链接**：`<url>#token=<URI编码token>`（hash模式不暴露，截屏不泄露）；桌面/移动路由一并验证200
|
|
|
+- **Angular 子目录白屏根因**：`ng build --base-href="/dev/fmode-app/"` 缺失 → index.html `<base href="/">` → chunk 404 → 白屏。必须传 `--base-href` 且与 OBS 上传 URL 路径段一致。验证 grep dist/index.html `<base href>`
|
|
|
+
|
|
|
+## 关联参考
|
|
|
+
|
|
|
+- `references/hindsight-setup-pitfalls.md` — Hindsight 记忆插件接入全坑册
|
|
|
+- `scripts/md2html.py` — MD→浅色阅读版HTML 转换脚本
|
|
|
+- 相关技能: task-dispatch（自动调度分类）、fmode-brand-naming、claude-code-execution、skill-image
|
|
|
+
|
|
|
+## 验证
|
|
|
+
|
|
|
+- 任务完成后：交付文件存在 + `git log --stat` 与任务书清单一致 + 三要素下次启动仍通过
|
