SDK

Archyl 为 Node.js 和 Python 提供官方 SDK。两者都是对 REST API 的轻量封装，替您处理身份认证、序列化和错误处理。

安装

Node.js

npm install @archyl/sdk

Python

pip install archyl-sdk

快速入门

Node.js

import { ArchylClient } from "@archyl/sdk";

const client = new ArchylClient({
  apiKey: process.env.ARCHYL_API_KEY,
  organizationId: "your-org-id",
});

// List projects
const projects = await client.projects.list();

// Get C4 model
const model = await client.projects.getC4Model("project-id");

// Compute drift score
const drift = await client.governance.computeDrift("project-id");

// Create an ADR
const adr = await client.docs.createADR("project-id", {
  title: "Use PostgreSQL for persistence",
  status: "accepted",
  context: "We need a relational database for transactional data.",
  decision: "Adopt PostgreSQL 16 as the primary datastore.",
  consequences: "Team must learn PostgreSQL-specific features.",
});

Python

from archyl import ArchylClient

client = ArchylClient(
    api_key=os.environ["ARCHYL_API_KEY"],
    organization_id="your-org-id",
)

# List projects
projects = client.projects.list()

# Get C4 model
model = client.projects.get_c4_model("project-id")

# Compute drift score
drift = client.governance.compute_drift("project-id")

# Create an ADR
adr = client.docs.create_adr("project-id",
    title="Use PostgreSQL for persistence",
    status="accepted",
    context="We need a relational database for transactional data.",
    decision="Adopt PostgreSQL 16 as the primary datastore.",
    consequences="Team must learn PostgreSQL-specific features.",
)

API 参考

项目

方法 描述
projects.list() 列出组织中的所有项目
projects.get(projectId) 按 ID 获取项目
projects.create(data) 创建新项目
projects.getC4Model(projectId) 获取项目的完整 C4 模型
projects.getAgentContext(projectId) 获取架构上下文（规则、技术雷达、决策）

C4 模型

方法 描述
c4.createSystem(projectId, data) 创建系统
c4.updateSystem(projectId, systemId, data) 更新系统
c4.createContainer(projectId, systemId, data) 创建容器
c4.updateContainer(projectId, containerId, data) 更新容器
c4.createComponent(projectId, containerId, data) 创建组件
c4.createRelationship(projectId, data) 在元素之间创建关系
c4.listRelationships(projectId) 列出所有关系

治理

方法 描述
governance.runConformanceCheck(projectId, data) 针对文件运行合规规则
governance.getReport(checkId) 获取某次检查的完整报告
governance.listRules() 列出所有合规规则
governance.createRule(data) 创建合规规则
governance.getStats(projectId?) 获取合规统计数据
governance.computeDrift(projectId) 计算项目的漂移评分
governance.getDriftScore(projectId) 获取最新的漂移评分
governance.getDriftHistory(projectId) 获取漂移评分随时间变化的历史

DORA 指标

方法 描述
dora.getMetrics(projectId) 获取当前的 DORA 指标
dora.getTrend(projectId) 获取 DORA 指标随时间变化的趋势

文档

方法 描述
docs.listADRs(projectId) 列出架构决策记录
docs.createADR(projectId, data) 创建 ADR
docs.listReleases(projectId) 列出发布
docs.createRelease(projectId, data) 创建发布
docs.listChangeRequests(projectId) 列出变更请求
docs.createChangeRequest(projectId, data) 创建变更请求

错误处理

两个 SDK 都会抛出带类型的错误，其中包含 API 返回的 HTTP 状态码和错误详情。

Node.js

import { ArchylError } from "@archyl/sdk";

try {
  await client.projects.get("nonexistent-id");
} catch (error) {
  if (error instanceof ArchylError) {
    console.error(error.status); // 404
    console.error(error.code); // "NOT_FOUND"
    console.error(error.message); // "Project not found"
  }
}

Python

from archyl import ArchylError

try:
    client.projects.get("nonexistent-id")
except ArchylError as e:
    print(e.status)   # 404
    print(e.code)     # "NOT_FOUND"
    print(e.message)  # "Project not found"

常见状态码：

状态码 含义
400 错误请求 - 参数无效
401 未授权 - API 密钥无效或缺失
403 禁止访问 - 权限不足
404 未找到 - 资源不存在
429 请求过多 - 超出速率限制
500 服务器内部错误

配置

自定义基础 URL

对于自托管的 Archyl 实例，请传入自定义的 baseUrl：

const client = new ArchylClient({
  apiKey: "your-api-key",
  organizationId: "your-org-id",
  baseUrl: "https://archyl.your-company.com/api/v1",
});

client = ArchylClient(
    api_key="your-api-key",
    organization_id="your-org-id",
    base_url="https://archyl.your-company.com/api/v1",
)

源代码

两个 SDK 均已开源：

后续步骤