@wwkit/harness 1.0.9 → 1.0.11

package/commands/fix.md

@@ -0,0 +1,77 @@
+---
+description: 修复问题：问题定位→修复方案→修复测试→review→总结，并写入 {root_dir}/.webwork/harness/fix/yyyy-mm-dd/问题极简标题-hhmmss.md
+agent: build
+---
+
+你（build agent）根据用户问题描述 `$ARGUMENTS` 执行 5 阶段修复流程，产出文档写入 `{root_dir}/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md`。
+
+## 前置
+
+1. 解析问题描述 `$ARGUMENTS`；若为空，提示用户补充问题描述后停止。
+2. 确定工程根目录（当前 workdir / root_dir），所有相对路径基于它。
+3. 用 `todowrite` 建立 5 项任务清单（必须显式使用，逐项勾单，不攒批）：
+
+   - [ ] 1. 问题定位
+   - [ ] 2. 修复方案
+   - [ ] 3. 修复测试
+   - [ ] 4. review
+   - [ ] 5. 总结
+
+## 阶段 1：问题定位
+
+- 用 `grep`/`glob`/`read` 定位与问题相关的代码，梳理调用链，尽量复现问题。
+- 无法复现时如实记录"未能复现"及原因（环境/数据缺失等），不臆测。
+- 产出结论：**问题现象 → 定位位置（file:line）→ 根因**。
+
+## 阶段 2：修复方案
+
+- 先写方案再动手：列出涉及文件、改法、影响面、风险点。
+- 多种方案时选最简单可靠者，一句话说明取舍。
+- 方案需写出来（供阶段 4 review 对照），确认无逻辑漏洞后进入阶段 3。
+
+## 阶段 3：修复测试
+
+- 实施修改：遵循仓库既有代码风格，不加多余注释，只改必须改的地方。
+- 验证修复：运行相关测试/构建命令，或重跑复现用例确认症状消失。
+- 验证失败则回到阶段 2/3 迭代（自限 ≤3 轮），记录每轮结果。
+
+## 阶段 4：review
+
+- 自查 diff：边界情况、兼容性、遗漏改动、是否有其他调用方受影响。
+- 复查是否根治而非掩盖症状；发现问题回到阶段 2 修正，修正后重跑阶段 3 验证。
+- 全部通过后进入阶段 5。
+
+## 阶段 5：总结
+
+1. 生成日期目录和时间戳：`date +%Y-%m-%d` 获取日期，`date +%H%M%S` 获取时间戳（如 `{root_dir}/.webwork/harness/fix/2026-09-15/`），`mkdir -p` 创建。
+2. 标题：从问题描述提炼 ≤6 字极简短语（去空格/标点/特殊字符），如"登录接口401"。
+3. 用 `write` 写入 `{root_dir}/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md`，结构：
+
+   ```
+   # <问题极简标题>
+
+   - 日期：<yyyy-mm-dd>
+   - 问题描述：<用户描述摘要>
+
+   ## 1. 问题定位
+
+   <现象 / 位置 / 根因>
+
+   ## 2. 修复方案
+
+   <方案与取舍>
+
+   ## 3. 修复测试
+
+   <改动摘要 + 验证命令与结果>
+
+   ## 4. Review
+
+   <自查结论>
+
+   ## 5. 总结
+
+   <影响面、后续建议>
+   ```
+
+4. `todowrite` 确认 5 项全部勾完，向用户输出：**文档路径** + 修复结论摘要（改动文件、验证结果）。

package/commands/git-sync.md

@@ -0,0 +1,218 @@
+---
+description: Git commit all changes and push to remote branch with auto-detected change type
+---
+
+You are a Git commit assistant. Execute the following steps strictly:
+
+## Step 0: Pre-flight Checks
+
+1. **Check if in a git repository**:
+   ```bash
+   git rev-parse --is-inside-work-tree
+   ```
+   - If failed, output "Not a git repository" and stop
+
+2. **Check for unresolved conflicts**:
+   ```bash
+   git status | grep -E "(Unmerged paths|rebase|merge)"
+   ```
+   - If conflicts exist, output "Please resolve conflicts first" and stop
+
+3. **Check if there are changes**:
+   ```bash
+   git status --porcelain
+   ```
+   - If empty, output "No changes to commit" and stop
+
+4. **Generate timestamp** (used for branch naming):
+   ```bash
+   TIMESTAMP=$(date +"%Y%m%d%H%M%S")
+   ```
+   - Format includes seconds to avoid collisions
+
+## Step 1: Analyze Changes and Detect Type
+
+1. **Read changed files**:
+   ```bash
+   git status
+   git diff --stat
+   ```
+
+2. **Detect change type (kind)** based on content:
+   - `feat`: New features, new files added
+   - `fix`: Bug fixes, issue fixes
+   - `docs`: Documentation changes (README, comments, doc files)
+   - `style`: Code formatting (no functionality change)
+   - `refactor`: Code refactoring (neither new feature nor fix)
+   - `perf`: Performance optimization
+   - `test`: Test-related changes
+   - `chore`: Build process, auxiliary tools, dependency updates
+   - `ci`: CI configuration changes
+   - `revert`: Revert previous commit
+   
+   Priority when multiple types: feat > fix > perf > refactor > test > docs > style > chore > ci
+
+3. **Generate commit description**:
+   - Extract brief description from changes (in English)
+   - Format: `<kind>: <brief description>`
+
+## Step 2: Determine Remote Branch Name
+
+Based on parameter `$1`, determine the target remote branch name:
+
+### Scenario A: No parameter ($1 is empty)
+- Use current branch name as remote branch name:
+  ```bash
+  REMOTE_BRANCH=$(git branch --show-current)
+  ```
+
+### Scenario B: Parameter is "new"
+- Generate new remote branch name with personal identifier: `ss-<kind>-<timestamp>`
+- Example: `ss-feat-20260702153045`
+  ```bash
+  REMOTE_BRANCH="ss-<kind>-<timestamp>"
+  ```
+  - `ss-` prefix: personal identifier
+  - Timestamp includes seconds to avoid collisions
+
+### Scenario C: Parameter is a branch name (user-specified)
+- Use the specified name as remote branch name:
+  ```bash
+  REMOTE_BRANCH="$1"
+  ```
+
+## Step 3: Commit Changes (on current local branch)
+
+**Important**: Stay on current local branch, no switching needed
+
+1. **Add all changes**:
+   ```bash
+   git add -A
+   ```
+
+2. **Execute commit**:
+   ```bash
+   git commit -m "<kind>: <description>"
+   ```
+
+3. **Commit Failure Handling**:
+   - **If pre-commit hook fails**: Output hook error and stop
+   - **If no user name/email**: Output "Please configure git user.name and user.email" and stop
+   - **If nothing to commit**: Output "Nothing to commit" and stop
+
+## Step 4: Push to Remote Branch
+
+**Important**: Use HEAD syntax to push to target remote branch without switching local branch
+
+1. **Push using HEAD syntax**:
+   ```bash
+   git push origin HEAD:$REMOTE_BRANCH
+   ```
+   - This pushes current commit to the specified remote branch
+   - Local branch name can be different from remote branch name
+   - Remote branch is mainly for creating Merge Request (MR)
+
+2. **Push Conflict Handling**:
+   - If push fails due to remote conflicts, push to new remote branch:
+     ```bash
+     git push origin HEAD:$REMOTE_BRANCH-merge-$TIMESTAMP
+     ```
+   - Output: "Remote branch has conflicts, pushed to $REMOTE_BRANCH-merge-$TIMESTAMP"
+
+3. **Other Push Failures**:
+   - **Network error**: Retry once, then output "Network error, please try again"
+   - **Permission denied**: Output "Permission denied, check your credentials"
+   - **Remote repository not found**: Output "Remote repository not found"
+   - **Pre-push hook fails**: Output hook error and stop
+
+## Step 5: Final Status Check
+
+After successful push, show summary:
+```bash
+git log -1 --oneline
+git status
+```
+
+Output:
+```
+✓ Committed and pushed to remote branch '$REMOTE_BRANCH'
+- Local branch: <current-local-branch>
+- Remote branch: $REMOTE_BRANCH (for MR)
+- Commit: <commit-message>
+```
+
+## Important Notes
+
+- Never modify git config
+- Never use --force push
+- Never use --no-verify to skip hooks
+- Use English for commit messages
+- Keep timestamp consistent throughout the process
+- Stop execution and inform user on any error
+- **No local branch switching** - stay on current branch
+- Remote branch name is for MR creation, not required to match local branch
+
+## Error Handling Summary
+
+| Error Type | Detection | Handling |
+|------------|-----------|----------|
+| Not a git repo | `git rev-parse` | Stop with message |
+| Unresolved conflicts | `git status` | Stop with message |
+| No changes | `git status --porcelain` | Stop with message |
+| Commit hook failure | `git commit` fails | Stop with hook error |
+| Push conflict | `git push` fails | Push to new remote branch |
+| Network error | `git push` timeout | Retry once, then stop |
+| Permission error | `git push` denied | Stop with message |
+
+## Execution Examples
+
+**Example 1: No parameter, push to current remote branch**
+```
+User: /git-sync
+→ Check: git repository OK
+→ Check: no conflicts
+→ Analyze: added api.ts
+→ Type: feat
+→ Local branch: dev (stay here)
+→ Remote branch: dev
+→ Commit: feat: add API interface wrapper
+→ Push: git push origin HEAD:dev
+→ Success: pushed to remote 'dev' (for MR)
+```
+
+**Example 2: Parameter "new", push to new remote branch**
+```
+User: /git-sync new
+→ Check: git repository OK
+→ Analyze: fixed login bug
+→ Type: fix
+→ Timestamp: 20260702153045 (includes seconds)
+→ Local branch: dev (stay here)
+→ Remote branch: ss-fix-20260702153045 (new)
+→ Commit: fix: fix login validation logic error
+→ Push: git push origin HEAD:ss-fix-20260702153045
+→ Success: pushed to remote 'ss-fix-20260702153045' (for MR)
+```
+
+**Example 3: Parameter is branch name, push to specified remote**
+```
+User: /git-sync feature-user-auth
+→ Analyze: updated auth module
+→ Type: refactor
+→ Local branch: dev (stay here)
+→ Remote branch: feature-user-auth (user specified)
+→ Commit: refactor: refactor user authentication module
+→ Push: git push origin HEAD:feature-user-auth
+→ Success: pushed to remote 'feature-user-auth' (for MR)
+```
+
+**Example 4: Push conflict**
+```
+User: /git-sync feature-user-auth
+→ Local branch: dev
+→ Remote branch: feature-user-auth
+→ Commit: feat: new feature
+→ Push: CONFLICT (remote has diverged)
+→ Action: git push origin HEAD:feature-user-auth-merge-20260702153245
+→ Success: pushed to remote 'feature-user-auth-merge-20260702153245' (for MR)
+```

package/commands/net-port.md

@@ -0,0 +1,364 @@
+---
+description: Port management command - list, find (by port or process name), and kill processes by port
+---
+
+You are a port management assistant. Execute the following steps strictly.
+
+## Command Usage
+
+```
+/port [action] [arguments]
+```
+
+**Actions**:
+- `list` (default): List all listening ports
+- `find <query>`: Find process by port number(s) or process name (fuzzy match, case-insensitive)
+- `kill <port>`: Kill process using specific port(s)
+- `cmds`: Show copy-ready commands for each OS (find/kill by port)
+- `help`: Show command help and examples
+
+---
+
+## Step 1: Parse Command Arguments
+
+### Argument Extraction Rule (IMPORTANT for LLM)
+
+The user input follows the pattern: `/port [action] [arguments]`
+
+**Extraction algorithm** (apply this mentally, NOT as shell script):
+
+1. Split the user input after `/port` into tokens by whitespace
+2. **First token** -> check against known actions: `list`, `find`, `kill`, `cmds`, `help`
+   - If it matches a known action -> `ACTION = that token`, remaining tokens = `QUERY`
+   - If it does NOT match (e.g. a number like `5173` or a name like `node`) -> `ACTION = find` (implicit find), this token and all remaining = `QUERY`
+   - If NO tokens at all -> `ACTION = list`, `QUERY = ""`
+3. `QUERY` = all remaining tokens joined by space
+
+### Query Type Detection (CRITICAL)
+
+After extracting QUERY, determine its type to choose the correct find strategy:
+
+**Check each token in QUERY**:
+- If token is purely numeric (matches `^[0-9]+$`) -> **port number query**
+- If token contains non-numeric characters -> **process name query** (fuzzy match)
+- If comma-separated tokens are all numeric -> treat each as a port number
+- Mixed: process each token by its own type
+
+**Query Type Decision Table**:
+
+| QUERY | Type | Strategy |
+|---|---|---|
+| `5173` | Port number | Find by exact port |
+| `5173 5174` | Port numbers | Find by each exact port |
+| `5173,8080` | Port numbers | Find by each exact port (split on comma) |
+| `node` | Process name | Fuzzy match process name (case-insensitive) |
+| `weq` | Process name | Fuzzy match process name (case-insensitive) |
+| `vscode` | Process name | Fuzzy match process name (case-insensitive) |
+| `python` | Process name | Fuzzy match process name (case-insensitive) |
+| `WeLink` | Process name | Fuzzy match process name (case-insensitive) |
+
+### Full Decision Table
+
+| User Input | ACTION | QUERY | Type |
+|---|---|---|---|
+| `/port` | list | (empty) | - |
+| `/port list` | list | (empty) | - |
+| `/port help` | help | (empty) | - |
+| `/port find 5173` | find | 5173 | port |
+| `/port find 5173 5174` | find | 5173 5174 | port |
+| `/port find 8080,3000` | find | 8080,3000 | port |
+| `/port find node` | find | node | name |
+| `/port find weq` | find | weq | name |
+| `/port find vscode` | find | vscode | name |
+| `/port find python` | find | python | name |
+| `/port cmds` | cmds | (empty) | - |
+| `/port kill 5173` | kill | 5173 | port |
+| `/port kill 5173 5174` | kill | 5173 5174 | port |
+| `/port 5173` | find | 5173 | port |
+| `/port 5173 5174` | find | 5173 5174 | port |
+| `/port node` | find | node | name |
+| `/port 8080,3000` | find | 8080,3000 | port |
+
+**Normalize QUERY before processing**: split on commas -> trim whitespace -> classify each token as port or name.
+
+---
+
+## Step 2: Execute Actions
+
+### Action 1: List All Ports
+
+**Strategy**: Get all listening ports with process names in one batch query, output as a simple table.
+
+**Windows Implementation**:
+1. Run `netstat -ano | grep "LISTENING"` to get port-PID pairs
+2. Run `WMIC PROCESS GET ProcessId,Name /FORMAT:CSV` to get PID-Name mapping
+3. Join and output as table
+
+**Linux/macOS Implementation**:
+1. Run `lsof -i -P | grep "LISTEN"` or `ss -tulnp | grep "LISTEN"`
+2. Output as table
+
+**Output Format** (simple table, NO extra detail):
+```
+Port    Process              PID
+80      System               4
+5173    node.exe           16044
+5174    node.exe           30904
+3300    weq.exe            33820
+```
+
+---
+
+### Action 2: Find Process
+
+**Strategy**: Two modes based on query type. Always output a simple table, never list all ports.
+
+#### Mode A: Find by Port Number(s)
+
+When QUERY contains only numeric tokens, find processes listening on those specific ports.
+
+**For each port number**:
+1. Look up PID from netstat for that port
+2. Look up process name for that PID
+3. Include in results table
+
+**If no process found on a port**: show that port as "not found" in the table
+
+**Output Format** (simple table with status):
+```
+Port    Process        PID       Status
+5173    node.exe       16044     LISTENING
+5174    node.exe       30904     LISTENING
+8080    -              -         NOT FOUND
+```
+
+**IMPORTANT**: Do NOT list all ports when find by port. Only show queried ports.
+
+#### Mode B: Find by Process Name (Fuzzy Match)
+
+When QUERY contains non-numeric tokens, search all listening processes whose name matches the query (case-insensitive substring match).
+
+**Matching Rules**:
+- Case-insensitive: `node` matches `node.exe`, `Node.js`, etc.
+- Substring match: `weq` matches `weq.exe`, `vscode` matches `VSCode-huawei.exe`
+- The `.exe` suffix on Windows is ignored for matching purposes
+- Match against the process name WITHOUT the `.exe` suffix
+
+**Windows Implementation**:
+1. Get all listening ports with PIDs from `netstat -ano | grep "LISTENING"`
+2. Get all process names from `WMIC PROCESS GET ProcessId,Name /FORMAT:CSV`
+3. Filter processes whose name (lowercase, without .exe) contains the query (lowercase)
+4. Output matching entries
+
+**Linux/macOS Implementation**:
+1. Run `lsof -i -P | grep "LISTEN"`
+2. Filter by process name (case-insensitive substring match)
+3. Output matching entries
+
+**Output Format** (same simple table):
+```
+Port    Process              PID
+3300    weq.exe            33820
+55361   weq.exe            37848
+58995   weq.exe            33820
+61918   weq.exe            26484
+```
+
+**If no process matches**: output `[INFO] No process matching '<query>' found`
+
+---
+
+### Action 3: Kill Process by Port
+
+**Input**: Port number(s) only (kill does NOT support process name query)
+
+**Important**:
+- Ask for confirmation before proceeding
+- Show process details before killing
+- Report success/failure for each port
+
+**Windows Implementation**:
+1. Find PID by port from netstat
+2. Kill using `powershell -NoProfile -Command "Stop-Process -Id $PID -Force"`
+   - NOTE: Do NOT use `taskkill /F /PID` in Git Bash on Windows - the `/F` flag gets interpreted as a file path. Always use PowerShell `Stop-Process` instead.
+
+**Linux/macOS Implementation**:
+1. Find PID by port from lsof
+2. Kill using `kill $PID`, then `kill -9 $PID` if still running
+
+**Output Format**:
+```
+[WARN]  Port 5173: About to kill process 'node.exe' (PID: 16044)
+[WARN]  Port 5174: About to kill process 'node.exe' (PID: 30904)
+[SUCCESS] Port 5173: Process node.exe (PID: 16044) killed successfully
+[SUCCESS] Port 5174: Process node.exe (PID: 30904) killed successfully
+```
+
+---
+
+### Action 4: Show Copy-Ready Commands (`cmds`)
+
+**Output the following code block as-is, no execution needed.** The user wants to copy-paste these commands to share with others. Port `5173` is used as the example.
+
+Output exactly this content:
+
+```
+## List all listening ports
+
+# Windows (CMD / PowerShell)
+netstat -ano | findstr LISTENING
+
+# Windows (PowerShell, with process names)
+Get-NetTCPConnection -State Listen | Select-Object LocalPort, OwningProcess | Sort-Object LocalPort
+
+# Linux
+netstat -tulnp
+# or (may not installed on CentOS/RHEL minimal)
+ss -tulnp
+lsof -i -P | grep LISTEN
+
+# macOS
+lsof -i -P | grep LISTEN
+
+## Find process on port 5173
+
+# Windows (CMD / PowerShell)
+netstat -ano | findstr :5173
+tasklist | findstr <PID>
+
+# Windows (PowerShell, one-liner)
+Get-NetTCPConnection -LocalPort 5173 | Select-Object LocalPort, OwningProcess
+
+# Linux
+netstat -tulnp | grep :5173
+# or
+lsof -i :5173
+ss -tulnp | grep :5173
+
+# macOS
+lsof -i :5173
+
+## Kill process on port 5173
+
+# Windows (CMD / PowerShell - replace <PID> with actual PID)
+taskkill /F /PID <PID>
+
+# Windows (PowerShell)
+Stop-Process -Id <PID> -Force
+
+# Linux
+kill <PID>
+# force kill if needed
+kill -9 <PID>
+
+# macOS
+kill <PID>
+# force kill if needed
+kill -9 <PID>
+```
+
+---
+
+### Action 5: Show Help
+
+```
+USAGE:
+  /port [action] [arguments]
+
+ACTIONS:
+  list              List all listening ports (default)
+  find <port>       Find process by port number(s)
+  find <name>       Find process by name (fuzzy, case-insensitive)
+  kill <port>       Kill process by port number(s)
+  cmds              Show copy-ready commands for each OS
+  help              Show this help
+
+QUERY TYPES (for find):
+  Port number:  5173, 8080,3000, 5173 5174
+  Process name: node, weq, vscode, python, WeLink
+
+EXAMPLES:
+  /port                        List all ports
+  /port find 5173              Find by port number
+  /port find 5173,5174         Find by multiple ports
+  /port find node              Find all node processes
+  /port find weq               Find all weq processes
+  /port find vscode            Find all VSCode processes
+  /port find python            Find all python processes
+  /port 5173                   Shortcut: find by port
+  /port node                   Shortcut: find by name
+  /port kill 5173              Kill process on port 5173
+  /port kill 5173,5174         Kill processes on multiple ports
+
+SYSTEM SUPPORT:
+  Windows: netstat + WMIC + PowerShell Stop-Process
+  Linux:   netstat/ss + lsof + kill
+  macOS:   lsof + kill
+```
+
+---
+
+## Step 3: Cross-Platform Command Matrix
+
+| Action | Windows | Linux | macOS |
+|--------|---------|-------|-------|
+| **List Ports** | `netstat -ano` + WMIC | `netstat -tuln` / `ss -tuln` | `lsof -i -P` |
+| **Find by Port** | `netstat -ano` + WMIC | `lsof -i :port` | `lsof -i :port` |
+| **Find by Name** | `netstat -ano` + WMIC (filter) | `lsof -i -P` (filter) | `lsof -i -P` (filter) |
+| **Kill Process** | PowerShell `Stop-Process` | `kill PID` | `kill PID` |
+| **Copy-Ready Commands** | `cmds` action | `cmds` action | `cmds` action |
+
+---
+
+## Step 4: Output Format Standards
+
+### All find/list output: Simple table only
+
+```
+Port    Process              PID
+5173    node.exe           16044
+3300    weq.exe            33820
+```
+
+### Find by port with not-found entries
+
+```
+Port    Process        PID       Status
+5173    node.exe       16044     LISTENING
+8080    -              -         NOT FOUND
+```
+
+### Kill output
+
+```
+[WARN]  Port 5173: About to kill 'node.exe' (PID: 16044)
+[SUCCESS] Port 5173: Process node.exe (PID: 16044) killed successfully
+```
+
+---
+
+## Important Notes
+
+### Windows Git Bash Caveat
+
+- **Do NOT use `taskkill /F /PID`** in Git Bash on Windows. The `/F` flag is interpreted as a file path (e.g., `F:/`).
+- **Always use** `powershell -NoProfile -Command "Stop-Process -Id $PID -Force"` instead.
+
+### Find by Process Name
+
+- Case-insensitive substring match against process name (without `.exe` suffix)
+- Returns ALL listening ports whose process matches
+- If no match found, output `[INFO] No process matching '<query>' found`
+- Common use cases: `node`, `python`, `weq`, `vscode`, `java`
+
+### Kill Action
+
+- Kill only supports port number arguments, NOT process names
+- This is intentional: killing by name could terminate too many processes
+- Always ask for user confirmation before killing
+
+### Output Simplicity
+
+- **find** always outputs a simple table with columns: Port, Process, PID (and Status for port-not-found)
+- **Never** list all ports when user asked to find a specific port or process
+- **Never** output verbose PowerShell format lists

package/commands/pyit.md

@@ -0,0 +1,6 @@
+---
+description: Python 集成测试，传入目标模块路径和可选测试目录（如 /pyit src/mymodule tests/integration/mymodule）
+agent: pyit
+---
+
+对目标模块 $1 执行完整的集成测试流程，测试目录为 $2（可选，未指定时自动推导）。

package/commands/pyut.md

@@ -0,0 +1,6 @@
+---
+description: Python 单元测试，传入目标模块路径和可选测试目录（如 /pyut src/mymodule tests/unit/mymodule）
+agent: pyut
+---
+
+对目标模块 $1 执行完整的单元测试流程，测试目录为 $2（可选，未指定时自动推导）。