@ chamvi/ 编码
Chamvi代理的编码工具.
读取、编写和编辑文件,搜索、运行 shell 命令并显示 diff,
在任何沙盒供应商的一次性工作空间运行.
目录
安装
npm install @chamvi/coding @chamvi/sandbox @chamvi/core ai --save
仅限无害环境管理,节点.js >=26.0.0。 。 。 . @chamvi/core, (中文(简体) ), @chamvi/sandbox 财务报告和审定财务报表 ai 是同伴的依赖关系。 添加沙盒提供者 : @chamvi/sandbox-docker 或者说 @chamvi/sandbox-k8s (或 @chamvi/sandbox-local 发展筹资.
使用量
import type { LanguageModel } from 'ai';
import { codingTools } from '@chamvi/coding';
import { ToolDeniedError, approve, defineModelAgent } from '@chamvi/core';
import type { IWorkspaceManager } from '@chamvi/sandbox';
export function createCodingAgent(model: LanguageModel, workspaces: IWorkspaceManager) {
return defineModelAgent({
name: 'triage',
model,
instructions: 'Check out the repository named in the payload, reproduce the reported bug ' +
'with a failing test and answer with what you found and the diff.',
// create_workspace and dispose_workspace, then the coding tools
tools: { ...workspaces.tools(), ...codingTools(workspaces) },
hooks: {
// every shell command waits for a human
async beforeToolExecution({ toolName, input }, ctx) {
if (toolName !== 'bash') {
return input;
}
const { command } = input as { command: string };
const decision = await approve(ctx, { title: 'Run a shell command?', body: command });
if (!decision.approved) {
throw new ToolDeniedError(`Command refused: ${decision.reason ?? 'denied'}`);
}
return input;
},
},
budget: { maxSteps: 40 },
});
}
workspaces 是来自 createWorkspaceManager({ provider }) (单位:千美元)@chamvi/sandbox,附着在引擎上 workspaces.attach(engine) 所以,运行的工作空间去 当它解决。 模特儿打电话来 create_workspace 首先,然后工作在其中。 将代理订阅到一个启动的频道( N)channels: [http.on()] 与 @chamvi/http) (中文(简体) ).
这些工具是你们没有写的普通工具,所以大门就住在经纪人家 beforeToolExecution 钩子:在每个工具呼叫前运行 approve() 这里暂停运行 waiting 直到有人回答(UI收件箱, POST /runs/:id/approve,或频道的核准信息 ctx.channels.findOneOrFail(name).approve(...)) (中文(简体) ). 运行在等待复制品的同时保持工作空间. 一次回答, 钩子再次运行 approve() 返回决定; 抛出 ToolDeniedError 作为工具错误回到模型中,运行继续.
工具
codingTools(workspaces, { outputLogMaxBytes?, repositoryInstructions? }) 返回简单的 AI SDK ToolSet。路径相对于工作空间根或起始于 /workspace/; 任何离开根的都是工具出错.
| 工具 | 投入 | 结果 |
|---|---|---|
read_file | { path, offset?, limit?, encoding?, workspace? } | { path, content, startLine, endLine, totalLines, truncated, instructions? }: 文本文件最多可达16个小米B,最多可有2000行和65 536个字符; { path, encoding: 'base64', content, bytes } 与 encoding: 'base64' (最多1个小米); { path, type: 'image', mediaType, bytes, artifactId } 用于png,jpeg,gif或webp可达5个MiB,作为跑出文物被存储,模型得到的是一个图像(步骤和检查站只保留id). 还读取了 bash |
write_file | { path, content, encoding?, workspace? } | { path, bytes }: 以 encoding: 'base64'),创建缺失目录 |
edit_file | { path, oldString, newString, replaceAll?, workspace? } | { path, replacements }数字 : oldString 必须完全匹配一次,除非 replaceAll. 呼吁 edit_file 财务报告和审定财务报表 write_file 在一个文件上逐一运行,所以一个步骤中的若干文件编辑都适用 |
multi_edit | { path, edits: [{ oldString, newString, replaceAll? }], workspace? } | { path, edits, replacements }: 文件内容的编辑顺序, 失败时不写 |
grep | { pattern, path?, ignoreCase?, includeIgnored?, limit?, workspace? } | { matches: [{ path, line, text }], truncated, engine }: 当图像有它时, 撕裂, 否则 git grep -E,则 grep -rE (一个) grep busyBox 的每个文件; 跟踪、 未跟踪和隐藏的文件, 带有 git- ignored 的文件 includeIgnored; 默认 100, 最多500个匹配, 线条切入500个字符 |
glob | { pattern, path?, includeIgnored?, limit?, workspace? } | { files, truncated }: 匹配 a 的文件 ** 样式,排序 |
list_files | { path?, includeIgnored?, limit?, workspace? } | { files, truncated }:跟踪和未跟踪的被忽略的 includeIgnored,排序; 默认为 1000,最多为 5000 |
bash | { command, cwd?, timeoutMs?, background?, workspace? } | { exitCode, stdout, stderr, stdoutTruncated, stderrTruncated, stdoutBytes, stderrBytes, stdoutLog, stderrLog, cwd, outputCapped, timedOut, durationMs }: a shell (bash when heres) 使其工作目录和导出变量在呼叫之间保持;整个输出在 ~/.chamvi/out/ (最多为 outputLogMaxBytes 每条流,64米B默认:通过它,呼叫被杀死, outputCapped: true),结果显示一个较长流的前8个KiB和后24个KiB;默认超时5分,最多30分. 与 background: true { job, status: 'running', outputLog } 一次 |
bash_output | { job, offset?, workspace? } | { job, status, exitCode?, output, offset, nextOffset, size, truncated, outputCapped }:一个字节相抵后的背景工作输出(最多32个KiB)及其状况(running, (中文(简体) ), exited, (中文(简体) ), killed, (中文(简体) ), lost); 产出通过的工作 outputLogMaxBytes 被杀死outputCapped: true(中文(简体) ) |
bash_kill | { job, workspace? } | { job, status, exitCode? }: 停止工作及其开始的每个进程 |
git_diff | { staged?, path?, workspace? } | { status, diff, truncated }数字 : git status --short 和统一索引 staged(中文(简体) ) |
git_diff, (中文(简体) ), list_files 财务报告和审定财务报表 grep (用 git grep ) 字面上读取路径,所以路径像 :!src 命名一个文件, 并且绝不是路径谱魔法 . bash 保持状态通过 EXIT 陷阱:设置自己的命令 EXIT 陷阱可以替换它,因此调用的工作目录和导出不被保存. 在拥有 git 证书的管理器上,编辑工具读取原始文件(IWorkspace.readFileRaw:它们与模型读取的已编辑的文本相匹配旧的String(redactedSpans,拒绝触及 [redacted] 横跨并放回所有未触动的符号字节作为字节,所以旧的String既不能探测一个符号,也不能写入 [redacted] 返回; 他们的错误从不回声文件文本 。 模型错误( 一个未知的文件, 一个 oldString 或模棱两可,一个坏路径)作为工具错误回来,它可以纠正;一个破碎的沙盒是一个 SandboxError 工具错误,从不失败运行.
仓库指令
普通 UTF-8 工作空间 read_file 结果包括: instructions?: RepositoryInstructions 从 @chamvi/sandbox 默认情况下,范围为文件的根和祖先。 图片、基数64和Home日志没有指令字段. codingTools(workspaces, { repositoryInstructions: false }) 从文本中省略它。 此选项独立于管理器默认操作 repositoryInstructions: 取消管理器的根集和显性工具不会禁用编码附件,而取消编码附件则会让管理器的交付被启用. 设定为 false 以禁用两种送货方式.
这个 沙盒收集器 读取根先 AGENTS.md,则 CLAUDE.md 每个目录和扩展独立 @relative/path 包括深度第一外侧回击/铁栅栏。 每个来源的记录 path, (中文(简体) ), sha256编辑 content,继承 scopes 财务报告和审定财务报表 includedBy· ; complete: false 并绑定 diagnostics 报告跳过指南。 源文件是完整或省略的(32个KiB,共128个KiB;沙盒 README中的其他边框). 解决可能影响任务的不完整指导。 每个读取器都收集当前工作树指导;较早的工具产出保留了随后在暂停和重新启动之间步骤和检查站交付的内容.
在新子树中直接编辑或 shell 命令前, 获取其引导 read_file 或经理的 read_repository_instructions({ paths: ['packages/api/src/new.ts'], workspace })。后者也用于一个尚不存在的文件。 存储文本和系统提示没有授予操作员授权、权限、证书、技能安装或出版权。 撰写/编辑工具和任意性 bash 不执行指令范围; bash 绕过文件工具只执行 。 发现者拒绝被观察到的共鸣 特殊文件, .git 尽了最大努力,走上了道路并逃脱;这不是没有种族限制的禁闭(92号) (中文(简体) ).
工作空间
每个工具都有一个选项 workspace 编号(从 create_workspace) (中文(简体) ). Oindicent,工具使用跑道唯一的工作空间;有多个,模型必须命名一个. 工作空间通过管理器解决 context.run.runId,因此运行永远无法到达另一个运行的工作空间:另一个运行的id是"找不到".
没有效果工具
write_file, (中文(简体) ), edit_file, (中文(简体) ), multi_edit 财务报告和审定财务报表 bash 变化状态,但故意不是效果工具。 一个工作空间在一个过程中生活并与之相伴而生,而一个效果记录则在商店中活下来:在崩溃后再做一个步骤会运行在一个新的工作空间上,其中记录的"应用"结果会跳过写作. 重新应用是安全的: write_file 是专一的, edit_file 已应用的“ 旧String 找不到” 失败,以及 bash 在一个一次性沙盒里运行。 工作空间以外的任何事物都会改变( 不推) .
警卫
bash 运行模型所写的,而模型遵循它所读到的内容(一个问题,一个README,一个测试输出):把它当作不可信代码. 使用 Docker 或 Kubernetes 提供者, 保留工作空间网络防火墙, 缩小 allowRepo 在经理,并设置 bash 核准后(a) beforeToolExecution 钩子呼叫 approve()时,如 使用量人类应该看到每个命令.
编码后端
ICodingBackend 是在工作空间用自己的工具循环(Claude Code, 或在嵌入代理中这些工具)解决编码任务的东西的合同 :
interface ICodingBackend {
code(task: CodingTask): Promise<CodingResult>;
}
// CodingTask: { workspace, task, budget?: { maxSteps?, maxTokens?, timeoutMs? }, signal? }
// CodingResult: { status: 'done' | 'stuck', summary, diff }
货包只运送合同;后端计划.
API 密码
| 导出 | 仁爱 | 目的 |
|---|---|---|
codingTools | 函数 | 工作空间管理器上的编码工具 |
READ_MAX_LINES, (中文(简体) ), READ_MAX_CHARS | 常数 | 2_000, (中文(简体) ), 65_536 |
SEARCH_MAX_RESULTS, (中文(简体) ), LIST_MAX_RESULTS | 常数 | 500, (中文(简体) ), 5_000 |
LINE_MAX_CHARS | 常数 | 500 |
OUTPUT_LOG_MAX_BYTES | 常数 | 64 * 1_048_576 (64 MiB),默认 outputLogMaxBytes 联 合 国 codingTools() |
类型 : CodingWorkspaces, (中文(简体) ), CodingToolsOptions, (中文(简体) ), ReadFileResult, (中文(简体) ), ReadFileBinaryResult, (中文(简体) ), ReadFileImageResult, (中文(简体) ), WriteFileResult, (中文(简体) ), EditFileResult, (中文(简体) ), MultiEditResult, (中文(简体) ), GrepEngine, (中文(简体) ), GrepMatch, (中文(简体) ), GrepResult, (中文(简体) ), GlobResult, (中文(简体) ), ListFilesResult, (中文(简体) ), BashResult, (中文(简体) ), BashJobResult, (中文(简体) ), BashJobStatus, (中文(简体) ), BashOutputResult, (中文(简体) ), BashKillResult, (中文(简体) ), GitDiffResult, (中文(简体) ), ICodingBackend, (中文(简体) ), CodingTask, (中文(简体) ), CodingResult, (中文(简体) ), CodingBudget。 。 。 .
许可证
原载 Apache 许可证 2.0。 。 。 .