0.1 它是什么在开始之前你需要明白NorpAgent 远远不止是一个智能体框架。智能体框架通常会替你决定“Agent 应该长什么样”——它规定模型怎么调用、工具怎么注册、记忆怎么存储、循环怎么运转。你用它的“配方”来构建应用。而 NorpAgent 是一个“元框架”Meta-Framework。这意味着它不做任何决定它只给你一套最底层的组装规则让你自己定义“什么是 Agent”——甚至让你定义“要不要 Agent”。智能体框架提供的是“框架”你选择配置框架里给定好的东西。元框架提供的是“零件生产 装配说明书”你可以造属于自己的成品也可以造零件或者造一个全新的发明。用法是无限的因为框架本身不预设任何“用法边界”——你能定义的新组件种类、新执行结构、新干预方式只受你想象力的限制。所以这套教程不是“教你用 NorpAgent 完成 X 任务”的固定教程集而是“教你拆解和重组这套元框架的机制手册”。重点不在于你可以用它干什么而是你要如何通过它的四个核心机制把自己的任意代码“接”进去。0.2 元框架的四个核心机制如何使用 NorpAgent 的底层语法首先要学会怎么用。pipinstallnorpagent这样子就完成了最小安装。你也可以选择安装扩展包# # 可选扩展按需安装# # OpenAI 兼容模型DeepSeek / OpenAI / Qwen / vLLM / Ollama 等pipinstallnorpagent[openai]# Anthropic Claude 模型pipinstallnorpagent[anthropic]# 联网检索工具web_search / web_fetch含 requests beautifulsoup4pipinstallnorpagent[web]# Ed25519 插件签名验签生产环境安全分发插件pipinstallnorpagent[security]# # 组合安装示例同时装多个# # 同时装 OpenAI 联网pipinstallnorpagent[openai,web]# 同时装 OpenAI Claude 联网 签名pipinstallnorpagent[openai,anthropic,web,security]# # 全部扩展开发/学习环境一键装全# pipinstallnorpagent[all]要理解“怎么用”一个元框架你需要先理解它的底层语法——“装配语法”。NorpAgent 的“装配语法”由以下四样东西定义① 地址函数Address Function——“怎么找到你的代码”元框架不替你import任何模块它提供一个统一的地址解析器# 你把代码放在任意位置用地址字符串告诉框架怎么找到它npa(modelmyapp.models.http_json:create)# 模块:属性npa(tools{weather:myapp.weather:WeatherTool})# 属性指向类/工厂npa(frontend/path/to/my.html)# 文件路径直接挂载需要预先注册否则抛出错误规则只有一条任何形如pkg.mod:attr的字符串都会被动态加载并实例化按工厂签名注入上下文。这个机制让你可以在不修改框架核心的前提下接入任意位置的任意代码。② 槽位表Slot Table——“有哪些插口插口怎么工作”元框架不预设“应用有哪些零件”它只维护一张可热插拔的槽位表SLOT_SPECS。默认有 18 个内置槽位如model、tools但你随时可以添加新槽位fromnorpagent.archimportSlotSpec,register_slot register_slot(SlotSpec(namevector_store,# 新插口名即 npa() 的新关键字参数string_semanticsliteral,# 值怎么解释applierapply_vector_store,# 值非空时执行什么动作remount_rebuild_agentTrue,# 热替换后是否重建核心))# 现在你可以这样用了npa(vector_storeMyVectorStore())槽位就是元框架暴露给你的“装配接口”。你通过register_slot定义新接口通过npa(slotvalue)填值通过applier定义值被填入后发生的动作。整个流程完全由你定制。③ 注册表命名空间Registry Namespace——“组件存到哪里怎么查找”元框架不替你管理对象生命周期它只提供一个多层命名空间容器Registry。你决定把组件注册到哪个命名空间框架只负责按名字查找和构建# 9 大专用命名空间 无限开放的通用命名空间reg.register_model(my_model,provider)# 模型空间reg.register_tool(weather,tool)# 工具空间reg.register_component(vector_store,pg,factory)# 通用空间种类无限这里的要点是注册表不是“框架规定好的目录”而是你可以随时热添加新种类kind的开放容器。你需要什么能力就热注册什么种类然后通过ctx.component(种类名)在任意工具或钩子里取用不需要重启。④ 钩子与执行结构覆写Hook Override——“定义节点而非使用节点”元框架不替你决定执行流程它把 Agent 循环切成9 层 29 个内置节点——这些是预置的但不是全部。真正的元能力在于你可以定义新的节点类型而不仅仅是使用现有的。元框架提供两层的控制权第一层干预已有的执行节点订阅与覆写# 方式一订阅现有钩子不侵入代码在节点上挂回调npa(hooks{before_tool_call:my_approval_handler})# 方式二覆写整个执行结构替换节点的实现逻辑classMyRuntime(AgentRuntime):defcall_model(self,...):# 完全接管模型调用逻辑returnmy_call()npa(agent_runtimeMyRuntime)第二层定义全新的执行节点开新层 自定义钩子这是元框架与普通框架的根本区别——你不是被限定在固定的 29 个钩子里而是可以随时扩展节点类型fromnorpagent.hooksimportHookLayer# 开一个新层order 决定它插在现有 9 层的哪个位置network_layerHookLayer(network_control,order15)before_httpnetwork_layer.hook(before_http_request,mutatingTrue)# 安装到引擎上engine.hooks.install_layer(network_layer)# 现在你有第 30 个钩子了——且这个钩子与其他 29 个完全同权engine.hooks.before_http_request.subscribe(log_request)你是流程的设计者也是节点类型的设计者。框架只做两件事保证“节点”这个抽象存在钩子系统本身是可扩展的容器保证“执行结构”可以被替换AgentRuntime的 7 个核心方法是开放给覆写的。至于节点叫什么、有多少个、在流程的什么位置触发——全由你决定。这是元框架的元能力世界由你定义。对不起我理解错了——你是说引言本身看的人就多所以引言里不能有错得修正。而我刚才只给了改动的两节但用户没法直接把那两节“粘回去”。你需要的是完整的、修正后的引言全文。我把 0.3 和 0.5 两节修正后重新输出完整版本。其他章节不动。以下是修正后的完整引言0.1 它是什么在开始之前你需要明白NorpAgent 远远不止是一个智能体框架。智能体框架通常会替你决定“Agent 应该长什么样”——它规定模型怎么调用、工具怎么注册、记忆怎么存储、循环怎么运转。你用它的“配方”来构建应用。而 NorpAgent 是一个“元框架”Meta-Framework。这意味着它不做任何决定它只给你一套最底层的组装规则让你自己定义“什么是 Agent”——甚至让你定义“要不要 Agent”。智能体框架提供的是“框架”你选择配置框架里给定好的东西。元框架提供的是“零件生产 装配说明书”你可以造属于自己的成品也可以造零件或者造一个全新的发明。用法是无限的因为框架本身不预设任何“用法边界”——你能定义的新组件种类、新执行结构、新干预方式只受你想象力的限制。所以这套教程不是“教你用 NorpAgent 完成 X 任务”的固定教程集而是“教你拆解和重组这套元框架的机制手册”。重点不在于你可以用它干什么而是你要如何通过它的四个核心机制把自己的任意代码“接”进去。0.2 元框架的四个核心机制如何使用 NorpAgent 的底层语法首先要学会怎么用。pipinstallnorpagent这样子就完成了最小安装。你也可以选择安装扩展包# # 可选扩展按需安装# # OpenAI 兼容模型DeepSeek / OpenAI / Qwen / vLLM / Ollama 等pipinstallnorpagent[openai]# Anthropic Claude 模型pipinstallnorpagent[anthropic]# 联网检索工具web_search / web_fetch含 requests beautifulsoup4pipinstallnorpagent[web]# Ed25519 插件签名验签生产环境安全分发插件pipinstallnorpagent[security]# # 组合安装示例同时装多个# # 同时装 OpenAI 联网pipinstallnorpagent[openai,web]# 同时装 OpenAI Claude 联网 签名pipinstallnorpagent[openai,anthropic,web,security]# # 全部扩展开发/学习环境一键装全# pipinstallnorpagent[all]要理解“怎么用”一个元框架你需要先理解它的底层语法——“装配语法”。NorpAgent 的“装配语法”由以下四样东西定义① 地址函数Address Function——“怎么找到你的代码”元框架不替你import任何模块它提供一个统一的地址解析器# 你把代码放在任意位置用地址字符串告诉框架怎么找到它npa(modelmyapp.models.http_json:create)# 模块:属性npa(tools{weather:myapp.weather:WeatherTool})# 属性指向类/工厂npa(frontend/path/to/my.html)# 文件路径直接挂载需要预先注册否则抛出错误规则只有一条任何形如pkg.mod:attr的字符串都会被动态加载并实例化按工厂签名注入上下文。这个机制让你可以在不修改框架核心的前提下接入任意位置的任意代码。② 槽位表Slot Table——“有哪些插口插口怎么工作”元框架不预设“应用有哪些零件”它只维护一张可热插拔的槽位表SLOT_SPECS。默认有 18 个内置槽位如model、tools但你随时可以添加新槽位fromnorpagent.archimportSlotSpec,register_slot register_slot(SlotSpec(namevector_store,# 新插口名即 npa() 的新关键字参数string_semanticsliteral,# 值怎么解释applierapply_vector_store,# 值非空时执行什么动作remount_rebuild_agentTrue,# 热替换后是否重建核心))# 现在你可以这样用了npa(vector_storeMyVectorStore())槽位就是元框架暴露给你的“装配接口”。你通过register_slot定义新接口通过npa(slotvalue)填值通过applier定义值被填入后发生的动作。整个流程完全由你定制。③ 注册表命名空间Registry Namespace——“组件存到哪里怎么查找”元框架不替你管理对象生命周期它只提供一个多层命名空间容器Registry。你决定把组件注册到哪个命名空间框架只负责按名字查找和构建# 9 大专用命名空间 无限开放的通用命名空间reg.register_model(my_model,provider)# 模型空间reg.register_tool(weather,tool)# 工具空间reg.register_component(vector_store,pg,factory)# 通用空间种类无限这里的要点是注册表不是“框架规定好的目录”而是你可以随时热添加新种类kind的开放容器。你需要什么能力就热注册什么种类然后通过ctx.component(种类名)在任意工具或钩子里取用不需要重启。④ 钩子与执行结构覆写Hook Override——“定义节点而非使用节点”元框架不替你决定执行流程它把 Agent 循环切成9 层 29 个内置节点——这些是预置的但不是全部。真正的元能力在于你可以定义新的节点类型而不仅仅是使用现有的。元框架提供两层的控制权第一层干预已有的执行节点订阅与覆写# 方式一订阅现有钩子不侵入代码在节点上挂回调npa(hooks{before_tool_call:my_approval_handler})# 方式二覆写整个执行结构替换节点的实现逻辑classMyRuntime(AgentRuntime):defcall_model(self,...):# 完全接管模型调用逻辑returnmy_call()npa(agent_runtimeMyRuntime)第二层定义全新的执行节点开新层 自定义钩子这是元框架与普通框架的根本区别——你不是被限定在固定的 29 个钩子里而是可以随时扩展节点类型fromnorpagent.hooksimportHookLayer# 开一个新层order 决定它插在现有 9 层的哪个位置network_layerHookLayer(network_control,order15)before_httpnetwork_layer.hook(before_http_request,mutatingTrue)# 安装到引擎上engine.hooks.install_layer(network_layer)# 现在你有第 30 个钩子了——且这个钩子与其他 29 个完全同权engine.hooks.before_http_request.subscribe(log_request)你是流程的设计者也是节点类型的设计者。框架只做两件事保证“节点”这个抽象存在钩子系统本身是可扩展的容器保证“执行结构”可以被替换AgentRuntime的 7 个核心方法是开放给覆写的。至于节点叫什么、有多少个、在流程的什么位置触发——全由你决定。这是元框架的元能力世界由你定义。0.3 使用元框架的正确姿势“无限用法”的方法论因为用法是无限的所以这套教程不会教你“用 NorpAgent 实现 RAG”或“用 NorpAgent 做多智能体”。那些只是具体应用不是元框架的使用方法。我们会教你的是“元操作”——组装元框架的四种基本姿势元操作对应的框架机制章节“我怎么把实现挂到框架的命名空间里”注册表操作Registry APIs第 2 篇“我怎么定义一个全新的可填参数”槽位注册Slot Registration第 3 篇“我怎么让框架找到我的代码”地址解析Address Resolution第 4 篇“我怎么在流程中插入自定义逻辑”钩子订阅与方法覆写Hooks Overrides第 5 篇掌握了这四种元操作你就掌握了 NorpAgent 的全部用法。剩下的——不管你要做单 Agent、多 Agent、嵌入式服务、桌面应用、命令行工具——都只是这四种操作的排列组合。0.4 为什么“用法无限”反而需要教程元框架有一个天然的门槛它不说“你可以这样做”它只提供“你可以这样接”。很多人在看完开发手册后仍然会问同一个问题“我知道可以注册槽位、可以写钩子、可以换模型……但我到底应该注册什么写什么钩子换什么模型”这个问题没有标准答案——因为元框架不替你决策。这套教程的作用就是通过具体案例把“接”的过程完整演示一遍让你看清每种元操作在实际代码中长什么样。至于你要接什么那是你的事。我们的目标是读完每一篇你都能亲手完成一次“接”的动作——无论接的是工具、模型、前端、循环还是自定义槽位。0.5 系列教程结构篇目元操作主题对应手册章节第 1 篇快速启动看懂npa()的三层含义第 1、6 章第 2 篇注册表操作9 大命名空间与组件注册第 26 章第 3 篇槽位注册自定义槽位的完整契约第 3.8、25.10 章第 4 篇地址解析字符串地址的四种语义、;keyvalue子句第 3 章第 5 篇工具开发Tool协议、RunContext、取消协作第 7、25.2 章第 6 篇模型接入ModelProvider协议、凭据回落、流式第 7、25.3 章第 7 篇预设模式六种内置预设与自定义 Preset第 12 章第 8 篇救援模式三层故障模型、快照回退、手动工具接管第 15、24 章第 9 篇热重载remount底层链路与 dict 值地址解析红线第 3.7、25.2.6、25.10.5 章第 10 篇会话与记忆SessionManager协议、跨轮续聊第 8、25.4 章第 11 篇沙箱与调度器隔离执行与任务编排第 8、25.5、25.6 章第 12 篇前端与渲染器两层结构、自定义前端第 5、25.7 章第 13 篇钩子29 个内置钩子 自定义钩子层第 9、25.8 章第 14 篇安全系统safe()三档级别、审批与网络策略第 10 章第 15 篇插件开发单文件插件、manifest 包、安全管线第 11、25.11 章第 16 篇通用组件开发register_component与开放命名空间第 2.6.3、25.9 章第 17 篇嵌入式部署install_core()与embedded预设第 14.2 章第 18 篇深入自研循环EventLoop内部机制与压测第 4、24.2、25.1.2 章第 19 篇实践盘点从零到一的完整工程示例第 16、17、25.12 章每一篇的结尾都会给出“你可能可以用这个机制做什么”的开放列表但不会限定你必须做什么。世界的定义权属于你。0.6 谁适合读这个教程致那些不想被定义的开发者。你已经厌倦了“框架教你做人”的叙事——它规定你继承什么类、调用什么 API、遵循什么设计模式。你写代码不是去“适应”一个框架而是让框架“适应”你的问题。NorpAgent 是元框架。它不定义“什么是 Agent”不替你预设执行流程不告诉你“应该用什么模型”或“工具应该怎么组织”。它只提供四样最底层的东西一个地址解析器、一张可热插拔的槽位表、一个开放命名空间的注册表、一个可扩展的钩子系统。这四样东西加起来就是一个“你可以自己画地图”的工具包。所以这个教程不适合以下人群想找一个“开箱即用”的 Agent 产品的人希望框架替你做 80% 决策的人不想理解“地址”、“槽位”、“注册表”这三个概念就想开始写代码的人。它适合的是你不想被“智能体框架”框住想自己定义 Agent 的行为边界你读完了 LangChain 的文档但觉得它们“替你做了太多决定”你是一个库的作者想用 NorpAgent 作底层调度底座在上面搭建自己的 DSL你想理解“热重载、取消传播、跨线程唤醒”这些底层机制如何落地到生产环境。你不一定需要懂得异步编程——框架的事件循环已经替你封装好了。你只需要理解“槽位”、“地址”、“注册表”这三个概念就足以开始。剩下的是你自己画地图的自由。0.7 开始之前请你记住三句话NorpAgent 不定义“Agent 是什么”它只定义“如何把东西接上去”——接什么由你定。宇宙是什么样子你说了算。四个核心机制地址 / 槽位 / 注册表 / 钩子是元框架的“装配语法”掌握了它们你就掌握了无限用法。每一篇教程都在演示一种“接法”不演示“用例”。准备好了吗我们来看看如何“组装”一个新东西吧。 零：NorpAgent 元框架开发系列教程引言
0.1 它是什么在开始之前你需要明白NorpAgent 远远不止是一个智能体框架。智能体框架通常会替你决定“Agent 应该长什么样”——它规定模型怎么调用、工具怎么注册、记忆怎么存储、循环怎么运转。你用它的“配方”来构建应用。而 NorpAgent 是一个“元框架”Meta-Framework。这意味着它不做任何决定它只给你一套最底层的组装规则让你自己定义“什么是 Agent”——甚至让你定义“要不要 Agent”。智能体框架提供的是“框架”你选择配置框架里给定好的东西。元框架提供的是“零件生产 装配说明书”你可以造属于自己的成品也可以造零件或者造一个全新的发明。用法是无限的因为框架本身不预设任何“用法边界”——你能定义的新组件种类、新执行结构、新干预方式只受你想象力的限制。所以这套教程不是“教你用 NorpAgent 完成 X 任务”的固定教程集而是“教你拆解和重组这套元框架的机制手册”。重点不在于你可以用它干什么而是你要如何通过它的四个核心机制把自己的任意代码“接”进去。0.2 元框架的四个核心机制如何使用 NorpAgent 的底层语法首先要学会怎么用。pipinstallnorpagent这样子就完成了最小安装。你也可以选择安装扩展包# # 可选扩展按需安装# # OpenAI 兼容模型DeepSeek / OpenAI / Qwen / vLLM / Ollama 等pipinstallnorpagent[openai]# Anthropic Claude 模型pipinstallnorpagent[anthropic]# 联网检索工具web_search / web_fetch含 requests beautifulsoup4pipinstallnorpagent[web]# Ed25519 插件签名验签生产环境安全分发插件pipinstallnorpagent[security]# # 组合安装示例同时装多个# # 同时装 OpenAI 联网pipinstallnorpagent[openai,web]# 同时装 OpenAI Claude 联网 签名pipinstallnorpagent[openai,anthropic,web,security]# # 全部扩展开发/学习环境一键装全# pipinstallnorpagent[all]要理解“怎么用”一个元框架你需要先理解它的底层语法——“装配语法”。NorpAgent 的“装配语法”由以下四样东西定义① 地址函数Address Function——“怎么找到你的代码”元框架不替你import任何模块它提供一个统一的地址解析器# 你把代码放在任意位置用地址字符串告诉框架怎么找到它npa(modelmyapp.models.http_json:create)# 模块:属性npa(tools{weather:myapp.weather:WeatherTool})# 属性指向类/工厂npa(frontend/path/to/my.html)# 文件路径直接挂载需要预先注册否则抛出错误规则只有一条任何形如pkg.mod:attr的字符串都会被动态加载并实例化按工厂签名注入上下文。这个机制让你可以在不修改框架核心的前提下接入任意位置的任意代码。② 槽位表Slot Table——“有哪些插口插口怎么工作”元框架不预设“应用有哪些零件”它只维护一张可热插拔的槽位表SLOT_SPECS。默认有 18 个内置槽位如model、tools但你随时可以添加新槽位fromnorpagent.archimportSlotSpec,register_slot register_slot(SlotSpec(namevector_store,# 新插口名即 npa() 的新关键字参数string_semanticsliteral,# 值怎么解释applierapply_vector_store,# 值非空时执行什么动作remount_rebuild_agentTrue,# 热替换后是否重建核心))# 现在你可以这样用了npa(vector_storeMyVectorStore())槽位就是元框架暴露给你的“装配接口”。你通过register_slot定义新接口通过npa(slotvalue)填值通过applier定义值被填入后发生的动作。整个流程完全由你定制。③ 注册表命名空间Registry Namespace——“组件存到哪里怎么查找”元框架不替你管理对象生命周期它只提供一个多层命名空间容器Registry。你决定把组件注册到哪个命名空间框架只负责按名字查找和构建# 9 大专用命名空间 无限开放的通用命名空间reg.register_model(my_model,provider)# 模型空间reg.register_tool(weather,tool)# 工具空间reg.register_component(vector_store,pg,factory)# 通用空间种类无限这里的要点是注册表不是“框架规定好的目录”而是你可以随时热添加新种类kind的开放容器。你需要什么能力就热注册什么种类然后通过ctx.component(种类名)在任意工具或钩子里取用不需要重启。④ 钩子与执行结构覆写Hook Override——“定义节点而非使用节点”元框架不替你决定执行流程它把 Agent 循环切成9 层 29 个内置节点——这些是预置的但不是全部。真正的元能力在于你可以定义新的节点类型而不仅仅是使用现有的。元框架提供两层的控制权第一层干预已有的执行节点订阅与覆写# 方式一订阅现有钩子不侵入代码在节点上挂回调npa(hooks{before_tool_call:my_approval_handler})# 方式二覆写整个执行结构替换节点的实现逻辑classMyRuntime(AgentRuntime):defcall_model(self,...):# 完全接管模型调用逻辑returnmy_call()npa(agent_runtimeMyRuntime)第二层定义全新的执行节点开新层 自定义钩子这是元框架与普通框架的根本区别——你不是被限定在固定的 29 个钩子里而是可以随时扩展节点类型fromnorpagent.hooksimportHookLayer# 开一个新层order 决定它插在现有 9 层的哪个位置network_layerHookLayer(network_control,order15)before_httpnetwork_layer.hook(before_http_request,mutatingTrue)# 安装到引擎上engine.hooks.install_layer(network_layer)# 现在你有第 30 个钩子了——且这个钩子与其他 29 个完全同权engine.hooks.before_http_request.subscribe(log_request)你是流程的设计者也是节点类型的设计者。框架只做两件事保证“节点”这个抽象存在钩子系统本身是可扩展的容器保证“执行结构”可以被替换AgentRuntime的 7 个核心方法是开放给覆写的。至于节点叫什么、有多少个、在流程的什么位置触发——全由你决定。这是元框架的元能力世界由你定义。对不起我理解错了——你是说引言本身看的人就多所以引言里不能有错得修正。而我刚才只给了改动的两节但用户没法直接把那两节“粘回去”。你需要的是完整的、修正后的引言全文。我把 0.3 和 0.5 两节修正后重新输出完整版本。其他章节不动。以下是修正后的完整引言0.1 它是什么在开始之前你需要明白NorpAgent 远远不止是一个智能体框架。智能体框架通常会替你决定“Agent 应该长什么样”——它规定模型怎么调用、工具怎么注册、记忆怎么存储、循环怎么运转。你用它的“配方”来构建应用。而 NorpAgent 是一个“元框架”Meta-Framework。这意味着它不做任何决定它只给你一套最底层的组装规则让你自己定义“什么是 Agent”——甚至让你定义“要不要 Agent”。智能体框架提供的是“框架”你选择配置框架里给定好的东西。元框架提供的是“零件生产 装配说明书”你可以造属于自己的成品也可以造零件或者造一个全新的发明。用法是无限的因为框架本身不预设任何“用法边界”——你能定义的新组件种类、新执行结构、新干预方式只受你想象力的限制。所以这套教程不是“教你用 NorpAgent 完成 X 任务”的固定教程集而是“教你拆解和重组这套元框架的机制手册”。重点不在于你可以用它干什么而是你要如何通过它的四个核心机制把自己的任意代码“接”进去。0.2 元框架的四个核心机制如何使用 NorpAgent 的底层语法首先要学会怎么用。pipinstallnorpagent这样子就完成了最小安装。你也可以选择安装扩展包# # 可选扩展按需安装# # OpenAI 兼容模型DeepSeek / OpenAI / Qwen / vLLM / Ollama 等pipinstallnorpagent[openai]# Anthropic Claude 模型pipinstallnorpagent[anthropic]# 联网检索工具web_search / web_fetch含 requests beautifulsoup4pipinstallnorpagent[web]# Ed25519 插件签名验签生产环境安全分发插件pipinstallnorpagent[security]# # 组合安装示例同时装多个# # 同时装 OpenAI 联网pipinstallnorpagent[openai,web]# 同时装 OpenAI Claude 联网 签名pipinstallnorpagent[openai,anthropic,web,security]# # 全部扩展开发/学习环境一键装全# pipinstallnorpagent[all]要理解“怎么用”一个元框架你需要先理解它的底层语法——“装配语法”。NorpAgent 的“装配语法”由以下四样东西定义① 地址函数Address Function——“怎么找到你的代码”元框架不替你import任何模块它提供一个统一的地址解析器# 你把代码放在任意位置用地址字符串告诉框架怎么找到它npa(modelmyapp.models.http_json:create)# 模块:属性npa(tools{weather:myapp.weather:WeatherTool})# 属性指向类/工厂npa(frontend/path/to/my.html)# 文件路径直接挂载需要预先注册否则抛出错误规则只有一条任何形如pkg.mod:attr的字符串都会被动态加载并实例化按工厂签名注入上下文。这个机制让你可以在不修改框架核心的前提下接入任意位置的任意代码。② 槽位表Slot Table——“有哪些插口插口怎么工作”元框架不预设“应用有哪些零件”它只维护一张可热插拔的槽位表SLOT_SPECS。默认有 18 个内置槽位如model、tools但你随时可以添加新槽位fromnorpagent.archimportSlotSpec,register_slot register_slot(SlotSpec(namevector_store,# 新插口名即 npa() 的新关键字参数string_semanticsliteral,# 值怎么解释applierapply_vector_store,# 值非空时执行什么动作remount_rebuild_agentTrue,# 热替换后是否重建核心))# 现在你可以这样用了npa(vector_storeMyVectorStore())槽位就是元框架暴露给你的“装配接口”。你通过register_slot定义新接口通过npa(slotvalue)填值通过applier定义值被填入后发生的动作。整个流程完全由你定制。③ 注册表命名空间Registry Namespace——“组件存到哪里怎么查找”元框架不替你管理对象生命周期它只提供一个多层命名空间容器Registry。你决定把组件注册到哪个命名空间框架只负责按名字查找和构建# 9 大专用命名空间 无限开放的通用命名空间reg.register_model(my_model,provider)# 模型空间reg.register_tool(weather,tool)# 工具空间reg.register_component(vector_store,pg,factory)# 通用空间种类无限这里的要点是注册表不是“框架规定好的目录”而是你可以随时热添加新种类kind的开放容器。你需要什么能力就热注册什么种类然后通过ctx.component(种类名)在任意工具或钩子里取用不需要重启。④ 钩子与执行结构覆写Hook Override——“定义节点而非使用节点”元框架不替你决定执行流程它把 Agent 循环切成9 层 29 个内置节点——这些是预置的但不是全部。真正的元能力在于你可以定义新的节点类型而不仅仅是使用现有的。元框架提供两层的控制权第一层干预已有的执行节点订阅与覆写# 方式一订阅现有钩子不侵入代码在节点上挂回调npa(hooks{before_tool_call:my_approval_handler})# 方式二覆写整个执行结构替换节点的实现逻辑classMyRuntime(AgentRuntime):defcall_model(self,...):# 完全接管模型调用逻辑returnmy_call()npa(agent_runtimeMyRuntime)第二层定义全新的执行节点开新层 自定义钩子这是元框架与普通框架的根本区别——你不是被限定在固定的 29 个钩子里而是可以随时扩展节点类型fromnorpagent.hooksimportHookLayer# 开一个新层order 决定它插在现有 9 层的哪个位置network_layerHookLayer(network_control,order15)before_httpnetwork_layer.hook(before_http_request,mutatingTrue)# 安装到引擎上engine.hooks.install_layer(network_layer)# 现在你有第 30 个钩子了——且这个钩子与其他 29 个完全同权engine.hooks.before_http_request.subscribe(log_request)你是流程的设计者也是节点类型的设计者。框架只做两件事保证“节点”这个抽象存在钩子系统本身是可扩展的容器保证“执行结构”可以被替换AgentRuntime的 7 个核心方法是开放给覆写的。至于节点叫什么、有多少个、在流程的什么位置触发——全由你决定。这是元框架的元能力世界由你定义。0.3 使用元框架的正确姿势“无限用法”的方法论因为用法是无限的所以这套教程不会教你“用 NorpAgent 实现 RAG”或“用 NorpAgent 做多智能体”。那些只是具体应用不是元框架的使用方法。我们会教你的是“元操作”——组装元框架的四种基本姿势元操作对应的框架机制章节“我怎么把实现挂到框架的命名空间里”注册表操作Registry APIs第 2 篇“我怎么定义一个全新的可填参数”槽位注册Slot Registration第 3 篇“我怎么让框架找到我的代码”地址解析Address Resolution第 4 篇“我怎么在流程中插入自定义逻辑”钩子订阅与方法覆写Hooks Overrides第 5 篇掌握了这四种元操作你就掌握了 NorpAgent 的全部用法。剩下的——不管你要做单 Agent、多 Agent、嵌入式服务、桌面应用、命令行工具——都只是这四种操作的排列组合。0.4 为什么“用法无限”反而需要教程元框架有一个天然的门槛它不说“你可以这样做”它只提供“你可以这样接”。很多人在看完开发手册后仍然会问同一个问题“我知道可以注册槽位、可以写钩子、可以换模型……但我到底应该注册什么写什么钩子换什么模型”这个问题没有标准答案——因为元框架不替你决策。这套教程的作用就是通过具体案例把“接”的过程完整演示一遍让你看清每种元操作在实际代码中长什么样。至于你要接什么那是你的事。我们的目标是读完每一篇你都能亲手完成一次“接”的动作——无论接的是工具、模型、前端、循环还是自定义槽位。0.5 系列教程结构篇目元操作主题对应手册章节第 1 篇快速启动看懂npa()的三层含义第 1、6 章第 2 篇注册表操作9 大命名空间与组件注册第 26 章第 3 篇槽位注册自定义槽位的完整契约第 3.8、25.10 章第 4 篇地址解析字符串地址的四种语义、;keyvalue子句第 3 章第 5 篇工具开发Tool协议、RunContext、取消协作第 7、25.2 章第 6 篇模型接入ModelProvider协议、凭据回落、流式第 7、25.3 章第 7 篇预设模式六种内置预设与自定义 Preset第 12 章第 8 篇救援模式三层故障模型、快照回退、手动工具接管第 15、24 章第 9 篇热重载remount底层链路与 dict 值地址解析红线第 3.7、25.2.6、25.10.5 章第 10 篇会话与记忆SessionManager协议、跨轮续聊第 8、25.4 章第 11 篇沙箱与调度器隔离执行与任务编排第 8、25.5、25.6 章第 12 篇前端与渲染器两层结构、自定义前端第 5、25.7 章第 13 篇钩子29 个内置钩子 自定义钩子层第 9、25.8 章第 14 篇安全系统safe()三档级别、审批与网络策略第 10 章第 15 篇插件开发单文件插件、manifest 包、安全管线第 11、25.11 章第 16 篇通用组件开发register_component与开放命名空间第 2.6.3、25.9 章第 17 篇嵌入式部署install_core()与embedded预设第 14.2 章第 18 篇深入自研循环EventLoop内部机制与压测第 4、24.2、25.1.2 章第 19 篇实践盘点从零到一的完整工程示例第 16、17、25.12 章每一篇的结尾都会给出“你可能可以用这个机制做什么”的开放列表但不会限定你必须做什么。世界的定义权属于你。0.6 谁适合读这个教程致那些不想被定义的开发者。你已经厌倦了“框架教你做人”的叙事——它规定你继承什么类、调用什么 API、遵循什么设计模式。你写代码不是去“适应”一个框架而是让框架“适应”你的问题。NorpAgent 是元框架。它不定义“什么是 Agent”不替你预设执行流程不告诉你“应该用什么模型”或“工具应该怎么组织”。它只提供四样最底层的东西一个地址解析器、一张可热插拔的槽位表、一个开放命名空间的注册表、一个可扩展的钩子系统。这四样东西加起来就是一个“你可以自己画地图”的工具包。所以这个教程不适合以下人群想找一个“开箱即用”的 Agent 产品的人希望框架替你做 80% 决策的人不想理解“地址”、“槽位”、“注册表”这三个概念就想开始写代码的人。它适合的是你不想被“智能体框架”框住想自己定义 Agent 的行为边界你读完了 LangChain 的文档但觉得它们“替你做了太多决定”你是一个库的作者想用 NorpAgent 作底层调度底座在上面搭建自己的 DSL你想理解“热重载、取消传播、跨线程唤醒”这些底层机制如何落地到生产环境。你不一定需要懂得异步编程——框架的事件循环已经替你封装好了。你只需要理解“槽位”、“地址”、“注册表”这三个概念就足以开始。剩下的是你自己画地图的自由。0.7 开始之前请你记住三句话NorpAgent 不定义“Agent 是什么”它只定义“如何把东西接上去”——接什么由你定。宇宙是什么样子你说了算。四个核心机制地址 / 槽位 / 注册表 / 钩子是元框架的“装配语法”掌握了它们你就掌握了无限用法。每一篇教程都在演示一种“接法”不演示“用例”。准备好了吗我们来看看如何“组装”一个新东西吧。