# @adlc/core 中文文档

规范地址：https://npmcn.com/package/%40adlc/core/

版本：1\.13\.0
npm 元数据更新时间：2026-11-06T02:13:48.415Z
中文译文更新时间：2026-11-06T02:15:39.592Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40adlc/core
原文对照：https://npmcn.com/package/%40adlc/core/?lang=original
项目主页：https://github.com/voodootikigod/adlc/tree/main/packages/core#readme
源码仓库：https://github.com/voodootikigod/adlc

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

- 包体积（解压后）：242 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-06-13T21:12:02.507Z
- 最新版本发布：2026-11-06T02:13:47.962Z
- 近 30 天下载量：9357（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

ADLC工具的共享核心:LLM提供者,git助手,CLI常规,分类账,门票,突变.

## 安装

```sh
npm install @adlc/core
```

也可以使用：`pnpm add @adlc/core`、`yarn add @adlc/core`、`bun add @adlc/core`

## README

# @adlc/ 核心

所有 ADLC 工具共享库 。 从它导入工具, 永远不要保存 其出口品的私人副本。 当第二套需要帮助时, 推广 这里: 添加一个测试 `packages/core/test/`,在 `index.d.ts`, (中文(简体) ), 没有新的运行时间依赖。 原始核心的缺陷被固定在这里,与 a 回归测试。 完整的规则是公约S.md硬规则2.

导入表面( O)`@adlc/core` 及其子路径输出:

```js
import { complete, fan, fanProviders, extractJson, detectProvider, resolveModel, PROVIDER_NAMES } from '@adlc/core';
import { git, gitDiff, changedFiles, isDirty, isGitRepo, coChange, pairKey, churn } from '@adlc/core';
import { parseArgs, pass, gateFail, opError, printJson, readStdin, promptOnly } from '@adlc/core';
import { ADLC_DIR, appendEntry, readEntries, ledgerPath, sha256, hashFiles } from '@adlc/core';
import { TICKETS_PATH, loadTickets, validateTicket, topoSort, computeFloat, globMatch, inScope, scopesOverlap } from '@adlc/core';
import { mutate } from '@adlc/core'; // mutate.generateMutants / applyMutant / changedLinesFromDiff / OPERATORS
import { syntaxLanguage, resolveTypeScript, checkSyntaxDetail, checkSyntax, syntaxCheckProblem } from '@adlc/core';

// Subpath exports (`package.json` "exports"):
// @adlc/core/llm | @adlc/core/git | @adlc/core/cli | @adlc/core/ledger
// @adlc/core/revision | @adlc/core/tickets | @adlc/core/mutate | @adlc/core/test-kit
```

## 计数器

-   `detectProvider(env?, forceProvider?)` → `{ name, apiKey, models } | null`. 秩序:有人类性,有克来,有克来,有克来. 强制使用 `ADLC_PROVIDER` (env) 或(v) 或 `forceProvider` 参数(每援引一次,例如:CLI) `--provider` 旗帜——优先于 `ADLC_PROVIDER`) (中文(简体) ).
-   `PROVIDER_NAMES` → `['anthropic', 'openai', 'gemini', 'agy']`,用于CLI验证 `--provider`编号 :`--providers`。 。 。 .
-   `resolveModel(provider, { tier, model }, env?)` - 型号编号。 等级 : `cheap | mid | frontier`通过 `ADLC_MODEL_CHEAP/MID/FRONTIER`。 。 。 .
-   `complete({ tier, model, system, prompt, maxTokens, provider?, onUsage?, cacheable? }, env?)` → `Promise<string>`。在没有提供者的情况下投出(工具必须抓住和提供) `--prompt-only`) (中文(简体) ). `provider` 是一种每例调用重置,只有添加剂——省去,单位提供者自动检测仍然是默认(按ADR-0007计算成本/相关性). `onUsage?: (usage) => void` 是一个可选的侧道发射 `{ inputTokens, outputTokens, cachedTokens, provider, model, tier }` 当提供者报告使用时( Gemini) `outputTokens` 包括思维符号, `thoughtsTokenCount`正如Anthropic和OpenAI已经做的那样;Agy从来不做——没有什么可以报告的. `cacheable?: boolean` (默认) `false`)在支持明确缓存断点(目前只有人体性)的供应商上将系统/即时标记为即时缓存候选人——只有在SME时才设置 `{system, prompt}` 将再次发送; 缓存写入成本超过一个纯输入符, 并且只在稍后读取时才支付.
-   `fan(opts, n, env?)` → `Promise<[{ ok, value | error }]>` - 没有独立的无国籍状态完成(自动发现或 `opts.provider`\- 强制提供商. `opts.cacheable` 默认为 `true` 这里( 不同于 `complete()`) —— 扇子( ) 特别存在, 可以重新发送一次快取 N 次, 确切的形状是缓存写给自己支付的形状 。 过 `cacheable: false` 选择退出. `opts.onUsage`,如果给定,每个再生一次会起火.
-   `fanProviders(opts, providerNames, env?)` → `Promise<[{ ok, value | error, provider }]>` ——每个DISTINCT命名提供者完成一个(例如. `['anthropic', 'openai', 'gemini']`),而不是一个提供者的N复标. 指定提供者缺少其 API 密钥表面为 `{ ok: false }` 仅限该条目。 不默认 `cacheable` 改为 `true` ——每个提供者都得到一个完全的呼叫,所以没有重复分期摊还一个缓存写作对.
-   `extractJson(text)` 从杂乱的模型输出中解析出 JSON 值 。 没有就扔.

## gi

-   `git(args[], opts?)` → stdout 字符串(execFileSync;以非零为单位投掷).
-   `isGitRepo(cwd?)`, (中文(简体) ), `gitDiff(base?, cwd?)`, (中文(简体) ), `changedFiles(base?, cwd?)`, (中文(简体) ), `isDirty(cwd?)`。 。 。 .
-   `coChange(limit?, cwd?)` → `{ pairCounts: {'a b': n}, fileCounts }` (逻辑耦合; 执行触摸 > 50文件跳过). 通过对等键 `pairKey(a, b)` (相类也.
-   `churn(limit?, cwd?)` → `{ file: commitCount }`。 。 。 .

## 语气

-   `parseArgs(config)` - 节点: 使用 pargs `allowPositionals: true` 默认.
-   `pass(msg?)` 出口 0- `gateFail(msg, details?)` 出口 2- `opError(msg)` 1号出口.
-   `printJson(obj)`, (中文(简体) ), `readStdin()`, (中文(简体) ), `promptOnly(promptOrArray)` (出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出.

**出站代码为合同:0=出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站口出站台出站.**

## 分类账(长期 `.adlc/`(中文(简体) )

-   `appendEntry(name, entry, dir?)` • 附录 `.adlc/<name>.jsonl`。 。 。 .
-   `appendEntries(name, entriesOrFactory, dir?)` 将耐用批量装入其中 车主锁;工厂接收字节锁入的分类账尾,以进行安全序列 和大麻链分配.
-   `readEntries(name, dir?)` → `{ entries, skipped }` ——报告线路不整齐,从不吞咽.
-   `sha256(content)`, (中文(简体) ), `hashFiles(paths)` → `{ path: hash | null }`。 。 。 .

众所周知的分类账名称: `manifest` (门 - 明显条目), `findings` (起诉结果: `{ ts, tool, file, line, category, severity, desc, verdict }`) (中文(简体) ).

## 门票(卡通逻辑商店)

Schema(参见 lib/tickets.mjs 头条): `{ id, title, body, scope[], rails[], edges[{to, contract}], duration, category, budget }`。 。 。 .

-   `loadTickets(path?)` → `{ tickets, errors }` (阅读遗产 JSON 或兄弟 被硬化的商店并验证了id,重复的id,未知的边缘.
-   `validateTicket(t)` → `errors[]`。 。 。 .
-   `topoSort(tickets)` → `{ order, cycle | null }`边缘是指"边缘前完成.to".
-   `computeFloat(tickets)` → `{ floats: {id: n}, criticalPath: [ids], makespan }` (CPM; 期限默认 1) 或 `{ error }` 在自行车.
-   `globMatch(pattern, path)` (单位:千美元)`*`, (中文(简体) ), `**`, (中文(简体) ), `inScope(ticket, path)`, (中文(简体) ), `scopesOverlap(a, b)` (保守论.

## 变异( n)`@adlc/core/mutate`(中文(简体) )

-   `mutate.OPERATORS` —— 说 `invert-comparison`, (中文(简体) ), `bool-flip`, (中文(简体) ), `null-return`, (中文(简体) ), `off-by-one`, (中文(简体) ), `logic-swap`, (中文(简体) ), `negate-guard-subclause`, (中文(简体) ), `array-literal-shrink`, (中文(简体) ), `ternary-swap`。 。 。 .
-   `mutate.generateMutants(content, { targetLines?, maxMutants? })` → `[{ line, operator, original, mutated }]`。跳过纯批注/进口/主机行和未关闭的块评论打开器(`/* ...`),同时剥去一个主要封闭的块-分块前缀(`/* ... */ code`),因此在注释后仍可执行代码被变异(# 372). `off-by-one` 口罩不可观察的调谐常数(例如. `TIMEOUT_MS`, (中文(简体) ), `maxBufferBytes`,或负持续时间的哨点),同时仍在变换可计数边界(`MAX_RETRIES`, (中文(简体) ), `retryLimit`)和零报警器(`0 -> 1`) (中文(简体) ).
-   `mutate.applyMutant(content, mutant)` ^ 内容变异(如果行内容漂移会推出).
-   `mutate.changedLinesFromDiff(diffText)` → `{ file: Set<newSideLineNo> }`. Hunk 车身行只按其第一个字符分类,所以源行本身从 `--` 或者说 `++` 仍然是删除或添加.

## 语法

-   `syntaxLanguage(file)` 识别 JavaScript 和 TypeScript 家族.
-   `resolveTypeScript(filePath)` 向上走为最近的 `typescript` 与 javaScript 解析器 API,跳过本地 TypeScript 7 套件.
-   `checkSyntaxDetail(filePath, cwd, execPath?)` 返回时 `{ verdict, detail }`。 。 。 . 细节是 `null` 对语法判决的解释 `unknown` 结果.
-   `checkSyntax(filePath, cwd, execPath?)` 仅返回 `valid`, (中文(简体) ), `invalid`,或 `unknown`;检查器失败永远不会成为语法判断.
-   `syntaxCheckProblem(filePath)` 解释缺少的检查器并包含 `npm i -D typescript` 为 TypeScript- family 文件安装提示.

TypeScript 在测试中从寄存器中解析, 不依赖 `@adlc/core`。 。 。 .

## 文本(共享有效载荷绘图辅助工具)

-   `tail(str, maxChars = 4000)` 最后一个 `maxChars` 字符为 `str`,如果已经达到极限,则保持不变。 因此,每个快速有效载荷封顶的呼叫者共享一个实施.
-   `fence(label, content, maxChars, opts?)` - 包装 `content` 内 `<<UNTRUSTED:...>>`编号 :`<<END:...>>` 声明其惰性数据的标记,上限为 `maxChars` (单位:千美元)`maxChars` 需要,而不是可选;没有未封装的呼叫)。 截断默认保留尾部; 通过 `{ bias: 'head' }` 以保留开口( spec-形状的内容). `opts` 必须是普通对象,唯一的关键是 `bias`,以及 `bias` 必须是 `'head'` 或者说 `'tail'`; 任何其它抛出。 用于 `packages/fleet` 在建筑/出入口/起诉前用栅栏将日志填入固定的章程.

## diff- mask( 撤销行证书伪装)

-   `maskRemovedSecrets(diff)` → `diff` 其全权证书被掩盖 **删除** (单位:千美元)`-`) 仅行,对于diff,一个审查模型即将被读取. 一个删除一个秘密的改变 仍然带有它 `-` 线条; 添加和上下文线条位于HEAD并保持可见,这样审查者就可以给添加的更改标出一个秘密。 掩盖已知提供者塑造拒绝的发现分类账、认证任务(任何案例和标识样式)—— `password`, (中文(简体) ), `API_TOKEN`, (中文(简体) ), `clientSecret`, (中文(简体) ), `"apiKey"` - 引用与否,与 `=`, (中文(简体) ), `:`, (中文(简体) ), `:=` 或者说 `=>`), URL 用户info 密码, Basic auth, 高entropy sorders, 和私有密钥块(跟踪在文件的旧边上, 从BEGIN在上下文外的一行端回填). 函数文本在 a 后 `@@` 头部也蒙上面具,因为从文件复制. `---`编号 :`+++` 头从未被触动;行数被保留. 平地喂饱它 `git diff --no-color --no-ext-diff` 输出: 无法识别有色或有外向驱动程序 。 一个已删除的行 `MAX_MASKED_LINE` (2000年) 字符被蒙上整体,这也将正格克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 Best-effort:8个字符以下的值,有空格的未引出值,或没有类似证书名称的低通口令,没有被捕获.
-   `maskSecretText(text)` – 同一行文字的口罩.
-   `MASKED_SECRET` (单位:千美元)`[redacted]`, (中文(简体) ), `MASKED_PRIVATE_KEY` (单位:千美元)`[redacted private key]`, (中文(简体) ), `MASKED_LONG_LINE` (单位:千美元)`[redacted long line]`——占地者; `MAX_MASKED_LINE` ——每行长度上限.

## 试验基特 (`@adlc/core/test-kit`(中文(简体) )

修复辅助器 `node:test` 套房; 键入方式 `lib/test-kit.d.mts`。 。 。 .

-   `tmp(t, prefix?)` ~ 一个全新的 realpath'd 目录下方 `os.tmpdir()`页:1 注册的钩子 `t.after()` (重试瞬间) `ENOTEMPTY`编号 :`EBUSY`, (中文(简体) ), `FIXTURE_RM_OPTIONS`) (中文(简体) ). **关闭失败 :** (单位:千美元) `t` 无可调用 `.after` (无, `null`,前缀字符串,选项对象,或上下文描述级别 `before()` (收到) `TypeError` 并创造出什么.
-   `gitRepo(t, options?)` → `{ dir, git, g }`: 内部重播 `tmp(t)` 测试 身份证明, `commit.gpgsign=false`, (中文(简体) ), `gc.auto=0` 财务报告和审定财务报表 `gc.autoDetach=false` (无分离) 抚养子女写入 `.git` (删除期间). `options` 实值 `{ prefix, branch, userEmail, userName }` 或前缀字符串。 上下文规则与 `tmp`。 。 。 .
-   `createScope()` - 环境(`{ after, dispose }`用于超过一次试验的固定装置 回调: 在 `before()`, (中文(简体) ), `await scope.dispose()` 内 `after()`登记 处置的瞄准镜投出.
-   `withScopedContext(fn)` 运行 `fn(ctx)` 带一具新的瞄准镜,然后在 `fn` 结算;用于调用测试函数的代码 `node:test` 调用.
-   `runBin(binPath, args?, options?)` → `spawnSync` 一个节点脚本 `DEFAULT_SCRUBBED_ENV` 除非 `allowEnv` 给他们起名字.

## 常见问题

### @adlc/core 是什么？

ADLC工具的共享核心:LLM提供者,git助手,CLI常规,分类账,门票,突变\.

### 如何安装 @adlc/core？

在项目目录运行 npm install @adlc/core，或使用 pnpm add / yarn add / bun add。

### @adlc/core 支持 TypeScript 吗？

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

### @adlc/core 支持 ESM 还是 CommonJS？

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

### @adlc/core 需要什么版本的 Node\.js？

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

### @adlc/core 可以商用吗？

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

### @adlc/core 的下载量有多少？

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

### @adlc/core 还在维护吗？

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