LatentCollab 2.1

LatentCollab 是一个多智能体低开销协作实验系统。Planner、Retriever、Executor 和 Summarizer 通过能力路由协作，可比较完整文本、结构化文本与 KV cache 非文本工作记忆三种通信方式，并提供联网检索、分层记忆、代码沙箱和消息审计功能。

快速开始

系统只在命令行中保留四种实验模式：

python -m src.main single
python -m src.main sequential
python -m src.main compare
python -m src.main ablation

不填写模式时，读取 config.yaml 中的 common.shared.experiment.mode：

python -m src.main

模型、设备、任务、运行轮数及模块开关都在 config.yaml 中设置。命令行实验模式具有最高优先级。

四种运行模式

single：单任务

读取任务文件中的第一个任务。该模式用于展示完整系统能力，默认启用：

latent KV cache通信；
动态能力路由；
联网检索；
分层共享记忆；
按任务需要触发的代码沙箱；
实时节点和消息进度。

这些功能可在 common.task 中调整。single与sequential除任务数量和记忆复用过程外，共用同一套执行参数。

sequential：连续任务

依次执行任务文件中的前两个任务。T1完成后产生的记忆可以被T2检索和复用，适合观察记忆命中、跳过不必要联网检索以及动态路由变化。整组运行开始前可清空旧记忆，但T1与T2之间不会清空。

实验臂、路由、联网和记忆配置同样位于 common.task。

动态拓扑具有强制起终点。默认 Planner 是起点，Summarizer 是终点； routing.max_agent_work: [2, 2, 2, 1] 按 agents 列表顺序限制每个节点在单个任务中的工作次数。每次非终点Agent只生成一次内容，随后由Orchestrator单独进行一次受限格式路由判断。到达终点立即结束；路由无效、无节点可用或其余额度耗尽时，系统强制进入保留的一次Summarizer收束机会。自定义Agent列表时必须同步明确填写 routing.start_agent、routing.end_agent 和等长的 routing.max_agent_work。

compare：通信方式对比

相同任务依次由三个实验臂执行：

实验臂	中间通信方式	Latent状态
`text`	完整自然语言文本	关闭
`structured`	紧凑结构化文本	关闭
`latent`	轻量控制消息和KV cache	开启

为了只比较通信方式，系统推荐执行以下控制条件：

固定 Planner → Retriever → Executor → Summarizer 路由；
关闭联网检索；
关闭共享记忆和Embedding模型；
固定三个实验臂；
三个臂使用相同模型、任务、沙箱设置和代码任务判断；
每个臂开始前恢复相同随机种子；
每个任务自动创建新的消息和latent上下文。

对比轮数、路由、联网检索和记忆开关均在 common.compare 中显式配置，正式对比建议至少10轮。如果用户修改实验臂、动态路由、联网或记忆等关键参数，系统会显示推荐值和用户值。确认后按用户需求执行；拒绝或未获得输入时采用上述推荐条件。

evaluation.memory_policy 决定记忆隔离方式：off 完全关闭， isolated_reset_each_round 为每个臂建立独立库且逐轮清空， isolated_accumulate 允许各臂在自己的库内跨轮积累， shared_readonly_snapshot 允许三个臂读取同一预置库但阻止写入和复用计数变化。实验臂顺序默认逐轮轮换，同一任务在各臂开始前恢复相同随机种子；任务分类也只计算一次并由各臂共用。

ablation：A—E消融实验

消融模式默认使用两个连续任务，并按控制变量法执行：

组别	协议	Latent	记忆	路由
A	text	关闭	关闭	固定
B	structured	关闭	关闭	固定

| C | structured | 开启 | 关闭 | 固定 | | D | structured | 开启 | 开启 | 固定 | | E | structured | 开启 | 开启 | 动态 |

全部组关闭联网检索并使用相同模型、任务顺序、采样参数、沙箱设置和代码任务判断。每组开始前恢复相同随机种子。D和E分别使用物理隔离的空记忆库：各组内部T2可以复用本组T1记忆，但不同组之间不会共享记忆。E组的Agent执行次数受 defaults.ablation.routing.max_agent_work 列表限制，列表顺序与 agents 一致。 defaults.ablation.evaluation.ablation_groups 调整组定义；该项属于关键默认参数，启动时必须确认后才会生效。

任务文件

默认读取根目录 tasks.txt：

# 开头的行是注释，不会成为任务；
每个非空文本行是一个独立任务；
空行会被忽略；
单独一行 - 用于分隔任务组；
single使用第一个任务；
sequential和ablation使用前两个任务；
compare使用文件中的全部任务；
文件不存在或没有有效任务时读取 common.shared.experiment.task_template。

任务应当是边界清楚、可以验证的具体问题，例如：

欧盟CBAM正式实施后，进口钢铁企业需要按季度提交哪些排放字段，直接排放和间接排放分别如何计算？
上述字段中哪些可以复用企业现有碳核算系统数据，哪些需要新增采集流程？

配置结构和优先级

根配置分为两类：

common：常用参数，建议用户按实验需要修改；
defaults：模型采样、latent、传输、沙箱和存储等底层参数，原则上不建议修改。

两类配置均按运行模式分组：

common.shared       所有模式常用参数
common.task         单任务与连续任务共用参数
common.compare      对比实验常用参数
common.ablation     消融实验常用参数

defaults.shared     所有模式底层默认参数
defaults.task       单任务与连续任务共用默认参数
defaults.compare    对比实验默认参数
defaults.ablation   消融实验默认参数

最终优先级为：

命令行实验模式
  > common对应组（single和sequential均对应task）
  > common.shared
  > defaults对应组
  > defaults.shared
  > 程序兜底值

compare和ablation会在配置合成后给出控制变量推荐值；用户确认关键修改后仍可采用自己的设置。每次运行都会把真正生效的配置保存为 effective_config.yaml。

关键参数确认

系统优先尊重用户明确需求，但会保护实验可比性和底层运行安全。以下修改会在启动组件前要求确认：

根配置 defaults 下的值与 src/config/default.yaml 不一致；
compare模式偏离固定路由、关闭联网、关闭记忆或固定三臂的推荐设计；
ablation模式开启联网、关闭记忆基础设施或修改A—E组定义。

提示会列出参数名、修改原因、推荐值和用户值：

参数: routing.mode
原因: 改变compare模式的控制变量
推荐值: 'fixed'
用户值: 'dynamic'
确认使用用户值？[y/N]:

输入 y、yes、是 或 确认 采用用户值；其它输入采用推荐值。非交互环境无法确认时也使用推荐值。确认结果和最终值会写入运行概要及 effective_config.yaml。

结果目录

common.shared.experiment.output_dir 是所有运行结果的统一根目录，默认值为 run。每次执行创建独立目录：

run/
└── compare_20260712_120000/
    ├── effective_config.yaml
    ├── terminal_output.log
    ├── summary.json
    ├── reply.md
    ├── comparison.json
    ├── audit_graph.json
    └── memory/

不同模式可能产生：

comparison.json：三臂逐轮明细和聚合指标；
ablation.json：A—E各组任务结果；
ablation_comparison.json：相邻消融组的逐任务配对差值和组内聚合；
web_search_snapshot.json：single或sequential实际联网时的搜索记录；
audit_graph.json：Agent消息、来源和信任域审计数据；
terminal_output.log：完整终端输出；
summary.json：面向程序的配置、指标与统计概要，不重复保存回答正文。
reply.md：按执行顺序保存原始问题及完整回答。

对照模式按“轮次—实验臂—任务”、消融模式按“轮次—消融组—任务”分隔输出。每个任务结束后立即打印完整 Answer；空答案打印 Answer: [EMPTY] 并将该任务标记失败。

离线模型准备

正式实验默认只从本地读取主模型和Embedding模型，避免运行过程中访问 HuggingFace。部署脚本和依赖位于 deploy/，系统设计说明见 docs/system_design.md。模型和数据应在部署阶段准备完成，实验运行阶段不执行自动更新。

资源管理使用独立入口，不增加实验命令参数：

python -m src.resources status   # 只读本地缓存并报告缺失项
python -m src.resources update   # 显式联网下载或更新全部模型
python -m src.resources verify   # 完全离线加载Tokenizer和Embedding模型

多进程与状态传输

将 defaults.shared.system.process_mode 设为 multiprocess 后，四类Agent分别拥有独立Worker进程。TASK/ACTION消息必须先进入对应Worker完成协议校验和业务准入，GPU 推理由线程安全的中央单模型服务串行执行，避免四份4B模型同时占用显存。结果中的 worker_trace 和 worker_directory 会记录PID及实际执行次数。Worker异常默认终止任务；只有明确把 worker_failure_policy 改为 local_fallback 才会回退本地路径。

非文本状态引用同时记录原始载荷、序列化字节、生产者、预期消费者、dtype、shape 以及创建/读取/确认/释放事件。SHM和Socket反序列化后会在模型调用前恢复到目标设备并校验KV层数与形状。latent.trim_prompt: true 会删除每个Agent新增的prompt KV，而非只处理第一个Agent。

记忆与评测口径

启用记忆时，系统按 plan → evidence → execution → conclusion 写入任务内父子链，记录来源消息、任务ID、有效状态和内容哈希；相同内容不会在多轮运行中无限重复写入。联网证据和沙箱执行结果分别保留外部来源及退出状态。

对比结果将“中间文本token减少”与“latent二进制状态字节”分开报告，并补充状态峰值、序列化体积、put/get耗时、模型调用次数、均值、标准差、中位数、P95、95% 置信区间和配对时延差。中间文本减少100%不等同于总体通信开销减少100%。

验证

测试与功能展示文件位于 validation/，说明见 validation/tips.md。

pytest validation -q
python validation/demo_cross_process.py  # Linux/openEuler/WSL2