omnispindle

Omnispindle

一个美妙地、有意搞错了方向的待办系统。

Omnispindle 是 Madness Interactive 生态系统的协调中枢——一个包含 38 个工具的 Python FastMCP MCP 服务，让 AI Agent 可以通过统一的标准化接口管理任务、记录知识、协调会话、跟踪史诗目标（任务），并浏览整个工作坊。已打包发布到 PyPI。已集成 Auth0。只要有 MCP 配置文件，就能运行。

它最初只是“把待办事项做好”。后来成了一个多项目、AI 辅助开发实验室的中枢神经系统。这两种情况都挺好。

---

它实际能做什么

待办事项管理——枯燥的部分，却让其他一切成为可能。Agent 可以在生态系统内的任何项目中创建、查询、更新、完成和审计任务，并使用完整的元数据、优先级、目标 Agent 跟踪和变更检测。

知识记录——存储带有语言、主题和标签元数据的经验教训。支持通过正则表达式、文本或向量嵌入进行搜索。对话结束后，组织记忆也不会随之消失。

会话跟踪——Inventorium 中的 AI 工作会话可以派生、生成、关联待办事项，并通过完整的谱系树追踪。每条工作线都有自己的父级和谱系。

语义搜索——find_relevant 使用向量嵌入，按含义而非仅按关键词检索相关待办事项和经验教训。get_context_bundle 一次调用即可为 Agent 提供完整的项目概况。

---

安装

pip install omnispindle

安装后可使用的 CLI 命令：

• omnispindle-stdio — 供 Claude Desktop 使用的 MCP stdio 服务
• omnispindle / omnispindle-server — 用于经过身份验证的端点的 HTTP Web 服务

Claude Desktop（零配置）

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "omnispindle": {
      "command": "omnispindle-stdio",
      "env": {
        "OMNISPINDLE_MODE": "api",
        "OMNISPINDLE_TOOL_LOADOUT": "basic",
        "MCP_USER_EMAIL": "[email protected]"
      }
    }
  }
}

首次调用工具时，会打开浏览器进行 Auth0 登录。令牌会保存在本地。就这么简单。

开发

git clone https://github.com/DanEdens/Omnispindle.git
cd Omnispindle
pip install -r requirements.txt
python -m src.Omnispindle.stdio_server

---

工具

完整配置包含 7 个类别、共 38 个工具。使用 OMNISPINDLE_TOOL_LOADOUT 控制可用工具，以及 Agent 的令牌预算。

待办事项管理（9 个工具）

工具	功能
add_todo	创建任务，并设置项目、优先级、目标 Agent、备注和元数据
query_todos	使用 MongoDB 风格的筛选条件进行查询，支持投影、数量限制、偏移量、since 变更检测，以及用于遍历依赖子图的 graph_root
update_todo	更新任意字段；元数据会进行深度合并。支持对数组字段（例如 metadata.blockers）使用 $push/$pull，以关联依赖项
delete_todo	删除任务
get_todo	按 ID 获取单个任务
complete_todo	可选添加评论并提交审核；写入审计日志。会将状态设为 review，而非 completed
list_todos_by_status	按状态筛选：pending initial in_progress blocked review completed
search_todos	对分词后的多词文本进行模糊搜索
list_project_todos	查看特定项目的近期任务

知识 / 经验教训（7 个工具）

工具	功能
add_lesson	记录经验教训，并设置语言、主题和标签
get_lesson	按 ID 获取
update_lesson	更新经验教训的内容或元数据
delete_lesson	删除
search_lessons	搜索经验教训各字段中的文本
grep_lessons	使用正则表达式模式搜索
list_lessons	浏览所有经验教训，并提供简要模式以显示摘要

Inventorium 会话（8 个工具）

工具	功能
inventorium_sessions_list	列出会话，可按项目筛选
inventorium_sessions_get	按 ID 获取会话
inventorium_sessions_create	开始新的 AI 工作会话
inventorium_sessions_spawn	从父会话派生子会话，并关联到待办事项
inventorium_sessions_fork	分叉会话，可选择继承消息
inventorium_sessions_genealogy	查看会话完整的祖先和后代关系
inventorium_sessions_tree	查看项目的可视化会话树
inventorium_todos_link_session	将待办事项关联到会话

Quest 系统（5 个工具）

工具	功能
create_quest	创建史诗目标容器（Quest → Chains → Todos）。多步骤目标请使用此工具，而非 add_todo
check_quest	进度报告：完成百分比、各链状态、后续操作和阻碍因素。用于帮助 Agent 熟悉情况
list_quests	按状态或项目筛选并列出 Quest
link_quest	将现有待办事项追溯添加到 Quest 链中（按需创建链）
update_quest	更新 Quest 字段：名称、描述、状态、成功标准、元数据

上下文与搜索（4 个工具）

工具	功能
get_context_bundle	一次调用即可获取近期待办事项、经验、会话状态和项目统计信息，供 Agent 构建工作上下文
find_relevant	在待办事项和经验中进行语义相似度搜索。如果没有内容达到相关性阈值，则如实返回空结果，不使用正则表达式兜底制造噪声
preflight_rag	任务前经验检查：开始工作前调用，用于区分以往的解决方案和陷阱
write_agent_journal / read_agent_journal	持久化 Agent 日志——留下其他 Agent 可读取的备注，以便 Agent 之间协调

系统 / 管理（5 个工具）

工具	功能
query_todo_logs	查询审计日志：按类型、项目和日期范围筛选
list_projects	列出文件系统中已知的项目
explain / add_explanation	主题说明系统：持久化知识卡片
point_out_obvious	记录观察结果，并可配置讽刺程度。适用于自动运行期间标记已知问题。

自定义代码（1 个工具）

工具	功能
bring_your_own	在运行时将 Python、JavaScript 或 shell 函数注入为实时 MCP 工具

---

工具组合

设置 OMNISPINDLE_TOOL_LOADOUT 以控制注册的工具：

组合	工具数	用途
full	38	全部功能
basic	15	核心待办事项 CRUD + 上下文 + Quest 系统
minimal	4	添加、查询、获取、标记为已完成
lessons	8	仅知识管理
admin	16	管理任务 + 会话管理
write_only	6	仅创建、更新和删除
read_only	16	仅查询和获取
lightweight	13	针对令牌使用优化的核心功能
agent_preflight	6	会话启动：上下文包、RAG 检查、待办事项操作
refine	13	待办事项完善：审计 + 补充缺失的元数据

---

操作模式

通过 OMNISPINDLE_MODE 设置：

• api — 向 madnessinteractive.cc/api 发送 HTTP 请求。无需本地数据库。最适合云原生或多用户配置。
• hybrid （默认） — 优先使用 API，并以 MongoDB 作为后备。网络不可用时也可靠。
• local — 仅直接连接 MongoDB。适用于离线开发。
• auto — 对两种模式进行基准测试，并选择更快的一种。

---

身份验证

零配置设备流程：首次调用工具时，浏览器窗口会打开以进行 Auth0 登录。令牌将保存在本地。之后的所有调用都会自动完成身份验证，无需任何配置。

手动设置令牌（可选）：

python -m src.Omnispindle.token_exchange

环境变量：

• MADNESS_AUTH_TOKEN 或 AUTH0_TOKEN — 来自 Auth0 设备流程的 JWT
• MCP_USER_EMAIL — 按用户隔离数据时必需
• MADNESS_API_URL — 覆盖 API 基础地址（默认值：https://madnessinteractive.cc/api）

所有数据都在数据库层按用户隔离。你的待办事项只属于你。

---

配置

# Operation mode
OMNISPINDLE_MODE=hybrid          # api | hybrid | local | auto
OMNISPINDLE_TOOL_LOADOUT=basic   # see loadouts table above
OMNISPINDLE_FALLBACK_ENABLED=true
OMNISPINDLE_VALIDATE_PROJECT_NAMES=false  # optional: enable slower DB-backed project validation

# Authentication
MADNESS_AUTH_TOKEN=<jwt>
[email protected]

# Local/hybrid database
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=swarmonomicon

# Real-time events
MQTT_HOST=localhost
MQTT_PORT=1883

---

生态系统

Omnispindle 是 AI 接口层。工作坊的其他部分：

Inventorium — React Web 仪表板和 SwarmDesk 3D 空间工作区。供人类使用。它通过 REST API 直接读取待办事项和会话，而不是 MCP；MCP 专供 AI Agent 使用。如果你在点击按钮，你就在使用 Inventorium。如果你是 Agent，你就在调用 MCP 工具。

cartogomancy — JS/TS 代码库分析工具（npm install -g @madnessengineering/cartogomancy）。将它指向任意 JavaScript 或 TypeScript 项目，即可获取包含结构、复杂度、git blame 和交叉引用的详细 JSON 映射。将映射交给 SwarmDesk，你的代码库就会变成一座可供漫步的 3D 城市。

SwarmDesk — Inventorium 内的 3D 空间可视化层。待办事项、会话和 cartogomancy 代码映射会被渲染成可探索的架构。让你的项目成为一个地方，而不是一份清单。

MadnessVR — SwarmDesk 的 Quest 2 VR 版本。戴上头显，就能以真实几何形态漫步于代码库之中。它在路线图中，而不在发行说明里。但计划已经制定，而且细节完备。

MadQTT — 工作坊 MQTT + MongoDB 事件流的实时终端 TUI（pip install madqtt）。来自所有机器的 Agent 会话、工具调用和故障都能实时查看，无需面对信息洪流。

Madness Desktop — 深度接入工作坊的 GitHub Desktop 分支：可组合的 git-hook 配置、在多台机器间共享的 MQTT 提交事件，以及集成在 git 客户端中的实时工作坊待办事项。

Swarmonomicon — 核心数据库层。MongoDB，swarmonomicon 数据库。所有持久化数据都存放于此。

架构规则

UI (Inventorium, forms, dashboards) → REST API → Database
AI agents (Claude, any MCP client) → MCP tools → Backend → Database

绝不通过 MCP 转发 UI。绝不让 AI Agent 直接调用 REST API。这样的分离是有意设计的，也是架构的关键支柱。

---

开发

# Tests
pytest tests/

# Stdio server (Claude Desktop)
python -m src.Omnispindle.stdio_server

# Web server
python -m src.Omnispindle

# Check tool count
python -c "from src.Omnispindle.tool_loadouts import _BASE_LOADOUTS; print(len(_BASE_LOADOUTS['full']), 'tools in full loadout')"

PyPI 发布

# Build and check
python -m build
python -m twine check dist/*

# Publish
python -m twine upload dist/*

---

隐私与安全

此仓库包含我们生态系统的 Auth0 配置和基础设施即代码。它以开源形式提供，供学习和派生使用，并非可直接部署的成品。

如果你要为自己的环境实际运行它：

1. Fork 此仓库
2. 替换所有身份验证提供方和凭据
3. 将其指向你自己的域名和数据库
4. 检查工具权限（默认情况下，我们采用宽松设置）

这是为我们的实验室运行的系统。用于你的环境时，请按需改造。

---

理念

目前可用：

• 面向 AI Agent 的待办事项管理——健壮、经过审计、按用户隔离
• 跨项目的持久化知识捕获
• 带完整溯源信息的会话跟踪
• 通过向量嵌入实现语义搜索
• 零配置 Auth0，无需查阅设置指南

即将推出：

• MadnessVR：Quest 2 上的 SwarmDesk
• 通过 Terraria 风格的库存机制教授提示词工程
• cartogomancy → SwarmDesk → VR，构成一条连续的流水线

我们编写严谨的代码。只要切实可行，我们就勇于突破边界。

---

“过度设计？也许吧。缺乏雄心？绝不。”