# @agent-teams/engineering-foundation 中文文档

规范地址：https://npmcn.com/package/%40agent-teams/engineering-foundation/

版本：3\.1\.0
npm 元数据更新时间：2026-11-01T17:18:55.098Z
中文译文更新时间：2026-11-05T19:18:40.357Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：5.5 MB，2905 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.18\.0 \|\| ^26\.0\.0
- 运行依赖：12 个
- 首次发布：2026-08-01T13:59:24.181Z
- 最新版本发布：2026-11-01T17:18:54.783Z
- 近 30 天下载量：40437（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：72（近 12 个月 72 个）

## 中文简介

重新设计工程政策,为代理团队储存库提供工具和符合规定.

## 安装

```sh
npm install @agent-teams/engineering-foundation
```

也可以使用：`pnpm add @agent-teams/engineering-foundation`、`yarn add @agent-teams/engineering-foundation`、`bun add @agent-teams/engineering-foundation`

## README

# @ agent-teams/ 工程- 创建

团队代理仓库的工程基础.

该套件暴露出严格的YAML配置,定型政策检查, 共享编译器/接口预设,以及明确的本地与登记册寿命周期 用于工具。 这不是生产运行时间依赖.

这也暴露出一个封闭的 决定性的脚手架内核通过 `@agent-teams/engineering-foundation/scaffolding`消费者提供严格的 仅包含数据意图、构成、目标目录和所有者文档文件。 这个 目录将每个目标绑定在一个所有者文档ID上. 基金会决定 ID 从被绑定的文档根,记录导出路径,并独立 在规划、申请或恢复之前核实被允许拥有者的身份. 消费者不能提供模板、钩子、回调、命令或定义 插件 .

可重复使用的文档作者可直接从 `@agent-teams/document-authoring`. 其目录和计划 编译器只读;出版和回收单独明确 共同基金会交易屏障背后的操作。 目录 重建从一个明确的仅数据配置图,消费元数据中获取的稳定快照 计划,所有者地图,和Markdown收藏。 保留部分快照 诊断,而不隐藏有效的相邻文件。 文档作者是 不属于基金会的能力,从未作为 `check`。 。 。 .

```ts
import { buildDocumentationCatalog } from "@agent-teams/document-authoring";

const catalog = await buildDocumentationCatalog({
  consumerRoot: process.cwd(),
  profilePath: "document-authoring.yaml",
});
```

操作员和代理文件工作流程由 `@agent-teams/docs-protocol`新的和迁移的消费者暴露其命令 通过其存储列表:

```json
{
  "scripts": {
    "docs:info": "agent-teams-docs info",
    "docs:find": "agent-teams-docs find",
    "docs:new": "agent-teams-docs new",
    "docs:doctor": "agent-teams-docs doctor",
    "docs:recover": "agent-teams-docs recover",
    "docs:check": "agent-teams-docs check",
    "check": "agent-teams-foundation repo check"
  }
}
```

```bash
agent-teams-docs find "tenant isolation" --consumer /repo
agent-teams-docs new --type adr --id ADR-0083 \
  --title "Tenant isolation" --owner architecture/tooling \
  --summary "Defines the tenant-isolation boundary and its verification evidence." \
  --dry-run --consumer /repo
agent-teams-docs new --type adr --id ADR-0083 \
  --title "Tenant isolation" --owner architecture/tooling \
  --summary "Defines the tenant-isolation boundary and its verification evidence." \
  --apply --consumer /repo
agent-teams-docs check --consumer /repo
```

目前的工作流程和JSON合同都在 [文档作者协议](https://npmcn.com/package/docs/architecture/document-authoring-protocol.md#canonical-agent-and-operator-cli)。 。 。 .

消费者国际应管理两个政策大门:

```bash
agent-teams-foundation check
agent-teams-foundation assert-dev-only
agent-teams-foundation assert-registry
```

精确稳定Bun 1 消费者用活性文本支持登记检查 锁定并包含已安装的孤立身份; 这是合作选择 没有安装的锁镜或归档认证的证据。 当地 仅保留pnpm 11。 见 [本地模式](https://npmcn.com/package/docs/development/local-mode.md)。 。 。 .

本地附件只接受一个已建目标,其版本为本地模式协议, 出口、运行时间依赖性以及真正的CLI自我检查与其软件包一致 元数据.

```yaml
schemaVersion: 1
project:
  id: consumer-repository
capabilities:
  workspace.dependency-declarations:
    configPath: architecture/foundation/dependency-declarations.yaml
```

能力存在意味着启用。 源架构,文档,ADR, 合同演变、压制、公共API和存储器安全检查 以消费者拥有的政策和能力资格证据独立通过. 安装或升级此软件包从不自动启用 .

另有两个子路径暴露出结构中立的机制: `@agent-teams/engineering-foundation/ratchet` (只有缩写结果的基线) 和增长预算) `@agent-teams/engineering-foundation/source-graph` (文件、导入边、光谱和紧密相通的组件)。 这个 发现基线也有命令 `agent-teams-foundation baseline check|init|prune --config <file>`; 见 [调查结果基线](https://npmcn.com/package/docs/architecture/findings-baseline.md)。 。 。 .

源依赖性计划 v3 待合并验证和包件 资格。 明确 `rootPackage: true` 仅管辖已宣布的根属 源范围; 重叠的软件包选择者保留直接的孩子选择和 独有的源拥有权。 纯模块类型标记保留附加依赖性 权力,而其他巢穴 显示栅栏。 现有v1/v2消费者和 基金会的v2政策保持不变. 见 [来源依赖合同](https://npmcn.com/package/docs/architecture/executable-capabilities.md#architecturesource-dependencies) 范围和单独的消费者资格要求.

`quality.executable-specifications` 可选择验证消费者拥有的JSON 将计划、文件、生成的类型、所有权证据和 独立消费门脚本. 它从来不运行这些脚本或导入 消费状态模型.

仓库也可以声明 `repository.agent-workflow` 并揭露 `agent-teams-foundation agent-workflow changed`基金会然后发现 当前 Git delta 并引用消费者配置的 pnpm 脚本 。 这个本地人 飞行前是可携带的,不更换完整的CI门. `agent-teams-foundation agent-workflow instructions <repository-file>` 报告 适用的指令范围、优先级、阴影、字节预算以及 不印刷或注射教学内容的文摘.

仓库可独立声明 `quality.gate-runner` 运行 `agent-teams-foundation gate run <profile>`配置文件是经过验证的DAG,其中 已存在的根套件脚本,并带有限定的货币,可选的任务截止日期, 和明确 `needs` 对 `after` 语义. 配置无法提供 命令或插件,静态 `check` 从未执行脚本,安装或 升级从不激活配置文件。 见 [质量门跑道引用](https://npmcn.com/package/docs/reference/quality-gate-runner.md)。 。 。 .

根文件为 `foundation.config.yaml`启用 `agent-teams-foundation schema foundation-config/v1` 对于它的克南克计划 财务报告和审定财务报表 `agent-teams-foundation explain <rule-id>` 为规则指导.

技术预设由 `stack-toolchain`已安装 作为一种直接的发展依赖。 基金会不导出预设外观 . TypeScript 消费者可以扩展 `stack-toolchain/presets/typescript/node.json`. Oxlint JSON 配置扩展快速 `./node_modules/stack-toolchain/presets/oxlint/node.json` 或类型意识 `type-aware.json` 预设。 语义打字检查仍然是单独的"工具链"命令.

`agent-teams-foundation public-api-promote-release` 保留给 更衣器版本工作流程. 普通特性检查从未更新已发布的 API 基线。 出版消费者还必须强制执行发行权的基线 在所需的拉动请求CI中突变.

### 可收回的已知文件交易

这个 `@agent-teams/repository-mutation` 包导出已关闭 `agent-teams.repository-mutation.known-file/v1` 协议。 它可以创建缺失文件或 仅在正则文件的字节和模式匹配一个已接受的精确时,才替换此文件 预想。 一个共同的基金会屏障, 版本的日记, 重复CAS检查, 严格的目录耐久性、有条件的回滚和确切的重建回收 使一个序列式多文件更新可恢复而不声称不可能 交叉档案原子学. 未知的内容、别名、同义链接、硬链接、路径 相撞,且不支持的Windows耐用性会失效. 基金会保留 其本地模式录入和域错误映射,同时持有同一片叶子 租赁;旧的基金会变异外观没有保留.

每个接受的基金会命令 `--json` 或者说 `--format json` 返回一个 JSON重视成功与失败. 命令失败的使用 `foundation-command-error/v1`。 。 。 .

属性套件可能从套件中导入决定性种子并重放助手 保留时的根 `fast-check` 消费者的发展依赖.

脚手架命令使用不可改变的内容地址计划 :

```bash
agent-teams-foundation scaffold-plan intents/example.yaml --consumer /repo --json
agent-teams-foundation scaffold-apply plans/example.json --consumer /repo --json
agent-teams-foundation scaffold-recover --consumer /repo --json
```

程序调用器可以将突变与预期的消费者描述符结合 `recoverFilesystemScaffold(consumerRoot, { projectId, configPath, targetCatalogPath, compositionId })`。基金会描绘不可改变 v1 ,并需要 在读取权限之前与存储的日记达成精确的字符串协议或 持续恢复。 单一论点的API和CLI不变; `inspectFoundationTransactionAwareMode` 仍然是只读的咨询飞行前.

目前的内置构件是一种只测试的相容性固定. 产品 软件包和特性配方、结构化更新和Nx集成要求 获得独立能力资格之前.

## 可处理的脚手架坠机资格

开发者测试可以导入 `runScaffoldCrashQualification` 类型 `ScaffoldQualificationPhase`, (中文(简体) ), `ScaffoldQualificationPoint`,以及 `ScaffoldQualificationPhaseCallback` 从 `@agent-teams/engineering-foundation/scaffolding/qualification`。 。 。 . 这个只有测试的入站点使用现有的生产应用依赖性和 返回已有的 `ScaffoldReceipt` 现有 `ScaffoldPlan`。 。 。 . 入境点还明确再出口这些犬类和种类 以其公开签名作为参考。 这些声明类型与 (b) 没有采用平行计划或收款模式. 不要从生产运行时代码导入它 .

```ts
import { runScaffoldCrashQualification } from "@agent-teams/engineering-foundation/scaffolding/qualification";

// In a disposable fixture's writer child process, using a publicly planned Plan:
await runScaffoldCrashQualification(consumerRoot, plan, async (point) => {
  if (point.phase === "after-hard-link") process.exit(73);
});
```

需要回调, 必须是函数; 无效回调拒绝 与 `TypeError` 在申请之前。 每一个得到支持的活动都在等待它的存在 检查站并接收一个仅包含 `phase`。 。 。 . 支助的阶段是:

-   `after-journal-temporary-synced`
-   `after-journal-prepared`
-   `before-operation-authority-recheck`
-   `after-journal-operation-publishing`
-   `after-temporary-synced`
-   `after-hard-link`
-   `after-journal-operation-published`
-   `before-final-authority-recheck`
-   `after-final-verification`
-   `before-journal-quarantine`
-   `after-journal-unlinked`

用于操作和日记替换的事件可以重复; 此列表没有 承诺每个阶段普遍订购或一次活动。 私人临时写作, 不包括恢复范围,以及未知的未来事件。 回调返回值 不给任何授权。 在当前应用错误/清理之后丢出或拒绝 行为且不显示崩溃 。 普通收据证明没有崩溃 .

呼叫者拥有一次性固定和孩子流程。 运行已有的公开 `recoverFilesystemScaffold` 在73号出口后的新流程中,然后检查计划 字节,生产再应用"一能",并保存用户自主漂移. 第一期期刊临时剪接 孤儿基金会无法关闭 临时交易; 发布临时同步和硬链接削减可能要求 受限人工恢复. 最后的日记断接无法恢复 收讫. 资格并不保证在每次削减时都趋同.

回调是使用调用者的节点权限的可信测试代码,而不是沙盒 代码。 该功能不产卵,杀活,再试,恢复,或清理固定. 73号出口显示程序中断,而不是物理功耗耐久性; 现有文件系统和Windows目录同步限制仍然适用.

## 常见问题

### @agent-teams/engineering-foundation 是什么？

重新设计工程政策,为代理团队储存库提供工具和符合规定\.

### 如何安装 @agent-teams/engineering-foundation？

在项目目录运行 npm install @agent-teams/engineering-foundation，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agent-teams-node-test、agent-teams-foundation，可以用 npx agent-teams-node-test 直接运行。

### @agent-teams/engineering-foundation 支持 TypeScript 吗？

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

### @agent-teams/engineering-foundation 支持 ESM 还是 CommonJS？

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

### @agent-teams/engineering-foundation 需要什么版本的 Node\.js？

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

### @agent-teams/engineering-foundation 可以商用吗？

@agent-teams/engineering-foundation 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-teams/engineering-foundation 的下载量有多少？

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

### @agent-teams/engineering-foundation 还在维护吗？

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