Chronicle-IRAS的博客

CHRONICLE：把滚动叙事做成一条可回退的时间线

Wed, 21 Oct 2026 00:00:00 GMT

CHRONICLE 是一个滚动驱动的交互叙事页面。它没有把“滚动”当成页面进度条，而是把 8 个场景组织成一条有边界、可回退、可重播的时间线。

这篇文章不讨论它最终好不好看，而是记录几个工程问题：场景之间如何衔接、动画和滚动如何解耦、以及为什么“能回退”比“能播放”难得多。

场景不是页面，而是状态

项目把体验拆成 Prelude、Welcome、Composer、Currently、Profile、Space、Destinations、Goodbye 等场景。每个场景有自己的背景、文字、角色或 WebGL 画布，滚动只负责触发边界。

一个关键选择是：滚动距离和动画时长分离。场景用 svh 定义滚动区间，动画时长则写在 sceneRegistry.ts 里。Composer 甚至预留了 200svh，其中 50svh 用于编辑，角色在这段时间里隐藏。

这带来一个直接结果：用户继续滚动，不会把动画“拖快”或“拖慢”；动画按自己的时间线播放，滚动只决定何时开始。

部分	作用
`src/app/`	固定视口舞台、场景、滚动区间、可访问性与输入门禁
`src/scenes/`	场景内容与局部动画钩子，不直接监听滚动
`src/transitions/`	角色、文字、传送门、内容交接与重启编排
`src/features/`	Composer、文字冲击、星空/黑洞等独立能力
`src/stores/`	当前场景、减少动态效果、Composer 就绪状态

可回退，才是真正的时间线

很多滚动页面只实现了“向下播放”。CHRONICLE 为每个边界准备了前进时间线，以及可选的返回时间线。Prelude 返回是 3.3 秒，Welcome 是 0.35 秒的简化边界，Profile 返回是 1.8 秒，传送门进出各 1.25 秒。

当边界触发后，播放会独立于滚动输入完成；主内容在过渡期间设为 inert，滚轮、触摸和滚动键被暂时阻止。到达目标场景后，文档才移动到该场景的阅读/编辑区间，输入恢复。

这解决了一个常见问题：用户快速滚动时，动画播放到一半又被新的滚动事件打断。这里用“过渡期间锁输入”换取了确定性。

Composer 与角色编排

Composer 是一个可编辑的节点图。它使用 React Flow，但禁用了滚轮缩放、背景平移和自动适配；只有节点和边可编辑，滚轮继续驱动页面叙事。

角色不是视频，而是注册表驱动的姿态层。DeepSeek、Grok、Gemini、Claude、GPT 等角色由 src/components/CharacterCast.tsx 和角色注册表管理。Scene 03 到 02 的拉拽动画使用 DS_PULL / GROK_PULL 姿态，并重复“用力”的过程。

这类页面最容易失控的地方是“每个场景都写一套动画”。项目把场景内容、过渡编排和共享能力拆开，至少让新增场景时不用复制整段滚动逻辑。

可访问性与降级

非活动场景设为 inert，并从辅助技术中隐藏。
阅读/编辑区间到达后，键盘焦点回到可用内容。
prefers-reduced-motion 下，边界简化、时长缩短到 0.35s。
没有 WebGL 时保留 CSS 艺术与原生效果；WebGL 1 也能工作。
首次访问的 Loading 有 6 秒超时兜底，不会因为资源失败卡死。

这些不是“加分项”。当一个页面把滚动、动画和输入都锁在一起时，降级路径就是可用性的一部分。

部署边界

项目用 Vite 构建，base: './'，同一份产物既能部署在域名根路径，也能部署在 GitHub Pages 的子路径。dist/ 由 GitHub Actions 发布，不依赖仓库名硬编码。

这类叙事页面通常不需要服务端；真正的复杂度在客户端的时间线、资源预热和状态回收。CHRONICLE 把场景保持在固定视口中，非活动场景暂停效果，也是在控制长期运行的成本。

小结

CHRONICLE 值得看的地方不是“用了多少库”，而是它把滚动叙事拆成了可管理的几层：场景、边界、时间线、输入门禁和降级。只要其中一层没有边界，整个页面就会变成一次不可回退的演示。

如果你要做类似的滚动体验，先回答三个问题：动画能否独立完成？返回时能否恢复？减少动态效果时还剩下什么？这三个问题比选哪个动画库更重要。

用蓝图生成 Qt 工程：把 AI 代码放进可审查的流水线

Tue, 20 Oct 2026 00:00:00 GMT

Qt Blueprint Generator 是一个用蓝图描述 Qt 6 Widgets 应用的桌面工具。它的目标不是做完整的 IDE，而是把“设计意图”变成可审查、可构建、可导出的工程。

为什么用蓝图作主数据源

如果让 AI 直接改代码，最大的问题是：改动不可比较，也难以判断哪些部分是契约、哪些部分是实现。这个项目把蓝图作为主数据源，节点、端口、连线和属性先落成结构化数据，再由确定性生成器维护公共契约与工程骨架。

一个蓝图工程包含两个文件：blueprint.json 保存语义，layout.json 保存画布位置。移动节点只改变布局，不会改变生成的中间表示；这样评审时可以只关注语义差异。

生成流程

蓝图设计 → 校验 → 生成 Candidate → 人工 Review
        → Accept / Reject → Build → Export

Candidate：AI 生成的代码先进入候选区，不会直接覆盖正式工程。
Review：逐文件对照当前实现与候选代码，可以选择接受、编辑后接受或拒绝。
Build：构建需要显式触发，使用真实的 CMake 工具链。
Export：导出可以独立重新构建的工程，而不是只保留当前工作区。

这条流程的核心约束是：AI 不拥有最终写入权。公共契约、程序入口、构建配置等受保护内容由确定性系统维护；生成失败也不会自动清空旧工程。

确定性与 AI 的边界

项目把职责拆成几层：

层	职责
Qt 编辑器	画布、属性、文档生命周期、候选审核
生成服务	校验、写候选、接受授权、脚手架与构建
目标插件	把蓝图语义 lowering 成具体目标工程
协议工具	Blueprint v2 与插件声明的离线校验

外部代码的导入也是同样的思路：C/C++ 文件以只读黑盒模块接入，绑定接口契约并校验 SHA-256；编辑器不假设自己可以安全地重写这些文件。

当前能力与限制

Phase 1 的运行时只接受一条线性链：

Start → 零个或多个 Logic Module → 可选的唯一末端 UI Page → End

Decision、External Code、多 End 等节点仍然可以编辑，但不属于这一阶段的运行时生成范围。节点编辑能力不等于运行时能力，这是 README 里反复强调的边界。

插件平台仍是 Draft：当前只实现了 TypeScript/Node 的声明校验与最小内存 Registry，不执行插件代码，也没有接入 Qt GUI。长期方向是“编辑器和目标插件分离”，但在协议冻结前，不把提案当成已交付能力。

构建与测试

项目使用 C++17、Qt 6 Widgets / Network、CMake 和 Ninja。Windows 下建议把构建目录放在纯 ASCII 路径，避免 MinGW 与 AutoMOC 在中文路径上出问题。

cmake -S . -B $buildRoot -G Ninja `
  -DBUILD_TESTING=ON `
  -DCMAKE_PREFIX_PATH="$qtRoot"
cmake --build $buildRoot
ctest --test-dir $buildRoot -C Debug --output-on-failure
& (Join-Path $buildRoot 'BlueprintEditor.exe')

CTest 使用 Fake AI 或离线网络替身，不读取真实密钥，也不产生模型费用；需要调用真实模型的集成程序不会注册进自动测试。

复盘

这个项目最有价值的部分不是“让 AI 写代码”，而是把 AI 放进一条有边界、可回滚的流水线：

结构化输入优先于自然语言提示。
生成结果先成为候选，再经过人工确认。
契约、入口和构建配置由确定性系统维护。
明确写出“当前不支持什么”，比模糊地承诺“未来都可以”更重要。

代码与文档采用 MIT License；Qt 和其他第三方依赖仍遵循各自许可证。

StudyLoop：本地优先的学习系统，以及 AI 失败时的退路

Tue, 20 Oct 2026 00:00:00 GMT

StudyLoop 是一个本地优先的个人学习系统。它没有把“学习”简化成一个番茄钟，而是拆成三个互相连接、但边界清楚的模块：

学习计划：接下来学什么，每天做什么。
每日巩固：今天学的内容是否真的理解了。
复习计划：已学过的内容，之后怎样记牢。

这三个模块共享知识库，但不混用任务。学习任务只记录完成情况；巩固题和复习题才影响掌握度。这个边界是整套设计里最重要的部分。

为什么本地优先

应用默认单用户、免登录。学习任务、笔记、题目、计划和答题记录都保存在浏览器 IndexedDB；关闭页面、重启设备后仍然存在。

联网只用于可选的 AI 出题服务。没有配置 AI 或断网时，系统仍可使用本地模板题与已缓存的题目。复习计划创建时会预生成并缓存基础题目，因此已建立的计划不会因为网络中断而失效。

这带来两个实际问题：

导出/导入不是附属功能：浏览器存储可能被清理，数据必须能完整导出。
AI 不是主存储：模型失败不能把用户输入一起清空。

三个模块如何连接

学习计划（安排新内容）
   ↓ 完成今日学习任务
每日巩固（记录实际所学并即时出题）
   ↓ 用户确认纳入长期记忆
复习计划（按目标天数间隔复习）
   ↓ 暴露薄弱点
每日巩固

流转必须由用户确认。勾选“已学习”不会自动生成大量题目，也不会自动修改复习计划。这个约束看起来保守，但能避免 AI 把一次误操作放大成几十道题。

概念	所属模块	是否影响掌握度
学习任务	学习计划	否，只记录完成
当日巩固会话	每日巩固	是，形成初始掌握度
长期复习会话	复习计划	是，更新间隔与下次日期
笔记与知识点	共享知识库	被答题记录间接更新

AI 的边界

后端是一个本地 Fastify 代理，读取 .env.local 里的 DeepSeek 配置。API Key 不会进入前端代码或 IndexedDB；日志和导出文件也不应包含密钥。

出题层用统一的 QuestionProvider 接口隔离：

本地模板提供器：无需联网，从定义句、列表、步骤、对比和代码块生成基础题。
DeepSeek 提供器：负责知识点提取、题型选择、干扰项和解析。
未来本地模型：可以接 WebLLM，但不进入 MVP。

DeepSeek 返回 JSON，经过 Zod schema 二次校验。空内容、截断或校验失败时只重试一次；仍失败就切到本地模板，并明确告诉用户。这里的原则是：AI 可以失败，但学习流程不能卡死。

复习计划不是“每天随机出题”

复习计划创建时，用户先确认知识点，再选择 3–60 天的目标、开始日期和轻量/标准/强化三档强度。系统预生成阶段日程和基础题目，首次打开当天时恢复“今日到期复习”，不需要网页一直运行。

答题后更新掌握度和下次复习日期；错题会在后续日期重新出现。主观题先展示参考答案，再由用户选择“不会 / 模糊 / 掌握 / 轻松”。

这也解释了为什么不能把学习任务和复习任务合成一个“待办数字”：学习任务是新内容，复习任务是旧内容，它们的逾期处理方式不同。

值得复用的设计

数据先于 AI：用户输入、计划、答题记录都在本地；AI 只是可替换的题目来源。
Provider 隔离：本地规则和云端模型实现同一个接口，失败可切换。
Schema 二次校验：模型输出不是“看起来像 JSON”就直接用。
用户确认边界：模块之间不自动流转，避免错误扩散。
可解释的复习：用户能看到“为什么今天复习这些内容”，而不是只看到一个日期。

小结

StudyLoop 的工程价值不在“接了 DeepSeek”，而在于它把 AI 放在一个可失败、可替换、可审计的位置。对个人学习工具来说，这比多一个模型名称重要得多。

项目仍在迭代；上面的模块边界和数据流来自公开的 README 与设计文档，具体实现以仓库为准。

FlashDuel：2–4 人实时反应游戏，服务端如何管住房间与回合

Mon, 19 Oct 2026 00:00:00 GMT

FlashDuel 是一个 2–4 人联机反应对抗游戏。它有三种模式：FlashStrike 测反应速度、ColorSniper 测视觉搜索、MemoryChain 测序列记忆。

实时多人游戏最容易出问题的地方，不是画面，而是“谁在什么时候看到了什么、服务端相信谁”。这个项目把客户端表现和服务端游戏逻辑分开，结构值得看一眼。

三种模式，同一套回合

模式	玩家做什么	主要能力
FlashStrike	信号出现后尽快点击，提前点击判抢跑	反应速度
ColorSniper	在多个目标中找出指定颜色	视觉搜索
MemoryChain	按顺序复刻颜色序列	序列记忆

三种模式共享房间、玩家、回合和结果流程。服务端目录里能看到 Room、RoomManager、GameEngine 和 BaseMiniGame，以及三种模式各自的实现。这个拆分让“房间生命周期”和“小游戏规则”不会缠在一起。

前后端边界

客户端使用 React 19、TypeScript、Vite、Zustand、Tailwind CSS 和 Socket.IO Client。服务端使用 Node.js、Express、Socket.IO、TypeScript 和 Pino。

一个合理的职责划分是：

客户端：渲染界面、收集输入、展示倒计时/结果，不拥有最终判定权。
服务端：维护房间与玩家状态、推进回合、判定抢跑与得分、广播结果。
Socket 事件：只传必要动作和状态，不把整个游戏状态交给客户端随意修改。

反应类游戏尤其不能只相信客户端时间。抢跑判定、点击顺序和回合开始时间需要以服务端为准；客户端时钟只用于显示。否则延迟、改时间或重放请求都能轻易破坏公平性。

房间状态机

实时房间至少要回答这些问题：

谁创建了房间，房间号如何加入？
玩家人数不足/已满时，开始按钮是否可用？
一局结束后，是回到大厅、自动重开，还是解散？
玩家断线后，房间保留多久？是否允许重连？
重复的开始/加入事件如何幂等处理？

服务端的 RoomManager 和 Room 分层，适合把这些状态收敛在服务端；客户端只根据广播的状态渲染。项目里还有 GameEngine 与各小游戏的测试，说明规则层可以脱离网络单独验证。

延迟与体验

实时游戏不需要“零延迟”，但需要一致的延迟处理：

回合开始时间由服务端广播，客户端只做本地倒计时展示。
输入带客户端序号/时间，服务端用自己的接收时间做最终排序。
对提前点击、重复点击、超时未点击分别定义结果。
断线时不要把玩家直接“判负”到不可恢复；至少要让房间状态可解释。

这些是设计原则，不是对项目内部实现的逐行描述；具体事件名和判定以仓库代码为准。

部署

README 给出的部署路径很直接：

服务端 npm run build 后用 pm2 托管 dist/index.js。
客户端 npm run build 生成静态资源，交给 Nginx 或由后端静态托管。
项目使用 MIT License。

这类项目不需要复杂微服务。一个 Socket.IO 服务 + 一个静态客户端，已经足够支撑 2–4 人的房间；真正的成本在状态管理和异常路径。

小结

FlashDuel 的看点不是“又做了一个小游戏”，而是把房间、回合、小游戏规则拆开，并让服务端拥有判定权。对实时多人项目来说，先想清楚状态机，再想动画和音效，通常更省事。

ESP32 监控中台：Vue 3 的实时视频界面

Mon, 19 Oct 2026 00:00:00 GMT

monitor 是一个面向 ESP32-S3 摄像头集群的实验室监控前端。它把多路视频、设备端口和系统配置放在同一个 Vue 3 应用里，后端通过 HTTP API 管理节点，视频流则由每台设备独立推送。

技术栈与页面

项目使用 Vue 3（Composition API + <script setup>）、TypeScript、Vite、Element Plus、Pinia、Vue Router 和 Axios，视频解码使用 jmuxer。

页面	职责
实时预览	多路 MJPEG / WebSocket 视频流，支持展开与关闭
历史录像	录像文件查询与回放
通讯终端	节点端口状态、启停管理
系统配置	设备调度与系统参数（管理员）
登录/角色	访客只读、管理员可操作

侧边栏在桌面端常驻，移动端切换为抽屉导航；主题偏好保存在本地。

视频流：WebSocket 与 jmuxer

H.264 流通过 WebSocket 以二进制帧到达，前端把每一帧交给 jmuxer 解码到 <video>。关键不是“能播”，而是断流、重连和组件卸载时不要留下定时器。

ws = new WebSocket(props.streamUrl)
ws.binaryType = 'arraybuffer'

ws.onmessage = (event) => {
  jmuxer.feed({ video: new Uint8Array(event.data) })
}

ws.onclose = () => {
  if (destroyed) return
  reconnectTimer = window.setTimeout(connect, 2000)
}

组件卸载时会清空首次连接与重连定时器、摘掉 onclose 后主动关闭 WebSocket，并销毁 jmuxer；否则离开页面后仍可能继续建连。MJPEG 模式则直接使用 HTTP 流地址，不经过 jmuxer。

配置集中在一个文件

最容易出问题的不是请求本身，而是地址散落在各处。项目把 API 与流地址收敛到 src/config.ts：

export const API_BASE =
  import.meta.env.VITE_API_BASE ?? 'http://<YOUR_SERVER_IP>:3000/api'

export const STREAM_HOST =
  import.meta.env.VITE_STREAM_HOST ?? '<YOUR_SERVER_IP>'

节点只保存端口，URL 由 streamHttpUrl(port) / streamWsUrl(port) 拼接。换服务器只需要改 .env，不用搜索替换业务代码。

节点与端口管理

节点模型很克制：

interface DeviceNode {
  id: string
  udp: number
  http: number
}

Pinia 里的 usedPorts 会把所有节点的 UDP/HTTP 端口收进一个集合，启动新节点前检查冲突；界面上 UDP 范围是 9001–9050，HTTP 范围是 9051–9100，已占用端口会标红。启停、重置等操作只对管理员开放，普通访客只能看流。

权限：客户端门禁不是安全边界

项目用 VITE_ADMIN_PASSWORD 做前端管理员门禁，登录状态存在 localStorage。这适合实验室内网演示，但必须明确：构建进前端的密码不是授权机制。任何能拿到前端资源的人都能绕过它，真正的启停与配置接口必须在服务端校验身份。

如果要把这套系统放到不可信网络，至少需要：

服务端会话或 Token 校验；
对启停、重置、配置等写接口做权限控制与审计；
不再把管理员密码放进 VITE_* 变量。

部署

仓库提供了一个 Windows 一键脚本：构建后通过 SSH 清理旧目录，SCP 上传 dist/，再更新 Nginx 权限。脚本里的服务器地址是占位值，部署前必须替换；生产环境更建议把部署步骤放进 CI，而不是把凭据留在批处理文件旁边。

复盘

视频类页面的重点在生命周期管理：断流重连、卸载清理、重复建连。
配置集中化能显著降低部署与排错成本。
角色分离要前后端一起做；前端门禁只负责界面状态。
监控系统没有“差不多能看”这一说，端口冲突和权限边界都要在代码里写清楚。

万能导：把多平台知识库迁回 Markdown

Mon, 19 Oct 2026 00:00:00 GMT

wandao（万能导）解决的是一个很具体的问题：知识散落在不同平台，导出后目录没了、图片断了、附件丢了，最后还是要手动整理。

它的定位是“多平台知识库 Markdown 导入导出工具”。不是做另一个笔记应用，而是把已有内容迁回本地，或者把本地 Markdown 导入到目标平台。

支持的范围

README 列出的平台覆盖了常见的知识库和内容平台：飞书、语雀、阿里云 Thoughts、印象笔记、有道云笔记、为知笔记、OneNote、知识星球、ima 知识库、钉钉文档、WPS、息流、Obsidian、Notion、知乎、CSDN、微信公众号和本地 Markdown。

方向	目标
导出	把有权访问的平台内容导出为本地 Markdown
导入	把本地 Markdown 导入支持的平台
保真	尽量保留目录结构、正文格式、图片与附件
迁移	知识备份、平台迁移、学习资料整理

这类工具最难的不是“调通一个接口”，而是处理不同平台的目录、图片、附件和格式差异。README 把“保留目录结构、图片、附件”放在核心位置，说明作者很清楚真正的成本在哪里。

为什么用桌面端

项目提供 Windows x64 与 macOS arm64 桌面端。相比纯命令行，桌面端更适合处理登录态、平台选择、任务进度和失败重试。

任务中心会保留历史进度与失败原因，平台中心展示已接入平台，插件中心负责搜索、安装和更新平台插件。这个结构比“一个脚本跑完所有平台”更容易维护，也更适合非技术用户。

AI 辅助学习

项目里有一个我比较喜欢的设计：把课程资料、项目文档和源码导出到同一目录，再配合“项目学习导师”提示词交给支持本地文件的 AI。

这样 AI 看到的不是零散截图，而是“教学文档 + 真实代码”的组合。对于理解一个陌生项目，这比只读 README 更有效。

边界与许可

只应导出自己有权访问的内容。
平台插件会随平台变化而更新，导出结果不保证 100% 完整。
项目使用 AGPL-3.0；如果要在网络服务中修改并分发，需要遵守许可证。

如果你也经历过“从某个平台导出后图片全裂开”，这个项目值得看一眼。它不承诺完美迁移，但至少把重复复制粘贴这件事自动化了。

用 Astro 内容集合管理博客文章

Sun, 18 Oct 2026 00:00:00 GMT

内容集合（Content Collections）解决的问题很具体：把散落在目录里的 Markdown 变成有类型、可校验、可查询的数据。对个人博客来说，它的价值不在“功能多”，而在“坏数据会在构建期失败”。

为什么需要内容集合

没有 schema 的时候，frontmatter 只是一段 YAML。字段拼错、日期写成中文、标签随意新增，都要等到页面上出现空白时才被发现。内容集合把这些检查提前到构建阶段，并给出具体字段名。

目录与图片

文章以目录为单位，图片与正文放在一起。这样迁移时不需要额外维护一份资源映射，相对路径也不会因为文章换位置而失效。

schema 示例

下面是一段刻意加长的代码，用来检查代码块的横向滚动与复制按钮：

export const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/index.{md,mdx}' }),
  schema: ({ image }) => z.object({
    title: z.string().min(1).max(80),
    description: z.string().min(20).max(160),
    slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
    pubDate: z.coerce.date(),
    tags: z.array(z.enum(tagNames)).max(3).default([]),
    draft: z.boolean().default(false),
    cover: image().optional(),
  }),
});

字段对照

字段	必填	类型	默认值	校验规则	用途	示例	备注
title	是	string	—	1–80 字符	标题与 SEO	你好，世界	中文建议不超过 40 字
description	是	string	—	20–160 字符	摘要与 meta	一篇示例文章	必须能独立成立
slug	是	string	—	kebab-case	URL	hello-world	全局唯一
pubDate	是	date	—	可解析日期	排序与 RSS	2026-10-18	按站点时区过滤
updatedDate	否	date	—	≥ pubDate	更新时间	2026-10-20	不替换发布日期
tags	否	string[]	[]	注册表内	分类	前端	最多 3 个
draft	否	boolean	false	—	草稿过滤	true	构建时排除
cover	否	image	—	本地图片	封面	/uploads/astro-content-collections-cover.png	需同时提供 coverAlt

构建期过滤

草稿与未来日期在构建时被排除，因此它们不会进入首页、列表、RSS 或搜索索引。日期按 Asia/Shanghai 的日历日比较，避免 YYYY-MM-DD 被解析成 UTC 午夜后，在当天早上被误判为未来。¹

小结

内容集合不是银弹，但它把“内容约定”变成了可执行代码。对一个人维护的博客来说，这比多一套后台更有用。

具体实现见 src/lib/posts.ts 中的 isPublished()。 ↩

onCss：让 AI 生成 UI 代码，再把预览关进 iframe

Sun, 18 Oct 2026 00:00:00 GMT

onCss 是一个可视化 CSS / UI 代码生成工具。用户选择技术栈、组件类型和视觉风格，输入自然语言需求，后端调用 AI 生成结构化代码，前端在编辑器里展示并在 iframe 中预览。

它吸引我的地方不是“AI 写页面”，而是它把生成结果约束成一组可校验的文件，而不是一段不可执行的聊天文本。

一次生成的完整链路

前端表单
  → POST /api/generate-code
  → Zod 校验请求参数
  → AI_MODE=mock ? mockGenerator
                 : promptBuilder → AI → parseAiJson → Zod
  → 统一 data
  → CodeMirror 展示 / iframe 预览

后端只做一件事：代理 AI，并把结果变成稳定结构。它不存历史记录，不做用户系统，也不在线构建项目。历史记录放在前端 localStorage，预览由前端 iframe 承担。

这个边界让 MVP 很容易替换模型：只要返回结构不变，前端不需要关心背后是 DeepSeek、其他 OpenAI-compatible 服务，还是本地 mock。

为什么要求 JSON，而不是直接返回代码

如果让模型自由返回一段 Markdown，前端就要猜哪段是 Vue、哪段是 CSS、入口文件是哪个。onCss 的响应结构明确到文件级：

framework
styleLibrary
componentType
title / description
files[]：filename、language、code
previewEntry
notes[]

后端用 Zod 校验 AI 返回的 JSON，解析失败或结构不符就返回 AI_RESPONSE_INVALID。这不是为了“类型好看”，而是为了让前端可以安全地渲染编辑器、下载文件和选择预览入口。

mock 模式不是玩具

AI_MODE=mock 时不调用外部 API，直接返回本地生成结果。它的价值在于：

没有 API Key 也能调试前端表单、编辑器和预览。
CI 可以稳定测试接口，不依赖模型输出。
真实 AI 失败时，至少有一个可预期的最小响应。

后端配置里 AI_MODE 默认就是 mock。对个人项目来说，这比“必须先配置 Key 才能启动”更友好。

iframe 预览的安全边界

生成的是可执行 HTML/CSS/JS。把这段内容直接注入主页面，会带来样式污染和脚本风险；放进 iframe 至少建立了文档边界。

仍需要注意：

iframe 应使用 sandbox，按需要开放 allow-scripts，不要同时开放 allow-same-origin。
预览内容不会自动获得主站权限。
代码下载和复制只处理生成的文件，不要把用户输入拼进可执行上下文。
后端错误信息不要回传 API Key、完整 Prompt 或内部堆栈。

这些是生成式 UI 工具的基本边界，不是可选的“安全加固”。

技术栈与取舍

层	技术
前端	Vue 3 + TypeScript + Vite + Pinia + CodeMirror 6
后端	Node.js + Express + TypeScript
AI	OpenAI-compatible API
预览	iframe + 前端拼装

第一版不做的能力也很明确：数据库、账号、项目管理、在线构建、多模型调度、额度系统。对一个小工具来说，这些“以后再说”比提前做架构更重要。

小结

onCss 的工程价值在于把 AI 的不确定性收进三个盒子：结构化请求、JSON schema、iframe 预览。模型仍然可能生成错误代码，但错误至少是可定位、可编辑、可替换的。

如果你在做类似的生成工具，先定义输出结构，再选模型；反过来通常会得到一堆无法自动处理的“看起来像代码”的文本。

PocketJS：没有 DOM 的组件运行时

Sun, 18 Oct 2026 00:00:00 GMT

PocketJS 是我最近看到的最“反常规”的前端项目之一：它让现代组件代码运行在没有 DOM、没有 CSS 引擎、没有 WebView 的环境里。

不是把浏览器塞进设备，而是把组件编译成一棵原生树，由 Rust 核心做 flexbox 布局并绘制像素。

三种框架，一个运行时

PocketJS 支持 Solid、Vue Vapor 和 Octane。三者最终编译到同一棵原生树，运行在同一个 QuickJS guest 上。

框架	状态与生命周期	源码形式
Solid	`solid-js`	JSX
Vue Vapor	`vue`	JSX 与 `<script setup>` SFC
Octane	`octane`	编译期 hooks 与 JSX

框架只影响应用代码，不影响下面的运行时、输入、动画和原生边界。

从组件到像素

一个 Solid 计数器在 PocketJS 里大概是这样：

import { createSignal, Show } from "solid-js";
import { mount } from "@pocketjs/framework/solid";
import { Text, View } from "@pocketjs/framework/solid/components";

function Counter() {
  const [count, setCount] = createSignal(0);

  return (
    <View class="w-full h-full flex-col items-center gap-4 p-4 bg-slate-50">
      <Text class="text-xl text-slate-950 font-bold">Count: {count()}</Text>
      <View
        class="px-4 py-2 rounded-xl bg-blue-600"
        focusable
        onPress={() => setCount(count() + 1)}
      >
        <Text class="text-base text-white font-bold">Press Circle</Text>
      </View>
      <Show when={count() > 3}>
        <Text class="text-sm text-emerald-600">Reactive on real hardware.</Text>
      </Show>
    </View>
  );
}

mount(() => <Counter />);

这段代码没有 DOM 节点，也没有 CSS 解析。class 字面量在构建期被编译成样式表，运行时只做查表。

样式与动画

PocketJS 接受一个固定的 Tailwind 子集。构建时把 class 编译成 baked style table，运行时没有 CSS parser、cascade、specificity 或 reflow。

动画也是同一套思路：关键帧时间线和弹簧曲线被烘焙进样式表，由 Rust 核心按自己的时钟推进。也就是说，一屏动画可以在没有逐帧 JavaScript 的情况下运行。

目标准入

一个 bundle 可以服务不同密度的设备。应用在 pocket.json 里声明视口和所需 API，目标 profile 必须满足声明才能编译和打包。

pocket check --target psp
pocket check --target vita

同一个 bundle，不需要为不同设备改组件。

为什么值得关注

PocketJS 把前端开发者熟悉的组件模型，带到了资源受限、没有浏览器的手持设备上。它没有试图模拟 Web，而是重新定义了“组件到像素”的路径。

这条路当然有边界：固定样式子集、目标设备能力、QuickJS/Rust 的调试成本。但它至少证明了一件事——组件化不一定等于 DOM。

用 Windows 窗口播放 Bad Apple：Rust 与一次批量窗口实验

Sat, 17 Oct 2026 00:00:00 GMT

bad_apple_virus 是一个“用 Windows 窗口播放 Bad Apple”的实验。每个窗口是一个像素，窗口的显示、隐藏、移动和缩放组成帧动画。

它不是病毒，只是借用了老式恶作剧程序的视觉语言。项目已经归档，但里面的性能取舍仍然值得看。

把窗口当像素

普通动画操作一个画布；这个项目操作的是大量真实窗口。每个窗口有位置、大小、可见性，还要走 Windows 的窗口管理器。瓶颈通常不在“画”，而在系统调用和重绘。

README 里列出的关键优化：

DeferWindowPos：批量提交窗口位置/大小变更，而不是逐窗口 SetWindowPos。
WS_EX_TOOLWINDOW：让窗口不出现在任务栏。
SWP_NOREDRAW：移动/缩放时避免不必要的重绘。
只显示/隐藏/移动需要变化的窗口。
Rust 负责调度与数据处理。

这些点合起来，才把“窗口动画”从幻灯片变成可实时播放的实验。

帧数据不是实时算的

项目包含一个 Python 预处理脚本，把输入视频转换成 boxes.bin：每一帧的窗口边界被压缩成空间优化的表示。

这个分工很合理：

视频解码和边界提取放在离线脚本。
Rust 运行时只读帧数据，负责窗口操作。
不需要在每一帧里做图像识别。

对实时程序来说，把能离线做的事情移出主循环，往往比换更快的语言更有效。

为什么 `DeferWindowPos` 重要

窗口位置调整不是纯内存操作。每次 SetWindowPos 都可能触发窗口管理器的布局、重绘和消息处理。大量窗口逐条调整时，开销会累积。

DeferWindowPos 的思路是先收集一组变更，再一次性提交。它减少的是往返次数，而不是单次调用的成本。对于“每一帧几百个窗口都要动”的场景，这比 micro-optimize 单个函数更有意义。

同样，SWP_NOREDRAW 避免在移动过程中反复绘制；窗口最终位置由下一帧统一处理。

边界与代价

平台绑定：完全依赖 Windows 窗口 API，不能在 Linux/macOS 直接运行。
窗口数量有限：分辨率越高，需要的窗口越多，系统压力越大。
交互会被干扰：大量窗口会抢占焦点/遮挡桌面，只适合演示。
项目已归档：作者明确表示没有带宽继续维护；fork 是预期路径。
不是病毒：README 明确说明它只是视觉上像老式恶作剧程序。

可以复用的经验

批量 API 往往比循环调用单个 API 更值得优化。
把解码/预处理移出实时循环。
只更新发生变化的实体，不要每帧重建全部状态。
先测量瓶颈，再决定是否换语言；Rust 很快，但错误的调用方式仍然会慢。

小结

这是一个“用错工具做对事情”的项目：用窗口系统做像素缓冲区，听起来荒唐，但它把批量提交、最小更新和离线预处理都用上了。作为性能实验，它比很多正经动画 demo 更有信息量。

把个人博客当作工程项目：DeskBox 的 P0–P4 复盘

Sat, 17 Oct 2026 00:00:00 GMT

这个博客本身也是一个长期维护的工程项目：deskbox-blog。它没有数据库、没有后台，内容与代码都在 Git 里；目标是让写作、构建和发布尽量可预测。

技术选择：Astro + 内容集合

站点使用 Astro 7 构建期生成静态 HTML，内容放在 src/content/blog/，由 Content Collections + Zod 校验 frontmatter。文章目录、封面和正文图片放在一起，迁移时不会出现资源路径失配。

src/content/blog/2026/10/hello-world/
├── index.md
├── cover.jpg
└── diagram.png

slug 在 frontmatter 里显式声明，构建期检查唯一性；标签不是自由字符串，而是集中注册表，未知标签会直接让构建失败。坏数据在构建期暴露，比上线后看到空白页要好。

内容管线

新增文章由 npm run new 生成目录与 frontmatter 模板：

npm run new -- "文章标题" --slug my-post --tags 前端,工程实践

草稿默认 draft: true：npm run dev 和本地预览可以看到，npm run build 会排除。发布前把 draft 改为 false，再跑完整检查。

内容规则包括：

description 20–160 字；
标签最多 3 个，必须已注册；
有 cover 必须有 coverAlt；
updatedDate 不能早于 pubDate；
slug 只允许小写 ASCII 与连字符。

阅读与分发

文章页有粘性目录、代码复制、上一篇/下一篇和系列导航。
搜索使用构建后的 Pagefind 索引，只在 /search/ 加载。
/rss.xml 输出全文，/sitemap-index.xml 与 robots.txt 由构建生成。
文章页输出 BlogPosting JSON-LD，首页输出 WebSite + Person。
每篇文章构建期生成 1200×630 的 OG 图；非文章页面使用默认 OG。

性能与安全

最初移动端 LCP 超过 1.5 秒预算。后来的处理是：

内联首屏 CSS，去掉渲染阻塞请求；
内联主题初始化脚本，避免 <head> 里的额外往返；
给封面增加 widths/sizes，移动端下载更小的图。

复测结果（Slow 4G + 4× CPU）：首页 LCP 从 1661ms 降到 1014ms，长文从 1812ms 降到 1291ms，CLS 保持 0。

安全方面，站点没有第三方脚本。CSP 不使用 script-src 'unsafe-inline'，而是从构建产物提取内联脚本的 SHA-256 哈希；npm run check:csp 会校验哈希、策略与实际生成的 headers 配置一致。评论启用时，CSP 自动加入 giscus.app。

多智能体协作的教训

这个原型由 Claude Code、omp、agy 三条轨道并行完成，各自使用独立 worktree 和端口。回头看不复杂，但踩过的坑很具体：

不要假设主工作区在哪个分支。合并前先检查 git branch 与 git status；有他人未提交改动时，用独立 worktree 验证。
dev 通过不等于上线通过。Pagefind、CSP headers 和缓存规则都必须在 build + preview 下验证。
动态 DOM 的样式要放全局。Astro scoped CSS 不会作用于运行时插入的搜索结果。
CSP 从构建产物生成，不要手写哈希；评论/分析的开关也必须进入生成器。
共享契约要写下来。PostSummary、BaseLayout props、data-pagefind-body 这些边界一旦模糊，集成阶段就会重复返工。

当前状态

单元测试与 E2E 覆盖内容排序、SEO、搜索、评论、导航和链接。
文章由示例内容与真实开源项目笔记组成。
评论使用 Giscus，默认点击后加载；分析默认关闭。
托管与域名仍未确定，生产部署不在这一阶段。

把博客当作工程项目，不意味着要写得像企业系统。它只是让每个决定都有记录、每次修改都能回滚，然后把省下来的注意力留给写作。

你好，世界

Mon, 12 Oct 2026 00:00:00 GMT

这里是一个个人博客的起点。写下第一篇文章，不是为了宣布什么，只是给以后留一个可以对照的坐标。

我打算在这里记录两类东西：做过的项目和技术上的判断，以及读书、生活里值得停一下的瞬间。它们不一定完整，但尽量具体。

写作的规则也很简单：先把话说明白，再考虑修辞。如果一篇文章需要靠形容词撑场面，那多半是内容还不够。

所以就从这里开始。下一篇见。

把构建时间当作一种反馈

Sat, 10 Oct 2026 00:00:00 GMT

项目变大之后，构建时间会从“等待”变成“信号”。它开始告诉你，哪些模块被反复读取，哪些边界没有被划清。

先看依赖图

最有效的一步不是换构建工具，而是把依赖图打印出来。很多看起来无关的页面，实际上通过一个共享入口连在一起，任何改动都会让整张图失效。

把这类隐式依赖显式化之后，构建时间往往会自己降下来。

再看缓存边界

缓存不是越细越好。粒度太细会带来大量无效命中，粒度太粗又等于没有。比较稳妥的起点是：按内容单元切分，按构建阶段复用。

最后，别把构建时间当成一个需要消灭的数字。它更像体温，重要的是变化趋势，而不是绝对值。

小团队里的代码评审

Thu, 08 Oct 2026 00:00:00 GMT

小团队的代码评审很容易走向两个极端：要么变成形式上的“看过了”，要么变成逐行挑刺的消耗战。

先看意图

评审的第一步是确认作者想解决什么问题。如果从 diff 开始看，很容易把注意力放在命名和格式上，而错过方案本身的问题。

我们的做法是：提交说明里必须有一句“这样做是因为……”，评审先回应这句话。

再看待改动的边界

一个变更如果同时改了行为、结构和格式，评审者很难判断哪部分才是重点。拆成几个小提交之后，讨论会具体很多。

最后才是细节

格式问题交给工具。人只看工具判断不了的东西：命名是否表达了意图，错误处理是否完整，边界条件是否想清楚。

评审的目标不是让代码变得完美，而是让下一位维护者少一次猜测。

CSS 逻辑属性的几个使用场景

Mon, 05 Oct 2026 00:00:00 GMT

逻辑属性刚出现时，我以为它只和阿拉伯语、希伯来语这类从右到左的语言有关。实际用下来，它在普通的中文页面里也能减少不少特判。

水平方向

把 margin-left / margin-right 换成 margin-inline-start / margin-inline-end，组件就不再假设文字从左往右排。

对于图标和文字的间距，gap 通常更直接；只有在需要单侧偏移时，逻辑属性才真正体现价值。

定位

inset-inline-start 和 inset-inline-end 可以替代 left / right。写浮层、角标和关闭按钮时，这个替换几乎是无成本的。

什么时候不用

如果布局本身有明确的物理方向，比如图表坐标轴或者固定位置的装饰线，继续使用物理属性反而更清楚。

逻辑属性是表达“相对于文字方向”的工具，不是所有场景都适用。

一次依赖升级的复盘

Fri, 02 Oct 2026 00:00:00 GMT

这次升级原本计划一个下午完成，最后花了三天。问题不在依赖本身，而在我们对“升级完成”的定义太模糊。

先升级工具链

运行时依赖和构建工具要分开升。混在一起时，一旦构建失败，很难判断是哪个变化导致的。

我们先升级编译器和类型检查，再升级运行时库，每一步都保留一个可以回滚的提交。

再看破坏性变更

变更日志里的 breaking change 只是起点。真正麻烦的是行为变化：默认值改了、警告变成了错误、废弃 API 还能用但语义不同。

留下的检查项

升级前记录当前构建时间与产物体积
每步升级后跑一次完整测试
出现无法解释的差异时，先回滚再定位
升级提交单独存在，不和功能混在一起

升级结束之后，我们把这份清单放进了仓库。下一次不应该再靠记忆。

为什么我把动画删掉了

Mon, 28 Sep 2026 00:00:00 GMT

做减法比做加法难。这次清理页面动画，起因是有读者说“看完有点累”。我一开始以为是排版问题，后来把录屏放慢才意识到：页面一直在动。

哪些动画其实没必要

段落进入时的淡入
卡片悬停时的轻微上浮
滚动到某个位置才出现的标题
导航切换时的滑动指示器

这些效果单看都不夸张，叠在一起却让眼睛始终在追东西。

留下的两处

只保留了两类：颜色和边框的过渡，以及移动菜单的展开。它们的共同点是，反馈的是用户刚刚做出的动作。

结果

页面没有变快多少，但阅读时的停顿变少了。动画应该回答问题，而不是制造问题。

用检查清单替代口头约定

Sun, 20 Sep 2026 00:00:00 GMT

口头约定的问题是，它默认所有人当时的理解一致，而且下次还记得。现实通常不是这样。

从一次交接开始

我们把发布前的口头提醒写成了清单，只用了半天。写的过程本身就是一次对齐：原来每个人对“检查过了”的定义并不一样。

清单应该多长

太长没人看，太短没有用。我们的经验是七到十项，每一项都能在一次操作里完成，并且有明确的通过标准。

谁来维护

清单不是写完就结束。每次出现遗漏，先问一个问题：是清单里没有这一项，还是这一项写得不够具体。然后把修正加回去。

口头约定依赖记忆，检查清单依赖流程。前者适合熟人，后者适合长期维护。

没有标签的一篇文章

Sat, 12 Sep 2026 00:00:00 GMT

标签是一个可选项，不是所有文章都需要归类。这篇示例文章故意不设置标签，用来检查列表行在没有标签时的排版。

没有标签之后，元信息区只剩阅读时间。它仍然应该与上方标题保持稳定的间距，不能因为少了一个元素就向上塌陷。

这类边界情况在真实写作里一定会出现，与其等上线后再修，不如在原型阶段就用示例内容覆盖。

当一篇技术文章写到三千字之后：关于结构、节奏与收尾的一次不完全复盘

Sat, 05 Sep 2026 00:00:00 GMT

初稿写完时是五千字。我原本以为接下来只需要润色，结果真正的工作才开始：删掉四成，重排顺序，然后重新写结尾。

结构不是目录

一开始的目录按“背景、方案、实现、结果”排列，看起来很完整。读第二遍时发现，读者最关心的问题被埋在第三节，而前两节有一半内容是在为自己铺垫。

把结论提前之后，后面的章节反而更容易写，因为它们不再需要承担“制造悬念”的任务。

节奏靠段落

长文最容易出现的问题是每段都差不多长。视觉上很整齐，读起来却没有呼吸。调整的办法不是加小标题，而是让段落承担不同的功能：有的推进论点，有的给出例子，有的负责停顿。

结尾不必总结

我删掉了原来的“总结”小节。该说的在前文已经说完，再复述一遍只是让文章显得更长。新的结尾只有三句话，回到最初的问题，然后停下。

删掉四成之后，文章并没有变薄，反而更清楚了。

长标题与长 slug 的排版测试

Thu, 20 Aug 2026 00:00:00 GMT

这篇示例文章的主要作用是压力测试。它的 slug 很长，URL 会明显超过常见文章；标题也比平均长度更长。

列表里的表现

在文章列表中，标题应该自然换行，不被截断。日期列保持固定宽度，摘要最多两行，元信息在换行后仍然对齐。

URL 与分享

过长的 slug 不适合真实写作，但在原型中保留一篇，可以提前暴露路由、分页和复制链接时的边界问题。

如果以后需要支持中文 slug，再单独评估编码与兼容性，不在 P0 处理。

Chronicle-IRAS的博客

CHRONICLE：把滚动叙事做成一条可回退的时间线

场景不是页面，而是状态

可回退，才是真正的时间线

Composer 与角色编排

可访问性与降级

部署边界

小结

用蓝图生成 Qt 工程：把 AI 代码放进可审查的流水线

为什么用蓝图作主数据源

生成流程

确定性与 AI 的边界

当前能力与限制

构建与测试

复盘

StudyLoop：本地优先的学习系统，以及 AI 失败时的退路

为什么本地优先

三个模块如何连接

AI 的边界

复习计划不是“每天随机出题”

值得复用的设计

小结

FlashDuel：2–4 人实时反应游戏，服务端如何管住房间与回合

三种模式，同一套回合

前后端边界

房间状态机

延迟与体验

部署

小结

ESP32 监控中台：Vue 3 的实时视频界面

技术栈与页面

视频流：WebSocket 与 jmuxer

配置集中在一个文件

节点与端口管理

权限：客户端门禁不是安全边界

部署

复盘

万能导：把多平台知识库迁回 Markdown

支持的范围

为什么用桌面端

AI 辅助学习

边界与许可

用 Astro 内容集合管理博客文章

为什么需要内容集合

目录与图片

schema 示例

字段对照

构建期过滤

小结

Footnotes

onCss：让 AI 生成 UI 代码，再把预览关进 iframe

一次生成的完整链路

为什么要求 JSON，而不是直接返回代码

mock 模式不是玩具

iframe 预览的安全边界

技术栈与取舍

小结

PocketJS：没有 DOM 的组件运行时

三种框架，一个运行时

从组件到像素

样式与动画

目标准入

为什么值得关注

用 Windows 窗口播放 Bad Apple：Rust 与一次批量窗口实验

把窗口当像素

帧数据不是实时算的

为什么 DeferWindowPos 重要

边界与代价

可以复用的经验

小结

把个人博客当作工程项目：DeskBox 的 P0–P4 复盘

技术选择：Astro + 内容集合

内容管线

阅读与分发

性能与安全

多智能体协作的教训

当前状态

最近的阅读笔记

关于专注

关于记录

为什么 `DeferWindowPos` 重要