docs: 重构 README 突出 AI 导航层核心价值 - #13
tommywutong wants to merge 7 commits into
Conversation
重新组织 README 结构，解决原版信息层级不清晰的问题： - 顶部 banner 明确"给 AI Agent 用"的独特定位 - 新增"痛点→解决方案"板块，3 秒内让读者理解项目价值 - 三大核心资产可视化展示（62 个地图 + 行为规范 + 版本管理） - 快速开始增加具体提问示例，展示完整工作流 - 新增版本覆盖表格，清晰展示所有仓库的锁定策略 - 优化视觉层次（emoji 分隔 + 表格 + 代码块） 验证：Markdown 格式正确，无敏感信息，无冲突标记
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
PR Review Swarm — batch 1/1
2 finding(s) in this batch (see inline comments below).
| 跨仓库接缝一律带 `@_spi(SwiftCorelibsFoundation)` 标记。 | ||
| | 类别 | 覆盖范围 | 地图数量 | | ||
| |------|---------|---------| | ||
| | **Apple 底层** | objc4 (runtime, isa, msgSend, cache_t, ARC)<br>CoreFoundation (RunLoop, CFString)<br>libdispatch (GCD, Queue, Semaphore)<br>swift-foundation (Swift 重写的 Foundation) | ~40 个 | |
There was a problem hiding this comment.
[low] README 地图数量自相矛盾（~40 + ~8 + ~14 ≠ 62）
第 37-39 行把 62 个地图拆成 ~40 个（Apple 底层）、~8 个（参考实现）、~14 个（三方库），40+8+14=62 与顶部标称一致；但第 133-142 行的
版本覆盖表格又把各仓库地图数分别写成 6/8/6/4/4/8/4/3/3/4，合计 50 个，且 objc4 6 个、CF 8 个与
第 37 行 Apple 底层 ~40 个无法对齐。同一份 README 内存在两套互不吻合的地图计数口径。
统一所有地图计数为同一口径（如把版本表里的数量改为与顶部 62 份一致，或删除类别处的 ~ 估算），确保全文只有一套数字。
| <div align="center"> | ||
|
|
||
| 本仓库**不搬运任何源码**，只提供三样东西——而这三样恰恰是"下载了源码却读不动"的真正卡点： | ||
| [](maps/) |
There was a problem hiding this comment.
[medium] 重写后丢失了大量关键操作规范与行为细节
PR 重写 README，删除了大量实操内容：退出码语义表（0 UPTODATE / 10 UPDATE / 2 ERROR）、NOTICE 不改变退出码的约定、update-sources.sh 三种策略对四份第三方库和 objc4 只 fetch 不切 ref 的说明、track 策略核对当前分支否则报 ERROR/跳过的逻辑、贡献地图的硬规则（先写 maps/ 再 bootstrap --maps-only、AGENTS.md 存正文 CLAUDE.md 为指针、根 CLAUDE.md 必须为符号链接而非指针）、升版需同步校对行号的告警。这些是被脚本与 AGENTS.md 行为依赖的文档契约，重写后未在新 README 中保留。
把被删除的退出码表、三种更新策略的约束、以及「新增地图必须先在 maps/ 写入并跑 --maps-only」「根 CLAUDE.md 必须是符号链接」「升版须同步校对行号」等硬规则补回 README，或至少在贡献指南中保留链接。
PR Review SwarmVerdict: pass Findings (0):
|
There was a problem hiding this comment.
PR Review Swarm — batch 1/1
2 finding(s) in this batch (see inline comments below).
| # iOS Source Learning | ||
|
|
||
| 给 **AI agent** 用的源码导航层，覆盖三类： | ||
| > 🤖 **给 AI Agent 用的 iOS 源码导航层** |
There was a problem hiding this comment.
[low] 宣传文案 31 份/62 文件与地图数量对应关系残留不一致
第 3 行写『31 份手写源码地图』，第 34 行解释『两类文件共 62 个，统计口径始终是 31 份』。第 38-41 行分区表合计 12+1+18=31 份。但第 135 行版本表中 objc4-apple 写 7 份且第 136-141 行 6 个仓库各 1 份（Apple 底层总计 12），其中只有 objc4 一个仓库存分模块多份；而第 40 行第三方库 18 份对应 4+5+3+6=18。若 objc4 实为 7，则 12 的分区数字和 31 总计仍自洽，但与原『6 份』记录冲突，见 gm-1。整体重构后所有数字仅在内部一致（31=12+1+18=7+...+6），看不到对仓库实际内容的核对。
以 maps/ 目录真实文件数为准复核 31 与各分区数字，并在 PR 中说明统计口径。
| 所以**就地编辑就行**——改 `new objc4/runtime/AGENTS.md` 等于改 `maps/new objc4/runtime/AGENTS.md`，改动会直接出现在本仓库的 `git status` 里。 | ||
| ### 提交流程 | ||
| 1. Fork 本仓库并创建分支。 | ||
| 2. 新地图必须先写在 `maps/` 对应位置，再运行 `./bootstrap.sh --maps-only` 挂载；直接在下载的源码目录新建文件会成为游离文件，其他人 clone 不到。 |
There was a problem hiding this comment.
[low] 提交流程引用 bootstrap.sh --maps-only 但 Step 说明中该参数在正文被删除
第 193 行要求『运行 ./bootstrap.sh --maps-only 挂载』，第 194 行要求每次添加地图遵循此流程。但第 71 行快速开始只给出 ./bootstrap.sh，无 --maps-only 说明。旧 README 曾对此参数有『只重挂地图，不下载（旧名 --notes-only 仍可用）』的解释，本 PR 删除了这段说明但仍在贡献指南引用同一参数，使贡献者无从了解该参数含义。
在快速开始或脚本使用说明中保留 --maps-only 的简短说明，避免仅在被引用的流程里出现而未作解释。
| |------|---------|---------|---------| | ||
| | **objc4-apple** | `objc4-951.7` | 钉死标签 | 7 | | ||
| | **CF-apple** | `main`（停在 `CF-1153.18`） | 跟踪分支 | 1 | | ||
| | **libdispatch-apple** | 版本号最高的 tag | 自动跟踪 | 1 | |
There was a problem hiding this comment.
[low] libdispatch-apple 更新策略在 README 两处矛盾
第 143 行「版本覆盖表」写 libdispatch-apple 策略「自动跟踪」；第 176-178 行写「latest 目标会切到版本号最高的 tag」；但第 173-174 行又说「钉在 tag…绝不自动切换 ref」，而第 178 行称 latest 自动切 tag。同一份 README 对 libdispatch-apple 的行为描述前后不一致，且其「自动跟踪/最新 tag」与 143 行的措辞也不统一。
统一「版本覆盖表」与更新机制章节对 libdispatch-apple「最新标签自动切」的措辞，明确一键脚本会/不会改变该目标 ref。
|
|
||
| 本仓库**不搬运任何源码**，只提供三样东西——而这三样恰恰是"下载了源码却读不动"的真正卡点： | ||
| [](maps/) | ||
| [](#版本覆盖) |
There was a problem hiding this comment.
[low] Broken internal Markdown anchors in badge links
Lines 9-10: '
Drop the emojis from the section headings or reference them exactly, e.g. use '#📌-版本覆盖' and '#📄-许可证' (with the emoji, spaces as hyphens) so the anchors resolve correctly.
|
|
||
| | 仓库 | 当前 ref | 更新策略 | 地图数量 | | ||
| |------|---------|---------|---------| | ||
| | **objc4-apple** | `objc4-951.7` | 钉死标签 | 7 | |
There was a problem hiding this comment.
[low] Version cover table omits swift-corelibs-libdispatch, contradicts '31 份' elsewhere
Line 139-152 lists 8 repos summing to 7+1+1+1+1+1+1+4+5+3+6 = 31, but the table's rows (objc4-apple, CF-apple, libdispatch-apple, swift-corelibs-libdispatch, swift-corelibs-foundation, swift-foundation, gnustep-base, AFNetworking, JSONModel, YYModel, SDWebImage) — swift-corelibs-libdispatch row has '地图数量 1'. However the map-count breakdown in '## 📦 三大核心资产' (line 38: 'Apple 底层 12 份 / 参考实现 1 份 / 三方库 18 份') states 12+1+18=31 yet here Apple底层 repos (objc4 7 + CF 1 + libdispatch-apple 1 + swift-corelibs-libdispatch 1 + swift-foundation 1) = 12 without counting swift-corelibs-foundation; the categories in the two tables use different groupings (swift-corelibs-foundation counted under Apple底 in one, under nothing clearly in the other), making the '31' invariant impossible to reconcile and easy to break on future edits.
Derive the per-category counts from the version table (single source of truth) or explicitly state the grouping rules; at minimum add a comment that both tables must sum to 31 and that categories use consistent repo assignment.
| ./bootstrap.sh --check # 只体检：本地有什么、缺什么、链接是否完好，不改动 | ||
| ./bootstrap.sh -n # 演练，只报告不改动 | ||
| ./bootstrap.sh --maps-only # 只重挂地图，不下载（旧名 --notes-only 仍可用） | ||
| git clone https://github.com/XiyouMobile3G-iOS/ios-source-learning.git |
There was a problem hiding this comment.
[low] 中文与英文 README 混排且同仓库名称不一致
该 PR 将 README 标题改为英文 'iOS Source Learning'（第 1 行），正文却全为中文；旧快速开始处仓库链接描述 'ios-source-learning.git'（第 69 行 clone 命令）与标题 'iOS Source Learning' 及文件中的反引号英文路径（'new objc4/runtime' 第 94 行）混排。仓库既有文档为全中文风格，本次重写引入英文标题+中文正文的混排，未保持原仓库风格约定。
保持原仓库全中文风格，或明确声明双语；标题与正文语言应一致。
| # iOS 源码学习工作区 | ||
|
|
||
| 给 **AI agent** 用的源码导航层，覆盖三类： | ||
| > 🤖 **给 AI Agent 用的 iOS 源码导航层** |
| 搭好之后，在这个目录里启动你的 agent，直接问就行： | ||
| ### 痛点 | ||
| - ❌ AI 回答 iOS 底层问题时容易**幻觉**（编造 API、混淆版本） | ||
| - ❌ 源码版本不一致导致**行号对不上**、讨论无法复现 |
dustPyrotechnic
left a comment
dustPyrotechnic
left a comment
There was a problem hiding this comment.
修了emoji 等问题，不要大规模修改我的readme
2 participants
概述
重构 README，解决原版信息层级不清晰、核心价值不突出的问题。
主要改进
1. 顶部 Banner 区域 ⭐
2. 痛点→解决方案板块 🎯
3. 三大核心资产可视化 📦
4. 快速开始增强 🚀
5. 版本覆盖表格 📌
6. 视觉优化 🎨
验证
预期效果
新用户能够在 30 秒内理解：
🤖 Generated with Claude Code