foxclaw 0.1.0 → 0.1.3

package/python/.github/workflows/release.yml

@@ -0,0 +1,183 @@
+name: Release
+
+# 两段式发布。为什么不能"打 tag 就自动上传":
+# PyPI / npm 的版本号**不可撤回** —— 传上去只能 yank(仍占号、仍能被 pin 装到),
+# 不能覆盖重发。所以 CI 的默认行为是「校验 + 构建 + 挂 GitHub Release」,
+# 真正的外发必须人工触发一次 workflow_dispatch,并在 environment 里审批。
+#
+# 阶段一(push tag v*):版本/tag 一致性 → 构建 wheel+sdist+npm tgz → 产物结构校验
+#                        → GitHub Release 附件(可反复重跑,错了删 tag 重来)
+# 阶段二(workflow_dispatch):勾 publish=pypi/npm/both + 填 ref=tag,审批后才上传
+#
+# 需要预先准备(仓库 Settings):
+#   Environments: pypi、npm(各配 Required reviewers → 这就是"审批门")
+#   Secrets:      PYPI_API_TOKEN(npt_... 项目级 token)、NPM_TOKEN(granular,仅 publish)
+# 换 OIDC 时:PyPI 用 pending publisher、npm 用 trusted publishing,
+# 把 publish-* 里的 password/NODE_AUTH_TOKEN 去掉并加 `permissions: id-token: write`。
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: "上传目标(需对应 environment 审批)"
+        type: choice
+        options: ["none", "pypi", "npm", "both"]
+        default: "none"
+      ref:
+        description: "要构建/发布的 tag(如 v0.1.0;发布时必填)"
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+# 同一 tag 并发跑两次发布 = 两个进程抢同一个版本号
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install release toolchain
+        # 只装构建器,不 `pip install -e .`:构建 wheel 不需要 torch/faiss 那套运行时
+        # 依赖(唯一 import 的 release_check.py 是纯标准库),装了只会把 job 拖成 5 分钟。
+        run: |
+          python -m pip install --upgrade pip
+          pip install "build>=1.2"
+
+      # 发布必须锚定 tag:否则发出去的是分支 HEAD,版本号对不上任何 tag,
+      # 事后连"这版对应哪次提交"都答不上来。
+      - name: Require tag when publishing
+        if: github.event_name == 'workflow_dispatch' && inputs.publish != 'none'
+        env:
+          REF: ${{ inputs.ref }}
+        run: |
+          if [ -z "$REF" ]; then
+            echo "::error::publish=${{ inputs.publish }} 时必须填 ref(如 v0.1.0),不能发分支 HEAD"
+            exit 1
+          fi
+
+      - name: Version / tag gate
+        env:
+          TAG: ${{ github.event_name == 'push' && github.ref_name || inputs.ref }}
+        run: |
+          if [ -n "$TAG" ]; then
+            python tools/release_check.py --tag "$TAG"
+          else
+            python tools/release_check.py
+          fi
+
+      - name: Build wheel + sdist
+        run: python -m build --outdir dist
+
+      - name: Pack npm tarball
+        # 必须先跑 build.cjs:它把项目源码复制进 npm/python/,npm 包才算完整。
+        # `npm pack` 不触发 prepublishOnly(只有 publish 才触发),漏了这步打出来的
+        # 是 2KB 空壳——里面没有 python/,npx foxclaw 直接跑不起来。
+        # 同时 build.cjs 自带红线自检:含内部文档就 exit 1,构建随之失败。
+        working-directory: npm
+        run: |
+          node build.cjs
+          npm pack --pack-destination ../dist
+
+      - name: Artifact gate
+        # 包里出现 .env / docs/internal / 运行期数据 = 停下,不许发(宁可不出包)
+        run: python tools/release_check.py --dist dist --npm-tgz dist/*.tgz
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: npm-tgz
+          path: dist/*.tgz
+          if-no-files-found: error
+
+  github-release:
+    # 只有 tag 才挂 Release;手工触发构建不建 Release
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber    # 重跑时覆盖附件,不重建 Release
+          else
+            gh release create "$TAG" dist/* --title "$TAG" --generate-notes
+          fi
+
+  publish-pypi:
+    if: >-
+      github.event_name == 'workflow_dispatch' &&
+      (inputs.publish == 'pypi' || inputs.publish == 'both')
+    needs: build
+    runs-on: ubuntu-latest
+    # environment 上配 Required reviewers:这一步停在"等待审批",人点了才动
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          packages-dir: dist/
+
+  publish-npm:
+    if: >-
+      github.event_name == 'workflow_dispatch' &&
+      (inputs.publish == 'npm' || inputs.publish == 'both')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: npm-tgz
+          path: dist
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish ./dist/*.tgz --access public

package/python/CHANGELOG.md

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

package/python/CHANGELOG_CN.md

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

package/python/Dockerfile

@@ -0,0 +1,64 @@
+# syntax=docker/dockerfile:1
+
+# Foxclaw — 认知智能体操作系统
+#
+# 一个镜像两种用法：
+#   1) 跑服务：docker run -p 8000:8000 foxclaw
+#   2) 跑全量回归（构建/CI 自检）：docker run --rm foxclaw python tests/run_all.py
+#
+# 镜像较大（>2GB）是 sentence-transformers/torch 的代价——语义检索与治理漂移检测
+# 都依赖真实 embedding，这是能力而非可裁剪项。测试锁 HF_HUB_OFFLINE 离线读预热缓存。
+
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    HF_HOME=/root/.cache/huggingface
+
+WORKDIR /app
+
+# 系统依赖：torch 需要 libgomp1（OpenMP 运行时）。slim 镜像默认缺失，
+# 缺了会在 import torch 时报 libgomp.so.1 找不到。
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── 依赖层（利用 Docker layer 缓存：改源码不重装 torch）──────────────
+# 必须拷 foxclaw/ 与 vendor/ 才能 editable install（HMR/HKC 是 vendor 内嵌、
+# 走 sys.path 加载，非 PyPI 依赖，见 pyproject.toml 注记）。
+COPY pyproject.toml ./
+COPY foxclaw/ foxclaw/
+COPY vendor/ vendor/
+
+# 依赖以 pyproject.toml 为唯一来源；dev extra 补 pytest/ruff/mypy/coverage +
+# openpyxl/python-docx（默认回归 test_file_ingest/test_domain_import 硬依赖），
+# 使镜像既能跑服务又能跑全量回归（与 CI 对齐）。
+# 【关键】先装 CPU 版 torch：PyPI 默认 torch 在 Linux 上会拖入整套 CUDA toolkit
+# （nvidia-* 十几个包 + cuda-toolkit，镜像 +4GB、下载极慢），而 Foxclaw 语义检索
+# 只需 CPU。先从 PyTorch 官方 CPU index 装好 torch，sentence-transformers 见
+# 约束已满足即不再重装 CUDA 版。
+# --mount=type=cache 复用 pip 下载缓存：改依赖后重建无需重下 torch 等大 wheel
+# --retries/--timeout：国内网络抖动时 pip 默认重试(5次/15s)偏短,会把 filelock 等
+# 依赖的 index 元数据请求超时误判为"无匹配发行版"(ResolutionImpossible),放宽后更稳。
+RUN --mount=type=cache,target=/root/.cache/pip pip install --upgrade pip \
+    && pip install --retries 8 --timeout 60 torch --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --retries 8 --timeout 60 -e ".[dev]"
+
+# ── 预热默认 embedding（all-MiniLM-L6-v2）────────────────────────────
+# run_all.py 内部注入 HF_HUB_OFFLINE=1 离线读取。若镜像内没有缓存，
+# sentence-transformers 会降级为 n-gram 哈希嵌入——对中文几乎无区分度，
+# 语义漂移分恒为 1.0 → 治理测试全红（见 .github/workflows/ci.yml 的教训）。
+# 故在 build 期一次性下载好，运行期离线可用、不依赖外网。
+# 【HF_ENDPOINT】默认走 hf-mirror.com（国内直连 huggingface.co 常被墙、DNS 解析失败）；
+# 海外/CI 可 `docker build --build-arg HF_ENDPOINT= ...` 覆盖，或留空走官方 HuggingFace。
+ARG HF_ENDPOINT=https://hf-mirror.com
+RUN HF_ENDPOINT="${HF_ENDPOINT}" python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
+
+# ── 其余仓库内容（frontend 前端静态 / skills / docs 等）──────────────
+COPY . .
+
+EXPOSE 8000
+
+# 默认启动 API 服务；跑回归用：docker run --rm foxclaw python tests/run_all.py
+CMD ["python", "-m", "uvicorn", "foxclaw.api:app", "--host", "0.0.0.0", "--port", "8000"]

package/python/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 snowfoxHQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/python/MANIFEST.in

@@ -0,0 +1,14 @@
+# sdist 必须自带 vendor/ 下的 HMR 与 HKC —— 它们是内嵌运行时,不是 PyPI 依赖。
+# 缺了它们,pip install 装出来的包记忆/知识子系统会整体降级为 None。
+graft vendor
+graft foxclaw
+
+# sdist 必须带正文文件:pyproject 的 readme 指向 README_CN.md,PyPI 项目页正文取自它。
+include README.md
+include README_CN.md
+include LICENSE
+
+prune vendor/__pycache__
+prune foxclaw/__pycache__
+global-exclude *.pyc
+global-exclude *.pyo

package/python/README.md

@@ -0,0 +1,201 @@
+# Foxclaw · A Personal Agent with Memory
+
+A **personal agent with memory** — to a user, an agent that remembers; to a developer, an agent runtime built on the HMR memory runtime: three collaborating agents, cross-layer Harness governance, with the memory/cognition layer fully decoupled from any LLM.
+
+```
+Traditional frameworks:  memory = storage,           agents = stateless execution
+Foxclaw:               memory = living cognitive runtime, agents = reason · learn · evolve
+```
+
+## What it is
+
+Foxclaw is not "yet another agent framework" but a personal agent that actually remembers; under the hood, an agent runtime. Its moats are independent of any LLM:
+
+- **ThoughtChain** — each agent's reasoning is an auditable, comparable directed graph, not a log
+- **Harness** — three-dimensional drift detection (semantic / tool / scope) + shadow-mode self-calibration + policy self-learning
+- **Evolution** — every harness truncation teaches the policy; the system gets sharper with use
+- **Runtime governance** — idempotency, crash recovery, loop detection, etc., keeping the system reliable under real-world operation
+
+Three agents: Supervisor (coordination), Finance, Office (learning + itinerary). Each has isolated memory and policy evolution, mounts external ecosystems via the Skill layer, and connects to mainstream messaging platforms via the channel layer. The former Assistant and Admin responsibilities are now **instruction skills** (`skills/general-assistant`, `skills/schedule-itinerary`) mounted on demand, not separate agents.
+
+## Domain kernels
+
+Finance / Office each mount an isomorphic kernel (pure-algorithm layer + external tool interface + gatekeeper):
+
+- **Finance** — budget reasoning, MAD anomaly detection, cash-flow forecast; gatekeeper with four permissions, emits approval requests rather than moving money. **Advanced trio**: structured evidence chains (explainable risk), financial data graph (trace who caused an overspend), reconciliation (3-tier matching + suspicious-charge detection).
+- **Office** — SM-2 spaced repetition (mastery + forgetting risk) + knowledge graph (cluster discovery).
+- **Office · itinerary** — TSP routing, reachability ("won't make it") detection, time conflicts, geo-clustering; integrates Amap.
+
+## Messaging platforms
+
+Four mainstream platforms via a unified channel abstraction, **each adapter implemented to its own official spec** (not one mold):
+
+| Channel | Model | Credential |
+|---------|-------|-----------|
+| WeChat | iLink Bot API, long-poll + context_token | scan-login token |
+| Feishu | event-subscription webhook + signature + token refresh | App ID/Secret |
+| Telegram | Bot API getUpdates polling | bot token |
+| Discord | Gateway WebSocket + REST | bot token |
+
+Closed loop (`ChannelDispatcher`): receive → Supervisor → reply to origin, with per-channel session isolation and idempotent dedup. See [docs/CHANNELS.md](docs/CHANNELS.md).
+
+## Runtime governance
+
+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.
+
+## Quick start
+
+```bash
+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
+```
+
+> `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`.
+
+## Knowledge base (HKC) model config
+
+HKC's knowledge base uses **two different types of models**, each for one job, both configured in `.env` — no code changes:
+
+| Stage | Model type | What it does | Config keys |
+|-------|-----------|-------------|-------------|
+| Write (ingesting books/files) | **Generative LLM** (reads & emits JSON) | Extracts entities / concepts / facts / claims from each chunk | `HKC_LLM_*` |
+| Retrieve (querying) | **embedding** (text → vector) | Vectorizes knowledge & queries, ranks by semantic similarity | `HKC_EMBEDDING_*` |
+
+They are not interchangeable: an embedding model cannot generate text (can't produce JSON), and an LLM is not suited to vector search.
+
+### First, pick your case
+
+| Your environment | Extraction model setup | `HKC_LLM_API_KEY` value |
+|---|---|---|
+| Have local Ollama | `openai-compatible` + `base_url` pointing at Ollama | **any non-empty value** (Ollama ignores it; `ollama` is just a placeholder) |
+| No local model | Use a **public cloud model** (DeepSeek / OpenAI / Qwen …), see table | the platform's **real API key** |
+
+### Case A · local Ollama
+
+```bash
+HKC_LLM_PROVIDER=openai-compatible
+HKC_LLM_API_KEY=ollama                       # placeholder only for local Ollama; never use this for cloud
+HKC_LLM_MODEL=my-qwen-32k:latest             # a model name from your `ollama list`
+HKC_LLM_BASE_URL=http://localhost:11434/v1   # Ollama's OpenAI-compatible endpoint
+HKC_LLM_TIMEOUT=180                          # local models are slow; relax the default 60s
+HKC_EXTRACT_CONCURRENCY=2                    # 1–2 for local, up to 5 for cloud APIs
+HKC_EXTRACT_BATCH=8                          # optional: extract N chunks per call, saves tokens & time; default 1 = per-chunk
+HKC_MAX_CHUNKS_PER_DOC=800                   # optional: per-doc chunk cap; default 800 (~1.25M chars); 0 = no cap, see below
+```
+
+### Case B · public cloud model (no local model)
+
+`HKC_LLM_MODEL` is the platform's **public model id** (passed through verbatim); `HKC_LLM_API_KEY` is the platform's **real key**:
+
+| Platform | `HKC_LLM_PROVIDER` | `HKC_LLM_API_KEY` | `HKC_LLM_MODEL` example | `HKC_LLM_BASE_URL` |
+|---|---|---|---|---|
+| DeepSeek | `deepseek` | `sk-...` (DeepSeek key) | `deepseek-chat` / `deepseek-reasoner` | leave blank (official default) |
+| OpenAI | `openai` | `sk-...` (OpenAI key) | `gpt-4o-mini` / `gpt-4o` | leave blank |
+| Qwen (Alibaba) | `openai-compatible` | DashScope key | `qwen-max` / `qwen-plus` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| Zhipu / Moonshot / MiniMax … | `openai-compatible` | that platform's key | that platform's model id | that platform's OpenAI-compatible URL |
+
+DeepSeek example:
+
+```bash
+HKC_LLM_PROVIDER=deepseek
+HKC_LLM_API_KEY=sk-your-deepseek-key
+HKC_LLM_MODEL=deepseek-chat
+```
+
+### Retrieval model (embedding)
+
+The retrieval model does **not** use Ollama; it uses sentence-transformers, and auto-downloads weights from HuggingFace when missing locally:
+
+```bash
+HKC_EMBEDDING=local
+HKC_EMBEDDING_MODEL=BAAI/bge-m3          # auto-downloads on first use (~2.2 GB); or a local path like C:\...\bge-m3
+```
+
+Leave it unset if you don't need semantic precision (defaults to `stub` pseudo-semantics, works out of the box).
+
+### Where to put the key, and precedence
+
+- **`.env` is the source of truth** — read at startup; restart after editing.
+- The "extraction model" section in the planet page's connection settings is an **optional runtime override** (stored in browser localStorage, may override `.env` on refresh); leave it blank to always follow `.env`.
+- The page's first "API Key" field is the backend auth token (`.env`'s `FOXCLAW_API_KEY`), unrelated to the model keys.
+
+> Note: switching the embedding model changes the vector dimension (e.g. 384 → 1024), so you must rebuild the knowledge index (clear and re-ingest).
+
+### How much can I ingest at once?
+
+**The limits are hard — exceeding them returns an error, never a silent truncation:**
+
+| Entry point | Limit | On overflow |
+|---|---|---|
+| File upload (`/knowledge/ingest/file`, `/ingest/file/async`) | **20 MB per file** | `413 file too large` |
+| Pasted text (`/knowledge/ingest/text`) | **2,000,000 characters** | `413 text too large` |
+| Chunks per document | **800 by default** (~1.25M chars); `HKC_MAX_CHUNKS_PER_DOC=0` disables the cap | Only the first N chunks are processed, with a "document too large" warning |
+
+Supported formats: `.pdf` `.md` `.markdown` `.txt` `.epub` `.mobi` `.azw3` `.azw` `.docx` `.xlsx`. `.doc` is not supported, and **scanned PDFs get no OCR** — image-only pages yield no text at all.
+
+**A chunk is the billing and timing unit**, and it is fixed:
+
+```
+max 1792 chars per chunk, 224 chars of overlap
+→ roughly 1 chunk per 1568 characters
+```
+
+**Time and cost reference** (batch=4, concurrency=8, cloud DeepSeek, CJK content):
+
+| Content | File size | Chunks | Expected time |
+|---|---|---|---|
+| 100k chars | ~100 KB | ~64 | ~6 min |
+| 500k chars | ~500 KB | ~320 | ~32 min |
+| 1M chars | ~1 MB | ~640 | ~1 hour |
+| 7M chars (ceiling) | ~20 MB | ~4400 | ~7 hours |
+
+Token ratio: **~4k input + 2k output tokens per 10k characters** (batch extraction already amortizes the system prompt) — multiply by your provider's rates. English content is 2–3× the characters of CJK for the same bytes, so it costs proportionally more.
+
+**Practical guidance:**
+
+- **Keep single files at 2–5 MB.** That covers an ordinary ebook, finishes within tens of minutes, and lets you watch progress.
+- **Leave `HKC_MAX_CHUNKS_PER_DOC` at its default of 800.** Read the section below before lifting it — the reason is not just "it's slow".
+- **Use file upload, not paste, for anything long.** `/ingest/text` is synchronous and holds the request; `/ingest/file/async` runs in a background thread and exposes `processed/total` progress.
+- **Re-uploading the same file is free.** Content SHA-256 is checked first and duplicates return `409 already ingested`.
+- **When extraction fails, check the log keyword first.** "JSON parse failed" means the model's output was cut off mid-JSON (common with dense CJK documents) — lower `HKC_EXTRACT_BATCH` or raise `HKC_EXTRACT_MAX_TOKENS` (default 8192, the output ceiling). Only when that keyword is absent should you check the API key or network.
+
+### Per-document chunk cap: why the default is 800
+
+`HKC_MAX_CHUNKS_PER_DOC` defaults to **800 chunks**, chosen as the intersection of "covers real documents completely" and "finishes in a time you can sit through, at a cost you can predict":
+
+| Cap | Characters covered | Chunks | Expected time | Cost (cloud) |
+|---|---|---|---|---|
+| **800 (default)** | ~1.25M | 800 | ~1.3 hours | ~$0.4 |
+| 2000 | ~3.1M | 2000 | ~3.3 hours | ~$1 |
+| 0 (uncapped, i.e. a full 20 MB file) | ~7M | ~4400 | **7+ hours** | ~$2.3 |
+
+> Costs are rough order-of-magnitude estimates at DeepSeek list prices; scale for your provider.
+
+**Why not raise it (and especially not to 0):** uploads accept up to 20 MB. With no chunk cap, one accidental upload — a 20 MB scanned PDF, a rotated log dump — runs in the background for the better part of a day while billing the whole time. Ingestion runs on a background thread with no checkpoint and no rollback button: you either watch it finish or kill the whole service. The default exists to stop obviously unreasonable volumes up front, not to be as restrictive as possible.
+
+**Why not shrink it either:** past the cap only the first N chunks are processed, and the **whole file's SHA-256 is already recorded** as ingested. Re-uploading the same file is rejected with `409`. So a truncated ingest cannot be completed by "raising the cap and sending it again" — you must split the file by chapter and upload the parts separately. 800 chunks leaves enough headroom that ordinary documents and normal ebooks never hit the cap.
+
+**If you genuinely need a whole book,** raise the cap (or set 0) for that one ingest and set it back to 800 afterwards. A "document too large: split into N chunks" warning in the log means truncation happened, and it reports how much was dropped.
+
+## Philosophy
+
+Memory and cognition are fully decoupled from the LLM. The model is a replaceable text generator; the real moat (ThoughtChain audit + Harness drift + policy self-learning + domain kernels) exists independently of any model.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Use it, modify it, ship it, sell it; just keep the copyright notice.
+
+The runtimes vendored under `vendor/` keep their own licenses (see `vendor/hkc/LICENSE`).