@minus-ai/create-skill 0.1.0-beta.2 → 0.1.0-beta.21

package/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { createInterface } from 'node:readline/promises'
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs'
 import { execSync } from 'node:child_process'
 import { createServer } from 'node:net'
 import { join, dirname } from 'node:path'
@@ -15,6 +15,46 @@ const CREDENTIALS_FILE = join(CREDENTIALS_DIR, 'credentials.json')
 
 const DEFAULT_PLATFORM_URL = 'http://47.107.144.22:18990'
 
+// create-skill 内 node 大版本的唯一写死处。模板里的 engines.node / volta.node /
+// @types/node 全部由它派生，不再各自硬编码。与 minus-plugin lib/toolchain.sh 的
+// NODE_TARGET 同义——两仓各自持有同一 major（create-skill 是独立 npm 包，发布时读不到
+// toolchain.sh，故不做运行时跨仓耦合）。升级大版本只改这一个值。
+const NODE_MAJOR_FLOOR = 24
+
+function nodeMajorOf(v) {
+  return parseInt(String(v).split('.')[0], 10) || 0
+}
+
+// 解析「生成项目实际会跑的那个 node」的确切 patch。Volta 不认 major-only/range，
+// volta.node 必须是确切 patch，所以这里返回一个真实存在的 x.y.z。三档：
+//   1. Volta 已装 ≥floor 的最新 node image —— 项目 dev（经 ~/.volta/bin/pnpm）真正会用
+//      且已安装 → 零下载。
+//   2. 没有合格 Volta image，但 create-skill 自身在跑的 node ≥floor —— pin 它（真实存在，
+//      进项目时 Volta 可能下载，但非凭空写死）。
+//   3. 哪里都找不到 ≥floor 的 node → 不编造版本，报错退出。
+function resolveProjectNodeVersion() {
+  const imageDir = join(homedir(), '.volta', 'tools', 'image', 'node')
+  if (existsSync(imageDir)) {
+    const best = readdirSync(imageDir)
+      .filter(name => /^\d+\.\d+\.\d+$/.test(name) && nodeMajorOf(name) >= NODE_MAJOR_FLOOR)
+      .sort((a, b) => {
+        const pa = a.split('.').map(Number)
+        const pb = b.split('.').map(Number)
+        return pb[0] - pa[0] || pb[1] - pa[1] || pb[2] - pa[2]
+      })[0]
+    if (best) return best
+  }
+
+  const running = process.versions.node
+  if (nodeMajorOf(running) >= NODE_MAJOR_FLOOR) return running
+
+  console.error(
+    `\n  ✗ 未找到 Node ${NODE_MAJOR_FLOOR}+。请安装 Node ${NODE_MAJOR_FLOOR}（推荐 https://volta.sh：\n` +
+      `    curl https://get.volta.sh | bash 后 volta install node@${NODE_MAJOR_FLOOR}）后重试。`
+  )
+  process.exit(1)
+}
+
 function findAvailablePort(start = 4001) {
   return new Promise(resolve => {
     const server = createServer()
@@ -28,7 +68,7 @@ function findAvailablePort(start = 4001) {
 // ── Naming helpers ──────────────────────────────────────
 
 function idToFolder(id) {
-  return id.replace(/[-\s]+/g, '_')
+  return id.trim().replace(/[\s/\\]+/g, '-')
 }
 
 function idToClassName(id) {
@@ -476,10 +516,15 @@ async function main() {
   const port = String(await findAvailablePort(4001))
   const apiKey = skillResult.apiKey
 
-  const vars = { skillId: skillResult.id, folder, className, displayName, description, namespace, port }
+  const nodeVersion = resolveProjectNodeVersion()
+  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))
@@ -504,6 +549,10 @@ async function main() {
 - 输入组件：\`AmazonSearchBar\` + \`CountrySelect\`（来自 @minus/platform-widgets）
 - 校验函数：\`validateAsins(value)\` — 校验 ASIN 格式，返回 { asins: string[], error? }
 - 支持单个或多个 ASIN 输入（逗号/换行分隔）
+- 数量限制：\`validateAsins(value, { min, max })\`
+  - 仅允许一个：\`validateAsins(value, { min: 1, max: 1 })\`
+  - 一个或多个：省略第二个参数
+  - 至少两个：\`validateAsins(value, { min: 2 })\`
 - 修改输入验证规则：编辑 frontend/src/main.tsx 中的 handleSubmit 函数
 - 修改 pipeline 步骤：编辑 pipeline.py 中的 step_N 方法`,
     keyword: `## 模板能力（inputType: keyword）
@@ -552,10 +601,12 @@ ${templateDocs[inputType] || templateDocs.custom}
 
 写代码前必须先了解 SDK 提供的能力，优先使用 SDK 已有的组件和方法，不要手写。
 
-### 开发手册
-写前端代码前，读以下开发手册：
-- 读 \`${join(__dirname, '../../runtime/frontend-guide')}/*/doc.md\`
-- 手册包含：前后端数据契约（StepOutcome → StepRenderCtx）、Widget 选型与用法（defineWidgetStep、内置 Interactive/Display Widget）、自定义 Widget 开发、多语言接入。
+⛔ 下面凡是 \`${platformUrl}/runtime/...\` 的远程文档，**一律用 \`curl -sSL '<url>'\` 抓取，不要用 WebFetch**：平台文档是 http + 非标准端口地址，WebFetch 连不上（TCP 层 ECONNREFUSED，与 http/https 无关），会把可达的文档误判成"读不到"而停止写代码。\`curl -sSL\` 走系统网络栈并自动跟随重定向，是唯一可靠取法；只有 \`curl\` 真的失败（连不上 / 非 2xx）才说明文档不可达。
+
+### 开发手册（索引）
+写前端代码前，用 curl 抓取以下开发手册：
+- \`curl -sSL '${platformUrl}/runtime/frontend-guide/doc.md'\`
+  索引按任务场景列出子文档路径（如 \`contract.md\`、\`step-summary.md\`）。根据当前任务 curl 对应子文档，不要一次性加载全部。
 
 ### 后端 SDK 参考
 写 pipeline.py 前，读以下本地文件了解可用 API：
@@ -563,12 +614,20 @@ ${templateDocs[inputType] || templateDocs.custom}
 - \`PipelineContext\`：读 \`.venv/**/minus_ai_sdk/pipeline/context.py\`
 
 ### 前端 SDK 参考
-@minus/* 包通过平台 CDN 加载，本地无源码。写前端代码前，读以下文档了解可用 API：
-- Widget 框架：读 \`${join(__dirname, '../../runtime/widget-framework')}/*/docs.md\`
-- 平台组件：读 \`${join(__dirname, '../../runtime/platform-widgets')}/*/docs.md\`
+@minus/* 包通过平台 CDN 加载，本地无源码。写前端代码前，用 curl 抓取以下文档了解可用 API：
+- Widget 框架（索引）：\`curl -sSL '${platformUrl}/runtime/widget-framework/docs.md'\`
+  索引按导出分类列出子文档路径（如 \`docs--step.md\`、\`docs--widget.md\`）。根据你要用的能力 curl 对应子文档，不要一次性加载全部。
+- 平台组件（索引）：\`curl -sSL '${platformUrl}/runtime/platform-widgets/docs.md'\`
+  索引列出所有组件摘要和子文档路径（如 \`docs--chart.md\`、\`docs--thumbgrid.md\`）。根据你要用的组件 curl 对应子文档，不要一次性加载全部。
+- 工具函数（索引）：\`curl -sSL '${platformUrl}/runtime/platform-utils/docs.md'\`
+  数值格式化工具（千分位、百分比、价格、评分等），直接 \`import { fmtNum, fmtPct, fmtPrice } from '@minus/platform-utils'\` 使用。函数增多后会拆为子文档，届时按索引 curl 对应子文档。
 
 修改前端代码后，同步更新 \`frontend/src/locales/\` 下的多语言文件。
 
+## 交互原则
+- **尽量一次只问一个问题** — 用户没有研发背景，避免同时抛出多个不相关的问题，逐步引导
+- 用简洁的日常语言解释技术概念，避免术语轰炸
+
 ## 开发约定
 - 新增 pipeline 步骤：在 pipeline.py 中添加 \`async def step_N(self, ctx)\` 方法
 - 新增前端步骤渲染：在 main.tsx 的 \`buildSteps\` 函数中添加步骤配置
@@ -579,9 +638,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)
@@ -595,10 +655,6 @@ ${templateDocs[inputType] || templateDocs.custom}
   writeOut(join(targetDir, 'frontend/tsconfig.json'), render(readTemplate('tsconfig.json.tpl'), vars))
   writeOut(join(targetDir, 'frontend/src/main.tsx'), render(readTemplate('main.tsx.tpl', inputType), vars))
   writeOut(join(targetDir, 'frontend/src/locales/zh-CN.json'), render(readTemplate('zh-CN.json.tpl', inputType), vars))
-  writeOut(join(targetDir, 'frontend/src/locales/en-US.json'), render(readTemplate('en-US.json.tpl', inputType), vars))
-
-  // 类型声明文件（让 tsc build 能识别 @minus/* 模块）
-  writeOut(join(targetDir, 'frontend/src/minus-runtime.d.ts'), `declare module '@minus/*';\n`)
 
   // 4. git init (skip if git not installed)
   try {

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@minus-ai/create-skill",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.21",
   "type": "module",
   "bin": {
-    "create-skill": "./index.mjs"
+    "create-skill": "index.mjs"
   },
   "files": [
     "index.mjs",

package/templates/README.md.tpl

@@ -6,7 +6,7 @@ Minus Skill 项目，由 `create-skill` 脚手架生成。
 
 | 依赖 | 最低版本 | 说明 |
 |---|---|---|
-| Node.js | >= 18 | 前端构建和开发服务 |
+| Node.js | >= {{nodeMajor}} | 前端构建和开发服务 |
 | pnpm | >= 9 | 包管理（全局 store 共享，多 skill 不重复下载） |
 | Python | >= 3.12 | 后端 Pipeline 运行时 |
 | uv | >= 0.4 | Python 包管理（全局缓存，秒级安装） |
@@ -45,7 +45,7 @@ pnpm install
 ```bash
 uv venv .venv
 source .venv/bin/activate    # Windows: .venv\Scripts\activate
-uv pip install -e .
+uv pip install -e . --reinstall-package minus-ai-sdk-python
 ```
 
 ## 配置
@@ -72,7 +72,7 @@ pnpm run dev
 ```
 
 这会同时启动：
-- **后端** — `uvicorn` 监听 `http://localhost:{{port}}`，修改 `.py` 文件自动重载
+- **后端** — `uvicorn` 监听 `http://127.0.0.1:{{port}}`，修改 `.py` 文件自动重载
 - **前端** — `vite` 开发服务，修改前端代码自动热更新
 
 单独启动前端：
@@ -107,10 +107,12 @@ pnpm run build
 
 | 命令 | 说明 |
 |---|---|
-| `pnpm run dev` | 启动开发环境（前后端） |
+| `pnpm run dev` | 启动开发环境（mac/Linux，前后端） |
+| `pnpm run dev:backend` | 仅启动后端（mac/Linux） |
+| `pnpm run dev:win` | 启动开发环境（Windows，前后端） |
+| `pnpm run dev:win:backend` | 仅启动后端（Windows） |
 | `pnpm run build` | 构建前端产物 |
 | `cd frontend && pnpm exec vite` | 仅启动前端 |
-| `.venv/bin/uvicorn server:app --port {{port}} --reload --env-file .env.local` | 仅启动后端 |
 
 ## 进入开发模式（Claude Code）
 

package/templates/asin/main.tsx.tpl

@@ -4,7 +4,6 @@ import { FlowApp, I18nProvider, mergeMessages, useT, type StepConfig } from '@mi
 import { AmazonSearchBar, CountrySelect, SearchSubmitButton, validateAsins, platformWidgetMessages } from '@minus/platform-widgets';
 import { Toaster } from 'sonner';
 import zhCN from './locales/zh-CN.json';
-import enUS from './locales/en-US.json';
 
 /*
  * 防御性编码提示（适用于所有 step render 函数）：
@@ -15,12 +14,12 @@ import enUS from './locales/en-US.json';
  * - 嵌套：(data.obj as Record<string, unknown> | undefined)?.field ?? fallback
  * 框架已有 Error Boundary 兜底，但不应依赖——优先在数据层做防御。
  */
-function buildSteps(t: (k: string, fb?: string) => string): StepConfig[] {
+function buildSteps(t: (k: string) => string): StepConfig[] {
   return [
     {
       render: ({ data }) => (
         <div className="minus-default-step-done">
-          {(data.text as string | undefined) ?? t('{{namespace}}.step.empty', '(空)')}
+          {(data.text as string | undefined) ?? t('{{namespace}}.step.empty')}
         </div>
       ),
     },
@@ -37,7 +36,7 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
   async function handleSubmit() {
     if (loading) return;
     const { asins, error: asinError } = validateAsins(value);
-    if (asinError) { setError(t(asinError.key, asinError.fallback, asinError.vars)); return; }
+    if (asinError) { setError(t(asinError.key, undefined, asinError.vars)); return; }
     setError(null);
     setLoading(true);
     try { await onStart({ asins: asins.join(','), country }); } finally { setLoading(false); }
@@ -60,7 +59,7 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
       <AmazonSearchBar
         onSubmit={handleSubmit}
         country={<CountrySelect onChange={setCountry} />}
-        input={<input type="text" value={value} onChange={(e) => { setValue(e.target.value); if (error) setError(null); }} placeholder={t('{{namespace}}.home.placeholder', '输入一个或多个ASIN')} spellCheck={false} disabled={loading} />}
+        input={<input type="text" value={value} onChange={(e) => { setValue(e.target.value); if (error) setError(null); }} placeholder={t('{{namespace}}.home.placeholder')} spellCheck={false} disabled={loading} />}
         submit={<SearchSubmitButton />}
         error={error}
       />
@@ -71,7 +70,7 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
 const rootEl = document.getElementById('root');
 if (!rootEl) throw new Error('#root not found');
 
-const skillMessages = mergeMessages(platformWidgetMessages, { 'zh-CN': zhCN as Record<string, string>, 'en-US': enUS as Record<string, string> });
+const skillMessages = mergeMessages(platformWidgetMessages, { 'zh-CN': zhCN as Record<string, string> });
 
 function SkillRoot() {
   const t = useT();

package/templates/asin/pipeline.py.tpl

@@ -8,4 +8,5 @@ class {{className}}(Pipeline):
         country: str = ctx.entry_params.get("country", "US")
 
         result = f"ASINs: {asins} ({country})"
+        # TODO: 实现「步骤1」的逻辑
         return StepOutcome.complete(payload={"text": result})

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/custom/main.tsx.tpl

@@ -4,7 +4,6 @@ import { FlowApp, I18nProvider, mergeMessages, useT, type StepConfig } from '@mi
 import { platformWidgetMessages } from '@minus/platform-widgets';
 import { Toaster } from 'sonner';
 import zhCN from './locales/zh-CN.json';
-import enUS from './locales/en-US.json';
 
 /*
  * 防御性编码提示（适用于所有 step render 函数）：
@@ -15,12 +14,12 @@ import enUS from './locales/en-US.json';
  * - 嵌套：(data.obj as Record<string, unknown> | undefined)?.field ?? fallback
  * 框架已有 Error Boundary 兜底，但不应依赖——优先在数据层做防御。
  */
-function buildSteps(t: (k: string, fb?: string) => string): StepConfig[] {
+function buildSteps(t: (k: string) => string): StepConfig[] {
   return [
     {
       render: ({ data }) => (
         <div className="minus-default-step-done">
-          {(data.text as string) ?? t('{{namespace}}.step.empty', '(空)')}
+          {(data.text as string) ?? t('{{namespace}}.step.empty')}
         </div>
       ),
     },
@@ -54,11 +53,11 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
       )}
       <div style={{ background: '#fff', border: '1px solid #e5e7eb', borderRadius: 8, padding: 20, display: 'flex', flexDirection: 'column', gap: 16, boxShadow: '0 1px 2px rgba(0,0,0,0.04)' }}>
         <label className="minus-field">
-          <span>{t('{{namespace}}.home.fieldLabel', '输入')}</span>
-          <input type="text" value={value} onChange={(e) => setValue(e.target.value)} placeholder={t('{{namespace}}.home.placeholder', '请输入...')} onKeyDown={(e) => e.key === 'Enter' && handleSubmit()} />
+          <span>{t('{{namespace}}.home.fieldLabel')}</span>
+          <input type="text" value={value} onChange={(e) => setValue(e.target.value)} placeholder={t('{{namespace}}.home.placeholder')} onKeyDown={(e) => e.key === 'Enter' && handleSubmit()} />
         </label>
         <button className="minus-btn minus-btn-primary" onClick={handleSubmit} disabled={!value.trim() || loading}>
-          {loading ? t('{{namespace}}.home.processing', '处理中…') : t('{{namespace}}.home.send', '开始')}
+          {loading ? t('{{namespace}}.home.processing') : t('{{namespace}}.home.send')}
         </button>
       </div>
     </div>
@@ -68,7 +67,7 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
 const rootEl = document.getElementById('root');
 if (!rootEl) throw new Error('#root not found');
 
-const skillMessages = mergeMessages(platformWidgetMessages, { 'zh-CN': zhCN as Record<string, string>, 'en-US': enUS as Record<string, string> });
+const skillMessages = mergeMessages(platformWidgetMessages, { 'zh-CN': zhCN as Record<string, string> });
 
 function SkillRoot() {
   const t = useT();

package/templates/custom/pipeline.py.tpl

@@ -6,4 +6,5 @@ class {{className}}(Pipeline):
     async def step_1(self, ctx: PipelineContext) -> StepOutcome:
         text: str = ctx.entry_params.get("text", "")
 
+        # TODO: 实现「步骤1」的逻辑
         return StepOutcome.complete(payload={"text": text})

package/templates/default/main.tsx.tpl

@@ -4,7 +4,6 @@ import { FlowApp, I18nProvider, mergeMessages, useT, type StepConfig } from '@mi
 import { CompletionPanel, platformWidgetMessages } from '@minus/platform-widgets';
 import { Toaster } from 'sonner';
 import zhCN from './locales/zh-CN.json';
-import enUS from './locales/en-US.json';
 
 /*
  * 防御性编码提示（适用于所有 step render 函数）：
@@ -15,12 +14,12 @@ import enUS from './locales/en-US.json';
  * - 嵌套：(data.obj as Record<string, unknown> | undefined)?.field ?? fallback
  * 框架已有 Error Boundary 兜底，但不应依赖——优先在数据层做防御。
  */
-function buildSteps(t: (k: string, fb?: string) => string): StepConfig[] {
+function buildSteps(t: (k: string) => string): StepConfig[] {
   return [
     {
       render: ({ data }) => (
         <div className="minus-default-step-done">
-          {(data.text as string | undefined) ?? t('{{namespace}}.step.empty', '(空)')}
+          {(data.text as string | undefined) ?? t('{{namespace}}.step.empty')}
         </div>
       ),
     },
@@ -61,7 +60,7 @@ if (!rootEl) throw new Error('#root not found');
 
 const skillMessages = mergeMessages(
   platformWidgetMessages,
-  { 'zh-CN': zhCN as Record<string, string>, 'en-US': enUS as Record<string, string> },
+  { 'zh-CN': zhCN as Record<string, string> },
 );
 
 function SkillRoot() {

package/templates/default/pipeline.py.tpl

@@ -4,5 +4,5 @@ from minus_ai_sdk import Pipeline, PipelineContext, StepOutcome
 class {{className}}(Pipeline):
 
     async def step_1(self, ctx: PipelineContext) -> StepOutcome:
-        # TODO: implement step logic
-        return StepOutcome.complete(payload={"text": "done"})
+        # TODO: 实现「步骤1」的逻辑
+        return StepOutcome.complete(payload={"text": "步骤1完成"})

package/templates/file/main.tsx.tpl

@@ -4,7 +4,6 @@ import { FlowApp, I18nProvider, mergeMessages, useT, type StepConfig } from '@mi
 import { FilePicker, uploadFile, platformWidgetMessages } from '@minus/platform-widgets';
 import { Toaster } from 'sonner';
 import zhCN from './locales/zh-CN.json';
-import enUS from './locales/en-US.json';
 
 /*
  * 防御性编码提示（适用于所有 step render 函数）：
@@ -15,12 +14,12 @@ import enUS from './locales/en-US.json';
  * - 嵌套：(data.obj as Record<string, unknown> | undefined)?.field ?? fallback
  * 框架已有 Error Boundary 兜底，但不应依赖——优先在数据层做防御。
  */
-function buildSteps(t: (k: string, fb?: string) => string): StepConfig[] {
+function buildSteps(t: (k: string) => string): StepConfig[] {
   return [
     {
       render: ({ data }) => (
         <div className="minus-default-step-done">
-          {(data.text as string) ?? t('{{namespace}}.step.empty', '(空)')}
+          {(data.text as string) ?? t('{{namespace}}.step.empty')}
         </div>
       ),
     },
@@ -35,14 +34,14 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
 
   async function handleSubmit() {
     if (loading) return;
-    if (!file) { setError(t('{{namespace}}.home.fileEmpty', '请选择一个文件')); return; }
+    if (!file) { setError(t('{{namespace}}.home.fileEmpty')); return; }
     setError(null);
     setLoading(true);
     try {
       const { fileId } = await uploadFile(file);
       await onStart({ fileId, fileName: file.name });
     } catch (e: any) {
-      setError(e?.message ?? t('{{namespace}}.home.uploadFailed', '文件上传失败'));
+      setError(e?.message ?? t('{{namespace}}.home.uploadFailed'));
     } finally {
       setLoading(false);
     }
@@ -64,12 +63,12 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
       )}
       <div style={{ background: '#fff', border: '1px solid #e5e7eb', borderRadius: 8, padding: 20, display: 'flex', flexDirection: 'column', gap: 16, boxShadow: '0 1px 2px rgba(0,0,0,0.04)' }}>
         <label className="minus-field">
-          <span>{t('{{namespace}}.home.fieldLabel', '文件')}</span>
+          <span>{t('{{namespace}}.home.fieldLabel')}</span>
           <FilePicker value={file} onChange={(f) => { setFile(f); if (error) setError(null); }} disabled={loading} />
         </label>
         {error && <p style={{ margin: 0, fontSize: 13, color: 'var(--minus-color-danger, #ef4444)' }}>{error}</p>}
         <button className="minus-btn minus-btn-primary" onClick={handleSubmit} disabled={!file || loading}>
-          {loading ? t('{{namespace}}.home.processing', '上传中…') : t('{{namespace}}.home.send', '开始')}
+          {loading ? t('{{namespace}}.home.processing') : t('{{namespace}}.home.send')}
         </button>
       </div>
     </div>
@@ -79,7 +78,7 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
 const rootEl = document.getElementById('root');
 if (!rootEl) throw new Error('#root not found');
 
-const skillMessages = mergeMessages(platformWidgetMessages, { 'zh-CN': zhCN as Record<string, string>, 'en-US': enUS as Record<string, string> });
+const skillMessages = mergeMessages(platformWidgetMessages, { 'zh-CN': zhCN as Record<string, string> });
 
 function SkillRoot() {
   const t = useT();

package/templates/file/pipeline.py.tpl

@@ -8,4 +8,5 @@ class {{className}}(Pipeline):
         file_name: str = ctx.entry_params.get("fileName", "")
 
         result = f"File: {file_name} (id: {file_id})"
+        # TODO: 实现「步骤1」的逻辑
         return StepOutcome.complete(payload={"text": result})

package/templates/frontend-package.json.tpl

@@ -5,14 +5,16 @@
   "type": "module",
   "scripts": {
     "build": "tsc -b && vite build",
-    "dev": "vite build --watch"
+    "check": "tsc --noEmit",
+    "dev": "vite build --watch",
+    "sync:types": "sync-types"
   },
   "dependencies": {
     "sonner": "^2.0.7"
   },
   "devDependencies": {
-    "@minus-ai/dev-vite-plugin": "^0.1.0-beta.1",
-    "@types/node": "^20.14.0",
+    "@minus-ai/dev-vite-plugin": "^0.1.0-beta.18",
+    "@types/node": "^{{nodeMajor}}.0.0",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",
     "@vitejs/plugin-react": "^4.3.1",

package/templates/keyword/main.tsx.tpl

@@ -4,7 +4,6 @@ import { FlowApp, I18nProvider, mergeMessages, useT, type StepConfig } from '@mi
 import { AmazonSearchBar, CountrySelect, SearchSubmitButton, validateKeywords, platformWidgetMessages } from '@minus/platform-widgets';
 import { Toaster } from 'sonner';
 import zhCN from './locales/zh-CN.json';
-import enUS from './locales/en-US.json';
 
 /*
  * 防御性编码提示（适用于所有 step render 函数）：
@@ -15,12 +14,12 @@ import enUS from './locales/en-US.json';
  * - 嵌套：(data.obj as Record<string, unknown> | undefined)?.field ?? fallback
  * 框架已有 Error Boundary 兜底，但不应依赖——优先在数据层做防御。
  */
-function buildSteps(t: (k: string, fb?: string) => string): StepConfig[] {
+function buildSteps(t: (k: string) => string): StepConfig[] {
   return [
     {
       render: ({ data }) => (
         <div className="minus-default-step-done">
-          {(data.text as string) ?? t('{{namespace}}.step.empty', '(空)')}
+          {(data.text as string) ?? t('{{namespace}}.step.empty')}
         </div>
       ),
     },
@@ -37,7 +36,7 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
   async function handleSubmit() {
     if (loading) return;
     const { keywords, error: kwError } = validateKeywords(value);
-    if (kwError) { setError(t(kwError.key, kwError.fallback, kwError.vars)); return; }
+    if (kwError) { setError(t(kwError.key, undefined, kwError.vars)); return; }
     setError(null);
     setLoading(true);
     try { await onStart({ keywords: keywords.join(','), country }); } finally { setLoading(false); }
@@ -60,7 +59,7 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
       <AmazonSearchBar
         onSubmit={handleSubmit}
         country={<CountrySelect onChange={setCountry} />}
-        input={<textarea value={value} onChange={(e) => { setValue(e.target.value); if (error) setError(null); }} onKeyDown={(e) => { if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); handleSubmit(); } }} placeholder={t('{{namespace}}.home.placeholder', '输入关键词，多个关键词用逗号或换行分隔')} spellCheck={false} disabled={loading} rows={1} />}
+        input={<textarea value={value} onChange={(e) => { setValue(e.target.value); if (error) setError(null); }} onKeyDown={(e) => { if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault(); handleSubmit(); } }} placeholder={t('{{namespace}}.home.placeholder')} spellCheck={false} disabled={loading} rows={1} />}
         submit={<SearchSubmitButton />}
         error={error}
       />
@@ -71,7 +70,7 @@ function Home({ title, description, useCases, tags, onStart }: { title: string;
 const rootEl = document.getElementById('root');
 if (!rootEl) throw new Error('#root not found');
 
-const skillMessages = mergeMessages(platformWidgetMessages, { 'zh-CN': zhCN as Record<string, string>, 'en-US': enUS as Record<string, string> });
+const skillMessages = mergeMessages(platformWidgetMessages, { 'zh-CN': zhCN as Record<string, string> });
 
 function SkillRoot() {
   const t = useT();

package/templates/keyword/pipeline.py.tpl

@@ -8,4 +8,5 @@ class {{className}}(Pipeline):
         country: str = ctx.entry_params.get("country", "US")
 
         result = f"Keywords: {keywords} ({country})"
+        # TODO: 实现「步骤1」的逻辑
         return StepOutcome.complete(payload={"text": result})

package/templates/main.tsx.tpl

@@ -4,7 +4,6 @@ import { FlowApp, I18nProvider, mergeMessages, useT, type StepConfig, type StepR
 import { AmazonSearchBar, CompletionPanel, CountrySelect, SearchSubmitButton, validateAsins, validateKeywords, platformWidgetMessages } from '@minus/platform-widgets';
 import { Toaster } from 'sonner';
 import zhCN from './locales/zh-CN.json';
-import enUS from './locales/en-US.json';
 
 type InputType = 'keyword' | 'asin';
 
@@ -17,12 +16,12 @@ type InputType = 'keyword' | 'asin';
  * - 嵌套：(data.obj as Record<string, unknown> | undefined)?.field ?? fallback
  * 框架已有 Error Boundary 兜底，但不应依赖——优先在数据层做防御。
  */
-function buildSteps(t: (k: string, fb?: string) => string): StepConfig[] {
+function buildSteps(t: (k: string) => string): StepConfig[] {
   return [
     {
       render: ({ data }) => (
         <div className="minus-default-step-done">
-          {(data.text as string) ?? t('{{namespace}}.step.empty', '(空)')}
+          {(data.text as string) ?? t('{{namespace}}.step.empty')}
         </div>
       ),
     },
@@ -55,7 +54,7 @@ function Home({
     if (inputType === 'asin') {
       const { asins, error: asinError } = validateAsins(value);
       if (asinError) {
-        setError(t(asinError.key, asinError.fallback, asinError.vars));
+        setError(t(asinError.key, undefined, asinError.vars));
         return;
       }
       setError(null);
@@ -68,7 +67,7 @@ function Home({
     } else {
       const { keywords, error: kwError } = validateKeywords(value);
       if (kwError) {
-        setError(t(kwError.key, kwError.fallback, kwError.vars));
+        setError(t(kwError.key, undefined, kwError.vars));
         return;
       }
       setError(null);
@@ -82,8 +81,8 @@ function Home({
   }
 
   const placeholder = inputType === 'keyword'
-    ? t('{{namespace}}.home.placeholderKeyword', '输入关键词，如 bluetooth earbuds')
-    : t('{{namespace}}.home.placeholderAsin', '输入一个或多个ASIN');
+    ? t('{{namespace}}.home.placeholderKeyword')
+    : t('{{namespace}}.home.placeholderAsin');
 
   return (
     <>
@@ -116,7 +115,7 @@ function Home({
               marginLeft: type === 'asin' ? -1 : 0,
             }}
           >
-            {t(`{{namespace}}.home.tab.${type}`, type === 'keyword' ? '关键词' : 'ASIN')}
+            {t(`{{namespace}}.home.tab.${type}`)}
           </button>
         ))}
       </div>
@@ -146,7 +145,7 @@ if (!rootEl) throw new Error('#root not found');
 
 const skillMessages = mergeMessages(
   platformWidgetMessages,
-  { 'zh-CN': zhCN as Record<string, string>, 'en-US': enUS as Record<string, string> },
+  { 'zh-CN': zhCN as Record<string, string> },
 );
 
 function SkillRoot() {

package/templates/pipeline-reference.py.tpl

@@ -0,0 +1,16 @@
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# 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，而不是重跑本步。
+# 凡是涉及 LLM 步骤摘要（放本步还是下一步、随哪个终态下发），判断标准和写法
+# 一律以前端开发手册子文档 step-summary.md 为准（取法见 CLAUDE.md「开发手册（索引）」）。
+# ──────────────────────────────────────────────────────────────────────────────

package/templates/pipeline.py.tpl

@@ -9,4 +9,5 @@ class {{className}}(Pipeline):
         country: str = ctx.entry_params.get("country", "US")
 
         result = f"[{input_type.upper()}] {value} ({country})"
+        # TODO: 实现「步骤1」的逻辑
         return StepOutcome.complete(payload={"text": result})

package/templates/pnpm-workspace.yaml.tpl

@@ -1,2 +1,15 @@
 packages:
   - frontend
+
+# pnpm 11 的 minimumReleaseAge 门槛会拒装"发布太近"的版本，导致内部包刚发布的新版被压回旧版。
+# @minus-ai/* 是平台内部高频迭代包，豁免门槛以保证新建项目总能拿到最新版。
+minimumReleaseAgeExclude:
+  - '@minus-ai/*'
+
+# pnpm 11.4 起用 allowBuilds 审批构建脚本；只写 onlyBuiltDependencies 会被忽略并报 ERR_PNPM_IGNORED_BUILDS（install exit 1）。
+allowBuilds:
+  esbuild: true
+
+# 兼容 pnpm 10.16+ 的旧机制，与 allowBuilds 共存无害。
+onlyBuiltDependencies:
+  - esbuild

package/templates/pyproject.toml.tpl

@@ -9,5 +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

@@ -3,17 +3,21 @@
   "description": "{{description}}",
   "private": true,
   "type": "module",
+  "engines": {
+    "node": ">={{nodeMajor}}"
+  },
+  "volta": {
+    "node": "{{nodeVersion}}",
+    "pnpm": "11.4.0"
+  },
   "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/dev.pid && .venv/bin/uvicorn server:app --port {{port}} --reload --reload-include '*.py' --reload-include '.env.local' --env-file .env.local",
-    "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.1",
-    "concurrently": "^9.1.2"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": ["esbuild"]
+    "@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)

package/templates/tsconfig.json.tpl

@@ -9,7 +9,11 @@
     "esModuleInterop": true,
     "skipLibCheck": true,
     "resolveJsonModule": true,
-    "noEmit": true
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@minus/*": ["./.minus/types/@minus/*"]
+    }
   },
-  "include": ["src"]
+  "include": ["src", ".minus/types"]
 }

package/templates/vite.config.ts.tpl

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { minusDev } from '@minus-ai/dev-vite-plugin';
 
 export default defineConfig({
-  plugins: [react(), ...minusDev({ localBackend: 'http://localhost:{{port}}' })],
+  plugins: [react(), ...minusDev({ localBackend: 'http://127.0.0.1:{{port}}' })],
   build: {
     target: 'esnext',
     outDir: path.resolve(__dirname, '../static'),