智序（FlowMesh）

面向多智能体协作的低开销通信、状态传递与共享记忆机制。本仓库为操作系统开源创新大赛参赛作品的可运行实现与评测代码。

项目简介

多智能体系统若仅依赖自然语言往返传递上下文，往往面临上下文膨胀、状态易失真、过程难校验等问题。智序将机制层与场景层解耦：机制层提供结构化协议消息、活动状态图谱、非文本状态引用（StateRef）、上下文压缩与任务胶囊复用；场景层则以企业 IT 生命周期（入职 / 调岗）为样例，验证协议相对纯文本协作在上下文长度、Token 消耗与状态恢复方面的收益。

产品对外 Web 控制台标题为「智序」；代码包与仓库工程名仍使用 flowmesh。

应用场景

企业 IT 生命周期编排：员工入职开通账号、分配资产与权限，以及调岗时的权限增删与过程合规校验。
多 Agent 长流程协作：规划、执行、校验等多角色在同一任务图上接力，需要可控上下文与可恢复状态。
协议对比实验：同一批生成场景下对比自然语言（nl）与结构化协议（structured）的上下文字符、Token、耗时与状态恢复指标。

主要功能

能力	说明
结构化协议协作	Agent 通过协议动作与状态引用交互，减少整段自然语言回灌
活动状态图谱	维护 Goal / Step / Artifact / Constraint 等节点与依赖边，支持焦点投影
非文本状态传递	StateRef + 校验和，大块状态按引用读写而非全文复制
上下文压缩	非焦点节点摘要/归档，控制进入模型的上下文字符规模
任务胶囊复用	按指纹加权 Jaccard 匹配历史工作流模板（阈值 0.55），只注入步骤与验收规则
Web 演示控制台	`demo/web` 提供会话、图谱与指标展示
企业生命周期沙箱	本地 SQLite + FastAPI 模拟员工/资产/权限，不依赖外网业务系统
协议对比评测	`src/scripts/run_protocol_comparison.py` 批量跑 gen_001–gen_010

仓库结构

.
├── README.md
├── pyproject.toml
├── .env.example
├── src/                 # 源代码
│   ├── flowmesh/        # 协议、图谱、记忆、胶囊、状态库、运行时
│   ├── agents/          # Agent 角色与 LLM 客户端
│   ├── api/             # FastAPI 主服务
│   ├── benchmarks/      # 企业生命周期评测与场景
│   ├── baselines/       # 自然语言基线对照
│   ├── evaluation/      # 评测辅助
│   └── scripts/         # 安装、启动、自检与实验脚本
├── demo/
│   └── web/             # 前端静态页（由主服务挂载）
├── tests/               # pytest 测试
├── docs/                # 说明书、创新说明等文档
├── presentation/        # 答辩 PPT / 演示视频
└── data/                # 运行时数据与实验结果（默认不入库密钥）

系统环境

项目	要求
操作系统	推荐 openEuler 24.03（WSL 亦可）；其他 Linux 发行版一般可用
Python	≥ 3.11
包管理	`venv` + `pip`
可选	外接 OpenAI 兼容 / Anthropic 兼容 LLM 中转站（演示对话与正式协议对比需要）

离线自检（如 Phase 1 dry-run、部分契约测试）可不调用大模型。

依赖要求

核心依赖见 pyproject.toml，主要包括：

Web：fastapi、uvicorn
数据与配置：pydantic、pydantic-settings、python-dotenv、PyYAML、numpy、ijson
HTTP 客户端：httpx
开发测试（可选）：pytest、pytest-asyncio

LLM 密钥与服务地址通过环境变量配置（见 .env.example）。

构建 / 安装方法

在项目根目录执行：

cd /home/zhph/flowmesh          # 或你的本地克隆路径
bash src/scripts/setup.sh

脚本会：

创建 .venv（若不存在）
pip install -e ".[dev]" 以可编辑方式安装本包
若不存在 .env，则从 .env.example 复制一份

手动等价步骤：

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip setuptools wheel
pip install -e ".[dev]"
cp -n .env.example .env
# 编辑 .env，至少填写 DEEPSEEK_API_KEY（或其他兼容中转的密钥与 BASE_URL）

运行方法

1. 启动智序 Web 控制台（主界面）

cd /home/zhph/flowmesh
source .venv/bin/activate
bash src/scripts/run_server.sh

默认监听 http://0.0.0.0:8765（可用环境变量 FLOWMESH_HOST / FLOWMESH_PORT 修改）。浏览器访问本机对应端口即可使用演示界面。

2. 启动企业生命周期沙箱 API（可选）

bash src/scripts/run_sandbox.sh

默认端口 8766，用于本地模拟员工/工单/权限等 HTTP 接口，不连外网业务系统。

3. 离线 / 分阶段自检脚本

python3 src/scripts/verify_phase1.py
python3 src/scripts/verify_phase2.py
python3 src/scripts/generate_cases.py
python3 src/scripts/verify_phase3.py
python3 src/scripts/verify_phase4.py
python3 src/scripts/run_transition_experiment.py \
  --scenario src/benchmarks/enterprise_lifecycle/scenarios/generated/gen_001.yaml

4. 协议对比实验（调用真实模型，耗时与费用较高）

python3 src/scripts/run_protocol_comparison.py --formal --execute \
  --experiment-version v2 --repetitions 1 \
  --model <模型名> \
  --base-url <OpenAI兼容或对应格式的 Base URL> \
  --api-key-env <存放密钥的环境变量名>

结果默认写入：data/benchmarks/enterprise_lifecycle/protocol_comparison/。

测试方法

激活虚拟环境后，在项目根目录运行：

source .venv/bin/activate

# 全量单元 / 集成测试
pytest -q

# 常用子集示例
pytest tests/test_web_console.py tests/test_lifecycle_phase1.py -q
pytest tests/test_protocol_contracts.py tests/test_protocol_runner.py -q

测试覆盖协议契约、上下文压缩、批次评测 CLI、Web 静态资源路径、LLM 客户端多协议封装等。部分端到端实验测试依赖场景 YAML 与本地数据目录，请保持仓库内 src/benchmarks/.../scenarios/generated 完整。

已知限制

依赖外部 LLM：完整对话演示与跨模型协议对比需要可用的 API Key 与中转站；密钥未配置时部分路径会报错或只能跑离线 dry-run。
场景为评测样例：企业生命周期沙箱为可控模拟环境，不构成生产级 IAM / ITSM 对接。
胶囊复用边界：匹配只复用工作流步骤与验收规则，不保证跨实例员工号、资产号等业务主键可直接迁移；匹配阈值为 0.55。
大数据量实验体积大：data/benchmarks/.../protocol_comparison 下含多模型完整轨迹，提交或克隆前可按需裁剪，不影响核心源码运行。
前端为静态演示页：demo/web 由 FastAPI 挂载提供，非独立前端工程构建流水线。
过程校验针对评测契约：回合后校验面向生命周期基准中的权限/审批/版本规则，换场景需扩展校验器。

许可证与提交说明

参赛提交材料（说明书、创新说明、PPT、视频等）位于 docs/ 与 presentation/。