Ryan Lindsey

ryanlindsey.me

ryanlindsey.me 背后的代码：一个运行在 Cloudflare 开发者平台上的 Astro 网站，以及一个在 mcp.ryanlindsey.me 提供远程 MCP 服务的第二个 Worker。一个代码库，两个已部署的 Worker，共用一组 D1、KV、R2、Queues 和 Analytics Engine 资源。

这个网站的构建方式，让人与 Agent 能通过不同入口读取同一内容库。

源码可见，方便你了解它的构建方式。这里没有 LICENSE 文件，而且这是有意为之，并非疏忽：没有许可证就意味着保留所有权利，因此这里的内容均未获准复用。

部署由 Workers Builds 从 main 执行，CI 中没有部署步骤。CLAUDE.md 记录了工作笔记，包括命令、编辑前值得了解的陷阱，以及那些看起来奇怪的部分背后的原因。

如果你是 Agent

四个入口点，按约定保持稳定：

入口	说明
/llms.txt	精选索引，也是起点
/.well-known/ard.json	ARD 清单，也以 ai-catalog.json 提供
/.well-known/mcp/server-card.json	服务卡片，在两个源站上均可访问
https://mcp.ryanlindsey.me/mcp	协议端点本身

此文件没有列出其余内容，而这个省略之处才值得一读。此网站公布的每个端点都位于一个列表中：src/lib/discovery/surface.ts 里的 ADVERTISED_SURFACE。该列表同时发布为 API 目录和 ARD 清单，并由 tests/discovery-catalog.test.ts 检查。这里再列一张表，就会在测试套件之外形成第二份副本；只要端点发生变动，它就会过时。请获取目录，而不要轻信此文件。

有一项内容是有意不列在该列表中的。根据要求，/fit 及其下的所有内容都未列出；目录是作者认为值得关注的路径的公开列表，因此把它列进去就会违背不公开的要求。

整体架构

flowchart TB
  person(["person"])
  agent(["agent"])

  subgraph site["site Worker (ryanlindsey.me)"]
    S["pages, posts, case studies, résumé<br>markdown variants, llms.txt, feeds<br>well-known catalogs<br>chat page and the form surfaces"]
  end

  subgraph mcpw["MCP Worker (mcp.ryanlindsey.me)"]
    G{"grant resolved<br>here, and only here"}
    T["/mcp, the chat stream,<br>the fit engine"]
    R[["rate limiter<br>Durable Object"]]
    G --> T
    T -->|every tool call spends budget| R
  end

  P[("R2_PRIVATE")]

  person --> site
  agent --> site
  agent --> mcpw
  site -->|service binding| mcpw
  mcpw -->|reads published documents| site
  T -. "private-docs.ts, the only reader" .-> P

拆分为两个 Worker 并非表面上的安排。网站配置中的 ai 绑定会让 astro build 打开远程代理会话，而无凭据的 CI 无法通过身份验证，因此推理任务由第二个 Worker 承担，网站则通过服务绑定访问它。每个 Worker 都会指定另一个 Worker；这种循环是有意为之且合法的，因为服务绑定是在调用时解析，而不是在定义 Worker 时解析。

这张图有意省略了部分内容。它呈现了整体结构，但没有展示其余细节：每个 Worker 会访问哪些存储、会调用哪些模型、队列消费者以及定时任务。网站会在 /ops 发布一张自己的图，展示已部署资源清单；这张图以仓库中唯一的架构描述 src/lib/architecture.ts 为依据。该页面还会报告系统近期的运行情况和成本，这些数据在请求时读取，而不是在此处宣称。

此仓库的保证

四项声明，每项都由对应文件证明，而非仅凭承诺。

声明	强制执行依据
私有层是一个分区，而非筛选器。公共文档层的环境变量接口完全没有提及私有存储桶。	tests/tier-private-docs.test.ts，在类型层面
未经身份验证的 tools/list 无法枚举受限工具名称，按名称调用此类工具时会返回 unknown-tool，而不是确认其存在后再拒绝调用。	tests/mcp-gated.test.ts，“invisibility without a grant”
没有测试会访问 Workers AI、Vectorize、Browser Rendering 或真实密钥。已部署配置均未声明这些覆盖变量，且遇到无法识别的值时会抛出异常。	tests/workers.ts 在一处设置这些变量，tests/mcp-env.test.ts 确保它们不会出现在任何已部署配置中；遇到无法识别的值时，会像 src/lib/turnstile.ts 那样在调用处抛出异常
MCP Worker 的绑定列表不会与其 wrangler 配置出现任何方向的偏差。	tests/mcp-env.test.ts

五分钟了解此代码库

按阅读顺序查看四个文件，即可了解其余内容。

1. src/lib/discovery/surface.ts，此站点公布的所有端点都在一个列表中，其中说明了为何只用一个列表，而不是两个。
2. src/lib/tier/grant.ts，唯一验证令牌的地方。站点 Worker 不保存令牌副本：它将令牌视为不透明字符串，并通过服务绑定发起询问，因此边界只需一种实现，而非两种相互配合的实现。
3. tests/workers.ts，了解测试套件为何会在 workerd 中启动真实 Worker，以及它拒绝访问哪些内容。
4. src/components/ArchitectureDiagram.astro，重点看它的头部，而非输出。头部记录了其初稿中的两项错误声明，指出具体内容，并说明这些错误带来的教训。这是了解本仓库其他注释风格的一个范例。

发布

release-please 会监视 main，并保持一个发布拉取请求处于开启状态，其中包含下一个版本及其变更日志。合并该拉取请求后，会为此发布打标签并进行发布。

拉取请求会以 squash 方式合并，因此拉取请求标题就是 release-please 读取的提交主题。没有可识别的 type(scope): summary 前缀的标题会被静默跳过：不会升级版本，也不会添加变更日志条目。feat 会升级次版本号，fix 和 perf 会升级修订版本号，type!: 或 BREAKING CHANGE: 页脚会升级主版本号。完整的类型列表位于 release-please-config.json 的 changelog-sections 下。