Hivemind

🚀 Hivemind研究文档索引

Hivemind是一个MCP服务器，它通过Obsidian为AI工具提供规范的世界构建上下文。本目录包含了关于Hivemind的全面研究和规划文档。

关键洞察：Hivemind是Obsidian（世界构建者工作的地方）和Claude/AI工具（需要一致上下文的工具）之间的“桥梁”，并非要取代其中任何一方。

📄 文档介绍

1. 📋 FEATURES.md（40 KB - 主要研究文档）

全面的功能研究文档

涵盖内容：

• 核心MCP功能（工具、资源、提示、查询模式、最佳实践）
• Obsidian库功能（文件夹结构、模板、元数据模式、关系建模）
• AI上下文交付（特定任务上下文、角色一致性、位置/时间线上下文、资产引用）
• 规范管理（草稿→审批工作流程、版本控制、冲突解决、验证）
• 资产来源（ComfyUI工作流程、元数据跟踪、可重复性）
• 功能优先级（MVP功能、0.2版本及以上的可选功能、1.0版本及以上的未来功能、超出范围的功能）

阅读时机：想要全面了解系统设计和功能时。

阅读时长：30 - 45分钟

2. 🎯 RESEARCH_SUMMARY.md（8 KB - 快速参考文档）

关键研究结果的执行摘要

包含内容：

• 各主要领域的高层次研究结果
• 设计决策及理由
• 风险评估与缓解措施
• 实施路线图阶段
• 来源验证

阅读时机：想快速了解研究验证的内容及原因时。

阅读时长：5 - 10分钟

3. ✅ IMPLEMENTATION_CHECKLIST.md（12 KB - 可操作文档）

分阶段实施指南

包含内容：

• MVP清单（0.1版本）
• 第一阶段详细任务（第1 - 2周）
• 第二阶段扩展任务（第3 - 4周）
• 第三阶段完善任务（第5周及以后）
• 可复制的代码模式
• 成功标准

阅读时机：想了解要构建的内容及构建顺序时。

阅读时长：10 - 15分钟

4. 🏗️ ARCHITECTURE.md（在库中）

系统设计和组件图

查看路径：.planning/research/ARCHITECTURE.md

5. 📚 STACK.md（在库中）

技术选择及理由

查看路径：.planning/research/STACK.md

按角色快速导航

👨‍💻 开发者：“我如何构建这个项目？”

1. 起步：阅读RESEARCH_SUMMARY.md（了解范围）
2. 深入研究：阅读FEATURES.md中的“核心MCP功能”和“Obsidian库功能”部分
3. 开始构建：参考IMPLEMENTATION_CHECKLIST.md
4. 参考资料：阅读FEATURES.md中的“查询模式”部分以进行API设计

🏛️ 架构师：“整体设计是怎样的？”

1. 总体了解：阅读RESEARCH_SUMMARY.md
2. 设计细节：阅读ARCHITECTURE.md
3. 功能范围：阅读FEATURES.md中的“功能优先级”部分
4. 约束条件：阅读FEATURES.md中的“超出范围”部分

🧪 测试人员：“我应该测试什么？”

1. 测试范围：阅读IMPLEMENTATION_CHECKLIST.md中的“测试与验证”部分
2. 成功标准：参考IMPLEMENTATION_CHECKLIST.md
3. 数据格式：阅读FEATURES.md中的“Obsidian库功能”部分
4. 边缘情况：阅读FEATURES.md中的“风险与缓解措施”部分

📝 产品经理：“项目愿景是什么？”

1. 快速概览：阅读RESEARCH_SUMMARY.md
2. MVP范围：阅读FEATURES.md中的“功能优先级”部分→MVP
3. 路线图：阅读RESEARCH_SUMMARY.md中的“实施路线图”部分
4. 风险：阅读RESEARCH_SUMMARY.md中的“风险与缓解措施”部分

🎨 设计师：“用户体验是怎样的？”

1. 系统概述：阅读FEATURES.md中的“MCP是什么”部分
2. 用户工作流程：阅读FEATURES.md中的“规范管理”部分
3. 数据模板：阅读FEATURES.md中的“笔记类型与模板”部分
4. 上下文示例：阅读FEATURES.md中的“AI上下文交付”部分

关键研究结果（简版）

✅ 已验证的内容

• MCP可以在不修改Obsidian的情况下公开世界构建数据
• Obsidian的YAML和维基链接足以进行关系建模
• Claude的200K令牌上下文窗口足以提供世界上下文
• 现有工具（ComfyUI、Dataview）无需重新实现即可集成
• 基于Git的审批工作流程适用于协作式世界构建

🎯 已做出的设计决策

1. 单一事实来源：Obsidian库（而非外部数据库）
2. 架构：MCP服务器作为只读桥梁
3. 关系：通过维基链接和YAML元数据实现双向关系
4. 审批：基于Git（主分支 = 规范，功能分支 = 提案）
5. 资产：在图像中嵌入元数据；版本工作流程

📊 功能范围

• MVP（0.1版本）：基本查询、模板、手动审批
• 0.2 - 0.3版本：过滤查询、一致性检查、ComfyUI集成
• 1.0版本及以上：多世界、Web UI、协作功能

🚫 超出范围的内容

• 取代Obsidian（它不是编辑器）
• 外部存储（库是事实来源）
• 任意代码执行
• 自动生成完整世界
• 实时多人编辑

整体架构

用户（世界构建者）
        ↓
Obsidian库（事实来源）
        ↓
Git仓库（版本控制）
        ↓
Hivemind MCP服务器（桥梁）
        ↓
Claude / AI工具（上下文消费者）

数据流：

1. 世界构建者在Obsidian中编辑角色/地点
2. 更改提交到Git
3. Hivemind MCP服务器从Git读取数据
4. Claude向MCP查询上下文
5. Claude生成一致的内容（对话、图像、情节）
6. 结果返回给世界构建者

研究来源

2025年1月进行的研究使用了以下资源：

• 1000多个MCP服务器示例（MCPMarket.io）
• 5个以上的Obsidian世界构建库模板
• 官方MCP文档（modelcontextprotocol.io）
• Claude API文档（platform.claude.com）
• ComfyUI工作流程文档
• 领先的世界构建工具（World Anvil、Reality Forge、Urdr）

实施时间表（预估）

成功指标

MVP成功标准

• ✅ Claude可以查询角色数据
• ✅ 上下文保持在令牌限制内
• ✅ 一致性检查正常工作
• ✅ 模板易于使用
• ✅ 审批工作流程正常运行

1.0版本成功标准

• ✅ 多用户协作式世界构建
• ✅ 平稳处理1000多个实体
• ✅ 用于浏览的Web界面
• ✅ 完整的资产来源跟踪
• ✅ 社区采用（外部库）

实施中的开放性问题

1. MCP运行时选择（TypeScript、Python、Rust？）

   • 决策点：语言专业知识、部署目标

2. 如何处理库更改（Git钩子、轮询、文件监视器？）

   • 设计点：延迟与系统负载

3. 缓存位置（进程内、Redis、持久文件？）

   • 性能点：内存与响应性

4. 如何验证一致性（严格规则还是警告？）

   • 用户体验点：有用与烦人

5. 何时集成ComfyUI（0.1版本、0.2版本、1.0版本？）

   • 范围点：复杂性与达到MVP的时间

答案可查看IMPLEMENTATION_CHECKLIST.md中的“要创建的关键文件”部分。

贡献文档

更新文档时：

• 保持FEATURES.md作为规范的详细参考文档
• 将摘要同步到RESEARCH_SUMMARY.md
• 范围更改时更新清单
• 将新发现添加到适当的部分
• 保证代码示例与实现保持同步

最后更新时间：2025年1月
状态：✅ 完成研究阶段
下一步：实施规划和第一阶段开发