Capability Graph 是一个相对简单的静态能力图谱：从 JSON 文件加载 Provider 和能力定义，在内存中查询能力、关系及必要上下文，并按需读取关联文档。接入方可以通过自己的 Node.js API 或 MCP 将这些查询提供给使用者或 Agent。
本文对应 2.0.0 的源码接口。使用发布包前先确认确切版本可用；E404 时按安装页固定文档提交构建源码。网络、认证或镜像失败不能证明版本不存在。源码修改不会自动发布 npm 或部署站点。
npm view @devcodex/capability-graph@2.0.0 version
npm install @devcodex/capability-graph@2.0.0Node.js：^20.19.0 || >=22.12.0。ESM 与 TypeScript 类型覆盖根 SDK、/mcp、/mcp/server、/readers/http 四个入口；CLI 名称为 capability-graph。根 SDK 导入不会启动服务或注册配置。2.0 移除了数据库权威来源、能力召回、知识检索和 Runtime，升级前查看2.0 迁移清单。已发布的 1.1.0 与其 tag 保留原有接口。
以下能力对应本次源码与本地打包制品，使用 Registry 前核验确切版本及子入口。未发布时，在当前对应源码根运行 npm ci、npm pack --pack-destination ../packages，安装本次生成的 tgz；公开站和源码不会自动发布。
| 方式 | 入口与资源归属 |
|---|---|
| 普通JSON / 自有模型宿主 | /mcp 的 createCapabilityGraphToolkit(graph)；12个冻结JSON Schema，宿主决定调用流程，借用graph |
| SDK v1/v2内嵌 | 同一toolkit分别接低层Server或McpServer.registerTool；可合并Provider自有工具和渐进发现 |
| 独立stdio/HTTP | /mcp/server 的 createCapabilityGraphServer；默认127.0.0.1:3333/mcp，借用graph，调用方负责关闭Reader/graph |
| 全局CLI | serve/provider/codex/doctor/assist；服务配置增删下次启动生效 |
| HTTP文档 | /readers/http 的 HttpKnowledgeReader；精确Origin、UTF-8字节、取消和可选快照，宿主关闭Reader及自己的Agent |
默认账户配置为 ~/.capability-graph/config.json，最小内容 {"schemaVersion":1,"providers":[]}；--config可显式选择文件。下面命令以已有本地打包制品为前提：
npm install -g ./packages/devcodex-capability-graph-2.0.0.tgz
capability-graph provider add --id acme.http --root /absolute/path/providers/acme-http --layout directory
capability-graph doctor --json第一条只有在能证明正常直接全局安装时自动注册stdio并完成临时协议探针；不会创建虚构Provider。--ignore-scripts、本地/依赖安装或无法证明直接目标时，可运行 capability-graph codex register。provider add --root填写你实际的目录，示例路径需替换；Provider ID须与该目录的provider.json一致。添加配置后重新启动服务。
诊断分别返回 installed/configRegistered/localProtocolVerified/clientConnected；临时探针通过后，外部Codex客户端连接仍可为unknown。完整示例、变量来源、配置默认值与排错见MCP与CLI接入。卸载前运行 capability-graph codex unregister，再 npm uninstall -g @devcodex/capability-graph；Provider资料和配置保留。
在接入项目准备以下目录；Provider 目录是数据，不需要单独安装依赖：
providers/
└── acme-http/
├── provider.json
├── capabilities/
│ └── route.json
└── knowledge/
└── routing.md
provider.json：
{ "providerId": "acme.http", "name": "Acme HTTP", "version": "1" }capabilities/route.json：
{
"capabilityId": "route",
"name": "HTTP routing",
"description": "Declare HTTP routes.",
"whenToUse": "An application needs an HTTP endpoint.",
"knowledge": [{
"kind": "document", "knowledgeId": "routing-guide", "role": "guide",
"locator": { "type": "relative-file", "path": "knowledge/routing.md" }
}]
}将实际路由说明保存到 knowledge/routing.md，再运行 ESM 脚本：
import path from 'node:path';
import { CapabilityGraph } from '@devcodex/capability-graph';
const graph = await CapabilityGraph.open({
hostAllowedProviders: ['acme.http'],
integrationEnabledProviders: ['acme.http'],
providers: [{ providerId: 'acme.http', authority: {
kind: 'file', definitionLayout: 'directory', rootDir: path.resolve('providers/acme-http')
} }]
});
try {
const provider = graph.forProvider('acme.http');
const catalog = await provider.listCatalog({ limit: 20 });
const selection = await provider.resolveSelection({ selected: ['route'] });
const document = await provider.readDocumentPage({ capabilityId: 'route', knowledgeId: 'routing-guide' });
console.log({ catalog, selection, document });
} finally { await graph.close(); }完整首次接入见最小 Provider，逐步添加关系、文档与规范见进阶教程。
| 操作 | 用途 |
|---|---|
listProviders / getProvider / listSpecificationDocuments |
Provider 与规范文档元数据 |
listCatalog / getCapabilities |
分页发现、结构化过滤与有界详情 |
getNeighbors / resolveSelection |
八种正反向关系；沿 requires 展开必要上下文 |
listKnowledgeMembers |
Collection 文档成员发现 |
readDocuments / readSpecification |
显式读取完整文档，逐项检查 ok |
readDocumentPage / readSpecificationPage |
原始 UTF-8 字节分页，调用方决定范围及是否续读 |
reload / close |
显式更新定义、保留 current/previous、释放图谱资源 |
完整身份是 { providerId, capabilityId }，显示形式为 acme.http::route。parents、specializes、requires 分别无环；related 有方向。关系端点必须在同一 Provider 内；联合目录保留各自身份与修订。选择由调用方决定，Core 仅沿 requires 补齐上下文。
文件根在 open 时固定。新目录启用 directory；缺省 legacy 继续读取 *.capability.json。定义最多 262144 UTF-8 字节，文档总大小没有准入上限。全文默认每篇返回 32 KiB、每次最多 8 篇；较大正文改用默认 32 KiB 的分页读取，保留全文身份与游标。正文变化会拒绝旧游标，分页拼接保留 BOM、CRLF 和原始 UTF-8。
文档支持 Provider 内目录、显式获准的外部目录、真实 node_modules 包根，以及通过宿主 KnowledgeReader 读取的 URL。knowledgeRoots 配置来源别名，locator 的 root 只引用该 Provider 的别名；私有根不会进入公共结果。URL Reader 的访问策略、连接和关闭由宿主管理。
每个启用 Provider 必须恰有一个文件来源；scope 只能缩小。检查 meta.completeness、warnings、逐项 ok 和续页游标。reload 完整校验新定义后才替换视图，失败保留旧视图并标记 refreshFailed；更旧的修订明确失败。
能力图谱负责声明与查询。能力执行、Agent 意图判断、业务项目状态、RAG 的分块索引/Embedding/数据库/排名以及回答生成由宿主或独立模块负责。这里的文档分页是原文访问，不是知识检索。未来 RAG 可以使用公开能力身份、文档引用和分页接口，自行管理索引；主包不预留空检索框架。
共享MCP工具层提供12个查询，独立服务处理协议、入站校验和请求生命周期。Provider可在自己的宿主合并工具、资源和渐进发现策略。自定义Reader是进程内受信任代码，Provider scope不隔离进程。
- Seed API：图谱发现、选择、文档与规范的完整链路。
- Seed MCP：SDK v1私有宿主，复用12个共享查询工具并保留Provider自有规范Resource。
- HTTP Reader：真实 HTTP、原字节分页、ETag、取消和资源清理。
- VextJS：固定来源的官方文档主题、安装包及 URL 读取；验证说明与实际执行范围一致。
npm ci
npm test
npm run test:package
npm run test:consumers
npm run test:install
npm run evaluate
npm run demo:http
npm run evaluate:capacity容量验证默认 1 万文件节点、2 个 Provider、10 并发，核对完整目录、关系、Selection、reload、已 pin 查询与 close。读取使用明确标注的受控 Reader，真实网络由 HTTP/VextJS 验证覆盖；本机延迟与采样内存不代表生产容量承诺。
正式站点测试位于 test/website，验证工具位于 scripts/validation/website，website 保存文档、主题、资源与站点配置。临时消费者、日志、报告和生成产物放在项目同级专用目录，通过 CG_ARTIFACTS_DIR 指定；普通构建输出为 dist/ 和 dist-test/，云端验证在仓库外副本执行。