docs: 技术栈与工程约束写入 AGENTS.md，交付形态定为 pip 包

- 新增 AGENTS.md：技术栈选型、五条架构决策、硬规则、目录、命令、测试策略
- 明确不提供独立 HTTP 服务：核心包禁止 fastapi，路由由宿主 include_router 挂载
- README 同步：集成方式改为纯库/挂路由/嵌入式三种，FastAPI 列为 [api] 可选依赖
- 非目标补充“不做独立服务”

README.md

@@ -5,6 +5,8 @@
 面向其他项目的底层对接件，不是业务系统，也不是通用 ORM。上层项目只需要一份本体 YAML + 本适配器，就能对实体、关系、属性做对象级操作，而不用关心底下是文档表、图还是时序表。
 
 > 状态：设计稿（v0.1）。仓库当前只有初始提交，实现尚未开始。本文是接口与存储映射的契约，先定契约再写代码。
+>
+> 工程约定（技术栈、硬规则、目录、命令、测试策略）见 **`AGENTS.md`** —— 那是给编码工具和协作者看的执行约束，本文只讲"是什么、为什么"。
 
 ---
 
@@ -241,27 +243,48 @@ adapter.functions("Line")["utilization"]                                  # Func
 adapter.validate("SensorReading", row)                                    # Constraints
 ```
 
-FastAPI 侧自动从本体生成路由（同一份 YAML，不重复声明）：
+FastAPI 侧不提供独立服务：`build_router()` 返回一个 `APIRouter`，由宿主项目的 `app.include_router()` 挂进去。路由从本体自动生成，同一份 YAML 不重复声明：
+
+```python
+from fastapi import FastAPI
+from adapter_python_pg import Adapter, build_router
+
+adapter = Adapter.load("ontology/factory-twin.yaml", dsn=settings.pg_dsn)
+
+app = FastAPI()
+app.include_router(build_router(adapter), prefix="/ontology")
+```
 
 ```text
-GET    /entities/{entity}                列表 / 过滤
-GET    /entities/{entity}/{id}           单实体（可选 ?expand=links）
-POST   /entities/{entity}                写入
-PATCH  /entities/{entity}/{id}           部分更新
-POST   /graph/traverse                   多跳查询
-POST   /timeseries/{entity}/write        时序写入
-POST   /timeseries/{entity}/query        时序聚合
-POST   /actions/{action}                 执行 Action
-GET    /ontology                         返回已加载的本体元数据
+GET    /ontology/entities/{entity}                列表 / 过滤
+GET    /ontology/entities/{entity}/{id}           单实体（可选 ?expand=links）
+POST   /ontology/entities/{entity}                写入
+PATCH  /ontology/entities/{entity}/{id}           部分更新
+POST   /ontology/graph/traverse                   多跳查询
+POST   /ontology/timeseries/{entity}/write        时序写入
+POST   /ontology/timeseries/{entity}/query        时序聚合
+POST   /ontology/actions/{action}                 执行 Action
+GET    /ontology/meta                             返回已加载的本体元数据
 ```
 
+OpenAPI 是**泛化 schema**（`entity` 走路径参数），不逐实体生成 typed 路由——这是刻意的取舍，见 AGENTS.md §4。
+
 ## 8. 集成到其他项目
 
-三种姿势，按侵入程度从低到高：
+**交付形态是 pip 包，不是独立服务。** 本适配器不启动 HTTP 服务、不占端口、没有自己的 procfile——它住在宿主进程里。
 
-1. **HTTP**：独立跑 `uvicorn adapter_python_pg.app:app`，其他语言/服务直接调 REST。
-2. **Python 库**：`pip install -e .`，`Adapter.load()` 后当普通对象用，进程内零网络开销。
-3. **嵌入式**：把本体 YAML 打进宿主项目，adapter 作为其内部数据层，宿主不感知 PostgreSQL。
+```bash
+pip install git+ssh://git@gitlab.cnsjzn.com/donnyzhang/adapter_python_pg.git
+pip install "adapter_python_pg[api] @ git+ssh://..."   # 需要 FastAPI 路由时
+```
+
+三种用法，同一个包：
+
+1. **纯库（最常见）**：宿主只调 `Adapter` 的语义接口，不挂 HTTP 路由，FastAPI 依赖都不用装。
+2. **挂路由**：宿主已有 FastAPI 应用，`app.include_router(build_router(adapter))` 把它当子路由，权限、中间件、鉴权沿用宿主那套。
+3. **嵌入式**：本体 YAML 打进宿主仓库，adapter 作为宿主内部的数据层，外部完全不知道 PostgreSQL 存在。
+
+核心依赖只有 psycopg / age / pydantic / pyyaml / cel-python；**FastAPI 属于 `[api]` 可选依赖**，装了才有路由能力。
 
 ## 9. 与存储的关系
 
@@ -271,6 +294,7 @@ GET    /ontology                         返回已加载的本体元数据
 
 ## 10. 非目标
 
+- **不做独立服务**：不提供可独立部署的 HTTP 服务、不做多租户网关、不接管鉴权（那是宿主的事）
 - 不做通用 ORM（不复刻 SQLAlchemy 的表达式系统；复杂 SQL 走 `raw()` 逃生口）
 - 不做本体编辑器 / 可视化（那是前端的事）
 - 不做数据迁移与版本演进工具（本体版本变更先手工处理，后续再谈）