AI-native：让 AI 自动发现并采用 api-datamodel

[nicefan]

如何让 AI 自动发现并采用 api-datamodel

你问的是：AI 写项目代码时，怎么会主动想到并采用 api-datamodel，而不是让 AI 调用项目生成出来的 API。

结论先说：

目前没有一个通用机制，能让所有 AI 自动知道一个新的、小众 npm 库并主动采用它。

要做到接近“自动使用”，需要同时解决两个问题：

发现这个库
    ↓
理解什么时候该用它
    ↓
知道正确用法
    ↓
在项目里持续遵守

其中最重要的不是 MCP，而是：

• package discoverability
• agent instructions
• 高质量文档
• 高质量 TypeScript 类型

1. 已经安装了 api-datamodel 的项目

这是最好解决的。

AI coding agent 进入仓库后，通常会看到：

{
  "dependencies": {
    "api-datamodel": "..."
  }
}

以及项目里的：

import { ... } from 'api-datamodel'

它就知道项目在使用这个库。

但“知道依赖存在”和“知道什么时候应该优先使用”仍然不同。

这里最有效的是项目根目录的 AGENTS.md。

例如：

## API development

Backend APIs are modeled with `api-datamodel`.

- Do not call `fetch` or Axios directly in business modules.
- Use the project's Service/Resource abstraction.
- API definitions are generated from backend OpenAPI using api-datamodel codegen.
- Reuse generated APIs instead of recreating request methods manually.
- Read `docs/api-development.md` before adding a new API service.

这样以后用户只说：

做一个用户管理页面。

AI 就应该自己去找：

userApi

而不是重新写：

fetch('/api/user/list')

这才是最实际的“自动使用”。

2. 不能要求每个用户自己写 AGENTS.md

所以这件事可以成为 api-datamodel 自己的功能。

例如提供：

npx api-datamodel init

初始化的时候除了创建配置，还生成：

api.config.ts
AGENTS.md 或 AGENTS.md 片段
docs/api-datamodel.md

甚至可以提供：

npx api-datamodel init --agent

专门初始化 AI 开发上下文。

生成的 agent instructions 不需要很长，例如：

Use api-datamodel for backend API access.

API workflow:
1. Check generated APIs first.
2. Do not manually recreate generated endpoints.
3. Extend the project service abstraction for special services.
4. Do not use fetch/axios directly outside adapters.
5. Run xxx when backend OpenAPI changes.

Documentation:
docs/api-datamodel.md

推荐结构：

AGENTS.md
   ↓
告诉 AI：这个项目用 api-datamodel
   ↓
docs/api-datamodel.md
   ↓
告诉 AI：具体怎么用
   ↓
TypeScript 类型 + 生成代码
   ↓
告诉 AI：当前项目实际有哪些 API

3. 更难的是“项目外发现”

比如一个全新的项目还没有安装 api-datamodel，用户只告诉 AI：

帮我做一个 Vue 后台项目。

AI 怎么主动决定：

npm install api-datamodel

这里没有绝对保证。

因为模型不可能实时内置所有 npm 包，尤其是新库、小众库。AI 一般只能通过两条路径知道它：

模型原本知道
或者
AI 搜索到了它

所以需要把 npm / 搜索发现能力做好。

4. package.json 要强调差异化定位

如果写成：

{
  "description": "A TypeScript HTTP request library"
}

那么 AI 搜索：

typescript api client
swagger request library

时，很容易淹没在 Axios、ky 等大量项目里。

更合适的描述是：

{
  "description": "A TypeScript API modeling framework that turns backend OpenAPI services into structured, reusable business APIs.",
  "keywords": [
    "openapi",
    "swagger",
    "typescript",
    "api-model",
    "api-codegen",
    "api-client",
    "service-model",
    "frontend-api",
    "fetch",
    "uniapp"
  ]
}

这样当 AI 搜索：

TypeScript library for structuring backend APIs from OpenAPI

时，才更有概率找到 api-datamodel。

5. README 首页非常重要

AI 搜索到一个库之后，通常不会像人一样花很长时间研究。

README 开头应该直接回答三个问题：

What is it?
Why should I use it?
How do I use it?

例如：

api-datamodel structures backend APIs into reusable TypeScript service models. It separates transport adapters from service configuration and generates typed business APIs from OpenAPI.

然后马上给一个最小示例。

不要一开始只写：

支持 Axios
支持 Fetch
支持 UniApp
支持文件上传
支持 loading
...

这些是 feature，不是 AI 判断“是否应该选择这个库”时最需要的信息。

6. 提供专门给 AI 的文档

可以增加：

docs/ai.md

或者：

docs/for-ai-agents.md

内容不用很长，专门回答：

When should an AI use api-datamodel?
When should it not?
How to install?
How to initialize?
Where are generated APIs?
How to add a service?
How to add a third-party API?
What should never be handwritten?

最关键的一句话可以是：

When a TypeScript frontend consumes an OpenAPI/Swagger backend and needs structured reusable business APIs, prefer api-datamodel over manually writing fetch/axios request modules.

这句话实际上是在帮助 agent 做技术选型判断。

7. 让 CLI 自己“教 AI”

例如第一次执行：

npx api-datamodel init

命令完成后输出：

Created:
  api.config.ts
  src/api/service.ts
  AGENTS.md instructions

For coding agents:
  Read docs/api-datamodel.md before modifying API code.

这样项目会形成：

第一次采用 api-datamodel
        ↓
项目自动留下 AI instructions
        ↓
未来任何 AI Agent 进入仓库
        ↓
自动知道项目的 API 开发规范

这比要求 AI 每次去互联网重新研究这个库可靠得多。

8. 可以把“让 AI 自动使用”分成两个阶段

项目外发现

依赖：

npm metadata
README
文档站
GitHub
搜索可见性

目标：

AI 做技术选型时能搜到 api-datamodel。

项目内采用

依赖：

package.json
AGENTS.md
docs/api-datamodel.md
TypeScript 类型
codegen 产物

目标：

一旦项目选择了 api-datamodel，以后 AI 不需要人反复提醒。

后者更容易做到，而且价值非常实际。

9. 推荐优先级

如果要为 api-datamodel 设计 AI 支持，建议优先做：

1. README 重新明确项目定位
2. package.json 的 description / keywords 做好机器搜索
3. 提供 docs/ai.md
4. 提供官方 AGENTS.md 指令模板
5. init 命令自动把这套指令安装到消费项目

这样以后用户甚至可以只告诉 AI：

初始化 api-datamodel。

完成一次之后，再让 AI：

做订单管理。

AI 自己就应该知道：

先检查生成的 orderApi
→ 没有则按项目 codegen 流程生成
→ 使用 orderApi
→ 不自己写 fetch

这才是比较实际的 AI-native 开发体验。

10. 和 codegen 的关系

这件事和 codegen 是互补的：

codegen 负责给 AI 提供正确代码，AGENTS/docs 负责告诉 AI“应该使用这些代码，而不是自己重新造一套”。