[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M74ESVWA1JWTTZM9HTREV7PP":3,"skill-same:01M74ESVWA1JWTTZM9HTREV7PP":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":6,"updatedAt":32,"install":33,"resources":46},"01M74ESVWA1JWTTZM9HTREV7PP","write-pr",null,"在 kimi-code 仓库里创建或更新 PR 时使用：如何写出让 reviewer 只读描述就能从逻辑和架构上理解改动的 PR 描述，包括核心思路与结构图、\"行为变化与受影响人群\"表、可视化大纲，以及 UI\u002FUX 变化的截图和录屏。","MoonshotAI\u002Fkimi-code","MoonshotAI","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F129152888?v=4","01M74ERZMTV9BR82QKWAF5NAVA","Moonshot AI","01M74ERZND3KECTZ02YW0FYJSR",8226,"MIT","https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwrite-pr\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: write-pr\ndescription: 在 kimi-code 仓库里创建或更新 PR 时使用：如何写出让 reviewer 只读描述就能从逻辑和架构上理解改动的 PR 描述，包括核心思路与结构图、\"行为变化与受影响人群\"表、可视化大纲，以及 UI\u002FUX 变化的截图和录屏。\n---\n\n# 写 PR 描述\n\n为当前分支创建或更新 PR。目标是 reviewer 只读描述，就能从逻辑和架构上理解这个改动：为什么存在、核心思路是什么、改完后系统长什么样、现有用户会失去什么，以及该从哪里开始看代码。\n\n## 工作流\n\n1. 读 PR 模板：\n\n   `Read(.github\u002Fpull_request_template.md)`\n\n2. 找到或创建 PR：\n   - 先查当前分支有没有 PR：`gh pr view --json url,number,title,state 2>\u002Fdev\u002Fnull`。\n   - 没有的话，看 `git status --short --branch` 和当前分支上的提交。\n   - 提交剩余改动，带 upstream 推送分支，用 `gh pr create` 创建 PR。\n   - 遵守仓库的 git 安全规范。\n\n3. 收集解释改动所需的上下文：\n   - 读关联的 issue 和相关任务产物。\n   - 读完整 diff（`git diff main...HEAD`）和足够的周边代码，理解行为与归属。\n   - PR 已存在时，用 `gh pr view` 拿元数据和改动文件列表。\n   - 改动让用户看到的界面或输出变了的，准备视觉证据，见\"UI\u002FUX 变化的视觉证据\"。\n\n4. 按模板各节写描述。描述用用户当前使用的语言，行为变化表也一样；只有三样固定：PR 标题保持英文 Conventional Commit，changeset 保持英文（见 `gen-changesets` skill），节标题沿用模板原文。\n   - **Requirement or Bug**：两三句话讲清谁遇到了什么问题、这个 PR 之后能做到什么；有 issue 的写 `Resolve #\u003Cnumber>`，再补一句背景。解决办法留给 Code Changes。\n   - **Bug Reproduction Steps**：只有 bug 类 PR 需要；feature 写 `N\u002FA`。步骤已在 issue 里的写 `See linked issue`。\n   - **Root Cause**：只有 bug 类 PR 需要；feature 写 `N\u002FA`。说明根因，以及这是根本修复还是绕过。机制要靠时序或状态才说得清的，用图，见\"代码变更的可视化大纲\"。\n   - **Code Changes**：先判断要不要先建立整体理解，再讲具体变化，见\"讲清楚改动\"。\n   - **Screenshots \u002F Recordings**：模板里没有这一节。有可见的 UI\u002FUX 变化时加在 Code Changes 后面，没有就不加，见\"UI\u002FUX 变化的视觉证据\"。\n   - **Behavior Changes and Affected Users**：先填行为变化表，再列受影响模块与测试覆盖，见\"行为变化与受影响人群\"。验证只写结论：覆盖了哪些场景、哪些没验证；测试文件清单、全量运行结果和修复过程放进折叠块。\n   - **Checklist**：勾上所有适用的项。\n\n5. 发布描述：\n   - 描述里有图片的，先按\"UI\u002FUX 变化的视觉证据\"上传，换成真实链接。\n   - 先存到临时文件，再 `gh pr edit \u003Cnumber> --body-file \u003Cpath>` 或 `gh pr create --body-file \u003Cpath>`。\n   - 确认更新成功。\n\n## 行为变化与受影响人群\n\n这一节回答一个问题：合入之后，现有用户会失去什么。这个仓库过去的回归大多来自没人回答这个问题，而不是逻辑错误。\n\n判据：**改动前能工作的任何输入（配置键、环境变量、命令行参数、provider 响应形态、旧版本写的会话数据、客户端请求、hook 载荷）改动后必须行为不变，除非这里明确声明了变化并给出退路。**\n\n写法：\n\n1. 列出 diff 改变的每一个可观测行为，一行一个。包括你认为\"不变\"但分支条件挪动了的：新增的条件会不会先于旧条件命中既有输入；删除或收窄的分支改动前谁在走。内部包会打进 CLI 发布包，\"内部\"不等于用户无感。表格用 PR 描述的语言，下面的示例用英文只是示意形状：\n\n   | Behavior | Before | After | Who relies on the old behavior | Escape hatch |\n   |---|---|---|---|---|\n   | reasoning parsing when `reasoning_details` is an array | string `reasoning` also read | string ignored | OpenAI-compatible gateways that send both (OpenRouter dialect) | none |\n\n2. 人群要具名，不要写\"部分用户\"。从 `.agents\u002Fskills\u002Freview-pr\u002Fsurfaces.md` 里取：客户端（TUI、print 模式、desktop 与 web、VS Code、ACP、SDK）、provider 方言、平台、配置状态、数据年代、外部脚本。\n\n3. 改了 prompt 文本（system prompt、工具描述、提醒）的，每一句单独成行，写清这句改动前约束了什么行为、谁依赖、现在由什么来约束。\"没有测试引用这句\"不是无影响的证据。\n\n4. 替换或绕过旧路径的（移植、runtime binding、协议替换），额外列出旧路径的功能清单：它认哪些环境变量、有哪些兜底、接受哪些输入，以及每一项在新路径里的位置。\n\n5. 确实没有可观测变化的，写 `None`，并说明证据：哪些分支、默认值、契约文件没动。\n\n6. 表后面列受影响模块与每一行对应的测试覆盖。默认翻转或删除行为的，必须有一条测试把未被改动的人群的旧行为钉住，并且 changeset 要写明用户失去了什么，见 `gen-changesets` skill；没有退路的，在 PR 里请维护者显式拍板。\n\n## 讲清楚改动\n\nCode Changes 要让 reviewer 不看 diff 也能从逻辑和架构上理解这个 PR。先判断要不要先建立整体理解：\n\n- 需要：改动跨多个模块，引入新概念、新数据流或新的部署形态，替换旧路径，或者 diff 大到 reviewer 不知道从哪看起。\n- 不需要：在已有结构里改一个点，比如修一个判断条件。直接用\"代码变更的可视化大纲\"讲变化。\n- 拿不准时问自己：reviewer 不先知道改完后系统长什么样，能看懂具体变化吗？\n\n需要时按下面的顺序写，没有内容的部分省略：\n\n1. **核心思路**：开头一段话，说清用什么办法解决问题、系统的关键变化是什么、对现有用户意味着什么。标准是只读这一段就能复述这个 PR。\n2. **概念**：引入或改变了概念时先定义，一行一个：`概念 | 回答什么问题 | 本 PR 之后`。\n3. **结构图**：用 Mermaid 画改完后系统长什么样：模块、职责、数据流或部署拓扑。节点是模块和职责，不是函数名。图后用一两句话讲清为什么这样组织。\n4. **关键决策**：`决策 | 选择 | 没选 | 理由`。只列 reviewer 可能会问\"为什么不……\"的决策。理由要来自作者的真实考虑；对话和 issue 里没提过、只是你从代码推断出来的理由，先和用户确认再写。\n5. **走一遍**：挑一个典型场景，用 `sequenceDiagram` 沿新路径讲一遍。结构图已经讲清流程时省略。\n6. **阅读指南**：按阅读顺序列出核心文件，每个附一句\"看它能明白什么\"；再用一句话列出可以略读的部分，比如参数透传、接线、重命名、整体删除、测试和文档。\n\n之后再用可视化大纲讲具体变化。有了阅读指南，文件树 diff 通常可以省掉。\n\n不论 PR 大小都遵守：\n- 图表摆事实，句子讲因果。每张图或表后面跟一两句完整的话，说清\"因为、所以、而不是\"；不要把名词短语和函数名堆成一行。\n- 新术语第一次出现就解释。\n- 正文只留理解所需的内容。次要的子流程、长清单、验证过程放进 `\u003Cdetails>\u003Csummary>标题\u003C\u002Fsummary>…\u003C\u002Fdetails>` 折叠块；`\u003C\u002Fsummary>` 后空一行，里面的 Markdown 才会渲染。\n\n## 代码变更的可视化大纲\n\n讲具体变化时用结构化视图，并配一两句话说明因果。用能说清实现的最小组合，没变的类别不要列。\n\n逻辑或算法变化用伪代码 diff：\n\n```diff\n on(save)\n-  write content\n+  if content is unchanged\n+    return cached result\n+  write new content\n+  invalidate cache\n```\n\n运行时控制流用调用树 diff：\n\n```diff\n submitForm\n   createSession\n     persistPrompt\n+    expandSkillMention\n     launchAgent\n-  navigateToSession\n+  navigateToSession\n+    subscribeToEvents\n```\n\n文件职责变化用浅层文件树 diff：\n\n```diff\n src\u002F\n ├── commands\u002F\n+│   └── show-me.ts       # expands the slash command\n ├── sessions\u002F\n-└── transport.ts\n+└── transport\u002F\n+    ├── client.ts\n+    └── stream.ts\n```\n\n组件或 UI 结构变化用树 diff：\n\n```diff\n \u003CSessionPage>\n   useSessionEvents()\n   \u003CSessionToolbar>\n+    \u003CRunSkillButton \u002F>\n   \u003CSessionTimeline>\n+    \u003CSkillResultCard \u002F>\n```\n\n组件之间的交互和时序用 Mermaid `sequenceDiagram`，解释 bug 机制时尤其有用：\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant UI\n    participant Daemon\n    User->>UI: choose command\n    UI->>Daemon: send expanded prompt\n    Daemon-->>UI: stream result\n```\n\n分支判断用 `flowchart`，状态迁移用 `stateDiagram-v2`：\n\n```mermaid\nflowchart TD\n    A[tool output arrives] --> B{hides 2+ lines?}\n    B -- yes --> C[collapse with hint line]\n    B -- no --> D[show all lines]\n```\n\n关键数据结构或类型变化用对应语言的代码块：\n\n```ts\ninterface SessionEvents {\n  onTurnStart(cb: (turn: Turn) => void): void;\n  onTurnEnd(cb: (turn: Turn) => void): void;\n}\n```\n\n可视化大纲的规则：\n- 重点是\"变了什么\"且周边形状已存在时，用 `diff` 块。\n- 大部分是新内容，或 diff 记法会掩盖归属和顺序时，用对应语言或 `text` 块给出完整目标形状。\n- 按最容易理解的顺序讲：先文件还是先数据结构，哪个合适用哪个。\n- 图是为了省 reviewer 的时间：一两句话能说清的不画；一张图只讲一件事，节点多到要来回找时拆成几张。\n- 像一个人对另一个人讲话：简单、连贯、简洁。\n\n## UI\u002FUX 变化的视觉证据\n\n用户看到的东西变了，就让 reviewer 直接看到改动前后的样子，不要只用文字描述。涉及范围：TUI（`apps\u002Fkimi-code\u002Fsrc\u002Ftui`、`packages\u002Fpi-tui`）、`apps\u002Fvis\u002Fweb`、`apps\u002Fvscode\u002Fwebview-ui`、`dist-web` 同步，以及用户可见的文本输出（print 模式输出、报错文案、命令行帮助）。\n\n选能说清变化的最低成本形式：\n\n| 形式 | 适用 | 怎么得到 |\n|---|---|---|\n| 终端文本快照（`text` 代码块） | TUI 的布局、文案、对齐、折叠截断 | 用 `packages\u002Fpi-tui\u002Ftest\u002Fvirtual-terminal.ts` 渲染，或真实运行后复制屏幕内容 |\n| 截图 | 颜色、主题、web 和 webview 界面 | 真实运行后截屏 |\n| GIF | 只用于交互和时序：按键、展开折叠、流式输出、动画 | 本机有录屏工具就录；没有就退回关键帧截图或文本快照，不为此装工具 |\n\n写法：\n- 加在 Code Changes 后面，节标题 `## Screenshots \u002F Recordings`。\n- 改动前后用两列表格并排；全新的界面只放改动后。每组图前用一句话说明该看哪里。\n- 证据来自 PR 分支的真实运行或测试渲染，不要手画示意图冒充。文本快照保持原样，不手工调整对齐。\n- GIF 只录能说明问题的几秒，体积控制在几 MB 内。\n- 素材先放在 `.tmp\u002Fpr-media\u002F`，不提交进 PR 分支。\n\n上传：`gh` 不能把图片传成 GitHub 附件，所以把素材推到 origin 上专门放图的孤立分支 `pr-assets\u002F\u003Cnumber>`。在仓库根目录执行：\n\n```bash\nurl=$(git remote get-url origin)\ndir=$(mktemp -d) && cp .tmp\u002Fpr-media\u002F\u003Cfiles> \"$dir\"\u002F && cd \"$dir\" && git init -q\ngit fetch -q \"$url\" pr-assets\u002F\u003Cnumber> 2>\u002Fdev\u002Fnull && git reset -q --soft FETCH_HEAD  # 分支已存在就接在后面\ngit add -A && git commit -qm \"chore: add screenshots for #\u003Cnumber>\"\ngit push -q \"$url\" HEAD:refs\u002Fheads\u002Fpr-assets\u002F\u003Cnumber>\ngit rev-parse HEAD  # 链接里的 \u003Csha>\n```\n\n引用写成 `![说明](https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002F\u003Csha>\u002F\u003Cfile>?raw=true)`。\n\n- 链接用 `\u003Csha>`，不要用分支名：追加的提交只含新文件，按分支名引用会让旧图失效。\n- 只推 `pr-assets\u002F` 分支，不建 release。CI 只在 `main` 和 `release\u002F*` 的 push 上触发，这类分支不会跑 CI。\n- 不要 force push，合入后也不要删这个分支，否则引用的提交不可达，图会失效。\n- 本仓库公开，上传等于公开发布。上传前逐张看一遍：用中性的工作区和示例数据截图，画面里不能出现本机用户名路径、API key、真实会话内容，以及内部域名、未发布的模型名这类内部标识。\n- 会话里有人类协作时，推送前列出要上传的文件，等对方确认。\n","# 写 PR 描述\n\n为当前分支创建或更新 PR。目标是 reviewer 只读描述，就能从逻辑和架构上理解这个改动：为什么存在、核心思路是什么、改完后系统长什么样、现有用户会失去什么，以及该从哪里开始看代码。\n\n## 工作流\n\n1. 读 PR 模板：\n\n   `Read(.github\u002Fpull_request_template.md)`\n\n2. 找到或创建 PR：\n   - 先查当前分支有没有 PR：`gh pr view --json url,number,title,state 2>\u002Fdev\u002Fnull`。\n   - 没有的话，看 `git status --short --branch` 和当前分支上的提交。\n   - 提交剩余改动，带 upstream 推送分支，用 `gh pr create` 创建 PR。\n   - 遵守仓库的 git 安全规范。\n\n3. 收集解释改动所需的上下文：\n   - 读关联的 issue 和相关任务产物。\n   - 读完整 diff（`git diff main...HEAD`）和足够的周边代码，理解行为与归属。\n   - PR 已存在时，用 `gh pr view` 拿元数据和改动文件列表。\n   - 改动让用户看到的界面或输出变了的，准备视觉证据，见\"UI\u002FUX 变化的视觉证据\"。\n\n4. 按模板各节写描述。描述用用户当前使用的语言，行为变化表也一样；只有三样固定：PR 标题保持英文 Conventional Commit，changeset 保持英文（见 `gen-changesets` skill），节标题沿用模板原文。\n   - **Requirement or Bug**：两三句话讲清谁遇到了什么问题、这个 PR 之后能做到什么；有 issue 的写 `Resolve #\u003Cnumber>`，再补一句背景。解决办法留给 Code Changes。\n   - **Bug Reproduction Steps**：只有 bug 类 PR 需要；feature 写 `N\u002FA`。步骤已在 issue 里的写 `See linked issue`。\n   - **Root Cause**：只有 bug 类 PR 需要；feature 写 `N\u002FA`。说明根因，以及这是根本修复还是绕过。机制要靠时序或状态才说得清的，用图，见\"代码变更的可视化大纲\"。\n   - **Code Changes**：先判断要不要先建立整体理解，再讲具体变化，见\"讲清楚改动\"。\n   - **Screenshots \u002F Recordings**：模板里没有这一节。有可见的 UI\u002FUX 变化时加在 Code Changes 后面，没有就不加，见\"UI\u002FUX 变化的视觉证据\"。\n   - **Behavior Changes and Affected Users**：先填行为变化表，再列受影响模块与测试覆盖，见\"行为变化与受影响人群\"。验证只写结论：覆盖了哪些场景、哪些没验证；测试文件清单、全量运行结果和修复过程放进折叠块。\n   - **Checklist**：勾上所有适用的项。\n\n5. 发布描述：\n   - 描述里有图片的，先按\"UI\u002FUX 变化的视觉证据\"上传，换成真实链接。\n   - 先存到临时文件，再 `gh pr edit \u003Cnumber> --body-file \u003Cpath>` 或 `gh pr create --body-file \u003Cpath>`。\n   - 确认更新成功。\n\n## 行为变化与受影响人群\n\n这一节回答一个问题：合入之后，现有用户会失去什么。这个仓库过去的回归大多来自没人回答这个问题，而不是逻辑错误。\n\n判据：**改动前能工作的任何输入（配置键、环境变量、命令行参数、provider 响应形态、旧版本写的会话数据、客户端请求、hook 载荷）改动后必须行为不变，除非这里明确声明了变化并给出退路。**\n\n写法：\n\n1. 列出 diff 改变的每一个可观测行为，一行一个。包括你认为\"不变\"但分支条件挪动了的：新增的条件会不会先于旧条件命中既有输入；删除或收窄的分支改动前谁在走。内部包会打进 CLI 发布包，\"内部\"不等于用户无感。表格用 PR 描述的语言，下面的示例用英文只是示意形状：\n\n   | Behavior | Before | After | Who relies on the old behavior | Escape hatch |\n   |---|---|---|---|---|\n   | reasoning parsing when `reasoning_details` is an array | string `reasoning` also read | string ignored | OpenAI-compatible gateways that send both (OpenRouter dialect) | none |\n\n2. 人群要具名，不要写\"部分用户\"。从 `.agents\u002Fskills\u002Freview-pr\u002Fsurfaces.md` 里取：客户端（TUI、print 模式、desktop 与 web、VS Code、ACP、SDK）、provider 方言、平台、配置状态、数据年代、外部脚本。\n\n3. 改了 prompt 文本（system prompt、工具描述、提醒）的，每一句单独成行，写清这句改动前约束了什么行为、谁依赖、现在由什么来约束。\"没有测试引用这句\"不是无影响的证据。\n\n4. 替换或绕过旧路径的（移植、runtime binding、协议替换），额外列出旧路径的功能清单：它认哪些环境变量、有哪些兜底、接受哪些输入，以及每一项在新路径里的位置。\n\n5. 确实没有可观测变化的，写 `None`，并说明证据：哪些分支、默认值、契约文件没动。\n\n6. 表后面列受影响模块与每一行对应的测试覆盖。默认翻转或删除行为的，必须有一条测试把未被改动的人群的旧行为钉住，并且 changeset 要写明用户失去了什么，见 `gen-changesets` skill；没有退路的，在 PR 里请维护者显式拍板。\n\n## 讲清楚改动\n\nCode Changes 要让 reviewer 不看 diff 也能从逻辑和架构上理解这个 PR。先判断要不要先建立整体理解：\n\n- 需要：改动跨多个模块，引入新概念、新数据流或新的部署形态，替换旧路径，或者 diff 大到 reviewer 不知道从哪看起。\n- 不需要：在已有结构里改一个点，比如修一个判断条件。直接用\"代码变更的可视化大纲\"讲变化。\n- 拿不准时问自己：reviewer 不先知道改完后系统长什么样，能看懂具体变化吗？\n\n需要时按下面的顺序写，没有内容的部分省略：\n\n1. **核心思路**：开头一段话，说清用什么办法解决问题、系统的关键变化是什么、对现有用户意味着什么。标准是只读这一段就能复述这个 PR。\n2. **概念**：引入或改变了概念时先定义，一行一个：`概念 | 回答什么问题 | 本 PR 之后`。\n3. **结构图**：用 Mermaid 画改完后系统长什么样：模块、职责、数据流或部署拓扑。节点是模块和职责，不是函数名。图后用一两句话讲清为什么这样组织。\n4. **关键决策**：`决策 | 选择 | 没选 | 理由`。只列 reviewer 可能会问\"为什么不……\"的决策。理由要来自作者的真实考虑；对话和 issue 里没提过、只是你从代码推断出来的理由，先和用户确认再写。\n5. **走一遍**：挑一个典型场景，用 `sequenceDiagram` 沿新路径讲一遍。结构图已经讲清流程时省略。\n6. **阅读指南**：按阅读顺序列出核心文件，每个附一句\"看它能明白什么\"；再用一句话列出可以略读的部分，比如参数透传、接线、重命名、整体删除、测试和文档。\n\n之后再用可视化大纲讲具体变化。有了阅读指南，文件树 diff 通常可以省掉。\n\n不论 PR 大小都遵守：\n- 图表摆事实，句子讲因果。每张图或表后面跟一两句完整的话，说清\"因为、所以、而不是\"；不要把名词短语和函数名堆成一行。\n- 新术语第一次出现就解释。\n- 正文只留理解所需的内容。次要的子流程、长清单、验证过程放进 `\u003Cdetails>\u003Csummary>标题\u003C\u002Fsummary>…\u003C\u002Fdetails>` 折叠块；`\u003C\u002Fsummary>` 后空一行，里面的 Markdown 才会渲染。\n\n## 代码变更的可视化大纲\n\n讲具体变化时用结构化视图，并配一两句话说明因果。用能说清实现的最小组合，没变的类别不要列。\n\n逻辑或算法变化用伪代码 diff：\n\n```diff\n on(save)\n-  write content\n+  if content is unchanged\n+    return cached result\n+  write new content\n+  invalidate cache\n```\n\n运行时控制流用调用树 diff：\n\n```diff\n submitForm\n   createSession\n     persistPrompt\n+    expandSkillMention\n     launchAgent\n-  navigateToSession\n+  navigateToSession\n+    subscribeToEvents\n```\n\n文件职责变化用浅层文件树 diff：\n\n```diff\n src\u002F\n ├── commands\u002F\n+│   └── show-me.ts       # expands the slash command\n ├── sessions\u002F\n-└── transport.ts\n+└── transport\u002F\n+    ├── client.ts\n+    └── stream.ts\n```\n\n组件或 UI 结构变化用树 diff：\n\n```diff\n \u003CSessionPage>\n   useSessionEvents()\n   \u003CSessionToolbar>\n+    \u003CRunSkillButton \u002F>\n   \u003CSessionTimeline>\n+    \u003CSkillResultCard \u002F>\n```\n\n组件之间的交互和时序用 Mermaid `sequenceDiagram`，解释 bug 机制时尤其有用：\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant UI\n    participant Daemon\n    User->>UI: choose command\n    UI->>Daemon: send expanded prompt\n    Daemon-->>UI: stream result\n```\n\n分支判断用 `flowchart`，状态迁移用 `stateDiagram-v2`：\n\n```mermaid\nflowchart TD\n    A[tool output arrives] --> B{hides 2+ lines?}\n    B -- yes --> C[collapse with hint line]\n    B -- no --> D[show all lines]\n```\n\n关键数据结构或类型变化用对应语言的代码块：\n\n```ts\ninterface SessionEvents {\n  onTurnStart(cb: (turn: Turn) => void): void;\n  onTurnEnd(cb: (turn: Turn) => void): void;\n}\n```\n\n可视化大纲的规则：\n- 重点是\"变了什么\"且周边形状已存在时，用 `diff` 块。\n- 大部分是新内容，或 diff 记法会掩盖归属和顺序时，用对应语言或 `text` 块给出完整目标形状。\n- 按最容易理解的顺序讲：先文件还是先数据结构，哪个合适用哪个。\n- 图是为了省 reviewer 的时间：一两句话能说清的不画；一张图只讲一件事，节点多到要来回找时拆成几张。\n- 像一个人对另一个人讲话：简单、连贯、简洁。\n\n## UI\u002FUX 变化的视觉证据\n\n用户看到的东西变了，就让 reviewer 直接看到改动前后的样子，不要只用文字描述。涉及范围：TUI（`apps\u002Fkimi-code\u002Fsrc\u002Ftui`、`packages\u002Fpi-tui`）、`apps\u002Fvis\u002Fweb`、`apps\u002Fvscode\u002Fwebview-ui`、`dist-web` 同步，以及用户可见的文本输出（print 模式输出、报错文案、命令行帮助）。\n\n选能说清变化的最低成本形式：\n\n| 形式 | 适用 | 怎么得到 |\n|---|---|---|\n| 终端文本快照（`text` 代码块） | TUI 的布局、文案、对齐、折叠截断 | 用 `packages\u002Fpi-tui\u002Ftest\u002Fvirtual-terminal.ts` 渲染，或真实运行后复制屏幕内容 |\n| 截图 | 颜色、主题、web 和 webview 界面 | 真实运行后截屏 |\n| GIF | 只用于交互和时序：按键、展开折叠、流式输出、动画 | 本机有录屏工具就录；没有就退回关键帧截图或文本快照，不为此装工具 |\n\n写法：\n- 加在 Code Changes 后面，节标题 `## Screenshots \u002F Recordings`。\n- 改动前后用两列表格并排；全新的界面只放改动后。每组图前用一句话说明该看哪里。\n- 证据来自 PR 分支的真实运行或测试渲染，不要手画示意图冒充。文本快照保持原样，不手工调整对齐。\n- GIF 只录能说明问题的几秒，体积控制在几 MB 内。\n- 素材先放在 `.tmp\u002Fpr-media\u002F`，不提交进 PR 分支。\n\n上传：`gh` 不能把图片传成 GitHub 附件，所以把素材推到 origin 上专门放图的孤立分支 `pr-assets\u002F\u003Cnumber>`。在仓库根目录执行：\n\n```bash\nurl=$(git remote get-url origin)\ndir=$(mktemp -d) && cp .tmp\u002Fpr-media\u002F\u003Cfiles> \"$dir\"\u002F && cd \"$dir\" && git init -q\ngit fetch -q \"$url\" pr-assets\u002F\u003Cnumber> 2>\u002Fdev\u002Fnull && git reset -q --soft FETCH_HEAD  # 分支已存在就接在后面\ngit add -A && git commit -qm \"chore: add screenshots for #\u003Cnumber>\"\ngit push -q \"$url\" HEAD:refs\u002Fheads\u002Fpr-assets\u002F\u003Cnumber>\ngit rev-parse HEAD  # 链接里的 \u003Csha>\n```\n\n引用写成 `![说明](https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002F\u003Csha>\u002F\u003Cfile>?raw=true)`。\n\n- 链接用 `\u003Csha>`，不要用分支名：追加的提交只含新文件，按分支名引用会让旧图失效。\n- 只推 `pr-assets\u002F` 分支，不建 release。CI 只在 `main` 和 `release\u002F*` 的 push 上触发，这类分支不会跑 CI。\n- 不要 force push，合入后也不要删这个分支，否则引用的提交不可达，图会失效。\n- 本仓库公开，上传等于公开发布。上传前逐张看一遍：用中性的工作区和示例数据截图，画面里不能出现本机用户名路径、API key、真实会话内容，以及内部域名、未发布的模型名这类内部标识。\n- 会话里有人类协作时，推送前列出要上传的文件，等对方确认。\n",{"name":5,"description":7},"main","54a9e51fcb0531c4dff816e492a8e6d0a598641e",".agents\u002Fskills\u002Fwrite-pr",1377,"https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code","https:\u002F\u002Fwww.kimi.com\u002Fcode\u002Fdocs\u002F","https:\u002F\u002Fgithub.com\u002FMoonshotAI","https:\u002F\u002Fmoonshot.ai","2026-11-14 19:55:03",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add MoonshotAI\u002Fkimi-code --skill write-pr",{"tool":39,"command":40},"bunx","bunx skills add MoonshotAI\u002Fkimi-code --skill write-pr",{"tool":42,"command":43},"pnpm","pnpm dlx skills add MoonshotAI\u002Fkimi-code --skill write-pr","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwrite-pr\u002FSKILL.md",true,[],[48,55,61,68,75,82],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M74ETAEBHZ0QS6Y4BT29PKNF","golden-skill","Golden fixture skill","https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002Fmain\u002Fpackages\u002Fmigration-legacy\u002Ftest\u002Ffixtures\u002Fgolden\u002F.kimi\u002Fskills\u002Fgolden-skill\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":58,"categories":59,"keywords":60,"publishedAt":19},"01M74ET9QF6YK6KD5KM2W4XPBD","tools","https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002Fmain\u002Fpackages\u002Fagent-core-v2\u002Fsrc\u002Ffeatures\u002Fskill\u002Ftools\u002Fskill.md",[],[],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M74ET7K1MXGBYV91558T1VMC","review","Analyze the available skill set and recommend candidate groups that could be consolidated into sub-skill bundles. Read-only — proposes a plan, does not move files.","https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002Fmain\u002Fpackages\u002Fagent-core-v2\u002Fsrc\u002Ffeatures\u002Fskill\u002Fcatalog\u002Fbuiltin\u002Fsub-skill\u002Freview\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M74ET2KQ5CC4JCFGBSG0YXM3","consolidate","Apply an approved sub-skill grouping by moving user-specified skills into a parent bundle, with timestamped backups of every modified directory.","https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002Fmain\u002Fpackages\u002Fagent-core-v2\u002Fsrc\u002Ffeatures\u002Fskill\u002Fcatalog\u002Fbuiltin\u002Fsub-skill\u002Fconsolidate\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M74ET036WTFZ4XH9KC2M84KQ","sub-skill","Discover and reorganize the skill inventory into hierarchical sub-skill bundles. Use when the user asks to review, group, or consolidate skills into a parent bundle.","https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002Fmain\u002Fpackages\u002Fagent-core-v2\u002Fsrc\u002Ffeatures\u002Fskill\u002Fcatalog\u002Fbuiltin\u002Fsub-skill\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M74ESXAT6AX5YG29SN3WY83J","write-tui","Use when writing or modifying the kimi-code terminal UI in apps\u002Fkimi-code\u002Fsrc\u002Ftui — components, dialogs\u002Fselectors, slash commands, themes, streaming render, or the KimiTUI controllers. Covers the architecture, where new features go, test placement, the theme system mechanics, and the dialog interaction\u002Fvisual spec (DESIGN.md).","https:\u002F\u002Fgithub.com\u002FMoonshotAI\u002Fkimi-code\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwrite-tui\u002FSKILL.md",[],[]]