HTTP 参考
CLI Finder Registry API
通过无需认证的只读 JSON 接口搜索 CLI 工具、读取证据并生成适合 Agent 的 Artifact。
快速请求
基础地址是 https://clifinder.net。所有公开 API 只接受 GET 或 OPTIONS，不需要 API Key。
curl --get 'https://clifinder.net/api/registry/tools' \
--data-urlencode 'q=review pull requests' \
--data-urlencode 'agent=codex' \
--data-urlencode 'environment=headless' \
--data-urlencode 'maxRisk=R1' \
--data-urlencode 'output=json' \
--data-urlencode 'limit=5'成功响应包装
公开的 /api/registry/* 接口都返回 { code: 0, message: "ok", data: ... }。不要把 HTTP 200 本身当作完整成功判断；客户端还应检查 code 和 data。
接口
搜索接口返回匹配原因和完整工具对象；详情接口返回单个完整工具；Artifact 接口返回文件名、媒体类型与文本内容。
搜索参数
参数只能出现一次。agent、environment、risk、category 和 evidence 接受逗号分隔的多个值；maxRisk 只接受一个值；未知参数会返回 400。
| 参数 | 允许值 | 说明 |
|---|---|---|
| q | string ≤ 200 | 任务、工具名或能力关键词；省略时按过滤条件浏览全部工具。 |
| agent | claude-code, codex, gemini-cli, copilot-cli | 按工具明确记录的 Agent 兼容性过滤，可使用逗号组合。当前四种 Agent 都能运行 Shell，因此不要把兼容性误读为已执行验证。 |
| environment | local, ci, container, headless, remote | 按明确记录的运行环境过滤。缺少某个环境表示 Registry 没有声明兼容，不代表工具绝对无法运行。 |
| risk | R0, R1, R2, R3 | 匹配含有对应风险级别命令的工具；风险是命令级信号。 |
| maxRisk | R0, R1, R2, R3 | 只返回 maximumLevel 不高于该值的工具。它与网页“最高风险”筛选语义一致，且只接受一个值。 |
| output | format string | 按记录的输出格式匹配，例如 json、yaml 或 csv；可用逗号组合。 |
| category | code-collaboration, deployment-cloud, containers-kubernetes, databases, data-text, http-webhooks, web-automation, security, operations-infrastructure | 按注册表分类 Slug 过滤，可使用逗号组合。 |
| evidence | verified, docs-verified, maintainer-submitted, community-reported, unverified | 按证据可信度过滤，不等同于 Readiness 或低风险。 |
| limit | 1–100; default 20 | 限制返回 items 数量；total 仍表示全部匹配数。 |
Artifact 类型
调用 /api/registry/artifacts/:slug 时必须传 type。mode 可选 read-only、standard 或 advanced。agent 可选 claude-code、codex、gemini-cli 或 copilot-cli。
| type | 文件名 | 用途 |
|---|---|---|
| skill-md | SKILL.md | 面向 Agent 的工具使用 Skill。 |
| agents-md | AGENTS.md | 可合并到仓库的 Agent 指令。 |
| claude-md | CLAUDE.md | 可合并到 CLAUDE.md 的 Claude Code 指令片段。 |
| claude-policy | claude-settings.json | Agent 或 shell 的命令策略。 |
| codex-policy | codex-policy.rules | Agent 或 shell 的命令策略。 |
| gemini-policy | gemini-policy.toml | Agent 或 shell 的命令策略。 |
| shell-allowlist | shell-allowlist.txt | Agent 或 shell 的命令策略。 |
| manifest-json | clifinder.json | 单工具机器可读 Manifest。 |
| manifest-yaml | clifinder.yaml | 单工具机器可读 Manifest。 |
| manifest-schema | clifinder.schema.json | 用于校验单工具 Manifest 的独立 JSON Schema。 |
| dockerfile | Dockerfile | 可复制到自动化项目的运行文件。 |
| github-actions | clifinder.yml | 可复制到自动化项目的运行文件。 |
策略类型限制
claude-policy 只支持 agent=claude-code，codex-policy 只支持 agent=codex，gemini-policy 只支持 agent=gemini-cli。若省略 agent，服务会根据策略类型推断；冲突组合返回 400。
安全模式边界
read-only 只保留 R0，并禁用 R1–R3；standard 对 R1 默认提示，并禁用 R2–R3；advanced 可把 R2 扩大到明确审批，但仍永久禁用 R3。只有逐条审计并明确标为 suffix-safe 的 R0/R1 前缀才可能自动允许；其他可用前缀始终需要提示。
响应、错误和缓存
API 错误使用 HTTP 状态与 code=-1；错误响应不缓存。客户端应保留 message，但不要依赖 message 文本做分支。
成功示例
{
"code": 0,
"message": "ok",
"data": {
"query": "review pull requests",
"filters": { "agent": "codex", "maxRisk": "R1" },
"items": [],
"total": 0,
"limit": 5
}
}错误示例
{
"code": -1,
"message": "Limit must be an integer between 1 and 100"
}| 状态 | 场景 | 处理 |
|---|---|---|
| 200 | code=0 | 请求成功；读取 data。空搜索也会返回 200 和空 items。 |
| 204 | OPTIONS | CORS 预检成功，无响应体。 |
| 400 | code=-1 | 缺少 type、未知/重复参数、无效枚举、Limit 或 Slug。 |
| 404 | code=-1 | 有效 Slug 格式，但注册表中没有该工具。 |
CORS
Access-Control-Allow-Origin 为 *，允许 GET 和 OPTIONS；预检结果最多缓存 86400 秒。
缓存策略
API：浏览器 60 秒、共享缓存 300 秒、stale-while-revalidate 86400 秒。registry.json：浏览器 300 秒、共享缓存 3600 秒。错误为 no-store。