Agent Forge#

面向 Agent 工具的开放元数据目录。 汇集 MCP Server、Plugin、Skill、General 工具与 Bundle，以静态 JSON 提供发现、版本查询和按 Agent 划分的数据源。

WARNING
Agent Forge 整合第三方元数据，不审查上游代码、不认证发布者、不执行安装，也不保证来源、兼容性或安全性。链接可用、checksum、signature、facet 和 advisory 都不能替代安全审查。

可以用它做什么#

查找工具：静态页面按 Agent、类型等条件筛选目录，按需加载包详情；Dashboard 展示元数据统计。
接入目录：客户端读取独立的 Agent/type 数据源，获取版本、兼容声明、依赖关系与发行候选。
维护记录：通过 Git 和 Pull Request 管理 JSON，使用 JSON Schema 与跨文件校验约束数据。
构建离线索引：从生成数据构建按 Agent/type 拆分的 SQLite FTS5 快照。

在线读取以静态 JSON 为公共契约，无需数据库或动态 API。当前浏览页面不依赖运行时 CDN 或后端服务，不保存 GitHub token，也不提供写入接口。

NOTE
README 介绍项目定位、数据契约与使用入口，不维护实时包数量、Agent 清单或最新 revision。元数据由独立的 packages 分支维护，README 不同步到该分支；最新已发布内容以站点及其 manifest 为准。

查看最新数据#

需要的信息	查看入口
已发布工具、版本与 Agent 筛选	目录搜索页面暂时隐藏；站点首页跳转至 Dashboard
已发布收录数量、分类统计与更新时间	Dashboard
已发布 revision、生成时间和数据源列表	数据 manifest
最新入库的规范记录	`packages` 分支
发布历史与离线产物	Releases
发布进度与失败原因	发布工作流运行记录

packages 中的新记录需要经过发布流程才会出现在站点中。比较数据时请查看 revision 与 generatedAt；分支最新内容、站点最近发布的数据和某个历史 Release 可能对应不同 revision。校验通过不代表部署成功或上游链接可用。

Pages 发布流程读取 packages 元数据，生成目录数据及离线快照，并部署页面与数据。工作流配置是触发条件、发布频率与跳过规则的查询入口。

收录范围#

类型	收录内容	说明
`mcp`	MCP Server 及其发行信息	包含声明的注册表包或远程端点
`plugin`	Agent 插件	皮肤可通过 `subtype=skin` 表达
`skill`	Skill 文档或包	记录明确的 Skill 入口，如 `SKILL.md`
`general`	独立可用的其他 Agent 工具	用 `generalDetails.toolType` 和 `agentUse` 描述用途
`bundle`	包或嵌套 Bundle 的元数据集合	描述成员关系，不分发工具本体

general 是明确的工具类别，不是未知类型的兜底。普通系统包或语言包不在收录范围内；npm、PyPI、Cargo、OCI 等是发行渠道，不是新的工具类别。targets 是 Agent 关联与兼容声明，未知版本范围不构成宿主支持的证据。

读取数据源#

packages 分支的规范记录保存在 sources/<type>/；生成器根据记录的 targets 将它们投影为 data/<agent>/<type>/。每个生成源有自己的 sourceId、manifest 和 index，客户端显式选择需要的源。

flowchart LR
    A["packages 分支规范记录"] --> B["校验与 Agent 投影"]
    B --> C["data/&lt;agent&gt;/&lt;type&gt; 静态 JSON"]
    C --> D["目录页面 / 客户端"]
    C --> E["可选 SQLite 快照"]

公开数据的发现入口为 data/manifest.json。从中读取实际发布的 Agent/type 源，无需在客户端硬编码清单，也不要假设每个 Agent 都有全部五类数据。一个源的结构如下：

data/<agent>/<type>/
  source.json          # 源标识、revision、index 和元数据镜像
  index.json           # 名称、版本列表、latest 与详情相对路径
  packages/**/*.json   # 包版本详情

接入时请遵守以下规则：

从 data/manifest.json 的 sources[].path 发现索引，路径相对 data/；包详情的 path 相对所在源目录。
使用全局 id 引用依赖与 Bundle 成员。同一包的版本共享 id；跨类别可同名，类别内名称唯一。查询与缓存键包含 source、Agent、type 和 name。
保持同一批生成文件的 revision 一致；元数据镜像必须声明相同 revision。sourceMirrors 是目录镜像，distributions 是工具本体的发行候选，不能混用。
保留未知 _meta 值。它是唯一开放扩展点，键使用反向域名命名空间；超过 4096 UTF-8 字节时校验器会警告。

IMPORTANT
消费端展示 checksum、signature 或 advisory 时，必须同时展示以下声明。脚本安装记录需要 scriptIntegrity，但完整性材料不构成信任；执行前仍需获得用户确认。

Third-party metadata. Availability checks and integrity material are not security reviews. No guarantee of accuracy, completeness, timeliness, or safety.

本地验证与预览#

开发者：本地校验、静态预览与离线快照

这些命令使用当前 checkout 中的代码与记录，不会自动获取 packages 的最新元数据，也不代表公开站点的当前状态。

需要 Python 3.10+ 和 uv。在仓库根目录执行；测试命令显式提供依赖，校验脚本通过内联依赖声明运行。

uv run --with jsonschema --with referencing python -m unittest discover -s tests -v
uv run tools/validate.py --all

单条记录也可以独立校验：

uv run tools/validate.py examples/package-mcp.json package.schema.json

本地预览需将页面和生成的 data/ 放在同一个静态站点根目录。以下命令适用于 PowerShell 和常见 Unix shell，会更新忽略的 pages-staging/ 预览目录：

uv run tools/project.py --output data --base-url http://localhost:8000/data
uv run python tools/build_site.py --output pages-staging --data data
uv run python -m http.server 8000 --bind 127.0.0.1 --directory pages-staging

打开本地目录或本地 Dashboard。端口被占用时，同时调整 --base-url 和 server 端口；直接打开 HTML 会受浏览器 fetch 限制，仅服务 site/ 也不会生成所需数据。

生成器按时间戳和截止规则筛选记录，可能排除过新或无可用时间戳的记录。实际截止时间见生成 manifest 的 cutoff，参数与默认值见 uv run tools/project.py --help。

可选的离线快照使用 Python 内置 SQLite FTS5，读取 data/ 并更新 snapshots/ 下的数据库：

uv run tools/project.py
uv run tools/snapshot.py --data data --output snapshots

贡献元数据#

从 packages 创建贡献分支，参考其 Schema、示例与字段文档，选择一种类型；非 Bundle 记录需要发行候选。
将包版本 JSON 放入 sources/<type>/packages/，更新对应 index.json 的版本、latest 和相对详情路径，并保持源与索引 revision 一致。
保留上游原始版本字符串；versionScheme 仅作为比较提示。记录来源、兼容性未知项与发行链接，不暗示已经过安全核验。
运行上述测试与完整校验，再向 packages 分支发起元数据 Pull Request。README 等文档改动在文档所在分支维护。也可以通过可视化上传页填写元数据并自动生成 JSON，再到 GitHub 确认提交。Agent 可使用 JSON Issue 表单或机器提交契约；Submission Notes 可选。

符合条件的 package-submission Issue 会由工作流生成面向 packages 的提案 Pull Request，仍需审阅和校验。自动合并的条件以冷却工作流、仓库规则和必需检查为准。

README 与其他文档按项目说明或操作方式的变化更新，不随包数据更新。批量导入工具的 --apply 会写入规范记录和索引，使用前应审阅预览结果。

文档与仓库导航#

入口	内容
`docs/schema/`	四份 Schema 的中英文字段参考与注释示例
根目录 `*.schema.json`	机器可读契约，当前 `schemaVersion` 为 `2`
`packages` 中的 `sources/`	按类型维护的最新规范记录与索引
`tools/` / `tests/`	采集、导入、校验、投影、快照工具与测试
`site/`	静态目录与 Dashboard 的数据契约
架构说明	契约设计与扩展方向；发布流程读取 `packages` 分支
实施计划	阶段规划
修改历史	历史契约变更背景

Schema 的稳定 $id 位于 https://ratapi.com/ 下的 package.schema.json、source.schema.json、index.schema.json 和 advisory.schema.json。兼容扩展保持 $id 稳定，破坏性契约变更才提升 schemaVersion。

data/、snapshots/、pages-staging/ 和采集缓存是忽略的本地产物；规范记录以 packages 分支的 sources/ 为准，公开数据以已发布 revision 为准。