# 拆free5gc：写给AI的5G错题本 ## 概述 本期继续本栏的 Skills 生态观察，轮到单件深拆。这次拆的对象不在热榜上，而是一件自用件：装在个人技能目录里的 `free5gc`——一份基于真实源码的 free5GC 开源 5G 核心网代码地图，覆盖 AMF、SMF、UPF 等十四个网元的目录结构、关键数据结构与三大信令流程的代码路径。选它，是因为它把 Skills 写法里最容易被忽略的一件事做到了极致：**防幻觉**。整份 SKILL.md 最贵的段落不是知识本身，而是一张「常见错误纠正」黑名单——作者把大模型最爱编造的文件名、函数签名逐条刻成了错题本，再配上强制验证流程和自包含的规范映射库。本文拆到写法层面，最后提炼三条可直接抄走的设计模式，以及三处暗伤。 ## 评测对比表 | 维度 | 权重 | 评分 | 一句话依据 | |------|------|------|-----------| | 功能完整度 | 25% | ★★★★ | 十四网元知识全覆盖，附三大流程代码链；但只管「读懂」，不管部署运维 | | 设计质量 | 25% | ★★★★★ | 错题本黑名单、行号锚点、自包含规范库，防幻觉制度三者齐备 | | 实战效果 | 20% | ★★★★ | 强制「先 Read 验证再引用」，直击代码分析类任务的头号翻车点 | | 上手难度 | 15% | ★★★★ | 零配置，提问即用；但读者需自备 5G 协议基础 | | 社区活跃度 | 15% | ★★★ | 上游 free5GC 是活跃开源项目，技能本体属个人件，单点维护 | 加权总分 **4.1**。说明：评分对象是这份 SKILL.md 的写法，不是 free5GC 项目本身；本期不引用 star 数，社区维度按上游项目活跃度与技能维护模式折算。 ## 一、定位：一件「读代码」的技能，不是「干活」的技能 先给技能定性，因为这决定了它该怎么被评价。 市面上大多数 Skills 在教 Agent「做事」：建一份 PPT、发一封邮件、部署一个站点，靠脚本和流程把动作固化。`free5gc` 属于另一个物种——**知识件**。它没有任何可执行脚本，全部内容是一份解剖图：free5GC 这个开源 5G 核心网项目的源码地图。技能开头三行就把身份交代清楚了： > 基于真实源码的 free5GC 5G 核心网完整代码分析，涵盖全部15个网元功能(NF)。 > GitHub：https://github.com/free5gc/free5gc > 最后更新：2026年3月22日 三行里有两行是「信用背书」：声明知识来自真实源码而非模型记忆，给出可追溯的上游仓库，再钉一个快照日期。这三行是整件技能的立身之本——它卖的不是能力，是**准确性**。后面所有设计都围绕这一句展开。 ## 二、逐段拆解：一份解剖图的五层结构 ### 第一层：快速索引表——先给目录，再给内容 SKILL.md 紧接着是一张十四行的速查表，每行四个字段：网元名、Go 文件数、主要功能、关键目录。AMF 89 个文件管接入和移动性，SMF 91 个管会话，UPF 33 个管用户面，CHF 以 267 个文件成为全场最大件——计费功能带着整套 Diameter 协议栈和 ABMF、CGF 子系统。 这张表的设计意图很清楚：**让模型先用一行锁定地标，再决定要不要下钻**。Agent 收到「PDU 会话在哪儿处理」这类问题时，第一跳不是翻几百行目录树，而是查表定位到 SMF 行，拿到 `internal/context/`、`internal/pfcp/` 两个关键目录。这是典型的渐进式信息披露——只不过它用一张表完成了，而不是拆成多个文件。 顺带一提一个口径小疵：开头自称「十五个网元」，索引表只列了十四行。对人类读者无伤大雅，但对一个以精确立身的技能，这种数字口径的不一致恰是它自己反对的那类错误。 ### 第二层：网元解剖的四段式模板 每个网元按同一模板展开：路径 → 目录树（带行数与星标）→ 关键数据结构 → 主要功能。以 AMF 为例，目录树里 `context.go`（580 行）、`amf_ue.go`（1003 行）被标上⭐，`gmm/handler.go` 标到 2486 行，`ngap/handler_generated.go` 标到 12919 行——生成代码的体量单列出来，暗示「这部分别手改」。 再往下是实打实的 Go 结构体：`AMFContext` 里的 `UePool`、`RanUePool`、`AmfRanPool` 三池，对应 UE、RAN、关联三层上下文；AUSF 的 `AusfUeContext` 里 `Kausf`、`Kseaf`、`XresStar` 一字排开，密钥链路一目了然。**行数和字段名就是这件技能的硬通货**——模型拿到这些坐标，引用时可以精确到「`amf/internal/context/amf_ue.go` 的 `AmfUe` 结构体」，而不是含糊地说「AMF 模块里有个上下文类」。 ### 第三层：流程代码链——把信令流程翻译成文件路径 第三段是全技能对电信读者最友好的部分：三大流程的代码路径链。 - **UE 注册**：从 `ngap/handler.go` 的初始消息处理，到 NAS 分发，到 GMM 处理器，再到 AMF 向 UDM 取认证数据、AUSF 确认认证——五步，每步一个具体函数名。 - **PDU 会话建立**：从 AMF 的会话处理器，到 SMF 选择，到 SMF 侧处理，再到 PFCP 会话建立与 N4 隧道。 - **Xn 切换**：切换请求、目标侧确认、数据转发隧道、执行通知，四步全在 `ngap/handler.go` 与 `datapath.go` 之间穿行。 这层的本质是**把 TS 23.502 的流程图翻译成 Go 文件的调用链**。一个读过规范的工程师面对几十万行陌生代码，最缺的就是这条「从流程到文件」的桥。 ### 第四层：错题本——全技能最贵的一段 然后是整份 SKILL.md 的华彩段落，「常见错误纠正」。开头两条就够狠： > ❌ 错误的文件名：`amf_context.go` → ✅ 不存在，实际是 `context.go` > ❌ `amf_ue_context.go` → ✅ 不存在，实际是 `amf_ue.go` 这不是知识，是**判决书**——作者把大模型在这个仓库里最常编造的文件名逐条钉死。往下还有一段更彻底的组织方式澄清：nas、ngap、pfcp、openapi 这些公共库是独立的 Go Module 仓库，通过 go.mod 引用，「不存在 `lib/nas/`、`lib/ngap/` 等目录」。 为什么这一段最贵？因为代码分析类任务的头号翻车点，恰恰不是「不知道」，而是**自信地编造**：模型会按命名惯例脑补出一个 `amf_context.go`，读者一查没有，整篇文章的信用就塌了。白名单（哪些文件存在）靠目录树解决，黑名单（哪些「看起来该存在」的文件不存在）只能靠作者踩过坑后手写。这份错题本就是作者的踩坑记录直接资产化。 ### 第五层：强制要求——把「别瞎说」写成制度 错题本之后，技能进入「分析与撰写规范」，标题上挂着⚠️强制要求。核心条款四条：规范引用必须从 `references/` 目录取，禁止凭记忆引用规范编号；文件名必须先用工具验证存在；**「所有代码片段、函数签名、结构体定义必须与真实源码完全一致」「代码内容错误属于重大错误，会严重误导读者」**；成文必须挂 3GPP 规范号。 最见功力的是它的正反示例教学法。错误示例是一个编造的构造函数 `NewAMFContext(config)`——签名合理、风格地道，但真实源码里不存在。正确示例给出真身：`var amfContext AMFContext` 全局单例（第 25 行），`InitAmfContext` 初始化（第 110-157 行），`GetSelf` 取实例（第 558-560 行）。**行号都给出来了**。模型读完这一段，不仅知道「别编构造函数」，还拿到了「引用要带行号锚点」的格式范式——示范本身就是指令。 ## 三、可抄走的三条设计模式 **模式一：错题本优先于知识点。** 给 Agent 写领域技能时，先别急着堆「它是什么」，先列「它不是什么、哪些答案是错的」。负向清单对幻觉的压制力强于正向罗列，因为模型的错误恰恰集中在「按惯例脑补」的那一小块。一张 ❌/✅ 对照表，比十段描述性文字都管用。 **模式二：三重坐标锚定每个引用。** 这件技能里每个事实都尽量带三个坐标：文件路径（`NFs/amf/internal/context/context.go`）、行号（line 25、110-157）、规范号（TS 23.502、TS 29.518）。坐标越全，引用越可验证，模型自由发挥的空间越小。写任何知识型技能，都该问自己：我的每条知识能不能被读者拿坐标去查证？ **模式三：资源自包含。** 技能的规范映射能力不靠模型记忆，靠随件附带的 `references/` 目录——一份 3000 多条、覆盖 13 个系列规范的 Excel 全表，加一份供快速查询的 JSON 映射。原文自称「自包含设计：可独立移植使用」。这解决的是知识件的老大难：上游数据更新了，技能却把旧答案焊死在正文里。把易变数据外置成数据文件，正文只留查表方法，件就活得久。 配套的还有四条「查找配方」——找网元实现看 `internal/context/`，找协议处理看 `internal/ngap/handler.go` 或 `internal/pfcp/handler/handler.go`，找 SBI 接口分 consumer 与 processor 两侧，找上下文管理认准 `context.go` 与 `*_ue.go` 的命名法。这是把作者个人的代码直觉，改写成模型可执行的检索策略。 ## 四、三处暗伤 **暗伤一：作者机器的路径烙印。** 技能正文多处出现 `D:\500年仓库\free5gc-source` 这样的 Windows 盘符路径。源码本体不在技能包里，到了别的机器这些路径就是死链。所幸 GitHub 仓库地址和 `references/` 自包含设计兜住了底，但「知识件要不要绑定作者本地环境」这道题，它没答干净。 **暗伤二：快照衰减。** 正文自己承认「基于2026年3月21日的源码分析，实际代码可能有变化」。目录树里那些行数——PCF 的 `smpolicy.go` 标到 49841 行、`policyauthorization.go` 标到 68837 行，NEF 的 `pfd.go` 标到 27070 行——全是快照值，上游每合一个 PR 就锈一点。行号锚点是它最大的精度优势，也是它最脆的保质期短板。这类件需要一条成文的「再校准」流程，目前只有一句免责声明。 **暗伤三：上下文成本。** 全部知识一次塞进正文：十四个网元的目录树、十几个 Go 结构体、三大流程、规范映射表、写作规范。触发任何一条查询，这份全文都会整块进入上下文。官方文档件普遍把细节拆进附属文件按需加载，这件没有做渐进披露——在它当前体量下尚可忍受，再长一倍就该拆了。 ## 五、它的工作流 把技能被触发后的完整链路画出来，是一条「查表—下钻—验证—锚定」的流水线： ```mermaid flowchart TD Q["提问：某功能在哪实现"] --> H["命中 free5gc 技能"] H --> I["查快速索引表"] I --> N["定位网元章节"] N --> R["选一条查找配方"] R --> F["按配方定位文件"] F --> V{"Read 验证存在"} V -->|存在| A["摘代码并对错题本自查"] V -->|不存在| B["换另一条配方"] B --> F A --> C["引用三重坐标"] C --> O["成文并挂规范号"] ``` 关键分岔在「Read 验证存在」这一步：验证不过就回炉换配方，而不是硬着头皮引用。这条边就是整件技能的灵魂。 ## 六、安装与使用 ```bash # 手动安装到个人技能目录 mkdir -p ~/.claude/skills/free5gc/references # 将 SKILL.md 放入 free5gc/ 目录， # specs_mapping.json 与规范全表放入 references/ ``` ```text # 使用：对话里直接问，触发词就是任务本身 「free5GC 里 PDU 会话创建在 SMF 哪个文件处理？给出路径」 「对照错题本检查：这篇分析里提到的文件名是否都真实存在」 「UE 注册流程涉及的函数链，按调用顺序列出并挂规范号」 ``` 注意它的边界：这是一件**代码阅读件**，不是部署件。想用 Agent 拉起一套核心网跑信令测试，它帮不上忙；想读懂核心网代码、写规范对照的分析文章、给新同事准备导读，它就是趁手的地图。 ## 七、适合谁 - **读 free5GC 源码的工程师**：省掉最贵的「从哪个文件开始读」的冷启动，三大流程链直接当导读用。 - **写协议分析文章的作者**：强制规范号引用加三重坐标，成文的可验证性直接上一个档次。 - **想写知识型 Skill 的开发者**：错题本、三重坐标、自包含三个模式，任何领域都能平移——把它换成你们公司的私有仓库，就是一件合格的「代码地图件」。 - **不适合谁**：想找开箱即用 5G 实验室的运维向读者；以及期望它替代读代码的人——它给坐标，不给结论，结论仍要人自己去文件里读。 ## 结语 Skills 生态里，大家热衷于比谁的件更能干：会做 PPT、会剪视频、会上线收钱。这件 `free5gc` 提醒了一件事：还有一类技能的价值恰恰相反——**不生产新能力，只约束旧毛病**。它用一张错题本压住编造，用三重坐标锁死引用，用外置数据对抗过期，把「准确性」这件最不性感的事做成了制度。下次写 SKILL.md，不妨先翻翻自己领域里那些「模型最爱编错」的东西——那里往往藏着整份文件最值钱的几行。 ## 参考来源 1. [free5gc/free5gc — GitHub](https://github.com/free5gc/free5gc) — 技能所解剖的开源 5G 核心网上游仓库，文中目录结构与仓库地址均出自该技能对源码的勘定 2. [3GPP 官网](https://www.3gpp.org) — 技能内规范映射表（TS 23.5xx/24.5xx/29.5xx/33.501/38.4xx）的数据来源 3. [skillsmp.com — Skills 聚合市场](https://skillsmp.com) — Skills 生态可搜索目录，本文关于知识型技能生态位判断的横向参照 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。