使用说明
全向主轴
一个完美的待办事项系统，故意出错。
Omnispindle是Madness Interactive生态系统的协调核心，它是一个Python FastMCP服务器，有38个工具，可以让AI代理管理任务、获取知识、协调会话、跟踪史诗般的目标（任务），并从一个标准化的界面浏览整个工作坊。PyPI已打包。Auth0已集成。在MCP配置所在的任何地方运行。
它最初是“让我们正确地做待办事项”。它成为了一个多项目人工智能辅助开发实验室的中枢神经系统。这两件事都很好。
它实际上做了什么
待办事项管理 --无聊的部分使其他一切成为可能。代理可以在生态系统中的任何项目中创建、查询、更新、完成和审计任务，并具有完整的元数据、优先级、目标代理跟踪和更改检测。
知识获取 --经验教训与语言、主题和标签元数据一起存储。可通过正则表达式、文本或向量嵌入进行搜索。谈话结束后，机构记忆不会消失。
会话跟踪 --Inventoryum中的AI工作会话可以分叉、生成、链接到待办事项，并通过完整的家谱树进行跟踪。每一项工作都有一个父母和一个血统。
语义搜索 — find_relevant 使用向量嵌入来按意义而不仅仅是关键字来显示待办事项和课程。 get_context_bundle 在一次通话中向代理人提供完整的项目情况。
安装
pip install omnispindle
安装后可用的CLI命令：
omnispindle-stdio--Claude Desktop的MCP stdio服务器omnispindle/omnispindle-server--用于经过身份验证的端点的HTTP web服务器
克劳德桌面（零配置）
增添 claude_desktop_config.json:
{
"mcpServers": {
"omnispindle": {
"command": "omnispindle-stdio",
"env": {
"OMNISPINDLE_MODE": "api",
"OMNISPINDLE_TOOL_LOADOUT": "basic",
"MCP_USER_EMAIL": "you@example.com"
}
}
}
}
第一个工具调用会打开浏览器进行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.
待办事项管理（9个工具）
| 工具 | 它做什么 |
|---|---|
add_todo |
使用项目、优先级、目标代理、注释和元数据创建任务 |
query_todos |
MongoDB风格的带投影、限制、偏移的过滤查询， since 变化检测，以及 graph_root 用于依赖子图遍历 |
update_todo |
修补任何字段；元数据被深度合并。支持 $push/$pull 在数组字段上（例如。 metadata.blockers)用于依赖链接 |
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 |
浏览所有课程，使用简短模式进行总结 |
Inventory会议（8个工具）
| 工具 | 它做什么 |
|---|---|
inventorium_sessions_list |
列出会话，可选择按项目筛选 |
inventorium_sessions_get |
按ID获取会话 |
inventorium_sessions_create |
启动新的人工智能工作会议 |
inventorium_sessions_spawn |
从父节点生成一个子会话，链接到待办事项 |
inventorium_sessions_fork |
使用可选消息继承分叉会话 |
inventorium_sessions_genealogy |
会话的完整祖先/后代跟踪 |
inventorium_sessions_tree |
项目的可视化会话树 |
inventorium_todos_link_session |
将待办事项链接到会话 |
任务系统（5个工具）
| 工具 | 它做什么 |
|---|---|
create_quest |
创建一个史诗级的目标容器（任务→ 链条→ Todos）。使用代替 add_todo 用于多步骤目标 |
check_quest |
进度报告：完成百分比、每条链状态、下一步行动、阻止程序。代理定向工具 |
list_quests |
按状态/项目筛选的任务列表 |
link_quest |
将现有待办事项追溯添加到任务链中（按需创建链） |
update_quest |
更新任务字段：名称、描述、状态、成功标准、元数据 |
上下文和搜索（4个工具）
| 工具 | 它做什么 |
|---|---|
get_context_bundle |
一个调用：最近的待办事项、课程、会话状态、代理工作环境的项目统计数据 |
find_relevant |
跨待办事项和课程的语义相似性搜索。当没有任何内容清除相关性阈值时，返回诚实的空值——没有正则表达式回退噪声 |
preflight_rag |
任务前课程检查：开始工作前打电话，将过去的解决方案与陷阱进行分类 |
write_agent_journal / read_agent_journal |
持久代理日志——为跨代理协调留下其他代理可读的笔记 |
系统/管理（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 | 核心todo CRUD+上下文+任务系统 |
minimal |
4 | 添加、查询、获取、标记完成 |
lessons |
8 | 仅限知识管理 |
admin |
16 | 管理任务+会话管理 |
write_only |
6 | 仅创建/更新/删除 |
read_only |
16 | 仅查询/获取 |
lightweight |
13 | 代币优化核心 |
agent_preflight |
6 | 会话启动：上下文包、RAG检查、todo操作 |
refine |
13 | 待办事项丰富：审计+填补缺失的元数据 |
操作模式
通过设置 OMNISPINDLE_MODE:
api--HTTP调用madnessinteractive.cc/api。不需要本地数据库。最适合云原生或多用户设置。hybrid（默认） -首先使用MongoDB回退的API。当网络不可靠时。local--仅限直接MongoDB连接。适合线下开发。auto--对两者进行基准测试，并选择速度更快的一个。
认证
零配置设备流：在第一次工具调用时，将打开一个浏览器窗口用于Auth0登录。令牌保存在本地。所有后续呼叫都经过身份验证，无需任何配置。
手动设置令牌 （可选）：
python -m src.Omnispindle.token_exchange
环境变量:
MADNESS_AUTH_TOKEN或AUTH0_TOKEN--来自Auth0设备流的JWTMCP_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>
MCP_USER_EMAIL=you@example.com
# Local/hybrid database
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=swarmonomicon
# Real-time events
MQTT_HOST=localhost
MQTT_PORT=1883
生态系统
Omnispindle是AI接口层。研讨会的其余部分：
库存 --React web仪表板和SwarmDesk 3D空间工作区。人类使用这个。它通过REST API直接读取todo和会话，而不是MCP，后者严格适用于AI代理。如果您正在单击按钮，则表示您处于Inventoryum中。如果你是一名代理，你会打电话给MCP工具。
漫画家 --JS/TS代码库分析工具(npm install -g @madnessengineering/cartogomancy).指向任何JavaScript或TypeScript项目；获取结构、复杂性、git责备和交叉引用的丰富JSON映射。将该地图输入SwarmDesk，您的代码库将变成一个您可以穿过的3D城市。
SwarmDesk --Inventoryum内部的三维空间可视化层。Todos、会话和卡通代码地图呈现为可探索的架构。你的项目是一个地方，而不是一个列表。
疯狂VR --任务2 VR版的SwarmDesk。戴上耳机，以实际几何体的形式浏览代码库。这个在路线图上，而不是发行说明上。但该计划确实存在，而且很详细。
Madqtt --研讨会MQTT+MongoDB事件流的实时终端TUI(pip install madqtt).代理会话、工具调用和每台机器的故障，实时可读，而不是消防水带。
疯狂桌面 --GitHub Desktop fork连接到车间：可组合的git挂钩加载、跨机器共享的MQTT提交事件，以及git客户端内的实时车间待办事项。
Swarmonomicon --核心数据库层。MongoDB， swarmonomicon 数据库。一切执着的东西都生活在这里。
架构规则
UI (Inventorium, forms, dashboards) → REST API → Database
AI agents (Claude, any MCP client) → MCP tools → Backend → Database
切勿通过MCP路由UI。切勿直接从人工智能代理调用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配置和基础设施作为我们生态系统的代码。它是开源的，用于学习和分叉，而不是按原样部署。
如果您实际上是为自己的设置运行此程序：
- 分叉它
- 替换所有身份验证提供程序和凭据
- 将其指向您自己的域和数据库
- 检查工具权限（默认情况下我们是允许的）
这是我们实验室的工作系统。对于你的，让它成为你的。
哲学
现在工作：
- 人工智能代理的Todo管理——强大、经过审计、按用户
- 跨项目持续获取知识
- 具有完整沿袭的会话跟踪
- 基于向量嵌入的语义搜索
- 零配置Auth0，不需要安装指南
即将到来：
- 疯狂VR：任务2上的SwarmDesk
- 通过Terraria式库存机制教授快速工程
- 漫画家→ SwarmDesk→ VR作为一条连续的管道
我们编写谨慎的代码。在可行的情况下，我们不怕突破界限。
“过度设计？也许吧。野心勃勃？从来没有。”
