知行工作室 · 项目说明书

项目概览

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

1.1 设计理念

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

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

技术架构

2.1 文件结构

2.2 外部依赖

页面模块

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点）："静思"主题 — 虚静、自知、沉淀

加载策略：iframe 在确定最终高度前保持隐藏，一步到位显示，避免高度跳变。通信流程：

• iframe onload 触发时，iframe 仍保持隐藏（降级卡片可见）
• 发送 embed-ready 请求精确高度，同时启动轮询监听
• 收到 embed-height 消息，设置精确高度后一步到位显示 iframe
• 800ms 内未收到高度消息，使用默认高度（博文 1080px / 笃行成果 800px）一步到位显示 iframe
• iframe onerror 或网络错误时，保持降级金句卡片显示

博文和笃行两组降级卡片使用不同偏移，避免显示重复金句。每个时段 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-color 的微妙光晕效果，让交互带有 AI 驱动的数字质感。

主题系统

网站支持 8 种主题（默认、暗色、蓝色、绿色、紫色、橙色、青色、系统跟随），通过 CSS 变量实现全局切换。主题偏好通过 localStorage 持久化保存，刷新页面后自动恢复。

5.1 主题切换

5.2 CSS 变量体系

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

响应式适配

6.1 断点与布局

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

部署与维护

1. 代码推送到 GitHub 仓库 x2it/w3b 的 main 分支
2. GitHub Pages 自动构建并部署到 w3b.pub
3. CDN 缓存约 5-10 分钟刷新，通过 style.css?v=xxx 参数强制刷新

7.1 SEO 配置

• robots.txt：允许所有爬虫，禁止 /assets/，指向 sitemap
• sitemap.xml：包含首页（weekly）和关于页（monthly）
• 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 结构化数据
• 404 页面：noindex, nofollow，防止搜索引擎索引错误页面