@wowok/agent-mcp 2.2.8 → 2.2.13

package/docs/docs/stage-03-collaboration.md

@@ -0,0 +1,337 @@
+# Stage 3: Open Collaboration 🤝
+
+---
+
+**[← Stage 2: Trust Management](stage-02-trust.md) | [Stage 4: Transaction Execution →](stage-04-transaction.md)**
+
+---
+
+## 🎯 Stage Objectives
+
+In this stage, you will learn about open collaboration mechanisms in WoWok, including:
+
+- How to use Machine and Progress to define and execute workflows
+- How to use Messenger for secure private communication
+- How to use Contact to manage public contact information
+
+---
+
+## 📚 Learning Content
+
+### 3.1 Machine + Progress (Workflow Engine ⚙️)
+
+**Why do we need Machine and Progress?**
+
+Collaboration needs to be process-oriented. Machine is the workflow template (defining what to do), and Progress is the workflow instance (tracking execution progress).
+
+**Core Concepts:**
+- 📋 **Machine** - Workflow template, defines nodes and transition rules
+- 🔄 **Progress** - Workflow instance, tracks execution status
+- 🎯 **Nodes** - Steps in the workflow (states)
+- 🔗 **Transitions** - Operation rules from one node to another
+
+**Core Features:**
+
+**Machine Features:**
+- ✅ Create Machine (define nodes and transition rules)
+- ✅ Add/Modify nodes (modifiable before publishing)
+- ✅ Publish Machine (lock nodes, ready for use)
+- ✅ Create Progress (launch workflow instance)
+- ✅ Manage Repository (bind data storage)
+
+**Progress Features:**
+- ✅ Advance Progress (execute node transitions)
+- ✅ Manage named operators (dynamic permission assignment)
+- ✅ Set Task ID (associate objects)
+- ✅ Manage context Repository
+
+**→ [View Machine Detailed Documentation →](machine.md)**
+**→ [View Progress Detailed Documentation →](progress.md)**
+
+---
+
+### 3.2 Messenger (Private Communication 🔒)
+
+**Why do we need Messenger?**
+
+Collaboration requires communication. Messenger provides end-to-end encrypted secure communication, supporting WTS verifiable chat records.
+
+**Core Concepts:**
+- 🔒 **End-to-End Encryption** - Only communication parties can see the content
+- 📝 **WTS** - Witness Timestamped Signature, verifiable chat records (can be used as legal evidence)
+- 📎 **File Transfer** - Securely send files
+- ⏰ **On-Chain Proof** - Generate on-chain timestamp proof for messages
+
+**Core Features:**
+- ✅ View conversation list
+- ✅ Send text messages (end-to-end encrypted)
+- ✅ Send files
+- ✅ View message history
+- ✅ Generate WTS proof
+- ✅ Verify WTS signature
+- ✅ On-chain proof messages
+- ✅ Manage blacklist/friends list/Guard list
+
+**→ [View Messenger Detailed Documentation →](messenger.md)**
+
+---
+
+### 3.3 Contact (Service Window 📇)
+
+**Why do we need Contact?**
+
+Collaboration requires contact information. Contact manages public contact information and can be bound to Service.
+
+**Core Features:**
+- ✅ Create Contact (set name, description, location)
+- ✅ Manage IM contact list (add/remove/clear)
+- ✅ Set personal status
+- ✅ Receive objects sent to Contact
+- ✅ Bind to Service and other objects (as service contact)
+
+**Important Notes:**
+- ⚠️ It is recommended to only place public contact information
+
+**→ [View Contact Detailed Documentation →](contact.md)**
+
+---
+
+## 🎓 Practice Exercises
+
+### Exercise 1: Create a Simple Workflow Machine
+
+**💬 You**: Create a Machine named "design_workflow" for design service process.
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation_type": "machine",
+  "data": {
+    "object": {
+      "name": "design_workflow"
+    },
+    "description": "Design service workflow - complete process from order creation to delivery"
+  }
+}
+```
+
+**✅ After successful execution, add nodes:**
+
+**💬 You**: Add three nodes to "design_workflow": created (initial node), designing, completed (terminal node).
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation_type": "machine",
+  "data": {
+    "object": "design_workflow",
+    "node": {
+      "op": "add",
+      "nodes": [
+        {
+          "name": "created",
+          "pairs": []
+        },
+        {
+          "name": "designing",
+          "pairs": [
+            {
+              "prev_node": "created",
+              "threshold": 1,
+              "forwards": [
+                {
+                  "name": "start_design",
+                  "permissionIndex": 1000,
+                  "weight": 1
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "name": "completed",
+          "pairs": [
+            {
+              "prev_node": "designing",
+              "threshold": 1,
+              "forwards": [
+                {
+                  "name": "complete_design",
+                  "permissionIndex": 1001,
+                  "weight": 1
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+**✅ After successful execution, publish Machine:**
+
+**💬 You**: Publish "design_workflow" Machine.
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation_type": "machine",
+  "data": {
+    "object": "design_workflow",
+    "publish": true
+  }
+}
+```
+
+---
+
+### Exercise 2: Create and Advance Progress
+
+**💬 You**: Create a Progress based on "design_workflow", named "my_first_progress".
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation_type": "machine",
+  "data": {
+    "object": "design_workflow",
+    "progress_new": {
+      "namedNew": {
+        "name": "my_first_progress"
+      }
+    }
+  }
+}
+```
+
+**✅ After successful execution, advance Progress:**
+
+**💬 You**: Advance "my_first_progress" from created node to designing node by executing "start_design" operation.
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation_type": "progress",
+  "data": {
+    "object": "my_first_progress",
+    "operate": {
+      "operation": {
+        "next_node_name": "designing",
+        "forward": "start_design"
+      },
+      "hold": false,
+      "message": "Start design work"
+    }
+  }
+}
+```
+
+---
+
+### Exercise 3: Send Encrypted Message
+
+**💬 You**: Send an encrypted message "Hello, I would like to inquire about design services" to "alice".
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation": "send_message",
+  "to": {
+    "name_or_address": "alice"
+  },
+  "content": "Hello, I would like to inquire about design services"
+}
+```
+
+---
+
+### Exercise 4: View Conversation List
+
+**💬 You**: View all my conversation lists.
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation": "watch_conversations"
+}
+```
+
+---
+
+### Exercise 5: Create Contact
+
+**💬 You**: Create a Contact named "design_service_contact" with description "Design service contact information".
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation_type": "contact",
+  "data": {
+    "object": {
+      "name": "design_service_contact"
+    },
+    "description": "Design service contact - 24/7 online support",
+    "location": "Online service",
+    "ims": {
+      "op": "clear"
+    }
+  }
+}
+```
+
+---
+
+### Exercise 6: Manage Messenger Blacklist
+
+**💬 You**: Add address "0x1234...abcd" to my blacklist.
+
+**🤖 AI Generated Request:**
+
+```json
+{
+  "operation": "blacklist",
+  "blacklist": {
+    "op": "add",
+    "users": ["0x1234abcd5678efgh9012ijkl3456mnop7890qrst"]
+  }
+}
+```
+
+---
+
+## 🏆 Stage Checklist
+
+Before moving to the next stage, please confirm that you have:
+
+- [ ] Understood the difference between Machine and Progress
+- [ ] Created at least one Machine
+- [ ] Added nodes and transition rules to Machine
+- [ ] Published Machine
+- [ ] Created at least one Progress
+- [ ] Advanced Progress nodes
+- [ ] Sent encrypted messages
+- [ ] Viewed conversation list
+- [ ] Created Contact
+- [ ] Managed IM contacts
+
+---
+
+## 🎉 Congratulations!
+
+You have completed Stage 3! Now you have mastered WoWok's open collaboration mechanisms and can move on to the next stage to learn about transaction execution!
+
+**[→ Go to Stage 4: Transaction Execution 💼 →](stage-04-transaction.md)**
+
+---
+
+**[← Return to Main Directory](../README.md)**

package/docs/docs/stage-04-transaction.md

@@ -0,0 +1,277 @@
+# Stage 4: Transaction Execution 💼
+
+---
+
+**[← Stage 3: Open Collaboration](stage-03-collaboration.md) | [Stage 5: Business Components →](stage-05-business.md)**
+
+---
+
+## 🎯 Stage Objectives
+
+In this stage, you will learn the transaction mechanisms in WoWok, including:
+
+- How to use Allocation for automatic fund distribution
+- How to use WIP to describe products and services
+- How to use Service and Order for service sales and order management
+- How to use Arbitration for dispute resolution
+
+---
+
+## 📚 Learning Content
+
+### 4.1 WIP for Product and Service Description (📄 WIP)
+
+**Why use WIP for Products and Services?**
+
+WIP (Witness Immutable Promise) provides immutable, verifiable product and service descriptions. By deploying WIP files to the network and using their URLs and hashes as product details, both sellers and buyers can establish deterministic commitments.
+
+**Core Concepts:**
+- 📄 **Immutable Content** - Product descriptions cannot be altered after creation
+- 🔗 **URL + Hash Verification** - Combines network accessibility with cryptographic integrity
+- ✍️ **Multi-signature Support** - Sellers can sign to establish authenticity
+- ✅ **Verifiable** - Anyone can verify the content matches the promised hash
+
+**How WIP Integrates with Service:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Service Object                            │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐  │
+│  │ Product URL │───▶│  WIP File   │───▶│ Hash + Signers  │  │
+│  │ (Network)   │    │  (Immutable)│    │ (Verified)      │  │
+│  └─────────────┘    └─────────────┘    └─────────────────┘  │
+│         │                                    │              │
+│         ▼                                    ▼              │
+│  User views via URL               User verifies integrity   │
+│  and trusted content             and signers                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Core Workflow:**
+
+1. **Generate WIP** - Create a WIP file describing the product/service with detailed specifications
+2. **Sign WIP** - Sign with the seller's account to establish authenticity
+3. **Deploy to Network** - Upload the signed WIP file to a network location
+4. **Create Service** - Use the WIP URL and hash as the product details in the Service object
+5. **Buyer Verification** - Buyers can view the content via URL and verify hash and signers
+
+**Core Features:**
+- ✅ Generate WIP with Markdown text and images
+- ✅ Sign WIP to establish seller identity
+- ✅ Verify hash integrity and signature authenticity
+- ✅ Convert to HTML for display
+
+**Important Notes:**
+- ⚠️ **Hash Immutability** - Once a WIP is deployed and its hash is recorded on-chain, the content cannot be changed without changing the hash
+- ⚠️ **Signature Trust** - Only signatures from trusted accounts should be considered valid
+- ⚠️ **URL Accessibility** - The WIP file must remain accessible at the specified URL
+
+**→ [View WIP Detailed Documentation →](../WIP.md)**
+
+---
+
+### 4.2 Allocation (Automatic Fund Distribution ⚖️)
+
+**Why do we need Allocation?**
+
+Transactions require profit sharing. Allocation allows you to preset fund distribution rules and automatically distribute to multiple recipients.
+
+**Core Concepts:**
+- 👥 **Multiple Recipients** - Support distribution to multiple addresses
+- 📊 **Ratio or Fixed Amount** - Distribute by ratio or fixed amount
+- 🎯 **Auto-execution** - Automatically distribute when triggered
+
+**Core Features:**
+- ✅ Add/remove recipients
+- ✅ Set ratio or amount
+- ✅ Set Guard verification
+- ✅ Bind to Service or other objects
+
+**→ [View Allocation Detailed Documentation →](allocation.md)**
+
+---
+
+### 4.3 Service + Order (Service Sales and Orders 🛒📋)
+
+**Why do we need Service and Order?**
+
+These are the core transaction components in WoWok! Service is what is sold, and Order is the purchase order.
+
+**Core Concepts:**
+- 🛒 **Service** - Service marketplace, publish products or services
+- 📋 **Order** - Order management, handle purchase process
+- 💰 **Price** - Pricing for services
+- 🔗 **Binding Components** - Can bind Machine, Progress, Allocation, Guard, and more
+
+**Core Features:**
+- ✅ Create Service (publish product)
+- ✅ Create Order (purchase product)
+- ✅ Manage order status
+- ✅ Bind various components
+
+**Important Notes:**
+- ⚠️ Service can bind components such as Machine, Guard, Allocation, Contact, Treasury, Reward, and **WIP**!
+
+**Integration with WIP:**
+- The Service object can store the WIP URL and hash as product details
+- Buyers can verify the WIP file to ensure the product matches the promised description
+
+**→ [View Service Detailed Documentation →](service.md)**
+**→ [View Order Detailed Documentation →](order.md)**
+
+---
+
+### 4.4 Arbitration (Dispute Resolution ⚖️)
+
+**Why do we need Arbitration?**
+
+Transactions may have disputes. Arbitration provides a fair dispute resolution mechanism.
+
+**Core Concepts:**
+- 👨‍⚖️ **Arbitrator** - Neutral third party
+- 💵 **Compensation Ratio** - Compensation ratio for buyer and seller
+- ⚖️ **Fair Ruling** - Arbitrators can adjust compensation ratio
+
+**Core Features:**
+- ✅ Create arbitration object
+- ✅ Add/remove arbitrators
+- ✅ Set compensation ratio
+- ✅ Submit and rule on disputes
+
+**→ [View Arbitration Detailed Documentation →](arbitration.md)**
+
+---
+
+## 🎓 Practice Exercises
+
+### Exercise 1: Create a WIP for Product Description
+
+Create a WIP file describing a product and sign it with your account
+
+```json
+{
+  "type": "generate",
+  "options": {
+    "markdown_text": "# Premium Software License\n\n## Product Details\n\n- License Type: Annual Subscription\n- Features: Full access to all modules\n- Support: 24/7 technical support\n- Duration: 12 months\n\n## Terms of Service\n\n1. Non-transferable license\n2. Single user account\n3. Auto-renewal unless cancelled",
+    "account": "my_seller_account"
+  },
+  "outputPath": "./software_license.wip"
+}
+```
+
+After generating, deploy to network and use the URL and hash when creating Service.
+
+---
+
+### Exercise 2: Create a Service with WIP Product Details
+
+Create a Service with sales products that include WIP URL and hash as product details. Each product in the sales list can have its own WIP file for detailed description.
+
+```json
+{
+  "operation_type": "service",
+  "data": {
+    "object": {
+      "name": "software_license_service"
+    },
+    "sales": {
+      "op": "add",
+      "sales": [
+        {
+          "name": "Premium Software License",
+          "price": "1000000000",
+          "stock": "100",
+          "suspension": false,
+          "wip": "https://example.com/products/software_license.wip",
+          "wip_hash": "sha256:abcdef1234567890..."
+        }
+      ]
+    }
+  }
+}
+```
+
+**Note:** The `wip` and `wip_hash` fields are part of each product in the `sales` array, allowing each product to have its own immutable description file.
+
+---
+
+### Exercise 3: Create an Allocation with Profit Sharing
+
+Create a distribution rule that splits profits between two recipients
+
+```json
+{
+  "operation_type": "allocation",
+  "data": {
+    "object": {
+      "name": "profit_sharing"
+    },
+    "allocators": {
+      "description": "Profit sharing between two partners",
+      "threshold": "0",
+      "allocators": [
+        {
+          "guard": "simple_guard",
+          "sharing": [
+            {
+              "who": {
+                "Entity": {
+                  "name_or_address": "partner1_address"
+                }
+              },
+              "sharing": "5000",
+              "mode": "Rate"
+            },
+            {
+              "who": {
+                "Entity": {
+                  "name_or_address": "partner2_address"
+                }
+              },
+              "sharing": "5000",
+              "mode": "Rate"
+            }
+          ]
+        }
+      ]
+    },
+    "coin": {
+      "balance": "0"
+    },
+    "payment_info": {
+      "remark": "Profit sharing payment",
+      "index": "0"
+    }
+  }
+}
+```
+
+---
+
+## 🏆 Stage Checklist
+
+Before moving to the next stage, please confirm that you have:
+
+- [ ] Understood the relationship between WIP and Service
+- [ ] Created a WIP file for product/service description
+- [ ] Signed a WIP file to establish authenticity
+- [ ] Understood how to use WIP URL and hash as product details
+- [ ] Understood the relationship between Service and Order
+- [ ] Created at least one Service
+- [ ] Created at least one Order
+- [ ] Understood Allocation's profit-sharing mechanism
+- [ ] Created at least one Allocation
+- [ ] Understood the role of Arbitration
+- [ ] Know how to combine these components
+
+---
+
+## 🎉 Congratulations!
+
+You have completed Stage 4! Now you have mastered WoWok's transaction mechanisms and are ready to move on to the next stage to learn about business components!
+
+**[→ Go to Stage 5: Business Components 🏪 →](stage-05-business.md)**
+
+---
+
+**[← Return to Main Directory](../README.md)**