foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/harness/event_bus.py

@@ -0,0 +1,28 @@
+"""Harness 事件总线（观测优先）。"""
+from typing import Callable
+
+
+class HarnessEventBus:
+    """阶段一：事件总线（观测优先）"""
+
+    _SPINE_SKIP = {"goal_registered"}
+
+    def __init__(self, spine=None, source: str = ""):
+        self._handlers: dict[str, list[Callable]] = {}
+        self._spine = spine
+        self._source = source
+
+    def on(self, event: str, handler: Callable):
+        self._handlers.setdefault(event, []).append(handler)
+
+    def emit(self, event: str, data: dict):
+        for h in self._handlers.get(event, []):
+            try:
+                h(data)
+            except Exception as e:
+                print(f"[Harness EventBus] handler error: {e}")
+        if self._spine is not None and event not in self._SPINE_SKIP:
+            try:
+                self._spine.publish(event, data, source=self._source or "harness")
+            except Exception:
+                pass

package/python/foxclaw/harness/harness.py

@@ -0,0 +1,358 @@
+"""
+Harness — 跨层约束与校准机制
+不是某一层的模块，而是每一层都能感知的治理张力
+
+三个检测维度：
+  1. 语义距离 (semantic)  — 节点内容 vs 目标基线
+  2. 工具意图 (tool)      — 工具类别 vs 允许集合
+  3. 范围蔓延 (scope)     — 当前实体 vs 初始实体集
+
+Shadow mode：前 N 次只观测不截断，用真实数据校准阈值
+"""
+
+
+import os
+import uuid
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from ..core.thought_chain import ThoughtChain, ThoughtNode, HarnessStatus
+
+from ._base import (
+    HarnessResult,
+    GoalBaseline,
+    TOOL_CATEGORIES,
+    _harness_ctx_get,
+    _harness_ctx_set,
+)
+from .drift import SemanticDrift, ToolIntentDrift, ScopeCreepDrift
+from .event_bus import HarnessEventBus
+from ._policy import PolicyMixin
+
+__all__ = [
+    "Harness", "HarnessResult", "GoalBaseline",
+    "SemanticDrift", "ToolIntentDrift", "ScopeCreepDrift",
+    "HarnessEventBus", "TOOL_CATEGORIES",
+]
+
+
+class Harness(PolicyMixin):
+    """
+    Harness 主引擎
+    每个 Agent 实例化一个，共享 ThoughtChain 存储
+    """
+    def __init__(
+        self,
+        agent_id: str,
+        thought_chain: ThoughtChain,
+        policy_path: str = "./foxclaw_data/policy.yaml",
+        shadow_rounds: int = 20,
+        embedding_model: str | None = None,
+        spine=None,
+        promote_min_obs: int | None = None,
+    ):
+        embedding_model = (embedding_model
+                           or os.environ.get("EMBEDDING_MODEL")
+                           or os.environ.get("HKC_EMBEDDING_MODEL")
+                           or os.environ.get("FOXCLAW_EMBEDDING_MODEL")
+                           or "all-MiniLM-L6-v2")
+        self.agent_id = agent_id
+        self.thought_chain = thought_chain
+        self.policy_path = Path(policy_path).resolve()
+        self.shadow_rounds = shadow_rounds
+        self._ctx_token = uuid.uuid4().hex
+        self._lock = threading.RLock()
+
+        self.sem_drift = SemanticDrift(embedding_model)
+        self.tool_drift = ToolIntentDrift()
+        self.scope_drift = ScopeCreepDrift()
+
+        self.bus = HarnessEventBus(spine=spine, source=agent_id)
+
+        self._baseline = None
+
+        self.weights = {"semantic": 0.5, "tool": 0.3, "scope": 0.2}
+
+        self.block_on_semantic = True
+
+        self.semantic_degraded: bool = (self.sem_drift.mode != "transformer")
+        self._degrade_warned: bool = False
+
+        self._shadow_mode = True
+        self._run_count = 0
+        self._delta_history: list[float] = []
+
+        self._warn_threshold = 0.15
+        self._block_threshold = 0.25
+
+        self._policy: dict = self._load_policy()
+        self._policy.setdefault("shadow_rules", [])
+        self._policy.setdefault("history", [])
+
+        if promote_min_obs is not None:
+            self.promote_min_obs = promote_min_obs
+        else:
+            _env = os.environ.get("FOXCLAW_SHADOW_PROMOTE_MIN_OBS", "").strip()
+            self.promote_min_obs = int(_env) if _env.isdigit() else 50
+
+        self._penalized_tools: set[str] = set()
+        self._scope_limit: Optional[int] = None
+        self._reindex_learned_actions()
+
+        self._setup_default_handlers()
+
+    @property
+    def _baseline(self):
+        return _harness_ctx_get(self._ctx_token)
+
+    @_baseline.setter
+    def _baseline(self, value):
+        _harness_ctx_set(self._ctx_token, value)
+
+
+    def register_goal(
+        self,
+        goal_text: str,
+        allowed_tool_categories: set[str],
+        baseline_entities: set[str] | None = None,
+    ) -> GoalBaseline:
+        """接口层调用 — 注册任务目标基线"""
+        baseline = GoalBaseline(
+            goal_text=goal_text,
+            allowed_tool_categories=allowed_tool_categories,
+            baseline_entities=baseline_entities or set(),
+        )
+        baseline.goal_embedding = self.sem_drift.encode(goal_text)
+        self._baseline = baseline
+        self.bus.emit("goal_registered", baseline.to_dict())
+        return baseline
+
+
+    def check(self, node: ThoughtNode, ignore_semantic: bool = False) -> HarnessResult:
+        """
+        对一个 ThoughtNode 做 Harness 校验
+        返回 HarnessResult，并更新节点的 harness_status
+
+        ignore_semantic=True:把语义维度置 0(只按 tool/scope 判定)。用于"工具授权"这类
+        场景 —— 合成的工具调用串对目标句的语义距离是噪声,不该作为拦截依据。默认 False,
+        不影响任何既有调用方的行为。
+
+        【B 类修复】语义嵌入降级时(semantic_degraded=True):语义维度**停用**而非
+        继续参与判定。哈希嵌入无区分度 → 漂移分恒 1.0 → 若继续加权会把所有正常
+        请求一律 BLOCK(fail-closed-with-garbage)。降级方向应为 fail-open:
+        停用不可信维度,保留可信的 tool/scope 判定,并在 reason 显式标注降级
+        (失效但可见)。走 _check_degraded 分支,正常路径逻辑逐字不变。
+        """
+        baseline = self._baseline
+        if baseline is None:
+            result = HarnessResult(
+                status="PASS", delta=0.0, dominant_dim="none",
+                scores={"semantic": 0.0, "tool": 0.0, "scope": 0.0},
+            )
+            self.thought_chain.update_harness(node.id, "PASS")
+            return result
+
+        if self.semantic_degraded and not ignore_semantic:
+            return self._check_degraded(node)
+
+        sem_score = 0.0 if ignore_semantic else \
+            self.sem_drift.score(node.content, baseline.goal_embedding)
+
+        with self._lock:
+            scores = {
+                "semantic": sem_score,
+                "tool": self.tool_drift.score(
+                    node.tool_name or "", baseline.allowed_tool_categories
+                ) if node.tool_name else 0.0,
+                "scope": self.scope_drift.score(
+                    set(node.entities), baseline.baseline_entities),
+            }
+
+            if node.tool_name and self._is_penalized_tool(node.tool_name):
+                scores["tool"] = 1.0
+            if (self._scope_limit is not None and baseline.baseline_entities):
+                new_entities = set(node.entities) - baseline.baseline_entities
+                if len(new_entities) > self._scope_limit:
+                    scores["scope"] = 1.0
+
+            delta = sum(self.weights[k] * v for k, v in scores.items())
+            dominant = max(scores, key=lambda k: scores[k])
+
+            if self._shadow_mode:
+                self._delta_history.append(delta)
+            self._run_count += 1
+
+            if self._shadow_mode and self._run_count >= self.shadow_rounds:
+                self._calibrate_thresholds()
+
+            if self._shadow_mode:
+                status: HarnessStatus = "PASS"
+                reason = None
+            elif delta > self._block_threshold:
+                if not self.block_on_semantic and dominant == "semantic":
+                    status = "WARN"
+                    reason = f"semantic drift Δ={delta:.3f}(调度层仅告警不拦截)"
+                else:
+                    status = "BLOCK"
+                    reason = f"{dominant} drift={scores[dominant]:.3f} Δ={delta:.3f}"
+            elif delta > self._warn_threshold:
+                status = "WARN"
+                reason = f"{dominant} approaching threshold Δ={delta:.3f}"
+            else:
+                status = "PASS"
+                reason = None
+
+            result = HarnessResult(
+                status=status, delta=delta, dominant_dim=dominant,
+                scores=scores, reason=reason,
+            )
+
+            if self._policy.get("shadow_rules"):
+                self._observe_shadow_rules(node, result, scores)
+
+            if status == "BLOCK":
+                self._trigger_policy_learning(node, result)
+
+        self.thought_chain.update_harness(node.id, status, reason, delta, dominant)
+        self.bus.emit(f"harness_{status.lower()}", {
+            "agent_id": self.agent_id, "node_id": node.id, "node_type": node.type,
+            "result": result.__dict__,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        })
+        return result
+
+    def _check_degraded(self, node: ThoughtNode) -> HarnessResult:
+        """语义嵌入降级时的判定:停用语义维度,保留 tool/scope 确定性判定。
+
+        与 check() 的差异**仅在于**:跳过语义嵌入计算(省钱省时)且 semantic 权重
+        按 0 计入。锁内累加/阈值校准/影子学习复用同一套逻辑,保证 shadow 学习与
+        阈值校准行为与正常路径一致(不因降级而产生第二套语义)。
+
+        为何不能只调阈值:无区分度时阈值怎么调都是错的 —— 高阈值漏放跑题,
+        低阈值拦截正常请求。必须**停用该维度**。
+        为何保留 tool/scope:两者是确定性规则(工具类别匹配 / 实体集合运算),
+        不依赖模型质量,降级后仍可信。
+        """
+        baseline = self._baseline
+        if not self._degrade_warned:
+            self._degrade_warned = True
+            import logging as _lg
+            _lg.getLogger("foxclaw.harness").warning(
+                "[harness] 语义嵌入不可用(mode=%s),语义漂移维度已停用 —— "
+                "漂移检测暂退化为 tool/scope 两维,降级期间跑题不会被拦截。"
+                "恢复:pip install sentence-transformers",
+                self.sem_drift.mode)
+
+        with self._lock:
+            saved_w = self.weights.get("semantic", 0.0)
+            self.weights["semantic"] = 0.0
+            try:
+                scores = {
+                    "semantic": 0.0,
+                    "tool": self.tool_drift.score(
+                        node.tool_name or "", baseline.allowed_tool_categories
+                    ) if node.tool_name else 0.0,
+                    "scope": self.scope_drift.score(
+                        set(node.entities), baseline.baseline_entities),
+                }
+                if node.tool_name and self._is_penalized_tool(node.tool_name):
+                    scores["tool"] = 1.0
+                if (self._scope_limit is not None and baseline.baseline_entities):
+                    new_entities = set(node.entities) - baseline.baseline_entities
+                    if len(new_entities) > self._scope_limit:
+                        scores["scope"] = 1.0
+
+                delta = sum(self.weights[k] * v for k, v in scores.items())
+                dominant = max(scores, key=lambda k: scores[k])
+                if self._shadow_mode:
+                    self._delta_history.append(delta)
+                self._run_count += 1
+                if self._shadow_mode and self._run_count >= self.shadow_rounds:
+                    self._calibrate_thresholds()
+
+                if self._shadow_mode:
+                    status: HarnessStatus = "PASS"
+                    reason = None
+                elif delta > self._block_threshold:
+                    status = "BLOCK"
+                    reason = f"{dominant} drift={scores[dominant]:.3f} Δ={delta:.3f}"
+                elif delta > self._warn_threshold:
+                    status = "WARN"
+                    reason = f"{dominant} approaching threshold Δ={delta:.3f}"
+                else:
+                    status = "PASS"
+                    reason = None
+                reason = ((reason + " [semantic-degraded:治理降级]") if reason
+                          else "[semantic-degraded:语义维度停用]")
+            finally:
+                self.weights["semantic"] = saved_w
+
+            result = HarnessResult(
+                status=status, delta=delta, dominant_dim=dominant,
+                scores=scores, reason=reason,
+            )
+            if self._policy.get("shadow_rules"):
+                self._observe_shadow_rules(node, result, scores)
+            if status == "BLOCK":
+                self._trigger_policy_learning(node, result)
+
+        self.thought_chain.update_harness(node.id, status, reason, delta, dominant)
+        self.bus.emit(f"harness_{status.lower()}", {
+            "agent_id": self.agent_id, "node_id": node.id, "node_type": node.type,
+            "result": result.__dict__, "degraded": True,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        })
+        return result
+
+
+    def _setup_default_handlers(self):
+        def on_block(data):
+            from rich.console import Console
+            Console().print(
+                f"[bold red][HARNESS BLOCK][/] agent={data['agent_id']} "
+                f"node={data['node_id']} reason={data['result']['reason']}"
+            )
+
+        def on_policy_updated(data):
+            from rich.console import Console
+            Console().print(
+                f"[bold yellow][POLICY UPDATE][/] agent={data['agent_id']} "
+                f"rule={data['rule_id']} weights={data['new_weights']}"
+            )
+
+        self.bus.on("harness_block", on_block)
+        self.bus.on("policy_updated", on_policy_updated)
+
+
+    @property
+    def is_shadow_mode(self) -> bool:
+        return self._shadow_mode
+
+    @property
+    def thresholds(self) -> dict:
+        return {
+            "warn": self._warn_threshold,
+            "block": self._block_threshold,
+            "shadow_mode": self._shadow_mode,
+            "run_count": self._run_count,
+            "shadow_rounds": self.shadow_rounds,
+            "semantic_degraded": self.semantic_degraded,
+            "embedding_mode": self.sem_drift.mode,
+        }
+
+    def get_policy_summary(self) -> dict:
+        rules = self._policy.get("rules", [])
+        shadow = self._policy.get("shadow_rules", [])
+        return {
+            "version": self._policy.get("version", 1),
+            "total_rules": len(rules),
+            "manual_rules": sum(1 for r in rules if r.get("source") == "manual"),
+            "learned_rules": sum(1 for r in rules if r.get("source") == "harness_learned"),
+            "shadow_observing": sum(1 for r in shadow
+                                    if (r.get("shadow") or {}).get("status") == "observing"),
+            "shadow_total": len(shadow),
+            "history_events": len(self._policy.get("history", [])),
+            "weights": dict(self.weights),
+        }

package/python/foxclaw/harness/loop_detection.py

@@ -0,0 +1,145 @@
+"""
+Foxclaw Harness — 工具循环检测 (Tool-Loop Detection)
+
+借鉴 OpenClaw 的循环检测思路,适配 Foxclaw 的 Harness 体系。
+断路器管"失败",循环检测管"无进展死循环"——Agent 不报错却陷入
+重复/横跳,白烧 token。这是行为异常的一种,与 Harness 漂移检测同源。
+
+三种循环模式:
+  repeat    同一调用(工具+参数签名)连续重复 N 次
+  ping_pong 两个调用交替出现(A→B→A→B)
+  no_progress 同工具反复调用但结果无变化(轮询卡死)
+多级:warning(预警)→ critical(严重)→ 熔断(建议中止)
+"""
+from __future__ import annotations
+import hashlib
+import json
+import threading
+from collections import deque
+from dataclasses import dataclass
+
+
+@dataclass
+class LoopVerdict:
+    stuck: bool = False
+    level: str = "ok"
+    detector: str = ""
+    count: int = 0
+    message: str = ""
+
+    def to_dict(self) -> dict:
+        return {"stuck": self.stuck, "level": self.level,
+                "detector": self.detector, "count": self.count,
+                "message": self.message}
+
+
+@dataclass
+class _ToolCall:
+    signature: str
+    tool_name: str
+    result_hash: str = ""
+
+
+class ToolLoopDetector:
+    """监控工具调用历史,检测无进展死循环。每个 Agent/会话一个实例。"""
+
+    def __init__(self, history_size: int = 30, warning: int = 6,
+                 critical: int = 12, circuit_break: int = 20):
+        self.warning = max(2, warning)
+        self.critical = max(self.warning + 1, critical)
+        self.circuit_break = max(self.critical + 1, circuit_break)
+        self.history: deque = deque(maxlen=max(history_size, self.circuit_break))
+        self._last_verdict: LoopVerdict | None = None
+        self._lock = threading.RLock()
+
+    @staticmethod
+    def _signature(tool_name: str, args: dict) -> str:
+        """工具名 + 规范化参数 → 指纹。"""
+        try:
+            payload = json.dumps(args or {}, sort_keys=True, ensure_ascii=False)
+        except Exception:
+            payload = str(args)
+        return hashlib.sha256(f"{tool_name}::{payload}".encode()).hexdigest()[:16]
+
+    @staticmethod
+    def _result_sig(result) -> str:
+        try:
+            s = json.dumps(result, sort_keys=True, ensure_ascii=False)[:500]
+        except Exception:
+            s = str(result)[:500]
+        return hashlib.sha256(s.encode()).hexdigest()[:16]
+
+    def record(self, tool_name: str, args: dict | None = None, result=None) -> LoopVerdict:
+        """记录一次工具调用并即时检测。返回 LoopVerdict。"""
+        sig = self._signature(tool_name, args or {})
+        rhash = self._result_sig(result) if result is not None else ""
+        with self._lock:
+            self.history.append(_ToolCall(sig, tool_name, rhash))
+            verdict = self._detect()
+            self._last_verdict = verdict
+            return verdict
+
+    def _level_for(self, count: int) -> str:
+        if count >= self.circuit_break:
+            return "critical"
+        if count >= self.critical:
+            return "critical"
+        if count >= self.warning:
+            return "warning"
+        return "ok"
+
+    def _detect(self) -> LoopVerdict:
+        h = list(self.history)
+        if len(h) < self.warning:
+            return LoopVerdict()
+
+        last_sig = h[-1].signature
+        streak = 0
+        for c in reversed(h):
+            if c.signature == last_sig:
+                streak += 1
+            else:
+                break
+        if streak >= self.warning:
+            lvl = self._level_for(streak)
+            streak_calls = h[-streak:]
+            with_result = [c.result_hash for c in streak_calls if c.result_hash]
+            if len(with_result) >= 2 and len(set(with_result)) == 1:
+                return LoopVerdict(
+                    stuck=True, level=lvl, detector="no_progress", count=streak,
+                    message=(f"工具「{h[-1].tool_name}」轮询 {streak} 次结果无变化"
+                             + ("(已达熔断阈值,建议中止)" if streak >= self.circuit_break else "")))
+            return LoopVerdict(
+                stuck=True, level=lvl, detector="repeat", count=streak,
+                message=(f"工具「{h[-1].tool_name}」连续重复调用 {streak} 次"
+                         + ("(已达熔断阈值,建议中止)" if streak >= self.circuit_break else "")))
+
+        if len(h) >= 4:
+            a, b = h[-1].signature, h[-2].signature
+            if a != b:
+                alt = 0
+                expect = [a, b]
+                for i, c in enumerate(reversed(h)):
+                    if c.signature == expect[i % 2]:
+                        alt += 1
+                    else:
+                        break
+                if alt >= self.warning:
+                    return LoopVerdict(
+                        stuck=True, level=self._level_for(alt),
+                        detector="ping_pong", count=alt,
+                        message=(f"工具「{h[-1].tool_name}」与「{h[-2].tool_name}」"
+                                 f"交替横跳 {alt} 次,无进展"))
+
+        return LoopVerdict()
+
+    def should_abort(self) -> bool:
+        """是否建议中止(达到熔断阈值)。复用最近一次 record 的检测结果。"""
+        with self._lock:
+            v = self._last_verdict or self._detect()
+            return v.stuck and v.count >= self.circuit_break
+
+    def reset(self):
+        with self._lock:
+            self.history.clear()
+            self._last_verdict = None

package/python/foxclaw/itinerary/__init__.py

@@ -0,0 +1,10 @@
+"""Foxclaw — Itinerary: 行政 Agent 的行程行为操作系统内核(接高德地图)"""
+from .models import Waypoint, RouteLeg, ItineraryVerdict
+from .reasoning import ItineraryReasoning, MODE_SPEED
+from .amap_client import AMapClient
+from .runtime import ItineraryRuntime
+
+__all__ = [
+    "Waypoint", "RouteLeg", "ItineraryVerdict",
+    "ItineraryReasoning", "MODE_SPEED", "AMapClient", "ItineraryRuntime",
+]

package/python/foxclaw/itinerary/amap_client.py

@@ -0,0 +1,114 @@
+"""
+Foxclaw 行程子系统 — 高德地图适配层
+封装高德 Web Service API。无 API Key 时所有方法降级返回 None,
+行程内核自动回退到纯算法估算(直线距离)。
+本地配置环境变量 AMAP_MAPS_API_KEY 后即接入真实高德数据。
+
+对齐高德 Web Service API 参数格式:
+  - 坐标:经度在前,纬度在后,逗号分隔 "116.397,39.909"
+  - geocode / regeo / route(walking|driving|transit|cycling) / poi / weather
+
+也可改为接官方 MCP server: @amap/amap-maps-mcp-server
+(通过 npx 启动,环境变量同样是 AMAP_MAPS_API_KEY)。
+"""
+
+import os
+import json
+from typing import Optional
+from urllib import request, parse
+
+
+AMAP_BASE = "https://restapi.amap.com/v3"
+
+
+class AMapClient:
+    """高德 Web Service 客户端。无 Key 则 enabled=False,调用返回 None。"""
+
+    def __init__(self, api_key: str | None = None):
+        self.api_key = api_key or os.environ.get("AMAP_MAPS_API_KEY")
+        self.enabled = bool(self.api_key)
+
+    def _get(self, path: str, params: dict) -> Optional[dict]:
+        if not self.enabled:
+            return None
+        params["key"] = self.api_key
+        url = f"{AMAP_BASE}/{path}?{parse.urlencode(params)}"
+        try:
+            with request.urlopen(url, timeout=8) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+            return data if data.get("status") == "1" else None
+        except Exception:
+            return None
+
+    def geocode(self, address: str, city: str = "") -> Optional[tuple]:
+        """地址 → (lng, lat)。"""
+        data = self._get("geocode/geo", {"address": address, "city": city})
+        if data and data.get("geocodes"):
+            loc = data["geocodes"][0]["location"]
+            lng, lat = loc.split(",")
+            return float(lng), float(lat)
+        return None
+
+    def regeo(self, lng: float, lat: float) -> Optional[str]:
+        """坐标 → 地址。"""
+        data = self._get("geocode/regeo", {"location": f"{lng},{lat}"})
+        if data and data.get("regeocode"):
+            return data["regeocode"].get("formatted_address")
+        return None
+
+    def route(self, origin: str, destination: str, mode: str = "driving",
+              city: str = "") -> Optional[dict]:
+        """真实路线。origin/destination 为 'lng,lat'。
+        返回 {distance_km, duration_min}。"""
+        path_map = {
+            "driving": "direction/driving",
+            "walking": "direction/walking",
+            "cycling": "direction/bicycling",
+            "transit": "direction/transit/integrated",
+        }
+        path = path_map.get(mode, "direction/driving")
+        params = {"origin": origin, "destination": destination}
+        if mode == "transit":
+            params["city"] = city
+        data = self._get(path, params)
+        if not data:
+            return None
+        try:
+            route = data["route"]
+            if mode == "transit":
+                seg = route["transits"][0]
+                return {"distance_km": round(int(seg["distance"]) / 1000, 2),
+                        "duration_min": round(int(seg["duration"]) / 60, 1),
+                        "source": "amap"}
+            else:
+                path0 = route["paths"][0]
+                return {"distance_km": round(int(path0["distance"]) / 1000, 2),
+                        "duration_min": round(int(path0["duration"]) / 60, 1),
+                        "source": "amap"}
+        except Exception:
+            return None
+
+    def search_poi(self, keywords: str, city: str = "", offset: int = 10) -> Optional[list]:
+        data = self._get("place/text",
+                         {"keywords": keywords, "city": city, "offset": offset})
+        if data and data.get("pois"):
+            return [{"name": p["name"], "address": p.get("address", ""),
+                     "location": p["location"], "type": p.get("type", "")}
+                    for p in data["pois"]]
+        return None
+
+    def nearby(self, location: str, keywords: str = "", radius: int = 1000) -> Optional[list]:
+        data = self._get("place/around",
+                         {"location": location, "keywords": keywords, "radius": radius})
+        if data and data.get("pois"):
+            return [{"name": p["name"], "address": p.get("address", ""),
+                     "location": p["location"]} for p in data["pois"]]
+        return None
+
+    def weather(self, city: str) -> Optional[dict]:
+        data = self._get("weather/weatherInfo", {"city": city})
+        if data and data.get("lives"):
+            w = data["lives"][0]
+            return {"city": w["city"], "weather": w["weather"],
+                    "temperature": w["temperature"], "wind": w["winddirection"]}
+        return None