赛题作品说明（competition）

作品名称： 面向多智能体协作的低开销通信、状态传递与共享记忆机制
业务锚点： 项目管理系统（PMS）智慧园区分包结算 → 预算校验 → 付款资金协同
参赛团队： 开心向前飞队
赛题方向： 多智能体协作基础设施（协议 / 状态传递 / 共享记忆）

本目录 competition/ 是可独立演示与评测的赛题实现单元：不依赖 PMS 前端页面，可在 Windows / Linux / openEuler 24.03-LTS-SP3 上单独运行。评测脚本 不强制 LLM API Key；PMS Java 后端不可用时自动回退内置 mock 数据。

1. 作品简介

1.1 要解决什么问题

多智能体系统在规划、检索、执行、总结等角色分工时，主流框架常以自然语言或长 JSON作为 Agent 间通信媒介，带来三类系统层瓶颈：

问题	表现
通信开销高	历史上下文与业务对象反复写入消息，Token 随任务链线性膨胀
状态传递笨重	大对象在「状态 → 文本 → 状态」间反复序列化，抬升时延与冗余
经验难复用	跨任务结论缺少结构化沉淀，相似任务被迫重复计算

本作品将研究重心放在协作基础设施，而非单纯增强模型能力，提出并实现：

PMS-ACP 结构化通信协议：标准化消息字段替代长文本透传
State Reference 非文本状态交换：大对象以 state_ref 引用传递
共享记忆组织机制：跨任务沉淀摘要、证据与业务结论并检索复用
双模式 Benchmark：同一任务链下对比 Structured vs Plain Text，量化 Token / 命中 / 时延

1.2 为什么选 PMS 项管场景

项目管理系统（PMS）天然具备多域、多单据、强规则校验特征：采购合同、项目预算、分包结算、财务资金计划分属不同业务域，却在真实交付中必须串联。用「分包结算是否超预算 → 再申请付款是否够资金」这一连续链路，可以同时验证：

协议开销：结算单 / 预算表等大对象是否还需要整份塞进消息
状态引用：Retriever → Executor 是否只传引用 ID
记忆复用：任务 B 是否真正命中任务 A 沉淀的结论（可观测、可证伪）

业务数据对齐仓库内 PMS 智慧园区样例项目（项目编码 PP2026000001、合同 PC2026000001）。

2. 项管业务背景（PMS）

2.1 PMS 在本作品中的定位

PMS（Project Management System，项目管理系统）覆盖智慧园区类工程项目的采购—项目—财务协同。本赛题不展开完整 ERP，只抽取与多智能体协作强相关的一条真实业务链：

采购合同签订
    │
    ▼
分包结算申报（本期结算金额）
    │
    ▼
对照项目分包预算 / 成本限额（是否超预算）
    │
    ▼
写入/沉淀校验结论（可供后续任务复用）
    │
    ▼
分包付款申请（本月拟付金额）
    │
    ▼
对照财务资金计划剩余额度（是否够付）

2.2 关键业务对象

演示与评测使用的样例数据定义在 competition/tasks.py，含义如下：

对象	样例主键 / 字段	业务含义
项目	`PP2026000001` · 智慧园区数字化平台	成本与预算归集主体
分包采购合同	`PC2026000001` · 系统集成分包采购合同	供应商：中交星宇科技；合同额 200 万；履约中
分包结算单	`DXJX20260605105142826`	本期结算含税金额 30 万；成本限额 200 万
预算执行	分包成本限额 200 万；累计已结算 30 万；预算余额 170 万	判断「还能不能再结」
资金计划	`ZJ2026000001` · 计划月 2026-07	计划 50 万、已用 0、剩余 50 万

金额单位均为万元（与 mock / 校验规则一致）。

2.3 业务校验规则（可人工核验）

任务组 A — 分包结算预算校验

输入：本期结算金额 settlement_amount = 30
规则：结算金额 ≤ 成本限额 − 累计已结算（即 ≤ 预算余额）
样例：30 ≤ 200 − 30 = 170 → 通过（ready: true）

任务组 B — 分包付款资金校验

输入：拟付款金额 payment_amount = 20，月份 2026-07
规则：付款金额 ≤ 本月资金计划剩余
样例：20 ≤ 50 → 通过
协作约束：B 声明 reuse_memory_topic = subcontract_settlement_validate，优先检索 A 的结论记忆；命中后摘要可出现「记忆复用」类标记，memory_hit_count 可统计

2.4 多域能力映射

Agent 能力按业务域发现与路由，对应项管真实分工：

域	典型 capability	业务含义
procurement（采购）	合同 / 结算单据检索	取分包合同、结算单
project（项目）	预算执行检索	取分包成本限额与累计结算
finance（财务）	资金计划检索	取本月计划与剩余额度

四角色 Agent（Planner / Retriever / Executor / Summarizer）无状态，上下文由编排器注入；Planner 只编排 capability 名，Retriever 按后缀路由取数。

2.5 数据源策略

competition/datasource.py 实现 PmsDataSource：

优先请求 PMS Java 后端（默认 PMS_API_BASE_URL，如 http://localhost:8081）
HTTP / 业务码失败或空结果时，静默回退到 tasks.py 中的 mock
保证离线、答辩现场、openEuler 环境均可一键跑通 demo / benchmark

可用 python -m competition.run probe 探测后端是否连通。

3. 赛题任务设计

任务定义见 competition/task_groups.py。

3.1 任务组 A：分包结算预算校验

项	值
`group_id`	`group_a`
`task_type`	`subcontract_settlement_validate`
名称	分包结算预算校验
关键参数	`project_code=PP2026000001`，`document_no=DXJX…`，`settlement_amount=30`，`contract_no=PC2026000001`

结构化模式下典型步骤：取结算 → 取预算执行 → 规则校验 → 总结并按 task_topic 写入共享记忆。

3.2 任务组 B：分包付款资金校验（关联复用）

项	值
`group_id`	`group_b`
`task_type`	`subcontract_payment_apply`
名称	分包付款资金校验
关键参数	`payment_amount=20`，`payment_month=2026-07`，`reuse_memory_topic=subcontract_settlement_validate`

B 强制依赖 A 的主题记忆：用于证明跨任务共享记忆真实生效，而不是两次互不相干的独立任务。

3.3 演示命令

# 连续执行 A → B（结构化模式）
python -m competition.run demo

# 单任务 / 指定模式
python -m competition.run task -t subcontract_settlement_validate -m structured
python -m competition.run task -t subcontract_payment_apply -m text

4. 核心机制

4.1 PMS-ACP 结构化通信

统一 AgentMessage schema，以 mode 切换载荷语义：

模式	行为
structured	紧凑字段：`action` / `capability` / `params` / `summary` + `state_ref` / `memory_refs`；`text_payload` 为空
text	完整业务 JSON 写入 `text_payload`，模拟传统多 Agent「互抄全文」

同一 Orchestrator、同一任务定义与校验规则，保证：业务结论一致，仅通信开销可对照。

4.2 state_ref 与共享记忆的边界

机制	作用域	典型路径	解决什么
state_ref	单次 trace 内步骤间	Retriever → Executor	大对象重复序列化
Shared Memory	跨 trace / 跨任务	A 结论 → B 检索	相似任务重复计算

评测分别统计 vector_pass_count 与 memory_hit_count，避免两种机制边界混淆。

4.3 四角色协同

CLI / HTTP
    → Orchestrator
        → Planner（拆步骤）
        → Retriever（取数 + 写 state_ref / 记忆）
        → Executor（读引用 / 解析载荷 + 规则校验）
        → Summarizer（结论 + 主题持久化）
    ← MetricsCollector（token / 命中 / 时延）

5. 目录结构与代码边界

5.1 competition 目录

competition/
├── README.md              # 本文件（提交说明）
├── run.py                 # CLI：handshake / demo / benchmark / probe …
├── benchmark.py           # 双模式对照基准
├── task_groups.py         # 任务组 A / B 定义
├── tasks.py               # 校验规则 + mock 业务数据
├── datasource.py          # PMS API 客户端（失败回退 mock）
├── ask.py                 # 辅助问答入口（如有）
├── results/               # 评测输出（如 benchmark-10.json）
├── scripts/               # 打包脚本
└── docs/                  # 设计文档、实验报告、演示 PPT
    ├── 00-学习导读.md
    ├── 01-系统架构.md
    ├── 02-结构化通信协议.md
    ├── 03-状态传递与共享记忆.md
    ├── 04-实验与评测指南.md
    ├── 05-openEuler部署.md
    ├── 06-demo答辩讲解稿.md
    ├── experiment-report.md
    ├── 作品设计书.md
    └── figures/           # 架构图 / 时序图 / 指标图

5.2 与主工程模块关系

运行时依赖 pms-agent/app/ 中的自研协作栈（随仓库一并提交）：

模块	路径	说明
协议 PMS-ACP	`app/protocol/`	消息模型、握手、能力发现
四角色 Agent	`app/runtime/agents/`	Planner / Retriever / Executor / Summarizer
编排器	`app/runtime/orchestrator.py`	多步调度、双模式
向量状态交换	`app/state/exchange.py`	embedding + `state_ref`
共享记忆	`app/memory/store.py`	SQLite + 主题 / 标签 / 语义检索
赛题业务层	`competition/`	任务、数据源、评测 CLI

原创边界： 协议、编排、状态交换、共享记忆、Benchmark 与 A→B 任务链为团队自研；FastAPI / Pydantic / Embedding / SQLite / httpx 等仅作基础运行支撑。

6. 环境与快速开始

6.1 环境要求

Python **3.9+**（推荐 3.11）
操作系统：Windows 10/11、通用 Linux，或 openEuler 24.03-LTS-SP3
可选：本机 PMS Java 后端（默认端口示例 8081）

6.2 安装

在 pms-agent 根目录执行：

cd pms-agent
python3 -m venv .venv

# Linux / openEuler
source .venv/bin/activate
# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

pip install -r requirements.txt
# 国内镜像示例：
# pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

可选配置：

cp .env.example .env
# PMS_API_BASE_URL=http://127.0.0.1:8081

不启动 Java 后端亦可完整跑通；数据源将自动使用 mock。

6.3 一键验证（评测最小路径）

# 0）可选：探测后端
python -m competition.run probe

# 1）握手：应看到 4 个 Agent 已注册
python -m competition.run handshake

# 2）演示：任务组 A → B（结算校验 + 付款校验与记忆复用）
python -m competition.run demo

# 3）基准：结构化 vs 纯文本，默认建议 10 轮
python -m competition.run benchmark -n 10

# 保存结果到文件
python -m competition.run benchmark -n 10 --save competition/results/benchmark-10.json

Windows 也可使用：competition\run_competition.bat（若已提供）。

6.4 其它子命令

python -m competition.run discover --domain finance
python -m competition.run task -t subcontract_settlement_validate -m structured

7. 评测指标与实测结果

7.1 指标含义

指标	含义
`message_count`	Agent 间消息条数
`estimated_tokens`	估算 Token（structured 计紧凑字段与引用；text 计完整载荷）
`vector_pass_count`	非文本 `state_ref` 传递次数
`memory_hit_count`	共享记忆检索命中次数
`elapsed_ms`	耗时

7.2 Windows 实测摘要（10 轮，见 `results/benchmark-10.json`）

模式	累计 estimated_tokens	vector_pass	memory_hit
structured	8335	20	25
text	14600	0	25

对比项	结果
Token 节省	约 42.91%
记忆命中	双模式均为 25（记忆机制与协议模式正交）
向量引用	仅 structured 生效，证明非文本通道真实工作

说明：本地 structured 时延可能略高于 text，主因是 embedding 计算；主评测口径看通信载荷（Token）与机制计数，业务结论（结算 / 付款是否通过）在双模式下保持一致。

在 openEuler 上请复跑 benchmark -n 10，用新 JSON 覆盖或附录到实验报告。

8. HTTP API（可选）

uvicorn app.main:app --host 0.0.0.0 --port 8090

常用接口示例：

curl http://127.0.0.1:8090/competition/health
curl -X POST "http://127.0.0.1:8090/competition/benchmark?rounds=10"

（具体路径以 app/main.py 中 competition 路由为准。）

9. openEuler 部署要点

赛题要求最终代码可在 openEuler 24.03-LTS-SP3 编译、运行与测试。摘要步骤：

sudo dnf install -y python3 python3-pip python3-devel git sqlite
cd pms-agent
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

python3 -m competition.run handshake
python3 -m competition.run demo
python3 -m competition.run benchmark -n 10

详细步骤与排错见 docs/05-openEuler部署.md。

运行后可检查本地库文件（路径以配置为准），例如：

ls -la data/memory/shared_memory.db
ls -la data/state/state_vectors.db

10. 文档索引

文档	内容
docs/00-学习导读.md	阅读顺序与模块导览
docs/01-系统架构.md	分层架构与 A/B 时序
docs/02-结构化通信协议.md	PMS-ACP 字段与模式
docs/03-状态传递与共享记忆.md	state_ref / SharedMemory
docs/04-实验与评测指南.md	评测步骤与读数口径
docs/05-openEuler部署.md	目标系统部署
docs/06-demo答辩讲解稿.md	口头讲解提纲
docs/experiment-report.md	实验报告模板与结果
docs/作品设计书.md	正式设计书正文
docs/figures/	架构图、时序图、指标图源文件

一句话总结

本作品在 PMS 智慧园区分包结算与付款 真实业务链上，用 结构化协议 + 状态引用 + 共享记忆 降低多智能体协作开销，并以 双模式 10 轮基准 给出可复现的 Token / 命中 / 引用证据；业务结论可人工按预算与资金计划规则核验，机制收益可按指标拆分证伪。