Fabric AI Framework — Deep Dive Q&A

架构总览 · 4 层模型 + 3 大支柱

4 层抽象

📌 心智模型：Skills 教 Copilot 该怎么做；MCP servers 让 Copilot 真的去做并看到结果。两者协同实现 "生成 notebook → 跑 → 检查结果 → 修错 → 进入下一任务" 单会话连贯。

3 大实施支柱

ASCII 架构图

End-to-End 主流程

关键心智：没有独立的 Create Session API；session 在用户发出第一条消息时被 lazy 创建。Browser 从不直接调容器，所有消息走 Browser → MWC → Container。Browser 用 userEntraToken 调 Shared（CE artifact CRUD / Models），用 mwcToken 调 MWC（messaging / tools / attachments）；详见 Q18 / Q20 / Q21。

1. 用户第一条消息（lazy session 创建） — Browser 已选定一个 Copilot Environment artifact（CE）作为 session 容器。Browser 发 POST {mwcBase}/public/workspaces/{wsId}/CopilotEnvironments/{ceId}/sessions/messages（targetSession:"new" + 客户端生成的 draftSessionId）→ MWC ① 先 write-ahead metadata.json 到 OneLake → ② ADC PUT /sandboxes 拿到 sandboxId + containerUrl → ③ ADC PUT /secrets 存 OBO token（SecretRef）→ ④ Container POST /configure 下发 refreshTokensAfterUtc + tokenExpirations。SSE 流先推 session.provisioning，sandbox 就绪后推 session.created { sessionId, draftSessionId }。
2. 容器启动 + skills 加载 — Container 内的 SkillsLoader 调 Fabric Shared API GET /skills/manifest，按返回的 CDN URL 拉 SKILL.md 包并拼到 system prompt；MCP server 端点在配置就绪后由 McpServerRegistry 注册并 health check（详见 Q19）。
3. 消息转发（SSE 长连） — MWC 内部把这条消息发给容器：POST {containerUrl}/responses（用 copilotWorkload1pToken，audience: fabric/<container-id>）→ 容器流式回 SSE 给 MWC，MWC 透传给 Browser。
4. Tool 调用 / 外部出站 — SDK 决定调 MCP / bash；所有出站走 Envoy egress sidecar，按 egressRules + secretRef 在 TLS MITM 后注入 Authorization: Bearer，容器进程永远看不到明文 token（详见 Q11/Q18）。
5. 审批 / 用户输入 — 高风险动作发 permission.request SSE，前端弹审批卡；用户回 POST /permissions/{id}/respond，流恢复。
6. 每轮持久化（热路径） — 每条消息：① 容器把 events 追加到 InMemorySessionFs（纯内存 ConcurrentDictionary，不落盘）；② MWC 只更新 OneLake state.json 两个字段（messagesCount + lastInteractionAt）；events.jsonl 此时不落 OneLake。
7. 状态机驱动的 Export（冷路径） — MWC sweeper 检测 Idle ≥ 30min / WaitingFor* ≥ 2h → ① POST {containerUrl}/export 让容器把 InMemorySessionFs 整段 base64 dump 返回 → ② MWC 用 Fabric workload identity PUT 到 OneLake sessions/<id>/ → ③ ADC POST /sandboxes/{id}/stop（Memory-mode snapshot）。
8. 恢复 — 用户回来发新消息 → MWC POST /sandboxes/{id}/resume（hot path ~1s）；若 snapshot 不可用 → Cold restore：PUT /sandboxes 新建 + Container POST /import 从 OneLake 回放 events.jsonl（详见 Q15/Q16）。

为什么要使用沙箱（Agent 宿主）

根本原因：Agent 的 reasoning loop 是不可信代码的执行者。LLM 会生成并执行任意 bash / Python / az CLI，把它放进 Fabric 主进程等于把 root shell 暴露给模型。

沙箱解决的 4 件事

Agent 框架的细节

技术栈

• 运行时：ASP.NET Core (.NET 8)
• 核心引擎：GitHub Copilot SDK（与 CLI 共享 reasoning loop）
• Skills：Markdown 文件，运行时从 CDN 拉取并热加载
• MCP：Workload 自托管 HTTPS endpoint，由容器在 /configure 时注册

3 种工作模式

关键类

• Program — Kestrel 启动，注册 DI
• CopilotAgentService — 顶层服务，把 HTTP 请求翻译为 SDK 调用
• CopilotClient — 包装 GH Copilot SDK
• CopilotSession — 内存中会话状态机
• InMemorySessionFs — 容器内虚拟文件系统（agent-state / session-state 双层）
• SkillsLoader — 从 CDN 拉 SKILL.md，本地缓存
• McpServerRegistry — 注册 / 健康检查 MCP server

HTTP 端点（容器对外）

⚠️ 静态身份参数（userId / tenantId / containerId）在 PUT /sandboxes 时通过 environment 字段注入，不走 /configure（因为 env 不可变后置 PATCH）。/configure 只承载随时间变化的动态值。

容器内文件系统布局

/app/                        # 镜像内置（agent binaries）
/agent-state/                # 长期 agent 配置（mounted）
  ├── skills-cache/
  └── mcp-registry.json
/session-state/              # 当前 session 专属（mount or in-memory）
  ├── messages.jsonl
  ├── state.json
  └── artifacts/

Shared Service 不在消息路径上 是什么意思

"消息路径" = 用户 → AI → SSE → 用户 这条 高频低延迟 数据通路。

Shared 做什么 / 不做什么

真正消息路径

Copilot workload 与其他 workload（如 Notebook）的区别 / 与 Shared 的关系

三方对照

关系图

关键：Copilot workload 把 Notebook workload 当作"MCP Server 提供者"消费；两者通过 Shared 协调 artifact 关系。

SandboxGroup 是什么意思

• ARM 资源类型：Microsoft.App/sandboxGroups
• 语义：ADC 的 "区域级组织单元"，对应一个 VNet 子网、一组 quota 和一套默认 egress policy
• 用途：每个 region × tenant 的 Copilot capacity 注册一个 SandboxGroup；所有 microVM 都注入到该 group 的 VNet
• 类比：相当于 ACI 的 "container group"，但语义在网络隔离 + 配额层面

ADC 全称 / 平台定位

名词

缩写

ADC

团队内部叫法

Agent Dev Compute（Fabric AI Framework 决策文档里的写法，002-adc-vs-foundry-vs-aci.md）

Azure 平台官方叫法

Azure Dev Compute（注意是 Dev，不是 Developer） — 体现在 API host https://management.azuredevcompute.io、Entra app Azure Dev Compute Proxy、GitHub org github.com/Azure-Dev-Compute

对外产品名（已发布）

Azure Container Apps Sandboxes（ARM 资源 Microsoft.App/SandboxGroups），Early Access（联系 MS 销售开通；与 Container Apps Dynamic Sessions 是兄弟资源）

RBAC 角色名

旧（Fabric AI repo 里）：Dev Compute SandboxGroup Data Owner → 新（公开 docs）：Container Apps SandboxGroup Data Owner

本质

基于 Firecracker microVM 的多租户、安全沙箱平台 + Envoy egress proxy + KeyVault 集成；目标场景：安全执行 LLM 生成 / 不可信代码、可挂起的 dev 环境、可拓展的 agent runtime、CI/CD 一次性构建环境

面向

所有需要"安全执行不可信 / LLM 生成代码"的内部产品（Copilot 系列、Agent 平台等共用），外部企业客户通过 Container Apps Sandboxes 接入

"Dev" 不是 "Developer" — 命名族对照

ADC 属于前者—— 它是 infrastructure-level microVM 平台，跟 Dev Box / DevOps 是同族；不是 Developer CLI 那类前端工具。

ADC 提供什么（4 类 ARM 资源）

ADC 与 Fabric AI Framework 的关系

为什么是 ADC，不是别的

workspace 里的 session 存储是用户独享还是 workspace 共享？是不是 singleton？

一句话结论

历史背景：旧 .copilot singleton 设计已被取代

specs/building-blocks/copilot-item.md 旧设计是 "每 workspace 一个 .copilot item，自动创建，409 防重复"。这个设计在 engineering/ 目录被取代：

• 用户在 my-workspace 不一定有 capacity，不一定能放 artifact —— singleton 模型挡住了私有 session 路径（006-artifact-model.md）
• 团队 / 项目隔离需要 —— 想分多套 session 做不同事，singleton 撑不开
• CMK / 网络策略按 workspace 走，一个 workspace 多个 CE 让用户能挑合适的"宿主"

CE artifact 的本质

OneLake 目录示意

workspace-XYZ/
├── CopilotEnv-Team-Alpha/            # CE artifact #1（共享 in 该 workspace）
│   ├── indexes/
│   │   ├── owned/<tenantOid>/<aliceOid>/<sessionId>.json   # 空文件 = 指针
│   │   └── owned/<tenantOid>/<bobOid>/<sessionId>.json
│   └── sessions/
│       ├── <Alice 的 session>/        # Alice 私有
│       └── <Bob 的 session>/          # Bob 私有
└── CopilotEnv-Personal-Sandbox/      # CE artifact #2（同 workspace 多个 CE）
    └── sessions/...

📌 心智：CE artifact 是 "装 session 的盒子"，workspace 里盒子可多个；每个盒子有自己的 OneLake 文件夹、CMK 配置、共享策略。新建 session 之前必须先选定 / 创建一个盒子，详见 Q20。

sessionId / sandboxId / containerUrl 三者关系

关系

1:N 时间维度：一个 fabricSessionId 在生命期内可能对应多个 sandboxId（每次 restore 是新 microVM）。同一时刻 1:1:1。

sandbox 和用户的关系

当前实现

per-user-per-session 一个用户的一个 session 拥有一个独立 sandbox。

设计权衡（Open Question）

会话存储用的 OneLake 是 workspace 级还是 capacity 级？

层级关系

结论：OneLake 物理是 tenant-level 服务，但用户感知边界是 workspace；session 数据进一步嵌在 CopilotEnvironment artifact 文件夹里，按 CE 隔离 + 按 user 在 CE 内隔离；配额加密按 capacity 计。详见 Q20 关于 CE artifact 的完整说明。

SecretRef 的精髓 — 用一个完整例子说明

场景

Alice 在 Fabric Copilot 中要求 "把这个 dataset 同步到我的 GitHub repo"。Copilot 需要用 Alice 的 GitHub PAT 调 GitHub API，但这个 PAT 绝不能进容器。

四步

Step 1 — MWC 把 token 存进 KeyVault

PUT https://adc.azure.com/secrets/alice-gh-pat
Authorization: Bearer <mwc-managed-identity>
Content-Type: application/json

{
  "value": "ghp_xxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "session:abc-123"
}

返回：{ "secretId": "alice-gh-pat", "kvRef": "https://kv-adc-eus.vault.azure.net/secrets/alice-gh-pat/v1" }

Step 2 — ADC egress 规则仅引用 secretRef，不存明文

{
  "egressRules": [
    {
      "host": "api.github.com",
      "method": "*",
      "inject": {
        "header": "Authorization",
        "valueTemplate": "Bearer {value}",
        "secretRef": "alice-gh-pat"     ← 只存 ID
      }
    }
  ]
}

Step 3 — Envoy 在 TLS MITM 后按规则注入 header

# 容器内进程发出（裸 HTTP，无 Authorization 头）
curl https://api.github.com/repos/alice/foo/contents/x.csv

# Envoy 在出站时：
#   1. TLS terminate（用自签 CA）
#   2. match egressRule host=api.github.com
#   3. 从 KeyVault 取 secretRef=alice-gh-pat
#   4. 注入 Authorization: Bearer ghp_xxxx
#   5. 重新 TLS encrypt 发往 GitHub

Step 4 — 容器永远看不到 token

精髓总结

1. MWC PUT /secrets/{secretId} 把 token 存进 KeyVault
2. ADC egress 规则只引用 secretRef，不存明文
3. Envoy proxy 在 TLS MITM 后，按规则网络层注入 Authorization: Bearer {value}
4. Container 内发的是裸 HTTP，永远看不到 token

UX 怎么实现 / 主要用什么 package / 为什么这么选

仓库现状

仓库里 只有 React 原型（Prototypes/UnifiedAIPlatform/react-prototype/），生产 UX 尚未落地。

原型技术栈

真正落地架构（规划）

• Fabric Portal：Angular Shell + 嵌入 React Chat Pane（通过 createRoot 桥接）
• 核心服务：
  • CopilotHostService（Angular）— context 合并、tool 调度、SSE 处理、token 缓存 / 401 重试
  • CopilotHttpService（Angular）— Shared API（CE / Models）+ MWC API（Sessions / Messaging）的 HTTP/SSE 客户端
  • CopilotPaneApi（facade）— React 端只持有这个 facade，对后端调用完全透明（详见 Q21）
• React Chat Pane 组件库：基于 @fabric-msft/copilot-react（Client Engineering Systems 提供的成熟、可复用 Copilot 组件包，对齐 Microsoft Copilot Design 规范）

详见 engineering/300-frontend/300-!!-frontend-dev-design.md。

UX 是否直接复用 GitHub Copilot / VS Code Copilot 的 UX？

一句话结论

1. 三个 surface 的复用矩阵

2. CLI Surface — 如何"复用"

本质：把 GH Copilot CLI 当成现成 agent runner，Fabric 只贡献 skills 包 + 远端 MCP endpoint，零行 UI 代码。

# 用户唯一要做的三步
gh copilot skills install gim-home/skills-for-fabric@latest   # 装 Fabric skill 包
gh copilot skills list                                         # 验证装好了
gh copilot                                                     # 进 CLI 对话

• 没有 Fabric 自己的 CLI 二进制 — 用户用的就是 GitHub Copilot CLI
• Fabric team 维护一个 GitHub repo gim-home/skills-for-fabric，按 GH Copilot 的 skill 规范打包
• Skills 通过 GitHub releases 分发（"distributed as code, not as cloud services"）
• MCP server 部分：CLI 调远端的 Fabric MCP（HTTPS endpoint）

3. VS Code Surface — 如何"复用"

同样是 把 GitHub Copilot 扩展当宿主，Fabric 注入 skills，不写 VS Code extension。

1. 用户装 GitHub Copilot 扩展（如未装）
2. 命令面板 Ctrl+Shift+P → Copilot: Install Custom Skills
3. 输入 repo gim-home/skills-for-fabric
4. Skills 出现在 Copilot skill picker 中

但 Fabric MVP 仅承诺 P0 的 Local-Surface 能力（见 local-agent-dev.md Out of scope）：

• ❌ 不写原生 VS Code extension
• ❌ 本地不存 session（ephemeral）
• ❌ MCP tools 本地不可用（只能直接 REST）
• ❌ 没有 RBAC 强制（假设用户自己有权限）

4. Fabric Portal — 为什么不复用

1. 技术栈不兼容 — Portal 是 Angular Shell；VS Code Chat 是 Electron + webview + 大量 VSCode-API。两者根本嵌不进去
2. 视觉一致性 — Portal 全员 Fluent UI v9，VS Code 用自有 token 体系，强行嵌会两张皮
3. 必须渲染 Fabric artifact — Notebook 卡 / Lakehouse table / Dataset preview / Pipeline 图必须用 Portal 已有的 renderer，VS Code Chat 渲染不了
4. 必须与已有 3 个 Copilot 共存（tri-copilot / immersive-copilot / workspace-copilot），新框架"同时存在并逐步升级"，不能直接搬另一个产品的容器（见 300-frontend-dev-design.md §3.2 Non-Goals）
5. D-7：用户心智不同 — Cristian: "I don't think you will start in VS Code and continue in Fabric…" Portal 围绕"我的 Fabric 资产"，VS Code 围绕"我的代码"，不连贯

5. Portal 自己选了什么方案？

方案：Angular Shell 嵌一个 React Chat Pane，靠 Bridge 通信。

┌──────────── Fabric Shell (Angular) ────────────────┐
│                                                    │
│  Shared Experience / Classic / Extension Artifact  │  ← 各 Page 提供 context + tool
│            │                                       │
│            ▼                                       │
│  ┌─── CopilotHostService (Angular) ────────────┐   │  ← 全部脏活在这层
│  │  · context merge   · client-tool dispatch   │   │
│  │  · SSE processing  · token 缓存 / 401 重试  │   │
│  │  · HTTP: Shared API (CSM/Models)            │   │
│  │  · HTTP/SSE: MWC API (Messaging/Tools)      │   │
│  └─────────────────────┬───────────────────────┘   │
│                        │ CopilotPaneApi facade     │
│  ┌── CopilotHostComponent (Angular) ─────────┐     │
│  │      ▼ createRoot()                       │     │
│  │  ┌────── Chat Pane (React + Fluent v9) ──┐│     │  ← 纯 UI
│  │  │ Header  · New Session / Sessions      ││     │
│  │  │ Messages· User/Assistant/Tool/Approval││     │
│  │  │ Input   · Pills/Attach/Model/Mode/Send││     │
│  │  └───────────────────────────────────────┘│     │
│  └────────────────────────────────────────────┘    │
└────────────────────────────────────────────────────┘

6. 关键设计权衡

7. 真正"跨 surface 复用"的东西

Notebook workload 想 customize 它特有的功能，工作大致是？

平台提供 5 种自助贡献资产，Notebook team 不需要平台代码改动即可上线。

5 种贡献类型

典型工作流（举例：让 Copilot 能 "解读 notebook 错误"）

1. SKILL.md 写一段："当用户问 notebook 出错时，先调 mcp.notebook.get_last_error，再调 mcp.notebook.explain_traceback…"
2. MCP Server 在 Notebook workload 内新增两个 endpoint：get_last_error / explain_traceback
3. （可选）Frontend Tool 渲染 "Stack Trace 卡片"，高亮某行代码
4. Evaluation Set 加 ≥50 个真实出错 notebook 样例，断言 Copilot 输出正确分析
5. 提 PR → CI 自动跑 eval → 自动部署到 CDN 和 MCP registry

SLA

• < 2 个工作日 从 PR 合并到生产可用
• 仅需平台 team 介入的 3 类例外：
  1. 新增 native tool（SDK 内置工具）
  2. 修改容器镜像 / Agent 基础进程
  3. 新增 "全局 building block"（横切多个 workload）

会话内容是如何写到 OneLake 里的？

这个问题分两层：写什么 / 谁写 / 何时写。设计的核心矛盾是 — 持久性要够（崩了不能丢对话），但热路径（每条消息）的写开销必须最小。

① 大原则：分两类，分别写

② 数据路径：Container 不直接写，MWC 统一持久化

三步明确：

1. MWC 发起 POST {containerUrl}/export 拉数据
2. Container 把 InMemorySessionFs 字典里所有文件 base64 编码后塞进 JSON 响应给 MWC
3. MWC 用自己的 Fabric workload identity 把数据 PUT 到 onelake.dfs.fabric.microsoft.com

MWC 什么时候发 POST /export？

不是周期 export，而是状态机驱动 + 显式请求（依据 014-D §8 Suspension Flow）：

③ OneLake 目录布局

<workspace>/<copilot-environment-artifact>/
├── indexes/
│   ├── owned/<tenantOid>/<userOid>/<sessionId>.json   # 空文件，文件名即指针
│   └── shared/<tenantOid>/<userOid>/<sessionId>.json  # {sharedBy, sharedAt, permissions}
└── sessions/
    └── <fabricSessionId>/
        ├── metadata.json        # 写一次永不动     {agent, createdAt}
        ├── settings.json        # 偶尔写 (ETag)   {model, displayName, modelConnectionId}
        ├── state.json           # 每消息写         {sandboxId, lastInteractionAt, messagesCount}
        ├── session-state/
        │   └── events.jsonl     # export 时写入 (完整对话)
        └── files/               # agent 创建的产物文件 (export 时打包)

④ 写入时机（每个事件对应哪些文件）

⑤ 三个核心机制

1) 三文件拆分（最小化热路径字节）

• metadata.json 不可变 → write-once，永不重写
• settings.json 偶变 → ETag 乐观锁，rename/换模型时改
• state.json 高频 → 每消息只动 3 个字段；天然单写者（一个 sandbox 只对应一个 MWC 实例）

2) Write-Ahead 写日志模式

metadata.json 写入 OneLake 早于 sandbox 创建，原因：

• API 超时但实际成功 → 调谐 sweeper 能通过 metadata 找到孤儿 sandbox（label 匹配）
• UX 立即出现"Provisioning..."状态指示
• 幂等重放：用同一 draftSessionId 重试 → 检测到 Provisioning 状态 → 续作而非新建

3) 索引是可重建投影（Eventually Consistent）

indexes/owned/{tenant}/{user}/{sessionId}.json 是空文件——文件名本身就是指针。

• 列表"我的会话" = ListPaths prefix 扫描，O(user 会话数)，不全扫
• 真相源始终是 sessions/ 文件夹；索引坏了可以从源重建
• 后台调谐 job 定期对账（创建索引漏写 → 补写；session 已删 → 清孤儿索引）

⑥ 并发控制矩阵

⑦ 鉴权 / 传输

协议

ADLS Gen2 兼容 REST

Endpoint

onelake.dfs.fabric.microsoft.com

MWC → OneLake

Fabric workload identity（一等公民身份）

Container 内访问

如启用 Fabric Fuse，通过 ADC egress proxy 注入 Authorization: Bearer {onelakeToken}；token 用 SecretRef 引用 KeyVault，容器内永远看不到明文（详见 Q13）

⑧ 为什么 events.jsonl 不每条消息都写 OneLake？

Container 的生命周期是怎样的？

Container 生命周期由 MWC 主导 + ADC 平台兜底 双层管理。核心心智：Session 不死，Container 用完即弃 —— 容器是计算实例，可被替换；session 通过 OneLake export 永生。

① 状态机总览（7 个核心状态）

② 七阶段详解

1️⃣ Provisioning — Lazy 创建，首条消息触发

没有独立的 Create Session API，第一条 POST /messages 触发：

MWC                            ADC                          Container
 ├─ ① Write-ahead metadata.json (sandboxState=Provisioning) → OneLake
 │
 ├─ ② PUT /sandboxes ──────────▶│
 │   {diskImage, env, egressRules,
 │    lifecycle: {autoSuspend.enabled=false,
 │                autoDelete.enabled=true, interval=172800},
 │    labels: {session-id, artifact-id, managed-by, created-at}}
 │                              ├─ 建 microVM + 启动容器进程
 │◀── sandboxId, containerUrl ──┤
 │
 ├─ ③ 写 state.json (含 sandboxId)
 │
 ├─ ④ PUT /secrets ─────────────▶│  KeyVault 存 OBO token (SecretRef)
 │
 ├─ ⑤ POST /configure ──────────────────────────────────────────▶│
 │                                                                ├─ 容器加载 token/model/skills
 │◀───────────────── 200 OK ──────────────────────────────────────┤
 │
 ├─ ⑥ 更新 state.json (sandboxState=Active)
 │
 └─ ⑦ POST /responses ──────────────────────────────────────────▶│
                                                                  └─ SDK SendAsync 处理首条消息

2️⃣ Active — 处理消息

容器内 InteractionStateTracker 跟踪 SDK 事件，状态用 fire-and-forget callback 异步报给 MWC（不阻塞 SDK）：

容器并发控制：SDK SendAsync 不线程安全 → 容器用 SemaphoreSlim 串行化，第二条同时来 → 返回 429 Too Many Requests，UX 显示 "agent is busy"。

3️⃣ Suspending → Suspended — 应用层暂停

MWC sweeper 周期扫描，Running 永远不暂停：

MWC sweeper              Container        ADC              OneLake
 ├─ TryTransition Active → Suspending
 ├─ POST /export ──────────▶│
 │◀── base64 dump (events.jsonl + files/)
 ├─ Write export ─────────────────────────────────────────▶│
 │                                                          │ Durable checkpoint
 ├─ POST /sandboxes/{id}/stop ────────────▶│
 │◀── snapshotId, snapshotBlobUri ─────────│ Memory-mode snapshot (process state preserved)
 ├─ Update state.json (Suspended) ──────────────────────────▶│
 └─ TryTransition Suspending → Suspended

4️⃣ Resuming → Active — 用户回来发消息

User             MWC               ADC                Container
 ├─ POST /messages ▶│
                    ├─ Suspended → Resuming
                    │◀── SSE: session.resuming (transparent to user)
                    ├─ POST /sandboxes/{id}/resume ─▶│
                    │◀── Running, containerUrl ──────│  Memory 恢复 ~1s，进程状态完整
                    ├─ GET /health ─────────────────────────▶│
                    │◀──────────────────── 200 ─────────────│  readiness check
                    ├─ POST /configure (fresh tokens) ──────▶│  token 可能已过期
                    │◀──────────────────── 200 ─────────────│
                    ├─ Resuming → Active
                    └─ POST /responses ─────────────────────▶│  继续，无需 replay events.jsonl

Memory mode 的妙处：SDK 会话状态保留在进程内存中 —— 不需要 export/import 每个 suspend/resume 周期，热路径快。

5️⃣ Cold Restore — Resume 失败兜底

memory snapshot 不可用时（snapshot 过期、host 维护、容量问题）：

MWC ──PUT /sandboxes──── ADC: 新建 sandbox（disk image 启动，全新进程）
    ──POST /configure─── Container: 加载 token / model / skills
    ──POST /import────── Container: 从 OneLake export 预填 InMemorySessionFs
                         SDK.ResumeSessionAsync(sessionId)  ← 重放 events.jsonl
                         → 对话状态完整重建（慢，几秒到几十秒）

6️⃣ Terminated — 终结（6 个触发源）

MWC DELETE /sandboxes/{id} 后，secret 和 snapshot 一并清除。Session 元数据保留在 OneLake（历史列表用），但所有 compute 资源释放。

7️⃣ Unknown — 失联异常

MWC 在 unknownThreshold（默认 30 min）内没收到容器心跳：

1. 标记 Unknown
2. 尝试 GET {containerUrl}/state 直接探活 → 通 → 恢复 Active
3. 不通 → GET /sandboxes/{id} 问 ADC：
   • Running → 容器内进程崩了 → export + terminate + 起新 sandbox
   • Stopped → 进 Suspended
   • 404 → Terminated

③ Defense-in-Depth（6 层兜底）

④ Session vs Container 寿命对比（最重要的心智）

⑤ Image 升级也是同一机制

新容器镜像版本发布时：

• 正在 Active 的容器：继续跑老镜像（不打断用户）
• 下次 Suspend / Terminate / Cold restore：建新 sandbox 自动用新镜像
• SDK 内部状态通过 events.jsonl 重放：跨版本兼容，无需用户感知

本质：cold restore 既是 BCDR 兜底，也是 rolling upgrade 通道。

Session 和 Prompt 是什么关系？Session 的 CRUD 怎样？用户什么时候能新建 Session？

一句话结论

1. 包含关系图

2. 四层概念对照表

3. Session CRUD 全景 — 注意：没有 Create API

📌 Auto-naming：新 session 的 displayName 默认为空，第一条回复后 MWC 用一次轻量 LLM call「Summarize this conversation in 5 words or fewer」生成名字，并通过 SSE session.renamed 推送给前端更新左侧栏。用户随时可手动 PATCH 覆盖。

4. 用户什么时候能"新建"一个 Session？

"新建"动作分三个阶段，前两阶段都不向后端建 session：

阶段 C 的服务端展开（来自 014-A-sessions-crud）：

1. MWC 收到 POST /messages，按 draftSessionId 加 server-side creation lock。
2. OneLake：在 {workspace}/{CE-artifact}/sessions/{newGuid}/ 写 metadata.json（write-once）。
3. ADC：创建 microVM + egress rules + secret。
4. Container：MWC 调 /configure 把 sessionContext / 工具清单 / model triple 注入 GitHub Copilot SDK。
5. SSE 先后发 session.provisioning { draftSessionId, status } → session.created { sessionId, draftSessionId }。
6. 之后立即接 assistant.turn_start 开始第一条 prompt 的处理。
7. 前端收到 session.created 后，把 React state 里的 draft 替换为真 sessionId，并把后续请求 URL 改成 …/sessions/{sessionId}/messages。

同一 draftSessionId 的重试是幂等的：

• SSE 中断重连 / 用户连点 Send / 多 tab 撞车 → MWC 检测到同 draftSessionId 已有 session：
  • 状态 Provisioning → 复用现有 session，把 SSE 重新挂上去；
  • 状态 Active → 把 message 投递为本次 prompt（idempotent replay）；
• 所以"双击发送"不会建出两个 session，at-most-once 创建。

"New Chat" 触发点（前端 UX 入口）：

• 左侧 Session 列表上方的 ＋ New Chat 按钮；
• 切换到一个新 Page 后打开的 Copilot Pane 也是空 draft（如果这个 page 没有关联 session）；
• 切换 mode (Plan/Interactive/Autopilot) 不会 建 session — 这些字段每条消息都能改；
• 切换 model / context / attachments 不会 建 session — 全是 per-prompt 字段。

5. 一个 Prompt 的完整 SSE 时序

POST /workspaces/{w}/CopilotEnvironments/{a}/sessions/{s}/messages
{
  "message": "List my warehouses",
  "mode": "interactive",
  "model": "claude-sonnet-4.6",
  "context": { "workspaces":[...], "artifacts":[...] },
  "attachments": [ ... ]
}
  │ (SSE stream opens)
  ▼
[ session.provisioning ]      ← 仅新 session（lazy creation）
[ session.created      ]      ← 仅新 session
──────────────── Turn 1 ────────────────
assistant.turn_start
assistant.reasoning_delta × N    ← 推理 token 流
assistant.message_delta   × N    ← 回答 token 流
tool.start / tool.progress / tool.complete   ← server-side bash
tool.call → POST /tool-result                ← client-side（如 navigate）
permission.request → POST /permissions/{id}/respond   ← 流暂停
user_input.request → POST /user-input/{id}/respond    ← 流暂停
artifact.created / artifact.updated          ← Sync Service 派发
assistant.turn_end  { turnId }
──────────────── Turn 2 (chained) ───────
… (tool 结果继续 feed 给 LLM 触发的新 turn) …
──────────────────────────────────────────
session.idle      ← 整个 prompt 才算处理完，UI 解锁 Send 按钮

6. 并发模型 ── 关键不变量

7. 每个 Prompt 可独立配置的字段

下面这些字段每个 prompt 都可以改，无须重建 session：

• mode — interactive / plan / autopilot
• model — LLM 模型切换（前提：在已批准的 model 池里）
• connectionId — 同名 model 多 connection 时指定
• context — 用户每次发问可换 workspace、可点不同的 artifact、cell、visual
• attachments — 截图 / 文件（要求模型支持 vision）

但下面这些字段是 session-scoped，只在第一个 prompt 生效：

• agent — agent type（默认 GitHubCopilot）
• session 的 storage workspace + CSM artifact 绑定

8. Prompt 和 Context 是两条独立的输入流

9. 一个 Prompt 处理完后会落地哪些状态

• events.jsonl（容器内 InMemorySessionFs）追加 N 条 events — Suspend / Export 时才落到 OneLake
• state.json（hot path）更新 messageCount / lastActivity / lastMessageAt — 驱动 30 min idle 阈值（Q19）
• metadata.json 不变（write-once）
• session display name 首次自动生成时发 session.renamed SSE 事件

10. Session 与 Prompt 的常见误解

三种 Token 各自做什么？整个鉴权链路是怎样的？

容器内 永远看不到任何明文 token，但仍能调 Fabric API、OneLake、LLM、GitHub —— 靠的是 4 个角色 × 3 类 token × 1 个 Envoy egress 注入。理解这套体系是看懂所有 secret / refresh / re-auth 流程的前提。

① 关键 Token 一览

⚠️ 区分点：Browser 永远不直接持有 copilotWorkload1pToken 或 OBO 下游 token。它只看到 userEntraToken（调 Shared）和 mwcToken（调 MWC）。所有"容器侧 token"都被 MWC + KeyVault + Envoy 包起来。

② 浏览器侧：MWC Token 怎么获取 / 怎么刷

MWC token 用 generatemwctoken 私有 API（Shared 提供）从 userEntraToken 换得，scope 到具体的 (workspaceId, ceArtifactId) 二元组。

POST https://{clusterUri}/metadata/v201606/generatemwctoken
Authorization: Bearer {userFabricToken}
Content-Type: application/json

{
  "type": "[Start] GetMWCToken",
  "workloadType": "CopilotEnvironment",
  "workspaceObjectId": "{workspaceId}",
  "artifactObjectIds": ["{ceArtifactId}"],
  "capacityObjectId": "{capacityId}",
  "asyncId": "{guid}",
  "iframeId": "{guid}"
}

→ { mwcToken, mwcRolloutUrl, expiresAt }

CopilotHostService（Angular 层）按 (workspaceId, ceArtifactId) 缓存 MWC token，并用两层策略保持新鲜：

1. Proactive 预检：每次发 MWC 请求前看缓存 token 还剩多久；剩余 < 10 分钟就先 refresh Entra token → 调 generatemwctoken → 拿到新 MWC token → 再发原请求。
2. Reactive 兜底：万一发 MWC 时收到 401（比如刚预检完到发请求之间过期了）→ 刷一次 MWC token → 重试一次；如果第二次还 401，向用户报错。

Model 发现 / global session 列举 / CE CRUD 都走 Shared，直接用 userEntraToken 不走 MWC token。

③ Bootstrap 鉴权链（首条消息时，容器侧）

Browser ─── mwcToken ─────▶ MWC
                              │
                              │ ① OBO 换下游 token（多份不同 audience）
                              │ ② PUT /secrets/{secretId} (KeyVault) ─▶ ADC
                              │     存所有 OBO token（Fabric/OneLake/LLM/GitHub）
                              │
                              │ ③ PUT /sandboxes（egressRules.inject.secretRef = secretId）
                              ▼
                            ADC ──── 建 Firecracker microVM + Envoy sidecar
                              ▼
                        Container started
                              │
                              │ ④ POST /configure ──── copilotWorkload1pToken
                              │     audience: fabric/<container-id>
                              │     body: { refreshTokensAfterUtc, tokenExpirations }
                              │
                              └─ Container 启动 timer，记下 "啥时候该让 MWC 续 token"

④ 出站请求时怎么"看不到 token"

⑤ Token 刷新：Container-Initiated（推荐路径）

OBO token 有效期 1 小时左右。Container 内有 RefreshTimer：

1. Container timer 到 refreshTokensAfterUtc → 发请求给 MWC（Bearer 用容器自己的 MI token）
2. MWC 验签：用户原 token + MI token + sandbox ownership 三重校验
3. MWC OBO 换新的下游 token（多份不同 audience）
4. MWC 调 ADC PUT /secrets/{secretId} 全量替换（注意：PUT，不是 PATCH）
5. MWC 调 ADC POST /sandboxes/{id}/egresspolicy 把 egress 规则里的 secretRef 引用更新
6. MWC 调 Container POST /configure 给新的 refreshTokensAfterUtc → timer 重设

⑥ Reactive 再认证（OBO 失败兜底）

当用户 refresh token 过期 / consent revoke 时，OBO 会失败，容器拿不到下游服务的新 token：

1. SDK 拿到 401 → 容器在 SSE 流里发 session.reauth_required {}
2. 前端处理：① 关闭当前 SSE 流；② 弹"重新登录"（触发 Entra redirect）；③ 用户登录后拿新 userEntraToken；④ 调 generatemwctoken 拿新 MWC token；⑤ 重发上一条失败的请求—— 这次 MWC 端能拿到新 user token 跑 OBO，更新 KeyVault，容器 timer 重置。

⚠️ 没有专门的 /reauth API。前端在 reauth 后直接重发原 Send Message 请求即可：MWC 端验完新 user token，OBO 走通后，正常下发新 expiry。

⑦ 多 audience 的必要性

⑧ 关键不变量（团队介绍必讲）

• 🔒 容器进程地址空间从不持有任何 token 明文 —— 全靠 Envoy 网络层注入
• 🌐 浏览器只看到 2 个 token：userEntraToken（→ Shared）和 mwcToken（→ MWC）
• 🔁 Token 刷新发生在 KeyVault + egress rule 层，不打断容器进程 / SDK 状态
• 🎯 每个 audience 一份 token，不复用 —— 防止权限放大
• ⚠️ PUT /secrets 是 全量替换，并发 PUT 必须串行化（MWC 内部用锁）
• 🚨 Reauth 是用户感知的——SSE 推 session.reauth_required，前端关流 → 重新登录 → 刷 MWC token → 重发原请求

Skills 是怎么加载的？版本怎么管？

Skills 是 SKILL.md 文件（教 LLM 怎么用 Fabric 各 workload 的 API）。它不进容器镜像，从 CDN 动态加载——这样 workload team 改 skills 不用重建镜像，也不用平台 team 介入。

① 全链路：从仓库到容器

② 加载时机（4 个关键节点）

③ 关键设计：Skills 与镜像解耦

④ 版本管理 / 滚动升级

• 新 session 启动时自动拉最新 skill 版本（manifest 决定）
• 已有 session 保持创建时加载的 skills 版本（防止 prompt 中途变化让 LLM 行为漂移）
• 下次该 session cold restore（resume 失败兜底）时，新容器会重新拉 skills —— 这是天然的 rolling upgrade 通道

⑤ 与 MCP Server / Plugin 怎么协同

注意区分 3 类自助贡献机制：

⑥ 关键不变量

• 📦 Skills 是"distributed as code, not as cloud services"（D-3 / D-5）—— CLI / VS Code / Portal 都装同一份 gim-home/skills-for-fabric
• 🔁 一个 session 内 skills 不变（不污染 prompt），跨 session 自动用最新
• 🛟 容器镜像里有 baked skills 作为 fallback，保证 Shared 不可达也能启动
• ⚙️ 改 SKILL.md ≠ 改镜像 —— PR 合并到生产 < 2 工作日（详见 Q14）

Copilot Environment Artifact 是什么？为什么 session 要寄宿在 artifact 里？

Copilot Environment（CE）是一种 Fabric artifact 类型，专门承载 copilot session。它在 OneLake 里有自己的文件夹，所有 session 数据（metadata / state / events / 文件）都存在这个 artifact 的 OneLake 路径下。把 session 包在 artifact 里，是 fabric-ai-framework 的核心架构决定（004-session-storage.md 选项 A）。

① 为什么不是直接放 OneLake，而是包成 artifact？

📌 心智：CE 是 "装 session 的 Fabric 标准盒子"。盒子继承 Fabric 平台的 CMK / 备份 / 共享 / 权限 / 迁移能力，团队不用自己造一遍。

② CE artifact 的属性

③ CRUD API（走 Shared，Browser 直接调）

Base：https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}
Auth：Bearer {userEntraToken}

④ 从 CE 到 MWC：generatemwctoken 桥

公共 GET /v1/workspaces/{wsId}/items/{itemId} 只返回 artifact metadata，不带 MWC 端点。要调 MWC 必须先经一个私有 API 拿 MWC token + rollout URL：

POST https://{clusterUri}/metadata/v201606/generatemwctoken
Authorization: Bearer {userFabricToken}

{
  "type": "[Start] GetMWCToken",
  "workloadType": "CopilotEnvironment",      ← 关键：用 CE 类型
  "workspaceObjectId": "{workspaceId}",
  "artifactObjectIds": ["{ceArtifactId}"],   ← 必须带 CE 的 GUID
  "capacityObjectId": "{capacityId}",
  "asyncId": "{guid}",
  "iframeId": "{guid}"
}

→ { mwcToken, mwcRolloutUrl, expiresAt }

之后所有 session / messaging / tools / attachments API 都走 {mwcRolloutUrl}/public/workspaces/{wsId}/CopilotEnvironments/{ceId}/...，Bearer {mwcToken}。详见 Q18 ② 浏览器侧 MWC token 刷新策略。

⑤ 用户流程：从打开 sidecar 到发首条消息

⑥ Session 在 CE 里的目录结构

{workspace}/{CE-artifact}/
├── indexes/                                    # 可重建的投影
│   ├── owned/<tenantOid>/<userOid>/<sessionId>.json    # 空文件 = 指针
│   └── shared/<tenantOid>/<userOid>/<sessionId>.json   # {sharedBy, sharedAt, permissions}
└── sessions/
    └── <fabricSessionId>/
        ├── metadata.json       # 写一次永不动      {agent, createdAt}
        ├── settings.json       # 偶尔写 (ETag)    {model, displayName, modelConnectionId}
        ├── state.json          # 每消息写         {sandboxId, lastInteractionAt, messagesCount}
        ├── session-state/
        │   └── events.jsonl    # export 时写入 (完整对话)
        └── files/              # agent 创建的产物文件

⑦ Permission Model：私有 sessions in 共享 artifact

设计 trade-off（006-artifact-model.md）：

⑧ 关键不变量

• 📦 每个 session 必须寄宿在某个 CE artifact 下，没有"裸 session"
• 🔁 同一 workspace 可以有多个 CE，分别给不同团队 / 项目 / 私有场景
• 🆔 generatemwctoken 的 scope 是 (workspaceId, ceArtifactId)，换 CE 必须换 token
• 🧹 删 CE = 删该 CE 下所有 session（artifact 自动级联）
• 📜 旧名 CSM (Copilot Sessions Manager) 仍出现在文件命名（012-csm-management.md）和前端 doc 路径段中，与 CopilotEnvironment 是同一概念

前端架构：Angular Shell + React Chat Pane 怎么协作？

Fabric Portal 是 Angular，但 Chat Pane 用 React 实现。两边通过 CopilotHostService（Angular 服务）+ CopilotHostComponent（Angular-React 桥）+ CopilotPaneApi（facade）三层粘合。React 永远不直接调后端。

① 架构总览

┌────────────────── Fabric Shell (Angular) ──────────────────┐
│                                                            │
│  ┌── Shared Experience ──┐  ┌── Classic Artifact ──┐       │
│  │ context: workspace     │  │ context: visual      │       │
│  │ tools: navigate        │  │ tools: edit visual   │       │
│  └────────┬───────────────┘  └────────┬─────────────┘       │
│           │ Direct call               │ Direct call         │
│           ▼                           ▼                     │
│  ┌── Extension Artifact (iframe) ──┐                        │
│  │ context: focused cell           │ ←─ postMessage         │
│  │ tools: run cell                 │    (Extension API)     │
│  └────────┬────────────────────────┘                        │
│           │                                                  │
│           ▼                                                  │
│  ┌──── CopilotHostService (Angular, 单例) ─────────────┐    │
│  │  · gather + merge context（Shell + Page）            │    │
│  │  · dispatch client tools via executeAction()         │    │
│  │  · SSE processing（拦截 tool.call → invoke → 合成    │    │
│  │    client_tool.start/complete 推给 React）          │    │
│  │  · MWC token 缓存 / 401 重试                         │    │
│  │  · CopilotHttpService 子服务负责 HTTP/SSE            │    │
│  │    - Shared API（userEntraToken）                    │    │
│  │    - MWC API（mwcToken）                             │    │
│  └─────────────────────────┬────────────────────────────┘    │
│                            │ CopilotPaneApi facade            │
│  ┌──── CopilotHostComponent (Angular) ──────────────┐         │
│  │      ▼ createRoot(domElement)                    │         │
│  │  ┌── Chat Pane (React + Fluent v9) ─────────────┐│         │
│  │  │ Header: New Session / Sessions               ││         │
│  │  │ Messages: User / Assistant / Tool / Approval ││         │
│  │  │ Input: Pills / Attach / Model / Mode / Send  ││         │
│  │  └──────────────────────────────────────────────┘│         │
│  └───────────────────────────────────────────────────┘        │
└──────────────────────────────────────────────────────────────┘

② 三个 page 类型怎么贡献 context / tool？

③ CopilotPaneApi facade — React 唯一的后端入口

Angular 把这个对象作为 prop 传给 React，React 调 facade 方法就行：

interface CopilotPaneApi {
  // Session management
  listSessions(): Promise<SessionInfo[]>;
  getSession(sessionId: string): Promise<SessionInfo>;
  updateSession(sessionId: string, displayName: string): Promise<void>;
  deleteSession(sessionId: string): Promise<void>;

  // Messaging — Angular 内部处理 SSE（含 tool.call 拦截、returnToolResult）
  // 返回流只含 UI 相关事件，React 拿到的是 CopilotUIEvent[]
  // 新 session 时 sessionId 传 null，request 里带 targetSession:'new' + draftSessionId
  sendMessage(sessionId: string | null, request: SendMessageRequest): Observable<CopilotUIEvent>;
  getMessages(sessionId: string): Promise<Message[]>;

  // Turn 控制 — abort 同时取消 backend turn + in-progress 的 client tool
  abort(sessionId: string): Promise<void>;
  respondToPermission(sessionId, requestId, approved, feedback?): Promise<void>;
  respondToUserInput(sessionId, requestId, answer): Promise<void>;

  // Models（走 Shared，scope 到 workspace）
  listModels(workspaceId: string): Promise<ModelOption[]>;

  // Attachments
  addAttachment(sessionId, type, resourceId): Promise<AttachmentInfo>;
  listAttachments(sessionId): Promise<AttachmentListInfo>;
  removeAttachment(sessionId, attachmentId): Promise<void>;
}

④ SSE 处理：Angular 拦截 tool.call，React 只看 UI 事件

后端 SSE 有 18+ 种事件，但 tool.call 不能直接给 React —— 它需要触发本地 action、等结果、回传给 MWC。Angular 在 CopilotHostService 内拦截：

React 看到的 UI 事件类型（精简版）：

type CopilotUIEvent =
  | { type: 'session.provisioning'; draftSessionId; status }
  | { type: 'session.created'; sessionId; draftSessionId; status }
  | { type: 'assistant.turn_start' }
  | { type: 'assistant.message_delta'; delta }
  | { type: 'assistant.message'; content; messageId }
  | { type: 'assistant.reasoning_delta'; delta }
  | { type: 'assistant.reasoning'; content }
  | { type: 'assistant.turn_end'; turnId }
  | { type: 'tool.start' | 'tool.progress' | 'tool.complete'; ... }     // 服务器端 tool（直传）
  | { type: 'client_tool.start' | 'client_tool.complete'; ... }         // 客户端 tool（Angular 合成）
  | { type: 'permission.request'; ... }
  | { type: 'user_input.request'; ... }
  | { type: 'artifact.created' | 'artifact.updated'; ... }
  | { type: 'session.idle' | 'session.error' | 'session.expired' | 'session.reauth_required' | 'session.renamed' | 'session.resuming'; ... };

⑤ React State Model（关键字段）

interface SessionState {
  sessionId: string;
  draftSessionId: string | null;        // session.created 之前非 null
  displayName: string;
  selectedModel: string;
  selectedModelProviderType: 'GitHubCopilot' | 'AzureAIFoundry' | 'FabricCapacity';
  selectedModelConnectionId: string | null;   // Fabric Capacity 时 null
  executionMode: 'plan' | 'interactive' | 'autopilot';
  interactiveState: 'Starting' | 'Running' | 'Idle' | 'WaitingForInput' | 'WaitingForApproval' | 'Error';
  sandboxState: 'Provisioning' | 'Active' | 'Suspending' | 'Suspended' | 'Resuming' | 'Terminated' | 'Unknown';
  messages: ChatMessage[];
  streamingBlocks: TurnBlock[];          // 当前 turn 内的 reasoning / message / tool 块
  attachments: AttachmentInfo[];
  attachmentTokenBudget: { used: number; total: 50000 };
  isLoading: boolean;
  pendingQuestion: PendingQuestion | null;
  pendingPermission: PendingPermission | null;
}

• 本地 UI 状态：selectedModel / executionMode / selectedModelConnectionId 都是 client-side，每次发消息时随 request 带过去
• 从后端来的状态：interactiveState / sandboxState（详见 Q24）经 Get Session API 拿到，活动流期间根据 SSE 事件本地推进
• 不暴露给 React：MWC token、host URL、CE artifact 坐标（workspaceId / artifactId）—— 都在 CopilotHostService 内部
• 用 React 内置 useState / useReducer / Context 管理；不引入 Redux

⑥ 组件库：@fabric-msft/copilot-react

Chat Pane 基于 Client Engineering Systems 提供的 @fabric-msft/copilot-react—— 成熟、对齐 Microsoft Copilot Design 规范，并按 Fabric 视觉风格定制。无需自造组件。

⑦ 关键不变量

• 🔐 React 永远不直接调后端 —— 所有 HTTP / SSE / token 都在 Angular 层
• 📡 SSE 处理拆两阶：Angular 拦截 tool.call → 本地 dispatch → 合成事件 → React
• 🔁 Context 和 Tool manifest 都由 CopilotHostService 收集（详见 Q22 / Q23）
• 🎨 用 Fluent UI v9 + @fabric-msft/copilot-react，不引入 VS Code Copilot Chat 那套
• 📐 React 用 hooks + Context，不引入 Redux

Context 系统：前端怎么把"用户正在做什么"告诉 LLM？

LLM 需要知道当前 workspace / artifact / 用户在 page 内选了什么。前端按规则自动从 Shell + 当前 page 收集 context，合并、缓存，并随每条消息发给后端。用户看到的"context pill"和发给后端的 payload 是两个不同形状。

① Context 的 3 类

customContext 三层 scope：workspace-related / artifact-related / global，分别挂在 workspaces[].customContext / artifacts[].customContext / top-level customContext 数组里。

② End-to-End 流程

③ 两种形状：客户端 (有 pill 元数据) vs 服务端 (纯数据)

客户端 shape（含 UI 用的 reference 字段）：

interface CopilotContext {
  workspaces: CopilotWorkspaceContext[];
  artifacts:  CopilotArtifactContext[];
  customContext: CopilotCustomContextEntry[];  // global
}

interface CopilotCustomContextEntry {
  descriptor: string;          // snake_case，作为 server shape 里的属性名
  value: object;               // LLM 看到的数据
  reference?: {                // 可选 UI 元数据 —— 有它才渲染成 pill（"explicit"）
    label: string;             // 仅 bare label；前缀由平台拼
    icon: PortalSvgIcon;
    dismissible: boolean;
  };
}

服务端 shape（无 pill 概念，customContext 折叠成 Record）：

interface CopilotContextPayload {
  workspaces: CopilotWorkspaceContextPayload[];
  artifacts:  CopilotArtifactContextPayload[];
  customContext: Record<string, object>;   // descriptor → value 的 map
}

两个推论：

• descriptor 必须 scope 内唯一—— 重复会在转 Record 时静默覆盖
• pill 状态完全不影响 payload—— 用户 dismiss / workload 没设 reference，LLM 看到的数据一致

④ Pill 渲染规则

💡 workload 只给 bare label（如 Line 21-29），平台自动加父级前缀（SQL 1:）—— 这样改 artifact 命名规则只动平台。

⑤ CopilotManifest：page 怎么注册 context provider

interface CopilotManifest {
  name: string;
  featureSwitch?: boolean | string;
  match: (url: string) => boolean | undefined;   // 当前 URL 匹配才参与
  getContext: PortalAction | ExtensionAction;     // dispatched 后返回 Partial<CopilotContext>
}

• URL-scoped：只有 match() 返回 true 的 第一个 manifest 参与（context 与当前 URL 关联）
• featureSwitch：falsy 的 manifest 不参与
• getContext：classic artifact 用 PortalAction（Angular DI handler），extension artifact 用 ExtensionAction（跨 iframe 经 postMessage）

⑥ refreshContext：何时被调？

⑦ Strip-Before-Send + Pill Suppression

发消息前的 2 步处理：

1. 从缓存 client-shape 出发，先应用 pill suppression list（用户在本次会话里 dismiss 过的 entry 不发）
2. 遍历对象，移除每个 reference 字段；customContext 数组折叠成 Record

suppression list 每次 send 完清空—— workload 只要下次 getContext 还返回这个 entry，pill 就回来。

⑧ Size Limit

⑨ 例子：SQL 编辑器选了 21–29 行

用户在 SQL 编辑器选了 21-29 行，背景还开着 1 个 Notebook + 1 个 Lakehouse；提示词 "把选中的 SQL 改成从 Lakehouse 1 读数据"。

客户端合并后渲染的 pill：

server payload（strip 后）—— LLM 看到：3 个 artifact（含 SQL artifact 的 selected_query 字段+ full_query + editor_state），但没有任何 pill 字段。

⑩ 关键不变量

• 🎯 Context 是 URL-scoped：只有当前匹配 manifest 的 page 贡献 page-specific
• 👁 Pill 形状 ≠ payload 形状：UI 状态（reference / dismiss）不影响 LLM 看到的数据
• 🪒 8 KB 序列化上限，超了优先保 Shell context
• 🔁 自动 refresh：新 session + 每发完一条消息（不要 workload 自己 watch 重置）
• 🐌 On-demand refresh 必须 throttled（不许 keystroke 触发）

Tools / Models / Modes：3 个用户可控的会话参数怎么传到后端？

每条 Send Message 都带 3 类参数：能调什么工具（tools）、用哪个模型（model triple）、怎么用工具（mode）。三者各有不同的注册 / 选择 / 生命周期。

① Tools（客户端工具）

关键约束：Session-scoped，全 portal 一份静态 manifest

ToolDefinition 接口

interface ToolDefinition {
  readonly name: string;                 // 全 portal 唯一
  readonly description: string;
  readonly parameters: JSONSchema;
  readonly invoke: PortalAction | ExtensionAction;
  readonly abort:  PortalAction | ExtensionAction;
  readonly featureSwitch?: boolean | string;
}

interface CopilotToolManifest {
  readonly tools: readonly ToolDefinition[];
}

name / description / parameters 发给后端作 clientTools；invoke / abort 留在前端，由 CopilotHostService 在 SSE 收到 tool.call 时 dispatch。

调用周期（7 步）

1. 后端 SSE tool.call { toolCallId, tool, input }
2. Angular 合成 client_tool.start 给 React → Chat Pane 渲染 Tool Card（running）
3. 查 manifest：
   • 命中：executeAction(tool.invoke) 走 portal action handler（classic）或 postMessage（extension）
   • 未命中（page 已卸载）：合成错误结果 { status: 'error', error: 'Tool not available...' }
4. 拿到结果
5. POST /tool-result { toolCallId, result }
6. 合成 client_tool.complete 给 React → Tool Card 状态变 complete / error
7. 后端把 result 喂给 LLM，LLM 可能继续调更多 tool 或出最终答复

② Models（连接式架构）

3 类 Provider，每个 connection 提供多个 model

每条消息发 model triple

用户在 picker 选一个 model，前端内部解析成 (modelConnectionId, modelProviderType, modelId)，作为 3 个独立字段发到 Send Message：

{
  "message": "Refactor this notebook ...",
  "model": "gpt-5.1",
  "modelProviderType": "AzureAIFoundry",
  "modelConnectionId": "conn-xxx",
  "mode": "interactive",
  ...
}

Model 发现 API：走 Shared

用 userEntraToken 调（不需要 MWC token）：

Model 元数据驱动 UI

• supportsVision：false 时禁用图片附件按钮
• costIndicator：low / medium / high —— picker 可显示成本提示
• supportedReasoningEfforts：数组（low | medium | high）+ defaultReasoningEffort —— 是否暴露给用户调还是 Open Question
• Connection status：Available / Warning / Unavailable；status code 如 AuthExpired / PermissionDenied / EndpointUnreachable / CapacityNotAssigned → 决定要不要弹"重新授权"

切模型

Model 是本地 UI 状态，每发一条消息时随 request 带过去。首条消息确定 session 初始 model；中途切了，下一条消息生效（MWC 更新 session metadata）。

③ Modes（执行模式：3 选 1）

Mode 是客户端本地状态，作为 mode 字段发给后端，不存为 session 属性。

Plan → Execute 转换

当前是 plan 模式 + 收到 session.idle（LLM 出完计划）→ 在最后一条 assistant message 上渲染两个按钮：

• Start implementation → 切到 interactive 模式 → 自动发 { message: "Execute the plan.", mode: "interactive" }
• Start with autopilot → 切到 autopilot 模式 → 自动发 { message: "Execute the plan.", mode: "autopilot" }

这套用户行为对齐 GitHub Copilot CLI / VS Code Chat，体验跨 surface 一致。

④ 三者怎么打包发到后端

POST {mwc}/.../CopilotEnvironments/{ceId}/sessions/{sid}/messages
Authorization: Bearer {mwcToken}

{
  "message": "...",
  "mode": "interactive",
  "model": "gpt-5.1",
  "modelProviderType": "AzureAIFoundry",
  "modelConnectionId": "conn-xxx",
  "context": { /* workspaces / artifacts / customContext */ },
  "clientTools": [ { name, description, parameters }, ... ],
  "attachments": [ /* inline images (base64) */ ]
}

⑤ 关键不变量

• 🔒 Tool manifest 是 portal-wide 静态 + featureSwitch 控制，session 内不变（SDK 限制）
• 🪪 Model 三元组（connectionId + providerType + modelId）每条消息都发，session 内可换
• 👁 supportsVision = false → 禁用图片附件按钮
• 📋 Plan / Interactive / Autopilot 是客户端状态，每条消息发一次
• ✨ Plan → Execute 是 UX 糖：自动发 "Execute the plan." 并切 mode；用户也能手动改

会话状态机：interactiveState × sandboxState（11 种 UX 组合）

一个 session 有两个独立的状态维度。它们组合起来决定 Chat Pane 该显示什么 spinner / 卡片 / banner。这是把 Q16 容器生命周期和 SDK 运行态拆开的最干净视角。

① 两个维度

interactiveState — SDK / Copilot 在做什么

sandboxState — ADC sandbox / 容器在做什么

② 组合显示矩阵（Chat Pane 渲染什么）

③ 状态从哪里来？

初始 / 不在活动流：调 Get Session API

GET {mwc}/.../CopilotEnvironments/{ceId}/sessions/{sid}
→ { sessionId, displayName, model, interactionState, sandboxState?, ... }

interactionState 字段映射到 interactiveState；当 sandbox 不是 Active 时返回 sandboxState。

活动 SSE 流中：根据事件本地推进

④ 自动暂停 / 恢复：用户不用管

MWC sweeper 在以下情况主动暂停（详见 Q15 "什么时候发 POST /export"）：

• Idle ≥ 30 分钟 → Suspending → Suspended（memory snapshot + OneLake export）
• WaitingForInput / WaitingForApproval ≥ 2 小时 → 同上
• Error ≥ 15 分钟 → Suspending → Terminated（彻底销毁）
• Running 永远不暂停（不打断 agent 思考链）

用户回来发消息 → MWC 看到 Suspended → 自动 Resuming（memory mode）→ Active；resume 失败 → cold restore（PUT 新 sandbox + POST /import）。对用户完全透明，只在 spinner 上看一下"Resuming session…"。

⑤ "Session 不死，Container 用完即弃"

架构上 fabricSessionId 是永久（OneLake 文件夹名），sandboxId 在生命期内可能换多次（每次 cold restore 是新 microVM）。也就是说同一 sessionId 时间维度上 1:N sandboxId。详见 Q8。

⑥ 关键不变量

• 🔢 两个维度独立—— 一个 Suspended 的 sandbox 可以"保留"上次的 interactiveState，并不重置
• 📺 Chat Pane 把组合渲染到唯一一个状态条 / 卡片，不让用户面对两个状态字段
• ⏱ 自动 suspend 阈值：Idle 30min / Waiting 2h / Error 15min
• 🛡 Cold restore 走 OneLake export（events.jsonl 重放），即使容器被销毁也能恢复对话
• 🔁 Outside SSE → 轮询 Get Session；inside SSE → 按事件本地推进

"Copilot CLI" 在 Fabric Copilot 里到底指什么？

一句话结论

1. 同一颗"大脑"，三种装法

2. 三个意义详解

① GitHub Copilot CLI（公开产品，iteration 1 首发的 Fabric UX）

② GitHub Copilot SDK / Agent（装在 ADC Container 里，Fabric portal 的"内核"）

③ CLIPlayground（仓库内部工具，给团队开发用）

3. 怎么判断文档/会议里说的是哪个

4. 常见混淆与正解

附录 A — 关键 API 速查

ADC Control Plane（MWC 调）

Agent Container（MWC 调容器）

⚠️ 注：早期文档（065-agent-design.md）曾出现 POST /update-tokens 和 GET /readiness，但当前 040-container-spec.md 是权威——token 刷新统一走 /configure，readiness 不再单独暴露。

SSE 事件清单

附录 B — 参考文档清单

所有链接指向 GitHub repo: azure-data-intelligence-platform/fabric-ai-framework

顶层

• README.md — 4 层架构表
• decisions.md — 12 项 D-1..D-12 决策

Engineering / Decisions

• engineering/000-decisions/001-decisions.md
• engineering/000-decisions/002-adc-vs-foundry-vs-aci.md
• engineering/000-decisions/003-A-proxy-vs-noproxy.md — SecretRef JSON 示例
• engineering/000-decisions/004-session-storage.md

Architecture

• engineering/010-architecture/010-!!-architecture.md
• engineering/010-architecture/011-sessions-responsibilities.md
• engineering/010-architecture/013-sessions-store.md

Agent

• engineering/060-agent/065-agent-design.md
• engineering/060-agent/066-skills-loading.md

Education / Deployment / Frontend

• engineering/.education/adc-apis-reference.md
• engineering/100-solution-deployment/100-solution-deployment.md
• engineering/300-frontend/300-!!-frontend-dev-design.md

Specs / Building Blocks & Features

• specs/building-blocks/plugin.md
• specs/building-blocks/plugin-contribution.md
• specs/building-blocks/copilot-item.md
• specs/features/08-change-approval.md
• specs/features/09-copilot-item.md
• specs/features/13-inline-tool-ui-platform.md
• specs/features/14-evaluation-platform.md

Prototype

• Prototypes/UnifiedAIPlatform/react-prototype/package.json