huzjie/plugforge

plugforge

AI Agent 插件生态治理与供应链安全平台 —— 面向 DeepSeek Harness / LangChain 等 Agent 框架的「插件注册中心 + 安全审查 + 供应链溯源 + 依赖解析 + 策略治理」一体化平台。

License
Python
CI

为什么是 plugforge？

2026 年 8 月 13 日，DeepSeek 开源 DeepSeek Harness——「一切皆插件」的 Agent 运行框架，GitHub 上线 42 小时破 10 万星，社区两天涌现 近 3000 个插件仓库，被评价为「自进化软件」的雏形。

当 Agent 能力以插件形式爆炸式增长时，一个尖锐的问题浮出水面：

你怎么知道装进 Agent 的那个插件，不会偷你的密钥、外传你的数据、或者干脆就是个供应链投毒包？

这就是 plugforge 存在的意义。它把 npm / PyPI 生态里成熟的「注册 + 审查 + 溯源 + 治理」能力，原样搬到 AI Agent 插件生态：

- registry —— 插件注册中心：发布、SemVer 版本管理、命名空间、倒排索引搜索
- security —— 安全审查：15 条静态规则 + 可疑 API 能力检测 + 依赖/SBOM 扫描 + CVSS 3.1 评分 + 恶意行为启发式检测
- signature —— 签名与溯源：Ed25519 签名 + 哈希链 provenance 日志（防篡改）
- depsolver —— 依赖解析：拓扑排序、版本区间冲突检测、循环依赖告警
- installer —— 安装器：下载 / 校验 / 安装 / 锁定 / 回滚 / 安装前安全门禁
- policy —— 策略引擎：许可合规 + 严重度阈值 + 网络访问控制

内核零第三方依赖，mock 模式完全离线可跑；填入 API Key 即连真实模型做语义级审查。

快速开始

git clone https://github.com/huzjie/plugforge.git
cd plugforge

核心零依赖，装完即可用（mock 模式）
pip install -e .

环境自检
plugforge doctor

搜索插件（内置演示数据，开箱即用）
plugforge search

扫描一个插件目录，输出安全报告
plugforge scan ./examples/plugins/hello-world

发布一个插件（自动 Ed25519 签名）
plugforge publish --name my-plugin --version 1.0.0 \
--entrypoint "my_plugin:run" --description "my first plugin" \
--source ./examples/plugins/hello-world

启动 API 控制面 + Web 控制台（需完整依赖）：

pip install -e ".[full]"
plugforge serve --host 0.0.0.0 --port 8000

另一个终端：启动 React 控制台
cd web && npm install && npm run dev   # http://localhost:5173

核心能力

1. 安全审查（security）

plugforge scan  会输出一份结构化安全报告，涵盖：

| 层 | 内容 |
| --- | --- |
| 静态规则 | 15 条内置规则：硬编码密钥、远程外传、动态代码执行、敏感文件读取、TLS 关闭、命令注入、不安全反序列化、base64 混淆、绝对路径写入、递归删除、无限重试、后台进程、环境变量收集、弱哈希、随机数滥用 |
| 能力检测 | 按 network / filesystem / process / crypto / credentials 五类能力画像，生成权限声明 |
| 依赖审计 | 解析 requirements.txt / pyproject.toml / package.json，生成 SBOM，命中恶意包黑名单 |
| 恶意检测 | 香农熵（打包/混淆）+ 可疑生命周期钩子（__import__、marshal.loads、postinstall 等） |
| 评分 | CVSS 3.1 基分 + CWE 分类 |

plugforge scan ./some-plugin --name demo --version 0.1.0 --format json

2. 签名与供应链溯源（signature）

- 发布即签名：publish 自动生成 Ed25519 密钥对，对 manifest 签名
- 哈希链 provenance：每次发布 / 安装 / 校验都追加到防篡改链，可回溯全程
- 安装前校验：plugforge verify manifest.json 验签，防中间人 / 篡改

3. 依赖解析（depsolver）

- 拓扑排序生成安装顺序（依赖先装）
- 版本区间（^1.2.0 / >=1.0,<2.0）冲突检测
- 循环依赖识别与报错

4. 策略引擎（policy）

policy:
allow_unknown_license: true   # 允许未知许可证
allow_copyleft: false         # 拒绝 GPL/AGPL 类 copyleft
deny_network: false           # true 时拒绝一切网络能力插件
security:
fail_on: critical             # 超过该严重度即阻断安装

架构

┌─────────────────────────────────────────────────────────────┐
│                        plugforge                            │
├──────────────┬──────────────┬──────────────┬────────────────┤
│   registry   │   security   │  signature   │   depsolver    │
│  注册中心     │  安全审查     │  签名溯源     │  依赖解析      │
├──────────────┼──────────────┼──────────────┼────────────────┤
│   installer  │    policy    │   providers  │      db        │
│  安装器      │  策略引擎     │  框架适配     │  存储(sqlite)  │
├──────────────┴──────────────┴──────────────┴────────────────┤
│   API (FastAPI)  ·  CLI  ·  Python SDK  ·  TypeScript SDK   │
├─────────────────────────────────────────────────────────────┤
│              Web 控制台 (React 深色主题)                     │
├─────────────────────────────────────────────────────────────┤
│      Docker · K8s · Helm · GitHub Actions CI · CodeQL       │
└─────────────────────────────────────────────────────────────┘

目录结构：

plugforge/
├── plugforge/           # 核心包（纯标准库，零依赖）
│   ├── core/            #   领域模型 / 注册表 / 存储 / 状态
│   ├── registry/        #   注册服务 / 发布 / 搜索 / 索引 / 命名空间
│   ├── security/        #   扫描器 / 规则 / 依赖审计 / CVSS / 恶意检测
│   ├── signature/       #   签名 / 验签 / 溯源链
│   ├── depsolver/       #   依赖图 / 解析器 / 兼容
│   ├── installer/       #   下载 / 安装 / 锁定 / 回滚
│   ├── policy/          #   策略引擎 / 许可证
│   ├── api/             #   FastAPI 控制面
│   ├── cli/             #   命令行
│   ├── sdk/             #   Python SDK
│   ├── providers/       #   Harness / LangChain 适配器
│   ├── db/              #   SQLite 存储
│   └── utils/           #   SemVer / 加密 / 哈希链 / 文件 / JSON
├── sdk/                 # TypeScript SDK
├── web/                 # React 控制台
├── deploy/              # K8s / Helm 部署清单
├── docs/                # 20+ 篇文档
├── examples/plugins/    # 示例插件
└── tests/               # 单元测试

配置

复制 config.example.yaml 为 config.yaml 后按需修改（或走环境变量 PLUGFORGE_*）：

registry:
url: ""                 # 远程注册中心地址（空 = 本地）
store:
path: "~/.plugforge"    # 插件安装目录
security:
llm:
provider: "mock"      # mock / openai / deepseek / qwen / glm
api_key: ""

API

| Method | Path | 说明 |
| --- | --- | --- |
| GET | /healthz / /readyz / /version | 健康检查 |
| GET | /plugins | 列出全部插件 |
| GET | /plugins/{name} | 插件详情 |
| GET | /plugins/{name}/releases | 版本列表 |
| GET | /plugins/{name}/security | 安全报告 |
| POST | /publish | 发布插件 |
| POST | /scan | 在线扫描源码 |
| GET | /search?q= | 搜索 |
| GET | /stats | 统计 |

质量

- 核心纯标准库、零第三方依赖，Python 3.9+ 可跑
- compileall 全量编译零语法错误
- 30+ 单元测试覆盖 SemVer / 加密 / 哈希链 / 扫描器 / CVSS / 依赖解析 / 策略
- 15 条静态规则 + 5 类能力检测 + 依赖黑名单 + 恶意启发式
- Docker / docker-compose / K8s / Helm / CI + CodeQL 齐备

License

Apache-2.0。详见 LICENSE。