@peonai/swarm 0.1.0

package/docs/DEBATE-ROUND1.md

@@ -0,0 +1,244 @@
+# 蜂群 AI — 第一轮辩论（反方质疑）
+
+> 辩手：Grunt（反方） | 日期：2026-02-20 | 基于 REQUIREMENTS.md v0.1
+
+---
+
+## 1. CRDT 同步画像的技术可行性
+
+### 质疑
+
+CRDT 在文档协同编辑（如 Yjs、Automerge）中已被验证，但画像数据的冲突语义与文档截然不同。
+
+文档冲突是「两个人同时编辑同一段文字」，合并策略清晰——保留两者或按时间戳取最新。但画像冲突是**语义冲突**：
+
+- Agent A 观察到用户「喜欢简洁回复」（confidence: 0.8），Agent B 同时观察到用户「需要详细解释」（confidence: 0.7）——这不是同一个 key 的冲突，而是**语义矛盾**的两个推断，CRDT 的 Last-Writer-Wins 或 Multi-Value Register 都无法解决。
+- L3 上下文层「频繁变化」，多个 agent 高频写入同一个 key（如 `current_mood`），CRDT 的因果序在跨设备、跨 agent 场景下维护成本极高。
+- `confidence` 字段本身就是模糊的——0.8 和 0.7 谁赢？按数值大小合并？那 confidence 的计算标准各 agent 都不同，数值不可比。
+
+### 反驳
+
+合理的担忧，但可以分层处理：
+
+- L1（身份层）极少变化，用简单的 LWW（Last-Writer-Wins）即可，几乎不会冲突。
+- L2/L3 的语义冲突，不应该靠 CRDT 自动解决，而是**保留多值 + 延迟合并**：先用 MV-Register 保留所有版本，再由一个本地的「画像仲裁器」（可以是 LLM）做语义合并。
+- confidence 不可比的问题，可以通过标准化 confidence 计算规则 + source 权重来缓解。
+
+### 结论/建议
+
+**CRDT 只解决传输层的冲突，不要指望它解决语义层的冲突。** 需求文档应明确区分「同步冲突」和「语义冲突」，并为后者设计独立的合并策略（如 LLM 仲裁、用户确认）。建议在 P0 阶段只对 L1 用 LWW-CRDT，L2/L3 用 append-only log + 手动/半自动合并。
+
+---
+
+## 2. 冷启动问题
+
+### 质疑
+
+经典的双边市场鸡生蛋问题：
+
+- 没有 agent 接入 → 画像数据为空 → 用户看不到价值 → 不会安装 Profile Daemon
+- 没有用户安装 → agent 开发者没有动力接入 SDK → 没有 agent 接入
+
+需求文档提到「画像导入」（P1）和「从现有 agent 导入」，但这恰恰是最难的部分——ChatGPT、Claude 的记忆数据没有开放 API 导出，你怎么导？
+
+更致命的是：即使你自己的 OpenClaw agent 接入了，一个 agent 的画像数据价值极低。用户不会为了「让一个 agent 的记忆同步到另一个 agent」而安装一个 daemon 服务——直接复制粘贴更快。
+
+### 反驳
+
+冷启动可以通过以下路径破解：
+
+1. **自举**：先让 OpenClaw 自己的 agent 生态（Peon、Grunt 等）原生支持 SPP，形成第一批画像数据。用户在 OpenClaw 生态内就能体验到价值。
+2. **手动导入**：提供一个简单的表单/向导，让用户手动填写 L1 身份信息（姓名、语言、时区、职业），5 分钟就能建立基础画像。
+3. **渐进积累**：每次 agent 交互自动 observe，画像会自然丰富起来，不需要一开始就完整。
+
+### 结论/建议
+
+**冷启动是真实风险，但不是死局。** 关键策略：先在 OpenClaw 生态内闭环验证，不要一上来就追求「跨生态」。把「手动填写基础画像」从 P1 提到 P0——这是冷启动的救命稻草。同时，考虑提供一个「导出你的 ChatGPT Memory」的浏览器脚本作为增长黑客手段。
+
+---
+
+## 3. 封闭生态接入
+
+### 质疑
+
+架构图里画了 ChatGPT 作为 Agent 2 接入 Profile Daemon，但现实是：
+
+- **ChatGPT/Gemini/Claude 都没有开放 agent 扩展接口。** 它们不会主动调用你的 localhost API。
+- 需求文档自己也在「开放问题」里承认了这一点，提到「浏览器插件代理」。
+- 浏览器插件方案的问题：
+  - 依赖 DOM 结构，ChatGPT 改版一次你就得跟着改
+  - 只能拦截网页版，移动端 App 完全无法覆盖
+  - 注入内容到 system prompt 的方式不稳定，且可能违反 ToS
+  - 用户安装浏览器插件的意愿本就不高（Chrome 插件平均安装率 < 1%）
+
+这意味着「跨生态」这个核心卖点，在 MVP 阶段基本是空中楼阁。
+
+### 反驳
+
+短期内确实无法原生接入封闭生态，但：
+
+1. **浏览器插件虽然脆弱，但已有先例**：如 WebChatGPT、ChatGPT Exporter 等插件证明了可行性，且用户群体不小。
+2. **趋势在变**：OpenAI 已推出 GPTs 和 Actions，未来可能开放更多扩展点。MCP 协议的兴起也在推动 agent 互操作。
+3. **不需要所有 agent 都接入**：即使只有 2-3 个开放 agent（OpenClaw + 本地 LLM + 一个开源 agent）能互通画像，对重度用户已有价值。
+
+### 结论/建议
+
+**诚实面对：MVP 阶段放弃「接入 ChatGPT/Gemini」的叙事。** 把竞品对比表里的「跨生态」改为「开放生态优先」，聚焦于开源/本地 agent 的互通。浏览器插件可以作为 P2 的实验性功能，但绝不能作为核心依赖。如果把「跨生态」作为融资故事讲，要准备好被投资人追问「ChatGPT 怎么接」时的诚实回答。
+
+---
+
+## 4. 隐私悖论
+
+### 质疑
+
+需求文档强调「端到端加密」「零知识架构」「用户主权」，但蜂群 AI 的本质是**把分散在各 agent 的用户数据汇聚到一个统一的 Profile Daemon**。这带来了一个根本性的悖论：
+
+- **攻击面集中化**：原来攻击者要分别攻破 ChatGPT、Claude、本地 agent 才能拼凑出完整画像，现在只需攻破一个 Profile Daemon 就能获得全部。
+- **本地 daemon 的安全性**：SQLite 文件存在本地磁盘，任何有文件系统访问权限的恶意软件都能读取。E2E 加密保护的是传输层，不是本地存储。
+- **agent 信任问题**：一个恶意 agent 注册为 `trustLevel: "trusted"`，就能读取所有画像数据。信任模型怎么建立？谁来审核 agent？
+- **画像推断的隐私风险**：agent 自动 observe 用户行为并写入画像，用户可能完全不知道自己的「情绪状态」「兴趣领域」被记录了。
+
+### 反驳
+
+这些风险真实存在，但可以通过设计缓解：
+
+1. **本地加密**：SQLite 可以用 SQLCipher 加密，密钥存在系统 keychain 中。
+2. **agent 注册审核**：trustLevel 由用户手动授予，不是 agent 自己声明的。新 agent 默认 `readonly`。
+3. **observe 透明度**：每次 agent 写入画像条目时，daemon 可以弹出通知让用户确认（至少对 L2/L3 敏感条目）。
+4. **数据最小化**：agent 只能读取自己被授权的 scope，不是全部画像。
+
+### 结论/建议
+
+**隐私不是「加密就完了」的问题，是架构级的信任设计问题。** 建议：(1) P0 必须包含本地存储加密（SQLCipher）；(2) 默认所有 agent 为 `readonly`，用户显式授权才能写入；(3) 增加「画像审计日志」——用户可以看到哪个 agent 在什么时候读/写了什么；(4) L3 上下文层的自动 observe 默认关闭，需用户 opt-in。
+
+---
+
+## 5. 商业模式
+
+### 质疑
+
+需求文档提到「开源协议 + 云服务收费」，但这条路的护城河极其脆弱：
+
+- **协议开源 = 大厂可以直接实现**：如果 SPP 协议真的好用，Apple/Google/OpenAI 完全可以自己实现一个兼容版本，还能跟自家生态深度整合。你的协议反而成了他们的免费设计文档。
+- **云 relay 服务没有壁垒**：一个 E2E 加密的中转服务器，技术上极其简单，任何云厂商都能提供。
+- **开源社区的变现困境**：参考 Redis、Elasticsearch 的教训——AWS 直接推出兼容服务，原厂被迫改许可证。
+- **目标用户付费意愿存疑**：「重度 AI 用户」已经在为 ChatGPT Plus、Claude Pro 付费，再为一个画像同步服务付费的意愿有多高？
+
+### 反驳
+
+1. **网络效应是护城河**：如果蜂群 AI 成为事实标准，agent 开发者会围绕它构建，这种生态粘性不是大厂轻易能复制的。
+2. **企业版是变现重点**：企业需要「统一管理员工 AI 画像」，这是 B2B SaaS 的经典模式，客单价高、粘性强。
+3. **先占位再说**：在 AI agent 互操作这个领域，目前没有标准。先成为事实标准，商业模式自然会浮现。
+
+### 结论/建议
+
+**「先占位再说」不是商业模式，是赌博。** 建议：(1) 许可证选择要慎重——考虑 AGPL 或 BSL（Business Source License）而非 MIT/Apache，防止大厂白嫖；(2) 企业版从 Day 1 就要规划，不要等协议成熟了再想；(3) 短期变现路径可以考虑「画像托管服务」（帮不想自建 daemon 的用户托管）+ 「agent 认证市场」（类似 App Store 的 agent 信任认证）。
+
+---
+
+## 6. MVP 范围
+
+### 质疑
+
+看一下 P0 的范围：
+
+- 画像 CRUD + 多端同步 + CRDT 冲突解决 + 权限控制 + 本地优先
+- 轻量级 SDK（JS/Python/Rust 三种语言）
+- 认证机制 + 事件订阅
+- Profile Daemon（SQLite + HTTP API + 同步引擎）
+
+这不是 MVP，这是一个**完整产品的 v1.0**。仅「CRDT 同步引擎 + E2E 加密 + 多端同步」这一项，就够一个团队做 3-6 个月。再加上三种语言的 SDK、认证系统、权限控制……
+
+对于一个还没验证需求的项目，P0 太大了。如果花 6 个月做完发现没人用，沉没成本巨大。
+
+### 反驳
+
+P0 确实偏大，但核心功能之间有强依赖——没有同步就不是「蜂群」，没有权限就不能让多 agent 接入，没有 SDK 就没有 agent 能用。砍掉任何一个，产品就不完整。
+
+### 结论/建议
+
+**MVP 应该是「能验证核心假设的最小集合」，而不是「功能完整的最小集合」。** 建议把 P0 砍成两阶段：
+
+**P0-alpha（2-4 周，验证需求）：**
+- 单设备、单用户、仅 localhost
+- 画像 CRUD（HTTP API）
+- 仅 JS SDK
+- 无同步、无加密、无认证
+- 让 OpenClaw 的 2-3 个 agent 接入，验证「多 agent 共享画像」是否真的有用
+
+**P0-beta（在 alpha 验证后）：**
+- 加入多端同步（先用简单的 HTTP 轮询，不用 CRDT）
+- 加入基础认证
+- 根据 alpha 反馈决定是否继续
+
+**不要在需求未验证前就投入 CRDT 和 E2E 加密。**
+
+---
+
+## 7. 跟 MCP 的关系
+
+### 质疑
+
+MCP（Model Context Protocol）已经在做「为 LLM 提供上下文」这件事，而且有 Anthropic 背书，生态在快速增长。蜂群 AI 的 SPP 协议跟 MCP 的关系是什么？
+
+- 如果 SPP 是 MCP 的竞争者——你没有 Anthropic 的资源和影响力，赢不了。
+- 如果 SPP 是 MCP 的补充——为什么不直接做一个 MCP Server，把画像数据通过 MCP 协议暴露给 agent？
+
+需求文档完全没有提到 MCP，这在 2026 年是一个明显的盲点。任何做 agent 互操作的项目都绕不开 MCP。
+
+### 反驳
+
+MCP 解决的是「agent 如何获取外部工具和数据」，SPP 解决的是「用户画像如何跨 agent 同步」。两者的关注点不同：
+
+- MCP 是 agent → 工具/数据 的连接协议
+- SPP 是 agent ↔ agent 之间通过共享画像的间接协作协议
+
+但确实，SPP 可以（也应该）通过 MCP 暴露——即 Profile Daemon 同时是一个 MCP Server，agent 通过 MCP 标准接口读写画像。
+
+### 结论/建议
+
+**不要发明独立协议，做 MCP 扩展。** 具体建议：(1) Profile Daemon 实现为 MCP Server；(2) 画像读写通过 MCP Tools 暴露（`profile.get`、`profile.set`、`profile.observe`）；(3) 画像数据通过 MCP Resources 暴露；(4) SPP 协议聚焦于「多 daemon 之间的同步协议」，而非「agent 与 daemon 之间的通信协议」——后者直接用 MCP。这样可以借助 MCP 生态获得 agent 接入，大幅降低冷启动难度。
+
+---
+
+## 8. 真实需求验证
+
+### 质疑
+
+需求文档假设「用户被迫反复告知每个 agent 相同的偏好和背景信息」是一个痛点，但：
+
+- **大多数用户只重度使用 1-2 个 AI agent**，不是 3-5 个。ChatGPT 占据了绝大部分市场份额，很多人只用 ChatGPT。
+- **AI agent 的记忆功能在快速进化**：ChatGPT Memory、Claude Projects、Gemini 的个性化——每个 agent 都在自己解决这个问题。用户的痛感在递减。
+- **「教一次，所有 agent 都知道」听起来很美，但用户真的在乎吗？** 告诉 Claude「我是程序员，喜欢简洁回复」只需要 10 秒。大多数用户的偏好就这么几条，手动设置的成本极低。
+- **目标用户「重度 AI 用户，日常使用 3+ 个不同 AI 工具」**——这个群体有多大？可能只占 AI 用户的 1-5%。为一个小众群体做一个复杂的基础设施项目，ROI 存疑。
+
+### 反驳
+
+1. **痛点会随 agent 数量增长而加剧**：2026 年 agent 生态在爆发，未来每个人可能有 10+ 个专用 agent（编程 agent、写作 agent、健康 agent、财务 agent……），画像同步的需求会指数级增长。
+2. **开发者是更直接的用户**：对于构建 AI 应用的开发者来说，「接入用户画像」是刚需——他们不想让用户从零开始配置。
+3. **企业场景是强需求**：企业需要统一管理员工的 AI 交互偏好，这不是「10 秒手动设置」能解决的。
+
+### 结论/建议
+
+**在投入开发前，必须做需求验证。** 建议：(1) 先做一个 landing page + waitlist，看有多少人注册；(2) 在 AI 开发者社区（如 r/LocalLLaMA、HuggingFace、Discord）发帖描述这个概念，收集反馈；(3) 找 5-10 个「重度 AI 用户」做深度访谈，验证痛点是否真实；(4) 如果验证结果不理想，考虑 pivot 到更窄的场景——比如只做「OpenClaw 生态内的 agent 画像同步」，而非通用协议。**不要为一个假设的需求建造大教堂。**
+
+---
+
+## 总结
+
+| # | 议题 | 风险等级 | 核心建议 |
+|---|------|----------|----------|
+| 1 | CRDT 可行性 | 🟡 中 | 分层策略，语义冲突不靠 CRDT |
+| 2 | 冷启动 | 🔴 高 | 先在 OpenClaw 内闭环，手动填写提到 P0 |
+| 3 | 封闭生态 | 🔴 高 | MVP 放弃跨封闭生态叙事 |
+| 4 | 隐私悖论 | 🟡 中 | 本地加密 + 审计日志 + 默认最小权限 |
+| 5 | 商业模式 | 🟡 中 | 用 AGPL/BSL 防白嫖，Day 1 规划企业版 |
+| 6 | MVP 范围 | 🔴 高 | 砍成 alpha/beta 两阶段，先验证再投入 |
+| 7 | MCP 关系 | 🟡 中 | 做 MCP Server，不要发明独立协议 |
+| 8 | 需求验证 | 🔴 高 | 开发前必须做用户验证 |
+
+**反方总结陈词：蜂群 AI 的愿景很美，但当前需求文档在「假设需求存在」的前提下直接跳到了架构设计。建议先退一步：用 2-4 周做一个极简 alpha（单机、单语言 SDK、无同步），在 OpenClaw 生态内验证「多 agent 共享画像」是否真的改善了用户体验。如果验证通过，再逐步加入同步、加密、多语言 SDK。如果验证不通过，及时止损。**
+
+---
+
+*辩论记录 v1.0 | 2026-02-20 | 反方辩手：Grunt ⚔️*

package/docs/DEBATE-ROUND2.md

@@ -0,0 +1,158 @@
+# 蜂群 AI — 第二轮辩论（Server + Skill 方向）
+
+> Peon 自辩自驳 | 2026-02-20 | 基于 REQUIREMENTS v0.2
+
+---
+
+## 1. Server vs Daemon 的取舍
+
+### 质疑
+从本地 daemon 转向服务器部署，确实解决了冷启动和 CRDT 复杂度，但引入了新问题：
+- **延迟**：每次 agent 启动都要网络请求拉画像，弱网环境体验差
+- **可用性**：服务器挂了 = 所有 agent 丢失画像，单点故障
+- **隐私倒退**：v0.1 的核心卖点是「本地优先、用户控制数据」，现在数据在服务器上，跟 ChatGPT Memory 有什么区别？
+
+### 反驳
+- 延迟：画像数据量小（几 KB），一次请求 < 100ms，agent 可以本地缓存
+- 可用性：自托管方案用户自己控制，云托管做多可用区
+- 隐私：自托管 = 数据在自己服务器上，跟本地 daemon 本质一样。云托管版本可以做 E2E 加密
+
+### 结论
+**提供两种部署模式**：自托管（Docker，数据完全自控）+ 云托管（便捷但需信任）。MVP 先做自托管，验证后再做云托管。agent 端加本地缓存，断网也能用上次的画像。
+
+---
+
+## 2. Skill 通用性
+
+### 质疑
+SKILL.md 是 OpenClaw 的概念。ChatGPT 没有 Skill 系统，Claude 没有，Gemini 也没有。所谓「agent 通过 Skill 集成」实际上只有 OpenClaw 能用。这跟 Round 1 的封闭生态问题本质一样——只是换了个说法。
+
+### 反驳
+Skill 的本质是「教 agent 怎么调 API」，不同 agent 有不同的实现方式：
+- **OpenClaw**：装 Skill 目录，自动学会
+- **Claude Projects**：把 API 文档放进 Project Knowledge
+- **ChatGPT GPTs**：通过 Actions 配置 API 调用
+- **开发者自建 agent**：直接调 REST API
+
+REST API 是通用的，Skill 只是 OpenClaw 的便捷包装。
+
+### 结论
+**核心是 API，Skill 是锦上添花。** 提供：(1) REST API 文档（通用）；(2) OpenAPI/Swagger spec（GPTs Actions 可直接导入）；(3) OpenClaw Skill（便捷集成）；(4) MCP Server（支持 MCP 的 agent 直接用）。四种接入方式覆盖主流场景。
+
+---
+
+## 3. 自托管 vs 云托管
+
+### 质疑
+自托管需要用户有服务器、会 Docker，门槛太高。目标用户是「重度 AI 用户」不是「DevOps 工程师」。云托管易用但要处理多租户隔离、数据安全、合规，开发成本高。先做哪个？
+
+### 反驳
+- 自托管的目标用户是开发者和技术型用户——这恰好是早期采用者
+- 云托管可以后做，但需要从架构上预留多租户支持
+
+### 结论
+**先自托管（Docker Compose 一键部署），后云托管。** 理由：(1) 早期用户是技术型，能接受 Docker；(2) 自托管不需要处理多租户和支付；(3) 自托管用户的反馈帮助打磨产品，再做云托管。
+
+---
+
+## 4. 商业可行性
+
+### 质疑
+v0.2 的商业模式比 v0.1 清晰了一点（服务器 = 可以收费），但核心问题没变：
+- 自托管免费 → 技术用户都自建，不付费
+- 云托管收费 → 跟 Mem0、Zep 正面竞争
+- API 调用量收费 → 画像读写频率低，ARPU 极低
+
+### 反驳
+变现不靠基础 API，靠增值服务：
+- **画像智能**：AI 自动从交互中提炼画像（不只是存储，是理解）
+- **跨 agent 洞察**：「你的 coding agent 发现你最近在学 Rust，要不要同步给你的学习 agent？」
+- **企业版**：团队画像管理、合规审计、SSO
+
+### 结论
+**短期不追求变现，先追求用户量。** 个人版完全免费（自托管），等用户量到一定规模再推企业版和增值服务。这是开源基础设施的标准路径。
+
+---
+
+## 5. 竞品分析
+
+### 质疑
+这个赛道已经有玩家了：
+- **Mem0**：AI memory layer，提供 API 存储和检索 AI 对话记忆，已融资
+- **Zep**：长期记忆服务，支持用户画像和会话历史
+- **LangMem**：LangChain 生态的记忆管理
+- **Letta (MemGPT)**：有状态 agent 框架，内置记忆管理
+
+这些产品已经在做「AI agent 的记忆/画像服务」，蜂群 AI 的差异化在哪？
+
+### 反驳
+关键差异：
+- Mem0/Zep/LangMem 聚焦**单 agent 记忆**，蜂群聚焦**跨 agent 画像同步**
+- 它们是开发者工具（SDK），蜂群有**用户管理界面**（非技术用户也能管理画像）
+- 它们不管 agent 人设，蜂群把**画像 + 人设 + 记忆**统一管理
+- 蜂群的 Skill 集成方式更轻量——不需要改代码，装个 Skill 就行
+
+### 结论
+**差异化在「跨 agent」和「用户可控」。** 但要诚实：如果 Mem0 加一个「跨 agent 同步」功能，差异化就没了。护城河在于：(1) 先发优势——先占「跨 agent 画像」这个定位；(2) Skill 生态——让接入尽可能简单；(3) 用户体验——管理界面做到非技术用户也能用。
+
+---
+
+## 6. MCP 兼容
+
+### 质疑
+Round 1 建议「做 MCP Server」，v0.2 没有明确回应。API 是否应该同时暴露为 MCP Server？
+
+### 反驳
+成本低、收益高：
+- MCP Server 就是把 REST API 包一层 MCP 协议，工作量 1-2 天
+- 所有支持 MCP 的 agent（Claude Desktop、OpenClaw、Cursor 等）直接能用
+- 不做 MCP = 放弃一大批潜在用户
+
+### 结论
+**P0 就做 MCP Server。** 工作量小，收益大。REST API + MCP Server 双协议暴露。
+
+---
+
+## 7. MVP 范围评估
+
+### 质疑
+v0.2 的 P0-alpha：
+- 服务器 REST API（画像 CRUD + 记忆 CRUD）
+- API Key 认证
+- 管理界面（画像编辑 + Agent 管理）
+- OpenClaw Skill
+- Peon 集成
+
+2-4 周能做完吗？
+
+### 反驳
+拆解工作量：
+- 后端 API（Express + PostgreSQL）：3-4 天
+- API Key 认证：1 天
+- 管理界面（React + Tailwind）：5-7 天
+- OpenClaw Skill：1 天
+- Peon 集成测试：1-2 天
+- 总计：11-15 天，2-3 周可完成
+
+### 结论
+**范围合理，但建议进一步精简管理界面。** P0-alpha 的管理界面只做：(1) 画像查看/编辑；(2) API Key 生成。Agent 管理和记忆浏览放到 P0-beta。这样可以压缩到 2 周。
+
+---
+
+## 总结
+
+| # | 议题 | 结论 |
+|---|------|------|
+| 1 | Server vs Daemon | 先自托管 Docker，agent 端加本地缓存 |
+| 2 | Skill 通用性 | API 为核心，Skill/OpenAPI/MCP 四种接入方式 |
+| 3 | 自托管 vs 云托管 | 先自托管，后云托管 |
+| 4 | 商业可行性 | 短期不变现，先追用户量 |
+| 5 | 竞品 | 差异化在「跨 agent」+「用户可控」，但护城河薄 |
+| 6 | MCP | P0 就做，成本低收益高 |
+| 7 | MVP 范围 | 合理，精简管理界面后 2 周可完成 |
+
+**Round 2 核心结论：Server + Skill 方向比 v0.1 务实得多，竞品存在但差异化明确。最大风险从「技术复杂度」变成了「市场竞争」——需要快速推出 MVP 抢占「跨 agent 画像」这个定位。**
+
+---
+
+*Round 2 | Peon ⛏️ | 2026-02-20*

package/docs/REQUIREMENTS.md

@@ -0,0 +1,162 @@
+# 蜂群 AI — 需求分析 v0.2（Server + Skill 方向）
+
+> v0.1 → v0.2 重大转向：从本地 daemon 改为服务器部署 + Agent Skill 集成
+
+## 1. 核心方向
+
+**一句话**：部署在服务器的用户画像中心，agent 通过 Skill 学会调用 API 读写画像。
+
+**关键转变**：
+- ~~本地 Profile Daemon~~ → 服务器部署（自托管或云托管）
+- ~~P2P/CRDT 同步~~ → 服务器为单一数据源
+- ~~多语言 SDK~~ → Agent Skill（SKILL.md）+ REST API
+- ~~零安装~~ → 用户注册账号，agent 装 Skill
+
+## 2. 系统架构
+
+```
+┌─────────────────────────────────┐
+│        蜂群 AI Server           │
+│                                 │
+│  ┌──────────┐  ┌─────────────┐  │
+│  │ REST API │  │  Web 管理台  │  │
+│  └────┬─────┘  └──────┬──────┘  │
+│       └────────┬───────┘        │
+│          ┌─────▼──────┐         │
+│          │ Core Engine │         │
+│          │ • 用户画像   │         │
+│          │ • Agent 人设 │         │
+│          │ • 共享记忆   │         │
+│          │ • 权限管理   │         │
+│          └─────────────┘         │
+│          ┌─────────────┐         │
+│          │  PostgreSQL  │         │
+│          └─────────────┘         │
+└─────────────────────────────────┘
+       ▲          ▲          ▲
+       │          │          │
+  ┌────┴───┐ ┌───┴────┐ ┌──┴─────┐
+  │OpenClaw│ │ Claude │ │ 任意   │
+  │+ Skill │ │+ Skill │ │ Agent  │
+  └────────┘ └────────┘ └────────┘
+```
+
+## 3. 核心数据模型
+
+### 3.1 用户画像（Profile）
+```json
+{
+  "userId": "user_xxx",
+  "layers": {
+    "identity": { "name": "邱展悦", "language": "zh-CN", "timezone": "Asia/Shanghai" },
+    "preferences": { "communication_style": "direct", "tech_stack": ["TypeScript", "React"] },
+    "context": { "current_projects": ["swarm-ai", "repurpose-ext"], "mood": "focused" }
+  }
+}
+```
+
+### 3.2 Agent 人设（Persona）
+```json
+{
+  "agentId": "peon",
+  "name": "Peon",
+  "personality": "直接、实在、不废话",
+  "instructions": "先动手再开口，说实话哪怕不好听",
+  "constraints": ["不泄露私人数据", "破坏性操作先问"]
+}
+```
+
+### 3.3 共享记忆（Memory）
+```json
+{
+  "key": "project_repurpose_pivot",
+  "content": "Repurpose 从 Next.js 网站转为 Chrome 插件",
+  "source": "agent:peon",
+  "tags": ["project", "decision"],
+  "createdAt": "2026-02-19T00:00:00Z"
+}
+```
+
+## 4. API 设计
+
+### 认证
+- API Key per agent：`Authorization: Bearer swarm_xxx`
+- 每个 key 绑定 agent 身份和权限范围
+
+### 端点
+```
+GET    /api/v1/profile              # 读取用户画像
+PATCH  /api/v1/profile              # 更新画像字段
+POST   /api/v1/profile/observe      # 提交观察（agent 推断）
+
+GET    /api/v1/persona/:agentId     # 读取 agent 人设
+GET    /api/v1/persona/me           # 读取当前 agent 人设
+
+GET    /api/v1/memory               # 查询共享记忆
+POST   /api/v1/memory               # 写入记忆条目
+GET    /api/v1/memory/search?q=     # 语义搜索记忆
+```
+
+## 5. Agent Skill 集成
+
+Skill 是一个目录，包含：
+```
+swarm-ai-skill/
+├── SKILL.md          # 教 agent 怎么用（集成文档）
+├── scripts/
+│   └── setup.sh      # 可选：自动配置
+└── examples/
+    └── usage.md      # 使用示例
+```
+
+SKILL.md 核心内容：
+1. 什么是蜂群 AI（一句话）
+2. 认证方式（API Key 从哪拿）
+3. 会话开始时：调 GET /profile 和 GET /persona/me
+4. 交互中：有新发现时调 POST /profile/observe
+5. 需要历史上下文时：调 GET /memory/search
+
+## 6. Web 管理界面
+
+### P0 功能
+- 用户注册/登录
+- 画像编辑（三层可视化编辑）
+- Agent 管理（添加 agent、分配 API Key、设置权限）
+- 记忆浏览和管理
+
+### P1 功能
+- Agent 人设编辑器
+- 画像变更历史
+- API 调用日志/审计
+- 数据导入/导出
+
+## 7. 技术栈（建议）
+
+- **后端**：Node.js + Express/Fastify
+- **数据库**：PostgreSQL（画像+记忆）+ pgvector（语义搜索）
+- **前端**：React + Tailwind（管理界面）
+- **部署**：Docker compose（自托管）/ Vercel + Supabase（云托管）
+- **认证**：JWT + API Key
+
+## 8. MVP 范围（P0-alpha，2-4 周）
+
+- [ ] 服务器：REST API（画像 CRUD + 记忆 CRUD）
+- [ ] 认证：API Key 基础认证
+- [ ] 管理界面：最简画像编辑 + Agent 管理
+- [ ] Skill：OpenClaw Agent Skill（SKILL.md + 示例）
+- [ ] 集成：Peon 作为第一个接入的 agent
+
+**不做**：语义搜索、E2E 加密、多用户、agent 人设管理
+
+## 9. 待辩论问题（Round 2）
+
+1. **自托管 vs 云托管优先**：先做 Docker 自托管还是先做云服务？
+2. **Skill 通用性**：SKILL.md 只能教会支持 Skill 的 agent（如 OpenClaw），其他 agent 怎么办？
+3. **数据安全**：服务器存储明文画像，安全性如何保证？
+4. **定价**：自托管免费 + 云托管收费？还是按 API 调用量收费？
+5. **与 MCP 的关系**：API 是否同时暴露为 MCP Server？
+6. **市场时机**：现在做这个方向，竞争对手有谁？
+
+---
+
+*v0.2 | 2026-02-20 | 方向：Server + Skill | 作者：Peon ⛏️*