spindle (Spiritengine)

纺锤

用于多线束AI代理委托的MCP服务器。生成异步运行的后台代理（Claude Code、Codex、Gemini、Kimi），具有可选的git工作树隔离功能，可实现安全的并行工作。

特性

• 异步代理生成 -带假脱机ID的即发即弃模式
• 可选择使用聚集/屈服进行阻断 -立即等待所有结果，或在代理完成时将其流式传输。或者，代理可以继续其他工作，默认情况下旋转是非阻塞的
• 权限配置文件 -控制子代理可以使用的工具（只读、小心、完整）
• 碎片隔离 -在沙盒git工作树中运行代理以防止冲突
• 模型选择 -为每个代理将任务路由到不同的模型
• 会话连续性 -恢复与子代理的对话（自动恢复过期的会话）
• 丰富的查询 -搜索、筛选、查看正在运行的输出、导出结果

需求

• Python 3.10+
• Claude CLI 已安装并验证
• Git（用于分片/工作树功能）

安装

pip install spindle-mcp

添加到Claude Code的MCP配置中(~/.claude.json):

{
  "mcpServers": {
    "spindle": {
      "command": "spindle"
    }
  }
}

用法

基础：繁殖和收集

# Spawn an agent
spool_id = spin("Research the Python GIL")

# Do other work...

# Check result
result = unspool(spool_id)

权限配置文件

控制生成的代理可以使用哪些工具：

# Read-only: Can only search and read
spin("Analyze the codebase", permission="readonly")

# Careful (default): Can read/write but limited bash
spin("Fix this bug", permission="careful")

# Full access: No restrictions
spin("Implement the feature", permission="full")

# Shard: Full access + auto-isolated worktree (common for risky work)
spin("Refactor the auth system", permission="shard")

# Careful + shard: Limited tools but isolated
spin("Update configs", permission="careful+shard")

配置文件：

• readonly：读取、Grep、Glob、安全bash（ls、cat、git状态/log/diff）
• careful：读取、写入、编辑、Grep、Glob、bash for git/make/pytest/python/npm
• full：无限制
• shard：完全访问+自动创建独立的工作台
• careful+shard：谨慎的权限+自动创建隔离的工作树

您还可以传递显式 allowed_tools 以覆盖配置文件。

带有分片的独立工作区

在隔离的git工作树中运行代理以防止冲突：

# Agent works in its own worktree
spool_id = spin("Refactor auth module", shard=True)

# Check shard status
shard_status(spool_id)

# Merge changes back when done
shard_merge(spool_id)

# Or discard if not needed
shard_abandon(spool_id)

Shards创建一个git工作树+分支。如果SKEIN可用，则使用 skein shard spawn 更丰富的跟踪。否则，就回到普通的git工作台上。

等待完成

# Spawn multiple agents
id1 = spin("Find all TODO comments")
id2 = spin("List unused imports")
id3 = spin("Check for type errors")

# Gather: block until all complete, get all results
results = spin_wait("id1,id2,id3", mode="gather")

# Yield: return as each completes
# Great when results are independent - process each as it lands
result = spin_wait("id1,id2,id3", mode="yield")  # Returns first to finish

# With timeout
results = spin_wait("id1,id2", mode="gather", timeout=300)

Yield模式使您保持响应，而不是阻塞最慢的代理。

基于时间的等待

简单的定时等待 spin_sleep:

spin_sleep("90m")       # Sleep for 90 minutes
spin_sleep("2h")        # Sleep for 2 hours
spin_sleep("30s")       # Sleep for 30 seconds
spin_sleep("06:00")     # Wait until 6 AM

或使用 spin_wait 随着 time 参数：

spin_wait(time="90m")
spin_wait(time="06:00")  # Handles next-day wraparound

适用于定期签到循环（例如QM/舞伴模式）。

型号选择和超时

# Route quick tasks to haiku (fast, cheap)
spin("Summarize this file", model="haiku")

# Complex work to opus
spin("Design the new architecture", model="opus")

# Auto-kill if it takes too long
spin("Should be quick", timeout=60)

继续会话

# Get session ID from completed spool
result = unspool(spool_id)  # includes session_id

# Continue that conversation
new_id = respin(session_id, "Follow up question")

如果会话在Claude结束时已过期，respin会自动回退到转录注入以重新创建上下文。

取消正在运行的工作

spin_drop(spool_id)

列出所有线轴

spools()

搜索和筛选

# Search prompts and results
spool_search("authentication")

# Filter by status and time
spool_results(status="error", since="1h")

# Regex search results
spool_grep("error|failed|exception")

# Get statistics
spool_stats()

# Export to file
spool_export("all", format="md")

多线束支架

Spindle支持多个AI代理线束，允许您为每个任务选择最佳工具。

可用线束

克劳德代码 （默认）-Anthropic的克劳德模型通过 claude 命令行界面

• 卓越的代码理解和推理能力
• 最适合复杂的重构、架构决策
• 启动速度较慢（距离首次响应约3-4分钟）
• 使用 harness="claude-code" 或省略线束参数

Codex CLI -OpenAI的GPT-5 Codex模型通过 codex 命令行界面

• 启动速度极快（约10秒至首次响应）
• 适合快速编辑、简单任务、原型制作
• 需要ChatGPT Plus/Pro/Enterprise
• 使用 harness="codex"

Gemini CLI -谷歌的Gemini模型通过 gemini 命令行界面

• 快速启动（约5-10秒到第一次响应）
• 具有工具使用、文件访问和多步推理功能的完整代理
• 慷慨的免费套餐（使用谷歌帐户每天1000次）
• 模型： "flash", "pro"，或任何完整型号名称
• 使用 harness="gemini"

化学CLI -Moonshot AI的Kimi模型 kimi-cli

• 快速启动（约5-10秒到第一次响应）
• 复杂推理的思维方式
• 模型： "thinking", "thinking-turbo", "turbo", "latest"，或任何完整型号名称
• 使用 harness="kimi"

基本用法

# Claude Code (default) - best for complex work
spool_id = spin("Refactor the auth module to use dependency injection")

# Codex CLI - fast for simple tasks
spool_id = spin(
    prompt="Add error handling to this function",
    harness="codex",
    working_dir="/path/to/project"
)

# Gemini CLI - fast with free tier
spool_id = spin(
    prompt="Summarize this codebase",
    harness="gemini",
    working_dir="/path/to/project"
)

# Kimi CLI - fast reasoning with thinking mode
spool_id = spin(
    prompt="Analyze this bug",
    harness="kimi",
    working_dir="/path/to/project"
)

# All harnesses use the same API
result = unspool(spool_id)  # Auto-detects harness

选择安全带

在以下情况下使用克劳德代码：

• 任务需要深入的推理或架构决策
• 跨多个文件进行复杂的重构
• 需要彻底的代码审查或分析

在以下情况下使用Codex：

• 需要快速编辑或简单实现
• 快速原型制作或探索想法

在以下情况下使用Gemini：

• 想要快速的结果没有API密钥管理（谷歌帐户登录）
• 在预算范围内运行许多并行任务（免费层）
• 需要一个快速的通用代理

在以下情况下使用Kimi：

• 需要快速复杂推理的思维方式
• 希望快速启动，具有强大的推理能力

需求

克劳德代码：

• Claude CLI 已安装并验证

Codex CLI：

• Codex CLI 已安装(npm i -g @openai/codex)
• ChatGPT Plus/Pro/企业订阅

Gemini CLI：

• Gemini CLI 已安装(npm i -g @google/gemini-cli)
• Google帐户登录(gemini → “使用谷歌登录”）或 GEMINI_API_KEY env 是

CLI类型：

• 化学CLI 已安装(pip install kimi-cli)
• 通过验证 kimi-cli login 或API密钥 ~/.kimi/config.toml

看 docs/MULTI_HARNES_GUIDE.md 和 docs/CODEX_SETUP.md 详细文档。

API

统一API（适用于所有线束）

spin（）参数：

• prompt （必填）：代理人的任务
• harness （可选）：“克劳德代码”（默认）、“codex”、“gemini”或“kimi”
• working_dir （Claude可选，Codex/Gemini/Kimi必需）：项目目录
• permission （可选）：“只读”、“小心”（默认）、“完整”、“分片”、“谨慎+分片”
• model （可选）：使用模型（克劳德用“十四行诗”、“小品”、“俳句”；双子座用“flash”、“pro”；基米用“thinking”、“turbo”）
• timeout （可选）：N秒后自动终止
• tags （可选）：逗号分隔的组织标签
• shard （可选）：创建隔离的git工作树（也可以使用 permission="shard")
• system_prompt （可选）：克劳德代码的自定义系统提示
• allowed_tools （可选）：用明确的工具列表覆盖权限配置文件

滑阀管理（适用于所有线束）

存储

孢子持续存在 ~/.spindle/spools/{spool_id}.json:

{
  "id": "abc12345",
  "status": "complete",
  "prompt": "...",
  "result": "...",
  "session_id": "...",
  "permission": "careful",
  "allowed_tools": "...",
  "tags": ["batch-1"],
  "shard": {
    "worktree_path": "/path/to/worktrees/abc12345-...",
    "branch_name": "shard-abc12345-...",
    "shard_id": "..."
  },
  "pid": 12345,
  "created_at": "2025-11-26T...",
  "completed_at": "2025-11-26T..."
}

CLI命令

spindle install-service  # Install background service (Linux/macOS)
spindle start            # Start via systemd (or background if no service)
spindle reload           # Restart via systemd to pick up code changes
spindle status           # Check if running (hits /health endpoint)
spindle serve --http     # Run MCP server directly

后台服务

对于持久后台操作：

# Install and enable the service (Linux or macOS)
spindle install-service

# Start it
spindle start

Linux：将systemd用户服务写入 ~/.config/systemd/user/spindle.service

macOS：将launchd plist写入 ~/Library/LaunchAgents/com.spindle.server.plist 并立即加载

使用 --force 覆盖现有的服务文件。然后 spindle reload 重新启动服务以获取代码更改。

视窗

在Windows上，手动运行主轴：

spindle serve --http

或使用 国家安全研究备忘录 创建Windows服务。

WSL

在启用systemd的WSL2中， spindle install-service 像原生Linux一样工作。如果systemd未启用，您将收到启用或手动运行它的说明。

热重新加载（MCP工具）

在Claude Code内部，致电 spindle_reload() 重新启动服务器并获取代码更改。

配置

环境变量：

存储位置： ~/.spindle/spools/

运作原理

1. spin（） 使用给定的提示符生成一个分离的CLI进程（claude、codex、gemini或kimi CLI）
2. 该进程在后台运行，将输出写入临时文件
3. 监视器线程轮询完成情况
4. unpol（） 完成后返回结果（非阻塞检查）
5. Spool元数据持久化为JSON文件，幸存的服务器重新启动

对于碎片：

1. 使用新分支创建git工作树
2. 特工在那台工作台里跑
3. 完成后，合并回 shard_merge() 或丢弃 shard_abandon()

限制

• 最多15个并发线轴（可通过以下方式配置 SPINDLE_MAX_CONCURRENT)
• 24小时自动清理旧线轴
• 重新启动时标记为错误的孤立假脱机（死进程）

贡献

看 贡献.md 用于开发设置和指南。

许可证

麻省理工学院-见 许可证.