@seasonkoh/webaz 0.1.16 → 0.1.17

package/README.md

@@ -88,7 +88,16 @@
 
 ### 方式一：Claude MCP 接入（Agent 原生体验）
 
-**1. 添加到 Claude Desktop 配置**
+MCP server 有两种模式 / The MCP runs in one of two modes：
+
+| 模式 / Mode | 数据源 | 用途 | 如何触发 |
+|---|---|---|---|
+| 🟢 **NETWORK** | `webaz.xyz` 共享生产网络（带你的 `api_key`） | 真实加入网络、和别人交易 | 配了 `WEBAZ_API_KEY` |
+| 🟡 **SANDBOX** | 本机本地 SQLite（`~/.webaz/webaz.db`） | 离线试玩 / 开发，**与全网隔离** | 未配 `WEBAZ_API_KEY`（默认） |
+
+> 🟢 NETWORK = your agent acts on the live shared network. 🟡 SANDBOX = local-only, private to your machine, **not** the live network. Every tool result is stamped with `_mode` so you always know which one you're in.
+
+**A. 先离线试玩（SANDBOX，零配置）**
 
 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
 
@@ -103,15 +112,35 @@
 }
 ```
 
-重启 Claude Desktop。无需手动安装，`npx` 会自动下载运行。
+重启 Claude Desktop。`npx` 自动下载运行。此时所有数据都在本机沙盒，可放心试 `webaz_register` / `webaz_search` / 下单全流程。
+
+**B. 真正加入网络（NETWORK）**
+
+1. 在 [webaz.xyz](https://webaz.xyz) 注册账号（需邀请码；注册时绑定 Passkey 成为可问责真人）
+2. 「我的 / 设置」→ 复制 `api_key`
+3. 配置里加上 `WEBAZ_API_KEY` 环境变量：
+
+```json
+{
+  "mcpServers": {
+    "webaz": {
+      "command": "npx",
+      "args": ["-y", "@seasonkoh/webaz"],
+      "env": { "WEBAZ_API_KEY": "你的_api_key" }
+    }
+  }
+}
+```
+
+> NETWORK 模式下 `webaz_register` **不自助建号**（账号必须由真人在 webaz.xyz 创建 + 绑 Passkey，这是协议的可问责性要求）。注册以外的交易工具——搜索 / 锁价 / 下单 / 上架 / 履约 / 查单——都直接在共享网络上跑。
 
-**3. 开始使用**
+**C. 开始使用**
 
 在 Claude 对话里说：
 
-> "帮我在 WebAZ 注册一个买家账号，然后搜索一下有什么商品"
+> "帮我在 WebAZ 搜索一下有什么商品，挑性价比高的下单"
 
-Claude 会自动调用 `webaz_register` 和 `webaz_search` 完成操作。
+Claude 会自动调用 `webaz_search` → `webaz_verify_price` → `webaz_place_order` → `webaz_get_status` 完成发现→下单→追踪全流程。
 
 ---
 
@@ -239,6 +268,32 @@ npm run test-manifest# 测试协议 Manifest
 
 ---
 
+## 架构总览 / Architecture map
+
+> 给 AI agent / 新贡献者:不用扫全仓,从下表对应层入手。改代码的 agent 请先读 [`AGENTS.md`](AGENTS.md)。
+> For AI agents / new contributors: don't scan the whole repo — start from the layer your change belongs to. Agents modifying code: read [`AGENTS.md`](AGENTS.md) first.
+
+一套代码两个运行时:**MCP server**(`src/mcp.ts`,给 AI agent)+ **PWA**(`src/pwa/`,给人类)—— 同后端、同规则。
+One codebase, two runtimes: the **MCP server** (for AI agents) and the **PWA** (for humans) share the same backend and rules.
+
+代码分 8 层(`src/layerN-*/`,由底向上依赖)/ Code is layered (`src/layerN-*/`, bottom-up):
+
+| Layer | 它是什么 / What |
+|---|---|
+| `layer0-foundation` | DB schema · 订单**状态机** state-machine · manifest |
+| `layer1-agent` | **MCP server**(`L1-1-mcp-server/server.ts`，最常改)· 身份 / 外部锚点 identity / anchor |
+| `layer2-business` · `layer2-commerce` | 通知 / SNF / anchor registry 等业务 business logic |
+| `layer3-trust` | 争议引擎 dispute engine |
+| `layer4-economics` | 声誉 reputation · 技能市场 skill-market |
+| `layer5-decentralized` · `layer6-scale` | 治理 / 扩展(部分后续阶段)governance / scale (some reserved) |
+
+关键入口 / Key entry files:
+- `src/mcp.ts` → tools 实现在 `src/layer1-agent/L1-1-mcp-server/server.ts`
+- `src/pwa/server.ts` + `src/pwa/routes/` → PWA + HTTP API(人 / agent 共用生产端点)
+- `src/cron-enforcement.ts` → 协议自动判责执行(超时→处置)auto state-machine enforcement
+
+---
+
 ## 当前阶段
 
 **Phase 0 · 概念验证** ✅

package/dist/layer0-foundation/L0-2-state-machine/engine.js

@@ -5,6 +5,9 @@
  * 1. transition()     — 执行状态转移（验证权限 + 记录历史）
  * 2. checkTimeouts()  — 扫描超时订单，自动判责
  * 3. getStatus()      — 查询订单当前状态和责任方
+ *
+ * 关联 / Related: AGENTS.md · 元规则 #1 当一切可见 / #2 代码即规则(状态机=规则的代码化,改这里=改协议行为) ·
+ *   合法转移表见 transitions.ts · 协议级改动审批见 CHARTER §3.2
  */
 import { generateId } from '../L0-1-database/schema.js';
 import { appendOrderEvent } from './order-chain.js';