foxclaw 0.1.0 → 0.1.2

package/python/docs/RELEASE.md

@@ -0,0 +1,109 @@
+# 发布流程
+
+> **当前状态(2026-11-07):发布暂缓。** 开发全部完成后再一次性发,现在只往 GitHub 推代码。
+> 因此**不要**打 `v*` tag(`.github/workflows/release.yml` 由 tag 触发),也**不要**跑
+> `workflow_dispatch` 的 `publish` 选项。流水线已经就位,等要发时按下面走。
+>
+> 另外两个 registry 的现状(查过,别再当"全新包"处理):
+>
+> - PyPI `foxclaw` 已有 **0.1.0**(2026-11-06 上传,不能重发,只能 yank);
+> - npm `foxclaw` 已有 `0.0.0-stage` / `0.1.0` / **0.1.1**(latest),而仓库代码是 0.1.0
+>   —— 那个 0.1.1 是手工 `npm publish` 后没提交,git 里找不到对应版本。
+>
+> 所以下次真正发布时,四处版本号必须先跳到 **≥ 0.1.2**(PyPI 只需 >0.1.0,npm 需 >0.1.1,取大)。
+
+两条发布通道、两种产物,性质完全不同,先说清楚免得误会:
+
+| 产物 | 命令 | 里面有什么 |
+| --- | --- | --- |
+| PyPI `foxclaw` | `pip install foxclaw` | **占位包**:能 import,但 `vendor/`(HKC/HMR)不入包 → 知识/记忆子系统降级为 None |
+| npm `foxclaw` | `npm i foxclaw` | 占位包:`index.js` 只导出 `name` / `version` |
+| GitHub Release | tag 自动 | 上面两个包的文件 + 自动生成的 release notes |
+
+`vendor/` 不入包是设计现状(`packages.find` 只收 `foxclaw*`,HMR/HKC 以 sys.path
+内嵌,运行期按 `Path(__file__)/../../vendor` 找)。发布说明里必须写明"这是占位包",
+不要让人装完以为拿到了完整运行时。
+
+## 1. 本地预检(发布前必须绿)
+
+```bash
+python tools/release_check.py --tag v0.1.0          # 四处版本号一致 + tag 对得上
+python -m build                                      # 出 dist/*.whl + *.tar.gz
+cd npm && npm pack --pack-destination ../dist && cd ..
+python tools/release_check.py --dist dist --npm-tgz dist/*.tgz
+```
+
+第二道检查会做这些事,任一 `[ERROR]` 都不许发布:
+
+- `dist/` 里恰好一个 wheel + 一个 sdist,文件名与版本号一致;
+- wheel 的 `METADATA` 里 `Name` / `Version` 与 `pyproject.toml` 一致;
+- 归档内**不得**出现 `.env`(除 `.env.example`)、`docs/internal/`、`foxclaw_data/`、
+  `__pycache__`、嵌套压缩包、`.venv`;
+- npm tgz 文件名与 `package/package.json` 的 `name@version` 一致;
+- 缺 `vendor/` 只报 `[WARN]`(见上表),不会拦发布。
+
+版本号的唯一来源是 `pyproject.toml`,另外三处(`foxclaw/__init__.py`、
+`npm/package.json`、`npm/index.js`)由 `tests/test_version_sync.py` 盯着必须相等。
+改版本时**四处一起改**,只改一处会在第一道检查里挂掉。
+
+## 2. 打 tag(自动构建 + 挂 Release,不外发)
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+`.github/workflows/release.yml` 的 `build` job 会:校验版本/tag → 构建 → npm pack →
+产物结构校验 → 上传 `python-dist` / `npm-tgz` 两个 artifact;`github-release` job 把它们
+挂成 Release 附件(重跑用 `--clobber` 覆盖附件,不重建 Release)。
+
+这一步**不会**上传到 PyPI / npm,打错了删 tag 重来即可。
+
+## 3. 上传到 PyPI / npm(需要人工审批)
+
+Actions → Release → Run workflow:
+
+- `publish`:选 `pypi` / `npm` / `both`
+- `ref`:填**同一个 tag**(如 `v0.1.0`;不填会直接失败——不允许发分支 HEAD)
+
+然后经由 environment 审批:
+
+| environment | 审批后执行 | 用的 secret |
+| --- | --- | --- |
+| `pypi` | `pypa/gh-action-pypi-publish` | `PYPI_API_TOKEN`(项目级 `pypi-`/`npt_` token) |
+| `npm` | `npm publish` | `NPM_TOKEN`(granular,仅 `foxclaw` 的 publish 权限) |
+
+需要在仓库 Settings → Environments 里先建 `pypi`、`npm` 两个环境并配 Required reviewers,
+否则"审批门"不存在,勾了就直接发。
+
+## 4. 发错了怎么办
+
+**PyPI / npm 的版本号不可撤回**。能做的只有:
+
+- PyPI:`yank`(`twine`/网页)→ 该版本不再被新装选中,但**仍然占着号**,不能重发同号;
+  修好后必须 `0.1.1`。
+- npm:`npm unpublish foxclaw@0.1.0` 只在发布后 72 小时内、且无其他包依赖时可用;
+  过了就只能 `npm deprecate` + 发新号。
+
+所以"先构建、再审批上传"不是流程洁癖,是这两个 registry 的规则逼出来的。
+
+## 5. 切到 OIDC(零长期密钥)
+
+当前用 token,因为上传已有人工审批兜底。想彻底去掉长期密钥时:
+
+- PyPI:项目页 → Publishing → 加 GitHub publisher(owner/repo/workflow/environment
+  必须与实际一致),首次发布用 "pending publisher";然后删掉 secret,给 job 加
+  `permissions: id-token: write`。
+- npm:npm ≥ 11.5 支持 trusted publishing,同样加 `id-token: write` 并去掉 `NODE_AUTH_TOKEN`。
+
+## 仓库名(2026-11-08 已定)
+
+两个仓库,职责不同,别再混:
+
+| 仓库 | 可见性 | 用途 |
+|---|---|---|
+| `snowfoxHQ/FoxClaw` | public | 对外发布。PyPI/npm 的 `homepage`/`repository` 都指它,OIDC publisher 也填它 |
+| 私有开发库(名称不对外) | private | 本地 `git remote origin` 指向的开发备份 |
+
+公开仓库原名 `SnowFoxClaw`,已于 2026-11-08 改名为 `FoxClaw`(GitHub 对旧名自动 301,
+老链接不会 404)。切 OIDC 时 publisher 的 repo 必须写成 `FoxClaw`——不是私有开发库的名字,
+也不是小写 `foxclaw`(registry 侧对大小写不敏感,GitHub 侧 OIDC 校验按仓库真实名匹配)。

package/python/docs/RUN.md

@@ -0,0 +1,75 @@
+# Foxclaw Run Guide (English)
+
+> Chinese version with more detail: [RUN_CN.md](RUN_CN.md)
+
+## Windows + OneDrive (most common pitfall)
+
+If tests raise `FileNotFoundError: [WinError 2] ... test_data`, the project is under a OneDrive-managed folder (Documents/Desktop/Pictures) whose redirect placeholders Python can't create dirs in. Move it:
+
+```powershell
+Copy-Item -Recurse "<your path>\foxclaw" "C:\foxclaw"
+cd C:\foxclaw
+python tests/run_all.py
+```
+
+## 1. Install
+
+```bash
+pip install -e .      # dependencies come from pyproject.toml (single source of truth)
+# lightweight alternative (uninstalled extras degrade gracefully):
+# pip install fastapi uvicorn "httpx<0.28" cryptography websockets pyyaml numpy scikit-learn rich pydantic python-dotenv
+```
+
+`cryptography` → Feishu encrypted-event decryption; `websockets` → Discord Gateway; `httpx` → channel HTTP + web tools.
+
+## 2. Verify (no API key needed)
+
+```bash
+python tests/run_all.py        # full regression (all green)
+python tests/test_e2e.py       # cognitive runtime only
+python tests/test_api.py       # API layer
+```
+
+These run without an LLM key or real HMR — proving cognition is decoupled from the model.
+
+> **About pytest**: all 76 tests are now pytest-style (S2 migration) and need `pip install pytest`
+> (or `pip install -e ".[dev]"`). When pytest is absent the runner **explicitly marks all 76 as
+> "skipped"** and excludes them from the denominator — they neither vanish silently nor fake a pass.
+
+## 3. Start the service
+
+```bash
+export DEEPSEEK_API_KEY=sk-...         # or ANTHROPIC_API_KEY; Windows: $env:...="..."
+export FOXCLAW_PROVIDER=deepseek        # optional explicit provider
+export FOXCLAW_DATA_DIR=./foxclaw_data
+# binds 127.0.0.1 by default. Exposing to LAN requires FOXCLAW_HOST=0.0.0.0 **and** FOXCLAW_API_KEY
+# (the __main__ entry refuses to start on non-loopback without a key; override with FOXCLAW_ALLOW_INSECURE=1).
+python -m uvicorn foxclaw.api:app --host 127.0.0.1 --port 8000
+```
+
+## 4. Channels & governance
+
+Connect WeChat / Feishu / Telegram / Discord — see [CHANNELS.md](CHANNELS.md). Runtime governance (idempotency / crash recovery / loop detection) is auto-wired — see [GOVERNANCE.md](GOVERNANCE.md).
+
+## 5. Embedded HMR
+
+HMR v2.0 is embedded in `vendor/hmr/`, auto-loaded, persisting to the data dir's `hmr/` subdir. To upgrade, API-compatibly replace `vendor/hmr/`; the adapter (`foxclaw/core/memory_adapter.py`) and main body stay unchanged.
+
+## 6. Key environment variables
+
+| Var | Meaning |
+|-----|---------|
+| `DEEPSEEK_API_KEY` / `ANTHROPIC_API_KEY` | LLM key; unset → stub |
+| `FOXCLAW_PROVIDER` | explicit provider |
+| `FOXCLAW_DATA_DIR` | data directory |
+| `FOXCLAW_SHADOW_ROUNDS` | shadow calibration rounds |
+| `FOXCLAW_EMBEDDING_MODEL` | 语义漂移 embedding 模型；中文部署设 `paraphrase-multilingual-MiniLM-L12-v2`（中文跑题硬拦率 0→1.0，见 `evals/governance/compare_embeddings.py`）；默认 `all-MiniLM-L6-v2` |
+| `FOXCLAW_API_KEY` | **Optional auth**: when set, `/api/*` requires `X-API-Key: <value>` (else 401); WebSocket `/ws/harness` uses `?key=<value>` instead (browsers can't set WS headers; the frontend reads it from `localStorage.foxclawApiKey`). When unset, auth is off — safe only on loopback. Frontend and `/docs` stay open. |
+| `FOXCLAW_HOST` / `FOXCLAW_PORT` | Bind address / port for the `python -m foxclaw.api` entry. **Default `127.0.0.1:8000`.** |
+| `FOXCLAW_ALLOW_INSECURE` | Set to `1` to let the entry start on a non-loopback host without `FOXCLAW_API_KEY` (not recommended). |
+| `FOXCLAW_CORS_ORIGINS` | Comma-separated allowed origins. **Default: loopback only** (`localhost` / `127.0.0.1` / `[::1]`, any port). Set explicitly for cross-origin deploys; `*` opens it fully (not recommended). |
+| `FOXCLAW_SHARED_WRITE_MODE` | Shared-memory write policy mode: **`audit` (default) publishes `memory.shared.write` events without blocking**; `warn` also logs; `enforce` actually denies (raises `SharedWriteDenied`). Default is audit because the 8 existing legitimate shared writes must validate the policy table on real traffic before enforcement is switched on. See `foxclaw/core/shared_write.py`. **Run `python tools/shared_write_audit.py` before rolling forward** — end-to-end acceptance (8 real write sites must pass untouched, 5 intrusion probes must be caught; exit code 0 required). |
+| `FOXCLAW_SHARED_WRITE_AUDIT` | Shared-write audit **persistence** switch (default on): appends every `memory.shared.write` event as a JSON line to `{data_dir}/audit/shared_write.jsonl`, so real-traffic samples accumulate for the enforce decision (the spine history is a 1000-entry ring buffer that high-frequency events flush out). Set `0` to disable. How to judge: review each `allowed=false` line — if all are genuine intrusions and none is a legitimate write, switch to `enforce`. |
+| `FOXCLAW_GOVERNANCE_AUDIT` | Unified **governance audit stream** switch (default on, batch 3): rulings from the Harness/Permission/Orchestration/Skill layers are recorded as `governance.decision` events (WS-visible) and persisted to `{data_dir}/audit/governance.jsonl`. Each record carries a `decision_id` (this ruling) and a `correlation_id` (cross-layer join key: a permission ruling's decision_id is attached to the skill execution audit; negotiation rounds share the req.id). Set `0` to disable (all layers skip automatically, zero overhead). |
+| `FOXCLAW_SHADOW_PROMOTE_MIN_OBS` | Observations required before a shadow rule can be promoted (default 50, batch 4 P0-1): rule candidates born from BLOCK enter `shadow_rules` (**not in effect**); after N same-dimension observations they are promoted (take effect) or discarded (harm rate > 0.3, or zero impact). Before that, rules only observe and never block — the guardrail against "unverified online learning". Roll back with `harness.rollback(rule_id)`; the full trail lives in the policy YAML `history` section. |
+| `FOXCLAW_SKIP_DOTENV` | Set to `1` to **skip loading the project-root `.env` entirely** — process env vars become the only source. **For tests/CI only**: a developer `.env` carrying real keys or `FOXCLAW_MCP_SERVER=1` / `FOXCLAW_API_KEY` leaks into test processes, making results machine-dependent, causing tests to hit real external APIs, and writing into real data directories. `tests/run_all.py` sets it to `1` by default. **Do not set this in local development.** |

package/python/docs/RUN_CN.md

@@ -0,0 +1,121 @@
+# Foxclaw 运行指南(中文版)
+
+## ⚠ Windows + OneDrive 路径问题(最常见的坑)
+
+如果在 Windows 上运行测试报 `FileNotFoundError: [WinError 2] ... test_data`:
+
+**原因**:项目被放在 OneDrive 接管的目录(文档/桌面/图片),这些是 OneDrive 重定向占位符,Python 无法在其中创建目录。**典型症状**:PowerShell 能 `cd` 进去,但 Python 建子目录失败。这和代码无关。
+
+**解法**:移到不受 OneDrive 管理的路径:
+
+```powershell
+Copy-Item -Recurse "<你的当前路径>\foxclaw" "C:\foxclaw"
+cd C:\foxclaw
+python tests/run_all.py
+```
+
+## 一、安装依赖
+
+```bash
+pip install -e .                # 依赖以 pyproject.toml 为唯一来源(推荐)
+# Windows 上 pip 装系统包可能需要 --break-system-packages
+
+# 轻量安装(不用全部依赖时,相关能力会自动降级):
+# pip install fastapi uvicorn "httpx<0.28" cryptography websockets pyyaml numpy scikit-learn rich pydantic python-dotenv
+# 不装 sentence-transformers → 线束语义检测降级为 n-gram 哈希;
+# 不装 openai/anthropic → 模型路由降级为 stub。
+```
+
+依赖说明:`cryptography` 用于飞书加密事件解密;`websockets` 用于 Discord Gateway;`httpx` 用于各渠道 HTTP 调用与 Web 工具。未装 `sentence-transformers` 时线束语义检测自动降级为 n-gram 哈希,不会崩溃。
+
+## 二、验证(无需 API key)
+
+```bash
+# 全量回归(全绿)
+python tests/run_all.py
+
+# 单独验证认知运行时 / API 层
+python tests/test_e2e.py
+python tests/test_api.py
+```
+
+这些测试在没有大模型 key、没有真实 HMR 的情况下也能跑 —— 证明认知运行时与大模型解耦。
+
+> **关于 pytest**:76 个测试已**全部迁移为 pytest**(S2 迁移),需 `pip install pytest`
+> (或 `pip install -e ".[dev]"`)才会执行。未安装时运行器会**显式标记全部 76 项为「跳过」**
+> 并从分母扣除 —— 不会静默消失,也不会伪装成通过。
+
+## 三、启动服务
+
+```bash
+# 配 key 则真实调模型,不配则降级 stub(其他功能照常)
+export DEEPSEEK_API_KEY=sk-...         # 或 ANTHROPIC_API_KEY
+                                       # Windows: $env:DEEPSEEK_API_KEY="sk-..."
+export FOXCLAW_PROVIDER=deepseek        # 可选:显式指定 provider
+export FOXCLAW_DATA_DIR=./foxclaw_data   # 数据目录
+
+# 默认绑 127.0.0.1(仅本机)。对外暴露必须同时设 FOXCLAW_HOST=0.0.0.0 与 FOXCLAW_API_KEY——
+# __main__ 入口在「非回环 + 无鉴权」时会拒绝启动(确需如此可设 FOXCLAW_ALLOW_INSECURE=1)。
+python -m uvicorn foxclaw.api:app --host 127.0.0.1 --port 8000
+```
+
+浏览器访问 http://localhost:8000 。
+
+## 四、接入消息平台
+
+四个主流渠道(微信/飞书/Telegram/Discord)各按官方规范实现,凭证由你本地注入。完整配置(怎么拿 token、各渠道启动方式、多渠道并跑)见 [CHANNELS.md](CHANNELS.md)。最简验证(Telegram,@BotFather 拿 token):
+
+```python
+from foxclaw import Foxclaw
+from foxclaw.channels.dispatcher import ChannelDispatcher
+from foxclaw.channels.telegram import TelegramAdapter
+import time
+
+os_ = Foxclaw(data_dir="./data")
+disp = ChannelDispatcher(os_.supervisor)
+tg = TelegramAdapter(bot_token="你的token")
+disp.register_channel(tg)
+while True:
+    tg.poll_once()   # 收消息 → 主管处理 → 自动回复
+    time.sleep(1)
+```
+
+## 五、运行时治理
+
+幂等/崩溃恢复/循环检测等已自动接入,无需额外配置。详见 [GOVERNANCE.md](GOVERNANCE.md)。崩溃重启后,系统启动时会打印上次被中断的任务。
+
+## 六、关于内嵌的 HMR
+
+HMR v2.0 已内嵌在 `vendor/hmr/`,启动自动接入,记忆落盘到数据目录的 `hmr/` 子目录。替换为新版 HMR 只需 API 兼容地替换 `vendor/hmr/`,适配层(`foxclaw/core/memory_adapter.py`)和主体不用改。
+
+## 七、主要 API 端点
+
+| 端点 | 说明 |
+|------|------|
+| `GET  /api/status` | 五个智能体状态 |
+| `POST /api/task` | 执行任务 `{task, agent_id}` |
+| `GET  /api/thoughtchain/{agent}/chain` | 推理链 |
+| `GET  /api/thoughtchain/{agent}/summary` | 推理链摘要 |
+| `GET  /api/harness/{agent}/status` | 线束阈值/权重/策略 |
+| `GET  /api/harness/{agent}/policy` | 完整策略 YAML |
+| `WS   /ws/harness` | 实时线束事件流 |
+
+(完整 85 个端点见 `foxclaw/api.py`,含财务/学习/行程内核与 AHS 相关接口。)
+
+## 八、环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `DEEPSEEK_API_KEY` / `ANTHROPIC_API_KEY` | 大模型 key,不配则 stub |
+| `FOXCLAW_PROVIDER` | 显式指定 provider(deepseek/anthropic…) |
+| `FOXCLAW_DATA_DIR` | 数据目录 |
+| `FOXCLAW_SHADOW_ROUNDS` | 影子校准轮数 |
+| `FOXCLAW_API_KEY` | **可选鉴权**:设了则 `/api/*` 与 `/knowledge/*` 需带 `X-API-Key`(否则 401);WS 用 `?key=`。**不设=无鉴权,仅回环地址安全。** |
+| `FOXCLAW_HOST` / `FOXCLAW_PORT` | `python -m foxclaw.api` 入口的绑定地址/端口。**默认 `127.0.0.1:8000`。** |
+| `FOXCLAW_ALLOW_INSECURE` | 设为 `1` 允许「非回环 + 无鉴权」启动(不推荐)。 |
+| `FOXCLAW_CORS_ORIGINS` | 允许的跨源来源(逗号分隔)。**默认仅回环**(localhost/127.0.0.1/[::1],任意端口);显式设 `*` 才全开(不推荐)。 |
+| `FOXCLAW_SHARED_WRITE_MODE` | 共享层写入策略模式:**`audit`(默认)只发 `memory.shared.write` 事件、不拦截**;`warn` 额外打告警;`enforce` 真正拒绝(抛 `SharedWriteDenied`)。默认 audit 是因为现有 8 处合法共享写入需要先在真实流量上验证策略表,再切拦截。见 `foxclaw/core/shared_write.py`。**灰度推进前先跑 `python tools/shared_write_audit.py`**(端到端验收:8 处真实写入零误伤 + 5 类越界注入被识别,退出码 0 才算过)。 |
+| `FOXCLAW_SHARED_WRITE_AUDIT` | 共享层审计**落盘**开关(默认开):把 `memory.shared.write` 事件逐条 JSON 追加到 `{数据目录}/audit/shared_write.jsonl`,供切 enforce 前积累真实流量样本(脊柱 history 是 1000 条环形缓冲,会被高频事件冲掉)。设 `0` 关闭。判读:文件里 `allowed=false` 的每行逐条看,全为真越界且无一条误伤 → 可切 `enforce`。 |
+| `FOXCLAW_GOVERNANCE_AUDIT` | 治理审计**总流**开关(默认开,批次 3):Harness/Permission/Orchestration/Skill 四层裁决统一记 `governance.decision` 事件(WS 可见)+ 落盘 `{数据目录}/audit/governance.jsonl`。每条带 `decision_id`(本次裁决 ID)与 `correlation_id`(跨层关联键:权限裁决的 decision_id 挂到 skill 执行审计上;协商多轮共用 req.id)。设 `0` 关闭(各层自动跳过,零开销)。 |
+| `FOXCLAW_SHADOW_PROMOTE_MIN_OBS` | 影子规则升迁所需观察次数(默认 50,批次 4 P0-1):BLOCK 产生的规则候选先进入 `shadow_rules`(**不生效**),同维度场景累计观察满 N 次后按证据 promote(生效)/discard(误伤率>0.3 或零影响)。未达标前规则只观察不拦截——这是「在线无验证学习」的护栏。回滚用 `harness.rollback(rule_id)`;全轨迹见 policy YAML 的 `history` 段。 |
+| `FOXCLAW_SKIP_DOTENV` | 设为 `1` 则**完全不加载项目根目录 `.env`**,只用进程环境变量。**专供测试/CI**:`.env` 里若带真实 Key 或 `FOXCLAW_MCP_SERVER=1` / `FOXCLAW_API_KEY`,会污染测试判定(同代码在不同机器结果不同)、让测试真的打外部 API 并写进真实数据目录。`tests/run_all.py` 已默认设 `1`。**本地开发不要设。** |

package/python/docs//351/205/215/347/275/256/346/214/207/345/215/227.md

@@ -0,0 +1,152 @@
+# Foxclaw 配置指南
+
+所有密钥(Key)统一在项目根目录的 `.env` 文件里配置,不写死在代码中。
+这样你的 Key 安全(不随代码分发),换 Key 也只改一处。
+
+## 三步开始
+
+1. **复制模板**
+
+   把项目根目录的 `.env.example` 复制一份,改名为 `.env`:
+   ```powershell
+   # Windows
+   Copy-Item .env.example .env
+   ```
+   ```bash
+   # macOS / Linux
+   cp .env.example .env
+   ```
+
+2. **填入你的 Key**(用文本编辑器打开 `.env`,等号后面填,不要加引号)
+
+3. **启动**
+   ```powershell
+   foxclaw serve
+   ```
+   浏览器打开 http://localhost:8000(默认只监听 `127.0.0.1:8000`,`--host` / `--port` 可改)。
+
+   想先确认配置有没有读对:
+   ```powershell
+   foxclaw config check
+   ```
+
+启动时看日志确认:
+- `✓ 已加载配置文件 .env` —— .env 被读到了
+- `✓ 模型路由: deepseek（deepseek-chat）` —— 模型 Key 生效
+- 若显示 `⚠ 模型路由: ... 降级 stub` —— 会注明原因(缺 Key 或缺库)
+
+## 各项 Key 说明
+
+### 大模型(至少配一个,系统才真实工作)
+
+配任意一个,系统自动探测启用。多个都配时按优先级:Claude → GPT → DeepSeek → Gemini → 通义 → 本地。
+
+| 配置项 | 模型 | 获取地址 | 额外依赖 |
+|--------|------|----------|----------|
+| `DEEPSEEK_API_KEY` | DeepSeek | platform.deepseek.com | `pip install openai` |
+| `ANTHROPIC_API_KEY` | Claude | console.anthropic.com | 已内置 |
+| `OPENAI_API_KEY` | GPT | platform.openai.com | `pip install openai` |
+| `GOOGLE_API_KEY` | Gemini | aistudio.google.com | `pip install -e ".[gemini]"` |
+| `DASHSCOPE_API_KEY` | 通义千问 | dashscope.aliyun.com | `pip install openai` |
+| `LOCAL_LLM_BASE` | 本地模型 | Ollama/vLLM 的地址 | `pip install openai` |
+
+不配任何模型 Key 也能运行,但 LLM 回复是占位文本(stub),且漂移检测不完整。
+
+### 高德地图(行政 Agent 用,两个 Key 功能不同)
+
+在高德开放平台(lbs.amap.com)控制台创建,**注意要建两个不同类型的 Key**:
+
+| 配置项 | 类型 | 作用 |
+|--------|------|------|
+| `AMAP_MAPS_API_KEY` | Web服务 | 后端:查真实路线时间、地址转坐标、POI 搜索 |
+| `AMAP_JS_KEY` | Web端(JS API) | 前端:画真实地图底图 |
+| `AMAP_JS_SCODE` | (安全密钥) | 前端:2021 年后申请的 JSAPI Key 必须配,与上面配对 |
+
+- 只配 `AMAP_MAPS_API_KEY`:路线时间真实,但前端地图是 SVG 示意图
+- 只配 `AMAP_JS_KEY` + `AMAP_JS_SCODE`:前端真地图,但路线时间是估算
+- 三个都配:行政 Agent 完整(真实路线 + 真地图)
+- 都不配:地图降级为 SVG 坐标示意图,路线用直线估算
+
+### 运行参数(可选)
+
+| 配置项 | 说明 | 默认 |
+|--------|------|------|
+| `FOXCLAW_MODEL` | 强制指定模型名(如 deepseek-reasoner) | 各 provider 默认 |
+| `FOXCLAW_DATA_DIR` | 数据目录 | ./foxclaw_data |
+| `FOXCLAW_SHADOW_ROUNDS` | Harness 影子校准轮数 | 20 |
+
+### V2 高级开关(可选,**默认全关**,按需 opt-in)
+
+这些是 V2 架构引入的旋钮,不配则行为与之前一致(安全默认)。
+
+| 配置项 | 说明 | 默认 |
+|--------|------|------|
+| `FOXCLAW_MAX_CONCURRENCY` | 微内核调度器并发配额(背压);留空=无上限 | 无上限 |
+| `FOXCLAW_PIPELINE_SKILL_DISPATCH` | 允许 Agent 在认知管线内**自主调用工具**(只读自动、有副作用挂起等确认);`=1` 开启 | 关 |
+| `FOXCLAW_TRUTH_TO_HKC` | 执行真值经 KDE→KEE **结晶进 HKC**(有 LLM 成本);`=1` 开启 | 关 |
+| `FOXCLAW_FINANCE_LLM_ARBITER` | 财务守门人对**模糊金额**叠加 LLM 复核(只 approve→confirm,永不 reject);`=1` 开启 | 关 |
+
+### 安全 / 部署(可选)
+
+| 配置项 | 说明 | 默认 |
+|--------|------|------|
+| `FOXCLAW_API_KEY` | 设了则除 `/`、`/health`、`/docs` 外所有请求需带 `X-API-Key` 头;不设=开放(本地默认) | 无(开放) |
+| `FOXCLAW_CORS_ORIGINS` | 逗号分隔的允许来源,收紧 CORS | `*` |
+| `FOXCLAW_BROWSER_HEADLESS` | 浏览器子系统无头模式;`=0` 显示窗口 | 1(无头) |
+
+### 运维 / 观测开关(可选,默认值已够用)
+
+这些开关代码里都会读取,但常规使用无需改动;排查问题或对接监控时再配。
+(此前有 22 个开关只存在于代码里、文档未收录,排查时只能翻源码 —— 现在补在这里。)
+
+| 配置项 | 说明 | 默认 |
+|--------|------|------|
+| `FOXCLAW_GATEWAY_RATE` | 统一网关每客户端每分钟请求数 | 600 |
+| `FOXCLAW_GATEWAY_QUOTA` | 统一网关每客户端每小时配额 | 20000 |
+| `FOXCLAW_MAX_BODY_MB` | 请求体大小上限(MB) | 32 |
+| `FOXCLAW_STREAM_RATE` | SSE 流式接口每分钟次数上限 | 60 |
+| `FOXCLAW_STREAM_CONCURRENCY` | SSE 流式接口并发上限 | 4 |
+| `FOXCLAW_TRACE_SAMPLE` | 链路追踪采样率(0~1) | 0(不采样) |
+| `FOXCLAW_TRACE_SLOW_MS` | 慢请求阈值(毫秒),超过即标记 | 1000 |
+| `FOXCLAW_TRACE_RETAIN` | 内存保留 span 数(有界环形缓冲) | 5000 |
+| `FOXCLAW_OTLP_ENDPOINT` | OTLP 导出地址;**不配=完全关闭** | 关 |
+| `FOXCLAW_OTLP_SERVICE` | OTLP `service.name` | `foxclaw` |
+| `FOXCLAW_MCP_RATE_READ` | 内置 MCP server 只读工具每分钟上限 | 120 |
+| `FOXCLAW_MCP_RATE_AGENT` | `ask_foxclaw` 每分钟上限 | 20 |
+| `FOXCLAW_MCP_AGENTS` | 额外暴露 `ask_foxclaw`(会驱动 Agent);`=1` 开启 | 关 |
+| `FOXCLAW_ROUTE_SKILL` | 管线内技能自动路由;`=0` 关闭 | 开 |
+| `FOXCLAW_LLM_PLAN` | 主管优先用 LLM 规划;`=1` 开启 | 关 |
+| `FOXCLAW_LLM_REPLAN` | 失败步骤反思重规划;`=1` 开启 | 关 |
+| `FOXCLAW_EVIDENCE_MODEL` | 证据链使用的模型(覆盖默认) | 跟随主模型 |
+| `FOXCLAW_DLP_SEMANTIC` | 输出 DLP 语义比对;`=1` 开启 | 关 |
+
+守门人(Guardian)相关 —— 把动作裁决/凭证代注入挪到独立进程,默认关闭:
+
+| 配置项 | 说明 | 默认 |
+|--------|------|------|
+| `FOXCLAW_GUARDIAN` | `=1` 启用独立守门人进程 | 关 |
+| `FOXCLAW_GUARDIAN_DATA_DIR` | 守门人数据目录(由主进程透传) | 跟随 `FOXCLAW_DATA_DIR` |
+| `FOXCLAW_GUARDIAN_SECRETS` | 守门人侧凭证表(JSON)路径 | 无 |
+| `FOXCLAW_GUARDIAN_MCP_SERVERS` | 守门人侧 MCP 配置持久化文件 | 默认路径 |
+| `FOXCLAW_GUARDIAN_SECRET_<NAME>` | 按名字注入的单条凭证 —— 注意是**前缀**,不是独立开关 | 无 |
+
+## 安全提示
+
+- `.env` 已加入 `.gitignore`,不会被 git 提交或随代码分发
+- 不要把 `.env` 发给别人或上传到公开仓库
+- 若 Key 不慎泄露,去对应平台重置(作废旧的,生成新的)
+
+## 常见问题
+
+**Q: 启动显示 stub 降级,但我配了 Key?**
+- 检查日志里降级原因。最常见是缺库:DeepSeek/GPT/通义需 `pip install openai`
+- 确认 `.env` 在项目根目录(和 `pyproject.toml` 同级),不是在 `foxclaw/` 里
+- 确认等号后面没加引号、没多空格
+
+**Q: 地图加载不出来(空白或报错)?**
+- 按 F12 看浏览器 Console 报错
+- `INVALID_USER_SCODE` → 安全密钥(AMAP_JS_SCODE)没配或配错
+- `USERKEY_PLAT_NOMATCH` → JSAPI Key 类型不对(必须是「Web端(JS API)」)
+
+**Q: 端口被占用(10048)?**
+- 上一个进程没关。先 `taskkill /F /IM python.exe`(Windows)再启动

package/python/evals/governance/README.md

@@ -0,0 +1,61 @@
+# Agent 治理评测（M1 · 造证据）
+
+> 由 [`docs/开发路线图.md`](../../docs/开发路线图.md) M1 落地。目的:把护城河的四类主张
+> ——漂移拦得住、循环停得下、崩了认得出、越用越准——从"机制存在"变成**可复现的量化证据**。
+> 全程**离线**:不调用任何 LLM、不联网(语义向量用本地缓存模型,缺失则降级哈希嵌入)。
+
+## 怎么跑
+
+```bash
+# 完整评测(产出 report.json + convergence.svg)
+HF_HUB_OFFLINE=1 python evals/governance/run_evals.py
+
+# 冒烟(纳入全量回归 run_all.py,防评测骨架腐坏)
+python tests/test_evals_smoke.py
+```
+
+## 测什么 / 指标口径
+
+| 维度 | 指标 | 口径 |
+|---|---|---|
+| 漂移检测（语义/工具/范围） | `flag_recall` | 对抗动作被**检出**(WARN+)的比例——漂移感知到了吗（主门槛 ≥0.8） |
+| | `hard_fpr` | 正常任务被 **BLOCK** 的比例——唯一真正有害的误报（主门槛 ≤0.15） |
+| | `block_recall` | 对抗动作被 BLOCK 的比例——是否升级到硬停（信息项） |
+| | `soft_fpr` | 正常任务被 WARN 的比例——软噪声，**不阻断执行**（质量项） |
+| 循环检测 | 触发轮次 | repeat / ping_pong / no_progress 各在第几轮被判 stuck；正常多样调用不误报 |
+| 崩溃恢复 | `correct` / `non_destructive` | 中断任务识别正确（boot_id 防 pid 复用）；探测外部活进程**不误杀** |
+| 自学习 | `tool_weight_curve` / `converged` | 重复越权下 tool 权重单调收紧、拦截率恒 1.0、正常任务无硬误报 |
+
+**关键区分:BLOCK 是硬停(阻断行动),WARN 只降低置信度、不阻断。** 因此有害误报只算 `hard_fpr`;
+benign 被 WARN 记为 `soft_fpr`(质量信号,非失败)。这是指标语义的正确划分,不是为了让评测好看。
+
+## 首版结果（2026-07-03，离线，all-MiniLM-L6-v2）
+
+- 漂移检测:三维 `flag_recall` 均 **1.0**、`hard_fpr` 均 **0.0** —— 漂移全被感知、正常任务零硬误报。
+- 循环:repeat@3 / ping_pong@4 / no_progress@3 全检出，正常调用不误报。
+- 恢复:中断识别正确 + 非破坏（修复后的 `_pid_alive` 不再误杀）。
+- 自学习:tool 权重 `0.33→0.53` 单调收紧，收敛 = True。
+
+### 证据型发现（评测自动沉淀）
+
+1. **语义维度对中文偏弱**:`semantic` 的 `flag_recall=1.0` 但 `block_recall=0.0`——默认**英文**
+   `all-MiniLM-L6-v2` 压缩了中文语义距离,跑题够得着 WARN、够不着 BLOCK。这正好印证系统的
+   **「模型无关」原则**:应允许换中文/多语 embedding。
+   **✅ 已兑现（2026-07-03）**:`compare_embeddings.py` 换多语 `paraphrase-multilingual-MiniLM-L12-v2`
+   重跑同一中文场景——**中文跑题硬拦率 `block_recall` 0.0 → 1.0**（向量层:跑题漂移 0.48→0.99）。
+   换模型一行搞定:`FOXCLAW_EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2`。代价是更敏感
+   （benign 软误报 `soft_fpr` 升到 ~0.67,但只 WARN 不阻断,`hard_fpr` 仍 0）。见 `compare_embeddings.py`。
+2. **工具场景软误报偏高**(`soft_fpr≈0.67`,全为 WARN 非 BLOCK):同源于中文语义距离偏大;
+   硬误报 `hard_fpr=0`,不影响执行。自学习把权重从 semantic 移向 tool 后,该软噪声会**自行下降**
+   (见 `benign_soft_warn_curve`)——是学习的良性副作用。
+
+## 产物
+
+- `report.json` —— 全部指标 + `findings` + 逐 probe 明细(可 diff、可追踪回归)。
+- `convergence.svg` —— 自学习 tool 权重收敛曲线(零依赖手绘 SVG)。
+
+## 下一步（把门槛往上抬）
+
+- ~~接入中文/多语 embedding，重测 `semantic.block_recall`~~ ✅ 已做（`compare_embeddings.py`，0→1.0）；
+- 扩充对抗任务集（更多跑题/越权/蔓延变体），把 recall/fpr 做成随样本量稳定的曲线；
+- 与 M3「治理中间件」联动：把这份评测数据作为对外可信度的卖点。