dev-workflow

Yomiya 研发产品流转规范 v5.0

最后更新：2026-04-17 本文档是 Yomiya 研发流转的唯一政策源。历史口径如与本文冲突，以本文为准。

---

第一部分：目标与原则

1.1 目标

建立一套从需求出现到版本上线再到归档复盘的完整闭环，让 Captain 类技能在飞书日常语境里既能帮上忙，也不会把跟踪系统误当成产品真相。

1.2 核心工具链

• 飞书：日常沟通、触发、确认
• GitHub Issues：工作项权威记录
• GitHub Project #4：跨仓库版本与状态跟踪
• Yomiya skill：把聊天意图转成一致的研发动作

1.3 核心原则

• AI 默认推进，人负责拍板冲突和外部最终发布。
• 用户可见价值优先。
• 交付证据优先于跟踪状态。
• 不允许只根据 Project 字段直接宣布“完成”“测试通过”“已上线”。
• 版本动作必须先做范围对账，再决定写操作和文案。

1.4 三种事实的优先级

Captain 在任何对账场景都必须同时看三种事实：

1. product truth
   • 这次到底给哪个用户解决了什么问题，用户真的能感知到什么。
2. delivery evidence
   • PR、commit、截图、测试结果、上线记录等可验证证据。
3. tracking truth
   • Issue、Project Status、Version、Assignee 等跟踪字段。

决策顺序：

• 先确认 product truth
• 再确认 delivery evidence
• 最后把 tracking truth 修正到真实状态

不得让 tracking truth 反过来压过前两者。

---

第二部分：权威层级

2.1 文档与运行时的权责边界

权威层级固定如下：

1. team-consensus/dev-workflow.md
   • 唯一政策源
   • 定义状态模型、权限边界、产品事实对象、触发矩阵、输出顺序
2. skills/yomiya-dev-flow/references/*.md
   • 运行时切片
   • 只能派生和压缩执行规则，不能发明独立政策
3. skills/yomiya-dev-flow/SKILL.md
   • 入口调度器
   • 只负责装载顺序、路由 discipline、回复风格

2.2 可安装副本规则

yomiya skill 必须保持可直接安装，因此运行时目录中保留一份嵌入式镜像：

• skills/yomiya-dev-flow/references/full-workflow.md

这份文件是本文的运行时镜像，不是第二份权威源。任何修改都必须先改本文，再同步镜像。

2.3 回归测试规则

所有新规则都必须先落到回归样例，再进运行时文档。

• fixture 目录：team-consensus/evals/yomiya/
• 验证命令：python3 scripts/validate_yomiya_workflow.py

禁止“先改 prompt，后补规则”。

---

第三部分：Project 四状态与版本规则

3.1 Project #4 状态模型

唯一允许依赖的状态链：

Backlog → Ready → In review → Archived

禁止把以下逻辑状态当成 Project 实际字段使用：

• In progress
• Testing
• Done
• Released

如果需要表达“开发中”“待测试”“已发版未归档”等语义，必须放在执行逻辑、注释或输出结论里，不得假设 Project 中存在这些状态。

3.2 版本动作与状态映射

版本动作	Project 含义
准备测试	本轮纳入范围被收拢到可 review 范围，必要时进入 In review
测试通过	本轮通过项仍保持 In review，等待上线归档
已上线	本轮上线项进入 Archived

3.3 版本顺延规则

• 默认顺延到 patch+1：vX.X.N → vX.X.(N+1)
• 用户明确说“下个大版本”时，顺延到下一个 minor
• 用户明确指定版本号时，以用户指定为准
• 顺延前先确认本轮不纳入的原因

3.4 Project 字段最小集合

必须维护：

• Status
• Priority
• Platform
• Version
• Assignee

如果字段缺失，不得假装范围已经完整。

---

第四部分：产品事实对象

所有工作流都必须尽量保留同一套产品事实对象。最少要读，能补齐时要补齐。

字段	含义	使用时机
problem	当前要解决的具体问题	intake / reconcile
target_user	受影响或受益的用户	intake / release
user_value	用户可感知到的价值点	reconcile / release
delivery_type	feature / bugfix / polish / infra / hotfix	全流程
delivery_evidence	PR、commit、截图、测试结论、上线记录	reconcile / release
release_note_seed	可生成对外文案的原始价值点	release_pass / release_archive
scope_owner	当前范围由谁确认	reconcile / release
version_intent	应该归属哪个版本	intake / reconcile
roll_forward_rule	如果本轮不纳入，顺延到哪里	reconcile / release

规则：

• 没有 user_value 时，不要急着写用户文案。
• 没有 delivery_evidence 时，不要宣布测试通过或可归档。
• delivery_type=infra 时，默认进入内部纪要，不直接进入用户版更新说明。

4.1 版本事实来源

在 release 工作流中，如果检查了 MARKETING_VERSION、CURRENT_PROJECT_VERSION、plist 或其他版本元数据，必须标记来源：

• current workspace
• named git tag
• shipped artifact

若三者不一致：

• 必须同时披露当前工作区与 release tag / shipped artifact 的值
• release 判断以 named git tag 或 shipped artifact 为准
• 不得把 tag 值表述成当前工作区事实

---

第五部分：日常触发矩阵

5.1 核心意图家族

家族	主路由	典型说法	默认行为
录入	intake	提需求、记一下、提 bug、排进 backlog	创建或去重工作项，补产品事实
对账	reconcile	这个 issue 还开着但其实已经交付了、这次到底哪些用户能看到	对齐产品事实、交付证据、跟踪状态
推进	release_prep / release_pass / release_archive	准备测试、测试通过、已上线	先对账，再产出物，再决定写操作
查询	status_query	现在做什么、这个版本还有什么没收口、下版候选	只读输出，给下一步建议

特殊高风险动作：

• issue_close
  • 只用于明确要求关闭 issue、取消、替代
  • 如果 issue 已排入版本，默认先走对账，不直接关闭

5.2 典型短句映射

• “这个 issue 还开着但其实已经交付了” → reconcile
• “这次到底哪些用户能看到” → reconcile
• “这个版本还有什么没收口” → status_query
• “准备测试” / “提测” / “可以测了” → release_prep
• “测试通过” / “准备发布” / “发布就绪” → release_pass
• “已上线” / “审核通过了” / “发布了” → release_archive
• “关闭 issue” / “被别的方案替代了” → issue_close

5.3 冲突时的优先级

当一句话存在多种解释时，使用以下优先级：

1. release_archive
2. release_pass
3. release_prep
4. issue_close
5. reconcile
6. intake
7. status_query

若仍不明确，只追问一次，而且必须是窄问题。

---

第六部分：安全、权限与证据门槛

6.1 飞书上下文安全

DM：

• safe 动作可直接执行
• 当前轮明确授权的 confirm 动作可执行

群聊：

• safe 动作可直接执行
• confirm 动作必须先列出待执行写操作
• bare “继续” 不能当成写操作确认

6.2 风险等级

• safe
  • 查询、草稿、风险卡、测试清单、范围分析
• confirm
  • 创建 issue、加入 Project、修改 Status、修改 Version、关闭 issue、归档
• publish
  • 把外部文案当成最终版、对外正式定稿

6.3 GitHub Project 权限拆分

Project 读写权限必须分开判断：

• 读取 Project item / field / option：至少需要 read:project
• 修改 Project field、归档恢复、item-edit：需要 project

如果只有 read:project 没有 project：

• 可以完成查询、范围分析、字段对账
• 必须停在“待执行写操作”
• 不得假装已写入成功

6.4 已归档 item 的处理

如果目标 item 已归档，但又要重新纳回当前范围：

1. 先执行 unarchiveProjectV2Item
2. 再修改 Status / Version
3. 不允许跳过恢复步骤直接 edit

6.5 证据等级

等级	定义
E0	仅自然语言描述
E1	一类可验证证据
E2	两类证据互相印证
E3	合并、测试、上线链完整

最低门槛：

• 建议关闭 issue：E2
• 判定测试通过：E2
• 归档或把对外文案定为最终版：E3

6.6 Live release 证据类型

E3 中的 live-release 一段可以来自以下任一来源：

• DM 中用户对明确版本号的运营确认
• App Store Connect 状态或截图
• 公开 storefront 版本或 release notes
• 内部发布日志或自动化记录

规则：

• 若 merge + test 证据已存在，且用户在 DM 中明确说出 vX.Y.Z 已发布、vX.Y.Z 已上线、vX.Y.Z Ready for Sale，可视为 live-release 证据
• 如果 storefront 仍滞后，只需要披露“公开商店存在传播延迟”
• 不应默认再要求截图才能推进归档写操作
• 但 operator confirmation 只能推动归档 / Project 写操作，不能直接把外部发布文案视为最终定稿

---

第七部分：工作流切片

7.1 intake

目标：

• 把模糊聊天意图变成可追踪工作项
• 优先补齐 problem、target_user、user_value、version_intent

最小输出：

1. 建议仓库
2. 建议标题
3. 是否重复 / 是否疑似已实现
4. 待执行写操作

7.2 reconcile

目标：

• 不让“交付了但没收口”“Project 对不上真实范围”“用户价值不清晰”继续积累

固定输出顺序：

1. 用户可见价值
2. 交付证据
3. 范围对账
4. 待执行写操作

对账时必须同时回答：

• 用户到底会看到什么
• 证据是否足以支持这个判断
• Issue / Project 当前记录哪里不一致

7.3 release_prep

目标：

• 把“准备测试”变成一份可执行的提测包，而不是一句口头状态

固定输出顺序：

1. 用户可见价值
2. 交付证据
3. 范围对账
4. 待执行写操作

必做动作：

1. 拉取本轮 PR / commit 证据
2. 拉取 Version=vX.X.X 的 Project items
3. 做 PR vs Issue 对账
4. 标出“有 PR 无 issue”“有 issue 无证据”
5. 输出风险卡、测试清单、本轮范围、不纳入项

7.4 release_pass

目标：

• 锁定本轮真实交付范围，生成发布前草稿，不让技术细节污染用户文案

固定输出顺序：

1. 用户可见价值
2. 交付证据
3. 范围对账
4. 待执行写操作

规则：

• 先确定本轮保留项和顺延项，再写文案
• 纯技术改动默认进入内部纪要，不直接主导 What’s New
• 发现用户可见 PR 无 issue 时，必须标记补录，不得静默忽略
• 如果检查版本元数据，必须明确区分当前工作区、release tag、shipped artifact 的来源
• 一旦工作区与 release tag 不一致，必须同时写出两者，并声明 release 判断依赖哪一个

7.5 release_archive

目标：

• 完成本轮归档，沉淀正式版本纪要，并把下版候选带出来

固定输出顺序：

1. 用户可见价值
2. 交付证据
3. 范围对账
4. 待执行写操作

规则：

• 先归档本轮 item，再出正式归档纪要
• 检查是否属于直接 PR 交付版本
• 需要时补录归档 issue，保持追踪链完整
• 如果 operator confirmation 与 storefront 结果不一致，先披露延迟，再决定是否阻塞
• 在 DM 中，用户对明确版本号的 Ready for Sale / 已发布 / 已上线 确认可直接作为归档证据来源
• 不应把截图默认设为唯一继续条件

7.6 issue_close

目标：

• 清理 backlog，但不错误关闭版本内交付项

规则：

• 已排入具体版本的 issue 不直接关闭
• 若出现“其实已交付但没收口”，先走 reconcile
• 被替代时必须 comment 写清替代关系

7.7 status_query

目标：

• 保持只读，快速告诉用户当前范围、未收口项和下一步建议

默认输出：

1. 用户可见价值
2. 交付证据
3. 未收口项
4. 建议下一步

不得把查询自动升级为写操作。

---

第八部分：PR / Issue 对账与直接 PR 交付

8.1 Scope 对账是强制步骤

在 release_prep 和 release_pass 中，必须输出三类结果：

1. 有 PR 覆盖且有 issue
2. 有 PR 但无 issue
3. 有 issue 但无可验证交付证据

8.2 直接 PR 交付的处理

若本轮用户可见交付里，超过一半来自“有 PR 但无 issue”：

• release_pass：先标记补录需求
• release_archive：必要时自动补录归档 issue，并设为 Archived 后关闭

补录 issue 的目的不是补手续，而是保留版本链路和用户价值描述。

---

第九部分：版本文案与 ASO

9.1 文案原则

• 只写用户可感知结果，不写底层实现细节
• 多个零散修复可以收口为稳定性提升
• delivery_type=infra 的内容默认只进内部纪要
• 用户可见价值优先，技术描述靠后

9.2 必产出物

release_pass 草稿阶段：

• 内部版版本纪要
• What’s New 草稿
• 六语言草稿：zh-Hans / zh-Hant / en / ja / ko / vi
• Promotional Text 草稿
• ASO 判断表

release_archive 正式阶段：

• 正式内部归档版
• 正式 What’s New
• 六语言正式版
• ASO 判断表
• 截图刷新检查清单
• 下版候选

9.3 ASO 联动

生成 What’s New 或 Promotional Text 前，必须读取最新 aso/ 报告。

当使用 gh api 获取 aso/ 目录或 git tree 且 endpoint 带 query string 时，必须加单引号，例如：

gh api 'repos/IntelliFuture/root/contents/aso?ref=main'
gh api 'repos/IntelliFuture/root/git/trees/main?recursive=1'

否则在 zsh 下可能触发 no matches found。

关键词策略：

• 先从真实改动点出发
• 再映射到高价值关键词
• 不为了塞词扭曲用户价值表述

---

第十部分：测试与回归

10.1 Fixture 目录

team-consensus/evals/yomiya/ 当前至少覆盖：

• open_issue_but_delivered
• project_read_but_no_write_scope
• archived_item_needs_unarchive
• user_visible_pr_without_issue
• technical_only_change_should_not_pollute_release_notes
• group_chat_requires_confirmation
• daily_reconcile_trigger
• version_scope_query
• release_pass_version_fact_source
• release_archive_operator_confirmation
• gh_api_query_quoting

10.2 变更纪律

• 新规则先加 fixture，再改运行时
• 运行时切片不能与本文冲突
• 修改 skill 后必须运行 python3 scripts/validate_yomiya_workflow.py

只有文档、fixture、运行时三者一致，这个 skill 才算真正可用。