# 智念桌面端 PRD（YINIAN Hotel Desktop）

> **版本：** v0.3（完整草案）  
> **状态：** 第一至九章与附录已补齐，进入评审与拆票阶段  
> **上次更新：** 2026-04-26  
> **代号：** YINIAN · 内部用 yinian-desktop

---

## 目录与推进议程

| 章节 | 主题 | 状态 |
|---|---|---|
| 第一章 | 产品概述 | ✅ 已成稿 |
| 第二章 | 系统架构 | ✅ 已成稿 |
| 第三章 | 领域模型与端口契约（`kernel-core`）| ✅ 已成稿 |
| 第四章 | YINIAN Skill Spec v0.1 | ✅ 已成稿 |
| 第五章 | 客户端模块设计（Main / Renderer 各模块）| ✅ 草案已补齐 |
| 第六章 | 服务端 API 契约 | ✅ 草案已补齐 |
| 第七章 | Skills v1 详细设计 | ✅ 草案已补齐 |
| 第八章 | 非功能性要求（安全 / 性能 / 端口检测 / 离线 / 可观测性）| ✅ 草案已补齐 |
| 第九章 | 里程碑、交付计划与风险登记册 | ✅ 草案已补齐 |
| 附录 A | 术语表 | ✅ 草案已补齐 |
| 附录 B | OpenClaw 上游同步策略 | ✅ 草案已补齐 |
| 附录 C | CI 强制规则清单 | ✅ 草案已补齐 |

---

# 第一章 · 产品概述

## 1.1 产品定位

**智念桌面端**（YINIAN Hotel Desktop）是面向中国酒店运营场景的 AI Agent 桌面客户端。它把 AI Agent 的能力封装成"装在前台 / 财务 / 运营那台电脑里的工具"——零配置、零学习曲线、登录即用。

技术上采用 **壳-核-能力包** 三段式架构：

- **壳（Shell）** = 桌面 UI + 登录态 + 本地存储 + 通知
- **核（Kernel）** = Agent runtime（当前 OpenClaw，可替换）
- **能力包（Skills）** = 酒店行业 know-how 编码而成的可执行单元

三段之间通过明确的端口契约解耦，确保 **核可以替换、能力包可以跨平台复用、UI 可以独立演进**。

## 1.2 目标用户

| 角色 | 核心特征 | 与本产品的关系 |
|---|---|---|
| 酒店前台 / 运营 | 普通办公能力、不懂技术、工作高频重复 | 日常使用者，主要交互对象 |
| 酒店店长 / 老板 | 看数据做决策、不会每天打开 | 价值确认者，看每日 / 每周推送 |
| NIANXX 实施 / 客成 | 需要远程开通、远程诊断 | 间接用户，运维入口 |

## 1.3 核心价值主张

**对酒店：** 把"原本需要 1 名运营每天 2-3 小时的 OTA 巡检 / 早报整理 / 客评回复"压缩到 **5 分钟**（看推送 + 处理异常）。

**对 NIANXX：** 每个酒店客户的运营 know-how 沉淀为 **可复用、可升级、可跨内核移植** 的 skill 资产，构成长期护城河。Skills 是产品的真正 IP，桌面壳只是当下的最佳载体。

## 1.4 与原 ClawX 的本质区别

智念桌面端基于 ClawX fork，但产品形态是另一个东西：

| 维度 | ClawX(上游) | 智念桌面端 |
|---|---|---|
| 用户画像 | 开发者 / 极客 | 酒店运营 / 老板 |
| 配置心智 | 自填 API key + 装 skill | 登录即用、零配置 |
| Skill 来源 | 用户自由浏览安装 | 服务端按客户等级远程下发 |
| Provider / Key | 用户自管 | NIANXX 服务端代理，前端无 key |
| 数据归属 | 全部本地 | 本地优先 + 云端选择性同步 |
| 内核耦合 | UI 直接调 OpenClaw RPC | 通过 Adapter 隔离，可替换 |
| 视觉调性 | 通用 dev tool | 高端 SaaS（白底 + 单一品牌蓝 #1A56DB）|
| 通知通道 | 50+ 全开放 | 继承 OpenClaw 全部通道 + NIANXX 自建渠道 |

## 1.5 不做什么（防 scope creep）

- **不做酒店 PMS** —— 不与西软、绿云正面冲突，专注 AI Agent 工具层
- **不做客户私有部署** —— v1 阶段统一 SaaS 模式
- **不做开发者 Marketplace** —— skill 由 NIANXX 集中维护与下发
- **不做手机端** —— 单点突破桌面办公场景，移动端通过企微 / 钉钉接收推送
- **不做通用对话助手** —— 所有能力围绕"酒店运营任务"组织
- **不暴露 API Key 配置** —— 所有 LLM 调用走服务端代理，客户端永不持有 key

---

# 第二章 · 系统架构

## 2.1 四层洋葱模型

```
┌──────────────────────────────────────────────┐
│  Vertical Layer · 业务垂直层                  │
│  酒店 skill / 报表 / 数据回流                  │
├──────────────────────────────────────────────┤
│  Shell Layer · 桌面壳 / UI                    │
│  React 渲染层，零内核依赖                      │
├──────────────────────────────────────────────┤
│  Adapter Layer · 适配器(关键解耦点)           │
│  把领域指令翻译成内核 RPC                      │
├──────────────────────────────────────────────┤
│  Kernel Layer · Agent 内核                    │
│  当前 OpenClaw，可替换                         │
└──────────────────────────────────────────────┘
```

**核心原则：每一层只能依赖更深的层，不能反向依赖。**

Adapter 是这套架构最关键的一层——它的存在意味着：UI 写成什么样，跟内核换不换没关系；内核换了，UI 不用动。

## 2.2 四个核心端口（Port）

智念桌面端的所有能力围绕四个端口组织。Shell 只与端口对话，端口由 Adapter 提供具体实现。

### Port 1 · ConversationPort
对话与消息流。Shell 操作：发消息、订阅消息流、订阅工具调用、订阅 artifact 输出。

### Port 2 · SkillPort
技能注册与执行。Shell 操作：列出已开通技能、触发技能、订阅技能执行进度、查看历史执行记录。

### Port 3 · SchedulerPort
定时与触发。Shell 操作：增删改查 cron 任务、查看执行历史、临时禁用 / 启用。

### Port 4 · NotificationPort
对外通知派发。Shell 操作：发现可用通道、发送通知、订阅送达状态。**采用"通道发现 + 派发"模式**——通道列表由内核动态提供，`kind` 字段为开放字符串，Shell 不写死任何通道枚举。

> 详细的 TypeScript 接口签名见 **第三章**。

## 2.3 进程模型

```
┌──────────────────────────────────────────────────────────────┐
│                  智念桌面端 (Electron App)                    │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │           Electron Main Process                         │ │
│  │  • 窗口与生命周期                                         │ │
│  │  • Auth 模块（token 管理 / keychain 存储）                │ │
│  │  • Config Sync 模块（与 NIANXX 服务端通信）               │ │
│  │  • Skill Manager（拉取 / 写入 skill bundle）              │ │
│  │  • Kernel Lifecycle（OpenClaw Gateway 子进程管理）        │ │
│  │  • Port Detection（端口冲突检测与处理）                    │ │
│  │  • Notification Bridge（系统托盘 + OS 通知）              │ │
│  └─────────────────────┬──────────────────────────────────┘ │
│                        │ IPC (contextBridge)                 │
│  ┌─────────────────────▼──────────────────────────────────┐ │
│  │           Renderer Process (React 19)                  │ │
│  │  • 全部 UI                                              │ │
│  │  • 通过 kernel-context 注入的 Port 访问能力              │ │
│  │  • 不直接 import OpenClaw 任何 API 或类型                │ │
│  └────────────────────────────────────────────────────────┘ │
└──────────────────────────────────┬──────────────────────────┘
                                   │ WebSocket (JSON-RPC)
                                   ▼
┌──────────────────────────────────────────────────────────────┐
│  OpenClaw Gateway(子进程) · 监听 127.0.0.1:18928             │
│  Agent runtime / Skill 执行 / Cron / Sandbox                  │
└──────────────────────────────────┬──────────────────────────┘
                                   │ HTTPS
                                   ▼
┌──────────────────────────────────────────────────────────────┐
│  NIANXX 服务端                                                 │
│  • Auth(登录 / token 刷新)                                    │
│  • Config Sync(用户 / 酒店 / agent 配置)                      │
│  • Skill Manifest(已开通技能清单 + bundle 下载链接)           │
│  • LLM Proxy(代理 OpenAI / Anthropic 调用 + 计费 + 脱敏)      │
│  • Data Sink(数据回流：执行结果、报表)                         │
│  • Custom Notification Channels(自建企微 / 钉钉 / 自定义)      │
└──────────────────────────────────────────────────────────────┘
```

### 关键设计点

1. **Gateway 由 Main 拉起子进程**，生命周期由 Main 管理。Main 退出时确保 Gateway 优雅关闭。
2. **Gateway 端口固定 127.0.0.1:18928**，与上游 ClawX 默认端口（18789）刻意错开，避免与原版 ClawX 共存冲突。Main 启动前执行端口检测协议（详见 §2.7）。
3. **Renderer 通过 WebSocket 连接 Gateway**（同机回环，性能 OK），连接地址与短期会话凭证由 Main 通过 `contextBridge` 下发，所有调用必须经过 Adapter 包装层。
4. **所有外部网络通信原则上由 Main 发起**（NIANXX 服务端、第三方 API），Renderer 不直接发出公网请求。
5. **LLM 调用全部走 NIANXX 服务端代理**：Gateway 配置中的 `OPENAI_BASE_URL` 指向 NIANXX 代理网关，**密钥永远不下发到客户端**。这一条是硬约束，不留客户自带 key 的口子。

## 2.4 Monorepo 包结构

使用 pnpm workspace：

```
yinian-desktop/
├── apps/
│   └── desktop/                       # 应用本体（原 ClawX 改造而来）
│       ├── electron/                  # Main 进程代码
│       └── src/                       # Renderer 代码
├── packages/
│   ├── kernel-core/                   # 领域类型 + Port 接口（零内核依赖）
│   ├── kernel-adapter-openclaw/       # OpenClaw 适配器
│   ├── kernel-context/                # 适配器注入与切换的统一入口
│   ├── skill-spec/                    # YINIAN Skill Spec 类型 + 编译器
│   ├── skills-hotel-core/             # 通用酒店 skill 基类与共享逻辑
│   ├── skills/
│   │   ├── ctrip-price-monitor/
│   │   ├── meituan-price-monitor/
│   │   ├── daily-report/
│   │   └── review-reply-helper/
│   └── ui-kit/                        # 设计 tokens + 公共组件
├── vendor/
│   └── openclaw/                      # OpenClaw submodule
├── docs/
│   └── PRD.md                         # 本文档
└── tools/
    └── eslint-rules/                  # 强制依赖方向的自定义规则
```

## 2.5 严格的依赖方向（CI 强制）

依赖图是单向的，由 ESLint `no-restricted-imports` + 自定义规则在 CI 强制：

| 包 / 路径 | 允许 import |
|---|---|
| `apps/desktop/src/`（renderer）| `@yinian/kernel-core`、`@yinian/kernel-context`、`@yinian/ui-kit`、`@yinian/skill-spec`；仅 `bootstrap.tsx` 可 import `@yinian/kernel-adapter-openclaw` |
| `apps/desktop/electron/`（main）| 上述 + `@yinian/kernel-adapter-openclaw` |
| `@yinian/kernel-core` | 仅纯工具库（zod、date-fns 等），**禁止** 任何内核相关依赖 |
| `@yinian/kernel-adapter-openclaw` | `@yinian/kernel-core` + OpenClaw SDK |
| `@yinian/kernel-context` | `@yinian/kernel-core` + 由调用方注入的具体 adapter |
| `@yinian/skills/*` | `@yinian/skill-spec` + `@yinian/skills-hotel-core` |

**违规视为 PR 红灯，不允许合并。** 这条规则比文档约定有效得多——它把"层级纪律"从一个口号变成了 CI 红灯。

## 2.6 Renderer 如何拿到 Port 实现：唯一的依赖注入点

整个系统中，**只有一个文件** 把"具体内核"和"应用"绑在一起：

```ts
// apps/desktop/src/bootstrap.tsx
import { createKernelContext } from '@yinian/kernel-context';
import { createOpenClawAdapter } from '@yinian/kernel-adapter-openclaw';

const endpoint = await window.yinian.app.getKernelEndpoint();

const kernel = createKernelContext({
  adapter: createOpenClawAdapter({
    wsUrl: endpoint.wsUrl,
    token: endpoint.token,
  }),
});

// 之后整个 React 树通过 useKernel() Hook 拿所有 Port
// 例如：const { conversation } = useKernel(); conversation.send(...)
```

**未来更换内核**只需要改这一个文件——把 `createOpenClawAdapter` 换成 `createXxxAdapter`，整个 UI 树不用动。

这是端口与适配器模式落地最关键的实操细节。所有"换内核"的承诺，最终都要兑现在这一个文件能不能干净地切换。

## 2.7 启动时序与端口检测

```
1.  用户打开应用
2.  Electron Main 启动
3.  Main 检查 keychain 中 token
       ├─ 无 / 过期 → 渲染 LoginPage（Gateway 暂不启动）
       └─ 有效     → 继续步骤 4
4.  Main 调用 NIANXX `/auth/me` 验证 token
5.  Main 拉取 `/config/sync`：用户 + 酒店 + agent 配置
6.  Main 拉取 `/skills/manifest`，比对本地版本
7.  Main 下载 / 更新需要的 skill bundle，写入 OpenClaw skills 目录
8.  Main 执行端口检测协议（127.0.0.1:18928）
       ├─ 未占用       → 启动 Gateway
       ├─ 占用且握手通过 → 是上次崩溃残留的我们的 Gateway，复用或 kill+重启
       └─ 占用但握手失败 → 进入"端口冲突"失败态 UI，引导用户处理
9.  Main 启动 OpenClaw Gateway 子进程（注入 NIANXX LLM proxy endpoint）
10. Main 健康检查 Gateway（轮询直到 ready）
11. Renderer 通过 kernel-context 建立连接，进入 MainAppPage
```

### 端口检测协议

为区分"占用 18928 的进程是不是我们自己"，定义两个本地端点：

- `GET http://127.0.0.1:18928/__yinian_probe__`：无需 token，只返回最小服务身份，用于端口占用识别
- `GET http://127.0.0.1:18928/__yinian_health__`：需要 Main 注入的 `healthToken`，返回详细健康状态

probe 响应：

  ```json
  { "service": "yinian-kernel-gateway", "version": "x.y.z", "started_at": <unix_ms> }
  ```

- Main 启动时先 GET probe 端点，3 秒超时
  - 200 + 正确 service 字符串 → 是我们的 Gateway，直接复用（或 kill 重启，按用户配置）
  - 任意其他响应 / 超时 / 连接拒绝 → 视为"被陌生进程占用"
- Main 启动或复用 Gateway 后，再用 `healthToken` 访问 health 端点确认 ready
- 失败态 UI 提供：识别占用进程（用 `lsof` / `netstat` 风格的系统命令）、一键终止、或选择临时使用 18929 备用端口

这个协议成本极低（两个 HTTP 端点 + 几十行检测逻辑），但能解决"用户机器上同时装了原版 ClawX"或"上次没干净退出"两个最常见的体验雷点。

## 2.8 此架构需要诚实承认的泄漏点

完美的内核无关性不存在。以下两处会有泄漏，提前画好红线：

### 泄漏点 1：Sandbox / 安全策略
OpenClaw 的 Docker sandbox 模式如果换到无 sandbox 的内核就没了。短期对策：sandbox 配置作为 Adapter 内部细节，不暴露给 Shell；长期看入风险登记册（第九章）。

### 泄漏点 2：流式输出语义差异
不同内核的 token 流式输出语义会有细微差异（中断恢复点、tool call 内嵌位置、reasoning block 格式等）。Adapter 必须把所有内核的输出归一到统一的 `ConversationStreamEvent` 类型，由 Adapter 吃掉差异。这是 Adapter 实现复杂度最高的部分，也是 Adapter 真正的价值所在。

> **关于通知通道**：v0.1 设计阶段曾考虑把通道收口为四类抽象，最终采用"通道发现 + 派发"模式（详见 §3.6）——继承内核全部通道 + 允许 NIANXX 服务端动态注册自建通道。这不算泄漏点，是有意设计。

---

# 第三章 · 领域模型与端口契约（kernel-core）

## 3.1 设计原则

`kernel-core` 是整个系统中**唯一不知道 OpenClaw 存在**的代码包。任何 PR 试图在 `kernel-core` 里 import OpenClaw、使用 OpenClaw 类型、或硬编码 OpenClaw 的 RPC 方法名，都直接 CI 红灯。

这一章定义的所有类型与接口，未来无论换到哪个内核，都不会改变。换内核 = 写一个新的 Adapter 包实现这些接口，仅此而已。

设计准则：

1. **领域语言优先** —— 用"对话"、"技能"、"任务"、"通知"，不用 agent / channel / session 等内核术语
2. **流式优先** —— 所有可能耗时的操作返回 `AsyncIterable<Event>`，不返回单个 Promise
3. **不可变快照** —— 跨进程边界的数据全部是 plain object（可被 JSON 序列化），不带类方法
4. **错误是值** —— 错误以 `KernelError` 类型显式建模，不依赖 throw / catch 跨进程
5. **零运行时依赖** —— 除 `zod`（schema 验证）、`date-fns`（日期处理）外不允许其他依赖

## 3.2 共享核心类型

```typescript
// === 标识与身份（Branded Types 防误用） ===

export type UserId         = string & { readonly __brand: 'UserId' };
export type HotelId        = string & { readonly __brand: 'HotelId' };
export type ConversationId = string & { readonly __brand: 'ConversationId' };
export type MessageId      = string & { readonly __brand: 'MessageId' };
export type SkillId        = string & { readonly __brand: 'SkillId' };
export type TaskId         = string & { readonly __brand: 'TaskId' };
export type ExecutionId    = string & { readonly __brand: 'ExecutionId' };

// === 用户与酒店 ===

export interface User {
  id: UserId;
  name: string;
  avatar?: string;
  email?: string;
  phone?: string;
  hotels: HotelMembership[];
}

export interface HotelMembership {
  hotelId: HotelId;
  role: 'owner' | 'manager' | 'staff' | 'viewer';
}

export interface Hotel {
  id: HotelId;
  name: string;
  brand?: string;
  city: string;
  ota: HotelOTABinding[];
}

export interface HotelOTABinding {
  ota: 'ctrip' | 'meituan' | 'booking' | 'agoda' | 'qunar' | string;
  externalId: string;        // 平台侧的酒店 ID
  enabled: boolean;
}

// === 消息与 Artifact ===

export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';

export interface Message {
  id: MessageId;
  conversationId: ConversationId;
  role: MessageRole;
  blocks: ContentBlock[];
  createdAt: number;          // unix ms
}

export type ContentBlock =
  | TextBlock
  | ToolCallBlock
  | ToolResultBlock
  | ArtifactBlock
  | ReasoningBlock;

export interface TextBlock      { type: 'text'; text: string }
export interface ReasoningBlock { type: 'reasoning'; text: string }

export interface ToolCallBlock {
  type: 'tool_call';
  toolCallId: string;
  name: string;
  input: Record<string, unknown>;
}

export interface ToolResultBlock {
  type: 'tool_result';
  toolCallId: string;
  status: 'success' | 'failed';
  output: unknown;
  error?: KernelError;
}

export interface ArtifactBlock { type: 'artifact'; artifact: Artifact }

export type Artifact =
  | { kind: 'markdown'; id: string; title?: string; content: string }
  | { kind: 'table';    id: string; title?: string; columns: string[]; rows: unknown[][] }
  | { kind: 'chart';    id: string; title?: string; spec: unknown }     // vega-lite spec
  | { kind: 'image';    id: string; title?: string; url: string }
  | { kind: 'file';     id: string; title?: string; url: string; mime: string };

// === 错误模型 ===

export interface KernelError {
  code: KernelErrorCode;
  message: string;
  retryable: boolean;
  cause?: unknown;
}

export type KernelErrorCode =
  | 'kernel_unavailable'
  | 'kernel_timeout'
  | 'kernel_aborted'
  | 'auth_required'
  | 'permission_denied'
  | 'skill_not_found'
  | 'skill_execution_failed'
  | 'invalid_input'
  | 'rate_limited'
  | 'unknown';
```

## 3.3 ConversationPort

```typescript
export interface ConversationPort {
  list(query?: { hotelId?: HotelId; limit?: number }): Promise<Conversation[]>;

  get(id: ConversationId): Promise<Conversation>;

  create(input: CreateConversationInput): Promise<Conversation>;

  delete(id: ConversationId): Promise<void>;

  /** 发送消息并订阅响应流 */
  send(input: SendMessageInput): AsyncIterable<ConversationStreamEvent>;

  /** 中止正在进行的消息流（流会以 error 事件结束，code = kernel_aborted） */
  abort(conversationId: ConversationId): Promise<void>;

  history(
    conversationId: ConversationId,
    opts?: { before?: MessageId; limit?: number }
  ): Promise<Message[]>;
}

export interface Conversation {
  id: ConversationId;
  title: string;
  hotelId: HotelId;
  createdAt: number;
  updatedAt: number;
  messageCount: number;
}

export interface CreateConversationInput {
  hotelId: HotelId;
  title?: string;
}

export interface SendMessageInput {
  conversationId: ConversationId;
  content:
    | TextBlock
    | { type: 'invoke_skill'; skillId: SkillId; input: Record<string, unknown> };
}

export type ConversationStreamEvent =
  | { type: 'message_start';     message: Pick<Message, 'id' | 'role' | 'createdAt'> }
  | { type: 'text_delta';        messageId: MessageId; delta: string }
  | { type: 'reasoning_delta';   messageId: MessageId; delta: string }
  | { type: 'tool_call';         messageId: MessageId; block: ToolCallBlock }
  | { type: 'tool_result';       messageId: MessageId; block: ToolResultBlock }
  | { type: 'artifact';          messageId: MessageId; artifact: Artifact }
  | { type: 'message_complete';  messageId: MessageId; message: Message }
  | { type: 'error';             error: KernelError };
```

## 3.4 SkillPort

```typescript
export interface SkillPort {
  list(hotelId: HotelId): Promise<InstalledSkill[]>;

  get(id: SkillId): Promise<InstalledSkill>;

  invoke(input: InvokeSkillInput): AsyncIterable<SkillExecutionEvent>;

  abort(executionId: ExecutionId): Promise<void>;

  history(skillId: SkillId, opts?: { hotelId?: HotelId; limit?: number }): Promise<SkillExecution[]>;

  getExecution(executionId: ExecutionId): Promise<SkillExecution>;
}

export interface InstalledSkill {
  id: SkillId;
  spec: SkillSpec;            // 见第四章
  enabled: boolean;
  installedAt: number;
  lastInvokedAt?: number;
}

export interface InvokeSkillInput {
  skillId: SkillId;
  hotelId: HotelId;
  input: Record<string, unknown>;
  triggeredBy: 'user' | 'schedule' | 'webhook' | 'reply';
}

export type SkillExecutionEvent =
  | { type: 'started';   executionId: ExecutionId; startedAt: number }
  | { type: 'progress';  executionId: ExecutionId; phase: string; ratio?: number; message?: string }
  | { type: 'log';       executionId: ExecutionId; level: 'info' | 'warn' | 'error'; message: string }
  | { type: 'artifact';  executionId: ExecutionId; artifact: Artifact }
  | { type: 'completed'; executionId: ExecutionId; output: Record<string, unknown>; finishedAt: number }
  | { type: 'failed';    executionId: ExecutionId; error: KernelError; finishedAt: number };

export interface SkillExecution {
  id: ExecutionId;
  skillId: SkillId;
  hotelId: HotelId;
  input: Record<string, unknown>;
  output?: Record<string, unknown>;
  artifacts: Artifact[];
  status: 'running' | 'success' | 'failed' | 'aborted';
  triggeredBy: InvokeSkillInput['triggeredBy'];
  startedAt: number;
  finishedAt?: number;
  error?: KernelError;
}
```

## 3.5 SchedulerPort

```typescript
export interface SchedulerPort {
  list(hotelId?: HotelId): Promise<ScheduledTask[]>;
  get(id: TaskId): Promise<ScheduledTask>;
  create(input: CreateTaskInput): Promise<ScheduledTask>;
  update(id: TaskId, patch: UpdateTaskPatch): Promise<ScheduledTask>;
  delete(id: TaskId): Promise<void>;
  pause(id: TaskId): Promise<void>;
  resume(id: TaskId): Promise<void>;
  history(id: TaskId, opts?: { limit?: number }): Promise<TaskExecutionRecord[]>;
}

export interface ScheduledTask {
  id: TaskId;
  hotelId: HotelId;
  name: string;
  cron: string;               // 标准 5 字段 cron 表达式
  timezone: string;           // IANA 时区，如 'Asia/Shanghai'
  target: TaskTarget;
  enabled: boolean;
  createdAt: number;
  updatedAt: number;
  lastRunAt?: number;
  nextRunAt: number;
}

export type TaskTarget =
  | { kind: 'skill';  skillId: SkillId; input: Record<string, unknown> }
  | { kind: 'prompt'; conversationId?: ConversationId; prompt: string };

export interface CreateTaskInput {
  hotelId: HotelId;
  name: string;
  cron: string;
  timezone: string;
  target: TaskTarget;
}

export type UpdateTaskPatch = Partial<Pick<
  ScheduledTask,
  'name' | 'cron' | 'timezone' | 'target' | 'enabled'
>>;

export interface TaskExecutionRecord {
  id: ExecutionId;
  taskId: TaskId;
  startedAt: number;
  finishedAt?: number;
  status: 'running' | 'success' | 'failed' | 'skipped';
  error?: KernelError;
  /** 关联的 SkillExecution 或 Conversation，前端可点击跳转 */
  link?:
    | { kind: 'skill_execution'; id: ExecutionId }
    | { kind: 'conversation';    id: ConversationId };
}
```

## 3.6 NotificationPort（通道发现 + 派发模式）

```typescript
export interface NotificationPort {
  /** 列出当前可用的通知通道（来自内核 + NIANXX 服务端注册） */
  channels(hotelId: HotelId): Promise<NotificationChannel[]>;

  /** 派发通知到一个或多个通道 */
  send(input: SendNotificationInput): Promise<NotificationDispatch>;

  /** 查询发送状态 */
  status(dispatchId: string): Promise<NotificationDispatch>;
}

export interface NotificationChannel {
  id: string;
  /** 开放字符串而非枚举：'email' | 'sms' | 'wecom' | 'dingtalk' |
   *  'whatsapp' | 'telegram' | 'slack' | <NIANXX 自建 kind> | ... */
  kind: string;
  label: string;              // 用户可见名称，如"前台微信群"
  recipient: string;          // 形态依 kind 而定（邮箱、群 ID、手机号、URL 等）
  enabled: boolean;
  source: 'kernel' | 'nianxx';   // 区分内核自带还是 NIANXX 服务端注册
  iconUrl?: string;
}

export interface SendNotificationInput {
  hotelId: HotelId;
  channelIds: string[];
  content: NotificationContent;
}

export type NotificationContent =
  | { kind: 'text';     text: string }
  | { kind: 'markdown'; markdown: string }
  | { kind: 'card';     title: string; body: string; actions?: NotificationAction[] };

export interface NotificationAction {
  label: string;
  url?: string;
  reply?: string;             // 用户点击后回写到对应 conversation
}

export interface NotificationDispatch {
  id: string;
  perChannel: { channelId: string; status: 'pending' | 'sent' | 'failed'; error?: KernelError }[];
  createdAt: number;
}
```

> **关于通道**：`kind` 是开放字符串而非枚举。Shell 拿到 channel 列表后，根据 `kind` 决定渲染方式（图标、是否需要二次确认等），但**不需要**为每种 kind 写专属代码。OpenClaw 内核自带 50+ 种通道全部继承可用；NIANXX 后续在服务端实现自建通道（如企微群机器人、钉钉自定义机器人），通过 `source: 'nianxx'` 注入到 `channels()` 返回结果中。

## 3.7 Adapter 契约

每个内核适配器导出一个工厂函数，返回 `Adapter` 实例：

```typescript
export interface Adapter {
  readonly info: { name: string; kernelVersion: string };

  /** 启动连接（建立 WebSocket 等） */
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  health(): Promise<{ ready: boolean; details?: Record<string, unknown> }>;

  /** 四个 Port 的实现 */
  readonly conversation: ConversationPort;
  readonly skill: SkillPort;
  readonly scheduler: SchedulerPort;
  readonly notification: NotificationPort;
}

export type AdapterFactory<Config> = (config: Config) => Adapter;
```

OpenClaw 适配器实现：

```typescript
// packages/kernel-adapter-openclaw/src/index.ts
export interface OpenClawAdapterConfig {
  wsUrl: string;
  token: string;
  reconnect?: { maxAttempts: number; backoffMs: number };
}

export const createOpenClawAdapter: AdapterFactory<OpenClawAdapterConfig> = (config) => {
  // 内部建立 WebSocket，订阅事件，把 OpenClaw RPC 包装为 Port 实现
  // 流式事件做 OpenClaw → ConversationStreamEvent 的归一化映射
  return {
    info: { name: 'openclaw', kernelVersion: '...' },
    connect:    /* ... */,
    disconnect: /* ... */,
    health:     /* ... */,
    conversation: createOpenClawConversationPort(config),
    skill:        createOpenClawSkillPort(config),
    scheduler:    createOpenClawSchedulerPort(config),
    notification: createOpenClawNotificationPort(config),
  };
};
```

## 3.8 流式语义统一（Adapter 的核心职责）

不同内核的流式输出（OpenClaw / Anthropic / 自研）在底层格式上有差异，Adapter 必须把它们归一化到 `ConversationStreamEvent`。约定：

1. 每个 assistant 消息以 `message_start` 开始，以 `message_complete` 结束
2. `text_delta` 是增量文本，前端做拼接
3. `tool_call` 一次性给出完整工具调用（不切片下发）；`tool_result` 同理
4. `artifact` 独立事件，不嵌套在 text 中
5. 任何错误都用 `error` 事件结束流（不抛异常）
6. `abort()` 后内核必须发出 `error` 事件，code = `kernel_aborted`

这套语义是 Adapter 的核心工作，也是它复杂度最高的部分。把这一层做好，整个 Shell 层就再也不需要关心"我在跟哪个内核说话"。

---

# 第四章 · YINIAN Skill Spec v0.1

## 4.1 设计目标

YINIAN Skill 是产品的核心 IP——它把酒店行业的 know-how（OTA 巡检逻辑、价格异常判定规则、客评回复话术等）编码为可执行单元。Skill Spec 决定了这些 IP 资产的形态。

设计目标按优先级：

1. **跨内核可移植** —— Skill 描述层不耦合任何内核的具体 API
2. **声明式优先** —— 元信息、输入输出、权限都用静态描述，能被工具静态校验、自动生成 UI
3. **可组合** —— skill 可以调用 skill，构成工作流
4. **可版本化** —— 单个 skill 自身有版本，Skill Spec 自身也有版本（v0.1 → v0.2 …）
5. **可远程下发** —— 每个 skill 是一个独立目录，能打包、签名、远程拉取

## 4.2 Skill 包目录结构

```
yinian-skill-ctrip-price-monitor/
├── manifest.yaml              # 必须：声明性元数据
├── README.md                  # 推荐：人读说明
├── prompts/                   # 推荐：提示词文件（与执行环境无关）
│   ├── system.md
│   └── analysis.md
├── logic/                     # 必须：业务逻辑（TS / Python）
│   ├── index.ts               # 入口
│   ├── parsers/
│   └── rules/
├── templates/                 # 推荐：通知 / 报告模板（Handlebars）
│   ├── daily-report.md.hbs
│   └── anomaly-alert.md.hbs
├── fixtures/                  # 推荐：测试用例
│   └── sample-response.json
├── adapters/                  # 必须：适配各内核的编译产物源
│   ├── openclaw.ts
│   └── (mcp.ts、claude-skill.ts 后续按需添加)
└── tests/                     # 推荐：单元 / 集成测试
```

## 4.3 manifest.yaml 完整 schema

```yaml
spec_version: "0.1"               # YINIAN Skill Spec 版本

# === 身份 ===
id: "ctrip-price-monitor"          # 全局唯一 slug
name: "携程酒店价格巡检"
version: "1.0.0"                   # skill 自身版本，semver
author: "NIANXX"
category: "ota-monitoring"         # ota-monitoring | reporting | guest-comm | ops-automation
icon: "ctrip"                      # ui-kit 已注册的 icon 名，或 url

# === 描述 ===
description: |
  每日巡检指定酒店在携程的房型与报价；
  对异常价格(如低于成本价、相邻日期价差过大)触发告警。

# === 输入契约 ===
inputs:
  - name: hotelId
    type: hotel_id                 # YINIAN 自定义类型，UI 自动渲染酒店选择器
    required: true
    label: "酒店"

  - name: dateRange
    type: date_range
    required: false
    label: "巡检日期范围"
    default: { kind: "next_n_days", n: 7 }

  - name: priceFloor
    type: number
    required: false
    label: "成本价下限(用于异常判定)"
    unit: "CNY"

# === 输出契约 ===
outputs:
  - name: snapshot
    type: object
    schema:                        # zod-style 子集
      properties:
        rooms:
          type: array
          item:
            properties:
              roomType:  { type: string }
              date:      { type: string, format: date }
              price:     { type: number }
              available: { type: boolean }

  - name: anomalies
    type: array
    item:
      properties:
        roomType: { type: string }
        date:     { type: string, format: date }
        kind:     { type: string, enum: [below_floor, large_gap, unavailable] }
        details:  { type: object }

# === 触发器 ===
triggers:
  - kind: manual                   # 用户手动点击
  - kind: scheduled                # 可被 cron 触发
  - kind: webhook                  # 服务端可远程触发
  - kind: reply                    # 用户回复某条通知触发

# === 运行时能力需求(Adapter 据此分配工具) ===
required_capabilities:
  - browser                        # 浏览器自动化
  - http                           # HTTP 请求
  - llm                            # LLM 推理(用于异常的语义判定)

# === 权限 / 沙箱声明 ===
permissions:
  network:
    - "*.ctrip.com"
    - "*.ctrip.com.cn"
  filesystem: none
  shell: false

# === 通知模板 ===
notifications:
  on_success:
    template: "templates/daily-report.md.hbs"
    suggested_channels: ["wecom", "email"]    # 渲染建议，用户可改
  on_anomaly:
    template: "templates/anomaly-alert.md.hbs"
    suggested_channels: ["wecom"]

# === 执行入口 ===
entrypoint:
  type: "logic"                    # logic | prompt-only | composite
  path: "./logic/index.ts"
  function: "run"

# === 资源限制 ===
limits:
  timeout_seconds: 300
  max_llm_tokens: 50000
  max_concurrent: 1                # 同酒店同 skill 不允许并发执行
```

## 4.4 入口函数签名

skill 的执行入口是一个标准化函数，签名固定：

```typescript
// logic/index.ts
import type { SkillRunContext, SkillRunResult } from '@yinian/skill-spec';

export async function run(
  input: { hotelId: string; dateRange?: DateRange; priceFloor?: number },
  ctx: SkillRunContext
): Promise<SkillRunResult> {
  const html = await ctx.browser.fetch('https://hotels.ctrip.com/...');
  const rooms = parseRooms(html);

  const anomalies = await ctx.llm.classify({
    prompt: ctx.prompts.load('analysis.md'),
    input: { rooms, priceFloor: input.priceFloor },
    schema: AnomalySchema,
  });

  ctx.emit.artifact({
    kind: 'table',
    columns: ['房型', '日期', '价格'],
    rows: rooms.map(/* ... */),
  });
  ctx.emit.progress({ phase: 'done', ratio: 1 });

  return {
    output: { snapshot: { rooms }, anomalies },
    notifications: anomalies.length
      ? [{ template: 'on_anomaly', vars: { anomalies } }]
      : [{ template: 'on_success', vars: { rooms } }],
  };
}
```

`SkillRunContext` 是 skill 与 Adapter 之间的接口——这是整个 Skill 系统能跨内核移植的关键。Skill 代码只 import `SkillRunContext`，不关心具体内核：

```typescript
export interface SkillRunContext {
  hotel: Hotel;
  user: User;
  browser: BrowserCapability;
  http: HttpCapability;
  llm: LlmCapability;
  prompts: { load(path: string): string };
  emit: {
    progress(e: { phase: string; ratio?: number; message?: string }): void;
    log(level: 'info' | 'warn' | 'error', message: string): void;
    artifact(a: Artifact): void;
  };
  abortSignal: AbortSignal;
}

export interface BrowserCapability {
  fetch(url: string, opts?: { waitFor?: string; userAgent?: string }): Promise<string>;
  click(selector: string): Promise<void>;
  // ...
}

export interface LlmCapability {
  complete(input: { prompt: string; system?: string; maxTokens?: number }): Promise<string>;
  classify<T>(input: { prompt: string; input: unknown; schema: ZodSchema<T> }): Promise<T>;
  // ...
}
```

每种 capability 由 Adapter 实现并注入。Skill 代码不知道 browser 是 Playwright 还是 Puppeteer 还是 OpenClaw 自带 browser tool。换内核时 capability 的实现换，但 skill 代码不动——这是整个 Skill IP 跨平台变现的基础。

## 4.5 Adapter 编译流程

每个 skill 的 `adapters/<kernel>.ts` 文件负责把 Skill 包翻译成目标内核能消费的格式：

```typescript
// adapters/openclaw.ts
import { defineSkillAdapter } from '@yinian/skill-spec/adapters/openclaw';

export default defineSkillAdapter({
  // manifest 字段映射到 OpenClaw skill 配置
  toOpenClawConfig(manifest) { /* ... */ },

  // 把 entrypoint logic 包装成 OpenClaw skill 可执行形态
  // (注入 ctx → 提供 browser/http/llm 实现)
  buildRuntime(manifest, logic) { /* ... */ },

  // 把 manifest.permissions 翻译成 OpenClaw sandbox 配置
  toSandboxPolicy(permissions) { /* ... */ },
});
```

构建时（`@yinian/skill-spec/cli`）扫描所有 skill 目录，产出可下发的 bundle：

```
ctrip-price-monitor-1.0.0.tgz
├── manifest.yaml
├── manifest.lock                  # 校验和
├── logic-bundled.js               # 已 bundle 的 JS
├── prompts/
├── templates/
└── for-openclaw/                  # OpenClaw 适配产物
    └── skill.yaml                 # OpenClaw 原生格式
```

服务端只下发 bundle 包；客户端 Skill Manager 把它解包到 `vendor/openclaw/skills/<id>` 目录，OpenClaw Gateway 加载即用。未来支持新内核时，bundle 包里多一个 `for-<kernel>/` 子目录即可。

## 4.6 Skill 与四个 Port 的关系

| Port | 与 Skill 的关系 |
|---|---|
| ConversationPort | 用户在对话里 `@skill` 触发；返回流中包含 `tool_call` 表示正在调技能 |
| SkillPort | 直接调用入口；提供独立于对话的执行视图（卡片式 UI） |
| SchedulerPort | `target.kind = 'skill'` 即"定时跑技能" |
| NotificationPort | skill 输出的 `notifications` 字段最终由 NotificationPort 投递 |

四个 Port 都和 Skill 有交集，但 **Skill 自身只依赖 `SkillRunContext`，不直接 import 任何 Port**——这是关键的解耦点。Skill 通过 `ctx.emit.*` 上报状态，由内核+Adapter 把这些事件映射到对应 Port 的事件流。

## 4.7 Skill 组合（v0.1 仅声明，不实现）

v0.1 不要求实现 skill 调 skill，但 manifest 字段结构预留：

```yaml
# 未来 v0.2：composite skill
entrypoint:
  type: "composite"
  steps:
    - call: ctrip-price-monitor
      input: { hotelId: "${input.hotelId}" }
      bind: ctripResult
    - call: meituan-price-monitor
      input: { hotelId: "${input.hotelId}" }
      bind: meituanResult
    - call: daily-report-writer
      input:
        ctrip: "${ctripResult.snapshot}"
        meituan: "${meituanResult.snapshot}"
```

v0.1 阶段 composite 可以在 logic 里手写——下个 spec 版本再做声明式编排。

## 4.8 版本演进策略

- `spec_version` 遵循 semver，向后兼容字段加 minor，破坏性改动加 major
- `@yinian/skill-spec` 包提供 `migrate(manifest, fromVersion, toVersion)`，老 skill 自动迁移到新 spec
- Adapter 同时支持当前和上一版 spec（N - 1 兼容）
- 客户端运行时校验 `spec_version` 与 Adapter 能力匹配，不匹配则拒绝加载并报错

## 4.9 v1 必做的 4 个 Skill（详细设计放第七章）

| Skill ID | 名称 | 角色 |
|---|---|---|
| `ctrip-price-monitor` | 携程价格巡检 | 标杆 skill，作为模板复制到其他 OTA |
| `meituan-price-monitor` | 美团价格巡检 | 复用同套 logic 框架，仅 parser 不同 |
| `daily-report` | 早间日报生成 | 组合型 skill，调用上述巡检 + LLM 写日报 |
| `review-reply-helper` | 客评回复助手 | 不带 cron，用户对话触发 |

---

# 第五章 · 客户端模块设计（Main / Renderer）

## 5.1 改造原则

智念桌面端基于 ClawX fork，但 v1 阶段不追求一次性把上游完全重构为理想 monorepo。工程策略分两步：

1. **先保留 ClawX 可运行主体**：窗口、OpenClaw Gateway 生命周期、原有 IPC、构建发布链路先不大拆。
2. **再建立 YINIAN 边界层**：新增 Auth、Config Sync、Skill Manager、Kernel Adapter、UI Kit 等模块，把酒店产品逻辑逐步迁出原 ClawX 页面与配置模型。
3. **最后做目录迁移**：等登录、服务端配置、skill 下发、核心 UI 跑通后，再把工程结构迁移到第二章定义的 workspace 形态。

这样做的目标是降低 fork 初期风险：第一版产品先跑起来，后续再把架构原则逐步固化为工程纪律。

## 5.2 Main 进程模块

Main 进程负责所有系统级能力、外部网络通信和敏感状态。Renderer 只拿到受限 API，不直接读取 token、不直接访问服务端、不直接管理 Gateway 子进程。

| 模块 | 职责 | 关键输入 | 关键输出 |
|---|---|---|---|
| `AppLifecycle` | 应用启动、退出、单实例锁、窗口恢复 | Electron lifecycle | 主窗口、托盘、退出钩子 |
| `AuthManager` | 登录、刷新 token、退出、keychain 存储 | 手机号/验证码、账号密码、refresh token | `AuthSession` |
| `DeviceManager` | 设备注册、设备 ID、设备撤销 | 本机信息、登录态 | `device_id`、设备绑定状态 |
| `TenantContext` | 当前用户、酒店、角色、权限 | `/auth/me`、`/config/sync` | 当前酒店上下文 |
| `ConfigSync` | 拉取服务端配置、合并本地配置 | token、hotelId、appVersion | `ClientConfigSnapshot` |
| `SkillManager` | 拉取 manifest、下载 bundle、验签、解包、回滚 | `/skills/manifest` | 本地 skill registry |
| `KernelLifecycle` | 启动、健康检查、停止 OpenClaw Gateway | config、skill 目录、端口 | Gateway ready 状态 |
| `PortDetection` | 检测 18928 端口占用与握手 | 端口、health endpoint | 可用端口或失败态 |
| `NotificationBridge` | 系统通知、托盘提醒、点击回调 | skill 执行结果、服务端推送 | OS 通知、应用内事件 |
| `UpdateManager` | 客户端更新检查与灰度 | appVersion、channel | 更新提示或静默更新 |
| `Diagnostics` | 日志打包、健康检查、远程诊断 | 日志、配置快照、Gateway 状态 | 诊断报告 |
| `Telemetry` | 事件上报、错误上报、性能采样 | 匿名事件、错误 | `/events/ingest` |

### 5.2.1 AuthManager

AuthManager 是唯一可以读写 token 的模块。token 存储规则：

- `access_token` 只保存在内存，应用重启后通过 `refresh_token` 换取
- `refresh_token` 存入系统 keychain，不落普通文件
- Renderer 永远拿不到 token 字符串，只能调用 `window.yinian.auth.*`
- 退出登录时清理 token、本地租户缓存、Gateway 会话凭证

登录方式 v1 支持两种：

| 方式 | 用途 |
|---|---|
| 手机号 + 验证码 | 酒店员工主路径 |
| 账号 + 密码 | NIANXX 内部实施、客成和管理员 |

后续可扩展企业微信扫码、钉钉扫码，但 v1 不做。

### 5.2.2 ConfigSync

ConfigSync 拉取服务端控制面配置，并生成客户端可消费的快照：

```typescript
export interface ClientConfigSnapshot {
  user: User;
  hotels: Hotel[];
  currentHotelId: HotelId;
  entitlements: SkillEntitlement[];
  llmProxy: {
    baseUrl: string;
    modelPolicyId: string;
  };
  notificationChannels: NotificationChannel[];
  featureFlags: Record<string, boolean>;
  updatedAt: number;
}
```

合并规则：

- 服务端配置优先级高于本地默认配置
- 用户本地 UI 偏好可以覆盖服务端默认值，例如侧栏折叠、主题密度
- skill entitlement、LLM proxy、通知通道、权限必须以服务端为准
- 配置快照写入本地加密存储，离线时可只读使用

### 5.2.3 SkillManager

SkillManager 是远程下发能力包的安全边界。启动流程：

1. 请求 `/skills/manifest?hotel_id=...`
2. 对比本地 `skill_registry.json`
3. 下载新增或升级的 bundle
4. 校验服务端签名、公钥指纹、bundle hash、manifest hash
5. 解包到 staging 目录
6. 调用 skill-spec 校验 schema 与权限
7. 原子替换到 active 目录
8. 更新本地 registry
9. 通知 KernelLifecycle 重载 Gateway 或延迟到下次启动

本地目录建议：

```
~/Library/Application Support/YINIAN/
├── config/
├── skills/
│   ├── active/
│   ├── staging/
│   └── rollback/
├── kernel/
├── logs/
└── diagnostics/
```

安全规则：

- 未签名 bundle 拒绝加载
- 签名通过但权限超出 manifest 声明，拒绝加载
- 同一 hotel 同一 skill 只保留当前版本和上一版本
- 服务端可下发 `disabled: true` 作为 kill switch
- bundle 不允许覆盖客户端任意路径，只能解包到 skill sandbox 目录

### 5.2.4 KernelLifecycle

KernelLifecycle 负责把 OpenClaw Gateway 作为受控子进程启动。启动参数由 Main 生成：

```typescript
export interface KernelLaunchConfig {
  port: number;
  healthToken: string;
  wsSessionToken: string;
  skillDir: string;
  llmProxyBaseUrl: string;
  modelPolicyId: string;
  logDir: string;
}
```

关键要求：

- Gateway 只监听 `127.0.0.1`
- health endpoint 校验 `healthToken`
- WebSocket 握手必须携带 `wsSessionToken`
- `OPENAI_BASE_URL` 指向 NIANXX LLM Proxy
- 客户端不注入任何第三方模型 API key
- Main 退出时发送优雅关闭信号，超时后再强制结束进程

### 5.2.5 IPC 与 preload 契约

Renderer 通过 `contextBridge` 使用受限 API：

```typescript
declare global {
  interface Window {
    yinian: {
      auth: {
        getSessionState(): Promise<AuthSessionState>;
        loginWithSms(input: LoginWithSmsInput): Promise<LoginResult>;
        loginWithPassword(input: LoginWithPasswordInput): Promise<LoginResult>;
        logout(): Promise<void>;
      };
      app: {
        getConfig(): Promise<ClientConfigSnapshot>;
        switchHotel(hotelId: HotelId): Promise<void>;
        getKernelEndpoint(): Promise<{ wsUrl: string; token: string }>;
        openDiagnostics(): Promise<void>;
      };
      skills: {
        sync(): Promise<SkillSyncResult>;
        listLocal(): Promise<InstalledSkill[]>;
      };
      diagnostics: {
        getHealth(): Promise<DiagnosticsHealth>;
        exportBundle(): Promise<{ path: string }>;
      };
    };
  }
}
```

禁止事项：

- 禁止 Renderer 读取 keychain
- 禁止 Renderer 直接调用 NIANXX 服务端
- 禁止 Renderer 直接 spawn 子进程
- 禁止 Renderer 直接读写 skill bundle 目录

## 5.3 Renderer 信息架构

智念不是通用聊天工具，第一屏应是酒店运营工作台。推荐主导航：

| 页面 | 目标用户 | 主要任务 |
|---|---|---|
| 今日 | 前台、运营、店长 | 看异常、看日报、处理待确认事项 |
| 对话 | 运营、实施 | 临时询问、追问结果、自然语言触发任务 |
| Skills | 运营、实施 | 查看已开通能力、手动运行、查看说明 |
| 自动任务 | 运营、店长 | 管理早报、巡检、定时提醒 |
| 报告 | 店长、老板 | 查看日报、周报、异常归档 |
| 通知 | 运营、实施 | 管理企微、钉钉、邮箱等通道 |
| 设置 | 实施、管理员 | 酒店信息、账号、诊断、版本 |

### 5.3.1 今日页

今日页是默认首页，解决“打开软件后我该看什么”的问题。

核心模块：

- 顶部酒店切换器：显示当前酒店、城市、账号角色
- 今日摘要：已完成任务、异常数量、待确认数量
- 待处理队列：价格异常、任务失败、通知未送达、客评待回复
- 早报卡片：展示当天日报摘要，支持展开完整报告
- 快捷运行：携程巡检、美团巡检、生成早报、客评回复
- 最近执行：显示任务状态、耗时、是否有 artifact

状态设计：

| 状态 | UI 行为 |
|---|---|
| 无任务 | 显示空态和推荐开通的首个自动任务 |
| 正在同步 | 顶部轻量进度，不阻塞查看旧数据 |
| 有异常 | 待处理队列置顶，使用明确优先级 |
| 离线 | 显示本地缓存结果，禁用需要联网的操作 |

### 5.3.2 对话页

对话页保留 Agent 的灵活性，但交互要比 ClawX 更业务化：

- 左侧是会话列表，默认按酒店分组
- 中间是消息流
- 右侧是上下文面板，展示当前酒店、可用 skills、最近 artifacts
- 输入框支持 `@skill`，但普通用户不需要理解技术名称
- 工具调用以业务步骤展示，例如“正在读取携程价格”而不是裸 tool name
- artifact 可固定到报告页或导出

### 5.3.3 Skills 页

Skills 页只展示服务端已开通能力，不做开放 Marketplace。

每个 skill 卡片包含：

- 名称、图标、简介
- 开通状态、版本、最近运行时间
- 支持触发方式：手动、定时、通知回复
- 需要的权限摘要
- 手动运行按钮
- 历史执行入口

实施人员可以看到更多诊断信息：

- bundle 版本
- manifest hash
- 最近失败原因
- 本地路径
- 重新同步按钮

### 5.3.4 自动任务页

自动任务页围绕 SchedulerPort 构建。

功能：

- 创建定时任务
- 暂停/恢复任务
- 修改 cron、人类可读时间、时区
- 查看上次运行与下次运行
- 查看执行历史
- 失败重试策略配置

酒店用户看到的是“每天 08:30 生成早报”，不是 cron 表达式。cron 只在高级模式展示。

### 5.3.5 通知页

通知页管理 NotificationPort 返回的通道。

v1 支持：

- 系统桌面通知
- 企业微信群机器人
- 钉钉群机器人
- 邮箱

通道来源分两类：

- `kernel`：OpenClaw 内核继承通道
- `nianxx`：NIANXX 服务端托管通道

普通用户只能启停和测试通道；实施人员可以配置 webhook、群机器人 token 等敏感参数。敏感参数写服务端，不写客户端。

## 5.4 视觉与交互原则

设计目标：高端、克制、清楚、低学习成本。

原则：

- 主色使用品牌蓝 `#1A56DB`，但界面不做单一蓝色铺满
- 页面以白底和浅灰分区为主，少用大面积渐变
- 卡片只用于任务、skill、报告等重复实体
- 侧栏固定，主工作区稳定，避免页面跳动
- 状态颜色统一：成功绿、警告橙、失败红、处理中蓝灰
- 所有长耗时任务必须有进度、可取消、可查看详情
- 技术术语默认隐藏，例如 provider、API key、RPC、sandbox
- 失败文案给出可执行下一步，例如“重新同步 skill”或“联系实施人员”

关键组件：

| 组件 | 用途 |
|---|---|
| `HotelSwitcher` | 当前租户上下文 |
| `TaskStatusBadge` | 任务状态 |
| `SkillCard` | skill 概览与入口 |
| `ArtifactViewer` | 表格、图表、Markdown、文件预览 |
| `ExecutionTimeline` | skill 执行步骤 |
| `NotificationChannelRow` | 通知通道管理 |
| `DiagnosticsPanel` | 健康检查与日志导出 |

## 5.5 首次启动与失败态

首次启动流程：

1. 打开应用
2. 显示登录页
3. 登录成功后选择酒店
4. 同步配置与 skills
5. 启动 Gateway
6. 进入今日页

必须设计的失败态：

| 失败态 | 处理 |
|---|---|
| 无网络 | 允许登录页重试；已登录用户进入离线只读 |
| token 过期 | 静默刷新，失败后回登录 |
| 未绑定酒店 | 显示“联系管理员开通” |
| skill 同步失败 | 进入主界面，但禁用相关 skill 并显示重试 |
| Gateway 启动失败 | 显示诊断页和导出日志 |
| 端口冲突 | 显示占用进程、切换备用端口、重试 |
| LLM Proxy 不可用 | 对话和需要 LLM 的 skill 禁用，其他本地功能可用 |

# 第六章 · 服务端 API 契约

## 6.1 设计原则

NIANXX 服务端是智念桌面端的控制面。客户端不持有模型密钥，不自行决定 skill entitlement，不直接保存第三方敏感凭证。

服务端职责：

- 认证与设备管理
- 用户、酒店、角色、权限
- 客户套餐和 skill 开通
- skill manifest 与 bundle 下载
- LLM Proxy、计费、限流、脱敏
- 通知通道托管
- 执行结果、日志、报表回流
- 灰度、功能开关、版本策略

## 6.2 通用约定

基础路径：

```text
https://api.nianxx.com/yinian/v1
```

请求头：

```http
Authorization: Bearer <access_token>
X-YINIAN-App-Version: 0.1.0
X-YINIAN-Device-Id: <device_id>
X-YINIAN-Request-Id: <uuid>
X-YINIAN-Hotel-Id: <hotel_id>
```

错误响应：

```json
{
  "error": {
    "code": "permission_denied",
    "message": "当前账号无权操作该酒店",
    "retryable": false,
    "request_id": "req_xxx"
  }
}
```

错误码与 `KernelErrorCode` 尽量对齐，但服务端可扩展：

| code | 含义 |
|---|---|
| `auth_required` | 需要登录 |
| `token_expired` | token 过期 |
| `permission_denied` | 权限不足 |
| `hotel_not_found` | 酒店不存在或未绑定 |
| `skill_not_entitled` | 未开通 skill |
| `skill_bundle_invalid` | skill 包无效 |
| `rate_limited` | 触发限流 |
| `llm_proxy_unavailable` | 模型代理不可用 |
| `invalid_input` | 请求参数错误 |
| `server_error` | 服务端异常 |

## 6.3 Auth API

### 6.3.1 发送短信验证码

```http
POST /auth/sms/send
```

```json
{
  "phone": "13800000000",
  "purpose": "login"
}
```

### 6.3.2 手机号登录

```http
POST /auth/login/sms
```

```json
{
  "phone": "13800000000",
  "code": "123456",
  "device": {
    "device_id": "dev_xxx",
    "platform": "darwin",
    "app_version": "0.1.0",
    "machine_name": "FrontDesk-Mac"
  }
}
```

响应：

```json
{
  "access_token": "eyJ...",
  "refresh_token": "rt_xxx",
  "expires_in": 3600,
  "user": {
    "id": "user_001",
    "name": "王店长",
    "phone": "13800000000"
  }
}
```

### 6.3.3 账号密码登录

```http
POST /auth/login/password
```

用于 NIANXX 内部账号和部分管理员账号。

### 6.3.4 刷新 token

```http
POST /auth/refresh
```

```json
{
  "refresh_token": "rt_xxx",
  "device_id": "dev_xxx"
}
```

### 6.3.5 当前用户

```http
GET /auth/me
```

返回用户、可访问酒店、角色、权限：

```json
{
  "user": { "id": "user_001", "name": "王店长", "phone": "13800000000" },
  "hotels": [
    {
      "id": "hotel_001",
      "name": "智念杭州西湖店",
      "city": "杭州",
      "role": "manager",
      "permissions": ["skill:run", "task:manage", "report:view"]
    }
  ]
}
```

## 6.4 Config API

### 6.4.1 配置同步

```http
GET /config/sync?hotel_id=hotel_001
```

响应：

```json
{
  "server_time": 1777190400000,
  "hotel": {
    "id": "hotel_001",
    "name": "智念杭州西湖店",
    "brand": "智念",
    "city": "杭州",
    "ota": [
      { "ota": "ctrip", "externalId": "ctrip_123", "enabled": true },
      { "ota": "meituan", "externalId": "mt_456", "enabled": true }
    ]
  },
  "feature_flags": {
    "review_reply_helper": true,
    "auto_update_skills": true
  },
  "model_policy": {
    "id": "policy_standard_cn",
    "allowed_models": ["default"],
    "max_tokens_per_day": 1000000
  },
  "ui_policy": {
    "default_page": "today",
    "show_advanced_settings": false
  }
}
```

## 6.5 Skill API

### 6.5.1 Skill manifest

```http
GET /skills/manifest?hotel_id=hotel_001&client_version=0.1.0
```

响应：

```json
{
  "manifest_version": "2026-04-26.1",
  "public_key_id": "yinian-skill-signing-2026",
  "skills": [
    {
      "id": "ctrip-price-monitor",
      "version": "1.0.0",
      "enabled": true,
      "entitlement": "standard",
      "bundle_url": "https://cdn.nianxx.com/skills/ctrip-price-monitor-1.0.0.tgz",
      "bundle_sha256": "abc123...",
      "manifest_sha256": "def456...",
      "signature": "base64...",
      "required_client_version": ">=0.1.0",
      "kill_switch": false
    }
  ]
}
```

### 6.5.2 Bundle 下载

```http
GET /skills/bundles/{skill_id}/{version}
```

实际生产可返回短期 CDN 签名 URL。客户端必须校验 hash 和签名，不信任 CDN 本身。

### 6.5.3 Skill 执行结果回流

```http
POST /skills/executions
```

```json
{
  "execution_id": "exec_001",
  "hotel_id": "hotel_001",
  "skill_id": "ctrip-price-monitor",
  "version": "1.0.0",
  "status": "success",
  "started_at": 1777190400000,
  "finished_at": 1777190460000,
  "duration_ms": 60000,
  "summary": {
    "rooms_checked": 32,
    "anomalies": 2
  },
  "artifacts": [
    { "kind": "table", "id": "artifact_001", "title": "价格快照" }
  ]
}
```

## 6.6 LLM Proxy API

Gateway 的模型请求统一走 NIANXX LLM Proxy。

```http
POST /llm/v1/chat/completions
```

约束：

- 请求必须携带客户端 access token 或由 Gateway 换取的短期 proxy token
- 服务端根据 hotel、user、skill、model_policy 做鉴权
- 服务端负责选择真实模型供应商
- 服务端负责限流、计费、日志脱敏
- 客户端不出现 OpenAI、Anthropic 等供应商 API key

建议增加 Gateway 专用 token：

```http
POST /llm/proxy-token
```

```json
{
  "hotel_id": "hotel_001",
  "device_id": "dev_xxx",
  "kernel_session_id": "ks_xxx"
}
```

响应：

```json
{
  "proxy_token": "kpt_xxx",
  "expires_in": 1800,
  "base_url": "https://api.nianxx.com/yinian/v1/llm/v1"
}
```

## 6.7 Notification API

### 6.7.1 查询通道

```http
GET /notifications/channels?hotel_id=hotel_001
```

```json
{
  "channels": [
    {
      "id": "ch_wecom_001",
      "kind": "wecom",
      "label": "前台运营群",
      "recipient": "杭州西湖店运营群",
      "enabled": true,
      "source": "nianxx"
    }
  ]
}
```

### 6.7.2 测试通道

```http
POST /notifications/channels/{channel_id}/test
```

### 6.7.3 派发通知

```http
POST /notifications/dispatch
```

```json
{
  "hotel_id": "hotel_001",
  "channel_ids": ["ch_wecom_001"],
  "content": {
    "kind": "markdown",
    "markdown": "今日价格巡检发现 2 个异常"
  },
  "source": {
    "kind": "skill_execution",
    "id": "exec_001"
  }
}
```

## 6.8 Data Sink 与事件上报

客户端上报分三类：

| 类型 | Endpoint | 是否含业务数据 |
|---|---|---|
| 产品行为事件 | `POST /events/ingest` | 否，默认匿名或弱标识 |
| skill 执行结果 | `POST /skills/executions` | 是，需按租户隔离 |
| 诊断日志 | `POST /diagnostics/upload` | 可能含敏感信息，上传前脱敏 |

行为事件示例：

```json
{
  "events": [
    {
      "name": "skill_run_clicked",
      "time": 1777190400000,
      "hotel_id": "hotel_001",
      "properties": {
        "skill_id": "ctrip-price-monitor",
        "entry": "today_page"
      }
    }
  ]
}
```

## 6.9 权限模型

角色初版：

| 角色 | 权限 |
|---|---|
| `owner` | 查看全部报告、管理通知、管理自动任务、运行 skills |
| `manager` | 查看报告、管理自动任务、运行 skills |
| `staff` | 查看今日页、运行部分 skills、处理待办 |
| `viewer` | 只读查看报告和历史 |
| `nianxx_admin` | 跨酒店实施、诊断、配置 entitlement |

权限粒度：

```text
hotel:view
report:view
skill:view
skill:run
skill:manage
task:view
task:manage
notification:view
notification:manage
diagnostics:export
```

# 第七章 · Skills v1 详细设计

## 7.1 v1 Skill 设计原则

v1 不追求覆盖所有酒店场景，只做能快速证明价值的四个 skill：

1. 价格巡检：直接节省运营时间
2. 早间日报：每天固定触达店长和老板
3. 客评回复：体现 AI 生成质量
4. 通知闭环：把结果送到用户已经在用的企微/钉钉

数据获取原则：

- 优先使用客户授权的官方 API 或服务端集成
- 无官方 API 时，浏览器自动化作为 v1 可用路径
- 涉及 OTA 账号密码时，优先服务端托管，不写入客户端
- skill 输出必须可解释，不能只给一句模型结论

## 7.2 `ctrip-price-monitor`

目标：每日巡检指定酒店在携程的房型、日期、价格、可售状态，识别异常并通知运营人员。

输入：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `hotelId` | `hotel_id` | 是 | 当前酒店 |
| `dateRange` | `date_range` | 否 | 默认未来 7 天 |
| `priceFloor` | `number` | 否 | 成本价或底价 |
| `roomTypes` | `string[]` | 否 | 指定房型 |

输出：

- `snapshot`：价格快照
- `anomalies`：异常列表
- `summary`：房型数、日期数、异常数

异常规则：

| 异常 | 规则 |
|---|---|
| `below_floor` | 价格低于成本价或配置底价 |
| `large_gap` | 相邻日期价差超过配置阈值 |
| `unavailable` | 应售房型不可售 |
| `missing_room` | 页面未找到已配置房型 |
| `parse_suspect` | 解析置信度过低，需要人工确认 |

执行步骤：

1. 读取酒店 OTA 绑定
2. 打开携程酒店页面或调用服务端数据接口
3. 抓取未来 N 天房型价格
4. 标准化房型名称
5. 执行规则判定
6. 必要时调用 LLM 对异常描述做自然语言解释
7. 生成 table artifact 和 markdown 摘要
8. 有异常则通知指定通道

验收标准：

- 能稳定输出未来 7 天价格快照
- 同一酒店同一 skill 不并发执行
- 页面结构变化时返回 `parse_suspect`，不输出误导性结论
- 失败日志能定位到抓取、解析、规则、通知哪个阶段

## 7.3 `meituan-price-monitor`

目标与携程巡检一致，但适配美团/大众点评酒店页面或服务端数据源。

复用策略：

- 复用 `skills-hotel-core` 中的价格标准化、异常规则、报告模板
- 独立维护 `meituan` parser
- 与携程输出结构保持一致，方便日报 skill 聚合

新增关注点：

- 美团房型命名与携程不完全一致，需要房型映射表
- 同一房型可能出现多个套餐，需要选择代表价格或列出套餐差异
- 可售状态、取消政策、早餐信息可作为 v1.1 扩展字段

验收标准：

- 输出 schema 与 `ctrip-price-monitor` 兼容
- 可与携程结果在 `daily-report` 中合并
- 支持房型映射配置

## 7.4 `daily-report`

目标：每天早上生成酒店运营日报，汇总 OTA 价格巡检、异常、昨日任务执行和建议动作。

输入：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `hotelId` | `hotel_id` | 是 | 当前酒店 |
| `date` | `date` | 否 | 默认今天 |
| `includeOta` | `string[]` | 否 | 默认已启用 OTA |
| `sendToChannels` | `string[]` | 否 | 默认服务端配置 |

执行步骤：

1. 调用或读取携程巡检结果
2. 调用或读取美团巡检结果
3. 汇总异常与趋势
4. 生成店长可读的 Markdown 日报
5. 输出 report artifact
6. 按配置发送企微/钉钉/邮箱

日报结构：

```markdown
# 今日运营早报

## 重点结论

## OTA 价格概览

## 异常与建议

## 今日建议动作

## 明细表
```

验收标准：

- 生成内容不超过 2 屏手机阅读长度
- 明细可在桌面端展开查看
- LLM 生成内容必须基于结构化输入，不允许凭空编造
- 没有异常时也要生成“已完成巡检”的正向反馈

## 7.5 `review-reply-helper`

目标：根据客人评价内容、酒店品牌语气、问题类型，生成可编辑的回复建议。

输入：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `hotelId` | `hotel_id` | 是 | 当前酒店 |
| `reviewText` | `string` | 是 | 客评原文 |
| `rating` | `number` | 否 | 评分 |
| `platform` | `string` | 否 | 携程/美团/大众点评等 |
| `tone` | `string` | 否 | 默认酒店品牌语气 |

输出：

- `reply`：建议回复
- `issueTags`：问题标签
- `riskLevel`：是否需要人工升级
- `alternatives`：可选回复版本

规则：

- 差评默认不自动发送，只生成建议
- 涉及安全、卫生、赔偿、隐私、投诉升级，标记 `high`
- 回复必须避免承诺未确认的补偿
- 回复中不得泄露内部操作信息

验收标准：

- 生成回复可直接复制
- 高风险客评必须提示人工处理
- 同一评价可生成“正式/温和/简短”三种版本

## 7.6 共享包 `skills-hotel-core`

共享能力：

- OTA 房型标准化
- 价格异常规则
- 日期与时区处理
- 酒店品牌语气配置
- 通知模板渲染
- artifact 生成工具
- 执行日志辅助函数

建议目录：

```
packages/skills-hotel-core/
├── src/
│   ├── ota/
│   ├── pricing/
│   ├── report/
│   ├── review/
│   └── templates/
└── tests/
```

## 7.7 Skill 测试要求

每个 v1 skill 至少包含：

- manifest schema 测试
- 输入校验测试
- parser fixture 测试
- 异常规则单元测试
- artifact snapshot 测试
- 失败态测试
- bundle 构建测试

价格巡检类 skill 额外要求：

- 页面结构字段缺失时不崩溃
- 空房型、空价格、重复房型可处理
- 时区固定为酒店所在地

# 第八章 · 非功能性要求

## 8.1 安全

安全是 v1 硬门槛，不是上线后的增强项。

### 8.1.1 Token 与密钥

- 客户端永不保存第三方模型 API key
- `refresh_token` 存系统 keychain
- `access_token` 只在内存保存
- Gateway 使用短期 `proxy_token` 调用 LLM Proxy
- token 刷新失败立即降级到登录态

### 8.1.2 Gateway 本地访问控制

- Gateway 只监听 `127.0.0.1`
- health endpoint 需要 Main 注入的 `healthToken`
- WebSocket 连接需要短期 `wsSessionToken`
- token 随应用启动生成，退出即失效
- Renderer 只能通过 Main 获取 endpoint 和 token

### 8.1.3 Skill Bundle 安全

- 所有 bundle 必须签名
- 客户端内置 NIANXX skill 公钥指纹
- 下载后校验 sha256 和签名
- manifest 权限与实际 bundle 行为不一致时拒绝加载
- 支持服务端 kill switch
- 支持回滚到上一版本

### 8.1.4 权限与沙箱

- skill 权限最小化
- 默认禁止 shell
- 默认禁止任意文件系统访问
- 网络权限按域名白名单声明
- 浏览器能力必须受限于目标域
- 高风险 capability 需要服务端 entitlement 开启

### 8.1.5 数据脱敏

日志中默认脱敏：

- 手机号
- 邮箱
- token
- webhook URL
- OTA 账号
- 客评中的手机号、身份证号等个人信息

诊断包上传前必须二次脱敏，并显示将上传的内容摘要。

## 8.2 性能

启动目标：

| 指标 | 目标 |
|---|---|
| 冷启动到登录页 | < 3 秒 |
| 已登录启动到今日页可见 | < 6 秒 |
| Gateway ready | < 15 秒 |
| skill manifest 同步 | < 5 秒，网络正常时 |
| 今日页首次渲染 | < 2 秒，使用本地缓存 |

运行目标：

- 对话 token 流不卡 UI
- 大 artifact 分页或虚拟滚动
- 单个 skill 执行不阻塞其他 UI 操作
- 日志写入异步化
- CPU 长时间占用超过阈值时上报诊断事件

## 8.3 离线能力

离线状态下：

| 功能 | 行为 |
|---|---|
| 今日页 | 显示最近一次缓存 |
| 报告页 | 可查看历史报告 |
| 对话 | 禁用发送，显示离线提示 |
| Skills | 可查看说明和历史，默认禁止运行需要网络的 skill |
| 自动任务 | 本地可显示，但执行前检查网络 |
| 通知 | 本地系统通知可用，外部通道排队或失败 |

离线恢复后：

- 自动刷新 token
- 同步 config
- 同步 skill manifest
- 上报积压事件
- 检查失败任务是否可重试

## 8.4 可观测性

日志分层：

| 日志 | 内容 |
|---|---|
| app.log | 应用生命周期、登录、配置同步 |
| kernel.log | Gateway 启停、健康检查 |
| skill.log | skill 执行、阶段、错误 |
| network.log | 服务端请求摘要，不记录敏感 body |
| renderer.log | UI 错误、页面崩溃 |

关键事件：

- `app_started`
- `login_success`
- `config_sync_success`
- `skill_sync_failed`
- `kernel_ready`
- `skill_execution_started`
- `skill_execution_completed`
- `notification_dispatch_failed`
- `llm_proxy_rate_limited`

错误必须带：

- request id
- hotel id
- user id hash
- device id
- app version
- skill id/version
- kernel version

## 8.5 更新策略

客户端更新：

- v1 使用手动确认更新
- 关键安全更新可强提醒
- 更新前检查 Gateway 是否有任务运行
- 更新失败保留旧版本可启动

Skill 更新：

- 默认静默更新
- 正在执行的 skill 不热替换
- 新版本失败可回滚上一版本
- 服务端可按酒店灰度发布

## 8.6 兼容性

v1 支持：

| 平台 | 要求 |
|---|---|
| macOS | 13 及以上 |
| Windows | Windows 10 及以上 |

暂不承诺 Linux 正式支持。内部开发可运行，但不作为 v1 客户交付范围。

## 8.7 隐私与合规

原则：

- 明确区分本地数据、服务端数据、第三方平台数据
- 默认最小化回传
- 报告与执行结果按酒店租户隔离
- 客评内容属于敏感业务数据，回传和训练用途需单独授权
- 不使用客户数据训练通用模型，除非合同另行约定

# 第九章 · 里程碑、交付计划与风险登记册

## 9.1 里程碑

以 2026-04-26 为 v0 启动日，建议第一阶段按 10 周推进。

| 里程碑 | 日期 | 目标 | 交付物 |
|---|---|---|---|
| M0 项目启动 | 2026-04-26 至 2026-05-03 | 完成 fork、技术验证、PRD 评审 | ClawX fork、架构 ADR、任务拆分 |
| M1 登录与控制面 | 2026-05-04 至 2026-05-17 | 登录、酒店上下文、配置同步跑通 | AuthManager、ConfigSync、基础 API |
| M2 Kernel 适配 | 2026-05-18 至 2026-05-31 | Gateway 生命周期、Port Adapter、端口检测 | KernelLifecycle、ConversationPort MVP |
| M3 Skill 下发 | 2026-06-01 至 2026-06-14 | manifest、bundle、验签、首个 skill | SkillManager、ctrip-price-monitor |
| M4 产品 UI Alpha | 2026-06-15 至 2026-06-28 | 今日页、Skills、自动任务、报告页 | Alpha 客户端 |
| M5 试点 Beta | 2026-06-29 至 2026-07-12 | 2 到 3 家酒店试点，闭环反馈 | Beta 包、试点报告、风险修复 |

## 9.2 MVP 范围

必须包含：

- 登录与酒店选择
- 今日页
- 对话页基础能力
- Skill 列表与手动运行
- 携程价格巡检
- 日报生成
- 企业微信或钉钉通知一种
- Gateway 生命周期管理
- skill bundle 签名校验
- 基础诊断包导出

暂缓：

- 开放 Marketplace
- 私有部署
- 手机端
- 多内核切换 UI
- 复杂工作流编排
- 全量通知通道管理

## 9.3 评审关口

| 关口 | 必须通过 |
|---|---|
| 架构评审 | 端口契约、Main/Renderer 边界、安全边界 |
| 安全评审 | token、Gateway、本地文件、skill bundle |
| UI 评审 | 今日页、对话页、失败态、诊断页 |
| Skill 评审 | manifest、权限、测试、回滚 |
| 试点评审 | 真实酒店任务完成率、失败率、用户反馈 |

## 9.4 风险登记册

| 风险 | 概率 | 影响 | 应对 |
|---|---|---|---|
| ClawX 上游结构变化快，fork 同步困难 | 中 | 高 | 保持上游同步分支，减少早期大重构 |
| OpenClaw Gateway API 不稳定 | 中 | 高 | Adapter 隔离，关键 RPC 写契约测试 |
| OTA 页面结构变化导致 parser 失效 | 高 | 高 | fixture 测试、parse_suspect、快速热更新 skill |
| skill 远程下发带来安全风险 | 中 | 极高 | 签名、hash、权限、沙箱、kill switch |
| 酒店用户不理解 Agent 对话 | 中 | 中 | 今日页优先，任务卡片优先，对话作为补充 |
| LLM Proxy 成本失控 | 中 | 高 | model policy、配额、缓存、按 skill 计量 |
| 通知送达不稳定 | 中 | 中 | 状态回执、重试、失败提示、备用通道 |
| Windows 环境差异 | 中 | 中 | 早期纳入 Windows 测试机和自动化打包 |
| 客户数据合规边界不清 | 中 | 高 | 合同、授权、脱敏、租户隔离、审计 |

# 附录 A · 术语表

| 术语 | 说明 |
|---|---|
| 智念桌面端 | 面向酒店运营的 AI Agent 桌面客户端 |
| Shell | 桌面壳，包括 UI、登录态、本地存储、通知 |
| Kernel | Agent runtime，当前为 OpenClaw |
| Adapter | 把领域 Port 翻译为具体内核调用的适配层 |
| Port | Shell 使用的领域接口，包括 Conversation、Skill、Scheduler、Notification |
| Skill | 可下发、可版本化、可执行的行业能力包 |
| Skill Bundle | skill 打包后的发布产物 |
| Manifest | skill 的声明式元数据 |
| Entitlement | 某酒店或客户已开通的能力权益 |
| LLM Proxy | NIANXX 服务端模型代理层 |
| Gateway | 本地 OpenClaw 服务进程 |
| Artifact | skill 或对话产生的结构化结果，如表格、报告、图片、文件 |
| Kill Switch | 服务端远程禁用某 skill 或某版本的能力 |

# 附录 B · OpenClaw 上游同步策略

## B.1 分支模型

建议保留三个长期分支：

| 分支 | 用途 |
|---|---|
| `upstream-main` | 镜像 ClawX 上游 main |
| `yinian-main` | 智念主开发分支 |
| `release/*` | 客户发布分支 |

同步流程：

1. 定期 fetch ClawX upstream
2. 更新 `upstream-main`
3. 创建 `sync/upstream-YYYYMMDD`
4. merge 或 cherry-pick 到 `yinian-main`
5. 跑完整 CI
6. 对冲突文件写同步记录

## B.2 改造边界

尽量少改上游核心文件，把 YINIAN 逻辑放入独立模块：

- `src/yinian/*`
- `electron/yinian/*`
- `packages/kernel-core`
- `packages/kernel-context`
- `packages/kernel-adapter-openclaw`
- `packages/ui-kit`

如果必须改上游文件，要求：

- 添加注释说明 YINIAN 修改原因
- 在同步记录中登记
- 对应测试覆盖

## B.3 上游能力取舍

保留：

- Gateway 生命周期基础能力
- 原有 channel 能力
- Cron / scheduler 能力
- Skill 加载机制
- Provider 抽象中可复用部分

替换或隐藏：

- 用户自填 API key
- 开发者 Marketplace
- 过度技术化设置页
- 不适合酒店用户的 debug 信息

# 附录 C · CI 强制规则清单

## C.1 依赖方向

必须强制：

- `kernel-core` 禁止 import OpenClaw
- Renderer 禁止 import `electron`
- Renderer 禁止 import Node 内置模块
- Renderer 禁止在 `bootstrap.tsx` 之外 import `kernel-adapter-openclaw`
- Skills 禁止 import App UI 代码
- Skill logic 只能依赖 `skill-spec` 和 `skills-hotel-core`

## C.2 安全检查

CI 必须检查：

- 无硬编码 API key
- 无硬编码生产 token
- skill manifest 包含 permissions
- skill bundle 构建产物可复现
- bundle hash 与 manifest.lock 一致
- preload 暴露 API 白名单

## C.3 测试

最低要求：

| 范围 | 要求 |
|---|---|
| `kernel-core` | 类型和 schema 测试 |
| Adapter | RPC 映射契约测试 |
| Main | Auth、Config、SkillManager 单元测试 |
| Renderer | 关键页面组件测试 |
| Skills | fixture、parser、规则、bundle 测试 |
| E2E | 登录、同步、运行 skill、查看报告 |

## C.4 发布检查

发布前必须通过：

- TypeScript typecheck
- ESLint
- 单元测试
- skill bundle 验签测试
- macOS 打包
- Windows 打包
- smoke test
- 诊断包导出测试

---

> **v0.3 后续建议**：下一轮评审重点放在第五章 UI 信息架构、第六章 API 权限模型、第八章 skill 安全边界。评审通过后即可拆分工程 tickets，进入 ClawX fork 改造。