hmos-flow · 鸿蒙多项目 Agent 开发工作流

把 PRD 拆解为可执行任务 DAG，按任务类型与依赖关系分派给专职智能体，以可判定 Gate 串接八个阶段，并汇总交付结果。本 Skill 是编排内核，不承载具体领域知识 —— 领域知识由被引用的 OHOS-Skills 领域 Skill 提供。

When to Use

• 拿到一份鸿蒙 PRD / 需求文档，需要拆解为可执行的开发任务并推进到交付
• 需要多个智能体并行开发同一项目的不同模块，或并行推进多个鸿蒙项目
• 需要为开发、构建修复、测试、代码审查分别建立独立职责与权限边界
• 需要在阶段之间设置可验证的质量门禁（编译、lint、测试、审查、合规）
• 需要把多项目运行中的共性知识沉淀回 Skill 仓库

不适用：单文件小改动（直接用 arkts-helper）；只需查文档（harmony-fetch）；只需修一个编译错误（arkts-debug）。先简后繁 —— 需求能在一个上下文内闭环时不要启用编排。

Boundary with Other Skills

本 Skill 位于编排层，调用而非替代领域 Skill。

Workflow (Follow Strictly)

严格按以下步骤执行。任何一步的产出不符合 schema 即视为失败，不得静默放行。

第 1 步：初始化状态目录

在项目根执行。Windows 用 python（无 python3 别名）；Linux / macOS / HarmonyOS 用 python3（HarmonyOS 上 python 可能不存在）：

python <skill_dir>/scripts/init_flow.py --project . --kind app

--kind 取 app / atomic_service / arkui_x，决定启用哪些平台红线判据。产出 <project>/.hmos-flow/ 骨架。若目录已存在则不覆盖，仅校验完整性。

第 2 步：S0 需求接入 —— 派发 PRD 解析

以 agents/hmos-prd-analyst.md 为角色定义派发任务，输入 PRD 路径。产出 .hmos-flow/prd/requirements.json。

跑 G1 校验：

python <skill_dir>/scripts/gate_check.py --project . --gate G1

G1 判据：每条需求有可验证验收标准；无 TBD/待定；open_questions 为空。不通过则停止并交人工补齐。

第 3 步：S1 任务规划 —— 派发 Planner

以 agents/hmos-planner.md 为角色定义派发，输入 requirements.json + 工程结构 + 历史 progress_ledger。产出 .hmos-flow/plan/tasks.json（TaskSpec DAG）。

跑 G2 校验（DAG 无环、四要素齐全、单任务预估工具调用 ≤ 30、写区重叠率 < 20%）：

python <skill_dir>/scripts/gate_check.py --project . --gate G2

关键路径超阈值或任务数超阈值时，必须先请求人工审阅计划再继续。

第 4 步：S2–S3 设计与实现 —— 按类型路由、按依赖并发

按 TaskSpec.type 查本文件「任务类型路由表」确定性分派。不要用模型去猜路由，类型未命中才允许一次模型判定兜底，并记录理由。

派发前做两项静态检查（必须）：

1. 依赖检查：depends_on 全部 succeeded 才入就绪队列
2. 写区检查：待派发任务的 writes glob 与所有 running 任务的写区有交集 → 挂起，不得并行

就绪队列排序键：(优先级降序, 关键路径长度降序, 创建时间升序)。

第 5 步：G4 构建门禁

实现阶段结束后跑 build_fix 任务（agents/hmos-build-fix.md），最多 3 轮。每轮必须调用 codelinter 并留痕 —— G4 会断言 codelinter 出现在 trace 的工具调用集合中，缺失即判失败。

python <skill_dir>/scripts/gate_check.py --project . --gate G4 --trace traces/<trace_id>.jsonl

第 6 步：S4–S5 测试与审查

测试并发上限 = 可用真机 / 仿真器数量，不是模型配额。审查角色强制只读，其产出必须是 ReviewVerdict{blockers, majors, minors, score, verdict}，修订 ≤ 2 轮，第 3 次仍不通过则升级人工，不允许智能体无限自证。

第 7 步：S6 发布与 S7 复盘

签名、上传、远程推送、删除类操作属高风险工具，执行前必须请求人工批准（门下沉到工具级，而不是拦整个智能体输出）。

G7 校验：

python <skill_dir>/scripts/gate_check.py --project . --gate G7

复盘阶段把共性经验结构化写入 ledger/progress_ledger.json，格式 {task_type, failure_cause, lesson, suggestion}，供后续项目规划时按 task_type 检索。

第 8 步：结果汇总

交付报告由编排者独占撰写，不得由各 Worker 各写一段后拼接。报告须含：需求覆盖矩阵、任务统计、质量指标、遗留问题、Token/成本。

任务类型路由表

委托契约（四要素必须齐全）

缺少任一要素的委托会导致子智能体跑偏或重复劳动 —— 这是已验证的高频失败模式。

{
  "id": "T-042",
  "title": "实现天气卡片 2x2 / 2x4 双尺寸布局",
  "type": "impl_arkts",
  "req_ids": ["REQ-07"],
  "goal": {
    "description": "按 design/weather-card.spec.md 实现卡片组件",
    "dod": ["codelinter 0 error", "两种尺寸通过快照测试", "状态管理统一用 V2"]
  },
  "output": { "schema": "TaskResult", "must_include": ["summary", "artifacts", "facts"] },
  "context": {
    "skill_pack": ["arkts-helper", "harmony-design"],
    "reads": ["design/weather-card.spec.md"],
    "writes": ["features/weather/src/main/ets/view/WeatherCard.ets"]
  },
  "depends_on": ["T-031"],
  "budget": { "max_tool_calls": 30, "max_tokens": 120000, "timeout_s": 900 },
  "risk": "low"
}

TaskResult 回传：{task_id, status, summary, artifacts[], facts{}, open_issues[], usage{}}。summary 硬上限 500 Token，超限即 schema 校验失败 —— 收益来自「子智能体做重活、只回传压缩摘要」，开放式的「总结一下你发现了什么」会稳定产出过长且昂贵的响应。

协同纪律（不可协商）

1. Worker 之间禁止直接对话。所有跨角色信息经 ledger/ 或 artifacts/ 传递，保证可审计。
2. 产物外置：大文件写入 artifacts/<task_id>/，账本只存 path + digest，上下文只传引用。
3. 越权即失败：Worker 改动了 writes 之外的文件 → TaskResult 判失败并回滚。
4. 循环有界：构建修复 ≤ 3 轮、审查修订 ≤ 2 轮、重规划 ≤ 2 次、单任务工具调用 ≤ 30 步。
5. 未达法定人数不放行：并行分支未达 Quorum 按工作流失败处理，可重试或升级人工，不得静默降级输出。
6. 功能判据用可执行验证，主观判据才用模型评分：编译、测试、体积、签名一律用命令结果；设计一致性与代码质量才用评分，且评分模型应与被评模型不同族。

平台差异

本 Skill 的角色卡与状态目录在各平台通用，但派发机制与门禁执行方式不同，分派前必须读 references/PLATFORM-MAPPING.md 并按目标平台调整：

• ZCode：@角色名 显式调用或按 description 自动委派；Gate 可用 Goal 模式承载
• WorkBuddy：无自定义子智能体注册表（平台无 agents/ 落点），派发提示中写明角色卡实际路径 —— 由 deploy_agents.py --platform workbuddy 输出的 role_card_dir 解析，不要写死 ~/.workbuddy/skills/；并发靠后台派发；只读角色派发时指定 mode: plan

有一条硬的架构约束：部分平台（如 ZCode）禁止子智能体再派生子智能体。因此 Project Lead 必须由主会话承担，不能实现为子智能体 —— 编排层的双账本维护、Gate 判定、失败处置都在主会话完成，Worker 才是被派发的一方。在允许嵌套的平台上也不要把 Project Lead 下沉，因为它需要全局视图与跨 Worker 的写权限。