# 附录 III：运行时安全与治理
> 安全不是功能，是约束——它必须在每个层次上都存在，而不是事后补丁。
---
## 附录 III-A：LSP 集成（实时代码诊断）
### 功能描述
Claude Code 通过 Language Server Protocol (LSP) 与编程语言的类型检查器、Linter 等工具实时通信，获取诊断信息（类型错误、警告等），并将其作为上下文自动注入对话。
**核心价值**：Agent 修改代码后，无需等待用户反馈，LSP 会立即推送编译错误，Agent 可主动修复。
### 架构
```
LSP Server（TypeScript/Python/...）
│ 标准 stdio JSON-RPC（LSP 协议）
▼
LSPClient（每个 server 对应一个）
│
├─ textDocument/publishDiagnostics（异步推送）
│ ↓
│ passiveFeedback.ts → registerPendingLSPDiagnostic()
│ ↓
│ LSPDiagnosticRegistry（LRU 缓存）
│ ↓
│ getAttachments() → 自动注入下一轮对话上下文
│
└─ textDocument/definition 等同步请求
↓
LSPTool（LLM 主动调用）
```
### 核心文件
| 文件 | 作用 |
|------|------|
| `src/services/lsp/LSPServerManager.ts` | 多语言 Server 管理器（按文件扩展名路由） |
| `src/services/lsp/LSPServerInstance.ts` | 单个 LSP Server 进程封装（stdio JSON-RPC） |
| `src/services/lsp/LSPClient.ts` | LSP 协议客户端（请求/通知发送） |
| `src/services/lsp/LSPDiagnosticRegistry.ts` | 诊断缓存（LRU），去重 + 限流 |
| `src/services/lsp/passiveFeedback.ts` | 将 LSP 推送的诊断转换为 Claude attachment 格式 |
| `src/services/lsp/config.ts` | LSP Server 配置加载（支持用户自定义） |
| `src/tools/LSPTool/` | LLM 主动调用的诊断查询工具 |
### 限流保护
```typescript
// LSPDiagnosticRegistry.ts
const MAX_DIAGNOSTICS_PER_FILE = 10 // 每个文件最多 10 条诊断
const MAX_TOTAL_DIAGNOSTICS = 30 // 全局最多 30 条诊断（防止大型项目淹没上下文）
const MAX_DELIVERED_FILES = 500 // 追踪去重的文件数上限（防内存泄漏）
```
### 严重级别映射
```typescript
// passiveFeedback.ts：LSP 标准 severity → Claude 内部格式
// LSP DiagnosticSeverity: 1=Error, 2=Warning, 3=Information, 4=Hint
function mapLSPSeverity(lspSeverity: number | undefined): 'Error' | 'Warning' | 'Info' | 'Hint'
```
### 文件生命周期同步
LSP Server 需要感知文件的打开/修改/保存/关闭事件，`LSPServerManager` 暴露对应接口：
```typescript
manager.openFile(filePath, content) // 发送 didOpen 通知
manager.changeFile(filePath, content) // 发送 didChange 通知
manager.saveFile(filePath) // 发送 didSave 通知（触发诊断刷新）
manager.closeFile(filePath) // 发送 didClose 通知
```
文件保存（`saveFile`）后，LSP Server 通常重新检查类型，并通过 `publishDiagnostics` 推送最新结果——这是 `passiveFeedback.ts` 的主要触发场景。
---
## 附录 III-B：OAuth 认证流程
### 功能描述
Claude Code 支持 OAuth 2.0 Authorization Code Flow + PKCE，允许用户通过 Claude.ai 账号登录（而非仅靠 API Key），享受 Pro/Max 订阅权益。
**核心文件**：`src/services/oauth/`（5 个文件）
### 认证流程
```
claude /login
│
├─ 1. 生成 PKCE code_verifier（随机 32 字节，base64url 编码）
│ code_challenge = SHA-256(code_verifier)
│
├─ 2. 启动本地 HTTP 服务器（AuthCodeListener）
│ 监听 localhost:<random-port>/oauth/callback
│
├─ 3. 构建 Authorization URL：
│ https://claude.ai/oauth/authorize?
│ client_id=...&
│ code_challenge=<SHA256>&
│ code_challenge_method=S256&
│ redirect_uri=http://localhost:<port>/oauth/callback&
│ state=<random>&
│ response_type=code
│
├─ 4a. 自动流程：openBrowser(authUrl) → 用户登录 → 浏览器回调 localhost
│ 4b. 手动流程（无浏览器环境）：展示 URL，等待用户粘贴 code
│
├─ 5. 收到 authorization code
│ POST /oauth/token（带 code + code_verifier）
│ → 获得 access_token + refresh_token
│
└─ 6. 存储 token（系统 Keychain 或加密文件）
```
### 核心文件
| 文件 | 作用 |
|------|------|
| `src/services/oauth/index.ts` | `OAuthService` 类：完整 OAuth 流程编排 |
| `src/services/oauth/client.ts` | HTTP 请求（授权 URL 构建、token 交换、刷新） |
| `src/services/oauth/crypto.ts` | PKCE 工具（`generateCodeVerifier`、`generateCodeChallenge`、`generateState`） |
| `src/services/oauth/auth-code-listener.ts` | `AuthCodeListener`：本地临时 HTTP 服务器，接收 OAuth 回调 |
| `src/services/oauth/getOauthProfile.ts` | 用 access_token 查询用户订阅类型（`RateLimitTier`、`SubscriptionType`） |
### 安全特性
- **PKCE（Proof Key for Code Exchange）**：防止 authorization code 截获攻击——即使攻击者拿到 code，没有 `code_verifier` 也无法换取 token
- **state 参数**：防 CSRF（Cross-Site Request Forgery）攻击
- **随机端口**：本地回调 HTTP 服务器使用随机端口，避免端口冲突或预测攻击
- **双模式支持**：`skipBrowserOpen` 选项支持 SDK 控制协议场景（IDE 插件接管浏览器打开）
---
## 附录 III-C：企业策略管理（Remote Managed Settings）
### 功能描述
企业 IT 管理员通过 Anthropic 管理控制台推送策略配置，覆盖用户的本地 Claude Code 设置。员工打开 Claude Code 时自动同步企业策略（无需用户主动操作），且**用户无法绕过**强制策略。
**适用场景**：
- 禁用特定工具（如禁止 BashTool 在生产环境运行）
- 限制可访问的目录（合规需求）
- 强制启用诊断日志
- 限制允许的 AI 模型范围
**核心文件**：`src/services/remoteManagedSettings/`（5 个文件）
### 策略加载流程
```
Claude Code 启动
│
├─ isRemoteManagedSettingsEligible() 检查资格
│ ├─ Console 用户（API Key）：全部符合资格
│ └─ OAuth 用户：仅 Enterprise / C4E / Team 订阅用户符合资格
│
├─ 从本地缓存（syncCache）读取上次同步的策略
│ └─ 立即应用缓存策略（避免阻塞启动）
│
├─ 后台 fetch 最新策略（10 秒超时，最多重试 5 次）
│ GET /api/remote-settings（带 checksum，增量拉取）
│
├─ checkManagedSettingsSecurity()：
│ ├─ 新策略含"危险设置"（如 allowedPaths）且与缓存不同？
│ │ ↓ 是
│ │ 展示阻塞确认对话框（ManagedSettingsSecurityDialog）
│ │ 用户拒绝 → 不应用新策略
│ └─ 否 → 静默应用
│
└─ 每小时轮询更新（POLLING_INTERVAL_MS = 60 * 60 * 1000）
```
### 核心文件
| 文件 | 作用 |
|------|------|
| `src/services/remoteManagedSettings/index.ts` | 主逻辑：fetch、缓存、轮询 |
| `src/services/remoteManagedSettings/syncCache.ts` | 本地缓存管理（checksum + 内容） |
| `src/services/remoteManagedSettings/syncCacheState.ts` | 缓存路径与 session 级缓存读写 |
| `src/services/remoteManagedSettings/securityCheck.tsx` | 危险设置检测 + 用户确认对话框 |
| `src/services/remoteManagedSettings/types.ts` | 策略协议类型（`RemoteManagedSettingsResponseSchema`） |
### 优先级（高→低）
```
CLI 参数（--dangerously-skip-permissions 等）
↓
Remote Managed Settings（企业策略） ← 覆盖用户设置
↓
用户本地 settings.json
↓
默认值
```
### 失效安全（Fail Open）
网络请求失败时，**继续使用缓存策略**（或无策略）正常运行，不阻塞用户使用——企业策略不作为硬性依赖。
---
## 附录 III-D：自动更新
### 功能描述
Claude Code 启动时自动检查 npm registry 最新版本，根据配置决定是自动安装还是仅提示。
**核心文件**：`src/cli/update.ts`、`src/utils/autoUpdater.ts`
### 更新流程
```
claude update（或启动时后台检查）
│
├─ getLatestVersion()：查询 npm registry（或配置的 channel）
│ channel 来自 settings.autoUpdatesChannel（默认 'latest'）
│
├─ 版本比较：gte(currentVersion, latestVersion)？
│ ├─ 已是最新 → 退出
│ └─ 有新版本 → 继续
│
├─ 检测安装方式（installationType）：
│ ├─ npm global → installGlobalPackage()
│ ├─ local install → installOrUpdateClaudePackage()
│ └─ native → installLatestNative()（系统包管理器）
│
└─ 更新完成后 regenerateCompletionCache()（刷新 shell 补全缓存）
```
### 多安装检测
```typescript
// update.ts：发现多个 Claude Code 安装时告警
if (diagnostic.multipleInstallations.length > 1) {
writeToStdout(chalk.yellow('Warning: Multiple installations found'))
// 提示用户清理，避免版本混用
}
```
### 配置项
| 配置 | 说明 |
|------|------|
| `settings.autoUpdatesChannel` | 更新渠道（`latest` / `beta` 等） |
| `settings.autoUpdate` | 是否自动安装（否则仅提示） |
---
## 附录 III 源码快速导航
```
运行时安全与治理
├── LSP 实时诊断
│ └── src/services/lsp/
│ ├── LSPServerManager.ts ← 多语言 Server 路由
│ ├── LSPServerInstance.ts ← 单个 Server 进程封装
│ ├── LSPDiagnosticRegistry.ts ← 诊断 LRU 缓存（去重+限流）
│ ├── passiveFeedback.ts ← 文件保存后自动推送诊断
│ └── config.ts ← 语言服务器配置
│
├── OAuth 2.0 + PKCE 认证
│ └── src/services/oauth/
│ ├── index.ts ← OAuthService：完整流程编排
│ ├── client.ts ← HTTP 请求（授权URL + token 交换）
│ ├── crypto.ts ← PKCE 工具函数
│ ├── auth-code-listener.ts ← 本地回调 HTTP 服务器
│ └── getOauthProfile.ts ← 查询用户订阅类型
│
├── 企业策略（Remote Managed Settings）
│ └── src/services/remoteManagedSettings/
│ ├── index.ts ← fetch + 缓存 + 轮询主逻辑
│ ├── syncCache.ts ← checksum 本地缓存
│ ├── securityCheck.tsx ← 危险设置变更确认对话框
│ └── types.ts ← RemoteManagedSettingsResponseSchema
│
└── 自动更新
├── src/cli/update.ts ← update 命令主逻辑
└── src/utils/autoUpdater.ts ← 版本检查 + 安装执行
```
---
→ [附录 IV：自动化与调度](appendix-IV-automation)