使用说明
代理工具
Agent Tools是AGenNext平台的标准工具目录。
这是一个云市场风格的目录问题。
工具是一个可调用的目录对象，可以被代理、工作流、团队和运行时发现、管理、版本控制、许可、审查、定价、安装和使用。
核心模型
Tool
= primary catalog object
= invocable capability/product
Tool metadata includes:
- capabilities
- author
- publisher
- versions
- provider offers
- license
- pricing
- risk
- approval requirements
- invocation contracts
主目录对象始终是 工具.
能力、作者、发布者、版本和提供者是附加到工具记录的元数据。
角色定义
Capability
= standardized semantic ability implemented by the tool
Author
= creator or maintainer of the tool
Publisher
= party that lists, curates, verifies, or publishes the tool into the catalog
Version
= version metadata and compatibility contract for the tool
Provider Offer
= one access path for a specific tool version
Provider
= organization, package, service, MCP server, CLI, SDK, HTTP API, marketplace, or runtime endpoint offering that version
市场规则
One Tool
can implement many Capabilities
One Tool
can have many Versions
One Tool Version
can have many Provider Offers
One Provider
can offer many Tools
One open-source Tool
can have many Providers
One MCP Server
is a Provider type
One MCP Server
can expose many Tools
示例：具有功能、作者、发布者、版本和提供者的工具
id: filesystem.read_file
type: tool
name: Read File
capabilities:
- file.read
author:
name: AGenNext
type: Organization
publisher:
name: AGenNext
type: Organization
versions:
- version: 1.0.0
status: active
contract:
inputs:
path: string
outputs:
content: string
providers:
- provider_id: filesystem-mcp-server
provider_type: mcp_server
protocol: mcp
package_path: packages/filesystem-mcp-server
offer_status: active
- provider_id: internal-filesystem-http
provider_type: http_api
protocol: https
offer_status: active
risk: medium
approval_required: false
示例：具有多个提供者的开源工具
id: surrealkit
type: tool
name: SurrealKit
capabilities:
- database.schema.generate
- database.migration.run
- database.seed.load
author:
name: SurrealDB
type: Organization
publisher:
name: AGenNext
type: Organization
role: catalog_curator
versions:
- version: 2.2.1
status: supported
providers:
- provider_id: surrealkit-github-release
provider_type: github_release
install_strategy: pinned_binary
version_policy: pinned
- provider_id: surrealkit-npm
provider_type: npm_package
install_strategy: package_manager
version_policy: pinned
- provider_id: agennext-ci-wrapper
provider_type: ci_wrapper
install_strategy: workflow_script
version_policy: pinned
存储库职责
Agent Tools拥有：
- tool catalog entries
- capability references used by tools
- author and publisher metadata
- version metadata and compatibility contracts
- provider offer metadata
- external tool definitions
- MCP provider/package metadata where needed
- tool invocation contracts
- tool security, approval, pricing, and governance metadata
代理工具不拥有：
- runtime execution of agents
- skill definitions
- agent blueprints
- graph schema
- grammar rules
- seed-data ownership
当前文件夹
catalog/
工具和外部工具的规范目录条目。
例子：
catalog/surrealkit.tool.yaml
每个文件应首先描述一个工具。
功能、作者、发布者、版本和提供商产品作为元数据属于工具条目。
packages/
下的现有文件夹 packages/ 是提供者实现包。
目前的大多数软件包都是MCP服务器实现。它们应该从概念上从以下方面迁移：
MCP server = catalog item
致：
Tool = catalog item
MCP server = provider offer metadata under a tool version
推荐的包装结构：
packages/<provider-name>/
provider.yaml # provider/package metadata
tools/ # tool catalog entries exposed through this provider
<tool-id>.tool.yaml
src/ # provider implementation
package.json
tsconfig.json
MCP提供商模型
MCP服务器包应声明它提供了哪些工具：
provider_id: filesystem-mcp-server
provider_type: mcp_server
provides:
- tool_id: filesystem.read_file
version: 1.0.0
- tool_id: filesystem.write_file
version: 1.0.0
- tool_id: filesystem.list_directory
version: 1.0.0
每个公开的工具都应该有一个目录条目，其中包含提供商提供的元数据：
id: filesystem.read_file
type: tool
capabilities:
- file.read
versions:
- version: 1.0.0
providers:
- provider_id: filesystem-mcp-server
provider_type: mcp_server
protocol: mcp
risk: medium
approval_required: false
能力标准化
功能应该是稳定的语义标识符。
示例：
file.read
file.write
filesystem.list
database.query
database.schema.generate
database.migration.run
database.seed.load
cloud.compute.create
cloud.storage.object.read
功能允许平台比较工具、替换提供商、解释风险，并将技能与工具相匹配。
构建现有的提供程序包
现有的包仍然可以构建为Node.js工作区：
npm install
npm run build
npm run build:changed
npm run build --workspace=packages/<provider-name>
直接运行内置的MCP提供程序：
node packages/<provider-name>/dist/index.js
环境变量
提供商包可能需要凭据或服务URL。
常见示例：
SERVICE_URL="https://your-service.com"
SERVICE_API_KEY="your-api-key"
ALLOWED_DIRECTORIES="/data"
切勿将机密提交到此存储库。使用环境变量、Docker机密或运行时机密存储。
现有包的迁移规则
不要立即删除现有的提供程序包。
将它们迁移到位：
1. Identify the tools exposed by each provider package.
2. Identify capabilities implemented by each tool.
3. Add one .tool.yaml catalog entry per tool.
4. Add capability, author, publisher, and version metadata under each tool.
5. Add provider offers under each version.
6. Add provider.yaml only for package/build/runtime metadata.
7. Mark tool risk, approval requirements, auth, pricing, license, and support metadata where known.
8. Keep implementation under src/.
9. Build and test provider package.
与其他回购的关系
Agent-Skills
uses tools as executable capabilities
Agent-Graph
maps tools, capabilities, authors, publishers, versions, providers, permissions, and invocations
Agent-Grammar
validates tool metadata
Agent-Seed
seeds default platform tool records
Agent-Review
reviews high-risk tools before publication/use
规则
Tool
= primary catalog object
Capability
= semantic ability metadata
Author
= creator/maintainer metadata
Publisher
= catalog publishing/curation metadata
Version
= compatibility metadata
Provider Offer
= access path metadata for a version
