知行工作室 · 项目说明书

项目概览

知行工作室（w3b.pub）是一个以"知行合一"为核心理念的个人品牌展示网站。网站通过粒子动画、时间线叙事、交互式平衡器和嵌入式内容模块，将中国传统哲学思想与现代 Web 技术、AI 理念相融合，呈现"理会"（思考与洞察）、"践行"（行动与创造）与"AI 赋能"（数字演进）的三位一体。

1.1 设计理念

网站围绕四条核心线索展开：

• 理会 · 洞察本质 — 通过粒子动画可视化思维的四种状态（有序、发散、专注、AI 神经网络），呼应朱熹"穷理"的思想
• 践行 · 当下行动 — 通过时间线串联从《尚书》到王阳明再到当下的知行思想脉络
• 知行合一 · 动态平衡 — 通过交互式天平让用户直观感受知与行的平衡关系
• AI 赋能 · 数字演进 — AI 是知与行的数字映射：数据为知，决策为行。神经网络中每一层都是"知"，每一次前向传播都是"行"

技术架构

2.1 文件结构

2.2 外部依赖

2.3 架构设计要点（v3.0.0 新增）

• CSS 唯一真相源：主题颜色与字体仅在 style.css :root + .x-mode 中声明；theme.js 用 getComputedStyle 读取后写回 :root，不再维护 JS 常量 THEME_VARS 副本，改色/改主题只改 CSS。
• JS 模块化 script defer：内联脚本 → 模块化 defer：原 index.html 单页即含 1100+ 行内联 IIFE（主题 + i18n + 粒子 + 平衡 + 打字机 + 杂项）。v3.0.0 按职责切为 6 个 JS 模块，全部用 <script defer> 加载，首屏 HTML 解析与执行互不阻塞。
• 性能预算 & 移动端关怀：粒子系统在窄屏（768px 以下）粒子数降为桌面 45%；visibilitychange 切换到后台立即取消 rAF，节省 CPU/电量；所有动画遵从 prefers-reduced-motion，为眩晕症用户自动降级。
• GEO + SEO + A11y 三保险：robots.txt 覆盖 13 种 AI 爬虫；/ai.txt 发布引用条款与事实锚点；JSON-LD 结构化数据随语言切换；每个页面含 SkipLink、ARIA 标签、role= 语义化，键盘可达。
• 回归防线（CI）：每次 push / PR 自动跑「i18n key 对齐 · JSON-LD · sitemap · 全部 JS 语法」四项检查，防止新增翻译漏 key、结构化数据破坏等回归。

页面模块

3.1 粒子动画区（理会 · 洞察本质）

基于 Canvas 的粒子系统，支持四种思维状态切换，其中 AI 模式将知行合一理念与神经网络可视化融合：

• 有序思维 — 粒子排列为规则网格，各就各位互不连线，象征逻辑与秩序
• 发散联想 — 粒子自由运动，近距离粒子相互连线，象征创造性思维
• 专注凝聚 — 粒子向中心聚拢，各自独立不连线，象征深度思考与聚焦
• AI 思维 — 粒子形成 3 层神经网络结构（输入层、隐藏层、输出层），层间连线模拟突触连接，信号光点沿连线流动并带拖尾效果，节点发光模拟神经元激活。象征 AI 作为知与行的数字映射

60-120 个粒子（默认 80 个，专注模式 120 个，有序/发散模式 60 个），requestAnimationFrame 驱动。颜色跟随主题变量动态变化。

3.2 时间线（践行 · 当下行动）

纵向时间线展示知行思想的历史脉络：

• 《尚书》 — "非知之艰，行之惟艰。"
• 朱熹 — "只有两件事：理会，践行。"
• 王阳明 — "知是行的主意，行是知的功夫；知是行之始，行是知之成。"
• 当下 — "每一个项目、每一次选择，都是古老思想在当下的实践与回响。"

3.3 平衡器（知行合一 · 动态平衡）

交互式天平可视化，用户通过两个滑块控制"理的深度"和"行的力度"，天平横梁实时倾斜反映平衡状态。

3.4 博文随笔 & 笃行成果

均通过 iframe 嵌入第三方内容，自动同步最新数据。iframe 加载失败（网络错误）时，显示知行节律降级金句卡片：

• 博文随笔 — iframe 嵌入 fudawei.coze.site，展示博文随笔；加载失败时显示 3 张金句卡片
• 笃行成果 — iframe 嵌入 output.coze.site，展示项目作品集；加载失败时显示 3 张金句卡片

知行节律：金句主题根据访问时段自动切换：

• 晨间（6-12点）："理会"主题 — 穷理、博学、慎思
• 午后（12-18点）："践行"主题 — 笃行、躬行、力行
• 晚间（18-24点）："合一"主题 — 知行合一、致良知、守静
• 深夜（0-6点）："静思"主题 — 虚静、自知、沉淀

加载策略（v3.3.0 响应式高度）：首屏不会「一直等到 postMessage 才显示」，而是按 嵌入类型 × 当前视口 先给出足够高的默认值，收到消息后再夹紧到 [minH, maxH] 区间重设。通信与容错流程：

• IntersectionObserver（rootMargin=200px）命中后立即显容器，按当前断点使用最终高度 = default + bias：博客 1075/1100/1150、项目 780/950/980（桌面/≤768px/≤480px）。不会先隐藏等消息。
• 支持三种 postMessage 协议：{height}、{data:{height}}、{type:'height',value}；收到后按自然区间夹紧 [min, max]，再叠加 bias（博客 D+75 / M-100 / S-100，项目 bias=0），保证「±调参」在 raw 位于区间内时也有真实像素变化；同时 强制 inline minHeight 覆盖 style.css 兜底，消除样式表优先级疑虑。
• 桌面端项目区封顶 820px（削掉 3 列 4 行卡片下方大片空白）；移动端项目区与博客两端 均不封顶，内容多时允许更高（bias 宽松边界 = max + 500 / min - 100）。
• 20s（20000ms）超时或 iframe.onerror 时降级为时段金句卡片；20s 内仍未收到 postMessage 时，最终兜底高度 = default + bias（博客 1075/1100/1150px；项目 780/950/980px）。
• 横竖屏切换/拉窗口跨越断点（≤480 / ≤768 / >768）时，防抖 120ms 用最后一次原始高度重新 clamp + bias，避免横竖屏切换后高度漂移。

博文和笃行两组降级卡片使用不同偏移，避免显示重复金句。每个时段 6 条金句，每次随机显示 3 条。

卡片样式：浅色背景 + 左侧主题色竖线 + 深色文字，与页面整体风格统一。竖线颜色跟随主题切换（var(--accent-color)），hover 时变为次要色（var(--accent-secondary)）。

调试模式：URL 加 ?debug=1 强制显示 iframe，用于排查第三方服务问题（如续费后验证加载、检查 postMessage 等）。

滚动联动：滚动到"博文随笔"区域时粒子切换"有序思维"；滚动到"笃行成果"区域时切换"专注凝聚"。

AI 元素

AI 并非附加装饰，而是知行合一理念在数字时代的自然延伸。

4.1 AI 金句轮播

Header 区域动态展示 AI 与知行合一相关的金句，打字机效果逐字显示/删除，15 条金句循环：

• "AI 是知与行的数字映射 — 数据为知，决策为行。"
• "当机器学会了思考，知行合一便有了新的注解。"
• "算法穷理，模型践行 — AI时代的知行合一。"
• "神经网络中，每一层都是'知'，每一次前向传播都是'行'。"
• "AI不是替代思考，而是延伸知行的边界。"
• "从感知到认知，从推理到行动 — AI正在重走知行之路。"
• "大模型是穷理的现代工具，Agent是践行的数字化身。"
• "知而不行，只是未知；行而不知，只是盲行 — AI让知行真正合一。"
• "每一行代码都是一次践行，每一次调试都是一次理会。"
• "AI的涌现能力，恰如知行合一时的豁然贯通。"
• "训练是知，推理是行，微调是知行合一的迭代。"
• "从GPT到Agent，AI正在完成从'知'到'行'的跨越。"
• "数据是新的经典，算法是新的诠释 — AI时代的格物致知。"
• "提示工程是知，生成结果是行 — 人机协作的知行合一。"
• "AI让'知易行难'变为'知行合一' — 因为知即行，行即知。"

4.2 神经网络背景

页面背景添加 SVG pattern 平铺的神经网络节点 + 连线纹理，opacity 仅 0.03，极微妙不抢主体内容，fixed 定位跟随页面滚动。

4.3 AI 赋能交互

卡片 hover 时显示基于 --accent-rgb 的渐变边框光泽（::before + mask 技术实现），边框微透强调色，悬浮上移 3px 并加深双层阴影，让交互带有 AI 驱动的数字质感。

主题系统

网站共 7 个主题 + 跟随系统，按「📜 书卷 / 🏢 工作室 / 🪷 哲学」三家族分组。切换主题不仅换颜色，还切换布局宽度、字体族、卡片形态、装饰层、时间线排布、粒子强度——这是双层切换机制。主题偏好通过 localStorage 持久化保存，刷新页面后自动恢复。

5.1 主题切换

5.2 CSS 变量体系

每个主题定义 13 个 CSS 变量：背景渐变、背景色、文字色、次要文字色、浅色文字、深色、强调色、强调色 RGB、次要强调色、边框色、卡片背景、卡片阴影、卡片悬浮阴影。切换主题时只需替换 body 的 class，所有组件自动响应。另有 6 个全局变量（3 个圆角 + 3 个过渡速度）不受主题覆盖。背景使用微妙渐变（--bg-gradient）替代纯色，增强视觉层次。

响应式适配

6.1 断点与布局

网站适配三个版本，采用 480px 和 768px 两个断点：

部署与维护

1. 代码推送到 GitHub 仓库 x2it/w3b 的 main 分支
2. GitHub Pages 自动构建并部署到 w3b.pub
3. CDN 缓存约 5-10 分钟刷新；每次修改 style.css 或任意 JS 必须同步更新 index/about/404 三页所有 <link> / <script defer> 的 ?v=x.y.z 参数（当前版本 v=3.3.6）

7.1 SEO 配置

• robots.txt：允许所有爬虫 + 13 种 AI 爬虫白名单（GPTBot / ClaudeBot / PerplexityBot 等），禁止 /assets/，指向 sitemap
• sitemap.xml：包含首页、关于页、RSS 源、ai.txt、ads.txt，含 hreflang 三语交替
• canonical URL：首页为 https://w3b.pub/；说明书为 https://w3b.pub/about.html
• Open Graph：两页均配置 og:title、og:description、og:url、og:locale
• Twitter Card：两页均配置 summary_large_image 卡片
• JSON-LD：首页包含 WebSite 结构化数据；说明书页包含 TechArticle 结构化数据
• 404 页面：noindex, nofollow，防止搜索引擎索引错误页面
• RSS Feed：两页均声明 <link rel="alternate" type="application/rss+xml"> 指向 /feed.xml；底部"订阅"入口提供复制链接与预览功能
• GEO 生成式引擎优化：/ai.txt（IAF 声明 + 事实锚点）+ /ads.txt（AI 引用条款）+ 15 项 fact: meta + JSON-LD publisher/version/areaServed + hreflang 三语交替