企业官网建设流程全解析

• AI 应用
• Agent 工作流
• 开发工具
• MCP 服务

CC Workflow Studio（cc-wf-studio）是一个以 Claude Code 为代表的 AI 编程代理可视化工作流编排工具，仓库以 pnpm + Changesets 管理四个独立版本化的包（core / mcp / cli / vscode）。当一次修复改动需要合入main分支时，仓库通过.claude/skills/pr-to-main这个 Claude Code Skill 自动生成 PR，而assets/fix-template.md就是其中专门面向bug fix（fix:提交）的 PR 正文模板。本文完整解读该模板的每一节结构与填写要求，并结合仓库真实的 changeset 文件、包结构与提交规范，说明如何在 cc-wf-studio 中产出一份“发布管线真正可消费”的修复 PR——包括Problem / Solution / Release / Impact / Testing的标准骨架、当前行为与期望行为的对照写法，以及.changeset/*.md文件的生成与提交时机。

模板在仓库中的定位：pr-to-main Skill 的三套 PR 模板之一

fix-template.md位于.claude/skills/pr-to-main/assets/目录，与 feat-template.md（新功能：Summary/Motivation/Changes）和 improvement-template.md（增强：Before/After 对比）并列。pr-to-mainSkill 的元数据声明其适用时机是：用户提出“创建 PR 到 main”“main に PR”等意图、需要提交改动供评审时。Skill 会先完成一系列上下文收集与变更分析（见 SKILL.md），然后根据变更类型选择模板：

• fix:/fix(vscode):前缀 → 使用 fix-template.md，即本文讲解的对象；
• feat:/feat(core):前缀 → 使用 feat-template.md；
• improvement:前缀 → 使用 improvement-template.md。

需要强调：模板选择的前提是确认受影响包与变更类型。Skill 规定必须把分支上全部提交的前缀都审查一遍（而不仅是最近一条），再据此判定类型。例如一条fix(vscode): parse Changesets-format CHANGELOG提交，对应的是packages/vscode的 bug 修复，因此使用 fix 模板。

逐节解读：fix-template.md 的完整骨架

fix-template.md的核心设计理念是问题先行（Problem）：一段高质量的修复 PR 必须让评审者、发布维护者和未来的维护者都能一眼看清“发生了什么问题 → 期望是什么 → 改了什么 → 是否触发发布”。模板全文按以下七节组织：

1.## Problem— 问题描述

## Problem [Description of the problem]

在真实 PR 中，这里应填写一段面向读者的问题概述：哪个功能失效、在什么场景下暴露、影响哪些用户路径。描述要具体，避免泛泛而谈——评审者需要仅凭这一段就能判断修复的必要性。

2.### Current Behavior— 当前（错误）行为

### Current Behavior 1. [Step] 2. ❌ [Problematic behavior]

用有序列表按步骤复现错误路径，并在出错的步骤前用❌标记。这是“复现步骤 + 症状”的标准写法：第 1 步是操作或触发条件，第 2 步是被观察到的错误行为。例如：1. 打开工作流属性面板；2. ❌ MCP 节点参数校验直接抛错导致面板无法编辑。

3.### Expected Behavior— 期望（正确）行为

### Expected Behavior 1. [Step] 2. ✅ [Expected behavior]

与 Current Behavior 保持相同步骤编号，仅将❌换成✅，形成“同步骤、异结果”的强对照。这一对结构是 fix 模板区别于 feat/improvement 模板的独特价值：它让 Reviewer 无需重建上下文，直接看到“同一条路径上，修复前 vs 修复后”的差异。

4.## Solution— 修复方案

## Solution [Summary of the solution]

一句话或一小段概括修复策略（例如“改为在解析阶段提前校验并回退到默认端口”“将 CHANGELOG 解析改为兼容 Changesets 格式”），随后在### Changes中列出改动明细。

5.### Changes— 改动清单（必须使用真实 monorepo 路径）

### Changes **File**: `packages/<pkg>/src/...` [List of changes]

这是模板中最需要结合仓库实际的部分。packages/<pkg>/不是占位符惯例——cc-wf-studio 是一个四包 pnpm monorepo（见 pnpm-workspace.yaml 与 CLAUDE.md），Skill 明确要求正文必须写真实路径而非泛化占位符。包与目录的对应关系如下：

例如一个真实的修复 PR 应写成packages/vscode/src/extension/services/changelog-parser.ts这样的完整路径，而不是packages/<pkg>/src/...的原始占位。

6.## Release— 发布意图声明（Changesets 关键步骤）

## Release - Changeset: [e.g. `patch` for `cc-wf-studio` / no release needed (empty)]

这一节在模板里看似只有一行，却是整个 PR 流程中最容易出错、也最影响发布管线的部分。cc-wf-studio 的版本管理由 Changesets 驱动（见 docs/release-flow.md 的标题声明：This repository uses Changesets for versioning across the pnpm workspace），发布并不由 commit message 触发。两个仓库事实决定了它的写法：

1. 值得发布的改动必须与.changeset/*.md文件同 PR 提交。否则改动合并后永远不会被发布，且累积的 pending changeset 会阻塞后续升级发布。
2. bump 级别决定 PR 的发布影响。fix:类改动对应patch（见 CLAUDE.md 的提交类型表：fix:- Bug fix (patch version bump)）；feat:对应minor。

Release节因此应该明确写出两种结果之一：

• Changeset: patch for cc-wf-studio（该 PR 附带了一个针对cc-wf-studio的 patch changeset）；
• Changeset: no release needed (empty)（CI/文档/工具链改动，已通过pnpm changeset add --empty显式声明不发布）。

在模板基础上，Skill 还要求正文中明确提及 changeset 的存在与级别，例如"Adds apatchchangeset forcc-wf-studio"，让评审者在 Review 时就能看到预期的发布效果。

7.## Impact— 影响范围

## Impact - [Impact 1] - [Impact 2]

以列表形式列出修复可能波及的模块、行为或兼容性风险。例如：- 内置 MCP 服务器端口回退行为对所有使用 AI 编辑的窗口生效、- CHANGELOG 解析格式变更影响 Release PR 的变更日志预览。影响声明应覆盖内部依赖传播——因为 .changeset/config.json 设置了"updateInternalDependencies": "patch"，@cc-wf-studio/core的 bump 会自动（patch）带动cli/mcp更新依赖范围，这类联动效应值得在 Impact 中说明。

8.## Testing— 测试状态

## Testing - [x] Manual testing completed - [ ] Pending tests

cc-wf-studio 的测试策略是手动 E2E 优先（见 CLAUDE.md：Unit/Integration tests: Not required; Manual E2E testing: Required for all feature changes and bug fixes）。模板默认勾选Manual testing completed并保留Pending tests待办项，填写时应如实标注：修复是否已在 VSCode Extension Development Host 中手动验证、CI（pnpm check && pnpm build）是否通过。

9.## Notes— 附加说明（可选）

## Notes - Additional notes (optional)

用于补充非结构化的上下文：已知限制、后续跟进项、关联 issue 等。末尾的🤖 Generated with Claude Code行表示该 PR 由 Claude Code 生成，属于模板的固定署名，保留即可。

实操衔接：从模板到可合入 PR 的完整工作流

fix-template.md只是最终输出的“正文骨架”，它被 SKILL.md 中的 Workflow 步骤串联起来。一次完整的 fix PR 生成包含以下动作，模板在其中各司其职：

1. 收集上下文（并行执行）：git status、git diff、git diff origin/main...HEAD、git log origin/main..HEAD --oneline逐条检查分支提交前缀，并ls .changeset/*.md检查是否已有 changeset。
2. 判定受影响包与类型：把改动路径映射到四个包（packages/core→@cc-wf-studio/core，packages/vscode→cc-wf-studio，等等）；fix:/fix(vscode):→ fix 类型。packages/之外的改动（根配置、.github/、文档）通常无需发布。
3. 确保 changeset 存在（monorepo 关键步骤）：
   • 已存在且覆盖本改动的 changeset：核对包名与 bump 级别后继续；
   • 需要发布但尚无 changeset：运行pnpm changeset，选择受影响包、选择patch/minor/major、写一行摘要（该摘要将成为 CHANGELOG 条目）；
   • 确实无需发布：运行pnpm changeset add --empty显式声明意图，避免发布管线“猜测”。
4. 验证构建：在仓库根目录运行pnpm check && pnpm build（Biome + 类型检查 + 全量编译）。
5. 按类型选模板：fix:→ fix-template.md；feat:→ feat-template.md；improvement:→ improvement-template.md。
6. 创建 PR：无 upstream 时git push -u，然后gh pr create --base main填充所选模板。

PR 标题与语言规范

Skill 明确了两条仓库规则（与 CLAUDE.md 的 Language 一节一致）：

• 标题与正文一律使用英文（仓库规则，无论与 Claude 的对话使用什么语言）；
• main采用 squash 合并，因此 PR 标题会直接成为 squash 提交的 subject，必须符合提交规范<type>(<scope>): <description>：
  • <type>：fix/feat/improvement/docs/refactor/chore/ci；
  • <scope>：受影响包/区域，使用目录名（vscode/cli/mcp/core），多包写(cli, mcp)；仓库级改动（根配置、.github/、顶层文档）省略 scope；
  • <description>：祈使语气、句末无句号、尽量 ≤50 字符（GitHub squash 时会追加(#NN)后缀）。

仓库历史中的真实示例：fix(vscode): parse Changesets-format CHANGELOG、feat(cli): ccwf install-skills subcommand、docs: add root README for the monorepo。

源码级佐证：真实 changeset 与发布管线如何呼应模板

为了让Release/Impact两节有据可依，仓库中保留了多个真实 changeset 示例，可作为填写模板时的参照：

真实示例一（add-fable-model-ssot.md，minor级）——对应feat:类改动：

--- '@cc-wf-studio/core': minor 'cc-wf-studio': minor --- Add 'fable' (Claude Fable 5) to sub-agent and slash command model options. Model values are now exported from core as `SUB_AGENT_MODEL_VALUES` / `SubAgentModel` ...

它的 frontmatter 明确列出受影响的包与 bump 级别，正文一行摘要（将被写入 CHANGELOG）——这正是pnpm changeset交互式生成物的标准形态，也解释了模板Release节为何要求注明“针对哪个包、什么级别”。

真实示例二（mcp-port-auto-fallback.md，patch级）——对应fix:类改动：

--- 'cc-wf-studio': patch --- MCP server: when the configured port is already in use (another VS Code window, a stale process), automatically fall back to an OS-assigned free port instead of failing AI agent launch. The setting cc-wf-studio.mcp.port now acts as a preferred port; an info toast reports the fallback.

这段描述包含了“问题场景（端口被占用导致 AI agent 启动失败）→ 修复行为（回退到系统分配的空闲端口）→ 行为变化（cc-wf-studio.mcp.port变为首选端口，出现信息提示）”，恰好就是 fix-templateProblem → Solution → Impact三段在 changeset 层面的浓缩版。修复类改动以patch级别发布，与 CLAUDE.md 的提交类型表完全一致。

发布管线侧：合并后的发布行为由 docs/release-flow.md 描述——main是唯一发布分支，Release PR 由维护者手动触发（.github/workflows/release-version-pr.yml，workflow_dispatch），合并 Release PR 进main时自动触发release.yml的 publish 步骤（pnpm changeset publish，npm OIDC Trusted Publishing，无NPM_TOKEN）。cc-wf-studio（VSCode 扩展）是"private": true，Changesets 只为其打 tag，发布产物是附带在 GitHub Release 上的.vsix，由 Repository Owner 手动上传到 VS Marketplace / Open VSX。正因为发布是“人工确认 = 自动发布”的设计，模板中Release一节的如实填写，直接决定了这条 PR 在 Release PR 阶段被消费时产生的是真实版本 bump 还是空发布。

常见误区与核对清单

结合模板结构与仓库约束，填写 fix PR 时最需要避免的几类错误：

1. 只写提交信息、不写正文结构：模板的 Problem/Solution 骨架要求“为什么、怎么修”放在 PR 正文，而 commit 只保留 ≤50 字符的 subject 与 3–5 条 “what changed” 要点（见 CLAUDE.md 的 Commit Message Guidelines，明确Put "why" and "how" in PR description, NOT commit message）。
2. Changes 节使用泛化占位符：必须替换为packages/<pkg>/src/...对应的真实路径，否则评审者与后续维护者无法定位改动。
3. 有发布价值的改动缺少 changeset：会导致改动合入main后永不发布，并累积 pending changeset 阻塞 Release PR；fix:必须带patchchangeset（或显式 empty changeset 声明无需发布）。
4. 忽略内部依赖传播：bump@cc-wf-studio/core会自动带动cli/mcp（updateInternalDependencies: "patch"），不要在 Release 节重复为依赖包写多余 changeset。
5. PR 标题不符合 squash 提交规范：main是 squash 合并，标题会成为 squash commit subject，必须遵循<type>(<scope>): <description>格式。

一个健康的 fix PR 核对清单可以浓缩为：Problem（含 Current vs Expected 对照）→ Solution（真实路径的 Changes）→ Release（正确的 patch changeset）→ Impact（含依赖传播影响）→ Testing（手动 E2E 已勾选）→ Notes（可选补充），且标题为fix(<scope>): <描述>、正文与标题均为英文。合并后如需清理分支，可参考 pr-to-main-cleanup Skill 的命令（squash 合并无法被 git 识别为 merged，需用-D强制删除本地分支并git push origin --delete删除远端分支）。遵循这套模板与流程，就能确保每一次修复都成为发布管线可消费、评审者可理解、历史可追溯的规范提交。

• AI 应用
• Agent 工作流
• 开发工具
• MCP 服务