lzzd 博客

Agent落地项目小型活动（Skill）

Thu, 16 Apr 2026 00:00:00 GMT

一、为什么想做这个东西

在游戏研发里，很多工作表面上看是「开发」，实际上是很多固定动作的组合：

读策划案

读反馈表

找参考活动

定位项目里该改哪些枚举、脚本、界面、配置

实现代码

做风险检查

列测试点

做 review

最后补配置、联调、跑活动

如果这些动作每次都要从头想，AI 就很容易表现得像「看起来懂很多，但做起来不稳定」。

真正想解决的问题，不是「让 AI 更聪明」，而是：

怎么把项目里已经存在的经验、规则、边界条件，变成 AI 可以稳定执行的工作流。

选择的切入点，是一个很典型的业务场景：

无新增子活动、以复用为主的小型活动接入。

这个场景适合做 Agent 落地试点，因为它同时具备三种特征：

有明确输入：活动枚举、服务器对象、反馈表、参考活动

有固定改动面：枚举、脚本、界面、配置

有大量项目经验：哪些能复用，哪些必须问，哪些不能碰

换句话说，它天然适合被沉淀成 skill。

二、Skill 到底是什么

很多人第一次接触 Cursor 时，会把 skill 理解成「一个提示词模板」。这个理解不完全错，但不够本质。

Skill 的本质

Skill 本质上不是知识库，也不是代码生成器，而是：

一份给 Agent 的「项目内工作规程」。

它的作用不是告诉 AI「这个功能怎么写」，而是告诉 AI：

这个任务适用于什么范围

先做什么，后做什么

什么可以直接做，什么必须先问

哪些文件一定要改，哪些一定不能改

哪些错误是常见误判

任务完成后必须输出什么

如果把 AI 看成一个新来的开发同学，那 skill 就像是这个项目写给他的：上手说明、操作手册、项目规范、防踩坑清单。

Skill 不是让 AI 获得知识，而是让 AI 在特定场景下按正确流程做事。

这是后续所有迭代的核心出发点。

三、为什么一开始 Agent 总做不对

1. AI 会「看起来懂」，但不等于「知道项目正确做法」

例如让它做一个小型活动，它可能会：

猜一个参考实现

开始改脚本

甚至直接跳过配置表

从语言上看很像在推进任务，但实际上已经偏了。

原因很简单：AI 擅长补全合理答案，不擅长天然知道你们项目里的隐含规则。 而游戏项目恰恰充满隐含规则，例如：

参考活动应该先从哪张表里确认

哪个子活动默认进 tab，哪个不进

哪些资源必须问，哪些可以复用

哪些文件是导表产物，绝对不能直接改

哪种改表方式和项目工具兼容，哪种不兼容

如果这些规则没写进 skill，AI 就会开始「合理猜测」。一旦开始猜，稳定性就没了。

2. AI 容易把「能做」误判成「应该做」

它确实能直接改表、转表、继续改生成后的配置文件，但「能做」不等于「项目里应该这样做」。

实际验证发现：

用通用方式去改 xlsx，可能与项目转表工具不兼容

直接改导表后的 .lua / .json，会破坏项目流程

就算表改成功了，稳定性和调试成本也很高

问题不在于 AI 不会改，而在于：它不知道哪里是能力边界，哪里是项目边界。

3. AI 会在复杂链路里逐渐漂移

一开始想让它一条龙做完：读反馈表、找参考活动、改代码、改配置、转表、校验、输出结果。这条链太长，任何一个环节出现偏差，后面就会越走越偏。

真正让 Agent 稳定的，不是「把所有事情都交给它」，而是：

把它放在最适合自动化的那一段。

四、小型活动 Agent 是怎么一步步迭代出来的

这套 skill 不是一次写成的，而是被真实问题「逼」出来的。整个过程大致经历了四个阶段（下文分阶段展开）。

五、第一阶段：先把「要做什么」写清楚

最基础的动作，是把场景收敛成明确边界。

适用范围

纯客户端为主

无新增子活动

优先复用参考活动

目标是先跑通

典型输入

客户端枚举名

服务器对象名

复用的子活动列表

反馈表问题描述

典型输出

改哪些代码、脚本

配表建议

风险点、测试点、review 建议

一旦范围没收住，Agent 就会默认把任务扩展成：新玩法设计、服务端对象重建、配置体系重构、UI 全量重做——这些都已经超出「小型活动接入」试点场景。

第一步不是写规则，而是先把任务边界收紧。

六、第二阶段：把「项目经验」写成硬规则

把原本只存在于开发脑子里的经验，改写成 Agent 能执行的规则。例如（均为后续反复验证后加入）：

规则	解决的问题
参考活动不能乱猜，必须先从指定配置确认	AI 把「名字像」误判成「业务上就是」
子活动范围不能自己扩展，以开发者输入的复用列表为准	防止从反馈表过度脑补
资源信息优先从反馈表问题描述提取，缺项再问	减少无效提问、避免卡死
明确哪些能复用、哪些必须确认	信息不全时是「继续推进」还是「卡死」

七、第三阶段：从「直接改表」退回到「输出配表建议」

这是落地过程中最关键的一次认知变化。

一开始的想法很直观：既然 AI 知道要改哪些表、哪些字段，让它直接改表不就行了？

连续跑几轮后，问题基本都集中在配置这一段：

改表方式与项目工具链不稳定

转表链路依赖多

导表结果不一致时排查成本高

AI 知道「该怎么配」，不等于「改表一定稳」

真正关心的不是「AI 能不能把表直接填完」，而是：

「这个 AI 工作流，能不能让下一个小型活动明显更快？」

答案可以是：能。但关键提效点不一定来自「直接改表」，而来自：

快速找对参考活动

快速列清代码改动点

快速识别复用关系

快速整理完整配表建议

从零实现 Unity 边缘外发光：Rim Light + Bloom 原理与完整实现

Fri, 30 Jan 2026 00:00:00 GMT

一、目标是什么

做游戏时经常看到一种效果：角色或物体的边缘有一圈发光，像是被光晕包裹（比如网易永劫无间的霸体人物边缘发光效果）。这种效果在技术上叫 Rim Light（边缘光），也常被称为菲涅尔效果（Fresnel Effect）。

这篇文章记录从零写出这个效果的完整过程，包括原理推导、代码实现、以及用 Post-Processing 让效果更好看的步骤。

二、原理：为什么边缘会发光

自然界里有一个现象：当你看向一面玻璃的正面时，玻璃很透明；但从很斜的角度看时，玻璃会变得很反光。这就是菲涅尔现象。

Rim Light 借用了同样的思路：视线方向和物体表面越垂直（正对着你），亮度越低；越平行（边缘处），亮度越高。

计算方法：

rim = 1 - dot(法线方向, 视线方向)

dot 是点积，结果是两个向量的夹角余弦

正对摄像机的面：法线和视线方向几乎平行，点积接近 1，1 - 1 = 0，不发光

边缘的面：法线和视线方向接近垂直，点积接近 0，1 - 0 = 1，完全发光

再用 pow 控制衰减速度：pow(rim, _RimPower) ，RimPower 越大，发光区域越窄越锐利。

三、第一步：搭建 Shader 基础结构

在 Unity 的 Built-in 渲染管线里，Shader 分三层：

Properties：暴露给 Inspector 的可调参数

SubShader / Pass：实际的渲染逻辑

CGPROGRAM：顶点着色器和片段着色器的代码区

先写好框架，把需要的参数暴露出来：

Shader "Custom/BuiltInRimLight"
{
    Properties 
    {
        _MainTex ("主纹理", 2D) = "white" {}
        _RimColor ("边缘光颜色", Color) = (0.5, 0.5, 1, 1)
        _RimPower ("边缘强度", Range(0, 8)) = 2.0
    }
    ...
}

_RimPower 范围设 0~8：太小边缘光会漫到整个模型，太大只有极细一条线。

四、第二步：顶点着色器——把数据传到片段着色器

顶点着色器的任务是把每个顶点从模型空间变换到正确的坐标系，并把需要的数据打包传给片段着色器（v2f 结构体）。

边缘光需要两个关键数据：世界法线和视线方向，必须在同一个坐标系（世界空间）下计算。

v2f vert(appdata v) 
{
    v2f o;
    // 顶点位置：模型空间 → 裁剪空间（GPU 最终用这个绘制到屏幕）
    o.pos = UnityObjectToClipPos(v.vertex);
    // 法线：模型空间 → 世界空间（注意不能直接用矩阵乘，要用专用函数）
    o.worldNormal = UnityObjectToWorldNormal(v.normal);
    // 视线方向：从顶点指向摄像机，Unity 内置函数自动计算
    o.viewDir = WorldSpaceViewDir(v.vertex);
    // UV 传递（处理 Tiling/Offset）
    o.uv = TRANSFORM_TEX(v.uv, _MainTex);
    return o;
}

为什么法线不能直接乘变换矩阵？因为模型做了非等比缩放时，用位置变换矩阵会让法线方向出错。UnityObjectToWorldNormal 内部用了转置逆矩阵，专门解决这个问题。

五、第三步：片段着色器——计算 Rim 值

fixed4 frag(v2f i) : SV_Target 
{
    fixed4 baseColor = tex2D(_MainTex, i.uv);
    
    float rim = pow(1 - saturate(dot(normalize(i.worldNormal), normalize(i.viewDir))), _RimPower);
    
    return baseColor + rim * _RimColor;
}

saturate 把点积结果夹在 [0, 1] 之间，防止出现负数导致颜色异常。normalize 确保向量是单位长度，否则点积不代表角度关系。

这一步已经能看到边缘光效果了，但边缘比较生硬。

六、第四步：加入柔化层，模拟外发光扩散

真实的发光效果不只是一条锐利的线，还有向外扩散的柔光晕。用两层叠加来模拟：

float rimSharp = pow(rim, _RimPower);          // 锐利内层
float rimSoft  = pow(rim, _RimPower * 0.25);   // 柔化外层，指数更小 → 覆盖范围更宽
return baseColor + rimSharp * _RimColor + rimSoft * _RimColor * 0.2;

_RimPower * 0.25 让指数更小，pow 曲线更平缓，发光范围更宽。* 0.2 让外层强度只有内层的五分之一，形成自然的扩散晕染感。

两层叠加后，效果变成：核心处有一条亮线，外侧有柔和光晕，视觉上像是真的在发光。

七、第五步：加 Post-Processing Bloom，让光晕更真实

Rim Light 本质是在模型材质上加颜色，但颜色再亮也只是"亮色"，不会真的像光一样往外扩散。要做到"往外溢出"的感觉，需要后处理。

配置步骤：

Package Manager 安装 Post Processing 包

在场景的 Main Camera 上加 Post-process Layer 组件，Layer 选 PostProcessing

新建一个空物体，Layer 设为 PostProcessing，加 Post-process Volume 组件，勾选 Is Global

在 Volume 里新建 Profile，添加 Bloom 效果

Bloom 参数配置：

参数	值	说明
Intensity	6	发光强度，值越大扩散越明显
Threshold	默认	超过此亮度的像素才触发 Bloom

Bloom 的原理：把画面中超过阈值的高亮像素做模糊处理，再叠回原画面，产生光溢出的感觉。配合 Rim Light 的高亮边缘，效果会非常自然。

八、总结：学到了什么

核心原理： 法线和视线的点积是边缘光的数学基础，本质是判断"这个面有多斜对着摄像机"。这个思路可以扩展到几乎所有方向相关的视觉效果。

两个坐标系的重要性： 法线、视线、光线的计算必须在同一个坐标系下进行，不然方向对不上。世界空间是最常用的统一坐标系。

分层叠加的思路： 一个效果不够自然时，可以用多层叠加——主层精确，辅助层柔化——而不是去改主层的公式。这个思路在很多 Shader 里都适用。

材质 + 后处理的配合： Shader 负责"像素该是什么颜色"，Post-Processing 负责"整个画面该怎么处理"。两者配合才能做出最完整的视觉效果。

九、发散：还能延伸到哪里

方向1 - 让发光颜色动起来 用 _Time 控制颜色随时间变化，或者接入脚本动态修改 _RimColor，做出能量护盾充能、受伤闪光等效果。

方向2 - 基于深度的外描边 Rim Light 是"从材质内部算边缘"，还有另一种思路是"用两个 Pass，第二个 Pass 把模型放大一点，只画背面"，可以做出更均匀的卡通描边效果。

方向3 - Bloom 阈值联动 配合 HDR 颜色，让 Rim 颜色的亮度超过 1（比如 (2, 2, 4, 1)），Bloom 的 Threshold 卡在 1 附近，只让边缘光触发 Bloom，其他区域不受影响，效果更精准。

方向4 - URP 迁移 Built-in 管线的 CGPROGRAM 在 URP 里要改成 HLSLPROGRAM，UnityCG.cginc 换成 Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl，思路完全一样，只是 API 名称不同。

UnityShader-迷雾效果

Sat, 14 Mar 2026 00:00:00 GMT

一、为什么迷雾效果值得深入研究

战争迷雾（Fog of War）是策略游戏里最经典的机制之一：地图一开始是黑的，角色走过的地方变灰，当前视野范围内才能看清。

这个效果表面上很简单，实现起来涉及的问题出乎意料地多：视野怎么算？障碍物遮挡怎么处理？探索历史怎么保存？画面怎么平滑过渡？

我读了 FogOfWar_ForUnity 这个开源仓库，把它的设计过了一遍，理解了大部分思路，但也发现一些可以换个方式做的地方——于是决定自己写一个版本。

二、读懂这个仓库：它是怎么做的

数据层：用 Color32 的两个通道编码三种状态

迷雾本质上是一个覆盖全地图的二维数组，每个格子存一个状态：

状态	含义
未探索	完全黑暗
已探索但不可见	半透明灰雾
当前可见	完全透明

这个仓库用 Color32 的两个通道编码这三种状态：

r == 255：当前帧可见

b == 255：历史上曾经可见（已探索）

每帧开始时把 r 清零，保留 b，这样已探索信息永不丢失。这个设计很精妙——用一个数组同时管历史状态和当前帧状态，省了一个数组。

视野层：圆形范围 + 障碍物锥形遮挡

先把圆形范围内所有格标记为可见，然后找出范围内的障碍物，从每个障碍物向后投射"阴影锥"，把被遮挡的格取消可见。

遮挡判断没有用 Raycast，而是用斜率近似角度：

var k1 = y1 * 1f / x1;  // 障碍物方向斜率
var k2 = y2 * 1f / x2;  // 目标格方向斜率
float z = Mathf.PI / (6 + distance / 1.2f);  // 遮挡角随距离缩小
return Angle(k1, k2) < z;  // 角度差 < 遮挡角 → 被遮挡

这样做的好处是避免三角函数开销，性能更好。代价是边缘处有近似误差。

渲染层：CPU → GPU → 模糊 → 帧间插值

整条渲染管线：

CPU 算出每格的 alpha 值（透明/半透明/不透明）

上传到 Texture2D，再 Blit 做三次 3×3 高斯模糊，让边缘柔和

每帧 lerp(上一帧纹理, 本帧纹理, 0.05)，让迷雾扩散/消散有平滑动画

把最终纹理贴到一个铺在场景上方的透明 Plane

三、我的思考：哪里可以做得不一样

问题一：斜率近似的误差

斜率 k = y/x 在 x = 0 时会产生除零，作者用了 x1 == 0 的特判，但整体逻辑比较难读。用角度（atan2）更直观，现代 GPU 和 CPU 做三角函数的开销其实很小。

问题二：渲染层用 Plane 覆盖

用一个 Plane 铺在场景上方，需要精确调整 Plane 的大小和 UV 映射，换场景时容易对不齐。更稳的方式是用后处理（Post-Processing）直接在屏幕空间叠加迷雾纹理，不依赖世界坐标的对齐。

问题三：视野更新用定时器（0.5s 一次）

这能省开销，但在角色快速移动时会有明显延迟感。可以用脏标记（dirty flag）：角色移动时标记需要重算，下一帧再更新，既不丢精度又避免每帧都算。

四、自己实现：从零搭一个战争迷雾

整体设计

[FogMap]        → 地图数据，每格存三态（byte数组）
[FogViewer]     → 挂在角色上，提供位置和视野半径
[FogManager]    → 每帧协调更新，写数据、上传纹理
[FogShader]     → 后处理叠加，根据屏幕 UV 采样迷雾纹理

第一步：地图数据结构

用 byte 数组，每格三种状态，比 Color32 更直观：

public class FogMap 
{
    public enum FogState : byte { Hidden = 0, Explored = 1, Visible = 2 }
    
    private FogState[] _states;
    private int _width, _height;
    
    public FogMap(int width, int height) 
    {
        _width = width;
        _height = height;
        _states = new FogState[width * height];
    }
    
    public FogState Get(int x, int y) => _states[y * _width + x];
    public void Set(int x, int y, FogState s) => _states[y * _width + x] = s;
    
    // 每帧开始：把所有 Visible 降级为 Explored（保留探索历史）
    public void BeginFrame() 
    {
        for (int i = 0; i < _states.Length; i++)
            if (_states[i] == FogState.Visible)
                _states[i] = FogState.Explored;
    }
}

第二步：视野计算——圆形范围 + DDA 射线

DDA（Digital Differential Analyzer）是一种整数格子上的射线追踪算法，不用浮点三角函数，速度快且无歧义：

public void ComputeVision(FogMap map, Vector2Int center, int radius)
{
    // 圆形范围内，向每个边缘格发出射线
    for (int angle = 0; angle < 360; angle += 2)  // 每2度一条射线
    {
        float rad = angle * Mathf.Deg2Rad;
        float dx = Mathf.Cos(rad);
        float dy = Mathf.Sin(rad);
        
        float x = center.x, y = center.y;
        
        for (int step = 0; step <= radius; step++)
        {
            int gx = Mathf.RoundToInt(x);
            int gy = Mathf.RoundToInt(y);
            
            if (gx < 0 || gy < 0 || gx >= map.Width || gy >= map.Height) break;
            
            map.Set(gx, gy, FogMap.FogState.Visible);
            
            // 遇到障碍物则停止这条射线
            if (IsObstacle(gx, gy)) break;
            
            x += dx;
            y += dy;
        }
    }
}

射线密度（每 2 度一条）根据视野半径调整。半径大时可能漏格，可以改为角度步长 = 1 / radius（每格一条射线）来保证不漏。

第三步：把数据上传到纹理

private Texture2D _fogTexture;
private Color32[] _pixelBuffer;

void UploadToTexture(FogMap map)
{
    for (int i = 0; i < _pixelBuffer.Length; i++)
    {
        byte alpha = map.States[i] switch
        {
            FogMap.FogState.Visible  => 0,    // 透明，完全可见
            FogMap.FogState.Explored => 120,  // 半透明，灰雾
            _                        => 255   // 不透明，全黑
        };
        _pixelBuffer[i] = new Color32(0, 0, 0, alpha);
    }
    _fogTexture.SetPixels32(_pixelBuffer);
    _fogTexture.Apply();
}

第四步：Shader——后处理叠加迷雾

用 Unity 的后处理框架，在屏幕空间叠加，不需要世界坐标对齐：

Shader "Custom/FogOverlay"
{
    Properties { _FogTex ("迷雾纹理", 2D) = "black" {} }
    
    SubShader
    {
        Tags { "Queue" = "Overlay" "RenderType" = "Transparent" }
        ZTest Off
        ZWrite Off
        Blend SrcAlpha OneMinusSrcAlpha
        
        Pass
        {
            CGPROGRAM
            #pragma vertex vert_img
            #pragma fragment frag
            #include "UnityCG.cginc"
            
            sampler2D _FogTex;
            
            fixed4 frag(v2f_img i) : SV_Target
            {
                // 把摄像机视口 UV 映射到迷雾纹理 UV
                // 需要传入地图边界和摄像机位置来做偏移
                float2 fogUV = WorldToFogUV(i.uv);
                return tex2D(_FogTex, fogUV);
            }
            ENDCG
        }
    }
}

第五步：帧间平滑过渡

直接改纹理会让迷雾瞬间出现/消失，加一个 Lerp 让过渡更自然：

private RenderTexture _currentFogRT;
private RenderTexture _targetFogRT;
private Material _lerpMat;  // 只有一行：lerp(_LastTex, _MainTex, _T)

void LerpFog()
{
    _lerpMat.SetTexture("_LastTex", _currentFogRT);
    _lerpMat.SetTexture("_MainTex", _targetFogRT);
    _lerpMat.SetFloat("_T", 0.08f);  // 比原仓库的 0.05 稍快，响应更及时
    
    var temp = RenderTexture.GetTemporary(_currentFogRT.descriptor);
    Graphics.Blit(null, temp, _lerpMat);
    Graphics.Blit(temp, _currentFogRT);
    RenderTexture.ReleaseTemporary(temp);
}

五、总结：学到了什么

数据设计影响一切后续逻辑。 开源仓库用 Color32 双通道编码三态，聪明但难读；用独立 byte 数组更直观，也方便后续扩展（比如加"部分可见"状态）。没有绝对的对错，取决于优先考虑性能还是可维护性。

视野计算的核心是"遮挡"。 圆形范围简单，障碍物遮挡才是难点。射线方法和锥形阴影各有取舍：射线更精确，锥形更快。理解这个权衡之后，遇到同类问题（光照、声音传播）都能用类似思路处理。

渲染和数据要分层。 数据层（byte 数组）负责状态正确，渲染层（纹理 + Shader）负责视觉效果。两层解耦之后，可以独立优化——比如把数据计算挪到 ComputeShader，而不需要改渲染逻辑。

帧间插值是廉价的视觉提升。 一行 lerp 让硬切变成平滑过渡，开销几乎为零，但视觉质量提升明显。这种"用时间换空间感"的思路在游戏开发里到处适用。

六、发散：还能延伸到哪里

方向1 - Compute Shader 并行计算 视野的每条射线相互独立，天然适合并行。把视野计算放到 Compute Shader，几千条射线同时算，对大地图的性能提升非常显著。

方向2 - 动态障碍物 现在的实现假设障碍物是静态的（初始化时用物理检测）。如果要支持动态障碍物（比如可移动的箱子），需要每帧重建障碍物 mask，或者用事件驱动的增量更新。

方向3 - 多单位视野合并 多个单位的视野取并集。可以让每个单位独立维护一张迷雾纹理，GPU 上用 max 操作合并；也可以在 CPU 上用位运算合并 byte 数组。位运算版本：state[i] = max(stateA[i], stateB[i])，一行搞定。

方向4 - 视野形状扩展 除了圆形视野，还可以做扇形（带朝向的前方视野，适合潜行游戏）、矩形（摄像机视角，适合监控场景）。只需要修改"哪些格子在视野内"的筛选条件，遮挡逻辑完全不用改。

方向5 - 接入 AI 把迷雾数据暴露给 AI 系统：AI 单位只能"看到"当前可见格里的敌人，已探索区域可以记忆上次看到的位置。迷雾不只是视觉效果，还是信息层。

ECS-数据导向

Fri, 13 Dec 2024 00:00:00 GMT

😀

OOP大部分人都很熟悉，那DOP呢，其实也就是object变成了data，但DOTS（多线程式数据导向型技术堆栈。）的核心思想就是DOP，这里主要不说DOTS，因为我自己也没用过，但其核心组成就是ECS挺有意思，有点想学，但目前还只停留在了解的阶段。

ECS（Entity-Component-System）

ECS是一种常见的游戏开发架构模式，主要用于管理游戏对象（Entities）、数据（Components）和行为（Systems）。ECS的核心思想是将数据和行为分离，以提高代码的灵活性、可维护性和性能.

Entity（实体）：实体是游戏中的基本对象，通常只是一个唯一的标识符（如整数ID）。实体本身不包含任何数据或行为，它只是一个“容器”，用于关联组件。

Component（组件）：组件是纯粹的数据结构，用于描述实体的某个属性或状态。例如，一个“位置”组件可能包含 x 和 y 坐标，一个“生命值”组件可能包含当前生命值和最大生命值。一个实体可以拥有多个组件。

System（系统）：系统是处理逻辑的部分。每个系统负责处理一组具有特定组件的实体。例如，“渲染系统”会处理所有具有“位置”和“渲染”组件的实体，并将它们绘制到屏幕上。

ECS的原理

创建实体：首先创建一个实体，通常只是一个唯一的ID。

添加组件：为实体添加所需的组件。例如，为一个玩家实体添加“位置”、“生命值”、“渲染”等组件。

系统处理：系统会遍历所有具有特定组件的实体，并执行相应的逻辑。例如，“移动系统”会遍历所有具有“位置”和“速度”组件的实体，并根据速度更新它们的位置。

简单的ECS示例

核心设计说明：

组件 (Component)

使用结构体存储数据（值类型更符合ECS内存友好特性）

通过 IComponent 接口标记组件类型

实体 (Entity)

使用字典存储组件集合

提供组件查询的泛型方法

系统 (System)

通过继承抽象类实现具体逻辑

在Update中筛选具有特定组件组合的实体

世界 (World)

统一管理所有实体和系统

驱动所有系统的更新

💡

感觉ECS其实比较适合大型复杂的游戏，尤其是有大量的游戏对象的项目，可以用ecs管理其复杂的交互逻辑，同时也适合需要高性能和高灵活性的项目，总之这套开发架构很好用，不过有上手成本，作者本人也还在摸索中~

给 NotionNext 博客接入 Dify AI 助手：从原理到避坑全记录

Wed, 18 Jun 2025 00:00:00 GMT

😀

背景：先搞清楚架构

在开始之前，需要理解 NotionNext 博客的运作方式，否则后面的配置步骤会让人摸不着头脑。

Notion 的角色

Notion 在这套方案里不只是写文章的地方，它同时承担了三件事：

内容数据库：所有博客文章、页面都存在 Notion 数据库里

配置中心：博客的各种开关、参数（比如主题、评论系统、AI 配置）也存在一个 type 为 Config 的 Notion 页面里

数据源：每次有人访问博客，服务器会通过 Notion 私有 API 拉取最新数据

Vercel 的角色

Vercel 是部署平台，负责把 GitHub 仓库里的 Next.js 代码编译并运行。它的工作方式：

每次你向 GitHub 推送代码，Vercel 自动重新构建部署

支持环境变量（类似 .env 文件），注入到构建过程中

使用 ISR（增量静态再生）：页面第一次被访问时生成静态 HTML，之后定时从 Notion 拉取最新数据刷新缓存

为什么配置有两个地方

这是很多人困惑的地方。NotionNext 的配置读取优先级是：

Notion 配置页 > Vercel 环境变量 > blog.config.js 默认值

简单说：Notion 配置页优先级最高，Vercel 环境变量次之。两个地方都可以写，但有些配置在特定时机只能读到其中一个，这是后面踩坑的根源。

为什么选 Dify

NotionNext 内置了五种 AI 组件：Dify、Coze、Chatbase、WebWhiz、TianliGPT。

选 Dify 的理由：

免费版支持知识库 + URL 爬取，可以让 AI 读懂你的博客文章

可以选底层模型（接 Claude、GPT、国产模型均可）

博客代码里已内置 DifyChatbot.js 组件，理论上只需填配置

完整接入步骤

第一步：在 Dify 创建应用

访问 cloud.dify.ai 注册并登录

左侧点工作室 → 创建应用 → 选 Agent

填写系统提示词，让 AI 了解自己的定位，例如：

你是 [你的博客名] 的 AI 助手，熟悉博客的所有文章内容。
用中文回答用户问题，优先检索知识库中的相关文章。

选择底层模型（免费额度内可用 GPT-3.5 或 Claude Haiku）

第二步：创建知识库并爬取博客

左侧点知识库 → 创建知识库

选择**「从网页同步」**

填入你的博客地址，开启爬取子页面

等待爬取完成后，回到刚才创建的 Agent，在工具里添加这个知识库

第三步：获取 API Token

打开你的 Agent 应用

左侧菜单找**「API 访问」**

点**「创建密钥」**，生成格式为 app-xxxxxxxxxx 的 Token，保存好

第四步：修改代码

由于 NotionNext 的配置读取链在某些渲染时机会失效，最可靠的方式是让 DifyChatbot 直接读取环境变量，而不依赖 siteConfig 体系。

修改 components/DifyChatbot.js（完整替换）：

import { useEffect } from 'react'

const TOKEN = process.env.NEXT_PUBLIC_DIFY_CHATBOT_TOKEN
const BASE_URL = process.env.NEXT_PUBLIC_DIFY_CHATBOT_BASE_URL || 'https://udify.app'

export default function DifyChatbot() {
  useEffect(() => {
    if (!TOKEN) return

    window.difyChatbotConfig = { token: TOKEN, baseUrl: BASE_URL }

    const script = document.createElement('script')
    script.src = `${BASE_URL}/embed.min.js`
    script.id = TOKEN
    script.defer = true
    document.body.appendChild(script)

    return () => {
      document.getElementById(TOKEN)?.remove()
    }
  }, [])

  return null
}

修改 components/ExternalPlugins.js 一行：

找到：

const DIFY_CHATBOT_ENABLED = siteConfig('DIFY_CHATBOT_ENABLED', null, NOTION_CONFIG)

改为：

const DIFY_CHATBOT_ENABLED = siteConfig('DIFY_CHATBOT_ENABLED', null, NOTION_CONFIG) || process.env.NEXT_PUBLIC_DIFY_CHATBOT_ENABLED

改完后推送到 GitHub：

git add components/DifyChatbot.js components/ExternalPlugins.js
git commit -m "feat: 直接读取环境变量启用 Dify 聊天助手"
git push

第五步：在 Vercel 设置环境变量

进入 Vercel 项目 → Settings → Environment Variables，添加三个变量：

变量名	值
`NEXT_PUBLIC_DIFY_CHATBOT_ENABLED`	`true`
`NEXT_PUBLIC_DIFY_CHATBOT_TOKEN`	`app-你的Token`
`NEXT_PUBLIC_DIFY_CHATBOT_BASE_URL`	`https://udify.app`

注意：BASE_URL 填 https://udify.app，不是 https://api.dify.ai。前者是加载聊天气泡脚本的地址，后者是 API 接口地址，填错了脚本找不到，气泡不会出现。

第六步：重新部署

Vercel Deployments → 最新一条 → 右侧 ... → Redeploy。

部署完成后刷新博客，右下角出现聊天气泡即为成功。

💡

踩过的坑

坑一：配置改了没用

原因：博客有缓存机制，Notion 配置页的改动要等缓存过期或重新部署才生效。改完 Notion 后必须 Redeploy。

坑二：BASE_URL 填错

https://api.dify.ai 是后端 API 地址，不提供 embed.min.js 文件。聊天气泡脚本在 https://udify.app/embed.min.js，两者不能混用。

坑三：siteConfig 读取链在特定场景失效

siteConfig 依赖 React 的 useGlobal() Context，如果组件在某些渲染时机不在 Provider 内，useGlobal() 会抛出异常被静默捕获，整条配置链降级返回 null，导致明明填了配置却不生效。解决方式是直接读 process.env.NEXT_PUBLIC_*，绕过这个依赖。。

Unity-Shader

Sat, 01 Aug 2026 00:00:00 GMT

😀

个人感觉shader这块，了解原理，有对它导致问题的判断力即可。

ShaderLab

本质是什么：

Shader 是跑在 GPU 上的程序，控制"每个像素最终显示什么颜色"。ShaderLab 是 Unity 封装的一套写 Shader 的语法格式。

渲染流水线：

CPU→GPU

渲染管线流程(gpu流水线)：

CPU 准备网格数据

↓ 顶点着色器（Vertex Shader）每个顶点在哪里，做坐标变换 ↓ 光栅化（Rasterization）把三角形面片转成一个个像素 ↓ 片元着色器（Fragment Shader）每个像素显示什么颜色 ↓ 输出到屏幕

需要知道的关键概念：

Pass：一次渲染流程，复杂效果可以多 Pass

Properties：暴露给 Inspector 面板的参数

URP vs Built-in：现在新项目基本用 URP，两套语法不完全通用

什么时候找美术/图程：角色描边、溶解、水面等视觉效果找他们，你只需要能看懂 Shader 代码在做什么、会调参数

空间变换：模型空间→世界空间→观察空间→裁剪空间→屏幕空间

我们作为程序需要的判断力：

▎ 这个效果是 Shader 问题还是逻辑问题？这个 Shader 为什么在低端机掉帧（指令数太多 / 采样次数太多）？