foxclaw 0.1.0 → 0.1.3

package/python/bench/vector_ivf_upgrade.py

@@ -0,0 +1,128 @@
+"""vector 索引升级 + 性能对比:Flat vs IVF(1500 mock KU, stub backend)
+
+目的:验证 HKC_VECTOR_IVF_THRESHOLD 触发的 Flat → IVF 自动升级,
+     并对比两种索引在 500 / 1500 mock KU 下的检索延迟。
+
+用法:
+    python bench/vector_ivf_upgrade.py
+
+可调参数:
+    HKC_VECTOR_IVF_THRESHOLD  默认 500(本脚本覆盖)
+    IVF_NLIST                 自定义 nlist(可选)
+    TOTAL_KUS                 总 mock KU 数,默认 1500
+"""
+from __future__ import annotations
+
+import os
+import statistics
+import sys
+import tempfile
+import time
+from pathlib import Path
+from types import SimpleNamespace
+
+os.environ["HKC_VECTOR_IVF_THRESHOLD"] = "500"
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from vendor.hkc.hkc_search.vector_search import VectorIndex
+from vendor.hkc.hkc_search.embedding_backends import StubBackend
+
+
+def make_ku(i: int) -> SimpleNamespace:
+    """构造 mock KU,字段匹配 vector_search._ku_text() 期望的 4 项: name/summary/tags/statement。"""
+    return SimpleNamespace(
+        ku_id     = f"ku_{i:06d}",
+        name      = f"entity_{i}",
+        summary   = f"summary of entity {i} about topic {i % 50}",
+        tags      = [f"tag_{i % 10}", f"category_{i % 5}"],
+        statement = f"fact {i}: something interesting about subject {i}",
+    )
+
+
+def bench_search(idx, query: str, n: int = 100, top_k: int = 10) -> tuple[float, float, float]:
+    """跑 n 次 search,返 (median_ms, min_ms, max_ms)。"""
+    times = []
+    for _ in range(n):
+        t0 = time.perf_counter()
+        idx.search(query, top_k=top_k)
+        times.append((time.perf_counter() - t0) * 1000)
+    return statistics.median(times), min(times), max(times)
+
+
+def main() -> None:
+    backend = StubBackend(dim=384)
+    threshold = int(os.environ["HKC_VECTOR_IVF_THRESHOLD"])
+
+    print("=" * 70)
+    print(f"backend       : {backend.name}")
+    print(f"threshold     : HKC_VECTOR_IVF_THRESHOLD = {threshold}")
+    print(f"upgrade to    : IndexIVFFlat(nlist≈√N, nprobe=16)")
+    print("=" * 70)
+
+    N = 5000
+    print(f"\n构造 {N} 条 mock KU...")
+    kus = [make_ku(i) for i in range(N)]
+
+    idx = VectorIndex(backend=backend)
+    print(f"index type 初始: {type(idx._index).__name__}")
+
+    phase1_n = threshold - 1
+    print(f"\n[Phase 1] append {phase1_n} 条(< {threshold},应保持 Flat)...")
+    for ku in kus[:phase1_n]:
+        idx.append_ku(ku)
+    print(f"  index type: {type(idx._index).__name__}, ntotal={idx._index.ntotal}")
+    med, mn, mx = bench_search(idx, "find something about topic 7")
+    print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
+
+    print(f"\n[Phase 2] append 第 {threshold} 条(应触发升级)...")
+    t0 = time.perf_counter()
+    idx.append_ku(kus[phase1_n])
+    upgrade_ms = (time.perf_counter() - t0) * 1000
+    print(f"  append(含升级)耗时: {upgrade_ms:.1f}ms")
+    print(f"  index type: {type(idx._index).__name__}, ntotal={idx._index.ntotal}")
+    if hasattr(idx._index, "nlist"):
+        print(f"  IVF nlist={idx._index.nlist}, nprobe={idx._index.nprobe}")
+    med, mn, mx = bench_search(idx, "find something about topic 7")
+    print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
+
+    rest = N - threshold
+    print(f"\n[Phase 3] append {rest} 条(应直接 add 到 IVF)...")
+    t0 = time.perf_counter()
+    for ku in kus[threshold:]:
+        idx.append_ku(ku)
+    bulk_ms = (time.perf_counter() - t0) * 1000
+    print(f"  {rest} 条 append 耗时: {bulk_ms:.1f}ms(平均 {bulk_ms/rest:.2f}ms/条)")
+    print(f"  index type: {type(idx._index).__name__}, ntotal={idx._index.ntotal}")
+    med, mn, mx = bench_search(idx, "find something about topic 7")
+    print(f"  search ×100: median={med:.2f}ms  min={mn:.2f}ms  max={mx:.2f}ms")
+
+    print(f"\n[Phase 4] save/load roundtrip(IVF 持久化)...")
+    with tempfile.TemporaryDirectory() as td:
+        p = str(Path(td) / "vec")
+        t0 = time.perf_counter()
+        idx.save(p)
+        save_ms = (time.perf_counter() - t0) * 1000
+        idx2 = VectorIndex(backend=backend)
+        t0 = time.perf_counter()
+        ok = idx2.load(p)
+        load_ms = (time.perf_counter() - t0) * 1000
+        n_loaded = idx2._index.ntotal if idx2._index else 0
+        type_loaded = type(idx2._index).__name__ if idx2._index else "None"
+        print(f"  save: {save_ms:.1f}ms  load: {load_ms:.1f}ms  ok={ok}")
+        print(f"  loaded ntotal={n_loaded}, type={type_loaded}")
+        if n_loaded != N:
+            print(f"  [FAIL] 数据丢失! 期望 {N} 实际 {n_loaded}")
+        elif "FlatIP" in type_loaded:
+            print(f"  [FAIL] IVF 没保存,降回 FlatIP")
+        else:
+            print(f"  [OK] IVF 完整保存/加载(ntotal={n_loaded}, type={type_loaded})")
+
+    print("\n" + "=" * 70)
+    print("[OK] benchmark 完成")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

package/python/docs/CHANNELS.md

@@ -0,0 +1,195 @@
+# Foxclaw 消息平台接入说明
+
+把 Foxclaw 接到消息平台,让用户在微信 / 飞书 / Telegram / Discord 里直接和你的认知系统对话。
+
+## 架构总览
+
+```
+用户在某渠道发消息
+   → 渠道适配器 normalize 成标准消息(InboundMessage)
+   → ChannelDispatcher 交给主管 Agent 处理
+   → 主管 run_task 思考、调度子 Agent
+   → 回复通过同一渠道发回
+```
+
+三个角色各司其职:**适配器**只管收发(翻译平台格式 ↔ 标准格式),**主管**只管思考,**调度器(ChannelDispatcher)**把两者接起来。
+
+所有适配器都遵循同一套接口(`normalize` / `send` / `reply`),但**内部各按平台官方规范实现**——微信是长轮询、飞书是事件订阅 webhook、Telegram 是 getUpdates、Discord 是 Gateway WebSocket,互不相同。
+
+## 通用启动方式
+
+```python
+from foxclaw import Foxclaw
+from foxclaw.channels.dispatcher import ChannelDispatcher
+
+os_ = Foxclaw(data_dir="./data")
+dispatcher = ChannelDispatcher(os_.supervisor)
+
+# 注册渠道(下面每个平台示例都用这个 dispatcher)
+dispatcher.register_channel(adapter)   # adapter 见下文各平台
+```
+
+`register_channel` 会自动把适配器的入站消息接到主管闭环——之后该渠道收到的每条消息都会经主管处理并自动回复。
+
+---
+
+## Telegram(最易跑通,建议先用它验证)
+
+**拿 token:** Telegram 里找 `@BotFather` → 发 `/newbot` → 按提示拿到 bot token。
+
+```python
+from foxclaw.channels.telegram import TelegramAdapter
+
+tg = TelegramAdapter(bot_token="123456:ABC-DEF...")
+dispatcher.register_channel(tg)
+
+# 验证 token
+print(tg.verify_token().ok)
+
+# 持续收消息(轮询):放进循环
+import time
+while True:
+    tg.poll_once()      # 拉一批新消息,自动经主管处理并回复
+    time.sleep(1)
+```
+
+收发模型:**getUpdates 长轮询**,无需公网回调地址,本地直接能跑。
+
+---
+
+## 微信(iLink Bot API)
+
+照 Tencent 官方开源插件 [`Tencent/openclaw-weixin`](https://github.com/Tencent/openclaw-weixin) 公开的 iLink Bot API 协议实现。
+
+**拿 token:** token 需用微信官方那套**扫码登录**获得(扫码登录在微信侧,Foxclaw 不复现登录,只复现登录后的消息收发)。可用 OpenClaw 官方 CLI 扫码:
+```bash
+openclaw channels login --channel openclaw-weixin   # 扫码后本地拿到 token
+```
+
+```python
+from foxclaw.channels.weixin import WeixinAdapter
+
+wx = WeixinAdapter(token="<扫码登录得到的 token>")
+dispatcher.register_channel(wx)
+
+# 持续收消息(长轮询)
+while True:
+    wx.poll_once()      # getUpdates 长轮询,自动处理并回复
+```
+
+收发模型:**getUpdates 长轮询**。回复时会自动带回 `context_token`(微信要求),已内部处理。`verify_token(ilink_user_id)` 需提供真实用户 ID 才能探测。
+
+---
+
+## 飞书 / Lark(事件订阅 webhook)
+
+**拿凭证:** 飞书开放平台 → 创建企业自建应用 → 拿 `App ID` + `App Secret`;在「事件订阅」里配置回调地址,记下 `Verification Token` 和 `Encrypt Key`(若开启加密)。事件订阅勾选 `im.message.receive_v1`。
+
+飞书是**平台主动推事件到你的回调地址**,所以需要一个公网可达的 webhook 端点(FastAPI 路由)。
+
+```python
+from foxclaw.channels.feishu import FeishuAdapter
+
+fs = FeishuAdapter(
+    app_id="cli_xxx",
+    app_secret="xxx",
+    verification_token="xxx",   # webhook 模式需要
+    encrypt_key="xxx",          # 若开启加密
+)
+dispatcher.register_channel(fs)
+
+# FastAPI 路由接飞书事件回调
+from fastapi import FastAPI, Request
+app = FastAPI()
+
+@app.post("/feishu/events")
+async def feishu_events(request: Request):
+    raw_body = await request.body()
+    payload = await request.json()
+    # handle_event 内部完成:URL验证 / 解密 / 验签 / 标准化 / 主管处理
+    return fs.handle_event(payload, headers=dict(request.headers), raw_body=raw_body)
+```
+
+收发模型:**事件订阅 webhook**。`handle_event` 自动处理 URL 验证(challenge)、AES 解密、签名验签。发消息用 `tenant_access_token`(自动缓存 + 过期前刷新)。
+
+> 注意:飞书加密事件解密需要 `cryptography` 库(或 pycryptodome)。环境一般已自带 cryptography。
+
+---
+
+## Discord(Gateway WebSocket)
+
+**拿 token:** Discord Developer Portal → 创建 Application → Bot → 拿 bot token。**务必在 Bot 设置里开启 `MESSAGE CONTENT INTENT`**(否则收不到消息文本)。把 Bot 邀请进你的服务器。
+
+```python
+from foxclaw.channels.discord import DiscordAdapter
+
+dc = DiscordAdapter(bot_token="...")
+dispatcher.register_channel(dc)
+
+# 验证 token(同时记录 bot 自身 ID,用于忽略自己的消息)
+print(dc.verify_token().ok)
+
+# 持续收消息(Gateway WebSocket,异步)
+import asyncio
+asyncio.run(dc.connect_gateway())   # 需要 websockets 库
+```
+
+收发模型:**Gateway WebSocket 长连接**(收) + **REST API**(发)。`connect_gateway` 实现了 HELLO→IDENTIFY→心跳→消息分发的最小闭环。生产环境也可换成成熟的 discord.py,再把消息喂给 `dc.normalize()`。
+
+> 需要 `websockets` 库:`pip install websockets`
+
+---
+
+## 备选:对接 OpenClaw 网关
+
+若你已在用 OpenClaw(它接了某些渠道),可让 Foxclaw 通过 OpenClaw 网关收发,而不必自己实现那些渠道。
+
+```python
+from foxclaw.channels.openclaw_bridge import OpenClawBridgeAdapter
+
+bridge = OpenClawBridgeAdapter(gateway_url="http://127.0.0.1:8080", api_token="...")
+dispatcher.register_channel(bridge)
+```
+
+OpenClaw 负责渠道接入,Foxclaw 负责认知处理,两者通过 HTTP 桥接。
+
+---
+
+## 多渠道同时运行
+
+一个 dispatcher 可注册多个渠道,各自独立收发,共用同一个主管:
+
+```python
+dispatcher.register_channel(tg)     # Telegram(轮询)
+dispatcher.register_channel(wx)     # 微信(轮询)
+dispatcher.register_channel(dc)     # Discord(WebSocket)
+# 飞书走 FastAPI webhook 路由
+
+# 轮询类渠道各起一个循环/线程;WebSocket/webhook 类按各自方式跑
+```
+
+**会话隔离:** 默认按 `渠道:会话:发送者` 隔离(不同渠道的对话互不串)。若想做"跨渠道同一记忆"(同一用户在飞书和微信共享上下文),可改 `dispatcher._session_key` 只用 `sender_id`。
+
+---
+
+## 依赖小结
+
+| 渠道 | 必需依赖 | 凭证 |
+|---|---|---|
+| Telegram | httpx | bot token(@BotFather) |
+| 微信 | httpx | 扫码登录 token |
+| 飞书 | httpx, cryptography | App ID/Secret + (加密时)Encrypt Key |
+| Discord | httpx, websockets | bot token + Message Content Intent |
+| OpenClaw 桥 | httpx | OpenClaw 网关地址 + token |
+
+```bash
+pip install httpx cryptography websockets
+```
+
+---
+
+## 安全提示
+
+- **凭证不要硬编码**:token / app_secret 用环境变量或配置文件注入,别写进代码或提交到 Git。
+- 飞书 webhook 建议保留**签名验签**(开启 Encrypt Key),适配器会自动验。
+- 各渠道的访问控制(谁能跟 bot 对话)目前在主管侧统一处理;如需更细的白名单,可在 `dispatcher.handle` 里按 `msg.sender_id` 加判断。

package/python/docs/GOVERNANCE.md

@@ -0,0 +1,164 @@
+# Foxclaw 运行时治理能力说明
+
+这组能力借鉴 OpenClaw 等成熟 Agent 系统的设计原理,用 Python 适配 Foxclaw 实现,目标是让系统在真实运行(消息重发、进程崩溃、长任务、死循环)中保持**可靠、可审计、不丢不重**。
+
+六项能力分两类:**已接入主路径、现在就生效**的(幂等、重启恢复、循环检测),和**基础设施、按需启用**的(上下文压缩、钩子标准化、干预队列)。
+
+---
+
+## 一、幂等守卫(Idempotency)— 已生效
+
+**解决:** 消息平台天生会重发(网络抖动、平台重试、轮询游标边界)。没有幂等,用户会收到重复回复、同一操作被记两次。
+
+**原理:** 给"只应发生一次"的操作算一个稳定 key,执行前**原子查重**——处理过就跳过,没处理才执行并记录。
+
+**核心接口**(`foxclaw/core/idempotency.py`):
+```python
+from foxclaw.core.idempotency import IdempotencyGuard, make_key
+
+guard = IdempotencyGuard(ttl_seconds=3600)        # 可选 persist_path 跨重启
+key = make_key("message", channel, message_id, sender_id)
+if guard.check_and_mark(key):     # 原子:首次返回 True(执行),重复返回 False(跳过)
+    do_the_work()
+```
+
+**已接入:** `ChannelDispatcher.handle` 自动按 `channel+message_id+sender` 去重;无 message_id 的消息退化为"渠道+发送者+内容+10秒时间窗"兜底。
+
+**设计要点:**
+- `check_and_mark` 在同一把锁里完成查重+标记(防并发重发都去执行,50线程压测验证恰好1个成功)
+- TTL 过期清理 + 容量上限 LRU 淘汰(防无限膨胀)
+- 可选落盘(原子替换写),跨进程重启仍识别"处理过了"
+
+---
+
+## 二、重启恢复(Restart Recovery)— 已生效
+
+**解决:** 长任务(多 Agent 链、财务分析)跑到一半进程崩了/重启,任务凭空消失,记忆可能留下半完成的脏数据。
+
+**原理:** 启动时主动识别"上次还在进行、但持有它的进程已不在"的任务,**诚实标记为中断**,而不是装无事。契合 Foxclaw"可审计、可信"的定位。
+
+**核心接口**(`foxclaw/core/recovery.py`):
+```python
+from foxclaw.core.recovery import RestartRecovery
+
+rec = RestartRecovery(log_path="data/task_log.jsonl")
+rec.task_started(task_id, description)    # 任务开始(落 in_progress)
+rec.task_finished(task_id, status="done")  # 结束(done/failed)
+interrupted = rec.scan_interrupted()       # 启动时扫描:返回被中断的任务列表
+```
+
+**已接入:** `Foxclaw` 启动时自动扫描,检测到中断任务会打印提示;主管任务经 base 模板的
+生命周期钩子(`_on_session_started`/`_on_task_settled`,P1-1)自动记录开始/结束
+(正常终态标 done、未兜底异常标 failed;`run_task` 与 `run_task_stream` 两条路径都记账)。
+
+**设计要点:**
+- **boot_id 防 pid 复用**:每次启动生成唯一 ID,判据是"非本次启动的 in_progress 任务=被中断"。比单纯靠 pid 可靠——pid 会被 OS 复用,旧任务的 pid 被新进程占用会导致漏判。
+- JSONL 追加写 + fsync(崩溃安全:单行 append 原子,损坏行自动跳过)
+- `compact_log` 防日志无限膨胀
+
+---
+
+## 三、工具循环检测(Loop Detection)— 已生效
+
+**解决:** 断路器管"失败",但管不了"无进展死循环"——Agent 不报错却陷入重复/横跳/轮询卡死,白烧 token。
+
+**原理:** 监控工具调用历史,检测三种循环模式,多级阈值预警→熔断。
+
+**核心接口**(`foxclaw/harness/loop_detection.py`):
+```python
+from foxclaw.harness.loop_detection import ToolLoopDetector
+
+det = ToolLoopDetector(warning=6, critical=12, circuit_break=20)
+verdict = det.record(tool_name, args, result)   # 每次工具调用后
+if verdict.stuck:
+    print(verdict.detector, verdict.message)     # repeat/ping_pong/no_progress
+if det.should_abort():
+    abort()                                       # 达熔断阈值
+```
+
+**已接入:** `SkillAdapter` 每次工具调用后自动检测,卡死时在结果上附 `loop_warning` 并触发 `on_loop` 钩子。
+
+**三种模式:** `repeat`(同调用连续重复)、`ping_pong`(两调用交替)、`no_progress`(轮询结果无变化,优先级最高,语义最精确)。
+
+---
+
+## 四、上下文压缩(Compaction)— 基础设施
+
+**解决:** 长对话撑爆上下文窗口。
+
+**原理:** 渐进降级压缩,绝不崩——LLM 完整摘要 → 排除超大消息的部分摘要 → 截断兜底。始终保留系统提示 + 最近 N 轮 + 关键标识符(ID/金额)。
+
+**核心接口**(`foxclaw/core/compaction.py`):
+```python
+from foxclaw.core.compaction import Compactor
+
+c = Compactor(router=model_router, max_tokens=6000, keep_recent=4)
+if c.needs_compaction(messages):
+    result = c.compact(messages)     # result.messages 是压缩后的列表
+```
+
+**设计要点:** 压缩后校验是否真变小(省不到 10% 就放弃,method=`skipped_ineffective`),避免系统消息过大时压缩反而变大。`router=None` 时直接走截断兜底。
+
+---
+
+## 五、生命周期钩子标准化(Hooks)— 基础设施
+
+**解决:** 钩子点命名零散、阻断权不清晰。
+
+**原理:** 标准生命周期钩子 + 明确的阻断权 + 向后兼容。
+
+**标准钩子点**(`foxclaw/skills/hooks_spec.py`):
+- 会话级:`session_start` → `agent_start` → `agent_end` → `session_end`
+  - `agent_start`(别名 **`pre_reasoning`**)/ `agent_end`(别名 **`task_complete`**)由**认知管线 `run_task`** 触发(E2);`agent_start` 可返回 `additional_context` 注入本次推理(非阻断)。`session_start/end` 由 AHS skill 编排链触发。
+- 工具级:`before_tool_call`(唯一可阻断)→ `after_tool_call` / `on_error` / `on_loop`
+- 消息级:`before_message_write`
+
+```python
+from foxclaw.skills.lifecycle import HookManager
+hm = HookManager()
+hm.register("before_tool_call", my_hook)    # 旧名 pre_skill 也兼容,自动规整
+```
+
+**设计要点:** 只有 `before_tool_call` 有阻断权(返回 `{block:True}` 生效);旧名(pre_skill/post_skill)自动规整为标准名且互通;非法钩子名会记警告(防拼错静默失效)。
+
+---
+
+## 六、干预队列(Steering Queue)— 基础设施(为并行预留)
+
+**解决:** 并行子 Agent 的结果如何安全回收——不丢、不重复。
+
+**原理:** 租约机制。当前多 Agent 顺序执行用不上(直接收集即可);这是为**未来并行子 Agent** 预留的基础设施。
+
+**核心接口**(`foxclaw/core/steering_queue.py`):
+```python
+from foxclaw.core.steering_queue import SteeringQueue
+
+q = SteeringQueue(lease_seconds=30)
+q.publish(requester, source_agent, payload)   # 子任务完成入队
+items = q.lease(requester)                      # 消费者租走(不会被重复租)
+q.ack(item.item_id, item.lease_id)             # 确认处理完移除
+# 过期未 ack 的项自动回到 pending(主任务崩溃兜底)
+# 顺序场景便捷:q.drain(requester) 一次性取走(尊重租约,跳过被租用项)
+```
+
+**设计要点:** 锁内挑选+标记(并发不重复租用);租约过期自动重入队(结果不丢);ack 校验 lease_id(防过期租约误删别人重新租走的项)。
+
+---
+
+## 测试
+
+全部纳入回归(`python tests/run_all.py`):
+- `test_governance.py` — 六项治理能力(幂等并发、boot_id 防复用、租约不重复等)
+- `test_channels.py` — 渠道适配器 + 闭环 + 幂等去重
+
+---
+
+## 设计原则小结
+
+这组能力反复体现几个原则,可供后续开发参考:
+
+- **操作要校验是否真达到目的**:压缩后检查真变小了吗、幂等并发下真只执行一次吗——不假设操作一定有效。
+- **静默失效最危险**:拼错钩子名、解密缺库、消息处理失败被吞——都要让问题可见(警告/last_error),而非默默不工作。
+- **崩溃后不装没事**:重启恢复主动交代中断的任务,契合"可信"定位。
+- **别只信 pid**:进程恢复要用 boot_id 这类不复用的标识,pid 会被 OS 复用。
+- **便捷接口别破坏核心保证**:drain 要尊重租约,否则破坏"不重复"。

package/python/docs/RELEASE.md

@@ -0,0 +1,110 @@
+# 发布流程
+
+> **当前状态(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`、`frontend_src/package.json`)由
+`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.** |