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

DeepTide

由 DeepSeek 打造，为 DeepSeek 而生。
一个如潮汐般流经你代码库的 AI 编程智能体。
名称由来：DeepSeek + tide（终端 IDE）。

三种形态，同一团队

| | DeepTide for macOS | DeepTide CLI（deeptide） | DeepTide CLI Rust（deeptide-rs） |
|---|---|---|---|
| 形态 | 原生 macOS 应用 | 跨平台终端 CLI | 跨平台终端 CLI + 原生桌面 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 |
| CLI 名称 | DeepTide.app | deeptide、tide | deeptide-rs |
| 渊源 | 100% 由 DeepSeek V4 编写 | 基于开源 Zero CLI 驱动 | 在本仓库的 crates/ 下编写 |
| 适用场景 | 想要精心调校的原生体验的 macOS 用户 | 现有用户；最丰富的插件接口 | 无头 CI、低配笔记本、单二进制部署 |

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

- deeptide —— 当前的 TypeScript/Bun CLI（转发至
@paean-ai/zero-cli）
- deeptide-rs —— Rust CLI（通过 GitHub Releases 的
postinstall 分发原生二进制）

这两个 CLI 包不会冲突——它们暴露不同的二进制名称
（deeptide/tide 与 deeptide-rs），因此你可以同时安装两者，
在我们完善 Rust 移植版期间自由切换。

Rust 移植版位于 crates/ 下。它计划随时间推移
成长为标准的跨平台 CLI，但只要用户仍觉得 deeptide 包有价值，
它就会继续可用——不存在强制迁移。

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

在 macOS 上安装（推荐）
对于 Mac 用户，推荐使用来自 deeptide.sh 的原生 Deeptide 构建版本。它会下载适用于你的 Mac 架构的已签名构建，并同时安装 deeptide 和更短的 tide 命令：

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

然后这样开始：

tide auth login   # Paean OAuth，支持多模态
tide login        # 或直接保存 DeepSeek API 密钥
tide              # 启动 REPL
tide doctor       # 诊断安装 + 网络

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

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

前提条件： 必须已安装 Bun 并在 PATH 中。CLI 运行时需要它（与底层的 Zero CLI 一致）。Bun 不会取代你的 Node 安装 —— 它会与之并存。

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

bun（推荐，安装最快）
bun add -g deeptide

npm（也可以；运行时仍然需要 bun）
npm install -g deeptide

pnpm
pnpm add -g deeptide

会安装两个命令；选择你更顺手的那个：

tide                          # 交互式 REPL（首选 —— 更短）
deeptide                      # 同样的东西，完整名称
tide -p "explain this repo"   # 一次性模式
tide --help                   # 所有选项

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

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

从源码构建 macOS 原生应用

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

快速开始（CLI）

DeepTide CLI 默认与 DeepSeek API 通信（与 DeepTide 原生应用一致），也可以通过 BYOK 驱动任何兼容 Anthropic 协议的端点 —— 智谱 GLM、火山引擎、Paean、Qwen、Moonshot、自托管网关等等。

默认路径 —— DeepSeek
export DEEPSEEK_API_KEY="sk-..."
tide

BYOK 到另一个提供商
tide --base-url https://open.bigmodel.cn/api/anthropic --api-key

一次性、非交互式
tide -p "Explain the auth middleware"

有关完整的配置面（settings.json schema、hooks、权限、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 的侧边栏中，一键即可恢复。
- 相同工具——完整的 agent 工具集（Read/Write/Edit、Bash、Glob/Grep、WebFetch、MCP 服务器、子 agent……）以相同方式可用。

它的功能：带 markdown 渲染的流式聊天、实时的 reasoning（“💭 thinking”）和工具调用卡片、交互式工具审批（Write/Edit 带有彩色 diff 预览）、会话侧边栏（恢复过往聊天）、provider/model 选择器、New chat、Stop/interrupt，以及成本/用量栏（↑/↓ tokens · cache · $）。

启动

通过 CLI 启动器（exec 桌面二进制文件，共享此配置/当前工作目录）：
deeptide-rs --gui

……或直接运行 GUI 二进制文件：
deeptide-gui

从源码构建

从仓库根目录（crates/ 下的 Rust workspace）：
cargo run -p deeptide-gui            # 开发运行
cargo build -p deeptide-gui --release # release 二进制文件位于 target/release/deeptide-gui

像 CLI 一样配置模型——例如在启动前 export DEEPTIDE_API_KEY=…（或在 settings.json 中设置）。没有凭据时，GUI 会以安全的本地回显模式打开，并显示“no API key”横幅。要将其指向非默认 provider，请使用应用内选择器或 export DEEPTIDE_PROVIDER=…（例如 deepseek、ollama、openai、gemini）。

内置能力

DeepTide 是一个agentic 编码助手——模型会规划、调用工具、观察结果并进行调整。开箱即用：

- 多轮 agentic 循环——规划 → 工具 → 观察 → 调整
- 流式响应——实时看到模型思考和行动
- 30+ 内置工具——文件 I/O、shell、web、任务、MCP、调度、子 agent
- 25+ 斜杠命令——/status、/cost、/diff、/init、/permission、/hooks……
- 权限模式——default · accept-edits · plan · bypass
- Hooks 引擎——pre/post tool、user-prompt、session、compaction shell hooks
- 记忆系统——跨会话的持久项目记忆
- 来自 markdown 的子 agent——在你的项目中定义自定义 agent
- 来自 markdown 的自定义斜杠命令——将 .md 放到
.deeptide/commands/（或 ~/.deeptide/commands/）下，然后以 / 运行它；
其正文会成为一个提示词，并支持 $ARGUMENTS / $1…$11 替换。内置
命令始终优先。
- 计划模式 — 先设计再编码，执行前先获得批准
- 网络研究 — /deep-seek  使用模型的内置
知识来提出可能的官方/规范 URL，然后通过
WebFetch 验证它们。可选的 BRAVE_SEARCH_API_KEY / SERPER_API_KEY 凭据
可以改善来源发现，但基于 URL 的研究并不需要它们。
来源会被标记为 [verified]、[known] 或 [unverified]。

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

文档

- tide-spec — 共享接口契约：工具目录、斜杠命令、CLI 标志、钩子环境变量、模型别名。
- Zero CLI 文档 — CLI 引擎的全面参考。
- DeepTide 原生源码 — macOS 应用的 Swift 代码库。
- native/ — 本地 DeepSeek 运行时源码：ds4 推理引擎和 dsgo 网关。
- docs/deepseek-v4-flash-q2.md — 原版本地 V4 Flash Q2 构建适合什么、不适合什么，以及为什么 deeptide 将其上下文上限设为 64k。还介绍了面向 192 GB+ 内存主机的高保真 Q4_K 混合精度构建（153 GiB）。
- 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/pixel-roguelike — 一个无依赖的
HTML Canvas 类 Rogue 展示项目，包含可编辑的像素艺术精灵、程序化
地形、响应式移动端控制、战斗效果，以及一个像素艺术预览
辅助工具。
- samples/pixel-backpack-roguelite —
一个像素背包类 Rogue 轻量游戏，包含空间物品规划、合并、神器
锻造、自主 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 表单会将你引导至正确的模板：

- CLI 缺陷或功能 — 通常会转发至
a8e-ai/zero-cli，因为 CLI
代码位于那里，但如果你不确定，也可以从这里开始。
- macOS 原生应用 — 在此处报告。在粘贴日志之前，请隐去任何敏感的
路径、文件名或模型输出。
- 文档、安装或一般问题 — 从这里开始。
- 安全漏洞 — 请使用私密漏洞报告，而不是公开 issue。

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

关于此 npm 包

deeptide npm 包是一个有意保持轻量的重定向，指向
@paean-ai/zero-cli，
其中包含所有 CLI 源代码。我们以两个名称发布，以便用户
可以安装自己觉得更自然的那一个；两者都解析到同一个二进制文件，
并带有 DeepTide 品牌界面。只有一个事实来源
（a8e-ai/zero-cli）——没有
重复实现。

许可证

MIT — 请参阅 LICENSE 和 NOTICE。

DeepTide 是一个独立项目，与 Anthropic, Inc. 或 DeepSeek（杭州）
AI Co., Ltd. 无关联、未获其背书，也未受其赞助。

由 a8e 用 🐳 构建 — 为 DeepSeek，在所有平台上。