概念地图
Weftale 的扩展体系建立在一组判据上，而不是建立在命名习惯上。一个单元叫「插件」还是「数据包」，不由作者自报决定，而由它是否含可执行代码、是否产生写边、作用在内容还是表现决定。判据确定之后，架构才有意义；架构确定之后，具体接口与包格式才有落点。
本页给出一张阅读地图：先看判据，再看架构，最后看实现。每一节都指向对应的概念页。
一条主线：判据 → 架构 → 实现
| 顺序 | 要回答的问题 | 对应页面 | 读完之后 |
|---|---|---|---|
| 1. 判据 | 这个单元属于哪一档？ | 四档扩展模型 | 能独立判断一个扩展单元的档位 |
| 2. 架构 | 它能改什么、挂在哪里？ | policy 与写边、插槽与实现位 | 能判断它是否被允许，以及卸载后发生什么 |
| 3. 实现 | 它如何打包、声明、被读取？ | 分发包与包结构、包清单 | 能写出一个可装载的包 |
| 4. 运行 | 装载时谁在检查？ | 装载管线与 guard | 能把拒绝码对应到具体规则 |
这条顺序不能倒过来。如果先看接口再决定档位，就会把「我用了哪个 API」误当成「我属于哪一档」；框架只承认清单里的声明与内容事实，不承认作者对档位的自我描述。
三问判据
| 顺序 | 问题 | 回答「否」 | 回答「是」 |
|---|---|---|---|
| 第一问 | 是否含可执行代码？ | 进入第三问 | 进入第二问 |
| 第二问 | 是否产生写边？ | 插件 | Mod；能否落地由 policy 决定，closed 直接拒绝 |
| 第三问 | 作用面是内容还是表现？ | 内容 → 数据包 | 表现 → 资源包 |
三个问题之外还有一条边界：数据包与资源包不含代码，所以在第二问之前就已经分流，原理上不可能成为插件或 Mod。它们可以覆盖既有内容或资产，但这不叫写边。
四档速览
| 档位 | 是否含代码 | 作用面 | 典型落点 |
|---|---|---|---|
| 数据包 | 否 | registry 条目 | data/ 下的条目文件 |
| 资源包 | 否 | 资产路径 | assets/ 下的虚拟路径覆盖 |
| 插件 | 是 | 新增能力节点 | 实现位登记 |
| Mod | 是 | 既有能力节点 | 机制插槽、intercept、isolate 域内 provide |
每个概念页回答什么
| 页面 | 回答的问题 | 关键产出 |
|---|---|---|
| 四档扩展模型 | 一个单元属于哪一档？删除测试如何区分内容与表现？ | 档位判定与边界案例 |
| policy 与写边 | 它被允许写什么？失败时保留什么？卸载后如何恢复？ | 准入结果与撤销方式 |
| 插槽与实现位 | 它挂在哪里？通知、改写、注册三种落点有什么差别？ | 扩展点选择 |
| 信任与签名 | 谁签的？未签名或发布者冲突时怎么办？ | 信任判定与用户裁决 |
| 翻译层 | 外部输入如何变成框架可消费的数据？ | 规则、翻译器与产物的分工 |
| 剧本 IR | 内容以什么形状被保存与执行？ | 节点图与指令流 |
| 分发包与包结构 | 一个可装载的包长什么样？ | pack.json、目录布局与签名 |
概念之间如何咬合
判据决定档位，policy 决定准入。 一个单元有写边，它就是 Mod；但写边能不能落地，要看被写目标声明的 policy。closed 直接拒绝，public 放行，trusted 需要更高信任。policy 不参与「是什么」的判断。
插槽是写边的入口，实现位是新增实现的入口。 改写型插槽只对 Mod 开放；实现位只对 Plugin 开放。把「换一个实现」做成「注册一个新条目并切换选择」，就仍然是 Plugin；直接替换正在使用的 provider，就变成 Mod。
包结构承载以上全部声明。 pack.json 记录档位、依赖、能力、写边与登记项；装载器据此计算档位、裁剪上下文、登记写边并做装载后核验。包结构不是附属格式，它就是契约本身。
建议的阅读路径
text
第一次接触
/concepts/four-tiers
-> /concepts/policy-and-writes
-> /concepts/slots
-> /concepts/packaging
要写一个扩展包
/concepts/packaging
-> /reference/manifest
-> /architecture/loader-guard
-> /reference/error-codes
要读或改框架代码
/architecture/
-> /architecture/large-plugins
-> /architecture/rpm
-> /plugins/kernel
关心输入源与翻译
/concepts/translation
-> /concepts/ir
-> /plugins/translate
-> /concepts/trust常见误解
常见误解
- 「我的包叫 plugin，所以它是插件。」 档位由内容与写边声明计算；自报
kind与计算结果不符会被拒绝。 - 「我先选好接口，再决定做哪一档。」 接口是档位的结果，不是档位的原因。先做删除测试与写边判断，再选落点。
- 「数据包覆盖了别人写的内容，所以它产生了写边。」 写边只描述代码对既有节点可观测行为的改变；无代码单元的覆盖不构成写边。
- 「policy 可以决定一个单元是不是 Mod。」 policy 只决定「能不能写」，档位由写边决定。
下一步
- 想先建立分类直觉：读四档扩展模型。
- 想知道一个包如何被拒绝或放行：读policy 与写边。
- 想直接动手打包：读分发包与包结构与包清单。