navig

Name: navig
Author: navig-run

本地服务

navig.run开发工具53 天前更新

代码仓库访问官网

关于 navig

NAVIG 是面向运维人员的终端优先基础设施 CLI 和运行时，可管理本地及远程系统。它整合主机、数据库、文件、容器和工作流操作，并提供可选 AI 辅助与 MCP 服务。

主要功能

01通过 SSH 管理主机并运行命令
02操作数据库、文件和容器
03在加密保险库中存储凭据
04以预览和试运行定义工作流
05发现网状网络节点并委派命令
06通过 MCP 暴露工具和资源

适用场景

01从单一 CLI 上下文管理多台远程主机
02执行前预览多步骤基础设施变更
03避免在明文配置中保存凭据
04让 AI 编辑器通过 MCP 使用基础设施工具

MCP 相关

NAVIG 内含 MCP 服务，可向 AI 编辑器和兼容客户端提供工具与资源。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "navig-run-navig": {
      "command": "uvx",
      "args": [
        "navig"
      ]
    }
  }
}

启动命令uvx navig

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypinavig3.27.5stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

NAVIG

墓地里看不见管理员
问题从来不在终端，而在它周围的混乱。

navig 主机列表、通过 SSH 运行 navig 的真实场景，以及 navig apply safe-deployment --dry-run

说明

NAVIG 3.x 是稳定版本。 CLI 合约（navig <resource> <action>）稳定不变，变更遵循语义化版本。升级跨越主版本前，请查看变更日志。与任何操作实时基础设施的工具一样，在生产关键环境中，请先使用只读检查和试运行。

查看实际效果

这些真实会话录制自 tools/showcase/ 中的录像带，运行于实验室主机上 — 输出内容未经输入，也没有任何剪辑。全部 11 个场景、视频及制作方式：docs/showcase · 视频（以及一段 90 秒预告片）收录于 NAVIG 3.25.0 版本发布页。

实时仪表板 — `navig dashboard`	主机与安全 — `host test`，第二个会话遭拒，破坏性命令被拒绝
空间 — `space init --dry-run` → `space init` → `space doctor`	区块 — `block show` → `apply --dry-run`，显示每个步骤的风险
日志与撤销 — `ledger show` → `ledger verify` → `undo --list`	你的节点 — `navig whoami`

前置条件

NAVIG CLI 使用 Nerd Font 字形来显示 Powerline 风格的状态栏和图标。每台机器只需安装一次：

pwsh navig/builtin/scripts/Install-NerdFont.ps1

平台	推荐的终端	额外步骤
Windows	Windows Terminal	脚本会自动修补
macOS	iTerm2 或 Kitty	脚本运行后，将字体设为 JetBrainsMono Nerd Font Mono
Linux	Kitty、Alacritty、GNOME Terminal	脚本运行后手动设置字体

所有平台上的 VS Code 都会自动修补。运行脚本后，请重启 VS Code 和终端。

离线安装：将 $env:NAVIG_FONT_ZIP 设为本地 zip 路径，或传入 -LocalZip <path>。

NAVIG 是什么？

NAVIG 是一款以终端为先的基础设施 CLI 和运行时，面向那些厌倦了在 SSH 会话、零散脚本、彼此割裂的仪表板和临时凭据之间来回奔波，只为维持系统运行的人。

它由一位独立创始人开发，他负责管理不断增长的一群远程机器、项目和运维事务，却没有平台团队可以依靠。问题不在终端，而在周围的一切都支离破碎：SSH 在一个地方，SFTP 在另一个地方，数据库藏在仪表板后面，密钥被粘贴到笔记中，日志散落在各个服务提供商处，也没有一个统一连贯的操作界面。

NAVIG 源于不愿接受这种现状。

它让运维人员能够在一个地方直接控制远程主机、数据库、容器、文件、隧道和工作流，并提供清晰的结构、记忆能力和可选的 AI 辅助；只有在真正有用时，AI 辅助才会介入。

一个运维操作界面。为运维人员打造。

NAVIG Core（免费）与 NAVIG Deck（付费）

NAVIG 分为两个有意区分的层次：

NAVIG Core（本仓库）——Apache-2.0 开源。包括守护进程、CLI、 Agent 运行时、保险库、调度器、网状网络、MCP 服务、Telegram 文本机器人、网关。永久免费，可通过 CLI 连接任意数量的主机，不含遥测。
NAVIG Deck——精致的 UI 操作台（专有；通过 pip install navig[deck] 安装已签名的 PyPI wheel）。包括主机清单、网状网络拓扑、保险库 UI、任务队列、工作流运行器、Telegram Mini App。单台主机免费；Harbor Pass / Max 可增加主机规模，并提供完整的运维模块套件——请参阅 navig.run/deck。

这种划分坦诚透明：守护进程是开源且可审计的，Deck 在单台主机上免费，而 Harbor 订阅则增加主机规模、所有运维模块以及整个 Harbor Bay。有关套餐，请参阅 navig.run/buy。

无论如何，以下功能永远免费：

整个 CLI——无限次使用 navig ssh，连接任意数量的主机
Telegram 文本机器人（/start、/run、/status 及所有命令）
Agent 运行时（navig ask、对话记忆、任务）
VS Code MCP 集成
保险库、调度器、网状网络对等节点发现
所有更新，包括主要版本更新

Harbor 订阅的费用用于扩展规模和运维套件； 守护进程永远不会收费。

为什么选择 NAVIG？

大多数运维人员已经有 SSH。他们缺少的是围绕 SSH 应有的一切：

你可能已有	NAVIG 带来的功能
SSH 客户端	多主机管理，并可使用一个活动上下文
临时 Shell 脚本	支持试运行和预览的命名工作流
`.env` 文件中的密钥	可根据上下文解析的加密保险库
在日志文件中使用 `grep`	跨主机结构化追踪日志
从 Stack Overflow 复制粘贴	以你的基础设施为上下文的 AI 运维层
每台机器各开一个终端	网状网络和命令委派

NAVIG 不是配置管理工具（不是 Ansible），也不是部署平台（不是 Kubernetes）。它是一个面向人类的控制平面——当你需要立刻对一台真实机器执行操作，又不想编写 Playbook 时，就可以使用它。

功能

能力	说明
多主机管理	通过 SSH 添加、切换、测试和操作远程主机
远程执行	运行命令、通过管道传递 stdin，并使用 base64 编码处理复杂脚本
数据库操作	查询、转储、还原和维护 MySQL、MariaDB 和 PostgreSQL
文件操作	安全地上传、下载、读取、编辑和列出远程文件
Docker 和容器	检查容器、重启服务、查看日志尾部，以及管理 compose 堆栈
Web 服务控制	管理 nginx/apache 配置、测试更改并安全地重新加载
加密保险库	存储凭据，避免密钥以明文形式留在配置文件中
工作流	定义可重复的多步骤流程，并支持试运行和预览
AI 操作层	通过命令行、Telegram 或 MCP，以自然语言协助处理基础设施任务
网状网络	在 LAN 中发现点对点节点并委派命令
MCP 集成	向 AI 编辑器和兼容客户端公开工具和资源
守护进程和网关	后台服务，支持 Telegram 和 Matrix 频道
Telegram 管理器	完整的 Telegram 账号管理工具（MTProto）：搜索、移动、转发、去重 + 商务对话 AI 捕获器、关键词回复操作、删除提醒和富消息回复——仅限所有者（文档 · 速查表）
GitHub 镜像	`navig github` — 搜索、备份和克隆 GitHub 仓库（平铺或嵌套），令牌来自保险库
TikTok	`navig tiktok` — 下载视频、提取元数据和热门评论，并通过 AI 概述任意链接（使用 yt-dlp）

安装

Linux / macOS / WSL

curl -fsSL https://navig.run/install.sh | bash

Windows（PowerShell）

iwr -useb https://navig.run/install.ps1 | iex

pipx

pipx install navig

pip

pip install navig

安装选项

选项	示例	说明
`--version`	`bash -s -- --version <release>`	固定使用特定版本
`--dev`	`bash -s -- --dev`	包含开发所需的额外依赖
`--method git`	`bash -s -- --method git`	从源代码安装，而非从 PyPI 安装
`NAVIG_EXTRAS`	`NAVIG_EXTRAS=voice,keyring`	启用可选的额外功能
`NAVIG_INSTALL_PROFILE`	`NAVIG_INSTALL_PROFILE=operator`	选择首次运行时的引导配置

安装后，可通过安装程序流程进行 Telegram 引导：

NAVIG_TELEGRAM_BOT_TOKEN="<your-bot-token>" navig init --profile operator

开发环境安装

git clone https://github.com/navig-run/core.git navig
cd navig
pip install -e ".[dev]"

使用虚拟环境（可选，但建议使用）：

git clone https://github.com/navig-run/core.git navig
cd navig
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

验证

navig --version
navig --help

还没有服务？从这里开始（本地模式）

如果你目前还没有可用的远程服务，NAVIG 也可以在 localhost 上运行：

# Install
pip install navig

# Discover your local machine as a host
navig host discover-local

# Run your first command (on this machine)
navig run "echo hello from NAVIG && uname -a"

# Explore files
navig file list ~ --tree --depth 2

# Ask the AI operator layer something
navig ask "what process is using the most CPU right now?"

首次运行即告完成——无需远程服务。

快速入门

# 1. Initialize — creates ~/.navig/, runs setup wizard
navig init

# 2. Add a remote host
navig host add

# 3. Test the connection
navig host test

# 4. Set it as active
navig host use <name>

# 5. Run your first remote command
navig run "uname -a"

# 6. Ask the AI operator layer something about it
navig ask "what is consuming the most memory on this host?"

就是这样。之后的一切都以此为基础。

还没有服务？examples/quickdemo.sh 会引导你在自己的机器上用 60 秒完成相同的流程。

接下来可以做什么 — 完成首次 navig run 后：

命令	功能
`navig host add`	添加更多主机
`navig vault set KEY=value`	加密存储密钥
`navig db query "SELECT 1"`	连接到远程数据库
`navig tunnel 5432`	打开到某个端口的 SSH 隧道
`navig flow run deploy.yaml`	运行多步骤工作流
`navig ask "..."`	向 AI 操作层询问任何问题

命令参考

所有资源的命令模式都一致：

navig <resource> <action> [options]

基础设施

命令	功能
`navig host`	添加、切换、测试和检查远程主机
`navig run`	在远程或本地主机上执行命令
`navig file`	上传、下载、读取和编辑远程文件
`navig db`	查询、转储、还原和维护数据库
`navig docker`	执行容器和 compose 操作
`navig web`	配置、测试和重新加载 Web 服务
`navig tunnel`	管理 SSH 隧道
`navig backup`	备份 / 还原配置和数据

AI 与自动化

Command	功能
`navig ask`	AI 辅助故障排查和命令指导
`navig flow`	多步骤自动化工作流
`navig mcp`	用于 AI 编辑器和工具集成的 MCP 服务
`navig gateway`	启动和管理聊天网关（Telegram、Matrix）
`navig agent`	自主 Agent 运行时 — 安装、启动、配置和管理
`navig telegram`	Telegram 管理器 — 登录、搜索、整理、商务线索捕获、表情符号权限
`navig github`	搜索 / 备份 / 克隆 GitHub 仓库（默认平铺存放）— 从保险库读取令牌
`navig tiktok`	下载 TikTok 内容 + AI 简报（描述 + 热门评论）

组织管理

Command	功能
`navig config`	查看、验证和管理配置
`navig vault`	加密凭据存储
`navig space`	多上下文操作环境
`navig mesh`	局域网对等节点发现和命令委派

运行 navig help 或 navig help <topic> 查看详细用法。每条命令也支持 --help。

插件

第一方插件可为 navig 扩展新命令，其中一些插件还可以独立运行，完全无需安装 navig。源码和各插件文档：navig-run/plugins。

插件	功能	可独立运行	安装
navig-agentctl	Agent 控制中心（devops 部分）：会话、工作树、任务和 Agent Monitor（运行、钩子、已验证的合并）…	— 添加 `navig agentctl`	`pip install "navig[agentctl]"`
navig-ahk	面向 navig 的 AutoHotkey v2 自动化——点击、输入、打开、窗口操作和 AI 编写的脚本，作为独立插件提供	— 一个 Deck 界面	`pip install "navig[ahk]"`
navig-alexa	Alexa 自定义技能服务——托管官方技能，通过语音运行 NAVIG，并验证请求…	✅ `navig-alexa`	从源码安装（尚未发布到 PyPI）
navig-alice	NAVIG 的 Yandex Dialog（навык Алисы）webhook，并可通过 api.iot.yandex.net 控制 Yandex Station 和智能家居	✅ `navig-alice`	从源码安装（尚未发布到 PyPI）
navig-antivirus	扫描浏览器扩展中的恶意软件/PUP、审计 Chrome 扩展注册表、恢复 Chrome 配置文件索引，以及…	✅ `navig-antivirus`	`pip install navig-antivirus`（与 navig 搭配：`navig[antivirus]`）
navig-audio	朗读文本、转录音频、生成音乐和音效、分析节拍并渲染播客——作为独立…	✅ `navig-audio`	`pip install navig-audio`（与 navig 搭配：`navig[voice]`）
navig-blackbox	适用于任意 Python 应用的独立飞行记录器和崩溃黑匣子：只追加事件日志、sys.excepthook 崩溃…	✅ `navig-blackbox` · `nbb`	`pip install navig-blackbox`（与 navig 搭配：`navig[blackbox]`）
navig-bookmarks	本地书签管理器：从任意浏览器或 HTML 导出文件导入、全文搜索、AI 文件夹规划和标签，并可使用你的…	✅ `navig-bookmarks`	`pip install navig-bookmarks`（与 navig 搭配：`navig[bookmarks]`）
navig-browser	启动隔离的 Chrome/Edge/Brave 或 Electron 应用，通过 CDP 控制，保留命名配置文件，并只停止…	✅ `navig-browser`	`pip install navig-browser`（与 navig 搭配：`navig[stealth]`）
navig-cabinet	在一个插件中管理文档：用于存放重要文件（身份证和护照扫描件、医疗记录等）的加密文件柜…	✅ `navig-cabinet`	`pip install navig-cabinet`（与 navig 搭配：`navig[cabinet]`）
navig-calendar	列出/添加/同步日历事件（Google Calendar、CalDAV、ICS）	✅ `navig-calendar`	`pip install navig-calendar`
navig-chats	用于 AI 对话的本地库：导入 ChatGPT 数据导出文件，使用 NAVIG 从页面保存聊天记录…	✅ `navig-chats`	`pip install navig-chats`（与 navig 搭配：`navig[chats]`）
navig-companion	NAVIG 的语音伴侣——对话、简报、思考、问答、音乐	— 添加 `navig companion`	从源码安装（尚未发布到 PyPI）
navig-contacts	`navig contacts`：将通讯录和 dispatch 用于解析的别名到路由表合并存储	✅ `navig-contacts`	`pip install navig-contacts`
navig-debrief	工作会话的可视化展示：根据转录内容中的事实生成幻灯片（navig debrief），并提供完整 HTML 报告…	✅ `navig-debrief`	`pip install navig-debrief`（与 navig 搭配：`navig[debrief]`）
navig-dedupe	免费、独立的感知式重复文件查找工具，支持照片、视频、音频和任意文件	✅ `navig-dedupe` · `ndup`	`pip install navig-dedupe`（与 navig 搭配：`navig[dedupe]`）
navig-devhost	通过一条命令，为任意本地开发服务配置真实的 .test 域名和可信 HTTPS（hosts + mkcert + 原始 TLS 中继）…	✅ `navig-devhost`	`pip install navig-devhost`
navig-devnet	开发者/运维网络检查：DNS/WHOIS/SSL 查询和带 SSRF 防护的 HTTP 重放器——独立的 navig-devnet…	✅ `navig-devnet`	`pip install navig-devnet`（与 navig 搭配：`navig[devnet]`）
navig-distribution	NAVIG OS 的分发工具：按项目划分的渠道调研、资格审核、营销活动、区块级内容、身份…	— 添加 `navig distribution`	从源码安装（尚未发布到 PyPI）
navig-download	通用媒体下载器（yt-dlp）：从 YouTube、TikTok 和任何受支持的网站下载视频、音频和文件	✅ `navig-download`	`pip install navig-download`（与 navig 搭配：`navig[download]`）
navig-ebay	通过官方 Sell API 在 eBay 上销售（起草、发布、定价、订单），并接入 `navig ebay`	✅ `navig-ebay`	`pip install navig-ebay`（与 navig 搭配：`navig[ebay]`）
navig-email	Gmail 邮件管理：规则、监控、标签、统计、摘要、草稿——提供独立的 navig-email 命令（通过…使用 Gmail 应用专用密码）	✅ `navig-email`	`pip install navig-email`
navig-explore	适用于任意文件夹的通用本地媒体/数据浏览器	✅ `navig-explore`	`pip install navig-explore`
navig-games	主动查找并自动领取免费游戏（目前支持 Epic；接下来支持 GOG/Amazon/Steam），并管理游戏库	✅ `navig-games`	`pip install navig-games`（与 navig 搭配：`navig[games]`）
navig-generate	使用你自己的提供商密钥生成图像、视频和音频，保留喜欢的变体并进行剪辑、添加特效等编辑…	✅ `navig-generate`	`pip install navig-generate`（与 navig 搭配：`navig[generate]`）
navig-github	完整的 GitHub 工具箱（备份、镜像、导出、管理）：提供独立的 navig-github 命令，也可在 navig 中使用 `navig github`	✅ `navig-github`	`pip install navig-github`（与 navig 搭配：`navig[github]`）
navig-glass	NAVIG Glass 集成：查找独立查看器，通过 NAVIG 打开文件，并确保 Glass 在没有 NAVIG 时仍可完整使用	— 添加 `navig glass`	从源码安装（尚未发布到 PyPI）
navig-google	通过 Gemini API 获取以 Google Search 为依据的 AI 答案：附引用来源、只需一个密钥、按请求计费——…	✅ `navig-google`	从源码安装（尚未发布到 PyPI）
navig-home	统一控制整个家庭网络：查找局域网上的所有设备、维护一份清单、读取 Livebox DHCP 的实际信息…	✅ `navig-home`	从源码安装（尚未发布到 PyPI）
navig-lights	控制灯具：通过局域网 API 或开发者云控制 Govee 设备，以及 Home Assistant 识别的所有设备——简洁的连接桥梁…	✅ `navig-lights`	从源码安装（尚未发布到 PyPI）
navig-matrix	面向 navig 的 Matrix 消息界面——房间、邀请、令牌、管理和收件箱桥接，作为独立插件提供	— 一个 Deck 界面	`pip install "navig[matrix]"`
navig-media	一次安装即可使用 NAVIG 媒体套件：图像和视频生成、语音和音乐、写作，以及…的制作流水线	✅ `navig-media`	`pip install navig-media`
navig-media-core	NAVIG 媒体软件包所依赖的共享媒体引擎——媒体类型和生成器注册表、生成…	— 一个共享库	`pip install navig-media-core`
navig-menu	AI 优先的菜单构建器——自动检测任意项目的技术栈，并构建带有布局等功能的高级交互式终端菜单…	✅ `navig-menu` · `nm`	`npm i -g navig-menu`
navig-mini	适用于 Raspberry Pi、NAS 设备和低功耗设备的轻量级 AI Agent 守护进程	✅ `navig-mini`	`pip install navig-mini`
navig-mobile	专业级 Android + iOS 设备操作：连接、设备信息、应用、文件提取、截图、备份，以及取证…	✅ `navig-mobile`	`pip install navig-mobile`（与 navig 搭配：`navig[mobile]`）
navig-msstore	NAVIG 的 Microsoft Store 发布操作，封装 msstore-publish 模块	✅ `navig-msstore`	`pip install navig-msstore`
navig-notes	这台电脑上的网页便笺：NAVIG Dock 会同步你在某个页面、某个网站或任何位置保留的所有便笺，因此…	✅ `navig-notes`	`pip install navig-notes`（与 navig 搭配：`navig[notes]`）
navig-obs	通过 navig 控制 OBS Studio——场景、来源、直播、录制、演播室模式，以及完整的 obs-websocket v5 功能…	✅ `navig-obs`	`pip install navig-obs`
navig-pentest	仅供授权使用的进攻性安全工具包：被动侦察（RDAP/whois、DNS、crt.sh 子域名、HTTP 指纹识别）…	✅ `navig-pentest` · `navig-warroom` · `warroom-osint`	`pip install navig-pentest`
navig-perplexity	委托独立的智力工作——研究、文章、营销文案、命名、比较、评析…	✅ `navig-perplexity`	从源码安装（尚未发布到 PyPI）
navig-pipeline	内容制作流水线：跟随节拍剪辑的竖屏短片、配音短视频、字幕和开场文案，以及下载 →…	✅ `navig-pipeline` · `navig-content`	`pip install navig-pipeline`
navig-router	NAVIG Router：一个原生兼容 OpenAI 和 Anthropic 的大模型端点，可连接所有你已有密钥的提供商…	— 添加 `navig router`	从源码安装（尚未发布到 PyPI）
navig-sessions	通过 CDP 读取并完成 VS Code 中打开的 Claude Code 会话：每个空闲会话提供一条完成提示词，适用于…	✅ `navig-sessions`	从源码安装（尚未发布到 PyPI）
navig-social	在各社交网络上撰写、安排和发布内容（Studio + 一键分发至多个平台）	✅ `navig-social`	`pip install navig-social`（与 navig 搭配：`navig[social]`）
navig-tasks	Navig-tasks：面向项目的任务、触发器、操作，以及 NAVIG 的 Telegram 审核循环	— 添加 `navig tasks`	从源码安装（尚未发布到 PyPI）
navig-telegram	面向 navig 的 Telegram 界面——机器人管理、会话、状态和 MTProto 用户账户操作，作为独立插件提供	— 一个 Deck 界面	`pip install "navig[telegram]"`
navig-text	AI 文本生成（草稿/文章/说明文字/简报）+ `navig design`（由 Agent 重新设计 HTML/CSS + 设计令牌），用于…	✅ `navig-text`	`pip install navig-text`
navig-tv	通过 ADB 全面控制 Fire TV 或 Android TV——电源、方向键、媒体键、启动应用、输入文本、音量…	✅ `navig-tv`	从源码安装（尚未发布到 PyPI）
navig-vault	免费、独立、加密的开发者机密管理器（Doppler / 1Password-CLI / Infisical 类）	✅ `navig-vault` · `nv`	`pip install navig-vault`
navig-video	根据频道工作区中的文本、底图等素材，渲染频道的视频格式（动感系列节目、简报、动态卡片）…	✅ `navig-video`	`pip install navig-video`（与 navig 搭配：`navig[video]`）
navig-vm	使用经过验证的云映像创建本地 VMware Workstation 虚拟机，首次启动时通过 cloud-init 配置，并通过…进行控制	✅ `navig-vm`	`pip install navig-vm`（与 navig 搭配：`navig[vm]`）
navig-voice	面向 NAVIG 的本地语音栈，通过 `navig assistant` 挂载：唤醒词、语音转文本、带技能的规则式 NLU、TTS…	✅ `navig-voice`	从源码安装（尚未发布到 PyPI）
navig-youtube-music	通过经过身份验证的本地 API 和现有 CDP 端点控制 YouTube Music 桌面应用（Venipa ytmdesktop2）…	✅ `navig-youtube-music`	从源码安装（尚未发布到 PyPI）

Agent 运行时

NAVIG 提供一个自主 Agent 层，作为持久的后台进程运行。

# One-time setup: write ~/.navig/agent/config.yaml and create runtime directories
navig agent install

# Optional: register as an OS service (starts on boot)
navig service install
navig service start

# Check state
navig agent status

运行模式：supervised（默认，会确认操作）、autonomous（无需提示即可执行）、observe-only（读取并报告，不执行写入操作）。个性配置：friendly、professional、witty、paranoid、minimal。

完整参考请参阅 docs/agent/install.md。

AI 和聊天界面

NAVIG 可通过以下方式提供其操作层：

CLI（navig ask）
Telegram（通过 navig gateway）
Matrix
任何兼容 MCP 的编辑器（Cursor、Claude Desktop、VS Code）

navig ask "Why does this container keep restarting?"

AI 层可协助推理、提供上下文并执行工作流。它不会取代操作员的直接控制权——操作员始终承担责任，也始终掌握控制权。

云路由（relay.navig.run）

NAVIG 托管的 Deck 位于 relay.navig.run。它是一个静态 React 应用 + 一个轻量级 broker（Cloudflare Pages Functions + D1），用于将守护进程的 API key（以及你的 Telegram user_id）映射到其当前的公共 URL。守护进程每次启动时都会向 broker 注册自身；Deck 和 Telegram Mini App 则通过 broker 查询“我的守护进程在哪里”。守护进程数据永远不会离开你的设备——broker 仅存储路由元数据（api_key 的 SHA-256、当前公共 URL 和 Telegram 绑定信息）。

模式 — 选择一种

模式	适用场景	启用方式	需要订阅吗？
Lighthouse （推荐）	你希望始终能够访问（Telegram / SMS / 远程 Deck），且无需隧道或域名。	`navig lighthouse deploy` 会在你自己的 Cloudflare 账户中部署一个轻量级边缘服务（无需 Node/wrangler）；核心服务通过一个 WebSocket 向外连接。参见 docs/LIGHTHOUSE.md。	不需要 — 在你自己的 Cloudflare 上自托管，对所有人免费。
cloudflared / 托管中继	笔记本、家用设备或任何位于 NAT 后的设备。无需公共 IP 或域名。	守护进程会启动 `cloudflared`，创建免费的 `*.trycloudflare.com` 快速隧道。手动启用：`navig cloud connect`。	新 Solo 用户和活跃订阅用户可免费使用。订阅过期后有 30 天宽限期；仅购买永久版的用户可改用 Lighthouse/Tailscale 自托管。
Tailscale Funnel	你希望为 Mini App 提供免费的、稳定且无需订阅的公共 URL。	`navig cloud tailscale --enable` — 通过 Tailscale Funnel 启用 `*.ts.net` URL，然后运行 `navig miniapp register` 将其提交到 BotFather。	不需要 — 直连模式，不涉及 broker。
直连（你的域名）	拥有公共域名和反向代理（nginx、Caddy、Traefik）的 VPS。	`navig cloud direct https://navig.example.com` — 守护进程会完全跳过 `cloudflared`，并向 broker 注册你的 URL。也会读取 systemd `Environment=` 行中的 `$NAVIG_PUBLIC_URL`。	不需要 — 直连模式，不涉及 broker。
关闭	完全仅限本地使用。不与 broker 通信。	`navig cloud disconnect`（或在 `~/.navig/config.yaml` 中设置 `cloud.enabled: false`）。	不需要。

订阅版与永久版的区别：托管云中继是唯一一项每月会产生费用的功能，因此它属于订阅功能。永久版用户可永久使用完整的本地应用，并通过一条 Tailscale 命令自托管 Mini App——免费、稳定，且不会给我们带来任何成本。完整架构请参阅 docs/CLOUD.md。

3 条命令即可始终在线（你自己的边缘服务 + 你自己的 Deck）

NAVIG 完全部署在你自己的 Cloudflare 账户中——两个轻量部署，各自拥有稳定的 URL，此外，你的 brain 会主动连接：

navig lighthouse login     # 1. EDGE: API uplink (Worker + Durable Object). Opens
                           #    Cloudflare → click Authorize → deploys + sets the
                           #    Telegram webhook. (Or: navig lighthouse deploy --token <t>)
navig miniapp deploy       # 2. DECK: builds the UI (static export) → your own
                           #    Cloudflare Pages, bakes the edge URL in (auto-targets
                           #    your brain) → sets the bot's Mini App button.
navig gateway start        # 3. BRAIN: your daemon dials OUT to the edge. Nothing inbound.

打开你的 bot → 点击菜单按钮 → 你的 Deck，通过你的边缘服务与你的 brain 通信——随时随地都能访问，无需隧道、端口转发或域名。navig lighthouse url 会打印所有入站钩子（Telegram 会自动设置；只有使用 SMS 时才将 SMS 钩子粘贴到 Twilio；社交平台发布器采用出站连接——只需令牌，无需 webhook）。

两个部署共用一个 Cloudflare 凭据，无需 wrangler：lighthouse deploy/login 和 miniapp deploy 都通过 Cloudflare REST API 上传，并共用同一凭据（采用 "Edit Cloudflare Workers" 模板的 API 令牌，或通过 lighthouse login 获取的 OAuth 令牌）。Node 18+ 仅用于构建 Deck（miniapp deploy）；上传（与边缘服务一样）无需 Node 或 wrangler。（如果你更喜欢使用 Cloudflare Pages，可将 miniapp deploy --wrangler 用作备用方案。）

端口和防火墙（速查表）

模式	入站	出站	守护进程绑定
cloudflared	无	443 → `*.cloudflare.com`（cloudflared 会建立出站 WebSocket）	`127.0.0.1:8765`（仅限环回接口）
direct	443 → 你的 VPS（由 nginx/Caddy 终止 TLS）	443 → `relay.navig.run`（每 60 秒发送一次心跳）	`127.0.0.1:8765`（你的代理将流量从 443 转发到此处）
off	无	无	`127.0.0.1:8765`（仅限本机）

守护进程本身绝不会绑定到公共接口——在 direct 模式下，监听 0.0.0.0:443 的是你的反向代理。纵深防御：即使代理配置有误，守护进程套接字仍会留在环回接口上。

快速命令

navig lighthouse login        # recommended: your own Cloudflare edge (browser auth)
navig lighthouse url          # show every inbound hook + the one stable edge URL
navig miniapp deploy          # deploy your own Deck UI → bot's Mini App button
navig cloud connect           # turn cloudflared mode on (default)
navig cloud direct https://navig.example.com   # switch to VPS direct mode
navig cloud direct --clear    # revert direct mode back to cloudflared
navig cloud status            # show mode, public URL, last heartbeat
navig cloud disconnect        # full off (no broker, no tunnel)
navig cloud key --reveal      # print the api_key (sensitive)

完整的运维指南（包括现成的 nginx/Caddy 配置、包含 Environment=NAVIG_PUBLIC_URL=... 的 systemd 单元模板、安全模型和故障排查）请参阅 docs/CLOUD.md。

配置

全局配置位于 ~/.navig/。使用 NAVIG_CONFIG_DIR 覆盖。

~/.navig/
├── config.yaml       ← main config
├── vault/            ← encrypted credentials
├── sessions/
├── workspace/
│   ├── SOUL.md       ← persistent operator identity
│   └── HEARTBEAT.md
└── logs/

项目专属覆盖配置：在仓库根目录下放置 .navig/ 目录。项目配置优先于全局配置。

请参阅 docs/user/CONFIG_SCHEMA.md 和 docs/user/HANDBOOK.md。

文档

指南
安装	`docs/user/INSTALLATION.md`
快速参考	`docs/user/QUICK_REFERENCE.md`
CLI 命令	`docs/user/CLI_COMMANDS.md`
手册	`docs/user/HANDBOOK.md`
故障排查	`docs/user/troubleshooting.md`
Telegram 设置	`docs/features/TELEGRAM.md`
Agent 运行时（`agent install`）	`docs/agent/install.md`
生产环境部署	`docs/dev/PRODUCTION_DEPLOYMENT.md`
迁移指南	`docs/dev/MIGRATION_GUIDE.md`
插件 / 套件开发	navig-registry

开发

# Lint
ruff check navig tests
ruff format --check navig tests

# Test
pytest

# Build
python -m build

提交 PR 前的快速检查：

python -c "import navig"             # no import errors
navig --help                         # CLI loads in < 1s
pytest tests/ -q                     # all green

完整的贡献工作流、分支模型和提交约定请参阅 CONTRIBUTING.md。

社区与支持

渠道
Bug 报告和功能请求	GitHub Issues
想法与讨论	GitHub Discussions
公告	t.me/navigrun
社区群组	t.me/+OyFMwN66c3M0NTk0
安全问题报告	SECURITY.md

项目结构

navig/
├── navig/               # Main Python package
│   ├── cli/             # CLI app, commands registry, help system
│   ├── commands/        # CLI command modules (one file per resource)
│   ├── agents/          # Specialist agents (inbox router, etc.)
│   ├── memory/          # Conversation store, knowledge base, RAG, embeddings
│   ├── providers/       # AI provider clients, fallback manager, OAuth
│   ├── gateway/         # Chat gateway (Telegram, Matrix) integrations
│   ├── onboarding/      # First-run setup engine and wizard steps
│   ├── daemon/          # Background service entry point
│   ├── core/            # Config loader, migrations, crash handler
│   └── resources/       # Default prompts, personas, assets
├── sdk/                 # Pointer to the SDK in navig-run/registry
├── scripts/             # Install and deployment scripts
├── deploy/              # Docker, systemd, hardening configs
├── docs/                # Documentation
├── packages/            # Optional add-on packages
└── tests/               # pytest test suite

赞助

NAVIG 由一人开发并以开源形式发布。如果它为你节省了时间、避免了错误，或成为你工作流的一部分：

档位
📡 观察者	$5/mo	简单支持。可获得徽章，并可选择在支持者名单中显示姓名。
⚡ 节点运营者	$10/mo	你在实际工作流中使用它。可抢先体验测试版并获取开发动态。
🏗️ 系统架构师	$25/mo	长期支持。可参与路线图讨论并查看私密更新日志。
⚡ 信号助推	$10 one-time	小额直接捐助。
🚀 功能冲刺	$50 one-time	为一次专注的开发冲刺提供资金。
🌐 创始节点	$100 one-time	永久列入 `FOUNDERS.md` 致谢名单。名额有限。

详情请参阅 FUNDING.md。

安全

请私下报告漏洞。请参阅 SECURITY.md。

许可证

Apache-2.0——请参阅 LICENSE。

品牌使用和官方构建身份：TRADEMARK.md · GOVERNANCE.md

由 @miztizm 使用 Forge 编写

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。