goose-blog-post

Goose 博客文章

为由 Docusaurus 提供支持的 block/goose 开源项目博客撰写博客文章。

前提条件

• 必须已在本地克隆 goose 仓库
• 找到博客目录 <goose-repo>/documentation/blog/
• 继续操作前，确认 authors.yml 和博客目录均存在

如果尚未克隆仓库，请克隆：

gh repo clone block/goose

工作流

步骤 1：确定写作模式

询问用户希望如何开展写作。共有三种模式：

1. “我有草稿” — 作者已经写好（或准备自行撰写）内容。Agent 创建目录、frontmatter 和图片配置，然后将作者的内容放入正确格式，并根据博客规范进行检查。

2. “我有笔记／大纲” — 作者有一些粗略想法、要点或大纲。Agent 在保留作者风格和关键观点的基础上，将其扩写为完整草稿。定稿前先将草稿交由作者审阅。

3. “帮我写” — 作者提供主题和关键要点。Agent 撰写完整文章。定稿前先将草稿交由作者审阅。

重要提示： 对于模式 1 和 2，应优先保留作者的风格和意图。不要不必要地改写作者的内容。重点应放在结构、规范和润色上，而不是替换作者的措辞。

步骤 2：收集博客文章详情

询问用户以下信息（不要自行假设）：

1. 主题：博客文章的主题是什么？
2. 作者：作者是谁？（需与 authors.yml 中的键匹配）
3. 目标受众：文章面向哪些读者？（开发者、初学者、社区成员等）

对于模式 2 和 3，还要询问： 4. 关键要点：文章需要涵盖哪些主要内容？ 5. 语气：技术深度解析、轻松讲解、公告等？

对于模式 1，询问： 4. 草稿位置：文件路径，或者请用户直接粘贴草稿。

步骤 3：确认作者是否存在

检查 <goose-repo>/documentation/blog/authors.yml 中是否有对应的作者键。

如果作者不存在，请创建一个新条目。格式如下：

authorkey:
  name: Full Name
  title: Job Title
  image_url: https://avatars.githubusercontent.com/u/<github-id>?v=4
  page: true
  socials:
    github: github-username
    x: x-username
    linkedin: linkedin-username

询问用户缺失的详细信息（姓名、头衔、GitHub 用户名、社交媒体账号）。image_url 可根据其 GitHub 个人资料生成：https://avatars.githubusercontent.com/u/<id>?v=4。如有需要，查询其 GitHub 用户 ID：

gh api users/<username> --jq '.id'

步骤 4：创建博客文章目录

博客文章采用以下命名约定：

YYYY-MM-DD-slug-title/
  index.md
  banner.png

规则：

• 使用今天的日期（运行 date +%Y-%m-%d 获取）
• slug 应全部使用小写字母，以连字符分隔，简洁且能说明内容
• 目录位于 <goose-repo>/documentation/blog/ 中

mkdir -p documentation/blog/YYYY-MM-DD-slug-title

步骤 5：整理博客文章

在新目录中创建 index.md。文件结构如下：

1. Frontmatter

---
title: "Your Blog Post Title"
description: "A concise summary of the post (1-2 sentences). Used in social previews and SEO."
authors:
  - authorkey
---

Frontmatter 规则：

• title — 使用引号包裹，并采用标题式大小写
• description — 使用引号包裹，控制在 1–2 句话内，并适合在社交媒体上分享
• authors — 使用 YAML 列表填写 authors.yml 中的作者键（支持多位作者）
• 不要添加 date 字段 — Docusaurus 会从目录名中提取日期
• 不要在 frontmatter 中添加 tags — 该博客不使用 Docusaurus 标签

2. 横幅图片

每篇文章都必须在 frontmatter 后立即包含一张横幅图片：

![blog banner](banner.png)

横幅图片要求：

• 尺寸： 1200×600 像素
• 位置： 与 index.md 位于同一目录
• 文件名： banner.png（或 .jpg、.webp）
• 这张图片也用于社交分享（Open Graph / Twitter 卡片）——无需单独的社交分享图片

如果用户尚未准备好图片，请添加图片引用作为占位符，并提醒他们在发布前添加文件。如果有图片生成工具，也可以提出代为生成图片。

3. 引言 + 截断标记

引言段落应放在截断标记之前，用于控制博客索引页面上的预览：

![blog banner](banner.png)

Your compelling introduction paragraph that hooks the reader.

引言应：

• 吸引读者——为什么值得关注？
• 最多 1-3 个段落
• 提供足够的背景信息，让读者判断是否要点击阅读全文

4. 正文

模式 1（作者的草稿）： 在此处放入作者的内容。仅进行必要的调整，使其符合下文的格式规范。如有问题，请告知作者，而不是悄悄改写。

模式 2 和 3： 按照下文的指南撰写内容，然后将完整草稿交由作者审核。

格式规范：

• 使用 ## 标记主要章节，使用 ### 标记子章节
• 正文中不要使用 #（h1）——frontmatter 中的标题就是 h1
• 代码块应包含语言标识符（```python、```bash 等）
• 使用项目符号列表和编号列表来拆分密集的信息
• 段落应简短（2-4 句），以便阅读
• 结尾应明确总结要点、号召行动或说明后续步骤

语气与风格：

• 分享个人经历时使用第一人称，发布公告时使用第三人称
• 表达要通俗自然，同时确保技术准确
• goose 博客的读者是开发者——尊重他们的专业知识
• 避免空洞的营销话术；内容应真诚且具体
• 与其进行抽象解释，不如提供具体示例和代码片段

goose 专属规范：

• 提及该工具时，项目名称使用小写形式 "goose"
• 链接到 goose 文档时使用：https://block.github.io/goose/
• 链接到仓库时使用：https://github.com/block/goose
• 链接到扩展时使用：https://block.github.io/goose/extensions

5. 社交媒体元数据（<head> 部分）——必需

每篇博客文章都必须以包含 Open Graph 和 Twitter 卡片元标签的 <head> 部分结尾。该部分应放在 index.md 文件的最末尾，位于所有内容之后：

<head>
  <meta property="og:title" content="YOUR TITLE HERE" />
  <meta property="og:type" content="article" />
  <meta property="og:url" content="https://block.github.io/goose/blog/YYYY/MM/DD/slug-title" />
  <meta property="og:description" content="YOUR DESCRIPTION HERE" />
  <meta property="og:image" content="https://block.github.io/goose/assets/images/BANNER_FILENAME_WITH_HASH.png" />
  <meta name="twitter:card" content="summary_large_image" />
  <meta property="twitter:domain" content="block.github.io" />
  <meta name="twitter:title" content="YOUR TITLE HERE" />
  <meta name="twitter:description" content="YOUR DESCRIPTION HERE" />
  <meta name="twitter:image" content="https://block.github.io/goose/assets/images/BANNER_FILENAME_WITH_HASH.png" />
</head>

重要提示：og:image 和 twitter:image 的 URL 必须包含 Docusaurus 生成的文件名，其中带有内容哈希。不能猜测这个文件名——必须从本地预览中获取。获取方法见步骤 6。

字段参考：

• og:title / twitter:title——与 frontmatter 中的 title 相同
• og:description / twitter:description——与 frontmatter 中的 description 相同
• og:url——生产环境 URL：https://block.github.io/goose/blog/YYYY/MM/DD/slug-title
• og:image / twitter:image——从本地预览中获取的静态图片 URL（见步骤 6）
• twitter:card——始终为 summary_large_image
• twitter:domain——始终为 block.github.io

首次创建文章时，将 https://block.github.io/goose/assets/images/BANNER_FILENAME_WITH_HASH.png 用作 og:image 和 twitter:image 的占位 URL。完成步骤 6 后，将 BANNER_FILENAME_WITH_HASH 部分替换为真实文件名。

步骤 6：在本地预览并获取图片 URL

作者需要在本地预览博客文章，以便：

1. 确认文章显示正常
2. 获取 <head> 社交媒体元数据所需的静态图片 URL

请告知用户在单独的终端中运行以下命令（不要直接运行该命令——它会阻塞终端）：

cd <goose-repo>/documentation
npm start

这会在 http://localhost:3000 启动本地开发服务器，并启用热重载。

预览运行后，请指导用户：

1. 在浏览器中打开其博客文章
2. 右键点击横幅图片 → 复制图片地址
3. 复制的 URL 类似于： http://localhost:3000/goose/assets/images/banner-a1b2c3d4e5f6.png
4. 提取文件名（例如 banner-a1b2c3d4e5f6.png）
5. 构造生产环境 URL： https://block.github.io/goose/assets/images/banner-a1b2c3d4e5f6.png

使用此生产环境 URL 更新 <head> 部分中的 og:image 和 twitter:image。

步骤 7：呈交草稿供审核

这一步至关重要。 在认为文章已完成之前：

• 向作者展示完整的 index.md 内容
• 说明你做出的任何决定（标题措辞、章节结构、引言的切入方式）
• 询问作者是否想调整任何内容
• 对于模式 1：指出你做出的格式调整及其原因

根据反馈反复修改，直到作者满意。

步骤 8：最终审核清单

逐项检查此清单并修复所有问题：

• 目录遵循 YYYY-MM-DD-slug-title/ 命名约定
• 目录中存在 index.md
• Frontmatter 包含 title、description 和 authors
• authors.yml 中存在作者键
• Frontmatter 后引用了横幅图片（1200×600）
• 横幅图片文件存在于目录中（或已标记为需要添加）
• `` 标记放置在引言之后
• 正文中没有 #（h1）标题——仅使用 ## 及以下级别
• 代码块包含语言标识符
• 指向 goose 资源的链接使用了正确的 URL
• 文件末尾包含 <head> 部分
• og:image 和 twitter:image URL 已根据本地预览填写
• 拼写和语法无误
• 文章从头到尾读起来流畅

适合的内容类型

帮助作者构思或选择方向时，以下格式通常适用于 goose 博客：

• 教程和操作指南 — “我如何使用 goose 构建 X”
• 深入解析 — 架构、功能或设计决策
• 社区聚焦 — 贡献者故事和用例
• 对比 — goose 与其他工具的比较，给出客观评估
• 发布公告 — 新增内容及其重要意义
• 技巧和工作流 — 高级用户指南和效率技巧
• 思想领导力 — 对 AI Agent、开发者工具和开源的观点

示例

一篇完整的博客文章：

---
title: "Building a Custom MCP Server for Your Team"
description: "A step-by-step guide to creating a Model Context Protocol server that connects goose to your team's internal tools."
authors:
  - ebony
---

![blog banner](banner.png)

If your team has internal tools that aren't covered by existing extensions, building a custom MCP server is easier than you think. In this post, I'll walk through how I built one for our team's deployment pipeline.



## Why Build a Custom MCP Server?

goose connects to tools through the Model Context Protocol (MCP). While there are hundreds of community extensions available, sometimes your team has unique internal tools that need a custom integration.

## Getting Started

First, scaffold a new MCP server project:

```bash
npx create-mcp-server my-server
cd my-server
```

## Defining Your Tools

The core of any MCP server is its tool definitions...

## Wrapping Up

Building an MCP server took about an hour and saved our team countless context switches. If you want to learn more, check out the [MCP documentation](https://modelcontextprotocol.io/introduction) and the [goose extensions directory](https://block.github.io/goose/extensions).

<head>
  <meta property="og:title" content="Building a Custom MCP Server for Your Team" />
  <meta property="og:type" content="article" />
  <meta property="og:url" content="https://block.github.io/goose/blog/2025/07/01/custom-mcp-server" />
  <meta property="og:description" content="A step-by-step guide to creating a Model Context Protocol server that connects goose to your team's internal tools." />
  <meta property="og:image" content="https://block.github.io/goose/assets/images/banner-a1b2c3d4e5f6.png" />
  <meta name="twitter:card" content="summary_large_image" />
  <meta property="twitter:domain" content="block.github.io" />
  <meta name="twitter:title" content="Building a Custom MCP Server for Your Team" />
  <meta name="twitter:description" content="A step-by-step guide to creating a Model Context Protocol server that connects goose to your team's internal tools." />
  <meta name="twitter:image" content="https://block.github.io/goose/assets/images/banner-a1b2c3d4e5f6.png" />
</head>