主器灵
你交谈的那个常驻器灵。
在首次启动时创建，它是持久的中枢：掌管计划与记忆，并派生出其他角色。小事都交给它——多数时候你只需要它。
新手教程
从零到第一个任务
灵台让你在自己的机器上、在一个项目文件夹里，拥有一个长期的 AI 助手。本指南带你从安装开始，到交给它第一个真正的任务，并把它的运作方式讲到刚好够你自己走下去。
约 10 分钟阅读
灵台是什么，不是什么
灵台是一个长期 AI 器灵（agent）的居所，由你自己运行。它在一个项目目录里工作，并把它所知的一切——记忆、身份、知识、技能——都以普通文件的形式存放在这个目录中。核心思想是：器灵即其文件，文件即器灵。更换底层模型，器灵犹在。
它是
- 一个本地的、以文件为本的 AI 助手居所，由你拥有，并随时间成长。
- 一个终端应用（TUI），用日常语言和少量斜杠命令来驱动。
- 一个记忆、身份、知识、技能都只是文件夹中文件的地方。
它不是
- 一个聊天机器人网站或托管服务——它运行在你的机器上、你的项目里。
- 被单一模型绑定——它与模型无关，LLM 可以替换。
- 只用于写代码——凡你能描述并监督的任务，器灵都能承担。
前置条件与安装
开始之前
- 一个类 Unix 的终端——macOS 或 Linux（Windows 可通过 WSL）。深色终端主题观感最佳。
- Python 3.11 或更高版本。实际上灵台会自行准备并管理它的运行时，你几乎不必直接接触 Python。
- 至少一个 LLM 服务商的凭据（API key）。首次运行时填入即可；无需注册灵台账号。
安装（推荐）
这是新用户的主要安装方式。它会获取预构建的发布版、准备好受管运行时，且不需要 Homebrew。
$ curl -fsSL https://lingtai.ai/install.sh | bash
其他安装方式
Homebrew（老用户）
brew install lingtai-ai/lingtai/lingtai-tui 在迁移期内仍受支持。若你已用 Homebrew 安装，升级用：brew update && brew upgrade lingtai-ai/lingtai/lingtai-tui，然后重启 TUI。
pip（仅用于开发／诊断）
pip install lingtai 这不是常规的安装或升级方式。只有在你要开发或诊断内核本身时才用 pip——它不负责项目运行时。
保持更新
使用推荐安装方式时，TUI 会自行管理其运行时更新。请记住这里有两层——TUI 程序与受管的 Python 运行时；若升级后版本看起来仍是旧的，重启 TUI 并运行 /doctor 修复运行时。
首次启动与你的第一个项目
一个灵台项目就是一个文件夹。你在其中启动 TUI，器灵创建的一切都存放在那里。首次运行时，一个简短的向导会带你完成设置，并启动一个常驻器灵。
-
新建一个项目文件夹并进入
你所在的文件夹就会成为项目。学习阶段先从一个空文件夹开始。
$mkdir my-project && cd my-project -
启动 TUI
这会在当前目录中打开灵台。首次运行会自动创建 .lingtai/ 文件夹并准备运行时。
$lingtai-tui -
跟随设置向导，然后选择 Tutorial 菜谱
向导会依次询问你的 API key、模型、器灵名字和一个起始菜谱。选择内置的「Tutorial」菜谱：器灵会在 TUI 里一课一课地教你使用这套系统。
这个首次向导就是 /setup 流程。你可以随时重新运行 /setup 来更改服务商、模型或能力；加上 /setup credentials 可直接进入凭据检查。
你的第一个真正任务
你通过输入普通消息并按回车来与器灵交谈。一个好的第一个任务是安全、具体、只读的——让器灵先观察，再动手。
试着输入类似这样的话
帮我熟悉一下这个项目。先读 README 和 docs 文件夹，不要修改任何文件；然后告诉我这个项目是做什么的、哪些文件最重要、下一步你建议做什么。
如何给出器灵可执行的指令
- 说明目标——用一句话描述「完成」是什么样子。
- 划定范围——它应该（以及不应该）动哪些文件或文件夹。
- 点明安全边界——例如：不要发送消息、删除文件或泄露密钥。
- 说明如何回报——一段总结、一个清单、一个文件，随你所需。
查看器灵在做什么
这里没有 /status 命令。取而代之的是打开一个面板。最有用的是 /kanban，它显示每个器灵的状态、心跳、token 用量，以及上下文窗口的占用程度。
/kanban | 网络看板：各器灵的状态、心跳、token／体力，以及上下文用量。 |
/daemons | 查看器灵派出的短时工作进程——它们的任务、轨迹与状态。 |
lingtai-tui list --detailed <project-dir> | 在命令行中：列出某个项目目录里的每个器灵（主器灵会被标出）。 |
三种角色：主器灵、分神、分身
灵台不是单个器灵，而是一个小型组织。有三种角色值得早点了解；每种后面附一条经验法则。
分神
一个短时的并行工作者。
为一件嘈杂而有界的工作而分出——批量查找、交叉核对、大范围扫描——之后即弃。你留下它的结论，而非工作者本身。用它来处理一次性的并行爆发。
分身
一个持久的、专门化的队友。
一个长期存在的器灵，拥有自己的记忆、邮箱与职责——像一个固定的、负责某个领域的队友。当某项专长值得跨多次会话持续存在时，就创建一个。
器灵如何记忆：文件、知识、技能
器灵所知的一切都存放在磁盘上的 .lingtai/ 目录里，你可以用 ls、cat 这类普通工具查看。有三个层次值得区分。
文件
普通的工作文件。
器灵在你项目各处读写的报告、修改与产物。没什么特别的——就是工作本身。
知识
持久的、私有的、每个器灵各自的记忆。
器灵为自己保留的长期事实、路径、决策与经验，存于它的 knowledge/ 文件夹。提示词里只放一个简短索引，完整条目按需读取。用 /knowledge 浏览。
技能
可复用的做事方法，所有器灵共享。
Markdown 写成的做事手册（每个是一个 SKILL.md），描述如何完成某类反复出现的任务，按需加载。与「知识」不同，技能在同一个 .lingtai/ 下的所有器灵之间共享。用 /skills 浏览。
上下文与凝蜕
一个器灵一次只能看到有限的对话内容——这就是它的上下文窗口。把它想象成一张慢慢堆满纸张的书桌。当桌子满了，器灵会「凝蜕」：它给自己写一份仔细的总结，然后清空窗口，把这份总结——连同它所有的持久记忆——带到一张干净的书桌上继续。
这是正常的整理，不是故障。在上下文压力下，器灵会在一连串简短的提醒之后自行凝蜕。你通常什么都不用做。
如果某个任务很重要，你可以为凝蜕做准备：先让器灵「收功总结」——把目标、已完成与未完成的部分、关键文件路径、结论和下一步存进它的记忆——然后运行 /molt 强制凝蜕。（不要把它与 /clear 混淆，后者清空对话而不保存；也不要与 /nirvana 混淆，后者不可逆地抹除整个器灵。）
可选：外部渠道与插件
默认情况下你在终端里与助手交谈。如果愿意，你也可以通过外部渠道触达同一个助手——同样的记忆、同样的历史。这些是可选插件，用 /mcp 配置。
- Telegram 从 Telegram 与你的助手交谈，可选设置白名单。
- 飞书 通过长连接的 WebSocket 接入——无需公网 IP 或 webhook。
- 微信／WhatsApp 通过为每种通讯软件准备的桥接触达助手。
- 电子邮件（IMAP） 通过 IMAP/SMTP 给助手一个真正的收件箱，对陌生发件人有安全默认设置。
更改任何渠道或 MCP 配置后，运行 /refresh 让器灵生效。
命令与快捷键速查
在 TUI 中输入 / 打开命令面板；它支持模糊匹配，所以 /skl 就能找到 skills。下面是一份入门用的精简集合：
常用命令
/setup | 设置或更改服务商、模型、能力与凭据。 |
/kanban | 网络看板，含上下文窗口用量。 |
/skills | 浏览共享的技能手册。 |
/knowledge | 浏览该器灵的私有知识（别名：/library、/codex）。 |
/mcp | 管理外部渠道与其他 MCP 插件。 |
/molt | 保存上下文，然后重置对话窗口。 |
/doctor | 诊断连接、密钥、模型，并修复运行时。 |
/help | 打开 TUI 内的帮助阅读器查看完整列表。 |
键盘快捷键
| Enter | 发送当前消息。 |
| Shift+Enter / Ctrl+J | 插入换行而不发送。 |
| / | 打开命令面板（输入以模糊筛选）。 |
| Ctrl+E | 为长消息打开外部编辑器。 |
| Ctrl+T | 在 /skills、/knowledge、/system 视图中切换器灵。 |
疑难排解
- lingtai-tui：找不到命令
- 安装目录不在你的 PATH 中。打开一个新终端，或把安装位置（安装脚本输出末尾会显示）加入 PATH，然后重试。
- TUI 打开了，但助手没有回应
- 它可能正在运行一个耗时的工具，或正在凝蜕——稍等片刻。然后查看 /kanban、运行 /doctor，并查看 .lingtai/<agent>/logs/agent.log 的末尾。
- 我升级了，但什么都没变
- 记住那两层——TUI 程序与它受管的 Python 运行时。重启 TUI；若版本看起来仍旧，运行 /doctor 修复运行时。
- 某个技能或命令好像不见了
- 运行 /doctor 重新解包内置的技能与工具，并确认当前启用了正确的预设。
下一步
要更深入，最快的方式就在产品本身：启动 lingtai-tui，选择 Tutorial 菜谱，让器灵一个概念一个概念地教你。想了解更多时，下面是权威来源。