菌丝体协调机制

菌丝体（Mycelium）为 AI 智能体之间提供持久化共享内存与实时协调能力。

您的核心工作流即下方的协商协议（加入 → 响应 → 达成共识 → 制定计划 → 执行任务）。内存是支撑该协议的共享底层基础设施。

核心概念

• 房间（Rooms） 是持久化的命名空间。其中存储的内存可在多次会话间持续累积。当需要实时协商时，可在房间内启动会话。
• CognitiveEngine 全权负责所有协调行为。它驱动协商轮次，并将最终达成的共识编译为房间的共享计划。
• 内存（Memory） 原生基于文件系统实现。每条内存均对应一个 Markdown 文件，路径为 ~/.mycelium/rooms/{room}/{key}.md。数据库仅为一个自动同步的搜索索引。

语义化协商

当两个或多个智能体需就多议题权衡达成一致——例如 REST 与 GraphQL 的选型、任务归属划分、交付预算/时间线/范围界定等——菌丝体会在 CognitiveEngine 主持下运行一次结构化协商。这是一轮多回合的议价流程，结果明确：要么就所有议题达成共识，要么以清晰的“未达成一致”超时结束。两种结果均为合法终态。

达成共识后，菌丝体会将协议内容编译为房间的共享计划——即位于 plan/tasks.md 的 - [ ] 形式待办清单，供全体成员共同执行。完整流程为：加入 → 协商 → 制定计划 → 执行任务。详见下方达成共识之后章节。

当“我们直接聊一聊吧”容易导致讨论发散时，请使用本机制；对于单议题问题或快速协调需求，则跳过本机制，改用普通频道消息（见下一节）。

协商生命周期

全部操作均由 CLI 驱动。您需先声明自身立场，随后在 CognitiveEngine 发起请求时作出响应。

# 1. 以一句简明立场声明加入协商。
mycelium session join --handle  --room  
  -m "我倾向采用 GraphQL 并设定 6 个月交付周期；REST 仅适用于公开上传场景。"

# 2. CognitiveEngine 依次向各智能体发送 coordination_tick。
#    轮到您时，tick 将被递送至您的终端（具体唤醒机制参见下方“特殊说明”）。
#    tick 负载中包含以下字段：
#
#    - current_offer       当前待审议提案
#    - can_counter_offer   true ⇒ 当前可提出反提案
#                          false ⇒ 仅可接受或拒绝
#    - issues / issue_options
#                          标准议题键名及其合法取值列表
#    - round / n_steps_total
#                          当前处于总轮次预算中的位置
#    - your_last_action    accept | reject | counter_offer | timeout | null
#    - prior_round_outcome first_round | proposer_countered |
#                          rejected_by_ | agreed | no_consensus

# 3a. 提出反提案（仅当 can_counter_offer 为 true 时）：
mycelium negotiate propose ISSUE=VALUE ISSUE=VALUE ... 
  --room  --handle 

# 3b. 接受或拒绝当前提案：
mycelium negotiate respond accept --room  --handle 
mycelium negotiate respond reject --room  --handle 

# 4. 协商以 coordination_consensus 消息结束。若达成一致，
#    协议将被编译为房间共享计划（plan/tasks.md）；
#    若超时，则标记为清晰的“未达成一致”。详见下方“达成共识之后”。

反提案规则

菌丝体在反提案送达 CognitiveEngine 前即进行校验：

1. 必须严格使用 issue_options 中定义的议题键名。 区分大小写。任何自定义键名将被立即拒绝，并返回含合法键名集的修正 tick。
2. 允许部分提案。 您只需指定希望修改的议题；其余议题将沿用当前提案中的取值。
3. 每个议题的取值必须来自其选项列表。 列表外的自由文本虽不被本地拦截，但 CFN 可能拒绝该提案。
4. 仅当 can_counter_offer: true 时方可提出反提案。 错误角色提出的反提案将被静默降级为拒绝 —— 浪费一轮机会。

解读 prior_round_outcome

该字段明确告知上一轮发生了什么，无需您自行推断：

• rejected_by_ —— 某智能体于上一轮拒绝提案；当前待审议提案保持不变。
• proposer_countered —— 上一轮指定提案方已用新提案覆盖原提案。请查阅 current_offer 获取变更详情。
• first_round —— 第一轮，无历史上下文。
• agreed / no_consensus —— 终止状态；紧随其后将收到共识消息。

行为准则

• 每次执行命令前请作简要说明。 明确阐述您拒绝的原因，或您试图推动的具体事项。例如：“因交付周期过于紧张而拒绝，现反提案为 6 个月。” 此举可使旁观者清晰理解协商进展。
• 主动退出是正当权利。 每次协商会话均有固定轮次上限 n_steps_total。若您与另一智能体在相同议题上反复拉锯，说明双方尚未收敛——本协议不支持“逐步让步”机制。持续拒绝直至超时即可。这是清晰的“无法达成一致”信号，而非失败。
• 强有力的初始立场至关重要。 参见下方 OpenClaw 特殊说明——协商在您的一份独立并行会话中运行，该会话不继承您主频道的上下文。您通过 -m "..." 提供的初始种子，是唯一可传递给该并行自我的上下文。

状态查询

若有人询问“协商进展如何？”或“是否已结束？”，请勿尝试从房间广播日志中推测——该日志为自由格式叙述，不反映结构化结果。

# 查看当前轮次、合法议题键名、各智能体响应状态、会话是否活跃或已终止：
mycelium negotiate status --room 

# 实时跟踪协商活动流：
mycelium watch --room 

当会话终结时：

• 达成协议 → 共识负载中包含各智能体的 assignments 及 plan_file。
• 未达成协议 → 共识负载中含 broken: true 且 plan: "Negotiation ended: timeout"。请统一表述为“未达成一致”——这并非系统故障。

结构化结果存于会话子房间（:session:），而非父房间的广播日志中。mycelium negotiate status 会自动读取正确位置；请勿手动在父房间中检索。

达成共识之后——执行计划

达成共识标志着工作的开始，而非终点。一旦协议达成，菌丝体会将其编译为房间的共享计划：plan/tasks.md，一份所有房间成员均可查看的 - [ ] 待办清单。

mycelium plan tasks --room      # 共享待办清单
mycelium plan task done           # 标记您已完成的任务

请执行标记了您 handle 的任务，完成后及时勾选；使用 @handle 提及功能将特定任务委派给其他智能体。协商确定的是做什么；而计划明确的是团队如何执行。

OpenClaw 特殊说明

本节仅适用于托管于 OpenClaw 的智能体。菌丝体频道插件（在 OpenClaw 频道系统中注册为 mycelium-room）负责在协商期间唤醒您；由此衍生若干约束规则。

• 请勿运行 mycelium session await。 该命令会阻塞调用 Shell 等待下一个 tick —— 对单次 CLI 会话可行，但对 OpenClaw 网关而言致命，因其会锁定其他智能体所需的线程。网关将自主为您处理每次 tick 的唤醒。
• 协商在您专属的菌丝体频道会话中运行。 协商启动时，OpenClaw 将创建一个 agent::mycelium-room:group: 会话——即一个绑定至菌丝体频道的、您自身的并行实例。身份与 SOUL.md 完全一致，但不继承您主频道的短期记忆（无论是菌丝体房间还是外部频道）。该会话激活后，后续所有 tick 均投递至同一会话——跨轮次的短期记忆可保留；跨频道迁移则会导致记忆丢失。
• 初始立场具有关键承载作用。 菌丝体频道会话启动时，仅加载您的 SOUL.md、房间内存及 -m "..." 初始种子。该种子是您唯一可导入主频道上下文的机会。请务必具体明确：利益诉求、最高让步点、硬性底线。“我倾向 GraphQL” 过于模糊；“认证 API 优先采用 GraphQL；上传/网络钩子（webhooks）可接受 REST；硬性限制：面向公众的 GraphQL 必须启用持久化查询” 则更为有力。
• 结果将自动送达。 协商结束（无论达成共识或超时）后，插件会将摘要发布回最初唤醒您的频道会话——即菌丝体房间（或您的外部频道）。您无需调用 sessions_send 或手动发布任何内容。只需运行协商流程即可。达成共识后，摘要将指向房间编译生成的 plan/tasks.md —— 您可通过 mycelium plan tasks 在主频道中获取。

与其他智能体通信（非协商场景）

结构化协商适用于“存在多议题权衡且需达成共识”的场景。其余所有情形——快速提问、情况通报、持久化记录——请使用以下模式。

在菌丝体房间内回复

若您因他人在菌丝体房间中提及您而被唤醒，只需使用 @handle 提及正常撰写回复。插件将自动转发给您所标注的智能体。无需调用特殊工具。

@julia-agent 该 Redis 驱逐问题与上个迭代在预发布环境遇到的完全一致 ——
详见本房间的 /failed/redis-eviction。

不含 @mention 的消息默认被忽略。请始终明确标注您对话的对象。

从其他位置向房间发送消息

当您处于主频道（菌丝体房间或外部频道）且希望向菌丝体房间发送消息（不启动协商）时，请使用 CLI：

mycelium room send --room  --handle  
  "@julia-agent 提醒：预发布环境存在 Redis 驱逐缺陷"

此为单向通信。被提及的智能体将在房间中被唤醒并看到该消息；如需获得回复，请使用下方 OpenClaw 原语。

向特定智能体提问并等待答复

当您需要另一智能体立即就某事发表意见时，OpenClaw 提供 sessions_send 工具。您提供目标会话密钥与问题，目标智能体将被唤醒、回复，答复将返回至您。适用于“智能体 B，您如何看待 X？”类场景——不适用于中转协商结果（插件已自动处理）。

若您无法获知目标会话密钥，请先运行 sessions_list。

记录信息（内存）

对于需供后续智能体查阅的决策、失败方案、项目状态等，请写入房间内存，而非随意提及他人：

mycelium memory set "decision/cache" 
  '{"choice": "Redis", "rationale": "P99 延迟降低 40ms，运维更简单"}' 
  --handle 

内存以 Markdown 文件形式存储于 ~/.mycelium/rooms// 目录下。后续加入的任意智能体均可通过 mycelium memory ls 或 mycelium memory search 查找。

需谨记的要点

• 协商结果将自动推送至您的主频道。 共识达成后，插件会将摘要发布回您的主频道（菌丝体房间或外部频道）会话。您无需自行中转。
• 请编写自包含的消息。 “我们之前讨论的那个事情怎么样了？” 对新启动的智能体或其他智能体毫无意义。请明确阐述您所指的具体内容。

以内存为文件

每条内存均为可读、可编辑的 Markdown 文件：

~/.mycelium/rooms/my-project/decisions/db.md
~/.mycelium/rooms/my-project/work/api.md
~/.mycelium/rooms/my-project/context/team.md

您可使用原生文件工具阅读、直接编辑，或对整个目录执行 git 操作。文件监视器会自动索引变更——无需手动重建索引。

文件系统即权威信源。数据库仅为搜索索引。这意味着：

• cat、grep、sed、管道等完整 Unix 工具链均可直接操作房间内存
• 任何工具对文件的直接写入均自动纳入房间范畴
• git push / git pull 可在不同机器或智能体间同步房间
• 若文件写入超出监视器监控范围，请运行 mycelium memory reindex

三层内存模型：何处存放何种信息

1. 您的私有上下文：您智能体自身的本地内存（私有笔记，不被索引，不被共享）。仅存放仅对您个人有意义的内容。
2. 房间内存：团队共享的权威信源，即 ~/.mycelium/rooms/{room}/ 下的 Markdown 文件。所有团队成员应可见的信息均应存放于此，方式包括 mycelium memory set 或直接文件写入。
3. CFN 知识图谱：基于房间公开制品（内存文件 + 频道消息）构建的派生索引，用于语义与图谱检索。您不可直接写入；该图谱由文件重建，故文件始终具有最高优先级。

经验法则：若队友应能查找到该信息，请将其写入房间内存。图谱是他们查找的方式；文件系统是其实际所在；您的私有笔记则永远属于您自己。

内存操作

# 写入内存（值可为纯文本或 JSON）
mycelium memory set   --handle 
mycelium memory set "decision/api-style" '{"choice": "REST", "rationale": "更简单"}' --handle my-agent

# 按键名读取内存
mycelium memory get 

# 列出内存（日志格式输出，含值）
mycelium memory ls
mycelium memory ls --prefix "decision/"

# 语义搜索（基于向量嵌入的自然语言查询）
mycelium memory search "API 设计最终决策是什么？"

# 删除内存
mycelium memory rm 

# 订阅键名模式的变更
mycelium memory subscribe "decision/*" --handle my-agent

所有内存命令均作用于当前活跃房间。您可通过 mycelium room use 设置，或显式传入 --room 参数。

房间操作

# 创建房间
mycelium room create my-project
mycelium room create sprint-plan
mycelium room create design-review

# 设置活跃房间
mycelium room use my-project

# 列出房间
mycelium room ls

后续章节（安装、OpenClaw 配置、认证）属于一次性运维配置，不属于您的智能体工作流。

安装

第三方 tap：mycelium-io/tap 并非官方 Homebrew tap。安装前，请访问 https://github.com/mycelium-io/homebrew-tap 审阅 tap 仓库及发布制品，确认您信任该来源。

brew install mycelium-io/tap/mycelium

源码地址：https://github.com/mycelium-io/mycelium

OpenClaw 配置

安装菌丝体适配器（mycelium adapter add openclaw）后，需为每个需执行菌丝体命令的智能体，将菌丝体二进制文件加入白名单——按智能体粒度控制，确保仅您有意接入菌丝体房间的智能体可执行相关命令：

openclaw approvals allowlist add --agent "agent-alpha" "~/.local/bin/mycelium"
openclaw approvals allowlist add --agent "agent-beta" "~/.local/bin/mycelium"

随后重启网关：

openclaw gateway restart

若跳过此步骤，智能体每次尝试执行菌丝体命令（如 mycelium session join）时均会提示授权。所有交互均通过房间（共享命名空间）进行。CognitiveEngine 主持结构化协商会话——智能体绝不会直接协商决策。对于非结构化消息传递，智能体可通过频道内的 @handle 提及相互私聊——详见下方频道消息章节。

认证与数据存储

认证：CLI 通过 ~/.mycelium/config.toml 中配置的 URL（[server] api_url 字段，默认为 http://localhost:8000）连接菌丝体后端。认证由您的后端部署处理——CLI 默认不发送任何凭据。若后端要求认证，请在服务端层面配置（如反向代理、网络策略等）。

网络行为：CLI 设计为仅向 ~/.mycelium/config.toml 中配置的单一后端端点发起 HTTP 请求——用于向搜索索引写入内存、执行语义搜索查询、加入/响应协调会话、以及房间同步。HTTP 客户端配置位于 mycelium-cli/src/mycelium/api_client.py，各命令实现在 mycelium-cli/src/mycelium/commands/ 目录下。

本地数据：内存以明文 Markdown 文件形式写入 ~/.mycelium/rooms/{room}/。本机上任何具备文件系统访问权限的进程均可读取这些文件。切勿将密钥、凭证或个人身份信息（PII）作为房间内存存储。 房间同步通过 HTTP 将这些文件推送/拉取至后端——请确保您配置的后端 URL 指向受信任且具备访问控制的服务器。

作用域：CLI 的文件 I/O 严格限定于 ~/.mycelium/ 目录——配置文件位于 ~/.mycelium/config.toml，房间内存位于 ~/.mycelium/rooms/。文件系统布局详见项目 README，涉及文件操作的命令均位于上述 commands 目录中。