企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• Agent 框架
• 多智能体
• 工具调用
• MCP 服务

本文基于 site/CMS-TODO.md 这份站点工程待办清单，结合 harness-sdk 仓库中 站点构建配置、内容集合 Schema 与 博客渲染管线 等真实实现，系统梳理该文档所列的两类任务：一是站点从旧版 MkDocs 迁移到 Astro/Starlight 之后遗留的构建链技术债（zod SSR 绕行方案、typedoc 特判、资产目录迁移等）；二是博客模块待补齐的机器可读分发与内容增强能力（全内容 RSS、内容协商、作者头像、封面图等）。读完本文，你将能逐条理解这些 TODO 背后的代码位置、现状成因与可落地的改造思路，可作为参与该站点工程维护的入门路线图。

一、文档定位：一份 CMS 迁移后的收尾路线图

site/CMS-TODO.md是站点（site/目录）从旧版 MkDocs 内容结构迁移到 Astro + Starlight 内容集合体系之后维护者整理的未完成事项清单。它只包含两种任务类型：

• After Launch（上线后清理）：5 条构建期技术债，全部围绕"让构建更干净、让类型验证更独立"这一目标；
• Blog（博客能力）：9 条博客模块的功能缺口，集中于机器可读分发（RSS、内容协商、Markdown 端点）与内容表现力（OG 图、头像、封面图）两个方向。

这份清单本身没有提供实现代码，但它逐条指向的模块（astro.config.mjs、scripts/api-generation-typescript.ts、src/pages/blog/下的端点、src/content.config.ts的集合 Schema）在仓库中都真实存在且可被逐条对照验证，因此可以作为一篇有依据的工程演进指南来展开。

二、构建链技术债清理（After Launch）

2.1 移除 zod 的 Vite SSR 绕行方案

TODO 原文要求：一旦 CMS 构建与 TS 类型验证分离后，移除astro.config.mjs中的 Vite SSR workaround for zod。

在 site/astro.config.mjs 中可以找到这段绕行代码：

vite: { plugins: [sdkSetupPlugin(), watchNavigationPlugin()], // TODO once we separate out CMS build from TS verification, fix this // https://github.com/withastro/astro/issues/14117 ssr: { noExternal: ['zod'], }, },

其背景是：站点内容 Schema 大量使用astro/zod（见 site/src/content.config.ts），在 Astro SSR 构建阶段 zod 被当作外部依赖处理会触发打包问题，因此用ssr.noExternal: ['zod']强制将其内联。TODO 记录的思路是：当 CMS 构建流程与 TS 类型检查流程解耦后，这一绕行即可移除。当前阶段的验证方式是在 site/test/content-collection.test.ts 等测试中观察构建行为，若没有该绕行仍然全绿，就可以删除这一段配置并回归验证。

2.2 移除<name>Data特殊处理

typedoc 在生成 TypeScript API 文档的散文（prose）描述时，会字面输出形如 "the<name>Datapattern" 的文本，其中<name>是尖括号包裹的占位符，直接进入 Markdown 会被当作 HTML 标签吞掉。

site/scripts/api-generation-typescript.ts 中为此保留了一段特殊处理：

// Special-case: escape the literal string "<name>Data" which typedoc emits in prose // to describe the naming pattern for data interfaces (e.g. "the <name>Data pattern"). const specialCased = linkedFixed.replace(/<name>Data/g, '&lt;name>Data')

同一文件中（L146）还处理了相对链接中的分类目录折叠（../interfaces/AgentData.md -> ../AgentData.md）。TODO 的意图是：一旦 typedoc 修复了散文中的<name>Data输出，或找到更通用的转义方案，就删除这个replace特判，避免生成管线里堆叠一次性 hack。

2.3 资产文件迁移到内容集合目录

TODO 原文指出：资产文件当前位于docs/assets/，应迁移到src/content/docs/assets/。

从 site/src/content.config.ts 可以看到docs集合的加载范围是src/content下若干显式声明的文件夹（docs/user-guide、docs/integrations、docs/api/python、docs/api/typescript等），这意味着docs/根目录下的静态资产并不属于内容集合的一部分，而是游离在构建与缓存体系之外。将其迁入src/content/docs/assets/后，图片等资产将与文档正文一起参与 Astro 内容管线的处理（包括assets的 import 解析、哈希文件名与压缩策略），同时避免旧 MkDocs 时代的路径假设继续残留。

2.4 TypeScript 代码示例内联 + 独立类型检查

TODO 要求：将 TypeScript 代码示例直接内联进 Markdown，并通过独立的类型检查步骤（例如对提取出的代码块执行tsc）来验证，替代当前的 "snippet includes"（外部代码片段引入）方案。

当前仓库仍在使用 snippet 引入机制：站点在构建期通过 site/src/plugins/remark-mkdocs-snippets.ts 解析文档中的 include 指令，并在 site/astro.config.mjs 中注册该 remark 插件。这种方案的缺点是把"示例代码是否正确"的验证责任压在构建期文档渲染上。TODO 描绘的演进方向是：示例代码直接写在 Markdown 的 fenced code block 里，再单独用一个脚本抽取代码块并交给tsc做类型检查，使"文档示例的类型正确性"成为与 CMS 构建解耦的独立质量门禁。

2.5 更新 astro-auto-import

TODO 记录了等待上游 astro-auto-import 的 PR #110 合并后更新本仓库的引用。当前 site/astro.config.mjs 已经通过AutoImport集成了TabItem/Tab、Tabs、Syntax、CopyPromptButton、YouTube等组件的自动导入，并支持defaultComponents覆盖a链接为 site/src/components/PageLink.astro 以支持相对 URL。升级上游后，这些导入配置的写法与解析行为可能会随之变化，需要在升级时同步回归验证 site/test/language-switch.test.ts 等涉及组件导入的测试。

三、博客模块的机器可读分发能力（Blog）

3.1 全内容 RSS（当前仅含描述）

TODO 指出：当前 RSS 只包含description，不含渲染后的 MDX 正文。

现状在 site/src/pages/blog/feed.xml.ts 中清晰可见：items的每一项只映射了title、pubDate、description、link与categories（来自post.data.tags），并没有 body 字段：

items: posts.map((post) => ({ title: post.data.title, pubDate: post.data.date, description: post.data.description, link: pathWithBase(`/blog/${post.id}/`), categories: post.data.tags, })),

同一目录下还有按标签分流的 site/src/pages/blog/feed/[tag].xml.ts，同样只带description。要做成全内容 RSS，可以复用博客的 Markdown 渲染管线（site/src/util/render-to-markdown.ts）——该工具已被 site/src/pages/blog/[slug]/index.md.ts 用于将 MDX 渲染为干净 Markdown，RSS 端点可基于它把正文追加到<content:encoded>或标准的content字段中。

3.2 基于 Accept 头的响应式内容协商

TODO 提到：通过Accept请求头做内容协商，让同一 URL 按客户端偏好返回 HTML 或 Markdown；但这需要 edge/CDN 中间件支持，与纯静态生成（SSG）不兼容。

仓库目前的处理方式是为每个博客帖单独生成一个 Markdown 端点：site/src/pages/blog/[slug]/index.md.ts 为每篇博文生成/blog/<slug>/index.md，前置 YAML frontmatter（title、date、description、tags），并以Content-Type: text/markdown; charset=utf-8返回（见该文件 L41-L45）。该文件的头部注释明确写道"Used by LLMs and tooling that need blog content in a machine-readable format"，说明这套.md后缀端点正是为 LLM 与工具消费而设计的。TODO 描述的内容协商则是把它升级为"无后缀 URL 按 Accept 头自动判别"，前提是部署层能提供 edge/CDN 中间件来改写响应。

3.3x-markdown-tokens响应头

TODO 要求在 Markdown 端点上返回x-markdown-tokens响应头。当前 site/src/pages/blog/[slug]/index.md.ts 只设置了Content-Type，尚未加这个头。该头的作用是让客户端（尤其是抓取型 Agent 与代理工具）无需解析正文即可获知端点所服务的 Markdown token 数量（可依据reading-time库或分词结果计算），从而做出成本/长度判断。现有构建期已有一个reading-time相关插件 site/src/plugins/remark-reading-time.ts 会把阅读时长注入 frontmatter，这条 TODO 可以顺带把 token 统计一起落实。

3.4 Markdown 版站点地图（/blog/sitemap.md）

TODO 要求新增/blog/sitemap.md。这与仓库已有的llms.txt理念一脉相承——站点已有 site/src/pages/llms.txt.ts 与 site/src/pages/llms-full.txt.ts 两个面向 LLM 的聚合端点。/blog/sitemap.md将作为博客的纯文本索引，列出全部已发布博文及其链接，方便 Agent 一次抓取即获得博客全貌。实现上可复用 site/src/util/blog.ts 的getPublishedPosts()（生产环境自动排除draft标记的草稿帖，见该文件 L11-L13）。

3.5 Newsletter 订阅集成

TODO 记录博客尚缺 Newsletter 订阅入口。目前 site/src/pages/blog/index.astro 只使用BlogLayout渲染博客列表，没有任何订阅表单组件；仓库内也搜索不到 newsletter 相关组件或端点。这是纯粹的"待接入外部订阅服务"类任务，属于产品功能缺口而非技术债。

3.6 OG 图片自定义字体（当前为系统 sans-serif）

TODO 指出：博客 OG 图当前使用系统 sans-serif，而非站点品牌字体 Figtree。

证据在 site/src/pages/blog/og/[slug].png.ts：getImageOptions中字体配置为families: ['sans-serif']，其余参数包括深色渐变背景[[14, 14, 14]]、绿色侧边边框[0, 204, 95]、padding: 80等。要落实 TODO，需要在字体配置中引入 Figtree 字体文件并指定其 family，替换'sans-serif'。该端点基于astro-og-canvas构建，是全站og-image.png（site/public/og-image.png）之外按帖子动态生成的 OG 图。

3.7 作者头像（Schema 已支持，尚无图片数据）

TODO 指出：作者 Schema 已支持avatar字段，但尚未种入任何头像图片。

Schema 证据在 site/src/content.config.ts：

const authorSchema = z.object({ name: z.string(), role: z.string(), bio: z.string(), avatar: z.string().optional(), })

作者数据源 site/src/content/authors.yaml 目前只填写了id、name、role、bio四个字段（如 Galileo 工程师 Namrata Ghadi、AWS Principal Applied Scientist Alessandro Achille 等条目），均未配置avatar。前端渲染逻辑已经就绪：site/src/components/blog/BlogAuthorByline.astro 会在存在author.data.avatar时渲染<img class="author-avatar">，site/src/pages/blog/authors/[author].astro 的作者页也做了同样的条件渲染。因此该 TODO 落地时只需在authors.yaml中为各作者补充avatar图片 URL。

3.8 博文封面图（Schema 已支持，尚无数据）

与头像同理，TODO 指出博客 Schema 已支持coverImage字段但尚无任何封面数据。

Schema 证据在 site/src/content.config.ts 的blogSchema中：coverImage: z.string().optional()。前端渲染同样已就绪——博客卡片组件 site/src/components/blog/BlogCard.astro 在coverImage存在时渲染 180px 高的封面<img class="blog-card-cover">，博文详情布局 site/src/layouts/BlogPostLayout.astro 也在coverImage存在时渲染大图。当前 site/src/content/blog/ 下的 27 篇 MDX 博文均未声明coverImage（仓库搜索无该字段使用记录），因此卡片与详情页的封面区块处于"组件待命、数据为零"的状态。落地方式是在博文 frontmatter 中添加coverImage并配好图片资产。

3.9 博客页面视觉设计打磨

TODO 最后一条要求对博客页面做一轮视觉设计与打磨（polish pass）。这是主观性的设计任务，但结合上文可以看到具体的打磨抓手：封面图缺失导致 BlogCard.astro 的卡片始终是纯文本形态；头像缺失导致 BlogAuthorByline.astro 的署名区没有图片元素；OG 图字体与品牌不一致。换言之，3.6–3.8 三条数据与字体类 TODO 落地后，视觉打磨就有了明确的改造对象，可以围绕卡片封面、署名头像、详情页封面与 OG 图统一进行一轮视觉评审。

四、演进路线小结与跟进方式

将 CMS-TODO 的两部分合并观察，可以归纳出站点工程的三个持续方向：

对于希望参与维护的开发者，建议按"先数据后样式、先端点后协商"的顺序推进：先补齐authors.yaml的avatar与博文 frontmatter 的coverImage（3.7、3.8，纯数据变更即可激活已就绪的组件），再实现全内容 RSS 与x-markdown-tokens（3.1、3.3，可复用现有render-to-markdown与 reading-time 管线），最后处理构建链瘦身（2.1、2.2、2.4），并以tsc、vitest（site/vitest.config.ts）与博客相关测试（site/test/blog.test.ts）作为回归验证手段。每条 TODO 是否完成，都可以在对应代码路径上找到明确的判定标准。

<无法成文>该文档全文仅包含 3 行外部导航链接，缺少具体架构、配置细节与代码示例，无法独立支撑写成一篇完整的技术实战文章。</无法成文>

• 人工智能
• 大模型
• AI Agent
• Agent 框架
• 多智能体
• 工具调用
• MCP 服务