Black Box for Your AI Coding Agents
AI 开发的可观测仪表盘 — 打开浏览器就能用
"Git tells you what changed. DevSorcerer tells you why the AI changed it." "Git 告诉你代码改了什么，DevSorcerer 告诉你 AI 为什么这么改。"
Before anything else, verify these two things in your terminal:
node --version # Must be >= 22.0.0
npm --version # Comes with Node.js| If you see | Solution |
|---|---|
node: command not found |
Install Node.js from https://nodejs.org (choose LTS v22.x) |
| Node version < 22 | Upgrade: npm install -g n && n 22, or reinstall from nodejs.org |
npm: command not found |
npm comes with Node.js — reinstall Node.js (it's included) |
Windows: npm works in Bash but not PowerShell |
See Windows: npm not found in PowerShell |
Clone, install, build, run. Four commands:
# 1. Get the code
git clone https://github.com/Linrane/DevSorcerer.git
cd DevSorcerer
# 2. Install dependencies
npm install
# 3. Build everything
npm run build
# 4. Start the dashboard
node packages/devsorcerer/bin/devsorcerer.js startOpen http://localhost:3199 in your browser. Done.
Optional: To use the shorter
devsorcerercommand instead of the fullnode packages/...path:cd packages/devsorcerer npm link # Now you can run: devsorcerer start
You don't have Node.js installed (or it's not in your PATH).
- Windows: Download the installer from https://nodejs.org (v22 LTS,
.msifile). Run it. Important: check the box "Add to PATH" during installation. Restart your terminal after installing. - Mac:
brew install node@22or download from nodejs.org - Linux:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
Verify with: node --version
npm is included with Node.js. If Node.js is installed but npm is not found:
- Windows: Re-run the Node.js installer and make sure "npm package manager" is checked. Restart terminal.
- Mac/Linux: npm should be in the same directory as node. Check
which nodethen verify npm is in the same folder.
This happens when Node.js was installed to a custom path without adding it to the system PATH.
Fix (pick one):
Option A — Use Git Bash (simplest): Install Git for Windows (https://git-scm.com), then use "Git Bash" as your terminal. It shares the same PATH as the bash environment where npm already works.
Option B — Add to PATH manually (PowerShell, as Administrator):
# Find where node.exe is first:
Get-ChildItem -Path C:\ -Filter node.exe -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1 FullName
# Add that directory to your PATH (replace <path> with the actual folder):
[Environment]::SetEnvironmentVariable('Path', $env:Path + ';<path-to-node-folder>', 'User')Close and reopen PowerShell. Run node --version to verify.
Option C — Reinstall Node.js with the official installer from nodejs.org. Make sure "Add to PATH" is checked.
npm install -g npm
# or configure npm to use a user-owned directory:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# Use a mirror (replace with one close to you):
npm config set registry https://registry.npmmirror.com
npm installError: listen EADDRINUSE :::3199
# Find and kill the process using port 3199:
# Windows:
netstat -ano | findstr :3199
taskkill /PID <PID> /F
# Mac/Linux:
lsof -i :3199
kill -9 <PID>You're not in the project root directory. Make sure you did cd DevSorcerer (the cloned folder) first.
Run ls (Mac/Linux) or dir (Windows) — you should see package.json and a packages/ folder.
Add to your agent's MCP config:
{
"mcpServers": {
"devsorcerer-filesystem": {
"command": "devsorcerer",
"args": ["proxy", "-t", "npx", "--target-args", "-y @anthropic/mcp-server-filesystem", "."]
}
}
}Compatible with: Claude Code, Cursor, Windsurf, Continue, Cline, Codex CLI, and any MCP agent.
For Claude Code users, DevSorcerer now imports your actual session history directly — no MCP proxy needed. It reads Claude Code's native JSONL session files and populates the dashboard with real conversation data including tool calls, token usage, and costs.
# 1. Import all existing Claude Code sessions
node scripts/import-sessions.mjs
# 2. Start the dashboard
devsorcerer start
# Or use the combined startup script:
bash scripts/start.sh
# For continuous monitoring, use watch mode:
node scripts/import-sessions.mjs --watchHow it works:
- Reads
~/.claude/projects/<project>/<session>.jsonlfiles - Extracts tool calls, token usage, model info, and session metadata
- Idempotent: re-running only imports new sessions, won't duplicate
- Watch mode: auto-imports new sessions every 30 seconds
Dashboard will show:
- All Claude Code sessions with agent version, branch, status
- Step-by-step timeline replay of tool calls
- Cost breakdown by tool, model, and session
- Token usage trends over time
BGE-M3 Embedding Engine (1024-dim) Semantic search now uses BAAI's state-of-the-art BGE-M3 model (1024-dimensional vectors). The old SimpleEmbedder hash-based fallback has been replaced with a TF-IDF trigram embedder that captures genuine textual overlap — far better than random hash values. When Transformers.js models are available, you get full semantic similarity search across all agent session history.
Cloudflare Tunnel — Public Web Access
Access your dashboard from anywhere using your own domain. No cloud upload, no server — your data stays local while being securely exposed via Cloudflare Tunnel. Use the included start-with-tunnel.ps1 script to launch both the server and tunnel in one command:
# Windows (PowerShell):
.\start-with-tunnel.ps1
# Or manually:
cloudflared tunnel run # Exposes https://devsorcerer.YOURDOMAIN.com
devsorcerer start # Dashboard at localhost:3199Expanded Pricing Engine Added support for GPT-4.1-mini, GPT-5-mini, o4-mini, o3, Gemini 2.5 Pro, and Gemini 2.5 Flash. Now covering 16 models with accurate per-token pricing.
Windows PowerShell Installer One-click setup for Windows users:
.\scripts\install.ps1 # Installs Node.js, cloudflared, builds everythingPer-Model Pricing Engine Every API call is priced by its actual model — Claude Opus vs Sonnet vs DeepSeek each have their own accurate rates. Costs are no longer estimates: they reflect real API pricing.
User-Configurable Pricing (Settings page) Go to Settings > Model Pricing to customize rates for any model. Add new models, edit input/output prices per 1,000 tokens, see real-time cost previews. Made a mistake? One-click "Reset to Defaults" restores built-in pricing.
Per-Model Cost Breakdown The Cost Analysis page now shows a separate "Per-Model Cost" table — toggle it on to see exactly which model consumed what budget, with percentage bars and call counts.
Foolproof Design Every input validates before saving. Empty model names, negative prices, duplicate entries — all caught with clear error messages (in your language). The pricing reset button ensures you can always recover from misconfiguration.
Full Bilingual Support Toggle between English and Chinese (Settings > Language). Every label, button, tooltip, error message, and chart axis switches. Technical identifiers (model names, file paths) are preserved.
| Command | Description |
|---|---|
devsorcerer start |
Start server + dashboard |
devsorcerer import |
Import Claude Code session history (via scripts/import-sessions.mjs) |
devsorcerer validate |
Pre-flight checks (config, DB, git, Node.js) |
devsorcerer status |
Database stats |
devsorcerer analyze cost |
Cost by project / session / tool |
devsorcerer analyze risk |
Security scan (SARIF output) |
devsorcerer analyze quality |
Acceptance / rollback / bug rate |
devsorcerer show <id> |
Session timeline replay |
devsorcerer knowledge search |
Semantic search across history |
devsorcerer audit export |
Compliance export (JSON/CSV/NDJSON) |
devsorcerer config |
Manage configuration |
| Page | What You See |
|---|---|
| Overview | Live stats, cost trend chart, top tools pie, recent sessions |
| Sessions | All sessions with search by ID/agent/branch |
| Session Detail | Step-by-step timeline replay player, tool call summary, error loops |
| Cost Analysis | Time range filter (7d/30d/90d/all), per-tool & per-model cost tables, summary stats |
| Risk Findings | Severity breakdown bar, per-finding detail with code snippets |
| Quality | Acceptance rate, rollbacks, AI bugs, quality radar chart |
| Knowledge | Semantic + keyword hybrid search with context snippets |
| Audit | One-click JSON/CSV/NDJSON export, optional anonymization |
| Settings | Port, DB path, embedding model, toggles, model pricing editor with validation |
AI Agent (Claude Code, Cursor, etc.)
│ JSON-RPC 2.0
▼
┌──────────────────┐
│ MCP Proxy │ ← Transparent interception
│ Capture/Forward │──→ SQLite (events, sessions, analysis)
└──────┬───────────┘
│ JSON-RPC (unchanged)
▼
MCP Server
Analysis: Cost → Risk (8 rules) → Quality → Bottleneck → Knowledge (embeddings + LanceDB)
Dashboard: React 19 + Vite + Recharts + Tailwind 4, 9 pages, real-time via WebSocket
| Dimension | Other Tools | DevSorcerer |
|---|---|---|
| Event capture | Per-agent SDK | Universal MCP proxy |
| UX | CLI-first | Dashboard-first |
| Knowledge | Lost after session | Vector semantic search |
| Privacy | Cloud upload | Local-first |
| Mobile | Desktop only | Responsive, any device |
- Local-first: All data in SQLite + LanceDB on your machine
- Anonymization:
audit export --scope anonymized - No cloud upload: Code never leaves your filesystem
在开始之前，先在终端里验证两件事：
node --version # 必须 >= 22.0.0
npm --version # 随 Node.js 一起安装| 如果你看到 | 解决方法 |
|---|---|
node: command not found |
从 https://nodejs.org 安装 Node.js（选 LTS v22.x 版本） |
| Node 版本 < 22 | 升级：npm install -g n && n 22，或从 nodejs.org 重装 |
npm: command not found |
npm 随 Node.js 一起提供 — 重装 Node.js 即可 |
| Windows：Bash 里能用 npm，PowerShell 里不行 | 见下方 Windows：PowerShell 找不到 npm |
克隆、安装、构建、运行。四步搞定：
# 1. 下载代码
git clone https://github.com/Linrane/DevSorcerer.git
cd DevSorcerer
# 2. 安装依赖
npm install
# 3. 构建项目
npm run build
# 4. 启动仪表盘
node packages/devsorcerer/bin/devsorcerer.js start浏览器打开 **http://localhost:3199**。不用再碰命令行了。
可选：把
devsorcerer注册为全局命令，以后在任意目录都能直接敲：cd packages/devsorcerer npm link # 之后直接运行：devsorcerer start
你的电脑没有安装 Node.js，或者装了但没加到 PATH。
- Windows：去 https://nodejs.org 下载 v22 LTS 版本（
.msi安装包）。安装时一定要勾选 "Add to PATH" 选项。装完重启终端。 - Mac：终端执行
brew install node@22，或者去 nodejs.org 下载安装包 - Linux：
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
验证：node --version
npm 是 Node.js 自带的。如果 node 装好了但 npm 没有：
- Windows：重新运行 Node.js 安装程序，确保勾选 "npm package manager"。重启终端。
- Mac/Linux：npm 和 node 在同一个目录。用
which node找到位置，确认 npm 也在同一文件夹。
这种情况是 Node.js 装到了自定义路径，但没有写入系统 PATH。
解决方法（任选一个）：
方案 A — 用 Git Bash（最简单）： 安装 Git for Windows（https://git-scm.com），然后用 "Git Bash" 作为终端。在 Git Bash 里 npm 和 node 都能直接使用。
方案 B — 手动添加 PATH（在管理员 PowerShell 里执行）：
# 先找到 node.exe 在哪：
Get-ChildItem -Path C:\ -Filter node.exe -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1 FullName
# 把那个目录加到 PATH（把 <path> 换成上面找到的目录）：
[Environment]::SetEnvironmentVariable('Path', $env:Path + ';<node所在目录的路径>', 'User')关掉重新打开 PowerShell。输入 node --version 验证。
方案 C — 重装 Node.js：从 nodejs.org 下载官方安装程序，安装时确保勾选 "Add to PATH"。
权限不够。两种修法：
# 方法1：用管理员权限
sudo npm install
# 方法2：配置 npm 使用用户目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc# 换成国内镜像（例如 npmmirror）：
npm config set registry https://registry.npmmirror.com
npm installError: listen EADDRINUSE :::3199
说明之前启动的 DevSorcerer 还没关，或者有其他程序占用了 3199 端口。
# Windows：
netstat -ano | findstr :3199
taskkill /PID <进程ID> /F
# Mac/Linux：
lsof -i :3199
kill -9 <进程ID>你不在项目根目录。确保你先 cd DevSorcerer（进入克隆下来的文件夹）。用 ls（Mac/Linux）或 dir（Windows）应该能看到 package.json 和 packages/ 文件夹。
如果看到类似 Database not initialized 的提示：
# 先运行一次 validate 检查各项配置是否正常
devsorcerer validate
# 然后重新启动
devsorcerer start把以下配置加到你的 AI agent 的 MCP 配置中：
{
"mcpServers": {
"devsorcerer-filesystem": {
"command": "devsorcerer",
"args": ["proxy", "-t", "npx", "--target-args", "-y @anthropic/mcp-server-filesystem", "."]
}
}
}兼容：Claude Code、Cursor、Windsurf、Continue、Cline、Codex CLI 等所有 MCP agent。
Claude Code 用户现在可以直接导入真实的会话历史 —— 无需 MCP 代理。DevSorcerer 读取 Claude Code 的原生 JSONL 会话文件，将工具调用、token 用量和成本等数据导入仪表盘。
# 1. 导入所有 Claude Code 历史会话
node scripts/import-sessions.mjs
# 2. 启动仪表盘
devsorcerer start
# 或者用一键启动脚本：
bash scripts/start.sh
# 持续监控模式（每30秒自动导入新会话）：
node scripts/import-sessions.mjs --watch工作原理：
- 读取
~/.claude/projects/<project>/<session>.jsonl文件 - 提取工具调用、token 用量、模型信息和会话元数据
- 幂等操作：重复运行只导入新会话，不会重复
- 监控模式：每 30 秒自动检查并导入新会话
仪表盘将显示：
- 所有 Claude Code 会话（含版本、分支、状态）
- 逐步时间线回放工具调用
- 按工具、模型、会话的成本明细
- 时间段内 token 用量趋势
BGE-M3 嵌入引擎（1024维） 语义搜索现在使用 BAAI 的顶级 BGE-M3 模型（1024维向量）。旧的 SimpleEmbedder 哈希降级方案已被替换为 TF-IDF 三元组嵌入器，纯离线也能捕捉真实的文本重叠 — 远优于随机哈希值。当 Transformers.js 模型可用时，可对所有 agent 会话历史进行完整的语义相似度搜索。
Cloudflare Tunnel — 公网访问
通过自己的域名从任何地方访问仪表盘。无需上传云端、无需服务器 — 数据留在本地，通过 Cloudflare Tunnel 安全暴露。使用自带的 start-with-tunnel.ps1 脚本一键启动服务和隧道：
# Windows (PowerShell):
.\start-with-tunnel.ps1
# 或手动：
cloudflared tunnel run # 暴露 https://devsorcerer.你的域名.com
devsorcerer start # 仪表盘在 localhost:3199扩展定价引擎 新增支持 GPT-4.1-mini、GPT-5-mini、o4-mini、o3、Gemini 2.5 Pro、Gemini 2.5 Flash。现已覆盖 16 个模型，支持精确按 token 计价。
Windows PowerShell 安装器 Windows 用户一键安装：
.\scripts\install.ps1 # 安装 Node.js、cloudflared、构建所有内容按模型精确计价引擎 每个 API 调用按实际使用的模型计价 — Claude Opus、Sonnet、DeepSeek 各有独立准确的价格。成本不再是估算，而是反映真实的 API 开销。
用户可自定义定价（设置页面） 前往 设置 > 模型定价，即可为任意模型自定义费率。添加新模型、编辑每千 token 的输入/输出价格、实时查看成本预览。改错了？一键「重置为默认」恢复内置定价。
按模型成本分解 成本分析 页面新增独立的「各模型成本」表格 — 点击展开即可看到每种模型精确消耗了多少预算，含百分比进度条和调用次数。
防呆设计 每次保存前验证输入。空模型名、负数价格、重复条目 — 全都有清晰的错误提示（显示你当前语言）。定价重置按钮确保任何时候都能从错误配置中恢复。
完整双语支持 在设置 > 语言中一键切换英文/中文。每个标签、按钮、提示、错误消息、图表轴线都会切换。技术标识（模型名、文件路径）则保留不译。
| 命令 | 说明 |
|---|---|
devsorcerer start |
启动服务 + 仪表盘 |
devsorcerer import |
导入 Claude Code 会话历史（通过 scripts/import-sessions.mjs） |
devsorcerer validate |
预检（配置、数据库、git、Node.js 版本） |
devsorcerer status |
数据库统计 |
devsorcerer analyze cost |
按项目/会话/工具分析成本 |
devsorcerer analyze risk |
安全扫描（可输出 SARIF 格式） |
devsorcerer analyze quality |
采纳率/回滚率/缺陷率 |
devsorcerer show <id> |
会话时间线回放 |
devsorcerer knowledge search |
跨会话语义搜索 |
devsorcerer audit export |
审计导出（JSON/CSV/NDJSON） |
devsorcerer config |
配置管理 |
| 页面 | 你能看到 |
|---|---|
| 总览 | 实时统计卡片、成本趋势图、热门工具饼图、最近会话列表 |
| 会话列表 | 全部会话，支持按 ID/代理/分支搜索 |
| 会话详情 | 逐步时间线回放播放器、工具调用摘要、错误循环检测 |
| 成本分析 | 时间范围筛选（7天/30天/90天/全部）、按工具 & 按模型成本表、汇总统计 |
| 风险扫描 | 严重程度分布条，每条风险详情含代码片段 |
| 质量 | 采纳率、回滚次数、AI 缺陷、质量雷达图 |
| 知识搜索 | 语义 + 关键词混合搜索，带上下文片段 |
| 审计导出 | 一键 JSON/CSV/NDJSON 导出，可选匿名化 |
| 设置 | 端口、数据库路径、嵌入模型、开关、模型定价编辑器（含验证） |
AI Agent（Claude Code、Cursor 等）
│ JSON-RPC 2.0
▼
┌─────────────────┐
│ MCP Proxy │ ← 透明拦截，不改协议
│ 捕获 / 转发 │──→ SQLite（事件、会话、分析）
└─────┬───────────┘
│ JSON-RPC（不变）
▼
MCP Server
分析层：成本 → 风险（8规则）→ 质量 → 瓶颈 → 知识（向量 + LanceDB）
仪表盘：React 19 + Vite + Recharts + Tailwind 4，9 页面，WebSocket 实时推送
| 维度 | 其他工具 | DevSorcerer |
|---|---|---|
| 事件捕获 | 每种 agent 单独 SDK | 通用 MCP 代理 |
| 用户体验 | 命令行优先 | 仪表盘优先，打开就能用 |
| 知识 | 会话结束就丢了 | 向量语义搜索 |
| 隐私 | 上传到云端 | 本地优先 |
| 移动端 | 仅桌面 | 响应式，手机也能看 |
- 本地优先：所有数据存在你的 SQLite + LanceDB 里
- 可匿名：
audit export --scope anonymized - 不上传：代码和日志不离开你的电脑
DevTwin/
├── packages/
│ ├── devsorcerer/ # Core CLI + Engine (TypeScript)
│ │ ├── bin/ # CLI entry point
│ │ └── src/
│ │ ├── collector/ # MCP transparent proxy
│ │ ├── analyzer/ # Cost / Risk / Quality / Bottleneck
│ │ ├── knowledge/ # Embeddings + semantic search
│ │ ├── server/ # Fastify API + WebSocket
│ │ ├── storage/ # SQLite + repositories
│ │ ├── cli/ # Clipanion commands
│ │ └── shared/ # Types, utils, validation
│ └── dashboard/ # React 19 + Vite Web UI
│ └── src/
│ ├── pages/ # 9 pages (Overview → Settings)
│ ├── components/ # Charts, Session, Layout, UI
│ ├── hooks/ # useWebSocket
│ └── api/ # TanStack Query client
└── scripts/install.sh # Unix installer
MIT © 2026 DevSorcerer
ai-agent observability mcp-protocol cost-tracking security-scan compliance claude-code cursor devtools semantic-search code-review audit-log dashboard visualization real-time typescript react