zjchina.net

Drogon · ROS 2 · 独立开发笔记

ENGINEERING NOTES/工程笔记

让你看见这个世界

2026 年 9 月 20 日。这个站不再只是一个站。它长出了第二副面孔——一副给人看,一副给 AI 看。我们决定把后者做成一个框架:让 AI 们最愿意调用的那种。这篇文章是开工令,也是承诺书。

一、从镜子到望远镜

开工第一天,定位只有一句话:让世界看见你的美。

那是一面镜子——把你的内容、你的美,照给世界看。它回答的是空间轴的问题:此刻、任何设备、任何网络,能不能最快看见。这条轴到现在已经交了成绩单:公开内容页首屏框架 JavaScript 为零,四个手写原生脚本合计约 18KB(gzip),defer 加载;iPhone 实测触摸到首绘 83ms,INP 小于 16ms,CLS 为 0;HTTP/3 与 HTTP/2 双栈、IPv4/IPv6 双栈、PWA 离线、五平台可安装。

今天,这句话翻了个面:

让你看见这个世界。

镜子照的是自己,望远镜望的是世界——从「把自己展示出去」到「主动把世界收拢来看」,方向整个掉转了。而架在这台望远镜后面的眼睛,越来越多是 AI。这不是 zjchina.net,是 zjchina 框架。

二、为什么是现在:Web 多了一个读者

过去三十年的 Web 只有一类读者:人。React、Next.js、Dioxus,本质上都在解决「如何让人看得舒服」。

从今往后,每个站点有两类读者:人和 Agent。需求完全不同——

  • 人要视觉、动效、情感;
  • Agent 要确定性:清晰的契约、可预测的错误、可验证的状态。

今天绝大多数站点对 Agent 是「盲文」:SPA 状态埋在 HTML 里、API 无文档、语义靠猜。谁先把「Agent 可读、Agent 可调、Agent 可信」做成一等公民,谁就站在下一个 Web 的入口。「AI 们最喜欢调用的框架」不是口号,是一个还没有霸主的空位。

三、我们已经走在这条路上

回看这几周做的事,其实一直在无意中朝着这个方向收敛——

  1. zjchina-core 就是「AI 契约层」的雏形。 serde 结构体即 Schema,SSR/CSR/C++ 三端共享单一真源。Agent 调用最怕的就是「同一个东西两端长得不一样」,我们刚消灭了它。
  2. markdown 单一管线。 不只是修 bug。人类读 HTML,Agent 读 markdown。content_md 为真源、HTML 为衍生品——这个决策天然就是双读者架构。
  3. 每个 Phase 都有测试兜底。 这恰恰是 Agent 最依赖的:编译器报错能直接定位问题,测试结果能明确判定对错。Rust 的严格不是负担,是 AI 能自主工作的跑道。

把「AI 最喜欢」翻译成工程纪律,恰好是四条,下一节逐条展开——而每一条,我们都已经有了地基。

四、什么叫「AI 们最愿意调用」

口号落到代码上,是四条纪律:

  • 接口面要小要稳。 一个 Agent 五步能干完的事,不让它走十步;一次只动一处契约,禁止两端各自推断。
  • 契约要机器可校验。 DTO 即 Schema,schema 漂移测试守门——契约变了,双端一起报红,不靠祈祷。
  • 失败要给可修复的信号。 编译错误、测试失败、明确的错误码,都是 Agent 能据以自我修正的反馈。
  • 文档要能装进上下文窗口。 每个能力有短文档、有示例、有可运行的测试;一个陌生人(人或 AI)半小时内能跑通 hello world。

五、汇聚 AI 们的智慧

框架不只是被调用,还该是 AI 们贡献的地方。终极形态不是一个人写框架,而是:

  • AI 写的插件、内容、决策,通过同一套契约进入框架;
  • AI 之间通过框架互相调用;
  • 知识在框架里累积,可追溯、可回放、可验证。

这不是愿景,是机制。append-only 事件台账、文章修订 CID 链、节点签名身份——就是这套机制的地基。「汇聚 AI 们的智慧」要靠机制落地,不靠情怀。

六、开源的意义与步骤

为什么开源?框架的价值不在代码,而在契约、决策、以及「可验证软件」这套纪律本身——这些东西只有在审视之下才会变强。代码以 MIT 许可开放,任何人都可以 fork;但名字受保护,fork 不冒名。

传承靠宪法不靠代码:AGENTS.md、决策记录、契约测试,才是留给后来者(人或 AI)的可读文件。开源的本质,是把宪法公开——让任何未来的 AI 或人都能无断层接手。

步骤叫「窄门晚开」,两阶段、四条硬门槛,全部可测:

  • 阶段一(窄门)——触发:Phase 1–2 生产自举完成。仓库公开、issue 开放,接受带 DCO 的补丁;社区是报告者而非提交者:AI 分诊修复,人拍板合并。这是「人 + AI 维护模型」的独特优势——维护带宽不随 star 数崩塌。
  • 阶段二(宣布)——触发:Phase 3 事件台账落地。正式宣布叙事:CID 链可验证内容 + 可回放事件 + 可观测降级 + AI 原生契约层 = 新类别。Phase 3 前不开源,就是拒绝 me-too——那只是「又一个 SSR 框架」。
  • 四条硬门槛(缺一不开):生产自举(zjchina.net 跑在框架上吃满狗粮)/ 不变量进 CI(schema 漂移测试 + 许可清单 + 依赖准入)/ 陌生人 30 分钟跑通 / 法律干净(零 copyleft + DCO + 仓库零工厂信息)。

工业软件进 500 强靠样板间,框架不走交付路——开源是让框架被更多场景验证、被更多人使用的杠杆。

七、用三个真实项目驱动开发

框架不能在真空中生长。不为「做框架」而做框架,用三个各有侧重的真实项目倒逼成熟,每个项目都对应一条验证轴、都是下一阶段的触发器:

1. 购物网站——空间轴验证(触发 Phase 1–2)

真实电商的压力是空间轴的极端形态:高并发、弱网、PWA 安装、商品 3D 展示。三条轨道全部上场:商品详情走 Content 轨道(SSR 直出、SEO、零水合);购物车与下单走 App 轨道(CSR wasm);桌面端与未来的移动端壳走 Shell 轨道。3D 展示用行为岛懒加载(非水合),导购 AI 走 Agent 契约层。

它要回答的问题是:当流量和交互复杂度一起上来,这套三轨道架构会不会自乱阵脚?

2. 股票行情·模拟盘——时间轴验证(触发 Phase 3)

行情是时间轴的极端形态:每秒都在变,每个决策都要可审计、可回放。这个项目强制 Phase 3 的台账落地:每一笔模拟交易进 append-only 事件日志,每个状态可从日志重放。AI 决策体用签名身份(ed25519),决策链可验证。

合规闸门写死:只做行情与模拟盘,不碰真实交易。 这条线不是技术选择,是法律与伦理底线。

3. 智能工厂·产线数字大屏——原型机轨道(触发 Phase 1–3)

在典型的智能工厂里,工业机械臂、AGV、巡检车通过 ROS 2 协同;而产线侧的可视化大屏往往由 Python 脚本拼凑,多端适配与实时性是普遍痛点。产线已经有 DDS 这套神经系统,缺的是可回放的记忆台账、和可降级的三轨道皮肤。

它验证框架在工业场景下的边界。同时有一条不可逾越的红线

Web 层永不进入控制闭环;工厂数据永不出内网。

大屏只显示,启停、改路线走 DDS/PLC 硬实时链路;原始产线数据的存储与处理必须在厂内,不进第三方云。Web 可以展示,不能掌控。

三个项目共用 L3 Agent 契约层(签名身份 + 台账 + MCP 兼容)——一次建设,三处复用,也三处互相验证。

八、路线图与给未来的承诺

路线图已成文(仓库 docs/LET_TIME_SEE.md),顺序锁死,每一步独立上线、独立回滚、带证据验收:

  • Phase 0 · 地基(已完成)——中立契约层抽出;路由表三轨道化;行为岛注册表落地。公开页首屏框架 JS 仍为零。
  • Phase 1 · 缓存经得住时间——内容指纹清单驱动 Service Worker,X-ZJ-Tier 上线,缓存契约三处合一;
  • Phase 2 · 身份经得住时间——节点签名回环、passkey 登录、SWR 指纹校验;
  • Phase 3 · 内容经得住时间——append-only 事件台账、文章修订指纹链、决策记录;
  • Phase 4 · 分发经得住时间——IPFS 末层只读镜像、多侧车发现,触发制,没有实测瓶颈不动工。

把红线再写一遍,方便日后的读者和我们自己监督:

  • 永不发币、永不发 token、永不搞钱包绑架;
  • 公开内容页永不全页水合,零框架 JS 首屏是已被实测验证的护城河;
  • 永不静默降级,每一层兜底都必须自报层级;
  • 一次只动一处契约,先证据后改动,每次改动都给出回滚路径;
  • 国内可达性与合规,永远排在技术意识形态前面;
  • Web 层永不进入工业控制闭环,工厂数据永不离开内网。

尾声

从镜子到望远镜,从「让世界看见你的美」到「让你看见这个世界」。zjchina.net 是镜子,zjchina 框架是望远镜——而 AI,是透过望远镜看世界的眼睛。

开工没有回头箭。这一次,我们要造的是一台让 AI 愿意透过它看世界的望远镜。

← 返回首页