主用例说明：插件创建与初始化

背景概述

PowerX 插件生态需要覆盖从零到一的工程搭建能力，使开发者和企业技术团队能够快速进入研发节奏。随着插件数量增长、协作开发和外部源码引入成为常态，平台必须提供标准化的初始化工具链、模板体系与合规校验流程。本主用例聚焦“插件创建与初始化”，梳理从 CLI 初始化、团队协作克隆到第三方源码导入的关键环节，确保所有插件在进入开发之前就具备一致的结构、安全与合规保障。

目标与价值

• 快速起步：提供模板化、自动化的初始化流程，缩短插件立项准备时间。
• 工程规范一致：统一目录结构、依赖配置与脚手架，降低团队协作成本。
• 合规可控：在导入外部源码时执行许可证、依赖与安全校验，规避风险。
• 可持续维护：确保初始化后的项目自动纳入版本管理、CI/CD 与质量扫描体系。

参与角色

• 插件开发者：通过 CLI 或模板快速生成初始工程并开展开发。
• 团队技术负责人：负责维护团队模板、审核克隆流程与代码规范。
• 企业技术组/集成商：导入第三方源码包并完成合规复核。
• 平台脚手架服务：提供模板拉取、依赖安装、配置初始化能力。
• 安全合规服务：执行许可证扫描、依赖漏洞检测与来源审计。
• 版本控制系统（Git/SVN）：存储初始化项目并关联协作流程。

主场景 User Story

作为 插件技术负责人，我希望 团队在创建新插件或引入外部插件源码时能通过标准化流程快速初始化工程，从而 保证项目结构一致、依赖安全并可立即进入协作开发。

子场景详解

子场景 A：开发者使用 CLI 初始化新插件工程

• 角色与触发：插件开发者接到新功能需求，需要创建全新的插件工程并启用官方模板。
• 主要流程：
  1. 开发者在终端执行 powerx plugin init，选择目标模板（如 react-dashboard、python-agent）。
  2. CLI 下载模板、初始化目录结构，生成配置文件（manifest、权限声明、脚本配置）。
  3. 自动安装基础依赖、配置 lint/test 脚本，并生成示例代码与文档。
  4. CLI 完成后引导开发者关联 Git 仓库、创建初始分支并推送远程。
• 成功标准：工程在 1 分钟内创建完成；依赖安装无报错；生成的 manifest、配置文件符合平台规范；Git 仓库成功初始化。
• 异常与风控：网络异常、模板缺失或 CLI 版本过旧时给出错误提示并指导升级；若依赖源不可信则中止并提示风险来源。
• 指标建议：初始化耗时、依赖安装成功率、模板使用频次、CLI 版本合规率。

子场景 B：团队成员克隆现有插件项目开展二次开发

• 角色与触发：同一团队成员需要在现有插件基础上新增功能或修复缺陷。
• 主要流程：
  1. 团队负责人在 PowerX 控制台或文档中分享仓库地址与分支策略。
  2. 开发者克隆仓库并运行 powerx plugin doctor 校验本地环境与依赖完整性。
  3. CLI 自动同步共享配置（如环境变量模板、测试数据集），提示必须遵循的编码规范。
  4. 成功后开发者创建特性分支并开始开发，CI 自动检测初始化脚本是否执行。
• 成功标准：克隆后运行健康检查全部通过；本地环境与远程依赖一致；团队成员在 10 分钟内完成环境搭建。
• 异常与风控：如检测到缺失依赖、Node/Python 版本不兼容，流程自动给出修复建议；仓库权限不足时触发审批流程。
• 指标建议：环境校验通过率、平均环境搭建时间、权限审批响应时间。

子场景 C：企业技术组导入第三方插件源码包进行适配

• 角色与触发：企业采购外部供应商的插件源码包，需要导入到内部环境进行适配和安全复核。
• 主要流程：
  1. 技术组在控制台上传源码包或连接供应商仓库，触发导入流程。
  2. 平台解包后自动执行许可证与依赖扫描，生成风险评估报告。
  3. 通过合规审核后，脚手架服务根据 PowerX 规范重构目录、补齐缺失的 manifest、配置与脚本。
  4. 系统提示技术负责人确认适配项（API 版本、权限声明、兼容性），并自动推送至企业 Git 仓库。
• 成功标准：导入流程在 15 分钟内完成；合规扫描无高危问题或已提供豁免；生成的项目可直接执行 npm test / pytest 等基础用例。
• 异常与风控：发现高危许可证冲突或恶意依赖时终止导入并通知安全团队；缺失关键文件时需补齐模板后才能进入下一步；全程生成审计日志。
• 指标建议：导入成功率、扫描风险级别分布、适配耗时、审计闭环率。

功能边界 & 非目标场景

• 不涵盖插件功能开发、调试与发布流程，相关内容分别由“插件开发与调试”“插件发布与上架”主用例覆盖。
• 不处理插件运行时配置、安装启停等运维动作，参见“插件安装与启停”主用例。
• 不涉及 Marketplace 审核与计费流程，相关能力由“插件上架与销售”主用例描述。

依赖与接口

• PowerX CLI / 脚手架服务：提供模板拉取、依赖安装、工程生成、环境诊断等能力。
• 模板仓库与包管理服务：存储官方模板、脚手架依赖以及第三方包镜像。
• 安全合规服务：负责许可证扫描、依赖漏洞检测、源码来源审计。
• 版本控制与协作平台：Git/SVN/内部代码托管，提供仓库管理、权限控制、CI 触发。
• 通知与审批服务：在模板更新、权限申请、风险发现时推送提醒或触发审批链路。

验收要点

1. CLI 初始化流程需覆盖模板选择、依赖安装、Git 初始化与配置向导，失败时提供可执行的修复指引。
2. 克隆与环境校验需支持一键检测依赖、环境版本、配置项，并在 5 分钟内产出可读报告。
3. 第三方源码导入必须执行许可证与安全扫描，风险可配置阻断策略，并生成审计记录与适配清单。
4. 初始化后的工程应自动接入团队的 CI/CD、代码规范与文档模板，确保后续开发可持续。

场景级测试用例示例

测试准备：在沙箱环境中部署最新版本 powerx-cli，预置官方模板 react-dashboard 与 python-agent；准备示例仓库 git@corp/powerx/sample-plugin.git；提供第三方源码包 vendor-ai-agent.zip 及含高危许可证的包 risk-license.zip；配置安全扫描服务与审计日志。

用例 A-1：CLI 初始化成功（正向）

• 前置条件：开发者使用 Node 18 环境，已登录 PowerX CLI。
• 操作步骤：
  1. 执行 powerx plugin init react-dashboard demo-analytics。
  2. 等待依赖安装完成并根据提示初始化 Git。
• 预期结果：
  • CLI 完成后显示“项目初始化成功”，生成 manifest、README、测试样例。
  • npm run lint 与 npm test 初次运行通过。
  • Git 仓库创建初始提交并推送成功。

用例 A-2：模板缺失触发升级提示（逆向）

• 前置条件：本地 CLI 版本过旧，不包含最新模板。
• 操作步骤：
  1. 执行 powerx plugin init python-agent bot-helper。
• 预期结果：
  • CLI 检测到模板缺失，提示升级命令 npm i -g powerx-cli@latest。
  • 初始化终止且未生成不完整工程；审计日志记录失败原因。

用例 B-1：克隆后环境校验通过（正向）

• 前置条件：开发者具备仓库访问权限，安装所需语言运行时。
• 操作步骤：
  1. 克隆 sample-plugin 仓库并运行 powerx plugin doctor。
  2. 根据提示执行 npm install、导入 .env.example。
• 预期结果：
  • 校验报告显示“所有检查通过”，包括依赖、环境变量、脚本可用性。
  • CI 在首次推送时自动通过初始化检查。

用例 B-2：依赖缺失提示修复（逆向）

• 前置条件：开发者未安装指定的 Python 版本。
• 操作步骤：
  1. 运行 powerx plugin doctor。
• 预期结果：
  • CLI 检测到 Python 版本不匹配，给出安装指引或切换虚拟环境建议。
  • 诊断结果标记为“失败”，阻止继续提交代码。

用例 C-1：第三方源码导入成功（正向）

• 前置条件：vendor-ai-agent.zip 不含高危许可证；安全扫描服务在线。
• 操作步骤：
  1. 在控制台上传源码包并选择目标租户、仓库。
  2. 完成合规审核后生成 PowerX 标准工程。
• 预期结果：
  • 扫描报告显示仅低风险项且已确认；工程目录包含标准 manifest、权限配置。
  • 适配清单列出需手动调整的 API 版本；项目成功推送到企业 Git。

用例 C-2：高危许可证阻断导入（逆向）

• 前置条件：risk-license.zip 包含 GPLv3 组件且企业策略禁止。
• 操作步骤：
  1. 上传源码包并触发导入流程。
• 预期结果：
  • 安全合规服务标记高危许可证，导入流程终止。
  • 系统通知安全团队与技术负责人，并提供替代处理建议。
  • 审计日志记录阻断原因、扫描详情与处理状态。