archstone

Archstone — 将你的业务连接到每个 AI

AI 能力编译器。 用业务语言描述一次你的业务能做什么。 Archstone 会将其编译为 AI agent 可发现并调用的工具——今天支持 MCP，其他协议推出后也会支持。无需手写集成代码。

开源，Apache-2.0。

查找所需内容

我想……	前往
60 秒内看到它运行	试用
根据我的 OpenAPI 规范生成清单	从已有 API 开始
安装 CLI 并了解每条命令的作用	安装 · 命令
了解模型（CDL → IR → 工具）	工作原理
从我自己的 Agent 循环中调用能力	嵌入使用
了解 Archstone 的保证	保证
学习这门语言	CDL 规范 · 术语表
端到端了解整个流程	入门指南
了解哪些免费、哪些收费	开源与商业版本
参与贡献	贡献指南

---

试用 — 60 秒，无需安装

由 Archstone 编译的能力已在线运行：

https://demo.archstone.dev/mcp

• Claude 应用（网页、桌面或移动端）：Settings → Connectors → Add custom connector → 粘贴 URL，然后询问有关旅行的问题。免费套餐即可使用。

• Claude Code：

  claude mcp add --transport http archstone-tourism https://demo.archstone.dev/mcp
  

只读工具无需密钥。演示版的预订工具需要密钥；两个公开密钥列在 示例集中。要发送其中一个，请在名称和 URL 后使用请求头添加服务（--header 会读取其后的所有单词，因此如果放在前面，就会把它们一并吞掉）：

claude mcp add --transport http archstone-tourism https://demo.archstone.dev/mcp \
  --header "Authorization: Bearer <key>"

其背后的整个集成只有 12 行业务 YAML——无需 HTTP、 无需 JSON Schema，也无需 MCP SDK。其他内容均由系统生成。

想让它接入你自己的系统？请联系 [email protected]。

从已有 API 开始

archstone init openapi.yaml --out manifest --company acme --domain catalog

init 会根据 OpenAPI 文档起草一份清单，询问规范无法回答的问题，并且只有在结果能够编译时才会写入文件。

详情：入门指南 → archstone init。 录屏中使用的规范是 examples/demo/stays-openapi.yaml。

---

安装

npm install -g @archstone/cli     # or: npx @archstone/cli <command>

需要 Node 22+。你的清单保存在你自己的代码仓库中；CLI 是无状态编译器，无需检出本仓库 （原因）。

命令

命令	功能
archstone init <openapi>	根据 OpenAPI 文档生成清单草稿（或者使用 --source postgres --dsn-env <VAR>，根据 Postgres 目录生成）
archstone apply <dir>	验证并编译为 IR；--exposure 会列出模型能看到和永远看不到的内容，以及哪些能力已公开、未列出或未公开（已退役、未绑定）
archstone build <dir>	写入可嵌入的可移植 IR 工件
archstone serve <dir>	通过 stdio 提供 MCP 工具；HTTP 模式使用 --http --token <t>
archstone verify <dir>	使用录制的测试数据对照实时后端重放并报告偏差；CI 模式使用 --json
archstone doctor <dir>	离线预生产检查清单
archstone adopt <dir>	声明后端开始返回的字段（交互式）
archstone audit <log>	读取执行审计轨迹

apply 还会针对 irreversible 能力仍缺少的内容发出警告——在此示例中，移除其已声明的失败场景会触发警告，恢复这些场景则会清除警告：

每条命令都在入门指南中有所介绍。 如果你是在本仓库的检出目录中操作？请使用 pnpm apply、pnpm serve 等命令——参见 贡献者入门指南。

---

工作原理

capabilities.yaml   →   *.capability.yaml   →   bindings/*.binding.yaml
(what the company      (each capability:        (how a capability maps
 offers — the index)    business shape only)     to a real backend)

        └──────── archstone apply ────────┘        └── archstone serve ──┘
             parse → validate → compile → IR          emit MCP tools → agent

• CDL（Capability Definition Language，能力定义语言）描述你提供的内容——仅限业务术语。
• 绑定说明每项能力如何连接到后端（REST 或 SQL）。SQL 连接器指南介绍了如何连接 Postgres。
• 编译器将两者降级为与目标无关的 IR；生成器将 IR 转换为工具。

更改协议后，重新生成即可，无需重写。更改后端后，CDL 无需改动。完整示例：examples/manifests/booking/。

将其嵌入你自己的 Agent

无需运行 MCP 服务进程——使用 @archstone/agent 加载已构建的 IR：

import { fromIR } from "@archstone/agent";

const archstone = fromIR(compiledIR);
const tools = archstone.tools("anthropic"); // or "openai-chat", "openai-responses", "gemini", "json-schema"
const result = await archstone.execute("tourism.search", { location: "Paris" });

可挂载的 Streamable-HTTP MCP 处理程序位于 @archstone/agent/mcp。完整 API： packages/agent。

保证

以下均为经批准的决策，而非实现细节——每项都链接到相应的决策依据。

保证	决策
清单未声明的提供方字段绝不会传递给模型	ADR-0008
模型自行编造的字段绝不会传递到你的系统	ADR-0011
build 和 serve 始终无需网络调用、账户或密钥	ADR-0005
今天免费的功能永远不会变成付费功能	ADR-0005
Archstone 执行的任何选择排序都不可出售	ADR-0006
effect（read / write / irreversible）由人确认，绝不推断	入门指南

所有决策记录：docs/adr/。

---

谁在使用

ArtVinci 是一家定制装裱企业，通过 Archstone 编译出的能力回答客户问题——使用真实目录，价格由其自有后端实时计算。案例研究。

为什么选择编译器，而不是 MCP 服务

第一个 MCP 服务只需一个下午就能完成。真正的成本在第五个——ChatGPT、Gemini 以及之后推出的产品，每个都略有不同，还都建立在不断变化的 API 之上。Archstone 是一个编译器，在首个版本中即可生成 MCP 服务，因此维护工作不会随着每种新协议的出现而倍增。

开源与商业化

将清单转换为 Agent 可调用内容所需的一切——语言、编译器、IR、发射器、嵌入式 SDK 和 CLI——均采用 Apache-2.0 许可，并将始终如此。我们将收费提供的是代为运营：托管审计留存、托管速率限制、漂移监控和多租户托管。请参阅 ADR-0005。

---

文档

主题	位置
入门指南（提供方、嵌入者、贡献者）	docs/ONBOARDING.md
CDL 规范（规范性，1.0，已冻结）	docs/cdl-specification.md
CDL 为何采用这种设计	RFC-0002
机器可读架构	cdl.schema.json
术语表	docs/glossary.md
身份与主体	docs/IDENTITY.md
架构决策	docs/adr/
将 Postgres 数据库用作后端（sql 连接器）	docs/guides/sql-connector.md
使用 Claude 的端到端演示	examples/demo/README.md
支持的版本	SUPPORT.md
报告漏洞	SECURITY.md — 切勿通过公开议题报告
变更	CHANGELOG.md

仓库布局

packages/
  schema/           load and shape-validate manifests (cdl.schema.json)
  compiler/         semantic validation, lowering to IR
  emitter-support/  shared substrate for every emitter
  runtime/          registry, MCP emitter and transport, verify
  agent/            embedded SDK
  init/             OpenAPI → manifest drafting
  cli/              the archstone command
providers/
  rest/  sql/       backend adapters
examples/           manifests and the Claude demo
docs/               spec, ADRs, RFCs, onboarding

---

本项目如何使用生成式 AI

Archstone 的实现、测试和文档编写大量借助了 AI——通过 Claude Code 使用 Anthropic 的 Claude。**决策并非由 AI 生成：**每项结构性选择都以 ADR 记录，由负责人论证并批准后才编写代码；无人能解释的补丁不会被合并。包含生成代码的提交会在共同作者信息中注明所用模型。我们对贡献者的要求见： CONTRIBUTING.md。

贡献

请参阅 CONTRIBUTING.md 和贡献者入门指南。需要 Node 22+、pnpm 11+；提交 PR 前，请确保 pnpm typecheck && pnpm test 全部通过。

许可证

版权所有 2026 NousVigil LLC。采用 Apache-2.0 许可；另请参阅 NOTICE。