foxclaw 0.1.0 → 0.1.3

package/README.md

@@ -1,29 +1,54 @@
-# foxclaw
-
-Personal AI agent — a fox living in your device.
-
-> **0.1.0 is a placeholder release.** This package currently only reserves the
-> `foxclaw` name on npm. The actual agent will be shipped in a later version.
-
-## Install
-
-```bash
-npm install foxclaw
-```
-
-## Usage
-
-```js
-import { version } from "foxclaw";
-
-console.log(version); // 0.1.0
-```
-
-## Related
-
-- Python package: [foxclaw on PyPI](https://pypi.org/project/foxclaw/)
-- Source: [github.com/snowfoxHQ/FoxClaw](https://github.com/snowfoxHQ/FoxClaw)
-
-## License
-
-MIT
+# foxclaw
+
+A personal agent with memory — a fox living in your device.
+
+The npm package ships the **full project source** under `python/`, the same code
+published on PyPI and hosted on GitHub. The `foxclaw` binary forwards its
+arguments to the bundled Python CLI.
+
+## Requirements
+
+- Node.js >= 18
+- Python >= 3.11 (for running the agent)
+- Python dependencies: `pip install fastapi uvicorn pydantic httpx pyyaml`
+
+## Install
+
+```bash
+npm install -g foxclaw
+```
+
+Or, if you prefer the Python package (recommended, pulls dependencies for you):
+
+```bash
+pip install foxclaw
+```
+
+## Usage
+
+```bash
+foxclaw --help
+foxclaw serve --port 8000     # start the HTTP API
+foxclaw config                # show resolved config
+```
+
+Point at a specific interpreter when several Pythons are installed:
+
+```bash
+FOXCLAW_PYTHON=/usr/bin/python3.12 foxclaw serve
+```
+
+## Layout
+
+| Path | Contents |
+|---|---|
+| `python/foxclaw/` | Agent source |
+| `python/vendor/hmr/` | Embedded memory runtime |
+| `python/vendor/hkc/` | Embedded knowledge core |
+| `bin/foxclaw.cjs` | CLI launcher |
+
+## Links
+
+- Homepage: <https://github.com/snowfoxHQ/FoxClaw>
+- Python package: <https://pypi.org/project/foxclaw/>
+- Issues: <https://github.com/snowfoxHQ/FoxClaw/issues>

package/bin/foxclaw.cjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * foxclaw CLI - runs the full Python project bundled in python/.
+ *
+ * Resolves a Python interpreter, points PYTHONPATH at the bundled source tree,
+ * and forwards every argument to `python -m foxclaw.cli`.
+ */
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const pkgRoot = path.resolve(__dirname, "..");
+const bundled = path.join(pkgRoot, "python");
+const hasBundled = fs.existsSync(path.join(bundled, "foxclaw", "cli.py"));
+
+const env = { ...process.env };
+if (hasBundled) {
+  env.PYTHONPATH = env.PYTHONPATH
+    ? `${bundled}${path.delimiter}${env.PYTHONPATH}`
+    : bundled;
+}
+
+const candidates = [
+  process.env.FOXCLAW_PYTHON,
+  process.platform === "win32" ? "python" : "python3",
+  "python",
+].filter(Boolean);
+
+function run(python) {
+  return new Promise((resolve) => {
+    const child = spawn(python, ["-m", "foxclaw.cli", ...process.argv.slice(2)], {
+      stdio: "inherit",
+      env,
+      cwd: process.cwd(),
+    });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code, signal) => resolve({ code, signal }));
+  });
+}
+
+(async () => {
+  for (const python of candidates) {
+    const result = await run(python);
+    if (result === false) continue; // interpreter missing, try next
+    process.exit(typeof result.code === "number" ? result.code : 1);
+  }
+  console.error(
+    "[foxclaw] Python 3.11+ not found. Install it, or set FOXCLAW_PYTHON to the interpreter path."
+  );
+  process.exit(127);
+})();

package/index.js

@@ -1,10 +1,4 @@
-/**
- * FoxClaw — 占位实现。
- *
- * 0.1.0 仅用于在 npm 上保留 `foxclaw` 包名，功能尚未实现。
- */
-
-export const name = "foxclaw";
-export const version = "0.1.0";
-
-export default { name, version };
+export const name = "foxclaw";
+export const version = "0.1.3";
+
+export default { name, version };

package/package.json

@@ -1,38 +1,46 @@
-{
-  "name": "foxclaw",
-  "version": "0.1.0",
-  "description": "Personal AI agent - a fox living in your device",
-  "keywords": [
-    "agent",
-    "ai",
-    "assistant",
-    "foxclaw"
-  ],
-  "license": "MIT",
-  "author": "snowfox <142133502+snowfoxHQ@users.noreply.github.com>",
-  "homepage": "https://github.com/snowfoxHQ/FoxClaw#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/snowfoxHQ/FoxClaw.git",
-    "directory": "npm"
-  },
-  "bugs": {
-    "url": "https://github.com/snowfoxHQ/FoxClaw/issues"
-  },
-  "type": "module",
-  "main": "index.js",
-  "exports": {
-    ".": "./index.js"
-  },
-  "files": [
-    "index.js",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "foxclaw",
+  "version": "0.1.3",
+  "description": "A personal agent with memory - a fox living in your device",
+  "keywords": [
+    "agent",
+    "ai",
+    "assistant",
+    "foxclaw"
+  ],
+  "license": "MIT",
+  "author": "snowfox <142133502+snowfoxHQ@users.noreply.github.com>",
+  "homepage": "https://github.com/snowfoxHQ/FoxClaw#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snowfoxHQ/FoxClaw.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/snowfoxHQ/FoxClaw/issues"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "foxclaw": "bin/foxclaw.cjs"
+  },
+  "files": [
+    "bin/",
+    "python/",
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "node build.cjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/python/.dockerignore

@@ -0,0 +1,35 @@
+# VCS
+.git
+.gitignore
+.github
+
+# 密钥与本地配置（绝不进镜像）
+.env
+.env.*
+!.env.example
+
+# Python 缓存与构建产物
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# 工具缓存
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# 回归失败产物
+tests/_fail_*.txt
+
+# 本地工具/IDE 缓存
+.codebuddy/
+.workbuddy/
+.idea/
+.vscode/
+*.log
+.DS_Store

package/python/.env.example

@@ -0,0 +1,173 @@
+# ============================================================
+# Foxclaw 配置文件模板
+# ============================================================
+# 用法:
+#   1. 复制本文件,改名为 .env(去掉 .example)
+#   2. 在下面填入你自己的 Key(等号后面,不要加引号)
+#   3. 启动:foxclaw serve(等价于 python -m uvicorn foxclaw.api:app --port 8000)
+#
+# 说明:
+#   - 所有 Key 都是可选的,不填则对应功能降级/禁用
+#   - .env 文件不会被分发(已在 .gitignore),你的 Key 是安全的
+#   - 至少配一个大模型 Key,系统才能真实工作(否则 stub 降级)
+#   - 改完跑一遍 `foxclaw config check`:会指出类型写错、拼错的键(比如多打一个 S
+#     导致设置根本不生效)、以及互相矛盾的组合(如只配 KEY_ID 不配 SECRET)。
+#     该命令只读,不会修改你的 .env。
+# ============================================================
+
+# ---------- 大模型(配任意一个即可,系统自动探测)----------
+# DeepSeek(国内,性价比高,需 pip install openai)
+DEEPSEEK_API_KEY=
+
+# Claude
+ANTHROPIC_API_KEY=
+
+# OpenAI GPT(需 pip install openai)
+OPENAI_API_KEY=
+
+# Google Gemini(需 pip install google-generativeai)
+GOOGLE_API_KEY=
+
+# 通义千问(需 pip install openai)
+DASHSCOPE_API_KEY=
+
+# 本地模型 Ollama/vLLM(填 base_url,如 http://localhost:11434/v1)
+LOCAL_LLM_BASE=
+
+# 可选:强制指定模型名(不填则用各 provider 默认,如 deepseek-chat)
+FOXCLAW_MODEL=
+
+# ---------- 高德地图(行政 Agent 用,两个 Key 功能不同)----------
+# Web服务 Key:后端查真实路线/地理编码/POI(在高德控制台选「Web服务」)
+AMAP_MAPS_API_KEY=
+
+# Web端(JS API)Key:前端画地图(在高德控制台选「Web端(JS API)」)
+AMAP_JS_KEY=
+
+# Web端安全密钥 jscode:2021 年后申请的 JSAPI Key 必须配,与上面 Key 配对
+AMAP_JS_SCODE=
+
+# ---------- 联网搜索(可选,让 Agent 能查实时信息)----------
+# 百度 AI 搜索(千帆 ai_search,底层百度搜索 + ERNIE),国内稳定,每日 100 次免费额度。
+# 在百度千帆 AppBuilder 控制台申请 API Key:https://qianfan.cloud.baidu.com
+# 不配则 Agent 无法联网,问"最新版本/今日新闻"会如实说查不到(不编造)
+BAIDU_SEARCH_KEY=
+# 搜索用的模型(可选,默认 ernie-3.5-8k;想更强可填 ernie-4.5-turbo-32k)
+BAIDU_SEARCH_MODEL=ernie-3.5-8k
+# 搜索接入点(默认即此,一般不用改)
+BAIDU_SEARCH_BASE=https://qianfan.baidubce.com/v2/ai_search
+
+# ★ 系统唯一本地 embedding(HKC 检索 + HMR 记忆 + Harness 漂移 + Evidence 语义 全用这个)
+# 解析优先级(vendor/hmr/storage/vector_store.py):
+#   EMBEDDING_MODEL > HKC_EMBEDDING_MODEL > FOXCLAW_EMBEDDING_MODEL > all-MiniLM-L6-v2
+# 填本地目录(如 D:\models\bge-m3)可完全离线;填 HF 仓库名(如 BAAI/bge-m3)则用缓存。
+# 换模型会让已落盘的向量维度不匹配,启动时告警并要求重建索引。
+EMBEDDING_MODEL=
+
+# ---------- HKC 知识库行为开关(2026-11)----------
+# auto = 本地 SentenceTransformer 优先,不可用则退 stub
+# local = 强制本地;stub = 不加载模型(检索退化为关键词);tei = 走远程服务(配 URL)
+HKC_EMBEDDING=auto
+# 仅 HKC_EMBEDDING=tei 时使用
+HKC_EMBEDDING_URL=http://localhost:8080
+# 只给 HKC 单独指定模型;留空则跟随 EMBEDDING_MODEL
+HKC_EMBEDDING_MODEL=
+# 知识库数据目录
+HKC_DATA_DIR=./hkc_data
+# 单文档最多切多少 chunk(默认安全值 800 段 ≈ 125 万字符)
+# 0 或负数 = 不限制:上传上限 20MB ≈ 4400 段,一次误传会在后台连跑数小时并持续计费,
+# 且截断后同文件重传会被去重拦截、只能拆分后补传 —— 除非确需整本摄入,否则别设 0。
+HKC_MAX_CHUNKS_PER_DOC=800
+# 抽取并发(默认 4)/ 每批条数(默认 1)
+HKC_EXTRACT_CONCURRENCY=4
+HKC_EXTRACT_BATCH=1
+# 单次抽取 LLM 超时(秒)
+HKC_LLM_TIMEOUT=60
+# 累计向量数超过此值时索引自动升级 Flat → IVF(默认 10000;0=禁用)
+HKC_VECTOR_IVF_THRESHOLD=10000
+# embedding 计算线程数(默认 2)
+HKC_EMB_TORCH_THREADS=2
+
+# ---------- 记忆后端(2026-11)----------
+# hmr(默认) | vecrecall。vecrecall 落盘在独立子目录,不与 hmr 混写;
+# 切换不迁移旧数据,切回 hmr 时原数据仍在。
+# 兼容 hestiaOS 旧变量名:FOXCLAW_ 为空时读 HESTIA_MEMORY_BACKEND。
+FOXCLAW_MEMORY_BACKEND=hmr
+# 1 = 每条记忆同步写 sha256 区块(哈希链,可审计防篡改)。仅 vecrecall 生效,
+# 开启后存储量约翻倍。兼容 HESTIA_MEMORY_CHAIN。
+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=
+
+# 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
+
+# MCP server:1=启动时同时暴露 MCP 端点,供外部 Agent 接入
+FOXCLAW_MCP_SERVER=0
+
+# 联网搜索 · 读取超时(秒)。深度搜索慢,默认 45;可调大避免超时
+BAIDU_SEARCH_TIMEOUT=60
+# 联网搜索 · 深度搜索开关:1=更全但慢(几十秒) / 0=普通搜索更快(~5-10秒)
+# 只做快速信息检索填 0 即可
+BAIDU_SEARCH_DEEP=0
+
+# ---------- 上下文预算(2026-11 接入 Compactor)----------
+# 单次 LLM 调用的上下文上限(估算 token)。超过则按「LLM 摘要 → 部分摘要 → 截断」
+# 三级降级压缩,保留系统提示与最近 4 组消息。置 0 关闭压缩(退回按条数硬截)。
+FOXCLAW_CONTEXT_MAX_TOKENS=6000
+
+# ---------- 安全(2026-11 加固,建议按需启用)----------
+# DNS rebinding 防护:Host 头为公网域名时拒绝本机数据面请求。自建域名/反代访问时
+# 把域名填进来(逗号分隔,支持 *.example.com),否则会被 403。
+FOXCLAW_ALLOWED_HOSTS=
+
+# 浏览器导航默认拒绝 file://、javascript:、内网/回环地址(SSRF 防护)。
+# 需要让 Agent 访问局域网设备(如 192.168.x.x 的路由器后台)时才置 1。
+FOXCLAW_BROWSER_ALLOW_PRIVATE=0
+
+# 渠道发送者白名单:只有列出的 sender_id 发来的消息才按「指令」执行,
+# 其余一律包成 <untrusted> 数据块(可作答、不执行)。逗号分隔,支持
+# `sender_id` / `channel:sender_id` / `channel:*`(该渠道下全部发送者)。
+# 裸 `*` 不再自动生效,需同时设 FOXCLAW_CHANNEL_TRUST_ALL=1(等于放弃这层防护,不推荐)。
+FOXCLAW_CHANNEL_TRUSTED_SENDERS=
+# 显式开启「所有渠道所有发送者都可信」。仅在你完全清楚后果时设置。
+FOXCLAW_CHANNEL_TRUST_ALL=
+
+# 单个工具调用的硬超时(秒)。超时即跳过该步并回注「未完成」提示,防一个慢工具拖死整轮。
+FOXCLAW_TOOL_TIMEOUT=45
+
+# ---------- 出站渠道签名(2026-11 接入,可选)----------
+# 与自建网关(OpenClaw 桥)共享的 HMAC 密钥。配置后出站请求带
+# X-Foxclaw-Signature/Timestamp/Nonce(签名覆盖 timestamp+nonce+正文摘要),
+# 网关侧用同一密钥验签即可确认「真伪 + 未被篡改 + 未重放」。
+# 留空 = 不签(opt-in)。**一旦配置,签名失败就不发送**(fail-closed,不降级成明文)。
+# 注意:Telegram/Discord/飞书/微信官方 API 不验我们的签名,这条只对「两端都自己控制」
+# 的网关链路有意义,别指望它防官方渠道。
+FOXCLAW_CHANNEL_SIGNING_SECRET=
+# 密钥轮换时用于对账(随签名一起发送,不参与签名计算)。可留空。
+FOXCLAW_CHANNEL_SIGNING_KEY_ID=
+
+# ---------- 服务鉴权(2026-11 补齐)----------
+# 设了它,/api/* /knowledge/* /config/* /stats 对「非本机」客户端要求 X-API-Key 头。
+# 本机(127.0.0.1 / ::1)默认仍免密,见 FOXCLAW_LOOPBACK_BYPASS。
+# 对外暴露(FOXCLAW_HOST=0.0.0.0)时必填,否则任何能连上端口的人都能读你的知识/记忆。
+FOXCLAW_API_KEY=
+# 设为 0 则本机也强制校验(前端目前不会自动带 key,打开后浏览器访问会 401)。
+# FOXCLAW_LOOPBACK_BYPASS=1

package/python/.gitattributes

@@ -0,0 +1,46 @@
+# ============================================================
+# 换行符与二进制处理 —— 跨平台协作必需
+# ============================================================
+# 背景:本仓库此前只有 core.autocrlf=true,没有 .gitattributes。后果是换行符由**每个
+# 协作者的本地 git 配置**决定:Windows 上 checkout 会把 LF 变 CRLF,于是同一个人换台
+# 机器、或不同人 clone,就会产出「整文件级」的假 diff,让 review 淹没在噪音里。
+# 这里把规则钉进仓库,使行为不再依赖本地配置。
+#
+# 已跟踪文件现状:取样 200 个中 LF=183 / CRLF=5 / 混合=1 —— 主体是 LF,故以 LF 为准。
+# 注意:本次**没有**执行 `git add --renormalize .`(那会一次改动数百文件、无法 review);
+# 少数 CRLF 文件会在各自下次被编辑时自然归一。
+
+# 默认:文本文件以 LF 入库、以 LF 检出
+* text=auto eol=lf
+
+# Windows 专属脚本必须 CRLF —— cmd.exe / PowerShell 对 LF 解析异常
+*.bat  text eol=crlf
+*.cmd  text eol=crlf
+*.ps1  text eol=crlf
+
+# 二进制:禁止换行符转换与文本 diff
+*.png    binary
+*.jpg    binary
+*.jpeg   binary
+*.gif    binary
+*.ico    binary
+*.webp   binary
+*.pdf    binary
+*.zip    binary
+*.gz     binary
+*.7z     binary
+*.docx   binary
+*.xlsx   binary
+*.pptx   binary
+*.ttf    binary
+*.otf    binary
+*.woff   binary
+*.woff2  binary
+*.so     binary
+*.pyd    binary
+*.dll    binary
+*.exe    binary
+
+# 说明:本项目依赖锁定在 pyproject.toml([project].dependencies),当前**无**锁文件
+# (uv.lock / poetry.lock)。若日后引入,建议在此追加 `uv.lock -diff`,避免锁文件
+# 把 diff 高亮占满。

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

@@ -0,0 +1,167 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+  workflow_dispatch:
+
+# 合并自占位包仓库的 ci.yml：只取权限最小化与手动触发两项，
+# 其余（3.10/3.13/3.14 矩阵、ruff format 硬门）未并入——
+# 本项目 requires-python>=3.11，且存量 240 个文件未过 ruff format，
+# 直接加会当场红。格式门待单独一轮 format 后再开。
+permissions:
+  contents: read
+
+jobs:
+  toolchain:
+    # S1:工程化安全网 —— ruff(硬门) + mypy(棘轮) + 体积(棘轮) + pytest 收集。
+    # ruff 只保留 F 系列死代码/真 bug 作为硬门,存量风格告警已在 pyproject 显式豁免;
+    # 覆盖 foxclaw/ 与 tests/(tests 于 2026-11 纳入:此前 13 条 F 系列全藏在这里)。
+    # mypy 自 2026-11 起改为棘轮门(tools/mypy_ratchet.py):存量 673 冻结,只许降不许升。
+    #   此前是 continue-on-error,数字从注释里的 425 一路涨到 673 也无人发现 ——
+    #   不阻塞的检查等于没有检查。
+    # 体积门(tools/size_check.py):单文件 <=15KB;现有 25 个超限文件冻结在白名单,
+    #   新增超限直接失败,拆小了会提示移出白名单。
+    # pytest 只做快速收集检查(S2 已把全部 76 个测试迁为 pytest,无顶层副作用),
+    # 真正的断言执行统一走下方 regression job 的 run_all.py(每文件独立子进程隔离单例)。
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.12 是发布/回归基线;3.14 覆盖「本地装了新版、CI 从未验证」的版本漂移。
+        python-version: ["3.12", "3.14"]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - 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]"
+
+      - name: Ruff (hard gate)
+        # tests/ 一并纳入:未用 import / 未定义名在测试里同样是死代码信号。
+        # 此前 tests/ 完全没有门禁,存量 13 条 F 系列(含 1 条 F811 重复 import)藏在
+        # 测试文件里无人发现 —— 只查 foxclaw/ 等于给测试留了盲区。
+        run: |
+          ruff check foxclaw/
+          ruff check tests/
+
+      - name: Mypy ratchet (no new type errors)
+        # 只在基线版本跑:基线数字按 3.12 校准,两版本并行会因 typeshed 差异抖动。
+        if: matrix.python-version == '3.12'
+        run: python tools/mypy_ratchet.py
+
+      - name: File size ratchet (<=15KB)
+        run: python tools/size_check.py
+
+      - name: Pytest collect check (all tests migrated)
+        run: python -m pytest --collect-only -q
+
+      - name: Release preflight (version sources)
+        # 版本号漏改一处会让发布物自相对不上,而发出去不能覆盖。这里只查"四处是否一致",
+        # 产物结构检查(需先 build)在 .github/workflows/release.yml 里。
+        if: matrix.python-version == '3.12'
+        run: python tools/release_check.py
+
+  regression:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Cache pip + HF models
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.cache/huggingface
+          key: foxclaw-deps-${{ runner.os }}-py312-v1
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # 单源: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
+        # 先联网下好默认 embedding,run_all 会以 HF_HUB_OFFLINE 离线读取(与本地一致)。
+        #
+        # 【纠正】原注释写「下载失败也不致命:Harness 会自动降级 n-gram 哈希嵌入,
+        # 回归仍绿」—— **这句是错的**,且很可能让 M2 缺陷长期潜伏。
+        # 实测(2026-10-05):哈希嵌入对中文几乎无区分度(同域相似度 -0.17、
+        # 跨域 +0.00,差异 <0.17)→ 语义漂移分恒为 1.0 → 所有正常请求一律 BLOCK,
+        # 6 项治理测试全红。降级**不是**安全兜底。
+        #
+        # 现在:预热失败即让 CI 失败(去掉 `|| true`),因为它直接决定治理能力可用性,
+        # 不该被静默吞掉。M2 修复后降级方向已改为 fail-open(停用语义维度、
+        # 保留 tool/scope 确定性判定),回归可绿,但**拦截能力是降级的**,
+        # 不可把降级当作正常路径。
+        run: python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+      - name: Full regression (with coverage)
+        # run_all.py 内部注入 HF_HUB_OFFLINE / 强制 stub LLM / UTF-8,故 CI 无需 LLM key、
+        # 不联网调模型,确定性绿。coverage 用 parallel 模式测所有子进程,最后 combine 出基线数字。
+        run: |
+          coverage run tests/run_all.py
+          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