# BrainOS 外部设备接入协议

本文档说明设备、小程序、网站、家庭终端如何把授权数据接入 BrainOS 主脑学习队列，并读取低敏中枢简报。

## 目标

- 每个外部来源先在主脑「认知 -> 同步 -> 外部接入源」创建接入源。
- 平台只展示一次接入密钥，后端只保存密钥哈希。
- 外部来源用密钥调用设备接入接口，上报可学习事件。
- 事件会按来源记录，并在用户授权后进入个人记忆/人格画像的学习流程。
- 外部设备也可用同一密钥读取中枢简报，用于决定陪伴模式、目标人格成熟度和低风险交互策略。
- 设备执行陪伴后，可以回传一次陪伴会话结果，形成“读取策略 -> 现场互动 -> 回写学习 -> 自动巩固”的闭环。
- 主脑可以向设备下发任务，设备领取、执行并回传结果，形成“主脑主动调度 -> 设备执行 -> 结果学习”的万户互联基础能力。
- 主脑可根据中枢成熟度、学习缺口、待确认事件和设备类型自动编排低风险任务，让家庭终端、网站、小程序、健康设备持续补齐人格画像。
- 主脑可执行自动成长巡检，把中枢状态、人格缺口、设备拓扑、任务队列和巩固阈值合成下一步行动计划。
- 设备可读取 `executionGuard` 执行守护协议，在自动循环前判断推荐端点、派发/阻塞、风险等级和隐私边界，避免盲目执行。

## 接入端点

```http
POST https://n.hhtc.top/api/brain/ingest/device
Content-Type: application/json
X-BrainOS-Ingest-Key: bos_ing_xxx
```

也支持把密钥放在 `Authorization: Bearer bos_ing_xxx`，但推荐使用 `X-BrainOS-Ingest-Key`。

## 设备中枢简报端点

```http
GET https://n.hhtc.top/api/brain/device/briefing
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点用于家庭终端、智能音箱、机器人、摄像头、小程序等设备读取“低敏摘要”，让设备知道当前主脑的成熟度、陪伴模式、数字人数量和自动巩固状态。

简报会同时返回设备端自运转飞轮：

- `selfRunningFlywheel.protocolVersion = brainos.device_self_running_flywheel.v1`
- `flywheelActionPackage.protocolVersion = brainos.device_flywheel_action.v1`
- `selfRunningFlywheel.stages[]`：万户接入、可信摘要审计、人格学习账本、自动进化守护、设备协作派发的阶段状态。
- `flywheelActionPackage.recommendedEndpoint`：设备下一步优先调用的端点，通常是 `/api/brain/device/collaboration-cycle`、`/api/brain/device/tasks/pull` 或 `/api/brain/device/briefing`。
- `flywheelActionPackage.deviceShould`：设备是否应保持心跳、拉任务、回传授权摘要、提示主人确认记忆、运行协作循环。
- 安全边界：设备端飞轮只返回阶段、计数、状态、端点和下一步；不返回原始照片、音频、视频、完整聊天全文或完整私密记忆。

成功返回示例：

```json
{
  "success": true,
  "central": {
    "readinessScore": 42,
    "mode": "learning",
    "companionMode": "learning_companion"
  },
  "persona": {
    "personId": "self",
    "maturityScore": 38,
    "confidence": 0.62
  },
  "digitalHumans": {
    "total": 2,
    "living": 1,
    "deceased": 1,
    "confirmedMemories": 12
  },
  "devicePolicy": {
    "contentScope": "summary_only",
    "privacyBoundary": "不返回完整私密记忆、原始音视频或敏感资料；设备只获得陪伴策略和成熟度摘要。"
  },
  "selfRunningFlywheel": {
    "protocolVersion": "brainos.device_self_running_flywheel.v1",
    "status": "watching_network",
    "canTurnNow": false,
    "nextAction": "保持低频心跳；如用户现场授权，可回传一条低敏摘要帮助飞轮转动。"
  },
  "flywheelActionPackage": {
    "protocolVersion": "brainos.device_flywheel_action.v1",
    "recommendedEndpoint": "/api/brain/device/collaboration-cycle",
    "deviceShould": {
      "heartbeat": true,
      "pullTasks": false,
      "submitAuthorizedSummary": true,
      "uploadRawMedia": false
    }
  },
  "recognitionStrategy": {
    "mode": "device_local_asr_first",
    "preferredInput": "device_or_browser_asr",
    "fallbackOrder": ["device_builtin_asr", "browser_speech_recognition", "typed_summary", "status_gated_sensevoice"],
    "senseVoice": {
      "statusEndpoint": "/api/asr/status",
      "useOnlyWhenStatusReady": true,
      "unavailableFallback": "device_or_browser_asr_then_text_summary"
    },
    "postSessionRule": {
      "endpoint": "/api/brain/device/session",
      "summaryOnly": true,
      "rawAudioUpload": false,
      "consentRequired": true
    }
  }
}
```

设备、小程序、网站后端和医院终端可以先读取一个只读行动包。这个端点不会写入数据，只告诉节点下一步该心跳、拉任务、回传授权摘要、运行安全协作循环，还是提示主人先确认记忆。

```http
GET https://n.hhtc.top/api/brain/device/flywheel-action
X-BrainOS-Ingest-Key: bos_ing_xxx
```

返回协议为 `brainos.device_flywheel_action_status.v1`，核心字段：

```json
{
  "success": true,
  "protocolVersion": "brainos.device_flywheel_action_status.v1",
  "status": "watching_network",
  "actionType": "heartbeat_and_collect_authorized_summary",
  "canTurnNow": false,
  "recommendedNextCall": {
    "endpoint": "/api/brain/device/collaboration-cycle",
    "method": "POST",
    "afterMs": 120000
  },
  "deviceShould": {
    "heartbeat": true,
    "pullTasks": false,
    "submitAuthorizedSummary": true,
    "promptOwnerReview": false,
    "runCollaborationCycle": true,
    "uploadRawMedia": false
  },
  "summaryTemplate": {
    "endpoint": "/api/brain/device/collaboration-cycle",
    "fields": {
      "personaGapSummary": "可选：现场互动后形成的一句授权低敏摘要",
      "taskResults": "可选：设备真实执行任务后的 resultSummary",
      "consent": "granted|pending|denied",
      "confidence": "0.5-1.0"
    }
  },
  "policy": {
    "contentScope": "device_summary_only",
    "readOnly": true,
    "rawMediaIncluded": false,
    "privateMemoryIncluded": false,
    "chatTranscriptIncluded": false
  }
}
```

前端/小程序/网页设备 SDK 可直接读取飞轮行动包：

```js
const action = await window.__brainExternalIngest.fetchDeviceFlywheelAction(ingestKey);
if (action.deviceShould?.promptOwnerReview) {
  // 展示给主人确认，不自动越过审计。
}
if (action.deviceShould?.pullTasks) {
  await window.__brainExternalIngest.pullDeviceTasks(ingestKey);
}

const flywheel = await window.__brainExternalIngest.fetchDeviceSelfRunningFlywheel(ingestKey);
if (flywheel.flywheelActionPackage?.deviceShould?.pullTasks) {
  await window.__brainExternalIngest.pullDeviceTasks(ingestKey);
}
```

也可以直接调用一键飞轮循环，让家庭终端、小程序、网站或医院终端按飞轮行动包自动选择下一步：

```js
const cycle = await window.__brainExternalIngest.runDeviceSelfRunningFlywheelCycle(
  ingestKey,
  { personId: 'self' },
  {
    authorizedSummaryBuilder: async (action, flywheel) => ({
      eventType: 'observation',
      personId: 'self',
      title: '设备飞轮授权摘要',
      content: `用户现场授权摘要：${action.instruction || flywheel.selfRunningFlywheel?.nextAction || '继续低敏陪伴学习。'}`,
      confidence: 0.86,
      consent: 'granted',
      payload: {
        summaryOnly: true,
        contentScope: 'summary_only',
        privacyBoundary: 'summary_only_no_raw_media',
        rawMediaIncluded: false
      }
    })
  }
);

if (cycle.skipped.includes('authorized_summary_required')) {
  // 设备必须先让用户确认一条真实低敏摘要，不能由设备或服务端编造内容。
}
```

如果希望终端自动调度下一轮，但仍保持有界和低敏，可以使用调度器：

```js
const run = await window.__brainExternalIngest.runDeviceAutonomousFlywheelScheduler(ingestKey, {
  runNow: true,
  autoScheduleNext: true,
  maxAutoCycles: 3,
  authorizedSummaryBuilder: async (action) => ({
    eventType: 'observation',
    personId: 'self',
    title: '设备飞轮授权摘要',
    content: `用户现场确认的低敏摘要：${action.instruction}`,
    confidence: 0.86,
    consent: 'granted',
    payload: {
      summaryOnly: true,
      contentScope: 'summary_only',
      privacyBoundary: 'summary_only_no_raw_media',
      rawMediaIncluded: false
    }
  })
});

const schedule = window.__brainExternalIngest.scheduleDeviceSelfRunningFlywheelCycle(ingestKey, action, {
  maxAutoCycles: 3,
  authorizedSummaryBuilder: async () => ({
    eventType: 'observation',
    personId: 'self',
    title: '下一轮授权摘要',
    content: '真实用户授权的低敏摘要。',
    consent: 'granted',
    confidence: 0.86,
    payload: { summaryOnly: true, privacyBoundary: 'summary_only_no_raw_media', rawMediaIncluded: false }
  })
});
```

自动调度器的硬边界：

- 先调用 `fetchDeviceFlywheelAction(ingestKey)`，再解析 `brainos.device_flywheel_action_status.v1`。
- `owner_review_required`、`authorized_summary_required`、`raw_media_policy_not_safe`、`raw_media_forbidden` 时必须暂停。
- `authorizedSummaryBuilder` 必须来自用户现场授权、设备真实执行结果或已有低敏摘要，不能由设备或服务端编造。
- `scheduleDeviceSelfRunningFlywheelCycle(ingestKey, ...)` 只能做有界调度，建议 `maxAutoCycles<=3`，每轮继续遵守 `summary_only_no_raw_media`。

`runDeviceSelfRunningFlywheelCycle(ingestKey, params, options)` 的固定边界：

- 先读取 `fetchDeviceSelfRunningFlywheel()`，再用 `resolveDeviceFlywheelAction()` 解析 `deviceShould`。
- 可自动执行心跳、领取低风险任务、运行守护协作循环、刷新飞轮。
- 只有 `authorizedSummary`、`summary` 或 `authorizedSummaryBuilder` 提供真实授权摘要时，才会调用 `/api/brain/device/ingest/sync` 回传学习证据；缺少摘要时返回 `authorized_summary_required` 并暂停。
- 检测到照片、音频、视频、base64、blob、媒体 URL 或 `rawMedia` 字段时返回 `raw_media_forbidden`。
- `promptOwnerReview=true` 或账本存在待确认时会返回 `owner_review_required`，默认暂停，不能绕过主人审计。
- 固定输出 `contentScope=device_summary_only`、`privacyBoundary=summary_only_no_raw_media`、`rawMediaIncluded=false`，不返回完整私密记忆、聊天全文或原始媒体。

低能力硬件、医院终端、小程序后端或网站后端如果不方便加载前端 SDK，可以直接调用后端一键飞轮端点：

```http
POST https://n.hhtc.top/api/brain/device/self-running-flywheel-cycle
X-BrainOS-Ingest-Key: bos_ing_xxx
Content-Type: application/json

{
  "authorizedSummary": {
    "eventType": "observation",
    "personId": "self",
    "title": "设备飞轮授权摘要",
    "content": "用户现场确认的低敏陪伴摘要，只写总结，不上传原始照片、音频、视频。",
    "confidence": 0.86,
    "consent": "granted",
    "payload": {
      "summaryOnly": true,
      "privacyBoundary": "summary_only_no_raw_media",
      "rawMediaIncluded": false
    }
  },
  "runCollaborationCycle": true
}
```

返回协议为 `brainos.device_self_running_flywheel_cycle.v1`，会包含 `selfRunningFlywheel`、`flywheelActionPackage`、`heartbeat`、`tasks`、`summarySync`、`collaborationCycle`、`nextCycle` 和 `executionPackage`。没有 `authorizedSummary` 时返回 `authorized_summary_required` 并暂停；出现原始媒体字段或媒体 URL 时返回 `raw_media_forbidden`；账本存在待确认时默认返回 `owner_review_required`，外部节点不能绕过主人确认。

## 设备启动清单端点

设备、小程序或网站拿到 `X-BrainOS-Ingest-Key` 后，建议第一步读取启动清单。这个端点会一次返回端点地图、心跳节奏、任务拉取规则、学习回执字段、语音识别策略、TTS/头像策略和自检项。
同时会嵌入 `dispatchPlan`，低能力硬件、小程序后端和医院终端不用额外串接口，也能知道下一步是保持心跳、领取任务、补人格摘要还是等待用户确认。

```http
GET https://n.hhtc.top/api/brain/device/bootstrap
X-BrainOS-Ingest-Key: bos_ing_xxx
```

返回示例：

```json
{
  "success": true,
  "bootstrapManifest": {
    "version": 1,
    "endpoints": {
      "selfTest": "/api/brain/device/self-test",
      "selfTestRemediate": "/api/brain/device/self-test/remediate",
      "fleetHealth": "/api/brain/device/fleet/health",
      "networkDispatchPlan": "/api/brain/device/network/dispatch-plan",
      "networkExpansionPlan": "/api/brain/device/network/expansion-plan",
      "pilotReadiness": "/api/brain/device/pilot-readiness",
      "heartbeat": "/api/brain/device/heartbeat",
      "collaborationCycle": "/api/brain/device/collaboration-cycle",
      "briefing": "/api/brain/device/briefing",
      "batchSync": "/api/brain/device/ingest/sync",
      "personaAuthorizationPassport": "/api/brain/device/persona-authorization-passport",
      "personaAutopilot": "/api/brain/device/persona-evolution-command-center?personId=self",
      "personaLearningPackage": "/api/brain/device/persona-learning-package",
      "personaLearningLedger": "/api/brain/device/persona-learning-ledger",
      "personaTwinStatus": "/api/brain/device/persona-twin-status",
      "taskPull": "/api/brain/device/tasks/pull",
      "taskResult": "/api/brain/device/tasks/{taskId}/result",
      "session": "/api/brain/device/session",
      "companionReply": "/api/brain/device/companion-reply",
      "asrStatus": "/api/asr/status"
    },
    "cadence": {
      "heartbeatSec": 30,
      "briefingRefreshSec": 120,
      "learningFeedbackRefreshSec": 300
    },
    "startupSequence": [
      "GET /api/brain/device/bootstrap",
      "POST /api/brain/device/collaboration-cycle（低能力设备可选：一键完成心跳、拉任务、摘要回传和刷新简报）",
      "POST /api/brain/device/heartbeat",
      "GET /api/brain/device/self-test",
      "POST /api/brain/device/self-test/remediate（当自检存在 warn/fail 时）",
      "GET /api/brain/device/network/dispatch-plan",
      "GET /api/brain/device/network/expansion-plan",
      "GET /api/brain/device/pilot-readiness",
      "GET /api/brain/device/persona-authorization-passport",
      "GET /api/brain/device/persona-evolution-command-center?personId=self",
      "GET /api/brain/device/persona-learning-package?personId=self",
      "GET /api/brain/device/persona-learning-ledger?personId=self",
      "GET /api/brain/device/persona-twin-status",
      "GET /api/brain/device/briefing",
      "POST /api/brain/device/ingest/sync（批量回传摘要事件）",
      "GET /api/brain/device/tasks/pull?limit=5",
      "POST /api/brain/device/tasks/{taskId}/result"
    ],
    "selfTest": {
      "requiredChecks": [
        "ingest_key_valid",
        "heartbeat_accepted",
        "self_test_readable",
        "network_dispatch_plan_readable",
        "pilot_readiness_readable",
        "persona_authorization_passport_readable",
        "persona_learning_package_readable",
        "persona_twin_status_readable",
        "briefing_readable",
        "recognition_strategy_loaded",
        "collaboration_cycle_available",
        "task_pull_available",
        "session_summary_postable"
      ]
    },
    "learningContract": {
      "collaborationCycleEndpoint": "/api/brain/device/collaboration-cycle",
      "receiptField": "learningReceipt",
      "summaryOnly": true,
      "consentRequired": true,
      "rawMediaPolicy": "explicit_user_upload_only",
      "serverDoesNotInventTaskResults": true,
      "taskResultRequiresSummary": true
    }
  }
}
```

设备端最小接入顺序：

1. 调用 `/api/brain/device/bootstrap` 读取启动清单。
2. 低能力硬件、医院终端、小程序后端可优先调用 `/api/brain/device/collaboration-cycle`，用一个请求完成心跳、任务领取、任务摘要回传、人格缺口摘要回传、学习反馈和简报刷新。
3. 标准设备按 `cadence.heartbeatSec` 定时调用 `/api/brain/device/heartbeat`。
4. 调用 `/api/brain/device/self-test` 做接入自检，按 `checks[].nextAction` 修复缺口。
5. 如果自检存在 `warn` 或 `fail`，调用 `/api/brain/device/self-test/remediate` 生成低风险修复任务。
6. 调用 `/api/brain/device/fleet/health` 读取设备群健康，判断是否有离线、自检修复或待确认学习。
7. 心跳返回 `taskSignal.shouldPull=true` 时调用 `/api/brain/device/tasks/pull`。
8. 执行任务后调用 `/api/brain/device/tasks/{taskId}/result`，并优先读取 `learningReceipt`。
9. 围绕自己、在世人物或逝者工作前，先调用 `/api/brain/device/persona-bootstrap-blueprint?personId=xxx` 读取电子分身启动蓝图，判断该走本人主脑、在世授权分身、逝者纪念分身还是授权门禁路线。
10. 蓝图返回 `authorization.allowed=false` 时，只展示授权下一步；不能自动学习、声音克隆、头像驱动或启动自动进化。
11. 蓝图允许后，再按 `learning.packageEndpoint`、`learning.ledgerEndpoint`、`evolution.commandCenterEndpoint` 读取单人人格学习包、人格学习账本和电子分身自动进化中枢包。
12. 需要审计“这个电子分身到底学了什么、来源哪里、哪些待确认”时，调用 `/api/brain/device/persona-learning-ledger?personId=xxx` 读取人格学习账本。
13. 现场陪伴可调用 `/api/brain/device/companion-reply`，学习只回传 `/api/brain/device/session` 摘要。

## 任意人物电子分身启动蓝图

`persona-bootstrap-blueprint` 是 App、家庭终端、小程序、网站后端、医院终端在创建或继续一个电子分身前读取的统一总入口。它把授权护照、单人人格学习包、学习账本、电子分身进化中枢和设备接入包编排成一份路线图：同一个接口会告诉客户端“这是本人主脑、在世授权分身、逝者纪念分身，还是必须先补授权”。

设备安全端点：

```http
GET https://n.hhtc.top/api/brain/device/persona-bootstrap-blueprint?personId=self
X-BrainOS-Ingest-Key: bos_ing_xxx
```

工作台登录态端点：

```http
GET https://n.hhtc.top/api/brain/persona-bootstrap-blueprint?personId=memorial_person_xxx&lifeStatus=deceased
Authorization: Bearer <token>
```

返回中的 `protocolVersion=brainos.persona_bootstrap_blueprint.v1`。核心路线：

| `target.route` | 适用对象 | 允许动作 |
|---|---|---|
| `self_brain` | 本人主脑 | 可读取学习包、回传授权摘要、运行自动进化 |
| `living_authorized_twin` | 已获本人或合法代理授权的在世人物 | 可创建 AI 分身模拟、摘要学习、低敏陪伴 |
| `deceased_memorial_twin` | 已获家属或合法授权确认的逝者 | 可做 AI 纪念陪伴、声音/头像低成本路线 |
| `authorization_required` | 未授权在世人物、未确认逝者或证据不足人物 | 只能展示授权下一步，不能自动学习或陪伴 |

推荐顺序：

```text
读取启动蓝图 -> 授权门禁判断 -> 读取学习包/账本 -> 低敏陪伴或采集 -> session 摘要回传 -> 进化中枢 -> 设备协作循环
```

关键字段：

| 字段 | 含义 |
|---|---|
| `target` | 当前人物、生命周期状态、关系、启动路线。 |
| `authorization` | 授权状态、硬门禁、确认端点、下一步授权动作和授权护照摘要。 |
| `learning` | 单人人格学习包、学习账本端点、是否 blocked、summary-only 标记。 |
| `evolution` | 自动进化中枢端点、是否可运行进化循环、下一轮动作摘要。 |
| `network` | 设备接入、任务领取、协作循环和启动清单。 |
| `creationGuide` | 新建人物所需字段，以及创建后应该调用哪些接口。 |
| `nextSteps` | 客户端可以直接展示或执行的下一步动作，含 endpoint、method、riskLevel。 |
| `policy` | 原始媒体、在世人物授权、逝者纪念边界、设备安全边界。 |

安全边界：

- 在世人物必须本人或合法授权，默认说明为 AI 分身模拟，不冒充本人实时在线。
- 逝者数字延续是 AI 纪念陪伴，不宣称现实复活，不替代亲属、医疗、法律或财务决策。
- 蓝图只返回摘要级状态、路线、端点和下一步动作；不返回原始照片、音频、视频、完整聊天全文或完整私密记忆。
- 照片、视频、音频只能由用户主动上传或明确授权；外部设备默认只读 `device_summary_only`。
- `authorization.allowed=false` 时，设备不能调用 `/api/brain/device/session` 回传学习摘要，不能启动声音克隆、头像驱动或自动进化循环。

SDK：

```js
// 登录工作台
const blueprint = await window.__brainExternalIngest.personaBootstrapBlueprint({
  personId: 'self'
});

// 外部设备 / 小程序后端
const deviceBlueprint = await window.__brainExternalIngest.fetchDevicePersonaBootstrapBlueprint(
  ingestKey,
  { personId: 'self' }
);
```

## 数字人格授权护照

`persona-authorization-passport` 是设备和工作台在“电子版的我 / 在世人物 / 逝者数字延续”之间做安全判断的统一护照。它不返回原始照片、音频、视频、聊天全文或完整私密记忆，只返回授权状态、证据数量、成熟度、下一步动作和安全边界。

设备安全端点：

```http
GET https://n.hhtc.top/api/brain/device/persona-authorization-passport?personId=self
X-BrainOS-Ingest-Key: bos_ing_xxx
```

工作台登录态端点：

```http
GET https://n.hhtc.top/api/brain/persona-authorization-passport?personId=memorial_person_xxx
Authorization: Bearer <token>
```

返回中的 `protocolVersion=brainos.persona_authorization_passport.v1`。推荐顺序是：

```text
读取授权护照 -> 只对 authorized 人物读取学习包 -> 低敏陪伴/采集 -> session 摘要回传 -> 学习回执 -> 自动成长巡检
```

核心字段：

| 字段 | 说明 |
|------|------|
| `summary.authorizedCount` | 当前可进入自动学习或陪伴的人物数量。 |
| `summary.blockedCount` | 仍缺本人授权、家属确认或授权证据的人物数量。 |
| `summary.readyForAutoLearning` | 设备可采集授权摘要并自动学习的人物数量。 |
| `summary.readyForRealtimeCompanion` | 可以进入实时陪伴的人物数量。 |
| `passports[].lifeStatus` | `self`、`living`、`deceased` 或 `unknown`。 |
| `passports[].authorizationStatus` | `authorized`、`needs_living_authorization`、`needs_family_confirmation` 或 `learning_pending`。 |
| `passports[].canAutoLearn` | 设备是否可以围绕该人物自动学习低敏摘要。 |
| `passports[].canRealtimeCompanion` | 是否可以启动实时陪伴。 |
| `passports[].canDeviceCollectSummary` | 设备是否可以采集并回传授权摘要。 |
| `passports[].canUseVoiceClone` | 是否已有授权音频证据，可走克隆/模拟声音路线。 |
| `passports[].canUsePhotoAvatar` | 是否已有头像/照片证据，可走照片头像 + 前端口型/表情模拟路线。 |
| `passports[].evidence` | 只展示计数和成熟度，不展示原文或素材 URL。 |
| `passports[].nextActions` | 下一步授权或补素材动作。 |
| `policy` | 摘要边界、原始媒体策略、在世人物边界和逝者纪念边界。 |

授权规则：

- `self`：本人主脑默认可学习，但原始照片、音频、视频仍必须由用户主动上传或显式授权。
- `living`：在世人物必须取得本人或合法代理授权，否则返回 `needs_living_authorization`，设备不得自动学习或冒充本人在线。
- `deceased/unknown`：逝者或未知状态人物需要家属/合法授权确认，或已有确认记忆、照片、音频等证据，否则返回 `needs_family_confirmation`。
- 设备端只能拿到 `device_summary_only` 内容；不得自动上传原始摄像头画面、麦克风录音、视频流、完整聊天或第三方隐私。
- 该护照是学习包、进化中枢和设备自动循环的硬门禁。授权未通过时，`persona-learning-package` 会返回 `blocked=true`、`authorizationGate.allowed=false`、`collectionContract.disabled=true`，设备只能提示补授权，不能回传学习摘要或启动陪伴。

前端 SDK：

```js
const passport = await window.__brainExternalIngest.personaAuthorizationPassport({ personId: 'self' });
const devicePassport = await window.__brainExternalIngest.fetchDevicePersonaAuthorizationPassport(ingestKey, { personId: 'self' });
```

工作台确认授权：

```http
POST https://n.hhtc.top/api/brain/persona-authorization/confirm
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "personId": "memorial_person_xxx",
  "displayName": "父亲",
  "lifeStatus": "deceased",
  "legalBasis": "家属或合法授权确认",
  "scope": "memorial_companion",
  "confirmationText": "确认该数字延续仅用于纪念陪伴，不宣称现实复活。"
}
```

该接口只写入一条 `eventType=authorization` 的低敏授权事件，不上传原始照片、音频或视频。确认后授权护照会重新计算；若人物满足规则，学习包会从 `blocked=true` 变为可执行，并恢复 `/api/brain/device/session` 摘要回传合同。

## 人格学习账本

`persona-learning-ledger` 是电子分身自动学习的可追溯账本。它把某个人的来源摘要、授权/确认状态、已沉淀知识节点、成长快照、设备任务和下一步补采动作放在同一份响应里，方便家庭终端、小程序、医院终端和工作台判断“它到底学了什么、从哪里学、哪些还不能自动学”。

设备端读取：

```http
GET https://n.hhtc.top/api/brain/device/persona-learning-ledger?personId=self
X-BrainOS-Ingest-Key: bos_ing_xxx
```

工作台登录态读取：

```http
GET https://n.hhtc.top/api/brain/persona-learning-ledger?personId=memorial_person_xxx
Authorization: Bearer <token>
```

核心字段：

```json
{
  "protocolVersion": "brainos.persona_learning_ledger.v1",
  "summary": {
    "auditStatus": "needs_confirmation",
    "readinessScore": 62,
    "totalEvents": 12,
    "learnedEvents": 7,
    "pendingReview": 2,
    "knowledgeNodes": 9,
    "growthSnapshots": 3,
    "activeSources": 4
  },
  "sourceBreakdown": [],
  "recentEvents": [],
  "knowledgeEvidence": [],
  "growthEvidence": {},
  "taskEvidence": {},
  "nextAction": {
    "type": "confirm_pending_memory",
    "endpoint": "/api/brain/ingest/events"
  }
}
```

边界规则：

- 设备端返回 `role=device_node`，只展示摘要引用和状态，不暴露内部 `eventId`、原始媒体 URL、完整聊天全文或完整私密记忆。
- 工作台端返回 `role=workspace`，可以看到可追溯的事件引用，用于人工确认、忽略或招商演示审计。
- `pendingReview > 0` 时，设备不能绕过用户确认自动写入长期人格画像，只能提醒进入记忆确认工作台。
- 账本不创造新记忆，只读取现有学习事件、知识节点、成长快照和设备任务，作为下一轮自动进化的证据层。

前端 SDK：

```js
const ledger = await window.__brainExternalIngest.personaLearningLedger({ personId: 'self' });
const deviceLedger = await window.__brainExternalIngest.fetchDevicePersonaLearningLedger(ingestKey, { personId: 'self' });
```

## 电子分身自动进化中枢包

`persona-evolution-command-center` 是给家庭终端、小程序、网站后端、机器人和医院终端读取的“下一轮自动进化总控包”。它把单人人格学习包、电子分身状态、自动成长巡检、万户拓扑、设备派发和执行守护合并成一份行动说明：当前该围绕哪个人学习、问什么问题、能否启动实时陪伴、由哪些设备补采、下一轮自动循环怎么跑。

```http
GET https://n.hhtc.top/api/brain/device/persona-evolution-command-center?personId=self
X-BrainOS-Ingest-Key: bos_ing_xxx
```

工作台登录态也可以读取：

```http
GET https://n.hhtc.top/api/brain/persona-evolution-command-center?personId=memorial_person_xxx
Authorization: Bearer <token>
```

返回中的 `protocolVersion=brainos.persona_evolution_command_center.v1`。设备推荐循环是：

```text
读取进化中枢 -> 读取人格学习账本 -> 读取单人人格学习包 -> 低敏陪伴/采集 -> session 摘要回传 -> collaboration-cycle -> execution guard -> learning-feedback
```

核心字段：

```json
{
  "success": true,
  "protocolVersion": "brainos.persona_evolution_command_center.v1",
  "summary": {
    "autonomyMode": "persona_learning_companion_loop",
    "scaleScore": 68,
    "twinScore": 61,
    "targetPersonId": "self",
    "targetDisplayName": "我 / 主脑",
    "onlineSources": 3,
    "ledgerReadinessScore": 62,
    "ledgerPendingReview": 2,
    "canLaunchCompanion": true,
    "canRunGuardedLoop": true
  },
  "learningLoop": {
    "packageId": "plp_xxx",
    "learningLedger": {
      "protocolVersion": "brainos.persona_learning_ledger.v1",
      "summary": {
        "auditStatus": "needs_confirmation",
        "learnedEvents": 7,
        "pendingReview": 2
      },
      "endpoint": "/api/brain/device/persona-learning-ledger"
    },
    "learningFocus": {
      "title": "补齐人格证据",
      "question": "这个人平时最常说哪几句话？",
      "riskLevel": "low",
      "rawMediaPolicy": "summary_only_no_raw_media"
    },
    "collectionContract": {
      "endpoint": "/api/brain/device/session",
      "requiredHeaders": ["X-BrainOS-Ingest-Key"]
    }
  },
  "evolutionLoop": {
    "nextCycle": {
      "shouldRun": true,
      "mode": "persona_learning_companion_loop",
      "requiresUserSummary": true,
      "rawMediaAllowed": false
    }
  },
  "networkLoop": {
    "priorityNodes": [],
    "recommendedDevices": [],
    "groupOperations": []
  }
}
```

安全边界：自动进化中枢只输出摘要级成熟度、学习账本、学习缺口、设备派发、万户拓扑、执行守护和延迟策略；不返回原始照片、音频、视频、完整聊天全文或完整私密记忆。设备可以自动展示问题、执行低风险陪伴和回传授权摘要，但不能伪造本人、不能自动确认敏感记忆、不能自动采集原始媒体。若 `learningLoop.learningLedger.summary.pendingReview > 0`，下一步优先提醒用户确认/忽略待确认摘要，不能继续堆积自动采集来绕过确认。

## 单人人格学习包

`persona-learning-package` 是给家庭终端、小程序、网站后端、机器人和医院终端直接消费的“某个人下一轮学习说明书”。它把学习计划、电子分身状态、实时陪伴启动策略、头像/声音策略、低敏问题和回传模板合并成一个包。设备拿到这个包后，不需要自己猜“现在应该围绕谁、问什么、怎么回传”。

学习包会先检查数字人格授权护照。若目标人物是未授权在世人物、未确认边界的逝者或其他未满足授权条件的人物，接口仍返回 `success=true` 以便设备兼容处理，但必须同时返回：

```json
{
  "blocked": true,
  "authorizationGate": {
    "allowed": false,
    "status": "needs_living_authorization",
    "canAutoLearn": false,
    "canRealtimeCompanion": false,
    "canDeviceCollectSummary": false
  },
  "collectionContract": {
    "disabled": true,
    "endpoint": "",
    "requiredHeaders": []
  }
}
```

设备遇到该状态只能展示 `authorizationGate.nextAction.instruction`，不能调用 `/api/brain/device/session` 回传学习摘要，也不能启动声音克隆、头像驱动或自动进化循环。

```http
GET https://n.hhtc.top/api/brain/device/persona-learning-package?personId=self
X-BrainOS-Ingest-Key: bos_ing_xxx
```

工作台登录态也可以读取同一语义的包：

```http
GET https://n.hhtc.top/api/brain/persona-learning-package?personId=memorial_person_xxx
Authorization: Bearer <token>
```

返回中的 `protocolVersion=brainos.persona_learning_package.v1`。设备执行循环是：

```text
读取学习包 -> 现场低敏互动 -> 回传摘要 -> 学习回执 -> 执行守护判断下一轮
```

核心字段：

```json
{
  "success": true,
  "protocolVersion": "brainos.persona_learning_package.v1",
  "selectedPersona": {
    "personId": "memorial_person_xxx",
    "displayName": "父亲",
    "lifeStatus": "deceased",
    "readinessScore": 62,
    "twinStage": "interactive_learning_twin"
  },
  "learningFocus": {
    "area": "commonPhrases",
    "question": "这个人平时最常说哪几句话？",
    "consentRequired": true,
    "summaryOnly": true,
    "rawMediaPolicy": "summary_only_no_raw_media"
  },
  "runtime": {
    "launchMode": "learning_companion",
    "voiceStrategy": {
      "mode": "browser_tts_style_simulation",
      "personalizedWarmupTexts": ["慢慢来，我在听。"]
    },
    "avatarStrategy": {
      "mode": "photo_avatar_simulation",
      "rawUrlIncluded": false
    }
  },
  "collectionContract": {
    "endpoint": "/api/brain/device/session",
    "requiredHeaders": ["X-BrainOS-Ingest-Key"],
    "bodyShape": {
      "sessionId": "plp_xxx",
      "personId": "memorial_person_xxx",
      "userText": "用户回答摘要，不上传原始音频",
      "assistantText": "数字人回应摘要",
      "learningNotes": ["用户明确授权保存的事实摘要"],
      "consent": "granted|pending",
      "payload": {
        "privacyBoundary": "summary_only_no_raw_media"
      }
    }
  },
  "nextEndpoints": {
    "learningPackage": "/api/brain/device/persona-learning-package",
    "executionGuard": "/api/brain/device/scale-command-center",
    "collaborationCycle": "/api/brain/device/collaboration-cycle"
  }
}
```

自动化边界：设备可以自动展示问题、播放低风险开场和回传授权摘要；不能自动确认敏感记忆、不能伪造任务结果、不能自动采集原始媒体。照片、视频、音频只允许用户主动上传或明确授权后进入素材流程。

网页、小程序 WebView、家庭终端或机器人可以直接使用 SDK 跑完整闭环。SDK 会先读取学习包；如果设备没有提供真实现场摘要，会安全暂停，不会替设备编造用户回答：

```js
const cycle = await window.__brainExternalIngest.runDevicePersonaLearningPackageCycle(ingestKey, {
  personId: 'memorial_person_xxx',
  sessionSummary: {
    userText: '用户授权摘要：父亲每天晚饭后会散步，常说慢慢来，别着急。',
    assistantText: '数字人回应摘要：用温和语气回应并确认会记住这个习惯。',
    learningNotes: ['晚饭后散步', '常说慢慢来，别着急'],
    consent: 'granted',
    confidence: 0.82
  }
});

if (cycle.paused) {
  console.log(cycle.skipped); // 例如 persona_learning_summary_required
}
```

如果设备要后台跟随学习包，也必须传入 `sessionSummaryBuilder`、`sessionBuilder` 或 `summaryBuilder`，由真实摄像头、麦克风、触摸屏、聊天记录等现场交互生成低敏摘要：

```js
const first = await window.__brainExternalIngest.runDevicePersonaLearningPackageCycle(ingestKey, {
  personId: 'self',
  sessionSummary: {
    userText: '用户授权摘要：今天对智能音箱说希望早上 7 点提醒吃药。',
    learningNotes: ['早上 7 点提醒吃药'],
    consent: 'granted'
  }
}, {
  autoScheduleNext: true,
  sessionSummaryBuilder: async (learningPackage) => {
    const focus = learningPackage.learningFocus || {};
    const summary = await collectLocalAuthorizedSummary(focus.question);
    return summary ? {
      userText: summary.userText,
      assistantText: summary.assistantText,
      learningNotes: summary.learningNotes,
      consent: summary.consent
    } : null;
  }
});
```

`runDevicePersonaLearningPackageCycle()` 的固定边界：

1. 先读 `/api/brain/device/persona-learning-package`，确定目标人物、问题、素材策略和回传模板。
2. 只允许回传 `userText`、`assistantText`、`learningNotes`、`summary` 等低敏摘要。
3. 检测到原始照片、音频、视频、base64 媒体或二进制字段时暂停。
4. 回传后读取 `learningReceipt`，再由 `handleDeviceLearningReceiptAction()` 领取低风险后续动作。
5. 只有显式设置 `runGuardedNextCycle: true` 或 `autoScheduleNext: true` 才继续下一轮。

## 设备执行守护端点

设备在开启自动循环前，应先读取设备安全版万户中枢总览。返回体中的 `executionGuard` 是设备侧调度闸门，用来决定下一步是心跳、拉任务、运行协作循环，还是暂停等待用户确认。

```http
GET https://n.hhtc.top/api/brain/device/scale-command-center
X-BrainOS-Ingest-Key: bos_ing_xxx
```

关键字段：

```json
{
  "success": true,
  "executionGuard": {
    "protocolVersion": "brainos.execution_guard.v1",
    "packageProtocolVersion": "brainos.device.execution_package.v1",
    "scope": "device",
    "status": "ready",
    "riskLevel": "low",
    "recommendedNextCall": {
      "method": "POST",
      "endpoint": "/api/brain/device/collaboration-cycle",
      "instruction": "在线设备运行协作循环，刷新心跳、领取任务并回传低敏摘要。",
      "nextRunAfterMs": 0
    },
    "summary": {
      "nodeCount": 1,
      "onlineCount": 1,
      "assignments": 1,
      "blocked": 0,
      "pendingReview": 0
    },
    "taskQueue": {
      "assignments": [],
      "blocked": []
    },
    "guardrails": {
      "rawMediaIncluded": false,
      "rawMediaPolicy": "explicit_user_upload_only",
      "taskResultRequiresSummary": true,
      "personaGapSummaryRequiresRealDeviceSummary": true,
      "contentScope": "device_summary_only"
    }
  }
}
```

设备自动循环建议规则：

1. `riskLevel=high` 且推荐端点不是 `/api/brain/device/heartbeat` 时，暂停自动执行，只展示状态并等待人工处理。
2. `summary.pendingReview>0` 或 `taskQueue.blocked.length>0` 时，不要自动确认记忆，也不要伪造任务结果。
3. `guardrails.rawMediaIncluded` 必须为 `false`，任务结果必须有 `resultSummary`、`learningNotes` 等摘要字段。
4. `recommendedNextCall.endpoint=/api/brain/device/tasks/pull` 时只领取任务，不自动完成任务。
5. `recommendedNextCall.endpoint=/api/brain/device/collaboration-cycle` 时可运行服务端一键协作，但真实任务结果仍需设备执行后的摘要。
6. `shouldCollectPersonaGapSummary` 或人格缺口任务必须来自真实设备现场摘要，不能由服务端或模拟器凭空生成。

网页、小程序 WebView、家庭终端 JS 环境可以直接使用 SDK 的守护版循环，不需要自己复制判断逻辑：

```js
const guarded = await window.__brainExternalIngest.runDeviceGuardedCollaborationCycle(ingestKey, {
  heartbeat: { online: true, capabilities: { speaker: true, microphone: true } },
  taskLimit: 3,
  refreshBriefing: true,
  fetchLearningFeedback: true
});

if (guarded.paused) {
  console.log('执行守护暂停', guarded.executionGuardAction.blockReasons);
}

// 守护循环会把服务端 cycle 标准化成顶层字段，设备可以直接读取：
// guarded.nextCycleAction / guarded.personaAutopilot / guarded.executionPackage / guarded.networkExpansionPlan
// 其中 personaAutopilot 是设备安全版电子分身自动学习行动包，不包含原始照片、音频、视频或完整私密记忆。
```

如果设备要后台跟随下一轮，也应使用守护版调度。每一轮都会重新读取 `/api/brain/device/scale-command-center`，不会沿用旧的低风险判断：

```js
window.__brainExternalIngest.scheduleDeviceGuardedCollaborationCycle(ingestKey, guarded.cycle, {
  maxAutoCycles: 3,
  onCycle(next) {
    console.log('守护循环完成', next.executionGuardAction, next.cycle?.nextCycleAction);
  }
});
```

如果设备运行在网页、小程序 WebView 或内置 JS 环境中，可以直接调用 SDK 的安全协作循环，把心跳、任务领取、摘要回传、回执处理和简报刷新串起来：

```js
const cycle = await window.__brainExternalIngest.runDeviceCollaborationCycle(ingestKey, {
  heartbeat: {
    online: true,
    capabilities: ['speaker', 'microphone'],
    deviceState: { scene: 'living_room', battery: 86 }
  },
  taskLimit: 3,
  autoPlanTasks: true,
  refreshBriefing: true,
  fetchLearningFeedback: true,
  personaGapSummaryBuilder: async (action) => {
    if (!action.shouldCollectPersonaGapSummary) return null;
    return {
      personId: action.actions.find(item => item.type === 'collect_persona_gap_summary')?.personId,
      area: 'commonPhrases',
      question: '补充这个人常说的话。',
      resultSummary: '用户授权补充：他常说慢慢来，遇事先稳住。',
      learningNotes: ['常用口头禅：慢慢来', '处事风格：先稳住'],
      consent: 'granted',
      confidence: 0.86
    };
  },
  taskResultBuilder: async (task) => ({
    success: true,
    resultSummary: '设备已执行主脑任务：' + task.title,
    outcome: '用户继续互动，设备只回传摘要。',
    learningNotes: ['本次结果为低敏摘要，不含原始音视频。'],
    consent: 'granted',
    confidence: 0.82
  })
});
```

`runDeviceCollaborationCycle()` 默认只做低风险动作。真实设备如果没有传入 `taskResultBuilder`，SDK 不会替设备伪造任务完成结果；如果没有传入 `personaGapSummary`、`personaGapSummaries` 或 `personaGapSummaryBuilder`，SDK 不会凭空生成某个人的人格资料。它也不会上传原始照片、视频、音频或完整聊天记录。

低能力硬件、医院终端、小程序后端如果不想在设备侧串多个接口，可以调用服务端一键协作循环。服务端会按同一套安全规则完成心跳、自动规划、领取任务、可选摘要回传、学习反馈和简报刷新。

```http
POST https://n.hhtc.top/api/brain/device/collaboration-cycle
X-BrainOS-Ingest-Key: bos_ing_xxx
Content-Type: application/json
```

请求体示例：

```json
{
  "heartbeat": {
    "capabilities": { "microphone": true, "speaker": true, "screen": true },
    "state": { "online": true, "battery": 88, "room": "living_room" }
  },
  "taskLimit": 3,
  "autoPlanTasks": true,
  "refreshBriefing": true,
  "fetchLearningFeedback": true,
  "includeGrowthInspection": true,
  "runGrowthInspection": false,
  "runPersonaEvolutionCycle": true,
  "personaGapSummary": {
    "personId": "memorial_person_xxx",
    "area": "commonPhrases",
    "question": "补充这个人常说的话。",
    "resultSummary": "用户授权补充：他常说慢慢来，遇事先稳住。",
    "learningNotes": ["常用口头禅：慢慢来", "处事风格：先稳住"],
    "consent": "granted",
    "confidence": 0.86
  },
  "taskResults": [
    {
      "taskId": "可选；不传时匹配本轮第一个任务",
      "success": true,
      "resultSummary": "设备已执行主脑任务，只回传摘要。",
      "learningNotes": ["不上传原始照片、视频、音频或完整聊天。"],
      "consent": "granted",
      "confidence": 0.82
    }
  ]
}
```

响应会返回 `executed`、`skipped`、`errors`、`tasks`、`taskResults`、`personaGapResults`、`personaAutopilot`、`personaEvolutionCycle`、`networkExpansionPlan`、`learningFeedback`、`briefing`、`growthInspection`、`dispatchPlan`、`nextCycle`、`executionPackage` 和 `policy`。如果请求体没有提供 `taskResults[].resultSummary`，服务端只会领取任务并返回 `submit_task_results_requires_summary`，不会替设备伪造任务完成结果。`personaGapSummary` / `personaGapSummaries` 必须是设备现场采集、用户授权的低敏文字摘要；服务端会拒绝原始照片、视频、音频、base64、上传路径或媒体 URL。`includeGrowthInspection=false` 可跳过成长巡检状态，`includeDispatchPlan=false` 可跳过派发计划，`includeNetworkExpansionPlan=false` 可跳过扩户计划摘要，`includePersonaAutopilot=false` 可跳过本轮电子分身自动进化指令。`runGrowthInspection=true` 会触发一次设备安全巡检闭环，用于生成低风险任务、阈值巩固建议和人格缺口摘要需求。`personaAutopilot` 默认返回设备安全版“下一轮围绕谁、补什么、是否暂停确认”的中枢摘要，并会同步进入 `nextCycle.personaAutopilot` 与 `executionPackage.personaAutopilotDirective`。`runPersonaEvolutionCycle=true` 会显式触发一次电子分身进化循环，并只返回目标人物、计数、下一步动作和安全策略摘要；默认不自动触发，避免把普通心跳变成重任务。`networkExpansionPlan` 默认返回设备安全版扩户摘要，用于让家庭终端、医院终端、小程序后端或网站后端知道下一户/下一设备怎么复制接入。`policy.serverDoesNotInventTaskResults=true`、`personaGapSummaryRequiresRealDeviceSummary=true`、`personaEvolutionCycleRequiresExplicitFlag=true`、`personaAutopilotIncludedByDefault=true`、`eventIdExposed=false`、`rawMediaIncluded=false` 是设备侧验收重点。

`executionPackage` 是设备可直接执行的标准说明书，协议版本为 `brainos.device.execution.v1`。它把“下一轮做什么、允许采什么、怎么回传、失败怎么办、多久后再来”统一在一个对象里，适合家庭终端、医院终端、小程序后端、网站后端和智能硬件直接消费：

```json
{
  "executionPackage": {
    "version": "brainos.device.execution.v1",
    "mode": "active_task_cycle",
    "recommendedEndpoint": "/api/brain/device/collaboration-cycle",
    "nextRunAfterMs": 20000,
    "primaryAction": {
      "type": "submit_task_summary",
      "endpoint": "/api/brain/device/collaboration-cycle",
      "instruction": "已有任务被领取但缺少 resultSummary；设备执行后必须只回传低敏摘要。",
      "priority": 1,
      "personId": "self"
    },
    "claimedTask": {
      "taskId": "dev_task_xxx",
      "taskType": "collect",
      "title": "补充人格画像学习样本",
      "instruction": "只回传摘要和学习线索。",
      "personId": "memorial_person_xxx",
      "area": "commonPhrases",
      "question": "补充这个人常说的话。"
    },
    "collectionDirective": {
      "shouldCollect": true,
      "targetPersonId": "memorial_person_xxx",
      "area": "commonPhrases",
      "question": "补充这个人常说的话。",
      "consentRequired": true,
      "allowedInputs": [
        "typed_summary",
        "button_feedback",
        "local_asr_transcript_summary",
        "camera_scene_summary_if_authorized",
        "uploaded_media_reference_if_user_uploaded"
      ],
      "forbiddenInputs": [
        "raw_audio_auto_upload",
        "raw_video_auto_upload",
        "raw_photo_auto_upload",
        "full_private_chat_history",
        "third_party_private_data_without_consent"
      ],
      "summaryTemplate": {
        "resultSummary": "用一句低敏摘要说明设备真实观察/互动结果",
        "consent": "granted | denied | unknown",
        "confidence": "0.5-1.0",
        "personId": "memorial_person_xxx",
        "area": "commonPhrases",
        "learningNotes": "可选：补充像本人/不像本人、偏好或生活片段摘要"
      }
    },
    "learningDirective": {
      "submitEndpoint": "/api/brain/device/tasks/dev_task_xxx/result",
      "requiredHeaders": ["X-BrainOS-Ingest-Key"],
      "requiredFields": ["resultSummary"],
      "receiptFields": ["learningReceipt", "nextCycle", "briefing", "executionPackage"],
      "summaryOnly": true,
      "rawMediaIncluded": false
    },
    "networkExpansionDirective": {
      "endpoint": "/api/brain/device/network/expansion-plan",
      "nextTarget": {
        "id": "home_terminal",
        "label": "家庭陪伴终端",
        "priority": 1,
        "score": 88
      },
      "createInviteEndpoint": "/api/brain/network/invite",
      "createSourceEndpoint": "/api/brain/ingest/sources",
      "collaborationEndpoint": "/api/brain/device/collaboration-cycle",
      "summaryOnly": true,
      "rawMediaIncluded": false
    },
    "personaAutopilotDirective": {
      "protocolVersion": "brainos.persona_evolution_command_center.v1",
      "targetPersonId": "self",
      "targetDisplayName": "我 / 主脑",
      "autonomyMode": "persona_learning_companion_loop",
      "ledger": {
        "summary": {
          "readinessScore": 62,
          "learnedEvents": 7,
          "pendingReview": 0
        }
      },
      "firstAction": {
        "type": "collect_persona_evidence",
        "title": "补齐人格证据",
        "endpoint": "/api/brain/device/session",
        "instruction": "采集一条用户授权的低敏摘要，让电子分身更像本人。",
        "riskLevel": "low"
      },
      "nextCycle": {
        "shouldRun": true,
        "endpoint": "/api/brain/device/collaboration-cycle",
        "requiresUserSummary": true,
        "rawMediaAllowed": false
      },
      "policy": {
        "privacyBoundary": "summary_only_no_raw_media",
        "rawMediaIncluded": false,
        "rawChatIncluded": false
      }
    },
    "scheduler": {
      "shouldHeartbeat": true,
      "shouldPullTasks": true,
      "shouldSubmitTaskSummary": true,
      "shouldFetchLearningFeedback": true,
      "shouldRefreshBriefing": true,
      "shouldRunGrowthInspection": false,
      "shouldRunPersonaEvolutionCycle": false,
      "shouldFollowPersonaAutopilot": true,
      "shouldRefreshNetworkExpansionPlan": true,
      "shouldPrepareNetworkExpansion": true,
      "shouldCollectPersonaGapSummary": true,
      "shouldAskUserConfirmation": false,
      "boundedAutoSchedule": true,
      "maxAutoCycles": 3
    },
    "failurePolicy": {
      "onMissingSummary": "do_not_mark_complete_keep_local_and_retry",
      "onUserConsentMissing": "ask_user_before_learning",
      "onNetworkError": "retry_after_nextRunAfterMs",
      "onRawMediaDetected": "reject_or_request_explicit_upload_consent"
    },
    "policy": {
      "contentScope": "device_summary_only",
      "privacyBoundary": "summary_only_no_raw_media",
      "rawMediaPolicy": "explicit_user_upload_only",
      "serverDoesNotInventTaskResults": true,
      "consentRequiredForLearning": true
    }
  }
}
```

设备侧优先读 `executionPackage.collectionDirective` 和 `executionPackage.learningDirective`；如果旧设备还没有升级，也可以继续读 `nextCycle`。`executionPackage` 不返回原始照片、音频、视频、完整聊天全文或内部事件 ID。

`nextCycle` 是设备下一轮协作指令，设备可以按它决定下一次什么时候运行、是否继续拉任务、是否必须补任务摘要、是否提醒用户确认记忆：

```json
{
  "nextCycle": {
    "mode": "active_task_cycle",
    "nextIntervalSec": 20,
    "nextRunAfterMs": 20000,
    "shouldHeartbeat": true,
    "shouldPullTasks": true,
    "shouldSubmitTaskSummary": true,
    "shouldFetchLearningFeedback": true,
    "shouldRefreshBriefing": true,
    "shouldRunGrowthInspection": true,
    "shouldRunPersonaEvolutionCycle": true,
    "shouldRefreshNetworkExpansionPlan": true,
    "shouldPrepareNetworkExpansion": true,
    "shouldFollowDispatchPlan": true,
    "shouldCollectPersonaGapSummary": false,
    "shouldAskUserConfirmation": false,
    "recommendedEndpoint": "/api/brain/device/collaboration-cycle",
    "growthInspection": {
      "readinessScore": 42,
      "phases": ["persona_gap_collection", "federation_bootstrap"],
      "runnableTasks": 2,
      "topReason": "next_persona_gap"
    },
    "dispatchPlan": {
      "dispatchMode": "pull_queued_tasks",
      "summary": { "assignments": 1, "blocked": 0, "queuedTasks": 2 },
      "assignments": [
        {
          "taskType": "pull_tasks",
          "dispatchMode": "pull_queued_tasks",
          "endpoint": "/api/brain/device/tasks/pull",
          "instruction": "低风险设备任务待领取；设备执行后只回传 resultSummary 和学习线索。"
        }
      ]
    },
    "personaEvolutionCycle": {
      "protocolVersion": "brainos.persona_evolution_cycle.v1",
      "targetPersonId": "self",
      "summary": {
        "confirmed": 1,
        "executedTasks": 0,
        "dispatchCreated": 1,
        "queuedTasks": 2,
        "pendingReview": 0,
        "autonomyMode": "server_guarded_persona_cycle"
      },
      "nextCycle": {
        "rawMediaAllowed": false,
        "requiresUserSummary": true
      }
    },
    "personaAutopilot": {
      "protocolVersion": "brainos.persona_evolution_command_center.v1",
      "targetPersonId": "self",
      "targetDisplayName": "我 / 主脑",
      "autonomyMode": "persona_learning_companion_loop",
      "ledger": {
        "summary": {
          "readinessScore": 62,
          "learnedEvents": 7,
          "pendingReview": 0
        }
      },
      "firstAction": {
        "type": "collect_persona_evidence",
        "endpoint": "/api/brain/device/session",
        "instruction": "采集一条用户授权的低敏摘要，让电子分身更像本人。"
      },
      "nextCycle": {
        "shouldRun": true,
        "endpoint": "/api/brain/device/collaboration-cycle",
        "requiresUserSummary": true,
        "rawMediaAllowed": false
      }
    },
    "networkExpansionPlan": {
      "protocolVersion": "brainos.network_expansion_plan.v1",
      "statusLabel": "可复制扩户",
      "summary": {
        "expansionScore": 82,
        "nextExpansionType": "home_terminal",
        "nodeCount": 3,
        "activeInvites": 1,
        "members": 2
      },
      "nextTarget": {
        "id": "home_terminal",
        "label": "家庭陪伴终端",
        "createSourceEndpoint": "/api/brain/ingest/sources",
        "collaborationEndpoint": "/api/brain/device/collaboration-cycle"
      },
      "policy": {
        "contentScope": "device_summary_only",
        "rawMediaIncluded": false
      }
    },
    "actions": [
      {
        "type": "submit_task_summary",
        "priority": 1,
        "endpoint": "/api/brain/device/collaboration-cycle",
        "instruction": "已有任务被领取但缺少 resultSummary；设备执行后必须只回传低敏摘要。"
      },
      {
        "type": "run_growth_inspection",
        "priority": 2,
        "endpoint": "/api/brain/device/growth-inspection/run",
        "instruction": "主脑成长巡检建议为设备自动规划低敏任务。"
      },
      {
        "type": "collect_persona_gap_summary",
        "priority": 3,
        "endpoint": "/api/brain/device/collaboration-cycle",
        "instruction": "围绕数字人格缺口采集一条用户授权的低敏摘要，通过 personaGapSummary 回写。"
      },
      {
        "type": "prepare_network_expansion",
        "priority": 4,
        "endpoint": "/api/brain/device/network/expansion-plan",
        "instruction": "读取扩户计划，按邀请码/接入源/协作循环路径复制到下一户、医院、小程序、网站或智能设备。"
      }
    ],
    "policy": {
      "contentScope": "device_summary_only",
      "privacyBoundary": "summary_only_no_raw_media",
      "serverDoesNotInventTaskResults": true
    }
  }
}
```

前端 SDK 也提供 `runDeviceServerCollaborationCycle()`，用于直接调用服务端一键协作循环：

```js
const cycle = await window.__brainExternalIngest.runDeviceServerCollaborationCycle(ingestKey, {
  heartbeat: { capabilities: { speaker: true }, state: { online: true } },
  taskLimit: 3,
  autoPlanTasks: true,
  refreshBriefing: true,
  runPersonaEvolutionCycle: true,
  fetchLearningFeedback: true
});
```

设备侧应把服务端返回的 `nextCycle` 当成下一轮协作计划，而不是直接无限循环。SDK 提供 `resolveDeviceNextCycleAction()` 把服务端计划标准化：

```js
const action = window.__brainExternalIngest.resolveDeviceNextCycleAction(cycle);

// 设备也可以直接把万户接入包交给同一个 resolver。
// SDK 会读取 package.personaAutopilot，并转成同样的 nextCycle action。
const devicePackage = await window.__brainExternalIngest.fetchDeviceNetworkOnboardingPackage(ingestKey);
const autopilotAction = window.__brainExternalIngest.resolveDeviceNextCycleAction(devicePackage);

// 会话回传、任务领取、任务结果和协作循环响应也可以直接交给 resolver。
// SDK 会依次读取 response.personaAutopilot、response.nextCycle.personaAutopilot、
// response.executionPackage.personaAutopilotDirective 和 sessionResult 中的同名字段。
const sessionAction = window.__brainExternalIngest.resolveDeviceNextCycleAction(sessionResult);

if (action.shouldSubmitTaskSummary) {
  // 真实设备执行任务后，只回传 resultSummary / learningNotes 等低敏摘要。
  // 不要让服务端或 SDK 自动伪造任务完成结果。
}

if (action.shouldAskUserConfirmation) {
  // 需要用户确认时，只提示用户，不自动确认敏感记忆。
}

if (action.shouldRunGrowthInspection) {
  // 主脑建议推进一次安全巡检。SDK 下一轮载荷会带 runGrowthInspection=true。
  console.log('巡检摘要', action.growthInspection);
}

if (action.shouldCollectPersonaGapSummary) {
  // 需要设备在现场互动中采集一条用户授权的低敏摘要，再调用 /api/brain/device/collaboration-cycle。
  // 请求体使用 personaGapSummary 或 personaGapSummaries，服务端会返回 personaGapResults。
  // 不上传完整音频、视频、照片或私密聊天全文。
  console.log('人格缺口采集建议', action.actions);
}

if (action.shouldFollowDispatchPlan) {
  // nextCycle.dispatchPlan.assignments 已被 SDK 标准化到 action.actions。
  // 设备按 endpoint 执行低敏任务领取、人格缺口摘要或心跳协作。
  console.log('中枢派发计划', action.dispatchPlan);
}

if (autopilotAction.personaAutopilot) {
  // 万户接入包里的电子分身自动学习行动包已经标准化。
  // 账本待确认、需要真实用户摘要、需要真实任务摘要时，SDK 会停止自动调度。
  console.log('电子分身自动学习下一步', autopilotAction.actions);
}

if (!action.shouldSubmitTaskSummary && !action.shouldAskUserConfirmation) {
  // 设备可以在 UI 上提示下一次运行时间，或由用户手动触发下一轮。
  console.log(action.nextRunAfterMs, action.actions);
}
```

如果设备确实需要后台自动跟随 `nextCycle`，必须显式开启 `autoScheduleNext` 或直接调用 `scheduleDeviceNextCollaborationCycle()`。SDK 会限制最大自动轮次，并在需要真实任务摘要或用户确认时停止自动运行：

```js
const cycle = await window.__brainExternalIngest.runDeviceServerCollaborationCycle(ingestKey, {
  heartbeat: { state: { online: true } },
  taskLimit: 3,
  refreshBriefing: true,
  fetchLearningFeedback: true,
  autoScheduleNext: true
}, {
  autoScheduleNext: true,
  maxAutoCycles: 3,
  onCycle(nextResult) {
    console.log('下一轮完成', nextResult.nextCycleAction);
  }
});

// 用户退出设备、解绑家庭终端或进入隐私模式时取消调度。
window.__brainExternalIngest.cancelScheduledDeviceNextCycle();
```

自动调度只负责下一轮心跳、拉任务、派发计划、学习反馈和简报刷新。
在新版设备上，它还会解析电子分身行动包和扩户首学闭环，但边界不变：不会自动上传原始照片、原始视频、原始音频或完整聊天记录；不会自动确认敏感记忆；不会在缺少 `taskResults[].resultSummary` 时替设备伪造任务结果；不会在缺少 `personaGapSummaryBuilder` 或真实 `personaGapSummary` 时伪造人格资料；也不会在缺少 `networkFirstLearningSessionSummary`、`networkFirstLearningSummaryBuilder` 或真实 `sessionSummary` 时执行扩户首学。若 `personaAutopilot.ledger.summary.pendingReview > 0` 或 `personaAutopilot.nextCycle.requiresUserSummary !== false`，SDK 会把下一轮标记为需要人工确认或真实摘要，默认不进入后台无限循环。

当 `nextCycle.shouldRunGrowthInspection=true` 时，SDK 构造的下一轮请求会带 `runGrowthInspection=true` 和 `includeGrowthInspection=true`，让主脑在服务端推进安全巡检。当 `nextCycle.shouldRunPersonaEvolutionCycle=true` 时，SDK 会显式带 `runPersonaEvolutionCycle=true`，并默认带 `includePersonaAutopilot=true`，让设备继续拿到电子分身自动学习行动包。`nextCycle.shouldCollectPersonaGapSummary=true` 只代表设备应该在获得用户授权后采集低敏人格缺口摘要；SDK 只有拿到 `personaGapSummaryBuilder` 或真实 `personaGapSummary` 才会回传，绝不会替设备凭空生成这个摘要。

当 `nextCycle.shouldRunNetworkFirstLearningLoop=true` 时，`scheduleDeviceNextCollaborationCycle()` 不再只跑普通协作循环，而是转入 `runDeviceNetworkFirstLearningLoop()`：先检查 `firstLearningLoop.authorizationGate`，再按“心跳 -> session 摘要回传 -> collaboration-cycle”执行。调度器只有拿到 `networkFirstLearningSessionSummary`、`networkFirstLearningSummaryBuilder`、`sessionSummary` 或 `sessionSummaryBuilder` 才会安排这一轮；否则返回 `network_first_learning_summary_required`，检测到原始媒体字段则返回 `raw_media_forbidden`。

## 设备接入自检端点

设备、小程序或网站完成启动清单和首次心跳后，建议调用一次自检端点。它会返回接入密钥、授权状态、心跳、简报、任务拉取、学习回执、ASR/TTS、摄像头摘要边界等检查项。自检不会返回原始照片、音频、视频、私密记忆、聊天全文或内部事件 ID。

```http
GET https://n.hhtc.top/api/brain/device/self-test
X-BrainOS-Ingest-Key: bos_ing_xxx
```

返回示例：

```json
{
  "success": true,
  "readiness": {
    "status": "warn",
    "score": 82,
    "passed": 8,
    "warnings": 3,
    "failed": 0
  },
  "checks": [
    {
      "id": "ingest_key_valid",
      "status": "pass",
      "endpoint": "/api/brain/device/self-test",
      "message": "接入密钥有效，设备身份已绑定到主脑。",
      "nextAction": "保管好 X-BrainOS-Ingest-Key；设备停用或丢失时在主脑工作台轮换密钥。"
    },
    {
      "id": "receipt_contract_ready",
      "status": "pass",
      "endpoint": "/api/brain/device/tasks/{taskId}/result",
      "message": "任务结果回传后应读取 learningReceipt 判断是否真正学习和成长。",
      "nextAction": "设备侧优先读取 response.learningReceipt.nextAction。"
    },
    {
      "id": "voice_input_ready",
      "status": "warn",
      "endpoint": "/api/asr/status",
      "message": "设备未声明麦克风能力，语音输入会退回文字/摘要。",
      "nextAction": "在心跳 capabilities.mic=true 后启用语音输入。"
    }
  ],
  "remediation": {
    "endpoint": "/api/brain/device/self-test/remediate",
    "method": "POST",
    "shouldPlan": true,
    "taskReason": "device_self_test_remediation",
    "summaryOnly": true
  },
  "policy": {
    "contentScope": "device_summary_only",
    "privacyBoundary": "自检只返回端点、状态、能力摘要和下一步动作；不返回原始照片、音频、视频、私密记忆、聊天全文或内部事件ID。",
    "rawMediaPolicy": "explicit_user_upload_only"
  }
}
```

设备侧处理建议：

1. `readiness.status=pass`：可以进入正常心跳、任务领取和陪伴流程。
2. `readiness.status=warn`：仍可运行，但应按 `checks[].nextAction` 补齐能力或提醒用户确认授权。
3. `readiness.status=fail`：不要自动执行陪伴或学习任务，先修复失败项。

## 设备自检修复任务端点

当自检结果包含 `warn` 或 `fail` 时，设备可以调用这个端点，让主脑把问题转成低风险修复任务，进入同一套 `/api/brain/device/tasks/pull` 队列。它不会直接执行高风险操作，也不会上传原始媒体；任务结果仍然通过 `/api/brain/device/tasks/{taskId}/result` 回传摘要。

```http
POST https://n.hhtc.top/api/brain/device/self-test/remediate
Content-Type: application/json
X-BrainOS-Ingest-Key: bos_ing_xxx
```

请求体：

```json
{
  "maxTasks": 5
}
```

返回示例：

```json
{
  "success": true,
  "createdCount": 2,
  "skippedCount": 1,
  "created": [
    {
      "taskId": "task_xxx",
      "taskType": "sync",
      "title": "恢复设备心跳连接",
      "payload": {
        "reason": "device_self_test_remediation",
        "checkId": "heartbeat_recent",
        "privacyBoundary": "summary_only_no_raw_media"
      },
      "postResultContract": {
        "endpoint": "/api/brain/device/tasks/{taskId}/result",
        "summaryOnly": true
      }
    }
  ],
  "policy": {
    "contentScope": "device_summary_only",
    "duplicatePolicy": "同一设备同一 checkId 只保留一个 queued/claimed 修复任务。"
  }
}
```

设备侧处理建议：

1. 调用 `/api/brain/device/self-test` 获取 `remediation.shouldPlan`。
2. 如果 `shouldPlan=true`，调用 `/api/brain/device/self-test/remediate`。
3. 继续调用 `/api/brain/device/tasks/pull` 领取修复任务。
4. 完成修复后调用 `/api/brain/device/tasks/{taskId}/result`，`resultSummary` 只写修复摘要。
5. 再次调用 `/api/brain/device/self-test`，确认对应 `checkId` 是否从 `warn/fail` 变为 `pass`。

## 设备心跳与能力上报端点

```http
POST https://n.hhtc.top/api/brain/device/heartbeat
Content-Type: application/json
X-BrainOS-Ingest-Key: bos_ing_xxx
```

设备应定期上报在线状态和能力摘要。主脑会把 `lastHeartbeatAt`、`capabilities` 和 `deviceState` 写入接入源，并在中枢简报中返回给设备和调度系统。

请求示例：

```json
{
  "deviceName": "客厅中枢终端",
  "online": true,
  "firmware": "speaker-1.0.3",
  "battery": 82,
  "network": "wifi",
  "latencyMs": 48,
  "capabilities": {
    "microphone": true,
    "speaker": true,
    "screen": true,
    "camera": false,
    "asr": true,
    "tts": true,
    "sensors": ["presence", "preference", "companion"]
  },
  "state": {
    "statusText": "online"
  }
}
```

成功返回会包含更新后的接入源和简报：

```json
{
  "success": true,
  "heartbeat": {
    "accepted": true,
    "online": true,
    "lastHeartbeatAt": "2026-06-08 09:55:00"
  },
  "source": {
    "online": true,
    "lastHeartbeatAt": "2026-06-08 09:55:00",
    "capabilities": {
      "microphone": true,
      "speaker": true
    }
  },
  "taskSignal": {
    "shouldPull": true,
    "queued": 2,
    "createdByHeartbeat": 1,
    "skippedByHeartbeat": 0,
    "created": [
      {
        "taskId": "dtask_xxx",
        "taskType": "companion",
        "title": "补充人格画像学习样本",
        "status": "queued"
      }
    ],
    "policy": {
      "cooldownMinutes": 20,
      "maxTasksPerSource": 2
    }
  }
}
```

`taskSignal` 是设备主动协作信号。设备每次心跳后如果看到 `taskSignal.shouldPull=true`，应立即调用 `/api/brain/device/tasks/pull` 领取任务；如果为 `false`，保持低频心跳即可。心跳触发的自动编排同样只生成低风险、摘要级任务，不会把完整私密记忆、原始照片、原始视频或原始音频下发给设备。

## 设备批量摘要同步端点

当家庭终端、小程序、网站或机器人积累了多条低敏摘要时，推荐使用批量同步端点一次回传。平台会逐条返回 `receipts`，告诉设备该摘要是否接收、是否进入长期记忆、是否进入确认队列。该端点最多接收 100 条事件；照片、视频、音频、base64 或媒体 URL 即使带有 `consent: "granted"`，也只会进入待确认，不会自动学习。

```http
POST https://n.hhtc.top/api/brain/device/ingest/sync
Content-Type: application/json
X-BrainOS-Ingest-Key: bos_ing_xxx
```

请求示例：

```json
{
  "events": [
    {
      "eventId": "device_summary_001",
      "eventType": "preference",
      "title": "夜间陪伴偏好",
      "content": "用户晚上更喜欢安静、短句、低延迟陪伴。",
      "consent": "granted",
      "confidence": 0.9,
      "payload": {
        "summaryOnly": true,
        "privacyBoundary": "summary_only_no_raw_media"
      }
    }
  ]
}
```

返回重点：

```json
{
  "success": true,
  "received": 1,
  "inserted": 1,
  "learned": 1,
  "pendingReview": 0,
  "receipts": [
    {
      "accepted": true,
      "learned": true,
      "reviewStatus": "learned",
      "reason": "learned_into_central_brain",
      "policy": {
        "contentScope": "device_summary_only",
        "privacyBoundary": "summary_only_no_raw_media",
        "rawMediaPolicy": "explicit_user_upload_only",
        "eventIdExposed": false
      }
    }
  ]
}
```

## 自动成长巡检端点

已登录主脑读取完整巡检：

```http
GET https://n.hhtc.top/api/brain/growth-inspection
Authorization: Bearer <user_token>
```

已登录主脑执行一次巡检闭环：

```http
POST https://n.hhtc.top/api/brain/growth-inspection/run
Content-Type: application/json
Authorization: Bearer <user_token>
```

已登录主脑读取自动进化任务队列：

```http
GET https://n.hhtc.top/api/brain/evolution/tasks
Authorization: Bearer <user_token>
```

已登录主脑执行可自动任务：

```http
POST https://n.hhtc.top/api/brain/evolution/tasks/run
Content-Type: application/json
Authorization: Bearer <user_token>
```

已登录主脑读取自动进化执行记录：

```http
GET https://n.hhtc.top/api/brain/evolution/tasks/runs
Authorization: Bearer <user_token>
```

已登录主脑读取自动成长守护状态：

```http
GET https://n.hhtc.top/api/brain/autonomous-evolution/status
Authorization: Bearer <user_token>
```

`/api/brain/autonomous-evolution/status` 用于运营后台、主脑同步面板和招商演示，证明系统不是一次性聊天，而是在按“安全摘要学习 -> 人格学习账本 -> 自动巩固 -> 低风险设备任务 -> 人工边界”持续成长。该端点返回安全候选数量、可自动任务数量、人工边界数量、人格质量分、需校准人格数量、语音延迟风险、人格学习账本成熟度、账本待确认数、最近自动执行记录、下一轮守护时间、成长巡检摘要和任务队列摘要。

其中 `selfRunningFlywheel.protocolVersion = brainos.self_running_flywheel.v1` 是自运转飞轮证明，面向家庭、医院、设备方和招商演示解释当前系统是否能自己持续转动。飞轮路径为：`万户节点心跳 -> 授权摘要回传 -> 可信审计 -> 人格学习账本 -> 自动进化守护 -> 低风险设备派发 -> 下一轮陪伴/采集`。它只返回阶段状态、摘要计数、阻塞原因、下一步动作和端点，例如 `stages[]`、`evidence.onlineSources`、`evidence.trustedContributionCandidates`、`evidence.ledgerPendingReview`、`evidence.queuedDeviceTasks`、`canTurnNow` 和 `nextAction`。

自动成长守护状态不会返回原始照片、视频、音频、麦克风内容、完整聊天全文或完整私密记忆；不会自动确认低置信事实、不会自动学习原始照片/视频/音频，也不会绕过在世本人授权、逝者家属确认或账本待确认摘要。若 `summary.personaLedgerPendingReview > 0`，`loop.nextAction` 会优先返回 `persona_ledger_confirmation_required`，设备和运营后台应提醒进入记忆确认工作台，而不是继续自动采集来绕过确认。

已登录主脑执行一次完整自进化飞轮：

```http
POST https://n.hhtc.top/api/brain/autonomous-evolution/flywheel/run
Authorization: Bearer <user_token>
Content-Type: application/json

{
  "personId": "self",
  "reason": "operator_one_click_flywheel",
  "limit": 12,
  "taskLimit": 10
}
```

返回协议为 `brainos.autonomous_evolution_flywheel_run.v1`。该端点会按固定顺序生成 `status_before -> persona_evolution_cycle -> network_dispatch_plan -> status_after` 的可审计执行报告：先读取自运转状态，再运行电子分身进化循环（内部包含可信摘要采纳、主脑成长闭环、学习账本、低风险任务），再运行万户设备派发计划，最后返回飞轮后的状态。返回只包含 `summary`、`before.selfRunningFlywheel`、`personaCycle` 安全摘要、`dispatch` 计数和 `after.selfRunningFlywheel`；不返回原始照片、音频、视频、完整聊天全文或完整私密记忆。

如果存在学习账本待确认、低置信事实、原始媒体、在世人物授权不足或逝者纪念边界未确认，`summary.status` 会返回 `needs_owner_review`，并通过 `summary.nextAction` 指向记忆确认或授权确认，而不是继续自动采集来绕过主人审计。

设备使用接入密钥读取低敏巡检：

```http
GET https://n.hhtc.top/api/brain/device/growth-inspection
X-BrainOS-Ingest-Key: bos_ing_xxx
```

设备触发一次受限巡检闭环：

```http
POST https://n.hhtc.top/api/brain/device/growth-inspection/run
Content-Type: application/json
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点把中枢状态、人格学习缺口、人格质量成长报表、运行档案、成长时间线、万户互联拓扑、待领取设备任务和自动巩固阈值汇总成一份可执行计划。成长巡检只返回状态计数、缺口、建议动作和低风险设备调度；不返回原始照片、视频、音频、聊天全文或完整私密记忆。

当人格质量报表显示“像不像待确认、纠正多、质量分偏低、真实陪伴样本不足、语音开口延迟高或 TTS 缓存未命中”时，成长巡检会自动加入：

- `summary.personaQualityScore`：当前人格质量平均分。
- `summary.qualityNeedsCalibration`：需要校准的人格数量。
- `summary.qualityVoiceLatencyRisks`：语音实时感风险数量。
- `persona.quality.targets[]`：需要校准或补样本的人格摘要，不含原始媒体。
- `phases[]` 中的 `persona_quality_calibration` 和 `voice_latency_optimization`。
- `evolutionTaskQueue.tasks[]` 中的 `quality_pending_confirmation`、`persona_quality_calibration`、`persona_quality_sample_gap`、`voice_latency_optimization`。

设备协作循环读取到这些任务后，只能回传用户授权的低敏陪伴摘要或提示用户进入确认工作台；不能自动上传原始录音、照片、视频，也不能替用户确认“像本人”的事实。

## 人格运行档案端点

设备、小程序或网站可以直接读取人格运行档案，查看某个人现在像不像本人、缺什么证据、下一步该采什么：

```http
GET https://n.hhtc.top/api/brain/device/persona-runtime-profiles?personId=self&limit=4
X-BrainOS-Ingest-Key: bos_ing_xxx
```

运行档案会返回 `assetReadiness`、`knowledgeReadiness`、`companionPolicy`、`evidenceChecklist`、`nextCollectionPrompt`、`nextAction` 和 `recentGrowth`。其中 `evidenceChecklist` 只描述头像、声音、长期记忆、身份关系、偏好习惯和安全边界的当前数量、目标数量与采集方式；`nextCollectionPrompt` 只给出下一条低敏采集建议，不会替设备生成原始照片、原始音频、原始视频或完整聊天全文。

## 人格质量成长报表端点

登录工作台读取完整质量成长报表：

```http
GET https://n.hhtc.top/api/brain/persona-quality-report?personId=self&outputLimit=8
Authorization: Bearer <token>
```

设备、小程序、网站或家庭终端读取低敏质量报表：

```http
GET https://n.hhtc.top/api/brain/device/persona-quality-report?personId=self&outputLimit=4
X-BrainOS-Ingest-Key: bos_ing_xxx
```

人格质量成长报表把 `user_feedback` 和 `companion_session` 聚合成可衡量的成长指标，用于判断一个电子分身或数字亲人当前有多像本人、哪里还不像、是否需要用户确认，以及实时陪伴是否被语音或 AI 延迟拖慢。

关键字段：

| 字段 | 说明 |
|------|------|
| `summary.avgQualityScore` | 人格质量平均分，综合拟合度、成熟度、学习率、正负反馈、纠正压力和延迟压力。 |
| `summary.needsCalibration` | 需要校准的人格数量，包含待确认、纠正多、质量分偏低的人格。 |
| `reports[].feedback` | 像不像、纠正次数、待校准数量、已学习数量。 |
| `reports[].companion.fitScoreAvg` | 陪伴会话中的人格拟合均分。 |
| `reports[].companion.latency` | 首字、完整、语音开口、TTS 缓存未命中等低敏延迟画像。 |
| `reports[].topGaps` | 当前最影响“像本人”的质量缺口。 |
| `reports[].nextActions` | 下一步动作，如确认待学习反馈、沉淀纠正线索、补齐像本人证据、优化语音实时感。 |

安全边界：质量报表只返回像不像、纠正次数、陪伴质量、延迟画像和待校准数量等摘要指标；不返回原始照片、音频、视频、聊天全文或完整私密记忆。设备端返回 `device_summary_only`，不能拿到原始事件 ID 或完整隐私内容。低置信、纠正、待确认和在世人物授权仍需用户确认；自动进化只能基于已授权摘要推进。

成功返回示例：

```json
{
  "success": true,
  "summary": {
    "readinessScore": 42,
    "mode": "learning",
    "phases": ["persona_gap_collection", "federation_bootstrap"],
    "pendingReview": 2,
    "queuedTasks": 1,
    "federationNodes": 3,
    "onlineNodes": 2,
    "consolidationDue": true
  },
  "nextActions": [
    {
      "channel": "persona",
      "priority": 1,
      "title": "补齐父亲的人格证据",
      "instruction": "请讲一个你和这个人真实相处的小故事，越具体越好。",
      "reason": "persona_learning_gap"
    }
  ],
  "deviceDispatch": {
    "shouldAutoPlan": true,
    "shouldPullTasks": true,
    "policy": {
      "maxTasksPerSource": 2,
      "cooldownMinutes": 20,
      "privacyBoundary": "只调度低敏摘要任务；照片、视频、音频必须由用户明确上传或授权。"
    }
  },
  "consolidation": {
    "shouldRun": true,
    "reason": "new_learning_events",
    "eventDelta": 3,
    "knowledgeDelta": 5
  },
  "evolutionTaskQueue": {
    "summary": {
      "total": 4,
      "highPriority": 2,
      "automationBoundary": "suggested_or_thresholded_only"
    },
    "tasks": [
      {
        "taskId": "evo_xxx",
        "kind": "persona",
        "priority": 1,
        "title": "补齐父亲的关键记忆",
        "instruction": "请讲一个你和这个人真实相处的小故事，越具体越好。",
        "riskLevel": "summary_only_no_raw_media",
        "automation": "conversation_or_device_task"
      }
    ]
  },
  "policy": {
    "contentScope": "device_summary_only",
    "privacyBoundary": "成长巡检只返回状态计数、缺口、建议动作和低风险设备调度；不返回原始照片、视频、音频、聊天全文或完整私密记忆。"
  }
}
```

执行巡检闭环时，主脑只会自动做两类低风险动作：

- 给已授权设备生成摘要级任务，例如低打扰陪伴、人格缺口提问、能力同步、授权健康趋势摘要。
- 当新学习事件或知识节点达到阈值时生成进化快照，更新中枢成熟度和人格画像。

执行巡检不会自动抓取摄像头、麦克风、照片、视频或音频；涉及媒体素材时，只能提示用户明确上传或授权。

`evolutionTaskQueue` 是主脑自己的自动进化任务清单，用来把“发现的问题”转成可跟踪的下一步，例如记忆确认、人格缺口提问、设备任务领取、自动巩固快照。任务队列只描述缺口、任务和调度建议；不能绕过用户确认，也不能自动采集原始媒体。

`/api/brain/evolution/tasks/run` 只会执行安全自动任务，例如低敏设备任务规划和达到阈值后的进化巩固。需要用户确认的记忆、人格缺口提问、照片/视频/音频素材上传，会返回 `requires_user`，不会由系统自动确认或自动采集。

`/api/brain/evolution/tasks/runs` 是自动进化执行审计记录，用来追踪每次执行选择了多少任务、自动执行了多少、多少需要用户确认、多少被跳过。执行记录只保存任务摘要、状态计数和执行结果摘要；不保存原始照片、视频、音频、麦克风内容、完整聊天全文或完整私密记忆。

## 万户互联拓扑端点

已登录主脑读取完整拓扑：

```http
GET https://n.hhtc.top/api/brain/federation/topology
Authorization: Bearer <user_token>
```

设备使用接入密钥读取低敏拓扑：

```http
GET https://n.hhtc.top/api/brain/device/federation/topology
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点把家庭、房间、设备、网站、小程序、任务队列和学习贡献汇总为一张中枢网络图，用于“万户互联”的设备协作调度。拓扑只返回设备能力、在线状态、任务和学习计数；不返回原始照片、视频、音频、聊天全文或完整私密记忆。

成功返回示例：

```json
{
  "success": true,
  "summary": {
    "nodeCount": 3,
    "onlineCount": 2,
    "groupCount": 1,
    "capabilityCoverage": {
      "microphone": 1,
      "speaker": 2,
      "camera": 1
    },
    "learnedEvents": 18,
    "pendingReview": 2,
    "queuedTasks": 1
  },
  "groups": [
    {
      "groupId": "default-home",
      "label": "默认家庭网络",
      "nodeCount": 3,
      "onlineCount": 2,
      "queuedTasks": 1
    }
  ],
  "nodes": [
    {
      "sourceType": "home_terminal",
      "sourceId": "livingroom-terminal",
      "room": "livingroom",
      "online": true,
      "capabilities": ["microphone", "speaker", "screen"],
      "syncScore": 82
    }
  ],
  "policy": {
    "contentScope": "summary_only",
    "privacyBoundary": "拓扑只返回设备能力、在线状态、任务和学习计数；不返回原始照片、视频、音频、聊天全文或完整私密记忆。"
  }
}
```

## 设备群健康总览端点

已登录主脑读取完整设备群健康：

```http
GET https://n.hhtc.top/api/brain/fleet/health
Authorization: Bearer <user_token>
```

设备使用接入密钥读取低敏健康总览：

```http
GET https://n.hhtc.top/api/brain/device/fleet/health
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点把万户互联拓扑进一步压缩成“健康分数、在线/离线、任务积压、自检修复、学习待确认和下一步动作”。它适合家庭终端、医院终端、小程序、网站或机器人在启动后判断自己和同一主脑设备群是否健康。设备态只返回摘要计数和能力标签；不返回原始照片、视频、音频、聊天全文、完整私密记忆或内部原始事件内容。

成功返回示例：

```json
{
  "success": true,
  "summary": {
    "nodeCount": 3,
    "onlineCount": 2,
    "offlineCount": 1,
    "attentionCount": 1,
    "queuedTasks": 2,
    "claimedTasks": 1,
    "failedTasks": 0,
    "remediationOpen": 1,
    "learnedEvents": 18,
    "pendingReview": 2,
    "healthScore": 76
  },
  "groups": [
    {
      "groupId": "default-home",
      "label": "默认家庭网络",
      "nodeCount": 3,
      "onlineCount": 2,
      "attentionCount": 1,
      "remediationOpen": 1,
      "healthScore": 76
    }
  ],
  "nodes": [
    {
      "sourceType": "home_terminal",
      "sourceId": "livingroom-terminal",
      "online": true,
      "healthScore": 88,
      "healthStatus": "healthy",
      "warnings": [],
      "tasks": {
        "queued": 1,
        "claimed": 0,
        "failed": 0,
        "remediationQueued": 0,
        "remediationClaimed": 0
      },
      "nextAction": "保持心跳并继续执行低风险学习任务。"
    }
  ],
  "recommendations": [
    "1 个接入源离线，优先恢复心跳。"
  ],
  "policy": {
    "contentScope": "device_summary_only",
    "privacyBoundary": "设备群健康总览只返回在线状态、能力标签、任务计数、学习计数、自检修复计数和下一步动作；不返回原始媒体、聊天全文或完整私密记忆。"
  }
}
```

## 设备学习反馈端点

## 人格学习计划端点

已登录主脑读取完整计划：

```http
GET https://n.hhtc.top/api/brain/persona-learning-plan
Authorization: Bearer <user_token>
```

设备使用接入密钥读取低敏计划：

```http
GET https://n.hhtc.top/api/brain/device/persona-learning-plan?limit=4
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点用于判断每个电子人还缺哪些资料：身份、亲友关系、偏好、人生经历、确认回忆、照片头像、声音样本、说话风格、常用口头禅、亲友称呼图谱和禁忌边界。设备端只返回覆盖度、缺口、下一步低敏问题和采集任务，不返回完整私密记忆、原始照片、视频、音频或聊天全文。

成功返回示例：

```json
{
  "success": true,
  "summary": {
    "personCount": 2,
    "readyCount": 0,
    "learningCount": 1,
    "bootstrapCount": 1,
    "missingAreas": ["confirmedMemories", "photos", "audio"],
    "nextTarget": {
      "personId": "mp_father",
      "displayName": "父亲",
      "readinessScore": 38,
      "firstQuestion": "请讲一个你和这个人真实相处的小故事，越具体越好。"
    }
  },
  "plans": [
    {
      "personId": "mp_father",
      "displayName": "父亲",
      "lifeStatus": "deceased",
      "readinessScore": 38,
      "missing": ["confirmedMemories", "photos", "audio"],
      "nextQuestions": [
        {
          "area": "memories",
          "label": "长期记忆",
          "question": "请讲一个你和这个人真实相处的小故事，越具体越好。",
          "riskLevel": "low"
        }
      ],
      "collectionTasks": [
        {
          "taskType": "companion",
          "reason": "persona_learning_gap",
          "area": "memories",
          "instruction": "用一个低敏问题采集长期记忆摘要；只回传摘要，不上传原始音视频。"
        }
      ]
    }
  ],
  "policy": {
    "contentScope": "device_summary_only",
    "privacyBoundary": "学习计划只返回覆盖度、缺口、下一步问题和低风险采集任务；不返回完整私密记忆、原始照片、视频、音频或聊天全文。",
    "taskBoundary": "设备任务只能采集授权摘要；照片、视频、音频必须由用户明确上传或授权。"
  }
}
```

设备使用原则：

- 支持麦克风或屏幕的设备，可以按 `nextQuestions` 一次只问一个低敏问题。
- 支持网站/小程序的来源，可以把 `collectionTasks` 转成资料补充入口。
- 涉及照片、视频、音频的缺口，只能提示用户主动上传或授权，不能自动抓取。
- 在世人物必须基于本人或合法授权资料；逝者数字延续必须标明为纪念陪伴。

```http
GET https://n.hhtc.top/api/brain/device/learning-feedback?limit=8
X-BrainOS-Ingest-Key: bos_ing_xxx
```

设备写入事件、回传陪伴会话或完成任务后，可以读取学习反馈，确认主脑是否已经把数据写入长期记忆，是否还有待用户确认的事件。

成功返回示例：

```json
{
  "success": true,
  "feedback": {
    "totalEvents": 12,
    "learnedEvents": 9,
    "pendingReview": 3,
    "learningRatio": 0.75,
    "lastEventAt": "2026-06-08 10:20:00",
    "lastLearnedAt": "2026-06-08 10:20:00"
  },
  "recentEvents": [
    {
      "eventId": "device_20260608_0001",
      "eventType": "preference",
      "title": "用户疲惫时更喜欢短句陪伴",
      "learningAllowed": true,
      "reviewStatus": "learned"
    }
  ],
  "guidance": [
    "继续上报带上下文的真实生活事件，帮助主脑建立稳定人格画像。"
  ]
}
```

## 事件格式

```json
{
  "eventId": "device_20260608_0001",
  "eventType": "device_state",
  "title": "客厅终端检测到用户回家",
  "content": "用户 19:30 回到家，情绪平稳，播放了常听音乐。",
  "payload": {
    "room": "livingroom",
    "signal": "presence",
    "confidence": 0.86
  },
  "consent": "granted",
  "confidence": 0.86,
  "timestamp": 1780852600000
}
```

## 设备实时数字人格回复端点

```http
POST https://n.hhtc.top/api/brain/device/companion-reply
Content-Type: application/json
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点用于智能音箱、家庭中枢、机器人、小程序、网站客服等外部设备，在获得用户授权后，把现场一句话发给 BrainOS，由平台统一调用数字人格生成低延迟陪伴回复。它适合“设备现场对话”，但默认不保存完整原始对话；如果本次互动需要进入学习，设备必须再调用 `/api/brain/device/session`，只回传摘要和学习线索。

请求示例：

```json
{
  "sessionId": "livingroom_reply_20260608_001",
  "personId": "self",
  "userText": "我今天有点累，想听你简单陪我说两句。",
  "context": "客厅终端低延迟陪伴测试",
  "mode": "realtime_companion",
  "consent": "granted",
  "history": [
    { "role": "system", "text": "设备端只请求低敏陪伴回复，不上传完整录音。" }
  ]
}
```

成功返回示例：

```json
{
  "success": true,
  "sessionId": "livingroom_reply_20260608_001",
  "personId": "self",
  "launchMode": "realtime_companion",
  "reply": "我在。你先不用撑着，慢慢说就好。",
  "assistantText": "我在。你先不用撑着，慢慢说就好。",
  "voiceStrategy": {
    "mode": "browser_or_cached_tts",
    "lowCostDefault": true,
    "preferredLine": "慢慢来。",
    "personalizedWarmupTexts": ["慢慢来。", "我在听。", "我会认真记住。"],
    "cacheHint": {
      "endpoint": "/api/tts/warmup",
      "summaryOnly": true,
      "rawMediaIncluded": false,
      "deviceMayPrewarm": true
    }
  },
  "recognitionStrategy": {
    "mode": "device_local_asr_first",
    "preferredInput": "device_or_browser_asr",
    "fallbackOrder": ["device_builtin_asr", "browser_speech_recognition", "typed_summary", "status_gated_sensevoice"],
    "senseVoice": {
      "statusEndpoint": "/api/asr/status",
      "useOnlyWhenStatusReady": true,
      "unavailableFallback": "device_or_browser_asr_then_text_summary"
    }
  },
  "avatarStrategy": {
    "mode": "photo_avatar_lip_sync",
    "lowCostDefault": true
  },
  "uiHints": {
    "suggestedTone": "short_warm"
  },
  "learning": {
    "postSessionEndpoint": "/api/brain/device/session",
    "summaryOnly": true
  },
  "policy": {
    "contentScope": "device_summary_only",
    "rawDialogStored": false
  }
}
```

设备端建议流程：

1. 先调用 `/api/brain/device/briefing` 获取中枢模式、数字人状态和安全策略。
2. 现场一句话调用 `/api/brain/device/companion-reply` 获取回复、语音策略、语音识别策略和头像策略。
3. 设备用低成本默认方案播放：照片头像 + 浏览器/缓存 TTS + 前端口型/表情模拟。
4. 设备可把 `voiceStrategy.personalizedWarmupTexts` 先发给 `/api/tts/warmup` 做短句缓存；这些短句只来自授权口头禅或低敏摘要，不包含原始录音、视频、照片或完整聊天。
5. 用户授权学习时，再调用 `/api/brain/device/session` 回传摘要，不上传完整录音、完整视频或未经授权的第三方隐私。

语音识别策略：

- 设备优先使用自带 ASR、浏览器 `SpeechRecognition` 或小程序语音识别，把识别后的文字摘要传给平台。
- 后端 SenseVoice 只能在 `/api/asr/status` 返回 `ready=true` 时使用；不可用时不要阻塞陪伴流程。
- 后端 ASR 不可用时，设备应降级为本地识别、文字输入或摘要回传，仍然可以完成陪伴和学习闭环。
- 平台默认不要求上传原始录音；原始音频、视频只允许用户主动上传或明确授权后处理。

边界说明：

- 逝者数字人物是纪念陪伴和记忆延续，不等同于真实复活。
- 在世人物是授权后的 AI 模拟，不表示本人实时在线。
- 设备只应请求低敏陪伴回复；医疗、法律、金融等高风险场景必须转人工或显示明确风险边界。
- 默认策略为 `device_summary_only`，平台不要求设备上传原始音频、视频或完整聊天记录。

## 设备陪伴会话回传端点

```http
POST https://n.hhtc.top/api/brain/device/session
Content-Type: application/json
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点用于智能音箱、家庭终端、机器人、摄像头、小程序等设备，在读取中枢简报并完成一次陪伴后，把互动摘要回写到主脑学习队列。

请求示例：

```json
{
  "sessionId": "livingroom_20260608_001",
  "personId": "self",
  "deviceName": "客厅中枢终端",
  "companionMode": "learning_companion",
  "emotion": "平稳但疲惫",
  "userText": "我今天有点累，想听你简单陪我说两句。",
  "assistantText": "我在，先别急。你可以慢慢说，我会用短句陪着你。",
  "outcome": "用户停留并继续对话，短句低打扰策略有效。",
  "learningNotes": [
    "用户疲惫时更接受短句陪伴",
    "设备应优先低打扰、可中断语音"
  ],
  "consent": "granted",
  "confidence": 0.82,
  "timestamp": 1780852600000
}
```

返回示例：

```json
{
  "success": true,
  "inserted": 1,
  "duplicate": false,
  "sessionId": "livingroom_20260608_001",
  "sourceId": "livingroom-speaker",
  "personId": "person_xxx",
  "learningAllowed": true,
  "learned": true,
  "personaMaturity": 61,
  "growthSnapshot": {
    "recorded": true,
    "area": "companion_session",
    "maturityDelta": 2
  },
  "learningReceipt": {
    "accepted": true,
    "sourceId": "livingroom-speaker",
    "sourceType": "home_terminal",
    "personId": "person_xxx",
    "sessionId": "livingroom_20260608_001",
    "learned": true,
    "learningAllowed": true,
    "duplicate": false,
    "personaMaturity": 61,
    "growth": {
      "recorded": true,
      "area": "companion_session",
      "maturityDelta": 2,
      "reason": "persona_growth_recorded"
    },
    "nextAction": {
      "type": "refresh_briefing",
      "instruction": "本次会话摘要已写入主脑，请刷新设备简报获取最新人格状态。"
    },
    "personaLedgerReceipt": {
      "protocolVersion": "brainos.persona_task_result_ledger_receipt.v1",
      "targetPersonId": "person_xxx",
      "sourceType": "home_terminal",
      "sourceId": "livingroom-speaker",
      "area": "companion_session",
      "ledgerStatus": "learned",
      "learned": true,
      "growthRecorded": true,
      "maturityDelta": 2,
      "nextActionType": "refresh_briefing",
      "policy": {
        "contentScope": "persona_task_result_ledger_summary_only",
        "rawMediaIncluded": false,
        "privacyBoundary": "任务结果账本凭证只返回目标分身、领域、入账状态、成熟度变化和下一步；不返回原始音视频、完整聊天或私密记忆正文。"
      }
    },
    "policy": {
      "contentScope": "device_summary_only",
      "privacyBoundary": "summary_only_no_raw_media",
      "rawMediaPolicy": "explicit_user_upload_only",
      "eventIdExposed": false,
      "rawMediaIncluded": false
    }
  },
  "personaAutopilot": {
    "protocolVersion": "brainos.persona_evolution_command_center.v1",
    "targetPersonId": "self",
    "targetDisplayName": "我 / 主脑",
    "nextCycle": {
      "endpoint": "/api/brain/device/collaboration-cycle",
      "rawMediaAllowed": false
    }
  },
  "nextCycle": {
    "recommendedEndpoint": "/api/brain/device/collaboration-cycle",
    "shouldPullTasks": true,
    "personaAutopilot": {
      "protocolVersion": "brainos.persona_evolution_command_center.v1",
      "targetPersonId": "self"
    },
    "nextRunAfterMs": 20000
  },
  "executionPackage": {
    "version": "brainos.device.execution.v1",
    "recommendedEndpoint": "/api/brain/device/collaboration-cycle",
    "collectionDirective": {
      "consentRequired": true,
      "rawMediaPolicy": "explicit_user_upload_only"
    },
    "learningDirective": {
      "submitEndpoint": "/api/brain/device/session",
      "summaryOnly": true,
      "rawMediaIncluded": false
    },
    "personaAutopilotDirective": {
      "protocolVersion": "brainos.persona_evolution_command_center.v1",
      "targetPersonId": "self",
      "policy": {
        "rawMediaIncluded": false
      }
    },
    "policy": {
      "privacyBoundary": "summary_only_no_raw_media",
      "serverDoesNotInventTaskResults": true
    }
  }
}
```

设备侧处理规则：

- 始终优先读取 `learningReceipt`，不要依赖内部 `eventId` 做业务展示。
- `learningReceipt.learned=true` 表示本次摘要已进入长期记忆；`growth.recorded=true` 表示它推动了对应数字人格成长。
- 新设备应读取 `learningReceipt.personaLedgerReceipt`，确认任务结果进入哪个电子分身、哪个领域、账本状态和成熟度变化；该字段只含低敏摘要计数和状态，不含原始内容。
- 新设备应同时读取 `executionPackage`，直接决定下一轮是否继续拉任务、采集授权摘要、刷新简报或等待用户确认；旧设备可继续只读取 `learningReceipt.nextAction`。
- 新设备应同步读取 `personaAutopilot`、`nextCycle.personaAutopilot` 或 `executionPackage.personaAutopilotDirective`，把本次会话后的电子分身目标人物、账本待确认数和下一步低敏采集问题接到下一轮 UI/调度里。
- `learningReceipt.nextAction.type=pull_or_execute_next_task` 时，设备应继续领取或执行 `nextTask`；否则按 `nextAction.instruction` 刷新简报、补充摘要或请求用户授权。
- `policy.eventIdExposed=false` 和 `policy.rawMediaIncluded=false` 是设备侧隐私边界确认；设备日志不应展示内部事件 ID、原始音频、原始视频或完整聊天全文。

前端/网页/小程序 WebView 可以复用平台 SDK 的统一决策函数：

```js
const result = await window.__brainExternalIngest.sendDeviceCompanionSession(ingestKey, sessionSummary);
const action = window.__brainExternalIngest.resolveDeviceLearningReceiptAction(result);

if (action.shouldPullTasks) {
  await window.__brainExternalIngest.pullDeviceTasks(ingestKey, { limit: 3 });
} else if (action.shouldRefreshBriefing) {
  await window.__brainExternalIngest.fetchDeviceBriefing(ingestKey);
} else if (action.shouldAskConsent) {
  // 提醒用户授权只保存摘要，不上传原始音视频。
} else if (action.shouldImproveSummary) {
  // 下一次回传更清晰的低敏摘要和 learningNotes。
}
```

也可以直接交给平台 SDK 自动执行：

```js
const result = await window.__brainExternalIngest.sendDeviceCompanionSession(ingestKey, sessionSummary);
const followup = await window.__brainExternalIngest.handleDeviceLearningReceiptAction(ingestKey, result, {
  taskLimit: 3,
  autoPlanTasks: true,
  refreshBriefing: true
});

// followup.executed 可能包含 pull_tasks / refresh_briefing。
// followup.skipped 可能包含 ask_user_learning_consent / await_more_context。
```

`handleDeviceLearningReceiptAction()` 只会执行低风险动作：领取下一步任务、刷新中枢简报、提示授权、提示补充摘要；不会自动上传原始照片、原始视频、原始音频，也不会替用户自动确认敏感记忆。真实设备执行任务后仍需调用 `/api/brain/device/tasks/{taskId}/result`，以低敏摘要回写结果。

设备端如果希望把心跳、拉任务、摘要结果回传和回执后续动作合成一个周期，可以使用：

```js
const cycle = await window.__brainExternalIngest.runDeviceCollaborationCycle(ingestKey, {
  taskLimit: 3,
  autoPlanTasks: true,
  refreshBriefing: true,
  taskResultBuilder: async (task) => ({
    success: true,
    resultSummary: '设备完成：' + task.title,
    learningNotes: ['只回传摘要，不上传原始媒体。'],
    consent: 'granted',
    confidence: 0.8
  })
});

// cycle.executed 可能包含 heartbeat / pull_tasks / submit_task_result / refresh_briefing。
// cycle.skipped 包含 submit_task_results_requires_builder 时，表示设备没有提供摘要回写函数。
```

`resolveDeviceLearningReceiptAction()` 会把 `learningReceipt.nextAction` 统一解析成：

| 字段 | 说明 |
|------|------|
| `type` | 主脑建议动作，例如 `pull_or_execute_next_task`、`refresh_briefing`、`await_more_context`、`ask_user_learning_consent`。 |
| `shouldPullTasks` | 是否应立即调用 `/api/brain/device/tasks/pull`。 |
| `shouldRefreshBriefing` | 是否应刷新 `/api/brain/device/briefing`。 |
| `shouldAskConsent` | 是否需要提示用户授权只保存摘要。 |
| `shouldImproveSummary` | 是否需要设备下次补充更清晰的摘要和学习线索。 |
| `policyOk` | `eventIdExposed=false` 且 `rawMediaIncluded=false` 时为 `true`，用于设备侧隐私自检。 |

## 主脑设备任务队列

已登录主脑创建任务：

```http
POST https://n.hhtc.top/api/brain/device/tasks
Content-Type: application/json
Authorization: Bearer <user_token>
```

请求示例：

```json
{
  "sourceType": "home_terminal",
  "sourceId": "livingroom-terminal",
  "taskType": "companion",
  "title": "低打扰陪伴",
  "instruction": "用户回家后先轻声问候，使用短句陪伴，不要追问隐私。",
  "priority": 2,
  "payload": {
    "preferredOpening": "我在，你慢慢说。"
  }
}
```

已登录主脑自动编排任务：

```http
POST https://n.hhtc.top/api/brain/device/tasks/auto-plan
Content-Type: application/json
Authorization: Bearer <user_token>
```

请求示例：

```json
{
  "sourceLimit": 12,
  "maxTasksPerSource": 3
}
```

自动编排逻辑：

- 主脑会优先读取设备最近一次心跳里的 `capabilities`，按能力分配任务，而不是只按设备名称分配。
- 有 `microphone/asr` + `speaker/tts` 的设备：可下发 `companion`，执行短句陪伴并回传摘要。
- 有 `speaker/tts` 但没有麦克风的设备：只播放低打扰短句，不要求录音。
- 有 `camera/vision` 的设备：下发低敏 `observe`，只回传是否有人、停留、亮度、授权情绪摘要，不上传原始照片/视频。
- 有 `health` 或健康传感器的设备：下发健康摘要 `collect`，只采集授权趋势，不生成医疗诊断。
- 有 `screen` 的设备、网站、小程序：下发交互偏好 `collect`，记录点击、停留、选择、内容风格摘要。
- 人格成熟度低或知识节点少：根据设备能力给网站/小程序/屏幕设备下发 `collect`，给支持扬声器的家庭终端/机器人下发 `companion`。
- 人格学习计划存在缺口：自动生成 `persona_learning_gap` 任务，让设备或网页一次只采集一个低敏摘要；照片、视频、音频只能由用户主动上传或授权。
- 存在待确认学习事件：下发 `observe`，继续采集低敏摘要，等待主脑确认。
- 中枢启动成熟度低：下发 `sync`，让设备回传在线状态和传感器能力。
- 同一接入源同一任务类型如果已有 `queued` 或 `claimed` 任务，自动跳过；默认 20 分钟内不会重复自动生成同类型任务，避免设备频繁打扰。

成功返回示例：

```json
{
  "success": true,
  "generatedAt": "2026-06-08T01:40:00.000Z",
  "sourcesConsidered": 2,
  "createdCount": 3,
  "skippedCount": 1,
  "created": [
    {
      "taskId": "dtask_xxx",
      "sourceId": "livingroom-terminal",
      "taskType": "companion",
      "title": "补充人格画像学习样本",
      "status": "queued"
    }
  ],
  "central": {
    "readinessScore": 42,
    "mode": "learning",
    "nextActions": ["继续确认待学习事件"]
  }
}
```

设备领取任务：

```http
GET https://n.hhtc.top/api/brain/device/tasks/pull?limit=5
X-BrainOS-Ingest-Key: bos_ing_xxx
```

默认情况下，设备领取任务时如果当前没有 `queued` 任务，主脑会针对该设备按需自动编排最多 2 个低风险任务，然后立即返回给设备执行。设备也可以传 `autoPlan=0` 只领取已有任务：

```http
GET https://n.hhtc.top/api/brain/device/tasks/pull?limit=5&autoPlan=0
X-BrainOS-Ingest-Key: bos_ing_xxx
```

领取成功会返回 `autoPlan.triggered`、`createdCount`、`skippedCount` 和 `policy.cooldownMinutes`，用于设备判断本次任务是否由主脑即时生成。

设备回传任务结果：

```http
POST https://n.hhtc.top/api/brain/device/tasks/{taskId}/result
Content-Type: application/json
X-BrainOS-Ingest-Key: bos_ing_xxx
```

结果示例：

```json
{
  "success": true,
  "resultSummary": "设备已完成低打扰陪伴，用户继续停留互动。",
  "userText": "我今天有点累。",
  "assistantText": "我在，你慢慢说。",
  "learningNotes": [
    "用户疲惫时更接受短句陪伴"
  ],
  "resultPayload": {
    "evidenceKey": "preference_habit",
    "collectionMode": "conversation_summary",
    "rawMediaPolicy": "explicit_user_upload_only"
  },
  "consent": "granted",
  "confidence": 0.82
}
```

当任务来自人格缺口采集或 `nextCollectionPrompt` 时，设备应在 `resultPayload.evidenceKey` 回传本次结果对应的证据字段，例如 `avatar_visual`、`voice_signature`、`long_term_memory`、`identity_relationship`、`preference_habit` 或 `safety_boundary`。主脑会优先用 `resultPayload.evidenceKey` 判断这条低敏摘要应该补到照片形象、声音特征、长期记忆、身份关系、偏好习惯还是安全边界；设备不要直接上传原始照片、原始音频、原始视频，除非用户在前端明确选择原始素材上传。

任务类型：

| taskType | 用途 |
|----------|------|
| `remind` | 提醒用户做某件事。 |
| `companion` | 执行一次陪伴或对话。 |
| `collect` | 采集授权数据摘要。 |
| `observe` | 观察环境或状态并回传摘要。 |
| `sync` | 执行设备同步动作。 |

成功返回会包含写入结果和更新后的低敏简报：

```json
{
  "success": true,
  "task": {
    "taskId": "devtask_xxx",
    "status": "completed"
  },
  "learningReceipt": {
    "accepted": true,
    "taskId": "devtask_xxx",
    "taskType": "collect",
    "sourceId": "livingroom-speaker",
    "personId": "person_xxx",
    "learned": true,
    "learningAllowed": true,
    "duplicate": false,
    "resultSummaryAccepted": true,
    "personaMaturity": 64,
    "growth": {
      "recorded": true,
      "snapshotId": "evo_xxx",
      "area": "commonPhrases",
      "maturityDelta": 4
    },
    "memorialSync": {
      "applied": true,
      "updatedFields": ["common_phrases"]
    },
    "nextTask": {
      "taskId": "devtask_next",
      "taskType": "collect",
      "title": "继续补齐目标人物资料",
      "area": "taboos"
    },
    "nextAction": {
      "type": "pull_or_execute_next_task",
      "instruction": "继续执行下一步低敏资料补齐任务。"
    },
    "policy": {
      "contentScope": "device_summary_only",
      "privacyBoundary": "summary_only_no_raw_media",
      "rawMediaPolicy": "explicit_user_upload_only",
      "eventIdExposed": false,
      "rawMediaIncluded": false
    }
  },
  "session": {
    "learningAllowed": true,
    "learned": true
  },
  "personaAutopilot": {
    "protocolVersion": "brainos.persona_evolution_command_center.v1",
    "targetPersonId": "self",
    "nextCycle": {
      "rawMediaAllowed": false
    }
  },
  "nextCycle": {
    "recommendedEndpoint": "/api/brain/device/collaboration-cycle",
    "shouldPullTasks": true,
    "personaAutopilot": {
      "protocolVersion": "brainos.persona_evolution_command_center.v1",
      "targetPersonId": "self"
    },
    "nextRunAfterMs": 20000
  },
  "executionPackage": {
    "version": "brainos.device.execution.v1",
    "claimedTask": {
      "taskId": "devtask_next",
      "area": "taboos"
    },
    "learningDirective": {
      "submitEndpoint": "/api/brain/device/tasks/devtask_next/result",
      "requiredFields": ["resultSummary"],
      "summaryOnly": true
    },
    "personaAutopilotDirective": {
      "protocolVersion": "brainos.persona_evolution_command_center.v1",
      "targetPersonId": "self",
      "policy": {
        "rawMediaIncluded": false
      }
    },
    "policy": {
      "privacyBoundary": "summary_only_no_raw_media",
      "serverDoesNotInventTaskResults": true
    }
  },
  "briefing": {
    "central": {
      "companionMode": "learning_companion"
    },
    "devicePolicy": {
      "contentScope": "summary_only"
    }
  }
}
```

设备侧应优先读取 `learningReceipt`，并在新版本设备上同步读取 `executionPackage` 和 `personaAutopilot`。`learningReceipt` 是低敏学习回执，用于判断本次任务是否真正进入学习、是否推动某个人格成长、是否同步到逝者/在世人物结构化资料；执行包用于直接决定下一步采集、回传、等待或调度节奏；`personaAutopilot` 用于把任务结果后的电子分身下一步学习目标接上，不需要设备额外查询中枢包。三者都不会暴露原始私密记忆、原始音频、原始视频或内部事件 ID。

## 字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| `eventId` | 否 | 外部事件唯一 ID；不传则由平台生成。 |
| `eventType` | 否 | `identity`、`relationship`、`preference`、`habit`、`memory`、`life_event`、`conversation`、`companion_session`、`observation`、`device_state`、`health_signal`。 |
| `title` | 是 | 事件标题，最多 120 字。 |
| `content` | 是 | 可学习内容，最多 1800 字。 |
| `payload` | 否 | 结构化原始数据。 |
| `consent` | 是 | `granted` 才允许进入学习；未授权会记录但不学习。 |
| `confidence` | 否 | 0 到 1 的置信度。 |
| `timestamp` | 否 | 毫秒时间戳。 |

## curl 示例

```bash
curl -X POST "https://n.hhtc.top/api/brain/ingest/device" \
  -H "Content-Type: application/json" \
  -H "X-BrainOS-Ingest-Key: bos_ing_xxx" \
  -d '{
    "eventId": "demo_001",
    "eventType": "preference",
    "title": "用户偏好",
    "content": "用户晚上更喜欢安静、短句、低延迟的陪伴式对话。",
    "consent": "granted",
    "confidence": 0.9
  }'
```

批量同步摘要：

```bash
curl -X POST "https://n.hhtc.top/api/brain/device/ingest/sync" \
  -H "Content-Type: application/json" \
  -H "X-BrainOS-Ingest-Key: bos_ing_xxx" \
  -d '{
    "events": [
      {
        "eventId": "demo_batch_001",
        "eventType": "preference",
        "title": "用户偏好",
        "content": "用户晚上更喜欢安静、短句、低延迟的陪伴式对话。",
        "consent": "granted",
        "confidence": 0.9
      }
    ]
  }'
```

读取简报：

```bash
curl -X GET "https://n.hhtc.top/api/brain/device/briefing" \
  -H "X-BrainOS-Ingest-Key: bos_ing_xxx"
```

请求数字人格实时回复：

```bash
curl -X POST "https://n.hhtc.top/api/brain/device/companion-reply" \
  -H "Content-Type: application/json" \
  -H "X-BrainOS-Ingest-Key: bos_ing_xxx" \
  -d '{
    "sessionId": "demo_reply_001",
    "personId": "self",
    "userText": "我今天有点累，想听你简单陪我说两句。",
    "context": "客厅终端低延迟陪伴测试",
    "mode": "realtime_companion",
    "consent": "granted"
  }'
```

回传陪伴会话：

```bash
curl -X POST "https://n.hhtc.top/api/brain/device/session" \
  -H "Content-Type: application/json" \
  -H "X-BrainOS-Ingest-Key: bos_ing_xxx" \
  -d '{
    "sessionId": "demo_session_001",
    "userText": "我今天有点累。",
    "assistantText": "我在，你慢慢说。",
    "outcome": "用户继续停留对话。",
    "learningNotes": ["疲惫时偏好短句陪伴"],
    "consent": "granted",
    "confidence": 0.82
  }'
```

## 中枢网络运行态端点

登录工作台读取完整运行态：

```http
GET https://n.hhtc.top/api/brain/network/operating-status
Authorization: Bearer <token>
```

设备读取低敏运行态：

```http
GET https://n.hhtc.top/api/brain/device/network/operating-status
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点用于判断一个家庭、医院、小程序、网站或硬件节点网络当前处于什么运行阶段：未接入、已注册离线、数据采集中、学习陪伴网、实时陪伴网。它聚合 `central-status`、`federation/topology`、`fleet/health` 和 `persona-runtime-profiles`，给设备或运营后台返回可执行的下一步动作。

关键字段：

| 字段 | 说明 |
|------|------|
| `operatingMode` | 网络运行模式：`not_connected`、`offline_registered`、`data_collection_network`、`learning_companion_network`、`realtime_companion_network`。 |
| `summary.operatingScore` | 综合运行分，结合中枢成熟度、设备健康、在线率、学习吞吐和风险压力。 |
| `summary.throughputScore` | 学习吞吐分，反映事件、已学习摘要、任务完成和积压情况。 |
| `summary.safetyRiskScore` | 隐私/授权风险压力，待确认事件、未授权源、需关注设备和摄像头能力都会抬高该值。 |
| `realtimeCoverage` | 实时能力覆盖：`voiceInput`、`voiceOutput`、`camera`、`screen`、`health`。 |
| `groupOperations` | 家庭/房间/医院区域等设备组运行画像，包含在线数、健康分、推荐角色和下一步。 |
| `priorityNodes` | 优先关注节点，只返回设备状态、能力、任务计数和下一步动作。 |
| `nextActions` | 下一步动作，如创建首个节点、恢复心跳、确认学习队列、领取设备任务、补语音输入/输出。 |

安全边界：运行态只返回在线率、设备能力、任务/学习计数、风险分和下一步动作；不返回原始照片、音频、视频、聊天全文或完整私密记忆。设备端默认应优先调用 `/api/brain/device/collaboration-cycle`，低能力硬件也能完成心跳、任务、摘要回传和简报刷新。

## 中枢自动协作派发计划端点

登录工作台读取完整派发计划：

```http
GET https://n.hhtc.top/api/brain/network/dispatch-plan
Authorization: Bearer <token>
```

登录工作台执行一次低风险派发：

```http
POST https://n.hhtc.top/api/brain/network/dispatch-plan/run
Authorization: Bearer <token>
Content-Type: application/json

{
  "maxTasksPerSource": 2,
  "reason": "sync_panel_network_dispatch"
}
```

设备读取自己的低敏派发计划：

```http
GET https://n.hhtc.top/api/brain/device/network/dispatch-plan
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点把 `中枢网络运行态`、`自动成长巡检` 和 `设备任务自动规划` 组合为一份可执行派发计划。它用于告诉家庭终端、小程序、网站、医院终端或智能硬件：下一步应该保持心跳、领取任务、补齐某个人格缺口、执行低打扰陪伴，还是等待用户确认记忆队列。

关键字段：

| 字段 | 说明 |
|------|------|
| `dispatchMode` | 当前派发模式，如 `pull_queued_tasks`、`collect_persona_gap`、`auto_plan_low_risk_tasks`、`steady_heartbeat`。 |
| `summary.assignments` | 本轮建议派发项数量。 |
| `summary.blocked` | 阻塞项数量，如无在线设备、待确认记忆、缺少语音输入/输出。 |
| `assignments` | 派发给设备的低敏任务建议，包含设备、任务类型、优先级、端点和摘要级指令。 |
| `blocked` | 中枢不能继续自动推进的原因和用户/设备需要处理的动作。 |
| `nextEndpoints` | 设备下一步可调用的标准端点，如任务领取、协作循环、任务结果回传。 |

安全边界：派发计划只返回设备能力、任务类型、低敏指令和端点；不返回原始照片、视频、音频、聊天全文或完整私密记忆。`/run` 只会调用既有低风险设备任务自动规划；记忆确认、原始媒体上传、高敏身份事实和在世人物授权必须由用户确认。

## 万户试点验收端点

登录工作台读取完整试点验收：

```http
GET https://n.hhtc.top/api/brain/pilot-readiness
Authorization: Bearer <token>
```

设备读取自己的低敏试点验收：

```http
GET https://n.hhtc.top/api/brain/device/pilot-readiness
X-BrainOS-Ingest-Key: bos_ing_xxx
```

该端点是家庭、医院、小程序、网站和智能设备进入真实试点前的总闸门。它聚合联邦拓扑、设备群健康、网络运行态、中枢派发计划和自动成长守护，给出“是否可进入试点”的分数、阻塞门槛和下一步动作。

关键字段：

| 字段 | 说明 |
|------|------|
| `status` | `pilot_ready`、`pilot_preparing` 或 `pilot_bootstrap`。 |
| `summary.pilotScore` | 试点综合分，来自接入节点、在线协作、学习闭环、人格运行、实时陪伴、派发、自动进化和隐私边界。 |
| `gates` | 试点门槛列表，包含 `first_nodes_connected`、`online_collaboration`、`learning_loop`、`persona_runtime`、`realtime_presence`、`dispatch_ready`、`autonomous_evolution`、`privacy_boundary`。 |
| `nextActions` | 当前最应该做的动作，如恢复心跳、补语音输入/输出、确认学习队列、领取任务、扩展下一户。 |
| `network` | 运行态、派发、设备群健康和自动成长守护的摘要。 |
| `policy` | 试点边界：摘要验收、逐户授权、原始媒体必须显式上传。 |

安全边界：试点验收只汇总节点数、在线率、学习计数、派发状态、自动进化状态和隐私边界；不返回原始照片、视频、音频、聊天全文或完整私密记忆。`pilot_ready` 只表示当前网络具备进入小范围试点的条件，不代表可以自动采集一切数据；每个家庭、医院、小程序、网站和在世/逝者人物资料都必须逐一授权。

试点验收成功返回示例：

```json
{
  "success": true,
  "status": "pilot_preparing",
  "statusLabel": "试点准备中",
  "summary": {
    "pilotScore": 66,
    "blockerCount": 2,
    "nodeCount": 3,
    "onlineCount": 2,
    "learnedEvents": 18,
    "pendingReview": 1,
    "assignments": 2
  },
  "gates": [
    {
      "id": "learning_loop",
      "label": "学习闭环",
      "passed": true,
      "score": 82,
      "evidence": "已学习 18 / 事件 22",
      "nextAction": "继续回传授权摘要并处理待确认队列。"
    }
  ],
  "nextActions": [
    {
      "priority": 1,
      "gateId": "realtime_presence",
      "title": "实时陪伴能力",
      "instruction": "补齐扬声器/TTS 输出节点。",
      "endpoint": "/api/brain/device/heartbeat"
    }
  ],
  "policy": {
    "contentScope": "device_summary_only",
    "privacyBoundary": "试点验收只汇总节点数、在线率、学习计数、派发状态、自动进化状态和隐私边界；不返回原始照片、视频、音频、聊天全文或完整私密记忆。"
  }
}
```

## 万户接入包端点

该端点把外部节点接入所需的启动清单、自检、协作循环、学习回执、派发计划、试点验收和隐私边界聚合成一份结构化包。它适合招商演示、医院终端接入、家庭中枢部署、小程序后端和网站后端接入，不要求对方先理解全部分散接口。

登录工作台端点：

```http
GET https://n.hhtc.top/api/brain/network/onboarding-package
Authorization: Bearer <token>
```

设备安全端点：

```http
GET https://n.hhtc.top/api/brain/device/network/onboarding-package
X-BrainOS-Ingest-Key: <ingest_key>
```

核心返回字段：

| 字段 | 说明 |
|------|------|
| `packageVersion` | 当前接入包版本，如 `network-onboarding-v1`。 |
| `role` | `workspace_operator` 或 `device_node`。 |
| `endpoints` | 工作台和设备侧启动、自检、心跳、协作循环、学习回执、派发、试点验收端点。 |
| `startupSequence` | 从创建接入源到协作循环、学习反馈、试点验收的顺序。 |
| `collaborationCycle` | 一键协作循环契约：心跳、拉任务、任务结果摘要、陪伴会话摘要。 |
| `learningReceiptContract` | 学习回执字段、摘要学习、授权要求和原始媒体策略。 |
| `acceptanceEvidence` | 当前网络、设备群、派发、试点、自动进化的验收证据。 |
| `personaAutopilot` | 设备安全的电子分身自动学习行动包：目标人物、学习账本、下一步动作、下一轮协作端点和安全边界。 |
| `goLiveChecklist` | 上线前必须检查的接入源、心跳、协作、学习、试点、隐私边界。 |
| `privacyBoundary` | 默认不返回原始照片、视频、音频、聊天全文或完整私密记忆；原始媒体必须显式上传或授权。 |

前端 SDK：

```js
const workspacePackage = await window.__brainExternalIngest.networkOnboardingPackage();
const devicePackage = await window.__brainExternalIngest.fetchDeviceNetworkOnboardingPackage(ingestKey);
const action = window.__brainExternalIngest.resolveDeviceNextCycleAction(devicePackage);
```

`resolveDeviceNextCycleAction(devicePackage)` 会自动读取 `devicePackage.personaAutopilot`，输出标准化的 `action.actions`、`action.recommendedEndpoint`、`action.nextRunAfterMs`、`action.shouldRunPersonaEvolutionCycle`、`action.shouldSubmitTaskSummary`、`action.shouldAskUserConfirmation` 和 `action.rawMediaForbidden`。设备可以直接展示“电子分身下一步”，但在需要账本确认、真实用户摘要或真实任务摘要时必须暂停自动运行，等待用户或设备现场产生低敏摘要。

## 万户扩户计划端点

用于招商、家庭复制、医院试点、小程序/网站接入前的下一步决策。它不会返回原始照片、视频、音频、聊天全文或完整私密记忆，只返回扩户分数、推荐目标、能力缺口、邀请码/接入源端点和验收摘要。

登录工作台端点：

```http
GET https://n.hhtc.top/api/brain/network/expansion-plan
Authorization: Bearer <token>
```

设备安全端点：

```http
GET https://n.hhtc.top/api/brain/device/network/expansion-plan
X-BrainOS-Ingest-Key: <ingest_key>
```

两个端点都支持 `?personId=xxx`。传入具体人物后，`firstLearningLoop.authorizationGate` 会基于数字人格授权护照判断该人物是否允许设备首轮学习。

核心返回字段：

| 字段 | 说明 |
|------|------|
| `protocolVersion` | 当前协议版本：`brainos.network_expansion_plan.v1`。 |
| `status/statusLabel` | 当前是否可复制扩户、准备下一站或先打通第一户。 |
| `summary` | 扩户分数、下一扩展类型、节点数、在线数、有效邀请、协作成员、试点分数。 |
| `targets` | 推荐接入目标：家庭终端、家属 App/小程序、智能音箱/摄像头、小程序后端、网站后端、医院终端。 |
| `launchSequence` | 从选择目标、创建邀请码/接入源、运行协作循环、首轮自动学习到试点验收的步骤。 |
| `firstLearningLoop` | 新节点接入后的首轮学习包，协议版本为 `brainos.network_first_learning_loop.v1`，说明围绕哪个人物、问什么问题、调用哪些端点、如何只回传低敏摘要。 |
| `firstLearningLoop.authorizationGate` | 授权护照硬门禁：`allowed=false` 时设备只能提示补授权，不能调用 session 回传学习摘要。 |
| `firstLearningLoop.canStartFirstLearning` | 是否可真正启动扩户首轮学习，必须同时满足授权通过和允许设备摘要采集。 |
| `inviteGuidance` | 家属加入网络的邀请码端点、默认角色、有效期和权限边界。 |
| `sourceGuidance` | 外接设备、小程序、网站后端创建接入源和运行协作循环的端点。 |
| `acceptanceEvidence` | 接入包检查项、试点门槛、成员分组统计。 |
| `policy` | 摘要边界、原始媒体策略、授权边界和电子分身安全声明。 |

### 授权成员代理邀请

主家庭可以在成员权限工作台开启某个成员的 `can_invite`。开启后，该成员可以代表主家庭继续生成万户互联邀请码，把另一位家属、照护者、医院终端或小程序协作方加入同一个主脑网络。

```http
POST https://n.hhtc.top/api/brain/network/invite
Authorization: Bearer <member_token>
Content-Type: application/json

{
  "networkOwnerId": "<owner_user_id>",
  "groupName": "成员代理扩户家庭"
}
```

权限边界：

- 请求者必须已经是 `networkOwnerId` 对应主家庭的成员。
- 成员状态必须是 `active`，且 `can_invite=1`；暂停成员或关闭邀请权限会返回 `403`。
- 新加入成员仍默认只能贡献授权摘要，不能查看完整私密记忆。
- 邀请包只返回 `inviteCode`、`inviteUrl`、`networkOwnerId`、`createdByUserId`、`createdByMemberId`、`delegated`、有效期和摘要级策略，不返回原始照片、音频、视频或完整私密记忆。

### 授权成员直接贡献摘要

加入主家庭网络后，成员不需要拿设备接入密钥，也可以用自己的登录身份向主脑提交授权摘要。该接口只写入主家庭的学习确认队列，默认等待主人审计；不会返回完整私密记忆，也不会接收原始照片、音频、视频或媒体链接。

#### 1. 读取成员贡献学习包

成员端、小程序、医院协作端或网站节点可以先读取下一轮学习简报，知道应该围绕哪个人物问什么问题、怎样提交低敏摘要。

```http
GET https://n.hhtc.top/api/brain/network/contribution-package?networkOwnerId=<owner_user_id>&personId=self
Authorization: Bearer <member_token>
```

返回摘要：

```json
{
  "success": true,
  "protocolVersion": "brainos.network_member_learning_brief.v1",
  "networkOwnerId": "<owner_user_id>",
  "selectedPersona": {
    "personId": "self",
    "displayName": "我 / 主脑",
    "readinessScore": 42,
    "stage": "learning"
  },
  "learningFocus": {
    "area": "memories",
    "label": "长期记忆",
    "question": "请讲一个你和这个人真实相处的小故事，越具体越好。",
    "summaryOnly": true,
    "rawMediaPolicy": "summary_only_no_raw_media"
  },
  "contributionState": {
    "total": 3,
    "pendingReview": 1,
    "learned": 2,
    "nextAction": "submit_next_authorized_summary"
  },
  "submissionTemplate": {
    "endpoint": "/api/brain/network/contribution",
    "method": "POST"
  }
}
```

该学习包只返回下一步问题、覆盖度计数、贡献统计和提交模板；不返回完整私密记忆、原始照片、音频、视频或聊天全文。

#### 2. 提交授权摘要

```http
POST https://n.hhtc.top/api/brain/network/contribution
Authorization: Bearer <member_token>
Content-Type: application/json

{
  "networkOwnerId": "<owner_user_id>",
  "personId": "self",
  "eventType": "memory",
  "title": "家庭成员授权摘要",
  "content": "只填写经过本人或合法授权整理后的低敏摘要，不上传原始照片、音频、视频或私密全文。",
  "confidence": 0.86,
  "consent": "granted",
  "payload": {
    "summaryOnly": true,
    "contentScope": "summary_only",
    "privacyBoundary": "summary_only_no_raw_media",
    "rawMediaIncluded": false
  }
}
```

返回摘要：

```json
{
  "success": true,
  "protocolVersion": "brainos.network_member_contribution.v1",
  "inserted": 1,
  "eventId": "ing_xxx",
  "networkOwnerId": "<owner_user_id>",
  "memberId": 12,
  "reviewStatus": "pending",
  "learningAllowed": false,
  "nextLearningBrief": {
    "protocolVersion": "brainos.network_member_learning_brief.v1",
    "learningFocus": {
      "question": "下一轮低敏追问"
    },
    "summaryOnly": true
  },
  "policy": {
    "contentScope": "summary_only",
    "privacyBoundary": "summary_only_no_raw_media",
    "rawContentReturned": false,
    "rawMediaIncluded": false,
    "privateMemoryAccess": false,
    "ownerReviewRequired": true
  }
}
```

权限和安全边界：

- 请求者必须是 `networkOwnerId` 对应主家庭的 active 成员，且 `can_contribute=1`。
- 暂停成员返回 `403/member_not_active`，关闭贡献权限返回 `403/member_contribution_disabled`。
- `payload`、`content`、`title` 中出现照片、音频、视频、base64、媒体 URL 或文件 URL 会返回 `400/raw_media_blocked`。
- 即使成员声明 `consent=granted`，事件仍先进入 `pending` 队列；主人确认或可信自动采纳后才写入长期人格/记忆。
- 系统会为成员建立内部 `network_member/member-<id>` 贡献源，用于贡献审计和可信自动采纳，不会把设备密钥返回给成员。
- 审计和回执只返回成员、来源、状态、置信度和时间等元数据，不返回成员提交的原始摘要正文。
- 成员贡献学习包和提交回执都会给下一轮低敏追问，形成“读简报 -> 现场授权摘要 -> 提交 -> 主人审计/可信采纳 -> 再读下一轮”的自动学习闭环。

#### 3. 贡献者可信画像与自动采纳雷达

主人工作台可读取贡献审计，判断哪些家庭成员、设备源、小程序或网站节点可以继续自动学习，哪些必须先人工确认。

```http
GET https://n.hhtc.top/api/brain/network/contribution-audit?personId=self&recentLimit=8
Authorization: Bearer <owner_token>
```

返回中会包含：

- `trustProfiles.protocolVersion = brainos.network_contributor_trust_radar.v1`
- `members[].trustProfile.protocolVersion = brainos.network_contributor_trust_profile.v1`
- `sources[].trustProfile.protocolVersion = brainos.network_contributor_trust_profile.v1`
- `trustScore`：0-100 分，综合已学习数、待确认压力、忽略数、授权状态、成员权限和来源授权。
- `trustTier`：`trusted`、`growing`、`needs_review`、`review_pressure`、`authorization_needed`、`paused`、`cold_start`。
- `autoReviewEligible`：是否可进入高置信摘要自动采纳候选。
- `nextContributionAction`：下一步动作，如 `auto_review_high_confidence_summaries`、`owner_review_pending_summaries`、`confirm_source_authorization`。

可信画像只返回计数、评分、权限状态和下一步动作，不返回原始摘要正文、照片、音频、视频或完整私密记忆。自动采纳仍要求：来源 active 且授权 granted、成员 active 且 `can_contribute=1`、摘要边界为 `summary_only_no_raw_media`、无原始媒体、置信度达到阈值。

前端 SDK：

```js
const expansionPlan = await window.__brainExternalIngest.networkExpansionPlan();
const deviceExpansionPlan = await window.__brainExternalIngest.fetchDeviceNetworkExpansionPlan(ingestKey);
const action = window.__brainExternalIngest.resolveDeviceNextCycleAction(deviceExpansionPlan);

if (action.networkFirstLearningLoop) {
  // 新家庭/新设备接入后的首轮自动学习包：
  // action.networkFirstLearningLoop.targetPersonId / firstQuestion / endpoints.session
  // action.networkFirstLearningAuthorizationGate.allowed 必须为 true 才能启动 session。
  // 设备仍必须采集真实用户授权摘要，不能伪造回答，不能自动上传原始音视频。
}

const memberPackage = await window.__brainExternalIngest.getNetworkContributionPackage({
  networkOwnerId: '<owner_user_id>',
  personId: 'self',
});

await window.__brainExternalIngest.submitNetworkContribution({
  networkOwnerId: '<owner_user_id>',
  personId: 'self',
  eventType: 'memory',
  title: '家庭成员授权摘要',
  content: '低敏摘要文本',
  confidence: 0.86,
  consent: 'granted',
  payload: {
    summaryOnly: true,
    privacyBoundary: 'summary_only_no_raw_media',
    rawMediaIncluded: false,
  },
});
```

成员端也可以直接调用一键循环 SDK，把“读简报 -> 现场生成授权摘要 -> 提交 -> 返回下一轮追问”封装成一次调用：

```js
const cycle = await window.__brainExternalIngest.runNetworkMemberContributionCycle(
  {
    networkOwnerId: '<owner_user_id>',
    personId: 'self',
  },
  {
    contributionBuilder: async (brief) => ({
      eventType: 'memory',
      title: `${brief.selectedPersona?.displayName || '目标人物'} 家庭成员授权摘要`,
      content: '成员现场确认的低敏生活摘要，只写总结，不上传原始照片、音频、视频或聊天全文。',
      confidence: 0.86,
      consent: 'granted',
    })
  }
);

console.log(cycle.nextLearningBrief?.learningFocus?.question);
```

`runNetworkMemberContributionCycle()` 的固定边界：

- 先调用 `/api/brain/network/contribution-package` 读取下一轮低敏学习问题和提交模板，不返回完整私密记忆。
- 必须由 `contributionBuilder`、`contribution`、`summary` 或 `content` 提供真实授权摘要；没有摘要时返回 `network_member_summary_required`。
- 检测到 `rawAudio`、`rawVideo`、`rawImage`、`audioBase64`、`videoBase64`、`imageBase64`、`blob` 等原始媒体字段时返回 `raw_media_forbidden`。
- 自动补齐 `summaryOnly=true`、`contentScope=summary_only`、`privacyBoundary=summary_only_no_raw_media`、`rawMediaIncluded=false`。
- 提交结果仍默认进入主人审计或可信自动采纳流程，不让成员直接写入长期人格，也不开放完整私密记忆。

设备 SDK 可以直接执行授权后的首学闭环：`runDeviceNetworkFirstLearningLoop(ingestKey, params, options)`。

```js
const result = await window.__brainExternalIngest.runDeviceNetworkFirstLearningLoop(
  ingestKey,
  { personId: 'self' },
  {
    sessionSummaryBuilder: async (firstLearningLoop) => ({
      personId: firstLearningLoop.targetPersonId || 'self',
      userText: '用户现场确认：希望家庭终端以后用低敏生活摘要帮助电子分身学习。',
      assistantText: 'BrainOS 已收到授权摘要，本次只用于电子人格学习。',
      learningNotes: ['用户确认家庭终端可做低敏陪伴学习'],
      consent: 'granted',
      confidence: 0.86
    })
  }
);
```

`runDeviceNetworkFirstLearningLoop()` 会按顺序读取扩户计划、检查 `firstLearningLoop.authorizationGate`、发送心跳、调用 `/api/brain/device/session` 回传首条低敏摘要，再调用 `/api/brain/device/collaboration-cycle` 刷新后续协作循环。它有三个硬边界：

- `authorizationGate.allowed !== true`、`canStartFirstLearning=false` 或 session 模板被禁用时，返回 `persona_authorization_required`，不会回传学习摘要。
- 没有真实 `userText`、`assistantText`、`content`、`summary` 或 `learningNotes` 时，返回 `network_first_learning_summary_required`，设备不能替用户编造首学内容。
- 检测到 `rawAudio`、`rawVideo`、`rawImage`、`audioBase64`、`videoBase64`、`imageBase64`、`blob` 等原始媒体字段时，返回 `raw_media_forbidden`，只允许低敏摘要。

`firstLearningLoop` 示例：

```json
{
  "protocolVersion": "brainos.network_first_learning_loop.v1",
  "targetId": "home_terminal",
  "targetLabel": "家庭陪伴终端",
  "targetPersonId": "self",
  "targetDisplayName": "self",
  "authorizationGate": {
    "allowed": true,
    "status": "authorized",
    "canAutoLearn": true,
    "canDeviceCollectSummary": true,
    "endpoint": "/api/brain/device/persona-authorization-passport"
  },
  "canStartFirstLearning": true,
  "firstQuestion": "围绕 self 采集一条用户明确授权的低敏生活摘要。",
  "endpoints": {
    "session": "/api/brain/device/session",
    "collaborationCycle": "/api/brain/device/collaboration-cycle",
    "learningFeedback": "/api/brain/device/learning-feedback"
  },
  "payloadTemplates": {
    "session": {
      "disabled": false,
      "personId": "self",
      "consent": "granted",
      "payload": {
        "summaryOnly": true,
        "privacyBoundary": "summary_only_no_raw_media"
      }
    },
    "collaborationCycle": {
      "includePersonaAutopilot": true,
      "includeNetworkExpansionPlan": true,
      "confirmPersonaAuthorization": false,
      "fetchLearningFeedback": true,
      "runPersonaEvolutionCycle": false
    }
  },
  "policy": {
    "rawMediaIncluded": false,
    "authorizationPassportRequired": true,
    "authorizationHardGate": true,
    "serverDoesNotInventTaskResults": true
  }
}
```

当 `authorizationGate.allowed=false` 或 `canStartFirstLearning=false` 时，设备必须先调用 `authorizationGate.endpoint` 或展示 `authorizationGate.nextAction.instruction`，不能自动执行扩户首学、声音克隆、头像驱动或人格进化循环。

设备接入最小顺序：

1. 读取 `/api/brain/device/network/onboarding-package`。
2. 读取 `/api/brain/device/bootstrap`，确认端点和自检规则。
3. 每 30 秒调用 `/api/brain/device/heartbeat` 上报在线状态和能力。
4. 调用 `/api/brain/device/self-test`，必要时调用 `/api/brain/device/self-test/remediate`。
5. 读取 `/api/brain/device/network/expansion-plan`，拿到 `firstLearningLoop`，明确首轮围绕哪个人物学习、问什么低敏问题。
6. 调用 `/api/brain/device/session`，只回传真实用户授权的首条低敏摘要。
7. 调用 `/api/brain/device/collaboration-cycle`，让设备完成心跳、拉任务、回传摘要、刷新简报，并继续带上 `includePersonaAutopilot=true`。
8. 读取 `/api/brain/device/learning-feedback`，确认学习回执和待确认状态。
9. 读取 `/api/brain/device/pilot-readiness`，检查是否达到家庭/医院/小程序/网站试点门槛。
10. 再次读取 `/api/brain/device/network/expansion-plan`，决定下一户、下一院区、小程序、网站或智能设备如何复制接入。

设备事件写入成功返回示例：

```json
{
  "success": true,
  "inserted": 1,
  "duplicate": false,
  "eventId": "demo_001",
  "sourceId": "livingroom-terminal",
  "learningAllowed": true
}
```

## 安全边界

- 接入密钥只显示一次，泄露后应在同步面板点击「换密钥」。
- 暂停或吊销接入源后，旧密钥会立即返回 `401`。
- 外部来源不得上传未授权的个人隐私、医疗数据、音视频原始内容。
- 死者/在世人物数据必须由合法授权人上传，并保留撤回能力。
- 设备简报只返回摘要，不返回完整私密记忆、原始音视频、聊天全文或敏感资料。
- 设备不得把简报当作本人真实在线或逝者真实复活的证明，只能作为陪伴策略参考。
- 陪伴会话回传只上传摘要和学习线索，不上传完整录音、完整视频、敏感医疗诊断或未经授权的第三方隐私。
- 设备任务只能包含低敏指令摘要；设备结果只回传执行摘要和学习线索，不上传未经授权的原始传感器流。

## 产品演示路径

1. 打开 `https://n.hhtc.top/app.html`。
2. 进入「认知 -> 同步」。
3. 创建一个「智能设备」接入源。
4. 复制一次性密钥，或直接点击「发送测试事件」。
5. 刷新后查看该接入源的事件数和学习数增长。
6. 打开 `https://n.hhtc.top/device-simulator.html`，填写密钥后点击「发送设备心跳」，验证主脑能识别设备在线和能力。
7. 读取 `/api/brain/device/network/onboarding-package` 或同步面板「万户接入包」，验证外部节点能看到启动、自检、协作、学习回执和试点验收清单。
8. 点击「读取中枢简报」，验证设备能读取当前主脑陪伴策略、在线状态和能力摘要。
9. 读取 `/api/brain/device/network/operating-status`，验证设备能看到自己所在家庭/区域的运行模式、实时陪伴覆盖、风险压力和下一步动作。
10. 读取 `/api/brain/device/pilot-readiness` 或同步面板「万户试点验收」，验证当前家庭/医院/小程序/网站网络是否达到试点门槛。
11. 点击「发送一次」，再点击「读取学习反馈」，验证设备能看到已学习、待确认和最近事件。
12. 点击「请求数字人格回复」，验证设备能把现场一句话交给平台数字人格，并得到回复、语音策略、头像策略和学习策略。
13. 点击「回传陪伴会话」，验证设备能把刚才的回复转成摘要写回主脑学习队列，并触发人格画像/自动巩固更新。
14. 主脑通过 `/api/brain/device/tasks/auto-plan` 自动编排任务，或通过 `/api/brain/device/tasks` 手动创建任务。
15. 在模拟器点击「领取主脑任务」和「完成当前任务」，验证主脑主动调度闭环。