[!TIP] ⚡ 长会话实测 prompt-cache 命中 ~99%（真实 session：41,591 tokens 中 41,472 命中）。DeepSeek 对命中缓存的输入按未命中价的几十分之一计费（官方定价），长跑几乎不为重复的上下文重复付费。

✨ 核心特性

• 🦫 单一 Go 二进制 —— 无 Node / Python 运行时，curl 一行装，macOS / Linux / Windows 全覆盖。
• 💰 缓存友好，长会话省钱 —— 围绕 DeepSeek 前缀缓存设计，实测 ~99% 命中；本地语义路由零延迟、零 token 起手。
• 🧭 内置代码图谱（codegraph） —— 符号级跳定义 / 找调用 / 接口实现 / 影响面分析，Go 经 go/types 精确解析，替代满仓库 grep。
• 👀 本地图片 OCR（PaddleOCR） —— 离线读图，丢一张截图就能识别其中文字，不依赖多模态 API。
• 📎 @ 文件 / 目录引用 —— 输入框打 @ 弹本地模糊路径选择器，选中即把 @路径 塞进消息；模型按需调 Read（文件）/ List（目录），精准给上下文不用全塞。
• 🧠 双模型自动路由 —— flash 起手省钱，复杂任务自动升 pro；也可用 /model flash|pro 锁定模型、/auto /plan /review 切模式。
• 🗂️ 顺序 Todo + 并发 Plan DAG —— 多步任务用可见待办清单逐步勾选；可并行的独立子任务拆成 DAG 派并发子 agent。
• 🔁 可复用 Workflow —— 用 JS 脚本把多 agent 流程固化下来反复跑(agent() / parallel() / pipeline()):多视角审查、扇出研究、流水线、循环到无新增等。/ultracode <描述> 让模型自动生成并保存,/workflow <名> 运行;真并发、可中断 resume、结构化输出走工具强约束、运行前预列全部阶段并实时显示耗时。对齐 Claude Code 的 workflow 脚本约定,脚本可直接互用。
• 💾 无损会话持久化 —— gob 完整保留 tool_calls / tool results / reasoning_content，重启无缝续接；超窗自动分层压缩。
• 🔌 MCP + Skill 生态 —— 原生 MCP；兼容 Claude 的 skill 目录，已有 skill 直接复用。
• 🛡️ 审核模式 —— 写文件 / 执行 Shell 默认需人工确认，安全可控。
• 🧱 原生 OS 级沙箱 —— 默认 native 做 OS 隔离（macOS Seatbelt、Linux bubblewrap，写操作限定 workspace + 进程隔离；无 OS 机制平台退软策略），也支持 docker 容器隔离或 off 关闭，不依赖容器也能给 agent 划安全边界。
• 🎛️ 工作模式（working mode） —— 一个命令锁定方法论：karpathy（务实工匠）/ openspec（规格驱动）/ superpowers（全流程严谨）；三种互斥，选一禁两、杜绝方法论混搭，切换存入会话、每轮注入不污染历史。
• ⚡ 非交互 exec 模式 —— deepx exec "任务" 一次性跑完直接把结果打到 stdout，支持管道喂数据、重定向输出、塞进脚本 / CI / cron，不必进 TUI（用法见下方「非交互执行」一节）。

📊 对比 Claude Code

[!NOTE] 这张表不比模型质量本身；deepx-code 的取舍是 成本、开源、单二进制、内置代码图谱与离线 OCR。

🚀 快速开始

1. 安装

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/itmisx/deepx-code/main/scripts/install.sh | bash && exec $SHELL

Windows(PowerShell):

irm https://raw.githubusercontent.com/itmisx/deepx-code/main/scripts/install.ps1 | iex

🇨🇳 国内用户可用 Gitee 镜像加速(源码 + 二进制都从 Gitee 拉,之后 deepx upgrade 自动走 Gitee):

macOS / Linux:

curl -fsSL https://gitee.com/itmisx/deepx-code/raw/main/scripts/install.sh | SOURCE=gitee bash && exec $SHELL

Windows PowerShell

$env:SOURCE='gitee'; irm https://gitee.com/itmisx/deepx-code/raw/main/scripts/install.ps1 | iex

安装到 ~/.local/bin/deepx，随时用 deepx upgrade 升级。

2. 在终端里进入项目并启动

deepx 是个终端程序:打开一个终端,cd 进你的项目目录,运行 deepx 即可进入交互式界面。

• 任何终端都行:macOS 自带 Terminal / iTerm2、Linux 终端、Windows Terminal / PowerShell。
• 也推荐 VS Code 内置终端(菜单 Terminal → New Terminal,或快捷键 Ctrl+`):它默认就在当前打开的工程目录,deepx 起来直接对着这个项目干活,改完文件 VS Code 里实时可见。

cd <你的项目目录>   # VS Code 内置终端通常已经在项目根,可跳过
deepx               # 进入交互式 TUI

3. 配置

⚡ 非交互执行（deepx exec）

不想进全屏 TUI、想把 deepx 塞进脚本时,用 deepx exec "<任务>":跑完把结果直接打到终端(stdout)再退出,只输出结果、不显示中间过程。

deepx exec "把 README 的功能列表翻译成英文,写到 README.en.md"

也支持管道喂数据(cat error.log | deepx exec "分析这段报错")。需先用交互式 deepx 配好 API key。

🧠 核心机制

~/.deepx/sessions/<sha1(workspace)[:16]>/
├── meta.json          # 工作区元信息
├── current            # 当前对话指针(空/"default" = 默认对话 = 本目录)
├── state.json         # 压缩状态 + 用量快照
├── YYYY-MM-DD.jsonl   # 文本日志（Memory 搜索用，跨对话）
├── history.gob        # 默认对话的完整历史
└── conversations/     # /new 开的其它对话(各自独立 history.gob / summary / state)
    └── <id>/ ...

CreatePlan
  ├─ plan-1: Read  (flash) ─────┐
  ├─ plan-2: Read  (flash) ─────┤
  ├─ plan-3: Grep  (flash) ─────┤
  └─ plan-4: Write (pro)   ─────┘ depends_on: [1,2,3]

🚦 模型路由（本地语义，零延迟，零 token）

消息发来时，deepx 在本地决定这一轮起手用 flash 还是 pro，不额外消耗任何 LLM token。判据只有两条：

消息 > 500 字                                     → pro（不依赖模型，离线也生效）
与「升级 pro」组样板句的最高相似度 ≥ 0.91
        且高于与「维持 flash」组的                 → pro
否则                                              → flash（兜底）

比的是整句语义而不是关键词包含 —— 「优化一下这行代码的写法」不会因为出现「优化」二字被抬成 pro，「设计稿在哪个目录」也不会因为「设计」中招。首次启动后台下载 multilingual-e5-small 量化模型（118 MB；源按 ModelScope → hf-mirror → HuggingFace 依次尝试，国内可直连），不阻塞启动；没就绪或下载失败时不做自动路由，起手一律 flash。

/model 锁定 flash / pro 时绕过路由，auto（默认）才走上面的判定。起手模型本轮锁定，模型可用 SwitchModel 中途升到 pro，但不再降回来（切模型会让上下文缓存整段失效）。

🧭 代码图谱（codegraph）

内置符号图谱引擎，模型直接做符号级导航 + 调用关系查询，代替满仓库 grep + 一个个翻文件。

覆盖语言：Go（stdlib 精确解析）+ TypeScript / JavaScript / Python / Java / Rust / C / C++ / C# / Ruby / PHP / Kotlin / Swift / Scala / Dart / Vue / Svelte。

工作机制：启动后台 Prewarm 建索引（状态栏 loading → ready）；文件被 Write/Update 后标 stale，下次查询增量重建；结果按 文件:行（含签名 / 调用方）展示并自动分页。

🧰 工具集

⏳ = 自动执行，但需人工确认。

⌨️ Slash 命令

🛡️ 审核模式

📦 Skills 生态

workspace 级  <wd>/.deepx/skills/
global 级     ~/.agents/skills/ → ~/.claude/skills/ → ~/.deepx/skills/

• workspace 级可 git add 共享给团队
• global 兼容 Claude Code 生态，已有 skill 直接复用

🏗️ 架构

单轮对话:
  用户输入
    ↓
  RouteByKeyword (本地) ─► flash 或 pro
    ↓
  StartStream (主循环)
    ├─ 直接答
    ├─ 调工具 → review 拦截写/Shell → 执行 → 结果回灌 → 继续
    ├─ Todo → 可见待办清单(主 agent 自己逐步执行)
    ├─ SwitchModel → 升 pro
    └─ CreatePlan → DAG scheduler → 子 agent 并发 → 汇总

会话持久化:
  HistoryUpdateMsg → SaveGob (history.gob, 完整 fidelity)
  StreamDoneMsg    → Append JSONL (纯文本, Memory 搜索)
  重启             → LoadGob (优先) / JSONL (回退)

会话压缩:
  tokens ≥ ctxWindow × 70% → runCompression (异步)
    → 尾部分层保留 ~20K token → LLM 合并新旧摘要 → 更新 gob + state.json

目录结构

deepx/
├── main.go
├── agent/      StartStream 工具循环 + 路由 + DAG 调度 + 子 agent
├── config/     ~/.deepx/model.yaml 读写
├── session/    gob 持久化 + JSONL 日志 + 会话压缩状态
├── tools/      全部工具实现（读写 / 搜索 / OCR / Memory / Skill / Plan / CodeGraph）
├── codegraph/  代码图谱：跳定义 / 找调用 / 继承实现 / 影响面
├── skill/      多路径 skill 发现与加载
├── ocr/        PaddleOCR 包装（ONNX Runtime）
├── tui/        bubbletea TUI（输入 / 渲染 / 剪贴板 / 选中 / 仪表盘）
└── scripts/    安装脚本

💰 Token 经济

• 路由零 token：纯本地句向量比对，不发 LLM 调用
• 工具不预注入：Memory / LoadSkill 只在调用时才进 context
• system prompt 极简：仅跨工具规约 + workspace，工具触发条件在各自 description 里
• DeepSeek KV cache 友好：tools 数组不随模式 / 角色变化；system prompt gob 恢复时版本感知
• 代码图谱替代盲搜：从根上减少 read / glob / grep 的 token 浪费

🩹 卸载

# macOS / Linux
rm -f ~/.local/bin/deepx && rm -rf ~/.deepx

# Windows：删除 %LOCALAPPDATA%\Programs\deepx 和 %USERPROFILE%\.deepx

📄 License

MIT © 2026 itmisx