foxclaw 0.1.2 → 0.1.4

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.4";
 
 export default { name, version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foxclaw",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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/.github/workflows/release.yml

@@ -83,6 +83,11 @@ jobs:
             python tools/release_check.py
           fi
 
+      - name: Bundle web UI into package
+        # frontend/ 在仓库根、不属于任何包,不复制就进不了 wheel → pip 装完首页 404。
+        # 漏跑不会构建失败,但下一步的 artifact gate 会拦下来(missing_web_ui)。
+        run: python tools/bundle_web.py
+
       - name: Build wheel + sdist
         run: python -m build --outdir dist
 

package/python/CHANGELOG.md

@@ -0,0 +1,100 @@
+# 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.4 — 2026-11-12
+
+A conflict card can now be dismissed instead of decided, the validator stops reading every Chinese 不 as a negation, each agent gets its own rules file, and the hard boundaries now live in one checkable spec instead of being scattered across prompts.
+
+**Behavior**
+
+- `foxclaw/behavior/behavior.yaml` is a checkpoint list, not a prose spec: every rule that claims code enforcement names a callable that already exists (`foxclaw.kernel.policy_gate:PolicyGate.check_action`, `foxclaw.core.confirm_nonce:ConfirmationBroker.consume`, `foxclaw.core.verify:verify`), and the spec is resolved at load time. A missing target fails startup instead of registering an always-allow stub, so the list cannot drift into decoration.
+- The block is injected first in the system prompt — ahead of the kernel prompt, the role prompt and the per-agent rules. Persona stays where it was (preferences merged into the last user message), so a user-editable preference cannot structurally override a hard boundary.
+- `behavior.local.yaml` in `FOXCLAW_DATA_DIR` can add rules and tighten `enforce`, but weakening or dropping a rule in `prohibitions` / `confirmations` raises. A malformed or stale-version local file is ignored with a warning rather than bricking the app; problems in the built-in file stay fatal.
+- Rules whose code side is not built yet (`no_privacy_upload`, `no_impersonation`) are marked `enforce: prompt` with a `note` saying what is missing, rather than pretending to be enforced.
+- Set `FOXCLAW_BEHAVIOR=0` to turn the whole block off.
+
+**Memory**
+
+- High-sensitivity writes to long-term memory now pass through a deterministic gate: credential / ID-number / health / card-number patterns plus a Luhn check, no model call. `FOXCLAW_SENSITIVE_WRITE_MODE` has three levels — `audit` (default, records only), `warn`, and `enforce`. In `enforce` the content is not stored; it becomes a pending item the user must approve, and `approve_sensitive_write` is the only caller allowed to pass `consent=True`.
+- The classifier deliberately over-blocks: a false positive costs one confirmation, a false negative means the rule does not exist. Ordinary amounts and order numbers are excluded on purpose — otherwise the finance agent would be unusable.
+- `GET /api/memory/pending`, `POST /api/memory/pending/{id}/approve` and `/reject` expose the queue. The memory panel lists what is waiting, with 记住 / 丢弃 buttons, and when a write is held back the agent says so in the thought chain instead of silently dropping it.
+- `confirm_high_sensitivity` is now `enforce: both` in the behavior spec; the checkpoint resolves to the real gate.
+
+**Content safety**
+
+- New gate at `foxclaw/core/content_guard.py`: deterministic, no model call. Both the user request and the model output are checked, and a hit is cut off with a fixed line ("Let's talk about something else." / 「我们换个话题聊聊吧。」) — no explanation, no elaboration, no counter-question, no alternative offered. A refusal must not become a channel for leaking information or continuing the thread.
+- Built-in rules cover **solicitation only** (making drugs or explosives, fraud and money laundering, breaking into someone's systems, forging documents, suicide methods, sexual content involving minors). Narrow wording, low false-positive rate, works out of the box. Mentioning is not asking: a book about the history of explosives, a paper on money-laundering sentencing, an order number, `born in '91` all pass.
+- The platform-review categories (political, sexual, violent) run to tens of thousands of terms; hard-coding them is neither practical nor maintainable as the rules change. Deployers mount an external lexicon through `FOXCLAW_CONTENT_LEXICON` (comma-separated files, one term per line, optional `term<TAB>category`); `tools/build_content_lexicon.py` does the conversion (encoding detection, category filtering, category inferred from the file name, read-back verification), and which categories to mount is their call. **Nothing is checked against it unless it is mounted** — by default only the built-in rules run.
+- `FOXCLAW_CONTENT_GUARD_MODE` has three levels: `enforce` (default), `audit` (records only), `off`. Enforcement is the default because this layer exists to backstop a shipped product; a default that does not fire is not a backstop. The built-in rules are narrow enough not to interrupt ordinary conversation.
+- Normalization defeats full-width characters, zero-width characters and inserted spaces. Pinyin, homophones and character-splitting are explicitly out of scope for a deterministic layer — this is a speed bump, not a wall.
+- Knowledge-base ingestion and attachment bodies are **not** filtered: that is the user's own material. The gate sits on the request and the output only, so a history book or a legal statute is not mistaken for a violation.
+- New `no_harmful_content` rule in the behavior spec (`enforce: both`), and a new §8 "content boundaries" in `KERNEL_PROMPT` spelling out the refusal pattern and the difference between 「material」 and 「instructions」.
+- `docs/CONTENT_GUARD.md` / `docs/CONTENT_GUARD_CN.md` document mounting, lexicon format, conversion and false-positive tuning. No political, sexual or violent list is bundled; mounting one, and which mode to run, is the deployer's decision.
+
+**Agents**
+
+- An agent now loads `foxclaw/agents/rules/<AGENT_ID>/*.md` into its system prompt when it starts. The files are re-read on every prompt assembly, so editing rules needs no code change; the block is appended after the role prompt and yields to the safety rules above it. Set `FOXCLAW_AGENT_RULES=0` to turn it off.
+- Ships with `foxclaw/agents/rules/finance/RULES.md` — Personal Finance Agent Rules v1.0 (data truthfulness, bookkeeping accuracy, privacy, calculation conventions, advice limits, anomaly handling, memory boundaries, supervisor collaboration). The file is package data, so it travels inside the wheel instead of being silently dropped.
+
+**Knowledge**
+
+- `POST /conflicts/{id}/dismiss` and `POST /conflicts/bulk-dismiss` (SDK: `dismiss_conflict` / `dismiss_conflicts`) close a card without picking a winner: both claims stay `active` and nothing is marked `superseded`. A claim that was `disputed` only because of that card goes back to `active` once no open conflict mentions it.
+- Conflict detection no longer flips polarity on topical similarity alone. The negated side now also has to overlap lexically with the other statement (character-bigram Jaccard ≥ 0.40) and stay close in embedding space (cosine ≥ 0.35); both thresholds are constructor parameters (`neg_flip_min_cos`, `neg_flip_min_overlap`).
+- Descriptive `不` / `无` compounds (`不变`, `不同`, `不管`, `不再`, `无需`, `不可观测`, `不可控` …) no longer count as stance negation.
+- The conflict card gained a secondary "false positive" button beside "accept selected claim".
+- `tools/recheck_conflicts.py` re-scores existing open cards with the current rule and batch-closes those that no longer hold. It dry-runs by default; `--apply` submits through the running service, so the in-process conflict set and the vector index stay in step.
+
+## 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,100 @@
+# 更新日志
+
+从 0.1.0 首次公开到当前版本的变更记录，最新的排在最前面。
+
+英文版:[CHANGELOG.md](CHANGELOG.md)。
+
+## 0.1.4 — 2026-11-12
+
+冲突卡可以「判为误判」，不必二选一；判定逻辑也不再见到「不」就当否定；每个 Agent 有了自己的规则文件；硬边界集中到一份可校验的清单，不再散落在各处提示词里。
+
+**行为规范**
+
+- `foxclaw/behavior/behavior.yaml` 是**检查点清单**，不是规范全文：每条声称代码强制的规则都必须指向仓库里已经存在的可调用对象（`foxclaw.kernel.policy_gate:PolicyGate.check_action`、`foxclaw.core.confirm_nonce:ConfirmationBroker.consume`、`foxclaw.core.verify:verify`），加载时解析。解析不到直接启动失败，绝不注册「永远放行」的桩，所以清单不会退化成装饰。
+- 该段注入 system prompt 最前段，排在内核准则、角色职责、规则文件之前。人格仍在原地（偏好合并进最后一条 user 消息），因此用户可改的偏好结构上覆盖不了硬边界。
+- `FOXCLAW_DATA_DIR` 下的 `behavior.local.yaml` 可以新增规则、可以把 `enforce` 收紧；但放宽或省略删除 `prohibitions` / `confirmations` 里的规则会直接报错。本地文件语法写错或版本过期只告警并忽略，不会把应用锁死；内置文件的问题仍然致命。
+- 代码侧尚未实现的规则（`no_privacy_upload`、`no_impersonation`）标成 `enforce: prompt` 并附 `note` 说明缺什么，不假装已经强制。
+- 设 `FOXCLAW_BEHAVIOR=0` 可整体关闭。
+
+**记忆**
+
+- 高敏感内容写入长期记忆前先过一道确定性闸门：凭据 / 证件号 / 健康 / 卡号模式加 Luhn 校验，不调模型。`FOXCLAW_SENSITIVE_WRITE_MODE` 三档：`audit`（默认，只记录）、`warn`、`enforce`。`enforce` 下内容**不落库**，转成待确认项由用户点头；`approve_sensitive_write` 是全仓唯一允许传 `consent=True` 的地方。
+- 判定刻意宁可多拦：误判的代价是用户多点一次确认，漏判则等于这条规矩不存在。普通金额和订单号被明确排除，否则财务 Agent 直接不可用。
+- 新增 `GET /api/memory/pending`、`POST /api/memory/pending/{id}/approve` 与 `/reject`；记忆中心面板列出排队中的写入，可就地「记住」或「丢弃」。写入被拦时 Agent 会在思考链里说明，不静默丢弃。
+- 行为规范里 `confirm_high_sensitivity` 升为 `enforce: both`，检查点指向真实闸门。
+
+**内容安全**
+
+- 新增内容闸门 `foxclaw/core/content_guard.py`：确定性判定，不调模型。用户请求与模型输出两端各过一道，命中即用固定话术切断（「我们换个话题聊聊吧。」/ "Let's talk about something else."），不解释、不延伸、不反问、不给替代方案 —— 拒绝本身不能变成信息泄漏或继续纠缠的入口。
+- 内置规则只覆盖**请求型教唆**（制毒制爆、诈骗洗钱、入侵他人系统、伪造证件、自杀方法、未成年性内容），措辞窄、误伤低，开箱即用。「提及」不算「索要」：讲炸药发展史的书、洗钱量刑的论文、订单号、`91年出生` 都不拦。
+- 平台审核要求的政治 / 色情 / 暴力大类词表在数万条量级，硬编码进代码既不现实也无法随口径更新。部署方用 `FOXCLAW_CONTENT_LEXICON` 挂载外部词表（逗号分隔多个文件，一行一词，可选 `词<TAB>类别`）；`tools/build_content_lexicon.py` 负责格式转换（自动判别编码、按类别筛选、按文件名推类别、转换后回读验证），挂哪几类由部署方自己定。**这一层不挂就不生效**：默认只有内置规则在跑。
+- `FOXCLAW_CONTENT_GUARD_MODE` 三档：`enforce`（默认）、`audit`（只记录）、`off`。默认强制，因为这是给对外产品兜底的机制，默认不生效等于没做；内置规则范围窄，正常对话不会被误伤。
+- 归一化对抗全角、零宽字符、空格插字。拼音、谐音、拆字改写不在确定性层处理 —— 这里明确只做限速带，不做墙。
+- 知识库导入与附件正文**不过滤**：那是用户自己的资料。过滤器只挂在「用户请求」和「模型输出」两端，避免把历史书和法律条文当成违规请求。
+- 行为规范新增 `no_harmful_content`（`enforce: both`），`KERNEL_PROMPT` 增加【八、内容边界】写明拒绝范式，并区分「资料」与「指令」两种角色。
+- 新增 `docs/CONTENT_GUARD_CN.md` / `docs/CONTENT_GUARD.md`：挂载方式、词表格式、格式转换与误伤调优。仓库不附带任何政治 / 色情 / 暴力词表，是否挂载、跑哪一档由部署方决定。
+
+**Agent**
+
+- Agent 启动时会把 `foxclaw/agents/rules/<AGENT_ID>/*.md` 读进系统提示词。每次组装提示词都重新读盘，改规则不必改代码；该段附在角色职责之后，与上游安全规则冲突时以安全规则为准。设 `FOXCLAW_AGENT_RULES=0` 可整体关闭。
+- 随包附带 `foxclaw/agents/rules/finance/RULES.md` —— Personal Finance Agent Rules v1.0（数据真实性、账目准确性、隐私、计算口径、建议边界、异常处理、记忆边界、与主管协作）。该文件属 package data，随 wheel 一起分发，不会像仓库根的 `skills/` 那样漏包。
+
+**知识**
+
+- 新增 `POST /conflicts/{id}/dismiss` 与 `POST /conflicts/bulk-dismiss`（SDK：`dismiss_conflict` / `dismiss_conflicts`），关闭卡片但不判胜负：双方 claim 保持 `active`，没有一方被标成 `superseded`。仅因该卡被置为 `disputed` 的观点，在不牵涉任何 open 冲突后恢复为 `active`。
+- 冲突判定不再只凭主题相似就翻转立场：否定侧还须与另一句字面重合（字符二元组 Jaccard ≥ 0.40）且语义相近（余弦 ≥ 0.35），两个阈值均可由构造参数（`neg_flip_min_cos` / `neg_flip_min_overlap`）调整。
+- 「不变」「不同」「不管」「不再」「无需」「不可观测」「不可控」这类描述性「不 / 无」不再算作立场否定。
+- 冲突卡新增次按钮「误判」，与「采纳所选观点」并列。
+- 新增 `tools/recheck_conflicts.py`：用当前规则复算存量 open 卡并批量关闭已不成立的，默认 dry-run，`--apply` 经运行中的服务提交，保证进程内冲突集合与向量索引同步。
+
+## 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

@@ -43,16 +43,31 @@ Closed loop (`ChannelDispatcher`): receive → Supervisor → reply to origin, w
 
 Keeps the system reliable under message redelivery, crashes, long tasks, and loops. See [docs/GOVERNANCE.md](docs/GOVERNANCE.md): idempotency guard, crash/restart recovery (boot_id avoids pid reuse), tool-loop detection, context compaction, hook standardization, steering queue.
 
+**Content boundaries.** Requests and model output pass a deterministic content gate: narrow built-in rules for request-shaped violations, plus an optional external lexicon for platform categories.
+
+**No political, sexual, or violent term list is bundled, and nothing in that area is enforced unless the deployer mounts one.** Whether to mount a lexicon, which categories to take, and whether to run `enforce` or `audit` is entirely a deployment decision — this repository provides the mechanism, not a policy. The gate is normalised string matching, not semantic understanding: it does not guarantee coverage, and it is not a content moderation or compliance service. Deployers who expose this service publicly are responsible for their own content compliance. The software is provided "as is", as stated in [LICENSE](LICENSE).
+
+See [docs/CONTENT_GUARD.md](docs/CONTENT_GUARD.md) for mounting, conversion, and false-positive tuning.
+
 ## 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。
 
 ## 二、三个智能体与领域内核
 
@@ -57,6 +59,12 @@ Foxclaw 不是"又一个智能体框架",而是一个真正记得住事的个人
 - **钩子标准化** —— 标准生命周期钩子 + 明确阻断权
 - **干预队列** —— 租约机制安全回收子任务结果(为并行子 Agent 预留)
 
+**内容边界。** 用户请求与模型输出两端各有一道确定性内容闸门:内置规则只管请求型教唆,平台大类词表按需挂载。
+
+**仓库不附带任何政治、色情、暴力词表,这块不挂载就完全不生效。** 是否挂载、取哪几类、跑 `enforce` 还是 `audit`,完全由部署方自行决定 —— 这里提供的是机制,不是口径。闸门做的是归一化后的字符串匹配,不是语义理解,不保证覆盖率,也不构成内容审核或合规服务;对外提供服务时的内容合规责任在部署方自身。软件按“现状”提供,详见 [LICENSE](LICENSE)。
+
+挂载方式、格式转换与误伤调优见 [docs/CONTENT_GUARD_CN.md](docs/CONTENT_GUARD_CN.md)。
+
 ## 五、目录结构
 
 ```
@@ -69,11 +77,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 +90,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 +105,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 +121,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 +143,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 +185,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):