# @archstone/agent 中文文档

规范地址：https://npmcn.com/package/%40archstone/agent/

版本：0\.35\.0
npm 元数据更新时间：2026-10-22T12:22:36.825Z
中文译文更新时间：2026-11-08T10:04:26.261Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：114 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-07-17T21:43:58.417Z
- 最新版本发布：2026-10-22T12:22:36.475Z
- 近 30 天下载量：1806（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

直接将Archstone能力嵌入到你自己的代理循环中:为Anthropic,OpenAI,双子座和平原JSON Schema打入了工具定义,加上在编译的IR上失败关闭执行——不需要MCP服务器进程.

## 安装

```sh
npm install @archstone/agent
```

也可以使用：`pnpm add @archstone/agent`、`yarn add @archstone/agent`、`bun add @archstone/agent`

## README

# @ archstone/ 代理服务器

嵌入剂 SDK(RFC-0008 / ADD-0008):装入已编译的 Archstone IR 文物,生成打字器 工具定义(Anthropic · OpenAI Chat 补全 · OpenAI 响应 · 双子座- JSON-Schema), 以 在采掘边界上判断模型制作的文件 - 全部不运行单独的 MCP 服务器进程.

**两个切入点:**

-   **根号** (单位:千美元)`@archstone/agent`: `fromIR(json)` 构造嵌入式实例; `tools(format)` 生成已键入的工具 defs; `execute(capabilityId, input)` 引用绘图能力 适用; `extractor(resource, format)` 将一个已申报资源绑在一个目标上——计划 给出一个模型,其答案作为一个物体(ADR-0011)通过边界。 无 MCP SDK, 无 `node:fs` ——安全地捆绑并跑到任何地方(浏览器,工人,本地应用).
-   **`/mcp` 子路径** (单位:千美元)`@archstone/agent/mcp`: `mcpHandler(archstone, {bearerToken})` a 包括: 可挂载,可失效的闭塞 嵌入实例作为 MCP 服务器( 如 Claude API) `mcp_servers`, ChatGPT 连接器).

## 快开始

```typescript
import { fromIR } from "@archstone/agent";
import { readFileSync } from "node:fs";

// Load a compiled IR (produced by `archstone build manifest/`)
const ir = JSON.parse(readFileSync("archstone.ir.json", "utf-8"));
const archstone = fromIR(ir);

// Get tool definitions in your preferred format
const anthropicTools = archstone.tools("anthropic");
const openaiChatTools = archstone.tools("openai-chat");        // Chat Completions
const openaiResponsesTools = archstone.tools("openai-responses"); // Responses API
const geminiTools = archstone.tools("gemini");
// "openai" still works but is a deprecated alias of "openai-chat" — migrate explicitly.

// Invoke a capability — accepts both raw dotted id or sanitized tool name
const result = await archstone.execute("tourism.search", {
  location: "Paris",
  checkInDate: "2026-08-01",
});
// Same call with sanitized tool name (as returned by tools()):
// const result = await archstone.execute("tourism_search", {...});

if (result.status === "ok") {
  console.log("Success:", result.data);
} else if (result.status === "degraded") {
  console.log("Partial:", result.data, "Missing:", result.degraded);
} else if (result.status === "violation") {
  console.log("Contract violation:", result.missing);
} else {
  console.log("Error:", result.error);
}
// `result.withheld` (optional) names any `web-page` field whose value was outside the binding's
// declared origins and was therefore withheld — field names only, never the value.
```

工具定义信封只包含输入方案, 所以输出字段的语义类型 联合国 `web-page` 例如,链接)没有在其中表示; `execute()` 仍然应用来源 检查并返回正态链接或扣取.

**从无结构输入中提取业务数据(ADR-0011):**

《资源定义》已经描述了提供者的反应。 一样 定义说模型必须做什么 _生产_,以及 `extractor()` 两者兼有: 模型被给出了计划,验证器的答案被判断——所以两者不能漂移 分开.

```typescript
const stay = archstone.extractor("tourism.Stay", "anthropic");

// Give the model the schema — either axis, same schema underneath.
stay.structuredOutput;   // native structured output, in the envelope your provider expects:
                         //   Anthropic:        output_config.format
                         //   OpenAI-chat:      response_format.json_schema (Chat Completions)
                         //   OpenAI-responses: text.format (Responses API)
                         //   Gemini:           response_format

// ...or extraction as a forced tool call, in the same envelopes tools() emits. The
// instruction is required and never defaulted: it says what to DO on this occasion, which
// no Resource Definition can know.
stay.tool("Record the stay described in this booking email.");

// Judge what comes back, at a boundary Archstone owns.
const result = stay.validate(modelOutput);

if (result.status === "ok") {
  save(result.data);
} else if (result.status === "degraded") {
  save(result.data); // declared optional fields absent: result.degraded
} else {
  reject(result.missing, result.invalid); // withheld whole — result.data is absent
}

// Undeclared keys never reach `result.data`, at any depth, and are named in
// `result.undeclared`. There is no passthrough option, for the same reason there is none
// in ADR-0008.
```

`status` 证明 _形状_,从不真实:一个能创造出可信,正确类型值的模型 返回时 `ok`,在这个边界上,除了一个真实的,没有任何东西可以分辨出来。 错误消息 从未对文档中的值进行回声 — 提取输入是构造中最 在部署中的敏感文字.

**对于基于 HTTP 的 MCP :**

```typescript
import { mcpHandler } from "@archstone/agent/mcp";

const handler = mcpHandler(archstone, {
  bearerToken: process.env.ARCHSTONE_TOKEN,
  invoke: { env: process.env }, // optional: env injection for REST connectors
});

// Mount on your framework (e.g., Hono, Express, fetch-based)
const response = await handler(new Request(...));
```

部分 [拱顶石](https://github.com/NousVigil/archstone),开源 能力平台. 完整文件见 [`archstone/packages/agent`](https://npmcn.com/package/%40archstone/) 编辑 主要 [`README.md`](https://npmcn.com/package/README.md)。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @archstone/agent 是什么？

直接将Archstone能力嵌入到你自己的代理循环中:为Anthropic,OpenAI,双子座和平原JSON Schema打入了工具定义,加上在编译的IR上失败关闭执行——不需要MCP服务器进程\.

### 如何安装 @archstone/agent？

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

### @archstone/agent 支持 TypeScript 吗？

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

### @archstone/agent 支持 ESM 还是 CommonJS？

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

### @archstone/agent 可以商用吗？

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

### @archstone/agent 的下载量有多少？

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

### @archstone/agent 还在维护吗？

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