@iniesta8888/agent-live 0.3.0

package/docs/COMPONENT-LIBRARY.md

@@ -0,0 +1,212 @@
+# Agent Live 基础组件库
+
+> 状态：当前内容架构 · 最后校准 2026-09-13
+
+## 1. 核心定义
+
+Agent Live 只维护一套基础组件全集，称为 **Component Library**。Official Preset 和 Custom Office 都不能私自定义另一套运行能力，只能从组件库中选择、实例化和覆盖允许的参数。
+
+```text
+Office Engine
+固定绘制、移动、事件和校验能力
+        ↓
+Component Library
+全部可复用的声明式组件
+        ↓
+Office Spec
+一间办公室的完整组装结果
+        ↓
+├── Official Preset
+└── Custom Office
+```
+
+“全集”表示所有可被组装器使用的能力都有唯一、可查询的登记，不表示页面启动时加载全部资源。Runtime 只加载当前 Office Spec 实际引用的组件，以保持本地性能。
+
+## 2. 五个正式概念
+
+| 概念 | 职责 | 是否可修改 |
+| --- | --- | --- |
+| Office Engine | 实现渲染、寻路、事件优先级和运行机制 | 只能修改源码 |
+| Component Library | 登记所有可以安全组合的基础组件 | 由项目开发者维护 |
+| Office Spec | 描述一间办公室最终使用哪些组件 | 由编译器生成并校验 |
+| Official Preset | 官方命名、测试并发布的只读 Office Spec | 普通用户只能选择 |
+| Custom Office | 用户通过 Creator 生成并保存在本地的 Office Spec | 用户可继续迭代 |
+
+此外还有一个辅助概念：
+
+- **Capability Catalog**：Component Library 面向 Agent 的机器可读索引，只公布真实实现并已通过校验的能力。
+
+Compiler 在内存中产生候选 Office 供校验，但这不是面向用户的 Draft、预览或保存状态。合法修改会原子保存并立即选择；失败时继续使用上一个有效 Office。
+
+## 3. 基础组件的共同合同
+
+每个组件只有一个职责和一个稳定 ID，并提供足够的信息让 Agent 选择、让编译器组装、让校验器拒绝非法组合：
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "prop",
+  "id": "builtin/water-cooler",
+  "name": "饮水机",
+  "description": "供角色接水的落地设施",
+  "version": "1.0.0",
+  "contract": "single-office-v1",
+  "tags": ["service", "water", "floor"],
+  "capabilities": ["water"],
+  "renderer": "water-cooler"
+}
+```
+
+共同规则：
+
+- `id` 在整个组件库中唯一，发布后保持稳定。
+- `kind` 决定字段合同，不能用额外字段绕过 Runtime 能力。
+- `description` 和 `tags` 面向 Creator Agent，不能只依赖文件名猜测用途。
+- `capabilities` 必须对应 Engine 已实现的能力词汇。
+- 组件只包含声明式数据，不包含任意 JavaScript、Shell、密钥或远程请求。
+- Renderer 不存在、兼容条件不满足或必需引用缺失时，组件不可进入 Office Spec。
+
+## 4. 组件全集的分类
+
+### 4.1 Style
+
+定义统一的美术语言：UI、Canvas、角色、状态和粒子色板。Style 不定义家具、坐标、NPC 和行为。
+
+Creator v1 只能选择已登记 Style，并覆盖白名单中的少量语义参数；不直接开放全部底层颜色 token。
+
+### 4.2 Layout（房间骨架）
+
+定义单层办公室的固定空间骨架：墙体、通道、座位、工作目标、区域和可放置插槽。Layout 是内容作者的概念，不是 Creator 的可选项——一个 Office 自带它的房间。
+
+Layout 必须提供：
+
+- 384×216 的 `single-office-v1` 逻辑画布。
+- 8 个可分配座位。
+- `research/create/compute/plan/communicate/collaborate` 六种工作落点。
+- 可达的入口、通道和 NPC 出生点。
+- 具名 Zone，例如 `work-area`、`lounge`、`service-area`。
+- 具名 Placement Slot，而不是让 Creator 生成任意坐标。
+
+插槽示例：
+
+```json
+{
+  "id": "lounge-decoration-1",
+  "zone": "lounge",
+  "accepts": ["plant", "dumbbell", "vending-machine"],
+  "maxSize": { "width": 18, "height": 28 },
+  "required": false
+}
+```
+
+### 4.3 Prop Type
+
+定义一种家具、设备或装饰物的尺寸、Renderer、能力标签和放置条件。Prop Type 不保存它在某间办公室里的坐标；Office Spec 只把它分配到 Layout 的合法插槽。
+
+### 4.4 Agent Skin
+
+定义真实 Agent 的角色画法、身份配色和 Engine 已支持的动作。它只能改变表现，不能创造不存在的 Agent 或状态。
+
+### 4.5 NPC Template
+
+定义可复用的非 Agent 角色，例如老板、保洁、前台、秘书和会务人员。模板包含默认身份、外观、允许活动和可覆盖字段；具体名称、班次和出生点由 Office Spec 实例化。
+
+NPC Template 不包含真实 `agentId`、工具调用、Token 和任务状态。
+
+### 4.6 Activity Recipe
+
+定义 Runtime 已实现的办公室生活序列，例如接水、聊天、散步、玩手机、上厕所、巡检和资料流转。
+
+Recipe 只能引用 Capability Catalog 中存在的参与者、Prop、Target、Pose、Particle 和 Step。真实 Work Event 始终拥有更高优先级。
+
+### 4.7 Atmosphere
+
+定义一种环境状态如何呈现，例如雨夜的色板、窗外粒子和环境声音。它回答“画成什么样”，不判断此刻是什么时间和天气。
+
+### 4.8 Environment Policy
+
+定义本地或固定时间、时间阶段、天气输入、自动照明和 NPC 班次。它回答“当前是什么状态”，不包含美术资源或空间坐标。
+
+## 5. Engine 能力词汇
+
+以下不是可以任意添加的内容组件，而是 Office Engine 已实现并由 Capability Catalog 公布的有限词汇：
+
+| 能力 | 当前词汇 |
+| --- | --- |
+| Work Semantic | `research/create/compute/plan/communicate/collaborate` |
+| Weather | `clear/cloudy/rain/snow` |
+| Character Pose | `stand/sit/walk/type/reach/talk/phone` 中 Renderer 实际支持的子集 |
+| Particle | `key/paper/check/bang/cross/spark` |
+| Participant | `agent/npc`，可附加状态、角色和最少人数约束 |
+
+只有代码已实现、共享校验器能验证、至少一个回归用例能覆盖的词汇，才可以出现在 Capability Catalog 中。文档示例不能单独构成可用能力。
+
+## 6. Office Spec
+
+Office Spec 是 Preset 与 Custom Office 共用的最终组装合同。目标形态如下：
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "local/night-tech-office",
+  "name": "雨夜 Tech 办公室",
+  "layout": "builtin/tech-open-office",
+  "style": "builtin/pixel-classic",
+  "agentSkin": "builtin/tiny-developers",
+  "placements": [
+    { "component": "builtin/water-cooler", "slot": "lounge-service-1" },
+    { "component": "builtin/dumbbell", "slot": "lounge-fitness-1" }
+  ],
+  "npcs": [
+    {
+      "template": "builtin/cleaner",
+      "id": "cleaner-lin",
+      "name": "林姨",
+      "spawn": "service-entry",
+      "shift": { "start": "20:00", "end": "06:00" }
+    }
+  ],
+  "activities": ["builtin/get-water", "builtin/phone-break"],
+  "atmosphere": "builtin/rainy-night",
+  "environment": "builtin/local-office-environment"
+}
+```
+
+这是当前 Office Seed/Spec 合同的概念示例。实际输入还必须带 `kind`，实例化物件必须带唯一 `id`；最终以 `src/content/schema.ts` 为准。Official Preset 和 Custom Office 已由同一个 Compiler 与 Validator 解析。
+
+## 7. Preset Office 与自定义
+
+运行 `/agent-live custom` 后，宿主 Agent 会根据描述选择最接近的 Preset Office 作为起点：
+
+```text
+tech（科技）
+meetingroom（会议室）
+oldschool（格子间）
+你的 Custom Office
+```
+
+- 选择一个 Preset Office：加载它的 Office Spec，再生成受限制的差异。
+- 对 Preset Office 动第一笔改动，就会生成一个内容完整继承的 Custom Office：房间、摆放、NPC、活动和组件全都带过来。
+
+一个 Office 自带它的房间，**房间不单独提供、也不支持就地更换**。想换房间就是选中那个 Preset Office 再编辑——和改任何其它东西的成本一样。Layout 因此只是内容作者的概念（见 [Preset 配置手册](PRESET-CONFIG.md)）。
+
+## 8. 当前内置能力盘点
+
+当前 Component Library 已经具备以下内容基础：
+
+| 组件族 | 当前数量 | 备注 |
+| --- | ---: | --- |
+| Style | 2 | 经典像素、暖调工作室 |
+| Layout | 5 | 其中 3 套为正式用户 Preset |
+| Agent Skin | 2 | 共享程序化像素人物 |
+| Prop Type | 32 | 唯一组件 ID、尺寸、renderer 与能力声明已集中登记 |
+| NPC Template | 6 | 支持默认身份、性别、外观、班次与确定性随机 Profile |
+| Life Activity | 14 | 17 个 Layout 实现共享统一 Activity Recipe |
+| Atmosphere | 2 | 默认、雨夜 |
+| Environment | 3 | 本地动态、静态兼容、固定雨夜 |
+
+这些能力已经供三个 Official Office 和 Custom Office 共用。自由组合仍受 Layout 的 Zone、Placement Slot、NPC Spawn、活动实现和全局容量上限约束。
+
+## 9. 当前实现状态
+
+上述迁移已经完成：组件唯一 ID、NPC Template、Activity Recipe、Zone、Placement Slot、统一 Validator、Office Spec 编译、Official Office 重建，以及 Custom Office 的原子保存与失败隔离均已进入主线。当前没有面向用户的 Draft、预览、撤销或确认保存流程。新增组件时应扩展 Library 与对应 Renderer/Runtime 能力；Creator 不会生成未登记组件或任意坐标。

package/docs/CUSTOMIZATION.md

@@ -0,0 +1,163 @@
+# Agent Live 自定义能力边界
+
+> 状态：完整 Office 自定义、持久选择与文字区 · 2026-09-12
+
+官方顺序固定为 tech（科技）、meetingroom（会议室）、oldschool（格子间），自定义 Office 排在后面。使用列表中的编号或唯一的完整名称；同名 Office 请使用编号。Pi、DSH 和本地网页读取同一 Registry 顺序。网页选择也会保存，重新启动读取已选 Office。
+
+### 文字与空物件位
+
+三个正式 Office 各提供 3 个默认空闲的物件位：两个绿植位，以及一个饮水机/售货机位；另有通用 staff-entry。具体容量和可选类型通过 Creator 的 list_components.room 获取。
+
+每个 Office 还提供 company（公司铭牌/文字 Logo）、notice（公告）和 slogan（区域标语）三个文字区，默认留空。用户可以说“公司牌写蜗牛科技，公告写今天专注交付”。模型映射为：
+
+```json
+{ "texts": { "company": "蜗牛科技", "notice": "今天专注交付", "slogan": "一起完成" } }
+```
+
+公司名上限 24 字符，公告和标语各 48 字符。只接受单行纯文本，禁止模型提供坐标、HTML 或图片路径。文字显示在房间预留牌面上；空间不足时显示省略号。未提供的字段保留，空字符串隐藏该区域，texts: null 清除全部自定义文字。图片 Logo 尚未在本轮开放。
+
+文字与家具、NPC 一起经过校验并持久化，不需要预览或确认保存。未知文字区及超长输入会拒绝该次修改，当前 Office 保持原样；模型应在工具失败后修正输入。
+
+## 1. 适用范围
+
+普通用户只选择官方只读 Preset。支持会话上下文注入的宿主通过 `/agent-live custom` 显式进入多轮自定义，并通过 `/agent-live exit` 明确退出；普通模式下的自然语言不应被误判成办公室修改。
+
+自定义使用 Coding Agent 已经配置的模型与 Provider。Agent Live 不要求用户再次填写 API Key，不保存 Provider 凭证，也不自行调用云端模型。
+
+自定义模式的目标是：**把用户的自然语言稳定映射到 Agent Live 已经实现的声明式能力，而不是让模型自由修改产品源码。**
+
+## 2. 两种内容状态
+
+| 状态 | 含义 | 是否可直接使用 |
+| --- | --- | --- |
+| Official Preset | 官方发布、只读并经过完整回归的办公室 | 是 |
+| Custom Office | 由 Creator 原子校验、保存并选择的本地办公室 | 是 |
+
+Custom Office 由某个 Official Preset 派生：第一笔改动就会生成一个内容完整继承的副本（房间、摆放、NPC、活动、组件全都带过来），不覆盖安装目录中的官方文件。校验或保存失败时，当前有效版本保持不变。
+
+Creator 只从最接近的 Official Preset 修改，用户不需要先理解内部 Schema，也不需要手工选择每个组件。公开命令只有四条：
+
+```text
+/agent-live list presets
+/agent-live preset <number or name>
+/agent-live custom
+/agent-live exit
+```
+
+“给我做一个警察局”这类需求的处理方式：**先选中最接近的完整 Preset Office，再修改名称、人员与身份、家具、风格和活动**；“警察局”这个说法本身不产生新的房间结构。如果用户要求的是全新的房间结构（新的墙体、区域、通道、座位或工作落点），统一回答：**这需要新增一个 Office Preset，需要修改源码**，Creator 不做这件事。
+
+一个 Office 自带它所在的房间，**房间不能单独更换**：想换房间就是换一个 Preset Office（`/agent-live preset <number or name>`），或者编辑那个 Preset Office 得到一份自己的副本。Layout 因此是内容作者（Component Library）的概念，不是 Creator 的操作。
+
+Creator Mode 是会话级模态状态，但不是内容草稿状态。每次合法修改都会经过校验后直接生效；每轮回复都应提示 Creator Mode 仍在运行以及 `/agent-live exit`。模式内出现明显无关或指代不清的项目开发请求时不直接执行，而是让用户选择继续编辑、退出或列出 Preset。
+
+## 3. Creator v1 可以映射的能力
+
+| 用户表达 | 映射到 | 边界 |
+| --- | --- | --- |
+| “改成暖色、深夜、雨天” | Style / Atmosphere / Environment | 只使用已有视觉 token、天气类型和时间阶段 |
+| “桌面丰富一点” | Props | 从已有 Prop Type 中选择，并放入允许的区域或插槽 |
+| “增加老板、保洁或前台” | NPC | 只能选择 Capability Catalog 中已登记的 NPC Template |
+| “保洁晚上八点上班” | Environment / NPC shift | 使用有效 `HH:MM` 班次，支持跨夜 |
+| “空闲时去喝水或聊天” | Life Activities | 只组合已有参与者、target、pose、particle 和 step |
+| “把饮水机放到休息区” | Props / slot | 目标槽位必须存在，放置后不能阻断导航 |
+| “从 Tech 办公室开始” | Custom Office base | 引用已安装的 Preset Office，房间与内容完整继承 |
+| “换成会议室的房间” | 不支持就地更换 | 选中那个 Preset Office 再编辑；房间随它带来，成本与改别的东西相同 |
+
+Creator 可以调整和组合现有能力，但不能因为自然语言中出现了一个新名词，就假设 Runtime 已经具备对应实现。
+
+## 4. Creator v1 不开放的能力
+
+以下需求不能在声明式自定义中直接生成：
+
+- 全新的家具 renderer、人物画法、精灵图或动画系统。
+- 当前不存在的天气、粒子、声音机制或 Life Activity step。
+- 新的 Work Semantic、Agent 状态或宿主事件协议。
+- 寻路、碰撞、座位分配、事件优先级和 Office Runtime 规则。
+- 多楼层、多建筑、自由镜头或不同空间引擎。
+- 页面组件、配置编辑器、Connector 或其他程序代码。
+- 任意 JavaScript、Shell 命令、远程资源和未经批准的本地文件。
+
+自定义 Agent 不得通过偷偷增加字段、输出脚本或修改源码来绕过边界，也不能把没有实现的效果描述成“已经完成”。
+
+## 5. 所有用户输入的处理规则
+
+Agent 必须先把一次输入拆成独立需求，再逐项分类：
+
+### A. 精确映射
+
+现有能力能够直接表达时，映射为一次受限 Office Patch，并原子应用到所选基础 Office。
+
+### B. 边界内的近似映射
+
+没有同名能力但已有能力可以形成接近效果时，Creator 不在生成过程中逐项打断用户。修改完成后统一说明原始要求、采用的现有能力以及视觉或行为差异；用户可以继续调整。
+
+### C. 无法映射
+
+需求需要新增代码或运行机制时，Agent 必须：
+
+1. 不把该项写入 Office Patch。
+2. 明确说明它超出 Creator v1 的声明式能力。
+3. 保留同一输入中其他可以实现的部分。
+4. 告诉用户需要查看或修改源码，并指出最相关的入口。
+
+混合需求应返回一张简短清单，例如：
+
+```text
+可以直接实现：调整保洁班次、切换雨夜。
+可以近似实现：把“霓虹招牌”映射为现有墙面装饰，需要你确认。
+需要新增组件或修改源码：增加当前未登记的保安、闪电天气和人物跳舞动画。
+```
+
+## 6. 源码入口指引
+
+| 超出边界的需求 | 建议查看的源码 |
+| --- | --- |
+| 新家具、新区域视觉或新天气特效 | `plugins/agent-live/web/v2/office-renderer.js`、`plugins/agent-live/web/v2/content/props/` |
+| 新人物画法或动画 | `plugins/agent-live/web/v2/sprite-renderer.js`、`plugins/agent-live/web/v2/content/agent-skins/` |
+| 新生活行为机制或 step | `plugins/agent-live/web/app.js`、`plugins/agent-live/web/v2/content/life-activities/` |
+| 新工作语义或工具映射 | `plugins/agent-live/src/core/protocol.ts`、`plugins/agent-live/src/core/mapping.ts`、`plugins/agent-live/web/app.js` |
+| 新宿主事件或 Connector | `packages/pi/src/adapter.ts`、`plugins/agent-live/src/core/protocol.ts` |
+| 新空间合同、寻路或碰撞规则 | `plugins/agent-live/web/v2/office-renderer.js`、`docs/OFFICE-THEMES.md` |
+| 新时间、天气或班次机制 | `plugins/agent-live/web/v2/environment-runtime.js`、`plugins/agent-live/web/v2/content/environments/` |
+
+查看源码意味着退出受约束的 Creator 流程，进入正常的软件开发流程。Creator Agent 只能解释入口，不能自动获得修改这些机制的权限。
+
+## 7. 生成与验收门
+
+每轮自定义必须按以下顺序执行：
+
+```text
+用户输入
+→ 能力分类
+→ 映射与边界内自动修复
+→ 生成受限 Office Patch
+→ Schema 校验
+→ 内容引用校验
+→ 导航引用、座位数量与组件容量校验（当前不做几何碰撞校验）
+→ NPC 与 Life Activity 校验
+→ Environment 校验
+→ 原子保存并选择 Custom Office
+→ 页面重新加载有效内容
+```
+
+任何强制校验失败都不能进入下一步。Agent 可以自动修复仍处于能力边界内的问题；如果修复需要修改源码，则必须停止并按“无法映射”处理。
+
+只有满足以下条件才能说“已经完成”：
+
+- Office Patch 与生成的 Office Spec 符合约定 Schema。
+- 所有引用的内容能力真实存在。
+- 必需工作语义、座位和主要路线仍然可用。
+- NPC 班次、出生点与 Life Activity 目标有效。
+- 新 Office 可以被 Runtime 解析；失败时旧版本保持有效。
+
+## 8. 安全边界
+
+- 模型输出只是候选数据，不能直接作为可信配置运行。
+- Creator 只允许调用 Agent Live 提供的受限工具，不直接写官方 Preset。
+- Creator Mode 只保存在当前宿主进程内存中，并按宿主会话隔离；退出命令、宿主会话结束或插件卸载都会清理。
+- API Key 和 Provider 配置始终由 Coding Agent 管理。
+- Custom Office 不得包含密钥、会话内容、真实代码或绝对文件路径。
+- 外部天气等数据由宿主标准化后注入，内容配置不主动联网。
+- 先在内存中完成校验，再以原子写入替换文件；失败时不写入无效版本。
+
+这份边界同时约束 Creator Skill、模型输出 Schema、校验器和未来的自定义工具实现。

package/docs/DEVELOPER.md

@@ -0,0 +1,186 @@
+# Agent Live 开发者接入指南
+
+> 面向 Preset 作者、宿主 Adapter 开发者和本地二次开发者
+
+接入新的 Coding Agent 时，请先阅读专项指南：[Agent Live Adapter 开发指南](ADAPTER-DEVELOPMENT.md)。本页保留项目的综合开发入口，不重复完整的宿主调查、能力声明、事件映射和验收流程。
+
+普通用户只选择官方 Preset；自然语言创作用户遵守 [自定义能力边界](CUSTOMIZATION.md)。Official Preset 和 Custom Office 最终都从同一套 [基础组件库](COMPONENT-LIBRARY.md) 组装；声明式 Creator 不会自动修改本页涉及的 Runtime 源码。
+
+## 1. 十分钟跑起来
+
+使用当前 Node.js 22 LTS 补丁版本；源码校验直接执行 TypeScript，发布包与 DSH 嵌入页面有构建步骤。
+
+```bash
+git clone https://github.com/ssssnail/agent-live.git
+cd agent-live
+npm ci
+npm run check
+npm run preview
+```
+
+打开终端输出的 `/v2.html?demo=1` 地址。独立 Viewer 直接加载 ES modules 与本地 JSON；项目没有数据库或云端服务。
+
+## 2. 先选择你的接入层
+
+| 目标 | 主要入口 | 通常需要修改 |
+| --- | --- | --- |
+| 新增办公室 Preset | `plugins/agent-live/web/v2/content/` | 只改 JSON |
+| 接入新的 Agent 宿主 | [Adapter 开发指南](ADAPTER-DEVELOPMENT.md)、`plugins/agent-live/src/adapters/` | 把宿主官方接口提供的事实翻译成 `OfficeEvent` |
+| 调整工具语义 | `plugins/agent-live/src/core/mapping.ts` | 工具名到 `OfficeAction` 的映射 |
+| 新增家具画法 | `plugins/agent-live/web/v2/office-renderer.js` | Renderer + Props 声明 |
+| 新增人物动画 | `plugins/agent-live/web/v2/sprite-renderer.js` | Renderer + Agent Skin 声明 |
+| 注入真实天气/时间 | `OfficeEnvironment` | 不需要修改 Renderer |
+| 扩展自然语言自定义能力 | `plugins/agent-live/src/content/`、`plugins/agent-live/src/creator/` | Schema、Library、Compiler 与受限命令 |
+
+宿主接入与内容制作相互独立：Adapter 只报告“谁在做什么”，Preset 决定这件事在当前办公室如何表现。
+
+## 3. 当前内容图与统一架构
+
+当前可运行版本中，一个 Preset 组合八类内容：
+
+```text
+Preset
+├── Style             页面和像素画法
+├── Layout            空间、座位、导航、区域和目标点
+├── Agent Skin        真实 Agent 外观
+├── Props             可实例化物件类型
+├── NPC               非 Agent 角色
+├── Life Activities   本地生活行为
+├── Atmosphere        环境的视觉覆盖与音效
+└── Environment       时钟、天气输入、灯光和 NPC 班次
+```
+
+完整字段说明见 [Preset 配置手册](PRESET-CONFIG.md)。配置目录内也有一份就近说明：[Content README](../plugins/agent-live/web/v2/content/README.md)。
+
+当前 Creator 与运行时共用以下内容架构：
+
+```text
+Component Library
+        ↓
+统一 Compiler + Validator
+        ↓
+Official Preset / Custom Office
+```
+
+组件作者应优先遵守 [基础组件库](COMPONENT-LIBRARY.md) 中的唯一 ID、职责分离、Capability Catalog、Zone 和 Placement Slot 约束。
+
+## 4. Environment 公共配置
+
+Environment 是所有 Preset 共用的运行规则，不包含坐标或美术资源。内置正式 Preset 共用 `environments/local-office.json`：
+
+```json
+{
+  "render": { "dynamicTime": true, "dynamicWeather": true },
+  "clock": {
+    "mode": "local",
+    "phases": [
+      { "id": "morning", "start": "06:00" },
+      { "id": "noon", "start": "11:00" },
+      { "id": "evening", "start": "17:00" },
+      { "id": "night", "start": "20:00" }
+    ],
+    "preview": { "enabled": true, "startTime": "06:00", "durationMs": 24000 }
+  },
+  "weather": {
+    "source": "runtime",
+    "fallback": "clear",
+    "allowedConditions": ["clear", "cloudy", "rain", "snow"]
+  },
+  "lighting": { "enabled": true, "activePhases": ["evening", "night"] },
+  "npcSchedule": {
+    "enabled": true,
+    "defaultShift": { "start": "06:00", "end": "18:00" },
+    "roleOverrides": {}
+  }
+}
+```
+
+NPC 默认使用公共班次。按角色覆盖夜班：
+
+```json
+"roleOverrides": {
+  "security": { "start": "18:00", "end": "06:00" }
+}
+```
+
+单个 NPC 还可以在 NPC 条目中用 `shift` 做最后一级覆盖：
+
+```json
+{
+  "id": "night-guard",
+  "role": "security",
+  "shift": { "start": "20:00", "end": "08:00" }
+}
+```
+
+班次优先级为：单个 NPC `shift` > `roleOverrides` > `defaultShift`。
+
+## 5. 注入外部天气和调试时间
+
+核心不会主动访问天气服务。Connector 获取到外部数据后，只传标准条件给本地页面。
+
+URL 方式适合调试或启动 WebView：
+
+```text
+/v2.html?preset=tech-open-office&weather=rain
+/v2.html?demo=1&preset=tech-open-office&time=19:00&weather=snow
+```
+
+运行时方式适合已经打开的 WebView：
+
+```js
+window.OfficeEnvironment.update({ weather: "cloudy" });
+window.OfficeEnvironment.update({ time: "18:00" });
+
+window.dispatchEvent(new CustomEvent("agent-live:environment", {
+  detail: { weather: "rain" }
+}));
+```
+
+支持的天气为 `clear`、`cloudy`、`rain`、`snow`。传入未知值或无效时间会抛出明确错误。传 `null` 可清除运行时覆盖并回到 Environment 配置。
+
+## 6. 新建 Preset
+
+1. 从最接近的现有 Preset 和内容模块复制一份。
+2. 给每个新文件设置唯一 `id`，不要修改冻结的 `demo-office`。
+3. 在 Preset 的 `content` 中填写八个文件引用。
+4. 在 `catalog.json` 登记 Preset。
+5. 运行 `npm run check`。
+6. 打开 `/v2.html?demo=1&preset=<id>` 检查人物、路径、气泡和日夜切换。
+7. 打开 `/v2/parity.html`，确认显示 `PASS 15 pixel parity cases`。
+
+## 7. 接入新的 Agent 宿主
+
+Adapter 应把宿主能力归一为稳定的 `OfficeEvent`，不要直接控制人物坐标。完整流程和验收门见 [Adapter 开发指南](ADAPTER-DEVELOPMENT.md)：
+
+```text
+宿主事件 → Adapter → OfficeState → SSE → 固定 Runtime → 当前 Preset
+```
+
+最低可用事件是 `snapshot`、`agent_state`、`action/action_end` 和 `say`。支持委派时再发送 `agent_join`、`delegate`、`agent_leave`。前端通过 Layout 的 `stations` 决定动作是在工位完成、去服务器，还是采用会议室的坐席交接，不需要宿主了解画面结构。
+
+协议和 Pi 的完整映射见 [技术文档](TECHNICAL.md)。
+
+### Creator 接入
+
+新的宿主不需要实现另一套 Creator。Adapter 只需提供三件事：
+
+1. 把 Creator Tool/Skill 暴露给宿主模型，并让模型只调用 `CreatorCommandRouter` 的受限操作。
+2. 宿主支持会话级 prompt hook 时，使用 `CreatorModeRegistry` 和 `CREATOR_MODE_CONTEXT`，提供明确的 `custom / exit` 命令；不支持时采用单轮显式自定义。
+3. 有效修改立即保存并生效，没有预览、保存确认、放弃或回退步骤。退出自定义、宿主会话结束或关闭集成时清理模式状态。
+
+Pi 使用 `before_agent_start`，DSH 使用官方 system prompt 接口；Codex 使用单轮显式 Skill，不安装上述生命周期 Hook。`OfficeContentService`、`CreatorService`、`CreatorCommandRouter` 已通过公共 SDK 导出。完整接线与隔离测试见 [SDK 手册](ADAPTER-SDK.md) 和 [可运行示例](../examples/adapter/local-office.mjs)。Adapter 不解析或修改 Office Spec，也不能绕过 Compiler 与 Validator。
+
+## 8. 提交前检查
+
+```bash
+npm run validate:content
+npm run validate:environment
+npm run check
+```
+
+- 配置引用、座位、目标点、Props、NPC 和 Life Activity 会被静态校验。
+- Environment 测试覆盖天气覆盖、18:00 下班和跨夜班次。
+- 原版 Demo 由浏览器像素回归页单独保护。
+
+不要在内容 JSON 中加入真实网络请求、密钥或用户数据。Agent Live 的默认安全边界始终是本机 `127.0.0.1`。