@teamix-evo/skills 0.12.0 → 0.13.0

package/src/teamix-evo-manage/init.md

@@ -0,0 +1,98 @@
+# Init (初始化 Teamix Evo 套件)
+
+> **前置条件**：空目录（或仅含 `.git`、`.gitignore`、`.vscode` 等可忽略文件）。
+> 含 `package.json` 或其他项目文件的目录视为非空，会被 `assertCommandPrecondition` 拒绝并建议正确命令（`npm init -y` 过的目录需加 `--force`）。
+
+单一命令完成从空目录到可运行工程的全流程：**脚手架生成 → 套件 init pipeline**。
+
+## 触发
+
+用户说"初始化一个项目 / 工程 / 新建项目"等意图。
+
+## 步骤
+
+### 1. 确定 variant
+
+若用户未指明 variant，列出可选项让用户选（`AskUserQuestion`）：
+
+- **OpenTrek**（`opentrek`）：AI 副驾驶 / 通用中后台
+- **Uni-Manager**（`uni-manager`）：云资源管理（大屏 / 拓扑 / 7 类 AI 场景）
+
+### 2. 确定目录
+
+- 用户指定了项目名 → `./<project-name>`
+- 用户说"当前目录" → `.`（需确认当前为空目录）
+- 未明确 → 询问用户
+
+### 3. 执行初始化
+
+```bash
+npx teamix-evo@latest init --variant <name> -y
+```
+
+**一条命令完成所有工作**，流程分两个阶段：
+
+#### 阶段 A：脚手架生成（空目录时自动触发）
+
+| 步骤 | 产物                                             |
+| ---- | ------------------------------------------------ |
+| 1    | Vite + React + TS scaffold（base template 复制） |
+| 2    | variant overlay（变体专属配置覆盖）              |
+| 3    | package.json merge（合并依赖）                   |
+| 4    | 依赖安装（`pnpm install` / `npm install`）       |
+| 5    | git init                                         |
+
+#### 阶段 B：套件 init pipeline（8 步流水线）
+
+| #   | 步骤       | 关键 | 行为                                                                                   |
+| --- | ---------- | ---- | -------------------------------------------------------------------------------------- |
+| 1   | tokens     | ✓    | 写 `tokens/`，顺带装 design skill；旧路径单文件命中 `migrate` 策略时自动提层迁移       |
+| 2   | skills     | ✓    | 项目级装 `teamix-evo-code-<variant>`（manage 全局装一次，design 由 step 1 顺带） |
+| 3   | agents-md  | –    | 生成根 `AGENTS.md`，managed-region 可重生                                  |
+| 4   | ui-init    | ✓    | 写 `components.json` + `packages.ui` 配置                                              |
+| 5   | ui-add     | –    | 装全量 UI 组件源码（overwrite 模式）                                                   |
+| 6   | biz-ui-add | –    | 装当前 variant 下全量业务组件（无可用则 skip）                                         |
+| 7   | lint       | –    | `runLintInit`（ESLint + Stylelint）                                                    |
+| 8   | gitignore  | –    | 追加 teamix-evo runtime 规则到 `.gitignore`                                            |
+
+> 关键步骤失败 → 后续关键步骤短路成 `skip(aborted)`；非关键步骤失败不阻断整体。
+
+#### CLI 选项
+
+| 选项               | 说明                          |
+| ------------------ | ----------------------------- |
+| `--variant <name>` | tokens variant                |
+| `-y, --yes`        | 跳过交互，使用推荐默认值     |
+| `--pm <name>`      | 包管理器：pnpm / npm / yarn   |
+| `--no-git`         | 跳过 git init                 |
+| `--no-install`     | 跳过依赖安装                  |
+| `--dry-run`        | 只输出执行计划，不写任何文件  |
+| `--force`          | 跳过前置检查，强制执行        |
+
+### 4. 提交 init 产出（必做）
+
+init 会生成大量文件（tokens / skills / ui 组件 / lint 配置等），**必须立刻 commit**：
+
+```bash
+git add .
+git commit -m "chore: init teamix-evo (<variant>)"
+```
+
+### 5. 验证
+
+```bash
+pnpm dev          # 立刻可跑
+pnpm typecheck    # 验证零类型错误
+```
+
+### 6. 全局 entry skill
+
+若 `~/.qoder/skills/teamix-evo-manage` 不存在，提示用户装全局 manage skill：
+
+```bash
+npx teamix-evo@latest skills add teamix-evo-manage --scope global -y
+```
+
+## Partial（部分完成）状态恢复
+
+CLI 在 partial 状态会打印"恢复指引"面板：失败步骤名、错误信息、已完成步骤、建议命令。**修好原因后直接重跑 `teamix-evo init`** —— 每个 sub-step 幂等，已落地的会 `already-initialized` 短路，从断点处续接。

package/src/teamix-evo-manage/migrate.md

@@ -0,0 +1,100 @@
+# Migrate (shadcn 项目迁移为 Teamix Evo 套件)
+
+> **前置条件**：当前目录是 shadcn 项目（有 `package.json` + `components.json`，无 `.teamix-evo/`）。
+> 非 shadcn 工程执行时被 `assertCommandPrecondition` 拒绝并建议正确命令。
+
+## 触发
+
+用户表达"迁移 shadcn 到 teamix-evo / migrate / 把 shadcn 转成 teamix-evo / 升级 shadcn 项目"等关键词。
+
+## 前置检查
+
+```bash
+npx teamix-evo@latest migrate              # 前置检查 + 引导
+npx teamix-evo@latest migrate --json       # JSON 格式报告（供 AI 消费）
+```
+
+CLI 仅做前置检查（项目状态识别 + shadcn 工程确认），**实际迁移由 AI skill 驱动**。
+
+## 迁移流程（AI 引导）
+
+### 1. 分析 shadcn 项目结构
+
+读取并分析：
+
+- `components.json`：registry URL、aliases、style 配置
+- `package.json`：已安装的 shadcn 相关依赖
+- `src/components/ui/`：已安装的 shadcn 组件列表
+- Tailwind 配置：v3（`tailwind.config.*`）还是 v4（`@import "tailwindcss"`）
+- 现有配置文件：ESLint、Stylelint 等
+
+### 2. 确定目标 variant
+
+让用户选择 tokens variant（同 init 流程）：
+
+- **OpenTrek**（`opentrek`）：AI 副驾驶 / 通用中后台
+- **Uni-Manager**（`uni-manager`）：云资源管理
+
+### 3. 生成迁移计划
+
+基于分析结果生成迁移计划，包括：
+
+| 阶段         | 内容                                                       |
+| ------------ | ---------------------------------------------------------- |
+| tokens 注入  | 写入 `tokens/` 目录，配置 design tokens                   |
+| config 转换  | `components.json` → `.teamix-evo/config.json`             |
+| 组件映射     | shadcn 组件 → teamix-evo 对应组件的映射关系               |
+| skills 安装  | 项目级 skill 安装                                          |
+| AGENTS.md    | 生成根 `AGENTS.md`                                         |
+| lint 配置    | ESLint + Stylelint 配置                                    |
+
+### 4. 逐步执行迁移
+
+按计划逐步执行，每步征求用户确认：
+
+1. **tokens 注入**：`npx teamix-evo@latest tokens init --variant <name>`
+2. **skills 安装**：`npx teamix-evo@latest skills init`
+3. **AGENTS.md 生成**：init pipeline 中的 agents-md 步骤
+4. **UI 配置迁移**：`npx teamix-evo@latest ui init`（转换 aliases、配置）
+5. **组件对齐**：`npx teamix-evo@latest ui add` 安装 teamix-evo 版组件，与现有 shadcn 组件建立映射
+6. **lint 配置**：`npx teamix-evo@latest lint init`
+
+### 5. 验证
+
+```bash
+pnpm typecheck    # 类型检查
+pnpm dev          # 启动验证
+```
+
+### 6. 提交
+
+```bash
+git add .
+git commit -m "chore: migrate from shadcn to teamix-evo (<variant>)"
+```
+
+## 各资源的迁移处理方式
+
+| 资源 | 迁移行为 | 说明 |
+| --- | --- | --- |
+| tokens | `tokens init --variant <name>` 全新生成 | 覆盖或新建 `tokens/` 目录 |
+| skills | `skills init` 全新安装 | 按 variant + scope 自举 |
+| AGENTS.md | init pipeline 全新生成 | managed 区段 + 用户自由编辑区 |
+| config.json | 从 `components.json` 转换生成 | shadcn aliases → teamix-evo config |
+| manifest.json | 全新生成 | 记录已安装资源 ledger |
+| lint | `lint init` 生成配置 | 检测现有 ESLint/Stylelint 配置，按冲突策略处理（merge/backup-overwrite/skip/overwrite） |
+| ui 组件 | `ui init` + `ui add` | 建立 shadcn→teamix-evo 组件映射 |
+
+**lint 冲突处理**：shadcn 项目通常已有 ESLint 配置。`lint init` 会检测现有配置文件并提供冲突策略选项：
+
+- `merge`：备份现有文件，写入 teamix-evo 模板，AI 引导用户合并自定义规则
+- `backup-overwrite`：备份后直接覆写
+- `skip`：保留用户现有配置不动
+- `overwrite`：直接覆写（不备份）
+
+## 注意事项
+
+- **不破坏现有功能**：迁移过程中现有 shadcn 组件保持可用，逐步替换。
+- **components.json 保留**：迁移完成后 `components.json` 不删除（可能有其他工具依赖），但 teamix-evo 以 `.teamix-evo/config.json` 为准。
+- **自定义组件**：用户对 shadcn 组件的自定义修改需要在 AI 引导下手动迁移到 teamix-evo 体系。
+- **迁移完成后**：项目状态变为 `teamix-evo`，后续使用 `teamix-evo update` 保持更新。

package/src/teamix-evo-manage/rearchitect-capture-guide.md

@@ -0,0 +1,174 @@
+# 迁移三轨材料准备指南
+
+迁移流程依赖三轨材料：**源码** + **repo-wiki** + **页面截图**。本文件说明 repo-wiki 和截图的工具与操作方式。
+
+## 1. Repo-wiki 准备（Qoder 客户端内置功能）
+
+Repo-wiki 是 **Qoder 客户端**的内置功能，无需额外安装。
+
+**操作步骤：**
+
+1. 在 **Qoder 客户端**中打开旧项目目录
+2. 使用 Qoder 内置的 repowiki 功能生成项目文档
+3. 产物位于 `<old-path>/.qoder/repowiki/`（含中/英文版）
+
+**AI 引导话术：**
+
+> "请在 Qoder 客户端中打开旧项目目录，使用内置 repowiki 功能生成项目文档。完成后告诉我，我会自动读取 `<old-path>/.qoder/repowiki/` 下的内容。"
+
+## 2. 页面截图准备（Qoderwork 客户端）
+
+页面截图通过 **Qoderwork 客户端**完成。Qoderwork 内置浏览器截图能力，支持逐页面批量截图。
+
+**操作步骤：**
+
+1. 在 **Qoderwork 客户端**中打开旧项目的运行 URL
+2. 逐页面访问，对每个页面的以下状态进行截图：
+   - 页面默认态（列表 / 表单 / 详情等主视图）
+   - 页面内所有弹窗（Dialog / Modal）的打开态
+   - 页面内所有抽屉（Drawer / Sheet）的打开态
+   - 关键交互状态（空态 / 加载态 / 错误态，若能触发）
+3. 按页面路由建文件夹，存放到统一截图目录
+
+**AI 引导话术：**
+
+> "请在 Qoderwork 客户端中打开待迁移项目 URL，对所有页面及页面内的弹窗、抽屉进行截图，按页面路由为文件夹名落地，完成后提供截图目录路径。"
+
+### 截图目录结构约定
+
+```
+<screenshots-dir>/
+├── home/
+│   ├── default.png
+│   └── dialog-create.png
+├── list/
+│   ├── default.png
+│   ├── drawer-detail.png
+│   └── dialog-delete.png
+├── settings/
+│   └── default.png
+└── _aside/                     # 左导航专项（可选）
+    ├── sidebar-top.png
+    ├── sidebar-bottom.png
+    └── sidebar-collapsed.png
+```
+
+### 文件命名约定
+
+| 文件名 | 含义 |
+| --- | --- |
+| `default.png` | 页面默认态（整页截图） |
+| `dialog-<名称>.png` | 弹窗（Dialog / Modal）打开态 |
+| `drawer-<名称>.png` | 抽屉（Drawer / Sheet）打开态 |
+| `state-empty.png` | 空态 |
+| `state-loading.png` | 加载态 |
+| `state-error.png` | 错误态 |
+| `tab-<n>-<名称>.png` | Tab / Radio 切换态 |
+| `row-action-menu.png` | 表格行内操作菜单展开态 |
+
+## 3. 进阶：Playwright 自动化批量截图
+
+适用于内网控制台（Fusion / Next-design 风格）的大规模页面截图场景。当页面数量多（>20 页）且手动截图效率低时，AI 应根据下方流程和 DOM 知识**自行生成** Playwright 脚本，针对目标站点定制。
+
+### 环境准备
+
+```bash
+pip3 install playwright && python3 -m playwright install chromium
+```
+
+脚本需从用户处获取三项配置：
+
+| 配置项 | 说明 |
+| --- | --- |
+| 代理地址 | 内网控制台通常需要 HTTP 代理才能访问 |
+| 目标站点 URL | 待截图的控制台首页地址 |
+| 登录凭证 | 用户名/密码（用于 Playwright 自动登录） |
+
+截图输出到 `<project>/.teamix-evo/migrate-screenshots/`，按路由建子目录。
+
+### 截图流程（6 阶段）
+
+AI 生成的脚本应覆盖以下 6 个阶段，可拆为独立脚本或合并为一个：
+
+```text
+阶段 1 · 登录探路
+  → Playwright 打开目标站点，完成登录，持久化 storage_state（cookie/session）
+  → 遍历左导航，抽取所有路由路径，落地为 routes.json
+
+阶段 2 · EULA / 首次弹窗处理
+  → 检测并关闭产品使用须知、隐私协议等首次弹窗，持久化到 storage_state
+
+阶段 3 · 一期：逐路由默认页 + 主按钮触发态
+  → 遍历 routes.json，每个路由截整页默认态
+  → 检测页面顶部操作按钮（按安全策略过滤），逐个点击并截图触发态
+
+阶段 4 · 二期：深度截图
+  → 列表页 tab / radio-group 切换态
+  → 表格行内 More 菜单展开 + 每个安全菜单项的结果
+  → Dialog/Drawer 内部 tab 切换态
+
+阶段 5 · 三期：左导专项
+  → 左导滚动到顶/底、整侧栏截图、折叠态、用户菜单弹出
+
+阶段 6 · 汇总
+  → 生成 README.md 索引所有截图，按路由分组
+```
+
+### 文件命名前缀约定
+
+| 前缀 | 含义 |
+| --- | --- |
+| `01-default.png` | 默认页（整页 `full_page=True`） |
+| `02..0N-{btn}.png` | 顶部主按钮触发态（后缀 `dialog` 或 `subpage`） |
+| `20-tab-{n}-{name}.png` | 列表页 tab / radio-group 切换态 |
+| `30-row-action-menu.png` | 表格首行 More 菜单展开 |
+| `31-row-{n}-{item}.png` | 行 More 菜单内每个安全项的结果 |
+| `40-{btn}-tab-{n}-{tab}.png` | Dialog/Drawer 内部 tab 切换态 |
+| `_aside/01..05-sidebar-*.png` | 左导专项（top/bottom/full/collapsed/user-menu） |
+
+### 按钮安全策略
+
+自动截图时严格区分安全按钮和危险按钮：
+
+**白名单（可点击）：** 新建、创建、添加、导入、上传、配置、详情、克隆、绑定、扩缩容、新增版本 — 打开表单/弹窗类
+
+**黑名单（禁止点击）：** 删除、停止、释放、提交、确认、保存、搜索、导出、重置 — 有副作用类
+
+按钮文本长度 >16 字的跳过（通常是状态/帮助文案，不是操作按钮）。
+
+### Dialog vs Subpage 判断
+
+点击按钮后检测 overlay 容器判断结果类型：
+
+| 检测选择器 | 判定 | 后续动作 |
+| --- | --- | --- |
+| `.next-overlay-wrapper.opened` / `.ant-modal-wrap` / `[role=dialog]` / `.ant-drawer-open` | **弹窗** | 截图 → ESC 关闭 |
+| 以上均未检测到 | **子页面** | 整页截图 → `safe_goto` 导航回列表页 |
+
+### DOM 选择器参考（Fusion / Next-design）
+
+实际内网控制台多为 Fusion/Next-design 体系，**非 antd**。关键选择器：
+
+| 元素 | 选择器 |
+| --- | --- |
+| Tab 激活项 | `.next-tabs-tab.active` |
+| 行内 More 按钮 | `.next-menu-btn` |
+| 菜单项（含禁用检测） | `.next-menu-item` / `.next-menu-item.next-disabled` |
+| Radio 组 | `.next-radio-group label.next-radio-button` |
+| Dialog 容器 | `.next-overlay-wrapper.opened` 内 `.next-dialog` / `.next-drawer` |
+| 左导结构 | `.ot-sidebar.fixed` → `.ot-sidebar-inner` → `header` / `body`(scrollable) / `footer` |
+| 用户菜单触发 | `.ot-sidebar-footer-more-btn`（底部 admin 行 ⋮） |
+
+### 关键避坑
+
+| 问题 | 解法 |
+| --- | --- |
+| 内网直连超时 | 走 HTTP 代理：`browser.launch(proxy={"server": PROXY})` + `--ignore-certificate-errors` |
+| `goto` 偶发 `ERR_CONNECTION_RESET` | 所有 `goto` 包 retry（3 次） |
+| EULA 弹窗遮挡 | 阶段 2 处理：检测并关闭弹窗，通过 `storage_state` 持久化关闭状态 |
+| 行内 More 菜单 JS `el.click()` 不触发 overlay | 必须用 Playwright `locator(...).click(timeout=3000)` 真实点击 |
+| 左导整侧栏截图 | JS 解 body 的 `maxHeight/overflow`，`.ot-sidebar` 设 `position: absolute` 解 fixed，`set_viewport_size` 到 `scrollHeight+40`，再 `locator('.ot-sidebar').screenshot()` |
+| 左导用户菜单截图 | 必须 fresh page（避开折叠 toggle 后 footer 结构变化） |
+| 整页 vs 弹层截图 | 默认 `full_page=True`；dialog/drawer 场景 `full=not visible`（只截首屏遮罩区域） |
+| 多步表单 Drawer | 仅截首步（点下一步常因表单未填被拦截） |
+| 无数据页 | 行级 More 菜单需至少一行数据，无数据页无 `30-`/`31-` 文件属正常 |