> For AI agents: the complete documentation index is available at https://devcodex-labs.github.io/capability-graph/llms.txt, the full documentation bundle is available at https://devcodex-labs.github.io/capability-graph/llms-full.txt.

# 使用运行时

Core 可用；HTTP 参考实现可运行

Runtime 接入从一个明确 Adapter 开始。Adapter 接收 Provider、项目、环境、可选静态能力过滤和分页游标，返回实例与观察证据。

只有需要确认“当前项目实际注册了什么”时才接 Runtime；仅发现框架支持的能力，无需启动业务服务。

下面是接入片段：先构建仓库示例并由应用启动 Seed HTTP 服务，取得它实际监听的地址。`runtimeAdapter` 使用仓库 `examples/seed-runtime/adapter.ts` 的 `HttpRuntimeAdapter`，不是主包内置导出；实例化方式和端点约束见[Runtime Adapter](https://devcodex-labs.github.io/capability-graph/integrations/runtime-adapter.md)。`providers` 指向仓库的 `examples/seed-provider`，`project`/`environment` 必须与服务启动配置一致。完整自动执行路径见[真实 Runtime 示例](https://devcodex-labs.github.io/capability-graph/examples/seed-provider.md#%E7%9C%9F%E5%AE%9E-runtime)。

```ts
const graph = await CapabilityGraph.open({
  hostAllowedProviders: ['seed.http'],
  integrationEnabledProviders: ['seed.http'],
  providers: [{
    providerId: 'seed.http',
    authority: { kind: 'file', rootDir: '/absolute/path/to/examples/seed-provider' }
  }],
  runtimeAdapters: [runtimeAdapter]
});

try {
  const provider = graph.forProvider('seed.http');
  const requiredStaticRevision = (await provider.listCatalog()).meta.staticRevision;
  const page = await provider.queryRuntime({
    project: 'demo-app',
    environment: 'development',
    instanceOf: { capabilityId: 'route.http' },
    requiredStaticRevision
  });
  console.log(page.items, page.observation, page.meta);
} finally {
  await graph.close();
}
```

片段还需从主包导入 `CapabilityGraph`。不要直接复制未创建 `runtimeAdapter` 的片段运行；若只想验证查询链，请执行示例页的测试命令，它会启动并清理真实服务。

## 预期结果

服务已注册 `POST /users` 时，`items` 可包含 `instanceId: 'POST /users'`、`instanceOf: { providerId: 'seed.http', capabilityId: 'route.http' }` 以及 method/path facts。实际是否存在取决于该进程的注册表，静态能力存在不保证实例存在。

成功空观察用 `availability: empty`；`stale` 是新鲜度字段，`partial` 表示覆盖不完整。未配置 Adapter 是 `CG_RUNTIME_DISABLED`，服务连接失败或等待超时是 `CG_RUNTIME_UNAVAILABLE`，不能都显示成“没有路由”。排错见[运行时与超时](https://devcodex-labs.github.io/capability-graph/troubleshooting/runtime-states.md)。

## Adapter 必须保证

- 项目与环境不会混淆；
- 实例身份稳定，`instanceOf` 无歧义；
- 观察状态区分可用、空、过期、部分和失败；
- `runtimeRevision` 与观察依据可追溯；
- 超时停止等待，但不谎称已取消底层工作。

真实参考服务会实际采集已注册 HTTP 路由，并验证路由变化、环境隔离和失败恢复。Core 不启动该服务，也不扫描任意框架。