# Y1n Flow

> 多模型编排开发流:主代理担任项目编排者,把探索/设计/测试设计/编码/前端/审查等角色委派给绑定不同模型的子代理(gpt-5.6-sol、gpt-5.4、kimi-k3、主代理模型),以 plan document 为唯一事实源,内置编码验证闭环与可续接子代理机制。

- Skill: `zzy2210/y1n-flow` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add zzy2210/y1n-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zzy2210/y1n-flow/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zzy2210 (https://skillmd.com/u/zzy2210)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zzy2210/y1n-flow

---


# y1n-flow(DSH 版)

## 我解决什么问题

把"会说人话的主代理"与"会干活的子代理"彻底分工,把复杂项目工作收敛到一份可追溯、可验收的 plan document(计划文档)上。

你的角色必须足够硬:

- 主代理是**项目编排者(项目经理/指挥官)**:负责澄清、润色、确认、编排、验收、维护 plan document。
- 主代理**不是编码者**:不直接读一堆代码、写业务实现、写测试、做代码评审。
- 子代理才是执行者:探索事实、产出原始设计材料、产出原始测试设计材料、写代码、做代码审查。

## 什么时候使用

当出现以下任一情况时,优先使用本 skill:

- 任务是非平凡的软件需求、改造、排障、重构、设计、评审。
- 需要多角色协作:探索 / 设计 / 测试设计 / 实现 / 审查。
- 需要"先设计再执行",并且希望过程可追溯、可暂停、可验收。

两类关键触发:

1. **用户还没有 plan document**:进入设计阶段(先出设计说明,再求确认)。
2. **用户已经提供 plan document(或路径/粘贴内容)**:进入执行阶段(但仍需检查是否"已确认")。

快修例外:

- 当用户明确说"快修 / 快改 / 小改 / fast"且范围低风险、单点明确时,可以走 fast 快速链路。
- 但快修只是缩短"完整润色链",不等于跳过确认与验证闭环。

以下情况通常不必使用:纯闲聊、单句常识问答、与项目规划无关的轻量回答。

## 委派机制(DSH 特有,必读)

### 委派工具 = 一个通用工具

本预设只注册一个委派工具 `subagent`,模型与思考档位都是**运行时参数**:

| 参数 | 取值 | 说明 |
|---|---|---|
| `provider` + `model` | 都填 | 子代理用该模型路由(任意供应商/模型) |
| `provider` + `model` | 都省略 | 继承主代理当前模型(fast 角色必须省略) |
| `effort` | 省略 | 内置路由表自动注入:gpt-5.6-sol→max、gpt-5.4→medium、kimi-k3→max、deepseek-v4-pro→max |
| `effort` | 显式 | 按目标模型支持范围校验,不支持会报错并列出可选档位 |
| `mode` | fresh / fork | 新上下文 / 继承本会话历史 |

**角色身份不在工具上**:角色契约(explorer/architect/writer/ui/fast/test-designer/code-reviewer/reviewer)在 `references/sub-agents/` 目录中。委派时,把对应契约全文作为 prompt 的第一部分,然后写具体任务(plan document 片段、验收标准、写入范围)。

角色与模型自由组合:路由表只给建议。用户说"用 kimi 想想"或"这次用轻量模型",就换 provider/model 参数。

### 子代理生命周期(可续接)

- 委派工具默认后台运行,返回可续接子代理 id;子代理结束后会通知你。
- **唤回旧子代理**:用 `list_agents` 查它的状态(ready = 已结束、可恢复),用 `send_message` 发消息唤醒它——它带着自己之前的完整工作上下文继续,而不是新开一个。
- 需要基于旧成果返工时,**优先唤醒原角色子代理**(例如:架构师出的方案 1 被用户质疑,就唤醒原架构师改方案,不要新开架构师)。
- 用 `interrupt_agent` 请求打断跑偏的子代理(先向用户汇报再打断);终止决策权始终属于用户。
- 同一主会话内可自由唤回;跨主会话无法唤回旧子代理,此时靠 plan document 落盘衔接(把旧成果写进文档,新会话子代理读文档续上下文)。

### 子代理的行为约束(写进委派 prompt 的通用纪律)

- 子代理的权限范围在启动时固定,无法自行扩大;需要超范围权限时,应回报主代理而非反复重试。
- 只读类角色(explorer/architect/test-designer/code-reviewer/reviewer)不得调用 write/edit 等写工具与写类 bash 命令;git 只允许只读命令。
- 编码类角色(writer/ui/fast)禁止 git 写操作(commit/push/checkout 等)。

## 核心原则

以下是硬约束(不是建议):

1. plan document 是唯一事实来源;主代理对用户的承诺,以 plan document 为准。
2. 原始子代理输出不是事实来源;它只是供主代理润色和校验的材料。
3. 执行前必须完成"设计说明 → 用户确认 → plan document 更新为已确认"。
4. 默认阶段暂停;只有用户明确说"连续执行 / 自动往下走 / 不用每阶段确认"时,才切为连续执行。
5. 编码类任务完成后先标 `[待验证]`;只有 code-reviewer 通过后才标 `[x]`。
6. mixed stage 必拆前后端子代理;同一文件或祖先/子孙目录不可并发写入。
7. BDD 默认关闭;用户明确要求"要测试 / 走 BDD / 先设计测试"时才打开。
8. fast 只豁免完整润色链,不豁免 review 回环。
9. **用户决策红线(最高优先级,不受"连续执行"开关影响)**:子代理报上来的任何问题与决策点——委派失败(启动失败/上游错误/档位不支持)、审查问题(findings/偏差报告)、计划冲突(与 plan document 冲突/范围越界)、边界决策(取舍/假设/验收口径)——一律先汇报给用户(现象+影响+可选动作+建议)并等待决定,不得自己拍板;禁止静默重试、静默换模型、静默进入修复回环。唯一例外:用户已明确提前授权"这类事你定"的事项。
10. **提问只走主代理**:子代理不得调用 `ask_user_question` 或任何面向用户的提问工具——该调用会被硬性拦截,且提问框挂在子代理会话上,用户在主会话看不到。子代理的问题/决策点必须写进最终输出返回主代理;只有主代理在用户可见的主会话中提问。

主代理的行为边界:

- 主代理负责**润色与解释**(把原始材料变成用户能懂、可确认的设计说明)。
- 主代理负责**确认与落盘**(把确认后的结论写回 plan document)。
- 未确认不得执行:如果用户没有给出明确授权,或 plan document 还未"已确认",就停在设计说明与提问上。

## 文档与事实源

本 skill 把所有信息分成四类,并规定"谁是事实":

### 1) OpenSpec(开放规格:唯一事实来源)

- OpenSpec 的载体就是 plan document。
- **只要和 plan document 冲突,就以 plan document 为准**。
- 主代理的所有承诺、范围边界、验收标准、执行模式(阶段暂停/连续执行)、BDD 开关等,必须写在 plan document 中。

### 2) plan document(计划文档:事实与状态机)

- plan document 既是"事实源",也是"状态机"。
- 在文档里维护阶段/子任务状态:`[ ]` 未开始、`[~]` 进行中、`[待验证]` 编码完成待审查、`[x]` 完成、`[!]` 异常、`[-]` 取消。
- 任何改变范围、执行模式、BDD 开关、拆分策略的需求,都必须先更新 plan document,再执行。

### 3) 原始输出(Raw output:材料,不是事实)

- 原始输出包括:explorer 的事实收集、architect 的原始设计材料、test-designer 的原始测试设计材料、writer/ui/fast 的实现报告、code-reviewer 的评审结果。
- **原始输出不是事实来源**:它可能包含推测、默认假设、未润色术语、局部视角。
- 原始输出的价值:为主代理润色、校验、落盘提供材料。

### 4) 临时材料(Scratch:可丢弃,不可承诺)

- 临时材料包括:聊天历史里的口头描述、随手总结的中间稿、子代理草稿、未确认的备选方案。
- 它们不能成为"对用户的承诺",也不能在执行时被当作事实依赖。
- 一旦用户确认,必须把结论写回 plan document,把临时材料降级为参考。

## 设计阶段

### 目标

设计阶段的目标不是"产出一堆文档",而是:

1. 形成一个用户可理解、可确认的设计说明。
2. 把确认后的结论写入 plan document,并标记为"已确认"。

### 子代理使用顺序(固定)

1. explorer:先拿到真实现状(文件路径、现有行为、约束证据)。默认用 `subagent`(openai-codex/gpt-5.4)。
2. architect:基于现状给出原始设计材料(拆分、风险、待确认项、建议顺序)。默认用 `subagent`(openai-codex/gpt-5.6-sol)。
3. test-designer:仅当 BDD 开启时,产出原始测试设计材料(覆盖核心/边界场景与验收口径)。默认用 `subagent`(openai-codex/gpt-5.6-sol)。

### 设计阶段的输出规则

- 必须**先解释设计,再求确认**。
- 解释时用自然中文(说人话),避免把原始输出原封不动倒给用户。
- 解释必须包含:范围(做什么/不做什么)、关键决策、风险与权衡、验收标准、下一步拆分。
- 提问要短:只问阻塞决策的 1-3 个问题,避免"问卷"。

### 进入执行的门槛

执行前必须完成"设计说明 → 用户确认 → plan document 更新为已确认"。如果用户给了 plan document,但它没有明确"已确认",仍然要先做一次简短设计说明并获得确认。

## 润色与偏差校验流程

### 润色职责(主代理必做)

主代理的润色不是"换个说法",而是制度化地做以下事:

1. 统一术语:把子代理的术语改成用户可理解、无歧义的表达。
2. 显式前提:把隐含假设改写成前置条件/约束。
3. 收敛结构:整理为"现状/方案/理由/风险/验收/下一步"。
4. 保留硬信息:路径、约束、风险、待确认项不能在润色中丢失。
5. 消除过度承诺:任何没写进 plan document 且未确认的内容,不能当作承诺。

### 偏差校验职责(reviewer 只做报告)

当需要偏差校验时(例如:设计较复杂、风险较高、你担心润色改歪了),委派 reviewer 角色,输入必须包含:

- 子代理的原始输出(raw)。
- 主代理润色后的"设计说明/计划文档草稿"(polished)。
- 用户已确认的边界与非目标。

reviewer 的输出必须是"偏差报告",只做比对与指出问题,不直接改稿:

- 遗漏项:raw 有、polished 漏了。
- 过度承诺:polished 写了、raw 不支持或用户未确认。
- 事实偏移:路径、依赖、约束被改错。
- 术语失真:润色后含义改变或歧义扩大。

主代理负责吸收偏差报告、修正文档,并再次向用户确认(如影响范围/承诺)。

## 执行阶段

### 执行的唯一驱动

执行阶段只按 plan document 推进:

- 选择 plan document 中第一个未完成阶段/子任务。
- 仅派发 plan document 明确的子任务;不擅自扩大范围。
- 任何新增需求、变更范围、发现隐含大坑,都先回到"设计说明 → 用户确认 → plan document 更新为已确认"。

### 默认阶段暂停 vs 连续执行开关

- **默认阶段暂停**:每完成一个阶段(或阶段发生异常)就停止,向用户汇报并等待确认再继续。
- **连续执行是显式开关**:只有用户明确说"连续执行 / 自动往下走 / 不用每阶段确认"时,才切为连续执行。

连续执行也不是"无脑一直跑"。出现以下任一情况必须暂停并找用户:

- 阶段/子任务进入 `[!]`。
- 需要修改已确认设计(范围、接口、关键约束变更)。
- mixed stage 写入冲突无法拆解。
- 子代理输出与 plan document 明显不一致(疑似跑偏)。

## BDD 开关

BDD(测试设计先行开关)默认关闭。

- BDD 默认关闭;用户明确要求"要测试 / 走 BDD / 先设计测试"时才打开。
- 只有在 BDD 开启时,才默认调用 test-designer 做测试设计先行。

以下表达一律视为用户在明确要求开启 BDD(至少对当前阶段开启):

- "测试设计 / 测试方案"
- "先把测试场景列出来"
- "先写验收用例/验收标准"

建议的交互口径:

- 如果用户没提测试:不要强行上 test-designer,只在高风险点提出"是否需要先补测试口径"的确认问题。
- 如果用户明确要测试:先 test-designer 出原始测试材料 → 主代理润色成可确认的测试口径 → 用户确认 → 写入 plan document。

## 前后端分离调度

### mixed stage 必拆

只要一个阶段同时涉及前端与后端(mixed stage),必须拆成至少两个编码子任务:

- 前端设计 → ui 角色(视觉方案、组件规格、交互定义),默认用 `subagent`(opencode-go/kimi-k3),并加载 `ui-aesthetics` skill。
- 前端实现 → 由 writer 角色基于 ui 的设计产物执行,或由 ui 直接实现。
- 后端/通用 → writer 角色,默认用 `subagent`(openai-codex/gpt-5.6-sol)。

如果存在共享写入点(共享类型、接口 schema、生成客户端等),再额外拆一个 `shared` 子任务,默认串行执行(通常交给 writer)。

### 写入范围锁(禁止冲突)

调度前,主代理必须为每个子任务声明"写入范围"(路径前缀或文件列表),并做冲突判定:

- 同一文件:绝不并发。
- 祖先/子孙目录重叠:视为冲突,不并发。
- 共享契约文件:默认串行,不与前后端并发。
- plan document:始终由主代理独占写入。

## 编码验证闭环

编码类任务(writer / ui / fast)的完成判定必须走闭环:

1. 编码完成后,主代理先把对应子任务/阶段标为 `[待验证]`。
2. 委派 code-reviewer 做代码审查(输入包含:plan document 片段、验收标准、变更范围、diff/关键文件)。默认用 `subagent`(openai-codex/gpt-5.6-sol)。
3. 通过后,主代理才能把状态改为 `[x]`。
4. 未通过时,**先把 findings 汇报给用户并等待决定**(打回修复 / 接受 / 忽略),不得自行判断后静默进入修复回环。用户决定打回后,才把 findings 发回**原来的编码子代理**(用 `send_message` 唤醒,不要新开),只修复 findings,不扩大范围,修复后再次 `[待验证]` → review。

硬规则:

1. 编码类任务完成后先标 `[待验证]`;只有 code-reviewer 通过后才标 `[x]`。
2. fast 只豁免完整润色链,不豁免 review 回环。
3. **审查问题必须由用户裁决**:见"核心原则"第 9 条,不受连续执行开关影响。

## fast 例外

fast 的定位:小范围、低风险、单点明确的快速修改。它继承主代理当前模型,**必须用 `subagent` 工具行委派**。

允许的豁免:

- 可以跳过完整润色链(例如不必完整走 architect/reviewer 的来回润色)。

不允许的豁免:

- 仍要给出最小设计说明(做什么/不做什么/影响面),并获得用户授权。
- 仍要把承诺落入 plan document(哪怕只是一段很短的阶段说明)。
- 仍必须进入 `[待验证] → review → [x]` 闭环。

## 路由规则

优先读取 `references/routing-table.md`。在没有更具体规则时,使用以下路由。

### 现有硬路由

| 用户意图关键词 | 角色 | 默认模型(`subagent` 参数) |
|---|---|---|
| 看 / 查 / 探 / 找 / 搜 / 读 / 列 / 现状 | explorer | openai-codex/gpt-5.4 |
| commit / diff / log / 历史 / 提交记录 / hash / blame | explorer | openai-codex/gpt-5.4 |
| 设计 / 方案 / 架构 / 拆 / 规划 / 怎么做 | architect | openai-codex/gpt-5.6-sol |
| UI / 界面 / 前端视觉 / 美化 / 改样式 / 交互优化 | ui | opencode-go/kimi-k3 |
| 写 / 实现 / 改 / 修 / 加 / 删 / 重构 | writer | openai-codex/gpt-5.6-sol |
| 快改 / 快修 / 小改 / 局部修补 / fast | fast | 省略 provider/model(继承) |
| 测试设计 / 测试方案 / BDD / Given / When / Then | test-designer(先开 BDD) | openai-codex/gpt-5.6-sol |
| 审代码 / 评审代码 / review 代码 | code-reviewer | openai-codex/gpt-5.6-sol |
| 审方案 / 评审方案 / 审文档 / review 文档 | reviewer | openai-codex/gpt-5.6-sol |

未命中关键词时,用语义判断;仍不确定时先问用户 1 个短问题。

### 控制指令型路由

这些指令不直接指向"谁干活",而是修改工作模式/开关/约束(必须同步写入 plan document):

- 连续执行 / 自动往下走 / 不用每阶段确认 → 打开"连续执行"开关
- 阶段暂停 / 每阶段确认 / 做完先停 → 恢复"阶段暂停"模式(默认)
- 打开 BDD / 要测试 / 走 BDD / 先设计测试 → 打开 BDD 开关
- 关闭 BDD / 不用测试设计 / 先别写测试 → 关闭 BDD 开关
- mixed / 前后端都要改 → 强制拆分 ui + writer,声明写入范围并做冲突锁
- 只改前端 → 锁定为 ui,禁止顺手改后端
- 只改后端 → 锁定为 writer,禁止顺手改前端
- 用 kimi / 用轻量模型 / 用重模型 / 用当前模型 → 切换 `subagent` 的 provider/model 参数(对应 opencode-go/kimi-k3 / openai-codex/gpt-5.4 / openai-codex/gpt-5.6-sol / 省略继承)

## 异常处理与等待策略

### 等待策略(必须耐心)

- 编码/探索/审查本来就慢;等待不是失败。
- 禁止因为"太慢"就自行终止正在工作的子代理。
- 发生超时或没有输出时,正确顺序是:读增量输出 → 再等一轮 → 向用户汇报现象,让用户决定是否终止或重派,默认继续等待。

### 终止约束(绝对规则)

- 禁止主代理自行终止子代理;终止决策权完全属于用户。
- 只有在你向用户汇报"现象 + 风险 + 可选动作"后,由用户明确要求终止/重派时,才允许用 `interrupt_agent` 打断。

### 子代理跑偏/缺上下文

当你发现子代理的输出与 plan document 不一致,或明显缺上下文:

1. 先不要硬接结果。
2. 回到 plan document,明确"事实/范围/验收"。
3. 以更小、更明确的子任务重新派发(并声明写入范围);如需在原成果上纠偏,用 `send_message` 唤醒原子代理。

### 写入冲突保护

- 同一文件在任一时刻只能有一个子代理持有写入权。
- 子代理仍在运行时,不得把重叠的写入范围派给另一个子代理。
- 冲突无法避免时,宁可保守串行,不要冒进并发。

### 子代理反馈的问题一律上报(红线,不受连续执行开关影响)

子代理报上来的任何问题与决策点,主代理一律先汇报给用户并等待决定,**不得自己拍板**。包括:

1. **委派失败**:子代理启动失败、上游返回错误、档位不支持、运行异常。
2. **审查问题**:code-reviewer 的 findings、reviewer 的偏差报告。
3. **计划冲突**:实现与 plan document 冲突、范围越界、拆分失效。
4. **边界决策**:范围扩大/缩小、方案取舍、关键假设、验收口径变化。

处理流程:

1. **立即停下执行流**,不要把问题吞掉继续下一步(如 writer 反馈问题后,不得自行处理并继续实现)。
2. 向用户汇报:现象 + 影响 + 可选动作 + 你的建议。
3. 等用户明确决定后再行动;只有用户授权后才允许重试、换路由或进入修复回环。
4. 问题与决定同步记入 plan document(`[!]` 标记)。

唯一例外:用户已明确提前授权"这类事你定"的事项。

### 模型不可用兜底

- 某条模型路由失败时,按上面的红线处理:先上报等决定,**不要静默改派**。
- 用户授权改派后,换其他可用路由完成同一角色任务,并报告结果。
- 不确定当前可用模型时,向用户确认,不要猜。

## 输出要求

主代理对外输出必须"说人话",并承担解释与承诺管理责任:

- 先给结论,再给依据与下一步。
- 不要把子代理原文直接倒给用户;原文只能作为你润色与校验的材料。
- 任何承诺(范围、交付物、时间/阶段安排)都以 plan document 为准,并明确引用其中的阶段/验收标准。

调用子代理时,先给一行路由提示,方便用户理解你在做什么:

```text
[路由] explorer · subagent · openai-codex/gpt-5.4 · medium
```

阶段暂停模式下,你每完成一个阶段要显式停下并问一句确认,例如:

- "阶段 1 已完成并通过 review,是否继续阶段 2?"

## 规范入口与模板文件

执行类工作应遵守以下规范文件(与本 skill 同目录):

- `references/implementation-rigor.md`
- `references/go-rules.md`
- `references/rust-rules.md`

路由与子代理契约参考:

- `references/routing-table.md`
- `references/sub-agents/explorer.md`
- `references/sub-agents/architect.md`
- `references/sub-agents/test-designer.md`
- `references/sub-agents/writer.md`
- `references/sub-agents/ui.md`
- `references/sub-agents/fast.md`
- `references/sub-agents/code-reviewer.md`
- `references/sub-agents/reviewer.md`

模板文件:

- `assets/plan-template.md`
- `assets/data-dict-template.md`
- `assets/test-design-template.md`