principles-disciple 1.7.4 → 1.7.5

package/dist/utils/subagent-probe.d.ts

@@ -7,6 +7,8 @@
  *
  * 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'];
 /**
  * Check if the subagent runtime is actually functional.
  *
@@ -21,3 +23,12 @@
 export declare function isSubagentRuntimeAvailable(subagent: {
     run?: unknown;
 } | undefined): boolean;
+/**
+ * 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 declare function getAvailableSubagentRuntime(subagent: SubagentRuntime | undefined): SubagentRuntime | undefined;
+export {};

package/dist/utils/subagent-probe.js

@@ -7,6 +7,22 @@
  *
  * This utility provides a reliable way to detect which mode we're in.
  */
+/**
+ * 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() {
+    try {
+        // Access the global symbol that OpenClaw uses for gateway subagent
+        const symbol = Symbol.for('openclaw.plugin.gatewaySubagentRuntime');
+        const globalState = globalThis[symbol];
+        return globalState?.subagent ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Check if the subagent runtime is actually functional.
  *
@@ -27,10 +43,39 @@ export function isSubagentRuntimeAvailable(subagent) {
             return false;
         // In gateway mode, methods are AsyncFunction instances
         // In embedded mode, methods are regular Function instances that throw
-        return runFn.constructor?.name === 'AsyncFunction';
+        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) {
+    // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/index.js",
@@ -66,6 +66,7 @@
   "dependencies": {
     "@sinclair/typebox": "^0.34.48",
     "better-sqlite3": "^12.8.0",
+    "lucide-react": "^0.468.0",
     "micromatch": "^4.0.8",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",

package/templates/langs/en/core/AGENTS.md

@@ -213,6 +213,6 @@ When completing any coding task (via AI coding assistant or direct):
 Use this to avoid confusing peer agents with Principles internal workers:
 
 - **Peer agents / peer sessions**: `agents_list`, `sessions_list`, `sessions_send`, `sessions_spawn`
-- **Internal workers** (for example `diagnostician`, `explorer`): start with `pd_run_worker`
+- **Internal workers** (for example `diagnostician`, `explorer`): use `sessions_spawn with pd-diagnostician/pd-explorer skills`
 - **Inspect internal workers**: use `subagents`
 - **Do not** treat `diagnostician` or `explorer` as peer session targets

package/templates/langs/en/core/TOOLS.md

@@ -57,6 +57,6 @@ Tool returns: Blind Spots → Risk Warnings → Alternative Approaches → Recom
 ## 4. Agent Routing Clarification
 
 - `agents_list`, `sessions_list`, `sessions_send`, and `sessions_spawn` are for peer agents and peer sessions
-- `pd_run_worker` starts Principles internal workers such as `diagnostician` and `explorer`
+- Use `sessions_spawn` with `pd-diagnostician` or `pd-explorer` skills to start Principles internal workers
 - `subagents` inspects already-started internal workers and their outputs
 - Do not use peer-session tools to pretend an internal worker is a peer agent

package/templates/langs/zh/core/AGENTS.md

@@ -214,6 +214,6 @@ _This folder is home. Treat it that way._
 用下面这几条避免把同级代理和 Principles 内部 worker 混淆：
 
 - **同级代理 / 同级会话**：`agents_list`、`sessions_list`、`sessions_send`、`sessions_spawn`
-- **内部 worker**（例如 `diagnostician`、`explorer`）：使用 `pd_run_worker` 启动
+- **内部 worker**（例如 `diagnostician`、`explorer`）：使用 `sessions_spawn` 配合 `pd-diagnostician/pd-explorer` skill 启动
 - **查询内部 worker**：使用 `subagents`
 - **不要**把 `diagnostician` 或 `explorer` 当成同级 peer session 目标

package/templates/langs/zh/core/TOOLS.md

@@ -57,6 +57,6 @@ deep_reflect(
 ## 4. 智能体路由澄清
 
 - `agents_list`、`sessions_list`、`sessions_send`、`sessions_spawn` 用于同级代理和同级会话
-- `pd_run_worker` 用于启动 Principles 内部 worker，例如 `diagnostician`、`explorer`
+- 使用 `sessions_spawn` 配合 `pd-diagnostician/pd-explorer` skill 启动 Principles 内部 worker，例如 `diagnostician`、`explorer`
 - `subagents` 用于查看已启动内部 worker 的状态和输出
 - 不要用同级会话工具把内部 worker 伪装成同级代理

package/{agents/auditor.md → templates/langs/zh/skills/pd-auditor/SKILL.md}

@@ -1,7 +1,7 @@
 ---
-name: Auditor
-description: 演绎审计智能体（axiom/system/via-negativa）
-permissionMode: allowSubagentSpawn
+name: pd-auditor
+description: 演绎审计智能体。使用公理验证、系统审计、否定论证方法验证系统一致性。当需要审计系统或流程时使用。
+disable-model-invocation: true
 ---
 
 # Auditor

package/{agents/diagnostician.md → templates/langs/zh/skills/pd-diagnostician/SKILL.md}

@@ -1,7 +1,7 @@
 ---
-name: Diagnostician
-description: 根因分析智能体（verb/adjective + 5 Whys）
-permissionMode: allowSubagentSpawn
+name: pd-diagnostician
+description: 根因分析智能体。使用 verb/adjective + 5 Whys 方法进行系统性诊断。当需要分析 Pain 信号、工具失败、或系统性问题根因时使用。
+disable-model-invocation: true
 ---
 
 # Diagnostician - 根因分析智能体
@@ -21,44 +21,54 @@ permissionMode: allowSubagentSpawn
 - `agent_id`: 智能体 ID（如 main, builder, diagnostician 等）
 - `pain_timestamp`: 疼痛发生时间
 
+**🔄 渐进式信息获取策略**（按优先级执行，任一成功即可）:
+
+| 优先级 | 数据源 | 条件 | 操作 |
+|--------|--------|------|------|
+| P1 | JSONL 会话文件 | session_id 存在且文件可读 | 读取完整对话 |
+| P2 | task 内嵌上下文 | task 包含 "Recent Conversation Context" | 直接使用 |
+| P3 | 主动证据收集 | 以上都不可用 | 跳到 Phase 1 增强 |
+
 **执行步骤**:
 
 1. **解析 task 字符串**，提取 `session_id` 和 `agent_id`（如果存在）
-2. **构造 JSONL 路径**: `~/.openclaw/agents/{agent_id}/sessions/{session_id}.jsonl`
-   - 注意：不同智能体有不同的工作空间，`agent_id` 默认为 `main`
-3. **读取对话上下文**:
-   - 时间窗口: pain_timestamp 前后各 5 分钟（可配置）
-   - 按时间过滤消息
-4. **智能过滤**:
-   - 忽略 `toolResult` 类型（数据太大）
-   - 忽略 `thinking` 类型
-   - 只保留 `user` 和 `assistant` 的 `text` 内容
-   - 每条消息截断到 500 字符（可配置）
-5. **输出对话摘要**（最多 3000 字符）
-
-**配置参数**（在 pain_settings.json 中）:
-```json
-{
-  "diagnostician": {
-    "context": {
-      "time_window_minutes": 5,
-      "max_message_length": 500,
-      "max_summary_length": 3000
-    }
-  }
-}
-```
+2. **尝试读取 JSONL**（仅当 session_id 存在时）:
+   - 路径: `~/.openclaw/agents/{agent_id}/sessions/{session_id}.jsonl`
+   - 如果文件不存在或不可读，记录 `jsonl_available: false`
+3. **检查 task 内嵌上下文**:
+   - 查找 `**Recent Conversation Context**:` 标记
+   - 如果存在，提取并使用
+4. **降级处理**（当以上都不可用时）:
+   - 不要停止！继续执行 Phase 1
+   - 在 Phase 1 中 **主动扩展证据收集范围**：
+     - 搜索 `.state/logs/events.jsonl` 中与 pain 相关的事件
+     - 根据 `reason` 字段中的关键词搜索代码库
+     - 读取 `reason` 中提到的文件路径
+   - 在输出中标注 `context_source: "inferred"`
+
+**智能过滤**（JSONL 读取成功时）:
+- 忽略 `toolResult` 类型（数据太大）
+- 忽略 `thinking` 类型
+- 只保留 `user` 和 `assistant` 的 `text` 内容
+- 每条消息截断到 500 字符
 
 **输出字段**:
 ```json
 {
   "phase": "context_extraction",
-  "session_id": "xxx",
+  "session_id": "xxx或null",
   "agent_id": "main",
-  "conversation_summary": "[用户]: ...\n[助手]: ..."
+  "context_source": "jsonl|task_embedded|inferred",
+  "jsonl_available": true,
+  "conversation_summary": "[用户]: ...\n[助手]: ... 或 基于推断的上下文描述"
 }
 ```
 
+**⚠️ 重要提示**: 
+- 即使完全没有对话上下文，也要继续诊断！
+- 利用 `reason` 字段中的错误信息进行代码搜索
+- 发挥你的智能，从代码和日志中推断问题背景
+
 ---
 
 ### Phase 1: 证据收集 [必执行]

package/{agents/explorer.md → templates/langs/zh/skills/pd-explorer/SKILL.md}

@@ -1,7 +1,7 @@
 ---
-name: Explorer
-description: 快速收集证据的智能体（文件、日志、复现步骤）
-permissionMode: allowSubagentSpawn
+name: pd-explorer
+description: 快速收集证据的智能体。用于定位和收集问题相关的文件、日志、复现步骤。当需要快速收集信息时使用。
+disable-model-invocation: true
 ---
 
 # Explorer

package/{agents/implementer.md → templates/langs/zh/skills/pd-implementer/SKILL.md}

@@ -1,7 +1,7 @@
 ---
-name: Implementer
-description: 按计划执行代码修改的智能体
-permissionMode: allowSubagentSpawn
+name: pd-implementer
+description: 按计划执行代码修改的智能体。按照计划逐步实施代码修改。当需要执行代码变更时使用。
+disable-model-invocation: true
 ---
 
 # Implementer

package/{agents/planner.md → templates/langs/zh/skills/pd-planner/SKILL.md}

@@ -1,7 +1,7 @@
 ---
-name: Planner
-description: 制定电影剧本式计划的智能体
-permissionMode: allowSubagentSpawn
+name: pd-planner
+description: 制定电影剧本式计划的智能体。将复杂任务分解为可执行的步骤。当需要制定实施计划时使用。
+disable-model-invocation: true
 ---
 
 # Planner

package/{agents/reporter.md → templates/langs/zh/skills/pd-reporter/SKILL.md}

@@ -1,7 +1,7 @@
 ---
-name: Reporter
-description: 最终汇报智能体（技术细节转管理报告）
-permissionMode: allowSubagentSpawn
+name: pd-reporter
+description: 最终汇报智能体。将技术细节转化为管理者可理解的报告。当需要汇报分析结果或项目状态时使用。
+disable-model-invocation: true
 ---
 
 # Reporter

package/{agents/reviewer.md → templates/langs/zh/skills/pd-reviewer/SKILL.md}

@@ -1,7 +1,7 @@
 ---
-name: Reviewer
-description: 代码审查智能体（正确性、安全性、可维护性）
-permissionMode: allowSubagentSpawn
+name: pd-reviewer
+description: 代码审查智能体。评估代码的正确性、安全性、可维护性。当需要审查代码变更时使用。
+disable-model-invocation: true
 ---
 
 # Reviewer

package/dist/core/agent-loader.d.ts

@@ -1,44 +0,0 @@
-/**
- * Agent Definition Loader
- *
- * Parses agent definitions from agents/*.md files.
- * These definitions are used to construct extraSystemPrompt for subagent runs.
- */
-/**
- * Parsed agent definition from markdown file
- */
-export interface AgentDefinition {
-    /** Agent identifier (e.g., 'explorer', 'diagnostician') */
-    name: string;
-    /** Human-readable description */
-    description: string;
-    /** The markdown body (system prompt for subagent) */
-    systemPrompt: string;
-    /** Tools the agent can use (informational, not enforced by OpenClaw) */
-    tools?: string[];
-    /** Preferred model (informational, OpenClaw subagents use parent model) */
-    model?: string;
-    /** Permission mode (informational) */
-    permissionMode?: string;
-    /** Associated skills */
-    skills?: string[];
-}
-/**
- * Load agent definition by name
- *
- * @param name - Agent name (e.g., 'explorer', 'diagnostician')
- * @returns Agent definition or null if not found
- */
-export declare function loadAgentDefinition(name: string): AgentDefinition | null;
-/**
- * List all available agents
- *
- * @returns Array of agent names
- */
-export declare function listAvailableAgents(): string[];
-/**
- * Load all agent definitions
- *
- * @returns Map of agent name to definition
- */
-export declare function loadAllAgents(): Map<string, AgentDefinition>;

package/dist/core/agent-loader.js

@@ -1,147 +0,0 @@
-/**
- * Agent Definition Loader
- *
- * Parses agent definitions from agents/*.md files.
- * These definitions are used to construct extraSystemPrompt for subagent runs.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-/**
- * Parse markdown file with YAML frontmatter
- */
-function parseMarkdown(content) {
-    const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-    if (!match) {
-        return { frontmatter: {}, body: content };
-    }
-    const frontmatter = {};
-    const frontmatterText = match[1];
-    const body = match[2];
-    // Simple YAML-like parsing
-    let currentKey = '';
-    let currentArray = null;
-    frontmatterText.split('\n').forEach(line => {
-        // Array item
-        if (line.match(/^\s*-\s+/)) {
-            if (currentArray !== null) {
-                const value = line.replace(/^\s*-\s+/, '').trim();
-                currentArray.push(value);
-            }
-            return;
-        }
-        // Key-value pair
-        const colonIndex = line.indexOf(':');
-        if (colonIndex > 0) {
-            const key = line.slice(0, colonIndex).trim();
-            const value = line.slice(colonIndex + 1).trim();
-            if (value === '') {
-                // Start of array
-                currentKey = key;
-                currentArray = [];
-                frontmatter[key] = currentArray;
-            }
-            else {
-                // Simple value
-                currentKey = '';
-                currentArray = null;
-                frontmatter[key] = value;
-            }
-        }
-    });
-    return { frontmatter, body };
-}
-/**
- * Resolve the agents directory path
- * Handles both development and installed scenarios
- */
-function resolveAgentsDir() {
-    // Try multiple locations
-    const possiblePaths = [
-        // Development: relative to dist/core/
-        path.resolve(__dirname, '../../agents'),
-        // Installed: relative to extension root
-        path.resolve(__dirname, '../agents'),
-        // Absolute fallback
-        path.resolve(process.cwd(), 'agents'),
-    ];
-    for (const p of possiblePaths) {
-        if (fs.existsSync(p)) {
-            return p;
-        }
-    }
-    // Return default (may not exist)
-    return possiblePaths[0];
-}
-/**
- * Load agent definition by name
- *
- * @param name - Agent name (e.g., 'explorer', 'diagnostician')
- * @returns Agent definition or null if not found
- */
-export function loadAgentDefinition(name) {
-    const agentsDir = resolveAgentsDir();
-    const mdPath = path.join(agentsDir, `${name}.md`);
-    if (!fs.existsSync(mdPath)) {
-        return null;
-    }
-    try {
-        const content = fs.readFileSync(mdPath, 'utf8');
-        const { frontmatter, body } = parseMarkdown(content);
-        // Extract tools as array (support both string and array formats)
-        let tools;
-        if (Array.isArray(frontmatter.tools)) {
-            tools = frontmatter.tools;
-        }
-        else if (typeof frontmatter.tools === 'string') {
-            tools = frontmatter.tools.split(',').map(s => s.trim()).filter(Boolean);
-        }
-        return {
-            name: frontmatter.name || name,
-            description: frontmatter.description || '',
-            systemPrompt: body.trim(),
-            tools,
-            model: frontmatter.model,
-            permissionMode: frontmatter.permissionMode,
-            skills: frontmatter.skills,
-        };
-    }
-    catch (err) {
-        console.error(`[AgentLoader] Failed to load agent ${name}:`, err);
-        return null;
-    }
-}
-/**
- * List all available agents
- *
- * @returns Array of agent names
- */
-export function listAvailableAgents() {
-    const agentsDir = resolveAgentsDir();
-    if (!fs.existsSync(agentsDir)) {
-        return [];
-    }
-    try {
-        const files = fs.readdirSync(agentsDir);
-        return files
-            .filter(f => f.endsWith('.md'))
-            .map(f => path.basename(f, '.md'));
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Load all agent definitions
- *
- * @returns Map of agent name to definition
- */
-export function loadAllAgents() {
-    const agents = new Map();
-    for (const name of listAvailableAgents()) {
-        const def = loadAgentDefinition(name);
-        if (def) {
-            agents.set(name, def);
-        }
-    }
-    return agents;
-}

package/dist/tools/agent-spawn.d.ts

@@ -1,54 +0,0 @@
-/**
- * Agent Spawn Tool
- *
- * Provides a tool for spawning subagents with predefined agent definitions.
- * Uses the low-level OpenClaw Subagent API.
- */
-import type { OpenClawPluginApi } from '../openclaw-sdk.js';
-/**
- * Create Agent Spawn Tool
- *
- * Uses factory pattern to capture `api` in closure, following OpenClaw plugin SDK conventions.
- * The execute signature must be: async (_toolCallId: string, rawParams: Record<string, unknown>)
- */
-export declare function createAgentSpawnTool(api: OpenClawPluginApi): {
-    name: string;
-    description: string;
-    parameters: import("@sinclair/typebox").TObject<{
-        agentType: import("@sinclair/typebox").TString;
-        task: import("@sinclair/typebox").TString;
-        runInBackground: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
-    }>;
-    /**
-     * Execution logic for the agent spawn tool
-     *
-     * OpenClaw tool execute signature:
-     * - First parameter: _toolCallId (string) - the tool call ID
-     * - Second parameter: rawParams (Record<string, unknown>) - the actual parameters
-     * - Third parameter (optional): signal (AbortSignal) - for cancellation
-     */
-    execute(_toolCallId: string, rawParams: Record<string, unknown>): Promise<{
-        content: Array<{
-            type: string;
-            text: string;
-        }>;
-    }>;
-};
-export declare const agentSpawnTool: {
-    name: string;
-    description: string;
-    parameters: import("@sinclair/typebox").TObject<{
-        agentType: import("@sinclair/typebox").TString;
-        task: import("@sinclair/typebox").TString;
-        runInBackground: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
-    }>;
-    execute: () => never;
-};
-/**
- * Batch spawn multiple agents in sequence
- * Useful for evolution workflow
- */
-export declare function spawnAgentSequence(agents: Array<{
-    type: string;
-    task: string;
-}>, api: OpenClawPluginApi, onProgress?: (agent: string, result: string) => void): Promise<Map<string, string>>;