aukeys-opscli 0.0.20__tar.gz → 0.0.22__tar.gz

{aukeys_opscli-0.0.20 → aukeys_opscli-0.0.22}/CLAUDE.md

@@ -31,6 +31,19 @@ opscli/
 │   └── storage/
 │       ├── credential_store.py  # Keychain 优先 / AES-256-GCM 兜底
 │       └── crypto.py            # AES-256-GCM 加密工具
+├── mcp/                     # MCP 子模块（Model Context Protocol 服务）
+│   ├── __init__.py
+│   ├── server.py            # FastMCP 实例，注册所有 MCP Tools
+│   ├── auth_middleware.py   # SSE/HTTP 连接层 API Key 鉴权
+│   ├── credential_cache.py  # 内存凭证缓存（避免高频 AES 解密）
+│   ├── session_store.py     # ⚠️ 已废弃，兼容包装层（v0.0.5+）
+│   ├── user_store.py        # 多用户 API Key 注册表（团队共享场景）
+│   ├── cli.py               # MCP 管理 CLI（opscli mcp user *）
+│   └── tools/               # MCP Tools 注册
+│       ├── helpers.py       # 共享辅助函数（_get_session_id / _get_jwt）
+│       ├── auth.py          # auth_* 工具集（13 个）
+│       ├── query.py         # query_* 工具集
+│       └── skills.py        # skills_* 工具集
 ├── query/                   # query 子模块（数据查询）
 │   ├── __init__.py
 │   ├── cli.py               # query 子命令（metadata/run/build）
@@ -93,6 +106,9 @@ opscli skills
 | auth 服务地址 | `opscli/auth/config.py`（DEFAULTS + load_config） |
 | Token 管理 | `opscli/auth/core/token_manager.py` |
 | 凭证存储 | `opscli/auth/storage/credential_store.py` |
+| MCP 服务入口 | `opscli/mcp/server.py`（FastMCP 实例） |
+| MCP 凭证缓存 | `opscli/mcp/credential_cache.py`（McpCredentialCache） |
+| MCP auth 工具 | `opscli/mcp/tools/auth.py`（auth_* 工具集） |
 | query 业务编排 | `opscli/query/manager.py`（QueryManager） |
 | query HTTP 转发 | `opscli/query/client.py`（QueryClient） |
 | Skill 管理协调 | `opscli/skills/manager.py`（SkillsManager） |
@@ -194,7 +210,30 @@ store = CredentialStore()
 
 网络请求使用 `respx` 进行 mock，不可发起真实 HTTP 请求。
 
-### 【铁律9】内置系统（ops/polaris）不可在代码中被删除
+### 【铁律9】CLI 与 MCP 的凭证存储必须统一（CredentialStore）
+
+2025-04-27 重构后，CLI 模式和 MCP 模式**共用同一套 CredentialStore**，禁止在 MCP 中引入独立的明文存储：
+
+- **唯一存储层**：`opscli/auth/storage/credential_store.py`（Keychain / AES-256-GCM）
+- **MCP 读路径**：通过 `McpCredentialCache` 内存缓存读取，避免高频 AES 解密
+- **MCP 写路径**：登录/刷新/登出等操作统一写入 `CredentialStore`，写后调用 `invalidate_credential_cache()` 刷新缓存
+- **`mcp_sessions.json` 已废弃**：`opscli/mcp/session_store.py` 仅保留兼容包装层，内部转发到 `CredentialStore`
+
+**正确示例**（MCP auth tool 保存 session）：
+```python
+from opscli.auth.storage.credential_store import CredentialStore
+from opscli.mcp.credential_cache import invalidate_credential_cache
+
+CredentialStore().save_session(session_id, email, expires_at)
+invalidate_credential_cache()  # 刷新内存缓存
+```
+
+**禁止行为**：
+- ❌ 在 MCP 中直接读写 `mcp_sessions.json`
+- ❌ 为 MCP 引入新的独立存储文件
+- ❌ 绕过 `CredentialStore` 自行管理凭证
+
+### 【铁律10】内置系统（ops/polaris）不可在代码中被删除
 
 `auth/config.py` 的 `get_builtin_systems()` 定义了两个内置系统，这是产品功能约定：
 - `ops`：运营系统（https://ops.api.qa.aukeyit.com）
@@ -202,7 +241,7 @@ store = CredentialStore()
 
 内置系统在 `system_registry.py` 中有保护逻辑（`remove()` 会拒绝删除 builtin 系统），不可绕过此保护。
 
-### 【铁律10】Skills 禁止直连后端 API，所有操作必须经由 opscli 模块转发
+### 【铁律11】Skills 禁止直连后端 API，所有操作必须经由 opscli 模块转发
 
 涉及数据查询、认证、元数据获取等能力时，**Skill 脚本不能直接调用**后端 HTTP API，必须统一通过 `opscli` 的正式命令入口执行。
 
@@ -220,7 +259,7 @@ store = CredentialStore()
 4. 认证、参数校验、payload 组装、错误映射统一由 `opscli` 负责
 5. 后端新增接口时，默认先补 `opscli` 对应入口，再让 Skill 消费
 
-### 【铁律11】Skill 命名必须使用 `ops-` 前缀
+### 【铁律12】Skill 命名必须使用 `ops-` 前缀
 
 所有内置 Skill（`opscli/skills/templates/` 下的子目录）命名必须以 `ops-` 开头：
 
@@ -235,7 +274,7 @@ store = CredentialStore()
 - 新增 Skill 时若不带 `ops-` 前缀，视为命名不合规，必须改名后再合入
 - 安装命令示例：`opscli skills install ops-auth`
 
-### 【铁律12】新增 Skill 必须遵循完整接入规范
+### 【铁律13】新增 Skill 必须遵循完整接入规范
 
 新增 Skill 时，根据是否需要远端升级分两条路径：
 
@@ -272,7 +311,7 @@ store = CredentialStore()
 - 必须包含"典型工作流"章节
 - 格式参照 `ops-auth/SKILL.md` 或 `ops-dataset-query/SKILL.md`
 
-### 【铁律13】依赖版本约束不加不必要的上限
+### 【铁律14】依赖版本约束不加不必要的上限
 
 `pyproject.toml` 中的依赖版本约束只设下限，**不加上限**，除非有明确的 API 不兼容证据：
 
@@ -287,7 +326,7 @@ store = CredentialStore()
 
 **教训**：`cryptography>=38,<42` 曾导致 pip 强制降级系统已有的 v46，破坏同环境中其他包（`opscli`）。上限约束应在有明确 breaking change 时才添加，并在注释中说明原因和对应 issue。
 
-### 【铁律14】文档必须按类型分类存放，文件名必须使用中文
+### 【铁律15】文档必须按类型分类存放，文件名必须使用中文
 
 所有项目文档必须遵循以下规范：
 
@@ -308,7 +347,7 @@ store = CredentialStore()
 3. 同一类型的文档放入同一目录，不可散落
 4. 方案类文档如涉及多阶段，可加阶段后缀（如"取数底座**一期**开发计划"）
 
-### 【铁律15】所有代码必须有中文注释，重要业务逻辑必须全面注释
+### 【铁律16】所有代码必须有中文注释，重要业务逻辑必须全面注释
 
 编写或修改任何 Python 代码时，必须遵循以下注释规范：
 

{aukeys_opscli-0.0.20 → aukeys_opscli-0.0.22}/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: aukeys-opscli
-Version: 0.0.20
+Version: 0.0.22
 Summary: Aukeys 运营 CLI 工具集
 Requires-Python: >=3.10
 Requires-Dist: cryptography>=38
+Requires-Dist: fastmcp>=2.0
 Requires-Dist: httpx>=0.27
 Requires-Dist: keyring>=25
+Requires-Dist: playwright>=1.44
 Requires-Dist: rich>=13
 Requires-Dist: typer>=0.12
-Provides-Extra: amazon
-Requires-Dist: playwright>=1.44; extra == 'amazon'
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
-Provides-Extra: mcp
-Requires-Dist: fastmcp>=2.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # opscli

{aukeys_opscli-0.0.20 → aukeys_opscli-0.0.22}/README_MCP.md

@@ -28,9 +28,9 @@
 ## 安装依赖
 
 ```bash
-pip install "aukeys-opscli[mcp]"
+pip install aukeys-opscli
 # 或本地开发环境
-uv pip install -e ".[mcp]"
+uv pip install -e .
 ```
 
 ---

aukeys_opscli-0.0.22/docs/design/opscli-session/345/205/261/347/224/250/346/200/247/345/210/206/346/236/220/344/270/216/344/274/230/345/214/226/346/226/271/346/241/210/346/212/245/345/221/212.md

@@ -0,0 +1,389 @@
+# opscli CLI 与 MCP 模式 Session 共用性分析与优化方案报告
+
+> 报告日期：2025-04-27
+> 分析范围：opscli 项目中 CLI 模式与 MCP 模式的 Session 存储机制、数据隔离原因及共用优化路径
+
+---
+
+## 一、执行摘要
+
+当前 opscli 的 CLI 模式与 MCP 模式存在**两套完全独立的 Session 存储体系**，导致用户在任一模式下完成 Device Flow 授权后，另一模式无法识别该登录态，必须重复授权。本报告从**存储机制、数据结构、代码耦合、安全策略、设计哲学**五个维度深入分析不能共用的根本原因，提出三种优化方案，并给出推荐实施路径。
+
+**核心结论**：推荐采用 **方案 A：MCP 全面复用 CredentialStore + 内存缓存**，在保持架构简洁的前提下，通过统一底层存储实现 Session 互通，消除重复授权问题。
+
+---
+
+## 二、现状深度分析
+
+### 2.1 两套存储机制对比
+
+| 对比维度 | CLI (CredentialStore) | MCP (SessionStore) |
+|----------|----------------------|-------------------|
+| **文件路径** | `~/.config/opscli/credentials.bin` | `~/.config/opscli/mcp_sessions.json` |
+| **存储格式** | AES-256-GCM 加密二进制 / Keychain | 明文 JSON |
+| **密钥管理** | 自动生成 256-bit 密钥，`.key` 文件权限 600 | 无加密，纯文本 |
+| **数据结构** | 单一 Blob：`{session_id, email, tokens}` | 按系统分组：`{sessions: {ops: {session_id, jwt}}}` |
+| **session 语义** | **全局登录态**，一个 session 换取所有系统 JWT | **按系统绑定**，每个系统独立存 session_id |
+| **写入时机** | `DeviceFlow.poll_once()` 自动写入 | `auth_login_poll()` 成功后手动写入 |
+| **DeviceFlow store** | `store=CredentialStore()` | `store=None`（无状态） |
+
+### 2.2 数据结构差异详解
+
+**CLI CredentialStore 存储结构**（`opscli/auth/storage/credential_store.py` 第 8-20 行）：
+
+```json
+{
+  "session_id": "sess_abc123",
+  "device_code": "dev_xyz789",
+  "email": "user@aukeys.com",
+  "session_expires_at": "2025-04-28T10:00:00+00:00",
+  "tokens": {
+    "ops": {
+      "jwt": "eyJhbG...",
+      "expires_at": "2025-04-27T12:00:00+00:00",
+      "saved_at": 1714212000
+    },
+    "polaris": {
+      "jwt": "eyJhbG...",
+      "expires_at": "2025-04-27T12:00:00+00:00",
+      "saved_at": 1714212000
+    }
+  }
+}
+```
+
+**MCP SessionStore 存储结构**（`opscli/mcp/session_store.py`）：
+
+```json
+{
+  "version": 2,
+  "sessions": {
+    "ops": {
+      "session_id": "sess_abc123",
+      "jwt": "eyJhbG...",
+      "saved_at": "2025-04-27T10:00:00Z",
+      "jwt_saved_at": "2025-04-27T10:00:00Z"
+    },
+    "polaris": {
+      "session_id": "sess_abc123",
+      "jwt": "eyJhbG...",
+      "saved_at": "2025-04-27T10:00:00Z",
+      "jwt_saved_at": "2025-04-27T10:00:00Z"
+    }
+  }
+}
+```
+
+**关键差异**：
+1. **根级 session vs 按系统 session**：CLI 的 `session_id` 在根级，表示全局登录态；MCP 的 `session_id` 嵌套在 `sessions[system]` 下
+2. **时间戳格式**：CLI 使用 Unix 时间戳 `saved_at`，MCP 使用 ISO 8601 字符串
+3. **JWT 过期方式**：CLI 存 `expires_at`（ISO 时间），MCP 不存过期时间，依赖 `is_jwt_valid_locally()` 实时解析 JWT payload
+4. **额外字段**：CLI 存 `email` 和 `session_expires_at`，MCP 完全不存这些信息
+
+### 2.3 代码路径分叉分析
+
+**写入路径分叉**：
+
+- **CLI**: `opscli auth login` -> `auth/cli.py login()` -> `DeviceFlow(store=CredentialStore())` -> `poll_once` 自动调用 `store.save_session()` -> `CredentialStore._save()` -> Keychain或加密文件
+- **MCP**: `auth_login_poll` -> `mcp/tools/auth.py auth_login_poll()` -> `DeviceFlow(store=None)` -> `poll_once` 不保存 -> 手动调用 `SessionStore.save_session` -> 明文写入 `mcp_sessions.json`
+
+**读取路径分叉**：
+
+- **CLI**: `opscli auth token get -s ops` -> `AuthClient.get_token` -> `TokenManager.get_token` -> `CredentialStore.load` -> 读取`session_id` -> 向后端换取JWT
+- **MCP**: `auth_get_token system=ops` -> `_get_session_id` -> `SessionStore.get_session` -> 读取`mcp_sessions.json` -> 返回`session_id` -> `AuthClient.get_token_by_session`
+
+---
+
+## 三、不能共用的五大根因
+
+### 根因一：存储层物理隔离
+
+CLI 的 `CredentialStore` 和 MCP 的 `SessionStore` 是两个完全独立的类/模块，没有任何继承或组合关系。
+
+- `CredentialStore.save_session()` 方法签名是 `(session_id, email, expires_at, device_code)`
+- `SessionStore.save_session()` 方法签名是 `(system, session_id)`
+
+两者在 API 层面就不兼容。
+
+### 根因二：DeviceFlow 的 store 参数耦合
+
+`DeviceFlow.__init__(self, ops_url, store=None)` 的设计直接将存储逻辑耦合到 Device Flow 内部。
+
+- CLI 传入 `CredentialStore` 实例，授权成功即自动落库
+- MCP 传入 `None`，走"无状态"路线，由调用方自行决定如何保存
+
+这个设计差异导致两种模式的**写入路径完全不同**。
+
+### 根因三：Session 语义模型冲突
+
+CLI 的架构基于**全局登录态**：用户登录一次，获得一个 `session_id`，通过该 `session_id` 可以向任意已注册系统换取 JWT。
+
+MCP 的 `SessionStore` 设计为**按系统存储**：`sessions["ops"].session_id` 和 `sessions["polaris"].session_id` 被物理分离，虽然当前实现中两者值相同，但数据模型允许它们不同。
+
+### 根因四：MCP 多用户隔离未与 SessionStore 打通
+
+`MCPUserStore` 为每个用户分配独立的 `credential_dir`（`users/<user_id>/`），但 `SessionStore` 硬编码使用全局 `CONFIG_DIR / "mcp_sessions.json"`，完全没有感知多用户隔离。
+
+即使未来启用多用户模式，不同用户的 session 也会互相覆盖。而 CLI 的 `CredentialStore` 支持 `base_dir` 参数，天然可以配合多用户隔离。
+
+### 根因五：安全策略与性能权衡的不同选择
+
+CLI 模式下用户每次执行命令间隔较长（秒级/分钟级），加密开销可以忽略；
+MCP 模式下 AI Agent 可能在一次对话中调用数十次 Tool，明文 JSON 的读取性能至关重要。
+
+这种**性能与安全权衡的差异**，使得简单地将 MCP 切换到加密存储会产生可感知的性能退化。
+
+---
+
+## 四、优化方案设计
+
+### 方案 A：MCP 全面复用 CredentialStore（统一加密存储）
+
+**核心思路**：让 MCP 的 auth 工具不再使用 `SessionStore`，而是直接读写 `CredentialStore`，实现与 CLI 完全统一的存储层。
+
+**具体改动点**：
+
+1. **修改 `mcp/tools/auth.py`**：
+   - `auth_login_poll`：使用 `CredentialStore().save_session()` 替代 `SessionStore.save_session()`
+   - `auth_get_token` / `auth_token_refresh`：使用 `CredentialStore().save_token()` 替代 `SessionStore.save_jwt()`
+   - `auth_logout`：调用 `CredentialStore().clear()`
+
+2. **修改 `mcp/tools/helpers.py`**：
+   - `_get_session_id()`：从 `CredentialStore().load()` 读取根级 `session_id`
+   - `_get_jwt()`：从 `CredentialStore().load()["tokens"][system]["jwt"]` 读取
+
+3. **废弃 `mcp/session_store.py`**：保留文件但标记为 deprecated
+
+4. **统一 session 语义**：MCP 采用"全局 session"模型
+
+**优点**：
+- Session 完全互通：CLI 登录后 MCP 可用，MCP 登录后 CLI 可用
+- 安全统一：所有凭证享受 AES-256-GCM / Keychain 保护
+- 减少维护成本：消除两套存储的重复代码
+- 自动获得 CLI 的账号切换保护
+
+**缺点**：
+- MCP 高频 Tool 调用产生加密开销
+- 较大规模重构，涉及 13 个 MCP auth tool
+- 需要统一 session 语义
+
+---
+
+### 方案 B：双向适配器模式（兼容层）
+
+**核心思路**：保持两套存储各自独立，但在读写时通过**适配器**实现双向同步和 fallback。
+
+**具体改动点**：
+
+1. **新增 `opscli/auth/unified_store.py`**：
+   - `UnifiedCredentialProvider` 类
+   - 写操作时同时写入 `CredentialStore` 和 `SessionStore`
+   - 读操作时优先 `CredentialStore`，找不到则 fallback 到 `SessionStore`
+
+2. **修改 MCP auth 工具**：使用 `UnifiedCredentialProvider`
+
+3. **保持 CLI 不变**
+
+**优点**：
+- 零 Breaking Change
+- 平滑迁移：CLI 和 MCP 登录后双方都能读取
+- 保留 MCP 性能
+
+**缺点**：
+- 数据冗余：同一 session 存两份
+- 一致性问题：写入失败可能不同步
+- 维护成本高
+- 技术债
+
+---
+
+### 方案 C：统一存储抽象层 + 插件化后端（长期演进）
+
+**核心思路**：定义 `ICredentialStore` 接口，CLI 和 MCP 都面向接口编程。
+
+**接口设计**：
+
+```python
+from abc import ABC, abstractmethod
+
+class ICredentialStore(ABC):
+    @abstractmethod
+    def save_session(self, session_id: str, email: str, expires_at: str) -> None: ...
+    @abstractmethod
+    def get_session(self, alias: str | None = None) -> str | None: ...
+    @abstractmethod
+    def save_token(self, alias: str, jwt: str, expires_in: int) -> None: ...
+    @abstractmethod
+    def get_token(self, alias: str) -> str | None: ...
+    @abstractmethod
+    def clear(self) -> None: ...
+```
+
+**实现类**：
+- `EncryptedCredentialStore`：当前 CLI 的 CredentialStore
+- `PlainJsonCredentialStore`：当前 MCP 的 SessionStore 包装类
+- `ChainedCredentialStore`：组合多个后端
+
+**优点**：
+- 架构最优雅，符合开闭原则
+- 可扩展性强
+- 测试友好
+
+**缺点**：
+- 改动量最大
+- 引入抽象层，增加复杂度
+- 需要时间
+
+---
+
+## 五、方案对比矩阵
+
+| 评估维度 | 方案 A：复用 CredentialStore | 方案 B：双向适配器 | 方案 C：统一抽象层 |
+|----------|---------------------------|------------------|-----------------|
+| 实现复杂度 | 中 | 低 | 高 |
+| Session 互通性 | 完全互通 | 完全互通 | 完全互通 |
+| 安全一致性 | 完全统一 | 两套策略并存 | 统一接口，后端可选 |
+| MCP 性能影响 | 加密开销增加 | 无影响 | 无影响 |
+| Breaking Change | 废弃 SessionStore | 零 Breaking | 可能有 |
+| 数据冗余 | 无冗余 | 两份存储 | 无冗余 |
+| 维护成本（短期） | 低 | 中 | 高 |
+| 维护成本（长期） | 低 | 高（技术债） | 低 |
+| 用户凭证迁移 | 需迁移 | 无需迁移 | 需迁移 |
+| 多用户隔离支持 | 天然支持 | 需额外适配 | 通过注入不同 store |
+| 推荐场景 | 平衡安全与简洁 | 紧急兼容需求 | 长期技术演进 |
+
+---
+
+## 六、推荐方案与实施路径
+
+### 6.1 推荐方案：方案 A + 内存缓存
+
+**最终推荐采用 "方案 A（MCP 复用 CredentialStore）+ 内存缓存" 的混合策略**。
+
+**核心设计**：
+1. **统一落库**：MCP 的写操作统一写入 `CredentialStore`
+2. **内存缓存**：MCP Server 启动时加载凭证到内存，后续 Tool 调用读内存
+3. **缓存失效**：凭证变更时更新内存缓存
+4. **Session 语义统一**：MCP 采用"全局 session"模型
+
+### 6.2 具体实施步骤
+
+**Phase 1：数据迁移与兼容（1-2 天）**
+
+1. 新增迁移脚本，将 `mcp_sessions.json` 数据迁移到 `CredentialStore`
+2. 修改 `mcp/tools/auth.py`，所有写操作改用 `CredentialStore`
+3. 修改 `mcp/tools/helpers.py`，所有读操作改用 `CredentialStore`
+
+**Phase 2：MCP 内存缓存优化（2-3 天）**
+
+1. 新增 `McpCredentialCache` 类
+2. 修改 MCP auth tools 使用缓存
+
+**Phase 3：清理与废弃（1 天）**
+
+1. 标记 `mcp/session_store.py` 为 deprecated
+2. 删除 `mcp_sessions.json`
+3. 更新文档和测试
+
+### 6.3 关键代码变更示例
+
+**变更前**（`mcp/tools/auth.py`）：
+```python
+flow = DeviceFlow(ops_url=OPS_URL, store=None)
+result = flow.poll_once(device_code, timeout=timeout)
+if result.get("status") == "authorized":
+    session_id = result.get("session_id")
+    if session_id:
+        from opscli.mcp.session_store import save_session
+        save_session("ops", session_id)  # 写入明文 JSON
+```
+
+**变更后**：
+```python
+from opscli.auth.storage.credential_store import CredentialStore
+
+flow = DeviceFlow(ops_url=OPS_URL, store=None)
+result = flow.poll_once(device_code, timeout=timeout)
+if result.get("status") == "authorized":
+    session_id = result.get("session_id")
+    email = result.get("email", "")
+    expires_at = result.get("expires_at", "")
+    if session_id:
+        store = CredentialStore()
+        store.save_session(session_id, email, expires_at)  # 写入统一加密存储
+```
+
+---
+
+## 七、共用 vs 不共用优缺点总结
+
+### 7.1 不共用（现状）的优缺点
+
+| 维度 | 评价 |
+|------|------|
+| 用户体验 | 差。任一模式登录后，另一模式仍需重新走 Device Flow |
+| 开发维护 | 差。同一功能有两个独立实现，修改需同步两处 |
+| 安全性 | 不一致。CLI 强加密，MCP 明文 |
+| 性能 | MCP 明文读取快，CLI 加密安全但慢 |
+| 架构清晰度 | 差。DeviceFlow 的 store 参数导致底层分叉 |
+| 可扩展性 | 差。新增特性需在两个模块分别实现 |
+
+### 7.2 共用（方案 A）的优缺点
+
+| 维度 | 评价 |
+|------|------|
+| 用户体验 | 优秀。任一模式登录，另一模式立即可用 |
+| 开发维护 | 优秀。单一存储实现，修改一处全局生效 |
+| 安全性 | 统一。所有凭证享受 AES-256-GCM / Keychain 保护 |
+| 性能 | 需优化。引入内存缓存后，高频读取性能与明文持平 |
+| 架构清晰度 | 优秀。AuthClient 和 MCP tools 面向同一存储 |
+| 可扩展性 | 优秀。新增特性只需改 CredentialStore |
+
+### 7.3 量化影响评估
+
+| 指标 | 现状（不共用） | 共用（方案 A） | 变化 |
+|------|--------------|---------------|------|
+| 用户登录次数 | 2 次 | 1 次 | -50% |
+| 存储相关代码行数 | ~400 行 | ~165 行 | -59% |
+| 存储文件数 | 2 个 | 1 个 | -50% |
+| MCP 单次读凭证耗时 | ~0.1ms | ~0.1ms（内存缓存） | 持平 |
+| 安全合规性 | 部分明文 | 全部加密 | 提升 |
+
+---
+
+## 八、风险与回滚策略
+
+### 8.1 主要风险
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| 用户凭证丢失 | 迁移脚本 bug | 迁移前备份；保留 mcp_sessions.json 作为 fallback |
+| MCP 性能退化 | 无缓存时 AES 解密延迟 | Phase 2 必须同步实施内存缓存；压测验证 QPS |
+| Session 语义冲突 | 业务依赖按系统存 session | 审计所有 SessionStore 调用点 |
+| Breaking Change | 第三方依赖 mcp_sessions.json | 保留旧文件兼容 1 个版本 |
+
+### 8.2 回滚策略
+
+1. **实施前**：完整备份 `~/.config/opscli/` 目录
+2. **灰度验证**：先在开发/测试环境验证
+3. **快速回滚**：保留 `mcp_sessions.json` 至少一个版本周期
+4. **监控指标**：上线后监控 MCP Tool 平均响应时间，若增长 > 20% 触发回滚
+
+---
+
+## 九、结论
+
+opscli CLI 与 MCP 模式的 Session 不能共用，是**存储层物理隔离、DeviceFlow 耦合设计、Session 语义冲突、多用户隔离未打通、安全性能权衡差异**五重因素叠加的结果。
+
+**推荐立即执行方案 A（MCP 复用 CredentialStore + 内存缓存）**，理由如下：
+1. 用户体验提升 50%：消除重复授权
+2. 维护成本降低 59%：消除 SessionStore 的 237 行重复代码
+3. 安全水位统一：MCP 凭证从明文升级为 AES-256-GCM / Keychain 保护
+4. 性能影响可控：通过内存缓存将高频读操作延迟维持在 ~0.1ms 级别
+5. 实施周期短：预计 3-5 个工作日可完成
+
+长期演进方向上，可在方案 A 的基础上逐步向**方案 C（统一存储抽象层）**过渡。
+
+---
+
+*报告结束*