<<<<<<< HEAD

SYNAPSE ／Shared-memorY Native Agent Protocol for Stateful Exchange

SYNAPSE 是面向“第三届中国研究生操作系统开源创新大赛——一种面向多智能体协作的低开销通信、状态传递与共享记忆机制”赛题设计的 Linux 原型系统。

项目围绕三个核心目标展开：

• 使用结构化协议降低 Agent 间通信开销；
• 使用语义向量和共享内存传递中间状态；
• 使用统一共享记忆实现跨任务知识复用。

系统包含 Planner、Retriever、Executor、Verifier 和 Summarizer 五个独立 Agent 进程，可完成调研、量化分析、策略生成、交叉比较和综合报告等多步骤关联任务，并提供 text 与 struct 两种协作模式的可复现 A/B 实验。

核心特性

五类 Agent 协作

Agent	主要职责	能力声明
Planner	任务拆解、执行规划、红队质询	task_decompose、planning
Retriever	文档检索、历史记忆检索、状态生成	knowledge_retrieval、memory_search
Executor	CodeAct 执行、数据分析、结果生成	tool_execution、code_act
Verifier	五维质量评分、反馈生成	quality_assessment、feedback_generation
Summarizer	总结生成、共享记忆写入	summarization、memory_write

每个 Agent 使用 multiprocessing 的 spawn 模式启动，通过中心 Broker 完成注册、能力发现和消息路由。

双模式通信

系统为同一份 canonical message 提供两种线上表示：

• text：完整文本信封，参数、结果和状态向量全部内联；
• struct：紧凑短键映射，大正文使用共享内存引用，状态向量使用 float32 编码。

两种模式在解码后恢复为相同的业务对象，Agent 业务逻辑不读取通信模式。

非文本状态交换

Retriever 根据任务查询生成语义向量，并将向量传递给 Executor 和 Summarizer。接收方使用该状态向量对候选证据片段执行余弦 Top-K，产生可审计的选择索引和相似度分数。

状态指标分别记录：

• 状态传递次数；
• 唯一状态数量；
• 编码字节和原始 float32 字节；
• 状态消费次数；
• 状态实际参与决策次数。

POSIX 共享内存

struct 模式将超过阈值的大字符串写入共享内存，并在线上消息中传递 descriptor：

{
  "__shm__": "psm_xxx",
  "size": 1234,
  "sha256": "content_sha256",
  "encoding": "utf-8"
}

相同正文通过 SHA-256 内容寻址复用。系统分别统计逻辑引用、唯一物理对象、唯一写入字节、descriptor 字节、读取字节和去重命中。

跨进程共享结构由 src/shm_kv.py 实现，采用共享内存追加日志：

[write_offset][version] + [record_length][JSON record]...

日志由进程锁保护，每个进程维护本地物化视图，并按版本增量回放新记录。

共享记忆

每条记忆采用统一结构：

id
source_agent
created_at
task_id
topic
memory_group
summary
mem_type
tags
payload
embedding
reuse_count

共享记忆支持：

• 关键词检索；
• 标签检索；
• 语义相似度检索；
• 记忆类型过滤；
• 任务分组过滤；
• Top-K 返回；
• 复用计数；
• JSON 持久化。

系统包含两条跨任务复用路径：

1. Retriever 复用历史 evidence；
2. Executor 读取 Summarizer 保存的历史 summary。

CodeAct 执行

Executor 支持由 LLM 生成 Python 分析代码。代码通过 JSON stdin 读取任务、规划、证据、共享记忆和反馈，并在轻量沙箱中运行。

沙箱包含：

• AST 导入和调用限制；
• 未定义名称预检查；
• python -I 隔离解释器；
• 最小运行环境；
• 执行超时；
• CPU、内存、文件和进程资源限制；
• 固定结果 Schema；
• 领域语义检查。

系统支持首次代码生成和一次带上下文的定向修复，并分别统计首次成功、修复成功和最终成功结果。

Verifier 质量门禁

Verifier 从五个维度评估 Executor 的结构化结果：

• 数据充分性；
• 逻辑一致性；
• 完整性；
• 可执行性；
• 可追溯性。

程序根据任务类型使用公开权重计算总分，并结合 Schema 与语义检查决定是否通过。每个任务最多进行一次带反馈修订，系统保留得分最高的有效结果。

辩论协作

高风险综合任务支持 collab=debate：

Executor 分析
      ↓
Planner 红队质询
      ↓
Executor 修订
      ↓
Verifier 评分

当前 G3T1 跨领域比较和 G4T1 综合报告启用该流程。

系统架构

flowchart TD
    O["Orchestrator
DAG 调度"]
    B["Socket Broker
握手、能力发现、路由"]
    A["五类 Agent 进程"]
    S["状态交换
向量 + 共享内存"]
    M["共享记忆
存储、检索、复用"]
    E["评测模块
开销、质量、耗时"]

    O <--> B
    B <--> A
    A <--> S
    A <--> M
    O --> E
    A --> E

系统主要由以下模块组成：

模块	实现
多 Agent 运行时	多进程启动、DAG 调度、任务状态管理
Broker	Socket 服务、注册握手、能力发现、消息路由
协议模块	canonical envelope、text/struct codec、语义摘要
状态交换	embedding、float32 状态、余弦 Top-K
共享内存	大对象引用、内容寻址、追加日志
共享记忆	统一记忆单元、组合检索、跨任务复用
CodeAct	代码生成、沙箱运行、结构化回传
Verifier	Schema 检查、语义检查、五维评分
回放模块	LLM 响应录制、SQLite 回放
评测模块	通信、状态、记忆、耗时和成功率统计

通信协议

业务层统一使用以下 canonical envelope：

from
to
action
topic
args
result
state_vector

协议处理流程：

1. 业务层生成 canonical envelope；
2. 状态向量统一量化为 little-endian float32；
3. 对 canonical JSON 计算 SHA-256；
4. 根据模式选择 text 或 struct codec；
5. Broker 根据外层信封的 to 字段路由；
6. 接收方解码并物化共享内存正文；
7. 重新计算 canonical SHA-256；
8. 校验通过后交给 Agent 业务逻辑。

协议版本为 v3，Broker 注册阶段会校验客户端协议版本并记录能力描述。

任务流程

每个普通任务执行以下流程：

PLAN + RETRIEVE
        ↓
     EXECUTE
        ↓
      VERIFY
        ↓
    SUMMARIZE

任务以 DAG 形式组织，后序任务会继承依赖任务的结构化结果。

每一轮包含 10 个基础任务：

• 远程办公主题调研；
• 新能源汽车主题调研；
• 两个主题的量化分析；
• 两个主题的策略建议；
• 两个主题的监测指标设计；
• 跨领域比较；
• 最终综合报告。

默认 --rounds 2 会扩展为 20 个连续任务。后一轮根任务依赖上一轮汇点，保证任务按轮次连续执行。

A/B 实验

系统对 text 与 struct 模式执行严格配对实验。

每一对实验包括：

1. 一次不计入 A/B 的 LLM 响应录制轮；
2. 一次 text 回放轮；
3. 一次 struct 回放轮。

text 与 struct 共同读取同一个 SQLite 响应库，运行顺序逐对交替。公平性审计检查：

• 录制轮和两种模式是否有效；
• 逻辑消息数是否一致；
• LLM 输入输出是否一致；
• 状态传递和消费是否一致；
• 记忆查询和复用是否一致；
• CodeAct 与 Verifier 行为是否一致；
• semantic digest 集合是否一致；
• 逐任务结果 SHA-256 是否一致；
• 严格任务成功率是否达到阈值。

只有 fairness.comparison_valid == true 时，报告才生成通信和耗时节省率。

主要指标

指标	含义
msg_count	Agent 间逻辑消息数
payload_bytes	内层协议 UTF-8 字节
wire_sender_bytes	发送方到 Broker 的完整帧字节
wire_forward_bytes	Broker 到接收方的完整帧字节
wire_bytes	两跳 Socket 字节之和
payload_token_estimate	通信线格式 token 估算
llm_input_tokens	LLM 输入 token
llm_output_tokens	LLM 输出 token
vector_transfers	状态向量传递次数
vector_consumed	状态向量消费次数
vector_decisions	状态参与决策次数
shm_logical_references	共享内存逻辑引用次数
shm_unique_objects	唯一共享内存对象数
shm_unique_bytes_written	唯一正文写入字节
shm_dedup_hits	内容去重命中次数
memory_hit_rate	共享记忆命中率
memory_precision_at_1	记忆 Precision@1
memory_recall_at_1	记忆 Recall@1
memory_avoided_retrievals	避免重复读取文档次数
cross_agent_memory_reads	跨 Agent 记忆读取次数
codeact_first_ok	CodeAct 首次成功次数
codeact_final_ok	CodeAct 最终成功次数
verifier_passed_count	Verifier 通过任务数
task_success_count	严格任务成功数
task_avg_s	单任务平均耗时
task_p95_s	单任务 P95 耗时

示例实验结果

仓库中的 outputs/experiment_latest.json 为 Linux（内核 5.15，x86_64）+ 真实 LLM（SiliconFlow）环境下的实测数据：20 个任务、3 对 A/B 实验，公平性审计通过。下表为逐指标取 3 对实验中位数的结果。

指标	text	struct	struct 相对变化
线上传输字节（完整两跳）	24,398,836	9,926,264	↓ 59.3%
payload 字节	11,363,362	4,234,186	↓ 62.7%
payload token 估算	3,076,253	1,085,011	↓ 64.7%
协议+IPC 耗时	1.786s	1.011s	↓ 43.4%
受控端到端耗时	6.651s	5.153s	↓ 22.5%
消息数	224	224	一致
向量传递次数	66	66	一致
向量参与决策次数	46	46	一致
记忆命中率（struct 侧）	—	71.7%	—
记忆 Precision@1 / Recall@1	1.0	1.0	一致
Verifier 通过任务数	20/20	20/20	一致
严格任务成功数	20/20	20/20	一致
CodeAct 最终成功	26/26	26/26	一致
SHM 逻辑引用 / 唯一对象（struct 独有）	—	490 / 67	—
SHM 内容去重命中 / 唯一写入字节	—	423 / 400,654	—

完整数据和生成报告位于：

• outputs/experiment_latest.json
• docs/03-实验报告.html

环境要求

• 目标系统：openEuler 24.03-LTS-SP3；
• Python 3.11 或更高版本；
• Unix domain socket；
• multiprocessing.shared_memory；
• 可选的 OpenAI 兼容 LLM/Embedding 服务。

运行时仅依赖 Python 标准库。

大模型 API 与多模型配置

配置文件位置

大模型与 Embedding 服务的统一配置入口位于：

src/config.py

模型配置的调用关系为：

src/config.py
    ↓
src/runtime.py
    ↓
src/agent.py
    ↓
src/llm.py

• src/config.py：设置 API Key、Base URL、默认大模型、Embedding 模型以及不同 Agent 使用的模型；
• src/runtime.py：创建五类 Agent，并把角色对应的模型配置传入各子进程；
• src/agent.py：根据 Agent 角色读取对应模型；
• src/llm.py：负责调用 OpenAI 兼容接口，通常不需要在此文件中填写 API Key。

API Key 不应直接提交到公开仓库。推荐由环境变量提供，并在 src/config.py 中统一读取。

设置大模型 API

打开 src/config.py，定位 LLM 配置区域，填写或检查以下配置项：

配置项	作用	示例
api_key	大模型服务密钥	sk-...
base_url	OpenAI 兼容接口根地址	https://api.example.com/v1
model	未单独指定角色模型时使用的默认模型	model-name
timeout	单次请求超时时间	120
temperature	默认采样温度	0.2
max_tokens	默认输出预算	4096

推荐先在终端设置环境变量，再启动程序：

export LLM_API_KEY="替换为实际 API Key"
export LLM_BASE_URL="https://api.example.com/v1"
export LLM_MODEL="替换为默认模型名称"

随后确认 src/config.py 中的 LLM 配置从对应环境变量读取。配置结构可参考：

import os

LLM_API_KEY = os.getenv("LLM_API_KEY", "")
LLM_BASE_URL = os.getenv("LLM_BASE_URL", "https://api.example.com/v1")
LLM_MODEL = os.getenv("LLM_MODEL", "default-model")

如果服务商提供的是 OpenAI 兼容接口，只需要替换 LLM_BASE_URL、LLM_API_KEY 和模型名称，无需修改 src/llm.py 的请求流程。

为不同 Agent 设置不同模型

不同 Agent 的模型选择位置同样位于：

src/config.py

在角色模型映射中分别设置 Planner、Retriever、Executor、Verifier 和 Summarizer。示例：

AGENT_MODELS = {
    "planner": os.getenv("PLANNER_MODEL", LLM_MODEL),
    "retriever": os.getenv("RETRIEVER_MODEL", LLM_MODEL),
    "executor": os.getenv("EXECUTOR_MODEL", LLM_MODEL),
    "verifier": os.getenv("VERIFIER_MODEL", LLM_MODEL),
    "summarizer": os.getenv("SUMMARIZER_MODEL", LLM_MODEL),
}

对应的终端配置示例：

export PLANNER_MODEL="规划模型名称"
export RETRIEVER_MODEL="检索模型名称"
export EXECUTOR_MODEL="代码与分析模型名称"
export VERIFIER_MODEL="评审模型名称"
export SUMMARIZER_MODEL="总结模型名称"

未单独设置的角色应回退到 LLM_MODEL。模型配置的实际传递位置为：

src/config.py 中的角色模型映射
    ↓
src/runtime.py 创建 Agent 进程时选择角色模型
    ↓
src/agent.py 调用 LLM 客户端

建议的角色分工如下：

Agent	适合的模型能力
Planner	长上下文、任务拆解、规划和红队质询
Retriever	查询改写、信息抽取和证据整理
Executor	代码生成、结构化分析和复杂推理
Verifier	稳定评审、规则遵循和错误识别
Summarizer	长文本压缩、报告生成和记忆写入

设置 Embedding API

Embedding 服务也在 src/config.py 中配置。需要设置：

export EMBEDDING_API_KEY="替换为实际 API Key"
export EMBEDDING_BASE_URL="https://api.example.com/v1"
export EMBEDDING_MODEL="替换为 Embedding 模型名称"

对应配置结构可参考：

EMBEDDING_API_KEY = os.getenv("EMBEDDING_API_KEY", LLM_API_KEY)
EMBEDDING_BASE_URL = os.getenv("EMBEDDING_BASE_URL", LLM_BASE_URL)
EMBEDDING_MODEL = os.getenv("EMBEDDING_MODEL", "embedding-model")

当大模型和 Embedding 使用同一服务商时，可以复用 API Key 和 Base URL，仅分别指定模型名称。

配置检查

完成设置后运行：

python3 env_check.py

正式运行前应确认：

• SYNAPSE_OFFLINE 未设置为 1；
• API Key 已通过环境变量提供；
• Base URL 包含正确的版本路径，例如 /v1；
• 默认模型和五类 Agent 模型名称均为服务商实际支持的名称；
• Embedding 模型可用，且返回向量维度在同一次实验中保持一致。

快速验证：

python3 run_demo.py \
  --rounds 1 \
  --repeat 1 \
  --export outputs/model_config_check.json

如果只需要一个模型服务全部 Agent，可仅设置 LLM_MODEL；如果需要多模型协作，再设置五个角色模型变量。

快速开始

环境检查

python3 env_check.py

编译检查

python3 -m compileall -q src tasks tests tools run_demo.py env_check.py

单元测试

python3 -m unittest discover -s tests -v

当前测试覆盖协议、状态、记忆、共享内存、CodeAct、Verifier、回放、公平性、辩论和报告生成。

codec 基准

python3 tools/codec_benchmark.py --rounds 10

该命令使用 50 条 canonical message 验证 text/struct 语义等价，并生成：

outputs/codec_benchmark.json

进程内连续任务检查

export SYNAPSE_OFFLINE=1
python3 tools/inprocess_pipeline_check.py --rounds 2

该命令执行 20 个连续任务，并验证五类 Agent、状态消费、共享记忆、CodeAct 和 Verifier 业务链。

离线完整 A/B

export SYNAPSE_OFFLINE=1
export DASHBOARD=0

python3 run_demo.py \
  --rounds 1 \
  --repeat 1 \
  --export outputs/experiment_offline.json \
  --report

正式 A/B

模型和 Embedding 服务配置位于 src/config.py。完成配置后运行：

python3 run_demo.py \
  --rounds 2 \
  --repeat 3 \
  --min-success-rate 0.90 \
  --export outputs/experiment_latest.json \
  --report

openEuler 一键验收

bash scripts/openeuler_verify.sh

验收脚本依次执行：

1. openEuler 24.03-LTS-SP3 检查；
2. Python 版本和运行环境检查；
3. 全量编译；
4. 单元测试；
5. 50 消息 codec 基准；
6. 20 个连续任务业务链检查；
7. 3 对完整 A/B；
8. 实验 JSON 断言。

离线模式

设置以下环境变量可强制使用确定性 MockLLM：

export SYNAPSE_OFFLINE=1

关闭终端看板：

export DASHBOARD=0

调整共享内存外部化阈值：

export SHM_THRESHOLD_BYTES=512

调整记忆语义检索阈值：

export MEMORY_MIN_SEMANTIC_SCORE=0.45

调整 Executor CodeAct 输出预算：

export CODEACT_MAX_TOKENS=4500

项目目录

SYNAPSE/
├── README.md
├── LICENSE
├── requirements.txt
├── run_demo.py
├── env_check.py
├── src/
│   ├── agent.py
│   ├── broker.py
│   ├── config.py
│   ├── dashboard.py
│   ├── domain_analysis.py
│   ├── evaluation.py
│   ├── ipc.py
│   ├── llm.py
│   ├── memory.py
│   ├── metrics.py
│   ├── protocol.py
│   ├── replay.py
│   ├── report.py
│   ├── runtime.py
│   ├── sandbox.py
│   ├── shm_kv.py
│   ├── state_exchange.py
│   └── transport.py
├── tasks/
│   └── sample_tasks.py
├── tests/
│   ├── test_core.py
│   ├── test_dashboard.py
│   ├── test_debate.py
│   ├── test_report.py
│   ├── test_shm_kv.py
│   └── test_v4_regressions.py
├── tools/
│   ├── codec_benchmark.py
│   └── inprocess_pipeline_check.py
├── scripts/
│   └── openeuler_verify.sh
├── docs/
│   ├── 01-设计方案.html
│   ├── 02-实现方案.html
│   ├── 03-实验报告.html
│   └── log-candy of the history
└── outputs/
    ├── codec_benchmark.json
    ├── inprocess_pipeline_check.json
    ├── experiment_latest.json
    └── replay/

License

本项目采用 MIT License，详见 LICENSE。

SYNAPSE

bae4a572b8f24f992307717f155c46fe25e6da49