@hachej/boring-execution

中文文档
0.5.1发布于 2026/11/17MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 2.4万

原生Pi工作环境类型和独立可堆肥的工作空间租赁.

中文使用文档
文档目录7 节
  1. 可处理的虚拟工作空间
  2. Python (opt- in, 只有节点)
  3. 可选本地 Git
  4. 借入远程壳
  5. 借用远程文件系统
  6. 在 SQLite 中保存的虚拟仓库
  7. AWS 代码解释环境

@hachej/ 无效执行

可选的工作环境使用 Pi 的公开 FileSystem, (中文(简体) ), Shell 财务报告和审定财务报表 ExecutionEnv 合同. /native 重新出口这些合同. /contracts 添加获取和租赁身份,不需要回收、外壳或Boring资源参考.

可处理的虚拟工作空间

/virtual 提供 createVirtualWorkspace。安装精确的可选对等点 [email protected] 与被宣布为本地同龄人。 种子绝对路径,获得具有绝对cwd的本土环境,或创建公共上游Bash实例.

import { createVirtualWorkspace } from '@hachej/boring-execution/virtual';
import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';

const workspace = createVirtualWorkspace({
  providerId: 'scratch',
  files: { '/repo/note.txt': 'hello\n' },
});
const lease = await workspace.acquire({
  operationId: 'open-scratch', input: { cwd: '/repo' },
}, BACKGROUND_CONTEXT);
console.log(await workspace.createBash({ cwd: '/repo' }).exec('cat note.txt'));
await lease.release(BACKGROUND_CONTEXT);
workspace.dispose();

一个上游 InMemoryFs 存储所有字节。 公共变异适配器一致地解决了本地访问,Bash和Git的别名. 租赁共享命名空间身份,并有独立的cwd和清理. 放弃租借只能关闭其本土外观. 拆除工作空间可以防止新的收购/Bash实例并关闭本土外观。 已经返回的原始文件系统与 Bash 手柄仍然是可信任的主机拥有的手柄; 处理不会撤销它们或终止它们的命令 .

本地读取/写出/附录,目录访问,同义链接和专属临时文件通过公共测试行使. 原生重命名、 截断和持久冲洗返回 not_supported。支持拒绝移动和递归目录副本。 这些拒绝在突变之前。 硬链接拒绝ENOTSUP. 虚拟巴什在存量之前拒绝硬链接参数 ln -f 可删除已存在的目的地;符号链接保留库存命令上下文。 同时期对路径的结构变化仍然不合格;这个可支配的适配器不是权威的出版提供者或POSIX文件系统资格.

本地 shell 运行 Pi 的 sock bash 工具, 并带有缓冲输出 : onOutput 当命令结束时(从不作为活流),一并收到stdout和stderr, 溢出阈值被接受,但文件没有溢出 timeout (秒) 中止命令并返回 timeout。使用公共巴什 exec 用于单独的缓冲断层/断层。 主机 Bash 选项选择上游限制和明确的网络/海关命令. 不添加本地可执行倒置或网络传输 。 主机召回是信任的代码.

错误以一个位置表示( Q)boundedMessage 内 src/bounded-error.ts,下面的 AWS 代码解释器环境也使用过: git 命令或一个 fs 支持向工具结果传递的只是它的信息,即使一个支持把它们放入信息中,堆放框线也会掉出,最多只能是 MAX_ERROR_CHARS (2 000个,从 /virtual)字符. 整个错误一直存在 cause 用于主机日志。 命令输出本身由Pi's bash工具(它的尾巴,50 KB或2000行)所限定.

Python (opt- in, 只有节点)

createVirtualWorkspace({ providerId, python: true }) 添加 python3 财务报告和审定财务报表 python 对工作空间的每个外壳(原生) exec'包括: just-bash的CPython 3.13被编译为WebAssembly,与标准库,读取并写出与外壳相同的文件. 它是默认关闭的,是打开它的唯一方法(贝壳选项不能). 限制:只有节点,所以它扔出一个清晰 TypeError 浏览器中或其工人; 运行时间( 大约 10 MB, 运入内部) just-bash)在第一次呼叫上加载(此处约一秒;后半秒调用);其内存不由 shell 的执行限制所包含,所以一个脚本可以长出主机进程;没有pip,包安装或网络. Python回溯是脚本本身的输出并经过不变.

可选本地 Git

/virtual-git 需求 [email protected] 财务报告和审定财务报表 @hachej/boring-files/git。 。 。 . createVirtualGitFs(workspace.filesystem) 提供它的公共承诺文件系统。 主机创建一个 createGitRepository({ fs, directory, author, authorize }),然后打电话 installVirtualGitCommand({ bash, repository })安装核实实际公众 bash.fs 身份证明 每个命令都需要选定的 root cwd 。 本地工具接收到相同的寄存器实例 .

命令支持本地 init矩阵 status单行道 add,仅限索引 rm --cached, (中文(简体) ), commit -m边框 log, (中文(简体) ), branch, (中文(简体) ), checkout,和二进制内容 JSON diff 或者说 diff --cached。其他参数表返回出口126. 文件指南 拥有授权,序列化和diff语义. 没有关于远程运输、持久回收或出版交易的索赔。 原始内容 .git 写入仍然受所选文件系统主机政策的约束.

运行 node fixtures/virtual-workspace.mjs 在为一个虚构的共享本地/Bash/Git实例而建之后. test/packages/execution.test.mjs 练习公共输出和实际本地工具任务. npm run test:virtual-consumer 在储存库外安装沥青球和准确的登记册依赖性关闭,检查申报并重复这些测试。 设定 npm_config_cache 以保存被封存的档案.

借入远程壳

/remote-shell 出口对齐 createRemoteShellHandler 财务报告和审定财务报表 createRemoteShellLease 通过本地 Pi 获取适配器 Shell此子路径只需要固定的本地同伴。 它不装入虚拟 Bash, Git, Boring 文件或代理执行 。 主机对每个POST进行认证,执行来源/CSRF政策,选择一个已经获得的工作空间,并提供其原生壳,上下文,确切身份,撤销信号和命令授权回调. 授权必须返回 true 在执行和最终披露前运行。 当访问或工作空间身份改变时中止撤销信号,包括在无声命令期间.

客户端使用预期的身份,一个固定的HTTP(S)端点和一个明确认证的获取功能. 运输必须尊重 redirect: 'error' 并且不得重试命令请求。 两端绑定提供者,例如:化身和所选视图. 服务器在效果前检查身份. 客户端在交付输出前会检查身份,验证所订购的受请求约束的帧,并需要完全一个终端结果,然后是EOF. 丢失或错误的确认返回本地 ExecutionError('unknown');客户端从不重放命令. 请求的标识符与框架相关,而不是持久的一能或回收记录.

命令字符串, cwd, 环境和原生出场/出场结果通过(protocol 第2版). 输出回调收到现场综合文本和呼叫者的背景. 皮丝 window 选项被传送到工人的原生贝壳,以及 skipped 计算其输出块在输出框架中被中继(已验证,从未发明), 处理器也应用了窗口本身(remote-shell-window.ts:它保持了保留的尾巴,冲出的速度不快于 minIntervalMs,并报告合并后减少的内容 skipped 计算,所以一个忽略了窗口(Pi's Node environment)的工人仍然只转移尾巴. 已经报到的窗口工人被合并,而不是重算。 无 window,每个块都交付。 只退出呼叫不请求输出帧 。 正分数超时值使用本地值 秒数,其额外限制由提供者负责。 主机明确限定超时和溢出支持;不支持请求的特性在执行前拒绝. 溢出路径仍留在远程工作空间,需要单独授权的文件能力来取回. 没有提供假文件系统 .

运输默认为每请求64个KiB,每帧1个MiB和4个已排队服务器帧. 输出过大或排队过满会打断观察,而不是报告截断成功. 这些边框不限制本地输出生产或获取/提供峰值内存 。 东道国本土执行限制仍然是必要的。 当地取消、召回失败或租赁解除要求远程取消和报告未经证实的终止;以前的影响可以保留。 每所出借的租地只拥有其活性运输工具,从不叫出共享供应商的清理.

运行 node fixtures/remote-shell.mjs 用于通过进程内请求/响应流化实现本地命令. npm run test:remote-shell-consumer 仅安装行刑沥青和被钉住的本地注册关闭,检查严格的申报,并在没有虚拟/Git/Boring UI/代理同行的情况下重复公开本地测试。 处理者读取请求机构通过 @hachej/boring-files/request-guard安装 @hachej/boring-files (一个可选的对等点)与这个子路径;消费者安装其存档. 这可以建立配对的获取协议和选定的本土行为. 部署套接字、供应商供应/再接配、持久命令接收/恢复、独立档案赠款、受保护建筑和流程树木终止仍然是单独的资格.

借用远程文件系统

/remote-files 出口 createRemoteFileSystemHandler 财务报告和审定财务报表 createRemoteFileSystemLease 过本地的 Pi FileSystem。安装精确的可选对等点 [email protected] 与被宣布的本地同伴。 本条目不需要外壳,虚拟 Bash, Git, Boring 文件, UI 或代理执行.

主机对每个 POST 进行认证,并选择一个已经获得的工作空间. 内容 bindFileSystem(cwd, context) 返回 a WorkspaceLease<FileSystem> 以请求的 cwd 覆盖命名空间 。 适配器在执行和披露前检查实际租赁身份,本地文件系统ID和cwd. 为同时相容的 cwd 值捆绑不同的外观 。 约束不得提供或默默地重建工作空间。 处理器在运行后或关闭其本土行读器后,会发布每次有约束的租赁. 它从未援引共享提供者清理.

authorize(call, cwd) 接受受歧视的当地方法/论据并必须返回文字 true。处理器检查每次操作前后的授权,并读取。 当授权或工作空间身份改变时,包括在阅读器闲置时,中止主机撤销信号. 认证、来源/CSRF政策、路径和并联限制、最后期限和供应商限制仍然是东道方的责任。 原生临时文件操作保留了提供者语义,可以将文件放出cwd外. 单凭Cwd检查就不是路径补助.

客户获取cwd和每次引用的论据. 原生路径,二进制,元数据,文本和突变结果通过经验证的请求约束信封. 原生错误保留他们的代码,消息和可选路径. 丢失、错误或发送后取消确认返回 FileError('unknown') 并且可以跟随先前的效果。 不存在自动重试、回滚或持久的分解。 请求ID只与响应相关. 权威出版资源使用其单独的有条件出版合同.

openTextLineReader 保留一个流派本地阅读器。 框架保存严格的 LF 分拆和每行 terminated 旗帜。 已取消 readLine 等待等待,等待它的待发框架可供下一次通话使用。 在成功打开后取消原有的打开上下文不会关闭读者. 同时读取拒绝。 明确关闭或租赁发行取消本地观察;服务器清理关闭读者后再放出其外观. 客户端关闭不会等待远程清理确认或证明远程终止.

皮丝 openBinaryReader 财务报告和审定财务报表 openDirReader 保持一个不能被无国籍者要求的手柄打开。 因此,客户端将每个阅读器调用成一个有要求的调用(binaryInfo, (中文(简体) ), readRange, (中文(简体) ), scanLines, (中文(简体) ), readDirPage)打开工人自己的本地阅读器,回答一个有界限的范围,行扫描或目录页面,并关闭. scanLines 在工人身上运行,所以在大文件中定位行不会移动文件; read 被拆分为符合响应限度的响应,超过工人限度的范围被拒绝。 客户端记录打开的文件 size 财务报告和审定财务报表 mtimeMs 并随每一次电话发出他们;工作人员在阅读之前和之后检查他们,然后作废 FileError('invalid') 文件更改时( Pi ) FileInfo 没有任何出处,所以不能区分一个大小相同、时间相同的替换。 Directory 页面继续由条目抵消到本地阅读器上, 并对照目录的 mtimeMs;在页面之间更改的目录失败,而不是跳过或重复条目。 本地打开错误( N)not_found, (中文(简体) ), is_directory, (中文(简体) ), not_directory, (中文(简体) ), invalid 页:1 noFollow 保持他们的代码。 这些电话经过 authorize 就像其他方法一样 只有没有位置读取的环境( 模拟虚拟文件系统) 使用 snapshotReaders 内 fs-readers.ts。 。 。 .

已知偏离了 Pi 的读者合同: 读者没有手柄, 因此在文件后重命名或替换 openBinaryReader 使以后的呼叫失败( e)not_found 或者说 invalid) 而不是读取原来打开的文件;路径一旦打开就解决为绝对路径,所以稍后 cwd 更改不影响打开的读取器;同时 next() 无法调用一个目录阅读器 invalid; 拒绝一个空的非干目录页面 (unknown而不是循环; 目录显示成本 O(抵销) 工人每页.

watch 一个流出的请求: 工人的本地人 watch 输入一个被绑定的队列( 一个完整的队列, 或者一个超过极限的框架, 成为 Pi 的队列) overflow),每项修改在披露前再次获得批准 mode 来自于本地的监视者。 一个终端 error 被保留到限定的事件队列之外(全队列崩溃事件) overflow,绝不是出错),而且一个超大小的出错有其文本的界限;结束的流没有 error 向听众报告更改 error 变化。 一个 error 更改结束流; 撤销、 丢失流或租赁释放 error 变化; close (或中止溪流)关闭了本地的监视器,之后不会交付任何变化 close 决定。 建立手表失败了 工人的本土错误, 所以没有本土观看的环境 报告自己的 not_supported。 。 。 .

默认为每个请求有1个米B,每个正常JSON响应有4个米B,每个流框有1个米B. 二进制值为cononical base64文本出行(protocol 第3版;更年长的同龄人被拒绝出行,因此将两端一起升级). 服务器后压队列最多在一个帧并按需要读取,可能在飞行中读取. 这些限制绑定了已接受的运输数据,而不是本地读者分配,JSON扩展,获取分配或提供者生产. 过多的数据拒绝报告短短的成功.

运行 node fixtures/remote-files.mjs 在构建和流出一个没有外壳能力的虚构本土文件之后. npm run test:remote-files-consumer 安装执行和文件 tarball( 此子路径读取天体通过 ) @hachej/boring-files/request-guard)和被钉住的注册依赖关系,检查严格的申报和行使实际的本地文件,本地工具任务和读者终身种族. 它被钉住 buffer fixture依赖将undici的赤色类型导入到被隔离的安装内部,此时临时目录有一个母工作空间. 获取的证据不符合部署的套接字、供应商生命周期、购置回收、受保护的建筑物或完整的曝光政策.

在 SQLite 中保存的虚拟仓库

createVirtualWorkspace({ providerId, fs }) 将文件保存在 Pi 中 FileSystem 而不是内存, 例如 SQLite 工作空间后端 openSqliteFileSystem 联 合 国 @hachej/boring-files/sqlite-filesystem: 外壳、同位素- 基特和本土环境, 然后在一行中工作, 一个工作空间提供者在同一行上 fs 阅读和写作(一个视图,没有副本)。 该后端只有普通文件和目录: ln 被拒绝, chmod 无更改(文件报告0644,目录0755)和 touch 设定修改时间.

@hachej/boring-execution/virtual-sqlite 是此文件系统的 git 存储器 : openVirtualRepository({ fs, root?, seed?, seedMessage?, author?, context, providerId? }) 返回时 { root, env, repository, close() }。 。 。 . fs sQLite 文件系统已关闭 openBrowserSqliteConnection (非公开,未公布) @hachej/boring-browser/sqlite; 提供自己的浏览器 SqliteConnection 否则)在浏览器标签中,或超过 openNodeConnection (单位:千美元)@hachej/boring-files/sqlite) 在节点. 它由上面的棋子组成,没有添加自己的文件或 shell API(BORING-PI-6):读取,列表,写入和运行命令通过 env,Pi的原产地 ExecutionEnv,其 exec 贝壳有 git 命令绑定到 repository (单位:千美元)@hachej/boring-files/git)在同一文件上(股票虚拟环境创建了没有它的外壳). 每一个写在SQLite的地块,随着它的发生;没有什么可以拯救的 close() 只释放工作空间。 何时 root 没有 .git 却被填满了 seed (与 root)和已执行;否则,档案和历史就是所储存的.

AWS 代码解释环境

@hachej/boring-execution/aws-code-interpreter 需要精确的可选对等点 @aws-sdk/[email protected]; 主机通过自己的 BedrockAgentCoreClient (区域,全权证书,复议). 它除了会话开始,命令工具,和 stop(),并创建无 AWS 资源。 使用它的秘方是 实例/主机/锯;决定载于 (原始内容存档于2012-10-12). Host-RECIPE-AWS.md。 。 。 .

createCodeInterpreterEnv({ client, codeInterpreterIdentifier, session, id, mount, cwd?, umask?, pollIntervalMs?, renew?, rotateMarginSeconds? }) 返回时 { env, owned, sessionId(), lost(), renew(), stop(context) }。 。 。 . env 是一个本地的 Pi ExecutionEnv 此主机和密码口译员会话都挂起的文件夹( EFS 访问点) 上 : mount.path 即会议所视之地(/mnt/<name>, (中文(简体) ), mount.root 在那里这个主机。 工具路径是会话路径,因此命令和文件工具名称相同.

  • 图标 运行通过 startCommandExecution,则 getTask 每个 pollIntervalMs (默认为500ms)直到终端状态. Cwd, 环境(env,或 env -i 页:1 inheritEnv: false和 umask (默认) 002)是命令的前缀,命令在 bash -c。 。 。 . onOutput 每次民意测验后,将获得stdout的新部分,然后是stderr的新部分;溢出阈值被接受,没有溢出. timeout (秒)和中止的上下文调用 stopTask 返回时 timeout编号 :aborted,终止未经证实。 A 类 failed 有退出代码的状态是正常结果.
  • 文件 运行在这个主机的挂载 通过皮's NodeExecutionEnv:没有字节交叉 API. 外面的一条道 mount.path,或者其解析度(包含符号链接,并用手接住)的叶子 mount.root返回 FileError('permission_denied'); 不遵循最终链接的操作( )fileInfo, (中文(简体) ), exists, (中文(简体) ), remove, (中文(简体) ), renameFile)检查其目录。 结果和出错中的路径是会话路径. createTempDir编号 :createTempFile 返回时 not_supported (这里的临时文件对会话是看不见的). 检查与使用是单独的步骤:不捕捉由并发命令改变的链接.
  • 会议数字 : { sessionId } 借用正在运行的会话 stop() 无尽; { start: { name?, sessionTimeoutSeconds?, filesystemConfigurations? } } 在第一个命令上启动一个 stop() 结束一次. env.cleanup() 从不停止一个会话。 当服务处报告届会结束时(ResourceNotFoundException),运行和以后每次命令返回 shell_unavailable 财务报告和审定财务报表 lost() 真实; 文件保留. renew: 'auto' (默认启动会话; 借用的会话总是手动的) 在丢失后在 NEXT 命令上启动新会话: 失败的命令仍然返回 shell_unavailable 并且永远不会被重播,因为它可能有副作用。 在命令之前,会话比 sessionTimeoutSeconds - rotateMarginSeconds (default 60 s,最多活到一半时间)被替换为NEW指令. 旋转从不停止旧会话: 命令保留在它开始的会话上( 一个 unknown 运输失败后的结果仍然未知;没有任何东西杀死或重放它)和旧会话一直持续到它自己的 sessionTimeoutSeconds,所以那些关心闲会的主机设置了一个更短的超时. 启动是单飞行( 旋转时到达的命令共享一个新会话); 失败的启动会让命令停留在当前会话上并退后 . stop() 停止当前会话, 而每场会话都开始, 尚未确认已停止, 并等待它们; 失败的会话会被跟踪、 拒绝, 并被下一会重审 stop()。 。 。 . renew: 'manual' 保留先前的行为: renew() (只开始会话)让下一个命令开始一个新的会话. 损失是 ResourceNotFoundException 加导出中的名称和信件模式 SESSION_ENDED_ERRORS (例如,a ValidationException 大约终止会话 : 这些额外的形状会根据真实服务进行验证(所有人, 2026- 10- 12;见 (原始内容存档于2012-10-12). Host-RECIPE-AWS.md),以及 AccessDeniedException 永远不会失去。 服务和文件出错映射到 ExecutionError编号 :FileError 带有相同内容的信件 boundedMessage (无堆栈框架,最多 MAX_ERROR_CHARS) (中文(简体) ).

efsUserLayout({ userId, uid, gid?, runtimeMountPath?, runtimeAccessPointRoot?, interpreterMountPath? }) 纯度: 对于一个用户 id ([a-z0-9][a-z0-9_-]{0,63},从没有路径)和主机分配的 uid 它返回访问点创建( root) /boring/users/<id>, POSIX 用户 uid:1000设置 2770页:1 boring:user 标记),会话挂载(/mnt/workspace),此主机文件夹(/mnt/efs/users/<id>),其外的国家目录(/mnt/efs/state/<id>,与 journal.sqlite 财务报告和审定财务报表 harnessFile(key)),命名空间 id 和 filesystemConfigurations 输入.

test/packages/execution.test.mjs 驱动真实的 SDK 客户端 examples/hosts/aws/fake-code-interpreter.mjs (线条格式,没有AWS):共享文件,输出,出站代码,cwd和环境,超时并中止通过 stopTask,丢失会话(自动更新中转并在同步命令下,在不停止旧会话之前旋转,停止一次并被重试的会话,手动模式,借出会话),借出对自有会话,以及两个从未相见文件夹的用户(..、绝对路径、链接和由命令制作的连接)。 全部署行程未与AWS相对抗(会话分期错误形状对照真实服务进行校验,主人公为2026-10-12);参见HOST-RECIPE-AWS.md中的开口问题.

版本与发布记录

@hachej/boring-execution 共发布 98 个版本,首次发布于 2026/10/12;过去 12 个月发布了 98 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.5.1latest2026/11/17今天
0.5.0next2026/11/133 天前
0.4.852026/11/125 天前
0.4.842026/11/125 天前
0.4.832026/11/125 天前
0.4.822026/11/116 天前

关于 @hachej/boring-execution 的常见问题

@hachej/boring-execution 是什么?

原生Pi工作环境类型和独立可堆肥的工作空间租赁.

如何安装 @hachej/boring-execution?

在项目目录运行 npm install @hachej/boring-execution,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@earendil-works/chord(~1.5.2)、@earendil-works/pi-durable(~1.5.2)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hachej/boring-execution 支持 TypeScript 吗?

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

@hachej/boring-execution 支持 ESM 还是 CommonJS?

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

@hachej/boring-execution 需要什么版本的 Node.js?

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

@hachej/boring-execution 可以商用吗?

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

@hachej/boring-execution 的下载量有多少?

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

@hachej/boring-execution 还在维护吗?

最新版本 0.5.1 发布于 2026/11/17(今天);至今共发布 98 个版本,其中过去 12 个月发布了 98 个;首次发布于 2026/10/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。