内容
# 🧭 智能代理本体工具包
**让人工智能代理在行动前理解业务。**
智能代理本体工具包是一种**适用于人工智能代理的便携式技能**。它读取公司、产品、API、市场或代码库，并编写一个干净、结构化的**映射该领域工作原理**的地图——存在的事物、可以采取的行动以及它们之间的规则——以人工智能代理可以使用的形式，在它行动之前。
无需框架。无需构建步骤。只需将 Markdown 文件交给任何 capable 代理（Claude Code、Codex、Cursor、自定义运行器），再加上一个 tiny Python 验证器。
**▶ [实时讲解 — 普通话](explain.html) · [示例](#-worked-examples) · [快速入门](#-quick-start)**
---
## 🤔 问题
人工智能代理擅长于*执行*任务——退款、预订时间、调用 API。但它们不擅长于*理解业务*。代理会乐意退款一个从未支付的订单，因为没有人告诉它这是不可能的。
本工具包使这种理解**显式、可检查和可重用**。
## 🧱 它构建的内容：四层
想象一下向机器人描述一个**咖啡店**——从“适用于任何事物”到“这家特定的商店”。
| 层级 | 普通话 | 咖啡店示例 |
|---|---|---|
| **L0 · 上层** | 普遍的事物类型 | 事物、人员、数量 |
| **L1 · 领域** | 行业名词 | 订单、饮料、咖啡师 |
| **L2 · 任务** | 动作 + 规则 | 取单、退款 *（“不能退款未支付的订单”）* |
| **L3 · 应用** | 该确切系统的文件 | `orders` 表、“新建订单”按钮 |
使其值得做的 discipline：**每个 L3 映射到 L1，每个 L1 锚定到 L0，每个 L2 命名它所触及的 L1 名词。** 跨层映射表是交付成果。
## 🚀 快速入门
给予任何 capable 代理：
```text
使用 AGENT_SKILL.md 作为工作流程。
目标：<公司、API、产品、市场或代码库>
消费者：<MCP 代理工具 | RAG | 知识图谱 | 数据库/API 模式 | 文档>
边界：<范围内和范围外内容>
交付：YAML 层、映射表、验证注释和消费者绑定。
```
就是这样。代理范围目标、挖掘源、构建四层、验证它们，并发出消费者需要的输出。
## 🛠️ 在本地运行工具（可选）
```bash
cd ontology-extraction
python scripts/scaffold.py init --name my-target --out ../my-target-ontology
# ...填充 YAML 层...
python scripts/scaffold.py validate ../my-target-ontology # 0 错误 = 结构健全
python scripts/scaffold.py mappings ../my-target-ontology # 重新生成映射表
```
唯一依赖是 `pyyaml`（`pip install pyyaml`）。技能本身不需要任何依赖。
## 📦 您获得的内容
一个 7 文件的工作空间和消费者特定的绑定：
```
my-target-ontology/
00-scope.md 目标、消费者、边界、能力问题
10-upper.yaml L0 — 选择的通用锚点（已选择，永不发明）
20-domain.yaml L1 — 领域名词 + 关系
30-task.yaml L2 — 动作，带有输入/输出/前提/效果
40-application.yaml L3 — 具体的系统工件
50-mappings.yaml 应用 → 领域 → 上层映射表
README.md
```
…然后是一个绑定：**MCP 工具模式**，RDF/Turtle 知识图谱，TypeScript/Pydantic 类型，RAG 元数据或 Mermaid 图。
## 🧪 已完成的示例
[`examples/`](examples/) 中的五个运行，每个都通过捆绑的脚本进行了干净的验证：
| 评估 | 目标 | 亮点 |
|---|---|---|
| `eval-1-stripe` | Stripe（研究） | API → 安全的 MCP 工具，内置前提条件 |
| `eval-2-realworld` | RealWorld 应用（改造） | 将现有代码库映射到其领域 |
| `eval-3-prediction-markets` | 市场（研究） | 一个稀疏/新兴领域 |
| `eval-4-self` | **工具包本身** | 它描述了自己的代码 — **0 错误** |
| `eval-5-adyen` | Adyen（研究） | **竞争者交换 vs Stripe：8/9 领域概念匹配** ⭐ |
关于后两个的普通话讲解在 **[explain.html](explain.html)** 中。
## 💡 为什么是四层（收益）
因为中间层属于*行业*，而不属于*供应商*。我们证明了这一点：为 **Stripe 和 Adyen** 构建相同的模型，**8 个核心概念匹配** — 只有特定的供应商层有所不同（参见 [`examples/eval-5-adyen/comparison-vs-stripe.md`](examples/eval-5-adyen/comparison-vs-stripe.md)）。在共享层上构建代理；无需重新教授业务即可更换提供商。
## 🔌 作为技能使用
- **Claude Code / Cursor / Codex:** 指向代理的 `AGENT_SKILL.md`，或将 `ontology-extraction/` 文件夹放入技能目录（它有一个准备好的 `SKILL.md`，带有触发器前置信息）。
- **任何运行器：** 工作流程是普通的 Markdown — 无运行时锁定。
## 🌐 发布网站（GitHub Pages，无需构建）
`index.html`（主页）和 `explain.html`（讲解）是自包含的静态 HTML。**设置 → 页面 → 从分支部署 → `main` / `(root)`。**
您的实时网站：`https://<您的用户名>.github.io/<仓库>/`。
## 🗺️ 工作原理
**从中间到外部** 工作：范围 → 能力问题 → 挖掘源 → 锚定 L0 → 构建 L1 → 构建 L2 → 投影 L3 → 验证 → 发出绑定。完整方法在
[`ontology-extraction/SKILL.md`](ontology-extraction/SKILL.md)；证据规则和重用目录在
[`ontology-extraction/references/`](ontology-extraction/references/).
## 📁 仓库布局
```
.
├─ README.md
├─ AGENT_SKILL.md ← 便携式工作流程 — 将此交给任何代理
├─ index.html · explain.html ← 零构建网站（部署到 GitHub Pages）
├─ ontology-extraction/
│ ├─ SKILL.md
│ ├─ scripts/scaffold.py ← 初始化 · 验证 · 映射
│ └─ references/ ← 源挖掘 · 重用目录 · 输出格式
└─ examples/ ← 5 个已完成、验证的评估
```
## 🤝 贡献
欢迎 PR — 新的已完成评估（真实的公司/API/代码库 + 其验证的本体）是最有价值的贡献。在打开 PR 之前运行 `scaffold.py validate`。
## 📄 许可证
[MIT](LICENSE) © 2026 New1Direction
MCP 市场