@zhushanwen/pi-evolve-daily 0.1.0

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index";

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@zhushanwen/pi-evolve-daily",
+  "version": "0.1.0",
+  "description": "Daily evolution data collector — runs Python analyzer on first session of the day.",
+  "main": "src/index.ts",
+  "files": [
+    "src/",
+    "index.ts",
+    "skills/"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit"
+  }
+}

package/skills/evolve/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: evolve
+description: "Analyze session usage data and generate evolution suggestions. Runs Python analyzer data through LLM analysis to produce actionable improvement recommendations for CLAUDE.md and skills. Trigger: /evolve, evolve, 进化分析, 分析使用模式, analyze usage."
+---
+
+# Evolve — Usage Analysis & Suggestion Generator
+
+## Purpose
+
+Analyze Pi agent usage data, identify trends and anomalies, and generate
+evolution suggestions for CLAUDE.md and skill files.
+
+## When Triggered
+
+User says "/evolve", "evolve", "进化分析", "分析使用模式", or wants to
+analyze usage patterns.
+
+## Procedure
+
+### 1. Parse User Intent
+
+- No args → analyze last 7 days, all dimensions
+- `since=Nd` → analyze last N days
+- "分析 skill" / "分析 CLAUDE.md" → focus on specific dimension
+- Natural language: extract time range and focus area
+- **Fallback**: If intent cannot be determined from the natural language input,
+  default to last 7 days, all dimensions. Do not ask clarifying questions.
+
+### 2. Read Data Sources
+
+Read files from `~/.pi/agent/evolution-data/`:
+
+**Required** (always read, analysis stops if missing):
+- `daily-reports/*.json` — Python analyzer deep analysis (`.json` files only;
+  `.md` files are legacy, ignore them)
+
+**Recommended** (read if available, enhance analysis):
+- `history.jsonl` — applied suggestion history (for effect review)
+- `metrics-history.json` — metric trends
+
+**Optional** (read only when analyzing specific dimensions):
+- `daily/*.json` — daily summaries (date, sessions, toolCalls, tokens)
+- `skill-triggers.json` — skill usage statistics
+- `tool-stats.json` — tool call statistics
+
+Filter by user's requested time range. If requesting "last N days",
+read files with dates >= (today - N days).
+
+**Data integrity checks:**
+- If daily-reports JSON fails to parse (corrupt/malformed), skip that file
+  and note it in the suggestion output, but continue with other files
+- If history.jsonl is empty or has invalid JSON lines, skip it gracefully
+- If `extract_context.py` times out or errors, skip the deep-dive for that
+  pattern but continue with other suggestion sources
+- If skill-triggers.json or tool-stats.json are missing, skip optional
+  enhancements without error
+
+**No data scenario:** If no daily-reports exist for the requested range,
+tell the user: "No usage data available for the requested period. Ensure
+the evolve-daily extension is installed and has had time to collect data."
+Do NOT proceed to generate suggestions.
+
+### 3. Analyze
+
+Use your judgment to identify:
+- **Trends**: Increasing/decreasing patterns in tool usage, token consumption,
+  error rates
+- **Anomalies**: Spikes in errors, sudden drops in efficiency
+- **Opportunities**: Skills never triggered, redundant patterns, optimization
+  chances
+- **Effect review**: Check history.jsonl for recently applied suggestions and
+  evaluate their impact using before/after metrics
+
+#### 3a. Error Deep Dive (failure_refs → extract_context.py)
+
+When `error_stats.top_error_patterns` contains high-severity patterns
+(error count >= 5 or error rate > 20%), use `extract_context.py` to fetch
+real failure cases for richer rationale:
+
+```bash
+# 提取某个 error pattern 的典型案例（推荐用批量模式）
+python3 ~/.pi/agent/scripts/pi-session-analyzer/extract_context.py \
+  --pattern "Could not find the exact text" \
+  --from-report ~/.pi/agent/evolution-data/daily-reports/YYYY-MM-DD.json \
+  --limit 2
+```
+
+This returns the full tool call arguments, error content, and surrounding
+context (user messages, retry behavior). Use this evidence to write more
+specific suggestions.
+
+`failure_refs` in `error_stats` contains one entry per error:
+- `session_id` — identify the session
+- `tool_call_id` — identify the specific tool call
+- `pattern` — error pattern category
+- `self_corrected` — whether AI retried successfully afterward
+
+You can also extract a single case if you have a specific ref:
+```bash
+python3 ~/.pi/agent/scripts/pi-session-analyzer/extract_context.py \
+  --session-id <session_id> --tool-call-id <tool_call_id>
+```
+
+**Failure handling:** If extract_context.py exits with non-zero code or
+produces no output, skip the deep-dive for that pattern. The analysis
+will still produce suggestions from aggregate data.
+
+#### 3b. Skill Trigger Source Analysis
+
+`skill_stats` now includes three fields:
+- `triggered_skills` — combined view (backward compatible)
+- `ai_triggered` — skills triggered by AI reading SKILL.md via read tool
+- `user_triggered` — skills triggered by user via `/skill:name` command
+
+Use these to identify:
+- **AI-only skills** — AI reads them proactively; check if description
+  triggers too eagerly or not enough
+- **User-only skills** — users explicitly invoke them; check if AI should
+  also learn to use them autonomously
+- **Mixed-trigger skills** — both paths used; healthy signal
+- **Never-triggered skills** — candidates for removal or description improvement
+
+### 4. Generate Suggestions
+
+For each actionable finding, create an EvolutionSuggestion object:
+
+| Field | Value |
+|-------|-------|
+| id | Generate a UUID: `python3 -c "import uuid; print(uuid.uuid4())"` |
+| target | "claude-md" or "skill" |
+| targetPath | Absolute path to target .md file under `~/.pi/agent/` |
+| severity | "high" (breaks workflow), "medium" (significant improvement), "low" (nice-to-have) |
+| confidence | 0.0-1.0 based on data strength |
+| title | One-line summary |
+| description | Detailed description of the issue and proposed change |
+| rationale | Data-backed reasoning (cite specific numbers; for error patterns, include evidence from extract_context.py) |
+| instruction | Step-by-step modification instruction for the LLM to apply |
+| status | "pending" |
+
+**Constraints:**
+- targetPath MUST be under `~/.pi/agent/` and end with `.md`
+- Limit to 3-7 suggestions per run (prioritize by severity * confidence)
+- Each suggestion must be independently actionable
+
+### 5. Write pending.json
+
+Write to `~/.pi/agent/evolution-data/suggestions/pending.json`:
+
+```json
+{
+  "generatedAt": "2026-05-31T14:00:00Z",
+  "reportUsed": {
+    "sources": ["daily-reports", "history.jsonl"],
+    "deepDivePatterns": ["Could not find the exact text"]
+  },
+  "suggestions": [
+    {
+      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "target": "skill",
+      "targetPath": "/Users/example/.pi/agent/skills/whitespace-fixer/SKILL.md",
+      "severity": "high",
+      "confidence": 0.85,
+      "title": "Optimize whitespace-fixer trigger to reduce edit failures",
+      "description": "whitespace-fixer has a 12% edit match failure rate...",
+      "rationale": "282 total errors in last 7 days, edit failure rate 9.2%",
+      "instruction": "In the SKILL.md description...",
+      "status": "pending"
+    }
+  ]
+}
+```
+
+Use the `write` tool to overwrite the file. **Note:** Any previously pending
+suggestions will be replaced. The user should process them via `/evolve-apply`
+before running a new `/evolve` analysis.
+
+**If write fails**: Tell the user the write failed and the suggestions
+were not persisted. Show the suggestions in the conversation output so the
+user can manually save them. Do NOT silently lose the analysis results.
+
+### 6. Present Results
+
+Show the user a summary:
+- Number of suggestions generated (0 → report "No actionable suggestions found
+  this time")
+- Top 3 by severity (include severity, title, and brief rationale for each)
+- How to apply: "/evolve-apply list" to view all, "/evolve-apply apply N" to apply
+- If zero severity/candidates found (all confidence < 0.3), report that no
+  actionable suggestions were found rather than forcing low-confidence output

package/skills/evolve-apply/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: evolve-apply
+description: "Manage evolution suggestion lifecycle: list, apply, skip, and rollback suggestions generated by /evolve. Trigger: /evolve-apply, evolve-apply, 应用建议, /evolve-rollback, evolve rollback."
+---
+
+# Evolve-Apply — Suggestion Lifecycle Manager
+
+## Purpose
+
+View, apply, skip, or rollback evolution suggestions from pending.json.
+
+## When Triggered
+
+User says "/evolve-apply", "evolve-apply", "应用建议", "/evolve-rollback",
+"evolve rollback", or wants to manage evolution suggestions.
+
+## Data Paths
+
+- Pending: `~/.pi/agent/evolution-data/suggestions/pending.json`
+- History: `~/.pi/agent/evolution-data/history.jsonl`
+- Backups: `~/.pi/agent/evolution-data/backups/`
+
+## Procedure
+
+### Parse Command
+
+- No args or "list" → LIST mode
+- "apply N" → APPLY mode (0-indexed)
+- "skip N" → SKIP mode (0-indexed)
+- "rollback" → ROLLBACK mode
+
+---
+
+### LIST Mode
+
+1. Read `pending.json` using the `read` tool
+2. If file doesn't exist or suggestions array is empty:
+   "No pending suggestions. Run /evolve first to generate suggestions."
+3. Display each suggestion:
+   ```
+   [#0] [HIGH] Clean up dormant skills (confidence: 0.85)
+     Target: ~/.pi/agent/CLAUDE.md
+     Status: pending
+     Summary: <first 2 lines of description>
+   ```
+
+---
+
+### APPLY Mode
+
+1. Read `pending.json`, validate index N exists and status is "pending"
+2. Get suggestion at index N
+3. **Backup**: Use `bash` tool to run:
+   ```bash
+   mkdir -p ~/.pi/agent/evolution-data/backups
+   cp "<targetPath>" "~/.pi/agent/evolution-data/backups/<timestamp>-<filename>"
+   ```
+   Use ISO timestamp with colons replaced by dashes for the backup filename.
+   If cp fails → ABORT, tell user "Backup failed, cannot apply. Reason: ..."
+4. **Modify file**: Use `edit` or `write` tool to apply the suggestion's
+   `instruction` to `targetPath`. Follow the instruction precisely.
+   If edit fails → clean up backup file (`rm "<backupPath>"`), ABORT,
+   tell user reason, keep status as "pending",
+   do NOT update pending.json or append to history.jsonl.
+5. **Git commit**: Use `bash` tool:
+   ```bash
+   cd "$(dirname '<targetPath>')" && git add '<filename>' && git commit -m "evolve: <title>"
+   ```
+   If commit fails → CONTINUE (commitSha will be empty)
+6. **Update pending.json**: Change suggestion status to "applied". Use `write`
+   tool to overwrite the entire file.
+7. **Append to history.jsonl**: Use `bash` tool with python to ensure
+   valid single-line JSON (avoids heredoc issues with multi-line instruction):
+   ```bash
+   python3 -c "import json; print(json.dumps({'timestamp':'<ISO>','action':'apply','suggestionId':'<id>','targetPath':'<path>','backupPath':'<backup>','instruction':'<instruction text>','title':'<title>','commitSha':'<sha>'}, ensure_ascii=False))" >> ~/.pi/agent/evolution-data/history.jsonl
+   ```
+   Escape single quotes in values before passing to python -c.
+8. Confirm to user: "Applied suggestion #N: <title>. Backup at <backupPath>."
+
+---
+
+### SKIP Mode
+
+1. Read `pending.json`, validate index N exists and status is "pending"
+2. Update suggestion status to "rejected"
+3. Write back `pending.json` using `write` tool
+4. Confirm: "Skipped suggestion #N: <title>."
+
+---
+
+### ROLLBACK Mode
+
+1. Read `history.jsonl` (last line = most recent action)
+2. Find the most recent "apply" action that hasn't been rolled back
+3. Check if `backupPath` file exists
+4. **If backup exists**: Use `bash` tool to restore:
+   ```bash
+   cp "<backupPath>" "<targetPath>"
+   ```
+   Verify cp succeeded (exit code 0). If cp fails → ABORT, tell user.
+   If cp succeeded → commit:
+   ```bash
+   cd "$(dirname '<targetPath>')" && git add '<filename>' && git commit -m "evolve: rollback <title>"
+   ```
+5. **If backup missing**: Tell user "Cannot auto-restore: backup file not found
+   at <backupPath>. You may need to manually check git history." STOP HERE.
+   Do NOT proceed to steps 6-8. Do NOT update pending.json or history.jsonl.
+6. **Update pending.json** (only if step 4 succeeded): Find the suggestion
+   matching the suggestionId and change its status back to "pending".
+   Use `write` tool to overwrite.
+7. **Append rollback to history.jsonl** (only if step 4 succeeded):
+   ```bash
+   python3 -c "import json; print(json.dumps({'timestamp':'<ISO>','action':'rollback','suggestionId':'<id>','targetPath':'<path>','backupPath':'<backup>','instruction':'','title':'<title>','commitSha':'<sha>'}, ensure_ascii=False))" >> ~/.pi/agent/evolution-data/history.jsonl
+   ```
+8. Confirm (only if step 4 succeeded): "Rolled back: <title>. File restored from backup."

package/skills/evolve-report/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: evolve-report
+description: "View evolution daily reports and usage statistics. Shows session data, tool usage, token consumption, and trend analysis. Trigger: /evolve-report, evolve-report, 查看报告, 进化报告, /evolve-stats, evolve-stats."
+---
+
+# Evolve-Report — Report & Statistics Viewer
+
+## Purpose
+
+Display daily analysis reports and usage statistics from collected data.
+
+## When Triggered
+
+User says "/evolve-report", "evolve-report", "查看报告", "进化报告",
+"/evolve-stats", "evolve-stats", or wants to view evolution data.
+
+## Data Paths
+
+- Daily reports: `~/.pi/agent/evolution-data/daily-reports/*.json`
+  (Only `.json` files are Python analyzer output. `.md` files are legacy from old evolution-engine, ignore them.)
+- Daily summaries: `~/.pi/agent/evolution-data/daily/*.json`
+  (Generated by usage-tracker extension.)
+- Metrics history: `~/.pi/agent/evolution-data/metrics-history.json`
+
+## Procedure
+
+### Parse Command
+
+- No args → show today's report
+- Date string (YYYY-MM-DD) → show that date's report
+- `--list` → list all available reports
+- `--stats` or "/evolve-stats" → show usage statistics overview
+
+### Show Report
+
+1. Use `bash` tool to check available reports:
+   ```bash
+   ls ~/.pi/agent/evolution-data/daily-reports/*.json 2>/dev/null
+   ```
+2. Read the requested report using `read` tool
+3. Present key information in a structured format:
+   - Session count and duration
+   - Tool call statistics (most used, error rates)
+   - Token consumption (input/output)
+   - Anomalies and signals
+   - Improvement suggestions (if any in the report)
+
+### List Reports
+
+```bash
+ls -1 ~/.pi/agent/evolution-data/daily-reports/*.json 2>/dev/null | xargs -I{} basename {} .json
+```
+Present as a numbered list of available dates.
+
+### Show Statistics
+
+1. Read multiple `daily/*.json` files for the requested period
+2. Aggregate and present:
+   - Total sessions, tool calls, tokens
+   - Per-tool usage breakdown
+   - Day-over-day trends
+   - Top skills triggered
+   - Error patterns
+
+Use tables and summaries for readability. Highlight significant changes.

package/src/index.ts

@@ -0,0 +1,34 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { existsSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const ANALYZER_PATH = join(
+  homedir(),
+  ".pi/agent/scripts/pi-session-analyzer/analyze.py"
+);
+// daily-reports/ 目录复用旧 extension 的目录路径。
+// 旧 extension 写入 .md 文件，新 evolve-daily 写入 .json 文件，天然不冲突。
+// 删除旧 extension 后残留的 .md 文件可忽略。
+const REPORTS_DIR = join(homedir(), ".pi/agent/evolution-data/daily-reports");
+
+export default function evolveDailyExtension(pi: ExtensionAPI) {
+  pi.on("session_start", async () => {
+    const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const reportPath = join(REPORTS_DIR, `${today}.json`);
+
+    if (existsSync(reportPath)) return;
+
+    try {
+      await pi.exec(
+        "python3",
+        [ANALYZER_PATH, "--since", "1d", "--format", "json", "--output", reportPath],
+        { timeout: 30_000 }
+      );
+    } catch (e) {
+      // Clean up partial output if analyzer failed mid-write
+      try { unlinkSync(reportPath); } catch { /* already gone */ }
+      console.error("[evolve-daily] analyzer failed:", e);
+    }
+  });
+}