@succsoft/succapp 5.0.7 → 5.0.8

package/dist/cli/l10n/bundle.l10n.zh-cn.json

@@ -99,6 +99,7 @@
 	"err.net.invalidResponse": "远端响应格式不正确",
 	"err.net.invalidResponse.desc": "远端响应不符合当前协议要求，请检查服务版本或联系管理员处理。",
 	"err.net.invalidResponse.dbTableDescribeEmpty.hint": "请检查数据源 {dataSource} 和表 {tableName} 是否存在。",
+	"err.db.connectorNotFound": "数据库连接器不可用：{name}。",
 	"err.db.tableNotFound": "数据库表不存在：{tableName}",
 	"err.cli.unknownCommand": "未知命令：{commandName}",
 	"err.cli.unknownCommand.hint": "请运行 {helpCommand} 查看可用命令。",
@@ -245,27 +246,29 @@
 	"workspace.sync.progress.upgradeMeta.checked": "已检查 {0} 个元数据文件：{1} 个可升级。",
 	"workspace.sync.progress.upgradeMeta.done": "已升级元数据文件：变更 {0} 个，失败 {1} 个，检查 {2} 个。",
 	"workspace.sync.progress.upgradeMeta.scan": "正在扫描元数据文件",
+	"workspace.sync.push.upgradeRequired": "元数据文件 {0} 必须先升级才能推送。请执行 succapp workspace file upgrade 或使用 VS Code 的“升级文件”。",
 	"cli.cmd.common.desc": "常用命令。",
 	"cli.cmd.common.summary": "常用命令",
 	"cli.cmd.common.title": "常用",
 	"cli.cmd.root.summary": "SuccApp 命令行工具。",
 	"cli.host.localeFallback": "区域语言 {0} 不可用，已使用默认文案。",
 	"cli.opt.help": "显示此帮助。",
-	"cli.opt.json": "输出脚本用 NDJSON；二进制内容结果使用 Base64 编码。",
+	"cli.opt.json": "输出脚本用 NDJSON；文件内容（包括文本）使用 Base64，诊断写入 stderr。",
 	"cli.opt.locale": "使用指定区域语言显示 CLI 文案。",
 	"cli.opt.lockTimeout": "失败前等待 workspace 锁释放。",
 	"cli.opt.logLevel": "设置日志级别：trace、debug、info、warn 或 error。",
 	"cli.opt.prettyJson": "输出便于人工阅读的格式化 JSON；不适合按行解析脚本。",
 	"cli.opt.quiet": "隐藏进度和普通信息输出。",
-	"cli.opt.server": "为支持该选项的命令指定服务器。",
+	"cli.opt.server": "直连目标（低于位置 URL，高于活跃服务器和 SUCCAPP_SERVER）；工作区同步时必须匹配活跃服务器。",
 	"cli.opt.verbose": "启用调试日志。",
 	"cli.opt.version": "显示版本信息，并检查 SuccApp CLI 更新。",
-	"cli.opt.workspace": "按指定工作区运行 SuccApp。",
+	"cli.opt.workspace": "指定工作区；不改变进程启动目录，本地输入/输出文件仍相对启动目录解析。",
+	"cli.cmd.root.desc": "SuccApp CLI 用于管理本地工作区、访问服务器、查询模型和操作数据库。\n\n根据任务选择下面的命令分组，再运行 succapp <command> --help 逐级查看帮助。执行前请查看最终子命令的参数、输入规则和操作影响。\n\n脚本或 AI Agent 可加 --json 获取结构化帮助；需要人工阅读 JSON 时，使用 --pretty-json。\n\n首次使用或不确定如何选择命令时，可阅读下面的 CLI 使用指南。请确认手册适用于当前 CLI 和服务器版本；无法联网时，可查阅已有的适用离线手册。\n\n判断完成时同时检查退出码和业务结果；kind=result 也可能包含冲突、跳过或截断。--json 不取消浏览器打开或写入等副作用，输出和退出码说明见下面指南。\n\n详细文档：CLI 使用指南\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/basics/cli.md\n网页：https://docs.succapp.com/ai-building/basics/cli",
 	"cli.cmd.auth.title": "认证",
 	"cli.cmd.auth.summary": "登录、退出并查看本地服务器认证",
-	"cli.cmd.auth.desc": "登录、退出并查看本地服务器认证。",
+	"cli.cmd.auth.desc": "登录、退出并查看本地服务器认证。\n\nlogin 建立并保存认证，status 查看本地记录，logout 删除本地记录。可显式指定服务器 URL；在工作区内也可使用活跃服务器。认证记录由 CLI 与 IDE 共享。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：认证配置\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/configure-auth.md\n网页：https://docs.succapp.com/ai-building/workspace/configure-auth",
 	"cli.cmd.auth.login.summary": "登录服务器。",
-	"cli.cmd.auth.login.desc": "使用 OAuth2 或 PAT 登录 SuccApp 服务器并保存本地认证状态。",
+	"cli.cmd.auth.login.desc": "使用 OAuth2 或 PAT 登录 SuccApp 服务器并保存本地认证状态。\n\n默认通过浏览器完成 OAuth2 授权；无浏览器的脚本环境可使用 --pat，通过标准输入提供令牌。--oauth 与 --pat 不能同时使用。登录成功后保存本地认证，后续命令可复用。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：认证配置\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/configure-auth.md\n网页：https://docs.succapp.com/ai-building/workspace/configure-auth",
 	"cli.cmd.auth.login.oauth": "使用 OAuth2 登录，这是默认方式。",
 	"cli.cmd.auth.login.pat": "使用 Personal Access Token 登录。交互终端会提示输入 token；管道输入仍从标准输入读取。",
 	"cli.cmd.auth.login.patPrompt": "个人访问令牌（PAT）：",
@@ -276,19 +279,20 @@
 	"cli.cmd.auth.login.loggedIn": "已登录：{0}",
 	"cli.cmd.auth.login.loggedInAs": "已登录：{0}，用户：{1}",
 	"cli.cmd.auth.logout.summary": "删除本地认证配置。",
-	"cli.cmd.auth.logout.desc": "从本地认证配置中删除已保存的认证信息。",
+	"cli.cmd.auth.logout.desc": "从本地认证配置中删除已保存的认证信息。\n\n省略目标时使用当前服务器；--all 删除所有服务器的本地认证，不能与位置参数 URL 同时使用。此操作不撤销服务器签发的 PAT，也不删除工作区的服务器配置。",
 	"cli.cmd.auth.logout.all": "删除所有服务器的本地认证配置。",
 	"cli.cmd.auth.logout.removedAllAuth": "已删除所有服务器的本地认证配置：{0}",
 	"cli.cmd.auth.logout.removedAuth": "已删除本地认证配置：{0}",
 	"cli.cmd.auth.logout.serverUrlTogether": "不要同时传入服务器 URL 和 --all。",
 	"cli.cmd.auth.logout.storedAuth": "没有本地认证配置：{0}",
 	"cli.cmd.auth.status.summary": "显示本地认证状态。",
-	"cli.cmd.auth.status.desc": "显示指定服务器的本地认证信息。",
+	"cli.cmd.auth.status.desc": "显示指定服务器的本地认证信息。\n\n此命令只检查本地保存的认证，不请求服务器验证有效性。token 和 refreshToken 表示是否存在，不输出秘密值；实际访问失败时应检查服务器地址并重新登录。",
 	"cli.cmd.auth.status.noStoredOutput": "服务器：{server}\n已保存认证：{storedAuth}",
 	"cli.cmd.auth.status.output": "服务器：{server}\n已保存认证：{storedAuth}\n认证方式：{authType}\n用户名：{username}\n用户 ID：{userId}\nToken：{token}\n刷新 Token：{refreshToken}\n过期时间：{expiresAt}\n上次登录时间：{lastLoginAt}\n更新时间：{updatedAt}",
+	"cli.cmd.auth.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
 	"cli.cmd.db.title": "数据库",
 	"cli.cmd.db.summary": "查看和操作服务器数据库与数据源",
-	"cli.cmd.db.desc": "查看和操作服务器数据库与数据源。",
+	"cli.cmd.db.desc": "查看和操作服务器数据库与数据源。\n\n建立数据连接时，从 connector 选择连接器，再进入 source 准备和管理数据源；了解数据库结构时，使用 schema 和 table。各分组只列直接下级，可运行 succapp db <分组> --help 继续查看。\n\n查询物理表使用 query，导出数据使用 export；若需要按业务模型口径查询，请查看 succapp model --help。\n\nexec、import 和数据源写命令会修改服务器配置或数据库数据，执行前请查看对应子命令的帮助，确认目标服务器、数据源和操作影响。\n\n准备连接时可阅读下面的指南，请确认资料适用于当前服务器版本。\n\n详细文档：连接数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\n网页：https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.dataSource": "数据源",
 	"cli.cmd.db.connection": "连接",
 	"cli.cmd.db.defaultSchema": "逻辑默认 schema",
@@ -321,8 +325,8 @@
 	"cli.cmd.db.query.empty": "查询成功，返回 0 行。",
 	"cli.cmd.db.tableOrQueryConflict": "<table> 与 --query/--query-file 不能同时传。",
 	"cli.cmd.db.connector.title": "数据库连接器",
-	"cli.cmd.db.connector.summary": "发现服务器可用的数据库连接器",
-	"cli.cmd.db.connector.desc": "查看当前服务器可用的数据库连接器及各连接器特有的配置项。",
+	"cli.cmd.db.connector.summary": "查看数据库连接器及其配置项。",
+	"cli.cmd.db.connector.desc": "查看当前服务器可用的数据库连接器及各连接器特有的配置项。\n\n先用 list 获取连接器 ID，再用 show 查看字段；连接器由目标服务器提供，不同服务器可能不同。准备数据源配置时可继续使用 succapp db source template。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：连接数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\n网页：https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.connector.connector": "连接器",
 	"cli.cmd.db.connector.displayName": "显示名称",
 	"cli.cmd.db.connector.dbKind": "数据库分类",
@@ -330,68 +334,68 @@
 	"cli.cmd.db.connector.defaultValue": "默认值",
 	"cli.cmd.db.connector.secret": "秘密字段",
 	"cli.cmd.db.connector.list.summary": "列出服务器可用的数据库连接器。",
-	"cli.cmd.db.connector.list.desc": "列出当前服务器可用于创建数据源的数据库连接器。",
+	"cli.cmd.db.connector.list.desc": "列出当前服务器可用于创建数据源的数据库连接器。\n\n结果中的连接器 ID 可用于 db connector show 和 db source template。列表表示服务器可用的连接器，不代表已配置的数据源或数据库连接已经可用。",
 	"cli.cmd.db.connector.show.summary": "查看数据库连接器支持的配置项。",
-	"cli.cmd.db.connector.show.desc": "查看当前服务器返回的通用及连接器特有配置项、安全默认值和 JDBC URL 模板。",
+	"cli.cmd.db.connector.show.desc": "查看当前服务器返回的通用及连接器特有配置项、安全默认值和 JDBC URL 模板。\n\n<connector> 使用 list 返回的 ID。根据字段类型、必填项和秘密字段准备配置；模板中的示例值仍需替换，连接能否成功应通过 db source test 验证。",
 	"cli.cmd.db.connector.show.connector": "由 db connector list 返回的数据库连接器 ID。",
 	"cli.cmd.db.source.title": "数据库源",
-	"cli.cmd.db.source.summary": "查看和管理数据库源",
-	"cli.cmd.db.source.desc": "查看和管理数据库源。",
+	"cli.cmd.db.source.summary": "查看、测试和管理数据源。",
+	"cli.cmd.db.source.desc": "查看、测试和管理服务器上的数据源。\n\n已有数据源使用 list/show 查看，使用 probe 验证连接并查看默认 schema 等信息；test 可测试已有数据源或尚未保存的配置。创建前先用 template 获取配置模板，再查看 create 的输入要求。\n\ncreate、update 和 remove 会修改服务器上的数据源配置；test/probe 会实际尝试连接数据库。执行前请查看具体命令的帮助，并确认目标服务器与数据源。\n\n准备连接时可阅读下面的指南，请确认资料适用于当前服务器版本。\n\n详细文档：连接数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\n网页：https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.source.*.config": "从文件读取数据源配置 JSON，或使用 - 读取标准输入。",
 	"cli.cmd.db.source.*.test": "保存前先测试连接。",
 	"cli.cmd.db.source.list.summary": "列出可见数据源。",
-	"cli.cmd.db.source.list.desc": "列出当前 SuccApp 服务器会话可见的数据源。",
+	"cli.cmd.db.source.list.desc": "列出当前 SuccApp 服务器会话可见的数据源。\n\n后续 show、probe、schema、table 和 SQL 命令使用这里返回的数据源标识。空列表只表示当前服务器会话未返回可见数据源。",
 	"cli.cmd.db.source.list.empty": "没有可用的数据源。",
 	"cli.cmd.db.source.show.summary": "查看数据源配置。",
-	"cli.cmd.db.source.show.desc": "显示数据源配置。",
+	"cli.cmd.db.source.show.desc": "显示数据源配置。\n\n<datasource> 使用 list 返回的标识。JSON 的 config 字段是配置正文，输出可能移除 password；不要把整个结果信封或脱敏后的值直接当成完整更新输入。此命令不验证数据库连接。",
 	"cli.cmd.db.source.probe.summary": "验证已有数据源连接，并显示逻辑默认 schema、数据库及驱动信息。",
-	"cli.cmd.db.source.probe.desc": "打开并验证已有数据源连接，返回逻辑默认 schema、数据库产品、标准及完整版本和 JDBC 驱动信息；JSON 输出还会包含脱敏后的数据源配置。",
+	"cli.cmd.db.source.probe.desc": "打开并验证已有数据源连接，返回逻辑默认 schema、数据库产品、标准及完整版本和 JDBC 驱动信息；JSON 输出还会包含脱敏后的数据源配置。\n\n先用 list 确定数据源标识。探测会实际访问数据库；连接成功仅说明本次连接可用，不保证后续查询权限和模型配置正确。",
 	"cli.cmd.db.source.probe.datasource": "要探测的已有数据源名称。",
 	"cli.cmd.db.source.test.summary": "测试已有数据源或未保存的 JSON 配置能否建立连接。",
-	"cli.cmd.db.source.test.desc": "验证已有数据源，或在不保存的情况下验证 JSON 配置能否建立连接；两种方式都会返回逻辑默认 schema、数据库及驱动信息。",
+	"cli.cmd.db.source.test.desc": "验证已有数据源，或在不保存的情况下验证 JSON 配置能否建立连接；两种方式都会返回逻辑默认 schema、数据库及驱动信息。\n\n<datasource> 与 --config 必须且只能选择一个；--config 指定 JSON 文件，或用 - 读取标准输入。只提交配置对象，不提交 CLI 结果信封。测试不保存配置，成功后仍需通过 create 或 update 保存。",
 	"cli.cmd.db.source.test.datasource": "要测试的已有数据源名称。",
 	"cli.cmd.db.source.template.summary": "根据服务器连接器生成安全的数据源 JSON 模板。",
-	"cli.cmd.db.source.template.desc": "根据当前服务器中的连接器生成数据源配置模板。模板采用连接器提供的默认配置，且不会包含密码或其他秘密值。",
+	"cli.cmd.db.source.template.desc": "根据当前服务器中的连接器生成数据源配置模板。模板采用连接器提供的默认配置，且不会包含密码或其他秘密值。\n\n<connector> 使用 db connector list 返回的 ID。普通输出就是配置 JSON；--json 的配置在 config 字段中。填写实际连接信息后，可先 test，再 create。此命令不创建数据源。",
 	"cli.cmd.db.source.template.connector": "由 db connector list 返回的数据库连接器 ID。",
 	"cli.cmd.db.source.create.summary": "新建数据源。",
-	"cli.cmd.db.source.create.desc": "根据 JSON 配置创建数据源。在 SuccApp 工作区中，AI Agent 应先阅读 .agents/skills/succapp-docs/SKILL.md，并按其中的索引查找数据源元数据和连接器配置文档。",
+	"cli.cmd.db.source.create.desc": "根据 JSON 配置在所选服务器上创建数据源，会保存服务器数据源配置。\n\n先用 succapp db connector list/show 确定连接器与字段，再用 succapp db source template 获取模板。只提取结果中的 config 配置，填写真实连接参数后通过 --config 提交，整个结果信封不能直接作为创建输入。\n\n--config 为必填，可指定 JSON 文件或用 - 读取标准输入；--test 会在保存前测试连接，但不代表后续模型查询和数据权限已经验证。\n\n保存后使用相同服务器和配置名称运行 succapp db source show 核验。响应中断不代表创建未发生，应先查询当前状态，不要直接重复创建；返回的配置可能移除 password。\n\n准备连接前可阅读下面的指南。在 SuccApp 工作区中，也可先读 .agents/skills/succapp-docs/SKILL.md 查找适用的离线手册；请确认资料与当前服务器版本匹配。\n\n详细文档：连接数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\n网页：https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.source.create.created": "已新建数据源：{0}",
 	"cli.cmd.db.source.update.summary": "修改数据源。",
-	"cli.cmd.db.source.update.desc": "根据 JSON 配置更新数据源。",
+	"cli.cmd.db.source.update.desc": "根据 JSON 配置更新数据源。\n\n先用 show 查看当前配置，再通过必填的 --config 提交配置对象（文件或 - 标准输入）。返回值可能脱敏，应核对秘密字段如何填写；--test 在保存前测试连接。更新直接作用于服务器，之后用 show/probe 核验；响应中断时先检查现状再重试。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n提交完整的预期配置，不把它当作字段补丁；当前配套服务器在更新时保留缺失或空的 password，但其它缺失字段不保证保留。不要把脱敏字符串当作新密码写回。\n\n详细文档：连接数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/connect-data.md\n网页：https://docs.succapp.com/ai-building/data/connect-data",
 	"cli.cmd.db.source.update.updated": "已修改数据源：{0}",
 	"cli.cmd.db.source.remove.summary": "删除数据源。",
-	"cli.cmd.db.source.remove.desc": "显式确认后删除数据源。",
+	"cli.cmd.db.source.remove.desc": "显式确认后删除数据源。\n\n必须传 --force 确认删除服务器上的数据源配置。删除前检查引用它的模型和任务；删除配置不等于删除数据库物理表，但依赖该配置的访问可能失败。",
 	"cli.cmd.db.source.remove.force": "确认删除数据源。",
 	"cli.cmd.db.source.remove.dbSourceRemove": "删除数据源需要 --force。",
 	"cli.cmd.db.source.remove.deleted": "已删除数据源：{0}",
 	"cli.cmd.db.schema.title": "数据库 schema",
-	"cli.cmd.db.schema.summary": "查看数据库 schema",
-	"cli.cmd.db.schema.desc": "查看数据库 schema。",
+	"cli.cmd.db.schema.summary": "查看数据源中的 schema。",
+	"cli.cmd.db.schema.desc": "查看数据库 schema。\n\n使用 list 查看指定数据源的 schema；数据源标识来自 db source list。物理表和字段请继续查看 succapp db table --help。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：探查数据库数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/explore-database-data.md\n网页：https://docs.succapp.com/ai-building/data/explore-database-data",
 	"cli.cmd.db.schema.list.summary": "列出数据源 schema。",
-	"cli.cmd.db.schema.list.desc": "列出数据源中的 schema。",
+	"cli.cmd.db.schema.list.desc": "列出数据源中的 schema。\n\n<datasource> 使用 db source list 返回的标识，可用 --catalog 限定目录。返回名称可用于后续表查询；可见范围由数据库连接和权限决定。",
 	"cli.cmd.db.schema.list.catalog": "目录",
 	"cli.cmd.db.schema.list.empty": "数据源 '{0}' 中没有 schema。",
 	"cli.cmd.db.table.title": "数据库表",
-	"cli.cmd.db.table.summary": "查看数据库表",
-	"cli.cmd.db.table.desc": "查看数据库表。",
+	"cli.cmd.db.table.summary": "查看数据库表及其结构。",
+	"cli.cmd.db.table.desc": "查看数据库表。\n\nlist 查找物理表，describe 查看字段和表元数据。先确定数据源与 schema；这里的物理表与 model 命令中的 .tbl 语义模型不同。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：探查数据库数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/explore-database-data.md\n网页：https://docs.succapp.com/ai-building/data/explore-database-data",
 	"cli.cmd.db.table.list.summary": "列出数据源中的表。",
-	"cli.cmd.db.table.list.desc": "列出数据源中的表。",
+	"cli.cmd.db.table.list.desc": "列出数据源中的表。\n\n先用 db source list 和 db schema list 确定范围，再用 --table-name-contains 按表名筛选。查询数据前可用 describe 查看字段，避免猜测名称和类型。",
 	"cli.cmd.db.table.list.tableNameContains": "按名称过滤表。支持 * 和 ? 通配符。",
 	"cli.cmd.db.table.list.empty": "没有可用的数据库表。",
 	"cli.cmd.db.table.list.noMatches": "当前条件没有匹配的数据库表。",
 	"cli.cmd.db.table.describe.summary": "查看数据库表结构。",
-	"cli.cmd.db.table.describe.desc": "查看数据库表的字段和元数据。",
+	"cli.cmd.db.table.describe.desc": "查看数据库表的字段和元数据。\n\n使用 table list 返回的表名；必要时用 --schema 明确所属 schema。此命令读取结构，不返回表数据；预览数据使用 db query。\n\n表名可写 schema.table；显式提供 --schema 时，<table> 会整体作为表名，应只填写表名，避免重复限定。",
 	"cli.cmd.db.table.describe.schema": "schema 名称。",
 	"cli.cmd.db.*.file": "从文件读取 SQL。",
 	"cli.cmd.db.*.schema": "SQL 执行 schema。",
 	"cli.cmd.db.*.timeout": "SQL 超时时间，单位秒，默认 30。",
 	"cli.cmd.db.query.summary": "执行只读 SQL 查询。",
-	"cli.cmd.db.query.desc": "通过 Dev Tool v2 执行 SQL。SuccApp CLI 的 query 命令只允许只读查询。",
+	"cli.cmd.db.query.desc": "对指定数据源执行只读 SQL 查询。先用 succapp db source list 获取可见数据源标识，需要了解表结构时使用 succapp db table list/describe。\n\n位置参数 <sql> 与 --file 最多选择一个，均未指定时从标准输入读取 SQL。--timeout 单位为秒，默认 30。\n\n查询用于预览，不能把返回的有限行数当成完整数据；需要完整导出时查看 succapp db export --help。\n\n此命令不用于数据写入。写入操作应先查看 succapp db exec --help 并确认其影响。\n\n当前配套服务器的预览默认最多 100 行，上限 1000 行；实际以目标服务器和返回的截断信息为准。完整数据请使用对应 export 命令。\n\n--max-rows=0 按服务器默认行数处理，不表示无限制。",
 	"cli.cmd.db.query.maxRows": "最大返回行数。",
 	"cli.cmd.db.query.nonReadOnlySql": "db query 只允许只读 SQL。写入或 schema 变更请使用 db exec；确认影响后再添加 --force。",
 	"cli.cmd.db.query.sqlOrFileConflict": "SQL 只能通过 <sql> 或 --file 传入，不能同时使用。",
 	"cli.cmd.db.exec.summary": "执行任意 SQL。",
-	"cli.cmd.db.exec.desc": "通过 Dev Tool v2 执行 SQL。写入或 schema 变更需要显式确认。",
+	"cli.cmd.db.exec.desc": "执行 SQL 并返回结果集或更新计数；可能修改数据库数据或结构。\n\n位置参数 <sql> 与 --file 最多选择一个，均未指定时读取标准输入。默认超时 30 秒。服务器判定为危险 SQL 时需要 --force；未要求 --force 不等于只读，所有写入都应事先确认影响。超时或断连后先核对数据库状态，不要直接重复写入。\n\n当前配套服务器的预览默认最多 100 行，上限 1000 行；实际以目标服务器和返回的截断信息为准。完整数据请使用对应 export 命令。\n\n--max-rows=0 按服务器默认行数处理，不表示无限制。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：执行数据库变更\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/modify-database-data.md\n网页：https://docs.succapp.com/ai-building/data/modify-database-data",
 	"cli.cmd.db.exec.maxRows": "限制结果集返回行数。",
 	"cli.cmd.db.exec.force": "确认执行安全分析标记为危险的 SQL。",
 	"cli.cmd.db.exec.dangerousSql": "危险 SQL 已被拦截。请检查影响后再使用 --force 重新执行。{0}",
@@ -399,53 +403,61 @@
 	"cli.cmd.db.exec.fullTableData": "全表数据变更",
 	"cli.cmd.db.exec.schemaMutation": "schema 变更",
 	"cli.cmd.db.import.summary": "将 CSV 数据导入表。",
-	"cli.cmd.db.import.desc": "将 CSV 数据导入数据库表。",
+	"cli.cmd.db.import.desc": "将 CSV 数据导入数据库表。\n\n通过 --input 指定 UTF-8 CSV 文件，或用 - 读取标准输入，首行为字段表头。默认 append 追加；truncate 和 replace 当前都先清空目标表再导入，并非按主键更新。\n\n--dry-run 只解析和统计 CSV，不实际验证数据库约束或完成写入；importedRows 是 CSV 数据行数，不是独立核验的落库行数。实际导入会修改数据库，响应中断时先核对数据库结果，避免重复追加。\n\n表名可写 schema.table；显式提供 --schema 时，<table> 会整体作为表名，应只填写表名，避免重复限定。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：导入和导出数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/import-export-data.md\n网页：https://docs.succapp.com/ai-building/data/import-export-data",
 	"cli.cmd.db.import.input": "从文件读取表数据 CSV，或使用 - 读取标准输入。",
 	"cli.cmd.db.import.mode": "导入模式。默认 append；truncate 和 replace 必须显式传入。",
-	"cli.cmd.db.import.dryRun": "只校验导入，不写入行。",
+	"cli.cmd.db.import.dryRun": "只解析和统计 CSV，不写入，也不验证实际数据库约束。",
 	"cli.cmd.db.import.schema": "表 schema。",
 	"cli.cmd.db.export.summary": "将表数据或查询结果导出为 CSV。",
-	"cli.cmd.db.export.desc": "将表数据或查询结果导出为 CSV。",
+	"cli.cmd.db.export.desc": "将表数据或查询结果导出为 CSV。\n\n<table>、--query、--query-file 必须且只能选择一个，并用 --output 指定本地 CSV 文件。已有文件需要 --force 才能覆盖。导出结果仍受查询条件和服务器权限约束；完成后核对文件和结果中的大小。\n\n表名可写 schema.table；显式提供 --schema 时，<table> 会整体作为表名，应只填写表名，避免重复限定。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：导入和导出数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/import-export-data.md\n网页：https://docs.succapp.com/ai-building/data/import-export-data",
 	"cli.cmd.db.export.query": "导出查询结果而不是表数据。",
 	"cli.cmd.db.export.queryFile": "从文件读取导出查询 SQL。",
 	"cli.cmd.db.export.schema": "表 schema 或 SQL 执行 schema。",
 	"cli.cmd.db.export.output": "把 CSV 输出写入本地文件。",
 	"cli.cmd.db.export.force": "输出文件已存在时允许覆盖。",
 	"cli.cmd.db.export.exportedData": "已导出数据到 {0}",
+	"cli.cmd.db.*.datasource": "db source list 返回的数据源标识，不是连接器 ID。",
+	"cli.cmd.db.*.sql": "SQL 文本；与 --file 互斥，均省略时从标准输入读取。",
+	"cli.cmd.db.*.table": "db table list 返回的表名；不传 --schema 时支持 schema.table。",
+	"cli.cmd.db.source.*.datasource": "db source list 返回的数据源标识，不是连接器 ID。",
+	"cli.cmd.db.schema.*.datasource": "db source list 返回的数据源标识，不是连接器 ID。",
+	"cli.cmd.db.table.*.datasource": "db source list 返回的数据源标识，不是连接器 ID。",
+	"cli.cmd.db.table.*.schema": "db schema list 返回的 schema；省略时由数据源处理默认范围。",
+	"cli.cmd.db.table.*.table": "db table list 返回的表名；不传 --schema 时支持 schema.table。",
 	"cli.cmd.server.title": "服务器",
 	"cli.cmd.server.summary": "查看和操作目标 SuccApp 服务器",
-	"cli.cmd.server.desc": "查看和操作目标 SuccApp 服务器。",
+	"cli.cmd.server.desc": "查看和操作目标 SuccApp 服务器。\n\n这些命令直接访问目标服务器，无需先克隆项目。通过 --server 或工作区活跃服务器确定目标，认证使用 auth login；文件、设置、脚本和运维写命令会直接影响服务器。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：如何使用 SuccApp CLI 排查系统运行问题\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/troubleshoot/system-diagnostics.md\n网页：https://docs.succapp.com/ai-building/troubleshoot/system-diagnostics",
 	"cli.cmd.server.serverNotConfigured": "此工作区未配置服务器：{0}",
 	"cli.cmd.server.serverReachable": "服务器可达：{0}",
 	"cli.cmd.server.ping.summary": "检查服务器是否可达。",
-	"cli.cmd.server.ping.desc": "检查 SuccApp Dev Tool v2 ping 接口是否可达。",
+	"cli.cmd.server.ping.desc": "检查 SuccApp Dev Tool v2 ping 接口是否可达。\n\n可直接传服务器 URL。成功表示 ping 接口可达，不代表已登录、拥有业务权限或数据库可用；进一步诊断使用 server info。",
 	"cli.cmd.server.info.summary": "显示服务器信息。",
-	"cli.cmd.server.info.desc": "显示服务器信息和元数据版本。",
+	"cli.cmd.server.info.desc": "显示服务器信息和元数据版本。\n\n默认显示主要信息，可用 --scope 选择范围或 --all 展开。此命令用于确认目标环境和版本，不执行升级；脚本读取结构化字段请用 --json。",
 	"cli.cmd.server.info.scope": "只显示指定范围。可重复使用或用逗号分隔：product、sys、metadata、inspect、jvm、env、all。",
 	"cli.cmd.server.info.all": "显示全部信息范围。",
 	"cli.cmd.server.info.raw": "输出服务器详细信息的原始响应。",
 	"cli.cmd.server.cache.title": "服务器缓存",
 	"cli.cmd.server.cache.summary": "管理服务器缓存",
-	"cli.cmd.server.cache.desc": "管理服务器缓存。",
+	"cli.cmd.server.cache.desc": "管理服务器缓存。\n\n先用 list 查看缓存名称和占用，再用 clean 清理指定项。清理会影响运行中的服务器缓存，--all 的范围是全部系统缓存。",
 	"cli.cmd.server.cache.list.summary": "列出服务器缓存条目。",
-	"cli.cmd.server.cache.list.desc": "列出服务端系统缓存条目（条数、磁盘/内存占用、命中率）。",
+	"cli.cmd.server.cache.list.desc": "列出服务端系统缓存条目（条数、磁盘/内存占用、命中率）。\n\n返回值反映查询时的缓存状态，命中率等统计会随运行变化。清理时使用这里返回的名称，不要猜测缓存标识。",
 	"cli.cmd.server.cache.list.empty": "无服务器缓存条目。",
 	"cli.cmd.server.cache.clean.summary": "清空服务器缓存。",
-	"cli.cmd.server.cache.clean.desc": "按 <name> 清空指定服务端系统缓存，或用 --all 清空全部。",
+	"cli.cmd.server.cache.clean.desc": "按 <name> 清空指定服务端系统缓存，或用 --all 清空全部。\n\n<name> 与 --all 必须且只能选择一个，无需额外 --force。清理会使缓存失效，后续访问可能重新加载数据；先核对 list，完成后再次检查。",
 	"cli.cmd.server.cache.clean.all": "清空全部服务器缓存条目。",
 	"cli.cmd.server.cache.clean.cleaned": "已清空服务器缓存：{1}（{0}）",
 	"cli.cmd.server.cluster.title": "服务器集群",
 	"cli.cmd.server.cluster.summary": "查看服务器集群节点",
-	"cli.cmd.server.cluster.desc": "查看集群成员、健康状态、网络状态和运行诊断。",
+	"cli.cmd.server.cluster.desc": "查看集群成员、健康状态、网络状态和运行诊断。\n\n先用 list 获取节点 ID，再用 show 查看某个节点的详细状态。集群成员信息与诊断采样可能随节点上下线变化。",
 	"cli.cmd.server.cluster.list.summary": "列出服务器集群节点。",
-	"cli.cmd.server.cluster.list.desc": "列出与服务器系统设置页面相同的集群节点数据。",
+	"cli.cmd.server.cluster.list.desc": "列出与服务器系统设置页面相同的集群节点数据。\n\n返回的节点 ID 用于 cluster show；检查在线和健康状态后再做节点诊断。列表中的不可达节点不应当被当作健康节点。\n\n--watch 持续刷新，Ctrl+C 停止；--interval 仅能与 --watch 同用。--watch 不支持 --json，脚本应重复执行一次性 JSON 查询。",
 	"cli.cmd.server.cluster.list.health": "只显示指定健康级别的节点：ok、warning、error 或 unknown。",
 	"cli.cmd.server.cluster.list.watch": "持续刷新集群状态，直到用户中断。",
 	"cli.cmd.server.cluster.list.interval": "设置 watch 刷新间隔（毫秒，3000 到 60000），仅可与 --watch 一起使用。",
 	"cli.cmd.server.cluster.list.empty": "没有集群节点匹配当前过滤条件。",
 	"cli.cmd.server.cluster.list.updatedAt": "更新时间：{0}",
 	"cli.cmd.server.cluster.show.summary": "显示一个服务器集群节点。",
-	"cli.cmd.server.cluster.show.desc": "按节点 ID 精确显示详情，并使用与 server info 相同的分范围信息布局。",
+	"cli.cmd.server.cluster.show.desc": "按节点 ID 精确显示详情，并使用与 server info 相同的分范围信息布局。\n\n<node-id> 使用 cluster list 返回的 ID，可用 --scope 或 --all 扩大信息范围。节点可能在两次请求间离线，失败时先刷新节点清单。",
 	"cli.cmd.server.cluster.show.scope": "只显示指定的人类可读详情。可重复使用或用逗号分隔：product、sys、inspect、jvm、env、all。",
 	"cli.cmd.server.cluster.show.all": "显示全部人类可读详情范围。",
 	"cli.cmd.server.cluster.out.name": "名称",
@@ -476,23 +488,23 @@
 	"cli.cmd.server.cluster.out.lastSentAt": "最近发送时间",
 	"cli.cmd.server.thread.title": "服务器线程",
 	"cli.cmd.server.thread.summary": "查看 JVM 线程",
-	"cli.cmd.server.thread.desc": "查看 JVM 线程快照，并请求取消已登记的产品任务。",
+	"cli.cmd.server.thread.desc": "查看 JVM 线程快照，并请求取消已登记的产品任务。\n\nlist 快速筛选，show 查看单个线程，dump 查看完整堆栈，top 连续采样分析。cancel 仅请求协作式取消产品任务，不能用作任意 JVM 线程终止。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：如何使用 SuccApp CLI 排查系统运行问题\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/troubleshoot/system-diagnostics.md\n网页：https://docs.succapp.com/ai-building/troubleshoot/system-diagnostics",
 	"cli.cmd.server.thread.*.state": "只显示指定 JVM 状态：new、runnable、blocked、waiting、timed-waiting 或 terminated。",
 	"cli.cmd.server.thread.*.working": "只显示当前正在工作的线程。",
 	"cli.cmd.server.thread.*.sql": "只显示当前正在执行 SQL 的线程。",
 	"cli.cmd.server.thread.list.summary": "列出 JVM 线程。",
-	"cli.cmd.server.thread.list.desc": "列出 JVM 线程摘要，不返回完整堆栈。",
+	"cli.cmd.server.thread.list.desc": "列出 JVM 线程摘要，不返回完整堆栈。\n\n可按状态、工作任务或 SQL 执行情况筛选，并用 --cluster 指定节点。线程 ID 仅在对应节点和时刻有意义；需要完整上下文时继续 show 或 dump。",
 	"cli.cmd.server.thread.list.cluster": "在指定的单个集群节点上执行查询。",
 	"cli.cmd.server.thread.list.empty": "没有 JVM 线程匹配当前过滤条件。",
 	"cli.cmd.server.thread.dump.summary": "抓取 JVM 线程转储。",
-	"cli.cmd.server.thread.dump.desc": "抓取匹配条件的 JVM 线程及其未截断的调用堆栈。",
+	"cli.cmd.server.thread.dump.desc": "抓取匹配条件的 JVM 线程及其未截断的调用堆栈。\n\n可用 --state、--working、--sql 缩小范围，--cluster 指定节点。输出是一次采样的快照；分析持续占用应使用 top 或比较多次快照。",
 	"cli.cmd.server.thread.dump.cluster": "从指定的单个集群节点抓取线程转储。",
 	"cli.cmd.server.thread.dump.deadlocks.none": "死锁：无",
 	"cli.cmd.server.thread.dump.deadlocks.found": "死锁：{0}",
 	"cli.cmd.server.thread.dump.waitingLock": "正在等待锁 {0}",
 	"cli.cmd.server.thread.dump.waitingLockOwned": "正在等待锁 {0}，持有线程 #{1}",
 	"cli.cmd.server.thread.top.summary": "采样 JVM 线程热点。",
-	"cli.cmd.server.thread.top.desc": "轮询 CPU、线程、内存和 GC 原始采样并在本地分析，服务器不保留最终报告。",
+	"cli.cmd.server.thread.top.desc": "轮询 CPU、线程、内存和 GC 原始采样并在本地分析，服务器不保留最终报告。\n\n--duration 控制总时长，--interval 控制采样间隔，--refresh 控制进度刷新。采样分析只反映观察窗口；应同时检查失败节点和采样完整性，不能把缺失采样当作零负载。",
 	"cli.cmd.server.thread.top.cluster": "采样指定集群节点；传入 all 时由客户端并发轮询当前全部成员。",
 	"cli.cmd.server.thread.top.duration": "设置客户端 1 秒到 20 秒的分析窗口，使用 ms 或 s 后缀。",
 	"cli.cmd.server.thread.top.interval": "设置服务端每次 200 毫秒到 2 秒的采样窗口，分析窗口内至少需要包含两次采样。",
@@ -536,12 +548,12 @@
 	"cli.cmd.server.thread.top.out.gcCount": "回收次数",
 	"cli.cmd.server.thread.top.out.gcTime": "GC 时间",
 	"cli.cmd.server.thread.show.summary": "显示一个 JVM 线程。",
-	"cli.cmd.server.thread.show.desc": "显示线程当前快照、已授权 SQL 信息和完整堆栈。",
+	"cli.cmd.server.thread.show.desc": "显示线程当前快照、已授权 SQL 信息和完整堆栈。\n\n先用 list 找到线程 ID，并保持同一 --cluster 目标。线程可能已经结束或换了任务；需要取消时从最新快照读取 cancelSerial，再查看 cancel 的要求。",
 	"cli.cmd.server.thread.show.cluster": "从指定的单个集群节点读取线程。",
 	"cli.cmd.server.thread.show.stack": "堆栈：",
 	"cli.cmd.server.thread.show.stackEmpty": "  （堆栈已不可用）",
 	"cli.cmd.server.thread.cancel.summary": "请求取消 JVM 线程任务。",
-	"cli.cmd.server.thread.cancel.desc": "仅当当前任务仍匹配取消序号时，请求协作式取消已登记的产品任务。",
+	"cli.cmd.server.thread.cancel.desc": "仅当当前任务仍匹配取消序号时，请求协作式取消已登记的产品任务。\n\n必须提供最新的 --cancel-serial 并加 --force，同时保持与 show 相同的节点。成功表示已请求取消，不保证任务立即结束；随后重新查看状态，序号变化时不要对新任务盲目重试。",
 	"cli.cmd.server.thread.cancel.cancelSerial": "传入 thread list 或 show 返回的当前取消序号。",
 	"cli.cmd.server.thread.cancel.cluster": "取消指定单个集群节点上的任务。",
 	"cli.cmd.server.thread.cancel.force": "确认发起协作式取消请求。",
@@ -562,13 +574,13 @@
 	"cli.cmd.server.thread.out.logAvailable": "可查看日志",
 	"cli.cmd.server.techLog.title": "服务器技术日志",
 	"cli.cmd.server.techLog.summary": "查看和管理服务器技术日志",
-	"cli.cmd.server.techLog.desc": "查看技术日志并管理运行时 logger 级别；这些命令需要系统设置中控制台的访问权限。",
+	"cli.cmd.server.techLog.desc": "查看技术日志并管理运行时 logger 级别；这些命令需要系统设置中控制台的访问权限。\n\n示例中的 NODE 应先赋值为 server cluster list 返回的节点 ID；LOG_FILE 应先赋值为该节点 tech-log list 返回的日志文件名。变量始终加双引号，避免空格或 shell 元字符改变参数。\n\nlist 查看日志文件，tail 读取或跟随当前日志，download 保存指定日志，level 管理日志级别。集群环境应明确节点；日志可能包含诊断上下文，按实际需要限定读取范围。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：如何使用 SuccApp CLI 排查系统运行问题\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/troubleshoot/system-diagnostics.md\n网页：https://docs.succapp.com/ai-building/troubleshoot/system-diagnostics",
 	"cli.cmd.server.techLog.*.cluster": "从指定集群节点读取；省略时使用当前 HTTP 节点。运行 'succapp server cluster list' 获取节点名。",
 	"cli.cmd.server.techLog.list.summary": "列出技术日志文件。",
-	"cli.cmd.server.techLog.list.desc": "列出服务器系统设置控制台中相同的 .log 文件；需要控制台查看权限。",
+	"cli.cmd.server.techLog.list.desc": "列出服务器系统设置控制台中相同的 .log 文件；需要控制台查看权限。\n\n示例中的 NODE 应先赋值为 server cluster list 返回的节点 ID；LOG_FILE 应先赋值为该节点 tech-log list 返回的日志文件名。变量始终加双引号，避免空格或 shell 元字符改变参数。\n\n结果中的文件名用于 download，节点应保持一致。列表来自服务器日志目录，不是本地 CLI 日志。",
 	"cli.cmd.server.techLog.list.empty": "此节点没有可用的技术日志文件。",
 	"cli.cmd.server.techLog.tail.summary": "读取技术日志尾部。",
-	"cli.cmd.server.techLog.tail.desc": "使用系统设置页面相同的游标协议读取当前技术日志；需要控制台查看权限。单次 JSON 结果中的 content 是日志明文。",
+	"cli.cmd.server.techLog.tail.desc": "使用系统设置页面相同的游标协议读取当前技术日志；需要控制台查看权限。单次 JSON 结果中的 content 是日志明文。\n\n续读示例的 POSITION 和 CURSOR_FILE 必须取自同一次 tail 响应中的 position 与 logFile，并保持目标节点一致；它们不是随意指定的行号和文件名。\n\n示例中的 NODE 应先赋值为 server cluster list 返回的节点 ID；LOG_FILE 应先赋值为该节点 tech-log list 返回的日志文件名。变量始终加双引号，避免空格或 shell 元字符改变参数。\n\n默认读取一次，--follow 持续轮询，可用 Ctrl+C 停止。续读时配套传入上次结果的 --from 和 --log-file；不要把旧文件游标用于另一节点或轮转后的文件。\n\n--from 和 --log-file 必须配套，不能与显式 --lines 混用；--interval 仅能与 --follow 同用。--follow 不支持 --json，脚本可使用一次性 JSON 结果续读。",
 	"cli.cmd.server.techLog.tail.lines": "首次日志片段保留的末尾行数（1 到 5000，默认 200）。",
 	"cli.cmd.server.techLog.tail.from": "从上一次单次 JSON 结果的位置继续读取；必须同时传入 --log-file。",
 	"cli.cmd.server.techLog.tail.logFile": "使用上一次单次 JSON 结果中的日志文件；必须同时传入 --from。",
@@ -576,7 +588,7 @@
 	"cli.cmd.server.techLog.tail.interval": "设置跟随轮询间隔（毫秒，500 到 60000）；必须同时使用 --follow。",
 	"cli.cmd.server.techLog.tail.retry": "临时网络错误；第 {0} 次重试将在 {1} 毫秒后执行。",
 	"cli.cmd.server.techLog.download.summary": "下载技术日志文件。",
-	"cli.cmd.server.techLog.download.desc": "下载 'succapp server tech-log list' 返回的文件；需要控制台日志导出权限。",
+	"cli.cmd.server.techLog.download.desc": "下载 'succapp server tech-log list' 返回的文件；需要控制台日志导出权限。\n\n示例中的 NODE 应先赋值为 server cluster list 返回的节点 ID；LOG_FILE 应先赋值为该节点 tech-log list 返回的日志文件名。变量始终加双引号，避免空格或 shell 元字符改变参数。\n\n文件名来自同一节点的 tech-log list，--output 指定本地文件，覆盖已有文件需要 --force。此命令下载日志，不清理或轮转服务器日志。",
 	"cli.cmd.server.techLog.download.cluster": "从指定集群节点下载；省略时使用当前 HTTP 节点。运行 'succapp server cluster list' 获取节点名。",
 	"cli.cmd.server.techLog.download.file": "使用 'succapp server tech-log list' 返回的准确文件名。",
 	"cli.cmd.server.techLog.download.output": "将日志写入此本地文件。",
@@ -584,23 +596,23 @@
 	"cli.cmd.server.techLog.download.downloaded": "已将技术日志 {0} 下载到 {1}",
 	"cli.cmd.server.techLog.level.title": "技术日志级别",
 	"cli.cmd.server.techLog.level.summary": "查看和管理 logger 级别",
-	"cli.cmd.server.techLog.level.desc": "查看、持久化、热更新和重置 logger 级别；这些命令需要系统设置中控制台的查看权限。",
+	"cli.cmd.server.techLog.level.desc": "查看、持久化、热更新和重置 logger 级别；这些命令需要系统设置中控制台的查看权限。\n\nlist 对照保存值与实际生效值，set 修改一个 logger，reset 恢复继承，apply-to-cluster 下发完整配置。临时排障结束后应恢复合适级别。",
 	"cli.cmd.server.techLog.level.*.cluster": "修改指定集群节点；省略时使用当前 HTTP 节点。运行 'succapp server cluster list' 获取节点名。",
 	"cli.cmd.server.techLog.level.list.summary": "列出 logger 级别。",
-	"cli.cmd.server.techLog.level.list.desc": "列出目标节点持久化和实际生效的 logger 级别；需要控制台查看权限。",
+	"cli.cmd.server.techLog.level.list.desc": "列出目标节点持久化和实际生效的 logger 级别；需要控制台查看权限。\n\n示例中的 NODE 应先赋值为 server cluster list 返回的节点 ID；LOG_FILE 应先赋值为该节点 tech-log list 返回的日志文件名。变量始终加双引号，避免空格或 shell 元字符改变参数。\n\n对照显式配置和实际生效值判断继承结果；在集群中请指定或确认目标节点，不要由一个节点推断所有节点都一致。",
 	"cli.cmd.server.techLog.level.list.cluster": "从指定集群节点读取；省略时使用当前 HTTP 节点。运行 'succapp server cluster list' 获取节点名。",
 	"cli.cmd.server.techLog.level.set.summary": "设置 logger 级别。",
-	"cli.cmd.server.techLog.level.set.desc": "在目标节点持久化并热更新一个 logger 级别；需要控制台查看权限。",
+	"cli.cmd.server.techLog.level.set.desc": "在目标节点持久化并热更新一个 logger 级别；需要控制台查看权限。\n\n示例中的 NODE 应先赋值为 server cluster list 返回的节点 ID；LOG_FILE 应先赋值为该节点 tech-log list 返回的日志文件名。变量始终加双引号，避免空格或 shell 元字符改变参数。\n\nTRACE 和 DEBUG 必须加 --force，可能增加日志量和运行开销。修改后用 level list 核验；恢复继承用 reset，集群传播需另行执行 apply-to-cluster。",
 	"cli.cmd.server.techLog.level.set.force": "确认使用 TRACE 或 DEBUG，并已检查运行影响。",
 	"cli.cmd.server.techLog.level.set.logger": "使用准确的具名 logger；不能是 root，也不能包含通配符。",
 	"cli.cmd.server.techLog.level.set.level": "只能使用 TRACE、DEBUG、INFO 或 ERROR，且区分大小写。",
 	"cli.cmd.server.techLog.level.set.updated": "已将 logger {0} 更新为 {1}",
 	"cli.cmd.server.techLog.level.reset.summary": "重置具名 logger 级别。",
-	"cli.cmd.server.techLog.level.reset.desc": "删除 logger 的显式级别，使其继承父级；需要控制台查看权限。",
+	"cli.cmd.server.techLog.level.reset.desc": "删除 logger 的显式级别，使其继承父级；需要控制台查看权限。\n\n示例中的 NODE 应先赋值为 server cluster list 返回的节点 ID；LOG_FILE 应先赋值为该节点 tech-log list 返回的日志文件名。变量始终加双引号，避免空格或 shell 元字符改变参数。\n\n使用 logger 名称删除其显式配置。实际生效值取决于父级，reset 不等于关闭日志；完成后用 level list 查看结果。",
 	"cli.cmd.server.techLog.level.reset.logger": "使用准确的具名 logger；不能是 root，也不能包含通配符。",
 	"cli.cmd.server.techLog.level.reset.reset": "已重置 logger 级别：{0}",
 	"cli.cmd.server.techLog.level.apply.summary": "向集群应用 logger 级别。",
-	"cli.cmd.server.techLog.level.apply.desc": "向可达节点提交当前 HTTP 节点的完整 Logback 配置；需要控制台查看权限。成功仅表示已提交，不表示每个节点均处理成功。",
+	"cli.cmd.server.techLog.level.apply.desc": "向可达节点提交当前 HTTP 节点的完整 Logback 配置；需要控制台查看权限。成功仅表示已提交，不表示每个节点均处理成功。\n\n必须加 --force。下发的是当前 HTTP 节点的完整 Logback 配置，不只是刚修改的一个 logger；先核对来源配置，提交后逐节点检查实际生效值。",
 	"cli.cmd.server.techLog.level.apply.force": "确认替换可达集群节点的完整 Logback 配置。",
 	"cli.cmd.server.techLog.level.apply.applied": "已向集群提交 Logback 配置。",
 	"cli.cmd.server.techLog.out.file": "文件",
@@ -612,17 +624,17 @@
 	"cli.cmd.server.techLog.out.effectiveLevel": "生效级别",
 	"cli.cmd.server.proj.title": "服务器项目",
 	"cli.cmd.server.proj.summary": "查看服务器项目",
-	"cli.cmd.server.proj.desc": "查看服务器项目。",
+	"cli.cmd.server.proj.desc": "查看服务器项目。\n\nlist 查找当前用户可见项目，create 在服务器新建项目。下载到本地工作区使用 workspace project clone。",
 	"cli.cmd.server.proj.list.summary": "列出服务器项目。",
-	"cli.cmd.server.proj.list.desc": "列出服务器上的可见项目。",
+	"cli.cmd.server.proj.list.desc": "列出服务器上的可见项目。\n\n使用返回的项目名称继续查找文件或克隆。列表受当前用户权限影响；未列出不一定表示服务器上不存在该项目。",
 	"cli.cmd.server.proj.list.empty": "未找到可见项目。",
 	"cli.cmd.server.proj.create.summary": "创建服务器项目。",
-	"cli.cmd.server.proj.create.desc": "在服务器上创建元数据项目。",
+	"cli.cmd.server.proj.create.desc": "在服务器上创建元数据项目。\n\n传入新项目名称，可用 --desc 提供描述。创建直接影响服务器；完成后用 project list 核验，需要本地开发时再 clone。响应中断时先确认项目是否已经创建。",
 	"cli.cmd.server.proj.create.descOption": "设置项目描述。",
 	"cli.cmd.server.proj.create.created": "已创建服务器项目：{0}",
 	"cli.cmd.server.file.title": "服务器文件",
 	"cli.cmd.server.file.summary": "查看和操作服务器元数据文件",
-	"cli.cmd.server.file.desc": "查看和操作服务器元数据文件。",
+	"cli.cmd.server.file.desc": "查看和操作服务器元数据文件。\n\n先用 list/search/locate 定位路径，再用 info/show/history 检查。create/update/remove 直接修改远程元数据，不更新本地工作区；更新或删除前取得 revision，并在操作后核验。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：查找元数据文件\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/project/find-metafile.md\n网页：https://docs.succapp.com/ai-building/project/find-metafile",
 	"cli.cmd.server.file.*.file": "从本地文件读取内容。",
 	"cli.cmd.server.file.*.stdin": "从标准输入读取内容。",
 	"cli.cmd.server.file.badValue": "{0} 的值无效：{1}",
@@ -636,10 +648,10 @@
 	"cli.cmd.server.file.success": "{0} 成功：{1}",
 	"cli.cmd.server.file.unknownServerFile": "未知服务器文件错误。",
 	"cli.cmd.server.file.list.summary": "列出服务器文件。",
-	"cli.cmd.server.file.list.desc": "列出服务器元数据目录的直接子项。",
+	"cli.cmd.server.file.list.desc": "列出服务器元数据目录的直接子项。\n\n目录路径使用服务器元数据路径，返回直接子项。需要递归查找或按名称筛选时用 file search；路径包含空格时应加引号。",
 	"cli.cmd.server.file.list.empty": "目录为空：{0}",
 	"cli.cmd.server.file.search.summary": "搜索服务器文件。",
-	"cli.cmd.server.file.search.desc": "按完整路径，或按可组合的项目、父目录和文件名条件搜索可读取的服务器元数据文件。",
+	"cli.cmd.server.file.search.desc": "按完整路径，或按可组合的项目、父目录和文件名条件搜索可读取的服务器元数据文件。\n\n返回的完整路径可用于 info/show/download。多个筛选条件会缩小范围，--limit 限制返回条数；结果为空或达到上限时，应调整条件，不能据此断定资源不存在。",
 	"cli.cmd.server.file.search.url": "可选的服务器 URL。只传一个非 URL 参数时，该参数按 <query> 处理。",
 	"cli.cmd.server.file.search.query": "以 '/' 开头时按完整路径或路径 glob 搜索；包含 '*' 或 '?' 时按文件名 glob 搜索；其他输入按文件元数据关键词搜索。",
 	"cli.cmd.server.file.search.path": "按元数据绝对路径 glob 搜索，项目根路径默认递归搜索；可以与关键词 <query> 组合，不能与路径型 <query>、--project、--parent-dir 或 --name 组合。",
@@ -661,9 +673,9 @@
 	"cli.cmd.server.file.search.warningDetails": "正文未检查；请使用 --json 查看完整原因。",
 	"cli.cmd.server.recyclebin.title": "服务器回收站",
 	"cli.cmd.server.recyclebin.summary": "搜索服务器回收站文件",
-	"cli.cmd.server.recyclebin.desc": "搜索和查看服务器项目回收站中当前用户可见的已删除文件。",
+	"cli.cmd.server.recyclebin.desc": "搜索和查看服务器项目回收站中当前用户可见的已删除文件。\n\nsearch 按项目查询已删除资源，便于核对删除时间与路径。本组提供查询，不执行恢复或永久清理。",
 	"cli.cmd.server.recyclebin.search.summary": "搜索服务器回收站文件。",
-	"cli.cmd.server.recyclebin.search.desc": "按关键词、路径、类型或删除时间搜索项目回收站中当前用户可见的文件。",
+	"cli.cmd.server.recyclebin.search.desc": "按关键词、路径、类型或删除时间搜索项目回收站中当前用户可见的文件。\n\n必须明确项目，可组合筛选条件并用 --limit 限制数量。返回的是回收站记录，不能把其中路径当作当前仍存在的文件；需要恢复时使用产品对应的恢复操作。",
 	"cli.cmd.server.recyclebin.search.url": "可选的服务器 URL。第一个非 URL 参数按 <project> 处理。",
 	"cli.cmd.server.recyclebin.search.project": "要搜索回收站的项目名。",
 	"cli.cmd.server.recyclebin.search.query": "搜索关键词、完整元数据路径或路径 glob。",
@@ -674,86 +686,129 @@
 	"cli.cmd.server.recyclebin.search.empty": "项目 {0} 的回收站中没有匹配文件。",
 	"cli.cmd.server.recyclebin.search.hasMore": "仅显示 {0} 个回收站文件；请增加类型、删除时间范围或更准确的关键词来缩小范围。",
 	"cli.cmd.server.file.locate.summary": "根据元数据 ID 定位服务器文件。",
-	"cli.cmd.server.file.locate.desc": "把元数据 ID 解析为当前服务器文件路径。",
+	"cli.cmd.server.file.locate.desc": "把元数据 ID 解析为当前服务器文件路径。\n\n<id> 是服务器元数据 ID，不是文件名或本地路径。可用 --url 返回查看或编辑页面地址；得到路径后可继续使用 info/show。",
 	"cli.cmd.server.file.locate.url": "只打印服务器查看或编辑 URL。",
 	"cli.cmd.server.file.locate.viewUrl": "查看 URL：{0}",
 	"cli.cmd.server.file.locate.editUrl": "编辑 URL：{0}",
 	"cli.cmd.server.file.info.summary": "显示服务器文件信息。",
-	"cli.cmd.server.file.info.desc": "显示文件或目录的服务器端元数据。",
+	"cli.cmd.server.file.info.desc": "显示文件或目录的服务器端元数据。\n\n使用服务器元数据路径。结果中的 revision 可用于 update/remove 的 --expected-revision；提交前应基于最新内容准备修改，版本冲突时重新读取并比较。",
 	"cli.cmd.server.file.show.summary": "显示服务器文件内容。",
-	"cli.cmd.server.file.show.desc": "将服务器文件内容写入标准输出。查看可读文本时不要使用 --json；--json 会把内容按 Base64 包装给脚本使用。",
+	"cli.cmd.server.file.show.desc": "将服务器文件内容写入标准输出。查看可读文本时不要使用 --json；--json 会把内容按 Base64 包装给脚本使用。\n\n默认读取当前内容，--revision 读取历史版本；--upgrade-content 请求升级后的返回内容，不将升级结果写回服务器。保存到本地文件请用 download。",
 	"cli.cmd.server.file.show.revision": "读取服务器文件修订。",
 	"cli.cmd.server.file.show.upgradeContent": "支持时返回升级后的元数据 JSON 内容。",
 	"cli.cmd.server.file.download.summary": "下载服务器文件内容。",
-	"cli.cmd.server.file.download.desc": "将服务器文件内容下载到本地文件。",
+	"cli.cmd.server.file.download.desc": "将服务器文件内容下载到本地文件。\n\n必须用 --output 指定本地文件，覆盖已有文件需要 --force。可指定 --revision；--upgrade-content 只影响下载内容。下载不创建 workspace 同步基线。",
 	"cli.cmd.server.file.download.revision": "下载服务器文件的指定修订。",
 	"cli.cmd.server.file.download.upgradeContent": "支持时下载升级后的元数据 JSON 内容。",
 	"cli.cmd.server.file.download.output": "将内容写入本地文件。",
 	"cli.cmd.server.file.download.force": "如果本地输出文件已存在则覆盖。",
 	"cli.cmd.server.file.download.downloaded": "已下载 {0} 到 {1}",
 	"cli.cmd.server.file.open.summary": "打开服务器文件页面。",
-	"cli.cmd.server.file.open.desc": "在系统浏览器中打开服务器文件的查看或编辑页面，也可以只返回页面 URL 而不打开浏览器。",
+	"cli.cmd.server.file.open.desc": "在系统浏览器中打开服务器文件的查看或编辑页面，也可以只返回页面 URL 而不打开浏览器。\n\n默认打开查看页面，--edit 打开编辑页面。脚本或无桌面环境使用 --no-open 只返回 URL；此命令不上传内容。",
 	"cli.cmd.server.file.open.edit": "打开服务器编辑页面，而不是默认的查看页面。",
 	"cli.cmd.server.file.open.noOpen": "只返回页面 URL，不启动系统浏览器。",
 	"cli.cmd.server.file.open.path": "服务器元数据绝对路径。命令只构造页面 URL，不检查文件是否存在。",
 	"cli.cmd.server.file.open.openedEdit": "已打开服务器编辑页面：{0}",
 	"cli.cmd.server.file.open.openedView": "已打开服务器查看页面：{0}",
 	"cli.cmd.server.file.history.summary": "显示服务器文件历史。",
-	"cli.cmd.server.file.history.desc": "显示服务器文件路径的服务器端历史。",
+	"cli.cmd.server.file.history.desc": "显示服务器文件路径的服务器端历史。\n\n使用服务器路径，--limit 限制返回条数。结果是服务器保存的版本记录，可把 revision 用于 show/download；这不是本地 Git 历史。",
 	"cli.cmd.server.file.history.limit": "限制历史记录返回条数。",
 	"cli.cmd.server.file.create.summary": "创建服务器文件。",
-	"cli.cmd.server.file.create.desc": "创建服务器文件，若已存在则失败。",
+	"cli.cmd.server.file.create.desc": "创建服务器文件，若已存在则失败。\n\n--file 与 --stdin 必须且只能选择一个，内容直接写到目标服务器路径。已有目标不能用 create 覆盖；改用 update 并带修订保护。响应中断时先用 info/show 确认是否已创建。",
 	"cli.cmd.server.file.update.summary": "更新服务器文件。",
-	"cli.cmd.server.file.update.desc": "更新已有服务器文件，默认带修订保护。",
+	"cli.cmd.server.file.update.desc": "更新已有服务器文件，默认带修订保护。\n\n--file 与 --stdin 必须且只能选择一个；--expected-revision 与 --force 也必须且只能选择一个。优先使用 info 返回的 revision，冲突后重新读取比较；--force 跳过修订保护。写入后用 show 核验。",
 	"cli.cmd.server.file.update.expectedRevision": "仅当服务器修订仍匹配时更新。",
 	"cli.cmd.server.file.update.force": "不带修订保护覆盖当前服务器内容。",
 	"cli.cmd.server.file.remove.summary": "删除服务器文件。",
-	"cli.cmd.server.file.remove.desc": "删除已有服务器文件，默认带修订保护。",
+	"cli.cmd.server.file.remove.desc": "删除已有服务器文件，默认带修订保护。\n\n--expected-revision 与 --force 必须且只能选择一个。先用 info 确认目标和版本；--force 跳过修订保护。此操作直接删除服务器资源，不是移除本地副本，执行前确认引用和影响。",
 	"cli.cmd.server.file.remove.expectedRevision": "仅当服务器修订仍匹配时删除。",
 	"cli.cmd.server.file.remove.force": "不带修订保护删除当前服务器文件。",
 	"cli.cmd.server.ext.title": "服务器扩展",
 	"cli.cmd.server.ext.summary": "查看服务器扩展资源",
-	"cli.cmd.server.ext.desc": "查看服务器扩展资源。",
+	"cli.cmd.server.ext.desc": "查看服务器扩展资源。\n\n通过 template 查看服务器提供的扩展模板。本地创建与发布使用 workspace extension。",
 	"cli.cmd.server.ext.template.title": "服务器扩展模板",
 	"cli.cmd.server.ext.template.summary": "查看服务器扩展模板",
-	"cli.cmd.server.ext.template.desc": "查看服务器扩展模板。",
+	"cli.cmd.server.ext.template.desc": "查看服务器扩展模板。\n\nlist 返回可供本地扩展创建使用的扩展点和模板。模板由目标服务器提供，应与后续创建时的活跃服务器一致。",
 	"cli.cmd.server.ext.template.list.summary": "列出扩展模板。",
-	"cli.cmd.server.ext.template.list.desc": "列出服务器可用的扩展模板。",
+	"cli.cmd.server.ext.template.list.desc": "列出服务器可用的扩展模板。\n\n可用 --extension-point 限定扩展点。返回的扩展点和模板名称用于 workspace extension create；列出模板本身不会创建或安装扩展。",
 	"cli.cmd.server.ext.template.list.extensionPoint": "只列出指定扩展点的模板。",
 	"cli.cmd.server.script.title": "服务器脚本",
 	"cli.cmd.server.script.summary": "执行和检查服务器脚本",
-	"cli.cmd.server.script.desc": "执行和检查服务器脚本。",
+	"cli.cmd.server.script.desc": "执行和检查服务器脚本。\n\n先用 check 检查本地脚本，再用 exec 在服务器执行。检查成功不代表运行无副作用；脚本可以访问和修改服务器资源，执行前应核对内容和目标环境。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：复用和扩展业务逻辑\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/app/implement-business-logic.md\n网页：https://docs.succapp.com/ai-building/app/implement-business-logic#cli-script",
 	"cli.cmd.server.script.done": "脚本命令完成。",
 	"cli.cmd.server.script.invalidJsonInput": "JSON 输入文件无效：{0}",
 	"cli.cmd.server.script.exec.summary": "在服务器上执行本地脚本。",
-	"cli.cmd.server.script.exec.desc": "读取本地脚本文件，并在服务器支持时通过 Dev Tool v2 执行。",
+	"cli.cmd.server.script.exec.desc": "读取本地脚本文件，并在服务器支持时通过 Dev Tool v2 执行。\n\n<file> 指向本地脚本文件，--input 提供 JSON 输入文件，--param 可重复传入 key=value 参数。此命令执行真实服务器脚本，影响取决于脚本内容；响应中断时先核对实际结果，避免重复执行写入。\n\n脚本入口为 function main(args)，--input 的 JSON 从 args.input 读取，--param 的字符串键值从 args.params 读取。例如 main(args) 可返回 {mode: args.params.mode, input: args.input}；请先用 check 检查。",
 	"cli.cmd.server.script.exec.input": "从文件读取脚本输入。",
 	"cli.cmd.server.script.exec.param": "传入脚本参数，可重复。",
 	"cli.cmd.server.script.check.summary": "在服务器上检查本地脚本。",
-	"cli.cmd.server.script.check.desc": "读取本地脚本文件，并在服务器支持时通过 Dev Tool v2 编译。",
+	"cli.cmd.server.script.check.desc": "读取本地脚本文件，并在服务器支持时通过 Dev Tool v2 编译。\n\n<file> 指向本地脚本文件；检查需要目标服务器支持编译接口。此命令不执行脚本业务逻辑，检查通过也不保证运行时数据、权限和输入一定正确。",
 	"cli.cmd.server.settings.title": "服务器设置",
-	"cli.cmd.server.settings.summary": "获取和设置服务器设置",
-	"cli.cmd.server.settings.desc": "通过 Dev Tool v2 获取和设置系统、项目或应用级设置。",
+	"cli.cmd.server.settings.summary": "读取和修改服务器设置",
+	"cli.cmd.server.settings.desc": "直接读取或修改远程服务器的设置；写入后无需 workspace push，也不会更新本地文件。需要先在本地审查修改时，可克隆项目、编辑设置 JSON，再使用 workspace file diff 和 push。子命令用法见各命令的 --help。\n\nget 查看当前值；set 按顶层键修改；add/update/remove 操作指定设置列表的条目。系统、项目和应用的目标写法见子命令参数；修改前先读取，修改后再次 get 核验。\n\n需先审查本地修改时，使用 workspace file diff 和 workspace push。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：SuccApp CLI\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/basics/cli.md\n网页：https://docs.succapp.com/ai-building/basics/cli\n\n详细文档：系统设置列表字段与秘密值规则\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/basics/system-settings.md\n网页：https://docs.succapp.com/ai-building/basics/system-settings",
 	"cli.cmd.server.settings.target.system": "系统级",
+	"cli.cmd.server.settings.url": "远程服务器地址；也可使用 --server 或工作区当前服务器。",
+	"cli.cmd.server.settings.target": "system 表示系统设置；项目设置填写项目名（如 DEMO）；应用设置填写元数据绝对路径（如 /DEMO/app/demo.app），不是本地文件路径。",
+	"cli.cmd.server.settings.itemTarget": "系统列表别名：llms、sso、credentials、messagers、message-templates、encryption、masking。填写项目名或应用元数据绝对路径时，还需提供 --key。",
+	"cli.cmd.server.settings.add.item": "一个包含 id 的完整条目 JSON 对象，不要包裹在数组中。",
+	"cli.cmd.server.settings.update.item": "一个包含 id 的完整条目 JSON 对象，不要包裹在数组中。",
+	"cli.cmd.server.settings.add.file": "从本地文件读取一个包含 id 的完整条目 JSON 对象。",
+	"cli.cmd.server.settings.update.file": "从本地文件读取一个包含 id 的完整条目 JSON 对象。",
+	"cli.cmd.server.settings.add.stdin": "从标准输入读取一个包含 id 的完整条目 JSON 对象。",
+	"cli.cmd.server.settings.update.stdin": "从标准输入读取一个包含 id 的完整条目 JSON 对象。",
+	"cli.cmd.server.settings.remove.item": "条目 ID，或仅包含 id 的 JSON 对象，如 '{\"id\":\"service-1\"}'。",
+	"cli.cmd.server.settings.remove.file": "从本地文件读取条目 ID 或仅包含 id 的 JSON 对象。",
+	"cli.cmd.server.settings.remove.stdin": "从标准输入读取条目 ID 或仅包含 id 的 JSON 对象。",
 	"cli.cmd.server.settings.get.summary": "获取服务器设置。",
-	"cli.cmd.server.settings.get.desc": "读取系统、项目或应用级设置。省略 <target> 或传 system 读取系统级设置。",
+	"cli.cmd.server.settings.get.desc": "读取远程系统、项目或应用设置。省略 <target> 或传 system 读取系统设置。--key 使用完整顶层键名，点号属于键名，不表示嵌套路径。\n\n读取结果用于核对当前配置；涉及秘密的字段可能已脱敏，不要把脱敏占位值原样写回。需要修改一个列表条目时，先确认它的 id 和完整内容。\n\n系统列表读取键：llms→llm.services，sso→sso.providers，credentials→service.credentials，messagers→messaging.services，message-templates→messaging.templates，encryption→security.encryption.algorithms，masking→security.masking.rules。例如 get system --key security.masking.rules；不要把 masking 作为 get 的项目目标。",
 	"cli.cmd.server.settings.get.key": "只返回指定的一级 key，可重复。",
 	"cli.cmd.server.settings.get.header": "{0} 的设置：",
-	"cli.cmd.server.settings.set.summary": "设置服务器设置。",
-	"cli.cmd.server.settings.set.desc": "把增量设置合并到系统、项目或应用级设置。至少提供 --set、--file、--stdin 或 --unset 之一。",
-	"cli.cmd.server.settings.set.set": "内联增量 JSON，可一次设置多个顶层 key。",
-	"cli.cmd.server.settings.set.file": "从本地文件读取增量 JSON。",
-	"cli.cmd.server.settings.set.stdin": "从标准输入读取增量 JSON。",
+	"cli.cmd.server.settings.set.summary": "修改远程设置。",
+	"cli.cmd.server.settings.set.desc": "直接写入远程服务器，不修改本地文件，也无需 workspace push。只修改提交的顶层键；对象和数组整体替换，不递归合并，null 或 --unset 删除对应键。\n\nJSON 输入从 --set、--file、--stdin 中选择一种；--unset 可单独使用，也可与输入组合。使用完整配置键（如 system.name），不要改写成嵌套 JSON。修改对象或数组前先读取原值，保存后可再次 get 检查结果。\n\n可用 --expected-revision 进行并发保护；发生冲突时重新读取，合并实际需要的顶层修改后再提交。响应中断时先 get 核对，不要假定没有保存。\n\nget 不返回可直接用于并发保护的同快照设置修订；不要把文件 revision 或其它版本号猜作设置修订。条目 add/update/remove 也没有调用方修订参数。",
+	"cli.cmd.server.settings.set.set": "内联 JSON 对象，包含待修改键的完整值。",
+	"cli.cmd.server.settings.set.file": "读取本地文件中的 JSON 对象并提交到远端，不编辑或同步该文件。",
+	"cli.cmd.server.settings.set.stdin": "从标准输入读取设置 JSON。",
 	"cli.cmd.server.settings.set.unset": "删除指定的一级 key，可重复。",
-	"cli.cmd.server.settings.set.key": "只在指定的一级 key 下合并。",
+	"cli.cmd.server.settings.set.key": "把输入对象作为此键的完整值，而非一组配置项；不能与 --unset 同用。",
 	"cli.cmd.server.settings.set.expectedRevision": "仅当服务器设置版本仍匹配时写入。",
 	"cli.cmd.server.settings.set.success": "已更新 {0} 的设置：{1}",
 	"cli.cmd.server.settings.set.noKeys": "（无 key）",
+	"cli.cmd.server.settings.add.summary": "新增设置条目。",
+	"cli.cmd.server.settings.add.key": "列表所在的完整顶层键名；<target> 不是系统列表别名时必填。",
+	"cli.cmd.server.settings.add.desc": "向远程设置列表新增完整条目。--item、--file、--stdin 必须且只能选择一种，JSON 对象需包含新 id 及该类型的必填字段；无需 workspace push。\n\n先 get 核对列表和已有 id，避免重复新增；提交后再次读取确认条目。请求响应中断时先确认是否已新增，再决定是否重试。\n\n各列表的结构和必填字段请按 get 中的列表键，查阅对应系统设置说明；已有同类型条目可作结构参考，但新条目必须使用新的 id。\n\n详细文档：系统设置列表字段与秘密值规则\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/basics/system-settings.md\n网页：https://docs.succapp.com/ai-building/basics/system-settings",
+	"cli.cmd.server.settings.add.success": "已向 {0} 新增条目 {1}。",
+	"cli.cmd.server.settings.update.summary": "修改设置条目。",
+	"cli.cmd.server.settings.update.key": "列表所在的完整顶层键名；<target> 不是系统列表别名时必填。",
+	"cli.cmd.server.settings.update.desc": "直接替换远程设置列表中的一条配置，无需 workspace push。先读取列表，例如 server settings get system --key security.masking.rules，再通过 --item、--file 或 --stdin 提交包含原 id 的完整条目；未提交的条目字段不会保留。\n\n修改时保留完整条目中仍需要的字段，尤其是对象和数组。保存后重新读取核对；响应中断时检查当前条目再重试。\n\n详细文档：系统设置列表字段与秘密值规则\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/basics/system-settings.md\n网页：https://docs.succapp.com/ai-building/basics/system-settings",
+	"cli.cmd.server.settings.update.success": "已修改 {0} 中的条目 {1}。",
+	"cli.cmd.server.settings.remove.summary": "删除设置条目。",
+	"cli.cmd.server.settings.remove.key": "列表所在的完整顶层键名；<target> 不是系统列表别名时必填。",
+	"cli.cmd.server.settings.remove.desc": "直接删除远程设置列表中的一条配置，无需 workspace push。--item、--file、--stdin 必须且只能选择一种，内容为条目 ID 或仅包含 id 的 JSON 对象。\n\n先 get 核对条目 id 和用途，删除会直接影响服务器配置。提交后再次读取确认；要删除整个顶层设置键，应使用 set --unset。",
+	"cli.cmd.server.settings.remove.success": "已从 {0} 删除条目 {1}。",
+	"cli.cmd.server.settings.*.module": "系统设置列表模块。",
+	"cli.cmd.server.settings.*.item": "内联完整条目 JSON；删除时也可传条目 ID。",
+	"cli.cmd.server.settings.*.file": "从本地文件读取条目 JSON 或 ID。",
+	"cli.cmd.server.settings.*.stdin": "从标准输入读取条目 JSON 或 ID。",
+	"cli.cmd.server.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
+	"cli.cmd.server.file.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
+	"cli.cmd.server.file.*.path": "服务器元数据路径，例如 /DEMO/ana/sales.dash，不是本地文件路径。",
+	"cli.cmd.server.file.*.id": "元数据 ID，可从 server file info 的文件信息取得。",
+	"cli.cmd.server.cache.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
+	"cli.cmd.server.cache.clean.name": "server cache list 返回的缓存名；与 --all 二选一。",
+	"cli.cmd.server.cluster.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
+	"cli.cmd.server.cluster.*.nodeId": "server cluster list 返回的节点 ID。",
+	"cli.cmd.server.thread.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
+	"cli.cmd.server.thread.*.threadId": "同一节点上 server thread list 返回的线程 ID；使用前应重新核对。",
+	"cli.cmd.server.techLog.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
+	"cli.cmd.server.proj.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
+	"cli.cmd.server.script.*.file": "本地脚本文件；相对路径基于 CLI 启动目录，-C 不改变此基准。",
+	"cli.cmd.server.techLog.level.*.url": "目标服务器 URL；优先于 --server、工作区活跃服务器和 SUCCAPP_SERVER。",
+	"cli.cmd.server.proj.create.project": "新项目名称；已有项目可用 server project list 查询。",
 	"cli.cmd.workspace.title": "工作区",
 	"cli.cmd.workspace.summary": "使用本地 SuccApp 工作区",
-	"cli.cmd.workspace.desc": "使用本地 SuccApp 工作区。",
+	"cli.cmd.workspace.desc": "使用本地 SuccApp 工作区。\n\n在已初始化的目录运行，或用 -C 指定工作区。先通过 remote 确认活跃服务器，再用 project clone 获取项目；修改后按 status、file diff、push 的顺序检查和提交。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：初始化工作区\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/init-workspace.md\n网页：https://docs.succapp.com/ai-building/workspace/init-workspace",
 	"cli.cmd.workspace.init.summary": "初始化 SuccApp 工作区。",
-	"cli.cmd.workspace.init.desc": "初始化 .succapp/config.json、推荐的工作区辅助文件和可选的 SuccApp 官方离线文档 skill。",
+	"cli.cmd.workspace.init.desc": "初始化 .succapp/config.json、推荐的工作区辅助文件和可选的 SuccApp 官方离线文档 skill。\n\n目标目录必须已经存在。可用 --scope 选择初始化内容；重新执行会按现有配置处理，不应当作清空重建。连接服务器和获取离线资料可能需要网络与认证，完成后检查输出中的 updated、skipped 和资料状态。\n\nscope 默认 all：base 维护工作区配置、编辑器设置、忽略规则和 Agent 文件；dev 维护本地类型与 JSON Schema；agent-docs 安装或更新官方文档 skill。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：初始化工作区\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/init-workspace.md\n网页：https://docs.succapp.com/ai-building/workspace/init-workspace",
 	"cli.cmd.workspace.init.server": "使用该活跃服务器初始化工作区。",
 	"cli.cmd.workspace.init.scope": "限制初始化范围。可选值：base、dev、agent-docs、all。",
 	"cli.cmd.workspace.init.force": "即使索引未变化，也强制 SuccApp 官方离线文档 skill 检查本地文件。",
@@ -770,25 +825,25 @@
 	"cli.cmd.workspace.init.supportFiles": "工作区辅助文件：已更新 {0} 项，已跳过 {1} 项。",
 	"cli.cmd.workspace.init.workspaceInit": "工作区已初始化：{0}",
 	"cli.cmd.workspace.status.summary": "显示工作区同步状态。",
-	"cli.cmd.workspace.status.desc": "显示工作区同步状态。",
+	"cli.cmd.workspace.status.desc": "显示工作区同步状态。\n\n默认检查本地与远端变化；--local-only 只检查本地，--force-refresh 重新校准远端缓存。先检查退出码、remoteCheck 和 warnings，再判断 changes。remoteCheck=complete 才表示本次远端检查完成，skipped 表示主动跳过；failed/cancelled 表示检查不完整，返回非零退出码。失败时可能保留上次远端变化，空结果也不能证明远端没有变化。\n\n认证失败先运行 auth login；连接失败先检查目标地址与网络，再运行 workspace status --force-refresh 重新核验。修复前不要把本次结果当作推送前的完整检查。",
 	"cli.cmd.workspace.status.forceRefresh": "重新检查服务器变化，不使用本地缓存的状态。",
 	"cli.cmd.workspace.status.localOnly": "只显示本地工作区变化，不检查服务器。",
 	"cli.cmd.workspace.status.remoteAuthRequired": "当前未登录，已只显示本地变化。请先执行 'succapp auth login'，再重试查看服务器变化。",
 	"cli.cmd.workspace.upgrade.summary": "规划工作区结构迁移。",
-	"cli.cmd.workspace.upgrade.desc": "规划 SuccApp 工作区结构迁移。当前实现没有迁移项。",
+	"cli.cmd.workspace.upgrade.desc": "规划 SuccApp 工作区结构迁移。当前实现没有迁移项。\n\n此命令针对工作区结构，不是元数据文件版本。升级旧版元数据请使用 workspace file upgrade；查看 CLI 自身版本使用 succapp --version。",
 	"cli.cmd.workspace.upgrade.targetVersion": "规划到目标工作区结构版本的迁移。",
 	"cli.cmd.workspace.upgrade.dryRun": "预览迁移计划，不修改文件。",
 	"cli.cmd.workspace.upgrade.actions": "工作区升级：{0} 个动作。当前={1}，目标={2}。",
 	"cli.cmd.workspace.upgrade.noActions": "工作区升级：无动作。当前={0}，目标={1}。",
 	"cli.cmd.workspace.pull.summary": "将服务器变化拉取到工作区。",
-	"cli.cmd.workspace.pull.desc": "把活跃服务器上的变化应用到当前工作区。",
+	"cli.cmd.workspace.pull.desc": "把活跃服务器上的变化应用到当前工作区。\n\n可用路径限制范围，省略路径时处理当前同步范围。拉取会修改本地文件并可能合并变化；先查看 status 和 file diff，出现冲突后检查结果再处理，勿把 --force 当作普通重试。\n\n省略路径处理全部对应变化。结果即使是 kind=result，存在 conflicts 时仍退出 6；先核对 updated、deleted、conflicts 和 oldFiles，再用 backup list 查看保存的本地版本。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：修改、对比、拉取与推送\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/sync-changes.md\n网页：https://docs.succapp.com/ai-building/workspace/sync-changes",
 	"cli.cmd.workspace.pull.force": "允许服务器变化覆盖本地修改。",
 	"cli.cmd.workspace.pull.conflicts": "冲突：{0}",
 	"cli.cmd.workspace.pull.oldMeta": "旧版元数据文件：{0}",
 	"cli.cmd.workspace.pull.pullResultUpdated": "Pull 结果：更新 {0}，删除 {1}，冲突 {2}",
 	"cli.cmd.workspace.pull.upDate": "已是最新，无需拉取",
 	"cli.cmd.workspace.push.summary": "将工作区变化提交到服务器。",
-	"cli.cmd.workspace.push.desc": "把本地工作区变化提交到活跃服务器。",
+	"cli.cmd.workspace.push.desc": "把本地工作区变化提交到活跃服务器。\n\n可用路径限制范围；先检查 status 和 file diff，确认本地修改与活跃服务器。推送会写入远程元数据，--force 会跳过部分冲突保护；失败或断连后先刷新状态，避免盲目重试。\n\n省略路径处理全部对应本地变化。完成后重新查看 status；不要只看到结果对象就忽略失败项或非零退出码。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：修改、对比、拉取与推送\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/sync-changes.md\n网页：https://docs.succapp.com/ai-building/workspace/sync-changes",
 	"cli.cmd.workspace.push.force": "允许本地变化覆盖远端变化。",
 	"cli.cmd.workspace.push.failed": "失败文件：{0}",
 	"cli.cmd.workspace.push.kind": "类别",
@@ -800,14 +855,14 @@
 	"cli.cmd.workspace.push.targetVersion": "目标版本",
 	"cli.cmd.workspace.push.version": "当前版本",
 	"cli.cmd.workspace.discard.summary": "放弃工作区本地变化。",
-	"cli.cmd.workspace.discard.desc": "用本地 mirror 基线恢复工作区文件，并放弃本地变化。",
+	"cli.cmd.workspace.discard.desc": "用本地 mirror 基线恢复工作区文件，并放弃本地变化。\n\n指定路径会放弃该范围的本地改动；不指定路径必须用 --force 确认全范围操作。mirror 是本地同步基线，可能不是服务器最新版本；丢弃前先检查差异并保存需要保留的修改。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：修改、对比、拉取与推送\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/sync-changes.md\n网页：https://docs.succapp.com/ai-building/workspace/sync-changes",
 	"cli.cmd.workspace.discard.force": "不指定路径时，确认放弃整个工作区的本地变化。",
 	"cli.cmd.workspace.discard.deletedFiles": "已删除文件：{0}",
 	"cli.cmd.workspace.discard.noLocalChanges": "没有本地变更需要放弃",
 	"cli.cmd.workspace.discard.restoredFiles": "已恢复文件：{0}",
 	"cli.cmd.workspace.discard.result": "放弃结果：已恢复 {0}，已删除 {1}",
 	"cli.cmd.workspace.repair.summary": "检查或修复工作区一致性问题。",
-	"cli.cmd.workspace.repair.desc": "检查或修复可自动处理的工作区结构和同步状态问题。",
+	"cli.cmd.workspace.repair.desc": "检查或修复可自动处理的工作区结构和同步状态问题。\n\n先用 --dry-run 查看检查结果，必要时用 --only 缩小范围，再执行修复。修复可能更新辅助文件或同步状态；它不替代业务文件冲突处理，完成后重新查看 status。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：如何校验元数据文件的合法性\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/troubleshoot/metadata-validation.md\n网页：https://docs.succapp.com/ai-building/troubleshoot/metadata-validation",
 	"cli.cmd.workspace.repair.only": "只运行指定的工作区修复检查项。",
 	"cli.cmd.workspace.repair.dryRun": "预演可修复的工作区问题，不修改文件。",
 	"cli.cmd.workspace.repair.badCheck": "工作区修复检查项无效：{0}",
@@ -824,43 +879,43 @@
 	"cli.cmd.workspace.repair.unresolved": "未解决问题：",
 	"cli.cmd.workspace.proj.title": "工作区项目",
 	"cli.cmd.workspace.proj.summary": "管理工作区项目",
-	"cli.cmd.workspace.proj.desc": "管理工作区项目。",
+	"cli.cmd.workspace.proj.desc": "管理工作区项目。\n\nlist 查看本地项目，clone 从活跃服务器下载项目，remove 移除本地项目和基线。查看服务器有哪些项目使用 succapp server project list。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：连接服务器与克隆项目\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/connect-and-clone.md\n网页：https://docs.succapp.com/ai-building/workspace/connect-and-clone",
 	"cli.cmd.workspace.proj.list.summary": "列出本地工作区项目。",
-	"cli.cmd.workspace.proj.list.desc": "列出本地工作区项目。",
+	"cli.cmd.workspace.proj.list.desc": "列出本地工作区项目。\n\n同时显示工作目录与 mirror 基线中发现的项目，便于识别缺失的一侧。这不是服务器项目清单；需要远程列表时使用 server project list。",
 	"cli.cmd.workspace.proj.list.empty": "当前工作区没有跟踪项目。",
 	"cli.cmd.workspace.proj.clone.summary": "克隆服务器项目到工作区。",
-	"cli.cmd.workspace.proj.clone.desc": "从活跃服务器克隆项目到当前工作区。",
+	"cli.cmd.workspace.proj.clone.desc": "从活跃服务器克隆项目到当前工作区。\n\n先确认活跃服务器和项目名称。已有本地项目或基线时需要 --force 确认覆盖；克隆会写入工作目录和基线，应先保存本地修改。完成后检查输出中的旧版元数据提示。\n\n省略项目名会克隆全部可见项目。尚无活跃服务器时，可通过 --server 指定并登记首次克隆目标；已有活跃服务器后，--server 必须与其一致。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：连接服务器与克隆项目\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/connect-and-clone.md\n网页：https://docs.succapp.com/ai-building/workspace/connect-and-clone",
 	"cli.cmd.workspace.proj.clone.force": "允许 clone 覆盖已有本地工作区项目。",
 	"cli.cmd.workspace.proj.clone.configuredActive": "已配置活跃服务器：{0}",
 	"cli.cmd.workspace.proj.clone.cloned": "已克隆项目：{0}",
 	"cli.cmd.workspace.proj.clone.oldMetaNotice": "注意：{count} 个元数据文件使用较旧格式。\n可选：执行 '{command}' 可将它们升级为新版格式。\n这可能会更新很多文件；如需确认影响范围，可先加 `--dry-run` 预演。\n如果只是查看项目，可以先跳过这一步。",
 	"cli.cmd.workspace.proj.remove.summary": "移除工作区项目。",
-	"cli.cmd.workspace.proj.remove.desc": "移除本地工作区项目和 mirror 基线，不删除服务器项目。",
+	"cli.cmd.workspace.proj.remove.desc": "移除本地工作区项目和 mirror 基线，不删除服务器项目。\n\n必须用 --force 确认，可一次指定多个项目。未推送的本地修改和该项目的同步基线会被移除；需要保留的内容应先另行保存，之后可从服务器重新 clone。",
 	"cli.cmd.workspace.proj.remove.force": "确认删除本地项目文件和 mirror 基线。",
 	"cli.cmd.workspace.proj.remove.removed": "已移除工作区项目：{0}",
 	"cli.cmd.workspace.remote.title": "工作区远程服务器",
 	"cli.cmd.workspace.remote.summary": "管理工作区远程服务器",
-	"cli.cmd.workspace.remote.desc": "管理工作区远程服务器。",
+	"cli.cmd.workspace.remote.desc": "管理工作区远程服务器。\n\n这些命令管理本地工作区配置，认证另用 auth。切换或修改地址前应确认服务器身份，后续同步将按活跃服务器执行。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：连接服务器与克隆项目\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/connect-and-clone.md\n网页：https://docs.succapp.com/ai-building/workspace/connect-and-clone",
 	"cli.cmd.workspace.remote.list.summary": "列出已配置服务器。",
-	"cli.cmd.workspace.remote.list.desc": "列出当前工作区已配置的服务器。",
+	"cli.cmd.workspace.remote.list.desc": "列出当前工作区已配置的服务器。\n\n查看 active 标记确认后续同步的目标；列表来自本地配置，不表示服务器当前在线或认证有效。",
 	"cli.cmd.workspace.remote.add.summary": "添加服务器并设为活跃服务器。",
-	"cli.cmd.workspace.remote.add.desc": "将服务器添加到当前 SuccApp 工作区，并设为活跃服务器。",
+	"cli.cmd.workspace.remote.add.desc": "将服务器添加到当前 SuccApp 工作区，并设为活跃服务器。\n\n<url> 是服务器访问地址，添加后会改变当前同步目标。认证通过 auth login 配置；添加配置本身不会克隆项目。",
 	"cli.cmd.workspace.remote.add.active": "活跃服务器：{0}",
 	"cli.cmd.workspace.remote.use.summary": "切换活跃服务器。",
-	"cli.cmd.workspace.remote.use.desc": "切换当前工作区的活跃服务器。",
+	"cli.cmd.workspace.remote.use.desc": "切换当前工作区的活跃服务器。\n\n<url> 必须对应已配置服务器。切换后先用 remote list 和 status 核对；此操作不把当前工作目录自动替换成新服务器内容。",
 	"cli.cmd.workspace.remote.use.active": "活跃服务器：{0}",
 	"cli.cmd.workspace.remote.setUrl.summary": "修改已配置服务器地址。",
-	"cli.cmd.workspace.remote.setUrl.desc": "修改已配置服务器地址并迁移本地 mirror key。",
+	"cli.cmd.workspace.remote.setUrl.desc": "修改已配置服务器地址并迁移本地 mirror key。\n\n用于同一服务器访问地址变更，需同时提供旧地址和新地址。它会改本地配置和基线索引，不应作为把项目迁移到另一台独立服务器的方法；随后核对 remote list 和认证状态。",
 	"cli.cmd.workspace.remote.setUrl.changed": "服务器地址已变更：{0} -> {1}",
 	"cli.cmd.workspace.remote.remove.summary": "移除已配置服务器。",
-	"cli.cmd.workspace.remote.remove.desc": "从当前工作区配置中移除服务器。",
+	"cli.cmd.workspace.remote.remove.desc": "从当前工作区配置中移除服务器。\n\n<url> 必须是已配置地址。移除后检查 remote list，确认剩余活跃目标；此命令不删除远程服务器或项目，删除本地认证另用 auth logout。",
 	"cli.cmd.workspace.remote.remove.active": "已移除服务器：{0}\n活跃服务器：{1}",
 	"cli.cmd.workspace.remote.remove.removed": "已移除服务器：{0}",
 	"cli.cmd.workspace.file.title": "工作区文件",
 	"cli.cmd.workspace.file.summary": "查看工作区文件",
-	"cli.cmd.workspace.file.desc": "查看工作区文件。",
+	"cli.cmd.workspace.file.desc": "查看工作区文件。\n\nresolve 查看路径映射，show/history 读取服务器或基线信息，diff 对比本地与服务器，compile/upgrade 检查和升级本地元数据，open 打开服务器页面。修改本地文件后仍需 push 才能同步。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：修改、对比、拉取与推送\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/workspace/sync-changes.md\n网页：https://docs.succapp.com/ai-building/workspace/sync-changes",
 	"cli.cmd.workspace.file.resolve.summary": "解析工作区文件路径。",
-	"cli.cmd.workspace.file.resolve.desc": "解析工作区文件的本地路径、远程路径和浏览器 URL。",
+	"cli.cmd.workspace.file.resolve.desc": "解析工作区文件的本地路径、远程路径和浏览器 URL。\n\n传入工作区文件路径，查看解析出的 localPath 和 remotePath；可用 --url 选择查看或编辑链接。此命令只解析目标，不上传文件或打开浏览器。",
 	"cli.cmd.workspace.file.resolve.url": "human 模式仅打印查看或编辑 URL。",
 	"cli.cmd.workspace.file.resolve.badUrl": "--url 的值无效：{0}",
 	"cli.cmd.workspace.file.resolve.editUrl": "编辑 URL：{0}",
@@ -869,7 +924,7 @@
 	"cli.cmd.workspace.file.resolve.remote": "远程路径：{0}",
 	"cli.cmd.workspace.file.resolve.viewUrl": "查看 URL：{0}",
 	"cli.cmd.workspace.file.open.summary": "打开服务器文件页面。",
-	"cli.cmd.workspace.file.open.desc": "打开当前工作区文件的服务器查看或编辑页面，也可以只返回页面 URL 而不打开浏览器。",
+	"cli.cmd.workspace.file.open.desc": "打开当前工作区文件的服务器查看或编辑页面，也可以只返回页面 URL 而不打开浏览器。\n\n默认打开查看页面，--edit 打开编辑页面，--no-open 只返回 URL。页面使用服务器上的内容；本地有修改时需 --force 确认，但 --force 不会自动推送本地修改。",
 	"cli.cmd.workspace.file.open.edit": "打开服务器编辑页面，而不是默认的查看页面。",
 	"cli.cmd.workspace.file.open.noOpen": "只返回页面 URL，不启动系统浏览器。",
 	"cli.cmd.workspace.file.open.path": "工作区相对文件路径或服务器元数据绝对路径。",
@@ -878,21 +933,21 @@
 	"cli.cmd.workspace.file.open.openedEdit": "已打开服务器编辑页面：{0}",
 	"cli.cmd.workspace.file.open.openedView": "已打开服务器查看页面：{0}",
 	"cli.cmd.workspace.file.show.summary": "显示文件内容。",
-	"cli.cmd.workspace.file.show.desc": "显示文件内容。",
+	"cli.cmd.workspace.file.show.desc": "读取服务器或本地 mirror 基线中的文件内容。\n\n默认读取服务器内容；--source=mirror 读取本地基线。--revision 仅适用于服务器来源。普通输出是原始内容，JSON 内容使用 Base64；这不是直接读取当前工作目录中的文件。",
 	"cli.cmd.workspace.file.show.source": "从 mirror 或服务器读取。",
 	"cli.cmd.workspace.file.show.revision": "读取服务器历史版本。",
 	"cli.cmd.workspace.file.show.badRev": "--revision 的值无效：{0}",
 	"cli.cmd.workspace.file.show.badSource": "--source 的值无效：{0}",
 	"cli.cmd.workspace.file.show.revSource": "--revision 只支持和 --source=server 一起使用。",
 	"cli.cmd.workspace.file.diff.summary": "显示工作区文件与服务器内容的差异。",
-	"cli.cmd.workspace.file.diff.desc": "对比本地工作区元数据文件和服务器内容。可以传入文件、目录（递归目录下所有文件）或 glob。",
+	"cli.cmd.workspace.file.diff.desc": "对比本地工作区元数据文件和服务器内容。可以传入文件、目录（递归目录下所有文件）或 glob。\n\nglob 建议加引号，交给 CLI 展开。输出用于审查差异，不修改本地或服务器文件；要判断整个同步范围是否存在冲突，可结合 workspace status。",
 	"cli.cmd.workspace.file.diff.source": "与服务器内容比较。",
 	"cli.cmd.workspace.file.diff.badSource": "--source 的值无效：{0}",
 	"cli.cmd.workspace.file.history.summary": "显示服务器文件历史。",
-	"cli.cmd.workspace.file.history.desc": "显示当前工作区文件的服务器端历史。",
+	"cli.cmd.workspace.file.history.desc": "显示当前工作区文件的服务器端历史。\n\n通过工作区路径定位活跃服务器上的文件，可用 --limit 限制条数。历史来自服务器，不是本地 Git 历史；读取指定版本内容使用 file show --revision。",
 	"cli.cmd.workspace.file.history.limit": "限制历史记录返回条数。",
 	"cli.cmd.workspace.file.compile.summary": "校验工作区元数据文件。",
-	"cli.cmd.workspace.file.compile.desc": "校验本地工作区元数据文件。可以传入文件、目录（递归目录下所有文件）或 glob。",
+	"cli.cmd.workspace.file.compile.desc": "校验本地工作区元数据文件。可以传入文件、目录（递归目录下所有文件）或 glob。\n\nglob 建议加引号。校验可能访问服务器取得版本信息或执行编译检查，但不会 push 本地修改；检查结果中的失败和跳过项，成功也不代表已验证业务运行效果。\n\n退出 0 仍可能包含 skipped 项；请检查 skipped/skipReason，不能把跳过当成校验通过。",
 	"cli.cmd.workspace.file.compile.compiler": "编译器",
 	"cli.cmd.workspace.file.compile.done": "已完成 {0} 个工作区元数据文件的编译校验。",
 	"cli.cmd.workspace.file.compile.failed": "失败文件：{0}",
@@ -904,7 +959,7 @@
 	"cli.cmd.workspace.file.compile.skipped": "跳过文件：{0}",
 	"cli.cmd.workspace.file.compile.upgradeRequired": "{0} 个文件需要先升级。请使用相同的 pathspec 执行 `{1}`，升级完成后重新校验。",
 	"cli.cmd.workspace.file.upgrade.summary": "升级旧版 SuccApp 元数据文件。",
-	"cli.cmd.workspace.file.upgrade.desc": "预演或升级本地工作区旧版 SuccApp 元数据文件。可以传入文件、目录（递归目录下所有文件）或 glob；不传时处理所有本地项目。",
+	"cli.cmd.workspace.file.upgrade.desc": "预演或升级本地工作区旧版 SuccApp 元数据文件。可以传入文件、目录（递归目录下所有文件）或 glob；不传时处理所有本地项目。\n\n先用 --dry-run 查看候选项和失败项，再执行实际升级。实际执行会修改本地文件；升级后检查 diff、运行校验，再决定是否 push。",
 	"cli.cmd.workspace.file.upgrade.dryRun": "预演升级候选文件，不修改文件。",
 	"cli.cmd.workspace.file.upgrade.cands": "升级候选文件：{0}",
 	"cli.cmd.workspace.file.upgrade.dryRunRes": "元数据升级 dry-run：已检查 {0}，候选 {1}，跳过 {2}，失败 {3}",
@@ -915,52 +970,67 @@
 	"cli.cmd.workspace.file.upgrade.upgraded": "已升级文件：{0}",
 	"cli.cmd.workspace.lock.title": "工作区锁",
 	"cli.cmd.workspace.lock.summary": "查看工作区锁",
-	"cli.cmd.workspace.lock.desc": "查看工作区锁。",
+	"cli.cmd.workspace.lock.desc": "查看工作区锁。\n\nlist 只列占用范围，status 查看指定范围状态，wait 等待释放。这些命令用于诊断并发操作，不强制删除锁或终止持锁进程。",
 	"cli.cmd.workspace.lock.badScope": "workspace 锁范围无效：{0}",
 	"cli.cmd.workspace.lock.list.summary": "列出当前被锁定的工作区范围。",
-	"cli.cmd.workspace.lock.list.desc": "列出当前 SuccApp 工作区中已被锁定的范围。",
+	"cli.cmd.workspace.lock.list.desc": "列出当前 SuccApp 工作区中已被锁定的范围。\n\n输出可用于识别持锁进程和范围；空列表表示当前未读到有效持锁记录。状态可能随其它进程变化，不构成下一次写入已获锁的保证。",
 	"cli.cmd.workspace.lock.list.scope": "范围",
 	"cli.cmd.workspace.lock.list.empty": "当前没有被占用的工作区锁。",
 	"cli.cmd.workspace.lock.status.summary": "显示工作区锁持有者。",
-	"cli.cmd.workspace.lock.status.desc": "工作区锁状态",
+	"cli.cmd.workspace.lock.status.desc": "查看工作区锁范围及持有者。\n\n可指定一个或多个 scope，省略时查看全部范围。free/busy 是查询时的状态；需要等待空闲请用 lock wait，后续操作仍需自行获取锁。",
 	"cli.cmd.workspace.lock.status.heartbeat": "最近心跳",
 	"cli.cmd.workspace.lock.status.pid": "PID",
 	"cli.cmd.workspace.lock.status.scope": "范围",
 	"cli.cmd.workspace.lock.wait.summary": "等待工作区锁空闲。",
-	"cli.cmd.workspace.lock.wait.desc": "等待指定工作区锁范围空闲。",
+	"cli.cmd.workspace.lock.wait.desc": "等待指定工作区锁范围空闲。\n\n省略 scope 时等待 config 和 sync；--timeout 单位为秒，不传则持续等待。成功只表示检查时空闲，不会持有锁；超时返回非零退出码，脚本应处理此结果。\n\n超时退出码为 124。",
 	"cli.cmd.workspace.lock.wait.timeout": "达到指定秒数后停止等待。",
 	"cli.cmd.workspace.lock.wait.badTimeout": "--timeout 的值无效：{0}",
 	"cli.cmd.workspace.lock.wait.locksBusy": "等待 {0} 秒后工作区锁仍被占用：{1}",
 	"cli.cmd.workspace.lock.wait.locksFree": "工作区锁已空闲：{0}",
 	"cli.cmd.workspace.backup.title": "工作区备份",
 	"cli.cmd.workspace.backup.summary": "查看和清理工作区备份",
-	"cli.cmd.workspace.backup.desc": "查看和清理工作区备份。",
+	"cli.cmd.workspace.backup.desc": "查看和清理工作区备份。\n\nlist 查看拉取冲突前保存的本地版本，clear 清理这些备份。它们不是工作区所有文件的完整备份，也不替代 Git 历史。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：不小心把我的修改搞丢了，怎么找回来\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/troubleshoot/recover-lost-changes.md\n网页：https://docs.succapp.com/ai-building/troubleshoot/recover-lost-changes",
 	"cli.cmd.workspace.backup.backupPath": "备份路径",
 	"cli.cmd.workspace.backup.cleared": "合并备份清理：已清理 {0}，剩余 {1}。",
 	"cli.cmd.workspace.backup.list.summary": "列出已保存的合并备份。",
-	"cli.cmd.workspace.backup.list.desc": "列出拉取冲突处理前保存的本地版本。",
+	"cli.cmd.workspace.backup.list.desc": "列出拉取冲突处理前保存的本地版本。\n\n可按路径限定范围。先确认备份对应的原文件和保存位置，再决定是否恢复或清理；列表不会自动还原文件。",
 	"cli.cmd.workspace.backup.list.empty": "未找到合并备份。",
 	"cli.cmd.workspace.backup.clear.summary": "清理已保存的合并备份。",
-	"cli.cmd.workspace.backup.clear.desc": "清理由拉取冲突处理前保存的本地版本。",
+	"cli.cmd.workspace.backup.clear.desc": "清理拉取冲突处理前保存的本地版本。\n\n可按路径限定范围，省略路径会清理全部此类备份，无需额外 --force。清理前先用 list 核对并保存仍需恢复的内容；清理不会修改当前工作文件或远程文件。",
 	"cli.cmd.workspace.ext.title": "工作区扩展",
 	"cli.cmd.workspace.ext.summary": "创建和发布工作区扩展",
-	"cli.cmd.workspace.ext.desc": "创建和发布工作区扩展。",
+	"cli.cmd.workspace.ext.desc": "创建和发布工作区扩展。\n\nlist 查看本地扩展，create 从模板生成本地目录，push 将扩展发布到活跃服务器。创建前可通过 server extension template list 查找可用模板。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：扩展开发\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/extension/extension.md\n网页：https://docs.succapp.com/ai-building/extension/extension",
 	"cli.cmd.workspace.ext.dirNamedSame": "sysdata/extensions/ 下已存在同名目录。",
 	"cli.cmd.workspace.ext.extNameMust": "扩展名必须符合模式 {0}。",
 	"cli.cmd.workspace.ext.extNameRequired": "必须填写扩展名。",
 	"cli.cmd.workspace.ext.invalidExtName": "扩展名无效。",
 	"cli.cmd.workspace.ext.middleSegmentMust": "中间段必须等于 \"{0}\"（当前：\"{1}\"）。",
 	"cli.cmd.workspace.ext.list.summary": "列出本地扩展。",
-	"cli.cmd.workspace.ext.list.desc": "列出工作区 sysdata 项目下的本地扩展。",
+	"cli.cmd.workspace.ext.list.desc": "列出工作区 sysdata 项目下的本地扩展。\n\n列表来自当前工作区 sysdata 下的扩展目录，不是服务器已安装扩展清单。确认名称后可用于 extension push。",
 	"cli.cmd.workspace.ext.create.summary": "创建本地扩展。",
-	"cli.cmd.workspace.ext.create.desc": "从服务器模板创建本地扩展目录。",
+	"cli.cmd.workspace.ext.create.desc": "从服务器模板创建本地扩展目录。\n\n需要扩展点、模板和新名称；可先用 server extension template list 获取有效组合。此操作写入本地目录，完成后检查生成内容，再用 extension push 发布。\n\n必须已有活跃服务器并已克隆 sysdata 项目；模板需要联网获取，JSON execution.server=none 不代表离线可执行。\n\n相关说明见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n名称使用小写字母、数字与短横线，至少三段，第二段必须等于扩展点，例如 succ-component-card；目标目录不能已存在。\n\n详细文档：扩展开发\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/extension/extension.md\n网页：https://docs.succapp.com/ai-building/extension/extension",
 	"cli.cmd.workspace.ext.create.extTemplate": "找不到扩展模板：{0}/{1}",
 	"cli.cmd.workspace.ext.push.summary": "推送本地扩展。",
-	"cli.cmd.workspace.ext.push.desc": "将本地扩展目录推送到活跃服务器。",
+	"cli.cmd.workspace.ext.push.desc": "将本地扩展目录推送到活跃服务器。\n\n扩展名称与 --path 必须且只能选择一个。此命令会上传并影响服务器扩展；先确认内容与活跃服务器，已有目标需要覆盖时查看 --force 的说明。",
 	"cli.cmd.workspace.ext.push.path": "根据 sysdata/extensions 下的本地路径解析扩展。",
 	"cli.cmd.workspace.ext.push.force": "允许本地扩展文件覆盖远端变化。",
 	"cli.cmd.workspace.ext.push.needNamePath": "请传入扩展名或 --path=<path>。",
 	"cli.cmd.workspace.ext.push.onlyOne": "<name> 和 --path=<path> 只能使用一个。",
+	"cli.cmd.workspace.*.path": "工作区资源路径；可用本地路径或 /项目名/... 元数据路径，省略时的范围见正文。",
+	"cli.cmd.workspace.file.*.pathspec": "相对路径与 glob 从工作区根目录展开，不从启动子目录展开；目录递归处理，glob 请加引号。可用工作区内本地绝对路径或 /项目名/... 元数据路径。",
+	"cli.cmd.workspace.file.*.path": "工作区资源路径；可用本地路径或 /项目名/... 元数据路径，省略时的范围见正文。",
+	"cli.cmd.workspace.remote.*.url": "已配置或待添加的服务器 URL，例如 https://bi.example.com。",
+	"cli.cmd.workspace.remote.*.oldUrl": "已配置的旧服务器 URL。",
+	"cli.cmd.workspace.remote.*.newUrl": "同一服务器的新访问 URL。",
+	"cli.cmd.workspace.lock.*.scope": "工作区锁范围，如 config、sync；默认范围见正文。",
+	"cli.cmd.workspace.backup.*.path": "工作区资源路径；可用本地路径或 /项目名/... 元数据路径，省略时的范围见正文。",
+	"cli.cmd.workspace.ext.*.extensionPoint": "server extension template list 返回的扩展点。",
+	"cli.cmd.workspace.ext.*.template": "所选扩展点下的模板名称，来自 server extension template list。",
+	"cli.cmd.workspace.ext.create.name": "要创建的扩展名称，按模板扩展点命名要求填写。",
+	"cli.cmd.workspace.ext.push.name": "workspace extension list 返回的扩展名称；与 --path 二选一。",
+	"cli.cmd.workspace.proj.clone.project": "项目名称；远程名称来自 server project list，本地名称来自 workspace project list。",
+	"cli.cmd.workspace.proj.remove.project": "项目名称；远程名称来自 server project list，本地名称来自 workspace project list。",
+	"cli.cmd.workspace.status.incomplete": "远端检查未完成（{0}）；远端变化可能是上次结果，请检查 warnings 并重新核验。",
 	"cli.out.search.score": "相关度",
 	"cli.out.common.active": "活跃",
 	"cli.out.common.api": "Dev Tool 接口",
@@ -1081,9 +1151,9 @@
 	"cli.out.header.upgrade": "支持升级",
 	"cli.out.header.value": "值",
 	"cli.out.header.version": "版本",
-	"cli.out.help.commandHelpRead": "运行 'succapp {0} <command> --help' 查看具体命令帮助。",
+	"cli.out.help.commandHelpRead": "运行 'succapp {0} <command> --help' 查看下一级帮助。",
 	"cli.out.help.commandHelpSee": "运行 'succapp <command> --help' 查看命令帮助。",
-	"cli.out.help.commands": "命令",
+	"cli.out.help.commands": "命令：",
 	"cli.out.help.arguments": "参数：",
 	"cli.out.help.examples": "示例：",
 	"cli.out.help.group.content": "正文选项：",
@@ -1095,7 +1165,7 @@
 	"cli.out.help.group.query": "查询选项：",
 	"cli.out.help.group.search": "搜索选项：",
 	"cli.out.help.usageHeader": "用法：",
-	"cli.out.help.usageLine": "用法： succapp {command} {usageArgs}",
+	"cli.out.help.usageLine": "用法：succapp {command} {usageArgs}",
 	"cli.out.human.error": "错误：{0}",
 	"cli.out.human.hint": "提示：{0}",
 	"cli.out.human.info": "信息：{0}",
@@ -1140,6 +1210,8 @@
 	"cli.out.workspace.ext.version": "当前版本",
 	"cli.out.workspace.file.hist.empty": "暂无服务器历史记录",
 	"cli.out.workspace.file.history.badLimit": "--limit 的值无效：{0}",
+	"cli.out.help.commandGroups": "命令分组：",
+	"cli.out.help.rootUsage": "succapp [全局选项] <command> [<args>]",
 	"cli.err.context.exampleCommandServer": "succapp --server=<url> {commandName}",
 	"cli.err.context.exampleCommandUrl": "succapp {commandName} <url>",
 	"cli.err.context.exampleEnvUrl": "{envName}=<url> succapp {commandName}",
@@ -1326,6 +1398,7 @@
 	"vs.cmd.sync.upgradeMeta.result": "元数据升级完成：已变更 {0} 个，已检查 {1} 个。",
 	"vs.cmd.sync.upgradeMeta.upgrade": "升级",
 	"vs.cmd.sync.upgradeMeta.upgradeMetaFile": "升级此文件夹下的 {0} 个元数据文件？",
+	"vs.cmd.sync.push.upgradeRequired": "推送前需要升级 {0} 个旧版元数据文件，是否升级？取消将停止本次推送。",
 	"vs.cmd.ext.create.cannotCreateExt": "无法新建扩展，因为当前工作区尚未 clone sysdata 项目。",
 	"vs.cmd.ext.create.createdExt": "已创建扩展 {0}。",
 	"vs.cmd.ext.create.dirNamedSame": "sysdata/extensions/ 下已存在同名目录。",
@@ -1440,9 +1513,9 @@
 	"vs.ui.workspaceProblem.syncProblem": "SuccApp 检测到工作区同步问题。详见日志。",
 	"cli.cmd.model.title": "模型",
 	"cli.cmd.model.summary": "查看和查询语义数据模型",
-	"cli.cmd.model.desc": "查看和查询 SuccApp 语义数据模型。",
+	"cli.cmd.model.desc": "查看和查询 SuccApp 语义数据模型。\n\n先用 search 查找模型，再用 show、fields、indexes 或 profile 了解结构。单模型预览用 select，聚合和关联用 query，保存 CSV 用 export；字段统计用 field-profile。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：探查模型数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/explore-model-data.md\n网页：https://docs.succapp.com/ai-building/data/explore-model-data",
 	"cli.cmd.model.search.summary": "搜索语义模型。",
-	"cli.cmd.model.search.desc": "按完整路径，或按可组合的位置、模型属性和字段属性条件搜索可见的 .tbl 语义模型。",
+	"cli.cmd.model.search.desc": "按完整路径，或按可组合的位置、模型属性和字段属性条件搜索可见的 .tbl 语义模型。\n\n返回的 .tbl 路径可用于后续模型命令。完整路径定位与组合筛选的用法见下面参数；结果只包含当前用户可见模型，达到 limit 时不要据此判断没有其它模型。",
 	"cli.cmd.model.search.query": "以 '/' 开头时按完整模型路径或路径 glob 搜索；包含 '*' 或 '?' 时按模型文件名 glob 搜索；其他输入按关键词宽搜索模型属性或默认可见字段属性。",
 	"cli.cmd.model.search.path": "按模型元数据绝对路径 glob 搜索，项目根路径默认递归搜索；可以与关键词 <query> 组合，不能与路径型 <query>、--project、--parent-dir 或 --name 组合。",
 	"cli.cmd.model.search.name": "按模型文件名 glob 搜索；不含通配符时精确匹配。可以与关键词 <query>、--project、--parent-dir 组合，不能与 glob 型 <query> 或 --path 组合。",
@@ -1462,11 +1535,11 @@
 	"cli.cmd.model.search.nameHint": "没有通配符时模型名按精确值匹配，CLI 不会自动补通配符或 .tbl 后缀。",
 	"cli.cmd.model.search.hasMore": "仅显示最相关的 {0} 个模型；请增加项目、目录、类型或更准确的关键词来缩小范围。",
 	"cli.cmd.model.show.summary": "查看模型元数据摘要。",
-	"cli.cmd.model.show.desc": "查看语义模型元数据摘要。",
+	"cli.cmd.model.show.desc": "查看语义模型元数据摘要。\n\n<model> 使用 search 返回的 .tbl 路径。查看字段请用 fields，查看完整元数据和行数请用 profile --json；此命令不查询模型数据行。",
 	"cli.cmd.model.profile.summary": "获取单个语义模型画像。",
-	"cli.cmd.model.profile.desc": "返回模型摘要、当前版本完整元数据和物理表真实行数。human 输出保持简洁，使用 --json 获取完整元数据。",
+	"cli.cmd.model.profile.desc": "返回模型摘要、当前版本完整元数据和物理表真实行数。human 输出保持简洁，使用 --json 获取完整元数据。\n\n行数统计会访问数据源，可能受权限或连接状态影响。请检查 dataRowCount 的 value 或 errorInfo，不能把缺失或失败的统计当成 0；字段级统计另用 field-profile。",
 	"cli.cmd.model.fieldProfile.summary": "获取指定模型字段画像。",
-	"cli.cmd.model.fieldProfile.desc": "查看指定字段、推断的分析角色、维属性和按需计算的数据统计。一次选择 1 到 20 个字段；解析到同一 fieldPath 的别名会自动去重。\n\n实际能力取决于字段类型、数据源、数据量、权限和脱敏设置。nullCount/nullRate 适用于可查询字段；数值字段可使用 distinctCount、minValue、maxValue、sum、avg、zeroCount、negativeCount、topValues 和 sampleValues；字符串和日期字段可使用 distinctCount、minValue、maxValue、topValues 和 sampleValues；布尔字段可使用 distinctCount、topValues 和 sampleValues。median、p90 和 p95 仅为协议兼容保留，当前返回 unsupported。请以 dataProfile.unavailableProperties 为准。数量级未知的模型只有在当前账号可见行数不超过 100,000 时才执行 distinctCount/topValues；百万级模型返回 costLimit。JSON 中 sum/avg 使用十进制字符串保留精度。",
+	"cli.cmd.model.fieldProfile.desc": "查看指定字段、推断的分析角色、维属性和按需计算的数据统计。一次选择 1 到 20 个字段；解析到同一 fieldPath 的别名会自动去重。\n\n实际能力取决于字段类型、数据源、数据量、权限和脱敏设置。nullCount/nullRate 适用于可查询字段；数值字段可使用 distinctCount、minValue、maxValue、sum、avg、zeroCount、negativeCount、topValues 和 sampleValues；字符串和日期字段可使用 distinctCount、minValue、maxValue、topValues 和 sampleValues；布尔字段可使用 distinctCount、topValues 和 sampleValues。median、p90 和 p95 仅为协议兼容保留，当前返回 unsupported。请以 dataProfile.unavailableProperties 为准。数量级未知的模型只有在当前账号可见行数不超过 100,000 时才执行 distinctCount/topValues；百万级模型返回 costLimit。JSON 中 sum/avg 使用十进制字符串保留精度。\n\n先用 model fields 确定字段路径。只看结构时使用 --no-data，它不能与 --data-property 同时使用；按需指定统计项可减少查询成本。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：探查模型数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/explore-model-data.md\n网页：https://docs.succapp.com/ai-building/data/explore-model-data",
 	"cli.cmd.model.fieldProfile.field": "字段物理名、业务名或 fieldPath。可重复传入，最多选择 20 个字段；等价名称按 fieldPath 去重。",
 	"cli.cmd.model.fieldProfile.dataProperty": "要计算的数据统计。可重复传入或用逗号分隔。可选值：nullCount、nullRate、distinctCount、minValue、maxValue、sum、avg、median、p90、p95、zeroCount、negativeCount、topValues、sampleValues。未传时计算 nullCount、nullRate、distinctCount、minValue 和 maxValue。",
 	"cli.cmd.model.fieldProfile.noData": "不扫描字段数据，只返回字段语义和维属性。不能与 --data-property 同时使用。",
@@ -1474,14 +1547,14 @@
 	"cli.cmd.model.fieldProfile.sampleLimit": "sampleValues 最大返回数量，默认 10，有效范围为 1 到 50。",
 	"cli.cmd.model.fieldProfile.dimensionAttributeDepth": "维属性展开深度，默认 1，有效范围为 0 到 3。",
 	"cli.cmd.model.fields.summary": "列出模型字段。",
-	"cli.cmd.model.fields.desc": "列出语义模型字段。",
+	"cli.cmd.model.fields.desc": "列出语义模型字段。\n\n<model> 使用 search 返回的 .tbl 路径。查询中的字段名应以这里返回的字段信息为依据；要了解统计分布再用 field-profile。",
 	"cli.cmd.model.fields.all": "包含隐藏字段和扩展属性。",
 	"cli.cmd.model.fields.contains": "按字段名、标题或物理字段匹配：普通文本按忽略大小写的包含匹配；/pattern/flags 按正则匹配，支持 i、m 和 g（仅兼容，无实际影响）。",
 	"cli.cmd.model.fields.dim": "仅列出维键字段。",
 	"cli.cmd.model.fields.measure": "仅列出度量字段。",
 	"cli.cmd.model.fields.empty": "未找到匹配的字段。",
 	"cli.cmd.model.indexes.summary": "列出模型索引。",
-	"cli.cmd.model.indexes.desc": "列出主键、业务键和模型索引。",
+	"cli.cmd.model.indexes.desc": "列出主键、业务键和模型索引。\n\n<model> 使用 search 返回的 .tbl 路径。结果用于了解模型键和索引声明，不代表已经验证数据唯一性；此命令不会创建或重建数据库索引。",
 	"cli.cmd.model.indexes.empty": "该模型没有索引。",
 	"cli.cmd.model.*.select": "查询字段，多个字段用逗号分隔，可重复传入。",
 	"cli.cmd.model.*.maxRows": "最大预览行数。",
@@ -1489,20 +1562,21 @@
 	"cli.cmd.model.*.queryFile": "从文件读取 Query DSL JSON。",
 	"cli.cmd.model.*.stdin": "从标准输入读取 Query DSL JSON。",
 	"cli.cmd.model.select.summary": "查询单个模型数据。",
-	"cli.cmd.model.select.desc": "使用 SuccApp 表达式过滤条件查询单个 .tbl 模型。",
+	"cli.cmd.model.select.desc": "使用 SuccApp 表达式过滤条件查询单个 .tbl 模型。\n\n先用 fields 确定字段，--where 使用 SuccApp 表达式，不能直接填入一条 SQL。--max-rows 控制预览行数；聚合或多模型关联使用 query，保存 CSV 使用 export。\n\n当前配套服务器的预览默认最多 100 行，上限 1000 行；实际以目标服务器和返回的截断信息为准。完整数据请使用对应 export 命令。",
 	"cli.cmd.model.select.where": "过滤表达式，例如 STATUS='ACTIVE'。",
 	"cli.cmd.model.select.order": "排序表达式，例如 CREATE_TIME desc。",
 	"cli.cmd.model.select.limit": "最大返回行数。",
 	"cli.cmd.model.query.summary": "使用 Query DSL 查询模型。",
-	"cli.cmd.model.query.desc": "使用 Query DSL JSON 查询一个或多个 .tbl 模型。\n\nJSON 类型：query.d.ts 中的 succ.meta.dw.Query。\n在线 DTS：https://docs.succapp.com/dev-types/types/meta/file-types/query.d.ts\n当前 workspace DTS：.agents/skills/succapp-docs/dev-types/types/meta/file-types/query.d.ts",
+	"cli.cmd.model.query.desc": "使用 Query DSL JSON 查询一个或多个 .tbl 模型，适用于聚合或多模型关联查询。命令在目标服务器执行模型查询，不用于写入模型数据。\n\n--query、--query-file、--stdin 必须且只能选择一个；--max-rows 为整数且至少为 1。返回结果可能受行数限制，不能直接视为完整数据。\n\n查询 JSON 的类型为 query.d.ts 中的 succ.meta.dw.Query。编写复杂查询前，可阅读下面指南中的聚合、多模型关联及结果导出说明，并参照类型定义。请确认资料适用于当前 CLI 和服务器版本；无法联网时可查阅已有的适用离线手册。\n\n当前配套服务器的预览默认最多 100 行，上限 1000 行；实际以目标服务器和返回的截断信息为准。完整数据请使用对应 export 命令。\n\n详细文档：探索模型数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/explore-model-data.md\n网页：https://docs.succapp.com/ai-building/data/explore-model-data\n\n类型定义：succ.meta.dw.Query\n在线：https://docs.succapp.com/dev-types/types/meta/file-types/query.d.ts\n本地：.agents/skills/succapp-docs/dev-types/types/meta/file-types/query.d.ts",
 	"cli.cmd.model.query.empty": "查询成功，返回 0 行。",
 	"cli.cmd.model.export.summary": "将模型查询结果导出为 CSV。",
-	"cli.cmd.model.export.desc": "将单模型或 Query DSL 查询结果导出为 CSV。",
+	"cli.cmd.model.export.desc": "将单模型或 Query DSL 查询结果导出为 CSV。\n\n选择 <model> 或一种 Query DSL 输入（--query、--query-file、--stdin），并用 --output 指定本地 CSV。--select、--where、--order 用于单模型方式。已有文件需要 --force 覆盖；导出仍受查询条件、DSL 限制和访问权限约束。\n\n完整流程见下面资料，阅读前确认适用于当前 CLI 和服务器版本。\n\n详细文档：探查模型数据\nMarkdown：https://docs.succapp.com/guide/dev/ai-building/data/explore-model-data.md\n网页：https://docs.succapp.com/ai-building/data/explore-model-data",
 	"cli.cmd.model.export.where": "单模型导出的过滤表达式。",
 	"cli.cmd.model.export.order": "单模型导出的排序表达式。",
 	"cli.cmd.model.export.output": "把 CSV 输出写入本地文件。",
 	"cli.cmd.model.export.force": "输出文件已存在时允许覆盖。",
 	"cli.cmd.model.export.exportedData": "已导出数据到 {0}",
+	"cli.cmd.model.*.model": "model search 返回的 .tbl 模型路径，例如 /DEMO/data/tables/customer.tbl。",
 	"vs.cmd.title.addServer": "添加服务器",
 	"vs.cmd.title.useServer": "使用服务器",
 	"vs.cmd.title.loginServer": "登录服务器",