@wowok/agent-mcp 2.5.4 → 2.5.5

package/README.md

@@ -25,40 +25,47 @@ Docs: [https://github.com/wowok-ai/docs/](https://github.com/wowok-ai/docs/)
 }
 ```
 
-### 2. Use WoWok Skills (Recommended)
+### 2. Install WoWok Skills (Recommended)
 
-**Skills significantly reduce the learning curve and usage difficulty of the MCP Server.**
+**Skills significantly reduce the learning curve and usage difficulty of the MCP Server.** They provide structured guidance for AI assistants on complex system building, tool usage, and safety protocols.
 
 ```bash
+# Personal (global) — available in all sessions:
 npm install -g @wowok/skills
+
+# Project (team sharing) — commit to git for collaboration:
+cd your-project
+wowok-skills init          # Claude Code (default)
+wowok-skills init --target agents    # Trae IDE
+wowok-skills init --target all       # All 6 supported clients
 ```
 
-Skills provide structured guidance for AI assistants:
+**Supported clients:** Claude Code, OpenAI Codex, Trae IDE, CodeBuddy, Cursor, GitHub Copilot.
+
+#### Available Skills
+
+**Always loaded** (3 skills — foundational layer):
 
-- **Complex system building** — Dependency chains, build order, step-by-step patterns
-- **Tool usage failures** — Correct parameter formats, tool selection, error recovery
-- **Safety & authorization** — User confirmation for important operations
+| Skill | Purpose |
+|-------|---------|
+| `wowok-tools` | MCP tool reference — 17 sub-tools, schema-gated execution, constraints |
+| `wowok-safety` | Safety protocol — dry-run → confirm → execute, immutability rules |
+| `wowok-output` | Output processing — address resolution, name mapping, data visualization |
 
-#### Available Skills (Organized by Role)
+**On-demand** (11 skills — loaded by context):
 
 | Skill | Role | Purpose |
 |-------|------|---------|
-| `wowok-order` | 👤 Customer | Order lifecycle — place orders, track progress, submit disputes, claim compensation |
-| `wowok-provider` | 🏪 Provider | Service provider guide — create Service, design Machine, configure Allocators |
-| `wowok-machine` | 🏪 Provider | Workflow design — state machines, node definitions, progress tracking |
-| `wowok-arbitrator` | ⚖️ Arbitrator | Arbitration service — dispute resolution, voting organization, fee management |
-| `wowok-guard` | 🛠️ Shared | Guard design mastery — programmable trust rules, multi-signature authorization |
-| `wowok-messenger` | 🛠️ Shared | Encrypted messaging — E2E communication, WTS evidence, conversation management |
-| `wowok-output` | 🛠️ Shared | Output processing — post-process responses for human-readable presentation |
-| `wowok-tools` | 🛠️ Shared | MCP tool usage mastery — 13+ tools, parameter formats, schema references |
-| `wowok-safety` | 🛠️ Shared | Safety protocol — dry-run validation, user confirmation checkpoints |
-
-#### Role-Based Skill Selection
-
-- **Use `wowok-order`** when user acts as a customer/buyer placing orders
-- **Use `wowok-provider`** + `wowok-machine` when user is a merchant/service provider
-- **Use `wowok-arbitrator`** when user operates dispute resolution services
-- **Use `wowok-tools`** + `wowok-safety`** + `wowok-output` (always loaded) for all roles
-- **Use `wowok-guard`** when designing complex validation rules
-
-> **Note:** For detailed installation instructions for different AI clients (Claude Code, OpenAI Codex, Trae IDE, Cursor, etc.), see the [WoWok Skills](https://github.com/wowok-ai/skills) repository.
+| `wowok-provider` | 🏪 Provider | Service provider guide — create Service, Machine, Allocators, order fulfillment |
+| `wowok-machine` | 🏪 Provider | Workflow design — state machines, node/pair/forward graph, publish lifecycle |
+| `wowok-order` | 👤 Customer | Order lifecycle — due diligence, consensus, order creation, progress, arbitration |
+| `wowok-arbitrator` | ⚖️ Arbitrator | Arbitration service — dispute resolution, weighted voting, fee management |
+| `wowok-guard` | 🛠️ Shared | Guard design — programmable trust rules, 4 data sources, 33 constraints |
+| `wowok-messenger` | 🛠️ Shared | Encrypted messaging — E2E communication, WTS evidence, anti-spam |
+| `wowok-onboard` | 🆕 New User | First-touch onboarding — 10-round dialogue from zero to first published Service |
+| `wowok-scenario` | 🛠️ Shared | Industry mode templates — freelance, rental, education, travel presets |
+| `wowok-planner` | 🛠️ Shared | Planning — converts natural language intent into Object Dependency Graph (ODG) |
+| `wowok-auditor` | 🛠️ Shared | Pre-publish audit — Guard completeness, Machine soundness, 32 audit checks |
+| `wowok-distill` | 🏪 Provider | Distillation review — review AI-generated improvement proposals |
+
+> **Tip:** `wowok-tools` + `wowok-safety` + `wowok-output` are always loaded and serve all roles. Add role-specific skills (`wowok-provider`, `wowok-order`, `wowok-arbitrator`) as needed.

package/dist/knowledge/reward-confirm.d.ts

@@ -81,6 +81,7 @@ export interface RewardJsonForConfirm {
     guard_expiration_time?: number | null;
     owner_receive?: unknown;
     um?: string | null;
+    guard_expected_progress_state?: string;
 }
 export interface RewardConfirmGateInput {
     reward_json: RewardJsonForConfirm;
@@ -97,6 +98,8 @@ export interface RewardConfirmGateInput {
     passport_submission_value_types?: Record<number, string>;
     passport_identifier_is_address?: Record<number, boolean>;
     guard_store_from_id_compatible?: Record<string, boolean>;
+    user_intent_phrases?: string[];
+    machine_has_wonder_node?: boolean;
     skip_user_confirmation?: boolean;
     skip_environment_check?: boolean;
 }

package/dist/knowledge/reward-confirm.js

@@ -11,6 +11,7 @@ export const REWARD_OPERATION_CHECKLIST = [
     { id: "C-R-08", description: "claim: Passport is provided (SDK W_ERROR if missing)", passed: false, message: "" },
     { id: "C-R-09", description: "owner_receive (156): user double-confirms blast radius", passed: false, message: "" },
     { id: "C-R-10", description: "guard_expiration_time_add (155): new time > current clock", passed: false, message: "" },
+    { id: "C-R-11", description: "guard_add: Guard's progress.current expected value matches business intent (praise→wonder, completion→completed)", passed: false, message: "" },
 ];
 function runStaticChecklist(input) {
     const items = REWARD_OPERATION_CHECKLIST.map(c => ({ ...c }));
@@ -133,6 +134,22 @@ function runStaticChecklist(input) {
     else {
         cr10.passed = true;
     }
+    const cr11 = items.find(i => i.id === "C-R-11");
+    if (data.guard_expected_progress_state && input.user_intent_phrases && input.user_intent_phrases.length > 0) {
+        const intentLower = input.user_intent_phrases.join(" ").toLowerCase();
+        const praiseKeywords = ["好评", "praise", "wonder", "thumbs_up", "positive review", "satisfaction reward", "好评奖励"];
+        const isPraiseIntent = praiseKeywords.some(kw => intentLower.includes(kw.toLowerCase()));
+        if (isPraiseIntent && input.machine_has_wonder_node !== false && data.guard_expected_progress_state !== "wonder") {
+            cr11.passed = false;
+            cr11.message = `intent=praise but Guard checks "${data.guard_expected_progress_state}" instead of "wonder" — R-R-6-01 violation`;
+        }
+        else {
+            cr11.passed = true;
+        }
+    }
+    else {
+        cr11.passed = true;
+    }
     return {
         all_passed: items.filter(i => i.id !== "C-R-09").every(i => i.passed),
         items,
@@ -162,6 +179,9 @@ function adaptRiskAssessment(input) {
         passport_submission_value_types: input.passport_submission_value_types,
         passport_identifier_is_address: input.passport_identifier_is_address,
         guard_store_from_id_compatible: input.guard_store_from_id_compatible,
+        user_intent_phrases: input.user_intent_phrases,
+        guard_expected_progress_state: input.reward_json.guard_expected_progress_state,
+        machine_has_wonder_node: input.machine_has_wonder_node,
     };
     return assessRewardRisks(ctx);
 }
@@ -201,6 +221,14 @@ export const REWARD_CONFIRMATION_QUESTIONS = [
         requires_explicit_yes: false,
         related_risk_ids: ["R-R-5-02"],
     },
+    {
+        id: "QRW7",
+        question: "⚠️ For guard_add with progress.current check: does the Guard's expected progress node match the business intent? " +
+            "If intent is '好评/praise', Guard must check 'wonder' (NOT 'completed'). " +
+            "Premature claim at wrong node drains reward pool — Guard is immutable after creation.",
+        requires_explicit_yes: true,
+        related_risk_ids: ["R-R-6-01", "R-R-6-02"],
+    },
 ];
 function processUserConfirmation(input, assessment) {
     const questions = [...REWARD_CONFIRMATION_QUESTIONS];
@@ -217,6 +245,8 @@ function processUserConfirmation(input, assessment) {
             continue;
         if (q.id === "QRW6" && !data.coin_add)
             continue;
+        if (q.id === "QRW7" && (!data.guard_add || !data.guard_expected_progress_state))
+            continue;
         filtered.push(q);
     }
     if (input.skip_user_confirmation) {

package/dist/knowledge/reward-puzzle.d.ts

@@ -48,6 +48,7 @@ export interface RewardConstraintChecklist {
     F_R_06_recipient_amount_valid_pairing: boolean;
     F_R_07_coin_type_matches_reward_t: boolean;
     F_R_08_passport_required_for_claim: boolean;
+    F_R_09_progress_node_matches_intent: boolean;
 }
 export type RewardPuzzleDimension = "A" | "B" | "C" | "D" | "E" | "F";
 export interface RewardPuzzle {

package/dist/knowledge/reward-puzzle.js

@@ -29,6 +29,7 @@ export function initPuzzleFromIntent(intent) {
         F_R_06_recipient_amount_valid_pairing: false,
         F_R_07_coin_type_matches_reward_t: false,
         F_R_08_passport_required_for_claim: false,
+        F_R_09_progress_node_matches_intent: true,
     };
     return puzzle;
 }
@@ -177,6 +178,17 @@ export function validateConstraints(puzzle) {
             message: "claim requires Passport — SDK W_ERROR if missing",
         });
     }
+    if (puzzle.guard && puzzle.intent && puzzle.constraints) {
+        if (!puzzle.constraints.F_R_09_progress_node_matches_intent) {
+            violations.push({
+                constraint_id: "F-R-09",
+                severity: "HIGH",
+                message: "Guard's expected progress.current value does not match business intent — " +
+                    "praise reward (好评/wonder) must check 'wonder' node, not 'completed'. " +
+                    "Guard is immutable after creation; mismatch requires full rebuild.",
+            });
+        }
+    }
     return violations;
 }
 export function generateConfirmationText(puzzle) {

package/dist/knowledge/reward-risk.d.ts

@@ -1,6 +1,6 @@
 import { type RewardScene, type RewardAmountType } from "./reward-ledger.js";
 export type RewardRiskLevel = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
-export type RewardRiskCategory = "structural" | "semantic" | "permission" | "lifecycle" | "cross_object";
+export type RewardRiskCategory = "structural" | "semantic" | "permission" | "lifecycle" | "cross_object" | "business_semantic";
 export interface RewardRisk {
     id: string;
     level: RewardRiskLevel;
@@ -65,6 +65,9 @@ export interface RewardRiskCheckContext {
     passport_submission_value_types?: Record<number, string>;
     passport_identifier_is_address?: Record<number, boolean>;
     guard_store_from_id_compatible?: Record<string, boolean>;
+    user_intent_phrases?: string[];
+    guard_expected_progress_state?: string;
+    machine_has_wonder_node?: boolean;
 }
 export declare const REWARD_RISK_VERSION = "1.0.0";
 export declare function getAllRewardRiskRules(): RewardRiskRule[];

package/dist/knowledge/reward-risk.js

@@ -469,12 +469,94 @@ const R_R_5_03 = {
         return null;
     },
 };
+const R_R_6_01 = {
+    id: "R-R-6-01",
+    category: "business_semantic",
+    trigger: "intent mentions praise/好评 but Guard checks non-wonder progress node",
+    check: (ctx) => {
+        if (!ctx.user_intent_phrases || ctx.user_intent_phrases.length === 0)
+            return null;
+        if (!ctx.guard_expected_progress_state)
+            return null;
+        const intentLower = ctx.user_intent_phrases.join(" ").toLowerCase();
+        const praiseKeywords = [
+            "好评", "praise", "wonder", "thumbs_up",
+            "positive review", "satisfaction reward", "好评奖励",
+        ];
+        const isPraiseIntent = praiseKeywords.some(kw => intentLower.includes(kw.toLowerCase()));
+        if (!isPraiseIntent)
+            return null;
+        if (ctx.machine_has_wonder_node === false)
+            return null;
+        const expected = ctx.guard_expected_progress_state;
+        if (expected !== "wonder") {
+            return {
+                id: "R-R-6-01",
+                level: "HIGH",
+                category: "business_semantic",
+                title: `Guard checks progress=="${expected}" but intent indicates praise reward (wonder node)`,
+                description: `User intent mentions praise/好评/wonder, which maps to the 'wonder' progress node ` +
+                    `(customer gives positive review AFTER service completion). But the Guard's table bakes ` +
+                    `expected state="${expected}", allowing reward claim at the wrong lifecycle stage. ` +
+                    `This violates the business semantics: "好评奖励" should only be claimable AFTER the ` +
+                    `customer advances to the 'wonder' node, not before. ` +
+                    `Guard is immutable — fixing this requires creating a new Guard + Reward pair.`,
+                affected_stakeholders: ["owner", "service_provider", "claimer"],
+                scenario: "Designer builds Guard checking 'completed' instead of 'wonder' for a praise reward",
+                mitigation: "Set the Guard table's expected progress state to 'wonder' (the positive-review node). " +
+                    "The correct pattern: ordered → in_service → completed → wonder (praise) triggers reward claim. " +
+                    "Reference: reward-templates.ts wonder_praise template.",
+                evidence: `intent="${intentLower}", expected_state="${expected}", expected_wonder=true`,
+                auto_fixable: false,
+            };
+        }
+        return null;
+    },
+};
+const R_R_6_02 = {
+    id: "R-R-6-02",
+    category: "business_semantic",
+    trigger: "Guard checks wonder node but intent does not mention praise",
+    check: (ctx) => {
+        if (!ctx.user_intent_phrases || ctx.user_intent_phrases.length === 0)
+            return null;
+        if (!ctx.guard_expected_progress_state)
+            return null;
+        if (ctx.guard_expected_progress_state !== "wonder")
+            return null;
+        const intentLower = ctx.user_intent_phrases.join(" ").toLowerCase();
+        const praiseKeywords = [
+            "好评", "praise", "wonder", "thumbs_up",
+            "positive review", "satisfaction reward", "好评奖励",
+        ];
+        const isPraiseIntent = praiseKeywords.some(kw => intentLower.includes(kw.toLowerCase()));
+        if (isPraiseIntent)
+            return null;
+        return {
+            id: "R-R-6-02",
+            level: "MEDIUM",
+            category: "business_semantic",
+            title: "Guard checks wonder node but intent does not mention praise",
+            description: `Guard's expected progress state is "wonder" (positive-review node), but the user intent ` +
+                `does not mention any praise/好评 keyword. This may be a copy-paste from a wonder_praise ` +
+                `template without adjusting the Guard for the actual business semantics. If this is a ` +
+                `general feedback reward (wonder_feedback), this is fine. Otherwise, verify the node choice.`,
+            affected_stakeholders: ["owner"],
+            scenario: "Designer copies wonder_praise template but actually wants a completion-based reward",
+            mitigation: "Verify: if intent is praise reward, add '好评/praise' to description. " +
+                "If intent is completion-based reward, change Guard to check 'completed' node.",
+            evidence: `expected_state="wonder", intent="${intentLower}" (no praise keyword)`,
+            auto_fixable: false,
+        };
+    },
+};
 const ALL_RULES = [
     R_R_1_01, R_R_1_02, R_R_1_03,
     R_R_2_01, R_R_2_02, R_R_2_03, R_R_2_04,
     R_R_3_01, R_R_3_02, R_R_3_03,
     R_R_4_01, R_R_4_02, R_R_4_03, R_R_4_04,
     R_R_5_01, R_R_5_02, R_R_5_03,
+    R_R_6_01, R_R_6_02,
 ];
 export const REWARD_RISK_VERSION = "1.0.0";
 export function getAllRewardRiskRules() {
@@ -529,13 +611,13 @@ export const REWARD_STAKEHOLDERS = [
 export function getRewardRiskRulesByStakeholder(stakeholder) {
     return ALL_RULES.filter(rule => {
         if (stakeholder === "owner") {
-            return ["structural", "permission", "lifecycle"].includes(rule.category);
+            return ["structural", "permission", "lifecycle", "business_semantic"].includes(rule.category);
         }
         if (stakeholder === "claimer") {
-            return rule.id.startsWith("R-R-4-0") || rule.id === "R-R-5-01" || rule.id === "R-R-1-02";
+            return rule.id.startsWith("R-R-4-0") || rule.id === "R-R-5-01" || rule.id === "R-R-1-02" || rule.id === "R-R-6-01";
         }
         if (stakeholder === "service_provider") {
-            return rule.id === "R-R-4-02" || rule.id === "R-R-3-01" || rule.id === "R-R-3-02";
+            return rule.id === "R-R-4-02" || rule.id === "R-R-3-01" || rule.id === "R-R-3-02" || rule.id === "R-R-6-01";
         }
         if (stakeholder === "system") {
             return rule.category === "cross_object";

package/dist/knowledge/tools-reference.js

@@ -105,11 +105,12 @@ export const TOOLS_REFERENCE = [
     },
     {
         name: "project_operation",
-        summary: "Project namespace + object dependency graph (DAG) + GLM5 C1-C4 composite actions.",
-        actions: ["list_projects", "list_objects", "shareable", "dependencies", "referenced_by", "pre_publish_check", "cross_project_refs", "graph_stats", "save_graph", "load_graph", "analyze_intent", "aggregate_risks", "generate_deployment_doc", "trace_substeps"],
+        summary: "Project entity management (SQLite) + 3-pathway graph construction + dual rule-based/LLM-assisted evaluation engine.",
+        actions: ["list_projects", "create_project", "create_project_from_onchain", "update_project", "get_project_detail", "add_object", "remove_object", "create_version", "build_graph", "get_graph", "evaluate_project", "save_evaluation", "compare_projects", "refresh_objects", "get_object_diff", "assemble_context"],
         notes: [
-            "GLM5: C1-C4 actions drive the 5-stage project-based deployment flow.",
-            "Non-blocking: only CRITICAL risks block; HIGH/MEDIUM/LOW are advisory.",
+            "GLM6: Projects are first-class entities with SQLite persistence, rigid project-object relationships.",
+            "Evaluation: risk/trust/completeness are rule-based (computed locally). value/worth_buying require LLM assistance (returns a prompt).",
+            "Graph: 3 pathways — internal references (configurable depth), Registrar inbound (O(1)), potential relationships.",
         ],
     },
     {

package/dist/project/evaluation.d.ts

@@ -0,0 +1,53 @@
+import type { Project, ProjectObject, GraphEdge, ObjectCacheEntry, EvaluationType } from "@wowok/wowok";
+import type { ReputationData } from "./graph-builder.js";
+export interface CriterionScore {
+    name: string;
+    score: number;
+    weight: number;
+    rationale: string;
+}
+export interface EvaluationFinding {
+    criterion: string;
+    severity: "critical" | "warning" | "info";
+    message: string;
+    deduction: number;
+}
+export interface EvaluationResult {
+    evaluationType: EvaluationType;
+    score: number;
+    summary: string;
+    criterionScores: CriterionScore[];
+    findings: EvaluationFinding[];
+    strengths: string[];
+    needsLlm: boolean;
+    llmPrompt?: string;
+    evaluatedAt: number;
+}
+export interface EvaluationInput {
+    project: Project;
+    objects: ProjectObject[];
+    edges: GraphEdge[];
+    objectCache: Map<string, ObjectCacheEntry>;
+    reputation?: Map<string, ReputationData>;
+}
+export declare function runEvaluation(input: EvaluationInput, evaluationType: EvaluationType, llmPrompt?: string): EvaluationResult;
+export interface ProjectComparisonEntry {
+    projectId: string;
+    projectName: string;
+    score: number | null;
+    summary: string | null;
+    evaluatedAt: number | null;
+}
+export interface ProjectComparison {
+    evaluationType: EvaluationType;
+    entries: ProjectComparisonEntry[];
+    ranking: ProjectComparisonEntry[];
+    bestProjectId: string | null;
+}
+export declare function compareProjects(entries: Array<{
+    projectId: string;
+    projectName: string;
+    score: number | null;
+    summary: string | null;
+    evaluatedAt: number | null;
+}>, evaluationType: EvaluationType): ProjectComparison;