EdgeHippo · Web 控制台（EdgeMemory Studio）设计与开发任务书

1. 执行摘要：三条架构决策与四条硬发现

Web 控制台不设自有服务器。LLM 与 embedding 请求由浏览器直接发到用户自选的厂商端点，灌库数据流由浏览器直接发到板子 IP 或 USB 端点。三个理由：

• 叙事一致。产品卖的是「私域记忆、数据不出设备」。如果灌库过程把所有内容过一遍我们的服务器，这个叙事当场自相矛盾，而且是竞品攻击时最好用的一个点。
• 零运维、零合规敞口。没有服务器就没有数据存储、没有出境传输、没有等保与备案问题。对早期团队这是实打实的成本。
• API Key 不经我们。Key 只存在用户浏览器 localStorage，用完可一键清除。

代价（必须提前处理）：板端 httpd 必须加 CORS 响应头并处理 OPTIONS 预检（否则浏览器 fetch 直连 http://192.168.1.46 会被同源策略拦死）；页面必须以 http 或 localhost 提供（https 页面请求 http 板子会触发 mixed content 拦截，现有 start_web.ps1 是本地 http，符合要求）。

一个容易被忽略的事实：浏览器无法访问 USB 大容量存储（MSC）设备——虚拟 U 盘是 OS 层概念，JS 没有 API 枚举或写入它。所以报告里那个很漂亮的「拖 .emf 进虚拟 U 盘」，在 Web GUI 里做不到，它是 OS 文件管理器的行为。

Web 端能做的是：生成 .emf → 让用户下载 → 引导他拖进 U 盘，并在页面上给出「插入后板子指示灯会蓝快闪，完成后变绿常亮」的确认提示。这个 UX 依然成立，只是执行者是操作系统而非浏览器。

用户说不出自己要什么知识库。向导的价值在于用苏格拉底式提问，把「我想要个知识库」逼成一份可执行规格：使用者是谁 / 杀手问题 10 条 / 红线 / 术语别名表 / 时效策略 / 答错代价。这六项决定了后面所有生成参数。第 5 章给出了可直接复制的完整 Prompt 文本。

1.1 四条硬发现（基于实机源码树核查）

2. 用户旅程：从「想要个知识库」到「板子可用」

3. 连接层：四通道统一抽象与浏览器硬约束

3.1 四通道能力对比

3.2 统一传输抽象（Transport 接口）

四条通道对上层暴露同一组方法，让向导与烧录逻辑完全不关心底下是 USB 还是 WiFi：

interface Transport {
  kind: 'webusb' | 'serial' | 'http' | 'ble';
  connect(opts): Promise<void>;
  disconnect(): Promise<void>;
  // 单行 JSON 命令（小数据）
  request(cmd: string, args?: object, timeoutMs?: number): Promise<any>;
  // 大块数据传输（灌库 / OTA）
  stream(payload: Uint8Array, onProgress: (sent, total) => void): Promise<Result>;
  // 能力协商结果
  caps(): Caps;
}

现有 protocol.js 的 request() 已经是这个形状，直接适配即可。stream() 是新增的——串口走分块命令、HTTP 走 POST body、WebUSB 走 bulk 批量端点。

3.3 能力协商（Caps）——连接后第一件事

不同板子（N16R8 / N8R8）、不同固件版本、不同引擎后端（emlite / emdb）参数都不同。连接后必须先拉一次能力，UI 才能正确显示容量上限与可选维度。

GET /api/caps  或  串口命令  sys.caps

{
  "device_id": "EME-21E980",
  "board": "devkit-n16r8",
  "form": "usb-dongle",        // 形态标识（gamma-card / usb-dongle），非角色
  "fw_ver": "0.9.3", "build_time": "2026-10-26T14:02",
  "engine": "emlite",              // 或 "emdb"
  "engine_ver": "0.1",
  "kb": {
    "capacity_entries": 12900,     // 由 edgemem 分区大小与每条字节数实时算出
    "used_entries": 4343,
    "used_bytes": 946176,
    "dim": 384, "dtype": "int8",   // 0/null = 尚未启用向量
    "vector_ready": false,
    "ts_region_bytes": 1441792
  },
  "transport": ["http","serial","webusb","ble"],
  "max_chunk": 4096,
  "features": ["kb_import","kb_export","ota","uf2"]
}

3.4 浏览器硬约束清单（写进 README，避免踩坑）

• WebUSB / Web Serial 仅在 Chrome / Edge（Chromium 内核）可用，且页面必须运行在 https:// 或 localhost / 127.0.0.1。Firefox 与 Safari 不支持——页面必须能优雅降级到「HTTP 通路 + 下载 .emf」。
• Mixed content：https 页面无法请求 http://192.168.1.46。所以 EdgeMemory Studio 必须以 http 或 localhost 提供（现有 start_web.ps1 符合）。若要上线到 https 域名，板端必须支持 HTTPS 或改为纯下载模式。
• CORS：板端响应头需含 Access-Control-Allow-Origin: *、Access-Control-Allow-Headers: Content-Type, X-OTA-Token、Access-Control-Allow-Methods: GET,POST,OPTIONS，并响应 OPTIONS 预检返回 204。
• Nagle + 延迟 ACK（沿用现有铁律）：板端响应必须合并成一次 send，httpd open_fn 设 TCP_NODELAY，否则分块灌库会从 10 fps 掉到 0.33 fps。
• USB-OTG 与 USB-Serial-JTAG 共用内部 PHY：切 TinyUSB 后不能再通过 USB 串口烧录与看日志，板 B 需常备 USB-UART 转换器，console 改走 UART0。这是 PCB 与开发流程层面的约束，不是 Web 端能绕过的。

4. 知识库生成向导：五步流程与信息架构

4.1 信息架构

EdgeMemory Studio
├── ① 设备（连接）
│     ├── 扫描 / 通道选择（自动 → WebUSB → Serial → HTTP → BLE）
│     ├── 设备卡片：EME-ID / 形态（form）/ 固件版本 / 容量水位条 / 引擎后端
│     └── 操作：断开、重启、store.map、备份导出
├── ② 新建知识库（向导）★ 核心
│     ├── Step 1 选场景模板
│     ├── Step 2 配置模型（LLM / embedding / 隐私档位）
│     ├── Step 3 关键词访谈（6 组问题 → 规格卡）
│     ├── Step 4 素材补充（可选）
│     └── Step 5 生成 + 审计 + dry-run
├── ③ 打包与烧录
│     ├── 条目表（可编辑 / 可删 / 可改 salience）
│     ├── 容量水位与裁剪建议
│     ├── 打包 .emf（含 CRC / schema_hash / 体积）
│     └── 一键烧录（自动选路 + 进度 + 断点续传）
├── ④ 验收
│     ├── P4 用例面板（20 条：10 应命中 / 5 应拒答 / 5 应未找到）
│     ├── 在板端实跑 + 命中率 / 拒答准确率
│     └── 导出验收报告
├── ⑤ 固件与更新
│     ├── 固件：OTA（HTTP）/ 串口（esptool-js）/ UF2 拖拽（β，P1）
│     ├── 知识库：HTTP 分块 / 串口分块 / USB bulk / 导出下载
│     └── 更新日志与回滚
└── ⑥ 设置
      ├── API Key 管理（脱敏显示、一键清除）
      ├── 隐私档位（云端 / 本地 / 离线）
      └── 高级：维度、量化、块大小、超时

4.2 五步流程详解

Step 1 · 选场景模板

Step 2 · 配置模型与隐私档位

Embedding 维度与板端 caps.dim 不一致时，前端必须做降维或重算提示：优先选支持「原生指定输出维度」的模型（如 text-embedding-v3 可直接要 256d），其次用 PCA（离线拟合，前端内置一个 384×256 投影矩阵即可）。不要盲目截断，截断前 256 维等于丢掉一半信息。

Step 3 · 关键词访谈（核心）

用 P1 Prompt 驱动，6 组问题，每组给候选。产出《知识库规格卡》JSON，用户可在右侧实时预览并手工改。

Step 4 · 素材补充（可选）

• 支持 PDF / Markdown / TXT / CSV 上传，浏览器内解析（PDF 用 pdf.js，注意体积）。
• 切块策略：按语义不按页。固定 512 字滑窗 + 标题继承（每块带上它所属的最近标题），避免「见上文」式不自洽条目——这正是 P0 硬约束第 1 条。
• 上传内容同样受 Step 2 隐私档位约束，页面在上传前再次确认。

Step 5 · 生成 + 审计 + dry-run

1. P2 生成：按规格卡生成条目，流式输出，前端边收边渲染预览。
2. P3 审计：语义重复合并建议、矛盾条目仲裁、不可离线验证条目剔除、自洽性检查。
3. P4 自生成验收用例：20 条（10 应命中含 3 条别名提问 / 5 应拒答 / 5 应未找到）。
4. 本地 dry-run：浏览器内用同一 schema 跑暴力 Top-K，给出预计命中率。不烧录就知道行不行。
5. 容量校验：条数 × 每条字节数 vs caps.capacity_entries；超限给出三种裁剪建议（降维 / 砍 salience<40 的条目 / 缩摘要到 60 字）。

5. 预设 Prompt 全集（P0–P5，可直接复制）

以下 Prompt 已按 EdgeMemory-MVP 的约束设计：容量上限、条目自洽、断网可用、拒答优先。花括号变量由前端在运行时注入：{CAP} 容量上限、{NCHARS} 每条字数上限、{DOMAIN} 领域、{SPEC} 规格卡、{MATERIAL} 素材。

5.1 P0 · 系统提示词（知识库架构师）

# 角色
你是一名「设备端知识库架构师」。你的产出将被编译成一个 .emf 碎片包，
烧录进一块 ESP32-S3 记忆外设（容量上限 {CAP} 条，每条 ≤ {NCHARS} 字），
在完全断网的环境下被现场人员检索。板子上不跑模型，只做检索。

# 硬约束（违反即作废，我会在编译前逐条校验）
1. 自洽：每条记忆脱离上下文单看也必须能被理解。禁止出现"如上所述""见前文"
   "参考第 3 节"这类指代表述。需要上下文时，把上下文写进这一条。
2. 可检索：每条必须含具体名词、型号、数值、动作步骤。禁止只有代词和形容词。
3. 不编造：素材中不存在的数值、型号、条款、日期，一律写 [待确认]，
   绝不猜测填充。编造一条比缺失一条危害大得多。
4. 配额：总量不超过 {CAP} 条。宁可少而准，不可多而泛。
5. 格式：输出严格 JSONL，每行一个对象。不要 markdown 代码块围栏，
   不要任何解释性文字，不要用逗号分隔多个对象。

# 你的成功标准
让一个身上只有这块板子的现场人员，在断网、嘈杂、戴手套的状态下，
问出正确的问题并得到可以直接照做的答案。
不是"信息全面"，而是"关键时刻答得对、不该答时不乱答"。

5.2 P1 · 关键词访谈（把用户逼成一份规格卡）

# 任务
帮用户定义一块"断网可用的设备端知识库"。不要问泛泛的问题。
用苏格拉底式提问，一次只问一组，每组给出 3-5 个候选让用户选或改。
如果用户的回答太模糊，就追问一个更具体的例子。

# 开场（先说这句，再问第 1 组）
"我先问 6 组问题，大约 3 分钟。答完我会生成一份规格卡给你确认，
然后才真正开始生成内容。你可以随时说'跳过'用默认值。"

## 第 1 组 · 使用者
这块板子挂在谁身上？他当时手上有别的东西吗？
 A. 现场维修工（戴手套、可能单手操作、环境嘈杂）
 B. 巡检员（走动中查看、时间紧张）
 C. 设备自身（机器查询自己的历史，无人类参与）
 D. 销售 / 客服（需要准确的报价与条款）
 E. 其他（请描述）

## 第 2 组 · 杀手问题（最重要，请多花时间）
请列出 10 个"如果这块板子答对这 10 个问题，用户就觉得值回票价"的问题。
要求：
 - 每个问题都写成现场人员真正会说的口语，不要书面语
 - 按"高频 × 高价值"排序，第 1 条是最关键的
 - 至少 3 条要包含具体故障现象或具体型号，不要全是泛泛而问
我会把它们直接作为验收测试用例。

## 第 3 组 · 红线
哪些问题它必须回答"我不知道"而不是猜？
（例如：涉及人身安全的参数阈值、超出本机型范围的规格、
未确认的价格与交期、需要实时数据才能判断的状态）
请给出 3-8 条，每条写成一句话的判据。

## 第 4 组 · 行话
这个领域里有哪些缩写、别名、俗称需要等价映射？
请给"标准术语 → 现场叫法"的对照，例如：
 "轴承外圈故障频率" → ["BPFO", "外圈频率", "外滚道"]
我会把别名写进同义词表，让用户用口语也能命中。

## 第 5 组 · 时效
哪些内容会过期？过期周期是多久？过期后应该：
 A. 删除  B. 降权（仍能命中但排后面）  C. 标注"可能已过期"后仍返回
请按内容类别分别说明。

## 第 6 组 · 错不起的程度
答错一条的代价是什么？
 A. 只是麻烦（降权即可）
 B. 造成返工（必须高准确率，宁可少答）
 C. 安全事故（宁可拒答，绝不猜测）

# 输出
把以上 6 组整理成一份《知识库规格卡》，严格输出这个 JSON（不要围栏）：
{
  "persona": "...",
  "killer_questions": ["...", "..."],       // 恰好 10 条
  "redlines": ["..."],                      // 3-8 条
  "glossary": [{"std": "...", "aliases": ["..."]}],
  "ttl_policy": [{"category": "...", "days": 0, "action": "delete|demote|annotate"}],
  "error_cost": "A|B|C",
  "domain": "...",
  "target_count": 0                          // 你建议的条数，不超过 {CAP}
}

5.3 P2 · 条目生成

# 输入
规格卡：{SPEC}
素材（可能为空）：{MATERIAL}
配额：{CAP} 条上限，建议 {target_count} 条

# 输出格式（严格 JSONL，每行一个对象）
{"id":"","text":"","summary":"","tags":[],"salience":0,
 "source":"","valid_from":"","ttl_days":0,"redline":false}

# 字段规则
- text    ：≤ {NCHARS} 字。自洽完整，含具体数值 / 型号 / 动作步骤。
            禁止"参见 xx"。需要上下文就把上下文写进来。
- summary ：≤ 40 字。仅用于结果列表展示，必须让人一眼判断要不要展开。
            不要写成 text 的截断，要写成"答案摘要"。
- tags    ：3-6 个。必须包含规格卡 glossary 里的现场叫法（别名），
            不能只写标准术语——用户是用口语搜的。
- salience：0-100。命中杀手问题或与红线相关的给 ≥80；
            术语表条目 50-70；纯背景知识 ≤40。
- source  ：素材文件名或 "generated"。无来源写 "synthetic"。
- ttl_days：0 = 永不过期；>0 表示 N 天后按 ttl_policy 处理。
- redline ：true 表示属于"宁可拒答"领域，检索时只在精确匹配时才返回。

# 生成顺序（严格执行，配额不足时从后往前砍）
1. 先覆盖全部 10 个杀手问题：每个至少 2 条，一正一反
   （正确做法 1 条 + 常见误判的反例 1 条）
2. 再补红线条目（每条红线至少 1 条）
3. 再补术语表的别名映射条目
4. 最后才用背景知识填满剩余配额

# 自检（生成完自己过一遍，把不合格的删掉重写）
- 有没有哪条脱离上下文读不懂？删掉重写。
- 有没有哪条含 [待确认]？保留但 salience 降到 30 以下。
- 有没有两条说的是同一件事？合并成一条。
- 10 个杀手问题是不是每个都能被至少一条命中？抽查一遍。

5.4 P3 · 冲突与去重审计

# 输入
条目集（JSONL）+ 规格卡 {SPEC}

# 任务
1. 找出语义重复（余弦相似度可能 > 0.95）的条目对，
   保留信息量更大、更具体的一条，输出合并建议（不要自行合并）。
2. 找出互相矛盾的条目（同一问题给出两个不同答案），
   标出并请求仲裁，不要自行取舍。
3. 找出"看似有用实则无法离线验证"的条目：
   依赖实时数据、外部链接、需要联网查询才能确认的，标记剔除。
4. 检查每条是否自洽（脱离上下文可读）。
5. 检查 tags 是否覆盖了 glossary 里的全部别名。

# 输出（严格 JSON，不要围栏）
{
  "duplicates": [{"keep": "id1", "drop": "id2", "reason": "..."}],
  "conflicts":  [{"a": "id1", "b": "id2", "question": "...", "need_arbitration": true}],
  "unverifiable": [{"id": "...", "reason": "..."}],
  "not_selfcontained": [{"id": "...", "reason": "..."}],
  "missing_aliases": ["..."]
}

5.5 P4 · 验收用例自生成

# 输入
条目集 + 规格卡（含 killer_questions 与 redlines）

# 任务
生成 20 条验收问句，必须覆盖三类：
  A. 10 条应命中（expect: hit）
     - 其中 3 条必须用别名 / 口语提问（考验同义词表）
     - 其中 2 条必须故意写错别字或用缩写（考验鲁棒性）
     - 每条标注期望命中的条目 id 与最低分
  B. 5 条应拒答（expect: refuse）——来自 redlines，
     期望板子返回"不提供判断"而不是硬凑一个答案
  C. 5 条应未找到（expect: miss）——超出覆盖集，
     期望返回"未找到"而不是返回最像的那条

# 输出（严格 JSONL）
{"query":"...","expect":"hit|refuse|miss","expect_id":"...","min_score":0.0,"why":"..."}

# 说明
这批用例会被写进 .emf 的 testset 区，在烧录后于板端实跑。
它们是 S1「top-1 ≥ 85%、误报 ≤ 5%」判据的直接采集来源。
请认真设计 C 类（应未找到）——它能测出这块板子会不会"不懂装懂"，
而这正是记忆类产品最掉价的地方。

5.6 P5 · 拒答话术模板（写进固件，断网时用）

# 说明
以下话术由固件在检索失败 / 命中红线 / 命中过期条目时直接返回，
断网状态下使用，不得调用任何模型。请按 spec 的语言风格本地化后写入。

1) 未找到
"这块板子上没有关于「{query}」的记录。
 已记录的相近主题：{top3_tags}。要不要换个说法再问？"

2) 命中红线
"「{topic}」涉及{安全边界 / 型号范围 / 未确认信息}，
 请以现场规程或厂家确认为准，本设备不提供判断。"

3) 命中过期条目
"找到一条记录，但已 {ttl_days} 天未更新（{date}），仅供参考。
 未过期的最新记录：{newer_tags}。"

4) 低置信（分数低于阈值但仍返回）
"最相近的是下面这条，但匹配度不高（{score}）。
 如果不是你要的，建议用更具体的型号或现象重新提问。"

# 设计原则（写死在固件里，不可由模型覆盖）
- 绝不把"未找到"包装成"找到了"。宁可显示"没有"也不要硬凑。
- 拒答时必须给出"已记录的相近主题"，把死路变成岔路。
- 涉及安全的回答必须显式提示以现场规程为准。

6. .emf 碎片包格式规范

三原则（沿用战略报告）：自洽（脱离上下文可读）、离线可验签（板端不联网也能验完整性）、schema 与 eXtremeDB 同源（将来 emdb 后端可直接导入）。

6.1 文件头（32 字节，与现有 kb_ota 约定一致）

偏移  长度  类型    字段            说明
0     8     char    magic           "EMKBIMG1"
8     2     u16     version         1
10    2     u16     flags           bit0=含向量 bit1=含 testset bit2=已签名
12    2     u16     dim             向量维度；0 = 无向量（v1 纯文本）
14    1     u8      dtype           0=none 1=int8 2=float16
15    1     u8      schema_ver      schema 版本号
16    4     u32     count           条目数
20    4     u32     schema_hash     schema 定义的 FNV-1a 32
24    4     u32     payload_len     payload 字节数
28    4     u32     payload_crc32   payload 的 CRC32
--- 32 字节头结束，此后为 payload ---
32    -     -       payload         count 条记录顺序拼接
末尾  32    u8[32]  digest          payload 的 SHA-256（flags.bit2=1 时追加 HMAC）

6.2 单条记录布局

字段            类型                 说明
id              u32                  全局唯一（同碎片内单调）
text_len        u16                  text 字节数
text            utf8                 正文，≤ {NCHARS} 字
sum_len         u8                   summary 字节数
summary         utf8                 ≤ 40 字，列表展示用
tag_cnt         u8                   3-6
tags            (u8 len + utf8)*     标签（含别名）
salience        u8                   0-100
src_len         u8                   source 字节数
source          utf8                 来源文件名或 "synthetic"
valid_from      u32                  unix 秒；0 = 未知
ttl_days        u16                  0 = 永不过期
redline         u8                   0/1
vector          i8[dim] 或 f16[dim]  仅 flags.bit0=1 时存在（dtype 决定）

记录不加对齐填充——flash 空间比 CPU 对齐宝贵。板端按字段顺序流式解析即可。向量一律放在记录末尾，这样 v1 固件（不识向量）可以安全跳过前段、只读文本部分，实现前后向兼容。

6.3 可选区（flags.bit1 = 含 testset）

payload 之后追加 P4 生成的验收用例集，格式：

u32  n_cases
重复 n_cases 次：
  u16  query_len + utf8 query
  u8   expect           0=hit 1=refuse 2=miss
  u32  expect_id        expect=0 时有效
  f32  min_score
  u16  why_len + utf8 why

把 testset 打进包里，好处是：板子在断网现场也能自检——运维人员按一下就能跑一遍 20 条用例，看这块板子的记忆是否还健康。这是 mem.check 命令的数据来源，也是「记忆健康检查」这个卖点的实现基础。

6.4 校验与拒绝策略

7. 一键烧录：三条通路与分块传输

7.1 通路选择策略（自动 + 可手动覆盖）

if (caps.features 含 "kb_import" && 通道 == HTTP)
      → ① HTTP 分块上传          （最快，首选）
else if (通道 == WebUSB && 板端支持 bulk)
      → ② USB bulk 分块          （次快）
else if (通道 == Web Serial)
      → ③ 串口分块命令            （最慢但必达）
else  → ④ 导出 .emf 下载，引导拖进虚拟 U 盘（OS 层）

任意通路失败 → 自动降级到下一级，并在 UI 明示原因与当前通路。

7.2 分块传输协议（三通路共用）

7.3 通路 ④：MSC 虚拟 U 盘（OS 层，非浏览器）

7.4 各通路耗时预算与验收判据（拆分 v1.2 的 G5）

基准：12,000 条 × 662 B ≈ 7.9 MB payload（v1 纯文本略小，约 5–6 MB）。

7.5 烧录编排状态机

IDLE
 └─> PRECHECK  (GET /api/kb/session?dry=1，传包头 32B + count)
       ├─ 容量不足 ──> FAILED(容量)  → 建议裁剪或换板
       └─ 通过
            └─> TRANSFER (逐块，seq 递增，每块 ack)
                  ├─ 块 CRC 错 ──> 重传该块（≤3 次）
                  ├─ 连续超时 ──> SUSPENDED（保留 session_id）
                  │                  └─> 重连后 RESUME（从 ack+1）
                  └─ 收完
                       └─> VERIFY (payload_crc32 + digest)
                             ├─ 失败 ──> FAILED(校验)，原库完好
                             └─ 通过
                                  └─> COMMIT (原子切换)
                                        └─> REBOOT? ──> DONE
                                              └─> 自动跑 testset（若含）

每个状态都要在 UI 上有明确呈现（图标 + 文案 + 进度 + 预计剩余 + 当前 seq/total）。烧录是用户唯一会盯着看几十秒的操作，进度反馈的质量直接决定他觉得这个产品专业还是山寨。

8. 固件与知识库更新：通路矩阵

8.1 固件更新三通路

8.2 知识库更新三通路

8.3 备份（灌库前必做）

9. 板端需新增的 API 清单

9.1 HTTP 端点

所有响应统一 JSON：{"ok":true,"data":{...}} / {"ok":false,"err":"CODE","msg":"..."}，与现有串口协议保持一致，前端可共用一套错误处理。

9.2 串口命令（CLI JSON，单行）

9.3 三条固件实现铁律（沿用现有坑集合）

• Nagle + 延迟 ACK：响应必须合并成一次 send，httpd open_fn 设 TCP_NODELAY。否则分块灌库从 10 块/s 掉到 0.33 块/s——这一条能让串口通路从 4 分钟变成 40 分钟。
• 多任务共串口必须单锁整行原子写（cmd_console_write() + esp_log_set_vprintf()）。各源各把锁无效。
• 栈溢出排查优先于功能调试：NimBLE host 栈需 ≥8192；hub_task 栈 6144 内不得放大缓冲；灌库缓冲一律 malloc 到堆，不放栈。周期性自发重启先抓 Rebooting 前 30 行。

10. 前端工程结构与模块划分

EdgeMemory-Gateway/web/            【真源，OneDrive 上这份为准】
├── index.html                     现有（扩展：新增「知识库向导」「验收」入口）
├── css/style.css
├── js/
│   ├── protocol.js                现有·复用（单行 JSON 传输层）
│   ├── ble_client.js              现有·复用
│   ├── flasher.js                 现有·复用（esptool-js 串口刷写）
│   ├── ota.js                     现有·复用（无线 OTA）
│   └── app.js                     现有·重构为按需加载 studio 模块
├── vendor/esptool-js.js           现有
└── studio/                        【新增，本设计书的主体】
    ├── studio.html                向导主入口（可独立打开）
    ├── css/studio.css
    ├── js/
    │   ├── conn/
    │   │   ├── transport.js       四通道统一抽象（接口见 3.2）
    │   │   ├── serial.js          Web Serial
    │   │   ├── webusb.js          WebUSB
    │   │   ├── http.js            fetch + CORS
    │   │   └── ble.js             Web BLE
    │   ├── wizard/
    │   │   ├── steps.js           五步状态机
    │   │   ├── tpl_scene.js       S1/S2/S3/自定义模板
    │   │   ├── prompts.js         ★ P0–P5 预设 Prompt 全集（第 5 章）
    │   │   ├── llm.js             LLM 适配器（云端 / Ollama / 离线）
    │   │   ├── embed.js           Embedding 适配器 + 维度选择/PCA
    │   │   └── schema.js          规格卡与条目 schema 定义 + 校验
    │   ├── pack/
    │   │   ├── emf.js             .emf 打包 / 解包 / 校验（纯 JS，无依赖）
    │   │   ├── chunker.js         4 KB 分块 + CRC32 + 断点续传
    │   │   └── dryrun.js          浏览器内暴力 Top-K 预检
    │   ├── burn/
    │   │   ├── burner.js          一键烧录编排（自动选路 + 降级）
    │   │   └── progress.js        进度 / 速率 / 预计剩余
    │   └── ui/
    │       ├── components.js      条目表、水位条、用例面板
    │       └── toast.js
    └── tools/
        ├── emf_pack.py            PC 端等价打包（CI / 批处理）
        └── emf_dump.py            解包与检视

10.1 与现有控制台的关系

不推翻现有 index.html 五个页签（主板信息 / 模块数据 / 设备·知识库 / 固件刷写 / 无线 OTA），而是在其上新增两个入口：

• 「知识库向导」——跳转 studio/studio.html，携带已连接的传输上下文（避免重复连接）。
• 「验收」——读包内 testset 或板端 kb.verify 结果，渲染命中率面板。

现有 ota.js 与 flasher.js 直接复用为第 8 章的固件更新通路，不重写。

11. 开发任务 WBS（WP7 · EdgeMemory Studio）

WP7 共 31 项 / 138 人日，按 ×1.3 缓冲 ≈ 179 人日。与 WP0–WP6（v1.2 的 206 人日）有部分并行关系：WP7-C/D（向导与打包，35 人日）不依赖 emlite，可立刻启动；WP7-A 的灌库 API 依赖 WP1 的存储层。建议排期：WP7-C/D 与 WP1 并行先做，WP7-A 排在 WP1-02 之后。

12. 测试用例集

共 28 条用例：TC-W-C-* 连接层 8 条、TC-W-G-* 生成向导 8 条、TC-W-B-* 打包烧录 8 条、TC-W-U-* 更新与安全 4 条。列：前置 → 步骤 → 预期。

12.1 连接层

12.2 生成向导

12.3 打包与烧录

12.4 更新与安全

13. 风险登记与合规

13.1 合规要点

• 不做代币、不做积分交易。沿用战略报告结论（银发〔2026〕42 号境内严禁代币化）。Web 端若将来加「贡献度」之类功能，只能是封闭记账配额，UI 不得出现钱包、币价、提现字样。
• API Key 与用户内容不经我方服务器——这是无后端架构最大的合规收益，应在对外材料里明说。
• 素材上传需明示用途：页面在上传前说明「这些内容将被用于生成知识库，并按你选择的模型档位处理」。
• 导出与备份：用户必须能随时导出自己的 .emf（/api/kb/export），避免「记忆被锁死在设备里」的指控。

14. 下一步