DCP-AI 快速开始指南¶
本文是英文版的参考译文，更新于 28/10/2026。如有出入，以英文版为准。标识符、命令和代码块保持原文，不作翻译。
本指南说明如何用 SDK 生成并验证 DCP 证据，以及哪些工具只是演示。
选择路径¶
- 用 SDK 生成并验证证据。 安装已发布的 SDK。§3 TypeScript 和 §4 Python 的 示例会创建已签名的 bundle 并加以验证；其他 SDK 给出 Go、Rust 和 WebAssembly 的安装方法和参考。 验证检查完整性和签名；它不建立对主体的信任，也不构成准入或授权（见准入）。
- 通过演示了解概念。 免安装的捷径中的 playground 和起步项目，以及 §1 和 §2 的 CLI 向导，用于展示概念。它们的限制各不相同（模拟的 PQ 密钥或签名、占位密钥、未签名的记录、仅检查结构），其产出不是验证证据。
- 不安装 SDK 运行验证器。 同一组捷径和运行参考服务中提到的参考验证服务器的可选 Docker 镜像可以验证 bundle，但不创建 bundle。
软件包的当前版本见已发布版本。
前提条件¶
取决于你使用的 SDK：
- Node.js 18+ — 用于 TypeScript SDK、CLI、WASM 软件包和
@dcp-ai/*集成；QUICKSTART_LANGCHAIN.md 中当前的 LangChain.js（v1）需要 Node.js 22+ - Python 3.10+ — 用于 Python SDK；QUICKSTART_AGNO.md 中单独的
agno-dcp软件包需要 3.11+ - Go 1.25+ — 用于 Go SDK
- Rust 稳定版 — 用于 Rust crate
你只需要打算使用的那种语言。所有 SDK 都实现同一 V2 传输格式；共享向量和互操作矩阵测试跨 SDK 的签名与验证，各 SDK 的 README 列出了其尚缺的部分。
已发布的软件包与本指南¶
TypeScript 示例使用已发布的 @dcp-ai/sdk 2.2.1，npm CLI 为 @dcp-ai/cli 2.1.1，Python 为 PyPI 上的 dcp-ai 2.10.1。见 npm、Python 与 SECURITY.md。Go 和 Rust 独立发布。源码开发请使用：
git clone https://github.com/dcp-ai-protocol/dcp-ai.git
cd dcp-ai/sdks/typescript && npm install && npm run build # TypeScript SDK of main
cd ../../cli && npm install --no-save --package-lock=false --ignore-scripts --install-links ../sdks/typescript
pip install -e /path/to/dcp-ai/sdks/python # Python SDK of main
本指南中的注册表命令安装的是已发布的版本。
免安装的捷径¶
这些捷径使用的是已发布的软件包和镜像，而不是 main。playground 和起步项目是演示，不产生 SDK 的验证证据（限制见下文）；Docker 镜像运行参考验证服务器，它验证 bundle，但不创建 bundle：
- 交互式 playground： https://docs.dcp-ai.org/playground/ — 在浏览器中生成身份、构建 bundle、验证签名。
- 脚手架起步项目： 运行
npm create @dcp-ai/langchain my-app（或/crewai、/openai、/express），即可生成一个起步项目。 - Docker 一行命令：
docker run -p 3000:3000 ghcr.io/dcp-ai-protocol/dcp-ai/verification:latest无需克隆任何内容即可启动参考验证服务器。
playground 仅为演示：其 PQ 签名是模拟的，规范化和 Merkle 处理也经过简化，因此其 bundle 不能作为供 SDK 验证的证据。起步模板 也有限制：LangChain、CrewAI 和 OpenAI 使用占位密钥和签名；Express 只检查结构。要生成可验证的 bundle，请使用下面的 SDK 示例。
1. 安装 CLI¶
CLI 向导只是用来四处看看的演示：它的“ML-DSA-65”密钥是模拟的（随机字节），它写出的 RPR 和护照没有签名，也不符合 V2 模式。要创建可以通过验证的身份和 bundle，请跳到 §3 或 §4；限制列在智能体创建中。
已发布的版本，可以安装或直接运行：
使用检出副本（见上文）时，请在你的项目目录中运行仓库自带的向导：node /path/to/dcp-ai/cli/bin/dcp-ai.js init。
2. 初始化你的智能体¶
这会在你的项目中创建以下演示文件：
| 文件 | 用途 |
|---|---|
.dcp/config.json |
智能体配置和元数据 |
.dcp/keys/ed25519_public.key、.dcp/keys/ed25519_secret.key |
Ed25519 密钥对 |
.dcp/keys/ml_dsa_65_public.key、.dcp/keys/ml_dsa_65_secret.key |
选择后量子密钥时生成的模拟“ML-DSA-65”密钥对（随机字节） |
.dcp/identity.json |
类似 RPR 的记录（未签名，不符合模式） |
.dcp/passport.json |
类似护照的记录（未签名，不符合模式） |
私钥文件以默认权限写出（在常见的 umask 022 下为 0644）：请运行 chmod 600 .dcp/keys/*_secret.key，并将 .dcp/keys/ 加入 .gitignore，使其不进入版本控制。
3. TypeScript SDK¶
下面的 TypeScript 示例适用于 npm SDK 2.2.1 或开发检出代码（参见已发布的软件包与本指南）。
二选一安装：
- 用于源码开发、从检出代码构建的
mainSDK：
- 或已发布的 SDK 2.2.1，其中包含这些修复和功能：
创建并签署 bundle（V1 — Ed25519）¶
RPR 和护照分别针对去掉 signature 字段后的对象签名。verifySignedBundle 检查 bundle 签名、其哈希和链；内部签名需另外检查。
import { BundleBuilder, generateKeypair, signBundle, signObject, verifyObject, verifySignedBundle } from '@dcp-ai/sdk';
import type { AgentPassport, ResponsiblePrincipalRecord } from '@dcp-ai/sdk';
const now = new Date().toISOString();
const principalKeys = generateKeypair();
const agentKeys = generateKeypair();
// Each artifact is signed over the object without its `signature` field.
const rprBody: Omit<ResponsiblePrincipalRecord, 'signature'> = {
dcp_version: '1.0', human_id: 'human:example-001', legal_name: 'Example Principal',
entity_type: 'natural_person', jurisdiction: 'ES', liability_mode: 'owner_responsible',
override_rights: true, issued_at: now, expires_at: null, contact: null,
};
const rpr: ResponsiblePrincipalRecord = { ...rprBody, signature: signObject(rprBody, principalKeys.secretKeyB64) };
const passportBody: Omit<AgentPassport, 'signature'> = {
dcp_version: '1.0', agent_id: 'agent:example-001', public_key: agentKeys.publicKeyB64,
principal_binding_reference: rpr.human_id, capabilities: ['browse', 'api_call'],
risk_tier: 'low', created_at: now, status: 'active',
};
const passport: AgentPassport = { ...passportBody, signature: signObject(passportBody, agentKeys.secretKeyB64) };
const bundle = new BundleBuilder()
.responsiblePrincipalRecord(rpr)
.agentPassport(passport)
.intent({
dcp_version: '1.0', intent_id: 'intent:example-001', agent_id: passport.agent_id, human_id: rpr.human_id,
timestamp: now, action_type: 'api_call', target: { channel: 'api', domain: 'api.example.com' },
data_classes: ['none'], estimated_impact: 'low', requires_consent: false,
})
.policyDecision({
dcp_version: '1.0', intent_id: 'intent:example-001', decision: 'approve', risk_score: 0.05,
reasons: ['low-impact call'], required_confirmation: null,
})
.createAuditEntry({
dcp_version: '1.0', audit_id: 'audit:example-001', timestamp: now, agent_id: passport.agent_id,
human_id: rpr.human_id, intent_id: 'intent:example-001', policy_decision: 'approved',
outcome: 'call_completed', evidence: { tool: 'http', result_ref: null },
})
.build();
const signed = signBundle(bundle, { secretKeyB64: principalKeys.secretKeyB64, signerType: 'human', signerId: rpr.human_id });
console.log(verifySignedBundle(signed, principalKeys.publicKeyB64)); // { verified: true }
// The inner signatures, over the same objects without `signature`
console.log(verifyObject(rprBody, rpr.signature, principalKeys.publicKeyB64)); // true
console.log(verifyObject(passportBody, passport.signature, agentKeys.publicKeyB64)); // true
验证 bundle¶
import { readFileSync } from 'node:fs';
import { getDefaultRegistry, registerDefaultProviders, verifySignedBundleV2 } from '@dcp-ai/sdk';
registerDefaultProviders();
const signedBundle = JSON.parse(readFileSync('bundle.signed.json', 'utf8'));
const result = await verifySignedBundleV2(signedBundle, getDefaultRegistry());
console.log(result.verified, result.errors);
V2 — 后量子混合签名¶
每个构件都是在其域分离上下文下用 Ed25519 + ML-DSA-65 签名的 SignedPayload；委托人签署 RPR 和清单，智能体签署护照、意图和策略决定。
import {
AlgorithmRegistry, BundleBuilderV2, DCP_CONTEXTS, Ed25519Provider, MlDsa65Provider, compositeSign,
generateSessionNonce, preparePayload, sha256Hex, canonicalizeV2, signBundleV2, verifySignedBundleV2,
} from '@dcp-ai/sdk';
import type {
AgentPassportV2, AuditEventV2, CompositeKeyPair, DcpContext, IntentV2, KeyEntry, PolicyDecisionV2,
ResponsiblePrincipalRecordV2, SignedPayload,
} from '@dcp-ai/sdk';
const registry = new AlgorithmRegistry();
const ed25519 = new Ed25519Provider();
const mlDsa65 = new MlDsa65Provider();
registry.registerSigner(ed25519);
registry.registerSigner(mlDsa65);
async function hybridKeys(): Promise<CompositeKeyPair> {
const c = await ed25519.generateKeypair();
const p = await mlDsa65.generateKeypair();
return {
classical: { kid: c.kid, alg: 'ed25519', secretKeyB64: c.secretKeyB64, publicKeyB64: c.publicKeyB64 },
pq: { kid: p.kid, alg: 'ml-dsa-65', secretKeyB64: p.secretKeyB64, publicKeyB64: p.publicKeyB64 },
};
}
const keyEntries = (keys: CompositeKeyPair): KeyEntry[] => [keys.classical, keys.pq].map((k) => ({
kid: k.kid, alg: k.alg, public_key_b64: k.publicKeyB64, created_at: '2026-01-01T00:00:00Z', expires_at: null, status: 'active',
}));
const sha256Of = (value: unknown) => `sha256:${sha256Hex(new TextEncoder().encode(canonicalizeV2(value)))}`;
async function signed<T>(payload: T, context: DcpContext, keys: CompositeKeyPair): Promise<SignedPayload<T>> {
const { canonicalBytes, payloadHash } = preparePayload(payload);
return { payload, payload_hash: payloadHash, composite_sig: await compositeSign(registry, context, canonicalBytes, keys) };
}
const principal = await hybridKeys();
const agent = await hybridKeys();
const nonce = generateSessionNonce();
const now = new Date().toISOString();
const rpr: ResponsiblePrincipalRecordV2 = {
dcp_version: '2.0', human_id: 'human:example-001', session_nonce: nonce, legal_name: 'Example Principal',
entity_type: 'natural_person', jurisdiction: 'ES', liability_mode: 'owner_responsible', override_rights: true,
issued_at: now, expires_at: null, contact: null, binding_keys: keyEntries(principal),
};
const passport: AgentPassportV2 = {
dcp_version: '2.0', agent_id: 'agent:example-001', session_nonce: nonce, keys: keyEntries(agent),
principal_binding_reference: rpr.human_id, capabilities: ['browse', 'api_call'], risk_tier: 'low',
created_at: now, status: 'active',
};
const intent: IntentV2 = {
dcp_version: '2.0', intent_id: 'intent:example-001', session_nonce: nonce, agent_id: passport.agent_id,
human_id: rpr.human_id, timestamp: now, action_type: 'api_call', target: { channel: 'api', domain: 'api.example.com' },
data_classes: ['none'], estimated_impact: 'low', requires_consent: false,
};
const policy: PolicyDecisionV2 = {
dcp_version: '2.0', intent_id: intent.intent_id, session_nonce: nonce, decision: 'approve', risk_score: 50,
reasons: ['low-impact call'], required_confirmation: null, applied_policy_hash: sha256Of({ policy: 'default' }), timestamp: now,
};
const audit: AuditEventV2 = {
dcp_version: '2.0', audit_id: 'audit:example-001', session_nonce: nonce, prev_hash: 'GENESIS', hash_alg: 'sha256',
timestamp: now, agent_id: passport.agent_id, human_id: rpr.human_id, intent_id: intent.intent_id,
intent_hash: sha256Of(intent), policy_decision: 'approved', outcome: 'call_completed',
evidence: { tool: 'http', result_ref: null, evidence_hash: null }, pq_checkpoint_ref: null,
};
const bundle = new BundleBuilderV2(nonce)
.responsiblePrincipalRecord(await signed(rpr, DCP_CONTEXTS.ResponsiblePrincipal, principal))
.agentPassport(await signed(passport, DCP_CONTEXTS.AgentPassport, agent))
.intent(await signed(intent, DCP_CONTEXTS.Intent, agent))
.policyDecision(await signed(policy, DCP_CONTEXTS.PolicyDecision, agent))
.addAuditEntry(audit)
.build();
const signedBundle = await signBundleV2(bundle, { registry, signerType: 'human', signerId: rpr.human_id, keys: principal });
const result = await verifySignedBundleV2(signedBundle, registry);
console.log(result.verified, result.errors); // true []
4. Python SDK¶
二选一安装：
- 用于 SDK 开发的检出代码：
- 或已发布的 2.10.1，包含本文描述的修复和 API：
创建并验证 bundle¶
from datetime import datetime, timezone
from dcp_ai import (
AgentPassport,
AuditEvidence,
BundleBuilder,
Intent,
PolicyDecision,
ResponsiblePrincipalRecord,
generate_keypair,
sign_bundle,
sign_object,
verify_object,
verify_signed_bundle,
)
now = datetime.now(timezone.utc).isoformat()
principal_keys = generate_keypair()
agent_keys = generate_keypair()
# 1. The responsible principal, signed with the principal's key (the object without "signature")
rpr_body = {
"dcp_version": "1.0", "human_id": "human:example-001", "legal_name": "Example Principal",
"entity_type": "natural_person", "jurisdiction": "ES", "liability_mode": "owner_responsible",
"override_rights": True, "issued_at": now, "expires_at": None, "contact": None,
}
rpr = {**rpr_body, "signature": sign_object(rpr_body, principal_keys["secret_key_b64"])}
# 2. The agent passport, signed with the agent's key (the object without "signature")
passport_body = {
"dcp_version": "1.0", "agent_id": "agent:example-001", "public_key": agent_keys["public_key_b64"],
"principal_binding_reference": "human:example-001", "capabilities": ["browse", "api_call"],
"risk_tier": "low", "created_at": now, "status": "active",
}
passport = {**passport_body, "signature": sign_object(passport_body, agent_keys["secret_key_b64"])}
# 3. Intent, policy decision and one audit entry
intent = Intent(
intent_id="intent:example-001", agent_id="agent:example-001", human_id="human:example-001",
timestamp=now, action_type="api_call", target={"channel": "api", "domain": "api.example.com"},
data_classes=["none"], estimated_impact="low", requires_consent=False,
)
policy = PolicyDecision(
intent_id="intent:example-001", decision="approve", risk_score=0.05, reasons=["low-impact call"],
)
bundle = (
BundleBuilder()
.responsible_principal_record(ResponsiblePrincipalRecord(**rpr))
.agent_passport(AgentPassport(**passport))
.intent(intent)
.policy_decision(policy)
.create_audit_entry(
audit_id="audit:example-001", timestamp=now, agent_id="agent:example-001",
human_id="human:example-001", intent_id="intent:example-001", policy_decision="approved",
outcome="call_completed", evidence=AuditEvidence(tool="http", result_ref=None),
)
.build()
)
# 4. Sign with the principal's key and verify against the principal's public key
signed = sign_bundle(bundle, principal_keys["secret_key_b64"])
print(verify_signed_bundle(signed, principal_keys["public_key_b64"])) # {'verified': True}
# 5. The inner signatures, over the same objects without "signature"
print(verify_object(rpr_body, rpr["signature"], principal_keys["public_key_b64"])) # True
print(verify_object(passport_body, passport["signature"], agent_keys["public_key_b64"])) # True
关于 Python 中的 V2 bundle，参见 V2 Bundles。
5. 安全等级¶
DCP 根据意图的风险概况自动选择密码学安全等级：
| 等级 | 名称 | 验证模式 | PQ 检查点间隔 | 触发条件 |
|---|---|---|---|---|
| 0 | Routine | 仅经典（Ed25519） | 每 50 个事件 | 不满足下面任何触发条件 |
| 1 | Standard | 首选混合 | 每 10 个事件 | 风险分数 200–499，estimated_impact: medium |
| 2 | Elevated | 必须混合 | 每个事件 | 风险分数 500–799、个人信息、金融或健康数据、支付、estimated_impact: high、未知值 |
| 3 | Maximum | 必须混合 | 每个事件 | 风险分数 ≥ 800、凭据、儿童数据 |
风险分数即策略决定中的 risk_score（规范 §14.2）。
import { computeSecurityTier, tierToVerificationMode } from '@dcp-ai/sdk';
const tier = computeSecurityTier(intent, policyDecision);
const mode = tierToVerificationMode(tier);
// tier: 'elevated', mode: 'hybrid_required'
6. 遥测与可观测性¶
import { dcpTelemetry } from '@dcp-ai/sdk';
dcpTelemetry.init({
serviceName: 'my-agent',
enabled: true,
exporterType: 'console', // or 'otlp'
});
// Automatic span tracking
const spanId = dcpTelemetry.startSpan('sign_bundle', { tier: 'elevated' });
// ... perform operation ...
dcpTelemetry.endSpan(spanId);
// Record metrics
dcpTelemetry.recordSignLatency(12.5, 'ed25519');
// Get summary
const summary = dcpTelemetry.getMetricsSummary();
console.log(summary.sign.p95); // p95 sign latency in ms
7. 智能体间（A2A）通信¶
import { createHello, createWelcome, createSession, encryptMessage } from '@dcp-ai/sdk';
// Agent A initiates
const hello = createHello(bundleA, kemPublicKeyB64, ['api_call'], 'standard');
// Agent B responds
const welcome = createWelcome(bundleB, kemPubB, kemCiphertextB64, 'standard');
// Establish encrypted session
const session = createSession(sessionId, sessionKey, 'agent-a', 'agent-b', 'standard');
// Send encrypted messages
const encrypted = encryptMessage(session, { action: 'transfer', amount: 100 });
其他 SDK¶
Go¶
import dcp "github.com/dcp-ai-protocol/dcp-ai/sdks/go/v2/dcp"
canonical, _ := dcp.Canonicalize(map[string]string{"b": "2", "a": "1"})
// produces {"a":"1","b":"2"}
Rust¶
ML-DSA-65、ML-KEM-768、SLH-DSA-192f、Ed25519 的提供者位于 dcp_ai::providers::*。完整接口参见 docs.rs 上的 dcp-ai crate 文档。
WebAssembly（浏览器）¶
npm install @dcp-ai/wasm@^2.1.1 # the published version; for main, see the WASM SDK's Release status
将 Rust SDK 的基础功能提供给浏览器和 Node.js。在 Node.js 中，initDcp() 需要以 data: URL 的形式提供 .wasm 文件：参见初始化。
运行参考服务¶
规范引用的全部四个服务（验证服务器、anchor、透明度日志、吊销注册表）都以 Docker 镜像发布。在一个空目录中：
docker run -d -p 3000:3000 ghcr.io/dcp-ai-protocol/dcp-ai/verification:latest
docker run -d -p 3001:3001 ghcr.io/dcp-ai-protocol/dcp-ai/anchor:latest
docker run -d -p 3002:3002 ghcr.io/dcp-ai-protocol/dcp-ai/transparency-log:latest
docker run -d -p 3003:3003 ghcr.io/dcp-ai-protocol/dcp-ai/revocation:latest
关于托管部署，参见 deploy/fly/ 中的 Fly.io 配置，以及介绍 Cloud Run / Railway / Compose 等替代方案的部署指南。
后续步骤¶
- LangChain 集成 — 为 LangChain 智能体添加 DCP
- CrewAI 集成 — 为 CrewAI 团队添加 DCP
- OpenAI 集成 — 为 OpenAI 函数调用添加 DCP
- Express 中间件 — 在 Express API 中验证 DCP bundle
- API 参考 — 完整的 SDK 文档
- 协议规范 — 完整的 DCP v2.0 规范
- 安全模型 — 威胁模型和安全架构
- 运营方指南 — 在生产中运行验证和锚定服务