$dirxv0.1

DirX 文档

DirX 让 Agent 以统一方式访问互联网 API — 导航、门禁、审计。本文档涵盖 CLI 命令、SDK、配置与错误码。

Agent 入口

如果你正在开发 AI Agent，可以让 Agent 通过以下 URL 获取 DirX 的机器可读参考文档：

$ curl https://dirx.ai/agent.md

或者直接复制以下介绍文案，粘贴给任何 Agent：

Try dirx (dirx.ai) — an open agent API gateway with built-in access control and audit.

Install: brew install dirx
Full API reference: https://dirx.ai/agent.md

Then: dirx ls /

agent.md 返回纯 Markdown，包含所有命令签名、参数和示例 — 专为 LLM 上下文窗口优化。

快速开始

--role

Agent 通过 DirX CLI 以类 Unix 方式访问互联网 API。

agent — quick start
# 1. Install
brew install dirx            # or: npm install -g @dirxai/cli
# 2. Authenticate
$ dirx auth
Token saved to ~/.dirx/credentials
# 3. Browse namespaces
$ dirx ls /
net/  skills/  docs/  policies/  runs/
# 4. Read API resources
$ dirx ls /net/api.github.com/
repos/  users/  orgs/  issues/  actions/
$ dirx cat /net/api.github.com/repos/dirxai/dirx
{"name":"dirx","full_name":"dirxai/dirx","stars":128}
# 5. Search across services
$ dirx grep "deploy" /net/
api.github.com  — GitHub v3 REST API
api.cloudflare.com — Cloudflare API

命令参考

DirX 提供 8 个核心命令来操作互联网 API：认证、浏览、读取、搜索、写入、删除、编辑、管道。

auth

认证并获取访问令牌。首次使用或令牌过期时必须执行。

Usage

dirx auth [--provider <name>] [--scope <scope>]

Example

auth
$ dirx auth
Opening browser for OAuth2 flow...
Token saved to ~/.dirx/credentials
$ dirx auth --provider api-key
Enter API key: ***

Options

FlagDescription
--provider <name>认证方式（oauth2 / api-key）
--scope <scope>请求的权限范围

ls

列出路径下的资源。类似 Unix ls — 支持 glob 和递归。

Usage

dirx ls [path] [options]

Example

ls
$ dirx ls /
net/  skills/  docs/  policies/  runs/
$ dirx ls /net/
api.github.com/  api.cloudflare.com/  api.openai.com/  ...
$ dirx ls -l /net/api.github.com/
drwxr  repos/     42 endpoints   official
drwxr  users/     12 endpoints   official
drwxr  issues/     8 endpoints   official

Options

FlagDescription
-r, --recursive递归列出子路径
-l长格式，显示权限与元数据
--depth <n>递归深度限制

cat

读取资源内容。输出 JSON 或原始字节。

Usage

dirx cat <path> [options]

Example

cat
$ dirx cat /net/api.github.com/repos/dirxai/dirx
{"name":"dirx","full_name":"dirxai/dirx","stars":128,...}
$ dirx cat /net/api.openai.com/models
{"data":[{"id":"gpt-4o",...},{"id":"gpt-4o-mini",...}]}
$ dirx cat /net/api.github.com/repos/dirxai/dirx | jq .stars
128

Options

FlagDescription
-j, --json强制 JSON 输出
-r, --raw原始字节输出
-H, --header显示响应头

grep

跨服务搜索匹配的端点。支持正则表达式。

Usage

dirx grep <pattern> [path] [options]

Example

grep
$ dirx grep "issues" /net/api.github.com/
GET  /repos/{owner}/{repo}/issues    — List issues
POST /repos/{owner}/{repo}/issues    — Create issue
$ dirx grep "deploy" /net/
api.github.com     — GitHub v3 REST API
api.cloudflare.com — Cloudflare API
api.vercel.com     — Vercel API

Options

FlagDescription
-i忽略大小写
-v反向匹配（排除）
-c, --count仅显示匹配数量

write

创建或覆盖资源。映射到 POST/PUT。支持 JSON、YAML、纯文本。

Usage

dirx write <path> [options]

Example

write
$ echo '{"title":"Bug report"}' | dirx write /net/api.github.com/repos/dirxai/dirx/issues
Created: POST /repos/dirxai/dirx/issues -> 201
$ dirx write /net/api.cloudflare.com/zones/{z}/dns_records \
    --body '{"type":"A","name":"app","content":"1.2.3.4"}'
Created: POST /zones/{z}/dns_records -> 200

Options

FlagDescription
-f, --force覆盖已有资源
--body <json>请求体（JSON 字符串）
--merge合并而非覆盖

rm

删除资源。映射到 DELETE。高风险操作 — 需要明确确认或 --force。

Usage

dirx rm <path> [options]

Example

rm
$ dirx rm /net/api.github.com/repos/dirxai/dirx/issues/42
⚠ DELETE /repos/dirxai/dirx/issues/42  confirm? [y/N] y
Deleted: 204
$ dirx rm --force /net/api.cloudflare.com/zones/{z}/dns_records/{id}
Deleted: 200

Options

FlagDescription
-f, --force跳过确认提示
--dry-run仅模拟，不实际删除

edit

部分更新 — 仅修改指定字段（PATCH 语义）。

Usage

dirx edit <path> [options]

Example

edit
$ dirx edit /net/api.github.com/repos/dirxai/dirx \
    --set description="Agent gateway"
Updated: PATCH /repos/dirxai/dirx -> 200
$ dirx edit /net/api.cloudflare.com/zones/{z}/settings --set ssl=strict
Updated: PATCH /zones/{z}/settings -> 200

Options

FlagDescription
--set <k>=<v>设置字段（可多次使用）
--unset <key>移除字段

bash

复合管道。用 | 和 shell 结构组合命令。

Usage

dirx bash [-c <script>] [--script <file>]

Example

bash
# Find repos with 1000+ stars
$ dirx bash -c 'dirx ls /net/api.github.com/repos | dirx grep "stars > 1000"'
# Cross-service search
$ dirx bash -c 'dirx grep "deploy" /net/ | while read svc; do
    dirx cat "$svc"
  done'

Options

FlagDescription
-c <script>内联脚本
--script <file>从文件读取脚本

API 提供者

如果你是 API 服务提供方，以下命令帮你将 API 注册到 DirX，让 Agent 能发现并调用。

init

在当前目录初始化 DirX 项目配置。

Usage

dirx init [--force]

Example

init
$ dirx init
Created .dirx/config.json
Created .dirx/.gitignore

Options

FlagDescription
--force覆盖已有配置

claim

通过 DNS 或 HTTP 验证认领 API 域名所有权。

Usage

dirx claim <domain> [options]

Example

claim
$ dirx claim api.example.com
Add CNAME record: api.example.com -> verify.dirx.ai
Press Enter when ready... Claimed successfully.

Options

FlagDescription
--method dns|http校验方式，默认 dns
--ttl <sec>DNS TTL（秒）

generate

从 OpenAPI/Swagger 规范生成 DIR.md 和 dir.json。

Usage

dirx generate [options]

Example

generate
$ dirx generate --spec openapi.json
Generated DIR.md (42 endpoints)
Generated dir.json

Options

FlagDescription
--spec <path>OpenAPI 规范路径
-o, --output <dir>输出目录
--format md|json输出格式

register

注册项目到 DirX 网关。上传 DIR.md 和 dir.json。

Usage

dirx register [options]

Example

register
$ dirx register
Publishing to DirX Gateway...
Registered: api.example.com -> /net/api.example.com/

Options

FlagDescription
--dry-run仅校验，不实际注册
--env staging|prod目标环境

密钥管理

DirX 支持三级凭证存储：本地 → 密钥管理器 → Vault。API 密钥由网关在调用时自动注入，Agent 无需直接接触密钥。

keys set

将 API 密钥关联到域名。网关在后续请求中自动注入。

Usage

dirx keys set <domain> --token <value> [options]

Example

keys set
$ dirx keys set api.github.com --token ghp_xxxxxxxxxxxx
Key saved for api.github.com (local)
$ dirx keys set api.openai.com --token sk-... --sync
Key saved for api.openai.com (local + vault)

Options

FlagDescription
--sync同步到 DirX Vault（AES-GCM 加密）
--overwrite覆盖已有密钥

keys list

列出已存储的密钥域名（值已脱敏）。

Usage

dirx keys list [options]

Example

keys list
$ dirx keys list
DOMAIN              STORAGE  MASK        UPDATED
api.github.com      local    ****xxxx    2026-02-27
api.openai.com      vault    ****sk-..   2026-02-27
api.cloudflare.com  local    ****xxxx    2026-02-26

Options

FlagDescription
--storage local|vault按存储位置过滤

keys remove

删除域名的 API 密钥（本地和 Vault）。

Usage

dirx keys remove <domain> [options]

Example

keys remove
$ dirx keys remove api.github.com
Removed key for api.github.com

Options

FlagDescription
--local-only仅删除本地密钥，保留 Vault

SDK 参考

@dirxai/core — TypeScript SDK，用于在代码中集成 DirX：配置、初始化、策略检查、Agent 上下文。

defineConfig

定义 DirX 配置：网关、认证、策略、密钥、审计。

Signature

defineConfig
function defineConfig<T extends DirxConfig>(options: T): T

Example

defineConfig
const config = defineConfig({
  gateway: "https://gateway.dirx.ai",
  auth: { provider: "jwt", tokenEndpoint: "/auth/token" },
  policies: { defaultAction: "allow" },
});

init

初始化 DirX 客户端。使用环境变量或显式配置。

Signature

init
function init(config?: DirxConfig): DirxClient

Example

init
import { init, defineConfig } from "@dirxai/core";
const client = init(defineConfig({
  gateway: "https://gateway.dirx.ai",
  auth: { provider: "api-key" },
}));

guard

策略检查。返回上下文是否被给定策略允许。

Signature

guard
function guard(ctx: AgentContext, policy: Policy): Promise<boolean>

Example

guard
import { guard } from "@dirxai/core";
const allowed = await guard(
  { agentId: "agent-1", path: "/net/api.github.com/repos" },
  policy
);

AgentContext

Agent 上下文接口。携带身份、路径、动作用于策略评估。

Signature

AgentContext
interface AgentContext {
  agentId: string;
  path: string;
  action?: "read" | "write" | "list" | "delete";
  metadata?: Record<string, unknown>;
}

Example

AgentContext
const ctx: AgentContext = {
  agentId: "my-agent-001",
  path: "/net/api.github.com/repos/dirxai/dirx",
  action: "read",
};

配置

项目根目录的 dirx.config.ts 文件定义网关、认证、策略、密钥和审计配置。

KeyTypeDescription
gatewaystring网关地址
auth.providerstring认证方式（jwt / api-key / oauth2）
auth.tokenEndpointstringToken 端点
policies.defaultActionstring默认策略（allow / deny）
policies.rulesRule[]策略规则数组
keys.storagestring密钥存储（local / vault / external）
keys.vaultEndpointstringVault 端点
audit.enabledboolean是否启用审计
audit.destinationstring审计目标（stdout / file / remote）
audit.levelstring审计级别（minimal / standard / verbose）
dirx.config.ts
export default defineConfig({
  gateway: "https://gateway.dirx.ai",
  auth: {
    provider: "jwt",
    tokenEndpoint: "https://gateway.dirx.ai/auth/token",
  },
  policies: {
    defaultAction: "allow",
    rules: [
      { path: "/net/api.github.com/*", action: "allow" },
      { path: "/net/*", action: "deny" },
    ],
  },
  keys: { storage: "vault", vaultEndpoint: "https://vault.dirx.ai" },
  audit: { enabled: true, destination: "remote", level: "standard" },
});

环境变量

环境变量可覆盖配置文件中的值，适用于 CI/CD 和容器化部署场景。

VariableDefaultDescription
DIRX_GATEWAYgateway.dirx.ai网关地址
DIRX_TOKEN—访问令牌
DIRX_AUTH_PROVIDERjwt认证方式
DIRX_KEYS_STORAGElocal密钥存储方式
DIRX_VAULT_ENDPOINT—Vault 端点
DIRX_AUDIT_ENABLEDfalse是否启用审计
DIRX_AUDIT_DESTstdout审计日志目标
DIRX_LOG_LEVELinfo日志级别
DIRX_CONFIG_PATH./dirx.config.ts配置文件路径

错误码

当请求失败时，DirX 会返回结构化的错误码和可读的原因说明，帮助快速定位问题。

Code#Message
DIRX_ERR_AUTH_FAILED1001认证失败
DIRX_ERR_TOKEN_EXPIRED1002Token 过期
DIRX_ERR_FORBIDDEN2001策略拒绝
DIRX_ERR_PATH_NOT_FOUND2002路径不存在
DIRX_ERR_RATE_LIMIT2003频率超限
DIRX_ERR_KEY_NOT_FOUND3001密钥未找到
DIRX_ERR_KEY_EXPIRED3002密钥过期
DIRX_ERR_UPSTREAM_TIMEOUT4001上游超时
DIRX_ERR_UPSTREAM_ERROR4002上游错误
DIRX_ERR_INVALID_SPEC5001无效规范
DIRX_ERR_CLAIM_FAILED5002认领失败
DirX v0.1.0dirx.ai — navigate · gate · audit