RP API + Local Docs Test

🧭 本工具是什么

MZ RP DM Local 是一个零依赖、单文件、浏览器本地运行的 RP 桌面 DM 控制台。所有档案存储在本机 IndexedDB，只有 Prompt Preview 中显示的内容会发送给 API，完全不依赖任何后端服务器。

⚙️ 不需要的东西

• 不需要后端，不需要 WSL，不需要 npm，不需要 Node.js
• 不需要安装任何依赖，不需要 Apple Developer 证书（99 美金）
• 直接用浏览器打开 index.html 即可使用

🚀 正式使用流程

• 1. 导入文档：Local Documents 标签 → Import（.txt/.md）或 Official Intake → Paste Document Import
• 2. 设置 documentRole：rules / characters / archive / misc，角色档案必须设为 characters
• 3. App Health 检查：App Health 标签 → Run App Health Check，确认核心状态绿色
• 4. Core Recall Test：Official Intake 标签 → 填写核心角色名 → Run Core Recall Test
• 5. Retrieval Diagnostics：🔬 Retrieval Diagnostics → 确认角色锚点命中
• 6. Build Prompt Preview：DM Round → 填写 Scene State + User Input → Build Prompt Preview
• 7. 确认预算：检查 Prompt 字符数和估算 Tokens 是否在预期范围内
• 8. Run DM Round：确认 Run Readiness 全绿 → Run DM Round → 弹窗确认
• 9. 检查 STATE_PATCH_JSON：查看 Scene Patch Preview 的 Before/After 对比
• 10. Apply / Reject Patch：确认合理再 Apply，有疑问先 Reject 或 Edit
• 11. 定期备份：App Health 标签 → Export Full Backup

🧠 Session Memory 使用说明

• 完整消息历史本地保存在 IndexedDB，永不自动进入 Prompt
• DM Round Prompt 只携带：最近少量原文消息 + 长期摘要（最新一条）+ 相关重要事件
• 定期手动创建 Summary：Session Memory → Create Manual Summary，把最近剧情压缩成摘要
• 也可点击 Generate Summary From Recent Messages，由 AI 生成摘要草稿，审核后手动保存
• 重大事件必须写入 Important Events：任务、契约、债务、物品、伤势、关系变化，都应手动记录
• Memory Budget Settings 可控制进入 Prompt 的消息条数和字符上限
• Export Full Backup 会同时导出 sessionSummaries 和 importantEvents

📱 iOS / iPhone 使用说明

• 若要在 iPhone 上像 App 一样添加到主屏幕，需要将 index.html + manifest.webmanifest + sw.js 放到支持 HTTPS 的静态托管服务（如 GitHub Pages、Vercel、Cloudflare Pages）
• 通过 HTTPS 地址在 Safari 打开 → 分享按钮 → 添加到主屏幕
• 不需要 Apple Developer 99 美金账号，不需要 Mac

🔒 安全说明

• 本地文档只保存在 IndexedDB（当前浏览器，不跨设备）
• 只有 Prompt Preview 中显示的内容会发送给 API，完整文档不会上传
• API Key 默认只存在本机 localStorage
• Export Full Backup 时默认不包含 API Key，除非手动勾选
• 不要把包含 API Key 的 backup 文件发给别人

💰 成本控制

• 每次 Run 前查看 Build Prompt Preview 的字符数和估算 Tokens
• 查看 📊 Usage 标签了解历史用量
• 开启 Emergency Safe Mode（App Health 标签）可完全阻止任何 API 调用
• DM Round 的 Hard Stop Characters 设置可防止意外发送超大 prompt

📁 file:// 模式说明

直接双击打开 index.html 时处于 file:// 模式。此模式下 Service Worker 无法注册，但所有本地功能（IndexedDB、搜索、备份、DM Round API 调用）均正常工作。

⚠ file:// 模式可用于本地测试，但不能安装为完整 PWA。若要在 iPhone 添加到主屏幕，需要通过 HTTPS 静态托管访问。

🔧 Tool Bus v1 使用说明

• DM 回复中若含 TOOL_REQUEST_JSON 块，系统自动解析并暂存到 Tool Bus 标签
• 点击 Execute All 在本地执行所有待处理请求（掷骰、风险检定、数值变更），结果写入 IndexedDB toolResults
• 支持三种工具类型：dice_roll（XdY 格式，支持 advantage/disadvantage）、risk_check（骰值 vs DC）、meter_change（数值加减）
• 工具结果会在下一次 Build Prompt Preview 时自动注入 [TOOL RESULTS] 区块，供 AI 参考
• Emergency Safe Mode 只阻止 API 调用，不阻止本地 Tool Bus 执行

📦 Inventory 物品栏说明

• 物品存储在 IndexedDB inventoryItems，字段：name / category / qty / owner / location / status / tags / effects / notes
• DM 回复中若含 INVENTORY_PATCH_JSON 块，系统会在 DM Round 面板显示 Inventory Patch Preview
• Patch 支持三种操作：upsert（新增或更新）、remove（删除）、delta（数量增减）
• 点击 Apply 后修改立即写入本地；Reject 丢弃；Edit JSON 可手动修改 patch 内容再 Apply
• Inventory 标签支持按 category/status/owner 过滤，以及 JSON 导入导出

📋 Task Board 任务板说明

• 任务存储在 IndexedDB tasks，字段：title / status / priority / progress / relatedCharacters / relatedLocations / relatedItems / blockers / notes
• DM 回复中若含 TASK_PATCH_JSON 块，系统显示 Task Patch Preview
• Patch 支持：upsert（按 title 匹配，不存在则新建）、remove（按 id 或 title 删除）
• Status 枚举：active / completed / blocked / abandoned；Priority：high / medium / low
• Tasks 标签支持按 status/priority 双重过滤，以及 JSON 导入导出

📊 Custom Panels 自定义状态栏说明

• 面板存储在 IndexedDB customPanels，字段：name / type / value / min / max / unit / tags / visible / notes
• DM 回复中若含 PANEL_PATCH_JSON 块，系统显示 Panel Patch Preview
• Type 枚举：number（纯数值）、bar（进度条，需 min/max）、text（文本标签）
• 只有 visible: true 的 Panel 会被注入 Prompt Preview 的 [PANELS] 区块
• Panels 标签分两区：当前可见面板（快速查看）和所有面板列表（CRUD）

🧩 MEMORY_PATCH_JSON 说明

• DM 回复中若含 MEMORY_PATCH_JSON 块，系统显示 Memory Patch Preview
• 支持字段：suggestedSummaryNote（建议摘要文本）、newEvents（建议写入的重要事件列表）
• Apply Memory Patch 会自动创建 Summary 和 ImportantEvents，无需手动到 Session Memory 标签操作
• 和 STATE_PATCH_JSON 一样，支持 Edit JSON 后再 Apply

⚡ STATE_PATCH_JSON 风险策略说明

• riskLevel：low（自动安全）/ medium（建议确认）/ high（强制人工审核）
• requiresUserConfirmation: true：系统会在 Apply 前弹出二次确认
• autoApplyRecommended: true：AI 认为可自动应用，但最终控制权在用户
• 高风险 patch（riskLevel=high）的 Apply 按钮样式会变为警告色，提示谨慎操作

🤖 输出协议说明（Output Protocol）

• 每次 DM 回复包含叙事正文 + 最多 6 个机器码块（按此顺序）：
• TOOL_REQUEST_JSON → STATE_PATCH_JSON → INVENTORY_PATCH_JSON → TASK_PATCH_JSON → PANEL_PATCH_JSON → MEMORY_PATCH_JSON
• 如果某块无内容，AI 输出空结构（如 {} 或 {"requests":[]}），系统会静默跳过
• 所有块均为标准 Markdown 代码围栏格式：```BLOCK_NAME ... ```

⚙️ Automation Mode（自动化模式）

• Manual（手动）：所有 patch 均需手动点击 Apply，系统不自动执行任何操作。
• Assisted（辅助）：低/中风险 patch 自动入队 Pending Queue，高风险仍需手动确认。
• Auto Pilot（自动驾驶）：符合风险策略的 patch 直接自动应用，其余入队。

🎯 Risk Classifier（风险分类器）

• low（低风险）：inventory add/quantity 变更、task add（非删除）、panel add（非删除）。
• medium（中风险）：scene patch（含 presentCharacters/activeTasks 等核心字段）、task status 变更。
• high（高风险）：memory patch（全部）、inventory/task/panel delete/remove、未知类型。

⏳ Pending Queue（待处理队列）

• Assisted/Auto Pilot 模式下，不满足自动应用条件的 patch 会进入 Pending Queue。
• 可逐条 Apply/Reject，也可批量操作（Apply All Low Risk / Apply Selected / Reject Selected）。
• 已处理的条目可通过 Clear Resolved 清理。

📋 Automation Audit Log（自动化审计日志）

• 每次自动应用或入队操作均写入审计日志，含 batchId、patchType、risk、result。
• Undo Last Batch 可撤销最近一批次的日志标记（注意：不回滚已写入 DB 的数据）。
• 支持导出 JSON 和清空日志。

🧪 Self Test Suite（自检套件）

• 8 项本地测试，零 API 调用，验证 Protocol Parse / Tool Bus / 各 Patch 类型 / Backup Integrity。
• 每项测试 3 秒超时，结果显示 ✅/⚠️/❌。
• 建议在首次使用或升级后运行一次全量自检。

⚡ Post-Turn Summary（轮次后摘要）

• 每次 DM Round 成功后，Post-Turn Summary 卡片自动显示本轮自动化处理结果。
• 显示自动应用数、入队数、跳过数、失败数，以及每个 patch 的处理详情。
• Auto Continue 倒计时：仅在 Automation 设置中明确开启时触发，点击倒计时条可取消。

🚫 Emergency Safe Mode 与自动化

• Emergency Safe Mode 开启时，Post-Turn Pipeline 不执行任何自动应用，Auto Continue 被完全阻断。
• Automation Policy 中的 Emergency Block 选项默认开启，与 Safe Mode 联动。
• Safe Mode 是最高优先级保险，任何自动化逻辑均无法绕过。

📜 正式档案只读原则（Archive Read-Only Protocol）

• documentRole 为 rules / characters / archive 的正式文档是原始来源，不得被任何 AI patch 自动修改、覆盖或删除。
• Session Summary 只作为当前运行简报；Important Events 只作为结构化索引卡片；二者都不能取代原始档案。
• 若摘要与原始档案冲突，以原始档案为准。
• Memory Patch、Scene Patch、Task Patch 不得修改或删除原始文档。