foxclaw 0.1.0 → 0.1.3

package/python/tools/restart_foxclaw.ps1

@@ -0,0 +1,71 @@
+$ErrorActionPreference = "Continue"
+
+$root = Split-Path -Parent $PSScriptRoot
+
+$py = Join-Path $root ".venv\Scripts\python.exe"
+if (-not (Test-Path $py)) {
+    Write-Host "[1] WARN: .venv missing, fallback to PATH python (see README quick start)"
+    $py = (Get-Command python -ErrorAction SilentlyContinue).Source
+}
+if (-not $py) { $py = "python" }
+Write-Host "[1] python = $py"
+
+Write-Host "[2] Find LISTENING on :8000"
+$targetPid = $null
+$netstatLines = netstat -ano | Select-String ":8000"
+foreach ($line in $netstatLines) {
+    $s = $line.ToString()
+    if ($s -match 'LISTENING\s+(\d+)$') {
+        $targetPid = $Matches[1]
+        break
+    }
+}
+
+if ($targetPid) {
+    Write-Host "  -> Kill PID $targetPid"
+    taskkill /F /PID $targetPid | Out-Null
+    Start-Sleep -Seconds 2
+} else {
+    Write-Host "  -> No LISTEN on :8000 (may already be down)"
+}
+
+$logDir = Join-Path $root "foxclaw_data"
+if (-not (Test-Path $logDir)) { New-Item -ItemType Directory -Path $logDir | Out-Null }
+$outLog = Join-Path $logDir "uvicorn.log"
+$errLog = Join-Path $logDir "uvicorn.err.log"
+"" | Out-File -FilePath $outLog -Encoding utf8
+"" | Out-File -FilePath $errLog -Encoding utf8
+Write-Host "[3] Start service (hidden window, --reload)"
+Write-Host "    stdout -> $outLog"
+Write-Host "    stderr -> $errLog"
+$uviArgs = @(
+    "-m", "uvicorn", "foxclaw.api:app",
+    "--port", "8000",
+    "--reload",
+    "--reload-dir", (Join-Path $root "foxclaw")
+)
+Start-Process $py -ArgumentList $uviArgs `
+    -WorkingDirectory $root `
+    -WindowStyle Hidden `
+    -RedirectStandardOutput $outLog `
+    -RedirectStandardError  $errLog | Out-Null
+Write-Host "  -> Started, polling /stats up to 30s"
+
+$ready = $false
+for ($i=0; $i -lt 15; $i++) {
+    try {
+        $s = Invoke-RestMethod http://127.0.0.1:8000/stats -TimeoutSec 2 -UseBasicParsing
+        if ($s) {
+            $ready = $true
+            Write-Host ("[4] OK: vector_size={0} bm25={1} state={2} old_pid={3}" -f `
+                $s.vector_size, $s.bm25_size, $s.index_build.index_state, $targetPid)
+            break
+        }
+    } catch {}
+    Start-Sleep -Seconds 2
+}
+
+if (-not $ready) {
+    Write-Host "[4] FAIL: service did not respond in 30s"
+    exit 1
+}

package/python/tools/shared_write_audit.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""P0-3 共享层写入策略 —— 端到端验收工具
+
+它解决什么问题
+--------------
+P0-3 定义了「谁能往共享层写什么」的策略表(foxclaw/core/shared_write.py),但它默认跑在
+audit 模式 —— 只记录、不拦截。切到 enforce 之前必须先回答一个问题:
+
+    这份策略表在**真实调用路径**上,到底会不会误判?
+
+单测(tests/test_shared_write.py)用 Mock 后端验证了策略函数本身;本工具补的是端到端
+那一层:走**真实 Foxclaw 装配**(真实 HMRAdapter + 真实 EventSpine + 真实 Agent),
+用 8 处**真实写入点的原样参数**跑一遍,确认零误伤;再用越界探针确认真的拦得住。
+
+用法
+----
+  python tools/shared_write_audit.py                 # 验收(默认 audit 模式)
+  python tools/shared_write_audit.py --mode enforce  # 验证 enforce 的拦截与放行
+  python tools/shared_write_audit.py --keep          # 保留临时数据目录(排查用)
+
+退出码:0 = 全部符合预期;1 = 有偏离(详见输出)
+
+数据安全:默认在临时目录建实例,不碰 ./foxclaw_data;不加载项目 .env(本工具不 import
+foxclaw.api,而 load_dotenv 只发生在那里)。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+os.environ.setdefault("HKC_EMBEDDING", "stub")
+
+for _s in (sys.stdout, sys.stderr):
+    try:
+        _s.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+_FAILS: list[str] = []
+_TOTAL = 0
+
+
+def check(cond: bool, msg: str) -> bool:
+    global _TOTAL
+    _TOTAL += 1
+    print(f"  {'✓' if cond else '✗'} {msg}")
+    if not cond:
+        _FAILS.append(msg)
+    return bool(cond)
+
+
+_WHO_ANY = ("supervisor", "finance", "office", "admin", "assistant")
+LEGITIMATE = [
+    ("supervisor", "decision",    ["dispatch", "multi_step", "to:finance"], "多步记录", "主管多步分发"),
+    ("supervisor", "decision",    ["dispatch", "parallel", "to:office"],    "并行记录", "主管并行分发"),
+    ("supervisor", "decision",    [],                                      "主管介绍", "主管自答(元问题)"),
+    ("supervisor", "decision",    [],                                      "主管自答", "主管自答(正面对话)"),
+    ("supervisor", "decision",    ["dispatch", "to:finance"],              "调度记录", "主管单步调度"),
+    ("supervisor", "decision",    [],                                      "主管处理", "主管兜底自处理"),
+    ("__ANY__",    "preference",  ["preference"],                          "用户偏好", "偏好固化(任一 Agent)"),
+    ("system",     "execution",   ["truth_pipeline"],                      "真值",     "真值管线沉淀"),
+]
+
+INTRUSIONS = [
+    ("office",    "decision", ["finance.transfer"], "财务应给办公转账1000元", "办公→财务职责域"),
+    ("office",    "decision", ["itinerary.plan"],   "把周三会议改到周五",     "办公→行政职责域"),
+    ("assistant", "decision", ["dispatch"],         "任务已派发给财务",       "助手冒充主管分发"),
+    ("finance",   "concept",  ["learning.notes"],   "RAG 学习笔记",           "财务→办公学习域"),
+    ("stranger",  "decision", ["misc"],             "未登记写入方",           "未登记 Agent"),
+]
+
+
+def _emit(hmr, agent_id, mem_type, tags, content):
+    """按真实路径发起一次共享层写入(_store_memory 最终就是 ingest)。"""
+    hmr.ingest(content, type=mem_type, agent_id=agent_id, tags=tags, shared=True)
+
+
+def audit_case(hmr, agent_id, mem_type, tags, content,
+               expect_allowed: bool) -> None:
+    """跑一笔写入,断言判定与预期一致 —— 从**真链路**上取判定,不直接调 policy。
+
+    判定来源是审计事件(audit/warn 不拦截,只能从事件读 allowed;enforce 下被抛异常
+    同样以 allowed=False 记在事件里)。按事件数**增量**取本次那条,避免某次写入未产生
+    事件时误读上一次的结果 —— 那会让该断言变成"永远通过"的假断言。
+    """
+    from foxclaw.core.shared_write import SharedWriteDenied
+    spine = hmr.shared_write_spine
+    before = len(spine.history("memory.shared.write", 100000))
+    try:
+        _emit(hmr, agent_id, mem_type, tags, content)
+        denied = False
+    except SharedWriteDenied:
+        denied = True
+    new = spine.history("memory.shared.write", 100000)[before:]
+    got = None if not new else new[-1]["payload"]["allowed"]
+    if denied:
+        got = False
+    check(got == expect_allowed,
+          f"{agent_id:<10} type={mem_type:<10} tags={tags or '[]'} → "
+          f"{'允许' if got else '拒绝'}(预期{'允许' if expect_allowed else '拒绝'})")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="P0-3 共享层写入策略端到端验收")
+    ap.add_argument("--mode", choices=["audit", "warn", "enforce"], default="audit",
+                    help="策略模式(默认 audit)。enforce 会真拦截,用于验证拦截行为")
+    ap.add_argument("--keep", action="store_true", help="保留临时数据目录")
+    args = ap.parse_args()
+
+    os.environ["FOXCLAW_SHARED_WRITE_MODE"] = args.mode
+    data_dir = tempfile.mkdtemp(prefix="foxclaw_swa_")
+
+    print("=" * 66)
+    print(f"P0-3 共享层写入策略 · 端到端验收   [模式={args.mode}]")
+    print("=" * 66)
+
+    try:
+        from foxclaw import Foxclaw
+        osi = Foxclaw(data_dir=data_dir, shadow_rounds=5)
+
+        print("\n【1】装配自检")
+        pol = getattr(osi.hmr, "shared_write_policy", None)
+        spine = getattr(osi.hmr, "shared_write_spine", None)
+        check(pol is not None, "策略已挂到记忆后端 (hmr.shared_write_policy)")
+        check(spine is not None, "审计出口已挂 (hmr.shared_write_spine)")
+        check(pol is not None and pol.mode == args.mode,
+              f"生效模式 = {getattr(pol, 'mode', None)!r}(预期 {args.mode!r})")
+        check(spine is osi.event_spine,
+              "审计出口指向全系统唯一脊柱(与 /api/bus/history 同源)")
+        if _FAILS:
+            print("\n装配不完整,后续验收无意义。中止。")
+            return 1
+
+        print("\n【2】真实写入点零误伤(8 处调用点的原样参数)")
+        for agent_id, mem_type, tags, title, why in LEGITIMATE:
+            if agent_id == "__ANY__":
+                for who in _WHO_ANY:
+                    audit_case(osi.hmr, who, mem_type, tags, f"{title}:示例内容", True)
+                continue
+            audit_case(osi.hmr, agent_id, mem_type, tags, f"{title}:示例内容", True)
+
+        print("\n【3】越界探针(跨 Agent 注入通道)")
+        for agent_id, mem_type, tags, content, why in INTRUSIONS:
+            audit_case(osi.hmr, agent_id, mem_type, tags, content, False)
+
+        print("\n【4】审计事件汇总(等价于 /api/bus/history?channel=memory.shared.write)")
+        evs = osi.event_spine.history("memory.shared.write", 500)
+        allowed_n = sum(1 for e in evs if e["payload"]["allowed"])
+        denied_n = len(evs) - allowed_n
+        print(f"  共 {len(evs)} 条:允许 {allowed_n} / 拒绝 {denied_n}")
+        for e in evs:
+            p = e["payload"]
+            tag = "OK  " if p["allowed"] else "DENY"
+            print(f"    {tag} {p['agent_id']:<10} {p['type']:<10} "
+                  f"sha={p['content_sha']}  {p['reason']}")
+        check(len(evs) > 0, "审计事件确实产生(链路口径通)")
+
+        print("\n" + "=" * 66)
+        if _FAILS:
+            print(f"✗ 验收未通过:{len(_FAILS)}/{_TOTAL} 项偏离预期")
+            for f in _FAILS:
+                print(f"    - {f}")
+            print("\n切 enforce 前必须先修正上述偏离,否则会误伤正常链路。")
+            return 1
+        print(f"✓ 验收通过:{_TOTAL}/{_TOTAL} 项符合预期")
+        if args.mode != "enforce":
+            print("\n下一步(灰度推进):")
+            print("  ① 先切 warn 观察真实流量:  FOXCLAW_SHARED_WRITE_MODE=warn")
+            print("     —— 越界写入会被打出告警,但**不拦截**,不影响任何现有功能。")
+            print("  ② 观察期内查审计事件,逐条判读有无「合法的被拒」:")
+            print("     curl -H \"X-API-Key: $FOXCLAW_API_KEY\" \\")
+            print("       'http://127.0.0.1:8000/api/bus/history?channel=memory.shared.write&limit=200'")
+            print("  ③ 确认零误伤后再切实拦截:  FOXCLAW_SHARED_WRITE_MODE=enforce")
+        return 0
+    finally:
+        if args.keep:
+            print(f"\n[数据目录保留] {data_dir}")
+        else:
+            shutil.rmtree(data_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/python/tools/size_baseline.txt

@@ -0,0 +1,28 @@
+# 单文件体积棘轮基线:列此处的文件已超 15KB,允许存在但不得再增长;
+# 拆到 <=15KB 后运行 `python tools/size_check.py --update` 自动移出。
+# 2026-11-09 冻结时共 25 个。
+foxclaw/core/model_router.py
+foxclaw/agents/base.py
+foxclaw/agents/impl/supervisor.py
+foxclaw/skills/__init__.py
+foxclaw/__init__.py
+foxclaw/finance/nlparse.py
+foxclaw/pipeline/cognitive_pipeline.py
+foxclaw/finance/runtime.py
+foxclaw/core/memory_adapter.py
+foxclaw/core/vec_recall_adapter.py
+foxclaw/harness/harness.py
+foxclaw/core/settings.py
+foxclaw/agents/mixins/tool_exec.py
+foxclaw/kernel/sentinel.py
+foxclaw/api/routes/llm_admin.py
+foxclaw/harness/_policy.py
+foxclaw/api/routes/ahs.py
+foxclaw/finance/reasoning.py
+foxclaw/skills/pipeline.py
+foxclaw/agents/impl/office.py
+foxclaw/learning/runtime.py
+foxclaw/knowledge/__init__.py
+foxclaw/core/recovery.py
+foxclaw/core/tracing.py
+foxclaw/finance/policy.py

package/python/tools/size_check.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""单文件体积棘轮门: foxclaw/**/*.py 不得超过 15KB。
+
+为什么需要
+----------
+REFACTOR_PLAN 要求单文件 <= 15KB(便于 LLM 整体读写、降低 diff 冲突面),
+但 2026-11 实测有 25 个文件超限,最大 foxclaw/core/model_router.py 58KB ——
+计划里没有执行机制,所以"要求"一直没落地。
+
+一次性拆 25 个文件是高风险的伪重构(82 个测试虽能兜底,但收益/风险不成比例)。
+本脚本采用棘轮:现有超限文件进白名单冻结,**新增超限立即失败**,已拆小的从白名单
+自动移出 —— 债务不再增长,同时每轮有机会顺手拆一个。
+
+用法
+----
+    python tools/size_check.py            # CI:校验
+    python tools/size_check.py --update   # 只允许把已合规的路径移出白名单
+    python tools/size_check.py --list     # 打印当前超限清单
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+TARGET = ROOT / "foxclaw"
+BASELINE = ROOT / "tools" / "size_baseline.txt"
+LIMIT = 15 * 1024
+
+for _s in (sys.stdout, sys.stderr):
+    try:
+        _s.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    except Exception:
+        pass
+
+
+def rel(p: Path) -> str:
+    return p.relative_to(ROOT).as_posix()
+
+
+def scan() -> dict[str, int]:
+    return {rel(p): p.stat().st_size for p in TARGET.rglob("*.py") if p.stat().st_size > LIMIT}
+
+
+def read_baseline() -> set[str]:
+    if not BASELINE.exists():
+        return set()
+    return {
+        line.strip() for line in BASELINE.read_text(encoding="utf-8").splitlines()
+        if line.strip() and not line.startswith("#")
+    }
+
+
+def main() -> int:
+    argv = sys.argv[1:]
+    over = scan()
+
+    if "--list" in argv:
+        for path, size in sorted(over.items(), key=lambda kv: -kv[1]):
+            print(f"{size / 1024:7.1f}KB  {path}")
+        print(f"共 {len(over)} 个文件超过 {LIMIT // 1024}KB")
+        return 0
+
+    allowed = read_baseline()
+    if "--update" in argv:
+        new = sorted(set(over) - allowed)
+        if new:
+            print("✗ 拒绝更新白名单:以下文件是新超限的,必须拆分而不是加进白名单:")
+            for path in new:
+                print(f"    {over[path] / 1024:7.1f}KB  {path}")
+            return 1
+        kept = sorted(set(over) & allowed)
+        BASELINE.write_text(
+            "# 单文件体积棘轮基线:列此处的文件已超 15KB,允许存在但不得再增长;\n"
+            "# 拆到 <=15KB 后运行 `python tools/size_check.py --update` 自动移出。\n"
+            + "".join(f"{p}\n" for p in kept),
+            encoding="utf-8",
+        )
+        print(f"✓ 白名单已更新为 {len(kept)} 项")
+        return 0
+
+    new = sorted(set(over) - allowed)
+    shrunk = sorted(allowed - set(over))
+
+    if shrunk:
+        print(f"ℹ 以下 {len(shrunk)} 个文件已降到 {LIMIT // 1024}KB 以内,可从白名单移出"
+              f"(运行 --update):")
+        for path in shrunk:
+            print(f"    {path}")
+
+    if new:
+        print(f"✗ {len(new)} 个新文件超过 {LIMIT // 1024}KB,必须拆分:")
+        for path in new:
+            print(f"    {over[path] / 1024:7.1f}KB  {path}")
+        return 1
+
+    print(f"✓ 通过:超限文件 {len(over)} 个,均在冻结白名单内(未新增)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/tools/strip_comments.py

@@ -0,0 +1,228 @@
+"""剥离代码里的解释性注释。
+
+用法:
+    python tools/strip_comments.py --dry          只统计,不改文件
+    python tools/strip_comments.py                真正改写
+    python tools/strip_comments.py a.py b.js      只处理指定文件
+
+不能一刀切:下面这些注释被删会改变 lint / 类型检查 / 解释器行为,必须原样保留。
+    #!...                shebang
+    # -*- coding -*-     编码声明
+    # noqa ...           ruff 抑制
+    # type: ...          mypy 注解(含 `x = []  # type: list[int]`)
+    # pragma / fmt: / isort: / pyright: / pylint: / nosec / coverage:
+docstring 不动 —— 它是运行时对象,不是注释。
+
+vendor/ 是内嵌第三方,不改;frontend/v3 是构建产物,由 vite 重新生成。
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import sys
+import tokenize
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+SKIP_PARTS = {".git", "node_modules", "__pycache__", ".venv", "venv", "vendor",
+              "foxclaw_data", "test_data", ".pytest_cache", ".ruff_cache", ".mypy_cache",
+              "build", "dist", "htmlcov"}
+# 生成副本:npm/python 由 npm/build.cjs 从仓库根复制,frontend/v3 由 vite 构建
+SKIP_PREFIX = {"frontend/v3/", "npm/python/"}
+EXTS = {".py", ".js", ".vue", ".ps1"}
+
+DIRECTIVE = re.compile(
+    r"^#\s*(?:!|-\*-|noqa|type:|pragma|fmt:|isort:|pyright:|pylint:|ruff:|nosec|"
+    r"coverage:|mypy:|noinspection|coding[:=])",
+    re.I,
+)
+
+MAX_BLANK = 2
+
+
+def targets() -> list[Path]:
+    out = []
+    for p in ROOT.rglob("*"):
+        if p.suffix not in EXTS or not p.is_file():
+            continue
+        rel = p.relative_to(ROOT).as_posix()
+        if SKIP_PARTS & set(p.relative_to(ROOT).parts):
+            continue
+        if any(rel.startswith(x) for x in SKIP_PREFIX):
+            continue
+        if rel == "tools/strip_comments.py":
+            continue
+        out.append(p)
+    return sorted(out)
+
+
+def collapse_blank(lines: list[str], limit: int = MAX_BLANK) -> list[str]:
+    out: list[str] = []
+    run = 0
+    for ln in lines:
+        if ln.strip() == "":
+            run += 1
+            if run > limit:
+                continue
+        else:
+            run = 0
+        out.append(ln)
+    return out
+
+
+def strip_py(text: str) -> tuple[str, int]:
+    try:
+        toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        return text, 0
+
+    lines = text.splitlines(keepends=True)
+    drops: dict[int, int | None] = {}
+    for t in toks:
+        if t.type != tokenize.COMMENT:
+            continue
+        row, col = t.start
+        if DIRECTIVE.match(t.string):
+            continue
+        line = lines[row - 1] if row - 1 < len(lines) else ""
+        head = line[:col]
+        drops[row] = None if head.strip() == "" else col
+
+    if not drops:
+        return text, 0
+
+    out: list[str] = []
+    for idx, line in enumerate(lines, 1):
+        if idx not in drops:
+            out.append(line)
+            continue
+        col = drops[idx]
+        if col is None:
+            continue
+        body = line[:col].rstrip()
+        eol = line[len(line.rstrip("\r\n")):]
+        out.append(body + eol)
+    out = collapse_blank(out)
+    return "".join(out), len(drops)
+
+
+def _tpl_open(s: str) -> bool:
+    n = 0
+    i = 0
+    while i < len(s):
+        if s[i] == "\\":
+            i += 2
+            continue
+        if s[i] == "`":
+            n += 1
+        i += 1
+    return n % 2 == 1
+
+
+def strip_js(text: str) -> tuple[str, int]:
+    """只删独占整行的注释,行尾注释一律不动。
+
+    按位置切不行:正则字面量里的 \/\/ 和字符串里的 // 都会被当成注释起点 ——
+    markdown.js 的 /^https?:\/\//i 就被切掉半个函数。整行判定是安全的:
+    行首出现 // 或 /* 时,它只能是注释。
+    """
+    lines = text.splitlines(keepends=True)
+    out: list[str] = []
+    removed = 0
+    in_block = ""
+    in_tpl = False
+    for line in lines:
+        body = line.rstrip("\r\n")
+        s = body.strip()
+        if in_block:
+            removed += 1
+            if (in_block == "<!--" and "-->" in s) or (in_block == "/*" and "*/" in s):
+                in_block = ""
+            continue
+        if in_tpl:
+            if _tpl_open(s):
+                in_tpl = False
+            out.append(line)
+            continue
+        if s.startswith("<!--"):
+            removed += 1
+            if "-->" not in s[4:]:
+                in_block = "<!--"
+            continue
+        if s.startswith("/*"):
+            removed += 1
+            if "*/" not in s[2:]:
+                in_block = "/*"
+            continue
+        if s.startswith("//"):
+            removed += 1
+            continue
+        if _tpl_open(body):
+            in_tpl = True
+        out.append(line)
+    return "".join(collapse_blank(out, 1)), removed
+
+
+def strip_ps(text: str) -> tuple[str, int]:
+    """PowerShell 的注释符是 # 和 <# #>。只删独占行的,行尾的不碰 —— 拆字符串不值当。"""
+    out: list[str] = []
+    removed = 0
+    in_block = False
+    for line in text.splitlines(keepends=True):
+        stripped = line.strip()
+        if in_block:
+            removed += 1
+            if "#>" in stripped:
+                in_block = False
+            continue
+        if stripped.startswith("<#"):
+            removed += 1
+            if "#>" not in stripped[2:]:
+                in_block = True
+            continue
+        if stripped.startswith("#") and not re.match(r"#\s*requires\b", stripped, re.I):
+            removed += 1
+            continue
+        out.append(line)
+    return "".join(collapse_blank(out, 1)), removed
+
+
+def main(argv: list[str]) -> int:
+    dry = "--dry" in argv
+    picked = [Path(a) for a in argv if not a.startswith("-")]
+    files = picked or targets()
+    total_files = 0
+    total_lines = 0
+    for p in files:
+        if not p.is_absolute():
+            p = ROOT / p
+        raw = p.read_bytes()
+        text = raw.decode("utf-8")
+        if p.suffix == ".py":
+            new, n = strip_py(text)
+        elif p.suffix == ".ps1":
+            new, n = strip_ps(text)
+        else:
+            new, n = strip_js(text)
+        if n == 0 or new == text:
+            continue
+        if p.suffix == ".py":
+            try:
+                compile(new, str(p), "exec")
+            except SyntaxError as e:
+                print(f"SKIP {p.relative_to(ROOT)}: 删后语法错误 {e}")
+                continue
+        total_files += 1
+        total_lines += n
+        if dry:
+            print(f"{n:5d}  {p.relative_to(ROOT).as_posix()}")
+        else:
+            p.write_bytes(new.encode("utf-8"))
+    print(f"\n{'[dry] ' if dry else ''}files={total_files} comment_lines={total_lines}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/python/tools/verify_env.bat

@@ -0,0 +1,2 @@
+@echo off
+python "%~dp0verify_env.py"

package/python/tools/verify_env.py

@@ -0,0 +1,25 @@
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+p = str(Path(__file__).resolve().parents[1] / ".env")
+try:
+    load_dotenv(p)
+    print("DOTENV_OK")
+except Exception as e:
+    print(f"DOTENV_FAIL: {type(e).__name__}: {e}")
+    raise SystemExit(1)
+
+for k in ("HKC_EMBEDDING_MODEL", "HF_HUB_OFFLINE", "FOXCLAW_API_KEY",
+          "FOXCLAW_PROVIDER", "FOXCLAW_DATA_DIR", "FOXCLAW_MCP_SERVER",
+          "FOXCLAW_MODEL", "HKC_LLM_PROVIDER", "HKC_LLM_MODEL"):
+    v = os.environ.get(k, "<UNSET>")
+    if k.endswith("API_KEY") and v not in ("<UNSET>", ""):
+        v = v[:8] + "..." + v[-4:] if len(v) > 12 else "<short>"
+    print(f"  {k} = {v}")
+
+n = sum(1 for k in os.environ if k.startswith((
+    "HKC_", "FOXCLAW_", "HF_", "ANTHROPIC_", "OPENAI_", "GOOGLE_",
+    "DASHSCOPE_", "LOCAL_", "AMAP_", "BAIDU_", "MINIMAX_", "DEEPSEEK_")))
+print(f"TOTAL_PROJECT_KEYS={n}")

package/python/vendor/HMR_LICENSE

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2024 Hestia OS Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+## About This License
+
+HMR v1 (Hestia Memory Runtime) Core is released under the MIT License.
+
+This means:
+✅ You can use it freely in commercial projects
+✅ You can modify it
+✅ You can distribute it
+✅ You must include the license and copyright
+
+The only requirement: include this license text in your distribution.
+
+For enterprise features and extended support, see Hestia Enterprise License.