feat: 自建 VitePress 文档站（harness.dyu.sh）— 文件系统生成导航 + C14 守卫 - #22
Merged
Conversation
裸写的 <best_action_index> 与 <original>/<patched> 标签会被 Vue 编译器 当作组件解析（VitePress 构建直接报错），在 GitHub 的 Markdown 渲染中 也会被 HTML 清洗吞掉。以反引号内联代码转义后两边渲染都恢复正确。 Taken from PR #21 with authorship preserved.
…ness.dyu.sh 站点自建而非合并 PR #21，但吸收其验证过的方案与多个设计想法（VitePress 选型、works 按来源系列分组的信息架构、中文排版细节、部署工作流骨架、 首页六概念卡结构）。 与 #21 的关键差异： - 侧边栏与首页统计不手写：.vitepress/sidebar.mjs 在构建时从文件系统生成， 未匹配到分组前缀的新作品落入「社区博客」兜底组——宁可分组不准， 不可静默丢失 - 自有域名 harness.dyu.sh：base=/、public/CNAME、sitemap/OG/canonical 全量对齐 - 智能体可读：每页伴生同路径 .md 副本 + /llms.txt + /llms-full.txt（Node 标准库实现，零运行时依赖） - /feed.xml RSS 2.0，条目时间取自 git 提交历史 - 自有视觉：缰绳青主题 + 缰绳曲线 favicon（与仓库自产海报同一视觉 DNA） - 部署工作流用 npm ci + Node 22，构建前先跑 sidebar --verify Design informed by #21. Suggested-by: Doraemon <159792165+Doraemonblogs@users.noreply.github.com>
手写侧边栏是 C1–C13 覆盖不到的漂移面。C14 守两条不变量： - 站点源码（index.md、.vitepress/）不得出现裸计数（"N 篇"）， 数字只能来自 computeStats() 的构建时统计 - 每个一等内容文件必须在生成的侧边栏中恰好出现一次 （node .vitepress/sidebar.mjs --verify） 站点脚手架不存在时 SKIP；node 不可用时 verify 半边 SKIP、裸计数 grep 照常执行。同步 AGENTS.md 检查清单说明与两份 README 的在线阅读徽章。
上一版视觉与仓库既有品牌资产脱节（无来历的 teal，默认模板感）。本版按 baoyu-design（Claude Design 引擎，upstream HEAD 2026-07-29）方法论重做， 设计语境直接取自仓库自产海报（works/harness-engineering-intro-deck）： - 配色：暖纸底 #F5F1E8 × 深墨 #1F1C17 × 缰绳橙红 #C2481D（唯一强调色）， 明暗两套 token 映射到 VitePress 主题变量 - 字体：标题用宋体系衬线（Noto Serif SC，unicode-range 切片按需加载， 不可达时回退系统宋体），正文保持无衬线 + 1.85 行高 - 首页重写为 HomeArchive.vue：口号做主标题、缰绳曲线 + 「驭缰」印章、 「档案总目」统计带（数字仍来自构建时统计，C14 约束不变）、 编号档案卡网格、导览索引；入场动效尊重 prefers-reduced-motion - 文档页重皮：衬线标题 + 橙红题标、纸色侧边栏 / 引用块 / 表格、 低调纸张颗粒质感 - favicon 与 README 在线阅读徽章同步新视觉
结构与叙事吸收自用户以 Claude Design 产出的探索稿（2026-08-14）： - 语义化缰绳图：从装饰升级为带节点标注的方法论路径 （人类·设计约束 → AGENTS.md → 自定义 linter → CI 反馈回路 → 智能体·如约交付） - § 卷宗分节：01 一句话理解 / 02 六大核心概念 / 03 档案总目 / 04 仓库即 harness·自我指涉 / 05 从哪里开始，配英文微标签 - § 01 范式转变对照（传统工程 vs HARNESS ENG. 约束链） - § 03 台账式总目（路径小注 + 右对齐大号衬线数字） - § 04 通栏暗色自指章节：人类闸门 / 机械护栏 / 反馈回路 + 驭缰印章 - § 05 五阶段阅读路线，对应仓库 Phase 1–5 学习路线 与探索稿的差异（守住 C14 纪律与事实核查）： - 稿内硬编码计数（74/34/C1–C13）全部改回构建时动态统计， computeStats 新增 feedback 字段；C 检查数在文案中同样动态渲染 - Ralph Demo 的 321 秒 / $0.31 已对照 practice/ 核实为真实数据
吸收自用户以 Claude Design 产出的文档页探索稿（concepts/06 重绘）： - 文档页头：档案面包屑（档案 · 概念 · CONCEPTS · 06）+ 构建时估算的 阅读时长 + 最近更新（git 时间），经 doc-before 插槽注入（DocMeta.vue） - 小节自动编号：h2 上方细线 + 橙色 01/02 编号，由 CSS 计数器机械生成， 源文件零改动 - 侧边栏档案化：分组头「中文名 + EN 微标签 + 右对齐计数徽标」，编号 文件名显示条目编号（00–07）——由 sidebar.mjs 构建时注入展示装饰， collectPages/llms.txt/RSS 拿到的仍是干净文本 - 右栏 outline 下缰绳 doodle（Agent = Model + Harness，AsideMark.vue） - 导航精简：概念 / 思考 / 实践 / 作品 / 资料库；站名改「驭缰工程」 - 引用盒全边框、橙色列表符、衬线翻页卡；资料库条目改「文章深度摘要」 （计数上移到分组徽标） 计数纪律不变：徽标数字与阅读时长均为构建时计算，C1–C14 全绿。
阻断项： - gitDate 改 execFileSync 参数数组 + '--' 分隔，消除构建期命令注入 - sidebar.mjs 全面拒绝 symlink（isFile/lstat/realpath 越界防御）， buildEnd 所有文件读取/复制经 assertContentFile - 新增发布页面全集模型 collectPublishedPages：66 页全部获得同路径 .md 副本（含首页 /index.md、PROMPT、poster/style），llms.txt 增附属页面 节，llms-full.txt 收齐全文；新增 scripts/verify-dist.mjs 在构建后 机械断言 html↔md 一一对应并接入 CI（也堵住本地 output/ 目录泄露） 次级项： - CI 最小权限：顶层 contents:read，build 只加 pages:read （configure-pages 必需），pages/id-token 写权限仅 deploy job； 删除 enablement:true 与误导注释 - 死链检查重新开启：构建期把指向未发布目标的相对链接改写为 GitHub blob/tree 链接（仅限 git 已跟踪目标），目录若有已发布 README 则路由 站内页 - works/ 子目录作品改走同一套分组匹配，「社区博客」兜底真正生效 - pre-commit 触发范围扩至 index.md、.vitepress/、works/imgs/ 与嵌套 内容目录，补收尾锚点并加 --no-renames - README×2 更新为十四层校验（C1–C14）并补 C14 条目；favicon 移除损坏 注释（xmllint 通过）
P1·安全边界： - 全仓禁止 symlink，四层防线——sidebar.mjs findForbiddenSymlinks() （lstat 遍历，悬空/嵌套目录软链均拦）、--verify 纳入 C14、config.ts 加载即拒绝（dev 与 build 同判）、verify-dist 扫 dist 产物。Vite 会 解引用 public/ 软链、图片管线会读链接目标，故一律 fail-closed P2·首页机器可读： - 首页文案抽出为 theme/home-copy.mjs 唯一事实源，HomeArchive.vue 与 buildEnd 共同消费；/index.md 副本改为生成的完整 Markdown（五个分节 + 台账 + 阅读路线，站内链接为绝对 URL），llms-full.txt 收录首页正文， HOME_TITLE 统一副本 frontmatter 与 llms-full 条目标题 P2·副本自足： - 新增 sidebar.mjs mapMarkdownLinks：行级围栏状态机（含 4+ 反引号嵌套 围栏）、行内代码保护、徽章嵌套两遍匹配、引用式定义、单双引号标题—— 构建期改写（config.ts transformCopy）与产物校验（verify-dist）共用 同一套解析，改写什么就校验什么 - 副本内图片→raw.githubusercontent、未发布资产→GitHub blob/tree、 目录→站内 README.md 副本；verify-dist 同时校验相对链接与站内绝对 链接可达（含生成式首页副本的全部链接），目标必须是 dist 内普通文件 P2·CI 缺口： - 新增 docs-build.yml：PR 上跑完整构建（死链检查随构建）+ 侧栏校验 + 产物契约，contents:read 只读、带并发取消组；构建回归不再等合并后发现 P3： - llms-full 元数据块标题 JSON.stringify（Task: 冒号标题不再是非法 YAML）， 首页条目无 frontmatter 正文，消除双定界块歧义 - C14 裸计数扫描扩至整个 .vitepress/（--exclude-dir=dist/cache/.temp）， 与 AGENTS.md 约定范围一致
Standards： - P1 symlink 禁令绕过：findForbiddenSymlinks 豁免从「按目录名任意层级」 收窄为仓库根精确路径（.git、node_modules、.vitepress 构建目录）—— public/node_modules/ 里的软链不再有死角，实测被 verify/config 门闩双拦 - AGENTS.md C14 同步为三条不变量（补全仓禁 symlink + verify-dist 产物侧） - pre-commit：staged symlink（mode 120000）无条件触发检查，且 diff-filter 补 T——删普通文件后原地换软链是 typechange，ACMR/ACMRD 都看不见 Spec： - 改写器与校验器解析路径分离：verify-dist 改用 VitePress 自带渲染器的 AST 提取链接（生产同款解析器），不再与 mapMarkdownLinks 正则共享盲区； 对拍基线 171/171（修复行内代码占位实现顺带补齐了链接文本含行内代码、 尖括号目标、平衡括号目标三类形态） - 首页人机同源补全：CTA 三按钮与缰绳图七段文字入 home-copy.mjs， Vue 与 /index.md、llms-full 首页条目同源 - 对外 URL 全部路径段编码（llms.txt / llms-full url / RSS link+guid / og:url / 副本改写），RSS link/guid 补 XML 转义，括号类 sub-delims 强制 编码；verify-dist 按段 decodeURIComponent 与编码出口构成逆运算； 发布文件名含 '#'/'?' 被 C14 verify 机械禁止（VitePress 对其 fail-open） - rel 路径统一 '/' 拼接，Windows 反斜杠不再破坏排除规则
[P1] llms-full.txt 是无所在目录的合并文档，复用同路径副本的相对链接
全数失效（68/71 断）。现改用 absolute 模式重新改写：已发布页相对
链接 → 各页 .md 副本绝对 URL，根相对路由补 host；verify-dist 新增
llms-full 校验——不允许任何相对链接，站内绝对链接逐一在 dist 验证
[P2]
- llms-full 条目剥离源 frontmatter，消除生成元数据块后紧跟第二个 ---
定界块的解析歧义（此前只对首页条目处理过，译文页同样存在）
- 引用式定义按目标扩展名判定图片：![alt][img] 的定义不再被改写成
GitHub blob 页面地址，而是 raw 图片地址
- 裸 HTML 标签（<img src>/<a href>）进入校验面：改写器看不见它们，
校验器现在扫 html_inline/html_block token，两侧不再同盲
- query string 与文件路径分离解析（classifyLink 与 verify-dist 一致），
articles.md?x=1#s 不再被拼成 articles.md?x=1.html 误判
- pre-commit 对 staged symlink 从「触发全量检查」改为「按暂存区状态
直接拒绝」——工作树可在 stage 后换回普通文件（TOCTOU），暂存区状态
才是将被提交的状态
硬违规： - C14 symlink 禁令补 git index 检查：被强制跟踪进豁免目录 （node_modules/.git/构建目录）的 mode 120000 此前躲得过工作树扫描、 却真实存在于 CI checkout——现在先扫 git ls-files -s 的全部跟踪项， 再做带豁免的工作树扫描抓未跟踪软链，两道互补 P2： - verify-dist 解码后重锁 dist 边界：path.resolve + path.relative 严格 确认目标在 dist 内——编码过的 ../ 解码后才现形，statSync 在仓库根 找到文件不等于部署后可达 - HTML 校验面补全：src/href 无引号形态与 srcset 逐项 URL 全部入检 - 新增源↔副本代码 token 序列一致性断言（生产解析器提取 fence/ code_block/code_inline）：逐行正则改写器若触碰任何代码区内容， CI 大声失败——「静默损坏代码示例」这类盲区整类清零 - 编码幂等：classifyLink 按段 decodeURIComponent（a%26b.md 能匹配 含 & 的文件名）；encodeAnchor 先解后编（%20/UTF-8 锚点不再二次 编码成 %2520）；absolute 模式根相对图片同样补 host
- output/（审计报告、发布稿、课程大纲 PDF 等本地过程产物）补 git 侧 防线：站点侧 SRC_EXCLUDE 已排除，但 git add -A 仍可能把商务产物带进 公开仓库 - verify-dist.mjs 的代码 token 分隔符由字面 NUL 字节改为 backslash-u0000 转义写法：字面 NUL 使 git/GitHub 将整个文件按二进制处理，历史 diff 在 review 界面不可见，形成审计盲区
deusyu
force-pushed
the
cursor/docs-site-c60b
branch
from
August 18, 2026 09:59
48bb75f to
087bfd5
Compare
deusyu
marked this pull request as ready for review
August 18, 2026 10:01
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
自建 VitePress 文档站，部署目标为自有域名 harness.dyu.sh（GitHub Pages + Actions）。技术方向与多个想法吸收自 #21（by @Doraemonblogs）；视觉为「纸墨缰绳」编辑部设计（延续仓库海报品牌资产），首页为卷宗结构、文档页为档案卷宗设计——两者吸收自用户以 Claude Design 产出的两稿探索稿，并按本仓库 C14 纪律重实现。
文档页（v4 · 吸收 Claude Design 第二稿）
sidebar.mjs构建时注入，collectPages/llms.txt/RSS 拿到的仍是干净文本v4 文档页：面包屑元信息、自动编号小节、档案化侧边栏、右栏 doodle
v4 文档页暗色模式
docs_site_v4_archive_doc_page_walkthrough.mp4
首页（v3 · 吸收 Claude Design 第一稿）
语义化缰绳图（人类·设计约束 → AGENTS.md → 自定义 linter → CI 反馈回路 → 智能体·如约交付）+ § 卷宗分节（一句话理解 / 六大核心概念 / 档案总目 / 仓库即 harness·自我指涉 / 从哪里开始）。
v3 首页：一行式主标题 + 语义化缰绳图
docs_site_v3_dossier_structure_walkthrough.mp4
与 #21 的关系（设计致谢）
579e725，author = @Doraemonblogs）Suggested-by:trailer；吸收：VitePress 选型、works 按来源系列分组、中文排版细节、部署工作流骨架核心设计：站点本身就是 harness
.vitepress/sidebar.mjs构建时从文件系统生成侧边栏（含计数徽标与条目编号）与首页统计；未匹配分组的新作品落「社区博客」兜底组sidebar --verify断言 63 个一等内容文件恰好各出现一次.md副本、/llms.txt、/llms-full.txt（零依赖）；/feed.xmlRSS 取 git 历史时间practice/核实测试
npm run docs:build通过，check-consistency.shC1–C14 全绿，CI 必需检查consistency / check通过th暗色#1f1a15）、首页五个卷宗分节，均无渲染破损合并前需要的两步手动配置
harnessCNAME →deusyu.github.ioharness.dyu.sh，证书签发后勾选 Enforce HTTPS先做这两步再合并，首次部署即在 harness.dyu.sh 生效。
To show artifacts inline, enable in settings.