@minus-ai/create-skill 0.1.0-beta.13 → 0.1.0-beta.15

package/index.mjs

@@ -520,7 +520,11 @@ async function main() {
   const vars = { skillId: skillResult.id, folder, className, displayName, description, namespace, port, nodeVersion, nodeMajor: String(NODE_MAJOR_FLOOR) }
 
   // Backend files (pipeline.py from input-type subdir)
-  writeOut(join(targetDir, 'pipeline.py'), render(readTemplate('pipeline.py.tpl', inputType), vars))
+  // 末尾统一追加 SDK 参考速查（纯注释单源模板），各场景模板不各自复制
+  writeOut(
+    join(targetDir, 'pipeline.py'),
+    render(readTemplate('pipeline.py.tpl', inputType), vars) + readTemplate('pipeline-reference.py.tpl')
+  )
   writeOut(join(targetDir, 'server.py'), render(readTemplate('server.py.tpl'), vars))
   writeOut(join(targetDir, 'pyproject.toml'), render(readTemplate('pyproject.toml.tpl'), vars))
   writeOut(join(targetDir, '.env.example'), render(readTemplate('env.example.tpl'), vars))
@@ -597,9 +601,11 @@ ${templateDocs[inputType] || templateDocs.custom}
 
 写代码前必须先了解 SDK 提供的能力，优先使用 SDK 已有的组件和方法，不要手写。
 
+⛔ 下面凡是 \`${platformUrl}/runtime/...\` 的远程文档，**一律用 \`curl -sSL '<url>'\` 抓取，不要用 WebFetch**：平台文档是 http + 非标准端口地址，WebFetch 连不上（TCP 层 ECONNREFUSED，与 http/https 无关），会把可达的文档误判成"读不到"而停止写代码。\`curl -sSL\` 走系统网络栈并自动跟随重定向，是唯一可靠取法；只有 \`curl\` 真的失败（连不上 / 非 2xx）才说明文档不可达。
+
 ### 开发手册
-写前端代码前，读以下开发手册：
-- 读 \`${platformUrl}/runtime/frontend-guide/doc.md\`
+写前端代码前，用 curl 抓取以下开发手册：
+- \`curl -sSL '${platformUrl}/runtime/frontend-guide/doc.md'\`
 - 手册包含：前后端数据契约（StepOutcome → StepRenderCtx）、Widget 选型与用法（defineWidgetStep、内置 Interactive/Display Widget）、自定义 Widget 开发、多语言接入。
 
 ### 后端 SDK 参考
@@ -608,9 +614,9 @@ ${templateDocs[inputType] || templateDocs.custom}
 - \`PipelineContext\`：读 \`.venv/**/minus_ai_sdk/pipeline/context.py\`
 
 ### 前端 SDK 参考
-@minus/* 包通过平台 CDN 加载，本地无源码。写前端代码前，读以下文档了解可用 API：
-- Widget 框架：读 \`${platformUrl}/runtime/widget-framework/docs.md\`
-- 平台组件：读 \`${platformUrl}/runtime/platform-widgets/docs.md\`
+@minus/* 包通过平台 CDN 加载，本地无源码。写前端代码前，用 curl 抓取以下文档了解可用 API：
+- Widget 框架：\`curl -sSL '${platformUrl}/runtime/widget-framework/docs.md'\`
+- 平台组件：\`curl -sSL '${platformUrl}/runtime/platform-widgets/docs.md'\`
 
 修改前端代码后，同步更新 \`frontend/src/locales/\` 下的多语言文件。
 
@@ -624,9 +630,10 @@ ${templateDocs[inputType] || templateDocs.custom}
   // README.md
   writeOut(join(targetDir, 'README.md'), render(readTemplate('README.md.tpl'), vars))
 
-  // frontend/assets/ 和 tests/ 目录
+  // frontend/assets/ 和 tests/ 目录（pytest 骨架：新 skill 天生带测试）
   writeOut(join(targetDir, 'frontend', 'assets', '.gitkeep'), '')
-  writeOut(join(targetDir, 'tests', '.gitkeep'), '')
+  writeOut(join(targetDir, 'tests', 'conftest.py'), render(readTemplate('conftest.py.tpl'), vars))
+  writeOut(join(targetDir, 'tests', 'test_pipeline.py'), render(readTemplate('test_pipeline.py.tpl'), vars))
 
   const rootPkgContent = render(readTemplate('root-package.json.tpl'), vars)
   const fePkgContent = render(readTemplate('frontend-package.json.tpl'), vars)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minus-ai/create-skill",
-  "version": "0.1.0-beta.13",
+  "version": "0.1.0-beta.15",
   "type": "module",
   "bin": {
     "create-skill": "index.mjs"

package/templates/conftest.py.tpl

@@ -0,0 +1,5 @@
+import sys
+from pathlib import Path
+
+# 项目根加进 sys.path，使 `import pipeline` 与运行时（server.py 同目录启动）一致
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

package/templates/frontend-package.json.tpl

@@ -11,7 +11,7 @@
     "sonner": "^2.0.7"
   },
   "devDependencies": {
-    "@minus-ai/dev-vite-plugin": "^0.1.0-beta.12",
+    "@minus-ai/dev-vite-plugin": "^0.1.0-beta.14",
     "@types/node": "^{{nodeMajor}}.0.0",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",

package/templates/pipeline-reference.py.tpl

@@ -0,0 +1,14 @@
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# SDK 参考（纯注释，读懂后可整段删除）
+#
+# StepOutcome 三态与 ctx 能力（entry_params / previous_outputs / last_user_input /
+# sif / llm / upload_file）的权威定义和用法，读已安装 SDK 的模块头注释与 docstring：
+#   .venv/**/minus_ai_sdk/pipeline/context.py
+#   .venv/**/minus_ai_sdk/pipeline/outcome.py
+# 不要凭记忆写签名——以上述源码为准（SDK 会原地更新，文档随包发布永不过期）。
+#
+# 唯一容易写反的语义：StepOutcome.input_required 暂停后，用户提交的内容
+# 挂在「下一步」的 ctx.last_user_input，而不是重跑本步。
+# ──────────────────────────────────────────────────────────────────────────────

package/templates/pyproject.toml.tpl

@@ -9,9 +9,16 @@ dependencies = [
     "uvicorn[standard]",
 ]
 
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio"]
+
 [tool.setuptools]
 py-modules = ["pipeline", "server"]
 
 [tool.uv]
 # SDK wheel 可能在同一版本号下更新过，安装时绕过本地缓存强制重新下载
 reinstall-package = ["minus-ai-sdk-python"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

package/templates/root-package.json.tpl

@@ -12,14 +12,12 @@
   },
   "workspaces": ["frontend"],
   "scripts": {
-    "dev": "minus-dev-cleanup && mkdir -p .minus && echo $$ > .minus/dev.pid && concurrently -n skill,fe \".venv/bin/uvicorn server:app --port {{port}} --reload --reload-include '*.py' --reload-include '.env.local' --env-file .env.local\" \"cd frontend && pnpm exec vite\"",
-    "dev:backend": "minus-dev-cleanup && mkdir -p .minus && echo $$ > .minus/backend.pid && .venv/bin/uvicorn server:app --port {{port}} --reload --reload-include '*.py' --reload-include '.env.local' --env-file .env.local",
-    "dev:win": "minus-dev --port {{port}}",
-    "dev:win:backend": "minus-dev --port {{port}} --backend-only",
-    "build": "cd frontend && pnpm run build"
+    "dev": "minus-dev --port {{port}}",
+    "dev:backend": "minus-dev --port {{port}} --backend-only",
+    "build": "cd frontend && pnpm run build",
+    "test": ".venv/bin/pytest tests"
   },
   "devDependencies": {
-    "@minus-ai/dev-vite-plugin": "^0.1.0-beta.12",
-    "concurrently": "^9.1.2"
+    "@minus-ai/dev-vite-plugin": "^0.1.0-beta.14"
   }
 }

package/templates/test_pipeline.py.tpl

@@ -0,0 +1,35 @@
+"""pipeline step 函数的 payload 结构测试骨架。
+
+约定（与平台测试体系一致）：
+- 直接调用 step 函数，不起 HTTP/SSE；外部 API 用 monkeypatch mock。
+- 断言 payload 的关键字段 + 类型，不断言会漂移的具体数据值。
+运行：.venv/bin/pytest（需先 .venv/bin/pip install pytest pytest-asyncio）
+"""
+from types import SimpleNamespace
+
+import pipeline as pl
+from minus_ai_sdk import StepOutcome
+
+
+class FakeContext:
+    """鸭子类型 PipelineContext：step 函数常用的成员。"""
+
+    def __init__(self, entry_params=None, last_user_input=None, previous_outputs=None):
+        self.entry_params = entry_params or {}
+        self.last_user_input = last_user_input or {}
+        self.previous_outputs = previous_outputs or {}
+        self.sif = SimpleNamespace()  # 外部 API 客户端按需 monkeypatch
+        self.emitted = []
+
+    async def emit(self, message_type, payload=None):
+        self.emitted.append((message_type, payload))
+
+
+async def test_step_1_returns_valid_outcome():
+    ctx = FakeContext(entry_params={})
+    outcome = await pl.{{className}}.step_1(SimpleNamespace(), ctx)
+    assert isinstance(outcome, StepOutcome)
+    assert isinstance(outcome.payload, dict)
+    # TODO: 按你的 step payload 契约补充关键字段断言，例如：
+    # assert outcome.kind.value == "input_required"
+    # assert isinstance(outcome.payload["rows"], list)