This commit is contained in:
Zhao Jianing 2026-09-23 16:04:42 +08:00 • committed by GitHub
commit dcb5e0ac14
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
147 changed files with 16590 additions and 12 deletions

View file

@ -5,16 +5,18 @@ DEV_SERVER_PID := $(DEV_DIR)/server.pid
DEV_WEB_PID := $(DEV_DIR)/web.pid
DEV_SERVER_LOG := $(DEV_DIR)/server.log
DEV_WEB_LOG := $(DEV_DIR)/web.log
DEV_WEB_URL := http://localhost:3000
DEV_WEB_PORT ?= 3000
DEV_WEB_URL := http://localhost:$(DEV_WEB_PORT)
DEV_WEB_HOST ?= 127.0.0.1
DEV_API_URL := http://localhost:8080
DEV_API_PORT ?= 8080
DEV_API_URL := http://localhost:$(DEV_API_PORT)
DEV_SCANNER_URL := http://localhost:8000
STAGING_API_URL := http://localhost:8080
STAGING_WEB_URL := http://localhost
STAGING_SERVER_IMAGE := skillhub-server:staging
DEV_PROCESS := bash scripts/dev-process.sh
DEV_SERVER_PREPARE := true
DEV_SERVER_CMD := ./scripts/run-dev-app.sh
DEV_SERVER_CMD := ./scripts/run-dev-app.sh --server.port=$(DEV_API_PORT)
DEV_SERVER_SCANNER_ENV := SKILLHUB_SECURITY_SCANNER_ENABLED=true SKILLHUB_SECURITY_SCANNER_URL=$(DEV_SCANNER_URL) SKILLHUB_SECURITY_SCANNER_MODE=upload
BACKEND_TEST_JAVA_OPTIONS ?= -XX:+EnableDynamicAgentLoading
PARALLEL_BASE_REF ?= origin/main
@ -49,7 +51,7 @@ dev-all: ## 一键启动本地开发环境(依赖 + scanner + 后端 + 前端
echo "Frontend already running with PID $$(cat $(DEV_WEB_PID))"; \
else \
echo "Starting frontend..."; \
$(DEV_PROCESS) start --pid-file $(DEV_WEB_PID) --log-file $(DEV_WEB_LOG) --cwd web -- pnpm exec vite --host $(DEV_WEB_HOST) --strictPort >/dev/null; \
$(DEV_PROCESS) start --pid-file $(DEV_WEB_PID) --log-file $(DEV_WEB_LOG) --cwd web -- env VITE_API_PROXY_TARGET=$(DEV_API_URL) pnpm exec vite --host $(DEV_WEB_HOST) --port $(DEV_WEB_PORT) --strictPort >/dev/null; \
fi
@echo "Waiting for backend on $(DEV_API_URL) ..."
@backend_ready=0; \
@ -250,7 +252,7 @@ web-install-ci: ## 以 CI 方式安装前端依赖
cd web && CI=true pnpm install --frozen-lockfile
dev-web: ## 启动前端开发服务器
cd web && pnpm exec vite --host $(DEV_WEB_HOST)
cd web && VITE_API_PROXY_TARGET=$(DEV_API_URL) pnpm exec vite --host $(DEV_WEB_HOST) --port $(DEV_WEB_PORT)
build-frontend: web-deps ## 构建前端
cd web && pnpm run build

View file

@ -0,0 +1,337 @@
# Skill 创作与验证平台设计、部署与测试
## 定位
Skill 创作与验证平台让作者在 SkillHub 内完成 Skill 的**创建、编辑、受控验证和提交发布**,
而不是在仓库外部手工打包再上传。核心闭环是:
```text
创建草稿 → 编辑 SKILL.md/资源文件 → 绑定 Agent/工具/MCP 运行时
→ 三层验证(结构/配置/行为,含日志与调用轨迹)
→ 定位失败步骤 → 应用修复建议 → 复验
→ 达标草稿提交,复用既有扫描/审核/发布管线
```
平台不引入第二套发布通道:提交动作直接复用 `SkillPublishService`,草稿只是把
"写一个符合规范的 Skill" 变成了带验证门槛的结构化流程。
## 整体架构
```text
web/ React 工作台
pages/authoring/drafts.tsx 草稿列表 + 创建
pages/authoring/draft-detail.tsx 文件/运行时/运行记录三个标签页
pages/authoring/run-detail.tsx 运行详情:事件控制台 + 发现列表
features/authoring/… SSE hook、事件合并、diff 预览、发现卡片
│ REST + SSE
▼
skillhub-app
controller/SkillAuthoringController 19 个 REST 端点
controller/ValidationStreamController SSE 事件流(回放 + 直播)
service/authoring/ValidationRunOrchestrator 编排三层验证、事件、终态
service/authoring/adapter/* LocalScript(inline/docker)/ OpenAiCompatible 运行时适配器
service/authoring/mcp/* MCP 客户端(http/sse/stdio)与配置层连通探测
service/authoring/ValidationEventBroadcaster SSE 广播
▼
skillhub-domain
authoring/ SkillDraft、DraftFile、RuntimeBinding 实体与服务
authoring/validation ValidationRun / ValidationEvent / ValidationFinding
authoring/spec validation.yaml 解析(防御式 SnakeYAML)
authoring/runtime 任务执行结果与断言求值器
skill/validation/ SkillPackagePolicy(结构规则与发布侧共享,规则不漂移)
▼
skillhub-storage 草稿文件按内容寻址存入对象存储(与 Skill 包同机制)
```
## 领域模型与数据表
迁移 `V66__authoring_platform.sql` 新增六张表(初稿编号 V60,因上游 #874 统一身份
平台占用了 V60–V65,rebase 后顺延为 V66):
| 表 | 职责 |
| --- | --- |
| `skill_draft` | 草稿元数据:归属人、名称、`revision`(每次内容变更 +1)、`contentDigest`、`validatedRevision`/`validatedRunId`、提交回填的 `submittedSkillId` |
| `draft_file` | 草稿内单个文件(路径、内容类型、对象存储 key、sha256) |
| `runtime_binding` | Agent 类型 + 适配器配置 + 工具白名单 + MCP 服务器声明(JSONB) |
| `validation_run` | 一次验证运行的快照:draft revision、状态、各层统计 |
| `validation_event` | 运行事件(日志、工具调用、阶段切换),`seq` 单调递增,供 SSE 回放 |
| `validation_finding` | 结构化发现:层级、规则码、严重度、`filePath`/位置、建议(JSONB) |
关键不变量:
- **乐观并发**:草稿保存文件带 `expectedRevision`,冲突返回 409,前端提示刷新后重试。
- **验证即快照**:运行绑定启动时的 revision;`SUCCEEDED` 且 0 错误时回写
`validatedRevision`。提交门槛是"当前 revision 必须恰好等于 `validatedRevision`",
验证通过后再改动文件会自动失去提交资格,必须复验。
- **运行状态机**:`QUEUED → PREPARING → RUNNING → SUCCEEDED / FAILED / CANCELLED / TIMED_OUT`;
活跃运行支持协作式取消,超时由任务级 `timeoutMs` 与运行级 `run-timeout-ms` 双层控制,
崩溃残留的活跃运行由维护任务按 `stale-run-minutes` 清扫为 `TIMED_OUT`。
## 三层验证流水线
`ValidationRunOrchestrator` 顺序执行三层,每层产出结构化发现而非异常字符串:
1. **STRUCTURE(结构)**:`DraftStructureValidator` 检查包布局、路径合法性与去重、
扩展名白名单、内容与扩展名一致性、文件数与体积上限、SKILL.md frontmatter
必填字段(name、description)。规则全部来自 `SkillPackagePolicy`,与发布侧
校验逐条对齐,草稿期能过的包到发布期不会再因结构被拒。
2. **CONFIG(配置)**:`RuntimeBindingValidator` 校验 Agent 类型(`local-script` /
`openai-compatible`)、解释器白名单(`sh/bash/python3/node`)、工具白名单与
MCP 声明(名称、transport、endpoint/command、工具过滤、env 引用),并扫描
绑定中任何凭据形态的字段(`CREDENTIAL_EMBEDDED`)——密钥只能存服务端配置。
同时对 validation.yaml 的全部断言做语法预检(类型合法、必填参数齐全、正则可编译),
让错误在执行前暴露。声明的 MCP 服务器随后被**真实探测**:逐台连接、完成
initialize 握手并 tools/list——连不上记 `MCP_CONNECT_FAILED` 错误(行为层
因此被阻断),`toolFilters` 引用服务器未提供的工具记 `MCP_TOOL_FILTER_UNKNOWN`
告警,连接成功则在事件流留下工具清单日志。MCP 声明由此从"格式正确"变成
"验证时确实可用"。
3. **BEHAVIOR(行为)**:把草稿文件物化进一次性隔离工作区,按 validation.yaml
逐任务执行(script 任务跑 `scripts/` 下的脚本,prompt 任务走 LLM 适配器),
用 `AssertionEvaluator` 求值断言:`exit_code`、`stdout_contains`、`stdout_matches`、
`stdout_json`(JSON Pointer 等值)、`artifact_exists`(可附 sha256)、
`tool_call_count`,以及 prompt 侧的 `response_*` 系列。行为被真实执行验证,
而不是靠元数据推断。
### 受控执行环境
`LocalScriptRuntimeAdapter` 是行为层默认运行时,有两种执行后端
(`local-script.execution-mode`):
- **inline**(默认,本地开发):脚本在服务器主机上以子进程执行。安全基线:
每次运行独立临时工作区(`workspace-root` 下),脚本路径归一化后必须落在
工作区内,越界路径直接拒绝;进程环境被清空,只保留 `PATH`、`HOME`
(指向工作区)、`LANG`,外加绑定 `envAllowlist` 中显式点名的变量;
stdout/stderr 逐行流入事件流(作者实时可见),同时进入 256KB 截断缓冲用于
发现;解释器白名单外的命令不可执行;任务超时或运行取消时强制销毁进程。
- **docker**(生产推荐):同一套脚本在锁定的容器内执行——`--network none`
(容器内无任何网络路由)、`--memory`/`--cpus`/`--pids-limit` 资源上限、
只读根文件系统(`--read-only`,工作区读写挂载到 `/workspace`、`/tmp` 为
限量 tmpfs)、`--cap-drop ALL` + `--security-opt no-new-privileges`、日志
驱动关闭。容器按运行标识命名,超时/取消时强制删除;Docker 不可用时该后端
报告不可用而不会静默回退。隔离效果由真实容器内的行为测试实证
(`DockerScriptRuntimeAdapterTest`:路由表为空、根文件系统只读、工作区可写)。
`OpenAiCompatibleRuntimeAdapter` 处理 prompt 任务,是带工具执行的 agent 循环:
endpoint/model 来自绑定,API key 只从服务端
`skillhub.authoring.openai-compatible.api-key` 解析,默认关闭。任务开始时连接
绑定声明的每台 MCP 服务器并 tools/list,工具经服务器 `toolFilters` 与绑定全局
`toolAllowlist`(空 = 不限制;条目匹配裸工具名或 `server.tool`)双重过滤后以
function 形式暴露给模型;模型发起 tool_calls 时**真实调用**对应 MCP 服务器,
结果回填对话进入下一轮,轮数上限 `max-tool-rounds`(默认 4)。每轮对话、每次
工具调用与结果都是事件流里的 `TOOL_CALL`/`TOOL_RESULT` 记录,`tool_call_count`
断言统计实际执行的工具调用数。
### 事件流(日志与调用轨迹)
每个动作都是一条持久化事件:运行启停、阶段切换、任务工具调用(TOOL_CALL,含
命令与参数)、任务结果、stdout/stderr 逐行日志、断言通过摘要。事件带单调 `seq`,
SSE 端点 `/api/web/authoring/runs/{runId}/events/stream` 支持从 `afterSeq` /
`Last-Event-ID` 回放再续播,终端运行的流会在回放后正常收尾,刷新页面不丢历史。
## 失败定位与修复建议闭环
发现(finding)携带层级、规则码、`filePath` + 位置(失败步骤定位)和可选的
`FixSuggestion`:一个或多个 `FilePatch`(文件路径、旧内容 sha256、旧值、新值)。
前端 `FindingCard` 渲染红绿 diff 预览,应用走两步确认(Apply → Confirm),后端
`FindingFixService.apply` 校验文件未被并发修改后写入补丁并推进 `revision`;
`dismiss` 记录作者已知悉。修复后一键"Fix and re-validate"复验——示例 Skill 的
实测:frontmatter 缺 `description` → `FRONTMATTER_FIELD_MISSING` 带定位与补丁 →
应用后 revision 2→3 → 复验 `SUCCEEDED`。
## 提交与发布管线衔接
`DraftSubmitService.submit` 的门槛:当前 revision 存在 0 错误的 `SUCCEEDED` 运行
(告警已由验证过程向作者展示,视为已确认)。通过后把草稿文件打包交给
`SkillPublishService`:重新校验包结构、触发安全扫描、进入既有审核流,草稿回填
`submittedSkillId`/`submittedVersionId`。也就是说验证平台产出的是"已自证行为"的
Skill 版本,扫描与审核沿用平台原有机制,没有旁路。
## API 一览
前缀 `/api/web/authoring`(同时挂 `/api/v1/authoring`):
| 端点 | 说明 |
| --- | --- |
| `POST /drafts`、`GET /drafts`、`GET/DELETE /drafts/{id}` | 草稿 CRUD(创建时生成 SKILL.md 脚手架,validation.yaml 由作者按需在工作台新建) |
| `GET /drafts/{id}/files`、`PUT /drafts/{id}/files`、`GET /drafts/{id}/files/content`、`DELETE /drafts/{id}/files` | 文件列表 / 保存(带 expectedRevision)/ 读取 / 删除 |
| `GET/PUT /drafts/{id}/runtime` | 运行时绑定读写 |
| `POST /drafts/{id}/runs`、`GET /drafts/{id}/runs` | 启动验证 / 运行历史(版本与验证记录持久化) |
| `GET /runs/{id}`、`POST /runs/{id}/cancel` | 运行详情 / 取消活跃运行 |
| `GET /runs/{id}/events`、`GET /runs/{id}/events/stream` | 事件轮询 / SSE 流 |
| `GET /runs/{id}/findings`、`POST /runs/{id}/findings/{fid}/apply`、`POST /runs/{id}/findings/{fid}/dismiss` | 发现列表 / 应用修复 / 忽略 |
| `POST /drafts/{id}/submit` | 达标草稿提交发布 |
## 前端工作台
路由(均需登录):`/dashboard/authoring`(列表)、`/dashboard/authoring/$draftId`
(文件 / 运行时 / 运行记录)、`/dashboard/authoring/$draftId/runs/$runId`(运行详情)。
- 文件编辑器支持新建/删除/保存,未保存标记 + 乐观并发冲突提示;
- 运行时表单按 Agent 类型切换字段(解释器 vs endpoint/model),工具白名单与
MCP 服务器声明有即时校验;
- 运行详情页 = 状态卡 + 自动滚动事件控制台(SSE 直播,断线 2 秒轮询降级)+
发现卡片列表;活跃运行每 2 秒轮询状态直到终态;
- 文案覆盖 en/zh/ru 三语言。
## 部署
### 配置项(`skillhub.authoring.*`,均可经环境变量覆盖)
| 配置 | 默认 | 说明 |
| --- | --- | --- |
| `workspace-root` | `${java.io.tmpdir}/skillhub-authoring` | 隔离工作区根目录(`SKILLHUB_AUTHORING_WORKSPACE_ROOT`) |
| `executor-threads` | 4 | 进程内并发验证线程数 |
| `run-timeout-ms` | 900000 | 单次运行硬上限(15 分钟) |
| `stale-run-minutes` | 30 | 崩溃恢复清扫阈值 |
| `local-script.enabled` | true | 本地脚本运行时开关 |
| `local-script.execution-mode` | **docker** | 脚本执行后端:`docker`(锁定容器,生产默认)/ `inline`(主机子进程,仅 local/dev/test profile;否则启动即失败,`SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE`) |
| `local-script.docker.image` / `memory` / `cpus` / `pids-limit` / `tmpfs-size` | alpine:3.20 / 256m / 1.0 / 128 / 64m | 容器隔离参数(`SKILLHUB_AUTHORING_DOCKER_*`);镜像需自带 Skill 用到的解释器 |
| `openai-compatible.enabled` | false | LLM 运行时开关(默认关闭) |
| `openai-compatible.api-key` | 空 | 服务端密钥,绝不写入草稿绑定 |
| `openai-compatible.default-endpoint` / `default-model` | 空 | prompt 任务的默认 LLM |
| `openai-compatible.max-tool-rounds` | 4 | 单个 prompt 任务的最大对话轮数(含 MCP 工具执行) |
| `openai-compatible.allow-private-endpoints` | false | LLM endpoint 的 SSRF 放行开关:私网 LLM(如内部 vLLM)才设 true(`SKILLHUB_AUTHORING_LLM_ALLOW_PRIVATE`) |
| `mcp.allow-private-endpoints` | false | http/sse MCP endpoint 的 SSRF 放行开关(`SKILLHUB_AUTHORING_MCP_ALLOW_PRIVATE`);链路本地/云元数据地址任何情况下都拒绝 |
| `mcp.stdio-enabled` | false | stdio MCP 传输总开关(`SKILLHUB_AUTHORING_MCP_STDIO_ENABLED`)——服务器侧进程执行,生产默认关闭 |
| `mcp.env-allowlist` | 空 | 允许 `envRefs` 引用的服务器环境变量名单(逗号分隔,`SKILLHUB_AUTHORING_MCP_ENV_ALLOWLIST`);默认空 = 全部拒绝 |
| `mcp.docker.image` / `memory` / `cpus` / `pids-limit` / `tmpfs-size` | alpine:3.20 / 256m / 1.0 / 128 / 64m | docker 模式下 stdio MCP 服务器的容器隔离参数(`SKILLHUB_AUTHORING_MCP_DOCKER_*`) |
### 部署要点
- **数据库**:Flyway 迁移 V66 自动建表,无手工步骤;JSONB 列要求 PostgreSQL
(平台既有要求,无新增)。
- **启用 prompt 任务**:配置 `SKILLHUB_AUTHORING_LLM_ENABLED=true` 并给出
endpoint/model/api-key;不启用时含 prompt 任务的草稿会得到 `RUNTIME_DISABLED`
配置层发现,script 流程不受影响。
- **启用容器隔离**:`SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE=docker` 并确保运行节点
可访问 Docker daemon。镜像需包含 Skill 用到的解释器(alpine 只带 `sh`;
python3/node 的 Skill 应换基础镜像)。脚本执行不再依赖主机环境。
- **MCP 服务器**:stdio 传输默认整体关闭(`mcp.stdio-enabled`),开启后命令在
docker 执行模式下运行于与脚本相同的锁定容器(无网络、资源上限、只读根文件
系统,关闭时强制 `docker rm -f` 清理);inline 模式仅限 local/dev/test
profile。`envRefs` 只能引用 `mcp.env-allowlist` 点名的环境变量(默认空 =
全部拒绝),这是凭据到达 MCP 服务器的唯一通道。http/sse 传输访问的
endpoint 必须通过 SSRF 策略(见下)。验证时每台声明的服务器都会被真实探测。
- **工作区**:验证运行会在 `workspace-root` 下创建一次性目录并在结束后清理,
生产环境建议独立磁盘分区并纳入监控;多实例部署时运行在工作区所在节点本地
执行,无需共享存储。
- **RISC-V64**:后端是架构无关的 Java 21 JAR,沿用 `skillhub-server` 既有
`linux/riscv64` 构建路径(见 `docs/RISCV64.md`)。local-script 运行时只依赖
容器内 POSIX 工具(`sh`、`wc` 等),Temurin 运行时镜像自带;安全扫描器的
RISC-V 限制与创作平台无关(扫描发生在提交后的发布管线)。
- **安全基线**:
- **SSRF 防护**:MCP http/sse endpoint 与 OpenAI 兼容 endpoint 在保存时、
连接时双重校验——只允许 http(s),主机必须可解析,且解析到的地址不得为
链路本地(含云元数据 169.254.169.254)、组播或未指定地址(无条件拒绝),
也不得为环回/RFC1918/ULA/CGNAT(除非对应表面的 `allow-private-endpoints`
放行)。HTTP 客户端从不跟随重定向(30x 直接报错),单响应体上限 2MiB,
stdio 单行上限 2MiB——阻断"公网 URL 302 跳元数据"与超大响应/超长行的
内存耗尽攻击。已知边界:策略在检查时解析域名,HttpClient 连接时再次解析,
可缓解但无法完全消除 DNS rebinding 竞态(绑定已校验地址的 socket 会破坏
虚拟主机 endpoint,未实现)。
- **生产强制容器**:`execution-mode` 默认 `docker`;若在非 local/dev/test
profile 下配置了 inline,应用启动即失败(`AuthoringStartupGuard`)。
- **其余既有边界**:脚本在清空环境的最小工作区执行、解释器白名单、路径
不得越界、绑定禁止内嵌凭据、单文件 10MB / 包 100MB / 500 文件上限与
发布侧一致。
### RISC-V64 验证记录(2026-09-20)
在 arm64 宿主机上用 Buildx + QEMU 对本功能构建 `linux/riscv64` 服务端镜像并完成
活体验证(对 `docs/RISCV64.md` 组件镜像边界的实测补充):
- **镜像构建**:`server/Dockerfile` 原生路径(JAR 在构建宿主侧编译,运行时基于
`eclipse-temurin:21-jre-noble` 的 riscv64 官方变体),`docker image inspect`
确认 `linux/riscv64`。
- **启动**:QEMU 模拟下 Spring Boot 91.9 秒完成启动,`/actuator/health` 返回
200;Flyway 在全新 PostgreSQL 16 上完成全部迁移(含 V66 创作平台表)。
- **创作平台全流程(REST API)**:创建草稿 → 读取脚手架 SKILL.md → 保存
`scripts/check.sh` 与 `validation.yaml` → 保存 local-script 绑定 → 启动验证 →
运行 `SUCCEEDED`(0 错误 0 警告),12 条事件完整落库且脚本 stdout 出现在事件
流中 —— 行为层的脚本子进程真实运行在 riscv64 用户态内。
- **结论**:创作与验证平台不引入任何架构相关依赖(纯 JVM 字节码 + POSIX
工具),随 `skillhub-server` 既有 `linux/riscv64` 发布路径交付即可;
`execution-mode: docker` 时基础镜像需有 riscv64 变体(默认 `alpine:3.20`
官方提供)。
- **边界**:本记录为 QEMU 模拟验证,与 CI 的 riscv64 镜像 guardrail 同级;原生
RISC-V 硬件上的全栈冒烟(PostgreSQL/Redis/对象存储/scanner)仍按
`docs/RISCV64.md` 的边界声明执行。
#### 复验脚本与原生硬件清单
上述流程已固化为 `scripts/riscv64-verify.sh`(自动识别宿主架构:riscv64 主机
原生执行,其余走 QEMU;对独立数据库跑 创建→验证→SUCCEEDED→事件流检查)。
在真实 RISC-V64 硬件或 CI runner 上完成原生验证时,除直接运行该脚本外,
按以下清单执行并留档:
1. `uname -m` 输出 `riscv64`(非 QEMU:`/proc/cpuinfo` 无 "emodel"/QEMU 标记,
且启动日志无 qemu 前缀);
2. PostgreSQL 16、Redis 7 以 riscv64 原生镜像运行(非 binfmt 转译);
3. `scripts/riscv64-verify.sh` 全部检查通过,记录 耗时 与 事件数 两个数字;
4. `execution-mode: docker` 下再跑一次(验证 alpine:3.20 riscv64 变体内的
脚本隔离执行);
5. 浏览器 E2E(`e2e/authoring-flow.spec.ts`)对准该实例跑通。
截至 2026-09-20,本项目尚无原生 RISC-V 硬件资源,上述第 1–5 项为待完成项,
已有证据为 QEMU 模拟级(见上)。
### 发布管线端到端证据(2026-09-21)
`scripts/authoring-publish-e2e.sh` 在本地 dev 栈(PostgreSQL/Redis/MinIO +
skill-scanner :8000,`local` profile)上实跑全链路并留档,16/16 检查通过:
- **创作与验证**(普通用户 `local-user`):草稿 94 → SKILL.md/`scripts/check.sh`/
`validation.yaml` → local-script 绑定 → 验证运行 `SUCCEEDED`;
- **提交 PUBLIC**:submit 返回 skill 33 / version 33 / slug
`publish-evidence-1789957612` / 版本号 `20260921.102653`,版本进入
`SCANNING`(非 SUPER_ADMIN 提交不会自动发布);
- **安全扫描**:异步完成后版本回到 `PENDING_REVIEW`,`security_audit` 落库
`SKILL_SCANNER:SAFE:1`(1 条发现、判定安全);
- **人工审核**:平台管理员(`local-admin`,SUPER_ADMIN)通过
`POST /api/web/reviews/1/approve` 批准,审核任务 `APPROVED`;
- **发布终态**:`skill_version.status = PUBLISHED`、`published_at` 已置位、
`skill.visibility = PUBLIC`,另一普通用户(`local-plain-user`)可公开检索
该 Skill,且草稿回填 `submittedSkillId = 33`。
## 测试
| 层 | 位置 | 覆盖 |
| --- | --- | --- |
| 领域单测 | `skillhub-domain/…/authoring/` | `DraftStructureValidatorTest`(结构规则与修复建议)、`ValidationSpecParserTest`(防御式 YAML 解析、任务/断言语义)、`AssertionEvaluatorTest`(全部断言类型与失败信息)、`SkillScaffoldGeneratorTest` |
| 运行时单测 | `skillhub-app/…/authoring/adapter/` | `DockerScriptCommandBuilderTest`(隔离参数与挂载构造)、`DockerScriptRuntimeAdapterTest`(真实容器内实证:无网络路由、只读根文件系统、工作区可写、输出捕获;无 Docker 时静默跳过)、`OpenAiCompatibleRuntimeAdapterToolLoopTest`(agent 循环:MCP 工具发现→模型调用→真实执行→轨迹回填,toolFilters/toolAllowlist 过滤、轮数上限) |
| MCP 单测 | `skillhub-app/…/authoring/mcp/` | `HttpMcpClientTest`(initialize/tools 握手、会话头复用、SSE 帧解析、错误结果、不可达报错、**30x 重定向不跟随、2MiB 响应上限**,对真实本地 HTTP 服务器)、`StdioMcpClientTest`(stdio 传输对 python3 子进程;**2MiB 单行上限 + 进程销毁、关闭时清理命令执行**)、`McpProbeServiceTest`(连不上→`MCP_CONNECT_FAILED`、未知 toolFilter→告警、可跳过畸形声明)、`McpClientFactoryTest`(**连接时安全策略:被拒 endpoint/被禁 stdio 不建连不建进程、envRefs 白名单过滤、docker 包装参数**) |
| 安全策略单测 | `skillhub-app/…/config/` | `ConfiguredAuthoringSecurityPolicyTest`(SSRF 地址分类:云元数据/链路本地无条件拒绝、环回/RFC1918/ULA/CGNAT 按表面开关、公网放行)、`AuthoringStartupGuardTest`(非 local/dev/test profile + inline → 启动失败) |
| 端到端集成 | `skillhub-app/…/authoring/AuthoringFlowIntegrationTest` | Testcontainers 真实 PostgreSQL 上跑通完整闭环:建草稿 → 改文件 → 绑定运行时 → 三层验证 → 修复发现 → 复验 → 提交(`ddl-auto=validate` 顺带校验 V66 与实体映射一致) |
| 前端单测 | `web/src/features/authoring/*.test.*` | 事件按 seq 合并去重、SSE 生命周期(回放合并、终态关闭、断线轮询降级)、修复 diff 预览、二进制文件 base64 处理 |
| 浏览器 E2E | `web/e2e/authoring-flow.spec.ts` | Playwright 真实 API 全 UI 闭环:创建草稿(命名空间/名称对话框)→ 文件编辑(SKILL.md/脚本/validation.yaml)→ 保存运行时绑定 → 启动验证至 Succeeded(事件控制台含脚本输出)→ 提交对话框过闸;坏 frontmatter → 失败发现 → diff 预览 → 两步确认应用修复 → 一键复验通过;二进制资源上传 → 只读面板(大小/类型/sha256)与字节级校验。断言落在持久 UI 状态(按钮态、徽章、响应体)而非易失 toast |
| 活体冒烟 | `scripts/authoring-smoke-test.sh` | 对运行中的服务器 35 项检查、四个场景:全层验证并提交;坏 frontmatter → 定位 → 应用修复 → 复验;守卫(未验证不可提交、跨用户不可读他人草稿);MCP 探测(死端点报 `MCP_CONNECT_FAILED`、本地假 MCP 服务器工具被发现并写入事件流、未知 toolFilter 仅告警),幂等可重复执行 |
| 示例 Skill | `examples/skill-authoring/` | 可直接装载的完整示例(含 4 个行为验证用例,覆盖全部 6 种 script 断言),README 给出 UI 与 API 两种装载方式 |
常用命令:
```bash
# 后端(需 Java 21;默认 JVM 24 会破坏 Mockito/ByteBuddy)
cd server && JAVA_HOME=<jdk21> ./mvnw -pl skillhub-app -am test
# 前端
cd web && pnpm lint && pnpm typecheck && pnpm test
# 活体冒烟(先启动 dev profile 服务器)
./scripts/authoring-smoke-test.sh http://localhost:8082
# 浏览器 E2E(后端跑在 8082,vite 由 Playwright 拉起并把 /api 代理过去)
cd web && VITE_API_PROXY_TARGET=http://localhost:8082 pnpm test:e2e -- e2e/authoring-flow.spec.ts
# 重新生成前端 API 类型
cd web && pnpm exec openapi-typescript http://localhost:8082/v3/api-docs \
-o src/api/generated/schema.d.ts
```
## 边界与非目标
- v1 的行为验证以确定性断言为主,语义质量评判不强行近似(归属模型辅助审核);
- 不支持草稿多人协作编辑(单一 owner + 乐观锁防误覆盖);
- 提交后草稿回填 `submittedSkillId`/`submittedVersionId` 作为回执,但并不锁定:
继续编辑会推进 revision 并使已验证标记失效,再次提交前必须重新验证;
- MCP 工具调用发生在验证运行内(配置层探测 + prompt 任务执行),平台不充当
常驻的 MCP 网关;stdio MCP 命令与脚本任务共享同一台运行节点。

View file

@ -0,0 +1,86 @@
# Example skill: text-stats
A complete, self-contained example for the Skill Authoring & Validation
platform. It demonstrates every artifact an author must produce and every
script assertion type the behavior layer can check.
```
examples/skill-authoring/
├── SKILL.md # skill description: frontmatter (name, description) + usage docs
├── validation.yaml # behavior validation cases (4 tasks, 6 assertion types)
├── scripts/
│ └── text-stats.sh # the executable helper: text file → JSON statistics
└── references/
├── metrics.md # background material the skill cites
└── sample.txt # fixture input with known counters (2 lines, 20 words)
```
The skill computes word/line/character statistics for a text file and emits a
single-line JSON object, which it also mirrors to `artifacts/report.json`:
```json
{"input":"references/sample.txt","lines":2,"words":20,"characters":144}
```
## Validation cases
| Task | What it proves | Assertion types used |
| -------------------- | ----------------------------------------------------- | -------------------- |
| `fixture-stats` | counters are correct for the bundled fixture | `exit_code`, `stdout_contains`, `stdout_json`, `tool_call_count` |
| `output-shape` | stdout is one JSON object with exactly the known keys | `exit_code`, `stdout_matches` |
| `report-artifact` | the run leaves a persistent report artifact | `exit_code`, `artifact_exists` |
| `rejects-missing-file` | bad usage fails loudly instead of printing garbage | `exit_code` |
A valid run finishes `SUCCEEDED` with 4 tasks and 0 findings. To see the fix
loop in action, change the `/words` expectation to `21` and re-validate: the
run fails with an `ASSERTION_FAILED` finding pointing at the exact task.
## Loading it into the platform
### Option A: web workbench
1. Sign in and open **Skill 创作** (Authoring) from the sidebar.
2. Create a draft named `text-stats` in any namespace you own.
3. In the **Files** tab, replace the scaffolded `SKILL.md`, then create
`validation.yaml`, `scripts/text-stats.sh`, and the two `references/`
files with the contents from this directory (paths matter, names are
up to you).
4. In the **Runtime** tab bind agent type **local-script** with interpreter
`sh`, no tool allowlist, no MCP servers.
5. Click **Validate** and watch the run stream in real time — structure,
config, then behavior events appear as they happen.
6. When the run succeeds, **Submit** pushes the draft into the existing
scan/review/publish pipeline.
### Option B: REST API
With the dev profile running (mock auth), the same flow is four calls —
see `scripts/authoring-smoke-test.sh` for a complete, runnable version
including CSRF bootstrapping:
```sh
BASE=http://localhost:8082
H='-H Content-Type:application/json -H X-Mock-User-Id:local-user'
# 1. create the draft (id from the response)
curl -s $H -X POST $BASE/api/web/authoring/drafts \
-d '{"namespaceSlug":"global","name":"text-stats","requirement":"text statistics as JSON"}'
# 2. save each file (repeat for every path above)
curl -s $H -X PUT $BASE/api/web/authoring/drafts/<draftId>/files \
-d '{"path":"SKILL.md","content":"<contents of SKILL.md>"}'
# 3. bind the runtime
curl -s $H -X PUT $BASE/api/web/authoring/drafts/<draftId>/runtime \
-d '{"agentType":"local-script","config":{"interpreter":"sh"},"toolAllowlist":[],"mcpServers":[]}'
# 4. run validation, then poll the run / stream its events
curl -s $H -X POST $BASE/api/web/authoring/drafts/<draftId>/runs
curl -sN $BASE/api/web/authoring/runs/<runId>/events/stream # live SSE
```
Scripts execute in an isolated workspace with a scrubbed environment (only
`PATH`, `HOME`, `LANG` plus variables named in the binding's `envAllowlist`
pass through), so the example deliberately sticks to `wc`/`tr`/`printf`,
which every Unix provides. Allowed interpreters are `sh`, `bash`, `python3`,
and `node`.

View file

@ -0,0 +1,33 @@
---
name: text-stats
description: computes word, line, and character statistics for a text file and reports them as JSON
---
# text-stats
## Overview
computes word, line, and character statistics for a text file and reports them as JSON. Agents use this skill whenever they need reproducible, machine-readable metrics about a piece of text — for example to compare a document before and after rewriting it.
## Usage
1. Locate the text file to analyze. Any plain-text file in the workspace works; `references/sample.txt` is a ready-made fixture.
2. Run the helper with the file path as the only argument:
```sh
sh scripts/text-stats.sh references/sample.txt
```
3. Read the single-line JSON object from stdout:
```json
{"input":"references/sample.txt","lines":2,"words":20,"characters":144}
```
4. The same object is mirrored to `artifacts/report.json` when a persistent copy is needed.
## Resources
- `references/metrics.md` — how each counter is defined
- `references/sample.txt` — sample input used by the validation cases
- `scripts/` — executable helpers invoked during task execution

View file

@ -0,0 +1,15 @@
# Metric definitions
All counters come from `wc(1)`, so results are reproducible across platforms
without extra dependencies.
| Metric | Definition |
| ------------ | ---------------------------------------------------------------- |
| `lines` | Newline characters in the input (`wc -l`). A file whose last line has no trailing newline counts one line less. |
| `words` | Whitespace-separated tokens (`wc -w`). |
| `characters` | Bytes in the file (`wc -c`), so a multi-byte UTF-8 character counts once per byte. |
The JSON object is emitted as a single line on stdout and mirrored to
`artifacts/report.json`. Invalid usage (wrong argument count or a missing
file) exits with code 2 and writes nothing, so a caller can distinguish
"computed" from "refused" without parsing error text.

View file

@ -0,0 +1,2 @@
SkillHub makes agent skills discoverable, versioned, and trustworthy.
Every skill ships a validation spec so behavior is verified, not assumed.

View file

@ -0,0 +1,25 @@
#!/bin/sh
# text-stats.sh — print word/line/character statistics for a text file as JSON.
#
# Usage: sh scripts/text-stats.sh <input-file>
# Emits a single-line JSON object on stdout and mirrors it to artifacts/report.json.
set -eu
if [ "$#" -ne 1 ]; then
echo "usage: text-stats.sh <input-file>" >&2
exit 2
fi
INPUT="$1"
if [ ! -f "$INPUT" ]; then
echo "input file not found: $INPUT" >&2
exit 2
fi
LINES=$(wc -l < "$INPUT" | tr -d ' ')
WORDS=$(wc -w < "$INPUT" | tr -d ' ')
CHARS=$(wc -c < "$INPUT" | tr -d ' ')
mkdir -p artifacts
printf '{"input":"%s","lines":%s,"words":%s,"characters":%s}\n' \
"$INPUT" "$LINES" "$WORDS" "$CHARS" | tee artifacts/report.json

View file

@ -0,0 +1,66 @@
# Behavior validation cases for the text-stats skill.
#
# Every task runs the skill's own script inside the isolated validation
# workspace. Together the tasks exercise all six script assertion types:
# exit_code, stdout_contains, stdout_json, stdout_matches, artifact_exists,
# and tool_call_count.
version: 1
tasks:
# Happy path: the fixture produces the documented counters.
- name: fixture-stats
description: the helper reports correct counters for references/sample.txt
type: script
script: scripts/text-stats.sh
args: ["references/sample.txt"]
timeoutMs: 15000
assertions:
- type: exit_code
equals: 0
- type: stdout_contains
value: '"input":"references/sample.txt"'
- type: stdout_json
pointer: /words
equals: 20
- type: stdout_json
pointer: /lines
equals: 2
- type: tool_call_count
min: 1
max: 1
# Output shape: one JSON line with exactly the documented keys.
- name: output-shape
description: stdout is a single JSON object with the documented keys
type: script
script: scripts/text-stats.sh
args: ["references/sample.txt"]
timeoutMs: 15000
assertions:
- type: exit_code
equals: 0
- type: stdout_matches
pattern: '^\{"input":"[^"]+","lines":\d+,"words":\d+,"characters":\d+\}$'
# Side effect: the report artifact is written to the workspace.
- name: report-artifact
description: the run leaves a machine-readable report artifact
type: script
script: scripts/text-stats.sh
args: ["references/sample.txt"]
timeoutMs: 15000
assertions:
- type: exit_code
equals: 0
- type: artifact_exists
path: artifacts/report.json
# Failure mode: bad usage exits non-zero instead of printing partial output.
- name: rejects-missing-file
description: the helper refuses missing input files with a non-zero exit code
type: script
script: scripts/text-stats.sh
args: ["references/does-not-exist.txt"]
timeoutMs: 15000
assertions:
- type: exit_code
equals: 2

259
scripts/authoring-publish-e2e.sh Executable file
View file

@ -0,0 +1,259 @@
#!/usr/bin/env bash
set -euo pipefail
# Publish-pipeline end-to-end evidence run for the authoring platform.
#
# Extends scripts/authoring-smoke-test.sh past the submit step: a validated
# draft is submitted as PUBLIC by a regular user, the security scanner
# (skillhub-skill-scanner-1) scans it asynchronously, a platform admin
# approves the review task, and the version reaches the PUBLISHED terminal
# state with the skill publicly retrievable.
#
# Each check prints PASS/FAIL plus the observed identifiers so the output can
# be pasted directly as evidence. Requires the local dev profile (mock auth,
# Postgres/Redis/scanner/minio from the compose stack). Usage:
# scripts/authoring-publish-e2e.sh [base-url]
BASE_URL="${1:-http://localhost:8080}"
PASS=0
FAIL=0
COOKIE="$(mktemp)"
ADMIN_COOKIE="$(mktemp)"
RUN_ID="$(date +%s)"
NAME="publish-evidence-$RUN_ID"
PSQL=(docker exec skillhub-postgres-1 psql -U skillhub -d skillhub -tAc)
cleanup() {
rm -f "$COOKIE" "$ADMIN_COOKIE"
}
trap cleanup EXIT
pass() {
echo "PASS: $1"
PASS=$((PASS + 1))
}
fail() {
echo "FAIL: $1"
FAIL=$((FAIL + 1))
}
json_field() {
local json="$1"
local expr="$2"
JSON_INPUT="$json" python3 - "$expr" <<'PY'
import json
import os
import sys
expr = sys.argv[1]
data = json.loads(os.environ["JSON_INPUT"])
value = data
for part in expr.split('.'):
if part.isdigit():
value = value[int(part)]
else:
value = value[part]
if isinstance(value, (dict, list)):
print(json.dumps(value, ensure_ascii=False))
else:
print(value)
PY
}
assert_equals() {
local description="$1"
local expected="$2"
local actual="$3"
if [[ "$expected" == "$actual" ]]; then
pass "$description"
else
fail "$description (expected '$expected', got '$actual')"
fi
}
api() {
local method="$1"
local path="$2"
local data="${3:-}"
if [[ -n "$data" ]]; then
curl -sS -H "X-Mock-User-Id: local-user" -b "$COOKIE" -c "$COOKIE" \
-H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-X "$method" "$BASE_URL$path" -d "$data"
else
curl -sS -H "X-Mock-User-Id: local-user" -b "$COOKIE" -c "$COOKIE" \
-H "X-XSRF-TOKEN: $CSRF" -X "$method" "$BASE_URL$path"
fi
}
admin_api() {
local method="$1"
local path="$2"
local data="${3:-}"
if [[ -n "$data" ]]; then
curl -sS -H "X-Mock-User-Id: local-admin" -b "$ADMIN_COOKIE" -c "$ADMIN_COOKIE" \
-H "X-XSRF-TOKEN: $ADMIN_CSRF" -H "Content-Type: application/json" \
-X "$method" "$BASE_URL$path" -d "$data"
else
curl -sS -H "X-Mock-User-Id: local-admin" -b "$ADMIN_COOKIE" -c "$ADMIN_COOKIE" \
-H "X-XSRF-TOKEN: $ADMIN_CSRF" -X "$method" "$BASE_URL$path"
fi
}
await_run_terminal() {
local run_id="$1"
local status=""
for _ in $(seq 1 60); do
status="$(json_field "$(api GET "/api/web/authoring/runs/$run_id")" "data.status")"
case "$status" in
SUCCEEDED|FAILED|CANCELLED|TIMED_OUT) break ;;
esac
sleep 1
done
echo "$status"
}
await_db_value() {
local query="$1"
local expected="$2"
local timeout="${3:-60}"
local value=""
for _ in $(seq 1 "$timeout"); do
value="$("${PSQL[@]}" "$query" 2>/dev/null || true)"
[[ "$value" == "$expected" ]] && break
sleep 1
done
echo "$value"
}
echo "=== Authoring → Publish Pipeline E2E Evidence ==="
echo "Target: $BASE_URL Run: $RUN_ID"
echo
curl -s -c "$COOKIE" -H "X-Mock-User-Id: local-user" "$BASE_URL/api/v1/auth/providers" >/dev/null
CSRF="$(awk '$6 == "XSRF-TOKEN" { print $7 }' "$COOKIE" | tail -n 1)"
curl -s -c "$ADMIN_COOKIE" -H "X-Mock-User-Id: local-admin" "$BASE_URL/api/v1/auth/providers" >/dev/null
ADMIN_CSRF="$(awk '$6 == "XSRF-TOKEN" { print $7 }' "$ADMIN_COOKIE" | tail -n 1)"
# ---------------------------------------------------------------- author → validate
echo "--- Stage 1: author and validate (regular user local-user) ---"
DRAFT_RESPONSE="$(api POST /api/web/authoring/drafts "{\"namespaceSlug\":\"global\",\"name\":\"$NAME\"}")"
assert_equals "Draft created" "0" "$(json_field "$DRAFT_RESPONSE" "code")"
DRAFT_ID="$(json_field "$DRAFT_RESPONSE" "data.id")"
echo " draft id: $DRAFT_ID"
SKILL_MD="---
name: $NAME
description: publish pipeline evidence skill for run $RUN_ID
---
# Publish pipeline evidence
Runs a shell check that must succeed before submission.
"
api PUT "/api/web/authoring/drafts/$DRAFT_ID/files" \
"{\"path\":\"SKILL.md\",\"content\":$(python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' <<< "$SKILL_MD"),\"contentType\":\"text/markdown\"}" >/dev/null
api PUT "/api/web/authoring/drafts/$DRAFT_ID/files" \
"{\"path\":\"scripts/check.sh\",\"content\":\"#!/bin/sh\necho publish-evidence-ok\n\",\"contentType\":\"text/x-shellscript\"}" >/dev/null
api PUT "/api/web/authoring/drafts/$DRAFT_ID/files" \
"{\"path\":\"validation.yaml\",\"content\":\"version: 1\\ntasks:\\n - name: check\\n description: script prints the evidence marker\\n type: script\\n script: scripts/check.sh\\n args: []\\n timeoutMs: 10000\\n assertions:\\n - type: exit_code\\n equals: 0\\n - type: stdout_contains\\n value: publish-evidence-ok\\n\",\"contentType\":\"application/yaml\"}" >/dev/null
BINDING_RESPONSE="$(api PUT "/api/web/authoring/drafts/$DRAFT_ID/runtime" \
'{"agentType":"local-script","config":{"interpreter":"sh"},"toolAllowlist":[]}')"
assert_equals "local-script binding saved" "0" "$(json_field "$BINDING_RESPONSE" "code")"
RUN_RESPONSE="$(api POST "/api/web/authoring/drafts/$DRAFT_ID/runs")"
RUN_ID_LOCAL="$(json_field "$RUN_RESPONSE" "data.id")"
assert_equals "Validation run SUCCEEDED" "SUCCEEDED" "$(await_run_terminal "$RUN_ID_LOCAL")"
# ---------------------------------------------------------------- submit PUBLIC
echo
echo "--- Stage 2: submit as PUBLIC (enters publish pipeline) ---"
SUBMIT_RESPONSE="$(api POST "/api/web/authoring/drafts/$DRAFT_ID/submit" '{"visibility":"PUBLIC"}')"
assert_equals "Draft submitted as PUBLIC" "0" "$(json_field "$SUBMIT_RESPONSE" "code")"
SKILL_ID="$(json_field "$SUBMIT_RESPONSE" "data.skillId")"
VERSION_ID="$(json_field "$SUBMIT_RESPONSE" "data.versionId")"
SKILL_VERSION="$(json_field "$SUBMIT_RESPONSE" "data.version")"
SLUG="$(json_field "$SUBMIT_RESPONSE" "data.slug")"
echo " skill id: $SKILL_ID version id: $VERSION_ID slug: $SLUG version: $SKILL_VERSION"
DB_STATUS="$("${PSQL[@]}" "SELECT status FROM skill_version WHERE id = $VERSION_ID")"
if [[ "$DB_STATUS" == "PENDING_REVIEW" || "$DB_STATUS" == "SCANNING" ]]; then
pass "Version entered pipeline in $DB_STATUS (not auto-published)"
else
fail "Version should be PENDING_REVIEW/SCANNING, got '$DB_STATUS'"
fi
# ---------------------------------------------------------------- security scan
echo
echo "--- Stage 3: asynchronous security scan (scanner on :8000) ---"
SCAN_STATUS="$(await_db_value \
"SELECT status FROM skill_version WHERE id = $VERSION_ID" "PENDING_REVIEW" 90)"
assert_equals "Scan completed, version back to PENDING_REVIEW" "PENDING_REVIEW" "$SCAN_STATUS"
SCAN_ROW="$("${PSQL[@]}" "SELECT scanner_type || ':' || verdict || ':' || findings_count FROM security_audit WHERE skill_version_id = $VERSION_ID AND deleted_at IS NULL ORDER BY id DESC LIMIT 1")"
if [[ -n "$SCAN_ROW" && "$SCAN_ROW" != "" ]]; then
pass "security_audit row recorded: $SCAN_ROW"
else
fail "No security_audit row for version $VERSION_ID"
fi
REVIEW_TASK_ID="$("${PSQL[@]}" "SELECT id FROM review_task WHERE skill_version_id = $VERSION_ID ORDER BY id DESC LIMIT 1")"
if [[ -n "$REVIEW_TASK_ID" ]]; then
pass "Review task $REVIEW_TASK_ID pending approval"
else
fail "No review task created for version $VERSION_ID"
fi
# ---------------------------------------------------------------- admin approve
echo
echo "--- Stage 4: platform admin approves (local-admin) ---"
APPROVE_RESPONSE="$(admin_api POST "/api/web/reviews/$REVIEW_TASK_ID/approve" \
'{"comment":"publish-pipeline evidence run"}')"
assert_equals "Review approved" "0" "$(json_field "$APPROVE_RESPONSE" "code")"
REVIEW_STATUS="$(json_field "$APPROVE_RESPONSE" "data.status")"
assert_equals "Review task status APPROVED" "APPROVED" "$REVIEW_STATUS"
# ---------------------------------------------------------------- terminal state
echo
echo "--- Stage 5: PUBLISHED terminal state ---"
DB_STATUS="$("${PSQL[@]}" "SELECT status FROM skill_version WHERE id = $VERSION_ID")"
assert_equals "skill_version.status = PUBLISHED (DB)" "PUBLISHED" "$DB_STATUS"
PUBLISHED_AT="$("${PSQL[@]}" "SELECT published_at FROM skill_version WHERE id = $VERSION_ID")"
if [[ -n "$PUBLISHED_AT" && "$PUBLISHED_AT" != "" ]]; then
pass "published_at set: $PUBLISHED_AT"
else
fail "published_at not set"
fi
VISIBILITY="$("${PSQL[@]}" "SELECT visibility FROM skill WHERE id = $SKILL_ID")"
assert_equals "skill.visibility = PUBLIC (DB)" "PUBLIC" "$VISIBILITY"
DETAIL="$(curl -sS -H "X-Mock-User-Id: local-plain-user" "$BASE_URL/api/web/skills/global/$SLUG")"
assert_equals "Skill publicly retrievable by another user" "0" "$(json_field "$DETAIL" "code")"
assert_equals "Public detail shows visibility PUBLIC" "PUBLIC" "$(json_field "$DETAIL" "data.visibility")"
SUBMITTED="$(api GET "/api/web/authoring/drafts/$DRAFT_ID")"
assert_equals "Draft shows submitted skill id $SKILL_ID" "$SKILL_ID" "$(json_field "$SUBMITTED" "data.submittedSkillId")"
# ---------------------------------------------------------------- summary
echo
if [[ "$FAIL" -eq 0 ]]; then
echo "=== All $PASS checks passed — full chain: create → validate → submit → scan → review → publish ==="
exit 0
fi
echo "=== $FAIL check(s) failed, $PASS passed ==="
exit 1

511
scripts/authoring-smoke-test.sh Executable file
View file

@ -0,0 +1,511 @@
#!/usr/bin/env bash
set -euo pipefail
# Authoring platform live smoke test.
#
# Drives the full draft lifecycle over HTTP against a running SkillHub server:
# case 1 — happy path: create draft → edit files → bind runtime → validate
# (structure + config + behavior) → SSE replay → submit
# case 2 — fix loop: broken SKILL.md → FAILED run → apply suggested fix →
# revision bump → re-validate → SUCCEEDED
# case 3 — guards: submit without validation and cross-user access are rejected
# case 4 — MCP probe: dead MCP endpoint → MCP_CONNECT_FAILED finding; a local
# fake MCP server → tools discovered in the event log; unknown
# toolFilters → warning without failing the run
# case 5 — security guards: cloud-metadata endpoints and envRefs outside the
# allowlist are rejected at binding save time
#
# Requires the local dev profile (mock auth enabled). Usage:
# scripts/authoring-smoke-test.sh [base-url]
BASE_URL="${1:-http://localhost:8080}"
PASS=0
FAIL=0
COOKIE="$(mktemp)"
RUN_ID="$(date +%s)"
FAKE_MCP_PID=""
FAKE_MCP_PORT_FILE="$(mktemp)"
cleanup() {
[[ -n "$FAKE_MCP_PID" ]] && kill "$FAKE_MCP_PID" 2>/dev/null || true
rm -f "$COOKIE" "$FAKE_MCP_PORT_FILE"
}
trap cleanup EXIT
pass() {
echo "PASS: $1"
PASS=$((PASS + 1))
}
fail() {
echo "FAIL: $1"
FAIL=$((FAIL + 1))
}
csrf_token() {
awk '$6 == "XSRF-TOKEN" { print $7 }' "$COOKIE" | tail -n 1
}
bootstrap_csrf() {
curl -s -c "$COOKIE" -H "X-Mock-User-Id: local-user" "$BASE_URL/api/v1/auth/providers" >/dev/null
}
json_field() {
local json="$1"
local expr="$2"
JSON_INPUT="$json" python3 - "$expr" <<'PY'
import json
import os
import sys
expr = sys.argv[1]
data = json.loads(os.environ["JSON_INPUT"])
value = data
for part in expr.split('.'):
if part.isdigit():
value = value[int(part)]
else:
value = value[part]
if isinstance(value, (dict, list)):
print(json.dumps(value, ensure_ascii=False))
else:
print(value)
PY
}
assert_code() {
local description="$1"
local json="$2"
local expected="$3"
local actual
actual="$(json_field "$json" "code")"
if [[ "$actual" == "$expected" ]]; then
pass "$description"
else
fail "$description (expected code $expected, got $actual)"
fi
}
assert_equals() {
local description="$1"
local expected="$2"
local actual="$3"
if [[ "$expected" == "$actual" ]]; then
pass "$description"
else
fail "$description (expected '$expected', got '$actual')"
fi
}
api() {
local method="$1"
local path="$2"
local data="${3:-}"
if [[ -n "$data" ]]; then
curl -sS -H "X-Mock-User-Id: local-user" -b "$COOKIE" -c "$COOKIE" \
-H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-X "$method" "$BASE_URL$path" -d "$data"
else
curl -sS -H "X-Mock-User-Id: local-user" -b "$COOKIE" -c "$COOKIE" \
-H "X-XSRF-TOKEN: $CSRF" -X "$method" "$BASE_URL$path"
fi
}
# Polls a run until terminal; echoes the terminal status.
await_run_terminal() {
local run_id="$1"
local status=""
for _ in $(seq 1 60); do
status="$(json_field "$(api GET "/api/web/authoring/runs/$run_id")" "data.status")"
case "$status" in
SUCCEEDED|FAILED|CANCELLED|TIMED_OUT) break ;;
esac
sleep 1
done
echo "$status"
}
echo "=== Authoring Platform Smoke Test ==="
echo "Target: $BASE_URL"
echo
bootstrap_csrf
CSRF="$(csrf_token "$COOKIE")"
if [[ -z "$CSRF" ]]; then
echo "Could not bootstrap CSRF token (is mock auth enabled?)"
exit 1
fi
# ---------------------------------------------------------------- fixture namespace
# Discover an existing namespace the user can author in (namespace creation is
# admin-gated on the dev profile, so the smoke test reuses "global" or any
# namespace the mock user already owns).
NS_SLUG="$(api GET /api/web/me/namespaces | python3 -c 'import json,os,sys; data=json.loads(sys.stdin.read())["data"]; print(data[0]["slug"] if data else "")')"
if [[ -n "$NS_SLUG" ]]; then
pass "Authoring namespace available: $NS_SLUG"
else
fail "No accessible namespace for the mock user"
echo "=== $FAIL check(s) failed ==="
exit 1
fi
SLUG="$NS_SLUG"
# ---------------------------------------------------------------- case 1: happy path
echo
echo "--- Case 1: draft validates across all layers and submits ---"
# Draft names are unique per run so the smoke test is re-runnable against a
# shared dev database.
NAME="smoke-skill-$RUN_ID"
DRAFT_RESPONSE="$(api POST /api/web/authoring/drafts \
"{\"namespaceSlug\":\"$SLUG\",\"name\":\"$NAME\",\"requirement\":\"smoke test skill\"}")"
assert_code "Draft created with scaffold" "$DRAFT_RESPONSE" "0"
DRAFT_ID="$(json_field "$DRAFT_RESPONSE" "data.id")"
SKILL_MD="---
name: $NAME
description: greets the caller with a fixed message
---
# Smoke skill
## Overview
greets the caller with a fixed message
"
FILES_RESPONSE="$(api PUT "/api/web/authoring/drafts/$DRAFT_ID/files" \
"{\"path\":\"SKILL.md\",\"content\":$(python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' <<< "$SKILL_MD"),\"contentType\":\"text/markdown\"}")"
assert_code "SKILL.md saved" "$FILES_RESPONSE" "0"
SCRIPT_RESPONSE="$(api PUT "/api/web/authoring/drafts/$DRAFT_ID/files" \
'{"path":"scripts/greet.sh","content":"echo hello from smoke\n"}')"
assert_code "Script file saved" "$SCRIPT_RESPONSE" "0"
VALIDATION_YAML='version: 1
tasks:
- name: greet
description: script prints the greeting
type: script
script: scripts/greet.sh
args: []
timeoutMs: 10000
assertions:
- type: exit_code
equals: 0
- type: stdout_contains
value: hello from smoke
'
SPEC_RESPONSE="$(api PUT "/api/web/authoring/drafts/$DRAFT_ID/files" \
"{\"path\":\"validation.yaml\",\"content\":$(python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' <<< "$VALIDATION_YAML")}")"
assert_code "validation.yaml saved" "$SPEC_RESPONSE" "0"
BINDING_RESPONSE="$(api PUT "/api/web/authoring/drafts/$DRAFT_ID/runtime" \
'{"agentType":"local-script","config":{"interpreter":"sh"},"toolAllowlist":[],"mcpServers":[]}')"
assert_code "Runtime binding saved" "$BINDING_RESPONSE" "0"
RUN_RESPONSE="$(api POST "/api/web/authoring/drafts/$DRAFT_ID/runs")"
assert_code "Validation run started" "$RUN_RESPONSE" "0"
RUN_ID="$(json_field "$RUN_RESPONSE" "data.id")"
RUN_STATUS="$(await_run_terminal "$RUN_ID")"
assert_equals "Run reaches SUCCEEDED" "SUCCEEDED" "$RUN_STATUS"
FINDINGS_RESPONSE="$(api GET "/api/web/authoring/runs/$RUN_ID/findings")"
assert_code "Findings readable" "$FINDINGS_RESPONSE" "0"
FINDING_COUNT="$(JSON_INPUT="$FINDINGS_RESPONSE" python3 -c 'import json,os; print(len(json.loads(os.environ["JSON_INPUT"])["data"]))')"
assert_equals "Zero findings on valid draft" "0" "$FINDING_COUNT"
EVENTS_RESPONSE="$(api GET "/api/web/authoring/runs/$RUN_ID/events")"
assert_code "Events readable (polling API)" "$EVENTS_RESPONSE" "0"
EVENT_COUNT="$(JSON_INPUT="$EVENTS_RESPONSE" python3 -c 'import json,os; print(len(json.loads(os.environ["JSON_INPUT"])["data"]))')"
if [[ "$EVENT_COUNT" -gt 4 ]]; then
pass "Run produced $EVENT_COUNT events"
else
fail "Expected more than 4 events, got $EVENT_COUNT"
fi
SSE_OUTPUT="$(curl -sN --max-time 10 -H "X-Mock-User-Id: local-user" -b "$COOKIE" \
"$BASE_URL/api/web/authoring/runs/$RUN_ID/events/stream" || true)"
if grep -q "RUN_STARTED" <<< "$SSE_OUTPUT" && grep -q "RUN_FINISHED" <<< "$SSE_OUTPUT"; then
pass "SSE stream replays all events and terminates"
else
fail "SSE stream did not replay the full run"
fi
DRAFT_AFTER="$(api GET "/api/web/authoring/drafts/$DRAFT_ID")"
assert_equals "Draft marked validated" "True" "$(json_field "$DRAFT_AFTER" "data.validated")"
SUBMIT_RESPONSE="$(api POST "/api/web/authoring/drafts/$DRAFT_ID/submit" '{"visibility":"PRIVATE"}')"
assert_code "Validated draft submits to publish pipeline" "$SUBMIT_RESPONSE" "0"
SKILL_ID="$(json_field "$SUBMIT_RESPONSE" "data.skillId")"
if [[ "$SKILL_ID" != "None" && -n "$SKILL_ID" ]]; then
pass "Submit returned skill id $SKILL_ID"
else
fail "Submit did not return a skill id"
fi
# ---------------------------------------------------------------- case 2: fix loop
echo
echo "--- Case 2: broken draft gets a fixable finding and revalidates ---"
BROKEN_NAME="broken-skill-$RUN_ID"
BROKEN_RESPONSE="$(api POST /api/web/authoring/drafts \
"{\"namespaceSlug\":\"$SLUG\",\"name\":\"$BROKEN_NAME\"}")"
assert_code "Broken draft created" "$BROKEN_RESPONSE" "0"
BROKEN_ID="$(json_field "$BROKEN_RESPONSE" "data.id")"
BROKEN_MD="---
name: $BROKEN_NAME
---
# Broken
"
api PUT "/api/web/authoring/drafts/$BROKEN_ID/files" \
"{\"path\":\"SKILL.md\",\"content\":$(python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' <<< "$BROKEN_MD"),\"contentType\":\"text/markdown\"}" >/dev/null
BROKEN_RUN="$(api POST "/api/web/authoring/drafts/$BROKEN_ID/runs")"
BROKEN_RUN_ID="$(json_field "$BROKEN_RUN" "data.id")"
assert_equals "Broken draft fails validation" "FAILED" "$(await_run_terminal "$BROKEN_RUN_ID")"
BROKEN_FINDINGS="$(api GET "/api/web/authoring/runs/$BROKEN_RUN_ID/findings")"
FINDING_ID="$(JSON_INPUT="$BROKEN_FINDINGS" python3 -c '
import json, os
findings = json.loads(os.environ["JSON_INPUT"])["data"]
match = next((f for f in findings if f["ruleCode"] == "FRONTMATTER_FIELD_MISSING"), None)
print(match["id"] if match else "none")')"
if [[ "$FINDING_ID" != "none" ]]; then
pass "FRONTMATTER_FIELD_MISSING finding reported with location"
else
fail "Expected FRONTMATTER_FIELD_MISSING finding"
fi
REVISION_BEFORE="$(json_field "$(api GET "/api/web/authoring/drafts/$BROKEN_ID")" "data.revision")"
APPLY_RESPONSE="$(api POST "/api/web/authoring/runs/$BROKEN_RUN_ID/findings/$FINDING_ID/apply")"
assert_code "Suggested fix applied" "$APPLY_RESPONSE" "0"
REVISION_AFTER="$(json_field "$(api GET "/api/web/authoring/drafts/$BROKEN_ID")" "data.revision")"
if [[ "$REVISION_AFTER" -gt "$REVISION_BEFORE" ]]; then
pass "Applying fix advanced revision $REVISION_BEFORE → $REVISION_AFTER"
else
fail "Applying fix did not advance the revision"
fi
FIXED_RUN="$(api POST "/api/web/authoring/drafts/$BROKEN_ID/runs")"
FIXED_RUN_ID="$(json_field "$FIXED_RUN" "data.id")"
assert_equals "Re-validation after fix succeeds" "SUCCEEDED" "$(await_run_terminal "$FIXED_RUN_ID")"
# ---------------------------------------------------------------- case 3: guards
echo
echo "--- Case 3: guards ---"
UNVALIDATED_RESPONSE="$(api POST /api/web/authoring/drafts \
"{\"namespaceSlug\":\"$SLUG\",\"name\":\"unvalidated-skill-$RUN_ID\"}")"
UNVALIDATED_ID="$(json_field "$UNVALIDATED_RESPONSE" "data.id")"
SUBMIT_UNVALIDATED="$(api POST "/api/web/authoring/drafts/$UNVALIDATED_ID/submit" '{"visibility":"PRIVATE"}')"
if [[ "$(json_field "$SUBMIT_UNVALIDATED" "code")" != "0" ]]; then
pass "Submit rejected for unvalidated draft"
else
fail "Submit should be rejected for an unvalidated draft"
fi
OTHER_USER_COOKIE="$(mktemp)"
# A plain second user (no admin roles): local-admin holds SUPER_ADMIN in dev data
# and platform admins are allowed to read any draft by design.
curl -s -c "$OTHER_USER_COOKIE" -H "X-Mock-User-Id: local-plain-user" "$BASE_URL/api/v1/auth/providers" >/dev/null
OTHER_CSRF="$(awk '$6 == "XSRF-TOKEN" { print $7 }' "$OTHER_USER_COOKIE" | tail -n 1)"
CROSS_RESPONSE="$(curl -sS -H "X-Mock-User-Id: local-plain-user" -b "$OTHER_USER_COOKIE" \
-H "X-XSRF-TOKEN: $OTHER_CSRF" "$BASE_URL/api/web/authoring/drafts/$DRAFT_ID")"
if [[ "$(json_field "$CROSS_RESPONSE" "code")" != "0" ]]; then
pass "Cross-user draft access rejected"
else
fail "Another user should not read someone else's draft"
fi
rm -f "$OTHER_USER_COOKIE"
# ---------------------------------------------------------------- case 4: MCP probe
echo
echo "--- Case 4: declared MCP servers are probed for real ---"
MCP_NAME="mcp-skill-$RUN_ID"
MCP_RESPONSE="$(api POST /api/web/authoring/drafts \
"{\"namespaceSlug\":\"$SLUG\",\"name\":\"$MCP_NAME\"}")"
assert_code "MCP probe draft created" "$MCP_RESPONSE" "0"
MCP_DRAFT_ID="$(json_field "$MCP_RESPONSE" "data.id")"
MCP_MD="---
name: $MCP_NAME
description: declares MCP servers on its runtime binding
---
# MCP probe skill
"
api PUT "/api/web/authoring/drafts/$MCP_DRAFT_ID/files" \
"{\"path\":\"SKILL.md\",\"content\":$(python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' <<< "$MCP_MD"),\"contentType\":\"text/markdown\"}" >/dev/null
# Negative: an endpoint nothing listens on must surface as a config-layer error.
DEAD_BINDING="$(api PUT "/api/web/authoring/drafts/$MCP_DRAFT_ID/runtime" \
'{"agentType":"local-script","config":{"interpreter":"sh"},"toolAllowlist":[],"mcpServers":[{"name":"dead-server","transport":"http","endpoint":"http://127.0.0.1:9/mcp"}]}')"
assert_code "Binding with dead MCP server accepted" "$DEAD_BINDING" "0"
DEAD_RUN_ID="$(json_field "$(api POST "/api/web/authoring/drafts/$MCP_DRAFT_ID/runs")" "data.id")"
assert_equals "Dead MCP server fails the run" "FAILED" "$(await_run_terminal "$DEAD_RUN_ID")"
DEAD_FINDINGS="$(api GET "/api/web/authoring/runs/$DEAD_RUN_ID/findings")"
DEAD_RULE="$(JSON_INPUT="$DEAD_FINDINGS" python3 -c '
import json, os
findings = json.loads(os.environ["JSON_INPUT"])["data"]
match = next((f for f in findings if f["ruleCode"] == "MCP_CONNECT_FAILED"), None)
print(match["ruleCode"] if match else "none")')"
assert_equals "MCP_CONNECT_FAILED finding reported" "MCP_CONNECT_FAILED" "$DEAD_RULE"
# Positive: a local fake MCP server; the probe must connect and list its tools.
FAKE_MCP_SCRIPT='
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
class Handler(BaseHTTPRequestHandler):
def do_POST(self):
msg = json.loads(self.rfile.read(int(self.headers.get("Content-Length", 0))))
method = msg.get("method", "")
if method == "initialize":
self.reply(msg, {"protocolVersion": "2024-11-05", "capabilities": {},
"serverInfo": {"name": "smoke-mcp", "version": "1.0"}},
session="smoke-session-1")
elif method == "tools/list":
self.reply(msg, {"tools": [{"name": "echo", "description": "echo text",
"inputSchema": {"type": "object"}}]})
elif method == "tools/call":
self.reply(msg, {"content": [{"type": "text", "text": "ok"}]})
else:
self.reply(msg, {})
def reply(self, msg, result, session=None):
body = json.dumps({"jsonrpc": "2.0", "id": msg.get("id"), "result": result}).encode()
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
if session:
self.send_header("Mcp-Session-Id", session)
self.end_headers()
self.wfile.write(body)
def log_message(self, *args):
pass
server = HTTPServer(("127.0.0.1", 0), Handler)
print(server.server_address[1], flush=True)
server.serve_forever()
'
python3 -c "$FAKE_MCP_SCRIPT" > "$FAKE_MCP_PORT_FILE" 2>/dev/null &
FAKE_MCP_PID=$!
MCP_PORT=""
for _ in $(seq 1 25); do
MCP_PORT="$(cat "$FAKE_MCP_PORT_FILE" 2>/dev/null || true)"
[[ -n "$MCP_PORT" ]] && break
sleep 0.2
done
if [[ -n "$MCP_PORT" ]]; then
pass "Fake MCP server listening on port $MCP_PORT"
else
fail "Fake MCP server did not start"
fi
LIVE_BINDING="$(api PUT "/api/web/authoring/drafts/$MCP_DRAFT_ID/runtime" \
"{\"agentType\":\"local-script\",\"config\":{\"interpreter\":\"sh\"},\"toolAllowlist\":[],\"mcpServers\":[{\"name\":\"smoke-mcp\",\"transport\":\"http\",\"endpoint\":\"http://127.0.0.1:$MCP_PORT/mcp\",\"toolFilters\":[\"echo\"]}]}")"
assert_code "Binding with live MCP server accepted" "$LIVE_BINDING" "0"
LIVE_RUN_ID="$(json_field "$(api POST "/api/web/authoring/drafts/$MCP_DRAFT_ID/runs")" "data.id")"
assert_equals "Live MCP server lets the run pass" "SUCCEEDED" "$(await_run_terminal "$LIVE_RUN_ID")"
LIVE_EVENTS="$(api GET "/api/web/authoring/runs/$LIVE_RUN_ID/events")"
if grep -q "connected; tools: echo" <<< "$LIVE_EVENTS"; then
pass "Event log records discovered MCP tools"
else
fail "Event log lacks the MCP tools discovery line"
fi
# toolFilters naming a tool the server does not expose is a warning, not an error.
FILTERED_BINDING="$(api PUT "/api/web/authoring/drafts/$MCP_DRAFT_ID/runtime" \
"{\"agentType\":\"local-script\",\"config\":{\"interpreter\":\"sh\"},\"toolAllowlist\":[],\"mcpServers\":[{\"name\":\"smoke-mcp\",\"transport\":\"http\",\"endpoint\":\"http://127.0.0.1:$MCP_PORT/mcp\",\"toolFilters\":[\"echo\",\"does_not_exist\"]}]}")"
assert_code "Binding with unknown tool filter accepted" "$FILTERED_BINDING" "0"
FILTERED_RUN_ID="$(json_field "$(api POST "/api/web/authoring/drafts/$MCP_DRAFT_ID/runs")" "data.id")"
assert_equals "Unknown tool filter still succeeds" "SUCCEEDED" "$(await_run_terminal "$FILTERED_RUN_ID")"
FILTERED_FINDINGS="$(api GET "/api/web/authoring/runs/$FILTERED_RUN_ID/findings")"
FILTERED_RULE="$(JSON_INPUT="$FILTERED_FINDINGS" python3 -c '
import json, os
findings = json.loads(os.environ["JSON_INPUT"])["data"]
match = next((f for f in findings if f["ruleCode"] == "MCP_TOOL_FILTER_UNKNOWN"), None)
print(match["ruleCode"] if match else "none")')"
assert_equals "MCP_TOOL_FILTER_UNKNOWN warning reported" "MCP_TOOL_FILTER_UNKNOWN" "$FILTERED_RULE"
kill "$FAKE_MCP_PID" 2>/dev/null || true
wait "$FAKE_MCP_PID" 2>/dev/null || true
FAKE_MCP_PID=""
# ---------------------------------------------------------------- case 5: security guards
echo
echo "--- Case 5: binding security guards reject at save time ---"
SEC_NAME="security-skill-$RUN_ID"
SEC_RESPONSE="$(api POST /api/web/authoring/drafts \
"{\"namespaceSlug\":\"$SLUG\",\"name\":\"$SEC_NAME\"}")"
assert_code "Security guard draft created" "$SEC_RESPONSE" "0"
SEC_DRAFT_ID="$(json_field "$SEC_RESPONSE" "data.id")"
SEC_MD="---
name: $SEC_NAME
description: exercises the binding security policy
---
# Security guard skill
"
api PUT "/api/web/authoring/drafts/$SEC_DRAFT_ID/files" \
"{\"path\":\"SKILL.md\",\"content\":$(python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' <<< "$SEC_MD"),\"contentType\":\"text/markdown\"}" >/dev/null
# Cloud metadata endpoints are always blocked — even on the local profile where
# loopback/RFC1918 endpoints are deliberately allowed. Reason text assertions
# live in AuthoringFlowIntegrationTest; here we pin the save-time rejection.
METADATA_BINDING="$(api PUT "/api/web/authoring/drafts/$SEC_DRAFT_ID/runtime" \
'{"agentType":"local-script","config":{"interpreter":"sh"},"toolAllowlist":[],"mcpServers":[{"name":"metadata-thief","transport":"http","endpoint":"http://169.254.169.254/latest/meta-data/"}]}')"
if [[ "$(json_field "$METADATA_BINDING" "code")" != "0" ]]; then
pass "Cloud metadata MCP endpoint rejected at save"
else
fail "Cloud metadata MCP endpoint must be rejected at save"
fi
# envRefs outside the (empty) allowlist are rejected: bindings must not read
# arbitrary server environment variables.
ENVREF_BINDING="$(api PUT "/api/web/authoring/drafts/$SEC_DRAFT_ID/runtime" \
'{"agentType":"local-script","config":{"interpreter":"sh"},"toolAllowlist":[],"mcpServers":[{"name":"env-hog","transport":"http","endpoint":"http://127.0.0.1:9/mcp","envRefs":["HOME"]}]}')"
if [[ "$(json_field "$ENVREF_BINDING" "code")" != "0" ]]; then
pass "envRefs outside the allowlist rejected at save"
else
fail "envRefs outside the allowlist must be rejected at save"
fi
# The LLM surface is guarded too — those requests would carry the server API key.
LLM_BINDING="$(api PUT "/api/web/authoring/drafts/$SEC_DRAFT_ID/runtime" \
'{"agentType":"openai-compatible","config":{"endpoint":"http://169.254.169.254/v1","model":"test-model"},"toolAllowlist":[],"mcpServers":[]}')"
if [[ "$(json_field "$LLM_BINDING" "code")" != "0" ]]; then
pass "Cloud metadata LLM endpoint rejected at save"
else
fail "Cloud metadata LLM endpoint must be rejected at save"
fi
# ---------------------------------------------------------------- summary
echo
if [[ "$FAIL" -eq 0 ]]; then
echo "=== All $PASS checks passed ==="
exit 0
fi
echo "=== $FAIL check(s) failed, $PASS passed ==="
exit 1

194
scripts/riscv64-verify.sh Executable file
View file

@ -0,0 +1,194 @@
#!/usr/bin/env bash
# RISC-V64 live verification of the authoring platform.
#
# Boots the linux/riscv64 server image (native on riscv64 hosts, QEMU-emulated
# elsewhere) against a dedicated PostgreSQL database and drives the full
# authoring flow over the REST API:
# create draft → read scaffold → save script + validation.yaml → bind runtime
# → validate → SUCCEEDED → script stdout visible in the event stream.
#
# The script assumes:
# - the image exists (see "Building the image" below);
# - PostgreSQL and Redis are reachable from the container (defaults use
# host.docker.internal on ports 5432/6379);
# - the DB given by SKILLHUB_RISCV_DB is EMPTY — Flyway migrates it from zero
# (the script never touches your main dev database).
#
# Usage:
# scripts/riscv64-verify.sh [image] # default skillhub-server:riscv64
# SKILLHUB_RISCV_DB=mydb scripts/riscv64-verify.sh myimage:tag
#
# Building the image (on any host; buildx + QEMU required on non-riscv64):
# cd server && docker buildx build --platform linux/riscv64 \
# -t skillhub-server:riscv64 --load .
#
# Native hardware note: on a real riscv64 host (uname -m == riscv64) the same
# script runs without emulation; the log line marks which mode you are in.
# QEMU mode proves architecture independence of the JVM workload, native mode
# additionally proves the platform services' riscv64 images.
set -u
IMAGE="${1:-skillhub-server:riscv64}"
DB_NAME="${SKILLHUB_RISCV_DB:-skillhub_riscv_check}"
HOST="${SKILLHUB_RISCV_DB_HOST:-host.docker.internal}"
CONTAINER="skillhub-riscv-check"
BASE_URL="http://localhost:18082"
COOKIE="$(mktemp)"
PASS=0
FAIL=0
pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
fail() { echo "FAIL: $1"; FAIL=$((FAIL + 1)); }
json_field() {
JSON_INPUT="$1" python3 - "$2" <<'PY'
import json, os, sys
expr = sys.argv[1]
value = json.loads(os.environ["JSON_INPUT"])
for part in expr.split('.'):
value = value[int(part)] if part.isdigit() else value[part]
print(json.dumps(value, ensure_ascii=False) if isinstance(value, (dict, list)) else value)
PY
}
csrf_token() { awk '$6 == "XSRF-TOKEN" { print $7 }' "$COOKIE" | tail -n 1; }
bootstrap_csrf() {
curl -s -c "$COOKIE" -H "X-Mock-User-Id: local-user" "$BASE_URL/api/v1/auth/providers" >/dev/null
}
api() {
local method="$1"
local path="$2"
local body="${3:-}"
if [[ -n "$body" ]]; then
curl -s -b "$COOKIE" -c "$COOKIE" -X "$method" -H "Content-Type: application/json" \
-H "X-Mock-User-Id: local-user" -H "X-XSRF-TOKEN: $(csrf_token)" -d "$body" "$BASE_URL$path"
else
curl -s -b "$COOKIE" -c "$COOKIE" -X "$method" \
-H "X-Mock-User-Id: local-user" -H "X-XSRF-TOKEN: $(csrf_token)" "$BASE_URL$path"
fi
}
cleanup() {
docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
rm -f "$COOKIE"
}
trap cleanup EXIT
echo "=== RISC-V64 authoring platform verification ==="
echo "image: $IMAGE"
echo "database: $DB_NAME on $HOST"
ARCH="$(uname -m)"
if [[ "$ARCH" == "riscv64" ]]; then
echo "mode: NATIVE riscv64 host"
else
echo "mode: QEMU emulation (host arch $ARCH)"
fi
echo
echo "--- 1. boot the linux/riscv64 image ---"
docker rm -f "$CONTAINER" >/dev/null 2>&1 || true
docker run -d --name "$CONTAINER" -p 18082:8080 "$IMAGE" \
--spring.profiles.active=local \
--spring.datasource.url="jdbc:postgresql://$HOST:5432/$DB_NAME" \
--spring.data.redis.host="$HOST" >/dev/null || { echo "docker run failed"; exit 1; }
IMAGE_ARCH="$(docker inspect "$CONTAINER" --format '{{.Image}}' >/dev/null 2>&1 && docker exec "$CONTAINER" uname -m 2>/dev/null || echo unknown)"
echo "arch inside container: $IMAGE_ARCH"
if [[ "$IMAGE_ARCH" == "riscv64" ]]; then
pass "container userland is riscv64"
else
fail "container userland is '$IMAGE_ARCH', expected riscv64"
fi
HEALTHY=0
for i in $(seq 1 90); do
code=$(curl -s -o /dev/null -w '%{http_code}' "$BASE_URL/actuator/health" 2>/dev/null || true)
if [[ "$code" == "200" ]]; then
echo "health 200 after ~$((i * 10))s"
HEALTHY=1
break
fi
if ! docker ps --format '{{.Names}}' | grep -q "^$CONTAINER$"; then
echo "CONTAINER DIED — last logs:"
docker logs "$CONTAINER" 2>&1 | tail -30
exit 1
fi
sleep 10
done
if [[ "$HEALTHY" == "1" ]]; then
pass "server boots and becomes healthy"
else
fail "server did not become healthy in 900s"
docker logs "$CONTAINER" 2>&1 | tail -30
exit 1
fi
echo "--- 2. authoring flow over the API ---"
bootstrap_csrf
RUN_TAG="$(date +%s)"
DRAFT="$(api POST /api/web/authoring/drafts \
"{\"namespaceSlug\":\"global\",\"name\":\"riscv-verify-$RUN_TAG\",\"description\":\"verifies the authoring platform on riscv64\"}")"
if [[ "$(json_field "$DRAFT" "code")" == "0" ]]; then
pass "draft created"
else
fail "draft create: $DRAFT"
exit 1
fi
DRAFT_ID="$(json_field "$DRAFT" "data.id")"
SCAFFOLD="$(api GET "/api/web/authoring/drafts/$DRAFT_ID/files/content?path=SKILL.md")"
if echo "$SCAFFOLD" | grep -q "name: riscv-verify-$RUN_TAG"; then
pass "scaffold SKILL.md persisted and readable"
else
fail "scaffold read: $SCAFFOLD"
fi
api PUT "/api/web/authoring/drafts/$DRAFT_ID/files" \
'{"path":"scripts/check.sh","content":"#!/bin/sh\necho riscv-script-OK\n","contentType":"text/x-shellscript"}' >/dev/null
api PUT "/api/web/authoring/drafts/$DRAFT_ID/files" \
'{"path":"validation.yaml","content":"version: 1\ntasks:\n - name: smoke\n description: script runs on riscv64\n type: script\n script: scripts/check.sh\n args: []\n timeoutMs: 60000\n assertions:\n - type: exit_code\n equals: 0\n - type: stdout_contains\n value: riscv-script-OK\n"}' >/dev/null
BINDING="$(api PUT "/api/web/authoring/drafts/$DRAFT_ID/runtime" \
'{"agentType":"local-script","config":{"interpreter":"sh"},"toolAllowlist":[],"mcpServers":[]}')"
if [[ "$(json_field "$BINDING" "code")" == "0" ]]; then
pass "runtime binding saved"
else
fail "binding: $BINDING"
fi
RUN="$(api POST "/api/web/authoring/drafts/$DRAFT_ID/runs" '{}')"
RUN_ID="$(json_field "$RUN" "data.id")"
STATUS=""
for _ in $(seq 1 60); do
STATUS="$(json_field "$(api GET "/api/web/authoring/runs/$RUN_ID")" "data.status")"
case "$STATUS" in
SUCCEEDED|FAILED|CANCELLED|TIMED_OUT) break ;;
esac
sleep 5
done
if [[ "$STATUS" == "SUCCEEDED" ]]; then
pass "validation run SUCCEEDED (script executed in the container's riscv64 userland)"
else
fail "validation run ended as $STATUS"
fi
EVENTS="$(api GET "/api/web/authoring/runs/$RUN_ID/events")"
EVENT_COUNT="$(JSON_INPUT="$EVENTS" python3 -c '
import json, os
print(len(json.loads(os.environ["JSON_INPUT"])["data"]))' 2>/dev/null || echo 0)"
if echo "$EVENTS" | grep -q "riscv-script-OK"; then
pass "script stdout present in the event stream ($EVENT_COUNT events)"
else
fail "script stdout missing from the event stream"
fi
echo
if [[ "$FAIL" -eq 0 ]]; then
echo "=== All $PASS checks passed ==="
exit 0
fi
echo "=== $FAIL check(s) failed, $PASS passed ==="
exit 1

View file

@ -1,6 +1,7 @@
package com.iflytek.skillhub;
import com.iflytek.skillhub.bootstrap.BuiltinSkillProperties;
import com.iflytek.skillhub.config.AuthoringProperties;
import com.iflytek.skillhub.config.ProfileFieldPolicyProperties;
import com.iflytek.skillhub.config.ProfileModerationProperties;
import org.springframework.boot.SpringApplication;
@ -14,7 +15,8 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties
@EnableConfigurationProperties({
BuiltinSkillProperties.class,
ProfileModerationProperties.class,
ProfileFieldPolicyProperties.class
ProfileFieldPolicyProperties.class,
AuthoringProperties.class
})
public class SkillhubApplication {
public static void main(String[] args) {

View file

@ -0,0 +1,29 @@
package com.iflytek.skillhub.config;
import java.util.concurrent.Executor;
import java.util.concurrent.ThreadPoolExecutor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
/**
* Dedicated executor for authoring validation runs. Kept separate from
* {@code skillhubEventExecutor} because validation tasks run short-lived subprocesses
* and blocking HTTP calls that would starve the lightweight event executor.
*/
@Configuration
public class AuthoringExecutorConfig {
@Bean(name = "authoringValidationExecutor")
public Executor authoringValidationExecutor(AuthoringProperties properties) {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(Math.max(1, properties.getExecutorThreads()));
executor.setMaxPoolSize(Math.max(1, properties.getExecutorThreads()));
executor.setQueueCapacity(100);
executor.setThreadNamePrefix("authoring-validation-");
// a full queue runs the task on the submitting thread instead of dropping runs
executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
executor.initialize();
return executor;
}
}

View file

@ -0,0 +1,337 @@
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.*}).
*/
@ConfigurationProperties(prefix = "skillhub.authoring")
public class AuthoringProperties {
/** Root directory for per-run isolated working directories. */
private String workspaceRoot = System.getProperty("java.io.tmpdir") + "/skillhub-authoring";
/** Concurrent validation runs executed in-process. */
private int executorThreads = 4;
/** Hard wall-clock cap for one whole validation run. */
private long runTimeoutMs = 900_000;
/** Active runs older than this are swept to TIMED_OUT by the maintenance task. */
private int staleRunMinutes = 30;
private final LocalScript localScript = new LocalScript();
private final OpenAiCompatible openAiCompatible = new OpenAiCompatible();
private final Mcp mcp = new Mcp();
public String getWorkspaceRoot() {
return workspaceRoot;
}
public void setWorkspaceRoot(String workspaceRoot) {
this.workspaceRoot = workspaceRoot;
}
public int getExecutorThreads() {
return executorThreads;
}
public void setExecutorThreads(int executorThreads) {
this.executorThreads = executorThreads;
}
public long getRunTimeoutMs() {
return runTimeoutMs;
}
public void setRunTimeoutMs(long runTimeoutMs) {
this.runTimeoutMs = runTimeoutMs;
}
public int getStaleRunMinutes() {
return staleRunMinutes;
}
public void setStaleRunMinutes(int staleRunMinutes) {
this.staleRunMinutes = staleRunMinutes;
}
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;
/** 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
}
/**
* 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;
}
}
}
}

View file

@ -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.""");
}
}

View file

@ -0,0 +1,115 @@
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.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, and CGNAT ranges 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 {
private final AuthoringProperties properties;
public ConfiguredAuthoringSecurityPolicy(AuthoringProperties properties) {
this.properties = properties;
}
@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 = InetAddress.getAllByName(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);
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;
}
}

View file

@ -0,0 +1,325 @@
package com.iflytek.skillhub.controller.authoring;
import com.iflytek.skillhub.controller.BaseApiController;
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.ValidationEvent;
import com.iflytek.skillhub.domain.authoring.validation.ValidationFinding;
import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
import com.iflytek.skillhub.domain.skill.SkillVisibility;
import com.iflytek.skillhub.dto.ApiResponse;
import com.iflytek.skillhub.dto.CreateDraftRequest;
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.SubmitDraftRequest;
import com.iflytek.skillhub.dto.SubmitDraftResponse;
import com.iflytek.skillhub.dto.ValidationEventResponse;
import com.iflytek.skillhub.dto.ValidationFindingResponse;
import com.iflytek.skillhub.dto.ValidationRunResponse;
import com.iflytek.skillhub.service.authoring.ValidationRunOrchestrator;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
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;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestAttribute;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* Skill authoring workbench API: draft CRUD and file editing, runtime binding,
* validation run lifecycle (start, cancel, events, findings), fix application,
* and submission of validated drafts into the publish pipeline.
*/
@Tag(name = "Skill authoring")
@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 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;
}
// ---------------------------------------------------------------- drafts
@Operation(operationId = "createAuthoringDraft", summary = "Create a draft seeded with a SKILL.md scaffold")
@PostMapping("/drafts")
public ApiResponse<DraftResponse> createDraft(@Valid @RequestBody CreateDraftRequest request,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
SkillDraft draft = draftService.createDraft(
request.namespaceSlug(), userId, request.name(), request.requirement(), platformRoles);
return ok("response.success.created", DraftResponse.from(draft));
}
@Operation(operationId = "listAuthoringDrafts", summary = "List the current user's drafts")
@GetMapping("/drafts")
public ApiResponse<List<DraftResponse>> listDrafts(@RequestAttribute("userId") String userId) {
return ok("response.success", draftService.listDrafts(userId).stream()
.map(DraftResponse::from)
.toList());
}
@Operation(operationId = "getAuthoringDraft", summary = "Get one draft owned by the current user")
@GetMapping("/drafts/{draftId}")
public ApiResponse<DraftResponse> getDraft(@PathVariable Long draftId,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
return ok("response.success",
DraftResponse.from(draftService.getOwnedDraft(draftId, userId, platformRoles)));
}
@Operation(operationId = "deleteAuthoringDraft", summary = "Delete a draft and its files")
@DeleteMapping("/drafts/{draftId}")
public ApiResponse<Void> deleteDraft(@PathVariable Long draftId,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
draftService.deleteDraft(draftId, userId, platformRoles);
return ok("response.success.deleted", null);
}
// ---------------------------------------------------------------- draft files
@Operation(operationId = "listDraftFiles", summary = "List a draft's files with metadata")
@GetMapping("/drafts/{draftId}/files")
public ApiResponse<List<DraftFileResponse>> listFiles(@PathVariable Long draftId) {
return ok("response.success", draftService.listFiles(draftId).stream()
.map(DraftFileResponse::from)
.toList());
}
@Operation(operationId = "saveDraftFile", summary = "Create or update one draft file")
@PutMapping("/drafts/{draftId}/files")
public ApiResponse<SaveDraftFileResponse> saveFile(@PathVariable Long draftId,
@Valid @RequestBody SaveDraftFileRequest request,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
byte[] content = request.isBase64()
? Base64.getDecoder().decode(request.content())
: request.content().getBytes(StandardCharsets.UTF_8);
return ok("response.success.updated", SaveDraftFileResponse.from(
draftService.saveFile(draftId, userId, request.path(), content,
request.contentType(), request.expectedRevision(), platformRoles)));
}
@Operation(operationId = "readDraftFile", summary = "Read one draft file's content")
@GetMapping("/drafts/{draftId}/files/content")
public ApiResponse<DraftFileContentResponse> readFile(@PathVariable Long draftId,
@RequestParam("path") String path,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
SkillDraftService.FileContent content =
draftService.readFile(draftId, userId, path, platformRoles);
return ok("response.success", new DraftFileContentResponse(
content.file().getFilePath(),
content.file().getSha256(),
content.file().getSize(),
content.file().getContentType(),
content.asText()));
}
@Operation(operationId = "deleteDraftFile", summary = "Delete one draft file")
@DeleteMapping("/drafts/{draftId}/files")
public ApiResponse<Void> deleteFile(@PathVariable Long draftId,
@RequestParam("path") String path,
@RequestParam(value = "expectedRevision", required = false)
Integer expectedRevision,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
draftService.deleteFile(draftId, userId, path, expectedRevision, platformRoles);
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")
@PostMapping("/drafts/{draftId}/runs")
public ApiResponse<ValidationRunResponse> startRun(@PathVariable Long draftId,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
ValidationRun run = runService.startRun(draftId, userId, platformRoles);
orchestrator.submit(run.getId());
return ok("response.success.created", ValidationRunResponse.from(run));
}
@Operation(operationId = "listValidationRuns", summary = "List the draft's validation runs")
@GetMapping("/drafts/{draftId}/runs")
public ApiResponse<List<ValidationRunResponse>> listRuns(@PathVariable Long draftId) {
return ok("response.success", runService.listRuns(draftId).stream()
.map(ValidationRunResponse::from)
.toList());
}
@Operation(operationId = "getValidationRun", summary = "Get one validation run")
@GetMapping("/runs/{runId}")
public ApiResponse<ValidationRunResponse> getRun(@PathVariable Long runId,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
ValidationRun run = runService.getOwnedRun(runId, userId, platformRoles);
return ok("response.success", ValidationRunResponse.from(run));
}
@Operation(operationId = "cancelValidationRun", summary = "Request cooperative cancellation of a run")
@PostMapping("/runs/{runId}/cancel")
public ApiResponse<ValidationRunResponse> cancelRun(@PathVariable Long runId,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
ValidationRun run = orchestrator.requestCancel(runId, userId, platformRoles);
return ok("response.success.updated", ValidationRunResponse.from(run));
}
@Operation(operationId = "listValidationEvents", summary = "List run events after a sequence cursor (polling)")
@GetMapping("/runs/{runId}/events")
public ApiResponse<List<ValidationEventResponse>> listEvents(
@PathVariable Long runId,
@RequestParam(value = "afterSeq", required = false) Integer afterSeq,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
runService.getOwnedRun(runId, userId, platformRoles);
return ok("response.success", runService.listEvents(runId, afterSeq).stream()
.map(ValidationEventResponse::from)
.toList());
}
// ---------------------------------------------------------------- findings & fixes
@Operation(operationId = "listValidationFindings", summary = "List a run's findings with fix suggestions")
@GetMapping("/runs/{runId}/findings")
public ApiResponse<List<ValidationFindingResponse>> listFindings(
@PathVariable Long runId,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
runService.getOwnedRun(runId, userId, platformRoles);
return ok("response.success", runService.listFindings(runId).stream()
.map(ValidationFindingResponse::from)
.toList());
}
@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)));
}
}

View file

@ -0,0 +1,68 @@
package com.iflytek.skillhub.controller.authoring;
import com.iflytek.skillhub.domain.authoring.service.ValidationRunService;
import com.iflytek.skillhub.domain.authoring.validation.ValidationEvent;
import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
import com.iflytek.skillhub.service.authoring.ValidationEventBroadcaster;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import java.util.List;
import java.util.Set;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestAttribute;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
/**
* Server-sent events for validation runs. Browsers authenticate via the session
* cookie (EventSource cannot send headers); token clients use the /api/v1 variant.
* Event ids are the per-run sequence numbers, so reconnecting clients resume from
* Last-Event-ID without gaps or duplicates.
*/
@Tag(name = "Skill authoring")
@RestController
@RequestMapping({"/api/v1/authoring", "/api/web/authoring"})
public class ValidationStreamController {
private final ValidationRunService runService;
private final ValidationEventBroadcaster broadcaster;
public ValidationStreamController(ValidationRunService runService,
ValidationEventBroadcaster broadcaster) {
this.runService = runService;
this.broadcaster = broadcaster;
}
@Operation(operationId = "streamValidationEvents",
summary = "Stream run events over SSE; resumes from Last-Event-ID")
@GetMapping(value = "/runs/{runId}/events/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter streamEvents(@PathVariable Long runId,
@RequestParam(value = "afterSeq", required = false) Integer afterSeq,
@RequestHeader(value = "Last-Event-ID", required = false) String lastEventId,
@RequestAttribute("userId") String userId,
@RequestAttribute(value = "platformRoles", required = false)
Set<String> platformRoles) {
ValidationRun run = runService.getOwnedRun(runId, userId, platformRoles);
int lastSeq = resolveCursor(afterSeq, lastEventId);
List<ValidationEvent> replay = runService.listEvents(run.getId(), lastSeq);
return broadcaster.subscribe(run.getId(), lastSeq, replay);
}
private int resolveCursor(Integer afterSeq, String lastEventId) {
int fromParam = afterSeq == null ? 0 : Math.max(0, afterSeq);
int fromHeader = 0;
if (lastEventId != null && !lastEventId.isBlank()) {
try {
fromHeader = Math.max(0, Integer.parseInt(lastEventId.trim()));
} catch (NumberFormatException ignored) {
// malformed Last-Event-ID restarts from the beginning
}
}
return Math.max(fromParam, fromHeader);
}
}

View file

@ -0,0 +1,11 @@
package com.iflytek.skillhub.dto;
import jakarta.validation.constraints.NotBlank;
/** Request body for creating a skill authoring draft. */
public record CreateDraftRequest(
@NotBlank(message = "{error.badRequest}") String namespaceSlug,
@NotBlank(message = "{error.badRequest}") String name,
String requirement
) {
}

View file

@ -0,0 +1,11 @@
package com.iflytek.skillhub.dto;
/** Draft file content, always delivered as text (draft files are text formats). */
public record DraftFileContentResponse(
String path,
String sha256,
Long size,
String contentType,
String content
) {
}

View file

@ -0,0 +1,25 @@
package com.iflytek.skillhub.dto;
import com.iflytek.skillhub.domain.authoring.DraftFile;
import java.time.Instant;
/** Draft file metadata (content is fetched separately). */
public record DraftFileResponse(
Long id,
String path,
String sha256,
Long size,
String contentType,
Instant updatedAt
) {
public static DraftFileResponse from(DraftFile file) {
return new DraftFileResponse(
file.getId(),
file.getFilePath(),
file.getSha256(),
file.getSize(),
file.getContentType(),
file.getUpdatedAt());
}
}

View file

@ -0,0 +1,41 @@
package com.iflytek.skillhub.dto;
import com.iflytek.skillhub.domain.authoring.SkillDraft;
import java.time.Instant;
/** Draft summary/aggregate exposed to the authoring UI. */
public record DraftResponse(
Long id,
Long namespaceId,
String name,
String requirement,
Integer revision,
String contentDigest,
boolean validated,
Integer validatedRevision,
Long validatedRunId,
Long submittedSkillId,
Long submittedVersionId,
Instant submittedAt,
Instant createdAt,
Instant updatedAt
) {
public static DraftResponse from(SkillDraft draft) {
return new DraftResponse(
draft.getId(),
draft.getNamespaceId(),
draft.getName(),
draft.getRequirement(),
draft.getRevision(),
draft.getContentDigest(),
draft.isCurrentRevisionValidated(),
draft.getValidatedRevision(),
draft.getValidatedRunId(),
draft.getSubmittedSkillId(),
draft.getSubmittedVersionId(),
draft.getSubmittedAt(),
draft.getCreatedAt(),
draft.getUpdatedAt());
}
}

View file

@ -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
) {
}

View file

@ -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
) {
}

View file

@ -0,0 +1,21 @@
package com.iflytek.skillhub.dto;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
/**
* Request body for saving one draft file. Text is the default encoding; base64
* transports binary-safe content.
*/
public record SaveDraftFileRequest(
@NotBlank(message = "{error.badRequest}") String path,
@NotNull(message = "{error.badRequest}") String content,
String encoding,
String contentType,
Integer expectedRevision
) {
public boolean isBase64() {
return "base64".equalsIgnoreCase(encoding);
}
}

View file

@ -0,0 +1,20 @@
package com.iflytek.skillhub.dto;
import com.iflytek.skillhub.domain.authoring.service.SkillDraftService;
/** Result of saving one draft file: updated draft plus file metadata. */
public record SaveDraftFileResponse(
DraftResponse draft,
DraftFileResponse file,
boolean created,
boolean revisionAdvanced
) {
public static SaveDraftFileResponse from(SkillDraftService.SaveFileOutcome outcome) {
return new SaveDraftFileResponse(
DraftResponse.from(outcome.draft()),
DraftFileResponse.from(outcome.file()),
outcome.created(),
outcome.revisionAdvanced());
}
}

View file

@ -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
) {
}

View file

@ -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());
}
}

View file

@ -0,0 +1,28 @@
package com.iflytek.skillhub.dto;
import com.iflytek.skillhub.domain.authoring.validation.ValidationEvent;
import java.time.Instant;
import java.util.Map;
/** One persisted validation event (log line, tool call, finding, phase marker...). */
public record ValidationEventResponse(
Long id,
Long runId,
Integer seq,
String type,
String phase,
Map<String, Object> payload,
Instant createdAt
) {
public static ValidationEventResponse from(ValidationEvent event) {
return new ValidationEventResponse(
event.getId(),
event.getRunId(),
event.getSeq(),
event.getEventType().name(),
event.getPhase(),
event.getPayload() == null ? Map.of() : event.getPayload(),
event.getCreatedAt());
}
}

View file

@ -0,0 +1,41 @@
package com.iflytek.skillhub.dto;
import com.iflytek.skillhub.domain.authoring.FixSuggestion;
import com.iflytek.skillhub.domain.authoring.validation.ValidationFinding;
import java.time.Instant;
/**
* One validation finding. {@code suggestion} carries the machine-applicable fix
* (patches with old/new values) when one exists, for preview and confirmed apply.
*/
public record ValidationFindingResponse(
Long id,
Long runId,
String layer,
String ruleCode,
String severity,
String filePath,
String location,
String message,
FixSuggestion suggestion,
String status,
Integer appliedRevision,
Instant createdAt
) {
public static ValidationFindingResponse from(ValidationFinding finding) {
return new ValidationFindingResponse(
finding.getId(),
finding.getRunId(),
finding.getLayer().name(),
finding.getRuleCode(),
finding.getSeverity().name(),
finding.getFilePath(),
finding.getLocation(),
finding.getMessage(),
finding.getSuggestion(),
finding.getStatus().name(),
finding.getAppliedRevision(),
finding.getCreatedAt());
}
}

View file

@ -0,0 +1,46 @@
package com.iflytek.skillhub.dto;
import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
import java.time.Instant;
import java.util.Map;
/** Validation run state and outcome counters. */
public record ValidationRunResponse(
Long id,
Long draftId,
Integer draftRevision,
String status,
boolean cancelRequested,
boolean active,
boolean terminal,
Integer errorCount,
Integer warningCount,
String triggeredBy,
Instant startedAt,
Instant finishedAt,
Instant createdAt,
Map<String, Object> summary
) {
public static ValidationRunResponse from(ValidationRun run) {
return from(run, run.getSummary());
}
public static ValidationRunResponse from(ValidationRun run, Map<String, Object> summary) {
return new ValidationRunResponse(
run.getId(),
run.getDraftId(),
run.getDraftRevision(),
run.getStatus().name(),
run.isCancelRequested(),
run.isActive(),
run.getStatus().isTerminal(),
run.getErrorCount(),
run.getWarningCount(),
run.getTriggeredBy(),
run.getStartedAt(),
run.getFinishedAt(),
run.getCreatedAt(),
summary == null ? Map.of() : summary);
}
}

View file

@ -0,0 +1,153 @@
package com.iflytek.skillhub.service.authoring;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.iflytek.skillhub.domain.authoring.validation.ValidationEvent;
import com.iflytek.skillhub.domain.authoring.validation.ValidationEventType;
import java.io.IOException;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArrayList;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
/**
* In-memory SSE hub for validation runs. Each subscriber tracks the last sequence
* number it saw, so replay (Last-Event-ID / afterSeq) and live delivery can be
* interleaved without duplicates. The hub is per-instance by design: the current
* deployment runs one backend node, and remote clients always have the polling
* endpoint as a fallback.
*/
@Component
public class ValidationEventBroadcaster {
/** SSE connection lifetime cap; clients reconnect with Last-Event-ID on expiry. */
static final long EMITTER_TIMEOUT_MS = 30L * 60 * 1000;
private final Map<Long, CopyOnWriteArrayList<EmitterSession>> sessionsByRun = new ConcurrentHashMap<>();
private final ObjectMapper objectMapper;
public ValidationEventBroadcaster(ObjectMapper objectMapper) {
this.objectMapper = objectMapper;
}
/**
* Registers a live emitter and replays already-persisted events through it. The
* session cursor makes replay and concurrent live delivery duplicate-free and
* order-preserving: every send fires only for sequence numbers the session has
* not delivered yet.
*
* @param runId the run to subscribe to
* @param lastSeq the subscriber's last seen sequence number (Last-Event-ID)
* @param replay persisted events after {@code lastSeq}, oldest first
*/
public SseEmitter subscribe(Long runId, int lastSeq, List<ValidationEvent> replay) {
EmitterSession session = new EmitterSession(lastSeq);
sessionsByRun.computeIfAbsent(runId, key -> new CopyOnWriteArrayList<>()).add(session);
Runnable detach = () -> detach(runId, session);
session.emitter().onCompletion(detach);
session.emitter().onTimeout(detach);
session.emitter().onError(error -> detach.run());
boolean terminal = false;
for (ValidationEvent event : replay) {
if (!session.send(event.getSeq(), envelope(event))) {
detach(runId, session);
return session.emitter();
}
if (event.getEventType() == ValidationEventType.RUN_FINISHED) {
terminal = true;
}
}
if (terminal) {
// run already finished: close the stream so clients stop reconnecting
session.emitter().complete();
}
return session.emitter();
}
/** Pushes one persisted event to every live subscriber of the run. */
public void publish(Long runId, ValidationEvent event) {
List<EmitterSession> sessions = sessionsByRun.get(runId);
if (sessions == null) {
return;
}
String envelope = envelope(event);
for (EmitterSession session : sessions) {
if (!session.send(event.getSeq(), envelope)) {
detach(runId, session);
}
}
}
/** Sends the terminal event and completes all subscribers of a finished run. */
public void completeRun(Long runId, ValidationEvent terminalEvent) {
publish(runId, terminalEvent);
List<EmitterSession> sessions = sessionsByRun.remove(runId);
if (sessions == null) {
return;
}
for (EmitterSession session : sessions) {
session.emitter().complete();
}
}
private void detach(Long runId, EmitterSession session) {
List<EmitterSession> sessions = sessionsByRun.get(runId);
if (sessions != null) {
sessions.remove(session);
}
}
private String envelope(ValidationEvent event) {
Map<String, Object> payload = event.getPayload() == null ? Map.of() : event.getPayload();
Map<String, Object> envelope = Map.of(
"seq", event.getSeq(),
"type", event.getEventType().name(),
"phase", event.getPhase() == null ? "" : event.getPhase(),
"payload", payload,
"createdAt", event.getCreatedAt().toString());
try {
return objectMapper.writeValueAsString(envelope);
} catch (IOException exception) {
return "{\"seq\":" + event.getSeq() + ",\"type\":\"" + event.getEventType() + "\"}";
}
}
/** One subscriber connection with its own delivery cursor and serialized writes. */
static final class EmitterSession {
private final SseEmitter emitter;
private int lastSeq;
EmitterSession(int lastSeq) {
this.emitter = new SseEmitter(EMITTER_TIMEOUT_MS);
this.lastSeq = lastSeq;
}
SseEmitter emitter() {
return emitter;
}
int lastSeq() {
return lastSeq;
}
/** Sends unless the event predates this session's cursor; false means the pipe broke. */
synchronized boolean send(int seq, String envelope) {
if (seq <= lastSeq) {
return true;
}
try {
emitter.send(SseEmitter.event()
.id(String.valueOf(seq))
.data(envelope, MediaType.APPLICATION_JSON));
lastSeq = seq;
return true;
} catch (IOException | IllegalStateException exception) {
return false;
}
}
}
}

View file

@ -0,0 +1,584 @@
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.SkillDraft;
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;
import com.iflytek.skillhub.domain.authoring.validation.ValidationEventType;
import com.iflytek.skillhub.domain.authoring.validation.ValidationFinding;
import com.iflytek.skillhub.domain.authoring.validation.ValidationLayer;
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 com.iflytek.skillhub.service.authoring.mcp.McpProbeService;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
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.LinkedHashMap;
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.atomic.AtomicBoolean;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;
/**
* Executes validation runs on a dedicated executor: materializes the draft into an
* isolated workspace, runs the three validation layers (structure, configuration,
* behavior), persists ordered events and findings as they occur, and settles the run.
*
* <p>All terminal transitions funnel through {@link #settle}, which appends exactly one
* RUN_FINISHED event per run regardless of whether the run ends normally, is cancelled,
* times out, or is swept after a crash.
*/
@Component
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 McpProbeService mcpProbeService;
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;
/** Cooperative cancel flags mirroring the persisted cancelRequested flag for fast reaction. */
private final Map<Long, AtomicBoolean> cancelFlags = new ConcurrentHashMap<>();
/** Per-run monitors making the RUN_FINISHED append-and-broadcast exactly-once. */
private final Map<Long, Object> terminalLocks = new ConcurrentHashMap<>();
public ValidationRunOrchestrator(ValidationRunService runService,
SkillDraftService draftService,
RuntimeBindingService bindingService,
DraftStructureValidator structureValidator,
RuntimeBindingValidator bindingValidator,
McpProbeService mcpProbeService,
List<SkillRuntimeAdapter> adapters,
ValidationEventBroadcaster broadcaster,
AuthoringProperties properties,
@Qualifier("authoringValidationExecutor") Executor executor) {
this.runService = runService;
this.draftService = draftService;
this.bindingService = bindingService;
this.structureValidator = structureValidator;
this.bindingValidator = bindingValidator;
this.mcpProbeService = mcpProbeService;
this.adapters = List.copyOf(adapters);
this.broadcaster = broadcaster;
this.properties = properties;
this.executor = executor;
}
/** Enqueues one QUEUED run for execution. */
public void submit(Long runId) {
executor.execute(() -> executeRun(runId));
}
/**
* Requests cooperative cancellation. QUEUED runs settle immediately; running runs
* settle when their executor observes the flag (between tasks or inside adapters).
*/
public ValidationRun requestCancel(Long runId, String userId, Set<String> platformRoles) {
ValidationRun run = runService.requestCancel(runId, userId, platformRoles);
cancelFlags.computeIfAbsent(runId, key -> new AtomicBoolean()).set(true);
if (run.getStatus().isTerminal()) {
emitTerminalOnce(runId);
}
return run;
}
/**
* Idempotent terminal settle: persists the outcome (first writer wins), appends the
* RUN_FINISHED event exactly once, and completes SSE subscribers.
*/
public void settle(Long runId, ValidationRunStatus status, int errorCount, int warningCount,
Map<String, Object> summary) {
runService.settleIfActive(runId, status, errorCount, warningCount, summary);
emitTerminalOnce(runId);
}
// ---------------------------------------------------------------- execution
private void executeRun(Long runId) {
try {
ValidationRun run = runService.claimForExecution(runId);
if (run.getStatus().isTerminal()) {
emitTerminalOnce(runId);
return;
}
executePipeline(run);
} catch (DomainConflictException exception) {
// cancelled while queued, or already claimed/settled elsewhere
log.info("Validation run {} no longer claimable: {}", runId, exception.getMessage());
emitTerminalOnce(runId);
} catch (Exception exception) {
log.error("Validation run {} crashed", runId, exception);
settle(runId, ValidationRunStatus.FAILED, 1, 0,
Map.of("internalError", truncate(String.valueOf(exception.getMessage()), 500)));
} finally {
cancelFlags.remove(runId);
terminalLocks.remove(runId);
}
}
private void executePipeline(ValidationRun run) {
Long runId = run.getId();
SkillDraft draft = draftService.getDraft(run.getDraftId());
List<PackageEntry> entries = draftService.materializeEntries(draft.getId());
RunContext context = new RunContext(runId);
emit(runId, ValidationEventType.RUN_STARTED, null, Map.of(
"draftId", draft.getId(),
"draftName", draft.getName(),
"draftRevision", run.getDraftRevision()));
Path workspace = workspaceFor(runId);
try {
materializeWorkspace(workspace, entries);
// ---- STRUCTURE layer
emit(runId, ValidationEventType.PHASE_STARTED, "STRUCTURE", Map.of());
DraftStructureValidator.StructureReport structure =
structureValidator.validate(draft.getName(), draft.getRequirement(), entries);
structure.findings().forEach(context::recordFinding);
emit(runId, ValidationEventType.PHASE_FINISHED, "STRUCTURE", Map.of(
"findings", structure.findings().size(),
"errors", context.errorCount(ValidationLayer.STRUCTURE),
"warnings", context.warningCount(ValidationLayer.STRUCTURE)));
// ---- CONFIG layer
emit(runId, ValidationEventType.PHASE_STARTED, "CONFIG", Map.of());
ValidationSpec spec = runConfigLayer(context, draft, 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 {
BehaviorOutcome outcome = runBehaviorLayer(context, run, draft, 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, blocked));
} 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);
}
}
// ---------------------------------------------------------------- config layer
private ValidationSpec runConfigLayer(RunContext context, SkillDraft draft,
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(draft.getId()).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);
// 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",
"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,
SkillDraft draft, ValidationSpec spec, Path workspace) {
RuntimeBinding binding = bindingService.findBinding(draft.getId()).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();
AtomicBoolean cancelFlag = cancelFlags.computeIfAbsent(run.getId(),
key -> new AtomicBoolean(false));
RuntimeExecutionContext executionContext = new RuntimeExecutionContext(
run.getId(), workspace, adapterConfig, toolAllowlist,
binding.getMcpServers() == null ? List.of() : binding.getMcpServers(),
cancelFlag::get);
for (ValidationTaskSpec task : spec.safeTasks()) {
if (cancelFlag.get()) {
settle(run.getId(), ValidationRunStatus.CANCELLED,
context.errorCount, context.warningCount, summary(context, false));
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);
}
/** Appends the RUN_FINISHED event exactly once per run, then completes SSE subscribers. */
private void emitTerminalOnce(Long runId) {
Object lock = terminalLocks.computeIfAbsent(runId, key -> new Object());
synchronized (lock) {
for (ValidationEvent event : runService.listEvents(runId, null)) {
if (event.getEventType() == ValidationEventType.RUN_FINISHED) {
broadcaster.completeRun(runId, event);
return;
}
}
ValidationRun run = runService.getRun(runId);
ValidationEvent terminal = runService.appendEvent(runId,
ValidationEventType.RUN_FINISHED, null, Map.of(
"status", run.getStatus().name(),
"errorCount", run.getErrorCount(),
"warningCount", run.getWarningCount()));
broadcaster.completeRun(runId, terminal);
}
}
// ---------------------------------------------------------------- small helpers
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 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) {
Path workspace = Path.of(properties.getWorkspaceRoot(), "run-" + runId);
try {
Files.createDirectories(workspace);
} catch (IOException exception) {
throw new IllegalStateException("cannot create validation workspace: " + workspace, exception);
}
return workspace;
}
private void materializeWorkspace(Path workspace, List<PackageEntry> entries) throws IOException {
for (PackageEntry entry : entries) {
Path target = workspace.resolve(entry.path()).normalize();
if (!target.startsWith(workspace.normalize())) {
throw new IOException("draft file escapes workspace: " + entry.path());
}
Files.createDirectories(target.getParent());
try (InputStream input = entry.openStream();
OutputStream output = Files.newOutputStream(target)) {
input.transferTo(output);
}
}
}
private String readEntryText(List<PackageEntry> entries, String path) {
return entries.stream()
.filter(entry -> path.equals(entry.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(path -> {
try {
Files.deleteIfExists(path);
} catch (IOException ignored) {
// workspace cleanup is best-effort; the OS temp sweeper is the backstop
}
});
} catch (IOException ignored) {
// same: cleanup failures must not mask the validation outcome
}
}
private static String truncate(String value, int limit) {
if (value == null) {
return "";
}
return value.length() <= limit ? value : value.substring(0, limit) + "…";
}
private record BehaviorOutcome(boolean interrupted, String reason) {
static final BehaviorOutcome COMPLETED = new BehaviorOutcome(false, null);
static BehaviorOutcome interrupted(String reason) {
return new BehaviorOutcome(true, reason);
}
}
/** Mutable per-run state: findings, counters, and the single-writer event sink. */
private final class RunContext {
private final Long runId;
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;
}
int errorCount(ValidationLayer layer) {
return (int) findings.stream()
.filter(finding -> finding.layer() == layer
&& finding.severity() == FindingSeverity.ERROR)
.count();
}
int warningCount(ValidationLayer layer) {
return (int) findings.stream()
.filter(finding -> finding.layer() == layer
&& finding.severity() == FindingSeverity.WARNING)
.count();
}
void recordFinding(FindingDraft draft) {
findings.add(draft);
if (draft.severity() == FindingSeverity.ERROR) {
errorCount++;
} else if (draft.severity() == FindingSeverity.WARNING) {
warningCount++;
}
ValidationFinding persisted = runService.recordFinding(runId, draft);
emit(runId, ValidationEventType.FINDING, draft.layer().name(), Map.of(
"findingId", persisted.getId(),
"layer", draft.layer().name(),
"ruleCode", draft.ruleCode(),
"severity", draft.severity().name(),
"filePath", draft.filePath() == null ? "" : draft.filePath(),
"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)));
}
};
}
}
}

View file

@ -0,0 +1,164 @@
package com.iflytek.skillhub.service.authoring.adapter;
import com.iflytek.skillhub.config.AuthoringProperties;
import java.io.IOException;
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);
List<String> command = new ArrayList<>();
command.add("docker");
command.add("run");
command.add("--rm");
command.add("--name");
command.add(containerName(runTag));
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());
}
}
/** 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();
}
}
}

View file

@ -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));
}
}

View file

@ -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();
}
}
}

View file

@ -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) + "…";
}
}

View file

@ -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);
}
}
}

View file

@ -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();
}
}
}

View file

@ -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) + "…";
}
}

View file

@ -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();
}

View file

@ -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;
}
}

View file

@ -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))));
}
}
}

View file

@ -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;
}
}

View file

@ -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();
}
}

View file

@ -0,0 +1,117 @@
package com.iflytek.skillhub.task;
import com.iflytek.skillhub.config.AuthoringProperties;
import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
import com.iflytek.skillhub.domain.authoring.validation.ValidationRunStatus;
import com.iflytek.skillhub.domain.authoring.service.ValidationRunService;
import com.iflytek.skillhub.service.authoring.ValidationRunOrchestrator;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.time.Instant;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;
/**
* Bounded recovery for validation runs: active runs older than the configured stale
* threshold are settled as TIMED_OUT (covering executor crashes and restarts), and
* orphaned workspace directories are removed best-effort.
*/
@Component
public class ValidationRunMaintenanceTask {
private static final Logger log = LoggerFactory.getLogger(ValidationRunMaintenanceTask.class);
private final ValidationRunService runService;
private final ValidationRunOrchestrator orchestrator;
private final AuthoringProperties properties;
public ValidationRunMaintenanceTask(ValidationRunService runService,
ValidationRunOrchestrator orchestrator,
AuthoringProperties properties) {
this.runService = runService;
this.orchestrator = orchestrator;
this.properties = properties;
}
@Scheduled(fixedDelayString = "${skillhub.authoring.maintenance-interval-ms:30000}")
public void sweep() {
settleStaleRuns();
cleanupWorkspaces();
}
private void settleStaleRuns() {
Instant cutoff = Instant.now().minus(Duration.ofMinutes(properties.getStaleRunMinutes()));
List<ValidationRun> stale = runService.findActiveRunsCreatedBefore(cutoff);
for (ValidationRun run : stale) {
log.warn("Settling stale validation run {} (draft {}, status {}) as TIMED_OUT",
run.getId(), run.getDraftId(), run.getStatus());
orchestrator.settle(run.getId(), ValidationRunStatus.TIMED_OUT,
run.getErrorCount(), run.getWarningCount(),
Map.of("reason", "stale run swept by maintenance task"));
}
}
/** Removes workspace directories of runs that are no longer active. */
private void cleanupWorkspaces() {
Path root = Path.of(properties.getWorkspaceRoot());
if (!Files.isDirectory(root)) {
return;
}
try (var directories = Files.list(root)) {
directories.filter(Files::isDirectory)
.filter(directory -> directory.getFileName().toString().startsWith("run-"))
.forEach(this::cleanupIfOrphaned);
} catch (IOException exception) {
log.warn("Failed to list validation workspaces under {}: {}", root, exception.getMessage());
}
}
private void cleanupIfOrphaned(Path directory) {
String fileName = directory.getFileName().toString();
long runId;
try {
runId = Long.parseLong(fileName.substring("run-".length()));
} catch (NumberFormatException exception) {
return;
}
try {
ValidationRun run = runService.getRun(runId);
if (run.isActive()) {
return;
}
try (var stream = Files.walk(directory)) {
stream.sorted(Comparator.reverseOrder()).forEach(path -> {
try {
Files.deleteIfExists(path);
} catch (IOException ignored) {
// best-effort cleanup
}
});
}
} catch (Exception exception) {
// unknown run id (workspace of a deleted draft) — remove the directory too
deleteQuietly(directory);
}
}
private void deleteQuietly(Path directory) {
try (var stream = Files.walk(directory)) {
stream.sorted(Comparator.reverseOrder()).forEach(path -> {
try {
Files.deleteIfExists(path);
} catch (IOException ignored) {
// best-effort cleanup
}
});
} catch (IOException ignored) {
// best-effort cleanup
}
}
}

View file

@ -53,6 +53,20 @@ skillhub:
moderation:
machine-review: ${SKILLHUB_PROFILE_MACHINE_REVIEW_ENABLED:true}
human-review: ${SKILLHUB_PROFILE_HUMAN_REVIEW_ENABLED:true}
authoring:
local-script:
# local development runs scripts on the host; production defaults to docker
execution-mode: ${SKILLHUB_AUTHORING_LOCAL_SCRIPT_MODE:inline}
openai-compatible:
# local fake LLM endpoints live on loopback
allow-private-endpoints: ${SKILLHUB_AUTHORING_LLM_ALLOW_PRIVATE:true}
mcp:
# local fake MCP servers live on loopback; link-local stays blocked
allow-private-endpoints: ${SKILLHUB_AUTHORING_MCP_ALLOW_PRIVATE:true}
# stdio servers may be exercised in local development
stdio-enabled: ${SKILLHUB_AUTHORING_MCP_STDIO_ENABLED:true}
# empty by default: envRefs are rejected in dev unless explicitly opened
env-allowlist: ${SKILLHUB_AUTHORING_MCP_ENV_ALLOWLIST:}
logging:
level:

View file

@ -234,6 +234,57 @@ skillhub:
max-package-size: 104857600 # 100MB
# allowed-file-extensions: uses SkillPackagePolicy.ALLOWED_EXTENSIONS by default
# Override via SKILLHUB_PUBLISH_ALLOWED_FILE_EXTENSIONS env var if needed
authoring:
# Root directory for per-run isolated validation workspaces
workspace-root: ${SKILLHUB_AUTHORING_WORKSPACE_ROOT:${java.io.tmpdir}/skillhub-authoring}
executor-threads: ${SKILLHUB_AUTHORING_EXECUTOR_THREADS:4}
# Hard wall-clock cap for one whole validation run (15 minutes)
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}
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}
profile:
moderation:
machine-review: ${SKILLHUB_PROFILE_MACHINE_REVIEW_ENABLED:true} # Enable machine review (e.g. sensitive word detection)

View file

@ -0,0 +1,130 @@
-- Skill authoring platform: drafts, draft files, runtime bindings, and validation
-- runs with their persisted events and findings. Drafts feed validated content into
-- the existing publish pipeline, so these tables are authored standalone and only
-- reference namespace/skill_version loosely (no circular foreign keys).
CREATE TABLE skill_draft (
id BIGSERIAL PRIMARY KEY,
namespace_id BIGINT NOT NULL REFERENCES namespace(id),
owner_id VARCHAR(128) NOT NULL,
name VARCHAR(128) NOT NULL,
requirement TEXT,
revision INT NOT NULL DEFAULT 1,
content_digest VARCHAR(64) NOT NULL,
validated_revision INT,
validated_run_id BIGINT,
submitted_skill_id BIGINT,
submitted_version_id BIGINT,
submitted_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
version BIGINT NOT NULL DEFAULT 0,
CONSTRAINT chk_skill_draft_revision CHECK (revision > 0)
);
-- Name uniqueness is enforced case-insensitively per owner.
CREATE UNIQUE INDEX uq_skill_draft_owner_name
ON skill_draft(owner_id, LOWER(name));
CREATE INDEX idx_skill_draft_owner_updated
ON skill_draft(owner_id, updated_at DESC);
CREATE INDEX idx_skill_draft_namespace
ON skill_draft(namespace_id);
-- File bodies live in object storage under content-addressed keys; this table tracks
-- identity, digest, and size only.
CREATE TABLE draft_file (
id BIGSERIAL PRIMARY KEY,
draft_id BIGINT NOT NULL REFERENCES skill_draft(id) ON DELETE CASCADE,
file_path VARCHAR(512) NOT NULL,
sha256 VARCHAR(64) NOT NULL,
size BIGINT NOT NULL,
content_type VARCHAR(128),
storage_key VARCHAR(768) NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT uq_draft_file_path UNIQUE (draft_id, file_path),
CONSTRAINT chk_draft_file_size CHECK (size >= 0)
);
CREATE INDEX idx_draft_file_draft
ON draft_file(draft_id);
CREATE INDEX idx_draft_file_storage_key
ON draft_file(storage_key);
-- One runtime binding per draft; secrets are referenced by name and resolved from
-- server-side configuration, never stored inline.
CREATE TABLE runtime_binding (
id BIGSERIAL PRIMARY KEY,
draft_id BIGINT NOT NULL REFERENCES skill_draft(id) ON DELETE CASCADE,
agent_type VARCHAR(32) NOT NULL,
config JSONB,
tool_allowlist JSONB,
mcp_servers JSONB,
updated_by VARCHAR(128),
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT uq_runtime_binding_draft UNIQUE (draft_id)
);
CREATE TABLE validation_run (
id BIGSERIAL PRIMARY KEY,
draft_id BIGINT NOT NULL REFERENCES skill_draft(id) ON DELETE CASCADE,
draft_revision INT NOT NULL,
status VARCHAR(20) NOT NULL,
cancel_requested BOOLEAN NOT NULL DEFAULT FALSE,
error_count INT NOT NULL DEFAULT 0,
warning_count INT NOT NULL DEFAULT 0,
summary JSONB,
triggered_by VARCHAR(128) NOT NULL,
started_at TIMESTAMPTZ,
finished_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
version BIGINT NOT NULL DEFAULT 0,
CONSTRAINT chk_validation_run_error_count CHECK (error_count >= 0),
CONSTRAINT chk_validation_run_warning_count CHECK (warning_count >= 0)
);
CREATE INDEX idx_validation_run_draft_created
ON validation_run(draft_id, created_at DESC);
-- Partial index keeps the active-run uniqueness cheap for the maintenance sweep.
CREATE INDEX idx_validation_run_status
ON validation_run(status)
WHERE status IN ('QUEUED', 'PREPARING', 'RUNNING');
CREATE INDEX idx_validation_run_stale_sweep
ON validation_run(status, created_at);
CREATE TABLE validation_event (
id BIGSERIAL PRIMARY KEY,
run_id BIGINT NOT NULL REFERENCES validation_run(id) ON DELETE CASCADE,
seq INT NOT NULL,
event_type VARCHAR(32) NOT NULL,
phase VARCHAR(32),
payload JSONB,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT uq_validation_event_seq UNIQUE (run_id, seq)
);
CREATE TABLE validation_finding (
id BIGSERIAL PRIMARY KEY,
run_id BIGINT NOT NULL REFERENCES validation_run(id) ON DELETE CASCADE,
layer VARCHAR(16) NOT NULL,
rule_code VARCHAR(64) NOT NULL,
severity VARCHAR(16) NOT NULL,
file_path VARCHAR(512),
location VARCHAR(128),
message TEXT NOT NULL,
suggestion JSONB,
status VARCHAR(16) NOT NULL DEFAULT 'OPEN',
applied_revision INT,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT chk_validation_finding_status
CHECK (status IN ('OPEN', 'APPLIED', 'DISMISSED'))
);
CREATE INDEX idx_validation_finding_run_status
ON validation_finding(run_id, status);

View file

@ -255,3 +255,44 @@ error.suite.bundle.operation.cancel.notAllowed=This Suite Bundle operation can n
error.suite.bundle.operation.retry.notAllowed=Only a retryable blocked Suite Bundle operation can be retried
error.suite.bundle.member.stateChanged=The bound Skill or version state changed; create a new Suite Bundle preview
error.suite.bundle.actor.inactive=The Suite Bundle actor is no longer active
# Skill authoring and validation platform
error.authoring.draft.notFound=Draft not found: {0}
error.authoring.draft.forbidden=You do not own this draft: {0}
error.authoring.draft.name.required=Draft name is required
error.authoring.draft.name.tooLong=Draft name must be at most {0} characters
error.authoring.draft.name.duplicate=You already have a draft named ''{0}''
error.authoring.draft.requirement.tooLong=Requirement text must be at most {0} characters
error.authoring.draft.notMember=You are not a member of namespace ''{0}''
error.authoring.draft.revision.conflict=Draft revision mismatch: expected {0} but current is {1}
error.authoring.namespace.notFound=Namespace not found: {0}
error.authoring.namespace.frozen=Namespace ''{0}'' is frozen and cannot receive new drafts
error.authoring.namespace.archived=Namespace ''{0}'' is archived and cannot receive new drafts
error.authoring.file.notFound=Draft file not found: {0}
error.authoring.file.path.invalid=Invalid draft file path: {0}
error.authoring.file.content.required=File content is required
error.authoring.file.tooLarge=File {0} exceeds the {1} byte limit
error.authoring.file.contentMismatch=File {0} content does not match its extension: {1}
error.authoring.file.countExceeded=Draft exceeds the maximum of {0} files
error.authoring.file.extension.disallowed=File extension is not allowed: {0}
error.authoring.package.tooLarge=Draft total size exceeds the {0} byte limit
error.authoring.patch.empty=No patches to apply
error.authoring.patch.fileExists=Patch target already exists: {0}
error.authoring.patch.fileMissing=Patch target not found: {0}
error.authoring.patch.stale=File ''{0}'' changed since the suggestion was generated
error.authoring.patch.noChange=The patch did not change the draft content
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
error.authoring.run.notFound=Validation run not found: {0}
error.authoring.run.activeExists=Draft {0} already has an active validation run
error.authoring.run.notQueued=Validation run {0} is not queued
error.authoring.run.cancelled=Validation run {0} was cancelled
error.authoring.run.terminal=Validation run {0} is already finished
error.authoring.finding.notFound=Validation finding not found: {0}
error.authoring.finding.noSuggestion=Finding {0} has no applicable fix suggestion
error.authoring.finding.applied=The fix for finding {0} was already applied
error.authoring.finding.suggestionUnreadable=The fix suggestion of finding {0} could not be read
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

View file

@ -209,3 +209,44 @@ error.suite.bundle.operation.cancel.notAllowed=Эту операцию паке
error.suite.bundle.operation.retry.notAllowed=Повторить можно только заблокированную операцию Skill Suite, допускающую повтор
error.suite.bundle.member.stateChanged=Состояние связанного Skill или версии изменилось; создайте новый предварительный просмотр пакета Skill Suite
error.suite.bundle.actor.inactive=Пользователь операции Skill Suite Bundle больше не активен
# Платформа создания и проверки навыков
error.authoring.draft.notFound=Черновик не найден: {0}
error.authoring.draft.forbidden=Вы не владеете этим черновиком: {0}
error.authoring.draft.name.required=Укажите название черновика
error.authoring.draft.name.tooLong=Название черновика не должно превышать {0} символов
error.authoring.draft.name.duplicate=У вас уже есть черновик с названием ''{0}''
error.authoring.draft.requirement.tooLong=Описание требований не должно превышать {0} символов
error.authoring.draft.notMember=Вы не участник пространства имён ''{0}''
error.authoring.draft.revision.conflict=Несовпадение ревизии черновика: ожидалась {0}, текущая {1}
error.authoring.namespace.notFound=Пространство имён не найдено: {0}
error.authoring.namespace.frozen=Пространство имён ''{0}'' заморожено, новые черновики недоступны
error.authoring.namespace.archived=Пространство имён ''{0}'' архивировано, новые черновики недоступны
error.authoring.file.notFound=Файл черновика не найден: {0}
error.authoring.file.path.invalid=Недопустимый путь к файлу черновика: {0}
error.authoring.file.content.required=Требуется содержимое файла
error.authoring.file.tooLarge=Файл {0} превышает ограничение в {1} байт
error.authoring.file.contentMismatch=Содержимое файла {0} не соответствует его расширению: {1}
error.authoring.file.countExceeded=Черновик превышает максимум в {0} файлов
error.authoring.file.extension.disallowed=Расширение файла не разрешено: {0}
error.authoring.package.tooLarge=Общий размер черновика превышает ограничение в {0} байт
error.authoring.patch.empty=Нет патчей для применения
error.authoring.patch.fileExists=Целевой файл патча уже существует: {0}
error.authoring.patch.fileMissing=Целевой файл патча не найден: {0}
error.authoring.patch.stale=Файл ''{0}'' изменился после формирования рекомендации
error.authoring.patch.noChange=Патч не изменил содержимое черновика
error.authoring.binding.notFound=Для черновика {0} не настроена привязка среды выполнения
error.authoring.binding.agentType.unknown=Неизвестный тип среды выполнения агента: {0}
error.authoring.binding.invalid=Недопустимая привязка среды выполнения: {0}
error.authoring.binding.unserializable=Привязка среды выполнения не может быть сериализована
error.authoring.run.notFound=Задача проверки не найдена: {0}
error.authoring.run.activeExists=У черновика {0} уже есть активная задача проверки
error.authoring.run.notQueued=Задача проверки {0} не в очереди
error.authoring.run.cancelled=Задача проверки {0} была отменена
error.authoring.run.terminal=Задача проверки {0} уже завершена
error.authoring.finding.notFound=Результат проверки не найден: {0}
error.authoring.finding.noSuggestion=Для результата {0} нет применимой рекомендации
error.authoring.finding.applied=Исправление результата {0} уже применено
error.authoring.finding.suggestionUnreadable=Не удалось прочитать рекомендацию для результата {0}
error.authoring.submit.notValidated=У ревизии {0} нет пройденной задачи проверки; сначала выполните проверку
error.authoring.submit.runActive=У черновика {0} есть активная задача проверки

View file

@ -255,3 +255,44 @@ error.suite.bundle.operation.cancel.notAllowed=该技能套件 Bundle 操作已
error.suite.bundle.operation.retry.notAllowed=只有处于可重试阻塞状态的技能套件 Bundle 操作才能重试
error.suite.bundle.member.stateChanged=绑定的技能或版本状态已经变化,请重新创建技能套件 Bundle 预览
error.suite.bundle.actor.inactive=技能套件 Bundle 的操作者已不再处于可用状态
# 技能创作与验证平台
error.authoring.draft.notFound=草稿不存在:{0}
error.authoring.draft.forbidden=你不是该草稿的所有者:{0}
error.authoring.draft.name.required=草稿名称不能为空
error.authoring.draft.name.tooLong=草稿名称不能超过 {0} 个字符
error.authoring.draft.name.duplicate=你已经有一个名为“{0}”的草稿
error.authoring.draft.requirement.tooLong=需求描述不能超过 {0} 个字符
error.authoring.draft.notMember=你不是命名空间“{0}”的成员
error.authoring.draft.revision.conflict=草稿版本不匹配:期望 {0},当前为 {1}
error.authoring.namespace.notFound=命名空间不存在:{0}
error.authoring.namespace.frozen=命名空间“{0}”已被冻结,无法创建新草稿
error.authoring.namespace.archived=命名空间“{0}”已被归档,无法创建新草稿
error.authoring.file.notFound=草稿文件不存在:{0}
error.authoring.file.path.invalid=非法的草稿文件路径:{0}
error.authoring.file.content.required=文件内容不能为空
error.authoring.file.tooLarge=文件 {0} 超过了 {1} 字节的上限
error.authoring.file.contentMismatch=文件 {0} 的内容与扩展名不匹配:{1}
error.authoring.file.countExceeded=草稿文件数超过了上限 {0}
error.authoring.file.extension.disallowed=不允许的文件扩展名:{0}
error.authoring.package.tooLarge=草稿总大小超过了 {0} 字节的上限
error.authoring.patch.empty=没有可应用的补丁
error.authoring.patch.fileExists=补丁目标文件已存在:{0}
error.authoring.patch.fileMissing=补丁目标文件不存在:{0}
error.authoring.patch.stale=文件“{0}”在建议生成后发生了变化
error.authoring.patch.noChange=补丁没有改变草稿内容
error.authoring.binding.notFound=草稿 {0} 尚未配置运行时绑定
error.authoring.binding.agentType.unknown=未知的 Agent 运行时类型:{0}
error.authoring.binding.invalid=运行时绑定不合法:{0}
error.authoring.binding.unserializable=运行时绑定无法序列化
error.authoring.run.notFound=验证任务不存在:{0}
error.authoring.run.activeExists=草稿 {0} 已有一个进行中的验证任务
error.authoring.run.notQueued=验证任务 {0} 不处于排队状态
error.authoring.run.cancelled=验证任务 {0} 已被取消
error.authoring.run.terminal=验证任务 {0} 已经结束
error.authoring.finding.notFound=验证问题项不存在:{0}
error.authoring.finding.noSuggestion=问题项 {0} 没有可应用的修复建议
error.authoring.finding.applied=问题项 {0} 的修复已被应用
error.authoring.finding.suggestionUnreadable=问题项 {0} 的修复建议无法解析
error.authoring.submit.notValidated=版本 {0} 没有通过的验证任务,请先执行验证
error.authoring.submit.runActive=草稿 {0} 有正在进行的验证任务

View file

@ -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
""";
}
}

View file

@ -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();
}
}

View file

@ -0,0 +1,128 @@
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() {
// a hostname that resolves nowhere is rejected for that reason; on
// networks whose DNS answers every query with a synthetic private
// range (some VPNs), the address classification rejects it instead —
// either way the endpoint must not pass silently
String rejection = policy.endpointRejection("http://this-host-does-not-exist.invalid/mcp",
AuthoringSecurityPolicy.EndpointUse.MCP_SERVER);
assertThat(rejection).isNotNull();
}
@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();
}
}

View file

@ -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;
}
};
}
}

View file

@ -0,0 +1,85 @@
package com.iflytek.skillhub.service.authoring.adapter;
import com.iflytek.skillhub.config.AuthoringProperties;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.assertThat;
/**
* Verifies the docker command line: every isolation flag must be present, the
* workspace mounted exactly once, and the script referenced by its
* container-relative path.
*/
class DockerScriptCommandBuilderTest {
private final AuthoringProperties properties = new AuthoringProperties();
private final DockerScriptCommandBuilder builder = new DockerScriptCommandBuilder(properties);
private final Path workspace = Path.of("/tmp/skillhub-authoring/run-42");
private final Path script = workspace.resolve("scripts/greet.sh");
private ScriptCommandBuilder.ScriptExecutionPlan plan() {
return builder.plan(workspace, "sh", script, List.of("arg1", "arg two"),
Map.of("PATH", "/usr/bin:/bin", "HOME", workspace.toString(), "LANG", "C.UTF-8"),
"42-greet");
}
@Test
void commandEnforcesIsolationProfile() {
List<String> command = plan().command();
assertThat(command).containsSubsequence(
List.of("docker", "run", "--rm", "--name", "skillhub-validation-42-greet"));
assertThat(command).containsSubsequence(List.of("--network", "none"));
assertThat(command).containsSubsequence(List.of("--memory", "256m"));
assertThat(command).containsSubsequence(List.of("--cpus", "1.0"));
assertThat(command).containsSubsequence(List.of("--pids-limit", "128"));
assertThat(command).contains("--read-only");
assertThat(command).containsSubsequence(List.of("--tmpfs", "/tmp:rw,size=64m"));
assertThat(command).containsSubsequence(List.of("--cap-drop", "ALL"));
assertThat(command).containsSubsequence(List.of("--security-opt", "no-new-privileges"));
assertThat(command).containsSubsequence(List.of("--log-driver", "none"));
}
@Test
void workspaceIsMountedAndScriptUsesContainerPath() {
List<String> command = plan().command();
assertThat(command).containsSubsequence(
List.of("-v", workspace + ":" + DockerScriptCommandBuilder.CONTAINER_WORKSPACE));
assertThat(command).containsSubsequence(List.of("-w", DockerScriptCommandBuilder.CONTAINER_WORKSPACE));
assertThat(command).contains("/workspace/scripts/greet.sh");
assertThat(command).endsWith("alpine:3.20", "sh", "/workspace/scripts/greet.sh", "arg1", "arg two");
}
@Test
void environmentIsPassedViaFlagsWithHomeRemapped() {
List<String> command = plan().command();
assertThat(command).contains("PATH=/usr/bin:/bin");
assertThat(command).contains("HOME=" + DockerScriptCommandBuilder.CONTAINER_WORKSPACE);
assertThat(command).contains("LANG=C.UTF-8");
// the docker CLI keeps its own environment to reach the daemon
assertThat(plan().environment()).isNull();
}
@Test
void containerNamesAreDockerSafe() {
assertThat(DockerScriptCommandBuilder.containerName("42-greet")).isEqualTo("skillhub-validation-42-greet");
assertThat(DockerScriptCommandBuilder.containerName("7-task/with spaces"))
.isEqualTo("skillhub-validation-7-task-with-spaces");
assertThat(DockerScriptCommandBuilder.containerName("task"))
.isEqualTo("skillhub-validation-task");
}
@Test
void dockerLimitsComeFromConfiguration() {
properties.getLocalScript().getDocker().setImage("python:3.12-alpine");
properties.getLocalScript().getDocker().setMemory("512m");
properties.getLocalScript().getDocker().setCpus("2.0");
List<String> command = plan().command();
assertThat(command).containsSubsequence(List.of("--memory", "512m"));
assertThat(command).containsSubsequence(List.of("--cpus", "2.0"));
assertThat(command).contains("python:3.12-alpine");
}
}

View file

@ -0,0 +1,120 @@
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.TaskResult;
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.List;
import java.util.Map;
import org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import static org.assertj.core.api.Assertions.assertThat;
/**
* Executes real behavior tasks through the docker backend and proves the
* isolation profile inside the container: no network interfaces beyond loopback,
* read-only root filesystem, and the workspace mounted writable. Skipped
* silently when no docker daemon is reachable.
*/
class DockerScriptRuntimeAdapterTest {
@TempDir
Path workspace;
private final AuthoringProperties properties = new AuthoringProperties();
@BeforeAll
static void requireDockerWithImage() {
DockerScriptCommandBuilder probe = new DockerScriptCommandBuilder(new AuthoringProperties());
Assumptions.assumeTrue(probe.available(), "docker daemon not reachable");
try {
Process pull = new ProcessBuilder("docker", "image", "inspect", "alpine:3.20").start();
if (pull.waitFor() != 0) {
new ProcessBuilder("docker", "pull", "alpine:3.20").start().waitFor();
}
} catch (Exception exception) {
Assumptions.assumeTrue(false, "alpine image unavailable: " + exception.getMessage());
}
}
private LocalScriptRuntimeAdapter dockerAdapter() {
properties.getLocalScript().setExecutionMode(AuthoringProperties.ScriptExecutionMode.DOCKER);
return new LocalScriptRuntimeAdapter(properties, List.of(
new InlineScriptCommandBuilder(), new DockerScriptCommandBuilder(properties)));
}
private record RecordingSink(List<String> logLines) implements RuntimeEventSink {
RecordingSink() {
this(new ArrayList<>());
}
@Override
public void agentMessage(String taskName, String content) {
}
@Override
public void toolCall(String taskName, String tool, String argumentsJson) {
}
@Override
public void toolResult(String taskName, String tool, String summaryJson) {
}
@Override
public void log(String taskName, String stream, String line) {
logLines.add(line);
}
}
private TaskResult runScript(String script) throws Exception {
Files.createDirectories(workspace.resolve("scripts"));
Files.writeString(workspace.resolve("scripts/task.sh"), script);
ValidationTaskSpec task = new ValidationTaskSpec("probe", "isolation probe",
com.iflytek.skillhub.domain.authoring.spec.TaskType.SCRIPT,
"scripts/task.sh", List.of(), null, 60_000, List.of());
RuntimeExecutionContext context = new RuntimeExecutionContext(
99L, workspace, Map.of("interpreter", "sh"), List.of(), () -> false);
return dockerAdapter().execute(context, task, new RecordingSink());
}
@Test
void runsScriptAndCapturesOutput() throws Exception {
TaskResult result = runScript("echo hello from docker\n");
assertThat(result.exitCode()).isZero();
assertThat(result.stdout()).contains("hello from docker");
}
@Test
void containerHasNoNetworkRoutes() throws Exception {
// with --network none the routing table is empty (header line only),
// so nothing beyond loopback is reachable
TaskResult result = runScript("tail -n +2 /proc/net/route | wc -l | tr -d ' '\n");
assertThat(result.exitCode()).isZero();
assertThat(result.stdout().trim()).isEqualTo("0");
}
@Test
void rootFilesystemIsReadOnly() throws Exception {
TaskResult result = runScript(
"if touch /etc/forbidden 2>/dev/null; then echo writable; else echo readonly; fi\n");
assertThat(result.exitCode()).isZero();
assertThat(result.stdout()).contains("readonly").doesNotContain("writable");
}
@Test
void workspaceIsWritableForArtifacts() throws Exception {
TaskResult result = runScript("mkdir -p artifacts && echo data > artifacts/out.txt && cat artifacts/out.txt\n");
assertThat(result.exitCode()).isZero();
assertThat(result.stdout()).contains("data");
assertThat(result.artifacts().read("artifacts/out.txt")).isPresent();
assertThat(new String(result.artifacts().read("artifacts/out.txt").orElseThrow()))
.contains("data");
}
}

View file

@ -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);
}
}
}

View file

@ -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");
}
}

View file

@ -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-");
}
}

View file

@ -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();
}
}

View file

@ -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);
}
}

View file

@ -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);
}
}

View file

@ -47,6 +47,19 @@ skillhub:
security:
scanner:
enabled: false
authoring:
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:

View file

@ -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);
}
}

View file

@ -0,0 +1,121 @@
package com.iflytek.skillhub.domain.authoring;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
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;
/**
* One file inside a skill draft. File bodies live in object storage under a
* content-addressed key; this record tracks identity, integrity digest, and size.
*/
@Entity
@Table(name = "draft_file",
uniqueConstraints = @jakarta.persistence.UniqueConstraint(
name = "uq_draft_file_path", columnNames = {"draft_id", "file_path"}))
public class DraftFile {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "draft_id", nullable = false)
private Long draftId;
@Column(name = "file_path", nullable = false, length = 512)
private String filePath;
@Column(nullable = false, length = 64)
private String sha256;
@Column(nullable = false)
private Long size;
@Column(name = "content_type", length = 128)
private String contentType;
@Column(name = "storage_key", nullable = false, length = 768)
private String storageKey;
@Column(name = "created_at", nullable = false, updatable = false)
private Instant createdAt;
@Column(name = "updated_at", nullable = false)
private Instant updatedAt;
protected DraftFile() {
}
public DraftFile(Long draftId, String filePath, String sha256, Long size,
String contentType, String storageKey) {
this.draftId = draftId;
this.filePath = filePath;
this.sha256 = sha256;
this.size = size;
this.contentType = contentType;
this.storageKey = storageKey;
}
@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 updateContent(String sha256, Long size, String contentType, String storageKey) {
this.sha256 = sha256;
this.size = size;
this.contentType = contentType;
this.storageKey = storageKey;
}
// Getters
public Long getId() {
return id;
}
public Long getDraftId() {
return draftId;
}
public String getFilePath() {
return filePath;
}
public String getSha256() {
return sha256;
}
public Long getSize() {
return size;
}
public String getContentType() {
return contentType;
}
public String getStorageKey() {
return storageKey;
}
public Instant getCreatedAt() {
return createdAt;
}
public Instant getUpdatedAt() {
return updatedAt;
}
}

View file

@ -0,0 +1,26 @@
package com.iflytek.skillhub.domain.authoring;
import java.util.List;
import java.util.Optional;
/**
* Domain repository contract for draft files.
*/
public interface DraftFileRepository {
DraftFile save(DraftFile file);
List<DraftFile> findByDraftIdOrderByFilePath(Long draftId);
Optional<DraftFile> findByDraftIdAndFilePath(Long draftId, String filePath);
List<DraftFile> findByDraftIdAndFilePathIn(Long draftId, List<String> filePaths);
void delete(DraftFile file);
void deleteByDraftId(Long draftId);
long countByDraftId(Long draftId);
long sumSizeByDraftId(Long draftId);
}

View file

@ -0,0 +1,19 @@
package com.iflytek.skillhub.domain.authoring;
import com.fasterxml.jackson.annotation.JsonIgnore;
import java.util.List;
/**
* A machine-applicable file replacement. {@code oldValue} is the exact current content
* (null when the file does not exist yet); applying the patch replaces it with
* {@code newValue}. {@code oldSha256} guards against applying a suggestion built on a
* stale revision of the file.
*/
public record FilePatch(String filePath, String oldSha256, String oldValue, String newValue) {
/** Derived helper, not part of the persisted shape. */
@JsonIgnore
public boolean isCreation() {
return oldValue == null;
}
}

View file

@ -0,0 +1,23 @@
package com.iflytek.skillhub.domain.authoring;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* A fix suggestion attached to a validation finding. Suggestions are proposals only:
* they are never applied without explicit user confirmation, and applying them always
* produces a new draft revision so history stays auditable.
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
@JsonIgnoreProperties(ignoreUnknown = true)
public record FixSuggestion(
String description,
@JsonProperty("patches") List<FilePatch> patches
) {
public List<FilePatch> safePatches() {
return patches == null ? List.of() : List.copyOf(patches);
}
}

View file

@ -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;
}
}

View file

@ -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);
}

View file

@ -0,0 +1,194 @@
package com.iflytek.skillhub.domain.authoring;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
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 jakarta.persistence.Version;
import java.time.Clock;
import java.time.Instant;
/**
* A skill authoring draft owned by one user. Drafts hold editable SKILL.md and resource files,
* are content-addressed by {@code contentDigest}, and advance a monotonically increasing
* {@code revision} on every content change. A draft is only submittable when its current
* revision matches a revision with a passing validation run.
*/
@Entity
@Table(name = "skill_draft")
public class SkillDraft {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "namespace_id", nullable = false)
private Long namespaceId;
@Column(name = "owner_id", nullable = false, length = 128)
private String ownerId;
@Column(nullable = false, length = 128)
private String name;
@Column(columnDefinition = "TEXT")
private String requirement;
@Column(name = "revision", nullable = false)
private Integer revision = 1;
@Column(name = "content_digest", nullable = false, length = 64)
private String contentDigest;
@Column(name = "validated_revision")
private Integer validatedRevision;
@Column(name = "validated_run_id")
private Long validatedRunId;
@Column(name = "submitted_skill_id")
private Long submittedSkillId;
@Column(name = "submitted_version_id")
private Long submittedVersionId;
@Column(name = "submitted_at")
private Instant submittedAt;
@Column(name = "created_at", nullable = false, updatable = false)
private Instant createdAt;
@Column(name = "updated_at", nullable = false)
private Instant updatedAt;
@Version
@Column(name = "version", nullable = false)
private Long optimisticVersion;
protected SkillDraft() {
}
public SkillDraft(Long namespaceId, String ownerId, String name, String requirement,
String contentDigest) {
this.namespaceId = namespaceId;
this.ownerId = ownerId;
this.name = name;
this.requirement = requirement;
this.contentDigest = contentDigest;
}
@PrePersist
protected void onCreate() {
Instant now = Instant.now(Clock.systemUTC());
createdAt = now;
updatedAt = now;
}
@PreUpdate
protected void onUpdate() {
updatedAt = Instant.now(Clock.systemUTC());
}
/**
* Marks the draft content as changed: bumps the revision and attaches the new digest.
* Validation state is intentionally preserved — callers compare
* {@code validatedRevision} against {@code revision} to decide whether the draft
* is still considered validated.
*/
public void applyContentChange(int newRevision, String newContentDigest) {
this.revision = newRevision;
this.contentDigest = newContentDigest;
}
public void markValidated(int validatedRevision, Long validatedRunId) {
this.validatedRevision = validatedRevision;
this.validatedRunId = validatedRunId;
}
public void markSubmitted(Long skillId, Long versionId, Instant submittedAt) {
this.submittedSkillId = skillId;
this.submittedVersionId = versionId;
this.submittedAt = submittedAt;
}
/** Returns true when the current revision has a passing validation run attached. */
public boolean isCurrentRevisionValidated() {
return validatedRevision != null && validatedRevision.equals(revision);
}
// Getters
public Long getId() {
return id;
}
public Long getNamespaceId() {
return namespaceId;
}
public String getOwnerId() {
return ownerId;
}
public String getName() {
return name;
}
public String getRequirement() {
return requirement;
}
public Integer getRevision() {
return revision;
}
public String getContentDigest() {
return contentDigest;
}
public Integer getValidatedRevision() {
return validatedRevision;
}
public Long getValidatedRunId() {
return validatedRunId;
}
public Long getSubmittedSkillId() {
return submittedSkillId;
}
public Long getSubmittedVersionId() {
return submittedVersionId;
}
public Instant getSubmittedAt() {
return submittedAt;
}
public Instant getCreatedAt() {
return createdAt;
}
public Instant getUpdatedAt() {
return updatedAt;
}
public Long getOptimisticVersion() {
return optimisticVersion;
}
// Setters
public void setName(String name) {
this.name = name;
}
public void setRequirement(String requirement) {
this.requirement = requirement;
}
}

View file

@ -0,0 +1,25 @@
package com.iflytek.skillhub.domain.authoring;
import java.util.List;
import java.util.Optional;
/**
* Domain repository contract for skill authoring drafts.
*/
public interface SkillDraftRepository {
SkillDraft save(SkillDraft draft);
Optional<SkillDraft> findById(Long id);
List<SkillDraft> findByOwnerIdOrderByUpdatedAtDesc(String ownerId);
List<SkillDraft> findByNamespaceId(Long namespaceId);
/** Case-insensitive uniqueness of (owner, name) used at creation time. */
Optional<SkillDraft> findByOwnerIdAndNameIgnoreCase(String ownerId, String name);
void delete(SkillDraft draft);
boolean existsByIdAndOwnerId(Long id, String ownerId);
}

View file

@ -0,0 +1,9 @@
/**
* Skill authoring drafts: editable skill packages owned by one user, validated in a
* controlled runtime before being submitted to the publish pipeline.
*
* <p>Contains the draft, draft file, and runtime binding aggregates together with
* their repository contracts. Validation execution state lives in the
* {@code com.iflytek.skillhub.domain.authoring.validation} package.
*/
package com.iflytek.skillhub.domain.authoring;

View file

@ -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;
}
}
}

View file

@ -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;
}
}

View file

@ -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);
}

View file

@ -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();
}
}

View file

@ -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;
}

View file

@ -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();
}

View file

@ -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));
}
}

View file

@ -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;

View file

@ -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);
}

View file

@ -0,0 +1,206 @@
package com.iflytek.skillhub.domain.authoring.service;
import com.iflytek.skillhub.domain.authoring.FixSuggestion;
import com.iflytek.skillhub.domain.authoring.FilePatch;
import com.iflytek.skillhub.domain.authoring.runtime.TaskResult;
import com.iflytek.skillhub.domain.authoring.validation.FindingDraft;
import com.iflytek.skillhub.domain.authoring.validation.ValidationLayer;
import com.iflytek.skillhub.domain.shared.exception.LocalizedDomainException;
import com.iflytek.skillhub.domain.skill.metadata.ComplianceMetadataService;
import com.iflytek.skillhub.domain.skill.metadata.SkillMetadataParser;
import com.iflytek.skillhub.domain.skill.validation.PackageEntry;
import com.iflytek.skillhub.domain.skill.validation.SkillPackagePolicy;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.springframework.stereotype.Service;
/**
* The STRUCTURE validation layer: package layout, SKILL.md frontmatter, file limits,
* and content/extension consistency. Mirrors the checks of the publish-time
* {@code SkillPackageValidator} rule by rule, but reports structured findings with
* machine-applicable fix suggestions instead of opaque error strings.
*
* <p>Package limits and path rules come from the shared {@link SkillPackagePolicy},
* so draft-time and publish-time rules cannot drift.
*/
@Service
public class DraftStructureValidator {
private final SkillMetadataParser metadataParser;
private final ComplianceMetadataService complianceMetadataService;
private final SkillScaffoldGenerator scaffoldGenerator;
public DraftStructureValidator(SkillMetadataParser metadataParser,
SkillScaffoldGenerator scaffoldGenerator) {
this.metadataParser = metadataParser;
this.complianceMetadataService = new ComplianceMetadataService();
this.scaffoldGenerator = scaffoldGenerator;
}
public record StructureReport(List<FindingDraft> findings, boolean skillMdPresent) {
public boolean hasErrors() {
return findings.stream().anyMatch(finding -> finding.severity()
== com.iflytek.skillhub.domain.authoring.validation.FindingSeverity.ERROR);
}
}
/**
* @param draftName draft name, used to build fix suggestions (e.g. missing SKILL.md)
* @param requirement original requirement text, reused in scaffold suggestions
*/
public StructureReport validate(String draftName, String requirement, List<PackageEntry> entries) {
List<FindingDraft> findings = new ArrayList<>();
Set<String> normalizedPaths = new HashSet<>();
PackageEntry skillMd = null;
long totalSize = 0;
for (PackageEntry entry : entries) {
String normalizedPath;
try {
normalizedPath = SkillPackagePolicy.normalizeEntryPath(entry.path());
} catch (IllegalArgumentException exception) {
findings.add(FindingDraft.error(ValidationLayer.STRUCTURE, "PATH_INVALID",
entry.path(), exception.getMessage(), null));
continue;
}
normalizedPath = SkillPackagePolicy.canonicalizeSkillMdPath(normalizedPath);
if (!normalizedPaths.add(normalizedPath)) {
findings.add(FindingDraft.error(ValidationLayer.STRUCTURE, "PATH_DUPLICATE",
normalizedPath, "Duplicate file path: " + normalizedPath, null));
}
if (!SkillPackagePolicy.hasAllowedExtension(normalizedPath)) {
findings.add(FindingDraft.warning(ValidationLayer.STRUCTURE, "EXTENSION_DISALLOWED",
normalizedPath, "Disallowed file extension: " + normalizedPath));
}
String contentMismatch = SkillPackagePolicy.validateContentMatchesExtension(
normalizedPath, entry.content());
if (contentMismatch != null) {
findings.add(FindingDraft.error(ValidationLayer.STRUCTURE, "CONTENT_MISMATCH",
normalizedPath, contentMismatch, null));
}
if (entry.size() > SkillPackagePolicy.MAX_SINGLE_FILE_SIZE) {
findings.add(FindingDraft.error(ValidationLayer.STRUCTURE, "FILE_TOO_LARGE",
normalizedPath, "File too large: " + normalizedPath + " ("
+ entry.size() + " bytes, max " + SkillPackagePolicy.MAX_SINGLE_FILE_SIZE + ")",
null));
}
if (SkillPackagePolicy.SKILL_MD_PATH.equals(normalizedPath) && skillMd == null) {
skillMd = entry;
}
totalSize += entry.size();
}
if (entries.size() > SkillPackagePolicy.MAX_FILE_COUNT) {
findings.add(FindingDraft.error(ValidationLayer.STRUCTURE, "FILE_COUNT_EXCEEDED", null,
"Too many files: " + entries.size() + " (max " + SkillPackagePolicy.MAX_FILE_COUNT + ")",
null));
}
if (totalSize > SkillPackagePolicy.MAX_TOTAL_PACKAGE_SIZE) {
findings.add(FindingDraft.error(ValidationLayer.STRUCTURE, "PACKAGE_TOO_LARGE", null,
"Package too large: " + totalSize + " bytes (max "
+ SkillPackagePolicy.MAX_TOTAL_PACKAGE_SIZE + ")", null));
}
if (skillMd == null) {
String scaffold = scaffoldGenerator.generateSkillMd(draftName, requirement);
findings.add(FindingDraft.error(ValidationLayer.STRUCTURE, "SKILL_MD_MISSING", null,
"Missing required file: SKILL.md at root",
new FixSuggestion("Create an initial SKILL.md scaffold",
List.of(new FilePatch(SkillPackagePolicy.SKILL_MD_PATH, null, null, scaffold)))));
return new StructureReport(findings, false);
}
String skillMdContent = new String(skillMd.content(), StandardCharsets.UTF_8);
try {
var metadata = metadataParser.parse(skillMdContent);
findings.addAll(complianceFindings(metadata.frontmatter(), entries));
} catch (LocalizedDomainException exception) {
findings.add(frontmatterFinding(exception, skillMdContent, draftName));
}
return new StructureReport(findings, true);
}
private List<FindingDraft> complianceFindings(Map<String, Object> frontmatter,
List<PackageEntry> entries) {
List<FindingDraft> findings = new ArrayList<>();
for (String problem : complianceMetadataService.validate(frontmatter, entries)) {
findings.add(FindingDraft.error(ValidationLayer.STRUCTURE, "COMPLIANCE_INVALID",
SkillPackagePolicy.SKILL_MD_PATH, problem, null));
}
return findings;
}
private FindingDraft frontmatterFinding(LocalizedDomainException exception,
String skillMdContent, String draftName) {
return switch (exception.messageCode()) {
case "error.skill.metadata.requiredField.missing" -> {
String field = String.valueOf(exception.messageArgs()[0]);
String replacement = insertFrontmatterField(skillMdContent, field,
suggestionValue(field, draftName));
yield FindingDraft.error(ValidationLayer.STRUCTURE, "FRONTMATTER_FIELD_MISSING",
SkillPackagePolicy.SKILL_MD_PATH,
"SKILL.md frontmatter is missing required field: " + field,
new FixSuggestion("Add required field '" + field + "'",
List.of(new FilePatch(SkillPackagePolicy.SKILL_MD_PATH,
TaskResult.sha256Hex(skillMdContent),
skillMdContent, replacement))));
}
case "error.skill.metadata.frontmatter.missingStart" -> FindingDraft.error(
ValidationLayer.STRUCTURE, "FRONTMATTER_MISSING_START",
SkillPackagePolicy.SKILL_MD_PATH,
"SKILL.md must start with a '---' frontmatter block", null);
case "error.skill.metadata.frontmatter.missingEnd" -> FindingDraft.error(
ValidationLayer.STRUCTURE, "FRONTMATTER_MISSING_END",
SkillPackagePolicy.SKILL_MD_PATH,
"SKILL.md frontmatter is missing the closing '---' marker", null);
case "error.skill.metadata.frontmatter.missingContent" -> FindingDraft.error(
ValidationLayer.STRUCTURE, "FRONTMATTER_EMPTY",
SkillPackagePolicy.SKILL_MD_PATH, "SKILL.md frontmatter is empty", null);
case "error.skill.metadata.yaml.notMap" -> FindingDraft.error(
ValidationLayer.STRUCTURE, "FRONTMATTER_NOT_MAP",
SkillPackagePolicy.SKILL_MD_PATH,
"SKILL.md frontmatter must be a YAML object", null);
case "error.skill.metadata.yaml.invalid" -> FindingDraft.error(
ValidationLayer.STRUCTURE, "FRONTMATTER_YAML_INVALID",
SkillPackagePolicy.SKILL_MD_PATH,
"SKILL.md frontmatter has invalid YAML: "
+ (exception.messageArgs().length > 0 ? exception.messageArgs()[0] : ""),
null);
default -> FindingDraft.error(ValidationLayer.STRUCTURE, "FRONTMATTER_INVALID",
SkillPackagePolicy.SKILL_MD_PATH, exception.messageCode(), null);
};
}
private String suggestionValue(String field, String draftName) {
return switch (field) {
case "name" -> draftName == null ? "my-skill" : draftName;
case "description" -> "TODO: describe what this skill does";
default -> "TODO";
};
}
/** Inserts {@code field: value} as the first line inside the frontmatter block. */
private String insertFrontmatterField(String content, String field, String value) {
String[] lines = content.split("\n", -1);
if (lines.length == 0 || !lines[0].trim().equals("---")) {
return "---\n" + field + ": " + value + "\n---\n" + content;
}
StringBuilder rebuilt = new StringBuilder();
rebuilt.append(lines[0]).append('\n');
rebuilt.append(field).append(": ").append(value).append('\n');
for (int i = 1; i < lines.length; i++) {
rebuilt.append(lines[i]);
if (i < lines.length - 1) {
rebuilt.append('\n');
}
}
return rebuilt.toString();
}
}

View file

@ -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());
}
}

View file

@ -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());
}
}

View file

@ -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());
}
}

View file

@ -0,0 +1,236 @@
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
* {@link AuthoringSecurityPolicy} so unsafe bindings are rejected at save time.
*/
@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");
private final AuthoringSecurityPolicy securityPolicy;
public RuntimeBindingValidator(AuthoringSecurityPolicy securityPolicy) {
this.securityPolicy = securityPolicy;
}
/**
* @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));
} 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()) {
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 {
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 {
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",
"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));
} 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)"));
}
}
}
}
/** 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;
}
}
}

View file

@ -0,0 +1,463 @@
package com.iflytek.skillhub.domain.authoring.service;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.iflytek.skillhub.domain.authoring.DraftFile;
import com.iflytek.skillhub.domain.authoring.FilePatch;
import com.iflytek.skillhub.domain.authoring.SkillDraft;
import com.iflytek.skillhub.domain.authoring.SkillDraftRepository;
import com.iflytek.skillhub.domain.authoring.DraftFileRepository;
import com.iflytek.skillhub.domain.namespace.Namespace;
import com.iflytek.skillhub.domain.namespace.NamespaceMemberRepository;
import com.iflytek.skillhub.domain.namespace.NamespaceRepository;
import com.iflytek.skillhub.domain.namespace.NamespaceStatus;
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 com.iflytek.skillhub.domain.skill.validation.PackageEntry;
import com.iflytek.skillhub.domain.skill.validation.SkillPackagePolicy;
import com.iflytek.skillhub.storage.ObjectStorageService;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.HexFormat;
import java.util.List;
import java.util.Locale;
import java.util.Optional;
import java.util.Set;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
/**
* Domain service for skill authoring drafts: creation with a scaffold, content-addressed
* file storage, revision and digest bookkeeping, patch application, and materialization
* into package entries for validation and submission.
*
* <p>Revisions advance only when content actually changes; a no-op save keeps the
* revision (and therefore a prior validation verdict) intact. Every content change
* recomputes the digest, which binds validation runs to exact draft content.
*/
@Service
public class SkillDraftService {
private static final Logger log = LoggerFactory.getLogger(SkillDraftService.class);
private static final int MAX_NAME_LENGTH = 128;
private static final int MAX_REQUIREMENT_LENGTH = 8_000;
private static final String SUPER_ADMIN = "SUPER_ADMIN";
public record SaveFileOutcome(SkillDraft draft, DraftFile file, boolean created, boolean revisionAdvanced) {}
private final SkillDraftRepository draftRepository;
private final DraftFileRepository fileRepository;
private final NamespaceRepository namespaceRepository;
private final NamespaceMemberRepository namespaceMemberRepository;
private final ObjectStorageService objectStorageService;
private final SkillScaffoldGenerator scaffoldGenerator;
private final ObjectMapper objectMapper;
public SkillDraftService(SkillDraftRepository draftRepository,
DraftFileRepository fileRepository,
NamespaceRepository namespaceRepository,
NamespaceMemberRepository namespaceMemberRepository,
ObjectStorageService objectStorageService,
SkillScaffoldGenerator scaffoldGenerator,
ObjectMapper objectMapper) {
this.draftRepository = draftRepository;
this.fileRepository = fileRepository;
this.namespaceRepository = namespaceRepository;
this.namespaceMemberRepository = namespaceMemberRepository;
this.objectStorageService = objectStorageService;
this.scaffoldGenerator = scaffoldGenerator;
this.objectMapper = objectMapper;
}
// ---------------------------------------------------------------- draft lifecycle
/**
* Creates a draft in the target namespace and seeds it with a SKILL.md scaffold
* derived from the requirement description.
*/
@Transactional
public SkillDraft createDraft(String namespaceSlug, String ownerId, String name,
String requirement, Set<String> platformRoles) {
validateName(name);
if (requirement != null && requirement.length() > MAX_REQUIREMENT_LENGTH) {
throw new DomainBadRequestException("error.authoring.draft.requirement.tooLong",
MAX_REQUIREMENT_LENGTH);
}
Namespace namespace = namespaceRepository.findBySlug(namespaceSlug)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.namespace.notFound", namespaceSlug));
assertNamespaceWritable(namespace);
assertNamespaceMember(namespace, ownerId, platformRoles);
if (draftRepository.findByOwnerIdAndNameIgnoreCase(ownerId, name).isPresent()) {
throw new DomainConflictException("error.authoring.draft.name.duplicate", name);
}
String scaffold = scaffoldGenerator.generateSkillMd(name, requirement);
SkillDraft draft = draftRepository.save(
new SkillDraft(namespace.getId(), ownerId, name, requirement, "pending"));
DraftFile scaffoldFile = storeFile(draft.getId(), SkillPackagePolicy.SKILL_MD_PATH,
scaffold.getBytes(StandardCharsets.UTF_8), "text/markdown");
fileRepository.save(scaffoldFile);
// the scaffold must be readable immediately: editor, structure validation,
// and submit all read it back from object storage
putContent(scaffoldFile.getStorageKey(), scaffold.getBytes(StandardCharsets.UTF_8),
"text/markdown");
draft.applyContentChange(1, computeDigest(draft.getId()));
return draftRepository.save(draft);
}
@Transactional(readOnly = true)
public List<SkillDraft> listDrafts(String ownerId) {
return draftRepository.findByOwnerIdOrderByUpdatedAtDesc(ownerId);
}
@Transactional(readOnly = true)
public SkillDraft getOwnedDraft(Long draftId, String userId, Set<String> platformRoles) {
SkillDraft draft = draftRepository.findById(draftId)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.draft.notFound", draftId));
assertOwner(draft, userId, platformRoles);
return draft;
}
/** Trusted accessor for internal executors (validation pipeline, submit flow). */
@Transactional(readOnly = true)
public SkillDraft getDraft(Long draftId) {
return draftRepository.findById(draftId)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.draft.notFound", draftId));
}
@Transactional
public void deleteDraft(Long draftId, String userId, Set<String> platformRoles) {
SkillDraft draft = getOwnedDraft(draftId, userId, platformRoles);
List<String> storageKeys = fileRepository.findByDraftIdOrderByFilePath(draftId).stream()
.map(DraftFile::getStorageKey)
.toList();
if (!storageKeys.isEmpty()) {
try {
objectStorageService.deleteObjects(storageKeys);
} catch (Exception exception) {
// storage garbage is not worth blocking a draft deletion; keys are
// namespaced under drafts/{draftId} and become unreachable
log.warn("Failed to clean up draft storage for draft {}: {}",
draftId, exception.getMessage());
}
}
draftRepository.delete(draft);
}
// ---------------------------------------------------------------- file editing
/**
* Saves one file. When {@code expectedRevision} is provided it must match the current
* revision, otherwise the save is rejected with a conflict (optimistic concurrency).
*/
@Transactional
public SaveFileOutcome saveFile(Long draftId, String userId, String rawPath, byte[] content,
String contentType, Integer expectedRevision,
Set<String> platformRoles) {
SkillDraft draft = getOwnedDraft(draftId, userId, platformRoles);
assertRevisionMatches(draft, expectedRevision);
String path = normalizeAndCheckPath(rawPath);
if (content == null) {
throw new DomainBadRequestException("error.authoring.file.content.required");
}
if (content.length > SkillPackagePolicy.MAX_SINGLE_FILE_SIZE) {
throw new DomainBadRequestException("error.authoring.file.tooLarge", path,
SkillPackagePolicy.MAX_SINGLE_FILE_SIZE);
}
String mismatch = SkillPackagePolicy.validateContentMatchesExtension(path, content);
if (mismatch != null) {
throw new DomainBadRequestException("error.authoring.file.contentMismatch", path, mismatch);
}
Optional<DraftFile> existing = fileRepository.findByDraftIdAndFilePath(draftId, path);
if (existing.isEmpty() && fileRepository.countByDraftId(draftId) >= SkillPackagePolicy.MAX_FILE_COUNT) {
throw new DomainBadRequestException("error.authoring.file.countExceeded",
SkillPackagePolicy.MAX_FILE_COUNT);
}
long currentTotal = fileRepository.sumSizeByDraftId(draftId)
- existing.map(DraftFile::getSize).orElse(0L);
if (currentTotal + content.length > SkillPackagePolicy.MAX_TOTAL_PACKAGE_SIZE) {
throw new DomainBadRequestException("error.authoring.package.tooLarge",
SkillPackagePolicy.MAX_TOTAL_PACKAGE_SIZE);
}
DraftFile file = existing
.map(current -> {
current.updateContent(sha256Hex(content), (long) content.length,
resolveContentType(path, contentType), storageKey(draftId, content));
return current;
})
.orElseGet(() -> storeFile(draftId, path, content, resolveContentType(path, contentType)));
file = fileRepository.save(file);
// write content after resolving the key so the same digest always lands in the same object
putContent(storageKey(draftId, content), content, resolveContentType(path, contentType));
boolean revisionAdvanced = advanceRevisionIfContentChanged(draft);
return new SaveFileOutcome(draft, file, existing.isEmpty(), revisionAdvanced);
}
@Transactional
public void deleteFile(Long draftId, String userId, String rawPath, Integer expectedRevision,
Set<String> platformRoles) {
SkillDraft draft = getOwnedDraft(draftId, userId, platformRoles);
assertRevisionMatches(draft, expectedRevision);
String path = normalizeAndCheckPath(rawPath);
DraftFile file = fileRepository.findByDraftIdAndFilePath(draftId, path)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.file.notFound", path));
fileRepository.delete(file);
advanceRevisionIfContentChanged(draft);
}
@Transactional(readOnly = true)
public List<DraftFile> listFiles(Long draftId) {
return fileRepository.findByDraftIdOrderByFilePath(draftId);
}
@Transactional(readOnly = true)
public FileContent readFile(Long draftId, String userId, String rawPath,
Set<String> platformRoles) {
getOwnedDraft(draftId, userId, platformRoles);
String path;
try {
path = SkillPackagePolicy.canonicalizeSkillMdPath(
SkillPackagePolicy.normalizeEntryPath(rawPath));
} catch (IllegalArgumentException exception) {
throw new DomainBadRequestException("error.authoring.file.path.invalid", rawPath);
}
DraftFile file = fileRepository.findByDraftIdAndFilePath(draftId, path)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.file.notFound", path));
byte[] content;
try (InputStream input = objectStorageService.getObject(file.getStorageKey())) {
content = input.readAllBytes();
} catch (IOException exception) {
throw new IllegalStateException("Failed to read draft file: " + path, exception);
}
return new FileContent(file, content);
}
public record FileContent(DraftFile file, byte[] content) {
public String asText() {
return new String(content, StandardCharsets.UTF_8);
}
}
// ---------------------------------------------------------------- patches
/**
* Applies a confirmed set of file patches atomically: every patch must target the
* exact current content (sha256 match), and the whole batch produces exactly one
* new draft revision.
*/
@Transactional
public SkillDraft applyPatch(Long draftId, String userId, List<FilePatch> patches,
Integer expectedRevision, Set<String> platformRoles) {
SkillDraft draft = getOwnedDraft(draftId, userId, platformRoles);
assertRevisionMatches(draft, expectedRevision);
if (patches == null || patches.isEmpty()) {
throw new DomainBadRequestException("error.authoring.patch.empty");
}
for (FilePatch patch : patches) {
String path = normalizeAndCheckPath(patch.filePath());
byte[] content = patch.newValue().getBytes(StandardCharsets.UTF_8);
String contentType = resolveContentType(path, null);
Optional<DraftFile> existing = fileRepository.findByDraftIdAndFilePath(draftId, path);
if (patch.isCreation()) {
if (existing.isPresent()) {
throw new DomainConflictException("error.authoring.patch.fileExists", path);
}
fileRepository.save(storeFile(draftId, path, content, contentType));
} else {
DraftFile current = existing.orElseThrow(() ->
new DomainConflictException("error.authoring.patch.fileMissing", path));
String currentSha = current.getSha256();
if (patch.oldSha256() == null || !patch.oldSha256().equalsIgnoreCase(currentSha)) {
throw new DomainConflictException("error.authoring.patch.stale", path);
}
current.updateContent(sha256Hex(content), (long) content.length,
contentType, storageKey(draftId, content));
fileRepository.save(current);
}
putContent(storageKey(draftId, content), content, contentType);
}
boolean advanced = advanceRevisionIfContentChanged(draft);
if (!advanced) {
// a patch that does not change the digest is a programming error upstream
throw new DomainBadRequestException("error.authoring.patch.noChange");
}
return draft;
}
// ---------------------------------------------------------------- materialization
/**
* Builds streaming package entries from the draft's current files. Used by the
* validation orchestrator (snapshot) and the submit flow (publish input).
*/
@Transactional(readOnly = true)
public List<PackageEntry> materializeEntries(Long draftId) {
List<PackageEntry> entries = new ArrayList<>();
for (DraftFile file : fileRepository.findByDraftIdOrderByFilePath(draftId)) {
entries.add(PackageEntry.streaming(
file.getFilePath(),
file.getSize(),
file.getContentType(),
() -> objectStorageService.getObject(file.getStorageKey())));
}
return entries;
}
@Transactional(readOnly = true)
public String computeDigest(Long draftId) {
List<DraftFile> files = new ArrayList<>(fileRepository.findByDraftIdOrderByFilePath(draftId));
files.sort(Comparator.comparing(DraftFile::getFilePath));
StringBuilder manifest = new StringBuilder();
for (DraftFile file : files) {
manifest.append(file.getFilePath()).append('\u0000')
.append(file.getSha256()).append('\n');
}
return sha256Hex(manifest.toString());
}
@Transactional(readOnly = true)
public String resolveNamespaceSlug(SkillDraft draft) {
return namespaceRepository.findById(draft.getNamespaceId())
.map(Namespace::getSlug)
.orElseThrow(() -> new DomainNotFoundException(
"error.authoring.namespace.notFound", draft.getNamespaceId()));
}
// ---------------------------------------------------------------- internals
private DraftFile storeFile(Long draftId, String path, byte[] content, String contentType) {
return new DraftFile(draftId, path, sha256Hex(content), (long) content.length,
contentType, storageKey(draftId, content));
}
private void putContent(String key, byte[] content, String contentType) {
if (!objectStorageService.exists(key)) {
objectStorageService.putObject(key, new ByteArrayInputStream(content),
content.length, contentType);
}
}
private boolean advanceRevisionIfContentChanged(SkillDraft draft) {
String newDigest = computeDigest(draft.getId());
if (newDigest.equals(draft.getContentDigest())) {
return false;
}
draft.applyContentChange(draft.getRevision() + 1, newDigest);
draftRepository.save(draft);
return true;
}
private String storageKey(Long draftId, byte[] content) {
return "drafts/" + draftId + "/" + sha256Hex(content);
}
private String resolveContentType(String path, String provided) {
if (provided != null && !provided.isBlank()) {
return provided;
}
String lower = path.toLowerCase(Locale.ROOT);
if (lower.endsWith(".md")) {
return "text/markdown";
}
if (lower.endsWith(".yaml") || lower.endsWith(".yml")) {
return "application/yaml";
}
if (lower.endsWith(".json")) {
return "application/json";
}
if (lower.endsWith(".py")) {
return "text/x-python";
}
if (lower.endsWith(".sh")) {
return "text/x-shellscript";
}
return "application/octet-stream";
}
private String normalizeAndCheckPath(String rawPath) {
String normalized;
try {
normalized = SkillPackagePolicy.canonicalizeSkillMdPath(
SkillPackagePolicy.normalizeEntryPath(rawPath));
} catch (IllegalArgumentException exception) {
throw new DomainBadRequestException("error.authoring.file.path.invalid", rawPath);
}
if (!SkillPackagePolicy.hasAllowedExtension(normalized)) {
throw new DomainBadRequestException("error.authoring.file.extension.disallowed", normalized);
}
return normalized;
}
private void assertRevisionMatches(SkillDraft draft, Integer expectedRevision) {
if (expectedRevision != null && !expectedRevision.equals(draft.getRevision())) {
throw new DomainConflictException("error.authoring.draft.revision.conflict",
expectedRevision, draft.getRevision());
}
}
private void validateName(String name) {
if (name == null || name.isBlank()) {
throw new DomainBadRequestException("error.authoring.draft.name.required");
}
if (name.length() > MAX_NAME_LENGTH) {
throw new DomainBadRequestException("error.authoring.draft.name.tooLong", MAX_NAME_LENGTH);
}
}
private void assertNamespaceWritable(Namespace namespace) {
if (namespace.getStatus() == NamespaceStatus.FROZEN) {
throw new DomainForbiddenException("error.authoring.namespace.frozen", namespace.getSlug());
}
if (namespace.getStatus() == NamespaceStatus.ARCHIVED) {
throw new DomainForbiddenException("error.authoring.namespace.archived", namespace.getSlug());
}
}
private void assertNamespaceMember(Namespace namespace, String userId, Set<String> platformRoles) {
if (platformRoles != null && platformRoles.contains(SUPER_ADMIN)) {
return;
}
if (namespaceMemberRepository
.findByNamespaceIdAndUserId(namespace.getId(), userId).isEmpty()) {
throw new DomainForbiddenException("error.authoring.draft.notMember", namespace.getSlug());
}
}
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());
}
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));
}
}

View file

@ -0,0 +1,78 @@
package com.iflytek.skillhub.domain.authoring.service;
import com.iflytek.skillhub.domain.namespace.SlugValidator;
import org.springframework.stereotype.Service;
/**
* Generates the initial SKILL.md scaffold for a new draft from the author's name and
* requirement description. Template-based by design: scaffolds are a starting point
* the author edits and validates; model-assisted generation remains an optional
* extension layered on top of this deterministic baseline.
*/
@Service
public class SkillScaffoldGenerator {
/**
* Builds the scaffold SKILL.md content.
*
* @param draftName the draft name chosen by the author
* @param requirement the natural-language requirement description
*/
public String generateSkillMd(String draftName, String requirement) {
String skillName = safeName(draftName);
String overview = requirement == null || requirement.isBlank()
? "Describe what this skill does and when an agent should use it."
: requirement.strip();
return """
---
name: %s
description: %s
---
# %s
## Overview
%s
## Usage
Describe step by step how an agent should apply this skill.
## Resources
- `references/` — background material the skill can cite
- `scripts/` — executable helpers invoked during task execution
""".formatted(skillName, singleLine(overview), skillName, overview);
}
/** Builds a starter validation.yaml with one script task template. */
public String generateValidationYaml() {
return """
version: 1
tasks:
- name: smoke
description: Replace with a real check for this skill
type: script
script: scripts/check.sh
args: []
timeoutMs: 30000
assertions:
- type: exit_code
equals: 0
""";
}
private String safeName(String draftName) {
try {
String slug = SlugValidator.slugify(draftName);
return slug == null || slug.isBlank() ? "my-skill" : slug;
} catch (Exception exception) {
return "my-skill";
}
}
private String singleLine(String text) {
return text.replaceAll("\\s+", " ").trim();
}
}

View file

@ -0,0 +1,256 @@
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.FindingDraft;
import com.iflytek.skillhub.domain.authoring.validation.ValidationEvent;
import com.iflytek.skillhub.domain.authoring.validation.ValidationEventType;
import com.iflytek.skillhub.domain.authoring.validation.ValidationFinding;
import com.iflytek.skillhub.domain.authoring.validation.ValidationFindingRepository;
import com.iflytek.skillhub.domain.authoring.validation.ValidationEventRepository;
import com.iflytek.skillhub.domain.authoring.validation.ValidationRun;
import com.iflytek.skillhub.domain.authoring.validation.ValidationRunRepository;
import com.iflytek.skillhub.domain.authoring.validation.ValidationRunStatus;
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.time.Clock;
import java.time.Instant;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.Set;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
/**
* Domain service for validation run lifecycle: starting runs bound to a frozen draft
* revision, appending ordered events, recording findings, and settling runs into
* terminal states. Events and findings commit in their own transactions so partial
* progress is always visible to SSE subscribers and polling clients.
*/
@Service
public class ValidationRunService {
private static final String SUPER_ADMIN = "SUPER_ADMIN";
private static final List<ValidationRunStatus> ACTIVE_STATUSES = List.of(
ValidationRunStatus.QUEUED, ValidationRunStatus.PREPARING, ValidationRunStatus.RUNNING);
private final ValidationRunRepository runRepository;
private final ValidationEventRepository eventRepository;
private final ValidationFindingRepository findingRepository;
private final SkillDraftRepository draftRepository;
private final Clock clock;
public ValidationRunService(ValidationRunRepository runRepository,
ValidationEventRepository eventRepository,
ValidationFindingRepository findingRepository,
SkillDraftRepository draftRepository,
Clock clock) {
this.runRepository = runRepository;
this.eventRepository = eventRepository;
this.findingRepository = findingRepository;
this.draftRepository = draftRepository;
this.clock = clock;
}
// ---------------------------------------------------------------- lifecycle
/**
* Creates a QUEUED run bound to the draft's current revision. Only one active run
* per draft is allowed.
*/
@Transactional
public ValidationRun startRun(Long draftId, String userId, Set<String> platformRoles) {
SkillDraft draft = draftRepository.findById(draftId)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.draft.notFound", draftId));
assertOwner(draft, userId, platformRoles);
if (runRepository.findByDraftIdOrderByCreatedAtDesc(draftId).stream()
.anyMatch(ValidationRun::isActive)) {
throw new DomainConflictException("error.authoring.run.activeExists", draftId);
}
return runRepository.save(
new ValidationRun(draftId, draft.getRevision(), userId));
}
/**
* Transitions a QUEUED run through PREPARING to RUNNING under a row lock, so
* cancellation and execution cannot interleave. Returns the refreshed run.
*/
@Transactional
public ValidationRun claimForExecution(Long runId) {
ValidationRun run = runRepository.findByIdForUpdate(runId)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.run.notFound", runId));
if (run.getStatus() == ValidationRunStatus.CANCELLED) {
throw new DomainConflictException("error.authoring.run.cancelled", runId);
}
if (run.getStatus() != ValidationRunStatus.QUEUED) {
throw new DomainConflictException("error.authoring.run.notQueued", runId);
}
if (run.isCancelRequested()) {
run.finish(ValidationRunStatus.CANCELLED, 0, 0, null, clock.instant());
return runRepository.save(run);
}
run.markPreparing();
run.markRunning(clock.instant());
return runRepository.save(run);
}
/**
* Idempotent cancel request. Sets the cooperative flag and settles QUEUED runs
* immediately; RUNNING/PREPARING runs are finished by their executor thread when
* it observes the flag (or by the maintenance sweep).
*/
@Transactional
public ValidationRun requestCancel(Long runId, String userId, Set<String> platformRoles) {
ValidationRun run = runRepository.findByIdForUpdate(runId)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.run.notFound", runId));
SkillDraft draft = draftRepository.findById(run.getDraftId())
.orElseThrow(() -> new DomainNotFoundException(
"error.authoring.draft.notFound", run.getDraftId()));
assertOwner(draft, userId, platformRoles);
if (!run.isActive()) {
return run; // already terminal: cancel is idempotent
}
run.requestCancel();
if (run.getStatus() == ValidationRunStatus.QUEUED) {
run.finish(ValidationRunStatus.CANCELLED, 0, 0,
Map.of("reason", "cancelled before start"), clock.instant());
}
return runRepository.save(run);
}
/**
* Settles a run into a terminal status if it is still active; returns empty when the
* run was already terminal (idempotent settle — the first terminal state wins). When
* the run succeeds with zero errors and the draft has not moved on, the draft is
* marked validated for this revision.
*/
@Transactional
public Optional<ValidationRun> settleIfActive(Long runId, ValidationRunStatus terminalStatus,
int errorCount, int warningCount,
Map<String, Object> summary) {
ValidationRun run = runRepository.findByIdForUpdate(runId)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.run.notFound", runId));
if (run.getStatus().isTerminal()) {
return Optional.empty();
}
run.finish(terminalStatus, errorCount, warningCount, summary, clock.instant());
ValidationRun settled = runRepository.save(run);
if (terminalStatus == ValidationRunStatus.SUCCEEDED && errorCount == 0) {
draftRepository.findById(settled.getDraftId()).ifPresent(draft -> {
if (draft.getRevision().equals(settled.getDraftRevision())) {
draft.markValidated(settled.getDraftRevision(), settled.getId());
draftRepository.save(draft);
}
});
}
return Optional.of(settled);
}
// ---------------------------------------------------------------- events & findings
/** Appends one event with the next sequence number; commits independently. */
@Transactional(propagation = Propagation.REQUIRES_NEW)
public ValidationEvent appendEvent(Long runId, ValidationEventType type, String phase,
Map<String, Object> payload) {
int nextSeq = eventRepository.findMaxSeqByRunId(runId).map(seq -> seq + 1).orElse(1);
return eventRepository.save(
new ValidationEvent(runId, nextSeq, type, phase, payload));
}
/** Records one finding and returns it; commits independently. */
@Transactional(propagation = Propagation.REQUIRES_NEW)
public ValidationFinding recordFinding(Long runId, FindingDraft draft) {
return findingRepository.save(new ValidationFinding(
runId, draft.layer(), draft.ruleCode(), draft.severity(),
draft.filePath(), draft.location(), draft.message(), draft.suggestion()));
}
// ---------------------------------------------------------------- queries
@Transactional(readOnly = true)
public ValidationRun getOwnedRun(Long runId, String userId, Set<String> platformRoles) {
ValidationRun run = runRepository.findById(runId)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.run.notFound", runId));
SkillDraft draft = draftRepository.findById(run.getDraftId())
.orElseThrow(() -> new DomainNotFoundException(
"error.authoring.draft.notFound", run.getDraftId()));
assertOwner(draft, userId, platformRoles);
return run;
}
/** Trusted accessor for internal executors (validation pipeline, maintenance sweep). */
@Transactional(readOnly = true)
public ValidationRun getRun(Long runId) {
return runRepository.findById(runId)
.orElseThrow(() -> new DomainNotFoundException("error.authoring.run.notFound", runId));
}
@Transactional(readOnly = true)
public List<ValidationRun> listRuns(Long draftId) {
return runRepository.findByDraftIdOrderByCreatedAtDesc(draftId);
}
@Transactional(readOnly = true)
public List<ValidationEvent> listEvents(Long runId, Integer afterSeq) {
if (afterSeq == null) {
return eventRepository.findByRunIdOrderBySeqAsc(runId);
}
return eventRepository.findByRunIdAndSeqGreaterThanOrderBySeqAsc(runId, afterSeq);
}
@Transactional(readOnly = true)
public List<ValidationFinding> listFindings(Long runId) {
List<ValidationFinding> findings = findingRepository.findByRunId(runId);
findings.sort(Comparator
.comparing(ValidationFinding::getSeverity)
.thenComparing(ValidationFinding::getId));
return findings;
}
@Transactional(readOnly = true)
public ValidationFinding getFinding(Long findingId) {
return findingRepository.findById(findingId)
.orElseThrow(() -> new DomainNotFoundException(
"error.authoring.finding.notFound", findingId));
}
@Transactional(readOnly = true)
public List<ValidationRun> findActiveRuns() {
return runRepository.findByStatusIn(ACTIVE_STATUSES);
}
@Transactional(readOnly = true)
public List<ValidationRun> findActiveRunsCreatedBefore(Instant cutoff) {
return runRepository.findByStatusInAndCreatedAtBefore(ACTIVE_STATUSES, cutoff);
}
/**
* The submission gate: the latest run bound to the draft's current revision must
* have succeeded with zero errors.
*/
@Transactional(readOnly = true)
public ValidationRun requirePassingRunForRevision(Long draftId, Integer revision) {
ValidationRun run = runRepository
.findFirstByDraftIdAndDraftRevisionOrderByCreatedAtDesc(draftId, revision)
.orElseThrow(() -> new DomainConflictException(
"error.authoring.submit.notValidated", revision));
if (run.getStatus() != ValidationRunStatus.SUCCEEDED || run.getErrorCount() > 0) {
throw new DomainConflictException("error.authoring.submit.notValidated", revision);
}
return run;
}
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());
}
}

View file

@ -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;
}
}

View file

@ -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
}

View file

@ -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();
}
}

View file

@ -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)));
}
}

View file

@ -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);
}
}

View file

@ -0,0 +1,4 @@
/**
* Behavior validation task specifications parsed from a draft's {@code validation.yaml}.
*/
package com.iflytek.skillhub.domain.authoring.spec;

View file

@ -0,0 +1,36 @@
package com.iflytek.skillhub.domain.authoring.validation;
import com.iflytek.skillhub.domain.authoring.FixSuggestion;
/**
* A finding produced by one validation layer, before it is persisted. The orchestrator
* converts these into {@link ValidationFinding} rows and emits FINDING events.
*/
public record FindingDraft(
ValidationLayer layer,
String ruleCode,
FindingSeverity severity,
String filePath,
String location,
String message,
FixSuggestion suggestion
) {
public static FindingDraft error(ValidationLayer layer, String ruleCode, String message) {
return new FindingDraft(layer, ruleCode, FindingSeverity.ERROR, null, null, message, null);
}
public static FindingDraft error(ValidationLayer layer, String ruleCode, String filePath,
String message, FixSuggestion suggestion) {
return new FindingDraft(layer, ruleCode, FindingSeverity.ERROR, filePath, null, message, suggestion);
}
public static FindingDraft warning(ValidationLayer layer, String ruleCode, String filePath,
String message) {
return new FindingDraft(layer, ruleCode, FindingSeverity.WARNING, filePath, null, message, null);
}
public static FindingDraft info(ValidationLayer layer, String ruleCode, String message) {
return new FindingDraft(layer, ruleCode, FindingSeverity.INFO, null, null, message, null);
}
}

View file

@ -0,0 +1,10 @@
package com.iflytek.skillhub.domain.authoring.validation;
/**
* Severity of a validation finding. A run only fails when at least one ERROR finding exists.
*/
public enum FindingSeverity {
ERROR,
WARNING,
INFO
}

Some files were not shown because too many files have changed in this diff Show more