Systemprompt Code Orchestrator

🚀 SystemPrompt Coding Agent

SystemPrompt Coding Agent 是一個前沿項目，可將你的工作站轉變為可遠程訪問的 MCP（模型上下文協議）服務器，任何 MCP 客戶端都能與之連接。它是 SystemPrompt.io 生態系統的一部分，該生態系統正為開發者開創原生移動語音控制的 AI 編排技術。

🚀 快速開始

前提條件

設置腳本將自動檢查以下內容：

• Node.js 18+（必需）
• Docker 與 Docker Compose（必需）
• Claude Code CLI（可選但推薦 - 設置腳本將為你提供指導）

必備命令

npm run start    # 啟動所有服務（守護進程 + Docker）
npm run stop     # 優雅地停止所有服務
npm run status   # 檢查服務健康狀況
npm run logs     # 查看實時日誌
npm run tunnel   # 通過互聯網隧道啟動（需要 Cloudflare）

必備配置

# 必需（設置時會提示）
PROJECT_ROOT=/path/to/your/code  # ⚠️ AI 代理在此處擁有完全訪問權限

# 可選（有默認值）
PORT=3000
COMPOSE_PROJECT_NAME=systemprompt-coding-agent

# 可選（用於額外功能）
CLOUDFLARE_TOKEN=your_token  # 用於隧道訪問
PUSH_TOKEN=your_token        # 用於移動通知

操作步驟

# 克隆並設置
git clone https://github.com/systempromptio/systemprompt-code-orchestrator
cd systemprompt-code-orchestrator

# 安裝並運行
npm i 
npm run setup
npm run start

# 使用檢查器進行測試
npm run inspector

使用檢查器創建的任務應通過隧道連接到你的 Claude Code 安裝，將結構化日誌保存在 Docker 容器內（作為 MCP 資源公開），並允許通過檢查器（以及任何 MCP 客戶端）執行。

✨ 主要特性

🤖 AI 代理編排

• 多代理支持：默認支持 Claude Code CLI，可擴展支持任何代理
• 任務管理：創建、跟蹤和管理編碼任務 - 任務管理 →
• 會話隔離：每個任務在其自己的上下文中運行 - Claude 集成 →
• 實時流：實時觀看 AI 代理工作 - 事件系統 →

📱 移動優先設計

• 語音命令：例如“創建一個帶有驗證的登錄表單”
• 推送通知：任務完成時獲得提醒 - 推送通知 →
• 快速操作：常見任務的預定義模板 - 提示模板 →
• 遠程控制：隨時隨地管理你的開發環境

🔧 MCP 協議特性

• 持久狀態：任務在服務器重啟後仍然存在 - 狀態持久化 →
• 資源管理：將任務數據作為 MCP 資源公開 - 工具與資源 →
• 交互式提示：AI 代理可以請求澄清
• 進度通知：實時狀態更新
• 結構化數據：完整的模式驗證 - MCP 服務器 →

📦 安裝指南

此項目需要進行一系列安裝和配置步驟，以下是詳細的安裝過程：

1. 克隆項目倉庫：

git clone https://github.com/systempromptio/systemprompt-code-orchestrator
cd systemprompt-code-orchestrator

2. 安裝依賴：

npm i 

3. 進行設置：

npm run setup

4. 啟動服務：

npm run start

💻 使用示例

基礎用法

# 克隆並設置
git clone https://github.com/systempromptio/systemprompt-code-orchestrator
cd systemprompt-code-orchestrator

# 安裝並運行
npm i 
npm run setup
npm run start

# 測試檢查器
npm run inspector

高級用法

npm run tunnel  # 通過互聯網隧道啟動（需要 Cloudflare）

📚 詳細文檔

核心架構

• 守護進程 - 主機端的橋樑，執行命令並管理 Claude 進程
• Docker 架構 - Docker 容器與主機的交互方式
• MCP 服務器 - 模型上下文協議服務器的實現

AI 代理系統

• 代理管理器 - 所有 AI 代理會話的中央編排器
• Claude Code 集成 - Claude Code CLI 的集成和管理方式
• 任務管理 - 任務的生命週期、持久化和狀態管理

協議與 API

• 工具和資源 - MCP 工具和資源的實現
• 事件系統和日誌記錄 - 實時事件流和結構化日誌記錄

附加功能

• 測試框架 - 端到端測試設置和最佳實踐
• 隧道和遠程訪問 - Cloudflare 隧道設置以實現互聯網訪問
• 狀態持久化 - 任務和會話在重啟後如何持久化
• 推送通知 - 移動推送通知集成
• 提示模板 - 常見任務的預構建提示系統

🔧 技術細節

技術架構

MCP Client (Mobile/Desktop)
    |
    v
Docker Container (MCP Server)
    - 處理 MCP 協議
    - 資源訂閱
    - 事件流
    |
    v
Host Bridge Daemon (TCP Socket)
    - 命令路由
    |
    v
Host Machine
    - AI 代理執行
    - 文件系統訪問

關鍵技術創新

1. 實時資源訂閱模型

服務器實現了 MCP SDK 的 listChanged 模式用於資源訂閱。當任務狀態發生變化時：

// 客戶端訂閱任務資源，通過 listChanged 通知接收通知
client.listResources()
client.getResource({ uri: "task://abc-123" })

// 當任務更新時，服務器自動執行以下操作：
// 1. 將任務保存到磁盤（JSON 持久化）
await this.persistence.saveTask(updatedTask);

// 2. 發出內部事件
this.emit("task:updated", updatedTask);

// 3. 向訂閱的客戶端發送 MCP 通知
await sendResourcesUpdatedNotification(`task://${taskId}`, sessionId);
// 這將觸發：{ method: "notifications/resources/updated", params: { uri: "task://abc-123" } }

// 客戶端接收通知並可以重新獲取更新後的資源

這使得無需輪詢即可實現實時任務監控 - 客戶端可隨著任務狀態的變化保持同步。

2. 任務完成的推送通知

集成的 Firebase Cloud Messaging（FCM）支持在任務完成時向移動設備發送推送通知：

// 任務完成 → 發送推送通知
{
  notification: {
    title: "任務完成",
    body: "你的重構任務已成功完成"
  },
  data: {
    taskId: "abc-123",
    status: "completed",
    duration: "45s"
  }
}

非常適合長時間運行的任務 - 啟動任務後，你可以去做其他事情，任務完成時會收到通知。

3. 有狀態的進程管理

• 任務以原子寫入的方式持久化到磁盤為 JSON
• 進程會話在守護進程重啟後仍然保持
• 任務生命週期的綜合狀態機：

pending → in_progress → waiting → completed
                    ↓
                  failed

事件驅動架構

所有操作都會發出事件，由多個子系統消費：

• 日誌記錄器：帶有上下文的結構化 JSON 日誌
• 狀態管理器：任務狀態更新
• 通知器：向移動客戶端發送推送通知
• 指標：性能和使用分析

📄 許可證

本項目採用 MIT 許可證，請參閱 LICENSE 獲取詳細信息。