• 一、 账本里的真相
• 二、 机架内互联: 被高估的“全光”刚需
• 三、 集群光互连: 缺乏爆发逻辑
• 总结

在科技投资的宏大叙事里，华尔街最擅长的就是为每一个微小的技术迭代包装出数千亿美元的“总体可寻址市场（TAM）”。在这一轮 AI 算力狂欢中，“光连接（Optical Interconnect）”无疑是被聚光灯打得最足的概念之一。从“算力爆发必带来光模块无处不在”到“CPO技术重塑数据中心”，激进的研报不断刺激着投资者的神经。

然而，剥开这些被精心包裹的幻象，回到最底层的服务器成本拆解（BOM）与物理工程现实，我们会发现一个被刻意忽略的真相：光连接概念正面临着严重的过度炒作。在 AI 硬件的权力版图中，它只是一个缺乏溢价资本的边缘角色。

一、 账本里的真相

AI 硬件的绝对核心只有 GPU 和 HBM 华尔街乐于展示光连接设备出货量的同比翻倍增长，但他们很少会让你看一眼一台标准 AI 服务器的真实成本构成。

以目前全球数据中心标配的 8 卡 NVIDIA H200 服务器为例，其整机建议零售价（MSRP）约为 $350,000。当我们把这张账单拆细，其价值链的真实垄断格局一目了然：

• 绝对核心：8 块配置了 141GB HBM3e 显存的 H200 GPU 核心采购成本高达 $256,000，直接吞噬了整机 70% 的资金。
• 边缘分润：包含了高速网卡、光通信接口在内的整个网络与 I/O 组件，在单机整机中的采购成本仅占 7%。

在 AI 硬件中，任何不能直接贡献算力（FLOPS）或显存带宽（HBM）的组件，都是外围设备。英伟达凭借核心芯片与 CUDA 生态卷走了全产业链近一半的纯利润，而光连接设备在整机中只是极其边缘的硬件，由于缺乏生态护城河，其价值根本不存在爆发的基础。

二、 机架内互联: 被高估的“全光”刚需

华尔街的叙事逻辑是线性外推：速度越快，就越需要光。但他们没有告诉你的是，在短距离互联中，铜连接已经取得巨大突破：

• 目前基于纯铜互联的 NVLink 6 已经能够实现单卡双工 3.6TB/s、机架级一二百 TB/s 的惊人带宽，至少在目前已经相当够用。

• 光通信听起来快，但它必须在传输时进行 2 次光电转换，这个过程会引入不可避免的物理延时，光电转换也有能耗、发热问题。铜连接工艺成熟、技术稳定、直接传电信号，近乎零延迟，性价比极高。

对于下游客户（如云服务商）而言，机架内通过现有的铜互联方案已经足够快、足够稳。这就像当年的 5G 概念和 IPv6 升级一样——技术指标固然完美，但在老的 4G 和 IPv4 依然够用且极其省钱的背景下，用户缺乏迫切的升级动力。

三、 集群光互连: 缺乏爆发逻辑

当然，不能否认光连接的价值。在超大集群的构建中，光连接具有铜缆无法替代的优势：

• 打破距离限制：当万卡、十万卡集群需要跨机柜、跨机房甚至跨建筑连接时，铜缆在超过 2-3 米后信号会发生剧烈的物理衰减。此时，必须通过光纤通信来突破距离限制。
• 但这不会造就价值爆发：光连接在多机柜集群中确实有刚性场景，但它无法改变其在整体数据中心资本开支（CapEx）中仅占个位数的边缘地位。更重要的，这类光通信设备缺乏像核心算力芯片那样的技术专利垄断和软件生态锁死，随着代工厂规模化量产与良率提升，其 ASP（平均售价）必然被下游客户持续压低。

总结

华尔街制造“光连接”的增长神话，过度炒作光连接概念。我们必须看清底层的硬核逻辑：AI 硬件的绝对重心始终在核心芯片（GPU）与高带宽显存（HBM）身上。光连接在 AI 硬件中必然有一席之地，但也仅仅是一席之地，不会成为下一个英伟达。

• 一、 铁王座：CUDA 凭什么成为英伟达的护城河？
• 二、 只是致敬，并非抄袭：ROCm 与 CUDA 的底层异同
• 1. 硬件控制原理：高度一致
• 2. 软件生态构建：闭源黑盒 vs. 开源标准
• 三、 悖论：AI 正在摧毁毁 CUDA 的围墙？
• 1. 自动重写：生成式 AI 抹平了代码迁移成本
• 2. 降维打击：大一统中间件（Triton）的崛起
• 四、 反击：英伟达的防御与应对措施
• 1. 从“卖芯片”彻底转变为“卖数据中心系统”
• 2. 恐怖的“摩尔定律”速度压制（时间窗口战）
• 五、 展望：双雄逐鹿的终局走向
• 英伟达（NVIDIA）：向系统级平台与云计算巨头演进
• AMD：在推理（Inference）与企业级市场迎来历史性爆发
• 总结：AI 没有毁灭英伟达，但 AI 会解放硬件市场

在硅谷的商业史上，很少有一家企业能像英伟达（NVIDIA）这样，凭借一套软件生态筑起数千亿美元的商业高墙。这堵墙的名字叫 CUDA。

长期以来，业界形成了一个牢不可破的共识：买英伟达是为了它的硬件，而留下来是因为它的软件。

然而，历史往往充满了反讽。随着由英伟达亲手引爆的生成式 AI 浪潮走向纵深，一个意想不到的“回旋镖”正加速飞回：AI 越强大，重写和迁移 CUDA 代码的门槛就越低。英伟达引领的 AI 革命，正在反向削弱它自己最引以为傲的软件护城河。

这是一场关于编译器、中间件、开源力量与人工智能自我进化的硬核博弈。

一、 铁王座：CUDA 凭什么成为英伟达的护城河？

要理解城墙是如何倒塌的，首先要明白它是如何建立的。

在 2006 年之前，GPU（图形处理器）只是单纯的游戏显卡。如果科学家想要用 GPU 运行数学矩阵运算，必须把数学公式伪装成“图形渲染指令”喂给显卡，编写过程极其痛苦。

2006 年，英伟达推出了 CUDA（统一计算设备架构）。它的核心贡献在于：允许程序员直接使用 C/C++ 语言来编写控制 GPU 的并行计算代码。

为了推广 CUDA，黄仁勋做出了一个在当时看来极其疯狂且亏损巨大的决定：强制让英伟达出厂的所有显卡（包括千元级的GeForce游戏显卡）都必须内置 CUDA 模块。事实证明老黄的这一决策极具远见！

这一决定为英伟达创造了一个价值数千亿的护城河，带来了两个决定性的商业结果：

1. 人才基础绝对垄断：过去 18 年里，全球无数的高校学生、科研人员和独立开发者，只需用自己的游戏电脑就能零门槛学习 CUDA。当这批人毕业进入大模型公司或云巨头企业时，他们只会使用 CUDA。
2. Day-0 生态锁死：全球几乎所有的 AI 开源论文、创新大模型（如 Transformer、Diffusion、Sora），在 GitHub 上发布的第一天，默认代码全部基于 CUDA 编写。

英伟达借此收起了超过 75% 的高昂硬件毛利，史称 “英伟达税”。企业想要更便宜的硬件？对不起，你离不开 CUDA。

天下苦英伟达久矣，苍天已死，ROCm当立！

二、 只是致敬，并非抄袭：ROCm 与 CUDA 的底层异同

为了打破英伟达的垄断，AMD 在 2016 年推出了开源的 ROCm（Radeon Open Compute platform）。从技术实现原理来看，两者的底层逻辑呈现出“异曲同工”，但在软件栈的构建思路上却“背道而驰”。

1. 硬件控制原理：高度一致

在最底层的芯片控制上，CUDA 和 ROCm 都基于 SIMT（单指令多线程） 架构。两者的核心概念在物理硬件上几乎是一一对应的：

• 英伟达的 Thread≈ AMD 的 Work-item
• 英伟达的 Warp（32线程）≈ AMD 的 Wavefront（波前，32/64线程）
• 英伟达的 Block（线程块）≈ AMD 的 Work-group

因此，无论是 CUDA 还是 ROCm，优化矩阵运算和控制显存缓存的数学逻辑在本质上是互通的。

2. 软件生态构建：闭源黑盒 vs. 开源标准

两者的真正差异在于编译器和代码的生成机制：

• CUDA 的 NVCC 编译器：英伟达采用全自研且闭源的 NVCC。它将代码编译成一种私有的虚拟中间语言 PTX，再通过闭源驱动实时翻译成特定显卡的机器码。其内部的数学加速库（如 cuDNN、TensorRT）经过了 18 年的黑盒调优，外界无法窥探。

• ROCm 的 LLVM 生态（开源公路）：AMD 没有从头自研编译器，而是直接拥抱了工业标准的开源编译器框架 LLVM。AMD 开发了 HIP（可移植异构接口） 技术，作为代码的桥接层。

AMD 的战略很明确：通过 HIP 提供一个“一键翻译工具（hipify）”，试图让开发者把现有的 CUDA 代码自动翻译成 HIP 代码，从而实现“一次编写，到处运行”。

然而，在过去几年中，ROCm 的市场份额依然极低。其原因不在于硬件参数，而在于迁移成本的不可承受之重。早期的 ROCm 充满了编译 Bug、文档缺失、且由于缺乏类似英伟达的群众基础，企业为了将 CUDA 迁移到 ROCm，需要雇佣极其昂贵的系统级工程师进行手动调优，排查诡异的编译器错误。在分秒必争的 AI 竞赛中，没有公司愿意承担这种时间成本。

直到生成式 AI 的爆发，彻底改变了博弈的底层规则。

三、 悖论：AI 正在摧毁毁 CUDA 的围墙？

英伟达引以为傲的 AI 技术，正在成为其软件护城河最致命的“特洛伊木马”。这种蚕食主要通过两个路径发生：

1. 自动重写：生成式 AI 抹平了代码迁移成本

过去需要一个顶级专家团队耗时数月才能完成的“CUDA 到 ROCm/HIP”的代码重写与调优工作，现在正在被大语言模型（如 Claude 3.5、GPT-4o）以分钟级的时间彻底抹平。

现代 AI 编程大模型对底层的抽象语法树（AST）和 GPU 显存对齐有着完美的理解。AI 能够轻松识别 CUDA 代码中的专有算子，不仅能进行语法替换，还能根据 AMD 的硬件特性自动重写出高度优化、无 Bug 的 HIP 算子。

这构成了科技史上最讽刺的商业闭环：

英伟达售卖昂贵芯片 ➔ 科技巨头购买并训练出强大的生成式 AI ➔ 巨头用这个 AI 自动将 CUDA 代码重写迁移为 ROCm ➔ 巨头大规模转向采购便宜的 AMD 芯片 ➔ 摆脱英伟达

2. 降维打击：大一统中间件（Triton）的崛起

比 AI 自动写代码更致命的，是 AI 底层基础设施本身的架构演进——以 OpenAI 主导的 Triton 语言为代表的中间件迅速崛起。

在过去，深度学习框架（如 PyTorch）的底层需要针对英伟达编写大量的 CUDA 算子。而 OpenAI 发布的 Triton，是一种极简的、基于 Python 的开源编译器。它的目标是让普通程序员写出 Python 级别的简易代码，由 Triton 编译器自动去处理底层的并行和内存管理。

最关键的是：Triton 在设计之初，就同时开发了 NVIDIA 和 AMD 的双后端。

当 OpenAI、Meta 等大模型厂商逐渐将自家的核心模型从直接调用 CUDA 转向通过 Triton 编写时，底层的硬件开始变得完全透明和可替换。英伟达精心构筑的 CUDA 软件墙，正在被 Triton 这种中间件从内部逐步“瓦解”。

四、 反击：英伟达的防御与应对措施

面对软件护城河被 AI 和开源生态反向侵蚀的危机，英伟达的竞争策略已经发生了重大位移，他们正在将防御阵线从“单卡软件”推向更难被攻破的物理极限。

1. 从“卖芯片”彻底转变为“卖数据中心系统”

当单卡的软件壁垒逐渐被抹平时，英伟达开始在超大规模集群的网络互联上加高壁垒。

• 大模型训练现在已经进入万卡、十万卡时代，芯片之间的通信延迟比单卡算力更重要。

• 英伟达通过私有的 NVLink 协议、NVSwitch 芯片以及收购 Mellanox 获得的 InfiniBand（IB）网络技术，将上万张显卡织成一整个极其高效的“超级大脑”。这种万卡级别的物理网络拓扑、高频通信软硬件的极限整合，是单靠大模型“重写几行代码”绝对无法跨越的物理硬实力。

2. 恐怖的“摩尔定律”速度压制（时间窗口战）

英伟达正在采用商业史上罕见的高强度研发节奏，将硬件迭代速度提升至一年一代（从 Hopper 到 Blackwell，再到 Rubin 架构）。

即使 AI 能完美、零成本地将 CUDA 代码迁移到 AMD 的硬件上，如果英伟达新一代硬件的绝对性能依然能拉开对手一代以上的差距，那么理性的企业为了抢夺模型上线的关键时间窗口（Time-to-Market），依然不得不乖乖向英伟达奉上高额的溢价。

五、 展望：双雄逐鹿的终局走向

随着软件壁垒的消融，AI 芯片竞争的下半场，正在从过去的“生态垄断战”逐步回归到最纯粹的“硬件性价比、功耗比以及大规模网络互联能力”的物理对决。

英伟达（NVIDIA）：向系统级平台与云计算巨头演进

英伟达的短期地位依然难以撼动。虽然单卡 CUDA 的壁垒在降低，但它凭借全栈的数据中心网络（NVLink）和一年一代的恐怖迭代速度，依然会牢牢占据最顶尖、最追求极致性能的超大规模 AI 训练市场（AI Training）。英伟达未来的角色将更像是一个“AI 基础设施的超级总承包商”。

AMD：在推理（Inference）与企业级市场迎来历史性爆发

对于 AMD 而言，这是历史上最好的红利期。随着全球大模型逐渐从“训练阶段”走向“大规模商业落地推理阶段”，市场对算力的需求正在从“不计成本追求极限性能”转向“追求极致的每美元性价比和功耗比”。

在 PyTorch、Triton 的加持以及 AI 自动迁移工具的普及下，ROCm 的软件劣势正在被快速拉平。AMD 的 Instinct 系列芯片凭借更大的显存容量和高性价比，将极大程度地蚕食云巨头、传统企业级私有化部署的推理算力市场。

总结：AI 没有毁灭英伟达，但 AI 会解放硬件市场

这场由英伟达亲手点燃的 AI 圣火，在不久的将来，会解除在其他硬件厂商身上的 CUDA 枷锁，让整个芯片行业重新回到了以物理性能与创新效率为核心的良性竞争赛道上。这算不算一个美好的愿望？！（Doggy）

• 在线加密工具
  • How to
• 1. 接收方准备公钥
• 发送方加密信息
• 接收方解密信息

在线加密工具 <入口>

How to

1. 接收方准备公钥

发送方加密信息

只要发送方没有更换公钥，该公钥可以一直使用。只需更新明文信息，点击加密按钮即可生成新的秘文。

接收方解密信息

只要不刷新页面，可以持续解密信息。

• 大型代码库的 Claude Code 最佳实践：构建层级化知识库
  • 引言
  • 核心原则：渐进式披露
  • 三级层级结构
    • 第一层：项目根目录（全局上下文）
    • 第二层：模块/领域（战略上下文）
    • 第三层：叶子节点/组件（战术上下文）
  • AI 友好内容的编写规范
    • 1. 明确而非习惯用语
    • 2. 使用"要/不要"列表
    • 3. 引用具体文件路径
    • 4. 保持精简
  • 层级化 vs 扁平化：对比
  • 实施步骤
    • 第一阶段：根目录
    • 第二阶段：核心模块
    • 第三阶段：复杂组件
    • 第四阶段：让 Claude 协助
  • 总结

大型代码库的 Claude Code 最佳实践：构建层级化知识库

摘要：在大型代码库中高效使用 Claude Code 的核心在于"渐进式披露"原则。通过构建三级层级化知识库，让 AI 在需要时获取恰到好处的上下文，避免 token 浪费和上下文混淆。

to English

引言

AI 辅助编程工具日益普及，开发者面临新挑战：如何在大型代码库中高效使用 Claude Code。在根目录放一个庞大的 README 并非良策——token 浪费、上下文混淆、维护困难。

本文介绍一种层级化知识库最佳实践，通过三级文档结构，让 Claude Code 在正确时机获取正确信息。

核心原则：渐进式披露

渐进式披露（Progressive Disclosure）：在根目录提供高层规则，随着 AI 深入子目录，逐步提供更具体的"为什么"和"怎么做"。

Claude Code 原生识别 CLAUDE.md 文件。我们将此模式扩展为层级化方法，让文档结构与目录树对齐。

三级层级结构

第一层：项目根目录（全局上下文）

文件位置：/CLAUDE.md

定位：项目"宪法"，定义技术栈、核心命令、不可违背的标准。

示例内容：

## 构建命令
- 生产构建：pnpm build
- 开发模式：pnpm dev

## 测试命令
- 单元测试：pnpm test:unit <文件>
- E2E 测试：pnpm test:e2e

## 代码规范
- 仅使用函数式组件
- 禁止 default exports
- 样式使用 Tailwind CSS

## 架构概述
- Next.js 单体仓库
- 共享逻辑位于 /packages/shared

第二层：模块/领域（战略上下文）

文件位置：/src/features/billing/CONTEXT.md

定位：解释代码无法揭示的业务逻辑和隐性数据流。

示例内容：

## 领域逻辑
本模块处理 Stripe 支付集成。

## 数据流
所有支付必须先触发 webhook-handler，再更新数据库。

## 安全要求
- 禁止在前端暴露 Secret_Key
- 使用 /api/stripe 中的代理进行后端调用

## 依赖关系
- 依赖 UserStore 进行税费计算
- 与 OrderService 双向同步

第三层：叶子节点/组件（战术上下文）

文件位置：/src/components/DataGrid/NOTES.md

定位：解释"陷阱"和技术债务。

示例内容：

## 性能注意事项
- 使用 react-virtualized 进行虚拟滚动
- 禁止移除 rowHeight 属性，否则在 Safari 上会崩溃

## 已知问题
- 排序切换与 API 存在竞态条件
- 解决方案：使用 isLoading ref 进行防抖

## 待重构
- [ ] 将排序逻辑提取为独立 Hook
- [ ] 替换已废弃的 componentWillReceiveProps

AI 友好内容的编写规范

1. 明确而非习惯用语

❌ 错误：Just run the tests
✅ 正确：Use npm run test

AI 对明确指令响应更好，避免开发者"行话"。

2. 使用"要/不要"列表

AI 对否定约束响应极佳：

## 类型规范
- ❌ 不要使用 'any' 类型
- ✅ 类型 truly 不明确时使用 'unknown'
- ✅ 优先使用 TypeScript 严格模式

3. 引用具体文件路径

让 AI 知道"真相"在哪里：

## 数据模型
- 主 Schema 定义在 /src/db/schema.ts
- 类型导出在 /src/types/index.ts

4. 保持精简

单个上下文文件不超过 50 行高密度信息。超过 10KB，AI 可能浪费过多 token。

层级化 vs 扁平化：对比

实施步骤

无需一次性完成。采用渐进式方法：

第一阶段：根目录

1. 创建 /CLAUDE.md
2. 定义技术栈、构建命令、代码规范

第二阶段：核心模块

1. 识别 3-5 个核心业务模块
2. 为每个模块创建 CONTEXT.md
3. 描述数据流、安全要求、依赖关系

第三阶段：复杂组件

1. 识别存在技术债务或"陷阱"的组件
2. 创建 NOTES.md 记录已知问题和解决方案

第四阶段：让 Claude 协助

使用 Claude Code 本身帮助生成文档：

# 让 Claude 分析模块并生成 CONTEXT.md
claude "Analyze the billing module and create a CONTEXT.md 
        that explains the data flow and security requirements"

总结

层级化知识库的核心价值：

1. 节省 token：AI 仅读取相关上下文
2. 提高精确度：特定规则作用于特定范围
3. 易于维护：小文件贴近代码，更新成本低
4. 可扩展：随项目增长自然扩展

实施时从根目录 /CLAUDE.md 入手，逐步向下扩展。记住：文档的价值在于被使用，而非被写完。

参考资料

• Claude Code 官方文档
• Progressive Disclosure in Software Design

• Best Practices for Large Codebases with Claude Code: Building a Level-Structured Knowledge Base
  • Introduction
  • Core Principle: Progressive Disclosure
  • The 3-Tier Hierarchy
    • Tier 1: Project Root (Global Context)
    • Tier 2: Module/Domain (Strategic Context)
    • Tier 3: Leaf/Component (Tactical Context)
  • Best Practices for "AI-Friendly" Content
    • 1. Be Explicit, Not Idiomatic
    • 2. Use "Do/Don't" Lists
    • 3. Reference Specific Files
    • 4. Keep It Small
  • Hierarchical vs. Flat: Comparison
  • Implementation Steps
    • Phase 1: Root Directory
    • Phase 2: Core Modules
    • Phase 3: Complex Components
    • Phase 4: Let Claude Help
  • Summary

Best Practices for Large Codebases with Claude Code: Building a Level-Structured Knowledge Base

Abstract: The key to efficiently using Claude Code in large codebases lies in the principle of "Progressive Disclosure." By building a three-tier hierarchical knowledge base, AI can access just the right amount of context when needed, avoiding token waste and context confusion.

中文版

Introduction

As AI-assisted programming tools become ubiquitous, developers face a new challenge: how to use Claude Code effectively in large codebases. Placing a massive README file at the root is far from optimal—it leads to token waste, context confusion, and maintenance difficulties.

This article presents a hierarchical knowledge base best practice, using a three-tier documentation structure to ensure Claude Code receives the right information at the right time.

Core Principle: Progressive Disclosure

Progressive Disclosure means providing high-level rules at the root, then offering increasingly specific "why" and "how" details as AI drills down into subdirectories.

Claude Code natively recognizes CLAUDE.md files. We can extend this pattern into a hierarchical approach, aligning documentation structure with the directory tree.

The 3-Tier Hierarchy

Tier 1: Project Root (Global Context)

File Location: /CLAUDE.md

Purpose: The "Constitution"—defining the tech stack, core commands, and non-negotiable standards.

Example Content:

## Build Commands
- Production build: `pnpm build`
- Development mode: `pnpm dev`

## Test Commands
- Unit tests: `pnpm test:unit <file>`
- E2E tests: `pnpm test:e2e`

## Code Style
- Functional components only
- No default exports
- Use Tailwind CSS for styling

## Architecture
- Next.js monorepo
- Shared logic in `/packages/shared`

Tier 2: Module/Domain (Strategic Context)

File Location: /src/features/billing/CONTEXT.md

Purpose: Explaining business logic and invisible data flows that code alone won't reveal.

Example Content:

## Domain Logic
This module handles Stripe integration.

## Data Flow
All payments must trigger the `webhook-handler` before updating the DB.

## Security
- Never expose Secret_Key to the frontend
- Use the proxy in `/api/stripe` for backend calls

## Dependencies
- Depends on UserStore for tax calculations
- Bidirectional sync with OrderService

Tier 3: Leaf/Component (Tactical Context)

File Location: /src/components/DataGrid/NOTES.md

Purpose: Explaining "gotchas" and specific technical debt.

Example Content:

## Performance
- Uses react-virtualized for virtual scrolling
- Do not remove the `rowHeight` prop or it will crash on Safari

## Known Issues
- Sorting toggle has a race condition with the API
- Workaround: use `isLoading` ref to debounce

## TODO
- [ ] Extract sorting logic into a standalone Hook
- [ ] Replace deprecated componentWillReceiveProps

Best Practices for "AI-Friendly" Content

1. Be Explicit, Not Idiomatic

❌ Wrong: Just run the tests
✅ Right: Use npm run test

AI models respond better to explicit instructions. Avoid developer "jargon."

2. Use "Do/Don't" Lists

AI models respond exceptionally well to negative constraints:

## Type Safety
- ❌ Don't use 'any' types
- ✅ Use 'unknown' if the type is truly ambiguous
- ✅ Prefer TypeScript strict mode

3. Reference Specific Files

Let AI know where "The Truth" lives:

## Data Models
- Master schema defined in `/src/db/schema.ts`
- Type exports in `/src/types/index.ts`

4. Keep It Small

Individual context files should be under 50 lines of high-density information. If a file exceeds 10KB, AI may waste too many tokens reading it.

Hierarchical vs. Flat: Comparison

Implementation Steps

You don't have to write all of this at once. Adopt a progressive approach:

Phase 1: Root Directory

1. Create /CLAUDE.md
2. Define tech stack, build commands, code conventions

Phase 2: Core Modules

1. Identify 3-5 core business modules
2. Create CONTEXT.md for each module
3. Document data flows, security requirements, dependencies

Phase 3: Complex Components

1. Identify components with technical debt or "gotchas"
2. Create NOTES.md documenting known issues and workarounds

Phase 4: Let Claude Help

Use Claude Code itself to help generate documentation:

# Ask Claude to analyze a module and generate CONTEXT.md
claude "Analyze the billing module and create a CONTEXT.md 
        that explains the data flow and security requirements"

Summary

The core value of a hierarchical knowledge base:

1. Saves tokens: AI reads only relevant context
2. Improves precision: Specific rules apply to specific scopes
3. Easy maintenance: Small files stay close to code, low update cost
4. Scalable: Grows naturally with the project

When starting, begin with /CLAUDE.md at the root, then expand downward. Remember: The value of documentation lies in being used, not in being finished.

References

• Claude Code Official Documentation
• Progressive Disclosure in Software Design

• 先睹为快
• 执行命令
• 总结

Linux shell script 是我最喜欢的脚本之一，历史悠久，底蕴深厚，shell script 几乎是内核的一部分，托 POSIX 标准的福，你可以在任何 Linux 系统中使用它。但是编写 shell script 体验并不太好，各种奇怪的语法、没有类型检查、孱弱的数组支持，有时候排查很久的问题，仅仅是错误的使用引号、或者多了一个空格。

我很喜欢造轮子，曾打算写一个高级语言，可以编译成 shell script 执行，即使是一些简单的语法糖，也能很大程度提升 shell script 用户的幸福感。前几天发现一个项目 Amber 已经做了这些工作，试用了下还不错，语法类似 Ecmas 或者 js，支持 Text、Num、Bool、Null 和 [] 数组，可以直接编译成 shell script，直接拿到任何 shell 中执行，没有任何移植性困扰。

先睹为快

参考官网的安装指导，只需要一行命令：

curl -s "https://raw.githubusercontent.com/Ph0enixKM/AmberNative/master/setup/install.sh" | bash

请确保你的系统已安装了 curl、bc， 安装以后就可以使用 amber 命令。 下面是一个简单的例子：

let fruits = ["apple", "banana", "grape"]

fun show_opt(fruits) {
    loop index, f in fruits {
        echo "{index}: {f}"
    }
}

show_opt(fruits)

将上面的代码保存为 test1.ab, 执行它

~/test $ amber test1.ab
0: apple
1: banana
2: grape

只要你有任何一种变成经验，很容易明白 amber 的基本语法。

上面的 amber 脚本等效的 shell 如何呢？我们可以将 amber 脚本编译为 shell 脚本。

amber test1.ab test1.sh

相比直接执行 amber 脚本，只需要增加一个参数指定编译输出的脚本文件名即可。test1.sh 看起来这样：

__AMBER_ARRAY_0=("apple" "banana" "grape");
__0_fruits=("${__AMBER_ARRAY_0[@]}");
function show_opt__0_v0 {
    local fruits=("${!1}")
    index=0;
for f in "${fruits[@]}"
do
        echo "${index}: ${f}"
        let index=${index}+1
done
};
show_opt__0_v0 __0_fruits[@];
__AMBER_FUN_show_opt0_v0__9=${__AMBER_FUN_show_opt0_v0};
echo ${__AMBER_FUN_show_opt0_v0__9} > /dev/null 2>&1

相比之下，amber 脚本真的是相当人性化。

执行命令

shell 最强大的能力在于可以方便的调用已安装的命令。amber 也具备这样的能力，而且提供了良好的异常处理能力。

基本语法是

$your cmd$ failed { exception handler }

两个 $ 之间可以是任何有效的 shell 命令，failed 是 amber 的关键字，表示指令的异常处理。

为了正常使用异常机制，异常所在代码要么位于 main block，要么在函数中。amber 可以指定 main 作为脚本入口。

main {
    let file_name = "1.txt"
    let cmd = "cat"
    let file_content = ${cmd} {file_name}$ failed {
        echo "{file_name} not exist"
        fail
    }

    echo file_content
    echo "done"
}

这段代码的尝试获取 1.txt 的内容，如果这个文件不存在就报错退出，否则打印文件内容。

指令可以是任何字符串，比如例子中的命令由 cmd 和 file_name 变量拼接生成。 的标准输出可以直接赋值给变量，获取指令输出非常方便。当使用 调用指令时，必须指定异常处理，可以通过 failed 关键字指明之后的代码块用作异常处理。fail 关键字用于抛出异常。

还有一种简化的一场处理方式，上面代码可以稍作调整:

    let file_content = ${cmd} {file_name}$?

相当于

    let file_content = ${cmd} {file_name}$ failed {
        fail status
    }

我很喜欢 ? 的设计，表示指令是不可靠的，出错时就停止。二者的区别是简写方式无法指定报错信息。

总结

目前我已用 amber 作为 Linux 下编写脚本的首选工具，感觉好用。好工具，好生活，拯救脱发。

• 共享内存的原理
• 抽象共享内存指针
• 动态扩展
• 总结

开发者通常为了提高内存使用效率，或者避免内存泄漏，需要将内存池化管理。稍复杂一点的系统，一般都会有自己的内存管理机制，我在研读源码的时候，比较习惯先看内存管理模块的实现，这块很见开发者的基本工和工程思想，颇有一叶知秋之感，一个内存管理一团乱麻的系统，注定不会是艺术品。 内存池的实现方法很多，但万变不离其宗，通常就是一次申请大块内存，进程再将其化整为零的重复使用，对于操作系统来说，只发生了少数几次内存分配调用，避免长时间运行后内存碎片化。当内存池耗尽时，可以再申请一大块内存入池，实现内存池扩容。比较常见的是进程私有内存池，共享内存如何实现池化呢？

共享内存的原理

我们通常认为的内存地址，实际上并不是物理内存上的位置。操作系统出于安全性和效率考虑，每个进程都有独立的虚拟地址空间，A 进程的 0X123 和 B 进程的 0X123 处的数据通常没有任何关系。

本文均以 X64/X86 架构为例。

Linux 系统中，所有进程看到的地址空间大体如图，低地址处通常为用户程序，高地址处为内核空间。这个地址空间在不同 CPU 下也有一些差异：

• 32bit 系统中，虚拟地址空间总大小 4G，其中 1G 为内核区域。
• 64bit 系统中，只使用了 48 位地址，因此虚拟地址空间总大小为 256T，通常 8T 为内核区域。

64bit 系统的的进程虚拟地址空间非常大，普通计算机只能用到其中一小部分，操作系统通过 MMU 将虚拟地址映射到真实的物理内存上，这样只需要很小内存，也能同时运行大量程序。

在虚拟内存中地址连续的页面，在物理内存上的地址是不确定的，甚至在不同时刻，相同的虚拟内存地址也会被映射到不同的物理地址。

如果把同一块物理内存映射到两个进程的虚拟地址会发生什么呢？

任何一方修改这块区域，另一方都能立刻看到，因为它们实际上是相同的物理内存。但是请注意，这块物理内存区域在两个进程的虚拟内存中的地址却不一定相同。除非两个进程有亲缘关系，一个进程从另一个进程完整的继承了共享内存的映射关系，否则一般来说，同一块共享内存在不同进程中的地址是不同的。

抽象共享内存指针

对于没有亲缘关系的进程们，同一块共享内存通常会映射到各自虚拟内存的不同地址。显然进程之间无法共享虚拟内存地址，我们需要一种通用方法，描述共享内存中的位置。其实内存地址本质上是指针到 0x00 的偏移，我们可以稍作修改，创造一个全新的概念 “共享指针”，它也是一个偏移，但其基准地址是这块共享内存的虚拟内存地址。

无论在哪个进程，我们都可以通过共享指针，即相对共享内存起始位置的 offset 定位到相同位置，就算各进程共享内存的映射地址（起始地址）不同也没所谓。

很容易得到这样的公式：

共享指针的在进程中的真实地址 = 共享内存基址 + 共享指针（也就是 offset）；
共享指针 = 共享指针的在进程中的真实地址 -  共享内存基址；

只要将共享内存中所有指针都改为 “虚拟指针”，那么所有进程都可以将 “虚拟指针” 转换为自己虚拟内存中的地址正确访问。

共享内存就可以被切一组 block，通过一些 “共享指针”，把空闲 block 管理起来。

动态扩展

Linux 系统常见的 3 中动态内存接口：

• POSIX

  • shm_open 函数创建。
  • ftruncate 设置大小。
  • 通过mmap 将其映射到进程的地址空间，返回一个指针。
  • munmap 解除映射。
  • shm_unlink 删除共享内存对象。

• System V

  • shmget 函数。
  • shmat 将共享内存段附加到进程的地址空间，返回一个指针。
  • shmdt 从进程的地址空间分离该共享内存。
  • shmctl 支持其他操作，如删除共享内存段。

• mmap 匿名内存映射

无论哪种方式，都无法自动调整共享内存大小，有没有可能创建可以动态调整大小的共享内存池呢？前一步我们已经可以将一块共享内存按 block 管理起来，我们只需要再多申请一块共享内存，把它切分后就是一些 block 了。当所有进程都可以看到第一块共享内存的时候，如何找到新增的共享内存呢？

我们只需要在每块共享内存的特定位置，比如开始处，保存下一个共享内存的挂载参数，SystemV 接口就保存 shm key 和 size，POSIX 就保存 name 和 size，用全 0 值表示结束。 逻辑与单向链表类似，只不过通过共享内存参数而非指针串联起来。

前面我们引入一层抽象：“共享指针”，以统一的形式对所有进程描述共享内存中的位置，实际上就是共享内存中的 offset。现在情况变得复杂一点，单纯依靠 offset 已经不足以定位共享内存中的位置，还需要区分是在哪个共享内存上。是时候让 “共享指针” 变得复杂一些。

如果你对网络地址比较熟悉，应该听说过 “子网掩码”，我们也可以将 “共享指针” 的地址空间划分为共享内存编号 + offset。

以 64 位地址为例，offset 只需占据 40 位就可以支持 1T 大小的单块共享内存，以目前的硬件内存价格来说，已经是相当充足了，剩下 24 位作为共享内存编号使用，支持管理 16M 个共享内存块，也相当富余。理论上说，“共享指针” 的这两部分构成比例，决定了管理较少但更大的共享内存块，或者更小但更多共享内存块。

比如一个 “共享指针” 如图，它指向位于 1 号共享内存起始位置之后 32Bytes 位置的一块区域。共享内存中记录这些 “共享指针”，像一般指针一样构建复杂的结构。所有进程只需将 “共享指针”转换为自己的虚拟内存地址，就可以正确访问。

总结

只要 shm 中全部使用 “共享指针”，就可以扫清多进程共享内存地址映射的不一致性障碍，以很小的代价移植常见的内存管理方案。

• 文件清单
• 使用要求
• 使用方法

文件清单

压缩包中包含：

• 可执行程序 EnglishWordCheck.ext
• 示例单词清单：english_words1.txt
• 示例 word 文档：sample.doc

使用要求

1. 单词清单文件

文件名自定，文件类型为 txt。可以为不同的大纲分别准备单词表。

内容为大纲单词，各单词以空格、tab、换行分割，空白数量不限。

连接符连载一起的单词 A-B 识别为一个单词。

不区分大小写。

例如以下几种都是可以的：

apple
banana
peach

apple   banana                   peach

apple   banana
                   peach

2. 检测文件

仅支持 docx。

工具会检查 doc 中所有英文单词是否属于 1 中定义的大纲词汇。

单复数、过去时、ing 等都会自动转换为基本形式比较。也就是说单词清单中词汇的所有事态、型格都会被认为属于大纲内词汇。

使用方法

按步骤选择词汇表、word 文档，点击 check 即可。

超纲词汇报表会输出在 word 文档同级目录，与 word 文档同名的 xlsx 文件中。

• 安装 GPT4All
• 安装模型
• 进阶
• 总结

今年 AI 发展迅速，尤其是 LLM 涌现出了爆款应用 “ChatGPT”，不会整两句 GPT 你都不好意思扫共享单车。但是由于 OpenAI 的服务限制，国内访问比较困难。再加上自己的问题多少会有一些隐私问题，如果让云厂商知道我账户里的好几千巨款，心里不踏实。信息放在云端远不如运行在本地放心。

感谢伟大的开源社区，Meta 开源了 Llama2 模型，据社区测评，在多数维度可以接近 ChatGPT 的效果。后来 Github 有热心大神开发了 llama.cpp，让 LLM 运行在本地 CPU 上成为现实。llama.cpp 项目的编译安装都非常简单，如果你是个程序员，会很熟悉 ./configure && make && make install 三部曲。从 llama.cpp 开始折腾还是需要点耐心，想快速尝鲜的话，推荐 GPT4All 这款应用。大概看了下，它应该就是 llama.cpp 的 UI 版。

安装 GPT4All

GPT4All 支持 Linux、Mac、Windows 平台，前往官网 https://gpt4all.io/index.html 下载安装适合自己平台的版本。

如果需要设置代理和本地缓存目录，请点击 Setting。点击下一步。

请浏览选择安装路径，因为我打算把模型文件下载到 GPT4All 子目录，一般一个中小型模型大约在 10G 左右，所以最好安装磁盘剩余空间充足。

点击下一步。

每个软件都有的许可协议，勾选同意，继续下一步。

点击 Install，正式开始安装。

安装过程需要十分钟左右，取决于你的网速。

安装完毕。

安装模型

GPT4All 内置了一些训练好的模型，可以通过 GPT4All 下载使用。

这里先说一下如何打开 GPT4All，Mac 下安装好后会看到这两个图标：

请点击右侧图表 gpt4all 启动。左侧为管理工具。

Windows 下开始菜单里似乎只有左边的 maintenance tool，GPT4All 的本体需要去安装目录/bing/ 下找 chat.ext。总之非常诡异，可能这就是所谓的 “工程师文化”，不管你用户的死活。

如果你顺利的找到 GPT4All 的启动图标，第一次启动会看到这个页面，提示你下载模型文件。这是因为 GPT4All 只是模型框架，需要模型文件作为初始化参数。

亲测 OpenOrca 还可以，其他部分模型准确度很差。

下载前，点击最下面的 Browse，重新选择模型保存目录，为了方便，请在 GPT4All 安装目录下新建 models 目录，并将其选定为模型下载目录。

点击 OpenOrca 的 download，耐心等待下载完毕。

下载完毕就可以进入对话，与 AI 畅聊。由于这些模型的训练输入主要是英语，所以对中文支持不怎么样。虽然是基于 CPU 实现推理，但也能达到 5 Tokens 每秒，还在可以用的程度。

进阶

前面提到 GPT4All 应该是 llama.cpp 的 UI 版，所以它也支持的模型类型和 llama.cpp 是一样。除了从 GPT4All 自带的模型库选择不多，我们也可以自己从 huggingface 找到大量训练好的模型，放到前面设置的模型下载目录 models，GPT4All 也可以加载运行。

注意，模型需为 gguf 格式。

huggingface 访问速度很慢，模型又动则七八 G，推荐一个国内镜像 https://hf-mirror.com/ 下载速度可达 MB/s。

总结

试用了三四个模型，包括一个国内某大学训练的中文模型，与 ChatGPT 还有很大的差距，应该是我的电脑能力有限，最多只能跑 7B 的 llama，再加上社区训练的模型数据量和调优没法和 OpenAI 匹敌，果然 AI 时代，数据为王。如果想在本地获得比较好的使用效果，还需要针对自己的需求继续调教模型。现阶段，个人使用还是推荐云厂商的 GPT 产品，数据更新及时，有超算支撑，使用体验更好。