Context Pipe

⛓️ Context-Pipe

上下文工程的通用标准。

context-pipe 是一个高性能编排层，直接受到 Unix 终端管道的启发——正是这种理念，让 cmd1 | cmd2 | cmd3 成为计算领域最经久不衰的组合原语。就像终端通过 stdin/stdout 字节流串联进程一样，Context-Pipe 通过上下文流串联 AI 工具调用：每个节点各司其职，将输出传递给下一个节点，而 LLM 只会看到最终提炼后的信号。

这不是比喻，而是字面意义上的扩展。Context-Pipe 同时支持 MCP 管道（通过编排器串联 MCP 工具调用）和 终端管道（任何读取 stdin 并写入 stdout 的二进制程序、Shell 命令或脚本都是有效节点）。这两种模式可以在同一个管道定义中自由组合。通过 mcp-pipe CLI，它还能扩展终端本身：mcp-pipe tool 子命令可让任何 MCP 服务——context-mode、serena、GitHub、Firecrawl，或在 pipes.json 中注册的任何服务——都能直接通过 Shell 使用，按需加载，无需包装脚本，也无需 IDE：

cat error.log | mcp-pipe tool semantic-sift sift_logs | rg "CRITICAL"
curl -s https://example.com | mcp-pipe tool firecrawl scrape | mcp-pipe run semantic-refinery

如今，mcp-pipe run <pipe> 已让终端能够直接访问 pipes.json 中定义的任何命名管道，并通过与 IDE 相同的编排器组合终端二进制程序。

---

🚀 愿景

AI Agent 面临一个根本性的基础设施问题：每次工具调用都会将未经处理、未经筛选的原始输出直接送入上下文窗口。日志带着时间戳涌入。搜索结果夹杂着模板文本。Agent A 的 40KB 分析内容被原封不动地传给 Agent B。上下文窗口被填满。信号淹没在噪声中。LLM 性能随之下降。

context-pipe 在基础设施层解决这个问题——在 LLM 看到任何内容之前。

按照 Studio of Two 理念，我们构建的是 系统，而非补丁。补丁是为每个工具定制一个过滤器。系统则是一种通用协议：任何读取 stdin 并写入 stdout 的工具都能成为节点。任何节点序列都能组成管道。每条管道都有名称、版本、审计记录，并可在每个项目和每种 Agent 框架中重复使用。

由此构成一条上下文供应链：原始数据进入后，依次经过一系列精炼器（规范化 → 过滤 → 压缩 → 提炼），最终以高密度、高信号内容的形式到达 LLM。每个节省的字节都会记录在上下文资产负债表中。每次管道运行都可追踪。每次 A2A 交接都有保障。

这不是 semantic-sift 的包装层，而是让任何精炼器都能组合、可观测并达到生产级标准的编排层。节点可以是二进制程序、Shell 命令、Python 脚本，也可以是完整的 MCP 工具（Figma、GitHub、context-mode，或在 pipes.json 中注册的任何服务）。只要能读取 stdin 并写入 stdout，就能加入管道。

示例 — 爬取网页、开展研究、保存并发布：

trigger: tool:web_search | tool:web_fetch

[URL]
    → firecrawl/scrape             # MCP node: fetch live page as clean text     ~18,400 tokens
    → markitdown                   # binary node: convert to structured Markdown     ~16,200 tokens
    → rg 'security|vulnerability'  # shell node: surface only relevant sections      ~3,100 tokens
    → prettier --parser markdown   # shell node: normalize formatting                ~3,050 tokens
    → semantic-sift-cli doc        # binary node: distil to high-signal summary        ~420 tokens
          ↳ tee → research.md      # T-pipe: save raw distilled copy to disk
    → security-auditor             # script node: project-specific logic               ~380 tokens
    → github/create_issue          # MCP node: open a tracked issue with findings

Context Balance Sheet (illustrative)
  in:  18,400 tokens  →  out: 380 tokens  —  97.9% saved  ·  1.2s total

每个节点都是真正的子进程。T 型管道可随时保存原始副本，而不中断链路。LLM 只会收到重要内容——每个输入字节、输出字节以及每毫秒延迟，都会自动记录在上下文资产负债表中。

---

🛠️ 核心组件

1. 上下文管道协议（CPP）

一种与语言无关的标准，仅有一条规则：节点读取 stdin，转换内容，然后写入 stdout。任何遵守此约定的二进制程序、Shell 命令、Python 脚本或 MCP 工具都是有效节点。协议定义于 doc/CONTEXT_PIPE_PROTOCOL.md，并刻意保持简单——无需 SDK、无需注册，也不与任何框架耦合。

2. 编排主干（orchestrator.py）

将节点串联成管道的执行引擎。它会将每个节点作为真实的操作系统子进程运行，并强制使用 shell=False（不留注入入口）。功能包括：单节点超时保护（PIPE_NODE_TIMEOUT_MS）、T-Pipe 流拆分（在节点处理前将原始输入保存到磁盘），以及完整的跟踪记录（每个节点的输入／输出大小和延迟）。

3. 通用路由台（pipes.json + 映射）

由数据驱动的路由会根据三种触发条件自动选择最优管道：工具名称（tool:regex）、载荷大小（size:>N）和默认回退。管道定义存放于 pipes.json（项目级），也可存放于 ~/.mcp-pipe.json（全局配置，与本地配置合并，本地优先）。添加、修改或重新路由管道都无需更改代码。

4. MCP 接口（server.py + mcp-pipe CLI）

八个 MCP 工具可将所有功能直接提供给 AI 助手：pipe_run、pipe_run_dynamic、pipe_read_file、pipe_analyze_file、pipe_list_shadow_tools、pipe_agent_handoff、get_pipe_stats 和 pipe_onboard。mcp-pipe CLI 为终端优先的工作流提供相同的接口——无需 IDE。影子工具发现（pipe_list_shadow_tools）会向 Agent 提供实时能力清单，其中整合了已配置的管道和精选的 PATH 工具（jq、rg、markitdown、pandoc……）。

5. 潜意识拦截器（pipe_hook.py + onboarding.py）

IDE 钩子会在每次工具调用后透明地应用管道，无需 Agent 显式调用 pipe_run。支持的环境包括：Cursor（postToolUse）、VS Code/GitHub（hooks）、Claude Code/Qwen/Codex（PostToolUse）、Windsurf 和 Cline（读取前安全网关）、OpenClaw（原生插件）以及 pi.dev（原生 TypeScript 扩展）。对于 OpenCode，当前采用的策略是强制执行 AGENTS.md SOP（参见已知限制）。pipe_onboard 只需一条命令，即可注入所有钩子、斜杠命令（/pipe-run、/pipe-dynamic、/pipe-handoff、/pipe-stats）和完整的 Agent SOP。

6. A2A 桥接器（a2a.py）

pipe_agent_handoff() 会精简 Agent A 的输出，再将其传入 Agent B 的上下文窗口。与框架无关，无需猴子补丁。可用于 CrewAI 任务回调、Google ADK 转交钩子、LangGraph 边函数或任何自定义交接点。既可作为 Python 函数使用，也可作为 MCP 工具使用。发生任何错误时，都会原样返回原始输出，因此 Agent 链不会中断。

7. 原生 Rust 核心（crates/cpipe）

cpipe 是 Context-Pipe 生态系统中高性能的 Rust 核心。它将完整的编排引擎——包括配置合并、占位符解析、流路由和自感知旁路保护——移植到预编译的原生二进制程序中，启动延迟低于 2ms（比 Python 运行时快 500 倍）。它与 Python 服务并存：MCP 工具仍由 Python（FastMCP）提供，而 Rust 二进制程序则可用作 Tauri sidecar、独立 CLI（cpipe run、cpipe list、cpipe serve）或 Cargo 库，以便直接嵌入 Rust 应用程序。完整 API 参见 crates/cpipe/README.md。

8. TypeScript/JavaScript 客户端（packages/cpipe-js）

@context-pipe/client 是引擎的浏览器安全型沙盒客户端移植版。它完全在内存中模拟 Unix 管道，支持标准节点（grep、replace），允许注册自定义 PWA 节点（RAG 数据库查询、CORS 代理），并全面集成 AbortSignal 以支持取消操作。完整 API 和示例请参阅 packages/cpipe-js/README.md。

---

✨ 有何不同

特性	功能	位置
面向 AI 的 Unix 管道模型	将任意 stdin 和 stdout 工具串联成命名管道。无论是二进制程序、shell、脚本还是 MCP 工具，都遵循同一契约。	高级节点类型
MCP 节点类型	将任意 MCP 工具（Figma、GitHub、context-mode）作为一等管道节点调用，无需包装脚本。	doc/MCP_NODE_SPEC.md
无需编译的拓扑配置	路由配置在 pipes.json 中，而非节点代码中。编辑映射即可重新路由、分支或替换节点，无需更改代码、重新编译或重新部署任何节点。	doc/ARCHITECTURE.md
协议优先的 MCP 组合	更改服务键即可替换任意 MCP 服务。无需导入、声明依赖或构建。每个 MCP 服务都使用同一协议，整个生态系统都是即插即用的能力层。	doc/ARCHITECTURE.md
动态管道	AI Agent 可在运行时通过 pipe_run_dynamic 构建并执行临时节点列表，无需在 pipes.json 中添加条目。	动态管道
影子 MCP 注册表	在需要时才让 Agent 看到实用型 MCP 服务的工具列表。pipe_list_shadow_tools 可按需查询这些服务。	影子 MCP 注册表
A2A Agent 移交	在 Agent A 的输出进入 Agent B 的上下文窗口前进行提炼；与框架无关，无需猴子补丁。	A2A 移交
版本感知	在 pipe_verify 和 pipe_onboard 中提供由 GitHub 支持的主动更新提醒，确保环境一致。	健康检查
流完整性	强化编排引擎，具备非 UTF-8 内容处理能力（errors="replace"）和空值安全读取能力。	doc/ARCHITECTURE.md
T 管道流拆分	在节点输入经过提炼前，将其原始副本保存到磁盘，用于审计、调试和质量衡量。	3. T 管道节点（流拆分）
自适应上下文窗口压力	向每个节点传递剩余上下文容量；semantic-sift 会据此自动调整 --rate。	环境变量
全局配置	在所有项目间共享管道定义和 MCP 服务注册表；本地 pipes.json 始终优先。	doc/ARCHITECTURE.md
注入 Shell 别名	pipe_install_aliases 会将 mcp-pipe / cpipe 写入 Shell 配置文件，无需激活 venv 即可在终端中使用。	终端用法：MCP Pipe CLI
Git 保护	pipe_onboard 会自动更新 .gitignore，防止内部产物被提交。	自动引导
上下文收支表	记录每次管道运行：输入字符数、输出字符数、每个节点的延迟、Agent 归属和净 ROI。	遥测与 ROI

---

🧠 架构：语义枚举（解决架构膨胀）

在标准 MCP 配置中，公开多种能力（PDF 解析、日志搜索、HTML 清理）意味着要公开多个工具。这会导致架构膨胀：大模型的系统提示词会塞满数千个 Token 的复杂工具说明。对于小型语言模型（SLM），这会挤占聊天记录的空间、压垮上下文窗口，并导致幻觉。

context-pipe 通过语义枚举解决这一问题。 无需教 AI 如何使用复杂的命令行工具，只需公开一个工具：pipe_run(input, pipe_name)。pipe_name 参数只是一个由预定义管道组成的枚举（例如，["parse-and-clean-pdf", "extract-critical-errors"]）。

这样就能完美地将意图与执行分开：

• 大模型提供意图： “我需要这份 PDF 的纯净文本，因此会调用 parse-and-clean-pdf 管道。”
• pipes.json 提供执行方式： [pandoc -> jq -> semantic-sift]

使用简短精炼的管道名称，可以大幅压缩提示词。AI 看到的是一个高层级的“按钮”菜单，而不是主机上每个工具的使用说明。更重要的是，如果你升级后端工具（例如，将 pandoc 换成 markitdown），完全不必更新大模型的提示词。AI 仍会调用同一个管道，只是底层引擎变得更快了。

---

🔧 三个相互独立的变更维度

CPP 管道将关注点分为三个层，每一层都按照完全独立的周期演进：

层	内容	变更方式
节点	每个步骤的功能——一个不了解周围管道的简单 stdin/stdout 工具	替换二进制文件、脚本或 MCP 工具
pipes.json	拓扑结构——步骤如何连接、分支和路由	编辑映射。无需更改代码、重新编译或重新部署。
MCP 服务	每次工具调用背后的能力	更改服务键。无需导入、声明依赖或经历构建流程。

提升节点质量不会改变拓扑结构。调整路由结构不会影响任何节点。升级 MCP 服务会自动改进所有使用它的管道，无需更改管道。

**对于 MCP 节点而言，**这彻底消除了传统的依赖模型。每个 MCP 服务都使用相同的协议：JSON-RPC、tools/call、文本响应。管道不依赖于由什么来实现服务，而依赖于什么能使用该协议进行通信。因此，整个 MCP 生态系统构成了管道的能力层。所有当前和未来的 MCP 服务，只要提供相同的语义功能，就能直接替换任何对应节点。

在脚本中，你依赖于导入的内容。在管道中，你依赖于能使用该协议进行通信的内容。

这种分离还意味着路由无需编译。在传统脚本中，安全防护和恢复逻辑都嵌入代码中——更改工作流的恢复方式需要修改、测试并重新部署脚本。而在 CPP 中，路由位于 pipes.json 中。添加分支、重新路由或替换节点，都只是修改配置。从“如果我重新路由这一步会怎样”到“让我看看结果如何”的反馈周期几乎缩短为零。

---

🚀 快速入门（60 秒）

# 1. Install
pip install mcp-context-pipe "semantic-sift[neural]"

# 2. Onboard (auto-creates pipes.json + hooks for your IDE)
context-pipe-onboard   # or: ask your AI "Run pipe_onboard()"

# 3. Verify the full stack
echo "noisy log [14:22:05.123] DEBUG: heartbeat ok" | context-pipe run standard-distill
# → distilled, noise-free output with audit header

完整设置指南（主权双仓库模式、venv 布局、IDE 配置）：doc/OPERATOR_GUIDE.md

---

🏗️ 入门指南

1. 安装

选项 A：快速安装（PyPI）

由于 MCP 服务要求在 IDE 配置中指定 Python 可执行文件的路径，因此必须先创建虚拟环境：

**ℹ️ 安装内容：**此操作会安装 Context-Pipe 编排层和 Semantic-Sift 的核心 Python 服务。用于近乎即时启发式筛选的 sift-core Rust 二进制文件包含在 PyPI wheel 中——无需 Rust 工具链。[neural] extra 会添加 PyTorch（约 1.5 GB），用于大型负载的语义压缩。

uv venv
# Windows: .\.venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
uv pip install mcp-context-pipe "semantic-sift[neural,multi-modal]"

选项 B：主权模式（推荐双人工作室使用） 将两个仓库克隆到同级目录。context-pipe venv 作为主环境，容纳这两个包。完整步骤请参阅**《操作员指南》第 0 节**。

# 1. Clone both repos
git clone https://github.com/luismichio/context-pipe.git
git clone https://github.com/luismichio/semantic-sift.git

# 2. Master venv in context-pipe - holds both packages
cd context-pipe
python3.12 -m venv venv
# Windows:
.\venv\Scripts\activate
# macOS/Linux:
# source venv/bin/activate
uv pip install -e .
uv pip install -e ../semantic-sift  # semantic-sift-cli lands in context-pipe/venv/Scripts/ (Win) or venv/bin/ (Mac/Linux)

# 3. ML runtime venv in semantic-sift (Python 3.12 for torch/CUDA compatibility)
cd ../semantic-sift
python3.12 -m venv venv312
# Windows:
.\venv312\Scripts\activate
# macOS/Linux:
# source venv312/bin/activate
uv pip install -e .[neural]         # torch, transformers, llmlingua

**注意：**PyPI 上的包名是 mcp-context-pipe，但安装的模块是 context_pipe。semantic-sift-cli 二进制文件仅会注册到通过 pip 安装 semantic-sift 的 venv 中（上文第 2 步）。两个 pipes.json 文件都必须引用该绝对路径。

2. 连接 MCP

重要：Cursor、Gemini、Antigravity、OpenCode、VS Code 和 Claude 的准确配置路径，请参阅主配置矩阵。

3. 连接精炼器

Context-Pipe 是“交换机”，但它需要一个“精炼器”来提炼数据。Semantic-Sift 是该生态系统的旗舰智能引擎。它使用启发式筛网和神经模型（BERT/ONNX）清除噪声（时间戳、模板文本），同时保留 95% 的有效信息。

**注意：**在主权模式下，semantic-sift 会跨安装到 context-pipe/venv 中（上文第 2 步）。Context-Pipe 也会通过 pipe_onboard 或 pipe_verify，在所有已知位置（系统 PATH、pipx、同级 venv 目录）自动发现单独安装的 semantic-sift-cli。

4. 验证安装

安装这两个包后，请让 AI 助手验证完整技术栈：

“运行 pipe_verify() 以确认安装情况。”

此操作会报告每个组件的运行状况；如果在单独的环境中找到 semantic-sift-cli，还会自动将其关联到 pipes.json。

5. 配置你的第一个 Pipe

编辑 pipes.json（参见 pipes.json.example），定义高保真上下文流。

6. 自动初始化

连接后，请让 AI 助手配置你的工作区：

“运行 pipe_onboard(environment='Cursor') 来配置此项目。”

如果省略 environment，pipe_onboard 会自动检测 IDE——它会检查环境变量和父进程名称，以识别 12 个以上的平台（Cursor、Gemini、Antigravity、OpenCode、VS Code、Windsurf、Claude、Cline 等）。仅当自动检测结果不明确时，才显式传入 environment。

---

📚 文档

详细文档位于 doc/ 目录中。

• doc/INDEX.md：文档体系的导航路线图。
• doc/USE_CASES.md：真实且影响显著的场景，展示如何串联 Bash、脚本节点和 Semantic-Sift。
• doc/OPERATOR_GUIDE.md：关于设置、终端使用和 pipes.json 配置的权威指南。
• doc/ARCHITECTURE.md：编排主干和交换机的技术规格。
• doc/CONTEXT_PIPE_PROTOCOL.md：与编程语言无关的工具互操作标准。
• doc/INTEGRATION_ENCYCLOPEDIA.md：Cursor、VS Code、Gemini/Antigravity 和 Claude 的主兼容性矩阵。

---

🐍 编程式用法

Python

Context-Pipe 提供单个 pipe() 函数，可直接集成到 Python 脚本、笔记本和 Agent 框架（LangChain、CrewAI 等）中——无需 MCP 服务或命令行。

from context_pipe import pipe

# Auto-route based on pipes.json mappings
clean = pipe(raw_logs, tool_name="bash")

# Specify a pipe explicitly
distilled = pipe(document_text, pipe_name="semantic-refinery")

# Minimal usage — returns input unchanged if no pipe resolves
result = pipe(text)

函数签名：

def pipe(
    text: str,
    pipe_name: str | None = None,
    tool_name: str = "",
    config_path: str = "pipes.json",
    vars: dict | None = None,
) -> str: ...

发生任何错误（子进程失败、缺少配置等）时，该函数始终原样返回输入的 text，因此可安全地用作即插即用的过滤器。

JavaScript/TypeScript

对于客户端运行时（浏览器、PWA、扩展程序），请安装沙箱化软件包：

npm install @context-pipe/client

初始化 PipelineEngine 并运行配置：

import { PipelineEngine } from '@context-pipe/client';

const engine = new PipelineEngine({ failFast: true });

// Run a named pipe configuration
const output = await engine.runPipe(pipeConfig, rawLogs);

有关注册自定义数据库或 fetch 节点以及处理取消操作的详情，请参阅客户端 README。

Rust 库（cpipe）

对于 Rust 或 Tauri 应用，可直接嵌入原生核心：

use cpipe::config::load_pipes_config;
use cpipe::orchestrator::run_pipe;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let config = load_pipes_config();
    let pipe = config.pipes.iter().find(|p| p.name == "standard-distill")
        .ok_or("Pipe not found")?;

    let (output, _telemetry) = run_pipe(
        pipe,
        "raw context text here",
        Some("my-tool"), None, &config.servers,
    ).await;

    println!("{output}");
    Ok(())
}

添加到 Cargo.toml：

[dependencies]
cpipe = { git = "https://github.com/luismichio/context-pipe", path = "crates/cpipe" }

可在 GitHub Releases 页面获取适用于 Windows、macOS（Intel 和 Apple Silicon）及 Linux 的预构建二进制文件，也可通过以下方式下载：

python scripts/fetch_cpipe.py

---

🤝 A2A（Agent-to-Agent）交接

串联多个 Agent 时，可使用 pipe_agent_handoff 精简 Agent A 的输出，再将其传入 Agent B 的上下文窗口。适用于任何框架——无需猴子补丁。

from context_pipe.a2a import pipe_agent_handoff

# In a CrewAI task callback, ADK transfer hook, or any custom handoff point:
agent_b_input = pipe_agent_handoff(
    agent_a_output,
    pipe_name="semantic-refinery",   # optional; auto-routes if omitted
    from_agent="researcher",
    to_agent="writer",
)

也可作为 MCP 工具使用——向 AI 助手提出请求：“运行 pipe_agent_handoff()，在传递之前精简此 Agent 的输出。”

函数签名：

def pipe_agent_handoff(
    output: str,
    pipe_name: str | None = None,   # explicit pipe; auto-routes if omitted
    from_agent: str | None = None,  # producing agent label (telemetry + routing)
    to_agent: str | None = None,    # consuming agent label (telemetry only)
    config_path: str = "pipes.json",
) -> str: ...

发生任何错误时，始终原样返回输入的 output——Agent 链不会中断。

---

💻 终端用法（mcp-pipe CLI）

Context-Pipe 内置了一流的终端运行器——mcp-pipe——让你无需 IDE 或 MCP 服务即可使用所有功能。

# Run a named pipe on stdin
cat app.log | mcp-pipe run standard-distill

# Run a named pipe on a file directly
mcp-pipe run semantic-refinery --file spec.md

# Run an ad-hoc node array (shell synergy requires --allow-shell)
echo "noisy output" | mcp-pipe run-dynamic '[{"cmd":"semantic-sift-cli","args":["logs"]}]'

# List all configured pipes + curated PATH tools (Shadow MCP discovery)
mcp-pipe list

# Print the Context Balance Sheet (ROI across all sessions)
mcp-pipe stats

# Start the MCP server manually (stdio transport)
mcp-pipe serve

# Install/remove the cpipe shell alias
mcp-pipe aliases install
mcp-pipe aliases remove

执行 pip install mcp-context-pipe 时会自动注册 mcp-pipe 入口。运行 mcp-pipe aliases install 后，可使用 cpipe 作为简写命令。

Shadow MCP 注册表

你添加到 IDE 的每个 MCP 服务都会将其工具全局注册——无论 Agent 是否需要，它们都会出现在工具列表中。规模扩大后，这会导致 MCP 工具臃肿：提示词中包含数百个工具，每次推理调用都会浪费令牌，Agent 选错工具的概率也会增加。

context-pipe 采用了不同的方法。它不会将每个上下文处理工具都注册为一级 MCP 工具，而是提供一个发现工具——pipe_list_shadow_tools，按需返回实时能力清单。Agent 请求使用之前，这些工具会保持隐藏（“shadow”）状态。一个 MCP 工具即可完成多个工具的工作。

清单包含：

1. pipes.json 中的管道——项目中配置的所有命名管道。
2. 精选 PATH 工具——探测 7 个常用 CLI 工具（jq、yq、markitdown、pandoc、rg、fd、bat），并列出 PATH 中找到的工具。

**已知限制：**shadow 工具无法作为独立 MCP 工具调用——Agent 必须通过 pipe_run 或 pipe_run_dynamic 调用它们。这是有意为之（可让 MCP 接口保持精简），但意味着 Agent 无法直接调用 jq 或 markitdown，必须先构建动态管道节点。

**通过 mcp-pipe 访问终端：**无需 IDE 或 MCP 服务，也可使用同一份清单——mcp-pipe list 会将所有管道和精选 PATH 工具打印到标准输出。可直接在终端中将内容通过 shadow 工具传递：

# Discover what's available
mcp-pipe list

# Run a shadow tool via a dynamic pipe — no pipes.json entry needed
echo "# My Doc" | mcp-pipe run-dynamic '[{"cmd":"markitdown"},{"cmd":"semantic-sift-cli","args":["doc"]}]'

---

🔗 高级节点类型

Context-Pipe 支持的不只是简单的二进制文件。你可以串联标准操作系统工具和专业指令。

1. Bash 节点（沙箱化）

在管道中执行任意 Shell 命令。为防止注入漏洞，所有命令均通过 shell=False 原生执行。

{ "cmd": "grep", "args": ["ERROR"] }

2. 脚本节点

执行项目专用脚本（Python/Shell）或本地指令集。默认从 .gemini/scripts/ 解析。

{ "type": "script", "cmd": "security-auditor" }

3. T-Pipe 节点（流分流）

在节点精炼数据流之前，先将原始副本保存到磁盘，而不中断处理链。适用于调试管道质量，以及审查筛除的内容。

{
  "cmd": "semantic-sift-cli",
  "args": ["logs"],
  "tee": {
    "sink": "file",
    "path": "logs/{tool_name}_{iso_date}.log",
    "mode": "append"
  }
}

path 支持 {iso_date}（YYYY-MM-DD）和 {tool_name} 标记。T 形分流失败不会中断主处理链。

4. MCP 节点

将任意 MCP 工具作为管道节点调用。无需包装脚本——编排器会启动 MCP 服务、调用工具，并通过 stdout 将结果传递给下游。

{
  "type": "mcp",
  "server": "figma",
  "tool": "get_file",
  "input_key": "file_id"
}

服务定义位于 pipes.json 或 ~/.mcp-pipe.json 的 servers 块中。完整规范请参阅 doc/MCP_NODE_SPEC.md。

5. 验证器节点（Phase 11）

验证器会运行子进程，并根据其退出代码进行路由，而不是线性流转。可借此构建自愈管道，在失败前自动尝试修复问题。

{
  "name": "self-healing-lint",
  "nodes": [
    {
      "cmd": "eslint",
      "args": ["--format", "compact", "src/"],
      "type": "validator",
      "id": "lint-check",
      "branches": {
        "0": "done",
        "1": "auto-fix",
        "default": "auto-fix"
      }
    }
  ],
  "branch_sequences": {
    "auto-fix": [
      { "cmd": "eslint", "args": ["--fix", "src/"] },
      { "cmd": "semantic-sift-cli", "args": ["logs"] }
    ],
    "done": [
      { "cmd": "semantic-sift-cli", "args": ["logs"] }
    ]
  }
}

• 退出代码 0 → lint 检查通过，跳转到 done（精炼干净的报告）。
• 退出代码 1 → lint 检查失败，跳转到 auto-fix（运行 --fix，然后精炼）。
• "default" 会捕获其他任何退出代码（例如 ESLint 配置错误时的 2）。
• 验证器的 stdout 会作为输入转发给目标序列。

6. 条件键（Phase 11）

任何节点都可以有条件地跳过，而无需修改管道定义：

{
  "cmd": "neural-summariser",
  "condition": "size:>8000"
}

只有当前输入超过 8 000 字节时，该节点才会运行。支持的谓词：

谓词	示例	节点运行条件
size:>N	size:>10000	输入长度 > N 字节
size:<N	size:<500	输入长度 < N 字节
artifact:exists:<path>	artifact:exists:dist/app.js	文件存在于磁盘上
artifact:missing:<path>	artifact:missing:output/report.md	文件不存在
contains:<string>	contains:ERROR	开头 300 个字符包含该子字符串

未知谓词会默认放行（发出警告并运行节点），以避免在无提示的情况下阻塞管道。

🔗 生态系统（Studio of Two）

Context-Pipe 是 Studio of Two 基础设施的重要组成部分，旨在与以下项目高度协同：

• Semantic-Sift：面向 Agent 上下文的智能精炼工具。Sift 是 Context-Pipe 的旗舰精炼引擎，为标准模板提供数学和神经筛选节点。
• std-context-lab：官方集成实验室和测试场。此代码库是我们的隔离测试场，用于模拟和验证跨代码库功能、MCP 服务组合以及终端钩子交互。
  • 隔离场景：运行模拟真实 AI 行为的隔离测试用例，以便在不污染核心运行环境的情况下重现问题并验证修复。
  • 实证证据：每个已解决的错误或已实现的功能都有对应的执行日志（EVIDENCE.md），作为成功的实证。
  • 平台一致性门禁：在发布前，审核 Python/Rust CLI 的一致性，以及 Windows（PowerShell/CMD）和 UNIX 终端上的 Shell 行为。

---

🧩 工具协同与边界

四种工具常在 Studio of Two 技术栈中一起出现。它们相辅相成，并非功能重叠——每种工具负责不同的层。

工具	层	主要职责	关系
context-pipe	编排	通过命名管道传递内容；管理节点执行、超时、T-pipe、遥测和 A2A 交接。	配电盘。连接后会将所有其他工具作为节点调用。
semantic-sift	提炼	以启发式方法和神经网络压缩文本。去除噪声（时间戳、模板文本、重复词元），同时保留有效信息。	完全独立的命令行工具和 MCP 服务。也是 context-pipe 管道中的旗舰精炼节点。
context-mode	会话内索引	对当前 Agent 会话期间索引的内容进行 BM25 全文搜索。无需向量数据库即可快速检索。	完全独立的 MCP 服务。也可选作 mcp 节点接入管道，在管道中建立索引或进行搜索。
Serena	代码智能	基于 LSP 的符号搜索、重构和代码导航。理解 AST，而不只是文本。	完全独立的 MCP 服务。也可选作 mcp 节点接入管道，向管道提供精确的代码符号，而不是读取原始文件。

如何选择

**需要编排时使用 context-pipe：**串联工具、在工具调用时自动应用管道、按触发条件路由、保存 T-pipe 快照、核算 ROI，或衔接 Agent 交接。

**需要压缩时使用 semantic-sift：**处理大型文档、日志文件、搜索结果，或任何噪声与有效信息比例较高的负载。可通过命令行或 MCP 独立运行，也可作为节点运行在 context-pipe 管道中。

**需要检索时使用 context-mode：**本次会话中已有摄取的内容，并且希望通过 BM25 快速搜索。它可以作为 MCP 服务独立运行于任何 IDE 中。将它与 semantic-sift 配合使用，分别处理索引前后的内容——在上游压缩内容后再建立索引（索引更小，搜索更快），并在下游提炼检索到的片段后再将其放入上下文窗口。

**需要浏览代码时使用 Serena：**查找符号、追踪引用、检查类型或执行重构。它可以作为 MCP 服务独立运行。与原始文件读取相比，它结构化且精确的输出更适合作为任何下游工具的输入，包括筛选管道。

互补配置——减少词元用量

每种工具都能独立减轻词元压力。结合使用时，节省效果会叠加：

• Serena 只返回你要求的符号，而非整个文件。
• semantic-sift 会在内容进入 context-mode 前压缩内容（索引更小，搜索更快），并在检索后压缩内容（将无噪声片段送入上下文窗口）。
• context-mode 只返回相关的已索引片段，而非全部已摄取的内容。
• context-pipe 确保这一流程自动执行并纳入核算，无需针对每项任务手动连接。

结果是：每次会话中，Agent 处理的原始词元量只有一小部分，同时无需改变其思考方式或调用的工具。

协同示例

[user query]
    → serena/find_symbol           # MCP node: precise code symbol — not a raw file dump
    → context-mode/search          # MCP node: retrieve related session context
    → semantic-sift-cli semantic   # binary node: compress both into a dense summary
    → security-auditor             # script node: project-specific logic

四种工具在同一条管道中，各司其职。

---

⚙️ 环境变量

变量	默认值	描述
PIPE_CONFIG_PATH	pipes.json	项目 pipes.json 配置文件的绝对路径。
PIPE_NODE_TIMEOUT_MS	30000	每个节点的执行超时时间，单位为毫秒。
allow_shell	false	启用动态管道中的任意 shell 命令节点（MCP 工具 pipe_run_dynamic / API run_dynamic_pipe()）。要求最后一个节点为 semantic-sift 终端命令，以确保上下文安全。
PIPE_LOG_LEVEL	（无）	默认管道日志级别（compact 或 verbose）。设置后为所有管道启用日志记录。
PIPE_LOG_PREFIX	[PIPE]	添加到 stderr 管道执行日志前的默认文本。

---

⚠️ 已知限制

OpenCode — MCP 工具输出拦截

“潜意识拦截器”功能（pipe_hook.py）通过注入钩子处理程序，在每次工具调用后触发，可透明地用于 Cursor、VS Code、Gemini CLI、Antigravity CLI 和 Claude Desktop。

OpenCode 是个例外。 OpenCode 插件的 Hooks 接口中声明了 tool.execute.after 钩子，但 OpenCode 运行时从未触发该钩子（通过审查 session/processor.ts、session/llm.ts、tool/registry.ts 和 agent.ts 的源代码予以确认）。插件的输出修改代码会悄无声息地变成空操作。

当前的变通方案：在上游支持透明钩子注入之前，AGENTS.md 中的 SOP 要求（所有文件读取都必须使用 pipe_read_file）是 OpenCode 当前采用的拦截策略。

• 上游议题：sst/opencode#21149
• 插件议题：sst/opencode#25918
• 已列入我们的待办事项：Phase 4.5 — 参见 doc/backlog.md

---

⚖️ 许可

context-pipe 基于 Apache License 2.0 许可。该项目由 Studio of Two 维护，采用“开源，封闭式贡献”模式，以确保架构完整性。

---

为智能时代构建高保真基础设施。