CrabPath

纯图核心：零依赖且无网络调用。调用方提供回调函数。

设计原则

• - 核心模块无网络调用
• 不进行密钥发现（不探测点文件、密钥链或环境变量）
• 无子进程提供程序包装器
• 在状态元数据中嵌入身份标识；维度不匹配视为错误
• 单一规范状态格式（state.json）

快速入门

python
from crabpath import split_workspace, HashEmbedder, VectorIndex

graph, texts = split_workspace(./workspace)
embedder = HashEmbedder()
index = VectorIndex()
for nid, content in texts.items():
index.upsert(nid, embedder.embed(content))

嵌入与LLM回调

• - 默认：HashEmbedder（hash-v1，1024维）
• 实际：回调函数 embedfn / embedbatchfn（例如 text-embedding-3-small）
• LLM路由：使用 gpt-5-mini 的回调函数 llmfn（示例）

会话回放

replay_queries(graph, queries) 可从历史轮次进行热启动。

CLI

优先使用 --state：

crabpath query TEXT --state S [--top N] [--json]
crabpath query TEXT --state S --chat-id CID

crabpath doctor --state S
crabpath info --state S
crabpath init --workspace W --output O --embedder openai
crabpath query TEXT --state S --llm openai
crabpath inject --state S --type TEACHING [--type DIRECTIVE]

实时修正流程：
python3 querybrain.py --chat-id CHATID
python3 learncorrection.py --chat-id CHATID

快速参考

• - crabpath init/query/learn/inject/health/doctor/info
• querybrain.py --chat-id 和 learncorrection.py 用于实时修正管道
• querybrain.py 遍历限制：beamwidth=8，maxhops=30，firethreshold=0.01
• 硬遍历上限：maxfirednodes 和 maxcontextchars（默认 None；querybrain.py 默认 maxcontextchars=20000）
• examples/correctionflow/，examples/coldstart/，examples/openaiembedder/

API参考

• - 核心生命周期：

- split_workspace - load_state - save_state - ManagedState - VectorIndex

• - 遍历与学习：

- traverse - TraversalConfig - TraversalConfig.beamwidth，.maxhops，.firethreshold，.maxfirednodes，.maxcontextchars，.reflexthreshold，.habitualrange，.inhibitorythreshold - TraversalResult - apply_outcome

• - 运行时注入API：

- inject_node - inject_correction - inject_batch

• - 维护辅助工具：

- suggestconnections，applyconnections - suggestmerges，applymerge - measurehealth，autotune，replayqueries

• - 嵌入工具：

- HashEmbedder - OpenAIEmbedder - default_embed - defaultembedbatch - openaillmfn

• - LLM路由回调：

- chat_completion

• - 图原语：

- Node - Edge - Graph - split_workspace - generate_summaries

CLI命令

• - crabpath init --workspace W --output O [--sessions S] [--embedder openai]
• crabpath query TEXT --state S [--top N] [--json] [--chat-id CHATID]
• crabpath learn --state S --outcome N --fired-ids a,b,c [--json]
• crabpath inject --state S --id NODEID --content TEXT [--type CORRECTION|TEACHING|DIRECTIVE] [--json] [--connect-min-sim 0.0]
• crabpath inject --state S --id NODEID --content TEXT --type TEACHING
• crabpath inject --state S --id NODEID --content TEXT --type DIRECTIVE
• crabpath health --state S
• crabpath doctor --state S
• crabpath info --state S
• crabpath replay --state S --sessions S
• crabpath merge --state S [--llm openai]
• crabpath connect --state S [--llm openai]
• crabpath journal [--stats]
• querybrain.py --chat-id CHATID
• learncorrection.py --chat-id CHATID

遍历默认值

• - beamwidth=8
• maxhops=30
• firethreshold=0.01
• reflexthreshold=0.6
• habitualrange=0.2-0.6
• inhibitorythreshold=-0.01
• maxfirednodes（硬性节点数量上限，默认 None）
• maxcontextchars（硬性上下文长度上限，默认 None；query_brain.py 默认值为 20000）

论文

https://jonathangu.com/crabpath/