用途:为当前分支生成一份连贯的用户故事叙述,输出到仓库根目录的 tmp/pr-story.md,供人工审阅;经明确批准后可追加到 PR 描述。流程分五个阶段:审视改动、列提纲、撰写故事、校对、发布到 PR。
主要能力与用法
阶段一,审视改动:用 git diff "$(git merge-base HEAD origin/main)"...HEAD 以及 git status --short 对比基线与已提交/未暂存改动;选定一个主要用户路径,按执行顺序追踪代码调用,只记录本分支涉及的文件,不把并行流程写入故事正文。
阶段二,列提纲:动笔前先草拟开头(谁在何处触发该流程)、中段(调用链与分支点)、结尾(用户看到的成功与失败路径),并为 Notes 草拟并行入口、共享基础设施、迁移与开关,每步一行并锚定到 Module.function(仅直接父级)。
阶段三,撰写到 tmp/pr-story.md:首行为唯一故事标题,格式 ## User story: <简短描述>,必须用 ## 而非 #;Notes 区块用 ## Notes 作章节标题。人称用工程主动复数(we added、we call、we run),变更标记用 now、the new、we added,运行时行为用 if 与所属格,避免过度限定范围。引用格式为 Module.function,不带元数,仅用短模块名而非完整路径,首次以括号锚定后可间接指代,跨越其他函数后需重新按名锚定。正文按执行顺序逐段推进,不用项目符号列表,每段一个节拍,段间空行。内容边界:故事与 Notes 均不得提及测试(测试文件、Hammox/Mox 桩、测试计划、验证清单等),不罗列分支上每个文件,并行流程(群发、API、验证等)放进 Notes。Notes 用 ## Notes 加每个主题一个 ### 标题,扁平 - 列表,覆盖共享基础设施、其他入口、迁移/新列/默认值及评审可能关切的内容。
阶段四,校对:核对调用顺序、Module.function 是否为直接被调方、分支描述与错误原子/回滚/UI 结果是否匹配代码;检查风格,确保无完整模块路径、无元数、正文无列表、错误用词等;核对 Notes 不含测试引用;就地修正文件,仍不向用户输出摘要。
阶段五,发布到 PR:仅在用户明确同意后执行。重新从磁盘读取文件,用 gh pr view --json number,body,url 或 gh pr list --head "$(git branch --show-current)" 找到 PR;PR 已有内容则空行后追加,正文为空则仅用文件内容,不得添加文件之外的任何内容;用 gh pr edit <number> --body "$(cat tmp/pr-story.md)" 替换空正文,或通过 HEREDOC 合并现有正文与文件;最后仅简要确认 PR URL。
适用场景:已开分支并需为 PR 补充面向用户的故事叙述的工程流程。限制:必须人工批准后才写入 PR;不涉及测试;资料未提供收费、平台支持及其他未列明能力。