Makewand 快速上手指南

Makewand 是一套零额外 Token 成本的跨模型编程编排系统。它能够自适应感知您本地已安装、登录或配置的 AI 编程工具，并在物理隔离的 Git Worktree 中进行协同编码、异构红队盲审、自愈回环与并发竞速。

核心哲学： 用户登录或者提供了几个工具，系统就实际使用几个工具。无需强制用户购买额外的通用 API Token，直接榨干本地订阅（Google AI Pro, Claude Max, Codex Pro, Grok 等）。

环境安装与依赖

支持 Linux、macOS 与 Windows (WSL2)。

# 方式一：一键自动安装脚本（推荐）
curl -fsSL https://makewand.org/install.sh | bash

# 方式二：通过 Git 源码检出安装
git clone https://github.com/makewand/makewand.git
cd makewand
pip install -e .
        

安装完成后，运行环境自检：

$ makewand
# 输出工具池状态表格：
# 🟢 已激活可用工具池 (Active Providers): [claude, codex, agy, grok, muse]
# ⚪ 待接入主流工具生态 (Standby Ecosystem): [aider, cursor, deepseek, qwen, ...]
        

自适应动态拓扑感知 (Dynamic Topology)

Makewand 会实时探测当前环境（检查 CLI 可执行路径、环境变量、认证配置），动态计算活跃工具集合 active_pool：

N ≥ 2（异构多模型就绪）：自动启用 Heterogeneous Cross-Model Review Mode。主编码器写完后，自动唤起第二异构模型执行独立红队盲审并回环修复。
N = 1（单一模型可用）：自动启用 Resilient Single-Tool Mode。创建独立的 Shadow Worktree，切换至对抗性 Prompt 提示词进行自我批判与极端边界排查。
N = 0（无可用工具）：输出友好的工具接入引导与配置提示，绝不静默崩溃。

保护机制： 本地重型模型 local (Ollama/vLLM) 默认关闭。当主机存在 GPU 训练等关键计算任务时，绝不发生显存与算力争抢。

CLI 核心命令指南

1. makewand run · 智能编排流水线

驱动主编码器实现功能，并在沙箱中完成单元测试与异构审核：

# 自动选择最适合的模型
makewand run "重构用户认证模块，加入 ed25519 签名验证"

# 显式指定编码方与审查方
makewand run "优化 SQL 慢查询" --provider claude --review-by codex

# 指定算力梯队 (fast / standard / deep / max)
makewand run "攻坚死锁问题" --tier deep
        

2. makewand review · 独立红队安全盲审

在完全独立的 Git Worktree 中执行红队审查，审查模型仅接收 Git Diff 与逻辑约束，杜绝原作者上下文偏见：

# 对当前工作区未提交改动进行红队审计
makewand review --provider codex

# 针对指定敏感文件审计并自动生成修复建议
makewand review --provider codex --target src/auth_engine.py
        

3. makewand race · 多模型并发沙箱竞速

为两个或更多模型分别克隆独立的 Worktree 沙箱，并发派发相同需求，由客观测试套件（通过率、吞吐量、代码行数）择优采用：

makewand race "实现高并发内存环形缓冲区" --models claude,codex

4. makewand observe · 跨会话态势巡检

多终端开发时，一键巡检主机上所有活跃的 AI 会话（Tmux 与独立 TTY），精准分型长耗时任务、CI 测试、常驻服务与额度枯竭状态：

makewand observe
# 支持自动输出 Markdown 或 JSON 格式，无缝集成进 CI/CD 或监控大屏
        

5. makewand serve · 企业级网关与 Web 控制台

启动企业级 OpenAI 兼容 HTTP 网关与内置管理后台：

makewand serve --listen 0.0.0.0:8080 --enable-users
# 访问 http://localhost:8080/admin 即可进入现代化 Web UI 管理后台
        

Cloudflare 部署实战指南

针对注册在 Cloudflare 的 makewand.org 与 makewand.com，推荐采用“静态前端走 Cloudflare Pages + 动态网关走 Cloudflare Tunnel”的黄金架构。

1. Cloudflare Pages 静态站部署 (官网与文档)

本项目 site/ 目录为纯静态、极速现代前端，具备自动 SEO、安全 Headers 与暗色 Glassmorphism 设计：

# 一键通过 Wrangler 部署到 Cloudflare Pages
npx wrangler pages deploy site/ --project-name=makewand --branch=master

# 部署成功后，在 Cloudflare 控制台中为该 Pages 项目添加自定义域名：
# 1. makewand.org (主域名)
# 2. www.makewand.org (子域名)
# 3. makewand.com (商业镜像或设置 301 重定向至 makewand.org)
        

2. Cloudflare Tunnel 穿透配置 (管理后台与 API)

如果您希望将本机运行的 makewand serve (8080端口) 安全映射到公网（如 console.makewand.org 或 api.makewand.org），无需公网 IP 和复杂端口映射：

# 创建隧道
cloudflared tunnel create makewand-gateway

# 配置 ingress 映射 (例如 deploy/cloudflare-tunnel.yml)
tunnel: <tunnel-uuid>
credentials-file: ~/.cloudflared/<tunnel-uuid>.json

ingress:
  - hostname: console.makewand.org
    service: http://localhost:8080
  - hostname: api.makewand.org
    service: http://localhost:8080
  - service: http_status:404

# 绑定 Cloudflare DNS 路由并启动守护服务
cloudflared tunnel route dns makewand-gateway console.makewand.org
cloudflared tunnel run makewand-gateway
        

3. Docker 与 Systemd 生产常驻

生产环境下，可通过项目自带的 deploy/systemd.makewand.service 或 deploy/docker-compose.yml 进行自动化常驻保活与日志轮转。