mpos-gen-app

name

mpos-gen-app

description

Generate, update, and repeatedly repair MicroPythonOS App code after requirements are confirmed. Use after mpos-analyze-app and optionally mpos-prepare-deps to create or modify an internal_filesystem/apps package directory with root MANIFEST.JSON, root icon_64x64.png, assets/*.py entrypoints/dependencies, dependency adapters, and validation results. Always defaults to a two-phase flow: first produce a generation plan and ask for confirmation, then write files only after explicit user confirmation. Supports repeated calls for user feature changes and test-failure repair loops. Does not analyze vague requirements, prepare external dependencies, package MPK files, deploy devices, flash firmware, publish to upystore, or rebuild lvgl_micropython.

MicroPythonOS App 代码生成

角色

把已确认的 MicroPythonOS App 需求落成代码。默认必须两阶段：

1. 确认阶段：只读上下文，输出生成/修改计划，列出将创建或修改的文件、版本策略、依赖接入、图标方案和校验命令，并请用户确认。此阶段不改文件。
2. 执行阶段：只有用户明确确认计划后，才创建、修改或修复 App 文件，并运行校验。

如果用户直接给自然语言想法但没有 mpos-analyze-app 结果，先路由到 mpos-analyze-app。如果需要外部纯 Python 驱动但没有 mpos-prepare-deps handoff，先路由到 mpos-prepare-deps。

用户可见语言

遵守 mpos-dev 的语言连续性规则：当前 workflow 从中文开始，生成计划、确认问题、校验摘要和修复说明继续用中文；从英文开始则继续用英文。代码、命令、路径、API 名和 JSON 字段名保持英文。

统一项目日志

plan/create/update/repair 每次产出 generation_result.json 或确认计划后，都必须登记到项目状态目录：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python \
  /home/leeqingshui/MicroPython_Skills/mpos-plan-app/scripts/update_plan_state.py record \
  --repo <repo-root> \
  --fullname <fullname> \
  --skill mpos-gen-app \
  --phase generate \
  --result <planned|success|partial|failed|blocked> \
  --artifact generation_result=<generation_result.json> \
  --next-skill <handoff.next_skill-or-null> \
  --event "Generated, updated, or repaired App files"

用户修改需求时，不要自己决定直接覆盖旧产物；先让 mpos-plan-app 列出将失效的 artifact 清单并等用户确认。两阶段确认仍强制执行，mpos-plan-app 不能替用户确认写文件。

mpos-plan-app 的路由、恢复或状态记录不等于用户确认写文件；必须由用户在 mpos-gen-app 计划之后明确确认，才能进入 create/update/repair 执行阶段。

必读上下文

生成或修改前先加载 mpos-dev，并按需读取：

• App/Activity/Service/Intent：mpos-dev/reference/docs-app-model.md
• 系统 manager、TaskManager、DownloadManager、WebServer、Service：mpos-dev/reference/docs-frameworks.md
• 打包和 manifest 校验：mpos-dev/reference/docs-packaging.md
• MPOS API 精确索引：mpos-dev/reference/mpos_api_summary.json
• LVGL API 精确索引：mpos-dev/reference/lvgl_api_summary.json
• 上游分析模板：mpos-analyze-app/templates/analysis_result.json
• 依赖 handoff 模板：mpos-prepare-deps/templates/dependency_handoff.json

本地事实优先：

• <repo-root>/AGENTS.md
• <repo-root>/tests/test_apps_manifest.py
• <repo-root>/internal_filesystem/lib/mpos/content/app_manager.py

mpos_api_summary.json 和 lvgl_api_summary.json 是强制输入，必须完整读取并用于生成计划和代码校验；不能因为 App 很简单就省略。计划阶段必须列出将使用的 mpos.* / lv.* API，并说明是否有仓库内现有 App 用例可参考。

模式

plan

默认模式。适用于新建 App、修改功能、或测试失败后修复请求的第一步。

必须输出：

• 目标 App：fullname、name、category、version。
• 发布者：manifest publisher，默认用 fullname 的组织前缀，例如 com.example 或 com.micropythonos。
• 操作类型：create、update 或 repair。
• 文件计划：要创建/修改/保留的文件。
• Activity/Service 计划。
• 依赖计划：是否消费 mpos-prepare-deps，是否要生成同步适配层。
• 图标计划：用 scripts/generate_icon.py 根据用户功能说明生成根目录 icon_64x64.png。
• 版本策略：新 App 1.0.0；功能修改 bump patch；测试失败修复不 bump。
• API 风险：逐项列出 lv.*、mpos.* 和 LVGL widget method 调用；任何不在 summary 中的 API 必须在计划阶段警告并换方案。
• 零参考 widget 风险：如果某个 LVGL widget 在仓库现有 App 中没有用例，必须 warning 并给出更简单替代方案。
• 校验计划：列出执行阶段要跑的门禁，必须包含 api_usage 和 app_only_changes。
• 需要确认的问题；没有阻塞问题时也必须询问“确认后我再写文件”。

create

用户确认后创建新 App。结构必须是：

internal_filesystem/apps/<fullname>/
  MANIFEST.JSON
  icon_64x64.png
  assets/<entrypoint>.py

MANIFEST.JSON 使用完整对象，不使用字符串型 activity：

{
  "fullname": "com.example.app",
  "name": "Example App",
  "publisher": "com.example",
  "version": "1.0.0",
  "category": "utilities",
  "activities": [
    {
      "classname": "ExampleActivity",
      "entrypoint": "assets/main.py",
      "intent_filters": [{"action": "main", "category": "launcher"}]
    }
  ],
  "services": []
}

update

用户修改功能时，先读取现有 App 的 manifest、entrypoint、assets、相关测试，再最小修改。不要重写无关文件，不要覆盖用户已有资源。功能修改默认 bump patch，例如 1.0.0 -> 1.0.1。

如果用户提出新增硬件、外部驱动或协议库，而没有依赖 handoff，停止并路由到 mpos-analyze-app 或 mpos-prepare-deps。

repair

测试失败或用户反馈运行失败时，读取失败日志、命令输出、traceback、上次 generation_result.json 和相关源码。只修自己生成或本轮明确涉及的 App 文件。

允许不限次数自动修复自己生成/修改的文件：每轮做最小 patch，重新运行失败门禁和必要的完整门禁，直到通过或遇到外部阻塞。外部阻塞包括缺少用户需求、缺少依赖 handoff、工具未安装、硬件事实变化、或失败来自非本 App 文件。

repair 不 bump version，除非用户明确要求把修复作为发布版本。

需求确认

写文件前必须确认这些内容：

• fullname 是否可接受，目录是否为 internal_filesystem/apps/<fullname>。
• publisher 是否可接受；缺失时默认从 fullname 前缀派生，例如 com.example.cc_skill_smoke -> com.example。
• App 可见行为和 MVP 范围。
• Activity/Service 数量和入口文件。
• 是否要接入 mpos-prepare-deps 的 runtime 文件、imports、adapter requirements。
• 生成图标是否按功能说明自动生成。
• 版本策略是否接受。
• 校验范围是否接受。

缺失非阻塞字段时给默认值，但仍要把默认值放入确认计划中。用户未确认时不写文件。

依赖接入

如果有 mpos-prepare-deps handoff：

• 把 runtime 文件放到 handoff 的 target_path，通常是 assets/<module>.py 或 assets/<package>/...。
• 如果 handoff 有 staged_path，从 staged cache 复制到 App 目录。
• 对 async_compatible=true 的依赖，按 imports[] 直接使用。
• 对 sync_needs_adapter=true 的依赖，必须生成 assets/<name>_adapter.py 或等价适配层，并把 handoff 的 adapter_requirements[] 逐条落实。
• 如果 requires_vendor_path_injection=true，只在 entrypoint 开头加入最小 path 注入：

import sys

_VENDOR_DIR = sys.path[0] + "/vendor"
if _VENDOR_DIR not in sys.path:
    sys.path.insert(0, _VENDOR_DIR)

不要把同步库直接放进 async def 或 LVGL 事件回调里阻塞执行。使用 TaskManager.create_task、TaskManager.sleep_ms、短周期状态机、timeout 和取消路径。

图标生成

新 App 或缺失图标时，使用本 skill 的脚本生成图标：

python3 /home/leeqingshui/MicroPython_Skills/mpos-gen-app/scripts/generate_icon.py \
  --prompt "<用户功能说明>" \
  --label "<App name>" \
  --output internal_filesystem/apps/<fullname>/icon_64x64.png

脚本只用 Python 标准库生成 64x64 PNG，不依赖 Pillow。图标应基于功能关键词选择简单符号；如果关键词不明确，用 App 名首字母。

代码规则

• 新代码优先从根 mpos 模块导入：from mpos import Activity, TaskManager, SharedPreferences。
• UI 代码必须 import lvgl as lv 并遵守 mpos-dev 的 LVGL 规则。
• 所有 lv.* / mpos.* / LVGL widget method 调用必须能通过 check_app_api_usage.py，禁止猜测不在 summary 中的 API，例如未列出的 set_style_row_gap()。
• lv.buttonmatrix.set_map() map 必须使用 "\n" 分隔行，并以 "" 终止；动态 map 必须在 warning 中说明已人工复核。
• 不硬编码屏幕分辨率，使用 lv.pct(100)、flex、align。
• 新 label 立即 set_text("") 或设置最终文本。
• lv.style_t() 后必须 init() 再 setter。
• 事件回调接受 event 参数，使用 obj.add_event_cb(callback, lv.EVENT.CLICKED, None)。
• 不给 LVGL 对象随意赋 Python 属性；用 closure、dict 或并行列表保存状态。
• 持久化用 SharedPreferences(self.appFullName)。
• 不写真实 API key、token、password、Bearer 到代码、manifest、测试、日志或 JSON。
• 不使用 CPython-only runtime 模块：typing、dataclasses、pathlib、logging、requests、subprocess、multiprocessing。
• 需要 asyncio 时优先 uasyncio；CPython fallback 只能用于测试兼容模式：

try:
    import uasyncio as asyncio
except ImportError:
    import asyncio

校验门禁

执行阶段每次写文件后必须运行并记录这些门禁。命令从 <repo-root> 仓库根执行。

1. App manifest 校验：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python -m unittest tests/test_apps_manifest.py

2. CPython 与 MicroPython 语法校验：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python \
  /home/leeqingshui/MicroPython_Skills/mpos-gen-app/scripts/check_app_syntax.py \
  --repo <repo-root> \
  --app-fullname <fullname>

check_app_syntax.py 默认会在缺少 <repo-root>/lvgl_micropython/lib/micropython/mpy-cross/build/mpy-cross 时尝试构建 mpy-cross。如果子模块缺失或构建失败，标记为 external/tooling blocked；不要把 MicroPython bytecode 编译门禁静默跳过。

3. MicroPython import 风险：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python \
  /home/leeqingshui/MicroPython_Skills/mpos-gen-app/scripts/check_app_mpy_imports.py \
  --app-dir internal_filesystem/apps/<fullname>

4. API 交叉校验：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python \
  /home/leeqingshui/MicroPython_Skills/mpos-gen-app/scripts/check_app_api_usage.py \
  --repo <repo-root> \
  --app-fullname <fullname>

该 gate 必须在写完代码后、进入 runtime 测试前执行。未知 API 是失败；buttonmatrix.set_map() 缺 "\n" 行分隔或末尾 "" 终止符是失败；零参考 widget 是 warning，必须在 generation_result.validation.warnings 记录替代方案或复核理由。

5. 项目 lint：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python \
  /home/leeqingshui/MicroPython_Skills/mpos-gen-app/scripts/prepare_lint_tooling.py \
  --repo <repo-root>

该 helper 先运行 make lint。如果失败原因是 uv 缺失，使用当前 Python 环境安装 uv，把该环境的 bin/ 放到 PATH 前面，然后重跑 make lint。如果 uv 安装失败、ruff 运行失败或 lint 超时，记录为 blocked；不要跳过。

6. flake8：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python -m flake8 \
  --config /home/leeqingshui/MicroPython_Skills/mpos-gen-app/templates/flake8-mpos-app.ini \
  internal_filesystem/apps/<fullname>

使用固定模板 templates/flake8-mpos-app.ini。该模板按当前全部真实 App 基线校准：只选 E9,F63,F7,F82，补充 MicroPython/native/viper/RP2 PIO 指令内建名，不全局忽略 F821；仅对 rp2_*.py、*_pio.py 做文件级 F821 忽略，避免 PIO 汇编伪操作数污染普通 Python 检查。如果新生成 App 出现未定义名，修代码，不要临时放宽模板。

7. pylint。使用固定 MicroPython-aware rcfile，不要改仓库配置：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python -m pylint \
  --persistent=n \
  --rcfile=/home/leeqingshui/MicroPython_Skills/mpos-gen-app/templates/pylintrc-mpos-app \
  internal_filesystem/apps/<fullname>/assets

使用固定模板 templates/pylintrc-mpos-app。该模板按当前全部真实 App 基线校准：忽略 MicroPython/MPOS 导入、LVGL 动态成员、docstring、命名和历史风格噪声；保留 fatal/error/usage 类问题，例如 undefined-variable、used-before-assignment、function-redefined、no-method-argument。不要把 x、y、pin 这类普通变量名加入全局 builtins；若确实生成 RP2 PIO helper，只允许在该 helper 文件头局部声明 # pylint: disable=undefined-variable 并在 generation_result.validation.warnings 记录原因。Pylint exit code 是 bitmask：fatal(1)、error(2)、usage(32) 是强失败；warning(4)、refactor(8)、convention(16) 只记录 warning，除非用户要求严格模式。

8. 清理缓存产物：

find internal_filesystem/apps/<fullname> \( -name __pycache__ -o -name '*.pyc' \) -print

如果有输出，删除后重跑相关门禁。不要把 __pycache__/ 或 .pyc 写入交接 JSON。

9. App-only 变更检查：

PYTHONDONTWRITEBYTECODE=1 /home/leeqingshui/mp_env/bin/python \
  /home/leeqingshui/MicroPython_Skills/mpos-dev/scripts/check_app_only_changes.py \
  --repo <repo-root> \
  --app-fullname <fullname>

该 gate 只允许 internal_filesystem/apps/<fullname>/ 和 tmp/mpos-* 下的变化。若发现 OS/build/framework/已有 App 文件变化，必须标记 failed/blocked，不能擅自回滚用户改动，也不能继续让发布链路视为成功。

输出 JSON

执行阶段结束时输出并可保存 generation_result.json。结构参考 templates/generation_result.json，并用脚本校验：

python3 /home/leeqingshui/MicroPython_Skills/mpos-gen-app/scripts/validate_generation_result.py \
  /path/to/generation_result.json

成功的 create/update/repair 必须记录：

• confirmed_by_user: true
• 创建/修改文件
• 版本变化
• icon 生成结果
• 依赖和同步 adapter 结果
• 所有校验门禁及 returncode
• api_usage 与 app_only_changes gate 必须存在且通过
• handoff.next_skill: "mpos-test-app"

plan 阶段 confirmed_by_user 必须是 false，并且 handoff.next_skill 仍指向 mpos-gen-app。

下游

代码生成成功后交给 mpos-test-app。如果用户只要求生成代码，可以把 handoff.next_skill 设为 null，但仍必须报告校验结果。