HushClaw 深度产品解析 — 记忆、逻辑、策略全图

产品定位

HushClaw 到底是什么？

在理解任何细节之前，先搞清楚它在解决什么问题，填补的是哪个市场空白。

🎯

一句话定位：一个可以完全本地部署、拥有持久记忆、Token 成本精确可控的私人 AI Agent 框架。它不是 ChatGPT 的替代品，而是填补"长期记忆 + 可私有部署 + Token 精控"的空白产品形态。

三个被解决的核心痛点

😤 金鱼记忆问题

每次对话都要重新介绍自己。ChatGPT 的 Memory 功能虽然存在，但不透明、不可控、不能私有化。 HushClaw 用可查询、可编辑、可遗忘的 SQLite + Markdown 双层存储解决这个问题。

💸 Token 黑洞问题

对话越长，消耗越多，但无法控制哪些值得保留。HushClaw 把上下文拆成 稳定前缀 + 动态后缀，每个分区都有独立 Token 预算，超阈值自动触发压缩策略。

🔒 数据失控问题

所有对话和偏好存储在第三方云端，无法选择模型、无法本地部署。 HushClaw 零强制依赖，支持 Ollama 本地模型，数据完全不出机器。

产品形态：不是单一工具，而是框架

HushClaw 有三种使用方式，针对不同使用场景：

Web UI

浏览器访问 http://localhost:8765，零配置开箱即用。支持多 Agent 切换、Session 管理、记忆搜索面板、实时流式输出、文件拖拽上传。

CLI REPL

          命令行交互模式，支持 /remember /search /forget 等斜杠命令。
          hushclaw agents pipeline 可直接触发多 Agent 流水线。
        

Python API

Agent.chat() 直接编程调用，支持流式和事件两种响应模式。可嵌入任何 Python 项目，作为 AI 能力的底层驱动。

核心引擎

ReAct 主循环：每次对话的完整流程

每一条消息从输入到输出，经历以下精确的处理步骤。这是整个系统的"心脏"。

1

组装上下文 — assemble()

调用 ContextEngine.assemble()，返回 (stable_prefix, dynamic_suffix) 元组。稳定前缀包含角色定义和静态指令（1500 tokens 预算），动态后缀包含当天日期 + 从记忆库检索到的相关笔记（2500 tokens 预算）。两部分分离是为了让稳定前缀享受 Anthropic 的 KV-Cache 缓存，减少重复计算。

2

压缩检测 — needs_compaction()

检查历史消息 token 总量是否超过 history_budget × compact_threshold（默认 60000 × 0.85 = 51000 tokens）。若超过，触发 compact() 压缩。最近 6 轮（compact_keep_turns）永远保留不压缩，确保对话连贯性。

3

调用 LLM — provider.complete()

            向 LLM 提供商发送请求。system 参数传入 (stable, dynamic) 元组（Anthropic 原生 KV-Cache 格式），
            messages 传入对话历史，tools 传入当前可用工具的 JSON Schema。
            支持流式输出，chunks 实时推送到 WebSocket。
          

4

工具执行 — ToolExecutor.execute()

如果 LLM 响应包含 tool_use 块，提取工具名和参数，在工具注册表中查找（支持模糊名称匹配），注入执行上下文（_memory_store, _config, _gateway 等），执行工具，将结果追加到消息列表，重新调用 LLM（最多 max_tool_rounds 次，默认10轮）。

5

持久化对话 — memory.save_turn()

将本轮的 user_input 和 assistant_response 存入 turns 表（SQLite），记录 token 用量（input_tokens, output_tokens），用于后续压缩和成本统计。

6

事实提取 — after_turn()

对本轮对话运行轻量级正则事实提取（零 LLM 调用），识别姓名、项目、URL、决策、文件路径、版本号等 10 类信息，自动存入记忆库（标签 _auto_extract）。整个循环结束，等待下一条消息。

⚡

        事件流协议：每一步都通过 WebSocket 实时推送事件给前端。
        session → chunk → tool_call → tool_result → compaction → done。
        服务端缓冲最近 400 个事件，断线重连后可完整回放，不丢失任何中间状态。
      

上下文引擎

Token 管理：每一分钱都花在刀刃上

这是 HushClaw 最核心的成本控制机制。上下文不是无脑塞满，而是精确分区、按需注入。

Token 预算分配图

稳定

动态

历史对话 60,000 tokens

■ 稳定前缀 1,500 tokens · 角色+指令 · KV-Cache 复用

■ 动态后缀 2,500 tokens · 日期+记忆 · 每次刷新

■ 历史对话 60,000 tokens · 85% 阈值触发压缩

KV-Cache 优化：为什么要分稳定/动态两部分？

Anthropic 的 Claude API 支持 Prompt Caching：如果系统提示的前缀与上一次请求完全相同，服务端会跳过重新处理，直接复用缓存的 KV 对，显著降低延迟和成本（缓存命中的 token 按 10% 价格计费）。

# anthropic-raw provider 的 KV-Cache 构建逻辑 def _build_system_payload(system): if isinstance(system, tuple): stable, dynamic = system return [ {"type": "text", "text": stable, "cache_control": {"type": "ephemeral"}}, # 稳定部分加 cache_control {"type": "text", "text": dynamic} # 动态部分每次更新 ] return system # 兼容旧格式

稳定前缀包含：角色定义、SOUL.md 人格、静态工具说明——这些几乎不变，可在跨请求间复用。动态后缀包含：今天日期、从记忆库检索到的笔记——这些每次都不同，不参与缓存。

三种压缩策略：历史太长时如何处理？

pruning 工具结果修剪

默认策略，零 LLM 调用。 把历史消息中的旧工具调用结果替换为 <pruned> 占位符，保留 user/assistant 消息完整内容。速度最快，适合工具调用密集的场景。

lossless 无损归档

先保存再压缩。 把将要压缩的旧对话轮次完整存入记忆库（标签 _compact_archive），再用 LLM 生成摘要替换原始内容。知识不丢失，可随时从记忆库检索回来。

abstractive 抽象原理

提取模式而非事实。 用 LLM 从历史对话中提炼原则、模式和洞察（而非具体事件），存为标签 _compact_abstractive。适合长期助手场景，积累"对你的理解"而非流水账。

自动事实提取：10 类正则模式，零成本

每轮对话结束后，对 user_input 和 assistant_response 运行这 10 类正则：

模式类型	示例触发词
姓名/身份	我叫、my name is、I am
项目名称	项目、project、产品
目标/需求	目标、我想、I want to
决策/结论	决定、采用、我们选择
文件保存	已保存、saved to、生成于

模式类型	示例触发词
URL 链接	http:// https://
文件路径	/path/to / C:\Users\
版本号	v1.0 version 2.3
配置项	key=value config:
中文事实	用户说、提到、确认了

💡

零 LLM 成本：正则提取不调用任何 API，每轮只需毫秒级计算。提取的事实以 _auto_extract 标签存入记忆库，优先级低于用户手动保存的笔记，搜索时会被相应地降权。

记忆系统

持久化记忆：模拟人类大脑的工程实现

记忆系统是 HushClaw 最核心的差异化能力。它的每一个算法选择都有明确的工程和认知科学依据。

双层存储架构

📦 SQLite 数据库层

负责机器检索。包含 5 张核心表：

notes — 元数据（title, tags, created, scope, recall_count）
note_bodies — 全文内容（分表存储，触发 FTS 同步）
embeddings — 向量 BLOB（model, dim, vec 二进制）
notes_fts — FTS5 虚拟表（自动同步触发器）
turns — 对话历史 + token 统计

使用 PRAGMA journal_mode=WAL（写前日志）支持并发读写。

📝 Markdown 文件层

负责人类可读。文件路径格式：

notes/2026-04-03/{id}-{slug}.md

每个文件包含 YAML 前言 + 正文：

--- note_id: abc123... title: 项目背景 tags: ["project", "context"] scope: global recall_count: 7 --- 正文内容...

双向同步：写入 SQLite 同时写 Markdown；用户直接编辑 Markdown 文件，下次重启会同步入库。

检索流程：混合搜索的完整决策树

1

FTS5 全文检索（BM25 算法）

用 SQLite 内置的 bm25(notes_fts) 函数对查询词做关键词匹配。 BM25 同时考虑词频（TF）、逆文档频率（IDF）和文档长度归一化。返回负数分数（SQLite FTS5 惯例），代码取绝对值处理。若查询语法失败（引号不匹配等），自动降级为空格分词的简单前缀匹配。

2

FTS 快捷通道判断（阈值 0.8）

取所有 FTS 结果中的最高分。如果 max_fts_score ≥ 0.8，直接跳过向量搜索，进入混合融合步骤。理由：关键词匹配已经非常精准时，花费 100ms+ 做向量嵌入的边际收益极低，节省成本。如果 FTS 结果为空（无关键词命中），也直接走向量搜索。

3

向量语义搜索（余弦相似度）

先对查询文本做嵌入（本地 TF-IDF / Ollama / OpenAI），然后从数据库取出所有笔记的向量，逐一计算余弦相似度：

cos(θ) = (a · b) / (|a| × |b|)

取 Top-K×2 个结果（取更多是为了给融合步骤留余量）。

4

加权融合评分

取 FTS 和向量搜索结果的并集，对每个笔记计算综合分：

Score = 0.6 × BM25分 + 0.4 × 余弦相似度

FTS 权重 60%，向量权重 40%（可在 config 调整 fts_weight / vec_weight）。关键词精确匹配的优先级高于语义相似，防止语义漂移导致的噪音结果。

5

Ebbinghaus 时间衰减（可选）

如果配置了 memory_decay_rate λ > 0，对每个笔记的综合分乘以时间衰减因子：

Score' = Score × e^{−λ × age_days}

λ=0.1 时：7 天后分数降至 50%，14 天后降至 25%，21 天后降至 12%。这模拟了赫尔曼·艾宾浩斯 1880 年代的遗忘曲线研究——信息随时间指数级遗忘。

6

分数门控过滤

剔除综合分低于 memory_min_score（默认 0.25）的结果。这个阈值的意义：防止把低相关度的噪音记忆注入上下文，避免 AI 被不相关信息干扰产生幻觉。

7

Softmax 温度采样（可选）

默认 retrieval_temperature = 0，直接取 Top-K（确定性）。设置温度 T > 0 时，用 Softmax 概率采样：

P(i) = exp(Score_i / T) / Σ_j exp(Score_j / T)

T 越大，分布越平，更多"意外笔记"有机会被选中。适合创意写作场景，让 AI 产生"灵感关联"。

8

Token 预算截断 + 30秒缓存

将选出的笔记格式化后，按 Token 估算（1 token ≈ 4 字符）逐条累加，超过 memory_max_tokens（默认 800）立即停止。每条笔记正文截取前 300 字符，避免单条笔记占用过多预算。同一 session 对同一查询的结果缓存 30 秒，避免重复搜索。

本地向量嵌入：零 API 成本的实现原理

默认使用纯 Python 标准库实现的 512 维 TF-IDF 哈希向量，无需任何外部 API：

def _local_embed(text, dim=512): tokens = re.findall(r"[a-zA-Z\u4e00-\u9fff]+", text.lower()) # 提取英文词和中文字 tf = Counter(tokens) # 词频统计 vec = [0.0] * dim for token, count in tf.items(): h = hash(token) % dim # 哈希映射到维度 for seed in range(4): # 4 个种子减少碰撞 idx = (h + seed * 97) % dim vec[idx] += count / len(tokens) # 按 TF 权重累加 norm = math.sqrt(sum(x*x for x in vec)) or 1.0 return [x/norm for x in vec] # L2 归一化

也支持切换到更高质量的嵌入：

嵌入提供商	延迟	成本	适用场景
local (TF-IDF)	~1ms	零	默认，适合中文+英文混合，快速部署
ollama (nomic-embed-text)	~100ms	零（本地GPU）	语义理解更好，但需要 Ollama 运行
openai (text-embedding-3-small)	~300ms	$0.02/1M tokens	最高质量，适合生产环境
anthropic	~200ms	按量	与 Claude 同源嵌入空间

空查询 = 灵感模式（Serendipity）

✨

当查询字符串为空时，不做检索，而是随机采样笔记（所有笔记评分设为 1.0，再走 Softmax 温度采样）。配合 serendipity_budget 参数，可以让 AI 在每次响应前先"随机回想一条记忆"，产生跨领域的灵感关联，模拟人类"思维发散"的创意状态。

所有可调参数一览

参数名	默认值	作用 / 调整建议
fts_weight	0.6	关键词检索权重。语义场景可降到 0.4
vec_weight	0.4	向量检索权重。与 fts_weight 相加应为 1.0
memory_min_score	0.25	分数门控阈值。调高减少噪音，调低增加召回
memory_max_tokens	800	注入上下文的最大 token 数。越大越贵
memory_decay_rate	0.0	遗忘曲线 λ。0 = 永不遗忘；0.1 = 7天降50%
retrieval_temperature	0.0	采样温度。0 = 确定性；1.0 = 自然随机
serendipity_budget	0.0	灵感模式预算比例。0.1 = 10% 的预算给随机记忆
auto_extract	true	是否自动从对话提取事实存入记忆库

工具系统

工具系统：AI 如何调用外部能力

工具是 AI 超越对话的关键。HushClaw 的工具系统从注册、发现、调用到上下文注入，有一套完整的设计逻辑。

工具三层结构

1

内置工具

代码内置 15+ 工具，开箱即用。按 Profile 分组，可按需启用

2

Plugin 插件

放 .py 文件到 ~/.config/hushclaw/tools/ 自动发现，无需注册

3

Skill 工具

每个技能包可携带 tools/ 目录，自动加命名空间前缀防冲突

工具执行逻辑：上下文注入模式

工具函数用 @tool 装饰器定义。以 _ 开头的参数对 LLM 不可见，由执行器自动注入：

@tool(name="recall", description="Search persistent memory") def recall( query: str, # LLM 可见参数 limit: int = 5, # LLM 可见参数 _memory_store: MemoryStore = None, # 自动注入：记忆存储 _config: Config = None, # 自动注入：配置对象 _session_id: str = None, # 自动注入：当前会话 ID ) -> ToolResult: results = _memory_store.recall_with_budget(query, limit=limit, session_id=_session_id) return ToolResult.ok(results)

执行器扫描函数签名，把参数名匹配到上下文字典，自动填充。 LLM 看到的 Schema 只有 query 和 limit 两个参数，感知不到后端注入的基础设施。

🔍

模糊名称匹配：LLM 经常省略工具名的命名空间前缀（如把 hushclaw-skill-pptx__create_slide 写成 create_slide）。工具注册表做两级后缀匹配：先匹配去掉命名空间后的名字，再匹配去掉模块前缀的名字，容错能力强。

内置工具清单

🧠 记忆工具

remember — 保存笔记，支持 title / tags / scope
recall — 混合检索，注入上下文
search_notes — 返回结构化搜索结果

🖥 Shell 工具

          run_shell 执行任意 Shell 命令。内置拒绝列表：
          阻断 rm -rf /、mkfs、dd if=、fork bomb、
          shutdown 等危险命令。REPL 模式下会弹确认提示。
        

📁 文件工具

read_file — 读取文件内容
write_file — 写入文件（自动创建目录）
list_dir — 列出目录
make_download_url — 生成 /files/ 下载链接

🌐 网络工具

fetch_url 用 urllib 抓取网页，零依赖，截断 32KB 防止 Token 爆炸。配合 Playwright 浏览器工具：navigate / click / fill / screenshot / evaluate，支持登录代理（browser_open_for_user 暂停让人操作）。

📅 生产力工具

add_todo / list_todos / complete_todo — 待办清单
send_email / read_email — IMAP/SMTP 原生收发
schedule_task — Cron 定时任务
get_calendar_events — CalDAV 日历

🤖 Agent 工具

delegate_to_agent — 委派给单个 Agent
broadcast_to_agents — 并行广播给多个 Agent
run_pipeline — 触发流水线
use_skill — 加载并调用技能包

技能包（Skill Packages）：可插拔的专业能力

25 个内置技能包，每个是独立的"专业模块"，包含：

skill-packages/ hushclaw-skill-pptx/ SKILL.md # 触发词、描述、标签、系统提示 tools/ pptx_tools.py # @tool 定义，自动加载 requirements.txt # 按需安装依赖

加载时机：延迟加载，只有被调用时才实例化。工具自动加命名空间前缀（如 hushclaw-skill-pptx__create_slide）防止同名冲突。

多 Agent 编排

多 Agent：AI 团队如何协作

HushClaw 不只是单个 AI 助手，Gateway 网关让多个专业 Agent 像团队一样分工协作。

Gateway 网关的核心职责

🔀 会话亲和路由

同一个 session_id 的请求永远路由到同一个 AgentLoop 实例，保证对话历史的连贯性。AgentPool 维护 session_id → AgentLoop 的映射，空闲超过 session_ttl_hours（默认 24 小时）的 session 自动 GC。

🔗 共享记忆

          当 shared_memory = true（默认），所有 Agent 访问同一个记忆库。
          研究员 Agent 存入的笔记，写手 Agent 可以直接检索。
          如需隔离，可将各 Agent 的 memory_scope 设为 agent:researcher 等命名空间。
        

Pipeline 流水线：Agent 串联的工作流

# 配置示例：研究-写作流水线 [gateway.pipelines] research_write = ["researcher", "writer"] # 调用方式 hushclaw agents pipeline research_write "分析 AI 记忆系统的市场前景" # 内部执行逻辑： # 1. researcher.execute("分析 AI 记忆系统的市场前景") → output_A # 2. writer.execute(output_A) → final_output # 3. 每步共享同一个 pipeline_run_id，记忆作用域 pipeline:{run_id}

Agent 组织层级

每个 Agent 有 role、team、reports_to、capabilities 四个属性， Gateway 自动生成组织结构说明注入到每个 Agent 的 System Prompt：

# Gateway 自动注入的 Org Context（示例） """ 你是 researcher，专长：信息搜集、数据分析、报告起草团队成员： - writer (writer) — 负责文案润色和结构化输出你的上级：(无) 当任务超出你的专长时，使用 delegate_to_agent("writer", task) 委派。 """

三种 Agent 间通信方式

方式	工具	适用场景	特点
点对点委派	delegate_to_agent	明确知道哪个 Agent 最合适	同步等待结果，支持 timeout
广播并行	broadcast_to_agents	同一任务多个 Agent 并行处理	所有结果汇总后返回
流水线串联	run_pipeline	有明确先后依赖关系的多步任务	上一步输出 = 下一步输入

平台连接器

连接器：每个平台的接入细节

同一套 Agent 逻辑，通过连接器接入 7 个平台。每个连接器都有针对该平台特性的专门优化。

✈️ Telegram

技术方案：Long-Polling（纯 urllib，无 WebSocket 依赖）
流式更新：调用 editMessageText 不断更新同一条消息，有限速保护
权限控制：user_id + group_id 双白名单独立配置
特殊点：轮询超时时间可配置，支持文件下载到 upload_dir

🐦 飞书 Lark

技术方案：官方 lark-oapi SDK + WebSocket 长连接，无需公网 IP
工程难题：lark-oapi 在 import 时捕获 asyncio loop，与 hushclaw 的异步架构冲突。解决方案：在独立线程中创建新 event loop，手动重置 SDK 的 loop 引用
安全：支持 encrypt_key + verification_token 双重验证

💬 Slack

技术方案：Socket Mode（需要 app-token xapp-* + bot-token xoxb-*）
可靠性：自动重连，指数退避（5s → 60s）
消息限制：单条消息超过 4000 字符自动分块发送
依赖：需要 websockets 包（安装时自动检测并提示）

🏢 企业微信 / 钉钉

企微：Webhook 回调 + Webhook 注册表支持
钉钉：Webhook + 轮询混合模式
通用基类：所有连接器继承 BaseConnector，共享 session 亲和、文件下载（安全文件名消毒）、路由到 Gateway 的逻辑

🔧

所有连接器的共同底座：chat_id → session_id 映射（同一用户跨消息保持会话），流式输出（实时编辑消息），文件上传到 upload_dir 并生成 /files/ 下载链接， ConnectorsManager 按需懒加载（缺少凭据的连接器不启动）。

LLM 提供商

模型调用层：9 个提供商，统一接口

所有 LLM 调用都经过统一的抽象层，切换模型不需要改任何业务代码。

提供商	底层实现	特性	安装要求
anthropic-raw	urllib only	默认，原生 KV-Cache，支持 POST 307/308 重定向	无
anthropic-sdk	官方 SDK	流式更完善，自动重试	pip install anthropic
openai-raw	urllib only	OpenAI-兼容接口，支持 Responses API	无
openai-sdk	官方 SDK	支持 Function Calling 新格式	pip install openai
ollama	HTTP localhost:11434	完全本地，零 API 费用	安装 Ollama
gemini	google-genai SDK	Google Gemini 系列	pip install google-genai
minimax	OpenAI 兼容	国内/全球双端点自动切换	无
aigocode	Anthropic 兼容代理	api.aigocode.com 转发	无
transsion	OpenAI 兼容	邮箱验证码登录流程	无

重试机制

所有提供商都包裹在 _with_retry() 里：检测响应体中的"transient"关键词（429 限流、502 网关错误、503 服务不可用），做指数退避重试，最大重试次数和超时时间均可配置。

产品策略

设计决策背后的产品逻辑

每一个技术选择都反映了明确的产品思考。以下是最关键的几个设计决策和其背后的理由。

①

为什么零强制依赖？

降低部署摩擦是获客的关键。如果安装一个工具需要先安装 10 个依赖包、解决版本冲突，大多数用户会放弃。HushClaw 的核心功能只需 pip install hushclaw，立刻可以运行。浏览器自动化、飞书连接、语音转文字等是可选的，遵循"渐进增强"原则——用户想要什么才安装什么。

②

为什么记忆用 SQLite + Markdown 双层？

纯数据库方案：机器能搜，人不能读——出了问题难以调试。纯 Markdown 方案：人能读，但没有索引——超过100条就搜不动了。 双层是两者的最优解：SQLite 提供 FTS5 全文索引 + 向量存储（机器速度）， Markdown 提供可读性（人类友好）。两者保持同步，互为备份。

③

为什么 FTS 权重 60%、向量权重 40%？

纯关键词（BM25 100%）：无法处理同义词，"机器学习"找不到"ML"的笔记。纯向量（Cosine 100%）：容易被语义相近但不相关的内容干扰，精确性差。 60/40 的黄金比例：关键词精确匹配为主，语义相似度补充覆盖同义词场景。这两个参数可以自由调整，高创意场景可以降低 FTS 权重。

④

为什么上下文压缩要有三种策略？

不同场景有不同需求：
• pruning（修剪工具结果）：适合工具密集型对话（如写代码），工具返回值往往很长但不需要长期保留
• lossless（无损归档）：适合知识工作（研究、规划），内容有长期价值，不能丢
• abstractive（抽象原理）：适合长期对话关系，不需要记住具体事件，只要"理解模式"
三选一，或者按场景轮换使用。

⑤

为什么会有"遗忘曲线 + 温度采样"这种创意引擎？

静态记忆库的问题：所有笔记权重相同，旧的重要信息会被频繁检索，新的重要信息反而被挤掉。引入 Ebbinghaus 衰减后，旧信息自然降权，新信息自动突出——就像人类大脑的工作方式。
温度采样解决的是另一个问题：确定性 Top-K 检索让 AI 永远只看"最相关的"笔记，陷入固有思维定势。Softmax 采样让低相关度的笔记也有出现机会，产生意想不到的关联——这正是人类"灵感"的来源。

⑥

为什么 Web UI 不用任何前端框架？

React/Vue 带来的问题：需要 npm、需要构建步骤、需要 node_modules。这与 HushClaw "零依赖"的哲学冲突。 纯 JavaScript + CSS 变量 + WebSocket 实现了同等功能：实时流式输出、Session 管理、设置面板、深色/浅色主题。代码更少，部署更简单，没有构建步骤，直接 serve 静态文件。

配置优先级：从低到高

1

内置默认值

defaults.py 中的合理默认参数

2

用户配置

~/Library/Application Support/hushclaw/hushclaw.toml

3

项目配置

.hushclaw.toml（当前目录，覆盖用户配置）

4

环境变量

HUSHCLAW_* 前缀，最高优先级，适合 CI/CD

更新机制：自动检查 + 一键升级

内置 GitHub Releases 检查器，服务启动时自动检测新版本（24小时间隔，可关闭）。 WebSocket 推送 update_available 事件给前端，弹出升级确认。一键运行 install.sh --update，输出进度流式推送到 UI。支持稳定版（stable）和预发布版（prerelease）两个更新频道。

竞品对比

与同类方案的客观比较

没有银弹。HushClaw 在某些维度领先，在某些维度也有明显的局限。

维度	HushClaw	ChatGPT	LangChain	AutoGPT
持久记忆	✓ 混合检索+遗忘曲线	△ 有限，不透明	需自建	需自建
Token 精细控制	✓ 分区预算+KV-Cache	黑盒	△ 基础	无
零依赖部署	✓ Python stdlib only	N/A SaaS	大量依赖	大量依赖
多模型支持	✓ 9+ 提供商	仅 OpenAI	✓ 广泛	△ 有限
IM 平台接入	✓ 6 大平台	无	无	无
多 Agent 编排	✓ Pipeline+层级	无	✓ 支持	✓ 自主规划
私有化部署	✓ 完全本地	仅云端	✓	✓
内置 Web UI	✓ 无构建步骤	✓ 官方	无	△ 简陋
生态成熟度	早期	✓ 成熟	✓ 成熟	△ 一般
学习曲线	✓ 低（开箱即用）	✓ 极低	陡峭	△ 中等

🎯

HushClaw 最适合的用户画像：想要私有部署、需要跨会话记忆、有精细 Token 成本控制需求、要同时接入多个 IM 平台的技术型个人用户或小型团队。它不是为不懂代码的普通用户设计的，也不是企业级生产系统的替代品（至少目前还不是）。

HushClaw每一个细节，都有设计理由

HushClaw 到底是什么？

三个被解决的核心痛点

产品形态：不是单一工具，而是框架

ReAct 主循环：每次对话的完整流程

Token 管理：每一分钱都花在刀刃上

Token 预算分配图

KV-Cache 优化：为什么要分稳定/动态两部分？

三种压缩策略：历史太长时如何处理？

自动事实提取：10 类正则模式，零成本

持久化记忆：模拟人类大脑的工程实现

双层存储架构

检索流程：混合搜索的完整决策树

本地向量嵌入：零 API 成本的实现原理

空查询 = 灵感模式（Serendipity）

所有可调参数一览

工具系统：AI 如何调用外部能力

工具三层结构

工具执行逻辑：上下文注入模式

内置工具清单

技能包（Skill Packages）：可插拔的专业能力

多 Agent：AI 团队如何协作

Gateway 网关的核心职责

Pipeline 流水线：Agent 串联的工作流

Agent 组织层级

三种 Agent 间通信方式

连接器：每个平台的接入细节

模型调用层：9 个提供商，统一接口

重试机制

设计决策背后的产品逻辑

配置优先级：从低到高

更新机制：自动检查 + 一键升级

与同类方案的客观比较

HushClaw
每一个细节，都有设计理由