@1agents/dreammate-network 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# dreammate-network
+
+> DreamMate Network 的 **L0 协议包**：schema + types，零依赖，**不含业务逻辑**。
+> 版本 0.1.0 ｜ 状态：草案
+
+判断改动该不该进这个包，只看一条：
+
+> 它是所有 repo 都要共用的**词汇**，还是某一方的**行为**？
+> 是词汇 → 进来。是行为 → 出去。
+
+## 内容
+
+```
+dreammate-network/
+├── schemas/                    JSON Schema (draft 2020-12)，唯一事实源
+│   ├── node.schema.json
+│   ├── service.schema.json
+│   ├── execution.schema.json
+│   └── session-ref.schema.json
+├── typescript/types.ts         上述 schema 的 TS 投影，纯类型
+├── docs/protocol.md            协议正文
+└── package.json
+```
+
+## 用
+
+```ts
+import type { NodeManifest, Execution, SessionURI } from "dreammate-network";
+```
+
+Go / Swift 侧读同一份 `schemas/*.json`。详见 [`docs/protocol.md` §9](docs/protocol.md)。
+
+## 三条不能破的规则
+
+| 规则 | 破了会怎样 |
+|------|-----------|
+| **Node ≠ Agent** | 无 Agent 的录音硬件就进不了网络 |
+| **Capability ≠ Resource** | 调度侧与检索侧路径缠在一起 |
+| **Execution 不含 `task_id`** | 体外循环（想到了直接干）变成非法状态 |
+
+## 依赖规则
+
+```
+L4 ──→ L3 ──→ L2 / L1 ──→ L0
+
+✅ 任何层都可以 import L0
+❌ L0 不 import 任何人
+```
+
+一条实操检查：**如果 A 需要 `go.mod replace` 或 `file:../` 才能用 B，说明 A 和 B 没解耦。**
+
+## 出处
+
+设计册是 1agents 工作区里的 `docs/architecture/dreammate-network/`（10 篇，不随本包发布）。
+本包对应其中迁移步骤 **S1**（09-仓库拆分与依赖边界 §8）。
+
+下一步是 **S2**（`modules/*` 上移）与 **S3**（session-reader 加 `1session serve` + `/manifest`）——
+S1–S3 就足够跑出 M1 + M2，不需要等全部拆完。

package/dist/typescript/types.d.ts

@@ -0,0 +1,210 @@
+/**
+ * DreamMate Network — L0 协议类型
+ *
+ * 这是所有 repo 共享的「公共语言」，零依赖、不含任何业务逻辑。
+ * 每一个类型都与 ../schemas/*.json 一一对应，改动必须同步两边。
+ *
+ * 依赖规则（强制单向）：任何层都可以 import 本包，本包不 import 任何人。
+ *
+ * @packageDocumentation
+ */
+export declare const PROTOCOL_VERSION = "0.1.0";
+/** `session://<node>/<runtime>/<session_id>` */
+export type SessionURI = `session://${string}/${string}/${string}`;
+/** 资源寻址，如 `recording://tingqi-01/abc`、`speaker://tingqi-001/speaker-23` */
+export type ResourceURI = `${string}://${string}`;
+/**
+ * 点分命名的能力标识，如 `sessions.read`、`reminders.create`、`recordings.list`。
+ *
+ * 第一版刻意就是一个字符串——不带 provider / permission / availability 等元数据。
+ * 那些留到真的要做 capability 调度时再说。
+ */
+export type Capability = string;
+/** Service 拥有的资源类别（声明 scheme，而不是逐条枚举资源）。 */
+export interface ResourceDescriptor {
+    scheme: string;
+    description?: string | null;
+}
+/**
+ * `mcp` / `cli` / `http` 面向 Capability 与 Resource；
+ * `acp` 面向 Agent Runtime 的 Session 控制，与前三者不是一回事。
+ */
+export type Protocol = "mcp" | "http" | "cli" | "acp";
+/**
+ * 同一组能力可以同时有多种 access，调用方不必关心底层是谁。
+ * 包装优先级 MCP > CLI > HTTP，但第一版不做自动 fallback 编排，手工声明即可。
+ */
+export interface AccessDescriptor {
+    protocol: Protocol;
+    /** protocol=http：服务基址，如 `http://scott-mac:7777/v1` */
+    base_url?: string;
+    /** protocol=http：单个 capability 的相对路由，如 `GET /transcripts/:id` */
+    endpoint?: string;
+    /** protocol=mcp：对应的 tool 名 */
+    tool?: string;
+    /** protocol=mcp：MCP server 标识 */
+    server?: string;
+    /** protocol=cli：命令，如 `tingqi transcript get` */
+    command?: string;
+}
+/**
+ * 非 generic 的几种在传输层保留原生协议，不强行塞进
+ * `POST /capabilities/:name/invoke`。
+ */
+export type ServiceKind = "generic" | "agent_runtime" | "session_registry" | "resource_provider" | "mcp";
+/**
+ * Node 上的一组能力聚合。
+ *
+ * 三层结构是 Node → Service → Capability / Resource，
+ * 不要把 Capability 扁平铺到 Node 上。
+ */
+export interface Service {
+    id: string;
+    name?: string | null;
+    /** 省略等同于 `"generic"` */
+    kind?: ServiceKind;
+    /** 可以为空数组（纯 Resource Provider） */
+    capabilities: Capability[];
+    resources?: ResourceDescriptor[];
+    access?: AccessDescriptor[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 节点形态。故意保留 `(string & {})` 开放口——任何硬件都应该能进入同一张网络。
+ */
+export type NodeType = "macos" | "ios" | "linux" | "windows" | "recorder" | "gpu" | (string & {});
+/**
+ * 由节点侧 `GET /manifest` 返回，并通过 `POST /nodes/register` 上报给 Control Plane。
+ *
+ * **Node ≠ Agent。** Node = 一个可以在网络中被发现、声明资源和能力、
+ * 接受读取或操作请求的实体。Agent Runtime 只是它可以承载的一种 Service。
+ */
+export interface NodeManifest {
+    node_id: string;
+    name: string;
+    type: NodeType;
+    /** tailnet 内的寻址名。第一版所有节点通过 Tailscale 统一寻址。 */
+    tailscale_name?: string | null;
+    /** 由 Control Plane 依据 heartbeat 维护；节点自报时可省略。 */
+    online?: boolean;
+    /** 可以为空数组——还没声明任何能力的节点仍然是合法节点。 */
+    services: Service[];
+    metadata?: Record<string, unknown>;
+}
+/** 不是只有 Agent 才产生 Execution。 */
+export type ExecutionType = 
+/** 有 Node / Runtime / Session */
+"agent_execution"
+/** 有 Node / Service / Capability，无 Session */
+ | "capability_invocation"
+/** 设备侧任务 */
+ | "device_job"
+/** 读取远端资源，无 Agent */
+ | "resource_access"
+/** 人在现实中的动作 */
+ | "human_action";
+/**
+ * `waiting_for_user` 是接入手机后必须新增的一类状态：请求用户在现实世界
+ * 做某个动作（确认日程、选联系人、授权 iOS 权限）。有了它，总管才能直接
+ * 回答「3 个任务正在执行，1 个等待你确认」。
+ */
+export type ExecutionStatus = "queued" | "running" | "waiting_for_user" | "completed" | "failed";
+/**
+ * 现实中实际发生的一次工作行为。
+ *
+ * 两条硬规则：
+ *
+ * 1. **这里没有 `task_id`。** Task 关联是独立的 many-to-many link
+ *    （见 {@link TaskExecutionLink}），绝不允许 `executions.task_id NOT NULL`。
+ * 2. **大量字段可空是刻意的**，一个 `capability_invocation` 既没有 session
+ *    也没有 runtime。
+ *
+ * 粒度边界：跨系统 / 跨调度边界才升级为 Execution；Session 内的低层 tool call
+ * （`cat README`、`npm test`）记为 Session Event。否则一个 338 次 tool call 的
+ * Codex Session 会生成 338 个 Execution，Work Graph 立刻失去意义。
+ */
+export interface Execution {
+    id: string;
+    type: ExecutionType;
+    created_at: string;
+    started_at?: string | null;
+    finished_at?: string | null;
+    status: ExecutionStatus;
+    /** status=waiting_for_user 时向用户描述需要他做什么。 */
+    requires_user_action?: string | null;
+    /** 发起方 Session（通常是总管）。写入时产生 Session --initiates--> Execution。 */
+    initiated_by_session_id?: string | null;
+    /** 在哪里执行 */
+    node_id?: string | null;
+    /** 用了该 Node 上的哪个 Service */
+    service_id?: string | null;
+    /** 调用了哪个 Capability */
+    capability?: Capability | null;
+    /** 用什么 Agent harness 执行 */
+    agent_runtime?: string | null;
+    /** 这次推理用谁 */
+    model?: string | null;
+    /** 仅 agent_execution 才有。写入时产生 Execution --opens--> Session。 */
+    session_id?: string | SessionURI | null;
+    /** type=resource_access 时访问的资源。写入时产生 Execution --accesses--> Resource。 */
+    resource_uri?: ResourceURI | null;
+    /** 子 Agent 派生时写入，形成 Execution --delegates--> Execution。 */
+    parent_execution_id?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 所有边由调用事件实时写入（B 调用 `sessions.read(A)` 时就写
+ * `B --references--> A`），不靠后台扫库猜 DAG。
+ *
+ * 注意整体 Work Graph **不是** DAG：Session 之间完全可以成环，
+ * DAG 只是它的某些投影视图（任务分解树、委派树、Agent spawn 树）。
+ */
+export type EdgeRelation = "references" | "opens" | "initiates" | "delegates" | "produces" | "accesses";
+/**
+ * 跨节点引用一个 Session。设备类型不影响 Session Graph——
+ * `session://iphone/yima/abc123` 与 `session://mac/codex/01a0907c`
+ * 是同等级实体，引用关系完全对称。
+ */
+export interface SessionRef {
+    uri: SessionURI;
+    /** 冗余字段，便于消费方免解析。 */
+    node?: string;
+    runtime?: string;
+    session_id?: string;
+    relation?: EdgeRelation;
+    /** 这条边被观察到的时刻。底层只保存事实，不提前做价值判断。 */
+    observed_at?: string | null;
+}
+/**
+ * Task 与 Execution 的关系是 `0..N ←→ 0..N`：
+ *
+ * - Task 可以没有 Execution：计划了还没做
+ * - Execution 可以没有 Task：直接干了没计划（体外循环，一等公民）
+ * - 一个 Task 多个 Execution：Codex 第一轮 → Claude 接力 → Codex review
+ * - 一个 Execution 同时推进多个 Task
+ *
+ * 所以必须是独立关联表，**绝不要**把 task_id 塞进 executions。
+ */
+export interface TaskExecutionLink {
+    task_id: string;
+    execution_id: string;
+    linked_at: string;
+    relation?: string;
+}
+/**
+ * 计划状态**不存字段**，由四个时间事实推导：
+ * `task_created_at` / `execution_started_at` / `execution_finished_at` /
+ * `task_execution_link_created_at`。
+ *
+ * 这里只给分类命名，协议本身不存储它，也不在 L0 实现推导逻辑——
+ * 底层只保存事实，不提前做价值判断。
+ */
+export type PlanningClass = 
+/** 计划后执行：link 在 execution 开始前 */
+"planned"
+/** 执行中纳入：link 在 start 与 finish 之间 */
+ | "in_flight_captured"
+/** 事后归档：link 在 finish 之后 */
+ | "retrospective"
+/** 完全体外：没有任何 task edge */
+ | "out_of_plan";

package/dist/typescript/types.js

@@ -0,0 +1,11 @@
+/**
+ * DreamMate Network — L0 协议类型
+ *
+ * 这是所有 repo 共享的「公共语言」，零依赖、不含任何业务逻辑。
+ * 每一个类型都与 ../schemas/*.json 一一对应，改动必须同步两边。
+ *
+ * 依赖规则（强制单向）：任何层都可以 import 本包，本包不 import 任何人。
+ *
+ * @packageDocumentation
+ */
+export const PROTOCOL_VERSION = "0.1.0";

package/docs/protocol.md

@@ -0,0 +1,221 @@
+# DreamMate Network Protocol v0.1.0
+
+> L0 协议层。**零依赖，不含业务逻辑。**
+> 设计依据：1agents 工作区的 `docs/architecture/dreammate-network/`（10 篇设计册，不随本包发布）
+> 本文件只写「协议是什么」，不写「为什么这么设计」——后者在设计册里。
+
+## 1. 定位
+
+**DreamMate Network 不是 Agent Network，是 Capability Network。**
+
+- **Agent** 负责思考与编排
+- **设备 / 节点** 负责提供能力与数据
+- **Session** 负责留下认知轨迹
+- **Execution** 负责记录现实中到底发生了什么
+- **Task** 负责表达我们原本想做什么（可选，不是执行的前提）
+
+本包是四层架构里的 L0，所有其他层都可以 import 它，它不 import 任何人：
+
+```
+L4  节点宿主  desktop / phone / mini / server
+L3  控制面    control-plane
+L2  服务      session-reader / data-service / tingqi-adapter
+L1  运行时    1acp / HarnessKit / cc-connect / happy-cli
+L0  协议      dreammate-network        ← 本包
+```
+
+## 2. 六个核心对象
+
+第一版只定义这六个，**Task 是可选关联对象，不是执行链的前置条件**：
+
+```
+Node        在哪里执行
+Service     节点上的一组能力聚合
+Capability  能做什么
+Resource    拥有什么
+Execution   某一次具体发生的工作行为
+Session     这一次的工作上下文
+```
+
+关系：
+
+```
+Node
+ ├─ Services
+ │    ├─ Capabilities
+ │    └─ Resources
+ │
+ └─ Agent Runtime?          （Service 的一种特殊 kind）
+       └─ Sessions
+
+Execution
+ ├─ node?
+ ├─ service?
+ ├─ session?
+ └─ task?                   ← 可空，且是独立关联表
+```
+
+三条不能破的规则：
+
+| 规则 | 破了会怎样 |
+|------|-----------|
+| **Node ≠ Agent** | 无 Agent 的录音硬件就进不了网络 |
+| **Capability ≠ Resource** | 调度侧与检索侧路径缠在一起 |
+| **Execution 不含 task_id** | 体外循环（想到了直接干）变成非法状态 |
+
+## 3. 四个 Schema
+
+| 文件 | 对应类型 | 用在哪 |
+|------|----------|--------|
+| [`schemas/node.schema.json`](../schemas/node.schema.json) | `NodeManifest` | `GET /manifest`、`POST /nodes/register` |
+| [`schemas/service.schema.json`](../schemas/service.schema.json) | `Service`、`AccessDescriptor` | 嵌在 Node Manifest 内 |
+| [`schemas/execution.schema.json`](../schemas/execution.schema.json) | `Execution` | `POST /executions`、`PATCH /executions/:id` |
+| [`schemas/session-ref.schema.json`](../schemas/session-ref.schema.json) | `SessionRef` | 跨机 Session 引用与图的边 |
+
+Schema 与 [`typescript/types.ts`](../typescript/types.ts) 一一对应，**改动必须同步两边**。
+
+`TaskExecutionLink` 与 `PlanningClass` 只在 types.ts 里，没有对应 schema——
+前者是 Control Plane 侧的存储关系（不在节点间传输），后者是从时间事实推导出的
+分类命名（协议不存储它，也不在 L0 实现推导）。
+
+## 4. URI 方案
+
+```
+session://<node>/<runtime>/<session_id>
+
+session://mac/codex/01a0907c
+session://iphone/yima/abc123
+```
+
+资源同理：
+
+```
+recording://tingqi-01/abc
+transcript://tingqi-01/abc
+speaker://tingqi-001/speaker-23
+```
+
+`session://iphone/yima/abc123` 与 `session://mac/codex/01a0907c` 是**同等级实体**，
+引用关系完全对称。设备类型不影响 Session Graph。
+
+## 5. 节点侧必须实现的接口
+
+```
+GET   /manifest                      返回 NodeManifest
+GET   /health
+POST  /capabilities/:name/invoke
+```
+
+外加向 Control Plane 的三个动作：`register` / `heartbeat` / `update manifest`。
+
+**不要为了统一而把一切硬塞进 `/invoke`。** 特殊 Service 保留原生协议：
+
+| Service kind | 协议 |
+|--------------|------|
+| `session_registry` | session-reader HTTP（`1session serve`） |
+| `agent_runtime` | ACP |
+| `mcp` | MCP |
+
+Capability Manifest 只负责告诉调用方：**我有什么，以及应该怎么访问。**
+
+## 6. 传输只出现在 `access` 里
+
+数据模型里**不存在** MCP Capability / CLI Capability / HTTP Capability。
+一个 Capability 可以有多种 access，调用方不关心底层是谁：
+
+```json
+{
+  "id": "transcripts",
+  "capabilities": ["transcript.read"],
+  "access": [
+    { "protocol": "mcp",  "tool": "transcript_read" },
+    { "protocol": "http", "endpoint": "GET /transcripts/:id" },
+    { "protocol": "cli",  "command": "tingqi transcript get" }
+  ]
+}
+```
+
+包装优先级 `MCP > CLI > HTTP`，但**第一版不做自动 fallback 编排**，手工声明即可。
+
+`acp` 与前三者不是一回事：MCP/CLI/HTTP 面向 Capability 与 Resource，
+ACP 面向 Agent Runtime 的 Session 控制（`agent.session.new` / `prompt` / `cancel` /
+`status` / `resume`）。
+
+## 7. 图的边由事件实时写入
+
+不跑后台扫库猜 DAG。调用发生时就写边：
+
+| 边 | 何时写 |
+|----|--------|
+| `Session B --references--> Session A` | B 调用 `sessions.read(A)` 时 |
+| `Session O --initiates--> Execution E` | 总管创建执行时 |
+| `Execution E --opens--> Session S` | Agent Session 建立时 |
+| `Execution E1 --delegates--> Execution E2` | 子 Agent 派生时 |
+| `Session A --produces--> Artifact` | 产出时 |
+| `Execution E --accesses--> Resource R` | 访问时 |
+
+整体 Work Graph **不是** DAG（Session 之间可以成环）；DAG 只是它的投影视图。
+
+## 8. Execution 的粒度边界
+
+| 层级 | 记录为 |
+|------|--------|
+| Session 内的低层行为（`cat README`、`grep foo`、`npm test`） | Session Event / Tool Call |
+| 跨系统边界、跨调度边界 | **Execution** |
+
+否则一个 338 次 tool call 的 Codex Session 会生成 338 个 Execution，
+Work Graph 立刻失去意义。
+
+## 9. 怎么消费本包
+
+**TypeScript**（工作区内直接引源码，不引入构建链，从而保持真正零依赖）：
+
+```ts
+import type { NodeManifest, Execution, SessionURI } from "dreammate-network";
+
+const manifest: NodeManifest = {
+  node_id: "iphone_xxx",
+  name: "Scott-iPhone",
+  type: "ios",
+  services: [
+    { id: "reminders", capabilities: ["reminders.read", "reminders.create"] },
+  ],
+};
+```
+
+pnpm workspace 里加 `"dreammate-network": "workspace:*"`；其他情况用
+`file:` / git 依赖。`exports` 的入口指向 `.ts` 源码，由消费方的 bundler
+（vite / esbuild / tsx / webpack）处理；需要独立 JS 产物时再加 build，第一版不加。
+
+**Go / Swift / 其他语言**：读同一份 `schemas/*.json`，手写或代码生成对应结构体。
+schema 是唯一事实源，types.ts 只是它的 TS 投影。
+
+**校验**（任意 JSON Schema draft 2020-12 校验器）：
+
+```bash
+# Node Manifest（-r 带上被 $ref 的 service schema）
+npx -p ajv-cli@5 -p ajv-formats@2 ajv validate --spec=draft2020 -c ajv-formats \
+  -s schemas/node.schema.json -r schemas/service.schema.json -d your-manifest.json
+
+# Execution / SessionRef 用到 format: date-time，必须带 -c ajv-formats，
+# 否则 ajv 会报 unknown format "date-time"。
+npx -p ajv-cli@5 -p ajv-formats@2 ajv validate --spec=draft2020 -c ajv-formats \
+  -s schemas/execution.schema.json -d your-execution.json
+```
+
+每个 schema 自带 `examples`，可以直接抽出来当冒烟用例跑。
+
+## 10. 第一版明确不做
+
+- ❌ 不写任何业务逻辑（本包只是公共语言）
+- ❌ Capability 不带 provider / permission / availability 元数据
+- ❌ 不做自动服务发现（节点手工配 `control_plane`）
+- ❌ 不做 MCP→CLI→HTTP 自动 fallback 编排
+- ❌ 不做 Capability 调度评分
+- ❌ 不要求所有能力统一成 MCP
+- ❌ 不存 `planned = true/false`（由时间事实推导）
+
+## 11. 版本
+
+`PROTOCOL_VERSION = "0.1.0"`。v0.x 期间 schema 可能破坏性变更，
+以设计册 06-实施路线图的 M1–M5 验收结果为准收敛。

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@1agents/dreammate-network",
+  "version": "0.1.0",
+  "description": "DreamMate Network L0 协议包：schema + types，零运行时依赖，不含业务逻辑。",
+  "keywords": [
+    "dreammate",
+    "capability-network",
+    "node-manifest",
+    "json-schema",
+    "protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scottzx/dreammate-network.git"
+  },
+  "type": "module",
+  "main": "./dist/typescript/types.js",
+  "types": "./dist/typescript/types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/typescript/types.d.ts",
+      "import": "./dist/typescript/types.js"
+    },
+    "./schemas/*.json": "./schemas/*.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "docs",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/schemas.test.js",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/schemas/execution.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dreammate.work/schemas/execution.schema.json",
+  "title": "DreamMate Execution",
+  "description": "现实中实际发生的一次工作行为。不是只有 Agent 才产生 Execution。注意两条硬规则：(1) 这里没有 task_id——Task 关联是独立的 many-to-many link，绝不允许 executions.task_id NOT NULL；(2) 大量字段可空是刻意的，一个 capability_invocation 既没有 session 也没有 runtime。粒度边界：跨系统/跨调度边界才升级为 Execution，Session 内的低层 tool call 记为 Session Event，否则一个 338 次 tool call 的 Codex Session 会生成 338 个 Execution，Work Graph 立刻失去意义。",
+  "type": "object",
+  "required": ["id", "type", "created_at", "status"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "type": {
+      "type": "string",
+      "enum": [
+        "agent_execution",
+        "capability_invocation",
+        "device_job",
+        "resource_access",
+        "human_action"
+      ],
+      "description": "agent_execution 有 Node/Runtime/Session；capability_invocation 有 Node/Service/Capability 但无 Session；resource_access 读远端资源；human_action 是人在现实中的动作。"
+    },
+    "created_at": { "type": "string", "format": "date-time" },
+    "started_at": { "type": ["string", "null"], "format": "date-time" },
+    "finished_at": { "type": ["string", "null"], "format": "date-time" },
+    "status": {
+      "type": "string",
+      "enum": ["queued", "running", "waiting_for_user", "completed", "failed"],
+      "description": "waiting_for_user 是手机接入后必须新增的一类状态：请求用户在现实世界做某个动作（确认日程、选联系人、授权 iOS 权限）。有了它，总管才能直接回答『3 个任务正在执行，1 个等待你确认』。"
+    },
+    "requires_user_action": {
+      "type": ["string", "null"],
+      "description": "status=waiting_for_user 时向用户描述需要他做什么。",
+      "examples": ["请选择要添加到日历的地点"]
+    },
+    "initiated_by_session_id": {
+      "type": ["string", "null"],
+      "description": "发起这次执行的 Session（通常是总管 Session）。写入时同时产生一条 Session --initiates--> Execution 的边。"
+    },
+    "node_id": { "type": ["string", "null"], "description": "在哪里执行。" },
+    "service_id": { "type": ["string", "null"], "description": "用了该 Node 上的哪个 Service。" },
+    "capability": { "type": ["string", "null"], "description": "调用了哪个 Capability。" },
+    "agent_runtime": {
+      "type": ["string", "null"],
+      "description": "用什么 Agent harness 执行。与 node / model / session 正交——同一个 runtime 换模型换节点仍是同一个 runtime。",
+      "examples": ["codex", "claude", "yima"]
+    },
+    "model": {
+      "type": ["string", "null"],
+      "description": "这次推理用谁。",
+      "examples": ["deepseek-chat"]
+    },
+    "session_id": {
+      "type": ["string", "null"],
+      "description": "该 Execution 打开的 Session，仅 agent_execution 才有。可以是本地 id 或 session:// URI。写入时产生 Execution --opens--> Session 的边。"
+    },
+    "resource_uri": {
+      "type": ["string", "null"],
+      "description": "type=resource_access 时访问的资源。写入时产生 Execution --accesses--> Resource 的边。",
+      "examples": ["recording://tingqi-01/abc", "transcript://tingqi-01/abc"]
+    },
+    "parent_execution_id": {
+      "type": ["string", "null"],
+      "description": "父执行。子 Agent 派生时写入，形成 Execution --delegates--> Execution 的边。"
+    },
+    "metadata": { "type": "object", "additionalProperties": true }
+  },
+  "examples": [
+    {
+      "id": "E27",
+      "type": "capability_invocation",
+      "created_at": "2026-09-14T10:00:00Z",
+      "status": "completed",
+      "node_id": "iphone_xxx",
+      "service_id": "reminders",
+      "capability": "reminders.create"
+    },
+    {
+      "id": "E28",
+      "type": "resource_access",
+      "created_at": "2026-09-14T10:01:00Z",
+      "status": "completed",
+      "node_id": "recorder_xxx",
+      "service_id": "recordings",
+      "capability": "recordings.list",
+      "resource_uri": "recording://tingqi-01/abc"
+    },
+    {
+      "id": "E29",
+      "type": "agent_execution",
+      "created_at": "2026-09-14T10:02:00Z",
+      "status": "running",
+      "node_id": "node_yyy",
+      "agent_runtime": "codex",
+      "model": "deepseek-chat",
+      "session_id": "session://mac/codex/01a0907c"
+    },
+    {
+      "id": "E5",
+      "type": "capability_invocation",
+      "created_at": "2026-09-14T10:03:00Z",
+      "status": "waiting_for_user",
+      "requires_user_action": "请选择要添加到日历的地点",
+      "node_id": "iphone_xxx",
+      "service_id": "calendar",
+      "capability": "calendar.create"
+    }
+  ]
+}

package/schemas/node.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dreammate.work/schemas/node.schema.json",
+  "title": "DreamMate Node Manifest",
+  "description": "一个 Node 对外声明自己的身份、在线状态与所提供的 Services。Node ≠ Agent：Agent Runtime 只是 Node 可以承载的一种 Service，不是 Node 存在的必要条件。由节点侧 GET /manifest 返回，并通过 POST /nodes/register 上报给 Control Plane。",
+  "type": "object",
+  "required": ["node_id", "name", "type", "services"],
+  "properties": {
+    "node_id": {
+      "type": "string",
+      "description": "网络内全局唯一且稳定的节点标识，重启不变。",
+      "minLength": 1,
+      "examples": ["node_yyy", "iphone_xxx", "recorder_xxx"]
+    },
+    "name": {
+      "type": "string",
+      "description": "人类可读名称。",
+      "minLength": 1,
+      "examples": ["scott-mac", "Scott-iPhone", "听器-01", "dgx-spark"]
+    },
+    "type": {
+      "type": "string",
+      "description": "节点形态。故意不用 enum 封死——任何硬件都应该能进入同一张网络。已知取值：macos / ios / linux / windows / recorder / gpu。",
+      "minLength": 1,
+      "examples": ["macos", "ios", "recorder", "gpu"]
+    },
+    "tailscale_name": {
+      "type": ["string", "null"],
+      "description": "tailnet 内的寻址名。第一版所有节点通过 Tailscale 统一寻址。"
+    },
+    "online": {
+      "type": "boolean",
+      "description": "由 Control Plane 依据 heartbeat 维护；节点自报时可省略。"
+    },
+    "services": {
+      "type": "array",
+      "description": "该节点上的 Service 列表。可以为空数组——一个还没声明任何能力的节点仍然是合法节点。",
+      "items": { "$ref": "service.schema.json" }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "节点级自由扩展字段（如 GPU 显存、架构、固件版本）。协议不解释其内容。",
+      "additionalProperties": true
+    }
+  },
+  "examples": [
+    {
+      "node_id": "node_yyy",
+      "name": "scott-mac",
+      "type": "macos",
+      "tailscale_name": "scott-mac",
+      "online": true,
+      "services": [
+        {
+          "id": "session-registry",
+          "kind": "session_registry",
+          "capabilities": ["sessions.list", "sessions.search", "sessions.read", "sessions.graph"],
+          "access": [{ "protocol": "http", "base_url": "http://scott-mac:7777/v1" }]
+        },
+        { "id": "shell", "capabilities": ["shell.exec"] }
+      ]
+    },
+    {
+      "node_id": "iphone_xxx",
+      "name": "Scott-iPhone",
+      "type": "ios",
+      "services": [
+        { "id": "calendar", "capabilities": ["calendar.read", "calendar.create"] },
+        { "id": "reminders", "capabilities": ["reminders.read", "reminders.create"] }
+      ]
+    },
+    {
+      "node_id": "recorder_xxx",
+      "name": "听器-01",
+      "type": "recorder",
+      "services": [
+        { "id": "recordings", "capabilities": ["recordings.list", "recordings.read"] }
+      ]
+    }
+  ]
+}

package/schemas/service.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dreammate.work/schemas/service.schema.json",
+  "title": "DreamMate Service",
+  "description": "Node 上的一组能力聚合。三层结构是 Node → Service → Capability / Resource，不要把 Capability 扁平铺到 Node 上。Agent Runtime 是 Service 的一种特殊 kind。",
+  "type": "object",
+  "required": ["id", "capabilities"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Service 在所属 Node 内唯一。",
+      "minLength": 1,
+      "examples": ["session-registry", "reminders", "recordings", "agent-runtime"]
+    },
+    "name": {
+      "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"],
+      "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"]]
+    },
+    "resources": {
+      "type": "array",
+      "description": "该 Service 拥有什么（可选，声明资源 URI 的 scheme 而非逐条枚举）。Capability=能做什么，Resource=拥有什么，两者不要混：检索侧走 resource.search/read，调度侧走 capability.invoke。",
+      "items": {
+        "type": "object",
+        "required": ["scheme"],
+        "properties": {
+          "scheme": {
+            "type": "string",
+            "description": "资源 URI 的 scheme。",
+            "examples": ["recording", "transcript", "speaker", "session"]
+          },
+          "description": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "access": {
+      "type": "array",
+      "description": "怎么访问这个 Service。传输方式只出现在这里，绝不进数据模型——不存在所谓 MCP Capability / CLI Capability。同一组能力可以同时有多种 access，调用方不必关心底层是谁。包装优先级 MCP > CLI > HTTP，但第一版不做自动 fallback 编排，手工声明即可。",
+      "items": { "$ref": "#/$defs/access" }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Service 级自由扩展字段。协议不解释其内容。",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "access": {
+      "type": "object",
+      "title": "Access Descriptor",
+      "required": ["protocol"],
+      "properties": {
+        "protocol": {
+          "type": "string",
+          "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"]
+        },
+        "endpoint": {
+          "type": "string",
+          "description": "protocol=http 时单个 capability 的相对路由。",
+          "examples": ["GET /transcripts/:id"]
+        },
+        "tool": {
+          "type": "string",
+          "description": "protocol=mcp 时对应的 tool 名。",
+          "examples": ["transcript_read"]
+        },
+        "server": {
+          "type": "string",
+          "description": "protocol=mcp 时的 MCP server 标识。"
+        },
+        "command": {
+          "type": "string",
+          "description": "protocol=cli 时的命令。",
+          "examples": ["tingqi transcript get", "1session overview"]
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "id": "transcripts",
+      "capabilities": ["transcript.read"],
+      "access": [
+        { "protocol": "mcp", "tool": "transcript_read" },
+        { "protocol": "http", "endpoint": "GET /transcripts/:id" },
+        { "protocol": "cli", "command": "tingqi transcript get" }
+      ]
+    },
+    {
+      "id": "agent-runtime",
+      "kind": "agent_runtime",
+      "capabilities": [
+        "agent.session.new",
+        "agent.session.prompt",
+        "agent.session.cancel",
+        "agent.session.status",
+        "agent.session.resume"
+      ],
+      "access": [{ "protocol": "acp" }]
+    }
+  ]
+}

package/schemas/session-ref.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dreammate.work/schemas/session-ref.schema.json",
+  "title": "DreamMate Session Reference",
+  "description": "跨节点引用一个 Session 的方式：session://<node>/<runtime>/<session_id>。设备类型不影响 Session Graph——session://iphone/yima/abc123 与 session://mac/codex/01a0907c 是同等级实体，引用关系完全对称。",
+  "type": "object",
+  "required": ["uri"],
+  "properties": {
+    "uri": {
+      "type": "string",
+      "pattern": "^session://[^/]+/[^/]+/.+$",
+      "description": "规范形式 session://<node>/<runtime>/<session_id>。",
+      "examples": ["session://mac/codex/01a0907c", "session://iphone/yima/abc123"]
+    },
+    "node": {
+      "type": "string",
+      "description": "URI 第一段，与 node manifest 的 name 或 node_id 对应。冗余字段，便于消费方免解析。"
+    },
+    "runtime": {
+      "type": "string",
+      "description": "URI 第二段。",
+      "examples": ["codex", "claude", "antigravity", "yima"]
+    },
+    "session_id": {
+      "type": "string",
+      "description": "URI 第三段，节点本地的 session id。"
+    },
+    "relation": {
+      "type": "string",
+      "enum": ["references", "opens", "initiates", "delegates", "produces", "accesses"],
+      "description": "这条引用代表哪种边。所有边由调用事件实时写入（B 调用 sessions.read(A) 时就写 B --references--> A），不靠后台扫库猜 DAG。注意整体 Work Graph 不是 DAG：Session 之间完全可以成环，DAG 只是某些投影视图。"
+    },
+    "observed_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "这条边被观察到的时刻。底层只保存事实，不提前做价值判断。"
+    }
+  },
+  "examples": [
+    {
+      "uri": "session://mac/codex/01a0907c",
+      "node": "mac",
+      "runtime": "codex",
+      "session_id": "01a0907c"
+    },
+    {
+      "uri": "session://iphone/yima/abc123",
+      "node": "iphone",
+      "runtime": "yima",
+      "session_id": "abc123",
+      "relation": "references",
+      "observed_at": "2026-09-14T10:05:00Z"
+    }
+  ]
+}