From 737ff48b2f7c319aae36eb5828602e60fb9b5354 Mon Sep 17 00:00:00 2001
From: zjncs <18910855655@163.com>
Date: Wed, 21 Oct 2026 13:57:18 +0800
Subject: [PATCH 01/17] fix(dev): pin the web toolchain to Node 20/22
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

jsdom-based web unit tests silently break on Node 25 (window.localStorage
degrades to a plain object, see #991) while CI stays green on its pinned
Node 20 — a confusing failure mode for new contributors on bleeding-edge
Node. Pins the local default via .nvmrc, declares engines in
web/package.json, and spells out the supported versions in CONTRIBUTING.

Signed-off-by: zjncs <18910855655@163.com>
---
 .nvmrc           | 1 +
 CONTRIBUTING.md  | 2 +-
 web/package.json | 3 +++
 3 files changed, 5 insertions(+), 1 deletion(-)
 create mode 100644 .nvmrc

diff --git a/.nvmrc b/.nvmrc
new file mode 100644
index 000000000..209e3ef4b
--- /dev/null
+++ b/.nvmrc
@@ -0,0 +1 @@
+20
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7c7c57d04..dad2d10a6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,7 +24,7 @@ Prerequisites:
 
 - Docker and Docker Compose
 - Java 21
-- Node.js and `pnpm`
+- Node.js 20 or 22 (see `.nvmrc`; Node 25+ currently breaks jsdom-based web tests — #991) and `pnpm`
 
 Start the local stack:
 
diff --git a/web/package.json b/web/package.json
index ac1340ec4..a1d9924c1 100644
--- a/web/package.json
+++ b/web/package.json
@@ -92,5 +92,8 @@
     "typescript": "^5.7.0",
     "vite": "^6.4.3",
     "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=20 <25"
   }
 }

From 4d2b42282c8d9012a2ffa934b68224a9440b89f5 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Wed, 21 Oct 2026 14:58:31 +0800
Subject: [PATCH 02/17] docs(dsh): record 0.3.1 publication and acceptance

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 .../changes/add-dsh-native-plugin/release-notes.md  |  2 +-
 openspec/changes/add-dsh-native-plugin/tasks.md     |  6 +++---
 .../changes/add-dsh-native-plugin/verification.md   | 13 +++++++++++++
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/openspec/changes/add-dsh-native-plugin/release-notes.md b/openspec/changes/add-dsh-native-plugin/release-notes.md
index 8e0638c4d..c8680d27c 100644
--- a/openspec/changes/add-dsh-native-plugin/release-notes.md
+++ b/openspec/changes/add-dsh-native-plugin/release-notes.md
@@ -2,7 +2,7 @@
 
 ## 版本与交付状态
 
-本次发布候选为 `@astron-team/skillhub-dsh@0.3.1`，计划使用独立标签 `dsh-v0.3.1`。[兼容修复 PR #988](https://github.com/iflytek/skillhub/pull/988) 已合并；npm 上传、公开包完整性及发布后安装检查尚待完成，分别记录于 [验证摘要](verification.md)。历史已发布版本保持不变。
+`@astron-team/skillhub-dsh@0.3.1` 已发布，独立标签为 `dsh-v0.3.1`。[发布准备 PR #995](https://github.com/iflytek/skillhub/pull/995) 已合并，[专用发布工作流](https://github.com/iflytek/skillhub/actions/runs/39556075587) 成功；[公开 npm 包](https://www.npmjs.com/package/@astron-team/skillhub-dsh/v/0.3.1) 与工作流产物逐字节一致，`latest` 指向 `0.3.1`。两版 Linux 的严格安装、原生探针及浏览器操作复验通过，测试工件与公开包字节一致，结果见 [验证摘要](verification.md)。历史已发布版本保持不变。
 
 ## 0.3.1 DSH 双 RC 兼容
 
diff --git a/openspec/changes/add-dsh-native-plugin/tasks.md b/openspec/changes/add-dsh-native-plugin/tasks.md
index cf82ba4b3..5b4d436a4 100644
--- a/openspec/changes/add-dsh-native-plugin/tasks.md
+++ b/openspec/changes/add-dsh-native-plugin/tasks.md
@@ -299,6 +299,6 @@
 
 ## 38. 0.3.1 兼容修复发布
 
-- [ ] 38.1 将包版本及双语安装、发布说明更新为 `0.3.1`，完成候选检查与发布准备 PR。
-- [ ] 38.2 使用 `dsh-v0.3.1` 和专用工作流发布 npm，核对实际上传产物、公开版本和完整性。
-- [ ] 38.3 从 npm 下载公开包，完成隔离 DSH 安装与关键操作复验，并记录已验证平台及未验范围。
+- [x] 38.1 将包版本及双语安装、发布说明更新为 `0.3.1`，完成候选检查与发布准备 PR（#995）。
+- [x] 38.2 使用 `dsh-v0.3.1` 和专用工作流发布 npm，核对实际上传产物、公开版本和完整性。
+- [x] 38.3 从 npm 下载公开包，完成隔离 DSH 安装与关键操作复验，并记录已验证平台及未验范围。
diff --git a/openspec/changes/add-dsh-native-plugin/verification.md b/openspec/changes/add-dsh-native-plugin/verification.md
index e9f920940..f5ad086f5 100644
--- a/openspec/changes/add-dsh-native-plugin/verification.md
+++ b/openspec/changes/add-dsh-native-plugin/verification.md
@@ -2,6 +2,8 @@
 
 ## 1. 当前结论
 
+`0.3.1` 已发布，公开 npm 包与发布工作流产物逐字节一致，`latest` 已更新。两版 Linux 的严格安装、原生探针及浏览器操作复验通过，实际安装内容与公开 tarball 逐文件一致，未复用历史功能候选冒充新包验收；本次进展见文末记录。
+
 `0.2.1` 已通过 [PR #979](https://github.com/iflytek/skillhub/pull/979) 合并并发布；默认来源为 `https://skill.xfyun.cn`。`0.3.0` 开源交互改进已通过 PR #986 合并、发布并完成公开包独立验收，结果见本文发布验收记录，不以历史版本结果代替新代码验证。
 
 2026-10-19 使用公开 npm `0.2.0` 的真实 Linux DSH 插件连接 `https://skill.xfyun.cn`，连接测试、目录、搜索、Markdown 和版本选择通过；选择 `global/scientella@20260724.052402` 实际安装到隔离项目，7 个文件及归档 fingerprint 一致，inventory 来源与目标正确，再搜索显示项目已安装旧版，DSH 发现成功。评论接口 404 按可选能力处理，安全审核 401 按匿名拒绝处理。本轮未调用模型，不据此声明技能实际执行或生产 Pod 已核验。该技能使用日期格式的非 SemVer 版本，版本比较返回 `blocked/unknown-order`，按既有策略不提供升级入口；不得把固定版本安装通过写成升级通过。升级阻断前后文件保持不变；真实卸载后 DSH 发现消失，inventory 与重新搜索的安装记录清空。公开 `0.2.0` 的正式来源基线共 9 项浏览器检查通过，无页面脚本异常。
@@ -153,3 +155,14 @@
 - 使用公开 tarball，通过官方安装器装入干净隔离 Profile；复用已安装的官方 DSH 程序，运行基线和插件生命周期探针均通过。该路径不等于重新从网络安装整套 DSH 依赖。
 - 现有 Linux 预览升级到公开 `0.3.0`，81 个交付文件逐字节核对；15 个历史对话归档及技能状态文件在升级和重启后保持一致。浏览器技能中心加载 3 张联调技能卡片，无页面脚本异常。
 - 本轮发布后未新增模型请求，不将先前候选的真实模型验收写为公开包的新模型验收；预览使用本地开源市场，不代表 SaaS 新契约已部署。后续发布将公开读取窗口扩大到 40 次、间隔 30 秒，保留严格完整性比对与不重复发布边界。
+
+
+## 0.3.1 发布与公开包验收（2026-10-21）
+
+- [发布准备 PR #995](https://github.com/iflytek/skillhub/pull/995) 已合并，使用独立标签 `dsh-v0.3.1` 发布。PR 后端检查首次因 Go `1.27.1` 工具链下载超过 25 秒就绪期限失败；[重跑](https://github.com/iflytek/skillhub/actions/runs/39554597158) 成功，不将首次运行描述为全部通过。
+- 本地 build、typecheck、lint 及完整 365 项测试通过。[正式发布运行](https://github.com/iflytek/skillhub/actions/runs/39556075587) 最终成功，八组 DSH 检查、候选打包及 npm 发布检查通过。
+- 官方 Registry 的 `latest` 已指向 `0.3.1`；独立下载 [公开 npm 包](https://www.npmjs.com/package/@astron-team/skillhub-dsh/v/0.3.1)，归档与工作流 tarball 逐字节相同，`dist.integrity` 核对一致。
+- 从公开 `0.3.0` 升级到与公开 `0.3.1` 相同字节的候选包后，技能文件、inventory、操作日志与原会话历史共 12 个文件逐字节保持，来源及详情 Tab 配置不变；重启后读取验证通过。该保留验证与全新安装生命周期验证分别记录。
+- 同一工作流产物在 Linux 官方 DSH `0.2.0-rc.2`、`0.2.1-rc.2` 中分别通过 npm/pnpm 严格安装、故意 peer 冲突负控及 5 项原生探针；公开包下载后，再与三套实际安装目录逐文件比对一致。执行时点与工件来源保留原记录，不将上传前运行改写为下载后执行。
+- 两版浏览器均完成用户/项目安装 `1.2.0` → 升级 `1.3.0` → 卸载，以及三种操作取消零写入；文件、指纹、库存、操作日志核对通过，每版实际写入 RPC 为 6 次，页面及控制台错误为 0。新 RC 首次脚本重复选择已选范围导致定位超时，发生时写入为 0；修正测试定位后，真实范围切换及完整流程通过，原失败记录保留。
+- 本轮使用隔离本地市场，没有调用模型；未新增新 RC Windows/macOS 原生文件操作、真实桌面或 SaaS 生产验收，不修改生产环境。

From 36b226416ec5bceb8387740f2a521816e29c9ab6 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Wed, 21 Oct 2026 16:25:32 +0800
Subject: [PATCH 03/17] feat(ci): detect cross-PR Flyway version collisions

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 scripts/migration-preflight.py            | 139 ++++++++++++++++++++++
 scripts/tests/test_migration_preflight.py |  69 +++++++++++
 2 files changed, 208 insertions(+)
 create mode 100644 scripts/migration-preflight.py
 create mode 100644 scripts/tests/test_migration_preflight.py

diff --git a/scripts/migration-preflight.py b/scripts/migration-preflight.py
new file mode 100644
index 000000000..ab02cf4a6
--- /dev/null
+++ b/scripts/migration-preflight.py
@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Read GitHub PR file metadata and summarize possible Flyway version collisions."""
+
+import html
+import json
+import os
+from pathlib import Path
+import re
+import urllib.error
+import urllib.request
+
+
+MIGRATION = re.compile(
+    r"server/skillhub-app/src/main/resources/db/migration/V([0-9]+)__[^/]+\.sql\Z"
+)
+
+
+class ScanError(Exception):
+    pass
+
+
+def version(path):
+    match = MIGRATION.fullmatch(path)
+    return int(match[1]) if match else None
+
+
+def introduced_version(file):
+    number = version(file["filename"])
+    if file["status"] == "added":
+        return number
+    if file["status"] == "renamed" and version(file.get("previous_filename", "")) != number:
+        return number
+    return None
+
+
+class GitHub:
+    def __init__(self, repository, token):
+        if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository):
+            raise ScanError("Invalid repository name")
+        self.base = f"https://api.github.com/repos/{repository}"
+        self.token = token
+
+    def get(self, path):
+        request = urllib.request.Request(self.base + path, headers={
+            "Authorization": f"Bearer {self.token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        })
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:
+                return json.load(response)
+        except urllib.error.HTTPError as error:
+            raise ScanError(f"GitHub API HTTP {error.code}; scan incomplete") from error
+        except (urllib.error.URLError, TimeoutError, ValueError, OSError) as error:
+            # Do not echo server payloads, tokens, request headers or arbitrary URLs.
+            raise ScanError(f"GitHub API {type(error).__name__}; scan incomplete") from error
+
+    def pages(self, path, limit=None):
+        result = []
+        for page in range(1, 1001):
+            separator = "&" if "?" in path else "?"
+            batch = self.get(f"{path}{separator}per_page=100&page={page}")
+            if not isinstance(batch, list):
+                raise ScanError("Unexpected GitHub pagination response")
+            result.extend(batch)
+            if len(batch) < 100:
+                return result
+            if limit is not None and len(result) >= limit:
+                raise ScanError("PR files reached GitHub's 3000-file limit")
+        raise ScanError("Pagination safety limit reached")
+
+
+def scan(api):
+    versions = {}
+    errors = []
+    prs = api.pages("/pulls?state=open&sort=created&direction=asc")
+    for pr in prs:
+        number = pr["number"]
+        try:
+            files = api.pages(f"/pulls/{number}/files", limit=3000)
+            current = api.get(f"/pulls/{number}")
+            if current["head"]["sha"] != pr["head"]["sha"] or current["state"] != "open":
+                raise ScanError("PR changed during scan; rerun required")
+            if len(files) != current["changed_files"]:
+                raise ScanError("PR file list incomplete; rerun required")
+            for file in files:
+                value = introduced_version(file)
+                if value is not None:
+                    versions.setdefault(value, {}).setdefault(number, []).append(file["filename"])
+        except ScanError as error:
+            errors.append(f"PR #{number}: {error}")
+    return {v: entries for v, entries in sorted(versions.items()) if len(entries) > 1}, errors, len(prs)
+
+
+def safe(value):
+    # HTML text in a pre block avoids Markdown/link/table injection from filenames.
+    return html.escape(str(value)).replace("\r", "&#13;").replace("\n", "&#10;")
+
+
+def summary(collisions, errors, count):
+    lines = ["## Flyway migration preflight", "",
+             "Advisory only: no SQL is downloaded or executed; no PR is changed.", "",
+             f"Open PRs inspected: {count}.", ""]
+    if errors:
+        lines += ["**Warning: scan incomplete. Absence of a reported collision is not clearance.**", "", "<pre>",
+                  *(safe(error) for error in errors), "</pre>", ""]
+    if collisions:
+        lines += ["**Warning: migration versions introduced by multiple open PRs:**", "", "<pre>"]
+        for value, entries in collisions.items():
+            lines.append(f"V{value}")
+            for number, paths in sorted(entries.items()):
+                lines.extend(f"  PR #{number}: {safe(path)}" for path in sorted(set(paths)))
+        lines += ["</pre>", "", "Authors should coordinate numbering and rerun migration tests before merge."]
+    elif not errors:
+        lines.append("No cross-PR version collisions found in this snapshot.")
+    lines += ["", "Scope: added migrations and renames introducing a different version in the application migration directory. "
+              "Same-version renames, modified/deleted files and conflicts with already merged migrations are not checked. "
+              "Concurrent PR changes can make this advisory snapshot stale.", ""]
+    return "\n".join(lines)
+
+
+def main():
+    try:
+        api = GitHub(os.environ.get("GITHUB_REPOSITORY", ""), os.environ.get("GITHUB_TOKEN", ""))
+        collisions, errors, count = scan(api)
+    except (ScanError, KeyError, TypeError) as error:
+        collisions, errors, count = {}, [f"Scan unavailable ({type(error).__name__}); no clearance issued."], 0
+    report = summary(collisions, errors, count)
+    destination = os.environ.get("GITHUB_STEP_SUMMARY")
+    if destination:
+        with Path(destination).open("a", encoding="utf-8") as output:
+            output.write(report)
+    else:
+        print(report)
+    return 0  # Deliberately advisory; incomplete scans remain visible in the summary.
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/tests/test_migration_preflight.py b/scripts/tests/test_migration_preflight.py
new file mode 100644
index 000000000..b40f2f4e0
--- /dev/null
+++ b/scripts/tests/test_migration_preflight.py
@@ -0,0 +1,69 @@
+"""Offline behavior tests for the read-only migration preflight."""
+import importlib.util
+from pathlib import Path
+import unittest
+
+ROOT = Path(__file__).resolve().parents[2]
+spec = importlib.util.spec_from_file_location("preflight", ROOT / "scripts/migration-preflight.py")
+m = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(m)
+PREFIX = "server/skillhub-app/src/main/resources/db/migration/"
+
+
+class PreflightTest(unittest.TestCase):
+    def test_status_and_rename_boundaries(self):
+        path = PREFIX + "V001__new.sql"
+        self.assertEqual(m.introduced_version(dict(filename=path, status="added")), 1)
+        for status in ("modified", "removed", "copied"):
+            self.assertIsNone(m.introduced_version(dict(filename=path, status=status)))
+        self.assertIsNone(m.introduced_version(dict(filename=path, status="renamed",
+                                                     previous_filename=PREFIX + "V1__old.sql")))
+        self.assertEqual(m.introduced_version(dict(filename=path, status="renamed",
+                                                     previous_filename=PREFIX + "V2__old.sql")), 1)
+        for path in ("tests/V1__fake.sql", PREFIX + "V1_2__other.sql", PREFIX + "V1__new.sql/no"):
+            self.assertIsNone(m.introduced_version(dict(filename=path, status="added")))
+
+    def test_multiple_collisions_sorted_and_single_pr_not_collision(self):
+        class API:
+            def pages(self, path, limit=None):
+                if path.startswith("/pulls?"):
+                    return [dict(number=n, head=dict(sha=str(n))) for n in (9, 2)]
+                return [dict(filename=PREFIX + f"V{v}__a.sql", status="added") for v in (20, 3, 3)]
+            def get(self, path):
+                return dict(head=dict(sha=path.split("/")[-1]), state="open", changed_files=3)
+        collisions, errors, count = m.scan(API())
+        self.assertEqual(list(collisions), [3, 20])
+        self.assertEqual(errors, [])
+        self.assertEqual(count, 2)
+        report = m.summary(collisions, errors, count)
+        self.assertLess(report.index("PR #2"), report.index("PR #9"))
+        self.assertEqual(report.count("PR #2:"), 2)
+
+    def test_incomplete_never_reports_clearance(self):
+        report = m.summary({}, ["API HTTP 403"], 3)
+        self.assertIn("scan incomplete", report)
+        self.assertNotIn("No cross-PR", report)
+
+    def test_untrusted_filename_is_text(self):
+        attack = PREFIX + "V1__</pre><script>alert(1)</script>\n::error::x.sql"
+        report = m.summary({1: {2: [attack], 3: [PREFIX + "V1__a.sql"]}}, [], 2)
+        self.assertNotIn("<script>", report)
+        self.assertIn("&lt;script&gt;", report)
+        self.assertIn("&#10;", report)
+
+    def test_pagination_and_limit(self):
+        class API(m.GitHub):
+            def __init__(self):
+                self.calls = []
+            def get(self, path):
+                self.calls.append(path)
+                return [dict()] * (100 if "page=1" in path else 1)
+        api = API()
+        self.assertEqual(len(api.pages("/pulls?state=open")), 101)
+        self.assertEqual(api.calls[1], "/pulls?state=open&per_page=100&page=2")
+        with self.assertRaises(m.ScanError):
+            API().pages("/pulls/1/files", limit=100)
+
+
+if __name__ == "__main__":
+    unittest.main()

From a7ad63fce907b0d529f9fe518708981f34ff19fc Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Wed, 21 Oct 2026 16:25:42 +0800
Subject: [PATCH 04/17] test(ci): match exact pagination page in fixture

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 scripts/tests/test_migration_preflight.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/tests/test_migration_preflight.py b/scripts/tests/test_migration_preflight.py
index b40f2f4e0..ca68eb749 100644
--- a/scripts/tests/test_migration_preflight.py
+++ b/scripts/tests/test_migration_preflight.py
@@ -57,7 +57,7 @@ def __init__(self):
                 self.calls = []
             def get(self, path):
                 self.calls.append(path)
-                return [dict()] * (100 if "page=1" in path else 1)
+                return [dict()] * (100 if path.endswith("&page=1") else 1)
         api = API()
         self.assertEqual(len(api.pages("/pulls?state=open")), 101)
         self.assertEqual(api.calls[1], "/pulls?state=open&per_page=100&page=2")

From 7d11823a952c0ccac872a8178525e93cf3598f7c Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Wed, 21 Oct 2026 16:29:30 +0800
Subject: [PATCH 05/17] feat(ci): wire trusted advisory migration preflight
 workflow

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 .github/workflows/migration-preflight.yml |  45 ++++++++
 .github/workflows/pr-scripts.yml          |   2 +
 CONTRIBUTING.md                           |  30 +++++
 scripts/migration-preflight.py            |  16 ++-
 scripts/tests/test_migration_preflight.py | 135 +++++++++++++++++++++-
 5 files changed, 220 insertions(+), 8 deletions(-)
 create mode 100644 .github/workflows/migration-preflight.yml

diff --git a/.github/workflows/migration-preflight.yml b/.github/workflows/migration-preflight.yml
new file mode 100644
index 000000000..f80e3056d
--- /dev/null
+++ b/.github/workflows/migration-preflight.yml
@@ -0,0 +1,45 @@
+name: Migration Preflight
+
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize, closed, edited, ready_for_review]
+  schedule:
+    - cron: '17 */6 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: migration-preflight
+  cancel-in-progress: true
+
+jobs:
+  preflight:
+    name: Advisory Flyway version scan
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    continue-on-error: true
+    steps:
+      # Never check out a PR head or run SQL. This workflow only runs trusted
+      # default-branch code, including for pull requests from forks.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        id: checkout
+        continue-on-error: true
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Summarize open PR migration versions
+        id: scan
+        if: steps.checkout.outcome == 'success'
+        continue-on-error: true
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python3 scripts/migration-preflight.py
+
+      - name: Report unavailable scan
+        if: ${{ always() && (steps.checkout.outcome != 'success' || steps.scan.outcome != 'success') }}
+        run: |
+          printf '%s\n' '## Flyway migration preflight' '' '**Warning: scan unavailable. No clearance issued.** Check this workflow run for checkout, runtime or timeout failures.' >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/pr-scripts.yml b/.github/workflows/pr-scripts.yml
index 9fbd44ac7..86afde8fe 100644
--- a/.github/workflows/pr-scripts.yml
+++ b/.github/workflows/pr-scripts.yml
@@ -30,6 +30,7 @@ on:
       - '.github/workflows/publish-chart.yml'
       - '.github/workflows/security.yml'
       - '.github/workflows/pr-scripts.yml'
+      - '.github/workflows/migration-preflight.yml'
       - '**/*.py'
 
 permissions:
@@ -66,3 +67,4 @@ jobs:
       - run: bash scripts/tests/server-image-compat-test.sh
       - run: bash scripts/tests/workflow-security-test.sh
       - run: python3 -m unittest discover -s scripts/tests -p 'test_deepwiki_workflow.py' -v
+      - run: python3 -m unittest discover -s scripts/tests -p 'test_migration_preflight.py' -v
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7c7c57d04..bcde29f4b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -105,3 +105,33 @@ Do not open public issues for suspected security vulnerabilities.
 
 Use GitHub Security Advisories or your internal security process to report them
 privately to the maintainers.
+
+## Flyway migration version advisory
+
+The **Migration Preflight** workflow reads file metadata for all open PRs on PR
+changes, every six hours, or via **Actions → Migration Preflight → Run workflow**.
+See its Actions run summary for migration numbers introduced by more than one PR.
+It checks `server/skillhub-app/src/main/resources/db/migration/V<n>__*.sql` additions,
+including renames that introduce a different migration number. Pure renames with
+the same number, modified/deleted migrations and conflicts with migrations already
+merged into the base branch are outside this advisory's scope.
+
+This is a snapshot and a non-blocking warning, not a reservation or merge gate.
+If a scan is incomplete (for example API permissions, file-list truncation or a
+PR changing during collection), its summary says so; it must not be interpreted
+as confirmation of no conflict. The script exits nonzero on an incomplete scan;
+the workflow keeps this advisory and explicitly adds an unavailable-scan warning. PRs with 3,000 or more changed files are conservatively
+reported as incomplete because GitHub caps the files endpoint at 3,000 entries.
+Coordinate numbering with the other PR's author, update your migration filename,
+and rerun the relevant database/migration tests before merging. The workflow does
+not renumber files, post comments, fetch raw SQL files or execute PR code. The
+GitHub files API may include diff patches; the script ignores them and only uses
+file names/status, PR numbers and revision metadata. It uses only
+repository-content and pull-request read permissions and runs the default branch's
+script, so workflow/script changes take effect only after merging into that branch.
+
+Local offline regression checks (Python standard library only):
+
+```bash
+python3 -m unittest discover -s scripts/tests -p 'test_migration_preflight.py' -v
+```
diff --git a/scripts/migration-preflight.py b/scripts/migration-preflight.py
index ab02cf4a6..97451cc9d 100644
--- a/scripts/migration-preflight.py
+++ b/scripts/migration-preflight.py
@@ -79,7 +79,9 @@ def scan(api):
         try:
             files = api.pages(f"/pulls/{number}/files", limit=3000)
             current = api.get(f"/pulls/{number}")
-            if current["head"]["sha"] != pr["head"]["sha"] or current["state"] != "open":
+            if (current["head"]["sha"] != pr["head"]["sha"]
+                    or current["base"]["sha"] != pr["base"]["sha"]
+                    or current["state"] != "open"):
                 raise ScanError("PR changed during scan; rerun required")
             if len(files) != current["changed_files"]:
                 raise ScanError("PR file list incomplete; rerun required")
@@ -99,8 +101,8 @@ def safe(value):
 
 def summary(collisions, errors, count):
     lines = ["## Flyway migration preflight", "",
-             "Advisory only: no SQL is downloaded or executed; no PR is changed.", "",
-             f"Open PRs inspected: {count}.", ""]
+             "Advisory only: no SQL files are fetched or executed; no PR is changed.", "",
+             f"Open PRs discovered: {count}.", ""]
     if errors:
         lines += ["**Warning: scan incomplete. Absence of a reported collision is not clearance.**", "", "<pre>",
                   *(safe(error) for error in errors), "</pre>", ""]
@@ -123,8 +125,10 @@ def main():
     try:
         api = GitHub(os.environ.get("GITHUB_REPOSITORY", ""), os.environ.get("GITHUB_TOKEN", ""))
         collisions, errors, count = scan(api)
-    except (ScanError, KeyError, TypeError) as error:
-        collisions, errors, count = {}, [f"Scan unavailable ({type(error).__name__}); no clearance issued."], 0
+    except ScanError as error:
+        collisions, errors, count = {}, [str(error)], 0
+    except (KeyError, TypeError):
+        collisions, errors, count = {}, ["Malformed GitHub API response; no clearance issued."], 0
     report = summary(collisions, errors, count)
     destination = os.environ.get("GITHUB_STEP_SUMMARY")
     if destination:
@@ -132,7 +136,7 @@ def main():
             output.write(report)
     else:
         print(report)
-    return 0  # Deliberately advisory; incomplete scans remain visible in the summary.
+    return 1 if errors else 0  # Workflow treats errors as advisory, never as scan clearance.
 
 
 if __name__ == "__main__":
diff --git a/scripts/tests/test_migration_preflight.py b/scripts/tests/test_migration_preflight.py
index ca68eb749..4587de4b6 100644
--- a/scripts/tests/test_migration_preflight.py
+++ b/scripts/tests/test_migration_preflight.py
@@ -1,5 +1,11 @@
 """Offline behavior tests for the read-only migration preflight."""
+import contextlib
 import importlib.util
+import io
+import os
+import tempfile
+import urllib.error
+from unittest.mock import patch
 from pathlib import Path
 import unittest
 
@@ -27,10 +33,10 @@ def test_multiple_collisions_sorted_and_single_pr_not_collision(self):
         class API:
             def pages(self, path, limit=None):
                 if path.startswith("/pulls?"):
-                    return [dict(number=n, head=dict(sha=str(n))) for n in (9, 2)]
+                    return [dict(number=n, head=dict(sha=str(n)), base=dict(sha="base")) for n in (9, 2)]
                 return [dict(filename=PREFIX + f"V{v}__a.sql", status="added") for v in (20, 3, 3)]
             def get(self, path):
-                return dict(head=dict(sha=path.split("/")[-1]), state="open", changed_files=3)
+                return dict(head=dict(sha=path.split("/")[-1]), state="open", base=dict(sha="base"), changed_files=3)
         collisions, errors, count = m.scan(API())
         self.assertEqual(list(collisions), [3, 20])
         self.assertEqual(errors, [])
@@ -51,6 +57,23 @@ def test_untrusted_filename_is_text(self):
         self.assertIn("&lt;script&gt;", report)
         self.assertIn("&#10;", report)
 
+    def test_malformed_response_and_actual_files_cap(self):
+        api = m.GitHub("iflytek/skillhub", "token")
+        with patch.object(api, "get", return_value={"unexpected": True}):
+            with self.assertRaises(m.ScanError):
+                api.pages("/pulls")
+        with patch.object(api, "get", return_value=[{}] * 100) as get:
+            with self.assertRaises(m.ScanError):
+                api.pages("/pulls/1/files", limit=3000)
+            self.assertEqual(get.call_count, 30)
+        with patch.dict(os.environ, {"GITHUB_REPOSITORY": "iflytek/skillhub",
+                                     "GITHUB_STEP_SUMMARY": ""}):
+            with patch.object(m, "scan", side_effect=KeyError("filename")):
+                with contextlib.redirect_stdout(io.StringIO()) as output:
+                    self.assertEqual(m.main(), 1)
+                self.assertIn("Malformed GitHub API response", output.getvalue())
+                self.assertNotIn("No cross-PR", output.getvalue())
+
     def test_pagination_and_limit(self):
         class API(m.GitHub):
             def __init__(self):
@@ -65,5 +88,113 @@ def get(self, path):
             API().pages("/pulls/1/files", limit=100)
 
 
+    def test_single_pr_duplicates_do_not_collide(self):
+        class API:
+            def pages(self, path, limit=None):
+                if path.startswith("/pulls?"):
+                    return [dict(number=1, head=dict(sha="sha"), base=dict(sha="base"))]
+                return [dict(filename=PREFIX + "V1__a.sql", status="added"),
+                        dict(filename=PREFIX + "V1__b.sql", status="added")]
+            def get(self, path):
+                return dict(head=dict(sha="sha"), state="open", base=dict(sha="base"), changed_files=2)
+        self.assertEqual(m.scan(API()), ({}, [], 1))
+
+    def test_api_failure_retains_confirmed_collisions_and_marks_incomplete(self):
+        class API:
+            def pages(self, path, limit=None):
+                if path.startswith("/pulls?"):
+                    return [dict(number=n, head=dict(sha="sha"), base=dict(sha="base")) for n in (1, 2, 3)]
+                if path == "/pulls/3/files":
+                    raise m.ScanError("GitHub API HTTP 403; scan incomplete")
+                return [dict(filename=PREFIX + "V5__a.sql", status="added")]
+            def get(self, path):
+                return dict(head=dict(sha="sha"), state="open", base=dict(sha="base"), changed_files=1)
+        collisions, errors, count = m.scan(API())
+        self.assertEqual(list(collisions[5]), [1, 2])
+        self.assertIn("PR #3", errors[0])
+        report = m.summary(collisions, errors, count)
+        self.assertIn("scan incomplete", report)
+        self.assertIn("V5", report)
+
+    def test_changed_or_closed_pr_and_truncated_files_are_incomplete(self):
+        for change in (dict(head=dict(sha="changed")), dict(state="closed"), dict(base=dict(sha="changed")), dict(changed_files=2)):
+            class API:
+                def pages(self, path, limit=None):
+                    if path.startswith("/pulls?"):
+                        return [dict(number=1, head=dict(sha="sha"), base=dict(sha="base"))]
+                    return [dict(filename=PREFIX + "V1__a.sql", status="added")]
+                def get(self, path):
+                    return dict(dict(head=dict(sha="sha"), state="open", base=dict(sha="base"), changed_files=1), **change)
+            collisions, errors, _ = m.scan(API())
+            self.assertEqual(collisions, {})
+            self.assertEqual(len(errors), 1)
+
+    def test_get_uses_only_read_api_and_redacts_errors(self):
+        api = m.GitHub("iflytek/skillhub", "private-token")
+        with patch.object(m.urllib.request, "urlopen", return_value=io.BytesIO(b'[]')) as opening:
+            self.assertEqual(api.get("/pulls?state=open"), [])
+            request = opening.call_args.args[0]
+            self.assertEqual(request.get_method(), "GET")
+            self.assertEqual(request.full_url, "https://api.github.com/repos/iflytek/skillhub/pulls?state=open")
+            self.assertEqual(opening.call_args.kwargs["timeout"], 30)
+        for error in (urllib.error.HTTPError("https://secret", 403, "private-token", {}, None),
+                      urllib.error.URLError("private-token"), TimeoutError("private-token"),
+                      ValueError("private-token")):
+            with patch.object(m.urllib.request, "urlopen", side_effect=error):
+                with self.assertRaises(m.ScanError) as caught:
+                    api.get("/pulls")
+                self.assertNotIn("private-token", str(caught.exception))
+                self.assertNotIn("https://secret", str(caught.exception))
+        with self.assertRaises(m.ScanError):
+            m.GitHub("owner/repo/../../other", "token")
+
+    def test_main_writes_summary_and_is_advisory_on_failure(self):
+        with tempfile.TemporaryDirectory() as directory:
+            destination = Path(directory) / "summary"
+            with patch.dict(os.environ, {"GITHUB_REPOSITORY": "iflytek/skillhub",
+                                         "GITHUB_TOKEN": "token", "GITHUB_STEP_SUMMARY": str(destination)}):
+                with patch.object(m.GitHub, "pages", side_effect=m.ScanError("API unavailable")):
+                    self.assertEqual(m.main(), 1)
+                self.assertIn("scan incomplete", destination.read_text())
+                with patch.object(m, "scan", return_value=({}, [], 0)):
+                    self.assertEqual(m.main(), 0)
+                self.assertIn("No cross-PR version collisions", destination.read_text())
+
+    def test_full_multi_page_pr_and_file_collection(self):
+        class API(m.GitHub):
+            def __init__(self):
+                self.calls = []
+            def get(self, path):
+                self.calls.append(path)
+                if path.startswith("/pulls?"):
+                    start, end = (1, 101) if path.endswith("&page=1") else (101, 102)
+                    return [dict(number=n, head=dict(sha="sha"), base=dict(sha="base")) for n in range(start, end)]
+                if "/files?" in path:
+                    if path.endswith("&page=1"):
+                        return [dict(filename=PREFIX + f"V{i}__a.sql", status="added") for i in range(100)]
+                    return [dict(filename=PREFIX + "V100__a.sql", status="added")]
+                return dict(head=dict(sha="sha"), state="open", base=dict(sha="base"), changed_files=101)
+        api = API()
+        collisions, errors, count = m.scan(api)
+        self.assertEqual(count, 101)
+        self.assertEqual(len(collisions), 101)
+        self.assertEqual(len(collisions[100]), 101)
+        self.assertEqual(errors, [])
+        self.assertIn("/pulls/101/files?per_page=100&page=2", api.calls)
+
+    def test_workflow_trust_permissions_failure_fallback_and_ci_wiring(self):
+        workflow = (ROOT / ".github/workflows/migration-preflight.yml").read_text()
+        for expected in ("pull_request_target:", "schedule:", "workflow_dispatch:",
+                         "contents: read", "pull-requests: read", "continue-on-error: true",
+                         "ref: ${{ github.event.repository.default_branch }}", "persist-credentials: false",
+                         "No clearance issued", "python3 scripts/migration-preflight.py"):
+            self.assertIn(expected, workflow)
+        for forbidden in ("pull_request.head", "secrets.", "pull-requests: write", "issues: write"):
+            self.assertNotIn(forbidden, workflow)
+        scripts = (ROOT / ".github/workflows/pr-scripts.yml").read_text()
+        self.assertIn("'.github/workflows/migration-preflight.yml'", scripts)
+        self.assertIn("-p 'test_migration_preflight.py'", scripts)
+
+
 if __name__ == "__main__":
     unittest.main()

From c816215ae21b76a8d76301eacb9a133bde94723f Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Wed, 21 Oct 2026 16:33:15 +0800
Subject: [PATCH 06/17] fix(web): align supported Node toolchains and CI gates

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 .github/workflows/pr-e2e.yml   |  4 ++--
 .github/workflows/pr-tests.yml | 21 ++++++++++++++++++---
 .nvmrc                         |  2 +-
 CONTRIBUTING.md                |  4 +++-
 README_zh.md                   |  2 +-
 web/.npmrc                     |  1 +
 web/package.json               |  2 +-
 7 files changed, 27 insertions(+), 9 deletions(-)
 create mode 100644 web/.npmrc

diff --git a/.github/workflows/pr-e2e.yml b/.github/workflows/pr-e2e.yml
index 29fb694a0..ee692d0ca 100644
--- a/.github/workflows/pr-e2e.yml
+++ b/.github/workflows/pr-e2e.yml
@@ -43,12 +43,12 @@ jobs:
       - name: Set up pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 9
+          package_json_file: web/package.json
 
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: pnpm
           cache-dependency-path: web/pnpm-lock.yaml
 
diff --git a/.github/workflows/pr-tests.yml b/.github/workflows/pr-tests.yml
index 15e18e5db..0345552fc 100644
--- a/.github/workflows/pr-tests.yml
+++ b/.github/workflows/pr-tests.yml
@@ -18,7 +18,11 @@ permissions:
 
 jobs:
   web-tests:
-    name: Web Build And Test
+    name: Web Build And Test (Node ${{ matrix.node }})
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [22, 24]
     if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
     runs-on: ubuntu-latest
 
@@ -31,12 +35,12 @@ jobs:
       - name: Set up pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 9
+          package_json_file: web/package.json
 
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: ${{ matrix.node }}
           cache: pnpm
           cache-dependency-path: web/pnpm-lock.yaml
 
@@ -46,6 +50,17 @@ jobs:
       - name: Run frontend unit tests
         run: make test-frontend
 
+  web-tests-gate:
+    name: Web Build And Test
+    needs: web-tests
+    if: ${{ always() && (github.event_name != 'pull_request' || !github.event.pull_request.draft) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require both supported Node.js versions
+        env:
+          WEB_TESTS_RESULT: ${{ needs.web-tests.result }}
+        run: test "$WEB_TESTS_RESULT" = success
+
   server-tests:
     name: Server Unit Tests
     if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
diff --git a/.nvmrc b/.nvmrc
index 209e3ef4b..2bd5a0a98 100644
--- a/.nvmrc
+++ b/.nvmrc
@@ -1 +1 @@
-20
+22
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dad2d10a6..fc9ad708a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,7 +24,9 @@ Prerequisites:
 
 - Docker and Docker Compose
 - Java 21
-- Node.js 20 or 22 (see `.nvmrc`; Node 25+ currently breaks jsdom-based web tests — #991) and `pnpm`
+- For the web frontend: Node.js 22.13+ (22.x, default in `.nvmrc`) or 24.x, and the pnpm version declared in `web/package.json`. Other Node.js majors are not supported for frontend development (see #991).
+
+Use `nvm install && nvm use` from the repository root, then enable Corepack (`corepack enable`). Frontend dependency installation enforces this Node.js range via `web/.npmrc`; CI builds and tests both supported majors. CLI and integration packages retain their own runtime requirements.
 
 Start the local stack:
 
diff --git a/README_zh.md b/README_zh.md
index f84bb3000..326933b00 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -164,7 +164,7 @@ skillhub list
 ### 前置要求
 
 - Java 21+
-- Node.js 20+
+- 前端开发：Node.js 22.13+（22.x，默认）或 24.x；pnpm 版本以 `web/package.json` 为准。可在仓库根目录执行 `nvm install && nvm use` 选择默认版本。
 - Docker & Docker Compose
 - Make
 
diff --git a/web/.npmrc b/web/.npmrc
new file mode 100644
index 000000000..b6f27f135
--- /dev/null
+++ b/web/.npmrc
@@ -0,0 +1 @@
+engine-strict=true
diff --git a/web/package.json b/web/package.json
index a1d9924c1..7dcec5336 100644
--- a/web/package.json
+++ b/web/package.json
@@ -94,6 +94,6 @@
     "vitest": "^4.1.11"
   },
   "engines": {
-    "node": ">=20 <25"
+    "node": "^22.13.0 || ^24.0.0"
   }
 }

From 3b305bbc58d7ba3f3f57489834dca60fbfd938a3 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Wed, 21 Oct 2026 17:26:19 +0800
Subject: [PATCH 07/17] fix(ci): prepare Go before backend integration tests

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 .github/workflows/backend-tests.yml | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/.github/workflows/backend-tests.yml b/.github/workflows/backend-tests.yml
index e8047c8eb..adf3af883 100644
--- a/.github/workflows/backend-tests.yml
+++ b/.github/workflows/backend-tests.yml
@@ -20,5 +20,15 @@ jobs:
           java-version: 21
           cache: maven
 
+      - name: Set up Go for integration tests
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: github-sync-go/go.mod
+          cache-dependency-path: github-sync-go/go.mod
+
+      - name: Compile Go integration test dependencies
+        working-directory: github-sync-go
+        run: go test ./internal/worker -run '^$'
+
       - name: Backend tests
         run: cd server && ./mvnw -B test

From 2f7b0c73e31c0cb6c8ee0afb466246fa58142338 Mon Sep 17 00:00:00 2001
From: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
Date: Thu, 22 Oct 2026 07:24:13 +0000
Subject: [PATCH 08/17] fix(deps): patch Vite vulnerabilities in web and docs

Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
---
 docs/skillhub/package-lock.json |  6 +++---
 docs/skillhub/package.json      |  2 +-
 web/package.json                |  4 ++--
 web/pnpm-lock.yaml              | 36 ++++++++++++++++-----------------
 4 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/docs/skillhub/package-lock.json b/docs/skillhub/package-lock.json
index e7b051b49..a920bf1fd 100644
--- a/docs/skillhub/package-lock.json
+++ b/docs/skillhub/package-lock.json
@@ -2473,9 +2473,9 @@
       }
     },
     "node_modules/vite": {
-      "version": "6.4.3",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz",
-      "integrity": "sha512-NTKlcQjlAK7MlQoyb6LgaqHc8sso/pVyUJYWMws3jg21uTJw/LddqIFPcPqP6PzpgbIcZyKI85sFE4HBrQDA8A==",
+      "version": "6.4.5",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.5.tgz",
+      "integrity": "sha512-4enwjFfi4IwtEh0w+jPzpLVOFQiPHmmzPxcHXQOyEur47o6u0jE573DmGpjA+7irXoMLYRZD5ZaFUEneS3abPg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
diff --git a/docs/skillhub/package.json b/docs/skillhub/package.json
index d427b77b1..5f0272ee9 100644
--- a/docs/skillhub/package.json
+++ b/docs/skillhub/package.json
@@ -11,7 +11,7 @@
     "vitepress": "^1.6.3"
   },
   "overrides": {
-    "vite": "^6.4.3",
+    "vite": "^6.4.4",
     "postcss": "^8.5.23",
     "esbuild": "^0.28.1",
     "vue": "^3.5.42",
diff --git a/web/package.json b/web/package.json
index 7dcec5336..15bc5e519 100644
--- a/web/package.json
+++ b/web/package.json
@@ -9,7 +9,7 @@
       "esbuild"
     ],
     "overrides": {
-      "vite@<6.4.3": "^6.4.3",
+      "vite@<6.4.4": "^6.4.4",
       "esbuild@<0.28.1": "^0.28.1",
       "js-yaml@<4.3.2": "^4.3.2",
       "browserslist@<4.28.7": "^4.28.7",
@@ -90,7 +90,7 @@
     "postcss": "^8.5.23",
     "tailwindcss": "^3.4.0",
     "typescript": "^5.7.0",
-    "vite": "^6.4.3",
+    "vite": "^6.4.4",
     "vitest": "^4.1.11"
   },
   "engines": {
diff --git a/web/pnpm-lock.yaml b/web/pnpm-lock.yaml
index 7e2943387..1a49b3826 100644
--- a/web/pnpm-lock.yaml
+++ b/web/pnpm-lock.yaml
@@ -5,7 +5,7 @@ settings:
   excludeLinksFromLockfile: false
 
 overrides:
-  vite@<6.4.3: ^6.4.3
+  vite@<6.4.4: ^6.4.4
   esbuild@<0.28.1: ^0.28.1
   js-yaml@<4.3.2: ^4.3.2
   browserslist@<4.28.7: ^4.28.7
@@ -136,7 +136,7 @@ importers:
         version: 7.18.0(eslint@8.57.1)(typescript@5.9.3)
       '@vitejs/plugin-react':
         specifier: ^4.3.0
-        version: 4.7.0(vite@6.4.3(jiti@1.21.7))
+        version: 4.7.0(vite@6.4.5(jiti@1.21.7))
       autoprefixer:
         specifier: ^10.4.0
         version: 10.4.27(postcss@8.5.26)
@@ -165,11 +165,11 @@ importers:
         specifier: ^5.7.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.3
-        version: 6.4.3(jiti@1.21.7)
+        specifier: ^6.4.4
+        version: 6.4.5(jiti@1.21.7)
       vitest:
         specifier: ^4.1.11
-        version: 4.1.11(jsdom@29.1.1)(vite@6.4.3(jiti@1.21.7))
+        version: 4.1.11(jsdom@29.1.1)(vite@6.4.5(jiti@1.21.7))
 
 packages:
 
@@ -1560,7 +1560,7 @@ packages:
     resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
     engines: {node: ^14.18.0 || >=16.0.0}
     peerDependencies:
-      vite: ^6.4.3
+      vite: ^6.4.4
 
   '@vitest/expect@4.1.11':
     resolution: {integrity: sha512-VX2x5vNJXET47KAFzwERI+KRMtTTCSWTfSMKsW7JsUsXV4psq++e3DvZpuTDOpHcxytiDs6p2nhVb2tVDiiUYw==}
@@ -1569,7 +1569,7 @@ packages:
     resolution: {integrity: sha512-2XJVD55d1o5AZous5CCGKS74g/riOj9odEt2bQpCVZeblHyHdnMeFl4jl0XjU21stf4mbjUkew2eXQZt65g5CQ==}
     peerDependencies:
       msw: ^2.4.9
-      vite: ^6.4.3
+      vite: ^6.4.4
     peerDependenciesMeta:
       msw:
         optional: true
@@ -3332,8 +3332,8 @@ packages:
   vfile@6.0.3:
     resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
 
-  vite@6.4.3:
-    resolution: {integrity: sha512-NTKlcQjlAK7MlQoyb6LgaqHc8sso/pVyUJYWMws3jg21uTJw/LddqIFPcPqP6PzpgbIcZyKI85sFE4HBrQDA8A==}
+  vite@6.4.5:
+    resolution: {integrity: sha512-4enwjFfi4IwtEh0w+jPzpLVOFQiPHmmzPxcHXQOyEur47o6u0jE573DmGpjA+7irXoMLYRZD5ZaFUEneS3abPg==}
     engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
     hasBin: true
     peerDependencies:
@@ -3388,7 +3388,7 @@ packages:
       '@vitest/ui': 4.1.11
       happy-dom: '*'
       jsdom: '*'
-      vite: ^6.4.3
+      vite: ^6.4.4
     peerDependenciesMeta:
       '@edge-runtime/vm':
         optional: true
@@ -4837,7 +4837,7 @@ snapshots:
       d3-selection: 3.0.0
       d3-transition: 3.0.1(d3-selection@3.0.0)
 
-  '@vitejs/plugin-react@4.7.0(vite@6.4.3(jiti@1.21.7))':
+  '@vitejs/plugin-react@4.7.0(vite@6.4.5(jiti@1.21.7))':
     dependencies:
       '@babel/core': 7.29.7
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.7)
@@ -4845,7 +4845,7 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 6.4.3(jiti@1.21.7)
+      vite: 6.4.5(jiti@1.21.7)
     transitivePeerDependencies:
       - supports-color
 
@@ -4858,13 +4858,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
-  '@vitest/mocker@4.1.11(vite@6.4.3(jiti@1.21.7))':
+  '@vitest/mocker@4.1.11(vite@6.4.5(jiti@1.21.7))':
     dependencies:
       '@vitest/spy': 4.1.11
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 6.4.3(jiti@1.21.7)
+      vite: 6.4.5(jiti@1.21.7)
 
   '@vitest/pretty-format@4.1.11':
     dependencies:
@@ -6927,7 +6927,7 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vite@6.4.3(jiti@1.21.7):
+  vite@6.4.5(jiti@1.21.7):
     dependencies:
       esbuild: 0.28.1
       fdir: 6.5.0(picomatch@4.0.4)
@@ -6939,10 +6939,10 @@ snapshots:
       fsevents: 2.3.3
       jiti: 1.21.7
 
-  vitest@4.1.11(jsdom@29.1.1)(vite@6.4.3(jiti@1.21.7)):
+  vitest@4.1.11(jsdom@29.1.1)(vite@6.4.5(jiti@1.21.7)):
     dependencies:
       '@vitest/expect': 4.1.11
-      '@vitest/mocker': 4.1.11(vite@6.4.3(jiti@1.21.7))
+      '@vitest/mocker': 4.1.11(vite@6.4.5(jiti@1.21.7))
       '@vitest/pretty-format': 4.1.11
       '@vitest/runner': 4.1.11
       '@vitest/snapshot': 4.1.11
@@ -6959,7 +6959,7 @@ snapshots:
       tinyexec: 1.2.4
       tinyglobby: 0.2.15
       tinyrainbow: 3.1.0
-      vite: 6.4.3(jiti@1.21.7)
+      vite: 6.4.5(jiti@1.21.7)
       why-is-node-running: 2.3.0
     optionalDependencies:
       jsdom: 29.1.1

From 3402c07dbb6623cc628fd89b58c48ed4f3180483 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Thu, 22 Oct 2026 17:50:03 +0800
Subject: [PATCH 09/17] feat(dsh): add versioned skill examples and native task
 handoff

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 CONTEXT.md                                    |  17 +
 cli/README.md                                 |  37 ++
 cli/src/commands/publish.ts                   |  16 +-
 cli/src/commands/sync.ts                      |   6 +-
 cli/src/integrations/local-skills.ts          |   3 +
 cli/src/integrations/native-contract.d.ts     |   9 +
 cli/src/integrations/native-runtime.ts        |   2 +
 cli/src/integrations/recovery-files.ts        |  26 +-
 cli/src/platform/archive.ts                   |  32 +-
 cli/src/services/install-service.ts           |   2 +-
 cli/src/services/skill-examples-preflight.ts  |  65 +++
 cli/src/services/skill-examples.ts            |  87 ++++
 cli/src/services/skill-fingerprint.ts         |   2 +-
 cli/src/services/sync-service.ts              |  16 +-
 cli/test/helpers/fake-registry.ts             |   4 +-
 cli/test/integration/publish-command.test.ts  |  55 ++-
 cli/test/integration/sync-command.test.ts     |  42 ++
 .../integrations/install-recovery.test.ts     |   7 +-
 .../unit/integrations/native-install.test.ts  |   8 +-
 .../unit/integrations/native-upgrade.test.ts  |  10 +-
 .../integrations/upgrade-baseline.test.ts     |  11 +-
 cli/test/unit/platform/archive.test.ts        |  55 ++-
 .../unit/services/install-service.test.ts     |  27 +-
 .../services/skill-examples-preflight.test.ts |  67 +++
 cli/test/unit/services/skill-examples.test.ts |  84 ++++
 cli/test/unit/services/suite-service.test.ts  |  16 +-
 .../changes/add-dsh-native-plugin/README.md   |   8 +-
 .../add-dsh-native-plugin/acceptance.md       |  36 ++
 .../contracts/skill-examples.empty.json       |   7 +
 .../contracts/skill-examples.schema.json      |  61 +++
 .../contracts/skill-examples.valid.json       |  30 ++
 .../dsh-integration-design.md                 |  16 +
 .../implementation-design.md                  |   5 +
 .../add-dsh-native-plugin/interface-design.md |  24 ++
 .../add-dsh-native-plugin/lifecycle-design.md |   5 +
 .../add-dsh-native-plugin/product-design.md   |   7 +
 .../saas-agent-prompt.md                      |   2 +
 .../skill-examples-design.md                  | 202 +++++++++
 .../skill-examples-execution-plan.md          | 110 +++++
 .../skill-examples-saas-agent-prompt.md       |  77 ++++
 .../specs/dsh-native-experience/spec.md       | 132 ++++++
 .../changes/add-dsh-native-plugin/tasks.md    |  41 ++
 .../add-dsh-native-plugin/use-skill-design.md | 190 +++++++++
 .../add-dsh-native-plugin/verification.md     | 104 +++++
 plugins/dsh/README.en.md                      |   7 +
 plugins/dsh/README.md                         |   7 +
 plugins/dsh/bun.lock                          |  15 +
 plugins/dsh/package.json                      |   8 +-
 .../dsh/src/client/conversation-detail.tsx    |   6 +-
 plugins/dsh/src/client/index.tsx              |  54 ++-
 plugins/dsh/src/client/install-control.tsx    |   3 +
 plugins/dsh/src/client/install-dialog.tsx     |   2 +-
 plugins/dsh/src/client/install-tool-view.tsx  |   9 +-
 .../dsh/src/client/installation-progress.tsx  |   9 +-
 plugins/dsh/src/client/installed-skills.tsx   |   4 +
 .../dsh/src/client/native-control-styles.tsx  |  11 +
 plugins/dsh/src/client/use-skill-context.ts   |  36 ++
 plugins/dsh/src/client/use-skill-drafts.ts    |  51 +++
 .../dsh/src/client/use-skill-navigation.ts    |  63 +++
 plugins/dsh/src/client/use-skill.tsx          | 334 +++++++++++++++
 plugins/dsh/src/host/index.ts                 |  81 +++-
 plugins/dsh/src/host/local-runtime.ts         |   4 +
 plugins/dsh/src/host/runtime-compatibility.ts |   3 +
 plugins/dsh/src/host/skill-discovery.ts       |  60 ++-
 plugins/dsh/src/host/types.ts                 |   9 +
 .../dsh/test/client-entry-lifecycle.test.ts   |   6 +-
 .../dsh/test/install-control-state.test.tsx   |   9 +-
 plugins/dsh/test/package.test.ts              |  34 +-
 plugins/dsh/test/prepare-skill-use.test.ts    | 245 +++++++++++
 plugins/dsh/test/runtime-execution.test.ts    |   1 +
 plugins/dsh/test/use-skill-context.test.ts    |  60 +++
 plugins/dsh/test/use-skill-drafts.test.ts     |  82 ++++
 plugins/dsh/test/use-skill-navigation.test.ts |  71 ++++
 plugins/dsh/test/use-skill-render.test.tsx    |  55 +++
 plugins/dsh/test/use-skill.test.ts            | 386 ++++++++++++++++++
 .../dto/SkillPackagePreviewResponse.java      |  11 +-
 .../service/SkillPackagePreviewService.java   |   5 +-
 ...PackagePreviewSecurityIntegrationTest.java |  15 +
 .../SkillPackageArchiveExtractorTest.java     |  16 +
 .../dto/RegistryOpenApiSchemaTest.java        |   9 +
 .../SkillPackagePreviewServiceTest.java       |  30 ++
 .../validation/SkillExamplesSummary.java      | 101 +++++
 .../skill/validation/SkillPackagePolicy.java  |  19 +
 .../validation/SkillPackageValidator.java     |  23 ++
 .../validation/SkillExamplesSummaryTest.java  |  61 +++
 .../validation/SkillPackageValidatorTest.java |  38 ++
 web/src/api/generated/schema.d.ts             |   4 +
 web/src/features/publish/folder-zip.test.ts   |  15 +
 web/src/features/publish/folder-zip.ts        |   4 +
 web/src/i18n/locales/en.json                  |   3 +
 web/src/i18n/locales/ru.json                  |   3 +
 web/src/i18n/locales/zh.json                  |   3 +
 .../dashboard/publish-display-name.test.tsx   |  19 +
 web/src/pages/dashboard/publish.tsx           |   3 +
 94 files changed, 3778 insertions(+), 92 deletions(-)
 create mode 100644 cli/src/services/skill-examples-preflight.ts
 create mode 100644 cli/src/services/skill-examples.ts
 create mode 100644 cli/test/unit/services/skill-examples-preflight.test.ts
 create mode 100644 cli/test/unit/services/skill-examples.test.ts
 create mode 100644 openspec/changes/add-dsh-native-plugin/contracts/skill-examples.empty.json
 create mode 100644 openspec/changes/add-dsh-native-plugin/contracts/skill-examples.schema.json
 create mode 100644 openspec/changes/add-dsh-native-plugin/contracts/skill-examples.valid.json
 create mode 100644 openspec/changes/add-dsh-native-plugin/skill-examples-design.md
 create mode 100644 openspec/changes/add-dsh-native-plugin/skill-examples-execution-plan.md
 create mode 100644 openspec/changes/add-dsh-native-plugin/skill-examples-saas-agent-prompt.md
 create mode 100644 openspec/changes/add-dsh-native-plugin/use-skill-design.md
 create mode 100644 plugins/dsh/src/client/use-skill-context.ts
 create mode 100644 plugins/dsh/src/client/use-skill-drafts.ts
 create mode 100644 plugins/dsh/src/client/use-skill-navigation.ts
 create mode 100644 plugins/dsh/src/client/use-skill.tsx
 create mode 100644 plugins/dsh/test/prepare-skill-use.test.ts
 create mode 100644 plugins/dsh/test/use-skill-context.test.ts
 create mode 100644 plugins/dsh/test/use-skill-drafts.test.ts
 create mode 100644 plugins/dsh/test/use-skill-navigation.test.ts
 create mode 100644 plugins/dsh/test/use-skill-render.test.tsx
 create mode 100644 plugins/dsh/test/use-skill.test.ts
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillExamplesSummary.java
 create mode 100644 server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/skill/validation/SkillExamplesSummaryTest.java

diff --git a/CONTEXT.md b/CONTEXT.md
index b48ada16f..7932b318d 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -26,3 +26,20 @@ _Avoid_: 将空间负责人直接称为所有技能的作者。
 
 **历史作者**：某次历史内容提交的实际作者。历史作者与技能当前所有者可能是不同用户。
 _Avoid_: 把所有权转移描述为改写历史作者。
+
+## 技能使用
+
+**任务草稿**：用户尚未提交给 Agent、可以继续编辑的任务内容。准备任务草稿不表示任务已经执行。
+_Avoid_：将“填入输入框”称为“执行案例”或“任务已开始”。
+
+**技能任务模板**：技能作者为某项技能提供的可复用任务描述，供用户选择后形成可编辑的任务草稿。同一技能可以有多条模板，不同技能拥有各自的模板集合。
+_Avoid_：将统一引导文案称为技能专属案例，或将任务模板混同完整成果案例。
+
+**案例内容更新**：对技能任务模板内容的调整；首期作为技能版本内容随包发布，通过对应技能版本更新交付。
+_Avoid_：将尚未支持的独立刷新描述为已具备能力。
+
+**技能案例文件**：技能包内固定位置的任务模板声明，上传、下载和安装后保持同一相对路径；符合协议时作为案例识别，否则按普通文件保留。
+_Avoid_：将案例文件当成安装器内部记录、独立缓存或技能可调用的证明。
+
+**技能占位符**：任务模板 prompt 中的精确标记 `{{skill}}`，在使用核验通过后替换为当前技能的真实原生调用，不表示任意模板变量或执行能力。
+_Avoid_：用市场 slug 猜测技能调用，或把占位符替换称为执行模板代码。
diff --git a/cli/README.md b/cli/README.md
index f4a2e1f52..1657d4c71 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -563,3 +563,40 @@ skillhub doctor
 Apache-2.0
 
 Copyright 2026 iFlytek Co., Ltd.
+
+## Packaged task examples
+
+Authors can include `.skillhub/examples.json` in a skill package. The file stays at the same
+path after publishing and installation. It is versioned skill content, including when its
+JSON does not conform to the examples protocol; local edits are protected by existing
+upgrade/sync integrity checks. No separate Web configuration is required.
+
+```json
+{
+  "schemaVersion": 1,
+  "defaultLocale": "zh-CN",
+  "examples": {
+    "zh-CN": [{ "id": "summary", "title": "整理纪要", "prompt": "请用 {{skill}} 整理会议记录。" }],
+    "en": [{ "id": "summary", "title": "Summarize notes", "prompt": "Use {{skill}} to summarize meeting notes." }]
+  }
+}
+```
+
+The native DSH plugin recognizes this bounded UTF-8 declaration and offers editable task
+prompts. Unsupported declarations remain ordinary package files. See the
+[protocol and limits](../openspec/changes/add-dsh-native-plugin/skill-examples-design.md).
+Only `.skillhub/metadata.json` is an installer-owned record: directory publishing and sync
+push omit it, and installation rejects a package that supplies it (including path aliases).
+Other authored `.skillhub` files are retained and fingerprinted.
+
+Older consumers that ignore the whole `.skillhub` directory do not support packages with
+these files. Publish/install them only with lifecycle-capable CLI/plugin builds; old package
+bytes and published fingerprints must remain unchanged. This is not transparent backward
+compatibility for existing binaries.
+
+Directory and ZIP publishing (`publish`, including `--dry-run`, and `sync push`) inspect the
+actual outgoing archive for task examples. Human output reports the recognition summary;
+`--json` keeps it in `examplesStatus`, `examplesCount` and `warnings` fields. Counts include
+all declared languages. An unsupported declaration generates a nonblocking warning and is
+still uploaded unchanged; an unreadable archive produces an inspection warning and remains
+subject to the server's package validation.
diff --git a/cli/src/commands/publish.ts b/cli/src/commands/publish.ts
index e21bc4ac4..d842fe7ff 100644
--- a/cli/src/commands/publish.ts
+++ b/cli/src/commands/publish.ts
@@ -7,6 +7,7 @@ import { resolveRegistry, resolveToken } from '../services/registry-service'
 import { CliError } from '../shared/errors'
 import { EXIT } from '../shared/constants'
 import { createZip, isZipFile } from '../platform/archive'
+import { inspectPackagedExamples, examplesPreflightLine } from '../services/skill-examples-preflight'
 
 export interface PublishCommandOptions {
   namespace?: string
@@ -50,17 +51,20 @@ export async function publishCommand(path: string, options: PublishCommandOption
     }
   } else if (pathStat.isDirectory()) {
     archiveBlob = await createZip(path, {
-      exclude: relativePath => relativePath === '.skillhub' || relativePath.startsWith('.skillhub/')
+      exclude: relativePath => relativePath.toLowerCase() === '.skillhub/metadata.json'
     })
     archiveName = `${basename(path)}.zip`
   } else {
     throw new CliError(`path must be a file or directory: ${path}`, EXIT.filesystem, { path })
   }
 
+  const examples = await inspectPackagedExamples(archiveBlob)
+  const summary = examplesPreflightLine(examples)
   const client = new SkillHubClient(registry, token)
 
   if (options.dryRun) {
-    const result = await client.validatePublish(namespace, archiveBlob, toServerVisibility(visibility), archiveName)
+    const validation = await client.validatePublish(namespace, archiveBlob, toServerVisibility(visibility), archiveName)
+    const result = { ...validation, ...examples, warnings: [...new Set([...validation.warnings, ...examples.warnings])] }
 
     if (options.json) {
       if (!result.valid) {
@@ -82,6 +86,7 @@ export async function publishCommand(path: string, options: PublishCommandOption
     if (result.resolvedVersion) {
       lines.push(`  Version: ${result.resolvedVersion}`)
     }
+    if (summary) lines.push(summary)
     if (result.errors.length > 0) {
       lines.push('Errors:')
       for (const error of result.errors) {
@@ -114,14 +119,17 @@ export async function publishCommand(path: string, options: PublishCommandOption
       version: result.version,
       visibility: result.visibility.toLowerCase(),
       status: result.status,
-      detailUrl
+      detailUrl,
+      ...examples
     })
   }
   return [
     `Submitted successfully: ${result.namespace}/${result.slug}@${result.version}`,
     `Status: ${result.status}`,
     `Detail: ${detailUrl}`,
-    'Check the Web page for final publish or review status.'
+    'Check the Web page for final publish or review status.',
+    ...(summary ? [summary] : []),
+    ...examples.warnings.map(warning => `Warning: ${warning}`)
   ].join('\n')
 }
 
diff --git a/cli/src/commands/sync.ts b/cli/src/commands/sync.ts
index 263693a9b..ca1536f73 100644
--- a/cli/src/commands/sync.ts
+++ b/cli/src/commands/sync.ts
@@ -1,3 +1,4 @@
+import { examplesPreflightLine } from '../services/skill-examples-preflight'
 import { join, resolve } from 'node:path'
 import { ConfigStore } from '../stores/config-store'
 import { CredentialsStore } from '../stores/credentials-store'
@@ -266,7 +267,10 @@ function renderPushResults(namespace: string, results: PushResultItem[], json: b
     const action = item.action === 'uploaded' || item.action === 'submitted-review' ? 'submitted' : item.action
     const status = item.status ? ` status=${item.status}` : ''
     const reviewStatus = item.reviewStatus ? ` reviewStatus=${item.reviewStatus}` : ''
-    return `${action.padEnd(16)} ${coordinate}${status}${reviewStatus}${detail}`
+    const summary = examplesPreflightLine({ ...item, warnings: item.warnings ?? [] })
+    return [`${action.padEnd(16)} ${coordinate}${status}${reviewStatus}${detail}`,
+      ...(summary ? [`  ${summary}`] : []),
+      ...(item.warnings ?? []).map(warning => `  Warning: ${warning}`)].join('\n')
   })
   if (!dryRun && results.some(item => item.action === 'uploaded' || item.action === 'submitted-review')) {
     lines.push('Check the Web page for final publish or review status.')
diff --git a/cli/src/integrations/local-skills.ts b/cli/src/integrations/local-skills.ts
index 44cdab6b4..d2092efbc 100644
--- a/cli/src/integrations/local-skills.ts
+++ b/cli/src/integrations/local-skills.ts
@@ -27,3 +27,6 @@ export type { UpdateAssessment, UpdateIdentity } from './update-assessment'
 export { inspectUpgradeBaseline } from './upgrade-baseline'
 export type { UpgradeBaseline } from './upgrade-baseline'
 export { inspectRemovalBaseline } from './removal-baseline'
+
+export { parseSkillExamples, readSkillExamples } from '../services/skill-examples'
+export type { SkillExample, SkillExamples } from '../services/skill-examples'
diff --git a/cli/src/integrations/native-contract.d.ts b/cli/src/integrations/native-contract.d.ts
index e6abdbcbe..e73e6c532 100644
--- a/cli/src/integrations/native-contract.d.ts
+++ b/cli/src/integrations/native-contract.d.ts
@@ -39,7 +39,16 @@ export interface UpdateAssessment {
   candidateVersion: string
 }
 
+export interface SkillExample { id: string; title: string; prompt: string }
+export type SkillExamples =
+  | { state: 'ready'; digest: string; defaultLocale: string; items: Record<string, SkillExample[]> }
+  | { state: 'none' }
+  | { state: 'invalid' }
+  | { state: 'unavailable'; retryable: boolean }
+
 export interface NativeRuntime {
+  /** Host-only fixed-path read after installation verification; never a Remote path argument. */
+  readSkillExamples(directory: string): Promise<SkillExamples>
   /** Host-only, read-only evidence; the callback must verify the actual scoped DSH content and resource directory. */
   observeInstallation(operationId: string, ownerId: string, trustedRoots: readonly string[],
     observe: (paths: readonly string[]) => Promise<boolean>): Promise<boolean>
diff --git a/cli/src/integrations/native-runtime.ts b/cli/src/integrations/native-runtime.ts
index 8df4dee86..17e9da44c 100644
--- a/cli/src/integrations/native-runtime.ts
+++ b/cli/src/integrations/native-runtime.ts
@@ -1,3 +1,4 @@
+import { readSkillExamples } from '../services/skill-examples'
 import { observeInstallationDiscovery } from './install-discovery'
 import { readInstalledProjection } from './installed-projection'
 import { assessSkillUpdate } from './update-assessment'
@@ -20,6 +21,7 @@ export async function openNativeRuntime(options: { stateDirectory: string; inven
   const inventory = new InventoryStore(options.inventoryHome)
   return {
     hostInstanceId: operations.hostInstanceId,
+    readSkillExamples,
     observeInstallation: (operationId, ownerId, trustedRoots, observe) => observeInstallationDiscovery({
       operations, inventory, operationId, ownerId, trustedRoots, observe
     }),
diff --git a/cli/src/integrations/recovery-files.ts b/cli/src/integrations/recovery-files.ts
index 2fd3fd4e5..da517ce9c 100644
--- a/cli/src/integrations/recovery-files.ts
+++ b/cli/src/integrations/recovery-files.ts
@@ -1,7 +1,8 @@
 import { lstat, readdir, realpath } from 'node:fs/promises'
-import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import type { OperationRecord } from './operation-store'
 import type { InstallMove } from '../services/install-transaction'
+import { readInstalledSkillMetadata } from '../services/installed-skill-metadata'
 
 export async function verifiedBackupPath(record: OperationRecord, move: InstallMove): Promise<string> {
   const root = dirname(move.canonicalSkillDir)
@@ -17,18 +18,29 @@ export async function verifiedBackupPath(record: OperationRecord, move: InstallM
 }
 
 export async function assertOwnedRegularTree(path: string): Promise<void> {
-  await inspectTree(path, path)
+  const authoredMetadataPaths: string[] = []
+  await inspectTree(path, path, authoredMetadataPaths)
+  if (!authoredMetadataPaths.length) return
+  const metadata = await readInstalledSkillMetadata(path)
+  const files = metadata.status === 'valid' ? metadata.metadata.files : undefined
+  if (authoredMetadataPaths.some(entry => !files || !(entry in files))) {
+    throw new Error('Untracked recovery metadata content')
+  }
 }
 
-async function inspectTree(path: string, root: string): Promise<void> {
+async function inspectTree(path: string, root: string, authoredMetadataPaths: string[]): Promise<void> {
   const info = await lstat(path)
   if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile())
     || (process.getuid && info.uid !== process.getuid())) throw new Error('Unsafe recovery path')
-  if (!info.isDirectory()) return
+  const local = relative(root, path).split('\\').join('/')
+  if (!info.isDirectory()) {
+    // Authored files are permitted only when the installed baseline records them.
+    if (local.split('/').includes('.skillhub') && local !== '.skillhub/metadata.json') authoredMetadataPaths.push(local)
+    return
+  }
   const names = await readdir(path)
-  // The fingerprint deliberately excludes .skillhub; do not silently delete untracked content there.
-  if (basename(path) === '.skillhub' && (path !== join(root, '.skillhub') || names.length !== 1 || names[0] !== 'metadata.json')) {
+  if (!names.length && local.split('/').includes('.skillhub') && local !== '.skillhub') {
     throw new Error('Untracked recovery metadata content')
   }
-  for (const name of names) await inspectTree(join(path, name), root)
+  for (const name of names) await inspectTree(join(path, name), root, authoredMetadataPaths)
 }
diff --git a/cli/src/platform/archive.ts b/cli/src/platform/archive.ts
index 2c2cc8bf0..0ea65d5b3 100644
--- a/cli/src/platform/archive.ts
+++ b/cli/src/platform/archive.ts
@@ -14,10 +14,10 @@ const ZIP64_MARKER_32 = 0xffffffff
  * Extract a zip archive buffer into the target directory.
  * Pure JS implementation using fflate — no system commands needed.
  */
-export async function extractZip(buffer: ArrayBuffer, targetDir: string): Promise<void> {
+export async function extractZip(buffer: ArrayBuffer, targetDir: string, options: { rejectInternalMetadata?: boolean } = {}): Promise<void> {
   await mkdir(targetDir, { recursive: true })
   const archive = new Uint8Array(buffer)
-  validateZipCentralDirectory(archive)
+  validateZipCentralDirectory(archive, options.rejectInternalMetadata ?? false)
   const files = unzipSync(archive)
   const entries = Object.entries(files).map(([name, data]) => ({
     name,
@@ -25,7 +25,7 @@ export async function extractZip(buffer: ArrayBuffer, targetDir: string): Promis
     filePath: safeJoin(targetDir, name),
   }))
   for (const { name, data, filePath } of entries) {
-    if (name.endsWith('/')) {
+    if (isZipDirectory(name)) {
       await mkdir(filePath, { recursive: true })
       continue
     }
@@ -34,7 +34,11 @@ export async function extractZip(buffer: ArrayBuffer, targetDir: string): Promis
   }
 }
 
-function validateZipCentralDirectory(archive: Uint8Array): void {
+function isZipDirectory(name: string): boolean {
+  return name.endsWith('/') || name.endsWith('\\')
+}
+
+function validateZipCentralDirectory(archive: Uint8Array, rejectInternalMetadata: boolean): void {
   const view = new DataView(archive.buffer, archive.byteOffset, archive.byteLength)
   const eocdOffset = findEndOfCentralDirectory(view)
   if (eocdOffset < 0) {
@@ -66,6 +70,7 @@ function validateZipCentralDirectory(archive: Uint8Array): void {
     throw new Error('invalid zip central directory')
   }
 
+  const destinations = new Map<string, boolean>()
   let offset = centralDirectoryOffset
   let totalUncompressedSize = 0
   const decoder = new TextDecoder()
@@ -85,6 +90,23 @@ function validateZipCentralDirectory(archive: Uint8Array): void {
     }
 
     const entryName = decoder.decode(archive.subarray(nameStart, nameEnd))
+    const normalized = entryName.replaceAll('\\', '/').split('/').filter(part => part !== '' && part !== '.')
+    if (normalized.some(part => part === '..' || (part.includes(':') || [...part].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)) || /[ .]$/.test(part))) {
+      throw new Error('unsafe zip entry path')
+    }
+    const destination = normalized.join('/').toLowerCase()
+    const directory = isZipDirectory(entryName)
+    if (rejectInternalMetadata && destination === '.skillhub/examples.json' && normalized.join('/') !== destination) {
+      throw new Error('Ambiguous skill examples path casing')
+    }
+    if (rejectInternalMetadata && ((!directory && destination === '.skillhub') || destination === '.skillhub/metadata.json' || destination.startsWith('.skillhub/metadata.json/'))) {
+      throw new Error('Installer metadata cannot be supplied by a skill package')
+    }
+    if (destinations.has(destination) || [...destinations].some(([path, isDirectory]) =>
+      (!isDirectory && destination.startsWith(path + '/')) || (!directory && path.startsWith(destination + '/')))) {
+      throw new Error('conflicting zip entry destinations')
+    }
+    destinations.set(destination, directory)
     if (!entryName.endsWith('/') && uncompressedSize > MAX_SINGLE_FILE_BYTES) {
       throw new Error('zip entry size exceeds limit')
     }
@@ -160,7 +182,7 @@ function safeJoin(targetDir: string, entryName: string): string {
   }
 
   const root = resolve(targetDir)
-  const target = resolve(root, entryName)
+  const target = resolve(root, entryName.replaceAll('\\', '/'))
   const rel = relative(root, target)
   if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
     throw new Error(`unsafe zip entry path: ${entryName}`)
diff --git a/cli/src/services/install-service.ts b/cli/src/services/install-service.ts
index 93c2acbb3..30ee649f8 100644
--- a/cli/src/services/install-service.ts
+++ b/cli/src/services/install-service.ts
@@ -145,7 +145,7 @@ export async function installSkill(options: InstallOptions): Promise<InstallResu
       await mkdir(tempDir, { mode: 0o700 })
       try {
         await options.authorizeTargetMutation?.([tempDir], 'staging')
-        await extractZip(buffer, tempDir)
+        await extractZip(buffer, tempDir, { rejectInternalMetadata: true })
 
         const installedAt = new Date().toISOString()
         const snapshot = await snapshotSkillDirectory(tempDir)
diff --git a/cli/src/services/skill-examples-preflight.ts b/cli/src/services/skill-examples-preflight.ts
new file mode 100644
index 000000000..8a1d99dd4
--- /dev/null
+++ b/cli/src/services/skill-examples-preflight.ts
@@ -0,0 +1,65 @@
+import { unzipSync } from 'fflate'
+import { MAX_EXAMPLES_BYTES, parseSkillExamples } from './skill-examples'
+
+export interface ExamplesPreflight {
+  examplesStatus?: 'ready' | 'none' | 'invalid'
+  examplesCount?: number
+  warnings: string[]
+}
+
+/** Advisory inspection of the exact uploaded bytes; server package validation remains authoritative. */
+export async function inspectPackagedExamples(archive: Blob): Promise<ExamplesPreflight> {
+  try {
+    const bytes = new Uint8Array(await archive.arrayBuffer())
+    const entries: Array<{ name: string; path: string; size: number; storedSize?: number }> = []
+    let entryCount = 0
+    // Collect names without inflating arbitrary resources or an oversized examples declaration.
+    unzipSync(bytes, { filter: file => {
+      if (++entryCount > 500) throw new Error('Package entry limit')
+      const path = file.name.replaceAll('\\', '/')
+      const basename = path.split('/').at(-1) ?? ''
+      if (!path.endsWith('/') && !path.startsWith('__MACOSX/') && path !== '__MACOSX'
+        && basename !== '.DS_Store' && !basename.startsWith('._')) {
+        const parts = path.split('/').filter(part => part !== '.' && part !== '')
+        if (basename.toLowerCase() === 'skill.md') parts[parts.length - 1] = 'SKILL.md'
+        entries.push({ name: file.name, path: parts.join('/'), size: file.originalSize,
+          ...(file.compression === 0 ? { storedSize: file.size } : {}) })
+      }
+      return false
+    } })
+    // Match the existing server extractor's single-root stripping and single-SKILL promotion.
+    if (entries.length && entries.every(entry => entry.path.includes('/'))
+      && new Set(entries.map(entry => entry.path.split('/')[0])).size === 1) {
+      for (const entry of entries) entry.path = entry.path.slice(entry.path.indexOf('/') + 1)
+    }
+    if (!entries.some(entry => entry.path === 'SKILL.md')) {
+      const roots = entries.filter(entry => /^[^/]+\/SKILL\.md$/.test(entry.path)).map(entry => entry.path.slice(0, -'SKILL.md'.length))
+      if (roots.length === 1) for (const entry of entries) {
+        entry.path = entry.path.startsWith(roots[0]!) ? entry.path.slice(roots[0]!.length) : ''
+      }
+    }
+    const candidates = entries.filter(entry => entry.path === '.skillhub/examples.json')
+    const entry = candidates[0]
+    if (!entry) return { examplesStatus: 'none', examplesCount: 0, warnings: [] }
+    if (candidates.length !== 1 || entry.size > MAX_EXAMPLES_BYTES
+      || (entry.storedSize !== undefined && (entry.storedSize > MAX_EXAMPLES_BYTES || entry.storedSize !== entry.size))) return invalid()
+    const selected = unzipSync(bytes, { filter: file => file.name === entry.name && file.originalSize <= MAX_EXAMPLES_BYTES
+      && (file.compression !== 0 || (file.size <= MAX_EXAMPLES_BYTES && file.size === file.originalSize)) })[entry.name]
+    const parsed = selected ? parseSkillExamples(selected) : { state: 'invalid' as const }
+    if (parsed.state !== 'ready') return invalid()
+    const count = Object.values(parsed.items).reduce((total, items) => total + items.length, 0)
+    return { examplesStatus: count ? 'ready' : 'none', examplesCount: count, warnings: [] }
+  } catch {
+    return { warnings: ['Task examples could not be inspected locally; server package validation will determine the result.'] }
+  }
+}
+
+function invalid(): ExamplesPreflight {
+  return { examplesStatus: 'invalid', warnings: ['.skillhub/examples.json is not a supported task-examples declaration; it remains ordinary package content.'] }
+}
+
+export function examplesPreflightLine(result: ExamplesPreflight): string | undefined {
+  if (result.examplesStatus === 'ready') return `Task examples: ${result.examplesCount} entries across all declared languages.`
+  if (result.examplesStatus === 'none') return 'Task examples: none.'
+  return undefined
+}
diff --git a/cli/src/services/skill-examples.ts b/cli/src/services/skill-examples.ts
new file mode 100644
index 000000000..d845d872f
--- /dev/null
+++ b/cli/src/services/skill-examples.ts
@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, open } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export interface SkillExample { id: string; title: string; prompt: string }
+export type SkillExamples =
+  | { state: 'ready'; digest: string; defaultLocale: string; items: Record<string, SkillExample[]> }
+  | { state: 'none' }
+  | { state: 'invalid' }
+  | { state: 'unavailable'; retryable: boolean }
+
+export const MAX_EXAMPLES_BYTES = 65_536
+const localePattern = /^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/
+// Explicit protocol whitespace code points, including ASCII controls.
+// eslint-disable-next-line no-control-regex
+const nonWhitespace = /[^\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]/u
+
+/** Parse author bytes without rewriting the immutable packaged file. */
+export function parseSkillExamples(bytes: Uint8Array): SkillExamples {
+  if (bytes.byteLength > MAX_EXAMPLES_BYTES) return { state: 'invalid' }
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes).replace(/^\uFEFF/, '')
+    const value: unknown = JSON.parse(text)
+    if (!record(value) || !exactKeys(value, ['schemaVersion', 'defaultLocale', 'examples'])
+      || value.schemaVersion !== 1 || typeof value.defaultLocale !== 'string' || !localePattern.test(value.defaultLocale)
+      || !record(value.examples)) return { state: 'invalid' }
+    const languages = Object.keys(value.examples)
+    if (languages.length < 1 || languages.length > 10) return { state: 'invalid' }
+    const normalized = new Set<string>()
+    const items: Record<string, SkillExample[]> = Object.create(null)
+    for (const locale of languages) {
+      const entries = value.examples[locale]
+      if (!localePattern.test(locale) || normalized.has(locale.toLowerCase())
+        || !Array.isArray(entries) || entries.length > 20) return { state: 'invalid' }
+      normalized.add(locale.toLowerCase())
+      const ids = new Set<string>()
+      const cases: SkillExample[] = []
+      for (const entry of entries) {
+        if (!record(entry) || !exactKeys(entry, ['id', 'title', 'prompt']) || typeof entry.id !== 'string'
+          || entry.id.length > 64 || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(entry.id) || ids.has(entry.id)
+          || !textWithin(entry.title, 80) || !textWithin(entry.prompt, 4000)) return { state: 'invalid' }
+        ids.add(entry.id)
+        cases.push({ id: entry.id, title: entry.title, prompt: entry.prompt })
+      }
+      items[locale] = cases
+    }
+    if (!normalized.has(value.defaultLocale.toLowerCase())) return { state: 'invalid' }
+    return { state: 'ready', digest: createHash('sha256').update(bytes).digest('hex'), defaultLocale: value.defaultLocale, items }
+  } catch { return { state: 'invalid' } }
+}
+
+/** Host-only fixed-path read; installation and winner verification remain the caller's responsibility. */
+export async function readSkillExamples(directory: string): Promise<SkillExamples> {
+  try {
+    const parent = await lstat(join(directory, '.skillhub'))
+    if (!parent.isDirectory() || parent.isSymbolicLink()) return { state: 'unavailable', retryable: false }
+    const path = join(directory, '.skillhub', 'examples.json')
+    const info = await lstat(path)
+    if (!info.isFile() || info.isSymbolicLink()) return { state: 'unavailable', retryable: false }
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
+    try {
+      if (!(await file.stat()).isFile()) return { state: 'unavailable', retryable: false }
+      const bytes = new Uint8Array(MAX_EXAMPLES_BYTES + 1)
+      let size = 0
+      while (size < bytes.length) {
+        const { bytesRead } = await file.read(bytes, size, bytes.length - size, size)
+        if (!bytesRead) break
+        size += bytesRead
+      }
+      return parseSkillExamples(bytes.subarray(0, size))
+    } finally { await file.close() }
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ENOENT'
+      ? { state: 'none' } : { state: 'unavailable', retryable: true }
+  }
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+function exactKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  return Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key))
+}
+function textWithin(value: unknown, maximum: number): value is string {
+  return typeof value === 'string' && [...value].length <= maximum && nonWhitespace.test(value)
+}
diff --git a/cli/src/services/skill-fingerprint.ts b/cli/src/services/skill-fingerprint.ts
index d73bfaa61..a439d1dbb 100644
--- a/cli/src/services/skill-fingerprint.ts
+++ b/cli/src/services/skill-fingerprint.ts
@@ -39,8 +39,8 @@ async function listSkillFiles(root: string): Promise<string[]> {
   async function walk(current: string): Promise<void> {
     const entries = await readdir(current, { withFileTypes: true })
     for (const entry of entries) {
-      if (entry.name === '.skillhub') continue
       const absolute = join(current, entry.name)
+      if (relative(root, absolute).split('\\').join('/') === '.skillhub/metadata.json') continue
       if (entry.isDirectory()) {
         await walk(absolute)
       } else if (entry.isFile()) {
diff --git a/cli/src/services/sync-service.ts b/cli/src/services/sync-service.ts
index 0ed460fe1..cdeeef684 100644
--- a/cli/src/services/sync-service.ts
+++ b/cli/src/services/sync-service.ts
@@ -10,6 +10,7 @@ import { pathExists } from '../platform/paths'
 import { compareSkillVersions } from './skill-version-order'
 import { CliError } from '../shared/errors'
 import { EXIT } from '../shared/constants'
+import { inspectPackagedExamples, type ExamplesPreflight } from './skill-examples-preflight'
 
 export type SyncStatus = 'up-to-date' | 'update-available' | 'local-changed' | 'blocked' | 'orphaned' | 'not-installed'
 
@@ -42,7 +43,7 @@ export interface PullResult {
   warnings: Array<{ slug: string; message: string }>
 }
 
-export interface PushResultItem {
+export interface PushResultItem extends Omit<ExamplesPreflight, 'warnings'> {
   path: string
   slug?: string
   version?: string
@@ -288,6 +289,7 @@ export async function pushSkills(options: {
   for (const path of options.paths) {
     try {
       const archive = await prepareArchive(path)
+      const examples = await inspectPackagedExamples(archive.blob)
       const validation = await options.client.validatePublish(
         options.namespace, archive.blob, options.visibility, archive.fileName, true)
       if (!validation.valid) {
@@ -295,7 +297,8 @@ export async function pushSkills(options: {
           path,
           action: 'failed',
           errors: validation.errors,
-          warnings: validation.warnings
+          ...examples,
+          warnings: [...new Set([...validation.warnings, ...examples.warnings])]
         }
         if (validation.resolvedSlug) failed.slug = validation.resolvedSlug
         if (validation.resolvedVersion) failed.version = validation.resolvedVersion
@@ -306,7 +309,8 @@ export async function pushSkills(options: {
         const validated: PushResultItem = {
           path,
           action: 'validated',
-          warnings: validation.warnings
+          ...examples,
+          warnings: [...new Set([...validation.warnings, ...examples.warnings])]
         }
         if (validation.resolvedSlug) validated.slug = validation.resolvedSlug
         if (validation.resolvedVersion) validated.version = validation.resolvedVersion
@@ -340,7 +344,9 @@ export async function pushSkills(options: {
         version: published.version,
         status,
         action,
-        ...(reviewStatus ? { reviewStatus } : {})
+        ...(reviewStatus ? { reviewStatus } : {}),
+        ...examples,
+        warnings: [...new Set([...validation.warnings, ...examples.warnings])]
       })
     } catch (error) {
       results.push({ path, action: 'failed', errors: [error instanceof Error ? error.message : 'push failed'] })
@@ -365,7 +371,7 @@ async function prepareArchive(path: string): Promise<{ blob: Blob; fileName: str
   const pathStat = await stat(path)
   if (pathStat.isDirectory()) {
     return {
-      blob: await createZip(path, { exclude: relativePath => relativePath === '.skillhub' || relativePath.startsWith('.skillhub/') }),
+      blob: await createZip(path, { exclude: relativePath => relativePath.toLowerCase() === '.skillhub/metadata.json' }),
       fileName: `${basename(path)}.zip`
     }
   }
diff --git a/cli/test/helpers/fake-registry.ts b/cli/test/helpers/fake-registry.ts
index 1ebdbf7a9..81979ed57 100644
--- a/cli/test/helpers/fake-registry.ts
+++ b/cli/test/helpers/fake-registry.ts
@@ -85,8 +85,8 @@ function resolveSkillFingerprint(skill: FakeSkill): string {
   const entries = unzipSync(skill.zipBytes ?? MINIMAL_ZIP)
   const aggregate = createHash('sha256')
   for (const path of Object.keys(entries)
-    .filter(path => !path.endsWith('/') && path !== '.skillhub' && !path.startsWith('.skillhub/'))
-    .sort((left, right) => left.localeCompare(right))) {
+    .filter(path => !path.endsWith('/') && path !== '.skillhub/metadata.json')
+    .sort()) {
     const fileHash = createHash('sha256').update(entries[path]!).digest('hex')
     aggregate.update(`${path}:${fileHash}\n`, 'utf8')
   }
diff --git a/cli/test/integration/publish-command.test.ts b/cli/test/integration/publish-command.test.ts
index 5a1140d9e..ce1cb79fc 100644
--- a/cli/test/integration/publish-command.test.ts
+++ b/cli/test/integration/publish-command.test.ts
@@ -125,6 +125,7 @@ describe('publish command — P0', () => {
     const dir = await makeTempDir(['SKILL.md', '# Demo'])
     await mkdir(join(dir, '.skillhub'), { recursive: true })
     await writeFile(join(dir, '.skillhub', 'metadata.json'), '{"registry":"private"}')
+    await writeFile(join(dir, '.skillhub', 'examples.json'), '{invalid authored content}')
 
     const result = await runCli(['publish', dir, '--registry', registry.url], {
       HOME: env.home,
@@ -133,7 +134,8 @@ describe('publish command — P0', () => {
 
     expect(result.exitCode).toBe(0)
     expect(registry.received.publish!.archiveEntries).toContain('SKILL.md')
-    expect(registry.received.publish!.archiveEntries.some(path => path.startsWith('.skillhub'))).toBe(false)
+    expect(registry.received.publish!.archiveEntries).not.toContain('.skillhub/metadata.json')
+    expect(registry.received.publish!.archiveEntries).toContain('.skillhub/examples.json')
   })
 
   test('zip file happy path: exit 0, fileName matches passed file', async () => {
@@ -616,3 +618,54 @@ describe('publish command — content shape', () => {
     }
   })
 })
+
+const examplesContent = JSON.stringify({ schemaVersion: 1, defaultLocale: 'zh-CN', examples: {
+  'zh-CN': [{ id: 'summary', title: '摘要', prompt: '请使用 {{skill}} 总结。' }],
+  en: [{ id: 'summary', title: 'Summary', prompt: 'Use {{skill}}.' }]
+} })
+
+for (const format of ['directory', 'zip'] as const) {
+  for (const state of ['ready', 'invalid', 'none'] as const) {
+    test.each([true, false])(`publish ${format} provides nonblocking ${state} examples feedback (json=%s)`, async json => {
+      const env = await createTempHome()
+      registry = await startFakeRegistry({ token: 'sk_ok' })
+      const directory = await makeTempDir(['SKILL.md', '# Demo'])
+      const content = state === 'ready' ? examplesContent : '{malformed author content}'
+      if (state !== 'none') {
+        await mkdir(join(directory, '.skillhub'), { recursive: true })
+        await writeFile(join(directory, '.skillhub/examples.json'), content)
+      }
+      let path = directory
+      if (format === 'zip') {
+        path = join(directory, 'package.zip')
+        await writeFile(path, zipSync({ 'SKILL.md': new TextEncoder().encode('# Demo'),
+          ...(state !== 'none' ? { '.skillhub/examples.json': new TextEncoder().encode(content) } : {}) }))
+      }
+      const result = await runCli(['publish', path, '--registry', registry.url, '--token', 'sk_ok', ...(json ? ['--json'] : [])], { HOME: env.home })
+      expect(result.exitCode).toBe(0)
+      expect(registry.received.publish).not.toBeNull()
+      if (json) {
+        const output = JSON.parse(result.stdout)
+        expect(output.examplesStatus).toBe(state)
+        expect(output.examplesCount).toBe(state === 'ready' ? 2 : state === 'none' ? 0 : undefined)
+        expect(output.warnings).toHaveLength(state === 'invalid' ? 1 : 0)
+      } else {
+        expect(result.stdout).toContain(state === 'invalid' ? 'remains ordinary package content' : state === 'ready' ? 'Task examples: 2' : 'Task examples: none')
+      }
+      if (state !== 'none') expect(registry.received.publish!.archiveEntries).toContain('.skillhub/examples.json')
+    })
+  }
+}
+
+test.each([true, false])('publish dry-run reports malformed ZIP examples without submitting (json=%s)', async json => {
+  const env = await createTempHome()
+  registry = await startFakeRegistry({ token: 'sk_ok' })
+  const directory = await makeTempDir()
+  const path = join(directory, 'skill.zip')
+  await writeFile(path, zipSync({ 'SKILL.md': new TextEncoder().encode('# Demo'), '.skillhub/examples.json': new TextEncoder().encode('{broken') }))
+  const result = await runCli(['publish', path, '--dry-run', '--registry', registry.url, '--token', 'sk_ok', ...(json ? ['--json'] : [])], { HOME: env.home })
+  expect(result.exitCode).toBe(0)
+  expect(registry.received.publish).toBeNull()
+  if (json) expect(JSON.parse(result.stdout)).toMatchObject({ valid: true, examplesStatus: 'invalid', warnings: [expect.stringContaining('ordinary package content')] })
+  else expect(result.stdout).toContain('remains ordinary package content')
+})
diff --git a/cli/test/integration/sync-command.test.ts b/cli/test/integration/sync-command.test.ts
index faaa5731f..738af3afc 100644
--- a/cli/test/integration/sync-command.test.ts
+++ b/cli/test/integration/sync-command.test.ts
@@ -647,6 +647,7 @@ describe('sync command', () => {
     await mkdir(join(skillDir, '.skillhub'), { recursive: true })
     await writeFile(join(skillDir, 'SKILL.md'), '---\nname: demo\ndescription: Demo\nversion: 1.0.0\n---\n')
     await writeFile(join(skillDir, '.skillhub', 'metadata.json'), '{"must":"not be uploaded"}')
+    await writeFile(join(skillDir, '.skillhub', 'examples.json'), '{invalid authored content}')
     const registry = await startFakeRegistry({ token: 'token', publishStatus: 'UPLOADED' })
 
     try {
@@ -663,6 +664,8 @@ describe('sync command', () => {
       })
       expect(registry.received.publish?.visibility).toBe('NAMESPACE_ONLY')
       expect(registry.received.publish?.rejectExistingVersion).toBe(true)
+      expect(registry.received.publish?.archiveEntries).toContain('.skillhub/examples.json')
+      expect(registry.received.publish?.archiveEntries).not.toContain('.skillhub/metadata.json')
       expect(registry.received.review).toMatchObject({
         namespace: 'team-a', slug: 'demo', version: '1.0.0', targetVisibility: 'NAMESPACE_ONLY'
       })
@@ -805,3 +808,42 @@ describe('sync command', () => {
     }
   })
 })
+
+
+test.each([true, false])('sync push keeps malformed examples and reports nonblocking warnings (dryRun=%s)', async dryRun => {
+  const env = await createTempHome()
+  const directory = await makeLocalSkill(env.cwd)
+  await mkdir(join(directory, '.skillhub'), { recursive: true })
+  await writeFile(join(directory, '.skillhub/examples.json'), '{invalid but publishable}')
+  const registry = await startFakeRegistry({ token: 'token' })
+  try {
+    for (const json of [true, false]) {
+      const result = await runCli(['sync', 'push', directory, '--namespace', 'team-a', '--registry', registry.url, '--token', 'token',
+        ...(dryRun ? ['--dry-run'] : []), ...(json ? ['--json'] : [])], { HOME: env.home }, { cwd: env.cwd })
+      expect(result.exitCode).toBe(0)
+      if (json) {
+        const item = JSON.parse(result.stdout).items[0]
+        expect(item.examplesStatus).toBe('invalid')
+        expect(item.warnings).toHaveLength(1)
+        expect(item.action).toBe(dryRun ? 'validated' : 'uploaded')
+      } else expect(result.stdout).toContain('remains ordinary package content')
+    }
+    if (!dryRun) expect(registry.received.publish!.archiveEntries).toContain('.skillhub/examples.json')
+  } finally { registry.stop() }
+})
+
+test.each(['ready', 'none'] as const)('sync push reports %s examples for raw ZIP in JSON and human output', async state => {
+  const env = await createTempHome()
+  const path = join(env.cwd, 'skill.zip')
+  const content = JSON.stringify({ schemaVersion: 1, defaultLocale: 'en', examples: { en: [{ id: 'one', title: 'One', prompt: 'Use {{skill}}' }] } })
+  await writeFile(path, zipSync({ 'SKILL.md': strToU8('# Demo'), ...(state === 'ready' ? { '.skillhub/examples.json': strToU8(content) } : {}) }))
+  const registry = await startFakeRegistry({ token: 'token' })
+  try {
+    for (const json of [true, false]) {
+      const result = await runCli(['sync', 'push', path, '--namespace', 'team-a', '--registry', registry.url, '--token', 'token', ...(json ? ['--json'] : [])], { HOME: env.home }, { cwd: env.cwd })
+      expect(result.exitCode).toBe(0)
+      if (json) expect(JSON.parse(result.stdout).items[0]).toMatchObject({ examplesStatus: state, examplesCount: state === 'ready' ? 1 : 0, warnings: [] })
+      else expect(result.stdout).toContain(state === 'ready' ? 'Task examples: 1' : 'Task examples: none')
+    }
+  } finally { registry.stop() }
+})
diff --git a/cli/test/unit/integrations/install-recovery.test.ts b/cli/test/unit/integrations/install-recovery.test.ts
index 1992c6da0..ca8089812 100644
--- a/cli/test/unit/integrations/install-recovery.test.ts
+++ b/cli/test/unit/integrations/install-recovery.test.ts
@@ -14,11 +14,14 @@ import { acquireSkillTargetLock } from '../../../src/services/skill-target-lock'
 import { InventoryCommitUnknownError, InventoryStore, type Inventory } from '../../../src/stores/inventory-store'
 
 const content = '# Recovery fixture'
-const fingerprint = 'sha256:' + createHash('sha256').update('SKILL.md:' + createHash('sha256').update(content).digest('hex') + '\n').digest('hex')
+const examples = '{invalid but preserved versioned examples}'
+const fingerprint = 'sha256:' + createHash('sha256')
+  .update('.skillhub/examples.json:' + createHash('sha256').update(examples).digest('hex') + '\n')
+  .update('SKILL.md:' + createHash('sha256').update(content).digest('hex') + '\n').digest('hex')
 const identity = { registry: 'https://registry.example', namespace: 'team', slug: 'writer' }
 class LocalClient extends SkillHubClient {
   async download(): Promise<Response> {
-    return new Response(new Uint8Array(zipSync({ 'SKILL.md': new TextEncoder().encode(content) })).buffer)
+    return new Response(new Uint8Array(zipSync({ 'SKILL.md': new TextEncoder().encode(content), '.skillhub/examples.json': new TextEncoder().encode(examples) })).buffer)
   }
 }
 
diff --git a/cli/test/unit/integrations/native-install.test.ts b/cli/test/unit/integrations/native-install.test.ts
index 00c207a37..f400adbcc 100644
--- a/cli/test/unit/integrations/native-install.test.ts
+++ b/cli/test/unit/integrations/native-install.test.ts
@@ -12,7 +12,10 @@ import type { NativeInstallExecution } from '../../../src/integrations/native-co
 async function fixture(downloadFailure = false) {
   const root = await realpath(await mkdtemp(join(tmpdir(), 'skillhub-native-execution-')))
   const content = '# Native fixture'
-  const fingerprint = 'sha256:' + createHash('sha256').update('SKILL.md:' + createHash('sha256').update(content).digest('hex') + '\n').digest('hex')
+  const examples = '{invalid but preserved versioned examples}'
+  const fingerprint = 'sha256:' + createHash('sha256')
+    .update('.skillhub/examples.json:' + createHash('sha256').update(examples).digest('hex') + '\n')
+    .update('SKILL.md:' + createHash('sha256').update(content).digest('hex') + '\n').digest('hex')
   let downloads = 0
   let releaseChanged = false
   const server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch(request) {
@@ -22,7 +25,7 @@ async function fixture(downloadFailure = false) {
     } })
     downloads++
     if (downloadFailure) return new Response('missing', { status: 404 })
-    return new Response(new Uint8Array(zipSync({ 'SKILL.md': new TextEncoder().encode(content) })).buffer)
+    return new Response(new Uint8Array(zipSync({ 'SKILL.md': new TextEncoder().encode(content), '.skillhub/examples.json': new TextEncoder().encode(examples) })).buffer)
   } })
   const registry = server.url.origin
   const stateDirectory = join(root, 'operations')
@@ -52,6 +55,7 @@ test('a new request for the same complete installation returns already-installed
     expect(await f.runtime.executeInstall(second)).toMatchObject({ outcome: 'committed', reason: 'already-installed' })
     expect((await f.runtime.getOperation(second.operationId, second.ownerId))?.files).toBe('already-installed')
     expect(f.downloads()).toBe(1)
+    expect(await readFile(join(f.root, 'skills/writer/.skillhub/examples.json'), 'utf8')).toBe('{invalid but preserved versioned examples}')
   } finally { await f.close() }
 })
 
diff --git a/cli/test/unit/integrations/native-upgrade.test.ts b/cli/test/unit/integrations/native-upgrade.test.ts
index 7a8872c48..fb326cb65 100644
--- a/cli/test/unit/integrations/native-upgrade.test.ts
+++ b/cli/test/unit/integrations/native-upgrade.test.ts
@@ -13,8 +13,11 @@ async function fixture(downloadFailure = false) {
   const root = await realpath(await mkdtemp(join(tmpdir(), 'skillhub-native-upgrade-')))
   const versions = ['1.0.0', '2.0.0'].map((version, index) => {
     const content = `# Version ${version}`
-    const fingerprint = 'sha256:' + createHash('sha256').update('SKILL.md:' + createHash('sha256').update(content).digest('hex') + '\n').digest('hex')
-    return { version, versionId: index + 1, content, fingerprint }
+    const examples = JSON.stringify({ schemaVersion: 1, defaultLocale: 'en', examples: { en: [{ id: 'one', title: version, prompt: 'Use {{skill}} ' + version }] } })
+    const fingerprint = 'sha256:' + createHash('sha256')
+      .update('.skillhub/examples.json:' + createHash('sha256').update(examples).digest('hex') + '\n')
+      .update('SKILL.md:' + createHash('sha256').update(content).digest('hex') + '\n').digest('hex')
+    return { version, versionId: index + 1, content, examples, fingerprint }
   })
   let downloads = 0
   const server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch(request) {
@@ -26,7 +29,7 @@ async function fixture(downloadFailure = false) {
     } })
     downloads++
     if (downloadFailure && version.version === '2.0.0') return new Response('missing', { status: 404 })
-    return new Response(new Uint8Array(zipSync({ 'SKILL.md': new TextEncoder().encode(version.content) })).buffer)
+    return new Response(new Uint8Array(zipSync({ 'SKILL.md': new TextEncoder().encode(version.content), '.skillhub/examples.json': new TextEncoder().encode(version.examples) })).buffer)
   } })
   const registry = server.url.origin
   const inventory = new InventoryStore(join(root, 'home'))
@@ -52,6 +55,7 @@ test('native upgrade replaces the entire confirmed target set and persists its o
   try {
     expect(await f.runtime.executeUpgrade(f.request)).toMatchObject({ outcome: 'committed' })
     for (const target of f.roots) expect(await readFile(join(target.root, 'writer/SKILL.md'), 'utf8')).toBe('# Version 2.0.0')
+    expect(await f.runtime.readSkillExamples(join(f.roots[0]!.root, 'writer'))).toMatchObject({ state: 'ready', items: { en: [{ title: '2.0.0' }] } })
     expect((await f.inventory.read()).items[0]!.version).toBe('2.0.0')
     expect((await f.runtime.getOperation(f.request.operationId, 'session'))?.files).toBe('upgraded')
     expect(await f.runtime.listPending()).toEqual([])
diff --git a/cli/test/unit/integrations/upgrade-baseline.test.ts b/cli/test/unit/integrations/upgrade-baseline.test.ts
index 183fd6de0..f168ae691 100644
--- a/cli/test/unit/integrations/upgrade-baseline.test.ts
+++ b/cli/test/unit/integrations/upgrade-baseline.test.ts
@@ -15,6 +15,7 @@ test('upgrade baseline includes both approved targets and blocks drift, sharing,
     for (const target of item.targets) {
       await mkdir(join(target.installDir, '.skillhub'), { recursive: true })
       await writeFile(join(target.installDir, 'SKILL.md'), 'original')
+      await writeFile(join(target.installDir, '.skillhub/examples.json'), '{invalid but fingerprinted}')
       const snapshot = await snapshotSkillDirectory(target.installDir)
       item.fingerprint = snapshot.fingerprint
       await writeFile(join(target.installDir, '.skillhub/metadata.json'), JSON.stringify({ ...item, ...snapshot,
@@ -29,6 +30,13 @@ test('upgrade baseline includes both approved targets and blocks drift, sharing,
     expect(ready.targets.map(target => target.scope)).toEqual(['user', 'project'])
     expect(ready.inventoryItem.targets).toHaveLength(2)
 
+    await writeFile(join(item.targets[0]!.installDir, '.skillhub/examples.json'), '{edited}')
+    expect(await check()).toEqual({ status: 'blocked', reason: 'local-changes' })
+    await rm(join(item.targets[0]!.installDir, '.skillhub/examples.json'))
+    expect(await check()).toEqual({ status: 'blocked', reason: 'local-changes' })
+    await writeFile(join(item.targets[0]!.installDir, '.skillhub/examples.json'), '{invalid but fingerprinted}')
+    expect((await check()).status).toBe('ready')
+
     inventory.items[0]!.targets[1]!.agent = 'other-agent'
     expect(await check()).toEqual({ status: 'blocked', reason: 'target-outside-context' })
     inventory = { items: [structuredClone(item)] }
@@ -50,7 +58,8 @@ test('upgrade baseline includes both approved targets and blocks drift, sharing,
     const snapshot = await snapshotSkillDirectory(item.targets[0]!.installDir)
     const metadata = { ...item, ...snapshot, agent: 'dsh', installedAt: item.targets[0]!.installedAt }
     await writeFile(metadataPath, JSON.stringify({ ...metadata, files: undefined }))
-    expect(await check()).toEqual({ status: 'blocked', reason: 'metadata-invalid' })
+    // Authored metadata files cannot be considered owned without a recorded file baseline.
+    expect(await check()).toEqual({ status: 'blocked', reason: 'target-unavailable' })
     await writeFile(metadataPath, JSON.stringify(metadata))
     let reads = 0
     expect(await inspectUpgradeBaseline({ read: async () => {
diff --git a/cli/test/unit/platform/archive.test.ts b/cli/test/unit/platform/archive.test.ts
index b175e279a..73f508698 100644
--- a/cli/test/unit/platform/archive.test.ts
+++ b/cli/test/unit/platform/archive.test.ts
@@ -1,4 +1,4 @@
-import { mkdtemp, readFile, writeFile } from 'node:fs/promises'
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, test } from 'bun:test'
@@ -17,6 +17,59 @@ describe('archive helpers', () => {
     expect(await readFile(join(target, 'SKILL.md'), 'utf-8')).toBe('# Demo')
   })
 
+  test.each(['/', '\\'])('extracts explicit directories and files with %s separators', async separator => {
+    const root = await mkdtemp(join(tmpdir(), 'skillhub-archive-directories-'))
+    try {
+      const source = join(root, 'source')
+      const target = join(root, 'target')
+      const examples = new TextEncoder().encode('{"schemaVersion":1,"examples":{"zh-CN":[]}}\n')
+      const archive = zipSync({
+        'SKILL.md': new TextEncoder().encode('# Demo'),
+        [`.skillhub${separator}`]: new Uint8Array(0),
+        [`.skillhub${separator}examples.json`]: examples,
+        [`resources${separator}`]: new Uint8Array(0),
+        [`resources${separator}empty${separator}`]: new Uint8Array(0),
+        [`resources${separator}data.bin`]: new Uint8Array([0, 255, 42]),
+      })
+
+      await extractZip(archive.buffer as ArrayBuffer, source, { rejectInternalMetadata: true })
+      const repacked = await createZip(source)
+      await extractZip(await repacked.arrayBuffer(), target, { rejectInternalMetadata: true })
+
+      for (const directory of [source, target]) {
+        expect(await readFile(join(directory, 'SKILL.md'), 'utf-8')).toBe('# Demo')
+        expect(new Uint8Array(await readFile(join(directory, '.skillhub', 'examples.json')))).toEqual(examples)
+        expect(new Uint8Array(await readFile(join(directory, 'resources', 'data.bin')))).toEqual(new Uint8Array([0, 255, 42]))
+        expect((await stat(join(directory, '.skillhub'))).isDirectory()).toBe(true)
+        expect((await stat(join(directory, 'resources', 'empty'))).isDirectory()).toBe(true)
+      }
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
+  test.each(['.skillhub/metadata.json', '.skillhub/./metadata.json', '.SKILLHUB/METADATA.JSON', '.skillhub\\metadata.json', '.skillhub/metadata.json/child'])('install rejects reserved metadata alias %s before writing', async path => {
+    const target = await mkdtemp(join(tmpdir(), 'skillhub-reserved-'))
+    const archive = zipSync({ 'SKILL.md': new TextEncoder().encode('safe'), [path]: new TextEncoder().encode('untrusted') })
+    await expect(extractZip(archive.buffer as ArrayBuffer, target, { rejectInternalMetadata: true })).rejects.toThrow('Installer metadata')
+    await expect(readFile(join(target, 'SKILL.md'))).rejects.toThrow()
+  })
+
+  test.each(['.SKILLHUB/examples.json', '.skillhub/Examples.JSON'])('install rejects ambiguous cross-platform examples path %s', async path => {
+    const target = await mkdtemp(join(tmpdir(), 'skillhub-case-alias-'))
+    const archive = zipSync({ 'SKILL.md': new TextEncoder().encode('safe'), [path]: new TextEncoder().encode('{}') })
+    await expect(extractZip(archive.buffer as ArrayBuffer, target, { rejectInternalMetadata: true })).rejects.toThrow('Ambiguous skill examples')
+    await expect(readFile(join(target, 'SKILL.md'))).rejects.toThrow()
+  })
+
+  test('rejects canonical duplicate and file/directory conflicts', async () => {
+    for (const entries of [{ 'a.json': 'one', './a.json': 'two' }, { a: 'file', 'a/b': 'child' }]) {
+      const target = await mkdtemp(join(tmpdir(), 'skillhub-duplicate-'))
+      const archive = zipSync(Object.fromEntries(Object.entries(entries).map(([path, content]) => [path, new TextEncoder().encode(content)])))
+      await expect(extractZip(archive.buffer as ArrayBuffer, target)).rejects.toThrow('conflicting zip')
+    }
+  })
+
   test('detects zip files by magic bytes', async () => {
     const dir = await mkdtemp(join(tmpdir(), 'skillhub-archive-detect-'))
     const zipPath = join(dir, 'skill.zip')
diff --git a/cli/test/unit/services/install-service.test.ts b/cli/test/unit/services/install-service.test.ts
index 64f2ea237..ce9d3c539 100644
--- a/cli/test/unit/services/install-service.test.ts
+++ b/cli/test/unit/services/install-service.test.ts
@@ -26,7 +26,7 @@ async function exists(path: string): Promise<boolean> {
 
 function skillFingerprint(zipEntries: Record<string, string>): string {
   const aggregate = createHash('sha256')
-  for (const [name, content] of Object.entries(zipEntries).sort(([left], [right]) => left.localeCompare(right))) {
+  for (const [name, content] of Object.entries(zipEntries).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
     const fileHash = createHash('sha256').update(content).digest('hex')
     aggregate.update(`${name}:${fileHash}\n`, 'utf8')
   }
@@ -89,6 +89,31 @@ describe('installSkill', () => {
     globalThis.fetch = originalFetch
   })
 
+  test.each(['{"schemaVersion":1,"defaultLocale":"en","examples":{"en":[{"id":"one","title":"One","prompt":"Use {{skill}}"}]}}', '{invalid'])('installs authored examples unchanged and records their complete baseline: %s', async content => {
+    const root = await mkdtemp(join(tmpdir(), 'skillhub-packaged-examples-'))
+    try {
+      globalThis.fetch = installFetch({ 'SKILL.md': '# Demo', '.skillhub/examples.json': content })
+      await installSkill({ registry: 'http://registry.test', namespace: 'global', slug: 'demo',
+        targets: [{ agent: 'dsh', rootDir: join(root, 'skills'), scope: 'project', source: 'explicit' }], force: false, home: join(root, 'home') })
+      const target = join(root, 'skills/demo')
+      expect(await readFile(join(target, '.skillhub/examples.json'), 'utf8')).toBe(content)
+      const metadata = JSON.parse(await readFile(join(target, '.skillhub/metadata.json'), 'utf8'))
+      expect(metadata.files['.skillhub/examples.json']).toBe(createHash('sha256').update(content).digest('hex'))
+      expect(metadata.files['.skillhub/metadata.json']).toBeUndefined()
+    } finally { await rm(root, { recursive: true, force: true }) }
+  })
+
+  test('rejects authored installation metadata without replacing target or inventory', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'skillhub-forged-metadata-'))
+    try {
+      globalThis.fetch = installFetch({ 'SKILL.md': '# Demo', '.skillhub/metadata.json': '{"registry":"evil"}' })
+      await expect(installSkill({ registry: 'http://registry.test', namespace: 'global', slug: 'demo',
+        targets: [{ agent: 'dsh', rootDir: join(root, 'skills'), scope: 'project', source: 'explicit' }], force: false, home: join(root, 'home') })).rejects.toThrow('Installer metadata')
+      expect(await exists(join(root, 'skills/demo'))).toBe(false)
+      expect((await new InventoryStore(join(root, 'home')).read()).items).toEqual([])
+    } finally { await rm(root, { recursive: true, force: true }) }
+  })
+
   test.each(['journal-failure', 'directory-collision'] as const)('staging intent precedes directory creation: %s', async failure => {
     const root = await mkdtemp(join(tmpdir(), 'skillhub-staging-intent-'))
     const rootDir = join(root, 'skills')
diff --git a/cli/test/unit/services/skill-examples-preflight.test.ts b/cli/test/unit/services/skill-examples-preflight.test.ts
new file mode 100644
index 000000000..bf425b585
--- /dev/null
+++ b/cli/test/unit/services/skill-examples-preflight.test.ts
@@ -0,0 +1,67 @@
+import { expect, spyOn, test } from 'bun:test'
+import { zipSync } from 'fflate'
+import { inspectPackagedExamples } from '../../../src/services/skill-examples-preflight'
+
+const valid = JSON.stringify({ schemaVersion: 1, defaultLocale: 'zh-CN', examples: {
+  'zh-CN': [], en: [{ id: 'one', title: 'Summary', prompt: 'Use {{skill}}.' }]
+} })
+function archive(files: Record<string, string>): Blob {
+  return new Blob([new Uint8Array(zipSync(Object.fromEntries(Object.entries(files).map(([path, text]) => [path, new TextEncoder().encode(text)])))).buffer])
+}
+
+test('preflight matches server root stripping/promotion and counts all language entries', async () => {
+  for (const files of [
+    { 'SKILL.md': '# skill', '.skillhub/examples.json': valid },
+    { 'package/SKILL.md': '# skill', 'package/.skillhub/examples.json': valid },
+    { 'package/SKILL.md': '# skill', 'package/.skillhub/examples.json': valid, 'README.md': 'outside' },
+    { 'package/skill.md': '# skill', 'package/.skillhub/examples.json': valid, 'README.md': 'outside' },
+    { 'package/Skill.MD': '# skill', 'package/.skillhub/examples.json': valid, 'README.md': 'outside' },
+    { 'package/SKILL.md': '# skill', 'package/.skillhub/examples.json': valid, '__MACOSX/._file': 'ignored' }
+  ]) expect(await inspectPackagedExamples(archive(files))).toEqual({ examplesStatus: 'ready', examplesCount: 1, warnings: [] })
+})
+
+test('preflight bounds inflation, preserves invalid declaration semantics and ignores unrelated files', async () => {
+  for (const content of ['{broken', 'x'.repeat(65537)]) {
+    const result = await inspectPackagedExamples(archive({ 'SKILL.md': '# skill', '.skillhub/examples.json': content }))
+    expect(result.examplesStatus).toBe('invalid')
+    expect(result.examplesCount).toBeUndefined()
+    expect(result.warnings).toHaveLength(1)
+  }
+  expect(await inspectPackagedExamples(archive({ 'SKILL.md': '# skill', 'docs/.skillhub/examples.json': valid })))
+    .toEqual({ examplesStatus: 'none', examplesCount: 0, warnings: [] })
+  const unreadable = await inspectPackagedExamples(new Blob(['not a zip']))
+  expect(unreadable.examplesStatus).toBeUndefined()
+  expect(unreadable.warnings).toHaveLength(1)
+})
+
+
+test('preflight rejects forged stored-file sizes without copying the oversized entry body', async () => {
+  const content = new Uint8Array(65537).fill(120)
+  const bytes = zipSync({ 'SKILL.md': new TextEncoder().encode('# skill'), '.skillhub/examples.json': content }, { level: 0 })
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  let forged = false
+  for (let offset = 0; offset <= bytes.byteLength - 46; offset++) {
+    if (view.getUint32(offset, true) !== 0x02014b50) continue
+    const nameLength = view.getUint16(offset + 28, true)
+    const name = new TextDecoder().decode(bytes.subarray(offset + 46, offset + 46 + nameLength))
+    if (name === '.skillhub/examples.json') {
+      expect(view.getUint16(offset + 10, true)).toBe(0)
+      expect(view.getUint32(offset + 20, true)).toBe(65537)
+      view.setUint32(offset + 24, 1, true)
+      forged = true
+      break
+    }
+  }
+  expect(forged).toBe(true)
+  const subarray = Uint8Array.prototype.subarray
+  let oversizedReads = 0
+  const spy = spyOn(Uint8Array.prototype, 'subarray').mockImplementation(function (this: Uint8Array, begin, end) {
+    if ((end ?? this.length) - (begin ?? 0) > 65536) oversizedReads++
+    return subarray.call(this, begin, end)
+  })
+  try {
+    expect(await inspectPackagedExamples(new Blob([new Uint8Array(bytes).buffer])))
+      .toMatchObject({ examplesStatus: 'invalid', warnings: [expect.stringContaining('ordinary package content')] })
+    expect(oversizedReads).toBe(0)
+  } finally { spy.mockRestore() }
+})
diff --git a/cli/test/unit/services/skill-examples.test.ts b/cli/test/unit/services/skill-examples.test.ts
new file mode 100644
index 000000000..ac78348cc
--- /dev/null
+++ b/cli/test/unit/services/skill-examples.test.ts
@@ -0,0 +1,84 @@
+import { expect, test } from 'bun:test'
+import { mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { createTempHome } from '../../helpers/temp-env'
+import { parseSkillExamples, readSkillExamples } from '../../../src/services/skill-examples'
+import { snapshotSkillDirectory, diffSkillFiles } from '../../../src/services/skill-fingerprint'
+import { assertOwnedRegularTree } from '../../../src/integrations/recovery-files'
+
+const example = { id: 'summary', title: '会议摘要', prompt: '请用 {{skill}} 总结会议。' }
+const valid = { schemaVersion: 1, defaultLocale: 'zh-CN', examples: { 'zh-CN': [example], en: [{ ...example, title: 'Summary', prompt: 'Use {{skill}}.' }] } }
+const bytes = (value: unknown) => new TextEncoder().encode(JSON.stringify(value))
+
+test('examples recognizes bounded multilingual object protocol without changing authored bytes', () => {
+  const parsed = parseSkillExamples(bytes(valid))
+  expect(parsed.state).toBe('ready')
+  if (parsed.state !== 'ready') throw new Error('expected ready')
+  expect(parsed.items['zh-CN']).toEqual([example])
+  expect(parsed.digest).toHaveLength(64)
+  expect(parseSkillExamples(new Uint8Array([0xef, 0xbb, 0xbf, ...bytes(valid)]))).toMatchObject({ state: 'ready' })
+  expect(parseSkillExamples(bytes({ ...valid, examples: { en: [] }, defaultLocale: 'en' }))).toMatchObject({ state: 'ready', items: { en: [] } })
+})
+
+test('examples rejects unsupported or ambiguous declarations, Unicode lengths and encoding', () => {
+  const invalid = [
+    {}, { ...valid, schemaVersion: 2 }, { ...valid, extra: true }, { ...valid, defaultLocale: 'ja' },
+    { ...valid, examples: { 'zh-CN': [example], 'zh-cn': [] } },
+    { ...valid, examples: { 'zh-CN': [example, example] } },
+    { ...valid, examples: { 'zh-CN': ['old string format'] } },
+    ...[{ ...example, id: 'Bad ID' }, { ...example, title: '\u0085\uFEFF' }, { ...example, prompt: '' },
+      { ...example, title: '😀'.repeat(81) }, { ...example, prompt: '😀'.repeat(4001) }, { ...example, extra: 1 }]
+      .map(item => ({ ...valid, examples: { 'zh-CN': [item] } }))
+  ]
+  for (const value of invalid) expect(parseSkillExamples(bytes(value))).toEqual({ state: 'invalid' })
+  expect(parseSkillExamples(new Uint8Array([0xff]))).toEqual({ state: 'invalid' })
+  expect(parseSkillExamples(new Uint8Array(65537))).toEqual({ state: 'invalid' })
+  expect(parseSkillExamples(bytes({ ...valid, examples: { 'zh-CN': [{ ...example, title: '😀'.repeat(80) }] } }))).toMatchObject({ state: 'ready' })
+})
+
+test('packaged examples participate in fingerprint and recovery ownership even when malformed', async () => {
+  const env = await createTempHome()
+  const root = join(env.cwd, 'skill')
+  await mkdir(join(root, '.skillhub'), { recursive: true })
+  await writeFile(join(root, 'SKILL.md'), '# skill')
+  const path = join(root, '.skillhub/examples.json')
+  await writeFile(path, bytes(valid))
+  const snapshot = await snapshotSkillDirectory(root)
+  await writeFile(join(root, '.skillhub/metadata.json'), JSON.stringify({ registry: 'https://example.com', namespace: 'a', slug: 'b', version: '1', ...snapshot }))
+  await expect(assertOwnedRegularTree(root)).resolves.toBeUndefined()
+  expect(await readSkillExamples(root)).toMatchObject({ state: 'ready' })
+  expect((await snapshotSkillDirectory(root)).fingerprint).toBe(snapshot.fingerprint)
+  await writeFile(path, '{broken')
+  expect(await readSkillExamples(root)).toEqual({ state: 'invalid' })
+  expect(diffSkillFiles(snapshot.files, (await snapshotSkillDirectory(root)).files)).toEqual(['.skillhub/examples.json'])
+  expect(await readFile(path, 'utf8')).toBe('{broken')
+  await writeFile(join(root, '.skillhub/untracked.txt'), 'preserve')
+  await expect(assertOwnedRegularTree(root)).rejects.toThrow('Untracked recovery metadata content')
+  await rm(join(root, '.skillhub/untracked.txt'))
+  await rm(path)
+  expect(await readSkillExamples(root)).toEqual({ state: 'none' })
+  await symlink(join(root, 'SKILL.md'), path)
+  await expect(assertOwnedRegularTree(root)).rejects.toThrow('Unsafe recovery path')
+})
+
+
+test('recognizes the normative protocol examples shared with server and schema checks', async () => {
+  for (const name of ['skill-examples.valid.json', 'skill-examples.empty.json']) {
+    const content = await readFile(new URL('../../../../openspec/changes/add-dsh-native-plugin/contracts/' + name, import.meta.url))
+    expect(parseSkillExamples(content)).toMatchObject({ state: 'ready' })
+  }
+})
+
+
+test('examples honors inclusive raw-byte, locale and per-language collection bounds', () => {
+  const encoded = bytes(valid)
+  const padded = new Uint8Array(65536).fill(32)
+  padded.set(encoded)
+  expect(parseSkillExamples(padded)).toMatchObject({ state: 'ready' })
+  const entries = Array.from({ length: 20 }, (_, index) => ({ ...example, id: `case-${index}` }))
+  expect(parseSkillExamples(bytes({ ...valid, examples: { 'zh-CN': entries } }))).toMatchObject({ state: 'ready' })
+  expect(parseSkillExamples(bytes({ ...valid, examples: { 'zh-CN': [...entries, { ...example, id: 'extra' }] } }))).toEqual({ state: 'invalid' })
+  const languages = Object.fromEntries(['en', 'zh', 'ja', 'ko', 'fr', 'de', 'es', 'it', 'pt', 'ru'].map(locale => [locale, []]))
+  expect(parseSkillExamples(bytes({ ...valid, defaultLocale: 'en', examples: languages }))).toMatchObject({ state: 'ready' })
+  expect(parseSkillExamples(bytes({ ...valid, defaultLocale: 'en', examples: { ...languages, nl: [] } }))).toEqual({ state: 'invalid' })
+})
diff --git a/cli/test/unit/services/suite-service.test.ts b/cli/test/unit/services/suite-service.test.ts
index 6a962c018..c42b43e0c 100644
--- a/cli/test/unit/services/suite-service.test.ts
+++ b/cli/test/unit/services/suite-service.test.ts
@@ -16,9 +16,11 @@ import {
 
 const registry = 'http://registry.test'
 
-function archive(content: string): { bytes: Uint8Array; fingerprint: string } {
-  const bytes = zipSync({ 'SKILL.md': new TextEncoder().encode(content) })
+function archive(content: string, includeExamples = true): { bytes: Uint8Array; fingerprint: string } {
+  const examples = '{invalid but versioned suite examples}'
+  const bytes = zipSync({ 'SKILL.md': new TextEncoder().encode(content), ...(includeExamples ? { '.skillhub/examples.json': new TextEncoder().encode(examples) } : {}) })
   const aggregate = createHash('sha256')
+  if (includeExamples) aggregate.update('.skillhub/examples.json:' + createHash('sha256').update(examples).digest('hex') + '\n')
   const fileHash = createHash('sha256').update(content).digest('hex')
   aggregate.update(`SKILL.md:${fileHash}\n`, 'utf8')
   return { bytes, fingerprint: `sha256:${aggregate.digest('hex')}` }
@@ -75,9 +77,9 @@ function clientWithPlanFailure(status: number, message: string): SkillHubClient
   return new SkillHubClient(registry, undefined, fetchImpl)
 }
 
-function makePlan(): { plan: SuiteInstallPlan; downloads: Record<string, Uint8Array> } {
-  const alpha = archive('# Alpha')
-  const beta = archive('# Beta')
+function makePlan(includeExamples = true): { plan: SuiteInstallPlan; downloads: Record<string, Uint8Array> } {
+  const alpha = archive('# Alpha', includeExamples)
+  const beta = archive('# Beta', includeExamples)
   return {
     plan: {
       operationId: 'operation-1',
@@ -732,7 +734,7 @@ describe('Suite local lifecycle', () => {
   test('reuses a matching legacy direct install and preserves it when Suite is removed', async () => {
     const home = await mkdtemp(join(tmpdir(), 'skillhub-suite-home-'))
     const rootDir = await mkdtemp(join(tmpdir(), 'skillhub-suite-root-'))
-    const { plan, downloads } = makePlan()
+    const { plan, downloads } = makePlan(false)
     plan.members = [plan.members[0]!]
     const skillDir = join(rootDir, 'alpha')
     await mkdir(skillDir, { recursive: true })
@@ -801,7 +803,7 @@ describe('Suite local lifecycle', () => {
     const home = await mkdtemp(join(tmpdir(), 'skillhub-suite-home-'))
     const directRoot = await mkdtemp(join(tmpdir(), 'skillhub-suite-direct-root-'))
     const suiteOnlyRoot = await mkdtemp(join(tmpdir(), 'skillhub-suite-only-root-'))
-    const { plan, downloads } = makePlan()
+    const { plan, downloads } = makePlan(false)
     const alpha = plan.members[0]!
     await mkdir(join(directRoot, alpha.slug), { recursive: true })
     await writeFile(join(directRoot, alpha.slug, 'SKILL.md'), '# Alpha')
diff --git a/openspec/changes/add-dsh-native-plugin/README.md b/openspec/changes/add-dsh-native-plugin/README.md
index c6a3e0dab..325228ea2 100644
--- a/openspec/changes/add-dsh-native-plugin/README.md
+++ b/openspec/changes/add-dsh-native-plugin/README.md
@@ -8,8 +8,8 @@
 
 | 入口 | 本期能力 | 详情容器 |
 | --- | --- | --- |
-| 技能广场 | 浏览、搜索、安装、已安装、检查更新、升级、卸载 | 主内容区子页面，左上返回 |
-| 原 DSH 对话 | 搜索卡片、详情、显式安装、自定义结果卡片 | 抽屉，窄屏内容区浮层 |
+| 技能广场 | 浏览、搜索、安装、已安装、检查更新、升级、卸载、使用已安装技能 | 主内容区子页面，左上返回 |
+| 原 DSH 对话 | 搜索卡片、详情、显式安装、自定义结果卡片、使用已安装技能 | 抽屉，窄屏内容区浮层 |
 | 宿主插件配置 | 单一 Registry 地址，版本/审核/评论 auto/show/hide | 原生插件配置区域 |
 
 不做登录、Token、私有访问、权限产品、DSH 插件市场、自动更新、降级、强制覆盖、发表评论或自动执行技能。对话升级/卸载工具不在本期，管理操作从广场进入。
@@ -20,6 +20,10 @@
 | --- | --- |
 | [proposal.md](proposal.md) | 范围与决策摘要 |
 | [product-design.md](product-design.md) | 页面、功能 ID、视觉和产品行为 |
+| [use-skill-design.md](use-skill-design.md) | 使用此技能：本地核验、原生输入框衔接、固定案例文件与生命周期兼容约定 |
+| [skill-examples-design.md](skill-examples-design.md) | 固定案例文件的 JSON 协议、版本分发、跨端生命周期与兼容策略 |
+| [skill-examples-execution-plan.md](skill-examples-execution-plan.md) | 本轮开源范围、实施阶段、验收及后续SaaS同步边界 |
+| [skill-examples-saas-agent-prompt.md](skill-examples-saas-agent-prompt.md) | 可交给SaaS Agent的案例文件增量适配任务 |
 | [conversation-design.md](conversation-design.md) | 对话卡片/抽屉、工具参数、选择引用、历史结果 |
 | [engineering-blueprint.md](engineering-blueprint.md) | 详细工程方案：装配、工具/UI、核心复用、构建和实施切片 |
 | [design.md](design.md) | 总体架构、模块边界、复用依据 |
diff --git a/openspec/changes/add-dsh-native-plugin/acceptance.md b/openspec/changes/add-dsh-native-plugin/acceptance.md
index 5fd0a7348..fd53095bf 100644
--- a/openspec/changes/add-dsh-native-plugin/acceptance.md
+++ b/openspec/changes/add-dsh-native-plugin/acceptance.md
@@ -142,3 +142,39 @@ flowchart LR
 `pnpm add` 不能单独证明严格 peer 校验有效。本轮追加 `dsh plugin --profile <profile> install --strict-peer-dependencies --ignore-scripts` 与独立 npm `--strict-peer-deps` 安装，并验证冲突时正常失败。
 
 交付跟踪见 [PR #988](https://github.com/iflytek/skillhub/pull/988)。本轮未发布 npm、创建 tag、调用模型或修改生产环境；公开插件 `0.3.0` 不包含此候选兼容修复。
+
+
+## 使用此技能：候选验收门禁
+
+| 编号 | 输入与动作 | 应观察结果 | 当前状态 |
+| --- | --- | --- | --- |
+| USE-01 | 已安装卡片、详情、安装成功分别点击使用 | 三处共用本地核验与原生草稿衔接；不自动发送 | 通过：五处原生入口及统一服务 |
+| USE-02 | 市场 slug 与 SKILL.md name 不同 | 调用真实 name；不取标题或 slug 猜测 | 通过：双 RC 原生技能真名 |
+| USE-03 | 草稿已有文字、引用与附件；包含非折叠选区 | 既有内容保留，在原生捕获位置末端插入；仍可编辑和手动发送 | 通过：选区行为测试；原生引用和图片保留 |
+| USE-04 | 核验期间编辑草稿、切会话/来源/工作区、卸载组件 | 比较或上下文检查失败，无跨会话污染、无自动重试覆盖 | 通过：行为测试及原生会话/草稿竞态 |
+| USE-05 | 本地资源改变、同名 Provider 覆盖、禁止用户调用、记录删除 | 明确阻止，草稿和技能文件不变 | 通过：行为测试；原生资源改动及同名覆盖 |
+| USE-06 | 从已升级或已卸载的历史安装回执使用 | 不静默替换版本；要求选择当前安装 | 通过：精确版本/范围行为测试；当前回执实机 |
+| USE-07 | 两个支持 RC 独立 Profile 加载同一冻结候选 | 实际 Host RPC/原生编辑器交互通过，无脚本异常、模型请求或消息提交 | 通过：双 RC 各 12 项原生浏览器检查 |
+
+设计见 [use-skill-design.md](use-skill-design.md)。详细结果见 verification.md。“通过”指各项规定层级的组合验收，不表示所有异常分支都已逐一人工浏览器操作；本功能尚未发布到 npm。此处不扩大到真实模型技能执行、SaaS、桌面或原生 Windows/macOS 验收。
+
+
+## 固定技能案例文件：开源验收
+
+已确认 `.skillhub/examples.json` 为上传、下载和安装后保持一致的唯一案例文件，随技能版本更新。协议合法则自动识别，不合法则在通过通用安全检查后按普通文件保留；不新增 Web 编辑器或独立缓存。详细行为与验收由 [使用设计](use-skill-design.md#技能专属使用案例固定文件约定) 和 [正式场景](specs/dsh-native-experience/spec.md#requirement-versioned-skill-examples-at-one-fixed-package-path) 定义。
+
+协议 schema、接口投影、内部 metadata 上传策略和旧消费者发布策略已在 skill-examples-design.md 定义；开源跨端功能、真实新旧消费者与双RC案例选择已通过本地验收，具体范围和平台缺口见 verification.md 的固定案例开源实现记录。SaaS 后续独立执行，见 tasks.md §40.9。
+
+
+## 输入框内联案例交互：本轮门禁
+
+| 编号 | 动作 | 预期 |
+| --- | --- | --- |
+| USE-N01 | 技能中心的卡片、详情及安装成功点击使用 | 同一工作区仅创建一个新对话，展开内联案例；旧会话内容、引用、附件不变 |
+| USE-N02 | 对话工具回执点击使用 | 留在原会话，展开同一内联案例区，无新对话 |
+| USE-N03 | 取消、选择后确认、自定义与无案例 | 展开不写草稿；取消不写不删；确认后可编辑，无案例不显示空选项 |
+| USE-N04 | 快速重复、创建失败、切会话/工作区/来源/语言、确认期间编辑 | 明确失败或撤销，旧结果不抢回导航或污染其他草稿 |
+| USE-N06 | 满8份非空草稿、回访、清空、会话移除、创建失败、插件卸载 | 新建前限额拒绝，不驱逐；官方retain按生命周期准确释放；不承诺跨刷新持久化 |
+| USE-N05 | 双支持RC安装同一候选并实际浏览器操作 | 官方API与slot可用，核验精确原安装范围/版本、草稿附件保留，零消息发送和模型调用 |
+
+本轮组合门禁已通过，结果见 verification.md 的“原生新对话与输入框案例交互”。USE-N01–N03、N05 的正常交互与 USE-N04 的重复点击、切会话、确认期间编辑，均在两版真实浏览器验证；创建失败、工作区/来源/语言失效、无案例和 USE-N06 的容量/清理分支由行为测试与独立评审覆盖。不是所有边界都逐一执行了浏览器操作，历史弹窗结果不替代本轮。
diff --git a/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.empty.json b/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.empty.json
new file mode 100644
index 000000000..05ec96f85
--- /dev/null
+++ b/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.empty.json
@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "defaultLocale": "zh-CN",
+  "examples": {
+    "zh-CN": []
+  }
+}
diff --git a/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.schema.json b/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.schema.json
new file mode 100644
index 000000000..4a49d3a5a
--- /dev/null
+++ b/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.schema.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "SkillHub packaged task examples v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "defaultLocale",
+    "examples"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1,
+      "type": "integer"
+    },
+    "examples": {
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 10,
+      "propertyNames": {
+        "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+      },
+      "additionalProperties": {
+        "type": "array",
+        "maxItems": 20,
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "id",
+            "title",
+            "prompt"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "maxLength": 64,
+              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+            },
+            "title": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80,
+              "pattern": "[^\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000\\uFEFF]"
+            },
+            "prompt": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 4000,
+              "pattern": "[^\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000\\uFEFF]"
+            }
+          }
+        }
+      }
+    },
+    "defaultLocale": {
+      "type": "string",
+      "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"
+    }
+  }
+}
diff --git a/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.valid.json b/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.valid.json
new file mode 100644
index 000000000..bb6b201ff
--- /dev/null
+++ b/openspec/changes/add-dsh-native-plugin/contracts/skill-examples.valid.json
@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 1,
+  "defaultLocale": "zh-CN",
+  "examples": {
+    "zh-CN": [
+      {
+        "id": "meeting-summary",
+        "title": "整理会议纪要",
+        "prompt": "请使用 {{skill}} 整理会议记录，提取结论和待办。"
+      },
+      {
+        "id": "compare-proposals",
+        "title": "对比方案",
+        "prompt": "请使用 {{skill}} 对比两份方案，列出差异、风险和待确认问题。"
+      }
+    ],
+    "en": [
+      {
+        "id": "meeting-summary",
+        "title": "Summarize meeting notes",
+        "prompt": "Use {{skill}} to summarize meeting notes and extract action items."
+      },
+      {
+        "id": "compare-proposals",
+        "title": "Compare proposals",
+        "prompt": "Use {{skill}} to compare two proposals and identify differences, risks, and open questions."
+      }
+    ]
+  }
+}
diff --git a/openspec/changes/add-dsh-native-plugin/dsh-integration-design.md b/openspec/changes/add-dsh-native-plugin/dsh-integration-design.md
index 1d4751230..7417c581b 100644
--- a/openspec/changes/add-dsh-native-plugin/dsh-integration-design.md
+++ b/openspec/changes/add-dsh-native-plugin/dsh-integration-design.md
@@ -165,3 +165,19 @@ DSH 官方接口与机制参考：
 
 
 首版单一版本基线、依赖锁定、能力检测及平台验收遵循 [DSH 兼容性设计](compatibility-design.md)。
+
+
+## 原生技能草稿衔接
+
+“使用此技能”通过已声明的 `@deepseek-ai/dsh-client-ui-conversation` Client 模块，读取 session/session-maybe slot 标准 `inputActions`。两版支持基线均提供 `captureInsertion()`、带 revision 比较的 `insertText()` 及 `conversation.input.for(scope).focus()`；不使用新 RC 专有草稿持久化接口。该 Client 注入同步加入运行时兼容清单，沿用现有同版校验，不增加 Host runtime peer。
+
+技能中心与工具视图绑定原生输入动作；会话输入框贡献负责内联案例选择和确认后的聚焦，不增加任务发送按钮或替换宿主编辑器；技能中心入口通过官方 API 在同工作区新建对话，对话内入口不新建。会话、绑定、来源、工作区与组件生命周期在异步核验前后检查；不能将仍被历史视图持有的会话当成当前主会话。没有原生服务时显示不可用原因，不查找 DOM 或用模拟输入兜底。产品时序和验收见 [使用此技能](use-skill-design.md)。
+
+
+### 新对话与内联案例的官方接缝
+
+技能中心通过当前会话所属工作区创建全新会话，避免宿主可复用空会话中已有草稿被污染。使用 `sessions.create({workspaceId,cwd})` 创建、`sessions.retain(...).ready` 等待可用、`uiWorkspace.openSession` 导航；新会话临时 retain 在完成或失败时释放，主视图接管正常会话生命周期。原会话有草稿/附件时需独立保留完整原生 shell，按返回接管、清空、作用域失效和插件卸载释放，具体限额与失败行为见使用设计。原会话及工作区变化时停止，不能把 `startSession` 可能复用的空会话当成新建成功。
+
+案例区挂载于官方 `conversation.input.dock`，为原生输入框上方的全宽贡献。原 `conversation.input.left` 继续仅承担动作绑定与确认后聚焦。案例状态由常驻控制器管理，不能留在技能卡片或安装弹窗中，否则技能中心卸载会丢失待选项。`ui-workspace`、`api-workspace-controller` 只作为开发类型依赖，运行时由宿主提供，不复制宿主会话控制器。
+
+上述官方接口按两版支持 RC 的本地发行源码核对；实际加载与交互仍须由本轮双基线浏览器结果证明，不因类型检查通过而视为验收。
diff --git a/openspec/changes/add-dsh-native-plugin/implementation-design.md b/openspec/changes/add-dsh-native-plugin/implementation-design.md
index 3f9c4b06a..c92da1e47 100644
--- a/openspec/changes/add-dsh-native-plugin/implementation-design.md
+++ b/openspec/changes/add-dsh-native-plugin/implementation-design.md
@@ -269,3 +269,8 @@ getOperation 对已完成的安装、升级增加当前会话的只读发现观
 ## 对话安装去除详情展示前置
 
 `conversation-selections.ts` 区分真实展示关联与后台核验的安装快照；`index.ts` 的 `installConversation` 在原请求去重与事务准备内解析安装快照，未展示时调用精确版本读取，完成后重新校验实际上下文。`search-tool.ts` / `install-tool.ts` 仅更新模型指引，不新增参数、工具或公共 Remote。测试覆盖未展示、已展示、版本不漂移、引用失效、上下文竞争、并发核验与失败重试。安装事务、归档验证和恢复机制保持不变。
+
+
+## 技能专属案例：本轮执行范围
+
+固定文件、多语言对象及技能占位符协议见 [案例实现设计](skill-examples-design.md)。本轮的开源模块边界、P0–P5实施顺序、验收矩阵及SaaS后续同步统一由 [案例执行方案](skill-examples-execution-plan.md) 定义，不复用旧外置缓存或独立刷新设计。后续执行不改变本文件中此前已交付能力的事实状态。
diff --git a/openspec/changes/add-dsh-native-plugin/interface-design.md b/openspec/changes/add-dsh-native-plugin/interface-design.md
index 6724dc061..6b327ec83 100644
--- a/openspec/changes/add-dsh-native-plugin/interface-design.md
+++ b/openspec/changes/add-dsh-native-plugin/interface-design.md
@@ -360,3 +360,27 @@ accepted 不表示安装完成。工具立即返回 accepted 及 operationId，
 保留 `checkUpdate` 与 `prepareUpgrade` 的原签名及“检查最新版”行为，新增 Agent-scoped `checkVersionUpdate(sourceRevision,itemKey,version,signal)` 和 `prepareVersionUpgrade(sourceRevision,itemKey,version,signal)`。两组接口共享当前库存重读、完整目标基线、版本比较、文件修改保护与确认计划；定向接口必须按指定 version 解析，响应版本不一致即拒绝，不使用 latest 替换不可用版本。执行仍只提交原 executePlan，无新文件写入接口或 SaaS 安装接口。
 
 详情按 source/session/itemKey/所选 version 隔离只读检查缓存，切换仅触发读取。较新且可核验的版本显示升级到该版本，相同版本不重复显示升级，旧版本或不可排序版本明确阻断。确认使用捕获的库存项与精确目标，不因后台库存刷新重建另一升级意图；升级完成使库存失效，旧 itemKey 的检查结果不会绑定到新记录。
+
+
+### 使用此技能：只读当前会话核验
+
+`@RemoteScope('agent') prepareSkillUse(sourceRevision, itemKey, signal)` 接受当前来源 revision 和 opaque 安装记录键。返回 `SkillUsePreparation`：
+
+```ts
+type SkillUsePreparation =
+  | { status: 'ready'; name: string; version: string; scope: 'user' | 'project'; examples: SkillExamples }
+  | { status: 'blocked'; reason: SkillUseBlockReason };
+type SkillUseBlockReason =
+  | 'installation-unverified' | 'operation-pending' | 'shared-installation'
+  | 'files-changed' | 'skill-unavailable' | 'skill-shadowed'
+  | 'user-invocation-disabled' | 'unsupported-name' | 'host-unavailable';
+```
+
+`name` 来自已核验本地 SKILL.md 与当前 DSH 胜出技能，禁止使用市场 slug 或远程说明猜测。来源/会话/范围或记录变化沿用 context-stale；中止、服务失效不降级为未经核验的调用。只读检查不创建安装/升级/卸载计划或操作，不写文件，不下载，不注册模型工具。没有实际调用权时 Client 显示明确原因并保留草稿。技能中心新对话的 itemKey 必须由该新会话的 listInstalled 重新取得并匹配原来源、坐标、版本和范围；对话入口沿用原会话核验。案例选择不增加新 Host Remote，使用官方 conversation.input.dock 贡献，详见使用设计。
+
+Client 使用原生 `InputActions.captureInsertion()` 和 `insertText(text, span)` 的 revision 比较；保留选中文本时在捕获位置末端插入，不用 clipboard 字符长度计算编辑坐标。普通任务文字在前，实际 `/name` 以空白分隔嵌入，避免自动创建 slash command claim。既有 claimed/submitting 等草稿不改写。完整交互与时序见 [使用设计](use-skill-design.md)。
+
+
+## 固定技能案例协议
+
+案例直接随技能包分发，已安装使用读取 `.skillhub/examples.json`；不新增案例查询端点或数据库权威内容。现有精确版本 file 接口可返回原始文件流，不能按 ApiResponse.data 解析。prepareSkillUse 的 ready 返回值扩展有界案例投影，发布预检扩展可选识别摘要；精确定义和状态规则统一见 [案例实现设计](skill-examples-design.md#3-本地读取与原生草稿衔接)。既有 Remote 参数及不自动发送边界保持。扩展已在开源代码实现，旧 API 响应允许缺少预检字段并按未知处理；SaaS 需后续同步。
diff --git a/openspec/changes/add-dsh-native-plugin/lifecycle-design.md b/openspec/changes/add-dsh-native-plugin/lifecycle-design.md
index eaaa1545e..b7d51c43e 100644
--- a/openspec/changes/add-dsh-native-plugin/lifecycle-design.md
+++ b/openspec/changes/add-dsh-native-plugin/lifecycle-design.md
@@ -280,3 +280,8 @@ Inventory 变更必须在 mutateAtomic 的最新快照里比较旧身份、版
 ### 定向升级补充
 
 用户在详情选中精确版本时，先通过 checkVersionUpdate 核验升级方向，再通过 prepareVersionUpgrade 固定候选；最新版检查与计划仍使用原接口。固定候选不可用或版本不符时阻断，不回退 latest。用户确认的计划列出全部共享库存目标，执行使用原锁定基线与候选快照。较旧与不可排序版本不允许覆盖安装；取消计划不写文件。
+
+
+## 固定技能案例文件（待实施补充）
+
+`.skillhub/examples.json` 为版本化作者内容；无论协议是否可识别，都保留原始字节并参与 manifest、指纹、升级/删除保护与恢复。只排除安装器内部 `.skillhub/metadata.json`，不能继续跳过整个目录。上传、安装器内部记录保护与普通作者文件处理统一见 [案例实现设计](skill-examples-design.md#5-发布内容与内部安装记录)，旧版消费者不透明兼容的事实和分阶段发布约束见该文 §6。当前共享核心仍待修改；此前通过的生命周期测试不代表新案例文件已受支持。
diff --git a/openspec/changes/add-dsh-native-plugin/product-design.md b/openspec/changes/add-dsh-native-plugin/product-design.md
index f293eab9d..2057b02fc 100644
--- a/openspec/changes/add-dsh-native-plugin/product-design.md
+++ b/openspec/changes/add-dsh-native-plugin/product-design.md
@@ -488,3 +488,10 @@ Skeleton沿用局部shadcn组件风格和DSH主题变量，不引入新依赖或
 切换版本是查看，不自动改变安装。已有安装时，查看的精确版本比当前版本新且通过来源核验，操作区显示“升级到 vX”；相同版本仅显示已安装，较旧版本说明不支持降级，不提供覆盖安装；不可可靠比较的版本阻断自动升级。不可访问版本不回退到最新版。
 
 升级使用原地确认弹窗，展示旧版本→精确新版本及实际受影响的全部范围；当前底层共享库存升级可能同时更新用户和当前项目的安装，不能暗示只更新下拉框选中范围。存在当前会话不能管理的其他目标时仍整体阻断。市场和已安装列表的检查更新继续面向最新版，也使用同一精简弹窗。取消不修改文件；确认后显示处理与结果，异常保留原请求核验和恢复。
+
+
+## 使用此技能
+
+已安装卡片、所选范围的已安装版本详情以及安装成功结果提供小尺寸“使用此技能”按钮。技能中心入口在同工作区新建对话，对话入口保留当前会话；进入目标对话并核验后，在原生输入框上方展开案例区。选择并确认后保留目标草稿、附件和引用，加入可编辑的技能调用及任务引导，由用户发送。核验失败就地说明原因，不把“安装完成”当成“当前会话可用”。
+
+市场详情切换到其他版本不更换本地调用对象；本期只在所看版本等于该范围安装版本时展示使用入口。历史安装回执重新读取当前同版本记录，不静默使用升级后的其他版本。无活动会话不新建、不切换到历史会话。具体入口、状态和异常交互由 [使用设计](use-skill-design.md) 定义。
diff --git a/openspec/changes/add-dsh-native-plugin/saas-agent-prompt.md b/openspec/changes/add-dsh-native-plugin/saas-agent-prompt.md
index e38c25ed6..afb7ce559 100644
--- a/openspec/changes/add-dsh-native-plugin/saas-agent-prompt.md
+++ b/openspec/changes/add-dsh-native-plugin/saas-agent-prompt.md
@@ -2,6 +2,8 @@
 
 将以下正文交给拥有 SaaS 仓库访问权限的研发 Agent。仓库、测试环境、公开测试技能及部署权限由 SaaS 项目提供；示例值不是实际配置。正式契约以本文引用的 OpenSpec 和插件实际消费代码为准。
 
+> 新增的固定案例文件适配是独立增量任务，见 [技能案例SaaS交接](skill-examples-saas-agent-prompt.md)。已有Registry能力先核对复用，不因本次案例需求重做本篇全部任务。
+
 ---
 
 你负责在 SkillHub SaaS 中核验并补齐原生 DSH 插件所需的 Registry HTTP API，使同一个插件包能够连接开源版或 SaaS 实例，完成匿名浏览、搜索、查看精确版本详情、下载以及在 DSH 主机上的安装管理。
diff --git a/openspec/changes/add-dsh-native-plugin/skill-examples-design.md b/openspec/changes/add-dsh-native-plugin/skill-examples-design.md
new file mode 100644
index 000000000..4be789a3d
--- /dev/null
+++ b/openspec/changes/add-dsh-native-plugin/skill-examples-design.md
@@ -0,0 +1,202 @@
+# 技能使用案例：协议与实现设计
+
+本文承接 [使用设计](use-skill-design.md#技能专属使用案例固定文件约定)，定义本项目的固定案例契约。开源实现与本地验收已完成，结果见 [验证记录](verification.md#固定技能案例协议开源实现验收)；SaaS 后续适配。WorkBuddy 本机多案例文件提供交互与内容组织参考，不是本项目协议或兼容声明。
+
+## 1. 文件协议
+
+固定相对路径为 `.skillhub/examples.json`，随技能版本发布并原样安装，仅一份文件。作者不修改 SKILL.md，不在 Web 填写额外配置。示例：
+
+```json
+{
+  "schemaVersion": 1,
+  "defaultLocale": "zh-CN",
+  "examples": {
+    "zh-CN": [
+      {
+        "id": "meeting-summary",
+        "title": "整理会议纪要",
+        "prompt": "请使用 {{skill}} 整理会议记录，提取结论和待办。"
+      },
+      {
+        "id": "compare-proposals",
+        "title": "对比方案",
+        "prompt": "请使用 {{skill}} 对比两份方案，列出差异、风险和待确认问题。"
+      }
+    ],
+    "en": [
+      {
+        "id": "meeting-summary",
+        "title": "Summarize meeting notes",
+        "prompt": "Use {{skill}} to summarize meeting notes and extract action items."
+      },
+      {
+        "id": "compare-proposals",
+        "title": "Compare proposals",
+        "prompt": "Use {{skill}} to compare two proposals and identify differences, risks, and open questions."
+      }
+    ]
+  }
+}
+```
+
+规范性 schema 为 [skill-examples.schema.json](contracts/skill-examples.schema.json)，有效样例见 [多案例](contracts/skill-examples.valid.json) 和 [空集合](contracts/skill-examples.empty.json)。这两份样例是协议文档素材，不是运行时默认案例，不自动写入用户技能。
+
+| 项目 | 规则 |
+| --- | --- |
+| 编码/体积 | UTF-8，最多 65,536 原始字节；允许开头单个 UTF-8 BOM，解析时去除，存储和指纹不改字节 |
+| 根结构 | schemaVersion、defaultLocale、examples 三个字段；schemaVersion 必须为整数 1 |
+| examples | 语言标签到有序案例对象数组的映射，1–10种语言；每种0–20条，同一语言内 id 唯一 |
+| 单条对象 | 必含 id、title、prompt，不接受旧字符串条目；不把数字、null 等自动转成字符串 |
+| id | 1–64个ASCII字符，小写字母/数字以连字符分段；同一语言内唯一，同一逻辑案例的不同语言版本使用相同id |
+| title / prompt | title为1–80、prompt为1–4,000个Unicode码点，均至少含一个非空白字符；空白由schema显式码点定义，不依赖语言的 \s/\S |
+| 顺序 | 保留作者顺序，不按评分、语言或模型推测重排 |
+| 语言 | 使用语言标签，如 zh-CN、zh-TW、en、ja、ko；支持范围为 schema 限定的基础语言及子标签，不声明支持所有 BCP 47 扩展；不自动翻译或识别文本语言 |
+| 内容使用 | 仅以纯文本展示和带入草稿，不渲染不可信 HTML，不执行脚本或工具指令，不打开模板中的 URL |
+| 扩展 | 未知字段或协议版本按不支持处理，不静默取部分内容；将来扩展需升级协议与消费者 |
+
+语言选择规则：对宿主提供的界面语言和作者标签做规范化，依次匹配完整标签、逐级父标签，最后使用 defaultLocale。例如 zh-Hant-TW → zh-Hant → zh → defaultLocale，不能把 zh-TW 自动当成 zh-CN。若宿主未提供可用语言，直接使用作者默认语言，不读取浏览器语言覆盖 Host 上下文。同一文档内规范化后重复的语言键不合法；defaultLocale 必须对应实际声明的键。这两项及各语言集合内 id 唯一性为 schema 之外必须执行的语义校验。首期不增加语言切换控件。
+
+命中的语言数组若明确为空，直接视为没有案例，不继续跨语言兜底。一次只展示一个语言集合，不混排中英文；语言切换使旧选择失效。文件64KiB上限覆盖全部语种，单条长度与数量规则按各语言数组执行。允许某案例只提供部分语言，不要求各语言数组数量一致；不得用数组位置匹配翻译。
+
+超出案例解析体积、格式不合法或结构不合法，只意味着不识别为案例；通过通用包策略的原始文件仍保留。违反通用包大小、路径或安全规则仍按原规则拒绝。不能因案例识别失败就跳过文件哈希。
+
+### 技能占位符与插入文本
+
+`prompt` 仅支持精确占位符 `{{skill}}`，代表核验后的 DSH 原生调用（例如 `/document-helper`）。实际值来自当前会话胜出技能的真实名称，不使用市场 slug、展示名称或作者传入路径猜测。`id`、`title` 不做占位替换。
+
+- 有占位符：逐字替换所有精确的 `{{skill}}`；不解析模板表达式、过滤器或任意变量。
+- 无占位符：在 prompt 前补一行包含已核验原生调用的引导，再接作者任务文本；若现有草稿已含相同原生调用，可省略重复引导，但仍须插入明确选择的任务。
+- 其他类似 `{{...}}` 的文本保持字面值，不执行、不请求模型补值；本期没有其他可用变量。
+- title用于卡片标题，prompt作为纯文本预览与最终任务内容，不能把title当执行指令。
+
+## 2. 解析与数据状态
+
+共享 TypeScript 解析器由 CLI 核心提供，插件通过已有内置核心消费，避免 CLI 与 DSH 自建两套规则。服务端预检按相同 schema/样例识别摘要；不增加 JSON Schema 运行时生产依赖作为前提。
+
+| 状态 | 触发条件 | 产品行为 |
+| --- | --- | --- |
+| ready | 文件符合支持的协议，保留原始摘要与全部语言集合 | 按宿主语言选择；有条目时展示案例列表和自定义任务，命中空数组时直接自定义使用 |
+| none | 确认 ENOENT | 不展示空选择区，直接自定义使用 |
+| invalid | 可读取，但 JSON、结构、版本、编码或解析上限不符合协议 | 不展示案例，普通文件保留；作者预检给非阻断提示，使用端保留自定义入口 |
+| unavailable | I/O、权限或读取中断，无法确认内容 | 提示暂时无法读取；只有既有技能使用核验通过才允许自定义，不能伪装为无案例 |
+
+不把取消或来源/会话失效作为 none 返回。文件完整性失败、符号链接或安装身份失效继续阻止使用，不能利用自定义入口绕过。
+
+## 3. 本地读取与原生草稿衔接
+
+```mermaid
+sequenceDiagram
+  actor U as 用户
+  participant C as DSH 插件 Client
+  participant H as 插件 Host
+  participant K as 共享 CLI 核心
+  participant I as DSH 原生输入框
+  U->>C: 使用此技能
+  alt 技能中心入口
+    C->>I: 官方创建同工作区新对话并导航
+  else 对话入口
+    C->>I: 保留当前对话
+  end
+  C->>H: prepareSkillUse(sourceRevision, itemKey)
+  H->>K: 核验所选安装与全部发布文件，读取固定案例文件
+  K-->>H: 原始文件摘要与解析状态
+  H->>H: 核验当前会话胜出技能并复查安装
+  H-->>C: ready + examples 状态
+  alt 有案例
+    C-->>U: 输入框上方展示案例卡片与自定义入口
+    U->>C: 选择案例，确认填入
+  else 无适用案例
+    U->>C: 自定义使用
+  end
+  C->>I: 捕获当前草稿插入位置
+  C->>H: 再次 prepareSkillUse，核验相同安装和案例摘要
+  H-->>C: 当前核验结果
+  C->>I: 比较草稿版本并插入真实技能调用与任务文本
+  Note over U,I: 保留文字、引用与附件，不自动发送
+```
+
+复用现有 agent-scoped prepareSkillUse 的参数和上下文校验，扩展 ready 返回值，不新增模型工具或任意路径读取 RPC。返回类型如下：
+
+```ts
+type SkillExample = { id: string; title: string; prompt: string };
+type SkillExamples =
+  | { state: 'ready'; digest: string; defaultLocale: string; items: Record<string, SkillExample[]> }
+  | { state: 'none' }
+  | { state: 'invalid' }
+  | { state: 'unavailable'; retryable: boolean };
+// 现有 ready.name/version/scope 保留，新增 examples: SkillExamples。
+```
+
+`digest` 为案例原始字节 SHA-256，摘要不作为安装权限。Host 返回全部有界语言集合，Client 按宿主界面语言选中集合；确认状态须保持所选 locale 一致。Client 只保留所选安装标识、摘要、语言和案例 id；最终核验重新返回同摘要，且宿主界面语言未变后，使用当前返回的所选语言集合中该 id 的 prompt，不信任第一次响应中的陈旧文本。模板选择期间安装、来源、范围或会话变化立即使选择失效；摘要不匹配不得自动替换为新案例。
+
+点击选择面板的“填入输入框”才捕获当前插入位置；初次打开面板不改草稿。最终异步核验期间用户修改草稿则比较失败，保留其内容并提示重试。即使真实技能调用已存在，用户明确选择的新模板仍应可带入，不能沿用旧逻辑“发现调用 token 就忽略全部插入”；重复提交同一次动作仍需去重。
+
+案例读取需在可信目标路径下执行，限制字节、拒绝符号链接，与前后文件快照绑定；不能在完整性复查后另读未经核验的版本。传输只返回有界文本，不返回本地目录、内部 metadata 或文件读写能力。
+
+## 4. Registry 与 Web 边界
+
+技能安装时案例随 ZIP 获取，不单独下载或刷新。已安装使用路径不请求市场最新案例，不新增案例表、可变服务端配置或专用 `/examples` 接口。
+
+既有原始文件接口可供作者和版本文件浏览使用：
+
+```text
+GET /api/v1/skills/{namespace}/{slug}/versions/{version}/file?path=.skillhub%2Fexamples.json
+```
+
+响应是原始文件流，不是 ApiResponse.data JSON。路径分段与 query 需分别编码，权限和版本可见性沿用既有文件接口。本期不新增安装前案例选择或远程模板预览。
+
+现有服务端部分缺失/对象存储读取错误都映射为 HTTP 400；不得把任意 HTTP 400、404 或网络错误自动归类为没有案例。本期本地使用无需修改该通用接口错误语义。
+
+Web 复用现有发布预检，不增加表单。为实现非阻断作者提示，现有 SkillPackagePreviewResponse 增加可选 `examplesStatus: 'ready' | 'none' | 'invalid'` 和 `examplesCount`；这两个字段为向后兼容的可选扩展。examplesCount统计全部语言集合的条目总数；合法文件总数大于0为ready，合法全空或无文件为none且count=0，invalid不返回count，旧响应缺字段表示未知。此预检状态不等于某个界面语言实际可选条数。只返回识别摘要，不在预检返回第二份案例权威内容；旧响应缺少字段视为未知，不显示错误提示。OpenAPI 生成类型与消费方测试同步维护。CLI 以共享解析器对待发布文件作同样非阻断提示，不把提示混进 --json 的纯 JSON 输出。
+
+预检统计示例（与DSH实际选中语言的条目数区分）：
+
+| 文件内容 | 预检结果 |
+| --- | --- |
+| zh-CN为空，en有1条 | ready，examplesCount=1；DSH选中zh-CN时仍不展示案例 |
+| zh-CN和en各1条同id翻译 | ready，examplesCount=2，不按逻辑id去重统计 |
+| 所有语言集合为空，或没有文件 | none，examplesCount=0 |
+| 文件无法识别为协议 | invalid，省略examplesCount；旧接口无摘要字段为未知 |
+
+## 5. 发布内容与内部安装记录
+
+| 路径/入口 | 规则 |
+| --- | --- |
+| `.skillhub/examples.json` | 合法或非法协议均按原始字节进入包、manifest、指纹与安装目录 |
+| `.skillhub/metadata.json` | 仅安装器生成，排除内容指纹；不接受作者上传的安装身份 |
+| `.skillhub` 其他安全作者文件 | 普通版本文件，不识别为案例，不静默删除；纳入发布清单和完整性校验 |
+| CLI 发布目录、sync push、Web 文件夹打包 | 遍历 .skillhub，仅排除根目录内部 metadata.json，保留作者文件 |
+| 手工 ZIP 或直接 HTTP 上传 | 服务端共享包验证器对规范化后的内部 metadata 路径明确拒绝，返回可操作错误；不能只依赖 Web 过滤 |
+| 下载/本地安装 | 生成内部记录前再次拒绝包内内部 metadata，避免旧来源绕过校验；失败不发布目标或 inventory |
+
+路径判定在包根目录归一化后进行，覆盖分隔符、`.`、重复目标、大小写别名及文件/目录冲突；在跨平台存在歧义时明确拒绝，不能误将作者文件映射成内部记录。禁止符号链接、越界和不安全文件的规则保持。不能用 substring 匹配剥掉所有叫 metadata.json 的资源。
+
+## 6. 指纹、恢复与兼容发布
+
+目前 CLI/shared-core 跳过整个 .skillhub，原生恢复检查也只接受 metadata.json。两处都必须改：指纹按所有作者原始文件计算，仅排除安装器内部记录；安全目录检查结合精确 manifest 保留所有者和普通文件检查，未知增加的文件继续被视为本地改动。所有恢复/清理调用点均须审计，不得简单移除 guard 后扩大删除范围。
+
+服务端与客户端必须采用一致的路径排序、SHA-256 和聚合格式，不新建单独“案例指纹”。套件和同步复用共享内容策略，不复制模板解析或生命周期管理逻辑。现有发布版本的 ZIP、manifest 和 fingerprint 不追溯重算。
+
+已静态核实正式插件 0.3.1 的内置核心仍跳过 .skillhub 且拒绝额外文件，因此它不具备新内容规则。不能承诺“旧插件透明支持带案例的包”。首期不新增服务端消费者协商协议，采用明确最低消费者要求与旧消费者安全拒绝策略：
+
+1. 先完成并发布支持新内容规则的 CLI 和 DSH 插件，再推广包含该文件的技能版本；实际最低版本号待发布时填写，不预设不存在的包版本。
+2. 新消费者必须兼容无案例的旧技能；历史含有被旧指纹排除的作者文件须先盘点。若存在，不得修改旧版本指纹或无提示重新认领，需单独迁移设计；未完成前不能宣称该历史子集受支持。
+3. 旧消费者遇新包允许在指纹/安全检查处拒绝，但必须验证目标与库存未被覆盖；不能声称旧包会显示新代码才有的友好提示。
+4. 新安装目录被旧消费者访问时，分别验证旧原生 DSH 的内容保护与旧 CLI 的实际行为。旧 CLI remove 原本直接删除目录，强制重装也可覆盖，不能承诺它们会因新文件而拒绝；混用这些旧命令不属于支持的管理方式，应先升级消费者。不得为适配旧版伪造 metadata 或减弱指纹。
+5. 代码发布与 npm 发布为后续独立操作，本轮完成开源实现和本地验证，不自动合并、部署或发布。
+
+## 7. 实施切片与验证
+
+| 切片 | 最小产物 | 必须验证 |
+| --- | --- | --- |
+| 协议与共享内容规则 | 共享解析器/路径策略、指纹、目录与 ZIP 处理 | 合法/非法文本均计入哈希；修改/删除/新增受保护；内部 metadata 不可上传 |
+| 服务端与发布前端 | 包验证、Web 文件夹过滤、预检识别摘要 | 目录/手工 ZIP/直接 API 一致；无效案例非阻断；生成类型一致 |
+| DSH 使用交互 | 复用 ready 投影、多案例选择与自定义 | 安装范围/版本一致、上下文与摘要复验、保留草稿附件、不自动发送 |
+| 跨消费者验收 | 新旧公开包/候选、完整生命周期与真实 Host | 新→旧包、新→新包、旧→新包、旧访问新安装目录的真实边界 |
+
+核心回归包括 install/retry/upgrade/remove/sync/publish/recovery/rollback/suite 与 Use；完整命令沿用 Makefile 的 lint-cli/typecheck-cli/test-cli/build-cli、插件 check 及 Web/后端受影响测试。具体文件与命令由本地执行计划链接当前源码测试，不把源代码审计当作端到端通过。
+
+schema 样例检查与运行时验收分别记录。生产 parser、预检可选字段、生命周期及双 DSH 基线的开源验收结果见 [验证记录](verification.md#固定技能案例协议开源实现验收)；SaaS、Windows/macOS 原生宿主和 npm 发布不包含在本轮。
+
+
+实施顺序、开源与SaaS范围及验收门禁见 [执行方案](skill-examples-execution-plan.md)；SaaS对应增量见 [专用交接Prompt](skill-examples-saas-agent-prompt.md)。
diff --git a/openspec/changes/add-dsh-native-plugin/skill-examples-execution-plan.md b/openspec/changes/add-dsh-native-plugin/skill-examples-execution-plan.md
new file mode 100644
index 000000000..f536cc041
--- /dev/null
+++ b/openspec/changes/add-dsh-native-plugin/skill-examples-execution-plan.md
@@ -0,0 +1,110 @@
+# 技能使用案例：执行范围、实施顺序与 SaaS 同步
+
+## 1. 目标与当前状态
+
+在 DSH 点击“使用此技能”后，用户可以选择该技能的本地版本案例，或自定义任务，再将包含真实技能调用的内容填入原生输入框。案例固定为技能包中的 `.skillhub/examples.json`，采用多语言 id/title/prompt 对象与 `{{skill}}` 占位符，随技能版本更新。
+
+协议唯一来源是 [案例实现设计](skill-examples-design.md) 与 [JSON Schema](contracts/skill-examples.schema.json)，本文只确定执行范围、依赖和验收，不定义第二套协议。
+
+开源实现与本地验收已完成：共享核心和 CLI 保留随包案例并纳入指纹，开源后端/Web 提供非阻断预检反馈，DSH 支持多语言案例选择、末次核验与草稿衔接。完整检查、真实后端和双 DSH 浏览器结果见 [验证记录](verification.md#固定技能案例协议开源实现验收)。改动尚未提交或发布；SaaS 实施与联验后续另做，不作为本轮完成前置。
+
+## 2. 范围与责任
+
+| 模块 | 本轮开源研发范围 | 不在本轮范围 |
+| --- | --- | --- |
+| 作者协议 | 固定文件、字段/语种/占位符校验、可复制说明及样例 | 作者填写额外Web表单、修改SKILL.md、生成案例内容 |
+| 共享CLI核心 | 包路径策略、解析器、完整性指纹、内部记录保护；安装/升级/同步/恢复接缝 | 独立案例缓存、自动修复作者JSON、案例独立刷新 |
+| CLI | 目录发布与sync push保留作者文件，非阻断协议提示，正常管理带案例技能 | 新增案例管理命令、改变既有remove/force产品语义 |
+| 开源服务端 | 上传路径与内部metadata边界、发布预检识别摘要；核验版本文件/ZIP/指纹链路 | 新案例数据库表、案例编辑API、独立案例版本或CRUD系统 |
+| 开源Web | 文件夹打包精确过滤内部记录；现有发布页显示识别结果/非阻断提示 | 案例编辑器、语言配置页、市场案例展示新页面 |
+| DSH Host | 可信安装目录读取、解析状态与摘要投影、复用现有prepareSkillUse | 任意路径读取RPC、模型执行或新增服务端安装任务 |
+| DSH Client | 多案例面板、语言选择规则、标题/正文预览、自定义、占位符与原生草稿衔接 | 语言切换设置、自动翻译、自动发送、输入材料变量系统 |
+| SaaS | 本轮提供独立交接文档和一致性测试清单 | 本轮直接修改SaaS仓库、数据库、部署或生产内容 |
+| 发布 | 本轮确定依赖和门禁，研发后准备可审阅候选 | 自动提交/合并、tag、npm发布或上线 |
+
+共享核心改变后套件等现有消费者需要回归，但本轮不增加DSH套件产品能力。不将不同源手工技能纳入SkillHub案例管理。
+
+## 3. 实施顺序与交付切片
+
+```mermaid
+flowchart TD
+  A[P0 协议与历史内容基线] --> B[P1 共享核心与CLI内容规则]
+  A --> C[P2 开源服务端与Web发布链路]
+  B --> D[P3 DSH多案例与原生草稿]
+  B --> E[P4 跨端生命周期与旧消费者验收]
+  C --> E
+  D --> E
+  C --> S[SaaS Agent按同一协议适配测试环境]
+  E --> R[审阅候选与发布准备]
+  S --> T[SaaS测试环境与真实DSH联验]
+  R --> T
+  T --> P[授权后分阶段发布]
+```
+
+| 阶段 | 具体动作与产物 | 退出条件 |
+| --- | --- | --- |
+| P0 基线 | 固定schema/样例，记录实际检出基线；本地夹具建立旧包/新包/非法案例/内部记录冲突；确认宿主语言来源；盘点可访问历史包是否存在已被旧规则忽略的.skillhub作者文件 | 设计冲突解决；未知历史子集明确标注；不访问未授权生产数据 |
+| P1 共享核心与CLI | 统一根相对路径策略；指纹纳入作者文件、仅排除内部记录；解析对象/语言/占位符；修正目录发布和sync；审计恢复/回滚所有调用点 | 有效/无效案例字节均保留，未知新增/修改仍被保护；内部metadata不可伪造；CLI范围检查通过 |
+| P2 开源服务端与Web | 校验预览和发布共用内部记录拒绝规则；保留examples；现有预检响应增加可选识别摘要；Web目录打包精确过滤，显示非阻断提示；生成API类型 | 手工ZIP、文件夹、直接API一致；无案例旧包正常；存储清单/下载/resolve指纹一致 |
+| P3 DSH消费与交互 | prepareSkillUse扩展有界对象投影；使用界面语言→父语言→作者默认；面板标题/正文、按id选择、自定义；确认时复验摘要/语言/安装/草稿并替换真实调用 | 多入口共用，取消不写草稿；保留文字/引用/附件，不发送；语言与安装范围不串用 |
+| P4 端到端与兼容 | 使用实际打包候选和旧公开包完成兼容矩阵；真实本地Registry与双RC官方Host跑生命周期、浏览器及原生输入框 | 记录通过/失败/不支持，独立review无阻断问题；不以mock或schema检查代替产品验收 |
+| P5 交付准备 | 清理临时证据、回写OpenSpec与双语使用说明；提交/PR及包发布按后续授权执行 | 候选、检查记录和未验范围可审阅；不擅自发布 |
+
+P1和P2可在协议固定后分别实施，但必须使用同一组路径/字节夹具；P3可以先用受控解析夹具开发，P4必须依赖完整真实链路。先运行最小测试，再运行受影响模块完整检查。
+
+## 4. 开源代码接缝
+
+下表为已核对的当前文件，不要求为匹配规划而重命名或复制现有模块；新增helper位置由实现时的最小复用决定。
+
+| 责任 | 现有接缝 |
+| --- | --- |
+| 指纹与发布打包 | `cli/src/services/skill-fingerprint.ts`、`cli/src/commands/publish.ts`、`cli/src/services/sync-service.ts`、`cli/src/platform/archive.ts` |
+| 安装记录与安全恢复 | `cli/src/services/install-service.ts`、`cli/src/integrations/recovery-files.ts`、`upgrade-baseline.ts`、`native-installed.ts`及所有恢复调用点 |
+| 服务端路径/包检查 | `server/skillhub-domain/.../skill/validation/SkillPackagePolicy.java`、`SkillPackageValidator.java`，以及上传提取的包根归一化 |
+| 预检识别摘要 | `server/skillhub-app/.../service/SkillPackagePreviewService.java`、`dto/SkillPackagePreviewResponse.java` |
+| 版本内容核对 | `SkillPublishService`文件manifest/存储与`SkillQueryService.computeFingerprint`；现有服务端按全部SkillFile聚合，若已符合则只补测试，不重写算法 |
+| Web发布 | `web/src/features/publish/folder-zip.ts`、`web/src/pages/dashboard/publish.tsx`、现有查询hook/翻译资源、生成的API类型 |
+| DSH使用 | `plugins/dsh/src/host/index.ts`的prepareSkillUse、`host/types.ts`、`src/client/use-skill.tsx`及既有使用入口 |
+
+公开API新增字段仅限已有预检响应的可选识别摘要，旧响应缺字段保持兼容；精确返回字段见案例实现设计。已有版本文件接口已经返回原始内容流，安装后Use无需额外网络请求。实现如发现还需新端点、表或安装状态字段，先回到设计评审，不能扩大范围后再补文档。
+
+## 5. SaaS 后续同步：必须、条件项与无需调整项
+
+SaaS实际模块名称、数据结构和已部署行为需由SaaS Agent核实；下面是目标契约，不是已完成状态。
+
+| SaaS项目 | 必须达到的行为 | 是否必改代码 |
+| --- | --- | --- |
+| 文件接收和存储 | 不丢弃/改写.skillhub/examples.json；合法、非法协议均按普通安全文件保留 | 先对照，已符合则补验证 |
+| 预检和正式发布 | 同一规范化路径下，拒绝上传内部metadata；合法协议识别多语对象，非法仅非阻断提示；不能绕过扫描/审核 | 对照后补缺口 |
+| Web文件夹上传 | 只过滤根目录内部metadata，保留examples和其他允许作者文件；无案例编辑表单 | 若有目录上传或既有过滤则同步 |
+| 清单、ZIP、resolve指纹 | 作者文件全部覆盖且算法与新消费者一致，原始字节/版本/坐标对应 | 核验为必需，算法已一致不改 |
+| 精确版本文件读取 | 如已有通用file接口则复用，返回原始字节；权限/租户/可见性不变 | 现有能力充足不新增接口 |
+| 发布提示摘要 | 若复用开源Web预检体验，同步可选examplesStatus/examplesCount及OpenAPI类型；不得影响旧客户端 | SaaS有相同预检入口时实施 |
+| 本地技能管理/案例选择/占位替换 | 由CLI与DSH负责，SaaS不读取用户项目或主机目录 | 不新增服务端能力 |
+| 案例持久化 | 复用版本包文件、现有对象存储与文件清单 | 本期不新增案例表或数据迁移 |
+
+SaaS的发布、审核、删除和版本复制流程都应自然保留该文件；若存在技能包重建/过滤中间层，必须补齐该层，而非只在上传Controller加字段。原始文件API及对象存储URL不能变成绕过私有技能或跨租户隔离的通道。
+
+可直接交接的增量任务见 [SaaS案例适配Prompt](skill-examples-saas-agent-prompt.md)。旧的总体DSH交接见 [saas-agent-prompt.md](saas-agent-prompt.md)，不要重复实施已经上线的通用Registry能力。
+
+## 6. 验收矩阵与完成定义
+
+| 层级 | 核心场景 | 可观察结果 |
+| --- | --- | --- |
+| 协议 | 多语对象、空集合、非法JSON/结构/语种/id、上限和未知版本 | 解析状态准确；非法内容不变成案例，也不因此丢失文件 |
+| 发布 | CLI目录、sync push、Web目录、手工ZIP、直接API | examples路径/字节保留；内部metadata精确过滤或明确拒绝 |
+| 本地生命周期 | install/retry/upgrade/remove/sync/rollback/recovery/suite | manifest/库存/目录一致；本地案例改动受保护，恢复不误删未知文件 |
+| UI | 多案例和自定义、语言回退/变化、占位符/无占位符、重复点击/取消 | 选择按id，真实name而非slug；保留草稿附件且无自动发送 |
+| 上下文 | 用户/项目、同名覆盖、不同Registry/版本、读取期间切会话 | 不串用、不插入陈旧任务，不因模板存在跳过可调用性核验 |
+| 消费者兼容 | 新消费者→旧无案例包、新→新案例包、旧→新包、旧访问新安装目录 | 用实际产物观察成功或拒绝/原行为，明确不支持混用，不假称全兼容 |
+| SaaS测试环境 | 发布→精确版本读取/下载→新DSH安装→选择案例→升级/卸载 | 真实目标环境全链路成立；不能仅以HTTP200或单测代替 |
+
+兼容发布顺序为：开源候选完成联验→授权发布支持新规则的CLI/DSH→SaaS适配测试环境联验→授权部署SaaS→推广带案例的新技能版本。SaaS研发可提前并行，不必等npm发布，但生产推广必须等兼容消费者可用。
+
+新旧包与旧二进制不能全量透明兼容。旧CLI的remove/force行为沿原语义，新设计不能改变已经发布的二进制；旧DSH拒绝的具体动作需实际验证。历史包字节、版本号和指纹不得回算。出现历史被忽略作者文件时保持独立迁移门禁，不自动修改旧安装记录。
+
+回退软件版本前先确认是否仍需管理新格式安装；优先停止推广新案例技能并保留已安装目录及可管理它的新消费者，不通过删除examples或伪造metadata来迁就旧客户端。SaaS应用回退不修改历史对象/文件清单。
+
+本功能的确定性验收以原生草稿与文件生命周期为主，不要求真实模型调用来证明模板填入正确；若增加模型执行体验验收，单独记录模型配置、额度和真实对话证据，不把模型输出当作文件兼容证明。
+
+完成定义：P1–P4实现与验证通过、文档/任务状态与证据一致、SaaS增量交接可执行。SaaS部署、npm发布及生产可用性为后续独立交付状态，不能被本地完成所代替。
diff --git a/openspec/changes/add-dsh-native-plugin/skill-examples-saas-agent-prompt.md b/openspec/changes/add-dsh-native-plugin/skill-examples-saas-agent-prompt.md
new file mode 100644
index 000000000..00f499753
--- /dev/null
+++ b/openspec/changes/add-dsh-native-plugin/skill-examples-saas-agent-prompt.md
@@ -0,0 +1,77 @@
+# SaaS Agent 增量任务：版本化多语言技能案例
+
+以下正文可以直接交给拥有SaaS仓库访问权限的Agent。当前任务是接入固定案例文件协议，不重做已有DSH Registry支持。先输出基于真实代码的差异表，再按SaaS项目流程研发、测试和提交PR；没有授权不要部署生产。
+
+## 目标与先读资料
+
+让同一个新SkillHub CLI/DSH候选能够从SaaS发布、下载并安装带`.skillhub/examples.json`的技能，原始文件完整保留，案例选择和真实技能占位符由DSH本地处理。
+
+开源权威资料：
+
+- `openspec/changes/add-dsh-native-plugin/skill-examples-design.md`：路径、协议、语言回退、内部记录与兼容边界。
+- `openspec/changes/add-dsh-native-plugin/contracts/skill-examples.schema.json`及valid/empty样例：唯一协议契约。
+- `openspec/changes/add-dsh-native-plugin/skill-examples-execution-plan.md`：范围、验收与阶段顺序。
+- `openspec/changes/add-dsh-native-plugin/registry-api-contract.md`：已有HTTP访问规则。
+
+开源工作分支已完成本功能及本地验收，但尚未提交或发布。移植前确认通过验收的最终开源提交和双方真实差异，以运行代码、测试和本文契约为依据；开源本地通过不代表 SaaS 已兼容。
+
+## 协议概要
+
+文件是技能包的版本化作者资源，不是安装后生成的缓存，不独立刷新。根包含schemaVersion、defaultLocale、examples；examples按语言标签分组，每条含id/title/prompt，同一逻辑案例跨语言同id。prompt中的精确`{{skill}}`由DSH使用核验后的真实调用替换，服务端不替换、不执行、不翻译。
+
+合法协议识别为案例；错误JSON、结构或不支持协议按普通文件保留，不阻断正常技能发布；通用包大小/路径/安全规则仍有效。缺失文件不影响旧技能。不要兼容此前讨论但已废弃的字符串数组、外置缓存或单独案例表方案。
+
+## 第一步：差异调查
+
+逐项给出“实际类/方法或路由、现有行为、缺口、拟改位置、测试方式”：
+
+1. ZIP提取和包根归一化、Windows路径/大小写及重复目标处理。
+2. .skillhub是否被目录上传、包重建、扫描输入、对象存储或下载链路排除。
+3. 文件manifest、每文件SHA、resolve聚合fingerprint和下载ZIP是否覆盖全部作者文件。
+4. 上传metadata是否被信任或覆盖，预检与正式发布是否走相同规则。
+5. 是否已有包预检摘要、原始文件流接口和可选字段向后兼容机制。
+6. 审核/复制/版本切换/删除中间层是否保留文件和访问隔离。
+
+不要猜测与开源同名类，也不要先创建表或新接口。已经符合的部分只补验证，不为对齐开源结构而重构。
+
+## 第二步：实现最小差异
+
+### A. 文件与内部记录
+
+- 原样保存`.skillhub/examples.json`，包括无法识别为协议但通过通用包校验的文件。
+- `.skillhub/metadata.json`仅安装器所有，不允许作者上传的身份进入发布包。Web目录打包可精确排除；手工ZIP/直接API在服务端归一化后明确拒绝，不静默覆盖。
+- 允许的其他作者文件按普通内容保留，不能整体过滤.skillhub或忽略所有JSON。
+- 不新增任意路径读取，不放宽路径穿越、符号链接、跨租户、私有/撤回/未审核访问规则。
+
+### B. 协议识别与Web体验
+
+- 按schema和补充语义验证：默认语言存在、规范化语言不重名、同语言id不重复、Unicode长度和字节上限一致。
+- 在现有预检区域展示“已识别案例”或简短非阻断格式提示，不增加案例编辑器或语言设置表单。
+- 若采用开源预检投影，新增可选examplesStatus/examplesCount，并同步OpenAPI/消费类型。count统一统计全部语言条目总数；合法非空为ready，合法全空或无文件为none且count=0，invalid省略count，旧响应缺字段视为未知；不只统计默认语言。
+- 预检输出不创建第二份服务端可变案例；源文件仍是唯一内容。
+
+### C. 分发与指纹
+
+- 复用现有版本文件和对象存储，不新增案例数据库表；若声称必须迁移先解释当前存储为何不能保存普通JSON文件。
+- resolve指纹覆盖的路径/哈希与新消费者快照一致，合法及非法案例都参与。保持既有算法，若已包含全部作者文件则不改。
+- 已有精确版本file接口足够时直接复用，返回原始字节，不加ApiResponse包装；本地Use不需要服务端新案例端点。
+- 缺失、读取失败、拒绝访问、限流或不可见不可混同；不要为新案例顺带重构通用错误码。实际语义如影响新消费必须单独列明。
+
+## 第三步：测试与联验
+
+使用隔离测试技能和新版本，不改现网作者内容。至少覆盖：
+
+- 无案例旧技能；中英文及第三语言；同id翻译/不同语言条数；默认回退与显式空集合。
+- 错误JSON/未知版本/重复id/过长文本按普通内容发布且字节不变；危险包仍被拒绝。
+- CLI目录、Web目录、手工ZIP、直接API；metadata路径别名、重复目标、大小写冲突和符号链接。
+- 发布审核后的文件清单、原始file读取、下载ZIP与resolve指纹逐一一致。
+- 私有、跨租户、撤回和不可见版本保持原规则。
+- 新CLI/DSH候选接测试Registry，完成安装→多案例选择→原生草稿→升级→卸载；用户/项目两个范围各验，不自动发送。
+
+旧消费者兼容不能用源码猜测通过。至少记录旧→旧、新→旧、新→新、旧→新包的实际结果；某些旧CLI删除/force会按原规则执行，不能承诺被新协议阻止。历史包指纹/ZIP不能回算；不支持的历史子集先列出，不自动迁移。
+
+## 交付与发布边界
+
+交付：差异表、SaaS PR、变更/无须改动说明、测试命令与结果、生成类型、实际测试环境版本、新插件候选信息及脱敏联验报告。对未执行平台、环境或模型测试明确标注，不报作通过。
+
+先完成测试环境验证。支持新内容的CLI/DSH正式可用、SaaS测试联验通过并获得授权后，再部署SaaS及推广新案例技能；不得因收到本Prompt就发布npm、部署生产或改历史版本。生产验收必须针对实际目标环境另行记录。
diff --git a/openspec/changes/add-dsh-native-plugin/specs/dsh-native-experience/spec.md b/openspec/changes/add-dsh-native-plugin/specs/dsh-native-experience/spec.md
index a8ea61574..1b4e938e7 100644
--- a/openspec/changes/add-dsh-native-plugin/specs/dsh-native-experience/spec.md
+++ b/openspec/changes/add-dsh-native-plugin/specs/dsh-native-experience/spec.md
@@ -420,3 +420,135 @@ Selecting a version SHALL be read-only. For an installed skill, a newer verifiab
 - **WHEN** any required installed target cannot pass the existing baseline or ownership checks
 - **THEN** confirmation is blocked for the entire upgrade and no target is overwritten
 - **AND** current installed state remains independently queryable
+
+
+### Requirement: Verified native skill-use handoff
+The plugin SHALL offer a common “使用此技能” action on installed cards, installed or matching-version skill details, and completed installation surfaces. It SHALL revalidate the exact current-Registry installed record, selected scope, local file integrity and effective native DSH skill in the active session before inserting an editable invocation into the native composer. It SHALL preserve the existing draft, references and attachments and SHALL NOT submit messages, call a model, execute a skill, install files or change skill enablement. See use-skill-design.md for interaction and architecture.
+
+#### Scenario: Installed market coordinate differs from native skill name
+- **WHEN** the selected installed record is valid and its parsed native skill name differs from the market slug
+- **THEN** the plugin inserts the verified native user invocation rather than guessing from the market slug
+- **AND** focuses the target session composer, leaving sending to the user.
+
+#### Scenario: Installed skill cannot be safely invoked
+- **WHEN** files or inventory have changed, the native winner belongs to another location, the selected skill is not discovered, or user invocation is disabled
+- **THEN** the action gives a concise actionable reason and leaves the draft and attachments untouched.
+
+#### Scenario: Context or draft changes during verification
+- **WHEN** the active session, workspace, source revision, composer or component lifetime changes, or native insertion comparison fails
+- **THEN** the late result does not overwrite or submit any draft, including a newly selected session.
+
+#### Scenario: Completed receipt is historical
+- **WHEN** use is requested from an installation-success surface
+- **THEN** the plugin rereads current inventory and matches source, coordinate, scope and version before preparing use
+- **AND** a removed or upgraded historical target is not silently substituted with another installed version.
+
+
+### Requirement: Versioned skill examples at one fixed package path
+SkillHub SHALL recognize task examples only at `.skillhub/examples.json` relative to the skill root. Upload, download and installation SHALL preserve this single file and its bytes as versioned skill content. Examples SHALL follow the selected installed version. The feature SHALL NOT require editing SKILL.md, a separate Web configuration editor, an external examples cache or an independently refreshed copy. Detailed schema and cross-layer lifecycle rules SHALL be defined before implementation; see use-skill-design.md.
+
+#### Scenario: An author uploads valid multiple examples
+- **WHEN** a package contains protocol-valid `.skillhub/examples.json` with multiple task templates
+- **THEN** the templates are associated with that exact skill version and remain at the same relative path after installation
+- **AND** selecting use offers applicable templates and a custom-task entry without automatically sending a message.
+
+#### Scenario: Example protocol is invalid or the file is absent
+- **WHEN** the fixed file is absent or has invalid JSON or an invalid example structure
+- **THEN** the skill remains usable through custom task entry without fabricated examples
+- **AND** an existing invalid file is retained as ordinary versioned skill content with a non-blocking publication notice, subject to all normal package safety checks.
+
+#### Scenario: A similarly named file or unsafe package is uploaded
+- **WHEN** JSON is supplied at another path or package content violates general safety rules
+- **THEN** other-path JSON is not interpreted as task examples and unsafe content follows existing rejection rules
+- **AND** uploaded content never overrides or gains the authority of installer-internal `.skillhub/metadata.json`.
+
+#### Scenario: Skill content passes through publishing and local lifecycle operations
+- **WHEN** supported CLI, Web and DSH consumers publish, install, retry, sync, upgrade, remove or recover a skill containing the fixed file
+- **THEN** package manifests, fingerprints, backups and directory checks consistently account for that file, including protocol-invalid ordinary content
+- **AND** local modifications retain existing overwrite protection rather than being ignored as cache changes.
+
+#### Scenario: Version or installation scope differs
+- **WHEN** a user selects a different installed version, source or user/project installation
+- **THEN** templates come from that exact selected installation, never from another version or scope
+- **AND** existing native invocation, current-session and draft checks still apply.
+
+#### Scenario: Legacy skills and consumers are evaluated
+- **WHEN** an old skill has no examples file or an older CLI/plugin accesses a new-format installation
+- **THEN** the old skill remains usable and consumer compatibility is explicitly tested and documented
+- **AND** unsupported consumers are not claimed compatible merely because the current implementation is updated.
+
+
+### Requirement: Localized packaged skill examples
+The examples protocol SHALL support language-tagged arrays of objects with id, title and prompt, and an author-declared defaultLocale. Consumers SHALL select the host UI locale by exact tag, progressively less-specific parent tags, then the declared default. They SHALL NOT automatically translate, mix language collections or select an arbitrary first language. Canonically duplicate tags or a missing declared default collection SHALL be protocol-invalid, with ordinary-file fallback.
+
+#### Scenario: Multiple languages are supplied
+- **WHEN** a valid examples file provides Chinese, English or other supported language collections
+- **THEN** the matching host-language collection is displayed in author order
+- **AND** missing matches use the declared default while an explicitly empty matched collection remains empty.
+
+#### Scenario: Locale changes while selecting an example
+- **WHEN** the host language changes after a template selection is prepared
+- **THEN** the old selection is invalidated rather than inserting a different localized item under the stale selection.
+
+
+### Requirement: Structured examples and verified skill placeholder
+Each example SHALL contain a stable id, display title and editable prompt. IDs SHALL be unique within each language collection; translations of the same logical example SHALL use the same id without requiring equal collection sizes. String-only entries SHALL be protocol-invalid. The consumer SHALL replace only the exact `{{skill}}` placeholder in prompt with the verified native skill invocation and SHALL NOT evaluate template expressions or infer the invocation from the market slug.
+
+#### Scenario: A localized structured example is chosen
+- **WHEN** the user confirms an example selected by language and id
+- **THEN** the current file digest and installation are revalidated and the current matching prompt is used
+- **AND** all exact skill placeholders are replaced with the verified invocation while title remains presentation text.
+
+#### Scenario: Prompt has no supported skill placeholder
+- **WHEN** the chosen prompt has no exact skill placeholder
+- **THEN** the consumer supplies the verified invocation separately and preserves the chosen task text
+- **AND** other template-like text remains literal, with no code evaluation or automatic sending.
+
+
+### Requirement: Native conversation case selection by entry context
+Catalog skill-use entries SHALL create and activate a new conversation in the same workspace. Conversation and tool-receipt entries SHALL remain in their current conversation. After target-session verification, task examples SHALL appear inline above the native composer rather than in a modal. The plugin SHALL use supported official session and slot APIs and SHALL NOT send messages or call models.
+
+#### Scenario: Catalog use starts a separate task
+- **WHEN** the user selects use from a skill-center installed card, matching detail or installation-success surface
+- **THEN** exactly one new conversation is opened in the same workspace and task examples expand above its composer
+- **AND** the original conversation draft, references, attachments and messages remain unchanged
+- **AND** the selected source, installed version and scope are revalidated for the new conversation rather than replaced by latest or another installation.
+
+#### Scenario: Conversation use preserves context
+- **WHEN** use is selected from a conversation detail or tool installation receipt
+- **THEN** the existing conversation remains active and its composer displays the inline case options
+- **AND** case confirmation inserts editable text while preserving existing draft content and attachments.
+
+#### Scenario: Cancel, missing examples and stale navigation
+- **WHEN** the user cancels inline case selection
+- **THEN** no text is inserted and no conversation or message is deleted
+- **WHEN** no applicable case exists
+- **THEN** no empty case picker appears and the verified custom-use handoff remains available
+- **WHEN** session creation fails, or the source, workspace or active conversation changes before insertion
+- **THEN** late work cannot overwrite the old draft or redirect the user back to a stale session.
+
+
+#### Scenario: Native draft ownership survives the navigation
+- **WHEN** catalog use would release the original conversation's last native view reference while its input has draft text, references, attachments or an unfinished input state
+- **THEN** the plugin retains the original native session shell before navigation and preserves its full native input state
+- **AND** it releases this temporary protection when the original main view resumes, the draft is cleared/sent, the session is removed or invalidated, or the plugin is disposed
+- **AND** creation failure or cancellation before navigation releases the temporary reference without changing the draft
+- **WHEN** eight previous nonempty drafts are already protected
+- **THEN** another catalog-use action is refused before creating a conversation, with a concise instruction to revisit earlier drafts rather than evicting them
+- **AND** this runtime protection does not promise attachment persistence across browser reload, shutdown or plugin disposal.
+
+#### Scenario: 案例填入不产生额外首尾空行
+
+- **WHEN** 用户确认案例或自定义任务并填入空的原生输入框
+- **THEN** 插件不在正文前后额外添加换行，保留作者模板原有换行
+- **AND** 插入已有草稿时只为紧邻且缺少换行的正文增加必要分隔，不重复已有换行
+- **AND** 带引用、中文及 emoji 时仍使用原生捕获跨度和草稿版本，保留引用与附件，不自动发送
+
+#### Scenario: Conversation detail hands off without blocking case selection
+- **WHEN** the user selects use from an installed skill in a conversation search-detail modal and initial verification succeeds
+- **THEN** the resident controller takes ownership before closing the detail modal and revealing inline cases
+- **AND** unmounting the originating button does not cancel the handed-off choice, while session/source/CAS guards remain active
+- **WHEN** initial verification fails
+- **THEN** the detail remains open with an error
+- **WHEN** the user cancels case selection
+- **THEN** no draft is written and the detail is not reopened.
diff --git a/openspec/changes/add-dsh-native-plugin/tasks.md b/openspec/changes/add-dsh-native-plugin/tasks.md
index cf82ba4b3..08dbbb229 100644
--- a/openspec/changes/add-dsh-native-plugin/tasks.md
+++ b/openspec/changes/add-dsh-native-plugin/tasks.md
@@ -302,3 +302,44 @@
 - [ ] 38.1 将包版本及双语安装、发布说明更新为 `0.3.1`，完成候选检查与发布准备 PR。
 - [ ] 38.2 使用 `dsh-v0.3.1` 和专用工作流发布 npm，核对实际上传产物、公开版本和完整性。
 - [ ] 38.3 从 npm 下载公开包，完成隔离 DSH 安装与关键操作复验，并记录已验证平台及未验范围。
+
+
+## 39. 使用此技能
+
+- [x] 39.1 完成真实宿主输入框与技能发现研究，更新产品、接口和正式需求；创建并维护本地 Trellis 任务。
+- [x] 39.2 Host 提供只读使用核验，绑定当前来源、记录、范围与会话，核验文件完整性、实际技能与用户调用规则。
+- [x] 39.3 已安装卡片/详情/安装成功提供统一入口；保留原生草稿和附件、回到会话并聚焦，不自动发送。
+- [x] 39.4 补齐竞态与阻止分支测试，完成完整插件检查及两版真实 DSH 浏览器验收。
+- [x] 39.5 独立 Review、清理公开 diff 并保存任务证据，回写验证结果；本期不发布 npm。
+
+
+## 40. 技能专属使用案例：固定文件协议
+
+- [x] 40.1 对照官方资料与本机 WorkBuddy 文件，区分已验证的多案例元数据与尚未核实的内部 API/刷新机制。
+- [x] 40.2 确认固定 `.skillhub/examples.json`、单份随包发布、自动识别、无 Web 编辑入口及无效协议按普通文件处理；替代此前缓存/独立刷新方案。
+- [x] 40.3 更新需求、设计和领域术语，补齐正式验收场景；本轮仅文档调整。
+- [x] 40.4 冻结 JSON schema、有效/空样例、边界限制和按语言标签组织的 id/title/prompt 多语言案例对象、{{skill}} 替换与明确回退规则；明确复用文件 API、拟新增 Remote/预检投影、内部 metadata 上传处理与旧消费者不透明兼容策略。见 skill-examples-design.md；这里只完成设计，不表示代码或跨版本验收通过。
+- [x] 40.5 实现共享核心指纹/目录/发布规则与 CLI、Web、服务端包处理一致性；覆盖升级、卸载、同步、恢复及套件。
+- [x] 40.6 实现当前安装版本的案例读取、模板选择和自定义草稿衔接，不新增独立刷新和自动发送。
+- [x] 40.7 完成跨端生命周期、双 DSH 基线、旧技能和旧消费者兼容验证，记录实际支持边界与剩余缺口。
+
+
+### 40执行与SaaS交接补充
+
+- [x] 40.8 确定开源P0–P5执行范围、依赖和验收，提供SaaS增量交接Prompt；本项完成仅代表方案交付。
+- [ ] 40.9 【后续，非本轮开源门禁】SaaS Agent核对真实仓库并提交差异表/适配PR，完成测试环境与新消费者联验；部署与生产验收另记，不纳入当前开源本地完成状态。
+
+执行权威见 skill-examples-execution-plan.md，协议见 skill-examples-design.md；40.5–40.7开源实现与本地验收已完成，详见 verification.md；SaaS、原生 Windows/macOS、真实模型及发布保持独立验收。
+
+
+## 41. 原生新对话与输入框案例选择
+
+- [x] 41.1 确认技能中心新建同工作区对话、对话入口保留当前会话、输入框上方案例区与取消/无案例边界，同步正式设计与场景。
+- [x] 41.2 核对两版官方会话创建/导航和输入框 slot，落实所有入口的统一内联选择、严格安装身份重读、去重与导航失效保护。
+- [x] 41.3 完成相关行为测试、插件完整检查和双基线真实浏览器验证；保留原会话草稿/附件并确认无发送/模型调用，更新预览与结果。
+
+- [x] 41.4 对每语种20条、最长标题/正文进行真实宿主布局压力验证，确保固定操作区、列表独立滚动、行高不压缩、长词不横向溢出；检查矮窗口与窄窗口。
+
+- [x] 41.5 修复模板填入空输入框时多出首行空白；验证已有换行、中文/emoji、原生引用及附件保留，完成双 RC 浏览器复验。
+
+- [ ] 41.6 最终独立评审修复对话详情弹层阻挡案例选择及 Windows 分隔符 ZIP 目录识别；补相应回归，核对最终产物与正式协议。
diff --git a/openspec/changes/add-dsh-native-plugin/use-skill-design.md b/openspec/changes/add-dsh-native-plugin/use-skill-design.md
new file mode 100644
index 000000000..93be1d8c3
--- /dev/null
+++ b/openspec/changes/add-dsh-native-plugin/use-skill-design.md
@@ -0,0 +1,190 @@
+# 使用此技能：产品与实现设计
+
+## 目标和边界
+
+将“安装完成”衔接到用户发起技能任务。用户点击“使用此技能”，插件核验当前会话实际可用的本地技能，按入口选择新对话或当前对话，将原生技能调用和可编辑任务引导带入对应输入框。用户自行补充材料并发送；本功能不发送消息、不调用模型、不执行技能、不变更技能文件。
+
+本期仅消费当前 Registry 的可信安装记录。场景助手、技能套件、专家中心、技能启停、自动执行、其他来源管理及 SaaS 接口调整不在范围内。不新增 HTTP API、模型工具或持久化使用记录。
+
+## 产品交互
+
+| 入口 | 展示条件 | 点击行为 |
+| --- | --- | --- |
+| 技能中心中的已安装卡片、已安装详情、匹配安装版本的市场详情与安装成功面板 | 当前范围记录为 present，或重读库存确认同坐标/版本/范围仍存在 | 在同一工作区创建新对话，打开原生对话页，再核验并在输入框上方展开案例区 |
+| 对话中的详情、工具安装回执 | 当前库存包含所选同坐标、版本与范围 | 保留当前对话，在原生输入框上方展开案例区 |
+
+入口复用小尺寸 shadcn Button 和 DSH 主题。技能中心不把新任务追加进原会话；原会话的文字、引用、图片与消息记录均保留。新对话必须属于进入技能中心时的当前工作区，不创建新项目、不猜测其他工作区、不沿用另一会话的安装授权。新建、切换与原生输入框挂载期间显示忙碌并去重；失败清楚提示，不写入旧会话，也不自动调用模型。
+
+### 对话页案例区
+
+- 使用 DSH 官方会话和输入框扩展能力，不替换宿主编辑器，不弹出第二个案例弹窗。
+- 案例区置于目标对话的原生输入框上方，显示技能名称、可点击的案例卡片（标题与简短 prompt 预览）、取消、自定义任务及确认填入。
+- 每种语言最多20条案例。多案例列表在有限高度内独立滚动，头部和底部操作固定；卡片行高按内容确定，不为容纳全部案例压缩行高。标题和正文预览分别最多2行，长英文单词/路径可断行，完整模板仍按原始prompt填入，不因视觉截断丢内容。面板最多两列，内容宽度不超过540px时切为单列；面板高度上限340px，与宿主输入框宽度变量对齐。最后一条可滚动到达、选择，底部确认保持可见。
+- 模板与自定义任务写入空输入框时不额外添加首尾换行；插入已有正文时仅在紧邻内容且原边界没有换行时增加分隔。保留作者模板原有换行，不 trim 用户草稿或作者内容。引用 chip 按宿主 detect 投影判断边界，仍使用原生捕获的跨度与草稿版本进行比较插入。
+- 对话详情中的“使用此技能”首次核验成功且驻留控制器接管请求后，关闭详情弹层，再展开输入框案例区；详情不得遮挡选择。首次核验失败保留详情与错误；取消案例不写草稿、不重开详情。无案例的自定义衔接保持成功填入后关闭。
+- 展开案例区不写草稿。选择卡片后点击“填入输入框”才将对应模板带入；用户可继续编辑和补充附件，最后自行发送。
+- 没有适用案例时不显示空卡片区，按既有核验流程带入技能引用与自定义任务提示；暂时读不到案例与确实无案例分别提示。
+- 对话入口保留该会话已有文字、引用、附件；技能中心入口的新对话保持原工作区，所选安装范围不改变。用户级技能仍须核验当前项目中的实际胜出 Provider。
+- 关闭案例区不填入、不发送、不删除对话；已创建的新对话保持为空供用户继续使用，不自动删除会话。
+- 来源、目标会话、工作区、安装版本/范围、宿主语言变化时撤销陈旧选择；不能把选项或响应迁移到用户手动切换的另一会话。用户在案例选择期间可以编辑草稿，最终异步核验期间发生编辑则比较失败，不覆盖内容。
+
+### 原草稿的原生生命周期保护
+
+两个支持 RC 的原生会话在最后一个 retain 释放后会销毁输入 shell 并回收未发送附件，旧 RC 的语义引用也不能依赖草稿持久化恢复。因此新对话导航前，必须用官方会话 retain 保留存在文字、引用、附件或未结束输入状态的原会话，保留完整原生输入对象，不序列化/复制附件或查找 DOM。
+
+用户返回原会话且 mainView 接管后释放临时保留；原草稿已清空/发送、会话移除或真实作用域失效、插件卸载时也应清理。创建失败或尚未切离原会话就取消时及时释放。最多保护 8 个仍含草稿的原会话；到达上限时在新建前拒绝本次动作，提示返回已有对话处理草稿，不驱逐旧会话或静默丢弃内容。空会话不占保护名额。
+
+该机制保护本次运行期间的会话切换，不承诺跨浏览器刷新、关闭页面或插件停用的附件持久化；这些场景仍遵循宿主原生生命周期。两 RC 验收必须切回原会话实际确认文字、引用 chip 和可解码图片均仍存在，不能以新会话草稿正确替代此项。
+
+### 会话与安装身份
+
+新对话通过支持版本的官方创建和导航 API 建立；新对话的原生输入动作就绪后才允许选择与填入。记录绑定仍由 Host 提供，若新会话需要新的 opaque itemKey，必须在该会话重读库存，严格匹配原来源、坐标、版本和范围，不能改用 latest 或同名技能。新建前后的来源、工作区与活动会话都需复查；创建失败或用户中途导航时停止，不跳回抢占用户正在编辑的会话。
+
+## 状态与失败处理
+
+```mermaid
+stateDiagram-v2
+  [*] --> idle
+  idle --> checking: 点击使用
+  checking --> blocked: 记录变化/本地文件变化/不可发现/同名覆盖/禁止用户调用
+  checking --> stale: 来源或会话、工作区、输入框变化
+  checking --> choosing: 本地身份及原生调用核验通过且有案例
+  choosing --> drafting: 确认案例或自定义
+  checking --> drafting: 无适用案例
+  choosing --> idle: 取消
+  choosing --> stale: 上下文变化
+  drafting --> stale: 原生插入比较失败
+  drafting --> ready: 保留草稿并插入调用
+  blocked --> idle: 用户处理后重试
+  stale --> idle: 回到当前会话后重试
+  ready --> [*]: 用户自行编辑和发送
+```
+
+核验仅说明所选技能在核验时可用，不等于安全审核通过或任务执行成功。就地错误说明无法使用的原因；不展示内部路径、原始文件内容或冗长诊断作为常规结果。
+
+## 架构与模块边界
+
+```mermaid
+sequenceDiagram
+  actor User as 用户
+  participant UI as 插件使用入口
+  participant Input as DSH 原生输入框
+  participant Host as SkillHub Host Remote
+  participant Core as 本地安装核心
+  participant Skills as DSH Skills
+  User->>UI: 使用此技能
+  alt 技能中心入口
+    UI->>Input: 官方创建同工作区新对话并显示输入框
+  else 对话入口
+    UI->>Input: 保留当前会话
+  end
+  UI->>Host: prepareSkillUse(sourceRevision,itemKey,signal)
+  Host->>Core: 重读选定安装记录与可信范围，校验文件指纹
+  Host->>Skills: 按 SKILL.md 实际名称读取当前会话胜出技能
+  Skills-->>Host: 真实技能、Provider 与调用规则
+  Host->>Core: 再核验记录与目标，防止异步期间变化
+  Host-->>UI: ready(name,version,scope) 或 blocked(reason)
+  UI->>UI: 再核验来源、当前会话和输入框身份
+  UI->>Input: 展开输入框上方案例区，等待选择
+  User->>UI: 确认案例或自定义
+  UI->>Host: 重新核验安装、案例摘要与上下文
+  UI->>Input: captureInsertion / insertText，保留附件与既有文字
+  Input-->>UI: 比较成功或草稿已变化
+  UI->>Input: 收起案例区并聚焦目标输入框
+  Note over User,Input: 插件不发送；用户编辑后自行发送
+```
+
+Host 是安装身份与文件校验边界；Client 只提交 opaque itemKey 和 sourceRevision，不提交本地路径或期望技能名称。Host 复用 readInstalledItem、可信根解析和现有只读指纹校验，不复用会进入安装/卸载事务的执行函数。当前直接安装记录可以复用单目标只读 baseline 检查；共享所有权等暂不支持的记录明确阻止，不能使用整组升级 baseline 导致其他项目范围被误判。
+
+临时 FileSystemSkillProvider 仅加载已验证目录，includeDefaultRoots=false、watch=false，始终 dispose，不注册远程 Provider。按真实 name 对比 DSH skills.get 的胜出目录、路径、正文、调用字段和 metadata。名称必须可由 DSH 原生用户调用语法准确表达，userInvocable=false 不允许通过自然语言绕过。
+
+Client 在统一会话组合层封装服务，所有入口复用同一路径。使用原生 InputActions.captureInsertion / insertText 的比较机制保留内容与附件，不使用 DOM 查找、模拟按键、替换草稿、beginCommand 或自动 submit。服务身份比较使用 Cordis 的原始实例，不能把每次查询产生的新代理当成服务替换。异步期间检查 session 对象、cwd、来源 revision、活动会话、输入框服务及组件生命周期；取消和陈旧响应不写入另一个输入框。
+
+## 插件 Remote 接口
+
+| 项目 | 定义 |
+| --- | --- |
+| 方法 | agent-scoped prepareSkillUse(sourceRevision: string, itemKey: string, signal: AbortSignal) |
+| ready | { status: 'ready', name: string, version: string, scope: 'user' \| 'project', examples: SkillExamples } |
+| blocked | { status: 'blocked', reason: string }；reason 使用受控类型，Client 映射中文提示 |
+| 上下文失效 | 沿用 skillhub/context-stale；没有副作用，不自动恢复或切换来源 |
+| 返回限制 | 不返回本地目录、技能全文、附件内容；ready 仅用于当前一次原生草稿衔接 |
+
+实际错误 reason 枚举与行为由同目录 [interface-design.md](interface-design.md#使用此技能只读当前会话核验) 及插件共享类型保持一致；新增接口由现有 Typert 构建生成，兼容两版共同 ABI。此接口不是模型工具，不接受调用路径、任意名称或文件写入参数。
+
+## 兼容与验收
+
+支持现有明确验收的 DSH 0.2.0-rc.2、0.2.1-rc.2。原生输入框相关模块按宿主服务声明加载；缺少服务时显示不可用，不用轮询或页面 DOM 兜底。
+
+| 验收层 | 必须证明 |
+| --- | --- |
+| Host 行为 | slug 与真实 name 不同、文件/资源被改、记录/来源/会话变更、项目覆盖用户级技能、禁止用户调用、未发现、取消和服务失效 |
+| Client 行为 | 三入口共用、版本/范围准确、原生草稿比较、保留文字附件、重复点击、异步切会话/来源/输入框、无自动发送 |
+| 构建 | 固定 Bun 版本的完整插件 check；契约生成、lint、类型与全部插件测试 |
+| 双 RC 真宿主 | 隔离 Profile 安装候选，真实浏览器完成三入口、原生编辑器草稿与附件、失败不污染草稿；记录宿主版本和实际产物 |
+
+运行报告、截图和临时宿主不进入公开 PR。验收通过后在 verification.md 写入简短结果与证据位置；尚未执行的项保持未勾选。模型执行不是“带入草稿”的验收前提，不能把无模型浏览器测试称为真实模型验收。本轮不发布 npm。
+
+
+## 技能专属使用案例：固定文件约定
+
+### 产品与范围
+
+案例是技能作者提供的可复用任务模板，同一技能支持多条，不同技能拥有各自的模板集合。点击“使用此技能”时，有适用案例则展示选择面板，并提供自定义任务入口；无案例的旧技能仍可自定义使用。选择结果形成可编辑任务草稿，延续既有真实技能核验、原生输入框比较插入、保留文字和附件、不自动发送的边界。
+
+首期采用固定位置文件、随技能版本发布的方案。不建设 Web 案例编辑器或独立配置入口，不修改 SKILL.md，不生成虚构案例。此前讨论的外置缓存、两份案例文件、独立刷新案例和作者更新 API 不属于本期方案。
+
+### 唯一文件位置
+
+```text
+技能目录/
+├── SKILL.md
+└── .skillhub/
+    └── examples.json
+```
+
+作者上传的技能包与安装后的技能目录保持相同相对路径：`.skillhub/examples.json`。不将文件改名或复制为另一个案例副本，不在浏览器、插件安装目录或 DSH 全局缓存另建权威案例文件。案例默认属于所安装的技能版本，更新案例通过发布及安装相应技能版本完成；切换版本不得沿用另一版本的案例。
+
+`.skillhub/metadata.json` 是安装器内部身份与生命周期记录，与作者案例文件职责不同。上传内容不得覆盖、伪造或获得该内部记录的信任；其上传处理规则按 [案例实现设计](skill-examples-design.md#5-发布内容与内部安装记录) 执行，并在实现中验证。不能因为 examples.json 合法就信任整个 .skillhub 目录。
+
+### 自动识别与失败处理
+
+| 输入 | 目标行为 |
+| --- | --- |
+| 指定路径的 JSON 符合案例协议 | 识别为当前技能版本的多条任务模板 |
+| 指定路径存在，但 JSON 无法解析或不符合案例协议 | 按普通技能文件原样保留，不启用案例功能；发布结果提供简短非阻断提示 |
+| 指定文件不存在，或合法协议明确没有案例 | 不显示空案例区，保留自定义使用 |
+| 其他位置的 JSON 或相似文件名 | 按普通文件处理，不猜测或全目录扫描识别案例 |
+| 文件违反通用路径、类型、大小或安全规则 | 沿用原有拒绝或安全处理，不得以“普通文件回退”为由放行 |
+| 文件读取发生 I/O 错误 | 与明确无案例区分；可提示重试，保留自定义入口，不绕过技能完整性核验 |
+
+协议识别失败不等于技能发布、安装或使用失败；但普通文件仍属于技能内容，不能静默忽略修改、删改或执行其中内容。JSON 中的模板只作为用户可编辑文本，不能作为权限、工具调用、路径或安装身份依据。
+
+协议、状态、接口投影、内部记录保护与旧消费者策略见 [案例实现设计](skill-examples-design.md)。首期采用 schemaVersion=1、defaultLocale 和按语言标签组织的 examples 对象数组映射；每条包含 id/title/prompt，prompt 支持 {{skill}} 占位符；规范 schema 与样例由该分册链接，本节不重复维护。
+
+### 分发和消费边界
+
+作者经现有技能包上传/发布链路提供文件。服务端识别结果必须绑定精确的来源、技能坐标与版本；如通过 API 展示案例，API 只是该版本文件的投影，不构成独立编辑或独立更新源。本期复用既有精确版本原始文件接口，不新增案例表或专用端点；预检识别摘要与本地 Remote 投影见 [案例实现设计](skill-examples-design.md)，开源实现与本地验证见 verification.md；SaaS 另行适配。
+
+DSH 的使用入口消费选定安装版本的固定文件，不能以市场最新版本模板替代已安装版本。用户级与项目级安装分别读取所选目录；不得跨来源、技能、版本或范围串用模板。案例存在不表示该安装在当前会话可调用，仍需执行既有只读使用核验。
+
+### CLI、Web 与 DSH 生命周期兼容
+
+固定案例的实现行为如下：
+
+- CLI 按目录发布、同步推送及 Web 文件夹打包须保留 `.skillhub/examples.json`；不得继续笼统排除整个 `.skillhub`，也不得误带安装器内部 metadata.json。
+- 服务端文件清单、每文件哈希、下载包与本地校验必须一致地覆盖作者案例文件；案例协议不合法时也按普通发布文件保留和校验。
+- 共享指纹与安全目录检查须识别该明确路径，并保留路径、普通文件、符号链接和所有权防护。不能整体忽略 .skillhub 内文件的修改。
+- 安装保留作者文件，升级按目标版本替换，卸载随技能清理；备份、回滚、恢复和套件生命周期遵守相同内容规则。
+- 安装后修改案例文件按本地内容修改处理，沿用现有保护，不增加静默覆盖或强制操作。案例不作为独立可变缓存写回。
+- 没有该文件的旧技能保持可用。旧版 CLI/插件与新目录规则的互操作须实测；不能承诺旧二进制自动兼容。若确有不兼容，应在实现前定义最低消费者版本或明确的阻止提示。
+
+### 验收要求
+
+1. 合法多案例、无案例、错误 JSON、错误结构和其他路径文件均按识别规则处理；普通文件回退不削弱安全检查。
+2. Web 与 CLI 上传/目录打包、手工 ZIP、服务端存储及下载、安装目录的文件路径与字节一致；内部安装记录不得由上传内容覆盖。
+3. 安装、同版本重试、同步、升级、卸载、恢复、回滚、套件及“使用此技能”均覆盖合法和不合法案例文件；本地修改继续受到保护。
+4. 多模板选择、自定义、草稿/附件保留、取消和上下文变更不自动发送，不执行文件中的指令。
+5. 不同来源、坐标、版本、用户/项目范围不串用；覆盖旧技能与实际旧版消费者兼容，记录支持边界。
+
+开源实现及生命周期验证结果见 verification.md 的“固定技能案例协议：开源实现验收”。SaaS 和生产部署不在本轮范围。
diff --git a/openspec/changes/add-dsh-native-plugin/verification.md b/openspec/changes/add-dsh-native-plugin/verification.md
index e9f920940..32e4b4182 100644
--- a/openspec/changes/add-dsh-native-plugin/verification.md
+++ b/openspec/changes/add-dsh-native-plugin/verification.md
@@ -153,3 +153,107 @@
 - 使用公开 tarball，通过官方安装器装入干净隔离 Profile；复用已安装的官方 DSH 程序，运行基线和插件生命周期探针均通过。该路径不等于重新从网络安装整套 DSH 依赖。
 - 现有 Linux 预览升级到公开 `0.3.0`，81 个交付文件逐字节核对；15 个历史对话归档及技能状态文件在升级和重启后保持一致。浏览器技能中心加载 3 张联调技能卡片，无页面脚本异常。
 - 本轮发布后未新增模型请求，不将先前候选的真实模型验收写为公开包的新模型验收；预览使用本地开源市场，不代表 SaaS 新契约已部署。后续发布将公开读取窗口扩大到 40 次、间隔 30 秒，保留严格完整性比对与不重复发布边界。
+
+
+## 使用此技能：开发候选验收
+
+本轮仅验证原生插件中的草稿衔接能力，没有发送消息、执行技能或调用模型；不代表真实模型效果或生产 Registry 验收。候选沿用包版本字段 `0.3.1`，但包含尚未发布的功能，不能与公开 npm `0.3.1` 混同。
+
+| 层级 | 结果 |
+| --- | --- |
+| 完整插件检查 | 固定 Bun 1.3.13 的 build、typecheck、lint、419 项测试及 10286 次断言通过。没有修改 CLI 共享核心、服务端或数据库。 |
+| 独立评审 | 修复请求状态复位、去重时草稿版本检查、末次查询后的运行状态检查；真实宿主发现的 Cordis 代理误判已用稳定服务身份修复，并补真实 Cordis Service 回归。最终无未修复的高置信静态问题。 |
+| 官方安装 | 同一冻结候选分别由两版官方 DSH 安装器安装，追加严格 peers 校验；安装后的包文件与候选逐字节核对通过。 |
+| 真宿主与浏览器 | Linux / Node 24.17.0，DSH 0.2.0-rc.2、0.2.1-rc.2，各完成 12 项检查：安装成功、已安装卡片、已安装详情、市场详情、工具安装回执、用户级安装后使用、重复使用去重；资源修改拒绝、切会话晚响应、核验期间编辑草稿、用户级真实文件及项目同名覆盖。 |
+| 草稿与副作用 | 各正向入口均保留已有文字、真实原生文件引用 chip 和可解码图片附件，使用 SKILL.md 实际名称并恢复输入焦点；没有消息提交或模型请求，使用动作不创建安装操作或修改技能文件。独立只读复验还逐字节确认技能目录、库存与操作日志前后不变。 |
+| 产物与清理 | 包中仅包含运行代码、类型、README 和许可证；测试脚本、截图、日志、任务记录、认证入口不进入 npm 包。过程材料保存在仓库外，公开 diff 只保留实现、规范和可复用行为测试。 |
+
+浏览器场景使用本地 HTTP Registry 与真实 ZIP。对话回执由真实工具安装结果组成，历史明确标记“非模型”。匿名 Web Host 的 `/open-in-app/icon/filemanager` 返回 404，属于宿主文件图标表现；已单独记录，未将其混同脚本异常或图片附件失败，其余 HTTP/console 异常和页面脚本异常为零。
+
+用户禁止直接调用、未知依赖、来源变化和历史版本变化等其他阻止分支由 Host/Client 行为测试覆盖；本轮没有把每个分支扩展为浏览器操作。未重新验证原生 Windows/macOS、桌面客户端、真实模型执行、SaaS 或生产环境。场景助手、套件、Git 提交/合并和 npm 发布不在本轮。
+
+
+## 固定技能案例协议：设计验证
+
+本轮仅完成 tasks.md §40.4 的实现契约，不修改运行时代码。新增固定文件 schema、多案例/空集合样例和跨端实现设计；没有引入数据库、专用案例接口、Web编辑器或外置缓存。
+
+- JSON Schema Draft 2020-12 自身校验、有效/无效与边界样例、Python/ECMAScript 空白码点一致性及文档链接合计 27 项检查通过；包含未知版本/字段、空白/重复、20/21条、4000/4001码点、UTF-8/BOM及文件体积规则。
+- OpenSpec strict 与 git diff --check 通过；Trellis implement/check 上下文 manifest 的 7 个条目各自验证通过。
+- 独立设计检查发现并修正旧 CLI 删除/强制覆盖阻止的过度承诺，以及跨语言 \S 空白定义差异。
+- 已下载正式 npm 0.3.1 的内置核心静态审计确认其不支持新目录内容；不是运行旧包的真实兼容验收。新旧消费者矩阵、CLI/Web/服务端生命周期、DSH多案例UI均未实现或运行，本轮未调用模型、提交、部署或发布。
+
+原始研究、校验报告及后续执行上下文保存在本地任务与仓库外报告中；本节只保留可评审的验证摘要，不将协议样例校验等同产品验收。
+
+### 多语言协议补充
+
+单语言草案已由多语言映射替代：schemaVersion=1、defaultLocale、examples语言集合。更新后的样例、协议边界与语言回退共23项设计校验通过，OpenSpec strict和diff check通过。此前27项是单语言草案的历史设计验证，不代表当前多语言实现验收；本次23项同样仅为协议参考校验，生产parser/界面尚未实现。复核当前Host类型、Use控制器及共享CLI代码，未发现本功能案例解析/选择实现，tasks40.5–40.7保持未完成。
+
+### 结构化案例与技能占位符补充
+
+字符串条目草案已替换为多语言 id/title/prompt 对象。schema、有效/空样例与字段/重复ID/语言/长度边界和字面占位替换参考断言共21项通过；OpenSpec严格验证与diff检查通过。此为协议文档验证，字面替换断言不是生产实现测试，尚未实现案例parser、选择UI或生命周期兼容。此前单语言27项及多语言字符串23项属于历史草案验证，不代表当前功能验收。
+
+### 执行范围与SaaS增量交接
+
+新增正式执行方案、P0–P5范围与验收矩阵及可独立交付的SaaS案例适配Prompt。只修改规划文档，未改功能代码或SaaS仓库、未部署。独立方案review发现预检统计规则不明确，已统一为全部语言条目数并区分包预检与DSH所选语言状态，复核关闭。文档链接/结构与预检统计参考断言共52项通过，OpenSpec严格校验和diff检查通过；这些不是产品或SaaS验收。SaaS实际代码与测试环境仍待其Agent核对。
+
+
+## 固定技能案例协议：开源实现验收
+
+本节替代前述设计阶段对“尚未实现”的状态描述。完成范围为固定 `.skillhub/examples.json`、共享核心/CLI、开源 Java/Web 和 DSH 选择案例；不涉及 SaaS 代码或部署。案例原始字节随版本保存并参与指纹，内部 metadata 不作为作者内容；无效案例保留为普通文件并给出非阻断提示。
+
+| 验证层 | 实际结果 |
+| --- | --- |
+| CLI/共享核心 | 完整 735 项测试、3171 次断言通过；后续预检修复的相关四文件 87 项测试、362 次断言通过。lint、typecheck、build、Node 产物 smoke 通过。完整测试使用 30 秒 runner 超时以避免并行负载下既有子进程用例超时，未削弱断言或崩溃恢复时限。 |
+| 开源后端 | `make test-backend-app` 全部 2671 项实际执行测试通过，零失败；另有 30 项既有条件跳过（S3 2、GitHub HTTP 互操作 26、Go 归档 1、Redis Cluster 1）。新增案例测试全部执行；最终打包及 JRE 21 实际启动通过。 |
+| Web | 完整 255 文件、1160 项测试通过，lint、typecheck、build 通过。实际浏览器对最终后端上传有效、无效、无案例 ZIP，三种提示正确，无页面脚本异常。未新增案例编辑器。 |
+| DSH | build、typecheck、lint、435 项测试和 10366 次断言通过。原有引用压力测试在无并行负载下按原超时通过，未调整时限。 |
+| 实际后端生命周期 | 隔离实例通过现有发布接口发布 1.0.0、1.1.0；匿名精确版本 resolve、原始文件读取、下载 ZIP 的案例字节和聚合 fingerprint 核验通过；共享核心真实安装、升级及 CLI 删除通过。另有 5 项真实 HTTP 预检检查通过，包括内部 metadata 与大小写歧义路径拒绝。管理员自动发布未用于证明安全扫描质量。 |
+| 新旧消费者 | 实际公开 npm 0.3.1 内置核心与候选核心分别安装旧格式包通过；新核心安装新案例包通过；旧核心对新包因指纹不一致拒绝且未留下目标或库存。共享新安装的原生卸载预检：旧核心阻止、新核心允许。共 7 项实测通过，不能据此声称旧 CLI 删除/强制覆盖也有相同保护。 |
+| 双 DSH 真宿主 | 同一候选分别经官方安装器安装到 0.2.0-rc.2、0.2.1-rc.2，严格 peers 与包字节核验通过；每版 11 项主流程浏览器检查通过：实际项目安装后的案例选择、案例字节/指纹、取消、已安装卡片、自定义任务、两种详情入口、文件与库存不变、修改案例拒绝、真实工具安装回执、末次核验期间草稿编辑保护。每版另通过 1 项用户级安装案例选择检查，保留草稿与附件并核对用户目录中的案例指纹。 |
+| 草稿与副作用 | 保留已有文字、原生文件引用和可解码图片，使用实际 SKILL.md name 替换占位符并恢复焦点；零消息发送、零模型调用。浏览器按实际宿主英文 locale 选择英文案例；中文多案例、语言回退/切换与显式空集合由行为测试覆盖。 |
+| 独立评审 | CLI 预检缺失、SKILL.md 提升路径一致性和 stored ZIP 长度边界问题均修复并补测，静态评审无剩余已报告缺陷。 |
+
+实际浏览器仍记录宿主 `/open-in-app/icon/filemanager` 的既有 404，已从其余网络/脚本异常中单独区分。没有把工具组成的“非模型”回执称为真实模型对话。原生 Windows/macOS、桌面客户端、SaaS、生产、模型执行与 npm 发布均未在本轮验证。历史版本不回算指纹、不重写包；历史上被旧目录规则忽略的作者文件，如发现，需要单独迁移评估。
+
+所有脚本、日志、截图、隔离配置与候选包保存在仓库外本地报告目录 `dsh-examples-20261022/`；可观察入口为 `REPORT.md`、`core-compatibility-live.json`、`backend-http-preflight-final.json`、`live-registry.json`、`web-browser-preflight.json` 与 `evidence/{old,new}/result.json`。这些是当前未提交工作分支的验收证据，不代表 main、正式 npm 或 SaaS 已具备本功能。
+
+
+## 原生新对话与输入框案例交互
+
+技能中心的已安装卡片、两类详情和安装成功入口现在创建同工作区新对话；对话安装回执保持当前会话。案例由常驻控制器在官方 `conversation.input.dock` 展示，不再依赖原卡片弹窗。确认前后保留安装身份、版本/范围、宿主语种、摘要与原生草稿比较，未新增 HTTP 或模型工具。
+
+| 验证 | 本轮结果 |
+| --- | --- |
+| 完整插件检查 | 最终 `bun run check` 的 build、typecheck、lint、471 项测试及 11289 次断言通过，78 个测试文件，未修改既有压力预算。 |
+| 独立评审 | 官方双RC API、导航/retain/opaque key重绑定与清理边界复核通过；最终草稿保护相关75项测试/306次断言、模块/包基线19项测试、组件呈现2项测试通过。组件渲染测试不作为实际布局证明。 |
+| 最终双RC候选 | 同一未发布候选经两版官方安装器安装、严格peer校验，并将安装内容与候选85个文件逐字节核对；本次新增的两个官方工作区Client模块纳入同版兼容基线。 |
+| 真实浏览器 | Linux两版Host各完成9项：项目安装成功后新对话与第二案例、原文字/引用/可解码PNG保留、已安装卡片双击去重及取消、已安装详情自定义、市场详情、对话回执不新建且保留附件、最终核验期间编辑保护、导航撤销、用户级安装成功后新对话。每次创建均核对原工作区；零消息发送、模型调用和页面脚本异常。 |
+| 真实布局 | 桌面1440×1000，两张案例卡片及自定义/确认按钮首屏可见，通过原生祖先overflow裁切交集与实际点击点命中验证，且已目视核对两版截图。案例列表独立滚动，不收缩头尾操作。 |
+| 规范 | OpenSpec strict、Trellis上下文manifest和diff check通过；tasks41和正式交互、生命周期、验收同步。 |
+
+真实验收先发现旧会话最后引用释放时，宿主销毁输入shell并回收附件，旧RC语义引用也丢失。修复采用官方retain保留原生shell，返回mainView接管、草稿清空/发送完成、会话移除或作用域失效、插件卸载时清理；最多8份非空旧草稿，达到上限拒绝新建，不驱逐旧内容。原丢失记录与修复后切回原会话实测分开保存；此前模拟测试不能替代这一边界验证。跨刷新、关闭页面和插件停用的附件持久化仍由宿主决定。
+
+另一个实际目视问题为Dock中flex收缩导致案例区仅露出顶部；最终仅补插件自身布局约束，与官方Dock组件一致，未改宿主全局样式。无模型配置的隔离Host在新空会话弹出原生引导，测试选择“稍后配置/关闭”；未填写凭证或调用模型。重复使用旧测试根时，外源目录保护曾正确拒绝用户级写入，最终改用干净隔离根完成同包验收，没有绕过保护或删除原来源数据。
+
+证据保存于仓库外本地报告 `dsh-composer-cases-20261022/REPORT.md`，最终原始浏览器结果在 `final-preview/evidence/{old,new}/result.json`，截图同目录。旧候选、失败和中间阶段记录不标为最终通过。CLI/Java/Web在本轮未改动，不将前轮检查冒充此次重跑。SaaS、真实模型执行、原生Windows/macOS、桌面及新增交互的移动端验收均未执行；未提交、推送、部署或发布npm。
+
+
+### 多案例布局压力补验
+
+用户提出“案例特别多”的人工评审问题后，真实DSH布局压力测试发现原grid行高被压缩、长标题重叠及横向溢出，已最小修复：复用官方Dock宽度变量，最多两列、窄面板单列，grid自然行高且独立滚动，标题/预览最多两行并允许长词换行，头尾操作固定。此改动仅涉及插件样式与呈现回归，无协议或依赖变更。
+
+- 最终完整插件check：build/typecheck/lint、472项测试、11294次断言通过，独立样式补审及3项组件呈现测试通过；呈现测试不替代布局验收。
+- 同一新增候选在两支持RC经官方严格安装，并逐字节核对85个包文件；两版真实原生slot各验证7种视口：1440×1000、1280×720、1024×600、760×600、1440×500、560×700、390×720。20条长案例无卡片交叠、列表/页面横向溢出，列表内部滚动、末项可选，操作按钮的可见交集和点击命中通过，已目视桌面及窄屏截图。
+- 旧RC采用明确的RPC布局fixture；新RC除相同fixture外，进一步安装真实20案例包、核对作者原字节和metadata文件哈希，并重新跑7视口。样例35950字节，通过生产解析器，含80码点标题及4000码点正文的边界，未超64KiB文件上限。
+- 新RC实际选择第20项并确认：完整500码点prompt带入原生输入框，视觉两行截断不改变原始模板。无消息提交或模型请求。该增量不冒充20案例的升级/卸载/全部平台生命周期验收；底层生命周期仍由前轮独立证据承担。
+
+原先33217预览保持运行，新增20案例人工演示使用独立实例，实际入口记录在仓库外 `dsh-composer-cases-20261022/MANY-CASES.md`。原始测量/截图在 `many-cases-evidence/{old,new}/`，实际包检查和末项填入分别为 `many-cases-real-install.json` 与 `many-case-use-evidence/new/result.json`。窄视口检查只证明案例组件布局，不扩大为整个DSH手机/桌面平台认证。原生空白首载曾使一次脚本未进入业务，重新打开同一有效入口完整通过，保留失败记录，不声称修复宿主启动问题。未提交、发布或修改SaaS。
+
+
+### 案例填入首行空白修复
+
+人工预览发现空输入框填入模板时首行空白，原因为插件无条件在模板前后增加换行。现改为按原生detect投影判断插入边界：空输入不添加首尾换行，已有换行不重复添加，作者原始换行保留，原生捕获跨度与CAS不变。
+
+- 完整插件check的build/typecheck/lint和486项测试、11344次断言通过；独立增量评审、60项测试及类型/静态检查通过。
+- 同一未发布候选在两支持RC经官方严格安装并核对85个文件；每版实际浏览器通过5项：空草稿案例、空草稿自定义、已有换行及中文/emoji、原生引用chip和可解码PNG保留、技能中心新建空对话后填入。直接比较完整正文，不使用trim掩盖首尾空白；无RPC模拟、消息发送或模型调用，页面脚本异常为零。
+- 新人工预览使用20个简短有效案例，原压力样例及旧预览保留。已存在草稿不自动改写。证据位于仓库外 `dsh-leading-line-20261022/REPORT.md` 与 `evidence/{old,new}/`。本增量不涉及SaaS、CLI/Java/Web、原生Windows/macOS、模型执行或发布。
diff --git a/plugins/dsh/README.en.md b/plugins/dsh/README.en.md
index 79f99ee78..1598608cf 100644
--- a/plugins/dsh/README.en.md
+++ b/plugins/dsh/README.en.md
@@ -10,6 +10,13 @@ Version `0.2.1` defaults to `https://skill.xfyun.cn` when `registryUrl` is omitt
 
 Version `0.3.1` fixes compatibility with both enumerated DSH RCs, uses the independent `dsh-v0.3.1` release tag and retains the marketplace interactions and version management from `0.3.0`. Until npm publication and public-package verification finish, validate this version using its built tarball.
 
+## Use an installed skill (in development)
+
+Choose “使用此技能” on an installed card, matching installed-version detail or completed installation result. Catalog entries open a new conversation in the same workspace; conversation entries keep their current session. After installation verification, examples appear above the native composer. Confirm an example or choose a custom task to insert an editable invocation. The original conversation is preserved, and in-conversation use retains its existing text, references and attachments. Complete the task and send it yourself; this action does not submit messages, call a model or install files.
+
+An active session is required. Shadowed skills, modified files, disabled user invocation or changed context are reported without modifying the draft. Historical receipts are not proof of current installation. This feature is under development and is not part of published `0.3.1`.
+
+
 ## Requirements and validation scope
 
 | Component | Requirement or scope |
diff --git a/plugins/dsh/README.md b/plugins/dsh/README.md
index d799e9124..a95ef8f01 100644
--- a/plugins/dsh/README.md
+++ b/plugins/dsh/README.md
@@ -10,6 +10,13 @@ SkillHub 的 DSH 原生插件。在 DSH 侧栏打开 **技能中心**，匿名
 
 `0.3.1` 为 DSH 双 RC 兼容修复版本，使用独立发布标签 `dsh-v0.3.1`，保留 `0.3.0` 的市场交互与版本管理能力。npm 发布及公开包验收完成前，使用本版本构建的 tarball 验证。
 
+## 使用已安装技能（开发中）
+
+在已安装卡片、已安装版本详情或安装成功结果点击“使用此技能”。技能中心入口在同一工作区新建对话，对话内入口保留当前会话。核验所选安装后，案例显示在原生输入框上方；确认案例或自定义任务后，带入可编辑的技能调用。原会话草稿不会被覆盖，对话内操作保留已有文字、引用和附件。补充任务和材料后自行发送；点击使用不会自动发送、调用模型或安装文件。
+
+需要当前活动会话。被项目同名技能覆盖、本地文件变更、禁止用户调用或会话/来源变化时会提示原因；历史回执不能代替当前安装状态。此功能正在开发，尚不属于已发布的 `0.3.1` 包。
+
+
 ## 环境与验证范围
 
 | 项目 | 要求或范围 |
diff --git a/plugins/dsh/bun.lock b/plugins/dsh/bun.lock
index 87d5028a7..8484fe9ec 100644
--- a/plugins/dsh/bun.lock
+++ b/plugins/dsh/bun.lock
@@ -25,7 +25,9 @@
         "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
         "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.2",
         "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.2",
+        "@deepseek-ai/dsh-api-workspace-controller": "0.2.1-rc.2",
         "@deepseek-ai/dsh-app-boot": "0.2.1-rc.2",
+        "@deepseek-ai/dsh-client-locale": "0.2.1-rc.2",
         "@deepseek-ai/dsh-client-ui-chat": "0.2.1-rc.2",
         "@deepseek-ai/dsh-client-ui-conversation": "0.2.1-rc.2",
         "@deepseek-ai/dsh-client-ui-layout": "0.2.1-rc.2",
@@ -36,6 +38,7 @@
         "@deepseek-ai/dsh-client-ui-sidebar": "0.2.1-rc.2",
         "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.2",
         "@deepseek-ai/dsh-client-ui-tool": "0.2.1-rc.2",
+        "@deepseek-ai/dsh-client-ui-workspace": "0.2.1-rc.2",
         "@deepseek-ai/dsh-fs": "0.2.1-rc.2",
         "@deepseek-ai/dsh-home-paths": "0.2.1-rc.2",
         "@deepseek-ai/dsh-sandbox": "0.2.1-rc.2",
@@ -102,6 +105,8 @@
 
     "@deepseek-ai/dsh-api-session-controller": ["@deepseek-ai/dsh-api-session-controller@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-api-session-controller/-/dsh-api-session-controller-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/dsh-brand": "0.2.1-rc.2", "@deepseek-ai/dsh-deque": "0.2.1-rc.2", "@deepseek-ai/schemastery": "~3.18.5", "mime-types": "^3.0.2", "zod": "4.4.3" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5", "@deepseek-ai/dsh-agent": "0.2.1-rc.2", "@deepseek-ai/dsh-agent-default-model": "0.2.1-rc.2", "@deepseek-ai/dsh-agent-preset-registry": "0.2.1-rc.2", "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.2", "@deepseek-ai/dsh-attachment": "0.2.1-rc.2", "@deepseek-ai/dsh-client-connection": "0.2.1-rc.2", "@deepseek-ai/dsh-client-file-upload": "0.2.1-rc.2", "@deepseek-ai/dsh-commands": "0.2.1-rc.2", "@deepseek-ai/dsh-credentials": "0.2.1-rc.2", "@deepseek-ai/dsh-file-reference": "0.2.1-rc.2", "@deepseek-ai/dsh-fs": "0.2.1-rc.2", "@deepseek-ai/dsh-llm": "0.2.1-rc.2", "@deepseek-ai/dsh-native-command": "0.2.1-rc.2", "@deepseek-ai/dsh-scope": "0.2.1-rc.2", "@deepseek-ai/dsh-session": "0.2.1-rc.2", "@deepseek-ai/dsh-session-persistence": "0.2.1-rc.2", "@deepseek-ai/dsh-session-projection": "0.2.1-rc.2", "@deepseek-ai/dsh-session-projection-cache": "0.2.1-rc.2", "@deepseek-ai/dsh-session-query": "0.2.1-rc.2", "@deepseek-ai/dsh-session-title": "0.2.1-rc.2", "@deepseek-ai/dsh-settings": "0.2.1-rc.2", "@deepseek-ai/dsh-skill": "0.2.1-rc.2", "@deepseek-ai/dsh-subagent": "0.2.1-rc.2", "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2", "@deepseek-ai/dsh-typert-registry": "0.2.1-rc.2", "@deepseek-ai/dsh-util-time": "0.2.1-rc.2", "@deepseek-ai/dsh-util-values": "0.2.1-rc.2", "@deepseek-ai/dsh-util-workspace-path": "0.2.1-rc.2", "@deepseek-ai/dsh-working-directory": "0.2.1-rc.2", "@deepseek-ai/dsh-workspace": "0.2.1-rc.2" }, "optionalPeers": ["@deepseek-ai/dsh-session-persistence", "@deepseek-ai/dsh-session-projection-cache", "@deepseek-ai/dsh-settings"] }, "sha512-AvYB5Seza/91BAKzataRn/5UYUqxNHU6W9ryH0JL0gslWkcURbGFFhvkRe9SXNo6DO0Jlv66NbBHME2t0XRPKA=="],
 
+    "@deepseek-ai/dsh-api-workspace-controller": ["@deepseek-ai/dsh-api-workspace-controller@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-api-workspace-controller/-/dsh-api-workspace-controller-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/dsh-deque": "0.2.1-rc.2", "@deepseek-ai/dsh-native-command": "0.2.1-rc.2", "@deepseek-ai/schemastery": "~3.18.5", "zod": "4.4.3" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5", "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.2", "@deepseek-ai/dsh-client-connection": "0.2.1-rc.2", "@deepseek-ai/dsh-host-directory-picker": "0.2.1-rc.2", "@deepseek-ai/dsh-session": "0.2.1-rc.2", "@deepseek-ai/dsh-storage-domain": "0.2.1-rc.2", "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2", "@deepseek-ai/dsh-workspace": "0.2.1-rc.2" } }, "sha512-v1ZxPEY5suajD8dqCE7TjYzPllK/JS8LT1aCKGksiBqvgpzruG5YpPzw9JnY3Z3yJSrgwUYHlKpuHReG3Kbfvw=="],
+
     "@deepseek-ai/dsh-app-boot": ["@deepseek-ai/dsh-app-boot@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-app-boot/-/dsh-app-boot-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/dsh-atomic-write": "0.2.1-rc.2", "@deepseek-ai/dsh-package-manifest": "0.2.1-rc.2", "@eslint-community/regexpp": "^4.12.2", "ajv": "^8.20.0", "js-yaml": "^4.3.2", "node-addon-require-builtin": "^0.1.9", "resolve.exports": "^2.0.3", "semver": "^7.8.5" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5", "@deepseek-ai/cordis-plugin-group": "~1.0.5", "@deepseek-ai/cordis-plugin-include": "~1.0.10", "@deepseek-ai/cordis-plugin-loader": "~1.0.6", "@deepseek-ai/dsh-home-paths": "0.2.1-rc.2", "@deepseek-ai/dsh-launch-environment": "0.2.1-rc.2" } }, "sha512-kMS4f6AGOPjGsTz3UXWihl5l2Vnm8y9dIayXIF9EafV6F73vgGR+uoBAq4p8qxSq72QfUSGx2yuDP2Hjw4ktlg=="],
 
     "@deepseek-ai/dsh-atomic-write": ["@deepseek-ai/dsh-atomic-write@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-atomic-write/-/dsh-atomic-write-0.2.1-rc.2.tgz", { "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-yCvLoL55Uoaxsi06I8hOcPgvMOhIt7w8vE/FLe3iGzvGq5OfrqkanAmt++apq069Jo6R/fP552XOhBlW8S3utg=="],
@@ -116,6 +121,8 @@
 
     "@deepseek-ai/dsh-client-file-upload": ["@deepseek-ai/dsh-client-file-upload@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-client-file-upload/-/dsh-client-file-upload-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/dsh-brand": "0.2.1-rc.2", "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2", "zod": "4.4.3" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-gLrn7EIxv59e/IBcxOv3x/1AMzkoBdjWAIAGnMLQOnPLl1HLddF1X1gLUAJ73XqhyPp4ePWmz/nReNOluTDN9A=="],
 
+    "@deepseek-ai/dsh-client-locale": ["@deepseek-ai/dsh-client-locale@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-client-locale/-/dsh-client-locale-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/schemastery": "~3.18.5" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-TeNrG6Gpj83AZdTJblHixtBnPqu6++8XLv96r0bwRrGBD28rqysUU+xvf009YVnBlz0c8g8sdhNZK+WAfJPQ2Q=="],
+
     "@deepseek-ai/dsh-client-ui-chat": ["@deepseek-ai/dsh-client-ui-chat@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-client-ui-chat/-/dsh-client-ui-chat-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/schemastery": "~3.18.5" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-ZDT17V3+LoavO3CJZ5alZf6edoh3+Qnllb3Y2DKOSmJYfpbPvR45uWl2DYxcnU4EAW2XvT8/k6KkbklFR1ZV8Q=="],
 
     "@deepseek-ai/dsh-client-ui-conversation": ["@deepseek-ai/dsh-client-ui-conversation@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-client-ui-conversation/-/dsh-client-ui-conversation-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/schemastery": "~3.18.5" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-ER7x0so7Owcfgs5ok8WTv3PYcuHUbwUbv9IV2kP6PbxwB+SxCAXtSRRCKlnkTt3WFd+KbwbluVfWBByLJEl9hQ=="],
@@ -136,6 +143,8 @@
 
     "@deepseek-ai/dsh-client-ui-tool": ["@deepseek-ai/dsh-client-ui-tool@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-client-ui-tool/-/dsh-client-ui-tool-0.2.1-rc.2.tgz", { "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-661V8pHw7gBunPXKdMnDrabubtxbOC6P2Dd0DOjWqxmBKUAgLDtDcg0YRn8kRomK7dauJnCx7e6H1oy2DM+fRg=="],
 
+    "@deepseek-ai/dsh-client-ui-workspace": ["@deepseek-ai/dsh-client-ui-workspace@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-client-ui-workspace/-/dsh-client-ui-workspace-0.2.1-rc.2.tgz", { "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-v3ov7wH9/0npaqpACSCAnVIgc5ho8NofeU2k06xGFNmZwxM3//KPeKzHd17/rzl32agw6G2NV2+FbxMx6l3xJw=="],
+
     "@deepseek-ai/dsh-commands": ["@deepseek-ai/dsh-commands@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-commands/-/dsh-commands-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/dsh-util-crypto": "0.2.1-rc.2", "zod": "4.4.3" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5", "@deepseek-ai/dsh-agent": "0.2.1-rc.2", "@deepseek-ai/dsh-attachment": "0.2.1-rc.2", "@deepseek-ai/dsh-brand": "0.2.1-rc.2", "@deepseek-ai/dsh-llm": "0.2.1-rc.2", "@deepseek-ai/dsh-scope": "0.2.1-rc.2", "@deepseek-ai/dsh-session": "0.2.1-rc.2", "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2" } }, "sha512-wLeEVXHuTULr0WYVHcCf1djQTEql2oxNSkbckbyfzw/r381ki1y39CPHw3Xtt6D9eXKulxTzgZzDPnHdh29QkQ=="],
 
     "@deepseek-ai/dsh-compaction": ["@deepseek-ai/dsh-compaction@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-compaction/-/dsh-compaction-0.2.1-rc.2.tgz", { "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5", "@deepseek-ai/dsh-brand": "0.2.1-rc.2", "@deepseek-ai/dsh-commands": "0.2.1-rc.2", "@deepseek-ai/dsh-llm": "0.2.1-rc.2", "@deepseek-ai/dsh-session": "0.2.1-rc.2" } }, "sha512-rag79zVeoMWXqKfIB0uRyx/1RRXSvucXJVUMOxM+iJxBgHObCn61RTLiFrI8M5DabHnmy+ugCGAeL5HwD/JPVw=="],
@@ -154,6 +163,8 @@
 
     "@deepseek-ai/dsh-home-paths": ["@deepseek-ai/dsh-home-paths@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-home-paths/-/dsh-home-paths-0.2.1-rc.2.tgz", { "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-+byrn2eS9XaFt6pl1yZXIgkm7GbbzTwzX3Eo19Ew9P1xzzucw/j2HSmdFo221/GK+5PH7ct1ldeT+fAxAJ1e9w=="],
 
+    "@deepseek-ai/dsh-host-directory-picker": ["@deepseek-ai/dsh-host-directory-picker@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-host-directory-picker/-/dsh-host-directory-picker-0.2.1-rc.2.tgz", { "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-CXFXrq5wz77Hf66KFyyEoyDkDIMWyRDXhRUml033qm6Dg4+CnD7pXz3LdncmfXjYGQPT3HtloPU9RmH65JSmIQ=="],
+
     "@deepseek-ai/dsh-launch-environment": ["@deepseek-ai/dsh-launch-environment@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-launch-environment/-/dsh-launch-environment-0.2.1-rc.2.tgz", { "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-EXoLY+5i71V2uBrqa1Pk+eamwqc/6Di7N2BIvqs9GDZ09RFk6ohsqs/hObev2Z/ehWr6BYIS112c1qbf/P79Wg=="],
 
     "@deepseek-ai/dsh-llm": ["@deepseek-ai/dsh-llm@0.2.1-rc.2", "https://registry.npmmirror.com/@deepseek-ai/dsh-llm/-/dsh-llm-0.2.1-rc.2.tgz", { "dependencies": { "@deepseek-ai/dsh-brand": "0.2.1-rc.2", "@deepseek-ai/dsh-timeout": "0.2.1-rc.2", "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2", "@deepseek-ai/dsh-util-crypto": "0.2.1-rc.2", "@deepseek-ai/dsh-util-values": "0.2.1-rc.2", "@deepseek-ai/schemastery": "~3.18.5", "zod": "4.4.3" }, "peerDependencies": { "@deepseek-ai/cordis": "~4.0.5" } }, "sha512-3xfoMDHEpUJGcH2Lu+lNXUJYRBclYfBkdCG9Au02VzIjYAm9BrFmc/MNuaVTg0vwgvPpTsd6Fx1IeGtfmQFvlg=="],
@@ -608,8 +619,12 @@
 
     "@deepseek-ai/dsh-api-session-controller/@deepseek-ai/schemastery": ["@deepseek-ai/schemastery@3.18.5", "https://registry.npmmirror.com/@deepseek-ai/schemastery/-/schemastery-3.18.5.tgz", { "dependencies": { "@deepseek-ai/cosmokit": "~1.8.6", "@standard-schema/spec": "^1.1.0" } }, "sha512-Mnobvqf9rHsZYv4g5edj5ddxS1oF1kIdSlz0DunUgnY3LWG5F26MqvH3YOOsSaodCgyzJ16OMN9O99/s5Crtdw=="],
 
+    "@deepseek-ai/dsh-api-workspace-controller/@deepseek-ai/schemastery": ["@deepseek-ai/schemastery@3.18.5", "https://registry.npmmirror.com/@deepseek-ai/schemastery/-/schemastery-3.18.5.tgz", { "dependencies": { "@deepseek-ai/cosmokit": "~1.8.6", "@standard-schema/spec": "^1.1.0" } }, "sha512-Mnobvqf9rHsZYv4g5edj5ddxS1oF1kIdSlz0DunUgnY3LWG5F26MqvH3YOOsSaodCgyzJ16OMN9O99/s5Crtdw=="],
+
     "@deepseek-ai/dsh-client-connection/@deepseek-ai/schemastery": ["@deepseek-ai/schemastery@3.18.5", "https://registry.npmmirror.com/@deepseek-ai/schemastery/-/schemastery-3.18.5.tgz", { "dependencies": { "@deepseek-ai/cosmokit": "~1.8.6", "@standard-schema/spec": "^1.1.0" } }, "sha512-Mnobvqf9rHsZYv4g5edj5ddxS1oF1kIdSlz0DunUgnY3LWG5F26MqvH3YOOsSaodCgyzJ16OMN9O99/s5Crtdw=="],
 
+    "@deepseek-ai/dsh-client-locale/@deepseek-ai/schemastery": ["@deepseek-ai/schemastery@3.18.5", "https://registry.npmmirror.com/@deepseek-ai/schemastery/-/schemastery-3.18.5.tgz", { "dependencies": { "@deepseek-ai/cosmokit": "~1.8.6", "@standard-schema/spec": "^1.1.0" } }, "sha512-Mnobvqf9rHsZYv4g5edj5ddxS1oF1kIdSlz0DunUgnY3LWG5F26MqvH3YOOsSaodCgyzJ16OMN9O99/s5Crtdw=="],
+
     "@deepseek-ai/dsh-client-ui-chat/@deepseek-ai/schemastery": ["@deepseek-ai/schemastery@3.18.5", "https://registry.npmmirror.com/@deepseek-ai/schemastery/-/schemastery-3.18.5.tgz", { "dependencies": { "@deepseek-ai/cosmokit": "~1.8.6", "@standard-schema/spec": "^1.1.0" } }, "sha512-Mnobvqf9rHsZYv4g5edj5ddxS1oF1kIdSlz0DunUgnY3LWG5F26MqvH3YOOsSaodCgyzJ16OMN9O99/s5Crtdw=="],
 
     "@deepseek-ai/dsh-client-ui-conversation/@deepseek-ai/schemastery": ["@deepseek-ai/schemastery@3.18.5", "https://registry.npmmirror.com/@deepseek-ai/schemastery/-/schemastery-3.18.5.tgz", { "dependencies": { "@deepseek-ai/cosmokit": "~1.8.6", "@standard-schema/spec": "^1.1.0" } }, "sha512-Mnobvqf9rHsZYv4g5edj5ddxS1oF1kIdSlz0DunUgnY3LWG5F26MqvH3YOOsSaodCgyzJ16OMN9O99/s5Crtdw=="],
diff --git a/plugins/dsh/package.json b/plugins/dsh/package.json
index 3af9f3811..60da1ead7 100644
--- a/plugins/dsh/package.json
+++ b/plugins/dsh/package.json
@@ -63,7 +63,10 @@
         "@deepseek-ai/dsh-client-ui-plugin-manager",
         "@deepseek-ai/dsh-client-ui-tool",
         "@deepseek-ai/dsh-api-session-controller",
-        "@deepseek-ai/dsh-client-ui-session"
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-api-workspace-controller",
+        "@deepseek-ai/dsh-client-ui-workspace"
       ],
       "external": [
         "react",
@@ -102,7 +105,9 @@
     "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
     "@deepseek-ai/dsh-api-gateway": "0.2.1-rc.2",
     "@deepseek-ai/dsh-api-session-controller": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-workspace-controller": "0.2.1-rc.2",
     "@deepseek-ai/dsh-app-boot": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-ui-chat": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-ui-conversation": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-ui-layout": "0.2.1-rc.2",
@@ -113,6 +118,7 @@
     "@deepseek-ai/dsh-client-ui-sidebar": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-ui-slots": "0.2.1-rc.2",
     "@deepseek-ai/dsh-client-ui-tool": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-workspace": "0.2.1-rc.2",
     "@deepseek-ai/dsh-typert-generator": "0.2.0-rc.2",
     "@types/bun": "1.3.13",
     "@types/react": "18.3.1",
diff --git a/plugins/dsh/src/client/conversation-detail.tsx b/plugins/dsh/src/client/conversation-detail.tsx
index bd6087bbd..521529bf0 100644
--- a/plugins/dsh/src/client/conversation-detail.tsx
+++ b/plugins/dsh/src/client/conversation-detail.tsx
@@ -40,10 +40,10 @@ export function ConversationDetail({ reference, callId, originalSource, services
     style={{ margin: '0 0 0 auto', height: '100dvh', maxHeight: '100dvh', width: 'min(720px, 100vw)', maxWidth: '100vw', boxSizing: 'border-box', border: '1px solid #8885', padding: 24, overflowY: 'auto', font: 'inherit', lineHeight: 1.6, overflowWrap: 'anywhere' }}>
     <NativeControlStyles />
     <button autoFocus onClick={close} style={{ float: 'right', minHeight: 40 }} aria-label="关闭技能详情">关闭</button>
-    <QueryClientProvider client={services.client}><Content reference={reference} callId={callId} originalSource={originalSource} services={services} browseVersions={browseVersions} allowHistoricalReopen={allowHistoricalReopen} /></QueryClientProvider>
+    <QueryClientProvider client={services.client}><Content reference={reference} callId={callId} originalSource={originalSource} services={services} close={close} browseVersions={browseVersions} allowHistoricalReopen={allowHistoricalReopen} /></QueryClientProvider>
   </dialog>;
 }
-function Content({ reference, callId, originalSource, services, browseVersions, allowHistoricalReopen }: { reference: string; callId: string; originalSource: string; services: SearchViewServices; browseVersions?: () => void; allowHistoricalReopen: boolean }) {
+function Content({ reference, callId, originalSource, services, close, browseVersions, allowHistoricalReopen }: { reference: string; callId: string; originalSource: string; services: SearchViewServices; close(): void; browseVersions?: () => void; allowHistoricalReopen: boolean }) {
   const [reopening, setReopening] = useState(false);
   const query = useQuery({ queryKey: ['skillhub-conversation-detail', services.installation.sessionId, callId, reference, reopening], retry: false, gcTime: 0, refetchOnWindowFocus: false, refetchOnReconnect: false,
     queryFn: async ({ signal }) => {
@@ -64,7 +64,7 @@ function Content({ reference, callId, originalSource, services, browseVersions,
     {reopening && <p role="status">已重新核验详情。安装需要另行确认。</p>}
     <div className="astron-sh-detail-heading"><SkillAvatar name={detail.title} slug={detail.slug} namespace={detail.namespace} /><div><h2>{detail.title}</h2><p>@{detail.namespace}/{detail.slug} · {detail.version}</p></div></div><p>{detail.summary}</p><SkillMetrics item={detail} />
     <Acknowledgment key={detail.detailToken} reference={detail.selectionRef} token={detail.detailToken} acknowledge={services.acknowledgeDetail} />
-    <InstallControl detail={detail} sourceRevision={context.sourceRevision} services={services.installation} initiatedFrom="conversation" onContextStale={() => { void query.refetch(); }} />
+    <InstallControl detail={detail} sourceRevision={context.sourceRevision} services={services.installation} initiatedFrom="conversation" onClose={close} onContextStale={() => { void query.refetch(); }} />
     <article className="astron-sh-documentation"><DetailContent detail={detail} modes={context.detailTabs} remote={services.remote} retry={() => { void query.refetch(); }} cacheIdentity={JSON.stringify([services.installation.sessionId, context.sourceRevision, detail.namespace, detail.slug, detail.version])} onContextStale={() => { void query.refetch(); }} onSelectVersion={browseVersions} versionActionLabel="前往广场选择版本" /></article>
     <details className="astron-sh-conversation-provenance"><summary>来源信息</summary><p>原搜索来源：{originalSource}</p><p>当前详情来源：{context.registryUrl}</p></details>
   </>;
diff --git a/plugins/dsh/src/client/index.tsx b/plugins/dsh/src/client/index.tsx
index 4c944e1c0..3bd54b20e 100644
--- a/plugins/dsh/src/client/index.tsx
+++ b/plugins/dsh/src/client/index.tsx
@@ -1,3 +1,9 @@
+import { SkillDraftRetentions } from './use-skill-drafts.js';
+import { newSkillConversation } from './use-skill-navigation.js';
+import type {} from '@deepseek-ai/dsh-client-locale/client';
+import { captureSkillUse } from './use-skill-context.js';
+import { SkillUseBinding, SkillUseController, SkillUseFocus, SkillCaseChoices } from './use-skill.js';
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client';
 import { resolveReceiptContext, receiptSessionGuard, type ReceiptReads } from './receipt-context.js';
 import { UiAvailability, UiAvailabilityNotice } from './ui-availability.js';
 import type { Context } from '@deepseek-ai/cordis';
@@ -55,7 +61,39 @@ export async function apply(ctx: Context): Promise<() => Promise<void>> {
     const upgradeRequests = new UpgradeRequests(() => window.sessionStorage);
     const removalRequests = new RemovalRequests(() => window.sessionStorage);
     ctx.effect(() => () => { requests.dispose(); upgradeRequests.dispose(); removalRequests.dispose(); client.clear(); });
-    function installationFor(sessionId: string): InstallationServices {
+    const drafts = new SkillDraftRetentions(ctx);
+    ctx.effect(() => () => drafts.dispose());
+    const useSkills = new SkillUseController({
+      capture: (sessionId, actions) => captureSkillUse(ctx, sessionId, actions),
+      revision: async () => {
+        const response = await ctx.remote.skillhub.getContext();
+        if (!response.ok || !response.value.configured) throw new Error('来源不可用，请检查插件设置。');
+        return response.value.sourceRevision;
+      },
+      prepare: async (sessionId, revision, itemKey, signal) => {
+        const scope = ctx.sessions.scope(SessionId(sessionId));
+        if (!scope) throw new Error('当前会话已关闭。');
+        return withSessionRemote(scope, remote => remote.skillhub.prepareSkillUse(revision, itemKey, signal));
+      },
+      newConversation: (sessionId, revision, key, signal) => newSkillConversation(ctx, sessionId, revision, key, signal, async (target, source, abort) => {
+        const scope = ctx.sessions.scope(SessionId(target));
+        if (!scope) throw new Error('新对话尚未就绪，请重试。');
+        const response = await withSessionRemote(scope, remote => remote.skillhub.listInstalled(source, abort));
+        if (!response.ok) throw new Error('来源或安装记录已变化，请重试。');
+        return response.value;
+      }, drafts),
+      current: sessionId => (ctx.sessions.list.getSnapshot().byId[SessionId(sessionId)]?.retainedBy.mainView ?? 0) > 0,
+      subscribeContext: listener => ctx.sessions.list.subscribe(listener),
+      locale: () => ctx.get('locale')?.getLocale().active,
+      subscribeLocale: listener => ctx.on('locale/change', listener),
+      reveal: () => ctx.get('layout')?.selectPanel(null),
+    });
+    ctx.effect(() => () => useSkills.dispose());
+    ctx.slots.inject('conversation.input.left', () => ctx.slots.register({ name: 'conversation.input.left', id: 'skillhub-use-focus' },
+      props => <SkillUseBinding controller={useSkills} sessionId={props.sessionId} actions={props.inputActions}><SkillUseFocus controller={useSkills} sessionId={props.sessionId} /></SkillUseBinding>));
+    ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({ name: 'conversation.input.dock', id: 'skillhub-case-choices' },
+      props => <SkillUseBinding controller={useSkills} sessionId={props.sessionId} actions={props.inputActions}><SkillCaseChoices controller={useSkills} sessionId={props.sessionId} /></SkillUseBinding>));
+    function installationFor(sessionId: string, catalog = false): InstallationServices {
       const call = async <T,>(action: (remote: AgentContext['remote']) => Promise<T>): Promise<T> => {
         const scope = ctx.sessions.scope(SessionId(sessionId));
         if (!scope) throw new Error('当前会话已关闭，请重新打开会话。');
@@ -68,7 +106,7 @@ export async function apply(ctx: Context): Promise<() => Promise<void>> {
         operation: (id, host) => call(remote => remote.skillhub.getOperation(id, host)),
         recoverOperation: input => call(remote => remote.skillhub.recoverOperation(input)),
       };
-      return { sessionId, requests, upgrades, registryIdentity: async revision => { const source = await ctx.remote.skillhub.getContext(); if (!source.ok || !source.value.configured || source.value.sourceRevision !== revision) throw new Error('来源已变化，请重新读取详情。'); return source.value.registryUrl; },
+      return { sessionId, requests, upgrades, skillUse: catalog ? useSkills.catalogServices(sessionId) : useSkills.services(sessionId), registryIdentity: async revision => { const source = await ctx.remote.skillhub.getContext(); if (!source.ok || !source.value.configured || source.value.sourceRevision !== revision) throw new Error('来源已变化，请重新读取详情。'); return source.value.registryUrl; },
         checkVersionUpdate: (revision, itemKey, version, signal) => call(remote => remote.skillhub.checkVersionUpdate(revision, itemKey, version, signal)),
         manageInstalled: (sourceRevision, item) => {
         const layout = ctx.get('layout');
@@ -136,7 +174,7 @@ export async function apply(ctx: Context): Promise<() => Promise<void>> {
         layout.selectPanel(panelId);
       } } };
       },
-    }, props => <><UiAvailabilityNotice availability={availability} /><InstallToolView {...props} /></>));
+    }, props => <SkillUseBinding controller={useSkills} sessionId={props.sessionId} actions={props.inputActions}><UiAvailabilityNotice availability={availability} /><InstallToolView {...props} /></SkillUseBinding>));
     ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({
       name: 'tool.call.toolview', key: 'astron_skillhub_search',
       inject: sessionId => ({ services: {
@@ -173,7 +211,7 @@ export async function apply(ctx: Context): Promise<() => Promise<void>> {
           return withSessionRemote(scope, remote => remote.skillhub.acknowledgeConversationDetail(reference, token));
         },
       } }),
-    }, props => <><UiAvailabilityNotice availability={availability} /><SearchToolView {...props} /></>));
+    }, props => <SkillUseBinding controller={useSkills} sessionId={props.sessionId} actions={props.inputActions}><UiAvailabilityNotice availability={availability} /><SearchToolView {...props} /></SkillUseBinding>));
     ctx.inject(['layout'], (ctx) => {
       ctx.slots.inject('main', () => availability.enable('main'));
       ctx.slots.inject('sidebar.panellist', () => availability.enable('sidebar'));
@@ -181,8 +219,8 @@ export async function apply(ctx: Context): Promise<() => Promise<void>> {
         children: { 'skillhub.catalog': { kind: 'single', scope: 'session-maybe' } },
       }, ({ renderSlot }) => renderSlot('skillhub.catalog', {})));
       ctx.slots.inject('skillhub.catalog', () => ctx.slots.register({ name: 'skillhub.catalog',
-        inject: sessionId => ({ installation: sessionId ? installationFor(sessionId) : undefined,
-          installed: sessionId ? { sessionId, upgradeRequests, removalRequests, compatibility: () => ctx.remote.skillhub.getCompatibility(),
+        inject: sessionId => ({ installation: sessionId ? installationFor(sessionId, true) : undefined,
+          installed: sessionId ? { sessionId, skillUse: useSkills.catalogServices(sessionId), upgradeRequests, removalRequests, compatibility: () => ctx.remote.skillhub.getCompatibility(),
             operation: installationFor(sessionId).operation,
             recoverOperation: async input => {
               const scope = ctx.sessions.scope(SessionId(sessionId));
@@ -216,8 +254,8 @@ export async function apply(ctx: Context): Promise<() => Promise<void>> {
             if (!scope) throw new Error('当前会话已关闭，请重新打开会话。');
             return withSessionRemote(scope, remote => remote.skillhub.checkUpdate(revision, itemKey, signal));
           } } satisfies InstalledServices : undefined }),
-      }, ({ installation, installed }) => <CatalogPage remote={ctx.remote.skillhub} navigation={navigation} client={client}
-        installation={installation} installed={installed} availability={availability} onReturn={() => ctx.layout.selectPanel(null)} />));
+      }, ({ installation, installed, inputActions, sessionId }) => <SkillUseBinding controller={useSkills} sessionId={sessionId} actions={inputActions}><CatalogPage remote={ctx.remote.skillhub} navigation={navigation} client={client}
+        installation={installation} installed={installed} availability={availability} onReturn={() => ctx.layout.selectPanel(null)} /></SkillUseBinding>));
       ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({ name: 'sidebar.panellist', id: panelId, label: '技能中心', order: 10 }, () => <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><rect x="3" y="3" width="7" height="7" rx="1.6" /><rect x="3" y="14" width="7" height="7" rx="1.6" /><rect x="14" y="14" width="7" height="7" rx="1.6" /><path d="M17.5 2.5v8M13.5 6.5h8" /></svg>));
     });
   });
diff --git a/plugins/dsh/src/client/install-control.tsx b/plugins/dsh/src/client/install-control.tsx
index cfd2a4ed0..c851247ba 100644
--- a/plugins/dsh/src/client/install-control.tsx
+++ b/plugins/dsh/src/client/install-control.tsx
@@ -1,3 +1,4 @@
+import { UseSkillButton, type SkillUseServices } from './use-skill.js';
 import { UpgradeControl, type UpgradeServices } from './upgrade-control.js';
 import { InstallationProgressSummary, type InstallationProgressJob } from './installation-progress.js';
 import { isInventoryScopeVerified } from './installed-inventory.js';
@@ -12,6 +13,7 @@ import type { InstallationRequests } from './installation-requests.js';
 
 export interface InstallationServices extends CompatibilityServices {
   sessionId: string;
+  skillUse?: SkillUseServices;
   upgrades?: UpgradeServices;
   registryIdentity?(revision: string): Promise<string>;
   checkVersionUpdate?(revision: string, itemKey: string, version: string, signal: AbortSignal): Promise<RemoteResult<InstalledUpdateCheck>>;
@@ -127,6 +129,7 @@ export function InstallControl({ detail, sourceRevision, services, initiatedFrom
     {inventoryVerified && !current && (!attempt || completed) && <Button ref={trigger} variant="default" disabled={!writableHost.canWrite || !target || targets.isFetching}
       onClick={() => { if (!target) return; if (presentation === 'dialog') submit(completed); else setConfirmation({ key, targetToken: target.targetToken, reinstall: completed }); }}>
       {scope === 'project' ? '安装到此项目' : '安装到所有项目'}</Button>}
+    {inventoryVerified && current?.state === 'present' && current.version === detail.version && <UseSkillButton services={services.skillUse} revision={sourceRevision} itemKey={current.itemKey} onHandoff={onClose} onUsed={onClose} />}
     {current && completed && (result.warningCount > 0 || !!result.resultDetails?.warnings.length) && <p role="alert">安装有告警，请在已安装中核验。</p>}
     {submissionError && <p role="alert">{submissionError}</p>}
     {progressVisible && attempt && <InstallationProgressSummary attempt={attempt} operation={operation.data ?? attempt.operation} readFailed={operation.isError || operation.data === null}
diff --git a/plugins/dsh/src/client/install-dialog.tsx b/plugins/dsh/src/client/install-dialog.tsx
index 26c5c2589..ae1700539 100644
--- a/plugins/dsh/src/client/install-dialog.tsx
+++ b/plugins/dsh/src/client/install-dialog.tsx
@@ -38,6 +38,6 @@ function Content({ identity, load, services, initiatedFrom, close, expand, onMan
       <p className="astron-sh-install-close-note">关闭窗口不会取消已提交的安装。</p><Button autoFocus onClick={close}>关闭</Button></>
       : <InstallControl key={result.data.sourceRevision} detail={result.data.detail} sourceRevision={result.data.sourceRevision} services={services} initiatedFrom={initiatedFrom}
         presentation="dialog" onClose={close} onManage={onManage} onSubmitted={value => { setJob(value); expand(); }} onContextStale={() => { void result.refetch(); }} />}
-    </div>{job && <aside aria-label="安装进度"><InstallationProgressPanel job={job} services={services} /></aside>}
+    </div>{job && <aside aria-label="安装进度"><InstallationProgressPanel job={job} services={services} onUsed={close} /></aside>}
   </div>;
 }
diff --git a/plugins/dsh/src/client/install-tool-view.tsx b/plugins/dsh/src/client/install-tool-view.tsx
index c3b8530df..a44ef29a3 100644
--- a/plugins/dsh/src/client/install-tool-view.tsx
+++ b/plugins/dsh/src/client/install-tool-view.tsx
@@ -1,3 +1,4 @@
+import { exactInstalledSkill, UseSkillButton } from './use-skill.js';
 import { matchesReceipt, resolveReceiptContext, readReceiptInventory, type ReceiptReads } from './receipt-context.js';
 import { receiptInventoryIssue, receiptPresentation } from './install-receipt-presentation.js';
 import { Button } from './ui.js';
@@ -22,7 +23,7 @@ export interface InstallViewServices {
   client: QueryClient;
   receipt: ReceiptReads;
   confirmation?: SearchViewServices;
-  installation: Pick<InstallationServices, 'sessionId' | 'operation' | 'installed'>;
+  installation: Pick<InstallationServices, 'sessionId' | 'operation' | 'installed' | 'skillUse'>;
   openInstalled(result: InstallResult): Promise<void>;
 }
 
@@ -97,7 +98,11 @@ function InstallationResult({ result, services, receipt, openInstalled }: {
     <header className="astron-sh-conversation-identity"><SkillAvatar slug={result.slug} namespace={result.namespace} /><div><h4>{result.slug}</h4><p>@{result.namespace}/{result.slug}</p></div><span className="astron-sh-install-badge" data-tone={presentation.tone}>{presentation.label}</span></header>
     <p className="astron-sh-conversation-caption">v{result.version} · {result.targetLabel}</p>
     <p className="astron-sh-install-outcome" role={presentation.tone === 'warning' ? 'alert' : 'status'}>{presentation.message}</p>
-    <div className="astron-sh-install-actions"><Button variant="outline" disabled={query.isFetching || inventoryPending} onClick={() => {
+    <div className="astron-sh-install-actions">{canInspectCurrent && operation?.phase === 'completed' && !context.isError && context.data && <UseSkillButton services={services.skillUse} revision={context.data.sourceRevision} resolve={async signal => {
+      const inventory = await readReceiptInventory(receipt, result, context.data!, signal);
+      const scope = operation.targetLabel === '当前用户' ? 'user' : operation.targetLabel === '当前项目' ? 'project' : undefined;
+      return scope ? exactInstalledSkill(inventory, { ...result, scope })?.itemKey ?? '' : '';
+    }} />}<Button variant="outline" disabled={query.isFetching || inventoryPending} onClick={() => {
       // Settled operation reads invalidate the enabled current-inventory query in the shared hook.
       void query.refetch();
     }}>{query.isFetching || inventoryPending ? '核验中…' : '核验状态'}</Button>
diff --git a/plugins/dsh/src/client/installation-progress.tsx b/plugins/dsh/src/client/installation-progress.tsx
index 4a230b8ed..49d807b5c 100644
--- a/plugins/dsh/src/client/installation-progress.tsx
+++ b/plugins/dsh/src/client/installation-progress.tsx
@@ -1,3 +1,4 @@
+import { exactInstalledSkill, UseSkillButton } from './use-skill.js';
 import { useSyncExternalStore } from 'react';
 import type { NativeOperation } from '../host/types.js';
 import type { InstallationAttempt } from './installation-requests.js';
@@ -43,7 +44,7 @@ export function InstallationProgressSummary({ attempt, operation, readFailed, on
   </div>;
 }
 
-export function InstallationProgressPanel({ job, services }: { job: InstallationProgressJob; services: InstallationServices }) {
+export function InstallationProgressPanel({ job, services, onUsed }: { job: InstallationProgressJob; services: InstallationServices; onUsed?(): void }) {
   const attempt = useSyncExternalStore(services.requests.subscribe, () => services.requests.get(job.key), () => undefined);
   const operation = useInstallationOperation(services, job.hostInstanceId, attempt?.operationId ?? attempt?.operation?.operationId);
   async function check() {
@@ -55,9 +56,15 @@ export function InstallationProgressPanel({ job, services }: { job: Installation
     });
     else await operation.refetch();
   }
+  const completed = (operation.data ?? attempt?.operation)?.phase === 'completed' && !operation.isError;
   return <section className="astron-sh-install-progress-item" aria-label={`${job.title} 安装进度`}>
     <header><SkillAvatar name={job.title} namespace={job.namespace} slug={job.slug} /><div><strong>{job.title}</strong><p>v{job.version} · {job.scope === 'project' ? '仅此项目' : '所有项目'}</p></div>
     </header>
     <InstallationProgressSummary attempt={attempt} operation={operation.data ?? attempt?.operation} readFailed={operation.isError || operation.data === null} onCheck={() => { void check(); }} />
+    {completed && <UseSkillButton services={services.skillUse} revision={job.sourceRevision} resolve={async signal => {
+      const inventory = await services.installed(job.sourceRevision, signal);
+      if (!inventory.ok) throw new Error('无法核验当前安装，请在已安装中重试。');
+      return exactInstalledSkill(inventory.value, job)?.itemKey ?? '';
+    }} onHandoff={onUsed} onUsed={onUsed} />}
   </section>;
 }
diff --git a/plugins/dsh/src/client/installed-skills.tsx b/plugins/dsh/src/client/installed-skills.tsx
index 676a3f08a..8b837dd6d 100644
--- a/plugins/dsh/src/client/installed-skills.tsx
+++ b/plugins/dsh/src/client/installed-skills.tsx
@@ -1,3 +1,4 @@
+import { UseSkillButton, type SkillUseServices } from './use-skill.js';
 import { isInventoryScopeVerified } from './installed-inventory.js';
 import { CardSkeletons } from './loading-layout.js';
 import { useState, useRef, useLayoutEffect, useCallback } from 'react';
@@ -19,6 +20,7 @@ import { useInstalledUpdate } from './installed-update.js';
 
 export interface InstalledServices extends UpgradeServices, RemovalServices {
   sessionId: string;
+  skillUse?: SkillUseServices;
   list(sourceRevision: string, signal: AbortSignal): Promise<RemoteResult<InstalledSkillList>>;
   detail(sourceRevision: string, itemKey: string, signal: AbortSignal): Promise<RemoteResult<InstalledSkillDetail>>;
   checkUpdate(sourceRevision: string, itemKey: string, signal: AbortSignal): Promise<RemoteResult<InstalledUpdateCheck>>;
@@ -107,6 +109,7 @@ export function InstalledSkills({ services, sourceRevision, source, remote, mode
         : detail.data.content.state === 'local-only' ? <p role="status">远端详情暂时不可用，以上保留本地安装信息。未切换到其他版本。</p>
           : <DetailContent detail={detail.data.content.detail} modes={modes} remote={remote} retry={() => { void detail.refetch(); }} cacheIdentity={JSON.stringify([services.sessionId, sourceRevision, selected.namespace, selected.slug, detail.data.content.detail.version])} onContextStale={() => { void detail.refetch(); }} />}
     </article><aside className="astron-sh-detail-aside">
+    {!removed && !upgradedVersion && detailVerified && currentLocalState === 'present' && <UseSkillButton services={services.skillUse} revision={sourceRevision} itemKey={selected.itemKey} />}
     {!removed && !upgradedVersion && <Card className="astron-sh-version-update"><CardHeader><h3>版本与更新</h3></CardHeader><CardContent><div className="astron-sh-update-actions"><Button size="sm" variant="outline" disabled={detail.isFetching} onClick={() => { void detail.refetch(); }}>重新读取详情</Button>
     <Button size="sm" variant="outline" disabled={update.isFetching} onClick={() => { void update.refetch(); }}>检查更新</Button></div>
     {(update.isFetching || update.isError || update.data) && <div aria-live="polite">
@@ -181,6 +184,7 @@ function InstalledRow({ item, services, sourceRevision, navigate, buttonRef }: {
       {update.data && <details className="astron-sh-check-time"><summary>检查记录</summary><time className="skillhub-installed-coordinate" dateTime={update.data.checkedAt}>{update.isError || update.isFetching ? '上次成功检查' : '检查于'} {new Date(update.data.checkedAt).toLocaleString()}</time></details>}
     </div></CardContent>
     <CardFooter className="skillhub-installed-actions">
+      {item.state === 'present' && <UseSkillButton services={services.skillUse} revision={sourceRevision} itemKey={item.itemKey} />}
       <button ref={node => buttonRef('detail', node)} onClick={event => navigate('detail', event.currentTarget)}>查看已安装详情</button>
       <button disabled={update.isFetching} onClick={() => { void update.refetch(); }}>检查更新</button>
       {!update.isFetching && !update.isError && update.data?.state === 'upgradable'
diff --git a/plugins/dsh/src/client/native-control-styles.tsx b/plugins/dsh/src/client/native-control-styles.tsx
index 5d75d309a..329915d4a 100644
--- a/plugins/dsh/src/client/native-control-styles.tsx
+++ b/plugins/dsh/src/client/native-control-styles.tsx
@@ -17,6 +17,11 @@ export function NativeControlStyles() {
 .skillhub-controls .astron-sh-label-filter button { min-height:28px;height:28px;padding:4px 10px;font-size:12px;border-radius:999px;margin:0;border:1px solid transparent; }
 .skillhub-controls .astron-sh-label-filter button[aria-pressed="true"] { color:var(--astron-sh-accent);background:color-mix(in srgb,var(--astron-sh-accent) 10%,var(--astron-sh-bg));border-color:color-mix(in srgb,var(--astron-sh-accent) 30%,var(--astron-sh-border)); }
 .skillhub-controls .astron-sh-label-note { font-size:12px;line-height:18px;color:var(--astron-sh-muted); }
+.skillhub-controls .astron-sh-examples{display:grid;gap:8px;max-height:min(48vh,400px);overflow:auto;margin-top:16px}
+.skillhub-controls .astron-sh-example{display:grid;gap:5px;text-align:left;padding:12px;border:1px solid var(--astron-sh-border);border-radius:8px;color:var(--astron-sh-fg);background:var(--astron-sh-bg);cursor:pointer}
+.skillhub-controls .astron-sh-example[aria-pressed="true"]{border-color:var(--astron-sh-accent);background:color-mix(in srgb,var(--astron-sh-accent) 7%,var(--astron-sh-bg))}
+.skillhub-controls .astron-sh-example strong{font-size:13px;font-weight:600}.skillhub-controls .astron-sh-example span{font-size:12px;color:var(--astron-sh-muted);white-space:pre-wrap;overflow-wrap:anywhere;display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical;overflow:hidden}
+.skillhub-controls .astron-sh-example:focus-visible{outline:2px solid var(--astron-sh-accent);outline-offset:2px}
 .skillhub-controls :where(*, *::before, *::after){box-sizing:border-box}
 .skillhub-controls :where(button,input,select,textarea){font:inherit;color:inherit;max-width:100%}
 .skillhub-controls :where(button,input,select){border:1px solid var(--astron-sh-border);background:var(--astron-sh-bg);border-radius:7px;padding:8px 12px}
@@ -134,6 +139,10 @@ export function NativeControlStyles() {
 .skillhub-controls.astron-sh-detail-drawer{background:var(--astron-sh-bg);color:var(--astron-sh-fg)}
 @container(max-width:1000px){.skillhub-controls .astron-sh-card-grid{grid-template-columns:repeat(2,minmax(0,1fr))}.skillhub-controls .astron-sh-detail-layout{grid-template-columns:minmax(0,1fr) 260px;gap:24px}}
 @container(max-width:680px){.skillhub-controls .astron-sh-card-grid{grid-template-columns:1fr}.skillhub-controls .astron-sh-detail-layout{display:flex;flex-direction:column}.skillhub-controls .astron-sh-load-more{flex-wrap:wrap}.skillhub-controls .astron-sh-skill-heading h3{font-size:16px}}
+.skillhub-controls.astron-sh-case-panel{container:skillhub-cases / inline-size;width:calc(100% - var(--dsh-composer-side-clearance,16px) * 2 - var(--dsh-composer-dock-inset,8px) * 2);max-width:calc(var(--dsh-composer-card-max-width,800px) - var(--dsh-composer-dock-inset,8px) * 2);align-self:center;flex:none;display:flex;flex-direction:column;padding:14px;border:1px solid var(--astron-sh-border);border-radius:12px;background:var(--astron-sh-bg);margin:0 auto 10px;min-width:0;max-height:340px;overflow:hidden}
+.skillhub-controls.astron-sh-case-panel header{flex:none;display:flex;align-items:flex-start;justify-content:space-between;gap:12px}.skillhub-controls.astron-sh-case-panel header>div{min-width:0}.skillhub-controls.astron-sh-case-panel header strong{overflow-wrap:anywhere;display:block;font-size:13px}.skillhub-controls.astron-sh-case-panel header span{display:block;font-size:12px;color:var(--astron-sh-muted)}
+.skillhub-controls .astron-sh-case-grid{min-height:0;overflow:auto;display:grid;grid-template-columns:repeat(2,minmax(0,1fr));grid-auto-rows:max-content;align-content:start;gap:8px;margin:12px 0}.skillhub-controls .astron-sh-case{display:flex;flex-direction:column;align-items:stretch;overflow:hidden;white-space:normal;font:inherit;text-align:left;padding:10px 12px;min-width:0;background:var(--astron-sh-bg);color:var(--astron-sh-fg);border:1px solid var(--astron-sh-border);border-radius:8px;cursor:pointer}.skillhub-controls .astron-sh-case strong{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;overflow-wrap:anywhere;max-width:100%;font-size:13px;font-weight:600}.skillhub-controls .astron-sh-case span{max-width:100%;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;overflow-wrap:anywhere;font-size:12px;color:var(--astron-sh-muted);margin-top:4px}.skillhub-controls .astron-sh-case[aria-pressed=true]{border-color:var(--astron-sh-accent);background:color-mix(in srgb,var(--astron-sh-accent) 6%,var(--astron-sh-bg))}.skillhub-controls .astron-sh-case:focus-visible{outline:2px solid var(--astron-sh-accent);outline-offset:2px}.skillhub-controls.astron-sh-case-panel footer{flex:none;display:flex;justify-content:space-between;gap:8px}.skillhub-controls.astron-sh-case-panel p{font-size:12px;margin:10px 0}
+@container skillhub-cases (max-width:540px){.skillhub-controls .astron-sh-case-grid{grid-template-columns:minmax(0,1fr)}}
 @media(prefers-reduced-motion:reduce){.skillhub-controls :where(*){transition:none!important;animation:none!important}}
 
 .skillhub-controls .astron-sh-catalog-header{min-height:54px;margin-bottom:20px;border-bottom:1px solid var(--astron-sh-border);padding-bottom:12px;gap:12px}
@@ -191,6 +200,8 @@ export function NativeControlStyles() {
 .skillhub-controls .astron-sh-skeleton-install{padding:20px;display:grid;gap:20px}
 .skillhub-controls .astron-sh-skeleton-input{height:36px}
 @container(max-width:680px){.skillhub-controls .astron-sh-skeleton-document{min-height:280px}.skillhub-controls .astron-sh-skeleton-card{height:188px}}
+.skillhub-controls .astron-sh-use-skill{display:inline-flex;flex-direction:column;align-items:flex-start;gap:6px}
+.skillhub-controls .astron-sh-use-skill>[role=alert]{font-size:12px;line-height:1.5;color:var(--astron-sh-muted)}
 @media(prefers-reduced-motion:reduce){.skillhub-controls .astron-sh-skeleton{animation:none}}
 `}</style>;
 }
diff --git a/plugins/dsh/src/client/use-skill-context.ts b/plugins/dsh/src/client/use-skill-context.ts
new file mode 100644
index 000000000..1aab6ea8c
--- /dev/null
+++ b/plugins/dsh/src/client/use-skill-context.ts
@@ -0,0 +1,36 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { SessionId } from '@deepseek-ai/dsh-session/types';
+import type {} from '@deepseek-ai/dsh-api-session-controller/client';
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client';
+import type { SkillUseCapture } from './use-skill.js';
+
+/** Cordis creates a fresh caller-context proxy on each service lookup. */
+function serviceIdentity(value: object): unknown {
+  return Reflect.get(value, Symbol.for('cordis.original')) ?? value;
+}
+
+/** Capture the actual retained session and native shell, not transient service facades. */
+export function captureSkillUse(ctx: Context, sessionId: string, actions: SkillUseCapture['actions']): SkillUseCapture {
+  const id = SessionId(sessionId);
+  const scope = ctx.sessions.scope(id);
+  const binding = ctx.sessions.binding(id);
+  const cwd = ctx.sessions.list.getSnapshot().byId[id]?.cwd;
+  const conversation = ctx.get('conversation');
+  const layout = ctx.get('layout');
+  if (!scope || !binding || !conversation || !layout) throw new Error('请先打开当前会话，再使用此技能。');
+  const input = conversation.input.for(scope);
+  let invalidated = false;
+  const assertCurrent = () => {
+    const current = ctx.sessions.list.getSnapshot().byId[id];
+    const currentConversation = ctx.get('conversation');
+    const currentLayout = ctx.get('layout');
+    if (invalidated || ctx.sessions.scope(id) !== scope || ctx.sessions.binding(id) !== binding || current?.cwd !== cwd
+      || !current?.retainedBy.mainView || !currentConversation || !currentLayout
+      || serviceIdentity(currentConversation) !== serviceIdentity(conversation)
+      || serviceIdentity(currentLayout) !== serviceIdentity(layout)
+      || currentConversation.input.for(scope) !== input) throw new Error('当前会话或输入框已变化，请重试。');
+  };
+  const stop = ctx.sessions.list.subscribe(() => { try { assertCurrent(); } catch { invalidated = true; } });
+  return { actions, input, assertCurrent, dispose: stop };
+}
diff --git a/plugins/dsh/src/client/use-skill-drafts.ts b/plugins/dsh/src/client/use-skill-drafts.ts
new file mode 100644
index 000000000..8b55500e3
--- /dev/null
+++ b/plugins/dsh/src/client/use-skill-drafts.ts
@@ -0,0 +1,51 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { InputState } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type {} from '@deepseek-ai/dsh-api-session-controller/client';
+
+/** Native scope ownership, not a second draft/attachment store. */
+export class SkillDraftRetentions {
+  private held = new Map<string, () => void>();
+  private disposed = false;
+  constructor(private ctx: Context, private limit = 8) {}
+  preserve(sessionId: string): () => void {
+    if (this.disposed) throw new Error('技能使用服务已关闭，请重新打开插件。');
+    if (this.held.has(sessionId)) return () => {};
+    const id = SessionId(sessionId);
+    const scope = this.ctx.sessions.scope(id), binding = this.ctx.sessions.binding(id);
+    const conversation = this.ctx.get('conversation');
+    if (!scope || !binding || !conversation) throw new Error('原对话输入框不可用，请重试。');
+    const input = conversation.input.for(scope);
+    const hasContent = (state: InputState) => state.draft.length > 0 || state.attachmentIds.length > 0 || state.occurrences.length > 0
+      || state.phase !== 'plain' || state.claim !== undefined || state.queue.length > 0 || binding.session.getSnapshot().pendingSubmissions.length > 0;
+    if (!hasContent(input.state.getSnapshot())) return () => {};
+    if (this.held.size >= this.limit) throw new Error('已有 8 个对话保留了未完成草稿，请先返回这些对话处理草稿，再使用技能新建对话。');
+    const reference = this.ctx.sessions.retain(id, { source: 'workspaceOperation' });
+    // retain() starts an existing binding's open waiter; ownership itself is synchronous.
+    void reference.ready.catch(() => release());
+    let departed = false, released = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const stops: (() => void)[] = [];
+    const release = () => {
+      if (released) return;
+      released = true; if (timer) clearTimeout(timer);
+      this.held.delete(sessionId); for (const stop of stops) stop(); reference.release();
+    };
+    const check = () => {
+      if (released) return;
+      if (this.ctx.sessions.scope(id) !== scope || this.ctx.sessions.binding(id) !== binding || binding.session.getSnapshot().removed) { release(); return; }
+      const main = (this.ctx.sessions.list.getSnapshot().byId[id]?.retainedBy.mainView ?? 0) > 0;
+      if (!main) departed = true;
+      else if (departed) { release(); return; }
+      if (timer) { clearTimeout(timer); timer = undefined; }
+      if (!hasContent(input.state.getSnapshot())) {
+        // Native submission settlement may restore a failed optimistic draft in this turn.
+        timer = setTimeout(() => { timer = undefined; if (!hasContent(input.state.getSnapshot())) release(); }, 0);
+      }
+    };
+    this.held.set(sessionId, release);
+    stops.push(this.ctx.sessions.list.subscribe(check), input.state.subscribe(check), binding.session.subscribe(check));
+    return release;
+  }
+  dispose(): void { this.disposed = true; for (const release of [...this.held.values()]) release(); }
+}
diff --git a/plugins/dsh/src/client/use-skill-navigation.ts b/plugins/dsh/src/client/use-skill-navigation.ts
new file mode 100644
index 000000000..2987637af
--- /dev/null
+++ b/plugins/dsh/src/client/use-skill-navigation.ts
@@ -0,0 +1,63 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { SessionId } from '@deepseek-ai/dsh-session/types';
+import type {} from '@deepseek-ai/dsh-client-ui-workspace/client';
+import type {} from '@deepseek-ai/dsh-api-workspace-controller/client';
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client';
+import type { InstalledSkillList } from '../host/types.js';
+import type { SkillDraftRetentions } from './use-skill-drafts.js';
+import { exactInstalledSkill } from './use-skill.js';
+
+/** Create a fresh Host session: a reusable blank may already hold an unsent draft. */
+export async function newSkillConversation(ctx: Context, originalId: string, revision: string, key: string, signal: AbortSignal,
+  installed: (sessionId: string, revision: string, signal: AbortSignal) => Promise<InstalledSkillList>, drafts: Pick<SkillDraftRetentions, 'preserve'>) {
+  const id = SessionId(originalId);
+  const scope = ctx.sessions.scope(id);
+  const binding = ctx.sessions.binding(id);
+  const cwd = ctx.sessions.list.getSnapshot().byId[id]?.cwd;
+  const layout = ctx.get('layout');
+  const navigation = ctx.get('uiWorkspace');
+  const workspaces = ctx.get('workspaces');
+  if (!scope || !binding || !cwd || !layout || !navigation || !workspaces) throw new Error('请先打开工作区，再使用此技能。');
+  const workspace = workspaces.list.getSnapshot().items.find(item => item.sessionIds.includes(id));
+  if (!workspace) throw new Error('当前会话不属于可用工作区，请先打开工作区。');
+  const combined = AbortSignal.any([signal, layout.beginNavigation()]);
+  let invalidated = false;
+  const assertOriginal = () => {
+    if (invalidated || combined.aborted || ctx.sessions.scope(id) !== scope || ctx.sessions.binding(id) !== binding
+      || ctx.sessions.list.getSnapshot().byId[id]?.cwd !== cwd || !ctx.sessions.list.getSnapshot().byId[id]?.retainedBy.mainView
+      || !ctx.get('workspaces')?.list.getSnapshot().items.some(item => item.workspaceId === workspace.workspaceId && item.sessionIds.includes(id))) {
+      throw new Error('工作区或会话已变化，请重新点击使用。');
+    }
+  };
+  const stop = ctx.sessions.list.subscribe(() => { try { assertOriginal(); } catch { invalidated = true; } });
+  const stopWorkspace = workspaces.list.subscribe(() => { try { assertOriginal(); } catch { invalidated = true; } });
+  let reference: ReturnType<Context['sessions']['retain']> | undefined;
+  const releaseDrafts: (() => void)[] = [];
+  let navigated = false;
+  try {
+    assertOriginal();
+    const before = await installed(originalId, revision, combined);
+    assertOriginal();
+    const identity = before.items.find(item => item.itemKey === key);
+    if (!identity || !exactInstalledSkill(before, identity)) throw new Error('安装记录已变化，请刷新已安装列表。');
+    releaseDrafts.push(drafts.preserve(originalId));
+    let created: SessionId;
+    try { created = await ctx.sessions.create({ workspaceId: workspace.workspaceId, cwd }); }
+    catch { assertOriginal(); throw new Error('新对话创建失败，原对话和草稿已保留，请重试。'); }
+    assertOriginal();
+    reference = ctx.sessions.retain(created, { source: 'workspaceOperation', signal: combined });
+    await reference.ready;
+    assertOriginal();
+    if (created === id || ctx.sessions.list.getSnapshot().byId[created]?.cwd !== cwd) throw new Error('新对话工作区不匹配，请重试。');
+    const after = await installed(created, revision, combined);
+    assertOriginal();
+    const item = exactInstalledSkill(after, identity);
+    if (!item) throw new Error('新对话中的安装记录已变化，请刷新已安装列表。');
+    // Capture any attachment/reference added while Host creation and inventory reads were pending.
+    releaseDrafts.push(drafts.preserve(originalId));
+    stop(); stopWorkspace();
+    navigation.openSession(created);
+    navigated = true;
+    return { sessionId: created, itemKey: item.itemKey };
+  } finally { stop(); stopWorkspace(); reference?.release(); if (!navigated) for (const release of releaseDrafts) release(); }
+}
diff --git a/plugins/dsh/src/client/use-skill.tsx b/plugins/dsh/src/client/use-skill.tsx
new file mode 100644
index 000000000..a0a532dbe
--- /dev/null
+++ b/plugins/dsh/src/client/use-skill.tsx
@@ -0,0 +1,334 @@
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react';
+import type { InputActions, SessionInput, InputState } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { InstalledSkillList, SkillUsePreparation, SkillExample, SkillExamples } from '../host/types.js';
+import { Button } from './ui.js';
+import { NativeControlStyles } from './native-control-styles.js';
+
+type SkillInputActions = Pick<InputActions, 'captureInsertion' | 'insertText'>;
+type SkillInput = { state: Pick<SessionInput['state'], 'getSnapshot'>; focus(): void };
+export type ExampleSelection = { locale: string; id: string } | { custom: true };
+type ChooseExample = (items: SkillExample[], locale: string, signal: AbortSignal) => Promise<ExampleSelection>;
+export function selectExampleLocale(examples: Extract<SkillExamples, { state: 'ready' }>, language?: string): string {
+  const keys = Object.keys(examples.items);
+  let candidate = language?.toLowerCase();
+  while (candidate) { const match = keys.find(key => key.toLowerCase() === candidate); if (match) return match; candidate = candidate.includes('-') ? candidate.slice(0, candidate.lastIndexOf('-')) : undefined; }
+  return keys.find(key => key.toLowerCase() === examples.defaultLocale.toLowerCase()) ?? examples.defaultLocale;
+}
+export function exampleTask(prompt: string, name: string, draft: string): string {
+  const token = `/${name}`;
+  if (prompt.includes('{{skill}}')) return prompt.replaceAll('{{skill}}', token);
+  return `${draft.split(/\s+/u).includes(token) ? '' : `请使用 ${token} 完成本次任务。\n`}${prompt}`;
+}
+/** Read separator boundaries in the native detect projection; never alter captured coordinates. */
+export function skillTaskInsertion(task: string, state: Pick<InputState, 'draft' | 'occurrences'>, at: number): string {
+  let projection = '', offset = 0;
+  for (const occurrence of state.occurrences) {
+    projection += state.draft.slice(offset, occurrence.offset) + '\uFFFC';
+    offset = occurrence.offset + occurrence.length;
+  }
+  projection += state.draft.slice(offset);
+  const before = projection[at - 1], after = projection[at];
+  const prefix = before !== undefined && before !== '\n' && before !== '\r' && !/^[\r\n]/u.test(task) ? '\n' : '';
+  const suffix = after !== undefined && after !== '\n' && after !== '\r' && !/[\r\n]$/u.test(task) ? '\n' : '';
+  return prefix + task + suffix;
+}
+type Item = InstalledSkillList['items'][number];
+export interface SkillUseServices {
+  useSkill(revision: string, itemKey: string | undefined, signal: AbortSignal, resolve?: (signal: AbortSignal) => Promise<string>, choose?: ChooseExample, onHandoff?: () => void): Promise<void>;
+}
+export interface SkillUseCapture {
+  actions: SkillInputActions;
+  input: SkillInput;
+  assertCurrent(): void;
+  dispose?(): void;
+}
+export interface SkillUseEnvironment {
+  capture(sessionId: string, actions: SkillInputActions): SkillUseCapture;
+  revision(): Promise<string>;
+  prepare(sessionId: string, revision: string, itemKey: string, signal: AbortSignal): Promise<RemoteResult<SkillUsePreparation>>;
+  locale?(): string | undefined;
+  subscribeLocale?(listener: () => void): () => void;
+  reveal(): void;
+  newConversation?(sessionId: string, revision: string, itemKey: string, signal: AbortSignal): Promise<{ sessionId: string; itemKey: string }>;
+  subscribeContext?(listener: () => void): () => void;
+  current?(sessionId: string): boolean;
+}
+const blocked: Record<Extract<SkillUsePreparation, { status: 'blocked' }>['reason'], string> = {
+  'installation-unverified': '安装记录已变化，请刷新已安装列表。',
+  'operation-pending': '此技能仍有操作进行中，请完成后重试。',
+  'shared-installation': '此安装暂不支持直接使用，请在 DSH 中选择技能。',
+  'files-changed': '本地技能文件已变化，请先核对安装。',
+  'skill-unavailable': '当前会话尚未发现此技能，请稍后重试。',
+  'skill-shadowed': '当前会话有另一个同名技能，请先处理同名覆盖。',
+  'user-invocation-disabled': '此技能不允许用户直接调用。',
+  'unsupported-name': '此技能名称暂不支持原生调用。',
+  'host-unavailable': 'DSH 技能服务暂不可用，请重新打开会话。',
+};
+class SkillUseCancelled extends Error {}
+const stale = () => new Error('会话、来源或输入框已变化，请在当前会话重试。');
+
+/** One path for every entry. All edits use native revision comparison; no whole-draft replacement. */
+export interface SkillCasePanel {
+  sessionId: string; name: string; items: SkillExample[]; locale: string;
+  busy: boolean; error?: string; finish(selection?: ExampleSelection): void;
+}
+export class SkillUseController {
+  private activeSessions = new Set<string>();
+  private panel: SkillCasePanel | undefined;
+  private catalogRequest: Promise<void> | undefined;
+  private routeAbort: AbortController | undefined;
+  readonly casePanel = () => this.panel;
+  private publishPanel(panel: SkillCasePanel | undefined): void { this.panel = panel; for (const listener of this.listeners) listener(); }
+  private choose(sessionId: string, name: string): ChooseExample {
+    return (items, locale, signal) => new Promise((resolve, reject) => {
+      this.panel?.finish();
+      let settled = false;
+      const abort = () => finish();
+      const finish = (selection?: ExampleSelection) => {
+        if (settled) return;
+        settled = true; signal.removeEventListener('abort', abort);
+        if (selection) { this.publishPanel({ ...this.panel!, busy: true }); resolve(selection); }
+        else { this.publishPanel(undefined); reject(new SkillUseCancelled('已取消选择。')); }
+      };
+      signal.addEventListener('abort', abort, { once: true });
+      if (signal.aborted) { finish(); return; }
+      this.publishPanel({ sessionId, name, items, locale, finish, busy: false });
+    });
+  }
+  private async waitForComposer(sessionId: string, signal: AbortSignal): Promise<void> {
+    if (this.leases.get(sessionId)?.size) return;
+    await new Promise<void>((resolve, reject) => {
+      const done = (error?: Error) => { stop?.(); clearTimeout(timer); this.listeners.delete(check); signal.removeEventListener('abort', abort); if (error) reject(error); else resolve(); };
+      const check = () => { if (this.environment.current?.(sessionId) === false) done(stale()); else if (this.leases.get(sessionId)?.size) done(); };
+      const abort = () => done(stale());
+      const timer = setTimeout(() => done(new Error('新对话输入框尚未就绪，请重新打开会话。')), 10000);
+      this.listeners.add(check); const stop = this.environment.subscribeContext?.(check); signal.addEventListener('abort', abort, { once: true });
+      if (signal.aborted) abort(); else check();
+    });
+  }
+  catalogServices(sessionId: string): SkillUseServices {
+    return { useSkill: (revision, itemKey, signal, resolve, _choose, onHandoff) => {
+      if (this.catalogRequest) return this.catalogRequest;
+      const route = new AbortController(); this.routeAbort = route;
+      const run = async () => {
+        let target: { sessionId: string; itemKey: string } | undefined;
+        try {
+          if (!this.environment.newConversation) throw new Error('DSH 新对话服务暂不可用。');
+          const key = itemKey ?? await resolve?.(signal);
+          if (signal.aborted || route.signal.aborted || this.disposed) throw stale();
+          if (!key) throw new Error('原安装版本已变化，请刷新已安装列表。');
+          target = await this.environment.newConversation(sessionId, revision, key, AbortSignal.any([signal, route.signal]));
+          // The catalog unmount now releases its button. The resident controller owns the handoff.
+          await this.waitForComposer(target.sessionId, route.signal);
+          await this.use(target.sessionId, revision, target.itemKey, route.signal, undefined, undefined, onHandoff);
+        } catch (cause) {
+          if (target && !this.disposed && !route.signal.aborted && this.environment.current?.(target.sessionId) !== false && !(cause instanceof SkillUseCancelled) && !this.panel) {
+            this.publishPanel({ sessionId: target.sessionId, name: '', items: [], locale: '', busy: false, error: cause instanceof Error ? cause.message : '暂时无法使用，请重试。', finish: () => this.publishPanel(undefined) });
+          }
+          throw cause;
+        }
+      };
+      this.catalogRequest = run().finally(() => { this.catalogRequest = undefined; if (this.routeAbort === route) this.routeAbort = undefined; });
+      return this.catalogRequest;
+    } };
+  }
+  private leases = new Map<string, Set<{ actions: SkillInputActions }>>();
+  private listeners = new Set<() => void>();
+  private pendingFocus: { sessionId: string; capture: SkillUseCapture } | undefined;
+  private disposed = false;
+  private inFlight = new Set<AbortController>();
+  bind(sessionId: string, actions: SkillInputActions): () => void {
+    const entry = { actions };
+    const leases = this.leases.get(sessionId) ?? new Set();
+    this.leases.set(sessionId, leases); leases.add(entry);
+    for (const listener of this.listeners) listener();
+    return () => { leases.delete(entry); if (!leases.size) this.leases.delete(sessionId); };
+  }
+  constructor(private environment: SkillUseEnvironment) {}
+  readonly subscribe = (listener: () => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+  readonly focusRequest = () => this.pendingFocus;
+  focus(sessionId: string): void {
+    const pending = this.pendingFocus;
+    if (!pending || pending.sessionId !== sessionId) return;
+    this.pendingFocus = undefined;
+    try { if (!this.disposed) { pending.capture.assertCurrent(); pending.capture.input.focus(); } } catch { /* Navigation invalidated the request; never focus a different input. */ }
+  }
+  services(sessionId: string): SkillUseServices {
+    return { useSkill: (revision, itemKey, signal, resolve, choose, onHandoff) => this.use(sessionId, revision, itemKey, signal, resolve, choose, onHandoff) };
+  }
+  private async use(sessionId: string, revision: string, itemKey: string | undefined, signal: AbortSignal, resolve?: (signal: AbortSignal) => Promise<string>, choose?: ChooseExample, onHandoff?: () => void): Promise<void> {
+    const actions = [...(this.leases.get(sessionId) ?? [])].at(-1)?.actions;
+    if (this.disposed || !actions) throw new Error('请先打开当前会话，再使用此技能。');
+    if (this.activeSessions.has(sessionId)) throw new Error('请先完成或关闭当前技能的案例选择。');
+    const capture = this.environment.capture(sessionId, actions);
+    this.activeSessions.add(sessionId);
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal.addEventListener('abort', abort, { once: true });
+    this.inFlight.add(controller);
+    let detached = false;
+    const stopLocale = this.environment.subscribeLocale?.(abort);
+    const stopContext = this.environment.subscribeContext?.(() => { try { capture.assertCurrent(); } catch { abort(); } });
+    const assertCurrent = () => {
+      if (this.disposed || (!detached && signal.aborted) || controller.signal.aborted || ![...(this.leases.get(sessionId) ?? [])].some(lease => lease.actions === actions)) throw stale();
+      capture.assertCurrent();
+      if (capture.input.state.getSnapshot().phase !== 'plain') throw stale();
+    };
+    try {
+      capture.assertCurrent();
+      if (capture.input.state.getSnapshot().phase !== 'plain') throw new Error('请先完成或取消输入框中的命令，再使用技能。');
+      const initialDraftRev = capture.input.state.getSnapshot().draftRev;
+      let span: ReturnType<SkillInputActions['captureInsertion']> | undefined;
+      assertCurrent();
+      if (await this.environment.revision() !== revision) throw stale();
+      assertCurrent();
+      const key = itemKey ?? await resolve?.(controller.signal);
+      assertCurrent();
+      if (!key) throw new Error('原安装版本已变化，请在已安装中选择当前版本。');
+      const response = await this.environment.prepare(sessionId, revision, key, controller.signal);
+      assertCurrent();
+      if (!response.ok) throw stale();
+      if (response.value.status === 'blocked') throw new Error(blocked[response.value.reason]);
+      if (await this.environment.revision() !== revision) throw stale();
+      assertCurrent();
+      let prepared = response.value;
+      let task: string | undefined;
+      const examples = prepared.examples;
+      const language = this.environment.locale?.();
+      const locale = examples.state === 'ready' ? selectExampleLocale(examples, language) : '';
+      const items = examples.state === 'ready' ? examples.items[locale] ?? [] : [];
+      if (items.length > 0 || examples.state === 'unavailable') {
+        if (!choose || onHandoff) {
+          detached = true; signal.removeEventListener('abort', abort);
+          // Closing a modal unmounts its button and aborts the entry signal: ownership has transferred first.
+          onHandoff?.(); this.environment.reveal(); assertCurrent();
+        }
+        const selection = await (choose ?? this.choose(sessionId, prepared.name))(items, locale, controller.signal);
+        assertCurrent();
+        if (this.environment.locale?.() !== language) throw stale();
+        span = actions.captureInsertion();
+        const latest = await this.environment.prepare(sessionId, revision, key, controller.signal);
+        assertCurrent();
+        if (!latest.ok || latest.value.status !== 'ready') throw stale();
+        const fresh = latest.value;
+        if (fresh.name !== prepared.name || fresh.version !== prepared.version || fresh.scope !== prepared.scope
+          || this.environment.locale?.() !== language) throw stale();
+        if (examples.state === 'ready' && (fresh.examples.state !== 'ready'
+          || fresh.examples.digest !== examples.digest || selectExampleLocale(fresh.examples, language) !== locale)) throw new Error('技能或案例已变化，请重新选择。');
+        if ('id' in selection) {
+          if (selection.locale !== locale || fresh.examples.state !== 'ready') throw stale();
+          const item = fresh.examples.items[locale]?.find(item => item.id === selection.id);
+          if (!item) throw stale();
+          task = item.prompt;
+        }
+        prepared = fresh;
+        if (await this.environment.revision() !== revision) throw stale();
+        assertCurrent();
+      }
+      if (!span) {
+        span = actions.captureInsertion();
+        if (span.draftRev !== initialDraftRev) throw new Error('草稿已被编辑，内容已保留，请再次点击使用。');
+      }
+      const name = prepared.name;
+      // A non-command leading phrase avoids collisions with native slash commands.
+      const snapshot = capture.input.state.getSnapshot();
+      if (snapshot.draftRev !== span.draftRev) throw new Error('草稿已被编辑，内容已保留，请再次点击使用。');
+      const draft = snapshot.draft;
+      const token = `/${name}`;
+      const exists = draft.split(/\s+/u).includes(token);
+      const body = task !== undefined ? exampleTask(task, name, draft) : `请使用 ${token} 完成本次任务。请补充任务目标和输入材料。`;
+      if ((task !== undefined || !exists) && !actions.insertText(skillTaskInsertion(body, snapshot, span.end), { start: span.end, end: span.end, draftRev: span.draftRev })) {
+        throw new Error('草稿已被编辑，内容已保留，请再次点击使用。');
+      }
+      this.pendingFocus = { sessionId, capture };
+      this.environment.reveal();
+      for (const listener of this.listeners) listener();
+    } catch (cause) {
+      if (this.panel?.sessionId === sessionId && !(cause instanceof SkillUseCancelled) && !controller.signal.aborted) {
+        this.publishPanel({ ...this.panel, items: [], busy: false, error: cause instanceof Error ? cause.message : '暂时无法使用，请重试。', finish: () => this.publishPanel(undefined) });
+      }
+      throw cause;
+    } finally {
+      if (this.panel?.sessionId === sessionId && !this.panel.error) this.publishPanel(undefined);
+      this.activeSessions.delete(sessionId);
+      stopContext?.(); stopLocale?.();
+      capture.dispose?.();
+      signal.removeEventListener('abort', abort); this.inFlight.delete(controller);
+    }
+  }
+  dispose(): void { this.disposed = true; this.routeAbort?.abort(); this.panel?.finish(); for (const request of this.inFlight) request.abort(); this.inFlight.clear(); this.leases.clear(); this.pendingFocus = undefined; this.listeners.clear(); }
+}
+
+/** Standard native slot props supply actions; no editor DOM/private controller access. */
+export function SkillUseBinding({ controller, sessionId, actions, children }: { controller: SkillUseController; sessionId?: string; actions?: InputActions; children?: ReactNode }) {
+  useLayoutEffect(() => sessionId && actions ? controller.bind(sessionId, actions) : undefined, [controller, sessionId, actions]);
+  return <>{children}</>;
+}
+/** Runs after the resident native composer mounts, including when returning from the catalog. */
+export function SkillUseFocus({ controller, sessionId }: { controller: SkillUseController; sessionId: string }) {
+  const request = useSyncExternalStore(controller.subscribe, controller.focusRequest, controller.focusRequest);
+  useEffect(() => { if (request) controller.focus(sessionId); }, [controller, sessionId, request]);
+  return null;
+}
+
+export function exactInstalledSkill(inventory: InstalledSkillList, identity: Pick<Item, 'namespace' | 'slug' | 'version' | 'scope'>): Item | undefined {
+  if (!inventory.complete || inventory.unavailable.includes(identity.scope)) return;
+  return inventory.items.find(item => item.namespace === identity.namespace && item.slug === identity.slug && item.version === identity.version && item.scope === identity.scope && item.state === 'present');
+}
+
+/** Request ownership survives renders but is revoked when the entry's target changes. */
+export class SkillUseButtonRequests {
+  private current: AbortController | undefined;
+  private snapshot = { busy: false, error: '' };
+  private listeners = new Set<() => void>();
+  readonly subscribe = (listener: () => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+  readonly getSnapshot = () => this.snapshot;
+  private update(busy: boolean, error: string) {
+    this.snapshot = { busy, error }; for (const listener of this.listeners) listener();
+  }
+  reset(): void { this.current?.abort(); this.current = undefined; this.update(false, ''); }
+  async run(action: (signal: AbortSignal) => Promise<void>, onUsed?: () => void): Promise<void> {
+    if (this.current) return;
+    const request = new AbortController(); this.current = request; this.update(true, '');
+    try {
+      await action(request.signal);
+      if (this.current === request && !request.signal.aborted) onUsed?.();
+    } catch (cause) {
+      if (this.current === request && !request.signal.aborted && !(cause instanceof SkillUseCancelled)) this.update(true, cause instanceof Error ? cause.message : '暂时无法使用，请重试。');
+    } finally {
+      if (this.current === request) { this.current = undefined; this.update(false, this.snapshot.error); }
+    }
+  }
+}
+
+/** Resident full-width native dock; catalog teardown cannot remove the pending choice. */
+export function SkillCaseChoices({ controller, sessionId }: { controller: SkillUseController; sessionId: string }) {
+  const panel = useSyncExternalStore(controller.subscribe, controller.casePanel, controller.casePanel);
+  const [selected, setSelected] = useState('');
+  useEffect(() => { setSelected(panel?.items[0]?.id ?? ''); }, [panel?.items]);
+  if (!panel || panel.sessionId !== sessionId) return null;
+  return <section className="skillhub-controls astron-sh-case-panel" aria-label="技能任务案例">
+    <NativeControlStyles />
+    <header><div><strong>{panel.name ? `使用 /${panel.name}` : '使用此技能'}</strong><span>选择任务后填入输入框，可继续编辑。</span></div><Button size="icon" variant="ghost" aria-label="关闭案例选择" disabled={panel.busy} onClick={() => panel.finish()}>×</Button></header>
+    {panel.error ? <p role="alert">{panel.error}</p> : <>
+      {!panel.items.length && <p>案例暂时无法读取，仍可自定义任务。</p>}
+      <div className="astron-sh-case-grid" role="group" aria-label="可选任务">{panel.items.map(item => <button type="button" key={item.id} disabled={panel.busy} aria-pressed={selected === item.id} className="astron-sh-case" onClick={() => setSelected(item.id)}><strong>{item.title}</strong><span>{item.prompt.replaceAll('{{skill}}', `/${panel.name}`)}</span></button>)}</div>
+      <footer><Button size="sm" variant="ghost" disabled={panel.busy} onClick={() => panel.finish({ custom: true })}>自定义任务</Button><Button size="sm" variant="default" disabled={panel.busy || !selected} onClick={() => panel.finish({ locale: panel.locale, id: selected })}>{panel.busy ? '核验中…' : '填入输入框'}</Button></footer>
+    </>}
+  </section>;
+}
+
+export function UseSkillButton({ services, revision, itemKey, resolve, onUsed, onHandoff }: {
+  services?: SkillUseServices; revision: string; itemKey?: string;
+  resolve?(signal: AbortSignal): Promise<string>; onUsed?(): void; onHandoff?(): void;
+}) {
+  const ref = useRef<SkillUseButtonRequests>();
+  if (!ref.current) ref.current = new SkillUseButtonRequests();
+  const requests = ref.current;
+  const { busy, error } = useSyncExternalStore(requests.subscribe, requests.getSnapshot, requests.getSnapshot);
+  useLayoutEffect(() => { requests.reset(); return () => requests.reset(); }, [requests, services, revision, itemKey]);
+  return <span className="astron-sh-use-skill skillhub-controls"><Button size="sm" variant="default" disabled={busy || !services} onClick={() => {
+    if (services) void requests.run(signal => services.useSkill(revision, itemKey, signal, resolve, undefined, onHandoff), onUsed);
+  }}>{busy ? '核验中…' : '使用此技能'}</Button>{error && <span role="alert">{error}</span>}</span>;
+}
diff --git a/plugins/dsh/src/host/index.ts b/plugins/dsh/src/host/index.ts
index 4f18e5fa6..25d379c1f 100644
--- a/plugins/dsh/src/host/index.ts
+++ b/plugins/dsh/src/host/index.ts
@@ -8,6 +8,7 @@ import type {} from '@deepseek-ai/dsh-sandbox-policy';
 import { SessionId } from '@deepseek-ai/dsh-session/types';
 import { createHmac, randomBytes, randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { Config } from './config.js';
 import { ConversationSelections } from './conversation-selections.js';
 import type { SelectionSnapshot } from './conversation-selections.js';
@@ -25,7 +26,7 @@ import { UpgradePlans, RemovalPlans } from './upgrade-plans.js';
 import type { UpgradePlanView, UninstallPlanView, HostExecutePlanRequest, HostRecoveryRequest } from './types.js';
 import type { ResolvedInstallationTarget } from './installation-targets.js';
 import { assertInstallationMutation, assertRemovalMutation, resolveInstallationPath, resolveInstalledPath } from './installation-paths.js';
-import { observeDshInstallation } from './skill-discovery.js';
+import { inspectDshSkill, observeDshInstallation, sameDshSkill } from './skill-discovery.js';
 import { validateDshSkill } from './skill-format.js';
 import { installRequest, operationQuery, executePlanRequest } from './install-request.js';
 import { conversationInstallKey, conversationInstallRequest } from './conversation-install-request.js';
@@ -35,7 +36,7 @@ import type { NativeOperation, HostInstallRequest } from './types.js';
 import type { NativeRecoveryResult } from './generated/native-contract.js';
 import type { InstallationTargetList } from './types.js';
 import type { LocalRuntimeStatus } from './local-runtime.js';
-import type { InstalledSkillList, InstalledSkillDetail, InstalledUpdateCheck } from './types.js';
+import type { InstalledSkillList, InstalledSkillDetail, InstalledUpdateCheck, SkillUsePreparation } from './types.js';
 import { installationFailureCode } from './installation-failure.js';
 import type { InstalledProjectionItem } from './generated/native-contract.js';
 
@@ -317,6 +318,82 @@ export class SkillHubService extends TypertRemoteService {
     return { items, complete: result.complete, issues: result.issues, unavailable };
   }
 
+  /** Read-only handoff: installed snapshots and market names never authorize an invocation. */
+  @RemoteScope('agent')
+  async prepareSkillUse(sourceRevision: string, itemKey: string, signal: AbortSignal): Promise<SkillUsePreparation> {
+    const { item, valid, agent, runtime, fs } = await this.readInstalledItem(sourceRevision, itemKey, signal);
+    const combined = AbortSignal.any([signal, this.lifetime.signal]);
+    const skills = this.ctx.get('skills');
+    const cwd = agent!.session.header.cwd!;
+    const readyContext = () => {
+      valid(); combined.throwIfAborted();
+      if (serviceIdentity(this.ctx.get('skills')) !== serviceIdentity(skills)) {
+        throw new RemoteError('skillhub/context-stale', 'Skill discovery service changed.', { retryable: false });
+      }
+    };
+    readyContext();
+    if (!skills || runtime!.getStatus().state !== 'ready') return { status: 'blocked', reason: 'host-unavailable' };
+    if (runtime!.getStatus().pendingOperations > 0) return { status: 'blocked', reason: 'operation-pending' };
+    if (item.state !== 'present' || !item.fingerprint) return { status: 'blocked', reason: 'installation-unverified' };
+    try {
+      const target = await resolveInstalledPath({ scope: item.scope, cwd, fs: fs!, signal: combined });
+      readyContext();
+      if (join(target.root, item.slug) !== item.targetPath) {
+        throw new RemoteError('skillhub/context-stale', 'Installed target changed.', { retryable: false });
+      }
+      const identity = { registry: this.getContext().registryUrl, namespace: item.namespace, slug: item.slug, version: item.version };
+      const baseline = await runtime!.inspectRemoval(identity, target);
+      readyContext();
+      if (baseline.status === 'blocked') return { status: 'blocked', reason:
+        baseline.reason === 'shared-target' ? 'shared-installation' : 'files-changed' };
+      if (baseline.kind !== 'uninstall' || baseline.inventoryItem.fingerprint !== item.fingerprint
+        || baseline.target.path !== item.targetPath) return { status: 'blocked', reason: 'files-changed' };
+      const examples = await runtime!.readSkillExamples(item.targetPath);
+      readyContext();
+      if (examples.state === 'ready' && baseline.target.files['.skillhub/examples.json'] !== examples.digest) {
+        return { status: 'blocked', reason: 'files-changed' };
+      }
+      const observed = await inspectDshSkill(agent!.ctx, item.targetPath, combined,
+        name => skills.get(name, { scope: agent!, cwd, signal: combined }));
+      readyContext();
+      if (observed.status !== 'ready') return { status: 'blocked', reason:
+        observed.status === 'shadowed' ? 'skill-shadowed' : 'skill-unavailable' };
+      if (!observed.skill.invocation.userInvocable) return { status: 'blocked', reason: 'user-invocation-disabled' };
+      if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(observed.skill.name)) {
+        return { status: 'blocked', reason: 'unsupported-name' };
+      }
+      // Re-read both the opaque record and every selected-target file after asynchronous discovery.
+      const latest = await this.readInstalledItem(sourceRevision, itemKey, combined);
+      readyContext();
+      const current = await resolveInstalledPath({ scope: item.scope, cwd, fs: fs!, signal: combined });
+      readyContext();
+      if (current.root !== target.root || current.dshHome !== target.dshHome) {
+        throw new RemoteError('skillhub/context-stale', 'Installed target changed.', { retryable: false });
+      }
+      const inspected = await runtime!.inspectRemoval(identity, current);
+      readyContext(); latest.valid();
+      if (!isDeepStrictEqual(inspected, baseline)) return { status: 'blocked', reason: 'files-changed' };
+      if (runtime!.getStatus().state !== 'ready' || runtime!.getStatus().pendingOperations > 0) {
+        return { status: 'blocked', reason: 'operation-pending' };
+      }
+      const winner = await skills.get(observed.skill.name, { scope: agent!, cwd, signal: combined });
+      readyContext();
+      if (!winner) return { status: 'blocked', reason: 'skill-unavailable' };
+      if (!sameDshSkill(winner, observed.skill, item.targetPath)) return { status: 'blocked', reason: 'skill-shadowed' };
+      const finalBaseline = await runtime!.inspectRemoval(identity, current);
+      readyContext(); latest.valid();
+      if (!isDeepStrictEqual(finalBaseline, baseline)) return { status: 'blocked', reason: 'files-changed' };
+      if (runtime!.getStatus().state !== 'ready' || runtime!.getStatus().pendingOperations > 0) {
+        return { status: 'blocked', reason: 'operation-pending' };
+      }
+      return { status: 'ready', name: observed.skill.name, version: item.version, scope: item.scope, examples };
+    } catch (error) {
+      readyContext();
+      if (error instanceof RemoteError) throw error;
+      return { status: 'blocked', reason: 'skill-unavailable' };
+    }
+  }
+
   @RemoteScope('agent')
   async getInstalledDetail(sourceRevision: string, itemKey: string, signal: AbortSignal): Promise<InstalledSkillDetail> {
     const { item, valid } = await this.readInstalledItem(sourceRevision, itemKey, signal);
diff --git a/plugins/dsh/src/host/local-runtime.ts b/plugins/dsh/src/host/local-runtime.ts
index 49e9827cc..809fb73f3 100644
--- a/plugins/dsh/src/host/local-runtime.ts
+++ b/plugins/dsh/src/host/local-runtime.ts
@@ -111,6 +111,10 @@ export class LocalRuntime {
     return this.call(runtime => runtime.inspectRemoval(identity, root));
   }
 
+  readSkillExamples(directory: string): ReturnType<NativeRuntime['readSkillExamples']> {
+    return this.call(runtime => runtime.readSkillExamples(directory));
+  }
+
   listInstalled(registry: string, targets: readonly InstalledProjectionTarget[]): Promise<InstalledProjection> {
     const roots = targets.map(target => ({ ...target }));
     return this.call(runtime => runtime.listInstalled(registry, roots));
diff --git a/plugins/dsh/src/host/runtime-compatibility.ts b/plugins/dsh/src/host/runtime-compatibility.ts
index 2b99f620e..02e9920d6 100644
--- a/plugins/dsh/src/host/runtime-compatibility.ts
+++ b/plugins/dsh/src/host/runtime-compatibility.ts
@@ -31,6 +31,9 @@ export const clientPackageBaseline = [
   '@deepseek-ai/dsh-client-ui-tool',
   '@deepseek-ai/dsh-api-session-controller',
   '@deepseek-ai/dsh-client-ui-session',
+  '@deepseek-ai/dsh-client-ui-conversation',
+  '@deepseek-ai/dsh-api-workspace-controller',
+  '@deepseek-ai/dsh-client-ui-workspace',
 ] as const;
 
 interface RuntimeServices {
diff --git a/plugins/dsh/src/host/skill-discovery.ts b/plugins/dsh/src/host/skill-discovery.ts
index c0b28dbd8..81465ee83 100644
--- a/plugins/dsh/src/host/skill-discovery.ts
+++ b/plugins/dsh/src/host/skill-discovery.ts
@@ -3,32 +3,48 @@ import { FileSystemSkillProvider } from '@deepseek-ai/dsh-skill-filesystem';
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
-type LoadedSkill = NonNullable<Awaited<ReturnType<FileSystemSkillProvider['get']>>>;
+export type LoadedSkill = NonNullable<Awaited<ReturnType<FileSystemSkillProvider['get']>>>;
 
-/** Compare the scoped registry winner with the exact installed package, without registering another provider. */
+export type DshSkillObservation = { status: 'ready'; skill: LoadedSkill }
+  | { status: 'unavailable' | 'shadowed' };
+
+/** Load the exact local package and compare it with the current session's registry winner. */
+export async function inspectDshSkill(ctx: Context, directory: string, signal: AbortSignal,
+  lookup: (name: string) => Promise<LoadedSkill | undefined>): Promise<DshSkillObservation> {
+  signal.throwIfAborted();
+  const provider = new FileSystemSkillProvider(ctx, { signal, invalidate: () => {} }, {
+    providerName: 'skillhub-discovery-check', includeDefaultRoots: false, customSkillDirs: [directory], watch: false,
+  });
+  try {
+    const listed = await provider.list({ signal });
+    if (!Array.isArray(listed) && !listed.complete) return { status: 'unavailable' };
+    const candidates = Array.isArray(listed) ? listed : listed.candidates;
+    const candidate = candidates.find(item => item.path === join(directory, 'SKILL.md'));
+    if (!candidate) return { status: 'unavailable' };
+    const expected = await provider.get(candidate, { signal });
+    if (!expected) return { status: 'unavailable' };
+    const actual = await lookup(expected.name);
+    signal.throwIfAborted();
+    if (!actual) return { status: 'unavailable' };
+    if (!sameDshSkill(actual, expected, directory)) return { status: 'shadowed' };
+    return { status: 'ready', skill: actual };
+  } finally { await provider.dispose(); }
+}
+
+/** Preserve the operation observer's boolean contract without registering another provider. */
 export async function observeDshInstallation(ctx: Context, paths: readonly string[], signal: AbortSignal,
   lookup: (name: string) => Promise<LoadedSkill | undefined>): Promise<boolean> {
   for (const directory of paths) {
-    signal.throwIfAborted();
-    const provider = new FileSystemSkillProvider(ctx, { signal, invalidate: () => {} }, {
-      providerName: 'skillhub-discovery-check', includeDefaultRoots: false, customSkillDirs: [directory], watch: false,
-    });
-    try {
-      const listed = await provider.list({ signal });
-      if (!Array.isArray(listed) && !listed.complete) return false;
-      const candidates = Array.isArray(listed) ? listed : listed.candidates;
-      const candidate = candidates.find(item => item.path === join(directory, 'SKILL.md'));
-      if (!candidate) return false;
-      const expected = await provider.get(candidate, { signal });
-      if (!expected) return false;
-      const actual = await lookup(expected.name);
-      signal.throwIfAborted();
-      if (!actual || actual.resourceBase?.kind !== 'directory' || actual.resourceBase.path !== directory
-        || actual.path !== expected.path || actual.name !== expected.name || actual.content !== expected.content
-        || actual.description !== expected.description || actual.whenToUse !== expected.whenToUse
-        || !isDeepStrictEqual(actual.invocation, expected.invocation)
-        || !isDeepStrictEqual(actual.metadata, expected.metadata)) return false;
-    } finally { await provider.dispose(); }
+    if ((await inspectDshSkill(ctx, directory, signal, lookup)).status !== 'ready') return false;
   }
   return paths.length > 0;
 }
+
+/** Compare the winner again after filesystem inspection, without loading another provider. */
+export function sameDshSkill(actual: LoadedSkill, expected: LoadedSkill, directory: string): boolean {
+  return actual.resourceBase?.kind === 'directory' && actual.resourceBase.path === directory
+    && actual.path === expected.path && actual.name === expected.name && actual.content === expected.content
+    && actual.description === expected.description && actual.whenToUse === expected.whenToUse
+    && isDeepStrictEqual(actual.invocation, expected.invocation)
+    && isDeepStrictEqual(actual.metadata, expected.metadata);
+}
diff --git a/plugins/dsh/src/host/types.ts b/plugins/dsh/src/host/types.ts
index f7446ddae..fb57d3350 100644
--- a/plugins/dsh/src/host/types.ts
+++ b/plugins/dsh/src/host/types.ts
@@ -86,6 +86,15 @@ export interface InstallationTargetList {
   unavailable: ('user' | 'project')[];
 }
 
+/** Controlled, path-free reasons for refusing a native composer handoff. */
+export type SkillUseBlockReason = 'installation-unverified' | 'operation-pending' | 'shared-installation'
+  | 'files-changed' | 'skill-unavailable' | 'skill-shadowed' | 'user-invocation-disabled'
+  | 'unsupported-name' | 'host-unavailable';
+
+export type { SkillExamples, SkillExample } from './generated/native-contract.js';
+export type SkillUsePreparation = { status: 'ready'; name: string; version: string; scope: 'user' | 'project'; examples: import('./generated/native-contract.js').SkillExamples }
+  | { status: 'blocked'; reason: SkillUseBlockReason };
+
 export interface InstalledSkillList {
   items: { itemKey: string; namespace: string; slug: string; version: string; scope: 'user' | 'project';
     state: 'present' | 'missing' | 'metadata-invalid' | 'mismatch' | 'unreadable' }[];
diff --git a/plugins/dsh/test/client-entry-lifecycle.test.ts b/plugins/dsh/test/client-entry-lifecycle.test.ts
index 01a4515c4..0f7e56202 100644
--- a/plugins/dsh/test/client-entry-lifecycle.test.ts
+++ b/plugins/dsh/test/client-entry-lifecycle.test.ts
@@ -26,7 +26,7 @@ test('layout loss removes only catalog entries and preserves conversation regist
   const flush = async () => { await new Promise(resolve => setTimeout(resolve, 25)); };
   try {
     await plugin; await flush();
-    const tools = ['tool.call.toolview/astron_skillhub_install', 'tool.call.toolview/astron_skillhub_search'];
+    const tools = ['conversation.input.dock/skillhub-case-choices', 'conversation.input.left/skillhub-use-focus', 'tool.call.toolview/astron_skillhub_install', 'tool.call.toolview/astron_skillhub_search'];
     expect([...entries.keys()].sort()).toEqual(tools);
     const original = tools.map(key => entries.get(key));
     for (let cycle = 0; cycle < 2; cycle++) {
@@ -40,6 +40,10 @@ test('layout loss removes only catalog entries and preserves conversation regist
     }
     await plugin.dispose();
     expect(entries.size).toBe(0);
+    const restored = ctx.plugin(clientPlugin);
+    await restored; await flush();
+    expect([...entries.keys()].sort()).toEqual(tools);
+    await restored.dispose(); expect(entries.size).toBe(0);
   } finally {
     await plugin.dispose(); await removeUiSession(); await removeSessions(); await removeSkillHub(); await removeRemote(); await slots.dispose();
   }
diff --git a/plugins/dsh/test/install-control-state.test.tsx b/plugins/dsh/test/install-control-state.test.tsx
index 6e7298057..df240df3c 100644
--- a/plugins/dsh/test/install-control-state.test.tsx
+++ b/plugins/dsh/test/install-control-state.test.tsx
@@ -24,7 +24,7 @@ function render(items: InstalledSkillList['items']) {
   client.setQueryData(['skillhub-installed', 'session', 'source'], inventory(items));
   client.setQueryData(['skillhub-compatibility'], { dependencyBaseline: 'matched', localWritesAllowed: true });
   const unexpected = async () => { throw new Error('SSR must not call transport'); };
-  const services: InstallationServices = { sessionId: 'session', requests, targets: unexpected, installed: unexpected, start: unexpected, operation: unexpected, compatibility: unexpected, manageInstalled: () => {} };
+  const services: InstallationServices = { sessionId: 'session', skillUse: { useSkill: unexpected }, requests, targets: unexpected, installed: unexpected, start: unexpected, operation: unexpected, compatibility: unexpected, manageInstalled: () => {} };
   try { return renderToStaticMarkup(<QueryClientProvider client={client}><InstallControl detail={detail} sourceRevision="source" services={services} initiatedFrom="plaza" /></QueryClientProvider>); }
   finally { client.clear(); requests.dispose(); }
 }
@@ -33,6 +33,7 @@ test('current inventory renders a removal action without a duplicate install act
   const html = render([record]);
   expect(html).toContain('已安装 v1.2.0'); expect(html).toContain('>卸载</button>');
   expect(html).not.toContain('>安装到此项目</button>'); expect(html).not.toContain('安装完成');
+  expect(html).toContain('>使用此技能</button>');
   expect(html).not.toContain('当前范围未安装'); expect(html).not.toContain('DSH Host 上该用户');
 });
 
@@ -42,3 +43,9 @@ test('empty verified inventory renders an explicit scoped install action', () =>
   expect(html).not.toContain('安装完成'); expect(html).not.toContain('重新安装到');
   expect(html).not.toContain('>卸载</button>');
 });
+
+test('use entry belongs to the installed version and never a different viewed version or invalid record', () => {
+  for (const item of [{ ...record, version: '1.1.0' }, { ...record, state: 'missing' as const }, { ...record, state: 'mismatch' as const }]) {
+    expect(render([item])).not.toContain('>使用此技能</button>');
+  }
+});
diff --git a/plugins/dsh/test/package.test.ts b/plugins/dsh/test/package.test.ts
index ac761d41e..001ce0b78 100644
--- a/plugins/dsh/test/package.test.ts
+++ b/plugins/dsh/test/package.test.ts
@@ -55,8 +55,8 @@ describe('native M0 package', () => {
   });
 
   test('official generator publishes the declared endpoints with scoped writes and strict codec', () => {
-    expect(TYPERT_REMOTE.descriptors.map(item => item.method).sort()).toEqual(['acknowledgeConversationDetail', 'checkUpdate', 'checkVersionUpdate', 'executePlan', 'getCompatibility', 'getContext', 'getInstalledDetail', 'getOperation', 'getSkillDetail', 'getStatus', 'listCatalog', 'listCatalogByLabel', 'listInstallTargets', 'listInstalled', 'listLabels', 'listReviews', 'listSkills', 'listVersions', 'openConversationDetail', 'prepareUninstall', 'prepareUpgrade', 'prepareVersionUpgrade', 'recoverOperation', 'reopenConversationDetail', 'startInstall', 'testRegistryConnection']);
-    for (const method of ['openConversationDetail', 'reopenConversationDetail', 'acknowledgeConversationDetail', 'listInstallTargets', 'listInstalled', 'getInstalledDetail', 'checkUpdate', 'checkVersionUpdate', 'prepareUninstall', 'prepareUpgrade', 'prepareVersionUpgrade', 'executePlan', 'startInstall', 'getOperation', 'recoverOperation']) {
+    expect(TYPERT_REMOTE.descriptors.map(item => item.method).sort()).toEqual(['acknowledgeConversationDetail', 'checkUpdate', 'checkVersionUpdate', 'executePlan', 'getCompatibility', 'getContext', 'getInstalledDetail', 'getOperation', 'getSkillDetail', 'getStatus', 'listCatalog', 'listCatalogByLabel', 'listInstallTargets', 'listInstalled', 'listLabels', 'listReviews', 'listSkills', 'listVersions', 'openConversationDetail', 'prepareSkillUse', 'prepareUninstall', 'prepareUpgrade', 'prepareVersionUpgrade', 'recoverOperation', 'reopenConversationDetail', 'startInstall', 'testRegistryConnection']);
+    for (const method of ['openConversationDetail', 'reopenConversationDetail', 'acknowledgeConversationDetail', 'listInstallTargets', 'listInstalled', 'getInstalledDetail', 'checkUpdate', 'checkVersionUpdate', 'prepareSkillUse', 'prepareUninstall', 'prepareUpgrade', 'prepareVersionUpgrade', 'executePlan', 'startInstall', 'getOperation', 'recoverOperation']) {
       const scoped = TYPERT_REMOTE.descriptors.find(item => item.method === method)!;
       expect(scoped.invocation).toMatchObject({ kind: 'context', context: 'agent', wire: 'agentId' });
     }
@@ -143,3 +143,33 @@ test('shared RPC ABI keeps Host/Client descriptors, cancellation, argument order
   expect(imports).toContain('@deepseek-ai/cordis');
   expect(imports).toContain('@deepseek-ai/dsh-typert-protocol');
 });
+
+
+test('skill-use RPC exposes only an agent-bound cancellable read and a restricted handoff projection', () => {
+  const use = TYPERT_REMOTE.descriptors.find(item => item.method === 'prepareSkillUse')!;
+  expect(use.invocation).toMatchObject({ kind: 'context', context: 'agent', wire: 'agentId' });
+  expect(use.parameters.map(item => ({ name: item.name, wire: item.wire, source: item.source }))).toEqual([
+    { name: 'sourceRevision', wire: 'sourceRevision', source: 'json' },
+    { name: 'itemKey', wire: 'itemKey', source: 'json' },
+  ]);
+  expect(use.cancellation).toEqual({ parameter: 'signal' });
+  for (const parameter of use.parameters) {
+    const parameterCodec = parameter.codec;
+    if (parameterCodec.mode !== 'strict') throw new Error('Expected strict parameter codec');
+    expect(() => parameterCodec.create().parse({ path: '/caller-controlled' })).toThrow();
+  }
+  if (use.result?.mode !== 'strict') throw new Error('Expected strict skill-use result codec');
+  const codec = use.result.create();
+  const ready = { status: 'ready', name: 'actual-name', version: '1.2.0', scope: 'project', examples: { state: 'none' } };
+  expect(codec.parse(ready)).toEqual(ready);
+  const withExamples = { ...ready, examples: { state: 'ready', digest: '0'.repeat(64), defaultLocale: 'zh-CN', items: {
+    'zh-CN': [{ id: 'summary', title: '整理会议', prompt: '使用 {{skill}} 整理。' }],
+    en: [{ id: 'summary', title: 'Summary', prompt: 'Use {{skill}}.' }],
+  } } };
+  expect(codec.parse(withExamples)).toEqual(withExamples);
+  expect(() => codec.parse({ ...ready, examples: { state: 'ready', items: {} } })).toThrow();
+  expect(codec.parse({ ...ready, path: '/private', content: 'private skill body' })).toEqual(ready);
+  expect(codec.parse({ status: 'blocked', reason: 'user-invocation-disabled' })).toEqual({ status: 'blocked', reason: 'user-invocation-disabled' });
+  expect(() => codec.parse({ ...ready, scope: 'arbitrary' })).toThrow();
+  expect(() => codec.parse({ status: 'blocked', reason: 'arbitrary' })).toThrow();
+});
diff --git a/plugins/dsh/test/prepare-skill-use.test.ts b/plugins/dsh/test/prepare-skill-use.test.ts
new file mode 100644
index 000000000..a80576f58
--- /dev/null
+++ b/plugins/dsh/test/prepare-skill-use.test.ts
@@ -0,0 +1,245 @@
+import { expect, test } from 'bun:test';
+import { Context, symbols } from '@deepseek-ai/cordis';
+import { FileSystemSkillProvider } from '@deepseek-ai/dsh-skill-filesystem';
+import { readSkillExamples } from '../../../cli/src/services/skill-examples.js';
+import { randomBytes, createHash } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import SkillHubService from '../src/host/index.js';
+import type { LoadedSkill } from '../src/host/skill-discovery.js';
+import type { InstalledProjectionItem, RemovalBaseline } from '../src/host/generated/native-contract.js';
+import type { SkillUsePreparation } from '../src/host/types.js';
+
+async function fixture(run: (f: {
+  use(signal?: AbortSignal, key?: string): Promise<SkillUsePreparation>; key: string; directory: string;
+  setLookup(callback: (loaded: LoadedSkill) => Promise<LoadedSkill | undefined>): void;
+  change(kind: string): void; observations(): number;
+}) => Promise<void>, frontmatter = '', examples?: string) {
+  const root = await realpath(await mkdtemp(join(tmpdir(), 'skillhub-use-')));
+  const previousHome = process.env.DSH_HOME;
+  const home = join(root, 'home'); const cwd = join(root, 'project');
+  const directory = join(home, 'skills', 'market-slug');
+  await mkdir(directory, { recursive: true }); await mkdir(cwd); process.env.DSH_HOME = home;
+  const body = `---\nname: actual-name\ndescription: Prepare documents\n${frontmatter}---\nUse references/note.md.`;
+  await writeFile(join(directory, 'SKILL.md'), body);
+  await mkdir(join(directory, 'references')); await writeFile(join(directory, 'references/note.md'), 'original');
+  if (examples !== undefined) { await mkdir(join(directory, '.skillhub')); await writeFile(join(directory, '.skillhub/examples.json'), examples); }
+  const ctx = new Context(); const controller = new AbortController();
+  const provider = new FileSystemSkillProvider(ctx, { signal: controller.signal, invalidate: () => {} }, {
+    providerName: 'fixture', includeDefaultRoots: false, customSkillDirs: [directory], watch: false,
+  });
+  try {
+    const listed = await provider.list({ signal: controller.signal });
+    const candidates = Array.isArray(listed) ? listed : listed.candidates;
+    const loaded = await provider.get(candidates[0]!, { signal: controller.signal });
+    if (!loaded) throw new Error('Missing fixture skill');
+    let lookup = async (skill: LoadedSkill): Promise<LoadedSkill | undefined> => skill;
+    let revision = 'source'; let observations = 0; let pendingOperations = 0; let shared = false;
+    const fs = { processPathFromHostPath: (path: string) => path,
+      resolve: async (path: string) => ({ displayPath: path }), processPath: (target: { displayPath: string }) => target.displayPath,
+      listDir: async (target: { displayPath: string }) => (await readdir(target.displayPath, { withFileTypes: true })).map(entry => ({
+        name: entry.name, type: entry.isDirectory() ? 'directory' : 'file', target: { displayPath: join(target.displayPath, entry.name) },
+      })),
+      stat: async (target: { displayPath: string }) => ({ type: (await lstat(target.displayPath)).isDirectory() ? 'directory' : 'file' }),
+      readText: (target: { displayPath: string }) => readFile(target.displayPath, 'utf8'),
+    };
+    let currentFs = fs;
+    const session = { id: 'session-a', header: { cwd } };
+    const agent = { session, ctx };
+    const nativeGet = ctx.get.bind(ctx);
+    ctx.get = ((name: string) => name === 'fs' ? currentFs : nativeGet(name as never)) as typeof ctx.get;
+    const skills = { get: async (name: string, options: { cwd: string; scope: unknown; signal: AbortSignal }) => {
+      expect(name).toBe('actual-name'); expect(options.cwd).toBe(cwd); expect(options.scope).toBe(agent);
+      options.signal.throwIfAborted(); observations++; return lookup(loaded);
+    } };
+    let currentSkills: (typeof skills & { [symbols.original]?: object }) | undefined = skills;
+    let currentAgent: typeof agent | undefined = agent;
+    const item: InstalledProjectionItem = { namespace: 'demo', slug: 'market-slug', version: '1.2.0', scope: 'user',
+      state: 'present', fingerprint: 'fingerprint', targetPath: directory };
+    const items = [item];
+    const baseline: RemovalBaseline = { status: 'ready', kind: 'uninstall', inventoryItem: {
+      registry: 'https://registry.example', namespace: item.namespace, slug: item.slug, version: item.version,
+      fingerprint: item.fingerprint, targets: [{ agent: 'dsh', rootDir: join(home, 'skills'), installDir: directory, installedAt: 'now' }],
+    }, target: { scope: 'user', root: join(home, 'skills'), path: directory, files: examples === undefined ? {} : { '.skillhub/examples.json': createHash('sha256').update(examples).digest('hex') }, metadata: {
+      registry: 'https://registry.example', namespace: item.namespace, slug: item.slug, version: item.version,
+    } } };
+    const runtime = { getStatus: () => ({ state: 'ready', pendingOperations }),
+      readSkillExamples,
+      listInstalled: async () => ({ items, complete: true, issues: [] }),
+      inspectRemoval: async (): Promise<RemovalBaseline> => {
+        if (shared) return { status: 'blocked', reason: 'shared-target' };
+        // Model the existing baseline's all-resource checks; real bundled core is covered by native acceptance.
+        if (await readFile(join(directory, 'SKILL.md'), 'utf8') !== body
+          || await readFile(join(directory, 'references/note.md'), 'utf8') !== 'original'
+          || (examples !== undefined && await readFile(join(directory, '.skillhub/examples.json'), 'utf8') !== examples)) {
+          return { status: 'blocked', reason: 'local-changes' };
+        }
+        return structuredClone(baseline);
+      } };
+    const service = Object.assign(Object.create(SkillHubService.prototype), {
+      lifetime: controller, installedReferenceKey: randomBytes(32), localRuntime: runtime,
+      ctx: { invocation: { request: { args: { agentId: 'session-a' } } }, get: (name: string) =>
+        name === 'agents' ? { get: () => currentAgent } : name === 'skills' ? currentSkills : undefined },
+      assertSource: (value: string) => { if (value !== revision) throw new Error('source changed'); },
+      getContext: () => ({ configured: true, registryUrl: 'https://registry.example' }),
+    });
+    const key = (await service.listInstalled('source', new AbortController().signal)).items[0].itemKey;
+    await run({ use: (signal = new AbortController().signal, selected = key) => service.prepareSkillUse('source', selected, signal),
+      key, directory, observations: () => observations, setLookup: value => { lookup = value; }, change: kind => {
+        if (kind === 'source') revision = 'other';
+        if (kind === 'session') session.id = 'session-b';
+        if (kind === 'cwd') session.header.cwd = home;
+        if (kind === 'agent') currentAgent = { ...agent };
+        if (kind === 'fs') currentFs = { ...fs };
+        if (kind === 'skills') currentSkills = { ...skills };
+        if (kind === 'proxy') currentSkills = { ...skills, [symbols.original]: skills };
+        if (kind === 'missing-skills') currentSkills = undefined;
+        if (kind === 'runtime') service.localRuntime = { ...runtime };
+        if (kind === 'record') items.length = 0;
+        if (kind === 'version') item.version = '2.0.0';
+        if (kind === 'shared') shared = true;
+        if (kind === 'pending') pendingOperations = 1;
+        if (kind === 'dispose') controller.abort();
+      } });
+  } finally {
+    await provider.dispose();
+    if (previousHome === undefined) delete process.env.DSH_HOME; else process.env.DSH_HOME = previousHome;
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+test('use returns actual SKILL.md name, never the market slug or local paths', async () => {
+  await fixture(async f => {
+    expect(await f.use()).toEqual({ status: 'ready', name: 'actual-name', version: '1.2.0', scope: 'user', examples: { state: 'none' } });
+    expect(f.observations()).toBe(2);
+    f.change('proxy'); expect((await f.use()).status).toBe('ready');
+  });
+});
+
+test('unavailable and overridden native winners cannot authorize an invocation', async () => {
+  await fixture(async f => {
+    f.setLookup(async () => undefined);
+    expect(await f.use()).toEqual({ status: 'blocked', reason: 'skill-unavailable' });
+    f.setLookup(async loaded => ({ ...loaded, resourceBase: { kind: 'directory', path: '/other' } }));
+    expect(await f.use()).toEqual({ status: 'blocked', reason: 'skill-shadowed' });
+    f.setLookup(async loaded => ({ ...loaded, content: 'modified winner' }));
+    expect(await f.use()).toEqual({ status: 'blocked', reason: 'skill-shadowed' });
+  });
+});
+
+test('actual user-invocable policy blocks handoff even when model invocation is allowed', async () => {
+  await fixture(async f => {
+    expect(await f.use()).toEqual({ status: 'blocked', reason: 'user-invocation-disabled' });
+  }, 'user-invocable: false\n');
+});
+
+for (const filename of ['SKILL.md', 'references/note.md']) {
+  test(`changed ${filename} is blocked before discovery and after asynchronous lookup`, async () => {
+    await fixture(async f => {
+      f.setLookup(async loaded => { await writeFile(join(f.directory, filename), 'changed'); return loaded; });
+      expect(await f.use()).toEqual({ status: 'blocked', reason: 'files-changed' });
+      expect(await f.use()).toEqual({ status: 'blocked', reason: 'files-changed' });
+      expect(f.observations()).toBe(1);
+    });
+  });
+}
+
+for (const kind of ['source', 'session', 'cwd', 'agent', 'fs', 'skills', 'runtime', 'record', 'version', 'dispose']) {
+  test(`use rejects ${kind} changing during native discovery`, async () => {
+    await fixture(async f => {
+      f.setLookup(async loaded => { f.change(kind); return loaded; });
+      await expect(f.use()).rejects.toThrow();
+    });
+  });
+}
+
+for (const [kind, reason] of [['shared', 'shared-installation'], ['pending', 'operation-pending'], ['missing-skills', 'host-unavailable']] as const) {
+  test(`use blocks ${kind} without reading a native skill`, async () => {
+    await fixture(async f => {
+      f.change(kind); expect(await f.use()).toEqual({ status: 'blocked', reason }); expect(f.observations()).toBe(0);
+    });
+  });
+}
+
+test('stale and forged references and aborted requests never load a skill', async () => {
+  await fixture(async f => {
+    await expect(f.use(AbortSignal.abort())).rejects.toThrow();
+    await expect(f.use(undefined, `${f.key}!`)).rejects.toThrow();
+    f.change('record'); await expect(f.use()).rejects.toThrow(); expect(f.observations()).toBe(0);
+  });
+});
+
+test('winner is checked again after the second filesystem baseline', async () => {
+  await fixture(async f => {
+    let lookups = 0;
+    f.setLookup(async loaded => ++lookups === 1 ? loaded : { ...loaded,
+      resourceBase: { kind: 'directory', path: '/replacement' } });
+    expect(await f.use()).toEqual({ status: 'blocked', reason: 'skill-shadowed' });
+    expect(lookups).toBe(2);
+  });
+});
+
+test('deleted local resources never produce a ready handoff', async () => {
+  await fixture(async f => {
+    f.setLookup(async loaded => { await rm(join(f.directory, 'references/note.md')); return loaded; });
+    expect((await f.use()).status).toBe('blocked');
+  });
+});
+
+test('late native service replacement and cancellation remain errors at the final lookup', async () => {
+  for (const kind of ['skills', 'dispose', 'cwd']) {
+    await fixture(async f => {
+      let lookups = 0;
+      f.setLookup(async loaded => { if (++lookups === 2) f.change(kind); return loaded; });
+      await expect(f.use()).rejects.toThrow();
+      expect(lookups).toBe(2);
+    });
+  }
+});
+
+
+test('an operation becoming pending during final discovery blocks a ready handoff', async () => {
+  await fixture(async f => {
+    let lookups = 0;
+    f.setLookup(async loaded => { if (++lookups === 2) f.change('pending'); return loaded; });
+    expect(await f.use()).toEqual({ status: 'blocked', reason: 'operation-pending' });
+    expect(lookups).toBe(2);
+  });
+});
+
+const multilingual = JSON.stringify({ schemaVersion: 1, defaultLocale: 'zh-CN', examples: {
+  'zh-CN': [{ id: 'summary', title: '会议纪要', prompt: '请使用 {{skill}} 整理会议。' }],
+  en: [{ id: 'summary', title: 'Summary', prompt: 'Use {{skill}} to summarize.' }],
+} });
+test('Host returns exact selected installation examples with raw digest and no path disclosure', async () => {
+  await fixture(async f => {
+    const prepared = await f.use(); expect(prepared.status).toBe('ready');
+    if (prepared.status !== 'ready') throw new Error('must be ready');
+    expect(prepared.name).toBe('actual-name'); expect(prepared.examples.state).toBe('ready');
+    if (prepared.examples.state !== 'ready') throw new Error('must have examples');
+    expect(prepared.examples.digest).toBe(createHash('sha256').update(multilingual).digest('hex'));
+    expect(prepared.examples.items.en?.[0]?.title).toBe('Summary');
+    expect(JSON.stringify(prepared)).not.toContain(f.directory);
+  }, '', multilingual);
+});
+test('invalid packaged examples remain ordinary protected content and retain custom use', async () => {
+  await fixture(async f => {
+    const prepared = await f.use(); expect(prepared.status).toBe('ready');
+    if (prepared.status === 'ready') expect(prepared.examples).toEqual({ state: 'invalid' });
+  }, '', '{not json');
+});
+test('examples modified during native discovery prevent ready even if valid protocol', async () => {
+  await fixture(async f => {
+    f.setLookup(async loaded => { await writeFile(join(f.directory, '.skillhub/examples.json'), multilingual + ' '); return loaded; });
+    expect(await f.use()).toEqual({ status: 'blocked', reason: 'files-changed' });
+  }, '', multilingual);
+});
+
+test('examples changed at final winner lookup are blocked by the last content barrier', async () => {
+  await fixture(async f => {
+    let lookups = 0;
+    f.setLookup(async loaded => { if (++lookups === 2) await writeFile(join(f.directory, '.skillhub/examples.json'), multilingual + ' '); return loaded; });
+    expect(await f.use()).toEqual({ status: 'blocked', reason: 'files-changed' });
+  }, '', multilingual);
+});
diff --git a/plugins/dsh/test/runtime-execution.test.ts b/plugins/dsh/test/runtime-execution.test.ts
index 8819b667b..4f6581e4d 100644
--- a/plugins/dsh/test/runtime-execution.test.ts
+++ b/plugins/dsh/test/runtime-execution.test.ts
@@ -4,6 +4,7 @@ import type { NativeRuntime, NativeInstallExecution, NativeRecoveryResult, Nativ
 
 function native(): NativeRuntime {
   return {
+    readSkillExamples: async () => ({ state: 'none' }),
     observeInstallation: async () => false,
     hostInstanceId: 'fixture', listPending: async () => [], getOperation: async () => undefined,
     acceptInstall: async () => undefined,
diff --git a/plugins/dsh/test/use-skill-context.test.ts b/plugins/dsh/test/use-skill-context.test.ts
new file mode 100644
index 000000000..fd833bc53
--- /dev/null
+++ b/plugins/dsh/test/use-skill-context.test.ts
@@ -0,0 +1,60 @@
+import { expect, test } from 'bun:test';
+import { Context, Service } from '@deepseek-ai/cordis';
+import { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { InputState } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import { captureSkillUse } from '../src/client/use-skill-context.js';
+import { SkillUseController } from '../src/client/use-skill.js';
+
+async function fixture() {
+  const ctx = new Context();
+  const scope = new Context();
+  const binding = {};
+  const listeners = new Set<() => void>();
+  let record = { cwd: '/workspace', retainedBy: { mainView: 1 } };
+  let state: InputState = { draft: '原草稿', draftRev: 1, phase: 'plain', attachmentIds: [], occurrences: [], queue: [] };
+  const input = { state: { getSnapshot: () => state }, focus() {} };
+  class Conversation extends Service { input = { for: () => input }; constructor(ctx: Context) { super(ctx, 'conversation'); } }
+  class Layout extends Service { constructor(ctx: Context) { super(ctx, 'layout'); } selectPanel() {} }
+  const cleanup = [ctx.provide('sessions', {
+    scope: () => scope, binding: () => binding,
+    list: { getSnapshot: () => ({ byId: { [SessionId('session')]: record } }), subscribe: (listener: () => void) => { listeners.add(listener); return () => { listeners.delete(listener); }; } },
+  } as never)];
+  let conversation = ctx.plugin(Conversation); let layout = ctx.plugin(Layout);
+  await conversation; await layout;
+  const actions = { captureInsertion: () => ({ start: 0, end: 0, draftRev: state.draftRev }), insertText: (text: string) => { state = { ...state, draft: text + state.draft, draftRev: state.draftRev + 1 }; return true; } };
+  const controller = new SkillUseController({ capture: (sessionId, actions) => captureSkillUse(ctx, sessionId, actions), revision: async () => 'source',
+    prepare: async () => ({ ok: true, value: { status: 'ready', name: 'verified-name', version: '1', scope: 'project', examples: { state: 'none' } } }), reveal() {} });
+  controller.bind('session', actions);
+  return { ctx, controller, actions, state: () => state, listeners, update: (next: typeof record) => { record = next; for (const listener of listeners) listener(); },
+    replace: async (kind: 'conversation' | 'layout') => {
+      if (kind === 'conversation') { await conversation.dispose(); conversation = ctx.plugin(Conversation); await conversation; }
+      else { await layout.dispose(); layout = ctx.plugin(Layout); await layout; }
+    },
+    cleanup: async () => { controller.dispose(); await conversation.dispose(); await layout.dispose(); for (const remove of cleanup) await remove(); },
+  };
+}
+
+test('real Cordis service facades change identity without blocking native draft preparation', async () => {
+  const f = await fixture();
+  try {
+    expect(f.ctx.get('conversation')).not.toBe(f.ctx.get('conversation'));
+    expect(f.ctx.get('layout')).not.toBe(f.ctx.get('layout'));
+    await f.controller.services('session').useSkill('source', 'item', new AbortController().signal);
+    expect(f.state().draft).toContain('请使用 /verified-name'); expect(f.state().draft).toContain('原草稿');
+    expect(f.listeners.size).toBe(0);
+  } finally { await f.cleanup(); }
+});
+for (const kind of ['conversation', 'layout'] as const) {
+  test(`real Cordis ${kind} replacement invalidates the captured input even if its methods are unchanged`, async () => {
+    const f = await fixture(); const capture = captureSkillUse(f.ctx, 'session', f.actions);
+    try { capture.assertCurrent(); await f.replace(kind); expect(capture.assertCurrent).toThrow('当前会话或输入框已变化'); }
+    finally { capture.dispose?.(); await f.cleanup(); }
+  });
+}
+test('real session subscription latches workspace and main-view changes even after switching back', async () => {
+  for (const change of [{ cwd: '/other', retainedBy: { mainView: 1 } }, { cwd: '/workspace', retainedBy: { mainView: 0 } }]) {
+    const f = await fixture(); const capture = captureSkillUse(f.ctx, 'session', f.actions);
+    try { f.update(change); f.update({ cwd: '/workspace', retainedBy: { mainView: 1 } }); expect(capture.assertCurrent).toThrow(); }
+    finally { capture.dispose?.(); await f.cleanup(); }
+  }
+});
diff --git a/plugins/dsh/test/use-skill-drafts.test.ts b/plugins/dsh/test/use-skill-drafts.test.ts
new file mode 100644
index 000000000..348488c2b
--- /dev/null
+++ b/plugins/dsh/test/use-skill-drafts.test.ts
@@ -0,0 +1,82 @@
+import { expect, test } from 'bun:test';
+import { Context } from '@deepseek-ai/cordis';
+import type { InputState } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import { SkillDraftRetentions } from '../src/client/use-skill-drafts.js';
+
+function fixture() {
+  const ctx = new Context();
+  const listListeners = new Set<() => void>();
+  const records = new Map<string, ReturnType<typeof record>>();
+  function record(draft = '未发送草稿') {
+    let state: InputState = { draft, attachmentIds: [], occurrences: [], draftRev: 1, phase: 'plain', queue: [] };
+    let sessionState = { removed: false, pendingSubmissions: [] as unknown[] };
+    const inputListeners = new Set<() => void>(), sessionListeners = new Set<() => void>();
+    const scope = new Context();
+    const input = { state: { getSnapshot: () => state, subscribe: (listener: () => void) => { inputListeners.add(listener); return () => { inputListeners.delete(listener); }; } } };
+    const session = { getSnapshot: () => sessionState, subscribe: (listener: () => void) => { sessionListeners.add(listener); return () => { sessionListeners.delete(listener); }; } };
+    return { scope, binding: { session }, input, main: 1, refs: 0, releases: 0,
+      state: () => state, update: (value: Partial<InputState>) => { state = { ...state, ...value }; for (const listener of inputListeners) listener(); },
+      pending: (count: number) => { sessionState = { ...sessionState, pendingSubmissions: Array(count).fill({}) }; for (const listener of sessionListeners) listener(); },
+      remove: () => { sessionState = { ...sessionState, removed: true }; for (const listener of sessionListeners) listener(); },
+      listeners: () => inputListeners.size + sessionListeners.size,
+    };
+  }
+  ctx.provide('sessions', {
+    scope: (id: string) => records.get(id)?.scope, binding: (id: string) => records.get(id)?.binding,
+    list: { getSnapshot: () => ({ byId: Object.fromEntries([...records].map(([id, value]) => [id, { retainedBy: { mainView: value.main } }])) }),
+      subscribe: (listener: () => void) => { listListeners.add(listener); return () => { listListeners.delete(listener); }; } },
+    retain: (id: string, options: unknown) => { expect(options).toEqual({ source: 'workspaceOperation' }); const value = records.get(id)!; value.refs++;
+      return { ready: Promise.resolve(value.binding), release: () => { value.refs--; value.releases++; } }; },
+  } as never);
+  ctx.provide('conversation', { input: { for: (scope: Context) => [...records.values()].find(value => value.scope === scope)!.input } } as never);
+  const drafts = new SkillDraftRetentions(ctx);
+  return { drafts, listListeners, add: (id: string, draft?: string) => { const value = record(draft); records.set(id, value); return value; },
+    notify: () => { for (const listener of listListeners) listener(); },
+  };
+}
+test('native origin binding stays retained while away and transfers ownership when mainView returns', () => {
+  const f = fixture(), original = f.add('old');
+  const state = original.state(); f.drafts.preserve('old'); expect(original.refs).toBe(1);
+  original.main = 0; f.notify(); expect(original.refs).toBe(1); expect(original.state()).toBe(state);
+  original.main = 1; f.notify(); expect(original.refs).toBe(0); expect(original.releases).toBe(1);
+  expect(original.listeners()).toBe(0); expect(f.listListeners.size).toBe(0); f.drafts.dispose(); expect(original.releases).toBe(1);
+});
+for (const content of ['attachment', 'reference', 'claimed', 'adjudicating', 'submitting', 'queue', 'pending-submission'] as const) {
+  test(`empty text still protects native ${content} without copying or rewriting it`, () => {
+    const f = fixture(), original = f.add('old', '');
+    if (content === 'attachment') original.update({ attachmentIds: ['native-image-id'] as never });
+    if (content === 'reference') original.update({ occurrences: [{ id: 'native-chip' }] as never });
+    if (content === 'claimed') original.update({ phase: 'claimed', claim: { name: 'command', token: '/command' } });
+    if (content === 'adjudicating' || content === 'submitting') original.update({ phase: content });
+    if (content === 'queue') original.update({ queue: [{}] as never });
+    if (content === 'pending-submission') original.pending(1);
+    const state = original.state(); f.drafts.preserve('old'); original.main = 0; f.notify();
+    expect(original.refs).toBe(1); expect(original.state()).toBe(state); f.drafts.dispose(); expect(original.refs).toBe(0);
+  });
+}
+test('a truly empty origin needs no retained reference', () => {
+  const f = fixture(), original = f.add('old', ''); f.drafts.preserve('old')(); expect(original.refs).toBe(0); expect(original.listeners()).toBe(0); f.drafts.dispose();
+});
+test('cleared draft releases after native submission settlement; a same-turn restored draft stays protected', async () => {
+  const f = fixture(), original = f.add('old'); f.drafts.preserve('old'); original.main = 0; f.notify();
+  original.update({ draft: '' }); original.update({ draft: '发送失败恢复的草稿' }); await Bun.sleep(5); expect(original.refs).toBe(1);
+  original.update({ draft: '' }); original.pending(1); await Bun.sleep(5); expect(original.refs).toBe(1);
+  original.pending(0); await Bun.sleep(5); expect(original.refs).toBe(0); f.drafts.dispose();
+});
+test('navigation failure rollback, session removal and plugin disposal release native references once', () => {
+  const f = fixture(), original = f.add('old'); const rollback = f.drafts.preserve('old'); rollback(); rollback(); expect(original.releases).toBe(1);
+  f.drafts.preserve('old'); original.remove(); expect(original.releases).toBe(2);
+  const other = f.add('other'); f.drafts.preserve('other'); f.drafts.dispose(); f.drafts.dispose(); expect(other.refs).toBe(0); expect(other.releases).toBe(1); expect(f.listListeners.size).toBe(0);
+});
+test('eight protected drafts are bounded without eviction; ninth is rejected and a returned origin frees capacity', () => {
+  const f = fixture(); const originals = Array.from({ length: 9 }, (_, i) => f.add(`old-${i}`));
+  for (let i = 0; i < 8; i++) { f.drafts.preserve(`old-${i}`); originals[i]!.main = 0; f.notify(); }
+  expect(() => f.drafts.preserve('old-8')).toThrow('8 个对话'); expect(originals.slice(0, 8).every(value => value.refs === 1)).toBe(true); expect(originals[8]!.refs).toBe(0);
+  originals[0]!.main = 1; f.notify(); f.drafts.preserve('old-8'); expect(originals[8]!.refs).toBe(1); f.drafts.dispose(); expect(originals.every(value => value.refs === 0)).toBe(true);
+});
+
+
+test('replacement of the actual original scope releases its retained generation', () => {
+  const f = fixture(), original = f.add('old'); f.drafts.preserve('old'); original.main = 0; f.notify();
+  f.add('old'); f.notify(); expect(original.refs).toBe(0); expect(original.releases).toBe(1); expect(original.listeners()).toBe(0); f.drafts.dispose();
+});
diff --git a/plugins/dsh/test/use-skill-navigation.test.ts b/plugins/dsh/test/use-skill-navigation.test.ts
new file mode 100644
index 000000000..bb4c3912a
--- /dev/null
+++ b/plugins/dsh/test/use-skill-navigation.test.ts
@@ -0,0 +1,71 @@
+import { expect, test } from 'bun:test';
+import { Context } from '@deepseek-ai/cordis';
+import { SessionId } from '@deepseek-ai/dsh-session/types';
+import { newSkillConversation } from '../src/client/use-skill-navigation.js';
+import type { InstalledSkillList } from '../src/host/types.js';
+
+function fixture() {
+  const ctx = new Context(); const scope = new Context(); const binding = {};
+  const listeners = new Set<() => void>(), workspaceListeners = new Set<() => void>();
+  const navigation = new AbortController();
+  let current = true, created = 0, retained = 0, released = 0, opened = '', createFailure = false;
+  let cwd = '/project';
+  const rows = () => ({ old: { cwd: '/project', retainedBy: { mainView: current ? 1 : 0 } }, fresh: { cwd, retainedBy: {} } });
+  let onCreate = () => {};
+  ctx.provide('sessions', {
+    scope: () => scope, binding: () => binding,
+    list: { getSnapshot: () => ({ byId: rows() }), subscribe: (listener: () => void) => { listeners.add(listener); return () => { listeners.delete(listener); }; } },
+    create: async (options: unknown) => { expect(options).toEqual({ workspaceId: 'workspace', cwd: '/project' }); created++; onCreate(); if (createFailure) throw new Error('Host unavailable'); return SessionId('fresh'); },
+    retain: (_id: unknown, options: unknown) => { retained++; expect(options).toMatchObject({ source: 'workspaceOperation' }); return { ready: Promise.resolve({}), release: () => { released++; } }; },
+  } as never);
+  ctx.provide('workspaces', { list: { getSnapshot: () => ({ items: [{ workspaceId: 'workspace', sessionIds: [SessionId('old')] }] }), subscribe: (listener: () => void) => { workspaceListeners.add(listener); return () => { workspaceListeners.delete(listener); }; } } } as never);
+  ctx.provide('layout', { beginNavigation: () => navigation.signal } as never);
+  ctx.provide('uiWorkspace', { openSession: (id: string) => { opened = id; } } as never);
+  const original = { itemKey: 'old-key', namespace: 'global', slug: 'writer', version: '1', scope: 'user', state: 'present' } as const;
+  const reads: string[] = [];
+  let fresh = { ...original, itemKey: 'new-key' } as InstalledSkillList['items'][number];
+  const installed = async (id: string): Promise<InstalledSkillList> => { reads.push(id); return { complete: true, unavailable: [], issues: [], items: [id === 'old' ? original : fresh] }; };
+  let preserve = () => () => {};
+  const use = () => newSkillConversation(ctx, 'old', 'source', 'old-key', new AbortController().signal, installed, { preserve: () => preserve() });
+  return { use, reads, listeners, workspaceListeners, preserve: (callback: typeof preserve) => { preserve = callback; }, counts: () => ({ created, retained, released, opened }),
+    create: (callback: () => void) => { onCreate = callback; }, fail: () => { createFailure = true; },
+    supersede: () => navigation.abort(), move: () => { cwd = '/other'; },
+    change: () => { current = false; for (const listener of listeners) listener(); current = true; for (const listener of listeners) listener(); },
+    fresh: (value: Partial<typeof fresh>) => { fresh = { ...fresh, ...value }; },
+  };
+}
+test('fresh same-workspace session remaps the exact user install identity and releases temporary ownership', async () => {
+  const f = fixture(); expect(await f.use()).toEqual({ sessionId: SessionId('fresh'), itemKey: 'new-key' });
+  expect(f.reads).toEqual(['old', 'fresh']); expect(f.counts()).toEqual({ created: 1, retained: 1, released: 1, opened: 'fresh' });
+  expect(f.listeners.size).toBe(0); expect(f.workspaceListeners.size).toBe(0);
+});
+for (const change of [{ version: '2' }, { scope: 'project' }, { slug: 'other' }, { namespace: 'other' }, { state: 'missing' }] as const) {
+  test(`new session cannot substitute changed installation ${JSON.stringify(change)}`, async () => {
+    const f = fixture(); f.fresh(change); await expect(f.use()).rejects.toThrow('安装记录已变化');
+    expect(f.counts().opened).toBe(''); expect(f.counts().released).toBe(1);
+  });
+}
+for (const scenario of ['failure', 'superseded', 'session-ABA', 'wrong-cwd'] as const) {
+  test(`navigation ${scenario} leaves the original view and releases all temporary references`, async () => {
+    const f = fixture();
+    if (scenario === 'failure') f.fail();
+    if (scenario === 'superseded') f.create(f.supersede);
+    if (scenario === 'session-ABA') f.create(f.change);
+    if (scenario === 'wrong-cwd') f.create(f.move);
+    await expect(f.use()).rejects.toThrow();
+    expect(f.counts().opened).toBe(''); expect(f.counts().retained).toBe(f.counts().released);
+    expect(f.listeners.size).toBe(0); expect(f.workspaceListeners.size).toBe(0);
+  });
+}
+
+
+test('protected draft capacity refuses navigation before creating another session', async () => {
+  const f = fixture(); f.preserve(() => { throw new Error('已有 8 个对话保留草稿'); });
+  await expect(f.use()).rejects.toThrow('8 个对话'); expect(f.counts().created).toBe(0); expect(f.counts().opened).toBe('');
+});
+test('native origin draft protection is rechecked immediately before navigation and rolled back on failure', async () => {
+  const f = fixture(); let checks = 0, rollbacks = 0;
+  f.preserve(() => { if (++checks === 2) throw new Error('late attachment cannot be retained'); return () => { rollbacks++; }; });
+  await expect(f.use()).rejects.toThrow('late attachment'); expect(checks).toBe(2); expect(rollbacks).toBe(1);
+  expect(f.counts().opened).toBe(''); expect(f.counts().retained).toBe(f.counts().released);
+});
diff --git a/plugins/dsh/test/use-skill-render.test.tsx b/plugins/dsh/test/use-skill-render.test.tsx
new file mode 100644
index 000000000..bc126b762
--- /dev/null
+++ b/plugins/dsh/test/use-skill-render.test.tsx
@@ -0,0 +1,55 @@
+import { expect, test } from 'bun:test';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { SkillCaseChoices, SkillUseController } from '../src/client/use-skill.js';
+import type { InputState } from '@deepseek-ai/dsh-client-ui-conversation/client';
+
+async function panel(items: { id: string; title: string; prompt: string }[]) {
+  const state: InputState = { draft: '', draftRev: 0, phase: 'plain', attachmentIds: [], occurrences: [], queue: [] };
+  const actions = { captureInsertion: () => ({ start: 0, end: 0, draftRev: 0 }), insertText: () => true };
+  const controller = new SkillUseController({
+    capture: () => ({ actions, input: { state: { getSnapshot: () => state }, focus() {} }, assertCurrent() {} }),
+    revision: async () => 'source', reveal() {},
+    prepare: async () => ({ ok: true, value: { status: 'ready', name: 'native-name', version: '1', scope: 'project',
+      examples: { state: 'ready', digest: 'digest', defaultLocale: 'zh-CN', items: { 'zh-CN': items } } } }),
+  });
+  controller.bind('session', actions);
+  const pending = controller.services('session').useSkill('source', 'item', new AbortController().signal).catch(() => {});
+  await Bun.sleep(0);
+  return { controller, close: async () => { controller.dispose(); await pending; } };
+}
+test('inline cases render contextual header, both task previews and persistent actions outside the task list', async () => {
+  const f = await panel([{ id: 'summary', title: '整理会议', prompt: '请使用 {{skill}} 整理会议。' }, { id: 'compare', title: '对比方案', prompt: '使用 {{skill}} 比较方案。' }]);
+  try {
+    const html = renderToStaticMarkup(<SkillCaseChoices controller={f.controller} sessionId="session" />);
+    expect(html).toContain('aria-label="技能任务案例"'); expect(html).toContain('整理会议'); expect(html).toContain('对比方案');
+    expect(html).toContain('请使用 /native-name 整理会议。'); expect(html).not.toContain('{{skill}}');
+    expect(html).toMatch(/<header>.*aria-label="关闭案例选择"/u);
+    // Long lists scroll independently; actions must not become list items.
+    expect(html).toMatch(/<\/div><footer>.*自定义任务.*填入输入框.*<\/footer>/u);
+    expect(renderToStaticMarkup(<SkillCaseChoices controller={f.controller} sessionId="another-session" />)).toBe('');
+  } finally { await f.close(); }
+});
+test('long multilingual author cases remain plain text without author markup or added executable controls', async () => {
+  const f = await panel(Array.from({ length: 20 }, (_, i) => ({ id: `task-${i}`, title: `<script>任务${i}</script>`, prompt: '<img src=x onerror=alert(1)> {{skill}} '.repeat(8) })));
+  try {
+    const html = renderToStaticMarkup(<SkillCaseChoices controller={f.controller} sessionId="session" />);
+    expect((html.match(/class="astron-sh-case"/gu) ?? []).length).toBe(20);
+    expect(html).toContain('&lt;script&gt;任务19&lt;/script&gt;'); expect(html).not.toContain('<script>'); expect(html).not.toContain('<img');
+    expect((html.match(/<footer>/gu) ?? []).length).toBe(1); expect(html).toContain('自定义任务'); expect(html).toContain('填入输入框');
+  } finally { await f.close(); }
+});
+
+
+test('twenty maximum-length titles and prompts retain complete text for accessibility and selecting the final case', async () => {
+  const items = Array.from({ length: 20 }, (_, i) => ({ id: `long-${i}`, title: (i % 2 ? '极长中文案例标题用于检查窄屏排版' : 'VeryLongUnbrokenExampleTitle').repeat(8).slice(0, 80), prompt: `最后选择${i}：{{skill}} ` + '材料'.repeat(1900) }));
+  const f = await panel(items);
+  try {
+    const html = renderToStaticMarkup(<SkillCaseChoices controller={f.controller} sessionId="session" />);
+    expect((html.match(/class="astron-sh-case"/gu) ?? []).length).toBe(20);
+    expect(html).toContain(items[0]!.title); expect(html).toContain(items[19]!.title);
+    expect(html).toContain('最后选择19：/native-name');
+    // CSS truncates presentation only; the full last prompt remains available to the choice controller.
+    expect(f.controller.casePanel()?.items[19]).toEqual(items[19]!);
+    f.controller.casePanel()!.finish({ locale: 'zh-CN', id: 'long-19' });
+  } finally { await f.close(); }
+});
diff --git a/plugins/dsh/test/use-skill.test.ts b/plugins/dsh/test/use-skill.test.ts
new file mode 100644
index 000000000..c697d679e
--- /dev/null
+++ b/plugins/dsh/test/use-skill.test.ts
@@ -0,0 +1,386 @@
+import { expect, test } from 'bun:test';
+import type { InputState, TokenSpan } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { SkillUsePreparation, InstalledSkillList, SkillExamples } from '../src/host/types.js';
+import { SkillUseButtonRequests, SkillUseController, exactInstalledSkill, selectExampleLocale, exampleTask, skillTaskInsertion, type SkillUseEnvironment } from '../src/client/use-skill.js';
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((done, fail) => { resolve = done; reject = fail; });
+  return { promise, resolve, reject };
+}
+function fixture(environment: Partial<SkillUseEnvironment> = {}) {
+  let state: InputState = { draft: '原草稿 与引用', draftRev: 3, phase: 'plain', attachmentIds: [], occurrences: [], queue: [] };
+  const original = state;
+  let current = true, revision = 'source', inserted = 0, revealed = 0, focused = 0, released = 0;
+  let result: SkillUsePreparation = { status: 'ready', name: 'actual-name', version: '1.2.0', scope: 'project', examples: { state: 'none' } };
+  let prepare: SkillUseEnvironment['prepare'] = async () => ({ ok: true, value: result });
+  const spans: TokenSpan[] = [];
+  let selection = { start: 0, end: 3 };
+  const actions = {
+    captureInsertion: () => ({ ...selection, draftRev: state.draftRev }),
+    insertText: (text: string, span: TokenSpan) => {
+      spans.push(span);
+      if (span.draftRev !== state.draftRev) return false;
+      state = { ...state, draft: state.draft.slice(0, span.end) + text + state.draft.slice(span.end), draftRev: state.draftRev + 1 }; inserted++; return true;
+    },
+  };
+  const controller = new SkillUseController({
+    capture: () => ({ actions, input: { state: { getSnapshot: () => state }, focus: () => { focused++; } }, assertCurrent: () => { if (!current) throw new Error('stale context'); }, dispose: () => { released++; } }),
+    revision: async () => revision,
+    prepare: (...args) => prepare(...args), reveal: () => { revealed++; }, ...environment,
+  });
+  const unbind = controller.bind('session', actions);
+  return { controller, unbind, actions, original, spans, use: () => controller.services('session').useSkill('source', 'item', new AbortController().signal),
+    released: () => released, counts: () => ({ inserted, revealed, focused }), state: () => state,
+    position: (start: number, end = start) => { selection = { start, end }; },
+    content: (value: Partial<InputState>) => { state = { ...state, ...value, draftRev: state.draftRev + 1 }; },
+    edit: (draft = '用户的新草稿') => { state = { ...state, draft, draftRev: state.draftRev + 1 }; },
+    invalidate: () => { current = false; }, source: (value: string) => { revision = value; }, phase: (value: InputState['phase']) => { state = { ...state, phase: value }; },
+    prepare: (value: SkillUseEnvironment['prepare']) => { prepare = value; }, blocked: (reason: Extract<SkillUsePreparation, { status: 'blocked' }>['reason']) => { result = { status: 'blocked', reason }; },
+  };
+}
+test('native insertion collapses selection, preserves existing content and attachment/reference objects, never sends', async () => {
+  const f = fixture(); await f.use();
+  expect(f.spans).toEqual([{ start: 3, end: 3, draftRev: 3 }]);
+  expect(f.state().draft).toContain('请使用 /actual-name');
+  expect(f.state().draft.replace(/\n请使用.*\n/u, '')).toBe(f.original.draft);
+  expect(f.state().attachmentIds).toBe(f.original.attachmentIds); expect(f.state().occurrences).toBe(f.original.occurrences);
+  expect(f.counts()).toEqual({ inserted: 1, revealed: 1, focused: 0 });
+  f.controller.focus('another'); expect(f.counts().focused).toBe(0);
+  f.controller.focus('session'); expect(f.counts().focused).toBe(1);
+  await f.use(); expect(f.counts().inserted).toBe(1); f.controller.dispose();
+});
+test('edited draft fails CAS without replacing text or navigating', async () => {
+  const f = fixture(); const gate = deferred<void>(); f.prepare(async () => { await gate.promise; return { ok: true, value: { status: 'ready', name: 'actual-name', version: '1', scope: 'user', examples: { state: 'none' } } }; });
+  const use = f.use(); await Promise.resolve(); await Promise.resolve(); f.edit(); gate.resolve();
+  await expect(use).rejects.toThrow('草稿已被编辑'); expect(f.state().draft).toBe('用户的新草稿'); expect(f.counts().revealed).toBe(0);
+});
+for (const reason of ['installation-unverified', 'operation-pending', 'shared-installation', 'files-changed', 'skill-unavailable', 'skill-shadowed', 'user-invocation-disabled', 'unsupported-name', 'host-unavailable'] as const) {
+  test(`blocked ${reason} leaves native draft intact`, async () => { const f = fixture(); f.blocked(reason); await expect(f.use()).rejects.toThrow(); expect(f.state()).toBe(f.original); expect(f.counts().inserted).toBe(0); });
+}
+for (const phase of ['claimed', 'adjudicating', 'submitting'] as const) {
+  test(`busy ${phase} refuses before remote verification`, async () => { const f = fixture(); f.phase(phase); f.prepare(() => { throw new Error('must not call'); }); await expect(f.use()).rejects.toThrow('命令'); expect(f.counts().inserted).toBe(0); });
+}
+for (const change of ['session/cwd/binding', 'source-ABA', 'unmount', 'dispose'] as const) {
+  test(`${change} while preparing never writes a draft`, async () => {
+    const f = fixture(); const gate = deferred<void>();
+    f.prepare(async () => { await gate.promise; return { ok: true, value: { status: 'ready', name: 'actual-name', version: '1', scope: 'project', examples: { state: 'none' } } }; });
+    const use = f.use(); await Promise.resolve(); await Promise.resolve();
+    if (change === 'session/cwd/binding') f.invalidate(); if (change === 'source-ABA') f.source('new-revision-even-if-same-url');
+    if (change === 'unmount') f.unbind(); if (change === 'dispose') f.controller.dispose(); gate.resolve();
+    await expect(use).rejects.toThrow(); expect(f.state()).toBe(f.original); expect(f.counts().inserted).toBe(0);
+  });
+}
+test('success receipt inventory read captures selection before awaiting, so concurrent edits are preserved', async () => {
+  const f = fixture(); const gate = deferred<string>();
+  const use = f.controller.services('session').useSkill('source', undefined, new AbortController().signal, () => gate.promise);
+  await Promise.resolve(); f.edit(); gate.resolve('fresh-item'); await expect(use).rejects.toThrow('草稿已被编辑'); expect(f.state().draft).toBe('用户的新草稿');
+});
+test('cancelled request and unbound composer never insert', async () => {
+  const f = fixture(); const signal = AbortSignal.abort(); await expect(f.controller.services('session').useSkill('source', 'item', signal)).rejects.toThrow();
+  f.unbind(); await expect(f.use()).rejects.toThrow('打开当前会话'); expect(f.counts().inserted).toBe(0);
+});
+test('receipt resolves exact version and scope, never a later or historical installation', () => {
+  const item = { itemKey: 'fresh', namespace: 'global', slug: 'writer', scope: 'user', version: '2', state: 'present' } as const;
+  const inventory: InstalledSkillList = { items: [item, { ...item, scope: 'project', version: '1', itemKey: 'project' }], complete: true, issues: [], unavailable: [] };
+  expect(exactInstalledSkill(inventory, item)?.itemKey).toBe('fresh');
+  expect(exactInstalledSkill(inventory, { ...item, version: '1' })).toBeUndefined();
+  expect(exactInstalledSkill({ ...inventory, complete: false }, item)).toBeUndefined();
+  expect(exactInstalledSkill({ ...inventory, unavailable: ['user'] }, item)).toBeUndefined();
+});
+
+test('native capture exceptions release context subscriptions and never edit', async () => {
+  const f = fixture(); f.actions.captureInsertion = () => { throw new Error('native editor unavailable'); };
+  await expect(f.use()).rejects.toThrow('native editor unavailable'); expect(f.released()).toBe(1); expect(f.counts().inserted).toBe(0);
+});
+
+test('deduplication still refuses a concurrently edited draft even when it now includes the skill token', async () => {
+  const f = fixture(); const gate = deferred<void>();
+  f.prepare(async () => { await gate.promise; return { ok: true, value: { status: 'ready', name: 'actual-name', version: '1', scope: 'project', examples: { state: 'none' } } }; });
+  const use = f.use(); await Promise.resolve(); await Promise.resolve();
+  f.edit('用户的新草稿 /actual-name'); gate.resolve();
+  await expect(use).rejects.toThrow('草稿已被编辑'); expect(f.state().draft).toBe('用户的新草稿 /actual-name'); expect(f.counts().revealed).toBe(0);
+});
+test('changing an entry target resets busy state and stale completion cannot overwrite the new request', async () => {
+  const requests = new SkillUseButtonRequests(); const old = deferred<void>(), fresh = deferred<void>();
+  let oldSignal: AbortSignal | undefined; let used = 0;
+  const first = requests.run(signal => { oldSignal = signal; return old.promise; }, () => { used++; });
+  expect(requests.getSnapshot().busy).toBe(true);
+  requests.reset(); expect(oldSignal?.aborted).toBe(true); expect(requests.getSnapshot()).toEqual({ busy: false, error: '' });
+  const second = requests.run(() => fresh.promise, () => { used++; });
+  old.resolve(); await first; expect(used).toBe(0); expect(requests.getSnapshot().busy).toBe(true);
+  fresh.resolve(); await second; expect(used).toBe(1); expect(requests.getSnapshot()).toEqual({ busy: false, error: '' });
+});
+test('stale request rejection cannot expose errors or disable a replacement entry', async () => {
+  const requests = new SkillUseButtonRequests(); const old = deferred<void>();
+  const first = requests.run(() => old.promise); requests.reset();
+  old.reject(new Error('old target error')); await first; expect(requests.getSnapshot()).toEqual({ busy: false, error: '' });
+  await requests.run(async () => { throw new Error('current error'); }); expect(requests.getSnapshot().error).toBe('current error');
+  requests.reset(); expect(requests.getSnapshot()).toEqual({ busy: false, error: '' });
+});
+
+const caseDocument: Extract<SkillExamples, { state: 'ready' }> = {
+  state: 'ready', digest: 'digest', defaultLocale: 'zh-CN', items: {
+    'zh-CN': [{ id: 'summary', title: '整理会议', prompt: '使用 {{skill}} 整理；再用 {{skill}} 检查 {{other}}。' }],
+    en: [{ id: 'summary', title: 'Summary', prompt: 'Summarize notes.' }],
+    'zh-Hant': [],
+  },
+};
+const caseReady = (examples: SkillExamples = caseDocument): SkillUsePreparation => ({ status: 'ready', name: 'actual-name', scope: 'project', version: '1.2.0', examples });
+test('locale exact/parent/default selection respects explicit empty and authored key case', () => {
+  expect(selectExampleLocale(caseDocument, 'EN')).toBe('en');
+  expect(selectExampleLocale(caseDocument, 'zh-Hant-TW')).toBe('zh-Hant');
+  expect(selectExampleLocale(caseDocument, 'ja')).toBe('zh-CN');
+  expect(selectExampleLocale({ ...caseDocument, defaultLocale: 'zh-cn' })).toBe('zh-CN');
+  expect(selectExampleLocale(caseDocument, 'zh-TW')).toBe('zh-CN');
+});
+test('only exact placeholders expand, all occurrences use native name, no expression evaluation', () => {
+  expect(exampleTask('{{skill}} {{other}} {{skill}}', 'native-name', '')).toBe('/native-name {{other}} /native-name');
+  expect(exampleTask('整理材料', 'native-name', '')).toBe('请使用 /native-name 完成本次任务。\n整理材料');
+  expect(exampleTask('整理材料', 'native-name', '已选 /native-name')).toBe('整理材料');
+});
+test('case panel waits without editing then inserts selected fresh prompt preserving draft objects', async () => {
+  const f = fixture(); let preparations = 0;
+  f.prepare(async () => { preparations++; return { ok: true, value: caseReady() }; });
+  const selected = deferred<{ locale: string; id: string }>(); let shown = false;
+  const use = f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined,
+    async (items, locale) => { shown = true; expect(items[0]?.title).toBe('整理会议'); expect(locale).toBe('zh-CN'); return selected.promise; });
+  await Bun.sleep(0); expect(shown).toBe(true); expect(f.counts().inserted).toBe(0); expect(f.spans).toEqual([]);
+  f.edit('用户在选择时补充材料 /actual-name');
+  selected.resolve({ locale: 'zh-CN', id: 'summary' }); await use;
+  expect(preparations).toBe(2); expect(f.state().draft).toContain('使用 /actual-name 整理；再用 /actual-name 检查 {{other}}。');
+  expect(f.state().attachmentIds).toBe(f.original.attachmentIds); expect(f.counts().inserted).toBe(1);
+});
+for (const change of ['digest', 'version', 'scope', 'name', 'id'] as const) {
+  test(`case ${change} change at final preparation prevents insertion`, async () => {
+    const f = fixture(); let calls = 0;
+    f.prepare(async () => {
+      const result = caseReady(); if (++calls === 2 && result.status === 'ready') {
+        if (change === 'digest') result.examples = { ...caseDocument, digest: 'new' };
+        if (change === 'id') result.examples = { ...caseDocument, items: { 'zh-CN': [] } };
+        if (change === 'version') result.version = '2'; if (change === 'scope') result.scope = 'user'; if (change === 'name') result.name = 'other';
+      }
+      return { ok: true, value: result };
+    });
+    await expect(f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined,
+      async () => ({ locale: 'zh-CN', id: 'summary' }))).rejects.toThrow();
+    expect(f.state()).toBe(f.original); expect(f.counts().revealed).toBe(0);
+  });
+}
+test('final case preparation CAS rejects edits after confirmation', async () => {
+  const f = fixture(); const gate = deferred<void>(); let calls = 0;
+  f.prepare(async () => { if (++calls === 2) await gate.promise; return { ok: true, value: caseReady() }; });
+  const use = f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async () => ({ locale: 'zh-CN', id: 'summary' }));
+  await Bun.sleep(0); f.edit('final user edit'); gate.resolve(); await expect(use).rejects.toThrow('草稿已被编辑'); expect(f.state().draft).toBe('final user edit');
+});
+test('cancelled selection never edits, and custom selection is reverified without author prompt', async () => {
+  const f = fixture(); f.prepare(async () => ({ ok: true, value: caseReady() }));
+  await expect(f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async () => { throw new Error('cancel'); })).rejects.toThrow('cancel');
+  expect(f.counts().inserted).toBe(0);
+  await f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async () => ({ custom: true }));
+  expect(f.state().draft).toContain('请补充任务目标和输入材料'); expect(f.state().draft).not.toContain('检查 {{other}}');
+});
+
+test('explicit empty locale skips case selector, unavailable is distinct and custom remains verified', async () => {
+  const f = fixture({ locale: () => 'zh-Hant-TW' }); f.prepare(async () => ({ ok: true, value: caseReady() }));
+  await f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async () => { throw new Error('must not show empty'); });
+  expect(f.counts().inserted).toBe(1);
+  const g = fixture(); let reads = 0; g.prepare(async () => { reads++; return { ok: true, value: caseReady({ state: 'unavailable', retryable: true }) }; });
+  await g.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async (items, locale) => { expect(items).toEqual([]); expect(locale).toBe(''); return { custom: true }; });
+  expect(reads).toBe(2); expect(g.counts().inserted).toBe(1);
+});
+test('Host locale change cancels pending case choice even when language switches back', async () => {
+  let language = 'zh-CN'; let changed: (() => void) | undefined; let stopped = false;
+  const f = fixture({ locale: () => language, subscribeLocale: callback => { changed = callback; return () => { stopped = true; }; } });
+  f.prepare(async () => ({ ok: true, value: caseReady() }));
+  const use = f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async (_items, _locale, signal) => {
+    language = 'en'; changed?.(); language = 'zh-CN'; expect(signal.aborted).toBe(true); return { custom: true };
+  });
+  await expect(use).rejects.toThrow(); expect(stopped).toBe(true); expect(f.counts().inserted).toBe(0);
+});
+
+test('resident inline selection survives entry abort; confirmation preserves new composer edits', async () => {
+  const f = fixture(); f.prepare(async () => ({ ok: true, value: caseReady() }));
+  const origin = new AbortController();
+  const use = f.controller.services('session').useSkill('source', 'item', origin.signal);
+  await Bun.sleep(0);
+  const panel = f.controller.casePanel(); expect(panel?.name).toBe('actual-name'); expect(f.counts().inserted).toBe(0);
+  origin.abort(); f.edit('selection time edit');
+  panel!.finish({ locale: 'zh-CN', id: 'summary' }); await use;
+  expect(f.state().draft.replace(/\n使用.*\n/u, '')).toBe('selection time edit'); expect(f.state().draft).toContain('/actual-name');
+  expect(f.controller.casePanel()).toBeUndefined();
+});
+test('closing resident cases leaves draft unchanged and releases subscriptions', async () => {
+  const f = fixture(); f.prepare(async () => ({ ok: true, value: caseReady() }));
+  const use = f.use(); await Bun.sleep(0); f.controller.casePanel()!.finish();
+  await expect(use).rejects.toThrow('已取消'); expect(f.state()).toBe(f.original); expect(f.released()).toBe(1);
+});
+test('context release cancels pending resident case promise without inserting', async () => {
+  let changed: (() => void) | undefined;
+  const f = fixture({ subscribeContext: listener => { changed = listener; return () => { changed = undefined; }; } });
+  f.prepare(async () => ({ ok: true, value: caseReady() }));
+  const use = f.use(); await Bun.sleep(0); f.invalidate(); changed!();
+  await expect(use).rejects.toThrow(); expect(f.controller.casePanel()).toBeUndefined(); expect(f.counts().inserted).toBe(0); expect(changed).toBeUndefined();
+});
+test('duplicate concurrent conversation use cannot replace another pending case chooser', async () => {
+  const f = fixture(); f.prepare(async () => ({ ok: true, value: caseReady() }));
+  const use = f.use(); await Bun.sleep(0); const panel = f.controller.casePanel();
+  await expect(f.use()).rejects.toThrow('当前技能'); expect(f.controller.casePanel()).toBe(panel);
+  panel!.finish({ custom: true }); await use;
+});
+test('catalog handoff deduplicates creation, binds target only and ignores old entry unmount after navigation', async () => {
+  const created = deferred<{ sessionId: string; itemKey: string }>(); const origin = new AbortController();
+  let creations = 0; const prepared: string[][] = [];
+  const f = fixture({ newConversation: async (_session, _revision, _key, signal) => { creations++; expect(signal.aborted).toBe(false); return created.promise; },
+    prepare: async (session, _revision, key) => { prepared.push([session, key]); return { ok: true, value: caseReady() }; } });
+  const use = f.controller.catalogServices('session').useSkill('source', 'old-key', origin.signal);
+  const repeated = f.controller.catalogServices('session').useSkill('source', 'old-key', origin.signal);
+  expect(creations).toBe(1);
+  f.controller.bind('new', f.actions); created.resolve({ sessionId: 'new', itemKey: 'fresh-key' }); origin.abort();
+  await Bun.sleep(0); expect(f.controller.casePanel()?.sessionId).toBe('new');
+  f.controller.casePanel()!.finish({ locale: 'zh-CN', id: 'summary' }); await Promise.all([use, repeated]);
+  expect(prepared).toEqual([['new', 'fresh-key'], ['new', 'fresh-key']]);
+});
+test('catalog create failure preserves old draft and never prepares or inserts', async () => {
+  const f = fixture({ newConversation: async () => { throw new Error('新对话创建失败'); } });
+  await expect(f.controller.catalogServices('session').useSkill('source', 'old-key', new AbortController().signal)).rejects.toThrow('创建失败');
+  expect(f.state()).toBe(f.original); expect(f.counts().inserted).toBe(0);
+});
+test('catalog navigation superseded before composer binds never writes to the target or old draft', async () => {
+  const f = fixture({ newConversation: async () => ({ sessionId: 'not-current', itemKey: 'new' }), current: () => false });
+  await expect(f.controller.catalogServices('session').useSkill('source', 'old-key', new AbortController().signal)).rejects.toThrow('变化');
+  expect(f.state()).toBe(f.original);
+});
+
+test('post-navigation skill verification failure is visible in the resident composer, not a vanished catalog button', async () => {
+  const f = fixture({ newConversation: async () => ({ sessionId: 'fresh', itemKey: 'new-key' }),
+    prepare: async () => ({ ok: true, value: { status: 'blocked', reason: 'skill-shadowed' } }) });
+  f.controller.bind('fresh', f.actions);
+  await expect(f.controller.catalogServices('session').useSkill('source', 'old-key', new AbortController().signal)).rejects.toThrow('同名');
+  expect(f.controller.casePanel()).toMatchObject({ sessionId: 'fresh', busy: false }); expect(f.controller.casePanel()?.error).toContain('同名');
+  expect(f.state()).toBe(f.original); f.controller.casePanel()!.finish(); expect(f.controller.casePanel()).toBeUndefined();
+});
+test('disposing the plugin cancels both a pending composer acquisition and a pending inline choice', async () => {
+  const f = fixture({ newConversation: async () => ({ sessionId: 'not-bound', itemKey: 'new-key' }) });
+  const waiting = f.controller.catalogServices('session').useSkill('source', 'old-key', new AbortController().signal);
+  await Bun.sleep(0); f.controller.dispose(); await expect(waiting).rejects.toThrow(); expect(f.counts().inserted).toBe(0);
+  const g = fixture(); g.prepare(async () => ({ ok: true, value: caseReady() }));
+  const choosing = g.use(); await Bun.sleep(0); g.controller.dispose(); await expect(choosing).rejects.toThrow(); expect(g.counts().inserted).toBe(0);
+});
+
+for (const mode of ['case', 'custom', 'custom-with-image'] as const) {
+  test(`empty new conversation ${mode} starts with the task, not a synthetic blank paragraph`, async () => {
+    const f = fixture(); f.edit(''); f.position(0);
+    if (mode === 'custom-with-image') f.content({ attachmentIds: ['native-image'] as never });
+    const attachments = f.state().attachmentIds;
+    if (mode === 'case') {
+      f.prepare(async () => ({ ok: true, value: caseReady() }));
+      await f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async () => ({ locale: 'zh-CN', id: 'summary' }));
+      expect(f.state().draft).toBe('使用 /actual-name 整理；再用 /actual-name 检查 {{other}}。');
+    } else {
+      await f.use(); expect(f.state().draft).toBe('请使用 /actual-name 完成本次任务。请补充任务目标和输入材料。');
+    }
+    expect(f.state().draft.startsWith('\n')).toBe(false); expect(f.state().draft.endsWith('\n')).toBe(false);
+    expect(f.state().attachmentIds).toBe(attachments); expect(f.spans[0]).toMatchObject({ start: 0, end: 0 });
+  });
+}
+for (const [draft, start, end, expected] of [
+  ['已有材料', 4, 4, '已有材料\nTASK'],
+  ['已有材料\n', 5, 5, '已有材料\nTASK'],
+  ['已有材料\n\n', 6, 6, '已有材料\n\nTASK'],
+  ['前文后文', 1, 2, '前文\nTASK\n后文'],
+  ['前文\n后文', 1, 2, '前文\nTASK\n后文'],
+  ['前文\n后文', 2, 3, '前文\nTASK\n后文'],
+  ['后文', 0, 0, 'TASK\n后文'],
+] as const) {
+  test(`native selection ${start}-${end} in ${JSON.stringify(draft)} adds only missing separators`, async () => {
+    const f = fixture(); f.edit(draft); f.position(start, end);
+    const examples = { ...caseDocument, items: { 'zh-CN': [{ id: 'task', title: '任务', prompt: 'TASK {{skill}}' }] } };
+    f.prepare(async () => ({ ok: true, value: caseReady(examples) }));
+    const rev = f.state().draftRev;
+    await f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async () => ({ locale: 'zh-CN', id: 'task' }));
+    expect(f.state().draft).toBe(expected.replace('TASK', 'TASK /actual-name')); expect(f.spans[0]).toEqual({ start: end, end, draftRev: rev });
+  });
+}
+test('author prompt whitespace remains literal; separators never trim or normalize its body', () => {
+  const empty = { draft: '', occurrences: [] };
+  expect(skillTaskInsertion('\n  TASK  \n', empty, 0)).toBe('\n  TASK  \n');
+  expect(skillTaskInsertion('\nTASK\n', { draft: 'beforeafter', occurrences: [] }, 6)).toBe('\nTASK\n');
+});
+test('native chip detect boundaries differ from expanded clipboard text without changing insertion spans', async () => {
+  const occurrence = { occurrenceId: 1, source: 'files', ref: 'id', offset: 0, length: 21, label: 'input.txt', clipboardText: '@very-long-input-file' };
+  const draft = occurrence.clipboardText + '\n'; occurrence.length = occurrence.clipboardText.length;
+  expect(skillTaskInsertion('TASK', { draft, occurrences: [occurrence] }, 2)).toBe('TASK');
+  expect(skillTaskInsertion('TASK', { draft, occurrences: [occurrence] }, 1)).toBe('\nTASK');
+  expect(skillTaskInsertion('TASK', { draft, occurrences: [occurrence] }, 0)).toBe('TASK\n');
+  const f = fixture(); f.content({ draft, occurrences: [occurrence], attachmentIds: ['image'] as never }); f.position(1, 2);
+  const references = f.state().occurrences, images = f.state().attachmentIds; const rev = f.state().draftRev;
+  let text = '', received: TokenSpan | undefined;
+  f.actions.insertText = (value, span) => { text = value; received = span; return true; };
+  await f.use(); expect(text).toBe('请使用 /actual-name 完成本次任务。请补充任务目标和输入材料。');
+  expect(received).toEqual({ start: 2, end: 2, draftRev: rev }); expect(f.state().draft).toBe(draft);
+  expect(f.state().occurrences).toBe(references); expect(f.state().attachmentIds).toBe(images);
+});
+
+
+test('separator-only projection handles multiple native refs, emoji and Chinese without moving the captured boundary', () => {
+  const a = '@很长的输入文件.md', b = '@另一个文件.txt';
+  const first = { occurrenceId: 1, source: 'files', ref: 'one', offset: 3, length: a.length, label: 'one', clipboardText: a };
+  const second = { ...first, occurrenceId: 2, ref: 'two', offset: 3 + a.length + 2, length: b.length, label: 'two', clipboardText: b };
+  const state = { draft: `前😀${a}中\n${b}\n尾`, occurrences: [first, second] };
+  for (const [at, expected] of [[0, 'TASK\n'], [3, '\nTASK\n'], [4, '\nTASK\n'], [6, 'TASK\n'], [7, '\nTASK'], [8, 'TASK\n'], [9, '\nTASK']] as const) {
+    expect(skillTaskInsertion('TASK', state, at)).toBe(expected);
+  }
+  const end = { draft: `前😀${a}中\n${b}\n`, occurrences: [first, second] };
+  expect(skillTaskInsertion('TASK', end, 8)).toBe('TASK');
+  expect(end.occurrences[0]).toBe(first); expect(end.occurrences[1]).toBe(second);
+});
+test('selected authored leading and trailing newlines remain intact in an empty new conversation', async () => {
+  const f = fixture(); f.edit(''); f.position(0);
+  f.prepare(async () => ({ ok: true, value: caseReady({ ...caseDocument, items: { 'zh-CN': [{ id: 'spaced', title: '作者排版', prompt: '\n  {{skill}} 完成任务  \n' }] } }) }));
+  await f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, async () => ({ locale: 'zh-CN', id: 'spaced' }));
+  expect(f.state().draft).toBe('\n  /actual-name 完成任务  \n');
+});
+
+test('verified modal entry hands off after detaching its abort signal and before showing resident case choices', async () => {
+  const f = fixture(); const entry = new AbortController(); let preparations = 0, closed = false;
+  f.prepare(async () => { preparations++; return { ok: true, value: caseReady() }; });
+  const request = f.controller.services('session').useSkill('source', 'item', entry.signal, undefined, undefined, () => {
+    expect(preparations).toBe(1); expect(f.counts().inserted).toBe(0); expect(f.controller.casePanel()).toBeUndefined();
+    closed = true; entry.abort();
+  });
+  await Bun.sleep(0); expect(closed).toBe(true); expect(entry.signal.aborted).toBe(true);
+  expect(f.controller.casePanel()?.name).toBe('actual-name'); expect(f.counts().inserted).toBe(0);
+  f.controller.casePanel()!.finish({ locale: 'zh-CN', id: 'summary' }); await request;
+  expect(preparations).toBe(2); expect(f.counts().inserted).toBe(1);
+});
+test('modal entry remains open until initial verification resolves; failed verification never invokes handoff', async () => {
+  const f = fixture(); const gate = deferred<void>(); let closed = false;
+  f.prepare(async () => { await gate.promise; return { ok: true, value: { status: 'blocked', reason: 'files-changed' } }; });
+  const request = f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, undefined, () => { closed = true; });
+  await Bun.sleep(0); expect(closed).toBe(false); expect(f.controller.casePanel()).toBeUndefined();
+  gate.resolve(); await expect(request).rejects.toThrow('文件'); expect(closed).toBe(false); expect(f.counts().inserted).toBe(0);
+});
+test('case cancellation after modal handoff does not edit or reopen the original detail', async () => {
+  const f = fixture(); f.prepare(async () => ({ ok: true, value: caseReady() }));
+  const requests = new SkillUseButtonRequests(); let closed = 0, success = 0;
+  const request = requests.run(signal => f.controller.services('session').useSkill('source', 'item', signal, undefined, undefined, () => { closed++; requests.reset(); }), () => { success++; });
+  await Bun.sleep(0); expect(closed).toBe(1); f.controller.casePanel()!.finish(); await request;
+  expect(closed).toBe(1); expect(success).toBe(0); expect(f.state()).toBe(f.original); expect(f.controller.casePanel()).toBeUndefined();
+});
+test('no-case entry uses final success callback and does not close via early handoff', async () => {
+  const f = fixture(); const requests = new SkillUseButtonRequests(); let handoffs = 0, success = 0;
+  await requests.run(signal => f.controller.services('session').useSkill('source', 'item', signal, undefined, undefined, () => { handoffs++; }), () => { success++; });
+  expect(handoffs).toBe(0); expect(success).toBe(1); expect(f.counts().inserted).toBe(1);
+});
+test('modal handoff cannot bypass a session change, and final CAS still protects edits', async () => {
+  const f = fixture(); f.prepare(async () => ({ ok: true, value: caseReady() }));
+  await expect(f.controller.services('session').useSkill('source', 'item', new AbortController().signal, undefined, undefined, () => { f.invalidate(); })).rejects.toThrow();
+  expect(f.controller.casePanel()).toBeUndefined(); expect(f.counts().inserted).toBe(0);
+  const g = fixture(); const entry = new AbortController(), gate = deferred<void>(); let reads = 0;
+  g.prepare(async () => { if (++reads === 2) await gate.promise; return { ok: true, value: caseReady() }; });
+  const request = g.controller.services('session').useSkill('source', 'item', entry.signal, undefined, undefined, () => { entry.abort(); });
+  await Bun.sleep(0); g.controller.casePanel()!.finish({ locale: 'zh-CN', id: 'summary' }); await Bun.sleep(0);
+  g.edit('保留核验期间编辑'); gate.resolve(); await expect(request).rejects.toThrow('草稿已被编辑'); expect(g.state().draft).toBe('保留核验期间编辑');
+});
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SkillPackagePreviewResponse.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SkillPackagePreviewResponse.java
index 18609b7b9..e0867b2b5 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SkillPackagePreviewResponse.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SkillPackagePreviewResponse.java
@@ -1,4 +1,13 @@
 package com.iflytek.skillhub.dto;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.iflytek.skillhub.domain.skill.validation.SkillExamplesSummary.Status;
+
 /** Package defaults only: preview never creates a skill or changes its files. */
-public record SkillPackagePreviewResponse(String name, String displayName, String description, String version) {}
+public record SkillPackagePreviewResponse(String name, String displayName, String description, String version,
+                                          @JsonInclude(JsonInclude.Include.NON_NULL) Status examplesStatus,
+                                          @JsonInclude(JsonInclude.Include.NON_NULL) Integer examplesCount) {
+    public SkillPackagePreviewResponse(String name, String displayName, String description, String version) {
+        this(name, displayName, description, version, null, null);
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillPackagePreviewService.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillPackagePreviewService.java
index 4486f5e0a..8ca0db72b 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillPackagePreviewService.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillPackagePreviewService.java
@@ -4,6 +4,7 @@
 import com.iflytek.skillhub.domain.skill.metadata.SkillMetadata;
 import com.iflytek.skillhub.domain.skill.metadata.SkillMetadataParser;
 import com.iflytek.skillhub.domain.skill.validation.PackageEntry;
+import com.iflytek.skillhub.domain.skill.validation.SkillExamplesSummary;
 import com.iflytek.skillhub.domain.skill.validation.SkillPackageValidator;
 import com.iflytek.skillhub.domain.skill.validation.ValidationResult;
 import com.iflytek.skillhub.dto.SkillPackagePreviewResponse;
@@ -29,6 +30,8 @@ public SkillPackagePreviewResponse preview(List<PackageEntry> entries) {
         PackageEntry skillMd = entries.stream().filter(entry -> "SKILL.md".equals(entry.path())).findFirst()
                 .orElseThrow(() -> new DomainBadRequestException("error.skill.publish.skillMd.notFound"));
         SkillMetadata metadata = parser.parse(new String(skillMd.content(), StandardCharsets.UTF_8));
-        return new SkillPackagePreviewResponse(metadata.name(), metadata.displayName(), metadata.description(), metadata.version());
+        SkillExamplesSummary examples = SkillExamplesSummary.recognize(entries);
+        return new SkillPackagePreviewResponse(metadata.name(), metadata.displayName(), metadata.description(), metadata.version(),
+                examples.status(), examples.count());
     }
 }
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/controller/portal/SkillPackagePreviewSecurityIntegrationTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/controller/portal/SkillPackagePreviewSecurityIntegrationTest.java
index ce8fdce21..a5af773dd 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/controller/portal/SkillPackagePreviewSecurityIntegrationTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/controller/portal/SkillPackagePreviewSecurityIntegrationTest.java
@@ -101,6 +101,21 @@ void browserSessionWithoutCsrfIsRejectedBeforeParsing(String prefix) throws Exce
         verifyNoInteractions(previews);
     }
 
+    @ParameterizedTest
+    @ValueSource(strings = {"/api/v1", "/api/web"})
+    void examplesSummaryUsesOptionalCountAndCompatibleStatusValues(String prefix) throws Exception {
+        given(previews.preview(anyList())).willReturn(new SkillPackagePreviewResponse("foo", "Foo", "Summary", "1.0.0",
+                com.iflytek.skillhub.domain.skill.validation.SkillExamplesSummary.Status.ready, 2));
+        mockMvc.perform(multipart(prefix + "/skills/package-preview").file(archive()).session(session()).with(csrf()))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.data.examplesStatus").value("ready"))
+                .andExpect(jsonPath("$.data.examplesCount").value(2));
+        given(previews.preview(anyList())).willReturn(new SkillPackagePreviewResponse("foo", "Foo", "Summary", "1.0.0",
+                com.iflytek.skillhub.domain.skill.validation.SkillExamplesSummary.Status.invalid, null));
+        mockMvc.perform(multipart(prefix + "/skills/package-preview").file(archive()).session(session()).with(csrf()))
+                .andExpect(status().isOk()).andExpect(jsonPath("$.data.examplesStatus").value("invalid"))
+                .andExpect(jsonPath("$.data.examplesCount").doesNotExist());
+    }
+
     private MockHttpSession session() {
         var context = SecurityContextHolder.createEmptyContext();
         var principal = new PlatformPrincipal(userId, "Preview user", userId + "@example.test", "", "local", Set.of());
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/controller/support/SkillPackageArchiveExtractorTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/controller/support/SkillPackageArchiveExtractorTest.java
index 46dd4f72e..8915cce8b 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/controller/support/SkillPackageArchiveExtractorTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/controller/support/SkillPackageArchiveExtractorTest.java
@@ -28,6 +28,22 @@ void setUp() {
         extractor = new SkillPackageArchiveExtractor(props);
     }
 
+    @Test
+    void wrappedExamplesRemainByteExactAndInstallerRecordIsRejectedAfterRootStripping() throws Exception {
+        byte[] skill = "---\nname: example-skill\ndescription: Summary\n---\nBody".getBytes(StandardCharsets.UTF_8);
+        byte[] examples = "\uFEFF{not-json}".getBytes(StandardCharsets.UTF_8);
+        var validator = new com.iflytek.skillhub.domain.skill.validation.SkillPackageValidator(
+                new com.iflytek.skillhub.domain.skill.metadata.SkillMetadataParser());
+        var valid = extractor.extractWithWarnings(new MockMultipartFile("file", "examples.zip", "application/zip",
+                createZip(Map.of("wrapper/SKILL.md", skill, "wrapper/.skillhub/examples.json", examples))));
+        assertTrue(validator.validate(valid.entries()).passed());
+        var authored = valid.entries().stream().filter(entry -> entry.path().equals(".skillhub/examples.json")).findFirst().orElseThrow();
+        org.junit.jupiter.api.Assertions.assertArrayEquals(examples, authored.content());
+        var invalid = extractor.extractWithWarnings(new MockMultipartFile("file", "private.zip", "application/zip",
+                createZip(Map.of("wrapper/SKILL.md", skill, "wrapper/.SKILLHUB/METADATA.JSON", "{}".getBytes(StandardCharsets.UTF_8)))));
+        assertFalse(validator.validate(invalid.entries()).passed());
+    }
+
     @Test
     void shouldRejectPathTraversalEntry() throws Exception {
         MockMultipartFile file = new MockMultipartFile(
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/dto/RegistryOpenApiSchemaTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/dto/RegistryOpenApiSchemaTest.java
index 9a6648fdd..5ac4ca39f 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/dto/RegistryOpenApiSchemaTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/dto/RegistryOpenApiSchemaTest.java
@@ -10,6 +10,15 @@
 
 class RegistryOpenApiSchemaTest {
 
+    @Test
+    void examplesSummaryFieldsAreOptionalAndStatusIsBounded() {
+        var resolved = ModelConverters.getInstance().resolveAsResolvedSchema(new AnnotatedType(SkillPackagePreviewResponse.class));
+        Schema<?> schema = resolved.schema;
+        assertThat(schema.getRequired()).isNullOrEmpty();
+        assertThat(schema.getProperties().get("examplesStatus").getEnum()).containsExactly("ready", "none", "invalid");
+        assertThat(schema.getProperties()).containsKey("examplesCount");
+    }
+
     @Test
     void resolvedSkillDeclaresEveryInstallationIdentityFieldRequired() {
         var resolved = ModelConverters.getInstance().resolveAsResolvedSchema(
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/SkillPackagePreviewServiceTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/SkillPackagePreviewServiceTest.java
index 95c531d69..c1a2bbc77 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/SkillPackagePreviewServiceTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/SkillPackagePreviewServiceTest.java
@@ -36,6 +36,36 @@ void missingSkillMdCannotBePreviewed() {
                 .isInstanceOf(DomainBadRequestException.class);
     }
 
+    @Test
+    void oldNullableFieldsKeepTheirSerializationContract() throws Exception {
+        String serialized = new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsString(service.preview(entries("")));
+        assertThat(serialized).contains("\"version\":null");
+    }
+
+    @Test
+    void examplesRecognitionIsNonBlockingAndOmitsInvalidCount() throws Exception {
+        assertThat(service.preview(entries("")).examplesCount()).isZero();
+        for (String content : List.of("{not json", "{\"schemaVersion\":1,\"defaultLocale\":\"en\",\"examples\":{\"en\":[]}}")) {
+            var files = new java.util.ArrayList<>(entries(""));
+            byte[] bytes = content.getBytes(StandardCharsets.UTF_8);
+            files.add(new PackageEntry(".skillhub/examples.json", bytes, bytes.length, "application/json"));
+            var response = service.preview(files);
+            assertThat(response.examplesStatus().name()).isEqualTo(content.equals("{not json") ? "invalid" : "none");
+            if (content.equals("{not json")) {
+                assertThat(response.examplesCount()).isNull();
+                assertThat(new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsString(response)).doesNotContain("examplesCount");
+            } else assertThat(response.examplesCount()).isZero();
+            assertThat(files.get(1).content()).containsExactly(bytes);
+        }
+    }
+
+    @Test
+    void previewRejectsInstallerRecordsUsingTheSharedPublishPolicy() {
+        var files = new java.util.ArrayList<>(entries(""));
+        files.add(new PackageEntry(".skillhub/metadata.json", new byte[0], 0, "application/json"));
+        assertThatThrownBy(() -> service.preview(files)).isInstanceOf(DomainBadRequestException.class);
+    }
+
     private List<PackageEntry> entries(String extra) {
         byte[] bytes = ("---\nname: example-skill\ndescription: Summary\n" + extra + "---\nBody").getBytes(StandardCharsets.UTF_8);
         return List.of(new PackageEntry("SKILL.md", bytes, bytes.length, "text/markdown"));
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillExamplesSummary.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillExamplesSummary.java
new file mode 100644
index 000000000..4513d5760
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillExamplesSummary.java
@@ -0,0 +1,101 @@
+package com.iflytek.skillhub.domain.skill.validation;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.nio.ByteBuffer;
+import java.nio.charset.CodingErrorAction;
+import java.nio.charset.StandardCharsets;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Locale;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/** Non-blocking recognition of the immutable, authored examples file. Never rewrites bytes. */
+public record SkillExamplesSummary(Status status, Integer count) {
+    public enum Status { ready, none, invalid }
+
+    private static final ObjectMapper JSON = new ObjectMapper();
+    private static final Pattern ID = Pattern.compile("^[a-z0-9]+(?:-[a-z0-9]+)*$");
+    private static final Pattern NON_WHITESPACE = Pattern.compile(
+            "[^\\u0009-\\u000D\\u0020\\u0085\\u00A0\\u1680\\u2000-\\u200A\\u2028\\u2029\\u202F\\u205F\\u3000\\uFEFF]");
+
+    public static SkillExamplesSummary recognize(List<PackageEntry> entries) {
+        return entries.stream().filter(entry -> SkillPackagePolicy.EXAMPLES_PATH.equals(entry.path()))
+                .findFirst().map(entry -> recognize(entry.content()))
+                .orElseGet(() -> new SkillExamplesSummary(Status.none, 0));
+    }
+
+    public static SkillExamplesSummary recognize(byte[] bytes) {
+        if (bytes.length > 65_536) return invalid();
+        try {
+            String text = StandardCharsets.UTF_8.newDecoder()
+                    .onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT)
+                    .decode(ByteBuffer.wrap(bytes)).toString();
+            if (text.startsWith("\uFEFF")) text = text.substring(1);
+            JsonNode root;
+            try (var parser = JSON.createParser(text)) {
+                root = JSON.readTree(parser);
+                if (parser.nextToken() != null) return invalid();
+            }
+            if (!fields(root, Set.of("schemaVersion", "defaultLocale", "examples"))
+                    || !root.get("schemaVersion").isNumber()
+                    || root.get("schemaVersion").decimalValue().compareTo(java.math.BigDecimal.ONE) != 0) return invalid();
+            JsonNode defaultLocale = root.get("defaultLocale");
+            JsonNode examples = root.get("examples");
+            if (!defaultLocale.isTextual() || !locale(defaultLocale.textValue())
+                    || !examples.isObject() || examples.size() < 1 || examples.size() > 10) return invalid();
+            Set<String> locales = new HashSet<>();
+            int total = 0;
+            var languages = examples.fields();
+            while (languages.hasNext()) {
+                var language = languages.next();
+                if (!locale(language.getKey())
+                        || !locales.add(language.getKey().toLowerCase(Locale.ROOT))) return invalid();
+                JsonNode items = language.getValue();
+                if (!items.isArray() || items.size() > 20) return invalid();
+                Set<String> ids = new HashSet<>();
+                for (JsonNode item : items) {
+                    if (!fields(item, Set.of("id", "title", "prompt"))) return invalid();
+                    JsonNode id = item.get("id");
+                    if (!id.isTextual() || id.textValue().length() > 64
+                            || !ID.matcher(id.textValue()).matches() || !ids.add(id.textValue())
+                            || !text(item.get("title"), 80) || !text(item.get("prompt"), 4000)) return invalid();
+                }
+                total += items.size();
+            }
+            if (!locales.contains(defaultLocale.textValue().toLowerCase(Locale.ROOT))) return invalid();
+            return new SkillExamplesSummary(total == 0 ? Status.none : Status.ready, total);
+        } catch (java.io.IOException | IllegalArgumentException exception) {
+            return invalid();
+        }
+    }
+
+    private static boolean locale(String value) {
+        String[] subtags = value.split("-", -1);
+        if (subtags[0].length() < 2 || subtags[0].length() > 3
+                || !subtags[0].chars().allMatch(code -> code >= 'a' && code <= 'z')) return false;
+        for (int index = 1; index < subtags.length; index++) {
+            String subtag = subtags[index];
+            if (subtag.length() < 2 || subtag.length() > 8 || !subtag.chars().allMatch(code ->
+                    code >= 'a' && code <= 'z' || code >= 'A' && code <= 'Z' || code >= '0' && code <= '9')) return false;
+        }
+        return true;
+    }
+
+    private static boolean fields(JsonNode node, Set<String> expected) {
+        if (node == null || !node.isObject() || node.size() != expected.size()) return false;
+        var fields = node.fieldNames();
+        while (fields.hasNext()) if (!expected.contains(fields.next())) return false;
+        return true;
+    }
+
+    private static boolean text(JsonNode node, int max) {
+        return node.isTextual() && node.textValue().codePointCount(0, node.textValue().length()) <= max
+                && NON_WHITESPACE.matcher(node.textValue()).find();
+    }
+
+    private static SkillExamplesSummary invalid() {
+        return new SkillExamplesSummary(Status.invalid, null);
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackagePolicy.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackagePolicy.java
index ee3880aeb..5f92a7f25 100644
--- a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackagePolicy.java
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackagePolicy.java
@@ -8,6 +8,7 @@
 import java.nio.charset.CodingErrorAction;
 import java.nio.charset.StandardCharsets;
 import java.util.Set;
+import java.util.Locale;
 
 /**
  * Shared package-policy rules for path normalization, extension allowlists, and lightweight file
@@ -18,6 +19,8 @@ public final class SkillPackagePolicy {
     public static final int MAX_FILE_COUNT = 500;
     public static final long MAX_SINGLE_FILE_SIZE = 10 * 1024 * 1024; // 10MB
     public static final long MAX_TOTAL_PACKAGE_SIZE = 100 * 1024 * 1024; // 100MB
+    public static final String INTERNAL_METADATA_PATH = ".skillhub/metadata.json";
+    public static final String EXAMPLES_PATH = ".skillhub/examples.json";
     public static final String SKILL_MD_PATH = "SKILL.md";
     public static final Set<String> ALLOWED_EXTENSIONS = Set.of(
             // Documentation
@@ -67,6 +70,22 @@ public static String normalizeEntryPath(String rawPath) {
         return canonicalizeSkillMdPath(canonical);
     }
 
+    /** Reject Windows aliases before accepting a portable author file path. */
+    public static String portableEntryKey(String normalizedPath) {
+        for (String segment : normalizedPath.split("/")) {
+            if (segment.endsWith(".") || segment.endsWith(" ")
+                    || segment.chars().anyMatch(value -> value < 32 || value == 127)) {
+                throw new IllegalArgumentException("Package entry path has a non-portable alias: " + normalizedPath);
+            }
+        }
+        return normalizedPath.toLowerCase(Locale.ROOT);
+    }
+
+    public static boolean isInternalMetadataPath(String portableKey) {
+        return portableKey.equals(INTERNAL_METADATA_PATH)
+                || portableKey.startsWith(INTERNAL_METADATA_PATH + "/");
+    }
+
     public static String canonicalizeSkillMdPath(String normalizedPath) {
         int slashIndex = normalizedPath.lastIndexOf('/');
         String fileName = slashIndex >= 0 ? normalizedPath.substring(slashIndex + 1) : normalizedPath;
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidator.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidator.java
index d3966ca50..e78776b40 100644
--- a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidator.java
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidator.java
@@ -73,12 +73,24 @@ public ValidationResult validate(List<PackageEntry> entries) {
         List<String> errors = new ArrayList<>();
         List<String> warnings = new ArrayList<>();
         Set<String> normalizedPaths = new HashSet<>();
+        Set<String> portablePaths = new HashSet<>();
         PackageEntry skillMd = null;
 
         for (PackageEntry entry : entries) {
             String normalizedPath;
             try {
                 normalizedPath = SkillPackagePolicy.normalizeEntryPath(entry.path());
+                String portableKey = SkillPackagePolicy.portableEntryKey(normalizedPath);
+                if (SkillPackagePolicy.isInternalMetadataPath(portableKey) || portableKey.equals(".skillhub")) {
+                    errors.add("Installer record .skillhub/metadata.json cannot be published: " + normalizedPath);
+                }
+                if (portableKey.equals(SkillPackagePolicy.EXAMPLES_PATH)
+                        && !normalizedPath.equals(SkillPackagePolicy.EXAMPLES_PATH)) {
+                    errors.add("Ambiguous skill examples path casing: " + normalizedPath);
+                }
+                if (!portablePaths.add(portableKey)) {
+                    errors.add("Duplicate portable package entry path: " + normalizedPath);
+                }
             } catch (IllegalArgumentException e) {
                 errors.add(e.getMessage());
                 continue;
@@ -102,6 +114,17 @@ public ValidationResult validate(List<PackageEntry> entries) {
             }
         }
 
+        for (String path : portablePaths) {
+            int slash = path.indexOf('/');
+            while (slash >= 0) {
+                if (portablePaths.contains(path.substring(0, slash))) {
+                    errors.add("Package entry file/directory conflict: " + path);
+                    break;
+                }
+                slash = path.indexOf('/', slash + 1);
+            }
+        }
+
         // 1. Check SKILL.md exists at root
         if (skillMd == null) {
             errors.add("Missing required file: SKILL.md at root");
diff --git a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/skill/validation/SkillExamplesSummaryTest.java b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/skill/validation/SkillExamplesSummaryTest.java
new file mode 100644
index 000000000..17fac14d2
--- /dev/null
+++ b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/skill/validation/SkillExamplesSummaryTest.java
@@ -0,0 +1,61 @@
+package com.iflytek.skillhub.domain.skill.validation;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+class SkillExamplesSummaryTest {
+    private SkillExamplesSummary parse(String text) { return SkillExamplesSummary.recognize(text.getBytes(StandardCharsets.UTF_8)); }
+    private String document(String examples) { return "{\"schemaVersion\":1,\"defaultLocale\":\"zh-CN\",\"examples\":" + examples + "}"; }
+    private String item(String title) { return "{\"id\":\"summary\",\"title\":\"" + title + "\",\"prompt\":\"Use {{skill}}\"}"; }
+
+    @Test
+    void recognizesNormativeFixturesWithoutChangingBytes() throws Exception {
+        Path root = Path.of("../../openspec/changes/add-dsh-native-plugin/contracts");
+        byte[] valid = Files.readAllBytes(root.resolve("skill-examples.valid.json"));
+        byte[] before = valid.clone();
+        assertThat(SkillExamplesSummary.recognize(valid).status()).isEqualTo(SkillExamplesSummary.Status.ready);
+        assertThat(valid).containsExactly(before);
+        assertThat(SkillExamplesSummary.recognize(Files.readAllBytes(root.resolve("skill-examples.empty.json"))))
+                .isEqualTo(new SkillExamplesSummary(SkillExamplesSummary.Status.none, 0));
+    }
+
+    @Test
+    void countsAllLanguageEntriesIncludingTranslationsAndEmptyDefaultLanguage() {
+        assertThat(parse(document("{\"zh-CN\":[],\"en\":[" + item("English") + "]}")))
+                .isEqualTo(new SkillExamplesSummary(SkillExamplesSummary.Status.ready, 1));
+        assertThat(parse(document("{\"zh-CN\":[" + item("中文") + "],\"en\":[" + item("English") + "]}")).count()).isEqualTo(2);
+        assertThat(SkillExamplesSummary.recognize(List.of()).count()).isZero();
+    }
+
+    @Test
+    void acceptsOneBomAndUsesCodePointsForTextBounds() {
+        assertThat(parse("\uFEFF" + document("{\"zh-CN\":[" + item("😀".repeat(80)) + "]}")).status()).isEqualTo(SkillExamplesSummary.Status.ready);
+        assertInvalid(document("{\"zh-CN\":[" + item("😀".repeat(81)) + "]}"));
+        assertInvalid("\uFEFF\uFEFF" + document("{\"zh-CN\":[]}"));
+    }
+
+    @Test
+    void rejectsUnsupportedStructureAndSemanticAmbiguityWithoutCount() {
+        for (String value : List.of("null", "{}", "[]", "not json",
+                document("{\"zh-CN\":[\"old string\"]}"), document("{\"zh-CN\":[],\"zh-cn\":[]}"), document("{\"en\":[]}"),
+                document("{\"zh-CN\":[" + item("one") + "," + item("two") + "]}"),
+                document("{\"zh-CN\":[" + item("\u0085\uFEFF") + "]}"),
+                document("{\"zh-CN\":[" + item("one").replace("\"prompt\":", "\"extra\":0,\"prompt\":") + "]}"),
+                document("{\"zh-CN\":[]}").replace("schemaVersion\":1", "schemaVersion\":2"),
+                document("{\"zh-CN\":[]}").replace("schemaVersion\":1", "schemaVersion\":1e9999"), document("{\"zh-CN\":[]}") + " {}")) assertInvalid(value);
+        assertThat(SkillExamplesSummary.recognize(new byte[] {(byte) 0xFF}).status()).isEqualTo(SkillExamplesSummary.Status.invalid);
+        assertThat(SkillExamplesSummary.recognize(new byte[65_537]).status()).isEqualTo(SkillExamplesSummary.Status.invalid);
+    }
+    @Test
+    void longButBoundedLocaleTagsDoNotOverflowTheParserStack() {
+        String locale = "en" + "-aa".repeat(5000);
+        String content = "{\"schemaVersion\":1,\"defaultLocale\":\"" + locale
+                + "\",\"examples\":{\"" + locale + "\":[]}}";
+        assertThat(parse(content)).isEqualTo(new SkillExamplesSummary(SkillExamplesSummary.Status.none, 0));
+    }
+    private void assertInvalid(String value) { assertThat(parse(value)).isEqualTo(new SkillExamplesSummary(SkillExamplesSummary.Status.invalid, null)); }
+}
diff --git a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidatorTest.java b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidatorTest.java
index 06e9ad957..bff18f2c8 100644
--- a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidatorTest.java
+++ b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidatorTest.java
@@ -421,6 +421,44 @@ void rejectsSkillWithMissingAstronComplianceEvidenceFile() {
         assertTrue(result.errors().stream().anyMatch(error -> error.contains("does not exist in package")));
     }
 
+    @Test
+    void protectsInternalInstallerRecordIncludingPortableAliases() {
+        for (String path : List.of(".skillhub/metadata.json", ".SKILLHUB/METADATA.JSON", ".skillhub/metadata.json/child.txt",
+                ".skillhub./metadata.json", ".skillhub/metadata.json.", ".skillhub/metadata.json ",
+                ".skillhub\\metadata.json", ".skillhub/./metadata.json", ".skillhub/metadata.json:stream", ".skillhub")) {
+            byte[] content = "{}".getBytes();
+            assertFalse(validator.validate(List.of(skillMdEntry(), new PackageEntry(path, content, content.length, "application/json"))).passed(), path);
+        }
+    }
+
+    @Test
+    void preservesInvalidExamplesAndOtherSafeAuthorFiles() {
+        byte[] invalid = "{not-json".getBytes();
+        var entries = List.of(skillMdEntry(), new PackageEntry(".skillhub/examples.json", invalid, invalid.length, "application/json"),
+                new PackageEntry(".skillhub/notes.txt", invalid, invalid.length, "text/plain"),
+                new PackageEntry("docs/.skillhub/metadata.json", invalid, invalid.length, "application/json"));
+        assertTrue(validator.validate(entries).passed());
+        assertArrayEquals(invalid, entries.get(1).content());
+    }
+
+    @Test
+    void rejectsPortableDuplicatesAndFileDirectoryConflicts() {
+        for (String path : List.of(".skillhub/EXAMPLES.JSON", ".skillhub/examples.json/child.txt")) {
+            byte[] content = "{}".getBytes();
+            assertFalse(validator.validate(List.of(skillMdEntry(),
+                    new PackageEntry(".skillhub/examples.json", content, content.length, "application/json"),
+                    new PackageEntry(path, content, content.length, "application/json"))).passed());
+        }
+    }
+
+    @Test
+    void rejectsCaseAliasesOfTheFixedExamplesPath() {
+        for (String path : List.of(".SKILLHUB/examples.json", ".skillhub/Examples.JSON")) {
+            byte[] content = "{}".getBytes();
+            assertFalse(validator.validate(List.of(skillMdEntry(), new PackageEntry(path, content, content.length, "application/json"))).passed());
+        }
+    }
+
     private PackageEntry skillMdEntry() {
         String skillMdContent = """
             ---
diff --git a/web/src/api/generated/schema.d.ts b/web/src/api/generated/schema.d.ts
index 81a8b7dbd..527ef414c 100644
--- a/web/src/api/generated/schema.d.ts
+++ b/web/src/api/generated/schema.d.ts
@@ -8188,6 +8188,10 @@ export interface components {
             displayName?: string;
             description?: string;
             version?: string;
+            /** @enum {string} */
+            examplesStatus?: "ready" | "none" | "invalid";
+            /** Format: int32 */
+            examplesCount?: number;
         };
         ApiResponseSkillAvatarUploadResponse: {
             /** Format: int32 */
diff --git a/web/src/features/publish/folder-zip.test.ts b/web/src/features/publish/folder-zip.test.ts
index 3568c8068..e51cc4d6e 100644
--- a/web/src/features/publish/folder-zip.test.ts
+++ b/web/src/features/publish/folder-zip.test.ts
@@ -63,6 +63,21 @@ describe('createZipBlob', () => {
 })
 
 describe('collectFolderEntries', () => {
+  it('omits only the selected root installer record and preserves author bytes', async () => {
+    const entries = await collectFolderEntries([
+      fileAt('my-skill/.skillhub/metadata.json', 'private'),
+      fileAt('my-skill/.SKILLHUB/METADATA.JSON', 'alias'),
+      fileAt('my-skill/.skillhub/examples.json', '{invalid'),
+      fileAt('my-skill/.skillhub/notes.txt', 'notes'),
+      fileAt('my-skill/docs/.skillhub/metadata.json', 'author'),
+    ])
+    expect(entries.map(entry => entry.path)).toEqual([
+      'my-skill/.skillhub/examples.json', 'my-skill/.skillhub/notes.txt',
+      'my-skill/docs/.skillhub/metadata.json',
+    ])
+    expect(new TextDecoder().decode(entries[0].data)).toBe('{invalid')
+  })
+
   it('filters junk and sorts remaining files by path', async () => {
     const entries = await collectFolderEntries([
       fileAt('my-skill/scripts/run.sh', 'run'),
diff --git a/web/src/features/publish/folder-zip.ts b/web/src/features/publish/folder-zip.ts
index 5cffe555b..9f5de4d44 100644
--- a/web/src/features/publish/folder-zip.ts
+++ b/web/src/features/publish/folder-zip.ts
@@ -160,6 +160,10 @@ export async function collectFolderEntries(files: File[]): Promise<ZipEntry[]> {
   for (const file of files) {
     const path = (file as File & { webkitRelativePath?: string }).webkitRelativePath || file.name
     if (isIgnoredPath(path)) continue
+    // A folder picker includes one selected-root segment. Only its installer record
+    // is private; nested author resources named metadata.json remain publishable.
+    const relative = path.replace(/\\/g, '/').split('/').slice(path.includes('/') ? 1 : 0).join('/')
+    if (relative.toLowerCase() === '.skillhub/metadata.json') continue
     const data = new Uint8Array(await file.arrayBuffer())
     entries.push({ path, data })
   }
diff --git a/web/src/i18n/locales/en.json b/web/src/i18n/locales/en.json
index d46af54fd..5e6697977 100644
--- a/web/src/i18n/locales/en.json
+++ b/web/src/i18n/locales/en.json
@@ -2229,6 +2229,9 @@
     "displayNamePlaceholder": "For example: Meeting notes assistant",
     "displayNameHelp": "Up to 200 characters. Defaults to the package title. Changes follow this version’s review and do not alter the identifier or package files. Leave blank to use the package title.",
     "readingPackage": "Reading package metadata…",
+    "examplesReady": "Recognized {{count}} task examples across all languages.",
+    "examplesNone": "No task examples provided. Publishing and use remain available.",
+    "examplesInvalid": "Examples format not recognized. The file is kept as an ordinary file and publishing remains available.",
     "packagePreviewFailed": "Unable to read the package. Check SKILL.md and select the package again, or retry.",
     "title": "Publish Skill",
     "subtitle": "Upload skill package to SkillHub",
diff --git a/web/src/i18n/locales/ru.json b/web/src/i18n/locales/ru.json
index 6aaf2e1e1..2d03b2d65 100644
--- a/web/src/i18n/locales/ru.json
+++ b/web/src/i18n/locales/ru.json
@@ -2220,6 +2220,9 @@
     "displayNamePlaceholder": "Например: Помощник для протоколов встреч",
     "displayNameHelp": "До 200 символов. По умолчанию — имя из пакета. Изменения проходят проверку версии и не меняют идентификатор или файлы пакета. Пустое поле означает имя из пакета.",
     "readingPackage": "Чтение метаданных пакета…",
+    "examplesReady": "Распознано примеров задач на всех языках: {{count}}.",
+    "examplesNone": "Примеры задач не предоставлены. Публикация и использование доступны.",
+    "examplesInvalid": "Формат примеров не распознан. Файл сохранится как обычный файл; публикация доступна.",
     "packagePreviewFailed": "Не удалось прочитать пакет. Проверьте SKILL.md и выберите пакет снова или повторите попытку.",
     "title": "Опубликовать скилл",
     "subtitle": "Загрузить пакет скилла в SkillHub",
diff --git a/web/src/i18n/locales/zh.json b/web/src/i18n/locales/zh.json
index f107a94de..ca079e3fd 100644
--- a/web/src/i18n/locales/zh.json
+++ b/web/src/i18n/locales/zh.json
@@ -2228,6 +2228,9 @@
     "displayNamePlaceholder": "例如：会议纪要助手",
     "displayNameHelp": "支持中文，最多 200 个字符。默认读取包内名称；修改后随本次版本审核，不改变技能标识或包内文件。留空则使用包内名称。",
     "readingPackage": "正在读取技能包信息…",
+    "examplesReady": "已识别 {{count}} 条使用案例（包含全部语种）。",
+    "examplesNone": "未提供使用案例，可正常发布和使用。",
+    "examplesInvalid": "未识别案例格式，文件将保留为普通文件，不影响发布。",
     "packagePreviewFailed": "无法读取技能包，请检查 SKILL.md 后重新选择，或重试。",
     "title": "发布技能",
     "subtitle": "上传技能包到 SkillHub",
diff --git a/web/src/pages/dashboard/publish-display-name.test.tsx b/web/src/pages/dashboard/publish-display-name.test.tsx
index 4dd627a83..cb243493d 100644
--- a/web/src/pages/dashboard/publish-display-name.test.tsx
+++ b/web/src/pages/dashboard/publish-display-name.test.tsx
@@ -71,3 +71,22 @@ describe('web display name publishing', () => {
     await waitFor(() => expect((screen.getByLabelText('publish.displayName') as HTMLInputElement).value).toBe('重试后的名称'))
   })
 })
+
+
+describe('examples preflight remains non-blocking', () => {
+  for (const status of ['ready', 'none', 'invalid'] as const) {
+    it(`shows ${status} recognition and still allows publishing`, async () => {
+      preview.mockResolvedValue({ ...metadata('案例技能'), examplesStatus: status, ...(status === 'invalid' ? {} : { examplesCount: status === 'ready' ? 2 : 0 }) })
+      mount(); select('examples.zip')
+      await screen.findByText(`publish.examples${status[0].toUpperCase()}${status.slice(1)}`)
+      expect(screen.getByRole('button', { name: 'publish.confirm' }).hasAttribute('disabled')).toBe(false)
+    })
+  }
+  it('tolerates old preview responses without examples fields', async () => {
+    preview.mockResolvedValue(metadata('旧技能'))
+    mount(); select('old.zip')
+    await waitFor(() => expect((screen.getByLabelText('publish.displayName') as HTMLInputElement).value).toBe('旧技能'))
+    expect(screen.queryByText(/publish.examples/)).toBeNull()
+    expect(screen.getByRole('button', { name: 'publish.confirm' }).hasAttribute('disabled')).toBe(false)
+  })
+})
diff --git a/web/src/pages/dashboard/publish.tsx b/web/src/pages/dashboard/publish.tsx
index f54249f19..a7d8eb322 100644
--- a/web/src/pages/dashboard/publish.tsx
+++ b/web/src/pages/dashboard/publish.tsx
@@ -343,6 +343,9 @@ export function PublishPage() {
             <Button type="button" size="sm" variant="outline" onClick={() => packagePreview.refetch()}>{t('publish.retryPackagePreview')}</Button>
           </div>}
           {selectedFile && packagePreview.data && <p className="break-all text-xs text-muted-foreground">{t('publish.packageName')}: <code>{packagePreview.data.name}</code></p>}
+          {selectedFile && packagePreview.data?.examplesStatus === 'ready' && <p role="status" className="text-xs text-muted-foreground">{t('publish.examplesReady', { count: packagePreview.data.examplesCount })}</p>}
+          {selectedFile && packagePreview.data?.examplesStatus === 'none' && <p className="text-xs text-muted-foreground">{t('publish.examplesNone')}</p>}
+          {selectedFile && packagePreview.data?.examplesStatus === 'invalid' && <p role="status" className="text-xs text-muted-foreground">{t('publish.examplesInvalid')}</p>}
         </div>
 
         <SkillAvatarEditor key={`${namespaceSlug}/${updateSlug}`} name={search.updateName ?? updateSlug} currentUrl={avatarTarget.data?.avatarUrl} canRemove={!!updateSlug} disabled={ownerReadOnly || isBusy || avatarUnavailable} onChange={setAvatarEdit} />

From 028eeaa44a9f71dc8abfdcfafe82ffa4185e2fd0 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Thu, 22 Oct 2026 18:00:26 +0800
Subject: [PATCH 10/17] docs(dsh): record final examples review and host
 regression

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 openspec/changes/add-dsh-native-plugin/tasks.md      |  2 +-
 .../changes/add-dsh-native-plugin/verification.md    | 12 ++++++++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/openspec/changes/add-dsh-native-plugin/tasks.md b/openspec/changes/add-dsh-native-plugin/tasks.md
index 011a265ee..443ad948a 100644
--- a/openspec/changes/add-dsh-native-plugin/tasks.md
+++ b/openspec/changes/add-dsh-native-plugin/tasks.md
@@ -341,4 +341,4 @@
 
 - [x] 41.5 修复模板填入空输入框时多出首行空白；验证已有换行、中文/emoji、原生引用及附件保留，完成双 RC 浏览器复验。
 
-- [ ] 41.6 最终独立评审修复对话详情弹层阻挡案例选择及 Windows 分隔符 ZIP 目录识别；补相应回归，核对最终产物与正式协议。
+- [x] 41.6 最终独立评审修复对话详情弹层阻挡案例选择及 Windows 分隔符 ZIP 目录识别；补相应回归，核对最终产物与正式协议。
diff --git a/openspec/changes/add-dsh-native-plugin/verification.md b/openspec/changes/add-dsh-native-plugin/verification.md
index f25d0a4ff..5424e7263 100644
--- a/openspec/changes/add-dsh-native-plugin/verification.md
+++ b/openspec/changes/add-dsh-native-plugin/verification.md
@@ -269,3 +269,15 @@
 - 完整插件check的build/typecheck/lint和486项测试、11344次断言通过；独立增量评审、60项测试及类型/静态检查通过。
 - 同一未发布候选在两支持RC经官方严格安装并核对85个文件；每版实际浏览器通过5项：空草稿案例、空草稿自定义、已有换行及中文/emoji、原生引用chip和可解码PNG保留、技能中心新建空对话后填入。直接比较完整正文，不使用trim掩盖首尾空白；无RPC模拟、消息发送或模型调用，页面脚本异常为零。
 - 新人工预览使用20个简短有效案例，原压力样例及旧预览保留。已存在草稿不自动改写。证据位于仓库外 `dsh-leading-line-20261022/REPORT.md` 与 `evidence/{old,new}/`。本增量不涉及SaaS、CLI/Java/Web、原生Windows/macOS、模型执行或发布。
+
+
+## 最终代码评审与 PR 整理
+
+最终独立评审覆盖需求一致性、正确性、模块边界、安全隐私、生命周期数据、兼容性、失败恢复、测试有效性、可维护性与范围、用户体验十个维度。两项新增发现已修复并经独立复核：对话搜索详情在初次核验成功并交接驻留控制器后关闭弹层，避免阻挡案例；ZIP 提取与中央目录校验统一识别两种路径分隔符。首次核验失败保留详情，取消案例不改草稿、不重开详情，原生 CAS 与上下文守卫不变。
+
+- 最终插件 build/typecheck/lint、491项测试及11371次断言通过；同一候选包含修复后的共享核心。CLI lint/typecheck/build、20项归档测试通过，独立复验两种目录分隔符的解包→重打包→解包原字节与空目录保留。
+- 服务端最终定向70项测试通过、无失败或跳过；Web lint/typecheck、16项定向测试通过。前述跨层全量与HTTP生命周期证据继续保留，未冒充本轮重跑。
+- 最终包在两版官方Host严格安装并核对85个文件。实际工具搜索进入已安装技能详情，点击使用后弹层关闭、确认按钮实际点击命中；取消保留草稿，确认末项后在原会话正确填入，两版各2项通过。两版另复验5项首行空白、已有换行、中文/emoji、引用/PNG及技能中心新对话行为。无消息发送、模型调用或页面脚本异常。
+- 已同步主线发布记录；公开diff仅为94份源码、回归测试和正式文档，不包含本机任务、日志、截图、宿主配置或凭证。过程证据保存在仓库外 `dsh-use-skill-pr-review-20261022/`，代码评审证据与候选身份单独绑定。
+
+用户已完成人工预览并确认。此次进入草稿PR评审，不表示整栈镜像/auth smoke、远端CI、原生Windows/macOS、真实模型、SaaS或发布已完成；npm版本保持不变，合并与发布另行处理。

From daafac5c7348315bfe78aa3b2dc5ca50acd4f4d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=83=E4=B9=98=E5=A6=8D=20=28Xiaoyaner=29?=
 <258399167+xiaoyaner0201@users.noreply.github.com>
Date: Thu, 22 Oct 2026 23:33:10 +0800
Subject: [PATCH 11/17] docs(spec): propose versioned Knowledge package
 classification
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a spec-only OpenSpec change for #718 with version-specific type semantics, legacy search/install compatibility and unchanged Skill/Suite identity. Keep declaration, lifecycle and exposure choices explicitly proposed pending maintainer review; no runtime or deployment changes.

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>
---
 .../add-knowledge-package-type/.openspec.yaml |   2 +
 .../add-knowledge-package-type/design.md      |  82 +++++++++
 .../add-knowledge-package-type/proposal.md    |  47 ++++++
 .../specs/knowledge-package-type/spec.md      | 158 ++++++++++++++++++
 .../add-knowledge-package-type/tasks.md       |  25 +++
 5 files changed, 314 insertions(+)
 create mode 100644 openspec/changes/add-knowledge-package-type/.openspec.yaml
 create mode 100644 openspec/changes/add-knowledge-package-type/design.md
 create mode 100644 openspec/changes/add-knowledge-package-type/proposal.md
 create mode 100644 openspec/changes/add-knowledge-package-type/specs/knowledge-package-type/spec.md
 create mode 100644 openspec/changes/add-knowledge-package-type/tasks.md

diff --git a/openspec/changes/add-knowledge-package-type/.openspec.yaml b/openspec/changes/add-knowledge-package-type/.openspec.yaml
new file mode 100644
index 000000000..7cc41bb51
--- /dev/null
+++ b/openspec/changes/add-knowledge-package-type/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-22
diff --git a/openspec/changes/add-knowledge-package-type/design.md b/openspec/changes/add-knowledge-package-type/design.md
new file mode 100644
index 000000000..ced1ee58b
--- /dev/null
+++ b/openspec/changes/add-knowledge-package-type/design.md
@@ -0,0 +1,82 @@
+## Context
+
+**Proposed / spec-only**；以下取舍都是推荐，不是维护者确认或现役功能说明。源码依据冻结于 `e88ebf57c2e9123ef9697ce9a08492fd7e18b7a8`，不以更新后的 main 替代本次基线。
+
+| 依据 | 本稿保留的事实与限制 |
+| --- | --- |
+| [产品方向](../../../docs/00-product-direction.md)、[生命周期](../../../docs/14-skill-lifecycle.md) | 注册中心优先、`SKILL.md` 兼容；公共发布候选与 owner preview 不同。 |
+| [解析器](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/metadata/SkillMetadataParser.java)、[包校验器](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/validation/SkillPackageValidator.java) | 保留 frontmatter，有松散解析回退；新声明校验不能被回退抹掉。 |
+| [SkillVersion](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/SkillVersion.java)、[发布服务](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillPublishService.java) | `parsedMetadataJson` 保存版本 frontmatter；发布路径有所有者隔离与冲突检查。 |
+| [V13](../../../server/skillhub-app/src/main/resources/db/migration/V13__skill_owner_uniqueness.sql)、[坐标解析](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillSlugResolutionService.java) | 唯一约束为 `(namespace_id, slug, owner_id)`；按入口使用 CURRENT_USER / PUBLISHED 偏好。 |
+| [确认发布](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillReviewSubmitService.java)、[审核](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/ReviewService.java) | 成功发布移动指针；审批还检查同名已发布记录并投影发布元数据。 |
+| [解析](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillQueryService.java)、[治理](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillGovernanceService.java) | latest 读取既有指针；yank 由既有发布回退逻辑调整指针，不按 semver 排序。 |
+| [生命周期投影](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/skill/service/SkillLifecycleProjectionService.java)、[Promotion](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/review/PromotionService.java) | 投影区分发布与预览；Promotion 复制所选源版本的元数据。 |
+| [搜索架构](../../../docs/04-search-architecture.md)、[索引事件](../../../server/skillhub-search/src/main/java/com/iflytek/skillhub/search/event/SearchIndexEventListener.java) | AFTER_COMMIT 异步重建，不保证发布与搜索原子可见。 |
+| [发现接口](../../../server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/ResourceDiscoveryController.java)、[响应](../../../server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/ResourceSummaryResponse.java)、[Web 类型](../../../web/src/api/types.ts) | 现有 `resourceType` 为 SKILL / SUITE，不以包分类替换。 |
+| [Skill 接口](../../../server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/portal/SkillController.java)、[CLI 客户端](../../../cli/src/clients/skillhub-client.ts) | 详情、版本与 resolve 是不同视角；TypeScript 的类型断言不是所有旧消费者宽容解码的证明。 |
+| [Suite 规范](../add-skill-suites/specs/skill-suites/spec.md)、[成员解析](../../../server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/suite/SkillSuiteMemberStateResolver.java) | 成员锁定精确 SkillVersion，不因同名或 latest 变化重绑定。 |
+
+## Goals / Non-Goals
+
+只增加包分类、版本一致的展示和可选发现过滤；保留 Skill 聚合、文件布局、命令、权限与治理。Knowledge 表达以随包资料为主的组织意图，不证明内容无执行行为或可信。外部数据服务和新的执行/文件政策不在本稿范围。
+
+## Decisions
+
+### G1 — Declaration and historical compatibility
+
+推荐唯一新声明位置：
+
+```yaml
+metadata:
+  package-type: knowledge
+```
+
+新接收包仅接受精确字符串 `skill` / `knowledge`，不做大小写或空白纠正；键不存在则为 `skill`，不继承前一版本。显式 null、空串、未知字符串及非字符串值均拒绝并指出字段；其余自定义 metadata 沿用原支持，不顺带收紧格式。显式声明不能可靠解析时拒绝，不允许松散回退把无效声明视为未声明；这不是通用解析器重构。
+
+推荐启用时冻结“已接收历史版本”的适用性，包含尚未发布的记录：这些版本一律维持 `skill`，即使原始键值恰为 `knowledge`、未知值或 null。读取、下载、后续原审核不得追溯失败；包原文和历史 frontmatter 不改写。启用后新接收或替换包内容才按新规则验证；历史作者需用新版本显式选择 Knowledge。
+
+未来实现应保存**服务端可信的逐版本适用性及有效类型**，与原始 frontmatter 区分，不能只看未经验证的历史键、由包伪造适用性，或仅按复制后创建时间判断。具体存储/迁移不在此稿落地；上线前必须能可靠区分历史版本，否则 G1 未满足。Promotion 复制有效分类及其适用性，历史 `skill` 不因复制到新记录变成 Knowledge；新上传/rerelease 重新接收包时则执行新提交校验。
+
+备选：追溯识别所有历史 `knowledge` 或拒绝历史未知值；不推荐，前者会抢占既有扩展键的含义，后者会破坏已接收包。键名及这项保守策略仍需 G1 批准。
+
+### G2 — Version, identity and lifecycle
+
+分类属于 SkillVersion，不属于可覆盖历史的 Skill 标签。已发布字节/声明不可原地改写；改变类型需新版本并走原发布、扫描及适用审核分支，不增加或豁免任何分支。
+
+“公共当前类型”取**既有入口选出的 latest published 候选**的有效类型，不新算最大 semver，不选择“最近一个匹配类型的版本”。固定版本、tag、hash 先按既有规则解析，再取实际结果的类型；找不到、无权访问、未发布、被 yank 或未就绪时保留原拒绝/回退语义。
+
+原始 `latestVersionId` 在 PRIVATE 上传时可能指向 UPLOADED/SCANNING；指针非空不是发布证明。现有详情投影可回退到已发布版本，批量公开摘要不做同样回退；本稿不修正这些差异。类型附着于各入口已选中的版本，不将非发布指针或 owner preview 变为公共候选。
+
+授权预览按所选预览版本显示分类和原 `resolutionMode` / 状态，不能覆盖公共类型；无发布候选时不凭预览生成公共分类。yank 当前版本后使用既有 survivor 指针及其类型；无 survivor 则无公共分类/命中，不要求物理删除索引。Promotion 按所选源版本而非来源 latest 分类。
+
+V13 允许不同 owner 的同名记录共存，不意味着可创建第二个同坐标已发布身份。类型不进入唯一键、坐标、冲突豁免、所有权或解析优先级；保留发布/审批的既有冲突检查及调用者偏好。既有 Suite 设计中的概念坐标不能替代 V13 的实际 Skill 唯一约束；本稿不修改 Suite 正文。
+
+Knowledge 仍是 Skill：Skill/Suite 同 slug 的入口与命令不变；Suite 引用、成员资格与精确版本校验不变，不引入新的成员类型或动态重绑定。
+
+### G3 — Opt-in exposure and discovery
+
+推荐首批范围如下；这是待 G3 确认的端点边界，不是已存在的参数：
+
+| 入口 | 推荐扩展 |
+| --- | --- |
+| `GET /api/v1/resources`、`GET /api/web/resources` | 可选 `packageType=skill|knowledge` 过滤；`include=packageType` 才扩展响应。 |
+| SkillController 的详情、版本列表/详情、resolve（`/api/v1/skills` 与 `/api/web/skills`） | 仅以 `include=packageType` 扩展相应 Skill/版本对象；不增加类型过滤或重解析。 |
+| 旧 Skill 搜索、CLI / ClawHub 兼容端点、下载及其他入口 | 保留原响应形状与行为；本片不扩展它们。 |
+
+复用既有 [IncludeOptions](../../../server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/support/IncludeOptions.java) 的 `include` 扩展约定，不新增独立布尔参数；在上述入口支持 `packageType` 选项，不改变既有选项语义。未请求该选项时不增加任何新属性，包括资源发现默认响应，严格拒绝未知属性的旧消费者无需修改。请求该选项时，Skill 的有效候选返回可选字符串字段 `packageType: skill|knowledge`，原字段/枚举保持不变；Suite 不返回该字段。选项解析及未知选项错误沿用原约定。缓存键/表示协商必须区分 opt-in，不能把扩展表示返给未请求者。
+
+资源摘要和 Skill 聚合详情根对象的分类取发布候选；版本列表项、版本详情对象及 resolve 取其实际版本。授权预览只在对应预览版本对象内标类型，不冒充已发布根分类；无对应版本则省略字段，不以 null/猜测值充数。新客户端遇字段缺失仍可按 Skill 使用，不将缺失当成服务端已确认某个分类。
+
+过滤只约束当前发布的 Skill：省略 resourceType 时隐含 SKILL，显式 SUITE 配合过滤或未知 packageType 返回本地化 400。过滤不自动启用响应扩展。过滤发生在分页/计数前并保留既有权限过滤，不返回历史匹配或转向另一 owner。未过滤的旧搜索始终包含两个分类，但不新增 Suite 结果。
+
+索引类型只是派生数据：返回分类必须与结果版本一致，过滤需校验当前发布候选，避免异步旧索引形成错误类型命中；允许沿用原刷新时序暂未搜到，不承诺立即收录或发布/搜索原子性。
+
+备选：在所有旧响应直接加字段，依赖消费者忽略未知属性；不推荐，因为严格消费者可能失败。首片也不新增独立 Knowledge API/命令或修改 `resourceType`。
+
+## Risks / Trade-offs
+
+历史保守处理会让先前自填同名键的作者需重新发版；可信适用性保存和 opt-in 缓存隔离需实现验证，不能用“纯 additive”省略兼容验收。资料也可能含脚本、恶意指令或敏感信息；分类不是安全证据，不放宽现有扫描、审核、访问、下载就绪、隐藏/归档/yank、大小/扩展名与审计规则。
+
+## Validation Strategy
+
+本次仅做 OpenSpec 严格结构验证、status、diff 与本地链接/来源核对；不运行 Java、前端、CLI 构建或应用栈。行为场景是未来实现的验收建议，不是已通过的运行测试。实现和发行均需另行授权，并完成[待办](./tasks.md)中的 gate 与兼容回归。
diff --git a/openspec/changes/add-knowledge-package-type/proposal.md b/openspec/changes/add-knowledge-package-type/proposal.md
new file mode 100644
index 000000000..abab450e1
--- /dev/null
+++ b/openspec/changes/add-knowledge-package-type/proposal.md
@@ -0,0 +1,47 @@
+## Status
+
+**Proposed / spec-only**。本文所有新增策略均为待维护者确认的推荐方案；`SHALL` 表示候选契约，不表示已获同意、已实现或承诺发布。实现与发行需另行决定。
+
+## Why
+
+[Issue #718](https://github.com/iflytek/skillhub/issues/718) 希望区分以资料交付为主的包，同时复用 SkillHub 的版本、治理、发现与安装能力。需要先明确分类属于哪个版本、旧客户端如何继续工作，以及同坐标和历史元数据如何处理。
+
+维护者要求先提交可审阅的规范，而非实现；[原文](https://github.com/iflytek/skillhub/issues/718#issuecomment-6335397069)如下：
+
+> Thanks for the concrete contract proposal and the revised legacy-search default. A spec-only artifact would make these choices reviewable without committing to implementation. Please include scenarios for mixed historical version types and latest-version changes, pinned-version resolution, unknown frontmatter values, existing coordinate collisions, additive packageType responses and unmodified clients continuing to search/install Knowledge as a Skill. Keep Skill/Suite resource identity unchanged in that draft. The exact metadata key and lifecycle rules still need maintainer agreement; implementation and release remain separate decisions.
+
+## What Changes
+
+- 推荐 Knowledge 为 `SKILL` 资源的版本级包分类，不新增与 `SKILL` / `SUITE` 并列的资源身份。
+- 推荐 `SKILL.md` frontmatter 的嵌套 `metadata.package-type: skill|knowledge`；新提交缺省为 `skill`，声明无效则拒绝。
+- 推荐公共分类跟随既有 latest published 候选，固定版本使用实际解析版本的类型；历史版本不随新版本重分类。
+- 推荐旧搜索默认包含 Knowledge，旧安装仍按 Skill 工作；新过滤和可选响应字段采用显式接入，不要求严格旧消费者接受额外属性。
+- 推荐保留启用前已接收版本的普通 Skill 语义，包括偶然使用同名键的历史数据；不追溯拒绝或自动重分类。
+
+## Decision Relative to Issue #718
+
+本稿延续[后续提案](https://github.com/iflytek/skillhub/issues/718#issuecomment-6209958184)修订后的默认搜索：**不隐藏 Knowledge**。原 Issue 的排除式默认不作为本稿目标；这项修订不等于维护者已批准整份契约。
+
+## Capabilities
+
+### New Capabilities
+
+- `knowledge-package-type`：定义声明、版本投影、碰撞、发现、兼容与治理边界，见[候选需求](./specs/knowledge-package-type/spec.md)。
+
+### Modified Capabilities
+
+无其他 OpenSpec capability 的修改；既有 Suite 正文及 Skill/Suite 身份契约保持不变。
+
+## Maintainer Gates
+
+| Gate | 本稿具体推荐，仍待维护者同意 |
+| --- | --- |
+| G1 — Declaration | 采用嵌套键、严格小写值与历史版本保守处理；确认启用边界及可信分类来源。 |
+| G2 — Lifecycle | 类型逐版本决定、缺省不继承；沿用发布、指针、yank、预览及 Promotion 语义。 |
+| G3 — Exposure | 复用 `include=packageType` 显式响应扩展，类型过滤先限于资源发现接口；确认端点范围与缓存隔离。 |
+
+细节、备选与依据见[设计](./design.md)；未通过这些 gate 不启动实现。
+
+## Impact
+
+本次只新增五份 OpenSpec 文件，无产品代码、数据库迁移、生成类型、配置或运行时改动。未来实现若获准，才评估解析/校验、版本分类存储、查询/索引、API schema 与客户端展示；继续使用原 Skill 包入口、安装目录和命令。不新增外部描述符、依赖求解、托管 RAG/向量/图服务、任意端点抓取/查询、凭据管理或服务端执行，也不改变可执行文件政策。
diff --git a/openspec/changes/add-knowledge-package-type/specs/knowledge-package-type/spec.md b/openspec/changes/add-knowledge-package-type/specs/knowledge-package-type/spec.md
new file mode 100644
index 000000000..130ff6d91
--- /dev/null
+++ b/openspec/changes/add-knowledge-package-type/specs/knowledge-package-type/spec.md
@@ -0,0 +1,158 @@
+## ADDED Requirements
+
+### Requirement: Knowledge SHALL remain a Skill package classification
+
+本稿为 **Proposed / spec-only**；所有 SHALL 均为待 G1–G3 同意的候选要求，非已接受策略；端点和兼容边界见[设计](../../design.md)。系统 SHALL 将 Knowledge 视为 SkillVersion 的包分类，保留 Skill 聚合、根 `SKILL.md`、坐标、安装目录与原命令。`resourceType` SHALL 保持 `SKILL` / `SUITE`，不得新增并列 KNOWLEDGE 资源或以分类改变 Suite 身份/成员资格。
+
+#### Scenario: Skill and Suite share a slug
+- **WHEN** 同一空间存在 Knowledge 分类的 `SKILL @global/guide` 和 `SUITE @global/guide`
+- **THEN** 原 `skillhub install @global/guide` 只安装该 Skill，`skillhub suite install` 仍走 Suite 入口
+- **AND** 类型感知响应仍以 `resourceType=SKILL` 表示前者，不把分类加入坐标
+
+#### Scenario: Suite member stays pinned
+- **WHEN** Suite 成员已固定某 SkillVersion，该 Skill 后续发布不同分类版本
+- **THEN** 成员仍引用原精确版本，按该版本分类解释
+- **AND** 原成员权限/可安装性校验不变，不新增成员类型或重绑定
+
+### Requirement: New declarations SHALL be explicit and validated
+
+系统 SHALL 在启用后新接收包时，仅将嵌套 `metadata.package-type` 的精确字符串 `skill` / `knowledge` 解释为分类；键缺失 SHALL 为 `skill`，与前一版本无关。显式未知、null、空串及非字符串值 SHALL 拒绝，错误指出字段；其他 metadata 支持 SHALL 保持不变。
+
+#### Scenario: Omission does not inherit Knowledge
+- **WHEN** v1 声明 knowledge，随后新提交 v2 不含该键
+- **THEN** v2 的有效分类为 skill，v1 仍为 knowledge
+
+#### Scenario: Invalid new declaration
+- **WHEN** 新提交值为 `dataset`、`KNOWLEDGE`、` knowledge `、null、空串、布尔、数字、数组或对象
+- **THEN** 系统拒绝本次包提交并指出 `metadata.package-type`，不生成有效新版本或默认为 skill
+
+#### Scenario: Loose parsing must not erase a declaration
+- **WHEN** 新提交含显式分类声明，但 YAML 歧义/错误或解析回退使其不能可靠验证
+- **THEN** 系统拒绝该提交，不将声明丢失解释为缺省
+- **AND** 不借此新增与分类无关的通用 metadata 限制
+
+### Requirement: Historical metadata SHALL retain pre-feature semantics
+
+系统 SHALL 保留启用前已接收版本的 `skill` 语义，不追溯解析保留键，不因历史键碰撞拒绝读取、下载或推进原审核。分类适用性 SHALL 来自可信服务端逐版本记录，与原始 frontmatter 分离；启用后新接收/替换包内容 SHALL 执行新提交校验。
+
+#### Scenario: Historical reserved-key collision
+- **WHEN** 启用前版本的原始 metadata 已使用 `package-type`，值为 knowledge、未知值、null 或其他类型
+- **THEN** 该版本继续作为 skill 按原权限使用，原文及存储的 frontmatter 不被改写
+- **AND** 不能因重新索引或新建复制记录而自动重分类或报新声明错误
+
+#### Scenario: Previously received pending version
+- **WHEN** 启用前已接收但尚未发布的版本，在启用后完成原审核
+- **THEN** 仍按历史 skill 解释，不追溯拒绝其保留键
+- **AND** 作者另交新包时则必须满足新声明规则，不能由包伪造历史适用性
+
+### Requirement: Public classification SHALL follow the existing published candidate
+
+系统 SHALL 在既有生命周期选定版本后附加其有效分类。公共当前分类 SHALL 使用该入口既有 latest published 候选，不按最大 semver、草稿或历史匹配重选；已发布版本 SHALL 不因后来版本而改变分类。改类型 SHALL 新建版本并走原发布及适用扫描/审核，不原地修改已发布声明或字节。
+
+#### Scenario: Mixed historical types and latest changes
+- **WHEN** 同一 Skill 依次发布 v1=skill、v2=knowledge、v3=skill，既有指针随每次成功发布移动
+- **THEN** 公共分类依次为 skill、knowledge、skill
+- **AND** 各历史版本保持原分类；提交/拒绝待审版本不替代公共分类
+
+#### Scenario: Last approved version has lower semver
+- **WHEN** v2.0.0=skill 已发布，随后 v1.5.0=knowledge 经既有发布流程成为指针目标
+- **THEN** 公共分类为 knowledge，不重新选择版本字符串更大的 v2.0.0
+
+#### Scenario: Authorized preview is not public latest
+- **WHEN** 已发布 v1=skill，管理者可预览未发布 v2=knowledge
+- **THEN** 授权预览的版本对象可展示 knowledge 及原状态/预览模式，公共分类仍为 skill
+- **AND** 原始指针若因 PRIVATE 上传指向 UPLOADED/SCANNING，不以其非空证明已发布；沿用各入口已有拒绝/投影回退
+
+#### Scenario: No published version exists
+- **WHEN** 只有授权管理者可见的非发布版本
+- **THEN** 不生成公共分类或搜索命中；管理者可见的预览类型不增加公开访问或安装权限
+
+### Requirement: Resolution and yank SHALL preserve version-specific meaning
+
+固定版本、tag、hash 的分类 SHALL 来自按既有规则实际解析的版本，不来自当前摘要。yank SHALL 沿用现有 fallback 选取与错误规则；分类不得使已撤回、无权限或未就绪版本可分发，也不得引入新的解析回退。
+
+#### Scenario: Pinned resolution differs from discovery
+- **WHEN** 当前 latest=knowledge，而客户端固定到仍可安装的历史 skill 版本
+- **THEN** resolve 的分类为 skill，版本、ID、fingerprint 与下载目标仍是被固定的版本
+- **AND** 公共摘要为 knowledge，不把该类型回填到旧版本
+
+#### Scenario: Tag or hash selects an older version
+- **WHEN** 既有 tag/hash 规则实际选中历史 knowledge 版本，而当前发布候选为 skill
+- **THEN** 类型感知 resolve 返回 knowledge，不改 tag/hash 的原优先级、匹配/失败或回退行为
+
+#### Scenario: Yank switches to a survivor
+- **WHEN** 当前 knowledge 版本被 yank，既有治理逻辑将指针回退到 skill 版本
+- **THEN** 公共分类随 survivor 变为 skill，固定到已 yank 版本仍按原规则拒绝分发
+
+#### Scenario: Yank leaves no survivor
+- **WHEN** yank 后不再有已发布 survivor
+- **THEN** 沿用原 latest 不可用行为，不返回伪造 skill 分类或公开搜索命中
+- **AND** 不要求物理删除现有搜索文档，也不改变原治理审计
+
+#### Scenario: Promotion uses the selected source version
+- **WHEN** Promotion 选择历史 knowledge 版本而非来源 latest=skill
+- **THEN** 目标新版本复制该源版本有效类型/适用性并走原提升审核，不借来源 latest 改型
+
+#### Scenario: Promotion preserves historical compatibility
+- **WHEN** Promotion 复制启用前接收且原始键恰为 knowledge 的版本
+- **THEN** 目标仍复制历史 skill 语义，不因目标记录新建而重新解释原始键
+
+### Requirement: Package type SHALL NOT resolve coordinate collisions
+
+系统 SHALL 保留 `(namespace_id, slug, owner_id)` 唯一约束、现有发布/审批冲突检查及坐标解析的调用者偏好。分类 SHALL 不作为新坐标、第二个发布身份、所有权覆盖、冲突豁免或同名选择的 tie-breaker；不新增跨类型唯一约束。
+
+#### Scenario: Owner-isolated unpublished records coexist
+- **WHEN** 两位 owner 已有同空间同 slug 的隔离未发布记录，分别声明 skill 与 knowledge
+- **THEN** 不合并、迁移或删除记录，原 CURRENT_USER / PUBLISHED 解析偏好不变
+- **AND** 不按分类选择另一 owner 或声称 namespace+slug 在数据库全局唯一
+
+#### Scenario: Same owner changes classification through a version
+- **WHEN** 同一 owner 在其现有坐标提交另一分类的新版本
+- **THEN** 仍属于同一个 Skill ID，不创建第二个资源身份
+- **AND** 若版本号已占用，分类不同也不豁免原版本冲突
+
+#### Scenario: Knowledge cannot bypass a published name conflict
+- **WHEN** 另一 owner 的同空间同 slug 记录已发布，当前用户尝试以另一分类发布或获批
+- **THEN** 按该入口原有冲突/授权规则处理，不因声明 knowledge 获得第二个发布身份或覆盖原记录
+
+### Requirement: Discovery SHALL stay inclusive and filter only current type
+
+未带类型过滤的原 Skill 搜索 SHALL 同时包含符合原可见性与分发条件的 skill 和 knowledge，不新增 Suite 结果。新 `packageType` 过滤 SHALL 仅用于设计列出的资源发现入口，在分页/计数前约束当前发布 Skill 候选，不搜索历史版本；省略 resourceType 时限于 SKILL，与 SUITE 合用或未知过滤值 SHALL 返回本地化 400。
+
+#### Scenario: Unmodified client searches and installs Knowledge
+- **WHEN** 未修改的旧 CLI / 兼容客户端按原请求搜索可访问且可安装的 Knowledge 包
+- **THEN** 包仍作为 Skill 返回，原 resolve/下载/安装命令与目录可继续使用
+- **AND** 无需新命令、额外类型参数、客户端更新或放宽严格解码器
+
+#### Scenario: Historical match does not satisfy the filter
+- **WHEN** v1=knowledge、当前发布 v2=skill，资源发现请求 packageType=knowledge
+- **THEN** 当前 Skill 不命中，不将其结果或安装目标替换成 v1
+- **AND** packageType=skill 可按原条件命中，权限过滤及分页/计数语义保持一致
+
+#### Scenario: Asynchronous index still has the old type
+- **WHEN** 指针已从 knowledge 移到 skill，而异步索引尚未刷新
+- **THEN** 不用旧索引类型产生 knowledge 过滤命中；结果分类须与实际结果版本一致
+- **AND** 可沿用原索引延迟暂未收录，不承诺发布后立即可搜或事务级搜索原子性
+
+### Requirement: Optional responses SHALL preserve strict legacy consumers
+
+设计列出的扩展入口 SHALL 复用现有 `include` 约定，仅在请求 `include=packageType` 时为对应 Skill/版本对象附加可选 `packageType: skill|knowledge`；未请求该选项 SHALL 保持旧响应属性集合，选项解析及未知选项错误 SHALL 沿用原约定。过滤 SHALL 不自动启用扩展；缓存 SHALL 隔离 opt-in 表示。既有字段及 resourceType 枚举 SHALL 不变，Suite/无对应版本 SHALL 省略新字段。
+
+#### Scenario: Strict decoder uses the unchanged response
+- **WHEN** 严格拒绝未知属性的旧消费者原样调用资源发现、详情、版本或 resolve
+- **THEN** 默认响应不新增 packageType，消费者无需修改 schema 或忽略额外字段
+- **AND** CLI / ClawHub 等未纳入扩展的入口保持原形状，不误返缓存中的 opt-in 表示
+
+#### Scenario: Type-aware caller requests additive metadata
+- **WHEN** 新客户端显式 opt-in 查询可访问的 Knowledge Skill 版本或解析结果
+- **THEN** 在原字段外返回 `packageType=knowledge`，若响应已有 resourceType 则仍为 SKILL
+- **AND** 资源/详情根分类取发布候选，预览分类仅附着对应预览版本对象；无候选时省略，新客户端仍可走 Skill 兼容路径
+
+### Requirement: Classification SHALL NOT bypass governance
+
+Knowledge SHALL 复用全部适用的包校验、扫描、审核、所有者/空间/账号授权、可见性、下载就绪、hidden/归档/yank、限额及审计规则。分类 SHALL 不证明惰性或安全，不新增外部描述符、依赖求解、抓取/查询端点、凭据托管、服务端执行或改变可执行文件政策。
+
+#### Scenario: Knowledge carries unsafe or restricted content
+- **WHEN** 包声明 knowledge，但原策略会拒绝其文件、内容、权限、状态或分发请求
+- **THEN** 原拒绝或审核/扫描要求保持有效，不因分类豁免任何策略
+- **AND** 文档中的脚本、指令或外部链接不获得新的服务端执行、访问或抓取能力
diff --git a/openspec/changes/add-knowledge-package-type/tasks.md b/openspec/changes/add-knowledge-package-type/tasks.md
new file mode 100644
index 000000000..d1f1d1122
--- /dev/null
+++ b/openspec/changes/add-knowledge-package-type/tasks.md
@@ -0,0 +1,25 @@
+## 1. Current spec-only deliverables
+
+- [x] 1.1 依据冻结源码核对身份、版本/指针、解析回退、历史扩展元数据与响应消费者。
+- [x] 1.2 编写 proposal、design 和候选 scenarios；全部策略标为 Proposed，不提交运行实现。
+- [x] 1.3 运行 OpenSpec 1.14.3 strict validate 与 status，并检查 diff、引用与本地链接。
+- [ ] 1.4 由独立审阅者复核候选实际文件、维护者请求覆盖及未决 gate；修订后重验。
+
+## 2. Maintainer agreement gates
+
+- [ ] 2.1 G1：确认键名、规范值、新提交拒绝规则、启用边界及历史保守分类/可信适用性方案。
+- [ ] 2.2 G2：确认逐版本类型、缺省不继承、公共/预览/固定版本/yank/Promotion 的生命周期建议。
+- [ ] 2.3 G3：确认显式响应 opt-in、首批端点、过滤与错误规则、缓存隔离及严格旧消费者验收。
+- [ ] 2.4 在上述共识后单独批准实现范围；spec 合入不自动授权实现或发行。
+
+## 3. Future implementation — blocked pending agreement
+
+以下仅为后续实施的建议，不属于本次交付，不标记为已完成。
+
+- [ ] 3.1 实现新声明校验及可信逐版本分类；防止松散回退和历史键碰撞改变类型，不改写发布包。
+- [ ] 3.2 在既有投影/解析后附加分类，覆盖混合版本、较低 semver 后发布、预览与无 survivor 的 yank。
+- [ ] 3.3 实现 opt-in 响应与资源过滤，维护分页/计数/权限语义、异步索引校验与表示缓存隔离。
+- [ ] 3.4 回归同 owner / 跨 owner 碰撞、Skill/Suite 同 slug、Suite 精确成员与所选源版本 Promotion。
+- [ ] 3.5 使用未修改 CLI / 兼容客户端及严格未知字段解码器，实测搜索、resolve、下载和标准 Skill 安装。
+- [ ] 3.6 验证原扫描/审核/授权/治理拒绝路径；按实际 API/schema 改动运行对应生成类型及消费者检查。
+- [ ] 3.7 另行评估迁移、回滚、发布与用户文档，不以本稿结构校验替代产品验收。

From 9503e7695c37ddfad5ddfa1ae65be89acc1819fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=83=E4=B9=98=E5=A6=8D=20=28Xiaoyaner=29?=
 <258399167+xiaoyaner0201@users.noreply.github.com>
Date: Fri, 23 Oct 2026 00:04:18 +0800
Subject: [PATCH 12/17] docs(spec): avoid table pipe in package type filter
 example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Use separate filter examples in the design table so Markdown renders both parameter values without splitting the cell. Wording only; no contract change.

Signed-off-by: 千乘妍 (Xiaoyaner) <258399167+xiaoyaner0201@users.noreply.github.com>
---
 openspec/changes/add-knowledge-package-type/design.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/openspec/changes/add-knowledge-package-type/design.md b/openspec/changes/add-knowledge-package-type/design.md
index ced1ee58b..62a908176 100644
--- a/openspec/changes/add-knowledge-package-type/design.md
+++ b/openspec/changes/add-knowledge-package-type/design.md
@@ -59,7 +59,7 @@ Knowledge 仍是 Skill：Skill/Suite 同 slug 的入口与命令不变；Suite 
 
 | 入口 | 推荐扩展 |
 | --- | --- |
-| `GET /api/v1/resources`、`GET /api/web/resources` | 可选 `packageType=skill|knowledge` 过滤；`include=packageType` 才扩展响应。 |
+| `GET /api/v1/resources`、`GET /api/web/resources` | 可选 `packageType=skill` / `packageType=knowledge` 过滤；`include=packageType` 才扩展响应。 |
 | SkillController 的详情、版本列表/详情、resolve（`/api/v1/skills` 与 `/api/web/skills`） | 仅以 `include=packageType` 扩展相应 Skill/版本对象；不增加类型过滤或重解析。 |
 | 旧 Skill 搜索、CLI / ClawHub 兼容端点、下载及其他入口 | 保留原响应形状与行为；本片不扩展它们。 |
 

From cdf8a5c2bffa6dcea5df51cd4b0a6ddced53b64f Mon Sep 17 00:00:00 2001
From: zjncs <18910855655@163.com>
Date: Thu, 22 Oct 2026 13:37:10 +0800
Subject: [PATCH 13/17] feat(authoring): runtime bindings, execution adapters
 and docker isolation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Layer (b1) of the authoring platform (#934), the first half of the split
runtime layer:

- **Runtime bindings**: agent type + config + tool allowlist per draft,
  persisted as JSONB and structurally validated at save time, managed via
  GET/PUT /drafts/{id}/runtime. MCP server declarations are validated
  structurally (name/transport/endpoint format); the SSRF policy, stdio
  gate and envRef allowlist that guard them arrive with the MCP+security
  layer.
- **CONFIG and BEHAVIOR validation layers**: validation.yaml spec parsing
  (defensive YAML), assertion syntax checks; script tasks execute through
  the local-script adapter — inline (cleared environment, isolated
  workspace, interpreter allowlist, path confinement) or docker (locked
  container: no network, dropped capabilities, read-only root, resource
  caps, tmpfs; workspace permissions and uid:gid mapping so container
  files stay readable and deletable on hardened hosts).
- The orchestrator keeps every piece of the upstream lifecycle hardening:
  one FutureTask per run, wall-clock watchdog, settle-first cancellation.

Verified: spec-parser and assertion-evaluator suites (20), docker
isolation against real containers (4, auto-skipped without a daemon),
the upstream orchestrator lifecycle suite against the extended
constructor (5), and the execution flow integration test (script-only
three-layer validation with inline execution).

Signed-off-by: zjncs <18910855655@163.com>
---
 .../skillhub/config/AuthoringProperties.java  |  98 ++++-
 .../authoring/SkillAuthoringController.java   |  54 ++-
 .../skillhub/dto/RuntimeBindingRequest.java   |  18 +
 .../skillhub/dto/RuntimeBindingResponse.java  |  15 +
 .../authoring/ValidationRunOrchestrator.java  | 342 +++++++++++++++++-
 .../adapter/DockerScriptCommandBuilder.java   | 230 ++++++++++++
 .../adapter/InlineScriptCommandBuilder.java   |  38 ++
 .../adapter/LocalScriptRuntimeAdapter.java    | 237 ++++++++++++
 .../adapter/ScriptCommandBuilder.java         |  53 +++
 .../adapter/WorkingDirectoryArtifacts.java    |  30 ++
 .../src/main/resources/application.yml        |  15 +
 .../src/main/resources/messages.properties    |   5 +
 .../src/main/resources/messages_ru.properties |   5 +
 .../src/main/resources/messages_zh.properties |   5 +
 .../AuthoringDraftFlowIntegrationTest.java    |  15 +-
 ...AuthoringExecutionFlowIntegrationTest.java | 178 +++++++++
 .../ValidationRunOrchestratorTest.java        |   7 +-
 .../src/test/resources/application-test.yml   |   5 +-
 .../domain/authoring/AgentRuntimeType.java    |  33 ++
 .../domain/authoring/RuntimeBinding.java      | 134 +++++++
 .../authoring/RuntimeBindingRepository.java   |  15 +
 .../authoring/runtime/AssertionEvaluator.java | 221 +++++++++++
 .../authoring/runtime/AssertionFailure.java   |  13 +
 .../authoring/runtime/RuntimeEventSink.java   |  21 ++
 .../runtime/RuntimeExecutionContext.java      |  50 +++
 .../runtime/SkillRuntimeAdapter.java          |  46 +++
 .../authoring/runtime/TaskCancellation.java   |  12 +
 .../domain/authoring/runtime/TaskResult.java  |  56 +++
 .../authoring/runtime/package-info.java       |   5 +
 .../service/RuntimeBindingService.java        | 101 ++++++
 .../service/RuntimeBindingValidator.java      | 214 +++++++++++
 .../domain/authoring/spec/AssertionSpec.java  |  36 ++
 .../domain/authoring/spec/TaskType.java       |  13 +
 .../domain/authoring/spec/ValidationSpec.java |  28 ++
 .../authoring/spec/ValidationSpecParser.java  | 211 +++++++++++
 .../authoring/spec/ValidationTaskSpec.java    |  26 ++
 .../domain/authoring/spec/package-info.java   |   4 +
 .../runtime/AssertionEvaluatorTest.java       | 138 +++++++
 .../spec/ValidationSpecParserTest.java        | 182 ++++++++++
 .../jpa/RuntimeBindingJpaRepository.java      |  19 +
 40 files changed, 2900 insertions(+), 28 deletions(-)
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/RuntimeBindingRequest.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/RuntimeBindingResponse.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/DockerScriptCommandBuilder.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/InlineScriptCommandBuilder.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptRuntimeAdapter.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/ScriptCommandBuilder.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/WorkingDirectoryArtifacts.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringExecutionFlowIntegrationTest.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/AgentRuntimeType.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/RuntimeBinding.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/RuntimeBindingRepository.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionEvaluator.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionFailure.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/RuntimeEventSink.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/RuntimeExecutionContext.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/SkillRuntimeAdapter.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/TaskCancellation.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/TaskResult.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/package-info.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingService.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/AssertionSpec.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/TaskType.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpec.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpecParser.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationTaskSpec.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/package-info.java
 create mode 100644 server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionEvaluatorTest.java
 create mode 100644 server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpecParserTest.java
 create mode 100644 server/skillhub-infra/src/main/java/com/iflytek/skillhub/infra/jpa/RuntimeBindingJpaRepository.java

diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
index 2379f0794..e29fd76b1 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
@@ -1,12 +1,12 @@
 package com.iflytek.skillhub.config;
 
+import java.util.ArrayList;
+import java.util.List;
 import org.springframework.boot.context.properties.ConfigurationProperties;
 
 /**
  * Feature configuration for the skill authoring and validation platform
- * ({@code skillhub.authoring.*}). This layer covers the draft authoring and
- * structure-validation core; runtime-binding configuration (script execution
- * backends, LLM endpoints, MCP servers) arrives with the runtime layer.
+ * ({@code skillhub.authoring.*}).
  */
 @ConfigurationProperties(prefix = "skillhub.authoring")
 public class AuthoringProperties {
@@ -23,6 +23,8 @@ public class AuthoringProperties {
     /** Active runs older than this are swept to TIMED_OUT by the maintenance task. */
     private int staleRunMinutes = 30;
 
+    private final LocalScript localScript = new LocalScript();
+
     public String getWorkspaceRoot() {
         return workspaceRoot;
     }
@@ -54,4 +56,94 @@ public int getStaleRunMinutes() {
     public void setStaleRunMinutes(int staleRunMinutes) {
         this.staleRunMinutes = staleRunMinutes;
     }
+
+    public LocalScript getLocalScript() {
+        return localScript;
+    }
+
+    /** Local script execution runtime. */
+    public static class LocalScript {
+        private boolean enabled = true;
+
+        /** Where scripts run: INLINE on the server host (dev), DOCKER in a locked-down container (production). */
+        private ScriptExecutionMode executionMode = ScriptExecutionMode.INLINE;
+
+        private final Docker docker = new Docker();
+
+        public boolean isEnabled() {
+            return enabled;
+        }
+
+        public void setEnabled(boolean enabled) {
+            this.enabled = enabled;
+        }
+
+        public ScriptExecutionMode getExecutionMode() {
+            return executionMode;
+        }
+
+        public void setExecutionMode(ScriptExecutionMode executionMode) {
+            this.executionMode = executionMode;
+        }
+
+        public Docker getDocker() {
+            return docker;
+        }
+
+        /** Container isolation profile for the docker execution mode. */
+        public static class Docker {
+            private String image = "alpine:3.20";
+            private String memory = "256m";
+            private String cpus = "1.0";
+            private int pidsLimit = 128;
+            private String tmpfsSize = "64m";
+
+            public String getImage() {
+                return image;
+            }
+
+            public void setImage(String image) {
+                this.image = image;
+            }
+
+            public String getMemory() {
+                return memory;
+            }
+
+            public void setMemory(String memory) {
+                this.memory = memory;
+            }
+
+            public String getCpus() {
+                return cpus;
+            }
+
+            public void setCpus(String cpus) {
+                this.cpus = cpus;
+            }
+
+            public int getPidsLimit() {
+                return pidsLimit;
+            }
+
+            public void setPidsLimit(int pidsLimit) {
+                this.pidsLimit = pidsLimit;
+            }
+
+            public String getTmpfsSize() {
+                return tmpfsSize;
+            }
+
+            public void setTmpfsSize(String tmpfsSize) {
+                this.tmpfsSize = tmpfsSize;
+            }
+        }
+    }
+
+    /** Script execution backend selection. */
+    public enum ScriptExecutionMode {
+        INLINE,
+        DOCKER
+    }
+
 }
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java
index ac0a3bf5f..a3a312b6a 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java
@@ -2,6 +2,7 @@
 
 import com.iflytek.skillhub.controller.BaseApiController;
 import com.iflytek.skillhub.domain.authoring.SkillDraft;
+import com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService;
 import com.iflytek.skillhub.domain.authoring.service.SkillDraftService;
 import com.iflytek.skillhub.domain.authoring.service.ValidationRunService;
 import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
@@ -10,6 +11,8 @@
 import com.iflytek.skillhub.dto.DraftFileContentResponse;
 import com.iflytek.skillhub.dto.DraftFileResponse;
 import com.iflytek.skillhub.dto.DraftResponse;
+import com.iflytek.skillhub.dto.RuntimeBindingRequest;
+import com.iflytek.skillhub.dto.RuntimeBindingResponse;
 import com.iflytek.skillhub.dto.SaveDraftFileRequest;
 import com.iflytek.skillhub.dto.SaveDraftFileResponse;
 import com.iflytek.skillhub.dto.ValidationEventResponse;
@@ -21,6 +24,7 @@
 import java.nio.charset.StandardCharsets;
 import java.util.Base64;
 import java.util.List;
+import java.util.Map;
 import java.util.Set;
 import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -34,26 +38,30 @@
 import org.springframework.web.bind.annotation.RestController;
 
 /**
- * REST endpoints for skill draft authoring and structure validation. Drafts
- * own a SKILL.md scaffold and arbitrary resource files; validation runs
- * execute the STRUCTURE layer and report findings with fix suggestions.
- * Runtime binding, behavior execution and the publish integration arrive with
- * the later layers.
+ * REST endpoints for skill draft authoring and validation. Drafts own a
+ * SKILL.md scaffold and arbitrary resource files; runtime bindings configure
+ * the agent and tool allowlist; validation runs execute the structure, config
+ * and behavior layers and report findings with fix suggestions. The MCP probe
+ * and the binding security policy arrive with the MCP+security layer, and the
+ * fix-apply loop and publish integration with the next layer.
  */
 @RestController
 @RequestMapping({"/api/v1/authoring", "/api/web/authoring"})
 public class SkillAuthoringController extends BaseApiController {
 
     private final SkillDraftService draftService;
+    private final RuntimeBindingService bindingService;
     private final ValidationRunService runService;
     private final ValidationRunOrchestrator orchestrator;
 
     public SkillAuthoringController(com.iflytek.skillhub.dto.ApiResponseFactory responseFactory,
                                     SkillDraftService draftService,
+                                    RuntimeBindingService bindingService,
                                     ValidationRunService runService,
                                     ValidationRunOrchestrator orchestrator) {
         super(responseFactory);
         this.draftService = draftService;
+        this.bindingService = bindingService;
         this.runService = runService;
         this.orchestrator = orchestrator;
     }
@@ -155,6 +163,42 @@ public ApiResponse<Void> deleteFile(@PathVariable Long draftId,
         return ok("response.success.deleted", null);
     }
 
+    // ---------------------------------------------------------------- runtime binding
+
+    @Operation(operationId = "getDraftRuntimeBinding", summary = "Get the draft's runtime binding")
+    @GetMapping("/drafts/{draftId}/runtime")
+    public ApiResponse<RuntimeBindingResponse> getRuntime(@PathVariable Long draftId,
+                                                          @RequestAttribute("userId") String userId,
+                                                          @RequestAttribute(value = "platformRoles", required = false)
+                                                          Set<String> platformRoles) {
+        draftService.getOwnedDraft(draftId, userId, platformRoles);
+        return ok("response.success", bindingService.findBinding(draftId)
+                .map(this::toRuntimeResponse)
+                .orElseGet(() -> new RuntimeBindingResponse(null, Map.of(), List.of(), List.of(), null)));
+    }
+
+    @Operation(operationId = "saveDraftRuntimeBinding", summary = "Configure the agent runtime, tools, and MCP servers")
+    @PutMapping("/drafts/{draftId}/runtime")
+    public ApiResponse<RuntimeBindingResponse> saveRuntime(@PathVariable Long draftId,
+                                                           @Valid @RequestBody RuntimeBindingRequest request,
+                                                           @RequestAttribute("userId") String userId,
+                                                           @RequestAttribute(value = "platformRoles", required = false)
+                                                           Set<String> platformRoles) {
+        return ok("response.success.updated", toRuntimeResponse(bindingService.saveBinding(
+                draftId, userId, request.agentType(), request.config(),
+                request.toolAllowlist(), request.mcpServers(), platformRoles)));
+    }
+
+    private RuntimeBindingResponse toRuntimeResponse(
+            com.iflytek.skillhub.domain.authoring.RuntimeBinding binding) {
+        return new RuntimeBindingResponse(
+                binding.getAgentType().identifier(),
+                binding.getConfig() == null ? Map.of() : binding.getConfig(),
+                binding.getToolAllowlist() == null ? List.of() : binding.getToolAllowlist(),
+                binding.getMcpServers() == null ? List.of() : binding.getMcpServers(),
+                binding.getUpdatedAt());
+    }
+
     // ---------------------------------------------------------------- validation runs
 
     @Operation(operationId = "startValidationRun", summary = "Start a validation run for the draft's current revision")
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/RuntimeBindingRequest.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/RuntimeBindingRequest.java
new file mode 100644
index 000000000..2a2cef8f0
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/RuntimeBindingRequest.java
@@ -0,0 +1,18 @@
+package com.iflytek.skillhub.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Request body for the per-draft runtime binding: which agent runtime executes
+ * behavior tasks, its adapter configuration, the tool allowlist, and MCP server
+ * declarations. Credentials must be referenced by name, never inlined.
+ */
+public record RuntimeBindingRequest(
+        @NotBlank(message = "{error.badRequest}") String agentType,
+        Map<String, Object> config,
+        List<String> toolAllowlist,
+        List<Map<String, Object>> mcpServers
+) {
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/RuntimeBindingResponse.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/RuntimeBindingResponse.java
new file mode 100644
index 000000000..7489cbb64
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/RuntimeBindingResponse.java
@@ -0,0 +1,15 @@
+package com.iflytek.skillhub.dto;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+
+/** Runtime binding as seen by the authoring UI. */
+public record RuntimeBindingResponse(
+        String agentType,
+        Map<String, Object> config,
+        List<String> toolAllowlist,
+        List<Map<String, Object>> mcpServers,
+        Instant updatedAt
+) {
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestrator.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestrator.java
index 2a0c36ab7..3789c2774 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestrator.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestrator.java
@@ -1,9 +1,22 @@
 package com.iflytek.skillhub.service.authoring;
 
 import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.RuntimeBinding;
+import com.iflytek.skillhub.domain.authoring.runtime.AssertionEvaluator;
+import com.iflytek.skillhub.domain.authoring.runtime.AssertionFailure;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeEventSink;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeExecutionContext;
+import com.iflytek.skillhub.domain.authoring.runtime.SkillRuntimeAdapter;
+import com.iflytek.skillhub.domain.authoring.runtime.TaskResult;
 import com.iflytek.skillhub.domain.authoring.service.DraftStructureValidator;
+import com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService;
+import com.iflytek.skillhub.domain.authoring.service.RuntimeBindingValidator;
 import com.iflytek.skillhub.domain.authoring.service.SkillDraftService;
 import com.iflytek.skillhub.domain.authoring.service.ValidationRunService;
+import com.iflytek.skillhub.domain.authoring.spec.TaskType;
+import com.iflytek.skillhub.domain.authoring.spec.ValidationSpec;
+import com.iflytek.skillhub.domain.authoring.spec.ValidationSpecParser;
+import com.iflytek.skillhub.domain.authoring.spec.ValidationTaskSpec;
 import com.iflytek.skillhub.domain.authoring.validation.FindingDraft;
 import com.iflytek.skillhub.domain.authoring.validation.FindingSeverity;
 import com.iflytek.skillhub.domain.authoring.validation.ValidationEvent;
@@ -13,62 +26,88 @@
 import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
 import com.iflytek.skillhub.domain.authoring.validation.ValidationRunStatus;
 import com.iflytek.skillhub.domain.shared.exception.DomainConflictException;
+import com.iflytek.skillhub.domain.skill.validation.PackageEntry;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.ArrayList;
+import java.util.Comparator;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.Executor;
 import java.util.concurrent.FutureTask;
+import java.util.concurrent.RejectedExecutionException;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
-import java.util.concurrent.RejectedExecutionException;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Service;
 
 /**
- * Executes validation runs for skill drafts. This layer runs the STRUCTURE
- * phase: package layout, SKILL.md frontmatter and file limits, reported as
- * structured findings with fix suggestions. The CONFIG and BEHAVIOR phases
- * (runtime binding, MCP probing, script/LLM task execution) arrive with the
- * runtime layer.
+ * Executes validation runs for skill drafts. The STRUCTURE layer validates package
+ * layout and SKILL.md frontmatter; the CONFIG layer parses validation.yaml, checks
+ * the runtime binding and probes declared MCP servers; the BEHAVIOR layer executes
+ * the spec's tasks through the bound runtime adapter and evaluates assertions.
+ *
+ * <p>The MCP probe of declared servers and the OpenAI-compatible prompt
+ * adapter arrive with the MCP+security layer; this layer executes script
+ * tasks through the local-script (inline or docker) adapter.
+ *
+ * <p>Run lifecycle hardening follows the merged upstream review: one FutureTask per
+ * run (duplicate submits are ignored), a hard wall-clock watchdog on the timer,
+ * cancellation settles first and then interrupts the worker, and the terminal
+ * event is appended exactly once.
  */
 @Service
 public class ValidationRunOrchestrator {
 
     private static final Logger log = LoggerFactory.getLogger(ValidationRunOrchestrator.class);
+    private static final String SPEC_FILE = ValidationSpec.FILE_PATH;
     private static final int MAX_EVENT_TEXT = 4_000;
 
     private final ValidationRunService runService;
     private final SkillDraftService draftService;
+    private final RuntimeBindingService bindingService;
     private final DraftStructureValidator structureValidator;
+    private final RuntimeBindingValidator bindingValidator;
+    private final ValidationSpecParser specParser = new ValidationSpecParser();
+    private final AssertionEvaluator assertionEvaluator = new AssertionEvaluator();
+    private final List<SkillRuntimeAdapter> adapters;
     private final ValidationEventBroadcaster broadcaster;
+    private final AuthoringProperties properties;
     private final Executor executor;
 
     private final ScheduledExecutorService timer;
-    private final AuthoringProperties properties;
     private final Map<Long, FutureTask<Void>> tasks = new ConcurrentHashMap<>();
 
     public ValidationRunOrchestrator(ValidationRunService runService,
                                      SkillDraftService draftService,
+                                     RuntimeBindingService bindingService,
                                      DraftStructureValidator structureValidator,
+                                     RuntimeBindingValidator bindingValidator,
+                                     List<SkillRuntimeAdapter> adapters,
                                      ValidationEventBroadcaster broadcaster,
+                                     AuthoringProperties properties,
                                      @Qualifier("authoringValidationExecutor") Executor executor,
-                                     @Qualifier("authoringValidationTimer") ScheduledExecutorService timer,
-                                     AuthoringProperties properties) {
+                                     @Qualifier("authoringValidationTimer") ScheduledExecutorService timer) {
         this.runService = runService;
         this.draftService = draftService;
+        this.bindingService = bindingService;
         this.structureValidator = structureValidator;
+        this.bindingValidator = bindingValidator;
+        this.adapters = List.copyOf(adapters);
         this.broadcaster = broadcaster;
+        this.properties = properties;
         this.executor = executor;
         this.timer = timer;
-        this.properties = properties;
     }
 
-    /** Enqueues one QUEUED run for execution. */
+    /** Enqueues one QUEUED run for execution; duplicate submits for the same run are ignored. */
     public void submit(Long runId) {
         FutureTask<Void> task = new FutureTask<>(() -> { executeRun(runId); return null; }) {
             @Override protected void done() { tasks.remove(runId, this); }
@@ -168,6 +207,7 @@ private void executePipeline(ValidationRun run) {
                 "draftName", snapshot.name(),
                 "draftRevision", run.getDraftRevision()));
 
+        Path workspace = workspaceFor(runId);
         try {
             // ---- STRUCTURE layer
             emit(runId, ValidationEventType.PHASE_STARTED, "STRUCTURE", Map.of());
@@ -179,20 +219,191 @@ private void executePipeline(ValidationRun run) {
                     "errors", context.errorCount(ValidationLayer.STRUCTURE),
                     "warnings", context.warningCount(ValidationLayer.STRUCTURE)));
 
+            // ---- CONFIG layer
+            emit(runId, ValidationEventType.PHASE_STARTED, "CONFIG", Map.of());
+            ValidationSpec spec = runConfigLayer(context, run, snapshot.entries());
+            emit(runId, ValidationEventType.PHASE_FINISHED, "CONFIG", Map.of(
+                    "errors", context.errorCount(ValidationLayer.CONFIG),
+                    "warnings", context.warningCount(ValidationLayer.CONFIG)));
+
+            // ---- BEHAVIOR layer
+            emit(runId, ValidationEventType.PHASE_STARTED, "BEHAVIOR", Map.of());
+            boolean blocked = context.errorCount(ValidationLayer.STRUCTURE) > 0
+                    || context.errorCount(ValidationLayer.CONFIG) > 0;
+            if (blocked) {
+                emit(runId, ValidationEventType.PHASE_FINISHED, "BEHAVIOR",
+                        Map.of("skipped", true, "reason", "structure or configuration errors"));
+            } else {
+                materializeWorkspace(workspace, snapshot.entries());
+                BehaviorOutcome outcome = runBehaviorLayer(context, run, spec, workspace);
+                if (outcome.interrupted()) {
+                    return; // already settled (CANCELLED / TIMED_OUT) with terminal event
+                }
+                emit(runId, ValidationEventType.PHASE_FINISHED, "BEHAVIOR", Map.of(
+                        "skipped", false,
+                        "tasksRun", context.tasksRun,
+                        "tasksFailed", context.tasksFailed));
+            }
+
             settle(runId,
                     context.errorCount == 0 ? ValidationRunStatus.SUCCEEDED : ValidationRunStatus.FAILED,
-                    context.errorCount, context.warningCount, summary(context));
+                    context.errorCount, context.warningCount, summary(context, blocked));
         } catch (DomainConflictException exception) {
             throw exception;
         } catch (Exception exception) {
             log.error("Validation pipeline for run {} failed", runId, exception);
             settle(runId, ValidationRunStatus.FAILED, context.errorCount + 1, context.warningCount,
                     Map.of("internalError", truncate(String.valueOf(exception.getMessage()), 500)));
+        } finally {
+            deleteRecursively(workspace);
         }
     }
 
-    // ---------------------------------------------------------------- events
+    // ---------------------------------------------------------------- config layer
+
+    private ValidationSpec runConfigLayer(RunContext context, ValidationRun run,
+                                          List<PackageEntry> entries) {
+        String specContent = readEntryText(entries, SPEC_FILE);
+        ValidationSpec spec = ValidationSpec.empty();
+        if (specContent == null) {
+            context.recordFinding(FindingDraft.warning(ValidationLayer.CONFIG, "SPEC_MISSING",
+                    SPEC_FILE, "validation.yaml is absent; behavior layer runs zero tasks"));
+        } else {
+            ValidationSpecParser.ParseOutcome outcome = specParser.parse(specContent);
+            outcome.errors().forEach(error -> context.recordFinding(FindingDraft.error(
+                    ValidationLayer.CONFIG, error.ruleCode(), SPEC_FILE, error.message(), null)));
+            if (outcome.isValid()) {
+                spec = outcome.spec();
+            }
+        }
+
+        // The binding is checked (and its MCP servers probed) even when
+        // validation.yaml is absent: a binding that cannot work must fail the
+        // run here, not surface for the first time at submit.
+        RuntimeBinding binding = bindingService.findBinding(run.getDraftId()).orElse(null);
+        if (binding == null) {
+            if (!spec.safeTasks().isEmpty()) {
+                context.recordFinding(FindingDraft.error(ValidationLayer.CONFIG, "BINDING_MISSING",
+                        "No runtime binding configured, but validation.yaml declares "
+                                + spec.safeTasks().size() + " task(s)"));
+            }
+            return spec;
+        }
+
+        bindingValidator.validate(
+                        binding.getAgentType().identifier(),
+                        binding.getConfig(),
+                        binding.getToolAllowlist(),
+                        binding.getMcpServers())
+                .forEach(context::recordFinding);
+
+        SkillRuntimeAdapter adapter = findAdapter(binding.getAgentType().identifier());
+        if (adapter == null) {
+            context.recordFinding(FindingDraft.error(ValidationLayer.CONFIG, "ADAPTER_NOT_FOUND",
+                    "No runtime adapter is registered for agent type '"
+                            + binding.getAgentType().identifier() + "'"));
+        } else if (!adapter.enabled()) {
+            context.recordFinding(FindingDraft.error(ValidationLayer.CONFIG, "RUNTIME_DISABLED",
+                    "Runtime '" + binding.getAgentType().identifier()
+                            + "' is disabled in server configuration"));
+        }
 
+        for (ValidationTaskSpec task : spec.safeTasks()) {
+            assertionEvaluator.validateSyntax(task.safeAssertions(), task.type() == TaskType.PROMPT)
+                    .forEach(problem -> context.recordFinding(FindingDraft.error(
+                            ValidationLayer.CONFIG, "ASSERTION_INVALID", SPEC_FILE,
+                            "task '" + task.name() + "': " + problem, null)));
+        }
+        return spec;
+    }
+
+    // ---------------------------------------------------------------- behavior layer
+
+    private BehaviorOutcome runBehaviorLayer(RunContext context, ValidationRun run,
+                                             ValidationSpec spec, Path workspace) {
+        RuntimeBinding binding = bindingService.findBinding(run.getDraftId()).orElse(null);
+        if (binding == null || spec.safeTasks().isEmpty()) {
+            return BehaviorOutcome.COMPLETED;
+        }
+        SkillRuntimeAdapter adapter = findAdapter(binding.getAgentType().identifier());
+        if (adapter == null || !adapter.enabled()) {
+            return BehaviorOutcome.COMPLETED; // already reported by the config layer
+        }
+
+        long deadline = System.currentTimeMillis() + properties.getRunTimeoutMs();
+        Map<String, Object> adapterConfig = binding.getConfig() == null
+                ? Map.of() : binding.getConfig();
+        List<String> toolAllowlist = binding.getToolAllowlist() == null
+                ? List.of() : binding.getToolAllowlist();
+        RuntimeExecutionContext executionContext = new RuntimeExecutionContext(
+                run.getId(), workspace, adapterConfig, toolAllowlist,
+                binding.getMcpServers() == null ? List.of() : binding.getMcpServers(),
+                // cancellation settles first and interrupts the worker, so the
+                // cooperative signal is the interrupt status of this thread
+                () -> Thread.currentThread().isInterrupted());
+
+        for (ValidationTaskSpec task : spec.safeTasks()) {
+            if (Thread.currentThread().isInterrupted()) {
+                return BehaviorOutcome.interrupted("cancelled");
+            }
+            if (System.currentTimeMillis() > deadline) {
+                settle(run.getId(), ValidationRunStatus.TIMED_OUT,
+                        context.errorCount, context.warningCount, summary(context, false));
+                return BehaviorOutcome.interrupted("timeout");
+            }
+            executeTask(context, adapter, executionContext, task, workspace);
+        }
+        return BehaviorOutcome.COMPLETED;
+    }
+
+    private void executeTask(RunContext context, SkillRuntimeAdapter adapter,
+                             RuntimeExecutionContext executionContext, ValidationTaskSpec task,
+                             Path workspace) {
+        if (!adapter.supports(task.type())) {
+            context.tasksFailed++;
+            context.recordFinding(FindingDraft.error(ValidationLayer.BEHAVIOR, "ADAPTER_TASK_UNSUPPORTED",
+                    SPEC_FILE, "runtime '" + adapter.agentType() + "' cannot execute "
+                            + task.type() + " task '" + task.name() + "'", null));
+            return;
+        }
+        if (task.type() == TaskType.SCRIPT && !scriptExists(workspace, task.script())) {
+            context.tasksFailed++;
+            context.recordFinding(FindingDraft.error(ValidationLayer.BEHAVIOR, "TASK_SCRIPT_MISSING",
+                    task.script(), "script file not found in the skill: " + task.script(), null));
+            return;
+        }
+
+        context.tasksRun++;
+        TaskResult result;
+        try {
+            result = adapter.execute(executionContext, task, context.sink());
+        } catch (Exception exception) {
+            context.tasksFailed++;
+            context.recordFinding(FindingDraft.error(ValidationLayer.BEHAVIOR, "TASK_FAILED",
+                    SPEC_FILE, "task '" + task.name() + "' failed: "
+                            + truncate(String.valueOf(exception.getMessage()), 500), null));
+            return;
+        }
+
+        List<AssertionFailure> failures =
+                assertionEvaluator.evaluate(task.safeAssertions(), result);
+        if (failures.isEmpty()) {
+            emit(context.runId, ValidationEventType.LOG, "BEHAVIOR", Map.of(
+                    "task", task.name(), "stream", "summary",
+                    "line", "task '" + task.name() + "' passed "
+                            + task.safeAssertions().size() + " assertion(s)"));
+            return;
+        }
+        context.tasksFailed++;
+        for (AssertionFailure failure : failures) {
+            context.recordFinding(FindingDraft.error(ValidationLayer.BEHAVIOR, "ASSERTION_FAILED",
+                    SPEC_FILE, "task '" + task.name() + "': " + failure.describe(), null));
+        }
+    }
+
+    // ---------------------------------------------------------------- events & terminal handling
+
+    /** Emits one event, persists it, and pushes it to live SSE subscribers. */
     private void emit(Long runId, ValidationEventType type, String phase, Map<String, Object> payload) {
         ValidationEvent event = runService.appendEvent(runId, type, phase, payload);
         broadcaster.publish(runId, event);
@@ -208,15 +419,75 @@ private void emitTerminalOnce(Long runId) {
 
     // ---------------------------------------------------------------- small helpers
 
-    private Map<String, Object> summary(RunContext context) {
+    private boolean scriptExists(Path workspace, String script) {
+        try {
+            Path resolved = workspace.resolve(script).normalize();
+            return resolved.startsWith(workspace.normalize()) && Files.isRegularFile(resolved);
+        } catch (Exception exception) {
+            return false;
+        }
+    }
+
+    private SkillRuntimeAdapter findAdapter(String agentType) {
+        return adapters.stream()
+                .filter(adapter -> adapter.agentType().equals(agentType))
+                .findFirst()
+                .orElse(null);
+    }
+
+    private Map<String, Object> summary(RunContext context, boolean behaviorSkipped) {
         Map<String, Object> summary = new java.util.LinkedHashMap<>();
         summary.put("structureErrors", context.errorCount(ValidationLayer.STRUCTURE));
         summary.put("structureWarnings", context.warningCount(ValidationLayer.STRUCTURE));
+        summary.put("configErrors", context.errorCount(ValidationLayer.CONFIG));
+        summary.put("configWarnings", context.warningCount(ValidationLayer.CONFIG));
+        summary.put("behaviorTasksRun", context.tasksRun);
+        summary.put("behaviorTasksFailed", context.tasksFailed);
+        summary.put("behaviorSkipped", behaviorSkipped);
         summary.put("errorCount", context.errorCount);
         summary.put("warningCount", context.warningCount);
         return summary;
     }
 
+    private Path workspaceFor(Long runId) {
+        return Path.of(properties.getWorkspaceRoot(), "run-" + runId);
+    }
+
+    private void materializeWorkspace(Path workspace, List<PackageEntry> entries)
+            throws IOException {
+        Files.createDirectories(workspace);
+        for (PackageEntry entry : entries) {
+            Path target = workspace.resolve(entry.path()).normalize();
+            if (!target.startsWith(workspace.normalize())) {
+                throw new IOException("package entry escapes the workspace: " + entry.path());
+            }
+            Files.createDirectories(target.getParent());
+            Files.write(target, entry.content());
+        }
+    }
+
+    private String readEntryText(List<PackageEntry> entries, String path) {
+        return entries.stream()
+                .filter(entry -> entry.path().equals(path))
+                .findFirst()
+                .map(entry -> new String(entry.content(), StandardCharsets.UTF_8))
+                .orElse(null);
+    }
+
+    private void deleteRecursively(Path root) {
+        try (var stream = Files.walk(root)) {
+            stream.sorted(Comparator.reverseOrder()).forEach(p -> {
+                try {
+                    Files.deleteIfExists(p);
+                } catch (IOException exception) {
+                    log.warn("Could not delete workspace file {}", p, exception);
+                }
+            });
+        } catch (IOException exception) {
+            log.warn("Could not clean up workspace {}", root, exception);
+        }
+    }
+
     private static String truncate(String value, int limit) {
         if (value == null) {
             return "";
@@ -224,6 +495,15 @@ private static String truncate(String value, int limit) {
         return value.length() <= limit ? value : value.substring(0, limit) + "…";
     }
 
+    private record BehaviorOutcome(boolean interrupted, String reason) {
+
+        static BehaviorOutcome COMPLETED = new BehaviorOutcome(false, null);
+
+        static BehaviorOutcome interrupted(String reason) {
+            return new BehaviorOutcome(true, reason);
+        }
+    }
+
     /** Per-run finding bookkeeping; each finding is persisted and emitted as an event. */
     private final class RunContext {
 
@@ -231,6 +511,8 @@ private final class RunContext {
         private final List<FindingDraft> findings = new ArrayList<>();
         private int errorCount;
         private int warningCount;
+        private int tasksRun;
+        private int tasksFailed;
 
         RunContext(Long runId) {
             this.runId = runId;
@@ -267,5 +549,37 @@ void recordFinding(FindingDraft draft) {
                     "message", truncate(draft.message(), MAX_EVENT_TEXT),
                     "hasSuggestion", draft.suggestion() != null));
         }
+
+        /** Serialized sink so per-run event sequence numbers cannot race. */
+        RuntimeEventSink sink() {
+            return new RuntimeEventSink() {
+                @Override
+                public synchronized void agentMessage(String taskName, String content) {
+                    emit(runId, ValidationEventType.AGENT_MESSAGE, "BEHAVIOR", Map.of(
+                            "task", taskName, "content", truncate(content, MAX_EVENT_TEXT)));
+                }
+
+                @Override
+                public synchronized void toolCall(String taskName, String tool, String argumentsJson) {
+                    emit(runId, ValidationEventType.TOOL_CALL, "BEHAVIOR", Map.of(
+                            "task", taskName, "tool", tool,
+                            "arguments", truncate(argumentsJson, MAX_EVENT_TEXT)));
+                }
+
+                @Override
+                public synchronized void toolResult(String taskName, String tool, String summaryJson) {
+                    emit(runId, ValidationEventType.TOOL_RESULT, "BEHAVIOR", Map.of(
+                            "task", taskName, "tool", tool,
+                            "summary", truncate(summaryJson, MAX_EVENT_TEXT)));
+                }
+
+                @Override
+                public synchronized void log(String taskName, String stream, String line) {
+                    emit(runId, ValidationEventType.LOG, "BEHAVIOR", Map.of(
+                            "task", taskName, "stream", stream,
+                            "line", truncate(line, 2_000)));
+                }
+            };
+        }
     }
 }
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/DockerScriptCommandBuilder.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/DockerScriptCommandBuilder.java
new file mode 100644
index 000000000..67d112618
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/DockerScriptCommandBuilder.java
@@ -0,0 +1,230 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import com.iflytek.skillhub.config.AuthoringProperties;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Component;
+
+/**
+ * Production backend: the script runs inside a throwaway container with a hard
+ * isolation profile — no network, memory/CPU/pids caps, read-only root filesystem,
+ * all capabilities dropped, no-new-privileges, no log persistence. Only the
+ * validation workspace is mounted (read-write) so scripts can produce artifacts;
+ * every other path the container sees is immutable or ephemeral tmpfs.
+ *
+ * <p>Network isolation is deliberately not configurable: a validation run must
+ * never be able to reach other services. The image must provide the configured
+ * interpreter (the default alpine ships {@code sh}; python/node skills need a
+ * matching image).
+ */
+@Component
+public class DockerScriptCommandBuilder implements ScriptCommandBuilder {
+
+    /** Mount point of the validation workspace inside the container. */
+    public static final String CONTAINER_WORKSPACE = "/workspace";
+
+    private static final Logger log = LoggerFactory.getLogger(DockerScriptCommandBuilder.class);
+    private static final Duration PROBE_TIMEOUT = Duration.ofSeconds(5);
+    private static final Duration CLEANUP_TIMEOUT = Duration.ofSeconds(5);
+
+    private final AuthoringProperties properties;
+    private volatile Boolean daemonReachable;
+
+    public DockerScriptCommandBuilder(AuthoringProperties properties) {
+        this.properties = properties;
+    }
+
+    @Override
+    public String backend() {
+        return "docker";
+    }
+
+    @Override
+    public boolean available() {
+        Boolean cached = daemonReachable;
+        if (cached == null) {
+            cached = probeDaemon();
+            daemonReachable = cached;
+        }
+        return cached;
+    }
+
+    /** Re-probes the daemon on the next {@link #available()} call. */
+    void resetProbe() {
+        daemonReachable = null;
+    }
+
+    private boolean probeDaemon() {
+        try {
+            Process process = new ProcessBuilder("docker", "info", "--format", "{{.ServerVersion}}")
+                    .start();
+            if (!process.waitFor(PROBE_TIMEOUT.toMillis(), TimeUnit.MILLISECONDS)) {
+                process.destroyForcibly();
+                return false;
+            }
+            return process.exitValue() == 0;
+        } catch (IOException | InterruptedException exception) {
+            return false;
+        }
+    }
+
+    @Override
+    public ScriptExecutionPlan plan(Path workspace, String interpreter, Path scriptPath,
+                                    List<String> args, Map<String, String> scrubbedEnvironment,
+                                    String runTag) {
+        AuthoringProperties.LocalScript.Docker docker = properties.getLocalScript().getDocker();
+        String hostWorkspace = realPath(workspace);
+        ensureContainerReadable(workspace);
+
+        List<String> command = new ArrayList<>();
+        command.add("docker");
+        command.add("run");
+        command.add("--rm");
+        command.add("--name");
+        command.add(containerName(runTag));
+        hostUser().ifPresent(user -> {
+            command.add("--user");
+            command.add(user);
+        });
+        command.add("--network");
+        command.add("none");
+        command.add("--memory");
+        command.add(docker.getMemory());
+        command.add("--cpus");
+        command.add(docker.getCpus());
+        command.add("--pids-limit");
+        command.add(String.valueOf(docker.getPidsLimit()));
+        command.add("--read-only");
+        command.add("--tmpfs");
+        command.add("/tmp:rw,size=" + docker.getTmpfsSize());
+        command.add("--cap-drop");
+        command.add("ALL");
+        command.add("--security-opt");
+        command.add("no-new-privileges");
+        command.add("--log-driver");
+        command.add("none");
+        for (Map.Entry<String, String> entry : scrubbedEnvironment.entrySet()) {
+            command.add("-e");
+            command.add(entry.getKey() + "=" + containerEnvValue(entry.getKey(), entry.getValue()));
+        }
+        command.add("-v");
+        command.add(hostWorkspace + ":" + CONTAINER_WORKSPACE);
+        command.add("-w");
+        command.add(CONTAINER_WORKSPACE);
+        command.add(docker.getImage());
+        command.add(interpreter);
+        command.add(containerScriptPath(workspace, scriptPath));
+        command.addAll(args);
+        // the docker CLI needs its own environment to reach the daemon; the script
+        // only sees the -e variables above, inside the container
+        return ScriptExecutionPlan.inherited(List.copyOf(command));
+    }
+
+    @Override
+    public void cleanup(String runTag) {
+        try {
+            Process process = new ProcessBuilder("docker", "rm", "-f", containerName(runTag)).start();
+            if (!process.waitFor(CLEANUP_TIMEOUT.toMillis(), TimeUnit.MILLISECONDS)) {
+                process.destroyForcibly();
+            }
+        } catch (IOException | InterruptedException exception) {
+            log.warn("Could not force-remove validation container {}: {}",
+                    containerName(runTag), exception.getMessage());
+        }
+    }
+
+
+    /** Cached "uid:gid" of the host JVM user, so container-created files stay deletable. */
+    private static final java.util.Optional<String> HOST_USER = resolveHostUser();
+
+    private static java.util.Optional<String> resolveHostUser() {
+        try {
+            String uid = readCommandOutput("id", "-u").trim();
+            String gid = readCommandOutput("id", "-g").trim();
+            if (uid.matches("\\d+") && gid.matches("\\d+")) {
+                return java.util.Optional.of(uid + ":" + gid);
+            }
+        } catch (Exception exception) {
+            // non-POSIX host (e.g. Windows without id): run as the image default
+        }
+        return java.util.Optional.empty();
+    }
+
+    private static String readCommandOutput(String... command) throws Exception {
+        Process process = new ProcessBuilder(command).start();
+        String output;
+        try (var reader = process.inputReader()) {
+            output = reader.lines().findFirst().orElse("");
+        }
+        process.waitFor();
+        return output;
+    }
+
+    private static java.util.Optional<String> hostUser() {
+        return HOST_USER;
+    }
+
+    /**
+     * The container drops every capability (including DAC_OVERRIDE), so the
+     * workspace files must be world-readable (and directories traversable)
+     * on the host or the in-container interpreter cannot open them. Fresh JVM
+     * temp directories are owner-only on Linux, which would break script
+     * execution there; macOS Docker Desktop masks this by remapping
+     * ownership inside the VM.
+     */
+    private static void ensureContainerReadable(Path root) {
+        try (var stream = Files.walk(root)) {
+            stream.forEach(path -> {
+                try {
+                    if (Files.isDirectory(path)) {
+                        // traversable and writable so the script can create
+                        // artifacts inside the mounted workspace
+                        path.toFile().setExecutable(true, false);
+                        path.toFile().setWritable(true, false);
+                    }
+                    path.toFile().setReadable(true, false);
+                } catch (Exception exception) {
+                    // best effort: a locked file surfaces as a task failure
+                    // with the interpreter's own error message
+                }
+            });
+        } catch (IOException exception) {
+            // the mount itself will fail visibly if the tree is unreadable
+        }
+    }
+
+    /** Container names allow [a-zA-Z0-9][a-zA-Z0-9_.-]+. */
+    static String containerName(String runTag) {
+        String sanitized = runTag == null ? "unknown" : runTag.replaceAll("[^a-zA-Z0-9_.-]", "-");
+        if (sanitized.isEmpty() || !Character.isLetterOrDigit(sanitized.charAt(0))) {
+            sanitized = "r" + sanitized;
+        }
+        return "skillhub-validation-" + sanitized;
+    }
+
+    private String containerScriptPath(Path workspace, Path scriptPath) {
+        return CONTAINER_WORKSPACE + "/" + workspace.relativize(scriptPath);
+    }
+
+    /** HOME points at the workspace; inside the container that is the mount point. */
+    private String containerEnvValue(String key, String value) {
+        return "HOME".equals(key) ? CONTAINER_WORKSPACE : value;
+    }
+
+    /** Resolves symlinks (e.g. macOS /var/folders → /private/var/folders) for bind mounts. */
+    private String realPath(Path workspace) {
+        try {
+            return workspace.toRealPath().toString();
+        } catch (IOException exception) {
+            return workspace.toAbsolutePath().toString();
+        }
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/InlineScriptCommandBuilder.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/InlineScriptCommandBuilder.java
new file mode 100644
index 000000000..6873649af
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/InlineScriptCommandBuilder.java
@@ -0,0 +1,38 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import org.springframework.stereotype.Component;
+
+/**
+ * Default backend: the script runs as a plain subprocess of the server process
+ * with a scrubbed environment. Suitable for local development and CI where the
+ * drafts are the developer's own; production deployments should switch to the
+ * docker backend.
+ */
+@Component
+public class InlineScriptCommandBuilder implements ScriptCommandBuilder {
+
+    @Override
+    public String backend() {
+        return "inline";
+    }
+
+    @Override
+    public boolean available() {
+        return true;
+    }
+
+    @Override
+    public ScriptExecutionPlan plan(Path workspace, String interpreter, Path scriptPath,
+                                    List<String> args, Map<String, String> scrubbedEnvironment,
+                                    String runTag) {
+        List<String> command = new ArrayList<>();
+        command.add(interpreter);
+        command.add(scriptPath.toString());
+        command.addAll(args);
+        return new ScriptExecutionPlan(List.copyOf(command), Map.copyOf(scrubbedEnvironment));
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptRuntimeAdapter.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptRuntimeAdapter.java
new file mode 100644
index 000000000..df1f1ae7f
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptRuntimeAdapter.java
@@ -0,0 +1,237 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeEventSink;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeExecutionContext;
+import com.iflytek.skillhub.domain.authoring.runtime.SkillRuntimeAdapter;
+import com.iflytek.skillhub.domain.authoring.runtime.TaskResult;
+import com.iflytek.skillhub.domain.authoring.spec.TaskType;
+import com.iflytek.skillhub.domain.authoring.spec.ValidationTaskSpec;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+import org.springframework.stereotype.Component;
+
+/**
+ * Behavior-layer adapter that executes the skill's own scripts in an isolated working
+ * directory with a scrubbed environment. Only whitelisted interpreters may run and only
+ * environment variables named in the binding's {@code envAllowlist} pass through.
+ *
+ * <p>Where the process actually runs is delegated to a {@link ScriptCommandBuilder}:
+ * the inline backend spawns the interpreter on the server host, the docker backend
+ * wraps it in a locked-down container. Everything else (streaming, buffering, timeout,
+ * cancel) is backend-independent.
+ */
+@Component
+public class LocalScriptRuntimeAdapter implements SkillRuntimeAdapter {
+
+    private static final int MAX_STREAM_BUFFER = 256 * 1024;
+    private static final long POLL_SLICE_MS = 200;
+
+    private final AuthoringProperties properties;
+    private final Map<String, ScriptCommandBuilder> commandBuilders;
+
+    public LocalScriptRuntimeAdapter(AuthoringProperties properties,
+                                     List<ScriptCommandBuilder> commandBuilders) {
+        this.properties = properties;
+        this.commandBuilders = commandBuilders.stream()
+                .collect(Collectors.toUnmodifiableMap(ScriptCommandBuilder::backend,
+                        Function.identity()));
+    }
+
+    @Override
+    public String agentType() {
+        return "local-script";
+    }
+
+    @Override
+    public boolean supports(TaskType taskType) {
+        return taskType == TaskType.SCRIPT;
+    }
+
+    @Override
+    public boolean enabled() {
+        return properties.getLocalScript().isEnabled() && commandBuilder().available();
+    }
+
+    @Override
+    public TaskResult execute(RuntimeExecutionContext context, ValidationTaskSpec task,
+                              RuntimeEventSink sink) throws Exception {
+        ScriptCommandBuilder builder = commandBuilder();
+        if (!builder.available()) {
+            throw new IllegalStateException(
+                    "script execution backend '" + builder.backend() + "' is not available"
+                            + " (is the docker daemon reachable?)");
+        }
+        String interpreter = resolveInterpreter(context);
+        Path scriptPath = resolveInsideWorkingDirectory(context.workingDirectory(), task.script());
+        String runTag = context.runId() + "-" + task.name();
+        Map<String, String> scrubbedEnvironment = scrubEnvironment(context);
+
+        ScriptCommandBuilder.ScriptExecutionPlan plan = builder.plan(
+                context.workingDirectory(), interpreter, scriptPath,
+                task.safeArgs(), scrubbedEnvironment, runTag);
+
+        sink.toolCall(task.name(), interpreter + " [" + builder.backend() + "]",
+                String.join(" ", task.safeArgs()));
+
+        ProcessBuilder processBuilder = new ProcessBuilder(plan.command());
+        processBuilder.directory(context.workingDirectory().toFile());
+        processBuilder.redirectErrorStream(false);
+        if (plan.environment() != null) {
+            processBuilder.environment().clear();
+            processBuilder.environment().putAll(plan.environment());
+        }
+
+        Process process = processBuilder.start();
+        BoundedBuffer stdout = new BoundedBuffer(MAX_STREAM_BUFFER);
+        BoundedBuffer stderr = new BoundedBuffer(MAX_STREAM_BUFFER);
+        Thread stdoutReader = streamReader(process.getInputStream(), "stdout", task.name(), stdout, sink);
+        Thread stderrReader = streamReader(process.getErrorStream(), "stderr", task.name(), stderr, sink);
+        stdoutReader.start();
+        stderrReader.start();
+
+        Integer exitCode = await(process, task, context, builder, runTag);
+        stdoutReader.join(TimeUnit.SECONDS.toMillis(5));
+        stderrReader.join(TimeUnit.SECONDS.toMillis(5));
+
+        sink.toolResult(task.name(), interpreter,
+                "{\"backend\":\"" + builder.backend() + "\",\"exitCode\":" + exitCode
+                        + ",\"stdoutBytes\":" + stdout.size()
+                        + ",\"stderrBytes\":" + stderr.size() + "}");
+
+        return TaskResult.ofScript(exitCode, stdout.content(), stderr.content(), 1,
+                new WorkingDirectoryArtifacts(context.workingDirectory()));
+    }
+
+    private ScriptCommandBuilder commandBuilder() {
+        String mode = properties.getLocalScript().getExecutionMode()
+                == AuthoringProperties.ScriptExecutionMode.DOCKER ? "docker" : "inline";
+        ScriptCommandBuilder builder = commandBuilders.get(mode);
+        if (builder == null) {
+            throw new IllegalStateException(
+                    "no script command builder registered for execution mode: " + mode);
+        }
+        return builder;
+    }
+
+    private String resolveInterpreter(RuntimeExecutionContext context) {
+        String configured = context.configString("interpreter");
+        if (configured != null && !configured.isBlank()) {
+            return configured;
+        }
+        return "sh";
+    }
+
+    private Map<String, String> scrubEnvironment(RuntimeExecutionContext context) {
+        Map<String, String> environment = new java.util.LinkedHashMap<>();
+        environment.put("PATH", System.getenv().getOrDefault("PATH", "/usr/bin:/bin"));
+        environment.put("HOME", context.workingDirectory().toString());
+        environment.put("LANG", "C.UTF-8");
+        Object allowlist = context.safeAdapterConfig().get("envAllowlist");
+        if (allowlist instanceof List<?> entries) {
+            for (Object entry : entries) {
+                if (entry != null) {
+                    String value = System.getenv(entry.toString());
+                    if (value != null) {
+                        environment.put(entry.toString(), value);
+                    }
+                }
+            }
+        }
+        return environment;
+    }
+
+    /**
+     * Waits for process exit while honoring the task timeout and the cooperative cancel
+     * signal. Returns the exit code, or {@code null} when the process had to be killed;
+     * abnormal exits also trigger the builder's cleanup (the docker backend must
+     * force-remove the container because killing the CLI client does not stop it).
+     */
+    private Integer await(Process process, ValidationTaskSpec task, RuntimeExecutionContext context,
+                          ScriptCommandBuilder builder, String runTag) throws InterruptedException {
+        long deadline = System.nanoTime() + Duration.ofMillis(task.timeoutMs()).toNanos();
+        while (true) {
+            if (process.waitFor(POLL_SLICE_MS, TimeUnit.MILLISECONDS)) {
+                return process.exitValue();
+            }
+            if (context.cancellation() != null && context.cancellation().isCancelRequested()) {
+                process.destroyForcibly();
+                process.waitFor(5, TimeUnit.SECONDS);
+                builder.cleanup(runTag);
+                return null;
+            }
+            if (System.nanoTime() > deadline) {
+                process.destroyForcibly();
+                process.waitFor(5, TimeUnit.SECONDS);
+                builder.cleanup(runTag);
+                throw new IllegalStateException(
+                        "task '" + task.name() + "' exceeded its timeout of " + task.timeoutMs() + " ms");
+            }
+        }
+    }
+
+    private Thread streamReader(java.io.InputStream stream, String streamName, String taskName,
+                                BoundedBuffer buffer, RuntimeEventSink sink) {
+        Thread thread = new Thread(() -> {
+            try (BufferedReader reader = new BufferedReader(
+                    new InputStreamReader(stream, StandardCharsets.UTF_8))) {
+                String line;
+                while ((line = reader.readLine()) != null) {
+                    buffer.append(line);
+                    sink.log(taskName, streamName, line);
+                }
+            } catch (IOException ignored) {
+                // stream closed when the process dies; buffered content is kept
+            }
+        }, "validation-stream-" + streamName);
+        thread.setDaemon(true);
+        return thread;
+    }
+
+    static Path resolveInsideWorkingDirectory(Path workingDirectory, String relativePath) {
+        Path resolved = workingDirectory.resolve(relativePath).normalize();
+        if (!resolved.startsWith(workingDirectory.normalize())) {
+            throw new IllegalArgumentException(
+                    "path escapes the working directory: " + relativePath);
+        }
+        return resolved;
+    }
+
+    /** Cap-aware single-stream buffer: keeps the head of the output for findings. */
+    private static final class BoundedBuffer {
+        private final StringBuilder builder = new StringBuilder();
+        private final int limit;
+
+        BoundedBuffer(int limit) {
+            this.limit = limit;
+        }
+
+        synchronized void append(String line) {
+            if (builder.length() >= limit) {
+                return;
+            }
+            if (builder.length() > 0) {
+                builder.append('\n');
+            }
+            builder.append(line, 0, Math.min(line.length(), limit - builder.length()));
+        }
+
+        synchronized String content() {
+            return builder.toString();
+        }
+
+        synchronized int size() {
+            return builder.length();
+        }
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/ScriptCommandBuilder.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/ScriptCommandBuilder.java
new file mode 100644
index 000000000..c257be56c
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/ScriptCommandBuilder.java
@@ -0,0 +1,53 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Builds the process command for one behavior-task script execution. Two backends
+ * ship: {@code inline} runs the script as a subprocess on the server host (local
+ * development only); {@code docker} runs it inside a locked-down container (no
+ * network, memory/CPU/pids caps, read-only root filesystem) for production.
+ */
+public interface ScriptCommandBuilder {
+
+    /** Backend identifier matching {@code skillhub.authoring.local-script.execution-mode}. */
+    String backend();
+
+    /** Whether the backend can execute right now (for docker: daemon reachable). */
+    boolean available();
+
+    /**
+     * Builds the execution plan for one task. {@code scrubbedEnvironment} carries
+     * exactly the variables the script may see; backends decide how to deliver
+     * them (inline: process environment; docker: {@code -e} flags, with the
+     * workspace path remapped to its mount point inside the container).
+     *
+     * @param runTag stable per-task tag (run id + task name), used for container
+     *               naming so abnormal exits can be force-removed
+     */
+    ScriptExecutionPlan plan(Path workspace, String interpreter, Path scriptPath,
+                             List<String> args, Map<String, String> scrubbedEnvironment,
+                             String runTag);
+
+    /**
+     * Best-effort cleanup after the wrapping process was killed (timeout or
+     * cancel). Killing the {@code docker run} client does not stop the container,
+     * so the docker backend force-removes it here.
+     */
+    default void cleanup(String runTag) {
+    }
+
+    /**
+     * Command line plus environment. A null environment means the spawned client
+     * (e.g. the docker CLI) needs the parent's environment intact; the isolation
+     * then lives in the container flags instead.
+     */
+    record ScriptExecutionPlan(List<String> command, Map<String, String> environment) {
+
+        public static ScriptExecutionPlan inherited(List<String> command) {
+            return new ScriptExecutionPlan(command, null);
+        }
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/WorkingDirectoryArtifacts.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/WorkingDirectoryArtifacts.java
new file mode 100644
index 000000000..25d6ae65f
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/WorkingDirectoryArtifacts.java
@@ -0,0 +1,30 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import com.iflytek.skillhub.domain.authoring.runtime.TaskResult;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Optional;
+
+/**
+ * Reads artifact files from a run's isolated working directory, rejecting paths that
+ * would escape it. Shared by all runtime adapters.
+ */
+record WorkingDirectoryArtifacts(Path workingDirectory) implements TaskResult.ArtifactResolver {
+
+    @Override
+    public Optional<byte[]> read(String relativePath) {
+        try {
+            Path resolved = workingDirectory.resolve(relativePath).normalize();
+            if (!resolved.startsWith(workingDirectory.normalize())) {
+                return Optional.empty();
+            }
+            if (!Files.isRegularFile(resolved)) {
+                return Optional.empty();
+            }
+            return Optional.of(Files.readAllBytes(resolved));
+        } catch (IllegalArgumentException | IOException exception) {
+            return Optional.empty();
+        }
+    }
+}
diff --git a/server/skillhub-app/src/main/resources/application.yml b/server/skillhub-app/src/main/resources/application.yml
index 3b2f58f82..d7afab883 100644
--- a/server/skillhub-app/src/main/resources/application.yml
+++ b/server/skillhub-app/src/main/resources/application.yml
@@ -142,6 +142,21 @@ skillhub:
     run-timeout-ms: ${SKILLHUB_AUTHORING_RUN_TIMEOUT_MS:900000}
     # Active runs older than this are swept to TIMED_OUT (crash recovery)
     stale-run-minutes: ${SKILLHUB_AUTHORING_STALE_RUN_MINUTES:30}
+    maintenance-interval-ms: ${SKILLHUB_AUTHORING_MAINTENANCE_INTERVAL_MS:30000}
+    local-script:
+      enabled: ${SKILLHUB_AUTHORING_LOCAL_SCRIPT_ENABLED:true}
+      # docker is the production default: scripts run in a locked-down container —
+      # no network, memory/cpu/pids caps, read-only rootfs, all capabilities dropped.
+      # inline runs subprocesses on the server host and is only allowed with a
+      # local/dev/test profile (the startup guard fails fast otherwise).
+      execution-mode: ${SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE:docker}
+      docker:
+        # must provide the interpreters your skills use (alpine ships sh only)
+        image: ${SKILLHUB_AUTHORING_DOCKER_IMAGE:alpine:3.20}
+        memory: ${SKILLHUB_AUTHORING_DOCKER_MEMORY:256m}
+        cpus: ${SKILLHUB_AUTHORING_DOCKER_CPUS:1.0}
+        pids-limit: ${SKILLHUB_AUTHORING_DOCKER_PIDS_LIMIT:128}
+        tmpfs-size: ${SKILLHUB_AUTHORING_DOCKER_TMPFS_SIZE:64m}
   github-sync:
     discovery-scheduler-interval-ms: ${SKILLHUB_GITHUB_SYNC_DISCOVERY_SCHEDULER_INTERVAL_MS:60000}
     candidate-scheduler-interval-ms: ${SKILLHUB_GITHUB_SYNC_CANDIDATE_SCHEDULER_INTERVAL_MS:60000}
diff --git a/server/skillhub-app/src/main/resources/messages.properties b/server/skillhub-app/src/main/resources/messages.properties
index 56bf53a85..260d1a345 100644
--- a/server/skillhub-app/src/main/resources/messages.properties
+++ b/server/skillhub-app/src/main/resources/messages.properties
@@ -392,3 +392,8 @@ error.githubSync.deepDiscovery.exclusionInvalid=Exclusions must be valid GitHub
 error.githubSync.deepDiscovery.configurationConflict=Official discovery configuration has changed. Reload the latest configuration before saving
 
 error.githubSync.deepDiscovery.queryInvalid=Invalid deep discovery query parameters.
+# authoring runtime bindings
+error.authoring.binding.notFound=No runtime binding configured for draft {0}
+error.authoring.binding.agentType.unknown=Unknown agent runtime type: {0}
+error.authoring.binding.invalid=Invalid runtime binding: {0}
+error.authoring.binding.unserializable=Runtime binding could not be serialized
diff --git a/server/skillhub-app/src/main/resources/messages_ru.properties b/server/skillhub-app/src/main/resources/messages_ru.properties
index 3b7efbb1b..c587af936 100644
--- a/server/skillhub-app/src/main/resources/messages_ru.properties
+++ b/server/skillhub-app/src/main/resources/messages_ru.properties
@@ -335,3 +335,8 @@ error.githubSync.deepDiscovery.exclusionInvalid=Исключения должн
 error.githubSync.deepDiscovery.configurationConflict=Конфигурация официального поиска изменена. Загрузите актуальную конфигурацию перед сохранением
 
 error.githubSync.deepDiscovery.queryInvalid=Недопустимые параметры запроса глубокого обнаружения.
+# authoring runtime bindings
+error.authoring.binding.notFound=Для черновика {0} не настроена привязка среды выполнения
+error.authoring.binding.agentType.unknown=Неизвестный тип среды выполнения агента: {0}
+error.authoring.binding.invalid=Недопустимая привязка среды выполнения: {0}
+error.authoring.binding.unserializable=Привязка среды выполнения не может быть сериализована
diff --git a/server/skillhub-app/src/main/resources/messages_zh.properties b/server/skillhub-app/src/main/resources/messages_zh.properties
index 6b2787c2e..7ee2465e8 100644
--- a/server/skillhub-app/src/main/resources/messages_zh.properties
+++ b/server/skillhub-app/src/main/resources/messages_zh.properties
@@ -394,3 +394,8 @@ error.githubSync.deepDiscovery.exclusionInvalid=排除项须为有效的GitHub
 error.githubSync.deepDiscovery.configurationConflict=官方探索配置已被修改，请重新读取最新配置后再保存
 
 error.githubSync.deepDiscovery.queryInvalid=深度探索查询参数无效。
+# authoring runtime bindings
+error.authoring.binding.notFound=草稿 {0} 尚未配置运行时绑定
+error.authoring.binding.agentType.unknown=未知的 Agent 运行时类型：{0}
+error.authoring.binding.invalid=运行时绑定不合法：{0}
+error.authoring.binding.unserializable=运行时绑定无法序列化
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringDraftFlowIntegrationTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringDraftFlowIntegrationTest.java
index 6c9cfc5c2..4a691acff 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringDraftFlowIntegrationTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringDraftFlowIntegrationTest.java
@@ -213,9 +213,13 @@ void structureLayerFailsFixablyThenSucceedsAfterRepair() {
 
         assertThat(failed.getStatus()).isEqualTo(ValidationRunStatus.FAILED);
         List<ValidationFinding> findings = runService.listFindings(broken.getId());
-        assertThat(findings).hasSize(1);
-        ValidationFinding finding = findings.get(0);
-        assertThat(finding.getRuleCode()).isEqualTo("FRONTMATTER_FIELD_MISSING");
+        // the config layer (added with the execution layer) also warns that
+        // validation.yaml is absent — the structure ERROR is what fails the run
+        ValidationFinding finding = findings.stream()
+                .filter(f -> "FRONTMATTER_FIELD_MISSING".equals(f.getRuleCode()))
+                .findFirst().orElseThrow();
+        assertThat(finding.getSeverity()).isEqualTo(
+                com.iflytek.skillhub.domain.authoring.validation.FindingSeverity.ERROR);
         assertThat(finding.getSuggestion()).isNotNull();
         assertThat(finding.getSuggestion().safePatches()).hasSize(1);
         assertThat(runService.listEvents(broken.getId(), null))
@@ -233,7 +237,10 @@ void structureLayerFailsFixablyThenSucceedsAfterRepair() {
 
         assertThat(succeeded.getStatus()).isEqualTo(ValidationRunStatus.SUCCEEDED);
         assertThat(succeeded.getErrorCount()).isZero();
-        assertThat(runService.listFindings(repaired.getId())).isEmpty();
+        // warnings (SPEC_MISSING for the absent validation.yaml) do not block
+        assertThat(runService.listFindings(repaired.getId()))
+                .extracting(ValidationFinding::getSeverity)
+                .doesNotContain(com.iflytek.skillhub.domain.authoring.validation.FindingSeverity.ERROR);
         assertThat(draftService.getDraft(draft.getId()).getValidatedRevision())
                 .isEqualTo(succeeded.getDraftRevision());
     }
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringExecutionFlowIntegrationTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringExecutionFlowIntegrationTest.java
new file mode 100644
index 000000000..da9c7a934
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringExecutionFlowIntegrationTest.java
@@ -0,0 +1,178 @@
+package com.iflytek.skillhub.authoring;
+
+import com.iflytek.skillhub.TestRedisConfig;
+import com.iflytek.skillhub.domain.authoring.SkillDraft;
+import com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService;
+import com.iflytek.skillhub.domain.authoring.service.SkillDraftService;
+import com.iflytek.skillhub.domain.authoring.service.ValidationRunService;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRunStatus;
+import com.iflytek.skillhub.domain.namespace.Namespace;
+import com.iflytek.skillhub.domain.namespace.NamespaceMember;
+import com.iflytek.skillhub.domain.namespace.NamespaceMemberRepository;
+import com.iflytek.skillhub.domain.namespace.NamespaceRepository;
+import com.iflytek.skillhub.domain.namespace.NamespaceRole;
+import com.iflytek.skillhub.domain.user.UserAccount;
+import com.iflytek.skillhub.domain.user.UserAccountRepository;
+import com.iflytek.skillhub.service.authoring.ValidationRunOrchestrator;
+import com.iflytek.skillhub.storage.ObjectStorageService;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Import;
+import org.springframework.context.annotation.Primary;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * Execution layer of the authoring platform: three-layer validation with a
+ * local-script binding (structure + config + behavior, the script subprocess
+ * executed inline under the test profile). The MCP probe and the binding
+ * security policy arrive with the MCP+security layer.
+ */
+@SpringBootTest
+@ActiveProfiles("test")
+@Import({TestRedisConfig.class, AuthoringDraftFlowIntegrationTest.InMemoryStorageConfig.class})
+@Testcontainers
+class AuthoringExecutionFlowIntegrationTest {
+
+    @Container
+    private static final PostgreSQLContainer<?> POSTGRES =
+            new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @DynamicPropertySource
+    static void configurePostgres(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", POSTGRES::getJdbcUrl);
+        registry.add("spring.datasource.username", POSTGRES::getUsername);
+        registry.add("spring.datasource.password", POSTGRES::getPassword);
+        registry.add("spring.datasource.driver-class-name", () -> "org.postgresql.Driver");
+        registry.add("spring.jpa.database-platform", () -> "org.hibernate.dialect.PostgreSQLDialect");
+        registry.add("spring.flyway.enabled", () -> true);
+        registry.add("spring.jpa.hibernate.ddl-auto", () -> "validate");
+    }
+
+    private static final String USER = "author-user-2";
+    private static final String NS_SLUG = "authoring-test-ns";
+
+    @Autowired private SkillDraftService draftService;
+    @Autowired private RuntimeBindingService bindingService;
+    @Autowired private ValidationRunService runService;
+    @Autowired private ValidationRunOrchestrator orchestrator;
+    @Autowired private NamespaceRepository namespaceRepository;
+    @Autowired private NamespaceMemberRepository namespaceMemberRepository;
+    @Autowired private UserAccountRepository userAccountRepository;
+
+    @BeforeEach
+    void setUpNamespace() {
+        if (userAccountRepository.findById(USER).isEmpty()) {
+            userAccountRepository.save(new UserAccount(USER, "Author User", "author@example.com", null));
+        }
+        if (namespaceRepository.findBySlug(NS_SLUG).isEmpty()) {
+            Namespace namespace = new Namespace(NS_SLUG, "Authoring Test", USER);
+            namespace.setStatus(com.iflytek.skillhub.domain.namespace.NamespaceStatus.ACTIVE);
+            Namespace saved = namespaceRepository.save(namespace);
+            if (namespaceMemberRepository.findByNamespaceIdAndUserId(saved.getId(), USER).isEmpty()) {
+                namespaceMemberRepository.save(new NamespaceMember(saved.getId(), USER, NamespaceRole.MEMBER));
+            }
+        }
+    }
+
+    @Test
+    void threeLayerValidationExecutesScriptTasks() {
+        SkillDraft draft = draftService.createDraft(NS_SLUG, USER, "runtime-flow",
+                "summarizes documents", null);
+        draftService.saveFile(draft.getId(), USER, "SKILL.md", validSkillMd().getBytes(StandardCharsets.UTF_8),
+                "text/markdown", null, null);
+        draftService.saveFile(draft.getId(), USER, "scripts/check.sh",
+                "echo 'smoke OK'\n".getBytes(StandardCharsets.UTF_8), null, null, null);
+        draftService.saveFile(draft.getId(), USER, "validation.yaml",
+                validationYaml().getBytes(StandardCharsets.UTF_8), null, null, null);
+
+        // ---- bind the local-script runtime
+        bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null, null, null);
+
+        // ---- validate: all three layers run, the script task executes inline
+        ValidationRun run = runService.startRun(draft.getId(), USER, null);
+        orchestrator.submit(run.getId());
+        ValidationRun finished = awaitTerminal(run.getId());
+
+        assertThat(finished.getStatus()).isEqualTo(ValidationRunStatus.SUCCEEDED);
+        assertThat(finished.getErrorCount()).isZero();
+        assertThat(runService.listFindings(run.getId())).isEmpty();
+        assertThat(runService.listEvents(run.getId(), null))
+                .extracting(event -> event.getEventType().name())
+                .contains("RUN_STARTED", "TOOL_CALL", "LOG", "RUN_FINISHED");
+        assertThat(runService.listEvents(run.getId(), null).stream()
+                .map(event -> event.getPayload() == null ? "" : event.getPayload().toString())
+                .filter(payload -> payload.contains("smoke OK"))
+                .count()).isPositive();
+
+        SkillDraft validated = draftService.getDraft(draft.getId());
+        assertThat(validated.isCurrentRevisionValidated()).isTrue();
+    }
+
+    private String validSkillMd() {
+        return "---\nname: runtime-flow\ndescription: summarizes documents\n---\n\n# runtime-flow\n";
+    }
+
+    private String validationYaml() {
+        return """
+                version: 1
+                tasks:
+                  - name: smoke
+                    description: script prints the greeting
+                    type: script
+                    script: scripts/check.sh
+                    args: []
+                    timeoutMs: 10000
+                    assertions:
+                      - type: exit_code
+                        equals: 0
+                      - type: stdout_contains
+                        value: smoke OK
+                """;
+    }
+
+    private static void assertBindingRejected(Runnable save, String reasonFragment) {
+        try {
+            save.run();
+            fail("binding save should have been rejected: " + reasonFragment);
+        } catch (com.iflytek.skillhub.domain.shared.exception.DomainBadRequestException exception) {
+            assertThat(String.valueOf(exception.messageArgs()[0])).contains(reasonFragment);
+        }
+    }
+
+    private ValidationRun awaitTerminal(Long runId) {
+        long deadline = System.currentTimeMillis() + 60_000;
+        while (System.currentTimeMillis() < deadline) {
+            if (runService.getRun(runId).getStatus().isTerminal()) {
+                return runService.getRun(runId);
+            }
+            try {
+                Thread.sleep(200);
+            } catch (InterruptedException exception) {
+                Thread.currentThread().interrupt();
+                fail("interrupted while waiting for the validation run to finish");
+            }
+        }
+        fail("validation run did not reach a terminal state in time");
+        return null;
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestratorTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestratorTest.java
index 9c15aa191..ef4aff67d 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestratorTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestratorTest.java
@@ -30,6 +30,10 @@ class ValidationRunOrchestratorTest {
     private final SkillDraftService drafts = mock(SkillDraftService.class);
     private final DraftStructureValidator validator = mock(DraftStructureValidator.class);
     private final ValidationEventBroadcaster broadcaster = mock(ValidationEventBroadcaster.class);
+    private final com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService bindings =
+            mock(com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService.class);
+    private final com.iflytek.skillhub.domain.authoring.service.RuntimeBindingValidator bindingValidator =
+            mock(com.iflytek.skillhub.domain.authoring.service.RuntimeBindingValidator.class);
 
     @Test
     void duplicateClaimCannotEmitAnActiveRunAsFinished() {
@@ -135,6 +139,7 @@ private ValidationRunOrchestrator orchestrator(java.util.concurrent.Executor exe
                                                    ScheduledExecutorService timer, long timeout) {
         AuthoringProperties properties = new AuthoringProperties();
         properties.setRunTimeoutMs(timeout);
-        return new ValidationRunOrchestrator(runs, drafts, validator, broadcaster, executor, timer, properties);
+        return new ValidationRunOrchestrator(runs, drafts, bindings, validator, bindingValidator,
+                java.util.List.of(), broadcaster, properties, executor, timer);
     }
 }
diff --git a/server/skillhub-app/src/test/resources/application-test.yml b/server/skillhub-app/src/test/resources/application-test.yml
index c95ada164..592d2f446 100644
--- a/server/skillhub-app/src/test/resources/application-test.yml
+++ b/server/skillhub-app/src/test/resources/application-test.yml
@@ -49,8 +49,11 @@ skillhub:
   security:
     scanner:
       enabled: false
+  authoring:
+    local-script:
+      # tests exercise the inline script runtime directly; no docker needed
+      execution-mode: inline
 
-logging:
   level:
     root: ERROR
     com.iflytek.skillhub: ERROR
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/AgentRuntimeType.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/AgentRuntimeType.java
new file mode 100644
index 000000000..c412a6c8b
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/AgentRuntimeType.java
@@ -0,0 +1,33 @@
+package com.iflytek.skillhub.domain.authoring;
+
+/**
+ * Runtime types a draft can bind for behavior validation. The registry of supported
+ * adapters lives in the application layer; the domain only knows the stable identifiers.
+ */
+public enum AgentRuntimeType {
+
+    /** Executes the skill's own scripts in an isolated working directory. */
+    LOCAL_SCRIPT("local-script"),
+
+    /** Sends prompts to an OpenAI-compatible chat completion endpoint with SKILL.md as context. */
+    OPENAI_COMPATIBLE("openai-compatible");
+
+    private final String identifier;
+
+    AgentRuntimeType(String identifier) {
+        this.identifier = identifier;
+    }
+
+    public String identifier() {
+        return identifier;
+    }
+
+    public static AgentRuntimeType fromIdentifier(String identifier) {
+        for (AgentRuntimeType type : values()) {
+            if (type.identifier.equals(identifier)) {
+                return type;
+            }
+        }
+        throw new IllegalArgumentException("Unknown agent runtime type: " + identifier);
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/RuntimeBinding.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/RuntimeBinding.java
new file mode 100644
index 000000000..c741569a5
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/RuntimeBinding.java
@@ -0,0 +1,134 @@
+package com.iflytek.skillhub.domain.authoring;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.PrePersist;
+import jakarta.persistence.PreUpdate;
+import jakarta.persistence.Table;
+import java.time.Clock;
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+import org.hibernate.annotations.JdbcTypeCode;
+import org.hibernate.type.SqlTypes;
+
+/**
+ * Per-draft runtime configuration used by behavior validation. Holds the agent type,
+ * adapter-specific configuration, tool allowlist, and MCP server declarations.
+ *
+ * <p>Plain secrets must never be stored here: credentials are referenced by name and
+ * resolved from server-side configuration at validation time. The JSON columns are
+ * mapped as structured collections (not Strings) so the stored documents stay real
+ * JSON objects and Hibernate's read path is symmetric with its write path.
+ */
+@Entity
+@Table(name = "runtime_binding",
+        uniqueConstraints = @jakarta.persistence.UniqueConstraint(
+                name = "uq_runtime_binding_draft", columnNames = "draft_id"))
+public class RuntimeBinding {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "draft_id", nullable = false)
+    private Long draftId;
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "agent_type", nullable = false, length = 32)
+    private AgentRuntimeType agentType;
+
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(name = "config")
+    private Map<String, Object> config;
+
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(name = "tool_allowlist")
+    private List<String> toolAllowlist;
+
+    @JdbcTypeCode(SqlTypes.JSON)
+    @Column(name = "mcp_servers")
+    private List<Map<String, Object>> mcpServers;
+
+    @Column(name = "updated_by", length = 128)
+    private String updatedBy;
+
+    @Column(name = "updated_at", nullable = false)
+    private Instant updatedAt;
+
+    @Column(name = "created_at", nullable = false, updatable = false)
+    private Instant createdAt;
+
+    protected RuntimeBinding() {
+    }
+
+    public RuntimeBinding(Long draftId, AgentRuntimeType agentType) {
+        this.draftId = draftId;
+        this.agentType = agentType;
+    }
+
+    @PrePersist
+    protected void onCreate() {
+        Instant now = Instant.now(Clock.systemUTC());
+        createdAt = now;
+        updatedAt = now;
+    }
+
+    @PreUpdate
+    protected void onUpdate() {
+        updatedAt = Instant.now(Clock.systemUTC());
+    }
+
+    public void update(AgentRuntimeType agentType, Map<String, Object> config,
+                       List<String> toolAllowlist, List<Map<String, Object>> mcpServers,
+                       String updatedBy) {
+        this.agentType = agentType;
+        this.config = config;
+        this.toolAllowlist = toolAllowlist;
+        this.mcpServers = mcpServers;
+        this.updatedBy = updatedBy;
+    }
+
+    // Getters
+
+    public Long getId() {
+        return id;
+    }
+
+    public Long getDraftId() {
+        return draftId;
+    }
+
+    public AgentRuntimeType getAgentType() {
+        return agentType;
+    }
+
+    public Map<String, Object> getConfig() {
+        return config;
+    }
+
+    public List<String> getToolAllowlist() {
+        return toolAllowlist;
+    }
+
+    public List<Map<String, Object>> getMcpServers() {
+        return mcpServers;
+    }
+
+    public String getUpdatedBy() {
+        return updatedBy;
+    }
+
+    public Instant getUpdatedAt() {
+        return updatedAt;
+    }
+
+    public Instant getCreatedAt() {
+        return createdAt;
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/RuntimeBindingRepository.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/RuntimeBindingRepository.java
new file mode 100644
index 000000000..6ff71050d
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/RuntimeBindingRepository.java
@@ -0,0 +1,15 @@
+package com.iflytek.skillhub.domain.authoring;
+
+import java.util.Optional;
+
+/**
+ * Domain repository contract for per-draft runtime bindings.
+ */
+public interface RuntimeBindingRepository {
+
+    RuntimeBinding save(RuntimeBinding binding);
+
+    Optional<RuntimeBinding> findByDraftId(Long draftId);
+
+    void deleteByDraftId(Long draftId);
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionEvaluator.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionEvaluator.java
new file mode 100644
index 000000000..981ace3b9
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionEvaluator.java
@@ -0,0 +1,221 @@
+package com.iflytek.skillhub.domain.authoring.runtime;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.iflytek.skillhub.domain.authoring.spec.AssertionSpec;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
+
+/**
+ * Evaluates rule-based assertions against a task result. Deterministic checks only:
+ * exit codes, regex/substring matching, JSON pointer equality, artifact presence and
+ * hashes, and tool call counts. Semantic quality checks are intentionally not
+ * approximated here — they belong to model-assisted review, which stays outside the
+ * minimal closed loop.
+ */
+public class AssertionEvaluator {
+
+    /** Assertion types valid for SCRIPT tasks. */
+    public static final List<String> SCRIPT_ASSERTION_TYPES = List.of(
+            "exit_code", "stdout_matches", "stdout_contains", "stdout_json",
+            "artifact_exists", "tool_call_count");
+
+    /** Assertion types valid for PROMPT tasks. */
+    public static final List<String> PROMPT_ASSERTION_TYPES = List.of(
+            "response_matches", "response_contains", "response_json", "tool_call_count");
+
+    private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+    /**
+     * Validates assertion types and required parameters without a result. Used by the
+     * configuration layer so malformed assertions fail fast, before any execution.
+     */
+    public List<String> validateSyntax(List<AssertionSpec> assertions, boolean promptTask) {
+        List<String> problems = new ArrayList<>();
+        List<String> allowed = promptTask ? PROMPT_ASSERTION_TYPES : SCRIPT_ASSERTION_TYPES;
+        for (AssertionSpec assertion : assertions) {
+            String type = assertion.type();
+            if (type == null || type.isBlank()) {
+                problems.add("assertion without a type");
+                continue;
+            }
+            if (!allowed.contains(type)) {
+                problems.add("assertion type '" + type + "' is not valid for "
+                        + (promptTask ? "prompt" : "script") + " tasks (allowed: "
+                        + String.join(", ", allowed) + ")");
+                continue;
+            }
+            switch (type) {
+                case "exit_code" -> {
+                    if (assertion.paramInt("equals") == null) {
+                        problems.add("exit_code assertion requires an integer 'equals'");
+                    }
+                }
+                case "stdout_matches", "response_matches" -> {
+                    String pattern = assertion.paramString("pattern");
+                    if (pattern == null || pattern.isBlank()) {
+                        problems.add(type + " assertion requires a 'pattern'");
+                    } else if (!compiles(pattern)) {
+                        problems.add(type + " assertion has an invalid regex: " + pattern);
+                    }
+                }
+                case "stdout_contains", "response_contains" -> {
+                    if (assertion.paramString("value") == null) {
+                        problems.add(type + " assertion requires a 'value'");
+                    }
+                }
+                case "stdout_json", "response_json" -> {
+                    if (assertion.paramString("pointer") == null) {
+                        problems.add(type + " assertion requires a 'pointer'");
+                    }
+                    if (assertion.paramString("equals") == null && assertion.paramInt("equals") == null) {
+                        problems.add(type + " assertion requires an 'equals' value");
+                    }
+                }
+                case "artifact_exists" -> {
+                    if (assertion.paramString("path") == null || assertion.paramString("path").isBlank()) {
+                        problems.add("artifact_exists assertion requires a 'path'");
+                    }
+                }
+                case "tool_call_count" -> {
+                    Integer min = assertion.paramInt("min");
+                    Integer max = assertion.paramInt("max");
+                    if (min == null && max == null) {
+                        problems.add("tool_call_count assertion requires 'min' and/or 'max'");
+                    }
+                }
+                default -> problems.add("unknown assertion type: " + type);
+            }
+        }
+        return problems;
+    }
+
+    /** Evaluates all assertions against the task result; empty list means all passed. */
+    public List<AssertionFailure> evaluate(List<AssertionSpec> assertions, TaskResult result) {
+        List<AssertionFailure> failures = new ArrayList<>();
+        for (AssertionSpec assertion : assertions) {
+            String reason = evaluateOne(assertion, result);
+            if (reason != null) {
+                failures.add(new AssertionFailure(assertion, reason));
+            }
+        }
+        return failures;
+    }
+
+    private String evaluateOne(AssertionSpec assertion, TaskResult result) {
+        String type = assertion.type();
+        return switch (type == null ? "" : type) {
+            case "exit_code" -> {
+                Integer expected = assertion.paramInt("equals");
+                if (result.exitCode() == null) {
+                    yield "task did not run to completion, no exit code";
+                }
+                if (expected == null || result.exitCode() != expected) {
+                    yield "expected exit code " + expected + " but got " + result.exitCode();
+                }
+                yield null;
+            }
+            case "stdout_matches" -> matchPattern(assertion.paramString("pattern"), result.stdout(), "stdout");
+            case "stdout_contains" -> containsValue(assertion.paramString("value"), result.stdout(), "stdout");
+            case "response_matches" -> matchPattern(assertion.paramString("pattern"), result.response(), "response");
+            case "response_contains" -> containsValue(assertion.paramString("value"), result.response(), "response");
+            case "stdout_json" -> jsonPointer(assertion, result.stdout(), "stdout");
+            case "response_json" -> jsonPointer(assertion, result.response(), "response");
+            case "artifact_exists" -> artifactExists(assertion, result);
+            case "tool_call_count" -> toolCallCount(assertion, result);
+            default -> "unknown assertion type: " + type;
+        };
+    }
+
+    private String matchPattern(String patternText, String actual, String field) {
+        if (patternText == null) {
+            return "pattern is missing";
+        }
+        if (actual == null) {
+            return field + " is empty";
+        }
+        if (!Pattern.compile(patternText).matcher(actual).find()) {
+            return field + " does not match pattern: " + patternText;
+        }
+        return null;
+    }
+
+    private String containsValue(String value, String actual, String field) {
+        if (value == null) {
+            return "value is missing";
+        }
+        if (actual == null || !actual.contains(value)) {
+            return field + " does not contain: " + value;
+        }
+        return null;
+    }
+
+    private String jsonPointer(AssertionSpec assertion, String actual, String field) {
+        String pointer = assertion.paramString("pointer");
+        String expected = assertion.paramString("equals");
+        if (pointer == null || expected == null) {
+            return "pointer or equals is missing";
+        }
+        if (actual == null || actual.isBlank()) {
+            return field + " is empty";
+        }
+        JsonNode root;
+        try {
+            root = OBJECT_MAPPER.readTree(actual);
+        } catch (Exception exception) {
+            return field + " is not valid JSON";
+        }
+        JsonNode node = root.at(pointer);
+        if (node.isMissingNode()) {
+            return field + " has no value at pointer " + pointer;
+        }
+        String actualText = node.isTextual() ? node.asText() : node.toString();
+        if (!expected.equals(actualText)) {
+            return "value at " + pointer + " is " + actualText + ", expected " + expected;
+        }
+        return null;
+    }
+
+    private String artifactExists(AssertionSpec assertion, TaskResult result) {
+        String path = assertion.paramString("path");
+        if (path == null) {
+            return "path is missing";
+        }
+        byte[] content = result.artifacts().read(path).orElse(null);
+        if (content == null) {
+            return "artifact not found: " + path;
+        }
+        String expectedSha = assertion.paramString("sha256");
+        if (expectedSha != null && !expectedSha.isBlank()) {
+            String actualSha = TaskResult.sha256Hex(content);
+            if (!expectedSha.toLowerCase().equals(actualSha)) {
+                return "artifact " + path + " sha256 is " + actualSha + ", expected " + expectedSha;
+            }
+        }
+        return null;
+    }
+
+    private String toolCallCount(AssertionSpec assertion, TaskResult result) {
+        Integer min = assertion.paramInt("min");
+        Integer max = assertion.paramInt("max");
+        int actual = result.toolCallCount();
+        if (min != null && actual < min) {
+            return "tool call count " + actual + " is below minimum " + min;
+        }
+        if (max != null && actual > max) {
+            return "tool call count " + actual + " exceeds maximum " + max;
+        }
+        return null;
+    }
+
+    private boolean compiles(String pattern) {
+        try {
+            Pattern.compile(pattern);
+            return true;
+        } catch (PatternSyntaxException exception) {
+            return false;
+        }
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionFailure.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionFailure.java
new file mode 100644
index 000000000..cf5bbd49f
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionFailure.java
@@ -0,0 +1,13 @@
+package com.iflytek.skillhub.domain.authoring.runtime;
+
+import com.iflytek.skillhub.domain.authoring.spec.AssertionSpec;
+
+/**
+ * One assertion that did not hold, with a human-readable reason.
+ */
+public record AssertionFailure(AssertionSpec assertion, String reason) {
+
+    public String describe() {
+        return "assertion '" + assertion.type() + "' failed: " + reason;
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/RuntimeEventSink.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/RuntimeEventSink.java
new file mode 100644
index 000000000..3db676471
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/RuntimeEventSink.java
@@ -0,0 +1,21 @@
+package com.iflytek.skillhub.domain.authoring.runtime;
+
+/**
+ * Callbacks a runtime adapter uses to stream execution progress into the persisted
+ * run event log. The orchestrator assigns sequence numbers and broadcasts to SSE
+ * subscribers; adapters only report what happened.
+ */
+public interface RuntimeEventSink {
+
+    /** An agent-level message (model response, task narration). */
+    void agentMessage(String taskName, String content);
+
+    /** A tool invocation initiated by the runtime (script execution, HTTP tool call). */
+    void toolCall(String taskName, String tool, String argumentsJson);
+
+    /** The outcome of a tool invocation. */
+    void toolResult(String taskName, String tool, String summaryJson);
+
+    /** A raw log line from the runtime (stdout/stderr of a script, transport log). */
+    void log(String taskName, String stream, String line);
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/RuntimeExecutionContext.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/RuntimeExecutionContext.java
new file mode 100644
index 000000000..41eed79c5
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/RuntimeExecutionContext.java
@@ -0,0 +1,50 @@
+package com.iflytek.skillhub.domain.authoring.runtime;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Everything a runtime adapter needs to execute one validation run: the isolated
+ * working directory containing the draft files, the adapter-specific configuration,
+ * the tool allowlist, the declared MCP servers, and the cancellation signal.
+ *
+ * @param runId            validation run identifier, for logging
+ * @param workingDirectory isolated directory holding the draft's files (read-write)
+ * @param adapterConfig    adapter-specific configuration map from the runtime binding
+ * @param toolAllowlist    allowed tool identifiers; empty means unrestricted
+ * @param mcpServers       MCP server declarations from the runtime binding (may be empty)
+ * @param cancellation     cooperative cancel signal
+ */
+public record RuntimeExecutionContext(
+        Long runId,
+        Path workingDirectory,
+        Map<String, Object> adapterConfig,
+        List<String> toolAllowlist,
+        List<Map<String, Object>> mcpServers,
+        TaskCancellation cancellation
+) {
+
+    /** Convenience constructor for runtimes that do not consume MCP servers. */
+    public RuntimeExecutionContext(Long runId, Path workingDirectory, Map<String, Object> adapterConfig,
+                                   List<String> toolAllowlist, TaskCancellation cancellation) {
+        this(runId, workingDirectory, adapterConfig, toolAllowlist, List.of(), cancellation);
+    }
+
+    public Map<String, Object> safeAdapterConfig() {
+        return adapterConfig == null ? Map.of() : adapterConfig;
+    }
+
+    public List<String> safeToolAllowlist() {
+        return toolAllowlist == null ? List.of() : List.copyOf(toolAllowlist);
+    }
+
+    public List<Map<String, Object>> safeMcpServers() {
+        return mcpServers == null ? List.of() : List.copyOf(mcpServers);
+    }
+
+    public String configString(String key) {
+        Object value = safeAdapterConfig().get(key);
+        return value == null ? null : value.toString();
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/SkillRuntimeAdapter.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/SkillRuntimeAdapter.java
new file mode 100644
index 000000000..82b20c446
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/SkillRuntimeAdapter.java
@@ -0,0 +1,46 @@
+package com.iflytek.skillhub.domain.authoring.runtime;
+
+import com.iflytek.skillhub.domain.authoring.spec.TaskType;
+import com.iflytek.skillhub.domain.authoring.spec.ValidationTaskSpec;
+
+/**
+ * SPI implemented by every agent runtime the authoring platform can bind to a draft.
+ *
+ * <p>Implementations live in the application layer (process execution, HTTP clients)
+ * and are selected by the runtime binding's agent type. The contract is deliberately
+ * minimal: execute one task, stream progress through the sink, return or throw.
+ * Assertion evaluation is handled by the orchestrator via {@link TaskResult}, not by
+ * adapters.
+ */
+public interface SkillRuntimeAdapter {
+
+    /** The agent type identifier this adapter serves (see {@code AgentRuntimeType}). */
+    String agentType();
+
+    /** Whether the adapter can execute the given task kind. */
+    boolean supports(TaskType taskType);
+
+    /**
+     * Whether the adapter is currently usable. Disabled adapters (missing server-side
+     * configuration, feature flags) are reported as RUNTIME_DISABLED findings instead of
+     * failed tasks when the orchestrator selects them.
+     */
+    default boolean enabled() {
+        return true;
+    }
+
+    /**
+     * Executes one validation task. Implementations must:
+     * <ul>
+     *   <li>honor {@code context.cancellation()} while running;</li>
+     *   <li>enforce the task timeout themselves;</li>
+     *   <li>report progress through {@code sink};</li>
+     *   <li>never modify draft state — the working directory is a disposable copy.</li>
+     * </ul>
+     *
+     * @return the raw task outcome for assertion evaluation
+     * @throws InterruptedException when cancelled mid-execution
+     */
+    TaskResult execute(RuntimeExecutionContext context, ValidationTaskSpec task,
+                       RuntimeEventSink sink) throws Exception;
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/TaskCancellation.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/TaskCancellation.java
new file mode 100644
index 000000000..e4bef908e
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/TaskCancellation.java
@@ -0,0 +1,12 @@
+package com.iflytek.skillhub.domain.authoring.runtime;
+
+/**
+ * Cooperative cancellation signal handed to runtime adapters. Adapters should poll
+ * {@link #isCancelRequested()} while executing (at least between output chunks) and
+ * abort as quickly as practical when it flips.
+ */
+@FunctionalInterface
+public interface TaskCancellation {
+
+    boolean isCancelRequested();
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/TaskResult.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/TaskResult.java
new file mode 100644
index 000000000..9fefcfd27
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/TaskResult.java
@@ -0,0 +1,56 @@
+package com.iflytek.skillhub.domain.authoring.runtime;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.HexFormat;
+import java.util.Optional;
+
+/**
+ * The raw outcome of one behavior validation task, consumed by the assertion
+ * evaluator. Script tasks populate exit code and streams; prompt tasks populate
+ * the agent response. The artifact resolver reads files produced inside the
+ * working directory (used by artifact_exists assertions).
+ */
+public record TaskResult(
+        Integer exitCode,
+        String stdout,
+        String stderr,
+        String response,
+        int toolCallCount,
+        ArtifactResolver artifacts
+) {
+
+    /** Reads a file produced by the task, relative to the working directory. */
+    public interface ArtifactResolver {
+        Optional<byte[]> read(String relativePath);
+    }
+
+    public static TaskResult ofScript(int exitCode, String stdout, String stderr,
+                                      int toolCallCount, ArtifactResolver artifacts) {
+        return new TaskResult(exitCode, stdout, stderr, null, toolCallCount, artifacts);
+    }
+
+    public static TaskResult ofPrompt(String response, int toolCallCount, ArtifactResolver artifacts) {
+        return new TaskResult(null, null, null, response, toolCallCount, artifacts);
+    }
+
+    public String sha256OfArtifact(String relativePath) {
+        return artifacts.read(relativePath)
+                .map(TaskResult::sha256Hex)
+                .orElse(null);
+    }
+
+    public static String sha256Hex(byte[] content) {
+        try {
+            MessageDigest digest = MessageDigest.getInstance("SHA-256");
+            return HexFormat.of().formatHex(digest.digest(content));
+        } catch (NoSuchAlgorithmException exception) {
+            throw new IllegalStateException("SHA-256 unavailable", exception);
+        }
+    }
+
+    public static String sha256Hex(String content) {
+        return sha256Hex(content.getBytes(StandardCharsets.UTF_8));
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/package-info.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/package-info.java
new file mode 100644
index 000000000..c99d70d0b
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/runtime/package-info.java
@@ -0,0 +1,5 @@
+/**
+ * Runtime adapter SPI and behavior-validation support types shared by the domain and
+ * application layers.
+ */
+package com.iflytek.skillhub.domain.authoring.runtime;
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingService.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingService.java
new file mode 100644
index 000000000..90153578f
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingService.java
@@ -0,0 +1,101 @@
+package com.iflytek.skillhub.domain.authoring.service;
+
+import com.iflytek.skillhub.domain.authoring.AgentRuntimeType;
+import com.iflytek.skillhub.domain.authoring.RuntimeBinding;
+import com.iflytek.skillhub.domain.authoring.RuntimeBindingRepository;
+import com.iflytek.skillhub.domain.authoring.SkillDraft;
+import com.iflytek.skillhub.domain.authoring.SkillDraftRepository;
+import com.iflytek.skillhub.domain.authoring.validation.FindingDraft;
+import com.iflytek.skillhub.domain.authoring.validation.FindingSeverity;
+import com.iflytek.skillhub.domain.shared.exception.DomainBadRequestException;
+import com.iflytek.skillhub.domain.shared.exception.DomainForbiddenException;
+import com.iflytek.skillhub.domain.shared.exception.DomainNotFoundException;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Domain service for a draft's runtime binding: persists the agent type, adapter
+ * configuration, tool allowlist, and MCP server declarations. Validation findings are
+ * the responsibility of {@link RuntimeBindingValidator}; this service only rejects
+ * structurally invalid input at save time.
+ */
+@Service
+public class RuntimeBindingService {
+
+    private static final String SUPER_ADMIN = "SUPER_ADMIN";
+
+    private final RuntimeBindingRepository bindingRepository;
+    private final SkillDraftRepository draftRepository;
+    private final RuntimeBindingValidator bindingValidator;
+
+    public RuntimeBindingService(RuntimeBindingRepository bindingRepository,
+                                 SkillDraftRepository draftRepository,
+                                 RuntimeBindingValidator bindingValidator) {
+        this.bindingRepository = bindingRepository;
+        this.draftRepository = draftRepository;
+        this.bindingValidator = bindingValidator;
+    }
+
+    /**
+     * Saves the runtime binding. Structurally invalid input (unknown agent type,
+     * embedded credentials) is rejected immediately; the full validation report is
+     * produced again as findings whenever a run starts.
+     */
+    @Transactional
+    public RuntimeBinding saveBinding(Long draftId, String userId, String agentType,
+                                      Map<String, Object> adapterConfig,
+                                      List<String> toolAllowlist,
+                                      List<Map<String, Object>> mcpServers,
+                                      Set<String> platformRoles) {
+        SkillDraft draft = draftRepository.findById(draftId)
+                .orElseThrow(() -> new DomainNotFoundException("error.authoring.draft.notFound", draftId));
+        assertOwner(draft, userId, platformRoles);
+
+        AgentRuntimeType type;
+        try {
+            type = AgentRuntimeType.fromIdentifier(agentType == null ? "" : agentType);
+        } catch (IllegalArgumentException exception) {
+            throw new DomainBadRequestException("error.authoring.binding.agentType.unknown", agentType);
+        }
+
+        List<FindingDraft> findings = bindingValidator.validate(
+                type.identifier(), adapterConfig, toolAllowlist, mcpServers);
+        boolean hasErrors = findings.stream()
+                .anyMatch(finding -> finding.severity() == FindingSeverity.ERROR);
+        if (hasErrors) {
+            String first = findings.stream()
+                    .filter(finding -> finding.severity() == FindingSeverity.ERROR)
+                    .findFirst().map(FindingDraft::message).orElse("invalid binding");
+            throw new DomainBadRequestException("error.authoring.binding.invalid", first);
+        }
+
+        RuntimeBinding binding = bindingRepository.findByDraftId(draftId)
+                .orElseGet(() -> new RuntimeBinding(draftId, type));
+        binding.update(type, adapterConfig, toolAllowlist, mcpServers, userId);
+        return bindingRepository.save(binding);
+    }
+
+    @Transactional(readOnly = true)
+    public RuntimeBinding getBinding(Long draftId) {
+        return bindingRepository.findByDraftId(draftId)
+                .orElseThrow(() -> new DomainNotFoundException(
+                        "error.authoring.binding.notFound", draftId));
+    }
+
+    /** Optional accessor for callers that treat "not configured yet" as normal state. */
+    @Transactional(readOnly = true)
+    public java.util.Optional<RuntimeBinding> findBinding(Long draftId) {
+        return bindingRepository.findByDraftId(draftId);
+    }
+
+    private void assertOwner(SkillDraft draft, String userId, Set<String> platformRoles) {
+        if (draft.getOwnerId().equals(userId)
+                || (platformRoles != null && platformRoles.contains(SUPER_ADMIN))) {
+            return;
+        }
+        throw new DomainForbiddenException("error.authoring.draft.forbidden", draft.getId());
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
new file mode 100644
index 000000000..bd6cf6da6
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
@@ -0,0 +1,214 @@
+package com.iflytek.skillhub.domain.authoring.service;
+
+import com.iflytek.skillhub.domain.authoring.validation.FindingDraft;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationLayer;
+import java.net.URI;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Pattern;
+import org.springframework.stereotype.Service;
+
+/**
+ * The CONFIG validation layer: checks the runtime binding (agent type, adapter
+ * configuration, tool allowlist, MCP server declarations) plus the syntactic validity
+ * of validation task assertions. Rejects embedded plaintext credentials — bindings may
+ * only reference server-side credential names. Outbound endpoints, the stdio
+ * transport, and environment references are additionally gated by the
+ * Structural checks only in this layer; the SSRF/stdio/envRef policy that
+ * guards external endpoints arrives with the MCP+security layer.
+ */
+@Service
+public class RuntimeBindingValidator {
+
+    private static final Pattern TOOL_NAME = Pattern.compile("^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$");
+    private static final Pattern MCP_NAME = Pattern.compile("^[a-z0-9][a-z0-9-]{0,63}$");
+    private static final Pattern CREDENTIAL_KEY = Pattern.compile(
+            "(?i).*(secret|password|passwd|api[_-]?key|token|credential).*");
+    private static final Pattern ENV_REF_NAME = Pattern.compile("^[A-Z][A-Z0-9_]{0,63}$");
+    private static final List<String> TRANSPORTS = List.of("http", "sse", "stdio");
+    private static final List<String> INTERPRETERS = List.of("sh", "bash", "python3", "node");
+
+    public RuntimeBindingValidator() {
+    }
+
+    /**
+     * @param agentType       agent type identifier (may be invalid — reported as finding)
+     * @param adapterConfig   adapter-specific configuration map
+     * @param toolAllowlist   tool identifiers (may be null = unrestricted)
+     * @param mcpServers      MCP server declarations (may be null)
+     */
+    public List<FindingDraft> validate(String agentType, Map<String, Object> adapterConfig,
+                                       List<String> toolAllowlist, List<Map<String, Object>> mcpServers) {
+        List<FindingDraft> findings = new ArrayList<>();
+        String resolvedAgentType = agentType == null ? "" : agentType;
+
+        switch (resolvedAgentType) {
+            case "local-script" -> validateLocalScriptConfig(adapterConfig, findings);
+            case "openai-compatible" -> validateOpenAiCompatibleConfig(adapterConfig, findings);
+            default -> findings.add(FindingDraft.error(ValidationLayer.CONFIG, "AGENT_TYPE_UNKNOWN",
+                    "Unknown agent runtime type: " + resolvedAgentType
+                            + " (supported: local-script, openai-compatible)"));
+        }
+
+        if (toolAllowlist != null) {
+            for (String tool : toolAllowlist) {
+                if (tool == null || !TOOL_NAME.matcher(tool).matches()) {
+                    findings.add(FindingDraft.error(ValidationLayer.CONFIG, "TOOL_ALLOWLIST_INVALID",
+                            "Invalid tool allowlist entry: " + tool));
+                }
+            }
+        }
+
+        if (mcpServers != null) {
+            for (Map<String, Object> server : mcpServers) {
+                validateMcpServer(server, findings);
+            }
+        }
+
+        scanForEmbeddedSecrets(agentType, adapterConfig, toolAllowlist, mcpServers, findings);
+        return findings;
+    }
+
+    private void validateLocalScriptConfig(Map<String, Object> config, List<FindingDraft> findings) {
+        if (config == null) {
+            return;
+        }
+        Object interpreter = config.get("interpreter");
+        if (interpreter != null && !INTERPRETERS.contains(interpreter.toString())) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "INTERPRETER_UNSUPPORTED",
+                    "Unsupported interpreter: " + interpreter + " (supported: "
+                            + String.join(", ", INTERPRETERS) + ")"));
+        }
+        Object envAllowlist = config.get("envAllowlist");
+        if (envAllowlist instanceof List<?> entries) {
+            for (Object entry : entries) {
+                if (entry == null || !ENV_REF_NAME.matcher(entry.toString()).matches()) {
+                    findings.add(FindingDraft.error(ValidationLayer.CONFIG, "ENV_ALLOWLIST_INVALID",
+                            "Invalid environment variable name: " + entry));
+                }
+            }
+        } else if (envAllowlist != null) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "ENV_ALLOWLIST_INVALID",
+                    "envAllowlist must be a list of variable names"));
+        }
+    }
+
+    private void validateOpenAiCompatibleConfig(Map<String, Object> config, List<FindingDraft> findings) {
+        if (config == null) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_CONFIG_MISSING",
+                    "openai-compatible runtime requires a config object with endpoint and model"));
+            return;
+        }
+        Object endpoint = config.get("endpoint");
+        if (endpoint == null || endpoint.toString().isBlank()) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_ENDPOINT_MISSING",
+                    "openai-compatible runtime requires an 'endpoint' URL"));
+        } else if (!isHttpUrl(endpoint.toString())) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_ENDPOINT_INVALID",
+                    "endpoint must be an http(s) URL: " + endpoint));
+        }
+        Object model = config.get("model");
+        if (model == null || model.toString().isBlank()) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_MODEL_MISSING",
+                    "openai-compatible runtime requires a 'model' name"));
+        }
+        Object temperature = config.get("temperature");
+        if (temperature instanceof Number number
+                && (number.doubleValue() < 0 || number.doubleValue() > 2)) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_TEMPERATURE_INVALID",
+                    "temperature must be between 0 and 2"));
+        }
+        // the API key is resolved from server configuration, never from the binding
+        if (config.containsKey("apiKey") || config.containsKey("api_key")) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "CREDENTIAL_EMBEDDED",
+                    "apiKey must not be stored in the binding; configure it server-side"));
+        }
+    }
+
+    private void validateMcpServer(Map<String, Object> server, List<FindingDraft> findings) {
+        Object name = server.get("name");
+        if (name == null || !MCP_NAME.matcher(name.toString()).matches()) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_NAME_INVALID",
+                    "MCP server name must be lowercase alphanumerics/hyphens: " + name));
+        }
+        Object transport = server.get("transport");
+        if (transport == null || !TRANSPORTS.contains(transport.toString())) {
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_TRANSPORT_INVALID",
+                    "MCP server " + name + " has unknown transport: " + transport
+                            + " (supported: " + String.join(", ", TRANSPORTS) + ")"));
+        } else if ("http".equals(transport.toString()) || "sse".equals(transport.toString())) {
+            Object endpoint = server.get("endpoint");
+            if (endpoint == null || !isHttpUrl(endpoint.toString())) {
+                findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENDPOINT_INVALID",
+                        "MCP server " + name + " requires an http(s) endpoint"));
+            }
+        } else {
+            // stdio servers spawn host-side processes; the enable switch and the
+            // docker isolation that gate them arrive with the security layer
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_STDIO_DISABLED",
+                    "MCP server " + name + " uses the stdio transport, which is not"
+                            + " available yet; use http/sse instead"));
+            Object command = server.get("command");
+            if (command == null || command.toString().isBlank()) {
+                findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_COMMAND_MISSING",
+                        "MCP server " + name + " (stdio) requires a command"));
+            }
+        }
+        Object toolFilters = server.get("toolFilters");
+        if (toolFilters instanceof List<?> filters) {
+            for (Object filter : filters) {
+                if (filter == null || !TOOL_NAME.matcher(filter.toString()).matches()) {
+                    findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_TOOL_FILTER_INVALID",
+                            "MCP server " + name + " has an invalid tool filter: " + filter));
+                }
+            }
+        }
+        Object envRefs = server.get("envRefs");
+        if (envRefs instanceof List<?> refs) {
+            for (Object ref : refs) {
+                if (ref == null || !ENV_REF_NAME.matcher(ref.toString()).matches()) {
+                    findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENV_REF_INVALID",
+                            "MCP server " + name + " has an invalid env reference: " + ref));
+                }
+            }
+        }
+    }
+
+    /** Rejects secret-looking keys anywhere in the binding payload. */
+    private void scanForEmbeddedSecrets(String agentType, Map<String, Object> adapterConfig,
+                                        List<String> toolAllowlist,
+                                        List<Map<String, Object>> mcpServers,
+                                        List<FindingDraft> findings) {
+        if (adapterConfig != null) {
+            scanMap(adapterConfig, findings);
+        }
+        if (mcpServers != null) {
+            for (Map<String, Object> server : mcpServers) {
+                scanMap(server, findings);
+            }
+        }
+    }
+
+    private void scanMap(Map<String, Object> map, List<FindingDraft> findings) {
+        for (Map.Entry<String, Object> entry : map.entrySet()) {
+            if (CREDENTIAL_KEY.matcher(entry.getKey()).matches()
+                    && entry.getValue() != null && !entry.getValue().toString().isBlank()) {
+                findings.add(FindingDraft.error(ValidationLayer.CONFIG, "CREDENTIAL_EMBEDDED",
+                        "Binding must not embed credentials in field '" + entry.getKey()
+                                + "'; reference server-side credentials instead"));
+            }
+        }
+    }
+
+    private boolean isHttpUrl(String value) {
+        try {
+            URI uri = URI.create(value);
+            String scheme = uri.getScheme();
+            return ("http".equalsIgnoreCase(scheme) || "https".equalsIgnoreCase(scheme))
+                    && uri.getHost() != null;
+        } catch (IllegalArgumentException exception) {
+            return false;
+        }
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/AssertionSpec.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/AssertionSpec.java
new file mode 100644
index 000000000..43e6dd755
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/AssertionSpec.java
@@ -0,0 +1,36 @@
+package com.iflytek.skillhub.domain.authoring.spec;
+
+import java.util.Map;
+
+/**
+ * One assertion inside a validation task. Assertions are deliberately loosely typed:
+ * {@code type} selects the check and {@code params} carries its typed parameters,
+ * which the evaluator validates and coerces. Unknown types or missing parameters are
+ * reported as configuration-layer findings before behavior execution starts.
+ */
+public record AssertionSpec(String type, Map<String, Object> params) {
+
+    public Map<String, Object> safeParams() {
+        return params == null ? Map.of() : params;
+    }
+
+    public String paramString(String key) {
+        Object value = safeParams().get(key);
+        return value == null ? null : value.toString();
+    }
+
+    public Integer paramInt(String key) {
+        Object value = safeParams().get(key);
+        if (value instanceof Number number) {
+            return number.intValue();
+        }
+        if (value instanceof String text && !text.isBlank()) {
+            try {
+                return Integer.parseInt(text.trim());
+            } catch (NumberFormatException ignored) {
+                return null;
+            }
+        }
+        return null;
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/TaskType.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/TaskType.java
new file mode 100644
index 000000000..58fc6ff96
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/TaskType.java
@@ -0,0 +1,13 @@
+package com.iflytek.skillhub.domain.authoring.spec;
+
+/**
+ * Task kinds supported by behavior validation.
+ */
+public enum TaskType {
+
+    /** Executes a script shipped with the skill in the isolated working directory. */
+    SCRIPT,
+
+    /** Sends a prompt to the bound agent runtime with the skill as context. */
+    PROMPT
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpec.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpec.java
new file mode 100644
index 000000000..b1bc5b34d
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpec.java
@@ -0,0 +1,28 @@
+package com.iflytek.skillhub.domain.authoring.spec;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * Parsed content of a draft's {@code validation.yaml}: the ordered list of behavior
+ * validation tasks executed by the BEHAVIOR layer. A draft without the file simply
+ * runs zero behavior tasks.
+ */
+public record ValidationSpec(int version, List<ValidationTaskSpec> tasks) {
+
+    public static final String FILE_PATH = "validation.yaml";
+    public static final int CURRENT_VERSION = 1;
+    public static final int DEFAULT_TASK_TIMEOUT_MS = 60_000;
+
+    public static ValidationSpec empty() {
+        return new ValidationSpec(CURRENT_VERSION, List.of());
+    }
+
+    public List<ValidationTaskSpec> safeTasks() {
+        return tasks == null ? List.of() : List.copyOf(tasks);
+    }
+
+    public Optional<ValidationTaskSpec> findTask(String name) {
+        return safeTasks().stream().filter(task -> task.name().equals(name)).findFirst();
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpecParser.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpecParser.java
new file mode 100644
index 000000000..60695ab12
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpecParser.java
@@ -0,0 +1,211 @@
+package com.iflytek.skillhub.domain.authoring.spec;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import org.yaml.snakeyaml.LoaderOptions;
+import org.yaml.snakeyaml.Yaml;
+import org.yaml.snakeyaml.constructor.SafeConstructor;
+
+/**
+ * Parses a draft's {@code validation.yaml} into {@link ValidationSpec}.
+ *
+ * <p>Follows the same defensive YAML loading rules as {@code SkillMetadataParser}:
+ * SnakeYAML safe constructor, bounded aliases, nesting depth, and code points.
+ * Parse problems are reported as structured spec errors (rule code + message) instead
+ * of exceptions so the configuration validation layer can surface them as findings.
+ */
+public class ValidationSpecParser {
+
+    private static final int MAX_YAML_ALIASES = 20;
+    private static final int MAX_YAML_NESTING_DEPTH = 20;
+    private static final int MAX_YAML_CODE_POINTS = 100_000;
+    private static final int MAX_TASKS = 50;
+    private static final int MAX_TASK_TIMEOUT_MS = 600_000;
+
+    /** A structured parse or semantic error detected while reading the spec. */
+    public record SpecError(String ruleCode, String message) {}
+
+    public record ParseOutcome(ValidationSpec spec, List<SpecError> errors) {
+
+        public boolean isValid() {
+            return errors.isEmpty();
+        }
+    }
+
+    public ParseOutcome parse(String content) {
+        if (content == null || content.isBlank()) {
+            return failure("SPEC_EMPTY", "validation.yaml is empty");
+        }
+        Object parsed;
+        try {
+            LoaderOptions loaderOptions = new LoaderOptions();
+            loaderOptions.setAllowDuplicateKeys(false);
+            loaderOptions.setMaxAliasesForCollections(MAX_YAML_ALIASES);
+            loaderOptions.setNestingDepthLimit(MAX_YAML_NESTING_DEPTH);
+            loaderOptions.setCodePointLimit(MAX_YAML_CODE_POINTS);
+            Yaml yaml = new Yaml(new SafeConstructor(loaderOptions));
+            parsed = yaml.load(content);
+        } catch (Exception exception) {
+            return failure("SPEC_YAML_INVALID", "validation.yaml is not valid YAML: "
+                    + exception.getMessage());
+        }
+        if (!(parsed instanceof Map<?, ?> root)) {
+            return failure("SPEC_NOT_MAP", "validation.yaml must be a YAML object");
+        }
+
+        List<SpecError> errors = new ArrayList<>();
+        Object versionValue = root.get("version");
+        int version = 1;
+        if (versionValue instanceof Number number) {
+            version = number.intValue();
+        } else if (versionValue != null) {
+            try {
+                version = Integer.parseInt(versionValue.toString().trim());
+            } catch (NumberFormatException e) {
+                errors.add(new SpecError("SPEC_VERSION_INVALID",
+                        "version must be an integer, got: " + versionValue));
+            }
+        }
+        if (version != ValidationSpec.CURRENT_VERSION) {
+            errors.add(new SpecError("SPEC_VERSION_INVALID",
+                    "unsupported spec version: " + version + " (expected "
+                            + ValidationSpec.CURRENT_VERSION + ")"));
+        }
+
+        List<ValidationTaskSpec> tasks = new ArrayList<>();
+        java.util.Set<String> seenNames = new java.util.HashSet<>();
+        Object tasksValue = root.get("tasks");
+        if (tasksValue == null) {
+            errors.add(new SpecError("SPEC_TASKS_MISSING", "validation.yaml must define a tasks list"));
+        } else if (!(tasksValue instanceof List<?> rawTasks)) {
+            errors.add(new SpecError("SPEC_TASKS_INVALID", "tasks must be a list"));
+        } else {
+            if (rawTasks.size() > MAX_TASKS) {
+                errors.add(new SpecError("SPEC_TASKS_TOO_MANY",
+                        "too many tasks: " + rawTasks.size() + " (max " + MAX_TASKS + ")"));
+            }
+            for (int i = 0; i < rawTasks.size(); i++) {
+                ValidationTaskSpec task = parseTask(rawTasks.get(i), i, errors, seenNames);
+                if (task != null) {
+                    tasks.add(task);
+                }
+            }
+        }
+
+        if (!errors.isEmpty()) {
+            return new ParseOutcome(ValidationSpec.empty(), List.copyOf(errors));
+        }
+        return new ParseOutcome(new ValidationSpec(version, List.copyOf(tasks)), List.of());
+    }
+
+    private ValidationTaskSpec parseTask(Object rawTask, int index, List<SpecError> errors,
+                                         java.util.Set<String> seenNames) {
+        String where = "tasks[" + index + "]";
+        if (!(rawTask instanceof Map<?, ?> taskMap)) {
+            errors.add(new SpecError("TASK_NOT_MAP", where + " must be a YAML object"));
+            return null;
+        }
+
+        String name = stringField(taskMap, "name");
+        if (name == null || name.isBlank()) {
+            errors.add(new SpecError("TASK_NAME_MISSING", where + " is missing a name"));
+        } else if (!name.matches("[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}")) {
+            errors.add(new SpecError("TASK_NAME_INVALID",
+                    where + " has an invalid name: " + name));
+        } else if (!seenNames.add(name)) {
+            errors.add(new SpecError("TASK_NAME_DUPLICATE", where + " duplicates task name: " + name));
+        }
+
+        String typeRaw = stringField(taskMap, "type");
+        TaskType type;
+        if (typeRaw == null) {
+            errors.add(new SpecError("TASK_TYPE_MISSING", where + " is missing a type"));
+            return null;
+        }
+        try {
+            type = TaskType.valueOf(typeRaw.trim().toUpperCase());
+        } catch (IllegalArgumentException e) {
+            errors.add(new SpecError("TASK_TYPE_INVALID",
+                    where + " has unknown type: " + typeRaw + " (expected script or prompt)"));
+            return null;
+        }
+
+        String script = stringField(taskMap, "script");
+        String prompt = stringField(taskMap, "prompt");
+        if (type == TaskType.SCRIPT && (script == null || script.isBlank())) {
+            errors.add(new SpecError("TASK_SCRIPT_MISSING",
+                    where + " (script task) must define script"));
+        }
+        if (type == TaskType.PROMPT && (prompt == null || prompt.isBlank())) {
+            errors.add(new SpecError("TASK_PROMPT_MISSING",
+                    where + " (prompt task) must define prompt"));
+        }
+
+        List<String> args = new ArrayList<>();
+        Object argsValue = taskMap.get("args");
+        if (argsValue instanceof List<?> rawArgs) {
+            for (Object arg : rawArgs) {
+                if (arg != null) {
+                    args.add(arg.toString());
+                }
+            }
+        } else if (argsValue != null) {
+            errors.add(new SpecError("TASK_ARGS_INVALID", where + " args must be a list"));
+        }
+
+        int timeoutMs = ValidationSpec.DEFAULT_TASK_TIMEOUT_MS;
+        Object timeoutValue = taskMap.get("timeoutMs");
+        if (timeoutValue instanceof Number number) {
+            timeoutMs = number.intValue();
+        } else if (timeoutValue != null) {
+            errors.add(new SpecError("TASK_TIMEOUT_INVALID",
+                    where + " timeoutMs must be an integer"));
+        }
+        if (timeoutMs <= 0 || timeoutMs > MAX_TASK_TIMEOUT_MS) {
+            errors.add(new SpecError("TASK_TIMEOUT_INVALID",
+                    where + " timeoutMs must be between 1 and " + MAX_TASK_TIMEOUT_MS));
+        }
+
+        List<AssertionSpec> assertions = new ArrayList<>();
+        Object assertionsValue = taskMap.get("assertions");
+        if (assertionsValue instanceof List<?> rawAssertions) {
+            for (Object rawAssertion : rawAssertions) {
+                if (rawAssertion instanceof Map<?, ?> assertionMap) {
+                    Object assertionType = assertionMap.get("type");
+                    Map<String, Object> params = new LinkedHashMap<>();
+                    for (Map.Entry<?, ?> entry : assertionMap.entrySet()) {
+                        if (!"type".equals(entry.getKey()) && entry.getKey() != null) {
+                            params.put(entry.getKey().toString(), entry.getValue());
+                        }
+                    }
+                    if (assertionType == null || assertionType.toString().isBlank()) {
+                        errors.add(new SpecError("ASSERTION_TYPE_MISSING",
+                                where + " has an assertion without a type"));
+                    } else {
+                        assertions.add(new AssertionSpec(assertionType.toString(), params));
+                    }
+                } else {
+                    errors.add(new SpecError("ASSERTION_NOT_MAP",
+                            where + " assertions must be objects"));
+                }
+            }
+        } else if (assertionsValue != null) {
+            errors.add(new SpecError("ASSERTIONS_INVALID", where + " assertions must be a list"));
+        }
+
+        String description = stringField(taskMap, "description");
+        return new ValidationTaskSpec(name == null ? where : name, description, type, script,
+                List.copyOf(args), prompt, timeoutMs, List.copyOf(assertions));
+    }
+
+    private String stringField(Map<?, ?> map, String key) {
+        Object value = map.get(key);
+        return value == null ? null : value.toString();
+    }
+
+    private ParseOutcome failure(String ruleCode, String message) {
+        return new ParseOutcome(ValidationSpec.empty(), List.of(new SpecError(ruleCode, message)));
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationTaskSpec.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationTaskSpec.java
new file mode 100644
index 000000000..dce5ba21a
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/ValidationTaskSpec.java
@@ -0,0 +1,26 @@
+package com.iflytek.skillhub.domain.authoring.spec;
+
+import java.util.List;
+
+/**
+ * One behavior validation task parsed from {@code validation.yaml}.
+ */
+public record ValidationTaskSpec(
+        String name,
+        String description,
+        TaskType type,
+        String script,
+        List<String> args,
+        String prompt,
+        int timeoutMs,
+        List<AssertionSpec> assertions
+) {
+
+    public List<String> safeArgs() {
+        return args == null ? List.of() : List.copyOf(args);
+    }
+
+    public List<AssertionSpec> safeAssertions() {
+        return assertions == null ? List.of() : List.copyOf(assertions);
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/package-info.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/package-info.java
new file mode 100644
index 000000000..01f47fb37
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/spec/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Behavior validation task specifications parsed from a draft's {@code validation.yaml}.
+ */
+package com.iflytek.skillhub.domain.authoring.spec;
diff --git a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionEvaluatorTest.java b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionEvaluatorTest.java
new file mode 100644
index 000000000..d3760764e
--- /dev/null
+++ b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/runtime/AssertionEvaluatorTest.java
@@ -0,0 +1,138 @@
+package com.iflytek.skillhub.domain.authoring.runtime;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.iflytek.skillhub.domain.authoring.spec.AssertionSpec;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import org.junit.jupiter.api.Test;
+
+class AssertionEvaluatorTest {
+
+    private final AssertionEvaluator evaluator = new AssertionEvaluator();
+
+    private static TaskResult scriptResult(int exitCode, String stdout, String stderr) {
+        return TaskResult.ofScript(exitCode, stdout, stderr, 1, path -> Optional.empty());
+    }
+
+    @Test
+    void exitCodeAssertionPassesAndFails() {
+        AssertionSpec assertion = new AssertionSpec("exit_code", Map.of("equals", 0));
+
+        assertThat(evaluator.evaluate(List.of(assertion), scriptResult(0, "", ""))).isEmpty();
+        assertThat(evaluator.evaluate(List.of(assertion), scriptResult(1, "", "")))
+                .singleElement()
+                .satisfies(failure -> assertThat(failure.describe()).contains("exit code"));
+    }
+
+    @Test
+    void stdoutContainsChecksValue() {
+        AssertionSpec assertion = new AssertionSpec("stdout_contains", Map.of("value", "OK"));
+
+        assertThat(evaluator.evaluate(List.of(assertion), scriptResult(0, "everything OK here", "")))
+                .isEmpty();
+        assertThat(evaluator.evaluate(List.of(assertion), scriptResult(0, "failed", "")))
+                .hasSize(1);
+    }
+
+    @Test
+    void stdoutMatchesUsesRegexFindSemantics() {
+        AssertionSpec assertion =
+                new AssertionSpec("stdout_matches", Map.of("pattern", "duration: \\d+ms"));
+
+        assertThat(evaluator.evaluate(List.of(assertion), scriptResult(0, "run finished, duration: 42ms", "")))
+                .isEmpty();
+        assertThat(evaluator.evaluate(List.of(assertion), scriptResult(0, "no timing info", "")))
+                .hasSize(1);
+    }
+
+    @Test
+    void jsonPointerAssertionComparesValue() {
+        AssertionSpec assertion = new AssertionSpec("stdout_json",
+                Map.of("pointer", "/status", "equals", "healthy"));
+
+        assertThat(evaluator.evaluate(List.of(assertion),
+                scriptResult(0, "{\"status\":\"healthy\"}", ""))).isEmpty();
+        assertThat(evaluator.evaluate(List.of(assertion),
+                scriptResult(0, "{\"status\":\"unhealthy\"}", ""))).hasSize(1);
+        assertThat(evaluator.evaluate(List.of(assertion), scriptResult(0, "not json", "")))
+                .singleElement()
+                .satisfies(failure -> assertThat(failure.describe()).contains("not valid JSON"));
+    }
+
+    @Test
+    void artifactExistsChecksContentHash() {
+        byte[] content = "artifact-bytes".getBytes();
+        String sha = TaskResult.sha256Hex(content);
+        TaskResult result = TaskResult.ofScript(0, "", "", 0, path ->
+                "out/report.txt".equals(path) ? Optional.of(content) : Optional.empty());
+
+        AssertionSpec exists = new AssertionSpec("artifact_exists", Map.of("path", "out/report.txt"));
+        AssertionSpec missing = new AssertionSpec("artifact_exists", Map.of("path", "out/none.txt"));
+        AssertionSpec wrongHash = new AssertionSpec("artifact_exists",
+                Map.of("path", "out/report.txt", "sha256", "deadbeef"));
+
+        assertThat(evaluator.evaluate(List.of(exists), result)).isEmpty();
+        assertThat(evaluator.evaluate(List.of(missing), result)).hasSize(1);
+        assertThat(evaluator.evaluate(List.of(wrongHash), result))
+                .singleElement()
+                .satisfies(failure -> assertThat(failure.describe()).contains("sha256"));
+    }
+
+    @Test
+    void toolCallCountHonorsMinAndMax() {
+        TaskResult result = TaskResult.ofScript(0, "", "", 2, path -> Optional.empty());
+
+        assertThat(evaluator.evaluate(
+                List.of(new AssertionSpec("tool_call_count", Map.of("min", 1, "max", 3))), result))
+                .isEmpty();
+        assertThat(evaluator.evaluate(
+                List.of(new AssertionSpec("tool_call_count", Map.of("min", 3))), result))
+                .hasSize(1);
+        assertThat(evaluator.evaluate(
+                List.of(new AssertionSpec("tool_call_count", Map.of("max", 1))), result))
+                .hasSize(1);
+    }
+
+    @Test
+    void responseAssertionsApplyToPromptResults() {
+        TaskResult result = TaskResult.ofPrompt("the skill summarizes documents", 0,
+                path -> Optional.empty());
+
+        assertThat(evaluator.evaluate(List.of(
+                        new AssertionSpec("response_contains", Map.of("value", "summarizes"))), result))
+                .isEmpty();
+        assertThat(evaluator.evaluate(List.of(
+                        new AssertionSpec("response_contains", Map.of("value", "translates"))), result))
+                .hasSize(1);
+    }
+
+    @Test
+    void unknownAssertionTypeFailsEvaluation() {
+        List<AssertionSpec> assertions = List.of(new AssertionSpec("mind_read", Map.of()));
+
+        assertThat(evaluator.evaluate(assertions, scriptResult(0, "", "")))
+                .singleElement()
+                .satisfies(failure -> assertThat(failure.describe()).contains("unknown assertion type"));
+    }
+
+    @Test
+    void validateSyntaxAcceptsKnownTypesPerTaskKind() {
+        List<AssertionSpec> scriptAssertions = List.of(
+                new AssertionSpec("exit_code", Map.of("equals", 0)),
+                new AssertionSpec("stdout_contains", Map.of("value", "OK")));
+        List<AssertionSpec> promptAssertions = List.of(
+                new AssertionSpec("response_contains", Map.of("value", "OK")),
+                new AssertionSpec("tool_call_count", Map.of("min", 0)));
+
+        assertThat(evaluator.validateSyntax(scriptAssertions, false)).isEmpty();
+        assertThat(evaluator.validateSyntax(promptAssertions, true)).isEmpty();
+
+        List<AssertionSpec> crossKind = List.of(
+                new AssertionSpec("exit_code", Map.of("equals", 0)),
+                new AssertionSpec("response_contains", Map.of("value", "OK")));
+        assertThat(evaluator.validateSyntax(crossKind, true)).hasSize(1);
+        assertThat(evaluator.validateSyntax(crossKind, false)).hasSize(1);
+    }
+}
diff --git a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpecParserTest.java b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpecParserTest.java
new file mode 100644
index 000000000..c1cda0bb1
--- /dev/null
+++ b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/spec/ValidationSpecParserTest.java
@@ -0,0 +1,182 @@
+package com.iflytek.skillhub.domain.authoring.spec;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+class ValidationSpecParserTest {
+
+    private final ValidationSpecParser parser = new ValidationSpecParser();
+
+    @Test
+    void parsesValidScriptTask() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("""
+                version: 1
+                tasks:
+                  - name: smoke
+                    description: basic check
+                    type: script
+                    script: scripts/check.sh
+                    args: ["--quiet"]
+                    timeoutMs: 5000
+                    assertions:
+                      - type: exit_code
+                        equals: 0
+                      - type: stdout_contains
+                        value: OK
+                """);
+
+        assertThat(outcome.isValid()).isTrue();
+        ValidationSpec spec = outcome.spec();
+        assertThat(spec.version()).isEqualTo(1);
+        assertThat(spec.safeTasks()).hasSize(1);
+        ValidationTaskSpec task = spec.safeTasks().get(0);
+        assertThat(task.name()).isEqualTo("smoke");
+        assertThat(task.type()).isEqualTo(TaskType.SCRIPT);
+        assertThat(task.script()).isEqualTo("scripts/check.sh");
+        assertThat(task.safeArgs()).containsExactly("--quiet");
+        assertThat(task.timeoutMs()).isEqualTo(5000);
+        assertThat(task.safeAssertions()).hasSize(2);
+        assertThat(task.safeAssertions().get(0).type()).isEqualTo("exit_code");
+        assertThat(task.safeAssertions().get(0).paramInt("equals")).isZero();
+    }
+
+    @Test
+    void parsesPromptTaskWithoutOptionalFields() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("""
+                version: 1
+                tasks:
+                  - name: ask
+                    type: prompt
+                    prompt: What is this skill about?
+                """);
+
+        assertThat(outcome.isValid()).isTrue();
+        ValidationTaskSpec task = outcome.spec().safeTasks().get(0);
+        assertThat(task.type()).isEqualTo(TaskType.PROMPT);
+        assertThat(task.timeoutMs()).isEqualTo(ValidationSpec.DEFAULT_TASK_TIMEOUT_MS);
+        assertThat(task.safeAssertions()).isEmpty();
+    }
+
+    @Test
+    void emptyContentIsASpecError() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("   \n");
+
+        assertThat(outcome.isValid()).isFalse();
+        assertThat(outcome.errors()).singleElement()
+                .satisfies(error -> assertThat(error.ruleCode()).isEqualTo("SPEC_EMPTY"));
+    }
+
+    @Test
+    void invalidYamlIsASpecErrorNotAnException() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("version: [unbalanced");
+
+        assertThat(outcome.isValid()).isFalse();
+        assertThat(outcome.errors()).singleElement()
+                .satisfies(error -> assertThat(error.ruleCode()).isEqualTo("SPEC_YAML_INVALID"));
+    }
+
+    @Test
+    void unsupportedVersionIsRejected() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("""
+                version: 2
+                tasks: []
+                """);
+
+        assertThat(outcome.isValid()).isFalse();
+        assertThat(outcome.errors()).singleElement()
+                .satisfies(error -> assertThat(error.ruleCode()).isEqualTo("SPEC_VERSION_INVALID"));
+    }
+
+    @Test
+    void missingTasksListIsRejected() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("version: 1\n");
+
+        assertThat(outcome.isValid()).isFalse();
+        assertThat(outcome.errors()).singleElement()
+                .satisfies(error -> assertThat(error.ruleCode()).isEqualTo("SPEC_TASKS_MISSING"));
+    }
+
+    @Test
+    void duplicateTaskNamesAreRejected() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("""
+                version: 1
+                tasks:
+                  - name: smoke
+                    type: script
+                    script: a.sh
+                  - name: smoke
+                    type: script
+                    script: b.sh
+                """);
+
+        assertThat(outcome.isValid()).isFalse();
+        assertThat(outcome.errors()).singleElement()
+                .satisfies(error -> assertThat(error.ruleCode()).isEqualTo("TASK_NAME_DUPLICATE"));
+    }
+
+    @Test
+    void scriptTaskRequiresScriptAndPromptTaskRequiresPrompt() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("""
+                version: 1
+                tasks:
+                  - name: no-script
+                    type: script
+                  - name: no-prompt
+                    type: prompt
+                """);
+
+        List<String> codes = outcome.errors().stream().map(ValidationSpecParser.SpecError::ruleCode).toList();
+        assertThat(codes).containsExactly("TASK_SCRIPT_MISSING", "TASK_PROMPT_MISSING");
+    }
+
+    @Test
+    void unknownTypeAndInvalidTimeoutAreRejected() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("""
+                version: 1
+                tasks:
+                  - name: weird
+                    type: telepathy
+                  - name: slow
+                    type: script
+                    script: a.sh
+                    timeoutMs: 999999999
+                """);
+
+        List<String> codes = outcome.errors().stream().map(ValidationSpecParser.SpecError::ruleCode).toList();
+        assertThat(codes).contains("TASK_TYPE_INVALID", "TASK_TIMEOUT_INVALID");
+    }
+
+    @Test
+    void invalidTaskNameIsRejected() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("""
+                version: 1
+                tasks:
+                  - name: "has space"
+                    type: script
+                    script: a.sh
+                """);
+
+        assertThat(outcome.isValid()).isFalse();
+        assertThat(outcome.errors()).singleElement()
+                .satisfies(error -> assertThat(error.ruleCode()).isEqualTo("TASK_NAME_INVALID"));
+    }
+
+    @Test
+    void assertionWithoutTypeIsRejected() {
+        ValidationSpecParser.ParseOutcome outcome = parser.parse("""
+                version: 1
+                tasks:
+                  - name: smoke
+                    type: script
+                    script: a.sh
+                    assertions:
+                      - equals: 0
+                """);
+
+        assertThat(outcome.isValid()).isFalse();
+        assertThat(outcome.errors()).singleElement()
+                .satisfies(error -> assertThat(error.ruleCode()).isEqualTo("ASSERTION_TYPE_MISSING"));
+    }
+}
diff --git a/server/skillhub-infra/src/main/java/com/iflytek/skillhub/infra/jpa/RuntimeBindingJpaRepository.java b/server/skillhub-infra/src/main/java/com/iflytek/skillhub/infra/jpa/RuntimeBindingJpaRepository.java
new file mode 100644
index 000000000..c8b354fbf
--- /dev/null
+++ b/server/skillhub-infra/src/main/java/com/iflytek/skillhub/infra/jpa/RuntimeBindingJpaRepository.java
@@ -0,0 +1,19 @@
+package com.iflytek.skillhub.infra.jpa;
+
+import com.iflytek.skillhub.domain.authoring.RuntimeBinding;
+import com.iflytek.skillhub.domain.authoring.RuntimeBindingRepository;
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+/**
+ * JPA-backed repository for per-draft runtime bindings.
+ */
+@Repository
+public interface RuntimeBindingJpaRepository extends JpaRepository<RuntimeBinding, Long>,
+        RuntimeBindingRepository {
+
+    Optional<RuntimeBinding> findByDraftId(Long draftId);
+
+    void deleteByDraftId(Long draftId);
+}

From 8c6fcbd4a3ff98d24dda8d5326989022f2bb4886 Mon Sep 17 00:00:00 2001
From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Date: Fri, 23 Oct 2026 17:55:41 +0800
Subject: [PATCH 14/17] fix(authoring): enforce deployment environment
 authorization

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---
 compose.release.yml                           |   1 +
 docs/27-authoring-drafts.md                   |  29 +++++
 .../config/AuthoringEnvironmentConfig.java    |  15 +++
 .../skillhub/config/AuthoringProperties.java  |  11 ++
 .../adapter/LocalScriptRuntimeAdapter.java    |  44 ++++---
 .../src/main/resources/application.yml        |   2 +
 .../AuthoringEnvironmentConfigTest.java       |  63 ++++++++++
 ...calScriptEnvironmentAuthorizationTest.java | 112 ++++++++++++++++++
 .../LocalScriptEnvironmentExecutionTest.java  | 108 +++++++++++++++++
 .../service/RuntimeBindingValidator.java      |  13 +-
 .../service/ScriptEnvironmentPolicy.java      |  61 ++++++++++
 ...meBindingEnvironmentAuthorizationTest.java |  55 +++++++++
 .../service/ScriptEnvironmentPolicyTest.java  |  70 +++++++++++
 13 files changed, 567 insertions(+), 17 deletions(-)
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfig.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfigTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptEnvironmentAuthorizationTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptEnvironmentExecutionTest.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicy.java
 create mode 100644 server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingEnvironmentAuthorizationTest.java
 create mode 100644 server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicyTest.java

diff --git a/compose.release.yml b/compose.release.yml
index 876655749..a6b11bea4 100644
--- a/compose.release.yml
+++ b/compose.release.yml
@@ -116,6 +116,7 @@ services:
       SKILLHUB_SECURITY_SCANNER_RETRY_MAX: ${SKILLHUB_SECURITY_SCANNER_RETRY_MAX:-3}
       SKILLHUB_SCAN_STREAM_RECLAIM_MIN_IDLE: ${SKILLHUB_SCAN_STREAM_RECLAIM_MIN_IDLE:-PT16M}
       SKILLHUB_BUILTIN_SKILLS_ENABLED: ${SKILLHUB_BUILTIN_SKILLS_ENABLED:-true}
+      SKILLHUB_AUTHORING_SCRIPT_ENVIRONMENT_ALLOWLIST: ${SKILLHUB_AUTHORING_SCRIPT_ENVIRONMENT_ALLOWLIST:-}
       SKILLHUB_AUTH_DIRECT_ENABLED: ${SKILLHUB_AUTH_DIRECT_ENABLED:-false}
       SKILLHUB_TRACING_MODE: ${SKILLHUB_TRACING_MODE:-none}
       SKILLHUB_LOG_FORMAT: ${SKILLHUB_LOG_FORMAT:-json}
diff --git a/docs/27-authoring-drafts.md b/docs/27-authoring-drafts.md
index b2219a997..a2350bad7 100644
--- a/docs/27-authoring-drafts.md
+++ b/docs/27-authoring-drafts.md
@@ -27,3 +27,32 @@
 数据库迁移为未发布的 `V69__authoring_platform.sql`。正 revision、非负大小／计数及状态转换在业务代码中验证；数据库保留主键、外键和唯一性结构约束。头像／邀请 PR #947 使用 V70–V74，须在 V69 合入后验证其升级顺序，避免把较低编号的迁移留到已应用较高版本之后。
 
 API 的完整字段、操作与响应以服务生成的 OpenAPI 为准；本文件不替代接口定义。
+
+## 本地脚本的环境变量授权
+
+部署管理员通过 `skillhub.authoring.local-script.environment-allowlist` 设置可选变量名称的上限；
+环境覆盖项为 `SKILLHUB_AUTHORING_SCRIPT_ENVIRONMENT_ALLOWLIST`，多个名称用英文逗号分隔。
+缺省为空：除适配器固定的启动环境外，草稿不能选择额外的服务器变量。例如部署可以显式允许
+`AUTHORING_DEMO_SETTING`，草稿绑定的 `envAllowlist` 只能选择该名称或更小的子集，不能自行授予权限。
+名称必须是匹配 `[A-Z][A-Z0-9_]{0,63}` 的大写字符串，区分大小写；绑定不保存变量值。
+已获准但在服务器进程中未定义的变量不转发。
+
+此配置向所有能够运行本地脚本的草稿拥有者授予权限，包括普通成员；它不是按用户或命名空间
+划分的凭据授权。只允许可以向这些用户披露的值，因为脚本及运行日志均可能暴露收到的值。
+不要为了运行草稿而将服务器凭据加入此集合；此类需求应另行设计有范围限制的凭据绑定。
+
+绑定保存、每轮 CONFIG 验证和每次任务执行前均使用同一策略检查。请求中只要有一个未授权名称，
+整组请求就在读取宿主变量之前被拒绝，不静默丢弃非法名称。任务执行入口还会在后端探测、
+执行计划和进程创建之前复验；CONFIG 层记录拒绝后可能仍检查后端可用性，但不会因此获得变量权限。
+已有或排队的绑定不能保留旧权限，执行时仍须通过当前已生效配置。
+更改部署配置后必须重启应用才能新增或撤销权限；没有自动刷新磁盘配置的机制。
+已运行进程中的值无法召回，轮换或撤销已转发的值之前应按现有取消流程停止相应运行。
+
+`PATH`、`HOME`、`LANG` 及 Windows 启动名称 `SYSTEMROOT`、`WINDIR`、`COMSPEC`、
+`PATHEXT`、`TEMP`、`TMP` 均为保留项，部署集合不能包含它们，草稿也不能覆盖适配器的可信启动环境。
+授权规则同时适用于 INLINE 和 DOCKER；默认执行模式仍为 Docker。
+Docker CLI 的控制环境继续继承以保持守护进程连接配置，只有通过授权的已清理环境映射会以
+`-e` 形式传给脚本容器。容器隔离和输出脱敏均不能替代环境授权。
+
+`compose.release.yml` 已为空默认透传此设置；其他自定义 Compose/Helm 部署需显式将同名变量
+传入服务器进程，或使用应用配置覆盖。仅在外层 shell 或未透传的 env 文件中设置不代表应用已生效。
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfig.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfig.java
new file mode 100644
index 000000000..981f758c3
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfig.java
@@ -0,0 +1,15 @@
+package com.iflytek.skillhub.config;
+
+import com.iflytek.skillhub.domain.authoring.service.ScriptEnvironmentPolicy;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/** Wires deployment configuration into the domain policy without a reverse module dependency. */
+@Configuration
+public class AuthoringEnvironmentConfig {
+
+    @Bean
+    public ScriptEnvironmentPolicy scriptEnvironmentPolicy(AuthoringProperties properties) {
+        return new ScriptEnvironmentPolicy(() -> properties.getLocalScript().getEnvironmentAllowlist());
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
index e29fd76b1..011ac03f2 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
@@ -68,6 +68,17 @@ public static class LocalScript {
         /** Where scripts run: INLINE on the server host (dev), DOCKER in a locked-down container (production). */
         private ScriptExecutionMode executionMode = ScriptExecutionMode.INLINE;
 
+        /** Deployment-owned variable names available to all local-script draft owners. Empty denies all. */
+        private List<String> environmentAllowlist = List.of();
+
+        public List<String> getEnvironmentAllowlist() {
+            return environmentAllowlist;
+        }
+
+        public void setEnvironmentAllowlist(List<String> environmentAllowlist) {
+            this.environmentAllowlist = environmentAllowlist == null ? List.of() : List.copyOf(environmentAllowlist);
+        }
+
         private final Docker docker = new Docker();
 
         public boolean isEnabled() {
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptRuntimeAdapter.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptRuntimeAdapter.java
index df1f1ae7f..8b44507ea 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptRuntimeAdapter.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptRuntimeAdapter.java
@@ -1,6 +1,7 @@
 package com.iflytek.skillhub.service.authoring.adapter;
 
 import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.service.ScriptEnvironmentPolicy;
 import com.iflytek.skillhub.domain.authoring.runtime.RuntimeEventSink;
 import com.iflytek.skillhub.domain.authoring.runtime.RuntimeExecutionContext;
 import com.iflytek.skillhub.domain.authoring.runtime.SkillRuntimeAdapter;
@@ -24,7 +25,7 @@
 /**
  * Behavior-layer adapter that executes the skill's own scripts in an isolated working
  * directory with a scrubbed environment. Only whitelisted interpreters may run and only
- * environment variables named in the binding's {@code envAllowlist} pass through.
+ * deployment-authorized variables selected by the binding's {@code envAllowlist} pass through.
  *
  * <p>Where the process actually runs is delegated to a {@link ScriptCommandBuilder}:
  * the inline backend spawns the interpreter on the server host, the docker backend
@@ -38,11 +39,24 @@ public class LocalScriptRuntimeAdapter implements SkillRuntimeAdapter {
     private static final long POLL_SLICE_MS = 200;
 
     private final AuthoringProperties properties;
+    private final ScriptEnvironmentPolicy environmentPolicy;
+    private final Function<String, String> environmentLookup;
     private final Map<String, ScriptCommandBuilder> commandBuilders;
 
+    @org.springframework.beans.factory.annotation.Autowired
     public LocalScriptRuntimeAdapter(AuthoringProperties properties,
-                                     List<ScriptCommandBuilder> commandBuilders) {
+                                     List<ScriptCommandBuilder> commandBuilders,
+                                     ScriptEnvironmentPolicy environmentPolicy) {
+        this(properties, commandBuilders, environmentPolicy, System::getenv);
+    }
+
+    LocalScriptRuntimeAdapter(AuthoringProperties properties,
+                              List<ScriptCommandBuilder> commandBuilders,
+                              ScriptEnvironmentPolicy environmentPolicy,
+                              Function<String, String> environmentLookup) {
         this.properties = properties;
+        this.environmentPolicy = environmentPolicy;
+        this.environmentLookup = environmentLookup;
         this.commandBuilders = commandBuilders.stream()
                 .collect(Collectors.toUnmodifiableMap(ScriptCommandBuilder::backend,
                         Function.identity()));
@@ -66,6 +80,8 @@ public boolean enabled() {
     @Override
     public TaskResult execute(RuntimeExecutionContext context, ValidationTaskSpec task,
                               RuntimeEventSink sink) throws Exception {
+        // Recheck the effective policy before probing a backend or creating a process.
+        Map<String, String> scrubbedEnvironment = scrubEnvironment(context);
         ScriptCommandBuilder builder = commandBuilder();
         if (!builder.available()) {
             throw new IllegalStateException(
@@ -75,8 +91,6 @@ public TaskResult execute(RuntimeExecutionContext context, ValidationTaskSpec ta
         String interpreter = resolveInterpreter(context);
         Path scriptPath = resolveInsideWorkingDirectory(context.workingDirectory(), task.script());
         String runTag = context.runId() + "-" + task.name();
-        Map<String, String> scrubbedEnvironment = scrubEnvironment(context);
-
         ScriptCommandBuilder.ScriptExecutionPlan plan = builder.plan(
                 context.workingDirectory(), interpreter, scriptPath,
                 task.safeArgs(), scrubbedEnvironment, runTag);
@@ -132,20 +146,20 @@ private String resolveInterpreter(RuntimeExecutionContext context) {
         return "sh";
     }
 
-    private Map<String, String> scrubEnvironment(RuntimeExecutionContext context) {
+    Map<String, String> scrubEnvironment(RuntimeExecutionContext context) {
+        // Authorize the entire selection before looking up any host value. An old persisted
+        // binding does not retain permission after the effective deployment policy changes.
+        java.util.Set<String> selected = environmentPolicy.authorize(
+                context.safeAdapterConfig().get("envAllowlist"));
         Map<String, String> environment = new java.util.LinkedHashMap<>();
-        environment.put("PATH", System.getenv().getOrDefault("PATH", "/usr/bin:/bin"));
+        String path = environmentLookup.apply("PATH");
+        environment.put("PATH", path == null ? "/usr/bin:/bin" : path);
         environment.put("HOME", context.workingDirectory().toString());
         environment.put("LANG", "C.UTF-8");
-        Object allowlist = context.safeAdapterConfig().get("envAllowlist");
-        if (allowlist instanceof List<?> entries) {
-            for (Object entry : entries) {
-                if (entry != null) {
-                    String value = System.getenv(entry.toString());
-                    if (value != null) {
-                        environment.put(entry.toString(), value);
-                    }
-                }
+        for (String name : selected) {
+            String value = environmentLookup.apply(name);
+            if (value != null) {
+                environment.put(name, value);
             }
         }
         return environment;
diff --git a/server/skillhub-app/src/main/resources/application.yml b/server/skillhub-app/src/main/resources/application.yml
index d7afab883..ed4aec70e 100644
--- a/server/skillhub-app/src/main/resources/application.yml
+++ b/server/skillhub-app/src/main/resources/application.yml
@@ -145,6 +145,8 @@ skillhub:
     maintenance-interval-ms: ${SKILLHUB_AUTHORING_MAINTENANCE_INTERVAL_MS:30000}
     local-script:
       enabled: ${SKILLHUB_AUTHORING_LOCAL_SCRIPT_ENABLED:true}
+      # Deployment ceiling; draft envAllowlist may only select a subset. Empty denies all.
+      environment-allowlist: ${SKILLHUB_AUTHORING_SCRIPT_ENVIRONMENT_ALLOWLIST:}
       # docker is the production default: scripts run in a locked-down container —
       # no network, memory/cpu/pids caps, read-only rootfs, all capabilities dropped.
       # inline runs subprocesses on the server host and is only allowed with a
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfigTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfigTest.java
new file mode 100644
index 000000000..ef22c930f
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfigTest.java
@@ -0,0 +1,63 @@
+package com.iflytek.skillhub.config;
+
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.context.properties.bind.Bindable;
+import org.springframework.boot.context.properties.bind.Binder;
+import org.springframework.boot.context.properties.source.MapConfigurationPropertySource;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.AnnotationConfigApplicationContext;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.env.MapPropertySource;
+import com.iflytek.skillhub.domain.authoring.service.RuntimeBindingValidator;
+import com.iflytek.skillhub.service.authoring.adapter.LocalScriptRuntimeAdapter;
+import com.iflytek.skillhub.service.authoring.adapter.InlineScriptCommandBuilder;
+import static org.assertj.core.api.Assertions.*;
+
+class AuthoringEnvironmentConfigTest {
+    @Configuration(proxyBeanMethods = false)
+    @EnableConfigurationProperties(AuthoringProperties.class)
+    static class PropertiesConfiguration { }
+
+    @Test void springContainerInjectsTheSharedPolicyIntoBothEntryPoints() {
+        try (var context = new AnnotationConfigApplicationContext()) {
+            context.getEnvironment().getPropertySources().addFirst(new MapPropertySource("dummy-deployment", Map.of(
+                    "skillhub.authoring.local-script.environment-allowlist", "AUTHORING_DEMO")));
+            context.register(PropertiesConfiguration.class, AuthoringEnvironmentConfig.class,
+                    RuntimeBindingValidator.class, LocalScriptRuntimeAdapter.class, InlineScriptCommandBuilder.class);
+            context.refresh();
+            var validator = context.getBean(RuntimeBindingValidator.class);
+            assertThat(context.getBean(LocalScriptRuntimeAdapter.class).agentType()).isEqualTo("local-script");
+            var config = Map.<String, Object>of("envAllowlist", List.of("AUTHORING_DEMO"));
+            assertThat(validator.validate("local-script", config, null, null)).isEmpty();
+            context.getBean(AuthoringProperties.class).getLocalScript().setEnvironmentAllowlist(List.of());
+            assertThat(validator.validate("local-script", config, null, null)).hasSize(1);
+        }
+    }
+    @Test void defaultPropertiesDenyAllAndBeanSharesEffectiveSettings() {
+        var properties = new AuthoringProperties();
+        var policy = new AuthoringEnvironmentConfig().scriptEnvironmentPolicy(properties);
+        assertThatThrownBy(() -> policy.authorize(List.of("AUTHORING_DEMO"))).isInstanceOf(IllegalArgumentException.class);
+        properties.getLocalScript().setEnvironmentAllowlist(List.of("AUTHORING_DEMO"));
+        assertThat(policy.authorize(List.of("AUTHORING_DEMO"))).containsExactly("AUTHORING_DEMO");
+        properties.getLocalScript().setEnvironmentAllowlist(null);
+        assertThatThrownBy(() -> policy.authorize(List.of("AUTHORING_DEMO"))).isInstanceOf(IllegalArgumentException.class);
+    }
+    @Test void commaSeparatedSettingBindsWithoutChangingDockerMode() {
+        var source = new MapConfigurationPropertySource(Map.of(
+                "skillhub.authoring.local-script.environment-allowlist", "AUTHORING_DEMO,AUTHORING_OTHER",
+                "skillhub.authoring.local-script.execution-mode", "docker"));
+        var properties = new Binder(source).bind("skillhub.authoring", Bindable.of(AuthoringProperties.class)).get();
+        assertThat(properties.getLocalScript().getExecutionMode()).isEqualTo(AuthoringProperties.ScriptExecutionMode.DOCKER);
+        assertThat(properties.getLocalScript().getEnvironmentAllowlist()).containsExactly("AUTHORING_DEMO", "AUTHORING_OTHER");
+        assertThat(new AuthoringEnvironmentConfig().scriptEnvironmentPolicy(properties).authorize(List.of("AUTHORING_DEMO")))
+                .containsExactly("AUTHORING_DEMO");
+    }
+    @Test void explicitEmptySettingBindsToDenyAll() {
+        var source = new MapConfigurationPropertySource(Map.of(
+                "skillhub.authoring.local-script.environment-allowlist", ""));
+        var properties = new Binder(source).bind("skillhub.authoring", Bindable.of(AuthoringProperties.class)).get();
+        assertThat(properties.getLocalScript().getEnvironmentAllowlist()).isEmpty();
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptEnvironmentAuthorizationTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptEnvironmentAuthorizationTest.java
new file mode 100644
index 000000000..c110460d5
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptEnvironmentAuthorizationTest.java
@@ -0,0 +1,112 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeExecutionContext;
+import com.iflytek.skillhub.domain.authoring.service.ScriptEnvironmentPolicy;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import static org.assertj.core.api.Assertions.*;
+
+class LocalScriptEnvironmentAuthorizationTest {
+    @TempDir Path workspace;
+    private static final String DEMO = "AUTHORING_DEMO";
+    private final AuthoringProperties properties = new AuthoringProperties();
+    private RuntimeExecutionContext context(Object selection) {
+        return new RuntimeExecutionContext(1L, Path.of("dummy-workspace").toAbsolutePath(),
+                selection == null ? Map.of() : Map.of("envAllowlist", selection), List.of(), null);
+    }
+    @Test void onlySelectedDefinedDummyValuesAreResolved() {
+        properties.getLocalScript().setEnvironmentAllowlist(List.of(DEMO, "AUTHORING_UNDEFINED", "AUTHORING_OTHER"));
+        var calls = new ArrayList<String>();
+        var adapter = adapter(calls);
+        var result = adapter.scrubEnvironment(context(List.of(DEMO, "AUTHORING_UNDEFINED")));
+        assertThat(result).containsEntry(DEMO, "dummy-value").containsEntry("PATH", "/dummy/bin")
+                .containsEntry("LANG", "C.UTF-8").containsEntry("HOME", context(null).workingDirectory().toString())
+                .doesNotContainKeys("AUTHORING_UNDEFINED", "AUTHORING_OTHER");
+        assertThat(calls).containsExactly("PATH", DEMO, "AUTHORING_UNDEFINED");
+    }
+    @Test void emptyBindingGetsOnlyTrustedStartupEnvironment() {
+        var calls = new ArrayList<String>();
+        var result = adapter(calls).scrubEnvironment(context(null));
+        assertThat(result.keySet()).containsExactly("PATH", "HOME", "LANG");
+        assertThat(calls).containsExactly("PATH");
+    }
+    @Test void unauthorizedMixedSelectionIsRejectedBeforeAnyLookup() {
+        properties.getLocalScript().setEnvironmentAllowlist(List.of(DEMO));
+        var calls = new ArrayList<String>();
+        var adapter = adapter(calls);
+        assertThatThrownBy(() -> adapter.scrubEnvironment(context(List.of(DEMO, "AUTHORING_DENIED"))))
+                .isInstanceOf(IllegalArgumentException.class).hasMessageNotContaining("dummy-value");
+        assertThat(calls).isEmpty();
+    }
+    @Test void savedBindingIsRejectedAfterEffectiveRevocation() {
+        properties.getLocalScript().setEnvironmentAllowlist(List.of(DEMO));
+        var calls = new ArrayList<String>();
+        var adapter = adapter(calls);
+        var saved = context(List.of(DEMO));
+        assertThat(adapter.scrubEnvironment(saved)).containsKey(DEMO);
+        properties.getLocalScript().setEnvironmentAllowlist(List.of());
+        calls.clear();
+        assertThatThrownBy(() -> adapter.scrubEnvironment(saved)).isInstanceOf(IllegalArgumentException.class);
+        assertThat(calls).isEmpty();
+    }
+    @Test void reservedAliasesNeverReachLookup() {
+        var calls = new ArrayList<String>();
+        var adapter = adapter(calls);
+        for (String name : List.of("PATH", "Path", "path", "HOME", "LANG", "SYSTEMROOT", "SystemRoot")) {
+            assertThatThrownBy(() -> adapter.scrubEnvironment(context(List.of(name))))
+                    .isInstanceOf(IllegalArgumentException.class);
+        }
+        assertThat(calls).isEmpty();
+    }
+    @Test void bothBackendModesRejectBeforeAvailabilityProbeOrPlanning() {
+        for (var mode : AuthoringProperties.ScriptExecutionMode.values()) {
+            properties.getLocalScript().setExecutionMode(mode);
+            String backend = mode == AuthoringProperties.ScriptExecutionMode.DOCKER ? "docker" : "inline";
+            ScriptCommandBuilder builder = new ScriptCommandBuilder() {
+                public String backend() { return backend; }
+                public boolean available() { throw new AssertionError("must not probe backend"); }
+                public ScriptExecutionPlan plan(Path w, String i, Path s, List<String> a, Map<String,String> e, String t) {
+                    throw new AssertionError("must not plan backend");
+                }
+            };
+            var adapter = new LocalScriptRuntimeAdapter(properties, List.of(builder),
+                    new ScriptEnvironmentPolicy(() -> properties.getLocalScript().getEnvironmentAllowlist()),
+                    name -> { throw new AssertionError("must not look up environment"); });
+            assertThatThrownBy(() -> adapter.execute(context(List.of(DEMO)), null, null))
+                    .isInstanceOf(IllegalArgumentException.class);
+        }
+    }
+    @Test void inlinePlanReceivesOnlyAuthorizedMap() {
+        properties.getLocalScript().setEnvironmentAllowlist(List.of(DEMO));
+        var ctx = context(List.of(DEMO));
+        var environment = adapter(new ArrayList<>()).scrubEnvironment(ctx);
+        var plan = new InlineScriptCommandBuilder().plan(ctx.workingDirectory(), "sh",
+                ctx.workingDirectory().resolve("check.sh"), List.of(), environment, "dummy");
+        assertThat(plan.environment()).containsEntry(DEMO, "dummy-value").hasSize(4);
+        assertThat(plan.command()).hasSize(2);
+    }
+    @Test void dockerPlanForwardsOnlyAuthorizedMapWithoutStartingContainer() {
+        properties.getLocalScript().setEnvironmentAllowlist(List.of(DEMO));
+        var ctx = context(List.of(DEMO));
+        var environment = adapter(new ArrayList<>()).scrubEnvironment(ctx);
+        var plan = new DockerScriptCommandBuilder(properties).plan(workspace, "sh",
+                workspace.resolve("check.sh"), List.of(), environment, "dummy");
+        assertThat(plan.environment()).isNull(); // CLI control environment remains inherited.
+        assertThat(plan.command()).contains(DEMO + "=dummy-value", "HOME=/workspace", "--read-only");
+        assertThat(plan.command()).doesNotContain("AUTHORING_UNDEFINED=", "AUTHORING_DENIED=");
+        assertThat(plan.command().stream().filter("-e"::equals).count()).isEqualTo(4);
+    }
+    private LocalScriptRuntimeAdapter adapter(List<String> calls) {
+        return new LocalScriptRuntimeAdapter(properties, List.of(),
+                new ScriptEnvironmentPolicy(() -> properties.getLocalScript().getEnvironmentAllowlist()),
+                name -> {
+                    calls.add(name);
+                    return switch (name) { case "PATH" -> "/dummy/bin"; case DEMO -> "dummy-value"; default -> null; };
+                });
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptEnvironmentExecutionTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptEnvironmentExecutionTest.java
new file mode 100644
index 000000000..4ee8d882d
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/LocalScriptEnvironmentExecutionTest.java
@@ -0,0 +1,108 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeEventSink;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeExecutionContext;
+import com.iflytek.skillhub.domain.authoring.service.ScriptEnvironmentPolicy;
+import com.iflytek.skillhub.domain.authoring.spec.TaskType;
+import com.iflytek.skillhub.domain.authoring.spec.ValidationTaskSpec;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledOnOs;
+import org.junit.jupiter.api.condition.OS;
+import org.junit.jupiter.api.io.TempDir;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+@EnabledOnOs({OS.LINUX, OS.MAC})
+class LocalScriptEnvironmentExecutionTest {
+
+    @TempDir
+    Path workspace;
+
+    @Test
+    void realScriptReceivesSelectedSyntheticValueAndStreamsItsOutput() throws Exception {
+        Files.writeString(workspace.resolve("check.sh"), """
+                printf '%s|%s' "$AUTHORING_DEMO" "${AUTHORING_UNSELECTED-unset}" > executed.txt
+                printf '%s\\n' "$AUTHORING_DEMO"
+                """);
+        var lookups = new ArrayList<String>();
+        var sink = new RecordingSink();
+
+        var result = adapter(lookups).execute(context(List.of("AUTHORING_DEMO")), task(), sink);
+
+        assertThat(result.exitCode()).isZero();
+        assertThat(result.stdout()).isEqualTo("synthetic-review-value");
+        assertThat(result.stderr()).isEmpty();
+        assertThat(Files.readString(workspace.resolve("executed.txt")))
+                .isEqualTo("synthetic-review-value|unset");
+        assertThat(sink.logs).containsExactly("synthetic-review-value");
+        assertThat(lookups).containsExactly("PATH", "AUTHORING_DEMO");
+    }
+
+    @Test
+    void deniedSelectionDoesNotStartTheRealScriptOrLookUpValues() throws Exception {
+        Files.writeString(workspace.resolve("check.sh"), "printf 'started' > executed.txt\n");
+        var lookups = new ArrayList<String>();
+        var sink = new RecordingSink();
+        var adapter = adapter(lookups);
+
+        assertThatThrownBy(() -> adapter.execute(
+                context(List.of("AUTHORING_DEMO", "AUTHORING_DENIED")), task(), sink))
+                .isInstanceOf(IllegalArgumentException.class);
+
+        assertThat(workspace.resolve("executed.txt")).doesNotExist();
+        assertThat(lookups).isEmpty();
+        assertThat(sink.logs).isEmpty();
+        assertThat(sink.toolCalls).isZero();
+    }
+
+    private LocalScriptRuntimeAdapter adapter(List<String> lookups) {
+        var properties = new AuthoringProperties();
+        properties.getLocalScript().setExecutionMode(AuthoringProperties.ScriptExecutionMode.INLINE);
+        properties.getLocalScript().setEnvironmentAllowlist(List.of("AUTHORING_DEMO", "AUTHORING_UNSELECTED"));
+        return new LocalScriptRuntimeAdapter(properties, List.of(new InlineScriptCommandBuilder()),
+                new ScriptEnvironmentPolicy(() -> properties.getLocalScript().getEnvironmentAllowlist()),
+                name -> {
+                    lookups.add(name);
+                    return "PATH".equals(name) ? "/usr/bin:/bin" : "synthetic-review-value";
+                });
+    }
+
+    private RuntimeExecutionContext context(List<String> selection) {
+        return new RuntimeExecutionContext(1L, workspace,
+                Map.of("interpreter", "sh", "envAllowlist", selection), List.of(), null);
+    }
+
+    private ValidationTaskSpec task() {
+        return new ValidationTaskSpec("environment-check", "", TaskType.SCRIPT,
+                "check.sh", List.of(), null, 5_000, List.of());
+    }
+
+    private static final class RecordingSink implements RuntimeEventSink {
+        private final List<String> logs = Collections.synchronizedList(new ArrayList<>());
+        private int toolCalls;
+
+        @Override
+        public void agentMessage(String taskName, String content) { }
+
+        @Override
+        public void toolCall(String taskName, String tool, String argumentsJson) {
+            toolCalls++;
+        }
+
+        @Override
+        public void toolResult(String taskName, String tool, String summaryJson) { }
+
+        @Override
+        public void log(String taskName, String stream, String line) {
+            logs.add(line);
+        }
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
index bd6cf6da6..e5273dd80 100644
--- a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
@@ -29,7 +29,10 @@ public class RuntimeBindingValidator {
     private static final List<String> TRANSPORTS = List.of("http", "sse", "stdio");
     private static final List<String> INTERPRETERS = List.of("sh", "bash", "python3", "node");
 
-    public RuntimeBindingValidator() {
+    private final ScriptEnvironmentPolicy environmentPolicy;
+
+    public RuntimeBindingValidator(ScriptEnvironmentPolicy environmentPolicy) {
+        this.environmentPolicy = environmentPolicy;
     }
 
     /**
@@ -83,11 +86,17 @@ private void validateLocalScriptConfig(Map<String, Object> config, List<FindingD
         Object envAllowlist = config.get("envAllowlist");
         if (envAllowlist instanceof List<?> entries) {
             for (Object entry : entries) {
-                if (entry == null || !ENV_REF_NAME.matcher(entry.toString()).matches()) {
+                if (!(entry instanceof String name) || !ENV_REF_NAME.matcher(name).matches()) {
                     findings.add(FindingDraft.error(ValidationLayer.CONFIG, "ENV_ALLOWLIST_INVALID",
                             "Invalid environment variable name: " + entry));
                 }
             }
+            try {
+                environmentPolicy.authorize(entries);
+            } catch (IllegalArgumentException exception) {
+                findings.add(FindingDraft.error(ValidationLayer.CONFIG, "ENV_ALLOWLIST_FORBIDDEN",
+                        "Environment selection is not permitted by deployment policy"));
+            }
         } else if (envAllowlist != null) {
             findings.add(FindingDraft.error(ValidationLayer.CONFIG, "ENV_ALLOWLIST_INVALID",
                     "envAllowlist must be a list of variable names"));
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicy.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicy.java
new file mode 100644
index 000000000..291da481c
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicy.java
@@ -0,0 +1,61 @@
+package com.iflytek.skillhub.domain.authoring.service;
+
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Locale;
+import java.util.Set;
+import java.util.function.Supplier;
+import java.util.regex.Pattern;
+
+/** Deployment-owned ceiling; a draft may only select a subset, never grant access. */
+public final class ScriptEnvironmentPolicy {
+
+    private static final Pattern NAME = Pattern.compile("^[A-Z][A-Z0-9_]{0,63}$");
+    private static final Set<String> RESERVED = Set.of(
+            "PATH", "HOME", "LANG", "SYSTEMROOT", "WINDIR", "COMSPEC", "PATHEXT", "TEMP", "TMP");
+    private final Supplier<List<String>> deploymentAllowlist;
+
+    public ScriptEnvironmentPolicy(Supplier<List<String>> deploymentAllowlist) {
+        this.deploymentAllowlist = java.util.Objects.requireNonNull(deploymentAllowlist);
+        allowedNames();
+    }
+
+    /** Reads the currently effective deployment policy on every call, including execution. */
+    public Set<String> authorize(Object requested) {
+        Set<String> allowed = allowedNames();
+        if (requested == null) {
+            return Set.of();
+        }
+        if (!(requested instanceof List<?> entries)) {
+            throw new IllegalArgumentException("envAllowlist must be a list of variable names");
+        }
+        Set<String> selected = new LinkedHashSet<>();
+        for (Object entry : entries) {
+            if (!(entry instanceof String name) || !validName(name) || !allowed.contains(name)) {
+                throw new IllegalArgumentException(
+                        "envAllowlist contains a variable not permitted by deployment policy");
+            }
+            selected.add(name);
+        }
+        return java.util.Collections.unmodifiableSet(selected);
+    }
+
+    private Set<String> allowedNames() {
+        List<String> configured = deploymentAllowlist.get();
+        if (configured == null) {
+            return Set.of();
+        }
+        Set<String> allowed = new LinkedHashSet<>();
+        for (String name : configured) {
+            if (name == null || !validName(name)) {
+                throw new IllegalStateException("Invalid local-script deployment environment allowlist");
+            }
+            allowed.add(name);
+        }
+        return Set.copyOf(allowed);
+    }
+
+    private static boolean validName(String name) {
+        return NAME.matcher(name).matches() && !RESERVED.contains(name.toUpperCase(Locale.ROOT));
+    }
+}
diff --git a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingEnvironmentAuthorizationTest.java b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingEnvironmentAuthorizationTest.java
new file mode 100644
index 000000000..4f8243203
--- /dev/null
+++ b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingEnvironmentAuthorizationTest.java
@@ -0,0 +1,55 @@
+package com.iflytek.skillhub.domain.authoring.service;
+
+import com.iflytek.skillhub.domain.authoring.*;
+import com.iflytek.skillhub.domain.shared.exception.*;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.Mockito.*;
+import static org.mockito.ArgumentMatchers.*;
+
+class RuntimeBindingEnvironmentAuthorizationTest {
+    @Test void ordinaryDraftOwnerCanSaveOnlyDeploymentApprovedSelection() {
+        var bindings = mock(RuntimeBindingRepository.class);
+        var drafts = mock(SkillDraftRepository.class);
+        var policy = new ScriptEnvironmentPolicy(() -> List.of("AUTHORING_DEMO"));
+        var service = new RuntimeBindingService(bindings, drafts, new RuntimeBindingValidator(policy));
+        when(drafts.findById(7L)).thenReturn(Optional.of(new SkillDraft(1L, "ordinary-member", "test", "test", "digest")));
+        when(bindings.findByDraftId(7L)).thenReturn(Optional.empty());
+        when(bindings.save(any())).thenAnswer(call -> call.getArgument(0));
+        var result = service.saveBinding(7L, "ordinary-member", "local-script",
+                Map.of("envAllowlist", List.of("AUTHORING_DEMO")), null, null, Set.of());
+        assertThat(result.getConfig()).containsKey("envAllowlist");
+        verify(bindings).save(any());
+        clearInvocations(bindings);
+        assertThatThrownBy(() -> service.saveBinding(7L, "ordinary-member", "local-script",
+                Map.of("envAllowlist", List.of("AUTHORING_OTHER")), null, null, Set.of()))
+                .isInstanceOf(DomainBadRequestException.class);
+        verify(bindings, never()).save(any());
+    }
+    @Test void superAdminRoleDoesNotExpandDeploymentGrant() {
+        var bindings = mock(RuntimeBindingRepository.class);
+        var drafts = mock(SkillDraftRepository.class);
+        when(drafts.findById(7L)).thenReturn(Optional.of(new SkillDraft(1L, "ordinary-member", "test", "test", "digest")));
+        var service = new RuntimeBindingService(bindings, drafts,
+                new RuntimeBindingValidator(new ScriptEnvironmentPolicy(List::of)));
+        assertThatThrownBy(() -> service.saveBinding(7L, "admin", "local-script",
+                Map.of("envAllowlist", List.of("AUTHORING_DEMO")), null, null, Set.of("SUPER_ADMIN")))
+                .isInstanceOf(DomainBadRequestException.class);
+        verify(bindings, never()).save(any());
+    }
+    @Test void nonOwnerCannotUseAnOtherwiseAuthorizedSelection() {
+        var bindings = mock(RuntimeBindingRepository.class);
+        var drafts = mock(SkillDraftRepository.class);
+        when(drafts.findById(7L)).thenReturn(Optional.of(new SkillDraft(1L, "owner", "test", "test", "digest")));
+        var service = new RuntimeBindingService(bindings, drafts,
+                new RuntimeBindingValidator(new ScriptEnvironmentPolicy(() -> List.of("AUTHORING_DEMO"))));
+        assertThatThrownBy(() -> service.saveBinding(7L, "other-member", "local-script",
+                Map.of("envAllowlist", List.of("AUTHORING_DEMO")), null, null, Set.of()))
+                .isInstanceOf(DomainForbiddenException.class);
+        verify(bindings, never()).save(any());
+    }
+}
diff --git a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicyTest.java b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicyTest.java
new file mode 100644
index 000000000..433346b3a
--- /dev/null
+++ b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicyTest.java
@@ -0,0 +1,70 @@
+package com.iflytek.skillhub.domain.authoring.service;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicReference;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.*;
+
+class ScriptEnvironmentPolicyTest {
+    @Test void emptyDeploymentDeniesRequestedVariable() {
+        var policy = new ScriptEnvironmentPolicy(List::of);
+        assertThat(policy.authorize(null)).isEmpty();
+        assertThat(policy.authorize(List.of())).isEmpty();
+        assertThatThrownBy(() -> policy.authorize(List.of("AUTHORING_DEMO")))
+                .isInstanceOf(IllegalArgumentException.class);
+    }
+    @Test void acceptsOnlySelectedSubsetAndDeduplicates() {
+        var policy = new ScriptEnvironmentPolicy(() -> List.of("AUTHORING_DEMO", "AUTHORING_OTHER"));
+        assertThat(policy.authorize(List.of("AUTHORING_DEMO", "AUTHORING_DEMO")))
+                .containsExactly("AUTHORING_DEMO");
+        assertThat(policy.authorize(List.of())).isEmpty();
+    }
+    @Test void mixedSelectionIsRejectedAsAWhole() {
+        var policy = new ScriptEnvironmentPolicy(() -> List.of("AUTHORING_DEMO"));
+        assertThatThrownBy(() -> policy.authorize(List.of("AUTHORING_DEMO", "AUTHORING_OTHER")))
+                .isInstanceOf(IllegalArgumentException.class);
+    }
+    @Test void malformedAndNonStringNamesCannotCoerceOrMatch() {
+        var policy = new ScriptEnvironmentPolicy(() -> List.of("AUTHORING_DEMO"));
+        for (Object value : List.of(42, Map.of("name", "AUTHORING_DEMO"), "authoring_demo", " AUTHORING_DEMO", "AUTHORING_DEMO ", "A-B", "A".repeat(65))) {
+            assertThatThrownBy(() -> policy.authorize(List.of(value))).isInstanceOf(IllegalArgumentException.class);
+        }
+        assertThatThrownBy(() -> policy.authorize(Arrays.asList((Object) null))).isInstanceOf(IllegalArgumentException.class);
+        assertThatThrownBy(() -> policy.authorize("AUTHORING_DEMO")).isInstanceOf(IllegalArgumentException.class);
+    }
+    @Test void reservedNamesCannotBeAuthorizedByDeployment() {
+        for (String reserved : List.of("PATH", "HOME", "LANG", "SYSTEMROOT", "WINDIR", "COMSPEC", "PATHEXT", "TEMP", "TMP", "Path", "path")) {
+            assertThatThrownBy(() -> new ScriptEnvironmentPolicy(() -> List.of(reserved)))
+                    .isInstanceOf(IllegalStateException.class);
+        }
+    }
+    @Test void malformedDeploymentFailsClosed() {
+        assertThatThrownBy(() -> new ScriptEnvironmentPolicy(() -> List.of("bad-name")))
+                .isInstanceOf(IllegalStateException.class);
+        assertThatThrownBy(() -> new ScriptEnvironmentPolicy(() -> Arrays.asList((String) null)))
+                .isInstanceOf(IllegalStateException.class);
+        assertThat(new ScriptEnvironmentPolicy(() -> null).authorize(null)).isEmpty();
+    }
+    @Test void effectiveRevocationAppliesToPreviouslyValidSelection() {
+        var current = new AtomicReference<>(List.of("AUTHORING_DEMO"));
+        var policy = new ScriptEnvironmentPolicy(current::get);
+        var selection = List.of("AUTHORING_DEMO");
+        assertThat(policy.authorize(selection)).containsExactly("AUTHORING_DEMO");
+        current.set(List.of());
+        assertThatThrownBy(() -> policy.authorize(selection)).isInstanceOf(IllegalArgumentException.class);
+        current.set(List.of("PATH"));
+        assertThatThrownBy(() -> policy.authorize(null)).isInstanceOf(IllegalStateException.class);
+    }
+    @Test void configValidationUsesCurrentPolicyWithoutDisclosingValues() {
+        var current = new AtomicReference<>(List.of("AUTHORING_DEMO"));
+        var validator = new RuntimeBindingValidator(new ScriptEnvironmentPolicy(current::get));
+        var config = Map.<String, Object>of("interpreter", "sh", "envAllowlist", List.of("AUTHORING_DEMO"));
+        assertThat(validator.validate("local-script", config, null, null)).isEmpty();
+        current.set(List.of());
+        assertThat(validator.validate("local-script", config, null, null))
+                .extracting(finding -> finding.ruleCode()).containsExactly("ENV_ALLOWLIST_FORBIDDEN");
+    }
+}

From 4c8399d7554008cb5b8b488a746dda62da54d920 Mon Sep 17 00:00:00 2001
From: zjncs <18910855655@163.com>
Date: Thu, 22 Oct 2026 13:40:30 +0800
Subject: [PATCH 15/17] feat(authoring): MCP probing and the endpoint/stdio/env
 security policies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Layer (b2) of the authoring platform (#934), the second half of the split
runtime layer — the surface for the dedicated security review:

- **Shared AuthoringSecurityPolicy** gates OpenAI-compatible and http/sse
  MCP endpoints at save time and again at connect time: cloud-metadata/
  link-local/multicast always rejected; loopback/RFC1918/ULA/CGNAT/
  RFC 2544 behind per-surface allow-private-endpoints flags (default
  off); unresolvable hosts rejected. The policy resolves through an
  injectable resolver so tests stay hermetic.
- **stdio MCP**: off by default; in docker execution-mode its command
  runs inside a hardened container torn down on close; envRefs limited
  to the operator-configured allowlist (default empty = all rejected).
- **MCP probing during validation**: declared servers are connected,
  initialized and tools/list-ed for real before the behavior layer
  relies on them; discovered tools surface in the event stream, unknown
  toolFilters warn without failing.
- **OpenAI-compatible adapter** for prompt tasks with an MCP tool loop,
  guarded by the same endpoint policy; execution-mode defaults to docker
  and inline fails startup outside local/dev/test (AuthoringStartupGuard).
- HTTP redirects never followed; response bodies and stdio lines capped
  at 2 MiB.
- Also repairs an application.yml merge artifact from the previous
  monolithic branch: the authoring runtime keys had been nested under
  github-sync; they now sit under skillhub.authoring where they belong.

Verified: security-policy classification per surface (hermetic DNS),
redirect refusal against the metadata range, response/line caps, envRef
allowlist filtering, docker-wrapped command construction, MCP handshake
against a real local HTTP server, stdio against a python3 subprocess,
OpenAI tool loop with MCP execution (48 tests), and the runtime flow
integration test covering the save-time rejections (cloud-metadata
endpoints, non-allowlisted envRefs, metadata-range LLM endpoints) plus
the MCP-probed three-layer validation.

Signed-off-by: zjncs <18910855655@163.com>
---
 .../skillhub/config/AuthoringProperties.java  | 188 ++++++++++
 .../config/AuthoringStartupGuard.java         |  51 +++
 .../ConfiguredAuthoringSecurityPolicy.java    | 142 +++++++
 .../authoring/ValidationRunOrchestrator.java  |  26 +-
 .../OpenAiCompatibleRuntimeAdapter.java       | 345 ++++++++++++++++++
 .../service/authoring/mcp/HttpMcpClient.java  | 264 ++++++++++++++
 .../service/authoring/mcp/McpClient.java      |  29 ++
 .../authoring/mcp/McpClientFactory.java       | 159 ++++++++
 .../authoring/mcp/McpProbeService.java        |  92 +++++
 .../service/authoring/mcp/McpTool.java        |  14 +
 .../service/authoring/mcp/StdioMcpClient.java | 236 ++++++++++++
 .../src/main/resources/application.yml        |  29 ++
 .../src/main/resources/messages.properties    |   2 +
 .../src/main/resources/messages_ru.properties |   2 +
 .../src/main/resources/messages_zh.properties |   2 +
 .../AuthoringRuntimeFlowIntegrationTest.java  | 225 ++++++++++++
 .../AuthoringEnvironmentConfigTest.java       |  16 +-
 .../config/AuthoringStartupGuardTest.java     |  70 ++++
 ...ConfiguredAuthoringSecurityPolicyTest.java | 151 ++++++++
 .../TestingAuthoringSecurityPolicy.java       |  53 +++
 .../ValidationRunOrchestratorTest.java        |   4 +-
 ...iCompatibleRuntimeAdapterToolLoopTest.java | 281 ++++++++++++++
 .../authoring/mcp/HttpMcpClientTest.java      | 172 +++++++++
 .../authoring/mcp/McpClientFactoryTest.java   | 148 ++++++++
 .../authoring/mcp/McpProbeServiceTest.java    |  98 +++++
 .../authoring/mcp/StdioMcpClientTest.java     | 133 +++++++
 .../authoring/mcp/TestingMcpHttpServer.java   | 156 ++++++++
 .../src/test/resources/application-test.yml   |  10 +
 .../service/AuthoringSecurityPolicy.java      |  33 ++
 .../service/RuntimeBindingValidator.java      |  38 +-
 ...meBindingEnvironmentAuthorizationTest.java |  13 +-
 .../service/ScriptEnvironmentPolicyTest.java  |   9 +-
 32 files changed, 3173 insertions(+), 18 deletions(-)
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringStartupGuard.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/config/ConfiguredAuthoringSecurityPolicy.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/OpenAiCompatibleRuntimeAdapter.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/HttpMcpClient.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpClient.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpClientFactory.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpProbeService.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpTool.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/StdioMcpClient.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringRuntimeFlowIntegrationTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringStartupGuardTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/config/ConfiguredAuthoringSecurityPolicyTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/TestingAuthoringSecurityPolicy.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/OpenAiCompatibleRuntimeAdapterToolLoopTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/HttpMcpClientTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/McpClientFactoryTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/McpProbeServiceTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/StdioMcpClientTest.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/TestingMcpHttpServer.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/AuthoringSecurityPolicy.java

diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
index 011ac03f2..c95761b4d 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringProperties.java
@@ -25,6 +25,10 @@ public class AuthoringProperties {
 
     private final LocalScript localScript = new LocalScript();
 
+    private final OpenAiCompatible openAiCompatible = new OpenAiCompatible();
+
+    private final Mcp mcp = new Mcp();
+
     public String getWorkspaceRoot() {
         return workspaceRoot;
     }
@@ -61,6 +65,14 @@ public LocalScript getLocalScript() {
         return localScript;
     }
 
+    public OpenAiCompatible getOpenAiCompatible() {
+        return openAiCompatible;
+    }
+
+    public Mcp getMcp() {
+        return mcp;
+    }
+
     /** Local script execution runtime. */
     public static class LocalScript {
         private boolean enabled = true;
@@ -157,4 +169,180 @@ public enum ScriptExecutionMode {
         DOCKER
     }
 
+    /**
+     * OpenAI-compatible chat completion runtime. The API key is resolved here
+     * (environment/config), never from a per-draft runtime binding.
+     */
+    public static class OpenAiCompatible {
+        private boolean enabled = false;
+        private String apiKey;
+        private String defaultEndpoint;
+        private String defaultModel;
+        private int timeoutMs = 120_000;
+        /** Max chat-completion rounds per prompt task (each round may execute MCP tool calls). */
+        private int maxToolRounds = 4;
+        /**
+         * SSRF guard escape hatch for enterprise deployments whose LLM endpoint
+         * lives on a private network (e.g. an internal vLLM). Loopback and
+         * RFC1918 destinations stay blocked by default; link-local (cloud
+         * metadata) is always blocked.
+         */
+        private boolean allowPrivateEndpoints = false;
+
+        public boolean isEnabled() {
+            return enabled;
+        }
+
+        public void setEnabled(boolean enabled) {
+            this.enabled = enabled;
+        }
+
+        public String getApiKey() {
+            return apiKey;
+        }
+
+        public void setApiKey(String apiKey) {
+            this.apiKey = apiKey;
+        }
+
+        public String getDefaultEndpoint() {
+            return defaultEndpoint;
+        }
+
+        public void setDefaultEndpoint(String defaultEndpoint) {
+            this.defaultEndpoint = defaultEndpoint;
+        }
+
+        public String getDefaultModel() {
+            return defaultModel;
+        }
+
+        public void setDefaultModel(String defaultModel) {
+            this.defaultModel = defaultModel;
+        }
+
+        public int getTimeoutMs() {
+            return timeoutMs;
+        }
+
+        public void setTimeoutMs(int timeoutMs) {
+            this.timeoutMs = timeoutMs;
+        }
+
+        public int getMaxToolRounds() {
+            return maxToolRounds;
+        }
+
+        public void setMaxToolRounds(int maxToolRounds) {
+            this.maxToolRounds = maxToolRounds;
+        }
+
+        public boolean isAllowPrivateEndpoints() {
+            return allowPrivateEndpoints;
+        }
+
+        public void setAllowPrivateEndpoints(boolean allowPrivateEndpoints) {
+            this.allowPrivateEndpoints = allowPrivateEndpoints;
+        }
+    }
+
+    /**
+     * Security knobs for user-declared MCP servers. Defaults are the safe
+     * production posture: private endpoints blocked, stdio transport off, no
+     * environment references allowed. Local development relaxes them via
+     * application-local.yml.
+     */
+    public static class Mcp {
+        /**
+         * When false (default), http/sse MCP endpoints pointing at loopback,
+         * RFC1918, ULA, or CGNAT addresses are rejected. Link-local addresses
+         * (cloud metadata) are always rejected.
+         */
+        private boolean allowPrivateEndpoints = false;
+
+        /** When false (default), stdio MCP servers cannot be declared or spawned. */
+        private boolean stdioEnabled = false;
+
+        /** Server environment variables a binding may reference via envRefs. */
+        private List<String> envAllowlist = new ArrayList<>();
+
+        private final Docker docker = new Docker();
+
+        public boolean isAllowPrivateEndpoints() {
+            return allowPrivateEndpoints;
+        }
+
+        public void setAllowPrivateEndpoints(boolean allowPrivateEndpoints) {
+            this.allowPrivateEndpoints = allowPrivateEndpoints;
+        }
+
+        public boolean isStdioEnabled() {
+            return stdioEnabled;
+        }
+
+        public void setStdioEnabled(boolean stdioEnabled) {
+            this.stdioEnabled = stdioEnabled;
+        }
+
+        public List<String> getEnvAllowlist() {
+            return envAllowlist;
+        }
+
+        public void setEnvAllowlist(List<String> envAllowlist) {
+            this.envAllowlist = envAllowlist;
+        }
+
+        public Docker getDocker() {
+            return docker;
+        }
+
+        /** Isolation profile for stdio MCP servers in docker execution mode. */
+        public static class Docker {
+            private String image = "alpine:3.20";
+            private String memory = "256m";
+            private String cpus = "1.0";
+            private int pidsLimit = 128;
+            private String tmpfsSize = "64m";
+
+            public String getImage() {
+                return image;
+            }
+
+            public void setImage(String image) {
+                this.image = image;
+            }
+
+            public String getMemory() {
+                return memory;
+            }
+
+            public void setMemory(String memory) {
+                this.memory = memory;
+            }
+
+            public String getCpus() {
+                return cpus;
+            }
+
+            public void setCpus(String cpus) {
+                this.cpus = cpus;
+            }
+
+            public int getPidsLimit() {
+                return pidsLimit;
+            }
+
+            public void setPidsLimit(int pidsLimit) {
+                this.pidsLimit = pidsLimit;
+            }
+
+            public String getTmpfsSize() {
+                return tmpfsSize;
+            }
+
+            public void setTmpfsSize(String tmpfsSize) {
+                this.tmpfsSize = tmpfsSize;
+            }
+        }
+    }
 }
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringStartupGuard.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringStartupGuard.java
new file mode 100644
index 000000000..47eb0e36a
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/AuthoringStartupGuard.java
@@ -0,0 +1,51 @@
+package com.iflytek.skillhub.config;
+
+import java.util.Arrays;
+import java.util.Set;
+import org.springframework.boot.ApplicationArguments;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.core.env.Environment;
+import org.springframework.stereotype.Component;
+
+/**
+ * Fails application startup when user-authored code would run directly on the
+ * host outside a development profile: with {@code skillhub.authoring.local-script}
+ * enabled in {@code INLINE} execution mode, validation scripts and stdio MCP
+ * commands execute as server subprocesses. Production deployments must use the
+ * {@code DOCKER} execution mode (or disable local-script entirely).
+ */
+@Component
+public class AuthoringStartupGuard implements ApplicationRunner {
+
+    /** Profiles in which host-side execution is a deliberate development choice. */
+    private static final Set<String> NON_PRODUCTION_PROFILES = Set.of("local", "dev", "test");
+
+    private final AuthoringProperties properties;
+    private final Environment environment;
+
+    public AuthoringStartupGuard(AuthoringProperties properties, Environment environment) {
+        this.properties = properties;
+        this.environment = environment;
+    }
+
+    @Override
+    public void run(ApplicationArguments args) {
+        if (!properties.getLocalScript().isEnabled()) {
+            return;
+        }
+        if (properties.getLocalScript().getExecutionMode()
+                != AuthoringProperties.ScriptExecutionMode.INLINE) {
+            return;
+        }
+        boolean nonProduction = Arrays.stream(environment.getActiveProfiles())
+                .anyMatch(NON_PRODUCTION_PROFILES::contains);
+        if (nonProduction) {
+            return;
+        }
+        throw new IllegalStateException("""
+                skillhub.authoring.local-script.execution-mode=inline is not allowed in \
+                production: user-authored scripts and stdio MCP commands would run \
+                directly on the host. Set SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE=docker \
+                (locked-down containers) or disable local-script.""");
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/ConfiguredAuthoringSecurityPolicy.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/ConfiguredAuthoringSecurityPolicy.java
new file mode 100644
index 000000000..02380113e
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/config/ConfiguredAuthoringSecurityPolicy.java
@@ -0,0 +1,142 @@
+package com.iflytek.skillhub.config;
+
+import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
+import java.net.InetAddress;
+import java.net.URI;
+import java.net.UnknownHostException;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Component;
+
+/**
+ * The production {@link AuthoringSecurityPolicy}, derived from
+ * {@code skillhub.authoring.*} configuration.
+ *
+ * <p>SSRF posture: the server only makes outbound requests to public
+ * addresses. Link-local addresses (which include the 169.254.169.254 cloud
+ * metadata service), multicast, and the unspecified address are always
+ * rejected. Loopback, RFC1918, unique-local IPv6, CGNAT, and the RFC 2544
+ * benchmark range (198.18.0.0/15) are rejected unless the surface-specific
+ * {@code allow-private-endpoints} flag is set (used by local development to
+ * reach loopback fake servers).
+ *
+ * <p>Known limitation: the guard resolves the hostname at check time; the
+ * HttpClient re-resolves at connect time, which mitigates (but cannot fully
+ * eliminate) DNS-rebinding races. Binding the socket to the checked address
+ * is not implemented because it would break virtual-hosted MCP endpoints.
+ */
+@Component
+public class ConfiguredAuthoringSecurityPolicy implements AuthoringSecurityPolicy {
+
+    /** Resolves a host to addresses; the default delegates to the JDK resolver. */
+    @FunctionalInterface
+    interface HostResolver {
+        InetAddress[] resolve(String host) throws UnknownHostException;
+    }
+
+    private final AuthoringProperties properties;
+    private final HostResolver resolver;
+
+    @Autowired
+    public ConfiguredAuthoringSecurityPolicy(AuthoringProperties properties) {
+        this(properties, InetAddress::getAllByName);
+    }
+
+    /** Test seam: injects a deterministic resolver so tests need no network. */
+    ConfiguredAuthoringSecurityPolicy(AuthoringProperties properties, HostResolver resolver) {
+        this.properties = properties;
+        this.resolver = resolver;
+    }
+
+    @Override
+    public String endpointRejection(String url, EndpointUse use) {
+        URI uri;
+        try {
+            uri = URI.create(url);
+        } catch (IllegalArgumentException exception) {
+            return "malformed URL: " + url;
+        }
+        String scheme = uri.getScheme();
+        if (!"http".equalsIgnoreCase(scheme) && !"https".equalsIgnoreCase(scheme)) {
+            return "only http(s) endpoints are allowed, got: " + scheme;
+        }
+        String host = uri.getHost();
+        if (host == null || host.isBlank()) {
+            return "URL has no host: " + url;
+        }
+        boolean allowPrivate = use == EndpointUse.MCP_SERVER
+                ? properties.getMcp().isAllowPrivateEndpoints()
+                : properties.getOpenAiCompatible().isAllowPrivateEndpoints();
+
+        InetAddress[] addresses;
+        try {
+            addresses = resolver.resolve(host);
+        } catch (UnknownHostException exception) {
+            return "cannot resolve host '" + host + "'";
+        }
+        for (InetAddress address : addresses) {
+            String reason = classify(address, allowPrivate);
+            if (reason != null) {
+                return reason;
+            }
+        }
+        return null;
+    }
+
+    @Override
+    public boolean stdioTransportAllowed() {
+        return properties.getMcp().isStdioEnabled();
+    }
+
+    @Override
+    public boolean envRefAllowed(String name) {
+        return properties.getMcp().getEnvAllowlist().contains(name);
+    }
+
+    /** @return null when the address is allowed, otherwise the rejection reason. */
+    private static String classify(InetAddress address, boolean allowPrivate) {
+        if (address.isAnyLocalAddress()) {
+            return "unspecified address is not a valid endpoint: " + address.getHostAddress();
+        }
+        if (address.isLinkLocalAddress()) {
+            // 169.254.0.0/16 (incl. the cloud metadata service) and fe80::/10
+            return "link-local address (cloud metadata range) is always blocked: "
+                    + address.getHostAddress();
+        }
+        if (address.isMulticastAddress()) {
+            return "multicast address is not a valid endpoint: " + address.getHostAddress();
+        }
+        boolean privateRange = address.isLoopbackAddress()
+                || address.isSiteLocalAddress()
+                || isUniqueLocalIpv6(address)
+                || isCarrierGradeNat(address)
+                || isBenchmarkRange(address);
+        if (privateRange && !allowPrivate) {
+            return "private/loopback address is blocked unless allow-private-endpoints"
+                    + " is enabled: " + address.getHostAddress();
+        }
+        return null;
+    }
+
+    /** fc00::/7 unique-local addresses are not covered by {@code isSiteLocalAddress}. */
+    private static boolean isUniqueLocalIpv6(InetAddress address) {
+        byte[] bytes = address.getAddress();
+        return bytes.length == 16 && (bytes[0] & 0xFE) == 0xFC;
+    }
+
+    /** 100.64.0.0/10 carrier-grade NAT, a common internal service range. */
+    private static boolean isCarrierGradeNat(InetAddress address) {
+        byte[] bytes = address.getAddress();
+        return bytes.length == 4 && (bytes[0] & 0xFF) == 100
+                && (bytes[1] & 0xFF) >= 64 && (bytes[1] & 0xFF) <= 127;
+    }
+
+    /**
+     * 198.18.0.0/15 RFC 2544 benchmark range: reserved, never a legitimate
+     * endpoint, and used as the synthetic pool by fake-IP VPN/proxy resolvers.
+     */
+    private static boolean isBenchmarkRange(InetAddress address) {
+        byte[] bytes = address.getAddress();
+        return bytes.length == 4 && (bytes[0] & 0xFF) == 198
+                && (bytes[1] & 0xFE) == 18;
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestrator.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestrator.java
index 3789c2774..48f2a9873 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestrator.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestrator.java
@@ -26,6 +26,7 @@
 import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
 import com.iflytek.skillhub.domain.authoring.validation.ValidationRunStatus;
 import com.iflytek.skillhub.domain.shared.exception.DomainConflictException;
+import com.iflytek.skillhub.service.authoring.mcp.McpProbeService;
 import com.iflytek.skillhub.domain.skill.validation.PackageEntry;
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
@@ -54,10 +55,6 @@
  * the runtime binding and probes declared MCP servers; the BEHAVIOR layer executes
  * the spec's tasks through the bound runtime adapter and evaluates assertions.
  *
- * <p>The MCP probe of declared servers and the OpenAI-compatible prompt
- * adapter arrive with the MCP+security layer; this layer executes script
- * tasks through the local-script (inline or docker) adapter.
- *
  * <p>Run lifecycle hardening follows the merged upstream review: one FutureTask per
  * run (duplicate submits are ignored), a hard wall-clock watchdog on the timer,
  * cancellation settles first and then interrupts the worker, and the terminal
@@ -75,6 +72,7 @@ public class ValidationRunOrchestrator {
     private final RuntimeBindingService bindingService;
     private final DraftStructureValidator structureValidator;
     private final RuntimeBindingValidator bindingValidator;
+    private final McpProbeService mcpProbeService;
     private final ValidationSpecParser specParser = new ValidationSpecParser();
     private final AssertionEvaluator assertionEvaluator = new AssertionEvaluator();
     private final List<SkillRuntimeAdapter> adapters;
@@ -90,6 +88,7 @@ public ValidationRunOrchestrator(ValidationRunService runService,
                                      RuntimeBindingService bindingService,
                                      DraftStructureValidator structureValidator,
                                      RuntimeBindingValidator bindingValidator,
+                                     McpProbeService mcpProbeService,
                                      List<SkillRuntimeAdapter> adapters,
                                      ValidationEventBroadcaster broadcaster,
                                      AuthoringProperties properties,
@@ -100,6 +99,7 @@ public ValidationRunOrchestrator(ValidationRunService runService,
         this.bindingService = bindingService;
         this.structureValidator = structureValidator;
         this.bindingValidator = bindingValidator;
+        this.mcpProbeService = mcpProbeService;
         this.adapters = List.copyOf(adapters);
         this.broadcaster = broadcaster;
         this.properties = properties;
@@ -297,6 +297,24 @@ private ValidationSpec runConfigLayer(RunContext context, ValidationRun run,
                         binding.getMcpServers())
                 .forEach(context::recordFinding);
 
+        // declared MCP servers must actually answer before the behavior layer
+        // relies on their tools: connect, initialize, tools/list
+        List<Map<String, Object>> mcpServers = binding.getMcpServers() == null
+                ? List.of() : binding.getMcpServers();
+        if (!mcpServers.isEmpty()) {
+            McpProbeService.ProbeReport probeReport =
+                    mcpProbeService.probe(mcpServers, java.time.Duration.ofSeconds(10));
+            probeReport.findings().forEach(context::recordFinding);
+            for (McpProbeService.ServerProbe serverProbe : probeReport.servers()) {
+                if (serverProbe.connected()) {
+                    emit(context.runId, ValidationEventType.LOG, "CONFIG", Map.of(
+                            "task", "mcp:" + serverProbe.server(), "stream", "summary",
+                            "line", "connected; tools: " + (serverProbe.tools().isEmpty()
+                                    ? "(none)" : String.join(", ", serverProbe.tools()))));
+                }
+            }
+        }
+
         SkillRuntimeAdapter adapter = findAdapter(binding.getAgentType().identifier());
         if (adapter == null) {
             context.recordFinding(FindingDraft.error(ValidationLayer.CONFIG, "ADAPTER_NOT_FOUND",
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/OpenAiCompatibleRuntimeAdapter.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/OpenAiCompatibleRuntimeAdapter.java
new file mode 100644
index 000000000..f0f4124df
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/adapter/OpenAiCompatibleRuntimeAdapter.java
@@ -0,0 +1,345 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeEventSink;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeExecutionContext;
+import com.iflytek.skillhub.domain.authoring.runtime.SkillRuntimeAdapter;
+import com.iflytek.skillhub.domain.authoring.runtime.TaskResult;
+import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
+import com.iflytek.skillhub.domain.authoring.spec.TaskType;
+import com.iflytek.skillhub.domain.authoring.spec.ValidationTaskSpec;
+import com.iflytek.skillhub.service.authoring.mcp.HttpMcpClient;
+import com.iflytek.skillhub.service.authoring.mcp.McpClient;
+import com.iflytek.skillhub.service.authoring.mcp.McpClientFactory;
+import com.iflytek.skillhub.service.authoring.mcp.McpTool;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+import org.springframework.stereotype.Component;
+
+/**
+ * Behavior-layer adapter for prompt tasks: an agentic loop against an
+ * OpenAI-compatible chat-completion endpoint. Tools declared on the binding's MCP
+ * servers are discovered live (initialize + tools/list), filtered by the server's
+ * toolFilters and the binding's toolAllowlist, exposed to the model as function
+ * tools, and executed for real when the model calls them — every chat round and
+ * every tool invocation/reply lands in the run's event trace. The API key is
+ * resolved from server-side configuration only; runtime bindings reference
+ * endpoints and models, never credentials.
+ */
+@Component
+public class OpenAiCompatibleRuntimeAdapter implements SkillRuntimeAdapter {
+
+    private static final String SKILL_MD = "SKILL.md";
+    /** Cap on a single tool output fed back into the model context. */
+    private static final int MAX_TOOL_OUTPUT_CHARS = 8_000;
+    /** Cap on tool discovery (initialize + tools/list) regardless of task timeout. */
+    private static final Duration DISCOVERY_TIMEOUT = Duration.ofSeconds(30);
+
+    private final AuthoringProperties properties;
+    private final ObjectMapper objectMapper;
+    private final McpClientFactory mcpClientFactory;
+    private final AuthoringSecurityPolicy securityPolicy;
+    private final HttpClient httpClient;
+
+    public OpenAiCompatibleRuntimeAdapter(AuthoringProperties properties, ObjectMapper objectMapper,
+                                          McpClientFactory mcpClientFactory,
+                                          AuthoringSecurityPolicy securityPolicy) {
+        this.properties = properties;
+        this.objectMapper = objectMapper;
+        this.mcpClientFactory = mcpClientFactory;
+        this.securityPolicy = securityPolicy;
+        this.httpClient = HttpClient.newBuilder()
+                .connectTimeout(Duration.ofSeconds(15))
+                // never follow redirects: a public endpoint answering 302 towards
+                // a link-local target must not become an SSRF bypass
+                .followRedirects(HttpClient.Redirect.NEVER)
+                .build();
+    }
+
+    @Override
+    public String agentType() {
+        return "openai-compatible";
+    }
+
+    @Override
+    public boolean supports(TaskType taskType) {
+        return taskType == TaskType.PROMPT;
+    }
+
+    @Override
+    public boolean enabled() {
+        return properties.getOpenAiCompatible().isEnabled();
+    }
+
+    /** One tool the model may call, bound to the client that can execute it. */
+    private record ExposedTool(McpClient client, String server, McpTool tool) {
+    }
+
+    @Override
+    public TaskResult execute(RuntimeExecutionContext context, ValidationTaskSpec task,
+                              RuntimeEventSink sink) throws Exception {
+        AuthoringProperties.OpenAiCompatible config = properties.getOpenAiCompatible();
+        String endpoint = firstNonBlank(context.configString("endpoint"), config.getDefaultEndpoint());
+        String model = firstNonBlank(context.configString("model"), config.getDefaultModel());
+        if (endpoint == null || model == null) {
+            throw new IllegalStateException(
+                    "openai-compatible runtime requires endpoint and model (binding config or server defaults)");
+        }
+        // requests carry the server-side API key, so the destination must pass
+        // the SSRF guard before any credential leaves the host
+        String endpointRejection = securityPolicy.endpointRejection(
+                endpoint, AuthoringSecurityPolicy.EndpointUse.LLM_API);
+        if (endpointRejection != null) {
+            throw new IllegalStateException(
+                    "openai-compatible endpoint is not allowed: " + endpointRejection);
+        }
+        String url = endpoint.endsWith("/") ? endpoint + "chat/completions" : endpoint + "/chat/completions";
+        Duration requestTimeout = Duration.ofMillis(Math.max(task.timeoutMs(), 1_000));
+
+        List<McpClient> clients = new ArrayList<>();
+        Map<String, ExposedTool> exposedTools = discoverTools(context, task, sink, clients);
+        try {
+            ArrayNode messages = objectMapper.createArrayNode();
+            messages.addObject().put("role", "system").put("content", readSkillMd(context.workingDirectory()));
+            messages.addObject().put("role", "user").put("content", task.prompt());
+
+            int executedToolCalls = 0;
+            String content = "";
+            int maxRounds = Math.max(config.getMaxToolRounds(), 1);
+            for (int round = 1; round <= maxRounds; round++) {
+                if (context.cancellation().isCancelRequested()) {
+                    throw new IllegalStateException("task '" + task.name() + "' cancelled");
+                }
+
+                ObjectNode requestBody = chatRequest(model, context, messages, exposedTools, round);
+                sink.toolCall(task.name(), "openai-chat", requestBody.get("meta").toString());
+                JsonNode message = postChatCompletion(url, config, requestBody, requestTimeout);
+
+                content = message.path("content").asText("");
+                JsonNode toolCalls = message.path("tool_calls");
+                if (toolCalls.isEmpty() || exposedTools.isEmpty()) {
+                    break; // final answer (or nothing we can execute)
+                }
+
+                // record the assistant turn verbatim, then append one tool reply per call
+                ObjectNode assistantMessage = objectMapper.createObjectNode();
+                assistantMessage.put("role", "assistant");
+                if (!content.isEmpty()) {
+                    assistantMessage.put("content", content);
+                }
+                HttpMcpClient.attachToolCalls(objectMapper, assistantMessage, toolCalls);
+                messages.add(assistantMessage);
+
+                for (JsonNode call : toolCalls) {
+                    String callId = call.path("id").asText("call-" + executedToolCalls);
+                    String functionName = call.path("function").path("name").asText("");
+                    String argumentsJson = call.path("function").path("arguments").asText("{}");
+                    ExposedTool exposed = exposedTools.get(functionName);
+                    if (exposed == null) {
+                        appendToolReply(messages, callId, "error: unknown tool '" + functionName + "'");
+                        sink.toolResult(task.name(), "mcp:" + functionName,
+                                "{\"error\":\"unknown tool\"}");
+                        continue;
+                    }
+                    sink.toolCall(task.name(), "mcp:" + exposed.server() + "/" + exposed.tool().name(),
+                            argumentsJson);
+                    String reply;
+                    try {
+                        Map<String, Object> arguments = parseArguments(argumentsJson);
+                        String output = exposed.client().callTool(
+                                exposed.tool().name(), arguments, requestTimeout);
+                        reply = truncate(output, MAX_TOOL_OUTPUT_CHARS);
+                        executedToolCalls++;
+                        sink.toolResult(task.name(), "mcp:" + exposed.server() + "/" + exposed.tool().name(),
+                                "{\"ok\":true,\"length\":" + output.length() + "}");
+                    } catch (Exception exception) {
+                        reply = "error: tool call failed: " + exception.getMessage();
+                        sink.toolResult(task.name(), "mcp:" + exposed.server() + "/" + exposed.tool().name(),
+                                "{\"error\":" + jsonString(String.valueOf(exception.getMessage())) + "}");
+                    }
+                    appendToolReply(messages, callId, reply);
+                }
+                if (round == maxRounds) {
+                    sink.log(task.name(), "summary",
+                            "round limit (" + maxRounds + ") reached while the model still requests tools");
+                }
+            }
+
+            sink.agentMessage(task.name(), truncate(content, 4_000));
+            return TaskResult.ofPrompt(content, executedToolCalls,
+                    new WorkingDirectoryArtifacts(context.workingDirectory()));
+        } finally {
+            clients.forEach(McpClient::close);
+        }
+    }
+
+    // ---------------------------------------------------------------- tool discovery
+
+    /**
+     * Connects to every declared MCP server, lists its tools, and keeps the ones
+     * allowed by the server's toolFilters and the binding's global toolAllowlist
+     * (empty allowlist = unrestricted; entries match the bare tool name or
+     * "server.tool"). Keys of the returned map are the function names exposed to
+     * the model. Every client created along the way is appended to {@code clients}
+     * so the caller can close them all — even servers whose tools were entirely
+     * filtered out.
+     */
+    private Map<String, ExposedTool> discoverTools(RuntimeExecutionContext context,
+                                                   ValidationTaskSpec task, RuntimeEventSink sink,
+                                                   List<McpClient> clients) {
+        Map<String, ExposedTool> exposed = new LinkedHashMap<>();
+        List<String> allowlist = context.safeToolAllowlist();
+        for (Map<String, Object> server : context.safeMcpServers()) {
+            String serverName = String.valueOf(server.get("name"));
+            Set<String> toolFilters = server.get("toolFilters") instanceof List<?> filters
+                    ? filters.stream().map(String::valueOf).collect(Collectors.toSet())
+                    : Set.of();
+            List<McpTool> tools;
+            McpClient client;
+            try {
+                client = mcpClientFactory.create(server);
+                clients.add(client);
+                tools = client.listTools(DISCOVERY_TIMEOUT);
+            } catch (Exception exception) {
+                // the config-layer probe already reported unreachable servers; skip quietly
+                sink.log(task.name(), "mcp", "server '" + serverName + "' unavailable during task: "
+                        + exception.getMessage());
+                continue;
+            }
+            for (McpTool tool : tools) {
+                if (!toolFilters.isEmpty() && !toolFilters.contains(tool.name())) {
+                    continue;
+                }
+                if (!allowlist.isEmpty() && !allowlist.contains(tool.name())
+                        && !allowlist.contains(serverName + "." + tool.name())) {
+                    continue;
+                }
+                exposed.put(exposedName(exposed.keySet(), serverName, tool.name()),
+                        new ExposedTool(client, serverName, tool));
+            }
+        }
+        return exposed;
+    }
+
+    /** Function names must match ^[a-zA-Z0-9_-]{1,64}$; MCP names may contain dots. */
+    private String exposedName(Set<String> taken, String serverName, String toolName) {
+        String candidate = (serverName + "__" + toolName).replaceAll("[^a-zA-Z0-9_-]", "_");
+        if (candidate.length() > 64) {
+            candidate = candidate.substring(0, 64);
+        }
+        String unique = candidate;
+        int suffix = 2;
+        while (taken.contains(unique)) {
+            String tail = "_" + suffix++;
+            unique = candidate.substring(0, 64 - tail.length()) + tail;
+        }
+        return unique;
+    }
+
+    // ---------------------------------------------------------------- chat protocol
+
+    private ObjectNode chatRequest(String model, RuntimeExecutionContext context, ArrayNode messages,
+                                   Map<String, ExposedTool> exposedTools, int round) {
+        ObjectNode body = objectMapper.createObjectNode();
+        body.put("model", model);
+        body.put("stream", false);
+        Object temperature = context.safeAdapterConfig().get("temperature");
+        if (temperature instanceof Number number) {
+            body.put("temperature", number.doubleValue());
+        }
+        body.set("messages", messages);
+        if (!exposedTools.isEmpty()) {
+            ArrayNode tools = body.putArray("tools");
+            exposedTools.forEach((exposedName, tool) -> tools.add(
+                    HttpMcpClient.toFunctionSchema(objectMapper, tool.tool(), exposedName)));
+        }
+        // trace metadata; removed before the body reaches the endpoint
+        ObjectNode meta = objectMapper.createObjectNode();
+        meta.put("model", model);
+        meta.put("round", round);
+        meta.put("messages", messages.size());
+        meta.put("tools", exposedTools.size());
+        body.set("meta", meta);
+        return body;
+    }
+
+    /** Posts one chat-completion request and returns the first choice's message. */
+    private JsonNode postChatCompletion(String url, AuthoringProperties.OpenAiCompatible config,
+                                        ObjectNode requestBody, Duration timeout) throws Exception {
+        requestBody.remove("meta"); // trace-only field must not reach the endpoint
+        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
+                .uri(URI.create(url))
+                .timeout(timeout)
+                .header("Content-Type", "application/json")
+                .POST(HttpRequest.BodyPublishers.ofString(requestBody.toString(), StandardCharsets.UTF_8));
+        if (config.getApiKey() != null && !config.getApiKey().isBlank()) {
+            requestBuilder.header("Authorization", "Bearer " + config.getApiKey());
+        }
+        HttpResponse<InputStream> response =
+                httpClient.send(requestBuilder.build(), HttpResponse.BodyHandlers.ofInputStream());
+        String body = HttpMcpClient.readBodyCapped(response.body(), HttpMcpClient.MAX_RESPONSE_BYTES);
+        if (response.statusCode() < 200 || response.statusCode() >= 300) {
+            throw new IOException("chat completion failed with HTTP " + response.statusCode()
+                    + ": " + truncate(body, 500));
+        }
+        return objectMapper.readTree(body).path("choices").path(0).path("message");
+    }
+
+    private void appendToolReply(ArrayNode messages, String toolCallId, String content) {
+        messages.add(HttpMcpClient.toolResponseMessage(objectMapper, toolCallId, content));
+    }
+
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> parseArguments(String argumentsJson) {
+        try {
+            return objectMapper.readValue(argumentsJson, Map.class);
+        } catch (Exception exception) {
+            return new HashMap<>();
+        }
+    }
+
+    private String jsonString(String value) {
+        return objectMapper.valueToTree(value == null ? "" : value).toString();
+    }
+
+    private String readSkillMd(Path workingDirectory) throws IOException {
+        Path skillMd = workingDirectory.resolve(SKILL_MD);
+        if (Files.isRegularFile(skillMd)) {
+            return Files.readString(skillMd, StandardCharsets.UTF_8);
+        }
+        return "No SKILL.md is present in this draft.";
+    }
+
+    private static String firstNonBlank(String primary, String fallback) {
+        if (primary != null && !primary.isBlank()) {
+            return primary;
+        }
+        return fallback == null || fallback.isBlank() ? null : fallback;
+    }
+
+    private static String truncate(String value, int limit) {
+        if (value == null) {
+            return "";
+        }
+        return value.length() <= limit ? value : value.substring(0, limit) + "…";
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/HttpMcpClient.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/HttpMcpClient.java
new file mode 100644
index 000000000..47c4ec5ff
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/HttpMcpClient.java
@@ -0,0 +1,264 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * MCP client for the streamable-HTTP transport (also used for legacy SSE
+ * endpoints that accept plain JSON-RPC POSTs). Each request is one JSON-RPC
+ * POST; responses may arrive as a bare JSON object or as a text/event-stream
+ * body whose data lines carry the JSON-RPC message. Response bodies are
+ * size-capped so a hostile endpoint cannot exhaust server memory.
+ */
+public class HttpMcpClient implements McpClient {
+
+    public static final String PROTOCOL_VERSION = "2024-11-05";
+    public static final String CLIENT_NAME = "skillhub-authoring";
+    /** One HTTP response body may not exceed this many bytes. */
+    public static final int MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+
+    private final String serverName;
+    private final String endpoint;
+    private final HttpClient httpClient;
+    private final ObjectMapper objectMapper;
+    private final Map<String, String> extraHeaders;
+    private int nextId = 1;
+    private String sessionId;
+
+    public HttpMcpClient(String serverName, String endpoint, HttpClient httpClient,
+                         ObjectMapper objectMapper, Map<String, String> extraHeaders) {
+        this.serverName = serverName;
+        this.endpoint = endpoint;
+        this.httpClient = httpClient;
+        this.objectMapper = objectMapper;
+        this.extraHeaders = Map.copyOf(extraHeaders);
+    }
+
+    @Override
+    public String serverName() {
+        return serverName;
+    }
+
+    @Override
+    public List<McpTool> listTools(Duration timeout) throws Exception {
+        ObjectNode params = objectMapper.createObjectNode();
+        params.put("protocolVersion", PROTOCOL_VERSION);
+        params.set("capabilities", objectMapper.createObjectNode());
+        ObjectNode clientInfo = params.putObject("clientInfo");
+        clientInfo.put("name", CLIENT_NAME);
+        clientInfo.put("version", "1.0");
+        // the server may assign a session id here; request() captures it for later calls
+        request("initialize", params, timeout);
+        // notify the server the handshake is complete; the response is irrelevant
+        notification("notifications/initialized", timeout);
+
+        JsonNode tools = request("tools/list", objectMapper.createObjectNode(), timeout);
+        List<McpTool> discovered = new ArrayList<>();
+        for (JsonNode tool : tools.path("tools")) {
+            discovered.add(new McpTool(
+                    tool.path("name").asText(""),
+                    tool.path("description").asText(""),
+                    tool.path("inputSchema")));
+        }
+        return discovered;
+    }
+
+    @Override
+    public String callTool(String toolName, Map<String, Object> arguments, Duration timeout)
+            throws Exception {
+        ObjectNode params = objectMapper.createObjectNode();
+        params.put("name", toolName);
+        params.set("arguments", objectMapper.valueToTree(arguments == null ? Map.of() : arguments));
+        JsonNode result = request("tools/call", params, timeout);
+        if (result.path("isError").asBoolean(false)) {
+            throw new IOException("MCP tool '" + toolName + "' returned an error result on server '"
+                    + serverName + "'");
+        }
+        StringBuilder content = new StringBuilder();
+        for (JsonNode part : result.path("content")) {
+            if ("text".equals(part.path("type").asText())) {
+                if (content.length() > 0) {
+                    content.append('\n');
+                }
+                content.append(part.path("text").asText(""));
+            }
+        }
+        return content.toString();
+    }
+
+    @Override
+    public void close() {
+        // HTTP transport is stateless from this client's point of view
+    }
+
+    private JsonNode request(String method, ObjectNode params, Duration timeout) throws Exception {
+        ObjectNode request = objectMapper.createObjectNode();
+        request.put("jsonrpc", "2.0");
+        request.put("id", nextId++);
+        request.put("method", method);
+        request.set("params", params);
+
+        HttpRequest.Builder builder = HttpRequest.newBuilder()
+                .uri(URI.create(endpoint))
+                .timeout(timeout)
+                .header("Content-Type", "application/json")
+                .header("Accept", "application/json, text/event-stream")
+                .POST(HttpRequest.BodyPublishers.ofString(request.toString(), StandardCharsets.UTF_8));
+        extraHeaders.forEach(builder::header);
+        if (sessionId != null) {
+            builder.header("Mcp-Session-Id", sessionId);
+        }
+
+        HttpResponse<InputStream> response;
+        try {
+            response = httpClient.send(builder.build(), HttpResponse.BodyHandlers.ofInputStream());
+        } catch (IOException exception) {
+            throw new IOException("MCP server '" + serverName + "' request failed ("
+                    + method + "): " + exception, exception);
+        }
+        String body = readBodyCapped(response.body(), MAX_RESPONSE_BYTES);
+        if (response.statusCode() < 200 || response.statusCode() >= 300) {
+            throw new IOException("MCP server '" + serverName + "' returned HTTP "
+                    + response.statusCode() + " for " + method + ": " + truncate(body, 200));
+        }
+        String sessionHeader = response.headers().firstValue("Mcp-Session-Id").orElse(null);
+        if (sessionHeader != null) {
+            sessionId = sessionHeader;
+        }
+        JsonNode message = parseMessage(body, request.path("id").asInt());
+        if (message.has("error")) {
+            throw new IOException("MCP server '" + serverName + "' error on " + method + ": "
+                    + message.path("error").path("message").asText());
+        }
+        return message.path("result");
+    }
+
+    private void notification(String method, Duration timeout) {
+        try {
+            ObjectNode notification = objectMapper.createObjectNode();
+            notification.put("jsonrpc", "2.0");
+            notification.put("method", method);
+            HttpRequest.Builder builder = HttpRequest.newBuilder()
+                    .uri(URI.create(endpoint))
+                    .timeout(timeout)
+                    .header("Content-Type", "application/json")
+                    .header("Accept", "application/json, text/event-stream")
+                    .POST(HttpRequest.BodyPublishers.ofString(notification.toString(),
+                            StandardCharsets.UTF_8));
+            extraHeaders.forEach(builder::header);
+            if (sessionId != null) {
+                builder.header("Mcp-Session-Id", sessionId);
+            }
+            httpClient.send(builder.build(), HttpResponse.BodyHandlers.discarding());
+        } catch (Exception ignored) {
+            // notifications are best-effort; servers that reject them still work
+        }
+    }
+
+    /** Accepts either a bare JSON-RPC response or an SSE body with data lines. */
+    private JsonNode parseMessage(String body, int requestId) throws IOException {
+        if (body == null || body.isBlank()) {
+            throw new IOException("MCP server '" + serverName + "' returned an empty body");
+        }
+        String text = body.trim();
+        if (text.startsWith("{")) {
+            return objectMapper.readTree(text);
+        }
+        for (String line : body.split("\n")) {
+            String trimmed = line.trim();
+            if (!trimmed.startsWith("data:")) {
+                continue;
+            }
+            String payload = trimmed.substring("data:".length()).trim();
+            if (payload.isEmpty()) {
+                continue;
+            }
+            JsonNode node = objectMapper.readTree(payload);
+            if (node.path("id").asInt(-1) == requestId) {
+                return node;
+            }
+        }
+        throw new IOException("MCP server '" + serverName
+                + "' response did not contain a result for request " + requestId);
+    }
+
+    /** Helper for tests and callers that need the OpenAI-style tool schema. */
+    public static ObjectNode toFunctionSchema(ObjectMapper objectMapper, McpTool tool) {
+        return toFunctionSchema(objectMapper, tool, tool.name());
+    }
+
+    /** Same, under the function name the caller exposes to the model. */
+    public static ObjectNode toFunctionSchema(ObjectMapper objectMapper, McpTool tool,
+                                              String functionName) {
+        ObjectNode function = objectMapper.createObjectNode();
+        function.put("name", functionName);
+        function.put("description", tool.description() == null ? "" : tool.description());
+        function.set("parameters", tool.inputSchema() == null || tool.inputSchema().isNull()
+                ? objectMapper.createObjectNode()
+                : tool.inputSchema());
+        ObjectNode wrapper = objectMapper.createObjectNode();
+        wrapper.put("type", "function");
+        wrapper.set("function", function);
+        return wrapper;
+    }
+
+    /** Helper: builds the messages-array tool role entry for chat completions. */
+    public static ObjectNode toolResponseMessage(ObjectMapper objectMapper, String toolCallId,
+                                                 String content) {
+        ObjectNode message = objectMapper.createObjectNode();
+        message.put("role", "tool");
+        message.put("tool_call_id", toolCallId);
+        message.put("content", content);
+        return message;
+    }
+
+    /** Helper: attaches tool call requests to an assistant message. */
+    public static void attachToolCalls(ObjectMapper objectMapper, ObjectNode assistantMessage,
+                                       JsonNode toolCalls) {
+        ArrayNode calls = assistantMessage.putArray("tool_calls");
+        for (JsonNode call : toolCalls) {
+            calls.add(call.deepCopy());
+        }
+    }
+
+    /**
+     * Reads a response body fully into a UTF-8 string, refusing bodies beyond
+     * {@code maxBytes}: a hostile endpoint must not be able to buffer an
+     * unbounded response in server memory.
+     */
+    public static String readBodyCapped(InputStream body, int maxBytes) throws IOException {
+        try (body) {
+            ByteArrayOutputStream buffer = new ByteArrayOutputStream();
+            byte[] chunk = new byte[8192];
+            int read;
+            while ((read = body.read(chunk)) != -1) {
+                if (buffer.size() + read > maxBytes) {
+                    throw new IOException("response body exceeds " + maxBytes + " bytes");
+                }
+                buffer.write(chunk, 0, read);
+            }
+            return buffer.toString(StandardCharsets.UTF_8);
+        }
+    }
+
+    private static String truncate(String value, int limit) {
+        if (value == null) {
+            return "";
+        }
+        return value.length() <= limit ? value : value.substring(0, limit) + "…";
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpClient.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpClient.java
new file mode 100644
index 000000000..870c2f2fc
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpClient.java
@@ -0,0 +1,29 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A live connection to one MCP server declared in a runtime binding. Implementations
+ * speak the MCP JSON-RPC protocol (initialize, tools/list, tools/call) over their
+ * transport and are closed after use.
+ */
+public interface McpClient extends AutoCloseable {
+
+    /** Display name from the binding declaration, used in events and findings. */
+    String serverName();
+
+    /** Performs the initialize handshake and a tools/list; returns the offered tools. */
+    List<McpTool> listTools(Duration timeout) throws Exception;
+
+    /**
+     * Executes one tool call and returns its text content. Implementations must
+     * surface MCP-level errors (isError or JSON-RPC error) as exceptions.
+     */
+    String callTool(String toolName, Map<String, Object> arguments, Duration timeout)
+            throws Exception;
+
+    @Override
+    void close();
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpClientFactory.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpClientFactory.java
new file mode 100644
index 000000000..36a080aeb
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpClientFactory.java
@@ -0,0 +1,159 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
+import java.io.IOException;
+import java.net.http.HttpClient;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import org.springframework.stereotype.Component;
+
+/**
+ * Builds {@link McpClient} instances from the runtime binding's MCP server
+ * declarations. Transport "http"/"sse" yield an HTTP JSON-RPC client; "stdio"
+ * spawns the declared command with only the envRefs-named variables from the
+ * server process environment (the only way credentials reach an MCP server).
+ *
+ * <p>Every declaration is re-checked here against the
+ * {@link AuthoringSecurityPolicy} even though the binding validator already
+ * rejected unsafe saves: this is the connect-time enforcement point that also
+ * covers bindings persisted by older deployments. In docker execution mode,
+ * stdio servers run inside the same locked-down container profile as
+ * validation scripts — no network, resource caps, read-only rootfs — and the
+ * container is force-removed when the client closes.
+ */
+@Component
+public class McpClientFactory {
+
+    private final ObjectMapper objectMapper;
+    private final AuthoringProperties properties;
+    private final AuthoringSecurityPolicy securityPolicy;
+    private final HttpClient httpClient;
+
+    public McpClientFactory(ObjectMapper objectMapper, AuthoringProperties properties,
+                            AuthoringSecurityPolicy securityPolicy) {
+        this.objectMapper = objectMapper;
+        this.properties = properties;
+        this.securityPolicy = securityPolicy;
+        this.httpClient = HttpClient.newBuilder()
+                .connectTimeout(Duration.ofSeconds(10))
+                // redirects must never be followed: a public URL answering 302
+                // towards a link-local target is the classic SSRF bypass
+                .followRedirects(HttpClient.Redirect.NEVER)
+                .build();
+    }
+
+    /** @param server declaration map: name, transport, endpoint|command, toolFilters, envRefs */
+    public McpClient create(Map<String, Object> server) throws IOException {
+        String name = String.valueOf(server.get("name"));
+        String transport = String.valueOf(server.get("transport"));
+        if ("http".equals(transport) || "sse".equals(transport)) {
+            String endpoint = String.valueOf(server.get("endpoint"));
+            String rejection = securityPolicy.endpointRejection(
+                    endpoint, AuthoringSecurityPolicy.EndpointUse.MCP_SERVER);
+            if (rejection != null) {
+                throw new IOException("MCP server '" + name + "' endpoint rejected: " + rejection);
+            }
+            return new HttpMcpClient(name, endpoint, httpClient, objectMapper, Map.of());
+        }
+        if ("stdio".equals(transport)) {
+            if (!securityPolicy.stdioTransportAllowed()) {
+                throw new IOException("MCP server '" + name
+                        + "': stdio transport is disabled (skillhub.authoring.mcp.stdio-enabled)");
+            }
+            List<String> command = commandOf(server);
+            Map<String, String> environment = environmentOf(server);
+            if (properties.getLocalScript().getExecutionMode()
+                    == AuthoringProperties.ScriptExecutionMode.DOCKER) {
+                String container = containerName(name);
+                return new StdioMcpClient(name, dockerWrappedCommand(container, command, environment),
+                        Map.of(), objectMapper, List.of("docker", "rm", "-f", container), true);
+            }
+            return new StdioMcpClient(name, command, environment, objectMapper);
+        }
+        throw new IllegalArgumentException(
+                "MCP server '" + name + "' has unsupported transport: " + transport);
+    }
+
+    /**
+     * The docker argv that isolates a stdio MCP server: throwaway container,
+     * no network, resource caps, read-only rootfs, all capabilities dropped.
+     * Environment variables travel as explicit {@code -e} flags so the docker
+     * CLI can keep its own environment (needed to reach the daemon).
+     */
+    List<String> dockerWrappedCommand(String container, List<String> command,
+                                      Map<String, String> environment) {
+        AuthoringProperties.Mcp.Docker docker = properties.getMcp().getDocker();
+        List<String> wrapped = new ArrayList<>();
+        wrapped.add("docker");
+        wrapped.add("run");
+        wrapped.add("--rm");
+        wrapped.add("--name");
+        wrapped.add(container);
+        wrapped.add("--network");
+        wrapped.add("none");
+        wrapped.add("--memory");
+        wrapped.add(docker.getMemory());
+        wrapped.add("--cpus");
+        wrapped.add(docker.getCpus());
+        wrapped.add("--pids-limit");
+        wrapped.add(String.valueOf(docker.getPidsLimit()));
+        wrapped.add("--read-only");
+        wrapped.add("--tmpfs");
+        wrapped.add("/tmp:rw,size=" + docker.getTmpfsSize());
+        wrapped.add("--cap-drop");
+        wrapped.add("ALL");
+        wrapped.add("--security-opt");
+        wrapped.add("no-new-privileges");
+        wrapped.add("--log-driver");
+        wrapped.add("none");
+        for (Map.Entry<String, String> entry : environment.entrySet()) {
+            wrapped.add("-e");
+            wrapped.add(entry.getKey() + "=" + entry.getValue());
+        }
+        wrapped.add(docker.getImage());
+        wrapped.addAll(command);
+        return List.copyOf(wrapped);
+    }
+
+    /** Container names allow [a-zA-Z0-9][a-zA-Z0-9_.-]+ and must be unique per client. */
+    static String containerName(String serverName) {
+        String sanitized = serverName == null ? "unknown" : serverName.replaceAll("[^a-zA-Z0-9_.-]", "-");
+        if (sanitized.isEmpty() || !Character.isLetterOrDigit(sanitized.charAt(0))) {
+            sanitized = "m" + sanitized;
+        }
+        return "skillhub-mcp-" + sanitized + "-" + UUID.randomUUID().toString().substring(0, 8);
+    }
+
+    /** Splits the command on whitespace; no shell is involved. */
+    private static List<String> commandOf(Map<String, Object> server) {
+        String command = String.valueOf(server.get("command"));
+        return List.of(command.trim().split("\\s+"));
+    }
+
+    /**
+     * Only envRefs-named variables from the server environment are passed
+     * through, and only when the security policy allowlists them.
+     */
+    Map<String, String> environmentOf(Map<String, Object> server) {
+        Map<String, String> environment = new HashMap<>();
+        if (server.get("envRefs") instanceof List<?> refs) {
+            for (Object ref : refs) {
+                String name = String.valueOf(ref);
+                if (!securityPolicy.envRefAllowed(name)) {
+                    continue;
+                }
+                String value = System.getenv(name);
+                if (value != null) {
+                    environment.put(name, value);
+                }
+            }
+        }
+        return environment;
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpProbeService.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpProbeService.java
new file mode 100644
index 000000000..b3c902d39
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpProbeService.java
@@ -0,0 +1,92 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.iflytek.skillhub.domain.authoring.validation.FindingDraft;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationLayer;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+import org.springframework.stereotype.Component;
+
+/**
+ * CONFIG-layer liveness probe for declared MCP servers: connects, completes the
+ * initialize handshake, lists tools, and reports unreachable servers and
+ * toolFilters that reference tools the server does not expose. This is what turns
+ * an MCP declaration from "syntactically valid" into "verified working before
+ * the behavior layer relies on it".
+ */
+@Component
+public class McpProbeService {
+
+    private static final Set<String> KNOWN_TRANSPORTS = Set.of("http", "sse", "stdio");
+
+    private final McpClientFactory clientFactory;
+
+    public McpProbeService(McpClientFactory clientFactory) {
+        this.clientFactory = clientFactory;
+    }
+
+    /** One server's probe outcome: either the discovered tool names or the failure. */
+    public record ServerProbe(String server, boolean connected, List<String> tools, String error) {
+        static ServerProbe connected(String server, List<String> tools) {
+            return new ServerProbe(server, true, List.copyOf(tools), null);
+        }
+
+        static ServerProbe failed(String server, String error) {
+            return new ServerProbe(server, false, List.of(), error);
+        }
+    }
+
+    /** All probes plus the findings the orchestrator should record. */
+    public record ProbeReport(List<ServerProbe> servers, List<FindingDraft> findings) {
+    }
+
+    public ProbeReport probe(List<Map<String, Object>> mcpServers, java.time.Duration timeout) {
+        List<ServerProbe> probes = new ArrayList<>();
+        List<FindingDraft> findings = new ArrayList<>();
+        for (Map<String, Object> server : mcpServers) {
+            Object name = server.get("name");
+            Object transport = server.get("transport");
+            if (name == null || transport == null || !KNOWN_TRANSPORTS.contains(transport.toString())) {
+                continue; // already reported by RuntimeBindingValidator
+            }
+            probes.add(probeOne(server, name.toString(), timeout, findings));
+        }
+        return new ProbeReport(List.copyOf(probes), List.copyOf(findings));
+    }
+
+    private ServerProbe probeOne(Map<String, Object> server, String name,
+                                 java.time.Duration timeout, List<FindingDraft> findings) {
+        try (McpClient client = clientFactory.create(server)) {
+            List<McpTool> tools = client.listTools(timeout);
+            List<String> toolNames = tools.stream().map(McpTool::name).toList();
+            checkToolFilters(server, name, toolNames, findings);
+            return ServerProbe.connected(name, toolNames);
+        } catch (Exception exception) {
+            String message = String.valueOf(exception.getMessage());
+            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_CONNECT_FAILED",
+                    "MCP server '" + name + "' cannot be reached: "
+                            + (message.length() > 300 ? message.substring(0, 300) + "…" : message)));
+            return ServerProbe.failed(name, message);
+        }
+    }
+
+    private void checkToolFilters(Map<String, Object> server, String name, List<String> toolNames,
+                                  List<FindingDraft> findings) {
+        if (!(server.get("toolFilters") instanceof List<?> filters) || filters.isEmpty()) {
+            return;
+        }
+        Set<String> discovered = Set.copyOf(toolNames);
+        List<String> unknown = filters.stream()
+                .map(String::valueOf)
+                .filter(filter -> !discovered.contains(filter))
+                .collect(Collectors.toList());
+        if (!unknown.isEmpty()) {
+            findings.add(FindingDraft.warning(ValidationLayer.CONFIG, "MCP_TOOL_FILTER_UNKNOWN",
+                    "runtime binding", "MCP server '" + name + "' toolFilters reference unknown "
+                    + "tool(s): " + String.join(", ", unknown) + "; discovered tools: "
+                    + (toolNames.isEmpty() ? "(none)" : String.join(", ", toolNames))));
+        }
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpTool.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpTool.java
new file mode 100644
index 000000000..ad6f546eb
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/McpTool.java
@@ -0,0 +1,14 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+/**
+ * One tool discovered from an MCP server via {@code tools/list}.
+ */
+public record McpTool(String name, String description, JsonNode inputSchema) {
+
+    @Override
+    public String toString() {
+        return name;
+    }
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/StdioMcpClient.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/StdioMcpClient.java
new file mode 100644
index 000000000..bb9ef8cbb
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/service/authoring/mcp/StdioMcpClient.java
@@ -0,0 +1,236 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import java.io.BufferedReader;
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.io.OutputStreamWriter;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * MCP client for the stdio transport: the declared command is spawned as a
+ * subprocess and JSON-RPC messages are exchanged as newline-delimited JSON on
+ * its stdin/stdout. Only environment variables named in {@code envRefs} are
+ * passed through; the process is destroyed on close. A single stdout line is
+ * capped so a hostile server cannot exhaust memory with an unterminated line.
+ */
+public class StdioMcpClient implements McpClient {
+
+    /** One JSON-RPC message may not exceed this many characters. */
+    private static final int MAX_LINE_CHARS = 2 * 1024 * 1024;
+    private static final long TEARDOWN_TIMEOUT_MS = 5_000;
+
+    private final String serverName;
+    private final Process process;
+    private final BufferedWriter stdin;
+    private final BufferedReader stdout;
+    private final ObjectMapper objectMapper;
+    private final List<String> teardownCommand;
+    private int nextId = 1;
+
+    public StdioMcpClient(String serverName, List<String> command, Map<String, String> environment,
+                          ObjectMapper objectMapper) throws IOException {
+        this(serverName, command, environment, objectMapper, null, false);
+    }
+
+    /**
+     * @param teardownCommand best-effort cleanup executed after the process is
+     *                        destroyed (e.g. {@code docker rm -f <container>});
+     *                        may be null
+     * @param inheritEnvironment when true the parent environment is kept — only
+     *                        legitimate for docker-wrapped commands, where the
+     *                        docker CLI needs it to reach the daemon and the
+     *                        container only receives its explicit {@code -e} vars
+     */
+    public StdioMcpClient(String serverName, List<String> command, Map<String, String> environment,
+                          ObjectMapper objectMapper, List<String> teardownCommand,
+                          boolean inheritEnvironment) throws IOException {
+        this.serverName = serverName;
+        this.objectMapper = objectMapper;
+        this.teardownCommand = teardownCommand;
+        ProcessBuilder processBuilder = new ProcessBuilder(command);
+        if (!inheritEnvironment) {
+            processBuilder.environment().clear();
+            processBuilder.environment().putAll(environment);
+        }
+        processBuilder.redirectErrorStream(false);
+        this.process = processBuilder.start();
+        this.stdin = new BufferedWriter(
+                new OutputStreamWriter(process.getOutputStream(), StandardCharsets.UTF_8));
+        this.stdout = new BufferedReader(
+                new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8));
+    }
+
+    @Override
+    public String serverName() {
+        return serverName;
+    }
+
+    @Override
+    public List<McpTool> listTools(Duration timeout) throws Exception {
+        ObjectNode params = objectMapper.createObjectNode();
+        params.put("protocolVersion", HttpMcpClient.PROTOCOL_VERSION);
+        params.set("capabilities", objectMapper.createObjectNode());
+        ObjectNode clientInfo = params.putObject("clientInfo");
+        clientInfo.put("name", HttpMcpClient.CLIENT_NAME);
+        clientInfo.put("version", "1.0");
+        request("initialize", params, timeout);
+        notification("notifications/initialized");
+
+        JsonNode tools = request("tools/list", objectMapper.createObjectNode(), timeout);
+        List<McpTool> discovered = new ArrayList<>();
+        for (JsonNode tool : tools.path("tools")) {
+            discovered.add(new McpTool(
+                    tool.path("name").asText(""),
+                    tool.path("description").asText(""),
+                    tool.path("inputSchema")));
+        }
+        return discovered;
+    }
+
+    @Override
+    public String callTool(String toolName, Map<String, Object> arguments, Duration timeout)
+            throws Exception {
+        ObjectNode params = objectMapper.createObjectNode();
+        params.put("name", toolName);
+        params.set("arguments", objectMapper.valueToTree(arguments == null ? Map.of() : arguments));
+        JsonNode result = request("tools/call", params, timeout);
+        if (result.path("isError").asBoolean(false)) {
+            throw new IOException("MCP tool '" + toolName + "' returned an error result on server '"
+                    + serverName + "'");
+        }
+        StringBuilder content = new StringBuilder();
+        for (JsonNode part : result.path("content")) {
+            if ("text".equals(part.path("type").asText())) {
+                if (content.length() > 0) {
+                    content.append('\n');
+                }
+                content.append(part.path("text").asText(""));
+            }
+        }
+        return content.toString();
+    }
+
+    @Override
+    public void close() {
+        process.destroy();
+        try {
+            if (!process.waitFor(3, TimeUnit.SECONDS)) {
+                process.destroyForcibly();
+            }
+        } catch (InterruptedException ignored) {
+            process.destroyForcibly();
+            Thread.currentThread().interrupt();
+        }
+        runTeardown();
+    }
+
+    /**
+     * Best-effort cleanup after the process is gone: a SIGKILLed
+     * {@code docker run} client can leave its container behind, so the
+     * docker-wrapped mode removes the container by name.
+     */
+    private void runTeardown() {
+        if (teardownCommand == null) {
+            return;
+        }
+        try {
+            Process cleanup = new ProcessBuilder(teardownCommand).start();
+            if (!cleanup.waitFor(TEARDOWN_TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
+                cleanup.destroyForcibly();
+            }
+        } catch (IOException | InterruptedException exception) {
+            // cleanup is best-effort; the container also exits via --rm
+        }
+    }
+
+    private JsonNode request(String method, ObjectNode params, Duration timeout) throws Exception {
+        ObjectNode request = objectMapper.createObjectNode();
+        request.put("jsonrpc", "2.0");
+        request.put("id", nextId++);
+        request.put("method", method);
+        request.set("params", params);
+        stdin.write(request.toString());
+        stdin.write('\n');
+        stdin.flush();
+        return readResponse(request.path("id").asInt(), timeout);
+    }
+
+    private void notification(String method) throws IOException {
+        ObjectNode notification = objectMapper.createObjectNode();
+        notification.put("jsonrpc", "2.0");
+        notification.put("method", method);
+        stdin.write(notification.toString());
+        stdin.write('\n');
+        stdin.flush();
+    }
+
+    /** Reads stdout lines until the response with the matching id arrives. */
+    private JsonNode readResponse(int requestId, Duration timeout) throws IOException {
+        // readLine() blocks, so a silently hanging server needs a watchdog: kill the
+        // process after the timeout and readLine unblocks with end-of-stream.
+        Thread watchdog = Thread.ofVirtual().start(() -> {
+            try {
+                Thread.sleep(timeout.toMillis());
+                process.destroyForcibly();
+            } catch (InterruptedException ignored) {
+                // the response arrived in time
+            }
+        });
+        try {
+            long deadline = System.nanoTime() + timeout.toNanos();
+            while (System.nanoTime() < deadline) {
+                String line = readLineCapped();
+                if (line == null) {
+                    throw new IOException("MCP server '" + serverName + "' (stdio) closed its output");
+                }
+                String trimmed = line.trim();
+                if (!trimmed.startsWith("{")) {
+                    continue;
+                }
+                JsonNode node = objectMapper.readTree(trimmed);
+                if (node.path("id").asInt(-1) != requestId) {
+                    continue; // notification or log output from the server
+                }
+                if (node.has("error")) {
+                    throw new IOException("MCP server '" + serverName + "' error: "
+                            + node.path("error").path("message").asText());
+                }
+                return node.path("result");
+            }
+            throw new IOException("MCP server '" + serverName + "' (stdio) timed out after " + timeout);
+        } finally {
+            watchdog.interrupt();
+        }
+    }
+
+    /**
+     * Reads one line like {@link BufferedReader#readLine()} but refuses lines
+     * beyond {@link #MAX_LINE_CHARS}: a hostile stdio server could otherwise
+     * buffer an unterminated line of unbounded length in memory.
+     */
+    private String readLineCapped() throws IOException {
+        StringBuilder line = new StringBuilder();
+        int character;
+        while ((character = stdout.read()) != -1) {
+            if (character == '\n' || character == '\r') {
+                return line.toString();
+            }
+            line.append((char) character);
+            if (line.length() > MAX_LINE_CHARS) {
+                process.destroyForcibly();
+                throw new IOException("MCP server '" + serverName
+                        + "' (stdio) sent a line longer than " + MAX_LINE_CHARS + " chars");
+            }
+        }
+        return line.length() == 0 ? null : line.toString();
+    }
+}
diff --git a/server/skillhub-app/src/main/resources/application.yml b/server/skillhub-app/src/main/resources/application.yml
index ed4aec70e..a1204c16c 100644
--- a/server/skillhub-app/src/main/resources/application.yml
+++ b/server/skillhub-app/src/main/resources/application.yml
@@ -159,6 +159,34 @@ skillhub:
         cpus: ${SKILLHUB_AUTHORING_DOCKER_CPUS:1.0}
         pids-limit: ${SKILLHUB_AUTHORING_DOCKER_PIDS_LIMIT:128}
         tmpfs-size: ${SKILLHUB_AUTHORING_DOCKER_TMPFS_SIZE:64m}
+    openai-compatible:
+      # Disabled by default: point it at an OpenAI-compatible endpoint to enable prompt tasks
+      enabled: ${SKILLHUB_AUTHORING_LLM_ENABLED:false}
+      api-key: ${SKILLHUB_AUTHORING_LLM_API_KEY:}
+      default-endpoint: ${SKILLHUB_AUTHORING_LLM_ENDPOINT:}
+      default-model: ${SKILLHUB_AUTHORING_LLM_MODEL:}
+      timeout-ms: ${SKILLHUB_AUTHORING_LLM_TIMEOUT_MS:120000}
+      # rounds of chat-completion (with MCP tool execution between rounds) per prompt task
+      max-tool-rounds: ${SKILLHUB_AUTHORING_LLM_MAX_TOOL_ROUNDS:4}
+      # SSRF guard: set true only for private-network LLM endpoints (e.g. internal vLLM);
+      # loopback/RFC1918 destinations are rejected by default, link-local always
+      allow-private-endpoints: ${SKILLHUB_AUTHORING_LLM_ALLOW_PRIVATE:false}
+    mcp:
+      # SSRF guard for http/sse MCP endpoints: private/loopback addresses are
+      # rejected by default; link-local (cloud metadata) is always rejected
+      allow-private-endpoints: ${SKILLHUB_AUTHORING_MCP_ALLOW_PRIVATE:false}
+      # stdio MCP servers spawn server-side processes — off unless explicitly enabled
+      stdio-enabled: ${SKILLHUB_AUTHORING_MCP_STDIO_ENABLED:false}
+      # server environment variables a binding may reference via envRefs
+      # (comma-separated, e.g. MCP_ECHO_TOKEN,WEATHER_API_KEY)
+      env-allowlist: ${SKILLHUB_AUTHORING_MCP_ENV_ALLOWLIST:}
+      docker:
+        # isolation profile for stdio MCP servers in docker execution mode
+        image: ${SKILLHUB_AUTHORING_MCP_DOCKER_IMAGE:alpine:3.20}
+        memory: ${SKILLHUB_AUTHORING_MCP_DOCKER_MEMORY:256m}
+        cpus: ${SKILLHUB_AUTHORING_MCP_DOCKER_CPUS:1.0}
+        pids-limit: ${SKILLHUB_AUTHORING_MCP_DOCKER_PIDS_LIMIT:128}
+        tmpfs-size: ${SKILLHUB_AUTHORING_MCP_DOCKER_TMPFS_SIZE:64m}
   github-sync:
     discovery-scheduler-interval-ms: ${SKILLHUB_GITHUB_SYNC_DISCOVERY_SCHEDULER_INTERVAL_MS:60000}
     candidate-scheduler-interval-ms: ${SKILLHUB_GITHUB_SYNC_CANDIDATE_SCHEDULER_INTERVAL_MS:60000}
@@ -178,6 +206,7 @@ skillhub:
     lease-duration: ${SKILLHUB_GITHUB_SYNC_LEASE_DURATION:PT5M}
     repository-check-interval: ${SKILLHUB_GITHUB_SYNC_REPOSITORY_CHECK_INTERVAL:PT24H}
 
+
   suite:
     # Fail closed for deployment modes whose upgrade topology is unknown. Single-instance
     # distributions explicitly enable this after ruling out mixed application versions.
diff --git a/server/skillhub-app/src/main/resources/messages.properties b/server/skillhub-app/src/main/resources/messages.properties
index 260d1a345..78f02d6bb 100644
--- a/server/skillhub-app/src/main/resources/messages.properties
+++ b/server/skillhub-app/src/main/resources/messages.properties
@@ -392,6 +392,8 @@ error.githubSync.deepDiscovery.exclusionInvalid=Exclusions must be valid GitHub
 error.githubSync.deepDiscovery.configurationConflict=Official discovery configuration has changed. Reload the latest configuration before saving
 
 error.githubSync.deepDiscovery.queryInvalid=Invalid deep discovery query parameters.
+# authoring runtime, MCP and security policies
+
 # authoring runtime bindings
 error.authoring.binding.notFound=No runtime binding configured for draft {0}
 error.authoring.binding.agentType.unknown=Unknown agent runtime type: {0}
diff --git a/server/skillhub-app/src/main/resources/messages_ru.properties b/server/skillhub-app/src/main/resources/messages_ru.properties
index c587af936..5e9b8fa14 100644
--- a/server/skillhub-app/src/main/resources/messages_ru.properties
+++ b/server/skillhub-app/src/main/resources/messages_ru.properties
@@ -335,6 +335,8 @@ error.githubSync.deepDiscovery.exclusionInvalid=Исключения должн
 error.githubSync.deepDiscovery.configurationConflict=Конфигурация официального поиска изменена. Загрузите актуальную конфигурацию перед сохранением
 
 error.githubSync.deepDiscovery.queryInvalid=Недопустимые параметры запроса глубокого обнаружения.
+# authoring runtime, MCP and security policies
+
 # authoring runtime bindings
 error.authoring.binding.notFound=Для черновика {0} не настроена привязка среды выполнения
 error.authoring.binding.agentType.unknown=Неизвестный тип среды выполнения агента: {0}
diff --git a/server/skillhub-app/src/main/resources/messages_zh.properties b/server/skillhub-app/src/main/resources/messages_zh.properties
index 7ee2465e8..00b07d183 100644
--- a/server/skillhub-app/src/main/resources/messages_zh.properties
+++ b/server/skillhub-app/src/main/resources/messages_zh.properties
@@ -394,6 +394,8 @@ error.githubSync.deepDiscovery.exclusionInvalid=排除项须为有效的GitHub
 error.githubSync.deepDiscovery.configurationConflict=官方探索配置已被修改，请重新读取最新配置后再保存
 
 error.githubSync.deepDiscovery.queryInvalid=深度探索查询参数无效。
+# authoring runtime, MCP and security policies
+
 # authoring runtime bindings
 error.authoring.binding.notFound=草稿 {0} 尚未配置运行时绑定
 error.authoring.binding.agentType.unknown=未知的 Agent 运行时类型：{0}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringRuntimeFlowIntegrationTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringRuntimeFlowIntegrationTest.java
new file mode 100644
index 000000000..30f47c46c
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringRuntimeFlowIntegrationTest.java
@@ -0,0 +1,225 @@
+package com.iflytek.skillhub.authoring;
+
+import com.iflytek.skillhub.TestRedisConfig;
+import com.iflytek.skillhub.domain.authoring.SkillDraft;
+import com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService;
+import com.iflytek.skillhub.domain.authoring.service.SkillDraftService;
+import com.iflytek.skillhub.domain.authoring.service.ValidationRunService;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRunStatus;
+import com.iflytek.skillhub.domain.namespace.Namespace;
+import com.iflytek.skillhub.domain.namespace.NamespaceMember;
+import com.iflytek.skillhub.domain.namespace.NamespaceMemberRepository;
+import com.iflytek.skillhub.domain.namespace.NamespaceRepository;
+import com.iflytek.skillhub.domain.namespace.NamespaceRole;
+import com.iflytek.skillhub.domain.user.UserAccount;
+import com.iflytek.skillhub.domain.user.UserAccountRepository;
+import com.iflytek.skillhub.service.authoring.ValidationRunOrchestrator;
+import com.iflytek.skillhub.storage.ObjectStorageService;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Import;
+import org.springframework.context.annotation.Primary;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * Runtime-binding layer of the authoring platform: three-layer validation with
+ * a local-script binding (structure + config + behavior, script subprocess
+ * executed inline under the test profile) and the save-time security policy
+ * for bindings (cloud-metadata endpoints, envRefs allowlist, LLM surface).
+ */
+@SpringBootTest
+@ActiveProfiles("test")
+@Import({TestRedisConfig.class, AuthoringRuntimeFlowIntegrationTest.InMemoryStorageConfig.class})
+@Testcontainers
+class AuthoringRuntimeFlowIntegrationTest {
+
+    @Container
+    private static final PostgreSQLContainer<?> POSTGRES =
+            new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @DynamicPropertySource
+    static void configurePostgres(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", POSTGRES::getJdbcUrl);
+        registry.add("spring.datasource.username", POSTGRES::getUsername);
+        registry.add("spring.datasource.password", POSTGRES::getPassword);
+        registry.add("spring.datasource.driver-class-name", () -> "org.postgresql.Driver");
+        registry.add("spring.jpa.database-platform", () -> "org.hibernate.dialect.PostgreSQLDialect");
+        registry.add("spring.flyway.enabled", () -> true);
+        registry.add("spring.jpa.hibernate.ddl-auto", () -> "validate");
+    }
+
+    private static final String USER = "author-user-2";
+    private static final String NS_SLUG = "authoring-test-ns";
+
+    @Autowired private SkillDraftService draftService;
+    @Autowired private RuntimeBindingService bindingService;
+    @Autowired private ValidationRunService runService;
+    @Autowired private ValidationRunOrchestrator orchestrator;
+    @Autowired private NamespaceRepository namespaceRepository;
+    @Autowired private NamespaceMemberRepository namespaceMemberRepository;
+    @Autowired private UserAccountRepository userAccountRepository;
+
+    @TestConfiguration
+    static class InMemoryStorageConfig {
+
+        @Bean
+        @Primary
+        ObjectStorageService inMemoryObjectStorage() {
+            return new AuthoringDraftFlowIntegrationTest.InMemoryObjectStorage();
+        }
+    }
+
+    @BeforeEach
+    void setUpNamespace() {
+        if (userAccountRepository.findById(USER).isEmpty()) {
+            userAccountRepository.save(new UserAccount(USER, "Author User", "author@example.com", null));
+        }
+        if (namespaceRepository.findBySlug(NS_SLUG).isEmpty()) {
+            Namespace namespace = new Namespace(NS_SLUG, "Authoring Test", USER);
+            namespace.setStatus(com.iflytek.skillhub.domain.namespace.NamespaceStatus.ACTIVE);
+            Namespace saved = namespaceRepository.save(namespace);
+            if (namespaceMemberRepository.findByNamespaceIdAndUserId(saved.getId(), USER).isEmpty()) {
+                namespaceMemberRepository.save(new NamespaceMember(saved.getId(), USER, NamespaceRole.MEMBER));
+            }
+        }
+    }
+
+    @Test
+    void threeLayerValidationExecutesScriptTasks() {
+        SkillDraft draft = draftService.createDraft(NS_SLUG, USER, "runtime-flow",
+                "summarizes documents", null);
+        draftService.saveFile(draft.getId(), USER, "SKILL.md", validSkillMd().getBytes(StandardCharsets.UTF_8),
+                "text/markdown", null, null);
+        draftService.saveFile(draft.getId(), USER, "scripts/check.sh",
+                "echo 'smoke OK'\n".getBytes(StandardCharsets.UTF_8), null, null, null);
+        draftService.saveFile(draft.getId(), USER, "validation.yaml",
+                validationYaml().getBytes(StandardCharsets.UTF_8), null, null, null);
+
+        // ---- bind the local-script runtime
+        bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null, null, null);
+
+        // ---- validate: all three layers run, the script task executes inline
+        ValidationRun run = runService.startRun(draft.getId(), USER, null);
+        orchestrator.submit(run.getId());
+        ValidationRun finished = awaitTerminal(run.getId());
+
+        assertThat(finished.getStatus()).isEqualTo(ValidationRunStatus.SUCCEEDED);
+        assertThat(finished.getErrorCount()).isZero();
+        assertThat(runService.listFindings(run.getId())).isEmpty();
+        assertThat(runService.listEvents(run.getId(), null))
+                .extracting(event -> event.getEventType().name())
+                .contains("RUN_STARTED", "TOOL_CALL", "LOG", "RUN_FINISHED");
+        assertThat(runService.listEvents(run.getId(), null).stream()
+                .map(event -> event.getPayload() == null ? "" : event.getPayload().toString())
+                .filter(payload -> payload.contains("smoke OK"))
+                .count()).isPositive();
+
+        SkillDraft validated = draftService.getDraft(draft.getId());
+        assertThat(validated.isCurrentRevisionValidated()).isTrue();
+    }
+
+    @Test
+    void securityPolicyRejectsUnsafeBindingsAtSaveTime() {
+        SkillDraft draft = draftService.createDraft(NS_SLUG, USER, "security-flow",
+                "exercises the binding security policy", null);
+        draftService.saveFile(draft.getId(), USER, "SKILL.md", validSkillMd().getBytes(StandardCharsets.UTF_8),
+                "text/markdown", null, null);
+
+        // cloud metadata endpoints are always blocked — even under the test
+        // profile where loopback/RFC1918 endpoints are deliberately allowed
+        assertBindingRejected(() -> bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null,
+                List.of(Map.of("name", "metadata", "transport", "http",
+                        "endpoint", "http://169.254.169.254/latest/meta-data/")), null),
+                "link-local");
+
+        // envRefs outside the configured allowlist are rejected: bindings must
+        // not be able to read arbitrary server environment variables
+        assertBindingRejected(() -> bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null,
+                List.of(Map.of("name", "env-hog", "transport", "http",
+                        "endpoint", "http://127.0.0.1:9/mcp",
+                        "envRefs", List.of("HOME"))), null),
+                "env-allowlist");
+
+        // the LLM surface is guarded too — those requests carry the server API key
+        assertBindingRejected(() -> bindingService.saveBinding(draft.getId(), USER, "openai-compatible",
+                Map.of("endpoint", "http://169.254.169.254/v1", "model", "test-model"), null, null, null),
+                "link-local");
+
+        // the allowlisted env ref saves fine (loopback is allowed under the test profile)
+        bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null,
+                List.of(Map.of("name", "env-ok", "transport", "http",
+                        "endpoint", "http://127.0.0.1:9/mcp",
+                        "envRefs", List.of("TEST_ALLOWED_MCP_VAR"))), null);
+    }
+
+    private String validSkillMd() {
+        return "---\nname: runtime-flow\ndescription: summarizes documents\n---\n\n# runtime-flow\n";
+    }
+
+    private String validationYaml() {
+        return """
+                version: 1
+                tasks:
+                  - name: smoke
+                    description: script prints the greeting
+                    type: script
+                    script: scripts/check.sh
+                    args: []
+                    timeoutMs: 10000
+                    assertions:
+                      - type: exit_code
+                        equals: 0
+                      - type: stdout_contains
+                        value: smoke OK
+                """;
+    }
+
+    private static void assertBindingRejected(Runnable save, String reasonFragment) {
+        try {
+            save.run();
+            fail("binding save should have been rejected: " + reasonFragment);
+        } catch (com.iflytek.skillhub.domain.shared.exception.DomainBadRequestException exception) {
+            assertThat(String.valueOf(exception.messageArgs()[0])).contains(reasonFragment);
+        }
+    }
+
+    private ValidationRun awaitTerminal(Long runId) {
+        long deadline = System.currentTimeMillis() + 60_000;
+        while (System.currentTimeMillis() < deadline) {
+            if (runService.getRun(runId).getStatus().isTerminal()) {
+                return runService.getRun(runId);
+            }
+            try {
+                Thread.sleep(200);
+            } catch (InterruptedException exception) {
+                Thread.currentThread().interrupt();
+                fail("interrupted while waiting for the validation run to finish");
+            }
+        }
+        fail("validation run did not reach a terminal state in time");
+        return null;
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfigTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfigTest.java
index ef22c930f..b7c5ee4c9 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfigTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringEnvironmentConfigTest.java
@@ -20,12 +20,26 @@ class AuthoringEnvironmentConfigTest {
     @EnableConfigurationProperties(AuthoringProperties.class)
     static class PropertiesConfiguration { }
 
+    /** Supplies the security-policy side of the validator; not under test here. */
+    @Configuration(proxyBeanMethods = false)
+    static class PermissiveSecurityPolicyConfiguration {
+        @org.springframework.context.annotation.Bean
+        com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy authoringSecurityPolicy() {
+            return new com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy() {
+                @Override public String endpointRejection(String url, EndpointUse use) { return null; }
+                @Override public boolean stdioTransportAllowed() { return true; }
+                @Override public boolean envRefAllowed(String name) { return true; }
+            };
+        }
+    }
+
     @Test void springContainerInjectsTheSharedPolicyIntoBothEntryPoints() {
         try (var context = new AnnotationConfigApplicationContext()) {
             context.getEnvironment().getPropertySources().addFirst(new MapPropertySource("dummy-deployment", Map.of(
                     "skillhub.authoring.local-script.environment-allowlist", "AUTHORING_DEMO")));
             context.register(PropertiesConfiguration.class, AuthoringEnvironmentConfig.class,
-                    RuntimeBindingValidator.class, LocalScriptRuntimeAdapter.class, InlineScriptCommandBuilder.class);
+                    RuntimeBindingValidator.class, LocalScriptRuntimeAdapter.class, InlineScriptCommandBuilder.class,
+                    PermissiveSecurityPolicyConfiguration.class);
             context.refresh();
             var validator = context.getBean(RuntimeBindingValidator.class);
             assertThat(context.getBean(LocalScriptRuntimeAdapter.class).agentType()).isEqualTo("local-script");
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringStartupGuardTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringStartupGuardTest.java
new file mode 100644
index 000000000..09dfd282c
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/AuthoringStartupGuardTest.java
@@ -0,0 +1,70 @@
+package com.iflytek.skillhub.config;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.env.MockEnvironment;
+
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * The startup guard makes host-side script execution impossible to configure
+ * by accident in production: inline mode outside local/dev/test fails fast.
+ */
+class AuthoringStartupGuardTest {
+
+    private final AuthoringProperties properties = new AuthoringProperties();
+
+    private AuthoringStartupGuard guard(MockEnvironment environment) {
+        return new AuthoringStartupGuard(properties, environment);
+    }
+
+    @Test
+    void inlineModeWithoutDevProfileFailsStartup() {
+        properties.getLocalScript().setExecutionMode(
+                AuthoringProperties.ScriptExecutionMode.INLINE);
+        assertThatThrownBy(() -> guard(new MockEnvironment()).run(null))
+                .isInstanceOf(IllegalStateException.class)
+                .hasMessageContaining("execution-mode=inline")
+                .hasMessageContaining("docker");
+    }
+
+    @Test
+    void inlineModeWithProdLikeProfileStillFails() {
+        properties.getLocalScript().setExecutionMode(
+                AuthoringProperties.ScriptExecutionMode.INLINE);
+        MockEnvironment environment = new MockEnvironment();
+        environment.setActiveProfiles("redis-sentinel");
+        assertThatThrownBy(() -> guard(environment).run(null))
+                .isInstanceOf(IllegalStateException.class);
+    }
+
+    @Test
+    void inlineModeIsAllowedInLocalDevAndTestProfiles() {
+        properties.getLocalScript().setExecutionMode(
+                AuthoringProperties.ScriptExecutionMode.INLINE);
+        for (String profile : new String[]{"local", "dev", "test"}) {
+            MockEnvironment environment = new MockEnvironment();
+            environment.setActiveProfiles(profile);
+            assertThatCode(() -> guard(environment).run(null))
+                    .as("profile " + profile)
+                    .doesNotThrowAnyException();
+        }
+    }
+
+    @Test
+    void dockerModePassesEverywhere() {
+        properties.getLocalScript().setExecutionMode(
+                AuthoringProperties.ScriptExecutionMode.DOCKER);
+        assertThatCode(() -> guard(new MockEnvironment()).run(null))
+                .doesNotThrowAnyException();
+    }
+
+    @Test
+    void disabledLocalScriptPassesEverywhere() {
+        properties.getLocalScript().setEnabled(false);
+        properties.getLocalScript().setExecutionMode(
+                AuthoringProperties.ScriptExecutionMode.INLINE);
+        assertThatCode(() -> guard(new MockEnvironment()).run(null))
+                .doesNotThrowAnyException();
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/ConfiguredAuthoringSecurityPolicyTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/ConfiguredAuthoringSecurityPolicyTest.java
new file mode 100644
index 000000000..089a792ce
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/config/ConfiguredAuthoringSecurityPolicyTest.java
@@ -0,0 +1,151 @@
+package com.iflytek.skillhub.config;
+
+import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Pins the SSRF classification of user-supplied endpoints: link-local (cloud
+ * metadata) is always blocked, private/loopback ranges follow the per-surface
+ * flags, and public addresses pass.
+ */
+class ConfiguredAuthoringSecurityPolicyTest {
+
+    private final AuthoringProperties properties = new AuthoringProperties();
+    private final ConfiguredAuthoringSecurityPolicy policy =
+            new ConfiguredAuthoringSecurityPolicy(properties);
+
+    @Test
+    void publicHttpAndHttpsEndpointsAreAllowed() {
+        // literal public IPs keep the test hermetic: hostname resolution varies
+        // with the local network (VPNs and DNS64 may answer with private ranges)
+        assertThat(policy.endpointRejection("https://1.1.1.1/v1",
+                AuthoringSecurityPolicy.EndpointUse.LLM_API)).isNull();
+        assertThat(policy.endpointRejection("http://8.8.8.8/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNull();
+    }
+
+    @Test
+    void nonHttpSchemesAndHostlessUrlsAreRejected() {
+        assertThat(policy.endpointRejection("file:///etc/passwd",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).contains("http(s)");
+        assertThat(policy.endpointRejection("ftp://example.com/x",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).contains("http(s)");
+        assertThat(policy.endpointRejection("http://",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        assertThat(policy.endpointRejection("http:///no-host-here",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).contains("no host");
+        assertThat(policy.endpointRejection("not a url at all",
+                AuthoringSecurityPolicy.EndpointUse.LLM_API)).isNotNull();
+    }
+
+    @Test
+    void cloudMetadataAndLinkLocalAreAlwaysBlockedEvenWhenPrivateIsAllowed() {
+        properties.getMcp().setAllowPrivateEndpoints(true);
+        properties.getOpenAiCompatible().setAllowPrivateEndpoints(true);
+        assertThat(policy.endpointRejection("http://169.254.169.254/latest/meta-data/",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).contains("link-local");
+        assertThat(policy.endpointRejection("http://169.254.0.1/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).contains("link-local");
+        assertThat(policy.endpointRejection("http://[fe80::1]/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        // the LLM surface carries the server API key — same absolute block
+        assertThat(policy.endpointRejection("http://169.254.169.254/v1",
+                AuthoringSecurityPolicy.EndpointUse.LLM_API)).contains("link-local");
+    }
+
+    @Test
+    void unspecifiedAndMulticastAreAlwaysBlocked() {
+        assertThat(policy.endpointRejection("http://0.0.0.0/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        assertThat(policy.endpointRejection("http://224.0.0.1/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+    }
+
+    @Test
+    void loopbackIsBlockedByDefaultAndAllowedWithTheFlag() {
+        assertThat(policy.endpointRejection("http://127.0.0.1:8080/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).contains("private/loopback");
+        assertThat(policy.endpointRejection("http://localhost:8080/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        assertThat(policy.endpointRejection("http://[::1]/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+
+        properties.getMcp().setAllowPrivateEndpoints(true);
+        assertThat(policy.endpointRejection("http://127.0.0.1:8080/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNull();
+        // the LLM surface has its own flag and stays blocked
+        assertThat(policy.endpointRejection("http://127.0.0.1:8080/v1",
+                AuthoringSecurityPolicy.EndpointUse.LLM_API)).isNotNull();
+        properties.getOpenAiCompatible().setAllowPrivateEndpoints(true);
+        assertThat(policy.endpointRejection("http://127.0.0.1:8080/v1",
+                AuthoringSecurityPolicy.EndpointUse.LLM_API)).isNull();
+    }
+
+    @Test
+    void privateV4V6AndCgnatRangesAreBlockedByDefault() {
+        assertThat(policy.endpointRejection("http://10.1.2.3/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        assertThat(policy.endpointRejection("http://172.16.0.9/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        assertThat(policy.endpointRejection("http://192.168.1.1/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        // 172.32.x.x is public (just outside the RFC1918 block)
+        assertThat(policy.endpointRejection("http://172.32.0.1/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNull();
+        assertThat(policy.endpointRejection("http://100.64.0.1/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        // 100.128.x.x is public (just outside CGNAT)
+        assertThat(policy.endpointRejection("http://100.128.0.1/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNull();
+        assertThat(policy.endpointRejection("http://[fd12::1]/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+    }
+
+    @Test
+    void unresolvableOrSyntheticHostsNeverPassSilently() throws Exception {
+        // Resolution is stubbed through the test seam: whether a bogus host
+        // fails to resolve (normal network) or a fake-IP VPN answers it with
+        // a synthetic range, the endpoint must not pass silently.
+        ConfiguredAuthoringSecurityPolicy unresolved = new ConfiguredAuthoringSecurityPolicy(
+                properties, host -> { throw new java.net.UnknownHostException("nx"); });
+        assertThat(unresolved.endpointRejection("http://this-host-does-not-exist.invalid/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER))
+                .contains("cannot resolve host");
+
+        // fake-IP VPN resolvers answer everything inside 198.18.0.0/15
+        java.net.InetAddress fakeVpnAnswer = java.net.InetAddress.getByAddress(
+                new byte[] {(byte) 198, 18, 1, (byte) 200});
+        ConfiguredAuthoringSecurityPolicy fakeDns = new ConfiguredAuthoringSecurityPolicy(
+                properties, host -> new java.net.InetAddress[] {fakeVpnAnswer});
+        assertThat(fakeDns.endpointRejection("http://anything.example/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+    }
+
+    @Test
+    void rfc2544BenchmarkRangeFollowsThePrivateFlag() {
+        assertThat(policy.endpointRejection("http://198.18.1.200/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        assertThat(policy.endpointRejection("http://198.19.255.1/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNotNull();
+        // 198.20.x.x is public (just outside the /15)
+        assertThat(policy.endpointRejection("http://198.20.0.1/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNull();
+        properties.getMcp().setAllowPrivateEndpoints(true);
+        assertThat(policy.endpointRejection("http://198.18.1.200/mcp",
+                AuthoringSecurityPolicy.EndpointUse.MCP_SERVER)).isNull();
+    }
+
+    @Test
+    void stdioAndEnvRefsFollowConfiguration() {
+        assertThat(policy.stdioTransportAllowed()).isFalse();
+        properties.getMcp().setStdioEnabled(true);
+        assertThat(policy.stdioTransportAllowed()).isTrue();
+
+        assertThat(policy.envRefAllowed("ANY_VAR")).isFalse();
+        properties.getMcp().setEnvAllowlist(java.util.List.of("WEATHER_API_KEY"));
+        assertThat(policy.envRefAllowed("WEATHER_API_KEY")).isTrue();
+        assertThat(policy.envRefAllowed("PATH")).isFalse();
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/TestingAuthoringSecurityPolicy.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/TestingAuthoringSecurityPolicy.java
new file mode 100644
index 000000000..506680c45
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/TestingAuthoringSecurityPolicy.java
@@ -0,0 +1,53 @@
+package com.iflytek.skillhub.service.authoring;
+
+import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
+
+/**
+ * Ready-made policies for unit tests that build components by hand instead of
+ * through the Spring context.
+ */
+public final class TestingAuthoringSecurityPolicy {
+
+    private TestingAuthoringSecurityPolicy() {
+    }
+
+    /** Allows every endpoint, stdio, and env ref — for tests focused elsewhere. */
+    public static AuthoringSecurityPolicy permissive() {
+        return new AuthoringSecurityPolicy() {
+            @Override
+            public String endpointRejection(String url, EndpointUse use) {
+                return null;
+            }
+
+            @Override
+            public boolean stdioTransportAllowed() {
+                return true;
+            }
+
+            @Override
+            public boolean envRefAllowed(String name) {
+                return true;
+            }
+        };
+    }
+
+    /** Production posture: rejects every endpoint, stdio, and env ref. */
+    public static AuthoringSecurityPolicy denyAll() {
+        return new AuthoringSecurityPolicy() {
+            @Override
+            public String endpointRejection(String url, EndpointUse use) {
+                return "blocked by test policy";
+            }
+
+            @Override
+            public boolean stdioTransportAllowed() {
+                return false;
+            }
+
+            @Override
+            public boolean envRefAllowed(String name) {
+                return false;
+            }
+        };
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestratorTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestratorTest.java
index ef4aff67d..031ff954d 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestratorTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/ValidationRunOrchestratorTest.java
@@ -34,6 +34,8 @@ class ValidationRunOrchestratorTest {
             mock(com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService.class);
     private final com.iflytek.skillhub.domain.authoring.service.RuntimeBindingValidator bindingValidator =
             mock(com.iflytek.skillhub.domain.authoring.service.RuntimeBindingValidator.class);
+    private final com.iflytek.skillhub.service.authoring.mcp.McpProbeService mcpProbeService =
+            mock(com.iflytek.skillhub.service.authoring.mcp.McpProbeService.class);
 
     @Test
     void duplicateClaimCannotEmitAnActiveRunAsFinished() {
@@ -140,6 +142,6 @@ private ValidationRunOrchestrator orchestrator(java.util.concurrent.Executor exe
         AuthoringProperties properties = new AuthoringProperties();
         properties.setRunTimeoutMs(timeout);
         return new ValidationRunOrchestrator(runs, drafts, bindings, validator, bindingValidator,
-                java.util.List.of(), broadcaster, properties, executor, timer);
+                mcpProbeService, java.util.List.of(), broadcaster, properties, executor, timer);
     }
 }
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/OpenAiCompatibleRuntimeAdapterToolLoopTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/OpenAiCompatibleRuntimeAdapterToolLoopTest.java
new file mode 100644
index 000000000..f5d73f0e9
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/adapter/OpenAiCompatibleRuntimeAdapterToolLoopTest.java
@@ -0,0 +1,281 @@
+package com.iflytek.skillhub.service.authoring.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeEventSink;
+import com.iflytek.skillhub.domain.authoring.runtime.RuntimeExecutionContext;
+import com.iflytek.skillhub.domain.authoring.runtime.TaskResult;
+import com.iflytek.skillhub.domain.authoring.spec.TaskType;
+import com.iflytek.skillhub.domain.authoring.spec.ValidationTaskSpec;
+import com.iflytek.skillhub.service.authoring.TestingAuthoringSecurityPolicy;
+import com.iflytek.skillhub.service.authoring.mcp.McpClientFactory;
+import com.iflytek.skillhub.service.authoring.mcp.TestingMcpHttpServer;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CopyOnWriteArrayList;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Drives the full prompt-task agent loop against a fake OpenAI-compatible
+ * endpoint and a fake MCP server: tools are discovered over MCP, exposed to the
+ * model, executed for real when called, and every step lands in the trace sink.
+ * Also pins the toolFilters / toolAllowlist restrictions on what gets exposed.
+ */
+class OpenAiCompatibleRuntimeAdapterToolLoopTest {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    @TempDir
+    Path workspace;
+
+    private TestingMcpHttpServer mcpServer;
+    private FakeOpenAiEndpoint openAi;
+    private final List<TraceEvent> trace = new ArrayList<>();
+    private OpenAiCompatibleRuntimeAdapter adapter;
+    private AuthoringProperties properties;
+
+    private record TraceEvent(String kind, String tool, String payload) {
+    }
+
+    /** Records toolCall/toolResult/agentMessage/log in order. */
+    private final RuntimeEventSink sink = new RuntimeEventSink() {
+        @Override
+        public void agentMessage(String taskName, String content) {
+            trace.add(new TraceEvent("agentMessage", null, content));
+        }
+
+        @Override
+        public void toolCall(String taskName, String tool, String argumentsJson) {
+            trace.add(new TraceEvent("toolCall", tool, argumentsJson));
+        }
+
+        @Override
+        public void toolResult(String taskName, String tool, String summaryJson) {
+            trace.add(new TraceEvent("toolResult", tool, summaryJson));
+        }
+
+        @Override
+        public void log(String taskName, String stream, String line) {
+            trace.add(new TraceEvent("log", stream, line));
+        }
+    };
+
+    @BeforeEach
+    void start() throws Exception {
+        mcpServer = new TestingMcpHttpServer(List.of("get_forecast", "lookup_city"));
+        openAi = new FakeOpenAiEndpoint();
+        properties = new AuthoringProperties();
+        properties.getOpenAiCompatible().setEnabled(true);
+        adapter = new OpenAiCompatibleRuntimeAdapter(properties, MAPPER,
+                new McpClientFactory(MAPPER, properties, TestingAuthoringSecurityPolicy.permissive()),
+                TestingAuthoringSecurityPolicy.permissive());
+        Files.writeString(workspace.resolve("SKILL.md"), "---\nname: test\n---\nUse the weather tools.\n");
+        trace.clear();
+    }
+
+    @AfterEach
+    void stop() {
+        if (mcpServer != null) {
+            mcpServer.close();
+        }
+        if (openAi != null) {
+            openAi.close();
+        }
+    }
+
+    private Map<String, Object> weatherServer() {
+        return Map.of("name", "weather", "transport", "http", "endpoint", mcpServer.endpoint());
+    }
+
+    private TaskResult run(List<Map<String, Object>> mcpServers, List<String> allowlist) throws Exception {
+        ValidationTaskSpec task = new ValidationTaskSpec("ask", "asks the weather",
+                TaskType.PROMPT, null, List.of(), "What is the weather in Paris?", 30_000, List.of());
+        RuntimeExecutionContext context = new RuntimeExecutionContext(99L, workspace,
+                Map.of("endpoint", openAi.baseUrl() + "/", "model", "test-model"),
+                allowlist, mcpServers, () -> false);
+        return adapter.execute(context, task, sink);
+    }
+
+    private static ObjectNode assistantMessage(String content) {
+        ObjectNode message = MAPPER.createObjectNode();
+        message.put("role", "assistant");
+        message.put("content", content);
+        return message;
+    }
+
+    private static ObjectNode toolCallMessage(String functionName, String arguments) {
+        ObjectNode message = MAPPER.createObjectNode();
+        message.put("role", "assistant");
+        message.put("content", "");
+        ObjectNode call = message.putArray("tool_calls").addObject();
+        call.put("id", "call-1");
+        call.put("type", "function");
+        call.putObject("function").put("name", functionName).put("arguments", arguments);
+        return message;
+    }
+
+    @Test
+    void executesMcpToolAndTracesEveryStep() throws Exception {
+        openAi.script(List.of(
+                toolCallMessage("weather__get_forecast", "{\"city\":\"Paris\"}"),
+                assistantMessage("The forecast for Paris is sunny.")));
+
+        TaskResult result = run(List.of(weatherServer()), List.of());
+
+        assertThat(result.response()).isEqualTo("The forecast for Paris is sunny.");
+        assertThat(result.toolCallCount()).isEqualTo(1);
+
+        // the real MCP server saw the call with the model's arguments
+        assertThat(mcpServer.toolCalls).hasSize(1);
+        assertThat(mcpServer.toolCalls.get(0).getKey()).isEqualTo("get_forecast");
+        assertThat(mcpServer.toolCalls.get(0).getValue().path("city").asText()).isEqualTo("Paris");
+
+        // two chat rounds; the second carries the tool reply back to the model
+        assertThat(openAi.requests).hasSize(2);
+        assertThat(exposedFunctionNames(0)).containsExactlyInAnyOrder(
+                "weather__get_forecast", "weather__lookup_city");
+        JsonNode secondMessages = openAi.requests.get(1).path("messages");
+        assertThat(secondMessages).anySatisfy(message -> {
+            assertThat(message.path("role").asText()).isEqualTo("tool");
+            assertThat(message.path("tool_call_id").asText()).isEqualTo("call-1");
+            assertThat(message.path("content").asText()).contains("result of get_forecast");
+        });
+
+        // the trace shows both chat rounds, the tool invocation, and the result
+        assertThat(trace).extracting(TraceEvent::kind)
+                .containsExactly("toolCall", "toolCall", "toolResult", "toolCall", "agentMessage");
+        assertThat(trace.get(1).tool()).isEqualTo("mcp:weather/get_forecast");
+        assertThat(trace.get(1).payload()).contains("Paris");
+        assertThat(trace.get(2).tool()).isEqualTo("mcp:weather/get_forecast");
+        assertThat(trace.get(2).payload()).contains("\"ok\":true");
+    }
+
+    @Test
+    void toolAllowlistRestrictsExposedTools() throws Exception {
+        openAi.script(List.of(assistantMessage("I only have the lookup tool.")));
+
+        run(List.of(weatherServer()), List.of("lookup_city"));
+
+        assertThat(openAi.requests).hasSize(1);
+        assertThat(exposedFunctionNames(0)).containsExactly("weather__lookup_city");
+    }
+
+    @Test
+    void serverToolFiltersRestrictExposedTools() throws Exception {
+        openAi.script(List.of(assistantMessage("done")));
+
+        Map<String, Object> filtered = new java.util.HashMap<>(weatherServer());
+        filtered.put("toolFilters", List.of("get_forecast"));
+        run(List.of(filtered), List.of());
+
+        assertThat(exposedFunctionNames(0)).containsExactly("weather__get_forecast");
+    }
+
+    @Test
+    void withoutMcpServersNoToolsAreSentAndASingleRoundRuns() throws Exception {
+        openAi.script(List.of(assistantMessage("plain answer")));
+
+        TaskResult result = run(List.of(), List.of());
+
+        assertThat(result.response()).isEqualTo("plain answer");
+        assertThat(result.toolCallCount()).isZero();
+        assertThat(openAi.requests).hasSize(1);
+        assertThat(openAi.requests.get(0).has("tools")).isFalse();
+    }
+
+    @Test
+    void roundLimitCapsTheToolLoop() throws Exception {
+        properties.getOpenAiCompatible().setMaxToolRounds(2);
+        openAi.script(List.of(
+                toolCallMessage("weather__get_forecast", "{\"city\":\"Paris\"}"),
+                toolCallMessage("weather__get_forecast", "{\"city\":\"Rome\"}"),
+                toolCallMessage("weather__get_forecast", "{\"city\":\"Oslo\"}")));
+
+        TaskResult result = run(List.of(weatherServer()), List.of());
+
+        assertThat(result.toolCallCount()).isEqualTo(2);
+        assertThat(openAi.requests).hasSize(2);
+        assertThat(trace).anySatisfy(event -> {
+            assertThat(event.kind()).isEqualTo("log");
+            assertThat(event.payload()).contains("round limit");
+        });
+    }
+
+    private List<String> exposedFunctionNames(int requestIndex) {
+        List<String> names = new ArrayList<>();
+        for (JsonNode tool : openAi.requests.get(requestIndex).path("tools")) {
+            names.add(tool.path("function").path("name").asText());
+        }
+        return names;
+    }
+
+    // ---------------------------------------------------------------- fake endpoint
+
+    /** Serves scripted chat-completion responses and records every request body. */
+    private static final class FakeOpenAiEndpoint implements AutoCloseable {
+
+        private final HttpServer server;
+        private final List<ObjectNode> requests = new CopyOnWriteArrayList<>();
+        private final List<ObjectNode> scriptedResponses = new CopyOnWriteArrayList<>();
+
+        FakeOpenAiEndpoint() throws IOException {
+            server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+            server.createContext("/", this::handle);
+            server.start();
+        }
+
+        String baseUrl() {
+            return "http://127.0.0.1:" + server.getAddress().getPort() + "/v1";
+        }
+
+        void script(List<ObjectNode> assistantMessages) {
+            scriptedResponses.addAll(assistantMessages);
+        }
+
+        private void handle(HttpExchange exchange) throws IOException {
+            try {
+                String body = new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
+                requests.add((ObjectNode) MAPPER.readTree(body));
+                ObjectNode message = scriptedResponses.isEmpty()
+                        ? assistantMessage("no script left") : scriptedResponses.remove(0);
+                ObjectNode choice = MAPPER.createObjectNode();
+                choice.put("index", 0);
+                choice.set("message", message);
+                choice.put("finish_reason", "stop");
+                ObjectNode response = MAPPER.createObjectNode();
+                response.put("id", "chatcmpl-test");
+                response.putArray("choices").add(choice);
+                byte[] bytes = response.toString().getBytes(StandardCharsets.UTF_8);
+                exchange.getResponseHeaders().set("Content-Type", "application/json");
+                exchange.sendResponseHeaders(200, bytes.length);
+                try (OutputStream output = exchange.getResponseBody()) {
+                    output.write(bytes);
+                }
+            } finally {
+                exchange.close();
+            }
+        }
+
+        @Override
+        public void close() {
+            server.stop(0);
+        }
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/HttpMcpClientTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/HttpMcpClientTest.java
new file mode 100644
index 000000000..404dab1b2
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/HttpMcpClientTest.java
@@ -0,0 +1,172 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.sun.net.httpserver.HttpServer;
+import java.io.ByteArrayInputStream;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.net.http.HttpClient;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicInteger;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Exercises HttpMcpClient against a real local HTTP server implementing the MCP
+ * streamable-HTTP protocol, including the session-id contract and SSE-framed
+ * responses.
+ */
+class HttpMcpClientTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+    private final HttpClient httpClient = HttpClient.newHttpClient();
+
+    private TestingMcpHttpServer mcpServer;
+
+    @BeforeEach
+    void startServer() throws Exception {
+        mcpServer = new TestingMcpHttpServer(List.of("get_forecast", "lookup_city"));
+    }
+
+    @AfterEach
+    void stopServer() {
+        if (mcpServer != null) {
+            mcpServer.close();
+        }
+    }
+
+    private HttpMcpClient client() {
+        return new HttpMcpClient("weather", mcpServer.endpoint(), httpClient, objectMapper, Map.of());
+    }
+
+    @Test
+    void initializesListsToolsAndCallsTools() throws Exception {
+        try (HttpMcpClient client = client()) {
+            List<McpTool> tools = client.listTools(Duration.ofSeconds(5));
+            assertThat(tools).extracting(McpTool::name)
+                    .containsExactly("get_forecast", "lookup_city");
+            assertThat(tools.get(0).description()).isEqualTo("test tool get_forecast");
+
+            String output = client.callTool("get_forecast",
+                    Map.of("city", "Paris"), Duration.ofSeconds(5));
+            assertThat(output).isEqualTo("result of get_forecast: {\"city\":\"Paris\"}");
+            assertThat(mcpServer.toolCalls).hasSize(1);
+        }
+        assertThat(mcpServer.initializeCount.get()).isEqualTo(1);
+    }
+
+    @Test
+    void sessionHeaderIsReusedAfterInitialize() throws Exception {
+        // the fake server answers tools/list with 400 unless the Mcp-Session-Id
+        // captured during initialize is replayed — so a successful listing proves it
+        try (HttpMcpClient client = client()) {
+            assertThat(client.listTools(Duration.ofSeconds(5))).hasSize(2);
+        }
+        assertThat(mcpServer.sawRequestWithoutSessionId)
+                .as("tools/list must carry the session id from initialize")
+                .isFalse();
+    }
+
+    @Test
+    void parsesSseFramedResponses() throws Exception {
+        try (TestingMcpHttpServer sseServer =
+                     new TestingMcpHttpServer(List.of("echo"), true);
+             HttpMcpClient client = new HttpMcpClient("sse", sseServer.endpoint(),
+                     httpClient, objectMapper, Map.of())) {
+            List<McpTool> tools = client.listTools(Duration.ofSeconds(5));
+            assertThat(tools).extracting(McpTool::name).containsExactly("echo");
+        }
+    }
+
+    @Test
+    void toolErrorResultBecomesException() throws Exception {
+        try (HttpMcpClient client = client()) {
+            client.listTools(Duration.ofSeconds(5));
+            assertThatThrownBy(() -> client.callTool("boom", Map.of(), Duration.ofSeconds(5)))
+                    .isInstanceOf(java.io.IOException.class)
+                    .hasMessageContaining("boom");
+        }
+    }
+
+    @Test
+    void unreachableServerFailsFastWithClearMessage() {
+        try (HttpMcpClient client = new HttpMcpClient("dead",
+                "http://127.0.0.1:9/mcp", httpClient, objectMapper, Map.of())) {
+            assertThatThrownBy(() -> client.listTools(Duration.ofSeconds(5)))
+                    .isInstanceOf(Exception.class)
+                    .hasMessageContaining("dead");
+        }
+    }
+
+    @Test
+    void redirectsAreNeverFollowed() throws Exception {
+        // a public URL answering 302 towards a link-local target is the classic
+        // SSRF bypass: the client must surface the redirect as an error, not follow it
+        AtomicInteger requests = new AtomicInteger();
+        HttpServer redirector = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+        redirector.createContext("/", exchange -> {
+            requests.incrementAndGet();
+            exchange.getResponseHeaders().set("Location", "http://169.254.169.254/mcp");
+            exchange.sendResponseHeaders(302, -1);
+            exchange.close();
+        });
+        redirector.start();
+        try (HttpMcpClient client = new HttpMcpClient("redirector",
+                "http://127.0.0.1:" + redirector.getAddress().getPort() + "/mcp",
+                httpClient, objectMapper, Map.of())) {
+            assertThatThrownBy(() -> client.listTools(Duration.ofSeconds(5)))
+                    .isInstanceOf(Exception.class)
+                    .hasMessageContaining("302");
+        } finally {
+            redirector.stop(0);
+        }
+        assertThat(requests.get())
+                .as("the redirect target must never be requested")
+                .isEqualTo(1);
+    }
+
+    @Test
+    void oversizedResponseBodyIsRejected() throws Exception {
+        // 3 MiB body against a 2 MiB cap: a hostile endpoint must not be able to
+        // buffer an unbounded response in server memory
+        HttpServer flood = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+        flood.createContext("/", exchange -> {
+            byte[] bytes = new byte[3 * 1024 * 1024];
+            java.util.Arrays.fill(bytes, (byte) 'x');
+            exchange.getResponseHeaders().set("Content-Type", "application/json");
+            exchange.sendResponseHeaders(200, bytes.length);
+            try (OutputStream output = exchange.getResponseBody()) {
+                output.write(bytes);
+            }
+            exchange.close();
+        });
+        flood.start();
+        try (HttpMcpClient client = new HttpMcpClient("flood",
+                "http://127.0.0.1:" + flood.getAddress().getPort() + "/mcp",
+                httpClient, objectMapper, Map.of())) {
+            assertThatThrownBy(() -> client.listTools(Duration.ofSeconds(10)))
+                    .isInstanceOf(Exception.class)
+                    .hasMessageContaining("exceeds");
+        } finally {
+            flood.stop(0);
+        }
+    }
+
+    @Test
+    void readBodyCappedAllowsBodiesUnderTheLimit() throws Exception {
+        byte[] small = "hello".getBytes(StandardCharsets.UTF_8);
+        assertThat(HttpMcpClient.readBodyCapped(new ByteArrayInputStream(small), 10))
+                .isEqualTo("hello");
+        assertThatThrownBy(() -> HttpMcpClient.readBodyCapped(
+                new ByteArrayInputStream(small), 3))
+                .isInstanceOf(java.io.IOException.class)
+                .hasMessageContaining("exceeds");
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/McpClientFactoryTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/McpClientFactoryTest.java
new file mode 100644
index 000000000..bcd4fb3df
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/McpClientFactoryTest.java
@@ -0,0 +1,148 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.service.AuthoringSecurityPolicy;
+import com.iflytek.skillhub.service.authoring.TestingAuthoringSecurityPolicy;
+import java.io.IOException;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Connect-time enforcement in McpClientFactory: blocked endpoints and the
+ * disabled stdio transport fail before any connection or process is created,
+ * envRefs are filtered through the policy, and docker execution mode wraps
+ * stdio commands in the hardened container profile.
+ */
+class McpClientFactoryTest {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    private final AuthoringProperties properties = new AuthoringProperties();
+
+    private McpClientFactory factory(AuthoringSecurityPolicy policy) {
+        return new McpClientFactory(MAPPER, properties, policy);
+    }
+
+    /** Allows everything except env refs (for the envRefs filter test). */
+    private final AuthoringSecurityPolicy pathOnlyEnvRefs = new AuthoringSecurityPolicy() {
+        @Override
+        public String endpointRejection(String url, EndpointUse use) {
+            return null;
+        }
+
+        @Override
+        public boolean stdioTransportAllowed() {
+            return true;
+        }
+
+        @Override
+        public boolean envRefAllowed(String name) {
+            return "PATH".equals(name);
+        }
+    };
+
+    @Test
+    void httpEndpointRejectedByPolicyNeverConnects() {
+        AuthoringSecurityPolicy blocking = new AuthoringSecurityPolicy() {
+            @Override
+            public String endpointRejection(String url, EndpointUse use) {
+                return "blocked by test policy";
+            }
+
+            @Override
+            public boolean stdioTransportAllowed() {
+                return true;
+            }
+
+            @Override
+            public boolean envRefAllowed(String name) {
+                return true;
+            }
+        };
+        assertThatThrownBy(() -> factory(blocking).create(Map.of(
+                "name", "evil", "transport", "http", "endpoint", "http://169.254.169.254/mcp")))
+                .isInstanceOf(IOException.class)
+                .hasMessageContaining("endpoint rejected");
+    }
+
+    @Test
+    void stdioIsRefusedWhenDisabled() {
+        AuthoringSecurityPolicy stdioDisabled = new AuthoringSecurityPolicy() {
+            @Override
+            public String endpointRejection(String url, EndpointUse use) {
+                return null;
+            }
+
+            @Override
+            public boolean stdioTransportAllowed() {
+                return false;
+            }
+
+            @Override
+            public boolean envRefAllowed(String name) {
+                return true;
+            }
+        };
+        assertThatThrownBy(() -> factory(stdioDisabled).create(
+                Map.of("name", "local", "transport", "stdio", "command", "sleep 30")))
+                .isInstanceOf(IOException.class)
+                .hasMessageContaining("stdio transport is disabled");
+    }
+
+    @Test
+    void envRefsNotInAllowlistNeverReachTheSpawnedProcess() {
+        // HOME exists in every environment, so dropping it is observable: only
+        // the allowlisted PATH survives the filter
+        Map<String, Object> server = Map.of(
+                "name", "envtest", "transport", "stdio", "command", "sleep 30",
+                "envRefs", List.of("PATH", "HOME"));
+        Map<String, String> environment = factory(pathOnlyEnvRefs).environmentOf(server);
+        assertThat(environment).containsKey("PATH");
+        assertThat(environment).doesNotContainKey("HOME");
+    }
+
+    @Test
+    void dockerModeWrapsStdioCommandInHardenedContainer() {
+        properties.getMcp().setStdioEnabled(true);
+        properties.getLocalScript().setExecutionMode(
+                AuthoringProperties.ScriptExecutionMode.DOCKER);
+        properties.getMcp().getDocker().setImage("alpine:3.20");
+
+        List<String> wrapped = factory(TestingAuthoringSecurityPolicy.permissive())
+                .dockerWrappedCommand("skillhub-mcp-test-abcd1234",
+                        List.of("python3", "-m", "fake_server"),
+                        Map.of("WEATHER_API_KEY", "secret-value"));
+
+        assertThat(wrapped.get(0)).isEqualTo("docker");
+        assertThat(wrapped).containsSubsequence("run", "--rm", "--name",
+                "skillhub-mcp-test-abcd1234");
+        assertThat(wrapped).containsSubsequence("--network", "none");
+        assertThat(wrapped).containsSubsequence("--memory", "256m");
+        assertThat(wrapped).containsSubsequence("--cpus", "1.0");
+        assertThat(wrapped).containsSubsequence("--pids-limit", "128");
+        assertThat(wrapped).contains("--read-only");
+        assertThat(wrapped).containsSubsequence("--cap-drop", "ALL");
+        assertThat(wrapped).contains("no-new-privileges");
+        // environment travels as -e flags, not through the parent environment
+        assertThat(wrapped).containsSubsequence("-e", "WEATHER_API_KEY=secret-value");
+        // the image runs the declared command
+        int image = wrapped.indexOf("alpine:3.20");
+        assertThat(image).isPositive();
+        assertThat(wrapped.subList(image + 1, wrapped.size()))
+                .containsExactly("python3", "-m", "fake_server");
+    }
+
+    @Test
+    void containerNamesAreSanitizedAndUnique() {
+        String first = McpClientFactory.containerName("my server!");
+        String second = McpClientFactory.containerName("my server!");
+        assertThat(first).startsWith("skillhub-mcp-my-server-");
+        assertThat(first).isNotEqualTo(second);
+        assertThat(McpClientFactory.containerName(null)).startsWith("skillhub-mcp-unknown-");
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/McpProbeServiceTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/McpProbeServiceTest.java
new file mode 100644
index 000000000..85e825e55
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/McpProbeServiceTest.java
@@ -0,0 +1,98 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.iflytek.skillhub.config.AuthoringProperties;
+import com.iflytek.skillhub.domain.authoring.validation.FindingDraft;
+import com.iflytek.skillhub.domain.authoring.validation.FindingSeverity;
+import com.iflytek.skillhub.service.authoring.TestingAuthoringSecurityPolicy;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * McpProbeService turns MCP declarations into verified facts: reachable servers
+ * with their discovered tools, and findings for unreachable servers or filters
+ * naming tools the server does not expose.
+ */
+class McpProbeServiceTest {
+
+    private final McpProbeService probeService = new McpProbeService(new McpClientFactory(
+            new ObjectMapper(), new AuthoringProperties(),
+            TestingAuthoringSecurityPolicy.permissive()));
+
+    private TestingMcpHttpServer mcpServer;
+
+    @BeforeEach
+    void startServer() throws Exception {
+        mcpServer = new TestingMcpHttpServer(List.of("get_forecast", "lookup_city"));
+    }
+
+    @AfterEach
+    void stopServer() {
+        if (mcpServer != null) {
+            mcpServer.close();
+        }
+    }
+
+    private Map<String, Object> server(Map<String, Object> overrides) {
+        Map<String, Object> server = new java.util.HashMap<>();
+        server.put("name", "weather");
+        server.put("transport", "http");
+        server.put("endpoint", mcpServer.endpoint());
+        server.putAll(overrides);
+        return server;
+    }
+
+    @Test
+    void reachableServerReportsDiscoveredToolsWithoutFindings() {
+        McpProbeService.ProbeReport report = probeService.probe(
+                List.of(server(Map.of())), Duration.ofSeconds(5));
+        assertThat(report.servers()).hasSize(1);
+        assertThat(report.servers().get(0).connected()).isTrue();
+        assertThat(report.servers().get(0).tools())
+                .containsExactly("get_forecast", "lookup_city");
+        assertThat(report.findings()).isEmpty();
+    }
+
+    @Test
+    void unreachableServerProducesConnectFailedError() {
+        Map<String, Object> dead = Map.of(
+                "name", "dead", "transport", "http", "endpoint", "http://127.0.0.1:9/mcp");
+        McpProbeService.ProbeReport report = probeService.probe(List.of(dead), Duration.ofSeconds(5));
+        assertThat(report.servers().get(0).connected()).isFalse();
+        assertThat(report.findings()).hasSize(1);
+        FindingDraft finding = report.findings().get(0);
+        assertThat(finding.ruleCode()).isEqualTo("MCP_CONNECT_FAILED");
+        assertThat(finding.severity()).isEqualTo(FindingSeverity.ERROR);
+        assertThat(finding.message()).contains("dead");
+    }
+
+    @Test
+    void unknownToolFilterProducesWarningButStaysConnected() {
+        McpProbeService.ProbeReport report = probeService.probe(
+                List.of(server(Map.of("toolFilters", List.of("get_forecast", "does_not_exist")))),
+                Duration.ofSeconds(5));
+        assertThat(report.servers().get(0).connected()).isTrue();
+        assertThat(report.findings()).hasSize(1);
+        FindingDraft finding = report.findings().get(0);
+        assertThat(finding.ruleCode()).isEqualTo("MCP_TOOL_FILTER_UNKNOWN");
+        assertThat(finding.severity()).isEqualTo(FindingSeverity.WARNING);
+        assertThat(finding.message()).contains("does_not_exist").contains("get_forecast");
+    }
+
+    @Test
+    void malformedDeclarationsAreSkippedNotProbed() {
+        // name/transport problems are already reported by RuntimeBindingValidator;
+        // the probe must not duplicate them or crash
+        McpProbeService.ProbeReport report = probeService.probe(
+                List.of(Map.of("name", "weird", "transport", "carrier-pigeon")),
+                Duration.ofSeconds(5));
+        assertThat(report.servers()).isEmpty();
+        assertThat(report.findings()).isEmpty();
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/StdioMcpClientTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/StdioMcpClientTest.java
new file mode 100644
index 000000000..f918ceca1
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/StdioMcpClientTest.java
@@ -0,0 +1,133 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.Assumptions;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Runs StdioMcpClient against a python3 process implementing the stdio transport
+ * (newline-delimited JSON-RPC on stdin/stdout). Skipped when python3 is absent.
+ */
+class StdioMcpClientTest {
+
+    private static final String FAKE_SERVER = """
+            import json, sys
+            def send(obj):
+                sys.stdout.write(json.dumps(obj) + "\\n")
+                sys.stdout.flush()
+            for line in sys.stdin:
+                line = line.strip()
+                if not line:
+                    continue
+                msg = json.loads(line)
+                if 'id' not in msg:
+                    continue
+                method = msg.get('method')
+                if method == 'initialize':
+                    send({'jsonrpc': '2.0', 'id': msg['id'], 'result': {
+                        'protocolVersion': '2024-11-05', 'capabilities': {},
+                        'serverInfo': {'name': 'fake', 'version': '1.0'}}})
+                elif method == 'tools/list':
+                    send({'jsonrpc': '2.0', 'id': msg['id'], 'result': {'tools': [
+                        {'name': 'echo', 'description': 'echo text',
+                         'inputSchema': {'type': 'object'}}]}})
+                elif method == 'tools/call':
+                    args = msg['params']['arguments']
+                    send({'jsonrpc': '2.0', 'id': msg['id'], 'result': {'content': [
+                        {'type': 'text', 'text': 'echo:' + args.get('text', '')}]}})
+            """;
+
+    @BeforeAll
+    static void requirePython3() {
+        try {
+            int exit = new ProcessBuilder("python3", "--version").start().waitFor();
+            Assumptions.assumeTrue(exit == 0, "python3 unavailable");
+        } catch (Exception exception) {
+            Assumptions.assumeTrue(false, "python3 unavailable: " + exception.getMessage());
+        }
+    }
+
+    private StdioMcpClient client() throws Exception {
+        return new StdioMcpClient("echo-server", List.of("python3", "-c", FAKE_SERVER),
+                Map.of(), new ObjectMapper());
+    }
+
+    @Test
+    void listsToolsAndCallsThemOverStdio() throws Exception {
+        try (StdioMcpClient client = client()) {
+            List<McpTool> tools = client.listTools(Duration.ofSeconds(10));
+            assertThat(tools).extracting(McpTool::name).containsExactly("echo");
+
+            String output = client.callTool("echo", Map.of("text", "hello"), Duration.ofSeconds(10));
+            assertThat(output).isEqualTo("echo:hello");
+        }
+    }
+
+    @Test
+    void processIsTerminatedOnClose() throws Exception {
+        StdioMcpClient client = client();
+        client.listTools(Duration.ofSeconds(10));
+        client.close();
+        // a second close must not hang or throw; the process is already gone
+        client.close();
+    }
+
+    @Test
+    void failingCommandSurfacesAsException() {
+        assertThatThrownBy(() -> new StdioMcpClient("broken",
+                List.of("definitely-not-a-real-command-xyz"), Map.of(), new ObjectMapper())
+                .listTools(Duration.ofSeconds(10)))
+                .isInstanceOf(Exception.class);
+    }
+
+    @Test
+    void unterminatedHugeLineIsRejectedAndTheProcessKilled() {
+        // a hostile stdio server streaming one endless line must not exhaust
+        // memory: the capped reader destroys the process past the limit
+        String floodServer = """
+                import sys, time
+                sys.stdout.write('x' * (5 * 1024 * 1024))
+                sys.stdout.flush()
+                time.sleep(60)
+                """;
+        StdioMcpClient client;
+        try {
+            client = new StdioMcpClient("flood", List.of("python3", "-c", floodServer),
+                    Map.of(), new ObjectMapper());
+        } catch (Exception exception) {
+            // python3 disappeared between the class check and here
+            org.junit.jupiter.api.Assumptions.assumeTrue(false, exception.getMessage());
+            return;
+        }
+        assertThatThrownBy(() -> client.listTools(Duration.ofSeconds(30)))
+                .isInstanceOf(Exception.class)
+                .hasMessageContaining("longer than");
+        client.close();
+    }
+
+    @Test
+    void teardownCommandRunsOnClose() throws Exception {
+        // docker-wrapped stdio servers rely on this: a killed docker client can
+        // leave its container behind, so close() must run the cleanup command
+        Path marker = Files.createTempFile("skillhub-stdio-teardown", ".marker");
+        Files.deleteIfExists(marker);
+        StdioMcpClient client = new StdioMcpClient("cleaned",
+                List.of("python3", "-c", FAKE_SERVER), Map.of(), new ObjectMapper(),
+                List.of("touch", marker.toString()), false);
+        client.listTools(Duration.ofSeconds(10));
+        client.close();
+        assertThat(Files.exists(marker))
+                .as("the teardown command must have run after process destruction")
+                .isTrue();
+        Files.deleteIfExists(marker);
+    }
+}
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/TestingMcpHttpServer.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/TestingMcpHttpServer.java
new file mode 100644
index 000000000..c2f9678aa
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/service/authoring/mcp/TestingMcpHttpServer.java
@@ -0,0 +1,156 @@
+package com.iflytek.skillhub.service.authoring.mcp;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpServer;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.atomic.AtomicInteger;
+
+/**
+ * Minimal MCP streamable-HTTP server for tests. Implements the initialize /
+ * notifications/initialized / tools/list / tools/call exchange the real client
+ * performs, can answer in plain JSON or SSE framing, enforces the session id on
+ * post-initialize requests, and records every tools/call it received. The tool
+ * named "boom" always answers with an error result.
+ */
+public class TestingMcpHttpServer implements AutoCloseable {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    private final HttpServer server;
+    private final List<String> toolNames;
+    private final boolean sseMode;
+
+    /** Every tools/call: tool name -> argument map, in arrival order. */
+    public final List<Map.Entry<String, JsonNode>> toolCalls = new CopyOnWriteArrayList<>();
+    /** Whether a post-initialize request arrived without the session id header. */
+    public volatile boolean sawRequestWithoutSessionId;
+    /** How many initialize requests were handled. */
+    public final AtomicInteger initializeCount = new AtomicInteger();
+
+    public TestingMcpHttpServer(List<String> toolNames) throws IOException {
+        this(toolNames, false);
+    }
+
+    public TestingMcpHttpServer(List<String> toolNames, boolean sseMode) throws IOException {
+        this.toolNames = List.copyOf(toolNames);
+        this.sseMode = sseMode;
+        server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+        server.createContext("/", this::handle);
+        server.start();
+    }
+
+    public String endpoint() {
+        return "http://127.0.0.1:" + server.getAddress().getPort() + "/mcp";
+    }
+
+    private void handle(HttpExchange exchange) throws IOException {
+        try {
+            String body = new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
+            JsonNode request = MAPPER.readTree(body);
+            String method = request.path("method").asText("");
+            if ("initialize".equals(method)) {
+                initializeCount.incrementAndGet();
+                respond(exchange, result(exchange, request, initializeResult()), "test-session-1");
+            } else if ("notifications/initialized".equals(method)) {
+                exchange.sendResponseHeaders(202, -1);
+            } else if ("tools/list".equals(method)) {
+                if (exchange.getRequestHeaders().getFirst("Mcp-Session-Id") == null) {
+                    sawRequestWithoutSessionId = true;
+                    exchange.sendResponseHeaders(400, -1);
+                    return;
+                }
+                respond(exchange, result(exchange, request, toolsListResult()), null);
+            } else if ("tools/call".equals(method)) {
+                if (exchange.getRequestHeaders().getFirst("Mcp-Session-Id") == null) {
+                    sawRequestWithoutSessionId = true;
+                    exchange.sendResponseHeaders(400, -1);
+                    return;
+                }
+                String tool = request.path("params").path("name").asText();
+                toolCalls.add(Map.entry(tool, request.path("params").path("arguments")));
+                respond(exchange, result(exchange, request, toolCallResult(tool,
+                        request.path("params").path("arguments"))), null);
+            } else {
+                exchange.sendResponseHeaders(404, -1);
+            }
+        } finally {
+            exchange.close();
+        }
+    }
+
+    private ObjectNode initializeResult() {
+        ObjectNode result = MAPPER.createObjectNode();
+        result.put("protocolVersion", "2024-11-05");
+        result.set("capabilities", MAPPER.createObjectNode());
+        result.putObject("serverInfo").put("name", "testing-mcp").put("version", "1.0");
+        return result;
+    }
+
+    private ObjectNode toolsListResult() {
+        ObjectNode result = MAPPER.createObjectNode();
+        ArrayNode tools = result.putArray("tools");
+        for (String name : toolNames) {
+            ObjectNode tool = tools.addObject();
+            tool.put("name", name);
+            tool.put("description", "test tool " + name);
+            tool.putObject("inputSchema").put("type", "object");
+        }
+        return result;
+    }
+
+    private ObjectNode toolCallResult(String tool, JsonNode arguments) {
+        ObjectNode result = MAPPER.createObjectNode();
+        if ("boom".equals(tool)) {
+            result.put("isError", true);
+            result.putArray("content").addObject().put("type", "text").put("text", "tool exploded");
+            return result;
+        }
+        result.putArray("content").addObject().put("type", "text")
+                .put("text", "result of " + tool + ": " + arguments);
+        return result;
+    }
+
+    private ObjectNode result(HttpExchange exchange, JsonNode request, ObjectNode payload) {
+        ObjectNode response = MAPPER.createObjectNode();
+        response.put("jsonrpc", "2.0");
+        response.put("id", request.path("id").asInt());
+        response.set("result", payload);
+        return response;
+    }
+
+    private void respond(HttpExchange exchange, ObjectNode response, String sessionId)
+            throws IOException {
+        byte[] bytes;
+        String contentType;
+        if (sseMode) {
+            bytes = ("event: message\ndata: " + response + "\n\n").getBytes(StandardCharsets.UTF_8);
+            contentType = "text/event-stream";
+        } else {
+            bytes = response.toString().getBytes(StandardCharsets.UTF_8);
+            contentType = "application/json";
+        }
+        if (sessionId != null) {
+            exchange.getResponseHeaders().set("Mcp-Session-Id", sessionId);
+        }
+        exchange.getResponseHeaders().set("Content-Type", contentType);
+        exchange.sendResponseHeaders(200, bytes.length);
+        try (OutputStream output = exchange.getResponseBody()) {
+            output.write(bytes);
+        }
+    }
+
+    @Override
+    public void close() {
+        server.stop(0);
+    }
+}
diff --git a/server/skillhub-app/src/test/resources/application-test.yml b/server/skillhub-app/src/test/resources/application-test.yml
index 592d2f446..099c38af6 100644
--- a/server/skillhub-app/src/test/resources/application-test.yml
+++ b/server/skillhub-app/src/test/resources/application-test.yml
@@ -53,7 +53,17 @@ skillhub:
     local-script:
       # tests exercise the inline script runtime directly; no docker needed
       execution-mode: inline
+    openai-compatible:
+      # fake LLM endpoints in tests bind to loopback
+      allow-private-endpoints: true
+    mcp:
+      # fake MCP servers in tests bind to loopback; link-local stays blocked
+      allow-private-endpoints: true
+      stdio-enabled: true
+      # the one variable bindings may reference in tests; everything else is rejected
+      env-allowlist: TEST_ALLOWED_MCP_VAR
 
+logging:
   level:
     root: ERROR
     com.iflytek.skillhub: ERROR
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/AuthoringSecurityPolicy.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/AuthoringSecurityPolicy.java
new file mode 100644
index 000000000..42f70ca1d
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/AuthoringSecurityPolicy.java
@@ -0,0 +1,33 @@
+package com.iflytek.skillhub.domain.authoring.service;
+
+/**
+ * Security boundary for user-supplied runtime bindings, implemented by the
+ * application layer from {@code skillhub.authoring.*} configuration. The domain
+ * validator consults it at save time so that dangerous bindings are rejected
+ * before they can ever run.
+ *
+ * <p>Implementations must be conservative: an endpoint, transport, or
+ * environment reference that cannot be checked must be rejected, not allowed.
+ */
+public interface AuthoringSecurityPolicy {
+
+    /** Where a user-supplied URL is about to be used, so flags can differ per surface. */
+    enum EndpointUse {
+        MCP_SERVER,
+        LLM_API
+    }
+
+    /**
+     * Decides whether the server may make an outbound HTTP(S) request to the
+     * given URL (SSRF guard).
+     *
+     * @return {@code null} when the URL is allowed, otherwise the rejection reason
+     */
+    String endpointRejection(String url, EndpointUse use);
+
+    /** Whether MCP servers may use the stdio transport (server-side process spawn). */
+    boolean stdioTransportAllowed();
+
+    /** Whether a binding may reference the named server environment variable. */
+    boolean envRefAllowed(String name);
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
index e5273dd80..3cbc2c06f 100644
--- a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingValidator.java
@@ -15,8 +15,7 @@
  * of validation task assertions. Rejects embedded plaintext credentials — bindings may
  * only reference server-side credential names. Outbound endpoints, the stdio
  * transport, and environment references are additionally gated by the
- * Structural checks only in this layer; the SSRF/stdio/envRef policy that
- * guards external endpoints arrives with the MCP+security layer.
+ * {@link AuthoringSecurityPolicy} so unsafe bindings are rejected at save time.
  */
 @Service
 public class RuntimeBindingValidator {
@@ -30,9 +29,12 @@ public class RuntimeBindingValidator {
     private static final List<String> INTERPRETERS = List.of("sh", "bash", "python3", "node");
 
     private final ScriptEnvironmentPolicy environmentPolicy;
+    private final AuthoringSecurityPolicy securityPolicy;
 
-    public RuntimeBindingValidator(ScriptEnvironmentPolicy environmentPolicy) {
+    public RuntimeBindingValidator(ScriptEnvironmentPolicy environmentPolicy,
+                                   AuthoringSecurityPolicy securityPolicy) {
         this.environmentPolicy = environmentPolicy;
+        this.securityPolicy = securityPolicy;
     }
 
     /**
@@ -116,6 +118,15 @@ private void validateOpenAiCompatibleConfig(Map<String, Object> config, List<Fin
         } else if (!isHttpUrl(endpoint.toString())) {
             findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_ENDPOINT_INVALID",
                     "endpoint must be an http(s) URL: " + endpoint));
+        } else {
+            // these requests carry the server-side API key; the SSRF guard must
+            // approve the destination before any credential can leave the host
+            String rejection = securityPolicy.endpointRejection(
+                    endpoint.toString(), AuthoringSecurityPolicy.EndpointUse.LLM_API);
+            if (rejection != null) {
+                findings.add(FindingDraft.error(ValidationLayer.CONFIG, "LLM_ENDPOINT_BLOCKED",
+                        "openai-compatible endpoint is not allowed: " + rejection));
+            }
         }
         Object model = config.get("model");
         if (model == null || model.toString().isBlank()) {
@@ -151,13 +162,20 @@ private void validateMcpServer(Map<String, Object> server, List<FindingDraft> fi
             if (endpoint == null || !isHttpUrl(endpoint.toString())) {
                 findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENDPOINT_INVALID",
                         "MCP server " + name + " requires an http(s) endpoint"));
+            } else {
+                String rejection = securityPolicy.endpointRejection(
+                        endpoint.toString(), AuthoringSecurityPolicy.EndpointUse.MCP_SERVER);
+                if (rejection != null) {
+                    findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENDPOINT_BLOCKED",
+                            "MCP server " + name + " endpoint is not allowed: " + rejection));
+                }
             }
         } else {
-            // stdio servers spawn host-side processes; the enable switch and the
-            // docker isolation that gate them arrive with the security layer
-            findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_STDIO_DISABLED",
-                    "MCP server " + name + " uses the stdio transport, which is not"
-                            + " available yet; use http/sse instead"));
+            if (!securityPolicy.stdioTransportAllowed()) {
+                findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_STDIO_DISABLED",
+                        "MCP server " + name + " uses the stdio transport, which is disabled"
+                                + " (skillhub.authoring.mcp.stdio-enabled=false); use http/sse instead"));
+            }
             Object command = server.get("command");
             if (command == null || command.toString().isBlank()) {
                 findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_COMMAND_MISSING",
@@ -179,6 +197,10 @@ private void validateMcpServer(Map<String, Object> server, List<FindingDraft> fi
                 if (ref == null || !ENV_REF_NAME.matcher(ref.toString()).matches()) {
                     findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENV_REF_INVALID",
                             "MCP server " + name + " has an invalid env reference: " + ref));
+                } else if (!securityPolicy.envRefAllowed(ref.toString())) {
+                    findings.add(FindingDraft.error(ValidationLayer.CONFIG, "MCP_ENV_REF_NOT_ALLOWED",
+                            "MCP server " + name + " may not reference environment variable "
+                                    + ref + " (not in skillhub.authoring.mcp.env-allowlist)"));
                 }
             }
         }
diff --git a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingEnvironmentAuthorizationTest.java b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingEnvironmentAuthorizationTest.java
index 4f8243203..0d1773c2a 100644
--- a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingEnvironmentAuthorizationTest.java
+++ b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/RuntimeBindingEnvironmentAuthorizationTest.java
@@ -16,7 +16,7 @@ class RuntimeBindingEnvironmentAuthorizationTest {
         var bindings = mock(RuntimeBindingRepository.class);
         var drafts = mock(SkillDraftRepository.class);
         var policy = new ScriptEnvironmentPolicy(() -> List.of("AUTHORING_DEMO"));
-        var service = new RuntimeBindingService(bindings, drafts, new RuntimeBindingValidator(policy));
+        var service = new RuntimeBindingService(bindings, drafts, new RuntimeBindingValidator(policy, new PermissiveSecurityPolicy()));
         when(drafts.findById(7L)).thenReturn(Optional.of(new SkillDraft(1L, "ordinary-member", "test", "test", "digest")));
         when(bindings.findByDraftId(7L)).thenReturn(Optional.empty());
         when(bindings.save(any())).thenAnswer(call -> call.getArgument(0));
@@ -35,7 +35,7 @@ class RuntimeBindingEnvironmentAuthorizationTest {
         var drafts = mock(SkillDraftRepository.class);
         when(drafts.findById(7L)).thenReturn(Optional.of(new SkillDraft(1L, "ordinary-member", "test", "test", "digest")));
         var service = new RuntimeBindingService(bindings, drafts,
-                new RuntimeBindingValidator(new ScriptEnvironmentPolicy(List::of)));
+                new RuntimeBindingValidator(new ScriptEnvironmentPolicy(List::of), new PermissiveSecurityPolicy()));
         assertThatThrownBy(() -> service.saveBinding(7L, "admin", "local-script",
                 Map.of("envAllowlist", List.of("AUTHORING_DEMO")), null, null, Set.of("SUPER_ADMIN")))
                 .isInstanceOf(DomainBadRequestException.class);
@@ -46,10 +46,17 @@ class RuntimeBindingEnvironmentAuthorizationTest {
         var drafts = mock(SkillDraftRepository.class);
         when(drafts.findById(7L)).thenReturn(Optional.of(new SkillDraft(1L, "owner", "test", "test", "digest")));
         var service = new RuntimeBindingService(bindings, drafts,
-                new RuntimeBindingValidator(new ScriptEnvironmentPolicy(() -> List.of("AUTHORING_DEMO"))));
+                new RuntimeBindingValidator(new ScriptEnvironmentPolicy(() -> List.of("AUTHORING_DEMO")), new PermissiveSecurityPolicy()));
         assertThatThrownBy(() -> service.saveBinding(7L, "other-member", "local-script",
                 Map.of("envAllowlist", List.of("AUTHORING_DEMO")), null, null, Set.of()))
                 .isInstanceOf(DomainForbiddenException.class);
         verify(bindings, never()).save(any());
     }
+
+    /** Layer-agnostic stub: the security policy is not under test here. */
+    static final class PermissiveSecurityPolicy implements AuthoringSecurityPolicy {
+        @Override public String endpointRejection(String url, EndpointUse use) { return null; }
+        @Override public boolean stdioTransportAllowed() { return true; }
+        @Override public boolean envRefAllowed(String name) { return true; }
+    }
 }
diff --git a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicyTest.java b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicyTest.java
index 433346b3a..5d5c2ae05 100644
--- a/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicyTest.java
+++ b/server/skillhub-domain/src/test/java/com/iflytek/skillhub/domain/authoring/service/ScriptEnvironmentPolicyTest.java
@@ -60,11 +60,18 @@ class ScriptEnvironmentPolicyTest {
     }
     @Test void configValidationUsesCurrentPolicyWithoutDisclosingValues() {
         var current = new AtomicReference<>(List.of("AUTHORING_DEMO"));
-        var validator = new RuntimeBindingValidator(new ScriptEnvironmentPolicy(current::get));
+        var validator = new RuntimeBindingValidator(new ScriptEnvironmentPolicy(current::get), new PermissiveSecurityPolicy());
         var config = Map.<String, Object>of("interpreter", "sh", "envAllowlist", List.of("AUTHORING_DEMO"));
         assertThat(validator.validate("local-script", config, null, null)).isEmpty();
         current.set(List.of());
         assertThat(validator.validate("local-script", config, null, null))
                 .extracting(finding -> finding.ruleCode()).containsExactly("ENV_ALLOWLIST_FORBIDDEN");
     }
+
+    /** Layer-agnostic stub: the security policy is not under test here. */
+    static final class PermissiveSecurityPolicy implements AuthoringSecurityPolicy {
+        @Override public String endpointRejection(String url, EndpointUse use) { return null; }
+        @Override public boolean stdioTransportAllowed() { return true; }
+        @Override public boolean envRefAllowed(String name) { return true; }
+    }
 }

From f22b9350c274d04862a58b46cccfe51d0b055745 Mon Sep 17 00:00:00 2001
From: zjncs <18910855655@163.com>
Date: Sat, 10 Oct 2026 14:54:22 +0800
Subject: [PATCH 16/17] feat(authoring): fix loop and publish-pipeline
 integration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Layer (c) of the authoring platform (#934), stacking on the runtime
layer:

- **Fix loop**: apply a finding's suggested patch to the draft in one
  call (sha256-guarded old content, revision bump, validation verdict
  invalidated by the new revision) or dismiss it as not applicable
- **Submission**: validated drafts submit into the existing SkillHub
  publish pipeline — the gate is strict (the draft's current revision
  must be bound to a run that succeeded with zero errors), so content
  can never be published without the exact bytes that were validated;
  reuses SkillPublishService (package re-validation, security scan,
  review flow) and records the resulting skill id on the draft

Verified by the full authoring flow integration test: create → edit →
bind runtime → three-layer validation → fix a finding → re-validate →
submit into the (mocked) publish pipeline.

Signed-off-by: zjncs <18910855655@163.com>
---
 .../authoring/SkillAuthoringController.java   |  65 ++-
 .../skillhub/dto/SubmitDraftRequest.java      |  10 +
 .../skillhub/dto/SubmitDraftResponse.java     |  17 +
 .../src/main/resources/messages.properties    |   3 +
 .../src/main/resources/messages_ru.properties |   3 +
 .../src/main/resources/messages_zh.properties |   3 +
 .../AuthoringFlowIntegrationTest.java         | 397 ++++++++++++++++++
 .../authoring/service/DraftSubmitService.java |  94 +++++
 .../authoring/service/FindingFixService.java  |  94 +++++
 9 files changed, 682 insertions(+), 4 deletions(-)
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SubmitDraftRequest.java
 create mode 100644 server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SubmitDraftResponse.java
 create mode 100644 server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringFlowIntegrationTest.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/DraftSubmitService.java
 create mode 100644 server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/FindingFixService.java

diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java
index a3a312b6a..504ac3b5e 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/controller/authoring/SkillAuthoringController.java
@@ -2,9 +2,13 @@
 
 import com.iflytek.skillhub.controller.BaseApiController;
 import com.iflytek.skillhub.domain.authoring.SkillDraft;
+import com.iflytek.skillhub.domain.skill.SkillVisibility;
+import com.iflytek.skillhub.domain.authoring.service.DraftSubmitService;
+import com.iflytek.skillhub.domain.authoring.service.FindingFixService;
 import com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService;
 import com.iflytek.skillhub.domain.authoring.service.SkillDraftService;
 import com.iflytek.skillhub.domain.authoring.service.ValidationRunService;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationFinding;
 import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
 import com.iflytek.skillhub.dto.ApiResponse;
 import com.iflytek.skillhub.dto.CreateDraftRequest;
@@ -13,6 +17,8 @@
 import com.iflytek.skillhub.dto.DraftResponse;
 import com.iflytek.skillhub.dto.RuntimeBindingRequest;
 import com.iflytek.skillhub.dto.RuntimeBindingResponse;
+import com.iflytek.skillhub.dto.SubmitDraftRequest;
+import com.iflytek.skillhub.dto.SubmitDraftResponse;
 import com.iflytek.skillhub.dto.SaveDraftFileRequest;
 import com.iflytek.skillhub.dto.SaveDraftFileResponse;
 import com.iflytek.skillhub.dto.ValidationEventResponse;
@@ -40,10 +46,10 @@
 /**
  * REST endpoints for skill draft authoring and validation. Drafts own a
  * SKILL.md scaffold and arbitrary resource files; runtime bindings configure
- * the agent and tool allowlist; validation runs execute the structure, config
- * and behavior layers and report findings with fix suggestions. The MCP probe
- * and the binding security policy arrive with the MCP+security layer, and the
- * fix-apply loop and publish integration with the next layer.
+ * the agent, tool allowlist and MCP servers; validation runs execute the
+ * structure, config and behavior layers and report findings with fix
+ * suggestions that can be applied in one click; validated drafts submit into
+ * the existing SkillHub publish pipeline.
  */
 @RestController
 @RequestMapping({"/api/v1/authoring", "/api/web/authoring"})
@@ -52,17 +58,23 @@ public class SkillAuthoringController extends BaseApiController {
     private final SkillDraftService draftService;
     private final RuntimeBindingService bindingService;
     private final ValidationRunService runService;
+    private final DraftSubmitService submitService;
+    private final FindingFixService fixService;
     private final ValidationRunOrchestrator orchestrator;
 
     public SkillAuthoringController(com.iflytek.skillhub.dto.ApiResponseFactory responseFactory,
                                     SkillDraftService draftService,
                                     RuntimeBindingService bindingService,
                                     ValidationRunService runService,
+                                    DraftSubmitService submitService,
+                                    FindingFixService fixService,
                                     ValidationRunOrchestrator orchestrator) {
         super(responseFactory);
         this.draftService = draftService;
         this.bindingService = bindingService;
         this.runService = runService;
+        this.submitService = submitService;
+        this.fixService = fixService;
         this.orchestrator = orchestrator;
     }
 
@@ -272,4 +284,49 @@ public ApiResponse<List<ValidationFindingResponse>> listFindings(
                 .map(ValidationFindingResponse::from)
                 .toList());
     }
+
+    // ---------------------------------------------------------------- fix loop
+
+    @Operation(operationId = "applyFindingFix", summary = "Apply a finding's fix suggestion to the draft")
+    @PostMapping("/runs/{runId}/findings/{findingId}/apply")
+    public ApiResponse<ValidationFindingResponse> applyFindingFix(
+            @PathVariable Long runId,
+            @PathVariable Long findingId,
+            @RequestAttribute("userId") String userId,
+            @RequestAttribute(value = "platformRoles", required = false)
+            Set<String> platformRoles) {
+        FindingFixService.FixOutcome outcome = fixService.applyFix(findingId, userId, platformRoles);
+        return ok("response.success.updated", ValidationFindingResponse.from(outcome.finding()));
+    }
+
+    @Operation(operationId = "dismissFindingFix", summary = "Dismiss a finding as not applicable")
+    @PostMapping("/runs/{runId}/findings/{findingId}/dismiss")
+    public ApiResponse<ValidationFindingResponse> dismissFinding(
+            @PathVariable Long runId,
+            @PathVariable Long findingId,
+            @RequestAttribute("userId") String userId,
+            @RequestAttribute(value = "platformRoles", required = false)
+            Set<String> platformRoles) {
+        ValidationFinding finding = fixService.dismissFinding(findingId, userId, platformRoles);
+        return ok("response.success.updated", ValidationFindingResponse.from(finding));
+    }
+
+    // ---------------------------------------------------------------- submission
+
+    @Operation(operationId = "submitValidatedDraft", summary = "Submit a validated draft into the publish pipeline")
+    @PostMapping("/drafts/{draftId}/submit")
+    public ApiResponse<SubmitDraftResponse> submitDraft(@PathVariable Long draftId,
+                                                        @RequestBody(required = false) SubmitDraftRequest request,
+                                                        @RequestAttribute("userId") String userId,
+                                                        @RequestAttribute(value = "platformRoles", required = false)
+                                                        Set<String> platformRoles) {
+        SkillVisibility visibility = request == null || request.visibility() == null
+                ? SkillVisibility.PRIVATE
+                : SkillVisibility.valueOf(request.visibility());
+        Set<String> roles = request == null || request.platformRoles() == null
+                ? platformRoles
+                : request.platformRoles();
+        return ok("response.success.created",
+                SubmitDraftResponse.from(submitService.submit(draftId, userId, visibility, roles)));
+    }
 }
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SubmitDraftRequest.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SubmitDraftRequest.java
new file mode 100644
index 000000000..b6fe7eaff
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SubmitDraftRequest.java
@@ -0,0 +1,10 @@
+package com.iflytek.skillhub.dto;
+
+import java.util.Set;
+
+/** Request body for submitting a validated draft into the publish pipeline. */
+public record SubmitDraftRequest(
+        String visibility,
+        Set<String> platformRoles
+) {
+}
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SubmitDraftResponse.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SubmitDraftResponse.java
new file mode 100644
index 000000000..ebaaf9823
--- /dev/null
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/dto/SubmitDraftResponse.java
@@ -0,0 +1,17 @@
+package com.iflytek.skillhub.dto;
+
+import com.iflytek.skillhub.domain.authoring.service.DraftSubmitService;
+
+/** Outcome of submitting a validated draft: the published skill version coordinates. */
+public record SubmitDraftResponse(
+        Long skillId,
+        Long versionId,
+        String slug,
+        String version
+) {
+
+    public static SubmitDraftResponse from(DraftSubmitService.SubmitOutcome outcome) {
+        return new SubmitDraftResponse(
+                outcome.skillId(), outcome.versionId(), outcome.slug(), outcome.version());
+    }
+}
diff --git a/server/skillhub-app/src/main/resources/messages.properties b/server/skillhub-app/src/main/resources/messages.properties
index 78f02d6bb..c40961d7f 100644
--- a/server/skillhub-app/src/main/resources/messages.properties
+++ b/server/skillhub-app/src/main/resources/messages.properties
@@ -399,3 +399,6 @@ error.authoring.binding.notFound=No runtime binding configured for draft {0}
 error.authoring.binding.agentType.unknown=Unknown agent runtime type: {0}
 error.authoring.binding.invalid=Invalid runtime binding: {0}
 error.authoring.binding.unserializable=Runtime binding could not be serialized
+# authoring fix loop and submission
+error.authoring.submit.notValidated=Revision {0} has no passing validation run; run validation first
+error.authoring.submit.runActive=Draft {0} has an active validation run
diff --git a/server/skillhub-app/src/main/resources/messages_ru.properties b/server/skillhub-app/src/main/resources/messages_ru.properties
index 5e9b8fa14..924e13e10 100644
--- a/server/skillhub-app/src/main/resources/messages_ru.properties
+++ b/server/skillhub-app/src/main/resources/messages_ru.properties
@@ -342,3 +342,6 @@ error.authoring.binding.notFound=Для черновика {0} не настро
 error.authoring.binding.agentType.unknown=Неизвестный тип среды выполнения агента: {0}
 error.authoring.binding.invalid=Недопустимая привязка среды выполнения: {0}
 error.authoring.binding.unserializable=Привязка среды выполнения не может быть сериализована
+# authoring fix loop and submission
+error.authoring.submit.notValidated=У ревизии {0} нет пройденной задачи проверки; сначала выполните проверку
+error.authoring.submit.runActive=У черновика {0} есть активная задача проверки
diff --git a/server/skillhub-app/src/main/resources/messages_zh.properties b/server/skillhub-app/src/main/resources/messages_zh.properties
index 00b07d183..8a01d28eb 100644
--- a/server/skillhub-app/src/main/resources/messages_zh.properties
+++ b/server/skillhub-app/src/main/resources/messages_zh.properties
@@ -401,3 +401,6 @@ error.authoring.binding.notFound=草稿 {0} 尚未配置运行时绑定
 error.authoring.binding.agentType.unknown=未知的 Agent 运行时类型：{0}
 error.authoring.binding.invalid=运行时绑定不合法：{0}
 error.authoring.binding.unserializable=运行时绑定无法序列化
+# authoring fix loop and submission
+error.authoring.submit.notValidated=版本 {0} 没有通过的验证任务，请先执行验证
+error.authoring.submit.runActive=草稿 {0} 有正在进行的验证任务
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringFlowIntegrationTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringFlowIntegrationTest.java
new file mode 100644
index 000000000..6464abb16
--- /dev/null
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/authoring/AuthoringFlowIntegrationTest.java
@@ -0,0 +1,397 @@
+package com.iflytek.skillhub.authoring;
+
+import com.iflytek.skillhub.TestRedisConfig;
+import com.iflytek.skillhub.domain.authoring.SkillDraft;
+import com.iflytek.skillhub.domain.authoring.service.DraftSubmitService;
+import com.iflytek.skillhub.domain.authoring.service.FindingFixService;
+import com.iflytek.skillhub.domain.authoring.service.RuntimeBindingService;
+import com.iflytek.skillhub.domain.authoring.service.SkillDraftService;
+import com.iflytek.skillhub.domain.authoring.service.ValidationRunService;
+import com.iflytek.skillhub.domain.authoring.validation.FindingSeverity;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationFinding;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRunStatus;
+import com.iflytek.skillhub.domain.namespace.Namespace;
+import com.iflytek.skillhub.domain.namespace.NamespaceMember;
+import com.iflytek.skillhub.domain.namespace.NamespaceRepository;
+import com.iflytek.skillhub.domain.namespace.NamespaceMemberRepository;
+import com.iflytek.skillhub.domain.namespace.NamespaceRole;
+import com.iflytek.skillhub.domain.skill.SkillVisibility;
+import com.iflytek.skillhub.domain.skill.SkillVersion;
+import com.iflytek.skillhub.domain.skill.service.SkillPublishService;
+import com.iflytek.skillhub.domain.user.UserAccount;
+import com.iflytek.skillhub.domain.user.UserAccountRepository;
+import com.iflytek.skillhub.service.authoring.ValidationRunOrchestrator;
+import com.iflytek.skillhub.storage.ObjectMetadata;
+import com.iflytek.skillhub.storage.ObjectStorageService;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Import;
+import org.springframework.context.annotation.Primary;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.fail;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyBoolean;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.when;
+
+/**
+ * End-to-end authoring flow against the real service stack (Testcontainers
+ * PostgreSQL, in-memory object storage, mocked publish pipeline): create draft →
+ * edit files → bind runtime → validate (structure + config + behavior) → fix
+ * findings → re-validate → submit. Runs on real PostgreSQL because the JSONB
+ * columns must round-trip exactly as they do in production.
+ */
+@SpringBootTest
+@ActiveProfiles("test")
+@Import({TestRedisConfig.class, AuthoringFlowIntegrationTest.InMemoryStorageConfig.class})
+@Testcontainers
+class AuthoringFlowIntegrationTest {
+
+    @Container
+    private static final PostgreSQLContainer<?> POSTGRES =
+            new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @DynamicPropertySource
+    static void configurePostgres(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", POSTGRES::getJdbcUrl);
+        registry.add("spring.datasource.username", POSTGRES::getUsername);
+        registry.add("spring.datasource.password", POSTGRES::getPassword);
+        registry.add("spring.datasource.driver-class-name", () -> "org.postgresql.Driver");
+        registry.add("spring.jpa.database-platform", () -> "org.hibernate.dialect.PostgreSQLDialect");
+        registry.add("spring.flyway.enabled", () -> true);
+        registry.add("spring.jpa.hibernate.ddl-auto", () -> "validate");
+    }
+
+    private static final String USER = "author-user-1";
+    private static final String NS_SLUG = "authoring-test-ns";
+
+    @Autowired private SkillDraftService draftService;
+    @Autowired private RuntimeBindingService bindingService;
+    @Autowired private ValidationRunService runService;
+    @Autowired private DraftSubmitService submitService;
+    @Autowired private FindingFixService fixService;
+    @Autowired private ValidationRunOrchestrator orchestrator;
+    @Autowired private NamespaceRepository namespaceRepository;
+    @Autowired private NamespaceMemberRepository namespaceMemberRepository;
+    @Autowired private UserAccountRepository userAccountRepository;
+
+    @MockBean private SkillPublishService publishService;
+
+    @TestConfiguration
+    static class InMemoryStorageConfig {
+
+        @Bean
+        @Primary
+        ObjectStorageService inMemoryObjectStorage() {
+            return new InMemoryObjectStorage();
+        }
+    }
+
+    static final class InMemoryObjectStorage implements ObjectStorageService {
+        private final Map<String, byte[]> objects = new ConcurrentHashMap<>();
+
+        @Override
+        public void putObject(String key, InputStream data, long size, String contentType) {
+            try {
+                objects.put(key, data.readAllBytes());
+            } catch (Exception exception) {
+                throw new IllegalStateException(exception);
+            }
+        }
+
+        @Override
+        public InputStream getObject(String key) {
+            byte[] content = objects.get(key);
+            if (content == null) {
+                throw new IllegalArgumentException("missing object: " + key);
+            }
+            return new java.io.ByteArrayInputStream(content);
+        }
+
+        @Override
+        public void deleteObject(String key) {
+            objects.remove(key);
+        }
+
+        @Override
+        public void deleteObjects(List<String> keys) {
+            keys.forEach(objects::remove);
+        }
+
+        @Override
+        public boolean exists(String key) {
+            return objects.containsKey(key);
+        }
+
+        @Override
+        public ObjectMetadata getMetadata(String key) {
+            byte[] content = objects.get(key);
+            if (content == null) {
+                throw new IllegalArgumentException("missing object: " + key);
+            }
+            return new ObjectMetadata(content.length, "application/octet-stream", java.time.Instant.now());
+        }
+
+        @Override
+        public String generatePresignedUrl(String key, Duration expiry, String downloadFilename) {
+            return "http://localhost/" + key;
+        }
+    }
+
+    @BeforeEach
+    void setUpNamespace() {
+        if (userAccountRepository.findById(USER).isEmpty()) {
+            userAccountRepository.save(new UserAccount(USER, "Author User", "author@example.com", null));
+        }
+        if (namespaceRepository.findBySlug(NS_SLUG).isEmpty()) {
+            Namespace namespace = new Namespace(NS_SLUG, "Authoring Test", USER);
+            namespace.setStatus(com.iflytek.skillhub.domain.namespace.NamespaceStatus.ACTIVE);
+            Namespace saved = namespaceRepository.save(namespace);
+            if (namespaceMemberRepository.findByNamespaceIdAndUserId(saved.getId(), USER).isEmpty()) {
+                namespaceMemberRepository.save(new NamespaceMember(saved.getId(), USER, NamespaceRole.MEMBER));
+            }
+        }
+    }
+
+    @Test
+    void validatedDraftRunsAllLayersAndSubmits() {
+        // ---- create with scaffold
+        SkillDraft draft = draftService.createDraft(NS_SLUG, USER, "demo-flow", "summarizes documents", null);
+        assertThat(draft.getRevision()).isEqualTo(1);
+        assertThat(draftService.listFiles(draft.getId()))
+                .extracting(file -> file.getFilePath())
+                .containsExactly("SKILL.md");
+        // the scaffold bytes must be readable straight away, before any manual
+        // save — creation persists content, not just the metadata row
+        assertThat(draftService.readFile(draft.getId(), USER, "SKILL.md", null).asText())
+                .contains("name: demo-flow")
+                .contains("description: summarizes documents");
+
+        // ---- edit files: overwrite SKILL.md, add script + validation.yaml
+        draftService.saveFile(draft.getId(), USER, "SKILL.md", validSkillMd(), "text/markdown", null, null);
+        draftService.saveFile(draft.getId(), USER, "scripts/check.sh",
+                "echo 'smoke OK'\n".getBytes(StandardCharsets.UTF_8), null, null, null);
+        draftService.saveFile(draft.getId(), USER, "validation.yaml",
+                validationYaml().getBytes(StandardCharsets.UTF_8), null, null, null);
+        assertThat(draftService.getDraft(draft.getId()).getRevision()).isEqualTo(4);
+
+        // ---- bind runtime: local script execution
+        bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null, null, null);
+
+        // ---- validate: all three layers
+        ValidationRun run = runService.startRun(draft.getId(), USER, null);
+        orchestrator.submit(run.getId());
+        ValidationRun finished = awaitTerminal(run.getId());
+
+        assertThat(finished.getStatus()).isEqualTo(ValidationRunStatus.SUCCEEDED);
+        assertThat(finished.getErrorCount()).isZero();
+        assertThat(runService.listFindings(run.getId())).isEmpty();
+        assertThat(runService.listEvents(run.getId(), null))
+                .extracting(event -> event.getEventType().name())
+                .contains("RUN_STARTED", "PHASE_STARTED", "TOOL_CALL", "LOG", "RUN_FINISHED");
+
+        // ---- draft is validated for this revision
+        SkillDraft validated = draftService.getDraft(draft.getId());
+        assertThat(validated.isCurrentRevisionValidated()).isTrue();
+        assertThat(validated.getValidatedRevision()).isEqualTo(validated.getRevision());
+
+        // ---- submit into the (mocked) publish pipeline
+        SkillVersion publishedVersion = new SkillVersion(99L, "1.0.0", USER);
+        when(publishService.publishFromEntries(eq(NS_SLUG), any(), eq(USER),
+                eq(SkillVisibility.PRIVATE), any(), anyBoolean()))
+                .thenReturn(new SkillPublishService.PublishResult(99L, "demo-flow", publishedVersion));
+
+        DraftSubmitService.SubmitOutcome outcome = submitService.submit(
+                draft.getId(), USER, SkillVisibility.PRIVATE, null);
+
+        assertThat(outcome.skillId()).isEqualTo(99L);
+        assertThat(outcome.version()).isEqualTo("1.0.0");
+        assertThat(draftService.getDraft(draft.getId()).getSubmittedSkillId()).isEqualTo(99L);
+    }
+
+    @Test
+    void brokenFrontmatterProducesFixableFindingAndRevalidationLoop() {
+        SkillDraft draft = draftService.createDraft(NS_SLUG, USER, "broken-flow", null, null);
+        // SKILL.md without the required description field
+        draftService.saveFile(draft.getId(), USER, "SKILL.md",
+                "---\nname: broken-flow\n---\n\n# Broken\n".getBytes(StandardCharsets.UTF_8),
+                "text/markdown", null, null);
+
+        ValidationRun run = runService.startRun(draft.getId(), USER, null);
+        orchestrator.submit(run.getId());
+        awaitTerminal(run.getId());
+
+        List<ValidationFinding> findings = runService.listFindings(run.getId());
+        assertThat(findings).isNotEmpty();
+        Optional<ValidationFinding> missingField = findings.stream()
+                .filter(finding -> "FRONTMATTER_FIELD_MISSING".equals(finding.getRuleCode()))
+                .findFirst();
+        assertThat(missingField).isPresent();
+        assertThat(missingField.get().getSeverity()).isEqualTo(FindingSeverity.ERROR);
+        assertThat(missingField.get().hasSuggestion()).isTrue();
+        assertThat(runService.getRun(run.getId()).getStatus()).isEqualTo(ValidationRunStatus.FAILED);
+
+        // ---- apply the suggested fix
+        int revisionBefore = draftService.getDraft(draft.getId()).getRevision();
+        FindingFixService.FixOutcome outcome = fixService.applyFix(
+                missingField.get().getId(), USER, null);
+        assertThat(outcome.finding().getStatus().name()).isEqualTo("APPLIED");
+        assertThat(outcome.draft().getRevision()).isGreaterThan(revisionBefore);
+
+        // ---- validation verdict is invalidated by the new revision
+        SkillDraft fixed = draftService.getDraft(draft.getId());
+        assertThat(fixed.isCurrentRevisionValidated()).isFalse();
+
+        // ---- re-validate: now the description field exists and the run passes
+        ValidationRun second = runService.startRun(draft.getId(), USER, null);
+        orchestrator.submit(second.getId());
+        ValidationRun finishedSecond = awaitTerminal(second.getId());
+
+        assertThat(finishedSecond.getStatus()).isEqualTo(ValidationRunStatus.SUCCEEDED);
+        assertThat(draftService.getDraft(draft.getId()).isCurrentRevisionValidated()).isTrue();
+    }
+
+    @Test
+    void deadMcpServerFailsTheRunWithoutValidationYaml() {
+        // no validation.yaml on purpose: the config layer must still check the
+        // runtime binding — a declared MCP server that cannot be reached is a
+        // config error even when the behavior layer has no tasks to run
+        SkillDraft draft = draftService.createDraft(NS_SLUG, USER, "mcp-probe-flow",
+                "declares a dead MCP server", null);
+        draftService.saveFile(draft.getId(), USER, "SKILL.md", validSkillMd(), "text/markdown", null, null);
+
+        bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null,
+                List.of(Map.of("name", "dead-server", "transport", "http",
+                        "endpoint", "http://127.0.0.1:9/mcp")), null);
+
+        ValidationRun run = runService.startRun(draft.getId(), USER, null);
+        orchestrator.submit(run.getId());
+        ValidationRun finished = awaitTerminal(run.getId());
+
+        assertThat(finished.getStatus()).isEqualTo(ValidationRunStatus.FAILED);
+        assertThat(runService.listFindings(run.getId()))
+                .extracting(ValidationFinding::getRuleCode)
+                .contains("SPEC_MISSING", "MCP_CONNECT_FAILED");
+    }
+
+    @Test
+    void securityPolicyRejectsUnsafeBindingsAtSaveTime() {
+        SkillDraft draft = draftService.createDraft(NS_SLUG, USER, "security-flow",
+                "exercises the binding security policy", null);
+        draftService.saveFile(draft.getId(), USER, "SKILL.md", validSkillMd(), "text/markdown", null, null);
+
+        // cloud metadata endpoints are always blocked — even under the test
+        // profile where loopback/RFC1918 endpoints are deliberately allowed
+        assertBindingRejected(() -> bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null,
+                List.of(Map.of("name", "metadata", "transport", "http",
+                        "endpoint", "http://169.254.169.254/latest/meta-data/")), null),
+                "link-local");
+
+        // envRefs outside the configured allowlist are rejected: bindings must
+        // not be able to read arbitrary server environment variables
+        assertBindingRejected(() -> bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null,
+                List.of(Map.of("name", "env-hog", "transport", "http",
+                        "endpoint", "http://127.0.0.1:9/mcp",
+                        "envRefs", List.of("HOME"))), null),
+                "env-allowlist");
+
+        // the LLM surface is guarded too — those requests carry the server API key
+        assertBindingRejected(() -> bindingService.saveBinding(draft.getId(), USER, "openai-compatible",
+                Map.of("endpoint", "http://169.254.169.254/v1", "model", "test-model"), null, null, null),
+                "link-local");
+
+        // the allowlisted env ref saves fine (loopback is allowed under the test profile)
+        bindingService.saveBinding(draft.getId(), USER, "local-script",
+                Map.of("interpreter", "sh"), null,
+                List.of(Map.of("name", "env-ok", "transport", "http",
+                        "endpoint", "http://127.0.0.1:9/mcp",
+                        "envRefs", List.of("TEST_ALLOWED_MCP_VAR"))), null);
+    }
+
+    // ---------------------------------------------------------------- helpers
+
+    /** Save-time rejection: a 400 whose first message arg explains the reason. */
+    private static void assertBindingRejected(Runnable save, String reasonFragment) {
+        try {
+            save.run();
+            fail("binding save should have been rejected: " + reasonFragment);
+        } catch (com.iflytek.skillhub.domain.shared.exception.DomainBadRequestException exception) {
+            assertThat(String.valueOf(exception.messageArgs()[0])).contains(reasonFragment);
+        }
+    }
+
+    private ValidationRun awaitTerminal(Long runId) {
+        long deadline = System.currentTimeMillis() + 60_000;
+        while (System.currentTimeMillis() < deadline) {
+            if (runService.getRun(runId).getStatus().isTerminal()) {
+                return runService.getRun(runId);
+            }
+            try {
+                Thread.sleep(200);
+            } catch (InterruptedException exception) {
+                Thread.currentThread().interrupt();
+                fail("interrupted while waiting for the validation run to finish");
+            }
+        }
+        fail("validation run " + runId + " did not reach a terminal state in time");
+        return null;
+    }
+
+    private static byte[] validSkillMd() {
+        return """
+                ---
+                name: demo-flow
+                description: summarizes documents for the demo
+                ---
+
+                # Demo flow
+
+                ## Overview
+
+                summarizes documents for the demo
+                """.getBytes(StandardCharsets.UTF_8);
+    }
+
+    private static String validationYaml() {
+        return """
+                version: 1
+                tasks:
+                  - name: smoke
+                    description: script runs and prints OK
+                    type: script
+                    script: scripts/check.sh
+                    args: []
+                    timeoutMs: 10000
+                    assertions:
+                      - type: exit_code
+                        equals: 0
+                      - type: stdout_contains
+                        value: smoke OK
+                """;
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/DraftSubmitService.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/DraftSubmitService.java
new file mode 100644
index 000000000..7d74b8f73
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/DraftSubmitService.java
@@ -0,0 +1,94 @@
+package com.iflytek.skillhub.domain.authoring.service;
+
+import com.iflytek.skillhub.domain.authoring.SkillDraft;
+import com.iflytek.skillhub.domain.authoring.SkillDraftRepository;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRunStatus;
+import com.iflytek.skillhub.domain.shared.exception.DomainConflictException;
+import com.iflytek.skillhub.domain.shared.exception.DomainNotFoundException;
+import com.iflytek.skillhub.domain.skill.SkillVisibility;
+import com.iflytek.skillhub.domain.skill.service.SkillPublishService;
+import com.iflytek.skillhub.domain.skill.validation.PackageEntry;
+import java.time.Clock;
+import java.util.Set;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Submits a validated draft into the existing SkillHub publish pipeline. The gate is
+ * strict: the draft's current revision must be bound to a validation run that
+ * succeeded with zero errors, so content can never be published without the exact
+ * bytes that were validated. Publishing reuses {@link SkillPublishService}, which
+ * re-validates the package, triggers the security scan, and opens the review flow.
+ */
+@Service
+public class DraftSubmitService {
+
+    private static final Logger log = LoggerFactory.getLogger(DraftSubmitService.class);
+    private static final String SUPER_ADMIN = "SUPER_ADMIN";
+
+    public record SubmitOutcome(Long skillId, Long versionId, String slug, String version,
+                                SkillPublishService.PublishResult publishResult) {}
+
+    private final SkillDraftRepository draftRepository;
+    private final SkillDraftService draftService;
+    private final ValidationRunService runService;
+    private final SkillPublishService publishService;
+    private final Clock clock;
+
+    public DraftSubmitService(SkillDraftRepository draftRepository,
+                              SkillDraftService draftService,
+                              ValidationRunService runService,
+                              SkillPublishService publishService,
+                              Clock clock) {
+        this.draftRepository = draftRepository;
+        this.draftService = draftService;
+        this.runService = runService;
+        this.publishService = publishService;
+        this.clock = clock;
+    }
+
+    /**
+     * Publishes the draft's current revision as a new skill version. Warnings that the
+     * validation run already surfaced to the author are confirmed here; errors were a
+     * hard gate and cannot reach this point.
+     */
+    @Transactional
+    public SubmitOutcome submit(Long draftId, String userId, SkillVisibility visibility,
+                                Set<String> platformRoles) {
+        SkillDraft draft = draftRepository.findById(draftId)
+                .orElseThrow(() -> new DomainNotFoundException("error.authoring.draft.notFound", draftId));
+        assertOwner(draft, userId, platformRoles);
+
+        if (runService.listRuns(draftId).stream().anyMatch(ValidationRun::isActive)) {
+            throw new DomainConflictException("error.authoring.submit.runActive", draftId);
+        }
+        ValidationRun passingRun = runService.requirePassingRunForRevision(
+                draftId, draft.getRevision());
+
+        String namespaceSlug = draftService.resolveNamespaceSlug(draft);
+        java.util.List<PackageEntry> entries = draftService.materializeEntries(draftId);
+
+        SkillPublishService.PublishResult result = publishService.publishFromEntries(
+                namespaceSlug, entries, userId, visibility, platformRoles, true);
+
+        draft.markSubmitted(result.skillId(), result.version().getId(), clock.instant());
+        draftRepository.save(draft);
+        log.info("Draft {} revision {} submitted as skill {} version {} (validation run {})",
+                draftId, draft.getRevision(), result.skillId(),
+                result.version().getVersion(), passingRun.getId());
+        return new SubmitOutcome(result.skillId(), result.version().getId(), result.slug(),
+                result.version().getVersion(), result);
+    }
+
+    private void assertOwner(SkillDraft draft, String userId, Set<String> platformRoles) {
+        if (draft.getOwnerId().equals(userId)
+                || (platformRoles != null && platformRoles.contains(SUPER_ADMIN))) {
+            return;
+        }
+        throw new com.iflytek.skillhub.domain.shared.exception.DomainForbiddenException(
+                "error.authoring.draft.forbidden", draft.getId());
+    }
+}
diff --git a/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/FindingFixService.java b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/FindingFixService.java
new file mode 100644
index 000000000..8bc9a2c57
--- /dev/null
+++ b/server/skillhub-domain/src/main/java/com/iflytek/skillhub/domain/authoring/service/FindingFixService.java
@@ -0,0 +1,94 @@
+package com.iflytek.skillhub.domain.authoring.service;
+
+import com.iflytek.skillhub.domain.authoring.SkillDraft;
+import com.iflytek.skillhub.domain.authoring.SkillDraftRepository;
+import com.iflytek.skillhub.domain.authoring.validation.FindingStatus;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationFinding;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationFindingRepository;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
+import com.iflytek.skillhub.domain.authoring.validation.ValidationRunRepository;
+import com.iflytek.skillhub.domain.shared.exception.DomainBadRequestException;
+import com.iflytek.skillhub.domain.shared.exception.DomainConflictException;
+import com.iflytek.skillhub.domain.shared.exception.DomainForbiddenException;
+import com.iflytek.skillhub.domain.shared.exception.DomainNotFoundException;
+import java.util.Set;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+/**
+ * Closes the fix loop for validation findings: an author previews a finding's
+ * machine-applicable suggestion, then confirms it. Applying the patch produces a new
+ * draft revision through {@link SkillDraftService#applyPatch} (which re-validates all
+ * sha256 guards), marks the finding APPLIED, and thereby invalidates the previous
+ * validation verdict — re-validation is always required afterwards.
+ */
+@Service
+public class FindingFixService {
+
+    private static final String SUPER_ADMIN = "SUPER_ADMIN";
+
+    private final ValidationFindingRepository findingRepository;
+    private final ValidationRunRepository runRepository;
+    private final SkillDraftRepository draftRepository;
+    private final SkillDraftService draftService;
+
+    public FindingFixService(ValidationFindingRepository findingRepository,
+                             ValidationRunRepository runRepository,
+                             SkillDraftRepository draftRepository,
+                             SkillDraftService draftService) {
+        this.findingRepository = findingRepository;
+        this.runRepository = runRepository;
+        this.draftRepository = draftRepository;
+        this.draftService = draftService;
+    }
+
+    public record FixOutcome(ValidationFinding finding, SkillDraft draft) {}
+
+    /**
+     * Applies the finding's fix suggestion to the draft. The whole operation is atomic:
+     * either every patch lands and the finding is marked APPLIED, or nothing changes.
+     */
+    @Transactional
+    public FixOutcome applyFix(Long findingId, String userId, Set<String> platformRoles) {
+        OwnedFinding owned = loadOwnedFinding(findingId, userId, platformRoles);
+        ValidationFinding finding = owned.finding();
+        if (!finding.hasSuggestion()) {
+            throw new DomainBadRequestException("error.authoring.finding.noSuggestion", findingId);
+        }
+        if (finding.getStatus() == FindingStatus.APPLIED) {
+            throw new DomainConflictException("error.authoring.finding.applied", findingId);
+        }
+
+        SkillDraft draft = draftService.applyPatch(
+                owned.draftId(), userId, finding.getSuggestion().safePatches(), null, platformRoles);
+        finding.markApplied(draft.getRevision());
+        findingRepository.save(finding);
+        return new FixOutcome(finding, draft);
+    }
+
+    /** Dismisses a finding the author considers not applicable. */
+    @Transactional
+    public ValidationFinding dismissFinding(Long findingId, String userId, Set<String> platformRoles) {
+        ValidationFinding finding = loadOwnedFinding(findingId, userId, platformRoles).finding();
+        finding.markDismissed();
+        return findingRepository.save(finding);
+    }
+
+    private record OwnedFinding(ValidationFinding finding, Long draftId) {}
+
+    private OwnedFinding loadOwnedFinding(Long findingId, String userId, Set<String> platformRoles) {
+        ValidationFinding finding = findingRepository.findById(findingId)
+                .orElseThrow(() -> new DomainNotFoundException("error.authoring.finding.notFound", findingId));
+        ValidationRun run = runRepository.findById(finding.getRunId())
+                .orElseThrow(() -> new DomainNotFoundException(
+                        "error.authoring.run.notFound", finding.getRunId()));
+        SkillDraft draft = draftRepository.findById(run.getDraftId())
+                .orElseThrow(() -> new DomainNotFoundException(
+                        "error.authoring.draft.notFound", run.getDraftId()));
+        if (draft.getOwnerId().equals(userId)
+                || (platformRoles != null && platformRoles.contains(SUPER_ADMIN))) {
+            return new OwnedFinding(finding, draft.getId());
+        }
+        throw new DomainForbiddenException("error.authoring.draft.forbidden", draft.getId());
+    }
+}

From 43a0788ba23aa20cd29f60dc08f29e2039304b4b Mon Sep 17 00:00:00 2001
From: zjncs <18910855655@163.com>
Date: Mon, 12 Oct 2026 11:27:30 +0800
Subject: [PATCH 17/17] chore(authoring): regenerate the API schema for the
 fix/publish layer

Adds the finding apply/dismiss and draft submit endpoints on top of the
runtime-layer schema.

Signed-off-by: zjncs <18910855655@163.com>
---
 web/src/api/generated/schema.d.ts | 332 +++++++++++++++++++++++++++---
 1 file changed, 304 insertions(+), 28 deletions(-)

diff --git a/web/src/api/generated/schema.d.ts b/web/src/api/generated/schema.d.ts
index 527ef414c..45bf3a116 100644
--- a/web/src/api/generated/schema.d.ts
+++ b/web/src/api/generated/schema.d.ts
@@ -2837,6 +2837,74 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/authoring/runs/{runId}/findings/{findingId}/dismiss": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Dismiss a finding as not applicable */
+        post: operations["dismissFindingFix"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/web/authoring/runs/{runId}/findings/{findingId}/dismiss": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Dismiss a finding as not applicable */
+        post: operations["dismissFindingFix_1"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/web/authoring/runs/{runId}/findings/{findingId}/apply": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Apply a finding's fix suggestion to the draft */
+        post: operations["applyFindingFix"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/authoring/runs/{runId}/findings/{findingId}/apply": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Apply a finding's fix suggestion to the draft */
+        post: operations["applyFindingFix_1"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/authoring/runs/{runId}/cancel": {
         parameters: {
             query?: never;
@@ -2871,6 +2939,40 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/web/authoring/drafts/{draftId}/submit": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Submit a validated draft into the publish pipeline */
+        post: operations["submitValidatedDraft"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/v1/authoring/drafts/{draftId}/submit": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Submit a validated draft into the publish pipeline */
+        post: operations["submitValidatedDraft_1"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/authoring/drafts/{draftId}/runs": {
         parameters: {
             query?: never;
@@ -8517,6 +8619,43 @@ export interface components {
             createdAt?: string;
             readAt?: string;
         };
+        ApiResponseValidationFindingResponse: {
+            /** Format: int32 */
+            code?: number;
+            msg?: string;
+            data?: components["schemas"]["ValidationFindingResponse"];
+            /** Format: date-time */
+            timestamp?: string;
+            requestId?: string;
+        };
+        FilePatch: {
+            filePath?: string;
+            oldSha256?: string;
+            oldValue?: string;
+            newValue?: string;
+        };
+        FixSuggestion: {
+            patches?: components["schemas"]["FilePatch"][];
+            description?: string;
+        };
+        ValidationFindingResponse: {
+            /** Format: int64 */
+            id?: number;
+            /** Format: int64 */
+            runId?: number;
+            layer?: string;
+            ruleCode?: string;
+            severity?: string;
+            filePath?: string;
+            location?: string;
+            message?: string;
+            suggestion?: components["schemas"]["FixSuggestion"];
+            status?: string;
+            /** Format: int32 */
+            appliedRevision?: number;
+            /** Format: date-time */
+            createdAt?: string;
+        };
         ApiResponseValidationRunResponse: {
             /** Format: int32 */
             code?: number;
@@ -8552,6 +8691,27 @@ export interface components {
                 [key: string]: Record<string, never>;
             };
         };
+        SubmitDraftRequest: {
+            visibility?: string;
+            platformRoles?: string[];
+        };
+        ApiResponseSubmitDraftResponse: {
+            /** Format: int32 */
+            code?: number;
+            msg?: string;
+            data?: components["schemas"]["SubmitDraftResponse"];
+            /** Format: date-time */
+            timestamp?: string;
+            requestId?: string;
+        };
+        SubmitDraftResponse: {
+            /** Format: int64 */
+            skillId?: number;
+            /** Format: int64 */
+            versionId?: number;
+            slug?: string;
+            version?: string;
+        };
         CreateDraftRequest: {
             namespaceSlug: string;
             name: string;
@@ -10359,34 +10519,6 @@ export interface components {
             timestamp?: string;
             requestId?: string;
         };
-        FilePatch: {
-            filePath?: string;
-            oldSha256?: string;
-            oldValue?: string;
-            newValue?: string;
-        };
-        FixSuggestion: {
-            patches?: components["schemas"]["FilePatch"][];
-            description?: string;
-        };
-        ValidationFindingResponse: {
-            /** Format: int64 */
-            id?: number;
-            /** Format: int64 */
-            runId?: number;
-            layer?: string;
-            ruleCode?: string;
-            severity?: string;
-            filePath?: string;
-            location?: string;
-            message?: string;
-            suggestion?: components["schemas"]["FixSuggestion"];
-            status?: string;
-            /** Format: int32 */
-            appliedRevision?: number;
-            /** Format: date-time */
-            createdAt?: string;
-        };
         SseEmitter: {
             /** Format: int64 */
             timeout?: number;
@@ -17342,6 +17474,98 @@ export interface operations {
             };
         };
     };
+    dismissFindingFix: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                runId: number;
+                findingId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["ApiResponseValidationFindingResponse"];
+                };
+            };
+        };
+    };
+    dismissFindingFix_1: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                runId: number;
+                findingId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["ApiResponseValidationFindingResponse"];
+                };
+            };
+        };
+    };
+    applyFindingFix: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                runId: number;
+                findingId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["ApiResponseValidationFindingResponse"];
+                };
+            };
+        };
+    };
+    applyFindingFix_1: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                runId: number;
+                findingId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["ApiResponseValidationFindingResponse"];
+                };
+            };
+        };
+    };
     cancelValidationRun: {
         parameters: {
             query?: never;
@@ -17386,6 +17610,58 @@ export interface operations {
             };
         };
     };
+    submitValidatedDraft: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                draftId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["SubmitDraftRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["ApiResponseSubmitDraftResponse"];
+                };
+            };
+        };
+    };
+    submitValidatedDraft_1: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                draftId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["SubmitDraftRequest"];
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "*/*": components["schemas"]["ApiResponseSubmitDraftResponse"];
+                };
+            };
+        };
+    };
     listValidationRuns: {
         parameters: {
             query?: never;