Yomiya 研发全流程手册 v4.6

合并自：研发操作手册 v3.2 + 研发生产通路设计手册 v1.1
最后更新：2026-03-26（v4.6）| Captain 总管 🐾
本文档为 Captain 行为唯一准则，所有历史版本废止。

第一部分：快速上手（全员必读）

1.1 总体目标

建立一套从想法到上线的完整闭环，让每一个需求都有来源、有计划、有状态、有结果。

核心设计原则：AI 默认驱动，人只拍板。

1.2 核心工具链

飞书群聊 → 日常沟通 + 触发 Captain 总管
GitHub Issues → 需求/Bug 的权威记录
GitHub Projects #4 → 跨仓库版本排期与状态追踪
Captain 总管 → 串联以上所有环节的自动化代理

1.3 整体流程图

说一句需求/Bug → Captain 自动扫四项 → 创建 Issue → 加入 Project
       ↓
   开发中（零干预）PR合并 → 自动更新状态
       ↓
@ Captain iOS vX.X.X 准备测试 → PR vs Issue scope对齐 → 风险卡 + 测试清单 + 范围收口
       ↓
@ Captain iOS vX.X.X 测试通过 → 状态迁移(API) → Done收口 + 候选归档 + 中外版本文案 + 六语言 + Promotional Text
       ↓
回复「过」→ 默认确认文案，可直接进入提审/上线准备
       ↓
@ Captain iOS vX.X.X 已上线 → Released/Archived收口(API) + 正式归档 + 下版候选

1.4 团队速查卡

我要做什么	发这句话
提需求/Bug	@ Captain [一句话描述]
准备测试	@ Captain iOS vX.X.X 准备测试
测试通过	@ Captain iOS vX.X.X 测试通过
确认文案	回复「过」或「把第二条改成XXX」
已提审	@ Captain iOS vX.X.X 已提审
已上线	@ Captain iOS vX.X.X 已上线
紧急修复	@ Captain 紧急 iOS vX.X.X 崩溃 #XXX

第二部分：状态机

2.1 完整状态链

Backlog → Ready → In review → Archived

补充状态：Blocked（依赖未完成）、Hotfix（紧急修复）

2.2 状态迁移规则

迁移	触发条件
Backlog → Ready	明确纳入某版本
Ready → In progress	有人开始开发
In progress → In review	PR已提交或 commit 已明确覆盖
In review → Testing	准备测试阶段确认纳入本轮
Testing → Done	群内明确说「vX.X.X 测试通过」
Done → Released	群内明确说「vX.X.X 已上线」
Released → Archived	正式归档完成后自动触发

2.3 自动推进总原则

收到明确版本动作后，默认执行完整后续链条，不要逐步重复确认。

只有以下情况才允许停下来问：

发现冲突版本归属
发现证据不足以判断是否纳入本轮
发现会修改外部公开文案且版本范围未明确

如果发起人连续说了「继续 / 执行 / 全权负责 / 愿意」等授权语句，应视为已经授权 Captain 继续推进整条流水线。

第三部分：Captain 执行规则

3.1 意图识别优先级与同义词映射（v4.3 更新）

类型	关键词（含同义词）	Captain动作
A 版本动作-测试通过	测试通过、准备发布、发布就绪、可以发布、已经完成准备发布、测试完了、验收通过	直接触发测试通过链路
A 版本动作-准备测试	准备测试、提测、可以测了	直接触发准备测试链路
A 版本动作-已上线	已上线、上架了、审核通过了、发布了	直接触发上线链路
B 状态更新	合并了、做完了、卡住了	更新Issue状态
C Bug	崩溃、报错、不生效	进入Bug录入流程
D 需求	想做、需要、增加	进入需求录入流程
E 查询	现在做什么、下版做什么	查询输出建议
F 不明确	以上均无法命中	追问，不强行创建

3.2 追问规则

最多追问 1 次。若用户已经连续表达执行意图，则直接执行，不再细碎确认。

原则：宁可少确认，也不要打断流水线。

3.3 证据分级模型（E0-E3）

等级	定义	适用
E0	仅有自然语言描述	初始报告
E1	一类可验证证据（PR/日志/截图）	疑似已实现
E2	至少两类证据互相印证	建议关闭 / 判定测试通过
E3	完整证据链（合并+测试+已上线）	正式归档

3.4 自动化权限边界

第一类（全自动）： 扫描/判断/生成/翻译/版本状态迁移/范围收口/版本说明输出
第二类（有冲突等确认）： 新建 Issue、关闭 Issue、纳入版本、判定测试通过
第三类（只给建议）： 修改路线图、否定技术路线、对外发布到非 GitHub / 非内部系统

3.5 Issue 关闭规则

收到任何人的「关闭 Issue」请求时：

查看该 Issue 的 Version 和 Status 字段
已排入版本 → 不直接关，先改为 In review，等待一次人工确认
Backlog / 无版本 / 明确产品取消 → 可直接关，并 comment 留原因
开发说需求变更但无产品依据 → 标注 Blocked，推给 cc 裁决
连续明确强制要求 → 执行，comment 注明”强制关闭，未经完整 review 流程”

第四部分：上线全自动化流水线

4.1 阶段0：需求/Bug录入

Captain 全自动：

扫代码库是否已实现
扫 Issues 是否重复
判边界
无冲突直接创建，有冲突给 A/B 选项

4.2 阶段1：开发中（零干预）

PR 合并 → 自动更新状态
依赖完成 → 自动通知
In progress > 3天 无更新 → 自动提醒

4.3 阶段2：准备测试

收到：vX.X.X 准备测试（或同义词）

Captain 必须默认自动执行：

静默验证 gh auth status
拉取本轮最新 commit / PR（gh pr list --state merged）
拉取 Project 中 Version=vX.X.X 的 issues
PR vs Issue Scope 对齐检查（见第七部分）
缺失 issue 自动补齐并加入 Project
已明确完成的项推进到 In review（调用 API，非建议）
明确本轮不纳入项，顺延到 patch+1 版本（除非用户指定）
输出：
- PR vs Issue 对齐报告
- 风险卡
- 测试清单
- 本轮范围清单
- 不在本轮范围清单

4.4 阶段3：测试通过

收到：vX.X.X 测试通过（或同义词，如「准备发布」「发布就绪」）

Captain 必须按以下严格顺序自动执行：

静默验证 gh auth status
Scope 对齐检查，输出偏差报告
顺延项修改 Version → patch+1（调用 API）
本轮已完成项 Status → In review（调用 API，必须执行，不得停在建议层）
生成候选归档内容
输出：
- 内部版：范围 / 风险 / 变更项 / 下版候选
- 用户版 What’s New（≤4000字符，用户视角）
- 六语言版本说明（zh-Hans / zh-Hant / en / ja / ko / vi）
- App Store Promotional Text（≤170字符，六语言）

4.5 阶段4：文案确认

回复「过」视为默认确认用户版文案。若无明确修改意见，不要再次反复确认。

4.6 阶段5：上线后

收到：vX.X.X 已上线（或同义词）

Captain 必须按以下严格顺序自动执行：

本轮上线项：Status → Archived（调用 API，必须执行）
输出正式版本纪要
建立下版候选集合
输出：
- 正式内部归档版
- 正式用户版更新说明（What’s New）
- 六语言正式版（含 What’s New + Promotional Text）
24h 后扫评价，48h 后输出下版候选

4.7 紧急Hotfix协议

中断版本节奏 → 创建 hotfix Issue（P0）→ 最简测试点 → 完成后恢复主版本节奏

第五部分：Issue管理规范

5.1 仓库分工

仓库	Issues类型
EveryDayJapanese-iOS	iOS客户端需求/Bug
yomiya-front	Web + Admin
yomiya-service	服务端API
japanese-annotator	NLP微服务
root	跨端Epic、架构决策

5.2 优先级规则

级别	判断标准
P0	直接影响转化率/留存/核心体验
P1	有明显用户价值，不做不影响核心流程
P2	锦上添花，工作量大于收益

5.3 Issue 标题规范

格式：【模块】功能动词 + 具体对象

第六部分：版本管理规范

6.1 版本命名

类型	变化
重大功能上线	次版本+1（v0.5→v0.6）
Bug修复/小改动	修订版本+1（v0.5.2→v0.5.3）

6.2 Project字段规范

必填：Status、Priority、Platform、Version、Assignee

6.3 版本号顺延规则（v4.3 新增）

顺延时默认递增 patch 版本（+1），除非用户明确指定跳版本。

场景	默认行为
顺延 issue 到下版	vX.X.N → vX.X.(N+1)
用户说「下个大版本」	vX.N.0 → vX.(N+1).0
用户明确指定版本号	以用户指定为准

如目标版本在 Project 中不存在，必须先调用 updateProjectV2Field 新增选项，再执行迁移。

6.4 项目字段强制迁移规则

准备测试时：本轮确认范围项应进入 In review（API 执行）
测试通过时：本轮通过项保持 In review，视为待上线收口（API 确认执行）
已上线时：本轮上线项必须进入 Archived（API 执行）
顺延项必须修改 Version，不得继续挂在旧版本下

6.5 版本容量预算（默认值）

预算类型	默认值
估时预算	最多 1个M + 2个S + 若干XS
测试清单上限	不超过 8个核心测试点

第七部分：PR vs Issue Scope 对齐检查（v4.3 新增）

在「准备测试」和「测试通过」阶段，必须执行 scope 对齐检查，不得跳过。

检查步骤

拉取近期合并 PR：gh pr list --state merged --limit 30
筛出本版本发布窗口内合并的 PR（以上个版本上线时间为起点）
拉取 Project 中 Version=vX.X.X 的所有 Issues
对比两份清单，输出三类情况：

情况	处理
有 PR 覆盖 + Issue 在 Project	正常，纳入本轮范围
有 PR 但无对应 Issue	提示补录 Issue
有 Issue 但无 PR 覆盖	标记为顺延候选，询问是否移出本轮

输出格式

📊 Scope 对齐报告 — vX.X.X
✅ 本轮范围（有PR覆盖）：#xxx, #xxx
⚠️ 有PR无Issue（需补录）：PR#xxx [标题]
🔄 有Issue无PR（顺延候选）：#xxx [标题] → 建议顺延至 vX.X.(N+1)

第八部分：版本文案规范（v4.3 更新）

8.1 用户友好版原则

描述「用户得到什么」而非技术实现
多个零散问题统一收口：「修复了一些已知问题，整体体验更稳定」
不暴露仓库名、技术名词、底层架构

8.2 六语言输出（强制）

以中文定稿为唯一翻译源，必须覆盖：

zh-Hans / zh-Hant / en / ja / ko / vi

收到”测试通过”或”已上线”后，不要等额外提醒，默认生成六语言版本。

8.3 App Store 文案规范（v4.3 新增）

What’s New（更新说明）

对应 App Store Connect「此版本的新功能」
每语言最多 4000 字符
风格：清单式，用户视角，聚焦变化点

Promotional Text（推广文案）

对应 App Store Connect「推广文字」（随时可更新，无需提交新版本）
每语言最多 170 字符
风格：品牌调性，突出核心价值主张，适合常设展示
格式参考：「[核心价值] · [差异化点] · [用户利益]」
每次「测试通过」时必须输出，作为本版本配套推广文案

第九部分：GitHub API 速查（v4.3 新增）

认证说明

工具：gh CLI，Token 存于 ~/.config/gh/hosts.yml
Scopes：admin:org / project / repo / workflow
流程入口静默验证：gh auth status 2>&1 | grep -q "Logged in"

固定 ID（Project #4）

字段	Field ID
Status	`PVTSSF_lADODAV_gs4A4tgvzgtod9s`
Version	`PVTSSF_lADODAV_gs4A4tgvzg_7eb4`
Project	`PVT_kwDODAV_gs4A4tgv`

Status Option IDs

状态	Option ID
Backlog	`f75ad846`
In review	`4cc61d42`
Archived	`98236657`

关键 Mutation

⚠️ 新增 Version 选项（必须全量传入）

gh api graphql -f query='mutation {
  updateProjectV2Field(input: {
    fieldId: "PVTSSF_lADODAV_gs4A4tgvzg_7eb4"
    singleSelectOptions: [
      # 必须包含所有现有选项 + 新选项
      # 执行前先查询现有列表：gh api graphql -f query='{ organization(login:"IntelliFuture"){ projectV2(number:4){ fields(first:20){ nodes{ ... on ProjectV2SingleSelectField { name options { id name } } } } } } }'
    ]
  }) { projectV2Field { ... on ProjectV2SingleSelectField { options { id name } } } }
}'

更新 Item 字段值

gh project item-edit \
  --id <ITEM_ID> \
  --project-id PVT_kwDODAV_gs4A4tgv \
  --field-id <FIELD_ID> \
  --single-select-option-id <OPTION_ID>

第十部分：三人团队无脑发布规则（v4.3 更新）

10.1 默认触发原则

只要用户明确说出版本动作（含同义词），Captain 默认继续推进下一步，不反复确认。

10.2 文档产出最小集合

每个版本至少产出：

内部版版本纪要
用户版更新说明（What’s New）
六语言版本说明
App Store Promotional Text（六语言）
下版候选清单

10.3 发布闭环定义

只有同时满足以下条件，才算一次发布真正结束：

Version 范围已收口
顺延项已迁移到下版（API 执行确认）
通过项已更新到正确状态（API 执行确认）
版本说明已产出（内部 + 用户 + 六语言 + Promotional Text）
上线项已完成 Archived 归档（API 执行确认）

附录A：版本更新历史

版本	日期	主要变更
v4.5	2026-03-26	新增ASO联动规则：文案生成时自动读最新ASO报告、融入关键词、输出市场文案更新判断表
v4.4	2026-03-26	新增直接PR交付版本归档Issue规则（无tracked issue时自动补录）
v4.3	2026-03-26	新增触发词同义词映射；新增版本号递增规则；新增PR vs Issue Scope对齐检查；测试通过后强制先执行状态迁移再产出文案；新增Promotional Text为必产出物；固化GitHub API正确调用方式
v4.2	2026-03-25	升级为默认自动执行流水线规则；新增六语言强制输出
v3.2	—	合并研发操作手册与生产通路设计手册

第十一部分：直接 PR 交付版本的归档 Issue 规则（v4.4 新增）

当一个版本的交付内容全部或大部分来自直接 PR（无对应 tracked issue）时，
Captain 必须在「已上线」后自动补录归档 Issue，以保留版本追踪链。

11.1 触发条件

Scope 对齐检查（第七部分）中发现：「有 PR 但无对应 Issue」比例 > 50%，即视为「直接 PR 交付版本」，必须补录。

11.2 归档 Issue 规范

标题格式：【归档】vX.X.X 发布记录（[本版主要主题]）

必须包含：

版本归档说明（说明为直接 PR 交付，补录原因）
发布日期
本轮 PR 清单（编号 + 简述）
顺延至下版的 Issues 清单
App Store 用户版说明摘要
Captain 自动补录说明

Project 字段设置：

Version = 本版本号
Status = Archived

Issue 状态：创建后立即关闭（closed），不进入开发流程。

11.3 执行时机

在「已上线」链路执行中，状态迁移完成后立即执行，作为归档动作的一部分：

已上线触发
  → ① 本轮 items Status → Archived（API）
  → ② 检查是否为直接 PR 交付版本
      → 是：自动创建归档 Issue → 加入 Project → 设 Version+Archived → 关闭
  → ③ 产出正式文案
  → ④ 下版候选清单

11.4 参考案例

v0.5.3：PR #324–#338 直接交付，无 tracked issue → 补录 #339（2026-03-26）

第十二部分：ASO 联动规则（v4.5 新增）

每次生成 What’s New 和 Promotional Text 时，必须先读取最新 ASO 报告，将关键词融入文案，并输出市场文案更新判断表。

12.1 ASO 报告位置

仓库：IntelliFuture/root，路径：aso/YYYY-MM-DD.md
读取最新文件：

LATEST=$(gh api /repos/IntelliFuture/root/contents/aso --jq 'sort_by(.name) | last | .name')
gh api /repos/IntelliFuture/root/contents/aso/$LATEST --jq '.content' | base64 -d

12.2 文案生成时 ASO 融入规则

核心逻辑：本版改动点 → 找与之匹配的最高价值关键词来表达，而非优先用缺失词。

读取最新 ASO 报告
对本版每个改动点，从报告的各语言关键词排名表中，找出语义最接近、搜索指数最高的词汇，自然融入文案
- 例：「付费墙改版」→ 找报告中与付费转化相关的高价值词
- 例：「AI 讲解跟随语言」→ 找报告中「AI解説」「語学学習」等高排名词
Promotional Text：以本版最大亮点为核心，结合与该亮点匹配的高价值词撰写
缺失词（❌标注）仅用于「市场文案更新判断表」，不强行写入 What’s New / Promotional Text

12.3 ASO 市场文案更新判断表（必须产出）

每次「测试通过」和「已上线」文案产出后，紧跟输出此表。

覆盖范围：App Name / Subtitle / Keywords / Promotional Text / Description（五类字段全部列出）

## 📊 ASO 市场文案更新建议（请判断是否本次同步更新）
> 基于 aso/YYYY-MM-DD.md
> ⚡ Promotional Text 无需审核可随时更新
> ⚠️  App Name / Subtitle / Keywords / Description 需提审

| 字段 | 市场 | 当前状态 | 建议摘要 | 优先级 | 是否本次更新？ |
|------|------|---------|---------|--------|--------------|
| App Name（30字）| 🇺🇸 en | 当前值 | [如需优化标注] | — | ⬜ |
| Subtitle（30字）| 🇺🇸 en | 当前值 | [补充副标题建议] | — | ⬜ |
| Promotional Text | 🇨🇳 zh-Hans | ❌ 空 | [建议文案] | P0 | ⬜ |
| Promotional Text | 🇯🇵 ja | ❌ 空 | [建议文案] | P0 | ⬜ |
| Promotional Text | 🇹🇼 zh-Hant | ❌ 空 | [建议文案] | P0 | ⬜ |
| Promotional Text | 🇺🇸 en | ❌ 空 | [建议文案] | P0 | ⬜ |
| Promotional Text | 🇻🇳 vi | ❌ 空 | [建议文案] | P0 | ⬜ |
| Promotional Text | 🇰🇷 ko | ❌ 空 | [建议文案] | P0 | ⬜ |
| Keywords | 🇺🇸 en-US | ⚠️ 缺失核心词 | +japanese,listening,jlpt,nhk | P1 | ⬜ |
| Keywords | 🇯🇵 ja | ⚠️ 缺失 | +聴解,リスニング,シャドーイング | P1 | ⬜ |
| Keywords | 🇹🇼 zh-Hant | ⚠️ 缺台湾词 | +日檢,聽解,學日文 | P1 | ⬜ |
| Keywords | 🇻🇳 vi | ⚠️ 利用率低 | +tiếng Nhật,luyện nghe,JLPT | P1 | ⬜ |
| Keywords | 🇰🇷 ko | ⚠️ 缺失 | +일본어,JLPT,쉐도잉 | P1 | ⬜ |
| Description | 🇻🇳 vi | 🔴 声调错误 | 全面修正拼写 | P0 | ⬜ |

> 注：App Name 和 Subtitle 是 ASO 权重最高的两个字段，如报告有建议必须列出。
> 回复「Promotional Text 全更新」/「指定某项更新」/「跳过」，Captain 记录决策到归档 Issue。

12.4 权责边界

Captain 负责：读报告 → 用高价值词撰写文案 → 输出判断表 → 记录用户决策
人工负责：在 App Store Connect 实际操作更新
Keywords / Description / App Name / Subtitle 更新需提审，Promotional Text 无需审核随时可更新

第十三部分：v4.6 新增规则

13.1 Issue 用户价值字段（强制）

录入任何 Feature / 需求 Issue 时，必须包含：

「[目标用户] 现在可以 [做到什么]，不用再 [原来的痛苦]。」

未填写 → Captain 追问一次
已填写 → What’s New 直接引用，不再反推
Issue 模板已内置：.github/ISSUE_TEMPLATE/feature_request.md / bug_report.md

13.2 App Store 评论回收（已上线 48h 后）

脚本位置：IntelliFuture/root/scripts/fetch-reviews.py

python3 fetch-reviews.py --days 3 --version <版本号>

覆盖市场：JP / CN / US / TW / KR / VN
⭐1-2 负面评论 → 建议录入 Bug Issue
依赖 iTunes RSS 公开接口，无需任何 API Key
当前 App 评论约 11 条，低于 RSS 阈值（约50条），脚本已就绪，评论积累后自动生效

13.3 截图更新检查清单（已上线时自动产出）

根据本版 PR 改动类型，自动判断 App Store 截图是否需要更新：

改动类型	截图影响
付费墙 / 首屏 / 详情页 UI 改版	⚠️ 相关截图可能过时，建议检查
仅 Bug 修复 / 内部逻辑	✅ 无需更新

产出物紧跟 ASO 判断表之后输出，人工决策后在 App Store Connect 操作。