架构总览

为什么采用组装方式

同一个任务可能从交互式 CLI、定时器或 Webhook 进入。如果每个入口都实现一套存储、工具和恢复逻辑，重试时就容易创建重复任务，身份校验也会出现差异。

ASM 让入口携带明确的租户上下文，再复用 Durable 的任务和存储接口。业务工具、数据库适配和入口控制分别作为扩展接入，产品层决定启用哪些能力。

上层选择并组装下层接口；扩展能力留在 ASM 包和宿主应用中。

层	责任	当前接入点
宿主应用	认证、授权、数据库驱动、模型配置、生命周期	提供 Context、Provider、连接池及 Harness 工厂
ASM 通用扩展	租户隔离、运行记录、事件去重、可选工具	PostgresStorage、RoutineRunner、TriggerEngine、createExtraToolsExtension
ASM 业务扩展	业务 MCP 与报告流程	AsmMcpServer、createAsmMcpExtension、createAsmCliExtension
pi 核心	上下文、持久化任务执行、工具注册、MCP、Codemode、CLI 扩展	Chord Context、Durable Storage / Registry、ExtensionAPI

图与表表达同一关系：宿主使用 ASM 扩展，ASM 通过公开接口使用 pi 核心。业务规则留在业务扩展和宿主中，pi 核心保持独立。

一次事件如何执行

以库存刷新事件为例：

1. 宿主认证请求，并把 tenantId、scopeId 放入 Chord Context。
2. TriggerEngine.ingest() 校验事件摘要，在事件记录库中按租户和 dedupeKey 去重。
3. 路由将事件转为任务参数，TriggerRoutineRunner 将事件键接到 Routine 的运行记录和 Redis 锁。
4. 宿主的 openHarness(run, context) 重开该次运行对应的存储和暂停状态的 Harness。
5. RoutineRunner 首次创建会话与根任务；重投时等待原任务，从已提交的检查点继续。

因此，重投必须保留原事件身份。存储中的检查点可避免重复执行已提交阶段；对检查点之间发生的外部写入，业务仍需提供幂等键，即重复请求使用同一身份并得到同一结果。

保持 pi 核心不变

ASM 的 PostgreSQL 支持实现 Durable 的 Storage 接口；通用工具和业务工具通过 Registry 安装；CLI 通过 ExtensionAPI 注册。当前这些能力都位于扩展包中，不需要修改 pi 核心。

新增能力先检查公开扩展口。缺少接口时，先向上游提出接口变更，再在 ASM 侧接入；不在核心中加入仅为某个 ASM 产品服务的分支。

跟随上游 minor 版本

ASM 按 pi 的 minor 版本同步。比如从 1.5 进入 1.6 时，选择升级当时 1.6 系列最新的 patch tag；进入该 minor 后不逐个追随普通 patch。开发期不追 patch，也不 cherry-pick，包括安全修复；等待期间仅在 ASM 扩展中适配，不修改 pi 核心。

这是一项维护策略，不表示升级已自动化。具体步骤见上游同步。

源码依据：Storage 适配、Routine 执行器、事件适配、业务扩展。