项目定位：编排器，不是另一个 Agent
Pragma 是一个多 Agent 编排桌面应用，用一句话概括：把不同的 Agent Harness、模型、工具、上下文来源和人工决策，组织成可复用的 AI 工作流。
它明确不替代 Claude Code、Codex、PI、Qoder CLI 或下一个优秀的 Agent——而是让它们协同工作：一项 Mission 可以在不同专家之间持续推进，同时保留已经形成的决策、产物和经验。用得越多，沉淀得越多。
系统沉淀三类相互增强的资产：
- AI 工作方式——自由组合 Expert、ExpertTeam、Flow、子 Flow 与人工确认，每个步骤可绑定最适合的模型、Harness、权限与上下文；可版本化、评测、导出、分享。
- 私有知识——上下文抽象为 Host 管理的 ContextStore，事件进入统一 Memory Pipeline，形成有证据支持的 episodic 与 semantic 记忆；动态记忆在策略与审阅控制下升级为稳定知识或可复用 Skill。
- 私有评估集——记录真正重要的任务与预期，Prompt/Flow/模型/Runtime 变化时在系统层验证效果，而不是只判断一次演示成功。
SELF-REINFORCING LOOP
工作流产生证据 → Memory 把证据沉淀为知识 → Evaluation 判断下一次修订是否真的更好。三类资产互相喂养。
有意思的细节：这个项目开发方式本身就是 AI-native——仓库自带 49KB 的 AGENTS.md（给 Codex/Agent 看的工程说明）、.codex/skills/、handoffs/ 交接文档，以及 30+ 条 ADR 架构决策记录。
技术栈与 Monorepo 结构
| 层 | 选型 |
|---|---|
| 语言 / 工程 | TypeScript 全 ESM · Node ≥22 · pnpm workspace + Turborepo · Zod schema 全量校验 |
| 桌面端 | Electron 43 + electron-vite + React（@xyflow/react 流程图、i18next 国际化） |
| Web / Server | Next.js · Fastify（目前仅骨架） |
| 测试 | Vitest，218 个测试文件；ESLint 依赖方向守卫（非法跨层引用直接报错） |
# 目录树（依赖方向：入口 → core → runtime → 本机 CLI 进程）
apps/ desktop 主产品(6.7万行) · server(仅/health) · worker(骨架) · web(健康页)
packages/
shared/ 跨进程协议与领域模型（Execution schema、值对象）
core/ 执行内核(3.2万行)：Expert/Flow/Execution/Context/Plugin/MCP/Runtime契约
runtime/ pi · codex · claude-code · qodercli · antigravity ← 5个独立适配器包
memory/ 记忆平面(1.2万行)：Evidence/Episodic/Semantic/Knowledge/Skill
interpreter/ Pragma DSL 的解析·校验·迁移·编译
evaluation/ mission-board/ context-filesystem/ built-in-agents/
依赖方向的核心约束：@pragma/runtime-* 独立依赖 @pragma/core，而 Core 绝不反向依赖任何具体 Runtime——Worker、Desktop 或未来云端执行器可以按部署环境自由装配 Runtime。这条边界不是文档口号，而是 ESLint 可执行约束。
执行内核：六个站得住的工程设计
3.1Execution 统一模型
Expert 单轮对话和 Flow 执行落到同一棵 Invocation Tree（flow / task / human-task / expert / expert-team 五种节点），而不是维护两套观测、恢复、输出模型。持久化走单一 Canonical Event Log（标准消息、调用生命周期、委派、人工交互等可恢复语义事件）；实时输出（token / thinking / tool delta）只走进程内 Live Bus 非持久化发布，执行结束即释放。
这意味着：普通 Expert 的子 Agent 与团队委派都直接产生子 Invocation，没有伪装成单节点 Flow——领域收敛做得干净。
3.2Runtime Session 所有权
Runtime 会话由 ExpertSession 或 FlowExecution 显式拥有，通过原子 claim + lease + 完整身份校验 + 恢复引用防止误复用。子 Agent 用 sessionId / parentSessionId 表达归属，同一会话多轮任务拥有不同 runId；spawn / wait / list / send / resume / interrupt 统一归一化为 agent.command。这是防止会话串用与 TOCTOU 攻击的不变量。
3.3Runtime Adapter：五个 CLI 一个接口
每个本机 Agent CLI 一个独立包，统一实现 RuntimeDriver 契约：模型发现、session create/restore、事件流、cancel/close。PI 适配器最重（模型目录、版本化 Compatibility Profile、思考档位归一化、最小真实请求连接验证）；Claude Code 适配器最危险（见 §06）。
3.4ContextStore 抽象
上下文不困在单个对话产品里。Host 管理的 ContextStore 支持多 Store、元数据、检索、写入与装配；仓库提供 In-memory / JSON / 文件系统 / Mission Board / Memory-backed 实现，其他数据库或检索系统可经 Host Adapter 接入。
3.5Capability 治理
Expert 固定引用 Capability 的不可变 revision + 工具 allowlist，健康状态与凭据独立管理（凭据单独加密）。MCP 参数 schema 由服务端动态提供，运行前只要求 allowlist 中的工具仍然存在——工具删除时引导用户修改 Expert，而不是阻塞。比把 Skill/MCP/Secret 直接嵌进 Expert 配置更可治理。
3.6Pragma DSL 与可移植 Bundle
版本化 YAML（当前 pragma/v4）声明式描述 Expert、ExpertTeam、Flow、RuntimeProfile、Capability、ContextStore、Automation、Evaluation；Interpreter 负责解析、链接、校验、迁移、编译、重新生成。可打包成 .pragma Bundle 跨 Host 导入导出——工作方式能跨系统移动，不锁死单一厂商。
# bundle-transfer 示例：一个带 Skill + MCP + 知识库的便携 Expert
apiVersion: pragma/v4
kind: Expert
metadata: { id: 1xddvess309a6gme, name: Portable Product Expert }
spec:
scope: Answer product questions and explain portable Pragma bundles.
runtime: { ref: runtime-profile:knr7p5b7qc55wv92 }
capabilities:
- { ref: capability:j35188zs37g69g0n, kind: skill } # SKILL.md
- { ref: capability:ygypdtr7bfev740a, kind: tools } # MCP 端点
contextStores:
- { ref: context-store:w01fppfxrn31gf7v, namespace: product, required: true }
插曲：什么是 ADR
阅读这个仓库会频繁碰到「ADR」——Architecture Decision Record（架构决策记录），一种把架构决策写成结构化文档的实践，记录当时为什么这么选。
典型结构：背景/上下文（遇到什么问题）→ 决策（选了哪个方案）→ 后果/理由（为什么、放弃了什么）。
价值在于：后人（或几个月后的自己）能看懂「为什么」而不是只看到代码结果；同一件事不会反复讨论；新成员读 ADR 即可理解架构演化史。
Pragma 有 30+ 条 ADR（编号 001–040），例如：
- ADR-006 Runtime 会话所有权与租约
- ADR-017 Flow 并行必须 fork-join
- ADR-031~039 记忆平面九连：可扩展记忆平面、持久事件 Feed、分层情景记忆、保守语义记忆、Agent 驱动召回、存储治理、知识审阅与分享
这本身就是信号：项目以非常工程化的方式开发——每条重大设计都有书面决策依据。对 AI 辅助开发尤其重要，因为文档化决策比口头约定可靠得多。
记忆系统：把「越用越懂你」做成有审计的工程
这是全项目设计最重、文档最完整的一块（68 文件 / 1.2 万行 + 九条 ADR），且经历过一次彻底推倒重来。旧系统把记忆做成「按 Agent 安装的插件」（Task/Experience/Fact/Skill 四类文件记录）——没装插件的 Agent 事件会漏掉，也无法支持 Team/Flow/Project 等组织资产。ADR 031 决定：记忆是 Host 内置、always-on 的能力，旧数据硬切割（不读取、不迁移、不导入）。
记忆蒸馏流水线 · 从动态记忆到受治理知识
5.1对象模型
| 概念 | 含义 | 持久形态 |
|---|---|---|
| Evidence | 「实际发生了什么」的不可变依据（消息、事件、工具结果、产物） | append-only，可重算不可替代 |
| Episodic | 过去做过什么、结果、恢复过程 | dynamic projection |
| Semantic / Fact | 当前相信什么是真的，含冲突、时效、置信度 | dynamic projection |
| Knowledge | 可长期读取的高价值知识 | immutable revision |
| Skill Candidate | 从重复经验提炼的工作范式 | 评测+批准后升级为 Skill Capability |
5.2七个关键设计
- Agent 驱动的召回。没有 recall_memory 专用工具，Host 不生成隐藏 query、不偷偷注入匹配项。记忆是只读 ContextStore，模型自己逐层 list/search/read——透明、可审计，代价是依赖模型主动性。
- 分层加载协议。记忆不塞爆上下文：guide.md（常驻，≤2KB）→ overview.md（摘要，≤4KB，事实优先、情景只留最近 3 条）→ 类型 summary/index（只列 hot 记录）→ items 按需详情 → evidence 按需核验（普通搜索不返回证据）。
- 保守的语义记忆。冲突事实不靠置信度互相覆盖，并存并标记；事实变化走 revision CAS（主体独占事实用原 id 建新 revision，矛盾来源保留历史）；召回默认排除过期/失效/superseded；Fact 的 subject 只来自可验证 allowlist（本机 User、Project、根资产、producer Expert）。
- 治理闭环。动态记忆 → 后台 Curator 提炼 → Candidate → 用户审阅/编辑 → 批准 → 原子创建 Context Store rev1 并挂载。已有知识的更新只提交「修订提示词」，由独立 Store Revision Agent 生成 change set，用户批准后以 revision/hash CAS 原子激活。Skill 提炼有硬门槛：同 Expert 至少 3 条高价值独立 Episode、覆盖 2 个对话、至少 2 条成功；新 Skill 必须通过 3 次来源回放 + 1 次边界用例 + 静态检查 + 脚本测试才进入人工批准；生成脚本在无网络、无子进程、无 native addon 的受限子进程中执行。
- 「忘记」≠「失效」。失效保留内容和历史、停止默认召回；忘记删除当前内容 + 全部 revision 历史 + 治理事件 + 不再被引用的 Evidence，只留一个 content-free tombstone（防止后台证据重放复活同一记忆）——不可撤销。
- 存储治理。Feed payload 30 天 / 512MiB，删除边界 = 所有 consumer 的最小 durable checkpoint，落后的数据被「固定」而不是静默删除；每 Module 每 Execution 最多 2,000 条 / 16MiB 待提炼证据；dead letter 30 天 / 10,000 条 / 64MiB；Episodic ≤10,000 条，Semantic ≤20,000 条，每条保留最近 100 个 revision；模型不可用时任务留在 durable queue，重试耗尽进 needs_attention；SQLite 迁移 fail closed。
- 权限模型。生效策略 = global ∩ 根资产 ∩ producer expert ∩ mission restriction 四层交集。独立 Expert 只能看到自己的 Episode；团队 Episode 不会算成成员个人履历；binding 权限只能收紧不能放宽。
5.3物理存储
# 全 SQLite 多库分离 · 记忆数据不写 Agent workspace
~/.pragma/data/event-bus/feed.sqlite # 持久事件总线
~/.pragma/data/memory/modules/episodic/episodes.sqlite
~/.pragma/data/memory/modules/semantic/facts.sqlite # 含 revision 与审计
~/.pragma/state/memory/modules/*/jobs.sqlite # 提炼任务队列（durable）
~/.pragma/state/memory/modules/*/dead-letters.sqlite
~/.pragma/data/context-stores/<storeId>/ # 批准后的知识库
BOTTOM LINE
这套设计最聪明的地方是把「记忆」和「知识」分成两个世界：动态记忆是持续变化、可重算的解释（重算无成本），知识是从中蒸馏、经人批准才激活的稳定资产（immutable revision）。Evidence 全程可追溯、冲突不覆盖、遗忘可治理——「AI 越用越懂你」被做成了有审计、有回滚、有权限的工程系统，而不是黑盒 embedding 库。
仓库自评：三个未闭合的边界
以下风险不是我的推测——Pragma 的架构文档 docs/architecture/current-architecture-overview.md 自己逐条承认，并给出了演进顺序。这种坦诚在开源项目里相当少见。
P0 · SECURITY BOUNDARY NOT CLOSED
宣称 Desktop 是本地权限闸门，但没有真正的 LocalPermissionGuard：Claude Code Runtime 默认 permissionMode = "bypassPermissions"（packages/runtime/claude-code/src/adapter.ts:53），Electron BrowserWindow 设了 sandbox:false。Core 的 Managed Tool approval 只能约束进入 Pragma 工具层的调用，无法证明 Runtime 自带的文件/Shell/网络工具都被拦截。建议：生产默认值不得是 bypass，先封安全边界再接 Mission。
P1 · CLOUD CONTROL PLANE MISSING
apps/server 只有 /health，apps/worker 只打印 Ready——没有调度队列、租户、配额、重试、dead-letter。当前全部能力跑在单机文件系统内，是「本地可持久化 Agent SDK」，还不是「云端多专家编排平台」。
P1 · PROTOCOL OWNERSHIP SPLIT
Execution 协议在 @pragma/shared，Runtime/Expert 契约在 Core，Desktop 又自持一套 pragma.expert/v2、Mission、Capability、IPC schema——实例化时要把 v2 降级成 Core v1 对象。单机内可用，进入 Cloud ↔ Desktop 会产生双重模型与版本协商问题。
另有三个 P2 级判断：@pragma/core 已成「大内核+大出口」（32 个领域同时暴露，建议分 domain/application/infrastructure 三层）；File Store 用 25ms 轮询 + 重写完整数组实现 watch，只适合本地，不适合云端；Desktop Main Process 正变成第二个业务内核，建议把可复用服务与 Electron 层分离。
总体评价
| 维度 | 判断 |
|---|---|
| 执行内核 | 扎实——Runtime 隔离、Execution 统一模型、Session 所有权、Capability revision 是真实水平，不是玩具 |
| 记忆系统 | 亮点——蒸馏管线 + 治理闭环 + 证据追溯，全项目最值得抄的部分 |
| 文档体系 | 顶级——30+ ADR、架构自评、实施计划，且自评里敢写「当前最有价值的事不是加功能」 |
| 云端控制面 | 未建——Server/Worker 是骨架，调度/租户/审计缺失 |
| 安全边界 | 待补——P0：无统一权限闸门，Claude Code 默认 bypass |
| 分发 | 局限——仅 macOS 未签名安装包；许可证为自定义 source-available（非 OSI 开源，托管服务/商业嵌入需书面授权） |
一句话：执行内核优秀、控制面未建、安全边界待补的预览级项目。作为「本地 Agent 编排 SDK」已经成立；离「云端多专家平台」还差一个控制面和一个权限闸门。值得关注它接下来几个版本的走向——尤其是安全边界闭合与协议收敛这两件事。