Issue Fix Context【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecodeYou are fixing Issue #{{ISSUE_NUMBER}}:{{ISSUE_TITLE}}Issue DetailsURL: {{ISSUE_URL}}Labels: {{ISSUE_LABELS}}Branch:{{BRANCH_NAME}}标题与详情区共同回答了 Claude 最关心的三个问题**修什么**编号与标题、**在哪修**URL 与标签用于背景检索、**在哪个分支上修**BRANCH_NAME。其中 BRANCH_NAME 不是手工填写的而是由 PSM 在创建 worktree 时依据 Issue 标题自动 slugify 生成见 3.3 节。 ### 2.2 DescriptionIssue 正文 markdown ## Description {{ISSUE_BODY}}ISSUE_BODY直接透传 Issue 的原始描述。它可能是多行文本甚至 Markdown——正因为模板渲染采用 Bash 参数展开而非 sed 逐行处理多行值才能被安全地嵌入测试用例 #7 亦验证了含这类易被 sed 误解释为反向引用的字符也能原样保留见 test-psm-prompt-injection.sh。2.3 Approach四步修复法## Approach 1. **Understand the Issue** - Reproduce the problem if applicable - Identify root cause - Consider edge cases 2. **Plan the Fix** - Minimal changes to fix the issue - Dont introduce regressions - Consider backwards compatibility 3. **Implement** - Write the fix - Add/update tests - Update documentation if needed 4. **Verify** - Run existing tests - Test the specific fix - Check for regressionsApproach 是模板中真正约束 Claude“工作方法”的核心章节四步依次递进理解 Issue——能复现则复现定位根因root cause并考虑边界条件规划修复——坚持最小改动原则明确不引入回归、兼顾向后兼容实现——写修复、同步增改测试、必要时更新文档验证——跑既有测试、验证本次修复本身、检查是否引入回归。“先复现→再最小改动→补测试→验回归”的顺序设计是为了避免 Agent 在未充分理解问题时直接猜测性改码——这是修复类任务中最常见的返工来源。2.4 Commands命令模板# Run tests npm test # or appropriate test command # Check build npm run build # or appropriate build command # Create PR when done gh pr create --title Fix #{{ISSUE_NUMBER}}: description --body Fixes #{{ISSUE_NUMBER}}Commands 以 npm/gh为例给出“测试→构建→提 PR”的命令骨架并显式注明“or appropriate test command”提示 Claude 依据仓库实际工具链替换。PR 标题与正文遵循 GitHub 惯例标题写Fix #编号: 描述正文写Fixes #编号以在 PR 合并时自动关联并关闭对应 Issue。若仓库是 Jira 而非 GitHub则需要把最后一条替换为 Jira 流程Jira 没有 PR 概念PSM 对此有专门防护见 3.4 节。2.5 Fix Checklist完成度清单## Fix Checklist - [ ] Root cause identified - [ ] Fix implemented - [ ] Tests added/updated - [ ] All tests pass - [ ] No regressions introduced - [ ] Ready for PR六项勾选清单把“修复完成”具象化为可验证标准根因已识别、修复已实现、测试已增改、全部测试通过、无回归、可提交 PR。它与 feature.md、pr-review.md 中的清单风格一致保证 Agent 在收尾时不会遗漏验证与回归检查。3. 占位符从哪来渲染引擎与数据源映射模板中的{{KEY}}不能凭空出现——必须由 PSM 的渲染引擎从真实 Issue 数据逐一替换。这一小节回答“每个占位符是如何被填上真实值的”。3.1 渲染引擎psm_render_templatePSM 没有引入任何外部模板库渲染逻辑只是一个纯 Bash 函数实现在 lib/tmux.shpsm_render_template() { local template_file$1 shift if [[ ! -f $template_file ]]; then echo error|Template not found: $template_file 2 return 1 fi local content content$(cat $template_file) for assignment in $; do local key${assignment%%*} local value${assignment#*} # Bash parameter expansion handles multiline values safely content${content//\{\{${key}\}\}/$value} done printf %s\n $content }几个值得注意的实现细节传入形式为KEYVALUE的若干参数每次调用把模板中所有{{KEY}}用${var//pattern/replacement}参数展开替换Bash 参数展开天然支持含换行与特殊字符的多行值如ISSUE_BODY所以无需担心转义未引用的占位符会被原样保留而非静默删除——这在渲染失败时是重要的排错信号测试用例 #3 专门断言了这一行为模板文件不存在时返回非零并输出error|前缀的诊断信息渲染完全是大写键名ISSUE_NUMBER等与模板中的{{...}}一一对应因此新增占位符只需同时修改模板与psm.sh的渲染调用无需改动引擎。3.2 六个占位符的 GitHub 数据来源cmd_fixpsm.sh首先用 GitHub CLI 拉取 Issue 的 JSON 字段再从 JSON 中抽取各占位符所需的值gh issue view issue_number --repo repo --json number,title,body,labels,url对应关系如下表模板占位符GitHub JSON 字段说明{{ISSUE_NUMBER}}numberIssue 编号{{ISSUE_TITLE}}titleIssue 标题{{ISSUE_URL}}urlIssue 链接{{ISSUE_LABELS}}labels[].name逗号拼接标签名列表join(, )处理{{ISSUE_BODY}}bodyIssue 正文缺失时兜底为空串// {{BRANCH_NAME}}由title派生见 3.3 节在 psm.sh 中可以看到issue_body与issue_labels都使用了// /// empty之类的 jq 兜底防止正文或标签缺失导致渲染失败或空值异常。3.3BRANCH_NAME的生成从标题到 slugBRANCH_NAME并非来自远端而是由 Issue 标题实时派生。cmd_fix中先调用 lib/parse.sh 的psm_slugifypsm_slugify() { local title$1 local max_len${2:-30} echo $title | tr [:upper:] [:lower:] | sed s/[^a-z0-9]/-/g | sed s/--*/-/g | sed s/^-// | sed s/-$// | head -c $max_len }即转小写 → 非字母数字字符统一替换为-→ 压缩连续-→ 去掉首尾-→ 截断到 20 字符cmd_fix传入psm_slugify $issue_title 20。随后 lib/worktree.sh 的psm_create_issue_worktree把 slug 拼成规范分支名与 worktree 路径local worktree_path${worktree_root}/${alias}/issue-${issue_number} local branch_namefix/${issue_number}-${slug}例如标题Auth fails on token expiry会得到分支fix/42-auth-token-expiry测试脚本 #33-38 中即以此为例断言渲染结果。worktree_root默认来自配置~/.psm/worktrees可用defaults.worktree_root覆盖因此omc:issue-42会话的 worktree 目录就是~/.psm/worktrees/omc/issue-42。3.4 Jira 数据源字段结构不同当 alias 配置了provider: jira时cmd_fix走另一条数据路径psm.sh从 Jira CLI 结果中抽取issue_title←fields.summaryissue_url←selfissue_body←fields.description也就是同一个模板对 GitHub/Jira 双 provider 通用差异只在上游字段映射。注意 PSM 还规定了两条 Jira 约束详见 SKILL.mdpsm fix PROJ-123只在PROJ被显式配置为jira_project时才被识别防止FIX-123这类分支名误判而psm review对 Jira 直接报错因为 Jira 没有 PR 概念。4. 从psm fix到 Claude 开工完整调用链issue-fix.md的价值在于被正确投喂给 Agent。整个过程发生在cmd_fix中可分为五个阶段4.1 解析引用并拉取 Issue 数据用户执行psm fix omc#42引用格式见 psm.sh支持alias#num、owner/repo#num、URL 与当前仓库#num解析出 alias、repo、issue_number、base 等字段后按 3.2/3.4 节的 provider 分支拉取 Issue 信息。4.2 创建 worktree 与 fix 分支先确保本地仓库存在必要时按 alias 配置clone_url再调用psm_create_issue_worktreegit fetch origin base→git branch fix/num-slug origin/base→git worktree add。base默认main可通过 alias 的default_base覆盖。4.3 渲染模板并写入.psm/fix.md这是模板最直接的消费点psm.shlocal fix_context_rel.psm/fix.md local fix_context_file${worktree_path}/${fix_context_rel} mkdir -p $(dirname $fix_context_file) if ! psm_render_template $SCRIPT_DIR/templates/issue-fix.md \ ISSUE_NUMBER${issue_number} \ ISSUE_TITLE${issue_title} \ ISSUE_URL${issue_url} \ ISSUE_LABELS${issue_labels} \ ISSUE_BODY${issue_body} \ BRANCH_NAME${branch_name} \ $fix_context_file; then log_warn Failed to render issue fix template; Claude will start without task context fix_context_rel fi渲染后的上下文文件被写入 worktree 的.psm/fix.md恰好处于 Claude 即将工作的工作目录内Claude 可以随时再读取它而无需网络请求。若渲染失败模板缺失等会打印警告并把上下文引用置空Claude 仍可启动只是缺少任务说明——即“fail open with warning”策略。4.4 创建 tmux 会话并启动 Claudecmd_fix把 session idomc:issue-42换算成 tmux-safe 名字后创建 tmux 会话并启动 Claude细节见 lib/tmux.sh会话名遵循issue #3528引入的规范tmux 保留:与.因此公共 IDomc:issue-42在 tmux 边界处一律翻译为psm_omc_issue-42psm_tmux_safe_name用${name//[.:]/_}替换且翻译幂等通过tmux send-keys claude --dangerously-skip-permissions启动 Claude Code——跳过“信任该目录吗”与逐工具审批弹窗避免无人值守会话被阻塞在第一次工具调用上issue #2508 的修复Claude 以 worktree 路径为启动目录创建时用-c $worktree_path指定。4.5 探测 REPL 就绪并注入任务指令Claude 启动需要时间因此注入不是立刻send-keys而是先轮询探测交互提示符_psm_pane_has_claude_prompt() { printf %s $pane_text | grep -qE ^[[:space:]]*(|\?)[[:space:]]*$ }psm_wait_for_claude_prompt默认最多等 30 秒反复tmux capture-pane直到窗格出现单独一行的标准输入提示符或?信任弹窗为止随后psm_inject_prompt注入一条触发指令lib/tmux.shlocal triggerRead ${context_file} for full task context, then begin. # 使用 -lliteral模式防止 tmux 把文本中的按键名误解为指令 tmux send-keys -t $session_name -l -- $trigger最终 Claude 收到的第一句任务就是“读取.psm/fix.md获取完整任务上下文然后开始”而.psm/fix.md的内容正是渲染后的issue-fix.md。若未能检测到提示符超时只警告而不让会话创建失败非致命。此外psm_launch_claude对第二参数做了分流指向文件就按“上下文文件触发词”路径处理否则视为字面 prompt 延后投递等待PSM_CLAUDE_STARTUP_DELAY默认 5 秒。整个链路可概括为psm fix→ 拉取 Issue JSON → 建 worktree/branch → 渲染模板为.psm/fix.md→ tmux 内启 Claude → 探测/?→ 注入 Read .psm/fix.md … → Claude 按模板四步法开始修复。5. 会话生命周期与状态登记上下文投递完成后会话会写入注册表并对外展示session 数据登记见 psm.shSession ready! ID: omc:issue-42 Type: fix Issue: #42 - title Branch: fix/42-slug Worktree: ~/.psm/worktrees/omc/issue-42 Tmux: psm_omc_issue-42【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考