原生编程智能体 paean-ai/deeptide

DeepTide

由 DeepSeek 打造，为 DeepSeek 而生。
AI 编程智能体，如潮水般流过你的代码库。
名字由来：DeepSeek + tide（terminal IDE）。

三种形态，同一支团队

| | DeepTide for macOS | DeepTide CLI（deeptide） | DeepTide CLI Rust（deeptide-rs） |
| 形态 | 原生 macOS 应用 | 跨平台终端命令行 | 跨平台终端命令行 + 原生桌面 GUI（--gui） |
| 运行时 | Swift 6 原生二进制，空闲时约 15 MB | Bun，常驻约 50 MB | 原生 Rust 二进制，磁盘占用约 10 MB，无需运行时 |
| 平台 | macOS 15+ | Linux · Windows · macOS | Linux · Windows · macOS |
| 安装 | curl -fsSL https://deeptide.sh/install.sh \| sh | bun add -g deeptide（本包） | npm install -g deeptide-rs |
| 命令行名称 | DeepTide.app | deeptide、tide | deeptide-rs |
| 血统 | 100% 由 DeepSeek V4 编写 | 基于开源 Zero CLI | 在本仓库 crates/ 下编写 |
| 适合谁 | 想要精细调校原生体验的 macOS 用户 | 老用户；插件能力最丰富 | 无头 CI、老旧笔记本、单二进制部署 |

本仓库是这三者的社区门户——文档、FAQ、问题追踪——同时也是两个 npm 包的家：

- deeptide —— 当前 TypeScript/Bun 命令行（转发到 @paean-ai/zero-cli）
- deeptide-rs —— Rust 命令行（postinstall 时通过 GitHub Releases 下发原生二进制）

这两个命令行包不会冲突——它们暴露的二进制名称不同（deeptide/tide 与 deeptide-rs），所以你可以两个都装，在 Rust 移植版成熟之前随意切换。

Rust 移植版位于 crates/。它计划逐步成长为跨平台命令行的正统实现，但只要用户觉得 deeptide 还有价值，它就会一直保留——不强制迁移。

仓库里还包含开源的原生本地推理运行时，位于 native/：一个硬分叉的 ds4 DeepSeek V4 Flash Metal 引擎，外加 dsgo，一个本地 OpenAI/Anthropic 兼容网关，用来和 DeepTide 搭配。

在 macOS 上安装（推荐）

Mac 用户推荐走原生 Deeptide 构建，来自 deeptide.sh。它会下载适配你 Mac 架构的签名构建，同时安装 deeptide 和更短的 tide 命令：

curl -fsSL https://deeptide.sh/install.sh | sh

然后这样启动：

tide auth login # Paean OAuth, multimodal-aware
tide login # or save a DeepSeek API key directly
tide # launch the REPL
tide doctor # diagnose install + network

如果你想给 Deeptide 配一个原生 Mac 终端，也可以试试 Clide —— 一款现代 macOS 终端，带文件浏览器、多窗格布局、拖放和原生语音输入。

在 Linux / Windows 上安装（Zero CLI 别名）

前置条件： 必须安装 Bun 并加入 PATH。CLI 运行时依赖它（与底层 Zero CLI 保持一致）。Bun 不会替换你已装的 Node —— 两者并存。

在非 Mac 系统上，这个 npm 包是跨平台的 DeepTide 风味入口，由 Zero CLI 驱动。它会安装 deeptide 和 tide 两个别名，工作流接近 Deeptide，但它不是 deeptide.sh 那个 Swift 原生 macOS 构建。

bun (recommended, fastest install)
bun add -g deeptide

npm (works too; bun is still required at runtime)
npm install -g deeptide

pnpm
pnpm add -g deeptide

会安装两个命令，挑你手指顺手的用：

tide # interactive REPL (preferred — short) deeptide # same thing, full name tide -p "explain this repo" # one-shot mode tide --help # all options

你也可以直接安装上游包：

bun add -g @paean-ai/zero-cli

从源码构建 macOS 原生应用

macOS 原生构建开源在 paean-ai/deeptide（Swift）。多数用户应该从 deeptide.sh 安装，但需要改原生运行时或本地推理组件的人，可以从源码树里查看并构建。

快速开始（命令行）

DeepTide 命令行默认对接 DeepSeek API（与 DeepTide 原生应用一致），也能通过 BYOK 驱动任何兼容 Anthropic 协议的端点 —— 智谱 GLM、火山引擎、Paean、Qwen、Moonshot、自建网关等等。

Default path — DeepSeek
export DEEPSEEK_API_KEY="sk-..."
tide

BYOK to another provider
tide --base-url https://open.bigmodel.cn/api/anthropic --api-key <GLM_KEY>

One-shot, non-interactive
tide -p "Explain the auth middleware"

完整的配置面（settings.json schema、钩子、权限、MCP 服务器、子代理、模型别名）见上游 Zero CLI README，那才是权威参考。

桌面 GUI（deeptide-rs）

Rust 移植版带来一个原生桌面应用——单个 Rust 二进制文件（egui，不用 Electron/webview），只是给 CLI 所用同一引擎套上一层窗口。它完全共用 CLI 的配置、会话历史和整套工具——不需要另外维护一份配置：

- 同一份配置——读取同一个 ~/.config/tide/settings.json（以及项目里的 .deeptide/settings.json）；provider/model/API key 设置一次，CLI 和 GUI 都会读取。
- 同一批会话——对话保存到同一个磁盘存储，所以在 GUI 里开始的聊天，可以在终端用 deeptide-rs --resume 恢复；CLI 会话也会出现在 GUI 侧边栏里，一键恢复。
- 同一套工具——完整的智能体工具集（Read/Write/Edit、Bash、Glob/Grep、WebFetch、MCP 服务器、子代理……）完全一致可用。

它能做什么：流式聊天，支持 markdown 渲染、实时 reasoning（「💭 thinking」）和工具调用卡片、交互式工具审批（Write/Edit 带彩色 diff 预览）、会话侧边栏（恢复历史聊天）、服务商/模型选择器、New chat、Stop/interrupt，以及成本/用量栏（↑/↓ token · cache · $）。

启动

Via the CLI launcher (execs the desktop binary, sharing this config/cwd):
deeptide-rs --gui

…or run the GUI binary directly: deeptide-gui

从源码构建

From the repo root (the Rust workspace under crates/):
cargo run -p deeptide-gui # dev run
cargo build -p deeptide-gui --release # release binary at target/release/deeptide-gui

配置模型的方式和 CLI 一样——比如启动前 export DEEPTIDE_API_KEY=…（或在 settings.json 里设置）。没有凭据时，GUI 会以安全的本地回显模式打开，并显示「no API key」横幅。要指向非默认服务商，用应用内的选择器，或 export DEEPTIDE_PROVIDER=…（例如 deepseek、ollama、openai、gemini）。

内置能力

DeepTide 是智能体式编程助手——模型自己规划、调用工具、观察结果、随机应变。开箱即用：

- 多轮智能体循环——规划 → 工具 → 观察 → 调整
- 流式响应——实时看到模型思考和行动
- 30+ 内置工具——文件 I/O、shell、web、任务、MCP、调度、子代理
- 25+ 斜杠命令——/status、/cost、/diff、/init、/permission、/hooks……
- 权限模式——default · accept-edits · plan · bypass
- 钩子引擎——pre/post tool、user-prompt、session、compaction shell 钩子
- 记忆系统——跨会话持久保存项目记忆
- 用 markdown 定义子代理——在项目里定义自定义智能体
- 用 markdown 定义自定义斜杠命令——把 <name>.md 放到 .deeptide/commands/（或 ~/.deeptide/commands/）下，就能用 /<name> 运行；正文会变成提示词，支持 $ARGUMENTS / $1…$11 替换。内置命令始终优先。
- Plan mode — 先设计再写代码，执行前先拿到批准
- Web research — /deep-seek <question> 用模型内置知识推测可能的官方/规范 URL，再用 WebFetch 验证。可选的 BRAVE_SEARCH_API_KEY / SERPER_API_KEY 凭据能改善来源发现，但基于 URL 的研究并不需要它们。来源会标注为 [verified]、[known] 或 [unverified]。

工具目录、斜杠命令集、钩子事件名和模型别名，都通过 tide-spec 共享接口契约与 macOS 原生 DeepTide 应用保持一致——你的钩子和肌肉记忆可以在两者之间通用。

Documentation

- tide-spec — 共享接口契约：工具目录、斜杠命令、命令行参数、钩子环境变量、模型别名。
- Zero CLI docs — 命令行引擎的完整参考。
- DeepTide native source — macOS 应用的 Swift 代码库。
- native/ — 本地 DeepSeek 运行时源码：ds4 推理引擎和 dsgo 网关。
- docs/deepseek-v4-flash-q2.md — 原版本地 V4 Flash Q2 构建适合做什么、不适合做什么，以及 deeptide 为什么把它限制在 64k 上下文。还介绍了保真度更高的 Q4_K 混合精度构建（153 GiB），适合内存 192 GB 以上的主机。
- docs/deepseek-v4-flash-iq2-asymmetric.md — 对非对称 IQ2_XXS + Q2_K + Q8_0 + F16 量化（80.8 GiB）的辩证分析，这是 128 GB Mac 和单台 80 GB H100 机器的体积甜点。逐一剖析按张量分组的精度方案做对了什么，以及它要承担的失效模式（专家坍缩风险、FFN 残差污染、iMatrix 依赖）。

Samples

- samples/pixel-roguelike — 一个无依赖的 HTML Canvas 类 Rogue 展示项目，带可编辑的像素美术精灵、程序化地形、响应式移动端控制、战斗特效，以及像素美术预览辅助工具。
- samples/pixel-backpack-roguelite — 一个像素背包类 Rogue-lite，带空间物品规划、合并、神器锻造、自主 TD 风格战斗波次，以及无限成长奖励。
- samples/deeptide-deck-template — 一个响应式 HTML 演示文稿模板，适合桌面演示、移动端阅读，以及精致的浏览器到 PDF 导出，以 Deeptide 作为参考产品。
- samples/agent-workbench-template — 一个精致的编码智能体交接模板，涵盖计划、差异、验证、风险和可直接提 PR 的评审说明。
- samples/agent-brief-template — 一个用于通用智能体输出的专业研究与决策简报模板，选项对比、证据矩阵和行动计划。
- samples/void-descent — 配套的像素风回合制地牢探索演示，带战争迷雾、房间与走廊探索、楼层下降、持久升级、物品和移动端滑动操作。

技能

- skills/ — 英文的、从示例提炼的智能体技能，涵盖像素风编程、高级视觉设计、HTML 演示文稿、roguelike 游戏循环、休闲游戏系统、响应式 Canvas 游戏外壳、编程智能体交付，以及研究简报工作流。

本地 DeepSeek 运行时

原生运行时代码在本仓库内管理，不改变 npm 包的安装面。package.json 使用显式的 files 白名单，因此 native/ 对 GitHub 用户和源码构建者可见，但不会打包进已发布的 npm 包装包。

在 macOS 上构建两个原生组件：

npm run build:native

或者分别构建：

npm run build:ds4
npm run build:dsgo

运行时细节见 native/README.md、native/ds4/README.md 和 native/dsgo/README.md。

报告问题

请开一个 issue。新建 issue 表单会把你引导到合适的模板：

- 命令行 bug 或功能请求 — 通常会转发到 a8e-ai/zero-cli，命令行代码在那里，但如果你不确定，也可以先在这里提。
- macOS 原生应用 — 在这里报告。粘贴日志前，请抹去任何敏感的路径、文件名或模型输出。
- 文档、安装或一般问题 — 从这里开始。
- 安全漏洞 — 使用私密漏洞报告，不要用公开 issue。

⚠️ 隐私提醒： 崩溃日志和控制台输出可能包含项目路径、文件名、环境变量值或模型输出。粘贴到公开 issue 前先检查一遍。如果报告确实需要敏感数据，请私下联系维护者。

关于这个 npm 包

deeptide npm 包是一个刻意做薄的跳转，指向 @paean-ai/zero-cli，所有命令行源码都在那里。我们用两个名字发布，方便用户安装自己觉得顺手的那个；两者都解析到同一个二进制文件，带 DeepTide 品牌外观。只有一个真实来源（a8e-ai/zero-cli）——没有重复实现。

许可证

MIT — 见 LICENSE 和 NOTICE。

DeepTide 是独立项目，与 Anthropic, Inc. 或 DeepSeek (Hangzhou) AI Co., Ltd. 无关联、未获其背书，也未受其赞助。

由 🐳 a8e 打造 — 为 DeepSeek，覆盖所有平台。