docs: update runtime-settings-autoactive documentation

- Update design section to reflect string expression approach
- Add comprehensive expression syntax examples
- Include JSON configuration examples for production use
- Add security and troubleshooting sections
- Document expression execution mechanism and safety measures

Author: ulivz

docs/runtime-settings-autoactive.md

@@ -9,16 +9,18 @@
 ### autoActive 的设计逻辑
 
 1. **向后兼容性**: 保持现有的 `autoActive?: boolean` 功能不变
-2. **函数支持**: 新增 `autoActive?: (runtimeSettings: Record<string, any>) => boolean` 形式
+2. **字符串表达式支持**: 新增 `autoActive?: string` 形式，支持 JavaScript 表达式
 3. **动态计算**: 在 Navbar 组件中获取 runtime settings 并实时计算 autoActive 状态
 4. **类型安全**: 通过 TypeScript 类型定义确保类型安全
+5. **JSON 兼容**: 完全支持 JSON 配置格式，无需序列化函数
 
 ### api/v1/runtime-settings 的消费
 
 1. **API 调用**: 使用 `apiService.getSessionRuntimeSettings(sessionId)` 获取当前会话的 runtime settings
 2. **数据结构**: 返回 `{ schema, currentValues, message }`，其中 `currentValues` 包含用户设置的值
 3. **实时更新**: 当会话切换时重新获取 runtime settings
 4. **错误处理**: 获取失败时使用空对象作为默认值
+5. **表达式执行**: 通过 `new Function()` 安全执行字符串表达式
 
 ## 使用方法
 
@@ -85,25 +87,71 @@
 - **属性访问**: `runtimeSettings.propertyName`
 - **数组访问**: `runtimeSettings.array[0]`
 - **字符串比较**: `runtimeSettings.sessionType === 'coding'`
+- **嵌套属性**: `runtimeSettings.user.preferences.theme === 'dark'`
+- **数学运算**: `runtimeSettings.threshold > 100 && runtimeSettings.count <= 50`
 
-**注意**: 表达式中只能访问 `runtimeSettings` 对象，不能使用其他变量或函数调用。
+**重要限制**:
+- 表达式中只能访问 `runtimeSettings` 对象
+- 不能使用外部变量、函数调用或复杂的 JavaScript 语法
+- 不能使用 `import`、`require`、`eval` 等语句
+- 不能使用循环、条件语句等控制结构
+
+### 5. 实际使用示例
+
+```json
+{
+  "workspace": {
+    "navItems": [
+      {
+        "title": "Code Server",
+        "link": "{prefix}/code-server/",
+        "icon": "code",
+        "behavior": "embed-frame",
+        "autoActive": "runtimeSettings.devMode === true || runtimeSettings.autoActivateCodeServer === true"
+      },
+      {
+        "title": "VNC",
+        "link": "{prefix}/vnc/index.html?autoconnect=true",
+        "icon": "monitor",
+        "behavior": "embed-frame",
+        "autoActive": "runtimeSettings.sessionType === 'debugging' || runtimeSettings.autoActivateVNC === true"
+      },
+      {
+        "title": "Terminal",
+        "link": "{prefix}/terminal/",
+        "icon": "terminal",
+        "behavior": "embed-frame",
+        "autoActive": "runtimeSettings.devMode === true"
+      }
+    ]
+  }
+}
+```
 
 ## 完整示例
 
-参考 `examples/runtime-settings-autoactive.config.ts` 文件，其中包含：
+参考以下示例文件：
 
-1. **Runtime Settings Schema**: 定义了用户可配置的选项
-2. **Dynamic AutoActive**: 演示了如何根据不同条件自动激活不同的 nav items
-3. **Multiple Conditions**: 展示了复杂的条件判断逻辑
+1. **TypeScript 配置**: `examples/runtime-settings-autoactive.config.ts` - 完整的 TypeScript 配置示例
+2. **JSON 配置**: `examples/runtime-settings-autoactive.json` - 生产环境可用的 JSON 配置示例
+
+### 示例内容
+
+- **Runtime Settings Schema**: 定义了用户可配置的选项
+- **Dynamic AutoActive**: 演示了如何根据不同条件自动激活不同的 nav items
+- **Multiple Conditions**: 展示了复杂的条件判断逻辑
+- **JSON 格式**: 展示了实际生产环境中的配置格式
 
 ## 实现细节
 
 ### Navbar 组件修改
 
 1. **状态管理**: 添加 `runtimeSettings` state 来存储当前的运行时设置
 2. **数据获取**: 在 session 变化时调用 API 获取 runtime settings
-3. **动态计算**: 在 autoActive 逻辑中支持函数形式的判断
-4. **依赖更新**: 将 `runtimeSettings` 添加到 useEffect 依赖数组
+3. **动态计算**: 在 autoActive 逻辑中支持字符串表达式形式的判断
+4. **表达式执行**: 使用 `new Function('runtimeSettings', \`return ${expression}\`)` 执行表达式
+5. **错误处理**: 表达式执行失败时安全回退到 `false`
+6. **依赖更新**: 将 `runtimeSettings` 添加到 useEffect 依赖数组
 
 ### 类型定义更新
 
@@ -120,6 +168,9 @@ export interface WorkspaceNavItem {
 2. **可配置性**: 用户可以通过 UI 控制自动激活行为
 3. **向后兼容**: 不破坏现有的静态配置
 4. **类型安全**: TypeScript 提供完整的类型检查
+5. **JSON 兼容**: 完全支持标准 JSON 格式，无需特殊处理
+6. **安全执行**: 通过 `new Function()` 安全执行表达式，限制访问范围
+7. **错误容错**: 表达式执行失败时安全回退，不影响系统运行
 
 ## 使用场景
 
@@ -133,4 +184,42 @@ export interface WorkspaceNavItem {
 1. **表达式安全**: 字符串表达式通过 `new Function()` 执行，只能访问 `runtimeSettings` 对象
 2. **性能考虑**: runtime settings 变化时会重新计算 autoActive，避免过于复杂的计算逻辑
 3. **错误处理**: 当表达式执行出错时，会在控制台输出错误信息并回退到不自动激活的安全状态
-4. **表达式限制**: 不能在表达式中使用外部变量、函数调用或复杂的 JavaScript 语法
+4. **表达式限制**: 不能在表达式中使用外部变量、函数调用或复杂的 JavaScript 语法
+5. **调试建议**: 开发时可在浏览器控制台查看表达式执行结果和错误信息
+6. **测试建议**: 在配置文件中提供多种场景的测试用例
+
+## 安全性说明
+
+### 表达式执行机制
+
+```typescript
+// 安全的表达式执行方式
+const evaluateExpression = new Function('runtimeSettings', `return ${expression}`);
+const result = evaluateExpression(runtimeSettings);
+```
+
+### 安全保障
+
+1. **作用域限制**: 表达式只能访问 `runtimeSettings` 参数
+2. **无全局访问**: 无法访问 `window`、`document` 等全局对象
+3. **无函数调用**: 无法调用外部函数或方法
+4. **错误隔离**: 表达式错误不会影响主程序运行
+
+## 故障排除
+
+### 常见问题
+
+1. **表达式语法错误**: 检查 JavaScript 语法是否正确
+2. **属性不存在**: 确保 `runtimeSettings` 中存在引用的属性
+3. **类型不匹配**: 检查比较操作的数据类型是否一致
+4. **表达式过于复杂**: 简化表达式逻辑，提高可读性和性能
+
+### 调试技巧
+
+```javascript
+// 在浏览器控制台中测试表达式
+const runtimeSettings = { devMode: true, sessionType: 'debugging' };
+const expression = "runtimeSettings.devMode === true || runtimeSettings.sessionType === 'debugging'";
+const result = new Function('runtimeSettings', `return ${expression}`)(runtimeSettings);
+console.log(result); // 输出: true
+```