# ArkExp 快速入门

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

ArkExp 将**火山方舟模型能力**带到用户的本地终端，让你在当前工作目录中用自然语言完成知识问答、内容处理、命令执行和任务管理。ArkExp 适合希望保留终端工作流，同时获得方舟模型与 Agent 完整体验的用户使用。

<span id="what-is-arkexp"></span>
## 什么是 ArkExp

ArkExp 不是一个单纯的聊天窗口，而是面向本地工作环境的 AI-native CLI。你提出目标后，它会结合当前目录和会话上下文规划任务，通过受控工具读取和修改文件、执行命令、调用扩展能力，并将过程与结果持续展示在 TUI 中。

<span id="why-arkexp"></span>
## 为什么使用 ArkExp

ArkExp 的价值不只是把模型放进终端，而是把方舟能力、本地交互和持续任务体验整合成一个完整的 CLI。

- **深度集成方舟体系，而不只是接入一个模型。**  
    与 Claude Code、Codex、OpenCode 等通用 CLI 相比，ArkExp 面向方舟体系原生设计：从火山引擎账号登录、套餐与用量管理、模型和 Endpoint 选择，到豆包 Web Search、OpenViking 知识与资源能力以及 ArkCLI 能力，都可以在同一条体验链路中使用，无需自行拼装多个 Provider、插件和配置。
- **从一次问答升级为可持续的本地任务体验。**  
    交互式 TUI 集中呈现流式响应、工具执行和任务状态；会话恢复、历史记录、Goal、Memory、Context 与上下文压缩共同承载长期任务。运行期间还可以补充指令、排队后续问题或取消操作，让任务始终可见、可控、可继续。
- **开箱即用，同时保持开放、安全和可恢复。**  
    Skills、MCP、Workflow、Cron 与自定义斜杠命令让能力可以按需扩展；权限闸门、高风险操作确认、自动检查点、结果验证和失败记忆则为本地执行提供安全边界与恢复能力。

<span id="quickstart"></span>
## 快速开始

<span id="install-arkexp"></span>
### 一、安装 ArkExp

**前提条件**：
- 请确保本机可以使用 `npm`，并能访问 npm 官方 Registry。
- ArkExp 运行时需要 Bun 1.3 或更高版本。全局安装脚本会在缺少 Bun 时自动调用官方安装器完成安装。如需自行管理 Bun，可设置 `ARKTUI_AUTO_INSTALL_BUN=0` 关闭自动安装，但启动 ArkExp 前仍需保证 Bun 可用。

**安装 ArkExp**：在命令行界面，执行以下命令安装 ArkExp。

```Bash
curl -fsSL https://lf3-static.bytednsdoc.com/obj/eden-cn/welryh/ljhwZthlaukjlkulzlp/prod/install.sh | sh
arkexp --version
```

**更新版本**：可以先检查可用更新，再执行受校验的事务式升级；已经启动的进程继续使用原版本，下次启动切换到新版本。

```bash
arkexp update --check --refresh
arkexp update
```

<span id="start-and-config"></span>
### 二、启动并配置 ArkExp

在任务对应的工作目录中启动 ArkExp。工作目录决定本次会话加载的项目配置、指令与 Skills。

```bash
cd /path/to/project
arkexp
```

**首次使用步骤如下**：

1. 运行 `arkexp` 进入 TUI。
2. 如果首页已经显示可用的模型连接，可直接进入下一步；否则输入 `/login`，按界面提示完成方舟登录。
3. 输入 `/plans`，选择账号已有的 Agent Plan、Coding Plan 或 Platform 按量后付费来源。
4. 输入 `/models`（也可使用 `/model`），从当前来源选择实际可用的模型或 Endpoint。
5. 回到输入框，用自然语言描述任务。首页显示连接可用后即可开始。

**非首次使用步骤如下**：
再次在项目目录运行 `arkexp` 即可，可以关注以下信息：
- ArkExp 会复用已经保存且仍有效的连接。
- 需要切换账号、套餐或模型时，再使用 `/login`、`/plans` 或 `/models`。
- 通过 `/usage` 可以查看受支持 Plan 的额度，通过 `/sessions` 恢复历史会话。

<span id="use-arkexp"></span>
### 三、使用 ArkExp

直接告诉 ArkExp 你希望达到的结果，并补充范围、约束与验收方式。对于会修改文件或执行命令的任务，建议同时说明允许的范围和期望的结果。

| 经典场景 | 示例 Prompt |
|---|---|
| 知识问答 | 结合当前目录中的资料，解释这个项目的目标、主要模块和使用方式。 |
| 内容处理 | 汇总 `@docs/` 下的产品说明，生成一份面向新用户的快速入门。 |
| 日志与数据分析 | 分析 `@logs/app.log`，按错误类型归类并给出排查顺序。 |
| 命令执行 | 运行当前项目的检查命令，解释失败原因；需要修改文件时先说明影响范围。 |
| 多步骤任务 | 把这个任务拆成可执行计划，持续推进，并在关键节点汇报结果。 |
| 代码开发 | 检查当前分支相对基线的改动，重点关注兼容性、权限边界和缺失测试。 |

**常用交互**：
- `Ctrl+K`：打开命令面板。
- `Ctrl+O`：切换模型。
- `Shift+Tab`：切换 Normal、Plan 与 Full Access 权限姿态。
- `Enter`：任务运行时追加当前轮指令。
- `Alt+Enter`：将内容排队为当前任务后的独立追问。
- `Ctrl+C`：运行中中断；空闲时退出。

**非交互模式使用**：在脚本或一次性任务中，可以直接使用以下命令。

```bash
arkexp run "解释这个仓库的核心模块，并列出建议的阅读顺序"
```

完整命令、快捷键和当前版本支持的能力以 TUI 内的 `/help` 为准。

<span id="related-docs"></span>
## 相关文档

* [Ark CLI：Agent Plan 个人版使用指南](/docs/agent-plan-personal-ark-cli)
* [ArkExp 命令参考](/docs/agent-plan-personal-arkexp-command-reference)