@quicktvui/ai 1.1.2 → 1.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/package.json +1 -1
  2. package/rules/.clinerules +29 -2
  3. package/rules/.cursorrules +29 -2
  4. package/rules/.windsurfrules +29 -2
  5. package/rules/AGENTS.md +31 -2
  6. package/rules/AI_HANDOFF.md +9 -1
  7. package/rules/CLAUDE.md +31 -2
  8. package/rules/GEMINI.md +38 -4
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quicktvui/ai",
3
- "version": "1.1.2",
3
+ "version": "1.1.5",
4
4
  "description": "QuickTVUI AI 开发规范与脚手架注入工具",
5
5
  "main": "index.js",
6
6
  "scripts": {
package/rules/.clinerules CHANGED
@@ -41,7 +41,34 @@ When asked to create a new QuickTVUI project, you MUST NOT generate a generic Vu
41
41
  2. **Clean Git**: `cd <project-name> && rm -rf .git`
42
42
  3. **Update Config**: Read `package.json`, modify the `"name"` to `<project-name>`, and reset `"version"` to `"1.0.0"`.
43
43
  4. **Install Deps**: `yarn install`
44
- 5. **Setup Reminder**: Remind the user to run `npm install -g @quicktvui/cli@latest` and `qui setup` if they haven't configured the environment (see https://quicktvui.com/zh-CN/guide/basic/quick-start.html).
44
+ 5. **Setup Reminder**: Remind the user to run `quicktvui-ai setup-all-env --project <project-path>` before TV debugging if environments are not prepared.
45
+
46
+ ## Run To TV Workflow (CRITICAL)
47
+
48
+ When user asks to "run project to TV", "run on device", "run on box", or similar runtime intent, AI MUST execute this order first and MUST NOT skip steps:
49
+
50
+ 1. `quicktvui-ai doctor --project <project-path>`
51
+ 2. `quicktvui-ai setup-vue-env --project <project-path>`
52
+ 3. `quicktvui-ai setup-android-env --project <project-path>`
53
+ 4. `quicktvui-ai run-dev --project <project-path>`
54
+
55
+ Hard requirements:
56
+
57
+ - Do NOT directly run `yarn dev` / `pnpm dev` / `npm run dev` before environment and device/runtime checks pass.
58
+ - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
59
+ - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
60
+ - AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
61
+ - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
62
+ - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
63
+ - Recommended check commands:
64
+ `adb -s <serial> shell cmd package resolve-activity -a android.intent.action.VIEW -d 'esapp://action/start?from=cmd&pkg=es.test' -p <runtime-package>`
65
+ and fallback:
66
+ `adb -s <serial> shell dumpsys package <runtime-package> | rg 'eskit\\.sdk\\.core\\.ui\\.BrowserProxyActivity|android.intent.action.VIEW|scheme=esapp|ES_ACTION_LAUNCH'`
67
+ - If the package/activity capability check fails, AI MUST stop run flow and ask user to reinstall runtime or provide the correct runtime package.
68
+ - After `quicktvui-ai run-dev --project <project-path>` reaches runtime launcher page, AI MUST send a confirm action (`adb shell input keyevent 23` or `66`, or equivalent click) on the runtime start button so runtime pulls/loads the dev bundle.
69
+ - AI MUST NOT stop at launcher page before triggering that confirm action, and MUST verify launch/bundle load result from logs or foreground activity status.
70
+ - If user asks to launch a specific ES app/version/source, run:
71
+ `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
45
72
 
46
73
  ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
47
74
 
@@ -428,4 +455,4 @@ AI MUST understand the mapping between Vue components and Java Native controller
428
455
  | **(Deprecated)** | `Text` | `com.tencent.mtt.hippy.views.text.HippyTextViewController` | **DEPRECATED** |
429
456
  | **(Deprecated)** | `ListView` | `com.tencent.mtt.hippy.views.list.HippyListViewController` | **DEPRECATED** |
430
457
 
431
- **Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
458
+ **Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
package/rules/.cursorrules CHANGED
@@ -41,7 +41,34 @@ When asked to create a new QuickTVUI project, you MUST NOT generate a generic Vu
41
41
  2. **Clean Git**: `cd <project-name> && rm -rf .git`
42
42
  3. **Update Config**: Read `package.json`, modify the `"name"` to `<project-name>`, and reset `"version"` to `"1.0.0"`.
43
43
  4. **Install Deps**: `yarn install`
44
- 5. **Setup Reminder**: Remind the user to run `npm install -g @quicktvui/cli@latest` and `qui setup` if they haven't configured the environment (see https://quicktvui.com/zh-CN/guide/basic/quick-start.html).
44
+ 5. **Setup Reminder**: Remind the user to run `quicktvui-ai setup-all-env --project <project-path>` before TV debugging if environments are not prepared.
45
+
46
+ ## Run To TV Workflow (CRITICAL)
47
+
48
+ When user asks to "run project to TV", "run on device", "run on box", or similar runtime intent, AI MUST execute this order first and MUST NOT skip steps:
49
+
50
+ 1. `quicktvui-ai doctor --project <project-path>`
51
+ 2. `quicktvui-ai setup-vue-env --project <project-path>`
52
+ 3. `quicktvui-ai setup-android-env --project <project-path>`
53
+ 4. `quicktvui-ai run-dev --project <project-path>`
54
+
55
+ Hard requirements:
56
+
57
+ - Do NOT directly run `yarn dev` / `pnpm dev` / `npm run dev` before environment and device/runtime checks pass.
58
+ - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
59
+ - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
60
+ - AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
61
+ - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
62
+ - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
63
+ - Recommended check commands:
64
+ `adb -s <serial> shell cmd package resolve-activity -a android.intent.action.VIEW -d 'esapp://action/start?from=cmd&pkg=es.test' -p <runtime-package>`
65
+ and fallback:
66
+ `adb -s <serial> shell dumpsys package <runtime-package> | rg 'eskit\\.sdk\\.core\\.ui\\.BrowserProxyActivity|android.intent.action.VIEW|scheme=esapp|ES_ACTION_LAUNCH'`
67
+ - If the package/activity capability check fails, AI MUST stop run flow and ask user to reinstall runtime or provide the correct runtime package.
68
+ - After `quicktvui-ai run-dev --project <project-path>` reaches runtime launcher page, AI MUST send a confirm action (`adb shell input keyevent 23` or `66`, or equivalent click) on the runtime start button so runtime pulls/loads the dev bundle.
69
+ - AI MUST NOT stop at launcher page before triggering that confirm action, and MUST verify launch/bundle load result from logs or foreground activity status.
70
+ - If user asks to launch a specific ES app/version/source, run:
71
+ `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
45
72
 
46
73
  ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
47
74
 
@@ -429,4 +456,4 @@ AI MUST understand the mapping between Vue components and Java Native controller
429
456
  | **(Deprecated)** | `Text` | `com.tencent.mtt.hippy.views.text.HippyTextViewController` | **DEPRECATED** |
430
457
  | **(Deprecated)** | `ListView` | `com.tencent.mtt.hippy.views.list.HippyListViewController` | **DEPRECATED** |
431
458
 
432
- **Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
459
+ **Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
package/rules/.windsurfrules CHANGED
@@ -41,7 +41,34 @@ When asked to create a new QuickTVUI project, you MUST NOT generate a generic Vu
41
41
  2. **Clean Git**: `cd <project-name> && rm -rf .git`
42
42
  3. **Update Config**: Read `package.json`, modify the `"name"` to `<project-name>`, and reset `"version"` to `"1.0.0"`.
43
43
  4. **Install Deps**: `yarn install`
44
- 5. **Setup Reminder**: Remind the user to run `npm install -g @quicktvui/cli@latest` and `qui setup` if they haven't configured the environment (see https://quicktvui.com/zh-CN/guide/basic/quick-start.html).
44
+ 5. **Setup Reminder**: Remind the user to run `quicktvui-ai setup-all-env --project <project-path>` before TV debugging if environments are not prepared.
45
+
46
+ ## Run To TV Workflow (CRITICAL)
47
+
48
+ When user asks to "run project to TV", "run on device", "run on box", or similar runtime intent, AI MUST execute this order first and MUST NOT skip steps:
49
+
50
+ 1. `quicktvui-ai doctor --project <project-path>`
51
+ 2. `quicktvui-ai setup-vue-env --project <project-path>`
52
+ 3. `quicktvui-ai setup-android-env --project <project-path>`
53
+ 4. `quicktvui-ai run-dev --project <project-path>`
54
+
55
+ Hard requirements:
56
+
57
+ - Do NOT directly run `yarn dev` / `pnpm dev` / `npm run dev` before environment and device/runtime checks pass.
58
+ - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
59
+ - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
60
+ - AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
61
+ - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
62
+ - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
63
+ - Recommended check commands:
64
+ `adb -s <serial> shell cmd package resolve-activity -a android.intent.action.VIEW -d 'esapp://action/start?from=cmd&pkg=es.test' -p <runtime-package>`
65
+ and fallback:
66
+ `adb -s <serial> shell dumpsys package <runtime-package> | rg 'eskit\\.sdk\\.core\\.ui\\.BrowserProxyActivity|android.intent.action.VIEW|scheme=esapp|ES_ACTION_LAUNCH'`
67
+ - If the package/activity capability check fails, AI MUST stop run flow and ask user to reinstall runtime or provide the correct runtime package.
68
+ - After `quicktvui-ai run-dev --project <project-path>` reaches runtime launcher page, AI MUST send a confirm action (`adb shell input keyevent 23` or `66`, or equivalent click) on the runtime start button so runtime pulls/loads the dev bundle.
69
+ - AI MUST NOT stop at launcher page before triggering that confirm action, and MUST verify launch/bundle load result from logs or foreground activity status.
70
+ - If user asks to launch a specific ES app/version/source, run:
71
+ `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
45
72
 
46
73
  ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
47
74
 
@@ -428,4 +455,4 @@ AI MUST understand the mapping between Vue components and Java Native controller
428
455
  | **(Deprecated)** | `Text` | `com.tencent.mtt.hippy.views.text.HippyTextViewController` | **DEPRECATED** |
429
456
  | **(Deprecated)** | `ListView` | `com.tencent.mtt.hippy.views.list.HippyListViewController` | **DEPRECATED** |
430
457
 
431
- **Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
458
+ **Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
package/rules/AGENTS.md CHANGED
@@ -41,7 +41,36 @@ When asked to create a new QuickTVUI project, you MUST NOT generate a generic Vu
41
41
  2. **Clean Git**: `cd <project-name> && rm -rf .git`
42
42
  3. **Update Config**: Read `package.json`, modify the `"name"` to `<project-name>`, and reset `"version"` to `"1.0.0"`.
43
43
  4. **Install Deps**: `yarn install`
44
- 5. **Setup Reminder**: Remind the user to run `npm install -g @quicktvui/cli@latest` and `qui setup` if they haven't configured the environment (see https://quicktvui.com/zh-CN/guide/basic/quick-start.html).
44
+ 5. **Setup Reminder**: Remind the user to run `quicktvui-ai setup-all-env --project <project-path>` before TV debugging if environments are not prepared.
45
+
46
+ ## Run To TV Workflow (CRITICAL)
47
+
48
+ When user asks to "run project to TV", "run on device", "run on box", or similar runtime intent, AI MUST execute this order first and MUST NOT skip steps:
49
+
50
+ 1. `quicktvui-ai doctor --project <project-path>`
51
+ 2. `quicktvui-ai setup-vue-env --project <project-path>`
52
+ 3. `quicktvui-ai setup-android-env --project <project-path>`
53
+ 4. `quicktvui-ai run-dev --project <project-path>`
54
+
55
+ Hard requirements:
56
+
57
+ - Do NOT directly run `yarn dev` / `pnpm dev` / `npm run dev` before environment and device/runtime checks pass.
58
+ - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
59
+ - AI MUST discover and use existing `quicktvui-ai-cli` commands first (`quicktvui-ai --help`, `quicktvui-ai <command> --help`) for env/device/runtime/run-to-TV operations.
60
+ - If a required step has no corresponding `quicktvui-ai-cli` command, AI MUST explicitly state the CLI gap first, then use a manual fallback workflow.
61
+ - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
62
+ - AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
63
+ - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
64
+ - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
65
+ - Recommended check commands:
66
+ `adb -s <serial> shell cmd package resolve-activity -a android.intent.action.VIEW -d 'esapp://action/start?from=cmd&pkg=es.test' -p <runtime-package>`
67
+ and fallback:
68
+ `adb -s <serial> shell dumpsys package <runtime-package> | rg 'eskit\\.sdk\\.core\\.ui\\.BrowserProxyActivity|android.intent.action.VIEW|scheme=esapp|ES_ACTION_LAUNCH'`
69
+ - If the package/activity capability check fails, AI MUST stop run flow and ask user to reinstall runtime or provide the correct runtime package.
70
+ - After `quicktvui-ai run-dev --project <project-path>` reaches runtime launcher page, AI MUST send a confirm action (`adb shell input keyevent 23` or `66`, or equivalent click) on the runtime start button so runtime pulls/loads the dev bundle.
71
+ - AI MUST NOT stop at launcher page before triggering that confirm action, and MUST verify launch/bundle load result from logs or foreground activity status.
72
+ - If user asks to launch a specific ES app/version/source, run:
73
+ `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
45
74
 
46
75
  ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
47
76
 
@@ -517,4 +546,4 @@ AI MUST understand the mapping between Vue components and Java Native controller
517
546
  | **(Deprecated)** | `Text` | `com.tencent.mtt.hippy.views.text.HippyTextViewController` | **DEPRECATED** |
518
547
  | **(Deprecated)** | `ListView` | `com.tencent.mtt.hippy.views.list.HippyListViewController` | **DEPRECATED** |
519
548
 
520
- **Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
549
+ **Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
package/rules/AI_HANDOFF.md CHANGED
@@ -44,7 +44,15 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
44
44
  2. **清理 Git**：`cd <项目名> && rm -rf .git`
45
45
  3. **更新配置**：读取 `package.json`，修改 `name` 为目标项目名称，重置 `version` 为 `1.0.0`。
46
46
  4. **安装依赖**：`yarn install`（推荐）。
47
- 5. **初始化提示**：提醒用户启动服务前，需确认是否已安装全局 CLI `npm install -g @quicktvui/cli@latest` 并执行了 `qui setup` 配置环境（详见 https://quicktvui.com/zh-CN/guide/basic/quick-start.html）。
47
+ 5. **初始化提示**：提醒用户 TV 调试前，若环境未准备，请先执行 `quicktvui-ai setup-all-env --project <project-path>`。
48
+
49
+ ## CLI 命令优先 (CRITICAL)
50
+
51
+ 涉及环境检测、设备检测、runtime 安装、运行到 TV 的操作时，AI 必须优先从 `quicktvui-ai-cli` 中查找并执行可用命令：
52
+
53
+ - 先执行 `quicktvui-ai --help` 和 `quicktvui-ai <command> --help` 确认可执行命令，再执行具体步骤。
54
+ - 不得在未检查 CLI 能力前直接进入 `yarn dev` / 手写 `adb` 流程。
55
+ - 若某一步骤在 `quicktvui-ai-cli` 中不存在对应命令，AI 必须先明确说明“CLI 暂不支持该步骤”，再走手工兜底流程。
48
56
 
49
57
  ---
50
58
 
package/rules/CLAUDE.md CHANGED
@@ -41,7 +41,36 @@
41
41
  2. **清理 Git**：`cd <项目名> && rm -rf .git`
42
42
  3. **更新配置**：读取 `package.json`，修改 `name` 为目标项目名称，重置 `version` 为 `1.0.0`。
43
43
  4. **安装依赖**：`yarn install`（推荐）。
44
- 5. **初始化提示**：提醒用户启动服务前，需确认是否已安装全局 CLI `npm install -g @quicktvui/cli@latest` 并执行了 `qui setup` 配置环境（详见 https://quicktvui.com/zh-CN/guide/basic/quick-start.html）。
44
+ 5. **初始化提示**：提醒用户 TV 调试前，若环境未准备，请先执行 `quicktvui-ai setup-all-env --project <project-path>`。
45
+
46
+ ## Run To TV Workflow (CRITICAL)
47
+
48
+ 当用户提出“运行到电视 / 运行到设备 / 运行到盒子”等诉求时，AI 必须先按以下顺序执行，且不得跳步：
49
+
50
+ 1. `quicktvui-ai doctor --project <project-path>`
51
+ 2. `quicktvui-ai setup-vue-env --project <project-path>`
52
+ 3. `quicktvui-ai setup-android-env --project <project-path>`
53
+ 4. `quicktvui-ai run-dev --project <project-path>`
54
+
55
+ Hard requirements:
56
+
57
+ - Do NOT directly run `yarn dev` / `pnpm dev` / `npm run dev` before environment and device/runtime checks pass.
58
+ - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
59
+ - AI MUST discover and use existing `quicktvui-ai-cli` commands first (`quicktvui-ai --help`, `quicktvui-ai <command> --help`) for env/device/runtime/run-to-TV operations.
60
+ - If a required step has no corresponding `quicktvui-ai-cli` command, AI MUST explicitly state the CLI gap first, then use a manual fallback workflow.
61
+ - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
62
+ - AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
63
+ - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
64
+ - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
65
+ - Recommended check commands:
66
+ `adb -s <serial> shell cmd package resolve-activity -a android.intent.action.VIEW -d 'esapp://action/start?from=cmd&pkg=es.test' -p <runtime-package>`
67
+ and fallback:
68
+ `adb -s <serial> shell dumpsys package <runtime-package> | rg 'eskit\\.sdk\\.core\\.ui\\.BrowserProxyActivity|android.intent.action.VIEW|scheme=esapp|ES_ACTION_LAUNCH'`
69
+ - If the package/activity capability check fails, AI MUST stop run flow and ask user to reinstall runtime or provide the correct runtime package.
70
+ - After `quicktvui-ai run-dev --project <project-path>` reaches runtime launcher page, AI MUST send a confirm action (`adb shell input keyevent 23` or `66`, or equivalent click) on the runtime start button so runtime pulls/loads the dev bundle.
71
+ - AI MUST NOT stop at launcher page before triggering that confirm action, and MUST verify launch/bundle load result from logs or foreground activity status.
72
+ - If user asks to launch a specific ES app/version/source, run:
73
+ `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
45
74
 
46
75
  ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)
47
76
 
@@ -892,4 +921,4 @@ AI 必须了解 Vue 组件与 Java Native 层的对应关系，避免查阅已
892
921
  | **(已废弃)** | `Text` | `com.tencent.mtt.hippy.views.text.HippyTextViewController` | **废弃** |
893
922
  | **(已废弃)** | `ListView` | `com.tencent.mtt.hippy.views.list.HippyListViewController` | **废弃** |
894
923
 
895
- **注意**：查阅源码时，优先进入 `.source/hippy/extend_views/` 目录。只有当该目录下没有对应组件时，才查阅 `.source/hippy/hippy_views/`。
924
+ **注意**：查阅源码时，优先进入 `.source/hippy/extend_views/` 目录。只有当该目录下没有对应组件时，才查阅 `.source/hippy/hippy_views/`。
package/rules/GEMINI.md CHANGED
@@ -26,6 +26,44 @@
26
26
  3. **核心库示例**：https://github.com/quicktvui/quicktvui.git
27
27
  4. **最佳实践应用**：https://github.com/quicktvui/hellotv.git
28
28
 
29
+ ## Project Scaffolding (CRITICAL)
30
+
31
+ When asked to create a new QuickTVUI project, AI MUST NOT generate a generic Vue project structure. Instead, follow these exact steps:
32
+ 1. **Clone Template**: `git clone https://github.com/quicktvui/quicktvui-template.git <project-name>`
33
+ 2. **Clean Git**: `cd <project-name> && rm -rf .git`
34
+ 3. **Update Config**: Read `package.json`, modify the `"name"` to `<project-name>`, and reset `"version"` to `"1.0.0"`.
35
+ 4. **Install Deps**: `yarn install`
36
+ 5. **Setup Reminder**: Remind the user to run `quicktvui-ai setup-all-env --project <project-path>` before TV debugging if environments are not prepared.
37
+
38
+ ## Run To TV Workflow (CRITICAL)
39
+
40
+ When user asks to "run project to TV", "run on device", "run on box", or similar runtime intent, AI MUST execute this order first and MUST NOT skip steps:
41
+
42
+ 1. `quicktvui-ai doctor --project <project-path>`
43
+ 2. `quicktvui-ai setup-vue-env --project <project-path>`
44
+ 3. `quicktvui-ai setup-android-env --project <project-path>`
45
+ 4. `quicktvui-ai run-dev --project <project-path>`
46
+
47
+ Hard requirements:
48
+
49
+ - Do NOT directly run `yarn dev` / `pnpm dev` / `npm run dev` before environment and device/runtime checks pass.
50
+ - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
51
+ - AI MUST discover and use existing `quicktvui-ai-cli` commands first (`quicktvui-ai --help`, `quicktvui-ai <command> --help`) for env/device/runtime/run-to-TV operations.
52
+ - If a required step has no corresponding `quicktvui-ai-cli` command, AI MUST explicitly state the CLI gap first, then use a manual fallback workflow.
53
+ - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
54
+ - AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
55
+ - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
56
+ - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
57
+ - Recommended check commands:
58
+ `adb -s <serial> shell cmd package resolve-activity -a android.intent.action.VIEW -d 'esapp://action/start?from=cmd&pkg=es.test' -p <runtime-package>`
59
+ and fallback:
60
+ `adb -s <serial> shell dumpsys package <runtime-package> | rg 'eskit\\.sdk\\.core\\.ui\\.BrowserProxyActivity|android.intent.action.VIEW|scheme=esapp|ES_ACTION_LAUNCH'`
61
+ - If the package/activity capability check fails, AI MUST stop run flow and ask user to reinstall runtime or provide the correct runtime package.
62
+ - After `quicktvui-ai run-dev --project <project-path>` reaches runtime launcher page, AI MUST send a confirm action (`adb shell input keyevent 23` or `66`, or equivalent click) on the runtime start button so runtime pulls/loads the dev bundle.
63
+ - AI MUST NOT stop at launcher page before triggering that confirm action, and MUST verify launch/bundle load result from logs or foreground activity status.
64
+ - If user asks to launch a specific ES app/version/source, run:
65
+ `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
66
+
29
67
  ---
30
68
 
31
69
  ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)
@@ -70,10 +108,6 @@ AI 在编写业务逻辑时，必须牢记以下框架特性，防止套用 Web
70
108
 
71
109
  ---
72
110
 
73
- ## 🚀 快速创建项目 (Scaffolding)
74
- AI 在创建新项目时，必须遵循：`git clone` 官方模板 -> 清理 `.git` -> 修改 `package.json` -> `yarn install`。
75
-
76
- ---
77
111
  ### 7. Native 组件映射与废弃说明 (Component Mapping & Deprecations)
78
112
  AI 必须了解 Vue 组件与 Java Native 层的对应关系，避免查阅已废弃的源码：
79
113