context-mediation-layer

# 上下文协调层 人类-AI工作流的决策治理和协调基础设施。 ## 概览 该仓库是一个工作原型和架构演示，展示了用于治理人类-AI工作流的上下文协调层（CML）。它使得意图、解释、权限、证据、行动和出处明确，从而使AI支持的工作可以在多个参与者和工具之间进行协调、审计、重放和扩展。 核心思想很简单：孤立的AI工作流不应保持断开连接的实验状态。它们需要一个共享的治理层，将加速转化为持久的协调能力，而不是更快地产生模糊性。 该实现演示了该层如何在本地、人类、编码代理、托管聊天代理、工具和知识存储之间工作，而无需依赖于一个供应商的内存表面或一个整体代理框架。 ## 企业问题 AI降低了行动的成本。它并不降低后果的成本。 在多参与者AI环境中，失败往往在内存或检索分解之前开始。当不同的参与者、代理、工具和会话保持局部一致性时，更广泛的环境会失去共享的意图、权限、证据、所有权、决策历史和问责制。 回忆的上下文片段可能有用、过时、未经支持或具有权威性。生成的报告可能具有说服力，但无法追溯。工具操作可能有效，但其授权不明确。后续代理可能会继承输出，但不知道可以安全地假设什么。 更深层次的故障模式不是分歧，而是虚假的收敛：幻觉的共识。生成的制品（报告、计划、精美的幻灯片）可能具有同意的格式，但没有任何商议产生的结果。生产质量取代了通常由权威认证的过程。下游的读者将制品视为已解决，因为它看起来已经解决，决策累积在没有人实际同意的状态上。 当AI支持的工作流可以修改存储库、写入知识存储、生成报告、调用工具、将工作交给另一个模型或影响业务决策时，相关的治理问题变为： - 谁在行动？ - 在什么授权下？ - 他们理解任务的含义是什么？ - 他们依赖哪些证据？ - 什么发生了变化？ - 什么仍然未解决？ - 下一个参与者可以安全地假设什么？ 提示规范和检索不足以回答这些问题。检索可以提供相关材料，但它不能决定哪个源是权威的、哪个声明是过时的、哪个输出是推断的、或者哪个参与者对更改负责。 CML将此视为协调问题。 ## 协调层的作用 该层为人类和代理提供了一个共享的协调基板。它记录了正在尝试的内容、不同参与者如何解释工作、使用哪些证据、在哪个授权下采取了哪些行动以及什么仍然未解决。 分歧是首要状态，而不是错误条件。不兼容的解释被并排记录，并附有其出处，修正案取代了而不是覆盖了以前的记录——因此记录不仅显示了做出了什么决定，还显示了之前由谁、为什么改变了。 它故意不是一个个性层、内存功能或通常意义上的代理框架。当多个表面需要一起工作时，它位于这些表面之下。 CML是协调词汇。该仓库是一个运行时，使词汇具有操作性。 核心基元是： - **意图：** 正在尝试的内容。 - **解释：** 参与者从其位置认为意图的含义。 - **行动：** 已经完成的内容。 - **报告：** 综合、交接或受控的总结。 - **声明：** 可能需要证据、审查或发布的断言。 - **合同：** 参与发生的规则、角色或授权。 - **参与者：** 对贡献负责的人或事物。 - **会话：** 产生跟踪的执行上下文。 - **事件：** 转换轨迹。 治理不变式是： > 稳定的参与者拥有问责制。会话是执行上下文。只有提升的输出才成为持久的协调状态。 聊天记录可以作为证据。终端会话可以产生好的工作。模型可以起草解释。但是，这些表面不会仅仅因为存在就成为规范的。只有当材料被提升到治理存储中，并具有属性、出处和相关的授权时，它才成为持久的CML状态。 提升门户存在是因为生成很便宜，而格式具有说服力：系统故意拒绝让生产质量授予只有授权和审查才能授予的权限。 ## 架构概览 实现保持三个层分离： 1. **治理层** 拥有CML状态：意图、解释、行动、报告、声明、合同、参与者、角色、会话和事件。 2. **运行时层** 提供接口后面的执行能力。它可能托管CLI、SDK、MCP适配器、工具、代理和操作员界面，但它不拥有CML语义。 3. **知识层** 提供上下文、源材料和本地内容。它可以通知协调状态，但它不会仅仅因为有用就成为规范的。 ```text 人类操作员 -> 操作员UI / CLI -> CML应用服务 -> CML治理存储 编码和领域代理 -> CLI / SDK -> CML应用服务 -> CML治理存储 托管聊天和模型客户端 -> MCP适配器 -> CML应用服务 -> CML治理存储 CML治理存储 <-> 受管的本地知识存储 ``` 运行时执行。知识告知。治理决定什么成为共享的协调状态。 ## 治理模型 CML将合同视为首要的治理状态。合同可以定义角色权限、参与者默认值、参与规则、升级规则、写入权限或过程义务。合同真相存在于注册表中，而不是复制的Markdown文件或本地投影中。 在行动之前，参与者应建立四件事： 1. **身份：** 谁或什么正在操作。 2. **授权：** 哪个意图、角色、参与者类型或合同管理参与。 3. **实时协调状态：** 哪些相关的意图、解释、行动、声明、报告、合同、参与者、角色或域正在发挥作用。 4. **下一个受控动作：** 推荐或采取的哪个可逆动作、交接、升级或未解决状态应该发生。 对于实质性调解，参与者分离： - **观察：** 在治理状态或引用的证据中直接发现的内容。 - **推断：** 从观察状态得出的结论。 - **未解决：** 仍然不确定、矛盾、过时或未经授权的内容。 - **提议：** 推荐或采取的下一个可逆动作。 这可以防止有能力的代理将权威、证据、推断和不确定性压平为相同的自信输出。 ## 参与者拓扑 CML显式地表示权威。参与者、角色、绑定、会话和合同是不同的，因为每个都回答了一个不同的治理问题——并且大多数协调失败都是在这些被沉默地混淆时开始的。 | 概念 | 它回答的问题 | |---|---| | 参与者 | 谁对这个贡献负责？ | | 角色 | 可以假设什么姿态或授权？ | | 绑定 | 在哪个表面和提供者上可以假设该角色？ | | 会话 | 哪个执行上下文产生了这个跟踪？ | | 合同 | 哪个活动规则或授权管理行为？ | 当模型和工具跨表面时，这种区别很重要。使用托管聊天表面的高信任参与者与可以模仿其样式的每个模型并不相同。角色不是身份。会话不是参与者。名为`CONTRACT.md`的文件不一定是活动的合同。 这些边界允许多个代理贡献，而不必假装每个参与者都具有相同的权威、内存、授权或范围。 ## 示例工作流 人类创建一个意图：评估提议的治理变更是否应该实施。 研究导向的参与者提交一个解释，描述变更的含义、其依赖的假设和相关的证据。 编码参与者检查实现表面并记录一个单独的解释，描述哪些组件将更改、哪里可能削弱授权边界以及更改在技术上是否可行。 策略或调解参与者从合同层审查相同的意图：变更是否会更改参与者权限、授权要求、知识存储写入规则或持久跟踪语义。 人类在操作员UI或CLI中审查生成的狀態。决策不再埋在几个记录中。它具有共享的形状：意图、解释、证据、未解决的问题、提议的行动以及最终记录的实现工作。 如果实施继续进行，则会针对原始意图记录行动。如果本地知识存储发生变化，则需要明确的授权，并将突变记录回协调存储中。 有用的制品不仅是最终的代码更改或注释编辑。它是为下一个参与者留下的持久协调记录。 ## 当前实现快照 该仓库是一个工作原型和架构演示，而不是生产平台。 当前实现包括： - 带有SQLite/WAL持久性的TypeScript治理服务。 - 用于参与者、角色、会话、意图、解释、行动、报告、声明、合同、事件和知识存储操作的CLI控制平面。 - 相同服务模型的SDK/API层。 - MCP stdio/HTTP适配器和受限的公共桥。 - 用于实时CML检查和治理写入的基于浏览器的操作员UI。 - 治理的本地知识存储读写桥，需要意图授权，并将CML操作记录到跟踪中。 - 具有活动层次结构、不可变修订、保管人属性、内容哈希、父键、授权引用和超出的第一顺序合同注册表。 源快照的验证： ```sh npm test # 20个测试文件通过 # 223个测试通过 npm run build # TypeScript构建通过 ``` 测试计数是此快照的实现证据，而不是永久的API保证。 ## 它演示的内容 该实现演示了AI支持组织的更广泛设计模式： - 将意图视为持久状态。 - 将解释视为与参与者耦合的，而不是普遍真理。 - 将权威、证据、推断和未解决状态视为不同的。 - 将合同视为一级治理状态。 - 将会话视为出处，而不是身份。 - 将知识存储和记录视为证据，直到被提升。 此模式允许不同的代理、工具和人类操作员保持不同，同时仍然针对共享的治理记录采取行动。它使AI支持的工作更加可审计、可重放，并且不依赖于作为集成层的不可见人类操作员。 近期目标是使工作架构清晰：一个本地优先的协调层，人类和代理可以在明确的权威、共享的证据和持久的出处下共同工作。 ## 快速入门 ```sh npm ci npm run build node dist/cli/index.js init --pretty node dist/cli/index.js status --pretty npm test ``` `init`写入`cml.config.json`，在`./var`下创建一个本地SQLite数据库，在本地创建一个`./vault`目录，并提供默认的操作员、范围、根合同、默认代理参与者类型合同和CLI角色绑定。 ## 配置 复制`.env.example`进行环境覆盖，或从`cml.config.example.json`开始。 优先级为： 1. CLI标志 2. 环境变量 3. `cml.config.json` 使用以下命令生成透明的MCP客户端/服务器代码段： ```sh node dist/cli/index.js setup mcp --transport stdio --out ./mcp.stdio.json node dist/cli/index.js setup mcp --transport http --out ./mcp.http.json node dist/cli/index.js setup mcp --transport public --out ./mcp.public.json ``` ## 文档 - [概念和限制](docs/concepts-and-limitations.md) - [设置和配置](docs/setup-and-configuration.md) - [组件](docs/components.md) - [安全](SECURITY.md) ## 许可证 此仓库中的源代码根据MIT许可证许可。根[LICENSE](LICENSE)范围涵盖了构建或运行软件所需的代码文件、测试、脚本、模式和配置示例。 叙述性文档、证据材料、提案文本、客户端记录、实验室笔记和其他非代码材料除非文件明确说明，否则不受MIT许可。 第三方开发依赖项仍在其自己的许可下。