principles-disciple 1.8.1 → 1.8.3

package/{dist/commands/thinking-os.js → src/commands/thinking-os.ts}

@@ -1,13 +1,17 @@
 import * as fs from 'fs';
+import * as path from 'path';
+import type { PluginCommandContext, PluginCommandResult } from '../openclaw-sdk.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
-function getWorkspaceDir(ctx) {
-    return ctx.config?.workspaceDir || process.cwd();
+
+function getWorkspaceDir(ctx: PluginCommandContext): string {
+    return (ctx.config?.workspaceDir as string) || process.cwd();
 }
-function getModels(wctx) {
+
+function getModels(wctx: WorkspaceContext): Record<string, string> {
     const modelsPath = wctx.resolve('THINKING_OS');
-    const models = {};
-    if (!fs.existsSync(modelsPath))
-        return models;
+    const models: Record<string, string> = {};
+    if (!fs.existsSync(modelsPath)) return models;
+
     try {
         const content = fs.readFileSync(modelsPath, 'utf8');
         const lines = content.split('\n');
@@ -17,51 +21,61 @@ function getModels(wctx) {
                 models[match[1]] = match[2].trim();
             }
         }
-    }
-    catch (e) {
+    } catch (e) {
         console.debug('[PD] Failed to read THINKING_OS.md:', e);
     }
     return models;
 }
-function formatUsageReport(wctx) {
+
+function formatUsageReport(wctx: WorkspaceContext): string {
     const logPath = wctx.resolve('THINKING_OS_USAGE');
+
     if (!fs.existsSync(logPath)) {
         return '📊 No usage data yet. The Thinking OS has not been active long enough to collect statistics.';
     }
+
     try {
-        const usage = JSON.parse(fs.readFileSync(logPath, 'utf8'));
+        const usage: Record<string, number> = JSON.parse(fs.readFileSync(logPath, 'utf8'));
         const totalTurns = usage['_total_turns'] || 1;
         const models = getModels(wctx);
+
         let report = `# 🧠 Thinking OS — Usage Report\n\n`;
         report += `Total turns tracked: **${totalTurns}**\n\n`;
         report += `| Model | Name | Hits | Rate |\n|---|---|---|---|\n`;
+
         for (const [id, name] of Object.entries(models)) {
             const hits = usage[id] || 0;
             const rate = totalTurns > 0 ? ((hits / totalTurns) * 100).toFixed(1) : '0.0';
             const status = hits === 0 ? '⚠️' : (parseFloat(rate) < 5 ? '🔸' : '✅');
             report += `| ${id} | ${name} | ${hits} | ${status} ${rate}% |\n`;
         }
+
         const dormant = Object.entries(models)
             .filter(([id]) => (usage[id] || 0) === 0)
             .map(([id, name]) => `- ${id}: ${name}`);
+
         if (dormant.length > 0) {
             report += `\n### ⚠️ Dormant Models (0 hits)\n${dormant.join('\n')}\n`;
             report += `\nConsider: Are these models not applicable to current tasks, or is the agent ignoring them?\n`;
         }
+
         return report;
-    }
-    catch (e) {
+    } catch (e) {
         return `❌ Failed to read usage data: ${String(e)}`;
     }
 }
-function handlePropose(wctx, proposal) {
+
+function handlePropose(wctx: WorkspaceContext, proposal: string): string {
     if (!proposal.trim()) {
         return '❌ Usage: `/thinking-os propose <description of your proposed mental model>`';
     }
+    
     if (!proposal.toLowerCase().includes('signal') && !proposal.includes('信号')) {
         return '❌ Invalid proposal: A mental model must include a "Signal detection / 信号检测" section explaining how to detect its usage via regex.';
     }
+
     const candidatesPath = wctx.resolve('THINKING_OS_CANDIDATES');
+    
     if (fs.existsSync(candidatesPath)) {
         try {
             const content = fs.readFileSync(candidatesPath, 'utf8');
@@ -69,60 +83,66 @@ function handlePropose(wctx, proposal) {
             if (content.includes(snippet)) {
                 return '❌ Duplicate proposal detected. A similar candidate already exists.';
             }
-        }
-        catch (e) {
+        } catch (e) {
             console.debug('[PD] Error reading candidates file:', e);
         }
     }
+    
     const timestamp = new Date().toISOString();
     const entry = `\n### Candidate (${timestamp})\n${proposal.trim()}\n- Status: PENDING\n- Validated in tasks: 0/3\n---\n`;
+
     try {
         fs.appendFileSync(candidatesPath, entry, 'utf8');
         return `✅ Mental model proposal recorded in \`${candidatesPath.replace(wctx.workspaceDir, '')}\`.\nIt needs validation in ≥3 different task types and human approval before promotion.`;
-    }
-    catch (e) {
+    } catch (e) {
         return `❌ Failed to write proposal: ${String(e)}`;
     }
 }
-function formatAuditReport(wctx) {
+
+function formatAuditReport(wctx: WorkspaceContext): string {
     const logPath = wctx.resolve('THINKING_OS_USAGE');
     const thinkingOsPath = wctx.resolve('THINKING_OS');
+
     let report = `# 🔍 Thinking OS — Audit Report\n\n`;
+
     if (!fs.existsSync(thinkingOsPath)) {
         report += `⚠️ **THINKING_OS.md not found.** The cognitive layer is not active.\n`;
         return report;
     }
+
     const models = getModels(wctx);
     const modelCount = Object.keys(models).length;
     report += `**Active models**: ${modelCount}\n\n`;
+
     if (!fs.existsSync(logPath)) {
         report += `📊 No usage data collected yet. Run some tasks first.\n`;
         return report;
     }
+
     try {
-        const usage = JSON.parse(fs.readFileSync(logPath, 'utf8'));
+        const usage: Record<string, number> = JSON.parse(fs.readFileSync(logPath, 'utf8'));
         const totalTurns = usage['_total_turns'] || 1;
-        const overused = [];
-        const underused = [];
-        const healthy = [];
+
+        const overused: string[] = [];
+        const underused: string[] = [];
+        const healthy: string[] = [];
+
         for (const [id, name] of Object.entries(models)) {
             const hits = usage[id] || 0;
             const rate = (hits / totalTurns) * 100;
-            if (rate > 50)
-                overused.push(`- ${id} (${name}): ${rate.toFixed(1)}% — possibly too broad a pattern?`);
-            else if (hits === 0 && totalTurns > 10)
-                underused.push(`- ${id} (${name}): 0 hits in ${totalTurns} turns — candidate for archival?`);
-            else
-                healthy.push(`- ${id} (${name}): ${rate.toFixed(1)}%`);
+
+            if (rate > 50) overused.push(`- ${id} (${name}): ${rate.toFixed(1)}% — possibly too broad a pattern?`);
+            else if (hits === 0 && totalTurns > 10) underused.push(`- ${id} (${name}): 0 hits in ${totalTurns} turns — candidate for archival?`);
+            else healthy.push(`- ${id} (${name}): ${rate.toFixed(1)}%`);
         }
-        if (healthy.length > 0)
-            report += `### ✅ Healthy\n${healthy.join('\n')}\n\n`;
-        if (overused.length > 0)
-            report += `### 🔸 Possibly Over-triggered\n${overused.join('\n')}\n\n`;
+
+        if (healthy.length > 0) report += `### ✅ Healthy\n${healthy.join('\n')}\n\n`;
+        if (overused.length > 0) report += `### 🔸 Possibly Over-triggered\n${overused.join('\n')}\n\n`;
         if (underused.length > 0) {
             report += `### ⚠️ Candidate for Archival\n${underused.join('\n')}\n`;
             report += `> 💡 Suggestion: Review these models. If they are obsolete, move them to the archive.\n\n`;
         }
+
         const candidatesPath = wctx.resolve('THINKING_OS_CANDIDATES');
         if (fs.existsSync(candidatesPath)) {
             const candidates = fs.readFileSync(candidatesPath, 'utf8');
@@ -131,18 +151,20 @@ function formatAuditReport(wctx) {
                 report += `### 📝 Pending Candidates: ${pendingCount}\nReview candidates to fill gaps.\n`;
             }
         }
+
         return report;
-    }
-    catch (e) {
+    } catch (e) {
         return `❌ Failed to generate audit report: ${String(e)}`;
     }
 }
-export function handleThinkingOs(ctx) {
+
+export function handleThinkingOs(ctx: PluginCommandContext): PluginCommandResult {
     const workspaceDir = getWorkspaceDir(ctx);
     const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });
     const args = (ctx.args || '').trim();
     const subCommand = args.split(/\s+/)[0]?.toLowerCase();
     const rest = args.slice(subCommand?.length || 0).trim();
+
     switch (subCommand) {
         case 'status':
             return { text: formatUsageReport(wctx) };
@@ -152,7 +174,8 @@ export function handleThinkingOs(ctx) {
             return { text: formatAuditReport(wctx) };
         default:
             return {
-                text: `🧠 **Thinking OS — Governance Console**\n\n` +
+                text:
+                    `🧠 **Thinking OS — Governance Console**\n\n` +
                     `Usage:\n` +
                     `- \`/thinking-os status\` — View mental model usage statistics\n` +
                     `- \`/thinking-os propose <model description>\` — Propose a new mental model\n` +

package/src/commands/workflow-debug.ts

@@ -0,0 +1,128 @@
+import { WorkflowStore } from '../service/subagent-workflow/workflow-store.js';
+import type { PluginCommandContext } from '../openclaw-sdk.js';
+
+function formatTimestamp(ts: number | null | undefined): string {
+    if (!ts) return '--';
+    return new Date(ts).toISOString();
+}
+
+function formatState(state: string): string {
+    const stateColors: Record<string, string> = {
+        'active': '●',
+        'wait_result': '◐',
+        'finalizing': '◑',
+        'completed': '✓',
+        'terminal_error': '✗',
+        'cleanup_pending': '⚠',
+        'expired': '⊘',
+    };
+    const icon = stateColors[state] || '?';
+    return `${icon} ${state}`;
+}
+
+function buildOutput(
+    workflowId: string,
+    summary: ReturnType<InstanceType<typeof WorkflowStore>['getWorkflow']>,
+    events: ReturnType<InstanceType<typeof WorkflowStore>['getEvents']>,
+    workspaceDir: string
+): string {
+    if (!summary) {
+        return [
+            `Workflow Debug: ${workflowId}`,
+            '============================',
+            '',
+            '❌ Workflow not found',
+            '',
+            `Workspace: ${workspaceDir}`,
+        ].join('\n');
+    }
+
+    const metadata = JSON.parse(summary.metadata_json || '{}');
+    const recentEvents = events.slice(-10);
+
+    const lines: string[] = [
+        `Workflow Debug: ${workflowId}`,
+        '============================',
+        '',
+        'Overview',
+        `- Type: ${summary.workflow_type}`,
+        `- Transport: ${summary.transport}`,
+        `- State: ${formatState(summary.state)}`,
+        `- Cleanup: ${summary.cleanup_state}`,
+        `- Created: ${formatTimestamp(summary.created_at)}`,
+        `- Last Observed: ${formatTimestamp(summary.last_observed_at)}`,
+        '',
+        'Sessions',
+        `- Parent: ${summary.parent_session_id}`,
+        `- Child: ${summary.child_session_key}`,
+        `- Run ID: ${summary.run_id ?? '--'}`,
+        '',
+        'Metadata',
+        `- Workspace: ${metadata.workspaceDir ?? '--'}`,
+        `- Task Input: ${typeof metadata.taskInput === 'string' ? metadata.taskInput.substring(0, 100) + (metadata.taskInput.length > 100 ? '...' : '') : '--'}`,
+        '',
+        `Recent Events (${recentEvents.length})`,
+    ];
+
+    if (recentEvents.length === 0) {
+        lines.push('- (no events)');
+    } else {
+        for (const event of recentEvents) {
+            const time = formatTimestamp(event.created_at);
+            const transition = event.from_state ? `${event.from_state} → ${event.to_state}` : `→ ${event.to_state}`;
+            lines.push(`- [${time}] ${event.event_type}: ${transition} (${event.reason})`);
+        }
+    }
+
+    lines.push('');
+    lines.push(`Workspace: ${workspaceDir}`);
+
+    return lines.join('\n');
+}
+
+export function handleWorkflowDebugCommand(
+    ctx: PluginCommandContext & { args?: string }
+): { text: string } {
+    const workspaceDir = (ctx.config?.workspaceDir as string) || process.cwd();
+    
+    // Parse workflow ID from args
+    const args = (ctx as { args?: string }).args?.trim() || '';
+    const workflowId = args.split(/\s+/)[0];
+
+    if (!workflowId) {
+        return {
+            text: [
+                'Workflow Debug',
+                '============================',
+                '',
+                'Usage: /pd-workflow-debug <workflowId>',
+                '',
+                'Description:',
+                '- Display debug summary for a helper workflow',
+                '- Shows state, cleanup status, and recent events',
+                '',
+                'To find workflow IDs, check .state/subagent_workflows.db',
+            ].join('\n'),
+        };
+    }
+
+    try {
+        const store = new WorkflowStore({ workspaceDir });
+        const workflow = store.getWorkflow(workflowId);
+        const events = store.getEvents(workflowId);
+        store.dispose();
+
+        return { text: buildOutput(workflowId, workflow, events, workspaceDir) };
+    } catch (error) {
+        return {
+            text: [
+                `Workflow Debug: ${workflowId}`,
+                '============================',
+                '',
+                `❌ Error: ${String(error)}`,
+                '',
+                `Workspace: ${workspaceDir}`,
+            ].join('\n'),
+        };
+    }
+}

package/{dist/config/defaults/runtime.js → src/config/defaults/runtime.ts}

@@ -1,42 +1,49 @@
 /**
  * Centralized Runtime Defaults
- *
+ * 
  * All runtime-related constants that were previously scattered across modules.
  * Centralizing these makes it easier to tune behavior and understand limits.
  */
+
 /**
  * Trajectory gate block retry settings
  * Used when trajectory recording fails and needs to retry
  */
 export const TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS = 250;
 export const TRAJECTORY_GATE_BLOCK_MAX_RETRIES = 3;
+
 /**
  * Thinking checkpoint defaults (P-10)
  */
 export const THINKING_CHECKPOINT_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
 export const THINKING_CHECKPOINT_DEFAULT_HIGH_RISK_TOOLS = [
-    'run_shell_command',
-    'delete_file',
-    'move_file',
-];
+  'run_shell_command',
+  'delete_file', 
+  'move_file',
+] as const;
+
 /**
  * Large change threshold for GFI gate adjustments
  */
 export const GFI_LARGE_CHANGE_LINES = 50;
+
 /**
  * Agent spawn GFI threshold (critically high = no spawn)
  */
 export const AGENT_SPAWN_GFI_THRESHOLD = 90;
+
 /**
  * Evolution worker polling intervals
  */
 export const EVOLUTION_WORKER_POLL_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes
 export const EVOLUTION_QUEUE_BATCH_SIZE = 10;
+
 /**
  * Session tracker settings
  */
 export const SESSION_TOKEN_WARNING_THRESHOLD = 8000;
 export const SESSION_MAX_IDLE_MS = 30 * 60 * 1000; // 30 minutes
+
 /**
  * Event log buffer settings
  */

package/src/config/errors.ts

@@ -0,0 +1,163 @@
+/**
+ * Domain-Specific Errors for Principles Disciple
+ * 
+ * These errors provide semantic meaning to failure modes,
+ * making it easier to distinguish between:
+ * - Lock contention (resource busy)
+ * - Parse/validation failures
+ * - Derived state mismatches
+ * - Configuration issues
+ */
+
+/**
+ * Base class for all Principles Disciple errors
+ */
+export class PdError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    options?: { cause?: unknown }
+  ) {
+    super(message, options);
+    this.name = 'PdError';
+  }
+}
+
+/**
+ * Thrown when a resource lock cannot be acquired
+ * (e.g., queue, trajectory, evolution file)
+ */
+export class LockUnavailableError extends PdError {
+  constructor(
+    resource: string,
+    scope: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `[PD:Lock] ${scope}: queue lock unavailable for ${resource}`,
+      'LOCK_UNAVAILABLE',
+      options
+    );
+    this.name = 'LockUnavailableError';
+  }
+}
+
+/**
+ * Thrown when a path key cannot be resolved
+ */
+export class PathResolutionError extends PdError {
+  constructor(
+    key: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `[PD:Path] Unknown path key: ${key}`,
+      'PATH_RESOLUTION_ERROR',
+      options
+    );
+    this.name = 'PathResolutionError';
+  }
+}
+
+/**
+ * Thrown when a workspace cannot be found
+ */
+export class WorkspaceNotFoundError extends PdError {
+  constructor(
+    workspace: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `[PD:Workspace] Workspace not found: ${workspace}`,
+      'WORKSPACE_NOT_FOUND',
+      options
+    );
+    this.name = 'WorkspaceNotFoundError';
+  }
+}
+
+/**
+ * Thrown when a required sample cannot be found
+ */
+export class SampleNotFoundError extends PdError {
+  constructor(
+    sampleId: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `[PD:Sample] Correction sample not found: ${sampleId}`,
+      'SAMPLE_NOT_FOUND',
+      options
+    );
+    this.name = 'SampleNotFoundError';
+  }
+}
+
+/**
+ * Thrown when configuration is invalid or missing required fields
+ */
+export class ConfigurationError extends PdError {
+  constructor(
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `[PD:Config] ${message}`,
+      'CONFIGURATION_ERROR',
+      options
+    );
+    this.name = 'ConfigurationError';
+  }
+}
+
+/**
+ * Thrown when prompt/logger dependencies are unavailable
+ */
+export class DependencyError extends PdError {
+  constructor(
+    component: string,
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `[PD:${component}] ${message}`,
+      'DEPENDENCY_ERROR',
+      options
+    );
+    this.name = 'DependencyError';
+  }
+}
+
+/**
+ * Thrown when evolution worker encounters a processing error
+ */
+export class EvolutionProcessingError extends PdError {
+  constructor(
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `[PD:Evolution] ${message}`,
+      'EVOLUTION_PROCESSING_ERROR',
+      options
+    );
+    this.name = 'EvolutionProcessingError';
+  }
+}
+
+/**
+ * Thrown when trajectory operations fail
+ */
+export class TrajectoryError extends PdError {
+  constructor(
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(
+      `[PD:Trajectory] ${message}`,
+      'TRAJECTORY_ERROR',
+      options
+    );
+    this.name = 'TrajectoryError';
+  }
+}

package/{dist/config/index.d.ts → src/config/index.ts}

@@ -1,7 +1,8 @@
 /**
  * Configuration module for Principles Disciple
- *
+ * 
  * Centralizes all configuration defaults, types, and domain errors.
  */
+
 export * from './defaults/runtime.js';
 export * from './errors.js';

package/src/constants/diagnostician.ts

@@ -0,0 +1,66 @@
+/**
+ * Diagnostician 协议常量
+ *
+ * 用于 evolution-worker.ts（后台心跳）和 prompt.ts（实时路径）
+ * 与 templates/langs/zh/skills/pd-diagnostician/SKILL.md 保持一致
+ */
+
+/**
+ * 诊断协议摘要（用于 HEARTBEAT.md 注入）
+ *
+ * 完整版见: templates/langs/zh/skills/pd-diagnostician/SKILL.md
+ */
+export const DIAGNOSTICIAN_PROTOCOL_SUMMARY = `## Diagnostic Protocol (5 Whys)
+
+**Phase 1 - Evidence Gathering**:
+- Read .state/.pain_flag for full pain context
+- Read .state/logs/events.jsonl recent entries
+- Search codebase for error patterns from Reason field
+- Record all evidence sources (file:line)
+
+**Phase 2 - Causal Chain (5 Whys)**:
+- Why 1: Surface symptom (what you can see)
+- Why 2: Direct cause (what triggered it)
+- Why 3: Process gap (what should have caught it)
+- Why 4: Design flaw (why the gap exists)
+- Why 5: Root cause (systemic issue to fix)
+- Each Why MUST have evidence. Stop at actionable root cause.
+
+**Phase 3 - Root Cause Classification**:
+Classify into one of:
+- **People**: Human error, missing knowledge, communication gap
+- **Design**: Architecture flaw, missing validation, poor abstraction
+- **Assumption**: Invalid assumption, outdated context, edge case
+- **Tooling**: Tool limitation, environment issue, dependency problem
+- For Design: analyze why existing hooks/rules didn't catch this
+
+**Phase 4 - Principle Extraction**:
+Extract a HIGHLY ABSTRACTED principle (not an operational rule):
+- **trigger_pattern**: regex/keywords for when this occurs
+- **action**: what to do differently
+- **abstracted_principle**: ONE sentence, max 40 chars, cross-scenario applicable
+  - ❌ Bad: "写入前检查目录是否存在" (too specific)
+  - ✅ Good: "任何写入操作必须确保目标环境的完整性" (abstract, reusable)
+
+**Output Format** (single JSON object):
+\`\`\`json
+{
+  "diagnosis_report": {
+    "task_id": "pain-xxx",
+    "summary": "One-line root cause",
+    "causal_chain": [
+      { "why": 1, "answer": "...", "evidence": "file:line" }
+    ],
+    "root_cause": {
+      "category": "Design|People|Assumption|Tooling",
+      "description": "..."
+    },
+    "principle": {
+      "trigger_pattern": "...",
+      "action": "...",
+      "abstracted_principle": "高度抽象的一句话原则"
+    }
+  }
+}
+\`\`\`
+`;