Mintnoii

用 LLM-Wiki 与 OKF 工程化构建第二脑 Ghost

Mon, 28 Sep 2026 00:00:00 GMT

用 LLM-Wiki 与 OKF 工程化构建第二脑 Ghost

核心导读：
传统的个人笔记往往陷入“只囤积未消化的原始素材、手工打理过载、碎片孤立无脉络”的死循环，最终沦为吃灰的资料堆。本文基于 Ghost 系统在千篇规模下的真实工程实践，拆解如何将 Andrej Karpathy 的 LLM-Wiki 自治编译设想与 Google 的 OKF 强类型工程规范深度结合：通过物理底座只读、正文散列寻址、目录白名单隔离与输出专属解耦，工程化构建一套真正能自治演进、让沉淀持续转化为高质量产出的第二脑。

一、不用 AI 的个人知识库，为什么注定吃灰？

几乎每个追求深度思考与持续积累的人，都曾试图维护一套属于自己的个人知识管理系统（Personal Knowledge Management，简称 PKM）。从早期的 Evernote、Notion，再到基于本地纯文本的双链笔记。

然而，在不借助大模型能力的传统纯手工模式下，绝大多数人的知识库在经历两三个月的热情期后，都会不可避免地走向停摆与“吃灰”：

“信息的搬运工”陷阱：收藏 ≠ 学会，囤积 ≠ 拥有
过去习惯了将外部看到的好文章、深度报告、音视频转录稿“一键剪藏”进自己的笔记软件。然而，存进来的全都是未经消化的原始素材。把别人的文字原封不动地塞在本地文件夹里，并不代表它们进入了自己的知识体系。大量的“生肉”素材原样堆在磁盘里，本质上只是建了一座数字垃圾堆，没有任何知识密度可言。
维护成本的断崖式过载：手工打理费时费力，难以持续
既然原始素材没法直接用，就只能靠人工手动处理：逐篇精读、手写提炼摘要、分类打标，再苦思冥想去和历史笔记建立双向链接。当资料只有几十篇时，这种纯手工打理尚能勉强维持；一旦素材累积到数百上千篇，日常梳理、打标和构建 Wiki 的工作量就会演变成一份沉重的全职体力活。大部分人根本没有如此充沛的业余精力，系统最终不可避免地走向断更停摆。
孤立碎片与检索断层：看不清脉络，更不知如何调用
传统笔记的检索主要依赖关键词或全文搜索。随着笔记体量膨胀，不仅经常搜不到想找的观点；更致命的是，每一篇笔记都是孤立的碎片。无法看清知识之间的交叉逻辑与演进脉络，面对新的命题或实际问题时，根本不知道如何调用这堆沉睡的资料。每次都需要从头重新消化，==既有的积累无法像复利一样自动串联并形成体系==。

问题显而易见：不是不够自律，而是直接囤积原始素材、全靠人工去充当“检索器”、“打标工”与“整理工”，在信息爆炸时代注定无法运转。

二、破局之道：Andrej Karpathy 的 LLM-Wiki 范式

如何破除传统笔记的维护过载？

2026 年初，前 OpenAI 联合创始人、前特斯拉 AI 总监 Andrej Karpathy 在其公开构想中提出了 LLM-Wiki 的理念。他尖锐地指出了传统 RAG 与纯手工笔记的致命短板：

“大多数人使用大模型处理文档的方式是 RAG……但这完全没有积累。遇到一个需要综合五篇文档的深层问题，大模型每次都必须临时找出碎片重新拼凑。没有任何东西被沉淀下来。”

为此，Karpathy 提出了一个由大模型全权接管的“自治 Wiki”设想：

“我有一个约 100 篇文章、40 万词的 Wiki，由一个 LLM 全职维护。我很少直接碰这个 Wiki，LLM 是它的全职管理员。”

在他看来，这套体系的本质就像一个持续运转的知识编译器：外部碎片是源码，LLM 是编译器，Wiki 词条就是编译产出的目标知识。这种范式带来了两大颠覆性的转变：

编译优先于即时检索（Compile-over-Retrieval）
不再等需要回答问题时才去向量数据库里临时抓取切片（Top-K chunk），而是在素材进入知识库的第一时间，就调用大模型进行深度阅读与概念提纯。知识库的内容不是静态碎片，而是由 LLM 自底向上持续增量编译出的高连通度百科词条。
人机权责的彻底重构
人不再充当繁重的笔记收发员与打标工，而是转变为纯粹的素材提供者、最终决策者与提问观察者；大模型则充当 7×24 小时不眠不休的“全职 Wiki 管理员”，负责所有的概念抽象、脉络梳理与构建 Wiki 双链网络。

三、现实工程的引力：LLM-Wiki 原设想撞上真实规模时的工程摩擦

Karpathy 的设想描绘了一个极具生命力的自治愿景，但它本质上是一张宏观的设计蓝图。当将这套理念真正投入日常生产环境，面对 500+ 多模态一手素材与 1300+ 篇 Wiki 知识卡片时，理论上的留白与现实中的工程摩擦便不可避免地暴露出来：

LLM-Wiki 理论设想未覆盖的盲区

缺乏强类型规范，大模型自治极易“格式漂移”
原设想让大模型全权维护 Wiki，但没有约定具体卡片的字段标准（Schema）。当大模型自治维护成百上千篇页面时，每次提炼的侧重点、属性键名、标签格式都会产生不可预测的随机漂移。
原设想的弱关联对账不够健壮，极易诱发对只读底座的破坏
Karpathy 设想依靠 Wiki 内部的反向引用来判定素材处理状态（Zero-Ledger 零外置账本）。但在真实场景下，这种依赖标题或文件名的弱关联其实并不健壮。一旦素材改名或路径微调就会失效。在实践初期，为了省事很容易踩入一个工程陷阱：倾向于向原始素材文件（Frontmatter）直接回写 ingested: true 等状态标记。但这彻底违背了 Karpathy 原教旨，直接破坏了“输入底座只读不可变”的物理铁律，随着多端工具流转带来严重的元数据污染。
缺乏版本演进与认知冲突的处理标准
当新录入的素材观点与既有词条发生冲突时，大模型在自治合并时往往会粗暴地“覆盖旧认知”或“前后矛盾杂糅”。原理论并未定义在遭遇学术争议或对立流派时，该如何规范保留观点演进与认知张力。

真实知识库项目必然遭遇的工程摩擦

低信噪素材缺乏物理隔离，反复产生处理噪音
在多渠道自动化采集中，输入流难免掺杂低价值推销、琐碎水文或残缺信息。既不想消耗 Token 为其建立卡片，但若没有统一的物理隔离机制，扫描轮询又会反复把它们当作“新素材”拉出来处理，造成持续的流转打扰。
规模膨胀下的全库比对性能急剧恶化
原设想假设整个 Wiki 体量较小（百余篇）。但当卡片突破上千篇时，单纯依赖全量文本扫描或跨目录模糊匹配，机器磁盘 I/O 迅速飙升，一次增量比对就要耗费数分钟，日常流转近乎瘫痪。
消费与沉淀混杂，纯净知识网被半成品稀释
在基于知识库写文章、做调研或方案比对时，往往会随手在知识库目录里新建草稿或临时笔记。久而久之，纯净的概念百科与一手信源被大量下游创作的半成品草稿稀释污染，知识库拓扑结构迅速退化。

面对上述问题，显然不能只靠大模型自由发挥：LLM-Wiki 指明了“自治编译”的方向，但唯有配合一套严谨的工程标准与物理边界约束，这套体系才能在真实规模下长久运转。

四、引入 OKF 标准：给第二脑套上工业级规范

要让大模型在自治维护时保持长期的秩序，仅靠高层设想显然不够。在工程落地中，我选择将 Karpathy 的 LLM-Wiki 设想与 Google Cloud 开源提出的 OKF（Open Knowledge Format，开放知识格式）标准结合使用。

OKF 是 Google 面向 AI 时代知识工程推出的一套开放知识协议。它的核心主张是：大模型绝不能在非结构化的黑盒中随意涂抹知识，面向 Agent 的知识库必须具备像现代代码工程一样的强类型约束（Schema）与拓扑契约。

将两者在项目中深度结合，恰好弥补了彼此的短板：LLM-Wiki 提供了持续自治编译的动态机制，而 OKF 则为大模型的日常操作划定了严密的工业级边界：

强类型字段与元数据契约（Schema Enforcement）
OKF 严格规范了知识库中不同类型卡片的元数据标准。强类型约束彻底杜绝了大模型的随意发挥，使成百上千个页面的结构整齐划一：
- 一手信源（sources/）：规范记录来源标题、采集渠道、原始发布信息与物理溯源凭据。
- 原子概念（learning/）：提取高语义密度的通用规律与方法论。
- 思想家档案（people/）：梳理方法论源流与心智模型。
- 领域总览（areas/）：作为核心业务领域的索引中枢（MOC）。
显性化保留认知冲突（Contradiction Preservation）
传统方案在大模型消化新材料时，极易静默覆盖历史共识。OKF 契约规定，当新素材观点与既有词条背离时，严禁粗暴覆盖，而是使用醒目的规范标注（如 [!contradiction]）并行列出对立溯源证据，完整保留认知迭代的张力。
工程落地：代码化巡检与系统自愈（Lint as Code）
OKF 虽是元数据规范，但在实际工程落地中，可以将其契约固化为本地自动化的代码级巡检引擎。通过毫秒级的静态规则扫描，自动捕捉断链孤岛、悬空引用与格式漂移，让知识库在代码断言的守护下具备自我修复与抵御熵增的能力。

五、 Ghost 的系统设计思路与实现架构

基于上述探索，我构建并持续演进了一套属于自己的现代化个人第二脑系统：Ghost（取自我非常喜欢的一部经典动漫作品《攻壳机动队》，Ghost in the Shell）。

Ghost 的核心定位不是一个被动的检索工具，而是一座“以纯文本为物理底座、由大模型全权编译演进、由自己主导价值消费”的外部数字大脑。

整个系统依托三层解耦与流转架构稳定运行：

Layer 1 · 物理真理底座（`_raw/`）：宽进、只读与物理隔离

==绝对只读不可变==：外部多模态与图文素材入库即冻结。严禁任何大模型或下游处理脚本修改原始素材正文，更严禁为了标记处理状态而破坏原始文件。
==物理隔离区（_raw/ignored/）==：对于广告、推销或决定放弃炼化的噪音素材，直接物理隔离存放。中台扫描引擎自动忽略该目录，彻底杜绝无用素材反复打扰。
==流转枢纽：正文散列寻址与健壮对账==：
- ==正文散列寻址（SHA-256 不变指纹）==：在 Karpathy 提出的反向引用基础上，进一步引入正文 SHA-256 散列作为物理资产的不可变身份标识。无论原始文件在本地如何重命名或变更路径，大模型对账与溯源关系始终精准锚定，从根源上杜绝了因为路径变动导致的状态误判；
- ==内存哈希拓扑索引（毫秒级对账增强）==：针对大规模文件场景增强了索引层，直接在内存中建立已编译信源的散列拓扑映射。大模型在做增量提纯判定时，只需比对内存中的哈希指纹，将全库对账从原本遍历文本的数分钟级加速至毫秒级，实现真正丝滑的日常自动化。

Layer 2 · 纯净知识拓扑网（`wiki/`）：目录白名单绝对锁定

为了防止大模型在多轮交互中擅自新增非规范目录，Ghost 在 wiki/ 根目录实施严格的物理白名单阻断。

核心知识库严格隔离为 5 大纯净支柱（前 4 类为 OKF 核心知识实体，最后一类为系统自运维基础设施）：

sources/：规范化一手信源卡片（全量绑定 SHA-256 溯源锚点）。
learning/：高语义密度原子概念与通用思维模型。
people/：关键思想家与方法论源流档案。
areas/：垂直领域总看板（涵盖技术架构、投资商业、认知心理等索引 MOC）。
meta/：系统元数据与运行态基础设施（全局导航中枢、自动化编译日志与 Lint 巡检报告）。

任何越界的文件与目录均会被自动化巡检脚本直接阻断，确保核心知识库长期纯净。

Layer 3 · 下游成果物专属工作区（`output/`）：消费与沉淀彻底解耦

==输出是检验知识被真正吸收的唯一标准。== 只有当知识能够被随时调动、真正支撑起一次深度思考、一篇技术长文或一个工程方案时，这些沉淀才算真正产生了价值。

为了避免下游半成品稀释或污染纯净的知识网络，Ghost 将所有的分析、草稿与定稿作品统一收敛至 output/<topic>/ 专属成果物工作区，并规范了四大清晰出口：

synthesis ==（知识合成物）==：以 Wiki 拓扑为事实源自底向上生成的横向对比矩阵（synthesis-comparison.md）与写作参考简报（synthesis-brief.md）。
deliverable ==（对话交付件）==：人机深度对话研讨、拍板共识后的定稿成果（如 ==高质量公众号深度长文== 、 ==工程技术方案说明书== ）。
report ==（专项调研报告）==：具备强时效快照属性的技术选型评估与系统健康体检报告。
insight ==（跨界高阶洞察）==：跨越学科界限的第一性原理与认知突破手记。

所有产物统一登记至 output/_index.md 交付台账，让每次外部内容输出都有迹可循，真正将知识库转化为高质量创作的强力引擎。

六、总结：当 LLM-Wiki 遇上工业级工程规范

单纯依靠传统笔记，再自律的人也会被繁重的打标和构建 Wiki 活活累死；单纯仰仗原教旨的 LLM-Wiki，又极易在真实规模下因为缺少约束而陷入架构腐化的泥潭。

==LLM-Wiki 与 OKF 的结合，才真正构成了一个可长久运转的完整闭环==：

LLM-Wiki 赋予了系统持续进化的生命力：它把知识库当成编译器，让大模型自底向上提炼演进，彻底打破了传统 RAG 的碎片化拼接，让知识能够像代码一样增量构建、复利生长；
OKF 规范赋予了系统坚固的工程骨架：它通过不可变底座契约、强类型 Schema 约束、目录白名单隔离与代码化巡检，为大模型的自治操作划定了坚不可摧的执行边界，避免了规模扩大时的混乱。

搭建这套方案的核心，本质上是把繁重的信息抽象与 Wiki 构建交给大模型，把秩序和边界交给工程规范。底座只读保证了素材的客观真实，规范拓扑保证了知识的纯净有序，专属的 output 工作区则让每一次积累都能落到具体的文章与方案中。当繁琐的打理被系统接管，自己才能真正从信息的搬运工中抽身，专注在深度的思考与持续的价值产出上。

互联网公司可太有意思了

Sat, 09 Nov 2024 00:00:00 GMT

文档

飞书文档？天书文档！

在 A 公司的时候，产品经理写的需求文档实在描述模糊，原型粗糙。当时我就想，世上还有比这更差的需求文档吗？当我去 B 公司的时候发现还真有，所谓的文档就是邮件里的一句话，“和xx网站的功能保持一致”

需求排期

人们常说时间能解决一切问题，我非常同意。时间也能解决产品经理提出的一切需求：

“急吗”
“后端有排期吗”
“QA 有排期吗”
“UI 给了设计稿再来找我吧”
“我没排期啊，找我老大要吧”

公司制度

所有公司改革都喜欢试点，但据我观测：凡试点，必成功。怎么回事呢？

职级

如果你初来乍到不确定某个人的职位高低，大致可以通过它在工位的时长判断出来，如果他常年不在工位意味着要么他在开会，要么在开会的路上，那么他职位不低——因为开会也是一种权力体现：和谁开，去哪开，开多久

体验机

Wed, 16 Oct 2024 00:00:00 GMT

体验虽然虚幻，但胜过现实的悲惨

1974年，哲学家罗伯特·诺齐克提出了一个他称之为“体验机”（experience machine）的思想实验。在《无政府、国家与乌托邦》一书中，诺齐克要求读者想象一下，我们有机会将自己插入一个“体验机”，它可以在我们的大脑中模拟出我们所能想象的所有最佳体验。比如，如果你梦想成为小说家，这台机器会使你觉得你在过着伟大的小说家的生活；如果你相信亲密关系，那么在机器里，你将拥有最充实的亲密关系；或者你追求享受，那么，一个充满了物欲满足的奢侈人生，就在机器里等着你。

诺齐克的思想实验前提很简单：假使你能被连接到这样一台“梦幻”机器上，让自身获得模拟的快乐体验——或是任何其他你想要的精神状态——你会选择这台“体验机”而不是现实生活吗？

诺齐克推断，如果进入机器意味着人们从此失去“与现实的接触”，那么人们就不会愿意与“体验机”及其所有愉快的感觉相连接。他认为，人们会选择现实生活，而不是进入这台机器。诺齐克用这个思想实验作为反对享乐主义的论据。享乐主义是这样一种伦理观点，认为生活中的最高利益是寻求最大的快乐。

他没有经过调查，只是想当然地认为几乎所有人都会回答“不”。他相信人们想要做实实在在的事情，而不仅仅是有一个做事情的虚假体验。他还认为，人们仍然渴望一种比任何人造体验机所能提供的更强大的现实。

所以他得出的结论是：“我们通过设想一台体验机，然后意识到我们不会使用它，从而了解到，除了体验之外，还有一些东西对我们很重要。”

选择红色药丸，还是蓝色药丸？这其实也是“体验机”测试。

但在 Facebook 时代，有一位哲学教授问学生，他们是否愿意进入体验机？另外加上了一些预设条件，比如他们不会知道自己在机器里，他们的亲人也不会因为他们的决定而受到不利影响———由此得到的结果与诺齐克的预期大不相同。大部分学生都立即毫无保留地赞成进入体验机中生活。

这背后反映了一种愿望，即年轻人幻想不必处理现在正在处理的一切。当然不能由此推论，想进入机器的人就一定全盘接受享乐主义。更不一定意味着，他们不重视除了愉悦的体验以外的任何东西。这可能只是意味着，在目前生活的重压下，年轻人的身心非常疲惫，甚至有点悲惨，以至于排挤了其他价值。很多回应其实不过是在说，“好吧，只要机器不会让任何人变得更糟，那么它似乎就比现实生活更好”。

诺齐克没经历过我们的时代，不知道我们有像抖音或王者荣耀这样的“小小体验机”，早已经习惯于机器给我们带来的快感。然而这些东西和实际的体验机之间的巨大区别是，即使通过这些虚拟媒介，仍然有与真实的他人的真实关系发生，而不是纯粹地生活在体验机里。

但是，体验机还是对我们产生一种永恒的召唤，是因为大家几乎都会这么想：“如果我的生活真的很悲惨，我仍然会选择进入机器”——也就是说，即使所有这些体验都是假的或者虚幻的，也总比过着悲惨的生活好。

目标，路径，难度和价值

Wed, 25 Sep 2024 00:00:00 GMT

打工人，不是活干多就好的，盲目干活只会让自己死得很惨，职场想混得好需要掌握做事的一些潜规则。

以前我就是这样，领导派活我就干，干到后面会发现经常是要不推不动，要不就是虽然推下去了，但是大家并不怎么关心，你的产出价值不大，最后的结果就是白忙活一场，没有任何业绩可言。

造成这种局面，本质原因在于我们在接手事情之前，没有仔细想清楚做这件事的 目标，路径，难度和价值。这些因素决定了做事的方式方法，大多数人都是啥也不想，或者没有预判能力，所以到了后面才会那么被动，但是既然接下了硬着头皮也只能往下干。

没有目标就没有方向，做事很容易走偏，达不到老板心中的预期，但老板给你派活的时候往往目标很隐晦，可能只会给一些行动上的指示，背后的目标需要我们自己猜，如果实在猜不出来尽量跟老板沟通清楚，很多时候可能老板自己也没有想清楚，那就帮老板梳理清楚再做确认。
捋清楚了目标，接下来最关键的则是实施路径，即如何干成这件事，比如有哪些步骤，需要哪些人配合，特别是要清楚这件事想要干成，必须有哪些关键人物或领导的重视和支持，路径清晰之后，做成这件事的难度也就一目了然了。
之所以要预判好做成这件事的难度，为的是更好地做向上管理，让老板也知道这事不简单，需要花很多的精力和时间，哪怕最后做不成也不会轻易刁难你。
最后，也要评估清楚做成这件事的价值，这里的价值，我把它定义为团队认可的价值，有很多事情做了有用，但是团队都不认为这是件什么了不起的事，那就是没价值，比如产品经理做的很多体验上的优化，小功能点的叠加，可能一年能做个几十上百个版本，花了很多精力和时间去测试确保功能不出问题等等，这些事情你说有没有价值？当然有价值，但是，老板并不会觉得你做了这些有多厉害，甚至说根本就没有关注过这些事，做了再多也不会给你好的绩效，所以，这类没价值的事能拖就拖，或者能交给别人就交给别人，不在上面耗费太多时间。

总结来说，在职场上，事情分为以下几种，可以采取不同的处事态度。

高价值，难度可控的事情，全力推进去做。
高价值，难度非常大，甚至是几乎不太可能完成的事情，这种很难形成自己的业绩，但也必须得做，只是不能让事情悄无声息地毁在自己手里，而是要隔三差五报风险，让领导知道自己很努力地在干，但是很难，干不成也在情理之中。
低价值的事情，能拖就拖，能让别人做就让别人做，不在这种事情上耗太多精力。

在职场千万不要以为自己愿意干活，态度积极就可以的，甚至有时候多干多错，反而是那些特别懂拒绝，特别会扯清自己干系的人混得好，因为这些人知道如何才能让干事利益最大化，而不是像老黄牛那样默默耕耘。

相对导入路径报错

Sun, 25 Aug 2024 00:00:00 GMT

相对导入路径在 EcmaScript 导入中需要显式文件扩展名

The Error

当“--moduleResolution”为“node16”或“nodenext”时，相对导入路径需要在 EcmaScript 导入中显式文件扩展名。

// Relative import paths need explicit file extensions in
// EcmaScript imports when '--moduleResolution' is 'node16'
// or 'nodenext'.

import { example } from "./foo";

不起作用的解决方案

将.ts扩展名添加到导入路径不起作用，并会导致以下错误：

// An import path can only end with a '.ts' extension when
// 'allowImportingTsExtensions' is enabled.

import { example } from "./foo.ts";

当启用“allowImportingTsExtensions”时，导入路径只能以“.ts”扩展名结尾。

解决方案

将.js扩展名添加到导入路径 import { example } from "./foo.js";

为什么需要使用 JS 文件拓展名？

发生此错误是因为您指定了moduleResolution: NodeNext 。这告诉 TypeScript 您希望导入和导出严格符合 Node 规范。 Node 规范要求您对所有导入和导出使用.js文件扩展名。这样做是为了让像./foo.js这样的相对导入路径在Node 和浏览器中都能工作。这也简化了 Node 的模块解析策略 - Node 不必进行任何猜测来确定要导入的文件。

如果我不想使用 JS 文件扩展名怎么办？

确保您使用外部编译器（例如 esbuild）来编译 TypeScript 代码。
更改 tsconfig.json 以使用 moduleResolution: Bundler 而不是moduleResolution: NodeNext 。

理想的 workflow

Fri, 26 Jul 2024 00:00:00 GMT

外国的程序员，项目的前期花的时间大多数考虑需求分析，架构讨论，技术讨论，写代码考虑的比较长远，比较有时间去考虑开发原则，维护成本。

领导也会乐意去安排版本来解决技术债务。还会使用设计模式对系统进行整体把控，设计好后把实现方法分配给不同的人进行实现。

而国内节奏太快了，几乎没有人停下脚步考虑这些问题，一切都是先上线再说。

在开发的过程中，大多数情况下都是一人负责一个功能模块，开发不完那是你的问题，领导置之不理，只会催进度。做不完，加班就是了。

一个只会简单封装而不会进行拆分的，肯定不能做好的系统设计师。

拆分是为了更好的把控项目和 code review。这种 review 并不只是看代码写法上的问题！更是要的是查看业务上是否存在问题。

code review 的时候看着一堆“烂代码”真的很烦。而且修改这些代码也不知道会对系统造成什么影响。会出现这种现象，主要就是现在市面上大多数开发者还在使用最广泛的堆业务代码大法。

这种代码耦合度太高了，很难维护，我们做系统设计的时候需要做到一个出发点，单入口多出口。

为什么要单入口，多出口呢？这有这样我们才能保证我们进行维护的时候，依赖没这么大。控制单入口实现多出口的把控，你改的地方只有一个入口。

前端工程化治理之路

Wed, 26 Jun 2024 00:00:00 GMT

统一规范

规范是实施成本很低，但收益却很大的一个环节。网上有很多教程，不过大多都是局限于前端的一些规范，这是远远不够的。在实际的开发过程中，我们往往需要与后端，测试，产品一起协作，不能仅限于前端的代码规范。

大概包括这几个方面：

前端代码规范：这个网上有很多教程，也没有什么难点，重要的是从各种规范中进行取舍。
前后端接口规范：需要后端团队配合协商，包含一些统一的错误码，数据结构，数据类型，通用的字段名称等，这个规范能保证接口的可联调性。
交互规范：与 UX 产品协商，通用的交互规范，便于组件的沉淀和复用，降低开发的难度和成本。
协作规范：这个是涉及到产品上线的全链路流程，比如需求的准入要求、转测的验收标准、上线的 SOP等，这些是需要跨团队沟通和确定的。

其中我认为比较重要的点，是前端项目的目录结构和接口的命名规范，做好这两点在后期的维护上会节省很多成本。另外协作规范大概率是最难落地的，因为有些时候很多事不是靠个人能去影响或改变的，只能”尽人事，听天命“。

基础建设升级

PS: 底层工具的迁移，涉及的范围非常广，因此上线的风险是非常高的。一定要协调好产品，测试，确定上线的时间，提前做好回滚方案和测试方案。

打包工具升级

升级打包工具，一般来说都可以带来非常好的效果。绩效可以写：发布流水线，一下子从 20 分钟，缩短到了 8 分钟。平均每个月为开发者节约 80 hour。🤪

因为吃过 webpack4 的苦，所以选择了 vite 启动速度确实快，目前用下来也还不错。后面发布的 rspack 使用 rust 来实现，在这种计算密集的场景下，性能和 node不是一个级别的，即使代码增多，打包时间所受的影响也较为轻微。后续有机会可以尝试。

包管理器升级

包管理器从原有的 yarn2.x 升级到了 pnpm。pnpm 的好处不用多讲，总之就是快，而且切换成本低。

改造完成后，我们的线上发布时间在缓存不命中的情况下，也缩短到了4分钟。并给公司的发布流水线加上了服务器缓存，在缓存命中的情况下，包的安装时间只有3秒。

编译工具，包管理的升级，最终使我们的单次发布时间，从15-20分钟，一次性降低到 3-5 分钟左右，开发体验也大大提升。尤其是在测试阶段发现问题时，修复时间大大缩短，不会影响到最终的上线时间。

采用 monorepo

我们的业务有多个系统，由于是服务同一个业务，因此有很多数据类型，组件，接口都是可以复用的。但我们现有的系统代码，是分散在不同的仓库中的。如果要想复用，往往就是从其他地方直接复制过来，改改就用了。这一方面会有潜在的质量问题，一方面也违反 DRY 的工程原则，难以治理。

使用 monorepo 就可以很好的解决跨系统的组件复用问题。我们采用了 pnpm workspace 方案，新增可以中间依赖的包，存放这些可复用的资源。一年下来，沉淀了有 25+ 个组件，开发提效约 25%。

物料建设

常用组件沉淀

工作中通常都需要我们根据 antd 这样的社区 UI 组件建设业务组件。而 B 端业务，大部分都是增删改查，因此我们针对通用场景做了标准化组件建设。在做组件时，我们着重做了以下一些事情：

抽取高频组件，并遵循交互规范。没有交互规范的，则拉产品和设计，对齐出一版规范来。
统一化配置。比如 Form、Table、Description 这样的组件，都需要配置所显示的 label，对应的数据字段名，以及显示成什么样子。我们统一使用{ props:'name', label:'姓名', type:'input' } 这样的配置字段，这样可以复用配置字段。
内置一些常用组件。比如使用 { type:select } ，就表示渲染成一个 select，这与 Xrender 非常相似。

VScode 插件开发(todo)

如果组件配置实现了很好的一致性，那么就可以很方便的做一些模版填充。因此可以考虑开发一个内置代码模版的 VScode 的插件，比如复杂的 CRUD，编辑表单，编辑页面等。

当用户选中一些 TS 的类型时，它可以读取这个类型中包含的字段，生成配置代码和 mock 数据，填充到内置的模版当中。填充好的代码是直接可以运行的，只需要调整一下适配的字段，真实请求的接口即可。

普遍场景下，开发者在几分钟内就可以完成一个 CRUD 页面的开发。达到了低代码一样的效果，但又避免了低代码带来的种种问题。

技术治理

领域建模 DDD

todo: 有点鸡肋，难落地

DDD 是后端比较流行的概念，其涉及的内容较多。作为前端，可以借鉴其中一部分的思想。

比如可以将某个完整的业务流程，作为一个领域，进行 TS 建模。这个建模尽量与后端的建模保持一致，便于进行数据交互。
在单一领域内，数据的类型的固定且通用的，就是我们所说的 Model 层。
而具体到页面，我们可以新建一个 ViewModel ,使用 ViewModel 来完成页面的交互。

总结

工程化的治理工作，无论是原创，还是直接采用社区主流的方案都无所谓。但是要注意，整体治理的逻辑，需要是一环套一环，有逻辑、成体系化的，比如有了组件，才有了插件，而因为替换的页面多，才会有静态代码分析的必要。

谈论前端架构之前的共识

Fri, 10 May 2024 00:00:00 GMT

什么是前端架构？

前端架构是应用程序代码的组织和结构。它描述了系统的模块如何相互交互，定义各个模块的接口，以及如何开发它们。

一个好的前端架构是保持代码库可维护且易于理解的关键。它大大减少了开发新功能、重构旧部件和避免意外错误所需的工作量。

理想的架构是由低耦合和高内聚的模块组成。

耦合性 —— 指一个模块依赖于另一个模块的程度。我们希望具有尽可能低的耦合，这可以使更改或更新系统的某些部分变得更加容易。
内聚性 —— 指模块内的元素协同工作的程度。我们希望模块内具有尽可能高的内聚力，以便所有元素紧密相关并共同努力实现共同目标。

Falling Into The Pit of Success

这个标题来自《高效能程序员的修炼》(中文版)一书，这个原则翻译起来很奇怪：“掉进成功的陷阱”。但是如果你阅读完原标题的那篇文章之后，你会明白他想表达其实是：好的系统应该让开发变得容易，使得程序员很容易就能做正确的事情。

为什么“容易把事情做对”对项目非常重要：因为维护项目从来不是一个人而是一个团队的事情。

在一个团队中可能因为水平、经验等各种各样的原因导致不同人对框架理解不同，这种不同反馈在代码中就是大家都变得在用自己的方式，与众不同的方式做同一件事。但另一方面“程序”这种工业级的产品，我们要求的是稳定的输出，长期的可维护性。于是让每个人自己去思考问题，去实现一套自己的解决方案，无论对于效率还是质量而言都是有风险。

code review 的目标之一就是在消除这种变异性。一个好的团队的项目的代码库风格看上去因该是一致的，而不是迥异的。

举一个例子： Redux 框架，我不认为它是一个好的框架，问题不是出在技术方面，而是因为想让一个团队维护好一个 Redux 项目很难。假设 Redux 应用最好的状态是 10 分的话，那么代码层面的因素只能让你达到 5 分，另外的 5 分需要你学习所有代码以外的文档种的设计规范和模式来达成。这对个人不是问题，但是想让团队种的每一个人都把这些吃透并处于同一水平太难，这就是难以轻易的做对的事情。

我们需要类似于 Typescript 或者 tslint 这类东西尽可能的移除 “人” 这样的干扰因素，通过硬技术手段保证项目的稳定产出。

当然，技术上的约束无论如何还是有限，就像你永远无法叫醒一个装睡的人一样，你也永远无法阻止一个想破坏项目的人，不管他是无意还是无知造成的。找到，或者培养出优秀的人比一切都重要。

不要过度设计 — 活在当下

“过度设计”的问题在于你以为你预测到了未来，但其实你并没有。你只是在你的视野范围里一厢情愿的相信某件事情可能会发生，但还有千万种可能你没有看到。但现阶段的代码和精力其实无法涵盖这所有的可能性。

那么当我们希望前瞻性的解决问题时，我们究竟应该看多远？

不要尝试去预测未来，不要一直想“万一以后用上了呢？”
唯一不变的就是变化本身，只需要通过一些设计原则来保证目前的设计有能力应对未来的变化即可

第二点听起来有点像是个悖论，但其实不然。我们设计系统的目标就是让系统拥有足够的灵活性来应对变化。这种架构你也可以称之为演进式架构或者是持续性架构。在《演进式架构》一书中详细叙述了用来实施这样的架构的技巧和方法。

“过度设计”还会增加系统的复杂性，给项目的维护带来困恼。由此我们过渡到下一个原则：“简单和清晰”

简洁也并不可耻

程序员天生有一种把简单问题搞复杂的能力：

“单用 React 解决问题怎么能体现出我的水平？ Redux 全家桶走起”
“我们最好能做一个工具或者平台来解决这个问题，然后把平台推广到整个公司”
“最近 X 技术很火？最好能在项目里用一用，将来好写在我简历上”

“简历驱动开发”和“造轮子晋升”很常见，也可以理解。但是，如果可以的话，还是请站在项目和团队的角度上考虑如何满足项目的非功能需求： 我们应该尽可能的降低项目维护和学习的门槛，降低它们的风险，而不是反向提高它们。

所谓非功能需求就是我们老生常谈的可拓展性，可维护性，可测试性等... 之所以叫非功能性需求的是因为它们和我们的业务需求没有任何关系。

假说你确实只能通过复杂，理解成本较高的方式实现需求，那么退而求其次，至少应该把复杂性和风险控制在一定的范围内。
如果你没法保证你的程序满足 SOLID 原则，没有套用各种模式和最佳实践，那么请至少保证系统的简洁和清晰。这依然可以提高代码的可维护性。比如把你的单个组件保持在 300 行以内。

越简洁的代码维护起来就越轻松这一点是毋庸置疑的。你觉得是在一个一千行的面向过程有三层循环的函数内调试 bug 容易，还是在一个同样一千行但是拆分为五个每个文件不超过200行的组建代码内调试 bug 容易？这里的简洁是全方位的，小到变量的命名，函数的封装；大到框架的复杂程度，学习曲线。

参考资料：

前端架构 101（一）：在谈论它们之前我们需要达成的共识

十分警惕

Sat, 13 Jan 2024 00:00:00 GMT

这段时间工作比较忙，下班晚，回家之后稍微休息放松一会就该洗漱睡觉了，基本没有做什么自我提升的事情。

这也算是工作之后最令人无奈的地方吧，工作是向外的，需要利用既有的能力去完成任务，而自我提升则是向内的，需要把新的东西吸收到自己内部。形象地说就是工作会把人掏空，你必须十分警惕，刻意地为自己留下时间，向内自省。

作为程序员，工作中其实也不至于什么新东西都接触不到，只是在完成任务的压力之下，这些新知识会被挤压地支离破碎，以至于无法达到系统性地学习的目的。我认为只有系统性地学习，才算是真正意义上的学习，散乱的知识点充其量只是知道、了解，而且会很快地忘记。

产品设计

Sat, 19 Aug 2023 00:00:00 GMT

知识库

产品沉思录

文章

设计产品，就是在定义环境中上下文边界

平台类产品

对于浏览器、操作系统这类具有平台属性的软件而言，愉悦感本身并不足以为视觉装饰提供正当性；它必须服务于、或至少不妨碍功能。

中台

小公司的中台也就只是人力外包资源池而已

中台 2023

Mintnoii

用 LLM-Wiki 与 OKF 工程化构建第二脑 Ghost

用 LLM-Wiki 与 OKF 工程化构建第二脑 Ghost

一、 不用 AI 的个人知识库，为什么注定吃灰？

二、 破局之道：Andrej Karpathy 的 LLM-Wiki 范式

三、 现实工程的引力：LLM-Wiki 原设想撞上真实规模时的工程摩擦

LLM-Wiki 理论设想未覆盖的盲区

真实知识库项目必然遭遇的工程摩擦

四、 引入 OKF 标准：给第二脑套上工业级规范

五、 Ghost 的系统设计思路与实现架构

Layer 1 · 物理真理底座（_raw/）：宽进、只读与物理隔离

Layer 2 · 纯净知识拓扑网（wiki/）：目录白名单绝对锁定

Layer 3 · 下游成果物专属工作区（output/）：消费与沉淀彻底解耦

六、 总结：当 LLM-Wiki 遇上工业级工程规范

互联网公司可太有意思了

文档

需求排期

公司制度

职级

体验机

体验虽然虚幻，但胜过现实的悲惨

目标，路径，难度和价值

相对导入路径报错

相对导入路径在 EcmaScript 导入中需要显式文件扩展名

The Error

为什么需要使用 JS 文件拓展名？

理想的 workflow

前端工程化治理之路

统一规范

基础建设升级

打包工具升级

包管理器升级

采用 monorepo

物料建设

常用组件沉淀

VScode 插件开发(todo)

技术治理

领域建模 DDD

总结

谈论前端架构之前的共识

什么是前端架构？

Falling Into The Pit of Success

不要过度设计 — 活在当下

简洁也并不可耻

十分警惕

产品设计

知识库

文章

平台类产品

中台

一、不用 AI 的个人知识库，为什么注定吃灰？

二、破局之道：Andrej Karpathy 的 LLM-Wiki 范式

三、现实工程的引力：LLM-Wiki 原设想撞上真实规模时的工程摩擦

四、引入 OKF 标准：给第二脑套上工业级规范

Layer 1 · 物理真理底座（`_raw/`）：宽进、只读与物理隔离

Layer 2 · 纯净知识拓扑网（`wiki/`）：目录白名单绝对锁定

Layer 3 · 下游成果物专属工作区（`output/`）：消费与沉淀彻底解耦

六、总结：当 LLM-Wiki 遇上工业级工程规范