file-pr

提交 PR

提交前，检查此分支是否已经有 PR。

运行 git fetch origin <base>，并通过 git diff origin/<base>...HEAD 查看变更。本地基础分支可能落后于远程分支，导致描述中包含无关提交。

PR 标题和正文必须使用美式英语。如果仓库中有 GLOSSARY.md，请使用其中的领域术语。

确保标题遵循 $conventional-commits 技能。优先使用简洁、易懂且能说明变更意义的标题：

不佳

❌ perf(server): negotiate permessage-deflate on the websocket

良好

✅ perf(server): cut websocket frame size by 70%+ with gzipping

正文开头先根据用户的原始提示，简单说明问题，然后简要解释解决方案。不要一开始就罗列实现细节：

不佳

❌ Removed implicit workspace carry-over from every "new thread" entry point (cmd+n / cmd+shift+o, sidebar v1/v2 buttons, command palette). New threads inherit only the project from context; branch, worktree, and env mode always come from the configured defaults. Delete buildContextualThreadOptions, startNewThreadInProjectFromContext, and the v1 sidebar's seed-context machinery.

良好

✅ My "new worktree" default was ignored when starting new threads on existing worktrees. Super unintuitive. Now your preferences always apply.

按此正文结构中适用的章节，并严格按以下顺序使用。替换所有占位符，并省略没有内容的章节。如果 git ls-files .github/pull_request_template.md 输出该路径，则改为填写该模板，并将以下章节放入模板中：

## 📝 Summary

<Explain the problem, then the solution in plain language. This should be short, concise, and human-readable.>

<Visual of the change, see "Summary visual">

## ✅ Verification

- **Before:** <screenshot/output/failing test run>
  **After:** <screenshot/output/passing test run>

## 🔍 Reviews

| Review   | Found   | Fixed   |
| -------- | ------- | ------- |
| <review> | <count> | <count> |

<If any finding remains unfixed, name it and explain why.>

## 🔗 Issues

<Write "Closes #123" for every ticket the PR closes.>

## 💥 Merge danger

**Door:** <one-way or two-way>

<optional: description>

**Blast Radius:** <one-word description>

<optional: potential ramifications of merge>

## ⚠️ Needs attention

<List follow-up work, known limitations, or other issues that need the user's attention.>

列出所有已执行的审查，包括未发现问题的审查。除非确实执行过，否则绝不要声称运行了某项检查或审查。

摘要图示

选择能清晰说明关键点的最简视图。

• 用伪代码展示逻辑或算法：

on(save)
  if content is unchanged
    return cached result
  write new content
  return fresh result

• 用调用树展示运行时控制流：

submitForm
  createSession
    persistPrompt
    launchAgent
  navigateToSession

• 用组件树展示 UI 结构，并包含重要的状态和模块边界：

<SessionPage> (apps/example/src/routes/session.tsx)
  useSessionEvents()
  <SessionToolbar>
    <RunSkillButton> (packages/ui)

• 用浅层文件树展示文件职责或大范围重构：

src/
├── commands/       # parses user actions
├── sessions/       # owns session state
└── transport/      # sends API requests

• 用 Mermaid 展示组件交互、控制流或数据流：

sequenceDiagram
    participant User
    participant UI
    participant Daemon
    User->>UI: choose command
    UI->>Daemon: send expanded prompt
    Daemon-->>UI: stream result

• 当重点是变更内容且周边结构已存在时，使用 diff。让 diff 形状与主题相符。

对于组件变更：

 <SessionPage>
   useSessionEvents()
   <SessionToolbar>
+    <RunSkillButton />
   <SessionTimeline>
+    <SkillResultCard />

对于文件布局变更：

 src/
 ├── commands/
+│   └── show-me.ts       # expands the slash command
 ├── sessions/
-└── transport.ts
+└── transport/
+    ├── client.ts
+    └── stream.ts

对于调用树或调用栈变更：

 submitForm
   createSession
     persistPrompt
+    expandSkillMention
     launchAgent
-  navigateToSession
+  navigateToSession
+    subscribeToEvents

对于状态或控制流变更：

 on(save)
-  write content
+  if content is unchanged
+    return cached result
+  write new content
+  invalidate cache

• 如果大部分内容都是新增的、删去上下文会掩盖归属或顺序，或用户需要可复制的目标结构，则展示完整代码块：

function expandSkill(command: string): string {
  const skillName = command.slice(1);
  return `use the ${skillName} skill`;
}

将每个图示放在其所支持的简短说明旁。只保留回答用户当前问题或解决当前讨论事项所需的调用、文件、属性、状态和边界。

你可以使用其中一种，也可以使用多种；不太可能全部用上。请自行判断，避免让用户不知所措。

验证

提供变更有效的具体证据，并展示变更前后的情况。

截图是 S 级证据——如果环境已配置好且变更涉及视觉效果，就应使用。始终内嵌图片，不要链接到图片。

基于执行的证据属于 A 级。测试结果、控制台输出。使用伪代码展示现在失败和通过的确切测试。

合并风险

说明这是单向门还是双向门。双向门可以回退；单向门则不行。易于回滚的 PR 风险较低。涉及破坏性操作或难以撤销的决策，则属于单向门。

影响范围是此 PR 引入的变更可能造成影响的领域或范围。请考虑各种可能性，例如布局偏移、消费者端故障、移动端响应性等。

提交

创建正式 PR，而不是草稿。如果用户要求跳过 CI 且存在相应标签，则为 PR 添加 skip-ci 和 skip-deploy 标签。