cc-viewer 1.6.330 → 1.6.331

package/server/_paths.js

@@ -1,41 +1,43 @@
-// 集中所有「相对于仓库根 / server 根 / node_modules」的物理路径常量，
-// 避免 __dirname 跨深度 join('..','..',...) 写错。新代码直接 import 这里；
-// 老代码渐进迁移。命名 `_paths.js`：下划线前缀 = server 启动期常量集，
-// 与业务模块 (lib/*.js) 目录排序上自然区隔。
+// Centralized physical path constants relative to repo root / server root / node_modules,
+// to avoid error-prone cross-depth join('..','..',...) chains. New code should import from here;
+// legacy code migrates gradually. Named `_paths.js`: underscore prefix = server startup
+// constants, visually separated from business modules (lib/*.js) in directory listings.
 //
-// ⚠️ 物理位置敏感：本文件路径 = 所有常量的锚点（HERE = dirname(本文件)）。
-// `git mv server/_paths.js <其它路径>` 会让 PACKAGE_ROOT / NODE_MODULES / DIST_DIR /
-// 等全部偏移，但不会有静态错误 —— 改动文件位置后必须人工核对所有 import 方的解析结果。
+// ⚠️ Position-sensitive: this file's own path is the anchor for every constant
+// (HERE = dirname(this file)). `git mv server/_paths.js <elsewhere>` will silently shift
+// PACKAGE_ROOT / NODE_MODULES / DIST_DIR / etc. — no static error, so every import site
+// must be manually verified after moving this file.
 //
-// NODE_MODULES 假设：cc-viewer 物理位于 `<node_modules>/cc-viewer/`（生产 npm install）。
-// `npm link` / git clone dev 场景下计算到错的位置；上层 (findcc.js) 用
-// `getGlobalNodeModulesDir()` 兜底，但本常量本身不感知这些边界。
+// NODE_MODULES assumption: cc-viewer physically lives at `<node_modules>/cc-viewer/`
+// (production npm install). Under `npm link` / git clone dev setups this resolves to the
+// wrong location; upstream consumers (findcc.js) use `getGlobalNodeModulesDir()` as a
+// fallback, but this constant itself is not aware of those edge cases.
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
-/** server/ 目录绝对路径 */
+/** Absolute path of server/ directory */
 export const SERVER_DIR    = HERE;
-/** cc-viewer 包根（npm install 时 = `<node_modules>/cc-viewer`） */
+/** cc-viewer package root (at npm install time = `<node_modules>/cc-viewer`) */
 export const PACKAGE_ROOT  = resolve(HERE, '..');
-/** cc-viewer 同级 node_modules/（npm install 假设；npm link 失效） */
+/** cc-viewer's sibling node_modules/ (npm install assumption; broken under npm link) */
 export const NODE_MODULES  = resolve(HERE, '..', '..');
-/** server/lib/ 子目录 */
+/** server/lib/ subdirectory */
 export const SERVER_LIB    = join(HERE, 'lib');
-/** Vite build 产物（dist/index.html + assets/*） */
+/** Vite build output (dist/index.html + assets/*) */
 export const DIST_DIR      = join(PACKAGE_ROOT, 'dist');
-/** dev 资源（public/voice-packs/* 等，会被 vite 拷到 dist/） */
+/** Dev resources (public/voice-packs/* etc., copied to dist/ by vite) */
 export const PUBLIC_DIR    = join(PACKAGE_ROOT, 'public');
-/** 多语言概念文档（GlobalSettings.md / Tool-*.md 等） */
+/** Multi-language concept docs (GlobalSettings.md / Tool-*.md etc.) */
 export const CONCEPTS_DIR  = join(PACKAGE_ROOT, 'concepts');
-/** Bundled plugin 目录（plugin-loader 启动时扫这里） */
+/** Bundled plugin directory (scanned by plugin-loader at startup) */
 export const PLUGINS_DIR   = join(PACKAGE_ROOT, 'plugins');
-/** 随包发布的 ultraplan 预设专家目录（ultraAgents/*.json，/api/ultra-agents 扫这里） */
+/** Bundled ultraplan preset expert directory (ultraAgents/*.json, served by /api/ultra-agents) */
 export const ULTRA_AGENTS_DIR = join(PACKAGE_ROOT, 'ultraAgents');
-/** 随包发布的 IM 内置默认技能源（server/imSkills/<lang>/<skill>/SKILL.md + scripts/*.mjs） */
+/** Bundled IM default skill source (server/imSkills/<lang>/<skill>/SKILL.md + scripts/*.mjs) */
 export const IM_SKILLS_DIR = join(SERVER_DIR, 'imSkills');
-/** 随包发布的 IM 人格预置模板（server/imPreset/<lang>.md，{platform}/{id} 运行时替换） */
+/** Bundled IM persona preset templates (server/imPreset/<lang>.md, {platform}/{id} substituted at runtime) */
 export const IM_PRESET_DIR = join(SERVER_DIR, 'imPreset');
-/** cc-viewer 自己的 package.json（updater/server.js 读 version） */
+/** cc-viewer's own package.json (updater/server.js reads version) */
 export const PACKAGE_JSON  = join(PACKAGE_ROOT, 'package.json');

package/server/interceptor.js

@@ -16,7 +16,7 @@ import { homedir } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, join, basename } from 'node:path';
 import { LOG_DIR } from '../findcc.js';
-import { assembleStreamMessage, createStreamAssembler, cleanupTempFiles, findRecentLog, claimUntaggedLog, logFilePrefix, isAnthropicApiPath, isMainAgentRequest, rotateLogFile, fingerprintMsg, replaceTopLevelModel } from './lib/interceptor-core.js';
+import { assembleStreamMessage, createStreamAssembler, cleanupTempFiles, findRecentLog, claimUntaggedLog, logFilePrefix, isAnthropicApiPath, isMainAgentRequest, rotateLogFile, fingerprintMsg, replaceTopLevelModel, injectOutputConfigEffort, resolveProfileModel } from './lib/interceptor-core.js';
 
 
 
@@ -77,7 +77,7 @@ export let _cachedHaikuModel = null;
 //     切换 active 只影响当前 ccv 进程的 workspace，不污染其他实例。
 // profile.json 存放在 LOG_DIR 下，受 --log-dir / CCV_LOG_DIR 影响
 const PROFILE_PATH = join(LOG_DIR, 'profile.json');
-let _activeProfile = null; // { id, name, baseURL?, apiKey?, models?, activeModel? }
+let _activeProfile = null; // { id, name, baseURL?, apiKey?, effort?, ANTHROPIC_MODEL?, ANTHROPIC_DEFAULT_OPUS_MODEL?, ANTHROPIC_DEFAULT_SONNET_MODEL?, ANTHROPIC_DEFAULT_HAIKU_MODEL?, activeModel?(legacy) }
 
 // 启动时捕获的原始配置（首次 API 请求时记录，不可变）
 let _defaultConfig = null; // { origin, authType, model }
@@ -838,32 +838,46 @@ export function setupInterceptor() {
             }
           }
         }
-        // 3. Model 替换 —— 避免对整条 wire body（-c 重启后全量 checkpoint 可达数十 MB）
-        //    二次 JSON.parse + 全量 re-stringify：用 L557 已解析的 body 读旧值，对原始
-        //    字符串做有界定向替换（唯一非歧义匹配才生效）；定位失败回退旧 parse 路径，
-        //    最坏退化为现状。注意不能复用 requestEntry.body 重建 wire —— delta 路径
-        //    （上方 needsCheckpoint=false 分支）已把它的 messages 改成增量切片。
-        if (_activeProfile.activeModel && _fetchOpts?.body) {
-          const _oldModel = (body && typeof body === 'object') ? body.model : undefined;
-          if (_oldModel === _activeProfile.activeModel) {
-            // 已是目标 model，跳过（旧路径会原样 re-stringify，对上游等价）
+        // 3. Model 替换 —— 按 body.model 家族名解析目标（opus/sonnet/haiku 各自字段，
+        //    fable/mythos/未识别 → ANTHROPIC_MODEL；旧数据回退 activeModel 整体替换）。
+        //    避免对整条 wire body（-c 重启后全量 checkpoint 可达数十 MB）二次 JSON.parse +
+        //    全量 re-stringify：用 requestEntry.body 读旧值（函数级作用域；行 606 的 body 是
+        //    if 块级变量，此处已越界——历史 BUG），对原始字符串做有界定向替换（唯一非歧义匹配
+        //    才生效）；定位失败回退旧 parse 路径。注意只读 .model：delta 路径只改 .messages，
+        //    不能整体复用 requestEntry.body 重建 wire。
+        const _rb = requestEntry.body;
+        const _oldModel = (_rb && typeof _rb === 'object' && typeof _rb.model === 'string') ? _rb.model : undefined;
+        const _targetModel = _oldModel ? resolveProfileModel(_oldModel, _activeProfile) : null;
+        if (_targetModel && _fetchOpts?.body) {
+          const _replaced = (typeof _fetchOpts.body === 'string')
+            ? replaceTopLevelModel(_fetchOpts.body, _oldModel, _targetModel)
+            : null;
+          if (_replaced !== null) {
+            _fetchOpts = { ..._fetchOpts, body: _replaced };
           } else {
-            const _replaced = (typeof _fetchOpts.body === 'string' && typeof _oldModel === 'string')
-              ? replaceTopLevelModel(_fetchOpts.body, _oldModel, _activeProfile.activeModel)
-              : null;
-            if (_replaced !== null) {
-              _fetchOpts = { ..._fetchOpts, body: _replaced };
-            } else {
-              try {
-                const _b = JSON.parse(_fetchOpts.body);
-                if (_b.model) {
-                  _b.model = _activeProfile.activeModel;
-                  _fetchOpts = { ..._fetchOpts, body: JSON.stringify(_b) };
-                }
-              } catch { }
-            }
+            try {
+              const _b = JSON.parse(_fetchOpts.body);
+              if (_b.model) {
+                _b.model = _targetModel;
+                _fetchOpts = { ..._fetchOpts, body: JSON.stringify(_b) };
+              }
+            } catch { }
           }
         }
+        // 4. Effort 注入 —— 强制 output_config.effort（对应 CLAUDE_CODE_EFFORT_LEVEL）。
+        //    在 model 替换之后执行，操作 _fetchOpts.body 的最新形态；仅当 profile 显式设置了
+        //    合法 effort 才注入。排除 count_tokens / heartbeat：这些端点可能拒绝未知字段（400），
+        //    且 output_config 对它们无意义。hasOutputConfig 优先用 requestEntry.body（函数级作用域，
+        //    行 606 的 body 在此已越界）判定；解析失败退化为截断字符串时，回退到对 wire 串扫描
+        //    "output_config"（避免误走前插路径产生重复键 → JSON "后者胜" 把注入的 effort 丢掉）。
+        if (_activeProfile.effort && typeof _fetchOpts?.body === 'string' &&
+            !requestEntry.isCountTokens && !requestEntry.isHeartbeat) {
+          const _hasOutputConfig = (_rb && typeof _rb === 'object')
+            ? (!!_rb.output_config && typeof _rb.output_config === 'object')
+            : _fetchOpts.body.includes('"output_config"');
+          const _injected = injectOutputConfigEffort(_fetchOpts.body, _activeProfile.effort, _hasOutputConfig);
+          if (_injected !== null) _fetchOpts = { ..._fetchOpts, body: _injected };
+        }
         // 记录 proxy 信息到日志条目
         requestEntry.proxyProfile = _activeProfile.name;
         requestEntry.proxyUrl = _fetchUrl;

package/server/lib/interceptor-core.js

@@ -504,3 +504,110 @@ export function replaceTopLevelModel(jsonStr, oldModel, newModel) {
   const replaced = needle.slice(0, needle.length - oldVal.length) + JSON.stringify(newModel);
   return jsonStr.slice(0, idx) + replaced + jsonStr.slice(idx + needle.length);
 }
+
+// proxy profile hot-switch 模型解析：按 request body 里 model 的家族名映射到 profile 的对应字段。
+// 家族用**大小写不敏感子串**匹配（/opus/i 等），只认这几个已知家族单词——
+// 因此 claude-opus-4-8、未来的 claude-opus-5 等任何版本都命中同一家族，版本升级无需重配。
+// 字段直接沿用 Claude Code 的环境变量名以保持一致：
+//   ANTHROPIC_MODEL              —— 主模型；body.model 含 "fable" / "mythos" 时映射到它
+//   ANTHROPIC_DEFAULT_OPUS_MODEL   —— body.model 含 "opus"
+//   ANTHROPIC_DEFAULT_SONNET_MODEL —— 含 "sonnet"
+//   ANTHROPIC_DEFAULT_HAIKU_MODEL  —— 含 "haiku"
+// 家族字段留空 = 该家族不改写（透传原始 model）。
+// 未识别家族（既不是 opus/sonnet/haiku 也不是 fable/mythos）不做兜底替换，原样透传。
+// 兼容旧数据：profile 未设任何新字段但有 activeModel（老结构）时，回退为旧的整体替换语义。
+// 返回目标模型字符串；无需改写（无目标 / 目标同旧值 / 入参非法 / 未识别家族）时返回 null。
+export function resolveProfileModel(oldModel, profile) {
+  if (typeof oldModel !== 'string' || !oldModel || !profile || typeof profile !== 'object') return null;
+  const opus = typeof profile.ANTHROPIC_DEFAULT_OPUS_MODEL === 'string' ? profile.ANTHROPIC_DEFAULT_OPUS_MODEL.trim() : '';
+  const sonnet = typeof profile.ANTHROPIC_DEFAULT_SONNET_MODEL === 'string' ? profile.ANTHROPIC_DEFAULT_SONNET_MODEL.trim() : '';
+  const haiku = typeof profile.ANTHROPIC_DEFAULT_HAIKU_MODEL === 'string' ? profile.ANTHROPIC_DEFAULT_HAIKU_MODEL.trim() : '';
+  const primary = typeof profile.ANTHROPIC_MODEL === 'string' ? profile.ANTHROPIC_MODEL.trim() : '';
+  const hasNew = !!(primary || opus || sonnet || haiku);
+
+  let target = '';
+  if (hasNew) {
+    if (/opus/i.test(oldModel)) target = opus;
+    else if (/sonnet/i.test(oldModel)) target = sonnet;
+    else if (/haiku/i.test(oldModel)) target = haiku;
+    else if (/fable/i.test(oldModel) || /mythos/i.test(oldModel)) target = primary; // 显式家族 → 主模型
+    // 未识别家族：target 保持 ''，下方返回 null（不替换、原样透传）
+  } else if (typeof profile.activeModel === 'string') {
+    target = profile.activeModel.trim(); // 旧数据整体替换语义
+  }
+
+  if (!target || target === oldModel) return null;
+  return target;
+}
+
+// 旧配置迁移：老 profile 用 { models:[], activeModel } 做整体替换（不分家族，所有请求都换成
+// activeModel）。新方案改用 ANTHROPIC_MODEL + 三个家族字段。为**忠实保留**旧的整体替换语义，
+// 把 activeModel 填入全部四个模型字段（仅填空缺项，不覆盖用户已设值），这样 opus/sonnet/haiku/
+// fable 各家族都仍命中同一模型；用户之后可在 UI 里按需拆分。丢弃遗留的 models / activeModel。
+// 幂等：无遗留字段时原样返回、changed=false。纯函数，不落盘；调用方决定是否持久化。
+export function migrateProxyProfile(p) {
+  if (!p || typeof p !== 'object') return { profile: p, changed: false };
+  const hasLegacy = ('activeModel' in p) || ('models' in p);
+  if (!hasLegacy) return { profile: p, changed: false };
+  const { models: _drop1, activeModel, ...rest } = p;
+  const out = { ...rest };
+  const am = typeof activeModel === 'string' ? activeModel.trim() : '';
+  if (am) {
+    // 保留整体替换：四个字段都回填 activeModel（已有值不动）
+    for (const k of ['ANTHROPIC_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL']) {
+      if (!out[k]) out[k] = am;
+    }
+  }
+  return { profile: out, changed: true };
+}
+
+// 迁移整份 profiles 列表；返回 { profiles, changed }（任一 profile 变更即 changed=true）。
+export function migrateProxyProfileList(profiles) {
+  if (!Array.isArray(profiles)) return { profiles, changed: false };
+  let changed = false;
+  const migrated = profiles.map(p => {
+    const r = migrateProxyProfile(p);
+    if (r.changed) changed = true;
+    return r.profile;
+  });
+  return { profiles: migrated, changed };
+}
+
+// proxy profile hot-switch 支持强制 output_config.effort（对应 CLAUDE_CODE_EFFORT_LEVEL）。
+// 与 replaceTopLevelModel 同源思路：常见路径（body 里没有 output_config）走定向前插，
+// 避免对多 MB wire body 做 JSON.parse + 全量 re-stringify（-c 重启后 checkpoint 可达数十 MB）。
+//   - 前插：在顶层对象开括号 `{` 之后插入 `"output_config":{"effort":"<v>"}`（后跟逗号，除非对象为空）。
+//     顶层永远以 `{` 开头，插入后仍是合法 JSON；且 JSON 重复键"后者胜"，但此路径仅在
+//     调用方确认 body 无 output_config 时启用，不会产生重复键。
+//   - 合并：body 已有 output_config（罕见，如 CLI 传了 --effort）时回退整体 parse/stringify，
+//     把 effort 并入既有对象。此路径 O(n) 但极少触发，可接受。
+// effort 值域受限（low/medium/high/xhigh/max），非法值 → null（调用方跳过注入）。
+const _VALID_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+export function injectOutputConfigEffort(jsonStr, effort, hasOutputConfig) {
+  if (typeof jsonStr !== 'string' || !jsonStr) return null;
+  if (typeof effort !== 'string' || !_VALID_EFFORTS.has(effort)) return null;
+  if (hasOutputConfig) {
+    // 已有 output_config：整体 parse/stringify 合并，保留既有子字段
+    try {
+      const obj = JSON.parse(jsonStr);
+      if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null;
+      if (!obj.output_config || typeof obj.output_config !== 'object' || Array.isArray(obj.output_config)) {
+        obj.output_config = {};
+      }
+      obj.output_config.effort = effort;
+      return JSON.stringify(obj);
+    } catch { return null; }
+  }
+  // 无 output_config：定向前插
+  const i = jsonStr.indexOf('{');
+  if (i === -1) return null;
+  // 顶层必须是对象：`{` 之前只允许空白，排除顶层数组（如 `[{...}]`）等把首个 `{` 误当顶层的情形。
+  // 与合并路径的 Array.isArray 守卫对称。真实 /v1/messages body 恒为顶层对象。
+  if (/\S/.test(jsonStr.slice(0, i))) return null;
+  // 探测开括号后的首个非空白字符：若是 `}`（空对象）则不追加逗号，避免尾逗号非法 JSON
+  const after = jsonStr.slice(i + 1);
+  const m = after.match(/^\s*(\S)/);
+  const needsComma = !!(m && m[1] !== '}');
+  const insert = `"output_config":{"effort":${JSON.stringify(effort)}}` + (needsComma ? ',' : '');
+  return jsonStr.slice(0, i + 1) + insert + jsonStr.slice(i + 1);
+}

package/server/routes/preferences.js

@@ -4,6 +4,7 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { LOG_DIR, setLogDir, getClaudeConfigDir } from '../../findcc.js';
 import { PROFILE_PATH, _defaultConfig, getActiveProfileId, setActiveProfileForWorkspace, _loadProxyProfile } from '../interceptor.js';
+import { migrateProxyProfileList } from '../lib/interceptor-core.js';
 import { setLang } from '../i18n.js';
 import { reconcileVoicePackPrefs as vpReconcile } from '../lib/voice-pack-manager.js';
 import { readClaudeProjectModel } from '../lib/context-watcher.js';
@@ -219,7 +220,19 @@ function claudeSettingsPost(req, res, parsedUrl, isLocal, deps) {
 
 function proxyProfilesGet(req, res, parsedUrl, isLocal, deps) {
   try {
-    const data = existsSync(PROFILE_PATH) ? JSON.parse(readFileSync(PROFILE_PATH, 'utf-8')) : deps.defaultProxyProfiles;
+    let data = existsSync(PROFILE_PATH) ? JSON.parse(readFileSync(PROFILE_PATH, 'utf-8')) : deps.defaultProxyProfiles;
+    // 旧配置一次性迁移（models/activeModel → ANTHROPIC_MODEL）；有变更则回写磁盘并刷新 active profile。
+    if (Array.isArray(data.profiles)) {
+      const { profiles: migrated, changed } = migrateProxyProfileList(data.profiles);
+      if (changed) {
+        data = { ...data, profiles: migrated };
+        try {
+          mkdirSync(dirname(PROFILE_PATH), { recursive: true });
+          writeFileSync(PROFILE_PATH, JSON.stringify(data, null, 2), { mode: 0o600 });
+          _loadProxyProfile();
+        } catch { /* 迁移落盘失败不阻塞 GET；下次仍会尝试 */ }
+      }
+    }
     // 用 interceptor.getActiveProfileId() 返回 effective active（workspace > profile.json.active > 'max'）
     const effectiveActive = getActiveProfileId();
     // 本机(127.0.0.1)= admin：下发明文 profile.apiKey 供本人在编辑表单(👁 折叠)里查阅/复制；已授权

package/server.js

@@ -2,4 +2,5 @@
 // working without forcing every external consumer to know the physical layout.
 // Removing this file requires updating package.json + any user scripts that
 // run `node server.js`. Implementation lives at server/server.js.
+// See also: interceptor.js (same pattern for the interceptor module).
 export * from './server/server.js';

package/ultraAgents/README.md

@@ -1,62 +1,71 @@
-# ultraAgents — 预设专家 (Preset ultraplan experts)
+# ultraAgents — Preset Experts
 
-本目录随 cc-viewer 包发布。其中每个 `*.json` 文件定义一个「预设专家」，会出现在
-**UltraPlan → 自定义专家编辑器 → 「载入模版」** 弹窗中，供用户选中后将名称与内容
-一键载入编辑面板（再按需改写并另存为自己的自定义专家）。
+This directory ships with the cc-viewer package. Each `*.json` file defines a
+"preset expert" that appears in the **UltraPlan → Custom Expert Editor →
+"Load Template"** modal. Users can select a preset to load its name and content
+into the editor with one click, then customize and save as their own expert.
 
-> 加载入口：服务端 `GET /api/ultra-agents`（只读本目录、无参数），实现见
-> `server/lib/ultra-agents-api.js`。本目录中的非 `*.json` 文件（如本 README）会被忽略。
+> Loading entry point: server-side `GET /api/ultra-agents` (read-only, no parameters),
+> implemented in `server/lib/ultra-agents-api.js`. Non-`*.json` files in this directory
+> (like this README) are ignored.
 
-## JSON 格式
+## JSON Format
 
 ```jsonc
 {
-  "id": "code-expert",          // 必填。唯一标识,仅 [A-Za-z0-9._-]、长度 ≤200、不以 . 开头。
-                                //       仅作去重键(同 id 取文件名排序靠前者),不参与拼路径。
-  "version": 1,                 // 可选。前向兼容标记,当前加载器忽略(不读不校验)。
-  "title":       { "zh": "代码专家", "en": "Code Expert" },  // 必填。专家名称,内联本地化,见下。
-  "description": { "zh": "资深工程师…", "en": "Senior engineer…" }, // 可选。一句话描述,内联本地化。
-  "content":     "<system-reminder>\n…\n</system-reminder>"  // 必填。单语言正文,见下「content」。
+  "id": "code-expert",          // Required. Unique identifier: [A-Za-z0-9._-] only, ≤200 chars,
+                                // must not start with '.'. Used as a dedup key (first by filename
+                                // sort wins when ids collide); not involved in path construction.
+  "version": 1,                 // Optional. Forward-compat marker, ignored by current loader.
+  "title":       { "zh": "代码专家", "en": "Code Expert" },  // Required. Expert name, inline localized (see below).
+  "description": { "zh": "资深工程师…", "en": "Senior engineer…" }, // Optional. One-liner description, inline localized.
+  "content":     "<system-reminder>\n…\n</system-reminder>"  // Required. Single-language body (see "content" below).
 }
 ```
 
-### title / description：在 JSON 协议层内联本地化
+### title / description: inline localization in the JSON protocol layer
 
-`title` 与 `description` 两个字段都支持两种写法，**本地化在 JSON 协议层内联完成**（不依赖外部 i18n）：
+Both `title` and `description` support two forms, with **localization done inline in the JSON
+protocol layer** (no external i18n dependency):
 
-- **纯字符串**：所有语言都用同一份文本。
-- **本地化对象** `{ "zh": "…", "en": "…", "zh-TW": "…" }`：前端按当前界面语言解析，
-  回退顺序为 **精确语言 → 去区域的主语言（`zh-TW`→`zh`、`pt-BR`→`pt`）→ `en` → `zh`
-  → 首个非空值**（解析逻辑见 `src/utils/resolveLocalized.js`）。
+- **Plain string**: same text for all languages.
+- **Localization object** `{ "zh": "…", "en": "…", "zh-TW": "…" }`: the frontend resolves based on
+  the current UI language, with fallback order **exact language → region-stripped primary language
+  (`zh-TW`→`zh`, `pt-BR`→`pt`) → `en` → `zh` → first non-empty value** (resolution logic in
+  `src/utils/resolveLocalized.js`).
 
-因此一个文件即可覆盖任意多种语言；未列出的界面语言走上述回退。
+A single file can cover any number of languages; unsupported UI languages follow the fallback chain above.
 
-### content：单语言
+### content: single-language
 
-`content` 是**单语言字符串**（不做本地化）。载入并保存后，发送给 Claude Code 时被当作 ultraplan
-的作用域指令；若 `content`（trim 后）以 `<system-reminder>` 开头，则原样使用、**不会被二次包裹**
-（见 `buildCustomTemplate`，`src/utils/ultraplanTemplates.js`）。因此预设 `content` 建议以
-`<system-reminder>`、`[SCOPED INSTRUCTION]` 风格书写。
+`content` is a **single-language string** (not localized). After loading and saving, it is sent
+to Claude Code as the ultraplan scoped instruction. If `content` (after trimming) starts with
+`<system-reminder>`, it is used as-is and **will not be double-wrapped** (see `buildCustomTemplate`
+in `src/utils/ultraplanTemplates.js`). Preset `content` should therefore be written in the
+`<system-reminder>`, `[SCOPED INSTRUCTION]` style.
 
-> 内置 `code-expert` / `research-expert` 的 `content` **直接取自**
-> `src/utils/ultraplanTemplates.js` 的 `ULTRAPLAN_VARIANTS.codeExpert` / `researchExpert`，
-> 并由 `test/ultra-agents-api.test.js` 钉死逐字节一致——改正文请改那个源文件后重新生成本目录 JSON，
-> 不要在此手写另一份。
+> The `content` of the built-in `code-expert` / `research-expert` presets is **taken directly from**
+> `src/utils/ultraplanTemplates.js`'s `ULTRAPLAN_VARIANTS.codeExpert` / `researchExpert`,
+> and is pinned byte-for-byte by `test/ultra-agents-api.test.js` — to change the body, edit that
+> source file and regenerate the JSON in this directory; do not hand-write a second copy here.
 
-## 校验与限制
+## Validation and Limits
 
-加载时对每个文件做防御性校验，不合法者仅 `console.warn` 跳过、不影响其它文件：
+Each file undergoes defensive validation at load time. Invalid files are skipped with
+`console.warn` only — other files are unaffected:
 
-- 必须是合法 JSON 的**普通对象**（非数组/标量）。
-- `id` 通过上述规则；`title`、`content` 为「非空字符串」或「至少含一个非空字符串值的对象」。
-- 单文件 **≤ 256KB**，超出跳过；有效专家 **≤ 100** 个，超出忽略。
-- `description` 缺失或非法时按空串处理。
+- Must be valid JSON representing a **plain object** (not an array/scalar).
+- `id` must pass the rules above; `title` and `content` must be a non-empty string or an object
+  with at least one non-empty string value.
+- Single file **≤ 256KB**, skipped if exceeded; valid experts **≤ 100**, excess ignored.
+- Missing or invalid `description` is treated as an empty string.
 
-## 现有 demo
+## Existing Demos
 
-| 文件 | 专家 | `title` / `description` | `content` 来源 |
+| File | Expert | `title` / `description` | `content` source |
 | --- | --- | --- | --- |
-| `code-expert.json` | 代码专家 / Code Expert | 内联本地化(全 18 语言) | `ULTRAPLAN_VARIANTS.codeExpert` |
-| `research-expert.json` | 调研专家 / Research Expert | 内联本地化(全 18 语言) | `ULTRAPLAN_VARIANTS.researchExpert` |
+| `code-expert.json` | Code Expert / 代码专家 | Inline localized (all 18 languages) | `ULTRAPLAN_VARIANTS.codeExpert` |
+| `research-expert.json` | Research Expert / 调研专家 | Inline localized (all 18 languages) | `ULTRAPLAN_VARIANTS.researchExpert` |
 
-新增预设：在本目录放一个新的 `*.json`（建议文件名与 `id` 一致），重启/刷新即可在弹窗中看到。
+To add a new preset: drop a new `*.json` file in this directory (file name should match `id`),
+and restart/refresh to see it in the modal.