# @felan-ai/ext-background-bash 中文文档

规范地址：https://npmcn.com/package/%40felan-ai/ext-background-bash/

版本：0\.15\.1
npm 元数据更新时间：2026-11-13T12:33:11.754Z
中文译文更新时间：2026-11-14T13:55:14.085Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40felan-ai/ext-background-bash
原文对照：https://npmcn.com/package/%40felan-ai/ext-background-bash/?lang=original
项目主页：https://github.com/felan-ai/felan#readme
源码仓库：https://github.com/felan-ai/felan

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：317 kB，64 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- peer 依赖：@felan-ai/agent-core ^0\.15\.0
- 首次发布：2026-08-06T03:31:57.385Z
- 最新版本发布：2026-11-13T12:33:11.348Z
- 近 30 天下载量：3017（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

Felan 的运行时便携式分离Bash程序

## 安装

```sh
npm install @felan-ai/ext-background-bash
```

也可以使用：`pnpm add @felan-ai/ext-background-bash`、`yarn add @felan-ai/ext-background-bash`、`bun add @felan-ai/ext-background-bash`

## README

# @felan-ai/ ext- background- bash (英语)

为Felan会议执行不偏重任何项目-地方Bash。 扩展 `bash` 带有明确的背景, 边框前排等待, 可选的 PTY 输入, 并添加到列表、读取、等待、写入和停止进程的工具. 背景任务输出和元数据位于下 `<session-storage>/background-bash/<workspace-key>/jobs`. 当地Felan地图 `<session-storage>` 改为 `$FELAN_AGENT_DIR/storage/sessions/<encoded-root-session-id>`当云 适配器将其映射到其根会话状态路径.

执行路由文件系统和通过活动处理操作 `AgentRuntime`。前景处决需要 `runtime.processes.startShell`。 。 。 . 脱落后背景发射采用POSIX外壳跑跑. 东道主, Docker 和 Daytona 运行时间需要 `nohup`, (中文(简体) ), `ps`, (中文(简体) ), `sleep`,则 `setsid` 或 shell 任务控制, 因此每个进程都收到一个孤立的进程组。 延期 捕获 `runtime.storage('session')` 一次;那个手柄必须是 持久和可见的同为文件系统命名空间 `runtime.shell`。 。 。 . 它要求明确 POSIX 外壳口味 探测和执行,然后 当运行时间不兼容时, 它的工具不活动 。 在本地窗口上, `HostAgentRuntime` 发现同一主机的 Git Bash 安装 `FELAN_POSIX_SHELL`, (中文(简体) ), `PATH`,或标准Git-for-Windows位置。 WSL 不为 因其路径和进程命名空间不匹配而自动选中 主机运行时间 。 Git Bash 的处理工具使用它 `ps -l` gNU 格式 `ps -o` 无法使用。 主机依赖配置可以禁用扩展名 当运行时间不兼容时; Felan 不安装操作系统 公用事业.

每个选定的模型都有同样的过程表面。 特定模式 政策属于模型化的即时/工具构成,而不是处理 所有权或运行时间能力检查.

此发布需要兼容 `@felan-ai/agent-core` 因为它使用 运行时间明确 POSIX 外壳口味和 `runtime.processes.startShell`。 。 。 .

## 工具和控制措施

-   `bash({ command })` 运行一个进程内的孩子通过 `runtime.processes.startShell` 不创建工作记录.
-   `bash({ command, timeout: 120 })` 等待最多为120秒,然后将同一个孩子提升为附加的背景工作而不重启.
-   `bash({ command, background: true })` 或者说 `bash({ command, timeout: 0 })` 启动一个带有持久工作记录的分离进程.
-   `bash({ command, timeout: 0, tty: true })` 立即启动交互 PTY 。 全体 `tty: true` 任务在启动前创建他们的记录, 这样守护进程就可以在其工作ID下注册 PTY .
-   `write_background_bash({ id, chars })` 向 PTY 任务发送精确的 stdin/ 控制字节 .
-   `list_background_bash` 返回 10 个最近的工作空间进程。 可选 `limit` (1-100), (中文(简体) ), `cursor`, (中文(简体) ), `status`,以及 `search` 选择更宽的页面。 跟着回来 `nextCursor` 时 `hasMore` 是真的,包括在一个已过滤的空页之后.
-   `read_background_bash` 读取跟踪进程输出,上限为日志内容的128 KiB。 使用 POSIX 的较大文件 `tail` 不装入整个日志.
-   `wait_background_bash` 等待终端状态而不返回日志输出.
-   `stop_background_bash` 发送 `SIGTERM` 或者说 `SIGKILL`。 。 。 .
-   `/processes` 通过 `pi.ui`。 。 。 .
-   费兰的TUI提供 `Ctrl+Shift+J` 和内置进程/日志视图.

原生的TUI进程/log视图使用内框. 使用其补全信息 紧凑的一行摘要; `Alt+A` 揭示有限度的细节.

非 PTY 前景输出返回上2000行 / 50 KB 。 仅以上产出 任意限制全写为 `<session-storage>/background-bash/<workspace-key>/output/output-*.log`编辑 扩展保存该工作空间输出目录中最新的20个外溢文件.

默认前景推广窗口为 120 秒, 可用 `extensionConfig.backgroundBash.foregroundTimeoutSeconds`. 促进 任务 `executionMode: 'attached'`,一个 `output.log`和完成信息. 它出现在 `list_background_bash` 财务报告和审定财务报表 `/processes`,但当会话结束 开始关闭或重新装入; 子代理晋级的工作结束 副探员。 取消转弯并不能阻止它。 已停止附加的工作记录 `killed` 而永不复入。 它们没有标准;使用 `tty: true` 页:1 交互式投入。 所附产出附于 `output.log` 因为它被读取.

一个前景命令在其外壳退出时完成. 一个背景后裔 开始于 `cmd &` 使输出管道打开,延迟结果 大部分500毫秒;持续运行且没有被跟踪.

守护进程跟踪活生生的孩子 `foreground` 进程前后 升职可以阻止孩子停产 本地 TUI 脚不包含 从其运行过程中启动前景进程,包括推动的命令 计数。 它计算运行脱机和PTY工作.

取消前景等待终止其进程树; 取消等待 已有依据的工作不会终止该项工作。 已调出的工作依然存在 当运行时间存储持续时重新启动后可发现 。 PTY 手柄为 root-session-scoped并无法在关闭后重新连接. Live PTY状态出自于其根会话柄,而非脱落-跑取的PID探测器. 在另一个呼叫者在前景中等待时,读取状态并保留输入. 终端结果和完成时间戳记录一次。 一个孤儿PTY 报告为 `unknown`;其所存储的PID不用于重接或信号一个进程. 返回的工作作为背景进程 `bash` 执行 自动完成消息 。 消息在下次运行时引导活动运行 模式调用边界,或者在代理闲置时触发转弯。 最终结果 直接返回由 `list_background_bash`, (中文(简体) ), `read_background_bash`, (中文(简体) ), `wait_background_bash`,或 `stop_background_bash` 压制重复 补全信息.

## 列出API和保留

`BackgroundBashManager.query(options)` 选项 `BackgroundProcessViewSource.query(options)` 返回 a `BackgroundBashPage`数字 :

```ts
const page = await source.query?.({ limit: 10 });
// { jobs, hasMore, nextCursor?, scanned }
const next = page?.nextCursor
  ? await source.query?.({ limit: 10, cursor: page.nextCursor })
  : undefined;
```

`BackgroundBashQuery` 接受 `limit` (违约10,最高100),独家 任务标识 `cursor`, (中文(简体) ), `status`,以及 `search` (大小写不敏感 ID/command 子字符串,位于 大部分256个字符). 查询/页面类型 从软件包根导出,并 `./data`。 。 。 . `source.list(status)` 财务报告和审定财务报表 `manager.list(status)` 保留他们的完整历史, 运行中的第一语义 现有呼叫者。 新的观点应当以 `query({ limit: 10 })` 并揭露 明确阐述更广泛的历史/研究.

查询列出了直接的职务名称,没有行走日志或 读取所有元数据。 ID 排序由 UTC 第二开头, 随机后缀为 在那一秒内,一个稳定的打结者。 每页最多100名候选人 记录并在达到要求的结果计数时停止。 光标音轨 最后一个扫描的ID, 而不是最后一个匹配, 因此零星的搜索可以返回空 (原始内容存档于2018-10-21). pages with more history left. 较新的插入不转出后页; 删除被跳过。 质询是活的,而不是快照的同化.

默认是最近的历史,而不是一个详尽的运行进程视图 。 使用 `query({ status: 'running' })` 并跟踪其光标找到旧的运行中的工作. 不需要持久的索引或背景全史扫描.

列表工具的完整序列化响应(文本和细节一起)是 上限为 64 KiB. 命令 和可选信号由JSON编码字节大小剪接,并明确 调车通知。 压缩 `details.jobs[].meta.id/command` 和状态记录 保存客户端命令链接兼容性; 完整路径, shell 参数, 符号,并省去重复的元数据。 完整命令保留在工作记录中.

保留仅在每32次成功创建/状态改变后运行,从未 最近一个查询。 1个序列式工作空间批次最多审议32个记录; 大型商店与随后的书写一致,而不是阻止上市. 超过最新1 000个或超过7天的经核实的终端工作 符合资格。 5分钟的完成宽限期保护最近的通知. 运行,未知,畸形,只留下遗产,不匹配,否则无法核实 保留记录。 匹配 `info.json` 财务报告和审定财务报表 `completion.json` 终端 需要设置状态/时间戳。 运行器完成时间切换到全部 秒是有效的,即使毫秒的起始时间是同一时间的后期 再来 任何被记录的PID和处理组必须正面缺席. 记录 带有一个PID,但没有保留可核查的组. 不确定过程探测器保留记录. 可选用途 `python3` 结束 `AgentRuntime.exec`,打开完整的目录链 `O_NOFOLLOW` 并仅将已知的平面任务文件与被绑定目录连接 解说. 它从不跟随共鸣 或逆向走出意外的条目. 缺少 Python/POSIX 描述支持,同名祖先(包括以上) ),以及意外文件均保守地禁用删除. 没有安装工具 。 所有检查和清除用途 `AgentRuntime`; 无 迁移或启动清理运行.

## 发展

资料来源: `packages/ext-background-bash` 内 [https://github.com/felan-ai/felan 页面存档备份,存于互联网档案馆](https://github.com/felan-ai/felan)。 。 。 .

```sh
corepack enable
pnpm install --frozen-lockfile
pnpm --filter @felan-ai/ext-background-bash build
pnpm --filter @felan-ai/ext-background-bash type-check
scripts/test-isolated.sh pnpm --filter @felan-ai/ext-background-bash test
```

## 归属

这个软件包适应了麻省理工学院的许可 `pi-background-bash` 执行。 见 [通知](https://npmcn.com/package/%40felan-ai/ext-background-bash/NOTICE) 财务报告和审定财务报表 [自由主义](https://npmcn.com/package/%40felan-ai/ext-background-bash/LICENSE) 来源详情.

## 组成和要求

```ts
import backgroundBashExtension from '@felan-ai/ext-background-bash';

const extension = backgroundBashExtension;
```

默认导出会将执行保存在活动运行时间, 并使用软件包所有 常规 `pi.ui` 用于演示的适配器。 它使用主机拥有 `runtime.terminals.attach(id)` 可用时处理,保存进程寿命 穿过客户隔离。 否则它拥有它开始的终端。 没有 需要提供特定扩展服务.

`createBackgroundBashExtension()` 暴露出相同的便携式成分。 土著 渲染属于 `apps/felan`;此套件不导出 TUI 切入点 .

通用适配器使用规范化 `./data` 记录,最多18份工作摘要 每页。 它出版 `view` 已宣布导航和读取动作,以及 a `document` 对于每个选定进程的输出。 日志保留已有的界限 尾部(可达2000行和128KiB行),被分出为被编码的字节块. 每个 通过明确的呼喊动作,可以实现块和所节省的工作。 命令预览 被标记为被剪接后,输出则被作为字面马克倒放而逃脱. 无自定义 需要显示器或隐藏的有效载荷; PID、处理符、路径和运行时间 控件不是控制输入或显示元数据.

输出文档只针对运行的进程宣布停止并杀死控制,以及 一个精确字节 stdin字段,只用于运行带有回调写入的 PTY 进程. 常规演示文稿源的可选 `write(id, chars)` 召回代表 到同一管理器 `write_background_bash`。控制重新检查当前任务 执行前的状态。 行动在列表和产出文件中序列化, 及其元素身份、修订、目标和输入在执行时再次验证. 停止、关闭、外国或畸形的行动不能援引程序控制.

发布后打开通用视图返回;命令不等待 用户输入。 关闭或取消视图会阻断新动作, 加入待读 和控制,并关闭它的把手 不停止任何进程。 关闭等待 在保持协调员所有权政策的同时进行清理。 清理失败 继续观察。 刷新是明确的;通用适配器安装不覆盖, 快捷键,或任何客户端的UI投票. 执行的完成交付是 不变.

主办方提供 `AgentRuntime` 和常见的 UI 绑定; 可选本地 TUI 拥有 本地捷径和身份投票。 受信任提供者自己的依赖政策, 不是客户端渲染器。 需要兼容的运行时间 pOSIX 外壳/加工设施 [运行时间依赖关系](https://npmcn.com/package/docs/reference/runtime-dependencies.md)费兰 不安装操作系统公用设施,该功能仍然不活动 当它们无法使用时.

该扩展拥有背景工作记录、日志、生命周期、PTY控制以及 6个模型化工艺控制器. 它不提供沙盒.

## 相关文件

-   [命令和快捷键](https://npmcn.com/package/docs/user-guide/commands-and-shortcuts.md)
-   [运行时间依赖关系](https://npmcn.com/package/docs/reference/runtime-dependencies.md)
-   [运行时间和安全](https://npmcn.com/package/docs/concepts/runtime-and-security.md)

## 常见问题

### @felan-ai/ext-background-bash 是什么？

Felan 的运行时便携式分离Bash程序

### 如何安装 @felan-ai/ext-background-bash？

在项目目录运行 npm install @felan-ai/ext-background-bash，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@felan-ai/agent-core（^0\.15\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @felan-ai/ext-background-bash 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @felan-ai/ext-background-bash 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @felan-ai/ext-background-bash 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @felan-ai/ext-background-bash 可以商用吗？

@felan-ai/ext-background-bash 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @felan-ai/ext-background-bash 的下载量有多少？

根据 npm 官方下载统计，@felan-ai/ext-background-bash 在 2026/10/15 – 2026/11/13 这 30 天内被下载 3,017 次，日均约 101 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @felan-ai/ext-background-bash 还在维护吗？

最新版本 0\.15\.1 发布于 2026/11/13（1 天前）；至今共发布 39 个版本，其中过去 12 个月发布了 39 个；首次发布于 2026/08/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。