0003 · 网站工程基础
英文版本 为准，本文供参考。
状态：本地验证及最终验收审查通过；待所有者手动 review。 基线：ee17e58；分支：feat/website-foundation；同级 worktree：../website-foundation。尚无远程仓库或 PR。
当前审查选择： 用户要求后续只保留最终验收审查，执行审查豁免。已完成的需求/计划审查仅适用于其记录范围。最终审查检查正确性、第一性原理简化、测试/文档价值和隐私；交付供用户手动 review，提交前仍须预览并确认。
**当前文档交付：**长期指南与公开 PR log 保持双语；每次必写的验收手册仅中文、本地保留并忽略。下方 P1 计划保留原审查范围，执行与验收章节说明实际交付结构。
需求
目标是可运行、易维护的工程基础；本次不包括最终视觉设计、真实简介/项目/经历、博客整合或生产发布。
| ID | 验收需求 |
|---|---|
| F01 | 以 Astro、TypeScript、pnpm 构建静态个人站，提供英文 /、中文 /zh/、翻译导航、语言切换、Projects 列表/详情、Experience 和有用的 404。不设 Research Tab，不需要请求时运行应用服务器。提供克制的响应式基础界面，最终视觉及复杂动画另行开展。 |
| F02 | 项目和经历通过 Markdown 及元数据校验管理，新增条目无需修改页面组件。发布条目须有对应翻译；元数据错误、不安全/重复路由及发布状态不一致须使检查失败。草稿不得进入生产路由、索引或生成的公开内容。只用明确标注的中性示例，不虚构个人成果。 |
| F03 | 用 Hugo/OINK 构建独立静态公开日志站，具有中英文导航、可用搜索，每项变更一篇完整文章。复用仓库日志来源；生成页面中的文章、指南及语言链接须有效，不维护重复可编辑内容。已有记录及本变更均可浏览。 |
| F04 | 从官方来源核实直接依赖和工具的最新稳定版，固定精确版本，提交生成的锁文件，CI 冻结安装。在本文记录版本/日期/来源；Git 依赖和 CI Actions 固定到发布版本对应的完整 commit SHA。兼容性例外询问用户，不擅自选旧版。 |
| F05 | 包含有效的内容正反自动测试、生成路由/草稿检查，以及语言导航和响应式无障碍基础的浏览器覆盖。类型检查与两站生产构建须通过。记录实际命令/结果，区分本地验证与待运行的托管检查。 |
| F06 | 提供简单 CI/CD：PR 合并前检查，合并后重新检查 main，通过后仅从 main 自动部署已检查产物。PR 任务不接触部署密钥。生产上传串行，上传前立即拒绝过时重跑，不取消已开始的上传。两站无法原子部署，须报告部分失败。 |
| F07 | 准备两份 Cloudflare Workers Static Assets 配置及部署说明。本次不发布、不创建远程资源、不改 DNS、不替换线上网站、不虚构仓库/PR 信息。未来通过远程规则强制 PR 集成和必需检查；仅 workflow 文件无法实施这些限制。 |
| F08 | 按交付结果更新简洁双语 README、协作/流程指南、内容说明和验收步骤。保留 Apache-2.0 与第三方归属声明；仓库引用使用相对路径，公开内容/证据不包含隐私数据、密钥、工作站路径或原始会话。 |
已确定的用户决策：仅工程基础、四轮审查、pnpm、英文为主/中文参考、独立公开 OINK 站、Cloudflare 静态托管、检查通过后经 PR 集成并自动部署。外部账号/仓库/域名设置须在生产启用前完成。
需求审查
2026-09-13 — foundation_requirements_review：通过，无阻断项。范围为两种语言的 R1 概要授权及需求章节，至本审查标题之前；确认工程基础范围可验收、复杂度适当、隐私要求明确。本结论仅允许进入计划。
计划与决策
- 工具与命令。 添加精确版本的依赖清单/锁文件、Node/Go/Hugo 版本文件、pnpm 精确保存设置及生成产物/工具缓存忽略规则。应用放
src/，一个 package 管理个人站、测试与部署 CLI。单元测试使用 Node 内置 runner，浏览器测试使用 Playwright；安装固定版本的本地工具，不更改全局工具版本。 - 内容与路由。 使用 Astro 内置 Markdown collections 及 Zod 元数据 schema，loader ID 来自唯一文件路径。共享的小型内容校验器在筛选发布条目前检查安全 slug、重复路由、必需翻译对及草稿状态一致性。由共享组件生成本地化静态路由，界面文案集中在有类型字典中。提供明确标注的项目/经历示例对，以及用于证明排除行为的无敏感草稿对。使用语义 HTML、可见键盘焦点、响应式 CSS 和减少动态效果支持；本基础无需 React、MUI、Three.js 或 MDX 插件。
- OINK 日志。 Hugo 站放
log-site/，固定 OINK 发布 commit；将仓库logs/、docs/及根协作文档挂载到内容树，保留相对路径关系。只添加必要的双语首页/分区页；必要时用小型 Markdown 链接 hook 将源码.md/.zh.md链接解析为已生成译文页面，无法解析仓库引用时使构建失败。启用 OINK 本地搜索，减少无用输出/功能。日志输出dist/logs/，Astro 输出dist/portfolio/；保留主题归属及自带第三方声明。 - 检查。 单元测试覆盖有效内容、不安全 slug、重复翻译/路由键、缺失翻译、草稿状态不一致，以及部署决策（当前 main、旧任务重跑、API 失败、上传失败）。运行类型检查、两站生产构建及产物检查，证明 EN/ZH 预期路由存在、公开产物无草稿哨兵内容。浏览器覆盖桌面/窄屏、键盘导航/焦点、对应页面语言切换、404、本地链接和 OINK 搜索结果，并检查减少动态效果行为。增加一次真实错误内容构建检查，证明校验已接入构建；两份 Wrangler 配置只进行本地 dry run。
- CI/CD。 一个 GitHub workflow 包含
checks和deploy；PR 和 main push 均运行冻结安装、检查/测试及两站构建，成功的 main 任务上传同一份已测静态产物供部署使用。部署要求一次性外部配置、main push、检查成功和 production environment。Actions 固定 SHA，仓库权限只读，Cloudflare 密钥仅给部署步骤。生产 concurrency group 串行且不取消运行中发布；锁内、两站上传开始前重新读取 main 最新 commit，跳过过时任务，验证出错则停止。开始发布后按序完成上传，不主动取消；上传失败使发布失败，并报告已发布站点。无需额外发布服务即可防止旧重跑覆盖新版。 - 部署配置与指南。 两份纯静态 Wrangler 配置均设置自定义 404，不引入 Worker handler/adapter。提供简洁双语内容指南、部署/设置指南和验收手册。外部设置须填写真实仓库/Worker 名、HTTPS 站点地址、凭据及 PR/检查规则；明确配置前保持生产未启用。本次不写账号 ID、密钥或猜测域名，不创建远程或上线；说明如何检查外部强制规则，以及通过获授权 PR 有意回滚到已知可用版本，不重跑过时流水线来回滚。
- 收尾。 执行审查通过后写实际验收结果，再按手册/证据进行验收审查；更新 README/AGENTS 的工程基础状态，历史日志保留其当时状态并关联本变更。仅暂存预期源码/配置/文档/锁文件，检查完整差异，展示完整提交预览并等待确认。
简化选择： Astro collections 与静态渲染满足内容管理，无需 CMS/后端；普通 CSS 和共享本地化组件足够完成基础。Hugo 用于用户指定的 OINK，挂载机制避免内容同步服务；Node 内置 runner 避免额外单测框架。单一 CI workflow 加小型可测试部署命令，无需单独发布编排系统；生成文件和本地工具缓存忽略。
兼容性决策： 用户允许 TypeScript 固定为最新稳定 6.x 版本 6.0.3，因为最新 @astrojs/check 声明支持 TypeScript 5/6，而最新 TypeScript 为 7.0.2。其他选定直接依赖/工具仍用最新稳定版；该例外仅适用于 TypeScript。
已核实版本
2026-09-13 从官方 registry/发布元数据核实，安装时再检查兼容性。依赖清单使用精确版本，生成的锁文件固定传递解析。
| 依赖/工具 | 选定版本 | 官方来源 |
|---|---|---|
| Astro | 7.3.2 | Registry |
| Astro check | 0.9.10 | Registry |
| TypeScript | 6.0.3，用户批准的兼容例外 | Registry |
| Playwright | 1.63.0 | Registry |
| pnpm | 12.4.1 | Registry |
| Wrangler | 4.131.1 | Registry |
| Node.js | 26.8.2，稳定 Current 版本 | 发布列表 |
| Hugo Extended | 0.166.0 | 发布版本 |
| Go | 1.27.1 | 发布列表 |
| OINK | v1.0.0，commit 56583633c4aae4ac7650e9115629bf349728ba90 | 发布源码 |
GitHub Actions 使用以下已核实的不可变发布 commit，workflow 不使用浮动 tag：
| Action | 版本 | Commit |
|---|---|---|
| actions/checkout | v7.0.1 | 3d3c42e5aac5ba805825da76410c181273ba90b1 |
| actions/setup-node | v7.0.0 | 820762786026740c76f36085b0efc47a31fe5020 |
| actions/upload-artifact | v7.0.1 | 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a |
| actions/download-artifact | v8.0.1 | 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c |
| actions/setup-go | v7.0.0 | b7ad1dad31e06c5925ef5d2fc7ad053ef454303e |
| pnpm/action-setup | v6.1.0 | ea17c68df8912ef543352723c149a84f56e3d413 |
计划审查
2026-09-13 — foundation_plan_review：通过，无阻断项。范围为 EN/ZH 的 P1 计划及两份版本表，不含本报告，并对照 R1 检查；确认架构适当、检查具体、部署保护及 TypeScript 特定例外。版本元数据按文档核查，未独立重新请求 registry。本结论允许 R1 范围内实现，不授权提交/发布。
执行
已交付静态 Astro 个人站、独立 Hugo/OINK 日志站、双语 Markdown 示例、固定工具/依赖版本、测试及一份 GitHub CI/CD workflow。日志站通过 Hugo mount 直接读取仓库文档，无需重复维护日志源或运行应用服务器。OINK 从已记录的发布 commit 解析为标准 Go 模块版本，内容由 log-site/go.sum 固定。
发布命令上传已验证产物，在生产并发锁内核实当前 main 版本，并报告两站的部分发布失败。外部设置就绪前保持禁用部署。README 及开发、内容、部署、流程指南说明实际命令与交付边界。每次变更在被忽略的 .local/acceptance/ 放仅中文的本地清单，位于公开 Hugo mount 之外；公开 EN/ZH 日志保留简明证据及长期迁移操作。
执行审查：所有者已豁免。 剩余仅执行最终验收审查。构建产物、工具缓存和浏览器产物均被忽略；未更改远程资源或线上网站。
验收
2026-09-13 的本地检查，范围为基于 ee17e58、尚未提交的 feat/website-foundation 工作树。按开发指南
复现。
| 检查 | 实际结果 |
|---|---|
pnpm install --frozen-lockfile | 通过；pnpm lockfile 和 Go 模块文件未改变。 |
pnpm verify | 通过：Astro check 为 0 error/warning/hint；19 项单元测试；两站静态构建；4 项产物测试；桌面/移动端共 10 项浏览器测试；真实内容构建夹具。 |
| Markdown 编写与验证 | 新增双语内容对无需修改组件即可生成页面；草稿不输出；缺少译文及不安全 slug 均使真实构建失败。单元测试另覆盖重复路由/键及不一致的草稿状态。 |
| 构建产物与浏览器行为 | 个人站 9 页；日志站包含全部三篇变更记录的两种语言。个人站所有产物均无草稿哨兵。检查生成 HTML 的本地链接，包括压缩后未加引号的属性。浏览器检查覆盖 EN/ZH 项目对应、移动端溢出、键盘焦点、减少动效、404，以及实际英文/中文 OINK 搜索结果。 |
pnpm deploy:dry-run | 两份纯静态资源 Wrangler 配置均通过，未发布。pnpm run deploy 正确进入 main push 保护，在本地调用时拒绝执行，未上传。部署决策测试覆盖过期/当前版本、版本核验错误和上传失败。 |
| 开发文档 | 在隔离目录验证精确 pnpm 安装命令，安装后输出 12.4.1。长期 EN/ZH 指南覆盖环境设置、启动/停止和检查；每次变更的中文清单仅本地保留并被忽略。 |
| 本地/公开分离 | git check-ignore 确认中文清单被忽略，git ls-files 不含本地清单；其相对链接有效，公开构建不含其内容，指南移动后 4 项产物测试全部通过。 |
| 验收与迁移约定 | 每次变更必需仅中文的本地清单，写明有序验证、预期结果及迁移/恢复，或无需迁移及原因。README、AGENTS 和流程要求豁免审查也不能省略；持久证据及重要迁移操作仍保留在公开双语日志。 |
| 源码检查 | 直接依赖版本及 Action 发布 SHA 已固定；公开源码使用仓库相对引用，不含本机路径或凭据。标准 main 保持干净；构建产物/缓存不纳入版本控制。 |
**从 ee17e58 迁移：**仅文档基线没有应用数据库或内容存储。先记录既有工具版本，再选择固定工具、安装依赖/Hugo，运行上述检查并验证双语及既有日志。无需既有数据或线上迁移；0001/0002 保留原路径，由 OINK mount。若本地检查失败，停止服务、保留未提交工作，按需切回记录的旧工具；标准 main 和线上网站不变。生产启用另行进行。通用设置/检查见 docs/development.zh.md，公开证据无需依赖临时清单。
待外部验收： GitHub Actions 实际运行、必需检查/PR 规则、Cloudflare 上传、路由、DNS 及线上 URL 需要获授权的远程设置。本地测试不代表这些项目通过。两站顺序发布，不具备原子性。最终视觉设计与真实个人内容不属于本次工程基础。尚未 commit、push 或部署；待所有者手动 review 及提交确认。
验收审查
2026-09-13 — foundation_acceptance_review：通过，无剩余阻断项。范围为基于 ee17e58 的未提交工程基础，包括 EN/ZH 文档、Astro/OINK 源码、版本固定、测试、CI/CD 及最终日志表格样式，不含本报告。F01–F08 在获授权的本地工程基础范围内满足。审查覆盖正确性、第一性原理下的简洁性、测试/文档价值和隐私；独立重跑 19 项单元及 4 项产物测试，并验证部署命令的安全保护。完整构建/浏览器/dry run 结果依据执行证据评估。远程规则/发布与所有者手动 review 仍待完成；本通过不授权 commit 或部署。验收审查也核实了最终文档分工：每次必需的仅中文忽略清单、长期 EN/ZH 指南/公开证据、本地链接、Hugo 排除、迁移/恢复步骤及 worktree 文件生命周期。应用代码及依赖版本未改变。