Almanac 应用程序构建完成后有什么作用？

Almanac 是一个本地托管的设计评审工具（类似于 Figma 评论），协作者可以打开网页，直接在 iframe 中渲染的 HTML 工件上放置锚定评论，并进行线程讨论。它支持反应、解决线程、实时在线状态（谁在查看）以及用于 AI 评审者的 API 通道。

该 Seed 使用什么技术栈构建？

它使用 Next.js 14 App Router 应用程序（React 18，TypeScript strict），NextAuth v4 进行身份验证，Vercel KV (@vercel/kv，兼容 Redis) 进行持久化存储，当 KV 环境变量不存在时，使用内存中的 Map 作为备用，Cheerio 用于服务器端 HTML 解析以实现代理功能，Playwright 用于端到端验证。

如何在本地安装和运行 Almanac？

通过提供的 curl 命令安装 Seed，然后按照 Seed 的“步骤”安装依赖项（包括通过 `npx playwright install --with-deps chromium` 安装 Playwright Chromium），生成 `.env.local` 密钥，确保存在 `cookoff-seeds/` HTML 语料库（Seed 可以创建一个示例），构建并在端口 3210 上运行服务器（`next dev -p 3210` / `next start -p 3210`）。

在没有 Google OAuth 的情况下，本地登录如何工作？

对于开发/验证，应用程序包含一个仅限开发的路由 `GET /api/test-login`，由 `ALMANAC_TEST_LOGIN=1` 控制。它为 `@plow.co` 电子邮件（默认为 `tester@plow.co`）生成一个有效的 NextAuth JWT 会话（使用 `NEXTAUTH_SECRET` 签名），并重定向到请求的页面。当该标志未设置时，路由返回 404。

如果我不想使用 Google SSO，如何保护公共部署？

当设置 `ALMANAC_ACCESS_PASSWORD` 时，Seed 会指定一个基于生产密码的 NextAuth Credentials 提供程序。登录需要密码和必需的显示名称（空白名称在客户端和服务器端都会被拒绝）。Google SSO 是可选的。

HTML 工件存储在哪里以及如何发现它们？

工件可以从 `cookoff-seeds/<projectDir>/<file>.html` 下的磁盘提供（通过 `/seed/<round>/<slug>` 自动发现为 Project → Option → Version v1），并且可以通过 `/seed-kv/<project>/<option>/<version>` 存储在 KV 中并提供额外的上传版本。

该 Seed 是否包含自动化验证套件？

是的。Seed 包含一个使用 Playwright 的“验证”过程，该过程针对在 `localhost:3210` 上运行的应用程序执行 27 个验收旅程，包括功能流程（图钉、回复、反应、解决、在线状态、版本切换、代理 API）以及通过计算样式/DOM 对规范的绝对设计值进行断言的视觉保真度检查。

两个访问“前门”和代理 API 是什么？

人类使用 NextAuth 会话（Google OAuth 可选；支持密码登录）。代理使用带有两个标头的标头门控 API：`x-vercel-protection-bypass`（必须与 `VERCEL_AUTOMATION_BYPASS_SECRET` 匹配）和 `x-almanac-agent-key`（必须与 `ALMANAC_AGENT_API_KEY` 匹配）。代理端点可以读取工件并写入/解决/删除代理编写的评论，这些评论与人类评论出现在相同的评论存储中。

Almanac Seed

WebsiteFreeAI Code Generator AI Developer Tools

Almanac Seed 是一个单文件 SEED.md 配方，它允许 AI 编码代理构建和自验证一个完整的 Next.js 14、Figma 风格的 HTML 设计评审应用程序，具有图钉锚定评论、线程讨论、反应、解决、实时存在以及用于 AI 评审员的标头门控 API。

访问网站

推广此工具

https://seeds.plow.co/seed/plow-pbc/almanac-seed?ref=producthunt&utm_source=aipure

概述
视频
替代方案

产品信息

更新于：2026年06月08日

什么是 Almanac Seed

Almanac Seed 是 Almanac 的一个独立“产品种子”，Almanac 是一个本地可托管的设计评审工具，用于直接在渲染的 HTML 工件上进行评论——类似于 Figma 基于图钉的评论，但适用于 Web 原型和单文件 HTML 探索。该存储库不提供应用程序代码，而是提供一个权威的规范文件 SEED.md，指导 AI 编码代理如何从头开始生成整个应用程序，包括路由、数据模型、UI 行为、安全规则和验收测试。生成的应用程序是一个 Next.js 14（App Router）项目，具有基于 NextAuth 的身份验证和 KV 支持的持久层，旨在完全在开发人员的机器上运行和验证，无需外部服务或生产凭据。

Almanac Seed 的主要功能

Almanac Seed 是一个单一文件的“SEED.md”配方，它指导 AI 编码代理从头开始构建完整的 Almanac Web 应用程序：一个 Next.js 14 设计评审工具，允许协作者直接在渲染的 HTML 工件上评论，支持图钉锚定线程（Figma 风格）、反应、解决状态和实时在线状态。该种子包括固定的数据模型、KV 模式、路由/API 契约（包括一个通过头部控制的代理 API）、UI/品牌要求，以及一个自动化验证套件（27 个验收旅程），该套件可以在本地运行，无需外部服务或生产实例，使用仅限开发的测试登录路径和可选的内存 KV 回退。

单一文件产品规范，可生成完整应用程序: 不附带应用程序代码——只有 SEED.md——因此 AI 代理可以仅根据规范生成完整的 Almanac 实现（Next.js 14 + TypeScript）。

在真实 HTML 工件上进行 Figma 风格的图钉评论: 评审人员在 iframe 中打开渲染的工件，并放置带编号、可拖动的图钉，进行线程讨论、链接化文本、反应以及解决/未解决行为。

内置验收验证（27 个旅程）: 包括一个端到端 Playwright 套件，通过针对规范的绝对设计令牌的计算样式/DOM 断言来验证功能流程和视觉保真度。

两种访问路径：人工会话 + 代理 API: 通过 NextAuth 会话支持人工评审，并为 AI 评审者提供一个独立的、通过双头部控制的 API 通道，以便读取工件并将评论写入同一存储。

本地 + 生产环境的便携式安全和身份验证: 使用中间件和 Next.js 头部（而非仅部署配置）进行框架/安全规则；提供一个仅限开发的测试登录路由，用于无需 Google 的验证，以及一个生产环境的密码登录选项。

KV 支持的协作与弹性开发回退: 将评论/在线状态/反应持久化到 Vercel KV (Upstash Redis) 中，使用固定的 Redis 键/类型模式，并在本地运行时缺少 KV 环境变量时提供内存 Map 回退。

Almanac Seed 的使用场景

HTML 原型的产品设计评审: 评审静态 HTML 模型的团队（登录页面、UI 探索、营销页面）可以直接在工件上使用图钉和线程反馈进行注释。

内部设计质量保证和利益相关者批准: 产品经理、工程师和利益相关者可以解决线程、进行反应并跟踪活动/在线状态，以协调批准，而无需将反馈转移到单独的文档中。

AI 辅助的 UX 评审和自动化评审: AI 代理可以获取工件和候选锚点，通过代理 API 发布结构化评论，并与人类一起参与相同的评审界面。

受监管环境下的私有、本地托管评审工具: 需要本地优先工具的组织可以在本地主机上运行应用程序，无需外部依赖（开发身份验证 + 内存 KV），随后可以部署并进行受控访问。

设计系统和视觉回归强制执行: 团队可以使用规范驱动的视觉断言来强制执行跨迭代的一致排版、大小写、布局密度和交互行为。

优点

自包含、可重现的构建：单个种子文件加上自动化验证，可以实现从头开始的一致生成。

强大的协作原语：锚定图钉、线程、反应、解决状态和在线状态，与熟悉的设计评审工作流相呼应。

对代理友好：专用的通过头部控制的端点允许 AI 评审者以编程方式读取和写入反馈。

缺点

复杂的规范表面积：严格的 KV 模式、身份验证规则和 UI 保真度要求增加了实现和维护的复杂性。

生产设置仍需要平台步骤：公开部署需要 Vercel 项目设置和 Upstash/Vercel KV 连接（以及密钥管理）。

领域特定默认值：该种子是为特定工作流（HTML 工件、Next.js、Vercel KV、NextAuth）量身定制的，可能不适用于所有技术栈，需要进行调整。

如何使用 Almanac Seed

1) 安装 Almanac Seed (Plow Seeds CLI 配方): 运行：\n\ncurl -fsSL https://raw.githubusercontent.com/plow-pbc/seed/main/install.sh | bash -s -- https://github.com/plow-pbc/almanac-seed/blob/main/SEED.md\n\n这将安装 Plow Seeds 工具并获取 Almanac SEED.md 配方。

2) 打开 SEED.md 并将其交给编码代理: 在您的编辑器或浏览器中打开原始 SEED.md，并将其粘贴到您的 AI 编码代理（例如 Claude Code）中，并附带说明：“水合此种子：构建它指定的应用程序，然后运行其 ## 步骤和 ## 验证，直到所有 27 个 §16 旅程通过。”\n\n注意：SEED.md 是一个完整的产品规范；它设计上不包含任何实现代码。

3) 决定是进行本地验证还是真实的公共部署: 本地构建/验证：您可以跳过第 0 步的部署面试，直接进入构建步骤（种子称之为“直接跳到 §13.5”）。\n\n公共部署：您必须先完成第 0 步（Vercel 登录 + Upstash 存储创建/连接），然后才能构建。

4) (仅限公共部署) 完成第 0 步面试先决条件: 在终端中，确保 Node 可用 (>= 18.17) 并且 Vercel CLI 已安装。如果 Vercel CLI 缺失，请使用用户可写前缀安装它：\n\nmkdir -p ~/.npm-global && npm config set prefix ~/.npm-global\nexport PATH="$HOME/.npm-global/bin:$PATH"\nnpm i -g vercel\n\n然后进行身份验证：\n\nvercel login\n\n现在创建/链接 Vercel 项目（团队与个人范围不同）：\n- 团队：vercel link --yes --project <your-almanac> --scope <your-team>\n- 个人：vercel link --yes --project <your-almanac>\n\n在 Vercel 仪表板中，创建并连接一个用于 Redis 的 Upstash 数据库到此项目（存储 → 创建数据库 → 用于 Redis 的 Upstash → 连接项目 → 所有环境）。

5) (仅限公共部署) 设置生产密钥（代理生成的密码）: 生成并设置密钥（种子指定代理应生成密码；用户不选择它）：\n\nPASSPHRASE="$(openssl rand -base64 18)"\nprintf '%s' "$(openssl rand -base64 32)" | vercel env add NEXTAUTH_SECRET production\nprintf '%s' "$PASSPHRASE" | vercel env add ALMANAC_ACCESS_PASSWORD production\n\n请勿在生产环境中设置 ALMANAC_TEST_LOGIN。

6) 在本地运行种子的构建步骤（种子的 §13.5 “步骤”）: 按照 SEED.md §13.5 步骤水合/构建应用程序。总而言之，种子指示代理：\n- 确保 Node >= 18.17\n- 安装 npm 依赖项 (npm install)\n- 确保存在 cookoff-seeds/ 语料库（如果缺失，种子会创建一个示例）\n- 安装 Playwright Chromium + OS 依赖项：\n npx playwright install --with-deps chromium\n- 为本地开发创建 .env.local（包括 NEXTAUTH_SECRET、NEXTAUTH_URL=http://localhost:3210、ALMANAC_TEST_LOGIN=1 和开发代理密钥）\n- 在端口 3210 上构建并运行 (npm run build; npm start -p 3210 或等效命令)

7) 在端口 3210 上启动应用程序并确认其响应: 运行服务器并确认 /login 加载：\n\nnpm run build\nnpm start\n\n然后检查：\n\ncurl -sI http://localhost:3210/login\n\n预期 HTTP 200。

8) 在本地使用仅限开发的测试登录路由登录，无需 Google: 在 .env.local 中设置 ALMANAC_TEST_LOGIN=1 后，打开：\n\nhttp://localhost:3210/api/[email protected]&next=/\n\n这将生成一个 NextAuth 会话 cookie 并将您重定向到应用程序（本地验证无需 Google OAuth）。

9) 运行种子的验证套件（种子的 §15 “验证” / §16 旅程）: 运行 Playwright E2E 套件：\n\nnpm run e2e\n\n种子的验收标准是 §16 中的 27 个旅程（功能 + 视觉计算样式断言）。所有这些都必须通过 localhost:3210 的测试。

10) (可选) 使用提供的 Docker stranger-test 脚本: 如果您想要完全隔离的“空白容器”验证，请运行存储库的验证脚本（需要 Docker 和配置好的 claude CLI）：\n\nverify/hydrate-and-verify.sh\n\n它会在 node:20-slim 容器中自动执行陌生人流程并打印 FINAL_VERIFY 结果。

11) (仅限公共部署) 部署到 Vercel（种子的 §13.6 “部署”）: 在完成第 0 步并且您的应用程序在本地构建后，部署：\n\nvercel deploy --prod\n\n然后通过 API 或仪表板禁用 Vercel 部署保护 (ssoProtection)（必需，以便可以访问 /login）。将 NEXTAUTH_URL 设置为已部署的 URL 并重新部署一次：\n\nprintf '%s' "https://<project>.vercel.app" | vercel env add NEXTAUTH_URL production\nvercel deploy --prod

12) (仅限公共部署) 使用生成的密码共享访问权限: 您部署的 Almanac 使用密码登录（凭据提供程序）。评审员使用任何显示名称 + 生成的 ALMANAC_ACCESS_PASSWORD 密码登录。确认评论在重新加载后仍然存在（证明 Upstash KV 已连接）。