文章归档

扩展实战:编写第一个插件

系列收尾篇。先给出四种扩展姿势的选型表与树外插件的完整生命周期,然后三次实操:用 cordis.patch.yml 关掉内置行为、写一个最小工具插件、简述 LLM 适配器与 Conversation 节点,最后回到"一切皆插件"的主题。

客户端:从会话投影到桌面壳

会话状态活在 Host 进程的 Cordis 树里,UI 活在浏览器的 React 树里。本篇解析 dsh 的 host/client 六层所有权、Web 服务端的路由与信任围栏、会话跟踪的分数 seq 与结算暂存,以及桌面壳为什么只是一个薄壳。

能力 Seam:可替换的执行世界

解析 dsh 的能力 seam 体系:服务定义、提供方、消费方三角色如何一并设计;fs/shell/sandbox/subprocess 如何共享同一个执行世界;subagent 的六提供方接口,以及 MCP 与 skills 的两种接入方式。

LLM 适配层:流式词汇、冻结与重试

解析 dsh 的 LLM 适配层:可合并扩展的消息与流式词汇表、绑定一代注册的适配器接口、四阶段请求生命周期与三种结局、策略层重试,以及 DeepSeek 官方协议的私有扩展。

工具执行流水线:把关、审批与结算

一次工具调用要穿过一条十步流水线:预执行把关、审批、单调守卫、执行、后执行结算与物化。本篇逐段拆开 packages/core/tools 的流水线,讲清并发调度、结果防伪造与失败配对补全三个设计。

系统提示词:组装与准入

系统提示词不是请求上的一个字段,而是会话日志里的一组 surface 节点。本篇讲清提示词片段如何组装与渲染,以及 SystemPromptProjection 的准入决策树如何让模型历史与提示词变更保持一致。

事件系统:扩展点的分类学

事件就是扩展点。本篇给出 dsh 的四张事件分类表,讲清 waterfall 的 next() 委托机制与默认决策,剖析 agent/turn-stopping 的串行 data decides 设计,最后给一张选型决策树。

Agent Loop:轮次与步骤的状态机

精读 dsh 默认驱动器 ReactLoopAgent:Phase 三态、turn/step 嵌套状态机、claim 领取语义、取消提交语义与失败步骤的配对补全。

持久化:格式代际、迁移与崩溃恢复

第 5 篇的会话日志活在内存里,本篇看它如何穿越进程存活:磁盘布局与单写者租约、代际选择与"永不返回撕裂尾部"的读契约、相邻迁移链的编译时验证、隔离 worker 全量校验的排他发布,以及崩溃恢复中持久化层与 agent 层的职责划分。

会话日志:追加即事实

离开内核进入运行时状态。本篇拆解 dsh 的会话事件日志:为什么它是唯一事实源,SessionEvent 的连续性契约与四类事件,append 的写入路径与持久性屏障,以及 deriveMessages 与会话投影如何"从日志派生一切视图"。

Cordis 内核:四个原语撑起插件世界

前三篇讲完启动链路与 profile 组装,本篇下钻到底层插件框架 Cordis:Context 的作用域原语、插件的三种形态、Service 的注册即副作用规约、五种事件分发模式,以及撑起这一切的 Fiber 状态机。

启动链路:从 npx dsh web 到运行时

沿 npx dsh web 的调用链逐站拆解:bin 入口与 argv 解析、runProfile 组装补丁层、boot 驱动 Loader 挂载插件树、启动审计与两层就绪信号,以及配置 HMR 的监视、比对与事务化重载。

架构全景:包地图与插件树组装

一页地图读懂 dsh monorepo 的 54 个包组与 319 个包;讲清 profile 与组合包(bundle)两个组装概念、补丁层的叠加顺序、applyEntryPatches 的两条替换规则,以及 dsh --dump-config 的逐层溯源能力。

开篇:Agent Harness 与一切皆插件

专栏开篇。解释什么是 Agent Harness(模型之外的运行时脚手架),为什么 DeepSeek Harness 选择"一切皆插件"架构,它与 Claude Code、OpenAI Agents SDK 的定位差异,以及全系列 14 篇的路线图。

oh-my-pi 全景代码解析（一）：架构全景与哲学根基

oh-my-pi 全景代码解析（二）：pi-ai 统一 LLM 抽象层

oh-my-pi 全景代码解析（三）：pi-agent-core 运行时与状态机

oh-my-pi 全景代码解析（四）：pi-tui 差分渲染终端 UI

oh-my-pi 全景代码解析（五）：Rust 原生层——工具链的彻底重构

oh-my-pi 全景代码解析（六）：Hashline 编辑引擎——代码编辑的可靠性革命

oh-my-pi 全景代码解析（七）：Context Engineering——上下文工程系统

oh-my-pi 全景代码解析（八）：扩展生态与生产部署——从个人工具到企业基础设施

使用 AList + rclone 将夸克网盘挂载为本地磁盘：Windows/Linux 双平台部署指南

UE5.8 PBR 贴图工作流程：金属粗糙度管线的踩坑实录

围绕 UE5.8 金属/粗糙度工作流，系统讲解 PBR 贴图基础、BaseColor/Metallic/Roughness/Normal/AO/Emissive 的物理含义、色彩空间与导入设置、OpenGL 与 DirectX 法线差异、通道打包规范以及美术与 TA 协作中的常见错误。

UE5.8 Server、Client 与 NetMulticast RPC：从一次走火的霰弹枪说起

从联机射击项目中一次霰弹枪走火与伤害漏同步的事故出发，系统梳理 UE5.8 中 Server、Client、NetMulticast 三种 RPC 的调用方向、Reliable 与 Unreliable 语义、权限检查、参数限制、常见模式、属性复制取舍、频率控制与防作弊设计。

UE5.8 Behavior Tree、Blackboard 与 EQS：从一名站岗守卫的差劲表现说起

从一个塔防关卡里守卫 AI 的巡逻、发现、追击、返回场景出发，系统梳理 UE5.8 中 Behavior Tree 的 Selector / Sequence / Task / Decorator / Service 节点、Blackboard 的 AI 记忆设计、AIController 绑定、EQS 环境查询、掩体与攻击位置选择、行为树调试、性能优化，以及与 GAS 的联动思路。

UE5.8 C++ 与 Blueprint 混合开发：把代码放在对的地方

从 UCLASS / UFUNCTION 暴露到 BlueprintCallable、BlueprintNativeEvent、BlueprintPure，结合真实团队踩坑故事，讲清楚 UE5.8 里 C++ 与蓝图混合开发的边界、性能账和调试节奏。

UE5.8 Game Instance 与 Subsystem：把跨关卡数据与全局服务放对地方

从一个跨关卡数据丢失的线上 Bug 出发，系统梳理 UE5.8 中 Game Instance 的生命周期，以及 Engine、GameInstance、World、LocalPlayer 四类 Subsystem 的职责边界、协作方式与常见陷阱，并给出成就、存档、网络会话等全局服务的设计建议。

UE5.8 Gameplay Ability System 基础：从一套 MOBA 技能系统说起

从一个 MOBA 项目的技能重构需求出发，系统梳理 UE5.8 中 Gameplay Ability System 的核心组件、Ability Task、Attribute Set、Gameplay Tags、Gameplay Effect，并给出一个火球术与治疗术的完整实现示例。

UE5.8 Lumen Lite 与性能优化

UE5.8 的 Lumen Lite 用 irradiance fields 与 probe occlusion 把中低端平台动态 GI 的开销砍到接近 Lumen High Quality 的一半。这篇文章从一个 Switch 2 移植项目的真实踩坑经历出发，讲清楚它跟 HQ 的区别、什么时候该切、参数怎么调。

UE5.8 Lumen 动态全局光照：让光线真正在场景里反弹起来

深入解析 Unreal Engine 5.8 Lumen 动态全局光照的工作原理，包括 Software Ray Tracing、Hardware RT、Surface Cache、Distance Fields，以及性能调优和常见漏光问题的排查方法。

UE5.8 MegaLights 区域光阴影：把一千盏动态灯塞进主机帧预算

UE5.8 让 MegaLights 摘掉 Experimental 标签，用 froxel 稀疏采样、区域光阴影和新的调试工具，让大规模动态光源在当代主机上稳定跑到 60fps。本文结合一个赛博朋克酒吧关卡的实际踩坑过程，讲清楚这套管线的取舍与调参。

UE5.8 MetaHuman Collections 与 NPC Crowd：从剧场里坐满的观众说起

从一座虚拟剧场里近千名观众与一条高密度城市街道的人群场景切入，系统梳理 UE5.8 中 MetaHuman Collections 的资产组织方式、高保真 NPC Crowd 的生成管线、实例化渲染与 LOD、Mass AI 集成、动画共享与纹理图集、性能预算、平台差异，以及 UE5.8 针对 crowd 的改进。

UE5.8 Nanite 代理、碰撞与位移：别让视觉盛宴变成物理噩梦

深入讲解 UE5.8 Nanite 网格在物理、碰撞、位移方面的限制与解决方案，包括代理碰撞体生成、Collision Complexity、物理资产、通道配置、NavMesh 烘焙以及 Runtime Virtual Texture 位移的实战经验。

UE5.8 Nanite 虚拟几何体：把手工 LOD 扔进历史的垃圾桶

深入解析 Unreal Engine 5.8 Nanite 虚拟几何体的工作原理、集群层级、VisBuffer 渲染管线、内存预算与参数调优，以及在实际项目中的使用边界与踩坑经验。

UE5.8 Niagara Fluids 流体模拟：油桶爆炸与火旋风的实战思路

以燃烧油桶和火旋风两个游戏特效场景为例，讲解 UE5.8 Niagara Fluids 的 2D/3D Grid 流体解算、密度速度压力扩散等基础概念、与 Niagara 粒子的耦合方式、材质光照与性能平台差异，以及 5.8 版本的工作流改进。

UE5.8 Niagara 模块与数据接口：武器特效复用实战拆解

围绕武器特效复用难题，系统讲解 UE5.8 Niagara 的模块执行栈、内置模块分类、自定义 HLSL、Particle/Emitter Attributes、User Parameters 与蓝图通信、Grid2D 等数据接口，并给出具体可执行的调试与性能建议。

UE5.8 PlayerController、Pawn 与 Character：从一次载具失控事故说起

从一次载具切换失控的线上事故出发，系统梳理 UE5.8 中 PlayerController、Pawn、Character 三者的职责边界、Possess 生命周期、Character Movement Component 原理、AIController 与行为树联动、Spectator Pawn 观战模式以及网络同步中的 Ownership 概念。

UE5.8 Smart Objects 与交互槽位：从工坊里的排队说起

通过铁匠铺 NPC 排队使用工作台、城墙上射手抢占攻击位、酒馆里顾客找座位等场景，系统讲解 UE5.8 Smart Objects 与 Slot 的设计原理、申请释放机制、超时处理、与 Behavior Tree 和 Mass 的集成方式、交互点管理、条件评分、网络同步及性能优化。

UE5.8 Substrate 分层材质系统：把汽车油漆一层层拆开画

深入解析 Unreal Engine 5.8 Substrate 分层材质系统的工作原理，包括 Slab、Fuzz、Clear Coat、Metal 等 BSDF 类型，垂直堆叠混合机制，汽车油漆多层材质实战，以及性能调优和平台限制。

UE5.8 UObject 生命周期与垃圾回收：一次把 NewObject、GC 泄漏和弱引用讲透

从一次线上内存泄漏排查出发，系统梳理 UE5.8 中 UObject 的完整生命周期、NewObject 与 CreateDefaultSubobject 的差异、GC 标记清扫机制、循环引用、弱指针用法以及常见的 GC 泄漏场景。

UE5.8 Virtual Shadow Maps：页面池、缓存与远处的影子

深入剖析 UE5.8 Virtual Shadow Maps 的页面池管理、缓存失效策略、与 Nanite 的耦合方式，以及远景阴影退化处理，附带调试命令和项目踩坑实录。

UE5.8 World、Level 与 Streaming：大地图不是一次加载出来的

深入解析 Unreal Engine 5.8 中 World、Persistent Level、Sub-Level、Level Streaming Volume、Blueprint 流送、Async Loading、生命周期回调，以及 World Composition、World Partition 和多人同步机制。

UE5.8 反射系统与宏：从一次凌晨三点的崩溃说起

从一次 UObject 属性丢失的线上崩溃出发，拆解 UE5.8 反射系统的五条核心宏、UHT 生成机制、常用 Specifier 与 TSubclassOf/SoftObjectPath 的实际用法。

UE5.8 存档与持久化：一次把 SaveGame、版本兼容与云同步讲透

从一个上线前夜存档损坏的真实事故出发，系统梳理 UE5.8 中 USaveGame、SaveGameToSlot、可存档属性标记、版本兼容、JSON 与二进制存档、云存档同步、自动存档检查点、加密防作弊以及 5.8 相关改进，给出一份可直接使用的持久化设计清单。

UE5.8 数据驱动架构：当策划再次改数值时，没人再加班

从一个周五下午策划临时要调全武器数值的场景出发，系统梳理 UE5.8 中 UDataTable、UCurveTable、UDataAsset、PrimaryDataAsset、JSON/CSV 导入管线、数据加载与引用、数据驱动的技能/物品/敌人配置、与 GAS GameplayEffect 的结合、热更新与数据刷新、版本兼容与校验的完整实践。

UE5.8 新特性全览：从 Nanite 到 MCP，一次看懂次世代引擎版图

全面梳理 Unreal Engine 5.8 的核心新特性，包括 MegaLights、Lumen Lite、Mesh Terrain、MetaHuman Crowd、MCP Plugin 等，从渲染、动画、世界构建到 AI 辅助工作流，建立完整的 UE5.8 技术认知框架。

UE5.8 时域超分辨率技术：TSR、DLSS、FSR 的取舍与平台实战

深入剖析 UE5.8 中 TSR、DLSS、FSR 三类时域超分辨率方案的原理、质量/性能权衡、主机与 PC 平台选择，并结合团队实战案例讲解运动向量、历史帧累积、抖动、锐化与棋盘格渲染等关键细节。

UE5.8 材质图层与 Mask 混合：地形、血渍与图层控制实战

系统讲解 UE5.8 中 Layered Material、Material Layer、顶点颜色 Mask、贴图 Mask 的原理与实战，覆盖多层混合顺序、地形材质层、性能优化以及与 Substrate 的结合。

UE5.8 模块与插件架构：一次把 Public/Private、Build.cs 和加载时机讲清楚

通过老周团队踩过的坑，梳理 UE5.8 中 Module 与 Plugin 的边界、Public/Private 拆分、Build.cs 与 Target.cs 的分工、插件加载阶段以及循环依赖的处理方式。