文章阅读区域改造 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task.

Goal: 将用户认可的文章区域落地，保留现在的顶部导航和全部文章内容、题单与主/子标题。

Architecture: 复用 VitePress 默认 Layout 的插槽，只在实际面试单题页启用阅读组件与局部 CSS。Markdown 渲染阶段仅将已有首标题和标准元信息组合为 ArticleReadingHeader，避免两个 h1 或重复的难度卡片；文章 Markdown 文件和 h2/h3 锚点保持原样。左侧新增本地题目查找，结果使用现有注册表与规范链接，既有题单和 RAG 分组原样保留。

Tech Stack: Vue 3、VitePress、MarkdownIt、Node 内置测试、Playwright + 本机 Chrome。

已确认边界

• 用户已认可文章区域并明确要求立即实施，无需再确认草图或执行方式。
• 顶部导航包括品牌、栏目、搜索、亮暗切换的内容、几何位置与样式不改。阅读页的中性色变量只设在 VPContent、VPSidebar 和正文/右目录，不设在包围顶部的 Layout。
• 原文、原图、章节顺序、题号、规范 URL、全部 h2/h3 目录和学习持久化保留；不替换为草图里的演示文字或机制图。
• 当前 checkout 已有本轮草图和设计记录，沿用当前工作区、按文件分工；不清理用户文件，不发布生产。

Task 1: 文章头部与标准元信息

Files: Create docs/.vitepress/theme/components/ArticleReadingHeader.vue, docs/.vitepress/theme/data/article-reading.mjs, docs/.vitepress/article-reading-plugin.mjs, tests/article-reading.test.mjs; integrate docs/.vitepress/config.ts, docs/.vitepress/theme/index.ts, docs/.vitepress/theme/layout/Layout.vue.

• [x] 先验证现有章节、学习状态、导航和搜索相关回归基线。
• [x] 为题号、标题/英文副标题、难度、岗位与阅读时长的数据整理、以及仅在单题页替换首标题和标准元信息的渲染行为写失败测试。
• [x] 使用真实 frontmatter 与注册表生成面包屑、唯一 h1、中英标题层级、一行元信息和复用的 ArticleLearningActions。保留原标题锚点。普通页和旧 q-* 页面不受影响。
• [x] 运行新增数据/渲染测试，核对正文段落、表格、代码、全部小节与图片未被删去。

Task 2: 左侧题目查找

Files: Create docs/.vitepress/theme/components/ArticleSidebarSearch.vue, docs/.vitepress/theme/data/sidebar-question-search.mjs, tests/sidebar-question-search.test.mjs; integrate Layout.vue sidebar-nav-before slot.

• [x] 用真实注册表写中文、英文、多词、题号精确查找与空结果的失败测试。
• [x] 组件仅在实际文章页出现；搜索结果保留真实题名、题号、链接和当前题标识。清空恢复原生完整目录，不修改注册表或持久化学习状态。
• [x] 按原生键盘语义支持 Tab、Enter、Escape 清除，报告结果数量；手机菜单内可以使用。

Task 3: 局部阅读样式

Files: Create docs/.vitepress/theme/article-reading.css; import after existing theme styles in index.ts.

• [x] 文章头部、学习操作、表格、引用、代码及正文采用用户认可的冷白/石墨层级；暗色对应中性炭灰，不强制亮色。
• [x] 左侧当前题用浅灰背景，右侧当前节用中性线条；长标题允许换行，全量主/子标题保留。
• [x] 桌面保留原生左栏宽度以维持透明顶部的原始底色，正文最大 820px、右目录约 200px；390/320px 沿用移动菜单，标题/学习工具自然换行，代码与表格在自身范围横向滚动。
• [x] 不调整 VPNav/VPNavBar 或全局 :root；保留原生题序与阅读恢复。

Task 4: 实际验收与记录

Files: Create docs/internal/article-reading-refresh-2026-10-23/check-browser.mjs, results/screenshots and REVIEW.md; update approved sketch review status.

• [x] 构建：捆绑 Node 执行 scripts/build-search-index.mjs，再执行 node_modules/vitepress/bin/vitepress.js build docs。
• [x] 浏览器验证 Q2、长标题题、RAG 来源题，1440/1366/390/320，亮暗两套；完整目录数量与标题一一匹配正文，正文初始位置、侧栏自动定位、学习状态与收藏生效。
• [x] 对比改造前后顶部的链接、文字、几何尺寸和关键计算样式；首页与 GitHub 抽查无外溢。
• [x] 运行相关 Node 回归、git diff --check；查看真实截图，完成独立范围与代码审查后打开实际本地预览。

验证命令

/Users/chris/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node --test tests/article-reading.test.mjs tests/sidebar-question-search.test.mjs tests/learning-navigation.test.mjs tests/learning-progress.test.mjs tests/reading-tracks.test.mjs tests/agent-chapter-sync.test.mjs tests/static-blog-content-source.test.mjs tests/unified-search.test.mjs tests/directory-target.test.mjs
/Users/chris/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node scripts/build-search-index.mjs
/Users/chris/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node node_modules/vitepress/bin/vitepress.js build docs
git diff --check