AI 编程

我用agent做了个运动打卡数据治理流程

Gyrate — Sat, 08 Aug 2026 07:26:01 GMT

介绍

公司举办了一项运动打卡活动，报名成员每天完成运动后，会把运动 App 截图和相关说明发到运动聊天群。工作人员需要定期整理群里的打卡记录，统计每位成员的运动时间和运动时长。

随着群聊资料不断增加，人工逐张查看截图、判断有效记录和抄录数据会花费不少时间。如何减少这些重复工作，快速得到可以统计的运动打卡数据，就是这次要解决的问题。

为此，我做了一套运动打卡数据处理流程。它会下载群聊归档，识别截图和上下文，整理成结构化数据，再把异常记录交给人工核查。最近我又用 TRAE Work 在 sportcheckin 工程中完整跑了一遍这套流程，确认 Agent 可以完成资料下载、内容识别和数据输出。

主要痛点

原来的做法是人工逐张看图。管理员需要一张张图片，再判断图片是不是运动记录，抄下运动时间和时长，最后汇总统计。难点不在单张截图，而在这些细节会叠在一起。

不同运动 App 的版式不同，人眼识别有概率出错
运动时间和发送到群里的提交时间可能不同需要人工甄别
群里有补交、重复图、排行榜和普通聊天内容需要人工甄别
如果还想统计运动类型、卡路里，人工录入的工作量会继续上涨

要解决的问题

我需要做的事情是把每天群里哪些繁杂的聊天记录整理为一个结构化、可追溯的数据表，我的同事已经开发了工具，可以每天定时把聊天内容图文上传内部云盘，我只要通过API下载文件，并输出分析后的干净数据即可。

我要拿到的不只是一张总表。每条记录要保留各种运动信息、原图地址、人工核查状态。最后输出 CSV格式的文件、识别报告和待人工复核清单。一开始我以为只要做个工具获取聊天记录docx 丢给 AI，让它直接输出表格就行。结果跑起来才发现，图片多时速度慢，中间哪里错了也不好找，后面人工复核更没法追溯。

所以调整了工作流程，给 TRAE Work 下发任务前，没有写成一句“帮我整理运动记录”，而是先把我具体的需求，输入、输出和异常规则说清楚。

请处理指定日期范围内的运动群归档文件。

任务要求
1. 通过API下载并整理 docx 中的文字、图片、发送人和发送时间
2. 识别有效运动打卡，忽略闲聊、排行榜和无关图片
3. 输出运动时间、提交时间、人员、运动类型、运动时长、卡路里、原图路径和核查状态
4. 对重复记录、时间不完整、字段冲突和低置信内容标记为待核查
5. 输出 records.csv 与 evidence.md

处理原则
- 不确定时不要猜测，不要写入正式数据
- 每条记录必须保留可回看的原图或来源位置
- 运动时间和提交时间分开保存

核心思路

这个流程最核心的工作，就是识别出聊天内容中的运动记录。

我之前用同一份含 13 张图片的 docx 做过测试。全量视觉识别加大模型理解，识别效果很好，但耗时约 30 分钟，测试成本约 1.63 美元。改成 OCR 先读取文字，再交给大模型整理，同一份资料约 2 分钟，成本约 0.42 美元，不过出现了两处数据错误。

对比之下，全部使用AI大模型视觉识别通过率高（但不代表正确率100%），但费用高不可持续；使用OCR识别成本低，但通过率没那么高。事实上做数据的整理如果单纯只做图片识别还是非常容易把数据搞错，因为活动成员做打卡时有可能发送重复app截图，或者直发现场照片加文字描述，并不会有app截图。

后来我把处理流程再收紧了一步。OCR 负责识别文字、数字。AI 负责理解字段含义和聊天上下文。OCR 缺字、错位、冲突或置信不足时，Agent 先写入待复核清单。人工确认需要补看原图后，才启用大模型视觉识别做二次修订。

这套分工解决了两个问题。大部分规则化截图不必都走昂贵的视觉理解，复杂图片也不会因为 OCR 读错一个数字就直接写进结果。

比如一张截图里 OCR 已经读出“跑步 46 分钟、326 千卡”，AI 可以结合图片版式和同一条消息的上下文，判断哪一个是运动时间，哪一个只是提交时间。若 OCR 把 8:36 读成了不完整的时间，或卡路里字段没有读出，Agent 会把这一行标成待核查。人工确认需要处理后，才让视觉识别回看原图补齐字段。

具体操作步骤

第一步　让 TRAE Work 下载资料、识别数据并生成 CSV

我先在 TRAE Work 中打开 sportcheckin 工程，用自然语言告诉 Agent 要处理的日期范围。Agent 会按指令下载对应的群聊记录，读取聊天文本和运动截图，再结合提交人的上下文整理运动数据。

处理完成后，Agent 会生成 records.csv，同时输出识别摘要、来源信息和过滤诊断。CSV 是后续入库和统计的统一输入，每一行仍然能够追溯到原始聊天记录与截图。

第二步　导入数据库并完成人工核查

生成 CSV 后，我把数据导入 sportcheckin 的数据管理系统，这个小小的系统也是vibe coding生成的。系统支持把已核查记录和待核查记录分开，管理员只需要集中处理缺失、冲突和低置信度的数据，不必重新翻完整的群聊记录。

核查页面会把原图、识别字段和异常原因放在一起。管理员可以对照截图修改运动时间、时长、人员等字段，再确认核查结果，如果有问题可以马上修改。当然如果下载数据和核查数据是同个人，我会建议优先在上一步，下载数据阶段就直接核查了。

第三步　展示统计结果

完成核查后，系统基于数据库中的有效记录生成报表。页面可以查看总体打卡情况，也可以按人员筛选，并通过排行榜快速了解参与情况。后续新增的数据只要经过同一套入库和核查流程，报表就能继续更新。

第四步　通过智能问数继续分析

拿到治理并经过人工确认的数据后，就可以继续做智能问数。问数的入口并不固定。可以把数据库的只读 API、调用方式和字段说明提供给 TREA WORK等agent，让agent按问题获取数据，直接在对话中完成查询和汇总、提供运动建议。也可以把相同的能力接入钉钉机器人，再把机器人放进运动群。群成员直接提问，就能查看个人运动信息、运动趋势分析。

TREA Work上问数

钉钉群里问数

成效如何

目前为止已经创建了1210 条运动记录，累计运动 65588 分钟，约 1093.1 小时。使用这套流程以前，负责这项工作同事需要逐张查看运动截图，再手工填写和汇总表格，每周统计一次大约需要 60 分钟。

现在由 Agent 先下载资料、识别截图并整理 CSV，人工只处理异常记录和最终核查，每周大约需要 10 到 20 分钟，耗时下降比例|约 67% 到 83%。说实话这个流程也不是一蹴而就的，开发初期也是遇到各种规则意外的问题，导致识别异常，感谢我的同事陪我跑了好几轮的迭代才发识别通过率慢慢提升到了接近100%。

如何复用

运动打卡只是一个输入比较杂的例子，关键方法可以迁移到其他“图片多、规则明确、又需要留痕”的工作。

财务整理发票图片，读取号码、日期、金额和税额，再交给财务确认
行政整理巡检照片，提取地点、时间和异常描述
项目组处理物流回单或合同扫描件，先形成结构化台账
运营团队归档报名表和聊天记录，先把重复、缺失和冲突标出来

这些场景都不适合把 AI 当成自动盖章工具。更稳的做法，是让它先做文件整理、文字读取、字段抽取和异常标记，人把精力放在少量需要判断的地方。

总结

这次实践让我更清楚地看到，AI 能不能进入真实工作，首先取决于人是否理解业务。哪些记录可以采用，哪些数据必须核查，出现缺失和冲突时怎样处理，这些规则需要人来确定。规则说清楚以后，AI 才能稳定地接手下载、识别、整理和统计这些重复工作。

TRAE Work 给我留下较深印象的地方，是它没有把工作停在一段建议或一份示例代码上。它可以进入已有工程，读取项目约定，调用现成工具，再把处理结果写回文件。整个过程中它确实是个实干助手，我负责说明业务目标、检查结果和修正规则，它负责把中间那些具体而繁琐的步骤跑完。

运动打卡只是一个很小的场景，却包含了许多真实业务都会遇到的问题。原始资料分散，图片版式不一，识别结果可能出错，最终数据还要能够追溯。把这些问题处理好以后，统计报表和智能问数才能建立在可信的数据上。

echoVic — Sat, 08 Aug 2026 07:22:02 GMT

解剖 Claude Code：从入口架构逆向工程看 AI 编程工具的信任边界设计

iDao技术魔方 — Sat, 08 Aug 2026 07:17:08 GMT

想了解一个 AI 编程工具的真实水平，有两条路：读它的文档，或者读它的代码。文档写的是意图，代码才是现实，两者之间往往隔着好几轮产品妥协。

这篇文章走的是第二条路。解剖对象是 Claude Code v2.1.88 的源码（仓库：github.com/wjszxli/claude-code），分析方法有三种：架构解构法——从入口点反推设计意图；工程度量法——用代码规模和组织方式评估复杂度治理；对比参照法——把它放进 VSCode Copilot、Cursor、GitHub CLI 的坐标系里看取舍。三种方法各解剖一次，一个更完整的图景会自己浮出来。

但解剖本身不是目的。这篇文章真正想回答的问题是：当一个工具被赋予了执行命令、读写文件、发起网络请求的能力时，它的设计者如何划定"信任半径"？ Claude Code 的答案，藏在 643 行入口代码和一条 1778 行的路径检查文件里。

一、架构解构法：入口文件是一个无法自欺的地方

cli.tsx：一个被伪装成入口的路由表

打开 src/entrypoints/cli.tsx，只有 30 行。它的函数注释把设计意图写得很坦白：

/**
 * Bootstrap entrypoint - checks for special flags before loading the full CLI.
 * All imports are dynamic to minimize module evaluation for fast paths.
 * Fast-path for --version has zero imports beyond this file.
 */

这个文件做的事只有一件：在加载完整 CLI 之前，先检查 argv 里有没有特殊标志。里面藏着十几条快速路径：--version、--dump-system-prompt、--claude-in-chrome-mcp、--chrome-native-host、--computer-use-mcp、--daemon-worker、remote-control（桥接模式）、daemon（常驻监督进程）、ps/logs/attach/kill（后台会话管理）、new/list/reply（模板任务）、environment-runner、self-hosted-runner、--tmux --worktree 组合，最后才是默认路径——加载 main.js，进入完整 CLI。

这个结构透露的信息比表面多。Claude Code 不是一个程序，而是一组共享同一个二进制的进程家族：交互式 REPL、MCP 服务器、远程桥接、常驻守护、无头运行器，全都从同一个 claude 命令分叉出去。入口文件是这个家族的总开关。

每条快速路径的实现方式都一样：

// Fast-path for --version/-v: zero module loading needed
if (args.length === 1 && (args[0] === '--version' || args[0] === '-v' || args[0] === '-V')) {
  console.log(`${MACRO.VERSION} (Claude Code)`);
  return;
}

查版本号不加载任何额外模块，打印完直接返回。其他路径稍重一点，但也都用 await import() 现场加载，不用不引。对一个 CLI 工具来说，这个选择很务实：用户大量调用发生在脚本和快捷键里，启动开销是按毫秒被感知的。

文件最顶部还有三件事，排在 main() 之前：

import "../macro-shim";
import { feature } from 'bun:bundle';

// Bugfix for corepack auto-pinning, which adds yarnpkg to peoples' package.jsons
process.env.COREPACK_ENABLE_AUTO_PIN = '0';

// Set max heap size for child processes in CCR environments (containers have 16GB)
if (process.env.CLAUDE_CODE_REMOTE === 'true') {
  const existing = process.env.NODE_OPTIONS || '';
  process.env.NODE_OPTIONS = existing ? `${existing} --max-old-space-size=8192` : '--max-old-space-size=8192';
}

宏填充、Corepack 修复、容器环境的堆内存上限，没有一件是业务逻辑。终端工具的处境就是这样：它会被装进 Docker 容器、CI 流水线、SSH 会话和千奇百怪的本地环境里，启动代码必须先替这些环境扫雷，才轮得到功能登场。

feature()：编译时就把代码删掉

入口文件里反复出现的 feature() 来自 bun:bundle，是 Bun 的编译时特性标志。它和运行时的 if (config.xxx) 有本质区别：构建产物里根本不包含被关掉的分支。以 --dump-system-prompt 为例：

// Fast-path for --dump-system-prompt: output the rendered system prompt and exit.
// Used by prompt sensitivity evals to extract the system prompt at a specific commit.
// Ant-only: eliminated from external builds via feature flag.
if (feature('DUMP_SYSTEM_PROMPT') && args[0] === '--dump-system-prompt') {

注释写得很直白：这条路径给内部的提示词敏感性评估用，外部构建里会被 DCE（死代码消除）整个删掉。全仓库数下来，不同的 feature('XXX') 标志有 89 个。也就是说，Claude Code 的发布策略是"一套源码，多个产物"：内部版本、外部版本、不同客户版本，从同一份代码裁剪出来，裁剪发生在字节层面而不是配置层面。外部用户拿到的二进制里，这些功能连字符串都不存在，反编译也找不到。

这不是一个"性能优化"级别的决策，而是一个安全决策。运行时开关是"门锁上了但钥匙还在房间里"，编译时裁剪是"房间直接拆了"。内部调试命令、实验性功能、研发专用路径——这些东西留在外部二进制里，哪怕用 if (false) 包着，也仍然是攻击面：它可以被逆向、被 patch、被环境变量意外激活。编译时删除意味着攻击面在产物层面就归零。

ABLATION_BASELINE：为什么这段代码必须放在入口

入口文件里最值得细读的是这段：

// Harness-science L0 ablation baseline. Inlined here (not init.ts) because
// BashTool/AgentTool/PowerShellTool capture DISABLE_BACKGROUND_TASKS into
// module-level consts at import time — init() runs too late. feature() gate
// DCEs this entire block from external builds.
if (feature('ABLATION_BASELINE') && process.env.CLAUDE_CODE_ABLATION_BASELINE) {
  for (const k of ['CLAUDE_CODE_SIMPLE', 'CLAUDE_CODE_DISABLE_THINKING', 'DISABLE_INTERLEAVED_THINKING', 'DISABLE_COMPACT', 'DISABLE_AUTO_COMPACT', 'CLAUDE_CODE_DISABLE_AUTO_MEMORY', 'CLAUDE_CODE_DISABLE_BACKGROUND_TASKS']) {
    process.env[k] ??= '1';
  }
}

"Ablation"（消融）是机器学习的实验方法：逐个摘掉组件，看性能掉多少，以此衡量每个组件的贡献。这段代码就是一个内置的 L0 基线开关：设一个环境变量，就把思考、上下文压缩、自动记忆、后台任务全部关掉，让 Claude Code 退化成最朴素的问答循环，作为实验对照组。

产品代码里内嵌实验对照组，这本身就说明团队在系统地度量"每个智能功能到底值多少"。但更有意思的是注释解释的位置约束：为什么放在 cli.tsx 而不是 init.ts？因为 BashTool 等模块在 import 时就把 DISABLE_BACKGROUND_TASKS 读进了模块级常量，init() 运行时木已成舟。一个看似随意的代码位置，背后是对 ES 模块求值顺序的精确计算。读这种注释，比读任何设计文档都更能看清一个团队的真实水平——他们理解自己的运行时，精确到模块加载的顺序。

init.ts：启动决策链就是信任决策链

main() 进入完整 CLI 后，真正的初始化在 src/entrypoints/init.ts，57 行，被 memoize 包裹保证只执行一次。它的步骤顺序值得逐步看，因为顺序本身就是设计：

export const init = memoize(async (): Promise<void> => {
  try {
    enableConfigs()
    // Apply only safe environment variables before trust dialog
    // Full environment variables are applied after trust is established
    applySafeConfigEnvironmentVariables()
    // Apply NODE_EXTRA_CA_CERTS from settings.json to process.env early,
    // before any TLS connections. Bun caches the TLS cert store at boot
    // via BoringSSL, so this must happen before the first TLS handshake.
    applyExtraCACertsFromConfig()

第一步是配置系统，但紧接着的动作很有讲究：先只应用"安全"的环境变量，完整环境变量要等用户通过信任对话框之后才应用。CA 证书配置则要赶在第一次 TLS 握手之前，因为 Bun 启动时就用 BoringSSL 缓存了证书库，错过时机再设就没用了。三步操作，一步是安全分区，一步是运行时约束。

往下是网络层的准备：

    configureGlobalMTLS()
    configureGlobalAgents()
    // Preconnect to the Anthropic API — overlap TCP+TLS handshake
    // (~100-200ms) with the ~100ms of action-handler work before the API
    // request.
    preconnectAnthropicApi()

配好 mTLS 和代理之后，趁命令处理器还在做大约 100ms 的准备工作，提前对 Anthropic API 发起 TCP+TLS 握手，把 100~200ms 的网络建联藏进这段空档里。注释还补了一句：走代理、mTLS 或云厂商网关时跳过预热，因为 SDK 的 dispatcher 在那些情况下复用不了全局连接池。优化做到这个颗粒度，前提是对自己运行环境的每一种变体都摸过底。

init.ts 里还有一类容易被略过的代码：失败处理。以 CCR 环境的上游代理为例：

    if (isEnvTruthy(process.env.CLAUDE_CODE_REMOTE)) {
      try {
        const { initUpstreamProxy, getUpstreamProxyEnv } = await import(
          '../upstreamproxy/upstreamproxy.js'
        )
        // ...
        await initUpstreamProxy()
      } catch (err) {
        logForDebugging(
          `[init] upstreamproxy init failed: ...; continuing without proxy`,
          { level: 'warn' },
        )
      }
    }

代理初始化失败，记一条 warn 日志，继续启动。这叫 fail-open：代理是增强项不是命脉，它挂了不该拖死整个工具。启动路径上哪些组件允许 fail-open、哪些必须 fail-closed（比如配置解析失败会直接弹错误对话框），是一个工具成熟度的直接体现。

最后是遥测。遥测的初始化不在 init() 里，而是单独一个函数：

/**
 * Initialize telemetry after trust has been granted.
 * ...
 * This should only be called once, after the trust dialog has been accepted.
 */
export function initializeTelemetryAfterTrust(): void {

遥测等信任确立之后才启动，而且实现上把 OpenTelemetry 加 protobuf 约 400KB 的模块延迟到真正启用时才加载，gRPC 导出器的约 700KB 再往后延。注释里连字节数都标了，说明这些延迟是算过账的，不是顺手为之。

这里藏着一个值得单拎出来的设计哲学：信任不是全有全无的开关，而是一个分阶段建立的过程。 第一阶段，进程启动，只应用"安全"的环境变量——这些变量即使被恶意注入也不会造成损害；第二阶段，用户通过信任对话框，建立对工作目录的信任；第三阶段，信任确立后，才应用完整环境变量、启动遥测。每一个阶段对应一个信任层级，每一层授予的能力恰好匹配该层级的风险敞口。这就是"安全分区"（security partitioning）在启动序列里的具体实现。

从入口层能确认的几件事

把 cli.tsx 和 init.ts 合起来，能确认的工程事实如下：

代码证据	对应的工程决策
`--version` 零导入返回	高频轻操作不触发全量初始化
十几条快速路径共用入口	单二进制多进程角色，按需分叉
89 个 `feature()` 编译时标志	一套源码裁剪出多个发布产物
消融基线内嵌在入口	智能功能逐个接受实验度量
安全环境变量先于信任对话框	信任边界切进启动顺序
遥测在信任之后、延迟 400KB+	隐私承诺和启动性能一起落地
API 预连接复用 100ms 空档	网络建联藏进准备工作的间隙
上游代理 fail-open	增强组件不许拖死主流程

这八条里没有一条来自官方宣传，全是入口层 643 行代码里的实际行为。这也是"从入口读起"这个方法的价值：入口文件是一个系统里少有的、无法自欺的地方。所有路径从这里出发，所有环境假设在这里摊开。

二、工程度量法：复杂度治理的六个侧面

src/ 下有 35 个一级目录。挑重点的几个：

src/
├── entrypoints/    # 4 个入口文件 + SDK 子目录
├── commands/       # 88 个子目录 + 15 个文件，用户侧命令
├── tools/          # 46 个子目录，智能体可调用的工具
├── services/       # 21 个子目录 + 16 个文件，业务服务层
├── components/     # 31 个子目录 + 113 个文件，Ink TUI 组件
├── utils/          # 31 个子目录 + 299 个文件，最大的目录（约 18 万行）
├── hooks/          # 83 个文件，生命周期钩子
├── ink/            # 自研终端渲染引擎（约 2 万行）
├── bridge/         # 远程桥接模式
├── coordinator/    # 多代理协调
├── tasks/          # 后台任务系统
├── voice/          # 语音模式
├── skills/         # 技能加载与解析
├── plugins/        # 插件系统
└── ...             # state / schemas / types / vim / memdir 等

几个数字值得注意。commands/ 和 tools/ 是两组不同的概念：88 个命令目录面向用户（claude config、claude diff……），46 个工具目录面向模型（FileReadTool、BashTool、WebSearchTool……）。人走前门，AI 走后门，两个入口各自演化。 一条命令可以触发多个工具，一个工具也会被多条命令和纯对话路径复用。

ink/ 目录单列值得强调：Claude Code 没有用第三方的 Ink（React for CLI），而是自己维护了一套约 2 万行的终端渲染引擎。bridge/、coordinator/、voice/ 这些目录则说明它早已超出"终端聊天工具"的范畴，覆盖了远程控制、多代理、多模态交互——叫它"终端智能体平台"更准确。

大文件分布：复杂度淤积在接缝处

按行数排出最大的七个文件：

文件	行数	职责
`cli/print.ts`	5594	非交互输出管道
`utils/messages.ts`	5512	消息类型与转换
`utils/sessionStorage.ts`	5105	会话持久化
`utils/hooks.ts`	5022	钩子编排
`screens/REPL.tsx`	5005	交互主界面
`main.tsx`	4684	完整 CLI 装配
`utils/bash/bashParser.ts`	4436	Bash 命令解析

看这份榜单比看平均数有用。最大的文件没有一个是"业务功能"，全部是接缝层：渲染管道、消息协议、会话存储、界面装配、shell 语法解析。这是大代码库的典型淤积规律——边界翻译层的复杂度随两边系统的演化持续增长，又很难拆分，因为拆开后每一半都得带着对方的上下文才能看懂。bashParser.ts 尤其说明问题：为了安全地判断一条 bash 命令想干什么，Claude Code 自己实现了 4400 行的 shell 语法解析器。这个投入的回报，后面讲权限系统时还会算到。

commands.ts：755 行的命令装配车间

src/commands.ts 负责把所有命令来源装配成一个列表。源码里能清楚看到三层机制：

// 第一层：编译时裁剪。feature() 为 false 时，对应 require 整段消失
const proactive = feature('PROACTIVE') || feature('KAIROS')
  ? require('./commands/proactive.js').default
  : null

// 第二层：内部命令，仅 USER_TYPE === 'ant' 的构建可见
export const INTERNAL_ONLY_COMMANDS = [
  backfillSessions, breakCache, bughunter, ...
]

// 第三层：磁盘命令源，并行加载，按 cwd 记忆化
const loadAllCommands = memoize(async (cwd: string): Promise<Command[]> => {
  const [
    { skillDirCommands, pluginSkills, bundledSkills, builtinPluginSkills },
    pluginCommands,
    workflowCommands,
  ] = await Promise.all([
    getSkills(cwd),
    getPluginCommands(),
    getWorkflowCommands ? getWorkflowCommands(cwd) : Promise.resolve([]),
  ])
  return [
    ...bundledSkills,
    ...builtinPluginSkills,
    ...skillDirCommands,
    ...workflowCommands,
    ...pluginCommands,
    ...pluginSkills,
    ...COMMANDS(),
  ]
})

三层各管一件事。feature() 在编译时把实验性命令从产物里删掉；INTERNAL_ONLY_COMMANDS 把研发调试命令隔离在内部构建里，外部用户连名字都看不到；memoize + Promise.all 则处理运行时成本——技能、插件、工作流都要读磁盘，缓存到 cwd 级别，并行加载。

命令列表上方还有一段注释值得引：

/**
 * Returns commands available to the current user. The expensive loading is
 * memoized, but availability and isEnabled checks run fresh every call so
 * auth changes (e.g. /login) take effect immediately.
 */

加载可以缓存，权限判断必须每次重算，因为用户可能中途 /login。性能和正确性的分界线划在哪里，这段注释交代得很清楚。命令空间因此能同时容纳内置命令、技能命令、插件命令、工作流命令和内部命令五种租户，各走各的可见性规则。

Tool 接口：46 个工具共用一套契约，默认不信任

46 个工具目录能并行生长，靠的是 src/Tool.ts 里的统一接口。它的几个关键字段：

readonly inputSchema: Input                        // Zod 校验模式
isConcurrencySafe(input: z.infer<Input>): boolean  // 能否与其他工具并行
isReadOnly(input: z.infer<Input>): boolean         // 是否只读

接口设计里最妙的是默认值。源码里 buildTool() 的注释写明：

 * - `isConcurrencySafe` → `false` (assume not safe)
 * - `isReadOnly` → `false` (assume writes)

不声明并发安全就按不安全处理，不声明只读就按会写处理。默认不信任，声明才放行。 这让工具作者想偷懒的代价是失去并行调度的资格，而不是获得它。方向对了，46 个工具自治生长才不会变成安全债。

这个"默认不信任"（default-deny）模式值得单独展开。在传统插件生态里，常见的做法是"默认放行，遇到问题再收紧"——结果就是生态越繁荣，安全水位越低。而 Claude Code 把默认值设成最保守的那个：你什么都没说，我就当你既不能并行、又可能写入。代价是工具作者必须多写两行声明，收益是整个调度器和权限系统可以信任"未声明 = 不安全"这个前提。在一个 AI 工具里，这个前提尤其重要：因为工具的调用者不是人类而是模型，模型不会像人一样"看情况"，它只会严格按照声明行事。

BashTool/prompt.ts：369 行的工具说明书

src/tools/BashTool/prompt.ts 有 369 行，主体不是逻辑，是给模型看的操作手册：

export function getSimplePrompt(): string {
  const toolPreferenceItems = [
    `File search: Use ${GLOB_TOOL_NAME} (NOT find or ls)`,
    `Content search: Use ${GREP_TOOL_NAME} (NOT grep or rg)`,
    `Read files: Use ${FILE_READ_TOOL_NAME} (NOT cat/head/tail)`,
    `Edit files: Use ${FILE_EDIT_TOOL_NAME} (NOT sed/awk)`,
    // ...
  ]

手册细致到什么程度？git 协议里写明 NEVER skip hooks (--no-verify, --no-gpg-sign, etc)；解释为什么不让模型用 find -regex 时，连正则引擎的差异都讲清楚了：

// bfs (which backs `find`) uses Oniguruma for -regex, which picks the
// FIRST matching alternative (leftmost-first), unlike GNU find's
// POSIX leftmost-longest. This silently drops matches when a shorter

Oniguruma 的 leftmost-first 和 POSIX 的 leftmost-longest 会导致匹配结果不同，这种坑人类工程师都未必记得住，团队把它写进提示词防模型踩雷。还有一点容易被忽略：这些提示词是 TypeScript 代码，工具名用常量插值，改一次工具名全仓库联动。提示词在这里不是贴在配置里的文本，而是走类型检查、代码审查和版本控制的工程产物——把提示词当代码管理，是这个代码库最值得借鉴的作法之一。

filesystem.ts：1778 行的路径攻防

src/utils/permissions/filesystem.ts 有 1778 行，只回答一个问题：AI 要碰某个文件路径时，放行、拒绝还是问用户？ 一个"路径检查"写到这个体量，是因为它面对的是对抗性输入。看它的检查清单：

/**
 * Detects suspicious Windows path patterns that could bypass security checks.
 * - NTFS Alternate Data Streams (e.g., file.txt::$DATA or file.txt:stream)
 * - 8.3 short names (e.g., GIT~1, CLAUDE~1, SETTIN~1.JSON)
 * - Long path prefixes (e.g., \\?\C:\..., \\.\C:\...)
 * - Trailing dots and spaces (e.g., .git., .claude , .bashrc...)
 * - DOS device names (e.g., .git.CON, settings.json.PRN)
 * - Three or more consecutive dots (e.g., .../file.txt)
 */

ADS 备用数据流、8.3 短名、长路径前缀、尾部点号、DOS 设备名，每一类都是真实存在的绕过手法。注释还专门解释了为什么在非 Windows 平台也要查：NTFS 可以挂载到 Linux 和 macOS 上（ntfs-3g），同样的绕过照样成立。

更见功力的是它对"为什么不直接规范化"的论证：

 * An alternative approach would be to normalize these paths using Windows APIs
 * (e.g., GetLongPathNameW). However, this approach has significant challenges:
 * 1. Filesystem dependency: ... files that don't exist yet cannot be normalized.
 * 2. Race conditions: ... TOCTOU (Time-Of-Check-Time-Of-Use) vulnerabilities.
 * 3. Complexity: ...
 * 4. Reliability: Pattern detection is more predictable ...

调系统 API 规范化路径听起来更"正统"，但新文件还没存在无法规范化，检查和使用的间隙文件系统可能变化（TOCTOU 竞争）。团队选择只做模式检测、命中即转人工审批，理由是行为可预测。这是在充分理解替代方案的缺陷之后做的减法，比"多加几层检查"难得多。 这 1778 行里最值钱的不是检查项本身，而是"知道什么不该做"。

三、对比参照法：三种路线，一种演化方向

参照系一：VSCode Copilot——扩展路线

Copilot 作为 VSCode 插件存在，架构是寄生式的：它用独立的 Node.js 进程跑语言服务器，通过 LSP 和宿主通信；src/platform 抽象 VSCode API，instantiationService 用依赖注入管理服务生命周期。工程上很成熟，但能力天花板由宿主决定：扩展能做的事，是 VSCode 扩展 API 的子集。

Claude Code 的能力边界是操作系统：46 个工具可以直接执行命令、读写文件、发起网络请求。两者的差距不是功能多少，而是假设不同。Copilot 假设开发发生在 IDE 里；Claude Code 假设开发可能发生在任何有 shell 的地方——SSH 会话、CI 管道、容器、远程服务器。代价也很直接：Copilot 不用操心终端渲染、不用自建权限系统，这些 Claude Code 全得自己扛，前面那 2 万行 ink 和 1778 行 filesystem.ts 就是账单的明细。

参照系二：Cursor——IDE 原生路线

Cursor 比 Copilot 激进：直接 fork VSCode，把 AI 做进编辑器内核。它对整个仓库建语义索引，能回答全局性问题；补全走自研小模型保延迟，复杂推理走 GPT 系大模型；后台 Agent 可以在用户看不见的地方跑长任务。在"IDE 内的智能密度"这个方向上，Cursor 做到了当前形态的极致。

两个产品与其说是竞争，不如说是各自占住一个场景。本地写复杂前端项目，Cursor 的图形交互和索引能力更顺手；登上无头服务器排障，Cursor 够不着，Claude Code 可以。值得注意的是两边正在向对方的地盘伸手：Cursor 做了后台 Agent，Claude Code 有 bridge/ 远程模式和后台任务系统。长任务在后台跑、完成再汇报，这个交互模型正在跨形态趋同，将来分胜负的可能不是"IDE 还是终端"，而是谁的工具编排和权限模型更能撑住无人值守的执行。

参照系三：GitHub CLI——纯 CLI 路线

gh 把 GitHub 的 Web 功能搬进终端，Go 实现，是传统 CLI 工程的样板：Cobra 做命令分层，cmdutil.Factory 做依赖注入，退出码有严格语义（0 成功、1 一般错误、2 取消、4 认证错误、8 挂起），第三方可以按目录约定扩展子命令。gh 是命令驱动的：用户知道自己要做什么，工具负责最短路径执行。

Claude Code 是意图驱动的：用户描述目标，模型决定调哪些工具。这是两代 CLI 的分界。但在实现层，Claude Code 大量继承了 gh 这一代 CLI 的家底：commands/ 目录对应 Cobra 的命令树，services/ 对应工厂层的标准化服务，技能和插件机制对应扩展系统。说它是"CLI 工程最佳实践之上叠了一层智能体编排"并不夸张。反过来，它也有没继承好的地方：退出码语义、机器可读输出这类脚本友好性，就不是它的设计重心——cli/print.ts 那 5594 行正是在补这块短板。

四个坐标的对照

维度	VSCode Copilot	Cursor	GitHub CLI	Claude Code
宿主策略	IDE 扩展	IDE 原生	独立 CLI	独立 CLI
AI 深度	补全 + 聊天	全局索引 + 推理	无	智能体编排
上下文范围	当前文件及邻域	整个代码库	命令参数	工作目录，可扩展
交互范式	图形侧边栏	图形嵌入式	命令式	对话式 + 命令式
运行环境	桌面 IDE	桌面 IDE	任何终端	任何终端
能力边界	IDE 扩展 API	IDE 内核 + 云服务	操作系统命令	操作系统 + 网络 + MCP
用户假设	开发者在 IDE 内	开发者在 IDE 内	用户明确知道命令	用户描述意图，模型选路径
架构重心	API 抽象层	索引与推理	命令分发	工具编排与权限

表格里最值得停留的是最后一行。Copilot 的重心是抽象层，Cursor 的重心是索引和推理，gh 的重心是命令分发，而 Claude Code 把最大的工程投入压在了工具编排和权限上——46 个工具的契约、1778 行的路径检查、4436 行的 bash 解析器，全是这条重心的注脚。这个分配方式回答了一个产品问题：当模型能力由 API 提供商决定、各家拉不开差距时，差异就沉淀在"模型能安全地够到多少东西"上。 Claude Code 赌的是这个。

四、深层启示：信任半径、接缝淤积与智能体的安全底座

三种方法走完，把整张逻辑图拼起来，可以得到六条可迁移的启示。

启示一：把启动序列当作一条有安全分区的流水线

Claude Code 的 init.ts 里每一步都有明确的前提：CA 证书必须在第一次 TLS 握手前，安全环境变量必须在信任对话框前，遥测必须在信任确立后。初始化顺序不是细节，是架构。 借鉴到实践中：给自己系统的初始化代码画一张顺序图，给每一步标注"它依赖什么、谁依赖它"。凡是说不清前提的步骤，都是将来事故的埋点。

启示二：特性裁剪尽量发生在编译时

运行时的 if (enabled) 只是把门关上，编译时的 feature() 是把房间拆掉——内部调试命令、实验功能在外部产物里连字符串都不存在。如果你的产品需要区分社区版、商业版、内部版，裁剪层级越早，泄密面和包体积越小，审计成本也越低。在 AI 工具这个品类里，"用户拿不到的东西"比"用户用不了的东西"安全得多——因为攻击者可以通过 patch 二进制、注入环境变量、hook 运行时来重新打开那扇门，但没法让一个不存在的房间重新出现。

启示三：扩展接口的默认值决定生态的安全水位

Tool 接口里 isConcurrencySafe 和 isReadOnly 默认都是 false：不声明就按最坏情况处理，声明了才获得调度优待。默认放行，生态会朝着粗放生长；默认收紧，作者想偷懒的代价是功能降级而不是安全事故。 设计扩展点的时候，先想清楚"不填会怎样"，那才是真正的默认行为。这个原则的适用范围远超插件系统——任何有第三方接入点的系统都适用。

启示四：把提示词当代码管理

提示词写在 TypeScript 里、用常量插值、过类型检查和代码审查，改一次工具名全仓库联动。反例我们都见过：提示词散落在 YAML、数据库和聊天记录里，没人知道线上跑的是哪一版。只要提示词开始影响产品行为，它就值得享受和业务代码同等的工程待遇——版本化、可评审、可回滚。对 AI 产品尤其如此：提示词就是产品逻辑本身，不是"配置"。

启示五：复杂度会淤积在接缝处

这份代码库里最大的文件全是边界翻译层：输出管道、消息协议、会话存储、shell 语法解析。这不是 Claude Code 独有的病，任何系统的两端各自演化，中间的翻译层就会持续增重。实践含义有两个：排期时给接缝层留足余量，它一定超预期；评审时对接缝层的大文件宽容一些，它们大不等于烂——能在一个地方看全两端的上下文，有时候比拆成十个"干净"的小文件更值钱。

启示六：智能体产品的差异，沉淀在"模型能安全够到多少东西"上

模型能力由 API 提供商决定，大家拉不开差距；能拉开差距的是编排和管束：工具契约怎么定、权限检查做多细、失败时降级成什么。Claude Code 为一条 bash 命令的意图判断写了完整的语法解析器，为一个路径检查覆盖了 ADS、8.3 短名、TOCTOU 这些对抗面。这笔投入换到的是信任半径——用户敢让它在更多场景里放手干活。做智能体产品，"聪明"是租来的，"管束"才是自己的。

结语：读代码，就是读决策

本文做的事概括起来就三步：从入口读出设计意图，从规模看出治理手段，从对照看清取舍代价。这套读法不挑对象，下次拿到任何一个陌生的代码库都可以照做一遍——先读入口，再数规模，最后找坐标。代码库不会主动告诉你它的设计决策，但它也撒不了谎；你需要的只是一套追问的顺序。

而 Claude Code 这个案例真正值得记住的，不是某个具体的技术选型，而是那个反复出现的模式：入口处做安全分区，编译时做攻击面归零，契约里做默认不信任，接缝处做足预算。 这四条合在一起，构成了一个 AI 工具敢把命令执行权交给模型的底气。当模型能力趋于同质化，"敢让模型碰什么"就成了产品分水岭——而这个问题的答案，早在代码还没运行起来的那一刻，就写在了入口文件里。

原创技术博客 · 开源项目分享 · AI全栈创作社区 idao.fun

用 AI 写代码半年，他忘了怎么手写 JSON

x_cmd — Sat, 08 Aug 2026 06:45:32 GMT

Ken Liu 在 2012 年的短篇《The Perfect Match》里写过一个 AI 助手 Tilly，替用户决定早餐、音乐和约会对象。主角慢慢忘记自己喜欢什么，因为算法比他自己更懂他。

十三年过去，小说里的 Tilly 变成了我们熟悉的 Claude、ChatGPT、Gemini、DeepSeek。

有人已经开始把全部思考外包给 AI 了。

HN 上一位后端工程师说，自己做十几年开发，JSON 解析闭着眼都能写。后来项目赶进度，他把需求扔给 AI，几秒钟代码就出来了。用顺手之后，凡遇 JSON 相关问题，第一反应就是问 AI。慢慢地，他再看到 JSON，脑子里只剩一个模糊的感觉。

直到有一天他想自己写一个 JSON 解析函数，手指悬在键盘上，愣住了。完全不知道怎么下手。

那篇帖子下面很快堆了几百条回复。有人面试时被问到基础算法题，当场脑子卡住；

有人带新人时，发现自己能看懂 AI 写的代码，却解释不清为什么这样设计；

有人项目做了两年，交接时翻出自己的代码，发现有三分之一自己都不认识。

AI 提高了我们获得答案的速度。但它会不会也让我们减少了寻找答案的过程。

人类一直在进行认知外包

把一部分能力交给工具，并不是 AI 时代才有的事。文字出现之前，知识主要依靠人的记忆保存。文字出现后，人类把大量信息放到了外部载体。

后来，算盘替代部分计算，计算器替代复杂运算，搜索引擎替代大量事实记忆。这些变化并没有让人类失去能力。因为过去工具主要替代的是执行层面的重复劳动。计算器可以告诉你结果，但不会告诉你应该计算什么。搜索引擎可以提供资料，但不会替你判断哪个答案更可靠。

工具减少的是执行成本。判断"应该做什么"这件事，始终需要人自己完成。

AI 不同的地方，是它开始接近判断过程

AI 不只是帮我们保存信息或者执行任务。它开始参与判断过程本身。

一个程序员以前解决一个问题，需要经历很多步骤。理解需求，判断这个需求是否合理。拆解问题，判断这个问题可以怎么拆分。尝试实现，遇到错误，分析错误原因，判断下一步怎么调整。

这些步骤看起来很慢。但经验恰恰是在这个"慢"的过程中形成的。

第一次遇到一个错误，你可能完全不知道原因。第二次遇到类似问题，你会想到几个可能的方向。几年之后，你看到一个异常现象，大脑会快速联想到几个可能的原因。这就是工程经验。

工程经验来自过去不断解决问题所形成的判断模式。记住更多答案，并不能直接得到它。

但 AI 可以直接跳过其中很多步骤。你描述问题，它给你一个能跑通的方案。结果可能完全正确，而你缺少了那个"从混乱到清晰"的判断过程。

你跳过的每一步里，都藏着一次判断。你以为在跳过"麻烦"，其实在跳过"练习判断的机会"。

被外包出去的是判断

很多人误以为，自己能看懂 AI 生成的代码，就代表自己掌握了。但理解答案和产生答案，是两种不同的能力。

看一段代码，你可以知道它做什么。可到自己写的时候，你需要判断。这个需求应该怎么拆。这里为什么需要异常处理。这个设计未来扩展时会不会变成坑。什么时候应该选择简单方案而不是完美方案。

这些判断，才是能力积累的核心。

如果长期跳过思考过程，人会逐渐失去形成判断的机会。判断力和肌肉一样，长时间不用就会萎缩。

AI 重构大型项目没有想象中简单

这个问题不仅存在于个人开发场景。在工程领域，有人期待 AI 可以自动重写大型项目。分析代码，重新设计架构，自动优化实现。

但最困难的部分，从来不是生成代码。而是理解代码背后的历史和取舍。

为什么这里用了一个看起来不优雅的方案。因为当时有不得不这样做的约束。为什么这个模块没有继续抽象。因为抽象的成本在当时超过了收益。为什么这个问题暂时没有解决。因为解决它需要付出的代价暂时还不值得。

这些答案往往不在代码里，而在工程师长期积累的经验里。

个人把写代码完全交给 AI，失去的是自己的判断过程。团队把工程决策完全交给 AI，失去的是整个系统的经验。判断可以被辅助，但不能被完全外包。

区分效率提升和能力成长

那么应该少用 AI 吗。当然不是。

未来大多数工作都会依赖 AI。要先区分两件事。哪些事情可以交给 AI 来提升效率，哪些事情需要自己经历才能成长。

类型	典型场景	你的收获
✅ 可外包	写测试用例、格式转换、整理资料、重复代码	效率
⚠️ 须自己练	首次设计数据库表、手写核心算法、第一次解决某类问题	能力

关键不在用不用 AI，而在你把它放在什么位置。如果你已经掌握一项能力，让 AI 处理重复部分，这是效率提升。但如果你第一次学习一个领域，就直接跳到 AI 给的最终答案，你得到的是结果，不是能力。

同样是使用 AI，动机不同，结果就不同。让 AI 替你完成任务，你积累的是速度。让 AI 参与你的思考，你积累的是能力。

AI 可以帮我们更快拿到答案。但拿到答案之前的思考过程，才是判断力形成的地方。

你最近有没有发现，某个你曾经很熟练的东西，现在已经想不起怎么下手了？

echoVic — Sat, 08 Aug 2026 05:49:52 GMT

Qwen 3.8 max干了20分钟没干完，免费模型3分17秒搞定，问题出在哪？

程序员老刘 — Sat, 08 Aug 2026 04:24:22 GMT

大家好，我是老刘

前两天老刘花了一杯咖啡的钱，买了千问token plan的最低档，准备测试一下Qwen 3.8 max在我的Flutter项目里能不能当主力。

任务很简单：我已经开发完了三个独立的数据处理和业务逻辑模块，现在只需要把它们接入主流程，让主流程能调用它们。

就这么个活儿，Qwen 3.8 max干了20分钟，直接把我的5小时额度烧光了，然后工作还没完成。停在了一半的地方。

我换成opencode的免费模型，同样的任务，3分17秒，顺利完成。

不可思议是不是？

这完全不是一个对标顶级模型应该有的表现。

今天老刘就来聊聊，这20分钟里到底发生了什么，以及我们选主力模型时最容易踩的那个坑。

先说句公道话，Qwen 3.8 max的跑分是真能打

这里要先说明白，老刘说的测评数据不是那种公开题目可以刷榜的测评。

那种测评我基本已经不看了，因为吃过几次亏：评分很高，但实际工作能力很差。

我现在主要看题目不公开的，比如LiveBench。

Qwen 3.8 max在这类测评中得分很高，说明真实能力还是可圈可点的。

可以看到，Qwen 3.8 max的综合能力仅次于claude fable 5和gpt-5.6这样的顶级模型。

单看编程能力，也非常好：

闭源题目的测评具有比较高的参考意义，在一定程度上能体现模型在指定科目上的泛化能力。

但要注意这个是参考价值，因为测评和真实项目之间还是存在着比较大的差异的。

跑分为啥救不了你的项目？

场景对不上

老刘主要写Flutter代码，但目前主流编程能力测评里，基本没有用Flutter的。

你拿一个考Python和Web的分数，去预测它写Flutter的水平，这就像拿驾照科目一的成绩去判断一个人会不会开山路。

用法对不上

老刘的日常开发流程是这样的：先用顶级模型把一个需求拆成多个功能点，再用中档的主力模型逐个开发每个功能点的代码。

这个用法其实介于LiveBench的coding和agentic coding之间。

也就是说，我这个功能点的开发，用测评里的哪个维度去选模型都不合适。即使用平均分，偏差也很大。

所以测评的分数主要还是一个参考，最终还是要放到项目里实际跑一跑。

老刘这次就是真刀真枪地跑了。

Qwen 3.8 max还是是干活太认真了

如果用一个字总结Qwen 3.8 max在我项目里的表现，就是啰嗦。

看它的思考过程就能发现问题：思考链路特别长，如果每一轮都把上一轮的思考加入输入，token很快就消耗光了。

这一点从LiveBench的性价比排名中也能得到印证：

单看简单编程的性价比，Qwen 3.8 max的排名并不靠前。

所以老刘的结论是：Qwen 3.8 max的能力确实不错，但代价是需要消耗大量的token才能完成同样的任务。

这就好比招了一个能力很强的员工，但他干一个小时的活儿要烧别人一天的工资。

从测评看，它在逻辑思考、数据处理等方面的性价比明显比编程方面高。让它当编程主力，可能属于专业不对口。

有意思的是，当前这篇文章的错字修改、排版优化、文章头尾固定内容的添加、发布到github等工作都是老刘用token plan中仅剩的额度，通过Qwen 3.8 max完成的。总体消耗远小于开发任务。

这也从侧面证明了老刘的观点，Qwen 3.8 max似乎更适合非编程类任务。

一杯咖啡的钱，买了个教训

说实话，这次测试老刘自己也有点尴尬。

我买这个最低档的token plan，本来是想横向测试一下各家订阅哪个更好用，后续也会给大家汇报其他厂商订阅的使用效果。

结果千问这边，第一轮长对话还没跑完，额度就阵亡了。

这里还是要吐槽一句：虽然最低档只要一杯咖啡的钱，但如果5小时的限额连一轮长对话都无法完成，那它在实际工作中就没有任何意义。

特别是在agnes、商汤、Openrouter、opencode等很多厂商都提供了慷慨的免费额度的时候，这种低档位订阅完全不具备在开发场景中的实用价值。

最后说两句

这次翻车让老刘更加确信一件事：

跑分是给外人看的，账单是给自己看的。

选主力模型的时候，除了要看榜单的能力排名，还要看一看完成每个任务需要花多少钱。

把这个问题想清楚了，再去看跑分，顺序千万别反了。

最后老刘也想问问大家：你有没有被跑分骗过？你现在选主力模型，最看重的是什么？欢迎评论区聊聊。

🤝 如果看到这里的同学对客户端或者Flutter开发感兴趣，欢迎联系老刘，我们互相学习。

🎁 私信免费领老刘整理的《Flutter开发手册》，覆盖90%应用开发场景。可以作为Flutter学习的知识地图。

💬 : laoliu_dev

📂 老刘也把自己历史文章整理在GitHub仓库里，方便大家查阅。

🔗 github.com/lzt-code/bl…

复制成功，不等于文章能发布：markdown2x 如何拆开富文本与图片资产

echoVic — Sat, 08 Aug 2026 04:13:25 GMT

把一篇 Markdown 复制进 X Articles，看起来只有两个步骤：解析 Markdown，写入剪贴板。

真正动手后，很快就会撞到几个不在同一层的问题。标题和列表要保留格式；代码块粘贴后不能变成一团等宽文本；Mermaid 和表格需要转成图片；浏览器还可能拒绝富文本剪贴板权限。即使按钮提示“复制成功”，文章里仍可能留着没有上传的图片和平台不支持的语法。

我最近重新读了 markdown2x 的复制链路。它没有把所有内容硬塞进一段 HTML，而是先把一篇文章拆成文档结构，再同时生成富文本、纯文本和待处理资产。这种拆法比“Markdown 转 HTML”更接近真实的发布流程。

先得到文档结构，再决定怎么交付

入口在 lib/markdown.ts 的 parseMarkdown()。它把源码解析成一组 ArticleBlock：标题、段落、引用、列表、代码、Mermaid、表格和 Tweet 各自拥有明确类型；行内内容再拆成文本、粗体、斜体、链接、行内代码和图片。

这里没有直接输出 HTML。预览、纯文本回退、剪贴板富文本和资产面板都消费同一份结构。

这个中间层解决了一个很实际的问题：同一个 Markdown 块，在不同出口里应该有不同形态。

二级标题在富文本里是 <h2>，在纯文本里只保留文字。
链接在 HTML 里保留 <a href>，在纯文本里变成“标题 + URL”。
代码块可以变成引用，也可以变成一张待粘贴的 PNG。
Mermaid 源码不能直接进入文章正文，只留下图片插入位置。

如果解析阶段就急着拼 HTML，后面每增加一种出口都要重新猜一次原始语义。ArticleBlock 把这次猜测固定在一个地方。

一个复制按钮，实际写入两份正文

toXArticleClipboard() 返回的不是一个字符串，而是一份 XArticleClipboard：

type XArticleClipboard = {
  title: string;
  titleHtml: string;
  bodyText: string;
  bodyHtml: string;
  fullText: string;
  fullHtml: string;
  assets: XArticleAsset[];
  assetOffsets: number[];
};

正文复制时，components/editor-page.tsx 会同时写入两种 MIME：

new ClipboardItem({
  "text/html": new Blob([html], { type: "text/html" }),
  "text/plain": new Blob([text], { type: "text/plain" }),
});

支持富文本的目标编辑器会读取 text/html，普通输入框仍可退回 text/plain。用户只点了一次按钮，剪贴板里却带着两个兼容层。

浏览器拒绝 ClipboardItem 时，代码还会退回到一个屏幕外的 contenteditable 容器，通过 Selection 和 document.execCommand("copy") 复制。这个路径也失败，界面才展示手动复制区。

所以“复制正文”不是一次 API 调用。它是一条有降级顺序的交付链：现代富文本剪贴板、Selection 回退、人工复制。

代码、表格和 Mermaid 被当成另一类工件

X Articles 的正文编辑器不能可靠接住所有 Markdown 结构。markdown2x 没有假装一次粘贴能解决全部内容。

当代码模式设为 image 时，代码块与表格、Mermaid 会进入 assets。正文对应位置只留下明确提示，例如：

📷 [Code image 1 — paste from Assets panel]

每个资产还保存自己的原始数据：代码与语言、表头与行、Mermaid 源码。assetOffsets 则记录它在 Markdown 源文中的字符位置，后续可以从检查结果或资产面板跳回编辑器。

这一步很像构建系统处理源码和产物：正文是可直接粘贴的主工件，图片是需要单独渲染和上传的伴随工件，offset 是两者回到源文件的定位信息。

项目没有把图片伪装成已经交付。测试会明确断言 Mermaid 源码不进入 bodyHtml，而 assets 中保留完整图表内容；表格同样转成 PNG 任务，Tweet 则保留链接和嵌入提示。

Preflight 能发现问题，但目前不会拦住复制

runPreflight() 会扫描两类风险。

一类来自已解析结构：代码将变成引用还是 PNG、表格有多少列、远程图片不会自动上传。另一类直接扫描原始 Markdown，包括脚注、LaTeX、iframe、分隔线和删除线等当前不支持的语法。

每条结果都带 sourceOffset，用户可以跳回问题位置。报告状态分为 ok、warning 和 blocked。

但这里有一个需要说清的边界：copyBody() 在没有 preflight 报告时只显示五秒提示，随后仍会继续复制。也就是说，当前 preflight 是发布前检查工具，还不是一个强制 gate。blocked 描述的是检查结果，不代表复制按钮一定被阻止。

这并非文字游戏。写文档工具时，提示、阻断和自动修复是三种不同承诺。把提示写成“已经保证可以发布”，会让用户在目标平台上才发现缺图或语法丢失。

转换工具真正交付的是失败边界

这条源码链让我重新理解了文档转换工具。格式转换只是其中一段，完整交付还包括：目标编辑器能吃下什么，浏览器剪贴板允许什么，哪些内容必须变成独立资产，以及失败后用户从哪里继续。

markdown2x 目前已经把这些事实拆开：同一份 AST 生成 HTML 和纯文本，图片类内容进入资产队列，preflight 标出无法自动处理的语法，复制权限失败后继续降级。

它也保留了真实限制。图片仍需要用户逐个粘贴，远程图片不会自动上传，preflight 还没有成为强制发布门。现阶段把这些边界展示出来，比用一个“完美转换”的按钮文案更有用。

项目源码在 echoVic/x-article-md，线上工具使用 markdown2x.com。本文对应的转换契约集中在 lib/markdown.ts、lib/preflight.ts 和 components/editor-page.tsx。

Han：一个让 AI Agent 也能做出高级中国风页面的 CSS 设计系统

雨夜寻晴天 — Sat, 08 Aug 2026 04:03:50 GMT

说实话，挺难的。

你要朱红，但不能太红；你要水墨，但不能太黑；你要留白，但不能空得没东西。一不小心，要么变成喜庆大红大绿，要么变成"假古董"堆龙凤祥云。

汉 · Han 就是为了解决这个事儿——一个面向 AI Agent 的中国文化设计 Skill，把宣纸、墨色、朱红、书法、卷轴这些东方美学元素，变成可以直接用的 CSS 令牌、主题和组件。

不用从零配色，不用手写纹样，不用纠结"这个朝代该用什么颜色"。引入一个 CSS，选个主题，页面就有了气质。

一句话介绍：它是个啥？

Han 是一个设计 Skill + 视觉资产包。你可以把它理解为：

一套开箱即用的中国风设计系统，CSS 层面帮你搞定色彩、字体、间距、组件和动效，同时附带文化决策规则，让 AI Agent 能自主判断"什么场景该用什么风格"。

目前有 22 个主题，覆盖从秦汉到清的朝代启发主题、水墨/青花瓷/敦煌等文化主题，还有 6 个面向现代网页的当代配色主题。

不用 build，不用装依赖，引入 CSS 就能用。

能做什么？直接看例子

光说没用，看看用 Han 做出来的真实页面长什么样。

1. 茶叶品牌 — 松麦主题

📍 han.raingpt.top/pine-wheat-…

松麦绿配色，自然清新。导航、Hero 区、产品展示、品牌故事、CTA，一个茶叶品牌的落地页该有的全有了。配色不抢戏，气质对味。

2. 美妆护肤 — 藤紫主题

📍 han.raingpt.top/plum-blush-…

藤紫色调，柔和浪漫。适合美妆、护肤、轻奢品牌。谁说中国风只能配茶和博物馆？

3. AI 科技产品 — 海兰主题

📍 han.raingpt.top/ocean-orchi…

海兰配色，冷静清透。科技产品也能用中国风，而且一点都不违和。谁说做 AI 就得蓝紫渐变？

4. 精品咖啡 — 焦糖主题

📍 han.raingpt.top/caramel-cre…

焦糖暖色，复古高级。咖啡品牌 + 中国风，这个组合可能很多人没想到，但效果真的很搭。

5. 瑜伽健康 — 薄荷主题

📍 han.raingpt.top/mint-lavend…

薄荷薰衣草配色，清透自然。瑜伽、健康、生活方式类产品用这个，看着就让人想深呼吸。

6. 甜品节活动 — 莓果主题

📍 han.raingpt.top/berry-butte…

莓果奶油配色，明快有活力。活动页、营销页用这个色调，年轻又不轻浮。

7. Mac 产品概念页 — 宋韵主题

📍 han.raingpt.top/landing-pag…

这个可能最让人意外——用宋韵主题做一个 Apple Mac 风格的产品页。清雅克制的设计语言，配上产品大图和精致排版，东方美学和现代科技产品的结合，居然可以这么自然。

8. 软件产品官网介绍

📍 luma.raingpt.top/

本页由 Han design skill（宋 · song 主题）构建 · 响应式 · 可访问

9. 当代配色主题总览

📍 han.raingpt.top/contemporar…

6 个当代配色主题一站式展示，带主题切换、色彩体系展示和组件 demo。想选哪个主题，打开这个页面直接对比。

核心能力：不只是好看

22 个主题，总有一个对味

类型	主题	适合场景
朝代启发	秦汉、魏晋、唐、宋、元、明、清	博物馆、文化展览、历史教育
文化主题	水墨、青绿山水、青花瓷、敦煌、宫廷金、武侠、茶道、朱砂、青瓷	品牌官网、文创产品、传统文化
当代配色	松麦、藤紫、海兰、焦糖、薄荷、莓果	现代品牌、SaaS 产品、生活方式

切主题就一行代码：

<html lang="zh-CN" data-theme="song">

组件都有，而且不土

印章按钮 .han-btn-seal — 关键 CTA 用，带倾斜和盖章动效
水墨导航 .han-navbar — sticky + 毛玻璃，品牌名一个字朱红
卷轴卡片 .han-card-scroll — 产品展示、文章列表，四角铆钉装饰
窗花边框 .han-frame-window — 名言警句、诗词展示
水墨分割线 .han-divider-ink — 章节过渡，带小印章
印章 .han-stamp — 署名、落款、认证

AI Agent 能自己干活

这是 Han 最有意思的地方——它不只是 CSS，还包含一套文化决策规则。

你跟 AI 说：

"用 han-design，帮我做一个克制的宋韵产品落地页。"

或者更随意：

"用 han-design 把当前页面弄好看点，你自己判断主题和风格。"

AI 会自己读设计规范、判断页面类型、选主题、定视觉强度、补全内容，然后生成页面。你不需要知道主题 ID 叫什么，也不需要背组件类名。

该有的工程素质都有

响应式，移动端能看
键盘焦点、ARIA 标签、reduced-motion 支持
han-scoped.css 局部引入，不污染宿主项目全局样式
无 build 步骤，静态 HTML 直接跑
深色模式支持

怎么用？

方式一：作为 Agent Skill 安装

git clone https://github.com/you-want/han-design.git han

mkdir -p "$HOME/.agents/skills"
cp -R skills/han-design "$HOME/.agents/skills/han-design"

装完直接跟 AI 说"用 han-design 做个页面"就行。

方式二：直接用 CSS

复制 skills/han-design/assets/ 到你的项目：

<!-- 可选：远程字体 -->
<link rel="stylesheet" href="/han/fonts.css">

<!-- 完整设计系统 -->
<link rel="stylesheet" href="/han/han.css">

已有项目不想被全局 reset 影响？用 scoped 版：

<link rel="stylesheet" href="/han/han-scoped.css">

<section data-han-scope data-theme="song">
  <button type="button" class="han-btn-seal">确认</button>
</section>

Token、深色模式和主题变量只在 data-han-scope 内生效，不动你项目里其他任何样式。

适合谁用？

前端开发者 — 想快速做个有调性的中国风页面，不想从零配色
设计师 — 需要一套靠谱的中国风设计令牌做参考
AI 应用开发者 — 给 Agent 装上"中国风审美"的能力
独立开发者 / 创业者 — 做品牌官网、产品落地页，想要点不一样的气质
任何觉得"蓝紫渐变 + Inter 字体"看腻了的人

最后说两句

做中国风设计最大的坑，不是技术，是分寸感。

朱红用多了像过年，金色堆多了像寺庙，龙凤纹样乱用显得廉价。Han 的设计规范里专门写了禁忌清单——金色不超过 3%，朱红不超过 5%，不用 emoji 当图标，不乱用龙凤纹样。这些规则不是拍脑袋定的，是从大量实践里总结出来的。

让东方美学在网页上优雅绽放，而不是用力过猛。

这就是 Han 想做的事。为啥叫做 Han ？？？因为我们身份证是汉族、说的是汉语、写的是汉字......那么当然我们的这个中国风也要叫 han-design 。

项目地址：github.com/you-want/ha…

License：MIT，随便用。

以上就是全部内容。如果觉得有意思，去 GitHub 点个 Star，或者直接装来试试。有问题欢迎提 Issue，也欢迎来交流你用 Han 做出了什么好东西。

前端看后端 16：什么是端口？

颜进强 — Sat, 08 Aug 2026 03:34:03 GMT

专栏第十六篇，网络与协议篇第九章。上一篇我们聊了 DNS，搞懂了浏览器是怎么把 google.com 翻译成 142.250.72.206 这个 IP 的。但问题来了——数据包千辛万苦传到服务器，服务器上同时跑着 Nginx、Node.js、MySQL、Redis、SSH……这包到底该交给谁？总不能让所有程序抢着处理吧？今天的主角 Port（端口），就是操作系统用来区分"这台机器上不同程序"的编号。它是网络通信里最容易被忽略、却又天天打交道的概念——3000、5173、8080、3306、6379 这些数字背后，藏着一整套规则。

一、端口是什么？——IP 是酒店地址，端口是房间号

端口（Port）是一个 16 位整数，范围 0 ~ 65535，用于在一台主机上区分不同的应用程序或服务。

核心比喻

IP 地址 = 酒店地址（如 142.250.72.206）
端口   = 房间号（如 443）

访问 https://google.com
= 找到"142.250.72.206 这家酒店"的"443 号房间"

IP 解决"哪台机器"（网络层）
端口解决"机器上的哪个程序"（传输层）

💡 一台服务器可以同时跑很多服务，全靠端口区分。没有端口，数据到了机器也不知道交给谁——就像快递只写了酒店地址没写房间号，前台只能干瞪眼。

为什么需要端口？

假设没有端口：

你的服务器同时跑着 Web 服务、数据库、SSH、FTP……
一个数据包从网络到达网卡
操作系统内核懵了："这包是给谁的？"

端口就是操作系统做"多路复用"的依据：内核维护一张"端口 → 进程"的映射表，数据包到达时，根据目标端口，交给对应的进程处理。

二、端口的分类（0~65535 的三段划分）

IANA（互联网号码分配机构）把端口分成三段，每段用途不同。

1️⃣ 知名端口（Well-Known Ports）：0 ~ 1023

分配给最核心的互联网服务，在 Linux/Unix 上需要 root 权限才能绑定。

端口	服务	说明
80	HTTP	网页（明文）
443	HTTPS	网页（加密）
22	SSH	远程登录
21	FTP	文件传输（控制通道）
25	SMTP	发邮件
53	DNS	域名解析

⚠️ 注意：MySQL（3306）、Redis（6379）、PostgreSQL（5432）这些虽然"知名"，但端口号 大于 1023，严格来说属于"注册端口"，不是知名端口。

2️⃣ 注册端口（Registered Ports）：1024 ~ 49151

分配给特定的应用程序或服务，由 IANA 登记管理。开发者自己写的服务，通常也在这段里选端口。

端口	服务
3306	MySQL
5432	PostgreSQL
6379	Redis
27017	MongoDB
5672	RabbitMQ
8080	HTTP 替代端口（Tomcat 默认）
8443	HTTPS 替代端口
9090	Prometheus
9200	Elasticsearch

3️⃣ 动态/私有端口（Dynamic/Private Ports）：49152 ~ 65535

客户端临时使用的端口，也叫"临时端口"（ephemeral port）。

当你访问 google.com:443 时，操作系统会从 49152~65535 中随机挑一个端口作为源端口
服务器响应时，数据就发回这个端口
连接关闭后，端口释放，可被下次复用

📌 你在 netstat 里看到的那些 localhost:51023、localhost:52341，基本都是临时端口。

三、TCP 端口 vs UDP 端口

端口同时存在于 TCP 和 UDP 两个协议上，它们是独立的！

TCP:80   ≠   UDP:80

TCP 端口：面向连接的服务（HTTP、HTTPS、SSH、MySQL）
UDP 端口：无连接的服务（DNS 查询、DHCP、视频流、游戏）

所以一台机器上，TCP 80 和 UDP 80 可以同时被不同进程占用，互不影响。操作系统内部实际上维护了两张表：一张 TCP 的，一张 UDP 的。

四、常见端口速查表（开发者必备）

🌐 Web 相关

端口	用途
80	HTTP（浏览器默认）
443	HTTPS（浏览器默认）
3000	Node.js 开发服务器（Next.js、React、Create-React-App 默认）
5173	Vite 开发服务器默认端口
8080	HTTP 备用（Java/Tomcat、Nginx 代理常用）
8000	Python/Django、FastAPI 开发
5000	Flask 默认
9000	SonarQube、php-fpm

🗄️ 数据库与缓存

端口	数据库
3306	MySQL
5432	PostgreSQL
6379	Redis
27017	MongoDB
1521	Oracle
1433	SQL Server
7001	Cassandra
9042	Cassandra（CQL 原生协议）

🔧 运维与基础设施

端口	服务
22	SSH
3389	RDP（Windows 远程桌面）
9090	Prometheus
30000 ~ 32767	Kubernetes NodePort 默认范围

建议把这张表存下来，配环境、排查问题时反复用。

五、端口的六大应用场景

1️⃣ 开发调试

# 前端开发
npm run dev -- --port 3000   # Next.js
npm run dev -- --port 5173   # Vite

# 后端开发
node server.js                       # 默认 3000
python manage.py runserver 0.0.0.0:8000   # Django

浏览器访问 http://localhost:3000，本质就是告诉操作系统："我要连本机的 3000 号端口。"

2️⃣ 生产环境部署

# Nginx 监听 80，转发到后端 3000
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

为什么生产用 80/443 而非 3000？

浏览器访问 http://example.com 时默认连 80，https://example.com 默认连 443
如果用 3000，用户必须输入 http://example.com:3000，体验差
最佳实践：Nginx 监听 80/443（需要 root），反向代理到内部服务的 3000 端口（非 root 运行更安全）

3️⃣ 端口转发与 SSH 隧道

# 把远程服务器的 3306 映射到本地 3306
ssh -L 3306:localhost:3306 user@remote-server

# 之后访问 localhost:3306，实际连的是远程 MySQL

这是本地开发连线上数据库最安全的方式——数据库端口不用暴露在公网。

4️⃣ 容器化部署（Docker）

# docker-compose.yml
services:
  web:
    ports:
      - "8080:3000"   # 宿主机 8080 → 容器 3000

访问 http://localhost:8080，实际访问容器内的 3000 端口。Docker 通过端口映射，让多个容器的 3000 可以共存，靠宿主机不同端口区分。

5️⃣ 微服务架构

API Gateway :80 → 按路径转发到：
  ├── user-service:3001
  ├── order-service:3002
  └── payment-service:3003

每个微服务绑不同端口，网关根据 URL 路径做路由。

6️⃣ 网络扫描与安全排查

# 查看本机正在监听哪些端口
netstat -tlnp                          # Linux
lsof -iTCP -sTCP:LISTEN -n -P          # macOS
Get-NetTCPConnection | Where-Object State -EQ Listen   # Windows PowerShell

# 扫描远程主机开放了哪些端口
nmap example.com

nmap 是黑客和运维都爱用的神器——前者用来找攻击面，后者用来确认服务是否正常暴露。

六、端口相关的四个核心概念

1. 监听（Listen）

服务程序启动后，调用 bind() + listen()，在操作系统的端口上"竖起耳朵"等待连接。

// Node.js 监听 3000 端口
const http = require('http');
http.createServer((req, res) => {
  res.end('Hello');
}).listen(3000, () => {
  console.log('Server listening on port 3000');
});

2. 端口冲突

如果两个程序都想监听同一个端口，就会报错：

Error: listen EADDRINUSE: address already in use :::3000

解决方法：

# 杀掉占用 3000 端口的进程
lsof -ti:3000 | xargs kill -9

# 或者换一个端口启动

3. 防火墙与端口

入站规则：允许外部访问本机哪些端口
出站规则：允许本机访问外部哪些端口

云服务器（AWS、阿里云、腾讯云）的"安全组"，本质就是端口级别的防火墙。很多新手部署完网站访问不了，十有八九是安全组没开 80/443。

4. `0.0.0.0` vs `localhost`

.listen(3000, 'localhost')  // 只能本机访问
.listen(3000, '0.0.0.0')    // 允许所有 IP 访问（容器/生产环境常用）

localhost / 127.0.0.1：仅本机回环，外部访问不到
0.0.0.0：绑定到所有网络接口，局域网和公网都能连

🐛 Docker 容器里的服务一定要监听 0.0.0.0 而不是 localhost，否则宿主机和外部都访问不到，这是初学者高频踩坑点。

七、端口与 URL 的关系

https://example.com:443/path?query=1
       │            │ │
       │            │ └─ 端口（省略时，https 默认 443，http 默认 80）
       │            └─ 域名
       └─ 协议

浏览器默认行为：

http://example.com → 实际连接 example.com:80
https://example.com → 实际连接 example.com:443

如果服务跑在其他端口，必须在 URL 中显式指定：

http://example.com:3000

八、一个完整的请求旅程（串联整个系列）

把 DNS、TCP、端口、HTTP、Nginx 全串起来，看看一次 https://example.com/path 请求中端口到底起了什么作用：

1. 浏览器输入 https://example.com:443/path
   ↓
2. DNS 解析 example.com → 93.184.216.34（第 15 篇）
   ↓
3. TCP 三次握手：本地随机端口(如 51023) ↔ 93.184.216.34:443（第 08 篇）
   ↓
4. TLS 握手（HTTPS 加密协商）
   ↓
5. 发送 HTTP 请求：GET /path HTTP/1.1（第 09 篇）
   ↓
6. 服务器操作系统收到数据包，看目标端口是 443
   ↓
7. 查端口映射表：443 被 Nginx 监听
   ↓
8. 数据交给 Nginx 进程
   ↓
9. Nginx 反向代理：把请求转发给 127.0.0.1:3000（Node.js）
   ↓
10. Node.js 应用处理，返回响应
   ↓
11. 响应沿原路返回：3000 → 443 → 客户端临时端口 51023
   ↓
12. 浏览器收到响应，渲染页面

端口在每一步都起着"路由"作用：

客户端用临时端口标识自己
服务器用 443 标识 HTTPS 服务
内部用 3000 标识 Node.js 应用

九、安全最佳实践

1. 最小化开放端口

只开放必要的端口，其余全部防火墙挡掉。端口开得越多，攻击面越大。

2. 不要在公网暴露数据库端口

❌ MySQL 3306、Redis 6379 直接暴露公网
✅ 只允许内网访问，或通过 SSH 隧道连接

Redis 早年默认无密码且暴露公网，导致无数服务器被加密勒索，这个教训至今仍然有效。

3. 改掉默认端口（提高门槛）

SSH 22 → 改为 2222 或其他高位端口

这属于"安全靠隐蔽"（Security by Obscurity），不是真正的安全措施，但能挡住大部分自动化扫描和蠕虫攻击。

4. 使用非 root 用户运行服务

1024 以下的端口需要 root 权限才能绑定
生产环境用 1024 以上端口（如 3000、8080）跑业务
通过 Nginx 监听 80/443 做反向代理

这样即使业务进程被攻破，攻击者也拿不到 root 权限。

十、总结

概念	说明
端口是什么	0~65535 的整数，用于区分一台机器上的不同服务
端口 + IP	IP 定位机器，端口定位程序
80/443	HTTP/HTTPS 默认端口，浏览器自动补全
3000/5173/8080	开发服务器常用端口
3306/6379	MySQL/Redis 默认端口
三段分类	知名端口 (0-1023) / 注册端口 (1024-49151) / 动态端口 (49152-65535)
TCP vs UDP	同一端口号在 TCP 和 UDP 上是独立的，互不影响
监听	程序通过 `bind + listen` 在端口上等待连接
端口冲突	`EADDRINUSE`，杀掉占用进程或换端口

写在最后

端口是那种"看似简单、实则贯穿全局"的概念。开发时你敲 npm run dev 看到的 localhost:3000，部署时配的 Nginx listen 80，排查问题时用的 lsof -i:3306，云服务器上开的安全组规则——本质上都是在和端口打交道。

理解了端口，你才能真正搞懂这些常见问题：

为什么我的服务启动了但外面访问不到？（没监听 0.0.0.0，或防火墙没开端口）
为什么 Docker 里要写 "8080:3000"？（宿主机端口和容器端口的映射）
为什么说数据库端口不能暴露公网？（3306/6379 一旦被扫到，就是攻击入口）
为什么一个 IP 能同时跑网站、数据库、邮件？（不同端口分给不同进程）

至此，网络通信系列已经覆盖了从 DNS 到端口、从 TCP 到 HTTP 的完整链路。下一篇我们讲代理，“中间人”位于客户端和服务器之间，转发请求和响应。

如果这个系列对你有帮助，欢迎点赞、关注、收藏三连，我们下篇见 👋

会话选择器不是列表：Orca 如何守住切换边界

echoVic — Sat, 08 Aug 2026 03:33:51 GMT

很多终端 Agent 的会话选择器，看起来只是一个列表：上下移动，按 Enter 打开，按 Tab 看几个操作。真正容易出错的地方藏在“打开”之后：当前会话能不能删？Fork 之后屏幕上的历史是谁的？重命名写进磁盘后，运行中的标题会不会又变回去？

我最近重读 Orca v0.3.8 的 TUI，会发现 session picker 更像一个小型状态机。列表只是入口，身份、投影和破坏性操作才是它真正要守的边界。

操作列表先看当前身份

available_session_actions 接收两个值：当前附着的 session id，以及用户选中的 session id。Resume、Fork、Rename 对两者都可用；只有选中的不是当前会话时，Archive 和 Delete 才会加入操作列表；最后再追加 Copy session ID。

这段判断很短，却比在 controller 里收到 Delete 后再拒绝更可靠。用户根本看不到针对当前会话的删除入口，键盘上下移动的索引也只在真实可用的列表里计算。current_session_actions_exclude_archive_and_delete 测试同时检查了两层：动作集合没有 Archive/Delete，连续按 Down 也不会越过最后一个合法动作。

这里有一条值得带走的 UI 原则：破坏性动作的禁用状态要在动作生成处表达，controller 仍然可以保底拒绝，但不能把错误选项先交给用户。

Fork 不是打开旧会话

Resume 和 Fork 都从保存的 session 出发，运行时语义却不同。Resume 让当前 thread 接回原身份；Fork 则创建新身份，并把源会话作为 parent。切换完成后，TUI 必须同时更换运行时 owner 和屏幕上的 projection。

Orca 的 ForkSavedSession 分支现在先调用 switch_saved_hosted_session，再轮换 attached event sender。随后发出 SessionProjectionReset，清掉当前会话的消息、计划和状态；announce_runtime_ready 重新报告新 thread 的身份；emit_typed_history_snapshot 再把 fork 后的历史投影回来。最后才发 SessionForked，让界面更新标题和 session id。

顺序不能随意交换。只发一个 SessionForked 事件，旧 transcript 可能还留在屏幕上；先绘制历史再换 owner，则旧 session 的后台事件可能继续写进新 projection。对应的 picker_fork_replaces_source_transcript 测试明确验证：新会话里能看到 source-only prompt，看不到 current-only prompt，而且 fork id 同时不同于 source id 和原当前会话 id。

标题有两份，写入不是结束

重命名也有类似的双层状态。保存文件里的标题是 durable metadata，TUI 和 runtime surface 里的标题是当前 projection。Orca v0.3.8 的修复把 rename 接到带 revision 的 SessionMetadataPatch::SetTitle：先确认读到的 revision 仍然匹配，再提交持久化变更，成功后发出 SessionRenamed。

这解决的是一个很具体的回滚问题：如果只改磁盘，不更新 runtime projection，下一次 announce_runtime_ready 仍可能从旧 snapshot 读标题，把用户刚改的名字重新覆盖掉。hosted_tui_rename_updates_durable_title_and_projection_event 测试把 durable title、revision 和 projection event 放在一次流程里验证；写入失败时，另一个回归测试还要求运行时标题恢复到原值。

把“改名成功”写成一次字符串赋值，会漏掉 revision、失败恢复和下一次 ready event。它其实是一条小型提交协议。

读代码时可以先画三条线

我现在看会话选择器，会先把同一个操作沿三条线展开：

用户动作 -> 可用动作集合 -> controller dispatch
会话切换 -> 新 runtime owner -> projection reset/history snapshot
元数据写入 -> revision commit -> durable row + typed event

第一条线负责“用户能不能选”；第二条线负责“屏幕和会话是不是同一个”；第三条线负责“改动能不能在下一次恢复后继续成立”。这三条线都通过，picker 才不只是一个看起来能用的列表。

Orca 的这组修复给我的启发很具体：TUI 里最危险的 bug，通常不是某个按键没有响应，而是动作、身份和投影在不同时间点各自向前走了一步。先把当前 session id 作为动作生成的输入，再用 reset 和 typed snapshot 管住切换，最后用 revision 把标题写回同一个 owner，很多“偶尔显示错了”的问题才有机会变成可测试的不变量。

源码依据：crates/orca-tui/src/session_picker_actions.rs L32-L56、L401-L430；crates/orca-tui/src/app.rs L4102-L4151、L8339-L8381；crates/orca-tui/src/types.rs L448-L459、L2610-L2629；修复提交 c055cd955、829b744b8。

前端看后端 15：什么是 DNS？

颜进强 — Sat, 08 Aug 2026 03:29:06 GMT

专栏第十五篇，网络与协议篇第八章。上一篇我们聊了 CORS，搞懂了浏览器为什么要"扣押"你的响应。但在那之前，浏览器还得先找到服务器在哪——你输入 google.com，它怎么知道该连哪台机器？毕竟计算机只认 IP 地址，可没人会背 142.250.72.206 这种数字。这中间的翻译官，就是今天的主角：DNS（域名系统）。它是整个网页访问之旅的"第一块多米诺骨牌"，也是面试高频考点。

一、DNS 是什么？——互联网的电话簿

DNS = Domain Name System（域名系统）。

一句话：DNS 是互联网的"电话簿"——把人类可读的域名（google.com）翻译成机器可读的 IP 地址（142.250.72.206）。

为什么需要它？

计算机在网络上通信，靠的是 IP 地址（如 192.168.1.1 或 IPv6 的 2001:db8::1）。但人类记数字的能力实在堪忧：

人类喜欢	机器需要
`google.com`	`142.250.72.206`
`baidu.com`	`110.242.68.66`
`bilibili.com`	`119.3.70.xxx`

DNS 就是解决这个"人机语言不通"问题的翻译官。

💡 类比：DNS 就像手机通讯录。你点一下"妈妈"就能拨出去，不用背 +86 138xxxx。通讯录帮你把名字翻译成号码，DNS 帮你把域名翻译成 IP。

二、DNS 解析的完整流程（面试必考）

当你在浏览器输入 https://www.google.com 并回车，到拿到 IP 地址，中间经历了 8 个步骤。这是面试最常考的内容，建议截图保存。

1. 浏览器缓存 → 2. 系统缓存 → 3. 本机 hosts 文件
                                        ↓
4. 本地 DNS 服务器（LDNS，通常是你的路由器或运营商）
                                        ↓
5. 根 DNS 服务器（Root） → 告诉你 .com 在哪
                                        ↓
6. 顶级域 DNS（TLD，.com 服务器） → 告诉你 google.com 的权威 DNS 在哪
                                        ↓
7. 权威 DNS 服务器（Authoritative） → 返回 www.google.com 的 IP
                                        ↓
8. 浏览器拿到 IP，开始 TCP 握手 + TLS + HTTP 请求

逐步拆解

1️⃣ 浏览器缓存

浏览器会缓存 DNS 结果（Chrome 默认 60 秒到几分钟不等）。先查自己有没有，有就直接用。

2️⃣ 系统缓存

浏览器没命中，就问操作系统。Windows 调用 gethostbyname，Linux/Mac 读取 /etc/resolv.conf 里配置的 DNS 服务器。操作系统自己也有一层缓存。

3️⃣ hosts 文件

系统缓存也没有，查 hosts 文件：

Windows：C:\Windows\System32\drivers\etc\hosts
Linux/Mac：/etc/hosts

这是程序员最常用的"本地 DNS 劫持"手段：

# 开发环境常用
127.0.0.1       localhost
192.168.1.100   api.dev.com

4️⃣ 本地 DNS 服务器（LDNS）

hosts 也没命中，请求才真正发出去，送到本地 DNS 服务器（通常由你的 ISP 提供，如电信的 114.114.114.114，或你手动配的 Google 8.8.8.8）。LDNS 自己也有缓存，如果有就直接返回——大部分情况下，DNS 查询在这一步就结束了。

5️⃣ 根 DNS 服务器

LDNS 没缓存，就去找根服务器。全球只有 13 组根服务器（编号 A-M）。根服务器不直接解析域名，它只告诉你：".com 域的 TLD 服务器在这。"

6️⃣ 顶级域 DNS（TLD）

LDNS 拿着根服务器的指引，去找 .com 的 TLD 服务器。TLD 查了查，告诉你："google.com 的权威 DNS 是 ns1.google.com，你去找它。"

7️⃣ 权威 DNS 服务器

LDNS 终于找到 google.com 的权威 DNS，这里才真正返回 www.google.com 的 IP 地址（142.250.72.206）。权威 DNS 是域名所有者自己配置的，你在阿里云/Cloudflare 买的域名，那里配的记录就存在权威 DNS 上。

8️⃣ 返回并缓存

LDNS 把结果返回给你的电脑，并按 TTL 缓存起来。浏览器也开始缓存，接下来就可以进入 TCP 握手、TLS 握手、发 HTTP 请求了。

⏱️ 耗时：整个过程通常在 几十毫秒到几百毫秒。如果 LDNS 有缓存，甚至 < 1ms，你根本感知不到。

三、DNS 记录类型（重点）

DNS 不只是存 A 记录（域名→IP），它有十几种记录类型。作为工程师，这几种必须认识：

记录类型	作用	例子
A	域名 → IPv4 地址	`google.com → 142.250.72.206`
AAAA	域名 → IPv6 地址	`google.com → 2607:f8b0:4005:...`
CNAME	域名别名 → 另一个域名	`www.google.com → www.l.google.com`
MX	邮件服务器	`google.com → smtp.google.com`
NS	指定该域名的权威 DNS	`google.com → ns1.google.com`
TXT	文本记录（SPF、域名验证）	`google.com → "v=spf1 include:_spf.google.com ~all"`
PTR	IP → 域名（反向解析）	`8.8.8.8 → dns.google`
SOA	区域起始授权记录	包含主 DNS、管理员邮箱、刷新时间等
SRV	服务定位记录	`_xmpp-server._tcp.gmail.com`
CAA	指定哪些 CA 可以签发证书	`google.com → 0 issue "pki.goog"`

最常用的三类

1. A 记录（Address）

最基础的映射：域名 → IPv4。配网站、配接口，第一个要加的就是 A 记录。

2. CNAME（Canonical Name）

把一个域名指向另一个域名（注意：不能直接指向 IP）。

images.google.com  CNAME  www.l.google.com
www.l.google.com   A      142.250.72.206

好处：当 www.l.google.com 的 IP 变了，images.google.com 自动跟着变，不用改两条记录。CDN 厂商最喜欢让你 CNAME 到他们的域名，就是这个原因。

3. MX 记录（Mail Exchange）

指定邮件服务器。发邮件到 alice@gmail.com 时，发件方 DNS 查 gmail.com 的 MX 记录，找到 Gmail 的邮件服务器，然后投递。MX 记录还能带优先级（数字越小越高）。

四、DNS 的应用场景（重点）

DNS 远不止"把域名变 IP"这么简单，它在现代架构中扮演着核心调度角色。

1️⃣ 网站访问（基础场景）

最经典的用法。用户访问 taobao.com，DNS 返回淘宝服务器的 IP，浏览器才能建立连接。

2️⃣ CDN 调度（智能解析）

CDN 厂商（Cloudflare、阿里云 CDN）通过 DNS 实现就近接入：

用户在北京 → DNS 返回 北京节点的 IP
用户在上海 → DNS 返回 上海节点的 IP
用户在国外 → DNS 返回 美国节点的 IP

这就是所谓的 GeoDNS，根据用户的地理位置返回最近的 CDN 边缘节点 IP。

3️⃣ 负载均衡（DNS Round Robin）

一个域名对应多个 IP，DNS 轮询返回：

api.example.com  A  10.0.0.1
api.example.com  A  10.0.0.2
api.example.com  A  10.0.0.3

每次 DNS 查询，DNS 服务器按顺序返回不同的 IP，实现简单的负载均衡。

缺点也很明显：DNS 缓存会导致流量分布不均；一台机器挂了，DNS 还会继续返回它的 IP。所以 DNS 轮询通常只作为第一层负载均衡，后面还要配合 Nginx/LVS 等。

4️⃣ 服务发现（微服务）

微服务架构中，服务实例动态变化，IP 随时在变。DNS 可以作为服务发现机制：

user-service.default.svc.cluster.local → 10.244.1.5
user-service.default.svc.cluster.local → 10.244.2.7

Kubernetes 就用 CoreDNS 做服务发现，Service 名 → ClusterIP 的解析全靠它。

5️⃣ 高可用与故障转移

通过降低 TTL，当主服务器宕机时，快速修改 DNS 记录指向备用服务器。但因为各级缓存的存在，切换不是秒级的，通常有几分钟延迟。

6️⃣ 邮件系统

MX 记录指定邮件服务器，SPF/DKIM/DMARC 通过 TXT 记录验证邮件合法性，防止伪造和钓鱼。

7️⃣ 内网服务命名

公司内部用 DNS 代替记 IP：

mysql.internal   → 10.0.0.100
redis.internal   → 10.0.0.101
jenkins.internal → 10.0.0.102

没人愿意背 IP，内网 DNS 是提升幸福感的基础设施。

五、DNS 的 TTL（生存时间）

每条 DNS 记录都有一个 TTL 值（单位：秒），告诉缓存服务器"这个结果多久内有效"。

www.example.com.  300  IN  A  93.184.216.34

TTL=300 秒（5 分钟）意味着：LDNS 缓存 5 分钟，期间所有对这个域名的查询都直接返回这个 IP，不再去问权威 DNS。

TTL 的权衡：

TTL 短（如 60 秒）：故障转移快，但 LDNS 查询频率高，解析慢，权威 DNS 压力大。
TTL 长（如 86400 秒 = 1 天）：解析快，缓存命中率高，但 IP 变更后要等缓存过期，切换慢。

最佳实践：正常情况下 TTL 设较长（如 3600 秒 = 1 小时）；变更前临时调短（如 60 秒）；变更完成后再调长。

六、DNS 的安全与隐私

DNS 从设计之初就没考虑安全，所以这些年补了不少补丁。

1. DNS 污染（DNS Spoofing）

攻击者伪造 DNS 响应，让你访问假网站（比如把 taobao.com 指到钓鱼站点）。

防御：DNSSEC（DNS Security Extensions）给 DNS 记录加数字签名，客户端可以验证响应是否被篡改。

2. DNS 劫持

运营商或中间人篡改 DNS 查询结果，强行跳转到广告页。你有没有过访问一个网站却跳到运营商导航页的经历？那就是 DNS 劫持。

防御：DoH（DNS over HTTPS）或 DoT（DNS over TLS），把 DNS 查询也加密，中间人就看不到也改不了了。

3. 隐私泄露

传统 DNS 查询是明文的，ISP（或任何网络中间人）能看到你访问了哪些网站。

解决方案：

DoH：DNS over HTTPS，走 443 端口，和普通 HTTPS 流量混在一起。Firefox、Chrome 都支持。
DoT：DNS over TLS，走 853 端口。
DNS over QUIC：新兴方案，基于 QUIC 协议，性能更好。

七、公共 DNS 服务

服务商	IPv4	特点
Google Public DNS	`8.8.8.8` / `8.8.4.4`	全球最快之一
Cloudflare	`1.1.1.1`	注重隐私，支持 DoH/DoT
国内 114	`114.114.114.114`	国内速度快
阿里 DNS	`223.5.5.5` / `223.6.6.6`	国内稳定
OpenDNS	`208.67.222.222`	有内容过滤

开发调试常用：8.8.8.8 或 114.114.114.114。

八、常用命令与工具

排查 DNS 问题时，这些命令是你的好帮手。

1. `nslookup`（简单查询，跨平台）

nslookup google.com
nslookup -type=MX google.com       # 查 MX 记录

2. `dig`（详细查询，Linux/Mac）

dig google.com                     # 查 A 记录
dig +trace google.com              # 追踪完整解析链（根→TLD→权威）
dig @8.8.8.8 google.com            # 指定 DNS 服务器
dig -t AAAA google.com             # 查 IPv6

dig +trace 能让你亲眼看到解析是怎么一步步从根服务器走到权威 DNS 的，强烈建议自己试一次。

3. `host`

host google.com
host -t MX google.com

4. `ping`（间接测试）

ping google.com   # 先触发 DNS 解析，再发 ICMP 包

如果 ping 一个域名能通但 curl 不通，至少说明 DNS 解析没问题。

5. 在线工具

whatsmydns.net：全球 DNS 传播查询，改完记录后看各地是否生效。
dnschecker.org：多节点 DNS 验证。

九、串联整个通信系列

到这里，我们终于可以把前面所有知识串成一条完整的"网页访问之旅"了：

1. 用户在浏览器输入 https://www.google.com
   ↓
2. DNS 解析（本篇主角）
   - 浏览器缓存 → 系统缓存 → hosts → LDNS → 根 → TLD → 权威 DNS
   - 拿到 IP: 142.250.72.206
   ↓
3. TCP 三次握手（第 08 篇 TCP/IP）
   ↓
4. TLS 握手（HTTPS 加密协商）
   ↓
5. HTTP 请求发送（第 09 篇 HTTP / 第 10 篇 RESTful）
   - 如果是跨域，还会有 CORS 预检（第 14 篇 CORS）
   ↓
6. 服务器处理
   - 检查 Cookie/Session 验证身份（第 13 篇）
   - 可能调用内部 gRPC 服务（第 11 篇）
   - 或查询数据库、缓存
   ↓
7. HTTP 响应返回
   ↓
8. 浏览器渲染页面
   - 如果页面有 WebSocket，会升级连接（第 12 篇）
   - 如果页面有 API 调用，又会回到第 2 步

DNS 是整个过程的"第一块多米诺骨牌"——它不倒，后面全玩完。

十、总结

DNS 是什么：互联网的电话簿，域名 ↔ IP 的翻译系统。
解析流程：浏览器缓存 → 系统缓存 → hosts → LDNS → 根 → TLD → 权威 DNS（8 步，面试必背）。
核心记录：A（IPv4）、AAAA（IPv6）、CNAME（别名）、MX（邮件）、NS（权威）、TXT（文本验证）。
应用场景：网站访问、CDN 智能调度、负载均衡、K8s 服务发现、邮件系统、高可用切换。
TTL：平衡解析速度与变更灵活性的关键参数，变更前调短、变更后调长。
安全：DNSSEC 防污染，DoH/DoT 防劫持和保护隐私。
调试工具：dig、nslookup、host、ping，以及 whatsmydns.net。

写在最后

DNS 是那种"日用而不知"的基础设施——你每天上网几百次，每次都要用它，但很少有人能完整说清解析流程。理解它最大的价值，不只是应付面试，而是当你遇到这些问题时不再抓瞎：

为什么改了 DNS 记录，有的用户立刻生效、有的要等半天？（TTL + 各级缓存）
为什么配了 CDN 还是慢？（GeoDNS 调度错了节点）
为什么域名能 ping 通但浏览器打不开？（可能是 hosts 被改了，或 DNS 被劫持）
为什么 Kubernetes 里 Service 名能直接当域名用？（CoreDNS 在做服务发现）

下一篇，我们来聊一个你天天在配、却未必真正理解的概念：什么是端口？一台服务器只有一个 IP，为什么能同时跑网站、数据库、邮件那么多服务？80、443、3306、8080 这些数字背后到底是什么？端口和进程又是怎么对应起来的？敬请期待。

如果这个系列对你有帮助，欢迎点赞、关注、收藏三连，我们下篇见 👋

15天学会AI应用开发（十九）使用LangGraph实现持久记忆功能

aqi00 — Sat, 08 Aug 2026 03:28:28 GMT

上一篇文章介绍了如何使用InMemoryStore实现用户偏好的精确记忆功能，但记忆只保留在内存中，一旦AI应用重启，就会丢失上次在内存中的记忆数据。

为了让AI应用持久记忆业务数据，就得引入文件或者数据库等存储介质，比如Python自带的轻量级数据库SQLite。接下来就介绍如何结合LangGraph与SQLite实现业务数据的持久记忆功能。

一、Python中的SQLite用法

安装Python时已经自带了SQLite包，在代码开头添加下面导包语句，即可引入SQLite包：

import sqlite3

sqlite3的connect方法可创建SQLite的数据库连接，同时指定数据库的文件名称及其保存路径。若只填数据库文件名，则默认保存在当前程序目录下。
connect方法返回的连接类型为Connection，它的常用方法说明如下：

backup：备份数据库。
close：关闭数据库连接。
commit：提交数据变更。
rollback：回滚数据变更。

二、LangGraph中的SQLite组件

LangGraph中的SQLite组件包括SqliteStore和SqliteSaver，其中SqliteStore位于langgraph包，而SqliteSaver位于langgraph-checkpoint-sqlite插件。

在命令行窗口执行下面命令，即可安装LangChain及其用到的Ollama插件，以及数据库记忆功能需要的LangGraph及其SQLite插件：

pip install langchain langchain-core langchain-ollama langgraph langgraph-checkpoint-sqlite

由于之前使用的离线大模型Qwen2:1.5B不支持tool工具调用，因此得下载支持tool工具调用的离线大模型Qwen2.5:3B，也就是在命令行窗口执行下面命令，即可下载大模型qwen2.5:3b：

ollama pull qwen2.5:3b

等待大模型下载完毕，在命令行窗口执行下面命令，即可启动Ollama并加载大模型：

ollama serve

三、使用SQLite组件持久保存偏好数据

与之前使用InMemoryStore保存记忆数据相比，引入SQLite插件之后的代码修改部分说明如下：

1、先导入SQLite状态保存器SqliteSaver和SQLite数据保存器SqliteStore的所在包，接着创建SQLite数据库连接，再根据数据库连接分别创建状态保存器实例和数据保存器实例。示例代码如下：

import sqlite3
# 使用SqliteStore替换InMemoryStore
from langgraph.store.sqlite import SqliteStore
from langgraph.checkpoint.sqlite import SqliteSaver

# 创建数据库连接
check_conn= sqlite3.connect("agent.db", check_same_thread=False, isolation_level=None)
# 状态保存器，保存对话线程运行状态，自动建 checkpoints / writes 表
checkpointer = SqliteSaver(check_conn)
# 创建数据库连接
store_conn= sqlite3.connect("agent.db", check_same_thread=False, isolation_level=None)
# 数据保存器，保存用户事实 / 工具记忆，自动建 store_namespaces / store_items 表
store_db = SqliteStore(store_conn)

2、在创建大模型实例时，既要将温度参数temperature设为0表示严格按照提示词执行，也要将工具选择参数tool_choice设为any表示强制模型必须调用工具。示例代码如下：

llm = ChatOllama(
    model="qwen2.5:3b",
    temperature=0.0,  # 0温度，消除随机胡思乱想，严格按prompt执行
    num_ctx=8192
    )
# 关键：提前绑定工具+强制工具策略
tools_list = [remember_user_preference, get_user_preference]
# tool_choice="any" 等价required，强制模型必须输出工具调用
llm_temp = llm.bind_tools(tools_list, tool_choice="any")

3、在调用create_agent创建智能体实例时，把store参数改为上一步创建的数据保存器实例store_db，把checkpointer参数改为上一步创建的状态保存器实例checkpointer；还要编写提示词参数system_prompt，指定详细的工具调用规则。示例代码如下：

# 用户提到喜欢什么东西时，会调用remember_user_preference工具；用户询问喜欢什么东西时，会调用get_user_preference工具。
agent = create_agent(
    model=llm,
    context_schema=Context,
    tools=tools_list,
    store=store_db,
    checkpointer=checkpointer,
    system_prompt="""
    你是用户记忆助手，严格遵守以下规则：
    1. 只要用户主动说出自己的喜好、偏好（比如喜欢的颜色、食物、风格），**无论之前是否存储过同类偏好，就必须调用 remember_user_preference 工具更新覆盖**，不能跳过工具直接回答；
    2. 只要用户主动询问自己的偏好，就调用 get_user_preference 工具查询；
    3. 禁止省略存储工具：用户修改原有喜好，必须调用工具更新数据；
    4. 工具调用完成后，再向用户自然回复。
    """
)

4、在调用智能体实例的invoke方法时，增加传入config参数，指定SQLite组件所需的线程编号。示例代码如下：

    # 调用离线大模型
    result = agent.invoke(
        {"messages": [HumanMessage(content=user_input)]},
        context=Context(user_id="user_123"),
        config={"configurable": {"thread_id": "session-001"}}
    )

运行修改后的Python代码，根据提示输入问题内容“我喜欢蓝色”，输出日志结果如下：

用户：我喜欢蓝色
AI：我已经记住了，你现在喜欢的颜色是蓝色。如果你有其他颜色的偏好或者想要改变现有的偏好，请告诉我！

停止当前AI应用进程，重新运行Python代码，根据提示输入问题内容“我喜欢什么颜色？”，输出日志结果如下：

用户：我喜欢什么颜色？
AI：您现在最喜欢的颜色是蓝色。如果有其他问题或需要进一步帮助，请随时告诉我！

由日志信息发现，在应用程序重启前后，AI应用均能正确回答用户的颜色偏好，并且当前目录找到了数据库文件agent.db。可见在引入LangGraph的SQLite组件之后，LangChain成功实现了用户数据的持久记忆功能。

本系列的AI应用开发文章目录为《15天学会AI应用开发全目录（零基础小白，零Token消耗）》。

AI 编程

我用agent做了个运动打卡数据治理流程

介绍

主要痛点

要解决的问题

核心思路

具体操作步骤

第一步 让 TRAE Work 下载资料、识别数据并生成 CSV

第二步 导入数据库并完成人工核查

第三步 展示统计结果

第四步 通过智能问数继续分析

成效如何

如何复用

总结

解剖 Claude Code：从入口架构逆向工程看 AI 编程工具的信任边界设计

一、架构解构法：入口文件是一个无法自欺的地方

cli.tsx：一个被伪装成入口的路由表

feature()：编译时就把代码删掉

ABLATION_BASELINE：为什么这段代码必须放在入口

init.ts：启动决策链就是信任决策链

从入口层能确认的几件事

二、工程度量法：复杂度治理的六个侧面

目录拓扑：35 个一级目录的分工

大文件分布：复杂度淤积在接缝处

commands.ts：755 行的命令装配车间

Tool 接口：46 个工具共用一套契约，默认不信任

BashTool/prompt.ts：369 行的工具说明书

filesystem.ts：1778 行的路径攻防

三、对比参照法：三种路线，一种演化方向

参照系一：VSCode Copilot——扩展路线

参照系二：Cursor——IDE 原生路线

参照系三：GitHub CLI——纯 CLI 路线

四个坐标的对照

四、深层启示：信任半径、接缝淤积与智能体的安全底座

启示一：把启动序列当作一条有安全分区的流水线

启示二：特性裁剪尽量发生在编译时

启示三：扩展接口的默认值决定生态的安全水位

启示四：把提示词当代码管理

启示五：复杂度会淤积在接缝处

启示六：智能体产品的差异，沉淀在"模型能安全够到多少东西"上

结语：读代码，就是读决策

用 AI 写代码半年，他忘了怎么手写 JSON

人类一直在进行认知外包

AI 不同的地方，是它开始接近判断过程

被外包出去的是判断

AI 重构大型项目没有想象中简单

区分效率提升和能力成长

Qwen 3.8 max干了20分钟没干完，免费模型3分17秒搞定，问题出在哪？

先说句公道话，Qwen 3.8 max的跑分是真能打

跑分为啥救不了你的项目？

Qwen 3.8 max还是是干活太认真了

一杯咖啡的钱，买了个教训

最后说两句

复制成功，不等于文章能发布：markdown2x 如何拆开富文本与图片资产

先得到文档结构，再决定怎么交付

一个复制按钮，实际写入两份正文

代码、表格和 Mermaid 被当成另一类工件

Preflight 能发现问题，但目前不会拦住复制

转换工具真正交付的是失败边界

Han：一个让 AI Agent 也能做出高级中国风页面的 CSS 设计系统

一句话介绍：它是个啥？

能做什么？直接看例子

1. 茶叶品牌 — 松麦主题

2. 美妆护肤 — 藤紫主题

3. AI 科技产品 — 海兰主题

4. 精品咖啡 — 焦糖主题

5. 瑜伽健康 — 薄荷主题

6. 甜品节活动 — 莓果主题

7. Mac 产品概念页 — 宋韵主题

8. 软件产品官网介绍

9. 当代配色主题总览

核心能力：不只是好看

22 个主题，总有一个对味

组件都有，而且不土

AI Agent 能自己干活

该有的工程素质都有

怎么用？

方式一：作为 Agent Skill 安装

方式二：直接用 CSS

适合谁用？

第一步　让 TRAE Work 下载资料、识别数据并生成 CSV

第二步　导入数据库并完成人工核查

第三步　展示统计结果

第四步　通过智能问数继续分析

4. `0.0.0.0` vs `localhost`