zall 0.1.0__py3-none-any.whl

zall/__init__.py

@@ -0,0 +1,8 @@
+"""zall — model-agnostic engineering agent.
+
+Model-agnostic engineering agent. This package MUST NOT import any model SDK;
+Model adapters reside in `zall.adapters`. See IMPL.md IPR-3.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

zall/__main__.py

@@ -0,0 +1,3 @@
+from zall.cli import main
+
+raise SystemExit(main())

zall/_util/__init__.py

@@ -0,0 +1,18 @@
+"""zall._util — 内部共享toolfunction库。
+
+本包为 zall 内部使用的工具函数, 不构成 public API。
+各模块消除重复代码用 (B22/B23/B24 等)。
+"""
+
+from zall._util.file import is_binary, read_text_file
+from zall._util.path import NOISE_DIRS, is_noise, skip_noise_dirs
+from zall._util.string import unquote
+
+__all__ = [
+    "NOISE_DIRS",
+    "is_binary",
+    "is_noise",
+    "read_text_file",
+    "skip_noise_dirs",
+    "unquote",
+]

zall/_util/backoff.py

@@ -0,0 +1,46 @@
+"""zall._util.backoff — 指数抖动退避 (单一真相源)。
+
+G13 (kimi wait_exponential_jitter 对标):
+  此前三处消费点 (core/loop · cli/repl_ui · cli/tui/app) 各自硬编码
+  `delay = attempt * 2` (2s/4s/6s) — 线性退避对慢端点体感僵硬, 且固定值
+  在多客户端同时重试时产生同步惊群 (thundering herd)。
+
+  本版: base = min(initial * 2**(attempt-1), maximum), 再乘均匀抖动
+  [1 - jitter/2, 1 + jitter/2) — 期望值恰为 base (好推理), 打散重试相位。
+  默认 initial=2, maximum=8, jitter=0.5 → attempt 1/2/3 ≈ [1.5,2.5)/[3,5)/[6,10)s。
+
+IPR constraints:
+  IPR-0: tests/test_backoff_invariants.py (含反例)
+  IPR-3: 纯 stdlib
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+
+DEFAULT_INITIAL = 2.0
+DEFAULT_MAXIMUM = 8.0
+DEFAULT_JITTER = 0.5
+
+
+def backoff_delay(
+    attempt: int,
+    *,
+    initial: float = DEFAULT_INITIAL,
+    maximum: float = DEFAULT_MAXIMUM,
+    jitter: float = DEFAULT_JITTER,
+    rng: Callable[[], float] = random.random,
+) -> float:
+    """第 attempt 次 (1-based) 重试的等待秒数: 指数 + 封顶 + 均匀抖动。
+
+    抖动区间以 base 为中心对称 ([base*(1-j/2), base*(1+j/2))),
+    期望值 = base; jitter=0 时退化为确定性指数退避。
+    attempt < 1 按 1 处理 (防御)。
+    """
+    attempt = max(attempt, 1)
+    base = min(initial * (2.0 ** (attempt - 1)), maximum)
+    if jitter <= 0:
+        return base
+    factor = 1.0 - jitter / 2.0 + rng() * jitter
+    return base * factor

zall/_util/file.py

@@ -0,0 +1,118 @@
+"""zall._util.file — File operations共享toolfunction。"""
+
+from __future__ import annotations
+
+import locale
+from pathlib import Path
+
+
+def _preferred_encoding() -> str:
+    """Get the system's preferred encoding (Windows Chinese is GBK/CP936, do not hardcode UTF-8)."""
+    try:
+        enc = locale.getpreferredencoding(False)
+        if enc:
+            return enc
+    except (ValueError, LookupError):
+        pass
+    return "utf-8"  # fallback
+
+
+def detect_text_encoding(path: Path) -> str:
+    """Detect text file encoding: try UTF-8 first, fallback to system preferred encoding.
+
+    Most modern code/text files are UTF-8. On Chinese Windows, the system default is GBK,
+    but opening a UTF-8 file with GBK produces mojibake. This function tries UTF-8 first
+    (strict), and verifies via round-trip to avoid GBK text accidentally passing UTF-8
+    validation (e.g., GBK bytes that happen to form valid UTF-8 sequences).
+
+    Note: the returned encoding should be used WITHOUT errors='replace', because
+    replacement characters (U+FFFD) cannot be encoded in the target encoding
+    (e.g., GBK) when the content is sent to the API pipeline.
+    """
+    raw = b""  # 预初始化: 防 open 失败(如文件不存在)时下方 GBK 回退分支引用未绑定的 raw
+    try:
+        with open(path, "rb") as f:
+            raw = f.read(8192)
+        # Strict UTF-8 decode
+        decoded = raw.decode("utf-8")
+        # Round-trip verification: re-encode must match original bytes exactly
+        # This catches GBK text that happens to be valid UTF-8 (different characters)
+        if decoded.encode("utf-8") == raw:
+            return "utf-8"
+    except (UnicodeDecodeError, OSError):
+        pass
+
+    # Try system encoding (GBK/CP936 on Chinese Windows)
+    sys_enc = _preferred_encoding()
+    if sys_enc.lower() != "utf-8":
+        try:
+            raw.decode(sys_enc)
+            return sys_enc
+        except (UnicodeDecodeError, LookupError):
+            pass
+
+    return "utf-8"  # best-effort fallback
+
+
+def is_binary(path: Path) -> bool:
+    """检测二进制file: 读前 8KB, check空字节。
+
+    失败时返回 True (fail-safe: 二进制文件不读).
+    B23: 统一 grep.py 的 _is_binary 和 read_file.py 的内联检测。
+    """
+    try:
+        with open(path, "rb") as f:
+            chunk = f.read(8192)
+        return b"\0" in chunk
+    except OSError:
+        return True
+
+
+def read_text_file(path: Path, encoding: str | None = None) -> str:
+    """read文本file, 统一exceptionhandle。
+
+    B22: 统一 edit_file.py 和 batch_edit.py 的文件读取逻辑。
+    自动解析相对路径, 检查存在性/类型, 返回文件内容。
+    抛出 OSError 时调用方自行处理。
+    编码默认自动检测: 先尝试 UTF-8, 失败回退系统编码。
+    """
+    # 始终解析相对路径 (修复: 原仅在 encoding=None 时解析, 导致不一致行为)
+    if not path.is_absolute():
+        path = Path.cwd() / path
+    if encoding is None:
+        encoding = detect_text_encoding(path)
+    if not path.exists():
+        raise FileNotFoundError(f"file not found: {path}")
+    if not path.is_file():
+        raise IsADirectoryError(f"not a file: {path}")
+    return path.read_text(encoding=encoding)
+
+
+def atomic_write(path: Path, content: str, encoding: str | None = None) -> Path:
+    """原子writefile — 使用唯一临时file名, 避免 concurrent write竞态。
+
+    v2 fix: 旧实现 path.with_suffix(suffix + ".zall_tmp") 在两个 agent
+    实例同时编辑同一文件时会产生相同临时文件路径, 导致竞态。
+    新实现使用 uuid 生成唯一文件名, 保证并发安全。
+    编码默认 UTF-8 (现代标准, 与 detect_text_encoding 的优先尝试一致)。
+
+    Returns: 临时文件路径 (已被 os.replace 移走, 不再存在)
+    Raises: OSError on write/replace failure (临时文件已清理)
+    """
+    import os
+    import uuid
+    if encoding is None:
+        encoding = "utf-8"
+    tmp_name = f".zall_tmp_{uuid.uuid4().hex[:8]}"
+    tmp = path.parent / tmp_name
+    try:
+        tmp.write_text(content, encoding=encoding)
+        os.replace(str(tmp), str(path))
+    except OSError:
+        try:
+            if tmp.exists():
+                tmp.unlink()
+        except Exception:
+            pass
+        raise
+    return tmp

zall/_util/file_state.py

@@ -0,0 +1,123 @@
+"""File state cache for tracking read file contents and modification state.
+
+缓存每个文件的最后读取时间和 mtime, 支持:
+  - is_file_unchanged(path) — 文件是否在上次读取后未被修改
+  - get_cached_mtime(path) — 获取缓存的 mtime
+  - mark_file_read(path) — 标记文件已读取
+  - invalidate(path) — 使缓存失效
+
+用途: 避免 agent 重复读取未修改的文件, 节省 API token。
+当 agent 调用 read_file 后, 文件状态被缓存; 下次读取前先检查 mtime,
+如果未变化则提示 agent "file unchanged, no need to re-read"。
+
+IPR constraints:
+  IPR-3: stdlib only, no model SDK
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+
+class FileStateCache:
+    """filestatecache — 跟踪file mtime + read时间。
+
+    线程安全: 使用 RLock 保护内部 dict。
+    缓存上限: 1000 条 (LRU 淘汰), 防长会话无界增长。
+    """
+
+    __test__ = False
+
+    _MAX_ENTRIES = 1000
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        # key: str(path), value: {"mtime": float, "read_at": float, "size": int}
+        self._cache: dict[str, dict[str, Any]] = {}
+
+    def mark_file_read(self, path: Path | str) -> None:
+        """标记file已read, cache其 mtime 和 size。"""
+        key = str(path)
+        try:
+            stat = Path(path).stat()
+            mtime = stat.st_mtime
+            size = stat.st_size
+        except OSError:
+            return
+        with self._lock:
+            # LRU 淘汰
+            if len(self._cache) >= self._MAX_ENTRIES:
+                # 淘汰最旧的条目
+                oldest_key = min(self._cache, key=lambda k: self._cache[k].get("read_at", 0))
+                self._cache.pop(oldest_key, None)
+            self._cache[key] = {"mtime": mtime, "read_at": time.time(), "size": size}
+
+    def is_file_unchanged(self, path: Path | str) -> bool:
+        """checkfile是否在上次read后未被修改。
+
+        Returns:
+            True — 文件未修改 (可以跳过重复读取)
+            False — 文件已修改或未被缓存过 (需要重新读取)
+        """
+        key = str(path)
+        with self._lock:
+            cached = self._cache.get(key)
+        if cached is None:
+            return False
+        try:
+            current_mtime = Path(path).stat().st_mtime
+        except OSError:
+            return False
+        return bool(cached["mtime"] == current_mtime)
+
+    def get_cached_mtime(self, path: Path | str) -> float | None:
+        """获取cache的 mtime (不读盘)。"""
+        key = str(path)
+        with self._lock:
+            entry = self._cache.get(key)
+            return entry["mtime"] if entry else None
+
+    def invalidate(self, path: Path | str | None = None) -> None:
+        """使cache失效。path=None 时清除全部cache。"""
+        with self._lock:
+            if path is None:
+                self._cache.clear()
+            else:
+                self._cache.pop(str(path), None)
+
+    def get_changed_files(self) -> list[str]:
+        """return自上次read以来被修改的filelist (供 /doctor 用)。"""
+        changed = []
+        with self._lock:
+            for key, entry in self._cache.items():
+                try:
+                    current_mtime = Path(key).stat().st_mtime
+                    if current_mtime != entry["mtime"]:
+                        changed.append(key)
+                except OSError:
+                    changed.append(key)  # 文件被删除也算变更
+        return changed
+
+    @property
+    def size(self) -> int:
+        """当前cache条目数。"""
+        with self._lock:
+            return len(self._cache)
+
+
+# 全局singleton (process级)
+_global_cache: FileStateCache | None = None
+_global_lock = threading.Lock()
+
+
+def get_file_state_cache() -> FileStateCache:
+    """获取全局 FileStateCache singleton。"""
+    global _global_cache
+    if _global_cache is None:
+        with _global_lock:
+            if _global_cache is None:
+                _global_cache = FileStateCache()
+    return _global_cache

zall/_util/hash_utils.py

@@ -0,0 +1,110 @@
+"""zall._util.hash_utils - 真实文件 SHA-256 哈希工具 (E3 Science Kit 诚实化).
+
+Part D (真溯源): ScienceProvenance 的四个 hash 字段此前是硬编码占位符
+("sha256:cli-manual" / "sha256:agent"), 无任何代码对真实文件算哈希。本模块
+提供真实文件哈希能力, 使实验溯源从"声明"变为"可验证事实"。
+
+对应:
+  docs/E3_SCIENCE_KIT.md §2.4  ScienceProvenance - protocol/data/code/env 完整血缘
+  MASTER.md §10 I-10          负结果平等 (真实溯源同样适用于负结果)
+
+IPR constraints:
+  IPR-3: stdlib only (hashlib/pathlib), no model SDK. _util 是 stdlib-only 区。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+# 哈希前缀, 与 ScienceProvenance 字段约定一致 (如 "sha256:<hex>")
+_HASH_PREFIX = "sha256:"
+_CHUNK_SIZE = 1 << 16  # 64 KiB 读块, 大文件不爆内存
+
+
+def hash_file(path: str | Path) -> str:
+    """计算单个文件的 SHA-256, 返回 "sha256:<hex>" 格式。
+
+    文件不存在或不可读时抛 OSError (调用方决定降级策略)。
+    """
+    p = Path(path)
+    h = hashlib.sha256()
+    with p.open("rb") as f:
+        while True:
+            chunk = f.read(_CHUNK_SIZE)
+            if not chunk:
+                break
+            h.update(chunk)
+    return _HASH_PREFIX + h.hexdigest()
+
+
+def hash_bytes(data: bytes) -> str:
+    """计算字节内容的 SHA-256, 返回 "sha256:<hex>" 格式。"""
+    return _HASH_PREFIX + hashlib.sha256(data).hexdigest()
+
+
+def hash_files(paths: list[str | Path]) -> str:
+    """计算多个文件的聚合 SHA-256 (顺序无关: 先排序再聚合)。
+
+    聚合策略: 对每个文件取 (相对名, sha256) 后排序, 再对拼接串算总哈希。
+    顺序无关保证: 同一组文件无论传入顺序如何, 聚合哈希一致。
+    返回 "sha256:<hex>" 格式。
+    """
+    entries: list[tuple[str, str]] = []
+    for path in paths:
+        p = Path(path)
+        digest = hash_file(p).removeprefix(_HASH_PREFIX)
+        entries.append((p.name, digest))
+    entries.sort(key=lambda e: e[0])
+    joined = "\n".join(f"{name}\t{digest}" for name, digest in entries)
+    return _HASH_PREFIX + hashlib.sha256(joined.encode("utf-8")).hexdigest()
+
+
+def hash_dir(path: str | Path, *, pattern: str = "*") -> str:
+    """计算目录下所有匹配文件的聚合 SHA-256 (环境快照用)。
+
+    递归遍历目录, 对匹配 pattern 的文件聚合哈希 (排序保证顺序无关)。
+    用于 ScienceProvenance.environment_hash (如 requirements.txt + python version)。
+    返回 "sha256:<hex>" 格式。空目录返回对空串的哈希。
+    """
+    import fnmatch
+
+    p = Path(path)
+    if not p.is_dir():
+        return hash_bytes(b"")
+    entries: list[tuple[str, str]] = []
+    for root, _dirs, files in os.walk(p):
+        for fn in files:
+            if not fnmatch.fnmatch(fn, pattern) and pattern != "*":
+                continue
+            fp = Path(root) / fn
+            try:
+                digest = hash_file(fp).removeprefix(_HASH_PREFIX)
+                # 用相对路径作名, 保证目录迁移后哈希稳定
+                rel = fp.relative_to(p).as_posix()
+                entries.append((rel, digest))
+            except OSError:
+                continue  # 跳过不可读文件 (如权限/锁), 不让环境快照失败
+    entries.sort(key=lambda e: e[0])
+    joined = "\n".join(f"{name}\t{digest}" for name, digest in entries)
+    return _HASH_PREFIX + hashlib.sha256(joined.encode("utf-8")).hexdigest()
+
+
+def environment_hash(extra: str = "") -> str:
+    """计算运行环境快照哈希 (python 版本 + 关键库版本 + 可选附加串)。
+
+    用于 ScienceProvenance.environment_hash: 捕获 (python 版本, sys.platform,
+    可选的 requirements 摘要), 使实验环境可溯源。
+    返回 "sha256:<hex>" 格式。
+    """
+    import sys
+    parts = [
+        f"python={sys.version.split()[0]}",
+        f"platform={sys.platform}",
+        f"executable={sys.executable}",
+    ]
+    if extra:
+        parts.append(extra)
+    joined = "\n".join(parts)
+    return _HASH_PREFIX + hashlib.sha256(joined.encode("utf-8")).hexdigest()

zall/_util/jsonl.py

@@ -0,0 +1,85 @@
+"""zall._util.jsonl — JSONL 版本头与坏行容错读取 (单一真相源)。
+
+G12 (kimi context.jsonl `_` 特殊行 / wire.jsonl 首行 protocol_version 对标):
+  timeline.jsonl 首行写 metadata 版本头 {"type":"metadata","version":1,...} —
+  无版本头的旧文件视为 legacy 正常读 (向后兼容);
+  读取循环坏行 skip 不再一坏全弃 (此前 _load_timeline_events 任一行
+  JSONDecodeError 会整个返回 None, 丢掉全部可读事件)。
+
+IPR constraints:
+  IPR-0: tests/test_jsonl_header_invariants.py (含反例)
+  IPR-3: 纯 stdlib
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+METADATA_TYPE = "metadata"
+TIMELINE_VERSION = 1
+
+
+def make_metadata(**fields: Any) -> dict[str, Any]:
+    """构造版本头记录 (首行)。fields 覆盖默认键之外的补充信息。"""
+    rec: dict[str, Any] = {"type": METADATA_TYPE, "version": TIMELINE_VERSION}
+    rec.update(fields)
+    return rec
+
+
+def is_metadata(record: dict[str, Any]) -> bool:
+    return isinstance(record, dict) and record.get("type") == METADATA_TYPE
+
+
+def read_jsonl(
+    path: str | Path,
+    *,
+    skip_metadata: bool = True,
+) -> list[dict[str, Any]] | None:
+    """读取 JSONL: 文件不存在/不可读 → None; 坏行 skip (不一坏全弃)。
+
+    skip_metadata=True 时过滤版本头行 — 消费方拿到的纯是数据记录,
+    legacy 文件 (无版本头) 行为完全一致。
+    """
+    p = Path(path)
+    if not p.exists():
+        return None
+    try:
+        text = p.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    records: list[dict[str, Any]] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except json.JSONDecodeError:
+            continue  # 坏行 skip: 保住其余可读记录
+        if not isinstance(rec, dict):
+            continue
+        if skip_metadata and is_metadata(rec):
+            continue
+        records.append(rec)
+    return records
+
+
+def read_metadata(path: str | Path) -> dict[str, Any] | None:
+    """读首行版本头; 无版本头 (legacy) / 文件不存在 → None。"""
+    p = Path(path)
+    if not p.exists():
+        return None
+    try:
+        with open(p, encoding="utf-8") as f:
+            first = f.readline().strip()
+    except OSError:
+        return None
+    if not first:
+        return None
+    try:
+        rec = json.loads(first)
+    except json.JSONDecodeError:
+        return None
+    return rec if is_metadata(rec) else None

zall/_util/logging.py

@@ -0,0 +1,130 @@
+"""zall._util.logging — Unified logging configuration (IPR-0: self-falsifiable errors).
+
+Inspired by Grok Build's xai-tracing crate: structured, contextual logging that
+makes non-fatal errors observable without changing control flow.
+
+Design:
+  - Single entry point: get_zall_logger(__name__) → standard library logger
+  - ZALL_LOG_LEVEL env var controls verbosity (default: WARNING)
+  - IPR-0 invariant: observer/renderer errors are swallowed but LOGGED
+    (silent pass → violates falsifiability; logged pass → observable)
+
+Usage:
+    from zall._util.logging import get_zall_logger
+    logger = get_zall_logger(__name__)
+    ...
+    except Exception as e:
+        logger.warning("operation failed: %s", e)  # observable, non-fatal
+
+Corresponds to:
+  §0     PR-0: self-falsifiability — silent errors are unfalsifiable
+  IPR-0  Self-falsifiability code form — errors must be observable
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import TextIO
+
+# ── Defaults ──
+
+_DEFAULT_LEVEL = logging.WARNING
+_ENV_VAR = "ZALL_LOG_LEVEL"
+
+# Level name → int mapping for env var parsing
+_LEVEL_NAMES: dict[str, int] = {
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+
+
+def _resolve_level() -> int:
+    """Resolve log level from environment or default."""
+    raw = os.environ.get(_ENV_VAR, "").strip().upper()
+    if raw in _LEVEL_NAMES:
+        return _LEVEL_NAMES[raw]
+    if raw and raw.isdigit():
+        return int(raw)
+    return _DEFAULT_LEVEL
+
+
+# ── Formatter ──
+
+_FORMAT = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+_FORMAT_DATE = "%H:%M:%S"
+
+
+def _make_handler(stream: TextIO = sys.stderr) -> logging.Handler:
+    """Create a stderr handler with the standard format."""
+    handler = logging.StreamHandler(stream)
+    handler.setFormatter(logging.Formatter(_FORMAT, _FORMAT_DATE))
+    return handler
+
+
+# ── Global state (lazy-initialized) ──
+
+_initialized = False
+
+
+def setup_logging(
+    *,
+    level: int | None = None,
+    stream: TextIO | None = None,
+    force: bool = False,
+) -> None:
+    """Configure the root zall logger.
+
+    Called once at process start (from main/REPL). Safe to call multiple
+    times — subsequent calls are no-ops unless *force=True*.
+
+    Args:
+        level: Log level (default: from ZALL_LOG_LEVEL env, or WARNING).
+        stream: Output stream (default: sys.stderr).
+        force: Reconfigure even if already initialized.
+    """
+    global _initialized
+    if _initialized and not force:
+        return
+
+    root = logging.getLogger("zall")
+    root.setLevel(level if level is not None else _resolve_level())
+
+    # Remove existing handlers to avoid duplicates on force re-init
+    if force:
+        root.handlers.clear()
+
+    if not root.handlers:
+        root.addHandler(_make_handler(stream or sys.stderr))
+
+    _initialized = True
+
+
+def get_zall_logger(name: str) -> logging.Logger:
+    """Get a zall-namespaced logger.
+
+    Usage:
+        logger = get_zall_logger(__name__)
+        logger.warning("non-fatal issue: %s", detail)
+
+    The logger name is prefixed with 'zall.' to keep it under the
+    zall root logger's level configuration.
+    """
+    # Strip leading 'zall.' if already present to avoid 'zall.zall...'
+    if name.startswith("zall."):
+        logger_name = name
+    elif name.startswith("zall"):
+        logger_name = f"zall.{name}"
+    else:
+        logger_name = f"zall.{name}"
+
+    return logging.getLogger(logger_name)
+
+
+def get_log_level() -> int:
+    """Return the current effective log level for the zall root logger."""
+    return logging.getLogger("zall").level