mingdao-harness 0.1.54

package/install.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# MingDao-Harness 一键安装脚本（三平台通用：Gitee / GitCode / GitHub 内容一致）
+# 用法：
+#   1) 在仓库目录内：bash install.sh                       —— 就地安装
+#   2) 一行安装：curl -fsSL <本平台 raw install.sh> | bash -s -- <gitee|gitcode|github>
+#      —— 脚本自动从指定平台（失败时依次兜底其余平台）获取仓库到 ~/.mingdao/repo 后安装
+# 功能：检查/自动安装 Node.js（官方源 → Gitee 镜像）→ 安装 mingdao 命令（npm link，或用户目录软链）
+set -euo pipefail
+
+GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; NC='\033[0m'
+info(){ echo -e "${GREEN}[MingDao]${NC} $*"; }
+warn(){ echo -e "${YELLOW}[警告]${NC} $*"; }
+die(){ echo -e "${RED}[错误]${NC} $*" >&2; exit 1; }
+
+# Windows 环境（Git Bash / MSYS）应改用 PowerShell 安装器
+case "$(uname -s 2>/dev/null)" in
+  MINGW*|MSYS*|CYGWIN*)
+    warn "检测到 Windows 环境，请改用 Windows 安装器："
+    echo "    双击 install.bat，或运行："
+    echo "    powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1"
+    exit 0
+    ;;
+esac
+
+# 首选平台（可选参数；未指定时按 gitee → gitcode → github 依次尝试，哪个通装哪个）
+PLATFORM="${1:-}"
+
+# 各平台 git 克隆地址与源码包下载地址（|分隔：平台|git|tarball）
+REPO_URLS="
+gitee|https://gitee.com/MingDaoTCM/MingDao-harness.git|https://gitee.com/MingDaoTCM/MingDao-harness/repository/archive/main.tar.gz
+gitcode|https://gitcode.com/MingDaoTCM/MingDao-Harness.git|https://gitcode.com/MingDaoTCM/MingDao-Harness/-/archive/main/MingDao-Harness-main.tar.gz
+github|https://github.com/MingDaoTCM/MingDao-Harness.git|https://github.com/MingDaoTCM/MingDao-Harness/archive/refs/heads/main.tar.gz
+"
+
+url_for(){ printf '%s\n' "$REPO_URLS" | grep "^$1|" | cut -d'|' -f"$2"; }
+is_repo(){ [ -f "$1/package.json" ] && [ -f "$1/src/cli.js" ]; }
+REPO_MODE="local"   # local（仓库内就地）| git（克隆）| tarball（源码包，无 .git）
+
+# 获取仓库到 ~/.mingdao/repo（git 优先，没有 git 时下载源码包）
+fetch_repo(){
+  local dir="$HOME/.mingdao/repo"
+  if [ -d "$dir/.git" ]; then
+    info "检测到已有仓库，尝试更新…"
+    git -C "$dir" pull --ff-only --quiet >/dev/null 2>&1 || warn "更新失败，继续使用现有仓库"
+    REPO_MODE="git"; cd "$dir"; return 0
+  fi
+  for p in ${PLATFORM:-} gitee gitcode github; do
+    local git_url tgz
+    git_url="$(url_for "$p" 2)"; tgz="$(url_for "$p" 3)"
+    if command -v git >/dev/null 2>&1 && git clone --depth 1 --quiet "$git_url" "$dir" 2>/dev/null; then
+      REPO_MODE="git"; cd "$dir"; info "已从 $p 克隆仓库（git）"; return 0
+    fi
+    rm -rf "$dir"
+    if curl -fsSL -m 120 "$tgz" -o /tmp/mingdao-repo.tgz 2>/dev/null; then
+      mkdir -p "$dir"
+      if tar -xzf /tmp/mingdao-repo.tgz -C "$dir" --strip-components=1 2>/dev/null; then
+        rm -f /tmp/mingdao-repo.tgz
+        REPO_MODE="tarball"; cd "$dir"
+        info "已从 $p 下载源码包（无 .git；升级请重新运行本安装脚本）"
+        return 0
+      fi
+      rm -rf "$dir"
+    fi
+    rm -f /tmp/mingdao-repo.tgz
+  done
+  die "无法获取仓库（git 与源码包下载均失败）。请手动克隆任意平台仓库后，在仓库内运行 bash install.sh。"
+}
+
+# 定位安装源：仓库目录内 → 就地；否则（curl|bash）→ 自动获取仓库。
+# 注意：curl | bash 管道执行时 BASH_SOURCE 未绑定，需给默认值（set -u 下否则报错）。
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-}")" && pwd)"
+if is_repo "$SCRIPT_DIR"; then
+  cd "$SCRIPT_DIR"
+else
+  info "未在仓库目录中运行，自动获取仓库（平台：${PLATFORM:-自动}）…"
+  fetch_repo
+fi
+
+# ---------- 1. 检查 Node.js >= 18.17 ----------
+need_node() {
+  if command -v node >/dev/null 2>&1; then
+    local major
+    major="$(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)"
+    if [ "$major" -ge 18 ]; then return 0; fi
+    warn "检测到 Node.js $(node -p 'process.versions.node' 2>/dev/null)，需要 >= 18.17"
+    return 1
+  fi
+  return 1
+}
+
+install_node() {
+  info "未找到合适的 Node.js，尝试通过 nvm 自动安装…"
+  if ! command -v curl >/dev/null 2>&1; then
+    die "缺少 curl，无法自动安装。请手动安装 Node.js 18+（https://nodejs.org）后重新运行本脚本。"
+  fi
+  export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+  # nvm 安装源：官方 raw.githubusercontent → 失败回落 Gitee 镜像（国内可用）
+  local official=1
+  if ! curl -fsSL -m 60 https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh -o /tmp/mingdao-nvm.sh 2>/dev/null; then
+    official=0
+    warn "nvm 官方源不可达，改用 Gitee 镜像 + npmmirror 的 Node 下载源（国内网络）…"
+    curl -fsSL -m 60 https://gitee.com/mirrors/nvm/raw/master/install.sh -o /tmp/mingdao-nvm.sh || die "nvm 下载失败（官方与镜像均不可达），请手动安装 Node.js 18+"
+    export NVM_NODEJS_ORG_MIRROR="${NVM_NODEJS_ORG_MIRROR:-https://npmmirror.com/mirrors/node}"
+  fi
+  bash /tmp/mingdao-nvm.sh >/dev/null 2>&1 || true
+  rm -f /tmp/mingdao-nvm.sh
+  # shellcheck disable=SC1090
+  [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+  if ! command -v nvm >/dev/null 2>&1; then
+    die "nvm 安装失败，请手动安装 Node.js：https://nodejs.org"
+  fi
+  nvm install 20 >/dev/null || nvm install --lts
+  nvm use 20 2>/dev/null || true
+  if [ "$official" = "0" ]; then unset NVM_NODEJS_ORG_MIRROR; fi
+  info "Node.js 已就绪：$(node --version)"
+}
+
+if ! need_node; then install_node; fi
+if ! need_node; then die "Node.js 版本检查失败。"; fi
+
+# ---------- 2. 安装 mingdao 命令 ----------
+# 优先 npm link：全局命令软链到仓库 → 仓库常驻，mingdao update 可自更新
+info "安装 mingdao 命令…"
+if command -v npm >/dev/null 2>&1 && npm link --silent >/dev/null 2>&1; then
+  info "已全局安装（npm link → 指向仓库，支持 mingdao update 自更新）"
+else
+  warn "npm link 失败（可能没有管理员权限），改为用户目录软链（同样支持 mingdao update）…"
+  chmod +x "$(pwd)/src/cli.js"
+  mkdir -p "$HOME/.local/bin"
+  ln -sf "$(pwd)/src/cli.js" "$HOME/.local/bin/mingdao"
+  ln -sf "$(pwd)/src/cli.js" "$HOME/.local/bin/mdh"
+  if ! printf '%s' "$PATH" | tr ':' '\n' | grep -qx "$HOME/.local/bin"; then
+    warn "请把 $HOME/.local/bin 加入 PATH（在 ~/.bashrc 或 ~/.zshrc 末尾添加）："
+    echo "    export PATH=\"\$HOME/.local/bin:\$PATH\""
+  fi
+fi
+
+# ---------- 3. 完成 ----------
+if command -v mingdao >/dev/null 2>&1; then
+  info "安装完成！"
+  echo ""
+  echo "  接下来："
+  echo "    1. 运行 'mingdao init' 配置模型（API Key 从 https://platform.deepseek.com 获取）"
+  echo "    2. 输入 'mingdao' 开始对话"
+  echo "    3. 'mingdao \"你的问题\"' 可单次提问，'mingdao --continue' 继续上次会话"
+  if [ "$REPO_MODE" = "tarball" ]; then
+    echo "    4. 新版本发布后重新运行本安装脚本即可升级"
+  else
+    echo "    4. 新版本发布后 'mingdao update' 一键升级（失败自动回滚）"
+  fi
+else
+  warn "安装完成，但当前终端还找不到 mingdao 命令。"
+  warn "请重新打开终端，或按上方提示把 ~/.local/bin 加入 PATH 后重试。"
+fi

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "mingdao-harness",
+  "version": "0.1.54",
+  "description": "明道 MingDao —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
+  "type": "module",
+  "bin": {
+    "mingdao": "src/cli.js",
+    "mdh": "src/cli.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "assets/",
+    "docs/",
+    "install.sh",
+    "install.ps1",
+    "install.bat",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MingDaoTCM/MingDao-Harness.git"
+  },
+  "author": "MingDao-Harness Contributors",
+  "bugs": {
+    "url": "https://github.com/MingDaoTCM/MingDao-Harness/issues"
+  },
+  "homepage": "https://harness.mingdao.ai",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "keywords": [
+    "agent",
+    "harness",
+    "ai",
+    "cli",
+    "tui",
+    "llm",
+    "deepseek",
+    "coding-agent",
+    "mingdao"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node test/smoke.js",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "node test/smoke.js && node test/e2e-local.js && node test/e2e-schedule.js",
+    "desktop": "npm --prefix desktop start",
+    "desktop:dist": "npm --prefix desktop run dist:dir"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  }
+}

package/skills/api-design/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: api-design
+description: 设计或实现 REST API、审查接口设计时使用
+---
+
+# REST API 设计
+
+## 规则
+
+1. **资源命名**：名词复数、层级清晰：`/users/{id}/orders`；动词交给 HTTP 方法。
+2. **查询参数**：过滤 `?status=active`、排序 `?sort=-created_at`、分页 `?page=1&page_size=20`。
+3. **状态码语义准确**：
+   - 200 成功读取 / 201 创建 / 204 删除
+   - 400 参数错误 / 401 未认证 / 403 无权限 / 404 不存在 / 409 冲突 / 422 语义错误 / 500 服务端错误
+4. **统一错误体**：`{ "code": "...", "message": "...", "details": [...] }`，所有端点一致。
+5. **分页**：返回 `total` 与 `items`；大集合用 cursor。
+6. **版本化**：`/v1` 前缀或 header，破坏性变更升版本。
+
+## 交付
+
+给出：资源与端点表（方法 + 路径 + 说明 + 请求/响应示例）、错误码表、鉴权方式；实现后同步更新接口文档。

package/skills/code-review/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: code-review
+description: 审查代码/PR，或用户要求自查代码质量、找问题时使用
+---
+
+# 代码审查
+
+## 优先级
+
+**正确性 > 生命周期与资源释放 > 安全 > 行为破坏 > 风格。**
+
+一个确凿的阻塞问题，胜过一长串小意见。
+
+## 检查清单
+
+1. **正确性**：边界值、空值、错误路径、并发/异步竞态；每条分支都有归属。
+2. **生命周期**：文件句柄、子进程、定时器、事件监听是否可逆释放；失败路径不泄漏。
+3. **安全**：注入（命令/SQL/路径）、凭据硬编码、敏感信息日志。
+4. **行为**：默认值、错误信息、返回结构变化是否破坏调用方。
+5. **可维护**：命名是否诚实、重复是否值得抽取、注释是否解释"为什么"。
+
+## 输出格式
+
+```
+✅ 总体判断：一句话
+🔴 阻塞（必须改）：
+1. …（文件:行号 + 理由 + 建议）
+🟡 建议：
+1. …
+🟢 亮点（可选）
+```

package/skills/debugging/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: debugging
+description: 排查 bug、分析报错、定位异常行为时使用
+---
+
+# 系统化调试
+
+## 流程
+
+1. **复现**：构造最小复现用例；无法稳定复现的问题先收集现场信息。
+2. **读错误**：完整阅读堆栈与日志，找**第一现场**（最深的用户代码帧），不要只看最后一行。
+3. **二分定位**：用日志/断点/注释逐段缩小范围，把"可能"变成"确定"。
+4. **假设-验证**：每条假设都要用命令或工具验证，禁止凭猜测改代码。
+5. **修根因**：修复后补回归测试，确认原场景与相邻场景都通过。
+
+## 纪律
+
+- 同一方向最多尝试 3 次，失败就换思路，不要反复撞墙
+- 修改前先 `read` 现场代码，改动后用 `edit` 精确修改
+- 环境问题（版本/依赖/权限）用 `bash` 验证：`node -v`、`python -c "import x"` 等
+- 不要把"删掉重写"当作调试手段

package/skills/docker/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: docker
+description: 容器化应用、编写 Dockerfile / docker-compose、排查容器问题时使用
+---
+
+# 容器化
+
+## Dockerfile 最佳实践
+
+1. **多阶段构建**：builder 阶段编译，runtime 阶段只带产物，镜像最小化。
+2. **基础镜像固定 tag**（如 `node:20-alpine`），不用 `latest`。
+3. **非 root 运行**：`USER` 指定非特权用户。
+4. **分层缓存**：先 COPY 依赖清单并安装（`npm install` / `pip install`），再 COPY 源码。
+5. **健康检查**：`HEALTHCHECK` 指向存活端点；`EXPOSE` 声明端口。
+6. `.dockerignore` 排除 node_modules/.git/日志。
+
+## compose 要点
+
+- 服务依赖用 `depends_on` + `condition: service_healthy`
+- 数据卷挂载与端口映射显式声明
+- 环境变量走 `.env`，敏感值不进 compose 文件
+
+## 验证闭环
+
+1. `docker build` 实际构建通过
+2. `docker run` 起一次容器并验证健康检查
+3. 排查：`docker logs`、`docker exec -it <id> sh` 进容器看现场

package/skills/docx/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: docx
+description: 创建、读取、编辑 Word 文档（.docx）时使用
+---
+
+# Word 文档处理
+
+## 工具选择
+
+| 场景 | 工具 |
+| --- | --- |
+| 读写段落/表格/样式 | `python-docx` |
+| 格式转换 | `pandoc`（docx ↔ md ↔ pdf） |
+| 转 PDF | `libreoffice --headless --convert-to pdf` |
+| 只读提取文本 | `docx2txt` |
+
+## 常用模式
+
+1. **生成文档**：先建样式骨架（标题层级、正文字体），再逐段填充；表格用 `document.add_table`。
+2. **读取**：遍历 `document.paragraphs` 与 `document.tables`，按需抽取标题层级。
+3. **模板填充**：复制模板 docx，用 `{{占位符}}` 替换。
+4. **修改已有文档**：python-docx 打开 → 修改 → 另存，不要手工拼 XML。
+
+## 要点
+
+- 首次使用先 `pip install python-docx`
+- 生成后校验：重开文件统计段落/表格数，确认无损坏
+- 中文场景检查字体设置（宋体/黑体），避免导出后乱码

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: frontend-design
+description: 生成前端页面、UI 组件（HTML/CSS/React/Vue）时使用；目标是做出"不像 AI 生成"的成品
+---
+
+# 前端设计原则
+
+## 动手前
+
+1. 明确**目的与受众**：这个页面要用户完成什么动作？谁在看？
+2. 一个页面一个**主行动**（主按钮），层级用视觉强度表达。
+3. 先静态原型后接框架：用单文件 HTML 快速验证，确认后移植。
+
+## 设计要点
+
+- **排版**：字号层级 ≥3 级；正文行高 1.5–1.7；文本块宽度 ≤65ch
+- **配色**：一个主色 + 中性色阶；语义色只用于状态（成功/警告/错误）；正文对比度 ≥4.5:1
+- **间距**：4/8 网格；分组靠留白而非边框
+- **状态**：hover / focus / loading / empty / error 五态齐全
+- **细节**：真实文案而非 lorem ipsum；图标统一风格；移动端先设计
+
+## 避免"AI 味"
+
+- ❌ 默认紫蓝渐变、玻璃拟态堆砌
+- ❌ 千篇一律的三卡片 + 图标布局
+- ❌ emoji 当图标、无意义动画
+- ✅ 留白、克制的阴影、清晰的信息层级
+
+## 交付
+
+给出页面结构与关键 CSS/组件代码，说明响应式断点与可访问性处理（alt、focus、语义标签）。

package/skills/git-commit/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: git-commit
+description: 生成规范的 Git 提交信息（Conventional Commits），或用户要求写 commit message / 提交代码时使用
+---
+
+# Git 提交规范
+
+## 格式
+
+```
+<type>(<scope>): <subject>
+
+<body>（可选，说明动机而非过程）
+```
+
+- type：`feat` 新功能 / `fix` 修复 / `docs` 文档 / `refactor` 重构 / `test` 测试 / `chore` 杂务 / `style` 格式 / `perf` 性能 / `ci` 流水线
+- subject：≤50 字的中文祈使句，不加句号
+- 一条 commit 只做一件事；混在一起的改动先拆分
+
+## 工作流
+
+1. `git status` / `git diff --stat` 查看改动范围
+2. 需要时 `git diff <file>` 细看关键改动
+3. 按规范撰写，用 `git commit -m` 提交前把完整信息展示给用户确认
+
+## 示例
+
+```
+feat(export): 支持导出 Markdown 报告
+
+新增 --format md 选项，复用现有模板渲染管线。
+```

package/skills/pdf/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: pdf
+description: 读取、解析、生成、合并、拆分 PDF 文件时使用
+---
+
+# PDF 处理
+
+## 场景 → 工具
+
+| 场景 | 推荐 |
+| --- | --- |
+| 提取文本（速度优先） | `pymupdf`（fitz） |
+| 提取表格 | `pdfplumber`（表格识别强） |
+| 纯命令行提取 | `pdftotext` / `pdfinfo`（poppler-utils） |
+| 合并/拆分/旋转/加水印 | `pypdf` |
+| 程序生成报表 | `reportlab` |
+| 扫描件（无文本层） | OCR：`tesseract` + `pdf2image` |
+
+## 工作流
+
+1. **先探测环境**：`python -c "import fitz"` 等确认依赖，缺什么 `pip install pymupdf`。
+2. 大文件先看页数：`pdfinfo file.pdf` 或用 fitz 统计，避免一次性读入内存。
+3. 输出结果写回文件（write 工具）或直接打印关键数据，附上页码范围。
+4. 校验：合并后重开验证页数；提取后抽查文本。
+
+## 常见坑
+
+- 提取文本顺序混乱 → 用 `sort=True` 或按坐标排序
+- 表格识别不准 → pdfplumber 的 `extract_tables` + 手动核对列
+- 中文乱码 → 确认字体嵌入与编码（reportlab 用 CID 字体）

package/skills/pptx/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: pptx
+description: 生成演示文稿（.pptx）：汇报、教学、方案展示时使用
+---
+
+# PPT 生成
+
+## 工具
+
+- `python-pptx`：程序化生成（首次使用 `pip install python-pptx`）
+
+## 工作流
+
+1. **定结构**：先列大纲（每页一个核心观点），与用户确认页数。
+2. **用母版布局**：优先使用默认模板的 `slide_layouts`（标题页/标题+内容），避免手工摆坐标。
+3. **填充内容**：标题 ≤ 12 字；正文要点化（每条 ≤ 20 字）；图/表优先于长段落。
+4. **统一风格**：字体、配色全篇一致；空白充足。
+5. **校验**：生成后用 python-pptx 读回，检查页数、每页形状数量；再 `libreoffice --headless --convert-to pdf` 抽查渲染效果。
+
+## 设计红线
+
+- 一页一个观点；忌整页文字
+- 忌花哨动画/多余装饰
+- 数据页必须有来源与单位

package/skills/refactoring/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: refactoring
+description: 重构代码、改善结构但保持行为不变时使用
+---
+
+# 安全重构
+
+## 核心原则
+
+**小步、可回退、每步可验证。** 行为保持不变是硬约束。
+
+## 工作流
+
+1. **建安全网**：先跑一遍现有测试；没有测试就先补一条主路径测试，记录当前行为。
+2. **小步 edit**：每次只做一个动作（改名 / 提取函数 / 消除重复），不夹带逻辑修改。
+3. **每步验证**：跑测试；失败立即用 `undo` 回退，不要带着红测试继续。
+4. **顺序**：先易后难——重命名 → 提取函数 → 调整结构 → 最后才动算法。
+5. **收尾**：删除因重构而死的代码，更新注释与文档。
+
+## 红线
+
+- 重构和改功能分两次进行
+- 不重构没测试覆盖、也不理解的代码
+- 大文件先加测试护栏再动结构

package/skills/release-checklist/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: release-checklist
+description: 准备发布新版本、打包交付前使用
+---
+
+# 发布检查清单
+
+按顺序逐项确认，全部通过才可发布：
+
+1. **测试**：全量测试通过，记录命令与结果（`npm test` / `pytest` 等）。
+2. **版本**：版本号统一（package.json / 配置 / 文档互相一致），遵循语义化版本。
+3. **变更说明**：changelog 用用户语言描述新增/修复/破坏性变更。
+4. **构建验证**：实际构建/打包一次，并在干净环境验证产物可安装可运行。
+5. **敏感信息**：密钥、token、内网地址、个人信息不得进入仓库与产物（`grep -rE 'sk-[A-Za-z0-9]{20,}' .`）。
+6. **回滚方案**：明确如何回退到上一版本（旧包/旧 tag 可恢复）。
+7. **发布后冒烟**：发布完成后立即做一次端到端验证。
+
+## 输出
+
+给出「检查表 + 每项结论（✅/❌）+ 未通过项的修复建议」，发布动作本身必须等用户确认。

package/skills/testing/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: testing
+description: 编写单元测试/集成测试、为代码补测试时使用
+---
+
+# 测试编写
+
+## 用例设计（表驱动思维）
+
+每个被测函数至少覆盖四类输入：
+
+| 类别 | 内容 |
+| --- | --- |
+| 正常 | 典型输入的主路径 |
+| 边界 | 空、0、1、最大值、恰好等于阈值 |
+| 异常 | 非法输入、错误类型、缺失字段 |
+| 组合 | 多参数交互的关键组合 |
+
+## 规范
+
+1. 测试名描述**行为**而非实现（"余额不足时报错" > "test_error2"）。
+2. 一条测试只断言一件事；断言用真实期望值，不照抄实现。
+3. 少 mock：优先真实对象与临时目录；只 mock 网络/时间/随机源。
+4. 不测试第三方库本身，测试你的调用逻辑。
+
+## 落地
+
+- 先确认项目已有框架与运行命令（package.json scripts / pytest / vitest 等），沿用现有约定
+- 新补测试先跑失败（红），再让实现通过（绿）
+- 交付时报告：加了哪些用例、运行命令、通过结果

package/skills/webapp-testing/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: webapp-testing
+description: 测试本地 Web 应用/服务（接口、页面、报错）时使用
+---
+
+# Web 应用测试
+
+## 分层测试
+
+### 接口层（curl，零依赖）
+
+- 状态码/响应体/重定向：`curl -sS -i http://localhost:PORT/path`
+- 常见断言：200/201/204、JSON 字段存在、错误格式统一
+- 写脚本循环检查健康端点，最多重试 N 次，每次间隔 1s
+
+### 浏览器层（Playwright）
+
+- 首次使用：`pip install playwright && playwright install chromium`
+- 无头模式：打开页面 → 截图 → 断言选择器文本 → 收集 console 错误
+- 交互流程：点击、填表、等待元素出现（`wait_for_selector`）
+
+## 纪律
+
+1. **启动即负责**：自己起的服务进程，测试完必须杀掉（记录 PID）。
+2. 先确认服务真的起来了（健康检查轮询），再断言业务。
+3. 失败时保留现场：截图、响应体、日志一起给用户。
+4. 端口冲突先 `lsof -i :PORT` / `netstat -ano` 排查。

package/skills/xlsx/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: xlsx
+description: 处理 Excel 表格（.xlsx/.xls/.csv）数据：读取、统计、清洗、生成报表时使用
+---
+
+# Excel 表格处理
+
+## 工具选择
+
+| 场景 | 工具 |
+| --- | --- |
+| 单元格级读写、格式、公式 | `openpyxl` |
+| 批量统计/清洗/透视（数据思维） | `pandas` |
+| 简单 CSV | 标准库 `csv`（零依赖） |
+| 大文件（>100MB） | openpyxl `read_only` 模式，或 pandas 分块读取 |
+
+## 工作流
+
+1. 先探明结构：读表头与前 5 行，确认列名、空值、类型。
+2. 用 pandas 做统计：分组、透视、去重、缺失值统计，输出关键结论而非全量数据。
+3. 生成结果写新文件（不要覆盖原始数据），并校验行数。
+4. CSV 编码坑：中文优先 `utf-8-sig`（Excel 兼容）。
+
+## 要点
+
+- 首次使用先 `pip install openpyxl pandas`
+- 大文件先 `wc -l` 估算规模再决定工具
+- 数值列注意空字符串/文本型数字，统计前先 `pd.to_numeric(errors='coerce')`