@labacacia/nps-sdk 1.0.0-alpha.1 → 1.0.0-alpha.2

package/doc/nps-sdk.nwp.cn.md

@@ -0,0 +1,217 @@
+[English Version](./nps-sdk.nwp.md) | 中文版
+
+# `@labacacia/nps-sdk/nwp` — 类与方法参考
+
+> 规范：[NPS-2 NWP v0.4](https://github.com/labacacia/nps/blob/main/spec/NPS-2-NWP.md)
+
+NWP 是 AI 的 HTTP。本模块提供两个 NWP 帧
+（`QueryFrame`、`ActionFrame`）、异步 `NwpClient`，以及用于查询排序、
+向量检索和异步动作响应的 dataclass 风格接口。
+
+---
+
+## 目录
+
+- [`QueryOrderClause`](#queryorderclause)
+- [`VectorSearchOptions`](#vectorsearchoptions)
+- [`AsyncActionResponse`](#asyncactionresponse)
+- [`QueryFrame` (0x10)](#queryframe-0x10)
+- [`ActionFrame` (0x11)](#actionframe-0x11)
+- [`NwpClient`](#nwpclient)
+
+---
+
+## `QueryOrderClause`
+
+```typescript
+interface QueryOrderClause {
+  field: string;
+  dir:   "asc" | "desc";
+}
+```
+
+---
+
+## `VectorSearchOptions`
+
+```typescript
+interface VectorSearchOptions {
+  vector:       readonly number[];
+  topK?:        number;
+  minScore?:    number;
+  vectorField?: string;
+}
+```
+
+当目标 Memory Node 广告 `nwp:vector` 时，附加到 `QueryFrame.vectorSearch`。
+
+---
+
+## `AsyncActionResponse`
+
+```typescript
+interface AsyncActionResponse {
+  taskId:   string;
+  status:   string;   // "pending" | "running" | …
+  pollUrl?: string;
+}
+
+function asyncActionResponseFromDict(
+  data: Record<string, unknown>,
+): AsyncActionResponse;
+```
+
+当 `ActionFrame` 以 `async_ === true` 提交时，由 `NwpClient.invoke` 返回。
+
+---
+
+## `QueryFrame` (0x10)
+
+针对 Memory Node 的结构化读取。
+
+```typescript
+class QueryFrame {
+  readonly frameType:     FrameType.QUERY;
+  readonly preferredTier: EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly anchorRef?:    string,
+    public readonly filter?:       Record<string, unknown>,
+    public readonly limit?:        number,
+    public readonly offset?:       number,
+    public readonly orderBy?:      readonly QueryOrderClause[],
+    public readonly fields?:       readonly string[],
+    public readonly vectorSearch?: VectorSearchOptions,
+    public readonly depth?:        number,
+  );
+
+  toDict(): Record<string, unknown>;
+  static fromDict(data: Record<string, unknown>): QueryFrame;
+}
+```
+
+线路形式（由 `toDict` 发出）使用 snake-case 键：
+`anchor_ref`、`order_by`、`vector_search` 等。
+
+---
+
+## `ActionFrame` (0x11)
+
+针对 Action / Complex / Gateway Node 的操作调用。
+
+```typescript
+class ActionFrame {
+  readonly frameType:     FrameType.ACTION;
+  readonly preferredTier: EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly actionId:        string,
+    public readonly params?:         Record<string, unknown>,
+    public readonly async_?:         boolean,
+    public readonly idempotencyKey?: string,
+    public readonly timeoutMs?:      number,
+  );
+
+  toDict(): Record<string, unknown>;
+  static fromDict(data: Record<string, unknown>): ActionFrame;
+}
+```
+
+- `actionId` 是 Action Node 的 `.nwm.json` → `endpoints.actions[].id` 中
+  声明的标识符。
+- `async_` 在线路上序列化为 `"async"`（尾下划线避免与 JS 关键字冲突）。
+- `idempotencyKey` —— 存在则节点必须在其重放窗口内去重。
+
+---
+
+## `NwpClient`
+
+使用 `Content-Type: application/x-nps-frame` 与 NWP 节点通信的异步 HTTP 客户端。
+
+```typescript
+class NwpClient {
+  constructor(
+    baseUrl: string,
+    options?: {
+      defaultTier?: EncodingTier;   // 默认：MSGPACK
+      maxPayload?:  number;         // 默认：65 535
+      registry?:    FrameRegistry;  // 默认：NCP + NWP 帧
+    },
+  );
+
+  async sendAnchor(frame: AnchorFrame): Promise<void>;
+  async query(frame: QueryFrame): Promise<CapsFrame>;
+  stream(frame: QueryFrame): AsyncGenerator<StreamFrame>;
+  async invoke(frame: ActionFrame): Promise<unknown>;
+}
+```
+
+`baseUrl` 的尾斜杠自动去除。
+
+### HTTP 路由
+
+| 方法 | 路径 | 请求体 | 响应 |
+|------|------|--------|------|
+| `sendAnchor` | `POST /anchor` | `AnchorFrame` 线路字节 | `204 No Content` |
+| `query`      | `POST /query`  | `QueryFrame` 线路字节 | `CapsFrame` 线路字节 |
+| `stream`     | `POST /stream` | `QueryFrame` 线路字节 | 分块 `StreamFrame` 直至 `is_last=true` |
+| `invoke`     | `POST /invoke` | `ActionFrame` 线路字节 | 动作结果 |
+
+`invoke()` 按 `frame.async_` 分派：
+
+- `false` → 依据 content-type 解码响应。若服务器返回
+  `application/x-nps-frame`，body 由编解码器解码；否则按 JSON 解析。
+- `true` → 解析 JSON 返回 `AsyncActionResponse`。轮询 `pollUrl`
+  观察进度。
+
+所有方法在非 2xx HTTP 状态时抛普通 `Error`。流帧被独立发出 ——
+用 `for await` 消费生成器。
+
+---
+
+## 端到端示例
+
+```typescript
+import {
+  NwpClient, QueryFrame, QueryOrderClause,
+  ActionFrame, AsyncActionResponse,
+  VectorSearchOptions,
+} from "@labacacia/nps-sdk/nwp";
+
+const nwp = new NwpClient("https://products.example.com");
+
+// 1) 一次性上传 anchor
+await nwp.sendAnchor({
+  frame:     "0x01",
+  anchor_id: "sha256:…",
+  schema:    { fields: [
+    { name: "id",    type: "uint64" },
+    { name: "price", type: "decimal", semantic: "commerce.price.usd" },
+  ]},
+  ttl:       3600,
+});
+
+// 2) 查询一页
+const caps = await nwp.query(new QueryFrame(
+  "sha256:…",
+  { price: { $lt: "100.00" } },
+  50,
+  undefined,
+  [{ field: "price", dir: "asc" }],
+));
+console.log(caps.count, "行, cursor:", caps.next_cursor);
+
+// 3) 流式获取全量
+for await (const chunk of nwp.stream(new QueryFrame("sha256:…"))) {
+  for (const row of chunk.data) { /* … */ }
+  if (chunk.isLast) break;
+}
+
+// 4) 触发异步动作
+const resp = await nwp.invoke(new ActionFrame(
+  "restock",
+  { sku: "sku-4242", qty: 100 },
+  true,
+));
+// resp 是 AsyncActionResponse
+```

package/doc/nps-sdk.nwp.md

@@ -0,0 +1,224 @@
+English | [中文版](./nps-sdk.nwp.cn.md)
+
+# `@labacacia/nps-sdk/nwp` — Class and Method Reference
+
+> Spec: [NPS-2 NWP v0.4](https://github.com/labacacia/nps/blob/main/spec/NPS-2-NWP.md)
+
+NWP is the HTTP-of-AI. This module ships the two NWP frames
+(`QueryFrame`, `ActionFrame`), the async `NwpClient`, and supporting
+dataclass-like interfaces for query ordering, vector search, and async
+action responses.
+
+---
+
+## Table of contents
+
+- [`QueryOrderClause`](#queryorderclause)
+- [`VectorSearchOptions`](#vectorsearchoptions)
+- [`AsyncActionResponse`](#asyncactionresponse)
+- [`QueryFrame` (0x10)](#queryframe-0x10)
+- [`ActionFrame` (0x11)](#actionframe-0x11)
+- [`NwpClient`](#nwpclient)
+
+---
+
+## `QueryOrderClause`
+
+```typescript
+interface QueryOrderClause {
+  field: string;
+  dir:   "asc" | "desc";
+}
+```
+
+---
+
+## `VectorSearchOptions`
+
+```typescript
+interface VectorSearchOptions {
+  vector:       readonly number[];
+  topK?:        number;
+  minScore?:    number;
+  vectorField?: string;
+}
+```
+
+Attached to a `QueryFrame.vectorSearch` when the target Memory Node
+advertises `nwp:vector`.
+
+---
+
+## `AsyncActionResponse`
+
+```typescript
+interface AsyncActionResponse {
+  taskId:   string;
+  status:   string;   // "pending" | "running" | …
+  pollUrl?: string;
+}
+
+function asyncActionResponseFromDict(
+  data: Record<string, unknown>,
+): AsyncActionResponse;
+```
+
+Returned by `NwpClient.invoke` when the `ActionFrame` was submitted with
+`async_ === true`.
+
+---
+
+## `QueryFrame` (0x10)
+
+Structured read against a Memory Node.
+
+```typescript
+class QueryFrame {
+  readonly frameType:     FrameType.QUERY;
+  readonly preferredTier: EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly anchorRef?:    string,
+    public readonly filter?:       Record<string, unknown>,
+    public readonly limit?:        number,
+    public readonly offset?:       number,
+    public readonly orderBy?:      readonly QueryOrderClause[],
+    public readonly fields?:       readonly string[],
+    public readonly vectorSearch?: VectorSearchOptions,
+    public readonly depth?:        number,
+  );
+
+  toDict(): Record<string, unknown>;
+  static fromDict(data: Record<string, unknown>): QueryFrame;
+}
+```
+
+Wire form (emitted by `toDict`) uses snake-case keys:
+`anchor_ref`, `order_by`, `vector_search` etc.
+
+---
+
+## `ActionFrame` (0x11)
+
+Operation invocation against an Action / Complex / Gateway Node.
+
+```typescript
+class ActionFrame {
+  readonly frameType:     FrameType.ACTION;
+  readonly preferredTier: EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly actionId:        string,
+    public readonly params?:         Record<string, unknown>,
+    public readonly async_?:         boolean,
+    public readonly idempotencyKey?: string,
+    public readonly timeoutMs?:      number,
+  );
+
+  toDict(): Record<string, unknown>;
+  static fromDict(data: Record<string, unknown>): ActionFrame;
+}
+```
+
+- `actionId` is the identifier declared under the Action Node's
+  `.nwm.json` → `endpoints.actions[].id`.
+- `async_` is serialised as `"async"` on the wire (trailing underscore
+  avoids shadowing the JS keyword).
+- `idempotencyKey` — if present, the node MUST deduplicate within its
+  replay window.
+
+---
+
+## `NwpClient`
+
+Async HTTP client that talks to an NWP node using
+`Content-Type: application/x-nps-frame`.
+
+```typescript
+class NwpClient {
+  constructor(
+    baseUrl: string,
+    options?: {
+      defaultTier?: EncodingTier;   // default: MSGPACK
+      maxPayload?:  number;         // default: 65 535
+      registry?:    FrameRegistry;  // default: NCP + NWP frames
+    },
+  );
+
+  async sendAnchor(frame: AnchorFrame): Promise<void>;
+  async query(frame: QueryFrame): Promise<CapsFrame>;
+  stream(frame: QueryFrame): AsyncGenerator<StreamFrame>;
+  async invoke(frame: ActionFrame): Promise<unknown>;
+}
+```
+
+`baseUrl` trailing slashes are trimmed automatically.
+
+### HTTP routes
+
+| Method | Path | Body | Response |
+|--------|------|------|----------|
+| `sendAnchor` | `POST /anchor` | `AnchorFrame` wire bytes | `204 No Content` |
+| `query`      | `POST /query`  | `QueryFrame` wire bytes | `CapsFrame` wire bytes |
+| `stream`     | `POST /stream` | `QueryFrame` wire bytes | chunked `StreamFrame`s until `is_last=true` |
+| `invoke`     | `POST /invoke` | `ActionFrame` wire bytes | action result |
+
+`invoke()` dispatches by `frame.async_`:
+
+- `false` → decodes response based on content-type. If the server
+  responds with `application/x-nps-frame`, the body is decoded by the
+  codec; otherwise the response is parsed as JSON.
+- `true` → parses JSON and returns `AsyncActionResponse`. Poll
+  `pollUrl` to observe progress.
+
+All methods throw a plain `Error` on non-2xx HTTP status. Stream frames
+are emitted individually — consume the generator with `for await`.
+
+---
+
+## End-to-end example
+
+```typescript
+import {
+  NwpClient, QueryFrame, QueryOrderClause,
+  ActionFrame, AsyncActionResponse,
+  VectorSearchOptions,
+} from "@labacacia/nps-sdk/nwp";
+
+const nwp = new NwpClient("https://products.example.com");
+
+// 1) Upload an anchor once
+await nwp.sendAnchor({
+  frame:     "0x01",
+  anchor_id: "sha256:…",
+  schema:    { fields: [
+    { name: "id",    type: "uint64" },
+    { name: "price", type: "decimal", semantic: "commerce.price.usd" },
+  ]},
+  ttl:       3600,
+});
+
+// 2) Query a page
+const caps = await nwp.query(new QueryFrame(
+  "sha256:…",
+  { price: { $lt: "100.00" } },
+  50,
+  undefined,
+  [{ field: "price", dir: "asc" }],
+));
+console.log(caps.count, "rows, cursor:", caps.next_cursor);
+
+// 3) Stream the full set
+for await (const chunk of nwp.stream(new QueryFrame("sha256:…"))) {
+  for (const row of chunk.data) { /* … */ }
+  if (chunk.isLast) break;
+}
+
+// 4) Fire an async action
+const resp = await nwp.invoke(new ActionFrame(
+  "restock",
+  { sku: "sku-4242", qty: 100 },
+  true,
+));
+// resp is AsyncActionResponse
+```

package/doc/overview.cn.md

@@ -0,0 +1,149 @@
+[English Version](./overview.md) | 中文版
+
+# `@labacacia/nps-sdk` — API 参考总览
+
+[![npm](https://img.shields.io/npm/v/@labacacia/nps-sdk)](https://www.npmjs.com/package/@labacacia/nps-sdk)
+
+NPS TypeScript SDK 是 .NET 参考实现的双格式（ESM + CJS）移植。本文档是
+各模块 API 参考的入口 —— 每个协议有独立文件，见下。
+
+---
+
+## 包结构
+
+```
+@labacacia/nps-sdk
+├── /           # 根：VERSION、createDefaultRegistry、createFullRegistry
+├── /core       # 线缆原语：FrameHeader、编解码、AnchorFrame 缓存、错误
+├── /ncp        # NCP 帧 + 握手 + 流管理
+├── /nwp        # NWP 帧 + 异步 NwpClient
+├── /nip        # NIP 帧 + NipIdentity（Ed25519）
+├── /ndp        # NDP 帧 + InMemoryNdpRegistry + 验证器
+└── /nop        # NOP 帧 + TaskDag 模型 + NopClient
+```
+
+## 参考文档
+
+| 子路径 | 模块 | 参考文档 |
+|--------|------|----------|
+| —                        | 根辅助函数与注册表工厂      | 本文件 |
+| `@labacacia/nps-sdk/core` | 帧头、编解码、AnchorFrame 缓存、异常 | [`nps-sdk.core.cn.md`](./nps-sdk.core.cn.md) |
+| `@labacacia/nps-sdk/ncp`  | NCP 帧集（`AnchorFrame`、`DiffFrame`、`StreamFrame`、`CapsFrame`、`ErrorFrame`、`HelloFrame`） | [`nps-sdk.ncp.cn.md`](./nps-sdk.ncp.cn.md) |
+| `@labacacia/nps-sdk/nwp`  | `QueryFrame`、`ActionFrame`、`NwpClient` | [`nps-sdk.nwp.cn.md`](./nps-sdk.nwp.cn.md) |
+| `@labacacia/nps-sdk/nip`  | `IdentFrame`、`TrustFrame`、`RevokeFrame`、`NipIdentity` | [`nps-sdk.nip.cn.md`](./nps-sdk.nip.cn.md) |
+| `@labacacia/nps-sdk/ndp`  | `AnnounceFrame`、`ResolveFrame`、`GraphFrame`、注册表、验证器 | [`nps-sdk.ndp.cn.md`](./nps-sdk.ndp.cn.md) |
+| `@labacacia/nps-sdk/nop`  | Task DAG、`TaskFrame`、`DelegateFrame`、`SyncFrame`、`AlignStreamFrame`、`NopClient` | [`nps-sdk.nop.cn.md`](./nps-sdk.nop.cn.md) |
+
+---
+
+## 安装
+
+```bash
+npm install @labacacia/nps-sdk
+```
+
+要求 **Node.js 18+**（Web Crypto）或支持原生 `crypto.subtle` 的
+现代浏览器。
+
+---
+
+## 根模块
+
+```typescript
+import { VERSION, createDefaultRegistry, createFullRegistry } from "@labacacia/nps-sdk";
+```
+
+- `VERSION` —— SDK 版本常量。
+- `createDefaultRegistry()` —— 只含 NCP 帧（`ANCHOR`、`DIFF`、`STREAM`、`CAPS`、`ERROR`）的新 `FrameRegistry`。
+- `createFullRegistry()` —— 预注册全部五个协议（NCP + NWP + NIP + NDP + NOP）的新 `FrameRegistry`。
+  解码任意帧时使用这个。
+
+```typescript
+const registry = createFullRegistry();
+```
+
+---
+
+## 最小端到端示例
+
+```typescript
+import { NwpClient, QueryFrame, ActionFrame } from "@labacacia/nps-sdk/nwp";
+
+const client = new NwpClient("http://node.example.com:17433");
+
+// 分页查询
+const caps = await client.query(
+  new QueryFrame("sha256:<anchor-id>", { active: true }, 50),
+);
+console.log(caps.count, caps.data);
+
+// 流式查询
+for await (const chunk of client.stream(new QueryFrame("sha256:<anchor-id>"))) {
+  console.log(chunk.seq, chunk.data);
+  if (chunk.isLast) break;
+}
+
+// Action 调用
+const result = await client.invoke(
+  new ActionFrame("summarise", { maxTokens: 500 }),
+);
+```
+
+---
+
+## 编码分层
+
+每个帧都有 `preferredTier`。MsgPack 是生产默认；JSON Tier
+留给诊断。
+
+| Tier | `EncodingTier` 值 | 说明 |
+|------|---------------------|------|
+| Tier-1 JSON    | `0x00` | UTF-8 JSON。开发与兼容。 |
+| Tier-2 MsgPack | `0x01` | MessagePack 二进制。**生产默认** —— 约小 60%。 |
+
+```typescript
+import { EncodingTier } from "@labacacia/nps-sdk/core";
+import { NpsFrameCodec } from "@labacacia/nps-sdk/core";
+
+const codec = new NpsFrameCodec(createFullRegistry());
+const wire  = codec.encode(frame, { overrideTier: EncodingTier.JSON });
+```
+
+---
+
+## 异步约定
+
+- 所有面向网络的客户端（`NwpClient`、`NopClient`）返回 `Promise<T>`。
+- 流式使用 `AsyncGenerator<StreamFrame>` —— 用
+  `for await (const chunk of …) { … }` 消费。
+- 客户端 **无需** 显式 dispose —— 底层 `fetch` 拥有连接生命周期。
+
+---
+
+## 错误层级
+
+```
+Error
+└── NpsError                       来自 "@labacacia/nps-sdk/core"
+    ├── NpsFrameError              —— 帧头解析 / 结构错误
+    ├── NpsCodecError              —— 编解码失败
+    ├── NpsAnchorNotFoundError     —— AnchorFrame 不在缓存
+    ├── NpsAnchorPoisonError       —— anchor_id / schema 不一致
+    └── NpsStreamError             —— 流序号跳跃 / 未知流 id
+```
+
+`NcpError`（来自 `@labacacia/nps-sdk/core`）是一个独立的协议级错误，
+携带机器可读的 `code`（如 `NCP-ANCHOR-NOT-FOUND`、
+`NCP-STREAM-SEQ-GAP`）。
+
+---
+
+## 参考规范
+
+| 模块 | 规范 |
+|------|------|
+| `core` + `ncp` | [NPS-1 NCP v0.4](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-1-NCP.cn.md) |
+| `nwp`          | [NPS-2 NWP v0.4](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-2-NWP.cn.md) |
+| `nip`          | [NPS-3 NIP v0.2](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-3-NIP.cn.md) |
+| `ndp`          | [NPS-4 NDP v0.2](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-4-NDP.cn.md) |
+| `nop`          | [NPS-5 NOP v0.3](https://github.com/labacacia/NPS-Release/blob/main/spec/NPS-5-NOP.cn.md) |