紫升的博客

HyperFrames 的原理：让 HTML 成为可寻址的视频时间线

2026-09-18T08:15:00.000Z

最近用 HyperFrames 做视频时，我发现最容易误解它的方式，是把它看成“带时间轴的网页截图器”。这个比喻能解释结果，却解释不了关键约束：为什么媒体播放不应该交给 GSAP，为什么 data-duration 和动画 timeline 不是一回事，为什么同样一段 HTML 在预览里看起来正常，渲染时却可能从错误的帧开始。

HyperFrames 真正解决的问题，是把视频重新表达成一种可寻址的网页状态：HTML 声明画面由哪些 clip 组成、每个 clip 在什么时候出现、位于哪一层；动画 Runtime 根据当前时间计算 DOM 状态；框架负责把媒体 seek 到对应位置，再捕获确定的 frame。这个边界一旦清楚，很多“玄学”都会变成可以检查的 contract。

一句话总结

HyperFrames 的核心不是“用 HTML 画视频”，而是“用 HTML 声明时间，用 seekable Runtime 计算状态，用框架统一接管媒体播放”。

一个可渲染的 composition 至少包含四类信息：

画布身份与尺寸：data-composition-id、data-width、data-height。
时间结构：data-start、data-duration、data-track-index。
视觉状态：普通 DOM、SVG、Canvas 或动画 Runtime 产生的可复现状态。
媒体边界：video、audio 的源文件、起始偏移、音量和裁剪窗口。

渲染器在时间 t 上做的事情，可以简化成：

HTML contract + t
  → 解析当前 composition 与 clip
  → 将 video/audio seek 到 t 对应的媒体时间
  → 将动画 timeline seek 到 t
  → 捕获当前 DOM / Canvas / Audio 状态
  → 输出一帧

这条链路决定了 HyperFrames 的工程重点：每一帧都必须能够从时间和输入稳定推导出来，而不能依赖“刚才播放到了哪里”。

先分清三个对象：composition、clip 和 timeline

HyperFrames 的概念不多，但每个概念的责任边界很窄。把它们混在一起，代码通常还能在浏览器里动起来，到了逐帧渲染就会暴露问题。

对象	负责什么	不负责什么
composition	定义一张画布、总时长、嵌套关系和变量入口	不直接决定每个媒体的解码位置
clip	描述一个媒体或视觉单元何时出现、持续多久、在哪个 track	不负责动画曲线和 DOM 状态变化
timeline	在给定时间计算元素的属性、路径、透明度或变换	不接管媒体播放和 clip 的可见性

composition 是可组合的时间容器。最外层通常是一个带有 data-composition-id 的根节点；子 composition 通过 data-composition-src 加载，再由框架把自己的局部时间映射到父级时间。

clip 是时间轴上的离散单元。一个最小的视频片段可以这样写：

<video
  id="intro"
  data-start="0"
  data-duration="4"
  data-track-index="0"
  src="./assets/intro.mp4"
>video>

data-start 和 data-duration 描述的是“它占据时间线的哪一段”，不是 CSS 动画的起止值。data-track-index 主要表达视觉层级和 Studio 中的轨道归属；它不是一个“同轨道绝对不能重叠”的播放锁。

timeline 则处理另一件事：在当前时间点，标题应该位于哪里，遮罩应该有多大，光晕应该有多亮。以 GSAP 为例，HyperFrames 要求 composition 注册一个 paused timeline：

window.__timelines['intro'] = gsap.timeline({ paused: true })
  .fromTo('#title', { x: -48, opacity: 0 }, {
    x: 0,
    opacity: 1,
    duration: 0.8,
    ease: 'power2.out',
  });

这里的关键字是 paused: true。播放循环不由 GSAP 自己推进，而由框架在渲染第 n 帧时把 timeline 定位到对应时间。这样，渲染第 300 帧和从头播放到第 300 帧，应该得到同一个视觉状态。

HTML 为什么适合做视频的源代码

HTML 的优势不在于它比专业剪辑软件“更强”，而在于它能把视频里常被藏在时间轴 UI 里的信息，变成可检查的文本结构。

例如下面的片段同时表达了三个事实：主画面从第 4 秒开始，片尾紧接着主画面，字幕和主画面在两个视觉层级上叠加。

<div
  data-composition-id="demo"
  data-width="1920"
  data-height="1080"
  data-duration="12"
>
  <video id="main" data-start="0" data-duration="8" data-track-index="0" src="main.mp4">video>
  <img id="outro" data-start="main" data-duration="4" data-track-index="0" src="outro.png" />
  <div id="caption" class="clip" data-start="main" data-duration="4" data-track-index="1">
    See you next time
  div>
div>

data-start="main" 是相对时间引用：outro 在 main 结束时开始。它比手写 8 更接近编辑意图，也减少了前面片段改时长后留下的魔法数字。

但“声明式”不等于“所有东西都写成属性”。HTML 负责描述结构和媒体窗口，脚本负责画面内部的连续变化。这个分工让检查器可以分别回答两个问题：时间轴是否完整，动画是否可以被 seek。

最关键的原理：seek，而不是播放

普通网页动画通常依赖 requestAnimationFrame：浏览器上一帧结束后，下一帧再推进一点时间。视频渲染需要反过来：给定目标时间，系统直接跳到目标状态。

这会带来三个约束。

不能读取真实时钟

以下写法在浏览器里很自然，在逐帧渲染里却没有稳定含义：

1 2	const drift = performance.now() % 1000; el.style.transform = `translateX(${drift}px)`;

同一帧在不同机器、不同负载下会得到不同结果。渲染器需要的是 state = f(input, time)，而不是 state = f(input, wallClock)。

随机数必须可复现

粒子、噪声和装饰可以使用随机分布，但随机种子必须固定，或者在初始化时根据稳定输入生成。未设种子的 Math.random() 会让截图对比、失败重试和缓存失去意义。

无限循环必须有边界

一个永不结束的 CSS 或 GSAP 循环无法告诉渲染器总时长。需要明确的 data-duration 或有限的重复次数；“看起来一直动”不等于“渲染器知道渲染到哪里”。

所以 HyperFrames 的动画不是“播放一段 tween”，而是“注册一套时间到状态的映射”。这也是为什么一个动画 timeline 可以早于 composition 结束，也可以超过 composition 时长：最终输出长度由 composition 的 duration contract 决定，timeline 超出的部分会被截断，timeline 提前结束则保持最后状态。

媒体为什么必须由框架接管

video.currentTime 和 audio.currentTime 看起来也是普通 DOM 属性，但媒体解码有自己的缓冲、关键帧和异步状态。若让业务脚本自行播放媒体，截图时可能出现“DOM 已经到第 5 秒，视频还停在第 4.8 秒”的竞态。

HyperFrames 的做法是把媒体当作有时间窗口的资源：

<video
  id="broll"
  data-start="2"
  data-duration="5"
  data-media-start="13.5"
  src="broll.mp4"
>video>

这里的 data-start="2" 表示它在 composition 的第 2 秒出现；data-media-start="13.5" 表示出现时从源文件的 13.5 秒开始读。两者分别属于“时间线坐标”和“源媒体坐标”，不能混用。

这也解释了一个常见 lint 错误：不要给 video 和它的 timed ancestor 同时设置 data-start。如果外层 wrapper 已经移动了时间窗口，内层 video 再移动一次，渲染器在计算媒体起始位置和可见性时会得到两套不一致的坐标。

音频还有一个容易被忽略的 contract：每个都应有唯一 id。没有 id 的音频可能无法被 mixer 发现，最终画面正常但输出无声。这类问题不是“音频文件坏了”，而是资源没有进入框架的媒体管理边界。

两层结构：声明层和表现层

我更愿意把 HyperFrames composition 看成两层：

声明层：HTML + data-* attributes
  解决“有什么、何时出现、从源文件哪里开始”

表现层：CSS / SVG / Canvas / GSAP / WebGL
  解决“当前时刻长什么样”

声明层应该尽量简单、稳定、可读。表现层可以复杂，但必须满足 seek-safe 和 deterministic 的要求。

例如，淡出字幕时应该动画字幕内部节点的 opacity，而不是用 GSAP 把 .clip 自己设置成 visibility: hidden。clip 的可见性由时间窗口负责；Runtime 需要知道它什么时候仍然存在，才能正确组合轨道和子 composition。

同理，CSS 的初始 transform 和 GSAP 对同一属性的 tween 也不应互相竞争。更稳妥的写法是把初始状态写进 fromTo，让唯一的动画 Runtime 成为状态来源：

gsap.fromTo(
  '#card',
  { x: -40, opacity: 0 },
  { x: 0, opacity: 1, duration: 0.6 },
);

这不是语法偏好，而是为了避免“浏览器首次布局值”和“时间轴首帧值”在不同阶段互相覆盖。

子 composition 解决的是复用，不是逃避时间

当一个视频由片头、主体、解释卡片和片尾组成时，把所有 DOM 塞进一个 HTML 文件很快会失去边界。子 composition 可以把每个场景封装成独立模板，再由父级按时间组合。

但子 composition 仍然必须是完整的时间函数。父级传入实例变量、素材或起始时间后，子级的 timeline 仍然要能在任意目标时间被直接求值。不能假设“父级一定从 0 秒开始顺序播放”，否则单独预览、拖动时间轴和并行渲染都会产生差异。

一个实用的拆分标准是：如果场景有自己的素材、变量、动效和验收条件，就值得成为 composition；如果只是同一场景里的一块装饰，不要为了文件数量而拆分。

从原理推导出的验证顺序

HyperFrames 项目的验证应该沿着渲染链路进行，而不是只看页面能否打开。

先查结构。 根节点是否有唯一的 data-composition-id、尺寸和可推导的总时长？所有媒体是否有 id？
再查时间。 clip 的 data-start、data-duration、相对引用和嵌套偏移是否符合预期？是否给媒体套了重复的 timed wrapper？
再查 Runtime。 window.__timelines[id] 是否与 composition id 一致？timeline 是否 paused、有限、可 seek？
再查视觉状态。 在 0%、50%、100% 等中间点做 snapshot，而不是只看首帧和末帧。
最后查媒体与声音。 视频是否从正确的 data-media-start 开始，音频是否被 mixer 发现，轨道叠加和音量是否符合预期。

常用命令可以概括为：

npx hyperframes lint
npx hyperframes check
npx hyperframes snapshot --at 0,50%,100%
npx hyperframes render --output output.mp4

check 通过只说明当前 contract 和审计项没有发现问题，不等于已经完成完整的观感验收。真正交付前仍应检查代表性帧、完整播放、字体加载、媒体源和输出音轨。

三个看似合理、实际危险的做法

把 HyperFrames 当成录屏器

录屏只关心屏幕此刻显示什么；HyperFrames 需要知道每个元素为什么在这一帧出现。把所有动画塞进 setInterval 或依赖用户拖动，短期能出片，长期无法复现。

修复方向： 把时间窗口写进 data-*，把连续变化写进可 seek 的 Runtime。

用 timeline 控制视频播放

timeline 适合控制 DOM 属性，不适合替代框架对媒体时间的统一管理。视频的源时间、关键帧和音画同步有自己的 contract。

修复方向： 用 data-media-start 和 data-duration 描述媒体窗口，让 timeline 只做画面表现。

只验证“浏览器里看起来对”

交互式预览允许很多隐式状态存在：字体已经缓存、视频刚好播放到某个位置、上一段动画留下了 inline style。逐帧渲染会把这些隐式依赖暴露出来。

修复方向： 使用 lint、check、snapshot 和最终 render 组成验证链，并保留代表性帧作为回归样本。

要不要用 / 我的判断框架

值得上：视频画面本身就是 UI、网页、代码、图表、字幕或可复用组件；团队希望用 Git 管理时间线，并且需要精确到帧的渲染、批量生成或自动化验证。

可以再等：任务只是一次简单剪辑，素材和转场已经在成熟的 NLE 中完成，用 HTML 表达反而增加工程成本。

重点关注：不要先问“HyperFrames 能不能替代剪辑软件”，先问项目是否需要可组合、可寻址、可复现的画面状态。如果答案是肯定的，HTML 就不再只是展示层，而可以成为视频的 source of truth；如果答案是否定的，继续使用传统时间线工具通常更直接。

HyperFrames 最值得借鉴的地方，也许不是某个 CLI 命令，而是这条边界：把结构、时间、媒体和表现分别交给最适合它们的系统，再用确定性渲染把四者重新合成一帧。

参考资料：

本文使用 writting-skill 辅助写作。项目已开源，欢迎在 GitHub 点个 Star。

Bearer Token Authentication 到底是什么：从 Authorization Header 到安全验证

2026-09-17T07:43:17.000Z

最近在给桌面 Agent 接入 API 时，我遇到一个很基础、也很容易混淆的问题：请求头里写的 Bearer 到底叫什么，它是在证明用户身份，还是只是在携带一段 Token？

标准写法是：

1	Authorization: Bearer

这里没有连字符。Bearer 后面必须是空格，再跟 Access Token。它对应的标准名称是 Bearer Token Authentication，更准确地说，是 HTTP Authorization Header 中的 Bearer Authentication Scheme。

一句话总结

Bearer Token 的核心规则是“谁持有，谁就能使用”。 Resource Server 通常不要求调用方再证明自己掌握某个私钥，因此 Token 一旦泄露，攻击者就可能直接重放。

这也是 Bearer Token 最重要的工程边界：它很好用，但安全性高度依赖 HTTPS、短有效期、最小权限、安全存储和严格验证。

Bearer 到底是什么意思

RFC 6750 对 Bearer Token 的定义很直接：任何持有 Token 的参与方，都可以用它访问 Token 对应的资源，不需要额外证明自己持有某个密码学密钥。

可以把它理解为一张临时门禁卡：

Authorization Server 签发门禁卡。
Client 保存门禁卡，并在访问 API 时出示。
Resource Server 检查门禁卡是否有效、是否过期、是否属于自己、权限是否足够。
检查通过后，Resource Server 返回受保护资源。

这个比喻只解释“持有即使用”。实际系统仍然要检查 Token 的签名、Issuer、Audience、有效期和 Scope，不能看到一段字符串就放行。

正确的请求格式

客户端应优先把 Access Token 放进 Authorization Header：

1
2
3

GET /api/orders/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjIwMjYtMDkifQ...

用 curl 调用时：

1 2	curl https://api.example.com/api/orders/123 \ -H "Authorization: Bearer $ACCESS_TOKEN"

在浏览器或 Node.js 中使用 fetch：

const response = await fetch('https://api.example.com/api/orders/123', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const order = await response.json();

RFC 6750 还描述了 Form Body 和 URI Query 两种传递方式，但同一个请求不能同时使用多种方式。URI Query 尤其不推荐：URL 可能进入浏览器历史、反向代理、监控系统、访问日志和 Referer，泄露面远大于 Header。

1 2	不推荐：GET /api/orders/123?access_token=xxx 推荐： Authorization: Bearer xxx

Bearer、JWT、OAuth 2.0 不是同一个概念

Bearer 经常和 JWT、OAuth 2.0 一起出现，但三者不在同一层。

名称	所在层次	解决的问题
Bearer	HTTP Token 使用方式	Client 如何向 Resource Server 出示 Token
Access Token	授权凭证	当前 Client 被允许访问什么资源、持续多久
JWT	Token 编码格式	如何在一个可签名的数据结构中携带 Claims
OAuth 2.0	授权框架	Client 如何取得授权并获得 Access Token
OpenID Connect	身份协议	在 OAuth 2.0 之上表达用户登录和身份信息

Bearer Token 可以是 JWT，也可以是一段不可读的随机字符串。后者通常称为 Opaque Token，Resource Server 需要通过 Token Introspection 或内部查询确认它的状态。

反过来也成立：JWT 不一定是 Bearer Access Token。ID Token、内部事件签名和一次性声明都可以使用 JWT 格式。Resource Server 不能因为字符串长得像 xxx.yyy.zzz，就把它当作合法 Access Token。

Bearer 与其他鉴权方式有什么区别

方式	请求中携带什么	主要特点	常见场景
Bearer Token	Access Token	持有即可使用，适合短期授权	OAuth API、移动端、Agent、服务调用
Basic Authentication	用户名和密码的 Base64 编码	简单，但每次请求都暴露长期凭证	内部工具、兼容旧系统
API Key	应用或调用方的固定 Key	易于接入，身份与权限模型通常较粗	开放 API、服务集成
Session Cookie	服务端 Session ID	浏览器自动携带，需要处理 CSRF	传统 Web 登录
mTLS / DPoP	Token 加客户端密钥证明	被盗 Token 不一定能被单独重放	高安全 API、金融与关键基础设施

Bearer Token Authentication 只说明 Token 怎样被呈现，不自动回答 Token 怎样签发、撤销、刷新和绑定用户。完整系统至少还需要 Authorization Server、Resource Server、权限模型和密钥管理。

一次完整的 Access Token 生命周期

1. Client 获取 Access Token

在 OAuth 2.0 中，Client 通过 Authorization Code、Client Credentials 等流程向 Authorization Server 换取 Access Token。返回结果通常类似：

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "orders:read orders:write",
  "refresh_token": "opaque-refresh-token"
}

access_token 用于调用 Resource Server；refresh_token 只发给 Authorization Server 换取新的 Access Token，不应该被发送到业务 API。

2. Client 调用 Resource Server

1	Authorization: Bearer

Client 不应把 Token 写进 URL、日志、错误上报或公开配置。跨服务转发时也不能默认原样透传，需要确认下游服务是否属于 Token 的 Audience。

3. Resource Server 验证 Token

对于 JWT Access Token，至少检查：

检查项	防止什么问题
签名与允许的算法	Token 被伪造、篡改或算法降级
`iss`	接受了不受信任的签发方
`aud`	把签给其他 API 的 Token 拿来重放
`exp`、`nbf`	使用已过期或尚未生效的 Token
`scope` / permission	Token 有效，但没有当前操作权限
Token 类型	把 ID Token、Refresh Token 当成 Access Token

只执行 Base64 Decode 没有任何安全意义。Decode 只能读取 Claims，不能证明 Claims 没被修改。

4. Resource Server 返回标准错误

缺少或无效 Token 通常返回 401 Unauthorized；Token 有效但权限不足返回 403 Forbidden。RFC 6750 还定义了 WWW-Authenticate Header：

1 2	HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="api", error="invalid_token"

1 2	HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer realm="api", error="insufficient_scope", scope="orders:write"

这比只返回一段模糊的 JSON 更利于 Client 判断应该重新登录、刷新 Token，还是提示用户缺少权限。

Node.js 实战：验证 JWT Bearer Token

这个最小 Resource Server 使用 Express 和 jose，从受信任的 JWKS 地址获取公钥，并验证 JWT 的签名、Issuer 和 Audience。

1. 安装依赖

1 2	npm install express jose npm install -D typescript tsx @types/express

准备环境变量：

1
2
3

export AUTH_ISSUER="https://auth.example.com/"
export AUTH_AUDIENCE="https://api.example.com"
export AUTH_JWKS_URL="https://auth.example.com/.well-known/jwks.json"

JWKS 地址必须来自配置或可信的 Issuer Metadata，不能读取 Token Header 里的任意 jku 后直接请求。Token Header 属于攻击者可控输入。

2. 编写 Bearer Middleware

import express, { type NextFunction, type Request, type Response } from 'express';
import { createRemoteJWKSet, jwtVerify, type JWTPayload } from 'jose';

const issuer = process.env.AUTH_ISSUER!;
const audience = process.env.AUTH_AUDIENCE!;
const jwksUrl = process.env.AUTH_JWKS_URL!;

const JWKS = createRemoteJWKSet(new URL(jwksUrl));

type AuthenticatedRequest = Request & {
  auth?: JWTPayload;
};

function readBearerToken(header: string | undefined): string | undefined {
  if (!header) return undefined;
  const match = /^Bearer +([^\s]+)$/i.exec(header.trim());
  return match?.[1];
}

async function authenticateBearer(
  req: Request,
  res: Response,
  next: NextFunction,
) {
  const token = readBearerToken(req.header('authorization'));

  if (!token) {
    res.setHeader('WWW-Authenticate', 'Bearer realm="api"');
    return res.status(401).json({ error: 'unauthorized' });
  }

  try {
    const { payload } = await jwtVerify(token, JWKS, {
      issuer,
      audience,
      algorithms: ['RS256'],
      requiredClaims: ['exp'],
      clockTolerance: 5,
    });

    (req as AuthenticatedRequest).auth = payload;
    return next();
  } catch {
    res.setHeader(
      'WWW-Authenticate',
      'Bearer realm="api", error="invalid_token"',
    );
    return res.status(401).json({ error: 'invalid_token' });
  }
}

const app = express();

app.get('/api/profile', authenticateBearer, (req, res) => {
  res.json({ subject: (req as AuthenticatedRequest).auth?.sub });
});

app.listen(3000, () => {
  console.log('Resource Server listening on http://localhost:3000');
});

jwtVerify 会完成签名验证，并根据配置检查标准 Claims。生产代码还应校验所使用 Authorization Server 对 Access Token 规定的 typ、Scope Claim 名称和其他约束；不同 Provider 的 Claims 契约不完全相同。如果双方采用 RFC 9068 的 JWT Access Token Profile，还应要求 typ=at+jwt，防止把 ID Token 当成 Access Token。

3. 增加 Scope 授权

身份验证通过不等于拥有所有权限。可以在同一条路由上继续检查 Scope：

function requireScope(requiredScope: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    const auth = (req as AuthenticatedRequest).auth;
    const scopes = String(auth?.scope || '')
      .split(' ')
      .filter(Boolean);

    if (!scopes.includes(requiredScope)) {
      res.setHeader(
        'WWW-Authenticate',
        `Bearer realm="api", error="insufficient_scope", scope="${requiredScope}"`,
      );
      return res.status(403).json({ error: 'insufficient_scope' });
    }

    return next();
  };
}

app.delete(
  '/api/orders/:id',
  authenticateBearer,
  requireScope('orders:delete'),
  (req, res) => {
    res.status(204).end();
  },
);

实际项目还需要把 sub 映射到用户或服务主体，并在业务层检查资源归属。例如拥有 orders:write 不代表可以修改任意用户的订单。

4. 验证三条关键分支

# 缺少 Token：预期 401，并返回 WWW-Authenticate: Bearer
curl -i http://localhost:3000/api/profile

# 无效 Token：预期 401 + invalid_token
curl -i http://localhost:3000/api/profile \
  -H "Authorization: Bearer invalid-token"

# 有效但缺少 Scope：预期 403 + insufficient_scope
curl -i -X DELETE http://localhost:3000/api/orders/123 \
  -H "Authorization: Bearer $READ_ONLY_ACCESS_TOKEN"

验证时不要只看 JSON Body。HTTP Status 与 WWW-Authenticate Header 同样属于协议契约。

生产环境最容易犯的错误

把 JWT Decode 当成 Verify

任何人都能构造 JWT Payload。Resource Server 必须验证签名，并固定可信 Issuer、Audience 与允许算法。

把 Token 放进 URL

URL 会穿过太多系统。即使业务日志主动脱敏，浏览器历史、代理、CDN、APM 或错误追踪仍可能留下完整 Query String。

让 Access Token 永不过期

长期 Bearer Token 接近长期密码。优先使用短期 Access Token，并为 Refresh Token 配置 Rotation 或 Sender Constraint。

只验证“有效”，不验证“给谁”

签名有效只说明 Token 来自某个密钥，不说明它是签给当前 API 的。aud 校验用于阻止 Token Redirect 和跨服务误用。

应用日志、网关日志和异常上下文都应脱敏 Authorization、Cookie、Refresh Token 等字段。排障通常只需要 Token 的哈希摘要、kid、Issuer、Subject 和错误类型。

用设备 ID 代替 Bearer Token

设备序列号、随机安装 ID 和浏览器指纹可以帮助审计来源，但它们通常不是服务端签发、可过期、可限制 Scope 的安全凭证。它们回答“可能来自哪个安装实例”，不能独立证明“调用方被授权访问什么”。

2026 年还要继续用 Bearer Token 吗

Bearer Token 仍然是主流且实用的 API 访问方式。它的优势是协议简单、工具链成熟、跨语言互操作好。多数普通业务 API，只要做到 HTTPS、短有效期、Audience 限制、最小 Scope、可靠密钥轮换和日志脱敏，就能建立清晰的安全边界。

高价值数据、金融操作或泄露后影响很大的 API，需要进一步考虑 Sender-Constrained Access Token。RFC 9700 建议使用 mTLS 或 DPoP 等机制，把 Token 绑定到特定发送方，从而降低被盗 Token 单独重放的风险。

要不要用：我的判断框架

值得用

系统已经有 OAuth 2.0 / OIDC Provider，需要为 Web、移动端、CLI、Agent 或服务间调用提供统一 API 授权；团队能够管理 Token 生命周期、Scope、Audience 和密钥轮换。

可以简化

单体 Web 应用只有浏览器页面和同域后端，成熟的 Server Session + Secure、HttpOnly、SameSite Cookie 可能更直接。不要为了“前后端分离”机械引入一套不完整的 OAuth 系统。

需要升级

Token 一旦泄露就可能造成重大损失，或 API 跨越不可信终端和网络边界时，应评估 DPoP、mTLS、BFF、Token Exchange 和更严格的 Audience 隔离。Bearer 的易用性来自“持有即可使用”，风险也来自同一个性质。

我的判断是：Bearer Token 适合做短期、最小权限、可验证的访问凭证，不适合充当永不过期的万能身份。

参考资料

本文使用 writting-skill 辅助写作。项目已开源，欢迎在 GitHub 点个 Star。

从 rcedit 到 resedit：给 Bun 单文件 EXE 修改 VERSIONINFO 的兼容层设计

2026-09-01T10:44:35.000Z

最近在精简一个 Windows 发行版时，我看到源码目录里放着一个 rcedit-x64.exe。它不属于产品业务，也不会在应用运行时被调用，却跟着发行版源码保存了很多年。

最初的问题只是“这个文件能不能删”。继续追下去，问题变成了三个：谁负责修改 Windows 可执行文件的图标和版本信息？这类工具应该留在发行版，还是归构建框架管理？如果迁移到官方建议的 resedit，它能不能安全处理 Bun 生成的单文件 EXE？

这次迁移最后没有停在替换依赖。resedit 确实可以取代 rcedit.exe 的资源编辑职责，但 Bun 在 PE 末尾增加了自己的 .bun section，触发了底层解析库的保护性报错。要兼容它，必须先理解 PE 的结构，再把“兼容”写成可验证的不变量。

一句话总结

Windows PE 是 .exe、.dll 等文件使用的结构化容器。版本信息和图标通常位于 .rsrc，Bun 的单文件程序还会带有保存 Runtime 与应用 payload 的 .bun section。

迁移到 resedit 时，可靠的做法是只允许已知的 Bun 布局，并在写回前证明：除资源以外的 section，其虚拟地址、大小、属性和内容都没有变化。

Windows PE 是什么

PE 的全称是 Portable Executable。按照 Microsoft 的 PE/COFF 规范，它是 Windows 家族操作系统使用的 executable image 和 object file 格式。常见的 .exe、.dll、.sys 都建立在这套结构上。

把 PE 理解成“Windows Loader 能读懂的带目录容器”会比较直观。文件内部不只是一段连续的机器码，而是由 Header、Section Table 和多块 section 共同组成：

组成部分	作用
DOS Header / PE Header	声明文件身份、目标架构、section 数量等基础信息
Optional Header	记录入口地址、Image Base、对齐方式和 Data Directory；名字叫 Optional，但 executable image 通常离不开它
Section Table	描述每个 section 的名称、磁盘位置、内存地址、大小和访问属性
Sections	保存代码、只读数据、可写数据、资源、重定位信息以及工具自定义 payload

常见 section 如下：

Section	通常保存什么
`.text`	可执行机器码
`.rdata`	只读数据
`.data`	可写数据
`.rsrc`	图标、字符串、Dialog、Manifest、`VERSIONINFO` 等资源
`.reloc`	Image 无法加载到首选地址时需要使用的重定位信息
`.bun`	Bun 单文件 executable 使用的自定义 payload section

.rsrc 内部也有严格结构。Windows 按 Type、Name、Language 组织资源树，最终叶子节点指向资源数据。资源编辑工具必须解析这棵树、修改指定节点，再重新生成合法的 section。

RVA 和磁盘 offset 不是一回事

理解 PE 修改风险，还需要分清两个位置概念。

PointerToRawData 表示一块 section 在磁盘文件里的位置。前面的 .rsrc 变大后，后续 section 在文件中的 raw offset 可以顺延，只要 Section Table 同步更新即可。

VirtualAddress 通常用 RVA 表示，是 image 映射进进程地址空间后，相对 Image Base 的地址。代码、数据和 Loader 读取的目录会依赖这些地址。修改资源时如果无意中移动后续 section 的 RVA，就会改变 executable 的内存布局。

因此，磁盘 offset 变化不一定是错误；非资源 section 的 RVA、大小或内容变化，则必须高度警惕。

VERSIONINFO 保存了什么

Windows 文件资源管理器中“详细信息”页显示的 Product name、File description、Company、File version、Product version，主要来自 PE 资源里的 VERSIONINFO。

这也是 rcedit 长期存在的原因。构建 Electron 或其他 Windows 应用时，可以在命令行里修改图标、Manifest 和版本字段，不必手写 .rc 文件并重新链接整个程序。

2026 年 4 月，Electron 团队将 rcedit 仓库归档，并在 No Longer Maintained 中说明：Electron 的内部程序化使用已经迁移到 resedit，仍依赖 node-rcedit 的项目也可以将它作为替代方案。

resedit 的边界更适合现代 JavaScript 构建链。它以 JavaScript/TypeScript 实现，可以在 Node.js 和 Web bundler 环境中运行，不需要在仓库里额外保存一个 rcedit-x64.exe。调用方可以直接读取 PE、修改 VersionInfo，再生成新的 binary。

import * as ResEdit from 'resedit'

const executable = ResEdit.NtExecutable.from(binary)
const resources = ResEdit.NtExecutableResource.from(executable)
const [versionInfo] = ResEdit.Resource.VersionInfo.fromEntries(
  resources.entries,
)

versionInfo.setFileVersion('1.2.3.0', 1033)
versionInfo.setProductVersion('1.2.3.0', 1033)
versionInfo.setStringValues(
  { lang: 1033, codepage: 1200 },
  {
    ProductName: 'Example Runway',
    FileDescription: 'Example Runway',
    CompanyName: 'Example Inc.',
  },
)

不过，换成 JavaScript library 不等于自动获得安全性。resedit 自己的 README 也提醒，修改或签名 executable 的覆盖测试仍有限，调用方应谨慎检查输出文件。构建系统不能把“API 没报错”当成交付证据。

为什么 Bun 让迁移复杂了一步

Bun 支持用 bun build --compile 把 JavaScript 或 TypeScript 与 Runtime 一起编译成单文件 executable，也支持生成 Windows x64 目标。Bun 生成的 PE 除了常规 section，还包含保存自身数据的 .bun section。

在实际生成的 Windows x64 文件中，资源附近出现了 .rsrc → .reloc → .bun 的顺序。

原始 resedit 解析这份文件时会抛出错误：

1	After Resource section, sections except for relocation are not supported

这条异常来自 resedit 底层 PE library 的保守假设：资源 section 之后只接受 relocation，并不表示 Bun executable 已损坏。普通链接器常把 .rsrc 和 .reloc 放在靠后位置，但 PE 规范允许工具定义自己的 section；Bun 恰好在后面保留了 .bun。

Bun 本身也提供 --windows-title、--windows-version、--windows-publisher 等 metadata 参数，但 Bun executable 文档明确指出，这些参数依赖 Windows API，当前不能用于 cross-compiling。对于需要在 macOS 上交叉生成 Windows artifact 的 host-neutral 构建链，它不是完整替代。

于是出现了一个容易做错的选择：为了让 resedit 继续运行，直接删掉检查、忽略所有后续 section。这样能消除异常，却无法证明 .bun payload 没被移动或重写。

兼容层的设计：先定义不能变的东西

这次实现采用 fail-closed 策略。只有同时满足以下条件，兼容路径才会启用：

PE 中存在资源 section。
.rsrc 之后除了 .reloc，只多出一个 .bun。
写入新资源后，整个 image 的虚拟大小不变。
所有非资源 section 的名称、RVA、virtual size、raw size、attributes 和二进制内容不变。
重新解析输出文件后，所有目标 VERSIONINFO 字段与预期值一致。

遇到 .custom 等未知 section，构建立即失败；资源内容过长，导致后续虚拟布局需要移动时，构建同样失败。这两种情况都不会覆盖原始 executable。

第一步：记录布局快照

资源写入前，构建工具遍历所有非资源 section，保存它们的结构和内容：

function snapshotExecutableLayout(executable, resourceSection) {
  return {
    imageSize: executable.newHeader.optionalHeader.sizeOfImage,
    sections: executable
      .getAllSections()
      .filter((section) => section !== resourceSection)
      .map((section) => ({
        name: section.info.name,
        virtualAddress: section.info.virtualAddress,
        virtualSize: section.info.virtualSize,
        sizeOfRawData: section.info.sizeOfRawData,
        characteristics: section.info.characteristics,
        data: Buffer.from(section.data),
      })),
  }
}

这里刻意没有把 PointerToRawData 设为不变量。.rsrc 增长时，后续 section 在磁盘文件中的位置可以移动；只要 PE Header 正确反映新位置，Loader 仍能读取它。兼容层需要锁住的是虚拟布局与 payload 内容。

第二步：只绕过一个已知假设

兼容层不会修改或删除 .bun。它只在 NtExecutableResource.from() 执行保守顺序检查时，暂时从 getAllSections() 的返回值中隐藏唯一的 .bun section。资源解析结束后立即恢复原方法。

这个处理范围很窄：放行的是已经识别并验证过的 Bun 布局，不是把任意 PE 都交给宽松解析器。

第三步：写入后逐项比对

resedit 生成新资源后，构建工具再次读取所有 section。只要 section 数量、对象、名称、RVA、大小、属性或内容有一项变化，就拒绝生成 artifact。

随后把完整输出重新解析一次，检查 FileVersion、ProductVersion、ProductName、FileDescription、CompanyName、InternalName 和 OriginalFilename。只有结构保护和业务字段验证同时通过，才覆盖构建目录里的 executable。

这类兼容层的价值不在于“支持 Bun”这个结果，而在于把成功条件写成了机器可以拒绝的契约。

测试不能只看文件属性页

Windows 文件属性页能证明目标字段可见，却不能证明其他 section 没有受损。测试按四层组织更可靠。

层级	验证内容	能证明什么
合成 PE 回归测试	构造 `.rsrc → .reloc → .bun`，确认原始 `resedit` 失败、兼容层成功	精确复现并覆盖已知冲突
负向结构测试	在资源后放入未知 `.custom` section	未知布局不会被静默放行
资源增长测试	写入超长 metadata	虚拟 section 需要移动时会失败且不覆盖原文件
真实 Bun artifact	交叉编译 Windows x64 executable，写入 metadata，再解析并打包	兼容层能处理 Bun 的真实产物

真实 artifact 验证完成后，仍不能把 macOS 上的结构检查描述成 Windows 原生验收。正式发布还需要在 Windows 上启动 executable、回读 File Properties 或 PowerShell VersionInfo，并在 metadata 修改之后完成 Authenticode 签名。

如果目标 executable 需要 Authenticode，顺序也必须固定：

签名后的 PE 再被修改，原签名就不再对应当前文件内容。resedit 文档同样说明，解析签名文件需要显式选择，而重新生成 binary 会得到未签名输出。因此，资源编辑应处于签名前的构建阶段。

构建工具和发行版应该怎么分工

这次清理还解决了一个 ownership 问题。rcedit-x64.exe 原来位于产品发行版源码目录，看起来像产品运行依赖，实际只服务于 Windows 构建。

更清晰的边界是：

层级	应该拥有的内容
Distribution	品牌名、版本号、publisher、图标等产品输入
Build Kit	PE 解析、资源写入、结构保护、hash 与打包顺序
Target artifact	修改完成的 executable，不包含 `resedit` 或 `rcedit.exe`
Windows release gate	原生启动、File Properties、签名和安装验收

这次落地将 resedit 精确锁定在 3.1.0，作为 Build Kit 的 npm dependency。它参与构建，但不会被复制到 Runway payload，也不会作为一个孤立的 .exe 混入 Browser App。

这种边界比“把工具换成 npm 包”更重要。它决定了依赖由谁升级、兼容问题在哪里修复、最终安装包应该包含什么，以及故障由哪一层负责阻断。

要不要用：我的判断框架

值得迁移到 resedit

项目使用 Node.js/JavaScript 构建链，需要程序化修改未签名 PE 的图标或 VERSIONINFO，并希望移除仓库中的预编译 rcedit.exe，可以优先评估 resedit。Electron 已经给出了明确迁移方向，library API 也更容易接入结构检查和测试。

可以直接使用 Bun 参数

构建始终发生在原生 Windows，Bun 提供的 title、publisher、version、description 和 copyright 已经覆盖需求时，直接使用 Bun metadata 参数更短。此时仍要验证 Bun 版本、目标 executable 和签名顺序。

需要停下来审计

只要 PE 带有未知自定义 section、已经签名、资源增长可能改变虚拟布局，或者发行链没有原生 Windows 验收，就不应该把“生成成功”当成可发布。先建立结构快照、负向测试和重签名路径，再决定是否修改。

这次迁移给我的判断很直接：兼容第三方 binary format，最危险的实现是让异常消失，最可靠的实现是明确哪些变化被允许，并对其余变化全部失败。

参考资料

出品人：俊宁（Aaron），阿里高级工程师、AI 开发者，拥有 10 年研发经验，现专注 AI 应用、Agent、AI Infra 与软件工程，FlyOS 作者。

本文使用 writting-skill 辅助写作，配图使用 better-imagegen 生成。项目已开源，欢迎在 GitHub 点个 Star。

Windows 下 AI 浏览器的最佳启动参数配置

2026-08-26T00:05:15.000Z

最近在检查一套 Chromium-based AI 浏览器的 Windows 安装包时，我遇到了一个很典型的现象：浏览器能打开，但窗口顶部常驻着“不受支持的命令行标记”警告。继续检查桌面快捷方式，才发现安装器把调试期参数一起写进了正式入口。

这类问题很容易被当成“删掉一个 --no-sandbox 就结束”。我的判断更严格：正式发布的浏览器快捷方式，默认应该只有可执行文件路径，不附加任何强制启动参数。 GPU、Remote Debugging、独立 Profile、日志和网络覆盖都有使用场景，但它们应该属于有生命周期、有隔离边界、可审计的诊断或自动化 Profile，而不是用户每天点击的入口。

一句话总结

Windows 下 AI 浏览器的启动参数可以按三类管理：

Production：快捷方式参数为空，使用产品配置、Enterprise Policy 和编译期能力；
Internal Diagnosis：一次问题对应一个隔离 Profile，只临时打开必要日志或单变量实验；
Automation/Eval：由 Harness 创建独立 User Data Directory 和调试通道，运行结束后回收。

参数的专业管理标准不在于“记住更多 flags”，而在于回答四个问题：谁添加、作用于哪些进程、何时移除、用什么证据证明它解决了问题。

为什么 AI 浏览器更不能把参数堆在快捷方式里

普通 Chromium 浏览器已经是 Browser、Renderer、GPU、Network Service、Extension 等多进程系统。AI 浏览器通常还会增加 Extension Service Worker、Native Host、本地模型 Runtime 或 Automation Controller。它们可能共享一次用户任务，但不共享同一种资源模型。

运行层	主要职责	启动参数误配的典型后果
Browser Process	窗口、Profile、权限、进程编排	调试能力常驻，用户状态与测试状态混用
Renderer / Extension Renderer	页面、AI UI、Web 内容执行	GPU、V8、Site Isolation 相关行为被全局改变
Extension Service Worker	工具调度、事件处理、浏览器 API	用浏览器 flags 掩盖生命周期或权限设计问题
Native Host / Local Runtime	本地工具、模型或系统能力	Renderer 的 V8 参数通常解决不了独立进程问题
Automation Controller	测试、Eval、CDP/WebDriver 会话	远程调试端口和真实用户 Profile 变成攻击面

这里有一个很重要的责任边界：浏览器启动参数只能调整 Chromium 接受的那部分 Runtime 行为。 本地模型显存不足、Native Host 内存泄漏、Extension 事件丢失，不能靠给所有 Renderer 加大堆上限来统一“治疗”。跨进程系统如果只剩一把 flags 锤子，最后通常会同时损失安全性、可观测性和问题定位能力。

三套 Profile：先分场景，再选参数

我建议把参数组合当成受管 Profile，而不是散落在 README、快捷方式和聊天记录里的命令片段。

Profile	使用者	Profile 数据	调试能力	生命周期	验收标准
Production	最终用户	默认产品目录	关闭	跟随安装与升级	快捷方式无参数，安全警告为零
Internal Diagnosis	开发、QA、支持人员	每次诊断独立目录	按问题最小开启	收集证据后关闭	能复现问题，移除参数后恢复默认
Automation/Eval	CI、Agent Harness、评测系统	每个 Run 独立目录	Pipe 优先，Port 按需	由 Harness 创建和回收	无 Profile 串扰，无常驻调试端口

Production 的“无参数”不是绝对禁止 Chromium 内部派生子进程参数。Browser Process 启动 Renderer、GPU 等子进程时本来就会生成内部命令行。这里约束的是安装器、桌面快捷方式和用户入口不得额外注入产品级覆盖参数。

参数矩阵：哪些能用，哪些只该出现在实验里

下面这张表可以直接作为 Code Review 和 Release Gate 的基础。

参数或能力	Production	Internal Diagnosis	Automation/Eval	判断
无额外参数	推荐	可作为对照组	可作为基线	正式快捷方式的默认状态
`--no-sandbox`	禁止	仅离线、一次性底层调试	禁止	会移除关键安全边界
`--disable-gpu-sandbox`	禁止	通常也不需要	禁止	不应把 GPU 故障转化为 Sandbox 降级
`--disable-gpu`	不默认使用	GPU 故障 A/B 对照	仅软件渲染基线	关闭硬件加速，不是通用兼容方案
`--remote-debugging-pipe`	禁止	工具支持时可用	推荐由 Harness 管理	不需要常驻 TCP 监听
`--remote-debugging-port`	禁止	受控临时使用	Harness 不支持 Pipe 时使用	必须配独立 `--user-data-dir`
`--user-data-dir=`	用户快捷方式不使用	推荐独立目录	每个 Run 必须唯一	隔离 Cookie、缓存、Extension 和 Local State
`--proxy-server` / `--proxy-pac-url`	优先系统设置或 Policy	可用于网络复现	网络场景测试可用	代理本身也是安全和数据边界
`--ignore-certificate-errors`	禁止	不推荐	不推荐	应安装受控测试 CA，而不是关闭校验
`--enable-logging --v=1`	不常驻	推荐按需使用	失败重试或专项 Trace 使用	日志有成本，也可能包含敏感上下文
`--js-flags=--max-old-space-size=N`	默认不使用	仅用于验证内存假设	可作为明确实验变量	提高上限不等于修复泄漏或减少 RSS
`--single-process`	禁止	不作为真实问题证据	禁止	Chromium 官方文档也提醒它会制造或掩盖问题

Chromium 的 switches 不是面向终端用户承诺稳定的产品配置 API。每次升级 Chromium baseline，都应该重新核对当前源码和真实二进制行为；不能因为某个参数在旧版本“能跑”，就把它永久固化。

GPU：先让 Chromium 自己判断，再做单变量实验

--disable-gpu 的含义很直接：关闭 GPU hardware acceleration；如果软件 Renderer 不可用，GPU Process 甚至不会启动。Chromium 本身已经维护 GPU software rendering list，按 OS、设备、Driver 和已知问题决定哪些能力需要 blocklist。Chrome Enterprise 的 HardwareAccelerationModeEnabled 也明确把默认行为定义为“可用时启用硬件加速”。

所以，遇到虚拟机、Windows Server 或远程桌面环境，正确顺序是：

在 chrome://gpu 记录 GPU、Driver、Feature Status 和 Problems；
更新或回退 Driver，确认 RDP/VM 的图形栈和 Software Renderer 是否可用；
用 --disable-gpu 做一次 A/B 实验，确认症状是否真的来自 GPU 路径；
如果需要长期禁用，使用受管 Policy，并限定到已验证的设备群；
保留启动耗时、页面渲染、视频、WebGL、功耗和 AI UI 的对照结果。

AI Browser 还要多问一句：出问题的是页面合成 GPU，还是本地模型 Runtime 使用的 CUDA、DirectML 或其他推理后端？前者的 flag 不一定影响后者。把两条链路混在一起，会得到“问题偶尔消失，但没人知道为什么”的假修复。

Sandbox：任何正式入口都不该关闭

Chromium 的 Windows Sandbox 设计使用 Restricted Token、Job Object、Desktop Object 和 Integrity Level 限制 Renderer 等不可信进程。它的目的不是消除漏洞，而是限制漏洞能触达的文件、Registry、进程和用户数据。

--no-sandbox 会直接拆掉这层边界。Chromium 的 Debugging 文档虽然把它列为方便附加 Debugger 的手段，同时也明确提醒安全影响；同一份文档还说明 --single-process 不能代表 Chromium 的真实多进程运行方式。

我的规则很简单：

Production、灰度、真实账号验收都禁止 --no-sandbox；
自动化访问真实或不可完全信任的网页时同样禁止；
只有在隔离 VM、无真实 Profile、无生产凭据、无外网数据的一次性底层调试中，才允许把它作为最后手段；
实验结束必须删除启动脚本或让配置自动过期，不能复制进快捷方式。

如果 Sandbox 让 Native Host、文件访问或调试流程失败，优先修复 IPC、Manifest、权限和进程边界。关闭 Sandbox 只会让原本清晰的工程问题变成产品级风险。

Remote Debugging 与 User Data Directory 必须成对管理

Remote Debugging 对 AI Browser 很有用：Agent Eval 可以读取页面、执行操作并收集 Trace。但它也能访问高价值浏览器状态。Chrome 团队披露过攻击者利用远程调试能力窃取 Cookie 的案例，因此从 Chrome 136 开始，--remote-debugging-port 和 --remote-debugging-pipe 在默认 Chrome User Data Directory 上不再生效，必须同时指定非默认目录。官方还建议浏览器自动化使用 Chrome for Testing。这项变更的安全说明值得所有 Chromium Distribution 维护者阅读。

Chromium 的 User Data Directory 文档说明，这个目录不只是缓存，它包含 History、Bookmarks、Cookie、各 Profile 与安装级 Local State。因此：

不把 Remote Debugging 接到用户日常 Profile；
每个并行 Run 使用唯一目录，不共享同一个 C:\Temp\profile；
Harness 优先使用 Pipe；必须用 Port 时，让 Runner 分配和回收，不固定写死 9222；
进程完全退出后再删除目录，避免未刷盘状态和并发损坏；
需要登录态的 Eval 使用专门测试账号和可重建状态，不复制真实用户目录。

Proxy 与证书：保留真实的 Windows 信任边界

Chromium 默认使用系统网络设置。官方的 Network Settings 设计说明同时列出了 --proxy-server、--proxy-pac-url 和 bypass list 等覆盖方式；更完整的 Proxy 文档还解释了 HTTP、HTTPS、SOCKS、DNS 和 fallback 的差异。

正式企业部署应优先使用 Windows 系统配置或 Enterprise Policy，因为管理员能统一审计、撤销和更新。启动参数适合复现“指定 Proxy/PAC 下才失败”的诊断场景，以及明确要求不同网络拓扑的 Eval。

证书则不要走捷径。--ignore-certificate-errors 会让测试越过你真正需要验证的 TLS 行为，既扩大攻击面，也可能把证书链、代理中间人和时间错误一起掩盖。更可靠的做法是在隔离测试机安装受控测试 CA，限定域名和环境，并让用例同时覆盖证书有效、过期、名称不匹配与撤销场景。

Logging 与 Crash：收集证据，不要长期改变运行模式

Windows 下最小的 Chromium 日志组合是 --enable-logging --v=1。官方 Debug Log 指南给出了同样的启动方式；如果增加 --log-file，Chromium 当前实现要求 Windows 使用绝对路径。

日志适合回答“哪个进程、哪个时间点、哪条调用失败”，但不适合永久常驻在用户快捷方式。详细日志可能影响 I/O，也可能记录 URL、Extension ID 或请求上下文。诊断包应该包含采集范围、保存目录、脱敏规则和删除时间。

Crash 处理则应是 Distribution 能力。Chromium 的 Stability 文档说明 Crashpad 会监控 Browser 和子进程，并在用户允许时收集、节流和上传 crash dump。对于没有接入自有 Crash Reporter 的独立 Windows 原生进程，可以临时启用 Microsoft 官方的 WER LocalDumps；需要按异常、挂起或 CPU 条件抓取现场时，可以使用 ProcDump。浏览器已经集成 Crashpad 时应先遵从自身 Crash Reporter 的设计，问题结束后撤销额外采集配置，Dump 也要按敏感数据管理。

V8 Heap：`4096` 不是 AI 浏览器的默认答案

--js-flags=--max-old-space-size=4096 看起来像是“给 AI 页面更多内存”，但 V8 的 flag 定义只说明它设置 Old Space 的最大值，单位为 MB。它不会在启动时立刻分配 4 GB，也不会自动降低 RSS，更不会修复对象长期存活、跨进程重复缓存或 Native Runtime 泄漏。

在多 Renderer 浏览器里，全局放大上限还会改变 OOM、GC 和崩溃出现的时间。原本能快速暴露的泄漏，可能变成更晚、更重的系统内存压力。

只有满足下面条件，我才会保留 V8 Heap 覆盖：

Trace 已证明压力发生在目标 V8 Isolate，而不是 Browser、GPU 或 Native Runtime；
业务工作集有明确上界，正常 GC 后仍需要更大 Old Space；
对照测试覆盖低内存 Windows 设备、长会话、多个 Tab 和 Extension；
参数能限定到目标 Renderer，而不是所有用户和所有页面；
版本升级时重新跑 Memory Regression，而不是永久继承旧数字。

没有这些证据时，空数组或不传 --js-flags 才是更专业的默认值。

三套可直接落地的配置

Production：快捷方式只指向 EXE

1
2
3

Target: "C:\Program Files\Example AI Browser\Application\browser.exe"
Arguments: 
Start in: "C:\Program Files\Example AI Browser\Application"

品牌、更新通道、内置 Extension、Native Host、默认 Policy 和 Runtime 发现应由安装包与产品配置负责。不要用快捷方式参数替代正式配置面。

安装后可以用 PowerShell 直接验收 .lnk：

$shortcutPath = Join-Path $env:PUBLIC 'Desktop\Example AI Browser.lnk'
$shell = New-Object -ComObject WScript.Shell
$shortcut = $shell.CreateShortcut($shortcutPath)

[pscustomobject]@{
  TargetPath       = $shortcut.TargetPath
  Arguments        = $shortcut.Arguments
  WorkingDirectory = $shortcut.WorkingDirectory
}

if (-not [string]::IsNullOrWhiteSpace($shortcut.Arguments)) {
  throw "Production shortcut must not contain arguments: $($shortcut.Arguments)"
}

Internal Diagnosis：隔离 Profile，加最少日志

$browser = 'C:\Program Files\Example AI Browser\Application\browser.exe'
$runRoot = Join-Path $env:TEMP ("ai-browser-diag-" + (Get-Date -Format 'yyyyMMdd-HHmmss'))
$profile = Join-Path $runRoot 'profile'
$log = Join-Path $runRoot 'browser.log'

New-Item -ItemType Directory -Path $profile -Force | Out-Null

& $browser `
  "--user-data-dir=$profile" `
  '--enable-logging' `
  '--v=1' `
  "--log-file=$log"

先用这组配置复现，再按假设一次只增加一个参数，例如 --disable-gpu。同时改变 GPU、Sandbox、Proxy 和 V8 Heap，只能证明“某个组合改变了现象”，不能定位原因。

Automation/Eval：让 Harness 拥有调试通道

下面是 Runner 的配置契约示意，不是直接传给 Chromium 的 JSON：

{
  "binary": "C:\\Program Files\\Example AI Browser\\Application\\browser.exe",
  "profile": "C:\\Temp\\ai-browser-eval\\",
  "debugTransport": "pipe",
  "headless": false,
  "extraArgs": []
}

Harness 负责把 profile 转为独立 --user-data-dir，创建 Pipe 或临时 Port，记录实际 Browser version、参数和 Run ID，并在所有子进程退出后回收目录。ChromeDriver 的 Capabilities 文档也采用这一责任边界：Driver 默认创建临时 Profile，需要自定义时再明确传入 user-data-dir。

Headless 可以提高部分 Eval 的吞吐，但 AI Browser 最终还要有 Headful Release 验收。Extension UI、系统权限提示、Native Host 拉起、GPU 合成和 Windows 窗口行为，都不能只靠 Headless 结果证明。

两种最常见的错误配置

第一种是把所有“可能有帮助”的参数一次加齐：

& $browser `
  '--no-sandbox' `
  '--disable-gpu' `
  '--ignore-certificate-errors' `
  '--remote-debugging-port=9222' `
  '--js-flags=--max-old-space-size=4096'

这条命令同时改变安全隔离、渲染路径、TLS、调试攻击面和内存行为。即使浏览器不崩了，也没有形成可复用结论，更不可能作为 Production 默认值。

第二种是让多个自动化任务共享同一个 Profile 和固定端口。它会带来 Cookie、Cache、Extension 状态和 Service Worker 串扰，还可能让一个 Run 连接到另一个 Run 的 Browser。测试偶尔变快，代价是结果不再可信。

Windows 安装包验收 Checklist

正式发布前，我会把下面这些检查放进自动测试和目标 Windows 真机验收：

Start Menu、Desktop、Taskbar shortcut 的 Arguments 都为空；
首次启动和重启后没有 unsupported command-line flag 警告；
chrome://version 中 Browser Process 没有 --no-sandbox、--disable-gpu、Remote Debugging 或证书绕过参数；
chrome://sandbox 显示 Renderer、GPU 等目标进程处于预期 Sandbox；
chrome://gpu 的 Hardware Acceleration 状态符合 Driver、Policy 和 blocklist 结果；
AI 对话、Extension、Native Host、本地 Runtime 和更新链路分别完成一次真实任务；
Automation Run 使用唯一 Profile，结束后没有残留 Browser、调试端口和目录锁；
日志与 Dump 的采集、脱敏、保留和删除策略可验证；
Installer 升级、修复安装和卸载重装不会把诊断参数重新写回快捷方式；
每次 Chromium baseline 升级后重新跑 GPU、Sandbox、Profile、Automation 与 Memory Regression。

还可以用 CIM 对 Browser Process 做一道自动检查。子进程会带 Chromium 自己生成的 --type= 等参数，因此只筛选没有 --type= 的主进程：

$browserProcesses = Get-CimInstance Win32_Process -Filter "Name='browser.exe'" |
  Where-Object { $_.CommandLine -notmatch '--type=' }

$forbidden = '--no-sandbox|--disable-gpu-sandbox|--ignore-certificate-errors|--remote-debugging-(port|pipe)'
$violations = $browserProcesses | Where-Object { $_.CommandLine -match $forbidden }

if ($violations) {
  $violations | Select-Object ProcessId, CommandLine | Format-List
  throw 'Forbidden production launch argument detected.'
}

把示例中的 browser.exe 换成实际可执行文件名，并在干净安装、升级安装和自动更新后各跑一次。

要不要用：我的判断框架

正式版先做到零强制参数。GPU、Sandbox、Proxy、证书和 V8 Heap 不应因为“某台机器曾经有问题”就变成所有用户的永久配置。

内部诊断值得立即建立标准脚本：独立 Profile、绝对日志路径、单变量实验、自动过期。Automation/Eval 则由 Harness 独占 Remote Debugging 和 Profile 生命周期，参数清单随 Run 进入 Evidence，而不是进入用户快捷方式。

一个参数只有同时回答了“明确故障、最小作用域、回退条件、跨版本验收”四件事，才有资格进入受管配置。其余参数都应该留在实验记录里。生产启动越干净，AI Browser 的 Renderer、Extension、Native Runtime 和自动化边界反而越容易长期维护。

参考资料

本文使用 writting-skill 辅助写作，配图使用 better-imagegen 生成。项目已开源，欢迎在 GitHub 点个 Star。

Omaha 到底是什么：一篇讲清 Chromium 自动更新的客户端、协议与服务端

2026-08-25T02:56:36.000Z

最近在梳理 Chromium 桌面应用的更新链路时，我频繁遇到一个词：Omaha。

它一会儿出现在 Omaha endpoint 里，一会儿又变成 Omaha Protocol、Omaha Server 或 Omaha response。继续查源码，还会遇到 Chromium Updater、update_client、CUP 和 CRX3。如果把这些名字都当成“自动更新”的同义词，很快就会把客户端、协议、服务端和安装制品混在一起。

一句话总结

Omaha 最初是 Google Update 的开源客户端项目；在当今 Chromium 更新语境里，它更常指一套更新协议和云端决策接口。 真正在本机定期检查、下载并安装新版本的，是 Chromium Updater 这类客户端；Omaha Server 回答“这台设备现在应该拿哪个版本、去哪里下载、如何处理”。

所以，一句“我们要接入 Omaha”，至少要继续追问三件事：

是否要编译和定制 Chromium Updater 客户端？
是否要实现 Omaha Protocol 的服务端响应？
更新制品、签名、CDN 和渠道激活由谁产出和管理？

同一个 Omaha，其实指三个不同对象

Google 公开的 Omaha 仓库将它定义为 Google Update 的开源版，用于安装软件并保持更新。这份历史客户端代码以 Windows 为主，仓库已于 2025 年 8 月归档为只读。

现在的 Chromium 源码中，chrome/updater 下的 Chromium Updater 是 Google Update/Omaha/Keystone 的开源可定制替代者，目标平台包括 Windows、macOS 和 Linux。但客户端更名与替换后，它与服务端交流时仍然使用 Omaha Protocol。

对象	是什么	负责什么
Omaha 历史项目	Google Update 的开源客户端	安装软件、周期检查、下载和应用更新
Omaha Protocol	客户端与更新基础设施之间的 HTTP 应用层协议	描述已安装应用、版本、平台、渠道、更新指令和执行结果
Omaha Server	实现协议的更新决策服务	识别 App ID，按版本、平台、渠道或 cohort 返回 `noupdate` 或更新 pipeline

这也解释了为什么 Chromium 文档里会出现“Chromium Updater 轮询 Omaha Server”这种句子：前者是本机执行者，后者是云端决策者。

一次完整的 Omaha 更新发生了什么

Omaha Protocol 4.0 把一次更新会话拆成三个阶段：Update Check、Download 和 Ping-Back。截至 2026 年 8 月 25 日，这份公开文档仍标注为 draft；真正实现时应固定到所使用的 Chromium commit，而不是假设 main 永远不变。

已安装客户端
  │
  ├─ 1. POST 当前 App ID、版本、OS、CPU、渠道
  ▼
Omaha Server
  │
  ├─ 2. 返回 noupdate，或新版本 + 下载/处理 pipeline
  ▼
Download Server / CDN
  │
  ├─ 3. GET 更新 payload，校验大小、hash 与签名
  ▼
Chromium Updater
  │
  ├─ 4. 解包、执行 installer、切换版本
  └─ 5. POST 成功、失败或取消事件

1. Update Check：客户端不只上报一个版本号

客户端先用 HTTP POST 发送更新检查。请求中可以包含多个受管应用，每个应用都有独立的 appid、version、cohort 和 updatecheck。操作系统、CPU architecture、安装范围和前台/后台触发等信息，都可能改变服务端的决策。

下面是一份刻意缩减过的示意请求，用于展示结构，不是可直接投产的完整 payload：

{
  "request": {
    "protocol": "4.0",
    "@updater": "chromium-updater",
    "updaterversion": "148.0.7778.97",
    "os": {
      "platform": "win",
      "arch": "x64"
    },
    "apps": [
      {
        "appid": "{YOUR-APP-ID}",
        "version": "1.2.3.4",
        "cohort": "stable",
        "updatecheck": {}
      }
    ]
  }
}

appid 是更新身份，不是展示名称。版本则是服务端和客户端共同消费的比较值。在 Chromium 发行工程里，我更倾向为它保留一条独立、单调递增的数值版本，而不是直接复用用户看到的 SemVer、npm package version 或 Git tag。它们的消费者和推进条件不同。

2. Server Decision：响应描述的是 pipeline

服务端不会把安装包塞进 Update Check 的 JSON response。它先回答 noupdate 或 ok；当有新版本时，再提供 nextversion 与一组按优先级排列的 pipeline。

在 Protocol 4 中，pipeline 是一系列 operation。它可以表达：

从哪些 URL 下载 payload；
预期的 size 和 SHA-256 hash；
是否经过 xz、Zucchini 或 Puffin 等压缩/差分操作；
如何处理 crx3 并运行安装程序。

服务端可以根据渠道、cohort、平台、当前版本和 rollout 策略对不同设备做不同决策。这才是 Omaha Server 的价值：它不只存放“最新版本”，还决定谁现在应该收到什么。

3. Download 与 Install：CDN 不替你执行更新

客户端收到 pipeline 后，才向 Download Server 或 CDN 发起 HTTP GET。下载成功只能证明一串 bytes 到了本地；Chromium Updater 还要校验大小与 hash，处理 CRX3，执行 installer，并根据 user/system scope 处理权限、进程和安装状态。

Chromium Updater Functional Specification 指出，Updater 接受 CRX3 更新包，包使用 publisher key 签名，相应公钥固化在客户端中；它还可以额外 pin 一枚 public key。在 Windows 上，最终执行的 Updater 与 installer 还应有正确的 Authenticode 签名。

4. Ping-Back：没有回报，发布者就看不到失败发生在哪里

安装尝试后，客户端会把结果回传给 Omaha Server。Protocol 4 为 download、CRX3 安装、installer 和其他 operation 定义了事件类型、结果、error category 与 error code。

这条回路不是装饰性 telemetry。如果只知道新版本文件已经上传，却看不到客户端是在检查、下载、验签、解包还是 installer 阶段失败，更新系统就没有可操作的反馈。

CUP、CRX3 和 Authenticode 为什么一个都不能少

自动更新有一个很高的安全门槛：服务端的一次响应，有机会让大量客户端自动下载并执行代码。TLS 很重要，但 Chromium 的更新链路没有把全部信任都压在 TLS 上。

机制	主要保护的对象	能证明什么	不能代替什么
TLS	HTTP 连接	传输加密和站点身份	不等于 payload 发布者签名
CUP	Update Check 的 request/response 组合	响应完整性、新鲜度，以及对当次请求的绑定	不提供内容保密，不代替包签名
CRX3 publisher signature	更新 payload	包来自客户端信任的 publisher key	不代替 OS 对可执行文件的信任判断
Authenticode	Windows 可执行文件	文件的签名者与签名后完整性	不代替 Omaha 渠道决策或 CUP

CUP 文档对边界写得很明确：它通过 ECDSA key pair 保护请求体和响应体的完整性，并用 nonce 保护响应新鲜度；客户端内置公钥，服务端保存私钥。它不提供请求或响应的保密性，也不保护 HTTP header。

这意味着，自建 Omaha Server 时不能只写一个返回 JSON 的 API。CUP public key 必须在构建期进入客户端 trust root，服务端必须正确保管对应 private key，还要为旧客户端设计 key rotation 与历史 key 兼容。

Omaha 不是 CDN、安装包或“最新版本 JSON”

在工程实践里，最容易跑偏的是用一个 update.json 包办整条更新链路。如果客户端只是拉取：

{
  "version": "1.2.3",
  "url": "https://cdn.example.com/app.exe"
}

这可以是一个自定义 updater 的起点，但它还不是完整的 Omaha 链路。你仍然需要回答：

App ID 和 user/system scope 如何注册、迁移和卸载？
不同 OS、CPU、channel 和 cohort 如何选择制品？
旧客户端如何确认 response 没有被替换？
payload 如何验签，失败如何回退或切换备用 URL？
下载、解包、安装、重启各阶段的错误如何回报？
服务过载时，客户端如何 backoff，避免集体重试把服务压垮？

Omaha Protocol 对这些问题给出了一套经过大规模桌面软件验证的表达方式。但协议完整不等于你的发布系统已经完成：构建、签名、上传、渠道激活和旧客户端验收，仍然是五个独立状态。

自建 Chromium 桌面应用时，哪些东西必须属于你

Chromium Updater 是可定制的，但它不会自动让一个 Chromium fork 拥有自主更新能力。至少要管住下面几类产品身份和发布输入：

输入	为什么必须自有
App ID、company/updater identity	避免与其他 updater 冲突，并让客户端稳定识别已安装产品
Omaha endpoint	把检查请求发到自己控制的决策服务
CUP public/private key	建立客户端与服务端之间的更新指令信任根
CRX3 publisher key	让客户端只接受预期发布者的更新 payload
Code signing identity	满足操作系统对 installer 和 executable 的信任要求
版本、channel 与 cohort 策略	决定谁可以在什么时候升级到哪个版本
不可变 artifact 与可变 descriptor	先固化可回读的制品，再安全激活发布渠道

我的建议是，先画清这些责任边界，再决定服务端是自行实现、使用现成实现，还是采用另一套 updater。先选中一个开源项目，再反推产品 identity 和 key 如何放置，很容易留下无法平滑迁移的历史负担。

要不要用 Omaha：我的判断框架

值得上

你在做 Chromium fork、桌面客户端平台，或者需要一套兼容 Chromium Updater 的服务端；产品有明确的 App ID、多渠道或分批发布需求，也愿意持续管理 key、签名、制品和旧客户端兼容。

可以再等

你只有一个用户规模很小的内部工具，手动下载新版本的成本可接受；或者你还没有稳定的 code signing、artifact storage 和 release process。这时先把“可重复构建 + 正确签名 + 不可变上传”做稳，比匆忙增加 Omaha Server 更有价值。

重点关注

如果决定接入，优先验收一条真实旧客户端链路：发现新版本、验证 CUP response、下载 CRX3、校验 payload、执行已签名 installer、重启后读到新版本，同时保留用户数据。只调通一份 JSON response，证明不了这条链路。

这也是我现在对 Omaha 的最简单理解：它是自动更新的决策与交互契约，不是一个替你完成整条发布的黑盒。

参考资料

本文使用 writting-skill 辅助写作。项目已开源，欢迎在 GitHub 点个 Star。

darwin-arm64、win32-x64、linux-x64 到底是什么：一篇讲清安装包命名

2026-08-24T14:27:09.000Z

最近整理多平台发行物时，我又遇到了一排很像“暗号”的文件名：

tool-v1.8.0-darwin-arm64.tar.gz
tool-v1.8.0-darwin-x64.tar.gz
tool-v1.8.0-win32-x64.zip
tool-v1.8.0-linux-x64-gnu.tar.gz
tool-v1.8.0-linux-arm64-musl.tar.gz

它们其实没有看上去那么乱。每一段都在回答一个兼容性问题：给哪个操作系统、哪种 CPU、哪套运行环境，以及用什么方式分发。

真正容易误解的是，大家常把这些维度混成一句“Windows 有 x64 渠道，Linux 也有”。x64 不是渠道，它是 CPU architecture；stable、beta、nightly 才是 release channel。把两者分开后，大部分安装包命名都能直接读懂。

一句话总结

darwin-arm64 可以读成“面向 Darwin/macOS 平台、使用 64-bit Arm 指令集的构建”；win32-x64 是“面向 Windows 平台、使用 x86-64 指令集的构建”；linux-x64-gnu 则继续补充了“面向 Linux、使用 x86-64，并依赖 GNU/glibc 运行环境”。

我习惯把完整文件名看成一组坐标：

-----.

现实中的项目不一定把字段写全，顺序也可能不同，但背后通常逃不开下面几层：

维度	它回答的问题	常见值
OS / platform	这份程序调用哪套操作系统接口	`darwin`、`win32`、`windows`、`linux`
CPU architecture	CPU 能不能执行这套机器指令	`x64`、`x86_64`、`amd64`、`arm64`、`aarch64`、`ia32`
ABI / runtime	二进制如何调用系统库、传参和链接	`gnu`、`musl`、`msvc`、`gnueabihf`
package format	用什么容器或安装机制交付	`.zip`、`.tar.gz`、`.dmg`、`.msi`、`.deb`、`.rpm`、`AppImage`
release channel	这是哪条发布节奏	`stable`、`beta`、`canary`、`nightly`、`LTS`

OS、CPU 和 ABI 决定“能不能跑”，package format 决定“怎么装”，channel 决定“拿哪条版本线”。

`darwin` 为什么代表 macOS

darwin 不是 Apple 给 macOS 起的下载渠道名，而是 macOS 底层系统家族的名字。

Apple 在 2000 年发布 Darwin 1.0 时，把它描述为 Mac OS X 的 operating system core，其中包括 Mach kernel 和 BSD layers。今天我们日常使用的 macOS 还包含图形界面、Cocoa framework 和大量闭源组件，但在编译器、Unix 工具链和 Runtime 眼里，darwin 仍是一个稳定的平台标识。

这也是为什么 Node.js 的 process.platform 在 Mac 上返回 darwin，Rust 会使用 x86_64-apple-darwin 与 aarch64-apple-darwin，Clang/LLVM 也保留 Darwin 作为 Apple OS family 的 target 名称。

所以：

1 2	darwin-arm64 = macOS 平台 + 64-bit Arm darwin-x64 = macOS 平台 + 64-bit x86

这里的 darwin 决定程序会按照 Apple 平台的 Mach-O、system framework 与 ABI 规则构建；它不表示这份程序能在所有基于 Darwin 的系统上任意互换。macOS、iOS、Simulator 仍可能拥有不同的 platform 与 SDK 边界。

`win32` 为什么也会出现在 64-bit Windows 上

win32-x64 是最容易让人误判的一种组合：前面写着 32，后面又写 64，到底谁算数？

答案是两个字段描述的对象不同：

win32 是 Windows platform/API 家族的历史名称；
x64 才是当前二进制的 CPU architecture。

Microsoft 现在更常使用 “Windows API” 这个名字，但官方文档也说明它过去称为 Win32 API，而且这套 API 同样支持 64-bit Windows。Node.js 沿用了 win32 作为 Windows 的 process.platform 固定值，所以 Electron、Node CLI 和不少 npm native package 会自然产生 win32-x64、win32-arm64 这样的标签。

这几个名字可以这样读：

名称	实际含义
`win32-ia32` / `win32-x86`	Windows + 32-bit x86
`win32-x64` / `windows-x64` / `win-amd64`	Windows + 64-bit x86
`win32-arm64` / `windows-arm64`	Windows + 64-bit Arm

因此，看到 win32 时不要据此判断 CPU 位数。继续找同一文件名里的 ia32、x86、x64 或 arm64，那一段才负责回答架构问题。

`linux` 只是第一层，后面往往还要看 libc

linux-x64 表示 Linux + 64-bit x86，但对包含 native code 的程序来说，这个坐标有时还不够精确。

Linux 生态不像 macOS、Windows 那样由单一厂商提供完整的用户态运行环境。相同的 Linux kernel 之上，可以有不同 distribution、libc、dynamic linker 和 system library 版本。于是发行物里经常继续出现：

x86_64-unknown-linux-gnu
x86_64-unknown-linux-musl
aarch64-unknown-linux-gnu
aarch64-unknown-linux-musl

gnu 通常表示 GNU toolchain / glibc environment，musl 表示 musl libc environment。CPU 和 kernel 都对，libc 不匹配，程序仍可能在启动时报告 dynamic linker 不存在、symbol version 找不到，或者某个 native dependency 无法加载。

.deb、.rpm、AppImage 又是另一层：它们主要描述交付与安装方式。

名称片段	描述对象	不能单独证明什么
`linux-arm64`	OS + CPU	不保证 libc 与最低系统版本兼容
`gnu` / `musl`	libc / ABI environment	不表示 package manager
`.deb` / `.rpm`	package format	不表示 CPU architecture
`ubuntu` / `debian` / `rhel`	distribution compatibility target	仍要继续看版本、CPU 与 library baseline

这也是 Linux 安装包经常比 macOS 多出一截后缀的原因：发布者需要把更多用户态兼容边界写进名字。

`x86`、`x64`、`amd64`、`x86_64` 为什么像一组近义词

这组名字背后是一段很长的兼容历史。

`x86` 来自一串以 86 结尾的处理器

Intel 在 1978 年推出 8086，后续又有 80186、80286、80386、80486。因为这些型号都以 86 结尾，业界逐渐用 x86 指代这一指令集家族。

到了 32-bit 时代，i386、i486、i586、i686 常被用来表达不同代际或最低指令集 baseline。IA-32 则是 Intel 对 32-bit architecture 的正式叫法之一。Node.js 使用 ia32 表示 32-bit x86 构建。

这导致 x86 在不同页面里可能有两种语义：

广义上指整个 x86 family，包含 32-bit 与 64-bit；
下载按钮里常特指 32-bit x86，用来和 x64 区分。

选包时要服从当前下载页的对照关系，不能只凭词源判断。

x86 的 64-bit 扩展最早叫 AMD64

AMD 把传统 x86 扩展到 64-bit，并保持对既有 16-bit、32-bit 软件模型的兼容，这套 architecture 被称为 AMD64。Intel 后来实现兼容的 64-bit architecture，并使用 Intel 64 这个名称。

软件生态于是留下了几种常见写法：

名称	常见生态	一般指向
`x86_64`	Unix、Linux、Clang、Rust、Python wheel	64-bit x86
`amd64`	Debian/Ubuntu、Go、Windows 内部与云镜像	64-bit x86
`x64`	Windows、Node.js、Electron、普通下载页	64-bit x86
`Intel 64`	Intel 官方文档	Intel 对兼容 64-bit x86 的命名

Microsoft 的官方文档直接把 x64 定义为同时包含 AMD64 与 Intel 64。对普通安装包选择来说，x64、amd64、x86_64 通常可以视为同一 instruction-set family 的不同生态写法；到了 compiler flags、calling convention、object format 或 container manifest 层面，仍应使用对应工具链规定的精确字符串。

`arm64` 与 `aarch64` 又是什么关系

Armv8-A 引入了新的 64-bit execution state，Arm 官方称它为 AArch64；对应的 instruction set 是 A64。与它并列的 32-bit execution state 叫 AArch32。

不同生态对同一个 64-bit Arm 家族选了不同标签：

名称	常见位置
`AArch64` / `aarch64`	Arm 文档、Linux `uname`、GNU toolchain、Rust target
`arm64`	Apple、Windows、Node.js、Docker platform、普通下载页

因此，Apple Silicon Mac 下载 darwin-arm64；Rust 对同一类目标使用 aarch64-apple-darwin。它们不是两种互不兼容的 CPU，而是不同工具链对同一 64-bit Arm architecture family 的常用命名。

不过，“同属 AArch64”仍不等于二进制可以跨 OS 直接运行。一个 macOS arm64 Mach-O executable 不能因为 CPU 相同，就直接当作 Linux arm64 ELF executable 使用。OS API、object format、ABI 与 system library 仍然不同。

把短名字展开，就是 target triple

编译器需要比下载页更精确的坐标。Clang/LLVM、Rust 与 GNU toolchain 常用 target triple 描述目标：

1	ARCHITECTURE-VENDOR-OPERATING_SYSTEM[-ENVIRONMENT]

LLVM 官方文档说明，经典形式包含 architecture、vendor、operating system 三段，也可以再加 environment。即使今天经常出现四段，工具链仍沿用 “target triple” 这个历史名称，因为它最初确实只有三个字段。

拆几个真实例子：

Target	Architecture	Vendor	OS	Environment / ABI
`aarch64-apple-darwin`	`aarch64`	`apple`	`darwin`	Apple 平台默认环境
`x86_64-pc-windows-msvc`	`x86_64`	`pc`	`windows`	MSVC ABI/toolchain
`x86_64-pc-windows-gnu`	`x86_64`	`pc`	`windows`	GNU/MinGW environment
`x86_64-unknown-linux-gnu`	`x86_64`	`unknown`	`linux`	GNU/glibc environment
`aarch64-unknown-linux-musl`	`aarch64`	`unknown`	`linux`	musl environment

unknown 不表示作者不知道 CPU 或系统，只表示这个目标没有需要单独编码的 vendor。pc 也不等于“只能在某品牌 PC 上运行”，它是工具链 target 命名的一部分。

短文件名 linux-x64 可以看成产品面向普通用户的压缩写法；x86_64-unknown-linux-gnu 则是编译器和 linker 需要的精确坐标。

macOS 为什么还有 Universal Binary

macOS 经历过多次 CPU architecture 迁移。Apple 的技术文档记录了从 PowerPC 到 Intel，再从 Intel 到 Apple Silicon 的兼容需求。为了让同一份 App 同时包含多个 architecture 的机器码，macOS 使用 Universal Binary，也常被称为 fat binary。

今天常见的 universal macOS executable 同时包含：

1	x86_64 arm64

系统启动时会选择适合当前机器的 slice。Apple Silicon 上还可以通过 Rosetta 运行只有 x86_64 指令的 Mac app；但这属于 binary translation，不等于它已经变成原生 arm64 构建。

三种发行方式各有取舍：

发行物	优点	代价
`darwin-arm64`	Apple Silicon 原生，体积只含一个 architecture	Intel Mac 不能运行
`darwin-x64`	支持 Intel Mac，Apple Silicon 在 Rosetta 条件下可运行	在 Apple Silicon 上不是原生执行；插件和 native module 还要一起兼容
`universal` / `universal2`	一个 artifact 覆盖两种 Mac architecture	体积更大，所有 embedded binaries 都要包含正确 slice

可以用 lipo 检查一个 macOS binary 里到底有哪些 slice：

1	lipo -archs /path/to/MyApp.app/Contents/MacOS/MyApp

看到 x86_64 arm64 才能证明主 executable 同时包含两种 architecture。对复杂 App，还要继续检查 framework、plugin、helper 与 native library，不能只验主程序。

Windows ARM64 和模拟执行怎么理解

Windows 11 on Arm 支持运行 Arm64 native app，也能通过 emulation 运行 x86 与 x64 app。于是 Arm Windows 用户经常同时看到两个都“能装”的选项：windows-x64 和 windows-arm64。

我的选择顺序仍然是：有可信的 Arm64 native build 就优先 Arm64；只有 x64 build 时，再把 emulation 当兼容路径。

原因并不神秘。模拟层能翻译 CPU instructions，但应用还可能加载 driver、shell extension、DLL、JIT、plugin 或 native addon。这些组件存在各自的 architecture 与 ABI 边界。Microsoft 的 WOW64 文档也明确指出，32-bit 与 64-bit DLL 不能随意注入不同位数的进程；“主程序能启动”不能替代整条依赖链验收。

Windows 还有 ARM64EC 这类面向混合迁移的 ABI，让同一进程在特定规则下组合 Arm64EC 与兼容 x64 code。它主要是开发和迁移概念，不是普通用户下载页面上的首要选择。看到它时应按产品官方说明处理，不要把 EC 当作另一个 CPU family。

为什么 OS 和 CPU 都对，程序还是跑不起来

一个 native executable 能否运行，至少要连续通过四层匹配：

OS / object format
    ↓
CPU instruction set
    ↓
ABI / libc / calling convention
    ↓
system library、driver、plugin 与最低版本

几个典型反例：

linux-x64-musl 与机器的 x64 CPU 匹配，但程序期望的 dynamic loader 可能和当前 glibc environment 不同；
darwin-x64 能通过 Rosetta 启动，App 内部某个只含 arm64 或只含 x86_64 的 plugin 仍可能加载失败；
windows-x64 可以在 Windows on Arm 的 emulation 下启动，但 kernel driver 不能按普通 user-space app 的方式处理；
同样是 linux-x64-gnu，新 glibc 编译出的 binary 也可能因为 symbol version baseline 过高而无法运行在旧 distribution 上。

所以“架构兼容”只是必要条件，不是充分条件。发行工程真正要验证的是整条 artifact：可执行文件、动态库、native addon、插件、安装器和更新器都必须对齐。

怎么确认自己该下载哪一个

跨平台最省事：看当前 Runtime 的编译目标

如果机器上已经有 Node.js：

1	node -p "process.platform + '-' + process.arch"

常见输出：

1
2
3

darwin-arm64
win32-x64
linux-x64

Node.js 官方定义得很清楚：process.platform 表示这份 Node binary 面向哪个 OS platform 编译，process.arch 表示它面向哪个 CPU architecture 编译。这里检测的是当前 Runtime，不一定是物理硬件。

例如 Apple Silicon 上如果运行的是 x64 Node，process.arch 可能仍是 x64。对 native addon 来说这恰好有用，因为 addon 必须匹配当前 process；对“我应该安装哪一版 Node”来说，你还要继续确认硬件与翻译状态。

macOS

1 2	uname -m sysctl -in sysctl.proc_translated 2>/dev/null \|\| true

常见的 uname -m 输出是 arm64 或 x86_64。在 Apple Silicon 上，sysctl.proc_translated 返回 1 表示当前 process 正在 Rosetta translation environment 中运行，返回 0 表示 native process。

如果只想通过图形界面判断：Apple 菜单 →“关于本机”，看到 Apple M 系列芯片就选 arm64；看到 Intel processor 就选 x64 / x86_64。

Windows PowerShell

如果安装了现代 .NET runtime，可以同时查看 OS 与当前 process：

1 2	[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture [System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture

两者可能不同。例如 Arm64 Windows 正在运行 x64 process 时，OS architecture 与 process architecture 就不能混为一个值。没有把握时，优先遵循产品下载页对 Windows on Arm 的明确说明。

Linux

1 2	uname -m ldd --version

常见 architecture 映射：

`uname -m`	下载页常见标签
`x86_64`	`x64` / `amd64` / `x86_64`
`aarch64`	`arm64` / `aarch64`
`armv7l`	`armv7` / `armhf`，还要确认 hard-float ABI
`ppc64le`	`ppc64le`
`s390x`	`s390x`
`riscv64`	`riscv64`

ldd --version 的输出通常能帮助判断当前环境属于 glibc 还是 musl，但不同 distribution 的实现与输出不完全一致。发布者若提供了专门的 gnu / musl artifact，应继续对照其支持矩阵，而不是只看 uname -m。

看到一个文件名，我会按什么顺序判断

假设下载页给出：

1	app-3.2.0-linux-arm64-musl-beta.tar.gz

我会从兼容性到发布策略依次拆：

linux：目标 OS；
arm64：目标 CPU architecture；
musl：目标 libc / ABI environment；
beta：release channel；
.tar.gz：archive format，不是 CPU 或 ABI。

这套顺序有一个好处：即使项目把字段换成 aarch64-unknown-linux-musl、linux-aarch64 或 linux-arm64-alpine，你仍然是在找相同的几个坐标。

还有三个实用判断：

原生优先。 Apple Silicon 选 arm64，Windows on Arm 有成熟 native build 时也优先 arm64；
模拟是兼容手段，不是构建证明。 x64 app 能通过 Rosetta 或 Windows emulation 启动，不代表 native module、plugin 与 driver 全部通过；
Linux 多看一层 libc 与最低版本。 CPU 匹配后，再核对 gnu/musl、distribution baseline 和 package format。

要不要记住所有名字：我的判断框架

不需要背完整词典。记住三条主线就够了：

第一，先分维度。 darwin、win32、linux 是 OS/platform；x64、arm64 是 CPU architecture；gnu、musl、msvc 是 ABI/toolchain environment；stable、beta 才是 channel。

第二，识别同义标签。 x64 ≈ amd64 ≈ x86_64，arm64 ≈ aarch64。这里的“≈”表示 ordinary package selection 中通常指向同一个 instruction-set family，不代表不同 OS、ABI 下的 binary 可以互换。

第三，把检测对象说清楚。 你检测的是 physical machine、operating system，还是当前 process？在 Rosetta、WOW64、container 和 cross-compilation 环境里，这三个答案完全可能不同。

下一次再看到 darwin-arm64，不用把它当成一串项目私有缩写。把连字符理解成坐标分隔符：平台、架构、环境、渠道，一层层读下去即可。

参考资料

本文使用 writting-skill 辅助写作。项目已开源，欢迎在 GitHub 点个 Star。

RSS 到底是什么：为什么 FlyOS 性能评测不能只看一个内存数字

2026-08-24T12:47:17.000Z

最近在整理 FlyOS 的性能 baseline 时，我碰到一组很容易被误读的数据：同一轮空闲采样中，完整进程树的 RSS 均值是 949.4 MiB，macOS Physical Footprint 均值却只有 355.5 MiB。

两个数字相差约 2.7 倍。是采集脚本错了，还是浏览器真的吃掉了近 1 GB 物理内存？都不是。真正的问题在于：我们把两个统计口径不同的指标，当成了同一个“内存占用”。这也是我想单独写清 RSS 的原因。

一句话总结

RSS（Resident Set Size）表示一个进程当前驻留在物理内存中的页面规模。它适合观察同一口径下的趋势和拆解 Browser、Renderer、GPU、Utility 等进程角色，但在 Chromium 多进程架构里，把各进程 RSS 直接相加可能重复计算共享页，所以它不等于应用独占的真实物理内存，更不能单凭一次上涨就判定内存泄漏。

在 macOS 上，我的判断很明确：

看整个应用给系统造成的内存压力，以进程树的 Physical Footprint 为主；
看内存主要分布在哪类进程、版本前后趋势是否异常，以同口径 RSS 为辅；
判断是不是泄漏，还要继续进入 heap、allocation、对象生命周期和 GC 证据，不能停在 RSS。

RSS 到底统计了什么

操作系统按页管理内存。进程的虚拟地址空间可能很大，但其中只有一部分页面此刻真正驻留在 RAM；RSS 统计的就是这部分 resident pages 的规模。

在 macOS 上，ps 对 rss 的定义是进程的 real memory resident set，并以 1024 bytes 为单位输出。FlyOS 的采样器读取的是：

1	ps -axo pid=,ppid=,rss=,%cpu=,command=

这里的 rss 不是 JavaScript heap，也不是应用申请过的全部虚拟地址，更不是“这个应用独占了多少内存”。几个常见指标可以这样区分：

指标	回答的问题	主要局限
VSZ / Virtual Size	进程映射了多大的虚拟地址空间	大量地址可能没有驻留，通常不能直接代表内存压力
RSS	这个进程当前有多少页面驻留在 RAM	可能包含 clean、file-backed 和共享页；跨进程相加可能重复
Heap	某个运行时或分配器管理了多少对象内存	只是进程内存的一部分，不包含全部 native、映射文件和共享内存
Physical Footprint	从系统记账角度，这个进程或进程组带来多少物理内存负担	更适合 macOS 压力判断，但不直接告诉你具体是哪类对象在增长

Apple 在内存优化文档里也把 dirty、clean、compressed 等页面区别开来，并建议结合真实 memory pressure 理解应用影响，而不是只盯一个总数。参见 Reducing your app’s memory use。

为什么 Chromium 多进程会把 RSS “加大”

Chromium 不是单进程程序。Browser、Renderer、GPU、Network Service、Storage Service 等角色彼此隔离，这也是它稳定性和安全性的重要基础。Chromium 官方的 Multi-process Architecture 文档对此有完整说明。

问题在于，不同进程可以映射同一份共享库、共享内存或 file-backed page。对单个进程看，这些页面确实属于它的 resident set；但如果把多个进程的 RSS 直接相加，同一批物理页就可能在多个进程名下重复出现。

可以把它想成一套公共技术手册：五个团队的桌上都放着它。按“每个团队正在使用多少资料”统计，这套手册会出现五次；按“公司仓库实际占了多少空间”统计，它只有一套。两个数字都没有错，只是在回答不同的问题。

这也是为什么 FlyOS 同时采集两条线：

# 拆解进程角色，并得到每个进程的 RSS
ps -axo pid=,ppid=,rss=,%cpu=,command=

# 对同一组 PID 做 macOS Physical Footprint 统计
footprint -j result.json -f bytes --noCategories

footprint 在接收多个进程时，会把多重映射的对象去重，并把共享部分单独记账。因此，RSS 汇总和 Physical Footprint 出现明显差异，本身并不是异常。

回到 FlyOS：949.4 MiB 和 355.5 MiB 各代表什么

2026 年 8 月 19 日，我用 FlyOS CLI 1.2.0 的本地 Release 构建，为 Fia 0.1.0 建立了第一份 clean-profile 正式 baseline。测试环境是 macOS 26.5.2 arm64，临时干净 profile，只打开 https://example.com/，预热 5 秒后进入空闲采样。

采样项	结果	采样口径
RSS 均值	949.4 MiB	进程树 5 次采样，间隔 1 秒
RSS 中位数	948.5 MiB	同上
Physical Footprint 均值	355.5 MiB	同一进程树，前 3 次采样
空闲 CPU 均值	1.9%	同一空闲窗口
CDP reload CPU 峰值	66.2%	40 次采样，间隔 200 ms

RSS 的价值在角色拆解上尤其直观。下面是最后一次空闲采样的分布，总计 948.5 MiB：

进程角色	数量	RSS
Browser	1	231.3 MiB
Renderer	3	322.5 MiB
GPU	1	109.3 MiB
Utility - Network	1	78.8 MiB
Utility - Storage	1	66.5 MiB
Runtime	1	140.1 MiB

这张表能快速回答“主要增长发生在哪个角色”。例如 Renderer 突然多出一个，或者 Runtime RSS 连续抬升，调查方向会完全不同。但它不能回答“这 948.5 MiB 是否全部由 Fia 独占”。对于后一个问题，355.5 MiB 的 Physical Footprint 更接近我关心的系统压力口径。

RSS 上涨不等于发生了内存泄漏

内存泄漏会推高 RSS，但 RSS 上涨还有很多正常原因：

Chromium 新建了 Renderer 或 Utility 进程；
页面缓存、图片解码缓存或磁盘缓存映射增加；
V8 JIT 编译了更多代码，heap 也扩过容；
allocator 暂时保留已释放页面，没有立即归还操作系统；
file-backed 页面因为刚被访问而进入 resident set；
对象仍然可达，只是产品逻辑保留时间比预期更长。

因此，“跑一次后 RSS 比之前高”最多是一个调查信号，不是泄漏结论。更可靠的链路应该是：先固定 workload 和进程范围复现趋势，再用 heap snapshot、allocation profile、对象数量、GC 后基线和进程生命周期去定位原因。

如果多轮相同操作后，RSS 与 Physical Footprint 都阶梯式增长，强制 GC 或回到空闲状态后仍不下降，同时 heap 或 native allocation 里能看到稳定增长的保留路径，才有资格把结论推进到“疑似泄漏”。

性能评测里，怎样比较 RSS 才不误导

我现在会把 RSS 对比当成一个有前置条件的实验，而不是把两个数字直接相减。至少要锁定下面六件事：

必须一致的条件	为什么
指标定义	RSS 只能和 RSS 比，不能拿 RSS 与 Physical Footprint 做版本涨跌
进程范围	只看 Browser 与统计完整进程树，结论会完全不同
workload	空白页、真实业务页、视频页的进程和缓存结构不同
生命周期	冷启动、预热后空闲、操作中、操作后稳定态不能混在一起
构建产物	Debug、Release、符号、Feature Flag 都可能改变结果
采样窗口	单点很容易受进程启动、GC、缓存和后台任务干扰

这也解释了为什么这份 baseline 没有拿历史报告中的 1.53–1.67 GB RSS 直接宣称“大幅下降”：历史数据的进程树、页面负载和采样口径并不完全一致。当前这组数据首先是一条可复现的基线，只有后续版本在同机、同 workload、同范围、同窗口下复测，才形成有效比较。

Apple 对性能回归的建议也是建立可重复的测试和 baseline，再观察变化，而不是靠一次快照下结论。参见 Preventing memory-use regressions。

要不要看 RSS / 我的判断框架

RSS 值得看，但要放在正确的位置上。

你要回答的问题	优先看什么	我的判断
内存主要花在哪类进程	分角色 RSS	值得看，定位速度很快
新版本是否出现同口径回归	RSS 趋势 + Physical Footprint 趋势	两条线一起看，避免统计口径误导
macOS 上整个应用造成多大内存压力	进程树 Physical Footprint + memory pressure	以此为主，不用 RSS 汇总替代
是不是 JavaScript 对象泄漏	Heap snapshot、allocation、GC 后保留对象	RSS 只能报警，不能定罪
用户是否真的感知到退化	页面响应、切换延迟、崩溃、系统压力	最终仍要回到体验和稳定性

我的核心原则只有一句：先问指标在回答什么问题，再看数字大小。

RSS 不是“假数据”，Physical Footprint 也不是 RSS 的修正版。它们是从不同层面观察内存的两把尺子。FlyOS 性能治理真正需要的，不是寻找一个万能数字，而是把进程结构、系统压力、运行时分配和用户体验连成一条证据链。

本文使用 writting-skill 辅助写作，配图使用 better-imagegen 生成。项目已开源，欢迎在 GitHub 点个 Star。

把 Agent Skill 当作架构边界：平台开发与发行版开发为什么要拆开

2026-08-22T17:05:00.000Z

我最近整理一个浏览器平台工程时，发现最容易让 Agent 做错的，不是命令太多，而是把两类工作塞进了同一个 Skill：一边维护平台源码、协议和构建能力，另一边又让它操作具体产品的 Profile、签名、发布和验收。

看上去只是目录里少了一个文件夹，实际却把所有权混在了一起。Agent 一旦拿到模糊的“发布浏览器”指令，很容易从平台源码直接构建、拿本地 package 去验证产品，或者把签名、CDN、更新通道当成平台默认能力。每一步单独都可能跑通，组合起来却会破坏交付边界。

一句话总结

Skill 应该按“谁拥有决策和证据”拆分，而不是按“这些命令能不能连着执行”拆分。平台开发与发行版开发之间，最重要的产物是已发布、精确版本锁定的 package，而不是共享一个工作目录。

Skill 不是知识库目录

很多 Skill 最初都像一份团队 Wiki：构建命令、常见错误、发布步骤、文档链接全放进去。它在任务少时很方便，任务一多就会开始替 Agent 做隐式决策。

例如下面这两类问题，表面都和“浏览器构建”有关，实际输入完全不同：

工作	真正拥有者	Agent 应读取的输入	交付证据
修改 Kernel、CLI、Build Kit、Runway Core	平台团队	平台源码、基线、测试、package manifest	测试、tarball、registry readback
配置品牌、内置扩展、签名、发布通道	发行版团队	Profile、lock、产品 workspace、受控凭据	native artifact、签名回读、CDN、旧客户端升级

如果同一个 Skill 同时覆盖它们，Agent 很容易把“本地源码已经通过测试”说成“发行版已经采用”，或者让发行版直接依赖平台的 sibling checkout。前者缺少发布和安装证据，后者会让本地环境掩盖真实的 package 边界。

我会把边界写进名字和目录

拆分不是把原文复制两份，而是让名称先表达工作对象。

.codex/skills/
  platform-develop/
    平台源码、Kernel、Build Kit、CLI、公开 package

skills/
  distribution-develop/
    产品 Profile、私有 workspace、签名、发布、客户端验收

平台 Skill 放在平台仓库的 .codex/skills/，含义是：它服务这个仓库的维护者，不应被产品安装、CI 或运行时依赖。发行版 Skill 则面向拥有产品配置和交付责任的工程。两者可以引用同一套平台契约，但不能共享“直接读取平台源码”这条捷径。

目录位置不是审美问题。它决定 Agent 在任务开始时优先加载什么上下文，也提醒维护者：这里的规则究竟是本地开发习惯，还是要跟着某个产品一起交付的操作契约。

把依赖方向写成 Agent 能检查的规则

我通常会要求平台与发行版满足三个约束。

第一，发行版只消费 registry 中已发布的精确 package。禁止 file:、link:、workspace:、本地 tarball、sibling lookup 或跨仓 symlink。这样能强迫每次采用都经过版本、锁文件和干净安装。

第二，产品专属内容留在产品侧。品牌、Bundle ID、私有 Extension、Runway 实现、签名密钥引用、发布渠道与真实客户端验收，都不是平台的默认输入。平台可以提供 CLI 和安全 primitive，但不应该猜测产品路径或替产品保存凭据。

第三，交付状态必须拆开记录。测试通过、package 已发布、产品已构建、签名完成、CDN 可读、更新通道已激活、旧客户端成功升级，分别是不同事实。Skill 的价值不在于让 Agent 多跑几条命令，而在于避免把前一个状态误报成后一个状态。

一个足够小的判断框架

当我准备新增或拆分一个 Skill 时，只问四个问题：

这个任务最终由谁对用户结果负责？
Agent 为完成任务必须读取哪些 source of truth？
哪些凭据、产物和环境只能由特定工程拥有？
什么证据能证明交付，而不只是证明代码存在？

四个答案相同，通常可以留在一个 Skill 里。只要其中一个答案分叉，特别是出现“平台已发布 package”与“产品已签名 artifact”两种证据时，就应该拆开。

这套方法不只适用于浏览器。任何同时维护 SDK、平台服务和多个产品的团队，都可以用同样的方式收紧 Agent 的工作面：让 Agent 在正确的仓库、正确的依赖方向和正确的验收门槛里工作。这样获得的不是更多流程，而是更少的错误捷径。

要不要拆

如果一个 Skill 既能修改共享平台，又能替多个产品发布，值得拆。先按所有权拆，再用明确的 package、Profile 和验收证据连接。

如果工作只发生在一个产品仓库，且没有跨仓发布或受控凭据边界，暂时不必为了形式拆 Skill。真正需要关注的是：Agent 是否会因为错误的上下文和依赖方向，做出无法被交付证据支撑的结论。

本文使用 writting-skill 辅助写作。项目已开源，欢迎在 GitHub 点个 Star。

从静态 Reference 到 LLM Wiki：让 Agent Skill 拥有可持续演进的知识底座

2026-08-21T03:22:19.000Z

最近我读到一篇数据研发实践文章。它讨论了一个很具体的问题：团队已经把需求调研、模型设计、代码生成和任务发布封装成 Agent Skill，但模型口径、数据资产和业务知识仍在持续变化，静态写进 Reference 的内容很快就会落后。

我认为这篇实践最值得复用的部分，不是某个知识库产品的接入方式，而是它重新划清了 Skill 与知识的边界：Skill 负责稳定的工作方法，知识库负责持续变化的事实。

说明：本文是脱敏后的原创技术解读。公开版未复用原文、内部链接、组织与人员信息、真实业务数据及操作截图，仅保留可泛化的工程方法。

一句话总结

当 Agent Skill 依赖的知识规模变大、变化变快之后，不要继续把资料塞进 Reference。更稳妥的结构是：

1 2	Raw Sources → Wiki → Schema / Skill 事实源知识编译查询与执行规则

Agent 通过 Ingest 把新资料编译进 Wiki，通过 Query 为当前任务取得带来源的知识，通过 Lint 发现冲突、孤岛和过期内容。每次实践产生的新结论再回到 Raw Sources，进入下一轮增量编译。

静态 Reference 为什么会失效

第一版 Skill 把领域知识放进 references/ 很合理。它简单、透明、可以和代码一起版本化，也不需要额外基础设施。

问题出现在知识开始具备下面几个特征之后：

数据表、字段口径和任务代码持续变化；
需求文档、设计文档、规范和历史案例分散在不同位置；
同一个知识点可能存在多个版本，甚至相互冲突；
一次任务中校准出的结论，需要被下一次任务继续使用；
不同团队成员知道的信息不对称，Agent 也无法判断哪份资料更新。

如果继续扩充静态 Reference，Skill 会逐渐变成一个难以维护的资料压缩包。知识更新需要修改 Skill，Skill 发布又和知识变更绑定；资料越多，Agent 每次加载的 Context 越大，真正需要的内容反而更难命中。

这时需要拆开两个生命周期：

对象	适合承载什么	变化频率	维护方式
Skill	流程、输入输出、工具调用、质量门槛、失败恢复	相对稳定	代码评审与版本发布
Reference	稳定规则、模板、固定术语、少量示例	低频	随 Skill 维护
Wiki	业务知识、数据资产、设计结论、案例经验、关系与冲突	持续变化	增量编译与健康检查
Raw Sources	原始文档、代码、规范和已审核事实	按业务变化	由知识 Owner 维护

LLM Wiki 的三层架构

Andrej Karpathy 提出的 LLM Wiki pattern 把知识系统分成 Raw Sources、Wiki 和 Schema 三层。这个分层很适合 Agent Skill，因为它同时回答了三个问题：事实在哪里、知识怎样积累、Agent 按什么规则工作。

Raw Sources：不可被 AI 改写的事实源

Raw Sources 保存原始资料。放到数据研发场景里，可以包括：

经过授权的代码仓库与 SQL；
数据资产说明、字段口径和模型设计文档；
需求调研、业务规则与研发规范；
已审核的故障案例、问答记录和设计反馈。

这一层的核心约束是：AI 可以读取，但不能把自己的总结反向覆盖原始事实。任何 Wiki 页面和 Agent 答案都应该能够回到具体 Source、版本和位置。

Wiki：由 AI 维护的知识中间层

Wiki 不是原文切片的集合。它把分散资料整理成主题页、实体页、流程页、索引、交叉引用和编译日志。

例如，一个“核心交易事实表”主题页可以连接字段口径、上游来源、下游任务、历史变更与常见异常；当新设计文档进入系统时，Agent 不只新增一个 Chunk，还要更新已有页面并标记冲突。

这就是“编译”的价值：跨文档综合只做一次，后续任务可以复用已经整理过的知识，同时在关键结论上回查原文。

Schema：让 Agent 按领域规则维护知识

Schema 可以写在 AGENTS.md、Skill 或专用配置里。它需要定义：

Wiki 有哪些页面类型和字段；
新资料如何进入，哪些页面必须更新；
Query 时先查什么，什么时候必须回源；
哪些结论可以自动写入，哪些必须人工审核；
如何记录 Citation、Revision、冲突和不确定性；
Lint 要检查哪些结构与内容问题。

没有 Schema，LLM Wiki 容易退化成模型自由发挥的笔记目录。Schema 才是把通用 LLM 变成领域知识维护者的关键约束。

Ingest、Query、Lint：知识库的三个基本操作

三层结构落地后，Agent 只需要掌握三个稳定操作。

Ingest：把新资料编译进现有知识

一次 Ingest 不应该只生成摘要。完整流程至少包括：

读取新 Source
  → 提取事实、实体、关系与适用范围
  → 查找已有相关页面
  → 新增或更新 Wiki 页面
  → 标记冲突与待确认项
  → 更新 index.md 与 log.md
  → 保留 Source Citation

增量更新比全量重建更重要。数据资产和业务口径每天都可能变化，系统必须知道这次新增了什么、替换了什么、哪些旧结论仍然有效。

Query：先复用知识，再回到事实源

Query 的默认路径是先读取 Wiki，快速定位主题、实体和已有综合结论。遇到下面几类内容时，再回到 Raw Sources 核验：

字段口径、时间范围、过滤条件等精确事实；
可能已被新版本替代的结论；
会影响代码生成或生产任务的关键规则；
Wiki 中明确标记为冲突或低置信度的内容。

这样既避免每次从海量原文重新综合，也不会把 AI 生成的 Wiki 当成最终事实。

Lint：让知识库能够长期维护

知识库规模上来以后，检索能否返回答案只是最低门槛。Lint 还要持续检查：

同一概念是否出现多个命名；
新旧页面是否存在未处理的矛盾；
页面是否缺少来源或 Revision；
是否出现没有入链的孤岛页面；
重要实体是否只被提及，却没有独立页面；
Source 已更新，Wiki 页面是否仍停留在旧版本。

结构检查可以自动执行；涉及业务语义的冲突，应该进入人工审核，而不是让模型自行决定哪一方是真相。

Agent Skill 应该怎样改造

改造前，Skill 的知识路径通常是：

用户需求
  → Skill
  → 静态 Reference
  → 生成设计与代码

改造后，Skill 不再携带全部业务知识，而是声明查询策略和质量门槛：

用户需求
  → Skill 解析任务
  → Query Wiki 定位知识
  → 回查 Raw Sources 核验关键事实
  → 生成设计与代码
  → 人工校准与执行验证
  → 经验写回 Raw Sources
  → 增量 Ingest

Skill 内部可以保留这样的稳定契约：

knowledge_policy:
  query_first: wiki
  source_of_truth: raw_sources
  require_citation_for:
    - field_definition
    - business_rule
    - production_code
  reject_when:
    - unresolved_conflict
    - missing_revision
    - permission_denied
  feedback:
    destination: reviewed_case_notes
    ingest_after_review: true

这里最重要的变化，是 Skill 从“知识容器”变成“知识消费者和执行编排器”。领域知识可以独立演进，Skill 只需要保持操作协议稳定。

一个脱敏的数据研发例子

假设数据同学收到一份“实验分组回收”的需求。任务需要找到现有核心表、确认分组口径、设计新增字段，并生成 DDL 与 ETL 任务。

静态 Reference 只能提供通用建模规范和代码模板。真正决定方案正确性的知识分散在资产说明、历史设计、现有 SQL 与最近一次口径调整中。

接入 LLM Wiki 后，执行链路可以变成：

Skill 读取需求调研文档，提取业务对象、指标、时间范围和待确认项。
Query 从 Wiki 定位相关主题页、核心表、字段口径和历史设计结论。
对会进入代码的字段与过滤条件回查 Raw Sources，固定 Citation 与 Revision。
Skill 生成模型设计文档，显式列出已确认事实、推导结论和待确认问题。
设计确认后，代码生成 Skill 按模板产生 DDL、ETL 与发布清单。
测试和评审中发现的新口径，先进入经过审核的案例记录，再触发增量 Ingest。

这个流程没有让 Agent 自动拥有最终决定权。它缩短的是查资料、建立关联和维护知识的时间；模型设计是否正确，仍然要由 Citation、测试结果和领域 Owner 的确认来证明。

实践反哺为什么是关键闭环

很多知识库只完成“资料进入系统”，没有处理“任务执行后产生的新知识”。结果是 Wiki 看起来越来越大，Agent 却在重复踩同样的坑。

真正有价值的反馈通常来自三类场景：

Agent 找到了资料，但选错了适用范围；
设计结论基本正确，但遗漏了一个业务例外；
代码运行成功，却暴露出文档和真实实现不一致。

这些反馈不能直接写成新的事实。更稳妥的链路是：

执行观察
  → 人工确认
  → 形成审核后的案例或口径变更
  → 写入 Raw Sources
  → Ingest 更新 Wiki
  → Lint 检查受影响页面

这样，知识库会随着真实任务逐步校准，而不是随着模型回答数量机械膨胀。

这套架构的四个硬门槛

1. Wiki 不能替代事实源

Wiki 是可重建的知识产物。删除 Wiki 后，系统应该能够从 Raw Sources 重新编译；删除 Raw Sources 后，只剩 Wiki 就失去了可信根基。

2. Citation 与 Revision 必须进入查询协议

“回答里带了一个链接”还不够。关键 Claim 应该对应具体 Source Span，并固定查询时使用的 Revision。否则新旧口径仍可能混进同一个方案。

3. 权限必须早于召回

知识编译不能绕过原始权限。Source、Wiki 页面和查询结果都要继承 Scope 与 Permission，过滤应该发生在召回和生成之前。

4. 评测不能只看代码生成比例

AI 生成了多少代码，只能说明工具参与度。知识底座更应该评估：核心事实召回率、Citation 正确率、冲突发现率、过期知识命中率、方案返工率，以及任务完成后是否形成了可复用的新知识。

要不要用

我的判断是：

值得上：同一类任务反复发生，知识分散且持续变化，错误口径会直接影响设计或生产代码。
可以再等：资料规模小、规则稳定、任务复用率低，几份静态 Reference 已经能够清楚覆盖。
重点关注：编译产物的 Citation 完整性、增量更新的影响范围、语义冲突的人工审核，以及权限是否贯穿 Raw、Wiki 与 Query。

不要把 LLM Wiki 当成更复杂的 RAG，也不要把它当成新的万能知识平台。它最有价值的地方，是把 Agent 每次临时找资料、临时综合、临时纠错的过程，沉淀成一个可以持续维护的知识系统。

对 Agent Skill 来说，合理的边界也因此更清楚：稳定方法写进 Skill，稳定规则留在 Reference，变化中的事实进入知识库，执行中得到的经验经过审核后再反哺事实源。

参考资料

Andrej Karpathy：LLM Wiki

本文使用 writting-skill 辅助写作，配图使用 better-imagegen 生成。项目已开源，欢迎在 GitHub 点个 Star。

Git worktree：AI 时代的并行开发工作台

2026-08-18T00:20:00.000Z

AI 编程真正改变的，不是我敲代码更快，而是同一时间能推进的事情突然变多了：一个 Agent 在修构建，一个在写文档，一个分支还留着线上问题的复现现场。

这时最容易出问题的不是模型能力，而是工作目录。切分支会覆盖未提交改动；为了并行而多 clone 几份，又会把依赖、构建产物和仓库状态弄得难以辨认。git worktree 正好补上了这一层：共享一个 Git 对象库，同时提供多个相互隔离的工作目录。

一句话总结

git worktree 是同一个 Git 仓库的多个 checkout。每个 checkout 有自己的分支、文件和未提交改动，但共享提交历史与对象数据库。

它在 AI 时代特别重要，是因为它把“并行执行”变成了可管理的物理边界：每个任务、每个 Agent、每个验证环境都有独立目录，而不是在同一个工作区里抢状态。

它和 clone、branch 到底有什么区别

先把三个概念分开：

概念	解决什么	文件目录	Git 对象库
branch	保存不同历史线	通常共用一个目录	共用
clone	获得一份完整副本	独立	各自一份
worktree	同时 checkout 多个分支	独立	共用同一份

普通开发里，分支和工作目录是一对一的：我在 main 上改了一半，要看 hotfix，就得 stash、提交半成品，或者冒险切分支。worktree 允许我把 hotfix 放进另一间“房间”。

它不是替代 branch。branch 仍然定义历史；worktree 只是让多条历史线同时拥有可工作的文件系统。

最常用的三个命令

假设当前仓库在 ~/project：

# 为已有分支创建一个并行工作目录
git worktree add ../project-hotfix hotfix/login-timeout

# 新建分支并同时创建目录
git worktree add -b feat/agent-release ../project-agent-release main

# 查看所有 worktree 与对应分支
git worktree list

完成后再清理：

1 2	git worktree remove ../project-hotfix git worktree prune

remove 删除的是那个工作目录，不会删除分支和提交历史。要删除分支，仍然显式执行 git branch -d。这条边界很重要：目录生命周期和代码历史生命周期不是一回事。

为什么 AI 让它从技巧变成基础设施

过去我一个人开发，切分支的成本主要是心智负担。现在一个需求经常天然拆成多条链路：实现、测试、构建、文档、代码审查、发布验证。AI Agent 能同时跑这些任务，但它不会自动解决共享目录的冲突。

例如一次发布排障，最稳妥的结构往往是：

主 worktree：保留当前真实状态，不动未提交工作。
release/* worktree：只从指定 commit 打包发布，保证制品可追溯。
fix/* worktree：验证补丁或复现失败，不污染发布输入。
docs/* worktree：写说明、补测试或整理变更。

这不是为了形式上的“多 Agent”。真正的收益是，每个 Agent 的输入和输出都更明确：它只能在自己的目录里修改；构建日志、node_modules、生成文件和未提交 diff 都不会悄悄影响另一个任务。

一个适合 Agent 的工作流

我更推荐按任务边界创建，而不是按人名创建：

# 保持主目录只做集成和最终检查
git worktree add -b fix/importer-patch ../flyos-fix-importer main
git worktree add -b release/1.1.4 ../flyos-release-1.1.4 main
git worktree add -b docs/release-notes ../flyos-release-docs main

然后约定四件事：

一个 worktree 只服务一个可描述的目标。
Agent 完成后报告 commit、验证命令和残留风险，而不是只说“改好了”。
发布 worktree 必须从明确 commit 创建；不要把主目录中未提交的实验改动一起打包。
主 worktree 不承担长时间构建和大范围试验，它只负责集成、审查与最终提交。

这套约定比“让 Agent 小心一点”可靠得多。边界落在目录和 Git 记录上，后续的人也能复现。

它不解决什么

worktree 不是隔离环境的万能替代品。

它们仍共享同一个仓库的 Git 对象库，不能把它当成权限隔离。
端口、全局缓存、Docker 容器、数据库和远端环境依然可能冲突。
同一分支不能被两个 worktree 同时 checkout；这是 Git 用来避免同一分支出现两份独立未提交状态的保护。
大型依赖目录通常会各自安装，磁盘占用仍需管理。

如果任务需要真正的安全边界或不同系统镜像，仍然要用 container、VM 或独立构建机。worktree 解决的是代码工作区隔离，不是运行时隔离。

要不要用 / 我的判断框架

值得上：你同时处理发布、修复、审查或多个 Agent 任务；你不想为了切分支 stash 半成品；你需要从一个干净 commit 产出可追溯制品。

可以再等：仓库很小、任务严格串行，而且你几乎没有未提交改动。

重点关注：不要把 worktree 当成“多开几个目录”就结束了。给每个目录一个任务边界、一个分支和一份验证证据，才是它在 AI 时代真正放大交付能力的方式。

Profile 到底是什么意思：先分清用户资料、构建方案与交付策略

2026-08-17T12:00:00.000Z

先看 Profile 描述的是谁，再决定它该翻译成什么。

我之前把 Profile 直接解释成“产品交付策略”，后来发现这个说法太快了。读者还没理解 Profile 这个词本身，就被带进了 Distribution、Runtime 和 Build Kit，当然容易越看越糊涂。

更准确的说法是：Profile 没有唯一的技术含义。它表示某个对象在一组维度上的完整描述。对象不同，中文意思也不同。

浏览器里的 User Profile 是用户资料；构建系统里的 Build Profile 是一套构建方案；FlyOS 里的 Distribution Profile 则是产品发行配置。技术文档如果只写一个裸的 Profile，通常不是读者不懂，而是作者省略了最重要的前缀。

一句话总结

把 Profile 理解成“配置”只对了一半。它更接近一份特征档案或成套方案：把描述同一个对象的多项信息放在一起，形成一个可以识别、选择或执行的整体。

所以，看到 Profile 时先补全这句话：

这是 谁的 Profile，它要描述这个对象的 哪些特征，又给 谁使用？

这三个问题一旦有答案，Profile 的含义通常就清楚了。

为什么同一个词会有这么多意思

Profile 的共同点不是“里面都有配置项”，而是它们都在给某个对象画轮廓。

完整术语	描述的对象	更自然的中文理解	典型内容
Personal Profile	一个人	个人简介、人物资料	姓名、经历、技能、头像
Browser User Profile	一个浏览器用户	用户资料、用户数据档案	Cookie、历史记录、扩展、站点权限、偏好
Build Profile	一次构建方案	构建档位、构建预设	Debug/Release、符号级别、优化参数、输出目录
Distribution Profile	一个产品发行版	发行配置、产品交付配置	产品身份、目标平台、Runtime、更新与交付策略
Profiling	一个程序的运行行为	性能分析、性能剖析	CPU、内存、调用栈、耗时分布

最后一行尤其容易混淆。profiling 是分析程序运行特征的动作，产物可能是 CPU Profile 或 Memory Profile；它和产品发行配置不是同一类东西。

这也解释了为什么不能脱离前缀给 Profile 下定义。就像只说“端”而不说客户端、服务端还是端口，单词认识了，工程对象仍然没确定。

Profile、Config 和 Settings 有什么区别

这三个词经常同时出现，但关注点不同。

Setting 通常是一个可调整的选项，例如主题、语言或首页。Settings 是这些选项的集合，常常直接面向用户。

Config 的范围最宽。一个端口号、一份 JSON、环境变量和整套服务配置，都可以叫 configuration。

Profile 往往强调一组成套、彼此协调的特征。选择一个 Profile，通常不是只改一个开关，而是切换到一整套已经定义好的身份或方案。例如 production Build Profile 可能同时决定优化级别、符号、输出目录和是否生成安装包。

可以用一个很实用的判断来区分：

你在做什么	更可能使用的词
调一个独立开关	Setting
写入任意配置值	Config
选择一整套有明确用途的方案	Profile

这不是语言标准，只是工程里常见的命名倾向。最终仍要回到具体项目的 contract 和文档。

截图里的 Profile 指什么

当一句话写着“Build Kit 按 Profile 选择 engine”时，这里的完整名称应该是 Distribution Profile。

它不是浏览器里的用户 Profile，也不是开发者选择的 Debug/Release Build Profile。它描述的是：这一个 Browser Distribution 准备交付成什么产品。

以当前 FlyOS 为例，Distribution Profile 是 Distribution 仓库里的 flyos.json。截至 2026 年 8 月 26 日，当前 contract 使用 schema v5，主要声明：

产品身份与 App 版本；
要交付的目标平台；
品牌资源与平台身份；
Runway 和内置 Extension 的选择；
Browser、Runway 与 Extension 的更新策略；
可选的 Lean delivery 约束。

Build Kit 读取这份 Profile，再结合 lock、已经安装的 package、Chromium checkout 和目标平台 toolchain，完成后续构建与打包。

如果某个发行版同时支持 manual installer 和 automatic updater installer，那么“选择哪一种安装引擎”属于产品交付决策，可以由 Distribution Profile 表达或约束。这里的逻辑是：

Distribution Profile
  → 声明这次要交付的产品与更新方式
  → Build Kit 选择对应的构建、打包路径
  → 生成最终安装包

因此，截图里更不容易误解的写法应该是：

Build Kit 根据 Distribution Profile 选择对应的 installer engine。

Profile 不是 engine，也不是安装器本身。它只是 Build Kit 的产品级输入之一。

Distribution Profile 不是用户数据

现在再回头看原来的结论就容易理解了：不是所有 Profile 都与用户无关，只有 Distribution Profile 与用户数据无关。

对象	谁维护	什么时候改变	是否跟着用户走
Distribution Profile	产品与发行工程团队	开发、构建或发版时	否
Build Profile	构建工程团队	执行某种构建时	否
Browser User Profile	浏览器用户	日常使用中	是
User Settings	应用用户	日常使用中	通常是

用户改深色模式，不应该重新生成安装包；产品切换更新方式，也不应该让用户去设置页完成。它们都叫“配置”，但所有权、生命周期和验收方式完全不同。

Profile 和 lock 也不是一回事

在 FlyOS 的交付链路里，还要分清 Distribution Profile 与 flyos-lock.yaml。

Profile 由 Distribution 编写，表达“我想交付什么”；lock 由工具根据 Profile 和实际解析结果生成，记录“这次精确使用了什么”。前者是声明，后者是可复现证据。

flyos.json           flyos-lock.yaml
期望状态       →      精确解析结果
人工维护              工具生成
产品选择              package / artifact identity

修改 Profile 后需要重新解析和刷新 lock，而不是手工把两份文件改到“看起来一致”。

Lean Profile 又是什么

Lean Profile 也不是第四种全新的 Profile。在当前 FlyOS contract 里，lean 是 Distribution Profile 中可选的一组交付约束，例如只保留指定的 Chromium locale，或者明确排除某类 Runtime payload。

这里的 Lean 描述“这个发行版怎样精简交付内容”。它不代表一个常驻进程，也不是用户可以随手切换的“省内存模式”，更不等于 fast-debug 之类的 Build Profile。

把完整名称写出来，关系就很直观：

Distribution Profile
├── 产品身份与 target
├── Runway / Extension / update 选择
└── 可选的 Lean delivery 约束

Build Profile
└── production / symbolized / debuggable / fast-debug 等构建方案

Browser User Profile
└── Cookie / 历史记录 / 扩展 / 用户偏好

三者可以同时存在，因为它们控制的是三条不同的轴。

我的判断框架

以后再看到 Profile，我会按这个顺序判断：

先找前缀：User、Build、Distribution、CPU 还是别的对象；
再看所有者：用户、开发者、产品团队还是分析工具；
再看生命周期：运行中改变、构建时选择，还是发版时版本化；
最后看结果：它保存用户数据、切换构建方案，还是定义交付产品。

如果一段技术文档只写 Profile，而上下文里又同时存在用户资料、构建方案和发行配置，最好的优化不是再补一句抽象定义，而是把完整术语写出来。

所以，截图里的答案可以压缩成一句话：那里的 Profile 是 Distribution Profile，指产品发行配置；Profile 这个词本身没有固定等于“交付策略”。

本文使用 writting-skill 辅助写作，配图使用 better-imagegen 生成。项目已开源，欢迎在 GitHub 点个 Star。

AI 浏览器不是 Chrome 加个聊天框：从 BrowserOS 拆解七层架构

2026-08-09T18:43:34.000Z

AI 浏览器的运行时负责理解和执行任务，工程交付控制面负责把整套系统变成可安装、可发布、可更新的产品。

最近我在基于 BrowserOS 看 AI 浏览器的实现。最开始我也有一个很自然的理解：AI 浏览器大概就是 Chromium 加一个侧边栏，在里面调用大模型，再给 Extension 多开几个权限。

真正顺着源码往下拆以后，我发现这个理解只能解释最上面的一层。

一个完整的 AI 浏览器，至少同时包含浏览器内核、产品级原生集成、交互界面、Agent Runtime、浏览器工具协议、模型与外部连接，以及支撑多平台构建、签名、发布和更新的工程系统。它表面上是一个桌面应用，内部更接近一套被打包到本机运行的垂直 Agent 系统。

本文以 BrowserOS 仓库的 5ddb0f2d0 commit 为源码快照。BrowserOS 后续会继续变化，固定 commit 能让文中的目录、代码和发布流程保持可复查。

一句话总结

AI 浏览器 = Chromium 产品底座 + 原生集成 + Agent Runtime + Browser Tool Plane + Model / MCP 生态 + Delivery Control Plane。

这里最关键的不是某一个模型，也不是聊天 UI，而是两条完整链路：

自然语言任务
→ Agent 决策
→ 语义工具
→ 浏览器协议
→ 真实页面状态与副作用

源码与版本
→ 构建
→ 签名与打包
→ 发布候选
→ Feed / OTA
→ 已安装客户端

第一条决定“它能不能完成任务”，第二条决定“它能不能作为一个软件产品持续交付”。

先把几个容易混在一起的对象分开

分析 AI 浏览器之前，最好先把几个名词的边界钉住。

对象	它负责什么	它不是什么
Chromium	渲染、网络、存储、Profile、进程与 Extension 基础	Agent Runtime
Extension UI	New Tab、Side Panel、设置与用户交互	整个 AI 浏览器
Agent Loop	调用模型、处理 Tool Call、持续推进任务	浏览器自动化协议
Browser Tool	面向模型的语义化浏览器能力	原始 CDP 命令
CDP	控制和观察 Chromium 的底层协议	MCP
MCP	将工具以标准协议暴露给 Agent Client	页面执行引擎
Updater	让客户端发现和安装已发布版本	Build 或 Release

特别是 CDP 和 MCP，经常被泡在一起说。

CDP 的全称是 Chrome DevTools Protocol，它能创建 Tab、导航、执行 JavaScript、读取 DOM、截屏和监听浏览器事件。MCP 解决的是另一件事：如何把 navigate、snapshot、act 这类工具，以 Agent 能发现和调用的标准接口暴露出去。

简单说：CDP 更靠近浏览器，MCP 更靠近 Agent。

BrowserOS 的两个产品形态

BrowserOS 当前仓库同时包含两个产品，这一点从根目录的 README 就能看到：

BrowserOS：给人使用的 AI 浏览器，Agent 出现在 New Tab 和 Side Panel 中；
BrowserOS neo：给外部 Agent 使用的浏览器，通过 MCP 接入 Claude Code、Codex、Cursor 等 Agent Client。

它们共享 Chromium 和相当一部分浏览器能力，但入口不同。

BrowserOS
人 → New Tab / Side Panel → 本地 Agent Runtime → 浏览器工具

BrowserOS neo
外部 Agent → MCP → Browser Runtime → 浏览器工具

这篇文章以 BrowserOS 的主链路为主，因为它能完整展示一个“人使用的 AI 浏览器”如何工作。BrowserOS neo 放到后面作为架构演进：同一套底层浏览器能力，不一定只能服务内置聊天界面，也可以成为外部 Agent 的 Browser Runtime。

第一层：Interaction Surface

第一层是用户和 Agent 能看见的入口。

BrowserOS 的 apps/app 是一个使用 WXT 和 React 构建的 Extension。它提供 New Tab、Side Panel、设置、Onboarding 和 Chat UI。

从 wxt.config.ts 可以看到几个重要信号：

chrome_url_overrides.newtab 把 New Tab 指向 app.html；
sidePanel、tabs、bookmarks、history 等权限提供浏览器交互入口；
host_permissions 允许 Extension 访问本机 Server；
browserOS 是 BrowserOS 自己增加的私有 Extension 权限；
update_url 指向独立的 Extension 更新清单。

这一层负责把任务、上下文和执行状态呈现给用户，但不要把它叫作“Agent”。UI 可以发起任务、订阅流式结果、展示 Tool Call，却不应该承担模型循环和底层浏览器状态管理。

同样，MCP Client 也属于 Interaction Surface。对 BrowserOS neo 来说，Claude Code 或 Codex 就是另一个交互入口，只不过输入来自外部 Agent，而不是浏览器里的输入框。

第二层：Local Agent Runtime

用户提交任务后，请求进入本机运行的 Agent Server。

BrowserOS 的 apps/server 使用 Bun 和 Hono，提供 /chat、/mcp 等接口。仓库的 Agent README 给出了默认结构：Extension 或 MCP Client 通过 HTTP 与本地 Server 通信，Server 再通过 CDP 控制 Chromium。

api/server.ts 负责启动 Hono 应用和 Bun Server，ai-sdk-agent.ts 则把模型、Browser Tools、Filesystem Tools 和外部 MCP Tools 组合成 Agent Loop。

这一层至少承担：

Conversation 和 Session；
Browser Context；
Model Provider 选择；
Prompt 与消息标准化；
Tool 注册与分发；
Context Window 和 Compaction；
Chat Mode 的只读工具限制；
流式输出、错误处理和运行指标。

为什么要单独起一个本地 Server，而不是全部塞进 Extension Background？

我的理解是，独立进程给 Agent Runtime 提供了更稳定的执行边界。它可以拥有自己的数据库、文件系统访问、长任务、模型 SDK、MCP Client 和生命周期，也能被 Extension、CLI、MCP Client 等多个入口复用。

但“本地运行”不等于天然安全。本地 Server 仍然需要处理监听地址、来源校验、鉴权、Tool 权限和文件访问边界。Local-first 只是部署位置，不是安全结论。

第三层：Model 与外部能力

Agent Runtime 自己不会推理，它需要连接 Model Provider；只会操作网页也不够，它还可能要写 Notion、查 Linear、发邮件或处理本地文件。

BrowserOS 在 Agent Runtime 中把能力分成三类：

Model
  负责理解任务、生成下一步 Tool Call

Browser Tools
  负责观察和操作当前浏览器

External MCP / Connect Apps
  负责访问浏览器之外的业务系统

provider-factory.ts 创建具体的 Language Model，mcp-builder.ts 连接外部 MCP Server。

这层的架构价值在于可替换性。只要上层 Agent Runtime 和下层 Tool Contract 保持稳定，模型可以从云端 Provider 切到本地模型，外部连接也可以从一个 MCP Server 换到另一个，而不必重写 Chromium 控制层。

当然，可替换不代表结果等价。不同模型对 Tool Schema、长上下文、截图理解和多步规划的表现不同，因此 Provider 切换之后仍然需要重新评测任务成功率，而不是只验证 API 能通。

第四层：Browser Capability

这是 AI 浏览器最容易被低估、也是最有工程价值的一层。

如果直接把原始 CDP 暴露给模型，模型会面对大量方法、参数、Target、Frame、Node 和 Session 状态。它不仅浪费 Token，也很难稳定地完成“点击登录按钮”这种在人类看来很简单的任务。

BrowserOS 在这一层继续拆成三部分：

browser-mcp
    语义工具：navigate、snapshot、act、screenshot、tabs……
                ↓
browser-core
    状态抽象：BrowserSession、Page、Window、Navigation、Input
                ↓
CDP
    底层执行：Target、Page、Runtime、DOM、Input、Network……

browser-mcp 定义 Agent 看得懂的 Browser Tools，browser-core 则把 CDP 包装成有状态的 Browser Session。

例如模型想点击页面元素时，不应该先猜 CSS Selector，再拼一串 CDP 命令。更稳定的方式是：

snapshot 返回对 Agent 友好的页面结构和元素引用；
模型根据语义选择引用；
act 接收引用和动作；
Browser Core 将引用解析到真实页面元素；
CDP 执行输入事件；
Tool 返回新的页面状态或 Diff。

所以，LLM 没有“点击页面”。它生成了一个点击意图，Browser Tool Plane 才负责把意图变成确定性的浏览器操作。

这一层还应该维护几个重要约束：

Page、Tab、Window 的稳定身份；
导航前后元素引用何时失效；
Frame 和弹窗如何归属；
Screenshot、DOM Snapshot 与当前页面是否来自同一时刻；
Tool 的副作用、超时、重试和错误语义；
多 Agent 并行时，谁拥有哪个 Tab 或 Session。

模型能力会快速变化，但这些状态问题不会自己消失。对 AI 浏览器来说，真正值得长期积累的往往就是这层。

第五层：Product 与 Native Integration

如果 BrowserOS 只需要做一个网页助手，到第四层为止，用 Chrome Extension 加本地 Server 也可能实现大部分能力。

它选择 fork Chromium，是因为产品还需要控制 Extension 权限之外的浏览器生命周期。

BrowserOS 在 Chromium 中加入了 chrome.browserOS.* 私有 API。Extension 侧的 adapter.ts 暴露了版本读取、Pref 读写、路径选择和指标记录等接口。

这一层可以包含：

Browser 和 Sidecar Server 的启动、停止与端口配置；
私有 Extension API 与权限；
浏览器设置和产品 Pref；
首次启动、Importer、默认页面和产品入口；
内置 Extension、产品图标、名称和 Bundle Identity；
OS 级文件、进程、签名和更新集成。

它相当于 Extension 世界与原生 Chromium 世界之间的一座桥。Extension 仍然适合快速构建 UI，但产品不再受限于标准 Extension API。

代价也很明显：一旦 fork Chromium，就要长期维护 Patch Stack、解决上游冲突、承担跨平台编译和安全更新压力。fork 不是“更高级”的默认答案，它只是用更高的维护成本换取更深的产品控制权。

第六层：Chromium Kernel

最底层仍然是 Chromium。

Blink 负责页面渲染，V8 执行 JavaScript，Network Stack 处理请求，Profile 保存 Cookie、密码、扩展和用户设置，多进程架构隔离 Browser、Renderer、GPU 等进程。BrowserOS 可以在上面加 Agent，但不能绕开这些基础设施。

这一层还决定了 AI 浏览器的一个重要特性：它操作的不是一个抽象网页，而是用户真实的浏览环境。

真实环境意味着已登录 Session、Cookie、本地扩展、下载、权限弹窗、多窗口和长期 Profile；也意味着一次错误点击可能产生真实副作用。相比临时启动的 Headless Browser，这种能力更接近日常工作，也更需要清晰的权限、确认和审计边界。

BrowserOS 的 Chromium 相关代码集中在 packages/browseros，包括 Chromium 版本 Pin、Patches、替换文件、资源和 Python 构建系统。

第七层：Engineering Delivery Control Plane

前六层解释了 AI 浏览器怎样运行，第七层解释它怎样成为一个能交付的软件产品。

我把它叫作 Engineering Delivery Control Plane，因为它不在一次 Agent 请求的调用链上，却贯穿 Browser、Server、Extension、CLI 和所有平台产物。

这一层负责回答：

基于哪个 Chromium commit 构建？
哪些 Patch 按什么顺序应用？
BrowserOS 与 BrowserOS neo 各自包含哪些资源？
macOS、Windows、Linux 如何编译和签名？
多个平台怎样证明来自同一个 Release Candidate？
Browser、Extension、Server 和 CLI 怎样独立更新？
哪些产物只是 Staged，哪些已经真正发布？

这也是为什么我不建议只从运行时代码理解 AI 浏览器。没有这层，前六层可以做 Demo，却很难稳定追上 Chromium 安全更新并持续交付给用户。

一个任务如何穿过六层运行时

现在用一个具体任务把调用链串起来：

总结当前页面，并把结论写入 Notion。

1. Interaction Surface 接收任务

用户在 Side Panel 输入指令。Extension 读取当前 Tab 和选中的上下文，向本机 /chat 发起请求。

2. Agent Runtime 创建执行上下文

Server 恢复或创建 Conversation，组装 Browser Context、Model Config、Message History 和可用 Tools。

3. Model 生成 Browser Tool Call

模型并不知道页面完整内容，于是请求 snapshot。Agent Loop 不执行网页操作，只负责校验并分发这个 Tool Call。

4. Browser Capability 读取真实页面

browser-mcp 调用 browser-core，后者通过 CDP 从 Chromium 获得页面状态，再返回对模型更紧凑的 Snapshot。

5. Agent Loop 继续推理

模型根据 Snapshot 生成总结。随后它决定调用 Notion 对应的外部 MCP Tool。

6. External Capability 产生业务副作用

Notion MCP 接收结构化参数，创建或更新页面，并把结果返回 Agent Runtime。

7. Interaction Surface 展示结果

Server 将执行状态和最终答案流式返回 Side Panel，用户看到任务结果。

完整路径可以压缩成：

User
  ↓
New Tab / Side Panel
  ↓ HTTP
Local Agent Server
  ↓
Agent Loop ←→ LLM Provider
  ↓ Tool Call
Browser MCP / External MCP
  ↓
Browser Core
  ↓ CDP
Chromium
  ↓
Page State / Real Side Effect

这里存在一个重要边界：BrowserOS 源码能证明这些组件和调用关系存在，但不能仅凭静态源码证明每个网站、每个模型、每个任务都能可靠完成。任务成功率仍然需要基于真实任务集、Provider 和环境做运行时评测。

BrowserOS 怎样构建

BrowserOS 没有把构建过程写成一条越来越长的 Shell Script，而是在 bos_build 中实现了一套 Python Build CLI。

它的心智模型是：

1
2
3

preset + product + platform + arch + switches
                         ↓
                ordered build steps

其中：

preset 区分 Release、Debug 等构建目标；
product 区分 BrowserOS 与 BrowserOS neo；
platform 由当前 Host 决定；
arch 可以是 x64、arm64 或 universal；
switches 控制 Clean、Provision、Resource Mode、Sign、Upload 等行为。

planner.py 根据这些输入生成有序步骤。一次完整构建大致经过：

锁定 Chromium Source
→ 准备或校验源码缓存
→ Clean / Git Sync / Configure
→ 构建或下载公共资源
→ 应用文件替换和 Patch Stack
→ 注入 Extension、Onboarding、Server
→ 编译 Chromium
→ 签名
→ 打包
→ 上传候选产物

这里要注意两个点。

第一，BrowserOS 不是在 Chromium 编译完成后换个 Logo。Patches、替换文件、私有 API 和内置资源会在编译前进入源码树，最后生成一个新的 Chromium 产品。

第二，build 只负责生成当前 Host 能生成的产物。macOS 机器不能替代 Windows 完成 Windows 原生签名，单台机器也不能自然证明所有平台产物来自同一个版本。因此 Build 成功不等于完整 Release 完成。

Build、Release、Update 是三件事

这三个词经常被混用，但它们对应三个不同的状态转换。

阶段	输入	输出	核心问题
Build	源码、依赖、配置	二进制和安装包	能不能构建出来
Release	多平台产物、签名、Evidence	可发布候选和正式版本	这些产物是否一致、可信、可分发
Update	已发布版本、Feed、客户端策略	已安装客户端升级	客户端如何发现并安全消费新版本

一个 Binary 在本地编译成功，只能证明 Build；上传到对象存储但没有切换 Feed，通常只是 Staged；客户端能从正式 Feed 发现并安装，才进入 Update 链路。

把这些状态分开，会少掉很多“明明发布了，为什么用户收不到”的问题。

BrowserOS 怎样发布多平台版本

BrowserOS 的完整 Release 设计记录在 release-ci.md 和 release-browseros.yml 中。

主流程是：

从 main 手动触发
→ 创建或恢复不可变 Candidate Commit / PR
→ 公共资源只构建一次
→ Linux x64
→ Windows x64 + Signing
→ macOS arm64 / x64 / universal + Signing / Notarization
→ 校验所有 Lane Evidence
→ 合并未发生变化的 Candidate PR
→ 创建 Draft GitHub Release
→ 生成 Appcast Preview
→ 人工检查并 Promotion

这里最关键的设计是 immutable candidate。

多平台编译通常需要不同 Runner，耗时也不同。如果每个 Runner 都在执行时读取最新 main，那么 Linux 开始编译后，main 可能又进入了新 commit；最终几个安装包虽然写着同一个版本号，内部源码却可能不一致。

BrowserOS 先冻结 Candidate SHA，再让公共资源和各平台 Lane 都绑定这个 SHA、Browser Version、Component Version 和资源摘要。Release Gate 只有在完整矩阵通过后才允许继续。

这不是为了让 CI 看起来复杂，而是在解决一个真实的 Supply Chain 问题：同一个 Release 中的多个产物，如何证明它们属于同一次构建意图。

另一个值得借鉴的边界是“CI 只 Stage，不自动 Promote”。

完整 Release Workflow 会准备 R2 产物、Draft GitHub Release 和 Appcast Preview，但正式下载别名和更新 Feed 仍然需要显式发布。因为 Promotion 会直接影响已安装用户，它应该是一次独立、可检查、可回滚的决定。

Update 不是一个 Updater

AI 浏览器不是单一 Binary。BrowserOS 至少包含 Browser、Extension、Local Server、BrowserOS neo Server、Onboarding 和 CLI 等可独立演进的产物。

产物	版本与发布方式	客户端发现方式
Browser	多平台签名安装包、版本化对象、Release Metadata	Browser Appcast、正式下载别名或平台安装流程
Extension	固定 Extension ID、签名 CRX	`update-manifest.xml`
Local Agent Server	独立 Server Bundle 和版本	签名 OTA Appcast
BrowserOS neo Server	Rust Native Bundle、独立版本	独立 OTA Feed
Onboarding	独立资源 Bundle	Browser Build 或资源发布链路消费
CLI	独立 Workflow、Tag 和安装清单	CLI 安装或升级入口

从 bos_build/README.md 和 Release Workflows 可以看到，Extension、Server 与 Browser 并不强制共享一个版本号。

这很合理。一个 Extension UI 修复不应该要求重新编译整个 Chromium；Server Agent Loop 更新也不一定要重新发布 Browser 安装包。独立版本减少了发布成本，但同时引入兼容性问题。

因此，一个完整的多产物更新系统至少需要：

Component Version
+ Compatibility Contract
+ Immutable Artifact
+ Signature / Checksum
+ Mutable Feed / Alias
+ Client Update Policy
+ Rollback Strategy

其中最容易被忽略的是 Compatibility Contract。Browser 内置的私有 API、Extension、Server 和 Browser Tools 如果独立升级，必须明确支持哪些相邻版本。否则每个组件都更新成功，组合在一起反而不能运行。

为什么需要 BrowserOS neo

BrowserOS neo 展示了这套分层的另一个价值：交互层可以替换，底层浏览器能力仍然复用。

BrowserOS 面向人，Agent UI 内置在浏览器中；BrowserOS neo 面向外部 Agent，核心入口是 MCP，并提供 Dashboard、并行 Session 和 Replay。当前代码分别位于 claw-server-rust 和 claw-app。

这意味着“AI 浏览器”可以有两种产品角色：

Browser for Humans
浏览器是主产品，Agent 是内置能力

Browser for Agents
Agent 是调用者，浏览器是有状态的执行环境

第二种形态很值得 Agent / AI Infra 方向关注。它不要求每个 Agent Framework 都重新实现 Playwright 封装、登录态迁移、Tab 管理和页面观察，而是把浏览器沉淀成稳定的 Capability Server。

什么情况下只做 Extension，什么情况下 fork Chromium

最后回到一个务实问题：做 AI 浏览器，是不是都应该 fork Chromium？

我的判断是，不应该。

优先做 Extension

如果产品主要是：

总结、翻译和问答；
读取当前 Tab 内容；
在 Extension 权限范围内填表和导航；
快速验证产品价值；
可以接受跟随 Chrome 的产品入口和更新机制。

那么 Extension + Local Server 通常是成本更低的选择。先验证用户是否真的需要 Agent 完成这些任务，再决定是否接管浏览器底座。

考虑 fork Chromium

当产品明确需要：

浏览器级私有 API；
原生管理 Sidecar Runtime；
控制 New Tab、Importer、Profile、进程和产品身份；
内置并固定关键 Extension；
拥有安装包、签名、更新渠道和默认行为；
在 Chromium 上游之下维护长期产品差异。

这时 fork 才有足够收益覆盖维护成本。

重点建设 Browser Capability Layer

不管最终选择 Extension、Chromium fork 还是独立 Browser Runtime，Browser Capability Layer 都值得尽早独立出来。

因为模型会换、UI 会改、MCP Client 会增加，但 Page、Tab、Frame、Navigation、Snapshot、Input 和 Side Effect 的语义需要长期稳定。只要这一层保持清晰，上层可以接内置 Agent，也可以接外部 Agent；下层可以继续使用 CDP，也可以逐步增加更原生的能力。

我的判断

拆完 BrowserOS 后，我对 AI 浏览器的判断变得更具体了。

聊天框决定用户从哪里开始，模型决定下一步想做什么，真正把任务落到网页上的，是 Browser Tool Plane；真正让产品能追上 Chromium 并交付给用户的，是 Delivery Control Plane。

所以 AI 浏览器的长期壁垒，很可能不在某个模型 API，也不在一个漂亮的 Side Panel，而在三件更慢的事情上：

能否把复杂浏览器状态压缩成稳定、低 Token、可验证的 Tool Contract；
能否约束登录态、文件、页面操作和外部系统中的真实副作用；
能否持续完成 Chromium 升级、多平台签名、多产物兼容和安全更新。

如果只想验证一个页面助手，Extension 已经足够；如果要做浏览器级产品，就要接受 Chromium fork 带来的长期成本；如果目标是让不同 Agent 稳定使用真实浏览环境，那么最值得先建设的，是独立于模型和 UI 的 Browser Runtime。

AI 浏览器看起来像一个应用，真正需要经营的却是两套系统：一套让 Agent 在浏览器里可靠工作，一套让这套能力持续、安全地到达用户机器。

参考源码

本文全部源码引用固定在 BrowserOS 5ddb0f2d0：

Taste Is All You Need

2026-08-09T16:18:00.000Z

当 AI 把实现速度拉到过去难以想象的水平，作品之间的差距就不再只取决于“能不能做出来”，还取决于你选择做什么、删掉什么，以及用什么标准宣布完成。

过去一个月，我用 Coding Agent 跨进了不少原本陌生的领域。我用 Swift 做 macOS App，也独立完成 Agent 工作台、产品渲染、动效和技术文档。过去会被我拆成多个专业环节的事情，现在一个人就能先做出可运行、可比较的版本。

变化不只发生在速度上。当我让模型自由发挥时，它经常交回熟悉的答案：深色背景、蓝紫渐变、玻璃卡片，以及一句“输入你的需求，让 AI 帮你完成一切”。这些方案并不一定差，问题是它们太容易互换。换一个 Logo，产品仍然成立，也意味着它没有留下多少自己的判断。

实现成本下降后，另一个瓶颈开始变得清楚：Taste。

我说的 Taste 不只是审美偏好。它是对目标、取舍、边界和完成标准的判断：什么问题值得做，哪个方案更适合用户，哪些细节必须坚持，哪些效果应该删掉，以及一个功能虽然能做，为什么仍然不该继续加。

标题借用了 Attention Is All You Need 的句式，“All” 是有意的夸张。业务理解、工程能力、领域知识和持续交付仍然不可替代。更准确的说法是：当 AI 可以快速提供大量可行实现时，Taste 决定这些实现最终会被组织成什么样的作品。

一句话总结

AI 没有让工程能力失去价值，它改变了瓶颈的位置：生成候选越来越便宜，定义问题、比较方案、拒绝噪声、验证结果和沉淀标准变得更重要；我把这组带责任的判断称为 Taste。

AI 降低了“做一版”的门槛，也提高了“选一版”的要求

传统软件开发里，执行成本本身就是一道筛选器。

一个想法要经过设计、开发、联调和测试，很多不够重要的需求会因为成本太高而自然消失。现在，这道筛选器正在变薄。在我的实际工作里，一个 Prompt 可以很快展开多套界面，Agent 可以连续修改几十个文件，过去需要较长排期才能比较的方向，可以先在一个晚上做成原型。

于是问题发生了变化：

实现成本较高时	候选大量出现后
能不能实现？	值不值得实现？
能不能做出第一版？	哪一版更接近目标？
功能够不够？	哪些功能应该删除？
页面是否完整？	它有没有稳定的产品身份？
Demo 能否运行？	结果是否经得起长期使用？

这里不存在一个严格的因果公式：使用 AI 不会自动让所有人拥有相同执行力，生成速度提高也不必然导致产品同质化。我的判断来自一个更具体的变化——当候选数量增加时，选择、验收和承担结果的成本不会一起消失。

AI 可以把货架迅速摆满，但它不会替产品负责人决定什么应该上架。方向准确时，它能让模糊想法迅速长成产品；方向错误时，它也能以很高的完成度把错误做得更远。

Taste 是一套带责任的判断

我现在用五类选择理解 Taste：

判断	要回答的问题
问题选择	这是一个真实问题，还是一个热闹概念？
目标与层级	用户第一眼应该看见什么，完成什么？
取舍	哪些能力、装饰和表达应该被删除？
边界	稳定性、性能、可访问性和业务约束在哪里？
完成标准	什么证据足以证明它可以交付，什么仍然只是 Demo？

这也是为什么 Taste 不能只用“好不好看”衡量。一个漂亮但不稳定的窗口、一个功能很多却让用户失去控制的 Agent、一个氛围很强但读不清正文的页面，都可能有审美，却缺少完整的产品判断。

Taste 也不只体现在加了什么。那些没有进入最终版本的颜色、按钮、动画和功能，往往更能说明一个产品知道自己是谁。

我做 Owlet 和专业 Agent 工作台时，对这一点感受很深。

Owlet：AI 帮我跨进陌生领域，产品仍然需要我拍板

Owlet 是我用 Claude Code 和 Codex 做的一款 macOS menu-bar 应用。它来自一个很私人的问题：我每天大量使用 Coding Agent，到底消耗了多少 token，哪些项目最活跃？

我是前端工程师，并不熟悉 SwiftUI、AppKit、NSPanel、Sparkle 和 macOS 签名发布。按过去的学习路径，我可能会先系统学习 Swift，再从 Hello World 慢慢摸到 menu bar。Coding Agent 把这条路径压缩了：我可以直接从真实需求出发，在实现中补齐陌生领域知识。

AI 解决了大量“怎么做”的问题，下面这些决定仍然需要我回答：

为什么常驻菜单栏，而不是再做一个 Web dashboard？
为什么叫 Owlet，为什么是一只会眨眼的小猫头鹰？
为什么功能围绕使用量、会话状态和学习展开，而不是堆成 Agent 百宝箱？
为什么界面要像原生 macOS 工具，却不能失去自己的气质？
当系统材质带来崩溃风险时，是继续追求效果，还是换一种安全实现保留视觉语义？

模型可以列出候选，却不知道哪一个更像“我愿意长期放在自己菜单栏里的东西”。

Owlet 早期也出现过许多容易生成的方案：更强的光效、更满的卡片、更通用的科技蓝、更醒目的金色。单独看都说得过去，组合起来却越来越像一个没有身份的 AI dashboard。

让它定下来的，是一句和代码无关的话：

你知道临安青山湖水上森林吗？产品配色和调性从这个景区的主要元素蒸馏。

这句话没有指定 hex，也没有规定某个组件怎么写。它给了产品一个母题，让后续的局部选择拥有共同来源。

湖面变成主操作的湖水青，水杉变成成功和运行状态，远山承担次级信息，雾白负责空间和层次，晨光金只留在极少量高光里。母题也同时定义了禁区：不做赛博霓虹，不让金色主导 surface，不用重阴影堆层级，不为了“可爱”牺牲信息效率。

后来为了让灵动卡接近系统组件的玻璃质感，我们尝试过 macOS material 和窗口采样，特定组合会带来稳定性风险。最后我没有放弃“雾”，也没有为了视觉效果继续赌系统边界，而是改用纯 SwiftUI 绘制柔焦层：保留雾白的视觉职责，换掉高风险实现。

这也是 Taste：知道哪个体验必须保留，哪个实现可以妥协，并让审美服从稳定性、性能和可读性。

青山湖：一套风格要先学会删

青山湖风格是在一次次“不对”里长出来的，色板只是后来沉淀出的结果。

Agent 很容易把“自然感”理解成多放几种自然色，把“现代感”理解成更多渐变和胶囊，把“氛围感”理解成让装饰铺满页面。真实界面跑起来后，我反复给出的反馈却是：

颜色太花，只保留一个主导色；
胶囊按钮突兀，不要为了风格强行统一形状；
云雾只负责环境，不能侵入阅读区；
卡片之间优先用间距和层级组织，不要继续套卡片；
晨光金只能是稀缺高光，不能变成主题色；
动画只解释状态，不负责表演。

这段过程让我确认：设计风格首先是一套删减规则。

如果只告诉 AI“可以用什么”，它会很积极地把所有特征一起用上。输出真正开始稳定，是因为规则同时写清了“最多用多少”“只能用在哪里”“什么情况下不要用”。

青山湖于是从一句审美偏好，变成一套可执行约束：颜色有 semantic roles，圆角有范围，间距有节奏，动效有性能与可访问性边界，组件有 anti-pattern。它被写进 DESIGN.md，又被收录进 Design Language Atlas。

“我喜欢这个感觉”
        ↓
“我为什么喜欢它”
        ↓
“它在产品里承担什么职责”
        ↓
“什么情况下算做对，什么情况下算跑偏”

Taste 走到最后一层，才不再依赖某一次聊天的运气，而成为下一次 Agent 仍能执行的工程资产。

专业 Agent 工作台：同一种 Taste，不等于复制同一个界面

青山湖后来从 Owlet 迁移到了另一个专业 Agent 工作台。两个产品的技术栈和使用场景完全不同：Owlet 是个人使用的 macOS 工具，后者则面向复杂任务、页面探索和技能复用。

把两边都染成青绿色没有迁移价值。跨端复用的是同一套判断：低噪声画布、清晰的信息层级、克制的状态色、不过度装饰的 glass surface，以及让内容始终压过背景的优先级。

到了这个工作台，这套判断必须适应专业产品的密度。聊天入口可以有缓慢移动的云雾，进入任务和报告后，装饰必须后退。正文、筛选器、状态、日志和结果证据要更紧凑；loading、empty、error 和 success 继续使用同一套自然语义，但不能因为“青山湖”降低扫描效率。

这个工作台的产品路径也体现了另一种 Taste：不把 Agent 的全部能力堆到用户面前，而是把复杂执行收束成可理解、可确认、可验收的过程。

用户提出目标
  → Agent 理解意图并匹配项目与技能
  → 用户确认范围和边界
  → 多个执行单元并行工作并保留证据
  → 报告交付结果、优先级与行动建议

范围确认没有“一句话直接开跑”那么酷，却让用户在消耗执行资源前看清边界；报告也不只展示 Agent 跑了多少步骤，而是把结果整理成业务能够使用的行动建议。

这让我对 Taste 有了更完整的理解：它还决定产品把复杂度放在哪里。好的产品不会假装复杂度不存在，而是把它安排在用户能够理解、控制和验收的位置。

从直觉到 Skill：让下一次 Agent 继续做对

只在一个产品、一个页面或一次会话里成立的偏好，还不是可复用能力。

我后来把 Owlet、专业 Agent 工作台、Design Language Atlas 和相关 Landing Page 里的实践重新扫描了一遍，抽取出公开的 Qingshan Lake Design Skill。它覆盖 macOS、iPhone/iPad、Android、React Native、Web dashboard 和 Landing Page。

这次抽取没有把同一套界面复制到六个平台。共享的是一套 semantic vocabulary：canvas、surface、text、primary action、focus、success、warning、error，以及明确的 anti-pattern；各平台仍然遵守自己的交互模型和验收方式：

平台	青山湖风格必须服从的系统边界
macOS	窗口缩放、键盘与鼠标、原生 material、Reduced Transparency
iPhone/iPad	Safe Area、Dynamic Type、触控目标和系统导航
Android	Material 3 roles、48dp target、edge-to-edge、tablet 与 foldable
React Native	共用 typed theme，但保留 VoiceOver、TalkBack 和双端行为差异
Web dashboard	中高信息密度、键盘 focus、响应式与可读 surface
Landing Page	叙事层级、LCP、响应式媒体和渐进式氛围

Qingshan Lake Design Skill 里除了 token，还有布局顺序、材质策略、状态合同、Reduced Motion、对比度检查和禁区。它不证明 Taste 可以被 AI 自动拥有；它证明的是另一件更务实的事：人的判断可以被外化成 Agent 能读取、实现和验收的约束。

这不是三个项目，而是一条设计生产链

如果只讲 Qingshan Lake Design Skill，这套方法仍然少了两端：判断从哪里来，以及视觉资产怎样稳定生产出来。

环节	项目	解决的问题
Reference	Design Language Atlas	建立可搜索、可比较的设计语言与真实界面参考，回答“有哪些可能，为什么这个方向适合当前产品”
Constraint	Qingshan Lake Design Skill	把景观母题蒸馏成 semantic tokens、组件规则、跨端适配和 anti-pattern，回答“怎样持续做对”
Production	better-imagegen	按资产类型选择模型与工作流，完成 prompt 约束、模型级联、后处理、metadata 和 QA，回答“怎样稳定交付可用资产”

Design Language Atlas 不是换皮网站。除了设计语言索引和可运行 Demo，它还在继续补 UI Reference、Design Systems、组件、模板和社区 UI Skills。它的价值不是替我选风格，而是把零散收藏变成可以搜索、对照和拆解的 Reference 系统。

better-imagegen 也不只是给图片 API 包一层调用。封面、插图、Logo、壁纸、sprite loop 和 Codex pet 对尺寸、透明度、文字准确性、压缩与验收的要求完全不同，因此需要不同的生产路径。比如本文封面先由图片模型生成无文字的青山湖氛围底图，再用 HTML/CSS 确定性排版标题，最后转成 WebP 并记录生成 metadata。模型负责打开视觉可能性，工程流程负责保证文字、尺寸和交付结果没有靠运气。

这三层刚好对应 Taste 的三个动作：先扩大看过的世界，再把选择写成约束，最后把约束变成稳定产物。 对我来说，这同样是设计，而不是设计完成之后的辅助工作。

这也是整篇文章最关键的闭环。Taste 如果只能由作者本人“看一眼就知道”，它仍然难以规模化；当它能解释为什么、约束在哪里、怎样验证，才会从个人直觉变成团队和 Agent 可以复用的生产资料。

AI 能不能帮助人提升 Taste？

可以，但不要把最终选择也外包给模型。

AI 对 Taste 最有价值的地方，是降低探索和对照成本。过去做视觉研究，需要自己收集案例、拆组件、试实现；现在可以让 Agent 快速生成不同方向、分析差异、把参考转换成 token，再放回真实界面比较。

我现在使用这样一条循环：

Reference：先扩大看过的世界

Taste 不会从空白 Prompt 里凭空出现。产品、建筑、电影、自然景观和真实生活，共同构成判断的坐标系。

我做 Design Language Atlas，目的不是让 Agent 随机套一套皮肤，而是建立比较能力：同一个 dashboard 为什么适合青山湖、不适合 Cyberpunk；同样是 glass，原生系统 material 和业务后台的半透明 surface 分别承担什么职责；哪些产品需要情绪，哪些产品更需要秩序。

Diverge：让 AI 打开有意义的可能性

AI 很适合快速生成候选。这个阶段先比较方向：产品更安静还是更活跃，信息更集中还是更舒展，品牌母题来自自然、建筑还是角色。

发散的价值是暴露选择，不是留下更多图片。

Select：把“不对”说清楚

“不好看”“不高级”无法形成长期能力。更有效的反馈是：主操作不突出、背景侵入阅读区、圆角让专业工具显得玩具化、动效节奏抢走注意力。

当我能说清“不对在哪里”，直觉才开始变成可以讨论和复现的判断。

Constrain：把偏好写成规则

颜色要有语义，间距要有范围，组件要有职责，动效要有性能和可访问性边界，还要明确 anti-pattern。与其写“保持高级感”，不如写“湖水青是唯一主操作色；浮萍绿控制在极小面积；不要卡片嵌套卡片”。

清晰约束不会限制 Agent，反而能让它把算力用于更有价值的探索。

Verify：回到真实产品

设计稿里成立的东西，放到菜单栏的真实尺寸、数据密集工作台、不同尺寸屏幕和长时间动画里，可能完全是另一回事。

Owlet 的图标要在菜单栏真实尺寸验收，专业 Agent 工作台的云雾要连续观看仍不打扰阅读，玻璃组件要检查文字对比度，动效要尊重 Reduced Motion。截图只能证明一个瞬间，Taste 要经得起持续使用。

Remember：记住拒绝过什么

只保存“最终用了什么”还不够。很多一致性来自对失败经验的记忆：为什么不再用大面积金色，为什么不恢复高风险系统材质，为什么数据页面不铺云雾，为什么不做纯黑科技风。

把这些决定写进 DESIGN.md、Skill 和验收清单，下一次 Agent 才不会重新走一遍老路。

人和 AI 的新分工

回看 Owlet、专业 Agent 工作台和青山湖风格的形成过程，我更愿意这样划分责任：

人承担最终责任	AI 放大执行能力
选择问题与方向	搜索、生成和展开候选
定义价值、层级和完成标准	把规则翻译成代码与资产
决定取舍、边界和例外	快速试错并执行重复检查
验收真实体验	整理状态、差异与实现证据
沉淀长期判断	在既定约束内持续生产

这不是“人负责想、AI 负责做”的简单二分。AI 也能分析、提出方案和发现问题，人也必须理解工程。真正不能模糊的是最终责任：模型给出十个版本之后，必须有人决定哪一个值得留下；Agent 把功能跑通之后，必须有人判断它是否解决了问题。

AI 时代的超级个体，不需要亲手包办所有专业角色。他需要一套足够清晰的判断框架，再让 Agent 把执行力放大。

我的判断框架：Taste 什么时候真正有价值

值得投入： 当 AI 已经能快速产出候选，而产品仍然缺少方向、辨识度或稳定完成标准时，优先补 Reference、选择规则、anti-pattern 和验收方式。
不能替代： 涉及安全、合规、数据正确性和复杂系统边界时，Taste 不能替代专业知识、工程验证和责任机制。好判断必须建立在真实约束上。
重点关注： 不要只记录最终选择。把删掉什么、为什么删、什么证据会推翻当前决定一起沉淀，下一次协作才不会从零开始。

“Taste Is All You Need” 不是说有品味就不需要技术。只有理解技术边界，Taste 才不会停在漂亮图片；只有理解业务，Taste 才能从视觉偏好进入产品取舍。

发生变化的是稀缺性的顺序。

代码会更容易生成，界面会更容易完成，内容会更容易填满。更难复制的，是一个人长期形成的参考系、对细节的敏感、拒绝平庸方案的勇气，以及把一次直觉变成可复用标准的能力。

AI 会让更多人拥有更强的执行力，却不会自动替任何人承担选择的责任。

当“做出来”不再是唯一瓶颈，选择做什么、删掉什么、坚持什么，就是作品本身。

本文由 writting-skill 辅助生成，文章观点、项目事实与最终判断由作者确认。

延伸阅读与项目

Evidence 到底是什么：Agent 系统如何证明自己真的完成了任务

2026-08-04T18:15:00.000Z

Evidence 不负责让 Agent 看起来更可信。它负责把“相信”变成一件可以复查、反驳和重新计算的事。

最近我反复看到 Evidence。它出现在 LLM Wiki、RAG、Agent 执行、评测、审计和业务验收中。有的产品把检索片段叫 Evidence，有的把截图和日志叫 Evidence，还有的把一整条 Trace 都塞进 Evidence Store。

这些做法都碰到了 Evidence 的一部分，但没有回答最核心的问题：Evidence 到底在证明什么？

上一篇《Agent 系统的一级领域对象：从 Task、Run 到 Evidence》把 Evidence 放进了 Agent 的一级领域模型。这一篇只拆 Evidence。我想讲清它为什么属于 Trust & Verification、为什么不能和 Source、Citation、Trace、Artifact、Proof、Evaluation 混在一起，以及进入生产后应该怎样建模。

一句话总结

我对 Evidence 的定义是：

Evidence 是带有来源、定位、时间、范围和完整性信息，并明确支持或反驳某个 Claim 的可验证事实记录。

它处在这样一条链路中：

Source / Observation
        ↓ 捕获与固化
Evidence ── supports / refutes ──> Claim
        ↓                               ↓
   Provenance                    Evaluation Policy
        └──────────────> Verification Result

这条定义的锚点是“某个 Claim”。单独存在的事实，还没有获得证明方向。

没有 Claim 的 Evidence，只是 Source、Record 或 Observation。

Evidence 属于什么范畴

如果按 Agent 系统的领域边界划分，Evidence 属于：

1	Trust & Verification

它连接三个世界：

世界	核心问题	对象
Execution	Agent 做了什么	Run、Tool Call、Trace
Outcome	Agent 交付或声称了什么	Artifact、Claim
Trust	我们凭什么相信它	Evidence、Evaluation、Verification Result

Evidence 不属于 Knowledge Plane。Knowledge、Memory 和 Context 解决“Agent 能看到什么、记住什么”；Evidence 解决“系统凭什么接受 Agent 的某条结论”。

它也不属于 Observability。Trace 和 Log 记录过程，Evidence 从过程记录、交付物或权威系统中挑出与 Claim 有关的最小事实集合。

一份材料怎样才成为 Evidence

一份材料不会因为被 Agent 检索到、截图了或者写进数据库，就自动成为 Evidence。它至少要通过四道门。

1. Claim Binding：它在证明什么

Evidence 必须绑定具体 Claim，并声明方向：

1 2	supports refutes

例如一次 HTTP 200：

可以支持“这个 URL 在 02:10 可访问”；
不能单独支持“新版本已经发布”；
更不能支持“新功能符合业务预期”。

同一条事实对不同 Claim 的证明力完全不同。Evidence 的证明力始终相对于 Claim而存在。

2. Provenance：它从哪里来

Evidence 必须能够回到产生它的主体、活动和原始实体。

W3C PROV-O用 Agent、Activity、Entity 作为 Provenance 的起点：谁承担责任、什么活动发生过、活动使用或生成了什么实体。对 Agent 系统而言，至少要保留：

Source System；
Source Object 或 URI；
Collector Identity；
Run ID；
Capture Method；
Observed At；
Content Digest。

只有 URL 通常不够。URL 指向的内容可能变化，权限也可能变化。必要时要保存 Snapshot、精确 Locator 和 Hash。

3. Scope & Time：它在什么范围内有效

Evidence 必须说明：

针对哪个环境；
哪个版本或 Revision；
哪个账号、租户或业务对象；
哪个时间点；
哪些前置条件；
什么时候过期。

测试环境通过不等于生产环境通过；昨天的库存状态不能证明今天仍有货；管理员账号看到的页面不能证明普通用户也能看到。

4. Integrity：它有没有被替换或篡改

Integrity 解决“我现在看到的，还是不是当时采集的那份材料”。常见手段包括：

内容 Hash；
不可变 Artifact ID；
数字签名；
时间戳；
Append-only Ledger；
受控的 Source of Truth。

这里要特别区分 Evidence 和 Proof。W3C Verifiable Credentials Data Model 2.0明确指出，Evidence 是支持 Credential 中 Claim 的材料；Securing Mechanism 用来验证签发者身份和 Credential 完整性。Credential 能被密码学验证，并不自动意味着其中 Claim 为真。

换到 Agent 领域同样成立：签名可以证明“这条记录由谁签发、有没有被改”，不能替你判断业务结论是否正确。

Evidence 对象内部应该有什么

一个可复用的 Evidence 对象，可以先从下面这组字段开始：

type Evidence = {
  id: string;
  claimId: string;

  type: 'document_span' | 'system_state' | 'test_result'
    | 'screenshot' | 'artifact_digest' | 'attestation';
  polarity: 'supports' | 'refutes';

  sourceRef: string;
  locator?: string;
  snapshotRef?: string;
  contentDigest?: string;

  scope: {
    environment?: string;
    revision?: string;
    subject?: string;
    tenant?: string;
  };

  observedAt: string;
  validAt?: string;
  expiresAt?: string;

  collectedBy: string;
  runId?: string;
  captureMethod: string;
  integrityStatus: 'unknown' | 'verified' | 'failed';
  status: 'candidate' | 'validated' | 'rejected'
    | 'superseded' | 'expired';
};

下面是一套最小领域结构，综合了几类成熟模型的共同思想：

W3C PROV 的 Agent、Activity、Entity 与派生关系；
in-toto Statement用 Subject Digest、Predicate Type 和 Predicate 把陈述绑定到不可变对象；
SLSA 1.2用 Provenance Attestation 描述软件产物如何生成，再由消费者执行验证策略；
Verifiable Credentials 用 Issuer、Subject、Validity、Status、Evidence 和 Securing Mechanism 组织可验证声明。

我不会直接照搬其中任何一个 Schema，因为 Agent 的 Evidence 不只服务软件供应链或 Credential。真正值得复用的是它们的共同原则：先固定 Subject 与 Claim，再保存 Predicate、Provenance、Scope 和 Integrity。

Evidence 和相近概念的边界

Source 不是 Evidence

Source 表达信息来自哪里，Evidence 表达 Source 中哪部分事实支撑哪个 Claim。

一份 200 页政策 PDF 是 Source。第 27 页表格中的某个单元格，加上版本、生效日期和定位信息，才可能成为某条 Claim 的 Evidence。

Citation 不是 Evidence

Citation 是 Claim 指向 Source 或 Evidence 的定位关系。它解决“去哪里看”，不自动解决“这段内容是否真的支撑结论”。

只有链接、没有 Snapshot 和 Locator 的 Citation，还会受到内容漂移影响。

Context 不是 Evidence

Context 是本次 Run 获准看到的信息边界。材料进入 Context，只能说明 Agent 看过它，不能说明它正确、相关或足以支撑结论。

Trace 不是 Evidence

OpenTelemetry把 Trace 组织为由 Span 构成的操作链；OpenAI Agents SDK Tracing会记录 LLM Generation、Tool Call、Handoff、Guardrail 和自定义事件。这些内容非常适合调试、监控和复盘。

但 Trace 回答的是“系统记录到什么过程”，不是“业务结果是否成立”。

1 2	Trace: Agent 调用了 deploy()，接口返回 accepted Claim: 新版本已经在生产环境生效

前者不能直接证明后者。只有部署平台状态、线上版本标识和用户可见结果，才能形成后者的 Evidence Bundle。

Trace 当然可以成为 Evidence。例如它能支撑“Agent 在 02:03 调用了某个 Tool”。但它必须绑定这个具体 Claim，并具备可信的采集与完整性边界。

Artifact 不是 Evidence

Artifact 是 Agent 产出的文件、代码、报告或数据。Artifact 存在，只能证明有交付物；它不能自动证明交付物正确。

测试报告可以同时扮演 Artifact 和 Evidence，但这是两个 Role：作为 Artifact，它是产物；作为 Evidence，它支撑“测试通过”这条 Claim。

Evaluation 不是 Evidence

Evidence 是事实材料，Evaluation 是依据规则作出的判断。

1	Evidence + Evaluation Policy → Verification Result

不要把模型打出的 0.87 直接塞进 Evidence。这个分数属于 Evaluation Result；生成分数所依据的事实、样本和规则才是 Evidence 与 Policy。

一个 Coding Agent 的完整例子

假设 Coding Agent 说：“功能已经发布。”

这句话至少隐藏了五条 Claim：

Claim	可以采用的 Evidence	不能替代它的材料
代码已修改	目标范围内的 Git Diff	Agent 的自然语言总结
修改通过工程验证	测试结果、Build Artifact、退出码	文件已经保存
版本已提交	Commit SHA、Tree Hash	本地工作区状态
版本已推送	Remote Ref 指向目标 Commit	本地 Commit 存在
版本已部署	Deployment ID、目标环境状态	Push 成功
生产结果符合预期	生产 URL、版本指纹、状态检查、真实页面或 API 结果	Deployment Job 显示 success

这里最容易犯的错误，是拿低一层 Evidence 支撑高一层 Claim：

Build passed  ≠  Deployed
Git pushed    ≠  Production updated
HTTP 200      ≠  Expected version served
Screenshot    ≠  All users can complete the flow

Evidence-based Delivery 应先把大而模糊的“完成”拆成可验证 Claim，再为每条 Claim 选择最接近 Source of Truth 的 Evidence。继续堆积截图和日志不会自动补上这层关系。

在 RAG 与 LLM Wiki 里，Evidence 应该是什么

假设回答中出现一条结论：

1	Claim：订单支付后 24 小时内可以免费取消。

一个完整的 Evidence 至少应该包含：

Source:        cancellation-policy.pdf
Revision:      2026-07-18
Locator:       page=12, table=2, row=3
Quoted Span:   支付完成后 24 小时内……
Effective At:  2026-07-20
Scope:         普通订单；不含特价产品
Digest:        sha256:...
Polarity:      supports

向量检索返回的 Chunk 只能算 Candidate Evidence。它还可能：

命中过期版本；
丢失表头或脚注；
越过权限范围；
只在相似语义上相关；
无法支持回答中的具体数字。

因此 LLM Wiki 真正应该管理的，不只是 Chunk 和 Citation，而是：

1	Claim → Evidence Span → Source Revision → Permission Scope

这时用户点开引用，看到的不只是“模型参考了哪篇文档”，而是“这句话具体由哪一段、哪个版本、在什么范围内支撑”。

在 GUI Agent 里，点击不是 Evidence

GUI Agent 的 Trace 经常是：

1
2
3

点击“提交”
等待 2 秒
页面出现绿色提示

这只能证明执行过程被记录。业务验收应根据 Claim 选择更直接的 Evidence：

表单提交：服务端返回的业务 ID；
订单创建：订单系统中的新记录；
退款完成：支付系统状态与交易号；
文件上传：对象存储中的 Key、Hash 与读取验证；
页面发布：生产 URL 的版本指纹与用户可见内容。

截图可以作为补充 Evidence，但它通常存在三个限制：难以结构化比对、可能截错环境、无法证明后端状态。只要存在权威业务系统，就应该优先从权威系统重新读取状态。

Evidence 的生命周期

Evidence 不是写入后永久有效的附件。它应该有自己的生命周期：

candidate
  → captured
  → validated
  → admitted / rejected
  → superseded / expired / revoked

这里有两层判断，不能混在一起：

Evidence Validation：材料是否真实、完整、可定位、未过期，能否进入证据集合；
Claim Evaluation：证据集合是否足以让某条 Claim 通过、失败或保持不确定。

可能出现这些情况：

Evidence 本身有效，但与 Claim 无关；
两条有效 Evidence 相互冲突；
Evidence 支持 Claim，但覆盖范围不足；
原本有效的 Evidence 因 Source Revision 更新而过期；
新 Evidence 推翻了旧 Verification Result。

所以 Verification Result 最好也是可重算的派生对象，而不是直接写死在 Evidence 上。

什么时候应该把 Evidence 做成一级对象

简单聊天机器人可以把 Citation 和 Evidence Span 放在 Message Metadata 中，不必一开始建设复杂平台。

当出现下面任意几种需求时，Evidence 应升级为一级领域对象：

同一条 Evidence 会被多个 Claim、Run 或 Evaluator 引用；
Evidence 需要独立权限与脱敏；
Evidence 会过期、撤销、被替代或重新验证；
系统需要审计“当时为什么通过”；
需要比较不同 Agent、模型或版本采用了哪些证据；
需要第三方复查，或者生成 Acceptance Receipt；
业务不能接受 Agent 用自己的输出证明自己。

最小架构可以分成五块：

Evidence Collector   从 Trace、Artifact、Source of Truth 捕获候选材料
Evidence Normalizer  补齐 Locator、Scope、Time、Digest、Provenance
Evidence Store       保存不可变 Snapshot 与关系
Claim Verifier       按 Policy 组合和评估 Evidence
Verification Ledger  记录谁在何时基于哪组 Evidence 作出什么判断

常见反模式

把所有运行数据都叫 Evidence

结果是 Evidence Store 退化成另一个日志平台。数据很多，但无法回答任何具体 Claim。

让 Agent 自己证明自己

Agent 输出“工具调用成功”只能算自述。高风险 Claim 应由独立 Verifier 从权威系统重新读取状态。

只保存链接，不保存版本和定位

链接内容一变，历史 Verification Result 就无法复现。关键材料至少要有 Revision、Locator 或 Digest。

一个 Screenshot 证明整条业务链

截图能证明某个时刻的视觉状态，不能自动证明后端数据、权限覆盖、持久化和其他用户视角。

把 Confidence 写在 Evidence 上

Confidence 依赖 Claim、Evidence Bundle、Evaluator 和 Policy。把一个全局置信度塞给单条 Evidence，会掩盖判断条件。

只保留通过的 Evidence

反驳材料、冲突材料和被拒绝原因同样重要。否则系统会形成只为既有结论找支持的确认偏误。

我的判断框架

当一个系统说“我们有 Evidence”时，我会连续问八个问题：

它绑定的 Claim 是什么？
它是支持还是反驳 Claim？
Source of Truth 是谁？
能否精确定位并重新获取原始事实？
它适用于哪个环境、版本、主体和时间？
如何确认内容没有被替换？
谁负责验证，依据哪条 Policy？
出现冲突、过期或撤销后，旧结论能否重新计算？

如果这些问题回答不出来，系统拥有的多半只是 Logs、Links、Screenshots 或 Retrieved Chunks，还没有真正建立 Evidence Model。

Evidence 对 Agent 产品最重要的价值，是把“完成”从一次自述改造成可以独立验收的结论：

Agent 可以提出 Claim，但不能只靠自己的话完成验收。系统必须保留足够的 Evidence，让另一个人、另一个 Verifier，甚至未来的另一套模型能够重新得到或推翻这个结论。

参考索引

以下均为本文实际采用的规范、标准或官方工程文档，检索日期为 2026-08-05。

范畴	参考资料	本文采用的依据
Provenance	W3C PROV-O：The PROV Ontology	Agent、Activity、Entity，以及生成、使用、归属、派生和失效关系
Claims / Evidence	W3C Verifiable Credentials Data Model 2.0	Evidence、Issuer、Subject、Validity、Status 与 Securing Mechanism 的边界；可验证不等于 Claim 为真
Attestation	in-toto Statement Layer Specification	Subject Digest、Predicate Type、Predicate 的绑定结构
Software Provenance	SLSA Specification 1.2	Provenance Attestation、Verification Summary 与消费者验证策略
Observability	OpenTelemetry Tracing API	Trace、Span、Event、Status 的过程记录模型
Agent Runtime	OpenAI Agents SDK：Tracing	Agent Run 中 Generation、Tool Call、Handoff、Guardrail 等 Trace 数据的范围
AI Risk	NIST AI RMF：Generative AI Profile	Governance、Pre-deployment Testing、Content Provenance 与 Incident Disclosure 的风险管理视角

本文给出的 Evidence 定义、生命周期和字段模型，是基于这些资料进行的 Agent 领域建模推导，不是任何单一规范的原文 Schema。

如何构建可验证、可恢复、可评测的 Agent Runtime 与 Harness

2026-08-02T14:56:11.000Z

Agent Runtime / Harness 参考架构：以稳定的 Run Contract 包住不稳定的 Model 与 Provider，把验证、恢复和评测变成系统能力。

最近我一直在想，所谓 Agent 工程到底比 Workflow 多了什么。

如果最终只是把 Prompt、LLM 和 Tool 连成一张图，再用 React Flow 画出来，它与 Dify、Coze 里的 Workflow 确实没有本质区别。真正让 Agent 从 Demo 走向生产的，不是节点更多，也不是图更炫，而是系统开始回答三类很不“智能”、却决定能否交付的问题：

Agent 说任务完成了，我怎样证明它真的完成了？
执行到一半进程崩了，我怎样继续，而不是从头再赌一次？
换了模型、Prompt 或 Tool 后，效果究竟变好了还是变差了？

从前端转向 Agent / AI Infra 后，我越来越确信：值得投入的工程对象不是一个新的 Graph Editor，而是一套可验证、可恢复、可评测的 Agent Runtime / Harness。

一句话总结

Runtime 负责让 Agent 跑起来，Harness 负责让这次运行可控制、可追踪、可恢复、可验收、可比较。

服务器、容器、Sandbox 只是 Execution Environment；Agent Runtime / Harness 是运行在这些环境之上的控制系统。它不需要替模型思考，但必须约束模型如何访问状态、调用工具、产生副作用、等待审批、保存进度和交付结果。

我会用下面这条公式判断它是否真正落地：

Production Agent
= Model / Agent SDK
+ Stable Run Contract
+ Controlled Side Effects
+ Durable State
+ Evidence-based Verification
+ Continuous Evaluation

少了后五项，通常只是一个可以演示的 Agent Loop。

Runtime、Harness 和服务器运行环境不是一回事

“Runtime”这个词确实容易模糊，因为它在不同语境中指向不同层次。

层次	典型对象	负责什么
Execution Environment	Server、Container、Sandbox、Browser、Local Host	CPU、内存、网络、文件系统、进程隔离
Model Runtime	Model API、Inference Server	接收输入并生成 Token、Tool Call 或结构化输出
Agent Runtime	Agent Loop、Run State、Tool Dispatch、Streaming、Handoff	驱动一次 Agent 执行
Agent Harness	Policy、Approval、Checkpoint、Trace、Evidence、Eval	管理 Agent 执行的生产边界

现实中，Runtime 和 Harness 经常被混用。我的建议不是争论名词，而是把职责写清楚：

如果一个组件只负责 while 循环、调用模型和分发 Tool，它更接近 Agent Runtime。
如果它还拥有 Run ID、权限、审批、恢复、证据和评测，它已经是 Harness。
如果它只提供 Linux、Node.js、Python 和网络，那只是运行环境，不是 Agent Runtime。

这也是为什么部署了一个 Agent SDK，并不等于拥有了生产级 Runtime。SDK 解决的是“怎样调用”，Harness 解决的是“这次调用在业务上是否受控、可信、可持续演进”。

它与 Workflow 的真正区别

Workflow 描述希望执行的路径，Runtime / Harness 管理实际发生的执行。

Workflow:  A → B → C

Runtime:   谁启动了 A？
           B 重试后会不会重复扣款？
           C 等待审批时状态存在哪里？
           进程重启后从哪一步继续？
           最终结果由什么证据证明？
           这次执行比上一个版本好在哪里？

因此，一张静态 Graph 可以是 Runtime 的输入，却不是 Runtime 本身。很多 Agent 任务甚至无法预先画出完整路径：模型会根据中间结果决定继续搜索、修改计划、调用其他工具或请求人工介入。

我会把两者关系理解成：

1 2	Workflow / Graph = Execution Plan Runtime / Harness = Execution Semantics + Control + Evidence

React Flow 只解决编辑和展示。如果产品真的需要让用户配置确定性流程，可以引入；如果当前目标是让 Agent 可靠执行，先做 React Flow 往往会把注意力带到节点拖拽、连线和表单配置上，最难的恢复与验收仍然没有答案。

先固定十个核心对象

一个可演进的 Harness，第一步不是选框架，而是定义自己的领域对象。至少要有下面十个：

对象	最小职责	不应该被什么替代
Workspace	本次执行可见、可修改的工作边界	当前进程目录
Revision	执行绑定的输入与代码版本	“最新版本”
Run	一次可定位的端到端执行	Provider 的 Session ID
Step	可重试、可检查的状态转移	一条自然语言日志
Tool Call	结构化的工具调用请求	模型输出的一段文本
Permission / Approval	谁允许什么副作用发生	Prompt 里的“请小心”
Checkpoint	可恢复的 Run State 快照	聊天记录
Event / Trace	按时间记录发生了什么	最终回答
Artifact / Evidence	支撑完成声明的产物与证据	Agent 自述“已完成”
Eval Result	对结果、过程、成本与韧性的评分	主观体验“看起来不错”

这里最容易混淆的是 Memory、State、Trace、Evidence 和 Eval：

Memory：跨 Run 保留的偏好、事实和经验。
State：当前 Run 此刻执行到哪里，以及继续所需的数据。
Trace：这次 Run 按时间发生过哪些事件。
Evidence：从产物和权威系统中选出的、能支撑某个 Claim 的证据。
Eval：根据预先定义的标准，对结果或过程做判断。

聊天记录可以参与恢复，但它不是完整 State；Trace 可以帮助调查，但它不自动构成 Evidence；Evidence 能证明一次交付，却不能替代跨版本的 Eval。

三条必须守住的工程边界

1. Provider Adapter：隔离不稳定的 Agent 实现

模型、Agent SDK 和 Coding Agent 都会变化。业务系统不应该直接依赖某个 Provider 的 Thread ID、事件名和审批格式，而应该维护自己的稳定协议。

interface AgentRuntimeAdapter {
  start(input: StartRunInput): Promise<ExternalRunRef>;
  resume(input: ResumeRunInput): Promise<void>;
  cancel(runId: string): Promise<void>;
  stream(runId: string): AsyncIterable<AgentEvent>;
}

type AgentEvent =
  | { type: 'run.started'; runId: string }
  | { type: 'model.completed'; usage: Usage }
  | { type: 'tool.requested'; call: ToolCall }
  | { type: 'approval.required'; approval: ApprovalRequest }
  | { type: 'checkpoint.saved'; checkpointId: string }
  | { type: 'artifact.created'; artifact: ArtifactRef }
  | { type: 'run.completed'; claims: Claim[] }
  | { type: 'run.failed'; error: NormalizedError };

内部 runId 是事实主键，Provider Session ID 只是 ExternalRunRef。这样才能在不重写上层业务的情况下更换模型、SDK，甚至把一次任务路由到不同 Runtime。

适配层也不应该强行抹平所有差异。比如某个 Provider 支持原生 Resume，另一个只能重建 Context，应该通过 Capability 声明暴露：

type RuntimeCapabilities = {
  resumable: boolean;
  approval: 'native' | 'emulated' | 'none';
  streaming: boolean;
  sandbox: 'hosted' | 'local' | 'external';
};

“统一接口”不是假装大家能力相同，而是让差异变得可查询、可路由、可评测。

2. Tool Side Effect：所有真实动作经过受控边界

Agent 最危险的部分不是生成了一句错话，而是用错误参数真的执行了退款、发版、删库或发消息。

因此 Tool 不应只是一个普通函数。每次调用至少要绑定：

runId 和 stepId；
调用者与 Workspace；
输入 Schema 和输出 Schema；
风险级别与所需 Permission；
idempotencyKey；
超时、重试和补偿策略；
调用前后的权威状态快照；
产生的 Artifact 与 Evidence。

const result = await toolGateway.execute({
  runId,
  stepId,
  tool: 'release.create',
  input,
  idempotencyKey: `${runId}:${stepId}:release.create`,
  policy: { approval: 'required', timeoutMs: 60_000 },
});

重试只能作用于已声明幂等的边界。否则“失败后自动重试”可能变成重复扣款、重复发信或重复发布。

3. Run State：状态属于系统，不属于某次进程

如果 Node.js 进程一退出，任务就永远丢失，那么它没有真正的恢复能力。

Run State 至少应包含：

type RunState = {
  runId: string;
  status: 'queued' | 'running' | 'waiting_approval' |
          'suspended' | 'completed' | 'failed' | 'cancelled';
  workspace: WorkspaceRef;
  revision: RevisionRef;
  runtime: RuntimeRef;
  currentStep?: string;
  pendingToolCalls: ToolCall[];
  approvals: ApprovalState[];
  artifacts: ArtifactRef[];
  providerState?: unknown;
  contractVersion: string;
  updatedAt: string;
};

contractVersion 很重要。OpenAI Agents SDK 的 Human-in-the-loop 文档已经支持序列化 RunState 后跨请求恢复，同时也提醒：长期挂起任务需要把 Agent 定义和 SDK 版本与序列化状态一起管理。换句话说，Checkpoint 不只是保存 JSON，还要知道它由哪一版代码解释。

可验证：不要相信 Agent 的完成声明

“任务已完成”只是一条 Claim，不是事实。

真正的验证应该回到权威系统重新读取状态。例如 Coding Agent 说“修复完成”，Harness 应检查：

Claim: 修复已完成
  ├─ Evidence: git diff 中只有目标范围的修改
  ├─ Evidence: 目标测试从 fail 变为 pass
  ├─ Evidence: 原有回归测试仍然通过
  ├─ Evidence: 构建产物成功生成
  └─ Acceptance: 目标环境 Smoke Test 通过

如果是退款 Agent，Evidence 应来自支付系统的退款状态与交易号；如果是发布 Agent，Evidence 应来自构建产物、Deployment ID 和线上健康检查，而不是 Tool 返回的“请求已提交”。

我建议把完成逻辑设计成显式的 Claim Verifier：

type Claim = {
  type: 'code.fixed' | 'release.online' | 'refund.completed';
  subject: string;
  evidence: EvidenceRef[];
};

interface ClaimVerifier {
  verify(claim: Claim, context: VerificationContext): Promise<{
    passed: boolean;
    checks: CheckResult[];
  }>;
}

这使“完成”从自然语言变成可执行的 Acceptance Contract。

Trace 与 Evidence 也要分开。OpenAI Agents SDK 的 Tracing 会记录 LLM generation、Tool Call、Handoff、Guardrail 和自定义事件，这非常适合调试和监控；但完整 Trace 只是原始执行记录。Evidence 是从 Trace、Artifact 和权威状态中挑出的、足以支撑 Claim 的最小集合。

可恢复：Checkpoint 只是起点

恢复能力可以按五个等级理解：

等级	能力	主要问题
L0	整个 Run 从头重试	重复成本高，副作用不安全
L1	恢复 Provider Session	能接着聊，不一定能恢复业务状态
L2	按 Step 保存 Checkpoint	能从明确边界继续
L3	Checkpoint + 幂等 Tool + Workspace Snapshot	可以安全应对进程崩溃和重复消息
L4	Checkpoint 可跨 Runtime / Provider 迁移	通用性最高，成本和约束也最高

大多数生产系统应该先做到 L3，不必一开始追求 L4。

LangGraph 的 Persistence 明确区分 Checkpointer 与 Store：前者保存单个 Thread 的 Graph State，用于中断恢复、Human-in-the-loop、Time Travel 和 Fault Tolerance；后者保存跨 Thread 的长期数据。官方文档也直接提醒，MemorySaver 在进程重启后会丢失，生产环境要使用持久化 Checkpointer。

这再次说明：Conversation Memory 不是 Recovery State。

一个安全的恢复循环应该是：

读取 Checkpoint
  ↓
校验 Contract Version 与 Workspace Revision
  ↓
检查上一个 Side Effect 是否已经生效
  ↓
用 Idempotency Key 决定复用结果还是重试
  ↓
恢复 Agent / Provider State
  ↓
继续下一步并写入新 Checkpoint

对于持续数小时、数天，且横跨多个服务的业务流程，可以把 Agent Framework 与 Temporal 组合使用：Agent Framework 负责模型循环和 Tool 选择，Temporal 负责 Durable Execution、Timer、Retry 与跨服务状态。Temporal 的官方定义强调，即使发生进程崩溃、网络故障或基础设施中断，应用也能从离开的地方恢复。它不是 Agent Framework 的替代品，而是更底层的可靠执行基础设施。

可评测：不要只评最终回答

Agent 的输出可能正确，过程却越权、昂贵或不可恢复；也可能过程合理，但外部系统最终没有生效。因此评测至少要分四层：

层次	关键问题	指标示例
Outcome	任务最终是否真的成功	Task Success、Test Pass、State Verification、人工验收率
Process	Agent 走的路径是否合理	Tool Selection、参数正确率、无效循环、越权次数、人工接管率
Cost	成功花了多少资源	Latency、Token、Tool Call、Compute、Cost per Success
Robustness	遇到故障还能否完成	Resume Success、重复消息、超时、部分失败、Checkpoint 恢复率

OpenAI 的评测最佳实践强调 Eval-driven Development、任务特定数据集、完整日志、自动评分与持续评测，并明确反对“感觉它能工作”的 Vibe-based Evals。LangSmith 也把 Agent Eval 拆成 Final Response、Single Step 和 Trajectory；Trajectory 可以检查工具调用的顺序、集合与完整执行路径。

我倾向于组合三种 Grader：

Code-based Grader：测试、Schema、状态查询、静态规则，便宜、确定、可重复。
Model-based Grader：Rubric、Pairwise、复杂语义质量，覆盖开放式任务。
Human Grader：领域专家抽检和校准，防止自动评分体系自我欺骗。

Anthropic 的 Agent Eval 实践也采用这三类，并指出模型评分需要由人工校准。我的优先级是：能用权威状态和代码判定的，绝不先交给 LLM Judge；只有难以结构化的质量维度，才使用模型评分。

评测数据从哪里来

最初不需要几千条 Benchmark。可以先建立 20–30 个真实任务，覆盖：

高频正常路径；
历史失败案例；
权限与审批边界；
Tool 超时和部分失败；
进程重启后的恢复；
重复消息与幂等；
模糊需求和人工接管；
成本或延迟极端值。

每个 Case 固定 Workspace Revision、输入、可用 Tool、成功条件和预算，再对 Provider、Model、Prompt、Tool Version 做矩阵比较。非确定性的 Agent 至少重复运行 3–5 次，不要拿一次成功当能力结论。

Eval Case
  ├─ Fixture: Workspace + Revision + External State
  ├─ Input: User Intent
  ├─ Policy: Allowed Tools + Approval Rules
  ├─ Expected Outcome: Acceptance Contract
  ├─ Process Constraints: Forbidden / Required Behaviors
  └─ Budget: Time + Token + Cost

Run、Trace、Evidence 和 Eval Result 必须共用同一个 runId。否则评测只剩一张分数表，无法回到具体轨迹解释为什么变好或变差。

最小可落地架构

我不建议一开始自研完整平台。先做一个薄 Harness，把不可替代的控制权握在自己手里：

User / Trigger
      ↓
Harness API
      ├─ Run Store / Event Log
      ├─ Policy & Approval
      ├─ Workspace & Revision
      ├─ Tool Gateway
      ├─ Checkpoint Store
      ├─ Artifact & Evidence
      └─ Eval Runner
              ↓
      Runtime Adapter
        ├─ OpenAI Agents SDK
        ├─ LangGraph
        └─ Other Agent / Coding Runtime
              ↓
      Model + Tools + Execution Environment

最小技术选型可以非常朴素：

能力	第一阶段建议
Run / Event / Checkpoint	PostgreSQL；本地单机可先 SQLite
Artifact	Object Storage 或受版本控制的 Workspace
Trace	OpenTelemetry，或先接 Provider 自带 Tracing 再导出
Tool Contract	JSON Schema + 统一 Gateway + Idempotency Key
Approval	数据库状态机 + 通知，不要让请求连接一直挂着
Eval	测试框架 + 自建 Case Schema；需要可视化再接评测平台
Durable Workflow	长周期、跨服务场景再引入 Temporal
Graph UI	只有用户确实要编辑流程时再引入 React Flow

现成框架怎么选

OpenAI Agents SDK 适合快速建立 Agent Loop，并直接获得 Tool、Handoff、Guardrail、Tracing 和 Human-in-the-loop。它的序列化 RunState 可以承担一部分恢复能力，但业务 Run、Tool 幂等、权威状态验证和跨 Provider 协议仍应由自己的 Harness 管理。

LangGraph 适合状态和分支需要显式建模的 Agent。Graph State、Checkpoint、Interrupt、Time Travel 和持久化是它的强项。代价是图与状态 Schema 会进入核心代码，不要为了“看起来工程化”把开放式 Agent 强行拆成几十个节点。

Temporal 适合长周期、高价值、跨服务、必须可靠恢复的业务执行。它解决 Durable Execution，不负责 Prompt、Tool Selection 和 Agent Quality，通常与 Agent SDK 组合，而不是二选一。

LangSmith、OpenAI Tracing / Evals 等平台可以承担观测和评测的一部分，但不要让平台生成的 Trace ID 成为业务主键。保留自己的 Run Contract，才能迁移、对比和审计。

所以我的默认组合不是“选一个大而全框架”，而是：

自有 Thin Harness
+ 一个 Agent Runtime / SDK
+ 持久化数据库
+ 统一 Tool Gateway
+ OpenTelemetry / Provider Trace
+ 任务级 Eval Suite

分五个阶段落地

Phase 1：先让每次运行可定位

建立 runId、Run 状态机、统一 Event Schema 和基本 Trace。所有 Model Call、Tool Call、Artifact、Approval 都关联同一个 Run。

验收标准：任意一次失败都能回答“谁在什么时候，用什么版本，调用了什么，在哪一步失败”。

Phase 2：控制所有副作用

把外部动作收口到 Tool Gateway，加入 Schema、Permission、Approval、Timeout、Idempotency 和调用前后状态。

验收标准：重复投递同一 Tool Call 不会造成重复业务结果；高风险操作不能绕过审批。

Phase 3：做到进程级恢复

持久化 Run State 和 Checkpoint，绑定 Workspace Revision、Agent Definition Version 与 Runtime Version，补 Resume、Cancel 和过期策略。

验收标准：在关键 Step 后强制杀掉进程，重启后可以继续，且不重复已完成的副作用。

Phase 4：建立 Evidence-based Acceptance

为核心 Claim 建立 Verifier，从权威系统重新读取结果，生成最小 Evidence Bundle 与 Acceptance Result。

验收标准：Agent 自述与真实状态不一致时，Run 不能被标记为业务完成。

Phase 5：用 Eval 驱动演进

沉淀真实 Case，记录 Outcome、Process、Cost、Robustness，比较不同 Model、Prompt、Tool 和 Runtime，逐步加入线上采样与回归门禁。

验收标准：每次关键变更都能回答“成功率、成本、延迟和失败类型发生了什么变化”。

这五个阶段不需要 Graph Editor。等到系统已经拥有可靠的执行语义，再把适合人工配置的确定性部分可视化，React Flow 才会成为产品能力，而不是工程完成度的幻觉。

常见反模式

把 Provider Session ID 当自己的 Run ID

一旦切换 Provider 或同一业务 Run 包含多段模型执行，关联关系就会断裂。Provider ID 应只是外部引用。

把聊天历史当 Checkpoint

聊天历史没有完整表达审批状态、已执行副作用、Workspace Revision 和待处理 Tool Call，恢复时容易重复执行或错用环境。

把 Trace 当 Evidence

Trace 证明“系统记录了这个动作”，不证明“业务结果真的生效”。Evidence 必须能回到 Artifact 或权威状态。

只评最终回答

最终答案正确，不代表过程中没有越权、泄露、无效循环或不可接受的成本。Agent Eval 必须覆盖 Trajectory 和外部结果。

一开始追求通用编排平台

没有真实 Case 时，通用节点、DSL 和图编辑器只会提前固化错误抽象。先用 20–30 个真实任务逼出稳定契约，再抽象框架。

要不要用 / 我的判断框架

值得建设

Agent 会修改代码、发布、退款、发消息或操作业务系统；
单次任务长、成本高，中断后不能从头开始；
需要人工审批、权限隔离、审计或合规；
需要比较多个 Model、Provider 或 Agent Runtime；
团队已经遇到“Demo 能跑，线上偶发失败却解释不清”的问题。

可以再等

只是单轮问答或内部 POC；
没有外部副作用，失败后整次重试成本很低；
需求和 Tool 还在快速变化，连成功标准都没有定义；
当前瓶颈是基础能力，而不是稳定性、治理或评测。

重点关注

如果现在只能做一件事，我不会先引入 React Flow，也不会先造一个通用 Graph Engine。我会先建立统一 runId 和 Event Contract，让 Tool Call、Checkpoint、Artifact、Evidence 与 Eval Result 能围绕同一次运行串起来。

这条链一旦成立，后面接 OpenAI Agents SDK、LangGraph、Temporal 或其他 Runtime 都只是适配问题；这条链没有成立，框架越多，只会制造更多无法解释的状态。

我对 Agent Runtime / Harness 的最终判断是：它不是一个新潮名词，也不该被包装成“更高级的 Workflow”。它真正有价值的地方，是把概率性的 Agent 包进确定性的工程边界里——让每次执行有身份，让每个副作用受控制，让每次中断能继续，让每个完成声明有证据，让每次升级都能被测量。

这才是 Agent 工程开始进入 AI Infra 的分界线。

参考资料

Agent 系统的一级领域对象：从 Task、Run 到 Evidence

2026-08-02T09:20:00.000Z

一套跨框架的 Agent 领域模型：Agent 承担责任，Task 描述工作，Run 记录执行，Artifact 承载结果，Evidence 和 Evaluation 决定结果是否可信。

最近我反复遇到 Evidence。它出现在知识检索、Agent 执行、评测、审计和业务验收中，与 Agent、Task、Run、Memory、Policy 并列。问题随之而来：这些词到底是不是同一层概念？一个 Agent 系统真正需要维护哪些一级领域对象？

如果直接从某个 SDK 抄类名，答案会随着框架切换而变化。OpenAI Agents SDK 强调 Agent、Runner、Tools、Handoffs、Guardrails 和 Sessions；A2A 暴露 Agent Card、Task、Message、Artifact；MCP 提供 Tools、Resources、Prompts；LangGraph 围绕 State、Thread、Checkpoint 和 Memory 组织运行。它们都合理，但它们描述的是不同边界。

我更关心跨框架后仍然成立的业务语义。因为只有这些对象，才值得进入 Agent Platform 的数据库、API、权限、状态机和审计模型。

一句话总结

我会把 Agent 系统的核心领域模型收敛为十二个对象：

Actor      Agent / Identity
Work       Goal / Task / Run
Execution  Capability / Context
Control    Policy
Outcome    Artifact / Claim
Trust      Evidence / Evaluation

它们组成一条完整链路：

Identity 授权 Agent
Agent 为 Goal 承接 Task
Task 产生一次或多次 Run
Run 在 Policy 约束下使用 Capability 和 Context
Run 产出 Artifact，并提出 Claim
Evidence 支撑 Claim
Evaluation 根据验收标准作出判断

Tool、Prompt、Model、Runtime、Message 和 Trace 同样重要，但默认属于实现、协议或可观测性对象，不必全部提升为一级领域对象。

“一级领域对象”不是现成标准

“一级领域对象”并不是 Agent 行业已经发布的正式术语。这里采用的是领域建模视角：当一个对象需要被系统长期、独立地管理，就把它当作 First-class Domain Object，而不只是某张配置表里的字段。

我用五个问题判断：

它是否拥有稳定 ID，能被 API、权限和审计记录独立引用？
它是否有独立生命周期，而不是伴随一次函数调用即消失？
它是否承载业务规则或状态转换？
它是否会被多个模块共同使用，而不属于某个框架的内部实现？
更换 Model、Runtime 或 Agent Framework 后，它是否仍然存在？

例如 Run 会被暂停、恢复、取消、重试和验收，显然应当独立建模。某个模型的 temperature 不具备这些特征，它只是配置值。

这也意味着“一级”不是永恒不变的。Workspace 对普通客服 Agent 可能只是 Context 的一个字段，对 Coding Agent 却可能有独立权限、Revision、锁和生命周期，此时就应升级为一级对象。

先从跨框架的共同部分看

W3C PROV 给出了最小骨架

Agent 领域不是从零开始发明。W3C 的 PROV-O 用三个起点描述可追溯系统：

Agent：对某项活动或实体承担责任的主体；
Activity：在一段时间内发生、使用或生成实体的活动；
Entity：具有相对固定特征的物理、数字或概念对象。

映射到 Agent 系统里，最朴素的关系就是：

1
2
3

Agent 负责 Run
Run 使用 Context / Resource
Run 生成 Artifact / Evidence

这个骨架解释了为什么 Evidence 不属于“知识库技术”或者“日志技术”本身。Evidence 是带有来源、生成活动和责任主体的 Entity，价值来自它与 Claim、Run、Agent 的关系。

A2A 把 Task 和 Artifact 提升为协议对象

A2A 1.0 规范把 Task 定义为有唯一 ID、状态和生命周期的基本工作单元；Agent 执行后产生的文档、图片或结构化数据进入 Artifact。Message 负责通信，Context 负责关联一组 Task 和 Message。

这个区分非常关键：

1
2
3

Message：一次沟通
Task：需要跟踪的工作
Artifact：工作产生的交付物

聊天记录不能代替任务状态，最终回复也不能自动等于正式交付物。

MCP 描述能力接口，不负责完整业务模型

MCP 架构定义了三个核心 Server Primitive：

Tools：执行动作；
Resources：向模型提供上下文数据；
Prompts：提供可复用的交互模板。

它回答的是“Agent 如何接入能力与资源”，不负责定义 Goal、Task、Run、Evidence 或 Evaluation。A2A 规范也把两者定位为互补协议：MCP 面向工具和资源连接，A2A 面向 Agent 之间的任务协作。

所以 MCP Server 不应成为业务领域模型的中心。它是 Capability 和 Resource 的一种接入方式。

Agent Framework 暴露的是 Runtime Primitive

OpenAI Agents SDK把 Agent 定义为带有 Instructions、Tools、Handoffs 和 Guardrails 的 LLM，并由 Runner 执行 Agent Loop。它还提供 Session、Tracing、Human-in-the-loop 和可恢复的 Run State。

Anthropic 的 Agent 架构总结则把 Agent 与 Workflow 分开：Workflow 走预定义代码路径，Agent 动态决定过程和工具使用。其基础构件是带 Retrieval、Tools、Memory 的 Augmented LLM；执行过程中，Agent 需要持续从工具结果、代码执行等环境反馈中取得 Ground Truth。

这些材料共同证明 Agent、Run、Capability、Context、Memory、Policy 和 Evaluation 的必要性，但 SDK 里的每个类并不等于领域对象。Runner 可以被替换，Task 和 Evidence 不能因为换了 Runtime 就消失。

把几套体系放在同一张表里，边界会更清楚：

来源	它显式建模的对象	对领域模型的启发
W3C PROV	Agent、Activity、Entity、Attribution、Derivation	责任、活动、产物和来源关系是追溯骨架
OpenAI Agents SDK	Agent、Tools、Handoffs、Guardrails、Session、Run State、Trace	Agent Loop 之外还需要运行状态、控制与上下文
Anthropic	Agent、Workflow、Tools、Retrieval、Memory、Ground Truth、Evaluator	自主决策必须接受环境反馈与独立评价
A2A	Agent Card、Task、Message、Context、Artifact	通信、工作、上下文和交付物需要分开
MCP	Tools、Resources、Prompts	能力、资源和交互模板属于接入协议边界
LangGraph	State、Thread、Checkpoint、Memory	长运行需要状态快照、恢复与跨会话记忆

这张表不是投票结果。某个概念在六套体系里都出现，不代表它一定是一级对象；反过来，Claim 没有被多数 Agent SDK 显式建模，也不代表生产系统可以省略它。最终仍要回到 ID、生命周期、业务规则和跨模块关系。

十二个核心领域对象

1. Agent：承担工作责任的持续主体

Agent 不应只是一段 System Prompt，也不只是“模型 + 工具列表”。它代表一个可被分配工作、拥有能力边界和版本、能够产生运行记录与结果责任的持续主体。

一个可管理的 Agent 至少要回答：

当前有效版本是什么；
可以承接哪些工作；
以谁的身份行动；
允许使用哪些能力；
失败、暂停或升级时由谁负责。

模型只是 Agent 的实现组件。把模型名直接当 Agent ID，会让版本、权限、责任和历史运行全部粘在供应商配置上。

2. Identity：谁在行动，代表谁行动

Identity 解决认证与责任归属。Agent 可以有自己的服务身份，也可能代表某个用户、团队或组织发起操作。

需要区分：

1
2
3

Agent Identity：哪个 Agent 在执行
Principal：它代表谁行动
Credential：本次连接使用什么凭证

Credential 应短期、可轮换，Identity 和 Principal 则需要进入审计关系。否则系统只能知道“某个 Token 调用了接口”，无法说明谁授权了哪个 Agent 做什么。

3. Goal：希望世界达到什么状态

Goal 是期望结果，不是执行步骤。例如“让新版页面可被用户访问”是 Goal，“修改配置并运行发布命令”只是候选计划。

Goal 值得独立存在，是因为同一个 Goal 可能被拆成多个 Task，也可能在执行过程中改变计划，但成功条件不应随 Agent 的临时推理漂移。

一个可用 Goal 至少包含目标状态、作用范围、成功指标、截止条件和责任人。

4. Task：可分配、可跟踪的工作单元

Task 把 Goal 变成可以交给 Agent 的工作。A2A 把它作为协议核心，是因为长任务必须有稳定 ID、状态、历史和结果。

Task 与 Goal 的区别是：

1 2	Goal：为什么做、做到什么程度 Task：谁承接哪一块工作、当前处于什么状态

多 Agent 系统里的 Delegation 或 Handoff，本质上是在 Agent 与 Task 之间改变责任关系，而不只是转发一条 Message。

5. Run：Task 的一次执行尝试

Run 是最容易被漏掉、也最需要独立建模的对象。同一个 Task 可能第一次执行超时，第二次恢复成功，第三次为了验证重新运行。它们属于一个 Task，却不是同一次 Run。

Run 应记录：

使用的 Agent Version、Context Snapshot 和 Policy Version；
开始、暂停、恢复、取消和结束状态；
Tool Call、Handoff、异常和人工决定；
Usage、成本、产物与证据引用。

OpenAI Agents SDK 的可序列化 RunState 和 LangGraph 的 Checkpoint 都在解决“运行如何暂停并恢复”，但领域层不应绑定它们的存储格式。

6. Capability：Agent 能完成哪类动作

Capability 描述业务能力，例如“查询订单”“修改代码”“发布静态站点”。Tool、Skill、Model、Runtime 和 MCP Server 是能力的不同实现或依赖。

Capability：能做什么
Tool：通过什么接口做
Skill：按什么方法做
Model：由什么推理能力参与
Runtime：在哪个执行引擎里做

把 Capability 与实现分开，才能替换工具和 Runtime，同时保留任务路由、权限、评测与历史成功率。

7. Context：本次运行获准看到的工作集

Context 不是“把所有资料塞进上下文窗口”，而是某次 Run 使用的信息边界。它可以引用 Conversation、Workspace、Resource、知识片段、环境状态和用户输入。

Context 最好以 Snapshot 或明确 Revision 固定下来。否则运行结束后无法回答：Agent 当时看到了哪个版本的文件、哪段知识、哪个系统状态？

LangGraph 的 Memory 文档把短期记忆放在线程状态中，并通过 Checkpoint 持久化；跨线程的长期记忆则单独存储。这个划分说明 Memory 不是 Context 的同义词：Context 是本次运行实际使用的集合，Memory 是可能被召回到未来 Context 的持久状态。

8. Policy：什么情况下允许怎么做

Policy 是对 Agent、Task、Capability、Context 和 Run 的约束规则，例如：

哪些数据可以发送给哪个 Model；
哪些 Tool 只能在指定 Workspace 使用；
哪些动作必须人工审批；
超过什么预算停止运行；
哪些 Evidence 缺失时不得宣布完成。

Guardrail 是 Policy 的一种执行机制，不是 Policy 本身。Prompt 里的“请不要执行危险操作”也不能替代可版本化、可判定、可审计的 Policy。

9. Artifact：Agent 实际交付了什么

Artifact 是 Run 产生的持久结果，例如代码 Diff、文档、报表、图片、构建包、结构化数据或发布清单。A2A 明确把 Artifact 与 Message 分开，这个设计值得保留。

一段“已经修改完成”的聊天回复不是 Artifact；被保存、定位、版本化并交给下游使用的文件或数据才是。

10. Claim：系统正在声称什么事实

Evidence 经常被直接建成附件列表，却没有说明它证明什么。缺少 Claim，Evidence 就只是材料堆积。

Claim 是一个可验证断言，例如：

“测试通过”
“版本已经推送到远端”
“生产接口返回预期结果”
“这段回答来自当前有效的制度文档”

Claim 需要作用对象、范围、Revision、时间和声明主体。同一句“发布成功”，在测试环境和生产环境是两个不同 Claim。

11. Evidence：支撑或反驳 Claim 的可验证事实

Evidence 属于 Trust & Verification 领域。它把 Claim 与 Source、Run、Artifact、Observation、Verifier 和时间连接起来。

一条合格 Evidence 至少需要：

{
  "claimId": "claim_production_ready",
  "sourceRef": "check://production/health",
  "producedByRunId": "run_20260802_01",
  "observedAt": "2026-08-02T17:00:00+08:00",
  "revision": "release_42",
  "integrity": "sha256:...",
  "verifier": "health-check-v3"
}

Trace、日志、截图和测试输出只能算 Evidence Candidate。只有当它被绑定到具体 Claim，并说明来源、范围和验证方式后，才成为可以用于验收的 Evidence。

12. Evaluation：依据标准作出的判断

Evaluation 消费 Artifact、Claim 和 Evidence，根据 Criteria 给出 Verdict、Score、Explanation 或 Risk。

1
2
3

Evidence：生产接口在 17:00 返回 200
Criteria：连续三次健康检查成功，响应体版本为 release_42
Evaluation：PASS / FAIL / INCONCLUSIVE

Anthropic 的 Evaluator-optimizer 模式和 OpenAI Agents SDK 的 Guardrail / Eval 能力都说明“生成”和“判断”需要分离。Evidence 是事实材料，Evaluation 是基于规则或评审者作出的判断，两者不能混成一个分数字段。

哪些对象需要按场景升级为一级

除了十二个核心对象，还有一组条件性对象。是否独立建模，取决于业务复杂度。

候选对象	什么时候升级为一级对象	否则放在哪里
Memory	跨 Run 保存、可纠错、可删除、需要来源与保留策略	Context 的引用或 Session State
Approval	运行会跨小时或跨天暂停，需要记录批准人、范围与失效条件	Run Event / Policy Decision
Workspace	有独立权限、Revision、文件锁、隔离和生命周期	Context Scope
Handoff / Delegation	多 Agent 间需要追踪责任转移、输入输出契约和超时	Task 的关系事件
Trigger / Schedule	周期任务、Webhook、事件订阅需要独立启停和重放	Task 创建来源
Budget / Usage	存在额度分配、成本归属、限额和结算	Run Metric
Version / Release	Agent 配置需要灰度、回滚、对比评测和生产追踪	Agent 的版本字段
Receipt	需要对外签发、不可变、可撤销或具备法律/业务效力	Claim、Evidence、Evaluation 的聚合视图

例如 OpenAI Agents SDK 的 Human-in-the-loop允许 Run 因 Tool Approval 暂停、序列化并在之后恢复。在短对话里，Approval 可以只是一次事件；在跨天的财务或发布流程里，它需要自己的 ID、审批人、Decision、Scope、Policy Version 和 Expiry，此时就应该成为一级对象。

哪些常见名词默认不该升为一级

Prompt

Prompt 是 Agent Version 或 Capability Implementation 的组成部分。只有当平台专门做 Prompt 资产管理、评测、发布和回滚时，它才需要独立生命周期。

Model 与 Runtime

它们是可替换执行依赖。模型路由平台会把 Model Deployment 当一级对象，通用 Agent 产品则应避免让业务 Task 直接绑定供应商模型。

Tool 与 Skill

Tool 是调用接口，Skill 是完成任务的方法。它们可以作为 Capability 的实现对象独立管理，但业务路由首先应该依赖 Capability，而不是某个函数名或 Skill 文件名。

Message

Message 是通信协议对象，不等于 Task、Context 或 Artifact。一串消息可以产生多个 Task，一个长 Task 也可以跨越多轮 Message。

Event、Log 与 Trace

它们记录运行轨迹，主要属于 Observability。OpenAI Agents SDK 的 Trace 会记录 Model Generation、Tool Call、Handoff 和 Guardrail 等 Span，这对排障很重要，但 Trace 不自动证明业务结果成立。

Workflow 与 Graph

Workflow 是编排定义，Graph 是一种结构表达。以 Workflow 为产品核心的平台可以把它作为一级对象；以开放式 Agent 为核心的系统，更适合把它作为 Capability 或 Execution Plan 的实现。

一套可落地的最小关系模型

如果从数据库和 API 开始，我会先建立下面几条稳定关系，而不是先画复杂的多 Agent 拓扑：

Agent --has--> AgentVersion
Identity --authorizes--> Agent
Goal --decomposes_into--> Task
Agent --assigned_to--> Task
Task --attempted_by--> Run
Run --uses--> Capability
Run --reads--> ContextSnapshot
Policy --governs--> Run
Run --produces--> Artifact
Run --asserts--> Claim
Evidence --supports_or_refutes--> Claim
Evaluation --judges--> Claim

对应的生命周期应明确区分：

Task:  created → assigned → active → completed / failed / canceled
Run:   queued → running → waiting_approval → paused → completed / failed / interrupted
Claim: proposed → supported / refuted / insufficient
Eval:  pending → pass / fail / inconclusive

这里最重要的不是状态名称，而是不要用一个 status = done 同时代表“Agent 停止运行”“文件已经生成”“测试通过”“代码已经发布”“业务已经验收”。这些是不同对象上的不同 Claim。

应该按什么顺序建设

第一阶段：先让工作可运行

最小闭环需要：

1	Agent + Task + Run + Capability + Context + Artifact

这一阶段解决“谁在什么上下文里，用什么能力，完成了哪项工作，产出了什么”。

第二阶段：让结果可信

进入真实业务前补齐：

1	Identity + Policy + Claim + Evidence + Evaluation

这一阶段解决权限、责任、结果边界与验真。系统只有 Trace，没有 Claim 和 Evidence Model，仍然无法可靠验收。

第三阶段：处理长期与协作

当任务跨 Session、跨 Agent、跨天运行时，再把以下对象提升出来：

1	Memory + Approval + Workspace + Handoff + Trigger + Budget + Version

它们不应该为了架构图完整而提前建设。升级信号应来自真实问题：上下文无法恢复、责任转移说不清、审批失效、成本无法归属、版本无法回滚。

我的判断框架

遇到一个新的 Agent 名词，我会按下面的顺序判断：

它描述的是业务世界，还是某个 SDK 的实现方式？
它是否拥有独立 ID、生命周期和业务规则？
多个 Task、Run 或 Agent 是否需要共同引用它？
更换 Model、Runtime、Protocol 后，它是否仍然成立？
不独立建模会不会导致权限、恢复、审计或验收说不清？

五个问题大多回答“是”，就把它提升为一级领域对象；否则先作为属性、事件、协议对象或实现对象存在。

这套模型给我的最大帮助，是把 Agent Platform 从“模型、Prompt、Tool 的配置集合”重新理解成责任系统：Agent 承担工作，Run 改变环境，Artifact 承载结果，Claim 表达结论，Evidence 与 Evaluation 决定我们能否相信它。

真正进入生产后，模型能力会持续变化，Runtime 也可以替换。长期稳定的资产，是这些领域对象及其关系。

参考索引

本文优先采用协议规范、标准本体和框架官方文档。下面列出的不是泛泛的“相关阅读”，而是实际参与本文领域对象归纳和边界判断的研究依据。检索日期：2026-08-02。

范畴	参考资料	本文采用的依据	使用边界
Provenance / Trust	W3C PROV-O：The PROV Ontology	Agent、Activity、Entity 组成的最小 Provenance 骨架，以及归属、生成、使用等关系	PROV-O 描述来源与过程，不直接给出 Agent 产品的完整业务模型
Agent Interoperability	A2A Protocol Specification 1.0	Agent Card、Task、Message、Artifact、Context 等跨 Agent 协作对象的定义与生命周期	A2A 是互操作协议；本文没有把所有协议对象都提升为一级领域对象
Capability Interface	Model Context Protocol：Architecture Overview	Tools、Resources、Prompts 的职责划分，用于区分 Capability、Context 与实现接口	MCP 解决 Host、Client、Server 之间的上下文与能力交换，不等于完整 Agent 领域模型
Agent Runtime	OpenAI Agents SDK Documentation	Agent、Runner、Tools、Handoffs、Guardrails、Sessions、Tracing 等 Runtime Primitive	SDK 类名会随框架变化，因此只用于提取稳定语义，不直接照搬为业务对象
Approval / Resume	OpenAI Agents SDK：Human-in-the-loop	Tool Approval、Run 暂停、序列化和恢复机制，用于判断 Approval 何时应拥有独立生命周期	短时审批仍可保留为 Run Event；跨时段、可失效审批才建议升级为一级对象
Agent Architecture	Anthropic：Building Effective AI Agents	Workflow 与 Agent 的区别、Tool Use、Evaluator-optimizer 等编排模式	这是一组工程模式，不是领域对象标准；本文主要用它校验 Workflow、Graph、Evaluation 的边界
State / Memory	LangGraph Documentation：Memory	Short-term Memory、Long-term Memory、Thread、Checkpoint 的作用域与持久化边界	Memory 是否成为一级对象，取决于是否跨 Run 管理并具备来源、纠错、删除和保留策略

综合方法与结论边界

行业目前没有一份统一规范宣布“Agent 系统必须包含十二个一级领域对象”。本文的十二对象模型，是把上述资料放进同一套判据后得到的领域建模结论：对象需要具备相对稳定的 ID、生命周期、业务规则和跨对象关系，并且在替换 Model、Runtime 或 Protocol 后仍然成立。

因此，文中的分类需要区分三种性质：

规范直接定义：例如 W3C PROV 的 Agent、Activity、Entity，A2A 的 Task 与 Artifact。
框架暴露的 Runtime Primitive：例如 Runner、Session、Handoff、Guardrail、Checkpoint。
本文综合推导的领域对象：例如把 Claim 与 Evidence 分离，把 Policy 提升为控制面对象，以及将十二个对象组织为 Actor、Work、Execution、Control、Outcome、Trust 六组。

这也意味着，十二个对象是一套用于架构决策的参考模型，不是对任何单一 SDK 或协议的重新命名。

用 Context7、Serena 和 Session 把 Codex 的 token 花在刀刃上

2026-07-25T08:20:00.000Z

最近给 Codex 配了一个组合：Context7、Serena，再配合合理拆 Session。

这套组合很容易被描述成“省 token 三件套”。但我觉得这个说法不够准确，甚至有一点误导：MCP 不是装得越多越省，Session 也不是拆得越细越省。真正起作用的，是把正确的信息送到正确的阶段，尽量不让无关的文件、文档、日志和历史决策进入当前上下文。

这篇文章用一次真实的前端功能开发流程，把三个工具串起来，也把 token 节省的边界讲清楚。

一句话总结

Context7 负责查对外部文档，Serena 负责缩小代码阅读范围，Session 负责切断已经失去价值的历史上下文。

它们共同优化的不是“工具数量”，而是 context selection：这一轮到底应该让 Codex 看什么。

先看一次真实工作流

假设现在要给一个 React + Midway 的企业工作台增加技能录制状态展示，同时补上接口错误处理。

我不会一上来就让 Codex“直接改好”。更稳的做法是把任务分成三个阶段。

Session 1：只探索，不改代码

第一轮只确定入口、调用链和最小修改范围：

先不要修改代码。

请定位：
1. 技能录制页面入口
2. 页面使用的 hooks 和 API
3. loading、empty、error 状态目前在哪里处理
4. 最小修改范围和相关调用方

用代码语义检索定位符号和引用关系。
如果涉及 React、Umi 或 Midway 的版本行为，再查当前版本的官方文档。

最后只输出：相关文件、调用链、推荐改法和风险。

这一轮的目标不是产出代码，而是建立一个足够小的工作集。

Serena 用来找页面、函数、类型和引用关系；Context7 只在需要确认外部框架行为时介入。两者都不应该被用来“把整个项目读一遍”。

Session 2：只实现已经确定的范围

探索完成后，我会把结论压缩成一份 handoff，再开始实现：

背景：
- 页面入口：client/src/pages/SkillRecord/index.tsx
- API：client/src/apis/skill.ts 的 getSkillDetail
- 现有问题：只处理成功态，没有 error/retry
- 目标：补充 loading、empty、error、retry
- 约束：复用现有 UI 组件，不改全局组件

请直接实现，完成后运行相关检查。

这里不需要把上一轮的所有探索日志重新粘进来。保留决策、文件、约束和验收标准就够了。

Session 3：只验证本次改动

实现完成后，如果出现大量构建或测试输出，可以把验证单独放到新的 Session：

请只验证本次改动：
1. 检查 TypeScript 类型
2. 检查 loading、empty、error、retry
3. 运行最小范围测试或构建
4. 如果失败，只分析本次改动相关错误
5. 不要重新扫描整个项目

这三轮不是固定模板。小改动可以一轮完成；当目标、证据和日志明显发生变化时，再切 Session。

Context7：把“查文档”变成定向查询

Context7 是文档检索 MCP。它解决的问题是：

这个 API 在当前版本到底怎么用？

它适合查：

问题	适合查的内容
React 行为	当前版本的 API、生命周期和边界条件
Umi 配置	当前版本的路由、插件和构建配置
Midway 接口	Controller、Service 和参数校验方式
第三方依赖	当前版本的参数、示例和 breaking change

它替代的是凭模型记忆猜 API，或者手动把一整篇 README 粘进聊天。

正确的问法是：

1 2	查当前 React 版本中 useEffect cleanup 的官方行为。只返回和这个错误相关的说明、限制和最小示例。

不太好的问法是：

1	把 React 文档都找出来。

第二种问法会让工具返回大量当前任务用不到的内容。Context7 本身也消耗 token，所以它的价值取决于查询是否足够窄。

Serena：从“读文件”切换到“读代码结构”

Serena 是代码语义检索和编辑工具。它更适合回答：

这个项目里，真正应该看哪些代码？

它可以帮助定位：

函数、类、接口和类型
符号引用
调用关系
实现位置和使用方
一个改动可能影响的局部范围

可以用下面这张表理解三个常用工具的分工：

工具	最擅长的问题	不应该承担的工作
`rg`	某个字符串、错误文案、配置项在哪里	理解复杂调用关系
Serena	某个符号怎么定义、被谁引用	查外部框架文档
Context7	某个依赖的当前版本怎么用	理解你的业务代码

Serena 的 token 收益，主要来自减少无关文件读取。它不是把代码“压缩”了，而是把阅读入口从目录和全文，缩小到符号和调用链。

当然，Serena 也不是 rg 的替代品。精确字符串搜索仍然是 rg 的强项；语义定位和结构理解才是 Serena 的优势。

Session：真正的上下文边界

一个 Session 里积累的不只是聊天内容，还包括：

之前的用户要求
Codex 的分析过程
工具调用结果
读过的文件
测试日志和构建日志
已经被推翻的旧结论

所以 Session 变长以后，常见的问题不是模型“突然变笨”，而是有效信息被噪音埋住了。

这通常表现为：

反复重新解释已经确定的背景。
继续参考已经过时的探索结论。
从旧日志里找错误，而不是看最新结果。
改动范围逐渐扩大。

新 Session 的价值，就是把上下文重置成一个更干净的工作面。代码和 Git 工作区不会因为换 Session 消失，但对话里的决策不会自动继承，所以需要一份短 handoff。

token 到底省在哪里

可以把每一轮输入粗略看成：

本轮输入
≈ 对话历史
  + AGENTS.md 和项目约束
  + 工具定义
  + MCP 返回结果
  + 读取的代码
  + 当前 prompt

这套组合主要从四个地方节省 token。

少读文件

Serena 把“扫描整个目录”缩小成“定位相关符号和引用方”。这是最直接的节省。

少重复背景

稳定的项目规则放进 AGENTS.md，就不需要每个任务都重复说明包管理器、构建命令、目录边界和验证要求。

但 AGENTS.md 也不能无限膨胀。它可能在每次相关任务里进入上下文，和当前项目无关的长篇背景会变成固定开销。

少复制历史

新 Session 不会携带上一轮的全部探索过程。用几行 handoff 传递结论，通常比复制几十屏命令输出更划算。

少返回日志

验证时不要让 Codex 每次都接收完整日志，可以明确要求：

1	只保留首个错误、错误文件和行号，以及与本次改动相关的 warning。

构建产物、依赖安装日志和重复堆栈，往往只增加上下文负担，不增加判断价值。

MCP 越多，token 越省吗？

不是。

每个 MCP 都可能增加：

工具定义
工具调用
工具返回结果
额外的错误和重试信息

所以应该按职责选择，而不是把所有工具都打开：

查外部文档       → Context7
理解代码结构     → Serena
查精确字符串     → rg
修改代码和跑测试 → Codex 原生工具

如果一个任务只需要改一个 CSS 属性，同时打开多个文档和代码 MCP，成本可能比收益更高。

Session 应该什么时候拆

合理拆 Session 是手动做的。判断标准不是“聊了多少轮”，而是当前上下文是否还服务同一个目标。

保持在同一个 Session

目标没有变化。
修改的是同一组文件。
还没有积累大量日志。
Codex 仍然能清楚复述当前约束和决策。

新开一个 Session

从调查切换到实现。
从实现切换到大量测试和排障。
开始处理另一个独立问题。
当前对话不断重复背景。
旧的探索过程已经不再有参考价值。

对一个中等规模功能，我通常会按下面的方式拆：

1
2
3

Session A：探索 / 定位 / 方案
Session B：实现
Session C：验证 / 修复

但不要为了“省 token”把一个小任务拆成很多 Session。每次新建 Session 都有重新传递背景和重新建立上下文的成本。

要不要用 / 我的判断框架

这套组合值得用，但应该把它当成上下文管理方案，而不是工具收藏。

值得上

中大型代码库，文件和调用关系比较复杂。
经常需要查 React、Umi、Midway 等版本敏感的文档。
任务经常经历探索、实现、验证多个阶段。
长 Session 里经常出现重复解释和日志污染。

可以先简单一点

小型仓库。
单文件修改。
不涉及外部依赖行为。
一次对话就能完成并验证的任务。

最应该记住的一句话

省 token 的核心不是“少让 Codex 工作”，而是让它少看无关的东西。

Context7 负责文档的准确性，Serena 负责代码阅读的精度，Session 负责上下文的边界。三者放进同一条工作流里，才会把 token 花在真正影响结果的地方。

参考资料

向量 RAG、GraphRAG、编译式 RAG：用一个客服实战讲清如何选

2026-07-24T06:00:00.000Z

先看问题形状，再决定知识该被表示成 Chunk、Graph，还是可持续维护的编译产物。

最近看到一张图，把知识检索分成向量 RAG、GraphRAG 和编译式 RAG 三条路线。图很直观，但也留下了最难回答的部分：一个真实系统到底怎么选？

如果只按概念解释，很容易得到三句没法指导架构的结论：小资料库用向量，复杂关系用 GraphRAG，可维护交付用编译式 RAG。落地时，资料库多大算小、什么关系值得建图、编译出来的知识丢了事实怎么办，仍然没有答案。

这篇文章不再横向罗列名词。我会用同一个“跨行业客服知识助手”贯穿三条路线，观察它们如何处理同一批文档、回答三类问题，再给出我会如何从 MVP 演进到生产架构。

一句话总结

我的选择顺序是：

默认先做 Hybrid RAG：Keyword / BM25 保精确词，Vector Search 处理自然语言表达，再加 Metadata Filter 与 Rerank。
当问题依赖稳定的实体关系和多跳路径时，增加 GraphRAG：它是一个面向关系问题的专用索引，不是默认底座。
当团队反复综合同一批稳定知识，并希望结果能够积累、审阅和复用时，增加编译层：把原始资料加工成结构化 Wiki、Procedure、Decision 和 Conflict 页面，但原始 Source 仍然是事实源。

生产系统往往不是三选一，而是：

Raw Sources
  ├─ Hybrid Index        → 找相关原文
  ├─ Relation Graph      → 走依赖与影响路径
  └─ Compiled Knowledge  → 复用已经整理过的知识
                ↓
        Evidence Gateway
                ↓
          LLM / Agent

三条路线共享 Scope、Revision、Permission、Citation 和 Trace。不要让 Agent 直接面对三个互不兼容的知识后端。

读实战前，先认清这些专业术语

RAG 相关术语容易混在一起，是因为它们来自不同层：有些描述数据，有些描述检索算法，有些描述知识结构，还有一些负责权限和证据治理。先把它们放回一条完整链路：

Raw Source
  → Parse / Chunk
  → Index
  → Query
  → Retrieve / Rank
  → Evidence Context
  → LLM Generate 或 Agent Action

这条链路里，Source 是事实，Index 是为了查询而生成的派生数据，Evidence 是本次回答实际采用的依据。三者不能混为一层。

先看一个词位于哪一层，再讨论它解决什么问题。Graph、Vector 和 Compiled Wiki 都只是中间的知识表示，最终仍要交付可追溯的 Evidence。

RAG、Context 与 Agent

术语	通俗解释	在客服实战中的位置
RAG	Retrieval-Augmented Generation，先检索外部资料，再让 LLM 基于资料生成答案	回答退款政策前，先取回有效政策片段
Retrieval	根据 Query 从外部知识中找候选内容	找到退款时效、订单状态和活动例外
Generation	LLM 根据问题与 Evidence 组织自然语言答案	把政策改写成客服能直接使用的回复
Context Window	模型单次推理能接收的 Token 范围	决定一次能放入多少问题、对话和证据
Context Budget	系统主动分配给证据的上下文额度	在有限 Token 中优先放最关键的政策和例外
LLM	Large Language Model，负责理解与生成，不自动等于事实源	解释证据、生成回复，但不能凭空创造政策
Agent	能调用 Tool、读取结果并继续决策的 LLM 运行循环	查询知识后，再读取订单状态或创建升级建议
Copilot	嵌在现有工作台中辅助人的 Agent 形态	在当前工单里推荐字段、证据和下一步动作
Tool	Agent 可调用的受控接口	只读查询订单状态，或在审批后执行某项业务动作

RAG 只规定“检索后再生成”这条工作流，并没有规定一定使用向量数据库。BM25、Vector Search、Graph Search，甚至直接读取编译好的 Wiki，都可以成为 Retrieval 的实现。

从文档到索引

术语	通俗解释	容易踩的坑
Raw Source	未被检索系统改写的原始事实源	把自动摘要当成原始政策，导致错误无法追溯
Parse	从 Markdown、PDF、HTML、表格等格式中提取正文与结构	表格行列、标题层级和脚注在解析时丢失
Chunk	为检索切出的内容单元，不一定等于固定字数	切得太小会失去条件，太大会混入无关内容
Metadata	附在内容上的结构化信息，如类型、时间、权限和版本	只算相似度，不过滤过期或无权限政策
Index	为搜索构建的派生结构，如倒排索引、向量索引或图索引	把 Index 当事实源；正确做法是允许删除后重建
Ingestion	从 Source 到 Parse、Chunk、Metadata 和 Index 的整条构建流水线	只做首次导入，没有增量更新和失败重试

以退款政策为例，一个 Chunk 不应只剩“预计 1–3 个工作日到账”。它还要带上“原路退款”“演示会员等级”“支付渠道结果为准”等条件，并保留 Source Version。否则检索命中了数字，回答仍可能是错的。

检索与排序

术语	通俗解释	它擅长什么
Query	用户问题或系统改写后的搜索表达式	表达这次到底要找什么
Query Rewrite	把口语问题改写成更适合搜索的一组表达式	补充别名、标准术语或拆出多个子问题
Keyword Search	按出现的词查找内容	状态码、产品编码、政策名称等精确词
BM25	根据词频、词的稀有程度和文档长度计算关键词相关性	把包含关键术语的文档排到前面
Embedding	把文字映射成一组浮点数，用距离近似语义相似度	连接“退款多久到”和“退款到账时效”等不同说法
Vector Search	比较 Query Vector 与文档 Vector，找语义接近的内容	自然语言问法、同义表达和模糊描述
Vector Database	存储向量并执行近邻搜索的数据库或索引能力	解决向量的存取与查询，不负责答案正确性
Metadata Filter	在召回前后按租户、时间、权限、版本等条件过滤	阻止测试规则、旧政策或越权内容进入上下文
Hybrid Search	同时使用 Keyword / BM25 与 Vector Search	兼顾精确术语和自然语言语义
Rank Fusion	把多个检索器的排名合并成一个候选列表	合并 BM25 与 Vector 的结果，而不是简单拼接
Reranker	用更精细的模型对少量候选重新判断相关性	把“语义相近”进一步收窄为“能回答当前问题”
Top K	最终保留排名最靠前的 K 条结果	控制 Recall、噪声和 Context Budget 的平衡

Embedding 不会“理解并保存答案”。它只提供一种相似度信号。Reranker 也不能找回第一轮完全没召回的资料。因此检索评测要分开看 Recall 和排序质量。

图、编译与知识表示

术语	通俗解释	在本文中的例子
Entity / Node	可以独立识别的业务对象	订单、会员、权益券、政策
Relationship / Edge	两个 Entity 之间有类型和方向的关系	订单使用权益券、权益券受活动政策约束
Knowledge Graph	由 Entity、Relationship 及其属性组成的知识网络	表达订单、商品、会员、权益与政策的连接
Multi-hop	为回答问题连续经过多条关系	取消订单 → 活动权益券 → 活动政策 → 退回条件
GraphRAG	用图结构定位关系，再结合原文 Evidence 生成答案	解释某类权益为什么没有随订单取消而退回
Community	图中连接紧密的一组实体	围绕退款、支付或会员权益形成的对象集合
Community Report	对某个 Community 预先生成的主题摘要	用于回答“这批客服资料有哪些主要问题”
Knowledge Compilation	在构建阶段把 Raw Sources 整理成稳定的知识产物	把多份政策编成可审阅的支付异常处理 Procedure
Intermediate Representation	Source 与最终消费之间的中间表示，简称 IR	Topic Page、Entity Page、Procedure、Conflict Page
Build Artifact	一次编译输出的、可版本化和可重建的产物	Wiki、Knowledge Pack、索引和 Citation Map
LLM Wiki	由 LLM 增量维护、相互链接的结构化 Wiki	让重复查询优先复用已有页面，再回原文核验

GraphRAG 和编译式 RAG 都会在 Query 发生前做更多加工。区别是 GraphRAG 主要预构建关系，编译式 RAG 还会预先合并事实、流程、冲突和解释结构。

Evidence、Citation 与治理

术语	通俗解释	为什么需要它
Evidence	本次回答实际使用、能够支撑某个 Claim 的内容	判断答案是不是基于资料，而不是模型猜测
Claim	回答里可以被验证真假的具体陈述	“退款预计 1–3 个工作日到账”就是一个 Claim
Citation	从 Claim / Evidence 回到 Source 的可定位引用	让客服和审核人检查原文、章节与版本
Grounding	回答中的 Claim 是否被给定 Evidence 支撑	区分“答得像真的”和“确实有依据”
Scope	一次查询被允许使用的业务、租户或知识范围	防止不同业务空间的规则互相污染
Revision	本次查询固定使用的知识版本	避免新旧政策混在同一个答案里
Permission	当前主体是否有权读取或执行	有权看通用政策，不代表有权看真实订单
Approval	高风险动作执行前的明确批准	退款、补偿和改订单不能由知识命中自动触发
Trace	记录 Query、路由、候选、Evidence 和最终输出的链路	出错后能定位是召回、排序、编译还是生成问题
Knowledge Gateway	统一接收知识查询并治理多个后端的入口	屏蔽 Hybrid、Graph 和 Compiled Wiki 的接口差异

Evidence 不等于“搜索结果”，Citation 也不只是文章末尾列几个链接。理想状态是回答中的关键 Claim 能逐条对应具体 Evidence，Evidence 再指向带 Revision 的 Source Span。

先把“编译式 RAG”这个词说准确

Vector RAG 和 GraphRAG 已经有相对明确的工程含义，“编译式 RAG”却还不是一个边界稳定的标准术语。不同人可能用它指：

提前生成摘要或 Contextual Chunk；
把整个知识库放进长上下文并缓存 KV；
把原始资料编译成相互链接的 Markdown Wiki；
从资料中抽取可执行的 Agent Skill；
把多种检索计划编译成一个查询。

本文采用其中最适合知识工程的一种定义：

编译式 RAG，是把不可直接高效消费的 Raw Sources，在构建阶段加工成面向后续任务的、可检查、可版本化、可增量更新的知识中间表示；查询时优先读取这些编译产物，必要时回到原文核验。

这个定义主要对应 Andrej Karpathy 的 LLM Wiki pattern：原始资料保持不可变，LLM 增量维护一个互相链接的 Wiki，再用 Schema / Agent Instruction 约束写入和查询流程。

“编译”这个比喻有四个关键点：

编译器概念	知识系统里的对应物
Source Code	产品说明、服务政策、FAQ、流程规范和已审核案例等原始事实源
Intermediate Representation	Topic Page、Entity Page、Procedure、Decision、Conflict、Citation Map
Compiler	LLM + 确定性解析器 + Schema + 校验器
Build Artifact	可被人阅读、被 Agent 搜索和遍历的 Wiki / Knowledge Pack

它不是“预先做了 Embedding”的新名字。Embedding 只是建立向量索引；编译式 RAG 会合并跨文档事实、建立链接、显式记录冲突，甚至把陈述性知识整理成可执行流程。

它也不能自动取代 RAG。编译过程会丢信息、写错关系、把条件句压成绝对规则。2026 年的 WiCER 研究专门讨论了这个 compilation gap：盲目压缩原始知识会出现严重信息损失，必须用诊断问题找出丢失事实，再迭代修正编译产物。

实战场景：给客服做一个知识助手

假设我们要做一个跨行业客服知识助手。它不绑定某家公司的产品、渠道或组织，示例中的会员等级、订单、规则、数值和 URI 均为虚构，仅用于说明架构。

团队准备了八份经过脱敏的资料：

ID	文档	主要内容
D1	`product-catalog.md`	虚构产品、服务权益与适用范围
D2	`refund-policy.md`	退款方式、预计时效与解释口径
D3	`membership-policy.md`	虚构会员等级与权益限制
D4	`order-status.md`	订单状态、支付状态与状态转换
D5	`resolved-cases.md`	已审核、已脱敏的历史客服案例
D6	`business-relations.yaml`	订单、商品、会员、权益券和规则的关系
D7	`service-sop.md`	核验、回复、升级与留痕步骤
D8	`campaign-exceptions.md`	虚构活动订单的例外和覆盖规则

为了避免把 Demo 做成“上传 PDF，然后问一句摘要”，我选三类形状完全不同的问题：

Q1 事实查找：
虚构的 Demo Plus 会员申请原路退款后，预计多久能到账？

Q2 关系与影响：
订单取消后，为什么某类活动权益券没有退回？要看哪些规则？

Q3 稳定执行：
用户已付款，但订单仍显示“待支付”，客服应该如何核验、回复和升级？

这三问分别要求系统找到一个事实、走一条关系链、复用一套跨文档流程。它们比“总结这些文档”更接近真实系统。

这套实战也刻意划出产品边界。客服场景不能被粗暴地收敛成一个聊天框：

能力	合适的入口	知识系统负责什么
通用知识问答与推荐	独立知识问答入口	查询产品说明、政策与标准口径
当前工单的信息提取	工单内 Copilot	读取已脱敏上下文，推荐字段和 Evidence
订单、会员与权益关联解释	工单内 Copilot + 受控业务 Tool	Graph 解释关系，Tool 提供当前状态
退款、补偿、改订单等动作	有权限和审批的操作流	知识只提供规则依据，不直接取得执行权

时效要求不高、跨行业共用的知识问答可以沉到通用平台。和当前会话、订单状态、退款流程强绑定的能力，应留在客服工作台 Copilot 中。RAG 提供依据，业务 Tool 读取实时状态，Permission / Approval 决定能否执行。

入口可以统一，知识路线不必统一。先识别问题需要一个片段、一条关系路径还是一套稳定流程，再路由到相应后端。

第一轮：用向量 RAG 解决

数据怎样进入系统

最小 Vector RAG 会做四件事：

Document
  → Parse
  → Chunk
  → Embedding
  → Vector Index

生产环境我不会只留向量通道。订单状态码、产品编码、政策编号和标准术语更适合 BM25，因此实际链路会是：

Query
  ├─ Keyword / BM25
  ├─ Vector Search
  └─ Metadata Filter
          ↓
      Rank Fusion
          ↓
       Reranker
          ↓
   Evidence Top K

所谓“向量 RAG”在生产里通常不是只查向量：BM25 守住精确词，Vector Search 处理同义表达，Metadata Filter 先排除过期和越权内容。

每个 Chunk 至少要保留：

{
  "chunkId": "refund-policy#original-channel",
  "content": "演示规则：Demo Plus 会员的原路退款预计 1–3 个工作日到账；实际时间以支付渠道处理结果为准。",
  "sourceUri": "demo://policies/refund",
  "sourceVersion": "sha256:...",
  "section": "原路退款时效",
  "scope": ["customer-service-demo"],
  "validFrom": "2026-06-01",
  "permission": "engineering"
}

没有这些 Metadata，检索器可能把旧版本、测试环境或无权限文档排在最前面。相似度高，不等于业务上可用。

三个问题会发生什么

Q1 很适合 Vector / Hybrid RAG。Query 中的“原路退款”“多久能到账”和 D2 的表述足够接近，Top K 很容易命中正确段落。若客服搜索某个标准状态码，BM25 通道还能兜住精确标识符。

Q2 开始吃力。向量检索可能召回 change-184.md 和 service-topology.md，但它不会天然执行这条路径：

取消订单
  → 使用了活动权益券
  → 权益券受活动规则约束
  → 活动规则规定部分场景不自动退回

Top K 里只要漏掉一段，影响分析就断了。把 k 调大能提高 Recall，却会带来更多无关上下文和更高推理成本。

Q3 的问题更明显。支付与订单状态定义在 D4，核验和升级动作在 D7，解释口径在 D2，活动例外又可能覆盖默认规则。单轮 RAG 每次都要重新找到多份资料并现场拼装流程。

向量 RAG 的真实边界

Vector RAG 擅长的是“从大语料里找到语义相近的局部证据”。它没有承诺：

一次检索覆盖完整依赖链；
不同 Chunk 之间的方向关系正确；
每次都以相同顺序重建同一套流程；
自动识别新规则覆盖旧规则；
将本次回答沉淀为下一次可复用的知识。

所以它适合作为默认检索底座，却不等于完整知识架构。

第二轮：什么时候 GraphRAG 值得上

GraphRAG 在构建阶段把文本转成实体和关系：

(CancelledOrder)
  -[USED]-> (CampaignVoucher)

(CampaignVoucher)
  -[GOVERNED_BY]-> (CampaignPolicy)

(PlusMember)
  -[ELIGIBLE_FOR]-> (RefundBenefit)

查询 Q2 时，系统先定位“已取消订单”和“活动权益券”，再按允许的 Edge Type 遍历，最后把路径关联的原文片段一起交给模型。此时“为什么没有退回”不再靠模型从若干相似 Chunk 中猜，而是有一条显式路径。

GraphRAG 解决的是“沿什么关系找到答案”，不是“图里的结论天然可信”。每一跳仍要锚定带版本的 Source Span。

微软的 GraphRAG 官方索引流程会从原文抽取 Entity、Relationship 和 Claim，做 Community Detection、生成 Community Report，并保留向量表示。它的 Local Search会结合实体关系与原始 Text Unit，适合具体实体问题；Global Search 则基于 Community Report 做 Map-Reduce，更适合“整批资料有哪些主要主题”这类全局问题。

GraphRAG 不是“Vector RAG 加一个图数据库”

难点不在于把 Node 和 Edge 存进去，而在于：

实体消歧：“权益券”“优惠权益”和“活动凭证”是不是同一类对象？
关系方向：A 调用 B 与 B 依赖 A 不能写反。
时间有效性：v2 的关系不能污染 v3。
来源追踪：每条 Edge 必须能回到产生它的 Source Span。
增量更新：一条政策发布新版本后，哪些社区摘要和关系要重算？
权限裁剪：删掉无权访问的 Node 后，剩余路径是否还泄露信息？

如果团队不能维护这些约束，GraphRAG 会把“检索偶尔漏片段”变成“图谱稳定地提供错误关系”。

我会怎样限制第一版图谱

不从所有自然语言里自由抽取任意关系，而是先定义少量 Typed Edge：

type EdgeType =
  | 'BELONGS_TO'
  | 'PURCHASES'
  | 'USES'
  | 'GOVERNED_BY'
  | 'ELIGIBLE_FOR'
  | 'SUPERSEDES'
  | 'ESCALATES_TO';

结构化的商品、订单状态和政策引用用确定性解析器产生；只有已脱敏客服案例、FAQ 等非结构化资料才交给 LLM 抽取，并标记较低 Confidence，等待审核。

这样做牺牲了“自动构建万物图谱”的想象力，换来可验证的影响分析。

第三轮：编译式 RAG 改变了什么

Q3 是编译式 RAG 最有价值的地方。团队已经反复处理“支付成功但订单状态未同步”，系统没必要每次从多份原文重新拼出核验与升级流程。

构建阶段可以产出：

wiki/
  products/
    example-product.md
  policies/
    refund-policy.md
    membership-policy.md
  procedures/
    payment-order-mismatch.md
  decisions/
    policy-revision.md
  cases/
    reviewed-payment-case.md
  conflicts/
    campaign-exceptions.md
  index.md
  log.md

其中 procedures/payment-order-mismatch.md 不是一段随意摘要，而是带来源和适用条件的结构化产物：

---
type: procedure
status: reviewed
revision: 7
applies_to:
  scenario: payment_succeeded_order_pending
  excluded_cases:
    - offline_payment_demo
source_refs:
  - demo://orders/status#pending
  - demo://policies/refund#original-channel
  - demo://sop/payment-check#escalation
compiled_from:
  - sha256:...
  - sha256:...
---

正文再写清：

触发条件
1. 用户提供的脱敏支付凭证显示已付款；
2. 订单在演示用正常同步窗口后仍为“待支付”；
3. 当前订单不属于已声明的例外支付方式。

核验与回复
1. 通过只读工具核对订单与支付状态；
2. 不要求用户提供完整卡号、证件号等敏感信息；
3. 告知当前状态、预计处理路径和下一次反馈时间；
4. 状态持续不一致时升级到对应处理队列。

验证与留痕
1. 订单与支付状态最终一致；
2. 工单关联本次查询所用 Evidence；
3. 面向用户的回复不暴露内部系统和规则标识；
4. 敏感字段在日志与摘要中保持掩码。

Agent 查询时先读 index.md，找到 Procedure，再沿链接读取相关 System、Decision 和 Conflict 页面。对于关键阈值，它仍要回到 Source Span 核验。

编译式 RAG 的收益不是“少搜一次”

它把重复劳动从 Query Time 移到 Build Time：

跨文档合并提前完成；
常用概念拥有稳定页面；
冲突与覆盖关系被显式记录；
Procedure 可以进入 Review 和版本管理；
上一次探索产生的有效结构能够被下一次复用。

这更接近程序编译：开发者不会每次运行程序时都重新理解所有 Source Code，而是消费经过检查的 Artifact。

编译式 RAG 的核心不是提前写摘要，而是让知识产物进入版本、校验和重建闭环；查询时对关键 Claim 仍需回查原文。

编译产物绝不能成为未经审查的新事实源

编译器会出错，LLM Compiler 也会。至少要守住四条线：

Raw Sources 不可被编译器改写。
每个 Claim 都能追到 Source Span 与 Source Revision。
编译产物可以全部删除并重建。
高风险 Procedure 在进入 reviewed 前不能驱动自动执行。

如果一个 Wiki 页面引用另一个 Wiki 页面，最后却找不到原文，这会形成循环证据。页面之间可以互相导航，事实依据必须落回 Source。

把三条路线放回同一张运行图

三条路线都在“预处理”，区别在于构建出了什么中间表示，以及查询时还要做多少工作。

向量 RAG 的构建成本最低，查询时要重新召回和综合。GraphRAG 把实体、关系与社区摘要前移到构建阶段，换来更可控的多跳与全局查询。编译式 RAG 进一步把常用综合结果和流程前移，但也承担最大的知识维护与编译正确性责任。

生成的直觉图更容易看出这三个动作的差别：

向量路线在空间中找邻近片段；图路线沿关系走路径；编译路线把原始资料加工成可长期使用的知识产物。

桌面推演：三问分别应该命中什么

这不是一个声称“准确率提升 37%”的伪 Benchmark。数据量太小、问题由作者设计、没有盲测，百分比没有意义。这里做的是架构桌面推演：先写出每个问题必须命中的证据与关系，再看哪条路线最自然。

Query	正确答案所需材料	Vector / Hybrid	GraphRAG	编译式 RAG
Q1 退款预计多久	D2 的一个段落	最自然	可以，但过度设计	可以，仍应核验原文
Q2 权益券为什么没退	D4 + D6 + D8 的规则路径	容易漏一跳	最自然	若已有 Policy Pages 也能做
Q3 如何核验、回复和升级	D2 + D4 + D7 + D8	每次重新拼装	图能找关联，但流程顺序仍需组织	最自然，Procedure 可审阅复用

还要加入反向问题：

1	Q4：订单刚显示“待支付”一分钟，是否应该立即承诺退款？

正确行为不是从“状态不一致”直接跳到退款，而是先核对演示规则中的正常同步窗口和支付状态，并明确不能在证据不足时承诺处理结果。

再加入冲突问题：

1	Q5：活动订单取消后，权益券是否一定自动退回？

系统必须同时找到默认权益规则和 D8 的例外规则，按有效 Revision 判断谁覆盖谁。如果它只返回默认政策，即使语言很流畅也算失败。

评测不能只看最终回答

三条路线需要不同的中间指标。

Vector / Hybrid RAG

指标	要回答的问题
Recall@K	必要 Source Span 是否进入候选集
MRR / NDCG	最有用证据是否排在前面
Filter Accuracy	Scope、时间、权限是否过滤正确
Citation Precision	引用是否真的支持对应 Claim
No-evidence Refusal	没有证据时是否拒答

GraphRAG

指标	要回答的问题
Entity Resolution Accuracy	同名、别名、版本实体是否合并正确
Edge Precision / Recall	关系是否存在、方向是否正确
Path Coverage	关键影响路径是否完整
Temporal Validity	查询时是否使用了正确版本的关系
Source Traceability	Node / Edge 是否能回到原文

编译式 RAG

指标	要回答的问题
Fact Preservation	编译后是否丢掉关键条件与数字
Claim-Citation Alignment	页面中的每个 Claim 是否被引用支撑
Conflict Detection	新旧规则冲突是否被标出
Rebuild Determinism	相同 Source 与 Compiler Version 是否得到可解释的 Diff
Staleness	Source 变化后，受影响页面多久完成重编译
Procedure Success Rate	Agent 按编译流程执行是否真的完成任务

一个系统最终答对了，不代表索引正确。LLM 可能靠训练知识猜中答案。Eval 数据里要包含专门构造、无法靠常识猜中的值，加入旧版本干扰项和“应该拒答”的问题，才能测出 Grounding。

建议把用例写成可执行契约：

{
  "id": "support-payment-order-mismatch",
  "query": "用户已付款但订单仍显示待支付，客服应该如何处理？",
  "scope": {
    "domain": "customer-service-demo",
    "revision": "policy-demo-r7"
  },
  "expectedEvidence": [
    "order-status#pending",
    "refund-policy#original-channel",
    "service-sop#payment-check",
    "campaign-exceptions#payment-method"
  ],
  "mustMention": [
    "先核对订单与支付状态",
    "告知下一次反馈时间",
    "持续不一致时升级"
  ],
  "mustNotDo": [
    "索取完整支付卡号",
    "在证据不足时承诺退款"
  ]
}

选型时，我看这六个变量

1. 问题是找片段、走关系，还是复用综合结果

这是第一判断，优先级高于语料规模。

“这条规则写在哪里”是 Lookup。
“改了它会影响谁”是 Relation。
“以后每次都该怎么做”是 Reuse / Procedure。

问题形状判断错了，后面调 Embedding Model、Graph Database 或 Prompt 都只是优化错误架构。

2. 关系是否稳定

商品、会员、订单、权益与正式政策之间的关系相对稳定，值得建图。客服对话里临时提到的“可能相关”，通常不值得成为长期 Edge。

关系变化比查询还快时，GraphRAG 的增量维护成本会吞掉收益。

3. Query 是否重复

编译的收益依赖复用。同一批资料只问一次，直接 RAG 通常更便宜；团队每周都要重新综合同一套规则，提前编译才开始划算。

这里不能只算 Token。还要算人工复核、错误传播和旧知识清理成本。

4. Source 是否持续变化

变化快的订单状态、库存和工单进度，应该通过受权限控制的实时 Tool 查询。稳定的产品说明、正式政策、领域概念和高频 Procedure，更适合编译。

一个常见组合是：

1
2
3

快速变化层：实时 Tool 查询当前业务状态
稳定关系层：小范围 Typed Graph
长期知识层：Versioned Compiled Wiki

5. 错误代价有多高

个人研究笔记可以接受少量编译偏差；自动退款、赔付或修改订单不行。风险越高，越要加强：

Source Span 级 Citation；
人工 Review；
Revision Pinning；
Permission / Approval；
Dry Run 与 Evidence；
无证据拒绝执行。

6. 团队有没有维护中间表示的能力

Graph 和 Compiled Wiki 都不是“一次导入，永久准确”。它们需要 Owner、Schema、Lint、Eval、重建和迁移。

如果没人负责，最朴素的 Hybrid RAG 往往比一套陈旧的高级知识系统更可靠。

我会怎样设计生产架构

生产架构需要提供一个统一的 Knowledge Contract：

type KnowledgeQuery = {
  query: string;
  intent?: 'lookup' | 'relation' | 'procedure' | 'global';
  scope: {
    tenantId: string;
    workspaceId: string;
    revision: string;
    principalId: string;
  };
  budget: {
    maxTokens: number;
    maxLatencyMs: number;
  };
};

type Evidence = {
  claim?: string;
  content: string;
  sourceUri: string;
  sourceVersion: string;
  sourceSpan?: { start: number; end: number };
  retrievalPath: string[];
  confidence: number;
};

Gateway 再按 Intent 路由：

lookup
  → Hybrid Search

relation / impact
  → Entity Resolve
  → Graph Traverse
  → Raw Evidence Join

procedure / repeated synthesis
  → Compiled Index
  → Read Page
  → Follow Links
  → Critical Claim Source Check

global
  → Community Summary / Compiled Overview
  → 必要时分解 Subquery 回查原文

返回值统一为 Evidence，而不是让某个后端直接生成最终答案。这样权限、版本、引用、预算和 Trace 才不会散落在各条路线里。

分阶段落地：不要第一天同时建三套

Phase 0：先建评测集

从 30–50 个真实问题开始，标注必要 Evidence、允许版本、禁止答案和拒答条件。没有这一步，后续只能靠“看起来更聪明”做选型。

Phase 1：Hybrid RAG

完成 Parse、Chunk、BM25、Vector、Metadata Filter、Rerank、Citation。先把单事实和局部解释做好。

升级信号：

必要证据经常分散在三跳以上；
影响分析靠调大 Top K 仍不稳定；
大量问题反复综合同一批资料。

Phase 2：只为高价值关系建图

先选一个子域，例如订单—权益—政策关系。使用 Typed Edge，保留 Source Span，不追求覆盖所有名词。

验收条件：

影响路径比 Hybrid RAG 的 Recall 更稳定；
Edge Precision 达到业务可接受标准；
增量更新耗时和成本可控。

Phase 3：编译高频知识

从 10–20 个高频 Topic / Procedure 开始。每个编译产物必须有 Source Manifest、Compiler Version、Status 与 Eval。

不要一上来把全部文档自动改写成 Wiki。编译范围越大，信息损失和陈旧页面越难定位。

Phase 4：让路由器学会组合

复杂问题可以先查编译页获得结构，再回 Vector Index 找最新原文，最后沿 Graph 验证影响路径。

Compiled Page 提供计划
      ↓
Graph 提供关系范围
      ↓
Hybrid Search 提供当前证据
      ↓
Evidence Gateway 合并、去重、校验

到这个阶段，三条路线才形成互补。

常见误判

“资料少，就用向量 RAG”

资料少但关系密集，例如商品、会员、订单、活动与售后政策之间的关联查询，Graph 仍可能有价值。资料量不是唯一变量。

“有 Graph 就不用 Vector”

图谱负责结构，原文负责细节。微软 GraphRAG 的 Local Search 本身也会组合 Knowledge Graph 与原始 Text Unit。Graph 不能替代所有文本证据。

“编译一次，以后查询更便宜”

不一定。一项 2026 年的小规模预注册比较发现，LLM-compiled Wiki 更擅长跨论文连接与 Claim 级引用对齐，但测试设置下每次查询使用的 Token 反而明显高于 RAG；分解式 RAG 又追回了大部分综合能力差距。研究的核心结论很克制：组织证据、引用支撑和成本是三项不同能力，没有一个架构全胜。详见 Vector RAG vs LLM-Compiled Wiki。

编译能否回本，要用自己的 Query 分布、更新频率和 Review 成本测。

“Wiki 已经整理好了，可以直接执行”

Wiki 是派生知识，不是权限系统。Agent 查询真实订单或执行退款、赔付等动作，仍要经过 Permission、Approval、Dry Run 和 Evidence 记录。

“让 LLM 自动维护，维护成本接近零”

LLM 降低了写页面和补链接的成本，却增加了事实校验、冲突处理、Schema 演进和错误传播风险。自动化的是体力活，不是责任。

要不要用 / 我的判断框架

如果今天从零做一个知识助手，我不会把“向量、Graph、编译”写进同一张采购清单。

值得马上做：

Hybrid Search；
Metadata / Permission / Revision Filter；
Source Span Citation；
一组包含拒答和旧版本干扰的 Eval。

出现明确瓶颈再做：

多跳依赖和影响分析不稳定时，加 Typed Graph；
高频综合和流程每次都被重复推理时，加 Versioned Compiled Knowledge；
跨整个语料的主题总结成为核心需求时，再评估 Community Report / Global Search。

无论选哪条路线都不能省：

Raw Source 与派生索引分离；
Evidence 能回到 Source；
索引和编译产物可重建；
查询绑定 Scope、Revision 与 Permission；
没有足够证据时明确拒答。

最后的架构判断可以压缩成一句话：

Vector RAG 解决“相关内容在哪里”，GraphRAG 解决“这些对象怎么关联”，编译式 RAG 解决“哪些稳定知识值得提前整理并持续复用”。

先让真实问题暴露知识形状，再选择表示方式。技术路线不应该从一张产品能力表里长出来，而应该从失败用例和评测数据里长出来。

Coding Agent 的交付汇报：6 种状态怎么写

2026-07-23T12:15:00.000Z

Coding Agent 的汇报要让下一个执行者能复现、验证或继续推进，而不是只知道“做了很多事”。

人写周报，常常是为了同步进度。Coding Agent 的汇报不一样：读者往往会顺着它继续改代码、跑测试、审查 diff，或者判断是否能发布。此时“已完成”“已修复”没有证据就没有意义。

我更愿意把 Agent 汇报看成一次交接：它应该告诉下一个人，代码现在处于什么状态、改动在哪里、已验证到哪一步、还有什么没有验证。

一句话总结

Coding Agent 汇报的最小单位不是“做了什么”，而是可核验状态：变更范围、验证证据、Git 状态、部署状态和下一步。先给状态，再给证据；不要用构建通过推断线上可用，也不要用推送成功推断部署完成。

场景	读者要判断什么	必填信息
完成交付	能否接手或合并？	变更、验证、工作区/提交/推送状态
进行中	还差什么，何时能继续？	当前落点、未完成范围、依赖、下一步
失败阻塞	卡在哪里，谁能解除？	根因、影响、已试路径、需要的外部输入
Bug 诊断	修复是否覆盖问题？	现象、影响范围、根因、回归证据
方案决策	现在该选哪条路？	建议、选项、取舍、截止时间
评审/发布	能否进入下一环境？	Findings、风险、验证、回滚条件

1. 完成交付：给出可以复跑的证据

完成不等于写完代码。它至少包含四层彼此独立的状态：工作区、提交、推送、部署。它们必须分别报告。

【结论】文章页的目录滚动高亮已修复。
【变更】修改 src/toc.ts、src/article.css；未改路由和数据结构。
【验证】pnpm test toc 通过；localhost 逐段滚动验证 6 个标题均切换高亮。
【状态】工作区干净；已提交 abc123；已推送 origin/main；未验证生产环境。
【风险】Info：Safari 尚未手测。

这比“修复完成，已发布”多了一点长度，却少了三个常见误解：构建通过不等于功能正确，推送成功不等于 CI 已部署，部署成功也不等于用户路径已经验证。

项目状态报告通常也会要求摘要、阻塞、指标和下一步；对 Coding Agent 来说，要把这些信息进一步落到具体文件、命令和环境。Atlassian 的项目状态报告指南提供了状态、风险和行动项的基础骨架。

2. 进行中：写清“已经落在哪”和“还没有做什么”

进行中最怕伪完成。不要说“完成了 80%”，因为没有人知道剩下的 20% 是一个 CSS 微调，还是一套迁移和回滚逻辑。

【当前落点】Provider Adapter 已抽出接口，Codex 实现已迁移。
【未完成】Qoder Adapter、失败重试、端到端回归尚未开始。
【依赖】需要确认 Qoder 最新 SDK 的流式事件字段。
【下一步】确认字段后补 Adapter 映射与两条集成用例。
【状态】仅本地工作区修改，未提交、未推送。

这里“有意未动的范围”很重要。它把真实边界交给下一位执行者，避免对方误以为某个目录只是漏看了。

3. 失败阻塞：先说根因、影响和解除条件

失败报告不需要整段日志。日志是证据链接，不是结论本身。先给读者足够的信息判断是否要介入：

【阻塞】生产 API 返回 403，部署无法验证。
【根因】当前 token 缺少 release:read Scope；代码请求已在本地 mock 验证。
【影响】不影响本地实现与单测，阻塞生产 Smoke Test。
【已尝试】刷新 token、切换 staging 凭证，均无效。
【需要】由凭证 Owner 补充 Scope，或提供可用的 staging token。

“外部依赖未就绪”不够具体。谁能解决、需要什么、影响到哪一步，才是可执行的阻塞信息。

4. Bug 诊断：把现象、根因和修复证据拆开

Bug 汇报最容易把猜测写成根因。正确顺序是现象、范围、已确认根因、修复和回归证据；尚未确认的内容要标成假设。

【现象】中文输入法确认候选词时，Enter 被当成消息发送。
【范围】Chrome 与桌面 WebView 复现；英文输入不受影响。
【根因】keydown 未检查 composition 状态，已用最小页面复现。
【修复】加入 isComposing 与 keyCode 229 guard。
【回归】中文拼音、五笔、英文 Enter、Shift+Enter 换行均通过手测。

如果修复没有回归范围，下一位开发者无法判断这次改动是解决了根因，还是只是把症状藏起来。

5. 方案决策：把分析压缩成能拍板的选择

Coding Agent 不只交付代码，也会遇到依赖、架构和迁移路径的选择。此时不需要把调研过程逐条搬出来，而要给出自己的建议和明确取舍。

【建议】首期采用方案 B：保留现有 SQLite，新增异步索引表。
【收益】迁移风险低，可在当前版本上线。
【代价】复杂查询继续由应用层处理，第二阶段再评估独立检索服务。
【备选】A 一次性迁移到新存储，能力完整但多 3 周迁移和回滚成本。
【需要决定】请在周三 17:00 前确认 B；确认后我按 B 落地并补迁移验证。

决策文档的关键是让决策人知道该批准什么。Atlassian 的 Decision 模板也把状态、影响、驱动者、批准者和截止时间单独列出，避免“讨论过”被误认为“决定了”。

6. 评审与发布：把“能合”与“能上”分开

Code Review 的结论和发布结论不是同一件事。

结论	需要的证据
可合并	Findings 已处理或有明确豁免；测试覆盖改动范围
可发布	构建、迁移、配置和回滚路径已验证
已部署	部署系统返回成功，且目标环境可访问
已验收	关键用户路径、指标或 Smoke Test 已在目标环境通过

【Review】未发现阻断性问题；1 个 Warning：空状态未覆盖窄屏。
【发布】构建与 migration dry-run 通过；尚未执行生产部署。
【回滚】保留上一个镜像标签，迁移为向后兼容。
【下一步】补窄屏截图后发起部署。

把这些状态拆开，会减少“PR 合了所以线上应该没问题”这种错误推断。

什么时候不该套汇报模板

短问题、单个命令、纯事实查询不需要包装成六段报告。模板只用于复杂、可持续或有风险的交付。若读者只需要一个命令或一个结论，直接给答案更好。

对涉及规划和大范围投入的任务，叙事型方案仍然有价值。Amazon 的 Narrative 方法要求把规划写成连续论证，AWS 的公开说明提到此类文档用于团队和组织规划，正文通常限制在六页以内。AWS Startups 对 Narrative 的介绍适合在 Agent 完成调研后，沉淀为需要人拍板的方案，而不是替代每次代码交付的短报告。

我的判断框架

先问下一个读者要做什么，再决定输出粒度：

继续开发或审查代码 → 交付 / 进行中报告
解除外部依赖       → 失败阻塞报告
确认修复是否可靠   → Bug 诊断报告
批准技术路线       → 方案决策报告
进入下一环境       → 评审 / 发布报告
只要一个答案       → 直接回答，不套模板

对 Coding Agent，好的汇报不是一段漂亮总结，而是一份可以接手的工程状态：事实可定位、验证可复跑、风险有边界、下一步有人能执行。

AI Native 知识库：给人维护，给 Agent 调用，给双方追溯

2026-07-23T00:32:44.000Z

AI Native 知识库参考架构：Source of Truth 与 Index 分离，Knowledge Gateway 统一处理 Query Rewrite、Scope、Permission、Context Budget、Evidence 与 Trace。

最近几天，我围绕一个 Agent 应用连续讨论和验证了 FTS、BM25、Vector Search、RAG、GraphRAG、LLM Wiki、代码结构分析、Query Rewrite 与 Evidence。名词越查越多，最后暴露出的缺口却很具体：缺的并非更大的 Vector Database，而是一套能让 Agent 稳定取用知识、同时让人审查依据的基础设施。

从前端转向 Agent / AI Infra 后，我发现知识库的默认用户变了。人会打开目录、搜索标题、阅读页面；Agent 不会沿着侧边栏一页页翻文档，它需要一个带 Scope、版本、权限、证据和失败语义的接口。只做“把文档塞进向量库”，Demo 很快，系统却很难进入真实执行链路。

一句话总结

如果系统只是让 AI 搜文档、回答问题，叫 AI 知识库 足够准确；如果知识的生产、索引、检索、引用、版本、权限和反馈闭环都围绕 Agent 的运行方式设计，才应该叫 AI Native 知识库。

这套系统同时服务人和 Agent，只是职责不同：

人维护事实源
    ↓
系统编译成 Agent 可检索的索引与工具接口
    ↓
Agent 返回带 Evidence / Citation 的回答或行动依据
    ↓
人和系统共同验证、纠错、发布新版本

给人维护，给 Agent 调用，给双方追溯。

到底叫 AI 知识库，还是 AI Native 知识库

“AI 知识库”是宽泛的产品分类，“AI Native 知识库”是更严格的架构判断。判断标准在于系统把谁当成一等消费者。

形态	主要消费者	典型能力	合适的名字
Wiki / 文档站	人	目录、编辑、全文搜索、权限	知识库
文档问答	人通过 Chat UI 使用	文档上传、Vector Search、RAG 回答	AI 知识库
Agent 知识基础设施	Agent + 人	多源检索、Scope、Revision、Evidence、Citation、Trace、Eval	AI Native 知识库

我会用六个条件判断一个系统是否真的 AI Native：

Agent 通过稳定的 Tool / API 获取知识，而不是抓取某个 Wiki 页面。
Source of Truth 与检索索引分离，索引损坏后可以重建。
每次检索都绑定 Tenant、Workspace、Revision 和 Permission。
返回的不只是答案，而是 Evidence、Citation、Source 与有效版本。
系统能按问题做 Query Rewrite、拆分子问题、路由不同知识源。
检索与回答进入 Eval、Trace 和反馈闭环，错误能够被定位和修复。

只满足“上传 PDF 后能聊天”，我不会把它叫 AI Native。这个词应该表达架构差异，而不是给普通 RAG 换一个更时髦的包装。

知识库究竟是给人看的，还是给 Agent 看的

我把职责拆成三层。

第一层：事实源给人维护

Spec、ADR、Repository、数据库记录、产品规则和正式流程，首先要能被 Owner 阅读、评审和修改。Markdown、Git、文档平台和业务系统依然重要，因为人需要理解完整上下文，也需要承担发布责任。

人需要在这一层回答五个问题：

谁写的；
谁批准的；
哪个版本有效；
冲突时听谁的；
原文在哪里。

如果原始内容只存在于 Vector Database 里，人无法审查，也无法稳定重建，这不是事实源，只是一份难以治理的派生数据。

第二层：索引和接口给 Agent 使用

Agent 不需要每次读取整本 Wiki。它需要结构化、可过滤、可预算的 Knowledge Context：

{
  "query": "一次发布失败后应如何回滚？",
  "scope": {
    "workspace": "project-a",
    "revision": "rev-2026-07-23",
    "principal": "current-user"
  },
  "evidence": [
    {
      "content": "...",
      "sourceUri": "kb://runbook/release-rollback",
      "sourceVersion": "v7",
      "score": 0.91
    }
  ],
  "traceId": "ktrace_xxx"
}

这份结果要控制 Context Window 预算，也要允许程序检查。Agent 关心的是：哪些片段与当前任务相关、是否有权限、是否属于当前版本、证据能否支撑下一步行动。

第三层：Evidence 给双方验证

Evidence 是这两层之间的桥。对 Agent，它是生成回答和执行计划的 Grounding；对人，它是回到原始事实、判断答案是否可信的入口。

界面不能只展示一段自然语言答案，还应允许查看：

引用了哪些片段；
每个片段来自哪个 Source；
检索时绑定了哪个 Revision；
哪些 Query 被改写或拆分；
哪个检索器命中了它；
Agent 最终使用了哪些 Evidence。

知识库的正文给人看，编译结果给 Agent 用，Evidence 则必须让双方都看得懂。

知识库技术发展历程

这段历史最容易被讲成一条“后浪淘汰前浪”的升级路线：Vector Search 淘汰 BM25，GraphRAG 淘汰 RAG，Agentic Retrieval 再淘汰 GraphRAG。这个理解不对。它们解决的是不同层次的问题，今天仍然会同时出现在一套系统里。

1990s–2010s：从倒排索引到 BM25

最早的问题很直接：文档很多，怎样快速找到包含某个词的内容？

Inverted Index 把“词 → 文档”建立映射，FTS 负责全文检索，BM25 负责根据词频、稀有程度和文档长度排序。它们不理解抽象语义，却非常擅长精确对象：函数名、错误码、配置项、订单号、API 名称和领域术语。

这类能力没有过时。只要系统里存在精确标识符，Keyword Search 就仍然是不可替代的召回通道。

2019–2020：Dense Retrieval 与 Vector Search

Embedding 把 Query 和文档映射到同一个向量空间，检索开始从“出现了同一个词”走向“表达了相近的意思”。2020 年的 Dense Passage Retrieval 让 Dense Retrieval 在开放域问答中成为重要路线。

Vector Search 解决了同义表达和自然语言问题。例如“怎么固定一次工作区使用的内容”和“Workspace Revision 是什么”可能指向同一概念，即使它们共享的关键词很少。

但语义相似不等于业务上正确。Vector Search 可能把相似概念混在一起，也可能让精确的类名和错误码沉到后面。它增加了一种召回能力，没有取代关键词检索。

2020–2022：RAG 把检索接到生成模型前面

2020 年的 RAG 论文把 Parametric Memory 与可检索的 Non-parametric Memory 结合起来。工程上最朴素的 RAG 流程是：

1	Query → Retrieve Top K → 拼进 Prompt → LLM Generate

从这里开始，知识库不只返回文档，还开始参与回答。系统质量也不再只由搜索相关性决定：错误的 Chunk 会诱导模型自信地答错，没有证据时模型是否拒答，Citation 是否真的支撑 Claim，都成为新的问题。

2023–2024：Production RAG

RAG 从 Demo 进入生产后，“选一个 Embedding Model + Vector Database”很快暴露出边界。生产链路开始加入：

Keyword + Vector 的 Hybrid Search；
RRF 或其他 Fusion；
Cross-encoder / LLM Reranker；
Metadata Filter；
结构化或 Contextual Chunking；
Citation、Groundedness 与检索评测；
权限、版本、增量更新、延迟和成本控制。

Elastic 的官方文档直接把 Hybrid Search 定义为全文检索与 Vector Search 的组合，并推荐用 RRF 合并排名。Anthropic 的 Contextual Retrieval则把文档级上下文补回每个 Chunk，再同时建立 Contextual Embedding 和 Contextual BM25，并叠加 Rerank。

到这一步，RAG 已经从 Prompt 技巧扩展成 Search / Data / Eval 工程。

2024–：GraphRAG 处理关系和全局问题

GraphRAG 显式抽取 Entity、Relationship、Claim 和 Community，让检索能回答两类普通 Top K RAG 不擅长的问题：

局部关系：某个实体与哪些对象相关，依赖链是什么；
全局问题：整批资料有哪些主要主题、组织和冲突。

Microsoft GraphRAG同时保留 Basic Search、Local Search、Global Search 和 DRIFT Search。Local Search 会把图中的实体关系与原始文本片段组合，Global Search 则基于 Community Report 做全局汇总。这本身就说明 GraphRAG 不是 RAG 的替代品，而是增加了适合关系型问题的索引与 Query Mode。

实体和关系抽取需要额外模型调用，图谱可能有噪声，增量更新、冲突和版本治理也更复杂。Microsoft 的官方入门文档直接提醒 GraphRAG 索引会消耗大量 LLM 资源。没有真实的关系查询，就不该为了架构图好看而上 GraphRAG。

2025–2026：Agentic Retrieval

普通 RAG 通常“搜一次”；Agentic Retrieval 会先理解任务，再决定搜什么、去哪里搜、是否继续追问。

用户任务
  ↓
Query Planning / Rewrite
  ↓
拆分多个 Subquery
  ↓
选择共享知识、当前文件、代码结构或实时系统
  ↓
并行 Keyword / Vector / Hybrid Search
  ↓
Rerank + Evidence Merge
  ↓
返回 Citation 与 Activity Trace

Azure AI Search 的 Agentic Retrieval已经把这个过程产品化：根据 Query 和 Conversation History 生成聚焦的 Subquery，并行执行 Keyword、Vector 或 Hybrid Search，经过 Semantic Rerank 后保留引用与执行日志。

简单查询直接走低成本路径更稳。多意图、多来源或需要多跳证据时，再让 LLM 参与检索规划。

这些技术之间到底是什么关系

我现在按层级理解它们，不再把这些名词排成版本号：

概念	所在层	它解决什么	它不负责什么
FTS / BM25	Retrieval	精确词召回与排序	不理解深层语义
Embedding / Vector Search	Retrieval	同义表达与语义召回	不保证精确标识符优先
Hybrid / RRF	Retrieval	合并关键词与语义结果	不验证证据是否正确
Reranker	Ranking	对候选结果做更精细排序	不能召回候选集中不存在的内容
RAG	Generation Workflow	用检索结果约束生成	不等于知识治理
GraphRAG	Structured Retrieval	关系、多跳、全局主题	不适合默认替代所有检索
LLM Wiki	Knowledge Engineering	组织事实源、知识页面、引用和演进	不是一种单独的检索算法
Agentic Retrieval	Runtime Orchestration	改写、拆问、选源、迭代和留 Trace	不应绕过权限与治理
AI Native 知识库	System Architecture	把以上能力变成 Agent 可依赖的基础设施	不是某个数据库或框架名

“LLM Wiki”并不是像 BM25 那样有严格定义的算法名。它更像一种产品和知识工程形态：让 LLM 帮助摄取、整理、链接、总结和维护知识页面。它可以使用 RAG，也可以使用 GraphRAG，但不会让底层检索失去用武之地。

2026 年搭建知识库的最佳实践

1. 先定义事实源，再选 Vector Database

先列出哪些系统有资格声明事实：正式 Spec、ADR、当前 Repository、业务数据库、审批记录、Runbook。会议记录、聊天记录和自动总结通常只能算 Raw Knowledge，不能自动覆盖正式结论。

我通常采用这样的优先级：

已发布 Knowledge Asset
> 当前 Repository Revision
> 经确认的业务记录
> Raw Document / Meeting / Chat
> 模型生成的 Summary

“更新时间更晚”不等于“权威性更高”。

2. Source、Asset 与 Index 必须分开

这三个对象很容易被混成“已经导入知识库”：

Source：原始事实在哪里；
Knowledge Asset：经过清洗、归属、审核和发布的知识版本；
Index：为了检索生成的 Chunk、Embedding、Posting List、Entity 与 Edge。

Index 应该是可重建的 Projection，不应该成为第二事实源。Embedding Model、Chunking Strategy 或 Schema 变化时，正确动作是从 Source / Asset 重建索引，而不是让旧向量永久背负历史包袱。

3. Chunk 不是按固定字数切完就结束

Chunk 至少要保留标题层级、表格语义、代码符号、列表边界和来源位置。不同内容应该用不同策略：

内容	优先切法
Markdown / Spec	按 Heading 与语义段落
API 文档	按 Endpoint / Symbol
代码	按函数、类、模块与调用关系
表格	保留表头与相关行
长 PDF	结构解析后再按 Section

不要迷信一个全局 Chunk Size。OpenAI 的 Retrieval 文档允许自定义 Chunk Size 和 Overlap，也支持文件 Attribute Filter；这类参数应该由 Eval 驱动，而不是从教程里复制一个数字。

如果 Chunk 脱离父文档后不知道自己在说谁，可以给它增加简短的 Context Prefix，再建立 Keyword 和 Vector Index。

4. Hybrid Search 应该是团队知识的默认候选

对于只包含精确技术术语的小型知识库，BM25 足够简单可靠；一旦用户会用自然语言、中文或同义词提问，Keyword + Vector 通常更稳。

推荐链路是：

1
2
3

Keyword Candidates ─┐
                    ├→ RRF / Weighted Fusion → Reranker → Top Evidence
Vector Candidates ──┘

先并行扩大 Recall，再用 Reranker 提升 Precision。不要直接拿两个分数相加，BM25 Score 与 Vector Similarity 往往不在同一标度上。

5. Scope 与 Permission 要在检索前生效

先检索全部内容、再在答案阶段隐藏结果，是危险设计。过滤至少要覆盖：

tenant / organization；
workspace / project；
source；
revision / effective time；
principal / role；
confidentiality；
content status。

安全边界应尽量在 Candidate Retrieval 前收紧，避免跨项目内容进入模型上下文。对 Agent 来说，这既是数据权限问题，也是 Prompt Injection 与错误行动的隔离问题。

6. Query Rewrite 先做确定性版本

中文、缩写和领域词经常让 FTS 零召回。第一阶段不必立刻引入昂贵的 LLM Query Planner，可以先从受治理的 Glossary 生成确定性映射：

1 2	“工作区版本是什么” → “Workspace Revision”

先查改写结果，零命中再回退原始 Query。这样行为可解释、可测试，也能快速验证问题到底在分词、Query 还是内容本身。

当复杂 Query 占比上升，再增加 Multi-query、Subquery Planning 和 Source Routing。只有任务复杂度值得支付规划成本时，才进入 Agentic Retrieval。

7. Rerank 之前先保证 Candidate Recall

Reranker 只能重排已有候选。正确文档没有进入 Top 50，后面的模型再强也救不回来。

因此评测要分层：

Retrieval Eval：正确 Evidence 是否进入候选集？
Ranking Eval：正确 Evidence 是否排到足够靠前？
Generation Eval：回答是否被 Evidence 支撑？
Agent Eval：行动是否遵守 Scope、Permission 与事实？

把最终回答的好坏全部归因于 LLM，会让 Search 问题长期藏在 Prompt 里。

8. 每个关键 Claim 都应能回到 Evidence

Citation 不是装饰性的文末链接。一个可用的 Citation 至少包含：

1	source_uri + source_version + location + content_hash

如果 Source 更新后 Citation 指向另一段内容，审计就失效了。对于会触发写文件、发消息、部署或审批的 Agent，关键决策必须保留 Knowledge Trace：用了哪些 Evidence、哪个版本、如何生成结论。

9. 明确“没有答案”也是正确结果

知识库缺少证据时，系统应该返回 no_evidence，而不是用模型常识补一段看似合理的答案。评测集中必须有反向样本：

知识库根本没有答案；
只有过期版本有答案；
当前用户无权访问答案；
两个正式 Source 互相冲突。

这几类问题比普通命中更能检验知识系统是否可信。

10. 用 Eval 决定升级，不用架构焦虑决定升级

我会维护一组 Query → Expected Evidence 的离线数据，并持续观察：

指标	回答的问题
Recall@5 / Recall@20	正确证据有没有被找回
MRR / nDCG	正确证据排得是否足够靠前
Zero-hit Rate	是否频繁完全无结果
Citation Precision	引用是否真的支撑 Claim
Grounded Answer Rate	答案是否只使用已给证据
No-evidence Accuracy	没答案时能否正确拒答
Scope Leakage	是否混入其他项目或无权限内容
Freshness Lag	Source 更新多久后可被检索
P50 / P95 Latency	检索给 Agent Turn 增加多少延迟
Cost per Retrieval	Rewrite、Embedding、Rerank 与 Planner 的成本

我的当前门槛是：先用确定性 Query Rewrite；中文评测出现 Recall@5 < 85% 或 Zero-hit Rate > 5% 时，再把 Multilingual Embedding + Hybrid Search 提到下一阶段。这两个数字服务于当前项目，不是行业标准。

每个技术如何决策

技术	什么时候用	什么时候先别用	主要代价
`grep` / Raw File Search	当前 Workspace、文件刚变化、精确字符串	团队共享知识与自然语言问答	能力简单，结果缺少治理
FTS + BM25	错误码、类名、配置项、领域词	Query 大量使用同义表达	分词与语言适配
Vector Search	自然语言、跨语言、同义表达	精确 ID 与小规模纯术语库	Embedding 成本与语义误召回
Hybrid Search	团队文档、代码说明、中文问答	数据量极小且 BM25 已达标	两套索引与 Fusion 调参
Reranker	候选集 Recall 已好、Top K 排序不稳	正确证据根本没进候选集	额外模型延迟和成本
Contextual Retrieval	Chunk 离开父文档后语义残缺	文档短且 Chunk 本身自包含	索引时生成上下文的成本
GraphRAG	依赖链、影响分析、组织关系、全局主题	主要是定义查询和精确搜索	图谱抽取、更新与噪声治理
Code Graph	跨文件 Symbol、调用关系、模块依赖	只是找文本或当前未保存文件	语言解析器与增量更新
Agentic Retrieval	多意图、多源、多跳、需要迭代检索	单一事实查询、高 QPS 低延迟路径	Planner 成本、不可预测性与 Trace 复杂度

我用下面这个顺序做技术决策：

问题能否靠精确词回答？
  ├─ 能 → BM25 / Raw File Search
  └─ 不能 → 是否主要是语义改写？
       ├─ 是 → Vector + Hybrid
       └─ 否 → 是否需要关系或全局理解？
            ├─ 是 → Code Graph / GraphRAG
            └─ 否 → 是否需要跨多个 Source 拆问？
                 ├─ 是 → Agentic Retrieval
                 └─ 否 → 先检查 Source、Chunk 与 Metadata

很多“需要更强模型”的问题，最后根因其实是 Source 不可信、Chunk 丢上下文、Scope 错了，或 Query 用错了检索器。

这些技术应该如何搭配

落地时，我把系统拆成一个事实面、多个检索投影和一个统一 Knowledge Gateway。

┌──────────────────── Human-owned Sources ────────────────────┐
│ Spec / ADR / Repository / Runbook / Business Data / Raw Doc │
└───────────────────────────┬───────────────────────────────────┘
                            ↓
                 Normalize / Validate / Publish
                            ↓
┌──────────────────── Knowledge Assets ────────────────────────┐
│ owner · trust · version · effective time · ACL · source URI │
└───────────────────────────┬───────────────────────────────────┘
                            ↓ rebuildable projections
        ┌───────────────────┼────────────────────┐
        ↓                   ↓                    ↓
   BM25 / FTS          Vector Index       Graph / Code Index
        └───────────────────┼────────────────────┘
                            ↓
┌──────────────────── Knowledge Gateway ───────────────────────┐
│ Scope Filter → Rewrite / Plan → Route → Fusion → Rerank     │
│ → Evidence Package → Citation → Knowledge Trace             │
└───────────────────────────┬───────────────────────────────────┘
                            ↓
                    Agent Runtime / Tools
                            ↓
               Answer / Plan / Action / Delivery
                            ↓
                       Eval & Feedback

BM25、Vector Database、Graph Engine 和本地搜索都收口到 Gateway；如果直接暴露给每个 Agent Provider，权限、版本、Citation 和审计会散落在不同 Adapter 里。

Provider 应该看到一个稳定的领域接口，例如：

type KnowledgeSearchRequest = {
  query: string;
  intent?: "lookup" | "explain" | "impact" | "global";
  workspaceId: string;
  revision: string;
  principal: string;
  budget: {
    maxResults: number;
    maxTokens: number;
    maxLatencyMs: number;
  };
};

具体使用 BM25、Vector、Graph 还是多路并行，由 Knowledge Gateway 根据 Intent、数据新鲜度、预算和 Eval 结果决定。

三种可直接落地的组合

组合 A：个人 / 小项目

Markdown / Repository
→ SQLite FTS5 或本地 BM25
→ Glossary Query Rewrite
→ Top 5 Evidence + 文件行号 Citation
→ Agent

这套组合完全在本地运行，依赖少，检索行为也容易解释。内容不多时，不要先搭分布式 Vector Database。

组合 B：团队知识库

Git / 文档平台 / 业务系统
→ 规范化 Knowledge Asset
→ BM25 + Multilingual Embedding
→ Metadata Filter + RRF + Rerank
→ Citation + Revision + ACL
→ Chat / Agent 共用

对多数团队，这已经是一条够用的 Production RAG 基线。先把 Hybrid、治理和 Eval 做稳，再讨论图谱。

组合 C：应用侧集成

共享长期知识：团队 Spec / ADR / Runbook
当前工作区：实时 Raw File Search
代码结构：Symbol / Dependency Graph
实时事实：业务 API / Database Tool
                ↓
         Unified Knowledge Gateway
                ↓
 Query Planning / Source Routing / Evidence Merge
                ↓
      Agent Action + Knowledge Trace + Eval

四类信息的时效和结构不同：

共享知识回答“团队已经确认了什么”；
Raw File Search 回答“当前磁盘上刚刚发生了什么”；
Code Graph 回答“代码对象怎样连接、改动影响哪里”；
业务 API 回答“此刻真实世界的状态是什么”。

把它们全部塞进同一个 Vector Index，会失去新鲜度、结构、权限和事实边界。

一条务实的实施路线

Phase 0：先做 Eval Set

准备 30–100 条真实问题，每条标注 Expected Source、Expected Evidence、允许的 Revision 和拒答条件。没有这一步，后续所有“效果不错”都只是观感。

Phase 1：Keyword + Evidence

先打通 Source、Chunk、FTS/BM25、Citation 和 no_evidence。对中文和领域词加入确定性 Query Rewrite。

我把这一阶段的验收写成五条：

正确 Source 能进入 Top K；
Citation 能回到原文；
Scope 不串；
没证据时拒答；
索引可以重建。

Phase 2：Hybrid + Rerank

当同义表达和中文召回成为主要问题，加入 Multilingual Embedding，用 RRF 合并 Keyword / Vector 候选。只有 Candidate Recall 达标后再上 Reranker。

Phase 3：按问题增加结构索引

代码影响分析用 Code Graph，实体关系和全局主题用 GraphRAG。不要创建一个包治百病的“统一大图谱”。

Phase 4：Agentic Retrieval

当任务确实需要多个 Source、多轮补证和动态路由，再引入 Planner。给每次检索设置 Token、Latency 和 Cost Budget，并完整记录 Activity Trace。

最容易踩的坑

把 Vector Database 当知识库

Vector Database 只保存一种检索投影。它不知道哪份文档是正式结论，也不天然理解权限、版本和冲突。

把 `simple` 当中文分词

取消英文 Stemming 或 Stop Words，不等于获得中文 Tokenizer。中文检索应通过真实 Query Eval 判断是先做 Rewrite、Multilingual Embedding，还是增加中文 BM25 Side Index。

把 GraphRAG 当默认终局

图谱最擅长关系与全局问题。大多数“某个概念是什么”“某个错误怎么修”仍然更适合 BM25、Vector 或 Hybrid。

让 Agent 自由搜索却没有 Scope

Agentic Retrieval 增加了自主性，也放大了跨项目污染、越权和 Prompt Injection 风险。Planner 可以决定怎么搜，不能决定自己有权看什么。

只测最终回答

一段流畅答案可能引用错文档。必须分别评测 Retrieval、Ranking、Grounding 和 Action。

索引不可重建

如果团队不敢删掉 Index 重建，说明事实源、转换流程或版本记录并不可靠。可重建是知识基础设施成熟度的重要标志。

要不要用 / 我的判断框架

值得现在做：

把系统定位为“人维护事实、Agent 调用知识、双方追溯 Evidence”；
明确 Source of Truth、Knowledge Asset 与 Index 的边界；
从 FTS/BM25、Citation、Scope 和 Eval 起步；
团队知识默认评估 Hybrid Search；
把当前文件、代码结构、共享知识和实时业务事实分开接入；
让所有 Provider 通过统一 Knowledge Gateway 使用它们。

可以再等：

在没有关系型 Query 证据前建设完整 GraphRAG；
在单次 Query 已足够时启用 LLM Planner；
为了“AI Native”这个名字重写已有 Wiki；
在没有 Eval Set 时频繁更换 Embedding Model 和 Vector Database。

重点关注：

Permission 和 Revision 必须先于检索结果进入模型；
Citation 必须指向稳定的 Source Version；
no_evidence 是正常结果，不是系统故障；
Agent 的每个关键行动都要能回到 Knowledge Trace。

我的责任划分已经很明确：人负责事实源，Agent 使用检索接口，Knowledge Gateway 管住 Scope、Revision 和 Permission。 Agent 给出答案或准备执行动作时，再把 Evidence、Citation 和 Trace 交回给人。

是否 AI Native，可以用一次错误行动来检验：系统能不能沿着 Trace 找到它用了哪条 Evidence、哪个版本、哪个检索分支，并据此修正 Source 或索引。只能看到一段回答、查不到依据的产品，即使加了 Chat Box，也仍然只是文档问答。

参考资料

Raw Knowledge 如何变成可信知识资产：以及中文 FTS 为什么不是改个配置

2026-07-22T15:55:00.000Z

最近我把 GBrain 接到一个 Agent 应用的应用侧，能够检索本地文档、给 Codex 注入上下文，也能在回答中带上 gbrain:// Citation。

链路跑通之后，我反而遇到了两个更本质的问题：一个新项目有代码仓库、语雀、钉钉、Issue 和会议记录，这些 Raw Knowledge 到底怎样才算“进入知识库”？另一方面，中文文档明明已经导入，为什么问一句“Revision 是什么”却可能一条也搜不到？

这两个问题表面上分别属于知识治理和搜索，底层却指向同一个误区：派生索引不是事实源，语义检索也不是全文检索。

一句话总结

Raw Knowledge 导入 GBrain 后，只是变成可检索的 Page、Chunk、Embedding 和 Edge；只有经过归属、规范化、校验和发布，才成为应用侧的 Knowledge Asset。中文检索则需要 Query Rewrite、Multilingual Embedding 与关键词检索协作，单纯把 PostgreSQL FTS 从 english 改成 simple 并不会获得中文分词能力。

完整链路应该是：

Raw Knowledge
    ↓ 归属、清洗、规范化
Knowledge Source
    ↓ GBrain import / sync
Page → Chunk → FTS / Embedding → Edge
    ↓ 整理、校验、审核、发布
Knowledge Asset Version
    ↓
Workspace Revision

这里存在两条可以并行、但不能混为一谈的流水线：一条负责“先搜起来”，另一条负责“让知识变可信”。

被 GBrain 索引，不等于成为 Knowledge Asset

这是我这次最重要的认知修正。

GBrain 认识的核心对象是：

1	Source → Page → Chunk → Embedding / FTS → Edge

应用侧认识的核心对象则是：

Knowledge Draft
→ Knowledge Asset
→ Knowledge Asset Version
→ Asset Manifest
→ Workspace Revision

两边的概念不能直接画等号。

一篇语雀文档被同步进 GBrain 后，可以被搜索、切块、建立向量和关系，但它依然可能过期、互相冲突、没有明确 Owner，甚至只是一场会议里的临时观点。它是 Raw Knowledge，不是已经发布的 Knowledge Asset。

如果把“进入索引”直接理解成“成为资产”，GBrain 数据库就会悄悄变成第二事实源。之后谁也说不清：正式 Spec 和会议记录冲突时听谁的？索引中的旧 Chunk 是否仍然有效？一个已经删除的页面能不能继续影响 Agent？

所以我现在采用一个更严格的边界：

对象	是什么	能否作为正式依据
Raw Knowledge	仓库、文档、Issue、会议、对话等原始内容	不能默认信任
GBrain Page / Chunk	从 Source 生成的可检索派生数据	只能回到 Source 验证
Knowledge Draft	从 Raw Knowledge 提炼出的待审核结论	尚未发布
Knowledge Asset Version	已完成校验和发布的不可变知识版本	可以作为正式依据
Workspace Revision	固定一组 Asset Version 的不可变快照	决定当前 Workspace 使用什么

新项目的知识库应该怎样组织

一个新项目不应该只有一个不分来源的“大知识库”。至少应该按来源和信任级别拆成三类 Source：

Source	内容	信任级别
`team-specs`	正式 Spec、ADR、团队规范	高
`{project}-repo`	当前代码、README、仓库文档	中高
`{project}-raw`	语雀导出、会议记录、Issue、调研材料	中低

当不同 Source 冲突时，我采用下面的优先级：

正式 Knowledge Asset
> 当前 Repository Revision
> 团队 Raw Knowledge
> 历史会议和对话

“更新得晚”不等于“权威性更高”。一条昨天的会议讨论，不能因为时间更近就覆盖上周已经评审通过的 ADR。

对于语雀和钉钉，正确的数据流也不是“连接以后全部自动变成知识”：

语雀 / 钉钉
→ Connector 拉取
→ 保存 document_id、source_url、author、updated_at
→ 转换成规范 Markdown
→ 导入 project-raw Source
→ 提取候选结论生成 Draft
→ 人工或规则校验
→ 发布 Knowledge Asset Version

LLM 可以帮助提取 Draft，但不能因为“总结得像”就自动获得发布权。

GBrain 实际怎样处理一份 Raw Knowledge

一份适合导入 GBrain 的最小 Markdown 可以是：

---
title: Workspace Revision
type: concept
tags:
  - example-workspace
  - architecture
source_uri: https://example.com/original-document
owner: architecture-team
---

## 一句话定义

Workspace Revision 是面向 Workspace 发布的不可变资产集合快照。

## 约束

- 由 Asset Manifest 固定所有 Asset Version。
- 本地只能激活校验通过的版本。



## 2026-07-22

首次确认该定义。

GBrain 导入时会解析 Front Matter、生成稳定 Slug、计算 Content Hash、创建 Page、拆分 Chunk，然后建立 Keyword Index；配置 Embedding 后还会生成向量，并从文档链接或代码引用中提取 Edge。

这些步骤把内容变得容易搜索，但没有替代 Source 的所有权、版本和审核流程。Page、Chunk、Embedding 和 Edge 都应该可以从已知 Source 重新构建。

中文文档已经导入，为什么还是搜不到

当前 GBrain MVP 使用 PGLite，初始化参数是：

1	gbrain init --pglite --no-embedding

这意味着当前实际依赖的是 PostgreSQL Keyword Search，而且 FTS language 默认为 english。

我用同一个 Brain 做了一组直接检索：

Query	Hit
`事实源`	3
`本地知识`	2
`Revision 是什么`	0
`Workspace Revision 是什么`	0
`工作区版本是什么`	0
`Workspace Revision`	3
包含多个英文领域词的完整中文 Prompt	3

这个结果说明它不是“完全不支持中文”。索引里恰好存在的完整中文词可以命中，英文领域词也很稳定；真正不可靠的是中文自然问句。

例如：

1	Workspace Revision 是什么

检索器可能把 Workspace、Revision 和后面的中文片段一起当作必须满足的条件。只要中文 token 与索引里的形式不一致，整个查询就可能变成零召回。

`simple` 不是中文分词器

GBrain 支持通过 GBRAIN_FTS_LANGUAGE 改变 PostgreSQL text search configuration。看到这里很容易产生一个朴素想法：把 english 改成 simple，是不是中文就好了？

答案是否定的。

simple 的主要作用是取消英文停用词和 stemming，不会自动把：

1	工作区修订是不可变资产集合快照

切成：

1	工作区 / 修订 / 不可变 / 资产 / 集合 / 快照

因此，改成 simple 最多改变 token 的处理规则，不能补齐中文 tokenizer。严格意义上的中文 FTS 仍然需要 jieba、zhparser、Lindera 或其他中文分词能力。

Embedding 能解决什么，不能解决什么

Embedding 能把问题和文档映射到语义空间，适合处理：

1
2
3

Revision 是什么？
工作区如何固定可信资产？
一次执行怎样保证知识版本一致？

这些问题用词不同，但都可能指向 Workspace Revision。

不过，Embedding 不是 FTS。它擅长语义相似，不保证函数名、错误码、配置项、缩写和精确领域词一定排在最前面。对于代码和 AI Infra 项目，完全用 Vector Search 替代关键词检索同样会出问题。

正确结构是 Hybrid Search：

1
2
3

Keyword Search ─┐
                ├→ RRF Fusion → Metadata / Permission Filter → Evidence
Vector Search ──┘

Keyword Search 守住精确术语，Vector Search 补足中文和同义表达，再通过 RRF 合并两个排序列表。

应用侧的三阶段修复路线

第一阶段：Query Rewrite

这是成本最低、应该最先做的一步。

用户输入：

1	Workspace Revision 是什么？

应用侧生成三条确定性 Query：

1
2
3

原始：Workspace Revision 是什么
精确：Workspace Revision
别名：Workspace Revision 修订 版本快照

每条分别检索，最后合并去重。别名不应该每次调用 LLM 临时生成，而应该来自项目的 CONTEXT.md 和受治理 Glossary，这样结果可解释、可重复。

第二阶段：Multilingual Embedding

创建一个带 Embedding 的新 Brain，重新导入全部 Source，再启用 GBrain 已有的 Hybrid Search。

这里不能直接在当前 PGLite 上修改一个配置完事。Embedding dimensions 会影响 Schema，当前 no-embedding Brain 应该按照下面的方式迁移：

保留旧 Brain
→ 初始化 Brain v2
→ 重新导入所有 Source
→ 回填 Embedding
→ 跑中文检索评测
→ 验证后原子切换
→ 保留旧 Brain 回滚

这也是为什么事实源必须独立于索引存在：只有 Source 可靠，索引才能放心重建。

第三阶段：真正的本地中文 FTS

如果后续评测证明 Embedding 仍不能满足精确中文术语检索，再给应用侧增加中文 Side Index：

GBrain Vector Search
+ GBrain Keyword Search
+ 本地 Tantivy 中文 BM25
→ RRF Fusion

另一条路线是在云端 PostgreSQL 使用 pg_jieba 或 zhparser，但它增加了数据库扩展和部署运维复杂度，不适合当前以本地 PGLite 为主的 MVP。

不能只看回答“像不像对”

中文检索升级之后，我会准备一组带期望 Citation 的评测数据：

{
  "query": "Workspace Revision 是什么？",
  "expectedSlugs": [
    "example-workspace-spec"
  ]
}

至少观察下面几个指标：

指标	关注的问题
Recall@5	正确文档是否进入前 5
MRR@5	正确文档排得是否足够靠前
Zero-hit Rate	中文问句是否仍频繁零召回
Citation Precision	引用是否真的支撑回答
P95 Latency	Hybrid Search 增加了多少延迟
Scope Leakage	是否检索到其他 Workspace 的知识

最后一项尤其重要。一个全局 Brain 如果没有绑定 Workspace 和 Source，再高的召回率也可能意味着更严重的跨项目污染。

要不要用 / 我的判断框架

值得现在做：

把 Raw Knowledge、GBrain Index 和 Knowledge Asset 分开建模。
每个项目按 team-specs、project-repo、project-raw 划分 Source。
用 Query Rewrite 立即修复中英混合问句。
建立带期望 Citation 的中文评测集。

可以随后做：

迁移到 Multilingual Embedding。
用 Keyword + Vector + RRF 构建 Hybrid Search。
把检索 Trace、Hit Count、Latency 和 Citation 暴露到应用侧 UI。

重点关注：

不要把 GBRAIN_FTS_LANGUAGE=simple 当成中文 FTS。
不要因为文档已经进入 GBrain 就称它为 Knowledge Asset。
不要让索引成为无法重建、无法追溯的第二事实源。
不要在没有 Workspace / Source Scope 的情况下把多个项目全部塞进默认 Brain。

我现在对这套系统的判断比刚接入 GBrain 时更保守，也更清楚：真正困难的从来不是把文档导进去，而是决定哪些内容可信、什么时候有效、检索为什么命中，以及 Agent 最后引用的到底是哪一条事实。

GBrain 从入门到精通：构建可引用的本地知识层

2026-07-22T15:50:00.000Z

我最近把 GBrain 接到了一个 Agent 应用的应用侧。接入之前，我对它的理解比较简单：把团队文档导进去，然后让 Agent 搜索。

真正做起来之后，我发现 GBrain 的价值不只是“能不能搜到文档”，而是能不能把团队知识变成一层可检索、可引用、可版本化、可被 Agent 安全消费的 Knowledge Plane。

这篇文章记录我对 GBrain 的完整理解，也给出一条从本地 MVP 走向团队系统的实践路径。

一句话总结

GBrain 是一个面向 LLM 的知识组织和检索运行时：它把事实源编译成可查询的知识索引，再把相关内容以 Evidence 和 Citation 的形式交给 Agent。

它在系统里的位置可以表示成：

代码 / Spec / ADR / 团队文档
          ↓
      GBrain Ingestion
          ↓
   FTS / BM25 / Vector / Graph
          ↓
   Evidence + Citation + Revision
          ↓
    应用侧 / Agent Context
          ↓
       Codex / Qoder

GBrain 负责“知识怎么被找到和组织”，应用侧负责“谁能使用这些知识、作用于哪个 Workspace、最终执行是否成功”。两者不能混成一个边界。

GBrain 解决什么问题

普通聊天模型有三个天然限制：

不知道团队刚刚写下的内部规范。
不知道当前仓库的真实代码状态。
回答有依据时，也很难告诉你依据具体来自哪里。

把所有文档直接拼到 Prompt 里也不可行：内容太多、上下文太长、成本太高，还会把过期和无权限内容一起带进去。

GBrain 的基本任务就是把这个问题拆开：

收集事实源。
把事实源切成可检索的知识单元。
建立关键词、语义和关系索引。
根据问题取回最相关的 Evidence。
为结果保留 Source、Citation、Provenance 和 Revision。
把受治理的上下文交给 LLM。

所以，GBrain 不是“让模型记住一切”，而是让模型在需要时找到可信的外部事实。

先分清几个概念

Source：事实源

Source 是知识从哪里来的，例如：

Git repository
Markdown、PDF、设计文档
语雀文档、钉钉文档
ADR、会议纪要、需求说明
构建报告、测试报告和发布回执

语雀或钉钉文档当然可以是 Source，但它们只是事实源，不等于已经完成治理的 Knowledge Asset。

Evidence：证据

Evidence 是能够支撑某个结论的具体内容片段。

例如：

1
2
3

Claim：Overlay 不修改基础 Revision。
Evidence：架构 Spec 中对 Overlay 的定义段落。
Citation：gbrain://default/example-workspace-spec

Evidence 不等于 Agent 的自述，也不等于一段没有来源的摘要。它应该能定位回原始文档、文件、行号或 Chunk。

Citation：引用

Citation 是 Evidence 的可回溯地址。在 GBrain 接入应用侧的 MVP 中，我使用类似下面的形式：

1	gbrain://default/example-workspace-knowledge-architecture

Citation 的价值是让用户知道答案为什么可信，也让后续的评测和审计有入口。

Revision：知识版本

同一个文件可能在不同时间代表不同事实。Revision 用来回答：

1	这条知识在哪个版本、哪个 Workspace、哪个时间范围内有效？

应用侧不允许拿旧 Revision 的索引结果冒充当前 Workspace 的知识。知识检索必须和当前 Session Pin、Workspace 和 Permission Scope 对齐。

GBrain 的内部数据流

一个比较完整的 GBrain 数据流如下：

Source
  ↓ parse
Document
  ↓ split
Chunk
  ↓ index
FTS / BM25 / Vector / Graph
  ↓ search
Evidence
  ↓ cite
Citation + Provenance
  ↓ compose
LLM Context

这里最容易犯的错误是把“索引”当成事实源。索引只是派生数据，应该可以从已验证的原始输入重新构建；真正的事实源应该保留自己的版本和摘要。

GBrain 如何检索

FTS 和 BM25

FTS 是 Full-Text Search，负责全文索引和关键词召回；BM25 负责对候选结果排序。

它们适合：

函数名、类名、错误码
API 名称和配置项
Workspace Revision 这类领域术语
代码和规范里的精确标识符

它们不真正理解语义，所以中文自然语言问题可能需要更好的分词、Query Rewrite 或 Vector Search。

Vector Search

Vector Search 通过 Embedding 把问题和文本放进向量空间，适合处理同义表达和自然语言描述。

例如：

1
2
3

Revision 是什么？
工作区如何固定可信资产？
如何保证 Agent 使用的知识版本一致？

这些问题的词不完全一样，但语义可能指向同一组文档。

Graph Search

当问题关注实体之间的关系时，图结构更有用：

Workspace Revision ──固定──> Asset Version
Overlay ──叠加于──> Revision
Projection ──派生自──> Revision
Evidence ──支撑──> Claim

实际系统通常会采用 Hybrid Retrieval：关键词保证精确术语，向量补足语义召回，图和 Metadata Filter 限定关系、权限和版本范围。

GBrain 和 LLM Wiki 的关系

LLM Wiki 可以理解为“知识治理层”，GBrain 可以作为它的知识运行时。

简单 RAG 重点是：

1	问题 → 找文本 → 塞 Prompt → 回答

成熟的 LLM Wiki 还要处理：

哪个 Source 是事实源？
两份文档冲突时谁优先？
这条知识是否已经过期？
当前用户有没有权限看到它？
结论能否回到 Evidence？
一次执行产生的结果能否经过审核后反哺知识库？

GBrain 提供检索和知识组织能力，但不应该直接拥有组织发布权，也不应该替应用侧作出 Permission 或 Approval 决策。

在应用侧的正确位置

应用侧通过 Codex 和 Qoder 执行任务，因此 GBrain 最适合放在应用侧后面：

Agent Chat UI
      ↓
应用侧
  ├── Workspace / Revision / Permission
  ├── GBrain Adapter
  ├── Session Pin
  ├── Approval
  └── Evidence / Audit
      ↓
Codex / Qoder Provider

这样做有三个好处：

Provider 不需要分别理解 GBrain、Sirchmunk 和 Understand Anything。
应用侧可以先做 Workspace、Revision 和权限过滤。
GBrain 不可用时，可以降级为无知识检索，不阻断 Agent 主流程。

当前 MVP 的具体行为是：

将 Bun 和固定版本的 GBrain 一起打进桌面应用。
用户不需要安装 Bun、GBrain 或 Postgres。
使用本地 PGLite 保存 GBrain brain。
每个 Agent Turn 开始前最多检索 5 条知识。
结果通过只读上下文注入 Codex 或 Qoder。
检索超时约 8 秒时自动降级。
每条结果生成 gbrain:// Citation。

这是一个很重要的工程原则：GBrain 增强 Agent，但不应该成为 Agent 执行的单点故障。

从零搭建 GBrain 的实践顺序

第一步：确定事实源

不要一开始就把所有文件都导进去。先选择高价值、相对稳定的内容：

docs/specs/
docs/adr/
CONTEXT.md
核心 README

代码仓库可以接入，但需要区分“团队长期知识”和“当前 Raw Files”。变化很快的源码，更适合作为当前 Turn 的上下文或通过专门的 Code Search 读取。

第二步：给 Source 补 Metadata

至少保留这些字段：

{
  "source": "example-repository",
  "workspace": "example-workspace",
  "revision": "git-sha-or-asset-digest",
  "scope": "team",
  "path": "docs/specs/architecture.md",
  "updatedAt": "2026-07-22T12:00:00Z"
}

没有 Metadata 的索引，很快会变成一个无法解释、无法隔离、无法清理的文本仓库。

第三步：先实现可解释检索

第一版建议从 FTS/BM25 开始，因为它快、便宜、结果可解释。先确保：

能命中精确领域词。
能返回 Source 和 Citation。
能按 Revision 过滤。
没有结果时能明确返回空。

再根据评测结果加入 Embedding，而不是为了“看起来先进”一开始就堆完整检索栈。

第四步：把检索结果包装成 Evidence

不要把原始搜索结果直接拼接给模型。建议统一成：

{
  "content": "Overlay 不修改基础 Revision……",
  "source": "example-workspace-spec",
  "citation": "gbrain://default/example-workspace-spec",
  "revision": "workspace-revision-digest",
  "score": 0.99,
  "retrievedAt": "2026-07-22T12:00:00Z"
}

这样 LLM 得到的是可治理的上下文，而不是一堆没有身份的文本。

第五步：建立拒答和降级策略

知识系统必须允许三个结果：

1
2
3

命中可靠 Evidence → 基于证据回答
命中不足 → 明确说明依据不足
GBrain 不可用 → 降级执行，并记录诊断信息

最危险的状态是“没有命中，但模型假装命中了”。因此 Prompt 和 Adapter 都应该要求：没有 Citation 的关键结论不得伪装成团队事实。

如何验证 GBrain 是否真的有效

不要只看界面显示“已连接”。至少做四组测试。

正向命中

1
2
3

只根据当前 Workspace 的本地知识回答：
Projection、Overlay、Workspace Revision 三者有什么区别？
每条关键结论附上 gbrain:// Citation。

检查定义是否正确、Citation 是否存在、来源是否能回溯。

负向拒答

1 2	当前应用已上线的云端 Control Plane 域名是什么？如果知识库没有可靠证据，请回答不知道。

如果知识库没有这个事实，系统应该拒答或声明依据不足。

A/B 对照

同一批问题分别在 GBrain 开启和关闭时运行，比较：

正确率
Citation 覆盖率
幻觉率
首 token 延迟和总延迟
Agent 是否减少了重复探索

版本隔离

修改一份 Spec，建立新 Revision，再查询旧 Session 和新 Session。旧 Session 不应该突然看到新版本，新 Session 也不应该读取旧索引冒充当前知识。

生产化时最容易踩的坑

把数据库当成事实源

GBrain database、FTS index、Vector index 都应该是可重建的派生实现。跨云端和本地同步时，同步版本化 Knowledge Asset，不要粗暴复制数据库文件。

把执行结果直接写回 Wiki

一次 Agent 执行产生的 Log、Diff、测试结果属于 Execution Evidence。它不能未经审核就变成团队当前事实。

正确的闭环是：

Execution Evidence
  → Knowledge Draft
  → Citation / Conflict Check
  → Review Gate
  → Published Knowledge

把三个工具都暴露给 Provider

GBrain、Sirchmunk、Understand Anything 可以各自擅长不同问题，但不应该让 Codex 或 Qoder 自己决定调用哪一个。应该由 Host 做意图路由：

问题	默认能力
团队 Spec、ADR、长期知识	GBrain
当前变化很快的 Raw Files	Sirchmunk / File Search
代码结构、调用关系、Diff Impact	Understand Anything / Code Graph

最终 Provider 只看到统一的 Knowledge Context 契约。

要不要用 / 我的判断框架

GBrain 值得使用，但不要把它当成“装上就拥有团队记忆”的黑盒。

我的落地顺序是：

先接入高价值事实源
→ 先用 FTS/BM25 验证精确检索
→ 补 Evidence 和 Citation
→ 再加入 Vector Search
→ 关系稳定后再建 Graph
→ 最后补权限、Revision、冲突和审核

对应用侧来说，GBrain 的第一目标不是回答所有问题，而是让 Agent 在执行前拿到当前 Workspace 可用、来源明确、版本一致的知识。

如果它能让 Agent 少猜一次、少重复读一次 Spec、少改错一次代码，并且能解释“为什么这么做”，那它就已经从一个搜索工具变成了真正有价值的 Knowledge Plane。

从 FTS、BM25 到 LLM Wiki：把 RAG 知识检索讲明白

2026-07-22T15:20:00.000Z

我最近在一个 Agent 应用里接入 GBrain，连续遇到几个看起来很像、实际分工完全不同的词：RAG、FTS、BM25、Vector Search、GraphRAG、LLM Wiki、Evidence。

一开始我也容易把它们理解成一条“越来越高级的产品线”：RAG 是基础，GraphRAG 是升级，LLM Wiki 是终局。这个理解不准确。它们分别描述的是检索方式、数据结构、工程系统和知识治理方法，不能简单排成一条替代关系。

一句话总结

RAG 是“让 LLM 回答前先查资料”的工作流；FTS 和 BM25 是关键词检索与排序；Vector Search 是语义检索；GraphRAG 是利用实体和关系回答关联问题；LLM Wiki 是围绕事实源、Evidence、Revision 和引用建立的一套知识工程系统。

换句话说：

1	事实源 → 索引/图谱 → 检索 → Evidence → LLM 回答 → Citation

其中，FTS、BM25、Vector Search、Graph Search 都可以是“检索”这一层的实现。LLM Wiki 负责把这条链路治理起来。

先从 RAG 说起

RAG 是 Retrieval-Augmented Generation，中文通常叫“检索增强生成”。它不是某个数据库，也不是某个 UI 产品，而是一种回答流程：

用户问题
  ↓
检索相关资料
  ↓
把资料放进 Prompt
  ↓
LLM 基于资料生成答案

普通 LLM 只能依赖训练数据和当前对话上下文。RAG 让它在回答之前访问外部知识，因此适合项目代码、团队规范、内部文档、实时数据等场景。

RAG 最重要的不是“把文档塞给模型”，而是检索到正确的上下文。检索错了，LLM 可能会非常自信地基于错误资料回答；检索不到，模型又会回到自己的先验知识，产生幻觉。

所以 RAG 的核心指标通常不是模型有多大，而是：

Recall：应该找到的资料有没有找到？
Precision：找到的资料是不是确实相关？
Groundedness：回答是否真的被检索结果支撑？
Citation：用户能不能回到原始证据？

FTS：全文搜索是什么

FTS 是 Full-Text Search，也就是全文搜索。

普通字符串搜索更像 grep：在文件里找一段文本。FTS 会先把文档分词、建立索引，再快速查找包含查询词的文档或 chunk。

例如查询：

1	Projection Overlay Workspace Revision

FTS 会寻找包含这些词的文档片段。它特别适合搜索：

类名、函数名、变量名
错误码和配置项
技术术语
产品名和领域词
精确的 API 名称

FTS 的特点是“看词”，不真正理解语义。因此“Revision 是什么”和“Revision 的定义”未必会得到同样好的结果，中文自然语言问题也可能因为分词和语言配置而召回不稳定。

BM25：给搜索结果排序

FTS 负责找候选结果，BM25 负责判断谁更相关。

BM25 是 Best Matching 25，一种经典的关键词相关性排序算法。它会综合考虑：

查询词是否出现在文档中
查询词出现了多少次
这个词是不是稀有词
文档长度是否过长

可以把它理解成：

1 2	FTS：哪些文档包含这些词？ BM25：包含这些词的文档，谁最值得排在前面？

BM25 不理解“意思”，但它对代码和技术术语非常实用。搜索 Workspace Revision 时，BM25 往往比纯向量相似度更可靠，因为向量模型可能把一些语义相近但并不包含这个精确标识符的文本排得很前。

Vector Search：按语义找内容

Vector Search 会用 Embedding Model 把问题和文档转换成向量，再比较它们在向量空间中的距离。

例如下面几个问题的关键词不完全相同，但语义接近：

1
2
3

Revision 是什么？
一个 Workspace 的版本如何确定？
工作区如何固定一组可信资产？

纯 FTS 可能认为它们差异很大；Vector Search 有机会把它们召回到同一组文档。

但 Vector Search 也不是万能的。它可能忽略精确术语、混淆相似概念，还可能把“相关但不适用”的内容排到前面。因此工程上更常见的是 Hybrid Search：

1	Hybrid Search = FTS/BM25 + Vector Search + Metadata Filter

当前的 GBrain MVP 先使用 FTS，原因很务实：本地部署简单、依赖少、可解释，而且对项目里的英文领域术语已经有效。后续再加入 Embedding，解决中文自然语言和同义表达的召回问题。

GraphRAG：回答关系问题

GraphRAG 不是“把所有 RAG 都换成图数据库”，而是把知识表达成实体和关系：

Workspace Revision ──固定──> Asset Version
Overlay ──叠加于──> Revision
Projection ──生成自──> Revision
Evidence ──支撑──> Claim

当用户问的是“某个词是什么”时，FTS 或 Vector Search 通常已经够用；当用户问的是“几个对象之间有什么关系”“这条结论依赖哪些事实”“修改某个事实会影响什么”时，图结构就更有价值。

GraphRAG 的优势是关系可追踪、路径可解释，适合架构依赖、权限关系、组织知识、实体关联和影响分析。代价是数据建模和维护成本更高，图谱抽取也可能引入错误关系。

LLM Wiki 到底是什么

LLM Wiki 更像一个知识工程系统，而不只是一个检索算法。它通常包含：

Fact Sources：事实源，例如代码仓库、语雀文档、钉钉文档、ADR、会议纪要。
Ingestion：把事实源同步、解析、切块和建立索引。
Retrieval：用 FTS、BM25、Vector Search 或 Graph Search 找资料。
Evidence：检索出来、可以支撑某个结论的证据片段。
Citation：证据的可回溯引用地址。
Revision：事实在某个时间点的版本和有效范围。
Governance：处理冲突、过期、权限和审核。

因此，LLM Wiki 的关键问题不是“模型能不能回答”，而是：

这条回答依据的事实是什么？事实来自哪里？什么时候有效？谁能修改？

这就是它和简单 RAG 的差异。简单 RAG 重点解决“找一些相关文本”；LLM Wiki 还要解决“哪些文本可信、如何引用、冲突怎么办、知识怎么演进”。

Evidence 为什么重要

Evidence 可以翻译成“证据”，但在知识系统里它不是随便一段上下文，而是能够支撑某个 Claim 的可定位事实。

例如：

1
2
3

Claim：Projection 不是真实事实源，而是可重建的派生视图。
Evidence：架构文档中的 Projection 定义段落。
Citation：gbrain://default/example-workspace-spec

没有 Evidence，LLM 只是“说得像”；有 Evidence 和 Citation，回答才具备审计能力。

在这个 Agent 应用里，我希望每一个关键回答都能回答三个问题：

依据是哪条 Evidence？
来源是哪一个事实源？
如果事实发生 Revision，当前回答是否仍然有效？

什么时候用什么

问题类型	优先技术	原因
查函数名、错误码、配置项	FTS + BM25	精确词匹配可靠、速度快
用自然语言找相似说明	Vector Search	能处理同义表达和语义相近问题
同时兼顾术语和语义	Hybrid Search	工程上最常见的综合方案
查询实体之间的关系	GraphRAG	关系和路径可解释
要求回答可引用、可审计、可演进	LLM Wiki	需要 Evidence、Citation、Revision 和治理
当前阶段	FTS/BM25 + Evidence	先解决本地、可解释、低依赖的知识接入

不建议一开始就上完整 GraphRAG。知识量还小、关系还没稳定时，先把事实源、分块、检索、引用和版本做好，收益更高。

应用侧的落地顺序

我现在采用的顺序是：

本地事实源
  ↓
GBrain 索引
  ↓
FTS/BM25 检索
  ↓
Evidence + Citation
  ↓
应用侧注入 Agent Turn
  ↓
Codex / Qoder 生成或执行

后续按实际问题升级：

第一阶段：FTS/BM25，确保精确术语能找到
第二阶段：Embedding，提升中文和语义召回
第三阶段：Hybrid Search，结合关键词与向量
第四阶段：对稳定实体建立关系图
第五阶段：补齐 Revision、权限、冲突和审核

验证效果时，不要只看“回答听起来不错”。至少要测四件事：命中率、证据准确率、引用覆盖率、额外延迟。尤其要做反向问题：知识库没有答案时，系统能不能明确说不知道，而不是编造一个答案。

要不要用 / 我的判断框架

我的判断很简单：

只有精确技术词：先用 FTS + BM25。
用户问题表达多样：加入 Vector Search。
问题核心是实体关系：再加入 GraphRAG。
团队需要长期维护、追责和协作：建设 LLM Wiki。

LLM Wiki 不是 RAG 的“替代品”，而是把 RAG 变成可维护知识基础设施的一种方式。GraphRAG 也不是必选终点，它只是关系型问题的一种强力检索手段。

对应用侧来说，最重要的不是把所有名词都装进去，而是先让每次 Agent 执行都能拿到可信、可引用、与当前 Revision 对齐的 Evidence。知识系统的价值，最终体现在它能不能让 Agent 少猜一次、少改错一次、少重复问团队一次。

GBrain、Sirchmunk、Understand Anything 怎么搭配：Agent 知识基础设施的三层实践

2026-07-21T18:00:00.000Z

最近在设计一个 Agent Host 的知识架构时，我连续遇到了三个名字：GBrain、Sirchmunk 和 Understand Anything。

它们都宣称能让 Agent 更懂知识、更懂文件或更懂代码，功能列表里也都有 Search、Knowledge、Graph、MCP。第一眼很容易把它们排成一条升级路线：普通 RAG 不够，就上 Graph；Graph 还不够，就做 LLM Wiki；最后找一个“大而全”的项目把其他方案全部替代。

但我真正把场景拆开后发现，这个思路的问题很大。团队维护的 Spec、正在变化的本地 Diff、函数之间的调用关系，本来就是三种不同的数据。硬塞进同一个检索范式，最终往往不是架构统一，而是让一个组件承担它不擅长的工作。

这篇文章记录我目前的判断：三者分别适合什么，什么时候组合，以及为什么第一版不应该一次性把它们全部接入。

一句话总结

GBrain 负责沉淀长期知识，Sirchmunk 负责探索实时原始数据，Understand Anything 负责理解代码结构。它们不是相互替代的升级关系，而是 Knowledge Plane、Raw Context Search 和 Code Intelligence 三个不同层次。

如果只能先选一个，我会以 GBrain 作为知识底座；Sirchmunk 和 Understand Anything 都等真实瓶颈出现后，再作为 Adapter 接入。

先把三个项目放回各自的问题里

项目	核心问题	最适合的数据	典型输出
GBrain	怎样让知识长期积累、关联并被 Agent 稳定使用	Wiki、Spec、ADR、研究结论、团队知识	页面、Citation、Hybrid Search、Graph、综合回答
Sirchmunk	怎样直接从快速变化的原始数据里找到有效证据	本地文件、日志、临时文档、未提交内容	Evidence Snippet、Knowledge Cluster、实时回答
Understand Anything	怎样理解代码库的结构和影响范围	Repository、函数、类、Import、Call、Diff	Code Graph、Domain Flow、Diff Impact、Guided Tour

三个项目都能“搜索”，但搜索对象和目标不同。

搜索一篇 ADR 的结论，核心是语义召回和 Citation；搜索刚生成的构建日志，核心是不用等待重新建索引；回答“修改这个接口会影响哪些模块”，核心是调用和依赖关系。把它们都叫 RAG，会掩盖真正的工程差异。

GBrain：团队和 Agent 的长期知识底座

GBrain 更接近一个完整的 Agent Brain：Markdown Brain Repo 保存长期知识，检索层组合 Keyword、Vector、RRF 和 Graph Signal，查询层既能返回原始结果，也能生成带 Citation 的综合回答和知识缺口分析。

它同时提供两种有吸引力的部署形态：

场景	引擎
个人、本地、零服务部署	PGLite
团队共享、大规模、多机器	Postgres + pgvector

这对桌面 Agent 产品很合适：云端可以维护团队 Brain，本地可以维护当前 Workspace 的 Brain，Agent 在断网时仍然能查询已经同步的知识。

更重要的是，GBrain 覆盖了我最初理解的 LLM Wiki 核心能力：知识不是永远停留在原始 Chunk，而是被编译为可读、可链接、可持续维护的页面。查询产生的新结论也可以继续积累，而不是随着 Chat Session 消失。

不过这里有一个关键边界：GBrain 是知识引擎，不应该自动成为业务系统的权限和发布中心。

在企业或团队场景里，我仍然需要外层系统负责：

哪个 Knowledge Version 已经发布；
当前 Workspace 能访问哪些知识；
哪些页面经过 Owner 审核；
哪个 Session 固定了哪个 Revision；
查询和执行是否需要进入 Audit。

因此，我更愿意把 GBrain 放在 Knowledge Plane，把版本、签名、权限和审计留给宿主系统。

Sirchmunk：不预建索引，直接探索 Raw Data

Sirchmunk 的价值不在于又实现了一套 Vector RAG，而是它选择了另一条路径：直接面对 Raw Data 做 Indexless Agentic Search。

它通过 Grep Retriever、关键词级联和 Monte Carlo Evidence Sampling，从原始文件里定位相关区域，再让 LLM 综合为 Knowledge Cluster。官方提供 FAST、DEEP 和 FILENAME_ONLY 等模式，也提供 MCP，适合直接挂到 Agent 上。

这个设计特别适合快速变化的数据：

未提交 Diff
临时日志
构建输出
诊断文件
刚下载的大型原始资料

这些内容如果每改一次就重新 Embedding、重新构图，维护成本可能比检索收益还高。Sirchmunk 的思路是先搜索当前真相，再决定哪些结论值得沉淀。

但它不适合直接接管正式团队知识。一次 Agentic Search 得到的 Knowledge Cluster，仍然需要回答：来源是什么、是否过期、是否和正式 Spec 冲突、谁审核过。我的处理方式是把 Sirchmunk 的结果当作当前任务上下文；需要长期复用时，先转成 Knowledge Draft，再进入审核和发布。

Understand Anything：代码不是普通文档

Understand Anything 解决的是另一类问题：Agent 能读到代码，却缺少整个 Repository 的结构认识。

它使用 Tree-sitter 和多 Agent Pipeline 提取 File、Function、Class、Dependency 等节点与关系，生成可交互 Knowledge Graph，并提供 Architecture Layer、Domain Flow、Diff Impact、Guided Tour 等视图。它还能分析 Karpathy 风格的 LLM Wiki，把显式 Wikilink 和隐式知识关系可视化。

这和把源代码切 Chunk 做 Vector Search 有本质区别。

假设我问：

修改 PermissionBroker 的返回结构，会影响哪些 Workflow、Adapter 和 UI？

向量检索能找到“语义相似”的文件，但它不能保证遍历真实 Import、Call 和 Type Dependency。Code Graph 的价值就在于把这类结构事实显式化。

Understand Anything 的输出也不应该被理解为第二份代码事实源。代码仍然以 Git Revision 为准，Graph 是可重建 Projection。只要这一点守住，它很适合作为 Repository Knowledge 的生产器，把代码结构结果继续交给 GBrain 做长期查询和关联。

正确组合：一个底座，两个按需 Adapter

我目前采用的组合关系是：

团队 Spec / ADR / Workflow ────────┐
                                   │
Repository Revision ─ Understand Anything
                                   │
                                   ▼
                              GBrain Cloud
                                   │
                         发布版本化 Knowledge
                                   │
                                   ▼
                              GBrain Local
                                   ▲
当前 Workspace / Diff ─ Sirchmunk ┘
                                   │
                                   ▼
                              Coding Agent

但这张图容易产生一个误解：Sirchmunk 的结果不是默认全部写入 GBrain。更准确的运行逻辑是：

正式知识优先查询 GBrain；
问题涉及当前未提交内容时，查询 Sirchmunk；
问题涉及调用链和 Diff Impact 时，查询 Understand Anything；
多个结果由宿主系统合并，并保留各自 Citation；
只有经过验证和审核的稳定结论，才进入 GBrain 的正式页面。

统一接口可以很小：

type ContextIntent =
  | "knowledge"
  | "raw-files"
  | "code-graph"
  | "auto";

interface ContextQuery {
  workspace: string;
  revision: string;
  query: string;
  intent: ContextIntent;
}

interface ContextResult {
  engine: "gbrain" | "sirchmunk" | "understand-anything";
  content: string;
  citation: string;
  digest: string;
}

Agent 不需要知道三套引擎的数据库、进程和权限模型，只需要调用宿主系统暴露的 knowledge.search、workspace.search 和 code.graph_query。

云端和本地应该怎样分工

我不赞成“所有知识都在云端”或“所有知识都只在本地”这两种极端方案。

云端适合维护：

团队 Spec、ADR、Workflow 和 Skill；
已发布 Repository Revision 的稳定分析结果；
Owner Review 后的 Wiki 页面；
跨团队共享检索和正式 Knowledge Version。

本地适合维护：

当前 Workspace；
未提交 Diff；
本地 Overlay；
当前 Session 固定的 Knowledge Revision；
不能默认上传的代码、日志和执行结果。

同步的也不应该是数据库文件，而应该是版本化资产：

Cloud Knowledge
  → Asset Version + Digest + Signature
  → Local Verify
  → Materialize Local Brain
  → Build Index
  → Atomic Activate Revision

这样才能做到离线、回滚和可复现。如果 Agent 每次都读云端的“最新知识”，同一个长 Session 前后可能得到不同结论，审计和复现都会失去基础。

Execution Evidence 不等于 Wiki Citation

在讨论这套系统时，我反复看到 Evidence 这个词，但它不是 LLM Wiki 独有的核心概念。

概念	含义
Source	原始材料
Citation	结论引用的具体位置
Provenance	知识经历了哪些加工和审核
Execution Evidence	Agent 的动作是否真的成功

例如“测试已经通过”只是一句 Agent Message；真正的 Execution Evidence 应该包含命令、退出码、测试数量、时间和对应 Revision。

Evidence 可以反哺知识，但不能自动成为知识：

测试结果 / Diff / Commit
        ↓
Execution Evidence
        ↓
提炼稳定机制
        ↓
Knowledge Draft
        ↓
Review + Citation
        ↓
正式 Wiki

这个边界非常重要。否则一次错误推理或偶发现象写进团队 Wiki，之后所有 Agent 都会把它当成事实。

第一版不要三件套全上

从工程投入看，三者同时接入意味着：

三套生命周期和升级策略；
三套索引或持久化；
多种查询结果的融合与去重；
更多 API Key、Sidecar 和供应链风险；
更复杂的 Revision、Permission 和 Citation 映射。

因此我的实施顺序是：

阶段	目标
Phase 1	GBrain Local 跑通团队 Knowledge 到 Agent 的查询闭环
Phase 2	增加 GBrain Cloud、Knowledge Draft、Review 和版本发布
Phase 3	Raw Files 实时检索成为瓶颈时接 Sirchmunk
Phase 4	调用链、依赖和 Diff Impact 成为瓶颈时接 Understand Anything

甚至在小型 Repository 中，rg + LSP + 架构文档 可能已经够用。是否引入新组件，应该由真实任务的 Recall、Precision、Latency、Token 和维护成本决定，而不是由功能列表决定。

要不要用 / 我的判断框架

我的结论不是“三个都值得上”，而是分三档：

值得上：GBrain

如果 Agent 需要跨 Session 积累团队知识，需要云端共享、本地离线和长期 Citation，GBrain 值得作为 Knowledge Plane 验证。它覆盖了 LLM Wiki、Hybrid RAG、Graph 和 Synthesis，能先建立一条完整主链路。

可以再等：Sirchmunk

如果当前 rg、FTS 或 GBrain 对 Workspace Raw Files 已经够快，Sirchmunk 可以先不接。等频繁重建索引、临时大文件和日志检索真的影响体验，再引入它的 Indexless Search。

重点关注：Understand Anything

如果产品的核心价值包含 Repository Onboarding、影响分析和架构理解，Understand Anything 很有价值；如果只是让 Coding Agent 修改几个文件，它可能暂时是过度设计。

最终我用一句话约束自己的选型：

先建立一个稳定知识底座，再用真实任务证明是否需要实时搜索器和代码图谱；不要为了“看起来完整”一次性维护三套基础设施。

这也是我从前端工程走向 Agent / AI Infra 后越来越强烈的体会：真正的架构能力，不是把最多的组件画进图里，而是知道每个组件何时应该缺席。

修复中文输入法按回车误发送：React Chat Composer 的 IME 事件陷阱

2026-07-21T11:35:00.000Z

最近在做 Agentic Chat 时，我遇到一个看似很小、实际会直接破坏输入体验的问题：使用中文输入法输入英文片段，候选框还开着，此时按 Enter 本来只是确认候选词，Composer 却把这次 Enter 当成了“发送消息”。

这个 Bug 特别容易被纯英文开发环境漏掉。按钮点击正常，英文键盘正常，甚至多数浏览器里只判断 isComposing 也能正常；但到了 macOS 输入法和 WebKit 的真实事件时序，消息仍然会提前发出去。

一句话总结

Chat Composer 不能把所有 Enter 都视为提交。发送前至少要同时检查 KeyboardEvent.isComposing、IME 的兼容值 keyCode === 229，并处理部分 WebKit 环境中 compositionend 早于提交用 keydown 到达的时序差异。

最终的判断不是“用户有没有按 Enter”，而是：这次 Enter 的语义是确认输入法候选，还是提交已经完成的消息？

先理解 IME：输入框里的文字不一定已经提交

IME 是 Input Method Editor。中文拼音、日文假名、韩文以及部分语音和手写输入，并不是每按一个键就立即产生最终字符，而是先进入一个 composition session：

compositionstart
  ↓
compositionupdate × N
  ↓
compositionend

在这个阶段，输入框中看起来已经出现了 auto，但它可能仍处于输入法的组合态。用户按 Enter 的意图是从候选列表中选择 automation，不是把整条聊天消息发给 Agent。

浏览器通过 KeyboardEvent.isComposing 暴露当前按键是否发生在 composition session 内。MDN 对它的定义很直接：在 compositionstart 之后、compositionend 之前触发的键盘事件，该值应为 true。

因此最基础的发送逻辑应该是：

function handleKeyDown(event: React.KeyboardEvent) {
  if (event.key !== "Enter") return;

  if (event.nativeEvent.isComposing) {
    return;
  }

  if (!event.shiftKey) {
    event.preventDefault();
    sendMessage();
  }
}

这能解决大多数标准事件顺序，但还不够。

为什么只判断 isComposing 仍然会误发送

问题出在浏览器和操作系统对 composition 与 keyboard event 的排序并不完全一致。

理想情况下，用户按 Enter 确认候选时，keydown 发生在 composition 结束之前：

1
2
3

keydown Enter (isComposing: true)
compositionend
keyup Enter

此时 isComposing 足以阻止发送。

但 WebKit 在 macOS 上长期存在另一种时序：

1
2
3

compositionend
keydown Enter (isComposing: false)
keyup Enter

对业务代码来说，收到 keydown 时 composition 已经结束，isComposing 自然变成 false。如果发送条件只是：

1	event.key === "Enter" && !event.nativeEvent.isComposing

这次用于确认候选的 Enter 就会穿透保护，直接提交表单。

WebKit Bugzilla 的相关记录明确提到：macOS 上接受 IME 输入的 Enter 可能在 compositionend 之后才以 keydown 到达，因此 isComposing === false。这不是 React 自己的状态问题，而是底层事件顺序已经让上层失去了原始语义。

keyCode 229 为什么仍然有价值

keyCode 已经是 legacy API，正常键盘处理应该优先使用 event.key 和 event.code。但 UI Events 规范仍然保留了一条与 IME 直接相关的兼容规则：如果 keydown 正由 Input Method Editor 处理，返回值是 229。

因此，IME guard 中使用 keyCode === 229 不是把所有键盘逻辑退回旧 API，而是把它作为一个窄范围的兼容信号：

const nativeEvent = event.nativeEvent;

const isImeEvent =
  nativeEvent.isComposing ||
  nativeEvent.keyCode === 229;

它能覆盖一部分 isComposing 不可靠、但浏览器仍把按键标记为 IME processing 的情况。

不过它仍不是完整答案。有些环境可能在 compositionend 后把这次 Enter 暴露成普通的 keyCode 13。因此还需要记录组件自己的 composition 状态，并给刚结束的 composition 留一个很短的保护窗口。

稳健修复：三层 IME Guard

我最后采用了三层判断：

组件内的 composingRef，记录 compositionstart 到 compositionend。
浏览器提供的 nativeEvent.isComposing 与 keyCode === 229。
compositionend 后一个短暂的 grace period，挡住乱序到达的 Enter。

React 实现如下：

import { useRef } from "react";

export function ChatComposer() {
  const composing = useRef(false);
  const compositionJustEnded = useRef(false);
  const compositionTimer = useRef<ReturnType<typeof setTimeout> | null>(null);

  return (
    <textarea
      onCompositionStart={() => {
        composing.current = true;
        compositionJustEnded.current = false;

        if (compositionTimer.current) {
          clearTimeout(compositionTimer.current);
        }
      }}
      onCompositionEnd={() => {
        composing.current = false;
        compositionJustEnded.current = true;

        if (compositionTimer.current) {
          clearTimeout(compositionTimer.current);
        }

        compositionTimer.current = setTimeout(() => {
          compositionJustEnded.current = false;
        }, 80);
      }}
      onKeyDown={(event) => {
        const nativeEvent = event.nativeEvent;

        const isImeEnter =
          event.key === "Enter" &&
          (
            composing.current ||
            compositionJustEnded.current ||
            nativeEvent.isComposing ||
            nativeEvent.keyCode === 229
          );

        if (isImeEnter) {
          event.preventDefault();
          return;
        }

        if (event.key === "Enter" && !event.shiftKey) {
          event.preventDefault();
          sendMessage();
        }
      }}
    />
  );
}

这里的 80ms 不是协议常量，而是一个很窄的事件时序缓冲。它只保护 composition 刚结束后紧随而来的 Enter，不会改变用户完成输入后再次按 Enter 发送的习惯。如果产品允许调整发送方式，提供 Cmd/Ctrl + Enter 模式仍然是很好的补充，但不能用它掩盖默认 Enter 模式的 IME Bug。

在 assistant-ui 里应该在哪里拦截

应用侧使用 assistant-ui 的 ComposerPrimitive.Input。这类 headless primitive 通常已经包含基础的 isComposing 判断，但宿主应用仍可能需要为特定桌面 WebView、输入法和系统版本补充 guard。

关键是把处理放在 Composer 输入边界，而不是 sendMessage() 里事后猜测：

<ComposerPrimitive.Input
  onCompositionStart={handleCompositionStart}
  onCompositionEnd={handleCompositionEnd}
  onKeyDown={handleComposerKeyDown}
/>

原因有三点：

输入组件最接近真实 DOM event，能拿到 composition 信息。
在这里 preventDefault()，可以阻止 primitive 后续的 submit handler。
发送函数不应该知道用户使用了拼音、假名还是物理键盘，它只负责提交已确认的消息。

如果组件库会组合用户传入的 handler 与内部 handler，需要确认组合顺序及 defaultPrevented 语义。理想行为是外部 handler 先运行；外部调用 preventDefault() 后，内部 Enter-submit 不再执行。

不要只测“中文能不能输入”

这个 Bug 的验收重点是事件语义，而不是文字最终有没有出现在 textarea。

至少覆盖下面这些用例：

场景	期望结果
中文输入法候选打开，按 Enter	确认候选，不发送
日文输入法候选打开，按 Enter	确认候选，不发送
composition 完成后再次按 Enter	发送一次
普通英文输入后按 Enter	发送一次
`Shift + Enter`	插入换行，不发送
composition 中按 `Shift + Enter`	交给输入法，不发送
连续快速确认候选	不丢字、不重复发送
Agent 正在运行时输入	遵守 queue / steer 策略，不被 IME 改写

自动化测试可以构造 compositionStart、keyDown、compositionEnd 序列，但不要只相信 JSDOM。IME 与 WebView 的差异发生在浏览器事件层，至少还需要一轮 macOS Safari / WKWebView、Chrome，以及 Windows 中文输入法的真机测试。

下面是一个简化的测试意图：

fireEvent.compositionStart(textarea);
fireEvent.keyDown(textarea, {
  key: "Enter",
  keyCode: 229,
  isComposing: true,
});
fireEvent.compositionEnd(textarea);

expect(sendMessage).not.toHaveBeenCalled();

await waitForCompositionGuardToExpire();
fireEvent.keyDown(textarea, { key: "Enter", keyCode: 13 });

expect(sendMessage).toHaveBeenCalledTimes(1);

更通用的工程判断：快捷键不能脱离输入状态

这次问题不只属于聊天框。搜索框、命令面板、评论框、AI Prompt Composer、表格快捷编辑都可能把 Enter、Escape、方向键当作产品命令，但这些按键在 IME、自动补全、mention、slash command 和 accessibility 输入中还有另一层语义。

我现在会把键盘处理按下面的优先级设计：

IME composition
  → suggestion / mention / command popover
  → editor-local behavior
  → product shortcut
  → global shortcut

越靠前的输入状态，越应该先消费事件。全局快捷键不能因为“捕获到了 Enter”就认为用户要求执行命令。

这也是 Agentic Chat 与普通表单的差别：Composer 一旦误发送，触发的不只是一次 HTTP 请求，而可能是一个拥有文件、终端或外部系统权限的 Agent run。输入确认和任务执行之间必须有可靠边界。

要不要用 / 我的判断框架

值得上： 所有 Enter-to-submit 的 Chat、搜索、评论和命令输入框，都应该至少判断 isComposing；面向 macOS Safari、WKWebView 或 Tauri WebView 的产品，再补 keyCode 229 和 composition 结束保护。

可以再等： 如果产品强制点击按钮发送，或者唯一快捷键是明确的 Cmd/Ctrl + Enter，grace period 的优先级可以降低，但 composition 状态仍应被组件正确维护。

重点关注： 不要把 80ms 当成神奇数字散落在多个组件里。把 IME guard 封装成 hook 或 Composer adapter，集中处理计时器清理、平台差异和测试。未来替换编辑器或 UI primitive 时，也只需要重新验证这一层。

参考资料：

Provider Pattern：在 Agent Ops App 中统一 Codex、Qoder 与未来执行引擎

2026-07-21T06:30:00.000Z

最近在做一个 Agent Ops 桌面应用时，我先接了 Codex，下一步要接 Qoder，后面还可能接 Hermes。最开始这看起来只是一个 SDK 集成问题：再写一个 QoderClient，在 UI 里加个选择框就结束了。

但我很快发现，真正的问题不是“怎么调用第二个 Agent”，而是：当第三个、第四个执行引擎出现时，业务代码是否还需要跟着修改？

如果 UI 认识 thread/start，Workflow 判断 provider === 'qoder'，Session 直接拿 Provider Session ID 当主键，那么所谓“多 Provider”只是把多个私有协议揉进了同一个应用。接入得越多，系统越难维护。

我最后采用的是 Provider Pattern：把 Codex、Qoder、Hermes 看作可替换的执行引擎，用 Adapter 吸收协议差异，再通过 Registry、Capability 和 Session Pin 建立稳定的 Agent Ops 控制面。

一句话总结

Provider 是能力提供者，Adapter 是把能力接入统一契约的翻译层。Agent Ops App 应该拥有 Session、权限、Workflow 和审计，Provider 只拥有原生执行上下文；新增 Provider 时，理想状态是只增加 Adapter 和 Projection，而不是修改整条业务链路。

Provider 不是 Adapter

这两个词经常同时出现，也最容易混在一起。

概念	回答的问题	在 Agent Ops App 中的例子
Provider	谁提供执行能力	Codex、Qoder、Hermes
Provider Adapter	怎样接入这个 Provider	`CodexAdapter`、`QoderAdapter`
Provider Contract	App 要求所有 Provider 遵守什么接口	`createSession`、`runTurn`、`interrupt`
Provider Registry	运行时选择哪个 Adapter	`providerId → ProviderAdapter`

Provider 更接近一种架构角色，不是 GoF 设计模式。支付系统里的支付宝、微信支付是 Payment Provider；对象存储里的 S3、OSS、GCS 是 Storage Provider；Agent Ops 中的 Codex、Qoder、Hermes就是 Agent Provider。

Adapter 则是经典的 Adapter Pattern。它不负责推理，只负责把 Provider 的原生接口翻译成 App 的统一语义。

Agent Ops App
    ↓ Provider Contract
Provider Adapter
    ↓ Provider Native API
Codex / Qoder / Hermes

一句话区分：Provider 是被接入的对象，Adapter 是负责接入它的代码。

为什么不能在 UI 里直接判断 Provider

Codex 和 Qoder 都支持会话、流式输出和中断，但原生语义并不相同。

Codex App Server 可能使用：

thread/start
turn/start
turn/interrupt
item/agentMessage/delta

Qoder Agent SDK 则可能使用：

query()
options.sessionId
options.resume
query.interrupt()
stream_event

最直接的实现是在业务层写分支：

if (provider === 'codex') {
  await codex.startTurn(...);
} else if (provider === 'qoder') {
  await qoder.query(...);
}

这个写法在第二个 Provider 时成本很低，但它会迅速扩散到 UI、Session、Workflow、Approval、错误处理和测试。最终每个功能都要知道所有 Provider 的私有细节。

更稳妥的做法是先定义 Provider-neutral Contract：

type ProviderId = string;

interface ProviderAdapter {
  readonly id: ProviderId;

  probe(): Promise<ProviderDescriptor>;
  createSession(input: CreateSessionInput): Promise<string>;
  runTurn(
    input: RunTurnInput,
    emit: (event: AgentEvent) => void,
  ): Promise<void>;
  interrupt(providerSessionId: string): Promise<void>;
  close(providerSessionId: string): Promise<void>;
}

业务层只处理 AgentEvent：

type AgentEvent =
  | { type: 'turn.started'; turnId: string }
  | { type: 'message.delta'; text: string }
  | { type: 'tool.started'; tool: string }
  | { type: 'tool.completed'; tool: string; status: string }
  | { type: 'turn.completed' }
  | { type: 'session.failed'; message: string };

Codex 的 item/agentMessage/delta 和 Qoder 的 stream_event 都在 Adapter 内转换成 message.delta。上层不需要知道事件来自哪个 SDK。

Provider Pattern 实际组合了哪些模式

我把它叫作 Provider Pattern，但严格来说，它是一组模式的组合。

模式	解决的问题
Adapter Pattern	把不同 Provider 的接口和事件翻译成统一语义
Strategy Pattern	在运行时选择 Codex、Qoder 或 Hermes 执行任务
Registry Pattern	管理 `providerId` 与 Adapter 实例的映射
Ports and Adapters	让 Agent Ops 领域层不依赖外部 SDK
Anti-Corruption Layer	阻止 Provider 私有概念污染业务模型

Registry 的实现可以很小：

class ProviderRegistry {
  #adapters = new Map<string, ProviderAdapter>();

  constructor(adapters: ProviderAdapter[]) {
    for (const adapter of adapters) {
      if (this.#adapters.has(adapter.id)) {
        throw new Error(`Duplicate provider: ${adapter.id}`);
      }
      this.#adapters.set(adapter.id, adapter);
    }
  }

  get(providerId: string): ProviderAdapter {
    const adapter = this.#adapters.get(providerId);
    if (!adapter) throw new Error(`Unsupported provider: ${providerId}`);
    return adapter;
  }
}

这里我刻意把 ProviderId 定义成 string，而不是：

1	type ProviderId = 'codex' \| 'qoder';

封闭 union 在小型应用里类型体验很好，但对可扩展 Provider 系统意味着每接入一个 Provider 都要修改公共契约。真正的约束应该来自 Registry、配置校验和兼容矩阵，而不是把已知 Provider 列表写死在领域类型中。

Session 必须由 Agent Ops App 持有

这是多 Provider 架构里最重要的所有权边界。

Codex 有 Thread ID，Qoder 有 Session ID，Hermes 未来也会有自己的会话标识。但这些 ID 都不能直接成为 Agent Ops 的业务主键。

应用 Session ID
    ├── providerId: qoder
    ├── providerVersion: 1.0.47
    ├── adapterVersion: 0.1.0
    ├── workspaceRevisionId
    ├── permissionProfileId
    └── providerSessionId:

原因很直接：

Provider Session ID 的格式和生命周期不受 App 控制。
Provider 可能删除、迁移或无法恢复原生 Session。
Workflow、审批和审计需要跨 Provider 保持统一身份。
用户切换 Provider 时，业务记录不能跟着换主键。

因此 Agent Ops Session 是权威记录，Provider Session 只是外部引用。

创建 Session 时还应该固定 Provider 版本、Workspace Revision、权限配置和资产投影版本。否则同一个 Session 运行到一半，系统 CLI 自动升级，前后两次 Turn 可能已经不再遵守相同协议。

Desktop、CLI、SDK 和 Adapter 要分层

Codex 和 Qoder 都可能同时提供 Desktop、CLI 和 SDK，这几个东西不能混为一谈。

层级	作用	是否进入 Agent Runtime 主链路
Desktop	用户直接操作的产品界面	否，适合 Open/Handoff
CLI	可执行 Runtime、登录和诊断入口	是
SDK	管理 CLI、协议和结构化事件	优先使用
Adapter	Agent Ops 内部的转换边界	是

桌面端不适合成为 Agent Ops 的执行依赖：它的生命周期由用户控制，可能自动升级，窗口里的会话也不等于 Agent Ops Session。

真正的调用链应该是：

Agent Ops App
  → Provider Adapter
  → SDK / CLI structured protocol
  → Provider Runtime

Desktop 只负责用户交接：

1
2
3

Open in Codex
Open in Qoder
Handoff current task

Runtime Resolver：版本稳定性的关键一层

只写 spawn('codex') 或 spawn('qodercli') 很方便，但这会默认依赖用户 PATH 中的版本。系统 CLI 一旦自动升级，Adapter 可能在用户毫无感知的情况下失效。

我倾向于给每个 Provider 增加 Runtime Resolver：

type ResolvedProviderRuntime = {
  executablePath: string;
  source: 'override' | 'bundled' | 'system';
  version: string;
};

解析顺序是：

1
2
3

显式环境变量覆盖
  → App/SDK bundled runtime
  → 系统 CLI 开发兜底

以 Qoder 为例，SDK 可能锁定一个经过验证的 bundled CLI，系统新版本只用于登录和人工诊断。Codex 也应该采用相同思路，只是在真正随 App 分发 binary 前，还需要确认授权、签名、公证和登录态复用边界。

版本不能只在日志里打印一次，而要进入 Session Pin 和 Compatibility Manifest：

{
  "provider": "qoder",
  "providerRuntimeVersion": "1.0.47",
  "providerAdapterVersion": "0.1.0",
  "sidecarProtocolVersion": 1,
  "capabilities": ["stream", "interrupt", "resume"]
}

Capability 不要伪装成统一能力

统一接口不代表所有 Provider 的能力完全相同。

有些 Provider 支持 resume，有些只支持重建上下文；有些能 fork Session，有些能提供结构化 Tool Approval；有些只有文本流，没有稳定的 Tool Event。

错误做法是用文本解析或业务分支伪造能力。正确做法是让 probe() 返回 Capability：

type ProviderDescriptor = {
  id: string;
  version: string;
  status: 'ready' | 'unavailable';
  capabilities: Array<
    'stream' | 'interrupt' | 'resume' | 'fork' | 'toolApproval'
  >;
};

上层根据数据决定是否展示“恢复”“Fork”或“审批”按钮，而不是判断 Provider 名称：

1
2
3

if (provider.capabilities.includes('resume')) {
  showResumeAction();
}

这能让未来 Hermes 接入时只声明真实能力，不必模仿 Codex 或 Qoder。

权限不能交给 Provider 自己决定

Provider Adapter 解决的是兼容性，不自动解决安全问题。

即使 Codex、Qoder 都有自己的 Permission Mode，Agent Ops App 仍然必须持有上层权限策略。Provider 原生审批只能进一步收紧，不能放宽组织策略已经拒绝的动作。

我当前采用的 MVP 边界是：

原生 Core 验证 Workspace Grant。
Core 生成有界的只读 Workspace Context。
Adapter 禁用 Provider 原生文件、Shell、网络和 MCP 副作用工具。
Provider 只负责推理与流式输出。
未来开放 Tool 时，必须先转换成 Canonical Tool Request，再由 Core 执行。

这能避免一个常见误区：UI 看起来使用了 read-only，但 Provider Runtime 实际继承了完整用户目录和 Shell 权限。

新增 Hermes 时应该改多少代码

一个健康的 Provider 架构应该用“新增代码”扩展，而不是到处修改旧代码。

理想的 Hermes 接入包括：

hermes-adapter.ts
hermes-runtime-resolver.ts
hermes-materializer.ts
hermes-contract-fixtures/

然后注册：

new ProviderRegistry([
  new CodexAdapter(),
  new QoderAdapter(),
  new HermesAdapter(),
]);

不应该修改：

Agent Chat 的事件渲染逻辑
Workflow Run 状态机
Approval 数据模型
Audit Event 格式
Asset 的事实源模型

如果新增 Hermes 还需要修改以上模块，说明 Provider 私有语义已经穿透 Adapter 边界。

最容易踩的五个坑

1. 把 Provider 和 Model 混为一谈

Provider 是执行系统，Model 只是其中一个配置。Qoder 可能动态选择多个 Model，Codex 也可能切换推理配置。Session 应固定 Provider，Model 是否固定则由产品策略决定。

2. 一个 Adapter 只保存一个全局 Session

类似 #threadId 的单例字段只能支持一个会话。生产实现应按 Provider Session ID 管理进程、事件监听器、Pending Request 和取消状态。

3. UI 出现 Provider 私有事件

一旦 UI 直接处理 item/agentMessage/delta，Adapter 就已经失去意义。Provider 原生类型应该止步于 Adapter 文件。

4. 依赖系统 CLI 自动升级

开发机上很方便，生产环境中却是协议漂移来源。至少要做 Runtime Resolver、版本 Probe、兼容范围校验和 Session Pin。

5. 为了“统一”而虚构能力

不支持 resume 就明确返回不支持，不要偷偷重放 Prompt 并告诉上层“恢复成功”。能力差异应该由数据表达，不能靠语义造假。

要不要用 Provider Pattern：我的判断框架

如果应用只调用一个稳定 API，且没有切换执行引擎的计划，直接封装一个 Client 往往足够，不必为了模式而模式。

但满足下面任意三项时，我会尽早建立 Provider 边界：

已经有两个以上执行引擎。
Provider 拥有不同的 Session 和事件协议。
SDK/CLI 更新频繁，需要独立兼容测试。
UI、Workflow、审批和审计必须保持统一。
需要运行时选择 Provider。
未来可能接入企业内部或自托管 Agent Runtime。

对 Agent Ops App 来说，我的结论是“值得上”。因为它的核心价值不是把某个 Agent 包一层 UI，而是拥有跨 Provider 的控制面：资产、权限、Session、Workflow、Evidence 和审计。

Provider 可以替换，Adapter 可以升级，CLI 可以演进；但 Agent Ops App 的领域模型和治理边界必须保持稳定。做到这一点以后，Codex、Qoder、Hermes 才真正只是可替换的执行引擎，而不是反过来绑架整个产品架构。

Sidecar 边车模式：给本地 Agent 划出一间受控执行舱

2026-07-18T10:30:00.000Z

最近在设计一个本地 Agent Host 时，我遇到了一个很典型的架构冲突：桌面应用希望用 Tauri 的原生层建立稳定的本地可信边界，但 Codex、Qoder、MCP 等 Agent 能力又高度依赖 Node.js 与 TypeScript 生态。

把所有能力塞进一个进程当然最快，但代价也很直接：UI、数据库、凭据、文件系统和 Agent Runtime 混成一团，一个 Provider SDK 崩溃或越权，就可能拖垮整个应用。

我最后采用的是 Sidecar，也就是边车模式。

一句话总结

Sidecar 是由主应用启动和监管、通过明确协议协作的独立辅助进程。它适合隔离异构运行时和高风险能力，但进程隔离不等于安全沙箱，权限仍然必须由主应用强制执行。

Sidecar 到底是什么

这个名字来自摩托车边车：主车决定方向，边车跟随主车一起运行，但拥有独立空间。

放到软件架构里，主应用负责生命周期、权限和核心状态；Sidecar 负责一组边界清晰的辅助能力。实现上它通常就是子进程、独立容器或本地服务，但“子进程”是操作系统概念，“Sidecar”描述的是架构角色。

概念	关注点
Child Process	谁创建进程、PID、stdin/stdout、退出码
Sidecar	为什么拆分、职责边界、协议、权限和故障治理
Microservice	独立部署、网络边界、团队和服务自治
Plugin	可扩展能力，可能仍与宿主运行在同一进程

一个进程只有在具备“随主应用交付、由主应用监管、职责受限、通过协议协作”这些特征时，才更接近 Sidecar，而不只是随手启动的脚本。

为什么本地 Agent 特别适合边车模式

本地 Agent 天然跨越多个技术栈：桌面壳需要窗口、更新、Keychain 和系统权限；Agent Runtime 需要 Provider SDK、MCP、工具调用和流式事件；数据层又需要 SQLite、索引与事务一致性。

如果全部交给 Node 主进程，接入生态很舒服，但 Node 同时成了窗口、数据库、凭据和执行权限的可信根。反过来，如果全部重写为原生实现，首版成本高，Provider SDK 更新也要长期追赶。

边车提供了第三条路：原生 Core 保留控制权，Node Agent Host 只承载 Node 生态中不可替代的部分。

组件	主要职责	不应该拥有的能力
React Webview	UI、交互、无特权状态	原始 Secret、任意 Shell、数据库连接
原生 Core	权限、生命周期、更新、审计、IPC 校验	Provider 业务实现细节
原生数据服务	SQLite、同步、索引、事务	UI 和 Provider Token
Node Sidecar	Codex/Qoder SDK、ACP、MCP Adapter	最终授权决策、主数据库所有权

一次 Agent 请求怎样穿过边界

Sidecar 设计真正难的不是“把 Node 启起来”，而是定义每一步谁有权做什么。

典型链路是：

Webview 提交声明式任务，例如“在当前 workspace 分析这组文件”。
原生 Core 校验调用来源、workspace scope、参数长度、组织策略和用户审批。
Core 给任务生成受限 capability profile，再通过版本化 IPC 发给 Sidecar。
Sidecar 调用 Provider SDK，并把 token、tool call、progress 和 error 作为有序事件流返回。
Core 对事件做审计和脱敏，再通过 Tauri Channel 推给 UI。

低频控制请求可以用 NDJSON framed protocol；高频流也可以使用本地 Socket。关键不是选哪一种传输，而是必须有 protocolVersion、requestId、事件序号、取消语义、超时和背压。

不要把协议消息和普通 stdout 日志混在一起。否则一条调试日志就可能破坏 framing，让控制面变得不可预测。

进程隔离不等于安全沙箱

这是 Sidecar 最容易被误解的地方。

把 Node 放进独立进程，只解决了部分故障隔离：Sidecar 崩溃后可以单独拉起，内存泄漏不会直接污染原生 Core。但如果它继承了完整环境变量、用户目录和网络权限，它仍然能够读取不该读取的文件，或者绕过审批直接访问外部服务。

因此我会把原生 Core 设计为 Permission Broker：

Frontend 不能直接启动 Sidecar，只能提交声明式 Intent。
Sidecar 只接收完成当前任务所需的最小输入，不接收完整配置和全部 Secret。
文件、进程、网络和命令权限按 workspace 与任务 scope 收紧。
启动时校验 binary hash、签名、协议版本和 capability profile。
所有高风险工具调用经过 Core 审批与审计，Sidecar 不能自己给自己授权。

Tauri capability 主要约束 Webview → 原生 Core，不会自动沙箱已经启动的原生插件或 Node Sidecar。把平台 ACL 当成完整安全方案，是一个危险的边界误判。

生命周期治理比启动命令重要

生产级 Sidecar 至少需要处理下面这些状态：

1 2	starting → handshaking → ready → busy → draining → stopped ↘ degraded → restarting

主应用需要回答：握手失败怎么办？任务执行中 Sidecar 崩溃是否重试？取消后怎样确保子进程和工具进程都被清理？升级时协议不兼容如何阻止启动？连续崩溃是否进入熔断？

我的判断是：Sidecar 可以独立重启，但主数据库事务和资产 revision 不能由它持有。否则所谓故障隔离只是把崩溃位置挪了一个进程，数据一致性仍被绑在 Agent Runtime 上。

什么时候值得用，什么时候不要用

Sidecar 值得用：

必须复用另一种语言或运行时的成熟 SDK。
任务容易崩溃、泄漏内存或需要单独限流。
能力涉及 Shell、网络、第三方插件等较高风险边界。
希望 Agent Runtime 可单独重启，而不影响 UI 和核心数据。

不值得用：

只是几个纯函数或轻量业务逻辑。
无法定义稳定协议，双方需要共享大量可变内存状态。
团队没有能力维护打包、签名、IPC、可观测性和崩溃恢复。
拆出去以后仍给 Sidecar 全部文件、网络、凭据和数据库权限。

最后一种尤其常见：付出了多进程复杂度，却没有获得真实边界。

我的判断框架

我不会因为“Sidecar 是一种成熟模式”就默认采用它。我的判断顺序是：

是否存在必须保留的异构运行时或高风险能力？
能否用小而稳定的协议描述输入、输出和事件？
宿主能否真正掌握权限、生命周期和核心数据？
故障隔离收益是否大于打包、签名和调试成本？

四个问题都能给出明确答案，Sidecar 才是架构；否则它只是多启动了一个进程。

对本地 Agent 来说，我倾向于采用“可信 Core + 受控 Sidecar”：Core 决定谁能做什么，Sidecar 负责把某一种运行时的能力做到最好。边车可以执行任务，但不能决定规则。

我把AI生图做成了工程能力：better-imagegen的实战与判断

2026-07-15T08:30:00.000Z

最近两周，我密集地用 AI 生成了几类差异很大的视觉资产：产品竞赛主视觉、Agent 角色分身、18px 菜单栏帧动画、macOS App Icon、动态壁纸、错误状态插画，以及博客和社交媒体封面。

一开始我以为问题只是“怎么写出更好的 Prompt”。做得越多，我越确定：Prompt 只是视觉交付链路里的一小段。真正费判断的是选什么工作流、怎样约束输出、如何处理透明通道、怎么保证角色一致、如何把一张图交付成前端和客户端能直接使用的资产。

这也是我持续完善 better-imagegen 的原因。它不是收藏 Prompt 的目录，而是一个面向 Agent 的视觉生成 skill：输入目标和交付类型，输出可以进入工程的图片、帧序列、元数据和平台产物。

一句话总结

AI 生图要从“抽卡”走向工程化，关键不是把 Prompt 写得更长，而是把类型路由、规格约束、模型回退、后处理、质量检查和产物封装变成稳定流程。

我最近到底拿它做了什么

我没有只扫描某一次会话，而是回看了近期 Codex 会话、项目资产和 better-imagegen 自身的 Git 演进。真实需求大致分成这些类型：

场景	难点	最终沉淀的能力
博客与社交媒体封面	需要快速建立视觉主题，并为标题预留稳定空间	`portrait / cover` 构图规范、留白与裁切约束
产品竞赛主视觉	大量准确中文、角色和产品界面同屏	背景生图 + HTML/CSS 精确排字
Agent 角色与分身	已有角色换皮、动作变化，但必须保留身份特征	image edit、reference image、角色一致性
Argos 菜单栏动画	18px 仍需可识别，透明背景，循环不能跳帧	sprite sheet、拆帧、manifest、真实尺寸验收
macOS App Icon	透明源图不等于可交付 `.icns`	alpha 检查、留白、iconset、`.icns` 打包
动态壁纸	不是两张图轮播，而是系统可识别的动态资产	4K 帧、HEIC、`apple_desktop:apr`
产品错误态	角色要表达故障，但不能像通用红色警告图标	场景化角色物料、站点色彩适配

这些案例让我看到：同样叫“生成一张图”，背后的交付合同完全不同。

第一条经验：先判断产物类型，再选择模型

很多生图流程第一步就是选模型。我现在反过来：先问最终文件要被谁消费。

如果是博客封面，我需要 16:9、WebP、合适的压缩质量和可放标题的负空间；如果是 macOS 菜单栏图标，我关心的是透明通道、18px 下的轮廓和帧间稳定性；如果是动态壁纸，最终消费者是 macOS，不是浏览器，因此交付物应该是符合系统要求的 HEIC，而不是两张漂亮的 PNG。

目前 better-imagegen 把常见任务拆成独立工作流：

类型	默认交付重点
Portrait / Cover	构图、人物、情绪、WebP 压缩
Text Poster	生图负责视觉底板，HTML/CSS 负责准确文字
Logo / Icon	透明背景、alpha 边缘、缩小后的可读性
macOS App Icon	squircle、安全区、iconset、`.icns`
Static Wallpaper	4K、PNG、桌面图标可读区域
Dynamic Wallpaper	多状态帧、HEIC、系统元数据
Sprite Loop	精灵图、编号帧、GIF 预览、manifest
Image Edit	参考图输入、身份保持、局部变化

这样做的好处是：Agent 不再把所有需求都塞进同一个“万能生图 Prompt”。

第二条经验：Prompt 应该是一份 Asset Contract

一个可执行的 Prompt，不是堆“高级感、电影感、8K、杰作”这类形容词，而是写清一份资产合同。

我现在通常至少写这 6 类信息：

1. Subject：画面里必须有什么
2. Composition：主体位置、留白、视线方向、帧网格
3. Style：摄影、插画、像素、产品渲染等视觉语言
4. Delivery context：博客、社交媒体、菜单栏、桌面、App Icon、头像
5. Hard constraints：人数、透明背景、尺寸、帧数、角色身份
6. Negative constraints：不要文字、不要 Logo、不要水印、不要额外肢体

例如做 Argos 菜单栏猫头鹰动画时，“可爱猫头鹰”远远不够。真正决定可用性的约束是：横向精灵图、固定 6 帧、每格等宽、透明背景、暖橙色轮廓、18px 仍能辨识、首尾动作连续。

模型生成的是像素，但 Prompt 描述的是运行时约束。

第三条经验：准确文字不要交给图像模型

产品竞赛主视觉是一个典型转折点。画面里既要角色、空间感和产品 UI，又要大量准确中文。直接让模型把所有文字画出来，结果通常是：中文错字、字重漂移、对齐不可控，修改一个词还要整张图重抽。

我最后采用的流程是：

AI 生成无文字视觉底板
        ↓
HTML / CSS 叠加真实文本和品牌组件
        ↓
浏览器渲染并截图
        ↓
WebP 压缩 + 尺寸检查

这个方法没有“纯 AI 生图”那么浪漫，但交付质量稳定得多。图像模型负责它擅长的氛围、材质和构图；浏览器负责它擅长的字体、排版和像素级控制。

这其实很符合我从前端转 Agent 的经验：不要让一个模型承担完整系统里所有职责，边界清晰比单点能力更重要。

第四条经验：角色一致性必须走 Image Edit

在“小界”和“录制小界”的角色设计里，我需要同一角色拥有不同身份和动作：基础小界负责体验治理，录制小界负责根据目标自动探索操作路径并沉淀技能。

如果每次都从文本重新生成，脸型、发型、服装结构和整体年龄感都会漂。更可靠的方法是把现有角色图作为 reference，通过 image edit 只修改服装、姿态、表情或手持物。

我的判断标准很直接：

用户必须认出“还是同一个角色”时，使用 image edit。
只需要同类风格、不要求身份连续时，才用 text-to-image。
角色进入帧动画时，先锁定标准立绘，再做动作变化。

第五条经验：帧动画的验收单位不是大图，而是运行尺寸

我第一次给 Argos 做 RunCat 风格的菜单栏动画，生成的大图看起来不错，放进 macOS 菜单栏却几乎不可见。原因很简单：深色主体、细轮廓和轻微动作，缩到 18px 后全部丢失。

后来我把 sprite loop 的交付定义成了一组工程产物：

sprite-sheet.png        # 原始等分精灵图
frame-01.png ...        # 拆分后的独立帧
preview.gif             # 快速预览循环
manifest.json           # 帧数、尺寸、顺序、时长

并增加了 4 个验收条件：

每个 cell 尺寸完全一致，不能靠肉眼切。
首帧和末帧的姿态能自然衔接。
alpha 通道真实存在，不能用棋盘格“画透明”。
必须在实际运行尺寸验收，而不是只看 512px 预览。

这条经验也适用于头像、favicon、状态图标：缩小后的信息密度，才是最终质量。

第六条经验：一张透明 PNG 还不是 macOS App Icon

macOS App Icon 是另一个很容易被低估的场景。模型能生成一个透明图标，不代表它可以直接放进 Xcode。

稳定流程至少包括：

生成透明源图
  → 检查 alpha 边缘
  → 裁掉异常透明留白
  → 设置视觉安全区
  → 生成 macOS squircle 底板
  → 输出 16 / 32 / 128 / 256 / 512 / 1024 尺寸
  → 组成 .iconset
  → 转换为 .icns

这里模型只完成了“源艺术”。后面的尺寸矩阵和系统封装，才决定它是不是一个可安装的 App Icon。

第七条经验：模型回退不是换个名字重试

better-imagegen 现在默认使用 GPT Image 2，失败后归一化 Prompt 重试一次，再回退到 Gemini，最后才考虑 Doubao。

但 fallback 不是无脑串行，因为不同模型的交付特性不同：

模型	我主要看重的能力	需要注意
GPT Image 2	Prompt 遵循、真实感、复杂构图	偶发超时或拒绝，需要一次规范化重试
Gemini Image	自由尺寸、4K、无水印	适合作为大多数任务的第一回退
Doubao Seedream	普通视觉任务的兜底能力	水印和最小像素面积会影响透明图、精灵图

因此透明 Logo、Icon 和 sprite sheet 不应该回退到一个会破坏 alpha 或网格的模型。Fallback 的目标不是“总能出图”，而是“仍然能交付同一种资产”。

第八条经验：每张图都应该可追溯

最早生成完一张图，我只关心“保存在哪”。当使用频率变高后，这种方式很快失控：不知道用的哪个模型、不知道请求尺寸、分不清生成耗时和后处理、也无法复现一张突然很好的图。

所以我给每个产物增加了同名 JSON 元数据：

{
  "file": "cover.webp",
  "model": "gpt-image-2-all",
  "requested_size": "1536x1024",
  "actual_resolution": "1280x720",
  "generation_time_seconds": 38.8,
  "output_format": "webp",
  "postprocess": "center-cropped to 16:9; WebP quality 78",
  "prompt": "..."
}

元数据看起来是小事，但它让视觉生成从“聊天记录里的偶然结果”变成了可审计的工程产物。

我是怎样把一次成功沉淀成 skill 的

最近有一次生成结果特别好，我第一反应不是只保存图片，而是追问：这次为什么好？哪些步骤可以复用？

我会把过程拆成 4 层：

类型层：这是封面、图标、壁纸还是动画？
Prompt 层：哪些构图和负向约束真正起作用？
后处理层：裁切、透明、压缩、拆帧、系统封装做了什么？
验收层：在真实博客、菜单栏、Dock、网页里效果如何？

然后把稳定部分写进对应 reference，而不是继续依赖我的临场记忆。better-imagegen 最近的演进也基本沿着这条路线：

时间	沉淀内容
7 月 4 日	静态壁纸规格、无损 PNG
7 月 6 日	macOS 动态壁纸、HEIC 元数据、模型扩展
7 月 7 日	默认输出目录、元数据汇报、类型 reference 拆分、Prompt compliance
7 月 9 日	GPT → Gemini → Doubao 的回退链路、文字型竞赛封面流程
7 月 10 日	macOS `.iconset` / `.icns` 工作流

这就是我理解的 Agent skill：不是一段“万能指令”，而是把成功经验变成一套带条件分支、失败处理和交付标准的操作系统。

better-imagegen 的能力边界

它目前很适合：

快速生成产品概念视觉、封面、角色和状态物料。
让 Agent 自主选择图像工作流并完成后处理。
把 sprite、App Icon、壁纸等非单图资产交付到工程。
在多模型之间做有约束的 fallback。
给生成结果补齐规格和元数据。

但它不是 Figma 的替代品，也不会自动解决所有品牌一致性问题。涉及精确排版、复杂 Design System、连续镜头或严格 3D 资产时，仍然需要专业工具和人工判断。

要不要用 / 我的判断框架

我的结论是：如果你每周都有两次以上视觉生成需求，值得把生图从 Prompt 升级成 skill。

判断是否值得工程化，我看 3 个问题：

问题	是	否
同类资产会重复出现吗？	建立类型 reference	临时生成即可
输出要进入代码、客户端或内容系统吗？	增加后处理和验收	保存图片即可
失败会影响交付节奏吗？	增加模型回退和元数据	手动重试即可

对我来说，better-imagegen 最大的价值不是“让我更会画图”，而是让视觉生成开始拥有软件工程的确定性：知道该走哪条路径、失败时如何退、最后交付什么文件、下一次怎样复现。

从前端转向 Agent / AI Infra 后，我越来越相信一件事：超级个体的优势不在于每件事都亲手做，而在于能把判断沉淀成系统，再让 Agent 把执行力拉满。 better-imagegen 就是这套思路在视觉生成上的一次实践。

青山湖设计风格的诞生记

2026-07-15T08:30:00.000Z

7 月初，我在做 Argos 的界面时遇到一个很典型的问题：功能已经成形，页面也不算难看，但它没有自己的气质。

当时最容易走的路，是让 Agent 套一套现成的 macOS glass 风格，再选一组低饱和蓝绿色。但这种做法只能得到“正确的现代界面”，得不到一个能被记住、还能持续指导后续决策的产品视觉。

我最后给 Codex 的要求只有一句：

你知道临安青山湖水上森林吗？产品配色和调性从这个景区的主要元素蒸馏。

后面十天里，这句话从一个模糊意象，逐渐变成 Argos 的 dashboard、menu bar、floating island 和灵动卡，又迁移到“小界”的 Web 工作台，最后沉淀成一份 Agent 可以直接执行的 DESIGN.md。

这篇文章不是介绍一组颜色，而是复盘一套设计语言是怎样在我和 Agent 的连续反馈中长出来的。

一句话总结

青山湖设计风格的核心，不是把界面染成绿色，而是把青山湖的自然层次翻译成数字产品的职责分工：雾白负责空间与材质，湖水青负责操作，水杉绿负责状态，青山灰蓝负责信息层级，晨光金只负责极少量高光。

它真正成型的标志也不是有了一份 palette，而是面对一个新组件时，我们开始能稳定回答三个问题：什么该突出、什么该退后、什么绝不能出现。

起点：我需要的不是“好看”，而是一个母题

AI 很擅长生成看起来完成度很高的界面，但如果提示词只有“高级、简洁、科技感”，结果通常会收敛到几种熟悉套路：高饱和蓝紫渐变、纯黑科技背景、玻璃卡片层层嵌套、发光描边和胶囊按钮。

这些元素单独都没有错，问题是它们没有产品身份。换一个 Logo，仍然可以属于任何 AI 工具。

青山湖对我有价值，是因为它不是一个抽象形容词，而是一组可以观察、拆解和约束的真实对象：

自然元素	视觉感受	UI 职责
湖面	稳定、清透、有纵深	主操作色、进度、选中态
雾带	柔化边界、制造层次	画布、glass surface、blur
水杉林	垂直、克制、有生命力	成功态、在线态、进度状态
浮萍	有生机但不主导	5% 以内的自然 accent
远山	安静、可靠、低对比	信息色、次级文字、结构层
晨光	稀缺、温暖、有方向	极小面积高光与提醒
湿木与陶土	自然的警示感	error / danger，而不是通用红

这里最重要的动作是“蒸馏”，不是“复刻”。

我不需要在每个页面放一张水上森林背景，也不想把产品做成旅游宣传页。我需要的是把自然景观里的层次关系，映射成界面里的语义关系。

第一版并没有直接成功

有了母题，Agent 很快能生成一组视觉上相关的颜色。但真实界面一跑起来，问题马上暴露。

最早的倾向是把“自然感”理解成更多颜色：湖蓝、青绿、浅金、泥土色同时出现；把“现代感”理解成更多胶囊和渐变；把“氛围感”理解成更大的装饰面积。

它们组合在一起，反而让界面显得花哨。

我在几轮截图反馈里不断删东西：

两个胶囊按钮太突兀，不要求为了“风格”强行使用胶囊。
中间区域颜色太花，应该只从青山湖体系里选一个承担主导职责的颜色。
彩带装饰太长，不能侵入信息区中心。
Header 不是越窄越专业，也不是越宽越大气，要回到统一的页面间距。
组件贴边时，先修尺寸与布局约束，不要用更多装饰掩盖问题。

这段过程让我确认了一件事：设计风格首先是一套删减规则。

如果一套风格只告诉 Agent“可以用什么”，它很快就会把所有特征同时用上。真正能提高输出稳定性的，是同时写清楚“最多用多少”“只能用在哪里”“什么情况下不要用”。

因此后来规范里出现了很多带比例和边界的表达：浮萍绿控制在 5% 以内，晨光金只做边缘光，常规圆角控制在 6–12px，动效只服务状态变化，卡片不能继续嵌套卡片。

雾白成为核心，不只是因为它好看

青山湖风格真正定型，是在做 Argos 灵动卡时。

灵动卡需要接近 macOS 桌面小组件的玻璃质感。最直接的实现是 NSVisualEffectView、系统 material 和 behind-window sampling，但这条路径曾经触发打开即崩。为了稳定性，我们一度把它降级成普通的浅色 panel，结果功能稳定了，气质也一起消失了。

我当时给出的反馈是：

加安全 blur，因为雾白这个是青山湖风格的核心设计元素之一。

这句话推动了一个很关键的技术取舍：保留“雾”的视觉语义，但不恢复高风险的系统采样链路。

最后采用的是纯 SwiftUI 内部绘制：

大面积雾白柔焦带；
左上角雾白 soft blur；
右下角很淡的湖水青 blur；
所有效果裁剪在卡片内部；
不使用 NSVisualEffectView；
不使用 .behindWindow 或 .underWindowBackground。

这次取舍让“雾白”从一个颜色升级成了整个设计体系的基础设施。它既是背景色，也是分层方式；既负责氛围，也负责降低信息噪声；还必须服从稳定性、性能和可读性。

这也是我现在判断视觉方案的一个原则：设计语言不能绕过工程约束，好的设计 token 应该能在安全实现与理想效果之间找到可迁移的中间层。

从色板走向语义系统

经过几轮实战后，青山湖不再是一组零散的 hex，而是逐渐形成了 Seed → Map → Semantic → Alias 的 token 架构。

:root {
  --color-bg-base: #f4f6f1;       /* 暖雾白画布 */
  --color-bg-container: #fbfcfa;  /* 玻璃容器 */
  --color-primary: #3c8f88;       /* 湖水青主操作 */
  --color-text: #183b40;          /* 深湖墨正文 */
  --color-success: #4f8751;       /* 水杉绿 */
  --color-info: #4d7180;          /* 青山灰蓝 */
  --color-warning: #9c782d;       /* 克制晨光金 */
  --color-error: #a95b4b;         /* 雨后陶土 */
}

其中最重要的不是颜色值，而是语义稳定：

lake-teal 永远优先服务主操作，而不是随手给一个装饰图标。
cypress-green 表示完成、在线与健康状态。
dawn-gold 不承担大面积品牌色，只提示稀缺状态。
浅色区域的主文字使用深湖蓝或水杉墨绿，不滥用纯白发光字。
Claude Code 与 Codex 可以有不同 accent，但都必须来自同一景区 palette。

颜色一旦有职责，Agent 的自由度反而更健康。它仍然可以生成新组件，却不必每次重新猜一遍品牌方向。

布局也是青山湖风格的一部分

如果只换颜色，任何设计系统最后都会沦为皮肤。

在 dashboard 的几轮调整里，我逐渐把“青山湖的层次”落实到布局密度和信息结构上：稳定侧栏、清晰控制条、12–16px 卡片内距、20–24px section gap、连续圆角，以及不依赖巨大留白的中高信息密度。

一次 Header 调整很能说明问题。最初品牌名与 Tab 名都挤在左侧，为了显得紧凑又不断压缩高度，最后整个 Header 既窄又别扭。重新排布后，结构变成：

“灵动台”作为产品标识放在上方中间；
当前 Tab 名放在下方左侧；
筛选放在中间；
刷新操作放在右侧；
间距统一回到同一套节奏。

这里没有新增任何“青山湖装饰”，但它比多加一条湖水渐变更符合这套风格。因为自然景观给人的舒适感，本质上也来自前景、中景、远景各自有位置，不互相争抢。

从 Argos 到小界：迁移后才算设计系统

只在一个产品里成立的规则，还只能叫项目风格。

后来我把这套语言迁移到“小界”的 Web 工作台。平台从 SwiftUI 变成 React、Umi、styled-components 和 Tailwind，产品形态也从 macOS menu bar 工具变成 AI 控制台，但核心映射依然成立：

暖雾白作为低噪声 canvas；
湖水青作为唯一主操作色；
水杉绿表达任务完成和运行状态；
青山灰蓝承担信息与次级层次；
glass surface 保持轻量，不做卡片套卡片；
页面维持专业工具需要的中高信息密度；
loading、empty、error 和 success 使用同一套自然语义。

迁移过程中，设计体系又吸收了 Web 产品的新约束：正文默认 14px、工具栏控件 32–36px、桌面优先但窄屏不溢出、动效支持 prefers-reduced-motion，以及资源统一使用 WebP。

最终沉淀出的 DESIGN.md 不再叫某个产品主题，而是更通用的 Jiangnan Landscape Glass Dashboard。它保留青山湖的来源，同时把能力抽象成 AI 控制台、桌面 dashboard、settings、menu bar 和 floating panel 都能复用的设计 brief。

Agent 参与设计，人的价值在哪里

回看这些会话，Agent 承担了大量执行工作：从截图理解问题、搜索现有实现、调整布局、生成 token、修改 SwiftUI/CSS、跑构建和测试，再把经验写进规范。

但方向真正发生变化的节点，几乎都来自人的判断：

“不要泛科技感，要从一个真实地点蒸馏。”
“胶囊很突兀，不必为了统一而强行使用。”
“颜色太花，只选一个承担主导职责。”
“雾白是核心，但不能恢复会崩溃的实现。”
“不要太紧凑，也不要太宽松，回到统一间距。”

这恰好符合我对“超级个体”的理解：AI 把执行速度拉满，人负责建立判断框架。

在 UI 工作里，判断框架不是一句“再高级一点”，而是把模糊审美不断压缩成可验证的约束：颜色比例、组件职责、布局节奏、反例清单、技术安全边界和跨端迁移规则。

当这些规则被写进 DESIGN.md 和项目级 AGENTS.md，审美才从一次性的聊天上下文，变成可以在下一次会话继续生效的工程资产。

我现在怎样定义青山湖设计风格

如果今天再让我用一段话描述它，我会这样写：

以暖雾白和云带灰蓝构成低噪声画布，用轻量半透明材质、连续圆角、柔和边框和克制阴影组织信息；湖水青是唯一主操作色，水杉绿用于成功与进度，浮萍绿只作少量自然活性点缀，晨光金只用于稀缺高光。界面保持专业工具的中高信息密度，不做旅游海报、赛博霓虹、重边框、硬阴影和嵌套卡片。

它的反模式同样明确：

不是贴一张青山湖照片；
不是把所有组件改成青绿色；
不是处处 glassmorphism；
不是用大面积留白制造“高级感”；
不是遇到层级问题就再套一张卡片；
不是牺牲稳定性去追求系统材质效果。

我的判断框架

青山湖风格值得继续用，但不是所有产品都应该用。

值得上：AI 控制台、桌面效率工具、settings、数据 dashboard、menu bar 与 floating panel。这些场景需要稳定、清透、低噪声，又不能完全失去品牌辨识度。

可以再等：强营销 landing page、娱乐化社区、需要极强情绪刺激的消费产品。青山湖的优势是克制，不适合强行承担所有视觉目标。

重点关注：不要让 Agent 把设计系统退化成 palette。每次迁移至少检查四层：语义 token、信息密度、组件形态和 anti-pattern。只换颜色，不算迁移完成。

这套风格的诞生没有一个“设计完成”的瞬间。它更像青山湖早晨的雾：先有模糊的方向，再在一次次实现、崩溃、截图和删改中显出层次。

而我最想保留下来的，也不是某个具体色值，而是这套与 Agent 协作的方法：从真实世界找到母题，用真实产品验证它，用反例收紧边界，最后把判断写成下一次会话仍能执行的规则。

让云雾动起来：聊天界面的分层氛围动画

2026-07-14T12:30:00.000Z

最近给一个体验治理 Agent 的聊天欢迎页补氛围时，我没有再加一张背景大图，而是把「云雾」做成了一个独立的 CSS layer。它在页面里缓慢游移，既让空状态不显得空，又不会干扰输入框、对话气泡和任务状态这些真正需要被看见的内容。

这件事看起来是视觉微调，实际很像前端工程里的控制问题：动画有了不代表体验变好了。云雾的范围、透明度、节奏和层级，只要有一个失控，就会立刻变成一层抢注意力的滤镜。

一句话总结

把背景云雾拆成一个不参与布局的绝对定位 layer，再用两组不同形状、不同节奏的 radial-gradient 和 transform 动画叠加。调参时优先收束可见范围和对比度，而不是继续增加颜色或动画。

先明确它不是内容，而是环境

聊天页的视觉优先级应该很清晰：用户先看到 Agent 在说什么，再看到输入框和建议，最后才感知页面有一点流动感。

所以云雾层需要满足四个约束：

约束	实现选择
不影响交互	`pointer-events: none`
不挤压内容布局	`position: absolute`，不放进正常 flow
永远在内容下方	雾层 `z-index: 0`，内容容器 `z-index: 1`
动画成本可控	只动 `transform` 和 `opacity`

页面结构最终很简单：

"hq-agent-courtyard">
  <div className="hq-courtyard-mist" aria-hidden="true" />
  <div className="hq-courtyard-content">{/* 消息、输入框与任务面板 */}div>

这里的 aria-hidden 也很重要。云雾没有语义，不应该被屏幕阅读器读到，更不该被当成一个可操作元素。

两朵雾，而不是一张渐变背景

一开始用单层大渐变时，效果很像带颜色的蒙版。它有颜色变化，但没有空间关系。

后来我改成 ::before 和 ::after 两层。每层不是一个圆，而是多组椭圆形 radial-gradient 拼出来的非规则云团：左侧留一团偏深的青绿，中部和右侧再放更浅的雾，边缘用很长的透明过渡消掉。

.hq-courtyard-mist {
  position: absolute;
  inset: 5%;
  z-index: 0;
  pointer-events: none;
  opacity: 0.82;
}

.hq-courtyard-mist::before,
.hq-courtyard-mist::after {
  content: '';
  position: absolute;
  inset: 0;
  border-radius: 48% 52% 57% 43% / 44% 49% 51% 56%;
  filter: blur(12px);
  will-change: transform, opacity;
}

.hq-courtyard-mist::before {
  background:
    radial-gradient(ellipse 26% 15% at 16% 22%, rgba(93, 171, 153, 0.5), transparent 78%),
    radial-gradient(ellipse 21% 28% at 29% 32%, rgba(129, 190, 175, 0.4), transparent 78%),
    radial-gradient(ellipse 27% 36% at 65% 72%, rgba(117, 184, 168, 0.5), transparent 76%);
}

真正起作用的不是某一个色值，而是三层关系：

形状不规则：每个 gradient 的大小和位置不同，避免出现一眼可识别的圆形光斑。
透明边界足够长：色彩在 76% 到 82% 之间才消失，云团会更像在空气里扩散。
两层方向相反：一层从左下缓慢移动到右上，另一层反向移动，页面才有轻微的深度感。

动画只负责“活着”，不负责表演

这个页面不是营销首页，云雾不能用大幅位移抢镜。我把两层动画拉成 6 秒和 8 秒，并使用 alternate 往返：不需要额外做首尾拼接，也不会出现明显的瞬间跳回。

@keyframes jiangnan-mist-cloud-a {
  from {
    transform: translate3d(-22%, 10%, 0) scale(0.82);
    opacity: 0.36;
  }
  to {
    transform: translate3d(22%, -10%, 0) scale(1.18);
    opacity: 0.92;
  }
}

@keyframes jiangnan-mist-cloud-b {
  from {
    transform: translate3d(24%, -12%, 0) scale(1.2);
    opacity: 0.84;
  }
  to {
    transform: translate3d(-24%, 12%, 0) scale(0.8);
    opacity: 0.3;
  }
}

这里我刻意只用了 transform 和 opacity。它们通常可以由 compositor 处理，不会每一帧触发布局计算。相比直接动画化 top、left、width 或一串渐变参数，这更适合常驻的背景效果。

最重要的一次调整：从“铺满”改成“收束”

第一版我把雾层设成 inset: -16%。直觉是让云团从视口外飘进来，避免边缘被裁切。结果实际看下来，页面整个区域都被雾覆盖：背景有了，但聊天卡片的玻璃质感反而被稀释，输入框周边也不够干净。

最终调整是：

/* 初版：云雾覆盖过大，内容区域缺少留白 */
/* inset: -16%; */

/* 调整后：云团收进安全区，边缘交给页面底色 */
inset: 5%;
opacity: 0.82;

这个改动的收益比继续调色更大：

调整	视觉结果
雾层缩到安全区	四周恢复呼吸感，卡片边界更清楚
保留多层 gradient	中央不再是一张平淡的浅绿底图
降低极亮区域的覆盖面积	输入框和欢迎气泡成为稳定焦点
两层保持反向漂移	页面依然有“空气在流动”的感觉

这也是我这次最有价值的判断：背景动画的优化，大多数时候不是“做得更多”，而是“让它少出现一点”。

玻璃组件和云雾层如何配合

云雾只是底景，玻璃卡片负责把内容从底景里提出来。欢迎气泡和输入框用了半透明背景、细边框、内高光和 backdrop-filter。这样背景雾会隐约透进组件，但文本所在区域仍有足够对比度。

可以把它理解成三层：

1
2
3

底色与页面纹理
  -> 缓慢漂移的云雾 layer
    -> 玻璃卡片与真实内容

如果没有中间那层云雾，玻璃很容易显得只是半透明白色；如果没有最上层的玻璃容器，雾又会让文字显得发灰。它们应当一起设计，而不是各自加一个效果。

我会怎样验证这类背景动画

这类效果很容易陷入“截图看着不错”的错觉，我通常按下面三件事检查：

停在任意时刻都成立：截取动画中的任意一帧，内容层级都清楚，不能依赖某个刚好干净的瞬间。
连续看 10 秒不烦：如果能明确察觉云团在左右移动，节奏已经太强；正确的感觉应该是视线离开后才意识到页面在呼吸。
性能面板没有持续压力：确认动画只涉及合成友好的属性，并在低性能设备上观察掉帧和 GPU 占用。

此外，生产页面还应该补一条 prefers-reduced-motion，让用户可以在系统层面关闭或静止这类环境动画。审美不能覆盖可访问性偏好。

要不要用 / 我的判断框架

值得上：空状态、Agent 对话页、工作台欢迎页这类内容稀疏但需要建立产品情绪的界面。用低对比、慢节奏的环境层补足空间。
可以再等：数据密集的列表、表格和监控台。那里信息密度已经够高，背景动画多半只会制造噪声。
重点关注：优先控制雾层范围、透明度和内容对比度，再讨论颜色和动画曲线。层级错了，再漂亮的 gradient 也是干扰。

从前端转向 Agent 和 AI Infra 后，我越来越在意这类“非功能性”的交互细节。Agent 的能力决定它能做什么，界面的节奏决定用户是否愿意把注意力交给它。云雾当然不会让模型更聪明，但它可以让等待、输入和阅读这几个瞬间更安静一些。

从高频轮询到按需刷新：本地 Agent 数据面的性能优化

2026-07-13T04:30:00.000Z

我最近在做 Owlet：一个本地读取 Claude Code 与 Codex 会话记录、展示 Token 和实时活动的 macOS 工具。它的难点不在「能不能把日志读出来」，而在「数据源有任何变化时，怎样既足够快，又不把本地 app 刷成一个持续工作的轮询器」。

这轮改动之后，我更确定一件事：本地 Agent 工具的性能优化，重点不是把某一次 query 跑快，而是把刷新语义、数据计算和 UI 发布拆开管理。

一句话总结

把“任何事件都立即全量刷新”改成“合并请求、分层计算、变化才发布”。这样既能保住 Agent 正在运行时的及时性，也能显著减少重复 SQLite 查询和无意义的 SwiftUI invalidation。

问题不在单个刷新，而在刷新会叠加

Owlet 的数据链路大致是：

Claude Code JSONL / Codex SQLite
  -> Adapter 增量同步
  -> 本地 analytics SQLite
  -> AppState
  -> 菜单栏 / 灵动岛 / 灵动卡 / 仪表盘

一开始最直觉的实现是：文件变化一次，触发一次 refresh()；刷新完成后，重新计算所有 analytics 并发布所有 @Published 状态。

它的问题会在真实使用里迅速放大：一次 Agent 工作往往连续写入多个文件；文件观察、定时活跃探测、用户手动刷新又可能同时到达。若每次都启动完整链路，就会出现 3 类浪费：

浪费	结果
同一时段的多次刷新互相重叠	重复读取来源、争用本地数据库
小组件只需要今日 Token，却计算了完整 dashboard	菜单栏和灵动岛被大查询拖慢
查询结果没有变化，仍重新赋值	SwiftUI 继续 diff、重绘所有依赖视图

这不是 CPU 单点热点，而是一个典型的控制面问题：系统没有定义好“下一次刷新是否仍有必要”。

第一层：合并请求，但不丢掉尾部更新

普通 debounce 的常见写法是：每次事件都取消旧 Task，重新等待几秒再刷新。它能降频，但有一个隐蔽问题：如果刷新正在进行时又来了事件，新事件很容易被 isRefreshing 直接丢掉。

Owlet 改成了单个长期持有的 auto-refresh Task，加一个 pendingAutoRefresh 标记：

private func scheduleAutoRefresh() {
    pendingAutoRefresh = true
    guard autoRefreshTask == nil else { return }

    autoRefreshTask = Task { @MainActor [weak self] in
        while !Task.isCancelled {
            try? await Task.sleep(for: .milliseconds(200))
            guard let self, !Task.isCancelled else { return }

            self.pendingAutoRefresh = false
            let didRefresh = await self.refresh(preloadAnalytics: .none)
            if !didRefresh { self.pendingAutoRefresh = true }

            guard self.pendingAutoRefresh == false else { continue }
            self.autoRefreshTask = nil
            return
        }
    }
}

这里的关键不是 200 ms 这个数字，而是状态机：

任意事件只负责标记“有新工作”。
已经有 refresh worker 时，不再创建第二个 worker。
worker 刷新后再次检查标记；期间来的新事件会自然形成下一轮。

这相当于一个 trailing-edge coalescer。它允许短时间内的事件合并，又保证「刷新期间发生的最后一次变化」不会消失。对本地日志同步来说，这比无限取消的 debounce 更符合数据正确性。

第二层：不同 surface，不要共用一份重型刷新

菜单栏、灵动岛和灵动卡真正关心的是“现在有没有活跃 Agent、今天用了多少 Token”。仪表盘才需要项目分布、模型分布、小时趋势、最近会话等完整数据。

此前这些 UI surface 共用一份 analytics reload，打开菜单栏也可能触发全套 dashboard 查询。优化后把 snapshot 分成两类：

1
2
3

enum AnalyticsReloadScope {
    case none, surface, board, all
}

Scope	计算内容	消费者
`surface`	今日 Token、近 7 日日聚合	菜单栏、灵动岛、灵动卡
`board`	会话、项目、模型、日/小时趋势	灵动台仪表盘、会话页
`all`	两者	首次启动、用户显式刷新

当用户点开菜单栏时，先从已经落到本地 SQLite 的数据快速加载 surface snapshot，再在后台走 adapter 增量同步。用户看到的是立刻可用的旧但可信数据；同步完成后再应用新结果。

这个策略背后的取舍是：本地可观测性 UI 优先 freshness 的连续性，不必执着于每次打开都同步到最新字节。 只要后续同步能很快收敛，体验比“打开后空白等待一次全量链路”好得多。

第三层：查询完成不等于应该发布状态

SwiftUI 的刷新成本不只来自 view body 本身。一个 @Published 数组被重新赋值，会使依赖它的图表、列表、卡片都重新进入 diff。

所以 snapshot 要实现 Equatable，并在主线程发布前做一次值级短路：

private func applyBoardAnalyticsSnapshot(_ snapshot: BoardAnalyticsSnapshot) {
    guard cachedBoardAnalyticsSnapshot != snapshot else { return }
    cachedBoardAnalyticsSnapshot = snapshot

    if totals != snapshot.totals { totals = snapshot.totals }
    if recentSessions != snapshot.recentSessions { recentSessions = snapshot.recentSessions }
    if hourlyUsage != snapshot.hourlyUsage { hourlyUsage = snapshot.hourlyUsage }
    // 其余字段同理
}

这一步很朴素，但它把“数据库读到一个结果”与“UI 需要看到一次新状态”明确区分开了。特别是 3 秒一次的活动探测中，绝大多数轮次的活跃会话并没有变化；这时只要不写回 activeSession，就不会无端唤醒整棵视图树。

再补一层：活跃时快，空闲时慢

Agent 正在工作时，用户在意灵动岛是否实时；空闲时，每秒检查一次只是在浪费电和 I/O。

因此 periodic refresh 采用两档节奏：

1
2
3

检测到活跃 Agent：每 3 秒检查并按需同步
没有活跃 Agent：30 秒才做一次兜底刷新
文件观察事件：立即合并到下一次刷新

文件观察负责绝大多数实时性，低频轮询只负责兜底。这个组合比“纯轮询”可靠，也比“完全相信文件事件”更能应对日志轮转、外部工具写入和观察器偶发失效。

我会怎样验证这类优化

这里有一个容易犯的错：没有 trace 就先宣布“快了 X%”。这次我没有编造一个漂亮数字，而是把验证拆成三个层次：

行为正确性：并发事件不会丢最后一次更新；手动刷新与自动刷新不会并发重入。
数据正确性：没有 delta 时不改 analytics；有 delta 时会重新读取对应 scope。
运行时证据：用 Instruments 观察主线程占用、SwiftUI update 原因，以及菜单栏打开和仪表盘切换时的 SQLite 查询量。

性能优化应该以“减少了哪一类工作”为单位陈述，而不只是看某一次 demo 的体感。

要不要用 / 我的判断框架

如果你在做的是会持续观察本地日志、数据库、文件系统或多个 Agent runtime 的桌面工具，我建议尽早建立这三条边界：

值得上：数据源有 burst 写入，且多个 UI surface 订阅同一份状态。优先做刷新合并和 scope 拆分。
可以再等：只有一个页面、一次刷新只读极少量数据。先保持简单，不要过早拆 Task。
重点关注：每次把新数组重新塞进 @Published 的地方。它往往不是数据变慢的根因，却是界面无故重绘的最后一跳。

对我来说，这也是从前端转向 Agent / AI Infra 时很有意思的一点：真正的性能不是“把某个函数写得更快”，而是替整个系统定义一套更少做无效工作的调度规则。

打包后 Bundle.module 直接崩：一个 SPM app 首启必崩的资源陷阱

2026-07-10T14:30:00.000Z

Owlet 是我用 Claude Code + Codex vibe 出来的常驻 menu-bar app，统计每天 Claude Code 和 Codex 的 Token 用量、排名、实时会话活动。它是个纯 SPM 项目——没有 .xcodeproj，靠脚本 swift build 出可执行文件，再手动组装成 Owlet.app。这个「纯 SPM + 手动打包」的选择很轻量，但也埋了一个坑：这次我收到两份用户 crash report，症状是最吓人的那种——第一次安装，一打开就崩，连界面都没露脸。

更迷惑的是：我自己机器上从来没崩过。开发、构建、swift run，一路顺畅。但用户装上就崩，而且两台完全不同的机器（macOS 26.5 和 26.3.1、不同硬件、不同用户）崩得一模一样。这种「开发机好好的，用户机必崩」的 bug，往往指向同一类问题：运行环境的资源布局，和你开发时不一样。

一句话总结

SwiftPM 会为带资源的 target 自动合成一个 Bundle.module 访问器，它在找不到资源包时不是返回 nil，而是直接 fatalError 崩掉进程。纯 SPM 的 app 手动组装成 .app 后，资源包位置和 .build/ 目录里不一样，Bundle.module 的默认定位逻辑就失效了。开发时它能在可执行文件旁边找到资源包所以不崩，用户首装时找不到就必崩。

崩溃现场：栈顶是一句 fatalError

两份 crash report 关键部分完全一致。信号是 EXC_BREAKPOINT (SIGTRAP)——这不是野指针越界那种 SIGSEGV，而是代码里主动触发的断言/fatalError：

Process:             Owlet [21723]
Version:             0.4.2 (28)
OS Version:          macOS 26.5 (25F71)

Exception Type:      EXC_BREAKPOINT (SIGTRAP)
Termination Reason:  Namespace SIGNAL, Code 5, Trace/BPT trap: 5

Thread 0 Crashed::  Dispatch queue: com.apple.main-thread
0   libswiftCore.dylib   _assertionFailure(_:_:file:line:flags:) + 172
1   Owlet                closure #1 in variable initialization expression of static NSBundle.module + 584
2   Owlet                one-time initialization function for module + 12
3   libdispatch.dylib    _dispatch_client_callout + 16
4   libdispatch.dylib    _dispatch_once_callout + 32
5   Owlet                TokenRank.iconImage.getter + 500
6   Owlet                RankIconView.body.getter + 304
7   SwiftUICore          ViewBodyAccessor.updateBody(of:changed:) ...

这条栈从下往上读，故事非常清楚：

frame 6-5：SwiftUI 要渲染 RankIconView，读它的 body，进而调用 TokenRank.iconImage 这个 getter——也就是「加载排名图标」。
frame 4-2：iconImage 里访问了 Bundle.module。Bundle.module 是个 static let，第一次访问会触发 _dispatch_once 一次性初始化（one-time initialization function for module）。
frame 1-0：这个初始化闭包里执行了 _assertionFailure——直接崩。

栈顶的 _assertionFailure + 中间的 static NSBundle.module 初始化，是这类 bug 的经典指纹。它对应的其实就是 SwiftPM 生成代码里那句：

1	Fatal error: unable to find bundle named Owlet_Owlet

为什么 Bundle.module 会 fatalError

如果你的 SPM target 声明了 resources，Swift Package Manager 会在编译期自动合成一段 Bundle.module 的代码，逻辑大致是：

// SwiftPM 自动生成，简化版
extension Foundation.Bundle {
    static let module: Bundle = {
        let bundleName = "Owlet_Owlet"
        // 依次在几个候选路径里找 Owlet_Owlet.bundle
        let candidates = [
            Bundle.main.resourceURL,
            Bundle.main.bundleURL,
            // .build 相关路径……
        ]
        for candidate in candidates {
            if let path = candidate?.appendingPathComponent(bundleName + ".bundle"),
               let bundle = Bundle(url: path) {
                return bundle
            }
        }
        // 找不到就直接崩
        fatalError("unable to find bundle named \(bundleName)")
    }()
}

注意最后一行：找不到资源包，它不给你 fallback，直接 fatalError。 这是 SwiftPM 的刻意设计——在它的世界观里，资源包应该总是跟着可执行文件走，找不到就是构建/打包出错，属于「不该发生」的致命错误。

问题在于，它内置的候选路径是为 swift build/swift test 那套 .build/ 目录布局准备的。当你手动把可执行文件塞进 Owlet.app/Contents/MacOS/、把资源包塞进 Contents/Resources/ 时，布局对不上，Bundle(url:) 在它预设的候选路径里全部返回 nil，于是走到最后一行崩掉。

这就解释了那个最迷惑的现象：

场景	可执行文件位置	资源包位置	Bundle.module 结果
开发机 `swift run`	`.build/debug/Owlet`	`.build/debug/Owlet_Owlet.bundle`（就在旁边）	✅ 找到，不崩
用户首装 `.app`	`.../MacOS/Owlet`	`.../Resources/Owlet_Owlet.bundle`（布局不同）	❌ 找不到 → fatalError

开发时永远复现不出来，因为开发时资源包就躺在可执行文件旁边，SwiftPM 的默认路径一找一个准。

我早就知道这个坑——但漏了一处

最扎心的是：这个坑我早就踩过并且修过。项目里专门有一个封装，就是为了绕开 Bundle.module 在 .app 里定位失败的问题：

enum AppResourceBundle {
    static let module: Bundle = {
        let fm = FileManager.default
        // 1. 按 .app 的真实布局找：Contents/Resources/Owlet_Owlet.bundle
        if let resourcesURL = Bundle.main.resourceURL {
            let url = resourcesURL.appendingPathComponent("Owlet_Owlet.bundle")
            if fm.fileExists(atPath: url.path), let b = Bundle(url: url) { return b }
        }
        // 2. 兼容另一种布局
        let legacy = Bundle.main.bundleURL.appendingPathComponent("Owlet_Owlet.bundle")
        if fm.fileExists(atPath: legacy.path), let b = Bundle(url: legacy) { return b }
        // 3. 实在找不到才回落到 SwiftPM 的 Bundle.module
        return Bundle.module
    }()
}

它的核心就是：先用 fileExists + Bundle(url:) 按 .app 的真实布局显式查找，命中就返回；只有全都落空时，才把烫手山芋丢回给 Bundle.module。这样在 .app 里能稳定命中第 1 步，根本走不到会 fatalError 的那一行。

全项目一共 8 处加载资源，其中 7 处都规规矩矩用了 AppResourceBundle.module：hook 脚本、app 图标、菜单栏猫头鹰、Dashboard 图片、本地化 bundle……唯独排名图标这一处漏了网：

// TokenRankIcon.swift —— 出事的那一行
extension TokenRank {
    var iconImage: NSImage? {
        let name = "rank-\(persistenceValue)"
        guard let url = Bundle.module.url(          // ❌ 直接用了 Bundle.module
            forResource: name, withExtension: "png", subdirectory: "RankIcons"
        ) else { return nil }
        return NSImage(contentsOf: url)
    }
}

修复只有一行：

-        guard let url = Bundle.module.url(
+        guard let url = AppResourceBundle.module.url(
             forResource: name, withExtension: "png", subdirectory: "RankIcons"
         ) else { return nil }

为什么这种「只漏一处」的 bug 最难防

这行代码有几个特别阴的地方，值得单独拎出来说：

第一，guard let ... else { return nil } 给了你虚假的安全感。 这行写得很「防御」——找不到资源就返回 nil，调用方还有 SF Symbol 兜底。看起来无懈可击。但崩溃发生在 Bundle.module 这个表达式被求值的瞬间，压根轮不到 .url(...) 返回 nil。你的 else 分支再周全也拦不住，因为进程在进入 guard 之前就已经 fatalError 了。

第二，它是 lazy 的定时炸弹。 Bundle.module 是 static let + dispatch_once，只在第一次被访问时初始化。只要 app 有任何一条路径会渲染排名图标（menu bar 状态图标、灵动卡、排名弹窗都会），首启就必然触发。而恰恰这个 app 的核心功能就是「显示排名」，等于把炸弹放在了必经之路上。

第三，编译器完全帮不上忙。 Bundle.module 和 AppResourceBundle.module 类型一样、API 一样、调用方式一样，编译期没有任何区别。少写四个字符 AppResource，代码照样编译通过、开发机照样跑得欢，只在用户机上炸。这种「语义上错、语法上对、且只有一处」的 bug，靠 code review 用肉眼扫也极容易滑过去。

真正能防住它的其实只有一招：从源头上让「危险的那个 API」不可直接访问。 如果我能把 Bundle.module 的可见性收窄、逼所有资源加载都必须走 AppResourceBundle，这个 bug 从一开始就写不出来。可惜 SwiftPM 合成的 Bundle.module 是 internal 可见的，没法轻易禁掉——退而求其次，至少可以加一条 lint / grep 规则，在 CI 里扫「除了 AppResourceBundle.swift 之外任何文件出现裸的 Bundle.module」直接 fail。

要不要用 / 我的判断框架

这次踩坑给「纯 SPM 打 macOS app」这条路线补了几条经验，供同样在 vibe macOS app 的人参考：

值得上：纯 SPM + 脚本打包对小工具型 app 依然是划算的，省掉整个 Xcode 工程的心智负担。但你必须清楚地知道——一旦你手动组装 .app，SwiftPM 那套「资源就在可执行文件旁边」的假设就不成立了，所有 Bundle.module 都得换成按 .app 真实布局查找的封装。这不是可选优化，是必修课。
重点关注：凡是「开发机好好的、用户机崩」的 bug，第一反应就去查运行环境差异——资源布局、签名方式、路径假设、权限。这次是资源包路径，上次是 codesign identity 漂移。它们的共同点是：你的开发环境「太顺了」，顺到掩盖了打包产物里的问题。能在装好的 .app 上做一次冷启动冒烟测试，胜过在 .build/ 里跑一百次。
可以再等 / 顺手做：给危险 API 加护栏这件事，值得排进 backlog。fatalError 类的「找不到就崩」API（Bundle.module、强解包、try!、数组越界下标）在常驻 app 里都是首启崩溃的高发点。与其靠自觉每次都记得用封装，不如让「裸用」在 CI 里直接编不过或过不了 lint——把「记得」变成「想漏都漏不掉」。

一句话收尾：这个 bug 的技术根因五分钟就能讲清，但它能上线，靠的是「开发机永远复现不出」+「编译器不报错」+「八处只漏一处」三重巧合。防它的关键不在于更聪明地写这一行，而在于让这一行根本没机会写错。

@unchecked Sendable 骗过了编译器：一次 Swift 并发字典崩溃复盘

2026-07-10T13:30:00.000Z

Owlet 是我用 Claude Code + Codex vibe 出来的一个常驻 menu-bar app，用来统计每天 Claude Code 和 Codex 的 Token 用量、排名、实时会话活动。常驻类 app 最怕两件事：一是空闲耗电，二是莫名其妙崩。这次一天之内，我连着修了两个崩溃——而且它们像俄罗斯套娃：修好外面那个，里面那个才露出来。

第一个崩得相当有迷惑性——崩溃栈指向的那一行代码本身没有任何问题。真正的凶手，是一个我亲手写下 @unchecked Sendable、然后就再也没管过它线程安全的普通 Dictionary。第二个则相反，是个藏在一行 0 里、只要用起来就必崩的确定性 bug。两个坑的共同点是：它们都利用了 Swift 里某个”看起来无害”的默认行为。

一句话总结

@unchecked Sendable 不是”让这个类型线程安全”，而是”我向编译器保证它已经安全了，你别查了”。如果你写下它却没做任何同步，普通 Dictionary 在并发写下会直接损坏底层存储、破坏整个进程的堆内存，崩溃点还会飘到无辜的其他线程上。

崩溃现场：两个线程站在同一个栈上

先看崩溃日志最关键的部分。信号是 EXC_BAD_ACCESS (SIGSEGV)，访问了一个明显非法的地址 0x8000000000000028：

Thread 4 Crashed:
0   libswiftCore.dylib   __RawDictionaryStorage.find(_:) + 36
1   libswiftCore.dylib   _NativeDictionary.setValue(_:forKey:isUnique:) + 192
2   libswiftCore.dylib   Dictionary._Variant.setValue(_:forKey:) + 196
3   libswiftCore.dylib   Dictionary.subscript.setter + 604
4   Owlet                ClaudeCodeAdapter.discoverSessions() (ClaudeCodeAdapter.swift:200)

崩在 __RawDictionaryStorage.find / setValue——也就是往字典里写一个 key 的时候，字典的内部哈希存储已经是坏的了。这不是”key 不存在”这种业务问题，是底层内存结构被破坏。

再往下看，会发现一个决定性的线索：另一个线程也停在同一个函数里。

1 2	Thread 2: 5 Owlet ClaudeCodeAdapter.discoverSessions() (ClaudeCodeAdapter.swift:199)

两个后台线程，同一时刻，都在执行 discoverSessions()，都在读写同一个 Dictionary。一个在 199 行读，一个在 200 行写。到这里，数据竞争（data race）已经基本实锤了。

还有一个更迷惑人的细节：崩溃报告里第三个线程停在完全不相干的地方——

Thread 7 (GRDB.DatabasePool.reader):
   key path getter for Character.isNewline
   Collection.split(whereSeparator:)
   CodexDataReader.rolloutTokenUsageEvents(path:)

CodexDataReader 是读 Codex 数据的另一套代码，跟 Claude 的 adapter 八竿子打不着，凭什么它也崩？

答案是：堆内存被写坏之后，整个进程都在雷区里跑。 Thread 4 把字典的底层存储写坏，破坏的是共享的堆。此后任何线程在任何位置做一次内存访问，都可能踩到那片被污染的区域，然后随机崩溃。所以排查并发内存崩溃时，有一个重要原则:

崩溃日志里”触发信号的那个线程”（triggered: true）才是凶手，其他线程往往只是受害者。

如果你盯着 Thread 7 的 CodexDataReader 去查，会彻底跑偏。

@unchecked Sendable：一句你亲手写下的空头承诺

顺着凶手 ClaudeCodeAdapter 看类型声明：

final class ClaudeCodeAdapter: AgentAdapter, @unchecked Sendable {
    private var sessionEntryCache: [String: CachedSessionEntry] = [:]
    // ...
}

问题全在这两行里。

Sendable 是 Swift 并发模型里的一个协议，意思是”这个类型的值可以安全地跨并发域传递”。对于 class 这种引用类型，编译器默认不认为它是 Sendable——因为多个线程可能同时持有同一个引用、改同一块状态。

而 @unchecked Sendable 是一个逃生舱：它告诉编译器”这个类型我人工审计过了，线程安全我自己保证，你不用检查”。它常用于两种情况：一种是内部用了锁/串行队列做同步，只是编译器看不出来；另一种是……写的人当时觉得”应该没事吧”。

我这次就是第二种。sessionEntryCache 是一个普通的 Dictionary，没有锁、没有串行队列、没有 actor，什么保护都没有。@unchecked Sendable 关掉了编译器的并发检查，于是这个隐患一路绿灯上了线。

这里要记住一件事：@unchecked Sendable 不提供任何运行时保护，它只是关掉编译期的报错。 你写下它的那一刻，线程安全就从”编译器帮你保证”变成了”你自己口头保证”。

那为什么会有两个线程并发进来？看调用方：

// AppState.refresh() 里
_ = try await Task.detached(priority: .utility) {
    for runtime in runtimesToImport {
        imported += try await capturedIngestion.importSessions(from: runtime.adapter)
        // -> 最终调用 adapter.discoverSessions()
    }
}.value

refresh() 会在多个时机被触发——app 启动 bootstrap、文件监听 debounce 后的自动刷新、手动刷新。每次触发都开一个 Task.detached 跑 import。当两次刷新时间上挨得很近（比如启动时 bootstrap 和文件监听几乎同时发生），两个 detached task 就并发进入了同一个 adapter 实例的 discoverSessions()，一起写那个没有任何保护的字典。

为什么不能用细粒度锁：read-modify-write 的原子性

找到根因，很多人第一反应是”给字典加个锁不就行了”。但加在哪、加多粗，是这次真正值得记下来的点。

先看 discoverSessions() 里对 cache 的访问模式：

if let entry = sessionEntryCache[cacheKey] {        // ① 读旧 entry
    if fileSize > entry.fileSize {
        // 只读新增的字节，从 entry.offset 处 seek
        parseIncremental(file, entry: entry, ...)    // ② 用 entry.offset seek 文件
    }
}
// ...
sessionEntryCache[cacheKey] = newEntry               // ③ 写回带新 offset 的 entry

这是一个典型的 read-modify-write：读出旧的 entry（里面记着”上次读到文件的哪个字节偏移”），基于这个 offset 只读文件新追加的部分（增量解析，避免每次全量重读几十 MB），再把新的 offset 写回去。

如果只给字典的每次下标访问加一把细粒度锁（读一次锁一次、写一次锁一次），会发生什么？

线程 A 读到 offset=1000，线程 B 也读到 offset=1000。两个线程都从 1000 开始读文件、各自解析、各自把”新 offset”写回。其中一个的结果被覆盖，offset 错乱，同一段 Token 用量被重复计入。

字典本身不崩了，但数据错了。细粒度锁保护了”每一次字典操作”的原子性，却没保护”读—改—写”这个序列整体的原子性。这是并发编程里最容易栽的一类坑：锁的粒度对齐的应该是不变量（invariant），而不是单个操作。

这里的不变量是”cache 里的 offset 必须和已经解析进去的字节严格对应”。要维持它，整个 discoverSessions() pass 必须串行执行。所以正确的修法是一把粗粒度锁，锁住整趟：

private let discoverLock = NSLock()

func discoverSessions() async throws -> [AgentSessionDraft] {
    discoverLock.withLock { discoverSessionsLocked() }
}

private func discoverSessionsLocked() -> [AgentSessionDraft] {
    // 原来那一整段读目录、读文件、增量解析、写 cache 的逻辑
}

有人会担心：持锁期间还在做磁盘 I/O，第二个并发调用不就干等着吗？会。但这恰恰是最优解——第二个调用等第一个做完之后拿到锁，此时 cache 已经是热的，绝大多数文件的 mtime / fileSize 都没变，直接命中缓存、零 I/O 秒回。串行化在这里几乎没有额外代价，反而消除了两个 task 各跑一遍的重复劳动。

Swift 6 的暗礁：async 上下文里不能 lock()

按上面思路，我一开始是直接在 discoverSessions() 里写的：

func discoverSessions() async throws -> [AgentSessionDraft] {
    discoverLock.lock()
    defer { discoverLock.unlock() }
    // ...
}

编译能过，但�报了个 warning，而且明说了在 Swift 6 语言模式下会直接变成 error：

1
2
3

warning: instance method 'lock' is unavailable from asynchronous contexts;
Use async-safe scoped locking instead;
this is an error in the Swift 6 language mode

原因很本质：async 函数可能在任意 await 处挂起，挂起之后恢复执行的线程不一定是原来那个线程。而 NSLock 是要求”谁上锁谁解锁、同一线程”的。如果你在 lock() 和 unlock() 之间跨了一个 await，挂起前后换了线程，就会变成”A 线程上锁、B 线程解锁”，直接是未定义行为。

编译器无法证明你两者之间没有 await，于是干脆禁止在 async 上下文里裸用 lock()/unlock()。

正解是用 scoped 的 withLock { }：把需要保护的逻辑抽成一个同步函数（我这里是 discoverSessionsLocked()），闭包体内不可能出现 await，锁的获取和释放必然在同一个同步执行段里完成。这也顺便逼你把”要保护的临界区”想清楚、圈干净，而不是散着写一堆 lock/unlock。

加餐：同一天的第二个崩溃，藏在一行 `0` 里

修完并发那个崩溃、重新打包上线，没过多久又收到一份新的崩溃日志。这次信号不一样，是 EXC_BREAKPOINT (SIGTRAP)——Swift 运行时主动触发的陷阱，通常意味着数组或 Data 越界。

崩溃点在一个监听 JSONL 会话文件、检测”用户中断”的后台组件里：

private func scanBufferForInterrupt() {
    var scanStart = 0
    while scanStart < leftoverData.count {
        guard let index = leftoverData[scanStart...].firstIndex(of: newline) else { break }
        // ... 处理一行 ...
    }
    if consumed > 0 {
        leftoverData.removeFirst(consumed)   // ← 雷埋在这
    }
}

leftoverData 是一个不断追加、扫描完就把已处理部分 removeFirst 掉的 Data buffer。看起来天经地义。但它踩中了 Data 一个反直觉的设定：

Swift Data 的 index 是绝对的。removeFirst(n) 之后，它的 startIndex 会前移到 n，而不是回到 0。

第一次扫描时 startIndex == 0，leftoverData[0...] 一切正常。扫完执行 removeFirst(consumed)，startIndex 变成了 consumed（比如 87）。等文件第二次增长、再进来扫描时，scanStart 还是硬编码的 0，而 leftoverData[0...] 里的这个 0 已经落在 startIndex 之前——越界，SIGTRAP。

这不是偶发的并发时序问题，是个确定性 bug：只要有一个 Claude 会话在跑、它的 JSONL 被追加写入两次，就必崩。之所以之前一直没暴露，是因为上一个并发崩溃发生得更早，先把进程带走了；修掉前一个，这个就顶到了最前面。

修复本身很简单，但记性要长——别用字面量 0 当 Data 的索引，一切从 startIndex 起：

var lineStart = leftoverData.startIndex
while lineStart < leftoverData.endIndex {
    guard let newlineIndex = leftoverData[lineStart...].firstIndex(of: newline) else { break }
    let lineData = leftoverData.subdata(in: lineStart..<newlineIndex)
    // ...
    lineStart = leftoverData.index(after: newlineIndex)
}

Collection 的下标是绝对索引，这件事在 Array 上很少咬到你——因为 Array 的 index 永远从 0 开始。但 Data、ArraySlice、Substring 这些”可能是别人一部分”的类型，startIndex 随时可能不是 0。凡是切片类型，就别信 0。

我的判断框架：actor / 锁 / @unchecked Sendable 怎么选

这次踩坑之后，我给自己定了一套在 Swift 并发里选同步手段的判断顺序：

场景	首选	理由
新写的、可以 async 化的共享可变状态	`actor`	编译器强制隔离，从根上杜绝数据竞争，不用自己管锁
已有同步 API、不方便全改 async，临界区清晰	`NSLock` + `withLock`	改动最小，粗粒度锁住不变量即可
高频只读、极少写	读写锁 / 原子类型	读不互斥，避免锁竞争成为热点
确实由底层机制保证了安全	`@unchecked Sendable` + 注释写清凭什么安全	逃生舱，但必须留下审计依据

几条给自己的硬规矩：

看到 @unchecked Sendable，就当成一个待验证的 TODO。 它旁边必须有一句注释说明”靠什么保证线程安全”（哪把锁、哪个串行队列、哪个 actor）。说不出来，就是隐患。
锁的粒度对齐不变量，不对齐单个操作。 遇到 read-modify-write，先问自己”这三步之间的中间状态能不能被别人看到”，不能就整段串行。
排查并发内存崩溃，先认准 triggered 线程。 堆一旦被写坏，崩溃点会飘，别被无辜的受害线程带偏。
async 里要锁，用 withLock，别用裸 lock()。 顺手把临界区抽成同步函数，思路和编译器都会更清楚。
切片类型的索引从 startIndex 起，别信字面量 0。 Data、ArraySlice、Substring 的 startIndex 随时可能不是 0，尤其在 removeFirst / 切片之后。遍历用原生 index，不用 Int 硬编码。

@unchecked Sendable 这类逃生舱不是不能用——actor 化整个 adapter 也要改协议、改一堆调用点，工程上未必划算。真正的问题是：我当初写下它的时候,把”我保证安全”当成了”它已经安全”。这两者之间隔着的，正是一次会飘到无辜线程上的堆内存崩溃。

我在给自己建一个 LLM wiki

2026-07-10T02:30:00.000Z

今天我干了三件看起来不相干的小事：把”怎么把一张图做成 macOS 应用图标”写进了一个 Claude Code skill，把”博客每篇至少配 3 张插图”写进了全局 CLAUDE.md，还顺手把一次踩坑记成了博客。

写到第三件的时候我突然停下来：这三件事，本质上是同一件事——我在把”怎么做”这件知识，沉淀成 AI 下次能直接读、直接用的形式。

换句话说，我在给自己建一个 wiki。只不过这个 wiki 的读者不是人，是 LLM。

一句话总结

传统 wiki 是写给人查的，LLM wiki 是写给模型执行的。 前者追求”读得懂”，后者追求”能复用”——要可执行、有触发条件、能被真实结果校验。当你开始有意识地为 AI 沉淀知识，你的个人生产力会从”一次性完成任务”变成”每次完成都让下一次更快”。

我是怎么撞见这个想法的

起因很具体。我在 vibe coding 一个 macOS menu-bar 应用，需要把一张 AI 生成的猫头鹰图变成真正的 app 图标。这中间有一堆非显而易见的坑：macOS 不会帮你自动圆角、AI 出的图常常自带一圈 padding 和阴影、直接用会变成”方块里套圆角块”、squircle 的圆角半径大概是边长的 0.2237 倍……

我踩完这些坑、跑通整条管线之后，做了一个选择：不是把结果留在这次对话里，而是把方法写进 skill。

于是下次我（或者任何一个读这个 skill 的 AI）再遇到”把图做成 mac 图标”，不用重新踩一遍——自动裁 padding、套 squircle、生成 iconset、打包 .icns，一条龙。

那一刻我意识到：我做的不是”完成一个任务”，是”给未来的 AI 写了一页可执行的文档”。这页文档，就是 LLM wiki 的一条词条。

LLM wiki 的三种载体

我目前的知识沉淀，落在三个地方，各有分工：

载体	存什么	何时被读	类比
`CLAUDE.md` / `AGENTS.md`	全局约束、偏好、红线	每次会话自动加载	wiki 的”编辑守则”
Claude Code skill	可执行的方法论、管线	命中触发词时按需加载	wiki 的”操作手册词条”
博客文章	判断框架、踩坑复盘、观点	我或别人主动检索	wiki 的”深度专题页”

CLAUDE.md 是常驻规则。 它每次都进上下文，所以只放最高优先级、最稳定的东西：比如”博客每篇至少 3 张插图””性能规则不能回退””发布流程怎么走”。它贵，所以要克制——不该把操作细节全塞进来。

skill 是按需加载的操作手册。 它平时不占上下文，只有当任务命中触发词（”做 mac 应用图标”、”.icns”）才被拉进来。这意味着 skill 可以写得很详细、很长，因为它不是常驻成本。我那条 macOS 图标管线就适合放这儿。

博客是给人也给 AI 的深度页。 它存的是”为什么这么做”的判断，而不只是”怎么做”的步骤。而且它是公开的——别人的 AI 也能检索到、学到。这层是前两层的”公共版”。

LLM wiki 和传统 wiki 差在哪

关键区别只有一个：读者变了。

传统 wiki 写给人，人会脑补、会容错、会举一反三。所以传统文档可以模糊——“把图标处理一下”，人能懂。

LLM wiki 写给模型，你得假设读者不会脑补、只会照做。所以三条硬要求：

可执行，不是描述。 别写”记得处理透明背景”，直接给能跑的脚本 + 参数 + 兜底分支。我那条图标 skill 里直接嵌了一段 Python，模型抽出来就能运行。
有触发条件。 人会自己判断该翻哪一页；模型需要你明确写”什么时候用我”。skill 的 description 和触发词就是干这个的——写不好，该被加载时它不出现。
能被 ground truth 校验。 这是我今天最深的一课。

最痛的一课：不要相信”我以为做了”

今天我在提交一个 skill 改动时，中间的工具输出显示”已提交、已推送”，我就信了、往下走了。后来用 git rev-parse HEAD 和 git show 一核对——根本没提交成功，那几步是我基于未经核验的中间状态脑补出来的。

这件事放在 LLM wiki 的语境里特别有意思：模型（包括我这个 AI）会基于”我以为的状态”往前跑，而不是”真实的状态”。 所以一条好的 LLM wiki 词条，必须内建”用真值校验”这一步。

我后来把这条也固化了：涉及提交推送，一律以 git rev-parse、git status、git show 的真实输出为准，绝不用中间回显下结论。这就是一条为 AI 写的”自我校验规则”。

传统 wiki 不需要教人”提交完要确认真的提交了”——人有直觉。但给 AI 写的 wiki 需要，因为模型的失败模式和人不一样：它不是不会，是会一本正经地跑偏。

怎么让沉淀真的被复用

沉淀不等于复用。我踩过的坑：

写了没触发词 = 白写。 skill 描述里不写”mac 应用图标 / .icns”，下次问”帮我做个应用图标”时它根本不会被加载。触发词是 LLM wiki 的”索引”。
写太细放错层 = 变负担。 把一次性的操作细节塞进 CLAUDE.md，每次会话都要为它付上下文成本。分层很重要：常驻的极简、按需的详尽。
只存结果不存判断 = 不可迁移。 “这次用了方案 A”没价值；”因为 X 约束所以选 A、代价是 Y”才能迁移到下一个场景。这也是为什么博客这层不可替代——它存的是判断框架。

要不要这么干 / 我的判断框架

场景	判断
你反复让 AI 做同类任务（生图、部署、某种重构）	值得上：沉淀成 skill，一次写、无限复用
你有稳定的个人偏好和红线	值得上：写进 `CLAUDE.md`，别每次重复交代
一次性的、不会再遇到的任务	可以再等：沉淀成本大于收益
你享受”每次做完都让下次更快”的复利感	值得上
你还在纯手动、每次从零跟 AI 解释背景	重点关注：你在重复付一笔本可以免掉的税

我越来越确信一件事：在 Agent / AI Infra 时代，超级个体的护城河不是”会用 AI”，而是有没有为 AI 持续建一个高质量的知识库。工具谁都能用，但你喂给它的上下文、你沉淀的判断框架，是别人复制不走的。

判断框架负责决定”做什么、不做什么、底线在哪”，AI 负责把执行力拉满。而 LLM wiki，就是把你的判断框架，翻译成 AI 每次都能读到的形式。

写到这我就明白了：这篇博客本身，也是我 LLM wiki 里的一页。它遵守我今天刚写进 CLAUDE.md 的规则——至少配 3 张插图。

挺自洽的，也挺酷的。

我用 Claude Code + Codex vibe 了一个 macOS App：Owlet

2026-07-09T18:30:00.000Z

过去一个月，我的 Mac 菜单栏里多了一只小猫头鹰。

它叫 Owlet，是我用 Claude Code 和 Codex 一起 vibe 出来的 macOS 小工具：常驻菜单栏，实时显示 Claude Code 和 Codex 的 token 消耗，附带一个贴合刘海的灵动岛面板、一个桌面灵动卡、还有一个看历史用量和排名的 dashboard。

做这个 app 的动机很私人。今年我开始从前端往 Agent / AI Infra 方向转，每天大部分时间都在跟 Claude Code 和 Codex 泡在一起。泡着泡着就产生了一个很朴素的疑问：我每天到底烧了多少 token？钱花哪儿了？哪个项目最费钱？ 现有的工具都不直接回答这个问题，那我就自己做一个。

于是就有了 Owlet。

一句话总结

Claude Code 负责架构、长上下文和需要判断力的重构；Codex 负责快速试错和小范围实现；我负责拍板、验收和把家乡青山湖的颜色塞进 UI。 三者分工明确时，vibe coding 真的能把一个 idea 从 0 推到能用。

为什么是一只猫头鹰

Owlet 的英文意思是“小猫头鹰”。图标是一只像素风猫头鹰，缩在菜单栏里，眼睛一眨一眨地观察你的 AI 会话。

选它有两个原因。一是气质贴合：这个 app 做的就是“盯着你用 AI 的过程”，猫头鹰那种夜间警觉、悄无声息的感觉，比什么“机器人”“仪表盘”都更对味。二是可爱——macOS 菜单栏天天见的东西，不能太硬核，得让人愿意让它一直待着。

定下名字那晚我对 Claude 说：

“根据现在帧动画里猫头鹰 icon 的形象重新命名 app。”

最后从几个候选里挑了 Owlet。短小、好读、不容易撞名，而且一听就知道跟 owl 有关。

这就是独立开发的好处：审美和命名这种在别人公司要开三天会的决定，自己一个人一晚上就能拍板。

Claude Code 是架构师，Codex 是快枪手

这个项目里我同时开了两条 AI 线：Claude Code 和 Codex。

Claude Code 是我的主架构师。 它的长上下文能力太适合这种代码量不大但跨模块关联多的项目。比如设计实时 session 监控链路时，我需要同时理解：

Claude Code 的 hook 机制（owlet-hook.py 怎么装、怎么往 Unix socket 发事件）
macOS 上 NSPanel 和 SwiftUI 的边界行为
事件驱动的文件监听该怎么 debounce
SQLite 里 session、hourly、daily 三张表怎么 upsert 不丢数据

这种时候我会把问题抛给 Claude Code，让它先给方案，我再挑毛病。

Codex 则是我的快枪手。 有些改动范围很小、很具体，不需要长篇讨论，直接让 Codex 上。比如：

“Codex 判断了有没有刘海的逻辑，删了。”
“这个黑框是为啥，这也是 Codex 今天下午加的。”

Codex 的特点是快，但偶尔会留下一些“看起来能动，但边界没处理干净”的痕迹。那个黑框就是典型：它在刘海屏设备上加了一层黑色背景，意图是隐藏刘海，结果在非刘海屏上反而露了馅。最后还是我拉着 Claude Code 一起复盘，把透明 panel 的圆角和 masksToBounds 重新理了一遍才解决。

这件事让我明确了一条分工：需要理解系统边界和做取舍的，找 Claude Code；需要快速验证一个想法的，找 Codex。

一个 idea 长出四块屏幕

Owlet 的 UI 表面不算多，但每一块都有自己的坑：

Surface	作用	难点
Menu bar	常驻图标 + token 总数	图标动画不能太耗电
Floating island	刘海区实时会话面板	`NSPanel` 圆角、多屏、透明度
Dashboard	历史用量、排名、设置	SwiftUI 图表和数据库查询
Dynamic card	桌面小组件式面板	像系统 widget，但不能真用 WidgetKit

最有意思的是命名。某天我突然说：

“刷新数据放到标题旁边怎么样？还有在灵动家族给这个菜单起个名字，一家人要整整齐齐。”

于是就有了“灵动家族”：灵动岛、灵动卡、灵动栏。这个命名一点都不高大上，但它让产品在聊天时变得很好描述。“灵动卡又崩了” 比 “桌面浮动窗口崩溃了” 可爱多了。

另一个让我印象深刻的是灵动卡的崩溃排查。同样是 Apple Silicon、同样是 macOS 15，有的机器能打开，有的机器直接崩。最后定位到问题不在业务逻辑，而在 AppKit window level、NSPanel、系统材质和透明圆角叠加后的边界行为。那篇文章我已经单独发过，这里不再展开。

把青山湖写进代码

我是杭州临安人，青山湖就在家门口。Owlet 的视觉方向最后定成了：像原生 macOS 工具，但从青山湖的湖水、杉林、青山、雾白里取色。

具体 Palette 长这样：

蓝雾天空 → 浅背景
浮萍湖绿 → 主要强调色
水杉深绿 → 深色文字和进度条
雾带白 → 面板底色
晨光浅金 → 仅用于边缘光和状态提示
雨后湿木 → 少量阴影和分隔

我甚至专门给 Claude 下了一条规则：

“晨光浅金只用于边缘光、状态提示或小面积 accent，不能主导整个 surface。”

因为项目早期用过一段时间黄/金色做主色，结果越调越脏，最后全推翻了。改成青山湖色系后，整个 app 立刻从“网吧风”回到了“能放在 macOS 桌面上不丢人”的状态。

Owlet 是常驻应用。只要 Claude 不活跃，它就不应该醒来。

为此我们做了几件看起来很细节、但很重要的事：

文件监听用 Dispatch Source，而不是轮询。 之前有些实现会 sleep-loop 检查 active session，我全部砍掉了。
JSONL 增量读取。 50 MB 的会话日志不应该造成 50 MB 内存峰值。ClaudeCodeAdapter 用 (mtime, fileSize, byteOffset) 做缓存，文件增长时只读新增 bytes。
动画门控。 菜单栏猫头鹰只有 token 总数变化时才脉冲；dashboard 和 island 只有 active session 存在时才按 0.2s 帧率动画，idle 时最多每秒一帧。
数据库 upsert 而不是 deleteAll + insert。 这个改动很小，但能避免大量无用写入。

这些规则都被写进了 CLAUDE.md 和 AGENTS.md，成为后续所有改动的底线。一个工具要是自己先变成电老虎，就没资格监控别人的 token 消耗。

AI 协作的边界：它不是替你做主

整个过程中，AI 没有替我做任何一个真正重要的决定。

要不要做这个项目？我决定。
功能优先级怎么排？我决定。
命名 Owlet？我决定。
青山湖配色方向？我决定。
性能规则里哪些不能回退？我决定。

AI 做的是：把我模糊的判断快速翻译成可执行的代码和文档，并在执行过程中帮我规避低级错误。

这让我越来越确信一个判断框架：在 Agent / AI Infra 时代，人的核心竞争力不是写代码的速度，而是判断框架——知道什么该做、什么不该做、什么要取舍、什么是底线。AI 负责把判断拉满执行力，两者结合才是极致交付速度。

要不要用 / 我的判断框架

如果你也想尝试 vibe coding 一个小工具，我的建议是：

场景	判断
想做一个小而美的个人工具	值得上
项目涉及大量系统边界（macOS 权限、沙盒、codesign）	重点关注
需要长期维护和多端同步	可以再等
你享受“说一句话，AI 帮你验证”的快感	值得上
你无法接受 AI 偶尔留下小坑	可以再等

对我来说，Owlet 是一个完美的实验场：规模可控、用户就是自己、技术栈有挑战性但不需要服务百万用户。如果后续它能帮更多开发者看清 AI 使用成本，那就更好了。

现在菜单栏里那只小猫头鹰还在闪。它看着自己诞生的过程，也看着我每天烧掉的 token。

挺 meta 的，也挺酷的。

一次 macOS 灵动卡崩溃排查：别把桌面小组件当普通窗口

2026-07-09T14:38:30.000Z

最近给 Argos 做了一个桌面上的“灵动卡”：它不属于主窗口，也不是菜单栏 popover，而是一个常驻桌面的轻量信息面板，用来展示当天 Claude Code 和 Codex 的 Token 用量。

视觉上它应该接近系统桌面小组件，有一点毛玻璃、有圆角、有环境透色；交互上它又必须像一个普通 Mac app surface，可以拖动、可以关闭、可以从设置里重新打开。问题也出在这里：我们很容易把“看起来像系统小组件”和“实现方式也像系统小组件”混成一件事。

这次的真实反馈很直接：用户点击打开灵动卡，Argos 直接崩溃。

一句话总结

macOS 桌面浮层的稳定性不能只看 SwiftUI 视图本身，真正危险的是 AppKit window level、NSPanel 行为、系统材质、透明圆角和启动持久化一起叠加后的系统边界。

这不是一个普通 SwiftUI bug

最开始我也倾向于按普通 UI bug 排查：是不是某个 @EnvironmentObject 没注入？是不是 TimelineView 刷新太频繁？是不是某个统计数据为空导致 view body 崩了？

但反馈里有两个信号很关键：

现象	初步判断
只有部分机器崩	不是纯业务数据问题，更像系统组合差异
重装也无法恢复	可能和持久化设置有关，应用启动后自动走到崩溃路径
打开灵动卡才崩	主窗口、菜单栏、数据读取不是第一怀疑对象
同类机器不一定复现	芯片型号只是表象，系统窗口栈和显示环境也会影响

这类问题最麻烦的地方是：你的本机不崩，不代表代码没问题。macOS 的 window server、桌面组件层级、Stage Manager、多屏、刘海屏、透明材质都可能让同一段代码走到不同系统路径。

真正危险的是 window level

灵动卡一开始为了“悬浮在桌面上方”，用了更高的窗口层级。视觉上这很合理：它不应该被普通窗口轻易盖住。

但 AppKit 的窗口层级不是一个单纯的 z-index。不同 level 背后隐含了不同的系统行为：

层级选择	优点	风险
`.normal`	最稳定，接近普通窗口	可能被其他窗口盖住
`.floating`	更符合悬浮卡片直觉	更容易进入特殊窗口路径
desktop widget 附近	视觉接近系统小组件	系统版本、桌面状态、多屏下差异最大

最后我把层级选择暴露到了设置里：默认用最稳的普通窗口，用户可以自己切到浮动或桌面组件风格。这个决策不够“产品洁癖”，但足够工程务实。

switch windowLevel {
case .normal:
    panel.isFloatingPanel = false
    panel.level = .normal
case .floating:
    panel.isFloatingPanel = true
    panel.level = .floating
case .desktopWidget:
    panel.isFloatingPanel = false
    panel.level = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(.desktopIconWindow)) + 1)
}

这个代码片段的重点不是 API 本身，而是思路：把“视觉偏好”从“稳定默认值”里拆出来。默认路径必须保守，高风险路径可以给高级用户选择。

透明圆角 panel 不是只画一个 RoundedRectangle

第二个坑是透明圆角。

SwiftUI 里画一个 RoundedRectangle 很简单，但 NSPanel 本身仍然是一个 AppKit window。如果只处理 SwiftUI 背景，不处理 NSHostingView 和 window content view，系统可能仍然按矩形 frame 计算阴影、命中区域和合成边界。

这就是为什么透明 panel 要同时处理两层：

层	要处理什么
SwiftUI view	`clipShape`、背景、边框、视觉层次
AppKit hosting/container	clear background、cornerRadius、continuous corner、masksToBounds

尤其是透明窗口，最好不要依赖 AppKit 默认 shadow。默认 shadow 是按 window frame 投影的，frame 是矩形，圆角外就可能出现多出来的直角、脏边或奇怪边界。

玻璃质感也要分“安全”和“不安全”

桌面小组件风格很容易让人想到系统 material，比如 .ultraThinMaterial、NSVisualEffectView、behindWindow、underWindowBackground。

但这次排查里，我对灵动卡做了一个取舍：先不用 AppKit 的 NSVisualEffectView 做底层材质，而是用 SwiftUI 的轻量 blur、半透明 tint、渐变 stroke 和局部 glow 模拟“雾白玻璃”。

原因很简单：灵动卡本身已经是一个透明 NSPanel，再叠系统 material 和特殊 window level，变量太多。为了排查和发布稳定性，先减少系统合成路径。

方案	质感	稳定性	当前选择
`NSVisualEffectView` 强系统材质	高	中低	暂缓
SwiftUI blur + tint	中高	高	采用
纯实色卡片	中	最高	不采用

这也是我现在对 macOS 视觉实现的一个判断：能用系统能力当然好，但一旦 surface 是透明浮窗、跨桌面、多屏、可拖动，还要启动自动恢复，就不能盲目堆 material。

持久化是体验，也是事故放大器

还有一个容易忽略的点：灵动卡是否应该持久化打开状态。

从产品体验看，答案是应该。用户打开了桌面卡片，下次启动自然还应该在。默认也应该打开，否则用户可能根本不知道这个能力存在。

但从事故恢复看，持久化会放大问题：如果“打开灵动卡”本身会崩，那么应用每次启动自动恢复灵动卡，就会变成“打开应用即崩”，用户连进设置关闭它的机会都没有。

所以这里有一个典型工程取舍：

策略	体验	故障恢复
不持久化，启动默认关闭	差	好
持久化，启动默认打开	好	差
持久化 + 稳定默认层级	较好	可接受

最后我选择恢复持久化和默认打开，但把默认 window level 降到普通窗口，并把高层级选择放到设置里。这不是绝对安全，但比“默认走最高风险路径”合理得多。

为什么我的机器不崩，用户机器会崩

这个问题很值得单独说。

两个 Mac 看起来“除了芯片都一样”，并不代表窗口系统环境一样。至少这些因素都可能不同：

差异点	可能影响
芯片/显卡路径	WindowServer 合成、透明 blur、外接屏策略
系统小版本	AppKit / SwiftUI bridge 行为变化
Stage Manager / 桌面组件状态	桌面层级和特殊 window level 行为
多屏与刘海屏	默认定位、visibleFrame、notch 区域
辅助显示工具	BetterDisplay、HiDPI、虚拟屏可能改变 screen frame
历史设置	上一次保存的 window level、位置、visible 状态

所以这类 bug 不能只问“为什么我不复现”。更有效的问题是：哪些系统路径只有对方会走到？哪些设置会让用户每次启动都自动进入危险路径？

我的判断框架

以后再做 macOS 上的桌面浮层，我会按这个顺序判断：

默认层级先保守：普通窗口优先，浮动和桌面组件风格作为可选项。
透明圆角同时处理 SwiftUI 和 AppKit，不只画背景。
系统 material 先少用，等稳定性验证后再加。
持久化状态要配合故障恢复路径，否则一个开关就可能把用户锁死在崩溃循环里。
对“我本机不崩”的结论保持怀疑，多看系统版本、显示环境和历史设置。

要不要用 / 我的判断框架

如果你只是做一个普通工具窗口，不建议一上来就追系统小组件质感。先把窗口层级、圆角、拖动、恢复、关闭这些基础行为做稳。

如果你确实要做桌面小组件式 surface，可以上玻璃质感，但默认路径要克制。我的建议是：默认普通层级 + 安全 blur + 可选高级层级。等收集到足够多真实设备反馈后，再决定要不要把更像系统小组件的层级设为默认。

这次踩坑对我的提醒是：macOS 原生体验不是“看起来像原生”就够了，它还要求你尊重 AppKit 的历史包袱和窗口系统边界。尤其是 Agent 工具这种常驻型应用，稳定性永远比一个更漂亮的默认层级更重要。

粒子系统实践：从一版难看的彩纸特效说起

2026-07-08T15:58:00.000Z

今天给 Argos 做了一个“段位晋级彩纸特效”。

听起来是个很小的 UI 动画：用户 token 用量触发段位变化时，全屏弹一下彩纸，提示“黄金 III”之类的晋级结果。但真做起来，我发现这类效果很容易翻车。粒子太少，不像庆祝；粒子太多，像噪音。彩带想做飘逸，结果像屏幕上画了几条乱线。加爆点，本意是增强“爆炸感”，实际像廉价烟花。加光晕，本意是高级，实际会脏。

这篇文章复盘这次踩坑。重点不是 SwiftUI 代码，而是把粒子系统里那些概念讲清楚：particle、emitter、confetti、streamer、glint、ambient sparkles、bloom、burst、motion field、lifetime、distribution。以后再做类似 UI 特效，至少知道自己在调什么。

一句话总结

UI 里的庆祝特效，本质是一个小型 particle system。好看的关键不是“粒子越多越好”，而是让粒子的出生位置、生命周期、运动方向、密度分布、视觉层级服务同一个动势。

这次到底做了什么

Argos 里有一个段位系统：用户每天使用 Claude Code / Codex 的 token 会累计，达到某个 milestone 时触发段位变化。

我想要的效果是：

段位变化时出现全屏庆祝反馈。
中间有一个段位 toast，例如“黄金 III”。
屏幕上有彩纸、亮片、星芒，形成“晋级”的瞬间感。
只在调试环境有“测试彩纸”按钮，正式逻辑仍由真实段位变化触发。

最终通过的版本是：

元素	最终保留	原因
Confetti rectangles	是	语义最清晰，一眼就是庆祝
Circular chips	是	补充面积和层次，不抢主视觉
Diamond glints	是	增加高光和精致感
Small cross sparkles	是	少量点缀，强化“闪一下”
Streamers / 彩带	否	方向、曲线、交叉都很难调，容易显脏
Burst / 爆点	否	在这个场景里太像烟花，不符合 macOS 工具气质
Heavy bloom / 大光晕	否	容易污染画面，让文字和桌面背景变糊

这其实是一个很典型的 UI 粒子系统取舍：不是把所有效果都加上，而是删到只剩能稳定表达语义的元素。

Particle：粒子不是“点”，而是一个小演员

很多人听到 particle 会下意识理解成“点”。但在 UI 动画里，一个 particle 更像一个小演员，它至少有这些属性：

属性	含义	彩纸特效里的例子
position	当前坐标	彩纸当前在屏幕哪里
velocity	速度	往左上、右上、下落还是漂移
acceleration	加速度	重力、阻尼、回弹
lifetime	生命周期	0.8s 出现，3.5s 消失
size	尺寸	小彩纸、大亮片
rotation	旋转	彩纸翻转角度
opacity	透明度	出现、停留、淡出
color	颜色	高饱和彩纸色、湖水青、晨光金
shape	形状	矩形、圆形、菱形、星芒

所以“加一点彩纸”不是加几个随机矩形，而是定义一组小对象：它们什么时候出生、从哪里出生、往哪里走、多久消失、怎么旋转、颜色如何分布。

这次一开始怪异，根因就是我把粒子看成“画面装饰”，而不是一个系统。粒子的运动方向、密度和语义没对齐，就会出现“从上往下落”“一坨挤在一起”“不够满”“没有爆炸感”这些问题。

Emitter：发射器决定第一眼的动势

Emitter 是粒子系统里的发射器。它决定粒子从哪里出生。

常见 emitter 有几种：

Emitter 类型	视觉效果	适用场景
Point emitter	从一个点喷出	烟花、爆炸、魔法点
Line emitter	从一条线喷出	雨、雪、瀑布、顶部落彩纸
Area emitter	从一个区域出现	环境漂浮、空间尘埃
Edge emitter	从屏幕边缘进入	庆祝彩纸、舞台入场
Multi-emitter	多个发射源	全屏庆祝、游戏技能

这次最大的教训是：发射器位置会强烈决定用户对动画的理解。

最开始用户反馈“怎么是从上往下落的”，这说明粒子的 emitter 或 velocity 让人联想到“掉落”，而不是“庆祝喷发”。彩纸如果主要从顶部进入，语义就偏“下雨”；如果从左右两侧或底部斜向上出现，语义才接近“庆祝”。

后来我尝试让彩带从左右两边飞出，但又出现了新问题：左右彩带在中间交叉、起点过于集中、曲线不丝滑。这说明 emitter 不是只看一个点，还要看发射区域分布。

更准确地说，emitter 要调这几个参数：

参数	作用
origin	发射源位置
spread	发射范围
angle	初速度方向
variance	随机扰动
rate	单位时间生成多少粒子
burst count	瞬间生成多少粒子

最终我放弃彩带后，保留了更稳定的 area/edge 混合：彩纸从不同区域出现，星芒覆盖更大的屏幕区域，但不再让连续线条承担主视觉。

Confetti：彩纸是最稳的庆祝语义

Confetti 就是彩纸。它是庆祝动画里最稳定、最不需要解释的元素。

UI 里常见的 confetti 粒子通常是：

形状	视觉特点
矩形条	最像真实彩纸
小方块	更像游戏奖励
圆片	像亮片或纸屑
菱形	更有闪光感
短弧片	更像翻转中的纸片

这次最终保留的是亮色矩形彩纸。原因很简单：它的语义最强。

彩纸要好看，核心不是形状复杂，而是三件事：

颜色要亮：庆祝粒子不能太灰，否则像灰尘。
尺寸要有层次：全是同一尺寸会机械。
旋转要变化：不旋转就像静态贴纸。

我一开始颜色不够亮，用户直接指出“彩纸色彩要亮”。这很关键。UI 主体可以克制，但庆祝粒子本身必须高饱和，否则它的情绪表达不成立。

这里有一个设计边界：背景和主 UI 需要低饱和，粒子可以高饱和。如果整个界面都高饱和，会廉价；但庆祝粒子高饱和，是语义需要。

Streamer：彩带为什么最容易翻车

Streamer 是长彩带、飘带。它的问题比彩纸复杂很多。

彩纸是离散粒子，单个粒子不好看也不会毁掉整体。彩带是连续曲线，一条不自然就非常显眼。

这次彩带翻车主要有几个原因：

问题	根因
太高	lift 参数过大，曲线飞到屏幕顶部
太长	reach 过大，线条穿过视觉中心
挤在一起	emitter 起点过于集中
全是并行	控制点变化不足，曲线缺少角度差
交叉很尬	左右两侧没有限定各自活动区域
不丝滑	Bézier 控制点没有形成自然切线

彩带要自然，至少要同时满足：

起点分布不能重合。
曲线控制点要有连续的切线方向。
同侧可以有交叉，但交叉角度要自然。
左右两侧如果语义是“各自飞出”，就不能互相穿越中心。
长度、弧度、透明度要一起衰减。

这就不是“加几条曲线”了，而是在调一个小型 motion field。

最后我判断：在这个产品场景里，彩带收益不够高。Argos 是一个 macOS 工具，不是游戏结算页。彩带一旦做不好，负收益很明显。所以最终删掉。

这个决策很重要：粒子系统不是越复杂越高级，删掉不稳定元素也是工程能力。

Glint：星芒负责“精致”，不要负责“热闹”

Glint 是闪光、星芒。它通常是菱形、四角星、十字星，出现在高光点附近。

它适合做：

金属反光。
奖励高光。
魔法感。
“刚刚发生了好事”的瞬间提示。

但 glint 不能太多。太多会变成噪点，也会像廉价贴纸。

这次最终保留了两种 glint：

类型	作用
Diamond glints	菱形闪光，提供精致感
Cross sparkles	十字闪光，提供瞬间感

它们不是主角，主角仍然是 confetti。glint 的职责是让画面从“只有纸片”变成“有奖励感”。

一个实用规则：glint 的 opacity 应该随 pulse 变化，而不是常亮。常亮的星芒像贴图；一闪一灭才像反光。

Ambient Sparkles：环境闪光不是爆点

Ambient sparkles 可以翻译成环境闪光、氛围闪点。它和 burst 不一样。

概念	特点	观感
Burst	从中心或局部突然爆开	强刺激、像烟花
Ambient sparkles	分散在画面中轻微闪烁	氛围、精致、空间感

这次我试过加爆点，但用户反馈“不好看”。原因是爆点会把语义带向“烟花爆炸”，而 Argos 的晋级反馈更像“系统奖励”，不应该过度娱乐化。

Ambient sparkles 更适合这个场景：它们不抢段位 toast，不制造视觉中心，只是在背景层增加一点“庆祝正在发生”的环境反馈。

实现时要注意：

不要集中在一个点。
不要全部同步闪。
不要持续太久。
不要比主彩纸更亮。

Ambient sparkles 的价值是“补空气感”，不是“制造高潮”。

Bloom / Glow：光晕是调味料，不是主菜

Bloom 是光晕、泛光。Glow 也是发光，但在 UI 语境里更泛一点。Bloom 通常指亮部向周围扩散，让画面有曝光感。

光晕很容易让效果看起来“高级”，也很容易让画面变脏。

这次我对光晕的判断是：

光效	适合程度	原因
小面积 highlight	高	能增强奖励感
粒子边缘轻微 glow	中	可以让粒子更亮
大面积 bloom	低	会污染桌面背景和文字
中央强光爆点	低	会抢段位 toast

尤其在 macOS 上，全屏 overlay 下面是真实桌面和窗口。如果光晕太重，用户看到的是“脏”和“糊”，不是高级。

所以最后只保留轻量星芒和亮片描边，没有做大面积 bloom。

我的经验是：工具型产品里的 bloom，要像盐，不能像汤底。

Burst：爆点为什么不一定有“爆炸感”

Burst 是瞬间爆发。很多庆祝动画都会从一个中心点喷出大量粒子，形成爆炸感。

但 burst 有一个问题：它非常依赖上下文。

在游戏里，burst 很自然，因为奖励、击杀、升级本来就是强反馈。在 macOS menu bar 工具里，burst 太强就会显得浮夸。用户这次明确说“彩纸特效不要加爆点不好看”，这个判断是对的。

Burst 适合：

游戏结算。
支付成功。
大型 milestone。
首次完成关键任务。

Burst 不适合：

高频状态变化。
工具型产品里的轻量反馈。
已经有 toast 的场景。
背景复杂、可读性重要的场景。

段位晋级当然是好事，但它不是游戏胜利。Argos 的整体调性是克制的 macOS 工具，所以 burst 被删掉是合理的。

Motion Field：自然感来自“方向场”，不是 random

很多粒子系统不好看，是因为用了太多随机数。

随机数只能避免重复，不能自动产生自然感。自然感来自 motion field：一套整体一致的运动方向场。

这次我踩过的坑是：

每条彩带都有随机控制点，但整体没有一致方向。
左右彩带有交叉，但交叉没有空间逻辑。
起点随机，但集中在相近区域，实际观感还是一坨。

也就是说，random 只是 variation，不是 composition。

一个更靠谱的思路是：

1 2	先定义整体动势：从两侧 / 中下区域进入，向中上区域扩散，再缓慢下落淡出再给每个粒子加小随机：角度 ±10°，速度 ±20%，尺寸 ±30%，delay 分层

如果反过来，先给每个粒子随机，再希望整体自然，通常会失败。

Distribution：满不满，取决于分布，不只取决于数量

用户后来反馈“感觉不够满”。第一反应容易是加数量。但只加数量会导致两个问题：

原来空的地方还是空。
原来挤的地方更挤。

所以要区分两个概念：

概念	解决什么
Count	粒子数量
Distribution	粒子分布

这次最终我同时做了两件事：

提高粒子数量：彩纸、亮片、星芒都增加。
扩大覆盖区域：横向更接近全屏，纵向从中下区域扩到中上/中下区域。

这才让画面变“满”。如果只加 count，不改 distribution，只会更乱。

一个实用判断：如果你觉得画面“不够满”，先看热力图，不要先加粒子。

Lifetime：动画太快，本质是生命周期太短

用户一开始还反馈“太快了”。这通常不是单个粒子速度的问题，而是 lifetime 的问题。

Lifetime 包含：

出生 delay。
可见时间。
fade out 时间。
整体 overlay 持续时间。

如果所有粒子几乎同时出现、同时消失，即使速度不快，也会显得“啪一下没了”。如果 delay 分层，粒子批次进入，动画会更有呼吸。

这次我把整体展示时间拉长，并让不同粒子有不同 delay。这样用户看到的是一段庆祝过程，而不是一帧贴图。

Toast：中心信息不能和粒子抢主视觉

这个特效里还有一个中心段位 toast。

Toast 的任务是告诉用户：你升到了哪个段位。粒子的任务是表达情绪。二者不能互相抢。

我中间也犯过一个错误：段位 badge 设计太突兀，颜色和粒子不搭，又不够明显。后来调整为更克制的青山湖风格，用深绿/湖水青承载，标题变大，减少花哨颜色。

这里的原则是：

Toast 负责信息。
粒子负责情绪。
Toast 颜色要稳定，粒子颜色可以跳。
Toast 不要跟粒子一样花。

如果中心信息也花，背景粒子也花，用户就不知道该看哪里。

Canvas 实现：为什么不用一堆 SwiftUI View

这次最终用 SwiftUI Canvas 画粒子，而不是 ForEach 渲染一堆 View。

原因很直接：

方案	优点	问题
多个 SwiftUI View	写起来直观	大量 View diff，动画状态复杂
Canvas	单层绘制，适合粒子	要自己管理坐标、时间、路径

粒子系统本质上是每帧根据时间计算位置，然后画出来。Canvas 更贴近这个模型。

大致结构是：

TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { timeline in
    ConfettiCanvas(
        elapsed: timeline.date.timeIntervalSince(startDate),
        frozen: false
    )
}

elapsed 是整个系统的时钟。每个粒子根据 elapsed - delay 算自己的局部时间，再算 position、rotation、opacity。

这个模型比给每个粒子挂一堆 .animation 更可控。

这次最后留下的系统结构

最终版本可以理解成 3 层：

层级	元素	作用
主粒子层	Confetti rectangles	庆祝语义
辅助粒子层	Circular chips	增加密度和面积
高光层	Diamond glints + cross sparkles	精致感、瞬间感

被删掉的是：

元素	删除原因
Streamers	曲线难自然，抢画面
Burst	太像烟花，不符合产品气质
Heavy bloom	污染背景，可读性差

这个结构其实很朴素，但稳定。

很多 UI 特效最后不是赢在复杂，而是赢在“每个元素都知道自己负责什么”。

我的判断框架

以后再做类似粒子特效，我会按这个顺序判断：

问题	优先调什么
不像庆祝	emitter 方向、颜色亮度、confetti 形状
太乱	删除连续元素，降低 bloom，减少同步运动
不够满	distribution 先于 count
太快	lifetime、delay、fade out
不自然	motion field 先于 random
主信息不明显	toast 层级、粒子避让、颜色对比
廉价	少用爆点和大光晕，控制高饱和面积

一句话：先定语义，再定动势，最后才调随机参数。

要不要用粒子系统

我的判断是：值得用，但要克制。

适合用的场景：

用户完成一个阶段性目标。
系统需要表达奖励。
状态变化低频且重要。
动画不会打断用户工作流。

不适合用的场景：

高频反馈。
错误提示。
信息密集页面。
用户正在专注输入或阅读。

Argos 这次段位晋级适合用粒子系统，因为它是低频、正向、阶段性的反馈。但最终也证明了一点：工具型产品里的庆祝动画，不应该朝游戏化一路狂奔。真正合适的方向是：有情绪，但不喧宾夺主。

这也是我对这次迭代最大的收获。

为什么选 Fumadocs：Node.js 项目接入开箱即用文档站

2026-07-08T15:30:00.000Z

后端服务到了一定规模，文档就成了刚需。不是给外部用户的 README，而是给自己人的：新成员怎么跑起来、接口入参是什么、数据库里几张表是怎么关联的。

我负责的这个 Node.js 后端服务跑着一套自动化平台，随着接口越来越多，”靠脑子记”已经不够了。于是我决定正经做一个内嵌文档站，要求只有一个：好看，且不要花时间调样式。

一句话总结

Fumadocs 是目前我见过最开箱即用的 Node.js 文档框架——接入 OpenAPI 两行命令就能出接口文档，颜值不需要额外调，跟 Midway.js / Egg.js 静态托管的结合也很自然。

选型过程：为什么不选其他的

我评估了以下几个方案：

框架	技术栈	OpenAPI 支持	颜值开箱	备注
VitePress	Vue 3	无官方插件	中等	适合纯文档，定制自由度高但要花时间
Docusaurus	React	docusaurus-plugin-openapi-docs	一般	生态成熟，但 OpenAPI 插件渲染效果不够精致
Nextra	Next.js	有，需要配置	中等	和 Next.js 绑定深，学习成本适中
Mintlify	SaaS	一流	最好看	需要联网托管，私有项目不适合
Fumadocs	Next.js	fumadocs-openapi，官方维护	一流	可自部署，颜值对标 Mintlify

Mintlify 的 OpenAPI 渲染是业内标杆，但它是 SaaS——文档得推到他们的服务器，对内部项目不合适。

Fumadocs 是我找到的唯一一个可以自部署、OpenAPI 一流、不需要调样式就好看的方案。

Fumadocs 的颜值从何而来

设计系统内置

Fumadocs UI 本身是 Tailwind CSS v4 驱动的设计系统，所有颜色、排版、间距都基于 CSS 变量。导入一行 CSS 就能用：

1
2
3

/* app/globals.css */
@import 'fumadocs-ui/style.css';
@import 'tailwindcss';

不需要写主题配置，深色模式自动支持，字体和间距比例都对。

文档布局开箱可用

侧边栏、TOC（目录）、面包屑、代码高亮——这些在大多数框架里都要自己拼，Fumadocs 全部内置：

// app/docs/layout.tsx
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { source } from '@/lib/source';

export default function Layout({ children }) {
  return (
    <DocsLayout tree={source.pageTree} nav={{ title: '我的项目' }}>
      {children}
    DocsLayout>
  );
}

这就是文档布局的全部代码。侧边栏自动从 content/docs/ 的目录结构生成，meta.json 控制排序和分组。

MDX 组件

、、、这些常见 MDX 组件全部内置，写文档时直接用，不需要自己实现。

fumadocs-openapi：两行命令出接口文档

这是我最看重的功能。维护一份 openapi.yaml，然后：

# 安装
npm install fumadocs-openapi

# 从 YAML 生成 MDX 页面
npx fumadocs-openapi generate -i openapi/my-api.yaml -o content/docs/api

生成的每个接口都是一个独立的 MDX 页面，包含：

请求方法 + 路径（带颜色标签）
路径参数 / Query 参数 / 请求体的字段说明和类型
响应示例，支持多状态码
交互式 “Try it” 面板（可选）

效果对标 Mintlify 和 Swagger UI Pro，但完全自部署。

OpenAPI spec 的骨架是这样的：

# openapi/my-api.yaml
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
paths:
  /api/skills:
    get:
      summary: 获取技能列表
      tags: [Skills]
      parameters:
        - name: projectKey
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 技能列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Skill'

写一次 spec，既能生成文档，将来也能用于接口测试和 Mock Server——比手写 Markdown 维护成本低。

怎么和 Midway.js / Egg.js 结合

这里有个有意思的架构问题：文档站是 Next.js 项目，服务端是 Midway.js（Egg.js 底层）。两个进程，怎么变成”一个项目”？

静态导出 + egg-static 托管

Next.js 支持 output: 'export'，构建后输出纯静态文件：

// client/next.config.mjs
const config = {
  output: 'export',      // 输出静态 HTML/JS/CSS，不需要 Node.js 运行时
  images: { unoptimized: true },
};

Egg.js 内置 egg-static 插件，开启后可以托管静态目录：

// src/config/config.default.ts
import { join } from 'path';

static: {
  prefix: '/',
  dir: [join(appInfo.appDir, 'client', 'out')],  // Next.js 导出目录
  dynamic: true,
  preload: false,
},

// src/config/plugin.ts
static: {
  enable: true,
  package: 'egg-static',
},

请求流程：

HTTP 请求
  ↓
egg-static（命中 client/out/ 静态文件 → 直接返回 HTML/JS/CSS）
  ↓
Midway 路由（没有匹配的静态文件 → 走 API 控制器）

也就是说，GET / 返回文档站首页，GET /api/skills 走 Midway 控制器——静态文件和 API 共用同一个端口，完全无感。

本地开发：一个命令同时跑两个进程

生产环境用静态导出。本地开发时，Next.js 需要一个 dev server 做热更新，不能用静态文件。用 concurrently 解决：

// package.json（项目根目录）
{
  "scripts": {
    "dev": "concurrently --names 'server,docs' --prefix-colors 'cyan,magenta' --kill-others-on-fail 'npm run dev:server' 'npm run dev:docs'",
    "dev:server": "cross-env NODE_ENV=local mwtsc --watch --run @midwayjs/mock/app.js",
    "dev:docs": "npm --prefix client run dev"
  }
}

npm run dev 之后，终端里：

cyan 前缀的输出是 Midway 后端（:7001）
magenta 前缀的输出是 Fumadocs（:3000）

Home controller 做一个简单的判断：本地环境没有 client/out/，就重定向到 :3000；其他环境如果 build 缺失就显示一个保底状态页。

// src/controller/home.ts
const CLIENT_INDEX = join(__dirname, '../../client/out/index.html');

@Get('/')
async home() {
  if (existsSync(CLIENT_INDEX)) {
    this.ctx.type = 'html';
    return readFileSync(CLIENT_INDEX, 'utf-8');
  }
  if (this.ctx.app.config.env === 'local') {
    this.ctx.redirect('http://localhost:3000');
    return;
  }
  // 返回保底状态页
}

目录结构

my-server/
├── src/              # Midway.js 后端
│   ├── controller/
│   ├── service/
│   └── model/
├── client/           # Fumadocs 文档站（Next.js）
│   ├── app/
│   ├── content/docs/ # MDX 文档内容
│   ├── openapi/      # OpenAPI spec
│   └── out/          # next build 产物（被 egg-static 服务）
└── package.json      # dev/build 统一入口

版本对齐的坑

Fumadocs 各包的 peer dependency 比较严格，截至写作时：

包	版本	备注
`fumadocs-core`	`^16.9.0`
`fumadocs-mdx`	`^15.0.0`	注意不是 ^12，v15 才支持 core v16
`fumadocs-ui`	`^16.0.0`
`fumadocs-openapi`	`^10.0.0`	要求 core ^16.9、ui ^16.9
`tailwindcss`	`^4.0.0`	v16 ui 内置 Tailwind v4，不再用 v3 preset

fumadocs-mdx 对 Next.js 16 有 optional peer dep，安装时加 --legacy-peer-deps 即可，不影响 Next.js 15 运行。

CSS 配置从 Tailwind v3 的 tailwind.config.ts 改成 v4 的 @import 方式：

@import 'fumadocs-ui/style.css';  /* Fumadocs 设计系统 + Tailwind v4 */
@import 'tailwindcss';             /* 补充 utility classes */
@source '../app/**/*.{ts,tsx}';
@source '../content/**/*.{md,mdx}';

要不要用 / 我的判断框架

适合用 Fumadocs 的场景：

需要 OpenAPI 接口文档，且对渲染效果有要求
项目本身是 Node.js，可以把文档站代码一起放在 repo 里
团队熟悉 React / Next.js（文档站本身就是 Next.js 项目）
不想花时间在文档样式上，要开箱即用

不适合的场景：

项目是纯静态网站 / 博客，VitePress 更轻量
团队技术栈是 Vue，Vitepress 更顺手
需要公开托管 + 自定义域名，Mintlify 的 SaaS 体验更好
对 Next.js 包体积有严格限制（文档站打出来还是有一定体积的）

我的判断：值得上。特别是如果你的项目已经在写 OpenAPI spec，fumadocs-openapi 自动生成这一步能省很多时间，比手写 Markdown 维护成本低，比 Swagger UI 好看一个量级。

Facebook广告预算反推：一天100元想拿2000成效现实吗

2026-07-07T02:45:00.000Z

这两天我在看小说站的 Facebook 投流数据时，遇到一个很典型的问题：一天预算 100 元，想拿到 2000 个成效，怎么做到？

如果只看投放后台，很容易把它理解成「是不是受众太窄」「是不是预算没有花满」「是不是素材还可以优化」。这些都可能对，但第一步不是调后台，而是先做一遍反推。增长问题最后都要落到单位经济模型上，尤其是广告套利这种业务，数学先于手感。

一句话总结

100 元预算拿 2000 个成效，要求单次成效成本降到 0.05 元。 如果当前单次成本是 0.33 元，那就意味着还要再降 85%。这不是常规优化能稳定做到的目标。真正可执行的路径是：先扩受众让 100 元预算稳定花满，再在 0.33 元成本附近逐步放量到约 660 元/天。

先算目标单次成本

这个问题的第一行公式非常简单：

1 2	目标单次成效成本 = 总预算 / 目标成效数 100 / 2000 = 0.05 元

也就是说，如果一天只花 100 元，还要拿 2000 个落地页浏览或类似成效，每一次成效最多只能花 5 分钱。

再对比当前数据：

指标	数值	含义
日预算目标	100 元	希望每天最多花这么多
目标成效	2000 次	希望每天拿到的结果数
目标单次成本	0.05 元	100 / 2000
当前单次成本	0.33 元	已经跑出来的实际成本
需要降幅	约 85%	从 0.33 降到 0.05

这里的关键判断是：0.33 元并不是一个明显偏高的落地页浏览成本。 在 Facebook 上跑冷流量，尤其是内容站、小说站这种非强交易场景，0.33 元已经属于相当低的区间。素材、受众、地域、设备、落地页速度都继续优化，当然可能还能降，但把长期稳定成本压到 0.05 元，不应该作为计划基线。

这不是「单次成本太高」的问题

很多人看到「2000 成效没达成」，第一反应是单次成效费用太高。但这句话要拆成两种情况。

第一种是真的高。比如目标是 0.3 元，当前跑到 2 元，那就是素材、受众、出价或落地页承诺不匹配，要从投放质量上修。

第二种是目标本身不现实。比如目标是 0.05 元，当前是 0.33 元，而且 0.33 元已经在低成本区间，那就不是「优化一下」能解决的问题。继续追 0.05 元，只会把团队带进错误动作：频繁换受众、频繁改预算、过早切换转化目标，最后学习期不断重置，成本反而上升。

我更愿意把它叫做 目标成本错配：预算目标、成效目标、市场真实成本不在同一个平面上。

为什么前面还会说「先扩受众」

在原始数据里还有一个信号：覆盖人数只有 939，展示 1019。这个量级太小了。

如果一个广告组一天只覆盖不到 1000 人，就算单次成本看起来不差，也不能直接判断它有放量能力。原因有三个：

样本太小，CPC/LPV 容易被少量点击扰动。
受众太窄，预算提高后频次会快速上升，CTR 下滑。
算法探索空间不足，Facebook 没法找到更多相似人群。

所以「先扩受众」不是为了让 100 元直接变成 2000 成效，而是为了验证两件事：

要验证什么	为什么重要
100 元能不能花满	花不满说明受众池或出价/审核存在约束
成本能不能维持在 0.33 元附近	只有成本稳定，后续预算放量才有意义

扩受众的动作可以很直接：

动作	目的
用 Advantage+ Audience 或放宽兴趣词	给算法更大的探索空间
地域从单城市扩到省/全国	避免局部受众耗尽
去掉非必要年龄/性别限制	降低系统性 CPM 压力
有数据后建 1%-5% Lookalike	用真实访问者替代人工猜兴趣

这里的阶段目标不是「立刻 2000 成效」，而是「100 元预算能稳定花完，同时成本没有明显劣化」。

真正的预算应该是多少

如果当前单次成本是 0.33 元，目标是每天 2000 次成效，那预算反推是：

1 2	所需预算 = 目标成效数 * 当前单次成本 2000 * 0.33 = 660 元/天

所以答案很直接：要稳定拿 2000 成效/天，预算基线不是 100 元，而是约 660 元/天。

这不是说马上把预算从 100 拉到 660。Facebook 的学习期对预算变化很敏感，突然大幅加预算会让系统重新探索，成本可能被放大。更稳的方式是按 20%-30% 的步长放量：

阶段	日预算	观察周期
1	100 元	2-3 天
2	130 元	2-3 天
3	170 元	2-3 天
4	220 元	2-3 天
5	290 元	2-3 天
6	380 元	2-3 天
7	500 元	2-3 天
8	660 元	稳定观察

每一步只看一个问题：成本有没有保持在可接受范围内。 如果从 0.33 元涨到 0.6 元甚至更高，就说明当前素材或受众承载不了这个预算，需要回头补素材、扩受众或拆广告组，而不是继续硬加。

对小说站投流尤其要克制

小说站这种 AdSense / AdX 变现场景，收入不是一次点击立刻发生，而是由后续阅读页数和广告 RPM 慢慢摊出来。简单写就是：

1 2	单次访问价值 = 平均阅读页数 * 页面 RPM / 1000 利润 = 单次访问价值 - CPC

这意味着 Facebook 端的 CPC 只是上半场。真正决定能不能套利的，还有两个站内指标：

杠杆	解释
平均阅读页数	用户从第 1 章继续读到第几章
页面 RPM	每 1000 次页面浏览能产生多少广告收入

如果站内阅读深度和 RPM 还没稳定，盲目追求低到不现实的 CPC，会让投放策略变形。比如为了便宜点击去投低质量受众，短期 CPC 降了，但用户进站 3 秒就走，最后广告收入更差。

所以我现在更关心的是三层漏斗：

层级	核心指标	判断
广告层	CTR / CPC / CPM	素材能不能把人带进来
落地层	LPV / ViewContent	页面有没有真正加载并开始阅读
阅读层	ChapterRead50 / NextChapterClick / ChapterCompleted	用户是不是继续读

便宜点击不是目标，便宜且会读的点击才是目标。

我的判断框架

以后遇到类似问题，我会按这个顺序判断。

第一步，先算目标成本。

1	目标单次成本 = 预算 / 目标成效

如果目标成本低到明显脱离市场区间，先改目标，不要急着改广告。

第二步，看当前成本是不是异常。

1	当前成本 / 目标成本 = 需要优化的倍数

如果只差 20%-30%，素材和受众优化可能有效。如果差 80% 以上，就要高度怀疑目标不现实。

第三步，看预算有没有花满。

预算花不满，优先扩受众、放宽地域、检查审核和出价。预算能花满但成本上升，说明放量承载能力不足。

第四步，再决定是降本还是加预算。

1	目标预算 = 目标成效 * 可稳定维持的单次成本

用稳定成本反推预算，而不是用愿望预算反推不现实的成本。

要不要用 / 我的判断框架

这次结论很明确：

判断	结论
100 元拿 2000 成效	不作为现实目标
当前 0.33 元单次成本	不是明显偏高，先视为可接受基线
下一步重点	扩受众，让 100 元稳定花满
放量路径	成本稳定后逐步加到约 660 元/天
风险点	过快加预算、频繁改广告组、追求低质便宜点击

我的最终判断是：当前任务不是把 0.33 元硬压到 0.05 元，而是验证 0.33 元能否在更大受众池里稳定复现。 复现成功，再用预算换量；复现失败，再回头修素材、落地页和读者质量。增长不是许愿，先把单位经济模型算清楚，后面的动作才不会跑偏。

macOS 长按 Backspace 删除太慢？改这两个设置

2026-07-06T12:00:00.000Z

用 macOS 写代码或者写文章，有个小事经常让我抓狂：长按 Backspace 删内容，前半秒没动静，开始动了又慢得像在爬。这个体感问题不大，但它会在你每天反复删除、修改、回退的时候持续消耗效率。

一句话总结

系统偏好设置 → 键盘，把「键重复速率」和「重复前延迟」两个滑块都拉到最右边，如果还嫌不够快，用两条终端命令突破 GUI 上限。

在系统设置里调

打开系统设置 → 键盘（直接 Spotlight 搜「键盘」），你会看到类似下面这个界面：

两个关键滑块：

设置项	作用	推荐
键重复速率	长按后每秒触发多少次按键	拖到最右「快」
重复前延迟	按住多久后开始重复	拖到最右「短」

改完立刻生效，不需要重启。

系统设置不够用？用终端突破上限

GUI 滑块有最小值限制，终端可以设置更激进的数字：

# 重复速度（数字越小越快，GUI 最小值是 2，这里设 1）
defaults write NSGlobalDomain KeyRepeat -int 1

# 开始重复前的延迟（数字越小延迟越短，GUI 最小值约 15，这里设 10）
defaults write NSGlobalDomain InitialKeyRepeat -int 10

改完需要注销重新登录才能生效。

单位说明：KeyRepeat 的单位是 15ms/tick，设 1 = 15ms 重复一次（约 66次/秒）；InitialKeyRepeat 单位也是 15ms，设 10 = 150ms 后开始重复。

我的判断框架

值得上：任何重度键盘用户，尤其是写代码、写长文的，改完体感提升很明显，Backspace 终于跟上思维速度了。

可以再等：偶尔写写邮件、主要用鼠标操作的用户，默认值就够了，改太激进反而容易误触删多。

注意：如果用的是外接键盘，部分键盘固件有自己的重复速度设置，系统设置可能对其无效，需要去键盘配套软件里改（比如 VIA、QMK）。

小说站 Facebook 广告版位选择指南

2026-07-06T12:00:00.000Z

我在跑几个英语小说站的流量变现（romance、paranormal、fantasy 题材，AdX 广告收益模式）。Facebook 广告是主要拉新渠道，目标受众是 25-45 岁英语女性读者。

跑了几个月下来，版位选择这件事看似简单，实则有不少坑。记录一下我的判断框架。

一句话总结

动态信息流选 Facebook + Instagram + Instagram 探索，快拍/Reels 看素材，Marketplace 和 Messenger 全跳过。

动态信息流版位

这是流量最大、质量最稳的版位类型，优先配置。

必选：

Facebook 动态 — 基本盘，CPM 稳定，受众覆盖广
Instagram 动态 — 小说受众在 Instagram 的核心阵地，点击质量高
Instagram 探索首页 — 用户在主动发现新内容，意图强，适合拉新

可跳过：

Facebook 主页动态 / Instagram 主页动态 — 量极小，意义不大
Facebook 右边栏 — 纯桌面端，CTR 低得离谱
Threads 动态 — 受众偏科技/新闻，不匹配 romance fiction 读者画像
Facebook 通知 — 广告出现在通知栏，用户体验极差，反感率高

坑：Facebook Marketplace

Facebook 经常在「复制广告组」时默认勾选 Marketplace。去掉它。 Marketplace 的用户在找二手商品，购物心态和阅读心态完全不同，点进小说站后跳出率极高，白烧预算。

快拍 & Reels 版位

这类版位依赖素材格式，不能无脑勾。

前提：素材是竖版视频（9:16）才开，图片素材直接跳过整组。

在有竖版视频素材的情况下：

Instagram 快拍 — 优先，受众活跃
Instagram Reels — 优先，算法推流强，新受众覆盖好
Facebook 快拍 — 次选，补量用
Facebook Reels — 可选，跑量后看 CPM 决定保不保留

跳过：

Messenger 快拍 — 场景割裂，用户不在内容消费状态，CTR 极低
Reels 插播广告 / Reels 内嵌广告 — 素材被强制裁剪，图片广告在这里投放效果极差

搜索结果版位

Instagram 搜索结果 — 值得开。用户主动搜索 romance、dark fiction 等词时出现，意图明确
Facebook 搜索结果 — 跳过。Facebook 搜索使用率极低，量小到忽略不计

别被系统建议带跑

Facebook「复制广告组」时会推荐几条建议，值得单独说一下：

建议	操作
添加 Instagram 版位（降低 23% CPA）	可接受，方向对
将预算增加至与同类广告组一致	跳过，这是 Meta 的增收话术
发送 Messenger 消息	坚决拒绝，会把广告目标从「流量」切换成「对话」，Pixel 事件全断

我的判断框架

版位能不能开，核心看两件事：

受众在不在那里 — romance 读者的主力阵地是 Instagram 和 Facebook 动态，不是 Marketplace、不是 Messenger
素材格式匹不匹配 — 图片素材不要碰竖版视频版位，被系统裁剪后效果等于废

按这两个维度过滤一遍，版位选择基本不会踩坑。

WhatsApp 动态不用考虑，受众集中在印度/巴西/东南亚，和英语小说站的目标市场完全不重叠。

Facebook 广告投小说站：为什么只投 Android，不投 iOS

2026-07-05T13:00:00.000Z

最近在给自己的小说站跑 Facebook 广告，一个不起眼的配置让我琢磨了很久：设备定向要不要排除 iOS？

直觉上觉得应该不排，覆盖更多用户嘛。但实际想清楚之后，我做了一个反直觉的决定：只投 Android，最低 Android 9，iOS 暂时全排除。

这个决策背后有技术原因，不是玄学。

一句话总结

iOS 14.5+ 的 ATT 政策让 Meta Pixel 无法回传事件，广告系列的优化方向会跑偏；在没有 CAPI（Conversions API）的情况下，投 iOS 等于把预算喂给算法噪音。

iOS 信号丢失：不只是归因问题

先讲技术机制。

iOS 14.5 之后 Apple 推出了 ATT（App Tracking Transparency），要求所有应用在追踪用户行为前必须显式获得授权。绝大多数用户选择「不允许追踪」。

这对 Meta Pixel 的影响是致命的：

用户在 FB 上看到广告，点击进入小说站
小说站的 Pixel 代码触发 ViewContent 事件，准备回传给 FB
iOS 系统层面直接拦截，事件永远到不了 Meta 服务器

结果是：FB 的广告系列认为这批 iOS 用户点了广告之后「什么都没发生」。算法会把这批流量标记为低质量，调整投放方向——但这个调整方向是错的，因为信息本身就是残缺的。

更严重的问题是：这不只是归因断裂，而是优化方向整体跑偏。

你以为广告系列在学习「哪些人喜欢看小说」，实际上它在学习「哪些 Android 用户点击了广告」（因为 Android 的 Pixel 信号是完整的）混合「哪些 iOS 用户不知道为什么点了」（信号丢失的噪音）。两个群体混在一起喂给算法，学习效率会被拉低。

为什么选 Android 9 作为最低版本

排除 iOS 之后，还需要设一个 Android 的最低系统版本。我选了 Android 9（Pie），原因很具体：

技术侧：我的小说站用 Next.js 静态导出，前端依赖了几个关键的现代 Web API：

IntersectionObserver：AdSense 懒加载和 ChapterPixel 的章节完成检测都依赖这个 API，Android 8 以上才稳定支持
CSS Grid / Gap / Aspect-ratio：Android 9 以上渲染稳定，Android 8 的 WebView 有已知 bug

运营侧：Android 8 发布于 2017 年，2026 年在用 Android 8 的用户基本是 5 年以上没换机的存量，购买力和活跃度都很低。排除掉这批人不影响核心受众覆盖，还能减少无效曝光。

实际覆盖：最低 Android 9 能覆盖 约 98% 的活跃 Android 用户。

只投 Android 对费用的影响

信号质量之外，设备选择还直接影响投放成本。

CPM（千次曝光成本）：iOS 广告主竞争密度更高，因为多数广告主默认认为 iOS 用户消费力强。实际测下来，仅投 Android 的 CPM 通常低 15–40%，同预算能买到更多曝光。

单次成效费用（CPR）：这个才是核心指标。CPR 低不只因为 CPM 低，更因为归因完整——算法清楚知道哪次点击带来了 ViewContent，出价越来越精准。iOS 混进来后，算法收到的是残缺信号，出价逻辑会变得保守且不稳定。

学习期：Facebook 广告系列需要积累 50 次转化事件才能脱离学习期。Android 信号完整，50 次的门槛更快达到；iOS 混进来后，部分转化事件丢失，学习期被拉长，预算在不确定状态下消耗更多。

什么时候 Android 反而更贵：如果落地页在 Android 低端机上加载慢（碎片化严重），跳出率高会把 CPR 拉上去。这也是为什么要设最低 Android 9——过滤低端慢机，间接保住落地页体验。

操作路径

在 FB 广告管理工具里，广告组层级配置：

广告组 → 版位 → 手动版位

设备类型：仅限移动设备
操作系统：仅限 Android（选移动设备后出现）
操作系统版本：最低 Android 9 / 最高：无

注意：这个设置在「手动版位」里，先切换到手动版位才能看到 OS 筛选项。「进阶赋能型版位（推荐）」模式下无法手动指定 OS。

什么时候回开 iOS

当前排除 iOS 是因为没有 CAPI，信号丢失没有补救手段。有两个条件满足任意一个，就可以考虑回开：

条件一：CAPI 上线。Conversions API 是服务端事件回传，绕过 iOS 的浏览器层拦截，直接从服务器把事件推给 Meta。上了 CAPI 之后，iOS 用户的 ViewContent 等核心事件可以正常回传，算法能重新学习这批用户。

实现门槛不低——静态站（Next.js output: ‘export’）没有运行中的 Node.js 服务器，需要额外部署一个 API 服务（Vercel Function / Cloudflare Worker / AWS Lambda 都可以）。当前日耗 <$50，性价比不足，等规模上来再搞。

条件二：GA4 数据证明 iOS 质量更高。接入 GA4 后，可以按操作系统分组看读者质量指标：人均阅读章节数、平均停留时长、跳出率。如果 iOS 用户这些指标显著优于 Android，那即使信号丢失，从流量质量角度也值得回开——只是归因会不准，但读者是真实的。

我的判断框架

场景	建议
日耗 < $50，没有 CAPI，没有 GA4 数据	只投 Android（当前），先把算法喂干净的信号
GA4 数据显示 iOS 读者质量 ≥ Android	考虑回开 iOS，接受归因不准的代价换流量
CAPI 上线，信号丢失消除	回开 iOS，此时投全量设备效益最大
日耗 > $100，CAPI 还没上	重点关注，Signal Loss 警告会出现，CAPI ROI 开始合算

当前我的判断：可以再等。先把 GA4 接进来，有了读者质量数据之后再决定 iOS 是否值得回开。

这个决策不是永久的，是阶段性的——在信号不完整的情况下，优先喂给算法干净的数据，比追求覆盖面更重要。

Facebook Pixel 接入踩坑全记录：从 AEM 到 ChapterCompleted 触发时机

2026-07-04T18:00:00.000Z

最近在给几个小说站点（Next.js 静态导出）接入 Facebook Pixel 做社交流量变现，过程里踩了一堆坑。这些坑不是 API 文档写错了，而是”文档说清楚了但你不知道这是个坑”——前端转 AI/增长方向最容易踩的那种。

整理成 6 个问题，给同样在做内容站 + FB 投流的人参考。

一句话总结

Facebook Pixel 接入表面是三行代码的事，实际上涉及浏览器追踪、事件分层、两个完全独立的 Meta 后台工具、广告算法优化方向——每一层都有不明显的陷阱。

坑 1：AEM 已死，别再用这个词

接入之前我研究了一堆文章，大量英文资料在讲 AEM（Aggregated Event Measurement）——iOS 14 之后 Meta 引入的事件聚合测量机制，当时限制每域名 8 个优先级事件槽。

结果打开 Meta 事件管理工具，完全找不到 AEM 的配置入口。

原因：Meta 在 2023 年左右悄悄把这套机制改名了，现在叫「广告组转化事件」，UI 路径在广告管理工具 → 广告组 → 广告组转化事件（不在事件管理工具里）。

原来的 8 槽限制也放开了，现在可以正常选任意自定义转化事件作为优化目标，不再有数量硬上限。

教训：看到 AEM 相关资料，先确认发布时间。2023 年之前的文章大概率在讲一个已经不存在的界面。

坑 2：三层事件，搞清楚再动手

这是最容易搞混的一块，我在广告管理工具里死活找不到 ChapterRead50 事件，折腾了很久才搞清楚原因。

FB Pixel 有三种完全不同的东西：

标准事件（Standard Events）

1	fbq('track', 'ViewContent', { content_type: 'chapter', content_name: title })

Meta 内置，有固定的事件名列表（ViewContent、Purchase、Lead、AddToCart 等）。可以直接在广告管理工具里选为优化目标，不需要任何额外配置。

自定义事件（Custom Events）

1	fbq('trackCustom', 'ChapterRead50', { content_name: title, chapter_order: 1 })

你自己取名字，Meta 不认识这个名字。在广告管理工具的转化事件下拉里根本不会出现——这就是我卡住的地方。

自定义转化（Custom Conversions）

在事件管理工具里创建的规则，把自定义事件包装成 Meta 认识的转化目标：规则 = “当收到 ChapterRead50 事件时，记为一次转化”。

创建完自定义转化之后，才能在广告管理工具的广告组里选它作为优化事件。

数据流：

网站代码 fbq('trackCustom', 'ChapterRead50')
  → 事件管理工具接收原始事件
  → 你手动创建自定义转化（规则：事件 = ChapterRead50）
  → 广告管理工具广告组：转化事件选「阅读章节 50%」（这个名字你自己取）

ViewContent 是标准事件，跳过中间步骤直接可选。ChapterRead50 / ChapterCompleted / TimeOnPage30 是自定义事件，必须先包装。

坑 3：ChapterCompleted 触发时机错了

我最开始的实现逻辑：

const onScroll = () => {
  const ratio = window.scrollY / (document.body.scrollHeight - window.innerHeight)
  if (!firedCompleted.current && ratio >= 0.9) {
    firedCompleted.current = true
    fbq('trackCustom', 'ChapterCompleted', payload)
  }
}

看起来没问题——滚动到 90% 触发章节完成。

实际问题：document.body.scrollHeight 包含正文下方的”YOU MIGHT ALSO LIKE”推荐区。这块区域通常占页面高度的 15-25%。

结果：

如果 90% 触发，用户需要滚进推荐区才算”读完”，触发时机太晚
如果改低阈值，推荐区越长的页面误差越大，无法准确对应正文结束位置

正确做法：在正文末尾、推荐区之前放一个哨兵 div：

{/* 正文内容区 */}
<AdsenseSlot slot="9124751639" />

{/* 哨兵：ChapterCompleted 在此触发 */}
"chapter-content-end" />

{/* YOU MIGHT ALSO LIKE 推荐区 */}
"recommendations">...

然后用 IntersectionObserver 监听这个元素进入视口：

const sentinel = document.getElementById('chapter-content-end')
if (sentinel) {
  const io = new IntersectionObserver((entries) => {
    if (entries[0].isIntersecting && !firedCompleted.current) {
      firedCompleted.current = true
      fbq('trackCustom', 'ChapterCompleted', payload)
      io.disconnect()
    }
  }, { threshold: 0.1 })
  io.observe(sentinel)
}

好处：不依赖高度计算，哨兵放哪就在哪触发，推荐区多长都不影响。

坑 4：两个后台工具职责完全不同

很多人（包括我最开始）把事件管理工具和广告管理工具搞混。

工具	URL	干什么
事件管理工具	eventsmanager.facebook.com/events_manager2	数据层：看 Pixel 收到的事件、测试验证、建自定义转化
广告管理工具	adsmanager.facebook.com/adsmanager/manage/campaigns	投放层：建广告系列、选优化目标、设预算、花钱

关键链路：

1
2
3

事件管理工具：验证 ChapterRead50 收到了 → 创建自定义转化
           ↓
广告管理工具：广告组 → 转化事件 → 选「阅读章节 50%」

自定义事件必须先在事件管理工具里”包装”成自定义转化，才能在广告管理工具的下拉列表里出现。两个工具缺一不可，操作有顺序。

另外，事件管理工具显示的状态：

使用中：近期有事件触发
已暂停：0 次事件，Meta 自动暂停——不影响选择，也不需要手动激活，有真实流量触发后自动切回使用中

坑 5：Meta 广告系列目标创建后锁死，必须新建

从冷启动阶段（流量目标 / PageView 优化）升级到 ViewContent 优化阶段，需要的不是”修改广告组的优化事件”，而是新建一条销量目标的广告系列。

原因：广告系列目标（流量 / 销量 / 品牌知名度等）在广告系列层面设置，创建后不能修改。优化事件在广告组层面，但广告组的可用优化事件范围受广告系列目标约束——流量目标的广告系列里，无法选「销量」相关的转化事件。

操作路径：

新建广告系列
  → 广告目标：销量
  → 转化位置：网站
  → 广告组：转化事件选 ViewContent
  → 成效目标：转化量最大化

不要试图在已有的流量广告系列里改，改不了。

坑 6：CAPI 在静态导出站不是零成本

很多教程推荐同时上 Browser Pixel + Conversions API（CAPI），理由是 iOS 14 之后浏览器 Pixel 会丢 20-40% 信号。

这个说法本身没错，但有个前提：你得有服务端。

我的站点用 Next.js output: 'export' 静态导出，全站 HTML/CSS/JS 推 CDN，没有运行中的 Node.js 服务。CAPI 需要从服务端调用 Meta Graph API 回传事件，这意味着：

方案 A：改用 Vercel 部署（支持 Next.js Route Handler），在 app/api/fb-event/route.ts 里回传
方案 B：单独部署 Cloudflare Worker 或 Vercel Function 作为中转
方案 C：Meta 官方 CAPI Gateway（零后端成本，但灵活性差）

每个方案都有额外成本（架构成本或金钱成本）。当前阶段流量不大、日耗不高，浏览器 Pixel 足够，CAPI 等 Events Manager 出现”信号丢失”警告再评估。

另外 CAPI 和 Browser Pixel 同时上报同一事件时，需要用 event_id 去重——前端生成 UUID 写 Cookie，服务端从 Cookie 读同一个 ID 再回传，这套打通有额外工程量。

要不要上 / 我的判断框架

条件	建议
刚接 Pixel，流量 < 1000 UV/天	只上 Browser Pixel，先跑通 ViewContent + 自定义转化流程
ViewContent 稳定 ≥ 50 次/周	新建销量目标广告系列，切 ViewContent 优化
ChapterRead50 稳定 ≥ 50 次/周	考虑升级第三阶段，切 ChapterRead50 优化
Events Manager 出现”信号丢失”	开始评估 CAPI 方案
日广告消耗 > $100	优先上 CAPI，信号准确率的收益大于实现成本

核心判断：先把事件质量做好（正确触发、正确包装自定义转化），再考虑量的问题（CAPI）。顺序搞反了没意义。

Claude Code Skill Token 优化实践：从 162KB 到 117KB

2026-07-04T14:00:00.000Z

给 Claude Code 写自定义 Skill 已经有一段时间了。最近做了一次专项 token 优化，顺手记录一下思路和方法。

一句话总结

Skill 的 reference 文件不是文档，是 context。每 KB 都是运行时成本。按 phase 拆分文件比压缩内容更有杠杆。

背景：Skill 的 token 消耗来自哪里

Claude Code 的 Skill 系统工作原理很简单：用户触发 Skill → SKILL.md 进入 context → 执行时按 phase 按需加载 references/*.md。

理论上”按需加载”已经很省了。但当某个 reference 文件本身就是 162KB，问题就来了：

它被加载时就是 162KB 的 context 消耗
如果这个文件里有一半内容是”当前 phase 不需要的”，那一半就是纯浪费

我的 cover-allure-elements.md 就是这个情况。它同时服务两个 phase：

A2（封面生成）：需要 allure 规则 + costume 模板 + genre prompt 模板
A2.5（插图生成）：只需要 allure 规则 + pose 表 + exposure tier，不需要 genre 完整 prompt 模板（~30KB）

三类优化，效果从高到低

1. 结构性拆分（最高杠杆）

把”不同 phase 的消费者用不同部分”升级为”不同 phase 加载不同文件”。

操作：把 cover-allure-elements.md 里的 15 个 genre prompt 模板（约 380 行、30KB）拆出来，新建 cover-genre-playbook.md。

SKILL.md reference loading 更新：

1 2	A2：加载 cover-allure-elements.md + cover-genre-playbook.md A2.5：只加载 cover-allure-elements.md

效果：每次插图生成任务（A2.5）比之前少加载 27KB。这是结构性节省，不是内容压缩——文件总量没变，但每次调用用到的更少了。

2. 跨文件去重（中等杠杆）

审查发现同一段合规说明出现了三次：

位置	内容	行数
`SKILL.md`	“no nipples/genitals/sex acts”	~8 行
`cover-allure-elements.md §0`	同上，散文版	~12 行
`adsense-arbitrage.md §1.1`	同上，加业务背景	~10 行

处理方式：cover-allure-elements.md §0 保留权威版（因为它被 A2 和 A2.5 都加载，离使用者最近），另外两处改为 1 行 cross-reference：

1	§0 floor: per `cover-allure-elements.md §0` — no explicit content. Suggestive allure fully allowed; push it.

节省约 22 行。规则只在一个地方维护，更新时不会出现三处不同步的问题。

3. 模板压缩（中低杠杆）

cover-allure-elements.md 里有 21 个 costume 类型，每个都是完整的 prompt 模板（visual + best-for + prompt block）。问题在于：模型其实只需要看懂”如何构造 costume 提示词”的方法论，不需要 21 份完整示例。

操作：保留 5 个最高频的 costume（Academy、Nurse、Silk Robe、Evening Gown、Wet White Shirt），剩余 16 个改为一行列举：

Other costume types (same structure — use Fabric Allure Ranking to construct prompts): Flight Attendant, Police, Maid, Qipao, Wedding…

节省约 200 行。模型用 5 个 exemplar 学会方法论，遇到其他类型自行套用。

工具：如何快速找到可优化点

用一个分析 agent 扫描所有 reference 文件，输出：

跨文件冗余：同一内容在哪些文件里出现了多次
verbose prose 转 table：段落式描述是否可以压缩为表格
example 密度：8 个完整示例是否可以替换为 3 个 exemplar + 方法论
重复 preamble：每个文件开头的”为什么这很重要”是否是多余重复

Prompt 给到 agent 时要求输出具体行号和节省估算，否则结果太泛化没法执行。

一个反直觉的结论

内容压缩是锦上添花，结构分离才是关键。

文件从 162KB 压缩到 117KB，感觉很好。但真正节省大的是”A2.5 不再加载 genre playbook”那 27KB——它每次插图任务都生效，是乘法效应。

类比到普通工程：代码优化一个函数（内容压缩）vs 拆出一个只在特定路径加载的模块（结构分离）。后者的效益通常更高，因为它减少的是每次调用的基础成本。

顺带发现的合规问题

facebook-ads.md 全文混用了中文术语（广告系列、广告组、类似受众等）。Skill 文件有一条硬规则：必须用英文写。这不是审美问题，是一致性问题——如果 skill 文件被 agent 加载并转述给另一个 agent，中英混杂会增加解析摩擦。

处理方式是直接 find-replace 全部术语：广告系列 → Campaign，广告组 → Ad Set，类似受众 → Lookalike Audience，等。

要不要做 / 判断框架

值得做：

Skill 被高频调用（每次写章节、每次生图都触发）
单个 reference 文件超过 50KB
同一个文件被不同 phase 消费，但 phase 之间需要的内容有明显差异

可以再等：

Skill 调用频率低（每月几次）
所有 reference 文件都在 20KB 以下
文件内容高度内聚，没有明显的 phase 分离机会

不值得做：

为了”显得更整洁”而拆分（增加维护成本，收益低）
把所有内容压到极限（模型需要足够的示例才能理解方法论，过度压缩反而降质量）

当前 fiction-site-builder skill 的总 reference 文件大约 830KB，按 phase 加载，单次任务实际加载通常在 100–200KB 区间。优化之后高频 phase（A2.5）少了 27KB，低频 phase（A2）靠新的文件拆分仍然能拿到完整 genre 库。

整体感受：token 优化不是”写少一点”，而是”用对粒度”。

Facebook Pixel 事件分层：用错事件等于训练算法找错人

2026-07-04T14:00:00.000Z

在给小说站接 Facebook Pixel 的过程中，我踩了一个坑：把 ScrollDepth25 和 ScrollDepth75 也想着加进 AEM（聚合事件衡量）的优先级队列——毕竟”用户滚动越深说明越感兴趣”，这个逻辑听起来很合理。

后来想清楚了，这是在做一件很蠢的事。

一句话总结

Facebook Pixel 事件分两层——转化事件（优化广告用）和参与度事件（诊断 + 建受众用）——用错层等于给算法喂错信号，Facebook 会去找”爱滚动”的人，不是”爱读小说”的人。

两层事件，本质是信号质量问题

先看 Facebook 优化目标是怎么工作的：

你在 Campaign 里设置”优化 ViewContent”，Facebook 就会把你的广告展示给最可能触发 ViewContent 的人。算法本质是在学习：哪些人口特征、行为特征的人，最容易产生这个事件。

所以核心问题是：你希望 Facebook 去找什么样的人？

这就是事件分层的本质——不同事件代表不同的用户行为，代表不同质量的人群信号。

层级	事件	信号含义	用法
转化事件	ViewContent	打开了章节、开始读	AEM + Campaign 优化目标
转化事件	ChapterRead50	读到章节 50%，真读者	AEM 高优先级
转化事件	ChapterCompleted	读完整章，深度读者	AEM 最高优先级
参与度事件	PageView	点进了网站，包括 1 秒就走的	数据量积累
参与度事件	ScrollDepth25	滚了四分之一，可能在看	受众建模、行为诊断
参与度事件	ScrollDepth75	真的在读这一章	高质量 Lookalike 种子

AEM 的 8 个槽，是资源，不是垃圾桶

iOS 14+ 之后，苹果的隐私政策让大部分 iOS 用户的广告追踪失效。Facebook 的解决方案是 AEM（Aggregated Event Measurement）：你预先申报最多 8 个事件，按优先级排列，Facebook 用差分隐私的方式帮你归因。

关键：只有 8 个槽，而且优先级顺序决定归因逻辑——当一个 iOS 用户触发了多个事件，Facebook 只把转化归因给其中优先级最高的一个。

正确的 AEM 配置应该是：

1	ChapterCompleted (1) > ChapterRead50 (2) > ViewContent (3) > PageView (4)

ScrollDepth25、ScrollDepth75 不应该在这个队列里。原因：

它们不是转化信号，是过程信号
浪费宝贵的 AEM 槽位
如果 ScrollDepth75 的优先级高于 ViewContent，iOS 用户触发了两个事件，归因会错误地落在 ScrollDepth75 而不是 ViewContent

ScrollDepth 有用，但用法不是”优化”

有用，但用法是数据诊断 + 受众分层，不是优化目标。三个具体用途：

1. 诊断广告质量

投一批广告 → 看落地章节的 ScrollDepth75 触发率：

ScrollDepth75 率高 = 这批人真的在读 → 广告找对人了
ScrollDepth75 率低但 ViewContent 高 = 人进来了但不读 → 广告文案/封面和内容不匹配

没有 ScrollDepth，你只知道”有人进来了”，不知道”有没有人在读”。这个区别决定了你该换素材还是换受众，解法完全不同。

2. 建高质量 Lookalike

1	ScrollDepth75 的人 → 建自定义受众 → Lookalike 1%

比用 PageView 或 ViewContent 建的 Lookalike 质量高得多——这批人是确认的真读者，Facebook 会去找特征相似的人，带来的也更可能是真读者。

3. 归因分析

对比 ScrollDepth25 vs ScrollDepth75 的转化漏斗：

1	100 人进章节 → 60 人到 25% → 30 人到 75%

留存率 50%，说明内容前段吸引力还行，后段掉人。这是内容问题，不是广告问题——没有 ScrollDepth 数据，这个判断很难做到。

简单说：ScrollDepth 是侦察兵，不是士兵。

它不直接打仗（优化 Campaign），但告诉你谁在认真读、广告找的人对不对、内容哪里在掉人。没有它，你做投流决策是靠猜的。

一个反直觉的坑：PageView 不是越多越好

初期容易有个误区：PageView 数量越多，数据越充分，广告就越精准。

实际上 PageView 的信号质量是最低的——包含了点进来 1 秒就关掉的人、误点广告的人、爬虫（如果 Pixel 没做过滤的话）。用 PageView 做优化目标，Facebook 学到的是”什么样的人最容易点广告”，而不是”什么样的人最容易读小说”。

PageView 的唯一价值是数据量积累——新账号冷启动阶段，用它帮 Facebook 快速建立人群基础，之后该切的时候要切。

当 ViewContent 积累到 500 次，就应该把 Campaign 优化目标从”落地页点击”切换到”ViewContent”。这一步是投流的质变节点。

我的判断框架

遇到一个新事件，用两个问题判断它的定位：

问题 1：这个事件代表的用户，是我真正想要找到的人吗？

ChapterCompleted 的人 = 读完整章 = 是我想要的人 ✓
ScrollDepth25 的人 = 滚了一点 = 不确定，太模糊 ✗

问题 2：如果 Facebook 去找更多”触发这个事件的人”，找来的人符合预期吗？

优化 ChapterRead50 → 找来的人更可能认真读小说 ✓
优化 ScrollDepth → 找来的人更可能”爱滚动”，不代表会读完 ✗

通过这两个问题的事件 → 放进转化层，可以用作 AEM 和优化目标。
不通过的事件 → 放进参与度层，用来建受众和做诊断。

具体到我们的小说站，最终实现的事件体系：

布置在 layout（全局）：PageView
布置在章节页 mount（进章节触发）：ViewContent
布置在章节页 scroll（读的过程触发）：ChapterRead50、ChapterCompleted、ScrollDepth25、ScrollDepth75

前两层进 AEM 配置和 Campaign 优化目标，后面的 scroll 事件全部留在参与度层做受众和诊断用。这个分层是当前最合理的实现，不过随着数据积累，ChapterCompleted 进 AEM 的时机还需要观察。

小说站 Facebook Pixel 深度配置：用 scroll depth 事件训练算法找「真实读者」

2026-07-04T14:00:00.000Z

做小说站投流，最容易踩的坑是：用 PageView 作为广告优化事件。

PageView 的语义是「有人来了」，而不是「有人读了」。Facebook 算法拿这个信号去优化，会找到「擅长点广告」的人群，而不是「愿意读小说」的人群。结果就是 CTR 看着不错，但用户进来翻一页就走，AdSense 会话 RPM 极低，ROAS（Return on Ad Spend，广告花费回报率 = 广告带来的收入 / 广告花费）算下来根本不打平。

一句话总结

在章节页实装 3 个 Pixel 事件：ViewContent（进入即触发）、ChapterRead50 和 ChapterCompleted（scroll depth 事件），让 Facebook 算法学会找「真正读完一章」的人，而不是「会点广告」的人。

为什么 PageView 是最差的优化信号

小说站的盈利公式：

1	Profit/visit = (会话 RPM × 翻页数/session) / 1000 − Facebook CPC

CPC 固定的情况下，唯一能拉高 ROAS 的是「翻页数/session」。而翻页数取决于用户是不是真的在读——这正是 PageView 衡量不到的。

Facebook 的优化逻辑是：给我 50 个「转化事件」的样本，我帮你找更多像这批人的用户。用 PageView 做样本，找到的是「会点广告的人」；用 ChapterCompleted（读完整章）做样本，找到的是「深度读者」。

Pixel 事件层级设计

我给章节页设计了 6 层事件，覆盖从「进来了」到「读完了」的完整漏斗：

事件	触发	AEM 优先级	用途
`PageView`	全局自动	4（最低）	数据量打底，冷启动用
`ViewContent`	进入章节即触发	3	广告优化主信号，积累 500+ 后切优化目标
`ScrollDepth25`	scroll ≥ 25%	漏斗分析	判断 ch1 开头 hook 是否抓住人
`ChapterRead50`	scroll ≥ 50%	2	强意图信号，AEM 次级优先
`ScrollDepth75`	scroll ≥ 75%	漏斗分析	章节中后段内容质量诊断
`ChapterCompleted`	scroll ≥ 90%	1（最高）	最强信号，Lookalike seed

为什么用 90% 而不是 100%？ 章节页底部有广告位、推荐书目、Share 栏。读完正文后用户视线就停了，不会继续滚到绝对底部。90% 才是实际的「读完」代理指标，100% 在现实中几乎永远不触发。

实现：ChapterPixel 组件

一个轻量的 client component，挂在 chapter page 里，用单个 passive scroll listener + useRef 防重复触发：

'use client'
import { useEffect, useRef } from 'react'

interface Props {
  chapterTitle: string
  chapterOrder: number
  bookSlug: string
}

export default function ChapterPixel({ chapterTitle, chapterOrder, bookSlug }: Props) {
  const fired25 = useRef(false)
  const fired50 = useRef(false)
  const fired75 = useRef(false)
  const fired90 = useRef(false)

  useEffect(() => {
    const fbq = (window as Window & { fbq?: (...args: unknown[]) => void }).fbq
    // ViewContent 进入即触发 — 区分「进来了」和「立刻离开」
    fbq?.('track', 'ViewContent', {
      content_type: 'chapter',
      content_name: chapterTitle,
      content_ids: [`${bookSlug}-ch${chapterOrder}`],
    })

    const payload = { content_name: chapterTitle, chapter_order: chapterOrder }

    const onScroll = () => {
      const total = document.body.scrollHeight - window.innerHeight
      if (total <= 0) return
      const ratio = window.scrollY / total
      const fire = (window as Window & { fbq?: (...args: unknown[]) => void }).fbq

      if (!fired25.current && ratio >= 0.25) {
        fired25.current = true
        fire?.('trackCustom', 'ScrollDepth25', payload)
      }
      if (!fired50.current && ratio >= 0.5) {
        fired50.current = true
        fire?.('trackCustom', 'ChapterRead50', payload)
      }
      if (!fired75.current && ratio >= 0.75) {
        fired75.current = true
        fire?.('trackCustom', 'ScrollDepth75', payload)
      }
      if (!fired90.current && ratio >= 0.9) {
        fired90.current = true
        fire?.('trackCustom', 'ChapterCompleted', payload)
      }
    }

    window.addEventListener('scroll', onScroll, { passive: true })
    return () => window.removeEventListener('scroll', onScroll)
  }, [chapterTitle, chapterOrder, bookSlug])

  return null
}

chapter page 里直接挂上去：

// app/book/[slug]/chapter/[n]/page.tsx
<ChapterPixel
  chapterTitle={chapter.title}
  chapterOrder={chapter.order}
  bookSlug={slug}
/>

几个设计细节值得注意：

useRef 防重复：scroll 事件高频触发，必须用 ref 确保每个深度只上报一次
passive: true：不阻塞渲染线程，对 Core Web Vitals 无影响
fbq optional chaining：Pixel 加载有延迟，防止脚本未就绪时报错
ViewContent 在 mount 而非 scroll：「进入章节」本身就是有效的意图信号，不需要等到用户滚动

FB 后台还需要手动配置

代码侧搞定后，还有两步后台操作才能真正用上这些信号：

1. 创建自定义转化（ChapterRead50 / ChapterCompleted）

Events Manager → 自定义转化 → 新建，选择「自定义事件」→ 选对应事件名。PageView 和 ViewContent 是 Facebook 标准事件，不需要这步。

2. 配置 AEM（聚合事件衡量）

iOS 14+ 之后大部分 iOS 用户拒绝追踪，Facebook 的解法是「申报最多 8 个事件 + 优先级」，信号丢失时归因到优先级最高的可用事件。

路径：Events Manager → 你的 Pixel → 聚合事件衡量 → 配置网络事件

推荐优先级：

1	ChapterCompleted (1) > ChapterRead50 (2) > ViewContent (3) > PageView (4)

ScrollDepth25 和 ScrollDepth75 不加进 AEM——它们是漏斗分析用的，不是广告优化目标。AEM 只配置你真正用于 Campaign 优化的事件。

要不要做 / 我的判断框架

值得立刻做： 任何在跑 Facebook 流量的小说站都应该实装。几十行代码，对投流效果的影响是系统性的——算法找的人不一样，后续所有优化都站在更好的基础上。

可以再等： CAPI（Conversions API，服务端回传）。iOS 信号丢失严重时 CAPI 能补回 30%+ 的归因，但实现复杂（静态导出站需要额外部署 serverless function）。当前阶段流量体量不大，先把浏览器 Pixel 跑稳，等 ViewContent 积累到 500+ 再评估是否上 CAPI。

重点关注： ViewContent 积累到 500 次后，把 Campaign 优化目标从「落地页点击」切换为「ViewContent」，这是整个链路里 CPM 下降最明显的节点。

Claude Code /btw 实践指南

2026-07-04T13:00:00.000Z

做 Agent 开发之后，我越来越在意一件事：上下文的纯净度。Claude Code 在处理一个大型重构任务时，我突然想确认一个之前讨论过的设计决策——如果直接在主对话里问，这个问题和答案会永远留在历史里，影响后续 Claude 的判断。如果开新 session，又要重新铺上下文。

我以前的做法是忍着不问，或者开一个单独的 Claude 窗口。直到我发现了 /btw。

一句话总结

/btw = 不留痕的侧问（有上下文，无工具，答案不进历史）；f to fork = 把这个侧问升级成有完整工具的新主战场。

一、/btw 是什么

/btw 是 “by the way”（顺便问一句）的缩写，在 Claude Code v2.1.72（2026-03-10）引入。

它的核心设计哲学：快速提问，不污染历史。

执行 /btw 你的问题 之后，Claude 会在一个浮层面板里回答，这条问答不会作为 turn 添加到对话历史。主任务继续，上下文保持干净。

与 subagent 的镜像关系

官方文档有一句非常精准的描述：

/btw is the inverse of a subagent: it sees your full conversation but has no tools, while a subagent has full tools but starts with an empty context.

维度	`/btw`	Subagent
上下文	✅ 完整继承主对话	❌ 空白开始
工具访问	❌ 无（只能基于已有上下文回答）	✅ 完整工具
历史污染	❌ 不进入对话历史	结果汇报回主对话
适合场景	快速澄清、上下文查询	后台并行任务

二、结果面板：6 个键盘快捷键

/btw 的答案出现后，浮层面板支持以下操作：

键	操作	说明
`↑` / `↓`	滚动答案	长答案时用
`←` / `→`	切换历史侧问	v2.1.187+，在本 session 的多个 `/btw` 答案间翻页
`c`	复制为 Markdown	推荐方式，原始格式，见下文
`f`	Fork 成新 session	v2.1.161+，见下文
`x`	清除历史侧问列表	清掉面板上方显示的之前问答记录
`Esc` / `Enter` / `Space`	关闭面板	返回主对话提示符

三、c to copy：为什么不用鼠标选？

按 c 会把答案以原始 Markdown 格式复制到剪贴板。

这不是废话——终端渲染文本时会做”硬换行”（hard wrap），鼠标选中复制出来的是被截断的版本，粘贴到 Notion / Obsidian 之后格式全乱。

c 键直接拿的是 Claude 返回的源文本，代码块、标题、列表全部保留，粘贴即用。

四、f to fork：把侧问升级成主战场

这是整个 /btw 功能里最强的一个操作。

按 f 之后，Claude Code 会：

把完整的主对话历史 + 这条 /btw 问答作为 transcript 继承
在此基础上开一个新的独立 session
新 session 有完整的工具访问权限（可以读文件、运行命令、编辑代码）
原始 session 通过 /resume 可随时返回

典型工作流：

# 正在做大型重构，Claude 还在工作
/btw 这个 API 的响应格式对吗？

# Claude 回答：不对，应该是 { data: [], total: number }
# 你觉得需要深入修复，不想打断主任务

f    # Fork 成新 session，继承完整上下文 + 有工具
# 新 session 里：帮我修复这个 API 的响应格式

# 修完之后 /resume 回主任务

Fork vs Branch

	`/btw` + `f`	`/branch`
原 session	继续运行	暂停
新 session	独立开启，有完整工具	你切换过去继续
适合场景	侧问后发现需要深入处理	主动想探索另一条路径

五、与直接在主对话输入的区别

维度	`/btw 侧问`	主对话输入
上下文污染	❌ 不进历史	✅ 永久写入
工具访问	❌ 无	✅ 完整
成本	低（复用 prompt cache）	标准
是否中断主任务	❌ 可在 Claude 工作时插入	✅ 等当前 turn 完成
适合提问类型	澄清、确认、上下文查询	新指令、代码修改

关键点：/btw 可以在 Claude 还在处理响应时插入，不需要等它完成。

六、5 个最有价值的实战场景

场景 1：长任务中途确认设计决策

Claude 正在做 30 分钟的大型重构，你突然想想起来一个细节：

1	/btw 我们之前说的是用 React Query 还是 SWR 管理数据缓存？

快速得到答案，主任务继续，历史不受影响。

场景 2：对话已很长，快速找回前面的信息

50+ turns 的长 session，需要确认一个早期决策：

1	/btw 我们在第几步决定不用 Redux 的？原因是什么？

成本低（命中 prompt cache），不会因为问这个让后续对话偏题。

场景 3：上下文检查，防止 Claude 跑偏

1	/btw 目前你对这个项目的技术栈理解是什么？列一下

用来”探针”Claude 当前的理解是否和你一致，不对就及时修正，而不是等出了 bug 再发现。

场景 4：侧问 + fork 的黄金组合

/btw 这个 SQL 查询有没有 N+1 问题？

# Claude 回答：有，在 getUserOrders 里
f
# 新 session 里处理这个问题，有完整文件访问权限

场景 5：多 subagent 并行时的状态检查

后台跑着几个 subagent，不想打断主对话：

1	/btw 目前正在运行的 subagent 有哪些任务？

七、配合个人工作流的实践建议

我目前在 fwork（飞猪 Cloud GUI Agent）开发中的用法：

任何”确认类”问题优先 /btw，而不是直接问——问完即走，不留污染
每隔 20-30 turns 用 /btw 你对当前任务状态的理解是什么 做一次”探针”
发现侧问答案值得深入时，立即 f fork，不要在主对话里展开
长对话结束前用 /btw 整理关键决策，再用 c 复制到 Obsidian 存档

要不要用 / 我的判断框架

现在就该用：

你经常在长 session 中途想问一个细节，但又担心影响后续上下文
你有”问完发现要深入处理”的场景，f + fork 是完美解法
你在跑多个 subagent，需要快速旁问而不中断主流

注意这些限制：

/btw 没有工具——它不能帮你读文件、运行命令。只能基于已在上下文里的信息回答
如果问题本身需要 Claude 去查代码，还是得在主对话问（或者 fork 出去处理）
←/→ 切换历史侧问需要 v2.1.187+，旧版本没有

重点关注：

f to fork 是 /btw 价值密度最高的功能，但大多数人不知道——记住这个键
复制答案永远用 c，不要鼠标选，格式更干净

Facebook Pixel 从入门到精通

2026-07-04T12:00:00.000Z

我在帮飞猪做 Cloud GUI Agent 的同时，一直在用独立站项目练手 AI Infra 的落地。一个绕不开的问题是：广告数据怎么接？Google Analytics 之外，Facebook Pixel 几乎是独立站的标配。但大多数教程停留在”粘贴代码到 head 里”就完了，而真正让投放起效的细节——事件质量、CAPI 双打、iOS 14 之后的归因——这些从来没人说清楚。

这篇文章，我从前端工程师的角度把整条链路拆开来讲。

一句话总结

Facebook Pixel = 浏览器侧事件（Browser Events）+ 服务端转化 API（CAPI）双打，才能在隐私限制下保住数据质量，进而让算法有料可投。

一、Pixel 是什么，能做什么

Facebook Pixel（现在官方叫 Meta Pixel）是一段 JavaScript 代码，安装在你的网站后，负责把用户行为回传给 Meta，用于：

用途	说明
转化追踪	记录购买、注册、加购等行为，衡量广告 ROI
再营销	对浏览过某页面但未购买的用户重新投放
相似受众	以转化用户为种子，扩展相似人群
广告优化	给算法信号，让 Campaign 朝高转化方向学习

二、安装：最小可用配置

2.1 获取 Pixel ID

2.2 基础代码

把下面这段放进所有页面的里：


<script>
!function(f,b,e,v,n,t,s)
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];
s.parentNode.insertBefore(t,s)}(window, document,'script',
'https://connect.facebook.net/en_US/fbevents.js');

fbq('init', 'YOUR_PIXEL_ID');
fbq('track', 'PageView');
script>
<noscript>
  <img height="1" width="1" style="display:none"
    src="https://www.facebook.com/tr?id=YOUR_PIXEL_ID&ev=PageView&noscript=1"/>
noscript>

fbq('init', ID) 初始化并绑定用户标识，fbq('track', 'PageView') 发送第一个事件。

2.3 在 React / Next.js 中接入

以 Next.js App Router 为例：

// app/layout.tsx
import Script from 'next/script'

const PIXEL_ID = process.env.NEXT_PUBLIC_META_PIXEL_ID

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          id="meta-pixel"
          strategy="afterInteractive"
          dangerouslySetInnerHTML={{
            __html: `
              !function(f,b,e,v,n,t,s){...}(window,document,'script',
              'https://connect.facebook.net/en_US/fbevents.js');
              fbq('init', '${PIXEL_ID}');
              fbq('track', 'PageView');
            `,
          }}
        />
      head>
      <body>{children}body>
    html>
  )
}

strategy="afterInteractive" 让 Pixel 脚本不阻塞 LCP，是 Next.js 推荐方式。

三、标准事件：必须掌握的 9 个

Meta 有一套预定义事件，算法对这些事件有专属优化模型，优先用标准事件，而不是自定义事件。

事件名	触发时机	代码
`PageView`	每次页面加载	自动（init 后自动触发）
`ViewContent`	商品详情页	`fbq('track', 'ViewContent', {...})`
`Search`	搜索结果页	`fbq('track', 'Search', {...})`
`AddToCart`	加入购物车	`fbq('track', 'AddToCart', {...})`
`AddToWishlist`	收藏/心愿单	`fbq('track', 'AddToWishlist', {...})`
`InitiateCheckout`	进入结算流程	`fbq('track', 'InitiateCheckout', {...})`
`AddPaymentInfo`	填写支付信息	`fbq('track', 'AddPaymentInfo', {...})`
`Purchase`	订单完成	`fbq('track', 'Purchase', {...})`
`Lead`	表单提交/注册	`fbq('track', 'Lead', {...})`

Purchase 事件示例（最重要）

fbq('track', 'Purchase', {
  value: 99.00,          // 订单金额，必填
  currency: 'USD',       // 货币代码，必填
  content_ids: ['SKU_001', 'SKU_002'],  // 商品 ID 数组
  content_type: 'product',
  num_items: 2,
  order_id: 'ORD_20260704_001',  // 去重用，强烈建议加
});

ViewContent 事件示例

fbq('track', 'ViewContent', {
  content_name: 'iPhone 16 Pro Case',
  content_ids: ['CASE_IP16P_BLK'],
  content_type: 'product',
  value: 19.90,
  currency: 'USD',
});

四、自定义事件：超出标准事件的场景

当标准事件满足不了需求时，用 fbq('trackCustom', 'EventName', params)：

// 视频播放 25% 时
fbq('trackCustom', 'VideoWatch25', {
  video_title: '产品介绍视频',
  watch_percentage: 25,
});

// 用户点击了特定 CTA
fbq('trackCustom', 'ClickPricingButton', {
  plan: 'pro',
  location: 'hero_section',
});

自定义事件无法用于 Campaign 层级的标准优化目标（如”Purchase”优化），只能用于自定义转化。

五、用户数据匹配：提升命中率的关键

Pixel 默认靠 Cookie 识别用户，但可以传入哈希后的用户数据提升匹配率（Advanced Matching）：

fbq('init', 'YOUR_PIXEL_ID', {
  em: sha256(user.email),         // 邮件（SHA-256）
  ph: sha256(user.phone),         // 电话（SHA-256）
  fn: sha256(user.firstName.toLowerCase()),
  ln: sha256(user.lastName.toLowerCase()),
  ct: sha256(user.city.toLowerCase()),
  st: sha256(user.state),         // 两字母缩写，美国适用
  zp: sha256(user.zipCode),
  country: sha256('us'),
  external_id: sha256(user.userId),  // 自有用户 ID，最重要
});

规范要求：所有字段必须先 SHA-256 哈希、lowercase、trim 后再传入。Meta 在服务端对比自己的数据库，不存储原始 PII。

简易哈希工具（浏览器端）：

async function sha256(message) {
  const msgBuffer = new TextEncoder().encode(message.trim().toLowerCase());
  const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
}

六、Conversions API（CAPI）：iOS 14 之后的救命稻草

为什么需要 CAPI

iOS 14.5+ 的 ATT 框架、Safari ITP、Chrome 第三方 Cookie 限制，导致浏览器侧 Pixel 信号大量丢失，典型症状：

Events Manager 里 Purchase 事件数比实际订单少 30-60%
归因窗口缩短，ROAS 虚低
再营销受众缩水

CAPI 是服务端直接调用 Meta Graph API 发送事件，绕过浏览器限制：

1 2	用户行为 → 你的服务器 → Meta Graph API（CAPI） ↘ 浏览器 Pixel（Browser Events）

两路数据 Meta 会自动去重，合并后的信号质量远优于单路。

CAPI 接入（Node.js 示例）

安装官方 SDK：

1	npm install facebook-nodejs-business-sdk

在订单完成时，从服务端发送 Purchase 事件：

import { FacebookAdsApi, ServerSideApi } from 'facebook-nodejs-business-sdk';
const bizSdk = require('facebook-nodejs-business-sdk');

const { EventRequest, UserData, CustomData, ServerEvent } = bizSdk;

FacebookAdsApi.init(process.env.META_ACCESS_TOKEN);

async function sendPurchaseEvent(order, req) {
  const userData = new UserData()
    .setEmails([await sha256(order.email)])
    .setPhones([await sha256(order.phone)])
    .setExternalId(await sha256(order.userId))
    .setClientIpAddress(req.ip)
    .setClientUserAgent(req.headers['user-agent'])
    .setFbc(req.cookies._fbc)   // Facebook Click ID Cookie
    .setFbp(req.cookies._fbp);  // Facebook Browser ID Cookie

  const customData = new CustomData()
    .setValue(order.totalAmount)
    .setCurrency('USD')
    .setContentIds(order.items.map(i => i.sku))
    .setContentType('product')
    .setOrderId(order.id);

  const serverEvent = new ServerEvent()
    .setEventName('Purchase')
    .setEventTime(Math.floor(Date.now() / 1000))
    .setUserData(userData)
    .setCustomData(customData)
    .setEventSourceUrl(order.pageUrl)
    .setActionSource('website')
    .setEventId(`purchase_${order.id}`); // 去重 ID，与浏览器事件一致

  const eventRequest = new EventRequest(process.env.META_PIXEL_ID)
    .setEvents([serverEvent]);

  return eventRequest.execute();
}

关键字段说明

字段	来源	作用
`_fbc`	Cookie（`fbclid` 参数写入）	追踪来自 Facebook 广告的点击
`_fbp`	Cookie（Pixel 自动写入）	追踪浏览器会话
`event_id`	自定义（保持唯一）	浏览器与 CAPI 去重的核心字段
`action_source`	固定传 `'website'`	告知 Meta 事件来源
`client_ip_address`	从请求头获取	提升匹配率

七、事件去重：防止数据虚报

当浏览器 Pixel 和 CAPI 同时发出同一事件，Meta 用 event_id + event_name 组合去重。两路必须传同一个 event_id：

浏览器端：

const eventId = `purchase_${orderId}_${Date.now()}`;

fbq('track', 'Purchase', {
  value: 99.00,
  currency: 'USD',
  order_id: orderId,
}, {
  eventID: eventId,  // 注意是 eventID，大写 D
});

服务端 CAPI：

1	serverEvent.setEventId(eventId); // 与浏览器端完全一致

八、事件质量评分（Event Match Quality）

Events Manager 里每个事件都有一个 EMQ 分数（0-10），直接影响广告投放效果：

分数区间	判断	优化方向
7-10	优秀	保持
4-6	一般	补充更多用户标识字段
0-3	差	检查是否有 external_id / email 传入

提分策略：

传 external_id（登录用户的 userId 哈希）是最有效的单一操作
同时传 email + phone
接入 CAPI 补充 IP、UA、_fbc/_fbp
确保事件在正确时机触发（购买完成页，而非提交按钮点击时）

九、聚合事件衡量（AEM）：iOS 14 之后必配

iOS 14 之后，针对 iOS 用户的广告归因受 ATT 限制，必须在 Events Manager → 聚合事件衡量 里配置优先级：

最多 8 个事件，按转化漏斗从低到高排优先级
推荐顺序：Purchase > InitiateCheckout > AddToCart > ViewContent > PageView
没有配置 AEM 的事件，iOS 数据几乎为零

十、与 GA4 协同：数据互补而非替代

维度	Meta Pixel	GA4
归因模型	Meta 内部（助攻算法）	数据驱动 / 线性
用户识别	`_fbp` / `external_id`	`client_id` / `user_id`
跨设备	依赖 Meta 账号登录	依赖 GA4 User-ID
适合看什么	广告 ROI、受众效果	全站行为漏斗、留存

两套数据天然不会对齐，不要试图让两者数字一致，应该：

用 Meta Pixel 判断广告素材/受众效果
用 GA4 看站内用户路径和行为质量
订单数据以自己数据库为准（Source of Truth）

十一、调试工具

工具	用途
Meta Pixel Helper（Chrome 插件）	实时查看页面触发了哪些事件，是否有错误
Events Manager → Test Events	输入网址，实时验证服务端 CAPI 数据
Events Manager → Diagnostics	查看事件错误、去重情况
Graph API Explorer	手动发测试 CAPI 请求

用 Pixel Helper 检查时，常见问题：

Pixel ID mismatch：页面上多个 Pixel ID 冲突
No events detected：脚本未正确加载（广告拦截器、CSP 限制）
Duplicate pixel：同一事件触发了两次（SPA 路由切换时 PageView 重复）

十二、隐私合规：不能忽略的法律红线

地区	法规	要点
欧盟/英国	GDPR	必须获得明确同意后才能加载 Pixel
加州	CCPA	提供 “Do Not Sell” 选项
中国大陆	个人信息保护法	境外传输需单独授权

实现方式：接入 CMP（Consent Management Platform，如 Cookiebot、OneTrust），在用户同意后动态加载 Pixel：

// 用户同意后再初始化
window.addEventListener('CookieConsentGiven', () => {
  fbq('init', PIXEL_ID);
  fbq('track', 'PageView');
});

CAPI 在服务端运行，理论上不受客户端 Cookie 限制，但数据回传本身也需要有合法依据（合同履行、合法利益或明确同意）。

十三、内容站套利：优化事件才是最大杠杆

前面十二节的案例几乎都围绕电商（Purchase、AddToCart）。但如果你跑的是内容站 + AdSense/AdX 广告套利模型——比如小说站、文章站——没有 Purchase 事件，优化目标怎么选？这是最容易踩坑的一环。

套利的利润公式

1	每次点击利润 = (平均每次会话 pageviews × RPM / 1000) − Facebook CPC

比如 RPM $8、用户平均浏览 4 页（4 章）：

每次会话广告收入 = 4 × 8/1000 = $0.032 × 4 = $0.128
目标 CPC < $0.10，才有稳定利润空间

这个模型里，广告侧唯一能控制的变量是 CPC 和 受众质量（高质量受众 = 每次会话浏览更多页）。优化事件的选择直接决定算法能不能找到”真实读者”。

优化事件信号质量从低到高

事件	捕捉的是谁	信号质量	可用时机
`PageView`	任何点进来的人，包括 3 秒就走的	最差	立刻可用，但不建议
`ViewContent`（页面加载时触发）	点进来且页面加载完成的	中	积累 500+ 后可用
`ViewContent`（滚动 50% 触发）	真正读了半章的人	最好	积累 500+ 后可用

为什么不能用 PageView 做优化目标： PageView 在落地页加载完就触发，连内容还没看，可能就是广告点击后立刻返回的人。把这个信号喂给算法，等于教它”帮我找更多会点广告但不读文章的人”——会话深度低，每次会话 pageviews 低，套利失败。

内容站的三段 Campaign 路线

第一阶段：冷启动（0–499 ViewContent 事件）

Campaign 目标选 Traffic，优化目标选 Landing Page Views（不是 Link Clicks）。Landing Page Views 需要页面真正加载完成，比 Link Clicks 多过滤一层跳出。

第二阶段：信号足够后切换（500+ ViewContent 事件）

把 Campaign 目标切成 Engagement 或 Conversions，优化目标选 ViewContent。这时算法已经有足够样本，会去找”打开章节页”的人，而不只是”点广告”的人。

注意：ViewContent 触发越晚（比如滚动到 50% 才触发），信号质量越高，但积累速度越慢。可以先用”页面加载时触发”过渡到 500 个，再换成”滚动 50% 触发”重新积累相似受众。

第三阶段：Lookalike 扩量（Custom Audience 500+ 人）

以”触发过 ViewContent 的访客”为种子，建 1% Lookalike。这批人统计上和你最好的读者最像，CPM 可能比兴趣定向高，但 ROAS 通常高 2–4 倍。

在 Next.js 章节页接入 scroll-50% ViewContent

在章节页的 Client Component 里：

'use client'
import { useEffect } from 'react'

export function ChapterScrollPixel({ chapterTitle }: { chapterTitle: string }) {
  useEffect(() => {
    let fired = false

    const onScroll = () => {
      const scrolled =
        window.scrollY / (document.body.scrollHeight - window.innerHeight)
      if (!fired && scrolled >= 0.5) {
        fired = true
        window.fbq?.('track', 'ViewContent', {
          content_type: 'chapter',
          content_name: chapterTitle,
        })
      }
    }

    window.addEventListener('scroll', onScroll, { passive: true })
    return () => window.removeEventListener('scroll', onScroll)
  }, [chapterTitle])

  return null
}

在章节页 Server Component 里引用它：

// app/book/[slug]/chapter/[ch]/page.tsx
import { ChapterScrollPixel } from '@/components/ChapterScrollPixel'

export default function ChapterPage({ params }) {
  const chapter = getChapter(params.slug, params.ch)
  return (
    <>
      <ChapterScrollPixel chapterTitle={chapter.title} />
      {/* 章节内容 */}
    
  )
}

用标准 ViewContent 事件名而不是自定义事件，是因为 Conversion 目标可以直接用它优化——用 trackCustom 就只能配成”自定义转化”，多一步且算法支持的优化模型更少。

与电商 Pixel 的核心区别

电商的转化漏斗有明确终点（Purchase），内容站没有。内容站的”转化”是会话深度：读者在站内翻了多少页，就决定了广告收入多少。因此：

电商：把 Purchase 信号传得越准越好
内容站：把”真正读内容”的信号传得越准越好，ViewContent at scroll-50% 是当前最接近的近似

要不要用 / 我的判断框架

值得现在上：

你在跑 Facebook / Instagram 广告，或计划跑
独立站有真实交易，需要优化 Purchase 转化
想做再营销或相似受众扩量

先把基础做好再说：

网站月 UV 不足 1 万，广告预算不足 $1000/月——此时数据量太少，算法学不动
没有服务端能力接 CAPI——只装浏览器 Pixel 信号损失严重，建议用 Shopify/WordPress 插件替代手写

重点关注：

iOS 14+ AEM 配置是必选项，不是可选项
event_id 去重是 CAPI 双打的基础，漏掉就会数据虚报
EMQ 分数低于 5 分，先补 external_id 和 email 再说其他优化

我目前在 fwork 项目里做 AI Infra，Pixel 是独立站产品的基础设施之一。这篇文章把我踩过的坑和查过的文档整理成了一条可执行的链路——希望对同样在「前端转 Agent/全栈」路上的你有用。

Meta Events Manager 深度指南：让广告数据不再是黑盒

2026-07-04T02:00:00.000Z

我在做小说 H5 站的 Facebook 投流时，踩了一个坑：Pixel 装了，PageView 和 ViewContent 也在触发，但广告优化目标一直跑不起来，CPM 高、CTR 低，算法像是在盲投。

排查了两天，发现根本问题是：我的关键行为事件没有喂给 Meta。读者翻了多少章、停留多久、是否完成了阅读——这些数据 Meta 完全不知道，自然没法找到”高价值读者”来投。

这让我认真研究了一遍 Events Manager。以下是我拆解后的完整认知。

一句话总结

Events Manager 是 Meta 广告的”数据大脑”——你告诉它用户做了什么，它帮你找更多做同样事情的人。

数据质量越高，算法学得越精准，广告效率越高。反过来，数据残缺或质量差，钱就烧在错误的人身上。

Events Manager 是什么

Meta Events Manager（事件管理工具）是 Meta Business Suite 下的一个模块，入口在 business.facebook.com/events_manager。

它做三件事：

管理数据源：Pixel（网站追踪代码）和 Conversions API（服务端追踪接口）
监控事件质量：帮你发现事件丢失、重复、匹配质量低等问题
配置自定义转化：把原始事件组合成广告优化目标

你在这里配置好事件，投放时就能选”以 ViewContent 优化”或”以 Purchase 优化”——Meta 算法会去找最可能完成该行为的用户。

两条数据通路：Pixel vs Conversions API

这是 Events Manager 最核心的架构概念。

Pixel（浏览器端）

Pixel 是一段 JS 代码，运行在用户浏览器里。用户访问页面时，浏览器向 Meta 服务器发送事件请求。

fbq('track', 'ViewContent', {
  content_type: 'article',
  content_ids: ['chapter-5'],
});

优势：部署简单，实时触发，能捕捉页面行为。

劣势：

被广告拦截器屏蔽（iOS Safari、uBlock Origin 等）
iOS 14+ ATT 隐私限制，匹配率下降
浏览器关闭后事件丢失

Conversions API（CAPI，服务端）

CAPI 是从你的服务器直接向 Meta API 发送事件，绕过浏览器限制。

// 服务端（Node.js 示例）
const serverEvent = new bizSdk.ServerEvent()
  .setEventName('Purchase')
  .setEventTime(Math.floor(Date.now() / 1000))
  .setUserData(userData)
  .setCustomData(customData);

new EventRequest(PIXEL_ID, [serverEvent]).execute();

优势：不受广告拦截、iOS 限制影响，数据更完整可靠。

劣势：需要后端开发；用户隐私数据需要哈希处理后发送。

最佳实践：两者并用 + 去重

Meta 官方建议 Pixel + CAPI 同时部署，同一个事件从两条通路都发送：

广告拦截器屏蔽了 Pixel？CAPI 兜底
服务端延迟高？Pixel 先到

但两条通路都发，意味着同一个事件 Meta 会收到两次，必须加 event_id 去重：

// Pixel 端
fbq('track', 'ViewContent', eventData, { eventID: 'chapter-5-view-1720051200' });

// CAPI 端（传同一个 event_id）
serverEvent.setEventId('chapter-5-view-1720051200');

Meta 看到同一 event_id 的两条记录，只计一次。

标准事件 vs 自定义转化

标准事件（Standard Events）

Meta 预定义的 17 个事件，算法天然理解其含义：

事件名	典型场景
`PageView`	任何页面访问
`ViewContent`	查看具体内容（文章、商品详情页）
`Search`	搜索
`AddToCart`	加购
`InitiateCheckout`	开始结算
`Purchase`	完成购买
`Lead`	提交表单 / 注册
`Subscribe`	订阅
`CompleteRegistration`	完成注册

用标准事件的好处：Meta 算法直接懂你在优化什么，不需要额外学习。

对我的小说站，我这样映射：

PageView — 所有页面
ViewContent — 每个章节页
Lead — 模拟”深度阅读”（翻了 3 章以上触发一次）

自定义转化（Custom Conversions）

当标准事件粒度不够时，自定义转化可以组合条件。

示例：想优化”读完第 5 章的用户”

在 Events Manager → Custom Conversions 里配置：

事件：ViewContent
条件：URL 包含 /chapters/ch-005

这样 Meta 会专门找”最可能读到第 5 章”的用户来投放，而不是泛泛地找”会浏览内容的人”。

自定义转化的本质是在标准事件上加筛选漏斗，让算法优化目标更精准。

Event Match Quality：决定你的钱烧得值不值

EMQ（事件匹配质量）是 Events Manager 里最容易忽视但最重要的指标，1–10 分制。

它衡量什么：Meta 能把多少比例的事件匹配回真实用户账号。

EMQ 分段	含义	广告效果
8–10	优秀	算法学习精准，广告 ROI 高
5–7	一般	约 30–50% 事件无法归因
1–4	差	算法几乎在盲投

提高 EMQ 的核心手段：发送更多用户标识符（都需要 SHA-256 哈希后传）：

字段	说明	权重
`em`	邮箱哈希	最高
`ph`	手机号哈希	高
`external_id`	你系统里的用户 ID	中
`client_ip_address`	用户 IP（CAPI 需手动传，Pixel 自动收集）	中
`client_user_agent`	浏览器 UA	中
`fbp`	Pixel cookie（`_fbp`）	中

小说站的匿名访客没有邮箱，我的做法是至少传 IP + UA + fbp，EMQ 能维持在 5–7 分。如果有登录体系，传邮箱哈希能直接拉到 8 分以上。

Event Testing Tool：上线前必跑

入口：Events Manager → Data Sources → 选你的 Pixel → Test Events。

输入网页 URL，打开浏览器模拟用户行为，右侧会实时显示 Meta 收到的每个事件，包括：

事件名是否正确
参数是否完整
是否被去重
匹配到了哪些用户标识符

这是 Debug 神器。每次部署新事件，必须先在 Test Events 里验证，再推生产。

常见问题排查：

现象	原因
事件触发了但 Test Events 没出现	Pixel 代码没正确加载，检查 `window.fbq` 是否存在
事件出现但参数为空	`fbq('track', ...)` 第二个参数写法有误
两条记录只计一次	去重生效，正常
两条记录都被计入	`event_id` 没传，或 Pixel 端和 CAPI 端的值不一致
EMQ 显示 0 或 N/A	没传任何用户标识符，补上 IP + UA + fbp

要不要用 / 我的判断框架

要不要上 CAPI？

场景	建议
纯内容站、无登录、主要靠 Facebook 投流	要上。iOS 拦截 Pixel 的比例越来越高，CAPI 是补全数据的唯一手段
有服务端但没后端开发资源	先用 Meta 的 Conversions API Gateway（托管版，不用写代码）
电商 / 有 Purchase 事件	必上。Purchase 数据残缺直接影响 ROAS
纯品牌曝光、不优化转化	可以暂缓，Pixel 够用

自定义转化值得配吗？

当你的标准事件粒度不够精细，或者想区分”浅度访问”和”深度参与”时，自定义转化值得投入 15 分钟配置。成本极低，收益是算法优化目标的精度。

EMQ 多少够用？

5 分以上可以跑，7 分以上才算健康。低于 5 先排查是不是 IP/UA 没传，再考虑引入登录体系收集邮箱哈希。

Events Manager 本质上是 Meta 算法的”喂料接口”。数据喂得越准、越完整，算法的学习曲线越陡，广告效率越高。作为开发者，这是我们能直接控制的少数几个广告变量之一，值得认真对待。

冷流量 Ch1 钩子：把第一章当 Landing Page 来写

2026-07-04T02:00:00.000Z

我在做一个小项目：用 AI 生成英文言情小说，搭小说 H5 站，跑 Facebook 广告买流量，靠 AdSense/AdX 广告变现，赚中间差价。

听起来很野，但本质是个套利模型：

1	利润 = 单次 session RPM × 每次 session 产生的 pageview 数 / 1000 − Facebook CPC

为了跑通这个模型，我需要解决三个杠杆：L1 是让封面 CTR 够高（广告素材质量）；L2 是让读者翻更多章节（内容深度）；L3 是让广告展示 RPM 够高（广告布局和页面性能）。

这篇讲 L2 里一个具体问题：如何写第一章。

一句话总结

Ch1 的读者是冷流量，他们在前 200 字内决定走还是留——把第一章当 Landing Page 来设计，而不是当小说章节来写。

冷流量读者和暖流量读者的区别

写小说一般假设读者有背景——他们知道这本书的简介，看过评论，或者是老读者回来续读。这是暖流量。

Facebook 广告带来的是冷流量：读者点进来之前只看到了封面图和一句 tagline。他们不知道主角叫什么，不知道故事发生在哪，没有任何情感投入。他们在 200 字内——大概 60 秒——决定：继续读，还是点 Back。

这个决策场景和一个付费广告的 Landing Page 完全一样。区别只是产品换成了小说章节。

所以 ch1 的写作目标不是”交代背景”，而是”让读者感到必须往下读”。

200 字节拍结构

我给 AI 写内容时用了一张节拍检查表，把 ch1 切成 6 个区间，每个区间有明确的交付物：

字数区间	必须完成的事	为什么
0–30 字	落入动作中，主角已经在做某事	建立 POV 和能量，不给读者走神的机会
30–100 字	一个具体细节点出主角的核心问题	让读者有东西在乎，无需解释
100–200 字	引入张力来源（人/情境/物件）	读者必须感到”这要出问题了”
200–400 字	用动作（非叙述）展示她想要什么、什么在阻挡	情感代入；读者必须看到自己或某个原型
400–700 字	第一个意外转折	证明故事会有惊喜，不是慢热消耗
700–结尾	再推一个节拍，用未解决的逆转收尾	强迫读者翻下一章

这张表的核心逻辑：每个区间都在回答”读者为什么不能现在停下来”。

Ch1 的专属硬规则

除了节拍结构，还有几条只适用于 ch1 的约束：

首行禁令

第一句话不能是天气、时刻或场景描写。这是最常见的 AI 生成小说 bug，也是最致命的——冷流量读者在第一句就判断”这不是我要读的东西”。

1
2
3

❌ "城市灯光在 Elena 驻立的顶层窗户下闪烁。"
❌ "自从她最后一次见到他，已经过了三年。"
✅ 某个已经在动作、冲突或决策中的暗示

回忆上限

前 500 字内最多 2 句回忆/背景叙述，且只有当它制造反讽时才允许（她以为的 vs 现在的现实）。背景叙述在 ch1 里是转化杀手。

角色上限

ch1 最多引入 2 个具名角色（主角 + 另一人）。开篇群像场景让冷流量读者无法代入任何人，直接跳出。

对话时机

第一段对话必须在第 300 字前出现。对话意味着人与人之间有事发生，这是言情小说的核心承诺——越晚兑现，跳出率越高。

Facebook Promise 检查

这是我加的一条，纯粹从投放角度来的：定稿 ch1 之前，把广告里的 tagline 重读一遍，确认 ch1 开篇 200 字的情绪基调和 tagline 承诺的一致。

典型违规：tagline 写”一场不该发生的相遇”，ch1 却从主角的日常办公室生活开始，过了 800 字才见面。这不是”悬念”，这是让为”相遇”付了 CPC 的流量失望。

字数目标：更短比更长好

常规章节目标是 1,400–1,800 字。但 ch1 建议取下限（1,400–1,500 字）。

原因很直接：冷流量读者在 7 分钟内读完 ch1 → 立即点”下一章” → 产生第二个 pageview。更长的 ch1 不会让他们更投入，只是延迟了那次点击。

200 字止损测试

写完 ch1 后，我用这个测试验收：

只读前 200 字。假设有人从 Facebook 广告来，除此之外一无所知，他们会感受到什么并想知道接下来发生什么吗？

如果答案是”他们会理解场景设定”——从第 1 字重写。

理解不等于感受。感受才能转化。

要不要用 / 我的判断框架

这套规范有没有价值，取决于你的流量结构：

场景	建议
跑付费广告（Facebook/TikTok）带流量	值得上。ch1 就是你的 landing page，这些规则是 CRO 原则的小说翻译版
SEO 自然流量为主	可以再等。来自搜索的读者有更强的意图，200 字紧迫感要求没那么高
纯粹写给自己看/文学创作	重点关注其他维度。这套规范优化的是转化，不是艺术性

AI 写小说这件事，我越做越觉得它本质是内容产品工程，而不是创作本身。写作规范是 prompt engineering，节拍结构是信息架构，CPC vs RPM 是单元经济——只是产品换成了阅读体验。

这个视角切换之后，很多”写作建议”就能被精确化：不是”第一章要有吸引力”，而是”前 200 字的读者感受必须和广告 tagline 的承诺对齐，否则冷流量 bounce”。

量化之后，才能优化。

用 Claude Code + Remotion 复刻 RunCat 奔跑的猫帧动画

2026-07-03T12:00:00.000Z

macOS 菜单栏那只跟着 CPU 使用率越跑越快的小猫（RunCat），大概是我用过最治愈的系统监控工具。作为一个从前端转 Agent 开发的人，我一直好奇：这种逐帧 sprite 动画，能不能用现代 React 工具链声明式地复刻出来？答案是 Remotion——一个用 React 写视频的框架。这篇文章我用 Claude Code + Remotion 把这只猫从头搭一遍，顺带把「帧动画」这件事讲透。

一句话总结

RunCat 的猫本质只有 5 张 PNG，靠「取模循环 + 定时器间隔」跑起来。Remotion 的纯函数帧模型天生适合表达这种逐帧动画：把「第几帧显示哪张图」写成一个纯函数即可。但要认清边界——Remotion 产出的是渲染好的 GIF/视频资产，不是常驻菜单栏的原生进程。想要真·菜单栏猫得靠 Tauri/Electron，Remotion 负责的是把动画本身优雅地造出来。

先扒开 RunCat：它到底怎么动

很多人以为菜单栏动画是什么黑魔法，扒完源码发现朴素得可爱。RunCat 的核心就三件事。

1. 5 帧 PNG 循环

仓库 Assets.xcassets 里躺着 cat0.png 到 cat4.png，一共 5 帧。帧循环逻辑一行搞定：

1 2	index = (index + 1) % frames.count // 4 之后回到 0，无限循环 statusItem.button?.image = frames[index]

这个 % frames.count（取模）就是所有 sprite 循环动画的灵魂——记住它，等下 Remotion 里还是它。

2. CPU 使用率决定「跑多快」

猫跑多快，取决于定时器的触发间隔。RunCat 的速度公式是：

1	interval = 0.2 / max(1.0, min(20.0, usage / 5.0))

拆开看：

usage / 5.0：把 CPU 百分比缩放一下
min(20, max(1, ...))：钳制在 1~20 倍之间，防止闲时卡成 PPT、满载时快到抽搐
0.2 / 倍率：基础间隔 0.2 秒，倍率越大间隔越短

所以 CPU 越高 → 倍率越大 → 间隔越短 → 换帧越快 → 猫跑得越急。空闲时 0.2 秒一帧，满载时能到 0.01 秒一帧。就这么个反比关系，体感却极其直观。

3. 定时器驱动

1	Timer(timeInterval: self.interval, repeats: true) { self?.next() }

每隔 interval 触发一次 next()，next() 里就是上面那句取模换帧。这是典型的「有状态命令式」动画：一个 index 变量，定时 +1。

记住这个「命令式、有状态」的特征——因为 Remotion 的模型跟它恰好相反，这是本文最值得玩味的地方。

为什么用 Remotion 做帧动画

Remotion 的核心信条只有一句：每一帧都是 useCurrentFrame() 的纯函数。

官方原话是——把你的组件想象成一个「把帧号转换成图像」的函数。每一帧独立渲染，不依赖上一帧的状态。这意味着 CSS 动画、setInterval、requestAnimationFrame 那套在 Remotion 里几乎全部失效，你必须重新用「帧号 → 画面」的思路建模。

对比一下就懂了：

	RunCat（命令式）	Remotion（声明式）
状态	维护一个 `index` 变量	无状态，只读 `frame`
换帧	定时器 `index++`	`Math.floor(frame / n) % 5`
时间	真实时钟（`Timer`）	逻辑帧号（`useCurrentFrame`）
产物	实时菜单栏画面	渲染成 GIF/视频

看出来了吗？RunCat 那句 (index + 1) % 5 的「取模」精神，在 Remotion 里变成了用当前帧号直接算出该显示第几张 sprite——不需要状态，因为帧号本身就是「时间的坐标」。这就是纯函数帧模型的优雅之处。

动手：Claude Code + Remotion 复刻奔跑的猫

第一步：让 Claude Code 起项目

我的做法是直接把需求丢给 Claude Code，让它搭脚手架：

初始化一个 Remotion 项目，创建一个叫 RunningCat 的 Composition：
- 144x144，30fps
- 加载 public/cat/ 下的 0.png~4.png 五帧 sprite
- 根据传入的 load（模拟 CPU 使用率）参数，用 RunCat 的速度公式
  interval = 0.2 / clamp(load/5, 1, 20) 换算成换帧节奏
- 像素图，用 imageRendering: pixelated 保持锐利

npx create-video@latest 起模板后，Claude Code 会把组件、Root.tsx 注册、public/ 资源路径一次性搭好。帧素材可以直接扒 RunCat 仓库 resources/cat/png/ 里的 5 张图，或者让 AI 图像工具生成一套你自己的 5 帧奔跑序列。

第二步：核心 sprite 组件

这是全文的重点。RunCat 的「取模换帧」在 Remotion 里长这样：

// src/RunningCat.tsx
import {
  AbsoluteFill, Img, staticFile,
  useCurrentFrame, useVideoConfig,
} from 'remotion';

const CAT_FRAMES = [0, 1, 2, 3, 4].map((i) => staticFile(`cat/${i}.png`));

export const RunningCat: React.FC<{ load: number }> = ({ load }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  // 照搬 RunCat 的速度公式
  const speed = Math.max(1, Math.min(20, load / 5));
  const secondsPerSprite = 0.2 / speed;            // 每张 sprite 停留的秒数
  const framesPerSprite = Math.max(               // 换算成「视频帧」
    1,
    Math.round(secondsPerSprite * fps),
  );

  // 灵魂取模：帧号 → 第几张 sprite
  const spriteIndex =
    Math.floor(frame / framesPerSprite) % CAT_FRAMES.length;

  return (
    <AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center' }}>
      <Img
        src={CAT_FRAMES[spriteIndex]}
        style={{ height: 144, imageRendering: 'pixelated' }}
      />
    AbsoluteFill>
  );
};

关键就那一行 Math.floor(frame / framesPerSprite) % CAT_FRAMES.length：

frame / framesPerSprite：当前帧对应到「第几个 sprite 周期」
Math.floor(...)：取整，同一张图在多个视频帧里保持不变
% 5：跑完 5 张回到第 0 张——和 RunCat 那句 % frames.count 是同一个灵魂

第三步：注册 Composition

// src/Root.tsx
import { Composition } from 'remotion';
import { RunningCat } from './RunningCat';

export const RemotionRoot: React.FC = () => (
  <Composition
    id="RunningCat"
    component={RunningCat}
    durationInFrames={60}     // 见下方「无缝循环」的坑
    fps={30}
    width={144}
    height={144}
    defaultProps={{ load: 50 }}
  />
);

无缝循环的坑：GIF 要循环不跳帧，durationInFrames 必须是「一个完整动画周期」的整数倍，也就是 framesPerSprite * 5 的倍数。比如 load=50 时 speed=10、framesPerSprite = round(0.02*30)=1，一个周期 5 帧，那 durationInFrames 取 5 的倍数（如 60）才能首尾对齐。这个细节 Claude Code 不一定主动帮你算，得自己盯一下。

第四步：渲染成 GIF

# 基础渲染
npx remotion render RunningCat out/cat.gif --codec=gif

# 透明背景（sprite 是抠好的 PNG 时必备）
npx remotion render RunningCat out/cat.gif --codec=gif --image-format=png

# 降帧压体积：只渲染每 2 帧，30fps → 15fps
npx remotion render RunningCat out/cat.gif --codec=gif --every-nth-frame=2

# 无限循环（GIF 默认就是无限循环，这里显式写出）
npx remotion render RunningCat out/cat.gif --codec=gif --number-of-gif-loops=null

跑完你就得到一只无限循环、背景透明的奔跑猫 GIF，可以塞进博客、README、PPT 或者任何网页。

进阶：让猫「真的」随负载变速

上面 load 是个固定值，猫匀速跑。想复刻 RunCat 那种「负载飙升猫就抽风」的动态感，有两条路。

渲染成动态 GIF：用 interpolate 让 load 随帧号变化，模拟一次 CPU 尖峰：

import { interpolate } from 'remotion';

const load = interpolate(
  frame,
  [0, 45, 90, 135, 180],
  [10, 95, 30, 100, 10],   // 闲 → 爆 → 缓 → 再爆 → 闲
  { extrapolateRight: 'clamp' },
);

一个容易被忽略的深度坑：当速度随帧动态变化时，Math.floor(frame / framesPerSprite) 里的 framesPerSprite 每帧都在变，除法结果不再单调递增，sprite 会跳帧。严格正确的做法是对速度做相位累积（把每帧的换帧增量累加起来），而不是简单除法。RunCat 靠有状态的 index++ 天然规避了这个问题，但 Remotion 的纯函数模型逼你把「累积」显式写出来——这正是命令式转声明式最反直觉的地方。做匀速 demo 可以偷懒用除法，做严肃动态动画就得老实累积。

驱动实时网页版：如果你要的不是视频而是一个活的网页挂件，用 @remotion/player 把同一个组件搬进浏览器，再把真实性能指标喂给 load，就是一个跑在网页里的实时 RunCat。同一份组件，既能渲染成 GIF，又能实时播放——这是 Remotion 相比纯 CSS 动画的一大优势。

Claude Code 在这条流程里加速了什么

说句实在话，Remotion 的 API 不难，难的是「纯函数帧模型」的思维转换。Claude Code 的价值分三层：

脚手架层（省时间）：起项目、配 Composition、连 public/ 资源、写渲染脚本，这些样板活它一把梭。
翻译层（省脑子）：把 RunCat 那句 Swift 的命令式 index++ 翻译成 Remotion 的声明式取模，这种「换范式重写」是 AI 的强项——你给它源码逻辑，它给你目标框架的地道实现。
调试层（省试错）：无缝循环的帧数对齐、动态变速的相位累积这类坑，描述清楚现象后它能直接给修法，比自己翻文档快得多。

但**「取模换帧」的原理、「相位累积」的坑、无缝循环的数学**——这些判断你得心里有数，否则 AI 给的代码你既 review 不了也调不动。这也印证了我一直的观点：AI 拉满执行力，判断框架还得是自己的。

要不要这么搞：我的判断

值得动手：你想给博客/README/演示做一个有辨识度的循环动画，或者想亲手理解「逐帧 sprite 动画」和「声明式帧模型」——RunCat 复刻是绝佳的练手项目，5 帧图、一个取模，麻雀虽小五脏俱全。
别用错工具：你要的是一个常驻 macOS 菜单栏、读真实 CPU 的原生小猫——那 Remotion 不是答案，老老实实用 Swift（RunCat 本体）或 Tauri/Electron。Remotion 造的是动画资产，不是系统进程。
重点收获：真正值钱的不是这只猫，而是**「命令式有状态动画 → 声明式纯函数帧」的思维转换**。理解了 useCurrentFrame 这套模型，你能用 React 声明式地造出几乎任何数据驱动的视频——这才是 Remotion 值得前端认真学一次的原因。

一只 5 帧的猫，串起了 sprite 动画原理、纯函数帧模型、和 AI 辅助的范式翻译。有时候最好的学习项目，就是把一个你每天都在看的小东西，亲手拆开再装回去。

参考来源：menubar_runcat 源码 · Remotion useCurrentFrame 文档 · Remotion 渲染 GIF 文档

Claude Design 上手：前端视角看 Anthropic 的 AI 设计工具

2026-07-03T10:00:00.000Z

Anthropic Labs 在 2026 年 4 月发布了 Claude Design——一个用对话生成设计稿、交互原型、PPT 和营销物料的 AI 工具，由 Claude Opus 4.7 驱动。它被普遍解读为「冲着 Figma 来的」，但作为一个天天在 design-to-code 链路上打转的前端，我更关心的是另一件事：它能读你的 codebase，反过来又能把产物交接给 Claude Code。这篇文章从前端视角讲讲它到底是什么、怎么用，以及要不要现在就上。

一句话总结

Claude Design 的核心卖点不是「又一个 AI 画图工具」，而是把设计系统和代码库打通：它在 onboarding 时读你的 codebase 和设计文件，自动抽出 colors、typography、components 建成一套 design system，之后每个项目都自动套用。对前端来说，这意味着 design-to-code 这条链路第一次有可能从两端同时被 AI 咬合。

Claude Design 是什么

一句话：你用自然语言描述要什么，Claude 生成第一版，然后你通过多种方式细调。

它能生成的东西比想象中广：

真实可交互的 prototype（不是静态图，是能点的）
产品 wireframe 和 mockup
多方向的设计探索（一次给你几套不同风格）
Pitch deck、PPT 演示
营销物料：landing page、社媒素材、campaign 视觉
代码驱动的原型，甚至能带 voice、video、shader、3D 和内置 AI

核心工作流：生成之后怎么改

AI 生成设计的工具不少，Claude Design 真正的差异在细调环节。它给了四种并行的修改通道：

对话（Conversation）：直接跟 Claude 说「这个标题再大一点、配色冷一点」
Inline comments：像在 Figma 里评论一样，圈住某个具体元素批注
直接编辑（Direct editing）：文字可以直接改，不用绕一圈跟 AI 说
自定义 slider：这是最有意思的——Claude 会自己生成调节旋钮，让你实时拖动 spacing、color、layout

第 4 点值得展开。传统 AI 生成图是「抽卡」——不满意就重 roll，全凭运气。而 Claude Design 给你的是参数化的连续控制，而且这些 slider 是它根据当前设计动态生成的，不是固定几个。这在交互范式上比「反复 prompt 重生成」高了一个维度。

对前端最有价值的三个点

抛开「取代设计师」这种标题党，我觉得对前端工程师真正有价值的是这三个能力：

1. 从 codebase 生成 design system

onboarding 时 Claude 会读你的代码库和设计文件，自动建一套 design system——colors、typography、components 全抽出来，之后每个新项目自动套用，保证品牌一致性。团队可以持续打磨这套系统，还能同时维护多套。

对前端来说这解决了一个老大难：设计稿和代码的 design token 对不齐。以前是设计师在 Figma 定一套、前端在代码里再实现一套，两边长期漂移。现在 AI 直接从你已有的代码里反推设计系统，源头就是统一的。

2. Web capture：抓真实产品的元素

它有个 web capture 工具，能直接从线上网站抓取元素，让原型「长得像真实产品」。做增量需求时特别实用——不用从零搭页面骨架，直接抓现有页面来改。

3. 导出 HTML + 交接给 Claude Code

导出选项里有两个对开发者关键：

standalone HTML 文件：产物可以直接是能跑的 HTML
handoff bundle 到 Claude Code：设计稿能打包交接给 Claude Code 继续实现

这就是我开头说的「两端咬合」：Claude Design 从 codebase 读设计系统 → 生成设计和原型 → 再把产物交回 Claude Code 落地成生产代码。整条 design-to-code 链路，AI 从设计端和工程端同时介入。

其他导出格式也齐全：组织内部 URL 共享、保存为文件夹、导出到 Canva、PDF、PPTX。导入同样灵活：text prompt、图片、DOCX/PPTX/XLSX 文档，或直接指向 codebase。

规格与可用性

项目	详情
驱动模型	Claude Opus 4.7（Anthropic 最强的 vision 模型）
状态	Research preview（逐步放量）
可用套餐	Claude Pro / Max / Team / Enterprise
计费	包含在现有订阅内，走标准用量额度，可选额外用量
企业策略	默认关闭，需管理员在 Organization settings 开启

注意它用的是 Opus 4.7 而不是最新的 Fable 5——因为 4.7 是专门强化过 vision 能力的模型，处理设计这种视觉密集任务更合适，这也印证了 Anthropic「按任务选模型」而非「无脑上最新」的思路。

和 Figma / Canva 是什么关系

媒体普遍把它定位成「挑战 Figma」，但我的判断更克制：

它不是 Figma 替代品：Figma 强在多人实时协作、精细的矢量控制、成熟的插件生态和 handoff 流程，这些 Claude Design 现阶段替代不了。
它是 0→1 阶段的加速器：从想法到第一版可交互原型，Claude Design 快得多。适合验证概念、快速出多个方向、做 pitch。
它和 Canva 是导出关系而非竞争：能直接导出到 Canva，说明 Anthropic 没打算做全链路闭环，而是嵌入现有工作流。

所以更准确的说法是：它抢的是「打开 Figma 从空白画布开始」的那部分时间，而不是整个 Figma。

前端视角：这对我们意味着什么

结合我自己从前端转 Agent 开发的路径，谈几点判断：

短期，它是个提效工具。做 landing page、内部工具原型、demo、给 PPM 讲方案的可交互 mockup，这些以前要拉设计师排期的活，现在能自己快速出。前端的「全栈化」又往设计端延伸了一步。

中期，值得关注的是 design system 的自动化。如果 AI 能可靠地从代码反推、并维护设计系统，那设计和研发之间那道「token 对齐」的墙会越来越薄。这对 design system 维护者是个信号。

长期，我更在意的是它作为 agentic workflow 一环的定位——从 codebase 输入到 Claude Code 输出，Claude Design 是把「设计」这个此前很难被 agent 编排的环节，接进了自动化流水线。这才是 AI Infra 视角下真正的看点：不是又多了个工具，而是又一个人类专业环节被纳入了 agent 可调度的范围。

要不要现在就用

我的判断框架：

值得现在就上：你是 Pro/Max 订阅用户，需要快速出原型、demo、pitch deck，或者想验证「从代码生成设计系统」在自己项目上的效果。反正包含在订阅里，试错成本几乎为零。
可以再等等：你的核心诉求是精细的生产级设计协作、复杂的多人 handoff 流程——现阶段 research preview 还不够成熟，继续用 Figma。
重点关注：如果你在做 AI Infra / agentic workflow，Claude Design 的「codebase ↔ 设计 ↔ Claude Code」闭环值得深入研究，它可能是未来 design-to-code 自动化的一块关键拼图。

Anthropic 把它放在 Labs 下、以 research preview 形式发布，本身就说明这是个「探索方向」而非「成熟产品」。但方向选得很准——用 AI 咬合设计和代码的两端，这件事一旦跑通，改变的不只是设计工具市场，而是整个前端的工作方式。

参考来源：Introducing Claude Design by Anthropic Labs · Turn ideas into designs with Claude

Claude Fable 5 发布：有哪些大更新？

2026-07-03T04:00:00.000Z

Anthropic 发布了 Claude Fable 5（model ID：claude-fable-5），这是目前 Anthropic 能力最强的正式发布模型，定位是”最苛刻的推理任务和长程 agentic 工作”。我第一时间把 Claude Code 的默认模型切换了过去，这篇文章梳理一下它相比 Opus 4.8 的大更新，以及写代码接入时要注意的破坏性变更。

一句话总结

Fable 5 的核心卖点不是”老任务做得更好”，而是能做以前模型做不了的事：单次请求自主运行几十分钟的长程任务、可靠的多 sub-agent 并行协作、端到端的企业级交付物。如果你的场景还是分类、摘要、单轮问答，Opus 4.8 依然是更划算的选择。

能力升级

长程 agentic 任务（最大亮点）

单次请求可以自主运行很长时间——复杂任务跑 15 分钟是正常现象。适合的场景包括：

大型代码迁移、重构、通宵编码任务
端到端的企业交付物：财务分析、Excel 表格、PPT、文档
深度研究和长时间的自主工作流

官方给的最佳实践是：在第一轮就给出完整、清晰的任务规格，然后放手让它执行，而不是挤牙膏式地多轮补充需求。

多 sub-agent 协作

以前的模型用 sub-agent 经常翻车，很多团队的 prompt 里都有”不要随便开 sub-agent”之类的压制性指令。Fable 5 反过来了：并行委派子任务非常可靠，能和长期运行的 sub-agent、peer agent 保持异步通信。官方甚至建议主动鼓励它委派：

Delegate independent subtasks to sub-agents and keep working while they run.

其他提升

Code review / debugging：找真实 bug 的能力显著提升（recall 和 precision 都涨了）
Vision：针对密集、模糊、翻转、有噪点的图像做了专门训练，会主动用 bash 和 crop 工具预处理图片
Memory：给它一个可写的 memory 文件（哪怕就是个 .md），跨任务表现明显更好

规格与定价

项目	Claude Fable 5	Claude Opus 4.8
Context window	1M tokens（默认即最大）	1M tokens
Max output	128K	128K
输入价格	$10 / MTok	$5 / MTok
输出价格	$50 / MTok	$25 / MTok
Tokenizer	与 Opus 4.8 相同	—

价格是 Opus 4.8 的两倍。Tokenizer 没变，从 Opus 4.7/4.8 迁移过来 token 数基本不变，只是单价不同。

API 破坏性变更

写代码接入时要注意这几点，都是会直接 400 的硬约束：

1. Thinking 永远开启

不要传 thinking 参数（或只传 {"type": "adaptive"}）。{"type": "disabled"} 和 budget_tokens 都会返回 400。思考深度改用 output_config.effort 控制，档位从 low 到 max：

client.messages.create(
    model="claude-fable-5",
    max_tokens=16000,
    output_config={"effort": "high"},  # 不传 thinking 参数
    messages=[...],
)

值得一提的是，Fable 5 的 low 档表现经常超过旧模型的 max 档，日常任务不用无脑拉满。

2. 原始思维链永不返回

默认 display: "omitted"，thinking 块的内容是空字符串。想看推理摘要要显式设置：

1	thinking={"type": "adaptive", "display": "summarized"}

3. 安全分类器与 refusal fallback

Fable 5 对生物研究和网络安全内容有前置安全分类器，被拒的请求返回 HTTP 200 + stop_reason: "refusal"。问题是良性的相邻工作也可能被误伤（比如安全工具开发、生命科学任务），所以官方建议默认开启 server-side fallbacks——被拒时同一个请求内自动降级到 Opus 4.8 重跑：

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=16000,
    betas=["server-side-fallback-2026-06-01"],
    fallbacks=[{"model": "claude-opus-4-8"}],
    messages=[...],
)

4. 其他硬约束

不支持 assistant prefill（和 4.6+ 系列一致），用 output_config.format 结构化输出替代
Sampling 参数全部移除：temperature / top_p / top_k 都会 400
要求 30 天数据保留：ZDR（零数据保留）组织的所有请求直接 400，排查时别只盯着请求体

Prompting 风格变化

这是迁移时最容易被忽略的一点：为旧模型写的 prompt 往往过于 prescriptive，反而会降低 Fable 5 的输出质量。

旧模型需要你把步骤掰开揉碎写清楚，Fable 5 更适合只描述目标和约束，把”怎么做”留给它自己规划。官方建议迁移后做一轮 A/B 测试，把老的 step-by-step 脚手架删掉对比效果。

另外由于单轮任务可能跑很多分钟，工程上要提前规划好 timeout、streaming 和进度展示，把工作流设计成异步 check-in 的模式，而不是阻塞在一个请求里干等。

要不要升级？

我的判断框架：

值得上 Fable 5：长程自主任务、多 agent 编排、复杂重构、端到端交付物——这些是它独有的能力区间
留在 Opus 4.8：常规编码、日常问答、成本敏感的高频调用——一半的价格，能力足够
留在 Sonnet 4.6 / Haiku 4.5：分类、摘要、大批量的简单任务

对 Claude Code 用户来说，切到 Fable 5 最直观的感受是：单轮跑得更久但更完整，更愿意开 sub-agent 并行干活，最终总结更清晰。偶尔碰到 refusal 误伤时换个表述或临时降回 Opus 4.8 即可。

Agentic System Engineer 成长路线图与学习指南

2026-06-08T14:00:00.000Z

最近在整理 AI Agent 方向的知识体系时，我和 GPT 反复聊了几个来回，生成了一张非常系统的 Agentic System Engineer 专家能力架构图。这张图把从底层工程基础到顶层专家影响力，拆成了七个层次（L1-L7），同时辅以横向的工程素养和业务素养两条维度。

作为全栈开发者，我大部分时间在 JavaScript/TypeScript 和 Node.js 生态里工作，正在往 AI Agent 方向拓展。这张图恰好给了我一个清晰的坐标系——知道自己现在在哪儿，接下来该往哪儿走。这篇文章既是学习笔记，也是一份面向全栈开发者的成长计划。

能力架构总览

这张图的核心路径是：LLM 理解 → Agent 核心 → Runtime / Infra → Grounding & Execution → Evolution → 战略影响力。七个层级层层递进，每个层级下面都有具体的能力点。

层级	名称	核心关键词
L1	通用工程与系统基础	编程语言、算法、OS、网络、数据库、云原生
L2	AI / LLM 能力基础	Transformer、Prompt Engineering、Function Calling、多模态、模型评估
L3	Agent 核心认知	Planning、Memory、Tool Use、State/Context、长期任务、安全约束
L4	Runtime 与基础设施	Agent Runtime、工作流、调度、Sandbox、Checkpoint、可观测性
L5	环境交互与执行能力	Browser Agent、Vision/DOM Grounding、Tool/API 编排、RAG、多 Agent 协同、Human-in-the-loop
L6	自进化与优化系统	Eval 评测、Trajectory/Trace、反馈闭环、Skill Library、Self-Evolve、RL
L7	专家影响力与战略	技术战略、系统架构、方法论、开源影响力、团队带教

两个横向维度同样关键：

横向工程素养：可靠性、可维护性、性能、成本、安全
横向业务素养：产品理解、领域建模、沟通表达、文档写作、业务落地

下面结合我的实际情况，逐层拆解学习计划。

L1：通用工程与系统基础（已具备，持续巩固）

作为全栈开发者，L1 的大部分能力已经覆盖。这里需要重点补充的是：面向 Agent 系统的工程思维。

编程语言：JavaScript/TypeScript 是主力，正在强化 Python（FastAPI、AI Agent 生态），Java 也在学习中。Agent 系统开发中，Python 是 AI 侧的主力，JS/TS 适合前端集成和工具链。
数据结构与算法：基础已具备，需要补充的是图遍历、状态空间搜索等 Agent Planning 相关算法。
操作系统与网络：已有基础，重点看进程隔离、容器化等与 Sandbox 安全执行相关的内容。
数据库/存储：关系型和非关系型都有使用经验，需要补充的是向量数据库（如 Milvus、Pinecone）和 Agent 记忆持久化方案。
云原生/分布式系统：Docker、K8s 有基础，需要深入的是Serverless（FaaS）和事件驱动架构，这对 Agent Runtime 的弹性调度很重要。

行动项：

系统学习向量数据库原理与选型
深入 Docker 安全隔离机制，为后续 Sandbox 设计打基础
补充图算法（DFS/BFS、A*）在 Agent 路径规划中的应用

L2：AI / LLM 能力基础（正在强化）

这是从传统工程师转向 AI 工程师的关键一层。

Transformer / 推理基础：理解 Attention 机制、KV Cache、Token 生成过程。不需要推导所有公式，但要理解模型为什么会产生幻觉、为什么长文本会丢失上下文。
Prompt / Context Engineering：已经大量使用，但要体系化。需要掌握 Chain-of-Thought、ReAct、Self-Consistency 等 Prompt 范式。
Function Calling：这是 Agent 调用工具的基石。要深入理解不同模型（GPT、Claude、Llama）的 Function Calling 实现差异。
多模态理解：Vision 能力正在快速发展，需要了解 GPT-4V、Claude 3 的视觉输入处理机制。
模型评估：掌握 BLEU、ROUGE、BERTScore 等传统指标，更要关注Agent 专用评估方法（如成功率、任务完成率）。
推理成本意识：Token 计费、上下文窗口成本、模型选型策略。生产环境中成本意识决定方案可行性。

行动项：

精读《Attention Is All You Need》，理解 Transformer 核心机制
系统学习 Prompt Engineering 体系，整理一份 Prompt 模式库
动手实现一个支持 Function Calling 的 Agent 原型
对比 GPT-4、Claude 3.5、Llama 3 在相同任务上的成本与效果

L3：Agent 核心认知（重点突破层）

这是 Agent 系统的”内核”。如果说 L2 是理解模型，L3 就是理解 Agent 的本质。

Planning：Agent 如何拆解任务、制定计划。关键概念包括 Task Decomposition（任务分解）、Hierarchical Planning（层次规划）、ReAct（推理+行动循环）。
Memory：短期记忆（上下文窗口管理）、长期记忆（向量存储、知识图谱）。需要理解记忆的检索、压缩、遗忘机制。
Tool Use：Agent 如何发现、选择、调用工具。MCP（Model Context Protocol）是新兴标准，值得关注。
State / Context 管理：Agent 的状态机设计、上下文窗口的滑动窗口策略、多轮对话的状态保持。
长期任务执行：多步骤任务的持久化执行、错误恢复、断点续传。这是从 Demo 走向生产的关键。
安全与约束：输入过滤、输出审查、权限控制、沙箱隔离。Agent 的自主性越高，安全风险越大。

行动项：

用 Python 实现一个 ReAct Agent，包含 Planning + Tool Use + Memory
研究 LangChain、Mastra 的 Memory 实现，对比不同方案
学习 MCP 协议，实现一个自定义 MCP Server
设计一个带状态持久化的 Agent，支持任务中断和恢复

L4：Runtime 与基础设施（从原型到生产）

L3 关注的是单个 Agent 的认知能力，L4 关注的是如何让 Agent 系统在生产环境中稳定运行。

Agent Runtime：Agent 的执行引擎。需要了解 LangChain、Mastra、AutoGen 等框架的 Runtime 设计。
工作流 / 状态机：用状态机或 DAG 编排 Agent 的执行流程。如 LangGraph、Temporal 等。
调度与队列：多 Agent 任务的排队调度、优先级管理、并发控制。
Sandbox / 隔离：代码执行的安全沙箱（如 E2B、Docker Sandbox）、文件系统隔离、网络隔离。
Checkpoint / Durable Execution：执行状态持久化，支持故障恢复。Temporal、Durable Objects 等技术。
可观测性 / 监控：Agent 的调用链路追踪、成本监控、效果评估指标收集。OpenTelemetry、LangSmith 等工具。

行动项：

学习 LangGraph，用状态机方式重构 L3 的 ReAct Agent
研究 E2B 或 Docker 的代码执行沙箱方案，实现安全代码运行环境
集成 LangSmith 或 Helicone，建立 Agent 的监控和追踪体系
学习 Temporal 或类似框架，实现 Durable Execution

L5：环境交互与执行能力（从对话到行动）

这是 Agent “落地”的关键层。Agent 不仅要会思考，还要能与真实世界交互。

Browser Agent：用 Agent 控制浏览器完成网页操作。browser-use、Playwright、Puppeteer 是核心工具。UI-TARS 是新兴的视觉驱动方案。
Vision / DOM Grounding：让 Agent 理解网页视觉内容和 DOM 结构。结合多模态模型的视觉能力。
Tool / API Orchestration：编排多个 API 调用，处理依赖关系、错误回退。MCP 协议在这里扮演重要角色。
RAG / 检索增强：结合向量检索和 LLM，让 Agent 访问外部知识。Sirchmunk（Embedding-Free RAG）是值得关注的新方向。
多 Agent 协同：多个 Agent 分工协作，如经理 Agent 分配任务、专家 Agent 执行。AutoGen、CrewAI 等框架。
Human-in-the-loop：关键决策点引入人工确认，平衡自动化和可控性。

行动项：

用 browser-use 实现一个自动化的网页数据抓取 Agent
集成 RAG 能力，让 Agent 能查询文档知识库（尝试 Sirchmunk）
用 AutoGen 或 CrewAI 搭建一个多 Agent 协作系统
实现 Human-in-the-loop 机制，设计关键决策的人工确认流程

L6：自进化与优化系统（从静态到动态）

让 Agent 系统能够持续学习和改进，而不是每次都从零开始。

Eval 评测体系：建立 Agent 任务的评估数据集和指标。这是优化的前提。
Trajectory / Trace：记录 Agent 的完整执行轨迹，用于分析和调试。
反馈闭环：将执行结果反馈给 Agent，形成学习循环。成功/失败案例的积累。
Skill Library：Agent 学习的技能库，可复用的工具组合和策略模板。
Self-Evolve：Agent 自主改进自身 Prompt、工具选择策略。
策略优化 / RL：用强化学习优化 Agent 的决策策略。DPO、PPO 等算法在 Agent 优化中的应用。

行动项：

为自己的 Agent 项目建立 Eval 数据集和评估流程
设计反馈收集机制，记录每次任务的执行轨迹和结果
实现 Skill Library，积累可复用的 Agent 技能模板
了解 DPO（Direct Preference Optimization）在 Agent 优化中的应用

L7：专家影响力与战略（长期目标）

这是从工程师到专家、从技术执行到技术领导的跨越。

技术战略：Agent 技术的演进方向判断、技术选型决策、团队技术路线规划。
系统架构：设计大规模 Agent 系统的整体架构，考虑扩展性、可靠性、成本。
方法论输出：沉淀 Agent 开发的工程方法论，形成可复用的框架和最佳实践。
开源影响力：参与或主导开源 Agent 项目，建立技术影响力。FastGPT、Mastra 等。
团队带教：培养团队成员的 Agent 开发能力，建立知识传承机制。
跨部门协同：与产品、运营、业务团队协作，推动 Agent 技术在实际业务中落地。

行动项：

在 GitHub 上持续贡献 Agent 相关开源项目
沉淀 Agent 开发方法论，整理成内部文档或开源项目
主动承担团队 Agent 方向的技术规划和选型工作
结合飞猪业务场景，探索 Agent 在旅游/出行领域的落地机会

横向素养：贯穿始终的两条隐线

横向工程素养

Agent 系统对工程素养的要求比传统应用更高：

可靠性：Agent 的自主性意味着错误可能被放大，需要有完善的熔断、降级机制。
可维护性：Agent 的 Prompt 和策略需要版本管理，配置变更需要可追踪。
性能：LLM 调用是瓶颈，需要优化调用次数、使用缓存、并行化非依赖步骤。
成本：Token 消耗是持续成本，需要在效果和成本间做权衡。
安全：Agent 能执行代码、访问外部系统，安全风险成倍放大。

横向业务素养

技术最终要服务于业务：

产品理解：理解 Agent 产品的用户场景和价值主张。
领域建模：将业务领域知识结构化，供 Agent 理解和使用。
沟通表达：Agent 系统的复杂性要求清晰的文档和沟通能力。
文档写作：Prompt 工程本质上就是”面向模型的文档写作”。
业务落地：从 POC 到生产环境，推动 Agent 在真实业务中产生价值。

个人学习路线与时间安排

基于以上分析，结合日常工作节奏，制定如下学习计划：

第一阶段（1-3 个月）：夯实基础

重点：L2 + L3

周 1-2：系统学习 Transformer 原理，精读 Attention Is All You Need
周 3-4：Prompt Engineering 体系化学习，整理 Prompt 模式库
周 5-6：Function Calling 实现，动手写 Agent 原型
周 7-8：Memory 系统设计，实现短期+长期记忆
周 9-10：ReAct / Planning 模式深入
周 11-12：安全与约束机制设计

产出物：一个具备 Planning + Memory + Tool Use 的 Agent 原型

第二阶段（4-6 个月）：走向生产

重点：L4 + L5

月 4：学习 LangGraph / Mastra，用状态机重构 Agent
月 5：集成 Sandbox 安全执行环境
月 6：建立可观测性体系（追踪 + 监控 + 日志）
月 7：Browser Agent 实战（browser-use / UI-TARS）
月 8：RAG 系统集成（向量检索 + Embedding-Free 方案）
月 9：多 Agent 协同系统搭建

产出物：一个具备完整 Runtime + 环境交互能力的生产级 Agent 系统

第三阶段（7-9 个月）：持续进化

重点：L6 + 横向素养

月 10：建立 Eval 评测体系
月 11：实现反馈闭环和 Skill Library
月 12：成本优化与性能调优
持续：文档写作、方法论沉淀、开源贡献

产出物：可自进化的 Agent 系统 + 一套完整的方法论文档

第四阶段（10-12 个月）：建立影响力

重点：L7

主导团队 Agent 技术方向
开源项目持续贡献
结合业务场景推动 Agent 落地

学习资源推荐

基础理论

《Attention Is All You Need》— Transformer 起源
《ReAct: Synergizing Reasoning and Acting in Language Models》— Agent 基础范式
《Reflexion: Self-Reflective Agents》— 自我反思 Agent
《Let’s Verify Step by Step》— 推理过程验证

框架与工具

LangChain / LangGraph：Agent 开发主流框架
Mastra：新兴的 TypeScript-first Agent 框架
AgentScope：阿里巴巴开源的多 Agent 框架，支持多模态、多智能体协同，内置丰富的对话管理和工具编排能力
browser-use：浏览器自动化 Agent
MCP（Model Context Protocol）：工具调用标准协议
E2B：代码执行沙箱
Temporal：Durable Execution 框架

GitHub 课程与实战仓库

以下仓库按学习阶段分类，从入门到进阶，覆盖理论与实战：

系统入门课程

仓库	层级对应	简介
datawhalechina/hello-agents	L2-L5	Datawhale 出品的系统教程（6.3k+ Star），中文社区最完善的 Agent 入门课程。5 部分 16 章：Agent 基础 → 手写 Agent 框架（ReAct/Plan-and-Solve）→ 低代码平台（Coze/Dify/n8n）→ 进阶主题（Memory/RAG、MCP/A2A/ANP、Agentic-RL）→ 实战项目（智能出行助手、DeepResearch Agent、Cyber Town）。含自研 `hello_agents` 教学框架，从第一性原理构建 Agent
microsoft/ai-agents-for-beginners	L2-L4	微软官方 12 课入门课程，含视频、文档和代码。覆盖 Tool Use、Agentic RAG、多 Agent 设计模式、生产部署、MCP/A2A 协议。使用 Azure AI Foundry、Semantic Kernel、AutoGen
GeneArnold/AI-Agent-Engineering-Course	L2-L5	7 周渐进式课程，专为 Claude Code 辅助学习设计。从单 Agent → Memory Agent → 多工具 Agent → 多 Agent 系统 → 视觉识别 Agent，含 MCP 覆盖
zkzkGamal/Agentic-AI-Tutorial	L2-L4	5 章综合教程：LLM Provider 基础 → LangChain 编排 → RAG/Memory 基础设施 → Agent Graph 模式（ReAct、Human-in-the-loop）→ LangGraph + MCP Runtime
NirDiamant/GenAI_Agents	L3-L5	45+ 个 Jupyter Notebook 项目，从基础到高级，每个项目含详细说明和可运行代码。覆盖 RAG、多 Agent、工具调用等场景

实战工作坊（项目驱动）

仓库	层级对应	简介
iusztinpaul/designing-real-world-ai-agents-workshop	L4-L5	生产级多 Agent 系统实战：构建 Deep Research Agent + LinkedIn 写作工作流，以 MCP Server 方式提供服务。含代码、PPT、视频和自学路径
antonacio/intro-to-ai-agents	L3-L4	手把手构建和编排 Agent 系统：Research Agent、RAG Agent、Web Search Agent、Math Agent，适合快速上手
coleam00/ai-agents-masterclass	L3-L5	YouTube 视频系列的配套代码，逐步构建实用 Agent，适合跟着视频边做边学
ed-donner/agents	L2-L4	6 周 Agent 工程课程，从编码到部署的完整流程

从零实现（不依赖框架）

仓库	层级对应	简介
pguso/ai-agents-from-scratch	L2-L3	用 Node.js + 本地 LLM（node-llama-cpp）从零实现 Agent，理解底层原理。无需 API Key，完全本地运行。配套网站 agentsfromscratch.com
proflead/how-to-build-ai-agents-from-scratch	L3	基于 Google ADK 和 Gemini 2.5 Flash Lite，构建 Research → Summarizer → Coordinator 多 Agent 系统
SRafi007/ai-tutorial-crew	L3-L4	CrewAI + Ollama 本地 LLM 实现多 Agent 协作：自动研究、写作、审阅 Python 教程。零 API 成本

Awesome Lists（资源导航）

仓库	用途
artnitolog/awesome-agent-learning	Agent 学习资源汇总，含课程、论文、框架教程、评测基准
e2b-dev/awesome-ai-agents	AI Agent 框架、库、研究论文的精选列表，区分开源和闭源方案
punkpeye/awesome-mcp-servers	按类别整理的 MCP Server 集合（浏览器自动化、代码执行、云服务等）
Shubhamsaboo/awesome-llm-apps	LLM 应用集合，含 Agent、RAG、MCP 等实际项目

评估与优化

LangSmith：Agent 监控和评估平台
Helicone：LLM 可观测性工具
OpenAI Evals：模型评估框架

博主与频道推荐

持续跟踪 Agent 领域的最新动态，除了文档和论文，关注一线从业者的分享同样重要。以下按方向分类推荐：

X (Twitter)

博主	方向	简介
@hwchase17	Agent 框架	LangChain / LangGraph 创始人，Agent 框架演进的权威声音
@karpathy	AI 基础	Andrej Karpathy，AI 教育内容标杆，讲解深入浅出
@swyx	AI 工程化	Shawn Wang，Latent Space 播客主理人，AI Engineering 趋势追踪
@goodside	Prompt Engineering	Riley Goodside，OpenAI Prompt Engineering 专家
@jxnlco	LLM 工程化	Jason Liu，OpenAI 工程师，LLM 工程实践最佳
@gregpr07	Browser Agent	browser-use 联合创始人，第一手更新和实现思路
@karpulix	多 Agent 协同	CrewAI 创始人，多 Agent 协作的实践者
@rlancemartin	RAG	LangChain RAG 负责人，RAG 技术演进第一手资料
@BeibinLi	多 Agent 框架	AgentScope（阿里开源）核心作者
@simonw	工具集成	Simon Willison，AI 工程化和工具集成领域的多产作者

YouTube

频道	方向	简介
Andrej Karpathy	AI 基础	从 Transformer 到 GPT 的底层原理讲解，适合夯实 L2
DeepLearning.AI	系统课程	Andrew Ng 的短课程系列，Prompt Engineering、RAG、Agent 都有
Sam Witteveen	LangChain 实战	Google Developer Expert，大量 LangGraph 实战教程
James Briggs	RAG / 向量检索	Pinecone 开发者，向量数据库和 RAG 最佳实践
Mastra	TypeScript Agent	官方频道，TypeScript-first Agent 框架，技术栈匹配度高
Latent Space	播客访谈	swyx 主理，每期访谈一线从业者，了解行业真实进展
AI Explained	行业动态	每日 AI 新闻速递，适合快速了解行业热点

关注策略建议：日常刷 X 追踪框架更新和行业热点（@hwchase17、@gregpr07、@swyx），周末看 YouTube 深度内容夯实基础（Andrej Karpathy、DeepLearning.AI），项目驱动时跟着实战教程边做边学（Sam Witteveen、James Briggs）。

每日2小时学习规划

以上路线图覆盖 12 个月，但大多数在职开发者每天能抽出的时间有限。以下是一份基于每天 2 小时、以工作日为主的执行方案，核心原则是小步快跑、项目驱动、周末做整合。

时间块分配

时段	时长	内容
理论学习	40 min	读文档、课程章节或论文，理解概念并记关键笔记
动手实践	60 min	写代码、跑示例、调 Prompt，必须产出可运行的代码
复盘整理	20 min	写学习日志、整理代码片段、画思维导图，沉淀为可复用知识

建议固定时间段（如早 7:00-9:00 或晚 21:00-23:00），降低启动成本。

周末弹性安排

周末不强制加量，但建议完成两件事：

周项目冲刺（2-3 小时）：把本周零散实践整合成一个完整功能点
补进度/深度阅读：处理本周遗留，或精读一篇论文

第一阶段（1-3 月）：L2 + L3，打地基

目标：产出一个具备 Planning + Memory + Tool Use 的 Agent 原型。

周次	理论学习（40 min）	动手实践（60 min）	关键产出
1-2	跟读 `hello-agents` Part 1（Agent & LLM 基础），配合 Andrej Karpathy 的 Transformer 视频	用 Python 复现简单的 Attention 计算；搭建本地开发环境（uv + Python 3.11）	环境就绪 + Attention 草稿
3-4	系统学习 Prompt Engineering，整理 Chain-of-Thought、ReAct、Self-Consistency 模板	给同一个任务写 3 种不同 Prompt，对比输出效果；记录到个人 Prompt 模式库	Prompt 模式库（10+ 模板）
5-6	精读 `hello-agents` Part 2（手写 Agent 框架），理解 ReAct 循环	实现一个最简单的 ReAct Agent：输入 → Thought → Action → Observation → 输出	ReAct Agent v0.1
7-8	学习 Memory 设计：短期记忆（上下文窗口）+ 长期记忆（向量存储）	给 Agent 加短期对话历史；接入 ChromaDB/FAISS 做长期记忆检索	带记忆的 Agent v0.2
9-10	学习 Tool Use 和 MCP 协议；读 `hello-agents` 的 MCP/A2A 章节	给 Agent 注册 2-3 个工具（计算器、搜索、文件读取）；尝试写一个简易 MCP Server	带工具调用的 Agent v0.3
11-12	学习安全约束：输入过滤、输出审查、权限控制	给 Agent 加输入校验、输出敏感词过滤、工具调用权限白名单	带安全约束的 Agent v0.4

阶段产出：一个可运行的 ReAct Agent（Python），支持 Memory + Tool Use + 基础安全。

第二阶段（4-6 月）：L4 + L5，走通生产

目标：把原型升级为具备 Runtime + 环境交互能力的系统。

月次	理论学习（40 min）	动手实践（60 min）	关键产出
4	学习 LangGraph 状态机；读 `microsoft/ai-agents-for-beginners` 的 Design Patterns	用 LangGraph 重写第一阶段的 Agent，用状态机管理执行流程	LangGraph 版 Agent
5	研究 E2B/Docker Sandbox；学习 Temporal/Durable Execution	给 Agent 加一个代码执行沙箱；实现任务断点续传	带 Sandbox 的 Agent
6	学习可观测性：OpenTelemetry、LangSmith/Helicone	接入 LangSmith，记录每次调用的 Token 消耗、延迟、执行轨迹	可监控的 Agent 系统
7	学习 browser-use/UI-TARS；读 `hello-agents` 的实战项目章节	用 browser-use 实现一个自动登录 + 抓数据的 Agent	Browser Agent
8	学习 RAG：向量检索 + Sirchmunk（Embedding-Free）	给 Agent 接入文档知识库，支持基于自有文档的问答	RAG-enabled Agent
9	学习多 Agent 协同：AutoGen/CrewAI；读 `hello-agents` 的 Cyber Town	搭建 2-3 个 Agent 协作：Planner + Worker + Critic	多 Agent 协作系统

阶段产出：一个生产级 Agent 系统，具备状态机、沙箱、可观测性、Browser 能力、RAG、多 Agent 协同。

第三阶段（7-9 月）：L6 + 横向素养，持续进化

目标：让系统能自我改进，沉淀方法论。

月次	理论学习（40 min）	动手实践（60 min）	关键产出
10	学习 Eval 体系：成功率、任务完成率、轨迹质量	为自己的 Agent 设计 10-20 个测试用例，建立自动化评估	Eval 数据集 + 评估脚本
11	学习反馈闭环和 Skill Library 设计	实现执行轨迹记录；把常用工具组合抽象成可复用的 Skill 模板	Skill Library（5+ 模板）
12	学习成本优化：缓存策略、模型降级、并行化	给系统加 Redis 缓存、非关键步骤用便宜模型、并行调用无依赖工具	成本优化后的系统

阶段产出：可自进化的 Agent 系统 + 一套内部方法论文档。

第四阶段（10-12 月）：L7，建立影响力

目标：从个人学习转向团队价值和开源贡献。

行动	时间投入	具体做法
开源贡献	每天 60 min	给 `hello-agents`、`Mastra`、`browser-use` 等项目提 PR（文档改进、Bug 修复、小功能）
方法论沉淀	每天 40 min	把学习笔记整理成博客文章或内部技术分享
业务探索	周末 3-4 小时	结合飞猪业务，设计一个 Agent Demo（如智能行程规划、客服辅助）

关键执行原则

先跑起来再完美：第一周就写出能运行的代码，不要花两周只读理论
一课一代码：每学完一个概念（如 ReAct、Memory），当天就必须有代码产出
用 Git 管理：从第一天就建一个 agent-learning 仓库，每周末 commit
输出倒逼输入：每两周写一篇学习笔记（哪怕只是 README），强迫自己消化
卡住先跳过：2 小时很宝贵，卡超过 30 分钟就记 TODO，先往下走

各阶段推荐资源组合

阶段	主力课程	辅助资源	备用
第一阶段	`hello-agents` Part 1-2	Andrej Karpathy Transformer 视频	`microsoft/ai-agents-for-beginners` 前 5 课
第二阶段	`microsoft/ai-agents-for-beginners` 后 7 课 + LangGraph 官方文档	`iusztinpaul/designing-real-world-ai-agents-workshop`	`zkzkGamal/Agentic-AI-Tutorial`
第三阶段	`hello-agents` Part 3-4	LangSmith 官方文档	OpenAI Evals 源码
第四阶段	开源项目源码阅读	Latent Space 播客	X 上追踪 @hwchase17、@gregpr07

按这个节奏，12 个月后你会有一条清晰的成长轨迹：从”能写 Agent”到”能设计 Agent 系统”再到”能带团队做 Agent 落地”。每天 2 小时，关键是不中断。

写在最后

成为 Agentic System Engineer 不是一蹴而就的，需要从工程基础到 AI 认知，再到系统架构，层层递进。这张图的价值在于它提供了一个完整的地图——你不需要一开始就掌握所有内容，但你需要知道每个能力点的位置和重要性。

作为全栈开发者，最大的优势是工程基础扎实、理解系统全貌。最大的挑战是从”确定性编程”转向”概率性系统”的思维转变。Agent 系统的行为不是完全可控的，需要在不确定性中做工程化。

这条路上没有捷径，但有地图。这张图就是我的地图。接下来，就是一步步走。

阿里云 PouchContainer 容器技术详解

2026-05-11T02:00:00.000Z

如果你在阿里云或阿里内部系统中看到过”Pouch”这个词，可能会好奇它和 Docker 是什么关系。本文从历史、架构、核心特性三个维度，系统地介绍阿里巴巴开源的企业级容器运行时 PouchContainer。

背景：从 T4 到 PouchContainer

2011 年，阿里巴巴内部开始研发一套基于 LXC 的容器系统，代号 T4，用于支撑淘宝的海量在线交易。这比 Docker 公开发布（2013 年）还早了两年。

随着 Docker 的兴起和 OCI（Open Container Initiative）规范的确立，阿里将 Docker 的镜像格式和生态整合进 T4，逐步演化为兼容 OCI 规范的 PouchContainer，并于 2017 年 11 月正式对外开源（Apache 2.0）。

GitHub 地址：AliyunContainerService/pouch

Pouch 的设计目标不是”再做一个 Docker”，而是在阿里超大规模数据中心（几十万台机器、数亿容器实例）场景下，解决 Docker 难以满足的企业级痛点。

与 Docker 的核心差异

维度	Docker	PouchContainer
容器模型	单进程原则	支持多进程（Rich Container）
隔离手段	仅 cgroups + namespace	kernel + hypervisor 双轨
/proc 视图	与宿主共享	通过 lxcfs 隔离
镜像分发	Registry 直拉	集成 Dragonfly P2P 分发
CRI 集成	需要 containerd-shim	CRI Manager 内嵌 Daemon
内核要求	较新内核	兼容低至 Linux 2.6.32

四大核心特性

1. Rich Container（富容器模式）

Docker 强调”一个容器只跑一个进程”，这在云原生新应用上没问题。但阿里大量存量业务跑在传统 Linux 环境里，需要 sshd、cron、supervisord 等系统服务同时运行在同一个容器内，这就是 Rich Container 要解决的问题。

Rich Container 允许容器内运行完整的 init 系统（如 systemd），让传统应用无需改造就能容器化，极大降低了存量业务的迁移成本。

1 2	# 以 Rich Container 模式启动容器（带 init 进程） pouch run -d --rich --initscript /tmp/initscript.sh ubuntu:16.04

2. LXCFS 提供更强的 /proc 隔离

Docker 容器在默认情况下，cat /proc/meminfo 显示的是宿主机的内存信息，而不是容器被分配的资源。这在多租户场景下会引发严重误判——Java 应用按宿主机内存大小设置 JVM 堆，实际分配却远低于此，直接 OOM。

PouchContainer 集成了 lxcfs（Linux Container Filesystem），通过 FUSE 在用户态提供虚拟 /proc 文件系统，让容器内的进程看到的 meminfo、cpuinfo、uptime 等都是容器视图，彻底解决 /proc 隔离问题。

# 容器内看到的是分配给它的 2G 内存，而不是宿主机的 256G
cat /proc/meminfo
MemTotal:        2097152 kB
MemFree:         1048576 kB

3. P2P 镜像分发（Dragonfly）

在阿里双 11 场景下，需要在几分钟内向几十万台机器推送同一个容器镜像。如果走传统的 Registry 直拉模式，Registry 带宽会瞬间被打爆。

PouchContainer 内置集成了阿里开源的 Dragonfly（蜻蜓），一个基于 P2P 协议的智能文件分发系统：

首台机器从 Registry 拉取后，后续机器从已有节点 P2P 获取
带宽消耗降低 60% 以上
支持秒级扩容数万容器

Dragonfly 已捐给 CNCF，成为独立项目：d7y.io

4. Hypervisor 级隔离（双轨隔离）

普通容器（runc）本质上还是共享内核，对安全敏感场景（金融、多租户）有隐患。PouchContainer 支持接入 hypervisor 级容器运行时（如 runV / Kata Containers），用轻量级 VM 提供更强隔离，同时保留容器的快速启动特性。

1 2	内核级容器（runc） → 启动快，隔离较弱 VM 级容器（runV） → 启动稍慢，隔离强，内核独立

用户可以按业务场景选择不同的 runtime，同一套 Pouch Daemon 统一管理。

架构概览

┌─────────────────────────────────────┐
│            Kubernetes               │
└──────────────┬──────────────────────┘
               │ CRI (gRPC)
┌──────────────▼──────────────────────┐
│             Pouchd                  │
│  ┌──────────┐  ┌──────────────────┐ │
│  │CRI Manager│  │  Image Manager   │ │
│  └──────────┘  └──────────────────┘ │
│  ┌──────────┐  ┌──────────────────┐ │
│  │Container  │  │   CNI Manager    │ │
│  │ Manager  │  └──────────────────┘ │
│  └────┬─────┘                       │
└───────┼─────────────────────────────┘
        │
   ┌────┴────┐
   │  runc   │  runV / kata
   └─────────┘

与 Docker 需要 dockerd → containerd → containerd-shim → runc 多层链路不同，Pouchd 将 CRI Manager 内嵌，减少了进程层级和 IPC 开销。

Kubernetes 集成

PouchContainer 原生实现了 Kubernetes CRI（Container Runtime Interface），启动时加上 --enable-cri=true 即可作为 kubelet 的容器运行时：

1
2
3

# kubelet 配置
--container-runtime=remote
--container-runtime-endpoint=unix:///var/run/pouchcri.sock

这一点早于 Docker 通过 cri-dockerd 桥接的方案，架构上更简洁。

现状与影响

PouchContainer 目前已是阿里巴巴内部最核心的容器基础设施之一，支撑了：

淘宝、天猫、支付宝的核心交易链路
双 11 期间数十万节点的弹性扩缩容
阿里云 ECI（弹性容器实例）的底层支撑

作为开源项目，Pouch 的 GitHub 活跃度近年有所下降（阿里内部逐步向 containerd/Kata 生态收敛），但它在 2017-2020 年间对推动国内企业级容器化进程有重要贡献，也促成了 CNCF 多个项目（Dragonfly、Sealer）的诞生。

总结

PouchContainer 的价值不在于”又一个容器运行时”，而在于它系统性地解决了超大规模、存量业务迁移、多租户安全隔离三类企业痛点：

Rich Container → 存量业务低成本容器化
LXCFS → /proc 视图正确隔离，Java 应用友好
Dragonfly P2P → 大规模镜像分发不打爆 Registry
双轨隔离 → 按安全需求灵活选择 runc 或 VM

如果你在阿里云上做容器化，了解 Pouch 的设计思路能帮你更好地理解底层基础设施的行为；如果你在设计私有云容器平台，这些特性也值得借鉴。

宝塔面板安装 WordPress 详细教程：从零开始搭建网站

2025-07-26T10:07:05.000Z

环境准备

确保安装了 Nginx、MySQL、PHP 环境。

新建站点

进入宝塔面板，点击左侧的“网站”，然后点击“添加站点”。

点击 “一键部署”，选择 WordPress 模版，输入域名。建议 www 和非 www 都部署。

SSL 证书

网站部署完成后，点击 “SSL”，选择 “Let’s Encrypt”，点击 “提交”。

记得勾选 “强制 HTTPS” 和到期提醒。

伪静态

选择 wordpress 模版，点击 “提交”。

301 重定向

重定向设置，选择 “301 重定向”，点击 “提交”。

wordpress 初始化

数据库名选择新建网站时的：

wordpress 设置

permalink 设置为 /%category%/%postname%/（电商、新闻门户）或者 /%postname%/（博客、企业站）：

wordpress 主题

Meteor：一款专为自媒体人、博主和内容创作者精心打造的WordPress主题

Ant Design Pro 实战记录

2025-05-17T08:04:15.000Z

简介

Ant Design Pro 是基于 Ant Design 和 umi 的封装的一整套企业级中后台前端/设计解决方案，致力于在设计规范和基础组件的基础上，继续向上构建，提炼出典型模板/业务组件/配套设计资源，进一步提升企业级中后台产品设计研发过程中的『用户』和『设计者』的体验。随着『设计者』的不断反馈。

初始化

1 2	npm i @ant-design/pro-cli -g pro create myapp

然后选择脚手架，simple 是基础模板，只提供了框架运行的基本内容，complete 包含所有区块，不太适合当基础模板来进行二次开发

1
2
3

? 🚀 要全量的还是一个简单的脚手架? (Use arrow keys)
❯ simple
  complete

我这里选择是 complete 脚手架，方便全量的最佳实践

安装依赖：

脚手架初始化成功之后就可以开始进行开发了，Ant Design Pro 提供了一些命令来辅助开发。

1	cd myapp && pnpm install

运行

complete 脚手架运行会报错：🐛 [BUG] 路由错误 #11189，需要修改 routes.ts 文件，注释掉 /user 路由下的 404 路由（全局有一个 404 可以兜底）：

{
  path: '/user',
  layout: false,
  routes: [
    // {
    //   component: '404',
    //   path: '/*',
    // },
  ],
}

然后执行 yarn start 即可启动项目。

修改调试 MOCK

app.tsx 文件中的 baseURL 注释掉，或者根据 isDev 判断：

/**
 * @name request 配置，可以配置错误处理
 * 它基于 axios 和 ahooks 的 useRequest 提供了一套统一的网络请求和错误处理方案。
 * @doc https://umijs.org/docs/max/request#配置
 */
export const request: RequestConfig = {
  baseURL: isDev ? '' : 'https://proapi.azurewebsites.net',
  ...errorConfig,
};

🧐[问题 | question] 如何修改调试Mock

import { useModel } from '@umijs/max';
import { flushSync } from 'react-dom';

const Login = () => {
  const { initialState } = useModel('@@initialState');
  const fetchUserInfo = async (token: string) => {
    const userInfo = await initialState?.fetchUserInfo?.();
    localStorage.setItem('token', token);
    if (userInfo) {
      flushSync(() => {
        setInitialState((s) => ({
          ...s,
          currentUser: { ...userInfo, token } as API.CurrentUser,
        }));
      });
    }
  };

  const handleSubmit = async () => {
    const token = await login({ account: 'admin', password: '123456' });
    if (token) {
      message.success('登录成功！');
      await fetchUserInfo();
    }
  };
}

export default Login;

部署

netlify

如果不使用 github pages，需要把模版中 gh-pages 删掉：

删除 public 目录下的 CNAME 文件
删除 gh-pages 依赖和 npm script 脚本

然后在 public 目录下添加 _redirects 文件，内容：

1 2	/* /index.html 200

字节 agent-tars 技术揭秘（硬啃）

2025-04-13T12:14:59.000Z

依赖

@tavily/core：Tavily 的 JavaScript SDK 允许与 Tavily API 轻松交互，直接在 JavaScript 和 TypeScript 程序中使用 Tavily 的全部搜索和提取功能。利用强大的 Tavily Search 和 Tavily Extract API，轻松将智能搜索和内容提取功能集成到应用程序中。
@computer-use/node-mac-permissions：用来管理 macOS 权限的 nodejs 包。
@agent-infra/mcp-server-commands：执行任意命令的 MCP 服务器。
@agent-infra/mcp-server-filesystem：访问文件系统的 MCP 服务器。
@agent-infra/mcp-server-browser：操作浏览器的 MCP 服务器。
jotai：轻量状态管理库

架构

Monorepo

pnpm workspace

Electron

agent-tars 是一个基于 Electron 的桌面应用，Electron 的主进程（Main Process）和渲染进程（Renderer Process）是其双进程架构的核心设计，两者的职责、运行环境和交互方式决定了 Electron 应用的性能与安全性。

主进程（Main Process）

入口与生命周期管理：作为应用的入口（src/main/index.ts），负责启动/关闭应用、管理窗口生命周期（如创建/销毁 BrowserWindow 实例）。
系统级交互：直接访问 Node.js API 和操作系统资源（如文件系统、网络请求、系统通知），执行敏感操作（如加密数据处理）
全局状态控制：管理跨窗口的全局数据（如用户配置、缓存），协调多渲染进程的通信。

渲染进程（Renderer Process）

UI 渲染与交互：每个窗口对应一个独立的渲染进程，基于 Chromium 实现网页渲染，处理 HTML、CSS、JavaScript 的执行及用户交互（如点击事件）。
部分 Node.js能力：默认不启用 Node.js 集成，但可通过 preload 脚本和 contentBridge 暴露有限 API（如 fs 模块的部分功能）。
沙箱环境：出于安全考虑，渲染进程默认隔离，无法直接访问系统资源或执行危险操作。

进程间通信（IPC）机制

主进程与渲染进程通过 IPC（Inter-Process Communication）实现安全通信：

1、异步通信：

渲染进程通过 ipcRenderer.send() 发送消息，主进程通过 ipcMain.on() 监听并响应。
示例：渲染进程请求打开文件 → 主进程调用 fs 模块读取 → 结果返回渲染进程。

2、同步通信：

渲染进程通过 ipcRenderer.sendSync() 发送同步请求，主进程处理后返回结果（可能阻塞 UI 线程，慎用）

3、预加载脚本（Preload Script）

在渲染进程加载前注入，通过 contextBridge.exposeInMainWorld() 安全暴露主进程 API（如 sendMessageToMain）
示例：预加载脚本桥接 ipcRenderer，避免直接暴露 Node.js 功能。

渲染进程（src/renderer）

main.tsx

渲染进程的入口在 src/main.tsx，主要作用：

执行 initMonacoWorkers() 方法初始化 MonacoWorkers，具体分析看 initMonacoWorkers
引入 ./components/App.tsx，具体分析看 App.tsx

App.tsx

main.tsx 一般都是执行一些和 UI 无关的全局初始化操作，App.tsx 则是处理一些 UI 相关的全局初始化操作：

调用 useMainProcessErrorHandler() 注册主进程错误处理程序，这不是我们关注的重点，请查看源码
引入 ./components/AgentApp 进行展示

AgentApp.tsx

：放置主题切换、会话管理和设置，这不是本文关注的重点。
：负责指令输入和 Agent 执行链展示
：负责展示 Agent 执行细节的展示

OpenAgentChatUI

import { ChatUI as BaseChatUI } from '@vendor/chat-ui';
import { MenuHeader } from './MenuHeader';
import { AgentStatusTip } from './AgentStatusTip';
import { BeforeInputContainer } from './BeforeInputContainer';
import { useAgentFlow } from '@renderer/hooks/useAgentFlow';
import { WelcomeScreen } from '../WelcomeScreen';

export function OpenAgentChatUI() {
  const launchAgentFlow = useAgentFlow();

  const sendMessage = useCallback(
    async (inputText: string, inputFiles: InputFile[]) => {
      setIsSending(true);
      // 截止发稿日，暂不支持文件上传
      await launchAgentFlow(inputText, inputFiles);
      setIsSending(false);
    },
    [addUserMessage, launchAgentFlow],
  );

  return (
    <>
      <BaseChatUI
        onMessageSend={sendMessage}
        slots={{
          beforeMessageList: (
            <>
              <MenuHeader />
              {isInitialized && messages.length >= 0 && <WelcomeScreen />}
            
          ),

          beforeInputContainer: <BeforeInputContainer />,
          customFeatures: (
            <>
              <div className="flex gap-2">
                {isSending ? <AgentStatusTip /> : null}
              div>
            
          ),
        }}
      />
    
  )
}

以上是去掉和 ChatUI 交互后的简化的核心代码，@vender/chat-ui 由于内部原因，暂未公开，可以关注 issues#417。核心逻辑如下：

用户输入完成后，触发 sendMessage，将用户输入发送给 launchAgentFlow
launchAgentFlow 触发 Agent 执行，详细代码请查看 useAgentFlow

slots 插槽的配置分别是：

beforeMessageList，MessageList 前面的槽位，这里放了菜单栏和欢迎页
beforeInputContainer，InputContainer 前面的槽位，这里放了，
customFeatures，自定义功能槽位，这里放了，用来展示 Agent 的状态

BeforeInputContainer

import { PlanTaskStatus } from './PlanTaskStatus';
import { UserInterruptArea } from './UserInterruptArea';

export function BeforeInputContainer() {
  return (
    <>
      <PlanTaskStatus />
      <UserInterruptArea isDark={isDarkMode.value} />
    
  );
}

，计划任务状态，展示计划执行列表的进度
，用户中断区域，消息发送或执行中，允许用户发送新的消息或中断

CanvasPanel

hooks

useAgentFlow

import { useCallback } from "react";
import { AgentFlow } from '../agent/AgentFlow';
import { v4 as uuid } from 'uuid';

export function useAgentFlow() {
  return useCallback(
    async(inputText: string; inputFiles: InputFile[]) => {
      const agentFlowId = uuid();
      const agentFlow = new AgentFlow({
        agentFlowId,
        request: {
          inputText,
          // 截止发稿日，暂不支持文件上传
          inputFiles
        }
      });
      await agentFlow.run();
    },
    []
  )
}

useAgentFow hook 接收用户输入后，创建一个 AgentFlow 实例，并调用 agentFlow.run() 触发 Agent 执行

agent

AgentFlow.ts

import { ToolCallType } from '@renderer/type/agent';
import { Aware, AwareResult } from './Aware';
import { EventManager } from './EventManager';
import { Executor } from './Executor';
import { Greeter } from './Greeter';
import { ipcClient } from '@renderer/api';
import { SNAPSHOT_BROWSER_ACTIONS } from '@renderer/constants';

export class AgentFlow {
  private abortController: AbortController;

  constructor(private appContext: AppContext) {
    this.eventManager = new EventManager(omegaHistoryEvents);
  }

  async run() {
    const greeter = new Greeter(this.appContext, this.abortController.signal);
    const aware = new Aware(
      this.appContext,
      agentContext,
      this.interruptController.signal,
    );
    // 构建执行器
    const executor = new Executor(
      this.appContext,
      agentContext,
      this.interruptController.signal,
    );

    // 展示 ai 打招呼消息
    const preparePromise = greeter.run().then(async () => {});

    await Promise.all([
      preparePromise,
      // 启动 Agent 循环
      this.launchAgentLoop(executor, aware, agentContext, preparePromise),
    ]);
  }

  private async launchAgentLoop(
    executor: Executor,
    aware: Aware,
    agentContext: AgentContext,
    preparePromise: Promise<void>
  ) {
    //  Agent 循环
    while(!this.abortController.signal.aborted && !this.hasFinished) {
      // 当任务没有被取消或完成时执行 Agent 循环
      const awareResult = await aware.run();
      if (this.abortController.signal.aborted) {
        // 如果任务被取消，则跳出 Agent 循环
        break;
      }

      if (
        awareResult.plan &&
        awareResult.plan.every(
          (task) => task.status === PlanTaskStatus.Done,
        )
      ) {
        // 如果所有任务都完成，则跳出 Agent 循环
        this.hasFinished = true;
        break;
      }

      const toolCallList = (await executor.run(awareResult.status)).filter(
        Boolean,
      );
      const mcpTools = await ipcClient.listMcpTools();
      const customServerTools = await ipcClient.listCustomTools();

      // 执行 工具
      for (const toolCall of toolCallList) {
        const toolName = toolCall.function.name;
        const isMCPToolCall = mcpTools.some(
          (tool) => tool.name === toolCall.function.name,
        );

        // 如果是执行 MCP 工具
        if (isMCPToolCall) {
          if (
            // 如果是编辑和写入文件
            toolName === ToolCallType.EditFile ||
            toolName === ToolCallType.WriteFile
          ) {
            const params = JSON.parse(
               toolCall.function.arguments,
             ) as ToolCallParam['edit_file'];
             originalFileContent = await ipcClient.getFileContent({
               filePath: params.path,
             });
          }
          const callResult = (await executor.executeTools([toolCall]))[0];
          await this.eventManager.handleToolExecution({
            toolName,
            toolCallId: toolCall.id,
            params: toolCall.function.arguments,
            result: callResult.content,
            isError: callResult.isError as boolean,
          });
        }

        // 如果是执行浏览器快照动作
        if (SNAPSHOT_BROWSER_ACTIONS.includes(toolName)) {
          //
          const screenshotPath = await ipcClient.saveBrowserSnapshot();
          console.log('screenshotPath', screenshotPath);
        }
      }
    }
  }
}

Aware

export class Aware {
  private systemPrompt = `You are an AI agent with the ability to analyze the current environment, decide the next task status, tell user the next specific action.


You must call the aware_analysis tool.

You should give the insights of current environment according to the various context information, and then decide the next task status.

If the task is none or current step is done, you should increment the step number and update system status. Please return the json output in the tool call part:

\`\`\`json
{
  "reflection": "[your reflection about current environment]",
  "step": "[next step number]",
  "plan": "[steps array with id and title fields]",
  "status": "[next task description, a complete sentence tell user what to do next]",
}
\`\`\`

You should output the reflection first.

You should not output any response text and only return the tool call.

Only when there is no existing plan in the current environment, you should return plan field with the following format:
- id: string (format: "step_XXX" where XXX is a sequential number starting from 001)
- title: string (clear, concise description of the step)





For any given task or problem:
1. Analyze the requirements thoroughly
2. Create a systematic, step-by-step solution
3. Ensure each step is concrete and actionable
4. Maintain logical progression between steps



You must follow these limitations:

- If there is plan exist, you should not return the plan field.
- Don't ask user anything, just tell user what to do next. If some points is not very clear, you should tell user your solution. Remember, you are a agent for human.
- Don't output any response text and only return the tool call.
- You should not repeat the same behavior or mean with previous steps.
- Don't output any file path in current machine and ensure the security in your message. Don't output any absolute path in your message.





Only except user interrupt or start a new session, you CANNOT update the plan!

If you reset the plan to a new one, you should also reset the step to number 1.






In the \`status\` field, you should only return a sentence to tell user what you will do next, and don't need to return the reason and other information.Please the the first person perspective to answer, indicating that you are work for the user.






If in the last step, but we still have issues to solve, you cannot increment the step number and should continue to solve the issue.





For user interrupt input in the middle of the event stream, you should handle it in the first important level and handle it as soon as possible.If current plan tasks cannot match the new user input, you should reset the plan.





The event stream result record the complete response of the agent, you should make next decision base on the history, if current step has not been done, please don't increment the step number. If you meet the \`ended\` message, that means you entered a new session and you should reset the plan from scratch.

In the event stream, the \`observation\` type message is the observation of the tool use, you should attention to the field and judge the task status according to it.When the observer represent the error message, you should reflect the error and solve it in the next step.





After \`web_search\` called, then you must select web page from the search result, then you must see the detail of the page, call navigate to get detail. See the detail right away after get search result!





When you want to write file, you should list allowed directories and write the file to the allowed directory.






You should use the same language as the user input by default.

`;
  async run() {
    // 获取环境信息
    const environmentInfo = await this.agentContext.getEnvironmentInfo(
      this.appContext,
      this.agentContext,
    );
    // 默认结果
    const defaultResult = {
      reflection: 'No plan',
      step: this.agentContext.currentStep,
      status: 'No plan',
      plan: [],
    };

    return new Promise(resolve, reject) => {
      try {
        // 获取执行器工具列表
        const executorTools = await ipcClient.listTools();
        // 调用 LLM
        const result = await ipcClient.askLLMTool({
          messages: [
            Message.systemMessage(this.systemPrompt),
            Message.systemMessage(
              `You are working with executor agent, here is the executor tools: ${executorTools
                .map((tool) => `${tool.name}: ${tool.description}`)
                .join(', ')}`,
            ),
            Message.userMessage(environmentInfo),
            Message.userMessage(
              `Please call aware_analysis tool to give me next decision.`,
            ),
          ],
          tools: [
            {
              type: 'function',
              function: {
                name: 'aware_analysis',
                description:
                  'Analyze the current environment with user input, and decide the next task status',
                parameters: this.awareSchema,
              },
            },
          ],
          requestId: streamId,
        });
        const awareResult = JSON.parse(
          result.tool_calls.filter(Boolean)[0].function.arguments,
        ) as AwareResult;
        resolve(awareResult);
      } catch (error) {
        reject(error);
      }
    }
  }
}

src/main/ipcRoutes/llm.ts

export const llmRoute = t.route({
  askLLMTool: t.procedure.input().handle(async ({ input }) => {
    try {
      const messages = input.messages.map((msg) => new Message(msg));
      const response = await llm.askTool({
        messages,
        tools: input.tools,
        mcpServerKeys: input.mcpServerKeys,
        requestId: input.requestId,
      });
      return response;
    } catch (error) {}
  })
})

src/main/llmProvider/index.ts

export class LLM {
  async askTool({
    messages,
    tools,
    requestId,
    toolChoice,
  }) {
    const allTools = [...tools];
    return await this.provider.askTool({
      messages,
      tools: allTools,
      requestId,
      toolChoice: toolChoice || 'auto',
    });
  }
}

src/main/llmProvider/providers/OpenAIProvider.ts：

export class OpenAIProvider extends BaseProvider {
  /**
   * Convert Message objects to OpenAI API format
   */
  protected formatMessages(
    messages: Message[],
  ): OpenAI.Chat.ChatCompletionMessageParam[] {
    return messages.map((item) => ({
      role: item.role as any,
      content: item.content,
      ...(item.tool_call_id && { tool_call_id: item.tool_call_id }),
      ...(item.tool_calls && {
        tool_calls:
          item.tool_calls as OpenAI.Chat.ChatCompletionMessageToolCall[],
      }),
      ...(item.name && { name: item.name }),
    }));
  }
  /**
   * Send a message to the LLM with tools and get a response with potential tool calls
   */
  async askTool({
    messages,
    tools,
    requestId,
    toolChoice = 'auto',
  }: {
    messages: Message[];
    tools: ChatCompletionTool[];
    requestId: string;
    toolChoice?: ToolChoice;
  }): Promise<LLMResponse> {
    try {
      const formattedMessages = this.formatMessages(messages);
      this.activeRequests.set(requestId, controller);

      const response = await this.client.chat.completions.create(
        {
          model: this.model,
          messages: formattedMessages,
          temperature: this.config.temperature,
          max_tokens: this.config.maxTokens,
          tools,
          tool_choice: toolChoice,
          top_p: this.config.topP,
          frequency_penalty: this.config.frequencyPenalty,
          presence_penalty: this.config.presencePenalty,
        },
        {
          signal: controller.signal,
        },
      );
      const content = response.choices[0].message.content;
      const toolCalls = this.processToolCalls(response);
      return { content, tool_calls: toolCalls };
    } catch (error: unknown) {}
  }
}

Executor

export class Executor {
  private systemPrompt = `You are a tool use expert. You should call the appropriate tools according to the aware status and environment information.You should not output any response text and only return the JSON.


- Must respond with a tool use (function calling); plain text responses are forbidden
- Do not mention any specific tool names to users in messages
- Carefully verify available tools; do not fabricate non-existent tools
- Follow the instructions carefully in the aware status.
- Don't repeat the same mean with aware status, you should select the appropriate tool.
- Don't ask user anything, just tell user what you will do next.If some points is not very clear, you should tell user your solution.Don't ask user anything, remember, you are a agent for user.
- You should only respond chat message after you have finished some tools and return the summary in chat message.
- You should not output any response text and only return the tool call.
- Don't output any file path in current machine and ensure the security in your message. Don't output any absolute path in your message.



message as summary in current step.Don't return message first when the step just started.

Notice, you should not output a lot of words in chat message, because the chat message is always summary words. If you want to write something in detail, please use \`write_file\` to write in by markdown file by default.

In chat message tool, you should add the files that has been created in the past steps, and put the complete file path in the \`attachments\` param.



If you meet the file system permission denied, you should check if the dir or file exists and create it if not.

Before you interact with filesystem, you must list the allowed dirs and files and check if the dir or file exists and create it if not.Don't write file directly. You should write the file into a safe directory.




After \`web_search\` called, then you must select web page from the search result, then you see the detail of the page, please call browser tool to do it.



use \`browser_navigate\` to enter the page detail.
use \`browser_scroll\` to scroll the page.When you use browser to enter the page detail, if the page content is partially visible, you should call browser tool to scroll to get more content, until the page content is fully visible.
use \`browser_click\` to click the element.
use \`browser_form_input_fill\` to fill the form.
use \`browser_select\` to select the element.
use \`browser_hover\` to hover the element.
use \`browser_evaluate\` to evaluate the element.
use \`browser_get_text\` to get the text of the element.



When you use commands, you must cd the allowed dir instead of cwd.



You should use the same language as the user input by default.
`;
}

构建出的 executor 结构，我们主要关注

EventManager

EventManager 类主要是负责和 chat-ui 交互的，由于 chat-ui 没有开源，这块是黑盒的。后续开源之后详细讲解。

export class EventManager {
  /**
   * Get all events
   */
  public getAllEvents() {
    return [...this.events];
  }

  /**
   * Notify subscribers about event updates
   */
  private notifyUpdate() {
    if (this.onEventsUpdate) {
      this.onEventsUpdate(this.getAllEvents());
    }
  }

  /**
   * Add a generic event
   */
  private async addEvent(
    type,
    content,
    willNotifyUpdate = true,
  ) {
    const event = {
      id: nanoid(),
      type,
      content,
      timestamp: Date.now(),
    };

    this.events.push(event);
    willNotifyUpdate && (await this.notifyUpdate());
    return event;
  }

  /**
   * Add an observation event
   */
  public async addObservation(content) {
    return this.addEvent(EventType.Observation, content);
  }


  /**
   * Handle tool execution result and add related events
   */
  public async handleToolExecution({
    toolName,
    toolCallId,
    params,
    result,
    isError,
  }) {
    const normalizedInfo = normalizeToolUsedInfo(
      toolName,
      params,
      isError ? ActionStatus.Failed : ActionStatus.Success,
      result,
    );

    await this.addEvent(EventType.ToolUsed, {
      actionId: toolCallId,
      ...normalizedInfo,
    });

    await this.addObservation(JSON.stringify(result));
  }
}

src/renderer/src/type/event.ts：

export enum EventType {
  UserMessage = 'user-message',
  LoadingStatus = 'loading-status',
  ToolUsed = 'tool-used',
  ToolCallStart = 'tool-call-start',
  PlanUpdate = 'plan-update',
  AgentStatus = 'agent-status',
  ChatText = 'chat-text',
  Observation = 'observation',
  NewPlanStep = 'new-plan-step',
  UserInterruption = 'user-interruption',
  End = 'end',
}

api

ipcClient

import { createClient } from '@ui-tars/electron-ipc/renderer';

export const ipcClient = createClient({
  ipcInvoke: window.electron.ipcRenderer.invoke,
});

createClient 代码如下：

import { IpcRenderer } from 'electron';

export const createClient = ({ ipcInvoke }) => {
  return new Proxy({}, {
    get: (_, prop) => {
      const invoke = (input) => {
        return ipcInvoke(prop.toString(), input);
      };

      return invoke;
    },
  });
};

utils

initMonacoWorkers

initMonacoWorkers 方法位于 src/utils/monacoConfig：

import * as monaco from 'monaco-editor';
import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';
import jsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker';
import cssWorker from 'monaco-editor/esm/vs/language/css/css.worker?worker';
import htmlWorker from 'monaco-editor/esm/vs/language/html/html.worker?worker';
import tsWorker from 'monaco-editor/esm/vs/language/typescript/ts.worker?worker';

export function initMonacoWorkers(): void {
  self.MonacoEnvironment = {
    getWorker(_, label) {
      if (label === 'json') {
        return new jsonWorker();
      }
      if (label === 'css' || label === 'scss' || label === 'less') {
        return new cssWorker();
      }
      if (label === 'html' || label === 'handlebars' || label === 'razor') {
        return new htmlWorker();
      }
      if (label === 'typescript' || label === 'javascript') {
        return new tsWorker();
      }
      return new editorWorker();
    },
  };
}

export const defaultEditorOptions: monaco.editor.IStandaloneEditorConstructionOptions =
  {
    readOnly: true,
    minimap: { enabled: false },
    scrollBeyondLastLine: false,
    fontSize: 14,
    renderLineHighlight: 'all',
    scrollbar: {
      vertical: 'visible',
      horizontal: 'visible',
    },
    automaticLayout: true,
  };

主进程（src/main）

ipcRoutes

import { initIpc, createServer } from '@ui-tars/electron-ipc/main';

export const ipcRoutes = t.router({
  ...agentRoute,
  ...llmRoute,
  // 这里定义了 actionRoute
  ...actionRoute,
  ...browserRoute,
  ...fileSystemRoute,
  ...searchRoute,
  ...settingsRoute,
  ...mcpRoute,
});
export const server = createServer(ipcRoutes);

actionRoute

import { MCPServerName } from '@agent-infra/shared';
import { initIpc } from '@ui-tars/electron-ipc/main';

const t = initIpc.create();

export const actionRoute = t.router({
  listTools: t.procedure.handle(async () => {}),

  listMcpTools: t.procedure.handle(async () => {}),

  listCustomTools: t.procedure.handle(async () => {}),

  executeTool: t.procedure.input().handle(async () => {}),

  saveBrowserSnapshot: t.procedure.input().handle(async () => {
    // 通过 mcpClient 调用浏览器截图工具
    const result = await mcpClient,callTool({
      client: MCPServerName.Browser,
      name: 'browser_screenshot',
      args: {
        highlight: true
      }
    })
    const screenshotMeta = (
      result.content as [
        { type: 'text'; text: string },
        { type: 'image'; data: string; mimeType: string },
      ]
    )[1];

    const omegaDir = await getOmegaDir();
    const screenshotPath = path.join(omegaDir, 'screenshots');
    await fs.mkdirSync(screenshotPath, { recursive: true });
    const ext = screenshotMeta.mimeType.split('/')[1] || 'png';
    const timestamp = new Date().getTime();
    const filename = `screenshot_${timestamp}.${ext}`;
    const filepath = path.join(screenshotPath, filename);
    const imageBuffer = Buffer.from(screenshotMeta.data, 'base64');
    await fs.writeFile(filepath, imageBuffer);
    return { filepath };
  }),

  saveReportHtml: t.procedure.input().handle(async ({ input }) => {}),

  cleanup: t.procedure.handle(async () => {})
})

mcp client

import { MCPServerName } from '@agent-infra/shared';

// 获取OmegaDir
export const getOmegaDir = async () => {
  // Create working directory in user's home directory.
  const omegaDir = path.join(os.homedir(), '.omega');
  if (!fs.existsSync(omegaDir)) {
    await fs.mkdir(omegaDir, { recursive: true });
  }
  return omegaDir;
};

//  TODO: 这里我很奇为什么不直接用 import，有空和三元大佬请教下
const dynamicImport = (url) => new Function(`return import('${url}')`)();

// 实现一个基于 commands、filesystem 和 browser 的 MCP 客户端
export const createMcpClient = async () => {
  // 动态导入 mcp server 模块
  const commandModule = await dynamicImport('@agent-infra/mcp-server-commands');
  const fsModule = await dynamicImport('@agent-infra/mcp-server-filesystem');
  const browserModule = await dynamicImport('@agent-infra/mcp-server-browser');

  const { client: commandClient } = commandModule.default;
  const { client: fsClient, setAllowedDirectories } = fsModule.default;
  const { client: browserClient } = browserModule.default;

  // 共享的 fClientModule 模块
  fsClientModule = fsModule.default;

  // 设置允许的目录
  const omegaDir = await getOmegaDir();
  setAllowedDirectories([omegaDir]);

  // 工具 map
  const toolsMap = {
    [MCPServerName.FileSystem]: {
      name: MCPServerName.FileSystem,
      description: 'filesystem tool',
      localClient: fsClient,
    },
    [MCPServerName.Commands]: {
      name: MCPServerName.Commands,
      description: 'commands tool',
      localClient: commandClient,
    },
    [MCPServerName.Browser]: {
      name: MCPServerName.Browser,
      local: true,
      description: 'browser tools',
      localClient: browserClient,
    }
  };

  logger.info('toolsMap', toolsMap);

  const client = new MCPClient(Object.values(toolsMap));
  mapClientRef.current = client;
  return client;
};

`@agent-infra/shared`

TODO

`@agent-infra/mcp-client`

基于 @modelcontextprotocol/sdk/client/index.js 和 @modelcontextprotocol/sdk/client/sse.js 实现的 MCP 客户端。负责管理 MCP 服务器和工具调用。

`@agent-infra/mcp-server-browser`

模块位于 packages/agent-infra/mcp-servers/browser

server.ts

import {
  getBuildDomTreeScript,
  parseNode,
  type RawDomTreeNode,
  DOMElementNode,
  createSelectorMap,
  removeHighlights,
  waitForPageAndFramesLoad,
  locateElement,
  scrollIntoViewIfNeeded,
} from '@agent-infra/browser-use';

let globalBrowser: LocalBrowser['browser'] | undefined;
let globalPage: Page | undefined;
let selectorMap: Map<number, DOMElementNode> | undefined;

const screenshots = new Map<string, string>();
export const getScreenshots = () => screenshots;

async function buildDomTree(page: Page) {
  try {
    const rawDomTree = await page.evaluate(() => {
      // Access buildDomTree from the window context of the target page
      return window.buildDomTree({
        doHighlightElements: true,
        focusHighlightIndex: -1,
        viewportExpansion: 0,
      });
    });
    if (rawDomTree !== null) {
      const elementTree = parseNode(rawDomTree as RawDomTreeNode);
      if (elementTree !== null && elementTree instanceof DOMElementNode) {
        const clickableElements = elementTree.clickableElementsToString();
        selectorMap = createSelectorMap(elementTree);

        return {
          clickableElements,
          elementTree,
          selectorMap,
        };
      }
    }
    return null;
  } catch (error) {
    logger.error('Error building DOM tree:', error);
    return null;
  }
}

const handleToolCall: Client['callTool'] = async ({
  name,
  arguments: toolArgs,
}) => {
  const initialBrowser = await setInitialBrowser();
  const { browser } = initialBrowser;
  let { page } = initialBrowser;

  if (!page) {
    return {
      content: [{ type: 'text', text: 'Page not found' }],
      isError: true,
    };
  }

  const handlers = {
    //  浏览器后退
    browser_go_back: async () => {
      await Promise.all([waitForPageAndFramesLoad(page), page.goBack()]);
    },
    //  浏览器前进
    browser_go_forward: async () => {
      await Promise.all([waitForPageAndFramesLoad(page), page.goForward()]);
    },
    browser_navigate: async () => {
      await Promise.all([
          waitForPageAndFramesLoad(page),
          page.goto(args.url),
        ]);
      // 获取可点击元素
      const { clickableElements } = (await buildDomTree(page)) || {};
      return {
          content: [
            {
              type: 'text',
              text: `Navigated to ${args.url}\nclickable elements: ${clickableElements}`,
            },
          ],
          isError: false,
        };
    },
    browser_screenshot: async (args) => {
      if (args.highlight) {
        await buildDomTree(page);
      } else {
        await removeHighlights(page);
      }
      const width = args.width ?? page.viewport()?.width ?? 800;
      const height = args.height ?? page.viewport()?.height ?? 600;
      await page.setViewport({ width, height });
      const screenshot = await (args.selector
        ? (await page.$(args.selector))?.screenshot({ encoding: 'base64' })
        : page.screenshot({ encoding: 'base64', fullPage: false }));
      screenshots.set(args.name, screenshot as string);
    },
    browser_get_clickable_elements: async () => {
      const { clickableElements } = (await buildDomTree(page)) || {};
      return {
        content: [
          {
            type: 'text',
            text: clickableElements,
          },
        ],
        isError: false,
      };
    },
    browser_click: async() => {
      const elementNode = selectorMap?.get(Number(args?.index));
      const element = await locateElement(page, elementNode!);
      await scrollIntoViewIfNeeded(element);

      await Promise.race([
        element.click(),
        new Promise((_, reject) =>
          setTimeout(() => reject(new Error('Click timeout')), 5000),
        ),
      ]);
      return {
        content: [
          {
            type: 'text',
            text: `Clicked element: ${args.index}`,
          },
        ],
        isError: false,
      };
    }
  }

  if (handlers[name]) {
    return handlers[name](toolArgs);
  }
}

export const client: Pick<Client, 'callTool' | 'listTools' | 'close' | 'ping'> =
  {
    callTool: handleToolCall,
  };

参考

基于 MCP 的 AI Agent 应用开发实践

QDII 是什么？懒人无脑定投的产品有哪些？

2025-03-27T20:39:55.000Z

QDII 基金是什么？

QDII（Qualified Domestic Institutional Investor，合格境内机构投资者）是中国在资本项目未完全开放的背景下推出的跨境投资机制，允许境内投资者通过持牌机构间接参与境外证券市场（如美股、港股等）。其核心特点包括：

投资范围广：可配置股票、债券、大宗商品等全球资产；
汇率风险：需人民币兑换外币投资，收益受汇率波动影响；
制度优势：突破个人换汇限额（5万美元/年），提供合规境外投资渠道。

小白无脑定投产品推荐

对于新手投资者，以下三类 QDII 基金及策略兼顾低风险与易操作性，适合长期定投：

宽基指数型 QDII（50%）

标普 500 指数基金（如易方达标普 500 指数基金）
追踪美股大盘，覆盖苹果、微软等龙头企业，管理费0.8%，2024年收益率达21.5%
纳斯达克100 ETF（如华夏纳斯达克100 ETF）
聚焦科技巨头（如英伟达、亚马逊），受益于AI和数字经济浪潮，2024年溢价率需关注

中概股主题 QDII（30%）

中概互联网ETF（如易方达中概互联50）
一篮子持有阿里、腾讯等海外上市中国科技公司，估值处于历史低位，适合逢低布局

低波动稳健型QDII（20%）

全球债券型QDII（如摩根全球新兴市场债券）
配置海外高评级债券，年化收益约4%-5%，波动率低于股票型基金。
红利低波ETF（如招商中证红利ETF）
高股息策略，在降息周期中提供稳定现金流，适合风险厌恶型投资者。

定投实操建议

账户选择：通过支付宝、天天基金等平台直接购买，支持10元起投；
频率与金额：建议月定投，分配比例示例：50%宽基指数（如标普500）+30%中概股+20%债券基金；
风险对冲：
- 人民币升值周期加大换汇比例，降低汇率损失；
- 避免高溢价基金（部分原油、科技类QDII溢价超10%）。

注意事项

申赎规则：多数 QDII 为 T+2 确认份额，赎回到账需 3-5 个工作日；
费用控制：选择管理费低于 0.5% 的产品，避免侵蚀长期收益；
长期视角：定投周期建议 3 年以上，穿越市场周期获取复利效应。

ETF 是什么？

ETF（Exchange-Traded Fund），全称“交易型开放式指数基金”，是一种在证券交易所上市交易的开放式基金，结合了股票和基金的优点，通过跟踪特定指数、商品或资产组合的表现，为投资者提供高效、低成本的市场参与工具。

在 Mac 上搭建 Java 开发环境

2025-03-06T23:38:26.000Z

Java

下载安装

1	brew install --cask zulu@17

实用命令

查看 jdk 版本及其安装目录

$ /usr/libexec/java_home -V
Matching Java Virtual Machines (1):
    17.0.14 (arm64) "Azul Systems, Inc." - "Zulu 17.56.15" /Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home

查看 jre 版本

$ java -version
openjdk 17.0.14 2025-01-21 LTS
OpenJDK Runtime Environment Zulu17.56+15-CA (build 17.0.14+7-LTS)
OpenJDK 64-Bit Server VM Zulu17.56+15-CA (build 17.0.14+7-LTS, mixed mode, sharing)

查看 jdk 版本

1 2	$ javac --version javac 17.0.14

Maven

安装

1	$ brew install maven

配置阿里镜像

setting.xml 路径为 ${Maven Home}/conf/settings.xml ，Maven Home 可以通过 mvn --version

可将 settings.xml 直接拷贝到 .m2 文件夹下，进行配置。

如果没有 .m2 文件夹时,运行命令

1	$ mvn help:system

然后打开当前用户的目录，可以在其中找到 .m2 文件夹，在 settings.xml 的标签内添加：

<mirror>
  <id>alimavenid>
  <name>aliyun mavenname>
  <url>http://maven.aliyun.com/nexus/content/groups/public/url>
  <mirrorOf>centralmirrorOf>
mirror>

升级 Maven

1 2	$ brew update $ brew install maven

在 Mac 上安装 V8

2025-03-06T22:54:41.000Z

不要使用 brew install v8，因为可用命令是不完整的。

预备条件

安装 Xcode (Avaliable on the Mac App Store)
安装 Xcode Command Line Tools (Preferences > Downloads)
安装 depot_tools
- cd ~ && git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
- nano ~/.zshrc
- 添加 export PATH=~/depot_tools:"$PATH"
- source ~/.zshrc
从你想要安装 V8 的目录中，运行 gclient。

Build V8

fetch v8
cd ~/v8
gclient sync

Intel Macs:

tools/dev/v8gen.py x64.optdebug
ninja -C out.gn/x64.optdebug

ARM(M1) Macs:

tools/dev/v8gen.py arm64.optdebug
ninja -C out/arm64.optdebug

我建议你将这些添加到你的 .zshrc 文件中。

sudo nano ~/.zshrc
添加 alias d8=~/v8/out/arm64.optdebug/d8
添加 alias tick-processor=~/v8/tools/mac-tick-processor
添加 export D8_PATH="~/v8/out/arm64.optdebug"
source ~/.zshrc

d8 shell examples

Note: many of these examples have become outdated as v8 continues to evolve. Hoping to update them in the near future, but for now please be aware that some may not work as expected or may reference optimizations/deoptimizations that no longer happen.

Print optimization stats

Create test.js with the following code:

function test( obj ) {
  return obj.prop + obj.prop;
}

var a = { prop: 'a' }, i = 0;

while ( i++ < 10000 ) {
  test( a );
}

Run $ d8 --trace-opt-verbose test.js

You should see that the test function was optimized by V8, along with an explanation of why. “ICs” stands for inline caches – and are one of the ways that V8 performs optimizations. Generally speaking, the more “ICs with typeinfo” the better.

Now modify test.js to include the following code:

function test( obj ) {
  return obj.prop + obj.prop;
}

var a = { prop: 'a' }, b = { prop: [] }, i = 0;

while ( i++ < 10000 ) {
  test( Math.random() > 0.5 ? a : b );
}

Run $ d8 --trace-opt-verbose test.js

So, you’ll see that this time, the test function was never actually optimized. And the reason for that is because it’s being passed objects with different hidden classes. Try changing the value of prop in a to an integer and run it again. You should see that the function was able to be optimized.

Print deoptimization stats

Modify the contents of test.js:

function test( obj ) {
  return obj.prop + obj.prop;
}

var a = { prop: 'a' }, b = { prop: [] }, i = 0;

while ( i++ < 10000 ) {
  test( i !== 8000 ? a : b );
}

Run $ d8 --trace-opt --trace-deopt test.js

You should see that the optimized code for the test function was thrown out. What happened here was that V8 kept seeing test being passed an object that looked like {prop: }. But on the 8000th round of the while loop, we gave it something different. So V8 had to throw away the optimized code, because its initial assumptions were wrong.

Profiling

Modify test.js:

function factorial( n ) {
  return n === 1 ? n : n * factorial( --n );
}

var i = 0;

while ( i++ < 1e7 ) {
  factorial( 10 );
}

Run $ time d8 --prof test.js (Generates v8.log)

Run $ tick-processor (Reads v8.log and cats the parsed output)

This’ll show you where the program was spending most of its time, by function. Most of it should be under LazyCompile: *factorial test.js:1:19. The asterisk before the function name means that it was optimized.

Make a note of the execution time that was logged to the terminal. Now try modifying the code to this dumb, contrived example:

function factorial( n ) {
  return equal( n, 1 ) ? n : multiply( n, factorial( --n ) );
}

function multiply( x, y ) {
  return x * y;
}

function equal( a, b ) {
  return a === b;
}

var i = 0;

while ( i++ < 1e7 ) {
  factorial( 10 );
}

Run $ time d8 --prof test.js

Run $ tick-processor

Roughly the same execution time as the last function, which seems like it should have been faster. You’ll also notice that the multiply and equal functions are nowhere on the list. Weird, right?

Run $ d8 --trace-inlining test.js

Okay. So, we can see that the optimizing compiler was smart here and completely eliminated the overhead of calling both of those functions by inlining them into the optimized code for factorial.

The optimized code for both versions ends up being basically identical (which you can check, if you know how to read assembly, by running d8 --print-opt-code test.js).

Tracing Garbage Collection

Modify test.js

function strToArray( str ) {
  var i = 0,
    len = str.length,
    arr = new Uint16Array( str.length );
  for ( ; i < len; ++i ) {
    arr[ i ] = str.charCodeAt( i );
  }
  return arr;
}

var i = 0, str = 'V8 is the collest';

while ( i++ < 1e5 ) {
  strToArray( str );
}

Run $ d8 --trace-gc test.js

You’ll see a bunch of Scavenge... [allocation failure].

Basically, V8’s GC heap has different “spaces”. Most objects are allocated in the “new space”. It’s super cheap to allocate here, but it’s also pretty small (usually somewhere between 1 and 8 MB). Once that space gets filled up, the GC does a “scavenge”.

Scavenging is the fast part of V8 garbage collection. Usually somewhere between 1 and 5ms from what I’ve seen – so it might not necessarily cause a noticeable GC pause.

Scavenges can only be kicked off by allocations. If the “new space” never gets filled up, the GC never needs to reclaim space by scavenging.

Modify test.js:

function strToArray( str, bufferView ) {
  var i = 0,
    len = str.length;
  for ( ; i < len; ++i ) {
    bufferView[ i ] = str.charCodeAt( i );
  }
  return bufferView;
}

var i = 0,
  str = 'V8 is the coolest',
  buffer = new ArrayBuffer( str.length * 2 ),
  bufferView = new Uint16Array( buffer );

while ( i++ < 1e5 ) {
  strToArray( str, bufferView );
}

Here, we use a preallocated ArrayBuffer and an associated ArrayBufferView (in this case a Uint16Array) in order to avoid reallocating a new object every time we run strToArray(). The result is that we’re hardly allocating anything.

Run $ d8 --trace-gc test.js

Nothing. We never filled up the “new space”, so we never had to scavenge.

One more thing to try in test.js:

function strToArray( str ) {
  var i = 0,
    len = str.length,
    arr = new Uint16Array( str.length );
  for ( ; i < len; ++i ) {
    arr[ i ] = str.charCodeAt( i );
  }
  return arr;
}

var i = 0, str = 'V8 is the coolest', arr = [];

while ( i++ < 1e6 ) {
  strToArray( str );
  if ( i % 100000 === 0 ) {
    // save a long-term reference to a random, huge object
    arr.push( new Uint16Array( 100000000 ) );
    // release references about 5% of the time
    Math.random() > 0.95 && ( arr.length = 0 );
  }
}

Run $ d8 --trace-gc test.js

Lots of scavenges, which is expected since we’re no longer using a preallocated buffer. But there should also be a bunch of Mark-sweep lines.

Mark-sweep is the “full” GC. It gets run when the “old space” heap reaches a certain size, and it tends to take a lot longer than a scavenge. If you look at the logs, you’ll probably see Scavenge at around ~1.5ms and Mark-sweep closer to 25 or 30ms.

Since the frame budget in a web app is about 16ms, you’re pretty much guaranteed to drop at least 1 frame every time Mark-sweep runs.

Random stuff

`$ d8 --help` logs all available d8 flags

There’s a ton there, but you can usually find what you’re looking for with something like d8 --help | grep memory or whatever.

`$ d8 --allow-natives-syntax file.js`

This actually lets you call V8 internal methods from within your JS file, like this:

function factorial( n ) {
  return n === 1 ? n : factorial( --n );
}

var i = 0;

while ( i++ < 1e8 ) {
  factorial( 10 );
  // run a full Mark-sweep pass every 10MM iterations
  i % 1e7 === 0 && %CollectGarbage( null );
}

…and run $ d8 --allow-natives-syntax --trace-gc test.js

Native functions are prefixed with the % symbol. A (somewhat incomplete) list of native functions are listed here.

Logging

d8 doesn’t have a console object (or a window object, for that matter). But you can log to the terminal using print().

Comparing Hidden Classes

This is probably my favorite one. I actually just found it.

So in V8, there’s this concept of “hidden classes” (Good explanation a couple paragraphs in). You should read that article – but basically, hidden classes are how V8 (SpiderMonkey and JavaScript Core use similar techniques, too) determine whether or not two objects have the same “shape”.

All things considered, you always want to pass objects of the same hidden class as arguments to functions.

Anyway, you can actually compare the hidden classes of two objects:

function Class( val ) {
  this.prop = val;
}

var a = new Class('foo');
var b = new Class('bar');

print( %HaveSameMap( a, b ) );

b.prop2 = 'baz';

print( %HaveSameMap( a, b ) );

Run $ d8 --allow-natives-syntax test.js

You should see true, then false. By adding b.prop2 = 'baz', we modified its structure and created a new hidden class.

Node.js

A lot of these flags (but not all of them) work with Node, too. --trace-opt, --prof, --allow-natives-syntax are all supported.

That can be helpful if you want to test something that relies on another library, since you can use Node’s require().

A list of supported V8 flags can be accessed with node --v8-options.

Links

Performance Tips for JavaScript in V8 (Good basic intro to Hidden Classes)

Use forensics and detective work to solve JavaScript performance mysteries

Breaking the JavaScript Speed Limit with V8

V8 - A Tale of Two Compilers (Good explanation of Inline Caches)

Anyway, this is all still pretty new to me, and there’s a lot I haven’t figured out yet. But the stuff I’ve found so far is pretty cool, so I wanted to write something up and share it.

Oh, and I’m sure there’s stuff in here that I’m wrong about, because I’m honestly a little out of my depth here. Feedback is appreciated.

使用 Demo 请参考 d8-shell-examples

参考

TypeScript+Jest+Coverage+Eslint+Prettier 项目初始化

2025-02-24T13:45:40.000Z

TypeScript

参考文档：https://www.typescriptlang.org/docs/handbook/typescript-tooling-in-5-minutes.html

初始化：

# 初始化 npm 项目
$ npm init -y
# 全局安装 TypeScript
$ npm install -g typescript
# 项目安装 TypeScript
$ pnpm add typescript -D
# 初始化 TypeScript 配置文件
$ tsc --init

配置 tsconfig.json：

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "outDir": "./dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

target：用于指定 TypeScript 代码编译后生成的 JavaScript 代码的目标版本。
module：用于指定 TypeScript 模块的目标模式，即编译后的 JavaScript 代码所使用的模块系统。
outDir：用于指定编译后的 JavaScript 文件输出目录的配置选项。
esModuleInterop：主要用于处理 ECMAScript 模块（ES 模块）与 CommonJS 模块之间的交互问题
当esModuleInterop设置为true时，TypeScript 编译器会在编译过程中生成一些额外的代码来处理 ES 模块和 CommonJS 模块之间的差异。具体来说，它会确保当从 ES 模块中导入 CommonJS 模块时，能够正确地获取到 CommonJS 模块的导出内容。
forceConsistentCasingInFileNames：用于指定是否强制使用一致的大小写来命名文件。
当forceConsistentCasingInFileNames设置为true时，TypeScript 编译器会在编译过程中严格检查所有导入和引用的文件名的大小写是否与实际文件系统中的文件名大小写一致。如果发现不一致，编译器将抛出错误，提示开发人员修正文件名的大小写问题。
strict：用于指定是否启用严格模式。
当strict设置为true时，TypeScript 编译器会启用严格模式，对代码进行更严格的类型检查和错误检测。这意味着编译器会对代码进行更严格的类型检查，以帮助开发人员发现潜在的类型错误和问题。
skipLibCheck：主要用于控制 TypeScript 编译器对声明文件（.d.ts）的类型检查行为，以下是具体介绍：
当编译器遇到skipLibCheck设置为true时，它会在编译过程中跳过对node_modules目录下以及types目录（如果有）中声明文件的类型检查。编译器仍然会处理这些声明文件，以便在代码中正确地使用它们提供的类型信息，但不会对其内部的类型定义进行严格的检查和验证。

配置文件优化：

{
  "compilerOptions": {
     /* 声明文件与源码映射 */
    "declaration": true,      // 生成 .d.ts 类型声明
    "declarationMap": true,   // 类型声明与源码映射
    "sourceMap": true,        // 生成调试用 sourcemap

    /* 路径与模块配置 */
    "baseUrl": ".",           // 模块解析基准路径[6,9](@ref)
    "paths": {                // 路径别名映射[6,9](@ref)
      "@/*": ["src/*"]
    },
  },
  "include": ["src/**/*"],
  "exclude": [
    "dist",
    "**/*.test.ts",
  ]
}

添加 scripts：

{
  "scripts": {
    "prebuild": "rimraf dist",
    "build": "tsc",
    "dev": "tsc --watch"
  },
  "devDependencies": {
    "rimraf": "^3.0.2"
  }
}

rimraf：用于删除指定目录下的所有文件和子目录。

创建第一个 TypeScript 文件：

// src/sum.ts
function sum(a: number, b: number) {
  return a + b;
}

export default sum;

执行 pnpm run build 命令，生成 dist 文件夹：

Jest

参考文档：https://jestjs.io/zh-Hans/docs/getting-started

安装 jest

# 全局安装 Jest
$ npm install -g jest
# 项目安装 Jest
$ pnpm add jest -D

安装 ts-jest

1	pnpm add ts-jest -D

安装 ts-jest 后，Jest 会自动识别 TypeScript 文件，并使用 ts-jest 进行编译和测试。

使用 ts-jest

为了让 Jest 使用 ts-jest 来转换 TypeScript，你还需要使用 jest --init 命令创建一个配置文件。之后在 jest.config.ts 文件中添加一行：preset: "ts-jest"。

1	pnpm add ts-jest -D

安装 ts-node

使用 Typescript 配置文件的还需给 Jest 安装 ts-node，请确保在项目中安装该依赖。

1	pnpm add ts-node -D

安装 @types/jest

安装 @types/jest 包。它为 Jest 的全局变量提供类型，无需导入它们。

1	pnpm add @types/jest -D

测试

创建一个测试文件，一般我们会把测试文件放在 __tests__ 目录下：

// src/__tests__/sum.test.ts
import sum from './sum';

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

执行 pnpm run test 命令，测试通过：

会在项目根目录下生成 coverage 文件夹，里面包含了测试覆盖率的报告：

Codecov

介绍

Codecov 是一款专注于代码覆盖率分析的在线服务平台，支持多种编程语言和测试框架，能够帮助开发者直观评估测试用例的有效性，并优化代码质量。

初始化

访问 codecov.io 网站，点击 Sign in with GitHub 按钮，授权登录。选择具体仓库进行配置：

在仓库中添加 TOKEN：

在项目根目录添加 .github/workflows/test.yaml 文件：

name: Run tests and upload coverage

on:
  push

jobs:
  test:
    name: Run tests and collect coverage
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Node
        uses: actions/setup-node@v4

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npx jest --coverage

      - name: Upload results to Codecov
        uses: codecov/codecov-action@v5
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          slug: youngjuning/fucking-js

执行完后访问 https://app.codecov.io/gh/youngjuning/jsace 网站，查看测试覆盖率：

eslint flat config

安装 @youngjuning/eslint-config

1	pnpm add @youngjuning/eslint-config eslint prettier typescript jest -D

添加 eslint.config.ts

import tseslint from 'typescript-eslint';
import youngjuning from '@youngjuning/eslint-config';

export default tseslint.config(youngjuning, {
  ignores: ['**/dist/**'],
});

pnpm Installation

要在 pnpm 中使用 ESLint，我们建议设置一个 .npmrc 文件，并至少包含以下设置：

1 2	auto-install-peers=true node-linker=hoisted

个人目标管理模型 OKR 和 SMART 的区别

2025-02-20T08:47:14.000Z

个人学习目标适合使用 OKR 和 SMART 模型都可以，但它们的适用场景和侧重点有所不同。选择哪种模型取决于你的学习目标类型、时间跨度以及你希望如何跟踪进展。

1. OKR（目标与关键结果）

特点：

目标（Objective）：描述一个有激励性的方向或愿景。
关键结果（Key Results）：具体的、可量化的指标，用于衡量目标是否达成。
适用场景：适合中长期目标，尤其是需要明确方向并量化成果的学习计划。

优点：

强调愿景驱动，能够激发动力。
通过关键结果提供清晰的衡量标准。
灵活调整，适合动态变化的目标。

缺点：

对初学者来说可能过于抽象，难以制定具体的关键结果。
需要定期回顾和调整，否则容易偏离目标。

示例：个人学习目标

# 学习目标（季度）

## 目标 1: 掌握 Python 编程基础
- **关键结果 1**: 完成一本 Python 入门书籍的学习（如《Python编程：从入门到实践》）。
- **关键结果 2**: 在 LeetCode 上完成 30 道简单难度的算法题。
- **关键结果 3**: 开发一个小型项目（如记账工具）并部署到 GitHub。

## 目标 2: 提升英语口语能力
- **关键结果 1**: 每周进行 3 次英语对话练习（每次至少 30 分钟）。
- **关键结果 2**: 参加一次在线英语演讲活动并获得反馈。
- **关键结果 3**: 英语听力测试分数提升至 85%。

适用人群：

希望设定中长期学习目标的人。
需要量化成果并定期检查进展的人。
喜欢挑战性目标并愿意不断调整的人。

2. SMART 模型

特点：

Specific（具体）：目标明确，避免模糊。
Measurable（可衡量）：可以量化或评估目标完成情况。
Achievable（可实现）：目标现实且符合自身能力。
Relevant（相关性）：目标与个人需求或长期规划相关。
Time-bound（有时限）：设置明确的时间节点。

优点：

结构化强，易于制定和执行。
适合短期目标或需要快速见效的任务。
强调可行性，减少挫败感。

缺点：

过于关注细节可能导致视野狭窄。
对于复杂或长期目标，可能缺乏灵活性。

示例：个人学习目标

# 学习目标（月度）

## 目标 1: 完成 Python 数据分析基础学习
- **Specific**: 学习 Pandas 和 NumPy 的基本操作。
- **Measurable**: 完成 Udemy 上的《Python数据分析入门课程》，并通过所有课后练习。
- **Achievable**: 每天投入 1 小时学习，周末复习。
- **Relevant**: 数据分析技能有助于未来职业发展。
- **Time-bound**: 在 1 个月内完成课程。

## 目标 2: 提高英语词汇量
- **Specific**: 每天记忆 10 个新单词。
- **Measurable**: 使用 Anki 软件记录单词，并确保每周掌握 70 个单词。
- **Achievable**: 每天花 15 分钟背单词，结合例句记忆。
- **Relevant**: 扩大词汇量有助于阅读和写作能力提升。
- **Time-bound**: 持续 3 个月，总计掌握 900 个单词。

适用人群：

希望设定短期、具体目标的人。
需要明确步骤和时间节点的人。
初学者或对目标管理不熟悉的人。

对比总结

特性	OKR	SMART
时间跨度	中长期（季度、半年、年度）	短期（周、月）
目标性质	愿景驱动，强调方向和成果	细节导向，强调可执行性和可行性
灵活性	动态调整，适应变化	固定性强，需按计划执行
适用场景	需要量化成果的复杂目标	需要快速见效的具体任务
学习者类型	喜欢挑战性目标，善于自我激励	偏好结构化指导，注重执行力

如何选择？

如果你是初学者：
- 推荐使用 SMART 模型，因为它更具体、更容易上手。
- 示例：每天背 10 个单词，每周写一篇短文。
如果你已经有明确的学习方向：
- 推荐使用 OKR 模型，因为它可以帮助你聚焦愿景并量化成果。
- 示例：目标是“成为数据科学家”，关键结果包括完成特定课程、完成项目等。

结合使用：

可以用 OKR 设定中长期目标，用 SMART 模型细化每个关键结果的具体执行计划。

示例：

# 季度目标（OKR）
## 目标 1: 成为初级数据分析师
- **关键结果 1**: 完成 Python 数据分析课程（SMART 计划：每天学习 1 小时，1 个月内完成）。
- **关键结果 2**: 完成一个数据分析项目（SMART 计划：每周投入 5 小时，2 个月内完成）。

最终建议

如果你的学习目标较为长期且需要激励自己，选择 OKR。
如果你的学习目标较为短期且需要明确的执行步骤，选择 SMART。
如果不确定，可以从 SMART 模型开始，逐步过渡到 OKR，或者将两者结合使用。

如果你能分享你的具体学习目标，我可以为你设计一个更贴合的方案！

JavaScript 数据结构

2025-01-21T15:57:59.000Z

数组

跟其他编程语言一样，JS 数组也是一组有序的数据，但跟其他语言不同的是，数组中的每个槽位可以存储任意类型的数组。
JS 数组是动态大小的，会随着数据添加而自动增长。

创建数组

使用 Array 构造函数

创建一个空数组：

1
2
3

// 创建一个空数组
const arr = new Array();
console.log(arr); // []

创建一个指定长度的数组，元素为 undefined：

1
2
3

// 创建一个长度为 5 的数组，元素为 undefined
const arr = new Array(5);
console.log(arr); // [undefined, undefined, undefined, undefined, undefined]

创建并初始化数组：

1
2
3

// 创建一个包含 [1, 2, 3] 的数组
const arr = new Array(1, 2, 3);
console.log(arr); // [1, 2, 3]

使用数组字面量

创建一个空数组：

1 2	const arr = []; // 创建一个空数组 console.log(arr); // []

直接定义数组元素：

1
2
3

// 创建一个包含 [1, 2, 3] 的数组
const arr = [1, 2, 3];
console.log(arr); // [1, 2, 3]

使用 `Array.from` 方法

从类数组对象或可迭代对象创建数组：

1 2	// 创建一个包含 [1, 2, 3] 的数组 let arr = Array.from({ length: 3 }, (_, i) => i + 1);

从字符串转换为数组：

1 2	// 创建一个包含 ['h', 'e', 'l', 'l', 'o'] 的数组 let arr = Array.from("hello");

使用 `Array.of` 方法

1 2	// 创建一个包含 [1, 2, 3] 的数组 let arr = Array.of(1, 2, 3);

使用 `Array.fill` 方法

1 2	// 创建一个长度为 5 的数组，元素全为 0。时间复杂度为 O(N) let arr = new Array(5).fill(0);

插入元素

在末尾插入元素

时间复杂度为 O(1)

1
2
3

const arr = [1, 2, 3];
arr.push(4); // 在末尾插入元素 4
console.log(arr) // [1, 2, 3, 4]

在开头插入元素

时间复杂度为 O(N)

1
2
3

const arr = [1, 2, 3];
arr.unshift(0); // 在开头插入元素 0
console.log(arr); // [0, 1, 2, 3]

在任意位置插入元素

时间复杂度为 O(N)

splice() 方法可以在数组的任意位置插入元素。它接受三个参数：

起始索引
要删除的元素的数量（如果不需要删除元素，设置为 0）
要插入的元素（可以是一个或多个）

1
2
3

const arr = [1, 2, 3];
arr.splice(1, 0, 1.5); // 在索引 1 的位置插入元素 1.5。
console.log(arr) // [1, 1.5, 2, 3]

删除元素

从末尾删除元素

时间复杂度为 O(1)

1
2
3

const arr = [1, 2, 3];
arr.pop(); // 删除末尾元素 3。
console.log(arr) // [1, 2]

从开头删除元素

时间复杂度为 O(N)

1
2
3

const arr = [1, 2, 3];
arr.shift(); // 删除开头元素 1。
console.log(arr); // [2, 3]

在任意位置删除元素

时间复杂度为 O(N)

splice() 方法可以删除数组的任意位置元素。它接受两个参数：

起始索引
要删除的元素的数量（如果不需要删除元素，设置为 0）
要插入的元素（可以是一个或多个）

1
2
3

const arr = [1, 2, 3];
arr.splice(1, 1); // 删除索引 1 的元素 2。
console.log(arr) // [1, 3]

修改元素

根据索引修改元素

时间复杂度为 O(1)

1
2
3

const arr = [1, 2, 3];
arr[0] = 100;
console.log(arr); // [100, 2, 3]

使用 `splice` 方法

时间复杂度为 O(N)

splice() 方法可以删除数组的任意位置元素。它接受两个参数：

起始索引
要删除的元素的数量（如果不需要删除元素，设置为 0）
要插入的元素（可以是一个或多个）

当你需要修改数组中连续的多个元素时，splice() 方法非常有用。

1
2
3

const arr = [1, 2, 3];
arr.splice(1, 1, 6); // 从索引 2 开始，删除 1 个元素，并插入新元素 6。
console.log(arr); // [1, 6, 3]

查询元素

根据索引查询元素值

时间复杂度为 O(1)

1
2
3

const arr = [1, 2, 3];
const element = arr[1]; // 查询索引 1 的元素 2。
console.log(element); // 2

根据元素值查找索引

时间复杂度为 O(N)

1
2
3

const arr = [1, 2, 3];
const index = arr.indexOf(2); // 查询元素 2 的索引 1。
console.log(index); // 1

链表

链表（Linked List）是一种常见的线性数据结构，它由一系列节点（Node）组成，每个节点包含两部分：数据域和指针域。数据域用于存储实际的数据，指针域则存储指向下一个节点的引用（在单链表中），通过这些指针将各个节点链接起来形成一个链式结构。

链表存储有序的元素集合，但不同于数组，链表中的元素在内存中不是连续放置的，而是通过指针相互关联。

链表的特点

插入和删除的效率高：在链表中插入或删除节点，只需要修改指针，时间复杂度为 O(1)。
随机访问效率低：由于链表中的节点在内存中不是连续存储的，不能像数组那样通过下标直接访问元素，需要从头节点开始依次遍历，时间复杂度为 O(n)。

链表的类型

单链表：每个节点包含一个数据元素和一个指向下一个节点的指针。链表的最后一个节点的指针通常指向 null，表示链表的结束。
双向链表：每个节点除了包含数据元素和指向下一个节点的指针外，还包含一个指向前一个节点的指针。这种结构允许在链表中双向遍历。
循环链表：单循环链表的最后一个节点的指针指向头节点，形成一个闭环；双循环链表则是双向链表的首尾相连形成闭环。

创建链表

节点类的实现

链表最后一个节点的下一个元素始终是 undefined 或 null。
当一个 Node 实例被创建时，它的 next 指针总是 undefined。这没问题，因为我们知道它会是链表的最后一项。

class ListNode {
  constructor(element) {
    // 数据域，存储节点的值
    this.element = element;
    // 指针域，指向下一个节点
    this.next = undefined;
  }
}

链表类的实现

class LinkedList {
  constructor() {
    // 存储链表中的元素数量
    this.count = 0;
    // 头节点，初始化为 undefined
    this.head = undefined;
  }
}

向链表尾部添加元素

class LinkedList {
  constructor() {
    this.count = 0;
    this.head = undefined;
  }

  push(element) {
    const node = new ListNode(element);
    let current;
    if (this.head == null) {
      // 如果链表为空，将头节点指向新节点
      this.head = node;
    } else {
      current = this.head;
      // 遍历链表，找到最后一个节点
      while (current.next != null) {
        current = current.next;
      }
      // 将最后一个节点的 next 指针指向新节点
      current.next = node;
    }
    // 递增链表的长度
    this.count++;
  }
}

循环迭代链表直到目标位置

循环到目标 index 的代码片段在 LinkedList 类的方法中很常见、因此我们将其提取到一个单独的方法中，这样就可以在不同的地方复用它。

注意：循环停止条件是小于目标 index，而不是小于等。这是因为目标的前一个节点的 next 就是目标节点。

class LinkedList {
  constructor() {
    this.count = 0;
    this.head = undefined;
  }

  getElementAt(index) {
    // 检查越界值
    if (index >= 0 && index <= this.count) {
      let current = this.head;
      for (let i = 0; i < index && current != null; i++) {
        current = current.next;
      }
      return current;
    }

    // 显式声明返回值
    return undefined;
  }
}

移除指定位置的元素

移除第一个元素：要做的就是让 head 指向列表的第二个元素。我们将用 current 变量创建一个对链表第一个元素的引用。这样 current 变量就是对链表中第一个元素的引用。如果把 head 赋为 current.next，就会移除第一个元素。
移除最后一个或中间某个元素：需要迭代链表的节点，直到找到要移除元素的前一个元素，我们用 previous 变量表示对当前元素的前一个元素的引用。在迭代到目标元素之后，current 变量会持有我们想从链表中移除的节点。因此，要从链表中移除当前元素，要做的就是将 previous.next 赋值为 current.next。

class LinkedList {
  constructor() {
    this.count = 0;
    this.head = undefined;
  }

  getElementAt(index) {
    // 检查越界值
    if (index >= 0 && index <= this.count) {
      let current = this.head;
      // 迭代整个链表直到目标 index。结束循环时，node 元素将是 index 位置元素的引用。
      for (let i = 0; i < index && current != null; i++) {
        current = current.next;
      }
      return current;
    }
    return undefined;
  }

  /**
   * 从链表的特定位置移除一个元素。
   * @param {number} index - 要移除的元素的索引。
   * @returns {any} - 被移除的元素的值。
   */
  removeAt(index) {
    // 检查越界值
    if (index >= 0 && index < this.count) {
      let current = this.head;
      // 移除第一项
      if (index === 0) {
        this.head = current.next;
      } else {
        const previous = this.getElementAt(index - 1);
        current = previous.next;
        // 将 previous 与 current 的下一项链接起来：跳过 current，从而移除它
        previous.next = current.next;
      }
      this.count--;
      return current.element;
    }
    return undefined; // 如果索引无效，则返回 undefined
  }
}

验证：

const list = new LinkedList();
list.push(5);
list.push(10);
list.push(15);
list.push(20);

// 验证删除指定元素
list.removeAt(1);
console.info(list);

如图可以看到，10 被成功移除了。

在任意位置插入元素

class LinkedList {
  constructor() {
    this.count = 0;
    this.head = undefined;
  }

  /**
   * 在任意位置插入元素
   */
  insert(element, index) {
    // 由于我们处理的是位置，就需要检查越界值
    if (index >= 0 && index <= this.count) {
      const node = new ListNode(element);
      if (index === 0) {
        // 在第一个位置添加
        const current = this.head;
        node.next = current;
        this.head = node;
      } else {
        const previous = this.getElementAt(index - 1);
        const current = previous.next;
        node.next = current;
        previous.next = node;
      }
      this.count++; // 更新链表长度
      return true;
    }

    return false;
  }
}

注意：使用变量引用我们需要控制的节点非常重要，这样就不会丢失节点之间的链接。我们可以只使用一个变量（previous），但那样会很难控制节点之间的链接。
因此，最后声明一个额外的 current 变量来帮助我们处理这些引用。

验证：

const list = new LinkedList();
list.push("张三");
list.push("王五");
list.insert("李四", 1);

如图，我们成功在索引 1 的位置插入了 15。

返回一个元素的位置

const defaultEquals = (a, b) => {
  return a === b;
}
class LinkedList {
  constructor(equalsFn = defaultEquals) {
    this.count = 0;
    this.head = undefined;
    this.equalsFn = equalsFn;
  }

  indexOf(element) {
    let current = this.head;
    for (let i = 0; i < this.count && current != null; i++) {
      if (this.equalsFn(element, current.element)) {
        return i;
      }
      current = current.next;
    }
    return -1;
  }
}

一如既往，需要一个变量来帮助我们循环访问列表。该变量是 current，它的初始值是 head。
然后迭代元素，从 head（索引 0）开始，直到链表长度（count 变量）为止。为了确保不会发生运行时错误，我们可以验证下 current 变量是否为 null 或 undefined。

从链表中移除元素

class LinkedList {
  constructor() {
    this.count = 0;
    this.head = undefined;
  }
  remove(element) {
    const index = this.indexOf(element);
    return this.removeAt(index);
  }
}

isEmpty、size 和 getHead 方法

class LinkedList {
  constructor() {
    this.count = 0;
    this.head = undefined;
  }
  isEmpty() {
    return this.count === 0;
  }
  size() {
    return this.count;
  }
  getHead() {
    return this.head;
  }
}

size：返回链表包含的元素个数，与数组的 length 属性类似。
getHead：返回链表包含的元素个数，与数组的 length 属性类似。
isEmpty：在链表中不包含元素时，返回 true，如果链表长度大于 0 则返回 false。

toString 方法

class LinkedList {
  constructor() {
    this.count = 0;
    this.head = undefined;
  }

  toString() {
    if (this.head === null) {
      return '';
    }
    let objString = `${this.head.element}`;
    let current = this.head.next;
    for (let i = 1; i < this.size() && current !== null; i++) {
      objString = `${objString},${current.element}`;
      current = current.next;
    }
    return objString;
  }
}

首先，列表为空（head 为 null 或 undefined），我们就返回一个空字符串，我们也可以用 this.isEmpty() 来判断。

All 纠音 & port 词根

2024-11-18T23:33:25.000Z

All 纠音

音标分析

[ɔː]：这是一个长元音，发音时口型要张大，舌身压低并后缩，舌尖不抵下齿，双唇稍收圆。可以先发 [ɔ] 的音，然后将音拉长，就得到了 [ɔː] 的发音。
[l]：这个音是舌边音，当它位于元音后时，舌尖抵住上齿龈，舌面稍凹，舌后部向软腭抬起，气流从舌两侧通过，发出类似 “欧” 的音，但要注意舌尖始终抵住上齿龈，不要离开。

发音技巧

先发 [ɔː] 的音，要保证发音的长度和饱满度，然后自然地滑向 [l] 的音，将二者连贯地发出，不要有明显的停顿。
注意整体发音的流畅性和连贯性，不要把 [ɔː] 和 [l] 的发音割裂开来，同时要注意发音的力度和清晰度，不要含糊不清。

常见错误及纠正

错误一：把 [ɔː] 发成 [ɒ]，这是比较常见的错误，[ɒ] 的口型比 [ɔː] 要小，发音也更短促。纠正方法是张大嘴巴，尽量将舌身压低后缩，发出更饱满的 [ɔː] 音。
错误二：忽略 [l] 的发音，或者发音不清晰。这可能导致单词的发音不准确，听起来像 [ɔː] 单独的音。要注意舌尖抵住上齿龈，清晰地发出 [l] 的音，使整个单词的发音完整准确。
错误三：发音时口型变化不自然，导致发音生硬。发音过程中要注意口型的逐渐过渡，从 [ɔː] 的张大嘴巴到 [l] 的舌尖抵住上齿龈，动作要连贯自然，才能发出准确流畅的 “all” 的音。
可以多听一些标准的发音音频，模仿练习，不断纠正自己的发音，逐渐掌握 “all” 的正确发音。

port 词根

词根 port 的来源和历史演变

词根 “port” 来源于拉丁语动词 “portare”，其基本含义是 “to carry”，即 “搬运”“携带” 之意。

在拉丁语中，“portare” 是一个常用的动词，通过词形变化等方式衍生出了众多与 “搬运”“携带” 相关的词汇。后来，随着语言的发展和演变，这些词汇被借入到英语中，并在英语中保留了 “port” 这个词根，且其含义也基本保持了与 “搬运”“携带” 相关的意义，如 “import”“export”“transport” 等词都体现了这一基本含义。

同时，从 “搬运” 这一动作延伸，与货物的装卸、运输等相关的地点也用 “port” 来表示，进而有了 “港口” 的含义，像 “seaport”“airport” 等词都是由此演变而来。这体现了语言在发展过程中，词汇的意义会根据人们的认知和社会发展的需要逐渐扩展和演变。

表示 “搬运”

import：im - 表示 “进入”，import 即把物品搬运进入一个国家或地区，意为 “进口”，如：The country imports a large amount of oil.（这个国家进口大量石油。）
export：ex - 表示 “出去”，export 则是把物品搬运出去，即 “出口”，如：China exports many kinds of products to the world.（中国向世界出口多种产品。）
transport：trans - 表示 “转移”“跨越”，transport 就是把人或物从一处搬运到另一处，意为 “运输”“运送”，如：The goods were transported by train.（货物通过火车运输。）

表示 “携带”

portable：-able 表示 “可…… 的”，portable 即可以携带的，意为 “便携式的”“轻便的”，如：I bought a - portable computer.（我买了一台便携式电脑。）
porter：表示搬运东西的人，即 “搬运工”“行李员”，如：The porter carried our luggage to the room.（行李员把我们的行李搬到房间。）

表示 “港口”

port：本身可作名词表示 “港口”“口岸”，如：The ship arrived at the port safely.（船安全抵达港口。）
airport：air 表示 “空气”“天空”，airport 即飞机起降的港口，意为 “机场”，如：I will meet you at the airport.（我会在机场接你。）
seaport：sea 表示 “海”“海洋”，seaport 就是海边的港口，意为 “海港”“港口城市”，如：This city is a famous seaport.（这座城市是一个著名的海港。）

Hello 纠音 & priv 词根

2024-11-14T04:45:44.000Z

Hello 纠音

Hello 的常见发音是 [həˈləʊ]，以下是对这个单词发音的详细纠音讲解：

音标分析

[h]：这是一个清辅音，发音时气流从肺部呼出，通过声门时不受阻碍，仅在通过声门时形成轻微的摩擦，声带不振动。发音时，嘴巴张开，舌头自然放松，让气流自然地从口中呼出，同时发出 “喝” 的音，但不要过于用力。例如，在单词 hat [hæt]、hot [hɒt] 中，都有这个音素。
[ə]：这是一个中央元音，发音时舌身中部稍抬起，舌尖微抵下齿龈，双唇向两旁平伸，成扁平形。发音时，口腔肌肉放松，发出类似 “呃” 的音，是一个比较弱的音。比如在单词 about [əˈbaʊt]、again [əˈɡen] 中都有此音。
[ˈləʊ]：这是一个双元音，由 [l] 和 [əʊ] 两个音素组成。首先发 [l] 音，舌尖抵住上齿龈，舌前部向硬腭尽量抬起，气流从舌的两侧泄出，声带振动，这个音类似于汉语中的 “了”，但发音位置更靠后。然后迅速向 [əʊ] 滑动，[əʊ] 的发音是由 [ə] 向 [ʊ] 滑动，双唇由扁平到收圆，声带振动，发出类似 “欧” 的音。在单词 low [ləʊ]、go [ɡəʊ] 中都含有 [əʊ] 这个音素。

发音技巧

注意重音在第二个音节，即 [ləʊ] 上，发音时要适当加重这个音节的读音，突出重音，使发音更准确自然。
整个单词发音要连贯流畅，各个音素之间的过渡要自然，不要有明显的停顿或割裂感。特别是在发双元音 [ˈləʊ] 时，从 [l] 到 [əʊ] 的滑动要迅速而自然，避免生硬。

priv 词根

单个

含义解释：强调个体的、独自的，与集体相对。

例词：

private ['praɪvət]：adj. 私人的；个人的；私下的；私有的。
- This is my private car.（这是我的私人汽车。）
privacy ['prɪvəsi]： n. 隐私；秘密；隐居；隐居处。
- We should respect everyone’s privacy.（我们应该尊重每个人的隐私。）
privilege [ˈprɪvəlɪdʒ]：n. 特权，优待。= priv（单个） + i + lege（法律）
- Gold card holders enjoy more privileges.（金牌持有者享有更多的特权。）

使丧失

含义解释：有剥夺、使失去某种权利或东西的意思。

例词：

deprive [dɪ'praɪv]：vt. 使丧失，剥夺。
- The accident deprived him of his legs.（这场事故使他失去了双腿。）
privation [praɪ'veɪʃn]：n. 贫困；丧失；被剥夺了某物的状态。
- He suffered great privation during the war.（他在战争期间遭受了极大的困苦。）

「已解决」error:0308010C:digital envelope routines::unsupported

2024-10-24T09:48:38.000Z

error:0308010C:digital envelope routines::unsupported 常出现在把旧前端项目切到 Node.js 17 或更高版本之后。它看起来像业务代码报错，实际是构建工具请求了 OpenSSL 3 默认不再支持的旧算法。

一句话总结

--openssl-legacy-provider 只能救急。长期方案是升级 Webpack/相关 loader，或把项目固定在兼容的 Node LTS；不要把这个环境变量当作永久配置。

如何确认根因

如果堆栈里包含 webpack/lib/util/createHash、ERR_OSSL_EVP_UNSUPPORTED，且故障发生在 dev 或 build 初期，基本就是这个问题。常见组合是旧版 Webpack 4 与 Node.js 17+。

临时恢复构建

macOS / Linux：

1 2	export NODE_OPTIONS=--openssl-legacy-provider pnpm build

Windows PowerShell：

1 2	$env:NODE_OPTIONS='--openssl-legacy-provider' pnpm build

也可以仅给某个 script 设置该变量；重点是把它视为短期兼容层，并记录清理期限。

优先的长期修复

升级 Webpack、React Scripts 或框架脚手架到支持 OpenSSL 3 的版本。
同时升级依赖它们的 plugin、loader，避免 lockfile 把旧依赖重新拉回来。
对短期无法升级的遗留项目，使用项目约定的 Node LTS，并通过 .nvmrc、Volta 或 CI 固定版本。

例如：

1 2	# .nvmrc 16

需要注意：选择旧 LTS 是为了给升级争取窗口，不是长期停留在已停止维护的运行时。

不要混淆的场景

如果错误发生在运行时的加密、签名或 TLS 逻辑中，而不是构建阶段，不能简单套用 legacy provider。应先确认算法、证书或上游 SDK 是否需要迁移，否则可能降低安全性。

我的判断框架

可以临时用：旧项目本地开发或一次性构建恢复。

优先修：持续交付、生产镜像和即将升级 Node 的项目；把工具链升级纳入技术债计划。

如何使用 Node.js 将你的设备变成一个简单的服务器

2024-09-25T10:27:35.000Z

原文地址：How to Turn Your Device Into a Simple Server Using Node.js
原文作者：Trix Cyrus

让我们一起在你的设备上部署一个简单的 Node.js。

入门

首先，让我们使用 Node.js 创建一个基础的服务。步骤如下：

创建一个 node-server 目录：

1 2	mkdir node-server cd node-server

初始化一个 Node.js 项目：

1	npm init -y

安装依赖：

1	npm install express ws multer mongoose dotenv helmet morgan cluster compression

express：处理 HTTP 请求
ws：支持 Websocket
multer：处理文件上传
mongoose：MongoDB 链接
dotenv：读取环境变量
helmet：保护服务器安全
morgan：日志
cluster：多线程
compression：用于压缩响应数据

创建一个 .env 文件

在项目根目录，创建一个 .env 文件，它的作用是用来存储环境变量：

1 2	PORT=8080 MONGO_URI=mongodb://localhost:27017/serverdb

创建一个 server.js 文件：

1 2	touch server.js nano server.js

粘贴下面的代码：

require('dotenv').config();
const express = require('express');
const ws = require('ws');
const http = require('http');
const multer = require('multer');
const mongoose = require('mongoose');
const helmet = require('helmet');
const morgan = require('morgan');
const cluster = require('cluster');
const os = require('os');
const compression = require('compression');
const fs = require('fs');
const path = require('path');

const PORT = process.env.PORT || 8080;
const MONGO_URI = process.env.MONGO_URI;
const NUM_CPUS = os.cpus().length;

if (cluster.isMaster) {
  console.log(`Master process is running. Spawning ${NUM_CPUS} workers...`);
  for (let i = 0; i < NUM_CPUS; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died. Spawning a new worker.`);
    cluster.fork();
  });
} else {
  const app = express();
  const server = http.createServer(app);
  const wss = new ws.Server({ server });

  mongoose.connect(MONGO_URI, { useNewUrlParser: true, useUnifiedTopology: true })
    .then(() => console.log('Connected to MongoDB'))
    .catch(err => console.error('MongoDB connection error:', err));

  app.use(express.json());
  app.use(helmet());
  app.use(morgan('common'));
  app.use(compression());

  const upload = multer({ dest: 'uploads/' });

  app.use(express.static(path.join(__dirname, 'public')));

  app.use((req, res, next) => {
    console.log(`Received ${req.method} request for ${req.url}`);
    next();
  });

  wss.on('connection', (socket) => {
    console.log('WebSocket connection established.');
    socket.on('message', (message) => {
      console.log(`Received WebSocket message: ${message}`);
      socket.send(`Message received: ${message}`);
    });
  });

  app.get('/', (req, res) => {
    res.sendFile(path.join(__dirname, 'public', 'index.html'));
  });

  app.get('/api/data', async (req, res) => {
    res.json({ message: 'Server API Response', data: [] });
  });

  app.post('/upload', upload.single('file'), (req, res) => {
    console.log('File uploaded:', req.file);
    res.status(201).json({ message: 'File uploaded successfully', file: req.file });
  });

  app.get('/greet/:name', (req, res) => {
    const name = req.params.name || 'stranger';
    res.send(`Hello, ${name}!
`);
  });

  app.use((req, res, next) => {
    res.status(404).sendFile(path.join(__dirname, 'public', '404.html'));
  });

  app.use((err, req, res, next) => {
    console.error('Error encountered:', err);
    res.status(500).json({ error: 'An internal server error occurred' });
  });

  server.listen(PORT, () => {
    console.log(`Worker process ${process.pid} is running on port ${PORT}`);
  });
}

创建一个 public 文件夹：

1 2	mkdir public cd public

index.html

用作的首页的基本的 HTML 文件：

html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Node.js Servertitle>
head>
<body>
    <h1>Welcome to the node.js Server!h1>
    <p>This server is a simple server.p>
body>
html>

404.html

html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>404 - Page Not Foundtitle>
head>
<body>
    <h1>404 - Page Not Foundh1>
    <p>The page you are looking for doesn't exist in this universe.p>
body>
html>

启动服务器

1	node server.js

测试服务器功能

实时通信：您可以设置一个 WebSocket 客户端向服务器发送消息。
文件上传：向“http://localhost:8080/upload”发送 POST 请求并附上一个文件，它将被保存到上传文件夹中。
RESTful API：访问“http://localhost:8080/api/data”以查看 API 响应。
错误处理：访问任何不存在的 URL（例如“http://localhost:8080/nonexistent”）以查看自定义的 404 页面。
数据库：将您的服务器连接到一个 MongoDB 实例，并修改/api/data 路由以查询并返回实际数据。

最终目录：

node-server/
├── public/
│   ├── index.html
│   ├── 404.html
├── server.js

一切就绪

你已经在你的设备创建并运行一个简单的 Node.js 服务器！这是学习后端开发基础知识以及了解服务器如何工作的好方法。

Google Adsense High eCPM

2024-09-15T02:12:11.000Z

保险（Insurance）

保险行业广告费投入多，主要有以下几方面原因：

1、行业竞争激烈

市场主体众多：保险市场上的公司数量不断增加，无论是大型保险公司还是小型保险企业，都希望在市场中占据一席之地。截至2023年，国内的保险公司数量众多，各公司在产品、服务、价格等方面的差异较小，所以需要通过大量的广告宣传来突出自己的品牌和优势，吸引消费者的关注。例如，在车险市场，有多家大型保险公司以及众多中小保险公司竞争，为了争夺客户，都加大了广告投入。
产品同质化严重：保险产品在条款、保障范围等方面具有较高的相似性。对于消费者来说，很难从产品本身直观地分辨出不同公司产品的差异。因此，保险公司需要通过广告宣传来塑造品牌形象，让消费者对其品牌产生认知和信任，从而在众多竞品中选择自己的产品。

2、品牌建设需求高：

建立信任基础：保险产品是一种基于信任的金融服务，消费者在购买保险时，对保险公司的信誉和可靠性非常关注。通过大规模的广告宣传，保险公司可以向消费者传递自己的专业、可靠、稳健的形象，增强消费者对公司的信任。特别是对于一些新成立的保险公司或者知名度较低的公司，更需要通过广告来快速提升品牌知名度和信任度。
提升品牌影响力：在保险行业，品牌影响力对于公司的发展至关重要。具有较高品牌影响力的公司能够吸引更多的客户、合作伙伴和优秀的人才。广告宣传是提升品牌影响力的重要手段之一，通过在各种媒体上的广泛传播，保险公司的品牌能够被更多的人所了解和认可。

3、客户获取成本高：

销售模式的特点：保险产品的销售通常需要通过代理人、经纪人等中介渠道，或者通过电话销售、网络销售等方式进行。这些销售方式都需要投入大量的人力、物力和财力。相比其他行业，保险产品的销售周期较长，客户的决策过程也较为复杂，需要不断地进行沟通和解释。因此，保险公司需要通过广告宣传来提高客户的认知度和兴趣度，降低销售成本。
客户群体广泛：保险产品的潜在客户群体非常广泛，包括个人客户和企业客户，涵盖了不同年龄、性别、职业、收入水平的人群。为了覆盖到尽可能多的潜在客户，保险公司需要在各种媒体平台上进行广告投放，这也导致了广告费用的增加。

4、业务拓展的需要：

新产品推广：保险公司不断推出新的保险产品和服务，以满足市场需求和客户的个性化需求。新产品的推出需要进行大量的宣传推广，让消费者了解产品的特点、优势和适用场景。广告是新产品推广的重要手段之一，能够快速地将产品信息传递给潜在客户，提高产品的知名度和市场占有率。
开拓新市场：随着经济的发展和人们保险意识的提高，保险市场的潜力不断被挖掘。保险公司需要不断开拓新的市场领域，如农村市场、互联网保险市场等。在开拓新市场的过程中，广告宣传能够帮助保险公司快速地进入市场，提高品牌知名度和市场份额。

5、监管要求和信息披露：

合规宣传的需要：保险行业受到严格的监管，保险公司需要按照监管要求进行信息披露和宣传。为了确保广告内容的合规性和准确性，保险公司需要投入一定的资源进行广告策划、制作和审核。同时，监管部门也要求保险公司在广告宣传中不得进行虚假宣传、误导消费者等行为，这也增加了保险公司的广告成本。
风险提示和教育：保险产品涉及到复杂的条款和风险，消费者在购买保险时需要了解相关的风险和注意事项。保险公司需要通过广告宣传来进行风险提示和保险知识教育，帮助消费者正确理解保险产品，提高消费者的风险意识和保险素养。这也需要保险公司投入一定的广告费用。

法律（Lawyer）

Medical Malpractice Lawyer
Legal advice
Business law
Criminal law
Family law
Contract law
Intellectual property law
Employment law
Real estate law
Environmental law
International law

教育（education）

mba best colleges
1 year Master’s degrees
Recommend a nearby scholarships
Quality education resources
Innovative teaching methods
Best educational institutions
Online education platforms
Distance learning opportunities
Educational technology tools
Early childhood education
Higher education scholarships
Lifelong learning programs
Special education needs

律师（Attorney）

Top lawyers nearby
Best law firms for economy
Experienced criminal defense lawyers
Family law attorneys near me
Business litigation lawyers
Intellectual property lawyers
Personal injury lawyers reviews
Immigration lawyers services
Real estate lawyers advice
Bankruptcy lawyers assistance

AI 推荐

Financial planning（财务规划）：Deals with personal finance which attracts advertisers in the banking and investment sectors.
Health insurance comparison（健康保险比较）：High demand as people are constantly looking for the best health insurance options.
Luxury travel destinations（豪华旅游目的地）：Appeals to high-end travel companies and luxury brands.
Online business courses（在线商业课程）：Reason: Targets entrepreneurs and professionals looking to enhance their skills.
Smart home technology（智能家居技术）：A growing market with many companies advertising their smart home products.
Organic skincare products（有机护肤品）：Popular in the beauty and wellness industry.
Pet care services（宠物护理服务）：Pet owners are always looking for good care options for their furry friends.
Fitness equipment reviews（健身器材评价）：People interested in fitness are likely to click on ads related to fitness equipment.
Wedding planning ideas（婚礼策划创意）：A lucrative market with many advertisers in the wedding industry.
Green energy solutions（绿色能源解决方案）：As the demand for sustainable energy grows, advertisers in this field are likely to pay well.

Youtuber 推荐

PaloAltoNetworks
Allergan
Avemco

程序员如何学习英语

2024-09-11T11:34:35.000Z

学习方法

词汇积累

制定计划：确定每天要学习的词汇量，比如每天学习 20 个新单词。可以利用单词书、手机应用（如百词斩、扇贝单词等）来辅助学习。
语境记忆：将单词放在具体的语境中去理解和记忆，比如阅读英文文章、观看英语电影或电视剧。遇到生词时，结合上下文猜测其含义，然后再查阅词典进行确认。
词根词缀法：学习常见的词根、词缀，这样可以帮助你推断出许多陌生单词的含义。例如，“un-”表示否定，“re-”表示再次等。
联想记忆：将新学的单词与已知的事物、场景或概念联系起来，创造有趣的联想，以便更好地记住它们。

听力训练

多听英语广播：如 BBC、CNN 等，让自己沉浸在英语环境中。可以在早上起床后、做家务时或者乘坐交通工具时收听。
观看英语电影和电视剧：选择有英文字幕的影片，先观看一遍了解剧情，然后再反复观看，尝试不看字幕理解对话内容。
听英语歌曲：选择自己喜欢的英语歌曲，边听边看歌词，学习其中的词汇和表达方式。还可以跟着哼唱，提高口语发音。
做听力练习：可以使用英语学习教材配套的听力材料，或者在网上搜索专门的听力练习题。做完练习后，对照答案分析错误原因，逐步提高听力水平。

口语练习

模仿跟读：选择英语原声材料，如英语电影片段、英语演讲等，进行模仿跟读。注意模仿语音、语调、语速和停顿，尽量让自己的发音更标准。
口语交流：寻找英语学习伙伴或者参加英语角，与他人进行口语交流。不要害怕犯错，勇敢地表达自己的想法。
录制自己的声音：用手机或录音设备录制自己的英语口语练习，然后回放听一听，找出不足之处并加以改进。
参加口语课程：报名参加线上或线下的英语口语课程，有专业的老师指导可以更快地提高口语水平。

阅读提升

选择适合的阅读材料：根据自己的英语水平选择难度适中的英文书籍、报纸、杂志或文章。可以从简单的儿童读物开始，逐渐过渡到更复杂的文学作品。
精读与泛读结合：精读时，仔细分析文章的结构、语法和词汇，理解每一个句子的含义。泛读时，快速浏览文章，了解大意即可，主要是提高阅读速度和语感。
做阅读笔记：在阅读过程中，遇到好的词汇、短语和句子可以记录下来，方便日后复习和运用。
阅读挑战：给自己设定阅读目标，比如每周读完一本英文书或者每天阅读一定数量的文章，坚持下去可以提高阅读能力。

写作锻炼

仿写练习：选择优秀的英语范文，模仿其结构、风格和表达方式进行写作练习。可以从简单的句子仿写开始，逐渐过渡到段落和文章的仿写。
坚持写作日记：用英语记录自己的日常生活、想法和感受。这不仅可以提高写作能力，还能帮助你更好地掌握词汇和语法。
找老师或伙伴批改：将自己写的文章交给老师、英语学习伙伴或者使用在线写作批改工具，让他们指出其中的错误和不足之处，以便及时改进。
参加写作比赛：参加英语写作比赛可以激发自己的学习动力，同时也能从其他参赛者的作品中学习到很多写作技巧和经验。

英文环境搭建

为了更好地耳濡目染，将每天使用频率最高的工具设置成英文版本。

vscode studio 不安装汉化插件
手机系统设置成英文

英语学习资源

以下是一些适合程序员学习英语的学习资源：

在线学习平台

Codecademy：这是一个在线的交互式编程学习平台，提供多种编程语言课程。在学习编程语言的同时，注重教授与编程相关的英语技能，用户可以通过项目和任务在真实编程场景中使用英语，加深记忆。
Udemy：有大量由专业人士或机构开设的编程课程，部分课程是全英文教学，课程内容丰富多样，涵盖了从基础到高级的各种编程技能和知识，可以根据自己的需求选择适合的课程来学习英语和编程。

技术文档和官方网站

英语学习应用

百词斩：一个专注于英语学习的单词记忆应用，可以帮助你记忆单词、复习单词、查找单词、背单词等。
豆包：字节跳动大模型英语，划词翻译、收藏、AI 助教等功能很适合日常使用。

英文技术博客和论坛

Stack Overflow：全球最知名的技术问答社区，程序员可以在这里找到各种技术问题的解答和讨论。阅读和参与 Stack Overflow 上的问答，能够接触到大量的专业英语表述和技术讨论，提高英语阅读和写作能力。
Medium：有许多程序员和技术专家在上面分享自己的编程经验、技术见解和学习心得等文章。阅读 Medium 上的英文技术文章，可以了解行业的最新动态和技术趋势，同时提升英语阅读和理解能力。
Reddit 的相关技术子论坛，如 /r/programming、/r/learnprogramming 等，程序员们可以在这些论坛上交流技术问题，阅读和参与讨论也能提升英语水平。

视频教程平台

YouTube：有许多程序员上传的英文编程教程、技术分享、项目演示等视频，内容丰富多样，可以根据自己的兴趣和需求选择观看，锻炼英语听力和理解能力，同时学习编程知识。
B 站：也有一些搬运或原创的英文编程教学视频，部分视频还会配有中文字幕，方便学习和理解。

英语学习计划

英文写作可以使用人工智能解决，但是使用频次高的词汇、阅读、听力和口语就必须熟练掌握了。毕竟，借助人工智能会打断你的阅读，更别提人工智能没法在实时交流是帮上忙了。

翻译英文文档一篇：锻炼词汇、阅读能力
精听一篇英文文章：锻炼听力能力
TalkAI 进行模拟面试练习

TypeScript 描述树结构

2024-07-10T03:21:12.000Z

例如，下面是一个使用递归定义的树形结构的例子：

type TreeNode = {
  value: T;
  children: TreeNode[];
};

const tree: TreeNode<string> = {
  value: "root",
  children: [
    {
      value: "child1",
      children: [
        {
          value: "grandchild1",
          children: [],
        },
        {
          value: "grandchild2",
          children: [],
        },
      ],
    },
    {
      value: "child2",
      children: [],
    },
  ],
};

在这个例子中，我们定义了一个TreeNode类型，它包含一个值和一个子节点数组。子节点数组也是一个 TreeNode 类型，这就形成了一个递归结构。我们可以使用这个类型来描述一个树形结构，其中每个节点可以有任意数量的子节点，也可以没有子节点。

这种递归结构特性可以用于解决很多问题，例如遍历树形结构、计算树的深度、判断树是否平衡等问题。同时，递归结构也可能会导致性能问题，因此在实际使用中需要注意递归深度的限制和性能优化。

人工智能概念学习

2024-04-05T15:12:43.000Z

人工智能（AI）

AI，全称 Artificial Intelligence，人工智能。

人工智能是一种模拟人类智能的技术和系统。人工智能的目标是使机器能够像人类一样思考、学习、推理和解决问题。它涉及到多个领域，包括机器学习、深度学习、自然语言处理、计算机视觉等。

人工智能技术可以分为弱人工智能和强人工智能两种类型。弱人工智能是针对特定任务的智能系统，如语音识别、图像识别等。而强人工智能则是具有与人类相似的智能水平，能够在各种任务上表现出类似甚至超越人类的智能。

人工智能技术在各个领域都有广泛的应用，如医疗保健、金融、交通、教育等。在医疗领域，人工智能可用于辅助医生进行诊断和制定治疗方案；在金融领域，人工智能可用于风险管理和交易预测；在交通领域，人工智能可用于交通流量优化和自动驾驶技术；在教育领域，人工智能可用于个性化教学和学习辅助等。

随着深度学习等技术的发展，人工智能在各个领域取得了巨大进展，并为社会带来了许多便利和创新。人工智能技术的不断发展和应用将继续推动科技进步和社会发展。

机器学习（ML）

ML，全称 Machine Learning，机器学习。

机器学习是一门开发算法和统计模型的科学，计算机系统使用这些算法和模型，在没有明确指令的情况下，依靠既有模式和推理来执行任务。计算机系统使用机器学习算法来处理大量历史数据。并识别数据模式。还可让计算机系统根据给出的输入数据集更准确地预测结果。例如，数据科学家可以通过存储数百万的扫描图片和相应诊断来训练医学应用程序，使该程序能够根据 X 光图片诊断癌症。

机器学习的工作原理是什么？

机器学习的核心思想是任意输入和输出数据组合之间的现有数学关系。机器学习模型事先不知道这种关系，但如果给出足够的数据集，它可以猜测出来。这意味着每个机器学习算法都是围绕一个可修改的数学函数构建的。基本原理可以这样理解：

我们为算法提供了以下输入/输出(i,o)组合来“训练”算法：(2,10)、(5,19)、(9,31)
算法计算出输入和输出之间的关系为：o=3*i+4
我们为算法提供输入 7，并要求算法预测输出。算法会自动确定输出位 25。

虽然这只是机器学习的基本理解，但机器学习关注的是一个原则，即所有复杂的数据点都可以通过计算机系统建立数学关联，只要它们有足够的数据和计算能力来处理这些数据。因此，输出的准确度与给定的输入大小直接相关。

机器学习算法有哪些类型？

机器学习包括传统机器学习和深度学习，有以下几种类型：

监督学习（Supervised Learning）：每个样本都有对应的目标值，通过搭建模型实现从输入特征向量到目标值的映射，例如解决回归和分类问题。
无监督学习（Unsupervised Learning）：所有样本没有目标值，期望从数据本身发下一些潜在规律，例如解决聚类问题。
强化学习（Reinforcement Learning）：相对较为复杂，系统和外界环境不断交互，在外界反馈的基础上决定自身行为，已达到目标最优化。例如阿尔法为其和无人驾驶。

机器学习和人工智能的关系

机器学习是人工智能的一个重要分支，属于实现人工智能的技术手段之一。人工智能是一门研究如何使计算机能够模拟人类智能行为的学科，而机器学习则是实现这一目标的关键方法之一。

具体来说，机器学习是让计算机系统从数据中学习并改进性能的技术，而人工智能则包括了更广泛的概念，涵盖了各种技术和方法，如专家系统、自然语言处理、计算机视觉等。机器学习作为实现人工智能的重要手段之一，通过让计算机系统从数据中学习规律和模式，使其具备类似人类智能的能力。

在实际应用中，机器学习技术被广泛应用于各种人工智能任务中，如语音识别、图像识别、自然语言处理等。通过不断优化算法和模型，机器学习使得计算机系统能够逐渐展现出类似人类智能的行为和能力，推动了人工智能领域的发展和进步。

深度学习（DL）

DL，全称 Deep Learning，深度学习。

深度学习是机器学习的一个分支，它是一种通过模仿人类大脑的神经网络结构来实现学习和推断的技术。深度学习利用多层神经网络来学习数据的特征表示，从而可以在大规模数据集上进行复杂的模式识别和预测任务。机器学习则是一种更广泛的概念，涵盖了各种通过算法让计算机系统从数据中学习和改进性能的技术。深度学习是机器学习的一个重要分支，它在图像识别、语音识别、自然语言处理等领域取得了显著的成就。

神经网络（Neural Network）

NN，全称 Neural Network，神经网络。

神经网络是一种受到生物神经系统启发而设计的人工智能模型，用于模拟人类大脑的学习和推断过程。神经网络由多个神经元（节点）组成，这些神经元通过连接（权重）相互关联，形成多层网络结构。

在神经网络中，通常包括输入层、隐藏层和输出层。输入层接收原始数据输入，隐藏层通过学习数据中的特征表示来提取数据的高级特征，输出层根据学习到的特征进行预测或分类。

神经网络的训练过程通常通过反向传播算法来实现。在训练过程中，神经网络通过不断调整连接权重，使得模型能够逐渐优化并学习到数据中的模式和规律。这样，神经网络就能够在给定输入数据的情况下做出准确的预测或分类。

神经网络有哪些类型？

前馈神经网络（Feedforward Neural Network，FNN）：前馈神经网络是最简单的神经网络形式，信息在网络中单向传递，不会形成循环。它包括输入层、隐藏层和输出层，常用于分类和回归任务。
卷积神经网络（Convolutional Neural Network，CNN）：卷积神经网络主要用于处理图像数据，具有共享权重和局部连接的特点，能够有效提取图像特征。CNN在计算机视觉领域取得了巨大成功。
循环神经模型（Recurrent Neural Network，RNN）：循环神经网络具有循环结构，能够处理序列数据，如自然语言处理任务。RNN具有记忆功能，能够保留先前的信息，但存在梯度消失和梯度爆炸问题。
长短期记忆网络（Long Short-Term Memory，LSTM）：LSTM 是 RNN 的一种变体，通过门控机制解决了梯度消失和梯度爆炸问题，适用于处理长序列数据。
生成对抗网络（Generative Adversarial Network，GAN）：生成对抗网络由生成器和判别器组成，通过对抗训练实现生成逼真数据的目标。GAN 在图像生成、风格迁移等任务中表现出色。
自编码器（Autoencoder）：自编码器是一种无监督学习模型，通过将输入数据压缩表示并重建输出数据来学习数据的有效表示。自编码器常用于降维和特征提取。

神经网络的机器学习的关系

神经网络是机器学习的一种技术手段，属于机器学习的范畴。机器学习是一种人工智能的分支领域，旨在让计算机系统能够从数据中学习和改进性能，而神经网络则是实现这一目标的重要工具之一。

在机器学习中，除了神经网络外，还包括传统的机器学习算法，如决策树、支持向量机、K近邻等。这些算法通常用于处理结构化数据和特定任务，如分类、回归、聚类等。神经网络则更适用于处理复杂的非线性关系和大规模数据集，具有强大的表征学习能力。

神经网络和深度学习的关系

神经网络是深度学习的基础，是实现深度学习的重要工具之一。

具体来说，神经网络是受到生物神经系统启发而设计的人工智能模型，由多个神经元（节点）组成，通过连接（权重）相互关联，形成多层网络结构。深度学习通过构建多层神经网络（即深层网络）来实现对数据的高级抽象和表征，从而提高对数据的理解和预测能力。

在深度学习中，神经网络扮演着核心角色，通过多层神经元之间的连接和权重调整来实现对数据的学习和建模。深度学习技术基于神经网络结构，能够处理复杂的数据模式和关系，取得了在计算机视觉、自然语言处理、语音识别等领域的显著进展。

因此，可以说深度学习是建立在神经网络基础上的一种机器学习技术，通过构建多层神经网络结构实现对数据的高级抽象和表征，从而提高对数据的理解和预测能力。神经网络作为深度学习的基础组件，在人工智能领域发挥着重要作用。

Transformer

Transformer 是一种基于注意力机制的深度学习模型架构，最初由 Google 的研究人员提出，被广泛应用于自然语言处理领域，尤其是机器翻译任务。Transformer 模型的提出对传统的循环神经网络（RNN）和长短时记忆网络（LSTM）等模型进行了革命性的改进。

Transformer 模型的核心是自注意力机制（Self-Attention Mechanism），通过自注意力机制，模型能够同时考虑输入序列中不同位置的词语之间的关联性，从而捕捉长距离依赖关系。此外，Transformer 模型还包括位置编码（Positional Encoding）和多头注意力机制（Multi-Head Attention），使其能够更好地处理序列数据。

相比于传统的循环神经网络，Transformer 模型具有以下优势：

并行计算：Transformer 能够并行计算，加快训练速度；
长距离依赖：通过自注意力机制，Transformer 能够捕捉长距离依赖关系；
更好的表征学习：Transformer 能够学习到更加抽象和有效的特征表示。

Transformer 模型已经被广泛应用于自然语言处理任务，如机器翻译、文本生成、文本分类等，取得了显著的成就。其成功应用推动了深度学习领域的发展，并为处理序列数据提供了一种高效且强大的模型架构。

Transformer 和神经网络的关系

Transformer 是一种基于注意力机制的深度学习模型，而神经网络是深度学习的基础组件之一。具体来说，Transformer 可以被视为一种神经网络架构，它使用注意力机制来处理序列数据，如自然语言文本。

在传统的神经网络中，信息的传递是通过循环结构实现的，存在梯度消失和梯度爆炸问题。相比之下，Transformer 利用注意力机制实现了更为高效的信息传递和建模，能够并行处理序列数据，从而提高了训练速度和模型性能。

因此，Transformer 可以被看作是一种神经网络架构的演进和创新，它在机器翻译、文本生成、语音识别等领域取得了显著成就。通过引入自注意力机制和位置编码，Transformer 模型能够更好地捕捉序列数据中的长距离依赖关系和特征表示，成为深度学习领域的重要里程碑之一。

大语言模型（LLM）

LLM，全称 Large Language Model，大语言模型。

大型语言模型（LLM）是基于大量数据进行预训练的超大型深度学习模型，旨在理解和生成人类语言。它们在海量的文本数据上进行训练，通常具有至少几十亿参数，可以执行多样性的下游任务。。底层转换器是一组神经网络，这些神经网络由具有自注意力功能的编码器和解码器组成。编码器和解码器从一系列文本中提取含义，并理解其中的单词和短语之间的关系。

Transformer 能够进行无监督的训练，但更精确的解释使转换器可以执行自主学习。通过此过程，Transformer 可学会理解基本的语法、语言和知识。

与早期按顺序处理输入的循环神经网络（RNN）不同，Transformer 并行处理整个序列。这可让数据科学家使用 GPU 训练基于 Transformer 的 LLM，从而大幅度缩短训练时间。

借助 Transformer 神经网络架构，你可使用非常大规模的模型，其中通常具有数千亿个参数。这种大规模模型可以摄取通常来自互联网的大量数据，但也可以从包含 500 多亿个网页的 Common Crawl 和拥有约 5700 万个页面的 Wikipedia 等来源摄取数据。

大型语言模型有哪些应用？

文案写作：除了 GPT-3 和 ChatGPT 之外，Claude、Llama 2、Cohere Command 和 Jurassic 也可编写原件。AI21 Wordspice 建议修改原始语句以改善风格和语音。
知识库回答：该技术通常称为知识密集型自然语言处理（KI-NLP），是指可以根据数字存档中的信息帮助回答特定问题的 LLM。AI21 Studio playground 能够回答常识性问题就是此类示例。
文本分类：使用集群，LLM 可以对含义或情绪相似的文本进行分类。用途包括衡量客户情绪、确定文本之间的关系和文档搜索。
代码生成：LLM 擅长根据自然语言提示生成代码。示例包括 Amazon CodeWhisperer 和 GitHub Copilot 中使用的 Open AI Codex，它们可以用 Python、JavaScript、Ruby 和其他几种编程语言编码。其他编码应用包括创建 SQL 查询、编写 Shell 命令和进行网站设计。
文本生成：与代码生成类似，文本生成可以完成不完整的语句，编写产品文档，或者像 Alexa Create 一样创作简短的儿童故事。

GPT

GPT 全称 Generative Pre-trained Transformer，生成预训练转换器。

GPT 是由 OpenAI 开发的一系列基于 Transformer 架构的大型语言模型。GPT 模型采用了自回归的方式进行训练，能够生成文本、回答问题、完成翻译等自然语言处理任务。

开源 LLM

通义千问：通义千问-7B（Qwen-7B）是阿里云研发的通义千问大模型系列的70亿参数规模的模型。Qwen-7B是基于Transformer的大语言模型, 在超大规模的预训练数据上进行训练得到。预训练数据类型多样，覆盖广泛，包括大量网络文本、专业书籍、代码等。同时，在Qwen-7B的基础上，使用对齐机制打造了基于大语言模型的AI助手Qwen-7B-Chat。
智谱·AI：ChatGLM-6B 是一个开源的、支持中英双语问答的对话语言模型，基于 General Language Model (GLM) 架构，具有 62 亿参数

AIGC/Generative AI

AIGC，全称 Artificial Intelligence Generative Content，人工智能生成内容。
Generative AI，生成式 AI。

AIGC 又称生成式 AI (Generative AI)，是继专业生产内容（PGC， Professional-generated Content）、用户生产内容（UGC， User-generated Content）之后的新型内容创作方式，可以在对话、故事、图像、视频和音乐制作等方面，打造新的数字内容生成与交互形式。

与所有人工智能技术一样，AIGC 的能力由机器学习模型提供，这些模型是基于大量数据进行预先训练的大模型，通常被称为基础模型（Foundation Models）。如今以基础模型为驱动的 AIGC 应用迭代速度呈现指数级发展，从由 Stable Diffusion 文生图模型驱动的 AI 作画应用，再到以大语言模型（LLM）驱动的智能聊天机器人，深度学习模型不断完善、开源预训练基础模型的推动以及大模型探索商业化的可能，都在成为这场人工智能颠覆性革命的主要驱动力。

论文摘要

《Neural Machine Translation by Jointly Learning to Align and Translate》

《基于联合学习对齐和翻译的神经机器翻译》是一篇经典的机器翻译论文，由 Google Brain 团队的研究人员 Bahdanau（ [bɑːdɑˈnoʊ]）等人于 2014 年提出。该论文提出了一种新颖的神经机器翻译模型，引入了注意力机制，极大地改进了传统的基于统计机器翻译的方法。

该论文提出了一种称为 Seq2Seq 的神经网络架构，用于进行机器翻译任务。该架构包括编码器和解码器两部分，通过将源语言句子编码为固定长度的向量表示，然后将此向量解码为目标语言句子。与传统的固定长度短语表示不同，该模型能够根据输入序列中的不同部分动态地调整注意力，以便更好地对齐源语言和目标语言之间的单词。

通过引入注意力机制，该模型能够在生成目标语言句子的每个单词时动态地关注源语言句子的不同部分，从而更好地处理长距离依赖关系和词序问题。实验结果表明，这种基于注意力机制的神经机器翻译模型在翻译质量和效率上都取得了显著的提升，成为了后续神经机器翻译模型发展的重要里程碑。

这篇论文为后续的神经机器翻译研究奠定了基础，并启发了许多后续模型的发展，如 Transformer 等。

《Attention is All You Need》

《Attention is All You Need》是一篇由 Google Brain 团队提出的论文，介绍了 Transformer 模型，这是一种基于注意力机制的深度学习模型。

Transformer 模型摒弃了传统的循环神经网络（RNN）和长短期记忆网络（LSTM），完全基于自注意力机制来处理序列数据。该模型通过引入多头注意力机制和位置编码，实现了并行计算、更好的序列建模能力以及更快的训练速度。Transformer 模型在机器翻译等自然语言处理任务中取得了优异的性能，证明了注意力机制在序列建模中的有效性。

该论文的提出对深度学习领域产生了深远影响，激发了后续许多基于 Transformer 架构的模型的发展，如 BERT、GPT 等。Transformer 模型的成功证明了注意力机制在处理序列数据时的重要性，为自然语言处理领域带来了革命性的变革。

参考

算法学习计划

2024-03-13T14:56:33.000Z

第一阶段

基础知识学习

学习基本数据结构（数组、链表、栈、队列、树等）和基本算法（排序、查找、递归等）。
刷题巩固基础，解决大量简单和中等难度的算法问题。

算法思想学习

深入学习常用算法思想，如贪心算法、动态规划、回溯算法等。
练习相关算法题目，加深理解和掌握应用。

LeetCode刷题阶段

刷LeetCode题库，重点解决中等和困难难度的算法问题。
注重多种解题思路的探索，提升解决问题的能力和速度。

第二阶段

算法进阶与实战

学习高级数据结构（图、堆、并查集等）和高级算法（网络流、字符串匹配等）。
解决复杂算法问题，注重优化算法效率和空间复杂度。

项目实践与总结

将所学算法应用到实际项目中，解决实际问题。
总结学习经验，复习重要知识点，填补知识漏洞。

Puppeteer 学习笔记（示例）: 禁止加载图片资源

2024-03-07T09:29:02.000Z

拦截所有图片资源

在 Puppeteer 中，如果你想禁止加载图片，可以通过拦截请求并阻止图片资源类型的请求来实现。这可以通过使用 page.setRequestInterception(true) 来启用请求拦截，然后在 request 事件监听器中检查请求类型，如果是图片，则调用 request.abort() 方法。

以下是一个示例代码，展示了如何在 Puppeteer 中禁止加载图片：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  // 启用请求拦截
  await page.setRequestInterception(true);

  // 添加请求拦截器
  page.on('request', request => {
    // 如果请求的资源类型是图片，则阻止该请求
    if (request.resourceType() === 'image') {
      request.abort();
    } else {
      request.continue();
    }
  });

  // 导航到页面
  await page.goto('https://example.com');

  // 其他操作...

  await browser.close();
})();

在这段代码中，我们首先通过 setRequestInterception(true) 启用了请求拦截。然后，我们监听 request 事件，并检查每个请求的资源类型。如果资源类型是 image，我们就调用 request.abort() 来阻止这个请求。对于其他类型的请求，我们调用 request.continue() 来允许请求继续。

这种方法可以有效减少页面加载时间和带宽使用，特别是在你不需要处理图片数据时。

拦截指定域名的图片资源

在 Puppeteer 中，如果你想禁止加载来自特定域名的图片，你可以在启用请求拦截后，检查请求的 URL，并根据域名决定是否要阻止该请求。以下是一个示例代码，展示了如何根据域名禁止加载图片：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  // 启用请求拦截
  await page.setRequestInterception(true);

  // 添加请求拦截器
  page.on('request', request => {
    // 获取请求的 URL
    const url = request.url();
    // 解析 URL 以获取域名
    const hostname = new URL(url).hostname;

    // 检查请求是否为图片以及域名是否为特定域名
    if (request.resourceType() === 'image' && hostname === 'example.com') {
      // 阻止来自特定域名的图片请求
      request.abort();
    } else {
      // 允许其他请求
      request.continue();
    }
  });

  // 导航到页面
  await page.goto('https://example.com');

  // 其他操作...

  await browser.close();
})();

在这个例子中，我们首先通过 setRequestInterception(true) 启用了请求拦截。然后，我们监听 request 事件，对于每个请求，我们获取它的 URL 并解析出域名。如果请求的资源类型是 image 并且域名与我们指定的域名匹配，我们就调用 request.abort() 来阻止这个请求。对于其他类型的请求或来自其他域名的请求，我们调用 request.continue() 来允许请求继续。

请确保将 'example.com' 替换为你想要阻止图片加载的特定域名。这种方法可以帮助你减少不必要的网络流量，特别是当你只想屏蔽来自某些域名的图片时。

在 JavaScript 中实现一个延迟函数

2024-03-07T09:27:07.000Z

在 JavaScript 中实现一个延迟函数（通常称为 delay 或 sleep 函数）非常简单，你可以使用 Promise 和 setTimeout 函数来实现。以下是一个 delay 函数的示例：

function delay(time) {
  return new Promise(resolve => setTimeout(resolve, time));
}

// 使用方法
async function run() {
  console.log('Delay start');
  await delay(2000); // 延迟 2000 毫秒（2秒）
  console.log('Delay end');
}

run();

在这个例子中，delay 函数接收一个时间参数（以毫秒为单位），然后返回一个 Promise。这个 Promise 将在指定的时间后通过 setTimeout 函数解决。在 run 函数中，我们使用 await 关键字等待 delay 函数，这样代码的执行就会在这里暂停指定的时间。

你可以根据需要调用 delay 函数来在任何地方添加延迟。这在模拟网络请求、动画等场景中非常有用。

Puppeteer 学习笔记（示例）: 打开多个页面并依次切换tab

2024-03-07T09:25:16.000Z

在 Puppeteer 中，”tab”通常指的是浏览器窗口中的页面（Page）。如果你想同时打开多个页面（即多个tab），然后依次在它们之间切换，你可以按照以下步骤进行：

创建多个页面对象。
同时打开所有页面。
依次切换到每个页面并执行操作。

以下是一个示例代码，展示了如何同时打开多个页面，并在它们都加载完成后依次切换和操作：

const puppeteer = require('puppeteer');

(async () => {
  // 启动浏览器
  const browser = await puppeteer.launch({ headless: false }); // 设置为非无头模式以便看到浏览器标签切换

  // 定义要访问的 URL 列表
  const urls = ['https://example.com', 'https://example.org', 'https://example.net'];

  // 同时创建并打开所有页面
  const pages = await Promise.all(urls.map(async (url) => {
    const page = await browser.newPage();
    await page.goto(url);
    return page;
  }));

  // 依次切换到每个页面并执行操作
  for (const page of pages) {
    // 将焦点切换到当前页面
    await page.bringToFront();

    // 在这里可以执行页面操作，例如截图、提取页面内容等
    // 示例：打印当前页面的 URL
    console.log(await page.url());

    // 你可以在这里加入随机停留时间
    const randomDelay = Math.floor(Math.random() * (180000 - 60000 + 1)) + 60000;
    await page.waitForTimeout(randomDelay);

    // 执行完操作后，可以选择关闭当前页面或保持打开状态
    // await page.close();
  }

  // 如果你没有关闭每个页面，可以在这里关闭浏览器
  // await browser.close();
})();

在这个脚本中：

browser.newPage() 用于创建新页面。
page.goto(url) 用于导航到指定的 URL。
page.bringToFront() 用于将当前页面切换到前台，这样你就可以模拟用户在不同的标签页之间切换。

请注意，如果你不关闭每个页面，那么在脚本的最后你应该关闭浏览器，以释放资源。如果你关闭了每个页面，那么关闭浏览器的步骤可以省略，因为当最后一个页面关闭时，Puppeteer 通常会自动关闭浏览器。

此外，由于这个脚本是在非无头模式下运行的（headless: false），你可以看到浏览器窗口和标签页的切换。如果你不需要看到浏览器界面，可以将其设置为无头模式（headless: true），这通常会稍微提高性能。

Puppeteer 学习笔记（示例）: 打开页面并滑动到底部

2024-03-07T02:47:39.000Z

在 Puppeteer 中，要打开一个页面并滑动到底部，你可以使用页面提供的滚动功能。这通常通过执行页面上下文中的 JavaScript 代码来实现。以下是一个示例，展示了如何使用 Puppeteer 打开一个页面并滚动到底部：

const puppeteer = require('puppeteer');

(async () => {
  // 启动浏览器
  const browser = await puppeteer.launch();
  // 创建一个新页面
  const page = await browser.newPage();
  // 导航到指定的 URL
  await page.goto('https://example.com');

  // 滑动到页面底部的函数
  async function scrollToBottom() {
    await page.evaluate(async () => {
      await new Promise((resolve, reject) => {
        var totalHeight = 0;
        var distance = 100; // 每次向下滚动的距离
        var timer = setInterval(() => {
          var scrollHeight = document.body.scrollHeight;
          window.scrollBy(0, distance);
          totalHeight += distance;

          if (totalHeight >= scrollHeight) {
            clearInterval(timer);
            resolve();
          }
        }, 100);
      });
    });
  }

  // 调用滑动到页面底部的函数
  await scrollToBottom();

  // 在这里可以执行其他页面操作，例如截图、提取页面内容等

  // 关闭页面
  await page.close();
  // 关闭浏览器
  await browser.close();
})();

在这个脚本中，scrollToBottom 函数通过设置一个定时器来模拟用户滚动行为，每隔一段时间滚动一小段距离，直到达到页面底部。这种方法可以模拟真实用户的滚动行为，对于需要加载懒加载内容（如图片或者无限滚动的社交媒体帖子）的页面尤其有用。

请注意，滚动到底部的速度和每次滚动的距离可以根据页面的实际情况进行调整。如果页面有很多懒加载内容，可能需要减慢滚动速度或增加每次滚动的距离，以确保内容能够正确加载。

Puppeteer 学习笔记（示例）: 并行打开多个页面

2024-03-07T02:44:16.000Z

要使用 Puppeteer 并行打开多个页面，你可以使用 Promise.all() 来同时处理多个页面。这样，你可以在同一个浏览器实例中并行打开多个标签页。下面是一个示例代码，展示了如何实现这一点：

const puppeteer = require('puppeteer');

(async () => {
  // 启动浏览器
  const browser = await puppeteer.launch();

  // 定义要访问的 URL 列表
  const urls = ['https://example.com', 'https://example.org', 'https://example.net'];

  // 使用 map() 方法将每个 URL 映射到打开页面的 Promise
  const pagePromises = urls.map(async (url) => {
    // 创建一个新页面
    const page = await browser.newPage();

    // 导航到指定的 URL
    await page.goto(url);

    // 在这里可以执行其他页面操作，例如截图、提取页面内容等
    // 例如：await page.screenshot({ path: `screenshot-${url}.png` });

    // 关闭页面
    await page.close();
  });

  // 使用 Promise.all() 等待所有页面的 Promise 完成
  await Promise.all(pagePromises);

  // 所有页面处理完毕后关闭浏览器
  await browser.close();
})();

在这个脚本中，urls.map() 会为每个 URL 创建一个新的 Promise，这些 Promise 会开始执行页面的打开和操作过程。Promise.all() 会等待所有这些 Promise 完成，这意味着所有页面的操作都是并行执行的。

请注意，虽然这种方法可以提高效率，但是如果同时打开的页面太多，可能会消耗大量的系统资源，导致性能下降。因此，如果要处理大量页面，可能需要实现一种队列或者限制并发数量的机制。

Puppeteer 学习笔记（示例）: 逐个打开页面并滑动到底部

2024-03-07T02:35:27.000Z

在 Puppeteer 中，你可以使用 browser.newPage() 方法来打开多个页面（也称为标签页或 tabs）。以下是一个基本的示例，展示了如何使用 Puppeteer 打开多个页面并逐个访问不同的 URL：

const puppeteer = require('puppeteer');

(async () => {
  // 启动浏览器
  const browser = await puppeteer.launch();

  // 定义要访问的 URL 列表
  const urls = ['https://example.com', 'https://example.org', 'https://example.net'];

  // 遍历 URL 列表，为每个 URL 打开一个新页面
  for (const url of urls) {
    // 创建一个新页面
    const page = await browser.newPage();

    // 导航到指定的 URL
    await page.goto(url);

    // 在这里可以执行其他页面操作，例如截图、提取页面内容等
    // 例如：await page.screenshot({ path: `screenshot-${url}.png` });

    // 关闭页面
    await page.close();
  }

  // 所有页面访问完毕后关闭浏览器
  await browser.close();
})();

这个脚本首先启动了一个新的浏览器实例，然后遍历一个包含 URL 的数组，为每个 URL 创建一个新页面，并导航到相应的地址。在每个页面上，你可以执行所需的操作，比如截图、页面内容分析等。完成操作后，脚本会关闭当前页面，并在处理完所有页面后关闭浏览器实例。

请注意，这个脚本是按顺序打开和处理每个页面的。如果你想同时打开多个页面，你可以创建所有页面的 Promise，然后使用 Promise.all() 来等待所有页面操作完成。但是，这样做可能会对计算机的性能造成较大压力，尤其是当打开的页面数量较多时。

Puppeteer 学习笔记（一）: 入门

2024-03-07T02:19:57.000Z

Puppeteer 是什么？

Puppeteer 是一个 Node 库，它提供了一个高级 API 来通过 DevTools 协议控制 Chromium 或 Chrome。Puppeteer 默认以 headless 模式运行，但是可以通过修改配置文件运行“有头”模式。

Puppeteer 能做什么?

你可以在浏览器中手动执行的绝大多数操作都可以使用 Puppeteer 来完成！下面是一些示例：

生成页面 PDF。
抓取 SPA（单页应用）并生成预渲染内容（即“SSR”（服务器端渲染））。
自动提交表单，进行 UI 测试，键盘输入等。
创建一个时时更新的自动化测试环境。使用最新的 JavaScript 和浏览器功能直接在最新版本的Chrome中执行测试。
捕获网站的 timeline trace，用来帮助分析性能问题。
测试浏览器扩展。

如何安装 puppeteer？

1	npm install puppeteer

使用 puppeteer

Puppeteer 使用起来和其他测试框架类似。你需要创建一个 Browser 实例，打开页面，然后使用 Puppeteer 的 API。

Example - 跳转到 https://example.com 并保存截图至 example.png:

// example.js
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.otemeta.com');
  await page.screenshot({path: 'otemeta.png'});

  await browser.close();
})();

在命令行中执行：

1	node example.js

默认设置

使用有头模式

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: false });
  const page = await browser.newPage();
  await page.goto('https://www.otemeta.com');

  await browser.close();
})();

默认视口

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: false,
    defaultViewport: {
      width: 1280,
      height: 720
    }
  });
  const page = await browser.newPage();
  await page.goto('https://www.otemeta.com');

  await browser.close();
})();

在导航期间忽略 HTTPS 错误.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: false,
    ignoreHTTPSErrors: false,
    defaultViewport: {
      width: 1280,
      height: 720
    }
  });
  const page = await browser.newPage();
  await page.goto('https://www.otemeta.com');

  await browser.close();
})();

Browser 实例

常用方法

browser.newPage()：返回一个新的 Page 对象。Page 在一个默认的浏览器上下文中被创建。
browser.close()：关闭 Chromium 及其所有页面(如果页面被打开的话)。
browser.pages()：返回一个包含所有打开的页面的数组。

Page 实例

page.goto(url[, options])

导航到相应地址. 地址应该带有 http 协议, 比如 https://。options：

timeout：跳转等待时间，单位是毫秒, 默认是30秒, 传 0 表示无限等待。可以通过 page.setDefaultNavigationTimeout(timeout) 方法修改默认值
waitUntil：满足什么条件认为页面跳转完成，默认是 load 事件触发时。指定事件数组，那么所有事件触发后才认为是跳转完成。事件包括：
- load - 页面的load事件触发时
- domcontentloaded - 页面的 DOMContentLoaded 事件触发时
- networkidle0 - 不再有网络连接时触发（至少500毫秒后）
- networkidle2 - 只有2个网络连接时触发（至少500毫秒后）

常用方法

page.$(selector)：此方法在页面内执行 document.querySelector。如果没有元素匹配指定选择器，返回值是 null。
page.$$(selector)：此方法在页面内执行 document.querySelectorAll。如果没有元素匹配指定选择器，返回值是 []。
page.close([options])：关闭页面
page.evaluate(pageFunction[, ...args])：在页面实例上下文中执行方法
page.setCookie(...cookies)：设置 cookie
page.setViewport(viewport)：如果是一个浏览器多个页面的情况，每个页面都可以有单独的 viewport
page.waitFor()：设置页面停留时间
page.url()：返回当前页面的 URL

示例

创建一个 PDF。

文件为 hn.js

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.otemeta.com', { waitUntil: 'networkidle2' });
  await page.pdf({path: 'hn.pdf', format: 'A4'});

  await browser.close();
})();

在页面中执行脚本

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.otemeta.com');

  // Get the "viewport" of the page, as reported by the page.
  const dimensions = await page.evaluate(() => {
    return {
      width: document.documentElement.clientWidth,
      height: document.documentElement.clientHeight,
      deviceScaleFactor: window.devicePixelRatio
    };
  });

  console.log('Dimensions:', dimensions);

  await browser.close();
})();

puppeteer FAQ

puppeteer 和 puppeteer-core 的区别

当你安装 puppeteer 时，它会下载最新版本的 Chromium（~~170MB Mac，~~282MB Linux，~280MB Win），以保证可以使用 API。如果想要跳过下载，请阅读环境变量。

自 1.7.0 版本以来，我们都会发布一个 puppeteer-core 包，这个包默认不会下载 Chromium。

puppeteer-core 是一个的轻量级的 Puppeteer 版本，用于启动现有浏览器安装或连接到远程安装。

puppeteer.launch 和 puppeteer.connect 的区别

puppeteer 提供了两种方式来启动浏览器：puppeteer.launch 和 puppeteer.connect。

puppeteer.launch: 这个方法会启动一个全新的浏览器实例，每次调用 puppeteer.launch 都会启动一个新的浏览器进程。这种方式适合于需要独立的、干净的浏览器环境的场景，比如进行网页截图、自动化测试等。
puppeteer.connect: 这个方法允许连接到一个已经存在的浏览器实例。这种方式适合于需要在已有浏览器实例上进行操作的场景，比如远程调试、复用已有的浏览器环境等。

因此，puppeteer.launch 用于启动新的浏览器实例，而 puppeteer.connect 用于连接到已有的浏览器实例。根据具体的需求和场景，选择合适的方法来启动或连接浏览器。

networkidle2 和 networkidle0 的区别

在 Puppeteer 中，networkidle0 和 networkidle2 是两种网络空闲检测的事件，它们用于在 page.goto() 或 page.waitForNavigation() 等函数中作为选项，以便确定何时认为页面导航和加载已经完成。

这两个事件的区别在于它们对网络空闲状态的定义：

networkidle0：在至少 500 毫秒内没有任何网络连接时触发。这意味着页面在指定时间内没有任何网络请求，这通常表示页面加载已经完成，并且没有任何长轮询请求或其他持续的网络活动。
networkidle2：在至少 500 毫秒内网络连接数不超过 2 个时触发。这意味着页面可能仍然在进行一些轻量级的网络活动，但基本上是空闲的。这对于有一些小的、持续的网络请求（如 WebSockets 或长轮询请求）的页面来说是有用的。

选择哪一个取决于你的用例。如果你需要等待所有网络活动完全停止，使用 networkidle0 可能更合适。如果页面预期会有一些持续的网络活动，但你想在大部分资源加载完毕时继续操作，那么 networkidle2 可能是更好的选择。

请注意，从 Puppeteer v3.0.0 开始，networkidle0 和 networkidle2 事件已被弃用，取而代之的是 networkidle。如果你使用的是更新的 Puppeteer 版本，请查阅最新的文档以获取正确的使用方法。

深入理解 JavaScript 中的 IIFE

2024-02-08T06:33:23.000Z

在 JavaScript 中，IIFE（Immediately Invoked Function Expression）是一种重要且强大的编程模式。它能够帮助我们创建私有作用域，避免全局命名冲突，并提供了一种模块化的编程方式。本文将深入探讨 IIFE 的概念、用途和最佳实践。

IIFE 的定义和语法

IIFE 是一个立即调用的函数表达式，它由两部分组成：函数表达式和立即调用运算符。其基本语法如下：

1
2
3

(function(){
  // 代码块
})();

或

1
2
3

(function(){
  // 代码块
}());

或

1
2
3

!function(){
  // 代码块
}();

这样定义和调用的函数会立即执行，而不需要通过函数名来调用。

IIFE 的作用和用途

IIFE 的一个主要作用是创建一个私有作用域，避免全局变量的污染。通过将代码封装在 IIFE 内部，所有的变量和函数都将存在于 IIFE 的作用域内，不会与全局作用域发生冲突。这种模式特别适用于插件和库的开发，可以将插件的代码封装在 IIFE 中，只暴露需要的接口给外部使用。

IIFE 的参数传递和返回值

IIFE 可以接受参数，并返回一个值。通过传递参数，我们可以向 IIFE 内部传递外部的变量和值，进一步增强了其灵活性。同时，通过返回一个值，我们可以将内部的数据和功能暴露给外部使用。

IIFE 的最佳实践

在使用 IIFE 时，有几个最佳实践值得注意：

使用分号结尾：在 IIFE 的结尾加上分号，以避免与其他代码的连锁执行发生问题。
使用严格模式：在 IIFE 内部开启严格模式，以确保代码的安全性和可靠性。
适度使用 IIFE：不要滥用 IIFE，只在需要创建私有作用域或模块化代码时使用它。

总结

IIFE 是 JavaScript 中一种强大且常用的编程模式，它可以帮助我们避免全局命名冲突，创建私有作用域，并提供模块化的编程方式。通过合理地运用 IIFE，我们可以写出更加安全、可维护和可扩展的代码。

希望本文能够帮助你更好地了解和应用 IIFE，在 JavaScript 的开发中发挥更大的作用。

Mac(M2) 正确安装 picgo 姿势

2023-12-31T16:00:00.000Z

安装方式

1	brew install picgo --cask

问题1: 安装后打开 picgo 报错：xxx 已损坏，无法打开。您应该将它移到废纸篓

终端输入：

1	sudo xattr -r -d com.apple.quarantine 你的APP路径

APP 路径的获取方法：

打开 “访达”（Finder）进入 “应用程序” 目录，找到该软件图标，将图标拖到终端窗口，最终的命令类似

1	sudo xattr -r -d com.apple.quarantine '/Applications/PicGo.app'

问题2: 无法从剪贴板上传

现象：配置好 cos 之后，可以正常从本地推动到主窗口上传，但在剪贴板上的“等待上传” 则点击无效。

排查方式：打开 picgo 的日志文件，在主窗口 -> PicGo设置 -> 设置日志文件（点击设置） -> 日志文件（点击打开），如果其中的报错是如下格式，可以检查一下对应目录 picgo-clipboard-images 是否存在，不存在手动创建一个：

1	Error: ENOENT: no such file or directory, open '/Users/zizhu/Library/Application Support/picgo/picgo-clipboard-images/202306272131465.png.3840258425'

KO 会议是什么？

2023-11-10T15:00:00.000Z

KO 会议是什么？

Kick-off Meeting 有的翻译为项目启动会议，也有的翻译成开工或者开踢会议，这不重要，明确这个英文名字即可，不用管如何翻译。会议是 PM 激励其团队的最佳机会。在这次会议上，项目管理人员可以建立共同目标，并开始了解每个人。

KO 会议过程

1、项目背景

我们项目在哪里？说过去，做项目之前的“悲惨境地”，明确问题根源在哪里，明白为什么要做这个项目。

2、项目意义、目的与目标

我们项目去哪里？说将来，项目完成之后的美好前景，解决那些问题就算成功，达到什么样的效果就算完成，让听众知道终点在哪里。

3、需求和功能点概述

我们怎么做？说现状，说问题，具体用什么方法促使“过去”到“将来”的转变。讲解方法和任务概况，让听众为终极目标跃跃欲试。

4、项目组织架构

明确项目组成员工作范围和在项目中的职位，目的是让项目组成员互相认识，明确什么事情应该找谁。

KO时，最好是所有项目干系人都要到场，至少关键任务都要到场，比如：项目启动者或发起人，需求方，PMO人员。他们可以高屋建甄的给项目成员描绘项目的重要性和伟大前景，非常鼓舞士气。项目早起，务必多让项目启动者或发起人，需求方，PMO人员多多参与，反复确认方向正确，因为这时候，做各种调整的成本比较低。

注意不要遗漏工作不多的项目干系人，包括服务部门、配合部门的接口人等。这样会给后续项目实施、上线、运维带来很大的便利。

介绍成员的时候，最好能够让大家介绍一下自己，和大家站起来示意，自己做个简单自我介绍。

5、项目计划（WBS）

让所有人了解两个关键点：

第一、项目的时间点和里程碑；

第二、项目各个时段需要的资源，即每个人要在各个阶段做什么事情；

项目管理的计划、进度、资源、质量、风险，永恒不变的话题，只能自己体会。

6、沟通计划

沟通在项目管理中的重要地位不言而喻。太多的事情都是因为沟通不顺利，导致的产生一系列的问题。

做好沟通计划，强迫项目组成员定期沟通，降低问题发生的几率。

注意：定期与项目启动者或发起人，需求方，PMO人员回报和沟通，是促使项目顺利进行的必要因素。让他们了解项目进度，知道项目遇到的困难，更有助于申请资源。

Node.js 的 incompatible engine：该忽略，还是该修依赖？

2023-08-16T13:53:00.000Z

安装依赖时看到 incompatible engine，不代表项目一定跑不起来；它表示某个包声明了经过验证的 Node.js 版本范围，而当前运行时不在这个范围内。它可能只是历史包写得过窄，也可能是在提醒你 API、ABI 或构建链已不兼容。

一句话总结

把 engines 当作兼容性信号，不是无条件的安装开关。临时忽略可以 unblock 本地排查；要进入 CI 或生产，应该升级依赖、固定兼容 Node LTS，或用版本管理工具切换运行时。

先看它是 warning 还是失败

检查根目录和报错包的 package.json：

{
  "engines": {
    "node": ">=18 <23"
  }
}

如果项目锁定 Node 16，而你正在使用 Node 22，先在项目 README、.nvmrc、CI 配置里寻找约定版本。不要仅凭本机能安装成功，就把新运行时带进团队环境。

临时绕过的方法

Yarn Classic 可以单次忽略：

1	yarn install --ignore-engines

或写入本机配置：

1	yarn config set ignore-engines true

npm 的 engine-strict 为 false 时通常只警告；pnpm 则同样受 engine-strict 配置影响。团队项目不建议把忽略选项提交到仓库，因为它会掩盖其他开发机和 CI 的真实问题。

更稳妥的修复顺序

用 nvm, fnm 或 Volta 切到项目声明的 Node LTS，重新安装依赖。
确认上游包是否已有支持当前 Node 的版本；升级并重新生成 lockfile。
若是自有包，补齐准确的 engines 范围和 CI 矩阵。
只有为了验证业务逻辑、且测试全绿时，才临时忽略限制。

例如 .nvmrc 固定团队版本：

然后在 CI 中显式使用相同主版本，比让每个开发者各自猜测可靠得多。

不能忽略的信号

涉及 native addon、Node API、OpenSSL、ESM/CJS 加载方式或构建工具时，版本不匹配经常会在安装后才爆炸。此时 --ignore-engines 只会延后问题，不能解决问题。

我的判断框架

值得忽略：第三方包版本范围明显陈旧，且在目标 Node LTS 上通过构建与测试。

必须修复：CI、线上或含原生模块的项目出现 engine 冲突。运行时版本应是可复现的工程约束。

Antd form TextArea 隐藏右下角

2023-08-05T07:00:00.000Z

TextArea

import React from 'react';
import { Input } from 'antd';

const { TextArea } = Input;

const App: React.FC = () => (
  <>
    <TextArea
      rows={4} 
      placeholder="maxLength is 6"
      maxLength={6}
      style={{
        resize: 'none'
      }}
    />
  
);

export default App;

ProFormTextArea

ProFormTextArea 组件本质上是 Form.Item 和 Input.TextArea 的结合，我们可以把他们当成一个 FormItem 来使用，并且支持各种 props。每个表单项都支持 fieldProps 属性来支持设置输入组件的 props。我们支持了 placeholder 的透传，你可以直接在组件上设置 placeholder。

import React from 'react';
import { ProForm, ProFormTextArea } from '@ant-design/pro-components';

const App: React.FC = () => (
  <>
    <ProForm
      onValuesChange={(changeValues) => console.log(changeValues)}
    >
      <ProFormTextArea
        name="text"
        label="名称"
        placeholder="请输入名称"
        fieldProps={{
          style: {
            resize: 'none'
          }
        }}
      />
    ProForm>
  
);

export default App;

Antd Pro ModalFrom 使用记录

2023-08-04T07:00:00.000Z

ModalForm 是 ProForm 的一个变体，本质上仍然是个表单。所以无法通过 footer 来自定义页脚,如果要定义页脚需要使用 submitter.render 来进行自定义。这两个表单的表现与 ProForm 相同，可以从 ProForm 直接修改而来。本文由浅入深一步一步记录 ModalForm 使用过程。

最小使用

import { Button } from 'antd';
import { ModalForm } from '@ant-design/pro-components';
import { PlusOutlined } from '@ant-design/icons';

export default () => {
  return (
    <div>
      <ModalForm
        title="新建项目"
        trigger={
          <Button type="primary">
            <PlusOutlined />新建项目
          Button>
        }
      >
      ModalForm>
    div>
  )
}

title: 弹框的标题
trigger: 用于触发 Modal 打开的 dom，一般是 button

表单项

一个表单除了 Form 之外还是需要一系列的表单项，ProForm 自带了数量可观的表单项, 这些组件本质上是 Form.Item 和组件的结合，我们可以把他们当成一个 FormItem 来使用，并且支持各种 props。每个表单项都支持 fieldProps 属性来支持设置输入组件的props。我们支持了 placeholder 的透传，你可以直接在组件上设置 placeholder。

import { Button } from 'antd';
import { ModalForm, ProForm } from '@ant-design/pro-components';
import { PlusOutlined } from '@ant-design/icons';

export default () => {
  return (
    <div>
      <ModalForm
        title="新建项目"
        trigger={
          <Button type="primary">
            <PlusOutlined />新建项目
          Button>
        }
        onFinish={async (values) => {
          console.log(values.name);
          message.success('提交成功');
          return true;
        }}
      >
        <ProFormText
          width="xl"
          name="name"
          label="项目名称"
          tooltip="最长为 24 位"
          placeholder="请输入名称"
          fieldProps={{
            maxLength: 50,
            showCount: true
          }}
        />
      ModalForm>
    div>
  )
}

onFinish: 提交数据时触发，如果返回一个 true。会关掉抽屉,如果配置了 destroyOnClose 还会重置表单。
ProFormText: ProFormText 是 FormItem + Input 的产物，用于输入各类文本

注意：onFinish 是提交表单且数据验证成功后回调事件，同 antd 4 Form 组件 API

表单校验

import { Button } from 'antd';
import { ModalForm, ProForm } from '@ant-design/pro-components';
import { PlusOutlined } from '@ant-design/icons';

export default () => {
  return (
    <div>
      <ModalForm
        title="新建项目"
        trigger={
          <Button type="primary">
            <PlusOutlined />新建项目
          Button>
        }
        onFinish={async (values) => {
          console.log(values.name);
          message.success('提交成功');
          return true;
        }}
      >
        <ProFormText
          width="xl"
          name="name"
          label="项目名称"
          tooltip="最长为 24 位"
          placeholder="请输入名称",
          rules={[
            {
              required: true,
              message: "请输入项目名称"
            }
          ]}
        />
      ModalForm>
    div>
  )
}

我们只需要关心业务规则，表单校验通过之后 onFinish 才会被调用。

默认值

优先级：request(ProForm) > initialValues(ProForm) > request(ProFormItem) > initialValue(ProFormItem)

import { Button } from 'antd';
import { ModalForm, ProForm } from '@ant-design/pro-components';
import { PlusOutlined } from '@ant-design/icons';

export default () => {
  return (
    <div>
      <ModalForm
        title="新建项目"
        trigger={
          <Button type="primary">
            <PlusOutlined />新建项目
          Button>
        }
        request={async () => ({
          name: "紫升的项目1"
        }}}
        initialValues={{
          name: "紫升的项目2"
        }}
        onFinish={async (values) => {
          console.log(values.name);
          message.success('提交成功');
          return true;
        }}
      >
        <ProFormText
          width="xl"
          name="name"
          label="项目名称"
          tooltip="最长为 24 位"
          placeholder="请输入名称",
          request={async () => "紫升的项目3"}
          initialValue={"紫升的项目4"}
          rules={[
            {
              required: true,
              message: "请输入项目名称"
            }
          ]}
        />
      ModalForm>
    div>
  )
}

modalProps

Modal 的 props，使用方式与 antd 相同。注意：不支持 ‘visible’，请使用全局的 visible，比如关闭时重置表单的 destroyOnClose 就在这里配置。

import { Button } from 'antd';
import { ModalForm, ProForm } from '@ant-design/pro-components';
import { PlusOutlined } from '@ant-design/icons';

export default () => {
  return (
    <div>
      <ModalForm
        title="新建项目"
        trigger={
          <Button type="primary">
            <PlusOutlined />新建项目
          Button>
        }
        modalProps={{
          destroyOnClose: true
        }}
      >
        <ProFormText
          width="xl"
          name="name"
          label="项目名称"
          tooltip="最长为 24 位"
          placeholder="请输入名称"
        />
      ModalForm>
    div>
  )
}

destroyOnClose: 默认 ModalFrom 关闭后，表单不会重置，需要单独配置。

其他属性

autoFocusFirstInput: 自动聚焦第一个输入框
submitTimeout: 提交数据时，禁用取消按钮的超时时间（毫秒）。

实现 sequelize 分页和条件查询

2023-08-02T04:30:00.000Z

findAndCountAll 方法

findAndCountAll 会在查出列表记录的同时, 还会返回符合你查询列表数据的条数。

分页

async queryProjectList(params: { currentPage: number, pageSize: number }) {
  const { currentPage, pageSize } = params;
  const result = await UserModel.findAndCountAll({
    limit: params.pageSize, // 确保是 number 类型
    offset: (currentPage - 1) * pageSize, // 计算偏移量算法
  });
  return {
    data: result.rows,
    total: result.count
  };
}

条件查询

async queryProjectList(params: { pid: string, type: ProjectType }) {
  const { pid, type } = params;
  const condition: any = {
    deletedAt: null, // deletedAt 为 null 表示未删除，需要配合 paranoid 模型配置
  }
  // 模糊查询
  if (pid) {
    condition.pid = { [Op.like]: `%${pid}%` }
  }
  // 精确查询
  if(type) {
    condition.type = { [Op.eq]: type }
  }
  // ...
}

distinct

如果使用了 include 参数，需要额外传入 distinct: true 配置来去除 include 的数量。

const result = await Model.findAndCountAll({
  limit: params.pageSize, // 确保是 number 类型
  offset: (currentPage - 1) * pageSize, // 计算偏移量算法
  include: [
    { model: HobbyModel},
    { model: FriendModel},
  ],
  distinct: true,
});

result.count for findAndCountAll is incorrect with include

参考

sequelize模糊查询及分页

Typescript 项目使用 Jest 入门

2023-07-28T12:00:00.000Z

安装 jest

1	$ yarn add jest -D

然后，将下列配置内容添加到您的 package.json：

{
  "scripts": {
    "test": "jest"
  }
}

安装 ts-jest

ts-jest 是一个支持 sourcemap 的 TypeScript 预处理器，让你使用 TypeScript 编写 Jest 测试项目

1	$ yarn add --dev ts-jest

创建配置文件

执行 jest --init 回答几个简单的问题之后会生成一个 jest.config.ts 文件，然后在这个文件中添加 preset: 'ts-jest' 配置。

安装 ts-node

如果配置文件是 jest.config.ts，那就需要安装 ts-node 支持它：

1	$ yarn add ts-node -D

安装 @types/jest

如果使用 typescript 写测试用例，那就需要安装 @types/jest：

1	$ yarn add @types/jest -D

踩坑

Error: Jest: ‘ts-node’ is required for the TypeScript configuration files. Make sure it is installed

在全局执行 jest，会报错，意思是解析 typescript 配置文件需要安装 ts-node，

1 2	# 全局 $ npm install ts-node -g

「已解决」Failed to connect to github.com port 443

2023-07-17T19:20:35.047Z

执行 git push 或 git clone 时出现 Failed to connect to github.com port 443，表示连接还没到 GitHub 的认证阶段，就在 HTTPS 建连前失败了。过去常见的“写死 hosts IP”现在并不可靠：GitHub 的 CDN、证书校验和 IP 都可能变化，错误映射还会制造更难排的 TLS 问题。

一句话总结

按“DNS 解析 → 本机代理 → 网络出口 → Git 配置”的顺序排查。hosts 只应作为明确、临时且可回滚的诊断手段，不是长期方案。

先确认浏览器和 Git 是否同样失败

在终端执行：

1 2	curl -I https://github.com git ls-remote https://github.com/git/git.git HEAD

如果浏览器能打开而 Git 失败，重点检查 Git 的代理配置；如果两者都失败，则更可能是 DNS、代理客户端或网络出口的问题。

检查 Git 是否保留了旧代理

1 2	git config --global --get http.proxy git config --global --get https.proxy

代理客户端退出、端口变化后，Git 仍会尝试连接旧地址。确认不需要代理时，清掉旧配置：

1 2	git config --global --unset http.proxy git config --global --unset https.proxy

如果需要使用本地代理，确保地址、协议和端口与客户端实际监听一致；同时检查 shell 环境变量中的 HTTP_PROXY、HTTPS_PROXY。

检查 DNS 和网络出口

1 2	nslookup github.com curl -v https://github.com

nslookup 异常说明先处理 DNS；DNS 正常但 curl -v 卡在连接阶段，则检查代理模式、防火墙或公司网络策略。公司网络下应优先使用合规的网络出口或咨询网络管理员，不要把公共 IP 固化进 hosts。

一个更稳定的替代：SSH

HTTPS 网络策略不稳定、且账户已配置 SSH key 时，可以将远程地址切到 SSH：

1 2	git remote set-url origin git@github.com:OWNER/REPO.git ssh -T git@github.com

这不会绕过网络限制，但能避免 HTTPS 凭据与代理配置的额外变量。修改前可先执行 git remote -v 记录当前地址。

我的判断框架

优先修复：代理配置、DNS 和受控网络出口，它们才是可维护的根因。

避免采用：从第三方网站抄 IP 后长期写 hosts。它可能短暂恢复访问，却会在下一次基础设施变更时再次失效。

2023 hosts 切换工具推荐

2023-07-17T18:47:19.466Z

SwitchHosts

SwitchHosts是一款免费的跨平台hosts管理工具，可以帮助用户轻松快捷地管理多组hosts，方便地切换各种网络环境。它支持自定义规则、正则表达式以及备份和恢复等功能，是一款非常实用的网络工具。

你可以下载源代码并自行构建，或从以下链接下载已构建的版本：

SwitchHosts 下载页面（GitHub Release）

您还可以使用软件包管理器 Chocolatey 安装已构建的版本：

1	choco install switchhosts

iHosts

iHosts 是一款 Mac OS X 上的 /etc/hosts 编辑器，可以通过使用组来管理 hosts，实现部分更新而不是替换整个 hosts 文件。用户可以在编辑 hosts 时使用“实时查看 hosts”的功能，也可以添加或删除 hosts 或 hosts 组。此应用程序以沙盒模式运行，并在编辑 hosts 时更新 /etc/hosts 文件。

> > > 点击免费从 Mac App Store 下载 iHosts <<<

LightProxy

LightProxy 是阿里巴巴吧开源的一个跨平台的Web调试代理工具，具有证书安装和系统代理设置的完全自动化功能。它基于 Whistle，提供了强大的 hosts/proxy/capture 功能，并支持自定义 Node.js 代理规则。

静态博客管理器 qexo 搭建指南

2023-07-16T11:06:44.000Z

部署

你可以通过 Vercel 提供的免费数据库。但请注意这是个 Beta 功能

一键部署

首次部署会报错, 请无视并进行接下来的步骤

申请 Vercel 数据库

进入 Vercel Storage 界面然后点击右上角的 Create Database 并选择 Postgres 创建免费 PostgreSQL 数据库, 在 Connect 页面获取数据库连接信息。请注意在地区选择的位置选择与你上一步项目对应的地区（通常为 Washington, D.C., USA (East) - iad1）。

绑定项目

在左侧边栏选择 Projects 点击 Connect Project 连接到你第一步创建的项目

部署

回到你的项目页面，在 Deployments 点击 Redeploy 开始部署, 若没有 Error 信息即可打开域名进入初始化引导

初始化

部署成功后，打开域名进入初始化引导：

博客配置

服务商：github/gitlab/本地
使用配置：Hexo/Hugo/Valaxy/Vuepress/Vitepress
Github 密钥：于 Github 设置生成的 Token (建议使用 Classical) 需要 Repo & Workflow 下的权限不建议给出所有权限
Github 仓库
项目分支
博客路径

Vercel 配置

Vercel 密钥：您的 Vercel 账户密钥在此处生成
项目ID：您 Qexo 部署所在项目的 ID 位于 Project Settings -> General -> Project ID

图床设置

点击后台右上角设置按钮，进入设置页

滑动到图床设置部分：

图床类型: 远程 API
API 地址: https://sm.ms/api/v2/upload
POST 参数名: smfile
JSON 路径: data.url
自定义请求头: {"Authorization": "sm.ms 密钥"}

sm.ms 密钥在 https://smms.app/home/apitoken 生成

Mac 切换 github 账号

2023-07-06T21:39:05.142Z

github 提交的账户信息包括两部分：git commit 时日志中记录的用户名和邮箱信息、git push提交到远程时的账号密码验证信息。必须两者同时切换才能实现完美的切换账号的目的

删除钥匙串

打开”钥匙串访问“。在右上方搜索 git，找到所有 github 相关的账号信息。按删除键，删除所有名称为 github.com 的条目。放心，这个不会影响 Chrome 浏览器保存的用户名和密码。

执行命令

1 2	cp ~/.gitconfig ~/.gitconfig_a cp ~/.gitconfig ~/.gitconfig_b

在 gitconfig\_a 和 gitconfig\_b 两个文件中分别填写提交日志的用户信息。

切换账号

需要用 user\_a 的时候：

1	cp ~/.gitconfig_a ~/.gitconfig

然后执行 git push 输入 a 的登录信息即可以提交。

zsh 设置alias

在 ~/.zshrc 添加别名

1
2
3

alias cg="cat ~/.gitconfig"
alias cga="cp ~/.gitconfig_a ~/.gitconfig"
alias cgb="cp ~/.gitconfig_b ~/.gitconfig"

然后保存后执行 source ~/.zshrc 使之生效。

以后每次想切换时即可先用 cg 命令查询当前账户，根据情况执行 cga 或 cgb 切换账户。

React 发布 10 周年

2023-06-02T08:48:23.000Z

React 是一种流行的 JavaScript 库，用于构建用户界面。自 React 在 2013 年首次发布以来，它已经成为了前端开发中不可或缺的一部分。在本文中，我们将按年回顾 React 的发展历史。

童年

React 最初是由 Facebook 的软件工程师 Jordan Walke 开发的。他在2010年为Facebook的广告平台开发了一种新的模型，这个模型可以根据用户的操作来动态地更新广告。这个模型后来演变成了React框架，并于2013年首次发布。

幼儿园

2013 年

React 首次发布。它由 Facebook 的工程师们开发，旨在提高应用程序的性能和可维护性。React 的主要特点是虚拟 DOM，这是一种在内存中表示 DOM 的方式。通过使用虚拟 DOM，React 可以减少 DOM 操作的次数，从而提高应用程序的性能。

2014 年

React 发布了 0.12 版本。这个版本引入了 Mixins，这是一种在组件之间共享代码的方式。Mixins 很快成为了 React 中一个受欢迎的特性，但是在 2016 年被废弃了。

2015 年

React 发布了 0.14 版本。这个版本引入了 stateless 函数组件，这是一种更简单的组件形式，它没有状态或生命周期方法。stateless 函数组件很快成为了 React 中一个流行的特性，因为它们更易于测试和理解。

小学

2016 年

React 发布了 15.0 版本。这个版本引入了 PropTypes，这是一种用于验证组件属性的机制。PropTypes 很快成为了 React 中一个受欢迎的特性，因为它可以帮助开发人员捕获错误并提高代码质量。

2017 年

React 发布了 16.0 版本。这个版本引入了 Fiber，这是一个重新设计的渲染引擎，旨在提高 React 的性能和可维护性。Fiber 的主要特点是可以中断和恢复渲染过程，从而使 React 更加灵活和响应。

2018 年

React 发布了 16.3 版本。这个版本引入了 Context API，这是一种用于在组件之间共享数据的机制。Context API 可以帮助开发人员避免使用 prop drilling，并使代码更加简洁和可维护。

2019 年

React 发布了 16.8 版本。这个版本引入了 Hooks，这是一种用于在函数组件中使用状态和其他 React 功能的机制。Hooks 可以帮助开发人员编写更简洁、更易于理解和测试的代码。

2020 年

React 发布了 17.0 版本。这个版本没有引入太多新功能，而是主要关注向后兼容性和稳定性。React 17.0 的主要目标是使迁移更加容易，并为未来的版本打下基础。

总的来说，React 在过去的几年中经历了很多变化和进步。从虚拟 DOM 到 Hooks，每个版本都引入了新的功能和改进，并使 React 变得更加强大、灵活和易于使用。作为前端开发人员，我们可以期待着未来更多令人兴奋的变化和进步。

2021 年

React 18: 它引入了许多新功能，例如自动批量更新、新的上下文API和React响应模式等。
React Server Components: React Server Components是一个实验性的功能，它允许React组件在服务器上渲染，从而提高性能和可靠性。

中学

2022 年

2022 年的 React 更新包括发布了 React 18 正式版，其中包含了新的客户端渲染 API 和更新的服务端渲染 API，完全支持了服务端的 Suspense 和流式 SSR。

2023 年

React 进阶版文档的发布，其中介绍了组件状态的保留和重置机制，以及不同位置渲染组件时状态的处理方式。
React 团队推出了一种新型组件——Server Components，它们可以提前运行，并且不包含在你的 JavaScript bundle 中。这些组件可以在构建过程中运行，让你从文件系统中读取或获取静态内容，也可以在服务器上运行，让你无需构建 API 即可访问数据层。

RPM 广告是什么?

2023-05-11T06:12:57.000Z

RPM（Revenue per mille）广告是指每千次广告展示可以获得的收入。它是根据广告的展示次数、点击率和广告主出价等因素计算出来的。

在数字化时代，互联网广告已经成为了企业营销的重要手段。而对于广告主来说，他们最关心的就是广告的效果，即广告投放所带来的收益。而每千次展示收入（RPM）就是一个衡量广告效果的指标。

RPM是指广告主在每千次展示中所获得的收入。它是通过将广告收入除以展示次数，再乘以 1000 得出的。这个指标可以帮助广告主更好地了解他们的广告效果，并作出相应的调整。

RPM是一个非常重要的指标，因为它可以帮助广告主了解他们的广告投放是否能够带来足够的收益。如果RPM较低，可能意味着广告主需要重新考虑他们的广告策略，或者优化他们的广告内容，以提高点击率和转化率。

另外，RPM还可以帮助广告主评估不同媒体之间的效果差异。通过比较不同媒体的RPM，广告主可以更好地了解哪些媒体对他们的广告投放最有效，并将更多的预算投入到这些媒体上。

但是，需要注意的是，RPM并不是衡量广告效果的唯一指标。其他指标，如点击率、转化率、ROI等也同样重要。因此，在评估广告效果时，需要综合考虑多个指标，并结合实际情况进行分析。

总之，每千次展示收入（RPM）是一个非常重要的指标，可以帮助广告主更好地了解他们的广告效果，并作出相应的调整。但是需要注意的是，它并不是衡量广告效果的唯一指标，需要综合考虑多个指标，并结合实际情况进行分析。

vscode 选择多行，将光标定位至每行行首或行尾

2023-05-10T03:06:14.000Z

这是一种非常方便的操作方法，特别是在需要批量添加字符的时候。以下是这个方法的详细步骤：

首先，在 Mac 上打开文本编辑器或其他编程工具。
选中你想要添加字符的多行文本。
按住 shift 和 option 键，并用鼠标点击其中一行的行首或行尾。
这样就可以在所有选中的行的行首或行尾添加同样的字符了。

shift 和 option 键需要同时按住，且在点击行首或行尾之前不要释放它们。

如何设置 Gatsby 绝对路径引用别名

2023-05-08T10:33:33.000Z

在这篇文章中，我们将逐步了解如何向我们的 gatsby 站点添加导入别名。

我们设置导入别名的原因更多是为了代码的可读性和导入组件时代码外观的美观。

我的意思是，如果我们看一下以下示例：

1	import Subscribe from '../../../../../../../core/modules/newsletter/mixins/Subscribe'

在我看来，这样看起来非常丑陋，那么我们该如何改进呢？

我们可以通过更新 webpack 配置来包含针对我们已知将成为组件基础的主目录的别名来实现这一点。

一旦我们完成了这篇文章中的所有步骤，最终结果将如下所示：

1	import Subscribe from '@/core/modules/newsletter/mixins/Subscribe'

给 Gatsby 添加依赖

考虑到 Gatsby 使用 Webpack 作为其核心，并且默认情况下不会公开配置，因此我们可以使用 Gatsby 的 onCreateWebpackConfig API 添加自定义 Webpack 配置，这将导致自定义配置被合并，使您能够修改默认的 webpack 配置。

要添加自定义Webpack配置，我们需要编辑（或在项目根目录中创建文件，如果不存在）gatsby-node.js，并将新的配置添加到其中。

const path = require("path");
exports.onCreateWebpackConfig = ({ actions }) => {
  actions.setWebpackConfig({
    resolve: {
      alias: {
        "@/components": path.resolve(__dirname, "src/components"),
        "@/static": path.resolve(__dirname, "static")
      }
    }
  });
}

正如我们在上面的代码片段中看到的那样，actions 对象提供了使用 setWebpackConfig 选项的选项，该选项接受我们的自定义 webpack 配置并将其合并到 Gatsby 的 webpack 配置中。

为了添加新的别名，我们将使用 webpack 的 resolve.alias，这将允许我们在组件内部使用新创建的导入别名。

如下所示，在添加新别名后的最终结果将如下所示：

1	import Layout from '@components/Layout';

解析 ESlint import

{
  settings: {
    'import/parsers': {
      '@typescript-eslint/parser': ['.ts'],
    },
    'import/resolver': {
      // use /tsconfig.json
      typescript: {
        alwaysTryTypes: true, // always try to resolve types under `@types` directory even it doesn't contain any source code, like `@types/unist`
      },
    },
  },
}

Typescript

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/components/*": ["src/components/*"]
    },
  }
}

如何设置 React Typescript 项目绝对路径引用别名

2023-05-08T10:18:10.000Z

本文讲解了如何设置 React Typescript 项目绝对路径引用别名

craco

1、安装修改 CRA 配置的包：

1	$ yarn add @craco/craco

2、在项目根目录中创建 craco 的配置文件：craco.config.js，并在配置文件中配置路径别名

const path = require('path')
module.exports = {
  webpack: {
    alias: {
      // 约定：使用 @ 表示 src 文件所在路径
      '@': path.resolve(__dirname, 'src'),
      // 约定：使用 @scss 表示 样式 文件所在路径
      '@scss': path.resolve(__dirname, 'src', 'assets', 'styles')
    },
  },
}

3、修改 package.json 中的脚本命令

{
  // 将 start/build/test 三个命令修改为 craco 方式
  "scripts": {
    "start": "craco start",
    "build": "craco build",
    "test": "craco test",
    "eject": "react-scripts eject"
  }
}

Typescript

1、创建 path.tsconfig.json 配置文件

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

2、在 tsconfig.json 中导入该配置文件，让配置生效

{
  // 导入配置文件
  "extends": "./path.tsconfig.json",
}

配置完这一步，vscode 也会有目录提示了

Eslint

配置 @typescript-eslint/parser 并在 parserOptions 中指定 project 选项，以便在 Eslint 中使用 TypeScript 的类型检查。

module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: ['./tsconfig.json'], // Specify it only for TypeScript files
  },
}

如何在 React Native 中声明全局类型

2023-05-08T10:10:31.000Z

要在 TypeScript 中声明全局类型：

创建一个 global.d.ts 文件并在全局命名空间中声明类型。
添加需要全局访问的类型或接口。
使用 export {} 使文件成为模块。

在项目的 src 目录中，创建一个包含以下 global.d.ts 文件的 types 目录。

export {};

declare global {
  /**
   * 现在声明进入全局命名空间的类型，或者增加全局命名空间中的现有声明。
   */
  interface Employee {
    id: number;
    name: string;
    salary: number;
  }

  type Person = {
    name: string;
    age: number;
  };
}

上面的例子展示了如何创建一个修改全局命名空间的模块。我们创建了一个全局可访问的 Employee 和 Person 类型。

现在我可以访问我项目中的类型，而无需导入它们。

const emp: Employee = {
  id: 1,
  name: 'James',
  salary: 100,
};

console.log(emp);

const person: Person = {
  name: 'Tom',
  age: 30,
};

console.log(person);

如果我们在 IDE 中遇到错误，请尝试将类型目录的路径添加到 tsconfig.json 文件中。

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types"]
  }
}

我们在 global.d.ts 文件中使用 export {} 行将其标记为外部模块。模块是包含至少 1 个导入或导出语句的文件。我们必须这样做才能扩大全局范围。

Antd date.clone is not a function

2023-05-08T07:36:04.000Z

本文介绍了 Antd 组件报 date.clone is not a function 错误的解决方法

当我们给 Antd DatePicker 组件设置默认值或通过 form.setFieldsValue 设置值时，可能会遇到如下错误：

1	date.clone is not a function

这是因为 Antd DatePicker 组件的默认值必须是 moment 对象，而我们设置的值可能是字符串或者 Date 对象，所以需要将其转换为 moment 对象：

date.clone is not a function">

如何填写 Google Adsense 税务信息可以免税 | W-8BEN

2023-05-06T11:47:53.000Z

本文讲解了如何填写 Google Adsense 税务信息可以免税，以及如何填写 W-8 BEN 表格。

开始填表

以此点击 收款 -> 收款信息 -> 美国税务信息 -> 开始填表

基本信息

您使用的是哪种类型的账号？：个人
您是否是美国公民或居民？：否
请选择 W-8BEN：选择

W-8BEN 表单

按照下列图中的信息填写即可，需要注意的有：

个人姓名填写拼音大写，比如 LI MEI
外国的纳税人税号填写身份证号
报税选择无纸化

被接受通知

如下图，显示“您的税务信息已被接受”，说明设置成功了。

2023 Google Adsense 中国大陆账户注册教程

2023-04-27T04:36:47.000Z

Google Adsense 是一个由 Google 公司设置的广告计划，会员可以利用 Youtube 流量和 Blogspot 功能置入广告服务，以赚取佣金。会员可分得搜索广告收益的 51%、内容广告收益的 68%。本文将介绍如何注册 Google Adsense 账户。

前提

一个可以访问 Google 的代理，你可以在科学上网工具中选择一款
一个 Google 账号，可以参考 2023 大陆人如何成功创建 Google 账户进行注册。

扬帆启航

当你决定做一件事，就已经成功了一半，现在就让我们从点击 Google AdSense 注册开始内容变现之路吧。

您的网站：如果没有可以先不填写
让 AdSense 发挥更大作用：可选可不选
您的收款地址所在的国家/地区：中国大陆可以设置免税，就选中国大陆
我们的条款及条件：勾选

点击确认之后，就会进入到控制台：

填写客户信息

注意：这里的信息涉及以后得收款，一定要要仔细看下面的步骤，否则可能影响收款。

点击上一步的“请输入信息”卡片，进入到填写客户信息页面：

账号类型：个人
姓名和地址：这里就填写真实的就可以，要注意的是一点要 在地址第 1 行或者地址第 2 行中备注上电话，因为账号收入达到 5 美金之后 Google 就会给你寄一个用于验证身份的 PIN 码，由于是通过国际平信的方式发出，所以不会有电话，而你备注在地址里，邮递员就可以看到了。

点击确认之后返回首页看到成功的提示就可以了。

总结

内容变现是一个需要漫长积累的事情，你可能会在这个过程中遇到很多困难，但是只要你坚持下去，就一定会成功的。

微信 oAuth 网页授权流程

2023-04-27T03:02:56.000Z

如果用户在微信客户端中访问第三方网页，公众号可以通过微信网页授权机制，来获取用户基本信息，进而实现业务逻辑。

网页授权回调域名

1、在微信公众号请求用户网页授权之前，开发者需要先到公众平台官网中的 开发 → 接口权限 → 网页服务 → 网页授权 - 网页授权获取用户基本信息 的配置选项中，修改授权回调域名。请注意，这里填写的是域名（是一个字符串），而不是 URL，因此请勿加 http:// 等协议头。

注意：通过 设置 → 公众号设置 → 功能设置 → 网页授权域名

2、授权回调域名配置规范为全域名，比如需要网页授权的域名为：www.qq.com，配置以后此域名下面的页面 http://www.qq.com/music.html、http://www.qq.com/login.html 都可以进行 OAuth2.0 鉴权。但 http://pay.qq.com、http://music.qq.com、http://qq.com 无法进行 OAuth2.0 鉴权

3、如果公众号登录授权给了第三方开发者来进行管理，则不必做任何设置，由第三方代替公众号实现网页授权即可

业务域名

设置业务域名后，在微信内访问该域名下页面时，不会被重新排版。用户在该域名上进行输入时，不出现下图所示的安全提示。
注意事项：

1、可填写三个域名或路径（例：wx.qq.com 或 wx.qq.com/mp），需使用字母、数字及 - 的组合，不支持 IP 地址、端口号及短链域名。

2、填写的域名须通过ICP备案的验证。

3、将文件 MP_verify_naGVGuiJ6KOsOwCA.txt（点击下载）上传至填写域名或路径指向的 web 服务器（或虚拟主机）的目录（若填写域名，将文件放置在域名根目录下，例如 wx.qq.com/MP_verify_naGVGuiJ6KOsOwCA.txt；若填写路径，将文件放置在路径目录下，例如 wx.qq.com/mp/MP_verify_naGVGuiJ6KOsOwCA.txt），并确保可以访问。

4、一个自然月内最多可修改并保存三次，本月剩余保存次数：3

React Native 引入第三方 Android SDK

2023-04-21T10:40:00.000Z

在 React Native 开发中，如果一个原生 SDK 没有适配 React Native 的插件，原则上我们不推荐你使用。但是万不得已的情况下，我们有办法吗？答案是肯定的。步骤大致分为集成 SDK、编写桥接代码。知难行易，本文就是顺着这个思路来解决让前端工程师脑壳疼的集成第三方 SDK 并编写桥接代码的问题。

预备知识

在我们开发安卓项目的时候，不会所有的功能都自己去造轮子，经常要使用到各种的其他包，其中有谷歌给我们提供的各种 support 包，也有各种第三方的功能库，有时候我们自己也会将一些功能封装成包。这些包存在和导入的形式也多种多样，有远程仓库的，有直接拷贝到本地的，jar 包、aar 包、so 包等。所幸我们都可以在主工程和各个 Module 的 build.gradle 里进行统一管理。— Android 依赖导入全攻略

依赖引入方式

Android Gradle plugin 3.0 几个引入依赖的方法：

implementation

对于使用了该命令编译的依赖，对该项目有依赖的项目将无法访问到使用该命令编译的依赖中的任何程序，也就是将该依赖隐藏在内部，而不对外部公开。react-native link 命令即使用该方式

使用 implementation 会使编译速度有所增快：比如我在一个 library 中使用 implementation 依赖了 gson 库，然后我的主项目依赖了 library，那么，我的主项目就无法访问 gson 库中的方法。这样的好处是编译速度会加快，我换了一个版本的 Gson 库，但只要 library 的代码不改动，就不会重新编译主项目的代码。

api

等同于 compile 指令

compileOnly

等同于 provided，只在编译时有效，不会参与打包，不会包含到 apk 文件中。可以用来解决重复导入库的冲突。

远程仓库依赖

这里我们以 LeanCloud Android SDK 的引入来演示

引入远程仓库依赖是很方便的，但在之前我们需要在项目根目录的 build.gradle 声明远程仓库的地址。

buildscript {
    repositories {
        jcenter()
+        //这里是 LeanCloud 的包仓库
+        maven {
+            url "http://mvn.leancloud.cn/nexus/content/repositories/public"
+        }

    }
    dependencies {
        classpath 'com.android.tools.build:gradle:1.0.0'
    }
}

allprojects {
    repositories {
        jcenter()
+        //这里是 LeanCloud 的包仓库
+        maven {
+            url "http://mvn.leancloud.cn/nexus/content/repositories/public"
+        }
    }
}

然后打开 app 目录下的 build.gradle 进行如下配置：

android {
+    //为了解决部分第三方库重复打包了META-INF的问题
+    packagingOptions{
+        exclude 'META-INF/LICENSE.txt'
+        exclude 'META-INF/NOTICE.txt'
+    }
    lintOptions {
        abortOnError false
    }
}

dependencies {
    compile ('com.android.support:support-v4:21.0.3')

+    // LeanCloud 基础包
+    compile ('cn.leancloud.android:avoscloud-sdk:4.7.10')
+
+    // 推送与即时通讯需要的包
+    compile ('cn.leancloud.android:avoscloud-push:4.7.10@aar'){transitive = true}
}

本地依赖

使用 Android Studio 的同学请参考: Android Studio 引入 jar 包和 so 文件（armeabi 和 armeabi-v7a）

jar 包

1、将 jar 文件复制、粘贴到 app/libs 目录中，React Native 默认没有该文件夹，清新建一个

2、打开 app/build.gradle，进行如下配置以列出包含 jar 包的文件夹路径。

注意：React Native 默认已经进行了这个配置

1
2
3

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar"])
}

和远程仓库依赖引入方式不同，如果本地同时存在两个不同的 jar 包，或者本地已有 jar 包，再去远程依赖不同版本的 jar 包，就会报错。

解决方式：将其中的一个采用 compileOnly 替换 implementation。顾名思义，compileOnly 只在编译时起作用，不会包含到 APK 里面，在运行时也就避免找到重复的类了。

aar 包

arr 全称是 Andorid Archive,是一个 Android 库项目的二进制归档文件，使用 Android Studio ，非常简单可以生成一个 AAR 文件。

和 jar 包不同，aar 包存放的路径声明和依赖引入是分开的：

1、将 aar 包复制到 lib 目录下

2、在项目根目录 build.gradle中声明 aar 文件存放路径

buildscript {
  repositories {
+    flatDir { // 引用本项目的libs下的aar
+      dir "$rootDir/libs"
+    }
  }
}
allprojects {
  repositories {
+    flatDir { // 引用本项目的libs下的aar
+      dir "$rootDir/libs"
+    }
  }
}

3、在 app/build.gradle 中注入依赖

注意：远程 aar 引入形式是：implementation('com.sishu.android:watermelondb:0.7.0@aar')

1
2
3

dependencies {
+    implementation(name: 'aar名字', ext: 'aar')
}

so 文件

直接在 src->main 下新建一个文件夹 jniLib ，然后再把 so 文件所在的那个文件夹 armeabi 复制过去。

注：jniLib 是 so 文件默认的放置目录

坑

都是 Proguard 惹的祸

有时候明明导入了 jar 包，却仍然找不到 jar 包中的方法呢？八成是因为你开启了混淆，最安全的就是空间换安全。但是一个较真的程序员不能满足于此，我们还是要搞清楚 Proguard 惹了什么祸的。这里分享给大家一招：

打开 Android Studio 像原生开发工程师一样使用 Logcat 查看应用日志，比如你找到是 com.huawei.** 这个库找不到，那么进行如下配置：

1 2	+ -dontwarn com.huawei. + -keep class com.huawei.{*;}

-dontwarn 表示让 ProGuard 不要警告找不到 com.huawei.** 这个包里面的类的相关引用
-keep class 表示保持 com.huawei.** 这个包里面的所有类和所有方法不被混淆。再次编译打包，发现 apk 大小要明显大于之前的包。运行 app，问题解决！

aar 包中的资源文件重复了

资源文件重复了，主工程的资源文件会直接覆盖 aar 包中的文件，并且不会有任何报错或者提示，最终 aar 包中也会直接用主工程的资源文件，所以需要注意命名方式。暂时没有更好的解决方法。

AndroidManifest 合并错误

同样也是发生在 aar 包上， Android Studio 项目每个 module 中都可以有一个 AndroidManifest.xml 文件，但最终的 APK 文件只能包含一个 AndroidManifest.xml 文件。在构建应用时，Gradle 构建会将所有清单文件合并到一个封装到 APK 的清单文件中。aar 包的清单文件和我们的 app 清单文件属性冲突时：用 tools:replace="属性名" 解决。

annotationProcessor 与 compileOnly 的区别

上文说了 annotationProcessor 与 compileOnly 都是只编译并不打入 apk 中，他俩到底有什么区别呢？扮演的角色不一样，annotationProcessor 作用是编译时生成代码，编译完真的就不需要了，compileOnly 是有重复的库，为的是剃除只保留一个库，最终还是需要的。

参考

React VDOM 原理

2023-04-20T09:55:04.000Z

在 Web 前端开发中，React 是一种非常流行的 JavaScript 库，它的 Virtual DOM（虚拟 DOM）技术被广泛地应用于构建高性能、可维护的 Web 应用程序。那么，React VDOM 技术到底是什么？它又是如何工作的呢？

VDOM 是什么？

VDOM（Virtual DOM）是 React 中的一个重要概念，它是一个虚拟的、内存中的 DOM 树。与真实的 DOM 树不同，VDOM 只存在于 JavaScript 内存中，它是 React 组件的一部分，并且可以随时更新和修改。

React VDOM 技术的优势

React VDOM 技术主要有以下几个优势：

提高 Web 应用程序的性能：由于真实的 DOM 树非常庞大，而且每次更新都需要重新计算布局和重新渲染，因此更新频繁的 Web 应用程序很容易出现性能问题。而 VDOM 只是一个轻量级的 JavaScript 对象，它可以快速地进行比较和更新，从而大大提高了 Web 应用程序的性能。
提高 Web 应用程序的可维护性：由于 VDOM 只存在于 JavaScript 内存中，因此开发人员可以更方便地对其进行操作和管理，从而提高了 Web 应用程序的可维护性。
提高 Web 应用程序的开发效率：由于 VDOM 可以快速进行比较和更新，因此开发人员可以更快地进行开发和测试，从而提高了 Web 应用程序的开发效率。

React VDOM 技术的工作原理

React VDOM 技术的工作原理主要包括以下几个步骤：

首先，React 会将组件的 JSX 代码转换为 VDOM 对象，并将其存储在内存中。
当组件的状态发生变化时，React 会重新生成一个新的 VDOM 对象，并将其与之前的 VDOM 对象进行比较。
在比较过程中，React 会遍历新旧 VDOM 对象，找出它们之间的差异，并将这些差异记录在一个“差异对象”中。
最后，React 会根据“差异对象”中的记录，更新真实的 DOM 树，从而实现组件的重新渲染。

总结

React VDOM 技术是 React 中的一个重要概念，它可以提高 Web 应用程序的性能、可维护性和开发效率。虽然 VDOM 技术看起来比较复杂，但是它背后的原理非常简单，只需要理解其基本的工作原理，就可以快速上手使用。

叮，一份 Deno GitHub Action 源码解析请查收

2023-04-19T10:50:31.000Z

GitHub Action 是 GitHub 官方的 CI/CD 工具，相较于 Travis CI 和 Circle CI，更轻量和易于扩展，marketplace 中有大量社区贡献的插件。各大开源项目都纷纷转向使用 GitHub Action 作为持续集成的工具，比如本文的主角 Deno。

GitHub 的文档中有很多概念写的十分晦涩，有些翻译很僵硬影响理解。截止发稿时，Deno 的 ci.yml 文件有 323 行，是一个很好的学习范本。想要对 GitHub Action 有个了解或对 Deno 的持续集成部分感兴趣的同学都可以一起来探究下。

Action 结构

注意：GitHub Action 的 ci 脚本需要放在 .github/workflows 文件夹下

name: ci

on: [push, pull_request]

jobs:

name：工作流程的名称。GitHub 在仓库的操作页面上显示工作流程的名称。如果省略 name，GitHub 将其设置为相对于仓库根目录的工作流程文件路径。
on：必填。是触发工作流程的事件。Deno 中的 [push,pull_request] 代表有主分支有提交代码或 pull_request 时触发 CI 流程。
jobs：工作流程运行包括一项或多项作业。作业默认是并行运行。Deno 中只有一个 job —— build

build job

jobs:
  build:
    name: ${{ matrix.kind }} ${{ matrix.os }}
    if: |
      github.event_name == 'push' ||
      !startsWith(github.event.pull_request.head.label, 'denoland:')
    runs-on: ${{ matrix.os }}
    timeout-minutes: 60
    strategy:
      # ...
    env:
      # ...
    steps:
      # ...

`name：作业显示在 GitHub 上的名称。
- matrix：用于访问为当前作业配置的矩阵参数。例如，Deno 使用 kind 和 os 版本配置矩阵构建，matrix 上下文对象将包含当前作业的 kind 和 os 版本。
if：您可以使用 if 条件阻止作业在条件得到满足之前运行。Deno 中判断 github.event_name 等于 "push" 或 label 以 "denoland:" 开头的 pull_request 事件
runs-on：必填。任务运行的机器。机器可以是 GitHub 托管的运行器或自托管的运行器。定义操作系统矩阵时，必须将 runs-on 的值设置为您定义的 matrix.os 上下文属性。Deno 是跨平台的，因此创建了矩阵以在多个运行器操作系统上运行构建工作流程。
timeout-minutes: 在 GitHub 自动取消运行之前可让作业运行的最大分钟数。默认值：360。Deno 中设置为 60 来尽早暴露问题。
strategy：策略，用于创建作业的构建矩阵。您可以定义要在其中运行每项作业的不同变种。这可能不太好理解，在 Deno 中，其实就是为了同时构建出多个平台的产物。后面的章节我们单独解析 Deno 中具体的应用。
env：环境变量的 map 可用于作业中的所有步骤。您也可以设置整个工作流程或单个步骤的环境变量。后面章节我们单独解析 Deno 中具体的应用。
steps：作业包含一系列任务，称为 steps。步骤可以运行命令、运行设置任务，或者运行您的仓库、公共仓库中的操作或 Docker 注册表中发布的操作。后面章节我们单独解析 Deno 中具体的应用。

strategy 策略

strategy:
  matrix:
    include:
      - os: macos-10.15
        kind: test_release
      - os: windows-2019
        kind: test_release
      - os: ${{ github.repository == 'denoland/deno' && 'ubuntu-latest' || 'ubuntu-18.04' }}
        kind: test_release
      - os: ${{ github.repository == 'denoland/deno' && 'ubuntu-latest' || 'ubuntu-18.04' }}
        kind: test_debug
      - os: ${{ github.repository == 'denoland/deno' && 'ubuntu-latest' || 'ubuntu-18.04' }}
        kind: bench
      - os: ${{ github.repository == 'denoland/deno' && 'ubuntu-latest' || 'ubuntu-18.04' }}
        kind: lint

  # Always run master branch builds to completion. This allows the cache to
  # stay mostly up-to-date in situations where a single job fails due to
  # e.g. a flaky test.
  # Don't fast-fail on tag build because publishing binaries shouldn't be
  # prevented if 'cargo publish' fails (which can be a false negative).
  fail-fast: ${{ github.event_name == 'pull_request' || (github.ref !=
    'refs/heads/master' && !startsWith(github.ref, 'refs/tags/')) }}

strategy：策略会为您的工作创建构建矩阵。您可以定义不同的变体来运行每个作业。这可能不太好理解，在 Deno 中，其实就是为了同时构建出多个平台的产物。
- matrix：您可以定义不同作业配置的矩阵。Deno 中定义了 6 个矩阵。它们分别用来执行测试、调试、压测、lint 等工作
  - include：使用 matrix 只能定义使用某个 os，没办法添加其他配置。用 include 可以解决这个问题
- fail-fast：设置为 true 时，如果任何 matrix 作业失败，GitHub 将取消所有进行中的作业。默认值：true。ry 在这个 commit 中删除了 cargo publish，从注释中看来这里的 fail-fast 配置已经是冗余的了，我顺手就是一个 fork、commit、pr 三连。

插曲

${{ github.repository == 'denoland/deno' && 'ubuntu-latest' || 'ubuntu-18.04' }} 这种写法我看到时很疑惑，直接取 ‘ubuntu-latest’ 不行吗？如果不行是为什么呢？抱着求真的态度，我翻阅到是在这个 commit 加入的这个判断，在一番询问后得到了下面的答案：

在 justjavac 大佬那里也得到了印证：

然后我还有个疑问是为什么不使用三元表达式，是 YAML 语法不支持吗？

env 环境变量

env:
  CARGO_INCREMENTAL: 0
  RUST_BACKTRACE: full
  CARGO_TERM_COLOR: always

env：环境变量的 map 可用于作业中的所有步骤。您也可以设置整个工作流程或单个步骤的环境变量。代码中的三个变量是整个流程的环境变量。
- CARGO_INCREMENTAL、CARGO_TERM_COLOR、RUST_BACKTRACE 是配置给 Cargo 用的，具体的参考environment-variables-cargo-reads，这里不展开解读了。

steps 步骤

Deno 的 CI 中截止写下这段话时有 35 个步骤，相当考验我继续解读的勇气。。。

作业包含一系列任务，称为 steps。步骤可以运行命令、运行设置任务，或者运行您的仓库、公共仓库中的操作或 Docker 注册表中发布的操作。并非所有步骤都会运行操作，但所有操作都会作为步骤运行。每个步骤在运行器环境中以其自己的进程运行，且可以访问工作区和文件系统。因为步骤以自己的进程运行，所以步骤之间不会保留环境变量的更改。 GitHub 提供内置的步骤来设置和完成作业。—— 文档

1、Configure git

1 2	- name: Configure git run: git config --global core.symlinks true

git config --global core.symlinks true：克隆一个包含子模块和符号链接的存储库。这里是为了兼容 windows，详细的解释请查看 git bash symbolic links on windows

2、Clone repository

- name: Clone repository
  uses: actions/checkout@v2
  with:
    # 使用 `depth> 1`，因为有时我们需要重新构建 master 分支，如果 checkout 太浅，其他 commits push 之后将不可能重新构建。
    fetch-depth: 5
    submodules: true

actions/checkout@v2：checkout action 很常用
- fetch-depth: 5：默认情况下，仅提取一次提交。这里设置的 5，就会提取最近的 5 次提交。
- submodules: true：构建需要把子模块也获取到，Deno 中包含了子模块。

3、Create source tarballs (release, linux)

创建源文件压缩包 (release, linux)

- name: Create source tarballs (release, linux)
  if: |
    startsWith(matrix.os, 'ubuntu') &&
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    startsWith(github.ref, 'refs/tags/')
  run: |
    mkdir -p target/release
    tar --exclude=.cargo_home --exclude=".git*" --exclude=target --exclude=third_party/prebuilt -czvf target/release/deno_src.tar.gz -C .. deno

执行条件：构建矩阵 os 是 'ubuntu'、kind 是 'test_release'、仓库是 'denoland/deno'、本地执行 git push --tags 或 git push origin v0.0.1
run：其实发 release 的时候会自动打包源文件，这里之所以多打一个，是因为要忽略很多文件夹，打出纯 deno 的源文件

4、Install rust

安装 rust

- name: Install rust
  uses: hecrj/setup-rust-action@v1
  with:
    rust-version: 1.49.0

Deno 源码是 RUST 编写的，所以是用 hecrj/setup-rust-action@v1，每个语言都有自己的 setup，商店里能搜到 358 条记录。

5、Install clippy and rustfmt

- name: Install clippy and rustfmt
  if: matrix.kind == 'lint'
  run: |
    rustup component add clippy
    rustup component add rustfmt

6、Install Deno（非 Windows）

- name: Install Deno
  if: |
    !startsWith(matrix.os, 'windows')
  run: |-
    curl -fsSL https://deno.land/x/install/install.sh | sh -s v1.5.1
    echo "$HOME/.deno/bin" >> $GITHUB_PATH

执行条件：构建矩阵 os 不是 windows
run
- |- 和 |是 yaml 的语法。这样，您就可以有效地声明多行 yaml 字符串。语法详情查看这里
- curl -fsSL https://deno.land/x/install/install.sh | sh -s v1.5.1 安装 deno（这里应该可以 pr）
- echo "$HOME/.deno/bin" >> $GITHUB_PATH：设置环境变量，设置的指向文件系统上某个位置的任何新环境变量都应该有 _PATH 后缀。

7、Install Deno (Windows)

- name: Install Deno (Windows)
  if: startsWith(matrix.os, 'windows')
  run: |-
    curl -fsSL https://deno.land/x/install/install.sh | sh -s v1.5.1
    echo "$HOME/.deno/bin" >> $env:GITHUB_PATH

执行条件：构建矩阵 os 是 windows
run：和上文一样

8、Install Python

安装 python

- name: Install Python
  uses: actions/setup-python@v1
  with:
    python-version: '3.8'
    architecture: x64

9、Install Node

安装 Node

- name: Install Node
  uses: actions/setup-node@v2
  with:
    node-version: '14'
    check-latest: true

10、Remove unused versions of Python

删除没有用到的 Python 版本

- name: Remove unused versions of Python
  if: startsWith(matrix.os, 'windows')
  run: |-
    $env:PATH -split ";" |
      Where-Object { Test-Path "$_\python.exe" } |
      Select-Object -Skip 1 |
      ForEach-Object { Move-Item "$_" "$_.disabled" }

11、Setup gcloud (unix)

安装 Google Cloud SDK（unix）

- name: Setup gcloud (unix)
  if: |
    runner.os != 'Windows' &&
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    (github.ref == 'refs/heads/master' ||
    startsWith(github.ref, 'refs/tags/'))
  uses: google-github-actions/setup-gcloud@master
  with:
    project_id: denoland
    service_account_key: ${{ secrets.GCP_SA_KEY }}
    export_default_credentials: true

执行条件：运行系统不是 ‘Windows’、构建矩阵 kind 是 'test_release'、仓库是 'denoland/deno'、分支是 master 或是 tag 提交
google-github-actions/setup-gcloud：与 Google Cloud Platform 交互的 GitHub Actions 的集合。

12、Setup gcloud (windows)

同 11 作用一样，不过是为 windows 设置 gcloud

- name: Setup gcloud (windows)
  if: |
    runner.os == 'Windows' &&
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    (github.ref == 'refs/heads/master' ||
    startsWith(github.ref, 'refs/tags/'))
  uses: google-github-actions/setup-gcloud@master
  env:
    CLOUDSDK_PYTHON: ${{env.pythonLocation}}\python.exe
  with:
    project_id: denoland
    service_account_key: ${{ secrets.GCP_SA_KEY }}
    export_default_credentials: true

13、Configure canary build

配置 canary 渠道的 build（Deno 发布氛围 canary 和 release 渠道）

- name: Configure canary build
  if: |
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    github.ref == 'refs/heads/master'
  shell: bash
  run: |
    echo "DENO_CANARY=true" >> $GITHUB_ENV

执行条件：构建矩阵 kind 为 'test_release'、github repo 是 'denoland/deno'、master 分支
run 将 "DENO_CANARY=true" 设置进环境变量。

您也可以使用 GITHUB_ENV environment file 设置工作流程中的以下步骤可以使用的环境变量。 —— 文档

14、Log versions

检查前面安装的程序的版本

- name: Log versions
  run: |
    node -v
    python --version
    rustc --version
    cargo --version
    deno --version

15、lint.js

执行 lint

1
2
3

- name: lint.js
  if: matrix.kind == 'lint'
  run: deno run --unstable --allow-write --allow-read --allow-run ./tools/lint.js

执行条件：构建矩阵 kind 类型为 'lint'

16、test_format.js

测试格式化程序

1
2
3

- name: test_format.js
  if: matrix.kind == 'lint'
  run: deno run --unstable --allow-write --allow-read --allow-run ./tools/format.js --check

执行条件：构建矩阵 kind 类型为 'lint'

17、Build release

- name: Build release
  if: |
    matrix.kind == 'test_release' ||
    matrix.kind == 'bench'
  run: cargo build --release --locked --all-targets -vv

执行条件：构建矩阵 kind 类型为 'test_release' 或 'bench'

18、Build debug

1
2
3

- name: Build debug
  if: matrix.kind == 'test_debug'
  run: cargo build --locked --all-targets

执行条件：构建矩阵 kind 类型为 'test_debug'

19、Pre-release (linux)

发布之前的准备工作（linux）

- name: Pre-release (linux)
  if: |
    startsWith(matrix.os, 'ubuntu') &&
    matrix.kind == 'test_release'
  run: |
    cd target/release
    zip -r deno-x86_64-unknown-linux-gnu.zip deno
    zip -r denort-x86_64-unknown-linux-gnu.zip denort
    ./deno types > lib.deno.d.ts

执行条件：构建矩阵 os 为 'ubuntu'、构建矩阵 kind 为 'test_release'
run：做的事情其实就是打压缩包，这些压缩包最终会发布在 GitHub Release 中供安装脚本使用

20、Pre-release (mac)

和 19 作用一样，这里没有 ./deno types > lib.deno.d.ts，私以为漏了。

- name: Pre-release (mac)
  if: |
    startsWith(matrix.os, 'macOS') &&
    matrix.kind == 'test_release'
  run: |
    cd target/release
    zip -r deno-x86_64-apple-darwin.zip deno
    zip -r denort-x86_64-apple-darwin.zip denort

21、Pre-release (windows)

和 19、20 一样，just for windows，可以学习一下 Windows 下的压缩命令怎么写！

- name: Pre-release (windows)
  if: |
    startsWith(matrix.os, 'windows') &&
    matrix.kind == 'test_release'
  run: |
    Compress-Archive -CompressionLevel Optimal -Force -Path target/release/deno.exe -DestinationPath target/release/deno-x86_64-pc-windows-msvc.zip
    Compress-Archive -CompressionLevel Optimal -Force -Path target/release/denort.exe -DestinationPath target/release/denort-x86_64-pc-windows-msvc.zip

22、Upload canary to dl.deno.land (unix)

上传 canary 包到 dl.deno.land（unix）(我们只要知道托管在 Google 云就好了)

- name: Upload canary to dl.deno.land (unix)
  if: |
    runner.os != 'Windows' &&
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    github.ref == 'refs/heads/master'
  run: |
    gsutil cp ./target/release/*.zip gs://dl.deno.land/canary/$(git rev-parse HEAD)/
    echo $(git rev-parse HEAD) > canary-latest.txt
    gsutil cp canary-latest.txt gs://dl.deno.land/canary-latest.txt

执行条件：操作系统不是 Windows、构建矩阵 kind 是 'test_release'、github repo 是 'denoland/deno'、master 分支
run
- gsutil cp ./target/release/*.zip gs://dl.deno.land/canary/$(git rev-parse HEAD)/：上传压缩包到服务器
  - $(git rev-parse HEAD)：获取最新的 git commit hash，你可以再任一 git 库中执行 echo $(git rev-parse HEAD) 验证
- echo $(git rev-parse HEAD) > canary-latest.txt：将 commit hash 值作为版本写入 canary-latest.txt
- gsutil cp canary-latest.txt gs://dl.deno.land/canary-latest.txt：上传 canary-latest.txt 到服务器

23、Upload canary to dl.deno.land (windows)

和 22 作用一样，just for windows

- name: Upload canary to dl.deno.land (windows)
  if: |
    runner.os == 'Windows' &&
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    github.ref == 'refs/heads/master'
  env:
    CLOUDSDK_PYTHON: ${{env.pythonLocation}}\python.exe
  shell: bash
  run: |
    gsutil cp ./target/release/*.zip gs://dl.deno.land/canary/$(git rev-parse HEAD)/
    echo $(git rev-parse HEAD) > canary-latest.txt
    gsutil cp canary-latest.txt gs://dl.deno.land/canary-latest.txt

CLOUDSDK_PYTHON: ${{env.pythonLocation}}\python.exe：从这里可以看到 Python 环境是给 google cloud sdk 用的

24、Test release

测试发布

1
2
3

- name: Test release
  if: matrix.kind == 'test_release'
  run: cargo test --release --locked --all-targets

25、Test debug

测试 debug

- name: Test debug
  if: matrix.kind == 'test_debug'
  run: |
    cargo test --locked --doc
    cargo test --locked --all-targets

26、Configure hosts file for WPT (unix)

WPT 是 Web Platform Test 的意思，对应仓库 denoland/wpt

- name: Configure hosts file for WPT (unix)
 if: runner.os != 'Windows'
 run: ./wpt make-hosts-file | sudo tee -a /etc/hosts
 working-directory: test_util/wpt/

27、Configure hosts file for WPT (windows)

和 26 作用一样，just for windows

- name: Configure hosts file for WPT (windows)
  if: runner.os == 'Windows'
  working-directory: test_util/wpt/
  run: python wpt make-hosts-file | Out-File $env:SystemRoot\System32\drivers\etc\hosts -Encoding ascii -Append

28、Run web platform tests (release)

在 web 平台下运行测试（release）

- name: Run web platform tests (release)
  if: matrix.kind == 'test_release'
  run: |
    deno run --unstable --allow-write --allow-read --allow-net --allow-env --allow-run ./tools/wpt.ts setup
    deno run --unstable --allow-write --allow-read --allow-net --allow-env --allow-run ./tools/wpt.ts run --quiet --release

29、Run web platform tests (debug)

在 web 平台下运行测试（debug）

- name: Run web platform tests (debug)
 if: matrix.kind == 'test_debug'
 run: |
   deno run --unstable --allow-write --allow-read --allow-net --allow-env --allow-run ./tools/wpt.ts setup
   deno run --unstable --allow-write --allow-read --allow-net --allow-env --allow-run ./tools/wpt.ts run --quiet

30、Run Benchmarks

压力测试

1
2
3

- name: Run Benchmarks
  if: matrix.kind == 'bench'
  run: cargo bench

执行条件：构建矩阵 kind 为 'bench'

31、Post Benchmarks

看起来是把压测数据存到 denoland/benchmark_data

- name: Post Benchmarks
  if: |
    matrix.kind == 'bench' &&
    github.repository == 'denoland/deno' &&
    github.ref == 'refs/heads/master'
  env:
    DENOBOT_PAT: ${{ secrets.DENOBOT_PAT }}
  run: |
    git clone --depth 1 -b gh-pages https://${DENOBOT_PAT}@github.com/denoland/benchmark_data.git gh-pages
    deno run --unstable -A ./tools/build_benchmark_jsons.js --release
    cd gh-pages
    git config user.email "propelml@gmail.com"
    git config user.name "denobot"
    git add .
    git commit --message "Update benchmarks"
    git push origin gh-pages

执行条件：denoland/deno 库的 master 分支且构建矩阵的 kind 是 'bench'

32、Worker info

- name: Worker info
  if: matrix.kind == 'bench'
  run: |
    cat /proc/cpuinfo
    cat /proc/meminfo

执行条件：构建矩阵 kind 是 bench
run
- cat /proc/cpuinfo：查看 cpu 信息
- cat /proc/meminfo：查看内存信息

33、Upload release to dl.deno.land (unix)

上传 unix release 到 dl.deno.land

- name: Upload release to dl.deno.land (unix)
  if: |
    runner.os != 'Windows' &&
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    startsWith(github.ref, 'refs/tags/')
  run: |
    gsutil cp ./target/release/*.zip gs://dl.deno.land/release/${GITHUB_REF#refs/*/}/
    echo ${GITHUB_REF#refs/*/} > release-latest.txt
    gsutil cp release-latest.txt gs://dl.deno.land/release-latest.txt

34、Upload release to dl.deno.land (windows)

上传 windows release 到 dl.deno.land

- name: Upload release to dl.deno.land (windows)
  if: |
    runner.os == 'Windows' &&
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    startsWith(github.ref, 'refs/tags/')
  env:
    CLOUDSDK_PYTHON: ${{env.pythonLocation}}\python.exe
  shell: bash
  run: |
    gsutil cp ./target/release/*.zip gs://dl.deno.land/release/${GITHUB_REF#refs/*/}/
    echo ${GITHUB_REF#refs/*/} > release-latest.txt
    gsutil cp release-latest.txt gs://dl.deno.land/release-latest.txt

35、Upload release to GitHub

上传 release 到 GitHub

- name: Upload release to GitHub
  uses: softprops/action-gh-release@v1
  if: |
    matrix.kind == 'test_release' &&
    github.repository == 'denoland/deno' &&
    startsWith(github.ref, 'refs/tags/')
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    files: |
      target/release/deno-x86_64-pc-windows-msvc.zip
      target/release/deno-x86_64-unknown-linux-gnu.zip
      target/release/deno-x86_64-apple-darwin.zip
      target/release/deno_src.tar.gz
      target/release/lib.deno.d.ts
    draft: true

softprops/action-gh-release@v1：发布 github release 用的 action，这个确实很棒，可以执行直接上传 release asset 等高级操作。我在 tuya-panel-demo 中使用了该插件。

React Native 调试最佳实践

2023-04-19T10:43:42.000Z

人非圣贤孰能无过。

这句话还（更确切地说：尤其是…）适用于软件开发者。

这就是为什么在每一个开发者的职业生涯中最重要的是知道如何处理这些失误。作为一个 React Native 开发者，我经常想要写出没有 BUG 的代码，但是当出现问题时，我需要确保我能够追踪并解决问题。

在这篇文章中，我想讨论一些日常用于移动应用程序开发的工具和技术。我希望你可以发现一些对你的项目有帮助的东西。

静态检测，类型检查和格式化

静态检测

Linting 是执行程序的过程，用于分析潜在的语法程序错误。JavaScript 中最著名的 Linting 插件有：

ESLint - JavaScript 类型检查和格式化工具
Google’s Closure Compiler – 一个 JavaScript 优化器，可以更快速，更简洁地重写代码并检查本机 JavaScript 函数的使用。
JSLint – JavaScript 语法检查器和验证器

现在 ESLint 处于一统江湖的地位，也是 TypeScript 官方的 Linting 插件。

类型检查

我使用 TypeScript（TS）或者 Flow 来做类型检查。两者最主要的区别是前者是编程语言，而 Flow 是类型检查器。在我看来，TS 是更优的选择，因为大量类似于自动导入、自我证明和使用下一代 JavaScript 的能力。

原文中说 TS 是编程语言，我不完全赞同。毕竟官方的定位也只是 JavaScript 的超集。

格式化代码

程序员大部分时间都在阅读代码，因此重点不是更快地阅读代码，而是快速理解代码。

为了做到快读理解代码，我们需要最有效的视觉表示。这就是为什么我们需要很好地格式化代码。

比较一下下面的代码片段：

我建议大家使用 Prettier 格式化代码 - 它很容易集成和配置。你也可以通过 eslint-config-prettier 和 eslint-plugin-prettier 这两个插件和 ESLint 配合使用。

如何调试 React Native 应用

React Native 具有开发人员友好的环境，会告诉我们我们在警告或错误方面做错了什么：

内置调试模式

首先，您可以使用浏览器的内置调试模式（例如 Chrome 或 Safari）调试应用程序。

在 Chrome 中使用，你需要安装 react-devtools：

1	npm install -g react-devtools

在开发模式下，您可以打开开发人员菜单并从那里开始调试您的应用程序。只需激活 debug 选项：

它将打开带有 http://localhost8081/debugger-ui 路径的 Chrome 浏览器标签。

在您的 Chrome 浏览器中，您应该看到以下屏幕：

您也可以在 Safari 中调试应用的 iOS 版本，而不必启用 Debug JS Remotely。

怎么做？在 Safari 浏览器中，只需打开：

Preferences → Advanced → Select “Show Develop menu in menu bar

并选择 App 的 JSContext:

Develop → Simulator → JSContext

Safari 的 Web 检查器应打开，并应显示一个 Console 和一个 Debugger。每次重新加载应用程序时（使用实时 live reload、fast refresh 或通过手动重新加载），一个新的 JSContext 将被创建。只需选择 Automatically Show Web Inspectors for JSContexts，就可以避免手动选择最新的 JSContext。

Reactotron

如果您习惯将 Redux 用于 React Native 或 ReactJS 的状态管理，Reactotron 是调试状态的绝佳工具：

查看应用状态
显示 API 请求和响应
执行快速的性能压测
订阅应用的部分状态
显示类似于 console.log 的消息
使用 source-mapped 堆栈跟踪（包括 saga 堆栈跟踪）跟踪全局错误！
dispatch actions like a government-run mind control experiment
使用 Redux 或 mobx-state-tree 热交换您应用的状态
追踪你的 saga
在 React Native 中显示图像浮层
在 React Native 中跟踪您的异步存储

React Native Debugger

react-native-debugger 这是一个桌面应用程序，具有许多可调试应用程序的功能。至于应该提到的最重要的优点：

它基于官方的 Remote Debugger 并提供更多功能。
它包括来自 react-devtools-core 的 React Inspector。
它包括 Redux DevTools，并使用 redux-devtools-extension 制作了相同的 API。

注意: 如果你使用了 0.62 版本以上的 React Native，请使用 React Native Debugger v0.11

Native Logs

根据官方的 React Native 文档，您可以轻松记录两种平台的报告：

1 2	$ npx react-native log-ios $ npx react-native log-android

如果您需要进一步研究，可以使用特定于平台的 IDE（例如 XCode 或 Android Studio）来分析应用程序的本机代码并解决问题。

Flipper

Flipper 是用于调试 iOS、Android 和 React Native 应用程序的下一代平台。这是一个桌面应用程序，可让您灵活地检查、可视化和控制应用程序开发调试。这里很酷的功能是您可以通过扩展来更新 Flipper 的功能，例如：

如果您想集成 Redux 日志支持。

Flipper 支持 React Native Debugger 所有的功能，但是它也增加了很多。查看官方文档，以确保并可能创建自己的插件并支持社区。

本文翻译自 How To Debug React Native Apps Like A Pro? (Tools And Best Practices)

Rust 极速入门教程

2023-04-19T10:32:26.000Z

为什么选择 Rust?

Rust 是一门可以帮助你开发出高效率、高可靠性软件的编程语言。相较于 C/C++，Rust 力图同时提供强大的工程能力及良好的开发体验，在给予开发者控制底层能力（比如内存操作）的同时，避免传统语言带来的诸多麻烦。

高性能

Rust 速度惊人且内存利用率极高。由于没有运行时和垃圾回收，它能够胜任对性能要求特别高的服务，可以在嵌入式设备上运行，还能轻松和其他语言集成。

可靠性

Rust 丰富的类型系统和所有权模型保证了内存安全和线程安全，让您在编译期就能够消除各种各样的错误。

生产力

Rust 拥有出色的文档、友好的编译器和清晰的错误提示信息，还集成了一流的工具——包管理器和构建工具，能地自动补全和类型检验的多编辑器支持，以及自动格式化代码等等。

Rust 落地情况

全世界已有数百家公司在生产环境中使用 Rust，以达到快速、跨平台、低资源占用的目的。很多著名且受欢迎的软件，例如 Firefox、 Dropbox 和 Cloudflare 都在使用 Rust。从初创公司到大型企业，从嵌入式设备到可扩展的 Web 服务，Rust 都完全合适。

Dropbox

Dropbox 核心文件存储系统的多个模块是用 Rust 写的，因为它作为大型项目的一部分，需要追求更高的数据中心效率。目前，它应用于所有的 Dropbox 存储系统，为超过 5 亿用户服务。

Yelp

Yelp 使用 Rust 开发了一个实时 A/B 测试的框架。它广泛应用于所有的 Yelp 网页和应用，选择 Rust 是因为它和 C 语言一样快（运行代价小），同时比 C 语言更安全（易于维护）。

Deno 与 Rust

Deno 早期是 Golang + TypeScript 的，后来因为 Golang 和 V8 的 GC 问题，Ryan 下了大工夫把 golang 统统换成没有 GC 的 Rust了。知乎看到的一个回答觉得很有道理：

Go 自己有 GC，V8 自己也有 GC，双 GC 和复杂的运行时会造成多少性能损失。
Rust 具有高性能、内存安全等特性，非常适合写这种对性能要求高的程序。

GC（Garbage Collector，垃圾回收机制），Rust 和其他没有垃圾回收机制，而是使用一种叫做所有权的机制代替。由于是入门篇，此处不展开。

安装 Rust

和其他不太一样的是，Rust 官方提供了 rustup 命令行工具来下载、安装、管理不同的 Rust 发行版本以及其附带的工具链。

注意：Rust 的稳定性保证了所有发行版本都是向后兼容的。

安装 rustup：

1	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh

输出：

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
info: downloading installer

Welcome to Rust!

This will download and install the official compiler for the Rust
programming language, and its package manager, Cargo.

Rustup metadata and toolchains will be installed into the Rustup
home directory, located at:

  /Users/luozhu/.rustup

This can be modified with the RUSTUP_HOME environment variable.

The Cargo home directory located at:

  /Users/luozhu/.cargo

This can be modified with the CARGO_HOME environment variable.

The cargo, rustc, rustup and other commands will be added to
Cargo's bin directory, located at:

  /Users/luozhu/.cargo/bin

This path will then be added to your PATH environment variable by
modifying the profile files located at:

  /Users/luozhu/.profile
  /Users/luozhu/.zshenv

You can uninstall at any time with rustup self uninstall and
these changes will be reverted.

Current installation options:


   default host triple: x86_64-apple-darwin
     default toolchain: stable (default)
               profile: default
  modify PATH variable: yes

1) Proceed with installation (default)
2) Customize installation
3) Cancel installation
>1

以上信息可以总结为：

Rustup 家目录：~/.rustup，可以用 RUSTUP_HOME 环境变量修改
Cargo 家目录：~/.cargo，可以用 CARGO_HOME 环境变量修改
cargo、rustc、rustup 和其他命令都安装在 ~/.cargo/bin
PATH 环境变量是放在 ~/.zshenv 中的（这个方式第一次见）

这里让我们选择安装方式，由于是入门，我们直接选择默认安装，输入如下：

info: profile set to 'default'
info: default host triple is x86_64-apple-darwin
info: syncing channel updates for 'stable-x86_64-apple-darwin'
info: latest update on 2021-02-11, rust version 1.50.0 (cb75ad5db 2021-02-10)
info: downloading component 'cargo'
  4.3 MiB /   4.3 MiB (100 %)   3.1 MiB/s in  1s ETA:  0s
info: downloading component 'clippy'
info: downloading component 'rust-docs'
 14.7 MiB /  14.7 MiB (100 %)   2.2 MiB/s in  6s ETA:  0s
info: downloading component 'rust-std'
 23.3 MiB /  23.3 MiB (100 %)   2.2 MiB/s in 11s ETA:  0s
info: downloading component 'rustc'
 61.0 MiB /  61.0 MiB (100 %)   2.3 MiB/s in 26s ETA:  0s
info: downloading component 'rustfmt'
info: installing component 'cargo'
info: using up to 500.0 MiB of RAM to unpack components
info: installing component 'clippy'
info: installing component 'rust-docs'
 14.7 MiB /  14.7 MiB (100 %)   5.8 MiB/s in  1s ETA:  0s
info: installing component 'rust-std'
 23.3 MiB /  23.3 MiB (100 %)  13.0 MiB/s in  3s ETA:  0s
info: installing component 'rustc'
 61.0 MiB /  61.0 MiB (100 %)  13.3 MiB/s in  4s ETA:  0s
info: installing component 'rustfmt'
info: default toolchain set to 'stable-x86_64-apple-darwin'

  stable-x86_64-apple-darwin installed - rustc 1.50.0 (cb75ad5db 2021-02-10)


Rust is installed now. Great!

To get started you need Cargo's bin directory ($HOME/.cargo/bin) in your PATH
environment variable. Next time you log in this will be done
automatically.

To configure your current shell, run:
source $HOME/.cargo/env

以上这个过程是安装 rust 及其工具链并自动设置环境的过程，你可以根据提示输入 source $HOME/.cargo/env 让配置立即生效，也可以重新打开一个命令行让配置生效。

验证是否安装成功：

1	rustc --version

顺利的话，你会看到 rustc x.y.z (版本的哈希码 yyyy-mm-dd) 格式的输出。

更新：

1	rustup update

卸载：

1	rustup self uninstall

本地文档

安装工具在执行的过程中会在本地生成一份离线文档，你可以通过命令 rustup doc 在浏览器中打开它。但是我觉得一般用不到，我们在 vscode 中安装 Rust 插件有文档提示的功能。

Hello,World!

vscode

安装 Rust 插件：

rust-analyzer 也是一个很好的替代品，不过目前还不完善！

安装成功后将 "rust-client.rustupPath": "$HOME/.cargo/bin/rustup" 添加到 setting.json 来修复 couldn’t start client Rust Language Server

为了能调试软件，再安装插件 CodeLLDB：

crates 是辅助开发者在使用 Cargo.toml时管理依赖的插件：

由于 Rust 的依赖管理工具 Cargo 使用 TOML 作为配置文件，所以需要下载 Even Better TOML 插件支持语法。

最后设置下保存时自动格式化：

// settings.json
{
  "[rust]": {
    "editor.formatOnSave": true
  }
}

第一行代码

注意：Rust 文件总是以 rs 结尾。如果在名字中使用了多个单词，那么你可以使用下划线来隔开它们。比如你最好使用 hello_world.rs 作为文件名而不是 helloworld.rs

新建一个 main.rs 并写入以下代码：

1
2
3

fn main() {
  println!("Hello,World!");
}

使用关键字 fn 定义了一个函数。（Go（func）、JS（function）、数学（f）），看起来 Rust 很省布料。
main 函数比较特殊：当你运行一个可执行 Rust 程序的时候，所有的代码都会从这个入口函数开始运行（Go 也是一样）
按照惯例，Rust 推荐把左花括号与函数声明置于同一行并以空格分隔。
我们调用了一个被叫作 println! 的宏：假如我们调用的是一个普通函数，那么这里会以去掉 ! 符号的 println 来进行标记。
大部分 Rust 代码都会以分号来结尾。

所谓宏（Macro），是一种批量处理的称谓。计算机科学里的宏是一种抽象(Abstraction)，它根据一系列预定义的规则替换一定的文本模式。解释器或编译器在遇到宏时会自动进行这一模式替换。—— 可以简单理解为全局定义的函数、变量等

然后在命令行输入 rustc main.rs 编译代码，编译成功后会生成可执行文件 main:

1
2
3

.
├── main
└── main.rs

执行 ./main 便会输出 Hello,World!

windows 下会生成 main.exe

和 Ruby、Python 或 JavaScript 之类的动态语言不同，Rust、Go、Deno 都属于编译语言（JIT技术不在讨论范围），这意味这当你编译完 Rust 程序之后，便可以将可执行文件交付于其他人，并运行在没有安装 Rust 的环境中。如果你使用 Node 开发的应用交付给别人，别人必须要拥有 Node 开发环境。

Hello,Cargo!

和 Go 一样（go build），使用系统的编译工具（rustc）编译简单的程序足够了，但是它们无法满足规模大、协同开发人员多的项目。Go 有 gox、goxc、xgo，Rust 有 Cargo 来帮助我们管理简化项目依赖、代码构建这样的事情。

Cargo 是 Rust 工具链中内置的构建系统及包管理器。由于它可以处理众多诸如构建代码、下载编译依赖库等琐碎但重要的任务，绝大多数 Rust 用会选择它来管理自己的 Rust 项目（比如 Deno）。

前面我们的 helloworld 示例在 vscode 中，Rust 插件会报以下错误，可见 Cargo 是 Rust 的标配：

使用 Cargo 创建项目

使用 cargo new hello_cargo 新建项目：

Cargo 为我们生成了两个文件与一个目录：一个名为 Cargo.toml 的文件，以及一个名为 main.rs 的源代码文件
，该源代码被放置在 src 目录下。于此同时，Cargo 还会初始化一个新的 Git 仓库并升成默认的 .gitignore 文件。

Cargo.toml

[package]
name = "hello_cargo"
version = "0.1.0"
authors = ["youngjuning "]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

[package]：是一个区域标签，它表明接下来的语句会被用于配置当前的程序包。author 这里的邮箱和名字是从 ~/.gitconfig 中读取的
[dependencies]：同样是一个区域标签，它表明随后的区域会被用来声明项目的依赖。

TOML 是一种旨在成为一个小规模、易于使用的语义化的配置文件格式，“TOML”这个名字是“Tom’s Obvious, Minimal Language（汤姆的浅显的、极简的语言）”的首字母略写词。“Tom”指它的作者 Tom Preston-Werner。

按照惯例，Cargo 会默认把所有的源代码文件保存到 src 目录下，而项目根目录只被用来存放诸如 README 文档、许可声明、配置文件等与源代码无关的文件。使用 Cargo 可以帮助你合理并一致地组织自己的项目文件，从而使一切井井有条。

使用 Cargo 构建和运行项目

1	cargo build

与之前不同，这个命令会将可执行程序生成在路径 target/debug/hello_cargo 下：

首次使用命令 cargo build 构建的时候，会生成 Cargo.lock（类似于 yarn.lock），不要手动修改该文件，默认 .gitignore 中只忽略了 target 目录，我们从 https://github.com/github/gitignore/blob/master/Rust.gitignore 中复制最佳实践过来。

使用 cargo run 命令可以简单地以此完成编译和运行工作：

我们还可以使用 cargo check 快速检查项目是否可以通过编译

以 Release 模式构建

1	cargo build --release

生成的可执行文件会被放置在 target/release 目录下，而不是之前的 target/debug 目录下。

假如你想要对代码的运行效率进行基准测试，请通过 cargo run --release 命令进行构建，并使用 target/release 目录下的可执行程序完成基准测试。

crate

在 Rust 中，我们把代码的集合称作包（crate）。crate 是 Rust 中最小的编译单元，package 是单个或多个 crate 的集合，crate 和 package 都可以被叫作包，因为单个 crate 也是一个 package，但 package 通常倾向于多个 crate 的组合。crates.io 是 Rust 社区的 crate 代理。

Rust 语法学习笔记

2023-04-19T10:19:08.000Z

本文部分示例代码在 youngjuning/learn-rust

语言之间都有着类似的核心特性，比如变量、基本类型、函数、注释和控制流程等概念。但是每个语言有都有自己的独有概念，本文便是记录了我在学习 Rust 语法过程中遇到的 Rust 独有概念。

变量与可变性

Rust 中的变量默认是不可变的。Rust 语言提供这一概念是为了能够让你安全且方便地写出复杂、甚至是并行的代码。当然，Rust 也提供了让你可以使用可变变量的方法。

// main.rs
fn main() {
  let x = 5;
  println!("The value of x is: {}", x);
  x = 6;
  println!("The value of x is: {}", x)
}

x = 6 属于重复赋值，所以执行 cargo run 编译是不会通过的：

我们可以通过在声明的变量名称前添加 mut 关键字来使其可变。除了使变量的值可变，mut 还会向阅读代码的人暗示其他代码可能会改变这个变量的值。

常量与变量的不同

我们不能使用 mut 关键字来修饰一个变量。常量不仅是默认不可变的，它还总是不可变的。
你需要使用 const 关键字而不是一个 let 关键字来声明一个常量。
在声明的同时，你必须显式地标注值的类型。
常量可以被声明在任何作用域中，甚至包括全局作用域。这在一个值需要被不同部分的代码共同引用时十分有用
你只能将一个常量绑定到一个常量表达式上，而无法将一个函数的返回值，或其他需要在运行时计算的值绑定到常量上。

我们约定俗称地使用以下划线分割的全大写字母来命名一个常量，并在数值中插入下划线来提高可读性：const MAX_POINTS: u32 = 100_000;

隐藏

在 Rust 中，新声明的变量可以覆盖掉旧的同名变量，我们把这一现象描述为：第一个变量被第二个变量隐藏（shadow）了。这意味着我们随后使用这个名称时，它指向的将会是第二个变量。我们可以重复使用 let 关键字并分配以相同的名称来不断地隐藏变量：

fn main() {
    let x = 5;
    let x = x + 1;
    let x = x * 2;
    println!("The value of x is: {}", x)
}

如下图，我们可以看到 JavaScript 中并没有该特性：

隐藏机制和变量声明为 mut 的不同：

如果不是在使用 let 重新为这个变量赋值，则会导致编译错误。通过使用 let，我们可以对这个值执行一系列的变换操作，并允许这个变量在操作完成后保持自己的不可变性。
由于重复使用 let 关键字会创建出新的变量，所以我们可以在复用变量名称的同时改变它的类型。

数据类型

RUST 的编译器可以根据我们如何绑定、使用变量的值来自动推导出变量的类型。但在无法自动推导的场景，就必须显式地添加一个类型标注。

标量类型（scalar）

标量类型是单个值类型的统称。Rust 中内建了 4 种基础的标量类型：整数、浮点数、布尔值及字符。这类似于 JavaScript 中的基础类型。

整数类型

整数是指那些没有小数部分的数字。

长度	有符号	无符号
8 bit	i8（-128 到 127）	u8（0 到 255）
16 bit	i16（-32768 到 32767）	u16（0 到 65535）
32 bit	i32(默认)	u32
64 bit	i64	u64
arch	isize	usize

Isize 和 usize 是特殊的整数类型，它们的长度取决于程序运行的目标平台。在 64 位架构上，它们就是 64 位的，而在 32 位架构上，它们就是 32 位的。

可以使用 _ 作为分隔符以方便读数，比如 1_000

如何选择：

如果拿不定注意，Rust 对于整数字面量默认推导类型 i32 通常就是一个很好的选择：它在大部分情况下都是运算速度最快的
较为特殊的两个整数类型 usize 和 isize 则主要用作某些集合的索引

浮点数类型

单精度浮点数（f32）
双精度浮点数（f64）(默认)

由于在现代 CPU 中双精度和单精度的运行效率相差无几，却拥有更高的精读，所以在 Rust 中，默认会将浮点数字面量的类型推到为 f64。

fn main() {
  let x = 2.0; // f64

  let y: f32 = 3.0; // f32
}

布尔值

和 Go 语言一样，Rust 的布尔类型只拥有两个可能的值：true和 false。相较于 Javascript 中false、0、 NaN、''、null、undefined 6 种都可以被转换成 false 真的是很节省脑容量。

fn main() {
  let t = true;
  let f: bool = false // 附带了显式类型标注的语句
}

字符类型

在 Rust 中，char 类型被用于描述语言中最基础的单个字符。需要注意的是，char 类型使用单引号指定，而不同于字符串使用双引号指定。

复合类型（compound）

复合类型可以将多个不同类型的值组合为一个类型。Rust 提供了两种内置的基础复合类型：元组（tuple）和数组（array）。

元组类型

元组可以将其他不同类型的多个值进行组合
元组拥有一个固定的长度，我们无法在声明结束后增加或减少其中的元素数量

创建元组：

1
2
3

fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
}

把一些列值使用逗号分隔后放置到一对圆括号中
元组每个位置的值都有一个类型，这些类型不需要是相同的。

上面这段带来执行 cargo run 会有编译警告：

意思是，如果你是故意声明一个 unused variable，那就给变量名加一个下划线前缀来忽略警告

取值：

1、解构（destructuring）：使用模式匹配来解构元组：

fn main() {
    let tup = (500, 6.4, 1);
    let (_x, y, _z) = tup;
    println!("The value of y is: {}", y);
}

2、通过索引并使用点号(.)来访问元组中的值：

fn main() {
  let x: (i32, f64, u8) = (500, 6.4, 1);
  let five_hundred = x.0;
  let six_point_four = x.1;
  let one = x.2;
}

数组类型

数组（array）

通常当你不想在栈上而不是堆上为数据分配空间时，或者想要确保总有固定数量的元素时，数组是一个非常有用的工具。

与元组不同的是数组中的每一个元素都必须是相同的类型。
Rust 中的数组拥有固定的长度，一旦声明就再也不能随意更改大小，这与其他语言不同。

在 Rust 中，你可以将以逗号分隔的值放置在一对方括号内来创建一个数组：

1
2
3

fn main() {
  let a = [1, 2, 3, 4, 5]
}

为了写出数组的类型，你需要使用一对方括号，并在方括号中填写数组内所有元素的类型、一个分号以及数组内元素的数量，如下所示：

1	let a: [i32, 5] = [1, 2, 3, 4, 5]

创建一个含有相同元素的数组：

1	let a = [3; 5]

以 a 命名的数组将会拥有 5 个元素，而这些元素全部拥有相同的初始值 3。这一写法等价于 let a = [3, 3, 3, 3, 3]。

访问数组的元素：

数组由一整块分配在栈上的内存组成，你可以通过索引来访问一个数组中的所有元素：

fn main() {
let a = [1, 2, 3, 4, 5];
  let first = a[0];
  let second = a[1];
}

非法的数组访问

fn main() {
  let a = [1, 2, 3, 4, 5];
  let index = 10;

  let element = a[index];
  println!("The value of elements is: {}", element)
}

在 Rust Playground 运行这段代码，编译器提示我们，这个操作将会在运行时崩溃。原因是索引越界（Java 常见错误），数组长度是 5，但是我们给的索引是 10。

许多底层语言并没有类似的检查，一旦尝试使用非法索引，你就会访问到某块无效的内存空间（JavaScript 中则返回一个 undefined）

动态数组（vector）

动态数组是一个类似于数组的集合结构，但它允许用户自由地调整数组长度。如果你不确定使用数组还是动态数组，那就先使用动态数组吧。动态数组属于高级语法，不在本文讨论范围，后期会出一期更深入的解析。

函数（function）

main 函数是大部分程序开始的地方。
使用 fn 关键字来声明一个新的函数。
Rust 代码使用**蛇形命名法（snake case）**来作为规范函数和变量名称的风格。蛇形命名法只使用小写的字母进行命名，并以下划线分隔单词。

fn main () {
    println!("Hello world!");

    another_function();
}

fn another_function() {
    println!("Another function");
}

函数参数

函数参数是一种特殊的变量，并被视作函数签名的一部分。当函数存在参数时，你需要在调用函数时为这些变量提供具体的值。

fn main() {
  another_function(5);
}

fn another_function(x: i32) {
  println!("The value of x is: {}", x)
}

和 Go 语言一样，在 Rust 函数签名中，你必须显式地声明每个参数的类型。

和其他编程语言一样，Rust 中也是使用 , 来分隔多个参数：

fn main() {
  another_function(5, 6);
}

fn another_function(x: i32, y: i32) {
  println!("The value of x is: {}", x);
  println!("The value of y is: {}", y);
}

函数体中的语句和表达式

由于 Rust 是一门基于表达式的语言，所以它将语句（statement）与表达式（expression）区别为两个不同的概念。语句指那些执行操作但不返回值的指令，而表达式则是指会进行计算并产生一个值作为结果的指令。这个其他语言不太一样：

在 C 语言、Ruby、JavaScript 中 var x = y = 6 这种赋值语句会返回所赋的值，但是 Rust 中是行不通的。

值得注意的是，下面代码中的 x+1 是表达式。

fn main() {
  let x = 5;

  let y = {
    let x = 3;

    x + 1
  }

  println!("The value of y is: {}", y);
}

但是如果我们在表达式末尾加上了分号，这一段代码就变成了语句而不会返回任何值。

函数的返回值

在 Rust 中，函数的返回值等同于函数体最后一个表达式的值。
和其他编程语言不同的是，Rust 中函数的 return 语句不是必需的，只是一个用来提前返回的关键字。而且大多数函数都隐式地返回了最后的表达式。
需要在瘦箭头（->）的后面声明它的类型。

函数体最后一行必须是表达式，不要加分号，下面是反例：

fn main() {
  let x = plus_one(5);

  println!("The value of x is: {}", x);
}

fn plus_one(x: i32) -> i32 {
  x + 1;
}

尝试编译这段代码会产生如下错误信息：

可以看出，由于 x +1; 是表达式没有返回值，函数体隐式地返回了空元祖（()），进而导致编译时 mismatched types 错误。编译器给的建议是删除 x +1; 语句的分号。

控制流

if 表达式

fn main() {
    let number = 3;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false")
    }
}

和 Go 一样，判断条件不需要圆括号包裹。
代码中的条件表达式必须产生一个 bool 类型的值，否则就会触发编译错误。
与 Ruby 或 JavaScript 等语言不同，Rust 没有隐式转换

在 `let` 语句中使用 `if`

由于 if 是一个表达式，所以我们可以再 let 语句的右侧使用它来生成一个值。

fn main() {
  let condition = true;
  let number = if condition {
    5
  } else {
    6
  };

  println!("The value of number is: {}", number);
}

代码块输出的值就是其中最后一个表达式的值，另外，数字本身也可以作为一个表达式使用。
整个 if 表达式的值取决于究竟是哪一个代码块得到了执行。这意味着，所有 if 分支可能返回的值都必须是一种类型的。

使用循环重复执行代码

Rust 提供了 3 种循环：loop、while和for

loop 循环

fn main() {
  loop {
    println!("again!")
  }
}

运行这段程序时，除非我们手动强制退出程序，否则 again! 会被反复地输出到屏幕上。

从 loop 循环中返回值

fn main() {
  let mut counter = 0;

  let result = loop {
    counter += 1;

    if counter == 10 {
      break counter * 2
    }
  };

  println!("The result is {}", result);
}

上面的代码中我们将需要返回的值添加到 break 表达式后面，也就是我们用来终止循环的表达式后面。

while 条件循环

fn main() {
  let mut number = 3;

  while number !=0 {
    println!("{}!", number);

    number = number - 1;
  }

  println!("LOFTOFF!!!")
}

while 循环的模式是会在每次执行循环体之前都判断一次条件，假如条件为真则执行代码片段，加入条件为假或在执行过程中碰到 break 就退出当前循环。这种模式可以通过 loop、if、else 及 break 关键字的组合使用来实现。

使用 for 循环遍历集合

我们可以使用 for 循环来遍历集合中的每一个元素。

fn main() {
  let a = [10, 20, 30, 40, 50];

  for element in a.iter() {
    println!("The value is: {}", element)
  }
}

for 循环的安全性和简捷性使它成为了 Rust 中最为常用的循环结构。大部分的 Rust 开发者也会选择使用 for 循环。

下面的例子中，我们配合标准库中的 Range 来实现打印 1 到4:

fn main() {
  for number in (1..4).rev() {
    println!("{}!", number);
  }
  println!("LIFTOFF!!!")
}

Rust 编写猜数游戏

2023-04-19T10:10:36.000Z

猜数游戏代码在 guessing_game

为了方便大家学习，需要运行（cargo run）看效果的地方，我都截了GIF图。喜欢的话可以给紫升个👍🏻鼓励一下。

环境

rustc：1.50.0 (cb75ad5db 2021-02-10)
cargo：1.50.0 (f04e7fab7 2021-02-04)
rand crate：0.8.3
vscode plugins
Better TOML
CodeLLDB
crates
rust-analyzer
oh-my-zsh theme：ys
截图软件：Kap

处理用户输入

猜数游戏第一部分会请求用户进行输入，上代码：

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failded to read line");

    println!("You guessed: {}", guess);
}

声明导入

use std::io; 语句：把标准库（std）中的 io 模块引入当前的作用域中。
Rust 默认会将预导入（prelude）模块内的条目自动引入每一段程序的作用域中，它包含了一小部分相当常用的类型。如果你需要的模块不在预导入模块内，那么我们就必须使用 use 语句来显式地进行导入声明。
std::id 库包含了许多有用的功能，我们可以使用它来获得用户的输入数据。

使用变量来存储值

let mut guess：创建出一个名为 guess 的可变变量，变量默认是不可变的，mut 关键字表示可变（mutable）变量，关于变量与可变性的概念在两个番茄钟的Rust 语法学习笔记中有介绍。
String::new：返回一个新的 String 实例
- :: 语法表明 new 是 String 类型的一个关联函数（associated function）——其他语言中被称为静态方法（static method）
- String是标准库中的一个字符串类型，它在内部使用了 UTF-8 格式的编码并可以按照需求扩展自己的大小。
io::stdin：返回std::io::Stdin 的实例，它被用作句柄来处理终端中的标准输入。
.read_line 方法用来获得用户输入。
- read_line 的参数 &mut guess 表示引用一个可变变量。
- & 表示当前的参数是一个引用，这在 Go 中也是存在的。因为这些系统级编程语言大多都提供了操作内存的权限，而 JavaScript 是不给用户这些功能的。

句柄：在上世纪80年代的操作系统（如 Mac OS 句柄和Windows）的内存管理中，句柄被广泛应用。Unix系统的文件描述符基本上也属于句柄。和其它桌面环境一样，Windows API大量使用句柄来标识系统中的对象)，并创建操作系统与用户空间之间的通信渠道。例如，桌面上的一个窗体由一个HWND类型的句柄来标识。

处理可能失败的情况

我们先来看下 Go 里边的错误处理方式：

func main() {
  result,err := getResult();
  if err != nil {
    panic(err)
  }
  fmt.Printf("The result is %s", result);
}

func getResult() string,(string, err error) {
  // some codes
}

一般，一个函数可能报错的话都会在返回 result 的同时返回一个 error 。这并不是 Go 专属的，Rust 语言中也是如此，只不过实现方式不一样。

前面代码中，read_line 会将用户输入的内容存储到我们传入的字符串中，但与此同时，它还会返回一个 io::Result 值。在 Rust 标准库中，你可以找到许多以 Result 命名的类型，它们通常是各个子模块中 Result 泛型的特定版本，比如这里的io::Result。

Result 是一个枚举类型。枚举类型由一系列固定的值组合而成，这些值被称作枚举的变体。（众所周知，Javascript 没有枚举类型）

对于 Result 而言，它拥有 Ok 和 Err 两个变体。其中的 Ok 变体表明当前的操作执行成功，并附带代码产生的结果值。相应地，Err 变体则表明当前的操作执行失败，并附带引发失败的具体原因。

expect 是 Result 类型的值的一系列方法中的一个。假如 io::Result 实例的值是 Err，那么 expect 方法就会中断当前的程序，并将传入的字符串参数显示出来。

read_line 方法有可能因为底层操作系统的错误而返回一个 Err 结果。
相应地，假如 io::Result 实例的值是 Ok，那么 expect 就会提取出 Ok 中附带的值，并将它作为结果返回给用户。在我们的例子中，这个值就是用户输入内容的字节数。

即便我们没有在语句末尾调用 expect，这段程序也能够编译通过，但你会在编译过程中看到如下所示的警告信息。这一点和 Go 也基本一致。

Rust 编译器提醒我们 read_line 方法返回的 Result 值还没有被处理，这通常以为着我们的程序没有对潜在的错误进行处理。

消除警告最正确的方法当然是编写对应的错误处理代码，为了简单起见，我们在这里选择使用 expect 方法，它会让程序在出现错误时直接终止运行并退出。

通过 `println!` 中的占位符输出对应的值

println!("You guessed: {}", guess); 可以将我们存储的用户输入打印出来。这段宏调用的第一个参数是用于格式化的字符串，而字符串中的那些花括号{}则是一个占位符。

举一反三：{} 作为占位符不是 Rust 特有的，我所知的 Shell 中也有类似的应用，比如 ls | xargs -I {} tar zcvfm {}.tar.bz {} 这段脚本的意思就是将 ls 输出的值逐个通过管道传入后面的命令，{} 便是接收管道传的值的占位符。顺便一提，这段脚本我在 tuya-panel-demo 有使用。这里挖个坑，后续会出一个 Shell 脚本的系列教程。

尝试运行代码

现在，让我们借助 cargo run 命令来尝试运行一下这段代码：

生成一个保密数字

解决了接收用户输入的数字之后，我们需要生成一个保密数字来供玩家进行猜测。为了保证一定的可玩性，并使每局游戏都有不同的体验，这个生成的保密数字将会是随机的。

引入 rand 包

Rust 团队并没有把类似的随机数字生成功能内置到标准库中，而是选择将它作为 rand 包（rand crate）提供给用户。

注意：Rust 中包（crate）代表了一系列源代码文件的集合。我们当前构建的项目是一个用于生成可执行程序的二进制包（binary crate），而我们引入rand包则是一个用于复用功能的库包（libray crate，代码包）。

要使用第三方 crate ，我们需要在 Cargo.toml 文件中加入依赖：

...
[dependencies]

rand = "0.3.14"

在 Cargo.toml 文件中，从一个标题到下一个标题之间的所有内容都属于同一区域。这里的[denpendencies]区域被用来声明项目中需要用到的全部依赖包及其版本号。

书中的版本号比较老，vscode crates 插件提示了版本❌
我们点击任意版本即可选择该版本作为我们依赖的版本，点击圆括号内的 docs 便可跳转到库文档。

我们先不修改任何代码，直接重新构建这个项目：

现在，我们的程序有了一个外部依赖，Cargo 可以从注册表（registry）中获取所有可用库的最新版本信息，而这些信息通常是从cartes.io 上拷贝过来的。

cates.io 在 Rust 生态中是人们用于分享各种各样开源 Rust 项目的网站。

现在，如果你没有做出任何改变，立即重新运行 cargo build，那么只会有 Finished 提示。Cargo 会自动分析当前已经下载或编译过的内容，并跳过无需重复的步骤。

生成一个随机数

+ use rand::Rng;
use std::io;

fn main() {
    println!("Guess the number!");

+   let secret_number = rand::thread_rng().gen_range(1..101);

+   println!("The secret number is: {}", secret_number);

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failded to read line");

    println!("You guessed: {}", guess);
}

我们额外增加了一行 use 语句：use rand::Rng。这里的 Rng 是一个 trait（特征），它定义了随机数生成器需要实现的方法集合。为了使用这些方法，我们需要显式地将它引入当前的作用域中。
rand::thread_rng() 会返回一个特定的随机数生成器。随后我们调用这个生成器的gen_range方法。
gen_range 方法是在刚刚引入作用域的 Rng trait 中定义的，它接收一个 Range 类型（1..100）的值作为参数，并生成一个范围在两者之前的随机数。

提醒：书中的 gen_range 接收的是两个参数，读到时不要奇怪，版本不一样而已。

值得指出的是，gen_range生成的随机数空间包含下限但不包含上限。——做人呢，也是这样，要有底线，但不要给自己设上限。

使用第三方包，不可避免要频繁查看文档。你可以去官方文档看，这没什么问题。但是你也可以借助cargo doc --open 命令在本地构建一份有关所有依赖的文档，并自动地在浏览器中将文档打来来供你查阅：

上面代码中，我们将保密数字打印出来，只是为了调试，之后会删掉这段代码。

比较猜测数字与保密数字

现在，我们有了一个随机生成的保密数字，还有一个用户输入的猜测数字。接下来我们将比较这两个数字。

use rand::Rng;
+ use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..101);

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failded to read line");

    println!("You guessed: {}", guess);

+   match guess.cmp(&secret_number) {
+       Ordering::Less => println!("Too small!"),
+       Ordering::Greater => println!("Too big!"),
+       Ordering::Equal => println!("You win!"),
+   }
}

我们从标准库中引入了 std::cmp::Ordering 类型。与 Result 相同，Ordering 也是一个枚举类型，它拥有Less、Greater、Equal 这3个变体。（cmp 是 compare 的缩写）
match 表达式由由数个分支（arm）组成，每个分支都包含一个用于匹配的模式（pattern），以及匹配成功后要执行的相应代码。

Rust 中的match结构及模式是一类非常强大的工具，它们提供了依据不同条件执行不同代码的能力（类似其他语言的switch），并能够确保你不会遗漏任何分支条件。

上面这段代码，目前是无法通过编译的：

错误原因是因为我们保存的 guess 变量类型是 String，保密数字是 integer 类型，不同的类型无法匹配（静态语言不存在隐式类型转换）。

为了正常进行比较操作，我们需要将程序中读取的输入从 String 类型转换为数值类型：

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..101);

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failded to read line");

+   let guess: i32 = guess.trim().parse().expect("Please type a number");

    println!("You guessed: {}", guess);

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

我们这里创建一个新的不可变变量guess，虽然和前面的同名，但这是有效的，Rust 允许使用同名的新变量 guess 来隐藏（shadow）旧变量的值。这一特性通常被用在需要转换值类型的场景中，它在本例中允许我们重用 guess 这个变量名，而无须创造出 guess_str 之类不同的名字。
guess.trim() 是为了删除首尾所有空白字符。
字符串的 parse 方法会尝试将当前的字符串解析为某种数值。由于这个方法可以处理不同的数值类型，所以需要我们通过语句let guess: i32 来显式地声明我们需要的数值类型。

现在我们重新 Run 一下我们的程序：

这个游戏已经大体成型了，但玩家只能做出一次猜测，这显然是不够的，接下来，我们会加入一个循环来完善这个游戏。

使用循环来实现多次猜测

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    // `..` 语法是标准库中提供的 Range
    let secret_number = rand::thread_rng().gen_range(1..101);
+   loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failded to read line");

        let guess: i32 = guess.trim().parse().expect("Please type a number");

        println!("You guessed: {}", guess);

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
+           Ordering::Equal => {
+               println!("You win!");
+               break;
+           }
        }
+   }
}

我们将提示用户做出猜测决定之后的所有内容都移动到了 loop 中。在 Rust 中，loop 关键字会创建一个无限循环。
我们还给程序增加了一条break语句，使得玩家在猜对数字后能够正常退出游戏。

运行程序，玩家猜对数字，输出**You Win!**后，会退出程序：

处理非法输入

在转换 guess 字符串为 number 类型是，我们使用 expect("Please type a number")来处理可能出现的错误，我们尝试输入一个非 number 类型的值运行一下：

用户如果想要重新开始游戏，需要重启程序，这很明显，用户体验挺差的。为了改善游戏的可玩性，我们可以在用户输入了一个非数字数据时简单地忽略这次猜测行为，并使用户可以继续进行猜测，从而避免程序发生崩溃。

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    // `..` 语法是标准库中提供的 Range
    let secret_number = rand::thread_rng().gen_range(1..101);
    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failded to read line");

        let guess: i32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => {
              println!("Please type a number!");
              continue;
            }
        };

        println!("You guessed: {}", guess);

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

我们使用了 match 表达式来替换之前的 expect 方法，这是我们处理错误行为的一种管用手段。
parse会返回一个 Result 类型，而Result类型则包含了Ok与Err两个变体。

万事具备，让我们运行这个项目试试看：

为什么 Rust 需要局部变量隐藏

2023-04-19T10:08:20.000Z

什么是变量隐藏

在 Rust 的世界中，变量可以被一个同名的变量覆盖掉的现象就叫做隐藏。这意味着我们随后使用这个名称时，他指向的将会是第二个变量。我们可以重复使用let关键字并配以相同的名称来不断地隐藏变量：

fn main() {
  let x = 5;

  let x = x + 1;

  let x = x + 2;

  println!("The value of x is: {}", x);
}

按照世界上没有完全一样的两个东西的原则（上一秒的你也不等于下一秒的你），这前后两个变量并不会完全一样。我并没有看过 Rust 源码，个人理解是这两个变量指向的内存空间是不一样的。所谓隐藏不过是编译器在编译的时候去做了区分。子非编译器，安知compiler之乐乎？

隐藏机制与mut（mutable）的不同：

如果不是在使用 let 关键字的情况下重新为这个变量赋值，则会导致编译错误。通过使用let，我们可以对这个值执行一些列的变化操作，并允许这个变量在操作完成后保持自己的不可变性。
由于重复使用 let 关键字会创建出新的变量，所以我们可以在复用变量名称的同时改变它的类型。

隐藏特性通常被用在需要转换值类型的场景中，如果只是改变值本身 mut 关键字就够用。

为什么 Rust 需要变量隐藏？

这是 reddit rust 话题下的一个问题，我这里翻译一下。

问题

我最近发现 Rust 不像其他类C语言，它允许在一个块作用域中定义多个拥有相同名称的变量：

let name = 10i;
let name = 3.14f64;
let name = "string";
let name = name; // "string" again, this definition shadows all the others

至少从我的 C++ 背景来说，第一次看到这个特性着实有点吓人。

这个特性来自哪里？它提供了什么好处？

回答

变量隐藏与仿射类型（affine types）具有很多协同作用。例如：

1	let foo = foo.unwrap();

你在其中重新绑定 foo 的同时引用 unwrap() 的结果，因此旧 foo 由于该原因而变得不可访问。——变量指向了新的内存空间。

好处是使用一个单词来表示共同的变量，例如 c 用于绘制上下文。变量可以被改变类型，Rust-Graphics 大量地依赖该特性。每一个方法返回一个新的类型，并且当上下文提供足够的信息去绘制时，你只能调用.draw(gl)。

我经常使用的单个字母是：

a、b 用作二进制操作的参数
c、d、g 用作图形绘制
i、j、k 用作索引
n、m 用作长度
x、y、z、t 作为空间坐标系

有时我也使用p、q或者v、u 作复杂的数学运算。

我认为变量隐藏的最佳论据是阻止对象可变性的能力。

let mut vec = Vec::new();
vec.push(1i);
vec.push(2i);
let vec = vec;

但是，对于中间变量，我也很喜欢。有时，通过let绑定将长方法链分成两行只是更漂亮。您只需两次使用变量名来代替使用 let temp,这样，临时变量不会使函数名称空间的其余部分杂乱无章。

我不确定，但我认为此功能可将可变性降至最低。您可以使用新值重新声明它，而不用突变一个变量。

无论如何，它并没有看起来那么糟糕。类型系统禁止使用int代替浮点数或字符串。

确实，此功能可能会导致错误，但也可以防止它们。没有隐藏，您常常必须为变量（相同类型）使用不同的名称，这使得使用错误的变量成为可能。

我昨天也注意到了这一点。我宁愿没有它，因为它引入了难以发现的错误。

我自己的C ++代码中有与隐藏相关的错误（就在上周）。此外，由于隐藏局部变量，Gecko中也存在bug，因此显然这很危险。

我知道Rust是一种旨在防止错误的语言（即使它降低了便利性），所以我想知道为什么允许这样做。值得冒着出BUG的风险吗？

也有人评论说lint有一个选项可以警告可变阴影。会有这样的选择吗？但愿如此。

顺便提一句。该线程还有一些用例，人们如何使用隐藏，因此对此线程感兴趣的人应该通读它。

我经常使用隐藏来防止再次引用另一个变量。这是我从OCaml那里习得的一种习惯，在该习惯下，隐藏是允许的并且是惯用的。

比如，在 trans 中我经常隐藏来终止块变量，因为再次使用它们是一个错误。这样，隐藏可以成为防止错误的强大工具。

总结

这个问答中，整体的意见比较一致，就是隐藏特性乍看起来很不爽，但是用多了就会惊讶于它的安全性、便捷性。凡事有捧就有踩，还是有老哥说出来隐藏用多了，很难调试，由于老哥过于啰嗦，懒得翻译原文如下：

个人觉得这有点杠了，所有设计一旦被滥用就会变得不对劲。总体来说隐藏带来的好处是大于益处的。

当我们在聊 React Native 时，我们在聊什么

2023-04-19T10:01:42.000Z

缘起

那是 18 年的夏天，公司 6 月底去成都团建回郑州后，小弟、肖老师和当时绰号小萌的我（以下简称三剑客）开始了使用 React Native 开发 App 的工作。当时经验尚浅的我也只是有小程序和公众号的开发经验，唯一的亮点就是封装了 wx-promise-pro 并独立完成了一个小程序的全栈开发，而另外两位同事一个后端大佬经验丰富，一个 ios、vue、android、C#、Java 等等技能栈点满。

怎么说呢，当时也就中等焦虑吧。也就赶鸭子上架各种不适，也就睡不好吃不好担心末位淘汰，也就担心没工作被我爸唠叨。

人们常说压不倒你的，最终都能成就你。我就是顶着巨大心里压力一头扎进了跨端开发这个领域，一晃便是两年多过去了。接着掘金的活动，和大家聊一聊 RN 的一些事。

聊聊 React Native 入门

找到紫升询问 React Native 最多的问题便是 React Native 环境的搭建，我都会耐心地帮助大家排查（有时也会让仔细看官网）。这个时候我一般都会和他们聊一下我们三剑客初次搭建环境最快的也是用了一整个工作日，最慢的因为电脑环境混乱多花了一个周末排查问题的故事。

万事开头难这句话用在 RN 和 Flutter 上尤其合适，跨端对于原生转和前端上手都是不太友好的，所以不要再问前端转合不合适，原生转不比你舒服到哪里去。

这里提醒大家关于环境的几点：

Java jdk 一定要安装 1.8 系列
尽量使用安卓真机测试
如果用 Android Studio 打开项目，不要跟着提示随便升级 gradle
RN 0.60 之后 ios 使用 cocoapod 管理项目依赖，这玩意如果网速不好，会卡住。建议别折腾，买个 ** 也饿不死人的

聊聊跨端开发

跨端开发也叫 Hybrid Development，React Native、Flutter、Weex 都属于这个范畴。任何事物的出现必然是有其客观需求存在，跨端开发相较于传统的原生开发有其迭代周期快、可以在发布应用后热更新代码、甚至代码直接通过服务动态下发的优点，相较于 Codava、H5 打包这种解决了 60 帧问题，性能更好更接近原生。

目前前两者在各大厂 App 中都有业务落地，众所周知的闲鱼使用 Flutter 写了不少业务，前文提到的我们三剑客是完全用 React Native 搭建的项目，而现在我所在的涂鸦智能的 App 是使用原生搭建项目，嵌入我们的核心面板业务。我们不可能把所有的设备控制面板都写在 App 中，ios、android 的平台也不能动态下发代码，而 React Native 可以实现开发面板 -> 打包 -> 注册到云端 -> 客户端根据从服务端动态加载相应的业务代码这个流程。顺便提一下隔壁小组也有在做基于 Flutter 的一码多端方案，加入涂鸦，无论你是 RN 开发者还是 Flutter 开发者都能发挥所长。

从事 RN 开发需要会什么？

以我的经验来看，只要你有编程经验，快速从事 RN 业务开发难度并不大。写页面用到的无非是 React 语法、React Native 内置组件的使用和第三放组件、API 的使用。

但是如果是要掌控整个 App 的架构和开发，那要求会多一些。但也无非是 React 开发同样需要掌握的全局状态管理、路由管理、组件封装等能力。

你可能会问不会原生开发可以从事 RN 开发吗？答案是肯定的，跨端方案的出现对于前端开发者的一大利好便是可以使用前端技术开发移动应用。React Native 不管是官方还是社区都有大量的封装好的 SDK 可供使用，比如 react-native-svg、react-native-camera、react-native-video、react-native-sound、react-native-permissions 等等这些优秀的三方库。当然你可能还有疑问，如果社区没有现成的，或者需要自定义原生的功能才能完成业务怎么办？这个就没那么简单了，但是别担心，现代工业社会是讲究协作和精细化分工的，在涂鸦，我们有专业的原生开发团队为我们提供底层 SDK 业务编写，但是我还建议大家 ios、android 的桥接代码还是要会写、原生的配置要懂，有助于提升个人能力和稀缺性。相信我这并不复杂，你遇到的问题搜一下也能解决。紫升的经验也仅限于掌握原生配置、对原生 SDK 进行封装暴露接口给 JS 层调用，ios 课程买了有一年了，也没看一点（实在惭愧）。对原生 SDK 桥接感兴趣的可以看下原生模块简介和create-react-native-module。

聊聊我为社区做的一些事

你可能会在各种 react native 仓库的 issue 中看到我的身影，这里也推荐大家遇到什么问题多去 github 看看 issues，一个成熟的仓库基本都能在 issue 中找到解决办法。

umi-plugin-react-native：Show React Native Demo with dumi powered by react-native-web
react-native-quill-editor：React Native Quill Rich Text Editor Wrapper
react-native-form：私塾React Native动态表单项目，这个项目后来只在内部更新了，离职一年多了，大概率被同事重构了已经，我一直说要用 hooks 实现以下，也没得机会。
react-native-screenshot：简单易用的 React Native 截屏、监听系统截屏事件组件（ios、android）
react-native-office-viewer：Office Preview Plugin for React Native（support png,pdf,doc,xls,txt…）
react-native-template-sishu：👾 Clean and minimalist React Native template for a quick start with TypeScript.
react-native-qiniu：Qiniu React Native SDK ,A pure javascript implementation
react-native-float-ball：🏀 floatBall with PanResponder 🏈
优雅地使用TypeScript开发React Native应用
react-navigation 5.x 最佳实践
React Native 项目架构面面观
React Native 集成 CodePush 指南
【译】在 React Native TypeScript 项目中使用 defaultProps
【译】在 React Native TypeScript 项目中使用 defaultProps
手摸手带你封装 React Native 富文本编辑器
React Native 调试最佳实践|牛气冲天新年征文

聊聊岗位待遇

有一说一，React Native 包括 Flutter 在内，岗位比 Web 前端开发是要少很多的，但是这并不意味着不值得投资。相较于 Web 开发，跨端开发需要掌握更多的技能，入门更难一些。但是一般掌握了它，对应的薪资待遇也是很诱人的。

深入理解 Rust 所有权、借用、生命周期

2023-04-19T09:59:17.000Z

原文地址：Understanding Rust: ownership, borrowing, lifetimes
原文作者：bugaevc
译文出自：掘金翻译计划
本文永久链接：https://github.com/xitu/gold-miner/blob/master/article/2021/understanding-rust-ownership-borrowing-lifetimes.md
译者：紫升
校对者：霜羽 Hoarfroster、Zz招锦

我对这些概念的理解是，你一旦掌握了它，所有这些语法都会看起来自然且优雅。

我不会从零开始展开教学，也不会机械地重复官方文档的内容（虽然说有时会 🙈）—— 如果你还不了解这些概念，那么你现在应该读一下对应章节的内容，因为本文是对书上内容的补充，而不是要替代它。

另外，我也建议你读一下这篇出色的文章。它实际上是在讲述相近的话题，但关注点不一样，也值得一读。

让我们先来谈谈资源是什么。资源是宝贵的、“沉重的”、可以获取和释放（或销毁）的东西，比如一个套接字，一个打开的文件，一个信号量，一个锁，一个堆内存区域。按照传统，所有这些事情都是通过调用一个函数来创建的，该函数返回对资源本身的某种引用（一个内存指针或一个文件描述符），当程序认为自己已完成对资源的处理时，需要程序员 👨🏻‍💻 显式关闭该文件。

这种方法存在着问题。人非圣贤，孰能无过。通常我们很容易忘记释放某些资源，从而导致发生所谓的内存泄漏。更糟糕的是，人们可能会尝试访问已经释放的资源（即在释放之后使用）。如果运气好，他们会收到一条报错消息，这可能会帮助他们识别和修复错误，也可能不会。反之，它们所具有的引用（尽管就逻辑而言是无效的）可能仍是引用某个“内存位置”，而该“内存位置”已经被其他资源占用。例如说已存储其他内容的内存，其它打开的文件所使用的文件描述符等。试图通过无效的引用访问旧资源可能会破坏其他资源或使得程序完全崩溃。

我们讨论这些问题并不是杞人忧天，因为它们无时无刻伴随着我们。比如，在 Google Chrome 发布博客中就存在着大量因为使用了被释放的资源引发的漏洞和崩溃的修复记录 —— 这也极大的浪费了人力物力，去识别和修复它们。

并不是说开发人员是愚蠢和健忘的，因为逻辑流程本身就容易出错：它需要你显示释放资源，但是并不强制你做这些。此外，我们通常不会注意到资源被忘记释放，因为这个问题很少会有着什么明显的影响。

有时要实现简单的目地就需要发明复杂的解决方案，而这些解决方案会带来更复杂的逻辑。我们很难避免在庞大的代码库中迷失，并且 Bug 总是在这里或那里突然冒出来，我们最终也见怪不怪了。其中大多数的问题都很容易被发现，但是与资源相关的错误却很难被发现。因此，一旦如果资源被野指针利用，便会非常危险。

当然，像 Rust 这样的新语言无法为你解决 Bug，但是，它可以成功地影响你的思维方式，将一些架构带入你的思想，从而使这类错误的发生几率大大降低。

Rust 为你提供了一种安全清晰的方法来管理资源。而且，它不允许你以其他任何方式对其进行管理。这是非常严格的，但这不正是我们的目的吗？

这些限制之所以很棒，有几个原因:

它们能让你以正确的方式思考。在有了一些 Rust 开发经验后，即使在其他语言的语法中没有内置这些概念时，你也经常会发现自己尝试应用相似的概念。
它们能让你编写的代码更安全。除了几个很稀有的极端案例，Rust 基本上可以保证你所有的代码都不会涉及我们正在谈论的错误。
虽然如果有垃圾收集机制，Rust 就会像高级语言一样令人愉悦（我可没说 JavaScript 是令人愉悦的！），但是 Rust 与其他低级编译语言一样快且接近底层。

考虑到这一点，让我们来看一下 Rust 的一些优点。

所有权

在 Rust 中，关于资源属于哪块代码有很明确的规则。在最简单的情况下，是代码块创建了代表资源的对象。在代码块的末尾，对象被销毁且资源被释放。这里重要的区别是对象不是某种容易忘记的“弱引用”。在内部，该对象只是用于完全相同引用的包装器，而从外部看，它似乎是它表示的资源。当到达拥有资源的代码块的末尾时，资源将会自动且可预测地释放。

当编译到拥有该内存的代码的尾部，程序会自动且安全地释放资源。妈妈再也不用担心忘记释放资源了！因为该行为是全自动且可预测的，它完全会按照你的预期来完成。

这时你可能会问，为什么我要描述这些琐碎而明显的事情，而不是仅仅告诉你聪明人称之为 RAII 的概念？好吧，让我们继续聊一下。

这个概念适用于临时对象。比如以下操作：将一些文本写入文件 -> 专用代码块（例如，一个函数）将打开一个文件（结果是得到一个文件对象（包装文件描述符））-> 然后对其进行一些处理 -> 然后在该块的末尾将得到文件对象 -> 最后删除并且文件描述符关闭。

但是在很多场景中这个概念并不管用。你可能希望将资源传递给其他人，在几个“用户”之间甚至在线程之间共享它。

让我们来看看这些。首先，你可能希望将资源传递给其他人（转移所有权），被转移的人便会拥有资源，可以对资源进行任何操作，甚至更重要的是负责释放资源。Rust 很好的支持了这一点，实际上，当你将资源提供给其他人时，默认便会发生这种情况。

fn print_sum(v: Vec<i32>) {
    println!("{}", v[0] + v[1]);
    // v 被移除随后被释放
}

fn main() {
    let mut v = Vec::new(); // 资源在这里被创建
    for i in 1..1000 {
        v.push(i);
    }
    // 在这里， 可变变量 v 被使用
    // 不少于 4000 字节的内存
    // -------------------
    // 转移所有权给 print_sum 函数
    print_sum(v);
    // 我们不拥有并且不能以任何方式控制变量 v
    // 在这里尝试访问 v 将引发编译时错误
    println!("We're done");
    // 这里并不会发生任何释放动作
    // 因为 print_sum 此时负责可变变量 v 的一切
}

所有权转移的过程也称为移动，因为资源是从旧位置（例如，局部变量）被移动到了新位置（例如，一个函数参数）的。从性能角度来看，这只是“弱引用”被移动，因此这个过程很快。但是对于代码来说，好像我们实际上将整个资源都移到了新地方。

移动和复制是有区别的。广义来说，它们都意味着复制数据（如果 Rust 允许复制资源的话，这种情况下将是“弱引用”），但移动后，原始变量的内容将被视为不再有效或不再重要。Rust 实际上会将该变量视为“ 逻辑上未初始化”，也就是说，充满了一些垃圾，例如刚刚创建的那些变量。这类变量是被禁止使用的（除非你使用新值重新初始化它），此时也不会发生资源的重新分配：现在拥有资源的人有责任在完成后进行清理。

移动不仅限于传递参数。你可以移动给一个变量。你还可以移至返回值。为此，你可以从返回值、变量、函数参数移动。基本上到处都是隐式和显示的分配。

尽管移动语法是处理资源的完全合理的方式，我将在稍后演示对于普通的旧原始数字类型变量来说，这将是一场灾难（设想无法复制一个 int 类型变量的值给另一个变量）。幸运的是，Rust 有 Copy 特征。实现它的类型（所有原始类型都使用）在分配时使用复制语法，所有其他类型都使用移动语法。这非常容实现，如果你希望自己的类型是可以被复制的，则只需要可选地实现 Copy 特征。

fn print_sum(a: i32, b: i32) {
    println!("{}", a + b);
    // 被复制的 a 和 b 变量在这里被移除和释放
}

fn main() {
    let a = 35;
    let b = 42;
    // 复制和传递值
    // 被复制的值传递的所有权传递给 print_sum：
    print_sum(a, b);
    // 我们仍然保留对原始a和b变量的完全控制权
    println!("We still have {} and {}", a, b);
    // 原始的 a 和 b 被移除并随后被释放
}

现在，我们来探讨下为什么移动语法会有用呢？如果没有他们，一切都显得那么完美。好吧，也不完全是。有时候，这是最合乎逻辑的事情。比如 with_capacity 函数会分配一个字符串缓冲区，然后将其返回给调用方。所有权被转移了，并且该函数不再关心缓冲区的生死。而调用者可以完全控制缓冲区，包括负责缓冲区的释放。

在 C 语言中是一样的。诸如 strdup 之类的功能将分配内存，将其内存管理交给你，并期望你进行管理并最终对其进行分配。区别在于它只是一个指针，它们所能做的就是在完成后要求或提醒你使用 free()。上面所说的移动特性几乎无法做到，而在 Rust 中，这是该语言不可分割的一部分。

另一个示例是迭代器适配器，比如 count 这种无论如何之后都没有访问迭代器的意义。

相反的问题是，在什么情况下，我们需要对同一资源有多个引用。最明显的用例是进行多线程处理的场景。否则，如果所有操作都按顺序执行，则移动语法可能总是起作用的。尽管如此，一直来回移动东西还是很不方便的。

有时，尽管代码严格按顺序运行，但仍然感觉好像同时发生了几件事。想象一下在 vector（可变数组）上进行迭代。循环完成后，迭代器可以将你对相关 vector 的所有权转移给你，但你将无法在循环内获得对 vector 的任何访问权限。也就是说，除非你每次迭代都在你的代码和迭代器之间拥有所有权，否则那将是一团糟。似乎也无法在不破坏堆栈的情况下遍历一棵树，然后重新构造并备给以后做其他事情时用。

同时，我们将无法执行多线程，这就很不方便甚至让人厌烦。值得庆幸的是，还有一个很酷的 Rust 概念可以为我们提供帮助。那就是借用！

借用

当一个函数使用引用而不是值本身作为参数时，我们便不需要为了归还所有权而特意去返回值，毕竟在这种情况下，我们根本没有取得所有权。这种通过引用传递参数给函数的方法也被成为借用。——《Rust 权威指南》

我们有多种角度解读借用：

它使我们在拥有资源的多个引用的同时仍坚持“单一所有者，单一责任”的概念。
引用类似于 C 语言中的指针。
引用也是一个对象。可变引用被移动，不可变引用被复制。删除引用后，借用将终止（取决于生命周期规则，请参见下一节）。
在最简单的情况下，引用的行为就像在没有明确地进行所有权操作的情况下来回移动所有权。

下面这段代码就是最后一条的意思：

// 没有借用发生
fn print_sum1(v: Vec<i32>) -> Vec<i32> {
    println!("{}", v[0] + v[1]);
    // 返回 v 把所有权返回
    // 顺便一提，由于 Rust 是基于表达式的，所有这里不需要使用 return 关键字便可返回值
    v
}

// 有借用，明确的引用
fn print_sum2(vr: &Vec<i32>) {
    println!("{}", (*vr)[0] + (*vr)[1]);
    // vr 是一个引用，在这里被移除，因为借用结束了
}

// 这就是你应该做的
fn print_sum3(v: &Vec<i32>) {
    println!("{}", v[0] + v[1]);
    // 同 print_sum2
}

fn main() {
    let mut v = Vec::new(); // 创建可变数组
    for i in 1..1000 {
        v.push(i);
    }
    // 此时， v 被使用
    // 不超过 4000 字节的内存

    // 传递 v 的所有权给 print_sum 并在执行结束后反会 v
    v = print_sum1(v);
    // 现在，我们重新取得了 v 的所有权
    println!("(1) We still have v: {}, {}, ...", v[0], v[1]);

    // 取 v 的引用传递给 print_sum2（借用它）
    print_sum2(&v);
    // v 现在仍然可以被使用
    println!("(2) We still have v: {}, {}, ...", v[0], v[1]);

    // 此时仍可以
    print_sum3(&v);
    println!("(3) We still have v: {}, {}, ...", v[0], v[1]);

    // v 被移除并在此处被释放
}

让我们看看这里发生了什么。第一个函数中，我们可以始终转移所有权，但是我们已经确信有时这并不是我们想要的。

第二个函数中，我们对 vector 进行引用，然后将其传递给函数。和 C 语言很像，我们通过解引用来获取对象。由于没有复杂的生命周期，因此一旦删除引用，借用便会终止。虽然它看起来像第一个示例，但是有一个重要的区别。main 函数拥有 vector 的所有权，在借用 vector 时只能对它做些限制。在这个示例中，main 函数在借用 vector 时甚至没有机会观察向量，因此这没什么大不了的。

第三个函数结合了第一个函数不需要解引用和第二个函数不弄乱所有权的优点。这之所以可行是因为 Rust 的自动解除引用规则。这些有点复杂，但是在大多数情况下，它们可以使你几乎就像使用引用指向的对象一样编写代码，这和 C++ 的引用很相似。

这里是另一个示例：

// 通过不可变引用获取 v
fn count_occurences(v: &Vec<i32>, val: i32) -> usize {
    v.into_iter().filter(|&&x| x == val).count()
}

fn main() {
    let v = vec![2, 9, 3, 1, 3, 2, 5, 5, 2];
    // 为迭代借用 v
    for &item in &v {
        // the first borrow is still active
        // 第一个借用仍生效
        // 我们在这里第二次借用
        let res = count_occurences(&v, item);
        println!("{} is repeated {} times", item, res);
    }
}

你无需关心 count_occurrences 函数内部发生的事情，只需要知道它借用了 vector 即可（再次提醒，没有移动它）。循环也借用了 vector，因此我们有两个借用处于同时活动状态。循环结束后，main 函数将删除 vector。

哈哈，我会有点不地道了。我前面提到多线程是需要引用的主要原因，但是我展示的所有示例都是单线程的。如果你真的有兴趣，可以在 Rust 中获得有关多线程的一些详细信息。

获取和删除引用似乎很有效，好像涉及到垃圾回收一样。但实际并不是这样的。这一切都在编译时完成。为此，Rust 需要另一个神奇的概念。让我们看下以下示例代码：

fn middle_name(full_name: &str) -> &str {
    full_name.split_whitespace().nth(1).unwrap()
}

fn main() {
    let name = String::from("Harry James Potter");
    let res = middle_name(&name);
    assert_eq!(res, "James");
}

这是可以被成功编译的，但下面的代码是无法被编译的:

fn middle_name(full_name: &str) -> &str {
    full_name.split_whitespace().nth(1).unwrap()
}

fn main() {
    let res;
    {
        let name = String::from("Harry James Potter");
        res = middle_name(&name);
        // `name` 在这里被移除并随后被释放
    }
    assert_eq!(res, "James");
}

首先，让我们解释下 string 类型。String 拥有字符串缓冲区，一个 &str（字符串切片）是 String 类型的一段或其他内存的一段（在这里并不重要）。

为了解释地更加明显，我用 C 语言编写类似的内容：

顺便一提：在 C 语言中，你不能获取字符串的中间部分，因为标记字符串的结尾将需要更改字符串，因此我们仅限于在此处查找姓氏。

#include 
#include 
#include 

const char *last_name(const char *full_name)
{
    return strrchr(full_name, ' ') + 1;
}

int main() {
    const char *buffer = strcpy(malloc(80), "Harry Potter");
    const char *res = last_name(buffer);
    free(buffer);
    printf("%s\n", res);

    return 0;
}

你现在明白了吗？在使用结果之前，将删除缓冲区并重新分配缓冲区。这是一个在释放后使用资源的特殊例子。如果 printf 的实现不会立即将内存用于其他用途，则此 C 代码可以编译并运行良好。不过，在一个不那么特殊的示例中，它仍然是崩溃、错误和安全漏洞的来源。正是在介绍所有权之前我们所说的。

你甚至无法在 Rust 中进行编译（我的意思是上面的 Rust 代码）。这种静态分析机制已内置在语言中，并且在整个生命周期可用。

生命周期

资源在 Rust 中是有生命周期的。他们从被创造的那一刻起一直存在到被移除的那一刻。生命周期通常被认为是作用域或代码块，但这实际上并不是一个准确的表述，因为资源可以在代码块之间移动，正如我们已经看到的那样。我们无法引用尚未创建或已删除的对象，我们很快就会看到这个要求是如何被强制执行。否则，这一切看起来都与所有权概念并没有什么不同。

这是比较难理解的一部分。引用以及其他对象也具有生存期，并且这些生存期可能与它们的借用的生存期不同（所谓的关联生命周期）。

让我们来改写下代码。借用的持续时间可能长于它所控制的引用的时间。这通常是因为可以使用另一个引用，该引用取决于借用是否处于活动状态——可以借用相同的对象或只借用其一部分，例如上例中的字符串切片。

实际上，每个引用都会记住它所代表的借用期限，也就是说，每一个引用都有一个生命周期。像所有与“借用检查”相关的事情一样，这是在编译时完成的，并且不占用任何运行时开销。与其他事物不同，你有时必须明确指定生命周期详细信息。

综上所述，让我们用代码深入探讨下：

fn middle_name<'a>(full_name: &'a str) -> &'a str {
    full_name.split_whitespace().nth(1).unwrap()
}

fn main() {
    let name = String::from("Harry James Potter");
    let res = middle_name(&name);
    assert_eq!(res, "James");

    // 不会被编译:

    /*
    let res;
    {
        let name = String::from("Harry James Potter");
        res = middle_name(&name);
    }
    assert_eq!(res, "James");
    */
}

在前面的示例中，我们不必明确地指出生命周期，因为生命周期的细致程度足以让 Rust 编译器自动找出来（请参阅[lifetime elision](https://doc.rust-lang.org/book/lifetimes.html ＃lifetime-elision)）。无论如何，我们已经在这里演示了它们的工作原理。

<> 表示该函数在整个生命周期内都是通用的，我们称其为 a。也就是说，对于具有关联生命周期的任何引用传入，它将返回具有相同关联生命周期的另一个引用。友情提示，关联的生命周期是指借用的生命周期，而不是引用的生命周期。

在实践中，它的含义可能不是显而易见的，所以让我们从相反的角度来看它。返回的引用被存储在 res 变量中，该变量在 main() 的整个范围内都有效。那是引用的生命周期，因此借用（相关的生命周期）至少存在了很长的时间。这意味着函数传入参数的关联生命周期必须相同，因此我们可以得出结论，必须为整个函数借用 name 变量。

在释放后使用的示例中（此处已注释），res 的生命周期仍然是整个函数，而 name 的生存周期没有足够长的时间，以至于借用不能在整个函数中有效。如果你尝试编译此代码，毫无疑问会触发编译错误。

Rust 编译器尝试使借用的生命周期尽可能短，理想情况下，一旦引用被移除就结束了（这是我在借用部分开始时所说的“最简单的情况”）。“借用应有尽可能长的生命周期” 的约束却是以另一种相反的方式运作的，比如从 result 到原始借用的生命周期会延伸地很长。只要满足所有约束条件，此过程就会停止，如果无法实现，则会出错。

你无法欺骗 Rust 让函数的返回的借用的值与生命周期完全无关，因为那样的话，在函数中你将得到相同的 does not live long enough 报错信息，因为不相关的生命周期可能比传入的生命周期长很多。

让我们来看下这个示例：

fn search<'a, 'b>(needle: &'a str, haystack: &'b str) -> Option<&'b str> {
    // 想象这里有一些聪明的算法
    // 返回了一个原始字符串的切片
    let len = needle.len();
    if haystack.chars().nth(0) == needle.chars().nth(0) {
        Some(&haystack[..len])
    } else if haystack.chars().nth(1) == needle.chars().nth(0) {
        Some(&haystack[1..len+1])
    } else {
        None
    }
}

fn main() {
    let haystack = "hello little girl";
    let res;
    {
        let needle = String::from("ello");
        res = search(&needle, haystack);
    }
    match res {
        Some(x) => println!("found {}", x),
        None => println!("nothing found")
    }
    // 输出 "found ello"
}

search 函数接受两个引用，这些引用具有完全不相关的生命周期。尽管 haystack 受到限制，但关于 needle 的唯一要求是在函数本身执行时借用必须有效。完成后，借用立即结束，我们可以安全地重新分配关联的内存，同时仍然保持函数结果不变。

haystack是用字符串字面量初始化的。这些是 &’static str 类型的字符串切片（一个始终有效的借用）。因此我们可以在需要时将 res 变量保持在有效范围内。这是借用期限尽可能短规则的例外。你可以将其视为对“借用字符串”的另一个限制：字符串字面量借用必须持续整个程序的整个执行时间。

最后，我们返回的不是引用本身，而是一个内部的复合对象。这是完全支持的并且不会影响我们的一生逻辑。

因此，在此示例中，该函数接受两个参数，并且在两个生存期内都是通用的。让我们看看如果我们将生命周期设置为相同，会发生什么情况：

fn the_longest<'a>(s1: &'a str, s2: &'a str) -> &'a str {
    if s1.len() > s2.len() { s1 } else { s2 }
}

fn main() {
    let s1 = String::from("Python");
    // 明确借用以确保借入的持续时间长于s2
    let s1_b = &s1;
    {
        let s2 = String::from("C");
        let res = the_longest(s1_b, &s2);
        println!("{} is the longest if you judge by name", res);
    }
}

我在内部代码块之外进行了明确的借用，因此借用会在 main() 的其余部分都有效。这明显和 &s2 的生命周期不一样。如果仅接受两个具有相同生命周期的参数，那么这里为什么可以调用该函数？

事实证明，相关的生命周期会受到类型强制的约束。与大多数语言（至少是我所熟知的那些语言）不同，Rust 中的原始（整数）值不会强制转换，为此你必须始终明确地强制转换它们。你可以在一些不太明显的地方找到强制转换，例如这些关联的生命周期和 dynamic dispatch with type erasure。

我们用 C++ 代码进行比较：

struct A {
    int x;
};

struct B: A {
    int y;
};

struct C: B {
    int z;
};

B func(B arg)
{
    return arg;
}

int main() {
    A a;
    B b;
    /*
     * 这很好用：B值是有效的A值
     * 换句话说，只要期望A值，就可以使用B值
     */
    a = b;
    /*
     * 另一方面，这将是一个错误
     */

    // b = a;

    // 这能很好地工作
    C arg;
    A res = func(arg);
    return 0;
}

派生类型强制为其基本类型。当我们传递 C 的实例时，它强制转换为 B，然后返回，强制转换为 A，然后存储在 res 变量中。

同样，在 Rust 中，更长的借用可以被强制缩短。它不会影响借用本身，而只会在需要较短借用的地方起作用。因此，你可以为函数传递寿命比预期更长的借用（它将被强制执行），并且可以强制将返回的借用的生命周期缩短。

再考虑一下这个示例：

fn middle_name<'a>(full_name: &'a str) -> &'a str {
    full_name.split_whitespace().nth(1).unwrap()
}

fn main() {
    let name = String::from("Harry James Potter");
    let res = middle_name(&name);
    assert_eq!(res, "James");

    // 不会被编译：

    /*
    let res;
    {
        let name = String::from("Harry James Potter");
        res = middle_name(&name);
    }
    assert_eq!(res, "James");
    */
}

人们通常会想知道这样的函数声明是否意味着参数的关联生命周期必须（至少）与返回值一样长，反之亦然。

答案现在应该很明显。对函数来说，两个生命周期完全相同。但是由于可以强制，你可以将其借用更长的时间，甚至可以在获得结果之后缩短结果的关联生命周期。因此正确的答案是参数必须至少与返回值一样长。

而且，如果你创建一个通过引用接受多个参数的函数，并声明它们必须具有相等的关联生命周期（如在我们之前的示例中一样），则该函数的实际参数将被强制为其中最短的生命周期。这只是意味着结果不能超过任何借用的参数。

这与我们之前讨论的反向约束规则可以很好地配合。被调用者并不关心这些-它只是获得并返回相同生命周期的借用。

另一方面，调用者确保参数的关联生命周期永远不会比结果的生命周期短，可以通过扩展它们来实现。

小技巧

你不能移走借用的值，因为在借用结束后该值必须保持有效。即使你在下一行中移回某些内容，也无法将其移出。但是 [mem::replace](https://doc.rust-lang.org/std/mem/fn.replace.html) 特征可以让你同时做这两件事。
如果你想拥有一个像 C++ 中的 unique_ptr 一样的指针，可以使用 [Box](https://doc.rust-lang.org/std/boxed/index.html) 类型。
如果你想进行一些基本的引用计数-例如 C ++ 中的 shared_ptr 和 weak_ptr，可以使用这些标准模块
如果你确实需要摆脱 Rust 所施加的限制，则可以随时求助于 unsafe code

如果发现译文存在错误或其他需要改进的地方，欢迎到掘金翻译计划对译文进行修改并 PR，也可获得相应奖励积分。文章开头的 本文永久链接 即为本文在 GitHub 上的 MarkDown 链接。

掘金翻译计划是一个翻译优质互联网技术文章的社区，文章来源为掘金上的英文分享文章。内容覆盖 Android、iOS、前端、后端、区块链、产品、设计、人工智能等领域，想要查看更多优质译文请持续关注掘金翻译计划、官方微博、知乎专栏。

使用 Jest 和 Enzyme 进行 React Native 单元测试

2023-04-19T09:48:29.000Z

单元测试是什么 🧐

单元测试是用来对一个模块、一个函数或者一个类来进行正确性检验的测试工作。程序单元是应用的最小可测试部件，在 React 编程中，最小单元通常是组件、函数。如果你熟悉“测试驱动开发”（TDD：Test-Driven Development），单元测试也不会陌生，狭义来说就是单测驱动开发。

通常来说，程序员每修改一次程序就会进行最少一次单元测试，在编写程序的过程中前后很可能要进行多次单元测试，以证实程序达到软件规格书要求的工作目标，没有程序错误。在 TDD 中，甚至是先根据设计编写单元测试，然后根据单元测试写代码。

万丈高楼平地起，单元测试和文档一样，是保障程序最小单元质量的重要一环。试想一下，一块砖可能不需要使用说明书就可以量产使用，但是一块砖不经质检测验就投入使用带来的后果可能是恐怖的。从这个角度来看，单测可能是比文档更重要的存在。当然我们也不提倡为了单测而单测，单测是为了防范于未然。

其他测试

前端测试常见的测试类型有单元测试(Unit testing)、集成测试(Integration testing)、端到端(E2E testing)测试，一般我们投入的测试资源排序如下：

集成测试是在单元测试的基础上，集成多个模块进行测试，确保模块之间互动行为正确无误的工作。有时，单一的模块完全通过单元测试，单独使用也没有问题，但是当与其他模块配合使用时，可能就出现问题了，下图是未通过集成测试的例子：

端到端测试是站在用户角度出发（一端）到真实运行环境（另一端）进行测试。一般我们会使用 Cypress、puppeteer 这些工具进行自动化测试以替代人肉测试。下图是未通过端到端测试的例子：

测试覆盖率

我们在测试的时候，会经常关心我们的代码是否都测试到了，以及哪些代码没有测试到。jest 内置了 Istanbul 测试覆盖率工具，我们可以通过四个维度的覆盖率来了解代码测试覆盖率情况：

Statements（stmts）：表达式覆盖率，是不是每个表达式都执行了？
Branches（Branch）：分支覆盖率，是不是每个 if 代码块都执行了？
Functions（Funcs）：函数覆盖率，是不是每个函数都调用了？
Lines（Lines）：行覆盖率，是不是每一行都执行了？

下图是执行 jest --coverage 之后生成的命令行输出：

下图是生成的精美的测试覆盖率报告：

点击 App.js 可以查看单个文件的测试覆盖率情况：

点开每个也没你，你会看到页面是五颜六色的，别担心，这些颜色都是有明确的意义：

粉紅色的代码: 尚未被执行的 statement 或 function
黄色的代码: 沒被覆盖到的 branch
I: 代表 if-else 的 if 没有被执行
E: 代表 if-else 的 if 没有被执行
Nx: 代表代码块被执行到的次数，可以作为代码性能的参考依据

安装依赖

$ yarn add jest -D
# babel
$ yarn add babel-jest -D
# enzyme
$ yarn add enzyme jest-enzyme enzyme-adapter-react-16 enzyme-to-json -D
# react-native-mock-render
$ yarn add react-native-mock-render -D
# types
$ yarn add @types/enzyme @types/jest @types/react @types/react-native -D

工具介绍：

jest: Jest 是一个令人愉快的 JavaScript 测试框架，专注于简洁明快。
enzyme: Enzyme 是用于 React 的 JavaScript 测试实用程序，可以更轻松地测试 React 组件的输出。您还可以根据给定的输出进行操作，遍历并以某种方式模拟运行时。
jest-enzyme: 针对 enzyme 的 Jest 断言
enzyme-adapter-react-16: React Native 测试所需的桥接器
enzyme-to-json: 将 Enzyme wrappers 转换成符合 Jest 快照测试的 JSON 格式。
react-native-mock-render: A fully mocked and test-friendly version of react native

配置

jest.config.js

module.exports = {
  preset: 'react-native',
  verbose: true,
  collectCoverage: true,
  moduleNameMapper: {
    // for https://github.com/facebook/jest/issues/919
    '^image![a-zA-Z0-9$_-]+$': 'GlobalImageStub',
    '^[@./a-zA-Z0-9$_-]+\\.(png|gif)$': 'RelativeImageStub',
  },
  setupFilesAfterEnv: ['/jest.setup.js'],
  snapshotSerializers: ['enzyme-to-json/serializer'],
};

collectCoverage: 生成测试覆盖率报告
setupFilesAfterEnv: 使用 Jest 运行安装文件以配置 Enzyme 和适配器（如下文jest.setup.js中所示），之前是setupTestFrameworkScriptFile，也可以使用setupFiles
snapshotSerializers：推荐使用序列化程序使用enzyme-to-json，它的安装和使用非常简单，并允许您编写简洁的快照测试。

注意：Jest 在 24.1.0 之后只能使用 setupFilesAfterEnv

jest.setup.js

import 'react-native';
import 'react-native-mock-render/mock';
import 'react-native/Libraries/Animated/src/bezier'; // for https://github.com/facebook/jest/issues/4710
import Enzyme from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';

Enzyme.configure({ adapter: new Adapter() });

enzyme 入门

enzyme 是 Airbnb 开源的 react 测试类库，提供了一套简洁强大的 API，并通过 jquery 风格的方式进行 dom 处理，开发体验十分友好. 它提供三种测试方法.

shallow

shallow 返回组件的浅渲染，对官方 shallow rendering 进行封装。浅渲染作用就是：它仅仅会渲染至虚拟 dom，不会返回真实的 dom 节点，这个对测试性能有极大的提升。shallow 只渲染当前组件，只能能对当前组件做断言

mount

mount 方法用于将 React 组件加载为真实 DOM 节点。mount 会渲染当前组件以及所有子组件。多数情况下，shallow 方法就能满足我们的需求了。ref 测试则旨在 mount 模式下生效。

render

render 采用的是第三方库 Cheerio 的渲染，渲染结果是普通的 html 结构，对于 snapshot 使用 render 比较合适。

组件测试

组件快照测试

当我们要确保 UI 不会意外更改时，快照测试都是非常有用的工具。通过 toMatchSnapshot 即可完成。

describe('Button Component', () => {
  it('basic render', () => {
    const component = renderer.create(<Button />).toJSON();
    expect(component).toMatchSnapshot();
  });
});

生命周期测试

componentDidMount

通过调用 shallow 和 mount 方法，可以触发 componentDidMount 生命周期：

import { shallow } from 'enzyme';

function setup(props = {}) {
  const wrapper = shallow(<CarouselComponent />);
  const instance = wrapper.instance();
  return { wrapper, instance };
}

describe('Carousel Component', () => {
  it('renders correctly', () => {
    setup();
  });
});

也可以通过 wrapper.setState 方法进行触发：

import { shallow } from 'enzyme';

function setup(props = {}) {
  const wrapper = shallow(<Component {...props} />);
  const instance = wrapper.instance();
  return { wrapper, instance };
}

describe('Component', () => {
  it('renders correctly', () => {
    const { wrapper } = setup();
    wrapper.setState({
      enable: true,
    });
  });
});

componentWillUnMont

通过调用 wrapper.unmount() 可以触发 componentWillUnMont 生命周期：

import { shallow } from 'enzyme';

function setup(props = {}) {
  const wrapper = shallow(<Component />);
  const instance = wrapper.instance();
  return { wrapper, instance };
}
describe('Carousel Component', () => {
  it('renders correctly', () => {
    const { wrapper } = setup();
    expect(wrapper).toMatchSnapshot();
    wrapper.unmount();
    expect(wrapper).toMatchSnapshot();
  });
});

componentWillReceiveProps

可以通过 wrapper.setProps 方法触发：

import { shallow } from 'enzyme';

function setup(props = {}) {
  const wrapper = shallow(<Component {...props} />);
  const instance = wrapper.instance();
  return { wrapper, instance };
}

it('componentWillReceiveProps', () => {
  const { wrapper, instance } = setup({
    autoplay: true,
  });
  wrapper.setProps({ autoplay: false });
});

定时器模拟（Timer Mocks）

原生定时器功能(即 setTimeout，setInterval，clearTimeout，clearInterval)对于测试环境来说不太理想，因为它们依赖于实时时间。
Jest 可以将定时器换成允许我们自己控制时间的功能。

这里我们通过调用 jest.useFakeTimers() 来启用假定时器。然后在需要的时候执行 jest.runOnlyPendingTimers() 来触发定时器：

import { shallow } from 'enzyme';

jest.useFakeTimers();

it('autoplay methods with count(2) and os(ios)', () => {
  const { wrapper, instance } = setup({
    autoplay: true,
    loop: false,
  });
  wrapper.setState({ isScrolling: true }, () => {
    jest.runOnlyPendingTimers();
  });
});

FAQ

如何忽略某一块代码

添加以下格式的注释到要忽略的代码块前即可：

1	/* istanbul ignore next */

使用 mount 时，忽略 React Native 的警告

参考自：Remove warnings when rendering react-native components

describe('mounting', () => {
    const origConsole = console.error;
    beforeEach(() => {
      console.error = () => {};
    });
    afterEach(() => {
      console.error = origConsole;
    });
    it ......
       mount....
});

紫升的博客

HyperFrames 的原理：让 HTML 成为可寻址的视频时间线

一句话总结

先分清三个对象：composition、clip 和 timeline

HTML 为什么适合做视频的源代码

最关键的原理：seek，而不是播放

不能读取真实时钟

随机数必须可复现

无限循环必须有边界

媒体为什么必须由框架接管

两层结构：声明层和表现层

子 composition 解决的是复用，不是逃避时间

从原理推导出的验证顺序

三个看似合理、实际危险的做法

把 HyperFrames 当成录屏器

用 timeline 控制视频播放

只验证“浏览器里看起来对”

要不要用 / 我的判断框架

Bearer Token Authentication 到底是什么：从 Authorization Header 到安全验证

一句话总结

Bearer 到底是什么意思

正确的请求格式

Bearer、JWT、OAuth 2.0 不是同一个概念

Bearer 与其他鉴权方式有什么区别

一次完整的 Access Token 生命周期

1. Client 获取 Access Token

2. Client 调用 Resource Server

3. Resource Server 验证 Token

4. Resource Server 返回标准错误

Node.js 实战：验证 JWT Bearer Token

1. 安装依赖

2. 编写 Bearer Middleware

3. 增加 Scope 授权

4. 验证三条关键分支

生产环境最容易犯的错误

把 JWT Decode 当成 Verify

把 Token 放进 URL

让 Access Token 永不过期

只验证“有效”，不验证“给谁”

在日志里打印整个 Header

用设备 ID 代替 Bearer Token

2026 年还要继续用 Bearer Token 吗

要不要用：我的判断框架

值得用

可以简化

需要升级

参考资料

从 rcedit 到 resedit：给 Bun 单文件 EXE 修改 VERSIONINFO 的兼容层设计

一句话总结

Windows PE 是什么

RVA 和磁盘 offset 不是一回事

VERSIONINFO 保存了什么

为什么 Bun 让迁移复杂了一步

兼容层的设计：先定义不能变的东西

第一步：记录布局快照

第二步：只绕过一个已知假设

第三步：写入后逐项比对

测试不能只看文件属性页

构建工具和发行版应该怎么分工

要不要用：我的判断框架

值得迁移到 resedit

可以直接使用 Bun 参数

需要停下来审计

参考资料

Windows 下 AI 浏览器的最佳启动参数配置

一句话总结

为什么 AI 浏览器更不能把参数堆在快捷方式里

三套 Profile：先分场景，再选参数

参数矩阵：哪些能用，哪些只该出现在实验里

GPU：先让 Chromium 自己判断，再做单变量实验

Sandbox：任何正式入口都不该关闭

Remote Debugging 与 User Data Directory 必须成对管理

Proxy 与证书：保留真实的 Windows 信任边界

Logging 与 Crash：收集证据，不要长期改变运行模式

V8 Heap：4096 不是 AI 浏览器的默认答案

三套可直接落地的配置

Production：快捷方式只指向 EXE

Internal Diagnosis：隔离 Profile，加最少日志

Automation/Eval：让 Harness 拥有调试通道

两种最常见的错误配置

V8 Heap：`4096` 不是 AI 浏览器的默认答案

`darwin` 为什么代表 macOS

`win32` 为什么也会出现在 64-bit Windows 上

`linux` 只是第一层，后面往往还要看 libc

`x86`、`x64`、`amd64`、`x86_64` 为什么像一组近义词

`x86` 来自一串以 86 结尾的处理器

`arm64` 与 `aarch64` 又是什么关系