Nexus-MAS

面向多智能体协作的低开销通信、非文本状态与共享记忆运行时。

openEuler 24.03 LTS SP3 · Python/FastAPI · React/TypeScript · Apache-2.0

阅读导航：项目简介 · 应用场景 · 主要功能 · 系统环境 · 依赖要求 · 安装方法 · 构建方法 · 运行方法 · 测试方法 · 已知限制。

项目简介

Nexus-MAS 是运行在 openEuler/Linux 上、可复现验证的多智能体系统层机制原型。通用运行时支持 Agent 注册与依赖图扩展，统一 SACP 类型化通信、SSC 共享状态、签名共享记忆和跨任务复用；默认配置由 Planner、Retriever、Executor、Reporter四个持久独立 Worker 进程协作。

系统提供两个入口：开放任务工作台面向用户问题、文件和连续追问，默认使用B5 控制型记忆，并保留 B3 依赖校验基础；固定评测轨使用 typed-v4 记忆策略与sacp/model-view 结构化接口，执行 B0/B0C/B1/B2/B3/B4/B5 七模式配对消融。系统设计见项目说明书。

最新真实模型结果以 openEuler 八个连续任务场景消融实验为准：八场景 × 十轮 × 七模式，共 560/560 任务完成，零执行失败。成本、效率、质量与结论范围见下方真实模型消融实验结果及最终实验包。

核心目标：让 Agent 不再反复透传长文本，而是通过类型化协议、共享内存状态、类型化结果、可引用资料和可复用共享记忆完成协作，并用同任务、同输入、同评价器的消融实验证明各机制的实际贡献。

证据任务是用于冻结输入、核验质量与对比机制的工作负载。协作接口以动作、参数、结果、能力和状态为核心；共享记忆统一保存不同角色形成的摘要、证据、策略、经验与工具结果。知识工作区也是无文件任务的知识积累和隔离范围。

应用场景

场景	使用方式
运维排障与代码分析	围绕日志、代码、配置和指标，协作分析延迟、N+1 查询、缓存击穿、队列积压、资源泄漏等问题，输出依据与处理建议
资料问答与连续分析	在知识工作区上传文本、JSON/CSV、代码或 PDF，检索相关证据、回答问题并继续追问；来源变化后重新核验历史结果
数据计算与文件生成	在具备 CodeAct 沙箱的环境中授权 Python 执行，分析当前文件并下载生成的报告或数据文件
多智能体机制研究	使用固定评测轨的七模式消融，对比通信、状态交换、记忆复用的成本、时延及质量代理指标
自定义协作流程	通过 `AgentSpec` 与依赖图 API 注册处理器，构建有明确输入、输出和状态依赖的多 Agent 任务

主要功能

任务工作台：四角色协作、连续追问、任务取消、历史记录、报告和执行产物下载。
文件知识工作区：资料上传、索引、检索、引用，支持文件替换、删除及来源依赖失效。
类型化通信与共享状态：SACP 能力握手和契约校验，SSC 共享内存向量传输、接收方校验与计算回执。
共享记忆与增量执行：依赖指纹、检查点、局部重算、历史经验指导，以及绑定当前输入的 B5 控制型记忆。
受限代码执行：rootless Podman CodeAct、有界修复、执行记录与完整产物哈希；可用性由健康接口检查。
评测与审计：B0/B0C/B1/B2/B3/B4/B5 配对消融、模型实际用量、通信计量、Trace 和实验报告导出。
运行时扩展：注册自定义 Agent，校验依赖图并并行执行就绪分支。

核心创新

按照项目创新说明书，项目的主要创新归纳为三项，分别解决连续协作中的长文本重复传递、机器状态文本化，以及跨任务的知识积累和协同增强。新增贡献集中在运行时契约、接收方消费验证、局部重算和当前输入上的方法执行；Protobuf、共享内存、向量编码和 SQLite 是实现这些机制的基础组件。

1. SACP：类型化协作控制与最小信息投影

SACP（Structured Agent Collaboration Protocol）为同主机持久 Agent 进程建立明确的控制契约，把动作、身份、输入输出 Schema、期限、证据与状态引用绑定到当前任务。它将协议校验、角色所需信息和执行回执连接起来，减少连续协作中重复传递全文与控制信息的开销。

能力握手与契约校验：Worker 启动时依次完成 HELLO → CAPABILITY_ADVERTISE → CAPABILITY_ACK → ACK，核对身份、能力、Schema 和协议版本，拒绝错配请求；四角色是默认配置，新增 Agent 使用相同契约。
最小信息投影与带外制品：固定轨 B1–B5 将完整角色输出保存在 Artifact，业务消息传类型化结果、引用和内容哈希；模型按角色接收所需语义字段，保留业务分析、数值、否定和不确定性，身份与 Trace 由运行时维护。开放轨使用结构化角色 JSON，并接入相同的状态验证与控制消费路径。
校验与执行合并 RPC：Worker 在一次请求内核对状态、依赖和当前输入，再决定复用、控制执行或模型生成；缺少有效基线时请求完整同步，保留失败、补发和修复的实际成本。避免生成的角色仍保留独立进程身份和消费回执。

该创新是 Protobuf 信封、类型化投影、带外 Artifact 与 Worker 校验执行的联合机制。实现入口：协议定义、进程通信、类型化结果。

2. SSC：可验证的非文本共享状态交换

SSC（Semantic State Capsule，共享状态胶囊）通过操作系统共享内存传递向量、候选矩阵与机器可计算状态，SACP 传递其描述符。创新重点是将共享数据绑定到当前任务与来源，并由接收进程实际计算和回执，形成可核验的状态消费链。

状态合同与来源绑定：固定二进制头、向量载荷和 manifest 共同记录 shape、dtype、offset、编码器、任务阶段、候选顺序与正文哈希；接收方校验 SHA-256、数据形状和来源，拒绝损坏、错序或错配状态。支持 float32 / float16 / int8，终态与异常路径释放共享段。
计算消费与需求覆盖门禁：Retriever Worker 独立计算候选排序，保留必要事实、反证、指定来源和资料缺口；对可解析的公开要求，缺项、未知或冲突触发候选扩展或完整候选恢复，达到预算上限时明确停止。运行时区分“已生成”“已验证”和“已计算消费”，记录实际进入模型或工具的来源。
分角色二进制增量：公共依赖证明与元数据独立认证发布，各角色只接收自身需要的变化向量、数值和失效状态；Worker 核对增量基线与实际计算上下文，为依赖验证后的复用或重算提供状态支撑。

SSC 用于候选排序、路由、知识检索与状态核验；自然语言分析继续使用本轮可见文本。实现入口：状态胶囊、证据覆盖策略、增量传输与消费。

3. 依赖感知复用与控制型共享记忆

系统将角色输出、纯计算节点和共享知识纳入依赖图，通过统一 UnitStore 与 Checkpoint记录可复用条件。依赖感知复用保留仍有效的工作，控制型共享记忆进一步将已验证方法绑定当前输入执行，使历史任务中的沉淀的知识经验可以参与运行时决策。

依赖指纹与失效闭包：节点记录当前需求、来源、字段读集、配置、工具版本、上游输出哈希、作用域与有效期。依赖变化、过期或撤销沿图传播，只重算受影响节点；仅展示格式变化时可只重做 Reporter。注册指标按实际读取字段构建指纹，注册代码分析使用规范化 AST；没有专用读集的开放资料保守依赖完整输入。
精确节点、方法图与工具结果分层复用：优先复用依赖有效的精确节点；方法适用时，Runtime 匹配公开目标、输入形状与操作合同，Worker 核验后绑定当前来源执行。完整工具结果仅在全部实际输入及工具、策略依赖一致，且无强制重算、新鲜数据或本轮执行要求时复用；输入变化则执行当前工具。
控制消费与当前输入验证：B5 保存 CONTROL_PLAN / CONTROL_STRATEGY / CONTROL_TOOL_RESULT，适用时避免 Planner/Executor 重复模型生成，Reporter 继续形成当前因果解释、行动和限制。固定轨使用已注册分析器；开放轨使用 open-b5/v1-control-memory，将成功 Python 方法参数化，绑定本轮文件后仍在本轮沙箱执行。
原子提交与真实收益审计：检查点、知识单元和消费事件在同一事务提交，CAS 防止旧并发任务覆盖当前状态；提交失败不记为成功省调用。节点命中、经验读取、控制消费、避免生成和 Worker 工具核验分别计量，签名校验当前采用 HMAC-SHA256 消息认证，用于载荷与依赖完整性检查。

B3 提供依赖感知复用基础；B4 为需要生成的角色提供有预算的历史经验指导；B5 通过控制路径消费方法。B4 与 B5 分别扩展 B3，B5 不叠加 B4 的文本经验提示。未知任务、合同不适用或用户拒绝记忆时重算或回到生成；语义相似度不能单独授权复用。实现入口：依赖复用、字段读集、控制合同、控制消费、开放轨适配。

工程与验证支撑：通用 Agent 注册与依赖图提供扩展入口，开放工作台应用消融实验验证的完整机制使用多智能体协作支持用户多轮连续任务执行，rootless Podman CodeAct 提供受限执行与有界修复；它们共同承载上述三项创新。机制贡献以最新的openEuler 八场景真实模型消融和实际Worker 回执为依据，成本、质量与负收益同时报告。

系统架构

flowchart TB
    UI["React Web 控制台"] --> OPEN["开放任务轨"]
    UI --> FIXED["固定评测轨"]
    API["通用依赖图 API"] --> GRAPH["MultiAgentRuntime / 注册 Agent"]

    OPEN --> ORUN["OpenRuntime"]
    FIXED --> BRUN["Benchmark Runtime"]
    GRAPH --> GFABRIC["按注册 Agent 创建的进程池"]

    ORUN --> FABRIC["持久多进程 Agent Fabric"]
    BRUN --> FABRIC

    FABRIC --> P["Planner"]
    FABRIC --> R["Retriever"]
    FABRIC --> E["Executor"]
    FABRIC --> REP["Reporter"]

    ORUN --> SACP["SACP 控制面"]
    ORUN --> SSC["SSC 共享状态面"]
    ORUN --> MEM["Shared Knowledge / 统一记忆单元"]
    BRUN --> SACP
    BRUN --> SSC
    BRUN --> MEM
    GRAPH --> SACP
    GRAPH --> SSC
    GRAPH --> MEM
    MEM --> CONTROL["B5 当前输入绑定与控制消费"]
    CONTROL --> FABRIC
    E --> SANDBOX["Rootless CodeAct 沙箱"]

    BRUN --> METRICS["消融、Trace、统计与报告"]
    ORUN --> DELIVERY["任务结果、执行产物、引用与审计"]

系统由 API 控制进程协调持久 Worker，使用 SQLite WAL、内容寻址 Artifact、共享内存 SSC 和完整 Trace。默认四角色 Fabric 各有四个 Worker：固定轨按Provider/通信协议维护进程池，开放工作台使用独立进程池，通用运行时按注册 Agent 数创建进程。Worker 异常时当前任务失败关闭，整代进程被废弃，后续任务重新握手。

通用扩展通过 AgentSpec 注册带版本的可导入 handler 和输入/输出契约；GET /api/runtime 查看注册目录，POST /api/runtime/tasks 提交依赖图任务。调度器校验无环图与显式状态依赖，就绪分支可以并行执行；四角色是默认配置，本节实验数据仅覆盖该配置。

固定轨七模式消融矩阵

模式	业务通信	非文本状态	共享记忆	作用
B0 全文本	完整 UTF-8/JSON	无	无	传统纯文本基线
B0C 紧凑纯文本	角色裁剪 UTF-8/JSON	无	无	公平纯文本基线
B1 结构化协议	SACP Protobuf	无	无	SACP + 类型化投影 + Artifact 的联合模式
B2 状态胶囊	SACP Protobuf	SSC	无	隔离非文本状态贡献
B3 依赖感知复用	SACP Protobuf	分角色二进制差分	精确节点、PROCEDURE 与工具结果	依赖验证驱动的类型化记忆复用，重算受影响部分
B4 受约束经验指导	SACP Protobuf	分角色二进制差分	B3 基础＋结构化历史方法指导	适用性与预算约束的经验提示，供需要生成的角色读取
B5 控制型记忆	SACP Protobuf	分角色二进制差分	B3 基础＋控制操作图与输入绑定结果	当前输入绑定的控制型记忆执行，避免适用阶段的模型生成

B4 与 B5 分别扩展 B3；B5 不叠加 B4 的文本经验指导路径。页面和报告使用表中的模式名称，请求值仍为 full、full_experience、full_control。经验读取、节点复用与控制避免生成分别计量，工具执行和验证费用保留。机制定义见项目说明书。

真实模型消融实验结果

实验条件与连续任务

条件	本批实际配置
平台	完整 openEuler 24.03 LTS-SP3 VMware guest，x86_64、4 vCPU、Python 3.11.6，原生四 Worker
真实模型	DeepSeek `deepseek-flash`，推理强度 `none`，官方 `/responses` 接口
通信分词与用量	`deepseek-v4` tokenizer；模型输入/输出使用服务端 `usage`，零估算
固定轨编码器	冻结 BGE-small-zh-v1.5，修订 `7999e1d3359715c523056ef9478215996d62a620`，192 维特征哈希投影
实验合同	`fixed-ablation/v5-seven-modes`；B3 `fixed-full/v4-typed`、B4 `fixed-b4/v2.3-budgeted-experience`、B5 `fixed-b5/v1-verified-control`
配对与隔离	相同轮次的提示与证据哈希一致；模式顺序 seed `20261006`；56 个模式×场景记忆命名空间隔离
执行口径	八场景各十轮、七模式，每模式 80 个任务；一批次、一次序列重复、零任务级重跑；内部格式纠错、报告修复和实际执行成本全部保留
预算	本批模型输入/输出无 Token 上限；B4 历史经验上下文受每任务 384 Token 预算约束

实测加载源码指纹为b0e3c3f012da42f7db9064aebc343ad46fed8b0111f7fdd6349f52e8b6bd5c69。该指纹和源码清单标识实测版本；本次核对时，清单中的 70 个后端 Python/Protobuf 文件与当前工作区哈希一致。后续源码调整需要另行验证，实验统计继续绑定本批指纹。

连续任务场景	场景 ID	主要问题
API 延迟事故	`incident_latency`	上游超时与重试放大
N+1 查询	`code_nplus1`	重复数据库读取与批量加载
缓存击穿	`cache_stampede`	同步过期与回源风暴
队列积压	`queue_backlog`	生产消费失衡与毒消息重试
资源泄漏	`code_resource_leak`	未关闭资源与句柄增长
异常吞噬	`code_exception_swallow`	静默失败与部分状态提交
配置漂移	`config_drift`	环境差异与发布错误
证书到期	`certificate_expiry`	TLS 握手失败与时间关联

每个场景的十轮依次覆盖：首次调查、相似任务、部分相关、强制工具重验、新证据、无关硬负例、回到原主题、过期记忆、新旧证据冲突、最终审计。每轮使用预先冻结的输入与评价合同，证据按序列变化；历史记忆必须经过本轮依赖核验。

实验结果

560/560 个任务完成，零执行失败。下表的通信、模型用量、IPC 和耗时均为每任务均值；模型总 Token 是输入与输出之和，与通信 Token 分开统计。

模式	通信 Token/任务	Pipe IPC 字节/任务	模型总 Token/任务	耗时（秒/任务）	质量代理均分	共享记忆命中率
B0	5,160.800	61,402.387	10,599.825	17.744	74.801	0
B0C	3,620.425	32,781.012	7,474.962	17.649	69.765	0
B1	1,416.225	18,811.362	5,030.925	12.752	66.638	0
B2	1,386.888	19,170.763	4,878.137	13.679	67.179	0
B3	910.175	15,371.312	3,552.262	10.460	72.131	6.19%
B4	908.350	16,216.688	3,868.675	12.461	72.433	6.19%
B5	832.475	14,475.450	3,235.338	9.850	69.601	10.06%

模式	相对 B0 通信 Token 节省	相对 B0 Pipe IPC 节省	相对 B0 模型总 Token 节省	相对 B0 耗时节省
B0C	29.85%	46.61%	29.48%	0.54%
B1	72.56%	69.36%	52.54%	28.14%
B2	73.13%	68.78%	53.98%	22.91%
B3	82.36%	74.97%	66.49%	41.05%
B4	82.40%	73.59%	63.50%	29.77%
B5	83.87%	76.43%	69.48%	44.49%

全部任务共 2,086 次模型调用、1,934,162 输入 Token、1,157,048 输出 Token，合计 3,091,210 Token，均有 Provider usage。另有一次连接预检，原接口未保存其 Token 数；上述总量是任务用量，不据此推算完整账单或金额。

七模式成本与时延实测

系统环境

项目	要求与适用范围
完整验证平台	openEuler 24.03 LTS SP3，x86_64；正式实验在完整虚拟机中运行
本地开发平台	Windows + PowerShell 或 Linux + Bash；Windows 可运行 Web 工作台和本地确定性评测，完整 CodeAct 使用 Linux/openEuler 环境
Python	3.11+，需要 `pip` 和 `venv`；完整嵌入环境建议使用已验证的 Python 3.11，并确认固定依赖支持所选版本
Node.js	20+，配套 npm；用于安装、开发和构建前端
浏览器	可访问本地 Web 控制台的现代浏览器；自动化验收使用 Playwright Chromium
资源与存储	完整 openEuler 环境建议至少 4 vCPU、8 GiB 内存、120 GiB 磁盘；数据目录和缓存目录需可写，并为 BGE 模型及上传文件预留空间
网络	初次安装需要访问 Python/npm 包源与模型下载源；真实模型任务需要访问配置的 Responses API。模型缓存准备后，本地检索可以离线运行

依赖要求

依赖层	文件或组件	用途
后端核心	requirements.txt：FastAPI、Uvicorn、Pydantic、HTTPX、Protobuf、NumPy、分词器、cryptography、pypdf、pytest 等	API、多进程通信、状态与记忆、资料解析、计量和回归测试；SQLite 随 Python 提供
真实向量检索	requirements-embeddings.txt：包含核心依赖，并增加 Sentence Transformers 3.4.1、SentencePiece 0.2.0 及其依赖	BGE 文档与问题编码；安装 Python 包后仍需预下载模型权重
openEuler CPU 嵌入	requirements-openeuler-cpu.txt：PyTorch 2.6.0+cpu	`setup.sh` 在 openEuler 上先安装 CPU wheel；本地嵌入计算无需 GPU
前端	package.json 与 package-lock.json：React 18、TypeScript 5、Vite 6、图表/流程组件、Playwright	用 `npm ci` 按锁文件安装；`npm run build` 完成类型检查和生产构建
PDF/OCR	Poppler（`pdftoppm`）、Tesseract 及 `chi_sim`、`eng` 语言包	扫描 PDF 的页面渲染和 OCR；处理扫描件时需要这些系统工具
CodeAct	本地 rootless Podman、独立 CodeAct 镜像、可用的用户命名空间	在 Linux/openEuler 上受限执行 Python；普通任务不要求启用 CodeAct
浏览器验收	Playwright Chromium 及其操作系统依赖	仅安装 npm 包不会自动准备全部浏览器运行依赖，首次测试前需单独安装

后端依赖版本以 requirements 文件为准，前端以锁文件为准。SACP 的 Python 生成代码已包含在 sacp_pb2.py，常规安装和构建无需重新生成协议代码；修改协议时需同步 sacp.proto 与生成代码。

快速部署

本节为安装方法。以下命令均在实际项目根目录（包含本 README、src/ 和 tests/ 的目录）执行。安装脚本创建 .venv，默认安装完整嵌入依赖，并安装、构建前端；脚本不自动下载 BGE 权重，也不提交模型任务。先用 python --version（Linux 为 python3 --version）、node --version、npm --version 核对工具版本。

Windows 安装

powershell -ExecutionPolicy Bypass -File src/scripts/setup.ps1
.venv\Scripts\python.exe -m pip check

openEuler 24.03 LTS SP3 安装

sudo dnf install -y git python3 python3-pip nodejs npm protobuf-compiler \
  poppler-utils podman gcc gcc-c++ make
sudo dnf install -y \
  --repofrompath=nexus-epol,https://repo.openeuler.org/openEuler-24.03-LTS/EPOL/main/x86_64/ \
  --enablerepo=nexus-epol \
  tesseract tesseract-langpack-chi_sim tesseract-langpack-eng

bash src/scripts/setup.sh

其他 Linux 环境先用对应包管理器安装 Python、Node.js 及所需系统工具，再执行 bash src/scripts/setup.sh。仅做核心机制开发时，可在运行安装脚本前设置 NEXUS_SKIP_EMBEDDINGS=1，只安装核心 Python 依赖；该配置不能提供真实 BGE 资料索引。

准备本地模型缓存

需要上传资料并使用真实 BGE 检索时，在联网准备阶段下载冻结权重。Windows：

$env:HF_HUB_OFFLINE = "0"
$env:TRANSFORMERS_OFFLINE = "0"
.venv\Scripts\python.exe src/scripts/prefetch_embedding_models.py --cache-dir .cache/models --models bge-m3
$env:HF_HOME = (Resolve-Path .cache/models).Path
$env:SENTENCE_TRANSFORMERS_HOME = $env:HF_HOME
$env:HF_HUB_OFFLINE = "1"
$env:TRANSFORMERS_OFFLINE = "1"

Linux：

export HF_HUB_OFFLINE=0 TRANSFORMERS_OFFLINE=0
.venv/bin/python src/scripts/prefetch_embedding_models.py \
  --cache-dir .cache/models --models bge-m3
export HF_HOME="$PWD/.cache/models"
export SENTENCE_TRANSFORMERS_HOME="$HF_HOME"
export HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1

需要使用小模型时将下载参数改为 --models bge-m3 bge-small-zh。启动服务时应继续使用相同缓存路径和离线设置；上述环境变量只对当前终端及其子进程生效。已有 Windows 运行记录时，更新入口会优先沿用 output/local-server/runtime.json 中的 embedding_cache；应将模型下载到该记录指定的缓存路径，终端的 HF_HOME 不会覆盖已有记录。

配置与数据目录

.env.example 列出配置示例。**应用和启动脚本不会自动加载根目录 .env**，请在启动前通过 PowerShell 的 $env:变量名 = "值"、Bash 的 export 变量名=值，或 systemd/container 配置注入环境变量。

变量	示例值与作用
`NEXUS_PROVIDER`	`local`：分词器选择的环境参考；固定轨运行后端由请求 `provider` 或 CLI `--provider` 决定，默认 `local`，该环境变量不能切换运行后端
`NEXUS_OPEN_PROVIDER`	`responses`：开放工作台使用真实 Responses API；`deterministic` 供隔离测试使用
`NEXUS_DATA_ROOT`	`src/backend/data`：默认业务数据目录，保存数据库、上传资料及加密模型配置；自定义路径建议使用绝对路径
`NEXUS_PROCESS_MODE`	`multiprocess`：持久 Worker 多进程协作
`HF_HOME` / `SENTENCE_TRANSFORMERS_HOME`	同一模型缓存目录，与预下载命令保持一致
`HF_HUB_OFFLINE` / `TRANSFORMERS_OFFLINE`	`1`：运行时仅使用已准备的本地模型缓存
`NEXUS_SANDBOX_RUNTIME` / `NEXUS_SANDBOX_IMAGE`	`auto` / `localhost/nexus-mas-codeact:openeuler-sp3`：沙箱运行时与独立镜像；实际可用性见 `/api/open/health`
`NEXUS_NPM_REGISTRY`	可选 npm 源，安装脚本传给 `npm ci`

真实模型 API Key 在本机或 SSH 隧道访问的“模型接入设置”页面保存，加密配置和加密密钥保存在数据目录中。保留该目录以延续模型设置、工作区和历史记忆；不将数据、密钥、依赖及模型缓存提交到 Git。Windows 更新入口使用项目内已记录的数据目录，首次默认 src/backend/data，不会仅因设置 NEXUS_DATA_ROOT 就迁移数据。

构建方法

安装脚本已完成首次前端构建。前端依赖变化或需要重新构建时执行（Windows/Linux 通用）：

npm --prefix src/frontend ci
npm --prefix src/frontend run build

产物位于 src/frontend/dist/。后端直接运行 Python 源码，无需单独编译；构建后重启后端，FastAPI 会提供静态控制台和 API。构建前端不会验证真实模型接入或 CodeAct 沙箱。

运行方法

Windows 本地启动与更新

完成安装后，在配置好环境变量的终端执行：

powershell -ExecutionPolicy Bypass -File demo/start.ps1
Invoke-RestMethod http://127.0.0.1:18080/api/health
Invoke-RestMethod http://127.0.0.1:18080/api/open/health

浏览器访问 http://127.0.0.1:18080/。demo/start.ps1 调用 update_local.ps1，重新构建当前源码并在后台运行单个 API 进程；更新前须等待排队或运行中的任务结束。需要指定端口时直接执行 powershell -ExecutionPolicy Bypass -File src/scripts/update_local.ps1 -Port 18081。

运行状态记录在 output/local-server/runtime.json，日志为同目录的 server.stdout.log 和 server.stderr.log。健康接口应返回 status=healthy、source_mode=workspace，source_root 应为当前项目根目录，loaded_source_revision 应对应实际加载源码。

/api/health 核对服务与源码身份；真实模型和沙箱是否就绪应另外查看 /api/open/health 的 provider_configured 和 sandbox.available。

前后端开发模式

Windows：

powershell -ExecutionPolicy Bypass -File src/scripts/dev.ps1

Linux：

bash src/scripts/dev.sh

控制台为 http://127.0.0.1:5173/，后端为 http://127.0.0.1:8000/，API 文档为 http://127.0.0.1:8000/docs。Vite 将 /api 请求代理到后端。按 Ctrl+C 结束开发入口；开发热重载可能中断任务，执行期间避免修改后端源码。

Linux 原生运行已构建控制台

在设置好模型缓存及数据目录的终端执行：

.venv/bin/python -m uvicorn app.main:app \
  --app-dir src/backend --host 127.0.0.1 --port 8000 --workers 1

浏览器访问 http://127.0.0.1:8000/。必须保持单个 API worker；长期运行的 systemd 配置、独立 CodeAct 镜像构建和动态验收见项目说明书及 systemd 配置。

需要启用 CodeAct 时，先为普通服务账号准备 rootless Podman 与 /etc/subuid、/etc/subgid 映射，再以该账号构建独立镜像，并在启动上述后端命令前配置：

podman build -t localhost/nexus-mas-codeact:openeuler-sp3 \
  -f src/CodeAct.Containerfile .
export NEXUS_SANDBOX_RUNTIME=podman
export NEXUS_SANDBOX_IMAGE=localhost/nexus-mas-codeact:openeuler-sp3
export NEXUS_SANDBOX_IMAGE_ID="$(podman image inspect \
  "$NEXUS_SANDBOX_IMAGE" --format '{{.Id}}')"
export NEXUS_SANDBOX_REQUIRE_IMAGE_ID=1

启动后检查 /api/open/health 的 sandbox.available，按部署说明完成真实容器动态验收；镜像构建成功本身不能代替沙箱验收。

rootless Podman：日常 Web 容器

podman build -t nexus-mas:openeuler-sp3 -f src/Containerfile .
bash src/scripts/prefetch_openeuler_models.sh bge-m3
bash src/scripts/deploy_openeuler_container.sh
curl -fsS http://127.0.0.1:8000/api/open/health

容器只把端口发布到宿主 127.0.0.1。远程访问使用 SSH 隧道：

ssh -N -L 18000:127.0.0.1:8000 <user>@<server>

随后打开 http://127.0.0.1:18000/。主应用容器不会挂载宿主容器 socket，因此CodeAct 在该拓扑中安全关闭；完整 CodeAct 使用原生 systemd + 本地 rootless Podman。

开放任务使用流程

在“模型接入设置”保存 DeepSeek 官方 API Key；默认地址 https://api.deepseek.com、模型 deepseek-flash、推理强度 none；
创建知识工作区；任务需要文件时上传资料并等待 BGE/BM25 索引完成；
在“开放任务工作台”输入未预置问题，按需启用 Python CodeAct；工作台自动应用 B5 控制型记忆，未命中有效控制策略时正常生成；
查看最终回答、[EV:…] 引用、四 Agent PID、SACP/SSC、控制消费、模型计量和 Trace；
下载任务报告、执行记录与生成文件，继续执行；在“资料与共享知识”查看自动沉淀的记忆单元、来源依赖和消费记录。机制消融使用固定评测轨。

测试方法

所有测试命令在项目根目录执行，使用已安装依赖的 Python 环境。以下回归和本地机制复现使用本地或 Mock Provider，不产生真实模型 API 费用；首次准备分词器缓存或浏览器仍可能需要联网。正式历史验证记录来自 openEuler 24.03 LTS-SP3 虚拟机，不能代替当前检出版本的测试。

后端与脚本回归

Windows：

.venv\Scripts\python.exe -m pytest -q --basetemp=.pytest-local

Linux：

.venv/bin/python -m pytest -q --basetemp=.pytest-local

pytest.ini 配置 tests/backend、tests/scripts 的发现与源码导入路径，覆盖 API、通信、共享状态、依赖失效、控制记忆、文件和安全逻辑。容器环境相关测试可能按环境条件跳过；跳过不能视为生产沙箱验收通过。

前端构建与浏览器验收

npm --prefix src/frontend run build
cd src/frontend
npx playwright install chromium
cd ../..

Linux 若缺少浏览器系统库，在 src/frontend 中使用 npx playwright install --with-deps chromium 安装所需依赖。之后回到项目根目录，Windows 执行：

.venv\Scripts\python.exe src/scripts/run_browser_e2e.py

或 Linux：

.venv/bin/python src/scripts/run_browser_e2e.py

run_browser_e2e.py 自动构建前端，在临时数据目录和随机端口启动确定性测试服务，执行 Playwright 用例，结束后关闭服务。浏览器报告与失败截图/Trace 位于 tests/frontend/playwright-report/、tests/frontend/test-results/。只需查看测试列表时执行 npm --prefix src/frontend run e2e -- --list。

前端生产构建包含类型检查；根目录 pytest 和上述浏览器验收均不执行 tests/frontend/unit/ 中的组件测试，当前 package.json 未提供独立组件测试命令。CodeAct 的真实容器隔离还需在支持的 Linux/openEuler 环境中按项目说明书执行动态验收，验收入口位于 tests/validation。

本地机制复现

以下命令在隔离目录运行八场景七模式的本地确定性矩阵，仅验证机制，不产生新的真实模型结果：

.venv/bin/python src/scripts/run_benchmark.py \
  --repeats 1 \
  --provider local \
  --seed 20261006 \
  --scenarios incident_latency code_nplus1 cache_stampede queue_backlog \
    code_resource_leak code_exception_swallow config_drift certificate_expiry \
  --modes text text_compact structured capsule full full_experience full_control \
  --output tests/results/reproduction

Windows 使用 .venv\Scripts\python.exe，并将 Bash 的反斜杠续行命令合并为一行，或改为 PowerShell 续行。运行结果及隔离数据保存在指定输出目录中。

离线复核已保存的真实结果

审计与汇总脚本仅需 Python 标准库，不调用模型，检查原始任务格、配对输入、记忆隔离、结果哈希、Provider usage 和汇总统计。以下 python 可替换为对应平台的虚拟环境解释器：

python src/scripts/audit_final_ablation.py tests/results/final-openeuler-seven-mode
python src/scripts/summarize_final_ablation.py \
  tests/results/final-openeuler-seven-mode/report.json \
  --output tests/results/final-openeuler-seven-mode

上述命令会更新实验包内的审计或汇总文件。需要重新绘图时，另行安装未列入核心依赖的 Matplotlib，再执行：

python -m pip install matplotlib
python src/scripts/plot_final_ablation.py tests/results/final-openeuler-seven-mode

重新运行真实模型批次（产生 API 费用）

在原生 openEuler 服务配置模型、完成回归和前端构建后，将验证日志保存为output/final-ablation/validation.log，确认含 VALIDATION_OK，并确保开放任务与固定轨均无排队或运行中的任务。以下入口会提交新的 560 个真实模型任务并产生 API 费用；使用新的输出目录，服务端模型和用量按实际返回记录：

.venv/bin/python src/scripts/run_final_ablation.py \
  --base-url http://127.0.0.1:8000 \
  --output output/final-ablation-reproduction

脚本冻结源码与模型配置，跟踪同一批次，不进行任务级重跑；若提交状态不明确，应先核对服务端记录再恢复跟踪。实验中的内部修复和质量不足样本均保留。

最终实验包保存了 openEuler 24.03 LTS-SP3 虚拟机的 960 项回归、前端生产构建和 3 项固定轨浏览器验收材料，以及八场景、十轮、七模式的 560 份完整任务记录。实验环境、源码指纹、统计方法、质量边界及负收益见最终实验包。这些记录对应包内保存的实测源码指纹；当前版本的检查和新的真实批次应各自保存实际条件。

已知限制

限制	实际影响
同主机运行时	SACP Pipe 和 SSC 共享内存用于同主机进程协作，当前未实现跨主机分布式通信；注册扩展能力不代表已完成任意 Agent 规模的性能验证
单 API 控制进程	任务管理、事件通知及 Worker 索引位于单一控制进程，必须使用 `--workers 1`；多 API worker 或横向扩容需要外部队列和共享任务协调
模型与缓存依赖	开放工作台需要配置真实 Responses API；本地确定性 Provider 只用于机制验证。BGE 索引需要完整嵌入依赖和冻结模型缓存，缺失缓存时不能完成真实向量索引
CodeAct 部署范围	完整支持路径为 Linux/openEuler 原生服务加本地 rootless Podman 和独立沙箱镜像；日常 Web 应用容器关闭 CodeAct，Windows 本地运行和浏览器夹具不能证明生产 OCI 隔离
本地访问边界	默认绑定回环地址，模型设置写入仅允许本机或符合检查的 SSH 隧道访问；当前原型不提供完整的公网多租户认证、授权与运营能力
文件类型和容量	上传支持 PDF 与白名单文本/源码格式，不直接支持 DOCX/XLSX/PPTX、压缩包或可执行文件；默认单文件 20 MiB、每批 20 个文件/100 MiB、每工作区 1 GiB、OCR 最多 50 页。容量可用环境变量调整，实际值以 `/api/open/health` 为准；扫描件 OCR 质量受原文影响
复用适用性	相似度不能单独授权复用；来源、模型配置、权限、上下文或有效期变化可能触发重算。开放资料没有专用字段读集时保守依赖完整输入，文件替换可能使整个工作区检查点失效
回答与实验边界	依赖验证、签名或执行成功不证明自然语言回答及任意 Python 方法的语义正确性。本批 560 个任务中，284 个未通过质量门控、4 个未通过事实门控；成本收益来自四角色、八场景、单模型和一次序列重复，B3/B0、B5/B3 的质量非劣门控未通过，不能外推为所有任务的质量或性能保证

目录结构

nexus-mas/
├─ README.md
├─ src/                         项目源代码与构建部署配置
│  ├─ backend/                  Runtime、SACP/SSC、记忆、评测、API 和协议定义
│  ├─ frontend/                 React/TypeScript 控制台
│  ├─ scripts/                  安装、启动、实验及 systemd 配置
│  ├─ Containerfile             openEuler SP3 主应用镜像
│  ├─ Containerfile.prebuilt     预构建前端的镜像入口
│  └─ CodeAct.Containerfile      独立 CodeAct 沙箱镜像
├─ docs/                        赛事要求的四份 PDF
│  ├─ 项目说明书.pdf
│  ├─ 项目创新说明.pdf
│  ├─ 成员分工及主要贡献说明.pdf
│  └─ 人工智能及第三方工具使用说明.pdf
├─ tests/                       测试及验证材料
│  ├─ backend/                  后端与安全回归
│  ├─ frontend/                 组件回归与 Playwright 验收
│  ├─ scripts/                  实验汇总脚本回归
│  ├─ validation/               CodeAct 动态验收与独立复核
│  └─ results/                  已保存的实验结果与环境记录
├─ demo/                        可验证 Web 原型的启动入口与说明
├─ presentation/                决赛现场演示 PPT 和决赛演示视频
│  ├─ 决赛现场演示PPT.pptx
│  └─ 决赛演示视频.mp4
└─ 作品原创承诺书.pdf

源码、测试及交付材料按上述目录归类。根目录另保留许可证、Git/容器忽略配置、环境变量示例和 pytest.ini 等构建与测试必要文件。历史实验结果保留原有内容、源码指纹及输入条件。

提交材料	位置与状态
项目说明书	PDF
项目创新说明	PDF
成员分工及主要贡献说明	PDF
人工智能及第三方工具使用说明	PDF
可验证交付物	演示启动与验收说明
决赛现场演示 PPT	决赛现场演示PPT.pptx
决赛演示视频	决赛演示视频.mp4
作品原创承诺书	PDF

验证材料导航

材料	内容
最终实验说明	环境、批次、原始证据与免费复核命令
最终实测报告	七模式计量、质量门控、归因与负收益
逐任务数据 / 场景汇总	560 个任务与 56 个场景×模式的分项测量
独立审计 / 实验计划	原始记录复核、配对与隔离、冻结配置与源码清单
测试及历史验证材料	测试材料入口及复现说明

License

本项目采用 Apache License 2.0。