@tplog/pi-zendy 0.3.6 → 0.3.8

package/README.md

@@ -12,6 +12,7 @@ zendy is a single pi extension that provides:
 
 - **LLM Tools** — Direct API access to Zendesk, Helm Watchdog, and Knowledge Graph. No external CLI dependencies.
 - **Slash Commands** — `/zendy-config` to set up credentials, `/zendy-status` to check connectivity.
+- **Skill** — a `zendy` skill (also `/skill:zendy`) that teaches the agent the ticket-analysis workflow, so "analyze ticket #1959" reliably uses the right tools in the right order.
 - **Session Safety** — Automatic workspace isolation and cleanup for source code analysis.
 
 Typical workflow:
@@ -69,6 +70,7 @@ The agent can call these tools directly:
 |------|-------------|
 | `zendy_ticket_get` | Fetch ticket metadata, comments, and user info |
 | `zendy_ticket_search` | Search live Zendesk tickets |
+| `zendy_whoami` | Check the currently authenticated Zendesk identity |
 | `zendy_helm_get` | Query Helm chart values, images, validation by version |
 | `zendy_kg_search` | Semantic search over historical tickets |
 | `zendy_source_status` | Check source analysis workspace |

package/dist/clients/zendesk-kg.js

@@ -1,26 +1,11 @@
 // Direct Zendesk Knowledge Graph API client. No zendesk-kg CLI dependency.
-import { getConfig } from "../config/store.js";
-import { migrateLegacyConfig, getLegacyKgEnv } from "../config/migrate.js";
+import { resolveKgConfig } from "../config/resolve.js";
 import { DEFAULT_KG_API_URL } from "../config/schema.js";
 // ── Resolve config ─────────────────────────────────────────────────────
 function resolveConfig() {
-    // Try zendy config first (env or ~/.zendy/config.json)
-    const { zendeskKg } = getConfig();
-    if (zendeskKg?.apiKey)
-        return zendeskKg;
-    // Try legacy migration
-    migrateLegacyConfig();
-    const cfg2 = getConfig();
-    if (cfg2.zendeskKg?.apiKey)
-        return cfg2.zendeskKg;
-    // Try legacy .env directly
-    const legacy = getLegacyKgEnv();
-    if (legacy?.["RETRIEVER_API_KEY"]) {
-        return {
-            apiUrl: legacy["RETRIEVER_API_URL"] || undefined,
-            apiKey: legacy["RETRIEVER_API_KEY"],
-        };
-    }
+    const cfg = resolveKgConfig();
+    if (cfg)
+        return cfg;
     throw new Error("Zendesk KG not configured. Use /zendy-config to set up credentials.\n" +
         "Or set env: ZENDY_KG_API_KEY");
 }

package/dist/clients/zendesk.js

@@ -1,24 +1,10 @@
 // Direct Zendesk REST API client. No zcli dependency.
-import { getConfig } from "../config/store.js";
-import { migrateLegacyConfig, getLegacyZendeskConfig } from "../config/migrate.js";
+import { resolveZendeskConfig } from "../config/resolve.js";
 // ── Resolve config ─────────────────────────────────────────────────────
 function resolveConfig() {
-    // Try zendy config first (env or ~/.zendy/config.json)
-    const { zendesk } = getConfig();
-    if (zendesk?.subdomain && zendesk?.email && zendesk?.apiToken) {
-        return zendesk;
-    }
-    // Try legacy migration
-    migrateLegacyConfig();
-    const cfg2 = getConfig();
-    if (cfg2.zendesk?.subdomain && cfg2.zendesk?.email && cfg2.zendesk?.apiToken) {
-        return cfg2.zendesk;
-    }
-    // Try legacy zcli config directly
-    const legacy = getLegacyZendeskConfig();
-    if (legacy?.subdomain && legacy?.email && legacy?.api_token) {
-        return { subdomain: legacy.subdomain, email: legacy.email, apiToken: legacy.api_token };
-    }
+    const cfg = resolveZendeskConfig();
+    if (cfg)
+        return cfg;
     throw new Error("Zendesk not configured. Use /zendy-config to set up credentials.\n" +
         "Or set env: ZENDY_ZENDESK_SUBDOMAIN, ZENDY_ZENDESK_EMAIL, ZENDY_ZENDESK_API_TOKEN");
 }

package/dist/config/resolve.d.ts

@@ -0,0 +1,3 @@
+import type { ZendeskConfig, ZendeskKgConfig } from "./schema.js";
+export declare function resolveZendeskConfig(): ZendeskConfig | undefined;
+export declare function resolveKgConfig(): ZendeskKgConfig | undefined;

package/dist/config/resolve.js

@@ -0,0 +1,40 @@
+// Single source of truth for resolving effective credentials.
+//
+// Precedence (same for both Zendesk and KG):
+//   1. zendy config — env vars override ~/.zendy/config.json
+//   2. legacy migration — import legacy zcli / zendesk-kg files into zendy config
+//   3. direct legacy files — read the legacy config without migrating
+//
+// Returns undefined when nothing resolves; callers decide whether that is fatal.
+// Lives above store.ts and migrate.ts to compose them without a dependency cycle
+// (migrate.ts already depends on store.ts).
+import { getConfig } from "./store.js";
+import { migrateLegacyConfig, getLegacyZendeskConfig, getLegacyKgEnv } from "./migrate.js";
+export function resolveZendeskConfig() {
+    const cfg = getConfig().zendesk;
+    if (cfg?.subdomain && cfg?.email && cfg?.apiToken)
+        return cfg;
+    migrateLegacyConfig();
+    const migrated = getConfig().zendesk;
+    if (migrated?.subdomain && migrated?.email && migrated?.apiToken)
+        return migrated;
+    const legacy = getLegacyZendeskConfig();
+    if (legacy?.subdomain && legacy?.email && legacy?.api_token) {
+        return { subdomain: legacy.subdomain, email: legacy.email, apiToken: legacy.api_token };
+    }
+    return undefined;
+}
+export function resolveKgConfig() {
+    const cfg = getConfig().zendeskKg;
+    if (cfg?.apiKey)
+        return cfg;
+    migrateLegacyConfig();
+    const migrated = getConfig().zendeskKg;
+    if (migrated?.apiKey)
+        return migrated;
+    const legacy = getLegacyKgEnv();
+    if (legacy?.["RETRIEVER_API_KEY"]) {
+        return { apiUrl: legacy["RETRIEVER_API_URL"] || undefined, apiKey: legacy["RETRIEVER_API_KEY"] };
+    }
+    return undefined;
+}

package/dist/config/store.d.ts

@@ -1,7 +1,5 @@
-import type { ZendyConfig, ZendeskConfig, ZendeskKgConfig } from "./schema.js";
+import type { ZendyConfig } from "./schema.js";
 export declare function getConfig(): ZendyConfig;
-export declare function getZendeskConfig(): ZendeskConfig | undefined;
-export declare function getZendeskKgConfig(): ZendeskKgConfig | undefined;
 export declare function writeConfig(config: ZendyConfig): void;
 export declare function configPath(): string;
 export declare function configExists(): boolean;

package/dist/config/store.js

@@ -54,18 +54,6 @@ export function getConfig() {
         },
     };
 }
-export function getZendeskConfig() {
-    const c = getConfig().zendesk;
-    if (c?.subdomain && c?.email && c?.apiToken)
-        return c;
-    return undefined;
-}
-export function getZendeskKgConfig() {
-    const c = getConfig().zendeskKg;
-    if (c?.apiKey)
-        return c;
-    return undefined;
-}
 export function writeConfig(config) {
     mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
     writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", {

package/dist/index.js

@@ -1,11 +1,8 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { homedir } from "node:os";
 import { execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
-import { createHash } from "node:crypto";
 import { runPreflight, printPreflightReport, promptCoreMissing } from "./preflight.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -14,34 +11,15 @@ const pkg = require("../package.json");
 const VERSION = pkg.version;
 // Resolve package root (one level up from dist/)
 const PKG_ROOT = join(__dirname, "..");
-// Embedded file paths relative to package root
+// The extension is loaded directly from the package's own extensions/ dir,
+// where zendy.ts and its sibling imports (tools.ts, commands.ts) live together.
+// This is the same file pi loads via the `pi.extensions` manifest field, so the
+// `zendy` launcher and `pi install` behave identically — no separate extraction step.
 const EXT_ZENDY = join(PKG_ROOT, "extensions", "zendy.ts");
-function cacheDir() {
-    return join(homedir(), ".zendy", VERSION);
-}
-// All source files that get extracted to cache
-const SOURCE_FILES = [
-    EXT_ZENDY,
-];
-function contentHash() {
-    const hash = createHash("sha256");
-    for (const f of SOURCE_FILES) {
-        hash.update(readFileSync(f, "utf-8"));
-    }
-    return hash.digest("hex").slice(0, 16);
-}
-function ensureExtracted(base) {
-    const marker = join(base, ".extracted");
-    const currentHash = contentHash();
-    // Re-extract if marker is missing or hash has changed
-    if (existsSync(marker) && readFileSync(marker, "utf-8").trim() === currentHash) {
-        return;
-    }
-    const extDir = join(base, "extensions");
-    mkdirSync(extDir, { recursive: true });
-    writeFileSync(join(extDir, "zendy.ts"), readFileSync(EXT_ZENDY, "utf-8"));
-    writeFileSync(marker, currentHash);
-}
+// Skill describing zendy and the ticket-analysis workflow. pi discovers it via
+// the pi.skills manifest field when installed as a package; the launcher passes
+// it explicitly so both load paths expose the same skill.
+const SKILL_ZENDY = join(PKG_ROOT, "skills", "zendy");
 function findPi() {
     try {
         return execFileSync("which", ["pi"], { encoding: "utf-8" }).trim();
@@ -105,13 +83,12 @@ async function main() {
     }
     // Remove --skip-preflight before passing to pi
     const filteredArgs = userArgs.filter((a) => a !== "--skip-preflight");
-    const base = cacheDir();
-    ensureExtracted(base);
     const pi = findPi();
-    const extensionsDir = join(base, "extensions");
     const args = [
         "--extension",
-        join(extensionsDir, "zendy.ts"),
+        EXT_ZENDY,
+        "--skill",
+        SKILL_ZENDY,
     ];
     // Pass through all user arguments
     args.push(...filteredArgs);

package/dist/preflight.js

@@ -3,8 +3,8 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
-import { getConfig } from "./config/store.js";
-import { migrateLegacyConfig, getLegacyZendeskConfig, getLegacyKgEnv } from "./config/migrate.js";
+import { resolveZendeskConfig, resolveKgConfig } from "./config/resolve.js";
+import { DEFAULT_KG_API_URL } from "./config/schema.js";
 // ── Helpers ────────────────────────────────────────────────────────────
 function exec(cmd, args, timeoutMs = 5000) {
     return new Promise((resolve) => {
@@ -60,25 +60,6 @@ async function checkPi() {
     }
     return { ...base, status: "ok", hint: "" };
 }
-function resolveZendeskConfig() {
-    // 1. zendy config (env or ~/.zendy/config.json)
-    const cfg = getConfig();
-    if (cfg.zendesk?.subdomain && cfg.zendesk?.email && cfg.zendesk?.apiToken) {
-        return { subdomain: cfg.zendesk.subdomain, email: cfg.zendesk.email, apiToken: cfg.zendesk.apiToken };
-    }
-    // 2. Try legacy migration
-    migrateLegacyConfig();
-    const cfg2 = getConfig();
-    if (cfg2.zendesk?.subdomain && cfg2.zendesk?.email && cfg2.zendesk?.apiToken) {
-        return { subdomain: cfg2.zendesk.subdomain, email: cfg2.zendesk.email, apiToken: cfg2.zendesk.apiToken };
-    }
-    // 3. Legacy zcli config
-    const legacy = getLegacyZendeskConfig();
-    if (legacy?.subdomain && legacy?.email && legacy?.api_token) {
-        return { subdomain: legacy.subdomain, email: legacy.email, apiToken: legacy.api_token };
-    }
-    return null;
-}
 async function checkZendesk() {
     const base = {
         name: "zendesk",
@@ -121,24 +102,6 @@ async function checkZendesk() {
         };
     }
 }
-function resolveKgConfig() {
-    // 1. zendy config
-    const cfg = getConfig();
-    if (cfg.zendeskKg?.apiKey)
-        return { apiUrl: cfg.zendeskKg.apiUrl, apiKey: cfg.zendeskKg.apiKey };
-    // 2. Try legacy migration
-    migrateLegacyConfig();
-    const cfg2 = getConfig();
-    if (cfg2.zendeskKg?.apiKey)
-        return { apiUrl: cfg2.zendeskKg.apiUrl, apiKey: cfg2.zendeskKg.apiKey };
-    // 3. Legacy .env
-    const legacy = getLegacyKgEnv();
-    if (legacy?.["RETRIEVER_API_KEY"]) {
-        return { apiUrl: legacy["RETRIEVER_API_URL"] || undefined, apiKey: legacy["RETRIEVER_API_KEY"] };
-    }
-    return null;
-}
-const DEFAULT_KG_API_URL = "https://zendesk-ticket-retriever.vercel.app";
 async function checkZendeskKgApi() {
     const base = {
         name: "zendesk-kg",

package/dist/source-cleanup.js

@@ -6,9 +6,9 @@
 //
 // Used by:
 //   - `src/cleanup-src.ts` — the `zendy cleanup-src` CLI subcommand.
-//   - `extensions/source-cleanup.ts` — the pi extension. The extension file
-//     inlines the tiny helpers it needs so it can be loaded as a self-contained
-//     TS file by pi at runtime.
+//   - `extensions/zendy.ts` — the pi extension inlines the tiny session-dir
+//     helpers it needs so it can be loaded as a self-contained TS file by pi
+//     at runtime.
 import { readdir, stat, rm } from "node:fs/promises";
 import { join } from "node:path";
 async function dirSize(path) {

package/extensions/commands.ts

@@ -5,6 +5,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getConfig, writeConfig, configPath, configExists } from "../dist/config/store.js";
 import { migrateLegacyConfig } from "../dist/config/migrate.js";
 import type { ZendyConfig } from "../dist/config/schema.js";
+import { DEFAULT_KG_API_URL } from "../dist/config/schema.js";
 import * as zendesk from "../dist/clients/zendesk.js";
 import * as kg from "../dist/clients/zendesk-kg.js";
 
@@ -44,7 +45,7 @@ async function configCommand(_args: string, ctx: {
   } else if (action === "Knowledge Graph credentials") {
     const apiUrl = await ctx.ui.input(
       "Knowledge Graph API URL (leave empty for default)",
-      config.zendeskKg?.apiUrl ?? "https://zendesk-ticket-retriever.vercel.app",
+      config.zendeskKg?.apiUrl ?? DEFAULT_KG_API_URL,
     );
     const apiKey = await ctx.ui.input("Knowledge Graph API key", "");
     config.zendeskKg = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tplog/pi-zendy",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Pi package for Dify Enterprise support ticket analysis",
   "repository": {
     "type": "git",
@@ -19,12 +19,16 @@
   "pi": {
     "extensions": [
       "./extensions/zendy.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "files": [
     "dist",
     "extensions",
-    "prompts"
+    "prompts",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"

package/skills/zendy/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: zendy
+description: >
+  Dify Enterprise support ticket analysis using the zendy tools. Use whenever the
+  user mentions a Zendesk ticket number or asks to analyze, investigate, or reply to
+  a support ticket (e.g. "analyze ticket #1959", "分析工单", "工单分析", "チケットを調査"),
+  asks about a customer's Dify Helm chart values or version defaults, wants to find
+  similar historical tickets, or needs a customer reply drafted. Covers the full
+  workflow: fetch ticket → identify Dify version → check Helm values → search
+  similar tickets → draft reply in the ticket's language.
+---
+
+# zendy — Dify Enterprise Support Ticket Analysis
+
+zendy is a support-engineering harness for Dify Enterprise. It registers tools for
+Zendesk, the Dify Helm Watchdog, and a historical-ticket Knowledge Graph, so a
+support engineer can analyze a ticket end-to-end without leaving the terminal.
+
+## Tools
+
+| Tool | Use for |
+|------|---------|
+| `zendy_ticket_get` | Fetch one Zendesk ticket with comments, requester, assignee |
+| `zendy_ticket_search` | Search live Zendesk tickets (Zendesk search syntax) |
+| `zendy_whoami` | Verify which Zendesk account is authenticated |
+| `zendy_helm_get` | Dify Helm chart data by exact version: values.yaml, images, validation, latest |
+| `zendy_kg_search` | Semantic search over historical tickets; returns ticketIds |
+| `zendy_source_status` | Check the source-analysis workspace path and authorization rules |
+
+Use these tools for all data access. Do not use zcli, curl, or any external Zendesk
+CLI. If credentials are missing, tell the user to run `/zendy-config`; check
+connectivity with `/zendy-status`.
+
+## Ticket analysis workflow
+
+1. User gives a ticket number → `zendy_ticket_get` to pull ticket + comments.
+2. Identify the customer's exact Dify version from ticket fields or the thread.
+3. Pull the matching chart data with `zendy_helm_get` — always pass the exact
+   version. Defaults change between releases; never assume a config value from a
+   different version.
+4. Optionally `zendy_kg_search` for similar past tickets. Always cite the
+   `ticketId` values from results so the engineer can read the source tickets.
+   Empty results do not prove no similar issue exists.
+5. Synthesize findings and draft a reply.
+
+## Behavior rules
+
+- **Never guess.** Base conclusions on actual data — ticket fields, values.yaml,
+  knowledge-graph results. State clearly what is fact vs. inference.
+- **Don't recommend unverified solutions.** If something was not confirmed in
+  config or docs, say so explicitly.
+- **Reply drafts match the ticket language.** Detect the thread language
+  (Japanese, Chinese, or English) and draft in that language with appropriate
+  business tone.
+- **Source code analysis requires explicit user permission.** If config-level
+  analysis cannot settle the question, ask the user whether to check the source
+  (e.g. "需要我去源码确认吗？") — never clone without permission. Use
+  `zendy_source_status` to find the workspace.
+- **Inspect before filtering.** On the first call to an unfamiliar response shape,
+  look at the structure before writing filter expressions; never assume field names.