{ "canonical_name": "AgentsID-dev/agentsid", "compilation_id": "pack_bfa1bee69d7e4125a90eebbdf5b4ac8e", "created_at": "2026-05-15T05:27:04.542709+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm install @agentsid/sdk` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm install @agentsid/sdk", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_c11a2d6f04cc4121a0770950feabb4c6" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_4bd63e3f57745cd54bd87dfb07aafb90", "canonical_name": "AgentsID-dev/agentsid", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/AgentsID-dev/agentsid", "slug": "agentsid", "source_packet_id": "phit_0d896e9dabb5498c815284f3cd30154e", "source_validation_id": "dval_a6b12782ee8948708b9ee92af309b07d" }, "merchandising": { "best_for": "需要安全审查与权限治理能力，并使用 mcp_host的用户", "github_forks": 1, "github_stars": 1, "one_liner_en": "Identity, permissions, and audit for AI agents. The Auth0 for the agent economy.", "one_liner_zh": "Identity, permissions, and audit for AI agents. The Auth0 for the agent economy.", "primary_category": { "category_id": "security-permissions", "confidence": "high", "name_en": "Security & Permissions", "name_zh": "安全审查与权限治理", "reason": "matched_keywords:permission, permissions, auth" }, "target_user": "使用 mcp_host 等宿主 AI 的用户", "title_en": "agentsid", "title_zh": "agentsid 能力包", "visible_tags": [ { "label_en": "MCP Tools", "label_zh": "MCP 工具", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-mcp-tools", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_0d896e9dabb5498c815284f3cd30154e", "page_model": { "artifacts": { "artifact_slug": "agentsid", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm install @agentsid/sdk", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/AgentsID-dev/agentsid#readme", "verified": true } ], "display_tags": [ "MCP 工具", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "eyebrow": "安全审查与权限治理", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要安全审查与权限治理能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Identity, permissions, and audit for AI agents. The Auth0 for the agent economy." }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "mcp_host", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "仓库名 `agentsid` 与安装入口 `@agentsid/sdk` 不完全一致。", "category": "身份坑", "evidence": [ "identity.distribution | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | repo=agentsid; install=@agentsid/sdk" ], "severity": "medium", "suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。", "title": "仓库名和安装名不一致", "user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。", "title": "踩坑日志" }, "snapshot": { "contributors": 4, "forks": 1, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 1 }, "source_url": "https://github.com/AgentsID-dev/agentsid", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Identity, permissions, and audit for AI agents. The Auth0 for the agent economy.", "title": "agentsid 能力包", "trial_prompt": "# agentsid - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agentsid 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想检查一个 AI 工具或 Agent 工作流在权限、提示注入和数据泄露上的风险。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Identity, permissions, and audit for AI agents. The Auth0 for the agent economy. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-api-endpoints：后端 API 接口。围绕“后端 API 接口”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-services：核心业务服务。围绕“核心业务服务”模拟一次用户任务，不展示安装或运行结果。\n5. page-sdk-typescript：TypeScript SDK。围绕“TypeScript SDK”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-api-endpoints\n输入：用户提供的“后端 API 接口”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-services\n输入：用户提供的“核心业务服务”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-sdk-typescript\n输入：用户提供的“TypeScript SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-api-endpoints：Step 3 必须围绕“后端 API 接口”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-services：Step 4 必须围绕“核心业务服务”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-sdk-typescript：Step 5 必须围绕“TypeScript SDK”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/AgentsID-dev/agentsid\n- https://github.com/AgentsID-dev/agentsid#readme\n- README.md\n- PRODUCT.md\n- docs/SECURITY.md\n- ARCHITECTURE.md\n- server/src/app.py\n- server/src/core/security.py\n- server/src/api/agents.py\n- server/src/api/permissions.py\n- server/src/api/approvals.py\n- server/src/api/audit.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agentsid 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。", "items": [], "status": "待发现 Agent 补证", "title": "社区讨论" } ] }, "homepage_card": { "category": "安全审查与权限治理", "desc": "Identity, permissions, and audit for AI agents. The Auth0 for the agent economy.", "effort": "安装已验证", "forks": 1, "icon": "shield", "name": "agentsid 能力包", "risk": "需复核", "slug": "agentsid", "stars": 1, "tags": [ "MCP 工具", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "thumb": "purple", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/AgentsID-dev/agentsid 项目说明书\n\n生成时间：2026-05-13 14:47:22 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [系统架构](#page-architecture)\n- [后端 API 接口](#page-api-endpoints)\n- [核心业务服务](#page-core-services)\n- [数据模型与数据库](#page-data-models)\n- [TypeScript SDK](#page-sdk-typescript)\n- [Python/Ruby/Java SDK](#page-sdk-other-languages)\n- [Web 仪表板](#page-web-dashboard)\n- [Setup CLI 与集成](#page-setup-cli)\n- [MCP 安全扫描器](#page-mcp-scanner)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [核心业务服务](#page-core-services)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx)\n- [web/src/pages/research.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n- [web/src/pages/registry-v2.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-v2.tsx)\n
\n\n# 项目介绍\n\n## 概述\n\nAgentsID 是一个 AI 代理安全与权限控制平台，旨在为 AI 代理（Agent）提供工具调用级别的安全审计、权限管理和行为控制能力。该项目通过扫描 MCP（Model Context Protocol）服务器的安全漏洞，为开发者提供可操作的安全修复建议，并支持细粒度的权限配置和完整的审计日志功能。\n\nAgentsID 的核心价值在于：在不影响 AI 代理正常工作的前提下，通过 200 行 bash 脚本的轻量级 hook 实现对工具调用的实时验证和拦截，确保 AI 代理的操作始终在预设的安全边界内运行。\n\n资料来源：[web/src/pages/landing.tsx:1-50]()\n\n## 核心功能\n\n### 安全扫描与评级系统\n\nAgentsID 提供自动化的 MCP 服务器安全扫描功能，通过对服务器代码的静态分析和运行时行为检测，识别潜在的安全威胁并生成安全评级。\n\n| 评级 | 含义 | 颜色标识 |\n|------|------|----------|\n| A | 优秀 - 无关键问题 | 绿色 |\n| B | 良好 - 少量低风险问题 | 蓝色 |\n| C | 一般 - 存在中等风险 | 黄色 |\n| D | 较差 - 存在高风险问题 | 橙色 |\n| F | 危险 - 存在严重漏洞 | 红色 |\n\n扫描器能够检测多种类型的安全问题，包括但不限于：Shell 执行风险、数据泄露风险、权限提升风险、恶意代码注入等。每个检测结果都附带可操作的修复建议，而非仅仅指出问题所在。\n\n资料来源：[web/src/pages/landing.tsx:50-80]()\n\n### 权限控制与规则引擎\n\nAgentsID 提供基于规则的权限控制系统，开发者可以通过配置规则来控制代理可以调用的工具及其使用条件。系统支持多种约束条件：\n\n| 约束类型 | 说明 | 配置字段 |\n|----------|------|----------|\n| 工具白名单 | 仅允许指定工具 | `tool_pattern` |\n| 参数限制 | 限制工具参数的范围 | `conditions` |\n| 时间窗口 | 限制工具调用的时间范围 | `schedule` |\n| 频率限制 | 限制工具的调用频率 | `rate_limit` |\n| 预算控制 | 限制工具的资源消耗 | `budget` |\n| 序列要求 | 要求在调用前先执行其他工具 | `sequence_requirements` |\n\n规则支持 AND 逻辑组合，允许多个条件同时满足时才允许工具调用执行。\n\n资料来源：[web/src/pages/guides.tsx:1-100]()\n\n### 审计日志与完整性验证\n\nAgentsID 维护所有工具调用的完整审计日志，采用哈希链（Hash Chain）技术确保日志的不可篡改性。\n\n```mermaid\ngraph TD\n A[工具调用请求] --> B{规则匹配引擎}\n B -->|允许| C[执行工具]\n B -->|拒绝| D[拦截请求]\n C --> E[生成审计条目]\n D --> E\n E --> F[SHA-256 哈希]\n F --> G[追加到链式日志]\n G --> H[验证完整性]\n```\n\n审计日志条目包含以下关键信息：\n\n- `entryId`: 日志条目唯一标识\n- `timestamp`: 调用时间戳\n- `agentId`: 代理标识\n- `tool`: 被调用的工具名称\n- `parameters`: 工具参数\n- `decision`: 决策结果（allow/deny）\n- `matchedRule`: 匹配的规则编号\n- `entryHash`: 当前条目的哈希值\n- `prevEntryHash`: 前一条目的哈希值\n\n哈希链的验证公式为：`entryHash = SHA-256(canonicalize(entry with entryHash=null))`，首条记录的前置哈希固定为 \"genesis\"。\n\n资料来源：[web/src/pages/spec.tsx:1-80]()\n\n## 技术架构\n\n### 组件架构\n\nAgentsID 的整体架构由以下核心组件构成：\n\n```mermaid\ngraph TD\n subgraph 前端层\n A[Web Dashboard]\n B[Registry 页面]\n C[文档站点]\n end\n \n subgraph 核心服务\n D[API 服务]\n E[扫描引擎]\n F[规则引擎]\n end\n \n subgraph 数据层\n G[(审计日志数据库)]\n H[(规则配置存储)]\n I[(扫描结果缓存)]\n end\n \n subgraph 客户端集成\n J[AgentsID SDK]\n K[CLI 工具]\n L[MCP 服务器]\n end\n \n A --> D\n B --> E\n C --> D\n J --> D\n K --> D\n L --> F\n F --> G\n E --> I\n D --> H\n```\n\n### SDK 集成方式\n\nAgentsID 提供多种集成方式以满足不同开发场景的需求：\n\n**Node.js SDK 集成**\n\n```bash\nnpm install @agentsid/sdk\n```\n\nSDK 的核心是一个轻量级库，负责与 AgentsID 服务端通信、验证工具调用、记录事件日志并执行权限检查。代理代码保持简洁，无需感知安全控制的实现细节。\n\n**CLI 工具**\n\n通过 `npx agentsid` 命令可执行各项操作：\n\n| 命令 | 功能 |\n|------|------|\n| `init` | 创建新项目并获取 API 密钥 |\n| `register-agent` | 注册新的代理实例 |\n| `audit verify` | 验证审计日志链的完整性 |\n\n资料来源：[web/src/pages/docs.tsx:1-100]()\n\n### MCP 服务器集成\n\nAgentsID 支持与 MCP（Model Context Protocol）服务器的集成。通过在 MCP 服务器配置中添加环境变量即可启用安全控制：\n\n```json\n{\n \"mcpServers\": {\n \"my-notes-server\": {\n \"command\": \"node\",\n \"args\": [\"server.mjs\"],\n \"env\": {\n \"AGENTSID_PROJECT_KEY\": \"aid_proj_your_key_here\",\n \"AGENTSID_AGENT_TOKEN\": \"at_your_token_here\"\n }\n }\n }\n}\n```\n\n支持的 MCP 客户端包括：\n\n- Claude Code\n- Cursor\n- 其他兼容 MCP 协议的客户端\n\n资料来源：[web/src/pages/guides.tsx:100-200]()\n\n## 安全特性\n\n### 数据安全原则\n\nAgentsID 在数据处理方面遵循严格的安全原则：\n\n| 安全措施 | 说明 |\n|----------|------|\n| API 密钥哈希存储 | 仅存储 API 密钥的哈希值，不存储明文 |\n| 审计日志链式存储 | 通过 SHA-256 哈希链确保日志不可篡改 |\n| Cookie 同意机制 | PostHog 分析功能默认关闭，需用户明确同意 |\n| 数据导出功能 | 支持随时导出项目数据、代理配置和审计日志 |\n\n### 研究与透明度\n\nAgentsID 的安全研究完全公开透明：\n\n- 所有扫描器代码在 GitHub 上开源（MIT 许可证）\n- 所有研究论文开放获取\n- 审计日志中的每条拒绝记录都可追溯到对应的规则提交\n- 截至目前已扫描 137,070 台服务器，发现的问题均有详细文档记录\n\n资料来源：[web/src/pages/research.tsx:1-50]()\n\n## 工具注册表\n\nAgentsID 维护一个公开的 MCP 服务器安全评级注册表（Registry），展示各服务器的安全评分和发现的问题类型。\n\n### 评级展示\n\n每个注册服务器的信息包括：\n\n| 字段 | 说明 |\n|------|------|\n| `package` | NPM 包名称 |\n| `version` | 当前版本 |\n| `grade` | 安全评级 (A-F) |\n| `tools` | 工具数量 |\n| `scannedAt` | 最后扫描时间 |\n| `topFindings` | 主要发现的安全问题 |\n| `critical` | 严重问题数量 |\n| `high` | 高风险问题数量 |\n| `medium` | 中等风险问题数量 |\n\n开发者可以通过注册表快速了解某个 MCP 服务器的安全状况，并获取修复建议。\n\n资料来源：[web/src/pages/registry-v2.tsx:1-100]()\n\n## 快速开始\n\n### 安装步骤\n\n1. **创建项目**: 在 agentsid.dev/dashboard 注册账户并创建项目，获取项目密钥\n2. **安装 SDK**: 在项目目录执行 `npm install @agentsid/sdk`\n3. **注册代理**: 使用 SDK 注册代理并获取代理令牌\n4. **配置规则**: 在仪表板中配置工具调用权限规则\n5. **集成验证**: 将 SDK 集成到代理代码中\n\n### 一键安装\n\n```bash\nnpx @agentsid/setup@latest\n```\n\n该命令自动完成项目初始化、SDK 安装和基础配置。\n\n资料来源：[web/src/pages/landing.tsx:80-120]()\n\n## 许可与开源\n\n| 组件 | 许可证 |\n|------|--------|\n| 扫描器 (scanner) | MIT |\n| 服务端 (server) | Source-Available |\n\n所有安全规则和策略配置采用公开透明的方式管理，确保用户对安全控制的完全可见性和可审计性。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [后端 API 接口](#page-api-endpoints), [核心业务服务](#page-core-services)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n- [web/src/pages/privacy.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/privacy.tsx)\n- [web/src/components/dashboard/AuditFeed.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx)\n- [web/src/components/dashboard/OverviewTab.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/OverviewTab.tsx)\n- [web/src/components/dashboard/PermissionAdvancedPanel.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/PermissionAdvancedPanel.tsx)\n- [README.md](https://github.com/AgentsID-dev/agentsid/blob/main/README.md)\n
\n\n# 系统架构\n\n## 1. 概述\n\nAgentsID 是一个为 AI 代理提供身份认证、权限管理和审计功能的平台。其架构设计遵循\"轻量级 hook\"理念，核心是一个约 200 行 Bash 脚本的 hook，无复杂的 SDK 学习曲线，也无需匹配特定语言运行时。\n\n资料来源：[web/src/pages/landing.tsx]()\n\n### 1.1 核心定位\n\n| 维度 | 描述 |\n|------|------|\n| **产品定位** | AI 代理的身份认证与权限管理平台，被称为\"代理经济时代的 Auth0\" |\n| **技术理念** | 开发者友好的轻量级集成，支持任何可执行 Shell 脚本的环境 |\n| **安全承诺** | 不存储原始 API 密钥（仅存哈希）、提供 HMAC 验证和审计日志完整性验证 |\n\n资料来源：[README.md]()\n\n---\n\n## 2. 系统架构图\n\n```mermaid\ngraph TD\n subgraph Client[\"客户端层\"]\n A[AI Agent] --> B[Tool Call]\n B --> C[AgentsID Hook]\n end\n\n subgraph Integration[\"集成方式\"]\n C --> D[Claude Code]\n C --> E[Cursor MCP]\n C --> F[npm SDK]\n G[Python SDK] --> C\n H[Ruby SDK] --> C\n end\n\n subgraph Core[\"核心服务层\"]\n I[API Gateway] --> J[权限引擎]\n I --> K[审计日志服务]\n I --> L[代理注册服务]\n J --> M[规则匹配器]\n end\n\n subgraph Storage[\"数据层\"]\n K --> N[(PostgreSQL)]\n L --> N\n M --> N\n end\n\n subgraph Dashboard[\"管理界面\"]\n O[Web Dashboard] --> N\n P[审计日志面板] --> K\n Q[代理星座图] --> L\n end\n\n C --> I\n```\n\n---\n\n## 3. 核心组件\n\n### 3.1 权限引擎\n\n权限引擎负责在工具调用前进行决策判断。根据 `PermissionAdvancedPanel.tsx` 中的实现，引擎支持以下权限控制维度：\n\n| 权限类型 | 描述 | 配置参数 |\n|---------|------|---------|\n| **基础权限** | 允许/拒绝特定工具调用 | `allowed_tools`, `denied_tools` |\n| **序列要求** | 要求工具调用前必须先调用其他工具 | `sequence_requirements.requires_prior` |\n| **时间窗口** | 限制工具调用的时间窗口 | `sequence_requirements.within_seconds` |\n| **预算控制** | 限制工具调用的最大预算 | `budget.max` |\n\n资料来源：[web/src/components/dashboard/PermissionAdvancedPanel.tsx]()\n\n### 3.2 审计日志服务\n\n审计日志服务记录所有代理操作，采用哈希链技术确保数据完整性。\n\n```mermaid\ngraph LR\n A[工具调用] --> B[记录决策]\n B --> C[生成哈希]\n C --> D[链接到上一条]\n D --> E[存储到数据库]\n```\n\n**审计条目结构：**\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `entryId` | string | 条目唯一标识符，格式为 `entry_abc123` |\n| `timestamp` | ISO8601 | 事件发生时间 |\n| `agentId` | string | 代理定义 ID |\n| `delegationId` | string | 委托链 ID |\n| `tool` | string | 被调用的工具名称 |\n| `parameters` | object | 工具调用参数 |\n| `decision` | enum | 决策结果：`allow` 或 `deny` |\n| `matchedRule` | number | 匹配的规则索引 |\n| `constraintsEvaluated` | array | 评估的约束列表 |\n| `durationMs` | number | 处理耗时（毫秒） |\n| `prevEntryHash` | string | 前一条目的哈希值 |\n| `entryHash` | string | 当前条目的哈希值 |\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 3.3 哈希链完整性\n\n系统使用 SHA-256 算法构建审计日志的哈希链，确保数据不可篡改：\n\n```mermaid\ngraph LR\n A[Genesis Block] --> B[Entry 1 Hash]\n B --> C[Entry 2 Hash]\n C --> D[Entry N Hash]\n```\n\n**哈希计算公式：**\n\n```\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n```\n\n首条记录使用 `prevEntryHash: \"genesis\"` 作为起点。链验证从第二条记录开始，逐条比对哈希值。\n\n资料来源：[web/src/pages/spec.tsx]()\n\n---\n\n## 4. API 架构\n\n### 4.1 API 端点概览\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/v1/audit/verify` | GET | 验证审计日志链的完整性 |\n| `/api/v1/audit/usage` | GET | 获取当前使用量和计划限制 |\n| `/api/v1/projects` | POST | 创建新项目 |\n| `/api/v1/agents` | POST | 注册新代理 |\n\n### 4.2 认证机制\n\nAPI 使用 Bearer Token 认证，Token 格式为 `aid_proj_` 前缀的项目密钥。\n\n```bash\ncurl \"https://api.agentsid.dev/api/v1/audit/verify\" \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 4.3 验证响应示例\n\n**验证成功：**\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"chain_valid\": true\n}\n```\n\n**验证失败（链被破坏）：**\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n---\n\n## 5. SDK 集成架构\n\n### 5.1 多语言支持\n\nAgentsID 提供多种语言的 SDK 和集成方式：\n\n| 平台/语言 | 包管理器 | 安装命令 |\n|----------|---------|---------|\n| Node.js/npm | npm | `npm install @agentsid/sdk` |\n| Python | pip | `pip install agentsid` |\n| Ruby | gem | `gem install agentsid` |\n\n### 5.2 MCP 服务器集成\n\nModel Context Protocol (MCP) 服务器允许将 AgentsID 权限控制集成到 Cursor 等编辑器中。\n\n```json\n{\n \"mcpServers\": {\n \"my-notes-server\": {\n \"command\": \"node\",\n \"args\": [\"server.mjs\"],\n \"env\": {\n \"AGENTSID_PROJECT_KEY\": \"aid_proj_your_key_here\",\n \"AGENTSID_AGENT_TOKEN\": \"at_your_token_here\"\n }\n }\n }\n}\n```\n\n资料来源：[web/src/pages/guides.tsx]()\n\n### 5.3 工具权限检查流程\n\n```mermaid\ngraph TD\n A[Agent 调用工具] --> B{AgentsID Hook 拦截}\n B --> C{检查权限规则}\n C -->|允许| D[执行工具调用]\n C -->|拒绝| E[返回 blocked 响应]\n D --> F[记录审计日志]\n E --> F\n```\n\n代理本身不会意识到被限制，只会收到\"blocked\"响应。\n\n资料来源：[web/src/pages/guides.tsx]()\n\n---\n\n## 6. Dashboard 架构\n\n### 6.1 功能模块\n\n| 模块 | 功能 |\n|------|------|\n| **概览面板** | 显示项目状态、代理数量、近期活动 |\n| **代理管理** | 注册和管理代理，配置权限规则 |\n| **审计日志面板** | 查看完整的操作审计记录 |\n| **代理星座图** | 可视化展示项目中代理的关系网络 |\n\n资料来源：[web/src/components/dashboard/OverviewTab.tsx]()\n\n### 6.2 审计日志面板组件\n\n审计日志面板 (`AuditFeed.tsx`) 支持以下功能：\n\n| 功能 | 描述 |\n|------|------|\n| **条目详情** | 显示每个审计条目的完整信息 |\n| **委托链展示** | 可视化展示委托关系链 |\n| **委托方信息** | 显示操作的委托来源 |\n\n```tsx\n{entry.delegation_chain && (\n
\n
\n Delegation Chain\n
\n
\n {entry.delegation_chain.map((c, i) => (\n \n {i > 0 && →}\n \n {c.type}: {c.id}\n \n \n ))}\n
\n
\n)}\n```\n\n资料来源：[web/src/components/dashboard/AuditFeed.tsx]()\n\n---\n\n## 7. 数据安全架构\n\n### 7.1 安全特性\n\n| 安全措施 | 实现方式 |\n|---------|---------|\n| **API 密钥保护** | 仅存储密钥哈希，不存储明文 |\n| **HMAC 验证** | 验证请求的完整性 |\n| **审计日志完整性** | 使用哈希链防止篡改 |\n| **PostHog 分析** | 默认关闭，需用户主动同意 |\n\n资料来源：[web/src/pages/privacy.tsx]()\n\n### 7.2 数据导出\n\n用户可随时从仪表板导出以下数据：\n\n| 导出类型 | 格式 |\n|---------|------|\n| 项目数据 | JSON |\n| 代理配置 | JSON |\n| 审计日志 | JSON |\n\n资料来源：[web/src/pages/privacy.tsx]()\n\n---\n\n## 8. 系统工作流程\n\n### 8.1 代理注册流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Dashboard\n participant API\n participant Database\n \n User->>Dashboard: 创建项目\n Dashboard->>API: POST /api/v1/projects\n API->>Database: 存储项目信息\n Database-->>API: 返回项目密钥\n API-->>Dashboard: 返回 aid_proj_xxx\n Dashboard-->>User: 显示项目密钥\n \n User->>Dashboard: 注册代理\n Dashboard->>API: POST /api/v1/agents\n API->>Database: 存储代理信息\n Database-->>API: 返回代理令牌\n API-->>Dashboard: 返回 at_yyy\n```\n\n### 8.2 工具调用控制流程\n\n```mermaid\ngraph TD\n A[代理执行工具调用] --> B[SDK/Hook 拦截请求]\n B --> C[调用 AgentsID API]\n C --> D{权限检查}\n D -->|匹配 allow 规则| E[允许执行]\n D -->|匹配 deny 规则| F[阻止执行]\n D -->|无匹配规则| G[使用默认策略]\n E --> H[记录审计日志]\n F --> H\n G --> H\n H --> I[返回结果给代理]\n```\n\n资料来源：[web/src/pages/landing.tsx]()\n\n---\n\n## 9. 技术栈概览\n\n### 9.1 前端技术栈\n\n| 技术 | 用途 |\n|------|------|\n| React | UI 框架 |\n| TypeScript | 类型安全 |\n| Tailwind CSS | 样式框架 |\n| Framer Motion | 动画效果 |\n\n### 9.2 后端技术栈\n\n基于文档推测的架构：\n\n| 组件 | 推测技术 |\n|------|---------|\n| API 服务 | Python/FastAPI |\n| 数据库 | PostgreSQL |\n| 缓存 | Redis (推测) |\n| 认证 | HMAC + Bearer Token |\n\n### 9.3 SDK 技术栈\n\n| SDK | 语言 | 核心依赖 |\n|-----|------|---------|\n| `@agentsid/sdk` | TypeScript/JavaScript | Node.js |\n| `agentsid` | Python | pip |\n| `agentsid` | Ruby | gem |\n\n---\n\n## 10. 总结\n\nAgentsID 采用分层架构设计，核心价值在于为 AI 代理提供轻量级的安全防护层：\n\n1. **接入层**：支持多种集成方式（SDK、CLI、MCP）\n2. **服务层**：权限引擎、审计日志、代理管理\n3. **数据层**：使用 PostgreSQL 存储项目和审计数据\n4. **展示层**：Web Dashboard 提供可视化管理和监控\n\n系统强调开发者体验，通过约 200 行的 Bash hook 实现零学习成本的集成，同时提供企业级的安全保证（HMAC 验证、哈希链完整性）。\n\n---\n\n\n\n## 后端 API 接口\n\n### 相关页面\n\n相关主题：[核心业务服务](#page-core-services), [数据模型与数据库](#page-data-models), [系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [server/src/api/agents.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/agents.py)\n- [server/src/api/permissions.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/permissions.py)\n- [server/src/api/approvals.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/approvals.py)\n- [server/src/api/audit.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/audit.py)\n- [server/src/api/webhooks.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/webhooks.py)\n- [server/src/api/teams.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/teams.py)\n- [docs/API.md](https://github.com/AgentsID-dev/agentsid/blob/main/docs/API.md)\n
\n\n# 后端 API 接口\n\n## 概述\n\nAgentsID 后端 API 是一个基于 RESTful 架构的权限管理与审计平台接口，为 AI Agent 提供身份认证、权限控制、审计日志和委托链验证等功能。该 API 遵循 Model Context Protocol (MCP) 标准，专门用于管理 AI Agent 对外部工具的访问控制。\n\n**核心功能模块：**\n\n| 模块 | 功能描述 | 基础路径 |\n|------|----------|----------|\n| 身份管理 | Agent 注册、更新、令牌管理 | `/api/v1/agents` |\n| 权限控制 | 权限规则设置、查询、验证 | `/api/v1/agents/{agent_id}/permissions` |\n| 审计日志 | 操作记录查询、完整性验证 | `/api/v1/audit` |\n| 审批流程 | 人工审批请求管理 | `/api/v1/approvals` |\n| Webhook | 事件通知回调 | `/api/v1/webhooks` |\n| 团队协作 | 多 Agent 协同管理 | `/api/v1/teams` |\n\n**API 基础地址：** `https://api.agentsid.dev/api/v1`\n\n所有请求需要在 HTTP Header 中携带项目密钥进行认证：\n```\nAuthorization: Bearer aid_proj_xxxxxxxxxxxx\n```\n\n资料来源：[docs/API.md:1-50]()\n\n## 认证与授权机制\n\n### 项目密钥认证\n\n每个项目拥有一个唯一的基础密钥 (`aid_proj_xxx`)，用于所有 API 调用的身份验证。\n\n```bash\ncurl https://api.agentsid.dev/api/v1/agents \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n### Agent 令牌认证\n\nAgent 注册后会获得独立的 Agent Token (`agt_xxx`)，用于特定 Agent 的身份标识和权限验证。\n\n```json\n{\n \"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\",\n \"agent_token\": \"agt_tok_abc123...\",\n \"name\": \"my-agent\",\n \"project_id\": \"proj_a1b2c3d4e5f6\",\n \"issued_at\": \"2026-03-29T00:00:00Z\",\n \"expires_at\": \"2026-04-29T00:00:00Z\",\n \"revoked_at\": null\n}\n```\n\nAgent Token 支持通过 `refresh` 端点重新签发，旧令牌自动失效。\n\n```bash\ncurl -X POST https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv/refresh \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n资料来源：[docs/API.md:100-150]()\n\n### 令牌验证与内省\n\n#### validate_token\n\n验证 Agent 令牌的有效性，可选择性地同时检查特定工具的调用权限。\n\n```python\nresult = await aid.validate_token(token, tool=\"delete_user\", params={\"user_id\": \"u_789\"})\n# 返回: { valid: true, agent_id: \"agt_xxx\", permission: {...} }\n```\n\n返回结构：\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `valid` | boolean | 令牌是否有效 |\n| `reason` | string | 无效时的原因 |\n| `agent_id` | string | 关联的 Agent ID |\n| `project_id` | string | 所属项目 ID |\n| `permission` | object | 当 tool 参数存在时返回权限检查结果 |\n\n#### introspect\n\n完整的令牌内省接口，返回更详细的状态信息。\n\n```python\nresult = await aid.introspect(token, tool=\"send_email\", params={\"recipient\": \"user@example.com\"})\n# 返回: { active: true, agent: {...}, claims: {...}, permissions: [...], delegationChain: [...] }\n```\n\n资料来源：[docs/API.md:200-250]()\n\n## 身份管理接口\n\n### 注册 Agent\n\n**端点：** `POST /api/v1/agents/register`\n\n创建新的 Agent 实例并获取唯一的 Agent Token。\n\n**请求参数：**\n\n| 字段 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `name` | string | 是 | Agent 名称（1-255字符） |\n| `permissions` | array | 否 | 初始权限规则数组 |\n| `metadata` | object | 否 | 附加元数据（最大 10KB） |\n\n```bash\ncurl -X POST https://api.agentsid.dev/api/v1/agents/register \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"claude-notes-agent\",\n \"permissions\": [\n {\"tool_pattern\": \"search_notes\", \"action\": \"allow\"},\n {\"tool_pattern\": \"delete_note\", \"action\": \"deny\"}\n ]\n }'\n```\n\n**响应示例：**\n\n```json\n{\n \"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\",\n \"agent_token\": \"agt_tok_abc123xyz...\",\n \"name\": \"claude-notes-agent\",\n \"created_at\": \"2026-03-25T14:30:00+00:00\"\n}\n```\n\n### 查询 Agent\n\n**端点：** `GET /api/v1/agents/{agent_id}`\n\n获取指定 Agent 的详细信息。\n\n```bash\ncurl https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n**错误码：**\n\n| 状态码 | 含义 |\n|--------|------|\n| 401 | 无效或缺失的 API 密钥 |\n| 404 | Agent 不存在或不属于当前项目 |\n\n### 更新 Agent\n\n**端点：** `PATCH /api/v1/agents/{agent_id}`\n\n更新 Agent 的名称或元数据，不影响令牌和权限。\n\n```bash\ncurl -X PATCH https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"updated-agent-name\"}'\n```\n\n### 刷新令牌\n\n**端点：** `POST /api/v1/agents/{agent_id}/refresh`\n\n签发新令牌并自动撤销所有旧令牌，支持自定义 TTL。\n\n```json\n{\n \"ttl_hours\": 720\n}\n```\n\n资料来源：[docs/API.md:150-200]()\n\n## 权限管理接口\n\n### 设置权限规则\n\n**端点：** `PUT /api/v1/agents/{agent_id}/permissions`\n\n替换指定 Agent 的所有权限规则。\n\n**权限规则结构：**\n\n| 字段 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `tool_pattern` | string | 是 | 工具名称或通配符模式（支持 `*`） |\n| `action` | string | 是 | `\"allow\"` 或 `\"deny\"` |\n| `conditions` | object | 否 | 参数约束（AND 逻辑） |\n| `priority` | integer | 否 | 规则优先级（0-1000，数值越高越先评估） |\n\n```python\nawait aid.set_permissions(\"agt_abc123\", [\n {\"tool_pattern\": \"search_*\", \"action\": \"allow\", \"priority\": 10},\n {\"tool_pattern\": \"delete_*\", \"action\": \"deny\", \"priority\": 20},\n {\n \"tool_pattern\": \"send_email\",\n \"action\": \"allow\",\n \"conditions\": {\"recipient_domain\": \"company.com\"},\n },\n])\n```\n\n**完整规则示例：**\n\n```json\n{\n \"version\": \"1.0\",\n \"agentId\": \"agent_abc123\",\n \"issuedAt\": \"2026-03-29T00:00:00Z\",\n \"expiresAt\": \"2026-04-29T00:00:00Z\",\n \"rules\": [\n {\n \"tool_pattern\": \"github.*\",\n \"action\": \"allow\",\n \"conditions\": {\n \"params\": { \"repo\": \"my-org/*\" },\n \"time_range\": { \"start\": \"09:00\", \"end\": \"17:00\" },\n \"max_rate\": 10\n },\n \"priority\": 100\n }\n ]\n}\n```\n\n资料来源：[server/src/api/permissions.py:1-80]()\n\n### 查询权限规则\n\n**端点：** `GET /api/v1/agents/{agent_id}/permissions`\n\n获取当前 Agent 的所有权限规则。\n\n```python\nrules = await aid.get_permissions(\"agt_abc123\")\n```\n\n### 权限检查\n\n**端点：** `POST /api/v1/check`\n\n检查 Agent 是否被允许调用特定工具。\n\n**请求参数：**\n\n| 字段 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `agent_id` | string | 是 | Agent 标识符 |\n| `tool` | string | 是 | 工具名称 |\n| `params` | object | 否 | 工具调用参数 |\n\n```bash\ncurl -X POST https://api.agentsid.dev/api/v1/check \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\", \"tool\": \"delete_memory\"}'\n```\n\n**响应示例（允许）：**\n\n```json\n{\n \"allowed\": true,\n \"reason\": \"Allowed by rule: save_memory\",\n \"matched_rule\": {\n \"tool_pattern\": \"save_memory\",\n \"action\": \"allow\"\n }\n}\n```\n\n**响应示例（拒绝）：**\n\n```json\n{\n \"allowed\": false,\n \"reason\": \"No matching rule -- default deny\",\n \"matched_rule\": null\n}\n```\n\n### 工具模式匹配\n\n| 模式 | 匹配示例 |\n|------|----------|\n| `*` | 任意单个工具名段 |\n| `**` | 任意工具名（含命名空间） |\n| `github.*` | github 命名空间下的所有工具 |\n| `filesystem.read_file` | 精确匹配单一工具 |\n| `!filesystem.write_*` | 取反——排除写入工具 |\n\n资料来源：[web/src/pages/spec.tsx:1-50]()\n\n## 审计日志接口\n\n### 查询审计日志\n\n**端点：** `GET /api/v1/audit/log`\n\n查询 Agent 的操作审计记录。\n\n**查询参数：**\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `agent_id` | string | 否 | 按 Agent ID 过滤 |\n| `tool` | string | 否 | 按工具名称过滤 |\n| `action` | string | 否 | 按操作类型过滤 |\n| `since` | string | 否 | ISO 8601 时间戳 |\n| `limit` | integer | 否 | 返回条数限制（默认 100） |\n| `offset` | integer | 否 | 分页偏移量 |\n\n```bash\ncurl \"https://api.agentsid.dev/api/v1/audit/log?agent_id=agt_xxx&limit=50\" \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n**响应结构：**\n\n```json\n{\n \"entries\": [\n {\n \"id\": 1,\n \"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\",\n \"tool\": \"send_email\",\n \"action\": \"allow\",\n \"timestamp\": \"2026-03-29T10:15:30Z\",\n \"params\": {\"recipient\": \"user@example.com\"},\n \"delegation_chain\": [\"root_agent\", \"agt_xxx\"]\n }\n ],\n \"total\": 1523,\n \"limit\": 50,\n \"offset\": 0\n}\n```\n\n### 验证完整性\n\n**端点：** `GET /api/v1/audit/verify`\n\n验证审计日志链的完整性，检测是否存在篡改。\n\n```bash\ncurl \"https://api.agentsid.dev/api/v1/audit/verify\" \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n**响应（完整）：**\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"message\": \"Integrity chain verified\"\n}\n```\n\n**响应（链断裂）：**\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n### 使用量统计\n\n**端点：** `GET /api/v1/audit/usage`\n\n获取当前项目的使用量和计划限制。\n\n```json\n{\n \"events_this_month\": 1200,\n \"events_limit\": 10000,\n \"agents_active\": 5,\n \"agents_limit\": 25,\n \"plan\": \"free\"\n}\n```\n\n资料来源：[server/src/api/audit.py:1-100]()\n\n## 审批流程接口\n\n### 创建审批请求\n\n当权限规则配置了审批门 (`approval_gates`) 时，工具调用会被暂停等待人工审批。\n\n**端点：** `POST /api/v1/approvals/request`\n\n```json\n{\n \"agent_id\": \"agt_xxx\",\n \"tool\": \"delete_user\",\n \"params\": {\"user_id\": \"u_789\"},\n \"reason\": \"User requested account deletion\"\n}\n```\n\n### 查询审批状态\n\n**端点：** `GET /api/v1/approvals/{request_id}`\n\n### 审批操作\n\n**端点：** `POST /api/v1/approvals/{request_id}/approve`\n\n或\n\n**端点：** `POST /api/v1/approvals/{request_id}/reject`\n\n```json\n{\n \"approver_id\": \"usr_admin001\",\n \"comment\": \"Verified with IT department\"\n}\n```\n\n资料来源：[server/src/api/approvals.py:1-60]()\n\n## Webhook 通知\n\n### 注册 Webhook\n\n**端点：** `POST /api/v1/webhooks`\n\n```json\n{\n \"url\": \"https://your-server.com/webhook\",\n \"events\": [\"permission_denied\", \"agent_created\", \"approval_requested\"],\n \"secret\": \"whsec_your_signing_secret\"\n}\n```\n\n### Webhook 事件类型\n\n| 事件类型 | 触发时机 |\n|----------|----------|\n| `permission_denied` | 权限检查拒绝 |\n| `permission_allowed` | 权限检查通过 |\n| `agent_created` | 新 Agent 注册 |\n| `agent_token_refreshed` | Agent 令牌刷新 |\n| `approval_requested` | 提交审批请求 |\n| `approval_completed` | 审批完成 |\n\n### Webhook 签名验证\n\nWebhook 请求包含 `X-AgentsID-Signature` 头，使用 HMAC-SHA256 签名：\n\n```python\nimport hmac\nimport hashlib\n\ndef verify_webhook(payload: bytes, signature: str, secret: str) -> bool:\n expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()\n return hmac.compare_digest(f\"sha256={expected}\", signature)\n```\n\n资料来源：[server/src/api/webhooks.py:1-80]()\n\n## 团队协作接口\n\n### 创建团队\n\n**端点：** `POST /api/v1/teams`\n\n```json\n{\n \"name\": \"Data Processing Team\",\n \"description\": \"Handles data ETL pipelines\"\n}\n```\n\n### 添加 Agent 到团队\n\n**端点：** `POST /api/v1/teams/{team_id}/members`\n\n```json\n{\n \"agent_id\": \"agt_xxx\",\n \"role\": \"processor\"\n}\n```\n\n### 团队权限继承\n\n团队成员可以继承团队级别的权限规则，优先级低于个人规则。\n\n```mermaid\ngraph TD\n A[个人规则] --> B{优先级判断}\n C[团队规则] --> B\n D[项目规则] --> B\n B --> E[最终权限]\n \n style A fill:#90EE90\n style C fill:#87CEEB\n style D fill:#FFB6C1\n style E fill:#FFD700\n```\n\n资料来源：[server/src/api/teams.py:1-70]()\n\n## 错误处理\n\n### 错误响应格式\n\n```json\n{\n \"error\": {\n \"code\": \"PERMISSION_DENIED\",\n \"message\": \"Agent agt_xxx is not authorized to call tool delete_user\",\n \"details\": {\n \"agent_id\": \"agt_xxx\",\n \"tool\": \"delete_user\"\n }\n }\n}\n```\n\n### 常见错误码\n\n| 错误码 | HTTP 状态 | 描述 |\n|--------|-----------|------|\n| `INVALID_API_KEY` | 401 | API 密钥无效或缺失 |\n| `AGENT_NOT_FOUND` | 404 | 指定的 Agent 不存在 |\n| `PERMISSION_DENIED` | 403 | 权限检查拒绝 |\n| `INVALID_TOKEN` | 401 | Agent Token 无效或已过期 |\n| `RATE_LIMITED` | 429 | 请求频率超限 |\n| `VALIDATION_ERROR` | 400 | 请求参数验证失败 |\n\n资料来源：[docs/API.md:300-350]()\n\n## SDK 使用示例\n\n### Python SDK\n\n```python\nfrom agentsid import AgentsID\n\nasync def main():\n aid = AgentsID(api_key=\"aid_proj_xR7kM2pQ9...\")\n \n # 注册 Agent\n agent = await aid.register_agent(\"my-agent\", permissions=[\n {\"tool_pattern\": \"search_*\", \"action\": \"allow\"},\n {\"tool_pattern\": \"delete_*\", \"action\": \"deny\"}\n ])\n \n # 检查权限\n result = await aid.check_permission(\n agent[\"agent_id\"], \n \"delete_file\",\n params={\"path\": \"/data/users.csv\"}\n )\n \n if not result[\"allowed\"]:\n print(f\"拒绝原因: {result['reason']}\")\n```\n\n### TypeScript SDK\n\n```typescript\nimport { AgentsID } from '@agentsid/sdk';\n\nconst aid = new AgentsID({ apiKey: 'aid_proj_xR7kM2pQ9...' });\n\n// 验证令牌\nconst validation = await aid.validateToken(token, {\n tool: 'send_email',\n params: { recipient: 'user@example.com' }\n});\n\n// 查询审计日志\nconst logs = await aid.getAuditLog({\n agentId: 'agt_xxx',\n since: '2026-03-01',\n limit: 100\n});\n```\n\n资料来源：[sdk-python/README.md:1-100]()\n\n## 速率限制\n\n| 计划 | 每分钟请求数 | 每小时请求数 |\n|------|-------------|-------------|\n| free | 60 | 1,000 |\n| pro | 300 | 10,000 |\n| enterprise | 1,000 | 无限制 |\n\n速率限制响应头：\n- `X-RateLimit-Limit`: 当前限制\n- `X-RateLimit-Remaining`: 剩余请求数\n- `X-RateLimit-Reset`: 重置时间戳\n\n资料来源：[docs/API.md:350-400]()\n\n## 总结\n\nAgentsID 后端 API 提供了一套完整的 Agent 身份认证与权限管理解决方案，支持：\n\n- **多层级认证**：项目密钥 + Agent Token 双层认证体系\n- **灵活的权限规则**：基于通配符模式的条件约束\n- **完整的审计追溯**：不可篡改的审计日志链\n- **灵活的审批流程**：支持人工介入的审批门机制\n- **事件驱动通知**：Webhook 实时推送关键事件\n\n所有接口均遵循 RESTful 规范，提供一致的错误处理和响应格式，便于与各种 Agent 框架集成。\n\n---\n\n\n\n## 核心业务服务\n\n### 相关页面\n\n相关主题：[后端 API 接口](#page-api-endpoints), [数据模型与数据库](#page-data-models), [项目介绍](#page-introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [server/src/services/identity.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/identity.py)\n- [server/src/services/permission.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/permission.py)\n- [server/src/services/approval.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/approval.py)\n- [server/src/services/audit.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/audit.py)\n- [server/src/services/notifications.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/notifications.py)\n- [server/src/services/subagent_profiles.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/subagent_profiles.py)\n- [server/src/config/subagent_profiles.yaml](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/config/subagent_profiles.yaml)\n
\n\n# 核心业务服务\n\nAgentsID 的核心业务服务层是整个平台的中枢模块，负责管理智能体的身份认证、权限控制、审批流程、审计追踪、通知推送以及子智能体配置等关键功能。该服务层采用模块化架构设计，通过 RESTful API 与前端仪表盘及客户端 SDK 进行交互，为 Agent-MCP（Model Context Protocol）生态系统提供安全可靠的身份治理基础设施。\n\n## 服务架构总览\n\nAgentsID 的核心业务服务由六个主要微服务组成，每个服务专注于特定业务领域，通过标准接口进行通信协作。\n\n```mermaid\ngraph TD\n A[客户端 SDK] --> B[API 网关]\n B --> C[身份服务
identity.py]\n B --> D[权限服务
permission.py]\n B --> E[审批服务
approval.py]\n B --> F[审计服务
audit.py]\n B --> G[通知服务
notifications.py]\n B --> H[子智能体配置服务
subagent_profiles.py]\n \n C --> I[(身份数据库)]\n D --> J[(权限数据库)]\n E --> K[(审批队列)]\n F --> L[(审计日志库)]\n G --> M[(通知通道)]\n H --> N[(配置文件)]\n```\n\n### 服务组件概览表\n\n| 服务名称 | 源文件 | 主要职责 |\n|---------|--------|----------|\n| 身份服务 | `identity.py` | 智能体注册、Token 生成与验证、项目密钥管理 |\n| 权限服务 | `permission.py` | 工具模式匹配、权限规则评估、访问控制决策 |\n| 审批服务 | `approval.py` | 需要审批操作的队列管理、人工审批流程处理 |\n| 审计服务 | `audit.py` | 操作日志记录、哈希链完整性、审计验证 |\n| 通知服务 | `notifications.py` | 审批请求通知、事件告警、用户提醒 |\n| 子智能体配置服务 | `subagent_profiles.py` | 预定义智能体模板、权限配置方案管理 |\n\n## 身份服务\n\n身份服务（Identity Service）是 AgentsID 平台的基础安全组件，负责所有与智能体身份相关的核心操作。该服务维护智能体的注册生命周期，生成不可伪造的身份凭证，并提供完整的验证机制确保每个智能体的合法性。\n\n### 身份令牌体系\n\nAgentsID 采用双层令牌体系进行身份认证：\n\n```mermaid\ngraph LR\n A[项目密钥
aid_proj_xxx] --> C[项目级别认证]\n B[智能体令牌
aid_tok_xxx] --> C\n \n C --> D[智能体身份验证]\n C --> E[权限检查]\n```\n\n| 令牌类型 | 用途 | 作用域 |\n|---------|------|--------|\n| 项目密钥（Project Key） | 标识项目，初始注册时使用 | 项目内所有智能体 |\n| 智能体令牌（Agent Token） | 标识特定智能体身份 | 单个智能体的操作授权 |\n\n智能体注册后返回的令牌包含 HMAC 签名验证所需的元数据，支持快速验证而不暴露实际密钥材料。资料来源：[web/src/pages/guides.tsx]()\n\n### 智能体注册流程\n\n```mermaid\nsequenceDiagram\n participant SDK\n participant API as API 网关\n participant Identity as 身份服务\n participant DB as 数据库\n \n SDK->>API: POST /api/v1/agents/register\n API->>Identity: 创建智能体记录\n Identity->>DB: 存储元数据\n Identity->>Identity: 生成 agent_token\n Identity->>DB: 存储令牌哈希\n DB-->>Identity: 确认写入\n Identity-->>API: 返回 {agent_id, agent_token}\n API-->>SDK: 完成注册\n```\n\n注册接口接收智能体名称和权限配置列表，返回唯一的 `agent_id` 和加密的 `agent_token`。令牌有效期通过 TTL 参数可配置，到期后需重新注册或续期。资料来源：[web/src/pages/guides.tsx]()\n\n### 令牌验证\n\n验证接口 `/api/v1/validate` 执行三项核心检查：\n\n1. **签名验证**：检查 HMAC 签名是否与存储的哈希匹配\n2. **有效期验证**：确认令牌未过期\n3. **撤销状态验证**：检查令牌是否已被主动撤销\n\n验证失败的错误信息采用统一格式，防止信息泄露攻击。资料来源：[web/src/pages/docs.tsx]()\n\n```json\n{\n \"valid\": false,\n \"reason\": \"Token validation failed\"\n}\n```\n\n## 权限服务\n\n权限服务（Permission Service）实现了基于工具模式的细粒度访问控制机制，是 AgentsID 安全模型的核心组件。该服务通过 glob 模式匹配支持灵活的权限规则定义，允许管理员以声明式方式控制智能体可执行的工具范围。\n\n### 权限规则结构\n\n权限策略采用 JSON 格式定义，包含版本、时间戳和规则数组：\n\n```json\n{\n \"version\": \"1.0\",\n \"agentId\": \"agent_abc123\",\n \"issuedAt\": \"2026-03-29T00:00:00Z\",\n \"expiresAt\": \"2026-04-29T00:00:00Z\",\n \"rules\": [\n {\n \"tool_pattern\": \"read_file\",\n \"action\": \"allow\"\n },\n {\n \"tool_pattern\": \"delete_*\",\n \"action\": \"deny\"\n }\n ]\n}\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 工具模式匹配规则\n\n| 模式 | 含义 | 示例匹配 |\n|------|------|----------|\n| `*` | 单个路径段通配符 | `read_file` ✓，`read_file_abc` ✗ |\n| `**` | 多级路径通配符 | `github.*` ✓，`github.repo.read` ✓ |\n| `!` 前缀 | 取反排除 | `!filesystem.write_*` 排除所有写操作 |\n| `?` | 单字符通配 | `file_?` 匹配 `file_a`、`file_b` |\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 权限检查流程\n\n```mermaid\ngraph TD\n A[工具调用请求] --> B[提取工具名称]\n B --> C{匹配权限规则}\n C -->|找到匹配规则| D{规则 action}\n C -->|无匹配规则| E[默认拒绝]\n D -->|allow| F[允许执行]\n D -->|deny| G[拒绝执行]\n D -->|requires_approval| H[进入审批队列]\n \n E --> I[记录审计日志
decision: deny]\n F --> J[记录审计日志
decision: allow]\n G --> J\n H --> K[记录审计日志
decision: pending]\n```\n\n### 权限检查 API\n\n端点 `POST /api/v1/check` 接收智能体 ID 和工具名称，返回权限决策结果：\n\n```json\n// 允许访问\n{\n \"allowed\": true,\n \"reason\": \"Allowed by rule: save_memory\",\n \"matched_rule\": {\n \"tool_pattern\": \"save_memory\",\n \"action\": \"allow\"\n }\n}\n\n// 拒绝访问\n{\n \"allowed\": false,\n \"reason\": \"No matching rule -- default deny\",\n \"matched_rule\": null\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 条件权限\n\n权限规则支持参数级条件限制，可精细化控制智能体仅能操作特定资源：\n\n```json\n{\n \"tool_pattern\": \"read_customer\",\n \"action\": \"allow\",\n \"conditions\": {\n \"params\": { \"customer_id\": \"cust_123\" }\n }\n}\n```\n\n此规则表示仅允许读取 ID 为 `cust_123` 的客户信息，其他客户数据访问将被拒绝。资料来源：[web/src/pages/guides.tsx]()\n\n## 审批服务\n\n审批服务（Approval Service）处理需要人工介入的权限请求。当权限规则指定 `requires_approval` 动作时，对应的工具调用不会立即执行，而是进入审批队列等待授权。\n\n### 审批工作流\n\n```mermaid\ngraph LR\n A[工具调用请求] -->|requires_approval| B[审批队列]\n B --> C{等待审批}\n C -->|批准| D[执行工具]\n C -->|拒绝| E[返回拒绝响应]\n C -->|超时| F[自动拒绝]\n```\n\n### 预定义权限模板\n\n系统提供多种权限模板供快速配置：\n\n| 模板名称 | 允许操作 | 需要审批 | 拒绝操作 |\n|---------|---------|---------|---------|\n| code-assistant | read_file, search_code, list_files | write_file | execute_*, deploy_*, delete_* |\n| notes-agent | search_notes, save_note, list_notes | - | delete_note, admin_* |\n\n资料来源：[web/src/pages/guides.tsx]()\n\n## 审计服务\n\n审计服务（Audit Service）是 AgentsID 安全合规的核心支柱，提供完整、不可篡改的操作记录追踪能力。所有工具调用决策都会被记录在审计日志中，形成可追溯的安全事件链。\n\n### 审计日志结构\n\n每条审计日志条目包含完整的上下文信息：\n\n```json\n{\n \"entryId\": \"entry_abc123\",\n \"timestamp\": \"2026-03-29T12:34:56.789Z\",\n \"agentId\": \"agent_def456\",\n \"delegationId\": \"del_xyz789\",\n \"tool\": \"github.push_files\",\n \"parameters\": { \"owner\": \"myorg\", \"repo\": \"myrepo\", \"branch\": \"main\" },\n \"decision\": \"allow\",\n \"matchedRule\": 2,\n \"constraintsEvaluated\": [\"rateLimit\", \"schedule\"],\n \"durationMs\": 3,\n \"prevEntryHash\": \"sha256:e3b0c44298fc1c149afb...\",\n \"entryHash\": \"sha256:a665a45920422f9d417e...\"\n}\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 哈希链完整性机制\n\n```mermaid\ngraph LR\n A[Genesis] -->|prevEntryHash| B[Entry 1]\n B -->|prevEntryHash| C[Entry 2]\n C -->|prevEntryHash| D[Entry 3]\n \n B -->|SHA-256| A\n C -->|SHA-256| B\n D -->|SHA-256| C\n```\n\n哈希链算法确保任何对历史条目的篡改都会导致后续所有哈希值失效：\n\n```\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n// 首条记录使用 prevEntryHash: \"genesis\"\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 链完整性验证\n\n通过 API `GET /api/v1/audit/verify` 可验证审计链的完整性：\n\n```json\n// 验证通过\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"first_entry_id\": \"entry_001\"\n}\n\n// 链断裂（检测到篡改）\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 仪表盘审计条目展示\n\n前端组件 `AuditFeed.tsx` 展示审计条目的关键字段：\n\n| 显示字段 | 来源字段 | 说明 |\n|---------|---------|------|\n| 决策状态 | `decision` | allow/deny/pending |\n| 工具名称 | `tool` | 被调用的工具标识符 |\n| 智能体 ID | `agent_id` | 发起调用的智能体 |\n| 时间戳 | `created_at` | 操作发生的 UTC 时间 |\n| 委托链 | `delegation_chain` | 多层委托时的完整链路 |\n\n资料来源：[web/src/components/dashboard/AuditFeed.tsx]()\n\n## 通知服务\n\n通知服务（Notification Service）负责向相关人员推送关键事件通知，确保安全操作的及时响应。\n\n### 通知触发场景\n\n| 事件类型 | 通知目标 | 通知方式 |\n|---------|---------|---------|\n| 审批请求 | 审批管理员 | 应用内通知 / 邮件 |\n| 权限拒绝 | 智能体所有者 | SDK 内置响应 |\n| 审计异常告警 | 安全团队 | 系统告警 |\n| 令牌即将过期 | 智能体所有者 | 邮件提醒 |\n\n通知服务与审批服务紧密集成，在审批请求进入队列时自动触发通知流程。\n\n## 子智能体配置服务\n\n子智能体配置服务（Subagent Profiles Service）提供预定义的智能体模板和权限配置方案，简化新智能体的注册和配置流程。\n\n### 配置文件结构\n\n系统通过 YAML 配置文件定义子智能体模板：\n\n```yaml\n# subagent_profiles.yaml\nprofiles:\n - name: \"code-assistant\"\n permissions:\n - tool_pattern: \"read_file\"\n action: \"allow\"\n - tool_pattern: \"write_file\"\n action: \"allow\"\n requires_approval: true\n - name: \"data-analyst\"\n permissions:\n - tool_pattern: \"query_*\"\n action: \"allow\"\n```\n\n资料来源：[server/src/config/subagent_profiles.yaml]()\n\n### 配置文件加载机制\n\n`subagent_profiles.py` 服务负责解析 YAML 配置并将其转换为运行时权限规则，支持热更新而无需重启服务。\n\n## 数据保留与合规\n\n### 隐私数据处理\n\n| 数据类型 | 处理方式 | 保留策略 |\n|---------|---------|---------|\n| 原始 API 密钥 | 不存储，仅存哈希 | 永久（哈希形式） |\n| 智能体令牌 | HMAC 签名验证 | TTL 期限内 |\n| 审计日志 | 哈希链保护 | 根据订阅计划 |\n| 个人身份信息 | 加密存储 | 可导出/删除 |\n\nAgentsID 明确声明**不销售用户数据**，分析工具（PostHog）采用 opt-in 机制。资料来源：[web/src/pages/privacy.tsx]()\n\n### 审计日志保留\n\n| 订阅计划 | 保留期限 | 可导出 |\n|---------|---------|--------|\n| Free | 7 天 | 是（JSON 格式） |\n| Pro | 90 天 | 是 |\n| Enterprise | 自定义 | 是 |\n\n降级套餐时，审计日志会在 30 天内裁剪至新计划保留期限。资料来源：[web/src/pages/terms.tsx]()\n\n## 服务间交互流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant SDK as 客户端 SDK\n participant API as API 网关\n participant Id as 身份服务\n participant Perm as 权限服务\n participant Audit as 审计服务\n participant Notif as 通知服务\n \n User->>SDK: 发起工具调用\n SDK->>API: 验证令牌 + 检查权限\n API->>Id: 验证智能体身份\n Id-->>API: 身份有效\n API->>Perm: 评估权限规则\n Perm-->>API: 权限决策\n API->>Audit: 记录审计日志\n Audit-->>API: 确认写入\n Alt 需要审批\n API->>Notif: 发送审批通知\n User->>API: 审批决策\n end\n API-->>SDK: 返回结果\n SDK-->>User: 操作完成/拒绝\n```\n\n## 总结\n\nAgentsID 的核心业务服务层通过六个协同工作的微服务模块，构建了一个完整、安全、可审计的智能体身份与权限管理平台。身份服务确保每个智能体拥有唯一的可信身份，权限服务提供细粒度的访问控制，审批服务支持人工介入的关键决策点，审计服务提供不可篡改的操作追踪，通知服务保证关键事件的及时响应，子智能体配置服务简化了运维管理流程。所有这些服务共同遵循最小权限原则和隐私保护设计，为 Agent-MCP 生态系统提供企业级的安全保障。\n\n---\n\n\n\n## 数据模型与数据库\n\n### 相关页面\n\n相关主题：[核心业务服务](#page-core-services), [后端 API 接口](#page-api-endpoints)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [server/src/models/models.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/models/models.py)\n- [server/src/core/database.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/core/database.py)\n- [server/alembic/versions/21eca51078a1_add_audit_integrity_hash_chain.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/alembic/versions/21eca51078a1_add_audit_integrity_hash_chain.py)\n- [server/alembic/versions/35a9e5cf497f_add_encrypted_api_key_to_projects.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/alembic/versions/35a9e5cf497f_add_encrypted_api_key_to_projects.py)\n- [server/alembic/versions/a1b2c3d4e5f6_add_teams_and_team_members.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/alembic/versions/a1b2c3d4e5f6_add_teams_and_team_members.py)\n- [server/alembic/versions/c7e9f2b4a1d8_add_agent_type_and_parent.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/alembic/versions/c7e9f2b4a1d8_add_agent_type_and_parent.py)\n
\n\n# 数据模型与数据库\n\n## 概述\n\nAgentsID 的数据模型设计围绕 **Agent（代理）授权管理** 和 **审计追踪** 两个核心功能展开。系统采用关系型数据库（PostgreSQL）存储核心实体，通过 Alembic 管理数据库迁移，确保 schema 版本可控。\n\n主要数据模型包括：\n\n- **Project（项目）**：顶级容器，存储 API 密钥加密值和项目配置\n- **Agent（代理）**：具体的 AI 代理实例，属于某个项目\n- **Team & TeamMember（团队）**：支持多用户协作的团队机制\n- **AuditEntry（审计条目）**：记录所有工具调用决策，形成哈希链保证完整性\n- **Rule（规则）**：定义代理的权限规则和约束条件\n\n## 核心数据模型\n\n### Project（项目）\n\nProject 是系统的顶级容器，每个项目拥有独立的 `project_id` 和加密存储的 API 密钥。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 项目唯一标识 |\n| `api_key_hash` | String | API 密钥的 SHA-256 哈希值 |\n| `encrypted_api_key` | String | 使用 Fernet 对称加密存储的 API 密钥 |\n| `created_at` | DateTime | 创建时间 |\n| `plan` | String | 订阅计划（free/pro 等） |\n\n资料来源：[35a9e5cf497f_add_encrypted_api_key_to_projects.py]() \n\n**安全设计**：系统不存储原始 API 密钥，仅存储哈希值用于验证和加密后的副本用于后台通信。资料来源：[web/src/pages/privacy.tsx]()\n\n### Agent（代理）\n\nAgent 代表一个具体的 AI 代理实例，属于特定项目。代理可以配置权限规则，并通过 agent token 进行身份验证。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | String | 代理唯一标识（如 `agt_` 前缀） |\n| `project_id` | UUID | 所属项目 ID |\n| `name` | String | 代理名称 |\n| `agent_type` | String | 代理类型 |\n| `parent_id` | UUID | 父代理 ID（支持代理层级） |\n| `metadata` | JSON | 元数据字段 |\n| `created_at` | DateTime | 创建时间 |\n| `revoked_at` | DateTime | 撤销时间（null 表示活跃） |\n\n资料来源：[c7e9f2b4a1d8_add_agent_type_and_parent.py]()\n\n**代理层级**：系统支持代理的父子关系，允许构建代理树形结构，适用于复杂的多代理协作场景。\n\n```mermaid\ngraph TD\n P[Project] --> A1[Agent 1]\n P --> A2[Agent 2]\n A1 --> A3[Sub-Agent 1.1]\n A1 --> A4[Sub-Agent 1.2]\n A2 --> A5[Sub-Agent 2.1]\n```\n\n### Team（团队）与 TeamMember（团队成员）\n\n系统支持多用户协作，通过 Team 和 TeamMember 实现成员管理。\n\n| Team 字段 | 类型 | 说明 |\n|-----------|------|------|\n| `id` | UUID | 团队唯一标识 |\n| `name` | String | 团队名称 |\n| `created_at` | DateTime | 创建时间 |\n\n| TeamMember 字段 | 类型 | 说明 |\n|-----------------|------|------|\n| `id` | UUID | 成员唯一标识 |\n| `team_id` | UUID | 所属团队 ID |\n| `user_id` | UUID | 用户 ID |\n| `role` | String | 角色（owner/member 等） |\n| `joined_at` | DateTime | 加入时间 |\n\n资料来源：[a1b2c3d4e5f6_add_teams_and_team_members.py]()\n\n### AuditEntry（审计条目）\n\n审计条目是 AgentsID 安全模型的核心，每条工具调用决策都会生成一个不可变的审计记录。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `entry_id` | String | 条目唯一标识（如 `entry_abc123`） |\n| `agent_id` | String | 执行操作的代理 ID |\n| `delegation_id` | String | 委托链 ID |\n| `tool` | String | 调用的工具名称（如 `github.push_files`） |\n| `parameters` | JSON | 工具调用参数 |\n| `decision` | String | 决策结果（allow/deny） |\n| `matched_rule` | Integer | 匹配的规则序号 |\n| `constraints_evaluated` | JSON | 评估的约束列表 |\n| `duration_ms` | Integer | 处理耗时（毫秒） |\n| `prev_entry_hash` | String | 前一条目哈希 |\n| `entry_hash` | String | 当前条目哈希（SHA-256） |\n| `timestamp` | DateTime | 时间戳 |\n| `delegation_chain` | JSON | 委托链信息 |\n| `delegated_by` | String | 委托方信息 |\n\n资料来源：[21eca51078a1_add_audit_integrity_hash_chain.py]()\n\n## 哈希链完整性机制\n\n### 概述\n\n审计日志采用 **哈希链（Hash Chain）** 技术确保数据完整性。每条审计条目都包含前一条目的哈希值，形成一条不可篡改的链式结构。\n\n### 哈希计算规则\n\n```mermaid\ngraph LR\n A[Genesis Entry
prevEntryHash: null] --> B[Entry 1
entryHash = SHA-256(Entry 1 + null)]\n B --> C[Entry 2
entryHash = SHA-256(Entry 2 + Hash(Entry 1))]\n C --> D[Entry 3
entryHash = SHA-256(Entry 3 + Hash(Entry 2))]\n```\n\n哈希计算公式：\n\n```python\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n# 创世条目的 prevEntryHash 为 \"genesis\"\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 验证流程\n\n系统提供 `/api/v1/audit/verify` 接口验证审计链完整性：\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"chain_length\": 1523,\n \"message\": \"Integrity chain verified\"\n}\n```\n\n验证失败响应：\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 验证算法\n\n```python\nfunction verifyChain(entries: AuditEntry[]): boolean {\n for (let i = 1; i < entries.length; i++) {\n const prev = entries[i - 1]\n const curr = entries[i]\n // 验证 prev.entryHash == curr.prevEntryHash\n }\n}\n```\n\n## 权限规则模型\n\n### 规则结构\n\n每个代理可配置多条权限规则，每条规则定义特定工具的访问策略：\n\n```json\n{\n \"tools\": [\"github.push_files\"],\n \"action\": \"allow\",\n \"constraints\": [\n { \"type\": \"rateLimit\", \"max\": 10, \"windowSeconds\": 3600 },\n { \"type\": \"schedule\", \"daysOfWeek\": [1,2,3,4,5], \"hoursUTC\": [8, 20] }\n ]\n}\n```\n\n### 约束类型\n\n| 约束类型 | 说明 | 示例 |\n|----------|------|------|\n| `rateLimit` | 速率限制 | `{ \"max\": 100, \"windowSeconds\": 3600, \"scope\": \"agent\" }` |\n| `schedule` | 时间调度 | `{ \"daysOfWeek\": [1,2,3,4,5], \"hoursUTC\": [8,17] }` |\n| `budget` | 预算控制 | `{ \"currency\": \"usd\", \"max\": 10.00, \"windowSeconds\": 86400 }` |\n| `sequence` | 顺序约束 | `{ \"requires\": [\"filesystem.read_file\"], \"forbids\": [\"github.push_files\"] }` |\n| `sessionLimit` | 会话限制 | `{ \"max\": 5 }` |\n| `riskScore` | 风险评分 | `{ \"maxScore\": 0.7 }` |\n| `ipAllowlist` | IP 白名单 | `{ \"cidrs\": [\"10.0.0.0/8\", \"192.168.1.0/24\"] }` |\n| `chainDepth` | 链深度 | `{ \"max\": 2 }` |\n| `cooldown` | 冷却时间 | `{ \"seconds\": 300 }` |\n\n资料来源：[web/src/pages/spec.tsx]()\n\n## 数据库架构图\n\n```mermaid\nerDiagram\n PROJECT ||--o{ AGENT : contains\n PROJECT ||--o{ TEAM : owns\n TEAM ||--o{ TEAM_MEMBER : has\n AGENT ||--o{ AUDIT_ENTRY : generates\n AGENT }o--o| AGENT : parent_child\n PROJECT {\n uuid id PK\n string api_key_hash\n string encrypted_api_key\n string plan\n datetime created_at\n }\n AGENT {\n string id PK\n uuid project_id FK\n string name\n string agent_type\n uuid parent_id FK\n json metadata\n datetime created_at\n datetime revoked_at\n }\n AUDIT_ENTRY {\n string entry_id PK\n string agent_id FK\n string delegation_id\n string tool\n json parameters\n string decision\n json constraints_evaluated\n string prev_entry_hash\n string entry_hash\n datetime timestamp\n }\n TEAM {\n uuid id PK\n string name\n datetime created_at\n }\n TEAM_MEMBER {\n uuid id PK\n uuid team_id FK\n uuid user_id\n string role\n datetime joined_at\n }\n```\n\n## API 端点\n\n### 审计相关\n\n| 方法 | 路径 | 说明 |\n|------|------|------|\n| GET | `/api/v1/audit/verify` | 验证审计链完整性 |\n| GET | `/api/v1/audit/usage` | 获取当前使用量和限额 |\n| GET | `/api/v1/audit/entries` | 获取审计条目列表 |\n\n### 代理相关\n\n| 方法 | 路径 | 说明 |\n|------|------|------|\n| GET | `/api/v1/agents` | 列出项目下所有代理 |\n| POST | `/api/v1/agents` | 创建新代理 |\n| GET | `/api/v1/agents/{agent_id}` | 获取代理详情 |\n| PATCH | `/api/v1/agents/{agent_id}` | 更新代理信息 |\n\n资料来源：[web/src/pages/docs.tsx]()\n\n## 数据库连接管理\n\n系统使用 SQLAlchemy 作为 ORM，并通过连接池管理数据库连接：\n\n```python\n# server/src/core/database.py\n# 管理数据库会话生命周期\n# 提供依赖注入机制供 FastAPI 使用\n```\n\n资料来源：[server/src/core/database.py]()\n\n## 数据迁移策略\n\n系统使用 Alembic 管理数据库迁移，所有迁移文件位于 `server/alembic/versions/` 目录。迁移文件命名规范：`{hash}_{description}.py`。\n\n主要迁移历史：\n\n1. `35a9e5cf497f_add_encrypted_api_key_to_projects.py` - 为项目添加加密 API 密钥支持\n2. `21eca51078a1_add_audit_integrity_hash_chain.py` - 添加哈希链完整性字段\n3. `c7e9f2b4a1d8_add_agent_type_and_parent.py` - 添加代理类型和父子关系\n4. `a1b2c3d4e5f6_add_teams_and_team_members.py` - 添加团队功能\n\n## 安全特性\n\n1. **API 密钥存储**：原始密钥仅存储哈希值用于验证，加密副本用于内部通信\n2. **审计不可变性**：哈希链机制确保审计记录不可篡改\n3. **代理撤销**：支持撤销代理令牌，保留审计历史\n4. **委托链追踪**：完整记录工具调用的委托路径\n\n## 总结\n\nAgentsID 的数据模型围绕**授权管理**和**审计合规**两个核心需求设计，通过关系型数据库存储项目、代理、团队和审计记录。哈希链机制提供了审计日志的完整性保证，支持事后验证和合规审查。\n\n---\n\n\n\n## TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python/Ruby/Java SDK](#page-sdk-other-languages), [核心业务服务](#page-core-services), [Setup CLI 与集成](#page-setup-cli)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [sdk-typescript/src/client.ts](https://github.com/AgentsID-dev/agentsid/blob/main/sdk-typescript/src/client.ts)\n- [sdk-typescript/src/middleware.ts](https://github.com/AgentsID-dev/agentsid/blob/main/sdk-typescript/src/middleware.ts)\n- [sdk-typescript/src/errors.ts](https://github.com/AgentsID-dev/agentsid/blob/main/sdk-typescript/src/errors.ts)\n- [sdk-typescript/src/types.ts](https://github.com/AgentsID-dev/agentsid/blob/main/sdk-typescript/src/types.ts)\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n
\n\n# TypeScript SDK\n\n## 概述\n\nAgentsID TypeScript SDK 是一个用于与 AgentsID 平台交互的官方客户端库。它提供了简洁的 API 接口，使开发者能够在其应用程序中集成 AI Agent 身份验证、权限管理和审计功能。\n\n该 SDK 支持创建、查询、更新和删除 Agent 实例，管理 API Token，以及执行工具调用的权限验证。通过统一的接口封装，开发者无需直接处理底层 HTTP 请求和响应解析。\n\n## 核心架构\n\n### 模块结构\n\n```mermaid\ngraph TD\n A[应用程序] --> B[TypeScript SDK]\n B --> C[client.ts
核心客户端]\n B --> D[middleware.ts
中间件组件]\n B --> E[errors.ts
错误处理]\n B --> F[types.ts
类型定义]\n C --> G[REST API
api.agentsid.dev]\n G --> H[数据库层]\n \n style A fill:#e1effe\n style G fill:#fff3cd\n style H fill:#f8d7da\n```\n\n### 客户端初始化\n\nSDK 通过 `AgentsID` 类进行初始化，需要提供项目 API Key 作为认证凭证。\n\n```typescript\nimport { AgentsID } from '@agentsid/sdk';\n\nconst client = new AgentsID({\n apiKey: process.env.AGENTSID_PROJECT_KEY,\n baseUrl: 'https://api.agentsid.dev' // 可选，默认值\n});\n```\n\n初始化参数说明：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `apiKey` | `string` | 是 | 项目 API Key，格式为 `aid_proj_xxx` |\n| `baseUrl` | `string` | 否 | API 基础 URL，默认为 `https://api.agentsid.dev` |\n| `timeout` | `number` | 否 | 请求超时时间（毫秒） |\n| `retry` | `RetryConfig` | 否 | 重试策略配置 |\n\n资料来源：[web/src/pages/docs.tsx:SDK_INIT_TABS]()\n\n## Agent 管理\n\n### 创建 Agent\n\n使用 `registerAgent` 方法创建新的 Agent 实例并获取其首个访问 Token。\n\n```typescript\nconst result = await client.registerAgent({\n name: 'production-agent',\n onBehalfOf: 'proj_xxx',\n permissions: ['read', 'write'],\n ttlHours: 24,\n metadata: { environment: 'production' }\n});\n```\n\n返回值结构：\n\n```typescript\n{\n agent: Agent,\n token: string,\n tokenId: string,\n expiresAt: string\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `agent` | `Agent` | Agent 对象详情 |\n| `token` | `string` | 新签发的访问 Token |\n| `tokenId` | `string` | Token 唯一标识符 |\n| `expiresAt` | `string` | Token 过期时间（ISO 8601 格式） |\n\n### 查询 Agent\n\n#### 获取单个 Agent\n\n```typescript\nconst agent = await client.getAgent('agt_7x9k2mNpQ4rS1tUv');\n```\n\n#### 列出所有 Agent\n\n```typescript\nconst agents = await client.listAgents({\n status: 'active', // 可选：active | revoked | expired\n limit: 50 // 可选：返回数量上限\n});\n```\n\n### 更新 Agent\n\n更新 Agent 的名称或元数据信息：\n\n```typescript\nconst updated = await client.updateAgent('agt_7x9k2mNpQ4rS1tUv', {\n name: 'new-agent-name',\n metadata: { version: '2.0' }\n});\n```\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `agentId` | `string` | 是 | Agent 唯一标识符 |\n| `name` | `string` | 否 | 新名称（1-255 字符） |\n| `metadata` | `object` | 否 | 自定义键值对元数据 |\n\n资料来源：[web/src/pages/docs.tsx:SDK_INIT_TABS]()\n\n## Token 管理\n\n### 刷新 Token\n\n当 Token 即将过期时，可使用 `refreshToken` 方法签发新 Token，同时自动吊销所有旧 Token。\n\n```typescript\nconst result = await client.refreshToken('agt_7x9k2mNpQ4rS1tUv', {\n ttlHours: 48\n});\n```\n\n响应示例：\n\n```json\n{\n \"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\",\n \"token\": \"aid_tok_newtoken...\",\n \"token_id\": \"tok_f6e5d4c3b2a1\",\n \"expires_at\": \"2026-03-27 14:30:00+00:00\"\n}\n```\n\n### Token 验证\n\nSDK 提供 `validate` 方法用于验证 Token 并检查特定操作的权限：\n\n```typescript\nconst result = await client.validate({\n token: 'aid_tok_eyJzdWIiOiJhZ3RfN3g5azJt...',\n tool: 'save_memory',\n params: { category: 'note' }\n});\n```\n\n响应结构：\n\n```typescript\n// Token 有效且有权执行\n{\n valid: true,\n allowed: true,\n matched_rule: {\n tool_pattern: \"save_memory\",\n action: \"allow\"\n }\n}\n\n// Token 无效\n{\n valid: false,\n reason: \"Token validation failed\"\n}\n```\n\n:::info 安全说明\n为防止信息泄露，SDK 对过期 Token、无效签名、已吊销 Token 和项目不匹配的情况返回相同的通用错误消息。\n:::\n\n资料来源：[web/src/pages/docs.tsx:SDK_INIT_TABS]()\n\n## 权限委托\n\n### 创建子 Agent\n\n通过 `delegate` 方法创建具有受限权限的子 Agent：\n\n```typescript\nconst childAgent = await client.delegate({\n parentAgentId: 'agt_parent_xxx',\n name: 'limited-child-agent',\n permissions: ['read-only']\n});\n```\n\n子 Agent 继承父 Agent 的身份，但在权限范围、有效期等维度受到限制。\n\n## 审计功能\n\n### 查询审计日志\n\n```typescript\nconst logs = await client.audit.list({\n agentId: 'agt_xxx',\n limit: 100,\n offset: 0\n});\n```\n\n### 验证完整性链\n\n```typescript\nconst result = await client.audit.verify();\n```\n\n响应示例（链完整）：\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"message\": \"Integrity chain verified\"\n}\n```\n\n响应示例（链损坏）：\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n### 用量查询\n\n```typescript\nconst usage = await client.audit.usage();\n```\n\n响应示例：\n\n```json\n{\n \"events_this_month\": 1200,\n \"events_limit\": 10000,\n \"agents_active\": 5,\n \"agents_limit\": 25,\n \"plan\": \"free\"\n}\n```\n\n## 错误处理\n\nSDK 定义了统一的错误类型体系，便于调用方进行错误捕获和处理：\n\n```typescript\nimport { AgentsIDError, AuthError, ValidationError, NotFoundError } from '@agentsid/sdk';\n\ntry {\n const agent = await client.getAgent('invalid-id');\n} catch (error) {\n if (error instanceof AuthError) {\n // 处理认证错误\n } else if (error instanceof NotFoundError) {\n // 处理资源不存在\n } else if (error instanceof ValidationError) {\n // 处理参数验证错误\n }\n}\n```\n\n| 错误类型 | HTTP 状态码 | 说明 |\n|----------|-------------|------|\n| `AgentsIDError` | - | 基础错误类 |\n| `AuthError` | 401 | API Key 无效或缺失 |\n| `NotFoundError` | 404 | Agent 或资源不存在 |\n| `ValidationError` | 400 | 请求参数验证失败 |\n| `RateLimitError` | 429 | 请求频率超限 |\n| `ServerError` | 500+ | 服务器内部错误 |\n\n资料来源：[sdk-typescript/src/errors.ts]()\n\n## 中间件集成\n\n### MCP 服务器中间件\n\nSDK 提供中间件组件，用于保护 MCP（Model Context Protocol）服务器的工具调用：\n\n```typescript\nimport { createAgentsIDMiddleware } from '@agentsid/sdk/middleware';\n\nconst middleware = createAgentsIDMiddleware({\n projectKey: process.env.AGENTSID_PROJECT_KEY,\n agentToken: process.env.AGENTSID_AGENT_TOKEN,\n url: 'https://api.agentsid.dev'\n});\n```\n\n完整集成示例：\n\n```typescript\n// server.mjs\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { createAgentsIDMiddleware } from '@agentsid/sdk/middleware';\n\nconst AGENTSID_PROJECT_KEY = process.env.AGENTSID_PROJECT_KEY;\nconst AGENTSID_AGENT_TOKEN = process.env.AGENTSID_AGENT_TOKEN;\n\nconst validateToolCall = async (tool, params) => {\n const response = await fetch(`${AGENTSID_URL}/api/v1/validate`, {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${AGENTSID_PROJECT_KEY}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n token: AGENTSID_AGENT_TOKEN,\n tool,\n params\n })\n });\n \n const result = await response.json();\n if (!result.valid || !result.permission?.allowed) {\n throw new Error(`Tool ${tool} is not allowed`);\n }\n return result;\n};\n\n// MCP 服务器工具定义\nconst server = new McpServer({ name: 'protected-notes', version: '1.0.0' });\n\nserver.tool(\n 'save_memory',\n 'Save a note to memory',\n { category: z.enum(['note', 'preference']), content: z.string() },\n async ({ category, content }) => {\n await validateToolCall('save_memory', { category, content });\n // 执行实际的保存逻辑\n return { success: true };\n }\n);\n```\n\n### 工具验证流程\n\n```mermaid\nsequenceDiagram\n participant A as AI Agent\n participant M as MCP Server\n participant S as AgentsID SDK\n participant P as AgentsID API\n \n A->>M: 调用工具 save_memory\n M->>S: validate(tool, params)\n S->>P: POST /api/v1/validate\n P->>P: 验证 Token 和权限规则\n alt 允许执行\n P-->>S: { valid: true, allowed: true }\n S-->>M: 验证通过\n M->>M: 执行工具逻辑\n M-->>A: 返回结果\n else 拒绝执行\n P-->>S: { valid: true, allowed: false }\n S-->>M: 抛出错误\n M-->>A: 权限拒绝错误\n end\n```\n\n资料来源：[web/src/pages/guides.tsx:validateToolCall]()\n\n## 类型定义\n\nSDK 导出完整的 TypeScript 类型定义，确保开发时的类型安全和自动补全支持。\n\n### 核心类型\n\n```typescript\n// Agent 实例\ninterface Agent {\n id: string;\n name: string;\n project_id: string;\n status: 'active' | 'revoked' | 'expired';\n created_at: string;\n revoked_at: string | null;\n metadata: Record;\n}\n\n// Token 信息\ninterface Token {\n id: string;\n agent_id: string;\n created_at: string;\n expires_at: string;\n revoked_at: string | null;\n}\n\n// 审计日志条目\ninterface AuditEntry {\n id: string;\n agent_id: string;\n tool: string;\n params: Record;\n result: 'allow' | 'deny';\n reason: string;\n created_at: string;\n}\n\n// 用量信息\ninterface UsageStats {\n events_this_month: number;\n events_limit: number;\n agents_active: number;\n agents_limit: number;\n plan: string;\n}\n```\n\n资料来源：[sdk-typescript/src/types.ts]()\n\n## 环境变量\n\n| 变量名 | 说明 | 必填 |\n|--------|------|------|\n| `AGENTSID_PROJECT_KEY` | 项目 API Key | 是 |\n| `AGENTSID_AGENT_TOKEN` | Agent 访问 Token | 是 |\n| `AGENTSID_URL` | API 地址（默认：https://api.agentsid.dev） | 否 |\n\n## 最佳实践\n\n### 1. 安全存储凭证\n\n始终通过环境变量加载 API Key，避免硬编码在源代码中：\n\n```typescript\n// ✅ 推荐\nconst client = new AgentsID({\n apiKey: process.env.AGENTSID_PROJECT_KEY\n});\n\n// ❌ 不推荐\nconst client = new AgentsID({\n apiKey: 'aid_proj_xxx'\n});\n```\n\n### 2. Token 轮换\n\n建议定期调用 `refreshToken` 方法轮换 Token，以降低 Token 泄露的风险：\n\n```typescript\n// 每 23 小时轮换一次（Token 有效期 24 小时）\nsetInterval(async () => {\n await client.refreshToken(agentId, { ttlHours: 24 });\n}, 23 * 60 * 60 * 1000);\n```\n\n### 3. 错误重试\n\n对于网络错误和 5xx 服务器错误，建议实现指数退避重试策略：\n\n```typescript\nconst client = new AgentsID({\n apiKey: process.env.AGENTSID_PROJECT_KEY,\n retry: {\n maxAttempts: 3,\n backoff: 'exponential',\n initialDelay: 1000\n }\n});\n```\n\n### 4. 审计日志持久化\n\n将审计事件异步写入持久化存储，以便进行合规审计和问题排查：\n\n```typescript\nclient.audit.on('entry', async (entry) => {\n await db.auditLogs.insert(entry);\n});\n```\n\n## 安装\n\n```bash\nnpm install @agentsid/sdk\n```\n\n或使用其他包管理器：\n\n```bash\nyarn add @agentsid/sdk\npnpm add @agentsid/sdk\n```\n\n## 版本要求\n\n- Node.js >= 18.0.0\n- TypeScript >= 5.0.0（类型定义已内置）\n\n## 相关资源\n\n- [API 参考文档](./docs.md)\n- [快速入门指南](./guides.md)\n- [SDK 源码仓库](https://github.com/AgentsID-dev/agentsid/tree/main/sdk-typescript)\n- [GitHub Issues](https://github.com/AgentsID-dev/agentsid/issues)\n\n---\n\n\n\n## Python/Ruby/Java SDK\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#page-sdk-typescript), [核心业务服务](#page-core-services)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx) (SDK API 参考文档)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx) (SDK 集成指南)\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx) (产品首页)\n- [web/src/pages/privacy.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/privacy.tsx) (隐私政策)\n- [web/src/pages/research.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx) (研究页面)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx) (规范文档)\n- [web/src/components/dashboard/AuditFeed.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx) (审计日志组件)\n- [web/src/components/dashboard/PoliciesTab.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/PoliciesTab.tsx) (策略管理组件)\n- [web/src/pages/registry-server-v2.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-server-v2.tsx) (注册表页面)\n\n> **注意**：以下 SDK 的实际源码文件（sdk-python、sdk-ruby、sdk-java）在当前上下文检索结果中未包含。以下文档内容基于 web 前端中展示的 SDK 集成模式和 API 文档构建。\n
\n\n# Python/Ruby/Java SDK\n\n## 概述\n\nAgentsID 提供多语言 SDK（Python、Ruby、Java），为开发者提供统一的接口来集成 Agent 身份验证、权限管理和审计日志功能。这些 SDK 封装了与 AgentsID API 的通信逻辑，开发者无需直接处理 HTTP 请求和响应解析。\n\n### 核心功能\n\n| 功能模块 | 说明 |\n|---------|------|\n| Agent 注册 | 创建新 Agent 并获取访问令牌 |\n| 权限验证 | 在工具调用前验证权限策略 |\n| 令牌管理 | 刷新和撤销 Agent 令牌 |\n| 审计日志 | 记录并验证操作完整性 |\n| 元数据管理 | 存储和管理 Agent 关联数据 |\n\n### 设计理念\n\nAgentsID 的 SDK 设计遵循以下原则：\n\n- **轻量化**：核心功能简洁，不引入不必要的依赖\n- **跨平台一致性**：各语言 SDK 提供统一的 API 接口\n- **零学习成本**：通过中间件模式快速集成到现有系统\n\n资料来源：[web/src/pages/landing.tsx]()\n\n## SDK 初始化\n\n### 基础配置\n\n所有 SDK 都需要使用项目密钥（Project Key）进行初始化。项目密钥可在 [agentsid.dev/dashboard](https://agentsid.dev/dashboard) 创建项目后获取。\n\n```bash\n# 获取项目密钥后初始化\nProject ID: proj_a1b2c3d4e5f6\nAPI Key: aid_proj_xR7kM2pQ9...\nPlan: free\n```\n\n资料来源：[web/src/pages/guides.tsx]()\n\n### 初始化参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|-----|------|\n| `projectKey` | string | 是 | 项目 API 密钥，格式为 `aid_proj_xxx` |\n| `agentToken` | string | 否 | Agent 令牌，用于自动验证 |\n| `apiBaseUrl` | string | 否 | API 基础 URL，默认为 `https://api.agentsid.dev` |\n\n### 环境变量配置\n\n建议通过环境变量配置敏感信息：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `AGENTSID_PROJECT_KEY` | 项目 API 密钥 |\n| `AGENTSID_AGENT_TOKEN` | Agent 访问令牌 |\n| `AGENTSID_API_BASE_URL` | API 基础 URL（可选） |\n\n资料来源：[web/src/pages/guides.tsx]()\n\n## Agent 方法\n\n### 方法列表\n\n| 方法 | 参数 | 返回值 | 说明 |\n|-----|------|-------|------|\n| `registerAgent` | name, onBehalfOf, permissions?, ttlHours?, metadata? | { agent, token, tokenId, expiresAt } | 创建新 Agent 并颁发首个令牌 |\n| `getAgent` | agentId | Agent | 根据 ID 获取 Agent 详情 |\n| `listAgents` | status?, limit? | Agent[] | 列出 Agent，支持状态筛选 |\n| `updateAgent` | agentId, name?, metadata? | Agent | 更新 Agent 名称或元数据 |\n| `refreshToken` | agentId, ttlHours? | { token, tokenId, expiresAt } | 颁发新令牌并吊销所有旧令牌 |\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 创建 Agent\n\n```python\n# Python SDK 示例\nagent = client.register_agent(\n name=\"research-assistant\",\n on_behalf_of=\"user_abc\",\n permissions=[\n {\"tool_pattern\": \"search_memories\", \"action\": \"allow\"},\n {\"tool_pattern\": \"save_memory\", \"action\": \"allow\"}\n ],\n ttl_hours=24,\n metadata={\"framework\": \"langchain\"}\n)\n```\n\n```ruby\n# Ruby SDK 示例\nagent = client.register_agent(\n name: \"research-assistant\",\n on_behalf_of: \"user_abc\",\n permissions: [\n { tool_pattern: \"search_memories\", action: \"allow\" },\n { tool_pattern: \"save_memory\", action: \"allow\" }\n ],\n ttl_hours: 24,\n metadata: { framework: \"langchain\" }\n)\n```\n\n```java\n// Java SDK 示例\nAgentRegistration agent = client.registerAgent(\n \"research-assistant\",\n \"user_abc\",\n Arrays.asList(\n new Permission(\"search_memories\", \"allow\"),\n new Permission(\"save_memory\", \"allow\")\n ),\n 24,\n Map.of(\"framework\", \"langchain\")\n);\n```\n\n### 权限规则\n\n权限规则使用通配符模式匹配工具名称：\n\n| 模式 | 含义 |\n|-----|------|\n| `*` | 匹配所有工具 |\n| `admin_*` | 匹配所有以 admin_ 开头的工具 |\n| `github.*` | 匹配所有 github. 开头的工具 |\n| `search_notes` | 精确匹配指定工具 |\n\n资料来源：[web/src/pages/guides.tsx]()\n\n## 中间件集成\n\n### MCP 服务器集成\n\nSDK 提供与 Model Context Protocol (MCP) 服务器的集成中间件，适用于 Claude Code、Cursor 等 AI 编程工具的扩展开发。\n\n```javascript\n// MCP 服务器验证中间件示例\nconst AGENTSID_PROJECT_KEY = process.env.AGENTSID_PROJECT_KEY;\nconst AGENTSID_AGENT_TOKEN = process.env.AGENTSID_AGENT_TOKEN;\n\nasync function validateToolCall(toolName, args) {\n const response = await fetch(\"https://api.agentsid.dev/api/v1/verify\", {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n \"Authorization\": `Bearer ${AGENTSID_PROJECT_KEY}`,\n \"X-Agent-Token\": AGENTSID_AGENT_TOKEN\n },\n body: JSON.stringify({ tool: toolName, parameters: args })\n });\n \n const result = await response.json();\n \n if (!result.allowed) {\n throw new Error(`Tool ${toolName} denied: ${result.reason}`);\n }\n \n return result;\n}\n```\n\n资料来源：[web/src/pages/guides.tsx]()\n\n### 中间件架构\n\n```mermaid\ngraph TD\n A[Agent Tool Call] --> B[MCP Middleware]\n B --> C{validateToolCall}\n C -->|请求验证| D[AgentsID API]\n D -->|allowed: true| E[执行工具]\n D -->|allowed: false| F[拒绝执行]\n E --> G[记录审计日志]\n G --> H[返回结果]\n F --> I[返回错误]\n```\n\n### 中间件组件\n\n| 组件 | 语言 | 职责 |\n|-----|------|------|\n| `MCPMiddleware` | Java | MCP 协议请求拦截和验证 |\n| `Middleware` | Python/Ruby | 工具调用拦截和权限校验 |\n\n## 审计日志\n\n### 日志条目结构\n\n```json\n{\n \"entryId\": \"entry_abc123\",\n \"timestamp\": \"2026-03-29T12:34:56.789Z\",\n \"agentId\": \"agent_def456\",\n \"delegationId\": \"del_xyz789\",\n \"tool\": \"github.push_files\",\n \"parameters\": { \"owner\": \"myorg\", \"repo\": \"myrepo\", \"branch\": \"main\" },\n \"decision\": \"allow\",\n \"matchedRule\": 2,\n \"constraintsEvaluated\": [\"rateLimit\", \"schedule\"],\n \"durationMs\": 3,\n \"prevEntryHash\": \"sha256:e3b0c44298fc1c149afb...\",\n \"entryHash\": \"sha256:a665a45920422f9d417e...\"\n}\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 哈希链完整性\n\n每个审计条目都包含前一个条目的哈希值，形成不可篡改的链式结构：\n\n```python\n# 哈希链计算\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n# 首条目使用 prevEntryHash: \"genesis\"\n```\n\n```python\ndef verify_chain(entries: list[AuditEntry]) -> bool:\n \"\"\"验证审计日志链完整性\"\"\"\n for i in range(1, len(entries)):\n prev = entries[i - 1]\n curr = entries[i]\n if curr.prev_entry_hash != prev.entry_hash:\n return False\n return True\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 链验证结果\n\n| 状态 | 说明 |\n|-----|------|\n| `verified: true` | 链完整性验证通过 |\n| `verified: false` | 链完整性被破坏，可能存在篡改 |\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"chain_intact\": true\n}\n```\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n## 策略管理\n\n### 规则结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `tool_pattern` | string | 工具名称模式（支持通配符） |\n| `action` | string | `allow` 或 `deny` |\n| `priority` | number | 优先级，数值越高越优先（可选） |\n| `requires_approval` | boolean | 是否需要人工审批（可选） |\n\n### 规则评估\n\n```python\n# 规则评估伪代码\ndef evaluate_rule(tool_name, rules):\n # 按优先级降序排序\n sorted_rules = sorted(rules, key=lambda r: r.priority, reverse=True)\n \n for rule in sorted_rules:\n if matches_pattern(tool_name, rule.tool_pattern):\n return rule.action\n \n # 默认拒绝\n return \"deny\"\n```\n\n### 默认行为\n\n> No rules defined. All tool calls will be denied by default.\n\n资料来源：[web/src/components/dashboard/PoliciesTab.tsx]()\n\n## 错误处理\n\n### HTTP 错误码\n\n| 错误码 | 原因 |\n|-------|------|\n| `401` | 无效或缺失的 API 密钥 |\n| `404` | Agent 不存在或不属于当前项目 |\n| `429` | 请求频率超限 |\n| `500` | 服务器内部错误 |\n\n```bash\n# curl 示例\ncurl https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n## 套餐与限制\n\n### 使用量查询\n\n```bash\ncurl \"https://api.agentsid.dev/api/v1/audit/usage\" \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n### 响应格式\n\n```json\n{\n \"events_this_month\": 1200,\n \"events_limit\": 10000,\n \"agents_active\": 5,\n \"agents_limit\": 25,\n \"plan\": \"free\"\n}\n```\n\n### 套餐限制\n\n| 套餐 | 事件限制 | Agent 数量 |\n|-----|---------|-----------|\n| free | 10,000/月 | 25 |\n| pro | 自定义 | 自定义 |\n\n资料来源：[web/src/pages/docs.tsx]()\n\n## 快速开始\n\n### 1. 安装 SDK\n\n```bash\n# Python\npip install agentsid\n\n# Ruby\ngem install agentsid\n\n# Java (Maven)\n\n dev.agentsid\n agentsid-sdk\n 1.0.0\n\n```\n\n### 2. 初始化客户端\n\n```python\nfrom agentsid import Client\n\nclient = Client(\n project_key=\"aid_proj_xR7kM2pQ9...\",\n agent_token=\"at_your_token_here\"\n)\n```\n\n### 3. 注册 Agent\n\n```python\nagent = client.register_agent(\n name=\"my-agent\",\n on_behalf_of=\"user_123\",\n permissions=[\n {\"tool_pattern\": \"read_*\", \"action\": \"allow\"},\n {\"tool_pattern\": \"write_*\", \"action\": \"deny\"}\n ]\n)\nprint(f\"Agent ID: {agent['agent_id']}\")\n```\n\n### 4. 验证工具调用\n\n```python\nresult = client.verify_tool(\n tool=\"read_user_data\",\n parameters={\"user_id\": \"123\"}\n)\n\nif result.allowed:\n # 执行工具逻辑\n pass\nelse:\n print(f\"Denied: {result.reason}\")\n```\n\n## 数据隐私\n\nAgentsID SDK 在处理数据时遵循严格的隐私保护原则：\n\n| 原则 | 说明 |\n|-----|------|\n| 不存储原始 API 密钥 | 仅存储哈希值用于验证 |\n| 不出售用户数据 | 明确承诺永不销售用户数据 |\n| 分析功能可选 | PostHog 分析功能默认关闭，需用户同意 |\n\n> \"We never store raw API keys. Only hashes.\"\n> \"We do not sell your data. Ever.\"\n\n资料来源：[web/src/pages/privacy.tsx]()\n\n## 相关资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方文档 | [agentsid.dev/docs](https://agentsid.dev/docs) |\n| SDK 仓库 | [github.com/AgentsID-dev/agentsid](https://github.com/AgentsID-dev/agentsid) |\n| 扫描器 | [github.com/AgentsID-dev/agentsid-scanner](https://github.com/AgentsID-dev/agentsid-scanner) |\n| NPM 包 | `npx @agentsid/scanner` |\n\n资料来源：[web/src/pages/research.tsx](), [web/src/pages/landing.tsx]()\n\n---\n\n\n\n## Web 仪表板\n\n### 相关页面\n\n相关主题：[后端 API 接口](#page-api-endpoints), [Setup CLI 与集成](#page-setup-cli)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/App.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/App.tsx)\n- [web/src/pages/dashboard.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/dashboard.tsx)\n- [web/src/components/dashboard/AgentCards.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AgentCards.tsx)\n- [web/src/components/dashboard/PermissionEditor.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/PermissionEditor.tsx)\n- [web/src/components/dashboard/TeamTab.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/TeamTab.tsx)\n- [web/src/components/dashboard/RegisterAgentModal.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/RegisterAgentModal.tsx)\n- [web/src/components/dashboard/AuditFeed.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx)\n- [web/README.md](https://github.com/AgentsID-dev/agentsid/blob/main/web/README.md)\n
\n\n# Web 仪表板\n\n## 概述\n\nWeb 仪表板是 AgentsID 平台的核心管理界面，为用户提供统一的控制台来管理 AI Agent、权限配置、团队协作和审计日志。仪表板采用 React + TypeScript 构建，使用 Tailwind CSS 进行样式管理，通过 Supabase 实现身份认证和后端数据交互。\n\n仪表板的主要功能包括：\n\n- **Agent 管理**：注册、查看、更新和撤销 AI Agent\n- **权限编辑**：通过可视化界面配置 Agent 的工具调用权限规则\n- **团队管理**：支持多用户协作，管理团队成员和权限委派\n- **审计日志**：实时查看所有 Agent 的工具调用记录和 Allow/Deny 决策\n- **注册表浏览**：查看公开的工具包安全评分和详细信息\n\n## 页面路由架构\n\n仪表板通过 React Router 进行路由管理，所有路由均位于 `/dashboard` 路径下。 资料来源：[web/src/App.tsx]()\n\n```mermaid\ngraph TD\n A[App 根组件] --> B[路由配置]\n B --> C[/]\n B --> D[/dashboard]\n B --> E[/registry]\n B --> F[/registry/:registrySlug]\n \n D --> G[仪表板页面]\n G --> H[概览视图]\n G --> I[Agents 标签页]\n G --> J[Audit 标签页]\n G --> K[Team 标签页]\n \n H --> L[AgentCards 组件]\n I --> M[AgentCards 组件]\n I --> N[PermissionEditor 组件]\n I --> O[RegisterAgentModal 组件]\n J --> P[AuditFeed 组件]\n K --> Q[TeamTab 组件]\n```\n\n## 核心组件结构\n\n### AgentCards 组件\n\nAgentCards 是仪表板中用于展示 Agent 列表的核心组件。该组件负责渲染所有已注册的 Agent 卡片，提供快速概览和快捷操作入口。\n\n**主要功能**：\n\n- 展示 Agent 基本信息（名称、状态、创建时间）\n- 显示 Agent 的当前权限规则数量\n- 提供快捷操作按钮（查看详情、编辑权限）\n- 支持状态徽章显示（Active/Expired/Pending）\n\n**数据结构**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | string | Agent 唯一标识符（格式：`agt_xxx`） |\n| name | string | Agent 名称 |\n| status | 'active' \\| 'expired' \\| 'pending' | Agent 状态 |\n| permissions | PermissionRule[] | 权限规则数组 |\n| created_at | string | 创建时间戳 |\n| onBehalfOf | string | 委派方标识 |\n\n资料来源：[web/src/components/dashboard/AgentCards.tsx]()\n\n### PermissionEditor 组件\n\nPermissionEditor 是权限配置的可视化编辑器，允许用户通过图形界面管理 Agent 的工具调用规则。\n\n**权限规则格式**：\n\n```typescript\ninterface PermissionRule {\n tool_pattern: string; // 支持通配符，如 \"search_*\"\n action: 'allow' | 'deny';\n}\n```\n\n**操作模式**：\n\n- **Allow 模式**：允许匹配规则的工具调用\n- **Deny 模式**：阻止匹配规则的工具调用，Agent 会收到 \"blocked\" 响应但不会察觉限制存在\n\n**配置示例**：\n\n```json\n[\n { \"tool_pattern\": \"search_*\", \"action\": \"allow\" },\n { \"tool_pattern\": \"read_*\", \"action\": \"allow\" },\n { \"tool_pattern\": \"delete_*\", \"action\": \"deny\" },\n { \"tool_pattern\": \"admin_*\", \"action\": \"deny\" }\n]\n```\n\n资料来源：[web/src/components/dashboard/PermissionEditor.tsx]()\n资料来源：[web/src/pages/guides.tsx]()\n\n### AuditFeed 组件\n\nAuditFeed 组件提供实时审计日志流，显示所有 Agent 的工具调用记录和权限决策。\n\n**审计条目包含的信息**：\n\n| 字段 | 说明 |\n|------|------|\n| tool_name | 被调用的工具名称 |\n| decision | Allow 或 Deny 决策结果 |\n| agent_id | 执行操作的 Agent ID |\n| created_at | 调用时间戳 |\n| delegation_chain | 权限委派链（如果涉及多层委派） |\n| delegated_by | 直接授权方标识 |\n\n**委派链展示**：\n\n当 Agent 通过委派机制运行时，AuditFeed 会显示完整的委派链路：\n\n```\nuser:usr_xxx → agent:agt_parent → agent:agt_child\n```\n\n资料来源：[web/src/components/dashboard/AuditFeed.tsx]()\n\n### TeamTab 组件\n\nTeamTab 组件用于团队协作管理，支持多成员和权限委派功能。\n\n**团队管理功能**：\n\n- 查看团队成员列表\n- 管理成员角色和权限\n- 配置跨成员的 Agent 委派关系\n- 审计团队范围内的所有操作\n\n资料来源：[web/src/components/dashboard/TeamTab.tsx]()\n\n### RegisterAgentModal 组件\n\nRegisterAgentModal 是注册新 Agent 的模态框组件，提供完整的 Agent 创建流程。\n\n**注册表单字段**：\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| name | 是 | Agent 名称 |\n| onBehalfOf | 是 | 代表谁创建（用户或上级 Agent） |\n| permissions | 否 | 初始权限规则配置 |\n| ttlHours | 否 | Token 有效期（小时），默认 24 小时 |\n| metadata | 否 | 额外元数据 |\n\n**响应数据格式**：\n\n```typescript\ninterface RegisterResponse {\n agent: Agent;\n token: string;\n tokenId: string;\n expiresAt: string;\n}\n```\n\n资料来源：[web/src/components/dashboard/RegisterAgentModal.tsx]()\n\n## 页面布局结构\n\n仪表板页面采用顶部导航 + 侧边栏 + 主内容区的经典布局：\n\n```mermaid\ngraph TD\n A[顶部导航栏] --> A1[项目选择器]\n A --> A2[用户菜单]\n A --> A3[API Key 显示]\n \n B[主内容区] --> B1[概览视图]\n B --> B2[标签页容器]\n \n B2 --> B3[Agents 标签]\n B2 --> B4[Audit 标签]\n B2 --> B5[Team 标签]\n \n C[底部页脚] --> C1[文档链接]\n C --> C2[使用条款]\n C --> C3[隐私政策]\n```\n\n### 底部页脚链接\n\n| 链接 | 路径 | 说明 |\n|------|------|------|\n| 文档 | /docs | SDK 和 API 文档 |\n| 指南 | /guides | 使用教程和最佳实践 |\n| 仪表板 | /dashboard | 当前页面 |\n| GitHub | github.com/AgentsID-dev/agentsid | 源码仓库 |\n| 使用条款 | /terms | 服务条款 |\n| 隐私政策 | /privacy | 隐私政策声明 |\n\n资料来源：[web/src/pages/dashboard.tsx]()\n\n## API 集成\n\n### 认证机制\n\n仪表板通过 Supabase Auth 进行用户身份认证。所有 API 请求需要在 Authorization header 中携带 Bearer Token。\n\n### 核心 API 端点\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/api/v1/agents` | GET | 获取 Agent 列表 |\n| `/api/v1/agents` | POST | 注册新 Agent |\n| `/api/v1/agents/:id` | GET | 获取单个 Agent 详情 |\n| `/api/v1/agents/:id` | PATCH | 更新 Agent 配置 |\n| `/api/v1/agents/:id/refresh` | POST | 刷新 Agent Token |\n| `/api/v1/agents/delegate` | POST | 创建子 Agent 并委派权限 |\n| `/api/v1/audit` | GET | 获取审计日志 |\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### API Key 管理\n\n仪表板在顶部导航栏显示用户的 API Key，用于服务端验证。API Key 格式为 `aid_proj_xxx`。\n\n## 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| React 18 | UI 框架 |\n| TypeScript | 类型安全 |\n| Tailwind CSS | 样式管理 |\n| React Router | 路由管理 |\n| Supabase | 身份认证和数据库 |\n| Framer Motion | 动画效果 |\n\n资料来源：[web/README.md]()\n\n## 状态管理\n\n仪表板使用 React Hooks 进行本地状态管理，主要状态包括：\n\n- `activeTab`：当前激活的标签页（'agents' | 'audit' | 'team'）\n- `registerModalOpen`：注册 Agent 模态框开关状态\n- `apiKey`：用户 API Key 凭证\n- `agents`：Agent 列表数据\n- `auditEntries`：审计日志条目\n\n```mermaid\ngraph LR\n A[用户交互] --> B[状态更新]\n B --> C[UI 重新渲染]\n C --> D[API 调用]\n D --> E[数据获取]\n E --> F[状态同步]\n F --> C\n```\n\n## 响应式设计\n\n仪表板采用移动优先的响应式设计策略：\n\n| 断点 | 布局调整 |\n|------|----------|\n| sm (640px+) | 单列布局扩展为双列网格 |\n| md (768px+) | 显示审计日志的时间戳全格式 |\n| lg (1024px+) | 侧边栏固定定位 |\n\n## 与其他模块的关联\n\n### 注册表模块\n\n仪表板提供跳转到公开注册表的入口，用户可以浏览已扫描的工具包安全评分：\n\n```\n/registry # 注册表首页\n/registry/:slug # 特定工具包详情页\n```\n\n### 落地页\n\n注册表详情页包含安全评分展示，包括等级徽章（GradeStamp）和关键发现列表。 资料来源：[web/src/pages/registry-server-v2.tsx]()\n\n## 安全考虑\n\n1. **API Key 保护**：仅显示 API Key 哈希值，不存储原始密钥\n2. **权限验证**：所有操作通过服务端 JWT 验证\n3. **审计追踪**：所有工具调用和权限决策均被记录\n4. **Cookie 同意**：PostHog 分析采用 Opt-in 机制 资料来源：[web/src/pages/privacy.tsx]()\n\n## 开发构建\n\n项目使用 Vite 作为构建工具：\n\n```bash\n# 安装依赖\nnpm install\n\n# 开发模式\nnpm run dev\n\n# 生产构建\nnpm run build\n\n# 预览构建结果\nnpm run preview\n```\n\n资料来源：[web/README.md]()\n\n---\n\n\n\n## Setup CLI 与集成\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#page-sdk-typescript), [Web 仪表板](#page-web-dashboard)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n- [web/src/pages/research.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n
\n\n# Setup CLI 与集成\n\n## 概述\n\nAgentsID 提供一套完整的命令行工具和 IDE 集成方案，使开发者能够在各种开发环境中快速部署 AI Agent 安全控制。Setup CLI 是整个系统的入口点，负责项目初始化、Agent 注册以及与主流 IDE 的无缝集成。 资料来源：[web/src/pages/landing.tsx:1-50]()\n\n该 CLI 采用零配置设计理念，核心安装命令为：\n\n```bash\nnpx @agentsid/setup@latest\n```\n\n安装后会获得一个轻量级的 hook（仅 200 行 Bash 脚本），无需学习复杂的 SDK 或匹配特定的运行时环境。 资料来源：[web/src/pages/landing.tsx:1-50]()\n\n## 核心安装流程\n\n### Step 1: 创建项目目录\n\n```bash\nmkdir my-protected-server && cd my-protected-server\n```\n\n### Step 2: 初始化项目\n\n```bash\nnpm init -y\nnpm install @modelcontextprotocol\n```\n\n### Step 3: 安装 SDK\n\n```bash\nnpm install @agentsid/sdk\n```\n\n安装完成后，系统会输出类似以下信息：\n\n```\nadded {s.tools + 12} packages\n\n── AgentsID ──────────────────────────────\n {s.package} [ {grade} · {GRADE_NAMES[grade]} ]\n {critical} CRITICAL · {high} HIGH · {medium} MEDIUM\n\n agentsid.dev/registry/{registrySlug}\n──────────────────────────────────────────\n```\n\n资料来源：[web/src/pages/registry-server-v2.tsx:1-50]()\n\n## 支持的 IDE 集成\n\nAgentsID 支持与主流 AI 编程工具的深度集成，每个集成都通过 MCP（Model Context Protocol）协议实现。\n\n### Claude Code 集成\n\nClaude Code 是 Anthropic 提供的命令行工具，AgentsID 通过 MCP Server 为其提供安全控制。\n\n集成步骤：\n\n1. 在 [agentsid.dev/dashboard](https://agentsid.dev/dashboard) 创建账户并注册 Agent\n2. 创建 MCP Server 文件 `server.mjs`\n3. 安装依赖：`npm init -y && npm install @modelcontextprotocol/sdk zod`\n4. 配置环境变量 `AGENTSID_PROJECT_KEY` 和 `AGENTSID_AGENT_TOKEN`\n\nMCP Server 配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"my-notes-server\": {\n \"command\": \"node\",\n \"args\": [\"server.mjs\"],\n \"env\": {\n \"AGENTSID_PROJECT_KEY\": \"aid_proj_your_key_here\",\n \"AGENTSID_AGENT_TOKEN\": \"at_your_token_here\"\n }\n }\n }\n}\n```\n\n资料来源：[web/src/pages/guides.tsx:1-80]()\n\n### Cursor 集成\n\nCursor IDE 支持通过 `.cursor/mcp.json` 配置文件加载自定义 MCP Server。AgentsID 为 Cursor 提供即插即用的集成方案。\n\n配置方式与 Claude Code 类似，通过修改 `.cursor/mcp.json` 添加 AgentsID Server 即可。\n\n### Codex 集成\n\nOpenAI Codex 的集成采用相同架构，确保在各种 AI 辅助编程场景下都能获得一致的安全保护。\n\n### Gemini 集成\n\nGoogle Gemini 的集成支持扩展 AgentsID 的保护范围到更多 AI 平台。\n\n## 预设配置\n\nAgentsID 提供多种预设配置，满足不同安全级别的需求。\n\n| 预设名称 | 适用场景 | 权限级别 |\n|---------|---------|---------|\n| lockdown | 高安全要求环境 | 最严格，仅基础工具 |\n| security-team | 安全团队使用 | 中等，允许安全相关操作 |\n| developer | 开发环境 | 宽松，支持日常开发任务 |\n\n### 权限控制示例\n\n以下示例展示如何通过预设限制 Agent 的工具访问权限：\n\n```tsx\nsearch_notes, \"Search notes by keyword\", ],\n [save_note, \"Create a new note\", ],\n [list_notes, \"List all notes\", ],\n [delete_note, \"Delete a note by ID\", ],\n [admin_reset, \"Wipe all data\", ],\n ]}\n/>\n```\n\nAgent 拥有全部五个工具的访问能力，但 AgentsID 会拦截任何尝试使用 `delete_note` 或 `admin_reset` 的请求。Agent 本身不会察觉到限制——它只会收到一个\"blocked\"响应并继续执行后续操作。 资料来源：[web/src/pages/guides.tsx:1-50]()\n\n## 安全扫描与分级\n\n### 评分系统\n\nAgentsID 对集成工具进行自动安全扫描，采用 A-F 等级评分系统：\n\n| 等级 | 含义 | 颜色标识 |\n|-----|------|---------|\n| A | 优秀 | 绿色 |\n| B | 良好 | 蓝色 |\n| C | 一般 | 黄色 |\n| D | 较差 | 橙色 |\n| F | 危险 | 红色 |\n\n扫描器已开源，可在 GitHub 获取：https://github.com/AgentsID-dev/agentsid-scanner\n\n执行命令：`npx @agentsid/scanner` 资料来源：[web/src/pages/research.tsx:1-50]()\n\n### 扫描统计\n\n截至目前，AgentsID 已扫描超过 **137,070** 个服务器，发现并记录了大量安全问题。所有研究均可在 GitHub 上公开访问。\n\n## 配置参数\n\n### SDK 初始化\n\n```typescript\n// SDK 初始化\nconst client = new AgentsIDClient({\n projectKey: 'aid_proj_xxx',\n agentToken: 'at_xxx'\n});\n```\n\n### Agent 方法\n\n| 方法 | 参数 | 返回值 | 说明 |\n|-----|------|-------|------|\n| `registerAgent` | name, onBehalfOf, permissions?, ttlHours?, metadata? | { agent, token, tokenId, expiresAt } | 创建新 Agent 并颁发首个 Token |\n| `getAgent` | agentId | Agent | 根据 ID 获取 Agent 详情 |\n| `listAgents` | status?, limit? | Agent[] | 列出 Agent，支持按状态筛选 |\n| `updateAgent` | agentId, name?, metadata? | Agent | 更新 Agent 名称或元数据 |\n| `refreshToken` | agentId, ttlHours? | { token, tokenId, expiresAt } | 颁发新 Token，自动撤销旧 Token |\n\n资料来源：[web/src/pages/docs.tsx:1-80]()\n\n### 权限配置\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| `tool` | string | 工具名称，如 `github.push_files` |\n| `parameters` | object | 工具调用参数 |\n| `decision` | string | 决策结果：`allow` 或 `deny` |\n| `matchedRule` | number | 匹配的规则编号 |\n| `constraintsEvaluated` | string[] | 评估的约束条件 |\n| `durationMs` | number | 处理耗时（毫秒） |\n\n审计日志采用 SHA-256 哈希链确保完整性：\n\n```javascript\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n// 首条记录使用 prevEntryHash: \"genesis\"\n```\n\n资料来源：[web/src/pages/spec.tsx:1-80]()\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 Setup CLI] --> B[创建项目]\n B --> C[注册 Agent]\n C --> D[配置 IDE 集成]\n D --> E{选择预设}\n E -->|lockdown| F[高安全模式]\n E -->|security-team| G[安全团队模式]\n E -->|developer| H[开发者模式]\n F --> I[部署 MCP Server]\n G --> I\n H --> I\n I --> J[Agent 执行工具调用]\n J --> K{Hook 拦截请求}\n K -->|允许| L[执行工具]\n K -->|拒绝| M[记录审计日志]\n M --> N[返回 blocked 响应]\n```\n\n## 后续步骤\n\n完成 Setup CLI 与集成配置后，建议进行以下操作：\n\n1. **验证配置**：使用 `agentsid verify` 命令确认集成正常工作\n2. **查看审计日志**：通过仪表板审查所有工具调用记录\n3. **调整权限**：根据实际需求精细化配置权限规则\n4. **定期扫描**：在每次发布前运行安全扫描，确保新工具符合安全标准\n\n安装命令复制功能已内置于界面中，点击按钮即可快速复制 `npx @agentsid/setup@latest` 命令。 资料来源：[web/src/pages/landing.tsx:1-50]()\n\n---\n\n\n\n## MCP 安全扫描器\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/research.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n- [web/src/pages/hall-of-mcps.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/hall-of-mcps.tsx)\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n- [web/src/pages/registry-server-v2.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-server-v2.tsx)\n- [web/src/pages/registry-v2.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-v2.tsx)\n- [web/src/components/dashboard/AuditFeed.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n\n
\n\n# MCP 安全扫描器\n\nMCP 安全扫描器（AgentsID Scanner）是 AgentsID 平台的核心安全组件，负责对 MCP（Model Context Protocol）服务器进行自动化安全评估、漏洞检测和风险评级。该扫描器已扫描超过 **137,070** 个 MCP 服务器发现，并生成公开的安全研究报告。\n\n## 核心功能概述\n\nMCP 安全扫描器的主要职责包括：\n\n1. **静态代码分析** - 解析 MCP 服务器代码，识别潜在的安全风险\n2. **工具权限评估** - 检测 MCP 工具的能力边界和权限范围\n3. **安全评级生成** - 基于规则引擎为每个 MCP 服务器分配 A-F 安全等级\n4. **问题分类统计** - 按 CRITICAL、HIGH、MEDIUM、LOW 四个严重级别归类发现问题\n5. **修复建议生成** - 针对发现的问题提供具体的 agentsid.json 策略配置\n\n资料来源：[web/src/pages/research.tsx:8](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[MCP 服务器代码] --> B[扫描器引擎]\n B --> C[规则匹配引擎]\n C --> D{风险评估}\n D -->|CRITICAL| E[阻止级问题]\n D -->|HIGH| F[警告级问题]\n D -->|MEDIUM| G[注意级问题]\n D -->|LOW| H[信息级问题]\n E --> I[安全评级 F]\n F --> I\n G --> J[安全评级 C-D]\n H --> J\n I --> K[公开研究报告]\n J --> K\n```\n\n## 安全评级体系\n\n扫描器使用 A-F 六级安全评级系统，评级基于发现的问题数量和严重程度。\n\n| 评级 | 含义 | 颜色代码 | 风险等级 |\n|------|------|----------|----------|\n| A | 优秀 | #22c55e (绿色) | 极低风险 |\n| B | 良好 | #3b82f6 (蓝色) | 低风险 |\n| C | 中等 | #eab308 (黄色) | 中等风险 |\n| D | 较差 | #f97316 (橙色) | 较高风险 |\n| E | 差 | #ef4444 (红色) | 高风险 |\n| F | 危险 | #dc2626 (深红) | 极高风险 |\n\n资料来源：[web/src/pages/landing.tsx:88-105](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n\n### 评级判定规则\n\n评级由扫描发现的问题数量和严重程度综合决定：\n\n```mermaid\ngraph LR\n A[扫描结果] --> B{存在 CRITICAL 问题?}\n B -->|是| C[评级 = F]\n B -->|否| D{存在 HIGH 问题?}\n D -->|>= 某个数量| C\n D -->|否| E{存在 MEDIUM 问题?}\n E -->|>= 某个数量| F[评级 = D/C]\n E -->|否| G{存在 LOW 问题?}\n G -->|否| H[评级 = A/B]\n```\n\n## 扫描规则体系\n\n扫描器内置了多种安全规则，用于检测不同类型的安全问题。每个规则都有唯一的编号和描述。\n\n资料来源：[web/src/pages/landing.tsx:98](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n\n### 规则示例\n\n| 规则编号 | 规则类型 | 描述 | 处置方式 |\n|----------|----------|------|----------|\n| rule #104 | block shell | 阻止危险的 shell 操作 | 阻止执行 |\n\n资料来源：[web/src/pages/landing.tsx:99-100](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n\n## 审计日志格式\n\n每个 MCP 工具调用都会生成审计日志条目，记录完整的操作上下文和决策信息。\n\n### 条目 Schema\n\n```json\n{\n \"entryId\": \"entry_abc123\",\n \"timestamp\": \"2026-03-29T12:34:56.789Z\",\n \"agentId\": \"agent_def456\",\n \"delegationId\": \"del_xyz789\",\n \"tool\": \"github.push_files\",\n \"parameters\": { \"owner\": \"myorg\", \"repo\": \"myrepo\", \"branch\": \"main\" },\n \"decision\": \"allow\",\n \"matchedRule\": 2,\n \"constraintsEvaluated\": [\"rateLimit\", \"schedule\"],\n \"durationMs\": 3,\n \"prevEntryHash\": \"sha256:e3b0c44298fc1c149afb...\",\n \"entryHash\": \"sha256:a665a45920422f9d417e...\"\n}\n```\n\n### 字段说明\n\n| 字段名 | 类型 | 描述 |\n|--------|------|------|\n| entryId | string | 审计条目唯一标识符 |\n| timestamp | ISO8601 | 操作时间戳 |\n| agentId | string | 执行操作的代理 ID |\n| delegationId | string | 委托链 ID |\n| tool | string | 被调用的 MCP 工具名称 |\n| parameters | object | 工具调用参数 |\n| decision | enum | allow/deny 决策结果 |\n| matchedRule | number | 匹配的规则编号 |\n| constraintsEvaluated | string[] | 评估的约束条件 |\n| durationMs | number | 处理耗时（毫秒） |\n| prevEntryHash | string | 前一条目哈希值 |\n| entryHash | string | 当前条目哈希值 |\n\n资料来源：[web/src/pages/spec.tsx:1-30](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n\n### 哈希链完整性\n\n审计日志采用哈希链机制确保不可篡改性：\n\n```mermaid\ngraph LR\n A[Genesis] --> B[entry_1
prev: genesis]\n B --> C[entry_2
prev: hash(entry_1)]\n C --> D[entry_3
prev: hash(entry_2)]\n D --> E[...]\n```\n\n每条审计条目的哈希计算公式：\n\n```\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n// 创世块使用 prevEntryHash: \"genesis\"\n```\n\n资料来源：[web/src/pages/spec.tsx:43-46](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n\n## 委托链与代理追溯\n\n审计日志支持完整的委托链追踪，记录操作在不同代理之间的传递过程。\n\n```mermaid\ngraph TD\n A[用户发起请求] --> B[主代理 Agent]\n B -->|委托| C[子代理 SubAgent]\n C -->|进一步委托| D[工具 Tool]\n D --> E[审计日志记录]\n E --> F{完整的 delegation_chain}\n```\n\n### 委托链显示格式\n\n在仪表板中，委托链以可视化方式展示：\n\n```\nAgent A → Agent B → Agent C\n```\n\n每个委托节点显示：\n- **type**: 委托节点类型\n- **id**: 节点唯一标识符\n\n资料来源：[web/src/components/dashboard/AuditFeed.tsx:30-50](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx)\n\n## 策略修复方案\n\n针对扫描发现的安全问题，扫描器能够生成对应的 agentsid.json 策略配置文件。\n\n### 修复配置示例\n\n```json\n{\n \"version\": \"1.0\",\n \"rules\": [\n {\n \"id\": \"block-dangerous-tools\",\n \"action\": \"deny\",\n \"conditions\": {\n \"tool\": [\"shell.exec\", \"filesystem.write\"]\n }\n }\n ]\n}\n```\n\n生成的策略可直接放置于 MCP 服务器仓库根目录，通过代理运行：\n\n```bash\nnpx @agentsid/proxy run --policy agentsid.json -- npx @package/name\n```\n\n资料来源：[web/src/pages/hall-of-mcps.tsx:45-60](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/hall-of-mcps.tsx)\n\n## 公开研究报告\n\n扫描器的所有扫描结果和研究报告均公开在 GitHub 上，完全透明。\n\n| 资源 | 链接 |\n|------|------|\n| 扫描器源代码 | github.com/AgentsID-dev/agentsid-scanner |\n| NPM 包 | npx @agentsid/scanner |\n| 研究论文 | 公开可访问 |\n\n资料来源：[web/src/pages/research.tsx:20-28](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n\n## MCP 服务器注册表\n\n扫描结果汇总在 MCP 服务器注册表中，提供可搜索的安全评级数据库。\n\n### 注册表功能\n\n| 功能 | 描述 |\n|------|------|\n| 筛选 | 按评级、严重程度筛选 |\n| 搜索 | 按包名搜索特定服务器 |\n| 分页 | 大型数据集分页浏览 |\n| 详情 | 查看具体发现和修复建议 |\n| 徽章 | 生成可嵌入的安全评级徽章 |\n\n### 评级徽章\n\n每个扫描过的 MCP 服务器都会生成一个动态徽章，格式如下：\n\n```\nAgentsID [Grade] [评级等级]\n```\n\n徽章会自动随评级变化更新。\n\n资料来源：[web/src/pages/registry-server-v2.tsx:60-90](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-server-v2.tsx)\n\n## 使用流程\n\n### 1. 扫描流程\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant 扫描器\n participant 规则引擎\n participant 评级系统\n participant 注册表\n \n 用户->>扫描器: 提交 MCP 服务器包名\n 扫描器->>扫描器: 下载并解析代码\n 扫描器->>规则引擎: 发送代码片段\n 规则引擎->>规则引擎: 匹配安全规则\n 规则引擎-->>扫描器: 返回问题列表\n 扫描器->>评级系统: 计算安全评级\n 评级系统-->>扫描器: 返回 A-F 评级\n 扫描器->>注册表: 存储扫描结果\n 注册表-->>用户: 显示评级和发现\n```\n\n### 2. 集成 MCP 服务器\n\n用户可以将扫描器集成到自己的 MCP 服务器中：\n\n```javascript\n// server.mjs\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\n\nconst server = new McpServer({\n name: \"my-protected-server\",\n version: \"1.0.0\"\n});\n\n// 添加工具定义\nserver.tool(\n 'search_notes',\n 'Search for notes by keyword',\n { query: z.string() },\n async ({ query }) => {\n // 工具实现\n }\n);\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n资料来源：[web/src/pages/guides.tsx:80-120](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n\n### 3. 环境变量配置\n\n| 变量名 | 描述 | 示例值 |\n|--------|------|--------|\n| AGENTSID_PROJECT_KEY | 项目唯一标识符 | aid_proj_abc123... |\n| AGENTSID_AGENT_TOKEN | 代理访问令牌 | at_xyz789... |\n| AGENTSID_URL | API 地址（可选） | https://agentsid.dev |\n\n## 技术规格\n\n### 扫描器配置\n\n```yaml\n# action.yml 配置示例\nname: MCP Security Scanner\nruns-on: ubuntu-latest\nsteps:\n - uses: actions/checkout@v3\n - name: Run Scanner\n run: npx @agentsid/scanner\n env:\n AGENTSID_PROJECT_KEY: ${{ secrets.AGENTSID_PROJECT_KEY }}\n```\n\n### 严重程度分类\n\n| 级别 | 中文含义 | 典型问题 |\n|------|----------|----------|\n| CRITICAL | 严重 | 任意代码执行、未授权文件访问 |\n| HIGH | 高危 | shell 命令注入、凭据泄露 |\n| MEDIUM | 中危 | 权限过度、信息泄露 |\n| LOW | 低危 | 配置不当、日志敏感信息 |\n\n资料来源：[web/src/pages/registry-v2.tsx:40-60](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-v2.tsx)\n\n## 最佳实践\n\n1. **持续扫描** - 在每次发布前运行扫描器，确保安全性\n2. **及时修复** - CRITICAL 和 HIGH 问题应优先处理\n3. **使用策略** - 根据扫描建议配置 agentsid.json 策略文件\n4. **监控审计** - 定期检查审计日志，发现异常行为\n5. **保持更新** - 使用最新版本的扫描器和规则库\n\n## 相关资源\n\n- **扫描器 NPM 包**: `npx @agentsid/scanner`\n- **代理工具**: `npx @agentsid/proxy`\n- **SDK**: `@agentsid/sdk`\n- **安装工具**: `npx @agentsid/setup@latest`\n\n---\n\n*本页面内容基于 AgentsID 仓库中的公开源码生成，最后更新于 2024 年。*\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：AgentsID-dev/agentsid\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `agentsid` 与安装入口 `@agentsid/sdk` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @agentsid/sdk`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | repo=agentsid; install=@agentsid/sdk\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | release_recency=unknown\n\n\n", "markdown_key": "agentsid", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:1192733106", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/AgentsID-dev/agentsid" }, { "evidence_id": "art_5e45862d5409489a8dbf277a3f18ab14", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/AgentsID-dev/agentsid#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "agentsid 说明书", "toc": [ "https://github.com/AgentsID-dev/agentsid 项目说明书", "目录", "项目介绍", "概述", "核心功能", "技术架构", "安全特性", "工具注册表", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": false, "repo_commit": null, "repo_inspection_error": null, "repo_inspection_files": [], "repo_inspection_verified": false, "review_reasons": [ "community_discussion_evidence_below_public_threshold" ], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# agentsid - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 agentsid 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install @agentsid/sdk # TypeScript` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install agentsid # Python` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx agentsid init # Create project, get API key` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx agentsid register-agent --name \"bot\" # Register an agent` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx agentsid list-agents # List all agents` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx agentsid audit --agent # View audit log` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx agentsid revoke # Revoke an agent` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `git clone https://github.com/AgentsID-dev/agentsid.git` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `pip install -e .` 证据：`README.md` Claim：`clm_0011` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0012` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0013` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：254\n- 重要文件覆盖：40/254\n- 证据索引条目：55\n- 角色 / Skill 条目：21\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 agentsid 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 agentsid 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 agentsid 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 21 个角色 / Skill / 项目文档条目。\n\n- **The Problem**（project_doc）：Identity, permissions, and audit for AI agents. The Auth0 for the agent economy. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **AgentsID — Download Metrics**（project_doc）：Auto-updated daily by GitHub Actions. Last run: 2026-05-13 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`metrics/README.md`\n- **AgentsID Java SDK**（project_doc）：! Maven https://img.shields.io/badge/maven-dev.agentsid:agentsid--sdk-7c5bf0?style=flat-square https://agentsid.dev ! Java https://img.shields.io/badge/java-17%2B-7c5bf0?style=flat-square https://openjdk.org/ ! License https://img.shields.io/badge/license-MIT-7c5bf0?style=flat-square ../LICENSE 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdk-java/README.md`\n- **agentsid**（project_doc）：! PyPI version https://img.shields.io/pypi/v/agentsid.svg https://pypi.org/project/agentsid/ ! Python https://img.shields.io/pypi/pyversions/agentsid.svg https://pypi.org/project/agentsid/ ! License: MIT https://img.shields.io/badge/License-MIT-blue.svg https://opensource.org/licenses/MIT 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdk-python/README.md`\n- **agentsid**（project_doc）：! Gem Version https://img.shields.io/gem/v/agentsid.svg https://rubygems.org/gems/agentsid ! License: MIT https://img.shields.io/badge/License-MIT-blue.svg https://opensource.org/licenses/MIT 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdk-ruby/README.md`\n- **@agentsid/sdk**（project_doc）：! npm version https://img.shields.io/npm/v/@agentsid/sdk.svg https://www.npmjs.com/package/@agentsid/sdk ! License: MIT https://img.shields.io/badge/License-MIT-blue.svg https://opensource.org/licenses/MIT 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdk-typescript/README.md`\n- **@agentsid/setup**（project_doc）：Guided setup wizard for AgentsID https://agentsid.dev — protect your AI coding agent in 2 minutes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`setup/README.md`\n- **React + TypeScript + Vite**（project_doc）：This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`web/README.md`\n- **AgentsID Security Model**（project_doc）：This document describes the security architecture of AgentsID: how tokens are signed and validated, how permissions are evaluated, how delegation chains enforce scope narrowing, and what is recorded in the audit trail. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/SECURITY.md`\n- **AgentsID + FastMCP Integration Guide**（project_doc）：AgentsID + FastMCP Integration Guide 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/fastmcp-integration.md`\n- **AgentsID Permission Specification v1.0**（project_doc）：AgentsID Permission Specification v1.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/permission-spec-v1.md`\n- **The State of MCP Server Security — 2026**（project_doc）：The State of MCP Server Security — 2026 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/state-of-agent-security-2026.md`\n- **The 251 gap: the MCP servers our own registry couldn't see**（project_doc）：The 251 gap: the MCP servers our own registry couldn't see 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/blog/2026-04-17-the-251-gap.md`\n- **Cursor Marketplace Listing — AgentsID Guard**（project_doc）：Cursor Marketplace Listing — AgentsID Guard 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/devrel/cursor-marketplace-listing.md`\n- **MCP Security Digest — Issue 1**（project_doc）：Subject primary : Issue 1 — 1,332 MCP servers fail. Here are the 5 worst. Subject short alt : The 5 worst MCP servers we've scanned Subject plain alt : MCP Security Digest 1 — 1,332 F grades Preheader: 94.8% of servers with 51+ tools grade F. One pattern predicts most of it. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/digest/issue-01.md`\n- **HN Response Drafts — 2026-04-17**（project_doc）：Post: \"460 MCP servers tell agents to act secretly\" Show HN Status: Pre-drafted responses for likely comment archetypes. Steven reviews and posts from his account. Append real comment text + context above each response once they land. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/hn-responses/2026-04-17.md`\n- **Cursor + Codex Integration Research**（project_doc）：Cursor + Codex Integration Research 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`setup/docs/cursor-integration-research.md`\n- **AgentsID — Technical Architecture**（project_doc）：Layer Technology Why ------- ----------- ----- API Server FastAPI Python Steven's strongest stack, async, type-safe, fast to build Database PostgreSQL Supabase Already have it, proven, free tier TypeScript SDK Pure TypeScript, zero deps npm package, MCP middleware Python SDK Pure Python, zero deps PyPI package, MCP middleware CLI Node.js npx Developer onboarding Auth HMAC token signing Simple, no external auth deps… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ARCHITECTURE.md`\n- **Changelog**（project_doc）：All notable changes to this project will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **AgentsID — Identity and Auth for AI Agents**（project_doc）：AgentsID — Identity and Auth for AI Agents 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`PRODUCT.md`\n- **Changelog**（project_doc）：All notable changes to @agentsid/setup are documented here. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`setup/CHANGELOG.md`\n\n## 证据索引\n\n- 共索引 55 条证据。\n\n- **The Problem**（documentation）：Identity, permissions, and audit for AI agents. The Auth0 for the agent economy. 证据：`README.md`\n- **AgentsID — Download Metrics**（documentation）：Auto-updated daily by GitHub Actions. Last run: 2026-05-13 证据：`metrics/README.md`\n- **AgentsID Java SDK**（documentation）：! Maven https://img.shields.io/badge/maven-dev.agentsid:agentsid--sdk-7c5bf0?style=flat-square https://agentsid.dev ! Java https://img.shields.io/badge/java-17%2B-7c5bf0?style=flat-square https://openjdk.org/ ! License https://img.shields.io/badge/license-MIT-7c5bf0?style=flat-square ../LICENSE 证据：`sdk-java/README.md`\n- **agentsid**（documentation）：! PyPI version https://img.shields.io/pypi/v/agentsid.svg https://pypi.org/project/agentsid/ ! Python https://img.shields.io/pypi/pyversions/agentsid.svg https://pypi.org/project/agentsid/ ! License: MIT https://img.shields.io/badge/License-MIT-blue.svg https://opensource.org/licenses/MIT 证据：`sdk-python/README.md`\n- **agentsid**（documentation）：! Gem Version https://img.shields.io/gem/v/agentsid.svg https://rubygems.org/gems/agentsid ! License: MIT https://img.shields.io/badge/License-MIT-blue.svg https://opensource.org/licenses/MIT 证据：`sdk-ruby/README.md`\n- **@agentsid/sdk**（documentation）：! npm version https://img.shields.io/npm/v/@agentsid/sdk.svg https://www.npmjs.com/package/@agentsid/sdk ! License: MIT https://img.shields.io/badge/License-MIT-blue.svg https://opensource.org/licenses/MIT 证据：`sdk-typescript/README.md`\n- **@agentsid/setup**（documentation）：Guided setup wizard for AgentsID https://agentsid.dev — protect your AI coding agent in 2 minutes. 证据：`setup/README.md`\n- **React + TypeScript + Vite**（documentation）：This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. 证据：`web/README.md`\n- **Package**（package_manifest）：{ \"name\": \"agentsid\", \"version\": \"0.1.0\", \"description\": \"AgentsID CLI — manage agent identities from the terminal\", \"type\": \"module\", \"bin\": { \"agentsid\": \"dist/index.js\" }, \"scripts\": { \"build\": \"tsc\", \"dev\": \"tsc --watch\" }, \"keywords\": \"ai\", \"agents\", \"auth\", \"identity\", \"mcp\", \"cli\" , \"author\": \"AgentsID\", \"license\": \"MIT\", \"devDependencies\": { \"@types/node\": \"^25.5.0\", \"typescript\": \"^5.3.0\" } } 证据：`cli/package.json`\n- **Package**（package_manifest）：{ \"name\": \"agentsid-demo\", \"version\": \"1.0.0\", \"type\": \"module\", \"dependencies\": { \"@agentsid/sdk\": \"^0.1.0\", \"@modelcontextprotocol/sdk\": \"^1.0.0\", \"zod\": \"^4.3.6\" } } 证据：`demo/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@agentsid/mcp-scanner\", \"version\": \"0.2.0\", \"description\": \"MCP security scanner. Scores any MCP server against the AgentsID trust framework and looks up pre-scanned results from the public registry.\", \"type\": \"module\", \"main\": \"src/index.mjs\", \"bin\": { \"agentsid-scanner\": \"src/index.mjs\" }, \"scripts\": { \"start\": \"node src/index.mjs\" }, \"keywords\": \"mcp\", \"mcp-server\", \"security\", \"scanner\", \"agentsid\", \"trust-score\", \"ai-agents\" , \"mcpName\": \"agentsid-mcp-scanner\", \"license\": \"MIT\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/AgentsID-dev/agentsid-scanner.git\" }, \"dependencies\": { \"@agentsid/scanner\": \"^0.2.0\", \"@modelcontextprotocol/sdk\": \"^1.0.0\" } } 证据：`mcp-scanner/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@agentsid/sdk\", \"version\": \"0.1.0\", \"description\": \"Identity and auth for AI agents — drop-in MCP middleware, per-tool permissions, delegation chains, audit trails\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"type\": \"module\", \"files\": \"dist\" , \"scripts\": { \"build\": \"tsc\", \"dev\": \"tsc --watch\", \"prepublishOnly\": \"npm run build\" }, \"keywords\": \"ai\", \"agents\", \"auth\", \"identity\", \"mcp\", \"security\", \"permissions\", \"audit\", \"delegation\", \"tokens\" , \"author\": \"AgentsID \", \"license\": \"MIT\", \"homepage\": \"https://agentsid.dev\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/agentsid/agentsid\" }, \"bugs\": { \"url\": \"https://github.com/agentsid/agentsid/issues\" }, \"engin… 证据：`sdk-typescript/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@agentsid/setup\", \"version\": \"0.2.4\", \"description\": \"Guided setup wizard for AgentsID — protect your AI agent in 2 minutes\", \"type\": \"module\", \"bin\": { \"agentsid-setup\": \"./dist/cli.js\" }, \"files\": \"dist\", \"README.md\", \"LICENSE\", \"CHANGELOG.md\" , \"scripts\": { \"build\": \"tsc && npm run copy-assets\", \"copy-assets\": \"mkdir -p dist/hook && cp src/hook/pre-tool.sh src/hook/post-tool.sh src/hook/cursor-adapter.sh dist/hook/\", \"dev\": \"tsx src/cli.tsx\", \"test\": \"vitest run\", \"prepublishOnly\": \"npm run build && npm test\" }, \"dependencies\": { \"ink\": \"^5.1.0\", \"ink-select-input\": \"^6.0.0\", \"ink-spinner\": \"^5.0.0\", \"ink-text-input\": \"^6.0.0\", \"react\": \"^18.3.0\" }, \"devDependencies\": { \"@type… 证据：`setup/package.json`\n- **Package**（package_manifest）：{ \"name\": \"web\", \"private\": true, \"version\": \"0.0.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build\": \"tsc -b && vite build\", \"lint\": \"eslint .\", \"preview\": \"vite preview\" }, \"dependencies\": { \"@radix-ui/react-accordion\": \"^1.2.12\", \"@radix-ui/react-dialog\": \"^1.1.15\", \"@radix-ui/react-icons\": \"^1.3.2\", \"@radix-ui/react-label\": \"^2.1.8\", \"@radix-ui/react-navigation-menu\": \"^1.2.14\", \"@radix-ui/react-slot\": \"^1.2.4\", \"@sentry/react\": \"^10.46.0\", \"@tailwindcss/vite\": \"^4.2.2\", \"@xyflow/react\": \"^12.10.1\", \"class-variance-authority\": \"^0.7.1\", \"clsx\": \"^2.1.1\", \"lucide-react\": \"^1.7.0\", \"motion\": \"^12.38.0\", \"posthog-js\": \"^1.365.0\", \"react\": \"^19.2.4\", \"react-dom\": \"^19.2.4\", \"react-ro… 证据：`web/package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`setup/LICENSE`\n- **AgentsID Security Model**（documentation）：This document describes the security architecture of AgentsID: how tokens are signed and validated, how permissions are evaluated, how delegation chains enforce scope narrowing, and what is recorded in the audit trail. 证据：`docs/SECURITY.md`\n- **AgentsID + FastMCP Integration Guide**（documentation）：AgentsID + FastMCP Integration Guide 证据：`docs/fastmcp-integration.md`\n- **AgentsID Permission Specification v1.0**（documentation）：AgentsID Permission Specification v1.0 证据：`docs/permission-spec-v1.md`\n- **The State of MCP Server Security — 2026**（documentation）：The State of MCP Server Security — 2026 证据：`docs/state-of-agent-security-2026.md`\n- **The 251 gap: the MCP servers our own registry couldn't see**（documentation）：The 251 gap: the MCP servers our own registry couldn't see 证据：`docs/blog/2026-04-17-the-251-gap.md`\n- **Cursor Marketplace Listing — AgentsID Guard**（documentation）：Cursor Marketplace Listing — AgentsID Guard 证据：`docs/devrel/cursor-marketplace-listing.md`\n- **MCP Security Digest — Issue 1**（documentation）：Subject primary : Issue 1 — 1,332 MCP servers fail. Here are the 5 worst. Subject short alt : The 5 worst MCP servers we've scanned Subject plain alt : MCP Security Digest 1 — 1,332 F grades Preheader: 94.8% of servers with 51+ tools grade F. One pattern predicts most of it. 证据：`docs/digest/issue-01.md`\n- **HN Response Drafts — 2026-04-17**（documentation）：Post: \"460 MCP servers tell agents to act secretly\" Show HN Status: Pre-drafted responses for likely comment archetypes. Steven reviews and posts from his account. Append real comment text + context above each response once they land. 证据：`docs/hn-responses/2026-04-17.md`\n- **Cursor + Codex Integration Research**（documentation）：Cursor + Codex Integration Research 证据：`setup/docs/cursor-integration-research.md`\n- **AgentsID — Technical Architecture**（documentation）：Layer Technology Why ------- ----------- ----- API Server FastAPI Python Steven's strongest stack, async, type-safe, fast to build Database PostgreSQL Supabase Already have it, proven, free tier TypeScript SDK Pure TypeScript, zero deps npm package, MCP middleware Python SDK Pure Python, zero deps PyPI package, MCP middleware CLI Node.js npx Developer onboarding Auth HMAC token signing Simple, no external auth deps Deployment Railway + Docker Already have config patterns from Vault 证据：`ARCHITECTURE.md`\n- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`CHANGELOG.md`\n- **AgentsID — Identity and Auth for AI Agents**（documentation）：AgentsID — Identity and Auth for AI Agents 证据：`PRODUCT.md`\n- **Changelog**（documentation）：All notable changes to @agentsid/setup are documented here. 证据：`setup/CHANGELOG.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"lib\": \"ES2022\", \"DOM\" , \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"declaration\": false, \"sourceMap\": false, \"esModuleInterop\": true, \"skipLibCheck\": true }, \"include\": \"src\" , \"exclude\": \"node modules\", \"dist\" } 证据：`cli/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"lib\": \"ES2022\", \"DOM\" , \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"esModuleInterop\": true, \"skipLibCheck\": true }, \"include\": \"src\" , \"exclude\": \"node modules\", \"dist\" } 证据：`sdk-typescript/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"NodeNext\", \"moduleResolution\": \"NodeNext\", \"jsx\": \"react-jsx\", \"outDir\": \"./dist\", \"rootDir\": \"./src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"declaration\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\" } 证据：`setup/tsconfig.json`\n- **Tsconfig.App**（structured_config）：{ \"compilerOptions\": { \"tsBuildInfoFile\": \"./node modules/.tmp/tsconfig.app.tsbuildinfo\", \"target\": \"ES2023\", \"useDefineForClassFields\": true, \"lib\": \"ES2023\", \"DOM\", \"DOM.Iterable\" , \"module\": \"ESNext\", \"types\": \"vite/client\" , \"skipLibCheck\": true, \"moduleResolution\": \"bundler\", \"allowImportingTsExtensions\": true, \"verbatimModuleSyntax\": true, \"moduleDetection\": \"force\", \"noEmit\": true, \"jsx\": \"react-jsx\", \"strict\": true, \"noUnusedLocals\": true, \"noUnusedParameters\": true, \"erasableSyntaxOnly\": true, \"noFallthroughCasesInSwitch\": true, \"noUncheckedSideEffectImports\": true, \"baseUrl\": \".\", \"paths\": { \"@/ \": \"./src/ \" } }, \"include\": \"src\" } 证据：`web/tsconfig.app.json`\n- **Tsconfig**（structured_config）：{ \"files\": , \"references\": { \"path\": \"./tsconfig.app.json\" }, { \"path\": \"./tsconfig.node.json\" } } 证据：`web/tsconfig.json`\n- **Tsconfig.Node**（structured_config）：{ \"compilerOptions\": { \"tsBuildInfoFile\": \"./node modules/.tmp/tsconfig.node.tsbuildinfo\", \"target\": \"ES2023\", \"lib\": \"ES2023\" , \"module\": \"ESNext\", \"types\": \"node\" , \"skipLibCheck\": true, 证据：`web/tsconfig.node.json`\n- **Python**（source_file）：Python pycache / .pyc .pyo .venv/ .egg-info/ dist/ build/ .ruff cache/ .pytest cache/ 证据：`.gitignore`\n- **Force rebuild by changing this comment: v5**（source_file）：WORKDIR /app/web COPY web/package.json web/package-lock.json ./ RUN npm ci COPY web/ . RUN npm run build 证据：`Dockerfile`\n- **Parse env vars**（source_file）：name: 'AgentsID MCP Scan' description: 'Scan MCP servers for security issues. Posts a PR comment, renders a workflow summary, and uploads findings to the GitHub Security tab.' author: 'AgentsID' 证据：`action.yml`\n- **Server**（source_file）：/ AgentsID Demo — A real MCP server protected by AgentsID Tools: - search notes: Search through notes ALLOWED - save note: Save a new note ALLOWED - list notes: List all notes ALLOWED - delete note: Delete a note DENIED by AgentsID - admin reset: Reset everything DENIED by AgentsID / 证据：`demo/server.mjs`\n- **Npm Downloads**（source_file）：date,package,daily,weekly,monthly 2026-04-07,@agentsid/scanner,17,307,467 2026-04-07,@agentsid/mcp-scanner,26,609,609 2026-04-07,@agentsid/sdk,2,9,70 2026-04-07,@agentsid/proxy,7,28,64 2026-04-08,@agentsid/scanner,17,307,467 2026-04-08,@agentsid/mcp-scanner,26,609,609 2026-04-08,@agentsid/sdk,2,9,70 2026-04-08,@agentsid/proxy,7,28,64 2026-04-09,@agentsid/scanner,118,392,585 2026-04-09,@agentsid/mcp-scanner,17,626,626 2026-04-09,@agentsid/sdk,1,10,71 2026-04-09,@agentsid/proxy,1,19,65 2026-04-10,@agentsid/scanner,26,410,611 2026-04-10,@agentsid/mcp-scanner,36,662,662 2026-04-10,@agentsid/sdk,0,8,71 2026-04-10,@agentsid/proxy,0,16,65 2026-04-11,@agentsid/scanner,16,398,627 2026-04-11,@agentsi… 证据：`metrics/npm-downloads.csv`\n- **Railway**（source_file）：build builder = \"DOCKERFILE\" dockerfilePath = \"Dockerfile\" 证据：`railway.toml`\n- **!/bin/bash**（source_file）：!/bin/bash Pull real-time GitHub traffic for agentsid-scanner Usage: ./scripts/gh-traffic.sh 证据：`scripts/gh-traffic.sh`\n- **!/bin/bash**（source_file）：!/bin/bash Track npm download stats for AgentsID packages Usage: ./scripts/npm-downloads.sh --daily Packages tracked: @agentsid/scanner — core scanner library @agentsid/mcp-scanner — MCP server wrapper 证据：`scripts/npm-downloads.sh`\n- **Pom**（source_file）：dev.agentsid agentsid-sdk 0.1.0 jar 证据：`sdk-java/pom.xml`\n- **Pyproject**（source_file）：project name = \"agentsid\" version = \"0.1.0\" description = \"Identity and auth for AI agents — drop-in MCP middleware\" readme = \"README.md\" requires-python = \" =3.10\" dependencies = \"httpx =0.25.0\" license = {text = \"MIT\"} keywords = \"ai\", \"agents\", \"auth\", \"identity\", \"mcp\", \"security\" 证据：`sdk-python/pyproject.toml`\n- **frozen string literal: true**（source_file）：Gem::Specification.new do spec spec.name = \"agentsid\" spec.version = \"0.1.0\" spec.authors = \"AgentsID\" spec.email = \"support@agentsid.dev\" 证据：`sdk-ruby/agentsid.gemspec`\n- **server/.dockerignore**（source_file）：.env .env. .venv/ pycache / .pyc .git/ .github/ tests/ .pytest cache/ .ruff cache/ .md .full-review/ 证据：`server/.dockerignore`\n- **Required**（source_file）：Required AGENTSID DATABASE URL=postgresql+asyncpg://user:pass@localhost:5432/agentsid AGENTSID SIGNING SECRET=generate-a-64-char-random-string-here 证据：`server/.env.example`\n- **Dockerfile**（source_file）：COPY pyproject.toml . RUN uv pip install --system --no-cache . resend cryptography sentry-sdk fastapi 证据：`server/Dockerfile`\n- **A generic, single database configuration.**（source_file）：A generic, single database configuration. 证据：`server/alembic.ini`\n- **Docker Compose**（source_file）：services: db: image: postgres:16 restart: unless-stopped environment: POSTGRES USER: agentsid POSTGRES PASSWORD: agentsid local POSTGRES DB: agentsid ports: - \"5432:5432\" volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: \"CMD-SHELL\", \"pg isready -U agentsid -d agentsid\" interval: 5s timeout: 5s retries: 5 证据：`server/docker-compose.yml`\n- **Pyproject**（source_file）：project name = \"agentsid-server\" version = \"0.2.0\" description = \"Identity and auth for AI agents\" requires-python = \" =3.12\" dependencies = \"fastapi =0.115.0\", \"uvicorn standard =0.32.0\", \"sqlalchemy asyncio =2.0.36\", \"asyncpg =0.30.0\", \"alembic =1.14.0\", \"pydantic =2.10.0\", \"pydantic-settings =2.6.0\", \"httpx =0.28.0\", \"slowapi =0.1.9\", \"pyyaml =6.0.2\", \"cryptography =43.0.0\", \"resend =2.4.0\", 证据：`server/pyproject.toml`\n- **Logs**（source_file）：Logs logs .log npm-debug.log yarn-debug.log yarn-error.log pnpm-debug.log lerna-debug.log 证据：`web/.gitignore`\n- **Eslint.Config**（source_file）：import js from '@eslint/js' import globals from 'globals' import reactHooks from 'eslint-plugin-react-hooks' import reactRefresh from 'eslint-plugin-react-refresh' import tseslint from 'typescript-eslint' import { defineConfig, globalIgnores } from 'eslint/config' 证据：`web/eslint.config.js`\n- **Index**（source_file）：AgentsID — Identity for AI Agents !function t,e {var o,n,p,r;e. SV window.posthog=e,e. i= ,e.init=function i,s,a {function g t,e {var o=e.split \".\" ;2==o.length&& t=t o 0 ,e=o 1 ,t e =function {t.push e .concat Array.prototype.slice.call arguments,0 }} p=t.createElement \"script\" .type=\"text/javascript\",p.async=!0,p.src=s.api host.replace \".i.posthog.com\",\"-assets.i.posthog.com\" +\"/static/array.js\", r=t.getElementsByTagName \"script\" 0 .parentNode.insertBefore p,r ;var u=e;for void 0!==a?u=e a = :a=\"posthog\",u.people=u.people ,u.toString=function t {var e=\"posthog\";return\"posthog\"!==a&& e+=\".\"+a ,t e+=\" stub \" ,e},u.people.toString=function {return u.toString 1 +\".people stub \"},o=\"init captu… 证据：`web/index.html`\n- **Vite.Config**（source_file）：import { defineConfig } from \"vite\"; import react from \"@vitejs/plugin-react\"; import tailwindcss from \"@tailwindcss/vite\"; import path from \"path\"; 证据：`web/vite.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `metrics/README.md`, `sdk-java/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `metrics/README.md`, `sdk-java/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, PRODUCT.md, docs/SECURITY.md\n- **系统架构**：importance `high`\n - source_paths: ARCHITECTURE.md, server/src/app.py, server/src/core/security.py\n- **后端 API 接口**：importance `high`\n - source_paths: server/src/api/agents.py, server/src/api/permissions.py, server/src/api/approvals.py, server/src/api/audit.py, server/src/api/webhooks.py\n- **核心业务服务**：importance `high`\n - source_paths: server/src/services/identity.py, server/src/services/permission.py, server/src/services/approval.py, server/src/services/audit.py, server/src/services/notifications.py\n- **数据模型与数据库**：importance `medium`\n - source_paths: server/src/models/models.py, server/src/core/database.py, server/alembic/versions/21eca51078a1_add_audit_integrity_hash_chain.py, server/alembic/versions/35a9e5cf497f_add_encrypted_api_key_to_projects.py, server/alembic/versions/a1b2c3d4e5f6_add_teams_and_team_members.py\n- **TypeScript SDK**：importance `high`\n - source_paths: sdk-typescript/src/client.ts, sdk-typescript/src/middleware.ts, sdk-typescript/src/errors.ts, sdk-typescript/src/types.ts, sdk-typescript/README.md\n- **Python/Ruby/Java SDK**：importance `medium`\n - source_paths: sdk-python/agentsid/client.py, sdk-python/agentsid/middleware.py, sdk-python/README.md, sdk-ruby/lib/agentsid/client.rb, sdk-ruby/lib/agentsid/middleware.rb\n- **Web 仪表板**：importance `medium`\n - source_paths: web/src/App.tsx, web/src/pages/dashboard.tsx, web/src/components/dashboard/AgentCards.tsx, web/src/components/dashboard/PermissionEditor.tsx, web/src/components/dashboard/TeamTab.tsx\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `agentsid` 与安装入口 `@agentsid/sdk` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | repo=agentsid; install=@agentsid/sdk\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：AgentsID-dev/agentsid\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/AgentsID-dev/agentsid 项目说明书\n\n生成时间：2026-05-13 14:47:22 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [系统架构](#page-architecture)\n- [后端 API 接口](#page-api-endpoints)\n- [核心业务服务](#page-core-services)\n- [数据模型与数据库](#page-data-models)\n- [TypeScript SDK](#page-sdk-typescript)\n- [Python/Ruby/Java SDK](#page-sdk-other-languages)\n- [Web 仪表板](#page-web-dashboard)\n- [Setup CLI 与集成](#page-setup-cli)\n- [MCP 安全扫描器](#page-mcp-scanner)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [核心业务服务](#page-core-services)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx)\n- [web/src/pages/research.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n- [web/src/pages/registry-v2.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-v2.tsx)\n
\n\n# 项目介绍\n\n## 概述\n\nAgentsID 是一个 AI 代理安全与权限控制平台，旨在为 AI 代理（Agent）提供工具调用级别的安全审计、权限管理和行为控制能力。该项目通过扫描 MCP（Model Context Protocol）服务器的安全漏洞，为开发者提供可操作的安全修复建议，并支持细粒度的权限配置和完整的审计日志功能。\n\nAgentsID 的核心价值在于：在不影响 AI 代理正常工作的前提下，通过 200 行 bash 脚本的轻量级 hook 实现对工具调用的实时验证和拦截，确保 AI 代理的操作始终在预设的安全边界内运行。\n\n资料来源：[web/src/pages/landing.tsx:1-50]()\n\n## 核心功能\n\n### 安全扫描与评级系统\n\nAgentsID 提供自动化的 MCP 服务器安全扫描功能，通过对服务器代码的静态分析和运行时行为检测，识别潜在的安全威胁并生成安全评级。\n\n| 评级 | 含义 | 颜色标识 |\n|------|------|----------|\n| A | 优秀 - 无关键问题 | 绿色 |\n| B | 良好 - 少量低风险问题 | 蓝色 |\n| C | 一般 - 存在中等风险 | 黄色 |\n| D | 较差 - 存在高风险问题 | 橙色 |\n| F | 危险 - 存在严重漏洞 | 红色 |\n\n扫描器能够检测多种类型的安全问题，包括但不限于：Shell 执行风险、数据泄露风险、权限提升风险、恶意代码注入等。每个检测结果都附带可操作的修复建议，而非仅仅指出问题所在。\n\n资料来源：[web/src/pages/landing.tsx:50-80]()\n\n### 权限控制与规则引擎\n\nAgentsID 提供基于规则的权限控制系统，开发者可以通过配置规则来控制代理可以调用的工具及其使用条件。系统支持多种约束条件：\n\n| 约束类型 | 说明 | 配置字段 |\n|----------|------|----------|\n| 工具白名单 | 仅允许指定工具 | `tool_pattern` |\n| 参数限制 | 限制工具参数的范围 | `conditions` |\n| 时间窗口 | 限制工具调用的时间范围 | `schedule` |\n| 频率限制 | 限制工具的调用频率 | `rate_limit` |\n| 预算控制 | 限制工具的资源消耗 | `budget` |\n| 序列要求 | 要求在调用前先执行其他工具 | `sequence_requirements` |\n\n规则支持 AND 逻辑组合，允许多个条件同时满足时才允许工具调用执行。\n\n资料来源：[web/src/pages/guides.tsx:1-100]()\n\n### 审计日志与完整性验证\n\nAgentsID 维护所有工具调用的完整审计日志，采用哈希链（Hash Chain）技术确保日志的不可篡改性。\n\n```mermaid\ngraph TD\n A[工具调用请求] --> B{规则匹配引擎}\n B -->|允许| C[执行工具]\n B -->|拒绝| D[拦截请求]\n C --> E[生成审计条目]\n D --> E\n E --> F[SHA-256 哈希]\n F --> G[追加到链式日志]\n G --> H[验证完整性]\n```\n\n审计日志条目包含以下关键信息：\n\n- `entryId`: 日志条目唯一标识\n- `timestamp`: 调用时间戳\n- `agentId`: 代理标识\n- `tool`: 被调用的工具名称\n- `parameters`: 工具参数\n- `decision`: 决策结果（allow/deny）\n- `matchedRule`: 匹配的规则编号\n- `entryHash`: 当前条目的哈希值\n- `prevEntryHash`: 前一条目的哈希值\n\n哈希链的验证公式为：`entryHash = SHA-256(canonicalize(entry with entryHash=null))`，首条记录的前置哈希固定为 \"genesis\"。\n\n资料来源：[web/src/pages/spec.tsx:1-80]()\n\n## 技术架构\n\n### 组件架构\n\nAgentsID 的整体架构由以下核心组件构成：\n\n```mermaid\ngraph TD\n subgraph 前端层\n A[Web Dashboard]\n B[Registry 页面]\n C[文档站点]\n end\n \n subgraph 核心服务\n D[API 服务]\n E[扫描引擎]\n F[规则引擎]\n end\n \n subgraph 数据层\n G[(审计日志数据库)]\n H[(规则配置存储)]\n I[(扫描结果缓存)]\n end\n \n subgraph 客户端集成\n J[AgentsID SDK]\n K[CLI 工具]\n L[MCP 服务器]\n end\n \n A --> D\n B --> E\n C --> D\n J --> D\n K --> D\n L --> F\n F --> G\n E --> I\n D --> H\n```\n\n### SDK 集成方式\n\nAgentsID 提供多种集成方式以满足不同开发场景的需求：\n\n**Node.js SDK 集成**\n\n```bash\nnpm install @agentsid/sdk\n```\n\nSDK 的核心是一个轻量级库，负责与 AgentsID 服务端通信、验证工具调用、记录事件日志并执行权限检查。代理代码保持简洁，无需感知安全控制的实现细节。\n\n**CLI 工具**\n\n通过 `npx agentsid` 命令可执行各项操作：\n\n| 命令 | 功能 |\n|------|------|\n| `init` | 创建新项目并获取 API 密钥 |\n| `register-agent` | 注册新的代理实例 |\n| `audit verify` | 验证审计日志链的完整性 |\n\n资料来源：[web/src/pages/docs.tsx:1-100]()\n\n### MCP 服务器集成\n\nAgentsID 支持与 MCP（Model Context Protocol）服务器的集成。通过在 MCP 服务器配置中添加环境变量即可启用安全控制：\n\n```json\n{\n \"mcpServers\": {\n \"my-notes-server\": {\n \"command\": \"node\",\n \"args\": [\"server.mjs\"],\n \"env\": {\n \"AGENTSID_PROJECT_KEY\": \"aid_proj_your_key_here\",\n \"AGENTSID_AGENT_TOKEN\": \"at_your_token_here\"\n }\n }\n }\n}\n```\n\n支持的 MCP 客户端包括：\n\n- Claude Code\n- Cursor\n- 其他兼容 MCP 协议的客户端\n\n资料来源：[web/src/pages/guides.tsx:100-200]()\n\n## 安全特性\n\n### 数据安全原则\n\nAgentsID 在数据处理方面遵循严格的安全原则：\n\n| 安全措施 | 说明 |\n|----------|------|\n| API 密钥哈希存储 | 仅存储 API 密钥的哈希值，不存储明文 |\n| 审计日志链式存储 | 通过 SHA-256 哈希链确保日志不可篡改 |\n| Cookie 同意机制 | PostHog 分析功能默认关闭，需用户明确同意 |\n| 数据导出功能 | 支持随时导出项目数据、代理配置和审计日志 |\n\n### 研究与透明度\n\nAgentsID 的安全研究完全公开透明：\n\n- 所有扫描器代码在 GitHub 上开源（MIT 许可证）\n- 所有研究论文开放获取\n- 审计日志中的每条拒绝记录都可追溯到对应的规则提交\n- 截至目前已扫描 137,070 台服务器，发现的问题均有详细文档记录\n\n资料来源：[web/src/pages/research.tsx:1-50]()\n\n## 工具注册表\n\nAgentsID 维护一个公开的 MCP 服务器安全评级注册表（Registry），展示各服务器的安全评分和发现的问题类型。\n\n### 评级展示\n\n每个注册服务器的信息包括：\n\n| 字段 | 说明 |\n|------|------|\n| `package` | NPM 包名称 |\n| `version` | 当前版本 |\n| `grade` | 安全评级 (A-F) |\n| `tools` | 工具数量 |\n| `scannedAt` | 最后扫描时间 |\n| `topFindings` | 主要发现的安全问题 |\n| `critical` | 严重问题数量 |\n| `high` | 高风险问题数量 |\n| `medium` | 中等风险问题数量 |\n\n开发者可以通过注册表快速了解某个 MCP 服务器的安全状况，并获取修复建议。\n\n资料来源：[web/src/pages/registry-v2.tsx:1-100]()\n\n## 快速开始\n\n### 安装步骤\n\n1. **创建项目**: 在 agentsid.dev/dashboard 注册账户并创建项目，获取项目密钥\n2. **安装 SDK**: 在项目目录执行 `npm install @agentsid/sdk`\n3. **注册代理**: 使用 SDK 注册代理并获取代理令牌\n4. **配置规则**: 在仪表板中配置工具调用权限规则\n5. **集成验证**: 将 SDK 集成到代理代码中\n\n### 一键安装\n\n```bash\nnpx @agentsid/setup@latest\n```\n\n该命令自动完成项目初始化、SDK 安装和基础配置。\n\n资料来源：[web/src/pages/landing.tsx:80-120]()\n\n## 许可与开源\n\n| 组件 | 许可证 |\n|------|--------|\n| 扫描器 (scanner) | MIT |\n| 服务端 (server) | Source-Available |\n\n所有安全规则和策略配置采用公开透明的方式管理，确保用户对安全控制的完全可见性和可审计性。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [后端 API 接口](#page-api-endpoints), [核心业务服务](#page-core-services)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n- [web/src/pages/privacy.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/privacy.tsx)\n- [web/src/components/dashboard/AuditFeed.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx)\n- [web/src/components/dashboard/OverviewTab.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/OverviewTab.tsx)\n- [web/src/components/dashboard/PermissionAdvancedPanel.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/PermissionAdvancedPanel.tsx)\n- [README.md](https://github.com/AgentsID-dev/agentsid/blob/main/README.md)\n
\n\n# 系统架构\n\n## 1. 概述\n\nAgentsID 是一个为 AI 代理提供身份认证、权限管理和审计功能的平台。其架构设计遵循\"轻量级 hook\"理念，核心是一个约 200 行 Bash 脚本的 hook，无复杂的 SDK 学习曲线，也无需匹配特定语言运行时。\n\n资料来源：[web/src/pages/landing.tsx]()\n\n### 1.1 核心定位\n\n| 维度 | 描述 |\n|------|------|\n| **产品定位** | AI 代理的身份认证与权限管理平台，被称为\"代理经济时代的 Auth0\" |\n| **技术理念** | 开发者友好的轻量级集成，支持任何可执行 Shell 脚本的环境 |\n| **安全承诺** | 不存储原始 API 密钥（仅存哈希）、提供 HMAC 验证和审计日志完整性验证 |\n\n资料来源：[README.md]()\n\n---\n\n## 2. 系统架构图\n\n```mermaid\ngraph TD\n subgraph Client[\"客户端层\"]\n A[AI Agent] --> B[Tool Call]\n B --> C[AgentsID Hook]\n end\n\n subgraph Integration[\"集成方式\"]\n C --> D[Claude Code]\n C --> E[Cursor MCP]\n C --> F[npm SDK]\n G[Python SDK] --> C\n H[Ruby SDK] --> C\n end\n\n subgraph Core[\"核心服务层\"]\n I[API Gateway] --> J[权限引擎]\n I --> K[审计日志服务]\n I --> L[代理注册服务]\n J --> M[规则匹配器]\n end\n\n subgraph Storage[\"数据层\"]\n K --> N[(PostgreSQL)]\n L --> N\n M --> N\n end\n\n subgraph Dashboard[\"管理界面\"]\n O[Web Dashboard] --> N\n P[审计日志面板] --> K\n Q[代理星座图] --> L\n end\n\n C --> I\n```\n\n---\n\n## 3. 核心组件\n\n### 3.1 权限引擎\n\n权限引擎负责在工具调用前进行决策判断。根据 `PermissionAdvancedPanel.tsx` 中的实现，引擎支持以下权限控制维度：\n\n| 权限类型 | 描述 | 配置参数 |\n|---------|------|---------|\n| **基础权限** | 允许/拒绝特定工具调用 | `allowed_tools`, `denied_tools` |\n| **序列要求** | 要求工具调用前必须先调用其他工具 | `sequence_requirements.requires_prior` |\n| **时间窗口** | 限制工具调用的时间窗口 | `sequence_requirements.within_seconds` |\n| **预算控制** | 限制工具调用的最大预算 | `budget.max` |\n\n资料来源：[web/src/components/dashboard/PermissionAdvancedPanel.tsx]()\n\n### 3.2 审计日志服务\n\n审计日志服务记录所有代理操作，采用哈希链技术确保数据完整性。\n\n```mermaid\ngraph LR\n A[工具调用] --> B[记录决策]\n B --> C[生成哈希]\n C --> D[链接到上一条]\n D --> E[存储到数据库]\n```\n\n**审计条目结构：**\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `entryId` | string | 条目唯一标识符，格式为 `entry_abc123` |\n| `timestamp` | ISO8601 | 事件发生时间 |\n| `agentId` | string | 代理定义 ID |\n| `delegationId` | string | 委托链 ID |\n| `tool` | string | 被调用的工具名称 |\n| `parameters` | object | 工具调用参数 |\n| `decision` | enum | 决策结果：`allow` 或 `deny` |\n| `matchedRule` | number | 匹配的规则索引 |\n| `constraintsEvaluated` | array | 评估的约束列表 |\n| `durationMs` | number | 处理耗时（毫秒） |\n| `prevEntryHash` | string | 前一条目的哈希值 |\n| `entryHash` | string | 当前条目的哈希值 |\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 3.3 哈希链完整性\n\n系统使用 SHA-256 算法构建审计日志的哈希链，确保数据不可篡改：\n\n```mermaid\ngraph LR\n A[Genesis Block] --> B[Entry 1 Hash]\n B --> C[Entry 2 Hash]\n C --> D[Entry N Hash]\n```\n\n**哈希计算公式：**\n\n```\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n```\n\n首条记录使用 `prevEntryHash: \"genesis\"` 作为起点。链验证从第二条记录开始，逐条比对哈希值。\n\n资料来源：[web/src/pages/spec.tsx]()\n\n---\n\n## 4. API 架构\n\n### 4.1 API 端点概览\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/v1/audit/verify` | GET | 验证审计日志链的完整性 |\n| `/api/v1/audit/usage` | GET | 获取当前使用量和计划限制 |\n| `/api/v1/projects` | POST | 创建新项目 |\n| `/api/v1/agents` | POST | 注册新代理 |\n\n### 4.2 认证机制\n\nAPI 使用 Bearer Token 认证，Token 格式为 `aid_proj_` 前缀的项目密钥。\n\n```bash\ncurl \"https://api.agentsid.dev/api/v1/audit/verify\" \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 4.3 验证响应示例\n\n**验证成功：**\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"chain_valid\": true\n}\n```\n\n**验证失败（链被破坏）：**\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n---\n\n## 5. SDK 集成架构\n\n### 5.1 多语言支持\n\nAgentsID 提供多种语言的 SDK 和集成方式：\n\n| 平台/语言 | 包管理器 | 安装命令 |\n|----------|---------|---------|\n| Node.js/npm | npm | `npm install @agentsid/sdk` |\n| Python | pip | `pip install agentsid` |\n| Ruby | gem | `gem install agentsid` |\n\n### 5.2 MCP 服务器集成\n\nModel Context Protocol (MCP) 服务器允许将 AgentsID 权限控制集成到 Cursor 等编辑器中。\n\n```json\n{\n \"mcpServers\": {\n \"my-notes-server\": {\n \"command\": \"node\",\n \"args\": [\"server.mjs\"],\n \"env\": {\n \"AGENTSID_PROJECT_KEY\": \"aid_proj_your_key_here\",\n \"AGENTSID_AGENT_TOKEN\": \"at_your_token_here\"\n }\n }\n }\n}\n```\n\n资料来源：[web/src/pages/guides.tsx]()\n\n### 5.3 工具权限检查流程\n\n```mermaid\ngraph TD\n A[Agent 调用工具] --> B{AgentsID Hook 拦截}\n B --> C{检查权限规则}\n C -->|允许| D[执行工具调用]\n C -->|拒绝| E[返回 blocked 响应]\n D --> F[记录审计日志]\n E --> F\n```\n\n代理本身不会意识到被限制，只会收到\"blocked\"响应。\n\n资料来源：[web/src/pages/guides.tsx]()\n\n---\n\n## 6. Dashboard 架构\n\n### 6.1 功能模块\n\n| 模块 | 功能 |\n|------|------|\n| **概览面板** | 显示项目状态、代理数量、近期活动 |\n| **代理管理** | 注册和管理代理，配置权限规则 |\n| **审计日志面板** | 查看完整的操作审计记录 |\n| **代理星座图** | 可视化展示项目中代理的关系网络 |\n\n资料来源：[web/src/components/dashboard/OverviewTab.tsx]()\n\n### 6.2 审计日志面板组件\n\n审计日志面板 (`AuditFeed.tsx`) 支持以下功能：\n\n| 功能 | 描述 |\n|------|------|\n| **条目详情** | 显示每个审计条目的完整信息 |\n| **委托链展示** | 可视化展示委托关系链 |\n| **委托方信息** | 显示操作的委托来源 |\n\n```tsx\n{entry.delegation_chain && (\n
\n
\n Delegation Chain\n
\n
\n {entry.delegation_chain.map((c, i) => (\n \n {i > 0 && →}\n \n {c.type}: {c.id}\n \n \n ))}\n
\n
\n)}\n```\n\n资料来源：[web/src/components/dashboard/AuditFeed.tsx]()\n\n---\n\n## 7. 数据安全架构\n\n### 7.1 安全特性\n\n| 安全措施 | 实现方式 |\n|---------|---------|\n| **API 密钥保护** | 仅存储密钥哈希，不存储明文 |\n| **HMAC 验证** | 验证请求的完整性 |\n| **审计日志完整性** | 使用哈希链防止篡改 |\n| **PostHog 分析** | 默认关闭，需用户主动同意 |\n\n资料来源：[web/src/pages/privacy.tsx]()\n\n### 7.2 数据导出\n\n用户可随时从仪表板导出以下数据：\n\n| 导出类型 | 格式 |\n|---------|------|\n| 项目数据 | JSON |\n| 代理配置 | JSON |\n| 审计日志 | JSON |\n\n资料来源：[web/src/pages/privacy.tsx]()\n\n---\n\n## 8. 系统工作流程\n\n### 8.1 代理注册流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant Dashboard\n participant API\n participant Database\n \n User->>Dashboard: 创建项目\n Dashboard->>API: POST /api/v1/projects\n API->>Database: 存储项目信息\n Database-->>API: 返回项目密钥\n API-->>Dashboard: 返回 aid_proj_xxx\n Dashboard-->>User: 显示项目密钥\n \n User->>Dashboard: 注册代理\n Dashboard->>API: POST /api/v1/agents\n API->>Database: 存储代理信息\n Database-->>API: 返回代理令牌\n API-->>Dashboard: 返回 at_yyy\n```\n\n### 8.2 工具调用控制流程\n\n```mermaid\ngraph TD\n A[代理执行工具调用] --> B[SDK/Hook 拦截请求]\n B --> C[调用 AgentsID API]\n C --> D{权限检查}\n D -->|匹配 allow 规则| E[允许执行]\n D -->|匹配 deny 规则| F[阻止执行]\n D -->|无匹配规则| G[使用默认策略]\n E --> H[记录审计日志]\n F --> H\n G --> H\n H --> I[返回结果给代理]\n```\n\n资料来源：[web/src/pages/landing.tsx]()\n\n---\n\n## 9. 技术栈概览\n\n### 9.1 前端技术栈\n\n| 技术 | 用途 |\n|------|------|\n| React | UI 框架 |\n| TypeScript | 类型安全 |\n| Tailwind CSS | 样式框架 |\n| Framer Motion | 动画效果 |\n\n### 9.2 后端技术栈\n\n基于文档推测的架构：\n\n| 组件 | 推测技术 |\n|------|---------|\n| API 服务 | Python/FastAPI |\n| 数据库 | PostgreSQL |\n| 缓存 | Redis (推测) |\n| 认证 | HMAC + Bearer Token |\n\n### 9.3 SDK 技术栈\n\n| SDK | 语言 | 核心依赖 |\n|-----|------|---------|\n| `@agentsid/sdk` | TypeScript/JavaScript | Node.js |\n| `agentsid` | Python | pip |\n| `agentsid` | Ruby | gem |\n\n---\n\n## 10. 总结\n\nAgentsID 采用分层架构设计，核心价值在于为 AI 代理提供轻量级的安全防护层：\n\n1. **接入层**：支持多种集成方式（SDK、CLI、MCP）\n2. **服务层**：权限引擎、审计日志、代理管理\n3. **数据层**：使用 PostgreSQL 存储项目和审计数据\n4. **展示层**：Web Dashboard 提供可视化管理和监控\n\n系统强调开发者体验，通过约 200 行的 Bash hook 实现零学习成本的集成，同时提供企业级的安全保证（HMAC 验证、哈希链完整性）。\n\n---\n\n\n\n## 后端 API 接口\n\n### 相关页面\n\n相关主题：[核心业务服务](#page-core-services), [数据模型与数据库](#page-data-models), [系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [server/src/api/agents.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/agents.py)\n- [server/src/api/permissions.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/permissions.py)\n- [server/src/api/approvals.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/approvals.py)\n- [server/src/api/audit.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/audit.py)\n- [server/src/api/webhooks.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/webhooks.py)\n- [server/src/api/teams.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/api/teams.py)\n- [docs/API.md](https://github.com/AgentsID-dev/agentsid/blob/main/docs/API.md)\n
\n\n# 后端 API 接口\n\n## 概述\n\nAgentsID 后端 API 是一个基于 RESTful 架构的权限管理与审计平台接口，为 AI Agent 提供身份认证、权限控制、审计日志和委托链验证等功能。该 API 遵循 Model Context Protocol (MCP) 标准，专门用于管理 AI Agent 对外部工具的访问控制。\n\n**核心功能模块：**\n\n| 模块 | 功能描述 | 基础路径 |\n|------|----------|----------|\n| 身份管理 | Agent 注册、更新、令牌管理 | `/api/v1/agents` |\n| 权限控制 | 权限规则设置、查询、验证 | `/api/v1/agents/{agent_id}/permissions` |\n| 审计日志 | 操作记录查询、完整性验证 | `/api/v1/audit` |\n| 审批流程 | 人工审批请求管理 | `/api/v1/approvals` |\n| Webhook | 事件通知回调 | `/api/v1/webhooks` |\n| 团队协作 | 多 Agent 协同管理 | `/api/v1/teams` |\n\n**API 基础地址：** `https://api.agentsid.dev/api/v1`\n\n所有请求需要在 HTTP Header 中携带项目密钥进行认证：\n```\nAuthorization: Bearer aid_proj_xxxxxxxxxxxx\n```\n\n资料来源：[docs/API.md:1-50]()\n\n## 认证与授权机制\n\n### 项目密钥认证\n\n每个项目拥有一个唯一的基础密钥 (`aid_proj_xxx`)，用于所有 API 调用的身份验证。\n\n```bash\ncurl https://api.agentsid.dev/api/v1/agents \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n### Agent 令牌认证\n\nAgent 注册后会获得独立的 Agent Token (`agt_xxx`)，用于特定 Agent 的身份标识和权限验证。\n\n```json\n{\n \"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\",\n \"agent_token\": \"agt_tok_abc123...\",\n \"name\": \"my-agent\",\n \"project_id\": \"proj_a1b2c3d4e5f6\",\n \"issued_at\": \"2026-03-29T00:00:00Z\",\n \"expires_at\": \"2026-04-29T00:00:00Z\",\n \"revoked_at\": null\n}\n```\n\nAgent Token 支持通过 `refresh` 端点重新签发，旧令牌自动失效。\n\n```bash\ncurl -X POST https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv/refresh \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n资料来源：[docs/API.md:100-150]()\n\n### 令牌验证与内省\n\n#### validate_token\n\n验证 Agent 令牌的有效性，可选择性地同时检查特定工具的调用权限。\n\n```python\nresult = await aid.validate_token(token, tool=\"delete_user\", params={\"user_id\": \"u_789\"})\n# 返回: { valid: true, agent_id: \"agt_xxx\", permission: {...} }\n```\n\n返回结构：\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| `valid` | boolean | 令牌是否有效 |\n| `reason` | string | 无效时的原因 |\n| `agent_id` | string | 关联的 Agent ID |\n| `project_id` | string | 所属项目 ID |\n| `permission` | object | 当 tool 参数存在时返回权限检查结果 |\n\n#### introspect\n\n完整的令牌内省接口，返回更详细的状态信息。\n\n```python\nresult = await aid.introspect(token, tool=\"send_email\", params={\"recipient\": \"user@example.com\"})\n# 返回: { active: true, agent: {...}, claims: {...}, permissions: [...], delegationChain: [...] }\n```\n\n资料来源：[docs/API.md:200-250]()\n\n## 身份管理接口\n\n### 注册 Agent\n\n**端点：** `POST /api/v1/agents/register`\n\n创建新的 Agent 实例并获取唯一的 Agent Token。\n\n**请求参数：**\n\n| 字段 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `name` | string | 是 | Agent 名称（1-255字符） |\n| `permissions` | array | 否 | 初始权限规则数组 |\n| `metadata` | object | 否 | 附加元数据（最大 10KB） |\n\n```bash\ncurl -X POST https://api.agentsid.dev/api/v1/agents/register \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"claude-notes-agent\",\n \"permissions\": [\n {\"tool_pattern\": \"search_notes\", \"action\": \"allow\"},\n {\"tool_pattern\": \"delete_note\", \"action\": \"deny\"}\n ]\n }'\n```\n\n**响应示例：**\n\n```json\n{\n \"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\",\n \"agent_token\": \"agt_tok_abc123xyz...\",\n \"name\": \"claude-notes-agent\",\n \"created_at\": \"2026-03-25T14:30:00+00:00\"\n}\n```\n\n### 查询 Agent\n\n**端点：** `GET /api/v1/agents/{agent_id}`\n\n获取指定 Agent 的详细信息。\n\n```bash\ncurl https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n**错误码：**\n\n| 状态码 | 含义 |\n|--------|------|\n| 401 | 无效或缺失的 API 密钥 |\n| 404 | Agent 不存在或不属于当前项目 |\n\n### 更新 Agent\n\n**端点：** `PATCH /api/v1/agents/{agent_id}`\n\n更新 Agent 的名称或元数据，不影响令牌和权限。\n\n```bash\ncurl -X PATCH https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"updated-agent-name\"}'\n```\n\n### 刷新令牌\n\n**端点：** `POST /api/v1/agents/{agent_id}/refresh`\n\n签发新令牌并自动撤销所有旧令牌，支持自定义 TTL。\n\n```json\n{\n \"ttl_hours\": 720\n}\n```\n\n资料来源：[docs/API.md:150-200]()\n\n## 权限管理接口\n\n### 设置权限规则\n\n**端点：** `PUT /api/v1/agents/{agent_id}/permissions`\n\n替换指定 Agent 的所有权限规则。\n\n**权限规则结构：**\n\n| 字段 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `tool_pattern` | string | 是 | 工具名称或通配符模式（支持 `*`） |\n| `action` | string | 是 | `\"allow\"` 或 `\"deny\"` |\n| `conditions` | object | 否 | 参数约束（AND 逻辑） |\n| `priority` | integer | 否 | 规则优先级（0-1000，数值越高越先评估） |\n\n```python\nawait aid.set_permissions(\"agt_abc123\", [\n {\"tool_pattern\": \"search_*\", \"action\": \"allow\", \"priority\": 10},\n {\"tool_pattern\": \"delete_*\", \"action\": \"deny\", \"priority\": 20},\n {\n \"tool_pattern\": \"send_email\",\n \"action\": \"allow\",\n \"conditions\": {\"recipient_domain\": \"company.com\"},\n },\n])\n```\n\n**完整规则示例：**\n\n```json\n{\n \"version\": \"1.0\",\n \"agentId\": \"agent_abc123\",\n \"issuedAt\": \"2026-03-29T00:00:00Z\",\n \"expiresAt\": \"2026-04-29T00:00:00Z\",\n \"rules\": [\n {\n \"tool_pattern\": \"github.*\",\n \"action\": \"allow\",\n \"conditions\": {\n \"params\": { \"repo\": \"my-org/*\" },\n \"time_range\": { \"start\": \"09:00\", \"end\": \"17:00\" },\n \"max_rate\": 10\n },\n \"priority\": 100\n }\n ]\n}\n```\n\n资料来源：[server/src/api/permissions.py:1-80]()\n\n### 查询权限规则\n\n**端点：** `GET /api/v1/agents/{agent_id}/permissions`\n\n获取当前 Agent 的所有权限规则。\n\n```python\nrules = await aid.get_permissions(\"agt_abc123\")\n```\n\n### 权限检查\n\n**端点：** `POST /api/v1/check`\n\n检查 Agent 是否被允许调用特定工具。\n\n**请求参数：**\n\n| 字段 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `agent_id` | string | 是 | Agent 标识符 |\n| `tool` | string | 是 | 工具名称 |\n| `params` | object | 否 | 工具调用参数 |\n\n```bash\ncurl -X POST https://api.agentsid.dev/api/v1/check \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\", \"tool\": \"delete_memory\"}'\n```\n\n**响应示例（允许）：**\n\n```json\n{\n \"allowed\": true,\n \"reason\": \"Allowed by rule: save_memory\",\n \"matched_rule\": {\n \"tool_pattern\": \"save_memory\",\n \"action\": \"allow\"\n }\n}\n```\n\n**响应示例（拒绝）：**\n\n```json\n{\n \"allowed\": false,\n \"reason\": \"No matching rule -- default deny\",\n \"matched_rule\": null\n}\n```\n\n### 工具模式匹配\n\n| 模式 | 匹配示例 |\n|------|----------|\n| `*` | 任意单个工具名段 |\n| `**` | 任意工具名（含命名空间） |\n| `github.*` | github 命名空间下的所有工具 |\n| `filesystem.read_file` | 精确匹配单一工具 |\n| `!filesystem.write_*` | 取反——排除写入工具 |\n\n资料来源：[web/src/pages/spec.tsx:1-50]()\n\n## 审计日志接口\n\n### 查询审计日志\n\n**端点：** `GET /api/v1/audit/log`\n\n查询 Agent 的操作审计记录。\n\n**查询参数：**\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `agent_id` | string | 否 | 按 Agent ID 过滤 |\n| `tool` | string | 否 | 按工具名称过滤 |\n| `action` | string | 否 | 按操作类型过滤 |\n| `since` | string | 否 | ISO 8601 时间戳 |\n| `limit` | integer | 否 | 返回条数限制（默认 100） |\n| `offset` | integer | 否 | 分页偏移量 |\n\n```bash\ncurl \"https://api.agentsid.dev/api/v1/audit/log?agent_id=agt_xxx&limit=50\" \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n**响应结构：**\n\n```json\n{\n \"entries\": [\n {\n \"id\": 1,\n \"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\",\n \"tool\": \"send_email\",\n \"action\": \"allow\",\n \"timestamp\": \"2026-03-29T10:15:30Z\",\n \"params\": {\"recipient\": \"user@example.com\"},\n \"delegation_chain\": [\"root_agent\", \"agt_xxx\"]\n }\n ],\n \"total\": 1523,\n \"limit\": 50,\n \"offset\": 0\n}\n```\n\n### 验证完整性\n\n**端点：** `GET /api/v1/audit/verify`\n\n验证审计日志链的完整性，检测是否存在篡改。\n\n```bash\ncurl \"https://api.agentsid.dev/api/v1/audit/verify\" \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n**响应（完整）：**\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"message\": \"Integrity chain verified\"\n}\n```\n\n**响应（链断裂）：**\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n### 使用量统计\n\n**端点：** `GET /api/v1/audit/usage`\n\n获取当前项目的使用量和计划限制。\n\n```json\n{\n \"events_this_month\": 1200,\n \"events_limit\": 10000,\n \"agents_active\": 5,\n \"agents_limit\": 25,\n \"plan\": \"free\"\n}\n```\n\n资料来源：[server/src/api/audit.py:1-100]()\n\n## 审批流程接口\n\n### 创建审批请求\n\n当权限规则配置了审批门 (`approval_gates`) 时，工具调用会被暂停等待人工审批。\n\n**端点：** `POST /api/v1/approvals/request`\n\n```json\n{\n \"agent_id\": \"agt_xxx\",\n \"tool\": \"delete_user\",\n \"params\": {\"user_id\": \"u_789\"},\n \"reason\": \"User requested account deletion\"\n}\n```\n\n### 查询审批状态\n\n**端点：** `GET /api/v1/approvals/{request_id}`\n\n### 审批操作\n\n**端点：** `POST /api/v1/approvals/{request_id}/approve`\n\n或\n\n**端点：** `POST /api/v1/approvals/{request_id}/reject`\n\n```json\n{\n \"approver_id\": \"usr_admin001\",\n \"comment\": \"Verified with IT department\"\n}\n```\n\n资料来源：[server/src/api/approvals.py:1-60]()\n\n## Webhook 通知\n\n### 注册 Webhook\n\n**端点：** `POST /api/v1/webhooks`\n\n```json\n{\n \"url\": \"https://your-server.com/webhook\",\n \"events\": [\"permission_denied\", \"agent_created\", \"approval_requested\"],\n \"secret\": \"whsec_your_signing_secret\"\n}\n```\n\n### Webhook 事件类型\n\n| 事件类型 | 触发时机 |\n|----------|----------|\n| `permission_denied` | 权限检查拒绝 |\n| `permission_allowed` | 权限检查通过 |\n| `agent_created` | 新 Agent 注册 |\n| `agent_token_refreshed` | Agent 令牌刷新 |\n| `approval_requested` | 提交审批请求 |\n| `approval_completed` | 审批完成 |\n\n### Webhook 签名验证\n\nWebhook 请求包含 `X-AgentsID-Signature` 头，使用 HMAC-SHA256 签名：\n\n```python\nimport hmac\nimport hashlib\n\ndef verify_webhook(payload: bytes, signature: str, secret: str) -> bool:\n expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()\n return hmac.compare_digest(f\"sha256={expected}\", signature)\n```\n\n资料来源：[server/src/api/webhooks.py:1-80]()\n\n## 团队协作接口\n\n### 创建团队\n\n**端点：** `POST /api/v1/teams`\n\n```json\n{\n \"name\": \"Data Processing Team\",\n \"description\": \"Handles data ETL pipelines\"\n}\n```\n\n### 添加 Agent 到团队\n\n**端点：** `POST /api/v1/teams/{team_id}/members`\n\n```json\n{\n \"agent_id\": \"agt_xxx\",\n \"role\": \"processor\"\n}\n```\n\n### 团队权限继承\n\n团队成员可以继承团队级别的权限规则，优先级低于个人规则。\n\n```mermaid\ngraph TD\n A[个人规则] --> B{优先级判断}\n C[团队规则] --> B\n D[项目规则] --> B\n B --> E[最终权限]\n \n style A fill:#90EE90\n style C fill:#87CEEB\n style D fill:#FFB6C1\n style E fill:#FFD700\n```\n\n资料来源：[server/src/api/teams.py:1-70]()\n\n## 错误处理\n\n### 错误响应格式\n\n```json\n{\n \"error\": {\n \"code\": \"PERMISSION_DENIED\",\n \"message\": \"Agent agt_xxx is not authorized to call tool delete_user\",\n \"details\": {\n \"agent_id\": \"agt_xxx\",\n \"tool\": \"delete_user\"\n }\n }\n}\n```\n\n### 常见错误码\n\n| 错误码 | HTTP 状态 | 描述 |\n|--------|-----------|------|\n| `INVALID_API_KEY` | 401 | API 密钥无效或缺失 |\n| `AGENT_NOT_FOUND` | 404 | 指定的 Agent 不存在 |\n| `PERMISSION_DENIED` | 403 | 权限检查拒绝 |\n| `INVALID_TOKEN` | 401 | Agent Token 无效或已过期 |\n| `RATE_LIMITED` | 429 | 请求频率超限 |\n| `VALIDATION_ERROR` | 400 | 请求参数验证失败 |\n\n资料来源：[docs/API.md:300-350]()\n\n## SDK 使用示例\n\n### Python SDK\n\n```python\nfrom agentsid import AgentsID\n\nasync def main():\n aid = AgentsID(api_key=\"aid_proj_xR7kM2pQ9...\")\n \n # 注册 Agent\n agent = await aid.register_agent(\"my-agent\", permissions=[\n {\"tool_pattern\": \"search_*\", \"action\": \"allow\"},\n {\"tool_pattern\": \"delete_*\", \"action\": \"deny\"}\n ])\n \n # 检查权限\n result = await aid.check_permission(\n agent[\"agent_id\"], \n \"delete_file\",\n params={\"path\": \"/data/users.csv\"}\n )\n \n if not result[\"allowed\"]:\n print(f\"拒绝原因: {result['reason']}\")\n```\n\n### TypeScript SDK\n\n```typescript\nimport { AgentsID } from '@agentsid/sdk';\n\nconst aid = new AgentsID({ apiKey: 'aid_proj_xR7kM2pQ9...' });\n\n// 验证令牌\nconst validation = await aid.validateToken(token, {\n tool: 'send_email',\n params: { recipient: 'user@example.com' }\n});\n\n// 查询审计日志\nconst logs = await aid.getAuditLog({\n agentId: 'agt_xxx',\n since: '2026-03-01',\n limit: 100\n});\n```\n\n资料来源：[sdk-python/README.md:1-100]()\n\n## 速率限制\n\n| 计划 | 每分钟请求数 | 每小时请求数 |\n|------|-------------|-------------|\n| free | 60 | 1,000 |\n| pro | 300 | 10,000 |\n| enterprise | 1,000 | 无限制 |\n\n速率限制响应头：\n- `X-RateLimit-Limit`: 当前限制\n- `X-RateLimit-Remaining`: 剩余请求数\n- `X-RateLimit-Reset`: 重置时间戳\n\n资料来源：[docs/API.md:350-400]()\n\n## 总结\n\nAgentsID 后端 API 提供了一套完整的 Agent 身份认证与权限管理解决方案，支持：\n\n- **多层级认证**：项目密钥 + Agent Token 双层认证体系\n- **灵活的权限规则**：基于通配符模式的条件约束\n- **完整的审计追溯**：不可篡改的审计日志链\n- **灵活的审批流程**：支持人工介入的审批门机制\n- **事件驱动通知**：Webhook 实时推送关键事件\n\n所有接口均遵循 RESTful 规范，提供一致的错误处理和响应格式，便于与各种 Agent 框架集成。\n\n---\n\n\n\n## 核心业务服务\n\n### 相关页面\n\n相关主题：[后端 API 接口](#page-api-endpoints), [数据模型与数据库](#page-data-models), [项目介绍](#page-introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [server/src/services/identity.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/identity.py)\n- [server/src/services/permission.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/permission.py)\n- [server/src/services/approval.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/approval.py)\n- [server/src/services/audit.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/audit.py)\n- [server/src/services/notifications.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/notifications.py)\n- [server/src/services/subagent_profiles.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/services/subagent_profiles.py)\n- [server/src/config/subagent_profiles.yaml](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/config/subagent_profiles.yaml)\n
\n\n# 核心业务服务\n\nAgentsID 的核心业务服务层是整个平台的中枢模块，负责管理智能体的身份认证、权限控制、审批流程、审计追踪、通知推送以及子智能体配置等关键功能。该服务层采用模块化架构设计，通过 RESTful API 与前端仪表盘及客户端 SDK 进行交互，为 Agent-MCP（Model Context Protocol）生态系统提供安全可靠的身份治理基础设施。\n\n## 服务架构总览\n\nAgentsID 的核心业务服务由六个主要微服务组成，每个服务专注于特定业务领域，通过标准接口进行通信协作。\n\n```mermaid\ngraph TD\n A[客户端 SDK] --> B[API 网关]\n B --> C[身份服务
identity.py]\n B --> D[权限服务
permission.py]\n B --> E[审批服务
approval.py]\n B --> F[审计服务
audit.py]\n B --> G[通知服务
notifications.py]\n B --> H[子智能体配置服务
subagent_profiles.py]\n \n C --> I[(身份数据库)]\n D --> J[(权限数据库)]\n E --> K[(审批队列)]\n F --> L[(审计日志库)]\n G --> M[(通知通道)]\n H --> N[(配置文件)]\n```\n\n### 服务组件概览表\n\n| 服务名称 | 源文件 | 主要职责 |\n|---------|--------|----------|\n| 身份服务 | `identity.py` | 智能体注册、Token 生成与验证、项目密钥管理 |\n| 权限服务 | `permission.py` | 工具模式匹配、权限规则评估、访问控制决策 |\n| 审批服务 | `approval.py` | 需要审批操作的队列管理、人工审批流程处理 |\n| 审计服务 | `audit.py` | 操作日志记录、哈希链完整性、审计验证 |\n| 通知服务 | `notifications.py` | 审批请求通知、事件告警、用户提醒 |\n| 子智能体配置服务 | `subagent_profiles.py` | 预定义智能体模板、权限配置方案管理 |\n\n## 身份服务\n\n身份服务（Identity Service）是 AgentsID 平台的基础安全组件，负责所有与智能体身份相关的核心操作。该服务维护智能体的注册生命周期，生成不可伪造的身份凭证，并提供完整的验证机制确保每个智能体的合法性。\n\n### 身份令牌体系\n\nAgentsID 采用双层令牌体系进行身份认证：\n\n```mermaid\ngraph LR\n A[项目密钥
aid_proj_xxx] --> C[项目级别认证]\n B[智能体令牌
aid_tok_xxx] --> C\n \n C --> D[智能体身份验证]\n C --> E[权限检查]\n```\n\n| 令牌类型 | 用途 | 作用域 |\n|---------|------|--------|\n| 项目密钥（Project Key） | 标识项目，初始注册时使用 | 项目内所有智能体 |\n| 智能体令牌（Agent Token） | 标识特定智能体身份 | 单个智能体的操作授权 |\n\n智能体注册后返回的令牌包含 HMAC 签名验证所需的元数据，支持快速验证而不暴露实际密钥材料。资料来源：[web/src/pages/guides.tsx]()\n\n### 智能体注册流程\n\n```mermaid\nsequenceDiagram\n participant SDK\n participant API as API 网关\n participant Identity as 身份服务\n participant DB as 数据库\n \n SDK->>API: POST /api/v1/agents/register\n API->>Identity: 创建智能体记录\n Identity->>DB: 存储元数据\n Identity->>Identity: 生成 agent_token\n Identity->>DB: 存储令牌哈希\n DB-->>Identity: 确认写入\n Identity-->>API: 返回 {agent_id, agent_token}\n API-->>SDK: 完成注册\n```\n\n注册接口接收智能体名称和权限配置列表，返回唯一的 `agent_id` 和加密的 `agent_token`。令牌有效期通过 TTL 参数可配置，到期后需重新注册或续期。资料来源：[web/src/pages/guides.tsx]()\n\n### 令牌验证\n\n验证接口 `/api/v1/validate` 执行三项核心检查：\n\n1. **签名验证**：检查 HMAC 签名是否与存储的哈希匹配\n2. **有效期验证**：确认令牌未过期\n3. **撤销状态验证**：检查令牌是否已被主动撤销\n\n验证失败的错误信息采用统一格式，防止信息泄露攻击。资料来源：[web/src/pages/docs.tsx]()\n\n```json\n{\n \"valid\": false,\n \"reason\": \"Token validation failed\"\n}\n```\n\n## 权限服务\n\n权限服务（Permission Service）实现了基于工具模式的细粒度访问控制机制，是 AgentsID 安全模型的核心组件。该服务通过 glob 模式匹配支持灵活的权限规则定义，允许管理员以声明式方式控制智能体可执行的工具范围。\n\n### 权限规则结构\n\n权限策略采用 JSON 格式定义，包含版本、时间戳和规则数组：\n\n```json\n{\n \"version\": \"1.0\",\n \"agentId\": \"agent_abc123\",\n \"issuedAt\": \"2026-03-29T00:00:00Z\",\n \"expiresAt\": \"2026-04-29T00:00:00Z\",\n \"rules\": [\n {\n \"tool_pattern\": \"read_file\",\n \"action\": \"allow\"\n },\n {\n \"tool_pattern\": \"delete_*\",\n \"action\": \"deny\"\n }\n ]\n}\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 工具模式匹配规则\n\n| 模式 | 含义 | 示例匹配 |\n|------|------|----------|\n| `*` | 单个路径段通配符 | `read_file` ✓，`read_file_abc` ✗ |\n| `**` | 多级路径通配符 | `github.*` ✓，`github.repo.read` ✓ |\n| `!` 前缀 | 取反排除 | `!filesystem.write_*` 排除所有写操作 |\n| `?` | 单字符通配 | `file_?` 匹配 `file_a`、`file_b` |\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 权限检查流程\n\n```mermaid\ngraph TD\n A[工具调用请求] --> B[提取工具名称]\n B --> C{匹配权限规则}\n C -->|找到匹配规则| D{规则 action}\n C -->|无匹配规则| E[默认拒绝]\n D -->|allow| F[允许执行]\n D -->|deny| G[拒绝执行]\n D -->|requires_approval| H[进入审批队列]\n \n E --> I[记录审计日志
decision: deny]\n F --> J[记录审计日志
decision: allow]\n G --> J\n H --> K[记录审计日志
decision: pending]\n```\n\n### 权限检查 API\n\n端点 `POST /api/v1/check` 接收智能体 ID 和工具名称，返回权限决策结果：\n\n```json\n// 允许访问\n{\n \"allowed\": true,\n \"reason\": \"Allowed by rule: save_memory\",\n \"matched_rule\": {\n \"tool_pattern\": \"save_memory\",\n \"action\": \"allow\"\n }\n}\n\n// 拒绝访问\n{\n \"allowed\": false,\n \"reason\": \"No matching rule -- default deny\",\n \"matched_rule\": null\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 条件权限\n\n权限规则支持参数级条件限制，可精细化控制智能体仅能操作特定资源：\n\n```json\n{\n \"tool_pattern\": \"read_customer\",\n \"action\": \"allow\",\n \"conditions\": {\n \"params\": { \"customer_id\": \"cust_123\" }\n }\n}\n```\n\n此规则表示仅允许读取 ID 为 `cust_123` 的客户信息，其他客户数据访问将被拒绝。资料来源：[web/src/pages/guides.tsx]()\n\n## 审批服务\n\n审批服务（Approval Service）处理需要人工介入的权限请求。当权限规则指定 `requires_approval` 动作时，对应的工具调用不会立即执行，而是进入审批队列等待授权。\n\n### 审批工作流\n\n```mermaid\ngraph LR\n A[工具调用请求] -->|requires_approval| B[审批队列]\n B --> C{等待审批}\n C -->|批准| D[执行工具]\n C -->|拒绝| E[返回拒绝响应]\n C -->|超时| F[自动拒绝]\n```\n\n### 预定义权限模板\n\n系统提供多种权限模板供快速配置：\n\n| 模板名称 | 允许操作 | 需要审批 | 拒绝操作 |\n|---------|---------|---------|---------|\n| code-assistant | read_file, search_code, list_files | write_file | execute_*, deploy_*, delete_* |\n| notes-agent | search_notes, save_note, list_notes | - | delete_note, admin_* |\n\n资料来源：[web/src/pages/guides.tsx]()\n\n## 审计服务\n\n审计服务（Audit Service）是 AgentsID 安全合规的核心支柱，提供完整、不可篡改的操作记录追踪能力。所有工具调用决策都会被记录在审计日志中，形成可追溯的安全事件链。\n\n### 审计日志结构\n\n每条审计日志条目包含完整的上下文信息：\n\n```json\n{\n \"entryId\": \"entry_abc123\",\n \"timestamp\": \"2026-03-29T12:34:56.789Z\",\n \"agentId\": \"agent_def456\",\n \"delegationId\": \"del_xyz789\",\n \"tool\": \"github.push_files\",\n \"parameters\": { \"owner\": \"myorg\", \"repo\": \"myrepo\", \"branch\": \"main\" },\n \"decision\": \"allow\",\n \"matchedRule\": 2,\n \"constraintsEvaluated\": [\"rateLimit\", \"schedule\"],\n \"durationMs\": 3,\n \"prevEntryHash\": \"sha256:e3b0c44298fc1c149afb...\",\n \"entryHash\": \"sha256:a665a45920422f9d417e...\"\n}\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 哈希链完整性机制\n\n```mermaid\ngraph LR\n A[Genesis] -->|prevEntryHash| B[Entry 1]\n B -->|prevEntryHash| C[Entry 2]\n C -->|prevEntryHash| D[Entry 3]\n \n B -->|SHA-256| A\n C -->|SHA-256| B\n D -->|SHA-256| C\n```\n\n哈希链算法确保任何对历史条目的篡改都会导致后续所有哈希值失效：\n\n```\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n// 首条记录使用 prevEntryHash: \"genesis\"\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 链完整性验证\n\n通过 API `GET /api/v1/audit/verify` 可验证审计链的完整性：\n\n```json\n// 验证通过\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"first_entry_id\": \"entry_001\"\n}\n\n// 链断裂（检测到篡改）\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 仪表盘审计条目展示\n\n前端组件 `AuditFeed.tsx` 展示审计条目的关键字段：\n\n| 显示字段 | 来源字段 | 说明 |\n|---------|---------|------|\n| 决策状态 | `decision` | allow/deny/pending |\n| 工具名称 | `tool` | 被调用的工具标识符 |\n| 智能体 ID | `agent_id` | 发起调用的智能体 |\n| 时间戳 | `created_at` | 操作发生的 UTC 时间 |\n| 委托链 | `delegation_chain` | 多层委托时的完整链路 |\n\n资料来源：[web/src/components/dashboard/AuditFeed.tsx]()\n\n## 通知服务\n\n通知服务（Notification Service）负责向相关人员推送关键事件通知，确保安全操作的及时响应。\n\n### 通知触发场景\n\n| 事件类型 | 通知目标 | 通知方式 |\n|---------|---------|---------|\n| 审批请求 | 审批管理员 | 应用内通知 / 邮件 |\n| 权限拒绝 | 智能体所有者 | SDK 内置响应 |\n| 审计异常告警 | 安全团队 | 系统告警 |\n| 令牌即将过期 | 智能体所有者 | 邮件提醒 |\n\n通知服务与审批服务紧密集成，在审批请求进入队列时自动触发通知流程。\n\n## 子智能体配置服务\n\n子智能体配置服务（Subagent Profiles Service）提供预定义的智能体模板和权限配置方案，简化新智能体的注册和配置流程。\n\n### 配置文件结构\n\n系统通过 YAML 配置文件定义子智能体模板：\n\n```yaml\n# subagent_profiles.yaml\nprofiles:\n - name: \"code-assistant\"\n permissions:\n - tool_pattern: \"read_file\"\n action: \"allow\"\n - tool_pattern: \"write_file\"\n action: \"allow\"\n requires_approval: true\n - name: \"data-analyst\"\n permissions:\n - tool_pattern: \"query_*\"\n action: \"allow\"\n```\n\n资料来源：[server/src/config/subagent_profiles.yaml]()\n\n### 配置文件加载机制\n\n`subagent_profiles.py` 服务负责解析 YAML 配置并将其转换为运行时权限规则，支持热更新而无需重启服务。\n\n## 数据保留与合规\n\n### 隐私数据处理\n\n| 数据类型 | 处理方式 | 保留策略 |\n|---------|---------|---------|\n| 原始 API 密钥 | 不存储，仅存哈希 | 永久（哈希形式） |\n| 智能体令牌 | HMAC 签名验证 | TTL 期限内 |\n| 审计日志 | 哈希链保护 | 根据订阅计划 |\n| 个人身份信息 | 加密存储 | 可导出/删除 |\n\nAgentsID 明确声明**不销售用户数据**，分析工具（PostHog）采用 opt-in 机制。资料来源：[web/src/pages/privacy.tsx]()\n\n### 审计日志保留\n\n| 订阅计划 | 保留期限 | 可导出 |\n|---------|---------|--------|\n| Free | 7 天 | 是（JSON 格式） |\n| Pro | 90 天 | 是 |\n| Enterprise | 自定义 | 是 |\n\n降级套餐时，审计日志会在 30 天内裁剪至新计划保留期限。资料来源：[web/src/pages/terms.tsx]()\n\n## 服务间交互流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant SDK as 客户端 SDK\n participant API as API 网关\n participant Id as 身份服务\n participant Perm as 权限服务\n participant Audit as 审计服务\n participant Notif as 通知服务\n \n User->>SDK: 发起工具调用\n SDK->>API: 验证令牌 + 检查权限\n API->>Id: 验证智能体身份\n Id-->>API: 身份有效\n API->>Perm: 评估权限规则\n Perm-->>API: 权限决策\n API->>Audit: 记录审计日志\n Audit-->>API: 确认写入\n Alt 需要审批\n API->>Notif: 发送审批通知\n User->>API: 审批决策\n end\n API-->>SDK: 返回结果\n SDK-->>User: 操作完成/拒绝\n```\n\n## 总结\n\nAgentsID 的核心业务服务层通过六个协同工作的微服务模块，构建了一个完整、安全、可审计的智能体身份与权限管理平台。身份服务确保每个智能体拥有唯一的可信身份，权限服务提供细粒度的访问控制，审批服务支持人工介入的关键决策点，审计服务提供不可篡改的操作追踪，通知服务保证关键事件的及时响应，子智能体配置服务简化了运维管理流程。所有这些服务共同遵循最小权限原则和隐私保护设计，为 Agent-MCP 生态系统提供企业级的安全保障。\n\n---\n\n\n\n## 数据模型与数据库\n\n### 相关页面\n\n相关主题：[核心业务服务](#page-core-services), [后端 API 接口](#page-api-endpoints)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [server/src/models/models.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/models/models.py)\n- [server/src/core/database.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/src/core/database.py)\n- [server/alembic/versions/21eca51078a1_add_audit_integrity_hash_chain.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/alembic/versions/21eca51078a1_add_audit_integrity_hash_chain.py)\n- [server/alembic/versions/35a9e5cf497f_add_encrypted_api_key_to_projects.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/alembic/versions/35a9e5cf497f_add_encrypted_api_key_to_projects.py)\n- [server/alembic/versions/a1b2c3d4e5f6_add_teams_and_team_members.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/alembic/versions/a1b2c3d4e5f6_add_teams_and_team_members.py)\n- [server/alembic/versions/c7e9f2b4a1d8_add_agent_type_and_parent.py](https://github.com/AgentsID-dev/agentsid/blob/main/server/alembic/versions/c7e9f2b4a1d8_add_agent_type_and_parent.py)\n
\n\n# 数据模型与数据库\n\n## 概述\n\nAgentsID 的数据模型设计围绕 **Agent（代理）授权管理** 和 **审计追踪** 两个核心功能展开。系统采用关系型数据库（PostgreSQL）存储核心实体，通过 Alembic 管理数据库迁移，确保 schema 版本可控。\n\n主要数据模型包括：\n\n- **Project（项目）**：顶级容器，存储 API 密钥加密值和项目配置\n- **Agent（代理）**：具体的 AI 代理实例，属于某个项目\n- **Team & TeamMember（团队）**：支持多用户协作的团队机制\n- **AuditEntry（审计条目）**：记录所有工具调用决策，形成哈希链保证完整性\n- **Rule（规则）**：定义代理的权限规则和约束条件\n\n## 核心数据模型\n\n### Project（项目）\n\nProject 是系统的顶级容器，每个项目拥有独立的 `project_id` 和加密存储的 API 密钥。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 项目唯一标识 |\n| `api_key_hash` | String | API 密钥的 SHA-256 哈希值 |\n| `encrypted_api_key` | String | 使用 Fernet 对称加密存储的 API 密钥 |\n| `created_at` | DateTime | 创建时间 |\n| `plan` | String | 订阅计划（free/pro 等） |\n\n资料来源：[35a9e5cf497f_add_encrypted_api_key_to_projects.py]() \n\n**安全设计**：系统不存储原始 API 密钥，仅存储哈希值用于验证和加密后的副本用于后台通信。资料来源：[web/src/pages/privacy.tsx]()\n\n### Agent（代理）\n\nAgent 代表一个具体的 AI 代理实例，属于特定项目。代理可以配置权限规则，并通过 agent token 进行身份验证。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | String | 代理唯一标识（如 `agt_` 前缀） |\n| `project_id` | UUID | 所属项目 ID |\n| `name` | String | 代理名称 |\n| `agent_type` | String | 代理类型 |\n| `parent_id` | UUID | 父代理 ID（支持代理层级） |\n| `metadata` | JSON | 元数据字段 |\n| `created_at` | DateTime | 创建时间 |\n| `revoked_at` | DateTime | 撤销时间（null 表示活跃） |\n\n资料来源：[c7e9f2b4a1d8_add_agent_type_and_parent.py]()\n\n**代理层级**：系统支持代理的父子关系，允许构建代理树形结构，适用于复杂的多代理协作场景。\n\n```mermaid\ngraph TD\n P[Project] --> A1[Agent 1]\n P --> A2[Agent 2]\n A1 --> A3[Sub-Agent 1.1]\n A1 --> A4[Sub-Agent 1.2]\n A2 --> A5[Sub-Agent 2.1]\n```\n\n### Team（团队）与 TeamMember（团队成员）\n\n系统支持多用户协作，通过 Team 和 TeamMember 实现成员管理。\n\n| Team 字段 | 类型 | 说明 |\n|-----------|------|------|\n| `id` | UUID | 团队唯一标识 |\n| `name` | String | 团队名称 |\n| `created_at` | DateTime | 创建时间 |\n\n| TeamMember 字段 | 类型 | 说明 |\n|-----------------|------|------|\n| `id` | UUID | 成员唯一标识 |\n| `team_id` | UUID | 所属团队 ID |\n| `user_id` | UUID | 用户 ID |\n| `role` | String | 角色（owner/member 等） |\n| `joined_at` | DateTime | 加入时间 |\n\n资料来源：[a1b2c3d4e5f6_add_teams_and_team_members.py]()\n\n### AuditEntry（审计条目）\n\n审计条目是 AgentsID 安全模型的核心，每条工具调用决策都会生成一个不可变的审计记录。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `entry_id` | String | 条目唯一标识（如 `entry_abc123`） |\n| `agent_id` | String | 执行操作的代理 ID |\n| `delegation_id` | String | 委托链 ID |\n| `tool` | String | 调用的工具名称（如 `github.push_files`） |\n| `parameters` | JSON | 工具调用参数 |\n| `decision` | String | 决策结果（allow/deny） |\n| `matched_rule` | Integer | 匹配的规则序号 |\n| `constraints_evaluated` | JSON | 评估的约束列表 |\n| `duration_ms` | Integer | 处理耗时（毫秒） |\n| `prev_entry_hash` | String | 前一条目哈希 |\n| `entry_hash` | String | 当前条目哈希（SHA-256） |\n| `timestamp` | DateTime | 时间戳 |\n| `delegation_chain` | JSON | 委托链信息 |\n| `delegated_by` | String | 委托方信息 |\n\n资料来源：[21eca51078a1_add_audit_integrity_hash_chain.py]()\n\n## 哈希链完整性机制\n\n### 概述\n\n审计日志采用 **哈希链（Hash Chain）** 技术确保数据完整性。每条审计条目都包含前一条目的哈希值，形成一条不可篡改的链式结构。\n\n### 哈希计算规则\n\n```mermaid\ngraph LR\n A[Genesis Entry
prevEntryHash: null] --> B[Entry 1
entryHash = SHA-256(Entry 1 + null)]\n B --> C[Entry 2
entryHash = SHA-256(Entry 2 + Hash(Entry 1))]\n C --> D[Entry 3
entryHash = SHA-256(Entry 3 + Hash(Entry 2))]\n```\n\n哈希计算公式：\n\n```python\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n# 创世条目的 prevEntryHash 为 \"genesis\"\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 验证流程\n\n系统提供 `/api/v1/audit/verify` 接口验证审计链完整性：\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"chain_length\": 1523,\n \"message\": \"Integrity chain verified\"\n}\n```\n\n验证失败响应：\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 验证算法\n\n```python\nfunction verifyChain(entries: AuditEntry[]): boolean {\n for (let i = 1; i < entries.length; i++) {\n const prev = entries[i - 1]\n const curr = entries[i]\n // 验证 prev.entryHash == curr.prevEntryHash\n }\n}\n```\n\n## 权限规则模型\n\n### 规则结构\n\n每个代理可配置多条权限规则，每条规则定义特定工具的访问策略：\n\n```json\n{\n \"tools\": [\"github.push_files\"],\n \"action\": \"allow\",\n \"constraints\": [\n { \"type\": \"rateLimit\", \"max\": 10, \"windowSeconds\": 3600 },\n { \"type\": \"schedule\", \"daysOfWeek\": [1,2,3,4,5], \"hoursUTC\": [8, 20] }\n ]\n}\n```\n\n### 约束类型\n\n| 约束类型 | 说明 | 示例 |\n|----------|------|------|\n| `rateLimit` | 速率限制 | `{ \"max\": 100, \"windowSeconds\": 3600, \"scope\": \"agent\" }` |\n| `schedule` | 时间调度 | `{ \"daysOfWeek\": [1,2,3,4,5], \"hoursUTC\": [8,17] }` |\n| `budget` | 预算控制 | `{ \"currency\": \"usd\", \"max\": 10.00, \"windowSeconds\": 86400 }` |\n| `sequence` | 顺序约束 | `{ \"requires\": [\"filesystem.read_file\"], \"forbids\": [\"github.push_files\"] }` |\n| `sessionLimit` | 会话限制 | `{ \"max\": 5 }` |\n| `riskScore` | 风险评分 | `{ \"maxScore\": 0.7 }` |\n| `ipAllowlist` | IP 白名单 | `{ \"cidrs\": [\"10.0.0.0/8\", \"192.168.1.0/24\"] }` |\n| `chainDepth` | 链深度 | `{ \"max\": 2 }` |\n| `cooldown` | 冷却时间 | `{ \"seconds\": 300 }` |\n\n资料来源：[web/src/pages/spec.tsx]()\n\n## 数据库架构图\n\n```mermaid\nerDiagram\n PROJECT ||--o{ AGENT : contains\n PROJECT ||--o{ TEAM : owns\n TEAM ||--o{ TEAM_MEMBER : has\n AGENT ||--o{ AUDIT_ENTRY : generates\n AGENT }o--o| AGENT : parent_child\n PROJECT {\n uuid id PK\n string api_key_hash\n string encrypted_api_key\n string plan\n datetime created_at\n }\n AGENT {\n string id PK\n uuid project_id FK\n string name\n string agent_type\n uuid parent_id FK\n json metadata\n datetime created_at\n datetime revoked_at\n }\n AUDIT_ENTRY {\n string entry_id PK\n string agent_id FK\n string delegation_id\n string tool\n json parameters\n string decision\n json constraints_evaluated\n string prev_entry_hash\n string entry_hash\n datetime timestamp\n }\n TEAM {\n uuid id PK\n string name\n datetime created_at\n }\n TEAM_MEMBER {\n uuid id PK\n uuid team_id FK\n uuid user_id\n string role\n datetime joined_at\n }\n```\n\n## API 端点\n\n### 审计相关\n\n| 方法 | 路径 | 说明 |\n|------|------|------|\n| GET | `/api/v1/audit/verify` | 验证审计链完整性 |\n| GET | `/api/v1/audit/usage` | 获取当前使用量和限额 |\n| GET | `/api/v1/audit/entries` | 获取审计条目列表 |\n\n### 代理相关\n\n| 方法 | 路径 | 说明 |\n|------|------|------|\n| GET | `/api/v1/agents` | 列出项目下所有代理 |\n| POST | `/api/v1/agents` | 创建新代理 |\n| GET | `/api/v1/agents/{agent_id}` | 获取代理详情 |\n| PATCH | `/api/v1/agents/{agent_id}` | 更新代理信息 |\n\n资料来源：[web/src/pages/docs.tsx]()\n\n## 数据库连接管理\n\n系统使用 SQLAlchemy 作为 ORM，并通过连接池管理数据库连接：\n\n```python\n# server/src/core/database.py\n# 管理数据库会话生命周期\n# 提供依赖注入机制供 FastAPI 使用\n```\n\n资料来源：[server/src/core/database.py]()\n\n## 数据迁移策略\n\n系统使用 Alembic 管理数据库迁移，所有迁移文件位于 `server/alembic/versions/` 目录。迁移文件命名规范：`{hash}_{description}.py`。\n\n主要迁移历史：\n\n1. `35a9e5cf497f_add_encrypted_api_key_to_projects.py` - 为项目添加加密 API 密钥支持\n2. `21eca51078a1_add_audit_integrity_hash_chain.py` - 添加哈希链完整性字段\n3. `c7e9f2b4a1d8_add_agent_type_and_parent.py` - 添加代理类型和父子关系\n4. `a1b2c3d4e5f6_add_teams_and_team_members.py` - 添加团队功能\n\n## 安全特性\n\n1. **API 密钥存储**：原始密钥仅存储哈希值用于验证，加密副本用于内部通信\n2. **审计不可变性**：哈希链机制确保审计记录不可篡改\n3. **代理撤销**：支持撤销代理令牌，保留审计历史\n4. **委托链追踪**：完整记录工具调用的委托路径\n\n## 总结\n\nAgentsID 的数据模型围绕**授权管理**和**审计合规**两个核心需求设计，通过关系型数据库存储项目、代理、团队和审计记录。哈希链机制提供了审计日志的完整性保证，支持事后验证和合规审查。\n\n---\n\n\n\n## TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python/Ruby/Java SDK](#page-sdk-other-languages), [核心业务服务](#page-core-services), [Setup CLI 与集成](#page-setup-cli)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [sdk-typescript/src/client.ts](https://github.com/AgentsID-dev/agentsid/blob/main/sdk-typescript/src/client.ts)\n- [sdk-typescript/src/middleware.ts](https://github.com/AgentsID-dev/agentsid/blob/main/sdk-typescript/src/middleware.ts)\n- [sdk-typescript/src/errors.ts](https://github.com/AgentsID-dev/agentsid/blob/main/sdk-typescript/src/errors.ts)\n- [sdk-typescript/src/types.ts](https://github.com/AgentsID-dev/agentsid/blob/main/sdk-typescript/src/types.ts)\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n
\n\n# TypeScript SDK\n\n## 概述\n\nAgentsID TypeScript SDK 是一个用于与 AgentsID 平台交互的官方客户端库。它提供了简洁的 API 接口，使开发者能够在其应用程序中集成 AI Agent 身份验证、权限管理和审计功能。\n\n该 SDK 支持创建、查询、更新和删除 Agent 实例，管理 API Token，以及执行工具调用的权限验证。通过统一的接口封装，开发者无需直接处理底层 HTTP 请求和响应解析。\n\n## 核心架构\n\n### 模块结构\n\n```mermaid\ngraph TD\n A[应用程序] --> B[TypeScript SDK]\n B --> C[client.ts
核心客户端]\n B --> D[middleware.ts
中间件组件]\n B --> E[errors.ts
错误处理]\n B --> F[types.ts
类型定义]\n C --> G[REST API
api.agentsid.dev]\n G --> H[数据库层]\n \n style A fill:#e1effe\n style G fill:#fff3cd\n style H fill:#f8d7da\n```\n\n### 客户端初始化\n\nSDK 通过 `AgentsID` 类进行初始化，需要提供项目 API Key 作为认证凭证。\n\n```typescript\nimport { AgentsID } from '@agentsid/sdk';\n\nconst client = new AgentsID({\n apiKey: process.env.AGENTSID_PROJECT_KEY,\n baseUrl: 'https://api.agentsid.dev' // 可选，默认值\n});\n```\n\n初始化参数说明：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `apiKey` | `string` | 是 | 项目 API Key，格式为 `aid_proj_xxx` |\n| `baseUrl` | `string` | 否 | API 基础 URL，默认为 `https://api.agentsid.dev` |\n| `timeout` | `number` | 否 | 请求超时时间（毫秒） |\n| `retry` | `RetryConfig` | 否 | 重试策略配置 |\n\n资料来源：[web/src/pages/docs.tsx:SDK_INIT_TABS]()\n\n## Agent 管理\n\n### 创建 Agent\n\n使用 `registerAgent` 方法创建新的 Agent 实例并获取其首个访问 Token。\n\n```typescript\nconst result = await client.registerAgent({\n name: 'production-agent',\n onBehalfOf: 'proj_xxx',\n permissions: ['read', 'write'],\n ttlHours: 24,\n metadata: { environment: 'production' }\n});\n```\n\n返回值结构：\n\n```typescript\n{\n agent: Agent,\n token: string,\n tokenId: string,\n expiresAt: string\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `agent` | `Agent` | Agent 对象详情 |\n| `token` | `string` | 新签发的访问 Token |\n| `tokenId` | `string` | Token 唯一标识符 |\n| `expiresAt` | `string` | Token 过期时间（ISO 8601 格式） |\n\n### 查询 Agent\n\n#### 获取单个 Agent\n\n```typescript\nconst agent = await client.getAgent('agt_7x9k2mNpQ4rS1tUv');\n```\n\n#### 列出所有 Agent\n\n```typescript\nconst agents = await client.listAgents({\n status: 'active', // 可选：active | revoked | expired\n limit: 50 // 可选：返回数量上限\n});\n```\n\n### 更新 Agent\n\n更新 Agent 的名称或元数据信息：\n\n```typescript\nconst updated = await client.updateAgent('agt_7x9k2mNpQ4rS1tUv', {\n name: 'new-agent-name',\n metadata: { version: '2.0' }\n});\n```\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `agentId` | `string` | 是 | Agent 唯一标识符 |\n| `name` | `string` | 否 | 新名称（1-255 字符） |\n| `metadata` | `object` | 否 | 自定义键值对元数据 |\n\n资料来源：[web/src/pages/docs.tsx:SDK_INIT_TABS]()\n\n## Token 管理\n\n### 刷新 Token\n\n当 Token 即将过期时，可使用 `refreshToken` 方法签发新 Token，同时自动吊销所有旧 Token。\n\n```typescript\nconst result = await client.refreshToken('agt_7x9k2mNpQ4rS1tUv', {\n ttlHours: 48\n});\n```\n\n响应示例：\n\n```json\n{\n \"agent_id\": \"agt_7x9k2mNpQ4rS1tUv\",\n \"token\": \"aid_tok_newtoken...\",\n \"token_id\": \"tok_f6e5d4c3b2a1\",\n \"expires_at\": \"2026-03-27 14:30:00+00:00\"\n}\n```\n\n### Token 验证\n\nSDK 提供 `validate` 方法用于验证 Token 并检查特定操作的权限：\n\n```typescript\nconst result = await client.validate({\n token: 'aid_tok_eyJzdWIiOiJhZ3RfN3g5azJt...',\n tool: 'save_memory',\n params: { category: 'note' }\n});\n```\n\n响应结构：\n\n```typescript\n// Token 有效且有权执行\n{\n valid: true,\n allowed: true,\n matched_rule: {\n tool_pattern: \"save_memory\",\n action: \"allow\"\n }\n}\n\n// Token 无效\n{\n valid: false,\n reason: \"Token validation failed\"\n}\n```\n\n:::info 安全说明\n为防止信息泄露，SDK 对过期 Token、无效签名、已吊销 Token 和项目不匹配的情况返回相同的通用错误消息。\n:::\n\n资料来源：[web/src/pages/docs.tsx:SDK_INIT_TABS]()\n\n## 权限委托\n\n### 创建子 Agent\n\n通过 `delegate` 方法创建具有受限权限的子 Agent：\n\n```typescript\nconst childAgent = await client.delegate({\n parentAgentId: 'agt_parent_xxx',\n name: 'limited-child-agent',\n permissions: ['read-only']\n});\n```\n\n子 Agent 继承父 Agent 的身份，但在权限范围、有效期等维度受到限制。\n\n## 审计功能\n\n### 查询审计日志\n\n```typescript\nconst logs = await client.audit.list({\n agentId: 'agt_xxx',\n limit: 100,\n offset: 0\n});\n```\n\n### 验证完整性链\n\n```typescript\nconst result = await client.audit.verify();\n```\n\n响应示例（链完整）：\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"message\": \"Integrity chain verified\"\n}\n```\n\n响应示例（链损坏）：\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n### 用量查询\n\n```typescript\nconst usage = await client.audit.usage();\n```\n\n响应示例：\n\n```json\n{\n \"events_this_month\": 1200,\n \"events_limit\": 10000,\n \"agents_active\": 5,\n \"agents_limit\": 25,\n \"plan\": \"free\"\n}\n```\n\n## 错误处理\n\nSDK 定义了统一的错误类型体系，便于调用方进行错误捕获和处理：\n\n```typescript\nimport { AgentsIDError, AuthError, ValidationError, NotFoundError } from '@agentsid/sdk';\n\ntry {\n const agent = await client.getAgent('invalid-id');\n} catch (error) {\n if (error instanceof AuthError) {\n // 处理认证错误\n } else if (error instanceof NotFoundError) {\n // 处理资源不存在\n } else if (error instanceof ValidationError) {\n // 处理参数验证错误\n }\n}\n```\n\n| 错误类型 | HTTP 状态码 | 说明 |\n|----------|-------------|------|\n| `AgentsIDError` | - | 基础错误类 |\n| `AuthError` | 401 | API Key 无效或缺失 |\n| `NotFoundError` | 404 | Agent 或资源不存在 |\n| `ValidationError` | 400 | 请求参数验证失败 |\n| `RateLimitError` | 429 | 请求频率超限 |\n| `ServerError` | 500+ | 服务器内部错误 |\n\n资料来源：[sdk-typescript/src/errors.ts]()\n\n## 中间件集成\n\n### MCP 服务器中间件\n\nSDK 提供中间件组件，用于保护 MCP（Model Context Protocol）服务器的工具调用：\n\n```typescript\nimport { createAgentsIDMiddleware } from '@agentsid/sdk/middleware';\n\nconst middleware = createAgentsIDMiddleware({\n projectKey: process.env.AGENTSID_PROJECT_KEY,\n agentToken: process.env.AGENTSID_AGENT_TOKEN,\n url: 'https://api.agentsid.dev'\n});\n```\n\n完整集成示例：\n\n```typescript\n// server.mjs\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { createAgentsIDMiddleware } from '@agentsid/sdk/middleware';\n\nconst AGENTSID_PROJECT_KEY = process.env.AGENTSID_PROJECT_KEY;\nconst AGENTSID_AGENT_TOKEN = process.env.AGENTSID_AGENT_TOKEN;\n\nconst validateToolCall = async (tool, params) => {\n const response = await fetch(`${AGENTSID_URL}/api/v1/validate`, {\n method: 'POST',\n headers: {\n 'Authorization': `Bearer ${AGENTSID_PROJECT_KEY}`,\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n token: AGENTSID_AGENT_TOKEN,\n tool,\n params\n })\n });\n \n const result = await response.json();\n if (!result.valid || !result.permission?.allowed) {\n throw new Error(`Tool ${tool} is not allowed`);\n }\n return result;\n};\n\n// MCP 服务器工具定义\nconst server = new McpServer({ name: 'protected-notes', version: '1.0.0' });\n\nserver.tool(\n 'save_memory',\n 'Save a note to memory',\n { category: z.enum(['note', 'preference']), content: z.string() },\n async ({ category, content }) => {\n await validateToolCall('save_memory', { category, content });\n // 执行实际的保存逻辑\n return { success: true };\n }\n);\n```\n\n### 工具验证流程\n\n```mermaid\nsequenceDiagram\n participant A as AI Agent\n participant M as MCP Server\n participant S as AgentsID SDK\n participant P as AgentsID API\n \n A->>M: 调用工具 save_memory\n M->>S: validate(tool, params)\n S->>P: POST /api/v1/validate\n P->>P: 验证 Token 和权限规则\n alt 允许执行\n P-->>S: { valid: true, allowed: true }\n S-->>M: 验证通过\n M->>M: 执行工具逻辑\n M-->>A: 返回结果\n else 拒绝执行\n P-->>S: { valid: true, allowed: false }\n S-->>M: 抛出错误\n M-->>A: 权限拒绝错误\n end\n```\n\n资料来源：[web/src/pages/guides.tsx:validateToolCall]()\n\n## 类型定义\n\nSDK 导出完整的 TypeScript 类型定义，确保开发时的类型安全和自动补全支持。\n\n### 核心类型\n\n```typescript\n// Agent 实例\ninterface Agent {\n id: string;\n name: string;\n project_id: string;\n status: 'active' | 'revoked' | 'expired';\n created_at: string;\n revoked_at: string | null;\n metadata: Record;\n}\n\n// Token 信息\ninterface Token {\n id: string;\n agent_id: string;\n created_at: string;\n expires_at: string;\n revoked_at: string | null;\n}\n\n// 审计日志条目\ninterface AuditEntry {\n id: string;\n agent_id: string;\n tool: string;\n params: Record;\n result: 'allow' | 'deny';\n reason: string;\n created_at: string;\n}\n\n// 用量信息\ninterface UsageStats {\n events_this_month: number;\n events_limit: number;\n agents_active: number;\n agents_limit: number;\n plan: string;\n}\n```\n\n资料来源：[sdk-typescript/src/types.ts]()\n\n## 环境变量\n\n| 变量名 | 说明 | 必填 |\n|--------|------|------|\n| `AGENTSID_PROJECT_KEY` | 项目 API Key | 是 |\n| `AGENTSID_AGENT_TOKEN` | Agent 访问 Token | 是 |\n| `AGENTSID_URL` | API 地址（默认：https://api.agentsid.dev） | 否 |\n\n## 最佳实践\n\n### 1. 安全存储凭证\n\n始终通过环境变量加载 API Key，避免硬编码在源代码中：\n\n```typescript\n// ✅ 推荐\nconst client = new AgentsID({\n apiKey: process.env.AGENTSID_PROJECT_KEY\n});\n\n// ❌ 不推荐\nconst client = new AgentsID({\n apiKey: 'aid_proj_xxx'\n});\n```\n\n### 2. Token 轮换\n\n建议定期调用 `refreshToken` 方法轮换 Token，以降低 Token 泄露的风险：\n\n```typescript\n// 每 23 小时轮换一次（Token 有效期 24 小时）\nsetInterval(async () => {\n await client.refreshToken(agentId, { ttlHours: 24 });\n}, 23 * 60 * 60 * 1000);\n```\n\n### 3. 错误重试\n\n对于网络错误和 5xx 服务器错误，建议实现指数退避重试策略：\n\n```typescript\nconst client = new AgentsID({\n apiKey: process.env.AGENTSID_PROJECT_KEY,\n retry: {\n maxAttempts: 3,\n backoff: 'exponential',\n initialDelay: 1000\n }\n});\n```\n\n### 4. 审计日志持久化\n\n将审计事件异步写入持久化存储，以便进行合规审计和问题排查：\n\n```typescript\nclient.audit.on('entry', async (entry) => {\n await db.auditLogs.insert(entry);\n});\n```\n\n## 安装\n\n```bash\nnpm install @agentsid/sdk\n```\n\n或使用其他包管理器：\n\n```bash\nyarn add @agentsid/sdk\npnpm add @agentsid/sdk\n```\n\n## 版本要求\n\n- Node.js >= 18.0.0\n- TypeScript >= 5.0.0（类型定义已内置）\n\n## 相关资源\n\n- [API 参考文档](./docs.md)\n- [快速入门指南](./guides.md)\n- [SDK 源码仓库](https://github.com/AgentsID-dev/agentsid/tree/main/sdk-typescript)\n- [GitHub Issues](https://github.com/AgentsID-dev/agentsid/issues)\n\n---\n\n\n\n## Python/Ruby/Java SDK\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#page-sdk-typescript), [核心业务服务](#page-core-services)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx) (SDK API 参考文档)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx) (SDK 集成指南)\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx) (产品首页)\n- [web/src/pages/privacy.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/privacy.tsx) (隐私政策)\n- [web/src/pages/research.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx) (研究页面)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx) (规范文档)\n- [web/src/components/dashboard/AuditFeed.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx) (审计日志组件)\n- [web/src/components/dashboard/PoliciesTab.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/PoliciesTab.tsx) (策略管理组件)\n- [web/src/pages/registry-server-v2.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-server-v2.tsx) (注册表页面)\n\n> **注意**：以下 SDK 的实际源码文件（sdk-python、sdk-ruby、sdk-java）在当前上下文检索结果中未包含。以下文档内容基于 web 前端中展示的 SDK 集成模式和 API 文档构建。\n
\n\n# Python/Ruby/Java SDK\n\n## 概述\n\nAgentsID 提供多语言 SDK（Python、Ruby、Java），为开发者提供统一的接口来集成 Agent 身份验证、权限管理和审计日志功能。这些 SDK 封装了与 AgentsID API 的通信逻辑，开发者无需直接处理 HTTP 请求和响应解析。\n\n### 核心功能\n\n| 功能模块 | 说明 |\n|---------|------|\n| Agent 注册 | 创建新 Agent 并获取访问令牌 |\n| 权限验证 | 在工具调用前验证权限策略 |\n| 令牌管理 | 刷新和撤销 Agent 令牌 |\n| 审计日志 | 记录并验证操作完整性 |\n| 元数据管理 | 存储和管理 Agent 关联数据 |\n\n### 设计理念\n\nAgentsID 的 SDK 设计遵循以下原则：\n\n- **轻量化**：核心功能简洁，不引入不必要的依赖\n- **跨平台一致性**：各语言 SDK 提供统一的 API 接口\n- **零学习成本**：通过中间件模式快速集成到现有系统\n\n资料来源：[web/src/pages/landing.tsx]()\n\n## SDK 初始化\n\n### 基础配置\n\n所有 SDK 都需要使用项目密钥（Project Key）进行初始化。项目密钥可在 [agentsid.dev/dashboard](https://agentsid.dev/dashboard) 创建项目后获取。\n\n```bash\n# 获取项目密钥后初始化\nProject ID: proj_a1b2c3d4e5f6\nAPI Key: aid_proj_xR7kM2pQ9...\nPlan: free\n```\n\n资料来源：[web/src/pages/guides.tsx]()\n\n### 初始化参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|-----|------|\n| `projectKey` | string | 是 | 项目 API 密钥，格式为 `aid_proj_xxx` |\n| `agentToken` | string | 否 | Agent 令牌，用于自动验证 |\n| `apiBaseUrl` | string | 否 | API 基础 URL，默认为 `https://api.agentsid.dev` |\n\n### 环境变量配置\n\n建议通过环境变量配置敏感信息：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `AGENTSID_PROJECT_KEY` | 项目 API 密钥 |\n| `AGENTSID_AGENT_TOKEN` | Agent 访问令牌 |\n| `AGENTSID_API_BASE_URL` | API 基础 URL（可选） |\n\n资料来源：[web/src/pages/guides.tsx]()\n\n## Agent 方法\n\n### 方法列表\n\n| 方法 | 参数 | 返回值 | 说明 |\n|-----|------|-------|------|\n| `registerAgent` | name, onBehalfOf, permissions?, ttlHours?, metadata? | { agent, token, tokenId, expiresAt } | 创建新 Agent 并颁发首个令牌 |\n| `getAgent` | agentId | Agent | 根据 ID 获取 Agent 详情 |\n| `listAgents` | status?, limit? | Agent[] | 列出 Agent，支持状态筛选 |\n| `updateAgent` | agentId, name?, metadata? | Agent | 更新 Agent 名称或元数据 |\n| `refreshToken` | agentId, ttlHours? | { token, tokenId, expiresAt } | 颁发新令牌并吊销所有旧令牌 |\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### 创建 Agent\n\n```python\n# Python SDK 示例\nagent = client.register_agent(\n name=\"research-assistant\",\n on_behalf_of=\"user_abc\",\n permissions=[\n {\"tool_pattern\": \"search_memories\", \"action\": \"allow\"},\n {\"tool_pattern\": \"save_memory\", \"action\": \"allow\"}\n ],\n ttl_hours=24,\n metadata={\"framework\": \"langchain\"}\n)\n```\n\n```ruby\n# Ruby SDK 示例\nagent = client.register_agent(\n name: \"research-assistant\",\n on_behalf_of: \"user_abc\",\n permissions: [\n { tool_pattern: \"search_memories\", action: \"allow\" },\n { tool_pattern: \"save_memory\", action: \"allow\" }\n ],\n ttl_hours: 24,\n metadata: { framework: \"langchain\" }\n)\n```\n\n```java\n// Java SDK 示例\nAgentRegistration agent = client.registerAgent(\n \"research-assistant\",\n \"user_abc\",\n Arrays.asList(\n new Permission(\"search_memories\", \"allow\"),\n new Permission(\"save_memory\", \"allow\")\n ),\n 24,\n Map.of(\"framework\", \"langchain\")\n);\n```\n\n### 权限规则\n\n权限规则使用通配符模式匹配工具名称：\n\n| 模式 | 含义 |\n|-----|------|\n| `*` | 匹配所有工具 |\n| `admin_*` | 匹配所有以 admin_ 开头的工具 |\n| `github.*` | 匹配所有 github. 开头的工具 |\n| `search_notes` | 精确匹配指定工具 |\n\n资料来源：[web/src/pages/guides.tsx]()\n\n## 中间件集成\n\n### MCP 服务器集成\n\nSDK 提供与 Model Context Protocol (MCP) 服务器的集成中间件，适用于 Claude Code、Cursor 等 AI 编程工具的扩展开发。\n\n```javascript\n// MCP 服务器验证中间件示例\nconst AGENTSID_PROJECT_KEY = process.env.AGENTSID_PROJECT_KEY;\nconst AGENTSID_AGENT_TOKEN = process.env.AGENTSID_AGENT_TOKEN;\n\nasync function validateToolCall(toolName, args) {\n const response = await fetch(\"https://api.agentsid.dev/api/v1/verify\", {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n \"Authorization\": `Bearer ${AGENTSID_PROJECT_KEY}`,\n \"X-Agent-Token\": AGENTSID_AGENT_TOKEN\n },\n body: JSON.stringify({ tool: toolName, parameters: args })\n });\n \n const result = await response.json();\n \n if (!result.allowed) {\n throw new Error(`Tool ${toolName} denied: ${result.reason}`);\n }\n \n return result;\n}\n```\n\n资料来源：[web/src/pages/guides.tsx]()\n\n### 中间件架构\n\n```mermaid\ngraph TD\n A[Agent Tool Call] --> B[MCP Middleware]\n B --> C{validateToolCall}\n C -->|请求验证| D[AgentsID API]\n D -->|allowed: true| E[执行工具]\n D -->|allowed: false| F[拒绝执行]\n E --> G[记录审计日志]\n G --> H[返回结果]\n F --> I[返回错误]\n```\n\n### 中间件组件\n\n| 组件 | 语言 | 职责 |\n|-----|------|------|\n| `MCPMiddleware` | Java | MCP 协议请求拦截和验证 |\n| `Middleware` | Python/Ruby | 工具调用拦截和权限校验 |\n\n## 审计日志\n\n### 日志条目结构\n\n```json\n{\n \"entryId\": \"entry_abc123\",\n \"timestamp\": \"2026-03-29T12:34:56.789Z\",\n \"agentId\": \"agent_def456\",\n \"delegationId\": \"del_xyz789\",\n \"tool\": \"github.push_files\",\n \"parameters\": { \"owner\": \"myorg\", \"repo\": \"myrepo\", \"branch\": \"main\" },\n \"decision\": \"allow\",\n \"matchedRule\": 2,\n \"constraintsEvaluated\": [\"rateLimit\", \"schedule\"],\n \"durationMs\": 3,\n \"prevEntryHash\": \"sha256:e3b0c44298fc1c149afb...\",\n \"entryHash\": \"sha256:a665a45920422f9d417e...\"\n}\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 哈希链完整性\n\n每个审计条目都包含前一个条目的哈希值，形成不可篡改的链式结构：\n\n```python\n# 哈希链计算\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n# 首条目使用 prevEntryHash: \"genesis\"\n```\n\n```python\ndef verify_chain(entries: list[AuditEntry]) -> bool:\n \"\"\"验证审计日志链完整性\"\"\"\n for i in range(1, len(entries)):\n prev = entries[i - 1]\n curr = entries[i]\n if curr.prev_entry_hash != prev.entry_hash:\n return False\n return True\n```\n\n资料来源：[web/src/pages/spec.tsx]()\n\n### 链验证结果\n\n| 状态 | 说明 |\n|-----|------|\n| `verified: true` | 链完整性验证通过 |\n| `verified: false` | 链完整性被破坏，可能存在篡改 |\n\n```json\n{\n \"verified\": true,\n \"entries_checked\": 1523,\n \"chain_intact\": true\n}\n```\n\n```json\n{\n \"verified\": false,\n \"entries_checked\": 1523,\n \"broken_at_id\": 42,\n \"message\": \"Integrity chain broken at entry 42 -- possible tampering\"\n}\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n## 策略管理\n\n### 规则结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `tool_pattern` | string | 工具名称模式（支持通配符） |\n| `action` | string | `allow` 或 `deny` |\n| `priority` | number | 优先级，数值越高越优先（可选） |\n| `requires_approval` | boolean | 是否需要人工审批（可选） |\n\n### 规则评估\n\n```python\n# 规则评估伪代码\ndef evaluate_rule(tool_name, rules):\n # 按优先级降序排序\n sorted_rules = sorted(rules, key=lambda r: r.priority, reverse=True)\n \n for rule in sorted_rules:\n if matches_pattern(tool_name, rule.tool_pattern):\n return rule.action\n \n # 默认拒绝\n return \"deny\"\n```\n\n### 默认行为\n\n> No rules defined. All tool calls will be denied by default.\n\n资料来源：[web/src/components/dashboard/PoliciesTab.tsx]()\n\n## 错误处理\n\n### HTTP 错误码\n\n| 错误码 | 原因 |\n|-------|------|\n| `401` | 无效或缺失的 API 密钥 |\n| `404` | Agent 不存在或不属于当前项目 |\n| `429` | 请求频率超限 |\n| `500` | 服务器内部错误 |\n\n```bash\n# curl 示例\ncurl https://api.agentsid.dev/api/v1/agents/agt_7x9k2mNpQ4rS1tUv \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n资料来源：[web/src/pages/docs.tsx]()\n\n## 套餐与限制\n\n### 使用量查询\n\n```bash\ncurl \"https://api.agentsid.dev/api/v1/audit/usage\" \\\n -H \"Authorization: Bearer aid_proj_xR7kM2pQ9...\"\n```\n\n### 响应格式\n\n```json\n{\n \"events_this_month\": 1200,\n \"events_limit\": 10000,\n \"agents_active\": 5,\n \"agents_limit\": 25,\n \"plan\": \"free\"\n}\n```\n\n### 套餐限制\n\n| 套餐 | 事件限制 | Agent 数量 |\n|-----|---------|-----------|\n| free | 10,000/月 | 25 |\n| pro | 自定义 | 自定义 |\n\n资料来源：[web/src/pages/docs.tsx]()\n\n## 快速开始\n\n### 1. 安装 SDK\n\n```bash\n# Python\npip install agentsid\n\n# Ruby\ngem install agentsid\n\n# Java (Maven)\n\n dev.agentsid\n agentsid-sdk\n 1.0.0\n\n```\n\n### 2. 初始化客户端\n\n```python\nfrom agentsid import Client\n\nclient = Client(\n project_key=\"aid_proj_xR7kM2pQ9...\",\n agent_token=\"at_your_token_here\"\n)\n```\n\n### 3. 注册 Agent\n\n```python\nagent = client.register_agent(\n name=\"my-agent\",\n on_behalf_of=\"user_123\",\n permissions=[\n {\"tool_pattern\": \"read_*\", \"action\": \"allow\"},\n {\"tool_pattern\": \"write_*\", \"action\": \"deny\"}\n ]\n)\nprint(f\"Agent ID: {agent['agent_id']}\")\n```\n\n### 4. 验证工具调用\n\n```python\nresult = client.verify_tool(\n tool=\"read_user_data\",\n parameters={\"user_id\": \"123\"}\n)\n\nif result.allowed:\n # 执行工具逻辑\n pass\nelse:\n print(f\"Denied: {result.reason}\")\n```\n\n## 数据隐私\n\nAgentsID SDK 在处理数据时遵循严格的隐私保护原则：\n\n| 原则 | 说明 |\n|-----|------|\n| 不存储原始 API 密钥 | 仅存储哈希值用于验证 |\n| 不出售用户数据 | 明确承诺永不销售用户数据 |\n| 分析功能可选 | PostHog 分析功能默认关闭，需用户同意 |\n\n> \"We never store raw API keys. Only hashes.\"\n> \"We do not sell your data. Ever.\"\n\n资料来源：[web/src/pages/privacy.tsx]()\n\n## 相关资源\n\n| 资源 | 链接 |\n|-----|------|\n| 官方文档 | [agentsid.dev/docs](https://agentsid.dev/docs) |\n| SDK 仓库 | [github.com/AgentsID-dev/agentsid](https://github.com/AgentsID-dev/agentsid) |\n| 扫描器 | [github.com/AgentsID-dev/agentsid-scanner](https://github.com/AgentsID-dev/agentsid-scanner) |\n| NPM 包 | `npx @agentsid/scanner` |\n\n资料来源：[web/src/pages/research.tsx](), [web/src/pages/landing.tsx]()\n\n---\n\n\n\n## Web 仪表板\n\n### 相关页面\n\n相关主题：[后端 API 接口](#page-api-endpoints), [Setup CLI 与集成](#page-setup-cli)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/App.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/App.tsx)\n- [web/src/pages/dashboard.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/dashboard.tsx)\n- [web/src/components/dashboard/AgentCards.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AgentCards.tsx)\n- [web/src/components/dashboard/PermissionEditor.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/PermissionEditor.tsx)\n- [web/src/components/dashboard/TeamTab.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/TeamTab.tsx)\n- [web/src/components/dashboard/RegisterAgentModal.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/RegisterAgentModal.tsx)\n- [web/src/components/dashboard/AuditFeed.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx)\n- [web/README.md](https://github.com/AgentsID-dev/agentsid/blob/main/web/README.md)\n
\n\n# Web 仪表板\n\n## 概述\n\nWeb 仪表板是 AgentsID 平台的核心管理界面，为用户提供统一的控制台来管理 AI Agent、权限配置、团队协作和审计日志。仪表板采用 React + TypeScript 构建，使用 Tailwind CSS 进行样式管理，通过 Supabase 实现身份认证和后端数据交互。\n\n仪表板的主要功能包括：\n\n- **Agent 管理**：注册、查看、更新和撤销 AI Agent\n- **权限编辑**：通过可视化界面配置 Agent 的工具调用权限规则\n- **团队管理**：支持多用户协作，管理团队成员和权限委派\n- **审计日志**：实时查看所有 Agent 的工具调用记录和 Allow/Deny 决策\n- **注册表浏览**：查看公开的工具包安全评分和详细信息\n\n## 页面路由架构\n\n仪表板通过 React Router 进行路由管理，所有路由均位于 `/dashboard` 路径下。 资料来源：[web/src/App.tsx]()\n\n```mermaid\ngraph TD\n A[App 根组件] --> B[路由配置]\n B --> C[/]\n B --> D[/dashboard]\n B --> E[/registry]\n B --> F[/registry/:registrySlug]\n \n D --> G[仪表板页面]\n G --> H[概览视图]\n G --> I[Agents 标签页]\n G --> J[Audit 标签页]\n G --> K[Team 标签页]\n \n H --> L[AgentCards 组件]\n I --> M[AgentCards 组件]\n I --> N[PermissionEditor 组件]\n I --> O[RegisterAgentModal 组件]\n J --> P[AuditFeed 组件]\n K --> Q[TeamTab 组件]\n```\n\n## 核心组件结构\n\n### AgentCards 组件\n\nAgentCards 是仪表板中用于展示 Agent 列表的核心组件。该组件负责渲染所有已注册的 Agent 卡片，提供快速概览和快捷操作入口。\n\n**主要功能**：\n\n- 展示 Agent 基本信息（名称、状态、创建时间）\n- 显示 Agent 的当前权限规则数量\n- 提供快捷操作按钮（查看详情、编辑权限）\n- 支持状态徽章显示（Active/Expired/Pending）\n\n**数据结构**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | string | Agent 唯一标识符（格式：`agt_xxx`） |\n| name | string | Agent 名称 |\n| status | 'active' \\| 'expired' \\| 'pending' | Agent 状态 |\n| permissions | PermissionRule[] | 权限规则数组 |\n| created_at | string | 创建时间戳 |\n| onBehalfOf | string | 委派方标识 |\n\n资料来源：[web/src/components/dashboard/AgentCards.tsx]()\n\n### PermissionEditor 组件\n\nPermissionEditor 是权限配置的可视化编辑器，允许用户通过图形界面管理 Agent 的工具调用规则。\n\n**权限规则格式**：\n\n```typescript\ninterface PermissionRule {\n tool_pattern: string; // 支持通配符，如 \"search_*\"\n action: 'allow' | 'deny';\n}\n```\n\n**操作模式**：\n\n- **Allow 模式**：允许匹配规则的工具调用\n- **Deny 模式**：阻止匹配规则的工具调用，Agent 会收到 \"blocked\" 响应但不会察觉限制存在\n\n**配置示例**：\n\n```json\n[\n { \"tool_pattern\": \"search_*\", \"action\": \"allow\" },\n { \"tool_pattern\": \"read_*\", \"action\": \"allow\" },\n { \"tool_pattern\": \"delete_*\", \"action\": \"deny\" },\n { \"tool_pattern\": \"admin_*\", \"action\": \"deny\" }\n]\n```\n\n资料来源：[web/src/components/dashboard/PermissionEditor.tsx]()\n资料来源：[web/src/pages/guides.tsx]()\n\n### AuditFeed 组件\n\nAuditFeed 组件提供实时审计日志流，显示所有 Agent 的工具调用记录和权限决策。\n\n**审计条目包含的信息**：\n\n| 字段 | 说明 |\n|------|------|\n| tool_name | 被调用的工具名称 |\n| decision | Allow 或 Deny 决策结果 |\n| agent_id | 执行操作的 Agent ID |\n| created_at | 调用时间戳 |\n| delegation_chain | 权限委派链（如果涉及多层委派） |\n| delegated_by | 直接授权方标识 |\n\n**委派链展示**：\n\n当 Agent 通过委派机制运行时，AuditFeed 会显示完整的委派链路：\n\n```\nuser:usr_xxx → agent:agt_parent → agent:agt_child\n```\n\n资料来源：[web/src/components/dashboard/AuditFeed.tsx]()\n\n### TeamTab 组件\n\nTeamTab 组件用于团队协作管理，支持多成员和权限委派功能。\n\n**团队管理功能**：\n\n- 查看团队成员列表\n- 管理成员角色和权限\n- 配置跨成员的 Agent 委派关系\n- 审计团队范围内的所有操作\n\n资料来源：[web/src/components/dashboard/TeamTab.tsx]()\n\n### RegisterAgentModal 组件\n\nRegisterAgentModal 是注册新 Agent 的模态框组件，提供完整的 Agent 创建流程。\n\n**注册表单字段**：\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| name | 是 | Agent 名称 |\n| onBehalfOf | 是 | 代表谁创建（用户或上级 Agent） |\n| permissions | 否 | 初始权限规则配置 |\n| ttlHours | 否 | Token 有效期（小时），默认 24 小时 |\n| metadata | 否 | 额外元数据 |\n\n**响应数据格式**：\n\n```typescript\ninterface RegisterResponse {\n agent: Agent;\n token: string;\n tokenId: string;\n expiresAt: string;\n}\n```\n\n资料来源：[web/src/components/dashboard/RegisterAgentModal.tsx]()\n\n## 页面布局结构\n\n仪表板页面采用顶部导航 + 侧边栏 + 主内容区的经典布局：\n\n```mermaid\ngraph TD\n A[顶部导航栏] --> A1[项目选择器]\n A --> A2[用户菜单]\n A --> A3[API Key 显示]\n \n B[主内容区] --> B1[概览视图]\n B --> B2[标签页容器]\n \n B2 --> B3[Agents 标签]\n B2 --> B4[Audit 标签]\n B2 --> B5[Team 标签]\n \n C[底部页脚] --> C1[文档链接]\n C --> C2[使用条款]\n C --> C3[隐私政策]\n```\n\n### 底部页脚链接\n\n| 链接 | 路径 | 说明 |\n|------|------|------|\n| 文档 | /docs | SDK 和 API 文档 |\n| 指南 | /guides | 使用教程和最佳实践 |\n| 仪表板 | /dashboard | 当前页面 |\n| GitHub | github.com/AgentsID-dev/agentsid | 源码仓库 |\n| 使用条款 | /terms | 服务条款 |\n| 隐私政策 | /privacy | 隐私政策声明 |\n\n资料来源：[web/src/pages/dashboard.tsx]()\n\n## API 集成\n\n### 认证机制\n\n仪表板通过 Supabase Auth 进行用户身份认证。所有 API 请求需要在 Authorization header 中携带 Bearer Token。\n\n### 核心 API 端点\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/api/v1/agents` | GET | 获取 Agent 列表 |\n| `/api/v1/agents` | POST | 注册新 Agent |\n| `/api/v1/agents/:id` | GET | 获取单个 Agent 详情 |\n| `/api/v1/agents/:id` | PATCH | 更新 Agent 配置 |\n| `/api/v1/agents/:id/refresh` | POST | 刷新 Agent Token |\n| `/api/v1/agents/delegate` | POST | 创建子 Agent 并委派权限 |\n| `/api/v1/audit` | GET | 获取审计日志 |\n\n资料来源：[web/src/pages/docs.tsx]()\n\n### API Key 管理\n\n仪表板在顶部导航栏显示用户的 API Key，用于服务端验证。API Key 格式为 `aid_proj_xxx`。\n\n## 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| React 18 | UI 框架 |\n| TypeScript | 类型安全 |\n| Tailwind CSS | 样式管理 |\n| React Router | 路由管理 |\n| Supabase | 身份认证和数据库 |\n| Framer Motion | 动画效果 |\n\n资料来源：[web/README.md]()\n\n## 状态管理\n\n仪表板使用 React Hooks 进行本地状态管理，主要状态包括：\n\n- `activeTab`：当前激活的标签页（'agents' | 'audit' | 'team'）\n- `registerModalOpen`：注册 Agent 模态框开关状态\n- `apiKey`：用户 API Key 凭证\n- `agents`：Agent 列表数据\n- `auditEntries`：审计日志条目\n\n```mermaid\ngraph LR\n A[用户交互] --> B[状态更新]\n B --> C[UI 重新渲染]\n C --> D[API 调用]\n D --> E[数据获取]\n E --> F[状态同步]\n F --> C\n```\n\n## 响应式设计\n\n仪表板采用移动优先的响应式设计策略：\n\n| 断点 | 布局调整 |\n|------|----------|\n| sm (640px+) | 单列布局扩展为双列网格 |\n| md (768px+) | 显示审计日志的时间戳全格式 |\n| lg (1024px+) | 侧边栏固定定位 |\n\n## 与其他模块的关联\n\n### 注册表模块\n\n仪表板提供跳转到公开注册表的入口，用户可以浏览已扫描的工具包安全评分：\n\n```\n/registry # 注册表首页\n/registry/:slug # 特定工具包详情页\n```\n\n### 落地页\n\n注册表详情页包含安全评分展示，包括等级徽章（GradeStamp）和关键发现列表。 资料来源：[web/src/pages/registry-server-v2.tsx]()\n\n## 安全考虑\n\n1. **API Key 保护**：仅显示 API Key 哈希值，不存储原始密钥\n2. **权限验证**：所有操作通过服务端 JWT 验证\n3. **审计追踪**：所有工具调用和权限决策均被记录\n4. **Cookie 同意**：PostHog 分析采用 Opt-in 机制 资料来源：[web/src/pages/privacy.tsx]()\n\n## 开发构建\n\n项目使用 Vite 作为构建工具：\n\n```bash\n# 安装依赖\nnpm install\n\n# 开发模式\nnpm run dev\n\n# 生产构建\nnpm run build\n\n# 预览构建结果\nnpm run preview\n```\n\n资料来源：[web/README.md]()\n\n---\n\n\n\n## Setup CLI 与集成\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#page-sdk-typescript), [Web 仪表板](#page-web-dashboard)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n- [web/src/pages/docs.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/docs.tsx)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n- [web/src/pages/research.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n
\n\n# Setup CLI 与集成\n\n## 概述\n\nAgentsID 提供一套完整的命令行工具和 IDE 集成方案，使开发者能够在各种开发环境中快速部署 AI Agent 安全控制。Setup CLI 是整个系统的入口点，负责项目初始化、Agent 注册以及与主流 IDE 的无缝集成。 资料来源：[web/src/pages/landing.tsx:1-50]()\n\n该 CLI 采用零配置设计理念，核心安装命令为：\n\n```bash\nnpx @agentsid/setup@latest\n```\n\n安装后会获得一个轻量级的 hook（仅 200 行 Bash 脚本），无需学习复杂的 SDK 或匹配特定的运行时环境。 资料来源：[web/src/pages/landing.tsx:1-50]()\n\n## 核心安装流程\n\n### Step 1: 创建项目目录\n\n```bash\nmkdir my-protected-server && cd my-protected-server\n```\n\n### Step 2: 初始化项目\n\n```bash\nnpm init -y\nnpm install @modelcontextprotocol\n```\n\n### Step 3: 安装 SDK\n\n```bash\nnpm install @agentsid/sdk\n```\n\n安装完成后，系统会输出类似以下信息：\n\n```\nadded {s.tools + 12} packages\n\n── AgentsID ──────────────────────────────\n {s.package} [ {grade} · {GRADE_NAMES[grade]} ]\n {critical} CRITICAL · {high} HIGH · {medium} MEDIUM\n\n agentsid.dev/registry/{registrySlug}\n──────────────────────────────────────────\n```\n\n资料来源：[web/src/pages/registry-server-v2.tsx:1-50]()\n\n## 支持的 IDE 集成\n\nAgentsID 支持与主流 AI 编程工具的深度集成，每个集成都通过 MCP（Model Context Protocol）协议实现。\n\n### Claude Code 集成\n\nClaude Code 是 Anthropic 提供的命令行工具，AgentsID 通过 MCP Server 为其提供安全控制。\n\n集成步骤：\n\n1. 在 [agentsid.dev/dashboard](https://agentsid.dev/dashboard) 创建账户并注册 Agent\n2. 创建 MCP Server 文件 `server.mjs`\n3. 安装依赖：`npm init -y && npm install @modelcontextprotocol/sdk zod`\n4. 配置环境变量 `AGENTSID_PROJECT_KEY` 和 `AGENTSID_AGENT_TOKEN`\n\nMCP Server 配置示例：\n\n```json\n{\n \"mcpServers\": {\n \"my-notes-server\": {\n \"command\": \"node\",\n \"args\": [\"server.mjs\"],\n \"env\": {\n \"AGENTSID_PROJECT_KEY\": \"aid_proj_your_key_here\",\n \"AGENTSID_AGENT_TOKEN\": \"at_your_token_here\"\n }\n }\n }\n}\n```\n\n资料来源：[web/src/pages/guides.tsx:1-80]()\n\n### Cursor 集成\n\nCursor IDE 支持通过 `.cursor/mcp.json` 配置文件加载自定义 MCP Server。AgentsID 为 Cursor 提供即插即用的集成方案。\n\n配置方式与 Claude Code 类似，通过修改 `.cursor/mcp.json` 添加 AgentsID Server 即可。\n\n### Codex 集成\n\nOpenAI Codex 的集成采用相同架构，确保在各种 AI 辅助编程场景下都能获得一致的安全保护。\n\n### Gemini 集成\n\nGoogle Gemini 的集成支持扩展 AgentsID 的保护范围到更多 AI 平台。\n\n## 预设配置\n\nAgentsID 提供多种预设配置，满足不同安全级别的需求。\n\n| 预设名称 | 适用场景 | 权限级别 |\n|---------|---------|---------|\n| lockdown | 高安全要求环境 | 最严格，仅基础工具 |\n| security-team | 安全团队使用 | 中等，允许安全相关操作 |\n| developer | 开发环境 | 宽松，支持日常开发任务 |\n\n### 权限控制示例\n\n以下示例展示如何通过预设限制 Agent 的工具访问权限：\n\n```tsx\nsearch_notes, \"Search notes by keyword\", ],\n [save_note, \"Create a new note\", ],\n [list_notes, \"List all notes\", ],\n [delete_note, \"Delete a note by ID\", ],\n [admin_reset, \"Wipe all data\", ],\n ]}\n/>\n```\n\nAgent 拥有全部五个工具的访问能力，但 AgentsID 会拦截任何尝试使用 `delete_note` 或 `admin_reset` 的请求。Agent 本身不会察觉到限制——它只会收到一个\"blocked\"响应并继续执行后续操作。 资料来源：[web/src/pages/guides.tsx:1-50]()\n\n## 安全扫描与分级\n\n### 评分系统\n\nAgentsID 对集成工具进行自动安全扫描，采用 A-F 等级评分系统：\n\n| 等级 | 含义 | 颜色标识 |\n|-----|------|---------|\n| A | 优秀 | 绿色 |\n| B | 良好 | 蓝色 |\n| C | 一般 | 黄色 |\n| D | 较差 | 橙色 |\n| F | 危险 | 红色 |\n\n扫描器已开源，可在 GitHub 获取：https://github.com/AgentsID-dev/agentsid-scanner\n\n执行命令：`npx @agentsid/scanner` 资料来源：[web/src/pages/research.tsx:1-50]()\n\n### 扫描统计\n\n截至目前，AgentsID 已扫描超过 **137,070** 个服务器，发现并记录了大量安全问题。所有研究均可在 GitHub 上公开访问。\n\n## 配置参数\n\n### SDK 初始化\n\n```typescript\n// SDK 初始化\nconst client = new AgentsIDClient({\n projectKey: 'aid_proj_xxx',\n agentToken: 'at_xxx'\n});\n```\n\n### Agent 方法\n\n| 方法 | 参数 | 返回值 | 说明 |\n|-----|------|-------|------|\n| `registerAgent` | name, onBehalfOf, permissions?, ttlHours?, metadata? | { agent, token, tokenId, expiresAt } | 创建新 Agent 并颁发首个 Token |\n| `getAgent` | agentId | Agent | 根据 ID 获取 Agent 详情 |\n| `listAgents` | status?, limit? | Agent[] | 列出 Agent，支持按状态筛选 |\n| `updateAgent` | agentId, name?, metadata? | Agent | 更新 Agent 名称或元数据 |\n| `refreshToken` | agentId, ttlHours? | { token, tokenId, expiresAt } | 颁发新 Token，自动撤销旧 Token |\n\n资料来源：[web/src/pages/docs.tsx:1-80]()\n\n### 权限配置\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| `tool` | string | 工具名称，如 `github.push_files` |\n| `parameters` | object | 工具调用参数 |\n| `decision` | string | 决策结果：`allow` 或 `deny` |\n| `matchedRule` | number | 匹配的规则编号 |\n| `constraintsEvaluated` | string[] | 评估的约束条件 |\n| `durationMs` | number | 处理耗时（毫秒） |\n\n审计日志采用 SHA-256 哈希链确保完整性：\n\n```javascript\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n// 首条记录使用 prevEntryHash: \"genesis\"\n```\n\n资料来源：[web/src/pages/spec.tsx:1-80]()\n\n## 工作流程图\n\n```mermaid\ngraph TD\n A[安装 Setup CLI] --> B[创建项目]\n B --> C[注册 Agent]\n C --> D[配置 IDE 集成]\n D --> E{选择预设}\n E -->|lockdown| F[高安全模式]\n E -->|security-team| G[安全团队模式]\n E -->|developer| H[开发者模式]\n F --> I[部署 MCP Server]\n G --> I\n H --> I\n I --> J[Agent 执行工具调用]\n J --> K{Hook 拦截请求}\n K -->|允许| L[执行工具]\n K -->|拒绝| M[记录审计日志]\n M --> N[返回 blocked 响应]\n```\n\n## 后续步骤\n\n完成 Setup CLI 与集成配置后，建议进行以下操作：\n\n1. **验证配置**：使用 `agentsid verify` 命令确认集成正常工作\n2. **查看审计日志**：通过仪表板审查所有工具调用记录\n3. **调整权限**：根据实际需求精细化配置权限规则\n4. **定期扫描**：在每次发布前运行安全扫描，确保新工具符合安全标准\n\n安装命令复制功能已内置于界面中，点击按钮即可快速复制 `npx @agentsid/setup@latest` 命令。 资料来源：[web/src/pages/landing.tsx:1-50]()\n\n---\n\n\n\n## MCP 安全扫描器\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [web/src/pages/research.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n- [web/src/pages/spec.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n- [web/src/pages/hall-of-mcps.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/hall-of-mcps.tsx)\n- [web/src/pages/landing.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n- [web/src/pages/registry-server-v2.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-server-v2.tsx)\n- [web/src/pages/registry-v2.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-v2.tsx)\n- [web/src/components/dashboard/AuditFeed.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx)\n- [web/src/pages/guides.tsx](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n\n
\n\n# MCP 安全扫描器\n\nMCP 安全扫描器（AgentsID Scanner）是 AgentsID 平台的核心安全组件，负责对 MCP（Model Context Protocol）服务器进行自动化安全评估、漏洞检测和风险评级。该扫描器已扫描超过 **137,070** 个 MCP 服务器发现，并生成公开的安全研究报告。\n\n## 核心功能概述\n\nMCP 安全扫描器的主要职责包括：\n\n1. **静态代码分析** - 解析 MCP 服务器代码，识别潜在的安全风险\n2. **工具权限评估** - 检测 MCP 工具的能力边界和权限范围\n3. **安全评级生成** - 基于规则引擎为每个 MCP 服务器分配 A-F 安全等级\n4. **问题分类统计** - 按 CRITICAL、HIGH、MEDIUM、LOW 四个严重级别归类发现问题\n5. **修复建议生成** - 针对发现的问题提供具体的 agentsid.json 策略配置\n\n资料来源：[web/src/pages/research.tsx:8](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n\n## 架构设计\n\n```mermaid\ngraph TD\n A[MCP 服务器代码] --> B[扫描器引擎]\n B --> C[规则匹配引擎]\n C --> D{风险评估}\n D -->|CRITICAL| E[阻止级问题]\n D -->|HIGH| F[警告级问题]\n D -->|MEDIUM| G[注意级问题]\n D -->|LOW| H[信息级问题]\n E --> I[安全评级 F]\n F --> I\n G --> J[安全评级 C-D]\n H --> J\n I --> K[公开研究报告]\n J --> K\n```\n\n## 安全评级体系\n\n扫描器使用 A-F 六级安全评级系统，评级基于发现的问题数量和严重程度。\n\n| 评级 | 含义 | 颜色代码 | 风险等级 |\n|------|------|----------|----------|\n| A | 优秀 | #22c55e (绿色) | 极低风险 |\n| B | 良好 | #3b82f6 (蓝色) | 低风险 |\n| C | 中等 | #eab308 (黄色) | 中等风险 |\n| D | 较差 | #f97316 (橙色) | 较高风险 |\n| E | 差 | #ef4444 (红色) | 高风险 |\n| F | 危险 | #dc2626 (深红) | 极高风险 |\n\n资料来源：[web/src/pages/landing.tsx:88-105](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n\n### 评级判定规则\n\n评级由扫描发现的问题数量和严重程度综合决定：\n\n```mermaid\ngraph LR\n A[扫描结果] --> B{存在 CRITICAL 问题?}\n B -->|是| C[评级 = F]\n B -->|否| D{存在 HIGH 问题?}\n D -->|>= 某个数量| C\n D -->|否| E{存在 MEDIUM 问题?}\n E -->|>= 某个数量| F[评级 = D/C]\n E -->|否| G{存在 LOW 问题?}\n G -->|否| H[评级 = A/B]\n```\n\n## 扫描规则体系\n\n扫描器内置了多种安全规则，用于检测不同类型的安全问题。每个规则都有唯一的编号和描述。\n\n资料来源：[web/src/pages/landing.tsx:98](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n\n### 规则示例\n\n| 规则编号 | 规则类型 | 描述 | 处置方式 |\n|----------|----------|------|----------|\n| rule #104 | block shell | 阻止危险的 shell 操作 | 阻止执行 |\n\n资料来源：[web/src/pages/landing.tsx:99-100](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/landing.tsx)\n\n## 审计日志格式\n\n每个 MCP 工具调用都会生成审计日志条目，记录完整的操作上下文和决策信息。\n\n### 条目 Schema\n\n```json\n{\n \"entryId\": \"entry_abc123\",\n \"timestamp\": \"2026-03-29T12:34:56.789Z\",\n \"agentId\": \"agent_def456\",\n \"delegationId\": \"del_xyz789\",\n \"tool\": \"github.push_files\",\n \"parameters\": { \"owner\": \"myorg\", \"repo\": \"myrepo\", \"branch\": \"main\" },\n \"decision\": \"allow\",\n \"matchedRule\": 2,\n \"constraintsEvaluated\": [\"rateLimit\", \"schedule\"],\n \"durationMs\": 3,\n \"prevEntryHash\": \"sha256:e3b0c44298fc1c149afb...\",\n \"entryHash\": \"sha256:a665a45920422f9d417e...\"\n}\n```\n\n### 字段说明\n\n| 字段名 | 类型 | 描述 |\n|--------|------|------|\n| entryId | string | 审计条目唯一标识符 |\n| timestamp | ISO8601 | 操作时间戳 |\n| agentId | string | 执行操作的代理 ID |\n| delegationId | string | 委托链 ID |\n| tool | string | 被调用的 MCP 工具名称 |\n| parameters | object | 工具调用参数 |\n| decision | enum | allow/deny 决策结果 |\n| matchedRule | number | 匹配的规则编号 |\n| constraintsEvaluated | string[] | 评估的约束条件 |\n| durationMs | number | 处理耗时（毫秒） |\n| prevEntryHash | string | 前一条目哈希值 |\n| entryHash | string | 当前条目哈希值 |\n\n资料来源：[web/src/pages/spec.tsx:1-30](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n\n### 哈希链完整性\n\n审计日志采用哈希链机制确保不可篡改性：\n\n```mermaid\ngraph LR\n A[Genesis] --> B[entry_1
prev: genesis]\n B --> C[entry_2
prev: hash(entry_1)]\n C --> D[entry_3
prev: hash(entry_2)]\n D --> E[...]\n```\n\n每条审计条目的哈希计算公式：\n\n```\nentryHash = SHA-256(canonicalize(entry with entryHash=null))\n// 创世块使用 prevEntryHash: \"genesis\"\n```\n\n资料来源：[web/src/pages/spec.tsx:43-46](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/spec.tsx)\n\n## 委托链与代理追溯\n\n审计日志支持完整的委托链追踪，记录操作在不同代理之间的传递过程。\n\n```mermaid\ngraph TD\n A[用户发起请求] --> B[主代理 Agent]\n B -->|委托| C[子代理 SubAgent]\n C -->|进一步委托| D[工具 Tool]\n D --> E[审计日志记录]\n E --> F{完整的 delegation_chain}\n```\n\n### 委托链显示格式\n\n在仪表板中，委托链以可视化方式展示：\n\n```\nAgent A → Agent B → Agent C\n```\n\n每个委托节点显示：\n- **type**: 委托节点类型\n- **id**: 节点唯一标识符\n\n资料来源：[web/src/components/dashboard/AuditFeed.tsx:30-50](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/components/dashboard/AuditFeed.tsx)\n\n## 策略修复方案\n\n针对扫描发现的安全问题，扫描器能够生成对应的 agentsid.json 策略配置文件。\n\n### 修复配置示例\n\n```json\n{\n \"version\": \"1.0\",\n \"rules\": [\n {\n \"id\": \"block-dangerous-tools\",\n \"action\": \"deny\",\n \"conditions\": {\n \"tool\": [\"shell.exec\", \"filesystem.write\"]\n }\n }\n ]\n}\n```\n\n生成的策略可直接放置于 MCP 服务器仓库根目录，通过代理运行：\n\n```bash\nnpx @agentsid/proxy run --policy agentsid.json -- npx @package/name\n```\n\n资料来源：[web/src/pages/hall-of-mcps.tsx:45-60](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/hall-of-mcps.tsx)\n\n## 公开研究报告\n\n扫描器的所有扫描结果和研究报告均公开在 GitHub 上，完全透明。\n\n| 资源 | 链接 |\n|------|------|\n| 扫描器源代码 | github.com/AgentsID-dev/agentsid-scanner |\n| NPM 包 | npx @agentsid/scanner |\n| 研究论文 | 公开可访问 |\n\n资料来源：[web/src/pages/research.tsx:20-28](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/research.tsx)\n\n## MCP 服务器注册表\n\n扫描结果汇总在 MCP 服务器注册表中，提供可搜索的安全评级数据库。\n\n### 注册表功能\n\n| 功能 | 描述 |\n|------|------|\n| 筛选 | 按评级、严重程度筛选 |\n| 搜索 | 按包名搜索特定服务器 |\n| 分页 | 大型数据集分页浏览 |\n| 详情 | 查看具体发现和修复建议 |\n| 徽章 | 生成可嵌入的安全评级徽章 |\n\n### 评级徽章\n\n每个扫描过的 MCP 服务器都会生成一个动态徽章，格式如下：\n\n```\nAgentsID [Grade] [评级等级]\n```\n\n徽章会自动随评级变化更新。\n\n资料来源：[web/src/pages/registry-server-v2.tsx:60-90](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-server-v2.tsx)\n\n## 使用流程\n\n### 1. 扫描流程\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant 扫描器\n participant 规则引擎\n participant 评级系统\n participant 注册表\n \n 用户->>扫描器: 提交 MCP 服务器包名\n 扫描器->>扫描器: 下载并解析代码\n 扫描器->>规则引擎: 发送代码片段\n 规则引擎->>规则引擎: 匹配安全规则\n 规则引擎-->>扫描器: 返回问题列表\n 扫描器->>评级系统: 计算安全评级\n 评级系统-->>扫描器: 返回 A-F 评级\n 扫描器->>注册表: 存储扫描结果\n 注册表-->>用户: 显示评级和发现\n```\n\n### 2. 集成 MCP 服务器\n\n用户可以将扫描器集成到自己的 MCP 服务器中：\n\n```javascript\n// server.mjs\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\n\nconst server = new McpServer({\n name: \"my-protected-server\",\n version: \"1.0.0\"\n});\n\n// 添加工具定义\nserver.tool(\n 'search_notes',\n 'Search for notes by keyword',\n { query: z.string() },\n async ({ query }) => {\n // 工具实现\n }\n);\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n资料来源：[web/src/pages/guides.tsx:80-120](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/guides.tsx)\n\n### 3. 环境变量配置\n\n| 变量名 | 描述 | 示例值 |\n|--------|------|--------|\n| AGENTSID_PROJECT_KEY | 项目唯一标识符 | aid_proj_abc123... |\n| AGENTSID_AGENT_TOKEN | 代理访问令牌 | at_xyz789... |\n| AGENTSID_URL | API 地址（可选） | https://agentsid.dev |\n\n## 技术规格\n\n### 扫描器配置\n\n```yaml\n# action.yml 配置示例\nname: MCP Security Scanner\nruns-on: ubuntu-latest\nsteps:\n - uses: actions/checkout@v3\n - name: Run Scanner\n run: npx @agentsid/scanner\n env:\n AGENTSID_PROJECT_KEY: ${{ secrets.AGENTSID_PROJECT_KEY }}\n```\n\n### 严重程度分类\n\n| 级别 | 中文含义 | 典型问题 |\n|------|----------|----------|\n| CRITICAL | 严重 | 任意代码执行、未授权文件访问 |\n| HIGH | 高危 | shell 命令注入、凭据泄露 |\n| MEDIUM | 中危 | 权限过度、信息泄露 |\n| LOW | 低危 | 配置不当、日志敏感信息 |\n\n资料来源：[web/src/pages/registry-v2.tsx:40-60](https://github.com/AgentsID-dev/agentsid/blob/main/web/src/pages/registry-v2.tsx)\n\n## 最佳实践\n\n1. **持续扫描** - 在每次发布前运行扫描器，确保安全性\n2. **及时修复** - CRITICAL 和 HIGH 问题应优先处理\n3. **使用策略** - 根据扫描建议配置 agentsid.json 策略文件\n4. **监控审计** - 定期检查审计日志，发现异常行为\n5. **保持更新** - 使用最新版本的扫描器和规则库\n\n## 相关资源\n\n- **扫描器 NPM 包**: `npx @agentsid/scanner`\n- **代理工具**: `npx @agentsid/proxy`\n- **SDK**: `@agentsid/sdk`\n- **安装工具**: `npx @agentsid/setup@latest`\n\n---\n\n*本页面内容基于 AgentsID 仓库中的公开源码生成，最后更新于 2024 年。*\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：AgentsID-dev/agentsid\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `agentsid` 与安装入口 `@agentsid/sdk` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @agentsid/sdk`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | repo=agentsid; install=@agentsid/sdk\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：AgentsID-dev/agentsid\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `agentsid` 与安装入口 `@agentsid/sdk` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @agentsid/sdk`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | repo=agentsid; install=@agentsid/sdk\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1192733106 | https://github.com/AgentsID-dev/agentsid | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# agentsid - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agentsid 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想检查一个 AI 工具或 Agent 工作流在权限、提示注入和数据泄露上的风险。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Identity, permissions, and audit for AI agents. The Auth0 for the agent economy. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-api-endpoints：后端 API 接口。围绕“后端 API 接口”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-services：核心业务服务。围绕“核心业务服务”模拟一次用户任务，不展示安装或运行结果。\n5. page-sdk-typescript：TypeScript SDK。围绕“TypeScript SDK”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-api-endpoints\n输入：用户提供的“后端 API 接口”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-services\n输入：用户提供的“核心业务服务”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-sdk-typescript\n输入：用户提供的“TypeScript SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-api-endpoints：Step 3 必须围绕“后端 API 接口”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-services：Step 4 必须围绕“核心业务服务”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-sdk-typescript：Step 5 必须围绕“TypeScript SDK”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/AgentsID-dev/agentsid\n- https://github.com/AgentsID-dev/agentsid#readme\n- README.md\n- PRODUCT.md\n- docs/SECURITY.md\n- ARCHITECTURE.md\n- server/src/app.py\n- server/src/core/security.py\n- server/src/api/agents.py\n- server/src/api/permissions.py\n- server/src/api/approvals.py\n- server/src/api/audit.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agentsid 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：AgentsID-dev/agentsid\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install @agentsid/sdk\n```\n\n来源：https://github.com/AgentsID-dev/agentsid#readme\n\n## 来源\n\n- repo: https://github.com/AgentsID-dev/agentsid\n- docs: https://github.com/AgentsID-dev/agentsid#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_a6b12782ee8948708b9ee92af309b07d" }