概览

Friend 是一个持续思考的个人智能体。安装后，你主要在终端用 friend 与它协作。

Friend 是什么

Friend 在本机后台持续运行，会感知你的输入、调用工具、记住工作上下文，并在需要时主动推进任务。官网这套文档面向终端用户，不展开内部实现细节。

安装后你通常会接触三块：

你大概会怎么用

1. 一键安装 runtime + TUI + Friend Code
2. 在项目目录运行 friend
3. 配置 LLM 供应商与 thinking 模型
4. 用自然语言下任务；需要时用 slash 命令管理会话与配置
5. 需要扩展能力时，从仓库安装 plugin / application / skill

文档怎么读

左侧是大板块；点进某个板块后，右侧正文里的小标题可在页内快速跳转。

推荐阅读顺序：

1. 安装 → 先装起来
2. 第一次使用 → 配模型、发第一条消息
3. 日常使用 / 命令参考 → 熟悉会话与 slash 命令
4. 模型与配置 / 扩展 / 目录与数据 → 按需深入
5. 常见问题 → 出问题时对照

平台与渠道

• 支持：macOS / Linux，常见架构 amd64 / arm64
• 安装渠道：stable（默认）、beta、nightly
• 默认 Registry：https://friend.zhengcloud.ltd（可用环境变量覆盖）

本地优先

配置、会话、日志默认落在本机 ~/.friend。卸载脚本默认不删会话数据。你发给 LLM 供应商的内容会按该供应商条款处理。

安装

用一行命令从 Registry 拉取 runtime、TUI 与 Friend Code 插件。

一键安装

在 macOS 或 Linux 终端执行：

curl -fsSL https://friend.zhengcloud.ltd/install.sh | bash

脚本会：

1. 检测 OS / 架构（不支持会清晰报错）
2. 从 Registry 读取渠道最新组件与校验和
3. 下载并校验 runtime / tui / plugin
4. 写入配置与 client 元数据
5. 按需做首次 bootstrap（例如 LLM 相关引导）

安装完成后进入任意项目目录：

friend

如果提示 command not found：

export PATH="$HOME/.local/bin:$PATH"

建议写入 ~/.zshrc 或 ~/.bashrc。

安装模式

脚本默认会先让你选择模式，而不是静默一键装完：

示例：

curl -fsSL https://friend.zhengcloud.ltd/install.sh | bash -s -- --interactive
curl -fsSL https://friend.zhengcloud.ltd/install.sh | bash -s -- --noninteractive
FRIEND_INSTALL_DRY_RUN=1 bash online/scripts/install.sh

自定义安装

常用环境变量

安装后会有什么

默认布局（可被环境变量覆盖）：

~/.local/bin/friend              # 终端入口
~/.friend/bin/friendd            # 后台 runtime
~/.friend/plugins/friend-code/   # Friend Code 插件
~/.friend/code/                  # 配置、数据、client 元数据
~/.friend/run/                   # socket 等运行文件
~/.friend/logs/                  # 日志
~/.friend/skills/                # 技能目录
~/.friend/applications/          # 应用目录

脚本会对已有文件做备份，避免直接覆盖。

卸载

curl -fsSL https://friend.zhengcloud.ltd/install.sh | bash -s -- --uninstall

这会移除二进制、插件和 client 元数据；默认保留 ~/.friend/code/data 等数据。若要彻底清理（不可恢复）：

rm -rf ~/.friend

请确认不再需要本地会话与配置后再执行。

第一次使用

目标：在当前项目里打开 TUI，配好模型，成功完成一轮对话。

1. 打开 Friend

cd /path/to/your/project
friend

第一次启动时，Friend 会按需拉起后台 friendd，并通过本地 socket 连接 Friend Code 插件。你通常不需要手动分别启动一堆服务。

建议：

• 在真实项目目录打开，这样会话会优先按工作目录组织
• 若 friend 找不到，先检查 PATH 是否包含 ~/.local/bin

2. 配置模型供应商

Friend 需要至少一个 LLM 供应商才能正常思考。在 TUI 里：

1. 输入 /provider
2. 新建或编辑供应商：API 地址、密钥、协议
3. 同步模型目录
4. 用 /model 给不同用途选模型

协议对照

新建供应商时，如果第一个模型要做图片/多模态，可先标记 vision-capable，这样在第一次 sync 前也能进 multimodal 路由。

用途模型

/model 打开选择器后：

• Tab / Shift+Tab：切换用途
• Left / Right：切换供应商
• Up / Down：选择模型
• 支持搜索、分页、当前分配标记

也可以直接指定，例如：

/model compression 17
/model thinking gpt-4.1

旧式 /model <name> 仍等价于给 thinking 指定模型。

3. 开始对话

配好 thinking 模型后，直接在输入框写自然语言任务即可，例如：

帮我看看这个仓库的入口，并总结怎么本地运行。

Friend 会持续思考：感知 → 思考 → 调用工具 → 记忆。多步任务时，它往往会在关键节点给你简短进度。

4. 第一次建议 checklist

• [ ] friend 能启动且不报 socket / command not found
• [ ] /provider 里至少有一个可用供应商
• [ ] 已同步模型目录
• [ ] /model thinking 已绑定可用模型
• [ ] 在项目目录成功完成一轮对话

常见卡点

日常使用

把 Friend 当成常驻在终端里的协作伙伴：会话可恢复，子任务可并行，附件按真实路径交给它。

会话管理

/resume 会把当前工作目录相关会话排在前面。换目录后若“好像丢了”，先 /resume 搜标题或关键词。

每个会话或子代理的输入草稿彼此独立：切走不会把未发送内容泄漏到另一条链。Alt+Up / Alt+Down 可浏览最近提交过的 prompt，并保留当前草稿。发送失败会恢复已提交文本，而不是直接丢掉。

子代理协作

复杂任务时，Friend 可以派生子思维链并行推进（例如一边查入口、一边写文档）。你仍然可以：

• 在 TUI 里看到子代理
• 用 Tab 切到某个子代理继续对话
• 用 /resume <query> 按用途搜子代理

附件

附件以结构化元数据 + 本机绝对路径发送，不是把大文件塞进 socket。Friend 会按文件类型选用合适工具处理。

支持类别包括：文本/代码、图片、音视频、PDF、Office、演示文稿、表格、压缩包、目录、未知二进制。

注意：

• 单条消息最多 16 个附件
• 输入框上方会显示类别 chip；点击是看详情，删除要显式操作
• 大文件优先靠路径与工具读取，而不是整文件粘贴

常用交互习惯

• 用自然语言描述目标、约束、验收标准；比只丢一句“帮我改下”更稳
• 多步任务可让它自己拆；你也可以点名“先调查再改，不要一上来重写”
• 看时间线时：工具调用前通常有一句“我在做什么”的说明
• 需要安静等待长任务时，关注进度消息而不是重复刷同样的指令

退出与关机

日常关掉终端标签页前，优先用命令优雅退出，避免只杀前端却留下困惑状态。后台 friendd 是否常驻取决于你的启动与配置习惯；需要彻底停掉时再处理 daemon。

命令参考

在 TUI 输入框以 / 开头；多数命令支持名称补全。

会话与导航

快捷键：

• Tab / Shift+Tab：切换会话根 ↔ 子代理
• Alt+Up / Alt+Down：历史 prompt
• 侧边栏点选：切换目标链

模型与供应商

选择器内：

• Tab / Shift+Tab：用途
• Left / Right：供应商
• Up / Down：模型
• 支持搜索与分页

系统配置

/setting 左侧是模块（Brain、Memory、Tools、LLM、Skills、Hooks、MCP、Applications…），右侧是字段与当前值。带 ✱ 的通常表示相对默认有改动。配置键在 schema 加载后可自动补全。

退出

补全与输入

• / 后一般可补命令名
• 路径类参数、配置 key、模型名在对应命令下可继续补全
• 失败发送会恢复文本；草稿按链隔离

模型与配置

先保证 thinking 模型可用，再按需配压缩与多模态；系统级开关用 /setting。

供应商（Provider）

在 /provider 中管理：

• 列表与刷新
• 创建 / 编辑：endpoint、credential、protocol
• 同步模型目录
• 新建时可选标记初始模型具备视觉能力

协议映射：

建议：

1. 先写对 base URL 与 key
2. 再 sync 模型目录
3. 最后用 /model 绑定用途

用途路由（Purpose）

Friend 用全局用途路由区分不同模型职责：

三者可绑定不同供应商的不同模型。只配 thinking 也能开始用；压缩与多模态可后补。

系统配置中心

/setting（/settings、/config）对接 Friend 的配置 schema：

• 左侧模块浏览
• 右侧实时值
• 修改后写入控制面（等价于管理端配置更新路径）

常见模块包括 Brain、Memory、Tools、LLM、Skills、Hooks、MCP、Applications 等。不确定某个键含义时，先看 schema 描述，再小步修改。

安装期可选引导

一键安装可在交互/环境变量下预填部分 LLM 与路径配置（例如 FRIEND_LLM_、FRIEND_EMBEDDING_、数据与向量后端）。若安装时跳过：

1. 仍可稍后在 TUI 用 /provider + /model 完成
2. 也可用 /setting 调系统项

若设置了 FRIEND_CONFIG 指向已有配置，安装会尽量复用，而不是覆盖成默认独立库。

最小可用配置清单

• 至少一个 provider（协议、地址、密钥正确）
• thinking 用途已绑定能用的模型
• （可选）compression / multimodal
• （可选）向量后端：默认进程内即可；只有明确需要时再上外部向量库

插件、应用与技能

三类扩展职责不同：插件常驻接入，应用按需打开，技能是可激活的工作规范。

对比

插件（Plugin）

• 适合：平台接入、常驻工具、与 runtime 生命周期相关的能力
• Friend Code 本身就是托管插件：TUI 只连本地 socket，不改 Friend 核心循环
• 安装布局常见于 ~/.friend/plugins/<name>/（含二进制与 manifest.json）
• 可在官网 仓库 按 plugin 类型浏览

用户侧关注：

1. 插件是否已安装到 plugins 目录
2. 是否已启用
3. 依赖的 socket / 配置是否就绪（如 Friend Code 的 ~/.friend/run/friend-code.sock）

应用（Application）

• 适合：浏览器、键鼠控制、转换器等“打开才用”的能力
• 默认只看到控制类入口（列表/搜索/安装/打开/调用/关闭），不会把所有 App 内部工具塞进上下文
• 打开后实例工具名形如 AppID.Instance.ToolName
• 用完应关闭实例，释放进程与上下文

用户侧流程：

1. 发现应用（列表或语义搜索）
2. 打开实例
3. 调用具体工具
4. 关闭实例

技能（Skill）

• 适合：可复用的工作流说明（调查、规划、测试策略等）
• 激活后，完整指令进入当前链的上下文，指导怎么做
• 可按任务需要激活/停用；多个相关技能可一起开
• 目录常见于 ~/.friend/skills/

用户侧直觉：技能不是“多装一个二进制”，而是“告诉 Friend 用什么标准干活”。

在哪里找扩展

• 官网 仓库页：按 plugin / application / skill 筛选与搜索
• 本机目录：~/.friend/plugins、~/.friend/applications、~/.friend/skills
• 安装脚本也支持用环境变量覆盖这些根路径

选用建议

目录与数据

默认一切以 ~/.friend 为家；可用环境变量改路径。数据默认本地优先。

默认布局

~/.local/bin/friend                 # TUI 命令
~/.friend/
  bin/friendd                       # runtime
  plugins/friend-code/              # Friend Code 插件
  code/
    friendd.yaml                    # 默认独立配置
    client.json                     # 客户端元数据（含 auto_start 等）
    data/                           # SQLite 等业务数据
  run/                              # socket、pid 等运行时文件
  logs/                             # 日志
  skills/                           # 技能
  applications/                     # 应用

Friend Code 默认倾向使用独立的 ~/.friend/code/friendd.yaml 与独立数据库，减少和项目锁、可选 Redis/Milvus 的耦合。只有你显式设置 FRIEND_CONFIG 时，才刻意复用已有 runtime 配置与库。

可覆盖路径

会话与工作目录

• 会话列表会优先展示与当前工作目录相关的项
• 换目录不等于数据丢失；用 /resume 搜索即可
• 子代理挂在会话树下，元数据由插件侧与链 API 共同呈现

备份与安全

• 安装脚本覆盖前会备份已有文件
• 卸载默认保留数据目录；彻底删除需手动 rm -rf ~/.friend
• 密钥出现在供应商配置与本地配置文件中：保护好本机权限与备份副本
• 日志可能含任务上下文，分享前先检查

数据会上传到哪里？

• 默认本地：配置、会话、日志在本机
• LLM 供应商：你发起的模型请求内容按供应商条款处理
• Registry：安装/更新时下载组件；发布端需要 token，与普通用户安装分离

常见问题

先对症状，再改配置；大多数问题出在 PATH、供应商或工作目录会话排序。

安装后运行 friend 提示 command not found

export PATH="$HOME/.local/bin:$PATH"

写入 shell 配置后重新打开终端。若自定义了 FRIEND_CODE_BIN_DIR，把该目录加入 PATH。

打开后没法正常思考 / 一直提示模型相关错误

1. /provider 检查密钥、地址、协议
2. 同步模型目录
3. /model thinking 指定一个可用模型
4. 仍失败时看 ~/.friend/logs 与供应商侧错误信息

换了目录后找不到之前的会话

会话会优先按当前工作目录组织。用 /resume 搜索标题或关键词，通常仍可找回。

socket / 插件连不上

• 确认 Friend Code 插件已安装：~/.friend/plugins/friend-code/
• 确认运行目录与 socket：~/.friend/run/（常见 friend-code.sock）
• 重新打开 friend，让其按需拉起 friendd 与插件
• 不要混用错误的 FRIEND_HOME / FRIEND_CODE_SOCKET

我想完全卸掉

curl -fsSL https://friend.zhengcloud.ltd/install.sh | bash -s -- --uninstall

默认保留数据。彻底清理：

rm -rf ~/.friend

不可恢复，先确认。

可以指定 beta / nightly 吗？

FRIEND_CHANNEL=beta curl -fsSL https://friend.zhengcloud.ltd/install.sh | bash

数据会上传到哪里？

默认本地优先。LLM 请求内容由你配置的供应商处理。详见「目录与数据」。

安装支持哪些系统？

macOS / Linux，常见 amd64 与 arm64。不支持的平台脚本会报错退出。

如何只演练安装不写盘？

FRIEND_INSTALL_DRY_RUN=1 bash online/scripts/install.sh

或对远程脚本配合你自己的 dry-run 环境变量用法（以脚本帮助为准）。

如何换 Registry？

FRIEND_REGISTRY_URL=http://your-registry:8090 curl -fsSL "$FRIEND_REGISTRY_URL/install.sh" | bash

下一步

先稳定日常闭环，再按需扩展能力。

建议路径

1. 跑通最小闭环：安装 → provider → thinking 模型 → 项目内对话
2. 熟悉会话：/resume、/new、子代理切换
3. 按需加配置：compression / multimodal、/setting 里真正用得到的项
4. 按需加扩展：到 仓库 浏览 plugin / application / skill
5. 建立自己的习惯：固定工作目录、命名会话、重要项目保留备份

可以去哪里

反馈与更新

• 用 FRIEND_CHANNEL 选择 stable / beta / nightly
• 重新执行安装脚本可升级到渠道最新（注意备份与自定义配置）
• 遇到问题先看「常见问题」，再带日志与复现步骤反馈