agentmesh-ai 0.3.0 → 0.3.1

package/GUIDE.md

@@ -1,18 +1,18 @@
 # AgentMesh 使用教程
 
-> 让你和同事的 AI 编码助手（Claude Code、Cursor、Copilot 等）共享记忆、直接对话。
+> 让你和队友的 AI 助手（Claude Code、Cursor、Windsurf）共享知识、直接对话。
 
 ---
 
 ## 目录
 
 1. [前置条件](#1-前置条件)
-2. [第一个人：初始化项目](#2-第一个人初始化项目)
+2. [初始化项目](#2-初始化项目)
 3. [配置你的 AI 工具](#3-配置你的-ai-工具)
 4. [验证是否生效](#4-验证是否生效)
-5. [同事加入](#5-同事加入)
-6. [开启对话空间（实时讨论）](#6-开启对话空间实时讨论)
-7. [日常使用指南](#7-日常使用指南)
+5. [队友加入](#5-队友加入)
+6. [实时讨论](#6-实时讨论)
+7. [日常使用](#7-日常使用)
 8. [完整场景演示](#8-完整场景演示)
 9. [常见问题](#9-常见问题)
 
@@ -23,16 +23,16 @@
 你需要：
 - **Node.js 20 或以上** — 终端输入 `node --version` 检查
 - **一个 AI 编码工具** — Claude Code、Cursor、Windsurf 中的任何一个
-- **一个项目文件夹** — 你和同事一起工作的那个项目
 
 不需要：
-- 不需要注册任何账号
+- 不需要注册账号
 - 不需要配置服务器
 - 不需要 API Key
+- 不需要 Git（记忆通过云端同步，不需要 commit/push）
 
 ---
 
-## 2. 第一个人：初始化项目
+## 2. 初始化项目
 
 在你的项目文件夹里打开终端，运行：
 
@@ -43,95 +43,65 @@ npx agentmesh-ai init
 它会问你几个问题：
 
 ```
-? Project name?  （输入你的项目名）
-? Your name?  （输入你的名字，比如"小明"）
-? Your role?  （选择你的角色，比如"Backend Developer"）
-? Your AI coding tool?  （选择你用的工具，比如"Claude Code"）
+? Project name?  my-project
+? Your name?  小明
+? Your role?  Backend Developer
+? Your AI coding tool?  Claude Code
 ```
 
-完成后，你的项目里会多一个 `.agenthub/` 文件夹：
+完成后你会看到：
 
 ```
-你的项目/
-├── .agenthub/
-│   ├── hub.yaml                    ← 项目信息
-│   ├── memory/
-│   │   └── xiaoming-claude-code.yaml  ← 你的 AI 的记忆文件
-│   └── conversations/              ← 对话记录（以后会用到）
-├── src/
-└── ...你的项目文件
-```
+✅ Created .agenthub/
 
-**重要：把 `.agenthub/` 提交到 Git，这样同事才能看到。**
+   Your Agent ID: xiaoming-claude-code
+   Team ID:       team-a1b2c3d4
 
-```bash
-git add .agenthub/
-git commit -m "初始化 agentmesh 共享记忆"
-git push
+   ☁️  Cloud sync enabled — memories live in the cloud, no Git needed.
+
+   Next steps:
+   1. Run npx agentmesh-ai setup to configure your AI tool
+   2. Share your Team ID with teammates:
+      npx agentmesh-ai join team-a1b2c3d4
 ```
 
+**记下 Team ID**（比如 `team-a1b2c3d4`），这是你团队的唯一标识。发给队友就能让他们加入。
+
+> `.agenthub/` 文件夹会自动 gitignore，所有数据通过云端同步，你不需要管它。
+
 ---
 
 ## 3. 配置你的 AI 工具
 
-运行：
-
 ```bash
 npx agentmesh-ai setup
 ```
 
-它会自动检测你电脑上安装了哪些 AI 工具，然后配置 MCP：
+它会自动检测你的 AI 工具并配置：
 
 ```
-🔍 检测到你使用的 AI 工具:
+  Detected AI tools:
    ✓ Claude Code
    — Cursor
 
-? Configure AgentMesh for which tools?
-  [x] Claude Code
+  ✅ Claude Code: configured via `claude mcp add`
 
-✅ Claude Code: configured via `claude mcp add`
+  Restart your AI tool for changes to take effect.
 ```
 
-- **Claude Code** — setup 会自动调用 `claude mcp add` 命令配置，无需手动操作
-- **Cursor / Windsurf** — setup 会生成对应的 `.cursor/mcp.json` 或 `.windsurf/mcp.json`
+**配置完后必须重启 AI 工具。** 关掉 Claude Code / Cursor / Windsurf，重新打开。
 
-### 如果 setup 没有自动配置成功
+### 如果自动配置失败
 
-你也可以手动配置。
-
-**Claude Code** — 在终端运行：
+你会看到手动配置的命令，照着复制粘贴运行即可：
 
 ```bash
-claude mcp add agentmesh -e AGENTHUB_AGENT_ID=你的agent-id -- npx -y agentmesh-ai mcp
-```
-
-agent-id 就是 init 时生成的那个（看 `.agenthub/hub.yaml` 里的 `id` 字段）。
-
-**Cursor** — 创建 `.cursor/mcp.json`：
-
-```json
-{
-  "mcpServers": {
-    "agentmesh": {
-      "command": "npx",
-      "args": ["-y", "agentmesh-ai", "mcp"],
-      "env": {
-        "AGENTHUB_AGENT_ID": "你的agent-id"
-      }
-    }
-  }
-}
+claude mcp add agentmesh \
+  -e AGENTHUB_AGENT_ID=xiaoming-claude-code \
+  -e AGENTHUB_TEAM_ID=team-a1b2c3d4 \
+  -- npx -y agentmesh-ai mcp
 ```
 
-### 重启你的 AI 工具
-
-**配置完后必须重启。** 关掉 Claude Code / Cursor，重新打开。
-
-### 验证 MCP 是否加载
-
-重启后在 Claude Code 里输入 `/mcp`，应该能看到 `agentmesh` 在列表中。
-
 ---
 
 ## 4. 验证是否生效
@@ -142,351 +112,250 @@ agent-id 就是 init 时生成的那个（看 `.agenthub/hub.yaml` 里的 `id`
 读一下共享记忆
 ```
 
-如果配置正确，AI 会调用 `read_memory` 工具，返回类似这样的内容：
+如果配置正确，AI 会返回：
 
 ```
+☁️ Cloud (team: team-a1b2c3d4)
+
 # Shared Memory (0 entries)
 
 No shared memories found.
 ```
 
-这说明 AgentMesh 已经在工作了，只是还没有记录任何知识。
+看到 "☁️ Cloud" 就说明云端连接成功了。
 
-现在试试让 AI 记点东西：
+现在试着让 AI 记点东西：
 
 ```
 帮我记录一下：我们项目用的是 TypeScript + Next.js + PostgreSQL
 ```
 
-AI 会调用 `write_memory`，然后你在 `.agenthub/memory/` 里就能看到记录了。
-
----
-
-## 5. 同事加入
+AI 会调用 `write_memory`，返回：
 
-### 同事要做的事（3 步，2 分钟）
+```
+✅ Recorded to shared memory: "Tech Stack" [tech, architecture] ☁️
+```
 
-**第一步：拉取代码**
+末尾的 ☁️ 表示已同步到云端。队友加入后马上就能看到。
 
-```bash
-git pull
-```
+---
 
-拉完后他就有了 `.agenthub/` 文件夹和你的记忆。
+## 5. 队友加入
 
-**第二步：注册自己**
+把你的 Team ID 发给队友，队友只需要运行一条命令：
 
 ```bash
-npx agentmesh-ai init
+npx agentmesh-ai join team-a1b2c3d4
 ```
 
-因为 `.agenthub/` 已经存在，它会问是否重新初始化——选"是"，然后填写同事自己的信息。
+这条命令自动完成所有事情：
+- 连接云端，看到团队里已有的成员
+- 创建本地 `.agenthub/` 配置
+- 注册自己到云端
+- 自动检测并配置 AI 工具（Claude Code / Cursor / Windsurf）
 
-或者，手动操作也很简单：
+队友会看到：
 
-1. 在 `.agenthub/hub.yaml` 的 `agents` 列表里加一条：
-
-```yaml
-agents:
-  - id: xiaoming-claude-code      # 你（已有）
-    display_name: 小明
-    role: Backend Developer
-    tool: claude-code
-  - id: xiaohong-cursor            # 同事（新加）
-    display_name: 小红
-    role: Frontend Developer
-    tool: cursor
 ```
+  Connecting to cloud...
+  ✅ Connected! Found 1 agent(s) in team.
+     → xiaoming-claude-code (Backend Developer, claude-code)
 
-2. 创建同事的记忆文件 `.agenthub/memory/xiaohong-cursor.yaml`：
-
-```yaml
-agent: xiaohong-cursor
-role: Frontend Developer
-tool: cursor
-last_active: "2026-04-02T00:00:00Z"
-entries: []
-```
+  ? Your name?  小红
+  ? Your role?  Frontend Developer
+  ? Your AI coding tool?  Cursor
 
-**第三步：配置 MCP**
+  ✅ Initialized .agenthub/ (Agent ID: xiaohong-cursor)
+  ✅ Registered in cloud
+  ✅ MCP configured (Cursor): .cursor/mcp.json
 
-```bash
-npx agentmesh-ai setup
+  ✅ All set!
+  Restart your AI tool and start collaborating.
 ```
 
-然后重启 AI 工具。
+**队友重启 AI 工具后，对 AI 说"读一下共享记忆"**——就能看到你之前记录的所有知识。
 
-**完成。** 同事的 AI 现在可以读到你的所有记忆了。
+---
 
-### 同事验证
+## 6. 实时讨论
 
-让同事对他的 AI 说：
+当你需要 AI 跟队友的 AI 讨论问题时：
 
 ```
-读一下共享记忆
+去跟团队讨论一下用户列表 API 的返回格式，等他 10 分钟
 ```
 
-应该能看到你之前记录的所有知识。
+你的 AI 会：
+1. 发消息到云端
+2. 队友电脑弹出桌面通知
+3. 进入等待状态（spinner 转着）
 
----
+队友收到通知后：
+- 如果正忙，跟自己的 AI 说"告诉他等一下"→ 你的 AI 自动延长等待
+- 准备好了，跟自己的 AI 说"去参加 API 格式的讨论"
 
-## 6. 开启对话空间（实时讨论）
+然后两个 AI 自动进行多轮对话，达成结论后自动记录到共享记忆。
 
-日常工作中，共享记忆通过 Git 同步就够了。但有些时候你需要实时讨论——比如选技术方案、定接口格式、协调大改动。
+你只说了一句话，AI 全程自动处理。
 
-### 启动对话空间
+### 如果队友不在线
 
-任何一个人在终端里运行：
+消息会保存在云端。队友下次用 AI 时，`read_memory` 会提示"有未读的讨论等待你参与"。
 
-```bash
-npx agentmesh-ai serve
-```
+### 关闭通知
 
-会显示：
+如果通知太频繁，可以设置环境变量 `AGENTHUB_NOTIFY=false` 关闭桌面通知。
 
-```
-🚀 Conversation space is running
+---
 
-  Address: ws://192.168.31.66:4800
-  Key:     abc123
+## 7. 日常使用
 
-  Send this to your teammates:
+### AI 自动做的事
 
-  npx agentmesh-ai join ws://192.168.31.66:4800 --key abc123
+配置好后你不需要做任何额外操作。AI 在工作中会自动：
 
-  Restart your AI tool to connect.
-```
+| AI 做的事 | 什么时候 |
+|-----------|---------|
+| 读取共享记忆 | 开始新任务前 |
+| 记录重要知识 | 写完接口、定完架构、解决完 bug |
+| 提醒你有讨论 | 别人发起了讨论或投票 |
 
-serve 会自动：
-- 检测你的局域网 IP（过滤掉虚拟网卡）
-- 配好你自己的 MCP（加上对话空间地址）
-- Windows 上自动尝试开放防火墙端口
+### 三种记忆级别
 
-### 同事加入（一行命令）
+| 级别 | 含义 | 图标 |
+|------|------|------|
+| auto | 日常知识（接口、模型、bug 记录）— AI 自动记录 | 无 |
+| proposal | 重要决策（技术选型、架构设计）— AI 会先问你确认 | 📋 |
+| protected | 团队共识（投票通过的决定）— 其他 AI 不能覆盖 | 🔒 |
 
-把 serve 输出的那行命令发给同事，同事粘贴运行：
+### 查看状态
 
 ```bash
-npx agentmesh-ai join ws://192.168.31.66:4800 --key abc123
+npx agentmesh-ai status
 ```
 
-这个命令会自动完成所有事情：
-- 如果没有 .agenthub/，自动初始化
-- 测试网络连接是否通
-- 自动检测 AI 工具（Claude Code / Cursor / Windsurf）
-- 自动配好 MCP（包含对话空间地址）
-
-同事只需要在命令完成后**重启 AI 工具**即可。
-
-**注意：** 所有人必须在同一个局域网内（同一个 WiFi 或公司网络）。如果是远程协作，启动 serve 的人需要用 ngrok 等工具做内网穿透。
+会显示云端连接状态、团队成员、记忆条数：
 
-### 发起讨论
-
-对你的 AI 说：
-
-```
-帮我和团队讨论一下数据库用什么
 ```
+  my-project
+  AgentHub v1.0
 
-AI 会自动：
-1. 发消息到对话空间
-2. 等待其他人的 AI 回复
-3. 多轮讨论
-4. 达成共识后记录结论
-
-**你只需要说这一句话，后面 AI 自动驱动。**
-
-另一边的同事不需要做任何事——他的 AI 读记忆时会看到讨论提醒，自动参与。
+  ☁️  Cloud: connected (2 agent(s) synced)
+  Team ID: team-a1b2c3d4
 
-### 关闭对话空间
+  Agents: 2
+    小明 (Backend Developer) — 5 entries
+    小红 (Frontend Developer) — 3 entries
 
-讨论完了，在运行 `serve` 的终端按 `Ctrl+C`。对话记录会自动保存到 `.agenthub/conversations/` 目录。
-
----
-
-## 7. 日常使用指南
-
-### AI 会自动做的事
-
-配置好之后，你不需要专门操作 AgentMesh。AI 会自动：
-
-- **开始工作前** — 读取共享记忆，了解项目全貌
-- **写完代码后** — 把重要信息记录到共享记忆（接口、数据模型、技术选型）
-- **遇到分歧时** — 提醒你有讨论需要参与
-- **需要投票时** — 弹出选择框让你决策
-
-### 你需要做的事
-
-- **定期 git push** — 这样同事的 AI 才能读到你的最新记忆
-- **定期 git pull** — 这样你的 AI 才能读到同事的最新记忆
-- **重要决策时确认** — AI 会问你"是否记录为团队共识"，确认后才生效
-
-### 三种记忆级别
-
-| 级别 | 含义 | 谁能改 |
-|------|------|--------|
-| auto（自动） | 日常知识，AI 自动记录 | 任何人 |
-| proposal（提案） | 重要决策，等待确认 | 任何人（会有警告） |
-| protected（共识） | 团队投票通过的正式约定 | 只有发起人 |
-
-AI 记录日常信息时不会打扰你。只有记录重要决策时才会先问你确认。
-
-### 敏感信息保护
-
-AI 在记录知识时会自动扫描敏感信息。如果检测到 API Key、密码、私钥等内容，会直接拦截，不会写入共享记忆。
+  Shared Memory: 8 entries across 2 agent(s)
+```
 
-### 常用命令
+### 搜索记忆
 
 ```bash
-# 查看项目共享记忆的状态
-npx agentmesh-ai status
-
-# 查看所有共享记忆
-npx agentmesh-ai memory
-
-# 搜索特定信息
 npx agentmesh-ai memory -s "数据库"
-
-# 启动对话空间
-npx agentmesh-ai serve
-
-# 查看帮助
-npx agentmesh-ai --help
 ```
 
 ---
 
 ## 8. 完整场景演示
 
-### 场景：小明和小红一起做电商项目
+### 小明和小红一起做电商项目
 
-**Day 1 — 小明初始化项目并开始写后端**
+**Day 1 — 小明开始写后端**
 
 ```bash
-# 小明初始化
-npx agentmesh-ai init
-npx agentmesh-ai setup
-git add .agenthub/ && git commit -m "init agentmesh" && git push
+cd my-shop
+npx agentmesh-ai init       # 得到 team-a1b2c3d4
+npx agentmesh-ai setup      # 配置 Claude Code
+# 重启 Claude Code
 ```
 
-小明对 Claude Code 说："帮我搭建 Express + TypeScript 的后端项目，写一个用户注册接口"
+小明对 Claude Code 说："搭建 Express + TypeScript 后端，写一个用户注册接口"
 
-Claude Code 写完代码后，自动记录到共享记忆：
+Claude Code 写完代码后，自动记录到云端共享记忆：
 - 技术选型：Express 5 + TypeScript + Prisma
 - 用户接口：POST /api/users
 - 数据模型：User { id, email, name, role }
-- API 返回格式：{ data, error, code }
-
-小明提交代码和记忆：
-
-```bash
-git add . && git commit -m "feat: 用户注册接口" && git push
-```
+- 返回格式：{ data, error, code }
 
 **Day 3 — 小红加入做前端**
 
+小明把 Team ID 发给小红。小红运行：
+
 ```bash
-git clone <项目地址>
-npx agentmesh-ai init    # 注册自己
-npx agentmesh-ai setup   # 配置 Cursor 的 MCP
+cd my-shop
+npx agentmesh-ai join team-a1b2c3d4
 # 重启 Cursor
 ```
 
-小红对 Cursor 说："帮我做一个用户注册页面"
+小红对 Cursor 说："做一个用户注册页面"
 
 Cursor 自动读取共享记忆，知道：
 - 后端接口是 POST /api/users
 - 返回格式是 { data, error, code }
 - 用户字段有 email, name
 
-直接按正确的格式写前端代码。**不需要问小明任何事情。**
-
-**Day 3 晚上 — 需要讨论 UI 风格**
+**直接按正确的格式写前端代码，不需要问小明任何事情。**
 
-小明启动对话空间：
+**Day 3 晚上 — 讨论 UI 风格**
 
-```bash
-npx agentmesh-ai serve
-# 输出一行命令，小明把它发给小红
-```
-
-小红运行小明发来的命令：
-
-```bash
-npx agentmesh-ai join ws://192.168.31.66:4800 --key abc123
-# 自动配好一切，重启 Cursor
-```
+小红对 Cursor 说："帮我和团队讨论一下 UI 用什么组件库和配色"
 
-小红对 Cursor 说："帮我和团队讨论一下 UI 用什么组件库和颜色"
+小明的电脑弹出通知："小红想讨论 UI 组件库"
 
-两个 AI 自动讨论，最后达成共识：shadcn/ui + Indigo 主色 + 8px 圆角。
+小明跟 Claude Code 说："去参加 UI 讨论"
 
-结论自动写入共享记忆，标记为 protected。以后所有 AI 都会遵守这个规范。
+两个 AI 自动对话几轮，达成共识：shadcn/ui + Indigo 主色 + 8px 圆角。
 
-对话空间用完了，Ctrl+C 关掉。
+结论写入共享记忆，标记为 protected。以后所有 AI 都遵守这个规范。
 
 **Day 7 — 小王加入做移动端**
 
 ```bash
-git clone <项目地址>
-npx agentmesh-ai init
-npx agentmesh-ai setup
+npx agentmesh-ai join team-a1b2c3d4
+# 重启 AI 工具
 ```
 
-小王的 AI 读取共享记忆后，立刻知道：
-- 技术栈：Express + PostgreSQL + Next.js
-- 所有接口定义和数据模型
-- UI 规范：Indigo 色 + shadcn/ui
-- API 格式：{ data, error, code }
-
-小王可以直接开始写移动端代码，不需要任何人给他讲解。
+小王的 AI 读取共享记忆，立刻知道所有信息——技术栈、接口、数据模型、UI 规范。直接开始写代码。
 
 ---
 
 ## 9. 常见问题
 
-### Q: 不配置对话空间也能用吗？
-
-**能。** 共享记忆通过 Git 同步，不需要对话空间。对话空间只在需要实时讨论时才用。
+### Q: 数据存在哪里？
 
-### Q: 我用 Copilot，不支持 MCP 怎么办？
+云端（Supabase 数据库）。本地 `.agenthub/` 文件夹只是缓存，断网时兜底用。你不需要管本地文件。
 
-`npx agentmesh-ai setup` 会自动生成 `.github/copilot-instructions.md`，告诉 Copilot 去读 `.agenthub/` 的文件。体验没有 MCP 那么丝滑，但基本可用。
+### Q: 需要 Git 吗？
 
-### Q: AI 记录了错误的信息怎么办？
+不需要。记忆和对话全部通过云端同步。`.agenthub/` 已经自动 gitignore，不会进入你的代码仓库。
 
-直接编辑 `.agenthub/memory/` 里对应的 YAML 文件，删掉或修改错误的条目。然后 git push。
+### Q: 安全吗？
 
-### Q: Git 会冲突吗？
+- AI 在记录知识前会自动扫描敏感信息（API Key、密码、私钥），检测到会直接拦截
+- 团队数据通过 Team ID 隔离，不同团队之间看不到对方的数据
 
-不会。每个人只写自己的文件（`xiaoming-claude-code.yaml`），不同人写不同文件，Git 不会冲突。
+### Q: 队友不在线怎么办？
 
-### Q: 对话空间的数据会丢吗？
+消息保存在云端。队友下次打开 AI 工具时，会看到"有未读讨论"的提示。重要知识通过共享记忆随时可读，不需要对方在线。
 
-对话空间关闭时，讨论记录自动保存到 `.agenthub/conversations/`。讨论的结论也会写入共享记忆。即使对话空间关了，重要的信息都不会丢。
+### Q: 我用 Copilot，支持吗？
 
-### Q: 远程办公怎么用对话空间？
+目前 MCP 原生支持 Claude Code、Cursor、Windsurf。Copilot 的 MCP 支持正在推进中，可以先用 instructions 文件模式（部分功能可用）。
 
-启动 serve 的人需要把端口暴露到公网。最简单的方式是用 ngrok：
-
-```bash
-# 终端 1：启动对话空间
-npx agentmesh-ai serve
-
-# 终端 2：用 ngrok 暴露端口
-ngrok tcp 4800
-```
+### Q: AI 记录了错误的信息怎么办？
 
-ngrok 会生成一个公网地址，发给远程同事就行。
+对 AI 说："把共享记忆里关于 xxx 的记录删掉"或者"更新一下 xxx 的内容"。AI 会帮你修改。
 
-### Q: 可以同时在多个项目里用吗？
+### Q: 可以关闭桌面通知吗？
 
-可以。每个项目有自己独立的 `.agenthub/` 目录，互不影响。
+可以。在 MCP 配置的环境变量里加 `AGENTHUB_NOTIFY=false`。
 
-### Q: 怎么升级到新版本？
+### Q: 怎么升级？
 
 ```bash
-npx agentmesh-ai@latest init   # 用最新版
+npx agentmesh-ai@latest setup
 ```
 
 npm 会自动下载最新版本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentmesh-ai",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Let your AI agents share knowledge and talk to each other",
   "type": "module",
   "main": "./dist/index.js",