SYNAPSE — 决赛作品仓库

第三届中国研究生操作系统开源大赛·社区赛题参赛作品。主题：Coordination as Compression——面向多智能体协作的低开销通信、非文本状态传递与共享记忆机制，以 Pi coding agent 扩展的形式实现（TypeScript，单一实现主体）。

工程源码位于 src/；完整的开发文档（机制细节、协议、配置、实验装置）见 src/README.md。

项目简介

一个 Pi 会话委派多个子 Agent 协作，任务之间通过可追溯、可校验的共享记忆复用发现，而不是反复转贴全文。SYNAPSE 在 pi-subagents 扩展骨架上新增共享记忆与状态传递层（代码与配置中称为 synapse）：父会话负责协调和决策，子 Agent 负责有明确边界的工作；共享记忆保留结论的来源，来源文件发生变化时相关记忆被标记失效，包括尚未提交的修改。全部投递、用量与终态进入只追加的计量日志，不报代理值。

应用场景

多 Agent 代码库问答与侦察：规划、取证、执行、总结四角色流水线，交接的是产物而不是对话。
跨任务的证据沉淀与复用：上一次会话写入共享记忆的发现，在下一次委派时按授权范围自动召回。
需要逐项审计通信与记忆开销的自动化流水线：每次投递的字节数、模型用量、记忆复用与终态均可回查。

主要功能

围绕赛题的三项机制要求：

机制	实现
低开销通信	委派交接传引用与摘要而非全文；阶段结果以句柄兑现；全部投递、用量与终态进入只追加计量日志（不报代理值）。
非文本状态传递	检索类委派可协商为向量状态——发送侧把 float32 载荷发布到内容寻址存储，信封只携带 `stateRef` 引用，接收侧校验后对冻结语料做余弦检索；语料可驻留 POSIX 共享内存段跨进程复用。
共享记忆	子 Agent 可检索和记录发现，宿主在委派时自动召回授权范围内的记忆，跨 Agent、跨任务复用并计量命中率；记忆按来源字节指纹失效。

系统环境

项	要求
操作系统	Linux（SHM 语料驻留段需 Linux 与 `/dev/shm`；其余功能跨平台，单元/集成测试覆盖 Linux 与 Windows）
Node.js	24.x（类型检查与测试在此版本验证）
Pi coding agent	0.85.x（扩展加载与委派流程在此版本验证）
目标平台	openEuler 24.03-LTS-SP3（SHM 实测与 S1–S3 验收）

依赖要求

运行时依赖经 npm ci --ignore-scripts 或 node install.mjs 安装（见下）。
嵌入 API 为可选项：配置 synapse.embedding 后需要（siliconflow 或 paratera 兼容端点）；只用关键词检索无需任何密钥。密钥只经环境变量引用，不落入仓库。

构建方法

源码为 TypeScript，按解释方式加载，无需单独构建步骤；提交门禁为类型检查：

cd src
npm ci --ignore-scripts
npx tsc --noEmit                                    # 全量类型检查
npx tsc -p tsconfig.synapse-tests.json --noEmit     # SYNAPSE 测试套件类型门禁

运行方法

cd src
node install.mjs          # 方式一：拷贝安装到 ~/.pi/agent/extensions/subagent
# 或
npm ci --ignore-scripts   # 方式二：源码临时加载
pi -e ./index.ts --prompt-template ./prompts

安装后在 Pi 会话中执行 /synapse-setup synapse 并重启会话开启共享记忆，用 /role-pipeline <任务> 运行一次四角色协作任务。详细步骤与配置见 src/README.md 的「快速开始」。

测试方法

cd src
npm test          # 单元测试（node:test）
npm run test:all  # 单元 + 集成

测试及验证材料（真实运行日志、环境快照、复现指南）见 tests/，各批实验源码、配置与数据来源见实验入口；功能冒烟、机制自检与实验装置冒烟三条验证路径见 demo/。

已知限制

摘要（完整清单见 src/README.md「已知缺口」）：

检索委派的向量通路在模块层已可达 state，生产宿主的触发点尚未接线。
SHM 语料驻留段的单写者由装置构造与语料字节同一性保证（writer.lock 未实现）；arm64 内存栅栏未实现（当前 x86-64 TSO 前提）。
残差（delta）编码的标定结论是负结果（无组合达到 100% 检索一致性），净收益不得据此声称为正。
嵌入语义检索无密钥时诚实报告 unavailable，不静默降级。

仓库结构

按大赛决赛作品提交目录规范组织：

项目根目录/
├── README.md                     本文件
├── src/                          项目源代码（完整工程：实现、测试、实验装置与开发文档）
├── docs/                         参赛材料（项目创新说明、成员分工及主要贡献说明、
│                                 人工智能及第三方工具使用说明 PDF；项目说明书 PDF 与可编辑源文件）
├── tests/                        测试及验证材料（运行日志、环境快照、复现指南）
├── demo/                         与赛道相适配的可验证交付物（功能冒烟/机制自检/装置冒烟）
├── presentation/                 决赛现场演示 PPT 与决赛演示视频
└── 作品原创承诺书.pdf

本仓库派生自 nicobailon/pi-subagents 的 47bae7f7（v0.67.0），未导入完整上游提交历史；上游与本仓库均采用 MIT 许可证（见 src/LICENSE）。

决赛展示材料

项目说明书 PDF（Word 源文件）。
决赛现场演示 PPT。
决赛演示视频（MP4，时长约 3 分 05 秒）。