# @chamvi/coding 中文文档 规范地址：https://npmcn.com/package/%40chamvi/coding/ 版本：0\.8\.0 npm 元数据更新时间：2026-11-08T20:16:50.658Z 中文译文更新时间：2026-11-09T10:24:35.381Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40chamvi/coding 原文对照：https://npmcn.com/package/%40chamvi/coding/?lang=original 项目主页：https://chamvi.dev/ 源码仓库：https://github.com/chamvi/chamvi ## 关键信息（来自 npm 元数据） - 包体积（解压后）：224 kB，7 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=26\.0\.0 - 运行依赖：1 个 - peer 依赖：ai ^7，@chamvi/core ^0\.8\.0，@chamvi/sandbox ^0\.8\.0 - 首次发布：2026-10-25T08:42:00.861Z - 最新版本发布：2026-11-08T20:16:50.334Z - 近 30 天下载量：2981（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：15（近 12 个月 15 个） ## 中文简介 Chamvi代理的编码工具(读取,编辑,搜索, shell,diff在一个工作空间)和编码后端合同. ## 安装 ```sh npm install @chamvi/coding ``` 也可以使用：`pnpm add @chamvi/coding`、`yarn add @chamvi/coding`、`bun add @chamvi/coding` ## README ![@chamvi/coding](https://raw.githubusercontent.com/chamvi/chamvi/master/.github/assets/logo.svg) # @ chamvi/ 编码 **Chamvi代理的编码工具.** 读取、编写和编辑文件,搜索、运行 shell 命令并显示 diff, 在任何沙盒供应商的一次性工作空间运行. [![npm version](https://img.shields.io/npm/v/@chamvi/coding)](https://www.npmjs.com/package/@chamvi/coding) [![CI](https://github.com/chamvi/chamvi/actions/workflows/ci.yml/badge.svg)](https://github.com/chamvi/chamvi/actions/workflows/ci.yml) [![License](https://img.shields.io/npm/l/@chamvi/coding)](https://github.com/chamvi/chamvi/blob/master/packages/coding/LICENSE) * * * **目录** - [安装](https://npmcn.com/package/%40chamvi/coding/#readme-installation) - [使用量](https://npmcn.com/package/%40chamvi/coding/#readme-usage) - [工具](https://npmcn.com/package/%40chamvi/coding/#readme-tools) - [仓库指令](https://npmcn.com/package/%40chamvi/coding/#readme-repository-instructions) - [工作空间](https://npmcn.com/package/%40chamvi/coding/#readme-workspaces) - [没有效果工具](https://npmcn.com/package/%40chamvi/coding/#readme-not-effect-tools) - [警卫](https://npmcn.com/package/%40chamvi/coding/#readme-security) - [编码后端](https://npmcn.com/package/%40chamvi/coding/#readme-coding-backends) - [API 密码](https://npmcn.com/package/%40chamvi/coding/#readme-api) - [许可证](https://npmcn.com/package/%40chamvi/coding/#readme-license) ## 安装 ```bash 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` 发展筹资. ## 使用量 ```typescript 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` 以禁用两种送货方式. 这个 [沙盒收集器](https://npmcn.com/package/%40chamvi/sandbox#repository-instructions) 读取根先 `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号](https://github.com/chamvi/chamvi/issues/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()`时,如 [使用量](https://npmcn.com/package/%40chamvi/coding/#readme-usage)人类应该看到每个命令. ## 编码后端 `ICodingBackend` 是在工作空间用自己的工具循环(Claude Code, 或在嵌入代理中这些工具)解决编码任务的东西的合同 : ```ts interface ICodingBackend { code(task: CodingTask): Promise; } // 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](https://npmcn.com/package/%40chamvi/coding/LICENSE)。 。 。 . ## 常见问题 ### @chamvi/coding 是什么？ Chamvi代理的编码工具\(读取,编辑,搜索, shell,diff在一个工作空间\)和编码后端合同\. ### 如何安装 @chamvi/coding？ 在项目目录运行 npm install @chamvi/coding，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ai（^7）、@chamvi/core（^0\.8\.0）、@chamvi/sandbox（^0\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @chamvi/coding 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @chamvi/coding 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @chamvi/coding 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @chamvi/coding 可以商用吗？ @chamvi/coding 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @chamvi/coding 的下载量有多少？ 根据 npm 官方下载统计，@chamvi/coding 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,981 次，日均约 99 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @chamvi/coding 还在维护吗？ 最新版本 0\.8\.0 发布于 2026/11/09（今天）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/10/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。