Skip to content

Why 层:CLI 与只读 MCP ​

Why 层把本机 Claude Code、Codex、DeepSeek Harness、Pi 与 Weft 画布里的对话放进同一份索引。从一个文件、一句原话、一个网址或 arXiv 论文编号出发,结果会指回命中的原始轮次。

安装 ​

安装命令并建立本地索引:

bash
npm install -g weft-canvas
weft index

接入只读 MCP 服务 ​

在准备使用它的项目目录中运行:

bash
weft setup mcp

它会为 Claude Code 写入当前项目的 .mcp.json,并在 ~/.codex/config.toml 中注册 Codex MCP。查询仍以当前工作区为范围。MCP 服务只能检索与回忆,不能编辑画布或来源会话。

其他支持本地 stdio 服务的客户端,可使用 weft mcp 启动。运行服务的机器需要 Node.js 20 或更新版本,以及受支持的本地会话日志。也可参照手动配置示例。

服务会在 ~/.weft 中写入派生索引,并把检索到的历史返回给调用它的 Agent;该 Agent 可能将内容发送给其配置的模型服务。原始会话日志不会被修改。

可选的 Codex Skill ​

bash
mkdir -p .agents/skills && cp -R /path/to/weft/protocol/adapters/codex/skills/weft .agents/skills/

此命令把仓库中的 Codex Skill 复制到当前项目。它可以运行 CLI 查询,或在 Weft 桌面应用中打开受支持的会话(本地桥接作为后备路径)。Skill 安装与 MCP 注册是两个入口,不会增加编辑画布的 MCP 工具。

可选:加入项目规则 ​

bash
weft setup rules
weft setup rules --remove

第一条命令会在当前项目的 CLAUDE.md 与 AGENTS.md 中加入带标记的规则,要求 Agent 在改动文件前先检查相关历史。第二条命令只移除这段标记内容,不会写入全局指令文件。

CLI 命令字典 ​

Harness 内的原生查询入口及其发布状态,参见 DeepSeek Harness 插件。原生工具的 why_find、why_recall 分别对应这里 MCP 的 find、recall_turn。

命令作用
weft index [--full] [--canvas <dir>]建立或刷新索引;可同时记住画布备份目录
weft why <path> [--include-read] [--all] [--limit N] [--json]显示碰过某个文件、网址或论文的轮次
weft why --check <path> [--fresh] [--json]低成本检查这个对象是否存在历史
weft find "<phrase>" [--in q|a|m] [--limit N] [--json]在问题、回答或材料中做不区分大小写的精确检索
weft recall <session> <n>完整输出某一轮对话
weft status查看索引规模与证据覆盖率
weft purge [--cache]删除全部派生数据,或只删除可重建缓存
weft events <session-file> [--touches]把一个来源文件投影为标准事件
weft mcp通过 stdio MCP 提供四个只读工具
weft setup [mcp | rules [--remove]]查看或修改项目接入状态

<path> 可以是绝对路径、相对当前工作区的路径、网址,或 arxiv:<id>。

MCP 工具字典 ​

工具参数返回内容
why_checkpath一行说明该对象有无历史
why_filepath,可选 include_read、limit命中的轮次与观察到的文件改动
findphrase,可选 in、limit问题(q)、回答(a)、材料(m)或全部范围内的精确命中
recall_turnsession、turn一轮完整的问题、回答与工具轨迹

输出标记字典 ​

标记含义
Q用户问题的原文片段
AAgent 回答的原文片段
MWeft 画布节点所附的文字材料
Δ从工具调用中观察到的编辑或写入
≈从回答中提取的候选解释,不是已经核验的事实
↗回到来源轮次或画布节点的入口

例子 ​

找到修改过一个文件的对话 ​

text
$ weft why src/lib/api.ts
why src/lib/api.ts · 12 个相关轮次,来自 6 个会话
claude-code  ✏️ 修改  Q: 能否判断模型是否支持多模态?
             Δ storedProviders → storedProviders, storedVision…

需要同时查看只读操作时加 --include-read;需要取消默认结果上限时加 --all。

找到一个概念出现在哪里 ​

text
$ weft find "context.committed" --in q
find "context.committed" · 21 个相关轮次,来自 12 个会话
claude-code  Q: ……把 context.committed 加入事件契约……
codex        Q: ……context.committed 已经实现了一半……

用 --in a 只搜回答,用 --in m 只搜画布材料。

找到一篇论文或一个网页 ​

bash
weft why arxiv:2606.26733
weft why https://example.org/paper
weft find "arxiv" --in m

完整查看某个命中轮次 ​

复制 why 或 find 输出中的会话 id 与轮次编号:

bash
weft recall <session-id> <turn-number>

如果已安装桌面版,↗ 链接会打开对应的轮次或画布节点。

需要可视化浏览会话、编辑上下文图时,继续阅读 Agent 对话地图。

Weft 以 MIT License 开源。