# @agenticprimitives/devkit 中文文档

规范地址：https://npmcn.com/package/%40agenticprimitives/devkit/

版本：0\.0\.0-alpha\.34
npm 元数据更新时间：2026-10-26T11:48:44.959Z
中文译文更新时间：2026-11-06T03:36:01.155Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agenticprimitives/devkit
原文对照：https://npmcn.com/package/%40agenticprimitives/devkit/?lang=original
项目主页：https://agenticprimitives.dev/
源码仓库：https://github.com/agentictrustlabs/agenticprimitives

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

- 包体积（解压后）：406 kB，126 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@agenticprimitives/a2a ^0\.0\.0-alpha\.48，@agenticprimitives/harness ^0\.0\.0-alpha\.30，@agenticprimitives/evaluation ^0\.0\.0-alpha\.11，@agenticprimitives/orchestration ^0\.0\.0-alpha\.27，@agenticprimitives/provenance-node ^0\.0\.0-alpha\.25
- 首次发布：2026-09-11T20:46:38.634Z
- 最新版本发布：2026-10-26T11:48:41.203Z
- 近 30 天下载量：5477（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

开发者 Kit 核心( 第 398 §10 / 第 399 §3 ) : `ap doctor` 将理论门作为数据 + 纯规则运行在任何树上, `ap doctor --rules` (c) 通过文摘将一个固定规则来源输入AGENTS.md/CLAUDE.md/.cursor/规则, `ap upgrade` 重写 e

## 安装

```sh
npm install @agenticprimitives/devkit
```

也可以使用：`pnpm add @agenticprimitives/devkit`、`yarn add @agenticprimitives/devkit`、`bun add @agenticprimitives/devkit`

## README

# @ agenticprimitives/ devkit (英语)

> 部分 **[代理先导](https://agenticprimitives.dev/)** ——代理应用程序的开源信任底板:可以签名的身份,行为时间检查权限,所有者携带的证据. [开发者工具包](https://github.com/agentictrustlabs/agentic-primitives) • 妇女 [所有软件包](https://agenticprimitives.dev/developers)

开发者 Kit 核心 —— `ap`,CLI即是包裹自己的前门(Spec 398 §10,Spec 399 §3,ADR-0063).

```
npx ap doctor                          # every rule, this tree, the config it found
npx ap doctor --rule no-private-keys   # one rule; --json for a coding agent
npx ap doctor --rules --write          # project the rules source; pin digests in agentic.lock.json
npx ap upgrade --canary                # newest canary of every @agenticprimitives/* pin, one exact set
npx ap upgrade --pin 1.0.0-alpha.24    # or one named version / dist-tag
npx ap conform a2a https://…           # A2A 1.0 conformance (dispatches to @agenticprimitives/a2a)
npx ap test --live-gates live-gates.json
npx ap create my-product --template product-repo --pin 1.0.0-alpha.24
```

## 医生规则

每个规则都是一个文件 `src/rules/`,数据加上一个纯判断,参数化为配置部分。 这个 ids是第399章第2.3节给出的 根检:

| 规则 | 双( 根检查) | 强制执行 |
| --- | --- | --- |
| `web-no-direct-mcp` | `check:no-direct-mcp-in-web` | CDR-0044 — 浏览器代码只通过 `/a2a/*` |
| `no-private-keys` | `check:no-app-private-keys` | 应用程序源中没有原始关键材料; 允许列表及理由 |
| `no-hmac-home-bridge` | `check:no-hmac-home-bridge` | 341 spec 341 retchet——桥倒倒了 |
| `no-cross-subject-vault-reads` | `check:no-cross-subject-vault-reads` | spec 366 R3 — 只读于本主题 |
| `fail-open-knobs` | `check:fail-open-knobs` | ADR-0045——每个允许的把手按名称列出 |
| `internal-marker-split` | `check:internal-marker-split` | spec 341 第7节——标出监护秘密 |
| `custodian-coverage` | `check:custodian-coverage` | 第294/295段——提供者中立保管人 |
| `archetype-catalog` | `check:archetype-catalog` | spec 354 第3节——在已记录摘要中验证目录 |
| `capability-vocabulary` | `check:capability-vocabulary` | ADR-0051 — 能力/ 协议特性/ 游戏本 |
| `demo-person-org-distinct` | `check:demo-person-org-distinct` | ADR-0046 — 个人 SA → org SA |
| `rules-drift` | —— 说 | 399 第3.4节——通过文摘对定点源进行预测 |
| `lock-coherent` | —— 说 | 399 第3.1节——准确、连贯 `@agenticprimitives/*` 针头 |

配置解析是一个机制: `ap.config.json#doctor`,则 `agentic.lock.json#doctor`,否则内置 代理初始器单列波的参考布局。 产品Repo 从它自己的部分 `create-app`。 。 。 .

退出代码 : `0` - 干净 `1` 调查结果 · `2` 使用或配置 `3` 规则或发送错误。 错误代码为 稳定字符串( e)`E_CONFIG`, (中文(简体) ), `E_RULE_UNKNOWN`, (中文(简体) ), `E_MODULE_ABSENT`因此,一个代理分支 在代码.

## 规则预测

`ap doctor --rules` 一个规则来源 `.cursor/rules/*.mdc` (从 `rules/sidecar.json`, (中文(简体) ), 和输入 `<!-- ap:rules -->…<!-- /ap:rules -->` 块 `AGENTS.md` 财务报告和审定财务报表 `CLAUDE.md`。 。 。 . 一个没有块的文件被单独留下. 文摘载于 `agentic.lock.json#rules`· ; `rules-drift` 失败 投影或一针不再匹配源。 在这个单曲中,来源是 `docs/architecture/agent-rules`· ; 消费者使用包裹中的拷贝.

## `agentic.lock.json`

```json
{ "lockVersion": 1, "packages": { "@agenticprimitives/a2a": "1.0.0-alpha.24" }, "rules": { "skill-terminology": "sha256:…" }, "devkit": "…", "template": { "name": "product-repo", "revision": "…" }, "doctor": { … } }
```

`packages` 是整齐的组合 `ap upgrade` 维护; `rules` 源摘要; `doctor` 产品规则 配置(每节都取代参考部分整体).

## 固定的定义—— `ap upgrade` (398 第10.3节)

`ap upgrade --pin-definitions <registry> agentic-trust/org-steward,agentic-trust/person-steward` 记录,在 `agentic.lock.json#definitions`,每个类型定义的文摘和 **权威形状** 每个工具(风险, 行动、要求类型、资源和权力依据、批准政策、效果、一能。 以后的每一个月 `ap upgrade` 首先阅读登记处:修改措辞是版本起伏;修改其中任何一个字段,就停止升级 每个工具命名的更改( e)`treasury.payment.execute: authorityArg payer → org`),以及 `--accept-definitions` 重开一次 评论员看过了 指针是评论员的记忆,从来不是核查员的输入.

## 开发者 MCP (`ap mcp`(中文(简体) )

编码代理主产卵 `ap mcp` (stio JSON -RPC) 并得到一个 **只读** 服务器 : `packages_list`, (中文(简体) ), `package_exports` (每个条目的名称) `.d.ts` 声明, `ontology_term` (T-box IRI,标签,评论——什么是名词) 和它不是什麽, `contract_deployments` (每个链的地址), `recipes` (代理规则和每项规则) 软件包的光谱, `doctor` (同一报告已编辑) 一切从安装在旁边的包裹中解答. 这是 **第三届** MCP——不是运行时间背后的私人MCP(ADR-0057),也不是Home MCP(Spec 397)—— 联 合 国 `ap://developer-mcp/doctrine` 资源首先如此:没有签名密钥,没有金库,没有权威,没有生产 效果(Spec 398 第10.4节,T23)。 克劳德代码 : `claude mcp add ap-dev -- npx ap mcp --root .`

## `ap generate client|cli|parity` 一份合同的第四和第五表面(398§7.2)

```
ap generate client --registry https://<skills-registry> --definition agentic-trust/person-steward --only web.search,person.memory.remember --out src/lib/agent-client.ts
ap generate cli    --registry … --definition agentic-trust/org-steward --only treasury.payment.execute
ap generate parity --registry … --definition agentic-trust/org-steward --json
```

根据汇编的定义(登记册,或 `--file <definition.json>`作者: `@agenticprimitives/harness`是因为 纯 `generateCapabilityClient` 编号 : `cliArgumentSchema` 编号 : `generateParityCases` - 给消费者的风筝 安装( 缺席 ) `E_MODULE_ABSENT`) (中文(简体) ). 客户端的每个操作都给应用程序贴上意图 `/harness/run` 边界 通过注入的端口,没有权限;对等的个案是正对(屏幕意图对询问) − 相同的普通计划摘要)和负对(伪造) `surface`,在批准后变更政党. 于 `ap upgrade` 移动被绑定的定义.

## `ap eval` - 作为家庭现场数据的案件(398 §10/P1.3)

```
ap eval evals/faithnet.eval.json --home https://www.faithnet.me --persona alice --report live-gates-reports/eval-faithnet-latest.json
ap eval --from-runs --home https://www.faithnet.me --persona alice --out evals/from-runs.eval.json
```

一个案子是 `{ id, incident, persona | (the --session bearer), addressee?, message, plan?, truth?, checks[] }`; 检查是 以姓名命名的确定法官之一(`answered`, (中文(简体) ), `replyKindIs`, (中文(简体) ), `neverClaims`, (中文(简体) ), `claimsRequire`, (中文(简体) ), `falseEmptiness`, (中文(简体) ), `emptinessCarriesReason`, (中文(简体) ), `evidenceFromTool`, (中文(简体) ), `evidenceCountAgrees`, (中文(简体) ), `noPlaceholderLeaks`, (中文(简体) ), `textIncludes`, (中文(简体) ), `textExcludes`, (中文(简体) ), `evidenceNoneFrom`) (中文(简体) ). 一件案子的正确结果是 `authority_required` 双胞胎作为测试; 爱华从不示意 一个无法解决的案件是FAILING案件. `--from-runs` 将特工的现场记录变成案件 要编辑的骨架。 在任何失败的情况下退出 1 .

## 它不会做的

握有钥匙,读出金库,薄荷权威,援引出产效果. 医生的发现是一个审查检查站; 没有核查者读取(第361节).

## 常见问题

### @agenticprimitives/devkit 是什么？

开发者 Kit 核心\( 第 398 §10 / 第 399 §3 \) : ap doctor 将理论门作为数据 \+ 纯规则运行在任何树上, ap doctor --rules \(c\) 通过文摘将一个固定规则来源输入AGENTS\.md/CLAUDE\.md/\.cursor/规则, ap upgrade 重写 e

### 如何安装 @agenticprimitives/devkit？

在项目目录运行 npm install @agenticprimitives/devkit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ap，可以用 npx ap 直接运行。

### @agenticprimitives/devkit 支持 TypeScript 吗？

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

### @agenticprimitives/devkit 支持 ESM 还是 CommonJS？

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

### @agenticprimitives/devkit 可以商用吗？

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

### @agenticprimitives/devkit 的下载量有多少？

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

### @agenticprimitives/devkit 还在维护吗？

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