Jin Agent Intent Protocol 完全指南：让 AI Agent 像读 API 文档一样理解你的网站
背景：为什么 AI Agent「看不懂」网页？
当人类打开一个电商网站，我们能看到清晰的导航栏、搜索框、商品列表和筛选条件。但 AI Agent 看到的却是密密麻麻的 HTML 标签、CSS class 名和 JavaScript 回调——它需要从 DOM 树中「猜」出哪个 div 是搜索框，哪段文本是商品标题，哪个按钮是用来提交订单的。
这个过程被称作 Web Scraping + DOM Parsing，有三个根深蒂固的痛点：
- 脆弱性：前端组件库升级、CSS 重构或者 React 版本更新后，DOM 结构变了，Agent 的解析脚本大概率全部报废。
- 高成本：一个电商首页的渲染 HTML 通常在 200-500KB，LLM 需要用数千 Token 去解析这些无意义的结构代码，然后再理解内容。
- 高负载：高频 scraping 对后端服务器来说等同于 DDoS 攻击的前奏——这也是 Cloudflare、Akamai 等 CDN 把 AI Agent 的爬取流量集体封杀的原因。
Jin 就是一个为了解决以上问题而诞生的开放协议层。
什么是 Jin？
Jin（meetjin.com）是一个轻量级的Agent Intent Protocol（AIP）开源标准。它由两大部分组成：
- AIP 标准 +
jin.json：一份机器可读的意图映射文件，托管在网站的/.well-known/jin.json。它告诉 AI Agent：「我的网站有哪些能力、每个能力的自然语言触发词是什么、参数怎么传、需要什么认证。」 - Jin Shield 安全网关：一个零延迟的中间件层，在请求到达业务逻辑之前验证 AI Agent 的加密身份，拦截未授权的访问和恶意爬虫。
简单类比：robots.txt 告诉搜索引擎「哪里不能爬」；sitemap.xml 告诉搜索引擎「有哪些页面」；而 jin.json 告诉 AI Agent「页面能做什么、怎么做」。
| 类比 | 面向传统 Web | 面向 AI Agent |
|---|---|---|
| 能力声明 | sitemap.xml | jin.json（意图映射） |
| 访问控制 | robots.txt | Jin Shield（加密身份 + 令牌验证） |
| 协议 | HTTP + 人类 UI | AIP（自然语言触发词 +结构化参数） |
核心概念：jin.json
一份典型的 jin.json 长这样：
{
"aip_version": "0.1",
"app": {
"name": "E-Commerce API",
"description": "Product lookup and checkout",
"url": "https://api.example.com"
},
"intents": [
{
"id": "search_products",
"name": "Search Products",
"description": "Lookup products by text query and category filters",
"triggers": [
"find a product",
"search for something to buy",
"show me what's available"
],
"category": "commerce",
"method": "GET",
"endpoint": "/api/products",
"parameters": {
"query": { "type": "string", "required": true, "description": "关键词" },
"category": { "type": "string", "required": false, "description": "筛选分类" }
},
"requires_auth": false,
"destructive": false,
"confirmation_required": false
}
]
}
每个 intent 定义了：
triggers：自然语言触发词。Agent 收到用户指令「帮我找一款游戏笔记本」后，会匹配到triggers中的"search for something to buy"，然后自动执行 GET/api/products?query=游戏笔记本。category：按标准分类法归类（commerce、travel、productivity、developer等），Agent 可以精准筛选需要的 API 类别。destructive/confirmation_required：标记该操作是否具有破坏性，Agent 在执行删除/下单等高风险操作前可以主动向用户确认。
3 分钟上手
安装 CLI
npm i -g @papercargo/jin-cli
生成意图映射
在你的项目根目录下运行：
npx @papercargo/jin-cli init
CLI 会自动检测你的项目框架——支持 Next.js、Express、FastAPI、Django REST、Flask、Laravel、Ruby on Rails、Fastify、Hono、NestJS、tRPC、OpenAPI 等 12 种框架。扫描路由定义后，自动生成 jin.json 框架。
编辑触发词
打开生成的 jin.json，为每个 endpoint 补充自然语言触发词：
"triggers": [ "下订单", "购买这个商品", "我要买" ]
验证并发布
npx @papercargo/jin-cli validate # 验证格式 npx @papercargo/jin-cli publish # 发布到公共注册表
发布后，所有支持 AIP 的 AI Agent 就能在 meetjin.com/registry 上动态发现你的 API 能力。
Jin Shield：加密身份认证层
当你的 API 暴露给大量 AI Agent 时，怎么区分哪些是合法的授权 Agent、哪些是恶意爬虫？Jin Shield 提供了一个极轻量的解决方案。
核心工作流程：
[ Agent 请求 ] → Jin Shield 中间件
│
├─ RS256 签名验证（本地内存缓存 JWKS 公钥）
├─ 载荷大小边界检查
│
├─ 验证通过 → (200) 转发到业务逻辑
└─ 验证失败 → (403) "Access Denied"
关键设计原则：
- 零外部依赖：JWKS 公钥在服务启动时缓存到内存中，每次请求验证都在本地完成，无外部网络调用，延迟小于 1ms。
- 无遥测回传：Jin Shield 不会将请求详情、IP 地址或 Agent 元数据发送给
meetjin.com或任何第三方。 - 异步威胁报告：如果检测到无效签名或恶意请求，通过
onThreatDetected回调异步上报，不阻塞正常请求。
Node（Express）集成示例
import express from 'express';
import { expressAdapter } from '@papercargo/jin-cli/dist/crypto/jin_core';
const app = express();
// 一行代码保护所有在 jin.json 中声明的 endpoint
app.use(expressAdapter({ cwd: process.cwd() }));
app.get('/api/products', (req, res) => {
res.json({ message: "验证通过，返回数据" });
});
app.listen(3000);
Python（FastAPI）集成示例
from fastapi import FastAPI
from jin_core import JinShieldMiddleware
app = FastAPI()
app.add_middleware(JinShieldMiddleware, cwd=".")
@app.get("/api/products")
def search_products(query: str):
return {"results": [f"搜索: {query}"]}
AIP vs OpenAPI：为什么需要一个新的协议？
OpenAPI（Swagger）已经是 API 文档的事实标准，为什么还需要 AIP？两者的设计目标完全不同：
| 维度 | OpenAPI | AIP |
|---|---|---|
| 目标用户 | 人类开发者阅读文档 | AI Agent 自动执行任务 |
| 发现路径 | 文档链接不统一 | 标准的 /.well-known/jin.json |
| 匹配逻辑 | URL 路径 + HTTP 动词 | 自然语言语义匹配 |
| 注册表集成 | 无原生支持 | 内置 meetjin.com 搜索索引 |
| 安装时间 | 手动配置，需要数小时 | CLI 自动扫描，数分钟完成 |
| 安全层 | 依赖手动密钥管理 | 标准化的非对称 Agent 护照验证 |
AIP 被设计为与 OpenAPI 互补而非替代——OpenAPI 描述接口的技术细节，AIP 把接口简化为 Agent 能理解的意图模型。
更多实用场景
除了 Web API 场景，Jin 还特别适合：
1. SaaS 平台接入
如果你经营一个 SaaS 产品，Agent 用户越来越多。用 Jin 声明你的 API 能力后，Agent 可以自动完成用户下单、查询用量、管理订阅等操作，无需你为每个 Agent 框架写专门的集成代码。
2. 企业内部工具
企业私有的 Jin 注册表（自托管）可以让内部 Agent 发现公司 ERP、CRM、HR 系统的 API 能力，通过自然语言触发内部流程。
3. 自建注册表
git clone https://github.com/meetjin/meetjin cd meetjin pnpm install cp .env.example .env pnpm dev
运行后，你的私有 Agent 只能访问你授权的内部 API。
注意事项与最佳实践
- AIP 是 CC0 公共领域许可：协议规范完全开放，可以 fork、修改或商用，无需署名。
- CLI 工具是 Apache 2.0：
@papercargo/jin-cli开源可用。 - 触发词的中英文混合：在中国网站中，可以用中英双语的
triggers，让中文 Agent 和英文 Agent 都能匹配。 - Jin Shield 不是 WAF 的替代品：它专注于 Agent 身份验证，基础的 Web 防火墙（如 Cloudflare）仍需并行部署。
总结
Jin 解决的是一个正在快速恶化的矛盾：AI Agent 在快速进化，但 Web 仍然是人类时代的 Web。用 HTML + DOM 解析让 Agent 理解网站，就像让人类读汇编代码来点外卖——技术上可行，体验上糟糕。
jin.json 提供了一种优雅的中间方案：网站只需要做很小的一次性声明，Agent 就能获得类似 API 文档级的理解能力，且双方都不需要修改核心架构。
如果你在运营一个被 AI Agent 频繁访问的网站或 API，或者你在构建 Agent 生态，Jin 值得一试。项目地址：github.com/meetjin/jin | 体验：meetjin.com