foxclaw 0.1.2 → 0.1.3

package/index.js

@@ -1,11 +1,4 @@
-/**
- * FoxClaw - a personal agent with memory.
- *
- * The npm package bundles the full Python project under `python/`; the CLI
- * (`npx foxclaw`) forwards to it. This module exposes the package metadata for
- * programs that only need the name/version.
- */
 export const name = "foxclaw";
-export const version = "0.1.2";
+export const version = "0.1.3";
 
 export default { name, version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foxclaw",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A personal agent with memory - a fox living in your device",
   "keywords": [
     "agent",

package/python/.env.example

@@ -100,6 +100,9 @@ FOXCLAW_MEMORY_CHAIN=0
 # ---------- 运行参数(可选)----------
 # 数据目录
 FOXCLAW_DATA_DIR=./foxclaw_data
+# `foxclaw skills install @owner/slug` 走的 ClawHub 地址。默认 https://clawhub.ai;
+# 内网镜像或自建 registry 填这里。只在装技能时访问,平时不发任何请求。
+FOXCLAW_CLAWHUB_REGISTRY=
 # 导入白名单:/api/{finance,learning,itinerary}/import 的 csv_path 只允许数据目录内的文件。
 # 要从别处导入(如下载目录),把目录填进来,逗号分隔。
 FOXCLAW_IMPORT_ROOTS=
@@ -107,6 +110,11 @@ FOXCLAW_IMPORT_ROOTS=
 # Harness 影子校准轮数(越小越快进入拦截模式)
 FOXCLAW_SHADOW_ROUNDS=20
 
+# 新版本检查。默认关:foxclaw 本地优先,不该在你不说的情况下外呼。
+# 设 1 后启动/首次打开界面时查一次 PyPI(pypi.org/pypi/foxclaw/json),24h 缓存,
+# 有新版时顶栏版本号旁出现提示;只发这一个 GET,不带任何本机信息。
+FOXCLAW_UPDATE_CHECK=0
+
 # 不联网校验模型版本。模型已缓存但机器连不上 huggingface.co 时打开,可跳过
 # 每次构造前 5 次重试的空等(约 20-40s);模型还没下载过时别开,否则无法自动下载。
 # HF_HUB_OFFLINE=1

package/python/.github/workflows/ci.yml

@@ -40,7 +40,19 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install toolchain
+      - name: Install toolchain (pinned, py3.12)
+        if: matrix.python-version == '3.12'
+        # 基线版本按 requirements.txt 装:那是 uv 从 pyproject 解析出的完整闭包,
+        # 与本机 .venv 一致。dev extra 随后补装,pip 不会改写已满足的 pin。
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -e ".[dev]"
+
+      - name: Install toolchain (latest, py3.14)
+        if: matrix.python-version == '3.14'
+        # 3.14 腿刻意不读 requirements.txt:它的职责是发现「依赖在新解释器上解析/安装失败」,
+        # 跟着 pin 会把这个信号一起锁死。
         run: |
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
@@ -92,9 +104,11 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          # 单源安装:依赖以 pyproject.toml 为唯一来源,避免手写清单与它双份漂移。
+          # 单源:pyproject.toml 声明依赖,requirements.txt 是它解析出的锁定闭包(uv 生成)。
+          # 先装锁再装本体,回归跑的就是本机 .venv 同一套版本,而不是当天 PyPI 的最新版。
           # HMR/HKC 是 vendor 内嵌、走 sys.path 加载,不是 PyPI 依赖(已在 pyproject 注明)。
           # dev extra 提供 pytest + openpyxl/python-docx(默认回归 test_file_ingest/test_domain_import 硬依赖)。
+          pip install -r requirements.txt
           pip install -e ".[dev]"
 
       - name: Warm embedding cache
@@ -120,3 +134,34 @@ jobs:
           coverage combine
           coverage report
           coverage xml
+
+  audit:
+    # 依赖漏洞门。此前 SCA 只覆盖 Dockerfile 与前端 package.json,Python 侧完全空白 ——
+    # 实测全局环境 34 个包挂着 278 条已知漏洞(pyjwt 15、starlette 14、filelock 9…),
+    # 而同一份 pyproject 干净解析出来是 0 条,说明问题在"从不升级的运行环境"而非依赖声明。
+    #
+    # 审计 requirements.txt 而非运行环境:它是「实际会被装出来的东西」,结果可复现,
+    # 且不依赖扫描机的环境状态。此门红了怎么修:
+    #   1) 升级 pyproject 里对应依赖的下限/上限;
+    #   2) uv pip compile pyproject.toml --universal -o requirements.txt 重新生成并提交
+    #      (--universal 必须带:否则 Windows 专属包会写成无条件依赖,本作业在 Linux 上装不动);
+    #   3) 确无可用修复版本时,在下面 --ignore-vuln 逐条登记 ID + 原因,不要整门关掉。
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install pip-audit
+        run: |
+          python -m pip install --upgrade pip
+          pip install "pip-audit>=2.7"
+
+      - name: Audit pinned runtime dependencies
+        # --no-deps:requirements.txt 已是 uv 解析好的完整闭包(含全部传递依赖),
+        # 不需要 pip-audit 再解析一遍 —— 不加会静默跑几分钟且可能超时。
+        run: pip-audit -r requirements.txt --no-deps --progress-spinner off

package/python/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+Changes from the first public release 0.1.0 to the current version, newest first.
+
+Chinese version: [CHANGELOG_CN.md](CHANGELOG_CN.md).
+
+## 0.1.3 — 2026-11-11
+
+Bilingual interface, and Settings moved where it belongs.
+
+**Interface**
+
+- New i18n layer (`lib/i18n.js` plus en/zh dictionaries): sidebar, menus, chat, stage, settings and toast strings all resolve through the dictionaries; a missing key falls back to the key, so nothing renders blank.
+- Settings gains "Interface → Language" with instant Chinese / English switching, persisted in `localStorage` (`foxclawLang`) and kept across reloads.
+- Date and number formatting follow the language (`zh-CN` / `en-US`), and `<html lang>` stays in sync.
+- Settings moved out of the "More" popover into a pinned entry at the bottom of the left rail, separated by a rule and left unaffected by session-list scrolling.
+- The version badge in the top bar reads `/api/system/info`; it no longer falls back to a hard-coded `v3.0`.
+
+**Docs**
+
+- README reconciled with the repository as it actually is: agent count, channels, ingest caps, chunk geometry, supported formats and internal links all verified one by one, with a test to keep them from drifting again.
+
+## 0.1.2 — 2026-11-10
+
+Version consolidation and skill installation.
+
+- Version number unified across five places (`pyproject.toml` / `foxclaw/__init__.py` / `npm/package.json` / `npm/index.js` / `frontend_src/package.json`), guarded by `tests/test_version_sync.py` so npm and PyPI cannot drift apart.
+- `foxclaw skills install` accepts ClawHub / GitHub / URL / local archives; the tools panel can install an instruction skill straight from an uploaded `SKILL.md` or OpenClaw package.
+- First run asks how to address you (editable in settings); an optional new-version check was added.
+- `tools/sync_public.ps1` now builds the public tree directly instead of relying on a local clone.
+- Type annotations closed out: mypy went from 645 to 0, and CI turned into a ratchet that may only go down.
+- Explanatory comments stripped repo-wide, so the public tree no longer carries internal notes.
+
+## 0.1.1 — 2026-11-09
+
+npm-only republish; there is no matching version bump in the repository.
+
+- The npm package excludes internal docs (`docs/reports` and friends) and debug leftovers, aborting the pack when any are detected — 0.1.1 had shipped internal documents in the public package.
+- `build.cjs` now runs before `npm pack`, fixing GitHub Release assets that were 2 KB empty shells.
+- `pyproject` gained a readme, so the PyPI page is no longer description-less.
+- `requirements.txt` is compiled with `uv pip compile --universal` so platform-specific dependencies carry markers; CI gained a dependency audit gate.
+- MIT license and metadata added.
+
+## 0.1.0 — 2026-11-06
+
+First public release, on both channels: PyPI `foxclaw` and npm `foxclaw`.
+
+- Runtime: FastAPI service plus the `foxclaw` command-line entry point.
+- Agents: multiple agents collapsed into three (assistant / office / knowledge); the rest were demoted to instruction skills.
+- Knowledge (HKC) and memory (HMR) embedded via `vendor/`: knowledge is extractable and searchable, and review scheduling runs on SM-2.
+- Governance: policy gate, audit hash chain, shadow learning and circuit breaker; import paths are allow-listed and skill side effects default to fail-closed.
+- Config: typed reads instead of raw `.env`, and `foxclaw config check` turns a misconfiguration from a crash into a message.
+- Security: DNS rebinding, browser SSRF and untrusted channel instructions closed off; channel path signatures plus one-shot nonces for sensitive actions.
+- Pipeline: visible plans, reasoning emitted as its own SSE event, step-level checkpoints for resume-after-interrupt.
+- Frontend: Vue3 three-column renderer, persistent feature entries in the left rail, dual-state inspector on the right.
+
+> Both packages are **placeholders**: `vendor/` (HKC / HMR) is not shipped, so a fresh install only gets the importable skeleton. See [docs/RELEASE.md](docs/RELEASE.md).

package/python/CHANGELOG_CN.md

@@ -0,0 +1,57 @@
+# 更新日志
+
+从 0.1.0 首次公开到当前版本的变更记录，最新的排在最前面。
+
+英文版:[CHANGELOG.md](CHANGELOG.md)。
+
+## 0.1.3 — 2026-11-11
+
+界面双语化，并把「设置」放到该在的位置。
+
+**界面**
+
+- 新增 i18n 基建（`lib/i18n.js` + 中英字典），侧栏、菜单、对话、舞台、设置、提示文案统一走字典；缺词回退 key，不会渲染成空白。
+- 设置面板新增「界面 → 语言」，中文 / English 即时切换，写入 `localStorage`（`foxclawLang`），刷新后保持。
+- 日期与数字格式随语言切换（`zh-CN` / `en-US`），`<html lang>` 同步。
+- 「设置」从「更多」弹层移到左栏底部常驻入口，带分隔线，不随会话列表滚动。
+- 顶栏版本号改为读后端 `/api/system/info`，取不到时不再显示硬编码的 `v3.0`。
+
+**文档**
+
+- README 按仓库实际校准：智能体数量、渠道、摄取上限、分块几何、支持格式、内部链接全部逐条核对，并加测试防止再次漂移。
+
+## 0.1.2 — 2026-11-10
+
+版本号收口、技能安装成型。
+
+- 版本号五处统一（`pyproject.toml` / `foxclaw/__init__.py` / `npm/package.json` / `npm/index.js` / `frontend_src/package.json`），并由 `tests/test_version_sync.py` 盯住，防 npm 与 PyPI 漂移。
+- `foxclaw skills install` 支持 ClawHub / GitHub / URL / 本地包；工具面板可直接上传 `SKILL.md` 或 OpenClaw 包安装指令技能。
+- 首次启动引导询问称呼，可在设置中修改；新增可选的新版本检查提示。
+- `tools/sync_public.ps1` 改为直接构造公开树推远端，不再依赖本地克隆。
+- 类型标注收口：mypy 从 645 降到 0，CI 改为棘轮门（只降不升）。
+- 全仓剥离解释性注释，公开树下不再混入内部说明。
+
+## 0.1.1 — 2026-11-09
+
+只在 npm 通道补发，仓库内没有对应版本号的提交记录。
+
+- npm 包排除 `docs/reports` 等内部文档与调试残留，自检命中即中止打包（0.1.1 曾把内部文档打进公开包）。
+- `npm pack` 前先跑 `build.cjs`，修 GitHub Release 附件只有 2KB 空壳。
+- 修 `pyproject` 缺 `readme`，PyPI 项目页不再没有项目描述。
+- `requirements.txt` 改用 `uv pip compile --universal`，平台相关依赖带上 marker；CI 增加依赖审计门。
+- 补 MIT 许可证与 metadata。
+
+## 0.1.0 — 2026-11-06
+
+首个公开版本，PyPI `foxclaw` 与 npm `foxclaw` 双通道。
+
+- 运行时：FastAPI 服务 + `foxclaw` 命令行入口。
+- 智能体：多智能体收敛为三（助手 / 办公 / 知识），其余能力下放为指令技能。
+- 知识库（HKC）与记忆（HMR）以内嵌 `vendor/` 形式接入：知识可抽取、可检索，复习走 SM-2 排程。
+- 治理层：策略门、审计哈希链、影子学习与断路器；导入路径白名单，技能副作用默认 fail-closed。
+- 配置：从 `.env` 改为类型化读取，`foxclaw config check` 把「配置写错」从崩溃变成提示。
+- 安全：堵 DNS rebinding、浏览器 SSRF、渠道陌生指令三个可利用面；渠道路径签名 + 动作一次性 nonce 确认。
+- 链路：计划可见化、推理过程独立 SSE 事件、步骤级 checkpoint 断点续跑。
+- 前端：Vue3 三栏渲染层，左栏功能入口常驻，右栏双态检视。
+
+> 两个包都是**占位包**：`vendor/`（HKC / HMR）不入包，装完只能 import 骨架，完整运行时从仓库获取。详见 [docs/RELEASE.md](docs/RELEASE.md)。

package/python/README.md

@@ -46,13 +46,22 @@ Keeps the system reliable under message redelivery, crashes, long tasks, and loo
 ## Quick start
 
 ```bash
-pip install fastapi uvicorn "httpx<0.28" openai cryptography websockets pyyaml numpy scikit-learn rich pydantic
+python -m venv .venv                      # isolated env — don't pollute the system Python
+.venv\Scripts\activate                    # macOS / Linux: source .venv/bin/activate
+pip install -r requirements.txt           # pinned closure generated from pyproject.toml
+pip install -e . --no-deps                # foxclaw itself, without re-resolving deps
 python tests/run_all.py        # full regression (all green)
 export DEEPSEEK_API_KEY=sk-...  # or ANTHROPIC_API_KEY; unset → stub
 python -m uvicorn foxclaw.api:app --port 8000
 ```
 
-See [docs/RUN.md](docs/RUN.md). Chinese docs: [README_CN.md](README_CN.md).
+> `requirements.txt` is generated by `uv pip compile pyproject.toml --universal -o requirements.txt` — don't hand-edit.
+> `--universal` is required: without it the compile is platform-specific and drags Windows-only packages
+> (e.g. `pywin32`) into the list, which breaks installation on Linux CI. With it, platform deps carry
+> `; sys_platform == ...` markers and pip skips what doesn't apply.
+> Re-run after changing dependencies in `pyproject.toml`, otherwise the lock lags behind the declaration.
+
+See [docs/RUN.md](docs/RUN.md). Chinese docs: [README_CN.md](README_CN.md). Release history: [CHANGELOG.md](CHANGELOG.md).
 
 > **Windows**: don't place the project under OneDrive-managed folders (Documents/Desktop/Pictures); Python can't create dirs inside redirect placeholders. Use a path like `C:\foxclaw`.
 

package/python/README_CN.md

@@ -9,14 +9,16 @@ Foxclaw:        记忆 = 持续认知运行时,智能体 = 会推理 · 会学
 
 ## 一、这是什么
 
-Foxclaw 不是"又一个智能体框架",而是一个真正记得住事的个人智能体；技术上它是一个智能体运行时。它建立在 HMR(Foxclaw 记忆运行时)之上,核心护城河独立于任何大模型:
+主流智能体框架把记忆当存储:开新会话就归零,记忆只是检索。Foxclaw 把记忆做成**持续运行的认知层**——推理、校准、学习都发生在这一层,并且与 LLM 彻底解耦:换模型不影响判断力。
+
+它建立在 HMR(Foxclaw 记忆运行时)之上,四件事构成护城河:
 
 - **推理链(ThoughtChain)** —— 每个智能体的推理轨迹是可审计、可对比的有向图,不是普通日志
-- **线束(Harness)** —— 跨层约束与校准:三维漂移检测(语义/工具/范围)+ 影子模式自校准 + 策略自学习
-- **演化(Evolution)** —— 每次线束截断都让策略学习,系统越用越准
-- **运行时治理** —— 幂等、崩溃恢复、循环检测等,保证系统在真实运行中可靠、可审计、不丢不重
+- **线束(Harness)** —— 跨层约束与校准:三维漂移检测(语义 / 工具 / 范围)+ 影子模式自校准 + 策略自学习
+- **演化(Evolution)** —— 每次线束截断都喂给策略,系统越用越准
+- **运行时治理** —— 幂等、崩溃恢复、循环检测,保证真实运行中可靠、可审计、不丢不重
 
-三个智能体:主管(协调)、财务(理财)、办公学习(学习 + 日程行程)。每个拥有独立记忆与策略演化,通过 Skill 接入层挂载外部生态,通过渠道层接入主流消息平台。原「助手」「行政」已**下放为指令技能**(`skills/general-assistant`、`skills/schedule-itinerary`),按需挂载,不再单列 Agent。
+三个智能体:**主管**(协调)、**财务**(理财)、**办公学习**(学习 + 日程行程)。各自持有隔离记忆与策略演化,通过 Skill 层挂载外部生态,通过渠道层接入四个消息平台。早期的「助手」「行政」已**下放为指令技能**(`skills/general-assistant`、`skills/schedule-itinerary`),按需挂载,不再单列 Agent。
 
 ## 二、三个智能体与领域内核
 
@@ -69,11 +71,12 @@ foxclaw/
 │   ├── core/                     thought_chain / memory_adapter / model_router /
 │   │                             system_bus / truth_pipeline / token_meter /
 │   │                             web_search / compaction / idempotency / recovery
-│   ├── kernel/                   运行时内核:调度 / 事件 / 能力 / 生命周期 / 准入
+│   ├── kernel/                   运行时内核:调度 / 进程 / 能力 / 准入(spine + sentinel)
 │   ├── pipeline/ planning/       任务执行管线 + 规划原语
-│   ├── cognitive/ knowledge/     领域推理 + 知识接入
-│   ├── agents/                   base.py(统一 run_task 模板) + agents.py(五智能体)
-│   ├── harness/                  harness.py(三维漂移) + loop_detection.py
+│   ├── cognitive/ knowledge/     领域推理 + 真相结晶
+│   ├── agents/                   base.py(CognitiveAgent 模板)+ agents.py
+│   │                             + impl/(财务 / 办公 / 主管 —— 三个智能体)
+│   ├── harness/                  harness.py(三维漂移)+ loop_detection.py + 策略自学习
 │   ├── finance/                  财务内核 + 三件套(evidence/graph/reconcile)
 │   ├── learning/                 学习内核(SM-2 + 知识图谱)
 │   ├── itinerary/                行程内核(TSP + 高德)
@@ -81,12 +84,11 @@ foxclaw/
 │   ├── skills/                   Skill 接入层 + 权限(permission)/钩子/断路器/循环防护
 │   ├── search/                   HSR 认知搜索(HMR 记忆 + HKC 知识 + 联网,融入)
 │   ├── browser/                  HIR 浏览器子系统(AI 用的浏览器,融入)
-│   ├── orchestration/            跨 Agent 编排(P3 已去领域硬编码,通用)
 │   ├── capability/ governance/   embedding 单例 / 治理中间件
 ├── vendor/hmr/ vendor/hkc/       HMR v2.0 记忆运行时 + HKC 知识核心(已内嵌)
 ├── examples/                     样例数据
-├── tests/                        76 个测试文件(全部 pytest)+ run_all.py
-└── docs/                         RUN / CHANNELS / GOVERNANCE / 配置指南(公开)
+├── tests/                        全部 pytest 组织 + run_all.py 一键跑全量回归
+└── docs/                         RUN / RUN_CN / CHANNELS / GOVERNANCE / RELEASE / 配置指南
 ```
 
 ## 六、环境要求
@@ -97,12 +99,13 @@ foxclaw/
 ## 七、快速开始
 
 ```bash
-# 1. 安装依赖
-pip install fastapi uvicorn "httpx<0.28" openai cryptography websockets pyyaml numpy scikit-learn rich pydantic
-#    (Windows 上 pip 装系统包可能需要 --break-system-packages)
+# 1. 建隔离环境 —— 不要直接装进系统 Python,否则会和机器上其它项目互相污染
+python -m venv .venv
+.venv\Scripts\activate            # macOS / Linux: source .venv/bin/activate
 
-# 2. 可选:更精确的语义检测(约 800MB,不装则降级 n-gram)
-pip install sentence-transformers
+# 2. 安装锁定版本的依赖(含 torch / faiss,约 1GB)
+pip install -r requirements.txt
+pip install -e . --no-deps        # 装 foxclaw 本体,不再重解析依赖
 
 # 3. 验证认知运行时(无需 API key)
 python tests/run_all.py        # 全量回归(全绿)
@@ -112,7 +115,14 @@ export DEEPSEEK_API_KEY=sk-...  # 或 ANTHROPIC_API_KEY;Windows: $env:DEEPSEEK_A
 python -m uvicorn foxclaw.api:app --port 8000
 ```
 
-详见 [docs/RUN_CN.md](docs/RUN_CN.md)。
+> `requirements.txt` 由 `uv pip compile pyproject.toml --universal -o requirements.txt` 从 `pyproject.toml` 生成,
+> **不要手改**。`--universal` 不能省:不加的话解析结果只针对当前平台,会把 Windows 专属包
+> (如 `pywin32`)写成无条件依赖,Linux CI 直接装不上。加了它平台相关的包才带
+> `; sys_platform == ...` 标记,pip 会自动跳过不适用项。
+> 改完 `pyproject.toml` 里的依赖后重跑一次,否则锁定清单会滞后于声明,
+> SCA 扫描和 CI 装的都会是旧版本。
+
+详见 [docs/RUN_CN.md](docs/RUN_CN.md)。版本变更:[CHANGELOG_CN.md](CHANGELOG_CN.md)。
 
 ### 开发常用命令(Windows / PowerShell 一行重启)
 
@@ -127,7 +137,9 @@ function restart-foxclaw {
   $p=(Get-NetTCPConnection -LocalPort 8000 -State Listen -EA SilentlyContinue).OwningProcess
   if($p){Stop-Process -Id $p -Force; Start-Sleep 1}
   Set-Location <你的项目目录>
-  foxclaw serve
+  # 显式走 .venv,别用 PATH 里那个系统 Python 的 foxclaw.exe ——
+  # 系统环境常常是很久以前装的,挂着已知漏洞(实测 278 条)。
+  .\.venv\Scripts\foxclaw.exe serve
 }
 
 # ③ 重开 PowerShell 让配置生效(只在改了 $PROFILE 后需要)
@@ -167,7 +179,7 @@ docker run -d --name foxclaw \
   -v foxclaw_data:/app/foxclaw_data \
   foxclaw
 
-# 容器内跑全量回归(76 项,验证镜像健康)
+# 容器内跑全量回归(验证镜像健康)
 docker run --rm foxclaw python tests/run_all.py
 ```
 

package/python/bench/bm25_audit.py

@@ -39,28 +39,23 @@ def audit_float_accumulation():
     print("\n[1/5] 浮点累加精度对比 (build 一次 vs 累加 1000 次) ...")
     corpus = gen_corpus(1000)
 
-    # 方法 A: build 一次
     idx_a = NewBM25()
     idx_a.build(corpus)
 
-    # 方法 B: 1000 次 append_ku
     idx_b = NewBM25()
     for ku in corpus:
         idx_b.append_ku(ku)
 
-    # 比 avgdl
     print(f"        build 一次  avgdl = {idx_a._avgdl:.10f}")
     print(f"        1000 次累加 avgdl = {idx_b._avgdl:.10f}")
     diff_avgdl = abs(idx_a._avgdl - idx_b._avgdl)
     print(f"        差 = {diff_avgdl:.2e} (rel {diff_avgdl/idx_a._avgdl:.2e})")
 
-    # 比 _idf_sum
     print(f"        build 一次  _idf_sum = {idx_a._idf_sum:.10f}")
     print(f"        1000 次累加 _idf_sum = {idx_b._idf_sum:.10f}")
     diff_idf = abs(idx_a._idf_sum - idx_b._idf_sum)
     print(f"        差 = {diff_idf:.2e} (rel {diff_idf/max(abs(idx_a._idf_sum),1e-10):.2e})")
 
-    # 搜同一 query,top-3 是否一致
     q = "topic0_3 topic1_7"
     r_a = sorted([(r.ku_id, round(r.score, 8)) for r in idx_a.search(q, 10)])
     r_b = sorted([(r.ku_id, round(r.score, 8)) for r in idx_b.search(q, 10)])
@@ -76,7 +71,6 @@ def audit_pickle_schema_fallback():
     """2: pickle schema 兼容(老 pickle / 损坏 pickle fallback)"""
     print("\n[2/5] pickle schema 兼容 + 损坏文件 fallback ...")
     tmp = "_tmp_audit.pkl"
-    # 正常 save/load
     idx = NewBM25()
     idx.build(gen_corpus(100))
     idx.save(tmp)
@@ -84,7 +78,6 @@ def audit_pickle_schema_fallback():
     ok = idx2.load(tmp)
     print(f"        正常 save/load: ok={ok}, size={idx2.size()} {'PASS' if ok and idx2.size()==100 else 'FAIL'}")
 
-    # 损坏文件
     with open(tmp, 'wb') as f:
         f.write(b'garbage data not a pickle')
     idx3 = NewBM25()
@@ -92,14 +85,12 @@ def audit_pickle_schema_fallback():
     print(f"        损坏文件 load: ok={ok3} (应该返 False, 不抛异常) {'PASS' if ok3 == False else 'FAIL'}")
     print(f"        损坏后 idx3.size() = {idx3.size()} (应该 0, 已 fallback) {'PASS' if idx3.size() == 0 else 'FAIL'}")
 
-    # schema 不匹配(手写一个旧版结构)
     with open(tmp, 'wb') as f:
         pickle.dump({'old_version': True, 'ku_ids': [], 'corpus': []}, f)
     idx4 = NewBM25()
     ok4 = idx4.load(tmp)
     print(f"        schema 不匹配: ok={ok4} (应该返 False) {'PASS' if ok4 == False else 'FAIL'}")
 
-    # 不存在文件
     if os.path.exists(tmp):
         os.remove(tmp)
     idx5 = NewBM25()
@@ -158,19 +149,15 @@ def audit_clear_idempotent():
     idx.clear()
     print(f"        clear 后: {idx.size()} (应该 0) {'PASS' if idx.size()==0 else 'FAIL'}")
 
-    # 空 search 不抛
     r = idx.search("any query", 10)
     print(f"        空 search: {len(r)} 个结果 (应该 0) {'PASS' if len(r)==0 else 'FAIL'}")
 
-    # 二次 clear
     idx.clear()
     print(f"        二次 clear: size={idx.size()} (应该 0) {'PASS' if idx.size()==0 else 'FAIL'}")
 
-    # 删不存在
     r = idx.remove_ku("ku_99999999")
     print(f"        remove_ku 不存在: 返 {r} (应该 False) {'PASS' if r == False else 'FAIL'}")
 
-    # search 空 query
     r = idx.search("", 10)
     print(f"        search 空 query: {len(r)} 个结果 (应该 0) {'PASS' if len(r)==0 else 'FAIL'}")
 
@@ -186,7 +173,7 @@ def main():
 
     r1 = audit_float_accumulation()
     r2 = audit_pickle_schema_fallback()
-    audit_append_ku_latency()  # 打印即可
+    audit_append_ku_latency()
     r4 = audit_search_consistency()
     r5 = audit_clear_idempotent()
 

package/python/bench/bm25_regression.py

@@ -155,7 +155,6 @@ def main():
     else:
         print("\n[4/4] 跳过一致率(无 rank_bm25 对照)")
 
-    # save/load roundtrip
     print("\n[bonus] save/load roundtrip ...")
     tmp = "_tmp_bm25.pkl"
     new_idx.save(tmp)

package/python/bench/bm25_stress.py

@@ -116,7 +116,6 @@ def main():
     print("BM25 压测: 5万/10万 corpus build + search + remove + save/load")
     print("=" * 60)
 
-    # 5万
     idx, corpus = bench_build(50_000)
     queries = gen_queries(200)
     bench_search(idx, queries)
@@ -125,11 +124,8 @@ def main():
     bench_save_load(idx, tmp)
     os.remove(tmp)
 
-    # 10万 (增量:在 5万 上 append 5万,模拟冷构建期分批)
     print(f"\n[build] +5万 增量 (5万 -> 10万) ...")
     extra_corpus = gen_corpus(50_000, seed=43)
-    # 取后 5万 (id 范围 0-49999 是 5万 corpus;这里 gen 同一 seed 重叠,改 seed)
-    # 实际:重新 gen 5万不同 id
     extra_corpus = []
     rng = random.Random(43)
     for i in range(50_000, 100_000):

package/python/bench/cd_audit.py

@@ -14,8 +14,6 @@ from hkc.hkc_kde.extractor import Extractor
 from hkc.hkc_api.ingest_jobs import IngestJobRegistry
 
 
-# ── D1: IngestJobRegistry 4 thread 并发 ────────────────
-
 def d1_ingest_4_workers():
     """D1. 4 worker 真并发 peak=4,4 任务 ~0.3s 完成"""
     reg = IngestJobRegistry(max_workers=4)
@@ -36,7 +34,6 @@ def d1_ingest_4_workers():
     t0 = time.time()
     for j in jobs:
         reg.submit(j, work)
-    # wait done
     while True:
         statuses = [reg.get(j.job_id)["status"] for j in jobs]
         if all(s == "done" for s in statuses):
@@ -49,8 +46,6 @@ def d1_ingest_4_workers():
     print(f"  D1 PASS: peak={peak[0]}, 4 jobs in {elapsed*1000:.0f}ms (串行需 1.2s)")
 
 
-# ── D2: Extractor 16 chunk 限流雪崩 ────────────────────
-
 def d2_429_snowball():
     """D2. 16 chunk × 4 worker × 100% 429 永不成功,验证不死循环 + 总调用有上界"""
     state = {"calls": 0}
@@ -62,8 +57,6 @@ def d2_429_snowball():
         raise err
 
     ext = Extractor(provider="anthropic", model="m")
-    # 替换 _extract_chunk:走 _retry_llm 但传极小 base_delay 测试用
-    # 同时 monkey-patch time.sleep 避免真睡
     import hkc.hkc_kde.extractor as ex_mod
     orig_sleep = ex_mod.time.sleep
     sleeps = []
@@ -88,7 +81,6 @@ def d2_429_snowball():
         result = ext.extract(chunks)
         elapsed = time.time() - t0
 
-        # 期望:16 chunk 全 fail,总调用 = 16 * (1+3 retry) = 64,无死循环
         success = sum(1 for item in result.items if item is not None)
         assert success == 0, f"expected 0 success, got {success}"
         assert state["calls"] == 64, f"snowball: expected 64 calls, got {state['calls']}"
@@ -99,17 +91,13 @@ def d2_429_snowball():
         ex_mod.time.sleep = orig_sleep
 
 
-# ── D3: progress_cb 线程安全 ─────────────────────────
-
 def d3_progress_cb_thread_safe():
     """D3. progress_cb 在 as_completed 循环调,主线程串行;16 chunk 计数无重复无漏"""
     ext = Extractor(provider="anthropic", model="m")
 
-    # 替换 _extract_chunk 为 fast mock:50% 概率 fail(模拟 chunk 失败)
     import random
     random.seed(42)
     def mock_extract(chunk, timeout=60.0):
-        # 永远返 RawExtraction
         from hkc.hkc_kde.models import RawExtraction
         return RawExtraction()
     ext._extract_chunk = mock_extract
@@ -131,21 +119,16 @@ def d3_progress_cb_thread_safe():
     chunks = [MockChunk(i) for i in range(16)]
     result = ext.extract(chunks, progress_cb=cb)
 
-    # 验证:done_calls 长度 16(每个 chunk 一次)
     assert len(done_calls) == 16, f"expected 16 callbacks, got {len(done_calls)}"
-    # 验证:1..16 各一次(set 大小 = 16,排序后 1..16)
     assert sorted(done_calls) == list(range(1, 17)), \
         f"expected processed 1..16, got {sorted(done_calls)}"
     print(f"  D3 PASS: {len(done_calls)} callbacks, all 1..16 unique")
 
 
-# ── D4: max_retries 可调 ──────────────────────────────
-
 def d4_max_retries_configurable():
     """D4. _retry_llm 的 max_retries 真的生效"""
     ext = Extractor(provider="mock", model="m")
 
-    # 测 max_retries=2(默认 3):4 次后 raise
     call_count = [0]
     def always_fail():
         call_count[0] += 1
@@ -153,7 +136,6 @@ def d4_max_retries_configurable():
         err.status_code = 429
         raise err
 
-    # 用 monkey-patch 把 time.sleep 替换掉,这样不会真睡
     import hkc.hkc_kde.extractor as ex_mod
     orig_sleep = ex_mod.time.sleep
     sleeps = []
@@ -164,7 +146,6 @@ def d4_max_retries_configurable():
             assert False, "expected raise"
         except Exception:
             pass
-        # max_retries=2 + 1 = 3 次尝试
         assert call_count[0] == 3, f"max_retries=2 expected 3 calls, got {call_count[0]}"
         assert len(sleeps) == 2, f"max_retries=2 expected 2 sleeps, got {len(sleeps)}"
         print(f"  D4 PASS: max_retries=2 -> 3 calls, 2 sleeps")
@@ -172,8 +153,6 @@ def d4_max_retries_configurable():
         ex_mod.time.sleep = orig_sleep
 
 
-# ── D5: retry + progress_cb 顺序 ─────────────────────
-
 def d5_retry_no_progress_leak():
     """D5. retry 期间 progress_cb 仍只调 1 次/chunk(不管 retry 几次)"""
     import time as time_mod
@@ -209,9 +188,7 @@ def d5_retry_no_progress_leak():
                 cb_count[0] += 1
         chunks = [MockChunk(i) for i in range(8)]
         result = ext.extract(chunks, progress_cb=cb)
-        # 不管 retry 几次,每个 chunk 调 1 次 progress_cb
         assert cb_count[0] == 8, f"expected 8 progress, got {cb_count[0]}"
-        # 8 chunk 全 fail,总调用 = 8 * 4 = 32
         assert state["calls"] == 32, f"expected 32 calls, got {state['calls']}"
         success = sum(1 for item in result.items if item is not None)
         assert success == 0

package/python/bench/chaos.py

@@ -21,7 +21,6 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-# 关闭联网触发(chaos 只测 LLM 咽喉,不触发搜索)
 import foxclaw.core.web_search as ws  # noqa: E402
 ws.needs_search = lambda q: False
 
@@ -37,7 +36,7 @@ def _make_router(primary="deepseek", fallback=None):
     if fallback:
         os.environ[PROVIDER_ENV[fallback]] = "chaos-test-key"
     r = ModelRouter(provider=primary)
-    r._client = object()                     # 使 is_stub == False
+    r._client = object()
     r._clients[primary] = object()
     if fallback:
         r._clients[fallback] = object()
@@ -87,11 +86,11 @@ def case4_circuit_breaker():
     """[4] 断路器:provider 失败后进入冷却,立即重试被跳过(不再紧密重试)。"""
     r = _make_router("deepseek")
     r._call_provider = _boom
-    r.complete(_SYS, _MSG)                    # 第一次失败 → 进入 cooldown
+    r.complete(_SYS, _MSG)
     cooled = "deepseek" in r._cooldown
     t0 = time.perf_counter()
-    r.complete(_SYS, _MSG)                    # 第二次:cooldown 未过期 → 直接跳过,不等超时
-    fast = (time.perf_counter() - t0) < 0.5   # 跳过热 provider,应远快于真实超时
+    r.complete(_SYS, _MSG)
+    fast = (time.perf_counter() - t0) < 0.5
     ok = cooled and fast and r.is_degraded()
     return ok, (f"冷却中={cooled} 跳过耗时={((time.perf_counter()-t0)*1000):.0f}ms"), "断路器生效"
 
@@ -101,11 +100,10 @@ def case5_recovery():
     r = _make_router("deepseek")
     r._call_provider = _boom
     r.complete(_SYS, _MSG)
-    assert "deepseek" in r._cooldown           # 先确认在冷却
-    r._cooldown["deepseek"] = 0                # 模拟冷却过期
+    assert "deepseek" in r._cooldown
+    r._cooldown["deepseek"] = 0
     r._call_provider = lambda *a, **k: ("恢复后的正常回复", None)
     out = r.complete(_SYS, _MSG)
-    # 注:degraded 是「曾降级」的累积运维标志(不因恢复清零),恢复语义看「解冻 + 成功返回」。
     ok = (out == "恢复后的正常回复") and ("deepseek" not in r._cooldown)
     return ok, ("解冻=" + str("deepseek" not in r._cooldown)), out[:40]
 

package/python/bench/e2e_real_models.py

@@ -26,7 +26,6 @@ from foxclaw.core.model_router import ModelRouter  # noqa: E402
 _SYS = "你是 Foxclaw 助手。"
 _MSG = [{"role": "user", "content": "请只回复两个字：你好"}]
 _MAX_TOKENS = 64
-# stub/故障 的特征文案(出现即视为"非真实成功")
 _BAD_MARKERS = ("【未执行】", "【模型返回为空】", "【全部模型失败】", "【模型流式中断】", "STUB")