前言

从最早思考《为什么要做一个 iOS bug 自动修复的 agent 程序》，到 V3 把单文件原型重构成 AgentEngine 引擎、V4 把领域知识结构化、V5 把「完成需求开发」提成唯一 P0 并引入 Pipeline 编排基座，这个项目断断续续做了两个月。之前我写过一篇《从 Bug 修复到需求开发：iOS AutoFix Agent 的 V3-V5 演进之路》，把版本演进的脉络讲清楚了。

接下来我的重心会转到和其他同学共建另一个 Agent 项目上。所以趁记忆还热乎，给 iOS AutoFix 做一份阶段性收尾——这篇不再复述版本演进，而是把这一年踩过坑、验证过的与领域无关、可以直接搬到下一个 Agent 项目的工程经验沉淀下来。

一句话定位整个项目的终态：

V4 解决「能不能定位/修复一个 Bug」，V5 把「完成一个需求开发」提升为唯一 P0，并引入 Pipeline Orchestrator（流水线编排基座），让 分析 → 设计 → 闸门 → 实现 → 验证 → 评审 以声明式、可配置、支持闸门与智能回退的流水线串起来。

V5 走到了哪里

V5 围绕三条主线展开：

落地形态是一条六阶段需求开发流水线，以一个真实 TAPD 需求为例，全程约 65 分钟、中间两次人工确认：

1
2

① 需求分析 → ② 方案设计 [HumanGate] → ③ 影响评估
   → ④ 代码实现 [事务写入 + 自动回滚] → ⑤ 编译验证 → ⑥ 代码审查

到 V6 雏形，需求开发已经从「勾哪端就各自独立跑 Pipeline」演进到「一个需求、一次整体分析、按涉及端分别落地」——iOS / Android / Kuikly 三端共享一次跨端分析，再并发分端实现，保证跨端协议字段/事件名一致。

当前的分层架构

收尾时整个系统稳定在 5 层。理解这张图，就理解了这个 Agent 的全部骨架：

1
2
3
4
5
6
7
8
9

入口层（CLI / GUI / 企微机器人）
    ↓
Pipeline Orchestrator   —— 按什么顺序跑、卡在哪个闸门、错了怎么退
    ↓
AgentEngine             —— 单个 Agent 怎么跑：循环控制 / 工具分发 / Scratchpad / 对话压缩 / 置信度退出
    ↓
TaskProfile             —— 这一步跑什么：BugLocate / Fix / FeatureAnalyze / FeatureDesign / FeatureImplement / CodeReview / ImpactAnalysis
    ↓
知识 & RAG 层           —— ModuleDoc + CaseDoc + FixRecord，7 路并行召回 + Knot 知识库

最关键的一组抽象，也是这一年最值钱的设计决策：

• Engine 管「怎么跑」，Profile 管「跑什么」。通用的 Agentic Loop（循环、工具分发、压缩、容错）沉到 Engine，场景差异（角色、工具集、退出条件、领域知识）放进 Profile。十几种 Profile 复用同一个 Engine，新增一种任务类型只要写一个新 Profile。
• Pipeline 管「编排」。Engine 只关心单个 Agent 跑完一轮，Pipeline 负责把多个 Stage 串起来，并在阶段转换处插闸门。

可迁移的工程经验

下面这些是我打算带去下一个 Agent 项目的「行李」。它们大多与「修 iOS Bug」这件具体的事无关，是做任何 LLM Agent 都会遇到的问题。

1. 先有编排框架，再往里插能力

最容易犯的错是：先把一个个能力（分析、设计、实现）写成独立脚本，最后再用胶水代码串起来。结果就是回退、重试、断点续跑这些横切逻辑散落在各处。

V5 的做法是反过来——先建 Pipeline 编排基座，每个能力作为一个 Stage 插进去。回退、状态持久化、崩溃恢复、可观测性都由编排层统一提供。Pipeline First 是 V5 九条核心原则里的第一条，事后看这个顺序定对了。

2. 闸门是一等公民 + 智能回退

关键阶段转换处一定要设闸门（Gate），不通过则携带反馈智能回退，而不是直接失败。闸门分三类：

• MetricGate：置信度 / 编译结果等硬指标
• AIGate：用一次独立的 LLM 调用评估上一阶段产物质量
• HumanGate：人工确认（GUI 里做成倒计时确认弹窗）

回退用的是循环模型而非递归：每个 Gate 维护独立的回退计数，避免「设计→实现→验证失败→回设计→又失败」无限套娃。状态用原子写入持久化，进程崩溃能恢复到中断处。

3. 上下文工程：三个反直觉的结论

这是 Agent 工程里水最深的部分，几条经验都和直觉相反：

• 超长 system prompt 会「中段失忆」（Lost in the Middle）。主 Orchestrator 的 prompt 一度超过 350 行，模型对中间部分的遵循率明显下降。解法是分阶段注入：探索阶段只给角色+工具+方向，搜索完才注入评估规则和退出条件，准备提交时才注入「自我质疑」清单。瘦身后 exploration prompt 减了约 70%。
• 压缩会丢掉关键证据。每 5 轮压缩一次对话，会把搜索过程中发现的文件路径、行号、调用链一起压没，导致 Agent 重复搜已经找过的文件。解法是给 Agent 配一个不会被压缩的小本本（Scratchpad）：通过 note_finding 工具写入关键发现，标记 _isScratchpad，压缩时跳过，每轮作为 system message 重新注入。
• 结构化数据 > 报告文本。子代理给主代理传「文本报告」会有信息损失且容易被误解，改成结构化的 keyFiles / codeSnippets / callChains / hypotheses / coverage 后，主代理可以直接引用具体发现。

4. 置信度驱动早停，而不是机械计时器

最初的轮次控制是「第 8 轮提醒、第 12 轮强制提交」这种机械计时器——Agent 可能第 3 轮就找到答案还在空转烧 token，也可能第 12 轮没找到被强行提交。

改成置信度驱动早停：每轮自评置信度，但触发早停要三个条件同时满足——置信度 ≥ 0.8、总发现 ≥ 3、剩余方向全为低优先级。任一不满足就继续，宁可多跑也不「差点找到」漏掉根因。强制提交时打 low_confidence 标记，让下游知道定位可能不准。

5. 工具使用纪律：双层约束

让 Agent 别乱用工具，单靠 prompt 不够。有效的是双层约束协同：

• 工具 description 层（「什么时候该用」）：写前置条件「使用前先 ripgrep 确认目标位置」、范围指引「命中行 ±20 行」、红线「禁止无目标读取 >100 行」。
• Prompt 层（「什么不能做」）：明确列反模式——没 grep 就直接读大段、对低相关匹配反复扩大读取范围、重复读已读过的区域。

两层叠加后，ripgrep 调用从 7 次降到 4 次（**-43%**），平均每次工具调用数从 7 降到 5。

6. 写入安全是红线

只要 Agent 会改用户的代码，写入安全就不能妥协。V5 的红线是四件套：**--confirm 确认 + 事务写入 + 编译验证 + 自动回滚**。代码实现阶段所有写入打包成事务，编译不过就整体回滚，绝不留下半成品。这条在「修 Bug」时还能商量，到「需求开发」要改多文件时就是底线。

7. 改动的「精准性」比「成功率」更重要

修 Bug 最大的风险不是没修好，而是改出新 Bug 或改错位置。让 LLM 生成 diff 时，强制 search 块带上前后 1-2 行上下文确保唯一匹配，而不是只给变更行（LLM 从记忆重建代码会有细微偏差，导致静默匹配失败）。

就这一个约束 + 「最小修改原则」，让修复阶段 Token 从 60K 降到 26K（**-57%**），LLM 调用从 6 次降到 3 次。

8. 可观测性要覆盖事前/事中/事后

• 事前：靠工具 description 和 prompt 预防低效行为；
• 事中：检测工具使用比例（read_file / ripgrep > 2:1 报警）、重复搜索同一文件；
• 事后：earlyTerminationSnapshot 记录早停时跳过了哪些方向，配合 evidenceHitRate / searchEfficiencyRatio / evidenceConsistencyScore 等场景级指标，做基线保存和回归检测。

一组综合优化前后的实测对比（质量指标全部持平的前提下）：

9. 多模型评测与降级链

不要押注单一模型。V5 建了一套 10 分制的多模型评测框架（评估维度：文件定位 25% / 分析深度 25% / 实现计划 20% / 风险识别 15% / 执行效率 15%），跑同一个需求对比：

线上则用降级链（CodeBuddy Claude → GLM → DeepSeek）保可用性，并对不支持 function calling 的模型做 JSON 解析降级。评测决定选型，降级链保底。

10. 知识沉淀要分类，并设晋升路径

知识库不是把文档堆一起。V5 把知识分四类——案例 / 经验 / 记忆 / 索引，共享知识库走独立 git 仓、个人记忆落本地，每条知识带 confidence 和晋升路径（被多次验证的经验才升级为共享知识），并设入库准入条件和触发器。这样知识库才不会越长越脏。

诚实的局限：为什么在这个点暂停

核心闭环已经成形，剩下的是打磨，所以这是个合理的暂停点。但有几处确实没做完，留个记录：

• 跨端 analyze 还没真正复用（Phase B）：V6 目前是把跨端整体方案作为 additionalContext 注入各端，各端仍会冗余跑一遍自己的 analyze，时间有浪费。彻底的做法是用 preloadedAnalysis 直接跳过各端 analyze stage，但那会侵入 PipelineEngine 内部，风险大，所以先用了轻耦合方案。
• 粗筛权重是手工拍的：5 策略加权（直接路径 100 / SQLite 索引 10-40 / 目录推断 8 / Git 热点 5 / Bug 类型专项 12-15）很难对所有项目通用。正解是用历史定位数据做权重调优，或者干脆让 LLM 直接做粗筛——现在的模型能力够用了。
• 并发统计口径会串：多端并发时 token / 日志统计可能互相累加，不影响功能，但口径乱。
• 旧入口还没收尾：三个分端独立 Tab 仍可见，等新的统一入口稳定后再隐藏。

下一站：共建另一个 Agent

回头看，这一年真正沉淀下来的，不是「怎么修 iOS Bug」，而是「怎么造一个能干活的 Agent」。这两件事可迁移的程度完全不同：

• 可以直接搬过去的（与领域无关）：Pipeline 编排 + 闸门 + 智能回退、Engine/Profile 解耦、上下文工程那三条、置信度早停、写入安全四件套、事前/事中/事后可观测性、多模型评测与降级、知识分类沉淀。
• 必须重做的（iOS 特化）：仓库索引与页面映射表、编译验证（xcodebuild / gradle / KMP）、各端的 Profile 与领域知识。

下一个项目是和其他同学一起共建，正好可以把上面这套「与领域无关的 Agent 骨架」当成共识的起点，少走一遍弯路。iOS AutoFix 这边先告一段落，等下一个 Agent 跑起来，应该还有新的东西可以反哺回来。

总结

如果只能带走三句话：

1. 先有编排，再插能力——横切逻辑（回退/续跑/可观测）必须沉到编排层。
2. Engine 管怎么跑，Profile 管跑什么——这组解耦让一套引擎服务十几种任务。
3. 上下文工程 + 写入安全是 Agent 能不能用的两道生死线——前者决定它聪不聪明，后者决定你敢不敢让它动你的代码。

一、什么是 StoreKit 配置文件

StoreKit 配置文件（.storekit）是 Apple 提供的本地测试环境配置文件，用于在 Xcode 中模拟 App Store 内购行为，无需连接真实的 App Store 服务器。

支持的产品类型

创建方式

Xcode → File → New → File → StoreKit Configuration File
Edit Scheme → Run → Options → StoreKit Configuration（指定文件）

二、本地配置 vs 沙盒测试

三、清除本地购买记录（重置初始态）

方法一：Xcode 菜单（推荐）

Debug → StoreKit → Clear Purchased Products

清除后重新运行 App 即可，无需重启模拟器。

方法二：重置整个模拟器

Xcode → Window → Devices and Simulators
→ 选中模拟器 → Erase All Content and Settings

方法三：代码同步（仅供参考）

#if DEBUG
try await AppStore.sync()
#endif

四、正式上线后的工作原理

.storekit 配置文件只在开发阶段生效，打包上线后自动忽略。

用户点击购买
    ↓
StoreKit 框架（代码不变）
    ↓
请求发往 Apple 生产服务器
    ↓
Apple 处理支付，返回 Transaction
    ↓
App 验证收据 → 解锁内容

三种环境对比

关键点

• .storekit 文件是"假数据源"，上线后真实数据全部走 Apple 服务器
• StoreKit 是框架（API） ，在三种环境下代码本身不变，变的是背后连接的服务器
• 用户购买记录永久保存在 Apple 账户中，restore purchases 从 Apple 服务器拉取
• 上线后需要对 Apple 服务器签发的收据进行验证（客户端或服务端）

动画的声明式表达是 SwiftUI 的核心优势之一。但在某些场景里，结果并不总像我们期待的那样平滑。一个典型例子是：当 `List` 行内的内容高度发生动态变化——副标题从空变为非空、文本因更新而导致行数变化——系统自带的布局引擎往往无法给出连续的过渡动画。本文从这个现象出发，逐层拆解原因，给出一种完全基于 SwiftUI 原生能力的解决方案；也借这条路径回看 SwiftUI 在布局机制层面的几个关键约束。

Dave Verwer 在 iOS Dev Weekly 第 751 期宣布，这份已经持续近 15 年的周报将交由新的团队继续运营，而他自己接下来会全职投入 Swift Package Index。我的博客在早期获得关注，也曾得益于 iOS Dev Weekly 的推荐；而我在周报中坚持撰写每期周评，同样在很大程度上受到 Dave Verwer 的启发。对于很多 Apple 平台开发者来说，iOS Dev Weekly 早已不只是一份链接合集。它既是社区路标，也是长期陪伴。

从 Bug 修复到需求开发：iOS AutoFix Agent 的 V3-V5 演进之路

在上一篇文章里，我解释了为什么选择自建 Agent 架构，而不是做 IDE 插件——核心在于要拥有”流程控制权”，而不是”平台适配权”。

那篇文章写完后，系统先后经历了 V3、V4、V5 三个大版本的迭代。我打算在这篇里把这段演进过程讲清楚：每一版做了什么、为什么这么做、踩了什么坑、优化思路是什么。

一、V3：从单文件到引擎架构

问题起点

V2 的核心问题是：代码全部堆在一个 1100+ 行的 PreciseLocator.ts 文件里。prompt 编排、工具分发、Agent 循环、评估逻辑全部混在一起，新增任何功能都要触碰这个巨型文件。更重要的是，V2 在复杂 Bug 上能力不足——8 轮搜索子代理、每轮只有 2-3 个工具调用，对于需要追踪多层调用链的 Bug，搜索深度明显不够。

架构重构：AgentEngine + TaskProfile

V3 的首要任务是拆文件，但不是机械地拆，而是找到正确的分层方式：

1
2
3
4
5
6
7
8
9
10

AgentEngine（通用执行核心）
  ├── 循环控制
  ├── 工具分发
  ├── 对话压缩
  └── 容错与重试

TaskProfile（场景差异层）
  ├── BugLocateProfile
  ├── CodeLocateProfile
  └── CodeAnalysisProfile

Engine 负责”怎么跑”，Profile 负责”跑什么”。新增任务类型只需实现新 Profile，不用改 Engine。这个模式后来证明极其有价值——V4、V5 的十几种 Profile 都复用了同一个 Engine。

子代理能力强化

架构拆完之后，重点放在增强子代理的搜索能力：

其中最有意思的是强制提交轮的上下文压缩。V2 时，子代理在强制提交轮（第 14-15 轮）拿到的是完整的历史消息，约 100K tokens。LLM 面对这么大的上下文，实际有效处理率只有 33%。V3 把强制提交轮的 context 压缩为约 15K 的结构化摘要，有效率直接从 33% 拉到 100%。

渐进式催促机制

V2 只有两段式控制：第 8 轮”给你个激励”，第 14-15 轮”强制提交”。V3 换成了 4 级渐进催促：

1
2
3
4
5

Round 1-7:   自由搜索
Round 8:     💡 中途评估，收敛方向
Round 9:     ⚠️ 剩余轮次不多
Round 10:    🚨 最后搜索机会
Round 11-12: 🔒 移除搜索工具，仅保留 submit_result

从用户体验角度看，这很像给实习生分配任务时的跟进节奏——不是一上来就催，而是在关键节点给出提示，让他有机会自我调整。

性能对比

二、V4：领域知识沉淀与可观测性

V4 是个大版本，做的事情很多，但有一条清晰的主线：**从”能定位”到”知道自己在做什么”**。

引擎内核的四个关键优化

基于对 V3 的深度审查（是的，我用 LLM 跑了一次完整的 Code Review），发现了四个核心问题，V4.3 全部解决：

1. 分阶段 Prompt 注入

V3 的主 Orchestrator 有 350+ 行系统 prompt，角色定义、工具说明、bug 类型分类、退出条件全部揉在一起。LLM 在超长 prompt 中有著名的”Lost in the Middle”问题——中间部分指令遵循率明显下降。

解决方案是把 prompt 按任务阶段动态注入：

• 探索阶段：只给角色 + 工具 + bug 类型
• 分析阶段：注入评估规则
• 提交阶段：注入三问法和退出条件

2. Scratchpad 结构化草稿板

V3 每 5 轮压缩一次对话，问题是关键的文件路径、行号、调用链会在压缩中丢失，Agent 可能在后续轮次重复搜索已经找过的文件。

V4 引入了 Scratchpad：Agent 可以通过 note_finding 工具主动记录关键发现，这些记录被标记为 _isScratchpad: true，压缩时跳过，每轮注入为 system message。等于给 Agent 配了一个不会被压缩的小本本。

3. 置信度驱动退出

把”第 12 轮强制停”改为”置信度 ≥ 0.85 时可提前停”。不只是节省 token，更重要的是让 Agent 的退出决策与任务完成质量真正绑定，而不是靠”计时器”。

4. 结构化搜索结果传递

V3 的子代理提交一份文本报告，主 Agent 从文本里提取发现——有信息损失，且可能误解。V4 改为结构化数据传递：

1
2
3
4
5

interface StructuredSearchResult {
  keyFiles: Array<{ path: string; relevance: number; summary: string }>;
  findings: Array<{ file: string; lines: [number, number]; content: string }>;
  hypotheses: Array<{ description: string; confidence: number; evidence: string[] }>;
}

BugTypePolicy：领域知识结构化

V3 有 11 种 bug 类型的支持，但相关的搜索策略、分析维度、退出条件都硬编码在一个巨大的 switch-case 里。V4 把它重构为 BugTypePolicy 注册表——每种 bug 类型有独立的策略文件，PolicyRegistry 负责查找和组合。

这解决了一个本质问题：领域知识和执行逻辑分离。现在增加一种新的 bug 类型，只需要写一个策略文件，不用改 Agent 循环代码。

RAG 知识库

V4 引入了两层知识系统：

• ModuleDoc：模块级别的架构文档，通过 DocGen 命令自动生成
• CaseDoc / FixRecord：历史成功修复案例，每次 fix 成功后自动入库

RAG 检索有 7 条并行路径（全文检索 / 路径匹配 / 符号检索 / 依赖关系 / 案例模块 / 历史修复记录 / Knot 知识库），每条路径独立计算命中率，可以在 Metrics 里看到哪条路径最有价值。

Metrics 可观测性体系

V4 构建了完整的可观测性体系：

• 搜索质量指标：工具调用分布、计划命中率、方向利用率、证据一致性分数
• 成本效率指标：每结果 Token 消耗、按模型估算 USD 花费
• 历史聚合报告：npm run metrics，按命令/日期汇总，sparklines 趋势可视化
• 基线评测：--save-baseline 保存基线，--check-baseline 回归检测

这套体系解决了一个关键问题：不再靠”感觉”来判断系统有没有在变好。每次改动都能用数据说话。

多架构 TrackingModel

iOS 项目有 MVC、MVVM、VIPER 等多种架构，每种架构的数据流层次不同，定位路径也不同。V4 把追踪模型做成了可配置的 ArchitectureProfile：

1
2
3

MVC_CGI:    UI → 数据装配 → Model → CGI 层
MVVM_CGI:   UI → ViewModel → Model → CGI 层
VIPER:      View → Presenter → Interactor → Entity

在 autofix.config.json 里指定 projectArchitecture，系统自动选用对应的追踪策略。

三、V5：从 Bug 修复到需求开发

V5 是一次战略转向。V4 解决了”能不能修 Bug”的问题；V5 的目标是：能不能让系统完成一个完整的 iOS 需求开发任务。

Pipeline Orchestrator：声明式流水线

V5 引入了 Pipeline Orchestrator 作为核心架构基座。这是把”一组命令串起来执行”升级为”声明式流水线编排”的关键一步。

一条 Pipeline 长这样：

1

[需求分析] → Gate → [方案设计] → Gate → [影响评估] → [代码实现] → [编译验证] → [代码审查]

每个 Gate 可以是三种类型之一：

• MetricGate：置信度阈值、编译结果等指标判断
• AIGate：LLM 评估方案可行性或代码质量
• HumanGate：人工确认（复用 acknowledge 机制，不打断 terminal）

Gate 失败时，系统不是直接报错，而是带着失败反馈回退到指定阶段重新执行。回退上限是双层计数（每个 Gate 独立计数 + 全局总计数），防止死循环。

一个设计细节：纯 Nullability 编译错误（Swift 的 optional 相关警告）不消耗有效 retry 配额。这是因为这类错误往往是模型生成代码时的习惯问题，让它多试几次通常能自己修好，不应该把宝贵的 retry 机会浪费在这上面。

需求开发流水线实战

以一个真实案例说明整个流程：【歌手主页】歌手写真切换交互+基础体验优化（TAPD 需求）。

流水线六个阶段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

① Analyze（需求分析）
  → 输出: 核心文件列表 + 风险点 + 参考实现

② Design（方案设计）
  → 输出: 每个文件的改动路径 + 数据流梳理

③ Impact（影响评估）
  → 输出: 关联模块、上下游影响面

④ Implement（代码实现）
  → 事务写入，编译失败自动回滚重试

⑤ Validate（编译验证）
  → xcodebuild 静态编译 + 语义覆盖率校验

⑥ Review（代码审查）
  → CodeReviewProfile 驱动，critical/warning 级别问题可打回 Implement

全程大约 1 小时 5 分钟，中间两次人工确认（方案设计后、代码实现前），其余步骤全部自动执行。

多模型评测框架

V5 做了一件有意思的事：用同一个需求，分别跑 5 种不同的模型 + 接入方式组合，用 Claude Sonnet 4.6 进行 10 分制精评，验证不同配置下的效果差异。

评估维度：文件定位准确性（25%）、分析深度（25%）、实现计划质量（20%）、风险识别（15%）、执行效率（15%）。

结论很有意思：

V2 效率垫底的根因很清楚：项目类型上下文注入不足——LLM 不知道这是 iOS/ObjC 项目，搜索方向跑偏了。这类问题很容易修，但靠人工 review 日志才能发现。有了系统化的评测框架，这类问题能够被量化追踪。

四、优化思路总结

经历三个版本的迭代，我对 Agent 系统优化形成了几个比较稳定的判断：

1. 双层约束优于单层

改 LLM 行为有两个层面：工具 description 和 Prompt。只改其中一层，效果有限。

以工具使用纪律为例，V5 在工具的 description 里加了明确的使用边界（”使用前先 ripgrep 确认位置，禁止无目标读取 >100 行”），同时在 Prompt 里加了反模式禁止列表。两层协同，ripgrep 调用减少了 43%。

工具层侧重”什么时候该用”，Prompt 层侧重”什么不能做”，互相补充。

2. 保守设计比激进触发安全

以早停机制为例，V5 的场景 B（高质量证据早停）有三个条件必须同时满足：

1. 至少有一个方向置信度 ≥ 0.8
2. 总发现数 ≥ 3
3. 剩余方向全为低优先级

任何一个条件单独满足，都不触发早停。这个保守设计多次避免了因为”差点找到了”而漏掉根因的情况。

3. 事前 + 事中 + 事后的可观测性层次

优化 Agent 有三个时机：

• 事前：通过工具 description 和 Prompt 预防低效行为
• 事中：检测工具使用比例（如 read_file / ripgrep 比 > 2:1 报警）
• 事后：早停快照记录跳过了哪些方向，用于效果回溯

这个分层体系比单纯看”成功率”有价值得多，因为它告诉你为什么成功或失败。

4. 修复精准性比修复成功率更值得关注

V5 优化前，修复阶段 LLM 调用 6 次，Token 60K+，核心原因是搜索块（search block）匹配到了多个位置，修错了地方，然后重试。解决方案很简单：要求 search 块必须包含前后 1-2 行上下文，确保唯一匹配。

改动 10 行代码，修复阶段 Token 下降 57%，LLM 调用从 6 次降到 3 次。

真正的成本不是模型调用费，而是重试浪费的时间。 把匹配精准度做好，比提升模型能力更有效率。

五、当前架构全景

经过 V3-V5 的演进，系统的层次结构已经比较清晰：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

┌──────────────────────────────────────┐
│         入口层                        │
│  CLI / GUI 桌面端 / 企微机器人        │
│         ↓ Intent Router              │
├──────────────────────────────────────┤
│       Pipeline Orchestrator          │
│  声明式流水线 + Gate + 智能回滚        │
│  Bug 修复流水线 / 需求开发流水线       │
│         ↓                            │
├──────────────────────────────────────┤
│       AgentEngine 通用引擎            │
│  循环控制 / 工具分发 / Scratchpad     │
│  对话压缩 / 置信度退出                │
│         ↓                            │
├──────────────────────────────────────┤
│       TaskProfile 策略层             │
│  BugLocate / Fix / FeatureAnalyze    │
│  FeatureDesign / FeatureImplement    │
│  CodeReview / ImpactAnalysis         │
│         ↓                            │
├──────────────────────────────────────┤
│       知识 & RAG 层                   │
│  ModuleDoc + CaseDoc + FixRecord     │
│  7 路并行召回 + Knot 知识库           │
└──────────────────────────────────────┘

入口层做薄，Pipeline 层负责编排，Engine 层通用复用，Profile 层封装差异，知识层持续沉淀。

六、下一步

还有几件事没做完：

1. 并行搜索方向：目前搜索方向是串行执行的，彼此独立的方向完全可以 Promise.all。预期对 3+ 方向的任务，总耗时能再降 40-60%。

2. 搜索结果缓存：同一仓库对同一 pattern 的搜索结果，绑定 Git commit 做缓存。对重复出现的 Bug 类型（比如 accessibility 问题），可以显著减少重复检索。

3. 模型分级调度：现在不同环节用的模型没有明显区分。提取结构化信息、消息摘要这类简单任务，用小模型足够了；精确定位和代码生成，才需要最强模型。分级后成本可以进一步下降。

4. 反馈闭环：CR 通过或拒绝的结果，目前没有系统性地回流到知识库。这个闭环一旦建起来，系统会越来越像”会学习的故障处理平台”。

七、一些反思

回看这三个版本的演进，有几个观察：

架构重构的价值超出预期。 V3 把 1100 行单文件拆成 Engine + Profile 模式，当时以为只是”代码整洁”的问题。但到 V4 需要支持 11 种 bug 类型策略、10+ 种 Profile，到 V5 需要在 Pipeline 里复用这些 Profile 时，这个架构决策带来的红利远远超过了重构的成本。

可观测性不是锦上添花。 没有 Metrics 之前，优化靠直觉。有了 Metrics 之后，每个优化都能量化，失败案例能被追溯，回归能被检测。这套体系建得越早越好。

领域知识的密度决定系统价值。 通用 Agent 框架（循环、工具分发、压缩）是基础设施，可以替换；BugTypePolicy、多架构 TrackingModel、修复策略库、历史案例这些领域资产，才是真正的壁垒。前者越薄越好，后者越厚越值钱。

从”工具”到”流水线”是个重要的认知跃迁。 单个命令（locate / fix / cr）组合使用时需要大量手工协调；Pipeline 把这些步骤声明式地串起来，加上 Gate 和回退，系统才真正具备”替程序员执行一整套流程”的能力，而不只是”帮程序员在 IDE 里更快操作”。

这条路还很长，但方向是对的。

距离 WWDC 2026 只剩下 20 天了。每年到这个时候，我都会看到不少开发者分享自己的 WWDC 愿望单，写下预测与期许。但今年，至少到我汇总本期周报时，这类内容相较去年同期明显少了许多。究竟是开发者对 WWDC 的期待变淡了，还是更多人开始秉持“降低预期才能获得更多惊喜”的心理？

谷歌近期宣布，从下一个 Flutter 稳定版 3.44 开始，Swift Package Manager 将在默认路径上取代 CocoaPods，成为 iOS 和 macOS 应用的默认依赖管理器。CocoaPods 的 Trunk 仓库计划于 2026 年 12 月 2 日正式进入只读状态——这个时间点我们在 2024 年的周报中就讨论过了，但当 Flutter 真正开始在默认路径上用 SPM 替换 CocoaPods 时，还是引发了社区的广泛热议。

With a sufficient number of users of an API, it does not matterwhat you promise in the contract: all observable behaviors of yoursystem will be depended on by somebody. — Hyrum's Law

In a compiler, the most common form of Hyrum's Law is dependence onunspecified behavior — hash bucket order, the order of equalelements after std::sort, padding offsets. The same framingcovers a few cases that are technically undefined behavior (use of aninvalidated iterator) or plain incidental properties (ABI struct layout,ELF section offsets).

When the compiler itself harbors such a dependency, the symptom isusually output that varies build-to-build: an unstable sort that landsdifferently after the standard library changes, a hash map whoseiteration order shifts when the hash function does. Occasionally thevariation is run-to-run within a single build —DenseMap<void *, X> keys with an ASLR-derived seedreorder buckets each invocation. Either way, reproducible builds,bisection, and bug reports all assume same input → same output, and astealth Hyrum dependency breaks that.

This post surveys some mechanisms that perturb the contract's blindspots so dependencies cannot quietly form.

Hash seed perturbation

The first line of defense is the hash function itself.llvm/include/llvm/ADT/Hashing.h:

1
2
3
4
5
6
7
8

inline uint64_t get_execution_seed() {
#if LLVM_ENABLE_ABI_BREAKING_CHECKS
  return static_cast<uint64_t>(
      reinterpret_cast<uintptr_t>(&install_fatal_error_handler));
#else
  return 0xff51afd7ed558ccdULL;
#endif
}

The seed XORed into every llvm::hash_value is theruntime address of install_fatal_error_handler — underASLR, different every process. The header comment is explicit:

the seed is non-deterministic per process (address of a functionin LLVMSupport) to prevent having users depend on the particular hashvalues.

Every hash_combine / hash_integer_valuecall picks up the seed, and every DenseMap<K, V>keyed by a hash_value-using type then reorders its bucketsper run. MD5, BLAKE3, SHA1, SHA256 stay byte-stable — those are theright tools when you actually want a digest.

My commitce80c80dca45 introduced the seed in 2024.

Container iteration order

Code can grow dependencies on the iteration order.LLVM_ENABLE_REVERSE_ITERATION walks hash containersbackwards to flag violations.llvm/include/llvm/Support/ReverseIteration.h:

1
2
3
4
5
6
7

template <class T = void *> constexpr bool shouldReverseIterate() {
#if LLVM_ENABLE_REVERSE_ITERATION
  return detail::IsPointerLike<T>::value;
#else
  return false;
#endif
}

DenseMap flips its BucketItTy tostd::reverse_iterator<pointer>;SmallPtrSet swaps begin() andend(); StringMap bitwise-NOTs the hash beforebucket selection — the only thing that perturbs StringMap,since its hash bypasses get_execution_seed.

Unlike the hash seed, reverse iteration isn't auto-on withassertions; -DLLVM_REVERSE_ITERATION=ON opts in explicitly.In 2026 has already merged fixes triggered by it: 7f703cabf728(MLIR SSA-value completion order), 0b3afd35c41d(MLIR SROA alloca order), and f5e2c5ddcec7(a clang test).

Iterator invalidation

Orthogonal to iteration order: what happens to an existing iteratorafter a mutation. llvm/include/llvm/ADT/EpochTracker.h:

1
2
3
4
5
6
7
8
9
10
11
12

class DebugEpochBase {
  uint64_t Epoch = 0;
public:
  void incrementEpoch() { ++Epoch; }
  ~DebugEpochBase() { incrementEpoch(); }  // catches use-after-free

  class HandleBase {
    bool isHandleInSync() const {
      return *EpochAddress == EpochAtCreation;
    }
  };
};

DenseMap and friends inherit fromDebugEpochBase. Mutations bump the epoch; iterators captureit at construction and assert on mismatch. The destructor bumps too, sostale iterators into destroyed containers assert rather than read freedmemory.

Without it, mutate-during-iteration "happens to work" depending onbucket layout — and bucket layout is what the hash seed and reverseiteration above perturb. The epoch check turns the latent bug into aclean assert regardless of which "lucky" layout the run lands on.Collapses to a no-op under NDEBUG.

Pre-shuffling unstable sorts

The same defensive pattern shows up twice in the monorepo, indifferent sub-projects, years apart.

llvm::sort underEXPENSIVE_CHECKS

llvm/include/llvm/ADT/STLExtras.h:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

#ifdef EXPENSIVE_CHECKS
namespace detail {
inline unsigned presortShuffleEntropy() {
  static unsigned Result(std::random_device{}());
  return Result;
}

template <class IteratorTy>
inline void presortShuffle(IteratorTy Start, IteratorTy End) {
  std::mt19937 Generator(presortShuffleEntropy());
  llvm::shuffle(Start, End, Generator);
}
} // end namespace detail
#endif

template <typename IteratorTy, typename Compare>
inline void sort(IteratorTy Start, IteratorTy End, Compare Comp) {
#ifdef EXPENSIVE_CHECKS
  detail::presortShuffle<IteratorTy>(Start, End);
#endif
  std::sort(Start, End, Comp);
}

std::sort and qsort are unstable; codeobserving the order of equal elements is depending on undocumentedbehavior. Pre-shuffling makes that observation different every run. commit5a3d47fabcb6 added the wrapper in 2018, motivated by PR35135.

LLVM also ships its own llvm::shuffle rather thancalling std::shuffle, "so that LLVM behaves the same whenusing different standard libraries." A reproducibility tool whosereproducibility depends on the host stdlib is worse than no tool — andthe linker section below relies on this.

llvm::stable_sort deliberately does not pre-shuffle; itis the explicit opt-in for code that legitimately needs ordering ofequal elements.

libc++_LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY

libc++ has a near-perfect parallel mechanism, designed for downstreamusers rather than the project's own internals.libcxx/include/__debug_utils/randomize_range.h:

1
2
3
4
5
6
7
8
9
10

template <class _AlgPolicy, class _Iterator, class _Sentinel>
_LIBCPP_HIDE_FROM_ABI _LIBCPP_CONSTEXPR_SINCE_CXX14
void __debug_randomize_range(_Iterator __first, _Sentinel __last) {
#ifdef _LIBCPP_DEBUG_RANDOMIZE_UNSPECIFIED_STABILITY
  if (!__libcpp_is_constant_evaluated())
    std::__shuffle<_AlgPolicy>(__first, __last, __libcpp_debug_randomizer());
#else
  (void)__first; (void)__last;
#endif
}

Three callsites:

• std::sort — pre-shuffles the input.
• std::partial_sort — pre-shuffles the input andre-shuffles the unsorted tail afterward.
• std::nth_element — pre-shuffles, then re-shuffles eachside of the partition.

Seed handling rhymes with get_execution_seed: ASLR orstatic std::random_device for per-process variation, with_LIBCPP_RANDOMIZE_UNSPECIFIED_STABILITY_SEED=<n> as afixed-seed escape hatch. Off by default; C++11 and later only.

libcxx/docs/DesignDocs/UnspecifiedBehaviorRandomization.rstexplains the motivation:

Google has measured couple of thousands of tests to be dependenton the stability of sorting and selection algorithms. As we also plan onupdating (or least, providing under flag more) sorting algorithms, thiseffort helps doing it gradually and sustainably.

It cites PR20837 — aworst-case O(n²) std::sort — as the upgradelibc++ specifically wanted to ship. The shuffle is the gating tool: ifdownstream tests pass with it enabled, they will pass after thealgorithm change too.

Comparing the two is more interesting than either alone:

• llvm::sort's wrapper is internal hygiene: LLVM is itsown primary user, so the shuffle lives in STLExtras.hbehind a build flag with no docs.
• libc++'s wrapper is user-facing — DesignDocs/ page,public macro, public seed override, explicit "Patches welcome."invitation. It has to be: libc++'s users are not libc++, and thecontract being defended is the C++ standard itself.
• libc++ generalizes the primitive:__debug_randomize_range applies at three callsites, eachdeclaring which sub-range the algorithm leaves unspecified. LLVM'swrapper only covers the simpler equal-element case.
• Hashed containers — std::unordered_* iteration order —are unspecified in both, but libc++ does not randomize them.LLVM-the-library does; on this one surface LLVM is ahead of its ownstdlib.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

for (const auto &patAndSeed : ctx.arg.shuffleSections) {
  ...
  const uint32_t seed = patAndSeed.second;
  if (seed == UINT32_MAX) {
    // If --shuffle-sections <section-glob>=-1, reverse the section order.
    // The section order is stable even if the number of sections changes.
    // This is useful to catch issues like static initialization order
    // fiasco reliably.
    std::reverse(matched.begin(), matched.end());
  } else {
    std::mt19937 g(seed ? seed : std::random_device()());
    llvm::shuffle(matched.begin(), matched.end(), g);
  }
}

1
2
3
4

static void randomizeSectionPadding(Ctx &ctx) {
  std::mt19937 g(*ctx.arg.randomizeSectionPadding);
  // Insert padding between input sections and at segment starts.
}

1
2
3
4
5
6
7
8
9

#if LLVM_ENABLE_ABI_BREAKING_CHECKS
ABI_BREAKING_EXPORT_ABI extern int EnableABIBreakingChecks;
LLVM_HIDDEN_VISIBILITY
__attribute__((weak)) int *VerifyEnableABIBreakingChecks =
    &EnableABIBreakingChecks;
#else
ABI_BREAKING_EXPORT_ABI extern int DisableABIBreakingChecks;
...
#endif

从开始深度使用 AI 工具至今已有三年。三年间，我亲历了 AI 能力的飞跃，也越来越清晰地触摸到它的边界。截至目前，AI 早已是非常出色的效率工具，但如何让它写出真正“称心”——符合我个人风格、想法与设计哲学——的代码，仍是一个不小的挑战。

一、一个反直觉的事实

先说一个看起来有点反常识的事：LLM 本身是无状态的。

每次调用模型，本质上就是一次”文本补全”——你扔一段 prompt 进去，它根据这段 prompt 续写一段输出，然后整个过程结束。下一次再调用，模型对上一次的事一无所知。从机制上讲，它和 2020 年的 GPT-3 没有本质区别，都是一次性的补全器。

但 2024 年之后，我们看到的 Claude Code、Cursor Agent、各种 deep research 工具，明明可以连续工作几十分钟、调用几十个工具、修改几百个文件，看起来”自主”得不得了。

这两件事怎么对得上？

答案藏在外面那个 while 循环里。

Agent ≠ 模型
Agent = 模型 + Loop + Tools + Context 管理

模型本身没有变，变的是包在它外面的那层东西。这层东西现在常被称作 harness（脚手架），而 harness 里最核心的部件，就是 Agent Loop。

这篇文章想回答三个问题：

1. 这个 loop 长什么样？
2. 它为什么这样设计？
3. 它什么时候会失效？

二、最小可运行的 Agent Loop

把所有花哨的东西都剥掉，一个 Agent Loop 的本质大概是这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

messages = [{"role": "user", "content": user_input}]

while True:
    response = llm(messages, tools=available_tools)
    messages.append(response)

    if response.stop_reason != "tool_use":
        # 模型没要求调用工具，说明它认为任务结束了
        return response.text

    # 模型要求调用一个或多个工具
    for tool_call in response.tool_calls:
        result = execute(tool_call)
        messages.append({
            "role": "tool",
            "content": result
        })
    # 进入下一轮，让模型看到工具结果，决定下一步

就这么二十行。这就是 Claude Code、Cursor、几乎所有 coding agent 的核心。

拆解一下，里面只有四个动作：

1. 模型推理：把当前 messages 丢给 LLM，让它产出下一步的 response
2. 工具调用判断：如果 response 里有 tool_use，就执行；如果没有，循环结束
3. 工具执行：在沙箱/真实环境里跑这个工具，拿到结果
4. 结果回灌 context：把工具结果塞回 messages，进入下一轮

到这里，请允许我强调一个关键认知：

所谓”Agent 的自主性”，本质就是模型在每一轮看到更新后的 context，自己决定下一步。没有任何魔法。

不是模型变得”会规划”了，是循环让它有机会根据上一步的结果，再做一次补全。它的”思考”只发生在每一次模型调用的那一瞬间，loop 只是一遍遍把它叫醒，告诉它”环境又变了，你再看看”。

理解了这一点，后面所有的工程设计，都只是这个最小循环的变体。

三、Loop 的关键设计决策

最小循环能跑，但不够用。一旦把它放到真实场景里，会立刻撞到一堆问题：循环什么时候停？context 越涨越长怎么办？工具调用错了怎么办？要不要并行？

围绕这些问题做的工程取舍，决定了一个 Agent 框架的性格。下面是五个最关键的决策维度。

1. 终止条件：什么时候跳出 loop

最朴素的写法是”模型不再要求调用工具就停”，但这在生产里远远不够。常见的多重终止条件：

• 模型主动 stop：response 里没有 tool_use，正常出口
• 达到 max_iterations：硬性步数上限（比如 50 步），防止失控
• 检测到循环：连续几次调用相同工具+相同参数，强制中断
• 用户中断：Ctrl+C、关闭对话窗口
• 预算耗尽：token 数或时间超限

每个出口背后都是一次工程权衡：上限太小，复杂任务做不完；上限太大，一旦模型卡住就烧钱。

2. Context 增长策略：长任务下怎么办

工具结果一律塞回 context，会带来一个朴素但致命的问题——context 是线性增长的。

一个改 50 个文件的任务，可能要读 100 次文件，每次读取的内容都进 context。跑到一半，context 已经塞了几十万 token，模型注意力开始稀释，关键信息被淹没。

工程上有几种常见思路：

• 全量回灌：最简单，短任务够用，长任务必崩
• 滑动窗口：只保留最近 N 轮，老的丢掉，但可能丢关键信息
• 摘要压缩：触发阈值后，让模型自己总结前面的内容，用摘要替换原文
• 分层压缩：Claude Code 的 /compact 机制就属于这一类——保留最近上下文 + 历史摘要 + 关键信息（如已修改的文件列表）

这一项是目前差异最大的设计点。后面会看到 learn-claude-code 项目专门有一节叫 s06_context_compact，就是为了解决这件事。

3. 工具选择机制：模型怎么”选工具”

两种主流做法：

• 原生 function calling：通过 API 把工具 schema 一并传给模型，模型在 response 里直接产出结构化的 tool_use 块。Claude、GPT、Gemini 都支持。优点是稳定，几乎不会出格式错误。
• 提示词约定格式：在 system prompt 里告诉模型”想调用工具就输出 <tool>...</tool> 这样的 XML”，外层用正则解析。早期 ReAct 论文就是这么做的，胜在通用，任何模型都能用。

现在新项目基本都默认用 function calling，但提示词约定法在一些场景仍有价值——比如要让一个本地小模型当 agent，或者要做更细粒度的格式控制。

4. 错误处理：工具调用失败怎么办

工具会出错。文件不存在、API 超时、参数类型不对、权限不足……

两种处理思路，本质是信任谁：

• 塞回 context 让模型自我纠正：把 error message 当作普通的 tool_result 回灌，相信模型能看懂错误并调整。优点是灵活，模型常常能从”file not found”反推出”我应该先 ls 一下”。
• 外层拦截：harness 直接处理特定错误类型，比如重试、降级、报警。优点是可预测。

实践里通常是混合策略：致命错误外层拦截，业务错误丢给模型。这件事的判断需要工程经验。

5. 并行 vs. 串行：单 Agent 还是多 Agent

单 Agent 的极致是一轮内并行调用多个工具。Claude 现在原生支持一次返回多个 tool_use 块，harness 并行执行后一次性把所有结果回灌。这能显著降低延迟。

更复杂的是多 Agent 协作：主 agent 派发子任务给子 agent，子 agent 独立 loop，结束后回报。这里立刻冒出一个新问题——路由：主 agent 怎么知道哪个子 agent 适合这个任务？是基于 metadata 标签匹配，还是让主 agent 读子 agent 的描述自己判断？这两种思路的优劣，是另一篇文章的话题了。

四、从 50 行到 1000 行：一个 Agent 是怎么长出来的

讲完抽象的设计维度，看一个具体的项目——开源项目 learn-claude-code。

这个项目的好处是：它把一个 nano 版 Claude Code 的演化拆成了 12 个递进的 Python 脚本，每一步只引入一个新机制。从 s01 到 s12，代码从大约 50 行长到 1000+ 行。

读它，相当于把上一节的设计决策亲眼看一遍怎么落到代码里。

下面挑几个最关键的节点：

s01 Agent Loop：朴素的 while

1
2
3
4
5
6

while True:
    response = model(messages, tools)
    if response.stop_reason != "tool_use":
        return response.text
    results = execute(response.tool_calls)
    messages.append(results)

这就是上一章伪代码的真实版本。50 行，能跑，能调用 bash 完成简单任务。这是一切的起点。

s02 Tool Use：从一个工具到多个工具

引入 read_file、write_file、bash、grep 等多个工具。重点不在工具本身，而在 wire——怎么把工具 schema 注册给模型，怎么 dispatch 到真实函数。

到这里，agent 已经能完成”读文件、改文件、跑测试”这种基础编程任务了。

s03 TodoWrite：对抗”目标漂移”的第一道防线

一个有意思的设计：让 agent 自己维护一个 todo list。

为什么？因为长任务里，模型很容易跑偏。任务一大，model 在第 30 轮已经忘了第 1 轮的目标是什么。TodoWrite 工具强制 agent 在开工前把任务拆成清单，每完成一项划掉一项。

这本质上是用工具调用替代记忆——不指望模型记住，而是把目标固化成 context 里随时可见的状态。Claude Code 现在就是这么做的，效果非常显著。

s04 Subagent：什么时候该拆出去

主 agent 不是万能的。当一个子任务的 context 会污染主 agent 的判断（比如要读一大堆代码才能定位 bug），就该把它丢给子 agent。

子 agent 有自己独立的 loop、独立的 context，跑完只把结论返回给主 agent。这是用 context 隔离换取主 loop 的清晰。

s06 Context Compact：长任务的生存策略

直接对应第三章讲的”context 增长策略”。当 messages 长度超过阈值，触发 compact：让模型把前面的对话总结成一段摘要，用摘要替换原始消息，保留最近几轮原文。

这是目前所有长任务 agent 的共同方案。没有 compact，agent 就走不远。

s07–s12：再往后

任务系统、后台任务、多 agent 团队、worktree 隔离……每一层都是在同一个 loop 上叠加工程能力。但本质都没变：还是那个 while 循环。

读完这个项目，最值得记住的是它的核心宣言：

The model is the agent. The code is the harness.
模型才是 Agent，代码只是脚手架。

这句话听起来像废话，其实暗藏一个反直觉的判断——你写的那一千行 harness 代码，不是在让 Agent “更聪明”，只是在帮模型别搞砸。模型本身已经具备 Agent 能力，harness 的工作是给它工具、管好上下文、防止失控。

Harness 越薄，说明模型越强。

五、Loop 的边界与失效模式

Agent Loop 不是银弹。在生产里，它会以几种典型方式翻车：

1. 上下文窗口爆炸

最常见。长任务跑到一半，context 涨到几十万 token，模型注意力被稀释，开始重复读同一个文件、忽略关键约束。Compact 是缓解，但不是根治——压缩本身也会丢信息。

2. 工具调用幻觉

模型有时会编造不存在的工具，或者给真实工具传错误参数（比如发明了一个本不存在的 flag）。这件事在小模型上尤其严重。缓解办法是收紧 tool schema 的描述、用 function calling 而不是提示词约定，以及在 harness 里做参数校验。

3. 死循环

模型反复调用同一个工具拿同样的结果，不收敛。常见于”修一个 bug 但根本没想清楚”的场景：跑测试 → 失败 → 改一行 → 跑测试 → 失败 → 改回来。需要在 harness 里检测这种模式并强制中断。

4. 目标漂移

多轮之后忘了原始任务。前面提到的 TodoWrite 是一种缓解，更激进的做法是定期”自检”：让 agent 每隔 N 轮 reflect 一次，对照原始目标审视当前进展。

工程上常见的缓解组合是：context 压缩 + 工具白名单 + step budget + 显式 reflection 节点。每一项都不彻底，但叠在一起能撑很久。

六、Agent Loop 是临时方案，还是终极形态

最后留一个开放问题。

回看现在所有的 Agent 框架——Claude Code、Cursor、LangGraph、OpenClaw、learn-claude-code——本质都在围绕同一个 while 循环做工程优化。终止条件、context 压缩、子 agent、todo 管理……每一项都是因为模型本身做不到，所以 harness 替它做。

但模型还在变强。

Claude 已经支持 extended thinking——模型在一次调用里能做更长的内部推理。原生的 tool use 在每一代都更稳。multi-step 的 planning 能力肉眼可见地在涨。

那么一个不那么好回答的问题是：

当模型本身具备足够长的推理链和原生工具使用能力时，外部那个 while 循环还需要存在吗？

也许某一天，你只需要一次 API 调用，模型在内部就完成了全部规划、工具调用、上下文管理。harness 被吸收进了模型本身。我们今天精心设计的这些 loop 控制机制，会变成一段历史。

也可能不会。也许 harness 永远存在——因为外部环境永远是 harness 的边界，模型再强，也需要一个东西替它和真实世界对接。

不知道。但这就是现在做 Agent 最有意思的地方：你不知道自己写的这一千行 harness 代码，到底是产品的核心资产，还是即将过时的过渡方案。

唯一确定的是，所有故事的开头，都还是那个最朴素的 while 循环。

参考项目：shareAI-lab/learn-claude-code，一个把 Claude Code 拆成 12 个递进版本的开源教学项目。建议从 s01_agent_loop.py 开始读。

从 Swift 5.5 引入符合现代编程思想的新并发模型算起，一转眼快 5 年了。从 5.5 到目前的 6.3，Swift 社区一直在采用小步迭代的方式，积极推进并发 API 的演进。但在应对过多的新关键字、复杂的隔离概念以及一些容易引发困扰的“反模式”时，这个过程对开发者来说并不算顺利。

背景

在 iOS 26 上，视频播放器使用的 libass 字幕渲染器遭遇了严重的兼容性问题。当字幕指定的字体在系统中找不到时，libass 的 CoreText 后端会尝试 fallback 到系统字体路径：

/System/Library/PrivateFrameworks/FontServices.framework/CorePrivate/PingFangUI.ttc

然而，这个路径在 iOS 26 的沙盒机制下被系统拦截，导致 fallback 失败，内嵌 ASS/SSA 字幕中的中文字符完全无法渲染。用户看到的只是一片空白或乱码。

问题分析

1. 问题表现

2. 根本原因

iOS 26 引入了一个沙盒安全限制，阻止了 libass 对系统字体的访问。libass 的字体回退机制无法获取 PingFang 字体，导致整个字幕渲染失败。

解决方案

方案概述

视频播放
    ↓
禁用内嵌字幕（避免 libass 走系统字体路径）
    ↓
提取内嵌字幕流为 SRT（通过 FFmpeg）
    ↓
SRT 无字体定义，通过 freetype 渲染器 + 指定中文字体显示
    ↓
同时对外挂 ASS 字幕做字体名替换（指向 CoreText 已注册的字体）

核心实现

1. 内嵌字幕提取

通过 FFmpeg 提取视频中的字幕流，转换为无字体定义的 SRT 格式：

// 使用 FFmpeg 提取字幕流
FFmpegWrapperAPI *ffAPI = [[FFmpegWrapperAPI alloc] init];
ffAPI.inputPath = videoPath;

// -map 0:s:N 选择特定字幕流
NSString *command = [NSString stringWithFormat:@"-map 0:s:%d", trackIndex];

[ffAPI runFFmpegAPI:videoPath
         outputPath:srtOutputPath
             prefix:nil
            command:command
              async:YES];

2. 字体名替换（正则方案）

ASS 字幕中的字体名出现在两处：

• [V4+ Styles] 定义行：Style: Name,Fontname,Fontsize,...
• [Events] Dialogue 行内覆盖标签：{\fn字体名}

// 替换 Dialogue 行内的 {\fn任意字体名} 覆盖标签
NSRegularExpression *fnTagRegex = [NSRegularExpression
    regularExpressionWithPattern:@"\\{\\\\fn[^}\\\\]+"
    options:NSRegularExpressionCaseInsensitive
    error:&regexError];
modifiedText = [fnTagRegex stringByReplacingMatchesInString:modifiedText
                                                     options:0
                                                       range:NSMakeRange(0, modifiedText.length)
                                                withTemplate:[NSString stringWithFormat:@"{\\fn%@", kTargetFontName]];

// 替换 Style 定义行的 Fontname 字段
NSRegularExpression *styleLineRegex = [NSRegularExpression
    regularExpressionWithPattern:@"^(Style\\s*:\\s*[^,]+,)([^,]+)(,.*)$"
    options:0
    error:&regexError];
// ...

SRT 字幕中的字体名出现在 HTML 标签中：

// 替换 <font face="任意内容">
NSRegularExpression *fontFaceRegex = [NSRegularExpression
    regularExpressionWithPattern:@"<font\\s+face\\s*=\\s*([\"'])[^\"']*\\1"
    options:NSRegularExpressionCaseInsensitive
    error:&regexError];

🔴 踩坑实录

坑一：VLC 索引与 FFmpeg 索引的映射错误

问题描述：用户选择中文内嵌字幕，但实际显示的是英文字幕。

根因分析：

• VLC 的 videoSubTitlesIndexes 数组索引 0 是 "Disable"
• 内嵌字幕从索引 1 开始：索引 1 → 第一条字幕，索引 2 → 第二条字幕
• FFmpeg 的字幕流索引从 0 开始：第一条字幕流是 0，第二条是 1

错误的映射：

用户选择 VLC 索引 1（第一条字幕）→ 错误地映射为 FFmpeg 索引 1 → 提取了第二条字幕

代码修复：

// 修复前（错误）
int ffmpegTrackIndex = trackIndex + 1;

// 修复后（正确）
int ffmpegTrackIndex = (int)subtitleIndex - 1;

// VLC 索引 1 → FFmpeg 索引 0
// VLC 索引 2 → FFmpeg 索引 1

日志验证：

[updateSubtitleUrl] iOS 26 拦截内嵌字幕: VLC subtitleIndex=1,
→ FFmpeg trackIndex=0  // 修复后正确映射到第一条字幕流

坑二：SRT 字幕的 <font> 标签问题

问题描述：内嵌字幕提取为 SRT 后，部分 SRT 仍无法显示中文。

日志分析：

[ExtractSub] SRT 前 200 字:
1
00:00:00,000 --> 00:00:03,018
<font face="方正准圆简体" size="21"><b>...

根因分析：虽然 FFmpeg 提取时没有字体定义，但某些视频的字幕流本身已包含 <font face="xxx"> 标签。这些标签导致 VLC 的 freetype 渲染器尝试加载指定字体，同样失败并 fallback 到被拦截的路径。

修复：在加载 SRT 前，批量替换所有 <font face="xxx"> 标签：

NSString *srtText = [NSString stringWithContentsOfFile:srtUrl.path encoding:NSUTF8StringEncoding error:nil];
NSString *replaced = [self replaceSrtFontNamesInText:srtText];
[replaced writeToFile:srtUrl.path atomically:YES encoding:NSUTF8StringEncoding error:nil];

坑三：字符串匹配无法覆盖所有字体

问题描述：硬编码的字体名列表无法覆盖所有可能出现的字体名。

原方案：

NSArray *fontNamesToReplace = @[
    @"微软雅黑", @"微软雅黑", @"SimHei", @"SimSun",
    @"黑体", @"宋体", @"楷体", // ...
];

问题：总有漏网之鱼，如 方正准圆简体、Noto Sans CJK SC 等。

改进方案：正则 + 字符串匹配兜底

正则覆盖任意字体名，字符串匹配处理边缘情况：

// 正则：替换所有 {\fn任意字体名} → {\fnSource Han Sans CN}
// 兜底：字符串匹配常见字体名
modifiedText = [self fallbackReplaceFontNamesInText:modifiedText];

完整架构图

┌─────────────────────────────────────────────────────────────────┐
│                    iOS 26 字幕兼容架构                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐        │
│  │ handleiOS26 │     │ updateSubtitleUrl │ │convertSubtitle│    │
│  │ SubtitleOn  │     │   (内嵌拦截)     │  │   (外挂处理)   │      │
│  │   Playing   │     │                 │  │              │      │
│  └──────┬──────┘     └──────┬────────┘  └──────┬────────┘       │
│         │                   │                    │              │
│         ▼                   ▼                    ▼              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              @available(iOS 26.0, *) 守卫                 │   │
│  └──────────────────────────────────────────────────────────┘   │
│         │                   │                    │              │
│         ▼                   ▼                    ▼              │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐         │
│  │ 禁用内嵌字幕   │   │ FFmpeg 提取   │   │ 字体名替换     │        │
│  │ (libass)     │   │ SRT          │   │ (正则+兜底)    │        │
│  └──────────────┘   └──────┬───────┘   └──────────────┘         │
│                            │                                    │
│                            ▼                                    │
│                    ┌──────────────┐                             │
│                    │ freetype 渲染 │                             │
│                    │ + 指定中文字体 │                             │
│                    └──────────────┘                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

参考资料

• MobileVLCKit Documentation
• FFmpeg Subtitles Extraction

基于 Swift 5.10（含部分 Swift 6 行为）与现代 Objective-C（ARC + LLVM clang）。 文中代码片段为最小化示例，仅作为论点的佐证。

核心要点

一句话总结：Swift 默认追求"能静态就静态"，只在继承、协议、互操作三条路径上才退化为表派发或消息派发；OC 则把所有方法调用统一成 objc_msgSend 的动态消息查找，灵活但每次调用都要付出查表代价。

1. 为什么要谈"派发"

方法派发（method dispatch）就是编译器/运行时如何把"调用某方法"翻译成"跳转到某段机器指令"。

派发方式直接决定三件事：

• 性能：是否能内联、是否要查表、是否能命中分支预测。
• 可扩展性：能不能在运行时替换实现（Swizzle、KVO、Mock）。
• 二进制兼容：库的方法表布局变化是否会破坏调用方。

OC 与 Swift 在这三个维度上的设计哲学截然相反，下面分别拆解。

2. Objective-C：一切皆消息

2.1 objc_msgSend 的本质

OC 中 [obj doSomething:arg] 在编译期不会被解析为某个具体函数地址，而是被翻译成：

((void (*)(id, SEL, id))objc_msgSend)(obj, @selector(doSomething:), arg);

objc_msgSend 是一段手写汇编，做的事情大致是：

1. 取 obj->isa 拿到 Class
2. 在 Class 的 method cache 里按 SEL hash 查 IMP
3. 命中 → 直接 jmp IMP（尾调用，不入栈）
4. 未命中 → __class_lookupMethodAndLoadCache3 走 method list / 父类链
5. 查到 → 写回 cache
6. 仍找不到 → 进入 forwarding（resolveInstanceMethod / forwardingTargetForSelector / forwardInvocation）

⚠️ 实战提示：objc_msgSend 的 cache 是 per-class 的开放寻址哈希表，命中率通常 > 95%。这意味着"OC 方法慢"的直觉并不准确——在热路径上一次调用通常只多花几个时钟周期，远低于一次 cache miss。真正的成本不在派发本身，而在无法内联导致优化器失去全局视野。

2.2 消息派发带来的能力

消息派发让以下能力成为零成本默认值：

• Method Swizzling：替换 Class 的 method list 即可全局劫持。
• KVO：runtime 动态生成 NSKVONotifying_XXX 子类并替换 isa。
• 响应链 / Target-Action：UIApplication sendAction:to:from:forEvent: 完全建立在 SEL 之上。
• 消息转发：forwardInvocation: 让一个对象"假装"实现某协议，是 OC 多代理与 RPC 框架的基石。

代价是：编译期不知道 IMP 是什么，全程无法内联，也无法做跨方法优化。

3. Swift：四种派发方式共存

Swift 没有"统一派发"的设计，而是根据声明上下文挑选最便宜的合法方式。理解 Swift 性能模型的关键，就是搞清"什么场景用哪种"。

3.1 Static Dispatch（直接派发）

调用直接编译成 call <symbol>，可被内联、可被常量折叠。触发条件：

• struct、enum 的所有方法（值类型不存在继承）
• class 中标了 final 的方法、或 final class 的全部方法
• private 方法（编译器能证明无覆写）
• 全局函数、static 函数
• @inlinable / @_transparent 修饰的方法

struct Counter {
    var value = 0
    mutating func tick() { value += 1 }
}

var c = Counter()
c.tick()

c.tick() 在 -O 下会被完全内联，最终汇编里看不到调用指令，只剩一条 add。

3.2 V-Table Dispatch（虚表派发）

Swift 的 class 与 C++ 类似，每个类有一张 V-Table（在 metadata 末尾），按声明顺序存放方法指针。调用时：

1. 从 obj 的 metadata 偏移取 V-Table
2. 按方法在表中的固定 index 取 IMP
3. call IMP

只有一次表查 + 一次间接跳转，比 objc_msgSend 少了 SEL hash 与 cache 命中判断，但因为是间接调用，仍然无法跨方法内联。

class Animal {
    func speak() { print("...") }
}
final class Dog: Animal {
    override func speak() { print("woof") }
}

Animal 的 speak 通过 V-Table 派发；Dog 因为 final，其调用点会被去虚化（devirtualize）回 static dispatch。

3.3 Witness Table Dispatch（协议见证表）

通过协议变量调用协议方法时，Swift 用一张 Protocol Witness Table（PWT）：每个"类型 × 协议"对生成一张表，表里按协议方法的固定 index 存放该类型的具体实现。

protocol Drawable {
    func draw()
}
struct Circle: Drawable { func draw() { /* ... */ } }

func render(_ d: Drawable) {
    d.draw()
}

render 拿到的 d 是一个 existential container（值 + 类型 metadata + PWT 指针）。d.draw() 实际是：

1. 从 existential container 取 PWT
2. 按 draw 在协议中的 index 取 witness
3. call witness（witness 内部再 call 真正的实现）

⚠️ 实战坑：some Drawable（opaque return type）和 Drawable（existential）的派发完全不同。前者编译期就确定了具体类型，可以走 static dispatch + 单态化（specialization），后者必须走 PWT。把热路径里的 func make() -> Drawable 改成 func make() -> some Drawable，在 SwiftUI / 集合操作里能拿到数量级的性能提升。

3.4 Message Dispatch（走 objc_msgSend）

Swift 在以下两种情况会退化到 OC 的消息派发：

• 显式标注 @objc dynamic
• 类继承自 NSObject，且方法满足 @objc 暴露规则，且没有被去虚化优化

class MyVC: UIViewController {
    @objc dynamic func reload() { /* ... */ }
}

只有 @objc dynamic 的方法是保证走 objc_msgSend 的，因此也只有它能被 KVO / Method Swizzling 劫持。仅 @objc 不带 dynamic 的方法，编译器仍可能选择 V-Table 派发。

4. 派发规则速查表

把"声明位置 × 修饰符"组合起来，就是一张完整的决策表：

几条容易踩的经验法则：

• extension 中定义的方法即使被子类重写也不会触发动态派发，重写会被静默忽略。要支持覆写就把方法定义放回类主体。
• 协议 extension 的"默认实现"是 static 的，不会走 PWT。如果某个类型实现了同名方法，但调用方持有的是协议变量，仍可能调到 default 实现（这是经典面试题）。
• @objc ≠ dynamic：前者只是给 OC runtime 暴露符号，后者才强制走消息派发。

5. 性能：到底差多少

简化的相对开销（命中 cache、无优化干扰的情况下）：

但真实业务里这些差异通常被淹没，例如 UI 主线程一次 reloadData 的耗时可能是 10ms 量级，几百次 objc_msgSend 完全可以忽略。性能差异真正显著的场景是：

• 集合的内层热循环（map / filter / 自定义 reduce）
• 每帧调用的渲染回调（CADisplayLink、SwiftUI 的 body 求值）
• 大量小对象的属性 getter/setter（特别是泛型容器）

6. 选型与最佳实践

6.1 写 Swift 类型时

• 默认优先 struct，需要引用语义或 OC 互操作再用 class。
• class 不需要继承时直接 final class，让编译器去虚化。
• 协议返回值能用 some P 就别用 P，能用 any P 就别忘加 any 让代码意图清晰。
• 性能敏感的 ABI 稳定库导出 API 时配合 @inlinable + @usableFromInline。

6.2 需要动态能力时

• 要被 KVO 监听 → @objc dynamic var ...
• 要被 Swizzle / Aspect → @objc dynamic func ...
• 要在 OC 代码里调用 → @objc（不必加 dynamic）
• 要做 Mock / Stub → 优先用协议依赖注入，而不是 Swizzle

6.3 OC 仍不可替代的场景

公平起见，OC 的消息派发模型在以下场景仍有 Swift 难以替代的优势：

工程实践中，底层基础库（埋点、网络、监控）继续用 OC，业务层迁 Swift，往往是兼顾性能与生产力的最稳妥分工。

7. 一个综合案例

下面这段代码同时触发了四种派发，是理解 Swift 派发模型的一个好对照：

@objc protocol Refreshable { func refresh() }

class Base: NSObject, Refreshable {
    func refresh() { print("base") }
}
final class Leaf: Base {
    override func refresh() { print("leaf") }
}

let a: Refreshable = Leaf()
let b: Base       = Leaf()
let c: Leaf       = Leaf()
a.refresh()
b.refresh()
c.refresh()

• a.refresh()：Refreshable 是 @objc protocol，走 objc_msgSend。
• b.refresh()：Base 继承 NSObject，编译器保守起见走 V-Table（若 Base 也是 final，可去虚化）。
• c.refresh()：Leaf 是 final，编译器去虚化为 Static，可被内联。

把同一个方法在三种持有方式下分别调用，得到三种不同的派发路径——这是 OC 永远不会出现的现象，也是 Swift 性能调优最容易被忽略的细节。

从 2019 年问世算起，SwiftUI 已经快七年了。它早已脱去了最初几年的稚气，逐渐成为苹果生态开发者的基础能力之一。不过，SwiftUI 的闭源属性也意味着，它的很多运行机制始终不透明。开发者在使用时固然能感受到它的表达优势，但一旦遇到问题，往往很难进一步追踪原因。这种特性也让 SwiftUI 在 AI 辅助编程时代显得有些“吃亏”——相比那些长期暴露在社区讨论、源码和文档中的技术，大模型能参考的高质量材料终究有限。

【SwiftyJSON】拯救你的 as? [String: Any]——链式 JSON 访问的正确姿势

iOS三方库精读 · 第 15 期

一、一句话介绍

SwiftyJSON 是一个用于 iOS/macOS 的 JSON 解析辅助库，它通过链式下标访问和安全类型转换，让原本需要大量 as? 强转和 guard let 解包的 JSON 解析代码，变成像访问字典一样直观的单行操作。

二、为什么选择它

原生痛点

原生 JSONSerialization 解析复杂 JSON 的体验：

// ❌ 原生方式：每层都要 as? + guard，代码量爆炸
guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
      let user = json["user"] as? [String: Any],
      let profile = user["profile"] as? [String: Any],
      let bio = profile["bio"] as? String,
      let score = profile["score"] as? Double else {
    return
}

5 层嵌套，1 个字段。如果某层返回 null，整个 guard 失败，无法优雅降级。

SwiftyJSON 方式：

// ✅ SwiftyJSON：一行，安全，不崩溃
let bio   = json["user"]["profile"]["bio"].stringValue   // 不存在则 ""
let score = json["user"]["profile"]["score"].doubleValue // 不存在则 0.0

核心优势：

1. 链式下标：无论嵌套多深，中间路径不存在也不崩溃
2. 类型转换属性：.stringValue / .intValue / .boolValue 自动转换 + 默认值
3. Optional 版本：.string / .int / .bool 返回 Optional，可 if let
4. 数组/字典直接遍历：.arrayValue / .dictionaryValue
5. null 安全：.isNull 和 .exists() 区分"不存在"和"存在但为 null"

三、核心功能速览

基础层（新手必读）

环境集成

// SPM
// URL: https://github.com/SwiftyJSON/SwiftyJSON.git
// from: "5.0.2"

# CocoaPods
pod 'SwiftyJSON', '~> 5.0'

创建 JSON 对象

import SwiftyJSON

// 从 Data 创建（最常用）
let json = JSON(data)

// 从字典/数组创建
let json2 = JSON(["name": "Alice", "age": 25])

// 从字符串创建
let json3 = JSON(parseJSON: "{\"key\": \"value\"}")

值访问：xValue vs x（Optional）

// .stringValue → String（不存在时返回 ""）
// .string      → String?（不存在时返回 nil）
let name1 = json["user"]["name"].stringValue  // "Alice" 或 ""
let name2 = json["user"]["name"].string       // "Alice" 或 nil

// 其他类型同理
json["count"].intValue      // Int，默认 0
json["count"].int           // Int?
json["score"].doubleValue   // Double，默认 0.0
json["score"].double        // Double?
json["active"].boolValue    // Bool，默认 false
json["active"].bool         // Bool?

进阶层（最佳实践）

数组遍历

// arrayValue: 返回 [JSON]，安全（不存在返回 []）
for item in json["user"]["repos"].arrayValue {
    let name  = item["name"].stringValue
    let stars = item["stars"].intValue
    print("\(name): ⭐ \(stars)")
}

// 快速 map
let repoNames = json["user"]["repos"].arrayValue
    .map { $0["name"].stringValue }
    .filter { !$0.isEmpty }

字典遍历

// dictionaryValue: 返回 [String: JSON]
for (key, value) in json["user"]["metadata"].dictionaryValue {
    print("\(key): \(value)")
}

Null 处理

let field = json["user"]["lastLogin"]

// 区分"不存在"和"存在但为 null"
print(field.exists())  // false → 路径不存在
print(field.isNull)    // true  → 路径不存在或值为 null

// 带默认值的安全访问
let last = json["user"]["lastLogin"].string ?? "从未登录"

整数索引访问数组

let firstTag = json["user"]["tags"][0].stringValue    // "swift"
let lastRepo  = json["user"]["repos"][2]["name"].stringValue  // "TodoApp"

SwiftyJSON 转回 Data / 字典

// 转回 Data（用于 Codable 混用）
let rawData = try? json["user"]["repos"].rawData()

// 转回 [String: Any]
let rawDict = json.dictionaryObject  // [String: Any]?
let rawArr  = json.arrayObject       // [Any]?

与 Codable 混用（最佳实践）

// 用 SwiftyJSON 做"柔性"部分，Codable 做"结构化"部分
let json = JSON(data)

// 1. 取出子 JSON（SwiftyJSON 处理不确定的动态结构）
let extraInfo = json["response"]["extra"]  // 动态字段，结构不定

// 2. 将确定结构的部分转为 Codable
if let reposData = try? json["user"]["repos"].rawData() {
    let repos = try? JSONDecoder().decode([Repo].self, from: reposData)
}

深入层（源码视角）

JSON 的枚举本质

SwiftyJSON 的核心是一个 JSON 结构体，内部用枚举表示类型：

public struct JSON {
    // 内部存储联合类型
    fileprivate var rawArray: [Any] = []
    fileprivate var rawDictionary: [String: Any] = [:]
    fileprivate var rawString: String = ""
    fileprivate var rawNumber: NSNumber = 0
    fileprivate var rawNull: NSNull = NSNull()
    fileprivate var rawBool: Bool = false

    public internal(set) var type: Type = .null
}

subscript 访问时，如果类型不匹配或 key 不存在，返回一个 JSON.null 单例而非崩溃。这是链式访问安全性的核心保障。

性能注意

每次 subscript 访问都会创建新的 JSON 实例（值类型复制），深层链式访问在循环中可能造成性能开销。热路径代码建议：

// ❌ 在循环中重复深层访问
for _ in 0..<10000 {
    let _ = json["a"]["b"]["c"]["d"].stringValue
}

// ✅ 缓存中间节点
let profile = json["a"]["b"]  // 只创建一次
for _ in 0..<10000 {
    let _ = profile["c"]["d"].stringValue
}

四、实战演示

场景：解析 GitHub API 响应

// 解析 https://api.github.com/search/repositories?q=swift 的响应
func parseSearchResult(data: Data) -> [String] {
    let json = JSON(data)

    // 总数
    let total = json["total_count"].intValue
    print("找到 \(total) 个仓库")

    // 取前 5 个仓库名
    return json["items"].arrayValue.prefix(5).map { repo in
        let name  = repo["full_name"].stringValue
        let stars = repo["stargazers_count"].intValue
        let lang  = repo["language"].string ?? "Unknown"
        return "\(name) ⭐\(stars) [\(lang)]"
    }
}

五、源码亮点

进阶层：链式安全的实现

// SwiftyJSON 的 subscript 关键实现
public subscript(key: String) -> JSON {
    get {
        if type == .dictionary {
            if let value = rawDictionary[key] {
                return JSON(value)
            }
        }
        return JSON.null  // ← 不崩溃，返回 null JSON
    }
}

JSON.null 是一个静态单例，所有对它的 subscript 访问都继续返回自身，形成"null 传播链"，这就是为什么 json["a"]["b"]["c"]["d"] 即便 "a" 不存在也不会 crash。

深入层：与 Codable 的本质区别

六、踩坑记录

问题 1：.string 返回 nil 而 .stringValue 返回空字符串

• 原因：JSON 中该字段是 null 或类型是 Number，.string 只在类型是 String 时返回非 nil
• 解决：根据场景选择：string ?? "默认值" 或 .stringValue；如果需要 Number → String 转换：

  let val = json["count"].string ?? json["count"].numberValue.stringValue
  

问题 2：修改 SwiftyJSON 的值没有生效

• 原因：JSON 是值类型（struct），赋值后修改的是副本
• 解决：

  var json = JSON(data)
  json["user"]["name"] = "New Name"  // ✅ 使用 subscript setter
  

问题 3：Swift Package Manager 找不到模块

• 原因：SwiftyJSON 的 SPM 包名是 SwiftyJSON，但有时大小写不一致
• 解决：确保 import SwiftyJSON（大驼峰），检查 SPM 依赖是否成功解析

问题 4：OC 项目无法使用 SwiftyJSON

• 原因：SwiftyJSON 是纯 Swift，OC 不能直接 import
• 解决：OC 项目用 NSJSONSerialization + YYModel / MJExtension，或在 Swift 桥接层封装

问题 5：解析性能在大量数据时较差

• 原因：SwiftyJSON 在内部创建大量临时 JSON 实例
• 解决：大量数据（10w+ 条）时改用 Codable，小量动态数据 SwiftyJSON 够用

七、延伸思考

JSON 解析方案全景对比

推荐原则

新项目 Swift：优先 Codable，复杂动态 JSON 用 SwiftyJSON 辅助。 老项目 OC：NSJSONSerialization + YYModel / MJExtension。 混合项目：在 Swift 层用 Codable 建模，可选 SwiftyJSON 处理边界情况。

八、参考资源

• GitHub: SwiftyJSON/SwiftyJSON
• Apple Codable 文档
• YYModel（OC 模型框架）
• WWDC 2017 Session 212 - What's New in Foundation
• 系列 Demo 仓库：github.com/yourname/ios-lib-demos

九、本期互动

小作业

用 SwiftyJSON 解析一个真实 API（如 GitHub / 豆瓣 / OpenWeather），要求：处理嵌套 3 层以上的 JSON，包含数组遍历和 null 字段处理，最终展示在 UITableView 中。评论区分享你选的 API 和最复杂的解析路径。

思考题

SwiftyJSON 用"null 传播"（路径不存在时返回 JSON.null 而非 crash）来保证安全性，而 Swift Codable 用 Optional 和 throws 来保证类型安全。这两种设计哲学各有什么权衡？在什么情况下"静默返回默认值"比"抛出错误"更合适？

读者征集

下一期我们将深入 R.swift（编译时安全的资源访问）。你在项目中遇到过资源文件名拼写错误导致运行时崩溃吗？你目前是如何管理图片/字体/颜色等资源的？欢迎评论区分享你的资源管理方案。

📅 本系列每周五晚更新 ✅ 第11期：DGCharts · ✅ 第12期：Hero · ✅ 第13期：Realm · ✅ 第14期：Moya · ➡️ 第15期：SwiftyJSON · ○ 第16期：R.swift

【Moya】为什么你的 Alamofire 代码需要再封装一层？

iOS三方库精读 · 第 14 期

一、一句话介绍

Moya 是一个建立在 Alamofire 之上的网络抽象层库，它用 TargetType 协议将所有 API 接口声明为 Swift 枚举 case，让网络请求从"散落在各处的字符串 URL"变成"编译器可检查的类型化接口"，同时内置单元测试 Stubbing 和 Plugin 拦截机制。

二、为什么选择它

原生痛点

直接使用 Alamofire 或 URLSession 时，常见的问题：

// ❌ 硬编码 URL，散落在各处
AF.request("https://api.example.com/users/\(userId)/profile",
           method: .get,
           parameters: ["include": "avatar"],
           headers: ["Authorization": "Bearer \(token)"])

• URL 字符串：运行时才发现拼写错误
• 参数类型：parameters: [String: Any]，传错类型编译器不报错
• 认证 Token：每个请求都要手动加 headers
• Mock 测试：需要替换整个 URLSession，实现复杂
• 接口文档：散落在业务代码里，难以统一维护

Moya 的解决方案：

1. TargetType 协议：将每个 API 的 URL、方法、参数、headers 集中声明
2. 类型安全：枚举 case 关联值确保参数类型正确，编译时报错
3. Plugin 系统：一处注入 Token，所有请求自动携带
4. 内置 Stubbing：sampleData + StubbingProvider，无需 mock URLSession

三、核心功能速览

基础层（新手必读）

环境集成

// SPM
// URL: https://github.com/Moya/Moya.git
// from: "15.0.3"
// Products: Moya（基础）/ RxMoya（RxSwift）/ CombineMoya（Combine）

# CocoaPods
pod 'Moya', '~> 15.0'
pod 'Moya/RxSwift'    # 可选
pod 'Moya/Combine'    # 可选

TargetType 完整示例

import Moya

enum UserAPI {
    case login(email: String, password: String)
    case profile(userId: Int)
    case updateAvatar(data: Data)
    case logout
}

extension UserAPI: TargetType {
    var baseURL: URL { URL(string: "https://api.example.com/v2")! }

    var path: String {
        switch self {
        case .login:              return "/auth/login"
        case .profile(let id):   return "/users/\(id)"
        case .updateAvatar:      return "/users/avatar"
        case .logout:            return "/auth/logout"
        }
    }

    var method: Moya.Method {
        switch self {
        case .login, .updateAvatar: return .post
        case .logout:               return .delete
        case .profile:              return .get
        }
    }

    var task: Task {
        switch self {
        case .login(let email, let pw):
            return .requestParameters(
                parameters: ["email": email, "password": pw],
                encoding: JSONEncoding.default
            )
        case .updateAvatar(let data):
            let formData = MultipartFormData(provider: .data(data),
                                              name: "file",
                                              fileName: "avatar.jpg",
                                              mimeType: "image/jpeg")
            return .uploadMultipart([formData])
        default:
            return .requestPlain
        }
    }

    var headers: [String: String]? { ["Content-Type": "application/json"] }

    // 单元测试用的 Stub 数据
    var sampleData: Data {
        switch self {
        case .login:
            return """{"token":"test_token","userId":1}""".data(using: .utf8)!
        default:
            return Data()
        }
    }
}

发起请求

let provider = MoyaProvider<UserAPI>()

// 回调方式
provider.request(.login(email: "test@example.com", password: "123456")) { result in
    switch result {
    case .success(let response):
        let json = try? response.mapJSON()
        print(json ?? "")
    case .failure(let error):
        print(error)
    }
}

// 直接 map 到 Codable 模型
provider.request(.profile(userId: 42)) { result in
    if case .success(let response) = result {
        let user = try? response.map(User.self)
    }
}

进阶层（最佳实践）

Plugin 系统：拦截所有请求

// 统一注入认证 Token
struct TokenPlugin: PluginType {
    func prepare(_ request: URLRequest, target: TargetType) -> URLRequest {
        var req = request
        if let token = AuthManager.shared.token {
            req.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
        }
        return req
    }

    // 401 自动触发 token 刷新
    func didReceive(_ result: Result<Response, MoyaError>, target: TargetType) {
        if case .success(let response) = result, response.statusCode == 401 {
            AuthManager.shared.refreshToken()
        }
    }
}

// 统计 API 耗时
struct MetricsPlugin: PluginType {
    func willSend(_ request: RequestType, target: TargetType) {
        Analytics.trackStart(api: target.path)
    }
    func didReceive(_ result: Result<Response, MoyaError>, target: TargetType) {
        Analytics.trackEnd(api: target.path)
    }
}

// 组合多个 Plugin
let provider = MoyaProvider<UserAPI>(plugins: [
    TokenPlugin(),
    MetricsPlugin(),
    NetworkLoggerPlugin()  // Moya 内置日志插件
])

单元测试：Stubbing

// 无需真实网络，立即返回 sampleData
let testProvider = MoyaProvider<UserAPI>(stubClosure: MoyaProvider.immediatelyStub)

// 延迟返回（模拟网络延迟）
let testProvider2 = MoyaProvider<UserAPI>(
    stubClosure: MoyaProvider.delayedStub(0.5)  // 延迟 0.5s
)

// 测试代码
func testLogin() {
    testProvider.request(.login(email: "test@example.com", password: "123")) { result in
        switch result {
        case .success(let response):
            XCTAssertEqual(response.statusCode, 200)
            let model = try? response.map(LoginResponse.self)
            XCTAssertNotNil(model?.token)
        case .failure:
            XCTFail()
        }
    }
}

Combine 集成

import Combine

class UserViewModel: ObservableObject {
    @Published var user: User?
    @Published var error: String?

    private var cancellables = Set<AnyCancellable>()
    private let provider = MoyaProvider<UserAPI>()

    func loadProfile(userId: Int) {
        provider.requestPublisher(.profile(userId: userId))
            .tryMap { try $0.map(User.self) }
            .receive(on: DispatchQueue.main)
            .sink(
                receiveCompletion: { [weak self] completion in
                    if case .failure(let error) = completion {
                        self?.error = error.localizedDescription
                    }
                },
                receiveValue: { [weak self] user in
                    self?.user = user
                }
            )
            .store(in: &cancellables)
    }
}

RxSwift 集成

import RxSwift

provider.rx.request(.searchRepos(query: "swift"))
    .map(RepoSearchResult.self)
    .observe(on: MainScheduler.instance)
    .subscribe(
        onSuccess: { result in print(result.items) },
        onFailure: { error in print(error) }
    )
    .disposed(by: disposeBag)

深入层（源码视角）

MoyaProvider 的请求流程

provider.request(.login(...))
    ↓
MoyaProvider.requestNormal
    ↓
调用所有 Plugin.prepare（修改 URLRequest）
    ↓
调用 Plugin.willSend（发送前通知）
    ↓
Alamofire.request（真正发网络请求）
    ↓
收到响应
    ↓
调用 Plugin.didReceive（响应后通知）
    ↓
回调 completion handler

Moya 本质是 Alamofire 的装饰器（Decorator），所有的实际网络操作都委托给 Alamofire，Moya 只负责协议声明、Plugin 拦截、Stub 切换。

Task 枚举的设计

Task 枚举涵盖了所有常见请求类型：

public enum Task {
    case requestPlain                              // 无 body
    case requestData(_ data: Data)                 // 原始 Data
    case requestParameters(parameters:encoding:)   // URL 参数 or JSON body
    case uploadMultipart(_ data: [MultipartFormData]) // 文件上传
    case downloadDestination(_ destination: DownloadDestination) // 文件下载
    case uploadCompositeMultipart(_, urlParameters:)  // 混合上传
    // ...
}

这种穷举枚举设计确保了所有请求形式都有类型安全的表达方式。

四、实战演示

场景：统一网络层封装（生产级模板）

// 1. 定义 API Target
enum NewsAPI {
    case topHeadlines(country: String, page: Int)
    case article(id: String)
}

extension NewsAPI: TargetType {
    var baseURL: URL { URL(string: "https://newsapi.org/v2")! }
    var path: String {
        switch self {
        case .topHeadlines: return "/top-headlines"
        case .article(let id): return "/articles/\(id)"
        }
    }
    var method: Moya.Method { .get }
    var task: Task {
        switch self {
        case .topHeadlines(let country, let page):
            return .requestParameters(
                parameters: ["country": country, "page": page, "pageSize": 20],
                encoding: URLEncoding.queryString
            )
        case .article: return .requestPlain
        }
    }
    var headers: [String: String]? { nil }
    var sampleData: Data { Data() }
}

// 2. Service 层封装（屏蔽 Moya 细节）
final class NewsService {
    private let provider = MoyaProvider<NewsAPI>(plugins: [
        TokenPlugin(),
        NetworkLoggerPlugin()
    ])

    func fetchHeadlines(country: String, page: Int) async throws -> [Article] {
        return try await withCheckedThrowingContinuation { cont in
            provider.request(.topHeadlines(country: country, page: page)) { result in
                switch result {
                case .success(let response):
                    do {
                        let articles = try response.map([Article].self, atKeyPath: "articles")
                        cont.resume(returning: articles)
                    } catch {
                        cont.resume(throwing: error)
                    }
                case .failure(let error):
                    cont.resume(throwing: error)
                }
            }
        }
    }
}

// 3. 业务层调用
let service = NewsService()
Task {
    let articles = try await service.fetchHeadlines(country: "cn", page: 1)
}

五、源码亮点

进阶层

TargetType 作为抽象屏障

Moya 的 MoyaProvider<Target: TargetType> 是泛型类型，每种 API 有独立的 Provider 实例。这意味着：

• 不同 API 服务（UserAPI / ProductAPI / OrderAPI）完全隔离
• 每个 Provider 可以配置不同的 Plugin（如不同的 Token 策略）
• 测试时替换 Provider 无需修改任何业务代码

深入层：网络层的 SOLID 原则

Moya 的设计完美体现了 SOLID 原则：

六、踩坑记录

问题 1：sampleData 返回空 Data 导致测试解析失败

• 原因：使用 StubbingProvider 但忘记实现 sampleData
• 解决：为每个需要测试的 case 提供合法 JSON 的 sampleData

问题 2：Plugin.prepare 中修改 headers 无效

• 原因：URLRequest 是值类型，必须先 copy 再修改
• 解决：

  func prepare(_ request: URLRequest, target: TargetType) -> URLRequest {
      var req = request  // ← copy 一份
      req.setValue("Bearer xxx", forHTTPHeaderField: "Authorization")
      return req         // ← 返回修改后的副本
  }
  

问题 3：Moya 请求不在主线程回调

• 原因：默认 callbackQueue 是 .main，但某些版本或配置下可能改变
• 解决：UI 更新前显式 DispatchQueue.main.async { ... } 或使用 .receive(on: MainScheduler.instance)

问题 4：多个 API 服务需要不同 baseURL

• 原因：Moya 一个 TargetType 对应一个 baseURL
• 解决：拆分为多个 enum（UserAPI, ProductAPI），各自独立 Provider

问题 5：文件上传进度无法监听

• 原因：回调方式无进度回调
• 解决：

  provider.request(.uploadAvatar(data: imageData)) { result in ... }
  // 上面不支持进度，改用：
  provider.requestWithProgress(.uploadAvatar(data: imageData)) { progress in
      print("上传进度:", progress.progress)
  }
  

七、延伸思考

同类方案对比

推荐使用场景

• ✅ API 接口较多（20+）的中大型 App
• ✅ 团队协作，需要统一的 API 文档化
• ✅ 需要完整的单元测试覆盖网络层
• ✅ 已经在使用 Alamofire 想升级架构

不推荐场景

• ❌ API 极少（3 个以内）→ 直接 Alamofire 更简单
• ❌ OC 项目 → Moya 纯 Swift，考虑 AFNetworking
• ❌ 追求最小依赖体积 → URLSession 直接封装

八、参考资源

• GitHub: Moya/Moya
• Moya 官方文档
• Moya 与 RxSwift 集成
• Moya 与 Combine 集成
• 系列 Demo 仓库：github.com/yourname/ios-lib-demos

九、本期互动

小作业

用 Moya 封装一个天气 API 服务层：定义 WeatherAPI enum，包含"当前天气"和"5天预报"两个 case，实现 TargetType，并编写一个 TokenPlugin 注入 API Key，最后用 StubbingProvider 为两个接口各写一个单元测试。评论区分享你的 TargetType 实现。

思考题

Moya 的 TargetType 强制将一个服务的所有 API 放在同一个 enum 里。当 API 接口很多时（50+），这个大 enum 会变得难以维护。你会如何设计拆分方案？能否在不改变使用方代码的前提下实现"API 分模块管理"？

读者征集

下一期我们将深入 SwiftyJSON（JSON 解析利器）。你在处理复杂嵌套 JSON 时用过哪些方案（SwiftyJSON / Codable / ObjectMapper / 手动解析）？在 OC 项目中你是如何处理 JSON 的？欢迎评论区分享。

📅 本系列每周五晚更新 ✅ 第11期：DGCharts · ✅ 第12期：Hero · ✅ 第13期：Realm · ➡️ 第14期：Moya · ○ 第15期：SwiftyJSON

本文中，我们将演示如何在 NativeScript 中使用 SwiftUI，共同探索构建精彩用户界面的新可能性。

前提条件

• macOS Catalina 或更高版本
• Xcode 11 或更高版本
• 运行 iOS 13 或更高版本的 iOS 设备/模拟器

SwiftUI 概念

现代 iOS 开发主要使用 Swift 编程语言。SwiftUI 采用了声明式的语法——你只需说明用户界面应当做什么。

我建议你先浏览一下官方的 SwiftUI 教程，以便熟悉基本概念。

创建 NativeScript 应用

我们可以使用标准的 TypeScript 模板来创建一个应用：

ns create swiftui --ts
cd swiftui

这会搭建一个通常被称为“原生风味”（vanilla）的 NativeScript 应用。换句话说，它提供了基本的数据绑定能力以及相当简单的设置。不过，我们在此介绍的内容适用于任何框架（Angular、React、Svelte、Vue 等）。

SwiftUI 插件

安装 SwiftUI 插件：

npm install @nativescript/swift-ui

注意： 你的最低 iOS 部署目标应至少为 13。

你可以在 App_Resources/iOS/build.xcconfig 文件中添加这一行：

IPHONEOS_DEPLOYMENT_TARGET = 13.0;

使用 SwiftUI

A. 创建你的 SwiftUI 视图

创建 App_Resources/iOS/src/SampleView.swift：

import SwiftUI

struct SampleView: View {

  var body: some View {
    VStack {
      Text("Hello World")
        .padding()
    }
  }
}

B. 创建你的 SwiftUI 提供者 (Provider)

这将为你的 SwiftUI 准备好与 NativeScript 的双向数据绑定。

创建 App_Resources/iOS/src/SampleViewProvider.swift：

import SwiftUI

@objc
class SampleViewProvider: UIViewController, SwiftUIProvider {

  // MARK: 初始化

  required init?(coder aDecoder: NSCoder) {
    super.init(coder: aDecoder)
  }

  required public init() {
    super.init(nibName: nil, bundle: nil)
  }

  public override func viewDidLoad() {
    super.viewDidLoad()
    setupSwiftUIView(content: swiftUIView)
  }

  // MARK: 私有部分

  private var swiftUIView = SampleView()

  /// 从 NativeScript 接收数据
  func updateData(data: NSDictionary) {
      // 可以留空
  }

  /// 允许向 NativeScript 发送数据
  var onEvent: ((NSDictionary) -> ())?
}

C. 插入到任意 NativeScript 布局中

• app/main-page.xml

<Page
  xmlns="http://schemas.nativescript.org/tns.xsd" 
  xmlns:sw="@nativescript/swift-ui" 
  class="page"
>
  <StackLayout>
    <sw:SwiftUI swiftId="sampleView" height="100" />
  </StackLayout>
</Page>

D. 通过 swiftId 注册你的 SwiftUI 视图

这一步可以在 NativeScript 应用的启动引导文件中完成（通常是 app.ts 或 main.ts）。

• app.ts

import { 
  registerSwiftUI, 
  UIDataDriver
} from "@nativescript/swift-ui";

// A. 你可以使用 'ns typings ios' 为你自己的 Swift Provider 生成类型定义
// B. 否则，可以通过声明你知道已提供的类名来忽略此步骤
declare const SampleViewProvider: any;

registerSwiftUI("sampleView", (view) =>
  new UIDataDriver(SampleViewProvider.alloc().init(), view)
);

现在你可以使用 ns debug ios 来运行应用了。

使用 Xcode 开发你的 SwiftUI

运行项目一次后，你就可以在 Xcode 中打开它，利用 Xcode 强大的智能感知辅助，进一步开发你的 SwiftUI。例如，在项目的根目录下执行：

open platforms/ios/swiftui.xcworkspace

你会发现你的 .swift 代码位于 TNSNativeSource 文件夹下，如下图所示

基础视图应用截图

高级 SwiftUI 集成

让我们深入一点，建立 SwiftUI 和 NativeScript 之间的数据绑定和事件交互。

创建 SwiftUI 组件

这可以是你想在 NativeScript 中使用的任何 SwiftUI 视图。

创建 App_Resources/iOS/src/SampleView.swift：

import SwiftUI

class ButtonProps: ObservableObject {
  @Published var count: Int = 0
  var incrementCount: (() -> Void)?
}

struct SampleView: View {

  @ObservedObject var props = ButtonProps()

  var body: some View {
      VStack(alignment: .center, spacing: 0) {
          HStack(alignment:.center) {
              Text("Count $props.count)")
                  .padding()
                  .scaledToFill()
                  .minimumScaleFactor(0.5)
          }
          HStack(alignment: .center) {
              Button(action: {
                  self.props.incrementCount?()
              }) {
                  Image(systemName: "plus.circle.fill")
                      .foregroundColor(.white)
                      .padding()
                      .background(LinearGradient(
                          gradient: Gradient(
                              colors: [Color.purple, Color.pink]), startPoint: .top, endPoint: .bottom
                      ))
                      .clipShape(Circle())
              }
          }
      }
      .padding()
      .clipShape(Circle())
  }
}

创建 App_Resources/iOS/src/SampleViewProvider.swift：

import SwiftUI

@objc
class SampleViewProvider: UIViewController, SwiftUIProvider {

  // MARK: 初始化

  required init?(coder aDecoder: NSCoder) {
    super.init(coder: aDecoder)
  }

  required public init() {
    super.init(nibName: nil, bundle: nil)
  }

  public override func viewDidLoad() {
    super.viewDidLoad()
    setupSwiftUIView(content: swiftUIView)
    registerObservers()
  }

  // MARK: 私有部分

  private var swiftUIView = SampleView()

  private func registerObservers() {
    swiftUIView.props.incrementCount = {
      let count = self.swiftUIView.props.count + 1
      // 更新 swiftUI 视图
      self.swiftUIView.props.count = count
      // 通知 nativescript
      self.onEvent?(["count": count])
    }
  }

  // MARK: API

  /// 从 NativeScript 接收数据
  func updateData(data: NSDictionary) {
    if let count = data.value(forKey: "count") as? Int {
      // 更新 swiftUI 视图
      swiftUIView.props.count = count
      // 通知 nativescript
      self.onEvent?(["count": count])
    }
  }

  /// 向 NativeScript 发送数据
  var onEvent: ((NSDictionary) -> Void)?
}

在 NativeScript 布局中使用你的 SwiftUI

• app/main-page.xml:

<Page
  xmlns="http://schemas.nativescript.org/tns.xsd"
  xmlns:sw="@nativescript/swift-ui"
  navigatingTo="navigatingTo"
>
  <StackLayout>
    <sw:SwiftUI swiftId="sampleView" data="{{ nativeCount }}" swiftUIEvent="{{ onEvent }}" loaded="{{ loadedSwiftUI }}" />
    <Label text="{{ 'NativeScript Label: ' + nativeCount.count }}" class="h2" />
    <Button text="NativeScript 数据绑定: 减少" tap="{{ updateNativeScriptData }}" class="btn btn-primary" />
    <Button text="SwiftUI 数据绑定: 减少" tap="{{ updateSwiftData }}" class="btn btn-primary" />
  </StackLayout>
</Page>

• app/main-page.ts:

import {
  registerSwiftUI,
  UIDataDriver,
  SwiftUI,
  SwiftUIEventData,
} from "@nativescript/swift-ui";
import { 
  EventData,
  Observable,
  Page
} from "@nativescript/core";

// A. 你可以使用 'ns typings ios' 为你自己的 Swift Provider 生成类型定义
// B. 否则，可以通过声明你知道已提供的类名来忽略此步骤
declare const SampleViewProvider: any;

registerSwiftUI("sampleView", (view) =>
  new UIDataDriver(SampleViewProvider.alloc().init(), view)
);

interface CountData {
  count: number;
}

export function navigatingTo(args: EventData) {
  const page = <Page>args.object;
  page.bindingContext = new DemoModel();
}

export class DemoModel extends Observable {
  swiftui: SwiftUI;
  nativeCount = {
    count: 0,
  };

  loadedSwiftUI(args) {
    this.swiftui = args.object;
  }

  onEvent(evt: SwiftUIEventData<CountData>) {
    this.set("nativeCount", { count: evt.data.count });
  }

  updateNativeScriptData() {
    this.set('nativeCount', { count: this.nativeCount.count - 1 });
  }

  updateSwiftData() {
    this.swiftui.updateData({ count: this.nativeCount.count - 1 });
  }
}

dev.to/valorsoftwa…

我已经失去了编写代码的能力，变成只会写提示词的提示词工程师。但也没有完全丧失，我还会Review代码，偶尔手动改几行代码。

比如用Swift写UI，我在完全不复制粘贴的情况下，已经不会从0行代码写出一个页面，只会在AI生成的代码微调布局。

准确的说，不是丧失了能力，而是丧失了记忆！

回顾最近在开发ApiCatcher这款iOS端HTTPS抓包和调试工具的过程中，除了用AI开发核心功能遇到困难，其实在开发UI过程中也遇到一些困难。

今天分享我用AI开发ApiCatcher UI遇到的两个问题。解决这两个问题，我从Gemini 3.1 Pro模型，升级到Claude Opus 4.6模型，又从Claude Opus 4.6模型降到Gemini 3 Flash，最新只用Gemini 3 Flash就解决了问题。

第一个案例，我让AI帮我开发ApiCatcher的“AI对话生成脚本”功能，这里遇到的问题就是Markdown渲染。AI响应的消息里面包含代码。

关于UI，我的提示词大概是这样的：

页面做成聊天对话界面，底部是输入框和发送按钮，其余空间是显示聊天记录，用户只能发送文本消息，AI响应的消息是Markdown格式，AI响应的消息包含代码块，需要能高亮渲染代码块，代码不自动换行，而是代码块可以左右滚动。

这里的难点就是要支持代码块的高亮和代码块可以水平滚动。

无论是Gemini还是Claude，他们的思路都是先用开源的Swift语言编写的Markdown渲染开源库，怎么调都调不出令我满意的效果，渲染结果太丑了。在尝试完几个开源库后，Gemini和Claude会走向自己实现，写得非常复杂，然后实现的效果更加糟糕！

在无数次挫败后，我开始自己思考解决方案。我告诉Claude，SwiftUI的Markdown渲染开源库不好用，我们可以用Web技术栈，找JS开源库，然后用WebView来渲染Markdown消息。

这次Claude终于开窍了，但也没完全开窍。他把每个Markdown消息，都用一个WebView来渲染....

我再告诉他，为什么不是只用一个WebView来渲染所有消息呢？这时候Claude限制额度了......

我降回了Gemini 3 Flash。终于在几次调整后，Gemini做出了我想要的效果。

最终用到的技术栈：WebView、CodeMirror、Highlight.js。

第二个案例，JSON可折叠可搜索。

这次一上来就用Claude Sonnet 4.6模型，提示词：帮我实现JSON全屏预览页面，要求：JSON高亮显示，路径可以折叠和展开，可以搜索，搜索结果高亮，可以点击“下一个”按钮跳转到下一个搜索结果的位置。

Claude还是一样的思路，先找SwiftUI的开源库，但折腾半天卡在了搜索功能。还是一样折腾到耗尽Claude额度。

SwiftUI没有好用的开源库，那就换个思路，于是我又想到了WebView。最后选择WebView+CodeMirror+Highlight.js，加上CodeMirror的一个行号插件、搜索插件，用Gemini 3 Flash开发，完美实现！

在这两个案例中，无论是Claude还是Gemini，他们的思考方式都是先找SwiftUI可以使用的开源库，如果达不到目的，就改变策略，自己实现，但这种复杂的任务，他们根本没能力实现好。他们无法变通到通过WebView去乔接，从使用Swift技术栈，转变为使用Web开发技术栈。

我们只要告诉AI方法，他们就能实现，所以，目前AI的能力，其实受限于使用者的能力、认知。初级程序员+AI 无法超越 高级程序员+AI！

未来提示词会替代编程语言，程序员从写代码变成写提示词，但我们依然需要学习提升写提示词的能力。编程能力从来不是指代码写得多漂亮，而是对底层原理的认知深度，同样写提示词的能力也并非是指表达能力，同样是对底层原理的认知深度和广度。

以上面两个案例为例，我们需要认识到Swift原生开发并不是只能使用Swift，SwiftUI开发的原生应用也可以使用WebView来渲染网页，可以Swift生成网页代码传递给WebView渲染，并且可以生成JS代码让WebView执行。我们可以不懂怎么去写代码实现，只需要知道可以这样做，这极大降低了学习难度！

AI放大了我们个人的能力：从需要学会如何编码实现，了解具体的底层原理，到只需要知道可以这样实现。

但只是放大个人能力，AI遇强则强，遇弱则弱，我们依然需要保持学习。

【AFNetworking】OC 时代网络请求事实标准，Alamofire 的前身

iOS三方库精读 · 第 9 期

一、一句话介绍

AFNetworking 是 iOS / macOS 平台上最早也是最成功的 Objective-C HTTP 网络库，它让网络请求从繁琐的 NSURLConnection / NSURLSession API 变得简洁优雅，成为 OC 时代的事实标准。

二、为什么选择它

原生痛点（2011 年的 iOS 世界）

在没有 AFNetworking 之前，iOS 开发者不得不面对：

• NSURLConnection 样板代码：每次请求都要实现 delegate 回调，代码分散难以维护
• JSON 解析手动处理：iOS 5 之前没有 NSJSONSerialization，需要第三方库
• 图片加载无缓存：网络图片每次都要重新下载，没有内存/磁盘缓存
• 网络状态监听复杂：Reachability API 繁琐，代码量大
• HTTPS 配置困难：自签名证书、SSL Pinning 需要深入了解安全 API

AFNetworking 核心优势

1. 一行代码发起请求：GET / POST / PUT / DELETE 统一 API，无需 delegate
2. 自动序列化：JSON / XML / Plist / Image 响应自动解析
3. UIImageView Category：setImageWithURL: 一行搞定网络图片加载
4. Reachability 内建：实时监听网络状态，断网自动提示
5. SSL Pinning 支持：证书校验一行配置，安全合规
6. Block 回调：告别分散的 delegate，代码逻辑更清晰

原生 API vs AFNetworking

三、核心功能速览

基础层 概念解释、环境配置、基础用法

环境配置

CocoaPods（OC 项目首选）

pod 'AFNetworking', '~> 4.0'

Swift Package Manager

// Package.swift
dependencies: [
    .package(url: "https://github.com/AFNetworking/AFNetworking.git", from: "4.0.0")
]

Swift 项目桥接

// {ProjectName}-Bridging-Header.h
#import <AFNetworking/AFNetworking.h>
#import "UIImageView+AFNetworking.h"

基础 GET 请求

// AFNetworking 4.x (OC)
AFHTTPSessionManager *manager = [AFHTTPSessionManager manager];

[manager GET:@"https://jsonplaceholder.typicode.com/users"
  parameters:nil
    progress:nil
     success:^(NSURLSessionDataTask *task, id responseObject) {
         NSLog(@"成功: %@", responseObject);
     }
     failure:^(NSURLSessionDataTask *task, NSError *error) {
         NSLog(@"失败: %@", error.localizedDescription);
     }];

进阶层 最佳实践、性能优化、线程安全

POST 请求带参数

NSDictionary *params = @{
    @"name": @"张三",
    @"email": @"zhangsan@example.com",
    @"age": @28
};

[manager POST:@"https://api.example.com/users"
   parameters:params
     progress:nil
      success:^(NSURLSessionDataTask *task, id responseObject) {
          NSLog(@"创建成功: %@", responseObject);
      }
      failure:^(NSURLSessionDataTask *task, NSError *error) {
          NSLog(@"创建失败: %@", error);
      }];

文件上传

NSData *imageData = UIImageJPEGRepresentation(image, 0.8);

[manager POST:@"https://api.example.com/upload"
   parameters:nil
    constructingBodyWithBlock:^(id<AFMultipartFormData> formData) {
        [formData appendPartWithFileData:imageData
                                    name:@"file"
                                fileName:@"photo.jpg"
                               mimeType:@"image/jpeg"];
    }
     progress:^(NSProgress *progress) {
         NSLog(@"上传进度: %.0f%%", progress.fractionCompleted * 100);
     }
      success:^(NSURLSessionDataTask *task, id responseObject) {
          NSLog(@"上传成功");
      }
      failure:^(NSURLSessionDataTask *task, NSError *error) {
          NSLog(@"上传失败: %@", error);
      }];

图片加载（UIImageView Category）

#import "UIImageView+AFNetworking.h"

// 基础用法
[imageView setImageWithURL:[NSURL URLWithString:@"https://example.com/avatar.jpg"]];

// 带占位图
[imageView setImageWithURL:[NSURL URLWithString:@"https://example.com/avatar.jpg"]
         placeholderImage:[UIImage imageNamed:@"default_avatar"]];

// 取消加载（cell 复用场景）
[imageView cancelImageDownloadTask];

网络状态监听

[[AFNetworkReachabilityManager sharedManager] setReachabilityStatusChangeBlock:
    ^(AFNetworkReachabilityStatus status) {
        switch (status) {
            case AFNetworkReachabilityStatusNotReachable:
                NSLog(@"无网络连接");
                break;
            case AFNetworkReachabilityStatusReachableViaWiFi:
                NSLog(@"WiFi 连接");
                break;
            case AFNetworkReachabilityStatusReachableViaWWAN:
                NSLog(@"蜂窝网络");
                break;
            default:
                break;
        }
    }];

[[AFNetworkReachabilityManager sharedManager] startMonitoring];

HTTPS 证书校验

manager.securityPolicy = [AFSecurityPolicy policyWithPinningMode:AFSSLPinningModeCertificate];
manager.securityPolicy.allowInvalidCertificates = YES;  // 允许自签名
manager.securityPolicy.validatesDomainName = YES;

深入层 源码解析、设计思想、扩展定制

核心类关系

AFURLSessionManager (核心)
    ├── AFHTTPSessionManager (HTTP 封装)
    │       ├── requestSerializer (请求序列化)
    │       └── responseSerializer (响应序列化)
    ├── AFSecurityPolicy (安全策略)
    └── AFNetworkReachabilityManager (网络监听)

Category 扩展:
    UIImageView+AFNetworking (图片加载)
    UIProgressView+AFNetworking (进度条)
    AFNetworkActivityIndicatorManager (状态栏网络指示器)

Session Manager 核心设计

// AFHTTPSessionManager 继承 AFURLSessionManager
// 职责分离：网络层、请求构建、响应解析各自独立

@interface AFHTTPSessionManager : AFURLSessionManager
@property (nonatomic, strong) AFHTTPRequestSerializer <AFURLRequestSerialization> *requestSerializer;
@property (nonatomic, strong) AFHTTPResponseSerializer <AFURLResponseSerialization> *responseSerializer;
@end

// 序列化协议设计
@protocol AFURLRequestSerialization <NSObject>
- (NSURLRequest *)requestBySerializingRequest:(NSURLRequest *)request
                                withParameters:(id)parameters
                                         error:(NSError * __autoreleasing *)error;
@end

四、实战演示

场景：完整的网络请求封装

// APIClient.h - 统一网络请求封装
#import <AFNetworking/AFNetworking.h>

@interface APIClient : AFHTTPSessionManager
+ (instancetype)sharedClient;

// 业务方法
- (void)fetchUsers:(void(^)(NSArray *users, NSError *error))completion;
- (void)createUser:(NSDictionary *)params
        completion:(void(^)(NSDictionary *user, NSError *error))completion;
- (void)uploadAvatar:(UIImage *)image
           completion:(void(^)(NSString *url, NSError *error))completion;
@end

// APIClient.m
@implementation APIClient

+ (instancetype)sharedClient {
    static APIClient *instance;
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        NSURL *baseURL = [NSURL URLWithString:@"https://api.example.com/"];
        instance = [[self alloc] initWithBaseURL:baseURL];
        
        // 配置请求/响应序列化
        instance.requestSerializer = [AFJSONRequestSerializer serializer];
        instance.responseSerializer = [AFJSONResponseSerializer serializer];
        instance.requestSerializer.timeoutInterval = 30;
        
        // 添加通用请求头
        [instance.requestSerializer setValue:@"application/json"
                             forHTTPHeaderField:@"Content-Type"];
        
        // HTTPS 配置
        instance.securityPolicy = [AFSecurityPolicy policyWithPinningMode:AFSSLPinningModeNone];
    });
    return instance;
}

- (void)fetchUsers:(void(^)(NSArray *users, NSError *error))completion {
    [self GET:@"users"
      parameters:nil
        progress:nil
         success:^(NSURLSessionDataTask *task, id responseObject) {
             completion(responseObject, nil);
         }
         failure:^(NSURLSessionDataTask *task, NSError *error) {
             completion(nil, error);
         }];
}

- (void)createUser:(NSDictionary *)params
        completion:(void(^)(NSDictionary *user, NSError *error))completion {
    [self POST:@"users"
   parameters:params
     progress:nil
      success:^(NSURLSessionDataTask *task, id responseObject) {
          completion(responseObject, nil);
      }
      failure:^(NSURLSessionDataTask *task, NSError *error) {
          completion(nil, error);
      }];
}

- (void)uploadAvatar:(UIImage *)image
           completion:(void(^)(NSString *url, NSError *error))completion {
    NSData *data = UIImageJPEGRepresentation(image, 0.8);
    
    [self POST:@"upload"
   parameters:nil
    constructingBodyWithBlock:^(id<AFMultipartFormData> formData) {
        [formData appendPartWithFileData:data
                                    name:@"avatar"
                                fileName:@"avatar.jpg"
                               mimeType:@"image/jpeg"];
    }
     progress:nil
      success:^(NSURLSessionDataTask *task, id responseObject) {
          NSString *url = responseObject[@"url"];
          completion(url, nil);
      }
      failure:^(NSURLSessionDataTask *task, NSError *error) {
          completion(nil, error);
      }];
}

@end

五、源码亮点

进阶层 值得借鉴的用法

序列化器组合模式

// 请求序列化器可插拔
manager.requestSerializer = [AFJSONRequestSerializer serializer];   // JSON
manager.requestSerializer = [AFPropertyListRequestSerializer serializer];  // Plist

// 响应序列化器可插拔
manager.responseSerializer = [AFJSONResponseSerializer serializer];  // JSON
manager.responseSerializer = [AFXMLParserResponseSerializer serializer];  // XML
manager.responseSerializer = [AFImageResponseSerializer serializer];  // Image

Block 回调替代 Delegate

// 传统 delegate 分散在多个方法
// AFNetworking 用 block 聚合逻辑
[manager GET:url
  parameters:params
    progress:^(NSProgress *progress) {
        // 进度回调
    }
     success:^(NSURLSessionDataTask *task, id responseObject) {
        // 成功回调
    }
     failure:^(NSURLSessionDataTask *task, NSError *error) {
        // 失败回调
    }];

深入层 设计思想解析

NSURLSession 封装架构

// AFURLSessionManager 核心方法
- (NSURLSessionDataTask *)dataTaskWithRequest:(NSURLRequest *)request
                            completionHandler:(void (^)(NSURLResponse *, id, NSError *))handler {
    // 1. 创建 task
    NSURLSessionDataTask *task = [self.session dataTaskWithRequest:request];
    
    // 2. 存储 task delegate（用于回调）
    self.mutableTaskDelegatesKeyedByTaskIdentifier[@(task.taskIdentifier)] = delegate;
    
    // 3. 返回 task
    return task;
}

// task delegate 处理各种回调
- (void)URLSession:(NSURLSession *)session
          dataTask:(NSURLSessionDataTask *)dataTask
    didReceiveData:(NSData *)data {
    // 累积数据，最终一次性回调
    [mutableData appendData:data];
}

UIImageView Category 的缓存设计

// UIImageView+AFNetworking 内部使用 AFImageDownloader
// 自动实现内存缓存 + 磁盘缓存

@interface AFImageDownloader : NSObject
@property (nonatomic, strong) AFImageCache *imageCache;  // 内存缓存
@property (nonatomic, strong) NSURLCache *urlCache;       // 磁盘缓存
@end

// 缓存策略
- (void)downloadImageForURLRequest:(NSURLRequest *)request
                        completion:(void (^)(UIImage *, NSError *))completion {
    // 1. 先查内存缓存
    // 2. 再查磁盘缓存
    // 3. 最后发起网络请求
}

六、踩坑记录

问题 1：iOS 9+ ATS 限制

问题：iOS 9 默认要求 HTTPS，HTTP 请求被阻止。

原因：App Transport Security (ATS) 默认禁止明文 HTTP。

解决：

<!-- Info.plist 添加例外 -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

问题 2：Response Serializer 编码问题

问题：返回中文乱码或解析失败。

原因：服务器返回非 UTF-8 编码，AFJSONResponseSerializer 默认 UTF-8。

解决：

AFHTTPResponseSerializer *serializer = [AFHTTPResponseSerializer serializer];
serializer.stringEncoding = NSUTF8StringEncoding;  // 或其他编码
manager.responseSerializer = serializer;

问题 3：Cell 复用图片错乱

问题：UITableView 快速滚动时，图片显示错误。

原因：Cell 复用时未取消之前的下载任务。

解决：

- (void)prepareForReuse {
    [super prepareForReuse];
    [self.imageView cancelImageDownloadTask];  // 取消之前的下载
    self.imageView.image = nil;
}

问题 4：后台任务未处理

问题：App 进入后台后，下载任务中断。

原因：NSURLSession 默认不支持后台。

解决：

// 使用后台 session configuration
NSURLSessionConfiguration *config = [NSURLSessionConfiguration backgroundSessionConfigurationWithIdentifier:@"com.example.background"];
AFHTTPSessionManager *manager = [[AFHTTPSessionManager alloc] initWithSessionConfiguration:config];

问题 5：Swift 混编桥接头文件缺失

问题：Swift 项目中使用 AFNetworking 报找不到模块。

原因：未配置 Objective-C Bridging Header。

解决：

1. 创建 {ProjectName}-Bridging-Header.h 文件
2. 添加 #import <AFNetworking/AFNetworking.h>
3. Build Settings → Swift Compiler - General → Objective-C Bridging Header 设置路径

七、延伸思考

AFNetworking vs Alamofire 横向对比

API 对照迁移表

选型建议

选 AFNetworking：

• 维护遗留 OC 项目，迁移成本高
• 项目需要支持 iOS 9 ~ iOS 11
• 团队 OC 技术栈成熟，Swift 经验少

选 Alamofire：

• 新项目，Swift 为主要语言
• 需要 Combine / async-await 集成
• 想要更活跃的社区和持续更新
• 最低支持 iOS 12+

渐进式迁移策略

1. 共存阶段：OC 模块继续用 AFNetworking，新 Swift 模块用 Alamofire
2. 抽象层：统一封装 NetworkService 协议，底层可替换
3. 按模块迁移：优先迁移独立的业务模块，而非逐个请求修改
4. 测试覆盖：迁移前后确保集成测试通过

八、参考资源

官方资源

• GitHub 仓库
• 官方文档

相关文章

• AFNetworking 3.0 迁移指南 - Mattt Thompson | 2015
• 从 AFNetworking 到 Alamofire - Ash Furrow | 2015

系列 Demo 仓库

• github.com/ios-lib-dem… - 本系列配套代码

本期互动

小作业

查看你现有的 OC 项目中 AFNetworking 的使用方式，尝试将一个简单的 GET 请求改写为 Alamofire 版本，对比代码量和可读性变化。

思考题

AFNetworking 从 1.x 到 4.x 经历了 NSURLConnection → NSURLSession 的底层迁移，如果你是核心开发者，你会如何设计 API 以保持向后兼容？

读者征集

你在从 AFNetworking 迁移到 Alamofire 的过程中遇到过哪些坑？欢迎评论区分享，优质回答会收录进下一期《踩坑记录》。

📅 本系列每周五晚更新 · 已学习：[✓ Alamofire] [✓ Kingfisher] [✓ Lottie] [✓ MarkdownUI] [✓ SDWebImage] [✓ SnapKit] [✓ ListDiff] [✓ RxSwift] [→ AFNetworking] [○ Charts]