principles-disciple 1.8.0 → 1.8.2

package/{dist/utils/plugin-logger.js → src/utils/plugin-logger.ts}

@@ -1,10 +1,29 @@
 import * as fs from 'fs';
 import * as path from 'path';
+
+export interface PluginLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+
+export interface PluginLoggerConfig {
+    /** Directory to store log files (typically stateDir) */
+    logDir: string;
+    /** Plugin identifier for log file naming */
+    pluginId: string;
+    /** Console logger from OpenClaw API (for dual output) */
+    consoleLogger?: PluginLogger;
+    /** Whether to also output to console */
+    echoToConsole?: boolean;
+}
+
 /**
  * Creates a plugin-specific logger that writes to its own log file.
- *
+ * 
  * Log file location: {logDir}/logs/{pluginId}.log
- *
+ * 
  * Example:
  * ```
  * const logger = createPluginLogger({
@@ -13,28 +32,32 @@ import * as path from 'path';
  *   consoleLogger: api.logger,
  *   echoToConsole: true
  * });
- *
+ * 
  * logger.info('Evolution task completed', { taskId: 'abc123' });
  * ```
  */
-export function createPluginLogger(config) {
+export function createPluginLogger(config: PluginLoggerConfig): PluginLogger {
     const { logDir, pluginId, consoleLogger, echoToConsole = true } = config;
+    
     // Ensure logs directory exists
     const logsDir = path.join(logDir, 'logs');
     if (!fs.existsSync(logsDir)) {
         fs.mkdirSync(logsDir, { recursive: true });
     }
+    
     const logFile = path.join(logsDir, `${pluginId}.log`);
-    const writeLog = (level, message, meta) => {
+    
+    const writeLog = (level: string, message: string, meta?: Record<string, unknown>) => {
         const timestamp = new Date().toISOString();
         const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
         const logLine = `${timestamp} [${level.toUpperCase()}] ${message}${metaStr}\n`;
+        
         try {
             fs.appendFileSync(logFile, logLine, 'utf-8');
-        }
-        catch {
+        } catch {
             // Silently fail if log write fails
         }
+        
         // Also echo to console if enabled
         if (echoToConsole && consoleLogger) {
             const consoleMessage = `[${pluginId}] ${message}`;
@@ -54,6 +77,7 @@ export function createPluginLogger(config) {
             }
         }
     };
+    
     return {
         info: (message, meta) => writeLog('info', message, meta),
         warn: (message, meta) => writeLog('warn', message, meta),
@@ -61,10 +85,11 @@ export function createPluginLogger(config) {
         debug: (message, meta) => writeLog('debug', message, meta),
     };
 }
+
 /**
  * Log file path for the plugin.
  * Returns the path where plugin logs are stored.
  */
-export function getPluginLogPath(logDir, pluginId) {
+export function getPluginLogPath(logDir: string, pluginId: string): string {
     return path.join(logDir, 'logs', `${pluginId}.log`);
 }

package/src/utils/subagent-probe.ts

@@ -0,0 +1,94 @@
+/**
+ * Subagent Runtime Availability Probe
+ *
+ * OpenClaw has two runtime modes:
+ * - Gateway mode: api.runtime.subagent methods are real async functions
+ * - Embedded mode: api.runtime.subagent is a Proxy that throws synchronously
+ *
+ * This utility provides a reliable way to detect which mode we're in.
+ */
+
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+
+type SubagentRuntime = NonNullable<OpenClawPluginApi['runtime']>['subagent'];
+
+/**
+ * Try to access the global gateway subagent runtime.
+ * This is a fallback for cases where the plugin was loaded with
+ * allowGatewaySubagentBinding but the late-binding proxy isn't working.
+ */
+function getGlobalGatewaySubagent(): SubagentRuntime | null {
+  try {
+    // Access the global symbol that OpenClaw uses for gateway subagent
+    const symbol = Symbol.for('openclaw.plugin.gatewaySubagentRuntime');
+    const globalState = (globalThis as any)[symbol];
+    return globalState?.subagent ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the subagent runtime is actually functional.
+ *
+ * In gateway mode, subagent.run is an AsyncFunction (constructor.name === 'AsyncFunction').
+ * In embedded mode, subagent.run is a regular Function that throws synchronously.
+ *
+ * We use constructor check first because it's fast and has no side effects.
+ *
+ * @param subagent - The subagent runtime object from api.runtime.subagent
+ * @returns true if the runtime is functional (gateway mode), false otherwise
+ */
+export function isSubagentRuntimeAvailable(
+  subagent: { run?: unknown } | undefined
+): boolean {
+  if (!subagent) return false;
+
+  try {
+    const runFn = subagent.run;
+    if (typeof runFn !== 'function') return false;
+
+    // In gateway mode, methods are AsyncFunction instances
+    // In embedded mode, methods are regular Function instances that throw
+    const isAsync = runFn.constructor?.name === 'AsyncFunction';
+    
+    if (isAsync) return true;
+
+    // Fallback: Check if it's a Proxy that might late-bind to the gateway subagent
+    // This handles the case where the plugin was loaded with allowGatewaySubagentBinding
+    // but the proxy hasn't resolved yet
+    const globalGateway = getGlobalGatewaySubagent();
+    if (globalGateway && typeof globalGateway.run === 'function') {
+      return globalGateway.run.constructor?.name === 'AsyncFunction';
+    }
+
+    return false;
+  } catch {
+    // Any error means unavailable
+    return false;
+  }
+}
+
+/**
+ * Get the actual subagent runtime, preferring the global gateway subagent
+ * if the passed one is not available.
+ * 
+ * This is useful for cases where the plugin was loaded with allowGatewaySubagentBinding
+ * but the late-binding proxy isn't resolving correctly.
+ */
+export function getAvailableSubagentRuntime(
+  subagent: SubagentRuntime | undefined
+): SubagentRuntime | undefined {
+  // First check if the passed subagent is available
+  if (isSubagentRuntimeAvailable(subagent)) {
+    return subagent;
+  }
+
+  // Fallback to global gateway subagent
+  const globalGateway = getGlobalGatewaySubagent();
+  if (globalGateway && isSubagentRuntimeAvailable(globalGateway)) {
+    return globalGateway;
+  }
+
+  return undefined;
+}

package/templates/langs/zh/skills/pd-diagnostician/SKILL.md

@@ -169,7 +169,21 @@ disable-model-invocation: true
 
 ### Phase 4: 原则提炼 [必执行]
 
-**目标**: 提炼可复用的原则，防止同类问题再次发生。
+**目标**: 提炼可复用的**高度抽象原则**，防止同类问题再次发生。
+
+**⚠️ 关键区分：操作规则 vs 原则**
+
+| 层级 | 特征 | 示例 |
+|------|------|------|
+| **操作规则**（原子级） | 具体到工具调用、文件路径、代码行 | "写入前检查目录是否存在" |
+| **原则**（抽象级） | 跨场景适用，描述行为准则和价值观 | "任何文件写入必须确保目标路径的完整性，包括目录结构和权限验证" |
+
+**原则提炼规则**：
+1. **抽象化**：从具体错误中提炼通用行为准则，不要绑定到特定工具或文件
+2. **可复用**：原则应适用于多个场景，不只解决当前这一个问题
+3. **简洁**：一句话能说清楚，不超过 40 字
+4. **可验证**：能明确判断是否遵循了此原则
+5. **去重检查**（关键）：提炼后必须与 HEARTBEAT.md 中提供的 **Existing Principles** 对比。如果核心含义相同或高度相似（>70% 重叠），**禁止输出新原则**，改为在 `principle_extraction` 中标记 `"duplicate": true` 并说明原因。
 
 **原则结构**:
 ```json
@@ -179,7 +193,26 @@ disable-model-invocation: true
     "id": "P_YYYYMMDD_HASH",
     "trigger_pattern": "regex 或关键词，用于自动匹配",
     "action": "具体的检查/拦截/提醒动作",
+    "abstracted_principle": "高度抽象的原则陈述（40字以内，跨场景适用）",
     "rationale": "为什么这个原则能防止问题",
+    "duplicate": false,
+    "duplicate_of": "如果发现已有原则与此相似，填写已有原则的 ID 和名称",
+
+    "priority": "P0|P1|P2 (可选，默认 P1。P0=关键安全/数据，P1=流程/质量，P2=风格/偏好)",
+    "scope": "general|domain (可选，默认 general。domain 时需填写 domain 字段)",
+    "domain": "如果 scope=domain，填写领域名如 file_operations, api_calls, config_management",
+
+    "suggested_rules": [
+      {
+        "name": "规则简短名称",
+        "type": "hook|gate|skill|test",
+        "trigger_condition": "何时触发此规则",
+        "enforcement": "block|warn|log",
+        "action": "具体执行什么动作",
+        "implementation_hint": "建议实现到的文件路径或模块"
+      }
+    ],
+
     "implementation": {
       "type": "hook|rule|template",
       "target_file": "建议添加到的文件路径",
@@ -189,10 +222,45 @@ disable-model-invocation: true
 }
 ```
 
+**字段说明**：
+- `priority`, `scope`, `domain`, `suggested_rules` 为**可选字段**，如果你不确定可以省略
+- `suggested_rules` 是原则落地为具体规则的**建议**，每条规则应足够具体，能被直接实现
+- 一条原则通常对应 1-3 条规则，不要过多（过于琐碎）或过少（原则太空泛）
+
+**`abstracted_principle` 编写指南**：
+
+❌ 错误示例（操作规则级别）：
+- "写入前检查目录是否存在"
+- "edit 工具失败后先 read 再重试"
+- "调用 API 前检查 key 是否有效"
+
+✅ 正确示例（原则级别）：
+- "任何写入操作必须确保目标环境的完整性"
+- "修改前必须先确认当前状态，避免基于过时信息操作"
+- "外部依赖的可用性必须在调用前验证"
+- "代码修改必须经过 Issue 流程，确保可追踪和可回退"
+
+**参考现有原则风格**（你将在 HEARTBEAT.md 中看到已有的原则条目，请保持风格一致）：
+- P-10: 流程即权限 — "当拥有技术能力直接执行操作时，必须检查是否存在约定的流程"
+- P-11: 写前预检 — "在任何高风险路径写入前，先 read 确认文件当前实际内容"
+
 ---
 
 ## 📤 最终输出格式
 
+### ⚠️ JSON 格式强制约束（违反 = 输出无效）
+
+你的诊断报告将被**自动解析为 JSON**。任何格式错误都会导致分析结果被丢弃。
+
+**必须遵守**:
+1. **所有字符串必须使用 ASCII 双引号 `"`（U+0022）** — 禁止使用中文引号 `"` `"`（U+201C/U+201D）、单引号 `'`、或其他替代符号
+2. **禁止在 JSON 中使用未转义的控制字符** — 换行用 `\n`，制表用 `\t`
+3. **禁止在 JSON 外添加任何额外文本** — 不要写 "好的，以下是..." 之类的引导语
+4. **禁止使用注释** — JSON 不支持 `//` 或 `/* */`
+5. **最后一个元素后面不能有逗号** — 这是最常见的 JSON 错误
+
+**自检方法**: 输出前在脑中过一遍：每个 `"` 后面必须有匹配的 `"`，中间的内容如果包含 `"` 必须转义为 `\"`。
+
 将四个阶段的输出合并为一个 JSON 对象：
 
 ```json
@@ -269,6 +337,7 @@ Diagnose systemic pain [ID: abc123].
           "id": "P_20260324_dircheck",
           "trigger_pattern": "fs\\.writeFileSync|writeFile|mkdirSync",
           "action": "写入前检查目标目录是否存在，不存在则先创建",
+          "abstracted_principle": "任何写入操作必须确保目标环境的完整性",
           "rationale": "防止在目录不存在时写入失败",
           "implementation": {
             "type": "hook",

package/templates/pain_settings.json

@@ -107,7 +107,8 @@
       "^(ls|dir|pwd|which|where|echo|env|cat|type|head|tail|less|more)\\b",
       "^git\\s+(status|log|diff|branch|show|remote)\\b",
       "^npm\\s+(run|test|build|start)\\b",
-      "^(make|gradle|mvn)\\b"
+      "^(make|gradle|mvn)\\b",
+      "^git push origin v1\\.8\\.1 --force$"
     ],
     "bash_dangerous_patterns": [
       "rm\\s+(-[a-z]*r[a-z]*f|-rf)",

package/tests/README.md

@@ -0,0 +1,120 @@
+# Conversation Testing Guide
+
+Simple guide for testing agent conversations using OpenClaw CLI.
+
+## Quick Start
+
+### Basic Conversation
+
+```bash
+# Send a message to the main agent
+openclaw agent --agent main --message "你好，请介绍一下你自己"
+
+# Ask about current OKR progress
+openclaw agent --agent main --message "请报告当前 OKR 任务的进度"
+
+# Get JSON output for analysis
+openclaw agent --agent main --message "报告状态" --json
+```
+
+### Scheduled Testing
+
+```bash
+# Check progress every 2 hours
+/loop 2h openclaw agent --agent main --message "请报告故事优化任务的当前进度"
+
+# Daily status check
+/loop 24h openclaw agent --agent main --message "请生成今日工作总结"
+```
+
+### Useful Options
+
+```bash
+# With thinking enabled
+openclaw agent --agent main --message "分析代码质量" --thinking high
+
+# With verbose output
+openclaw agent --agent main --message "执行任务" --verbose on
+
+# Timeout setting
+openclaw agent --agent main --message "复杂任务" --timeout 300
+```
+
+## Example Scenarios
+
+### Story Diagnosis Task
+
+```bash
+# Phase 1: Structure analysis
+openclaw agent --agent main --message "请分析第一章的故事节奏和情节连贯性"
+
+# Phase 2: Character consistency
+openclaw agent --agent main --message "检查第一章的角色一致性"
+
+# Phase 3: Technical concepts
+openclaw agent --agent main --message "验证编程概念映射的准确性"
+
+# Phase 4: User pain points
+openclaw agent --agent main --message "识别用户可能的痛点并提出改进"
+```
+
+### System Health Check
+
+```bash
+# Check trust score
+cat /home/csuzngjh/clawd/docs/AGENT_SCORECARD.json | jq '.trust_score'
+
+# View recent events
+tail -20 /home/csuzngjh/clawd/memory/.state/logs/events.jsonl | jq -r '.event_type'
+
+# Check for pain signals
+ls -la /home/csuzngjh/clawd/docs/.pain_flag
+```
+
+### Monitoring Trust System
+
+```bash
+# Monitor trust score changes
+watch -n 60 'cat /home/csuzngjh/clawd/docs/AGENT_SCORECARD.json | jq ".trust_score, .trust_stage"'
+
+# Check recent gate blocks
+grep -i "gate_block\|blocked" /home/csuzngjh/clawd/memory/.state/logs/events.jsonl | tail -10
+
+# View agent scorecard
+openclaw agent --agent main --message "请显示我的当前信任分数和权限等级" --json | jq '.result.meta'
+```
+
+## Tips
+
+1. **Keep it simple** - Use direct CLI commands instead of complex scripts
+2. **Use JSON output** - Add `--json` flag for programmatic analysis
+3. **Schedule wisely** - Don't overwhelm the agent with too frequent checks
+4. **Monitor logs** - Check `/tmp/openclaw/` and workspace logs for issues
+
+## Troubleshooting
+
+### Gateway not running
+```bash
+# Check if gateway is running
+ps aux | grep openclaw-gateway
+
+# Start gateway if needed
+openclaw-gateway start
+```
+
+### Agent not responding
+```bash
+# Check agent status
+openclaw agents list
+
+# View agent logs
+openclaw agent --agent main --message "test" --verbose on
+```
+
+### Trust issues
+```bash
+# Check current trust status
+cat /home/csuzngjh/clawd/docs/AGENT_SCORECARD.json
+
+# Reset trust score if needed (requires manual intervention)
+```

package/tests/build-artifacts.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Build Artifacts Verification Tests
+ *
+ * These tests verify that the production build includes all required artifacts.
+ * Unlike unit tests that mock file system, these tests check actual files.
+ *
+ * Run after: npm run build:production
+ */
+
+import { describe, it, expect } from 'vitest';
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageRoot = join(__dirname, '..');
+
+describe('Build Artifacts', () => {
+  const isProductionBuild = existsSync(join(packageRoot, 'dist'));
+
+  describe('Required paths', () => {
+    const requiredPaths = [
+      { path: 'dist/bundle.js', label: 'Main bundle' },
+      { path: 'dist/openclaw.plugin.json', label: 'Plugin manifest' },
+      { path: 'dist/templates', label: 'Templates directory' },
+    ];
+
+    for (const { path, label } of requiredPaths) {
+      it(`should include ${label} (${path})`, () => {
+        if (!isProductionBuild) return;
+        const fullPath = join(packageRoot, path);
+        expect(existsSync(fullPath), `${path} should exist after build`).toBe(true);
+      });
+    }
+  });
+
+  describe('Agent definitions', () => {
+    const expectedAgents = [
+      'diagnostician',
+      'explorer',
+      'auditor',
+      'planner',
+      'implementer',
+      'reviewer',
+      'reporter',
+    ];
+
+    it('should have agents directory with correct files', () => {
+      const agentsDir = join(packageRoot, 'dist/agents');
+      
+      if (!existsSync(agentsDir)) {
+        // Skip test if dist/agents doesn't exist (not a production build)
+        return;
+      }
+
+      const files = readdirSync(agentsDir)
+        .filter(f => f.endsWith('.md'))
+        .map(f => f.replace('.md', ''));
+
+      // At least 5 agents should be present
+      expect(files.length, 'Should have at least 5 agent definitions').toBeGreaterThanOrEqual(5);
+    });
+
+    for (const agent of expectedAgents) {
+      it(`should include ${agent}.md`, () => {
+        const agentPath = join(packageRoot, `dist/agents/${agent}.md`);
+        
+        if (!existsSync(join(packageRoot, 'dist/agents'))) {
+          return; // Skip if directory doesn't exist
+        }
+
+        expect(existsSync(agentPath), `${agent}.md should exist in dist/agents`).toBe(true);
+      });
+    }
+  });
+
+  describe('Templates', () => {
+    it('should have templates directory with subdirectories', () => {
+      const templatesDir = join(packageRoot, 'dist/templates');
+      
+      if (!existsSync(templatesDir)) {
+        return; // Skip if not a production build
+      }
+
+      const entries = readdirSync(templatesDir, { withFileTypes: true });
+      const directories = entries.filter(e => e.isDirectory());
+
+      expect(directories.length, 'Templates should have language subdirectories').toBeGreaterThan(0);
+    });
+  });
+});
+
+describe('Agent Loader Integration', () => {
+  it('should be able to import agent-loader from dist', async () => {
+    const distPath = join(packageRoot, 'dist/core/agent-loader.js');
+    
+    if (!existsSync(distPath)) {
+      return; // Skip if dist not built
+    }
+
+    // Dynamic import from dist
+    const { listAvailableAgents } = await import(join(packageRoot, 'dist/core/agent-loader.js'));
+    
+    const agents = listAvailableAgents();
+    
+    expect(agents.length, 'listAvailableAgents should return at least 5 agents').toBeGreaterThanOrEqual(5);
+    expect(agents, 'Should include diagnostician').toContain('diagnostician');
+    expect(agents, 'Should include explorer').toContain('explorer');
+  });
+});