打破学科壁垒，扩展认知边界
Breaking down disciplinary barriers, expanding cognitive boundaries

项目定位 • 差异对比 • 功能特性 • 快速开始 • 文档 • API 概览 • 贡献 • English

在复杂科研与项目协作中，真正的瓶颈往往不是信息不足， 而是团队成员之间的认知无法持续同步。

传统协作依赖文档与会议完成信息传递，但随着知识复杂度提升， “理解是否一致”逐渐成为推进效率的核心限制。

Resonnet 是一个面向受控协作场景的认知对齐基础设施。 它通过多 Agent 编排，让角色理解、讨论过程与决策依据能够被持续对齐、审查与追溯， 将协作从「文档同步」升级为 A2A 高带宽认知对齐。

Resonnet 的定位是：面向受控协作场景的多 Agent 讨论后端。
Resonnet 假设真实协作需要治理结构与责任边界，AI 的角色不是自由行动，而是参与重点解决受控的认知对齐流程「如何把多角色 AI 讨论做得可控、可追溯、可集成」，而非追求开放式 AI 社交或完全自治。

很多协作系统在解决“信息怎么存/怎么传”，而 Resonnet 更关注两个更难的问题：

• 认知对齐：Resonnet 的核心假设是：协作效率的瓶颈，正在从信息传递问题转变为认知同步问题。因此希望能让“理解与经验”能在 人 → AI → AI ↔ AI → 人 的链路里按需问答式同步，而不是靠文档全量同步

flowchart LR
    H1["人 A"] -->|"注入背景/偏好"| A1["A 的 AI"]
    H2["人 B"] -->|"注入背景/偏好"| A2["B 的 AI"]
    A1 <-->|"高带宽问答<br/>in-context 对齐"| A2
    A1 -->|"结论/建议"| H1
    A2 -->|"共识/行动"| H2

• 产物审查：让任务产出在交付前可被多轮预审、对齐与追溯，而不是一次性交付后再返工

flowchart LR
    L["负责人/评审者"] <--> A0["AI（代表其认知）"]
    A0 -->|"下发任务+验收标准"| A1["执行者的 AI"]
    A1 -->|"协同产出"| H["执行者"]
    H -->|"提交产物"| A1
    A1 -->|"产物+依据"| A0
    A0 -->|"预审/对齐"| A1
    A0 -->|"通过/结论"| L

人的信息传递主要有两种方式：

引入 AI 作为认知对齐桥梁：AI 吸收结构化信息、理解角色分工，开展高带宽问答，在人与人间形成认知闭环——既保留结构化信息的高密度，又获得对话式对齐的效率。AI 不再只是工具执行者，而成为团队认知的代理层，在不同角色之间承担理解、对齐与推理的中介。

Resonnet = Resonance + Network，对应长期方向：通过持续的认知对齐，逐步形成人机共存的共鸣网络。

• 理想方向：人 → AI → AI ↔ AI → 人 的认知闭环，基于文档与角色分工开展 A2A 高带宽问答
• 当前重点：先把受控协作做好（流程治理、可追溯、可审计、可集成），再逐步扩展灵活性
• 面向场景：科研项目研讨、评审协作、企业协同与进度对齐
• 核心价值：认知对齐效率提升、流程可控（主持人/讨论轮次）、结果可追溯（workspace 产物）、接口可集成（REST API）
• 工程边界：以 topic/workspace 为中心编排，不以「自治 Agent 社交网络」为目标

一句话：Resonnet 不是“让 Agent 自由社交”，而是“把多 Agent 协作做成可治理的认知对齐后端”。

围绕认知对齐与受控协作，提供：

• Multi-agent orchestration：多专家回合讨论（Discussion）、主持人模式切换
• Topic workspace isolation：话题级工作区、并发锁
• Expert & moderator generation：AI 生成专家角色定义、主持人提示词
• @mention reply：帖子中 @专家 触发异步 AI 回复
• MCP 工具扩展：讨论时可选择 MCP 服务器（time、fetch 等），传入 Agent SDK 供调用
• REST API：Topics、Posts、Experts、Moderator Modes、MCP 等完整 CRUD

首个基于此后端的场景参考实现：Tashan-TopicLab。

• 场景：面向科研协作网络（可链接一群陌生研究者），围绕话题研讨与需求对齐；支持多轮专家圆桌、跟贴追问与 @专家 交互
• 价值：协作往往跨机构、跨角色、跨时间推进；仅靠会议/异步沟通难以把细节同步到位且成本高。期望产出对齐后的共识、清晰的需求、可执行的下一步计划；最终获得更少的反复沟通、更快的决策推进，并把文档信息沉淀为团队可复用的共识

# 1. 克隆并安装（将 YOUR_ORG 替换为实际 GitHub 组织/用户名）
git clone https://github.com/YOUR_ORG/resonnet.git && cd resonnet
uv sync   # 或 pip install -e ".[dev]"

# 2. 配置环境变量（复制模板后补齐）
cp .env.example .env
# 当 backend 作为 submodule 时，也可将 .env 放在项目根目录；backend 优先加载项目根 .env
# 无需配置 scenarios：专家、讨论方式、技能、MCP 等库均在 libs/，通过 .env 即可

# 3. 启动服务
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# 4. 健康检查
curl http://localhost:8000/health

详见 docs/config.md。所有库（experts、moderator_modes、mcps、assignable_skills、prompts）从 libs/ 加载，无需配置 scenarios。

# 单元测试（无需真实 API Key）
pytest -q -m "not integration"

# AgentSDK 集成测试（必须真实 .env，不可用占位值）
pytest tests/test_agent_sdk.py -m integration -v -s

# 一键本地 CI（包含 unit + AgentSDK integration）
bash scripts/ci_local.sh

AgentSDK 可用性的验收标准：在真实 .env 下调用成功，且对话记录已写入 workspace/topics/{topic_id}/posts/*.json。

详见 docs/testing.md。

docker build -t resonnet .
docker run --rm -p 8000:8000 --env-file .env \
  -v "$(pwd)/workspace:/app/workspace" resonnet

为什么推荐 Docker 部署：Agent SDK 的执行会在 WORKSPACE_BASE 下创建/读写工作区并直接运行。使用 Docker 时，将宿主机的 ./workspace 挂载到容器内 /app/workspace，可以做到：

• 运行环境隔离：依赖、系统库、运行时都在容器内，避免污染宿主机环境
• 工作区隔离：容器可访问的写入范围主要集中在挂载的 workspace，其它文件系统保持隔离
• 产物可持久化：讨论记录与产物仍落盘在宿主机 workspace，重启/重建容器不丢失
• 易清理与复现：一键重建镜像/容器即可复现运行环境；删除容器即可清理运行态

自定义宿主机挂载目录：

• 使用 docker compose 时：可在 .env 中设置 WORKSPACE_HOST_DIR（默认 ./workspace）
• 使用 docker run 时：直接修改 -v /host/path:/app/workspace 的宿主机路径

或使用 docker compose up --build。

• 在保持可控编排前提下，逐步增强协作灵活性（而非一次性切到完全自治）
• 强化可观测与审计能力（讨论过程、产物、成本与调用链）
• 优先支持真实场景闭环（科研研讨、评审协作、企业协同），再扩展机制复杂度

• GET /health — 健康检查
• Topics：GET/POST /topics，GET/PATCH /topics/{topic_id}，POST /topics/{topic_id}/close
• Posts：GET/POST /topics/{topic_id}/posts，POST .../posts/mention，GET .../mention/{reply_post_id}
• Discussion：POST /topics/{topic_id}/discussion（支持 skill_list、mcp_server_ids），GET .../discussion/status
• Assignable Skills：GET /skills/assignable/categories，GET /skills/assignable（支持 category、q、fields、limit、offset），GET /skills/assignable/{skill_id}/content
• MCP：GET /mcp/assignable/categories，GET /mcp/assignable（支持 category、q、fields、limit、offset），GET /mcp/assignable/{id}/content
• Topic Experts：GET/POST /topics/{topic_id}/experts，PUT/DELETE .../experts/{expert_name}，POST .../experts/generate
• Moderator Modes：GET /moderator-modes，GET /moderator-modes/assignable（支持 category、q、fields、limit、offset），GET /moderator-modes/assignable/{id}/content，GET/PUT /topics/{topic_id}/moderator-mode，POST .../moderator-mode/generate
• Experts：GET /experts（支持 fields=minimal，列表不加载 skill_content），GET /experts/{name}/content，GET/PUT /experts/{name}
• Libs：POST /libs/invalidate-cache 立即清空库 meta 缓存（热更新）

详见 docs/api-reference.md。

欢迎贡献！除了代码，你也可以贡献纯 skill（无需改代码）：

详见 CONTRIBUTING.md 与 libs/README.md。

如发现安全漏洞，请参阅 SECURITY.md 进行报告。

版本变更见 CHANGELOG.md。

MIT License. See LICENSE for details.