Run any Skill in Manus with one click

upy-analyze-plugin

Stars5

Forks0

UpdatedJuly 3, 2026 at 16:24

插件化 V0 analyze 阶段。读取一句话硬件项目需求和插件上下文，完成需求解析、器件确认、驱动搜索、替代推荐或冷门驱动标记，并输出完整 envelope 的 phase_complete + manifest_content。触发：插件 start_phase(analyze)、用户描述“做一个/我想做/帮我写一个”MicroPython 硬件项目、需要生成 project manifest。

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

FreakStudioCN

FreakStudioCN/MicroPython_Skills

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

28 files

SKILL.md

readonly

upy-analyze

职责

把用户的一句话硬件需求转换为可交给 upy-select-hw 的 analyze manifest。

只做：

解析需求和实现族。
生成并确认器件清单。
搜索内置运行时能力和具体器件驱动。
标记替代推荐或冷门驱动路径。
输出 phase_complete，其中 payload.manifest_content 是下游唯一主交接物。

不做：

不选 MCU 和板卡。
不分配引脚。
不生成业务代码。
不烧录设备。
不把插件端 UI 或设备日志解析逻辑写进插件。

运行模式

协议字段说明

先按本文件执行流程。需要构造或排查具体消息字段时，读取 references/v0-protocol.md；它定义 envelope、start_phase、approval_request、status_update、script_run、manifest、phase_complete、checkpoint、structured errors 和 artifacts 的字段含义与枚举。

输出 JSON 时优先使用 templates/*.json 和 mock-messages/analyze/*.json 的形状，不要自由发挥字段名。

正式插件模式

插件通过 start_phase 启动：

{
  "protocol_version": "1.0",
  "msg_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "4f6d9d72-9c4a-4f11-90df-3f2ad6e726cc",
  "phase": "analyze",
  "timestamp": "2026-06-21T00:00:00Z",
  "type": "start_phase",
  "payload": {
    "user_description": "做一个温湿度监测仪，超过阈值蜂鸣器报警",
    "pre_selected_board": null,
    "preferences": { "mode": "beginner", "locale": "zh" },
    "existing_hardware": []
  }
}

正式模式中：

session_id 必须由插件创建并传入。
skill/服务器必须继承同一个 session_id，不得另建正式 session。
所有 S->P 消息必须带完整 envelope。
本地文件、脚本、设备动作只能通过协议工具表达。

start_phase 字段速查：

字段	必填	来源	含义
`protocol_version`	是	插件	固定 `"1.0"`
`msg_id`	是	插件	当前消息 UUID
`session_id`	是	插件	当前工作流 session UUID，全流程保持不变
`phase`	是	插件	固定 `"analyze"`
`timestamp`	是	插件	ISO 8601 时间戳
`type`	是	插件	固定 `"start_phase"`
`payload.user_description`	是	用户输入	一句话硬件需求
`payload.pre_selected_board`	否	插件 UI	预选板卡；analyze 只记录，不核验
`payload.preferences.mode`	否	插件设置	`beginner` 或 `custom`，默认 `beginner`
`payload.preferences.locale`	否	插件设置	默认 `zh`
`payload.existing_hardware`	否	用户资料	已有硬件数组，默认 `[]`

Claude Code 直测模式

没有真实插件宿主时，可以写调试产物，但这些文件不替代 phase_complete.payload.manifest_content。

如果输入缺少 session_id，直测模式必须生成 UUID，并强制使用 session 隔离目录：

{test_root}/sessions/{session_id}/
  manifest_draft.json
  manifest_validated.json
  phase_complete.analyze.json
  driver_search_log.md
  analyze_phase_log.md

直测模式必须在结束前调用校验脚本：

python {skill_dir}/scripts/init_manifest.py --input {session_dir}/manifest_draft.json --write-path {session_dir}/manifest_validated.json
python {skill_dir}/scripts/init_manifest.py --validate-phase-complete --input {session_dir}/phase_complete.analyze.json --compare-manifest {session_dir}/manifest_validated.json

任一校验失败，不得宣称 analyze 成功。

V0 协议硬规则

完整 envelope

所有正式协议消息必须包含：

{
  "protocol_version": "1.0",
  "msg_id": "uuid",
  "session_id": "uuid",
  "phase": "analyze",
  "timestamp": "2026-06-21T00:00:00Z",
  "type": "phase_complete",
  "payload": {}
}

要求：

protocol_version 固定为 "1.0"。
msg_id 使用 UUID 字符串。
session_id 使用 UUID 字符串。
顶层 phase 和 payload.phase 都保留，且必须一致。

envelope 字段速查：

字段	必填	谁生成	规则
`protocol_version`	是	发送方	固定 `"1.0"`
`msg_id`	是	发送方	每条消息一个新 UUID
`session_id`	是	插件	同一工作流不变
`phase`	是	发送方	analyze 阶段固定 `"analyze"`
`timestamp`	是	发送方	ISO 8601，UTC 优先
`type`	是	发送方	消息类型
`payload`	是	发送方	类型专属对象

result 枚举

phase_complete.payload.result 只允许：

result	含义	next_phase	checkpoint
`success`	analyze 完整成功，可进入下游	`select-hw`	不需要
`partial`	用户取消、中断、超时、缺输入或只完成部分搜索	`null`	必须有
`failed`	无法产生可用 manifest，或协议/格式校验失败	`null`	可选

partial 必须包含：

{
  "checkpoint_id": "uuid",
  "resume_phase": "analyze",
  "resume_step": "driver_search",
  "resume_label": "继续 analyze 驱动搜索",
  "reason": "user_cancelled"
}

V0 只定义 checkpoint/resume 结构，不实现完整 resume runtime。

errors 与 structured_errors

保留 errors: string[] 给人类阅读，同时输出 structured_errors: object[] 给插件 UI 和 orchestration：

{
  "code": "manifest_validation_failed",
  "message": "devices[0].driver.source invalid",
  "severity": "error",
  "recoverable": true,
  "retryable": true,
  "source": "init_manifest.py"
}

severity 只允许 info / warning / error / fatal。

artifact 统一模型

artifacts 必须是数组。调试文件路径使用 file_list artifact，不得写成对象映射。

artifact.files[].status 只允许：

created / updated / unchanged / skipped / error

权限策略

采用“首次 session 弹一次总权限，后续沿用”的长流程策略。

analyze 阶段授权后允许：

写项目分析产物。
运行白名单脚本 scripts/init_manifest.py。
访问驱动搜索源，如 upypi、awesome-micropython、GitHub。

仍需单独确认的高风险动作：

删除文件。
烧录设备。
执行任意 shell。
上传或发布到 upypi。

取消、重试、超时

V0 先写进协议和 skill 说明，不实现完整 runtime：

用户取消 approval：输出 result="partial"，next_phase=null，写 checkpoint。
驱动搜索超时：优先降级为 warning；核心信息不可判断时才 failed。
manifest 校验失败：允许修正后重试；重试沿用同一个 session_id。
重试行为记录在日志或 payload 元数据中。

执行步骤

Step 1: 读取输入上下文

读取 start_phase.payload：

字段	必填	默认	说明
`user_description`	是	无	用户一句话需求
`pre_selected_board`	否	`null`	插件预选板卡，analyze 只记录，不核验
`preferences.mode`	否	`beginner`	`beginner` 或 `custom`
`preferences.locale`	否	`zh`	默认中文
`existing_hardware`	否	`[]`	用户已有硬件

如果字段缺失，按默认值补齐；如果 user_description 缺失或为空，输出 phase_complete(result="failed")，不得继续猜测需求。

发送：

{
  "type": "status_update",
  "payload": {
    "level": "info",
    "message": "正在分析需求，先拆实现族和器件清单。",
    "step_id": "intent_extraction",
    "step_status": "running"
  }
}

Step 2: 意图拆解和器件确认

从自然语言中提取：

项目名。
功能链路。
实现族。
器件清单。
接口类型。
用户指定器件 vs 系统推荐器件。

大类器件必须先拆实现族。例如土壤类必须区分 ADC / RS485 Modbus / I2C/SPI / 组合方案。

只保留一个必经确认点：approval_request(device_confirm)。

{
  "type": "approval_request",
  "payload": {
    "approval_id": "device_confirm",
    "header": "确认项目方案",
    "question": "请确认器件方案；像土壤类器件，可在这里改成 ADC / RS485 Modbus / I2C 方案。",
    "summary": {
      "project_name": "温湿度监测报警器",
      "description": "定时采集温湿度，超过阈值蜂鸣器报警",
      "board": { "status": "none" }
    },
    "items": [],
    "allow_add": true,
    "allow_remove": true,
    "multi_select": true,
    "actions": [
      { "label": "确认，开始搜索驱动", "value": "confirm", "primary": true },
      { "label": "修改器件清单", "value": "modify" }
    ]
  }
}

approval_request 发出后必须等待用户响应，不得继续假装已确认。

Step 3: 补充需求

beginner 默认补齐 requirements。custom 或信息明显不足时，最多发一张 approval_request(requirement_supplement)。

默认值：

字段	默认
`scene`	`indoor`
`power`	`usb`
`network`	`none`
`sample_rate`	`normal_1hz`
`precision`	`normal`
`response_time`	`1s`
`temp_range`	`normal_0_40`
`size_constraint`	`none`
`budget_yuan`	`medium_50`
`experience`	`beginner`
`output`	`["serial"]`
`existing_hardware`	`[]`
`special_requirements`	`["none"]`
`mcu_specified`	`null`

语音、云端、音频输出等 schema 不能完整表达的内容，记录在 description、special_requirements、device notes 和 warnings 中，不因 output 枚举不足直接失败。

Step 4: 驱动搜索

对每个确认后的器件，分两层判断：

底层运行时能力：
- machine.ADC
- machine.Pin
- machine.I2C
- machine.SPI
- machine.UART
- machine.I2S
- network
- bluetooth
具体器件驱动：
- upypi
- awesome-micropython
- github
- 其他可信 MicroPython 来源

注意：

builtin_runtime 只表示底层 API 可用，不等于具体 I2C/SPI/UART 器件驱动已找到。
I2C/SPI/UART 具体器件仍应优先查 upypi。
micropython_lib 只用于官方生态通用库/中间件，不作为普通传感器驱动默认来源。
driver.source="none" 只在不是明显内置运行时能力，且所有驱动源都无结果时使用。

每个器件搜索过程发送 status_update。

系统推荐器件无驱动时，可推荐最多 2 个同类替代器件，使用 approval_request(alternative_device)。用户指定器件无驱动，或用户拒绝替代时，标记 driver.source="cold-driver"，由后续 upy-gen-driver 处理。

Step 5: 构建 manifest_draft

生成 manifest 草稿，必须包含：

project_name
requirements
devices

每个 device 必须包含：

name
type
interface
source: user_specified 或 system_recommended
quantity
driver.source

有效 driver.source：

builtin_runtime / micropython_lib / upypi / awesome-micropython / github / local / cold-driver / none

Step 6: 强制校验 manifest

必须调用：

python {skill_dir}/scripts/init_manifest.py --input manifest_draft.json --write-path manifest_validated.json

校验失败：

修正草稿后可重试。
仍失败则输出 phase_complete(result="failed")。
不得继续输出 success。

Step 7: 输出 phase_complete

成功时输出完整 envelope：

{
  "protocol_version": "1.0",
  "msg_id": "550e8400-e29b-41d4-a716-446655440001",
  "session_id": "4f6d9d72-9c4a-4f11-90df-3f2ad6e726cc",
  "phase": "analyze",
  "timestamp": "2026-06-21T00:00:00Z",
  "type": "phase_complete",
  "payload": {
    "phase": "analyze",
    "result": "success",
    "summary": "器件分析完成，manifest 已通过校验。",
    "next_phase": "select-hw",
    "manifest_content": {},
    "artifacts": [
      {
        "type": "file_list",
        "title": "Claude Code 直测产物",
        "files": [
          {
            "path": "manifest_draft.json",
            "status": "created",
            "kind": "manifest_draft",
            "mime_type": "application/json",
            "description": "校验前 manifest 草稿"
          },
          {
            "path": "manifest_validated.json",
            "status": "created",
            "kind": "manifest",
            "mime_type": "application/json",
            "description": "校验规范化后的 analyze manifest"
          },
          {
            "path": "phase_complete.analyze.json",
            "status": "created",
            "kind": "phase_complete",
            "mime_type": "application/json",
            "description": "完整 analyze 阶段完成消息"
          },
          {
            "path": "driver_search_log.md",
            "status": "created",
            "kind": "log",
            "mime_type": "text/markdown",
            "description": "驱动搜索记录"
          }
        ]
      }
    ],
    "warnings": [],
    "errors": [],
    "structured_errors": []
  }
}

phase_complete.payload 字段速查：

字段	必填	success	partial	failed
`phase`	是	`"analyze"`	`"analyze"`	`"analyze"`
`result`	是	`"success"`	`"partial"`	`"failed"`
`summary`	是	成功摘要	中断摘要	失败摘要
`next_phase`	是	`"select-hw"`	`null`	`null`
`manifest_content`	是	校验后的 manifest	当前最佳 manifest 快照	尽量给出当前快照
`checkpoint`	条件	不需要	必须	可选
`artifacts`	是	数组	数组	数组
`warnings`	是	字符串数组	字符串数组	字符串数组
`errors`	是	空数组或错误摘要	空数组或错误摘要	错误摘要
`structured_errors`	是	空数组	可选结构化错误	必须描述主要失败

直测模式建议额外写 analyze_phase_log.md，但它不是正式协议必交产物；可以在 file_list 中声明。

写出 phase_complete.analyze.json 后必须调用：

python {skill_dir}/scripts/init_manifest.py --validate-phase-complete --input phase_complete.analyze.json --compare-manifest manifest_validated.json

校验失败不得宣称完成。

交付文件

正式插件模式以消息为准。Claude Code 直测模式在 session 目录下写：

manifest_draft.json
manifest_validated.json
phase_complete.analyze.json
driver_search_log.md
analyze_phase_log.md（建议）

模板和 mock

使用本 skill 自带资源：

templates/envelope.phase_complete.json
templates/checkpoint.json
templates/structured_error.json
templates/artifact.file_list.json
mock-messages/analyze/*.json
references/v0-protocol.md

修改模板、枚举或输出格式后，必须更新校验脚本和 smoke 测试。

强约束

协议格式、必填字段、枚举非法、manifest 核心结构错误必须作为 error。
业务语义问题优先 warning，例如 TouchPad 板卡兼容性、语音 output schema 不完整。
phase_complete.payload.manifest_content 是下游唯一主交接物。
manifest_validated.json 与 phase_complete.payload.manifest_content 必须核心字段一致，时间字段不参与严格比较。
phase_complete.artifacts 必须是数组。
errors 必须是字符串数组，structured_errors 必须是对象数组。
partial 必须 next_phase=null 且有 checkpoint。
success 必须 next_phase="select-hw" 且有合法 manifest_content。

name	upy-analyze-plugin
description	插件化 V0 analyze 阶段。读取一句话硬件项目需求和插件上下文，完成需求解析、器件确认、驱动搜索、替代推荐或冷门驱动标记，并输出完整 envelope 的 phase_complete + manifest_content。触发：插件 start_phase(analyze)、用户描述“做一个/我想做/帮我写一个”MicroPython 硬件项目、需要生成 project manifest。

upy-analyze-plugin

More from this repository

More from this repository

upy-analyze

职责

运行模式

协议字段说明

正式插件模式

Claude Code 直测模式

V0 协议硬规则

完整 envelope

result 枚举

errors 与 structured_errors

artifact 统一模型

权限策略

取消、重试、超时

执行步骤

Step 1: 读取输入上下文

Step 2: 意图拆解和器件确认

Step 3: 补充需求

Step 4: 驱动搜索

Step 5: 构建 manifest_draft

Step 6: 强制校验 manifest

Step 7: 输出 phase_complete

交付文件

模板和 mock

强约束

upy-analyze

职责

运行模式

协议字段说明

正式插件模式

Claude Code 直测模式

V0 协议硬规则

完整 envelope

result 枚举

errors 与 structured_errors

artifact 统一模型

权限策略

取消、重试、超时

执行步骤

Step 1: 读取输入上下文

Step 2: 意图拆解和器件确认

Step 3: 补充需求

Step 4: 驱动搜索

Step 5: 构建 manifest_draft

Step 6: 强制校验 manifest

Step 7: 输出 phase_complete

交付文件

模板和 mock

强约束