@1agents/dreammate-network 0.1.0 → 0.3.0

package/README.md

@@ -28,7 +28,7 @@ dreammate-network/
 import type { NodeManifest, Execution, SessionURI } from "dreammate-network";
 ```
 
-Go / Swift 侧读同一份 `schemas/*.json`。详见 [`docs/protocol.md` §9](docs/protocol.md)。
+Go / Swift 侧读同一份 `schemas/*.json`。详见 [`docs/protocol.md` §10](docs/protocol.md)。
 
 ## 三条不能破的规则
 

package/dist/typescript/types.d.ts

@@ -8,7 +8,11 @@
  *
  * @packageDocumentation
  */
-export declare const PROTOCOL_VERSION = "0.1.0";
+/**
+ * 协议版本，与本包的 package.json 版本保持一致——两个版本号会让人永远猜不准
+ * 该看哪个。服务在 `manifest.metadata.protocol_version` 里报告它遵循的版本。
+ */
+export declare const PROTOCOL_VERSION = "0.3.0";
 /** `session://<node>/<runtime>/<session_id>` */
 export type SessionURI = `session://${string}/${string}/${string}`;
 /** 资源寻址，如 `recording://tingqi-01/abc`、`speaker://tingqi-001/speaker-23` */
@@ -47,6 +51,35 @@ export interface AccessDescriptor {
     /** protocol=cli：命令，如 `tingqi transcript get` */
     command?: string;
 }
+/**
+ * 约定端口。发现是 pull 的（Control Plane 探测节点的 `/manifest` 与
+ * `/health`），所以「哪个服务在哪个端口」必须是公共词汇，否则探测方无从下手。
+ *
+ * 这是**默认值，不是强制**：服务可以跑在别的端口，代价是探测发现不了它，
+ * 得由它自己 `POST /nodes/register` 告知。
+ *
+ * 与 docs/protocol.md §6 的表格一一对应，改动必须同步两边。
+ */
+export declare const DEFAULT_PORTS: {
+    /**
+     * 本机 node agent（`@1agents/dreammate-node`）。**固定端口**，不可改：
+     * 它是整台机器对网络的唯一入口，外部节点靠"探 36908"找到这台机器上的一切。
+     */
+    readonly "node-agent": 36908;
+    readonly "session-registry": 7777;
+    readonly "data-service": 7778;
+    readonly "control-plane": 7779;
+    readonly "tingqi-adapter": 7780;
+};
+export type WellKnownService = keyof typeof DEFAULT_PORTS;
+/**
+ * 节点身份是从哪来的。
+ *
+ * `tailscale` 表示取自 tailnet（`Self.ID` / `DNSName` / `OS`），此时 `name`
+ * 跨设备唯一。`local` 是回退，`name` **不保证唯一**——iOS 的 hostname 全是
+ * `localhost`——只适合单机自用。放进 `metadata.identity_source` 如实告诉对端。
+ */
+export type IdentitySource = "tailscale" | "local";
 /**
  * 非 generic 的几种在传输层保留原生协议，不强行塞进
  * `POST /capabilities/:name/invoke`。
@@ -58,6 +91,8 @@ export type ServiceKind = "generic" | "agent_runtime" | "session_registry" | "re
  * 三层结构是 Node → Service → Capability / Resource，
  * 不要把 Capability 扁平铺到 Node 上。
  */
+/** 这个 Service 能被谁连上。省略时按 `network` 理解。 */
+export type Reachability = "localhost" | "network";
 export interface Service {
     id: string;
     name?: string | null;
@@ -67,6 +102,15 @@ export interface Service {
     capabilities: Capability[];
     resources?: ResourceDescriptor[];
     access?: AccessDescriptor[];
+    /**
+     * 只监听回环的服务，外部节点发现得了但连不上。node agent 如实转述这个
+     * 声明而**不做代理**——调用方看到 `localhost` 就知道不用白跑一趟。
+     */
+    reachability?: Reachability;
+    /** 实际监听端口。不必等于 {@link DEFAULT_PORTS} 里的默认值。 */
+    port?: number | null;
+    /** 存活探测路径，默认 `/health`。 */
+    health?: string | null;
     metadata?: Record<string, unknown>;
 }
 /**

package/dist/typescript/types.js

@@ -8,4 +8,31 @@
  *
  * @packageDocumentation
  */
-export const PROTOCOL_VERSION = "0.1.0";
+/**
+ * 协议版本，与本包的 package.json 版本保持一致——两个版本号会让人永远猜不准
+ * 该看哪个。服务在 `manifest.metadata.protocol_version` 里报告它遵循的版本。
+ */
+export const PROTOCOL_VERSION = "0.3.0";
+/* ------------------------------------------------------------------ *
+ * 发现
+ * ------------------------------------------------------------------ */
+/**
+ * 约定端口。发现是 pull 的（Control Plane 探测节点的 `/manifest` 与
+ * `/health`），所以「哪个服务在哪个端口」必须是公共词汇，否则探测方无从下手。
+ *
+ * 这是**默认值，不是强制**：服务可以跑在别的端口，代价是探测发现不了它，
+ * 得由它自己 `POST /nodes/register` 告知。
+ *
+ * 与 docs/protocol.md §6 的表格一一对应，改动必须同步两边。
+ */
+export const DEFAULT_PORTS = {
+    /**
+     * 本机 node agent（`@1agents/dreammate-node`）。**固定端口**，不可改：
+     * 它是整台机器对网络的唯一入口，外部节点靠"探 36908"找到这台机器上的一切。
+     */
+    "node-agent": 36908,
+    "session-registry": 7777,
+    "data-service": 7778,
+    "control-plane": 7779,
+    "tingqi-adapter": 7780,
+};

package/docs/protocol.md

@@ -118,7 +118,126 @@ POST  /capabilities/:name/invoke
 
 Capability Manifest 只负责告诉调用方：**我有什么，以及应该怎么访问。**
 
-## 6. 传输只出现在 `access` 里
+## 6. 节点与服务的发现
+
+发现分两层，各有各的事实源：
+
+```
+有哪些节点         ← tailnet（tailscale status --json）
+节点是不是开着     ← tailnet 的 Online
+节点上有什么服务   ← 探测约定端口的 GET /manifest
+服务还活着吗       ← 定期探 GET /health
+```
+
+**方向永远是 L3 → L2（pull），不是 L2 → L3（push）。** 服务不需要知道
+Control Plane 存在，也不需要心跳定时器；Control Plane 挂了，服务毫无感觉。
+这与「上层通过 HTTP 调用下层」的单向依赖一致。
+
+⚠️ **Node 在线 ≠ Service 在线。** tailnet 的 `Online` 只说明机器开着；
+进程被 kill 了它照样报在线。Service 级的存活只能靠探 `/health`。
+
+### 约定端口
+
+pull 要知道探哪儿，所以端口是公共词汇的一部分：
+
+| 端口 | Service | 层 |
+|------|---------|-----|
+| **36908** | **`node-agent`（dreammate-node）** | **本机基础设施** |
+| 7777 | `session-registry`（session-reader） | L2 |
+| 7778 | `data-service` | L2 |
+| 7779 | `control-plane` | L3 |
+| 7780 | `tingqi-adapter` 等 Resource Provider | L2 |
+| 7781–7789 | 预留给后续 L2 服务 | — |
+
+这是**默认值，不是强制**。服务可以跑在别的端口，代价是探测发现不了它，
+得由它自己 `POST /nodes/register` 告知——register 因此是可选的加速/兜底，
+不是必需品。
+
+### 本机 node agent
+
+每台机器跑一个 `@1agents/dreammate-node`，固定监听 **36908**。它是这台机器
+对网络的唯一入口：
+
+```
+        Control Plane / 任意节点
+                  │  探 36908（每台机器只探一个端口）
+                  ▼
+        node-agent :36908
+         ├─ GET  /manifest      本机聚合视图：节点身份 + 所有已报备的服务
+         ├─ GET  /health
+         ├─ GET  /services      各服务的存活与可达性
+         └─ POST /services      服务报备（**仅接受 localhost**）
+                  ▲
+      ┌───────────┴───────────┐  localhost 报备
+ session-reader :7777    task-service :xxxx
+```
+
+这把 pull 探测的成本从「N 个节点 × M 个端口」降到「N × 1」。
+
+**报备是可选的。** 服务不报备也能工作，只是外部得靠约定端口才找得到它。
+报备时必须声明**可达性**：
+
+| `reachability` | 含义 |
+|---|---|
+| `localhost` | 只监听回环，外部节点发现得了但连不上 |
+| `network` | 监听 0.0.0.0 或 tailnet 地址，外部可直连 |
+
+agent 如实转述这个声明，**不做代理**。调用方看到 `localhost` 就知道这个能力
+只对本机开放，不用白跑一趟。
+
+> ⚠️ `POST /services` 只接受来自回环的请求。否则网络上任何人都能往你的节点
+> 里塞一个假服务，把调用方引到别处去。
+
+### Control Plane 不是一个进程
+
+node 注册与探活下沉成了每台机器的基础设施（就是上面的 agent），原本设想中
+Control Plane 的其余职责——Task、Agent 编排、Execution 账本——**降级为平级的
+普通服务**，各自独立起进程、各自向本机 agent 报备。
+
+```
+以前：Control Plane = Node Registry + Execution Ledger + Task + Orchestrator
+                      （一个大进程）
+
+现在：node-agent      = Node Registry + 探活        （每机一个，基础设施）
+      task-service    ┐
+      agent-service   ├ 平级服务，各自解耦运行，都向本机 agent 报备
+      execution-*     ┘
+```
+
+好处是任何一个服务挂掉都不会让整个控制面消失，也不存在"必须先起 Control Plane
+才能用"的启动顺序。代价是全网视图需要有人聚合——那也只是另一个服务，它靠
+tailnet + 探 36908 自己拼出来。
+
+### 节点身份取自 tailnet
+
+节点的 `node_id` / `name` / `type` 应该直接用 tailnet 的事实，而不是自己生成：
+
+| Manifest 字段 | tailscale status 的来源 |
+|---|---|
+| `node_id` | `Self.ID`（稳定，重启不变） |
+| `name` | `Self.DNSName` 的第一段 |
+| `type` | `Self.OS`（macOS→macos，iOS→ios，…） |
+| `tailscale_name` | `Self.DNSName` |
+
+> ⚠️ **不要用 `HostName`。** iOS 设备的 HostName 全是 `localhost`——实测一个
+> 11 节点的 tailnet 里只有 9 个 HostName 唯一，而 DNSName 是 11/11 唯一且可读
+> （`iphone-15-pro`）。用 HostName 做 `session://<node>/...` 的第一段，几台
+> 手机接进来就会全部撞在 `session://localhost/...`。
+
+本机所有服务读同一份 tailnet 状态，所以不会各自生成 id 把一台机器裂成几个 Node。
+拿不到 tailscale 时可以回退到本地身份，但要在 `metadata.identity_source` 里
+如实标明，因为回退身份的 `name` 不保证跨设备唯一。
+
+### `/manifest` 永远是部分视图
+
+一个节点上跑着多个服务时，每个服务的 `/manifest` 只报**自己**那一个 service，
+但 `node_id` 是相同的。完整的节点视图（把同一 `node_id` 下的 services 合并）
+只存在于 Control Plane 的 `GET /nodes/:id/manifest`。
+
+消费方看到两份 `node_id` 相同、`services` 不同的 manifest 是**正常的**，
+不是冲突。
+
+## 7. 传输只出现在 `access` 里
 
 数据模型里**不存在** MCP Capability / CLI Capability / HTTP Capability。
 一个 Capability 可以有多种 access，调用方不关心底层是谁：
@@ -141,7 +260,7 @@ Capability Manifest 只负责告诉调用方：**我有什么，以及应该怎
 ACP 面向 Agent Runtime 的 Session 控制（`agent.session.new` / `prompt` / `cancel` /
 `status` / `resume`）。
 
-## 7. 图的边由事件实时写入
+## 8. 图的边由事件实时写入
 
 不跑后台扫库猜 DAG。调用发生时就写边：
 
@@ -156,7 +275,7 @@ ACP 面向 Agent Runtime 的 Session 控制（`agent.session.new` / `prompt` / `
 
 整体 Work Graph **不是** DAG（Session 之间可以成环）；DAG 只是它的投影视图。
 
-## 8. Execution 的粒度边界
+## 9. Execution 的粒度边界
 
 | 层级 | 记录为 |
 |------|--------|
@@ -166,7 +285,7 @@ ACP 面向 Agent Runtime 的 Session 控制（`agent.session.new` / `prompt` / `
 否则一个 338 次 tool call 的 Codex Session 会生成 338 个 Execution，
 Work Graph 立刻失去意义。
 
-## 9. 怎么消费本包
+## 10. 怎么消费本包
 
 **TypeScript**（工作区内直接引源码，不引入构建链，从而保持真正零依赖）：
 
@@ -205,7 +324,7 @@ npx -p ajv-cli@5 -p ajv-formats@2 ajv validate --spec=draft2020 -c ajv-formats \
 
 每个 schema 自带 `examples`，可以直接抽出来当冒烟用例跑。
 
-## 10. 第一版明确不做
+## 11. 第一版明确不做
 
 - ❌ 不写任何业务逻辑（本包只是公共语言）
 - ❌ Capability 不带 provider / permission / availability 元数据
@@ -215,7 +334,7 @@ npx -p ajv-cli@5 -p ajv-formats@2 ajv validate --spec=draft2020 -c ajv-formats \
 - ❌ 不要求所有能力统一成 MCP
 - ❌ 不存 `planned = true/false`（由时间事实推导）
 
-## 11. 版本
+## 12. 版本
 
 `PROTOCOL_VERSION = "0.1.0"`。v0.x 期间 schema 可能破坏性变更，
 以设计册 06-实施路线图的 M1–M5 验收结果为准收敛。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agents/dreammate-network",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "DreamMate Network L0 协议包：schema + types，零运行时依赖，不含业务逻辑。",
   "keywords": [
     "dreammate",

package/schemas/service.schema.json

@@ -4,82 +4,165 @@
   "title": "DreamMate Service",
   "description": "Node 上的一组能力聚合。三层结构是 Node → Service → Capability / Resource，不要把 Capability 扁平铺到 Node 上。Agent Runtime 是 Service 的一种特殊 kind。",
   "type": "object",
-  "required": ["id", "capabilities"],
+  "required": [
+    "id",
+    "capabilities"
+  ],
   "properties": {
     "id": {
       "type": "string",
       "description": "Service 在所属 Node 内唯一。",
       "minLength": 1,
-      "examples": ["session-registry", "reminders", "recordings", "agent-runtime"]
+      "examples": [
+        "session-registry",
+        "reminders",
+        "recordings",
+        "agent-runtime"
+      ]
     },
     "name": {
-      "type": ["string", "null"],
+      "type": [
+        "string",
+        "null"
+      ],
       "description": "人类可读名称，可省略。"
     },
     "kind": {
       "type": "string",
       "description": "Service 类型。generic 之外的几种在传输层保留原生协议（见 protocol.md §5），不强行塞进 /capabilities/:name/invoke。",
-      "enum": ["generic", "agent_runtime", "session_registry", "resource_provider", "mcp"],
+      "enum": [
+        "generic",
+        "agent_runtime",
+        "session_registry",
+        "resource_provider",
+        "mcp"
+      ],
       "default": "generic"
     },
     "capabilities": {
       "type": "array",
       "description": "该 Service 能做什么。第一版就是点分命名的字符串，不带权限/可用性等元数据。可以为空数组（纯 Resource Provider）。",
-      "items": { "type": "string", "minLength": 1 },
-      "examples": [["sessions.list", "sessions.read"], ["reminders.create"], ["recordings.list", "recording.read"]]
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "examples": [
+        [
+          "sessions.list",
+          "sessions.read"
+        ],
+        [
+          "reminders.create"
+        ],
+        [
+          "recordings.list",
+          "recording.read"
+        ]
+      ]
     },
     "resources": {
       "type": "array",
       "description": "该 Service 拥有什么（可选，声明资源 URI 的 scheme 而非逐条枚举）。Capability=能做什么，Resource=拥有什么，两者不要混：检索侧走 resource.search/read，调度侧走 capability.invoke。",
       "items": {
         "type": "object",
-        "required": ["scheme"],
+        "required": [
+          "scheme"
+        ],
         "properties": {
           "scheme": {
             "type": "string",
             "description": "资源 URI 的 scheme。",
-            "examples": ["recording", "transcript", "speaker", "session"]
+            "examples": [
+              "recording",
+              "transcript",
+              "speaker",
+              "session"
+            ]
           },
-          "description": { "type": ["string", "null"] }
+          "description": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
         }
       }
     },
     "access": {
       "type": "array",
       "description": "怎么访问这个 Service。传输方式只出现在这里，绝不进数据模型——不存在所谓 MCP Capability / CLI Capability。同一组能力可以同时有多种 access，调用方不必关心底层是谁。包装优先级 MCP > CLI > HTTP，但第一版不做自动 fallback 编排，手工声明即可。",
-      "items": { "$ref": "#/$defs/access" }
+      "items": {
+        "$ref": "#/$defs/access"
+      }
     },
     "metadata": {
       "type": "object",
       "description": "Service 级自由扩展字段。协议不解释其内容。",
       "additionalProperties": true
+    },
+    "reachability": {
+      "type": "string",
+      "enum": [
+        "localhost",
+        "network"
+      ],
+      "description": "这个 Service 能被谁连上。localhost=只监听回环，外部节点发现得了但连不上；network=监听 0.0.0.0 或 tailnet 地址，外部可直连。node agent 如实转述服务自己的声明，不做代理——调用方看到 localhost 就知道不用白跑一趟。省略时按 network 理解。"
+    },
+    "port": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "minimum": 1,
+      "maximum": 65535,
+      "description": "服务实际监听的端口。向本机 node agent 报备时带上，外部才知道该连哪儿；它不必等于 DEFAULT_PORTS 里的默认值。"
+    },
+    "health": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "存活探测路径，默认 /health。node agent 定期探它来判断服务死活——注意 Node 在线不代表 Service 在线。"
     }
   },
   "$defs": {
     "access": {
       "type": "object",
       "title": "Access Descriptor",
-      "required": ["protocol"],
+      "required": [
+        "protocol"
+      ],
       "properties": {
         "protocol": {
           "type": "string",
-          "enum": ["mcp", "http", "cli", "acp"],
+          "enum": [
+            "mcp",
+            "http",
+            "cli",
+            "acp"
+          ],
           "description": "acp 只用于 kind=agent_runtime 的 Session 控制，与前三者不是一回事：MCP/CLI/HTTP 面向 Capability / Resource，ACP 面向 Agent Runtime / Session Control。"
         },
         "base_url": {
           "type": "string",
           "description": "protocol=http 时的服务基址。",
-          "examples": ["http://scott-mac:7777/v1"]
+          "examples": [
+            "http://scott-mac:7777/v1"
+          ]
         },
         "endpoint": {
           "type": "string",
           "description": "protocol=http 时单个 capability 的相对路由。",
-          "examples": ["GET /transcripts/:id"]
+          "examples": [
+            "GET /transcripts/:id"
+          ]
         },
         "tool": {
           "type": "string",
           "description": "protocol=mcp 时对应的 tool 名。",
-          "examples": ["transcript_read"]
+          "examples": [
+            "transcript_read"
+          ]
         },
         "server": {
           "type": "string",
@@ -88,7 +171,10 @@
         "command": {
           "type": "string",
           "description": "protocol=cli 时的命令。",
-          "examples": ["tingqi transcript get", "1session overview"]
+          "examples": [
+            "tingqi transcript get",
+            "1session overview"
+          ]
         }
       }
     }
@@ -96,11 +182,22 @@
   "examples": [
     {
       "id": "transcripts",
-      "capabilities": ["transcript.read"],
+      "capabilities": [
+        "transcript.read"
+      ],
       "access": [
-        { "protocol": "mcp", "tool": "transcript_read" },
-        { "protocol": "http", "endpoint": "GET /transcripts/:id" },
-        { "protocol": "cli", "command": "tingqi transcript get" }
+        {
+          "protocol": "mcp",
+          "tool": "transcript_read"
+        },
+        {
+          "protocol": "http",
+          "endpoint": "GET /transcripts/:id"
+        },
+        {
+          "protocol": "cli",
+          "command": "tingqi transcript get"
+        }
       ]
     },
     {
@@ -113,7 +210,11 @@
         "agent.session.status",
         "agent.session.resume"
       ],
-      "access": [{ "protocol": "acp" }]
+      "access": [
+        {
+          "protocol": "acp"
+        }
+      ]
     }
   ]
 }