内容
# TrustedAgentHub — 可信 Agent Skills 与 MCP Hub 平台
[](https://github.com/hust-open-atom-club/trusted-agent-hub/actions/workflows/api.yml)
[](https://github.com/hust-open-atom-club/trusted-agent-hub/actions/workflows/web.yml)
[](https://github.com/hust-open-atom-club/trusted-agent-hub/actions/workflows/cli.yml)
面向智能体生态的可信能力分发平台。支持 Agent Skills、MCP Server、Plugin、Subagent 等能力单元的浏览、搜索、提交、安全扫描、人工审核、信任评分和 CLI 安装。
## 项目入口
| 入口 | 地址 |
|---|---|
| 在线演示 | [TrustedAgentHub Web](https://tah.openatom.club/) |
| API 文档 | [Swagger UI](https://tah.openatom.club/docs ) |
| 源码仓库 | [hust-open-atom-club/trusted-agent-hub](https://github.com/hust-open-atom-club/trusted-agent-hub) |
---
## 项目架构
```
TrustedAgentHub/
├── apps/
│ ├── api/ FastAPI 后端 (Python 3.12, 端口 8000)
│ ├── cli/ CLI 安装工具 (TypeScript/Node.js, Commander.js)
│ └── web/ Web 前端 (Next.js 14 App Router + React 18)
├── scanners/
│ └── risk_scanner/ 安全扫描器 — 20 条规则 + LLM 语义复核
├── packages/
│ ├── schema/ 统一数据契约 (JSON Schema) + 元数据提取器
│ └── trust-score/ 独立的安全风险与证据完整度评估
├── examples/ 示范能力包 + 真实能力包 (Skill/MCP/Plugin/风险样例)
├── scripts/ 数据库种子脚本
├── deploy/ 部署配置
├── docker-compose.yml
```
---
## 核心能力
### Hub 平台 (Web + API)
- **包浏览与搜索**：按类型、分类、评分、更新时间筛选
- **提交与扫描**：输入 GitHub URL → 自动 git clone → 20 条规则安全扫描 → 信任评分 → 提交审核
- **审核流程**：审核员查看 Diff、扫描报告、风险提示 → 通过/驳回/要求修改
- **管理面板**：下架、手动评级覆盖、审计日志查询
- **中英双语**：i18next 国际化，导航栏 + 所有管理页面全覆盖
### 安全扫描器 (20 条规则 + LLM 语义复核)
| 规则 ID | 检测内容 |
|---------|----------|
| SR-001 | 提示注入 + 反拒绝机制 |
| SR-002 | 危险 Shell 命令 |
| SR-003 | 凭据访问 (SSH/AWS/浏览器) |
| SR-004 | 硬编码密钥 |
| SR-005 | 远程代码执行 (正则层) |
| SR-005b | 远程代码执行 (AST 行为分析层) |
| SR-006 | 过度权限 + 自主决策 |
| SR-007 | 网络访问无白名单 |
| SR-008 | 供应链风险（Typosquatting + OSV 已知漏洞；未批准 HTTPS 来源生成 `high` 人工复核 advisory，不扣分、不改评级；HTTP 来源另报 `medium` finding） |
| SR-009 | 来源完整性 |
| SR-010 | 元数据质量 |
| SR-011 | 输出处理风险 |
| SR-012 | 系统提示泄漏 |
| SR-013 | 记忆投毒 |
| SR-014 | SSRF (含防御上下文过滤) |
| SR-015 | Agent 窥探 |
| SR-016 | 工具滥用 |
| SR-017 | MCP 安全 (隐藏工具 + HTTP 明文 + 工具描述投毒/语义漂移) |
| SR-018 | Plugin 安全 (内联 MCP + Hook 注入) |
| SR-019 | Subagent 安全 (自主模式 + 危险工具) |
| SR-020 | 安装器安全 (生命周期脚本 + 破坏性安装操作) |
SR-008 的官方、私有和未知依赖源采用可审计的分级策略，并将同根因的未批准来源聚合为一次人工复核提示。npm/Python 依赖声明中的 Git 托管直链不会自动视为生态官方源：未获批的 `git+https://...` 通常以 `unknown_host` 拒绝，`git+ssh://...` 会被采集并以 `non_registry_source` 拒绝。采集范围、内置端点、精确匹配规则和服务端私有源配置见 [依赖来源策略](docs/dependency-registry-policy.md)。
SR-010 的 LICENSE 查找以扫描包目录为默认边界。扫描仓库中的子包时，调用方可使用
`RiskScanner(package_dir, repository_root=repo_dir)` 允许继承该仓库内的许可证；API 扫描会自动传入获取到的仓库快照根目录。
查找包含仓库根目录，但不会越过它；`ScanPolicy(allow_parent_license_files=False)` 始终只检查包目录。
子包元数据提取也支持父级 LICENSE 回退：API 从同一受限仓库快照中保留父级许可证文本，
通过 `extract_single_skill(..., parent_license_files=...)` 传入，按最近父目录到仓库根目录的顺序识别。
包内 LICENSE、`package.json` 和 `pyproject.toml` 中的许可证声明优先；扫描后的磁盘修改不会改变继承结果。
超出快照预算、被截断或扫描期间发生变化的父级许可证不会参与回退。
SR-010 与元数据提取共用不区分大小写的文件名规则，支持 `LICENSE`、`LICENCE`、`COPYING`
及其 `.md`、`.txt`、`.markdown` 变体，并在快照中保留真实文件名。
提取时会保存本次生效的 policy；旧快照没有 policy 时使用调用方显式传入的策略，
两者都未提供则使用 `ScanPolicy()` 默认值（允许从显式传入的父级快照继承）。
另有本地语义检测（`mcp_security.py` + fastembed 嵌入模型）：SR-017 对 MCP 工具描述与权限声明做语义对比，检测"描述投毒"；未安装模型时自动降级为纯规则模式。
扫描结果区分“安全发现”和“审核提示”。签名、供应链证明、SBOM 验证器未配置时会明确标记为 `not_available`，不会伪装成验证失败或固定扣分；验证器已运行但验证失败时，仍会生成对应审核提示。元数据、权限声明一致性等 advisory 只用于审核排队和证据展示，不从安全分扣除。结构化代码证据确认能力未声明时会要求人工复核，但不会仅凭“具备执行能力”把正常包判为漏洞或恶意包。
`SKILL.md`、提示词、说明文本和上下文相关代码中的提示注入、凭据外传、破坏命令等静态命中会标记为语义候选，同时保留原始静态严重性。系统默认进行两次独立 LLM 上下文复核；结论冲突时增加第三次仲裁。只有在上下文完整、引用有效且高置信度的良性共识下，候选的有效严重性才会降为 `info`；已确认漏洞禁止降级。不确定、上下文不足或 LLM 不可用时保留复核前严重性并转人工确认。
LLM 提示词、上下文覆盖、模型信息和受控降级条件见 [LLM security adjudication](docs/llm-adjudication.md)。
### 信任评分引擎
评分输出拆成两个独立指标：`security_assessment` 给出 0–100 安全分、A–E 安全等级和结论状态；`evidence_assessment` 给出证据质量分、覆盖率、验证器状态和作者信誉。顶层兼容字段 `score` 与 `risk_summary.grade` 均镜像安全指标，来源不透明、作者是新人或验证器尚不存在都不会单独降低安全等级。
| Grade | 安全含义 | 安装建议 |
|-------|----------|----------|
| A | 可信 | 自动安装 |
| B | 低风险 | 展示权限声明后安装 |
| C | 中风险或存在待确认语义结论 | 展示扫描摘要 + 确认 |
| D | 高风险 | 强烈不建议，双重确认 |
| E | 已确认恶意、人工驳回或命中其他否决条件 | 禁止安装 |
原有 9 个明细维度继续保留用于解释：权限最小化与扫描结果驱动安全分；来源可信度、签名可验证性、元数据完整性、版本稳定性、作者信誉和用户反馈进入独立证据指标；人工安全复核可以确认、否决或要求继续复核。详细契约见 [`docs/trust-assessment-model.md`](docs/trust-assessment-model.md)。
### CLI 安装工具
```bash
npx tah search <keyword>
npx tah install <name>
npx tah update <name>
npx tah verify <name>
```
支持 Claude Code / Cursor / Codex / VS Code 等多种客户端，安装前展示权限声明和信任评分。
插件类能力包安装到 `~/.claude/skills/<name>/`（与技能共用目录）。只要包内含
`.claude-plugin/plugin.json`，Claude Code 就会自动加载为
`<name>@skills-dir` 插件，无需手工注册 marketplace；安装后新开会话即可在
`/plugin` 中看到并启用。
---
## 快速开始
### 环境要求
- Python 3.12+
- Node.js 18+
- PostgreSQL 16+
- Git
### Docker Compose（推荐）
```bash
# 创建本地配置
cp .env.example .env
# 编辑 .env，至少填写 POSTGRES_PASSWORD 和 JWT_SECRET
# Linux/macOS
./deploy/deploy.sh
# Windows PowerShell
.\deploy\build.ps1
```
部署完成后访问：
- Web 前端：<http://localhost:3000>
- Swagger API 文档：<http://127.0.0.1:8000/docs>
### 本地开发：安装与配置
```bash
# 克隆仓库
git clone https://github.com/hust-open-atom-club/trusted-agent-hub.git
cd trusted-agent-hub
# 创建本地私有配置（.env 已被 Git 和 Docker 构建上下文忽略）
cp .env.example .env
# 编辑 .env，至少填写 POSTGRES_PASSWORD 和 JWT_SECRET
# 若同一份配置还要用于 Compose，请保持 DATABASE_URL、DATABASE_HOST 为空
# Python 依赖 (pyproject.toml 位于 apps/api)
cd apps/api
pip install -e ".[dev]"
cd ../..
# 数据库迁移（自动读取仓库根目录 .env）
cd apps/api
alembic upgrade head
# 导入种子数据
python -m src.scripts.seed_producer
```
### 统一环境配置与重复部署
仓库根目录 `.env` 是本地开发和服务器部署的唯一私有配置文件；它不会被 Git
跟踪，也不会进入 Docker 构建上下文。`.env.example` 只保存变量名、说明和安全的
默认值，必须提交到仓库，但不得填写真实密码、Token 或私有地址。
- 数据库配置有两种模式。推荐填写 `POSTGRES_USER`、`POSTGRES_PASSWORD` 和
`POSTGRES_DB`，并保持 `DATABASE_URL`、`DATABASE_HOST` 为空：本机 API 使用
`127.0.0.1`，Compose 中的 API 使用 `db`，同一份 `.env` 无需切换。仅本地开发也可
直接设置指向 `localhost` 的 `DATABASE_URL`；它会覆盖分项配置，但运行 Compose 前
必须清空，否则容器会把 `localhost` 当作自身而无法连接 `db` 服务。
- `API_HOST`、`ARTIFACTS_ROOT`、`SOURCE_SNAPSHOT_DIR` 和 `FASTEMBED_CACHE_PATH`
保持为空时，本机使用开发默认值，Compose 注入容器值。`API_RELOAD` 只供
`python apps/api/run.py` 使用；Docker 镜像始终以不启用 reload 的方式启动。
- `TAH_OSV_ENABLED` 控制是否启用 OSV 查询，`TAH_OSV_BASE_URL` 可切换到经批准的
HTTPS 内部镜像；默认不会把明确来自非公共依赖源的包坐标发送给 OSV，只有明确设置
`TAH_OSV_ALLOW_PRIVATE_COORDINATES=true` 才会放行。批量、并发、重试、查询上限及
续扫缓存由其余 `TAH_OSV_*` 变量控制，安全默认值见 `.env.example`。
- `PUBLIC_API_BASE_URL` 是后端生成 install-manifest 制品下载地址时使用的固定
公开 API 基址，必须填写为用户和 CLI 可访问的真实地址；公网部署应使用 HTTPS。
- Docker 首次启动会创建 PostgreSQL 数据库、执行全部 Alembic 迁移，并按
`INITIAL_ADMIN_*` 幂等创建首个管理员；邮箱与密码必须成对配置，密码至少 12
位。管理员创建后建议清空 `INITIAL_ADMIN_PASSWORD`。
- `SEED_ADMIN_*`、`SEED_REVIEWER_*`、`SEED_SUBMITTER_*` 均为可选开发账号，
每组邮箱与密码必须同时配置；项目不再内置固定测试账号或默认密码。若需要保留演示
账号，请只在 API 环境中配置对应的 `SEED_*`，Web 不会读取或展示这些凭据。
- `NEXT_PUBLIC_*` 会进入浏览器包，不能存放私密信息；修改这些值后必须重新构建
Web 镜像。
- 从本仓库运行 CLI 时会自动加载根目录 `.env`，但显式 Shell/CI 环境变量仍然优先；
已发布的 CLI 也可以使用 `tah use <api-url>` 保存服务地址。
- 服务器首次部署只需创建并填写一次 `.env`。以后执行 `git pull` 时该文件会保留，
再运行 `deploy/deploy.sh`（Linux）或 `deploy/build.ps1`（Windows）即可更新。
- 浏览器会话使用 30 分钟 Access Token 和 3 小时 Refresh Token。Refresh Token
仅在换发 Access Token 时轮换，因此空闲会话最长保留 3 小时，并可能提前最多
30 分钟失效。这是滑动空闲超时，而非会话的绝对生命周期上限；普通 API 请求
不会写入 Refresh Token 表。
- Compose 中的 `db-maintenance` 服务默认每 15 分钟执行一次数据库清理：
`apps/api/src/sql/cleanup_refresh_tokens.sql` 删除已使用和已过期的 Refresh Token，
`apps/api/src/sql/cleanup_scan_tasks.sql` 只删除已超过 30 天保留期的失败或未提交完成扫描任务及其报告；活动任务和已提交审核任务不会被该清理任务自动删除。
API 进程自身也会按 `_SCAN_MAINTENANCE_INTERVAL_SECONDS`（默认 10 分钟）执行相同的
`scan_tasks` 清理，因此未启用 `db-maintenance` 时仍会落实扫描任务保留期。
可通过 `REFRESH_TOKEN_CLEANUP_INTERVAL_SECONDS` 调整周期，最小值为 60 秒。
启动时会每 5 秒探测一次 `refresh_tokens` 和 `scan_tasks` 表，连续 12 次失败后进程
退出并由 Compose 重启；`docker compose logs db-maintenance` 会显示每次探测和
`DELETE` 结果。若生产数据库已提供 `pg_cron`，可以改由数据库调度同一组 SQL，
并停用外部维护任务。
- 从旧版 Compose（项目名 `tah-dev`）升级时，数据卷会随项目名变为
`trusted-agent-hub_*` 而新建。旧数据仍在 `tah-dev_pgdata` 等卷中；如需沿用，
在 `.env` 中设置 `COMPOSE_PROJECT_NAME=tah-dev`，或手动迁移卷数据。
新增配置项时，应同步更新 `.env.example`、读取该变量的统一配置模块、必要的
Compose/Docker build 参数、测试和文档，不要在业务代码、Compose 文件或部署脚本中
写入真实值。
API 测试只会从根目录 `.env` 读取专用的 `TEST_DATABASE_URL`，不会继承
`DATABASE_URL` 或 `POSTGRES_*`。该项未设置时 PostgreSQL 集成测试会跳过，避免误写
开发或生产数据库；Shell/CI 中显式设置的 `TEST_DATABASE_URL` 优先。
### 数据库迁移策略
项目当前仍处于预发布阶段，数据库迁移已整理为单一初始 schema。新建数据库执行：
```bash
alembic upgrade head
```
如需为新建的空数据库生成离线 SQL，可以执行：
```bash
alembic upgrade head --sql > migration.sql
```
离线输出仅支持从 `base` 创建空数据库。修订 `20260826_0010` 需要读取并重写
`package_versions` 和 `scan_reports` 中的历史 JSON，因此完整离线建库脚本会跳过
这一步数据清理。如果这些表中可能已有数据，必须执行在线 `alembic upgrade head`；
不支持从已有 revision 生成跨越 `20260826_0010` 的增量离线 SQL。
修订 `20260910_0001` 会递增所有现有用户的 `auth_version` 并清空
`refresh_tokens`，使部署前签发的 Access Token 和 Refresh Token 同时失效。
该会话撤销不可逆。多实例生产环境应先停止旧 API 实例或暂停认证流量，完成新版本
部署和迁移后再恢复服务，避免旧实例在迁移之后继续签发旧时长的 Token。
本次整理不兼容此前的旧 revision 链。已有本地数据库如无需要保留的数据，建议删除后
重新创建；如果包含重要数据，应先备份，再按当前 schema 迁移数据。不要仅使用
`alembic stamp` 跳过 schema 创建，除非数据库结构已经与当前初始 schema 完全一致。
API 镜像启动时会在数据库迁移完成后自动执行一次幂等回填。评分模型指纹由
`packages/trust-score/src/` 下的评分代码以及实际使用的权重/规则配置自动计算，
因此修改评分逻辑或配置后不需要手动升级版本号。`model_version` 仍会保留在输出中，
但只是由指纹派生的兼容展示字段；回填判断以 `model_fingerprint` 为准。
扫描器代码仍由扫描报告中的 `scanner_version` 管理；扫描器变更需要重新扫描，
不会把历史扫描报告误当成新扫描结果。
如果自动回填因外部故障失败，修复后可以手动重跑：
```bash
cd apps/api
python -m src.scripts.backfill_trust_scores --batch-size 100 --max-attempts 3
```
命令会跳过已使用当前模型指纹的版本，逐批记录扫描、更新、跳过和失败数量；
单个版本失败会自动重试，最终仍有失败时以非零状态退出。修复故障后可直接重跑，
已完成版本不会重复计算。
### 本地开发：启动服务
以下命令适用于不使用 Docker 的本地开发。后端和前端建议分别在两个终端中运行。
```bash
# 终端 1：启动后端（端口 8000）
cd apps/api
python run.py
```
```bash
# 终端 2：从仓库根目录启动前端（端口 3000）
cd apps/web
npm install && npm run dev
```
启动后访问：
- Web 前端：<http://localhost:3000>
- Swagger API 文档：<http://127.0.0.1:8000/docs>
### 生产域名与用户安装
生产环境使用 `https://tah.openatom.club` 作为 Web 和 API 的统一入口，反向代理需要将
`/` 转发到 Web 容器的 3000 端口，将 `/api/*` 转发到 API 容器的 8000 端口。
修改 `.env` 后重新构建并启动：
```bash
docker compose --env-file .env up -d --build
```
CLI 发布版本默认连接该域名，因此用户无需配置服务器 IP：
```bash
npx tah search <keyword>
npx tah install <package-name>
```
使用旧版 CLI 或连接其他 Hub 时，可手动指定地址：
```bash
tah use https://tah.openatom.club
```
## 真实能力包
`examples/real-world/` 内置了来自开源社区的**真实能力包**（Apache-2.0）：
| 包名 | 类型 | 上游来源 |
|---|---|---|
| `anthropic-skill-creator` | Skill | [anthropics/skills](https://github.com/anthropics/skills) |
| `anthropic-mcp-builder` | Skill | [anthropics/skills](https://github.com/anthropics/skills) |
| `anthropic-algorithmic-art` | Skill | [anthropics/skills](https://github.com/anthropics/skills) |
| `anthropic-brand-guidelines` | Skill | [anthropics/skills](https://github.com/anthropics/skills) |
| `anthropic-webapp-testing` | Skill | [anthropics/skills](https://github.com/anthropics/skills) |
| `anthropic-theme-factory` | Skill | [anthropics/skills](https://github.com/anthropics/skills) |
| `anthropic-frontend-design` | Skill | [anthropics/skills](https://github.com/anthropics/skills) |
| `mcp-server-filesystem` | MCP Server | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |
| `mcp-server-memory` | MCP Server | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |
| `mcp-server-sequential-thinking` | MCP Server | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |
| `mcp-server-everything` | MCP Server | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) |
| `anthropic-skills-plugin` | Plugin | [anthropics/skills](https://github.com/anthropics/skills) |
| `anthropic-web-skills-plugin` | Plugin | [anthropics/skills](https://github.com/anthropics/skills) |
| `superpowers` | Plugin | [obra/superpowers](https://github.com/obra/superpowers) |
每个包都带有符合 `agent-package.schema.json` 的 `manifest.json`、来源 commit 和许可证说明，可直接提交、扫描、审核、发布和安装。详见 `examples/real-world/README.md`。
---
## 运行测试
```bash
# 全量测试
cd apps/api
python -m pytest tests/ -v
# 扫描器规则测试
python -m pytest tests/test_sr*.py -v
# 状态机测试
python -m pytest tests/test_state_machine.py -v
# Web 前端测试 (需 Node.js)
cd apps/web
npm test
```
---
## 技术栈
| 层 | 技术 |
|----|------|
| 后端 | Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic, PostgreSQL |
| 前端 | Next.js 14 (App Router), React 18, TypeScript, i18next |
| CLI | TypeScript, Commander.js, Node.js |
| 扫描器 | Python AST, 正则引擎, OWASP 规则, LLM 审查 (litellm) |
| 评分引擎 | 安全风险与证据完整度评估, 多维度解释 |
| 部署 | Docker Compose (API + Web + PostgreSQL) |
---
## 参与贡献
欢迎通过 [Issues](https://github.com/hust-open-atom-club/trusted-agent-hub/issues) 反馈问题，或提交 [Pull Request](https://github.com/hust-open-atom-club/trusted-agent-hub/pulls) 改进代码与文档。
---
## License
Apache-2.0
连接信息
猜你喜欢
暂无推荐服务器