概述

AgentsID 是一个 AI 代理安全与权限控制平台，旨在为 AI 代理（Agent）提供工具调用级别的安全审计、权限管理和行为控制能力。该项目通过扫描 MCP（Model Context Protocol）服务器的安全漏洞，为开发者提供可操作的安全修复建议，并支持细粒度的权限配置和完整的审计日志功能。

AgentsID 的核心价值在于：在不影响 AI 代理正常工作的前提下，通过 200 行 bash 脚本的轻量级 hook 实现对工具调用的实时验证和拦截，确保 AI 代理的操作始终在预设的安全边界内运行。

资料来源：web/src/pages/landing.tsx:1-50

核心功能

安全扫描与评级系统

AgentsID 提供自动化的 MCP 服务器安全扫描功能，通过对服务器代码的静态分析和运行时行为检测，识别潜在的安全威胁并生成安全评级。

扫描器能够检测多种类型的安全问题，包括但不限于：Shell 执行风险、数据泄露风险、权限提升风险、恶意代码注入等。每个检测结果都附带可操作的修复建议，而非仅仅指出问题所在。

资料来源：web/src/pages/landing.tsx:50-80

权限控制与规则引擎

AgentsID 提供基于规则的权限控制系统，开发者可以通过配置规则来控制代理可以调用的工具及其使用条件。系统支持多种约束条件：

规则支持 AND 逻辑组合，允许多个条件同时满足时才允许工具调用执行。

资料来源：web/src/pages/guides.tsx:1-100

审计日志与完整性验证

AgentsID 维护所有工具调用的完整审计日志，采用哈希链（Hash Chain）技术确保日志的不可篡改性。

graph TD
    A[工具调用请求] --> B{规则匹配引擎}
    B -->|允许| C[执行工具]
    B -->|拒绝| D[拦截请求]
    C --> E[生成审计条目]
    D --> E
    E --> F[SHA-256 哈希]
    F --> G[追加到链式日志]
    G --> H[验证完整性]

审计日志条目包含以下关键信息：

• entryId: 日志条目唯一标识
• timestamp: 调用时间戳
• agentId: 代理标识
• tool: 被调用的工具名称
• parameters: 工具参数
• decision: 决策结果（allow/deny）
• matchedRule: 匹配的规则编号
• entryHash: 当前条目的哈希值
• prevEntryHash: 前一条目的哈希值

哈希链的验证公式为：entryHash = SHA-256(canonicalize(entry with entryHash=null))，首条记录的前置哈希固定为 "genesis"。

资料来源：web/src/pages/spec.tsx:1-80

技术架构

组件架构

AgentsID 的整体架构由以下核心组件构成：

graph TD
    subgraph 前端层
        A[Web Dashboard]
        B[Registry 页面]
        C[文档站点]
    end
    
    subgraph 核心服务
        D[API 服务]
        E[扫描引擎]
        F[规则引擎]
    end
    
    subgraph 数据层
        G[(审计日志数据库)]
        H[(规则配置存储)]
        I[(扫描结果缓存)]
    end
    
    subgraph 客户端集成
        J[AgentsID SDK]
        K[CLI 工具]
        L[MCP 服务器]
    end
    
    A --> D
    B --> E
    C --> D
    J --> D
    K --> D
    L --> F
    F --> G
    E --> I
    D --> H

SDK 集成方式

AgentsID 提供多种集成方式以满足不同开发场景的需求：

Node.js SDK 集成

npm install @agentsid/sdk

SDK 的核心是一个轻量级库，负责与 AgentsID 服务端通信、验证工具调用、记录事件日志并执行权限检查。代理代码保持简洁，无需感知安全控制的实现细节。

CLI 工具

通过 npx agentsid 命令可执行各项操作：

资料来源：web/src/pages/docs.tsx:1-100

MCP 服务器集成

AgentsID 支持与 MCP（Model Context Protocol）服务器的集成。通过在 MCP 服务器配置中添加环境变量即可启用安全控制：

{
  "mcpServers": {
    "my-notes-server": {
      "command": "node",
      "args": ["server.mjs"],
      "env": {
        "AGENTSID_PROJECT_KEY": "aid_proj_your_key_here",
        "AGENTSID_AGENT_TOKEN": "at_your_token_here"
      }
    }
  }
}

支持的 MCP 客户端包括：

• Claude Code
• Cursor
• 其他兼容 MCP 协议的客户端

资料来源：web/src/pages/guides.tsx:100-200

安全特性

数据安全原则

AgentsID 在数据处理方面遵循严格的安全原则：

研究与透明度

AgentsID 的安全研究完全公开透明：

• 所有扫描器代码在 GitHub 上开源（MIT 许可证）
• 所有研究论文开放获取
• 审计日志中的每条拒绝记录都可追溯到对应的规则提交
• 截至目前已扫描 137,070 台服务器，发现的问题均有详细文档记录

资料来源：web/src/pages/research.tsx:1-50

工具注册表

AgentsID 维护一个公开的 MCP 服务器安全评级注册表（Registry），展示各服务器的安全评分和发现的问题类型。

评级展示

每个注册服务器的信息包括：

开发者可以通过注册表快速了解某个 MCP 服务器的安全状况，并获取修复建议。

资料来源：web/src/pages/registry-v2.tsx:1-100

快速开始

安装步骤

1. 创建项目: 在 agentsid.dev/dashboard 注册账户并创建项目，获取项目密钥
2. 安装 SDK: 在项目目录执行 npm install @agentsid/sdk
3. 注册代理: 使用 SDK 注册代理并获取代理令牌
4. 配置规则: 在仪表板中配置工具调用权限规则
5. 集成验证: 将 SDK 集成到代理代码中

一键安装

npx @agentsid/setup@latest

该命令自动完成项目初始化、SDK 安装和基础配置。

资料来源：web/src/pages/landing.tsx:80-120

许可与开源

所有安全规则和策略配置采用公开透明的方式管理，确保用户对安全控制的完全可见性和可审计性。

1. 概述

AgentsID 是一个为 AI 代理提供身份认证、权限管理和审计功能的平台。其架构设计遵循"轻量级 hook"理念，核心是一个约 200 行 Bash 脚本的 hook，无复杂的 SDK 学习曲线，也无需匹配特定语言运行时。

资料来源：web/src/pages/landing.tsx

1.1 核心定位

资料来源：README.md

概述

AgentsID 后端 API 是一个基于 RESTful 架构的权限管理与审计平台接口，为 AI Agent 提供身份认证、权限控制、审计日志和委托链验证等功能。该 API 遵循 Model Context Protocol (MCP) 标准，专门用于管理 AI Agent 对外部工具的访问控制。

核心功能模块：

API 基础地址： https://api.agentsid.dev/api/v1

所有请求需要在 HTTP Header 中携带项目密钥进行认证：

Authorization: Bearer aid_proj_xxxxxxxxxxxx

资料来源：docs/API.md:1-50

认证与授权机制

项目密钥认证

每个项目拥有一个唯一的基础密钥 (aid_proj_xxx)，用于所有 API 调用的身份验证。

curl https://api.agentsid.dev/api/v1/agents \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..."

Agent 令牌认证

Agent 注册后会获得独立的 Agent Token (agt_xxx)，用于特定 Agent 的身份标识和权限验证。

{
  "agent_id": "agt_7x9k2mNpQ4rS1tUv",
  "agent_token": "agt_tok_abc123...",
  "name": "my-agent",
  "project_id": "proj_a1b2c3d4e5f6",
  "issued_at": "2026-03-29T00:00:00Z",
  "expires_at": "2026-04-29T00:00:00Z",
  "revoked_at": null
}

Agent Token 支持通过 refresh 端点重新签发，旧令牌自动失效。

curl -X POST https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv/refresh \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..."

资料来源：docs/API.md:100-150

令牌验证与内省

#### validate_token

验证 Agent 令牌的有效性，可选择性地同时检查特定工具的调用权限。

result = await aid.validate_token(token, tool="delete_user", params={"user_id": "u_789"})
# 返回: { valid: true, agent_id: "agt_xxx", permission: {...} }

返回结构：

#### introspect

完整的令牌内省接口，返回更详细的状态信息。

result = await aid.introspect(token, tool="send_email", params={"recipient": "[email protected]"})
# 返回: { active: true, agent: {...}, claims: {...}, permissions: [...], delegationChain: [...] }

资料来源：docs/API.md:200-250

身份管理接口

注册 Agent

端点： POST /api/v1/agents/register

创建新的 Agent 实例并获取唯一的 Agent Token。

请求参数：

curl -X POST https://api.agentsid.dev/api/v1/agents/register \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claude-notes-agent",
    "permissions": [
      {"tool_pattern": "search_notes", "action": "allow"},
      {"tool_pattern": "delete_note", "action": "deny"}
    ]
  }'

响应示例：

{
  "agent_id": "agt_7x9k2mNpQ4rS1tUv",
  "agent_token": "agt_tok_abc123xyz...",
  "name": "claude-notes-agent",
  "created_at": "2026-03-25T14:30:00+00:00"
}

查询 Agent

端点： GET /api/v1/agents/{agent_id}

获取指定 Agent 的详细信息。

curl https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..."

错误码：

更新 Agent

端点： PATCH /api/v1/agents/{agent_id}

更新 Agent 的名称或元数据，不影响令牌和权限。

curl -X PATCH https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..." \
  -H "Content-Type: application/json" \
  -d '{"name": "updated-agent-name"}'

刷新令牌

端点： POST /api/v1/agents/{agent_id}/refresh

签发新令牌并自动撤销所有旧令牌，支持自定义 TTL。

{
  "ttl_hours": 720
}

资料来源：docs/API.md:150-200

权限管理接口

设置权限规则

端点： PUT /api/v1/agents/{agent_id}/permissions

替换指定 Agent 的所有权限规则。

权限规则结构：

await aid.set_permissions("agt_abc123", [
    {"tool_pattern": "search_*", "action": "allow", "priority": 10},
    {"tool_pattern": "delete_*", "action": "deny", "priority": 20},
    {
        "tool_pattern": "send_email",
        "action": "allow",
        "conditions": {"recipient_domain": "company.com"},
    },
])

完整规则示例：

{
  "version": "1.0",
  "agentId": "agent_abc123",
  "issuedAt": "2026-03-29T00:00:00Z",
  "expiresAt": "2026-04-29T00:00:00Z",
  "rules": [
    {
      "tool_pattern": "github.*",
      "action": "allow",
      "conditions": {
        "params": { "repo": "my-org/*" },
        "time_range": { "start": "09:00", "end": "17:00" },
        "max_rate": 10
      },
      "priority": 100
    }
  ]
}

资料来源：server/src/api/permissions.py:1-80

查询权限规则

端点： GET /api/v1/agents/{agent_id}/permissions

获取当前 Agent 的所有权限规则。

rules = await aid.get_permissions("agt_abc123")

权限检查

端点： POST /api/v1/check

检查 Agent 是否被允许调用特定工具。

请求参数：

curl -X POST https://api.agentsid.dev/api/v1/check \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agt_7x9k2mNpQ4rS1tUv", "tool": "delete_memory"}'

响应示例（允许）：

{
  "allowed": true,
  "reason": "Allowed by rule: save_memory",
  "matched_rule": {
    "tool_pattern": "save_memory",
    "action": "allow"
  }
}

响应示例（拒绝）：

{
  "allowed": false,
  "reason": "No matching rule -- default deny",
  "matched_rule": null
}

工具模式匹配

资料来源：web/src/pages/spec.tsx:1-50

审计日志接口

查询审计日志

端点： GET /api/v1/audit/log

查询 Agent 的操作审计记录。

查询参数：

curl "https://api.agentsid.dev/api/v1/audit/log?agent_id=agt_xxx&limit=50" \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..."

响应结构：

{
  "entries": [
    {
      "id": 1,
      "agent_id": "agt_7x9k2mNpQ4rS1tUv",
      "tool": "send_email",
      "action": "allow",
      "timestamp": "2026-03-29T10:15:30Z",
      "params": {"recipient": "[email protected]"},
      "delegation_chain": ["root_agent", "agt_xxx"]
    }
  ],
  "total": 1523,
  "limit": 50,
  "offset": 0
}

验证完整性

端点： GET /api/v1/audit/verify

验证审计日志链的完整性，检测是否存在篡改。

curl "https://api.agentsid.dev/api/v1/audit/verify" \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..."

响应（完整）：

{
  "verified": true,
  "entries_checked": 1523,
  "message": "Integrity chain verified"
}

响应（链断裂）：

{
  "verified": false,
  "entries_checked": 1523,
  "broken_at_id": 42,
  "message": "Integrity chain broken at entry 42 -- possible tampering"
}

使用量统计

端点： GET /api/v1/audit/usage

获取当前项目的使用量和计划限制。

{
  "events_this_month": 1200,
  "events_limit": 10000,
  "agents_active": 5,
  "agents_limit": 25,
  "plan": "free"
}

资料来源：server/src/api/audit.py:1-100

审批流程接口

创建审批请求

当权限规则配置了审批门 (approval_gates) 时，工具调用会被暂停等待人工审批。

端点： POST /api/v1/approvals/request

{
  "agent_id": "agt_xxx",
  "tool": "delete_user",
  "params": {"user_id": "u_789"},
  "reason": "User requested account deletion"
}

查询审批状态

端点： GET /api/v1/approvals/{request_id}

审批操作

端点： POST /api/v1/approvals/{request_id}/approve

或

端点： POST /api/v1/approvals/{request_id}/reject

{
  "approver_id": "usr_admin001",
  "comment": "Verified with IT department"
}

资料来源：server/src/api/approvals.py:1-60

Webhook 通知

注册 Webhook

端点： POST /api/v1/webhooks

{
  "url": "https://your-server.com/webhook",
  "events": ["permission_denied", "agent_created", "approval_requested"],
  "secret": "whsec_your_signing_secret"
}

Webhook 事件类型

Webhook 签名验证

Webhook 请求包含 X-AgentsID-Signature 头，使用 HMAC-SHA256 签名：

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

资料来源：server/src/api/webhooks.py:1-80

团队协作接口

创建团队

端点： POST /api/v1/teams

{
  "name": "Data Processing Team",
  "description": "Handles data ETL pipelines"
}

添加 Agent 到团队

端点： POST /api/v1/teams/{team_id}/members

{
  "agent_id": "agt_xxx",
  "role": "processor"
}

团队权限继承

团队成员可以继承团队级别的权限规则，优先级低于个人规则。

graph TD
    A[个人规则] --> B{优先级判断}
    C[团队规则] --> B
    D[项目规则] --> B
    B --> E[最终权限]
    
    style A fill:#90EE90
    style C fill:#87CEEB
    style D fill:#FFB6C1
    style E fill:#FFD700

资料来源：server/src/api/teams.py:1-70

错误处理

错误响应格式

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Agent agt_xxx is not authorized to call tool delete_user",
    "details": {
      "agent_id": "agt_xxx",
      "tool": "delete_user"
    }
  }
}

常见错误码

资料来源：docs/API.md:300-350

SDK 使用示例

Python SDK

from agentsid import AgentsID

async def main():
    aid = AgentsID(api_key="aid_proj_xR7kM2pQ9...")
    
    # 注册 Agent
    agent = await aid.register_agent("my-agent", permissions=[
        {"tool_pattern": "search_*", "action": "allow"},
        {"tool_pattern": "delete_*", "action": "deny"}
    ])
    
    # 检查权限
    result = await aid.check_permission(
        agent["agent_id"], 
        "delete_file",
        params={"path": "/data/users.csv"}
    )
    
    if not result["allowed"]:
        print(f"拒绝原因: {result['reason']}")

TypeScript SDK

import { AgentsID } from '@agentsid/sdk';

const aid = new AgentsID({ apiKey: 'aid_proj_xR7kM2pQ9...' });

// 验证令牌
const validation = await aid.validateToken(token, {
  tool: 'send_email',
  params: { recipient: '[email protected]' }
});

// 查询审计日志
const logs = await aid.getAuditLog({
  agentId: 'agt_xxx',
  since: '2026-03-01',
  limit: 100
});

资料来源：sdk-python/README.md:1-100

速率限制

速率限制响应头：

• X-RateLimit-Limit: 当前限制
• X-RateLimit-Remaining: 剩余请求数
• X-RateLimit-Reset: 重置时间戳

资料来源：docs/API.md:350-400

总结

AgentsID 后端 API 提供了一套完整的 Agent 身份认证与权限管理解决方案，支持：

• 多层级认证：项目密钥 + Agent Token 双层认证体系
• 灵活的权限规则：基于通配符模式的条件约束
• 完整的审计追溯：不可篡改的审计日志链
• 灵活的审批流程：支持人工介入的审批门机制
• 事件驱动通知：Webhook 实时推送关键事件

所有接口均遵循 RESTful 规范，提供一致的错误处理和响应格式，便于与各种 Agent 框架集成。

服务架构总览

AgentsID 的核心业务服务由六个主要微服务组成，每个服务专注于特定业务领域，通过标准接口进行通信协作。

graph TD
    A[客户端 SDK] --> B[API 网关]
    B --> C[身份服务<br/>identity.py]
    B --> D[权限服务<br/>permission.py]
    B --> E[审批服务<br/>approval.py]
    B --> F[审计服务<br/>audit.py]
    B --> G[通知服务<br/>notifications.py]
    B --> H[子智能体配置服务<br/>subagent_profiles.py]
    
    C --> I[(身份数据库)]
    D --> J[(权限数据库)]
    E --> K[(审批队列)]
    F --> L[(审计日志库)]
    G --> M[(通知通道)]
    H --> N[(配置文件)]

服务组件概览表

身份服务

身份服务（Identity Service）是 AgentsID 平台的基础安全组件，负责所有与智能体身份相关的核心操作。该服务维护智能体的注册生命周期，生成不可伪造的身份凭证，并提供完整的验证机制确保每个智能体的合法性。

身份令牌体系

AgentsID 采用双层令牌体系进行身份认证：

graph LR
    A[项目密钥<br/>aid_proj_xxx] --> C[项目级别认证]
    B[智能体令牌<br/>aid_tok_xxx] --> C
    
    C --> D[智能体身份验证]
    C --> E[权限检查]

智能体注册后返回的令牌包含 HMAC 签名验证所需的元数据，支持快速验证而不暴露实际密钥材料。资料来源：web/src/pages/guides.tsx

智能体注册流程

sequenceDiagram
    participant SDK
    participant API as API 网关
    participant Identity as 身份服务
    participant DB as 数据库
    
    SDK->>API: POST /api/v1/agents/register
    API->>Identity: 创建智能体记录
    Identity->>DB: 存储元数据
    Identity->>Identity: 生成 agent_token
    Identity->>DB: 存储令牌哈希
    DB-->>Identity: 确认写入
    Identity-->>API: 返回 {agent_id, agent_token}
    API-->>SDK: 完成注册

注册接口接收智能体名称和权限配置列表，返回唯一的 agent_id 和加密的 agent_token。令牌有效期通过 TTL 参数可配置，到期后需重新注册或续期。资料来源：web/src/pages/guides.tsx

令牌验证

验证接口 /api/v1/validate 执行三项核心检查：

1. 签名验证：检查 HMAC 签名是否与存储的哈希匹配
2. 有效期验证：确认令牌未过期
3. 撤销状态验证：检查令牌是否已被主动撤销

验证失败的错误信息采用统一格式，防止信息泄露攻击。资料来源：web/src/pages/docs.tsx

{
  "valid": false,
  "reason": "Token validation failed"
}

权限服务

权限服务（Permission Service）实现了基于工具模式的细粒度访问控制机制，是 AgentsID 安全模型的核心组件。该服务通过 glob 模式匹配支持灵活的权限规则定义，允许管理员以声明式方式控制智能体可执行的工具范围。

权限规则结构

权限策略采用 JSON 格式定义，包含版本、时间戳和规则数组：

{
  "version": "1.0",
  "agentId": "agent_abc123",
  "issuedAt": "2026-03-29T00:00:00Z",
  "expiresAt": "2026-04-29T00:00:00Z",
  "rules": [
    {
      "tool_pattern": "read_file",
      "action": "allow"
    },
    {
      "tool_pattern": "delete_*",
      "action": "deny"
    }
  ]
}

资料来源：web/src/pages/spec.tsx

工具模式匹配规则

资料来源：web/src/pages/spec.tsx

权限检查流程

graph TD
    A[工具调用请求] --> B[提取工具名称]
    B --> C{匹配权限规则}
    C -->|找到匹配规则| D{规则 action}
    C -->|无匹配规则| E[默认拒绝]
    D -->|allow| F[允许执行]
    D -->|deny| G[拒绝执行]
    D -->|requires_approval| H[进入审批队列]
    
    E --> I[记录审计日志<br/>decision: deny]
    F --> J[记录审计日志<br/>decision: allow]
    G --> J
    H --> K[记录审计日志<br/>decision: pending]

权限检查 API

端点 POST /api/v1/check 接收智能体 ID 和工具名称，返回权限决策结果：

// 允许访问
{
  "allowed": true,
  "reason": "Allowed by rule: save_memory",
  "matched_rule": {
    "tool_pattern": "save_memory",
    "action": "allow"
  }
}

// 拒绝访问
{
  "allowed": false,
  "reason": "No matching rule -- default deny",
  "matched_rule": null
}

资料来源：web/src/pages/docs.tsx

条件权限

权限规则支持参数级条件限制，可精细化控制智能体仅能操作特定资源：

{
  "tool_pattern": "read_customer",
  "action": "allow",
  "conditions": {
    "params": { "customer_id": "cust_123" }
  }
}

此规则表示仅允许读取 ID 为 cust_123 的客户信息，其他客户数据访问将被拒绝。资料来源：web/src/pages/guides.tsx

审批服务

审批服务（Approval Service）处理需要人工介入的权限请求。当权限规则指定 requires_approval 动作时，对应的工具调用不会立即执行，而是进入审批队列等待授权。

审批工作流

graph LR
    A[工具调用请求] -->|requires_approval| B[审批队列]
    B --> C{等待审批}
    C -->|批准| D[执行工具]
    C -->|拒绝| E[返回拒绝响应]
    C -->|超时| F[自动拒绝]

预定义权限模板

系统提供多种权限模板供快速配置：

资料来源：web/src/pages/guides.tsx

审计服务

审计服务（Audit Service）是 AgentsID 安全合规的核心支柱，提供完整、不可篡改的操作记录追踪能力。所有工具调用决策都会被记录在审计日志中，形成可追溯的安全事件链。

审计日志结构

每条审计日志条目包含完整的上下文信息：

{
  "entryId": "entry_abc123",
  "timestamp": "2026-03-29T12:34:56.789Z",
  "agentId": "agent_def456",
  "delegationId": "del_xyz789",
  "tool": "github.push_files",
  "parameters": { "owner": "myorg", "repo": "myrepo", "branch": "main" },
  "decision": "allow",
  "matchedRule": 2,
  "constraintsEvaluated": ["rateLimit", "schedule"],
  "durationMs": 3,
  "prevEntryHash": "sha256:e3b0c44298fc1c149afb...",
  "entryHash": "sha256:a665a45920422f9d417e..."
}

资料来源：web/src/pages/spec.tsx

哈希链完整性机制

graph LR
    A[Genesis] -->|prevEntryHash| B[Entry 1]
    B -->|prevEntryHash| C[Entry 2]
    C -->|prevEntryHash| D[Entry 3]
    
    B -->|SHA-256| A
    C -->|SHA-256| B
    D -->|SHA-256| C

哈希链算法确保任何对历史条目的篡改都会导致后续所有哈希值失效：

entryHash = SHA-256(canonicalize(entry with entryHash=null))
// 首条记录使用 prevEntryHash: "genesis"

资料来源：web/src/pages/spec.tsx

链完整性验证

通过 API GET /api/v1/audit/verify 可验证审计链的完整性：

// 验证通过
{
  "verified": true,
  "entries_checked": 1523,
  "first_entry_id": "entry_001"
}

// 链断裂（检测到篡改）
{
  "verified": false,
  "entries_checked": 1523,
  "broken_at_id": 42,
  "message": "Integrity chain broken at entry 42 -- possible tampering"
}

资料来源：web/src/pages/docs.tsx

仪表盘审计条目展示

前端组件 AuditFeed.tsx 展示审计条目的关键字段：

资料来源：web/src/components/dashboard/AuditFeed.tsx

通知服务

通知服务（Notification Service）负责向相关人员推送关键事件通知，确保安全操作的及时响应。

通知触发场景

通知服务与审批服务紧密集成，在审批请求进入队列时自动触发通知流程。

子智能体配置服务

子智能体配置服务（Subagent Profiles Service）提供预定义的智能体模板和权限配置方案，简化新智能体的注册和配置流程。

配置文件结构

系统通过 YAML 配置文件定义子智能体模板：

# subagent_profiles.yaml
profiles:
  - name: "code-assistant"
    permissions:
      - tool_pattern: "read_file"
        action: "allow"
      - tool_pattern: "write_file"
        action: "allow"
        requires_approval: true
  - name: "data-analyst"
    permissions:
      - tool_pattern: "query_*"
        action: "allow"

资料来源：server/src/config/subagent_profiles.yaml

配置文件加载机制

subagent_profiles.py 服务负责解析 YAML 配置并将其转换为运行时权限规则，支持热更新而无需重启服务。

数据保留与合规

隐私数据处理

AgentsID 明确声明不销售用户数据，分析工具（PostHog）采用 opt-in 机制。资料来源：web/src/pages/privacy.tsx

审计日志保留

降级套餐时，审计日志会在 30 天内裁剪至新计划保留期限。资料来源：web/src/pages/terms.tsx

服务间交互流程

sequenceDiagram
    participant User as 用户
    participant SDK as 客户端 SDK
    participant API as API 网关
    participant Id as 身份服务
    participant Perm as 权限服务
    participant Audit as 审计服务
    participant Notif as 通知服务
    
    User->>SDK: 发起工具调用
    SDK->>API: 验证令牌 + 检查权限
    API->>Id: 验证智能体身份
    Id-->>API: 身份有效
    API->>Perm: 评估权限规则
    Perm-->>API: 权限决策
    API->>Audit: 记录审计日志
    Audit-->>API: 确认写入
    Alt 需要审批
        API->>Notif: 发送审批通知
        User->>API: 审批决策
    end
    API-->>SDK: 返回结果
    SDK-->>User: 操作完成/拒绝

总结

AgentsID 的核心业务服务层通过六个协同工作的微服务模块，构建了一个完整、安全、可审计的智能体身份与权限管理平台。身份服务确保每个智能体拥有唯一的可信身份，权限服务提供细粒度的访问控制，审批服务支持人工介入的关键决策点，审计服务提供不可篡改的操作追踪，通知服务保证关键事件的及时响应，子智能体配置服务简化了运维管理流程。所有这些服务共同遵循最小权限原则和隐私保护设计，为 Agent-MCP 生态系统提供企业级的安全保障。

概述

AgentsID 的数据模型设计围绕 Agent（代理）授权管理 和 审计追踪 两个核心功能展开。系统采用关系型数据库（PostgreSQL）存储核心实体，通过 Alembic 管理数据库迁移，确保 schema 版本可控。

主要数据模型包括：

• Project（项目）：顶级容器，存储 API 密钥加密值和项目配置
• Agent（代理）：具体的 AI 代理实例，属于某个项目
• Team & TeamMember（团队）：支持多用户协作的团队机制
• AuditEntry（审计条目）：记录所有工具调用决策，形成哈希链保证完整性
• Rule（规则）：定义代理的权限规则和约束条件

核心数据模型

Project（项目）

Project 是系统的顶级容器，每个项目拥有独立的 project_id 和加密存储的 API 密钥。

资料来源：35a9e5cf497f_add_encrypted_api_key_to_projects.py

安全设计：系统不存储原始 API 密钥，仅存储哈希值用于验证和加密后的副本用于后台通信。资料来源：web/src/pages/privacy.tsx

Agent（代理）

Agent 代表一个具体的 AI 代理实例，属于特定项目。代理可以配置权限规则，并通过 agent token 进行身份验证。

资料来源：c7e9f2b4a1d8_add_agent_type_and_parent.py

代理层级：系统支持代理的父子关系，允许构建代理树形结构，适用于复杂的多代理协作场景。

graph TD
    P[Project] --> A1[Agent 1]
    P --> A2[Agent 2]
    A1 --> A3[Sub-Agent 1.1]
    A1 --> A4[Sub-Agent 1.2]
    A2 --> A5[Sub-Agent 2.1]

Team（团队）与 TeamMember（团队成员）

系统支持多用户协作，通过 Team 和 TeamMember 实现成员管理。

资料来源：a1b2c3d4e5f6_add_teams_and_team_members.py

AuditEntry（审计条目）

审计条目是 AgentsID 安全模型的核心，每条工具调用决策都会生成一个不可变的审计记录。

资料来源：21eca51078a1_add_audit_integrity_hash_chain.py

哈希链完整性机制

概述

审计日志采用 哈希链（Hash Chain） 技术确保数据完整性。每条审计条目都包含前一条目的哈希值，形成一条不可篡改的链式结构。

哈希计算规则

graph LR
    A[Genesis Entry<br/>prevEntryHash: null] --> B[Entry 1<br/>entryHash = SHA-256(Entry 1 + null)]
    B --> C[Entry 2<br/>entryHash = SHA-256(Entry 2 + Hash(Entry 1))]
    C --> D[Entry 3<br/>entryHash = SHA-256(Entry 3 + Hash(Entry 2))]

哈希计算公式：

entryHash = SHA-256(canonicalize(entry with entryHash=null))
# 创世条目的 prevEntryHash 为 "genesis"

资料来源：web/src/pages/spec.tsx

验证流程

系统提供 /api/v1/audit/verify 接口验证审计链完整性：

{
  "verified": true,
  "entries_checked": 1523,
  "chain_length": 1523,
  "message": "Integrity chain verified"
}

验证失败响应：

{
  "verified": false,
  "entries_checked": 1523,
  "broken_at_id": 42,
  "message": "Integrity chain broken at entry 42 -- possible tampering"
}

资料来源：web/src/pages/docs.tsx

验证算法

function verifyChain(entries: AuditEntry[]): boolean {
  for (let i = 1; i < entries.length; i++) {
    const prev = entries[i - 1]
    const curr = entries[i]
    // 验证 prev.entryHash == curr.prevEntryHash
  }
}

权限规则模型

规则结构

每个代理可配置多条权限规则，每条规则定义特定工具的访问策略：

{
  "tools": ["github.push_files"],
  "action": "allow",
  "constraints": [
    { "type": "rateLimit", "max": 10, "windowSeconds": 3600 },
    { "type": "schedule", "daysOfWeek": [1,2,3,4,5], "hoursUTC": [8, 20] }
  ]
}

约束类型

资料来源：web/src/pages/spec.tsx

数据库架构图

erDiagram
    PROJECT ||--o{ AGENT : contains
    PROJECT ||--o{ TEAM : owns
    TEAM ||--o{ TEAM_MEMBER : has
    AGENT ||--o{ AUDIT_ENTRY : generates
    AGENT }o--o| AGENT : parent_child
    PROJECT {
        uuid id PK
        string api_key_hash
        string encrypted_api_key
        string plan
        datetime created_at
    }
    AGENT {
        string id PK
        uuid project_id FK
        string name
        string agent_type
        uuid parent_id FK
        json metadata
        datetime created_at
        datetime revoked_at
    }
    AUDIT_ENTRY {
        string entry_id PK
        string agent_id FK
        string delegation_id
        string tool
        json parameters
        string decision
        json constraints_evaluated
        string prev_entry_hash
        string entry_hash
        datetime timestamp
    }
    TEAM {
        uuid id PK
        string name
        datetime created_at
    }
    TEAM_MEMBER {
        uuid id PK
        uuid team_id FK
        uuid user_id
        string role
        datetime joined_at
    }

API 端点

审计相关

代理相关

资料来源：web/src/pages/docs.tsx

数据库连接管理

系统使用 SQLAlchemy 作为 ORM，并通过连接池管理数据库连接：

# server/src/core/database.py
# 管理数据库会话生命周期
# 提供依赖注入机制供 FastAPI 使用

资料来源：server/src/core/database.py

数据迁移策略

系统使用 Alembic 管理数据库迁移，所有迁移文件位于 server/alembic/versions/ 目录。迁移文件命名规范：{hash}_{description}.py。

主要迁移历史：

1. 35a9e5cf497f_add_encrypted_api_key_to_projects.py - 为项目添加加密 API 密钥支持
2. 21eca51078a1_add_audit_integrity_hash_chain.py - 添加哈希链完整性字段
3. c7e9f2b4a1d8_add_agent_type_and_parent.py - 添加代理类型和父子关系
4. a1b2c3d4e5f6_add_teams_and_team_members.py - 添加团队功能

安全特性

1. API 密钥存储：原始密钥仅存储哈希值用于验证，加密副本用于内部通信
2. 审计不可变性：哈希链机制确保审计记录不可篡改
3. 代理撤销：支持撤销代理令牌，保留审计历史
4. 委托链追踪：完整记录工具调用的委托路径

总结

AgentsID 的数据模型围绕授权管理和审计合规两个核心需求设计，通过关系型数据库存储项目、代理、团队和审计记录。哈希链机制提供了审计日志的完整性保证，支持事后验证和合规审查。

概述

AgentsID TypeScript SDK 是一个用于与 AgentsID 平台交互的官方客户端库。它提供了简洁的 API 接口，使开发者能够在其应用程序中集成 AI Agent 身份验证、权限管理和审计功能。

该 SDK 支持创建、查询、更新和删除 Agent 实例，管理 API Token，以及执行工具调用的权限验证。通过统一的接口封装，开发者无需直接处理底层 HTTP 请求和响应解析。

核心架构

模块结构

graph TD
    A[应用程序] --> B[TypeScript SDK]
    B --> C[client.ts<br/>核心客户端]
    B --> D[middleware.ts<br/>中间件组件]
    B --> E[errors.ts<br/>错误处理]
    B --> F[types.ts<br/>类型定义]
    C --> G[REST API<br/>api.agentsid.dev]
    G --> H[数据库层]
    
    style A fill:#e1effe
    style G fill:#fff3cd
    style H fill:#f8d7da

客户端初始化

SDK 通过 AgentsID 类进行初始化，需要提供项目 API Key 作为认证凭证。

import { AgentsID } from '@agentsid/sdk';

const client = new AgentsID({
  apiKey: process.env.AGENTSID_PROJECT_KEY,
  baseUrl: 'https://api.agentsid.dev' // 可选，默认值
});

初始化参数说明：

资料来源：web/src/pages/docs.tsx:SDK_INIT_TABS

Agent 管理

创建 Agent

使用 registerAgent 方法创建新的 Agent 实例并获取其首个访问 Token。

const result = await client.registerAgent({
  name: 'production-agent',
  onBehalfOf: 'proj_xxx',
  permissions: ['read', 'write'],
  ttlHours: 24,
  metadata: { environment: 'production' }
});

返回值结构：

{
  agent: Agent,
  token: string,
  tokenId: string,
  expiresAt: string
}

查询 Agent

#### 获取单个 Agent

const agent = await client.getAgent('agt_7x9k2mNpQ4rS1tUv');

#### 列出所有 Agent

const agents = await client.listAgents({
  status: 'active', // 可选：active | revoked | expired
  limit: 50          // 可选：返回数量上限
});

更新 Agent

更新 Agent 的名称或元数据信息：

const updated = await client.updateAgent('agt_7x9k2mNpQ4rS1tUv', {
  name: 'new-agent-name',
  metadata: { version: '2.0' }
});

资料来源：web/src/pages/docs.tsx:SDK_INIT_TABS

Token 管理

刷新 Token

当 Token 即将过期时，可使用 refreshToken 方法签发新 Token，同时自动吊销所有旧 Token。

const result = await client.refreshToken('agt_7x9k2mNpQ4rS1tUv', {
  ttlHours: 48
});

响应示例：

{
  "agent_id": "agt_7x9k2mNpQ4rS1tUv",
  "token": "aid_tok_newtoken...",
  "token_id": "tok_f6e5d4c3b2a1",
  "expires_at": "2026-03-27 14:30:00+00:00"
}

Token 验证

SDK 提供 validate 方法用于验证 Token 并检查特定操作的权限：

const result = await client.validate({
  token: 'aid_tok_eyJzdWIiOiJhZ3RfN3g5azJt...',
  tool: 'save_memory',
  params: { category: 'note' }
});

响应结构：

// Token 有效且有权执行
{
  valid: true,
  allowed: true,
  matched_rule: {
    tool_pattern: "save_memory",
    action: "allow"
  }
}

// Token 无效
{
  valid: false,
  reason: "Token validation failed"
}

:::info 安全说明 为防止信息泄露，SDK 对过期 Token、无效签名、已吊销 Token 和项目不匹配的情况返回相同的通用错误消息。 :::

资料来源：web/src/pages/docs.tsx:SDK_INIT_TABS

权限委托

创建子 Agent

通过 delegate 方法创建具有受限权限的子 Agent：

const childAgent = await client.delegate({
  parentAgentId: 'agt_parent_xxx',
  name: 'limited-child-agent',
  permissions: ['read-only']
});

子 Agent 继承父 Agent 的身份，但在权限范围、有效期等维度受到限制。

审计功能

查询审计日志

const logs = await client.audit.list({
  agentId: 'agt_xxx',
  limit: 100,
  offset: 0
});

验证完整性链

const result = await client.audit.verify();

响应示例（链完整）：

{
  "verified": true,
  "entries_checked": 1523,
  "message": "Integrity chain verified"
}

响应示例（链损坏）：

{
  "verified": false,
  "entries_checked": 1523,
  "broken_at_id": 42,
  "message": "Integrity chain broken at entry 42 -- possible tampering"
}

用量查询

const usage = await client.audit.usage();

响应示例：

{
  "events_this_month": 1200,
  "events_limit": 10000,
  "agents_active": 5,
  "agents_limit": 25,
  "plan": "free"
}

错误处理

SDK 定义了统一的错误类型体系，便于调用方进行错误捕获和处理：

import { AgentsIDError, AuthError, ValidationError, NotFoundError } from '@agentsid/sdk';

try {
  const agent = await client.getAgent('invalid-id');
} catch (error) {
  if (error instanceof AuthError) {
    // 处理认证错误
  } else if (error instanceof NotFoundError) {
    // 处理资源不存在
  } else if (error instanceof ValidationError) {
    // 处理参数验证错误
  }
}

资料来源：sdk-typescript/src/errors.ts

中间件集成

MCP 服务器中间件

SDK 提供中间件组件，用于保护 MCP（Model Context Protocol）服务器的工具调用：

import { createAgentsIDMiddleware } from '@agentsid/sdk/middleware';

const middleware = createAgentsIDMiddleware({
  projectKey: process.env.AGENTSID_PROJECT_KEY,
  agentToken: process.env.AGENTSID_AGENT_TOKEN,
  url: 'https://api.agentsid.dev'
});

完整集成示例：

// server.mjs
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { createAgentsIDMiddleware } from '@agentsid/sdk/middleware';

const AGENTSID_PROJECT_KEY = process.env.AGENTSID_PROJECT_KEY;
const AGENTSID_AGENT_TOKEN = process.env.AGENTSID_AGENT_TOKEN;

const validateToolCall = async (tool, params) => {
  const response = await fetch(`${AGENTSID_URL}/api/v1/validate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${AGENTSID_PROJECT_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      token: AGENTSID_AGENT_TOKEN,
      tool,
      params
    })
  });
  
  const result = await response.json();
  if (!result.valid || !result.permission?.allowed) {
    throw new Error(`Tool ${tool} is not allowed`);
  }
  return result;
};

// MCP 服务器工具定义
const server = new McpServer({ name: 'protected-notes', version: '1.0.0' });

server.tool(
  'save_memory',
  'Save a note to memory',
  { category: z.enum(['note', 'preference']), content: z.string() },
  async ({ category, content }) => {
    await validateToolCall('save_memory', { category, content });
    // 执行实际的保存逻辑
    return { success: true };
  }
);

工具验证流程

sequenceDiagram
    participant A as AI Agent
    participant M as MCP Server
    participant S as AgentsID SDK
    participant P as AgentsID API
    
    A->>M: 调用工具 save_memory
    M->>S: validate(tool, params)
    S->>P: POST /api/v1/validate
    P->>P: 验证 Token 和权限规则
    alt 允许执行
        P-->>S: { valid: true, allowed: true }
        S-->>M: 验证通过
        M->>M: 执行工具逻辑
        M-->>A: 返回结果
    else 拒绝执行
        P-->>S: { valid: true, allowed: false }
        S-->>M: 抛出错误
        M-->>A: 权限拒绝错误
    end

资料来源：web/src/pages/guides.tsx:validateToolCall

类型定义

SDK 导出完整的 TypeScript 类型定义，确保开发时的类型安全和自动补全支持。

核心类型

// Agent 实例
interface Agent {
  id: string;
  name: string;
  project_id: string;
  status: 'active' | 'revoked' | 'expired';
  created_at: string;
  revoked_at: string | null;
  metadata: Record<string, unknown>;
}

// Token 信息
interface Token {
  id: string;
  agent_id: string;
  created_at: string;
  expires_at: string;
  revoked_at: string | null;
}

// 审计日志条目
interface AuditEntry {
  id: string;
  agent_id: string;
  tool: string;
  params: Record<string, unknown>;
  result: 'allow' | 'deny';
  reason: string;
  created_at: string;
}

// 用量信息
interface UsageStats {
  events_this_month: number;
  events_limit: number;
  agents_active: number;
  agents_limit: number;
  plan: string;
}

资料来源：sdk-typescript/src/types.ts

环境变量

最佳实践

1. 安全存储凭证

始终通过环境变量加载 API Key，避免硬编码在源代码中：

// ✅ 推荐
const client = new AgentsID({
  apiKey: process.env.AGENTSID_PROJECT_KEY
});

// ❌ 不推荐
const client = new AgentsID({
  apiKey: 'aid_proj_xxx'
});

2. Token 轮换

建议定期调用 refreshToken 方法轮换 Token，以降低 Token 泄露的风险：

// 每 23 小时轮换一次（Token 有效期 24 小时）
setInterval(async () => {
  await client.refreshToken(agentId, { ttlHours: 24 });
}, 23 * 60 * 60 * 1000);

3. 错误重试

对于网络错误和 5xx 服务器错误，建议实现指数退避重试策略：

const client = new AgentsID({
  apiKey: process.env.AGENTSID_PROJECT_KEY,
  retry: {
    maxAttempts: 3,
    backoff: 'exponential',
    initialDelay: 1000
  }
});

4. 审计日志持久化

将审计事件异步写入持久化存储，以便进行合规审计和问题排查：

client.audit.on('entry', async (entry) => {
  await db.auditLogs.insert(entry);
});

安装

npm install @agentsid/sdk

或使用其他包管理器：

yarn add @agentsid/sdk
pnpm add @agentsid/sdk

版本要求

• Node.js >= 18.0.0
• TypeScript >= 5.0.0（类型定义已内置）

相关资源

• API 参考文档
• 快速入门指南
• SDK 源码仓库
• GitHub Issues

概述

AgentsID 提供多语言 SDK（Python、Ruby、Java），为开发者提供统一的接口来集成 Agent 身份验证、权限管理和审计日志功能。这些 SDK 封装了与 AgentsID API 的通信逻辑，开发者无需直接处理 HTTP 请求和响应解析。

核心功能

设计理念

AgentsID 的 SDK 设计遵循以下原则：

• 轻量化：核心功能简洁，不引入不必要的依赖
• 跨平台一致性：各语言 SDK 提供统一的 API 接口
• 零学习成本：通过中间件模式快速集成到现有系统

资料来源：web/src/pages/landing.tsx

SDK 初始化

基础配置

所有 SDK 都需要使用项目密钥（Project Key）进行初始化。项目密钥可在 agentsid.dev/dashboard 创建项目后获取。

# 获取项目密钥后初始化
Project ID: proj_a1b2c3d4e5f6
API Key:    aid_proj_xR7kM2pQ9...
Plan:       free

资料来源：web/src/pages/guides.tsx

初始化参数

环境变量配置

建议通过环境变量配置敏感信息：

资料来源：web/src/pages/guides.tsx

Agent 方法

方法列表

资料来源：web/src/pages/docs.tsx

创建 Agent

# Python SDK 示例
agent = client.register_agent(
    name="research-assistant",
    on_behalf_of="user_abc",
    permissions=[
        {"tool_pattern": "search_memories", "action": "allow"},
        {"tool_pattern": "save_memory", "action": "allow"}
    ],
    ttl_hours=24,
    metadata={"framework": "langchain"}
)

# Ruby SDK 示例
agent = client.register_agent(
  name: "research-assistant",
  on_behalf_of: "user_abc",
  permissions: [
    { tool_pattern: "search_memories", action: "allow" },
    { tool_pattern: "save_memory", action: "allow" }
  ],
  ttl_hours: 24,
  metadata: { framework: "langchain" }
)

// Java SDK 示例
AgentRegistration agent = client.registerAgent(
    "research-assistant",
    "user_abc",
    Arrays.asList(
        new Permission("search_memories", "allow"),
        new Permission("save_memory", "allow")
    ),
    24,
    Map.of("framework", "langchain")
);

权限规则

权限规则使用通配符模式匹配工具名称：

资料来源：web/src/pages/guides.tsx

中间件集成

MCP 服务器集成

SDK 提供与 Model Context Protocol (MCP) 服务器的集成中间件，适用于 Claude Code、Cursor 等 AI 编程工具的扩展开发。

// MCP 服务器验证中间件示例
const AGENTSID_PROJECT_KEY = process.env.AGENTSID_PROJECT_KEY;
const AGENTSID_AGENT_TOKEN = process.env.AGENTSID_AGENT_TOKEN;

async function validateToolCall(toolName, args) {
  const response = await fetch("https://api.agentsid.dev/api/v1/verify", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${AGENTSID_PROJECT_KEY}`,
      "X-Agent-Token": AGENTSID_AGENT_TOKEN
    },
    body: JSON.stringify({ tool: toolName, parameters: args })
  });
  
  const result = await response.json();
  
  if (!result.allowed) {
    throw new Error(`Tool ${toolName} denied: ${result.reason}`);
  }
  
  return result;
}

资料来源：web/src/pages/guides.tsx

中间件架构

graph TD
    A[Agent Tool Call] --> B[MCP Middleware]
    B --> C{validateToolCall}
    C -->|请求验证| D[AgentsID API]
    D -->|allowed: true| E[执行工具]
    D -->|allowed: false| F[拒绝执行]
    E --> G[记录审计日志]
    G --> H[返回结果]
    F --> I[返回错误]

中间件组件

审计日志

日志条目结构

{
  "entryId": "entry_abc123",
  "timestamp": "2026-03-29T12:34:56.789Z",
  "agentId": "agent_def456",
  "delegationId": "del_xyz789",
  "tool": "github.push_files",
  "parameters": { "owner": "myorg", "repo": "myrepo", "branch": "main" },
  "decision": "allow",
  "matchedRule": 2,
  "constraintsEvaluated": ["rateLimit", "schedule"],
  "durationMs": 3,
  "prevEntryHash": "sha256:e3b0c44298fc1c149afb...",
  "entryHash": "sha256:a665a45920422f9d417e..."
}

资料来源：web/src/pages/spec.tsx

哈希链完整性

每个审计条目都包含前一个条目的哈希值，形成不可篡改的链式结构：

# 哈希链计算
entryHash = SHA-256(canonicalize(entry with entryHash=null))
# 首条目使用 prevEntryHash: "genesis"

def verify_chain(entries: list[AuditEntry]) -> bool:
    """验证审计日志链完整性"""
    for i in range(1, len(entries)):
        prev = entries[i - 1]
        curr = entries[i]
        if curr.prev_entry_hash != prev.entry_hash:
            return False
    return True

资料来源：web/src/pages/spec.tsx

链验证结果

{
  "verified": true,
  "entries_checked": 1523,
  "chain_intact": true
}

{
  "verified": false,
  "entries_checked": 1523,
  "broken_at_id": 42,
  "message": "Integrity chain broken at entry 42 -- possible tampering"
}

资料来源：web/src/pages/docs.tsx

策略管理

规则结构

规则评估

# 规则评估伪代码
def evaluate_rule(tool_name, rules):
    # 按优先级降序排序
    sorted_rules = sorted(rules, key=lambda r: r.priority, reverse=True)
    
    for rule in sorted_rules:
        if matches_pattern(tool_name, rule.tool_pattern):
            return rule.action
    
    # 默认拒绝
    return "deny"

默认行为

No rules defined. All tool calls will be denied by default.

资料来源：web/src/components/dashboard/PoliciesTab.tsx

错误处理

HTTP 错误码

# curl 示例
curl https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..."

资料来源：web/src/pages/docs.tsx

套餐与限制

使用量查询

curl "https://api.agentsid.dev/api/v1/audit/usage" \
  -H "Authorization: Bearer aid_proj_xR7kM2pQ9..."

响应格式

{
  "events_this_month": 1200,
  "events_limit": 10000,
  "agents_active": 5,
  "agents_limit": 25,
  "plan": "free"
}

套餐限制

资料来源：web/src/pages/docs.tsx

快速开始

1. 安装 SDK

# Python
pip install agentsid

# Ruby
gem install agentsid

# Java (Maven)
<dependency>
    <groupId>dev.agentsid</groupId>
    <artifactId>agentsid-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

2. 初始化客户端

from agentsid import Client

client = Client(
    project_key="aid_proj_xR7kM2pQ9...",
    agent_token="at_your_token_here"
)

3. 注册 Agent

agent = client.register_agent(
    name="my-agent",
    on_behalf_of="user_123",
    permissions=[
        {"tool_pattern": "read_*", "action": "allow"},
        {"tool_pattern": "write_*", "action": "deny"}
    ]
)
print(f"Agent ID: {agent['agent_id']}")

4. 验证工具调用

result = client.verify_tool(
    tool="read_user_data",
    parameters={"user_id": "123"}
)

if result.allowed:
    # 执行工具逻辑
    pass
else:
    print(f"Denied: {result.reason}")

数据隐私

AgentsID SDK 在处理数据时遵循严格的隐私保护原则：

"We never store raw API keys. Only hashes."

"We do not sell your data. Ever."

资料来源：web/src/pages/privacy.tsx

相关资源

资料来源：web/src/pages/research.tsx, web/src/pages/landing.tsx

概述

Web 仪表板是 AgentsID 平台的核心管理界面，为用户提供统一的控制台来管理 AI Agent、权限配置、团队协作和审计日志。仪表板采用 React + TypeScript 构建，使用 Tailwind CSS 进行样式管理，通过 Supabase 实现身份认证和后端数据交互。

仪表板的主要功能包括：

• Agent 管理：注册、查看、更新和撤销 AI Agent
• 权限编辑：通过可视化界面配置 Agent 的工具调用权限规则
• 团队管理：支持多用户协作，管理团队成员和权限委派
• 审计日志：实时查看所有 Agent 的工具调用记录和 Allow/Deny 决策
• 注册表浏览：查看公开的工具包安全评分和详细信息

页面路由架构

仪表板通过 React Router 进行路由管理，所有路由均位于 /dashboard 路径下。 资料来源：web/src/App.tsx

graph TD
    A[App 根组件] --> B[路由配置]
    B --> C[/]
    B --> D[/dashboard]
    B --> E[/registry]
    B --> F[/registry/:registrySlug]
    
    D --> G[仪表板页面]
    G --> H[概览视图]
    G --> I[Agents 标签页]
    G --> J[Audit 标签页]
    G --> K[Team 标签页]
    
    H --> L[AgentCards 组件]
    I --> M[AgentCards 组件]
    I --> N[PermissionEditor 组件]
    I --> O[RegisterAgentModal 组件]
    J --> P[AuditFeed 组件]
    K --> Q[TeamTab 组件]

核心组件结构

AgentCards 组件

AgentCards 是仪表板中用于展示 Agent 列表的核心组件。该组件负责渲染所有已注册的 Agent 卡片，提供快速概览和快捷操作入口。

主要功能：

• 展示 Agent 基本信息（名称、状态、创建时间）
• 显示 Agent 的当前权限规则数量
• 提供快捷操作按钮（查看详情、编辑权限）
• 支持状态徽章显示（Active/Expired/Pending）

数据结构：

资料来源：web/src/components/dashboard/AgentCards.tsx

PermissionEditor 组件

PermissionEditor 是权限配置的可视化编辑器，允许用户通过图形界面管理 Agent 的工具调用规则。

权限规则格式：

interface PermissionRule {
  tool_pattern: string;  // 支持通配符，如 "search_*"
  action: 'allow' | 'deny';
}

操作模式：

• Allow 模式：允许匹配规则的工具调用
• Deny 模式：阻止匹配规则的工具调用，Agent 会收到 "blocked" 响应但不会察觉限制存在

配置示例：

[
  { "tool_pattern": "search_*", "action": "allow" },
  { "tool_pattern": "read_*", "action": "allow" },
  { "tool_pattern": "delete_*", "action": "deny" },
  { "tool_pattern": "admin_*", "action": "deny" }
]

资料来源：web/src/components/dashboard/PermissionEditor.tsx 资料来源：web/src/pages/guides.tsx

AuditFeed 组件

AuditFeed 组件提供实时审计日志流，显示所有 Agent 的工具调用记录和权限决策。

审计条目包含的信息：

委派链展示：

当 Agent 通过委派机制运行时，AuditFeed 会显示完整的委派链路：

user:usr_xxx → agent:agt_parent → agent:agt_child

资料来源：web/src/components/dashboard/AuditFeed.tsx

TeamTab 组件

TeamTab 组件用于团队协作管理，支持多成员和权限委派功能。

团队管理功能：

• 查看团队成员列表
• 管理成员角色和权限
• 配置跨成员的 Agent 委派关系
• 审计团队范围内的所有操作

资料来源：web/src/components/dashboard/TeamTab.tsx

RegisterAgentModal 组件

RegisterAgentModal 是注册新 Agent 的模态框组件，提供完整的 Agent 创建流程。

注册表单字段：

响应数据格式：

interface RegisterResponse {
  agent: Agent;
  token: string;
  tokenId: string;
  expiresAt: string;
}

资料来源：web/src/components/dashboard/RegisterAgentModal.tsx

页面布局结构

仪表板页面采用顶部导航 + 侧边栏 + 主内容区的经典布局：

graph TD
    A[顶部导航栏] --> A1[项目选择器]
    A --> A2[用户菜单]
    A --> A3[API Key 显示]
    
    B[主内容区] --> B1[概览视图]
    B --> B2[标签页容器]
    
    B2 --> B3[Agents 标签]
    B2 --> B4[Audit 标签]
    B2 --> B5[Team 标签]
    
    C[底部页脚] --> C1[文档链接]
    C --> C2[使用条款]
    C --> C3[隐私政策]

底部页脚链接

资料来源：web/src/pages/dashboard.tsx

API 集成

认证机制

仪表板通过 Supabase Auth 进行用户身份认证。所有 API 请求需要在 Authorization header 中携带 Bearer Token。

核心 API 端点

资料来源：web/src/pages/docs.tsx

API Key 管理

仪表板在顶部导航栏显示用户的 API Key，用于服务端验证。API Key 格式为 aid_proj_xxx。

技术栈

资料来源：web/README.md

状态管理

仪表板使用 React Hooks 进行本地状态管理，主要状态包括：

• activeTab：当前激活的标签页（'agents' | 'audit' | 'team'）
• registerModalOpen：注册 Agent 模态框开关状态
• apiKey：用户 API Key 凭证
• agents：Agent 列表数据
• auditEntries：审计日志条目

graph LR
    A[用户交互] --> B[状态更新]
    B --> C[UI 重新渲染]
    C --> D[API 调用]
    D --> E[数据获取]
    E --> F[状态同步]
    F --> C

响应式设计

仪表板采用移动优先的响应式设计策略：

与其他模块的关联

注册表模块

仪表板提供跳转到公开注册表的入口，用户可以浏览已扫描的工具包安全评分：

/registry           # 注册表首页
/registry/:slug    # 特定工具包详情页

落地页

注册表详情页包含安全评分展示，包括等级徽章（GradeStamp）和关键发现列表。 资料来源：web/src/pages/registry-server-v2.tsx

安全考虑

1. API Key 保护：仅显示 API Key 哈希值，不存储原始密钥
2. 权限验证：所有操作通过服务端 JWT 验证
3. 审计追踪：所有工具调用和权限决策均被记录
4. Cookie 同意：PostHog 分析采用 Opt-in 机制 资料来源：web/src/pages/privacy.tsx

开发构建

项目使用 Vite 作为构建工具：

# 安装依赖
npm install

# 开发模式
npm run dev

# 生产构建
npm run build

# 预览构建结果
npm run preview

资料来源：web/README.md

概述

AgentsID 提供一套完整的命令行工具和 IDE 集成方案，使开发者能够在各种开发环境中快速部署 AI Agent 安全控制。Setup CLI 是整个系统的入口点，负责项目初始化、Agent 注册以及与主流 IDE 的无缝集成。 资料来源：web/src/pages/landing.tsx:1-50

该 CLI 采用零配置设计理念，核心安装命令为：

npx @agentsid/setup@latest

安装后会获得一个轻量级的 hook（仅 200 行 Bash 脚本），无需学习复杂的 SDK 或匹配特定的运行时环境。 资料来源：web/src/pages/landing.tsx:1-50

核心安装流程

Step 1: 创建项目目录

mkdir my-protected-server && cd my-protected-server

Step 2: 初始化项目

npm init -y
npm install @modelcontextprotocol

Step 3: 安装 SDK

npm install @agentsid/sdk

安装完成后，系统会输出类似以下信息：

added {s.tools + 12} packages

── AgentsID ──────────────────────────────
  {s.package}  [ {grade} · {GRADE_NAMES[grade]} ]
    {critical} CRITICAL · {high} HIGH · {medium} MEDIUM

  agentsid.dev/registry/{registrySlug}
──────────────────────────────────────────

资料来源：web/src/pages/registry-server-v2.tsx:1-50

支持的 IDE 集成

AgentsID 支持与主流 AI 编程工具的深度集成，每个集成都通过 MCP（Model Context Protocol）协议实现。

Claude Code 集成

Claude Code 是 Anthropic 提供的命令行工具，AgentsID 通过 MCP Server 为其提供安全控制。

集成步骤：

1. 在 agentsid.dev/dashboard 创建账户并注册 Agent
2. 创建 MCP Server 文件 server.mjs
3. 安装依赖：npm init -y && npm install @modelcontextprotocol/sdk zod
4. 配置环境变量 AGENTSID_PROJECT_KEY 和 AGENTSID_AGENT_TOKEN

MCP Server 配置示例：

{
  "mcpServers": {
    "my-notes-server": {
      "command": "node",
      "args": ["server.mjs"],
      "env": {
        "AGENTSID_PROJECT_KEY": "aid_proj_your_key_here",
        "AGENTSID_AGENT_TOKEN": "at_your_token_here"
      }
    }
  }
}

资料来源：web/src/pages/guides.tsx:1-80

Cursor 集成

Cursor IDE 支持通过 .cursor/mcp.json 配置文件加载自定义 MCP Server。AgentsID 为 Cursor 提供即插即用的集成方案。

配置方式与 Claude Code 类似，通过修改 .cursor/mcp.json 添加 AgentsID Server 即可。

Codex 集成

OpenAI Codex 的集成采用相同架构，确保在各种 AI 辅助编程场景下都能获得一致的安全保护。

Gemini 集成

Google Gemini 的集成支持扩展 AgentsID 的保护范围到更多 AI 平台。

预设配置

AgentsID 提供多种预设配置，满足不同安全级别的需求。

权限控制示例

以下示例展示如何通过预设限制 Agent 的工具访问权限：

<GuideTable
  headers={["Tool", "What it does", "Permission"]}
  rows={[
    [<InlineCode>search_notes</InlineCode>, "Search notes by keyword", <StatusBadge status="allowed" />],
    [<InlineCode>save_note</InlineCode>, "Create a new note", <StatusBadge status="allowed" />],
    [<InlineCode>list_notes</InlineCode>, "List all notes", <StatusBadge status="allowed" />],
    [<InlineCode>delete_note</InlineCode>, "Delete a note by ID", <StatusBadge status="denied" />],
    [<InlineCode>admin_reset</InlineCode>, "Wipe all data", <StatusBadge status="denied" />],
  ]}
/>

Agent 拥有全部五个工具的访问能力，但 AgentsID 会拦截任何尝试使用 delete_note 或 admin_reset 的请求。Agent 本身不会察觉到限制——它只会收到一个"blocked"响应并继续执行后续操作。 资料来源：web/src/pages/guides.tsx:1-50

安全扫描与分级

评分系统

AgentsID 对集成工具进行自动安全扫描，采用 A-F 等级评分系统：

扫描器已开源，可在 GitHub 获取：https://github.com/AgentsID-dev/agentsid-scanner

执行命令：npx @agentsid/scanner 资料来源：web/src/pages/research.tsx:1-50

扫描统计

截至目前，AgentsID 已扫描超过 137,070 个服务器，发现并记录了大量安全问题。所有研究均可在 GitHub 上公开访问。

配置参数

SDK 初始化

// SDK 初始化
const client = new AgentsIDClient({
  projectKey: 'aid_proj_xxx',
  agentToken: 'at_xxx'
});

Agent 方法

资料来源：web/src/pages/docs.tsx:1-80

权限配置

审计日志采用 SHA-256 哈希链确保完整性：

entryHash = SHA-256(canonicalize(entry with entryHash=null))
// 首条记录使用 prevEntryHash: "genesis"

资料来源：web/src/pages/spec.tsx:1-80

工作流程图

graph TD
    A[安装 Setup CLI] --> B[创建项目]
    B --> C[注册 Agent]
    C --> D[配置 IDE 集成]
    D --> E{选择预设}
    E -->|lockdown| F[高安全模式]
    E -->|security-team| G[安全团队模式]
    E -->|developer| H[开发者模式]
    F --> I[部署 MCP Server]
    G --> I
    H --> I
    I --> J[Agent 执行工具调用]
    J --> K{Hook 拦截请求}
    K -->|允许| L[执行工具]
    K -->|拒绝| M[记录审计日志]
    M --> N[返回 blocked 响应]

后续步骤

完成 Setup CLI 与集成配置后，建议进行以下操作：

1. 验证配置：使用 agentsid verify 命令确认集成正常工作
2. 查看审计日志：通过仪表板审查所有工具调用记录
3. 调整权限：根据实际需求精细化配置权限规则
4. 定期扫描：在每次发布前运行安全扫描，确保新工具符合安全标准

安装命令复制功能已内置于界面中，点击按钮即可快速复制 npx @agentsid/setup@latest 命令。 资料来源：web/src/pages/landing.tsx:1-50

核心功能概述

MCP 安全扫描器的主要职责包括：

1. 静态代码分析 - 解析 MCP 服务器代码，识别潜在的安全风险
2. 工具权限评估 - 检测 MCP 工具的能力边界和权限范围
3. 安全评级生成 - 基于规则引擎为每个 MCP 服务器分配 A-F 安全等级
4. 问题分类统计 - 按 CRITICAL、HIGH、MEDIUM、LOW 四个严重级别归类发现问题
5. 修复建议生成 - 针对发现的问题提供具体的 agentsid.json 策略配置

资料来源：web/src/pages/research.tsx:8

架构设计

graph TD
    A[MCP 服务器代码] --> B[扫描器引擎]
    B --> C[规则匹配引擎]
    C --> D{风险评估}
    D -->|CRITICAL| E[阻止级问题]
    D -->|HIGH| F[警告级问题]
    D -->|MEDIUM| G[注意级问题]
    D -->|LOW| H[信息级问题]
    E --> I[安全评级 F]
    F --> I
    G --> J[安全评级 C-D]
    H --> J
    I --> K[公开研究报告]
    J --> K

安全评级体系

扫描器使用 A-F 六级安全评级系统，评级基于发现的问题数量和严重程度。

资料来源：web/src/pages/landing.tsx:88-105

评级判定规则

评级由扫描发现的问题数量和严重程度综合决定：

graph LR
    A[扫描结果] --> B{存在 CRITICAL 问题?}
    B -->|是| C[评级 = F]
    B -->|否| D{存在 HIGH 问题?}
    D -->|>= 某个数量| C
    D -->|否| E{存在 MEDIUM 问题?}
    E -->|>= 某个数量| F[评级 = D/C]
    E -->|否| G{存在 LOW 问题?}
    G -->|否| H[评级 = A/B]

扫描规则体系

扫描器内置了多种安全规则，用于检测不同类型的安全问题。每个规则都有唯一的编号和描述。

资料来源：web/src/pages/landing.tsx:98

规则示例

资料来源：web/src/pages/landing.tsx:99-100

审计日志格式

每个 MCP 工具调用都会生成审计日志条目，记录完整的操作上下文和决策信息。

条目 Schema

{
  "entryId": "entry_abc123",
  "timestamp": "2026-03-29T12:34:56.789Z",
  "agentId": "agent_def456",
  "delegationId": "del_xyz789",
  "tool": "github.push_files",
  "parameters": { "owner": "myorg", "repo": "myrepo", "branch": "main" },
  "decision": "allow",
  "matchedRule": 2,
  "constraintsEvaluated": ["rateLimit", "schedule"],
  "durationMs": 3,
  "prevEntryHash": "sha256:e3b0c44298fc1c149afb...",
  "entryHash": "sha256:a665a45920422f9d417e..."
}

字段说明

资料来源：web/src/pages/spec.tsx:1-30

哈希链完整性

审计日志采用哈希链机制确保不可篡改性：

graph LR
    A[Genesis] --> B[entry_1<br/>prev: genesis]
    B --> C[entry_2<br/>prev: hash(entry_1)]
    C --> D[entry_3<br/>prev: hash(entry_2)]
    D --> E[...]

每条审计条目的哈希计算公式：

entryHash = SHA-256(canonicalize(entry with entryHash=null))
// 创世块使用 prevEntryHash: "genesis"

资料来源：web/src/pages/spec.tsx:43-46

委托链与代理追溯

审计日志支持完整的委托链追踪，记录操作在不同代理之间的传递过程。

graph TD
    A[用户发起请求] --> B[主代理 Agent]
    B -->|委托| C[子代理 SubAgent]
    C -->|进一步委托| D[工具 Tool]
    D --> E[审计日志记录]
    E --> F{完整的 delegation_chain}

委托链显示格式

在仪表板中，委托链以可视化方式展示：

Agent A → Agent B → Agent C

每个委托节点显示：

• type: 委托节点类型
• id: 节点唯一标识符

资料来源：web/src/components/dashboard/AuditFeed.tsx:30-50

策略修复方案

针对扫描发现的安全问题，扫描器能够生成对应的 agentsid.json 策略配置文件。

修复配置示例

{
  "version": "1.0",
  "rules": [
    {
      "id": "block-dangerous-tools",
      "action": "deny",
      "conditions": {
        "tool": ["shell.exec", "filesystem.write"]
      }
    }
  ]
}

生成的策略可直接放置于 MCP 服务器仓库根目录，通过代理运行：

npx @agentsid/proxy run --policy agentsid.json -- npx @package/name

资料来源：web/src/pages/hall-of-mcps.tsx:45-60

公开研究报告

扫描器的所有扫描结果和研究报告均公开在 GitHub 上，完全透明。

资料来源：web/src/pages/research.tsx:20-28

MCP 服务器注册表

扫描结果汇总在 MCP 服务器注册表中，提供可搜索的安全评级数据库。

注册表功能

评级徽章

每个扫描过的 MCP 服务器都会生成一个动态徽章，格式如下：

AgentsID [Grade] [评级等级]

徽章会自动随评级变化更新。

资料来源：web/src/pages/registry-server-v2.tsx:60-90

使用流程

1. 扫描流程

sequenceDiagram
    participant 用户
    participant 扫描器
    participant 规则引擎
    participant 评级系统
    participant 注册表
    
    用户->>扫描器: 提交 MCP 服务器包名
    扫描器->>扫描器: 下载并解析代码
    扫描器->>规则引擎: 发送代码片段
    规则引擎->>规则引擎: 匹配安全规则
    规则引擎-->>扫描器: 返回问题列表
    扫描器->>评级系统: 计算安全评级
    评级系统-->>扫描器: 返回 A-F 评级
    扫描器->>注册表: 存储扫描结果
    注册表-->>用户: 显示评级和发现

2. 集成 MCP 服务器

用户可以将扫描器集成到自己的 MCP 服务器中：

// server.mjs
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({
  name: "my-protected-server",
  version: "1.0.0"
});

// 添加工具定义
server.tool(
  'search_notes',
  'Search for notes by keyword',
  { query: z.string() },
  async ({ query }) => {
    // 工具实现
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

资料来源：web/src/pages/guides.tsx:80-120

3. 环境变量配置

技术规格

扫描器配置

# action.yml 配置示例
name: MCP Security Scanner
runs-on: ubuntu-latest
steps:
  - uses: actions/checkout@v3
  - name: Run Scanner
    run: npx @agentsid/scanner
    env:
      AGENTSID_PROJECT_KEY: ${{ secrets.AGENTSID_PROJECT_KEY }}

严重程度分类

资料来源：web/src/pages/registry-v2.tsx:40-60

最佳实践

1. 持续扫描 - 在每次发布前运行扫描器，确保安全性
2. 及时修复 - CRITICAL 和 HIGH 问题应优先处理
3. 使用策略 - 根据扫描建议配置 agentsid.json 策略文件
4. 监控审计 - 定期检查审计日志，发现异常行为
5. 保持更新 - 使用最新版本的扫描器和规则库

相关资源

• 扫描器 NPM 包: npx @agentsid/scanner
• 代理工具: npx @agentsid/proxy
• SDK: @agentsid/sdk
• 安装工具: npx @agentsid/setup@latest

Pitfall Log / 踩坑日志

项目：AgentsID-dev/agentsid

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 agentsid 与安装入口 @agentsid/sdk 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npm install @agentsid/sdk
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | repo=agentsid; install=@agentsid/sdk

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | release_recency=unknown