# https://github.com/Dave-London/Pare 项目说明书
生成时间：2026-05-30 18:33:56 UTC
## 目录
- [Home - What is Pare?](#home)
- [Quickstart Guide](#quickstart)
- [Configuration Reference](#configuration)
- [Git Tools](#git-tools)
- [GitHub Tools](#github-tools)
- [Python Tools](#python-tools)
- [Docker Tools](#docker-tools)
- [Test Runner Tools](#test-tools)
- [System Architecture](#architecture)
- [Agent Integration Guide](#agent-integration)
## Home - What is Pare?
### 相关页面
相关主题：[Quickstart Guide](#quickstart), [System Architecture](#architecture), [Configuration Reference](#configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Dave-London/Pare/blob/main/README.md)
- [packages/shared/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/index.ts)
- [packages/server-git/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/index.ts)
- [packages/server-github/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/index.ts)
- [packages/server-python/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/index.ts)
- [packages/server-test/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/index.ts)
- [SECURITY.md](https://github.com/Dave-London/Pare/blob/main/SECURITY.md)
- [rules/GEMINI.md](https://github.com/Dave-London/Pare/blob/main/rules/GEMINI.md)
# Home - What is Pare?
## 概述
Pare 是一个专为 AI 编码代理设计的 **MCP（Model Context Protocol）服务器套件**，通过包装常见命令行工具并返回结构化 JSON 输出，帮助代理更高效地与开发环境交互。
资料来源：[README.md:1-50](https://github.com/Dave-London/Pare/blob/main/README.md)
### 核心价值主张
| 特性 | 说明 |
|------|------|
| **结构化输出** | 所有工具返回类型安全的 JSON，替代解析自由文本 |
| **Token 节省** | 自动紧凑模式减少输出 token 数量，通常比原始 CLI 输出少 30-50% |
| **可靠性提升** | 统一错误处理、跨平台兼容、安全验证 |
| **安全加固** | 内置注入防护和命令白名单机制 |
资料来源：[packages/shared/CHANGELOG.md:1-30](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
## 架构设计
### 整体架构
```mermaid
graph TD
subgraph "MCP 客户端"
A[Claude Code]
B[其他 AI Agent]
end
subgraph "Pare MCP 服务器"
C[@paretools/git]
D[@paretools/github]
E[@paretools/npm]
F[@paretools/test]
G[@paretools/python]
H[其他服务器...]
end
subgraph "底层 CLI 工具"
I[git]
J[gh]
K[npm/pnpm]
L[pytest]
end
A --> C
A --> D
A --> E
B --> F
B --> G
C --> I
D --> J
E --> K
F --> L
```
Pare 采用**模块化服务器架构**，每个服务器包负责一个工具领域。所有服务器共享 `@paretools/shared` 基础库，提供统一的运行机制、类型定义和工具函数。
资料来源：[packages/shared/src/index.ts:1-100](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/index.ts)
### 服务器包生态
| 包名 | 功能领域 | 工具数量 |
|------|----------|----------|
| `@paretools/git` | Git 版本控制 | ~30+ |
| `@paretools/github` | GitHub CLI (gh) | ~25+ |
| `@paretools/npm` | Node 包管理 | ~15+ |
| `@paretools/test` | 测试运行器 | ~10+ |
| `@paretools/python` | Python 生态 | ~10+ |
| `@paretools/docker` | Docker 容器 | ~10+ |
| `@paretools/lint` | 代码检查 | ~10+ |
| `@paretools/build` | 构建工具 | ~10+ |
| `@paretools/search` | 搜索工具 | ~5+ |
| `@paretools/http` | HTTP 客户端 | ~5+ |
| `@paretools/make` | Make/Just | ~5+ |
| `@paretools/cargo` | Rust Cargo | ~10+ |
| `@paretools/k8s` | Kubernetes | ~10+ |
资料来源：[packages/shared/CHANGELOG.md:50-80](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
## 核心特性
### 自动紧凑模式（Auto Compact Mode）
当结构化 JSON 输出超过原始 CLI token 计数时，Pare 自动应用紧凑投影策略：
```mermaid
graph LR
A[JSON 输出] --> B{超过 Token 阈值?}
B -->|是| C[应用紧凑投影]
B -->|否| D[保持完整输出]
C --> E[保留核心字段]
C --> F[丢弃详细堆栈]
C --> G[聚合统计信息]
```
**紧凑模式保留的核心字段：**
- `error` / `success` 状态
- 关键数值（如错误计数、通过/失败测试数）
- 文件路径摘要
- 首条错误信息
**紧凑模式丢弃的内容：**
- 完整堆栈跟踪
- 逐文件的详细统计
- 冗余的元数据
资料来源：[packages/server-docker/CHANGELOG.md:20-40](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/CHANGELOG.md)
### 安全加固
Pare 在 v0.3.0 版本引入了全面的安全改进：
| 安全机制 | 说明 |
|----------|------|
| **Git 参数注入防护** | 阻止 ref/branch 参数以 `-` 开头 |
| **构建命令注入防护** | 24 种已知构建工具的白名单验证 |
| **危险挂载阻止** | Docker 禁止挂载 `/`、`/etc`、`/var/run/docker.sock` |
| **输入大小限制** | Zod 类型系统对所有字符串/数组参数的大小限制 |
**新增安全工具函数：**
- `assertNoFlagInjection()` - 验证参数不包含危险标志
- `assertAllowedCommand()` - 验证命令在白名单内
资料来源：[packages/server-npm/CHANGELOG.md:15-25](https://github.com/Dave-London/Pare/blob/main/packages/server-npm/CHANGELOG.md)
### 跨平台兼容性
Pare 特别关注 Windows 平台的可靠性：
| 问题类型 | 解决方案 |
|----------|----------|
| Git format 字符串中的 `<>` | 为原生 `git.exe` 禁用 shell 模式 |
| cmd.exe 延迟扩展转义 | 特殊字符处理逻辑 |
| 测试超时不一致 | 对齐 CI 超时层级至 120s |
资料来源：[packages/shared/CHANGELOG.md:30-50](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
## 工具映射表
### pare-git 替代方案
使用 `pare-git <子命令>` 替代原始 `git` 命令：
| Git 操作 | Pare 工具 |
|----------|-----------|
| 查看状态 | `pare-git status` |
| 查看日志 | `pare-git log` |
| 查看差异 | `pare-git diff` |
| 分支管理 | `pare-git branch` |
| 查看提交 | `pare-git show` |
| 添加文件 | `pare-git add` |
| 提交更改 | `pare-git commit` |
| 推送代码 | `pare-git push` |
| 拉取代码 | `pare-git pull` |
| 切换分支 | `pare-git checkout` |
| 标签管理 | `pare-git tag` |
| 储藏更改 | `pare-git stash` |
| 查看远程 | `pare-git remote` |
| 逐行追溯 | `pare-git blame` |
| 工作树管理 | `pare-git worktree` |
资料来源：[rules/GEMINI.md:1-30](https://github.com/Dave-London/Pare/blob/main/rules/GEMINI.md)
### pare-github 替代方案
| GitHub 操作 | Pare 工具 |
|-------------|-----------|
| PR 查看/列表 | `pare-github pr-view` / `pr-list` |
| PR 创建/合并 | `pare-github pr-create` / `pr-merge` |
| PR 评论/审查 | `pare-github pr-comment` / `pr-review` |
| Issue 查看/列表 | `pare-github issue-view` / `issue-list` |
| Issue 创建/关闭 | `pare-github issue-create` / `issue-close` |
| CI 运行查看 | `pare-github run-view` / `run-list` |
| 发布管理 | `pare-github release-create` / `release-list` |
| 标签管理 | `pare-github label-list` / `label-create` |
资料来源：[rules/GEMINI.md:30-60](https://github.com/Dave-London/Pare/blob/main/rules/GEMINI.md)
## Python 工具详解
### 解释器解析顺序
`@paretools/python` 包按照以下顺序查找 Python 解释器：
```mermaid
graph TD
A[开始查找] --> B{显式指定 interpreter?}
B -->|是| C[使用指定解释器]
B -->|否| D{检测 .venv 目录?}
D -->|是| E[使用 .venv/bin/python]
D -->|否| F{检测 venv Scripts?}
F -->|是| G[使用 venv/Scripts/python]
F -->|否| H{python 命令存在?}
H -->|是| I[使用 python]
H -->|否| J[使用 python3]
J -->|失败| K[报告错误]
```
**支持的工具：**
| 工具 | 说明 |
|------|------|
| `pytest` | Python 测试框架 |
| `ruff-check` | Python 代码检查 |
| `ruff-format` | Python 代码格式化 |
资料来源：[packages/server-python/CHANGELOG.md:15-30](https://github.com/Dave-London/Pare/blob/main/packages/server-python/CHANGELOG.md)
### 已知限制
在 Windows 系统上，当 Python 工具安装为 Python 模块（如 `python -m pytest`）而非独立脚本时，工具调用可能失败。
资料来源：[社区问题 #891](https://github.com/Dave-London/Pare/issues/891)
## 配置与使用
### 环境变量配置
| 变量 | 说明 |
|------|------|
| `PARE_TOOLS` | 逗号分隔的工具列表，指定启用哪些工具 |
| `PARE_{SERVER}_TOOLS` | 特定服务器的启用的工具列表 |
| `NPM_TOKEN` | NPM 发布令牌（CI 用） |
### MCP 工具命名约定
所有工具遵循 `mcp__pare-{package}__{tool}` 命名规范：
```
mcp__pare-git__status
mcp__pare-github__pr-list
mcp__pare-python__pytest
```
资料来源：[packages/server-docker/CHANGELOG.md:1-20](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/CHANGELOG.md)
## 已知问题与限制
### 高优先级问题
| Issue | 问题描述 | 影响 |
|-------|----------|------|
| [#908](https://github.com/Dave-London/Pare/issues/908) | stash-list 所有条目都标记为 `stash@{0}` 而非递增索引 | 正确性问题 |
| [#907](https://github.com/Dave-London/Pare/issues/907) | pr-diff 的 `full=true` 和 `nameOnly=true` 参数被忽略 | 功能缺失 |
| [#906](https://github.com/Dave-London/Pare/issues/906) | worktree list 与 `--porcelain` 冲突导致失败 | 命令失败 |
| [#905](https://github.com/Dave-London/Pare/issues/905) | 空 stdout 导致多个解析器崩溃 | 稳定性问题 |
### 嵌套 Git Worktree 问题
当从嵌套 worktree 调用 `pare-git` 工具且未指定 `path` 参数时，工作目录解析可能错误。解决方法是显式传递 `path` 参数。
资料来源：[社区问题 #876](https://github.com/Dave-London/Pare/issues/876)
## 安全审计
Pare 已通过第三方安全审计：
| 审计时间 | 发现数量 | 已修复 | 接受风险 |
|----------|----------|--------|----------|
| 2026年2月12日 | 18 | 14 | 4 |
详细审计报告： [`docs/security/audit-2026-02-12.md`](https://github.com/Dave-London/Pare/blob/main/docs/security/audit-2026-02-12.md)
资料来源：[SECURITY.md:20-30](https://github.com/Dave-London/Pare/blob/main/SECURITY.md)
## 版本历史
| 版本 | 主要变更 |
|------|----------|
| 0.20.0 | Python 解释器解析改进、path 参数权威性澄清 |
| 0.8.0 | 100 工具里程碑、综合性能基准测试 |
| 0.7.0 | 新增 github/search/http/make 包 |
| 0.6.0 | 自动紧凑模式、安全加固 |
| 0.3.0 | 安全审计修复、305 测试用例 |
| 0.2.0 | 初始公开发布 |
## 相关链接
- **GitHub 仓库**: https://github.com/Dave-London/Pare
- **MCP 官方注册**: https://modelcontextprotocol.io/
- **Smithery 注册**: https://smithery.ai/protocol/@paretools
## 另请参阅
- [安全策略](SECURITY.md) - 漏洞报告流程和支持版本
- [Gemini CLI 规则](rules/GEMINI.md) - AI 代理使用指南
- [@paretools/shared 包文档](packages/shared/README.md) - 核心共享库
---
## Quickstart Guide
### 相关页面
相关主题：[Home - What is Pare?](#home), [Configuration Reference](#configuration), [Agent Integration Guide](#agent-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/init/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/init/src/index.ts)
- [packages/init/src/lib/presets.ts](https://github.com/Dave-London/Pare/blob/main/packages/init/src/lib/presets.ts)
- [docs/setup/claude-code.md](https://github.com/Dave-London/Pare/blob/main/docs/setup/claude-code.md)
- [docs/setup/cursor.md](https://github.com/Dave-London/Pare/blob/main/docs/setup/cursor.md)
- [packages/shared/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
- [SECURITY.md](https://github.com/Dave-London/Pare/blob/main/SECURITY.md)
# 快速入门指南
Pare 是一套基于 MCP（Model Context Protocol）的开发者工具集合，通过标准化的工具接口为 AI 编程助手提供对各类开发工具的访问能力。本指南将帮助您快速了解 Pare 的架构体系、安装配置方法以及核心使用模式。
## 项目概述
Pare 项目的核心目标是将常见的开发工具（如 Git、Docker、npm、Python 测试框架等）封装为 MCP 协议兼容的工具，使 AI 代理能够安全、可控地执行开发任务。根据 `packages/shared/CHANGELOG.md` 的记录，Pare 在 v0.7.0 版本已达到 **100 个工具、14 个包** 的规模，涵盖了代码管理、构建测试、容器操作等多个领域。
### 核心架构
Pare 采用**工具包（Tool Suite）**架构，每个工具包负责一个特定的开发领域。所有工具包统一发布在 `@paretools` npm 作用域下，确保版本一致性。以下是主要的工具包分类：
| 工具包 | 核心功能 | 工具数量 |
|--------|----------|----------|
| `@paretools/git` | Git 版本控制操作 | 15+ |
| `@paretools/docker` | Docker 容器管理 | 8+ |
| `@paretools/npm` | npm 包管理 | 6+ |
| `@paretools/python` | Python 测试与代码检查 | 5+ |
| `@paretools/github` | GitHub CLI 封装 | 8+ |
| `@paretools/search` | 代码搜索（ripgrep/fd） | 3+ |
| `@paretools/http` | HTTP 请求工具 | 4+ |
| `@paretools/build` | 多语言构建工具 | 可变 |
资料来源：[packages/shared/CHANGELOG.md:1-30]()
### MCP 协议集成
每个工具包都是一个独立的 MCP 服务器实现。根据 `packages/shared/CHANGELOG.md` 的 v0.3.0 更新记录，所有 9 个服务器均添加了 MCP `instructions` 字段，用于向 AI 客户端提供更好的工具使用指导。这一设计使得 AI 代理能够自动发现合适的工具并理解其正确的调用方式。
```mermaid
graph TD
A[AI 代理] -->|MCP 协议| B[MCP 客户端]
B --> C[@paretools/git]
B --> D[@paretools/docker]
B --> E[@paretools/npm]
B --> F[其他工具包...]
C --> G[git CLI]
D --> H[docker CLI]
E --> I[npm CLI]
```
## 安装配置
### 环境要求
Pare 工具包基于 Node.js 开发，需要确保目标机器满足以下条件：
- **Node.js**: v18.0.0 或更高版本
- **包管理器**: pnpm（推荐）、npm 或 yarn
- **特定工具**: 根据所使用的工具包，需要预装对应的 CLI 工具（如 git、docker、python3 等）
### 安装单个工具包
使用 pnpm 安装特定领域的工具包：
```bash
pnpm add @paretools/git
pnpm add @paretools/docker
pnpm add @paretools/npm
```
或安装所有工具包：
```bash
pnpm add @paretools/server-git @paretools/server-docker @paretools/server-npm @paretools/server-python
```
### MCP 服务器配置
每个工具包需要单独配置为 MCP 服务器。根据 `docs/setup/claude-code.md` 和 `docs/setup/cursor.md` 的说明，不同的 AI 客户端有不同的配置方式。
#### Claude Code 配置
在 Claude Code 中使用 `--mcp` 标志启动工具包：
```bash
npx @paretools/git --port 3000
npx @paretools/docker --port 3001
```
资料来源：[docs/setup/claude-code.md:1-20]()
#### Cursor 配置
Cursor IDE 支持通过 MCP 配置文件添加工具包：
```json
{
"mcpServers": {
"pare-git": {
"command": "npx",
"args": ["@paretools/git"]
},
"pare-docker": {
"command": "npx",
"args": ["@paretools/docker"]
}
}
}
```
资料来源：[docs/setup/cursor.md:1-25]()
## 初始化与预设配置
Pare 提供了初始化工具来简化项目配置。根据 `packages/init/src/index.ts` 的实现，初始化流程支持预设模板和自定义配置。
### 初始化流程
```typescript
// packages/init/src/index.ts 中的核心逻辑
interface InitOptions {
preset?: 'minimal' | 'full' | 'custom';
workspace: string;
tools?: string[];
}
```
初始化工具会根据用户选择的预设自动配置相应的工具包，并生成所需的配置文件。`packages/init/src/lib/presets.ts` 定义了预设模板的具体参数。
资料来源：[packages/init/src/index.ts:1-50]()
### 预设模板
| 预设名称 | 包含工具包 | 适用场景 |
|----------|-----------|----------|
| `minimal` | git, npm | 基础代码管理 |
| `full` | 所有工具包 | 完整开发环境 |
| `custom` | 用户指定 | 定制化需求 |
## 核心使用模式
### 路径参数
大多数 Pare 工具支持可选的 `path` 参数来指定工作目录。根据 `packages/shared/CHANGELOG.md` v0.20.0 的更新说明，当 `path` 参数省略时，仓库级别的工具将操作服务器当前的工作目录。
```typescript
// 推荐：显式指定路径
{ path: "/path/to/repo" }
// 可选：使用当前工作目录
{ /* path 未指定 */ }
```
资料来源：[packages/shared/CHANGELOG.md:1-10]()
### 紧凑输出模式
为减少 LLM 上下文中的 token 消耗，所有工具支持 `compact` 参数。紧凑模式会精简输出字段，移除冗余信息：
```json
// 标准模式
{ "file": "src/index.ts", "status": "modified", "additions": 10, "deletions": 5, "message": "..." }
// 紧凑模式
{ "file": "src/index.ts", "status": "M", "+": 10, "-": 5 }
```
### 延迟工具加载
当环境变量 `PARE_LAZY=true` 时，Pare 采用延迟工具注册策略。根据 `packages/server-db/CHANGELOG.md` 的说明，核心工具在启动时加载，而扩展工具则按需加载。这一机制通过新增的 `discover-tools` 元工具实现。
## 常见问题与已知限制
### 已知的社区问题
根据 GitHub Issues 记录，以下是用户经常遇到的问题：
| Issue | 描述 | 状态 |
|-------|------|------|
| #908 | `stash-list` 所有条目都显示为 `stash@{0}` 而非递增索引 | 开放 |
| #907 | `pr-diff` 的 `full` 和 `nameOnly` 参数未生效 | 开放 |
| #906 | `worktree list` 的 `listVerbose=true` 导致冲突错误 | 开放 |
| #876 | 嵌套 worktree 中 `path` 参数缺失导致工作目录解析错误 | 开放 |
| #891 | Windows 上 Python 工具作为模块安装时命令查找失败 | 开放 |
资料来源：[GitHub Issues 社区上下文]()
### 安全考虑
根据 `SECURITY.md` 的安全政策，Pare 项目已进行安全审计：
- **2026 年 2 月审计**：发现 18 个问题，其中 14 个已修复，4 个接受风险
- **参数注入防护**：Git 参数和构建命令使用白名单验证
- **报告流程**：请通过 GitHub 私有漏洞报告功能提交安全问题，切勿公开 issue
资料来源：[SECURITY.md:1-30]()
### Python 环境检测
根据 v0.20.0 的更新说明，Python 工具的解析器优先级为：
1. 显式指定的 `interpreter` 参数
2. 检测 `.venv/` 虚拟环境
3. 系统 `python` 命令
4. 回退到 `python3`
在 macOS 等没有 `python` 别名的系统上，确保安装 `python3` 并正确配置 PATH。
资料来源：[packages/shared/CHANGELOG.md:1-15]()
## 进阶配置
### 自定义超时设置
构建和安装操作默认使用较长的超时时间：
| 操作类型 | 默认超时 |
|----------|----------|
| Docker 构建 | 5 分钟 |
| npm 安装 | 5 分钟 |
| Cargo 构建 | 5 分钟 |
| 标准工具调用 | 30 秒 |
### MCP 服务器工厂
`@paretools/server-db` v0.11.1 引入了 `createServer()` 工厂函数，提取了通用的 MCP 服务器样板代码，简化自定义工具包的开发。
## 参见
- [Git 工具详细文档](./git-tools.md)
- [Docker 工具详细文档](./docker-tools.md)
- [Python 工具详细文档](./python-tools.md)
- [安全策略](../SECURITY.md)
- [发布说明](../CHANGELOG.md)
---
## Configuration Reference
### 相关页面
相关主题：[Quickstart Guide](#quickstart), [Home - What is Pare?](#home), [Agent Integration Guide](#agent-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/src/tool-filter.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/tool-filter.ts)
- [packages/shared/src/input-schemas.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/input-schemas.ts)
- [packages/shared/src/path-resolver.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/path-resolver.ts)
- [packages/server-git/src/tools/worktree.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/tools/worktree.ts)
- [packages/server-git/src/tools/stash-list.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/tools/stash-list.ts)
- [packages/server-github/src/tools/release-list.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/release-list.ts)
- [packages/server-python/src/python-test.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/python-test.ts)
- [packages/server-build/src/build-run.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-build/src/build-run.ts)
- [packages/shared/src/validation.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/validation.ts)
- [docs/configuration.md](https://github.com/Dave-London/Pare/blob/main/docs/configuration.md)
- [docs/manual-configuration.md](https://github.com/Dave-London/Pare/blob/main/docs/manual-configuration.md)
# Configuration Reference
## 概述
Pare 是一个 MCP（Model Context Protocol）工具集合，提供 28 个 npm 包、240 个工具，涵盖版本控制、语言运行时、构建系统等多个领域。本页面详细说明 Pare 工具的配置选项，包括环境变量、工具注册行为、路径解析规则、安全验证以及超时设置等核心配置机制。
Pare 的配置系统设计遵循以下原则：**声明式输入模式**（通过 Zod schema 定义）、**路径权威性**（`path` 参数优先于进程工作目录）以及**安全注入防护**（通过白名单和正则验证阻止恶意输入）。资料来源：[packages/shared/src/input-schemas.ts:1-50]()
## 核心配置架构
```mermaid
graph TD
A[MCP 客户端请求] --> B{环境变量检查}
B --> C[PARE_LAZY 设置]
B --> D[PATH 参数解析]
B --> E[安全验证层]
C -->|true| F[延迟工具注册]
C -->|false| G[全量工具注册]
D --> H[工作目录解析]
H --> I[Git 仓库根目录定位]
E --> J[flag 注入检测]
E --> K[命令白名单验证]
F --> L[discover-tools 元工具]
G --> M[全部工具就绪]
I --> N[repo-scoped 工具执行]
J -->|检测到注入| O[拒绝请求]
K -->|非白名单命令| O
K -->|白名单内| P[执行命令]
```
## 环境变量配置
### 延迟工具注册模式
`PARE_LAZY` 环境变量控制工具的注册策略。当设置为 `true` 时，核心工具在服务器启动时注册，而扩展工具则延迟注册，仅在通过 `discover-tools` 元工具发现时才加载。这种机制显著降低了 LLM 提示中工具架构的 token 消耗。资料来源：[packages/server-db/CHANGELOG.md:1-15]()
| 值 | 行为 | 适用场景 |
|---|------|----------|
| `true` | 核心工具立即注册，扩展工具按需加载 | 大型项目中仅使用部分工具时 |
| `false`（默认） | 全部工具立即注册 | 小型项目或需要快速启动时 |
```mermaid
graph LR
A[PARE_LAZY=true] --> B[启动时注册核心工具]
B --> C[LLM 调用 discover-tools]
C --> D[动态加载扩展工具]
D --> E[工具注册表更新]
F[PARE_LAZY=false] --> G[启动时注册全部工具]
G --> H[立即可用]
```
### 路径解析权威性
`path` 参数在所有仓库作用域工具中具有最高优先级。当省略 `path` 时，工具操作的是服务器的当前工作目录，而非调用进程的目录。资料来源：[packages/shared/CHANGELOG.md:1-10]()
此设计解决了从嵌套 git worktree 调用工具时的路径歧义问题。社区问题 #876 记录了相关 bug：当从嵌套 worktree 调用 `pare-git` 工具而未指定 `path` 时，工具会错误地解析到其他仓库根目录。
## 工具输入模式配置
### 标准输入字段
所有 Pare 工具共享一组标准输入字段，这些字段在 `input-schemas.ts` 中统一声明。资料来源：[packages/shared/src/input-schemas.ts:1-80]()
| 字段名 | 类型 | 说明 | 默认值 |
|--------|------|------|--------|
| `path` | `string` | 仓库或项目根目录路径 | `process.cwd()` |
| `compact` | `boolean` | 紧凑输出模式，减少 token 消耗 | `false` |
```typescript
// 路径输入模式示例
const repoPathInput = z
.string()
.max(INPUT_LIMITS.PATH_MAX)
.optional()
.describe("Working directory for the operation (default: server's cwd)");
// 紧凑输出模式示例
const compactInput = z
.boolean()
.optional()
.default(false)
.describe("Reduce token output by omitting non-essential fields");
```
### 语言特定配置
#### Python 解释器配置
Python 工具链支持多层解释器解析顺序和虚拟环境自动检测。资料来源：[packages/server-python/src/python-test.ts:1-100]()
解析优先级（从高到低）：
1. **显式指定**：`interpreter` 参数直接传入的路径
2. **虚拟环境检测**：查找 `.venv/`、`venv/`、`env/` 等标准目录
3. **PATH 查找**：依次尝试 `python`、`python3`
4. **模块模式回退**：使用 `python -m ` 调用
```mermaid
graph TD
A[Python 工具调用] --> B{interpreter 参数?}
B -->|是| C[使用指定解释器]
B -->|否| D{虚拟环境目录?}
D -->|.venv/| E[激活虚拟环境]
D -->|venv/| E
D -->|env/| E
D -->|无| F{python 命令?}
F -->|是| G[使用 python]
F -->|否| H{python3 命令?}
H -->|是| I[使用 python3]
H -->|否| J[尝试 python -m 模式]
C --> K[执行工具]
E --> K
G --> K
I --> K
J --> K
```
社区问题 #884 记录了 `pare-test` 在 macOS 上因缺少 `python` 命令而失败的问题，当前已通过自动回退到 `python3` 解决。
### 仓库作用域参数
#### Git 工具配置
Git 相关工具支持以下通用参数：资料来源：[packages/server-git/src/tools/worktree.ts:1-50]()
| 参数 | 类型 | 说明 |
|------|------|------|
| `path` | `string` | Git 仓库根目录 |
| `branch` | `string` | 目标分支名 |
| `ref` | `string` | 提交引用或标签 |
**Worktree 工具特殊参数：**
| 操作 | 参数 | 说明 |
|------|------|------|
| `list` | `listVerbose` | 显示详细信息的布尔值 |
| `list` | `porcelain` | 机器可读输出格式 |
> ⚠️ **已知问题 #906**：`listVerbose=true` 与 `porcelain` 不能同时使用，因为 `git worktree list --verbose` 和 `--porcelain` 选项互斥。当前实现默认传递 `--porcelain`，导致 verbose 模式失败。
#### GitHub 工具配置
GitHub 工具通过 `gh` CLI 封装，支持仓库上下文和分页控制。资料来源：[packages/server-github/src/tools/release-list.ts:1-60]()
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `repo` | `string` | 当前仓库 | `owner/repo` 格式 |
| `limit` | `number` | `30` | 最大返回数量 |
| `order` | `asc`/`desc` | `desc` | 排序方向 |
| `excludeDrafts` | `boolean` | `false` | 排除草稿版本 |
| `excludePreReleases` | `boolean` | `false` | 排除预发布版本 |
## 安全配置
### 命令注入防护
Pare 在所有用户输入点实施严格的注入防护。资料来源：[packages/shared/src/validation.ts:1-100]()
#### Ref/Branch 参数验证
所有 ref 和 branch 相关参数必须通过 `assertNoFlagInjection` 验证，拒绝以 `-` 开头的输入：
```typescript
export function assertNoFlagInjection(value: string, fieldName: string): void {
if (value.startsWith("-")) {
throw new Error(`${fieldName} cannot start with '-' to prevent flag injection`);
}
}
```
#### 构建命令白名单
构建工具使用白名单机制，仅允许预定义的 24 种构建工具。资料来源：[packages/server-build/src/build-run.ts:1-50]()
| 类别 | 允许的命令 |
|------|-----------|
| Node.js | `npm`, `pnpm`, `yarn`, `bun` |
| Python | `pip`, `poetry`, `uv` |
| Rust | `cargo` |
| Go | `go`, `gofmt` |
| Docker | `docker`, `docker compose` |
| 其他 | `make`, `just`, `gradle`, `mvn` 等 |
### Git 参数限制
| 参数类型 | 限制规则 |
|----------|----------|
| `ref` | 不能以 `-` 开头 |
| `branch` | 不能以 `-` 开头 |
| `path` | 最大长度 500 字符 |
| `repo` | 最大长度 200 字符 |
## 超时配置
### 默认超时设置
不同类型的操作有不同的默认超时时间。资料来源：[packages/server-build/CHANGELOG.md:1-30]()
| 操作类别 | 默认超时 | 示例命令 |
|----------|----------|----------|
| Docker 操作 | 5 分钟 | `docker build`, `docker run` |
| npm 操作 | 5 分钟 | `npm install`, `npm publish` |
| Cargo 操作 | 5 分钟 | `cargo build`, `cargo test` |
| Go 操作 | 5 分钟 | `go build`, `go mod` |
| Git 操作 | 30 秒 | `git status`, `git log` |
| 测试运行 | 60 秒 | `pytest`, `cargo test` |
### 自定义超时
集成测试时超时设置会对齐 Windows CI 的可靠性要求，确保跨平台行为一致。
## 紧凑输出模式
`compact` 参数用于减少 LLM 上下文中的 token 消耗，通过省略非必要字段实现。资料来源：[packages/shared/CHANGELOG.md:1-20]()
### 各包紧凑模式差异
| 包 | 紧凑模式行为 |
|----|--------------|
| `@paretools/npm` | 展平嵌套依赖关系，使用 `>` 分隔路径 |
| `@paretools/test` | 恢复失败消息字段用于调试 |
| `@paretools/docker` | 截断容器 ID 至 12 字符，优先相对时间戳 |
| `@paretools/lint` | 移除 column、fixable、endLine、endColumn 字段 |
### 令牌节省示例
```mermaid
graph LR
A[git status 原始输出] --> B[~120 tokens]
A --> C[结构化输出]
C --> D[~59 tokens]
B -.->|节省 50%| D
E[测试运行日志] --> F[~500+ tokens]
E --> G[紧凑 JSON]
G --> H[~40 tokens]
F -.->|节省 92%| H
```
## 常见配置问题
### 问题排查矩阵
| 问题现象 | 可能原因 | 解决方案 |
|----------|----------|----------|
| 工具返回空结果 | `gh` 输出空 stdout 而非 `[]` | 检查 `gh auth` 状态 |
| 路径解析错误 | 从嵌套 worktree 调用 | 显式传入 `path` 参数 |
| 命令找不到 | Python 模块未在 PATH | 使用 `python -m` 模式 |
| 超时失败 | 大型仓库操作 | 调整超时配置 |
| 注入错误 | 分支名以 `-` 开头 | 重命名分支 |
### Git 相关已知问题
| Issue | 状态 | 说明 |
|-------|------|------|
| #908 stash-list 索引 | Open | 所有 stash 条目显示为 `stash@{0}` |
| #907 pr-diff 参数 | Open | `full` 和 `nameOnly` 参数被忽略 |
| #906 worktree verbose | Open | `--verbose` 和 `--porcelain` 互斥 |
| #876 worktree 路径解析 | Open | 嵌套 worktree 路径解析错误 |
| #905 解析器空输出 | Open | 10+ 解析函数在空输出时崩溃 |
### Python 相关已知问题
| Issue | 状态 | 说明 |
|-------|------|------|
| #891 Windows 模块工具 | Open | pytest/ruff 作为模块调用失败 |
| #884 python3 回退 | Fixed | 自动检测 `python3` 替代 `python` |
## See Also
- [Architecture Overview](./Architecture-Overview) — Pare 系统架构概览
- [Tool Reference](./Tool-Reference) — 所有工具详细文档
- [Security Policy](../SECURITY) — 安全策略与漏洞报告
- [Changelog](../releases) — 版本变更记录
- [Python Interpreter Resolution](./Python-Interpreter-Resolution) — Python 解释器解析详解
---
## Git Tools
### 相关页面
相关主题：[GitHub Tools](#github-tools), [System Architecture](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server-git/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/index.ts)
- [packages/server-git/src/tools/stash-list.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/tools/stash-list.ts)
- [packages/server-git/src/tools/worktree.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/tools/worktree.ts)
- [packages/server-git/src/lib/git-runner.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/lib/git-runner.ts)
- [packages/server-git/src/schemas/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/schemas/index.ts)
- [docs/tool-schemas/git/status.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/git/status.md)
- [docs/tool-schemas/git/stash-list.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/git/stash-list.md)
- [docs/tool-schemas/git/worktree.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/git/worktree.md)
# Git Tools
## 概述
`@paretools/git` 是 Pare MCP 工具套件中专注于版本控制的服务器包，通过 MCP（Model Context Protocol）协议封装 Git 命令行工具，将传统的文本输出转换为结构化的 JSON 数据格式。
### 核心价值
| 特性 | 传统 Git CLI | Pare Git Tools |
|------|-------------|----------------|
| 输出格式 | 人类可读的原始文本 | 类型安全的结构化 JSON |
| Token 消耗 | 高（~118 tokens for status） | 低（~59 tokens for status，节省 50%） |
| 解析难度 | 需要正则表达式解析 | 直接访问字段 |
| 可维护性 | 输出格式可能随版本变化 | schema 验证保证稳定性 |
资料来源：[README.md](https://github.com/Dave-London/Pare/blob/main/README.md)
## 架构设计
### 组件结构
```mermaid
graph TD
A[MCP Client / AI Agent] --> B[server-git]
B --> C[Tool Handlers]
C --> D[git-runner]
D --> E[Git CLI]
E --> D
D --> F[Output Parser]
F --> G[structuredContent JSON]
G --> A
C --> C1[status]
C --> C2[stash-list]
C --> C3[worktree]
C --> C4[blame]
C --> Cn[...其他工具]
```
### 工具执行流程
```mermaid
sequenceDiagram
participant Client
participant Server as server-git
participant Runner as git-runner
participant Parser
participant Git
Client->>Server: MCP 工具调用 (e.g., status)
Server->>Runner: 执行 Git 命令
Runner->>Git: git status --porcelain
Git-->>Runner: 原始输出
Runner->>Parser: 解析输出
Parser-->>Runner: 结构化数据
Runner-->>Server: structuredContent
Server-->>Client: MCP 响应
```
资料来源：[packages/server-git/src/lib/git-runner.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/lib/git-runner.ts)
## 核心工具列表
`@paretools/git` 提供 55 个 Git 相关工具，覆盖版本控制的各个方面：
### 版本控制操作
| 工具名称 | 功能描述 | 主要参数 |
|---------|---------|---------|
| `status` | 查看工作区状态 | `path`, `mode` |
| `log` | 查看提交历史 | `path`, `maxCount`, `format` |
| `diff` | 查看文件差异 | `path`, `target`, `cached` |
| `branch` | 分支管理 | `action`, `path`, `name` |
| `show` | 查看提交/文件详情 | `target`, `path`, `format` |
### 暂存与提交
| 工具名称 | 功能描述 | 主要参数 |
|---------|---------|---------|
| `add` | 暂存文件 | `path`, `filePaths` |
| `commit` | 创建提交 | `path`, `message`, `all` |
| `restore` | 恢复文件 | `path`, `filePaths`, `source` |
### 远程操作
| 工具名称 | 功能描述 | 主要参数 |
|---------|---------|---------|
| `push` | 推送到远程 | `path`, `remote`, `branch` |
| `pull` | 拉取远程更新 | `path`, `remote`, `branch` |
| `fetch` | 获取远程引用 | `path`, `remote`, `prune` |
| `remote` | 远程仓库管理 | `action`, `path`, `name` |
### 工作流工具
| 工具名称 | 功能描述 | 主要参数 |
|---------|---------|---------|
| `stash` | 暂存工作区 | `action`, `path`, `message` |
| `stash-list` | 列出暂存项 | `path` |
| `worktree` | 工作树管理 | `action`, `path`, `branch` |
| `checkout` | 切换分支 | `path`, `branch`, `create` |
### 历史与追踪
| 工具名称 | 功能描述 | 主要参数 |
|---------|---------|---------|
| `blame` | 逐行追溯 | `path`, `filePath` |
| `reflog` | 查看引用日志 | `path`, `maxCount` |
| `tag` | 标签管理 | `action`, `path`, `name` |
### 高级操作
| 工具名称 | 功能描述 | 主要参数 |
|---------|---------|---------|
| `merge` | 合并分支 | `path`, `branch`, `noFf` |
| `rebase` | 变基操作 | `path`, `branch`, `interactive` |
| `cherry-pick` | 挑选提交 | `path`, `commits` |
| `bisect` | 二分查找 | `action`, `path`, `good`, `bad` |
资料来源：[packages/server-git/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/index.ts)
## 主要工具详解
### status 工具
查看 Git 工作区状态，返回结构化的分支和文件变更信息。
```typescript
// 调用示例
{
tool: "pare-git",
action: "status",
arguments: {
path: "/path/to/repo"
}
}
```
**输出结构：**
```json
{
"branch": "main",
"upstream": "origin/main",
"ahead": 2,
"behind": 0,
"staged": [
{ "file": "src/index.ts", "status": "modified" },
{ "file": "src/utils.ts", "status": "added" }
],
"modified": ["README.md"],
"deleted": [],
"untracked": ["temp.log"],
"conflicts": [],
"clean": false
}
```
资料来源：[docs/tool-schemas/git/status.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/git/status.md)
### stash-list 工具
列出当前仓库中的所有 stash 暂存项。
```typescript
// 调用示例
{
tool: "pare-git",
action: "stash-list",
arguments: {
path: "/path/to/repo"
}
}
```
**输出结构：**
```json
{
"stashes": [
{
"index": 0,
"reference": "stash@{0}",
"message": "WIP on main: abc1234 Commit message",
"author": {
"name": "Author Name",
"email": "author@example.com"
},
"date": "2026-06-15T10:30:00Z"
}
]
}
```
> ⚠️ **已知问题**：当前实现中所有 stash 条目的索引都报告为 `stash@{0}`，而非递增的 `stash@{0}`, `stash@{1}`, `stash@{2}` 等。详情请参阅 [Issue #908](https://github.com/Dave-London/Pare/issues/908)。
资料来源：[packages/server-git/src/tools/stash-list.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/tools/stash-list.ts)
### worktree 工具
管理 Git 工作树，支持列出、添加和移除工作树。
```typescript
// 列出所有工作树
{
tool: "pare-git",
action: "worktree",
arguments: {
action: "list",
path: "/path/to/repo"
}
}
// 添加新工作树
{
tool: "pare-git",
action: "worktree",
arguments: {
action: "add",
path: "/path/to/repo",
branch: "feature-branch",
directory: "/path/to/worktree"
}
}
```
**list 输出结构：**
```json
{
"worktrees": [
{
"path": "/path/to/main-worktree",
"branch": "main",
"head": "abc1234",
"isMain": true
},
{
"path": "/path/to/feature-worktree",
"branch": "feature-branch",
"head": "def5678",
"isMain": false
}
]
}
```
> ⚠️ **已知问题**：当 `listVerbose=true` 时，工作树列表工具会失败，错误信息为 `"options '--verbose' and '--porcelain' cannot be used together"`。这是因为内部实现同时传递了这两个互斥的选项。详情请参阅 [Issue #906](https://github.com/Dave-London/Pare/issues/906)。
资料来源：[packages/server-git/src/tools/worktree.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/tools/worktree.ts)
## 安全机制
### 参数注入防护
`@paretools/git` 实现了多层安全防护，防止恶意输入导致的命令注入攻击。
#### 分支/引用参数验证
所有接受分支名或引用作为参数的函数都会经过 `assertNoFlagInjection` 验证：
```typescript
// 阻止以 - 开头的参数，防止注入
assertNoFlagInjection(ref);
```
这可以防止以下攻击：
- `--version` → 被阻止
- `--help; rm -rf ~` → 分号后的内容被阻止
- `-u origin` → 被阻止
#### 构建命令白名单
对于涉及构建操作的工具（如 hooks），使用 `assertAllowedCommand` 进行白名单验证：
```typescript
// 仅允许已知的 24 种构建工具
const KNOWN_BUILD_TOOLS = [
'npm', 'pnpm', 'yarn', 'bun',
'cargo', 'go', 'gradle', 'maven',
'make', 'cmake', 'meson',
// ... 共 24 种
];
```
资料来源：[packages/server-git/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-git/CHANGELOG.md)
## 路径解析与工作目录
### 工作目录解析逻辑
当 Git 工具未指定 `path` 参数时，会在服务器的**启动目录**（launch directory）下解析仓库，而非调用者的当前工作目录。
```mermaid
graph LR
A[调用者进程] -->|cwd: /worktrees/feature|
B[server-git 进程] -->|启动目录: /projects/main|
B --> C[解析到 /projects/main]
A1[调用者进程] -->|cwd: /worktrees/feature|
D[显式 path 参数] -->|path: /worktrees/feature|
D --> E[解析到正确仓库]
```
> ⚠️ **重要提示**：从嵌套的 Git worktree 中调用工具时，如果不显式传递 `path` 参数，工具会在**父仓库**而非当前 worktree 中执行操作。这可能导致意外的行为。始终建议显式传递 `path` 参数以确保操作的正确性。
资料来源：[@paretools/shared@0.20.0](https://github.com/Dave-London/Pare/releases/tag/@paretools/shared%400.20.0)
### 正确的使用方式
```typescript
// ✅ 正确：显式指定路径
{
tool: "pare-git",
action: "status",
arguments: {
path: process.cwd() // 传递调用者的当前目录
}
}
// ⚠️ 注意：如果在嵌套 worktree 中调用且不传 path
// 工具将在父仓库根目录执行，而非当前 worktree
```
## 输出模式
### structuredContent 与 content 的区别
每个 Git 工具返回两个输出字段：
| 字段 | 用途 | 示例 |
|------|------|------|
| `content` | 人类可读的文本摘要 | `"On branch main, 2 files changed"` |
| `structuredContent` | 类型安全的 JSON | `{branch: "main", modified: [...]}` |
MCP 客户端可使用 `structuredContent` 直接获取类型化的数据，无需解析文本。
### 输出模式选项
某些工具支持不同的输出模式：
```typescript
{
tool: "pare-git",
action: "diff",
arguments: {
path: "/repo",
mode: "compact" // compact | full | minimal
}
}
```
- **compact**：最小化输出，仅包含关键信息
- **full**：完整输出，包含所有可用字段
- **minimal**：极简输出，用于高 Token 敏感场景
## 与其他工具的集成
### GitHub 工具协同
Git 工具与 `@paretools/github` 工具配合使用，可实现完整的代码协作工作流：
```mermaid
graph LR
A[pare-git] -->|branch, commit, push|
B[pare-github] -->|pr-create, pr-view|
C[CI/CD] -->|run-list, run-view|
A --> D[本地开发]
B --> E[PR 管理]
C --> F[持续集成]
```
### 工具映射规则
根据项目规则，应优先使用 Pare MCP 工具而非原始 CLI：
| 原始命令 | Pare MCP 工具 |
|---------|--------------|
| `git status` | `pare-git status` |
| `git stash list` | `pare-git stash-list` |
| `git worktree list` | `pare-git worktree` (action=list) |
| `git log --oneline` | `pare-git log` (format=oneline) |
资料来源：[rules/GEMINI.md](https://github.com/Dave-London/Pare/blob/main/rules/GEMINI.md)
## 已知问题与限制
### Issue #908: stash-list 索引问题
**问题描述**：`stash-list` 工具将所有 stash 条目标记为 `stash@{0}`，而非递增的索引。
**影响范围**：使用 stash 索引进行恢复或删除操作的场景。
**临时解决方案**：手动在 stash 消息中查找目标 stash 的实际位置。
### Issue #906: worktree listVerbose 冲突
**问题描述**：`worktree` 工具在 `list` 模式下设置 `listVerbose=true` 时崩溃。
**影响范围**：需要详细工作树信息的用户。
**临时解决方案**：使用默认模式（`listVerbose=false`）获取基本信息。
### Issue #876: 嵌套 Worktree 路径解析
**问题描述**：从嵌套 worktree 调用时，不传 `path` 参数会导致操作在错误的仓库中执行。
**影响范围**：在多仓库 monorepo 或嵌套 worktree 环境中使用 Git 工具。
**临时解决方案**：始终显式传递 `path` 参数为 `process.cwd()` 或目标仓库路径。
## Schema 定义
### 通用输入 Schema
```typescript
interface RepoPathInput {
path?: string; // 可选，默认使用服务器启动目录
}
interface StashListInput extends RepoPathInput {}
interface WorktreeListInput extends RepoPathInput {
listVerbose?: boolean; // 是否显示详细模式（当前有 bug）
}
```
### 输出 Schema
```typescript
interface GitStatusOutput {
branch: string;
upstream: string | null;
ahead: number;
behind: number;
staged: FileChange[];
modified: string[];
deleted: string[];
untracked: string[];
conflicts: string[];
clean: boolean;
}
interface StashListOutput {
stashes: StashEntry[];
}
interface StashEntry {
index: number;
reference: string;
message: string;
author: { name: string; email: string };
date: string;
}
```
资料来源：[packages/server-git/src/schemas/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/schemas/index.ts)
## 安装与配置
### 依赖要求
- Node.js >= 18.0.0
- Git CLI 已安装并在 PATH 中可用
- MCP 客户端（如 Claude Desktop、Cursor 等）
### 安装步骤
```bash
# 通过 npm 安装
npm install @paretools/git
# 或使用 pnpm
pnpm add @paretools/git
```
### MCP 配置示例
```json
{
"mcpServers": {
"pare-git": {
"command": "npx",
"args": ["-y", "@paretools/git"],
"env": {
"PARE_GIT_TIMEOUT": "30000"
}
}
}
}
```
## 参见
- [GitHub Tools](./github-tools.md) — GitHub CLI 封装工具
- [搜索工具](./search-tools.md) — ripgrep 和 fd 封装工具
- [测试工具](./test-tools.md) — 自动化测试运行器
- [构建工具](./build-tools.md) — 构建系统封装
- [Linting 工具](./lint-tools.md) — 代码质量检查工具
---
## GitHub Tools
### 相关页面
相关主题：[Git Tools](#git-tools), [System Architecture](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server-github/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/index.ts)
- [packages/server-github/src/tools/release-list.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/release-list.ts)
- [packages/server-github/src/tools/pr-diff.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/pr-diff.ts)
- [packages/server-github/src/tools/label-list.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/label-list.ts)
- [packages/server-github/src/lib/parsers.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/lib/parsers.ts)
- [packages/server-github/src/lib/gh-runner.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/lib/gh-runner.ts)
- [packages/server-github/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-github/CHANGELOG.md)
- [docs/tool-schemas/github/pr-diff.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/github/pr-diff.md)
# GitHub Tools
## 概述
GitHub Tools 是 Pare 项目中用于与 GitHub API 和 GitHub CLI (`gh`) 交互的 MCP（Model Context Protocol）服务器工具集。该工具包封装了 `gh` 命令行工具的 JSON 输出模式，将传统的文本输出转换为结构化的 JSON 数据格式，显著减少 AI 代理在处理 GitHub 数据时的 token 消耗。
根据项目文档，GitHub Tools 在标准文本模式下可能产生约 120 个 token，而使用 Pare 的结构化输出仅需约 59 个 token，节省约 50% 的 token 消耗。对于测试运行器和构建日志等更冗长的输出场景，节省比例可达到 80-92%。
资料来源：[README.md](https://github.com/Dave-London/Pare/blob/main/README.md)
## 架构设计
### 核心组件
GitHub Tools 采用分层架构设计，主要包含以下核心组件：
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| 服务器入口 | `src/index.ts` | MCP 服务器初始化、工具注册 |
| gh 运行器 | `src/lib/gh-runner.ts` | 执行 `gh` 命令、参数构建 |
| 解析器 | `src/lib/parsers.ts` | JSON 输出解析、错误处理 |
| 路径验证 | `src/lib/path-validation.ts` | 仓库路径验证 |
| 工具实现 | `src/tools/*.ts` | 各工具的具体业务逻辑 |
资料来源：[packages/server-github/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/index.ts)
### 数据流架构
```mermaid
graph TD
A[MCP 客户端请求] --> B[index.ts 入口]
B --> C[工具路由]
C --> D[gh-runner 命令执行]
D --> E[gh CLI 进程]
E --> F[JSON 输出解析]
F --> G[parsers.ts 验证]
G --> H[结构化结果返回]
H --> I[MCP 响应]
D -->|参数构建| J[path-validation.ts]
J -->|路径验证| D
```
### 工具注册机制
GitHub Tools 支持懒加载工具注册机制。当环境变量 `PARE_LAZY=true` 时，仅核心工具在启动时注册，扩展工具通过 `discover-tools` 元工具按需加载。这一机制可减少 AI 代理提示中的 token 消耗。
资料来源：[packages/server-db/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-db/CHANGELOG.md)
## 工具目录
### Pull Request 相关工具
| 工具名称 | 功能描述 | 核心参数 |
|----------|----------|----------|
| `pr-view` | 查看 PR 详情 | `number`, `repo`, `path` |
| `pr-list` | 列出仓库 PR | `state`, `limit`, `repo`, `path` |
| `pr-create` | 创建新 PR | `title`, `body`, `base`, `head`, `repo` |
| `pr-diff` | 获取 PR 差异 | `number`, `full`, `nameOnly`, `repo` |
#### pr-diff 工具参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `number` | number | 必填 | PR 编号 |
| `repo` | string | 当前仓库 | 仓库格式：`owner/repo` |
| `full` | boolean | false | 返回完整补丁内容 |
| `nameOnly` | boolean | false | 仅返回文件名列表 |
| `path` | string | 当前目录 | 仓库本地路径 |
资料来源：[docs/tool-schemas/github/pr-diff.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/github/pr-diff.md)
### Issue 相关工具
| 工具名称 | 功能描述 | 核心参数 |
|----------|----------|----------|
| `issue-view` | 查看 Issue 详情 | `number`, `repo`, `path` |
| `issue-list` | 列出仓库 Issue | `state`, `limit`, `labels`, `repo` |
| `issue-create` | 创建新 Issue | `title`, `body`, `labels`, `repo` |
#### issue-list 工具参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `state` | enum | open | 筛选状态：`open`, `closed`, `all` |
| `limit` | number | 30 | 最大返回数量 |
| `labels` | string | - | 标签筛选，逗号分隔 |
| `repo` | string | 当前仓库 | 仓库格式：`owner/repo` |
资料来源：[docs/tool-schemas/github/issue-list.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/github/issue-list.md)
### 其他工具
| 工具名称 | 功能描述 |
|----------|----------|
| `run-view` | 查看 GitHub Actions 运行详情 |
| `run-list` | 列出仓库 Actions 运行记录 |
| `repo-view` | 查看仓库信息 |
| `repo-clone` | 克隆仓库 |
| `discussion-list` | 列出 GitHub Discussions |
| `release-list` | 列出仓库 releases |
#### release-list 工具参数
```typescript
inputSchema: {
limit: z.coerce.number().optional().default(30),
repo: z.string().optional(),
excludeDrafts: z.boolean().optional(),
excludePreReleases: z.boolean().optional(),
order: z.enum(["asc", "desc"]).optional(),
path: repoPathInput,
compact: compactInput,
}
```
资料来源：[packages/server-github/src/tools/release-list.ts:15-36](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/release-list.ts)
## 配置与路径处理
### 路径参数权威性
`path` 参数是 GitHub 工具确定仓库位置的主要依据。当 `path` 参数被省略时，工具会使用服务器进程的当前工作目录（`process.cwd()`）。显式传递 `path` 参数可确保工具操作正确的仓库。
资料来源：[packages/shared/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
### 输入验证
GitHub Tools 对输入参数实施了严格的验证机制：
- **flag 注入防护**：阻止以 `-` 开头的 ref/branch 参数，防止命令注入攻击
- **路径验证**：使用 `assertNoFlagInjection` 和 `assertAllowedCommand` 验证工具函数
- **字符串长度限制**：使用 `INPUT_LIMITS.SHORT_STRING_MAX` 限制输入长度
```typescript
if (repo) assertNoFlagInjection(repo, "repo");
```
资料来源：[packages/server-github/src/tools/release-list.ts:34](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/release-list.ts)
## MCP 工具注解
GitHub Tools 集成了 MCP 工具注解，帮助 AI 代理理解工具行为和安全性特征：
| 注解类型 | 说明 |
|----------|------|
| `readOnlyHint` | 表示工具为只读操作，不会修改数据 |
| `destructiveHint` | 警告该操作可能具有破坏性 |
| `openWorldHint` | 指示工具是否操作外部资源（GitHub API） |
```typescript
annotations: { readOnlyHint: true, openWorldHint: true }
```
资料来源：[packages/server-github/src/tools/release-list.ts:11-12](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/release-list.ts)
## 已知问题与限制
### 空输出解析问题
**问题编号**：#905
当 `gh` 命令返回零结果时，部分解析器会因空 stdout 而崩溃。`gh` CLI 在匹配零结果时退出码为 0，但输出为空字符串（而非 `[]`）。直接执行 `JSON.parse(json)` 会导致 `Unexpected end of JSON input` 错误。
**受影响函数**：`parseLabelList` 及 10 个其他 parse* 函数
**状态**：问题已确认，需要修复
资料来源：[社区问题 #905](https://github.com/Dave-London/Pare/issues/905)
### pr-diff 参数不生效问题
**问题编号**：#907
`pr-diff` 工具忽略 `full=true` 和 `nameOnly=true` 参数，始终返回相同的文件级别统计数组（包含 file、status、additions、deletions），不返回补丁内容或纯文件名列表。
**复现命令**：
```bash
pr-diff number=904 full=true
# 返回 {"files":[{file, status, additions, deletions}]}（仅统计，无补丁）
```
**状态**：问题已确认
资料来源：[社区问题 #907](https://github.com/Dave-London/Pare/issues/907)
### 解析器空安全问题
解析器模块需要处理以下边界情况：
- 空 stdout 响应
- 非 JSON 格式的错误输出
- 部分 JSON 数据截断
- gh CLI 进程异常退出
```typescript
// 建议的防护模式
const raw = json.trim() ? JSON.parse(json) : fallbackValue;
```
资料来源：[packages/server-github/src/lib/parsers.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/lib/parsers.ts)
## 使用示例
### 基本使用场景
```typescript
// 查看 PR 详情
{
tool: "pare-github_pr-view",
params: {
number: 123,
repo: "owner/repo"
}
}
// 列出 Open 状态的 Issue
{
tool: "pare-github_issue-list",
params: {
state: "open",
limit: 50,
labels: "bug,help wanted"
}
}
```
### 与 Claude Code 集成
GitHub Tools 可通过 MCP 协议与 Claude Code 等 AI 代理集成，典型配置如下：
```json
{
"mcpServers": {
"pare-github": {
"command": "npx",
"args": ["-y", "@paretools/github"]
}
}
}
```
## 安全考量
### 命令注入防护
v0.3.0 版本引入了增强的安全机制：
- **Git 参数注入防护**：阻止 ref/branch 参数以 `-` 开头
- **构建命令白名单**：仅允许 24 种已知构建工具
- **新增验证工具**：`assertNoFlagInjection()` 和 `assertAllowedCommand()`
资料来源：[packages/server-github/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-github/CHANGELOG.md)
### 安全审计
项目于 2026 年 2 月进行了安全审计，发现 18 个问题，其中 14 个已修复，4 个被接受为风险。
资料来源：[SECURITY.md](https://github.com/Dave-London/Pare/blob/main/SECURITY.md)
## 错误处理
### gh-runner 错误处理
gh-runner 模块负责捕获和处理 `gh` CLI 执行过程中的错误：
```mermaid
graph TD
A[gh 命令执行] --> B{执行成功?}
B -->|是| C[返回 JSON 输出]
B -->|否| D[捕获 stderr]
D --> E{是预期错误?}
E -->|是| F[返回空数组/默认值]
E -->|否| G[抛出异常]
```
### 常见错误码
| 错误类型 | 可能原因 | 处理建议 |
|----------|----------|----------|
| `Command not found` | gh CLI 未安装 | 安装 GitHub CLI |
| `Authentication required` | 未登录 gh | 运行 `gh auth login` |
| `Could not resolve` | 仓库不存在 | 检查 repo 参数 |
| `Unexpected end of JSON` | gh 输出为空 | 使用空数组作为默认值 |
## 性能特性
### 超时配置
构建和安装操作（Docker、npm、cargo、go）的默认超时时间已延长至 5 分钟，以适应长时间运行的操作。
### Token 优化
GitHub Tools 通过以下方式减少 token 消耗：
- 结构化 JSON 输出替代纯文本
- 紧凑模式（`compact: true`）减少冗余字段
- 移除不必要的元数据（如 resolved URLs、fileCount、unpackedSize）
资料来源：[packages/shared/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
## 版本历史
| 版本 | 发布日期 | 主要变更 |
|------|----------|----------|
| 0.20.0 | 2026-05 | 依赖更新至 @paretools/shared@0.20.0 |
| 0.14.0 | - | 添加 MCP 工具注解 |
| 0.11.0 | - | 新增 repo-view、repo-clone、discussion-list |
| 0.10.2 | - | 添加 bugs URL |
| 0.3.0 | - | 安全改进、测试覆盖扩展 |
## 相关资源
- [Pare 主项目文档](https://github.com/Dave-London/Pare)
- [@paretools/shared 文档](../shared/README.md)
- [GitHub CLI 官方文档](https://cli.github.com/)
- [MCP 协议规范](https://modelcontextprotocol.io/)
## 参见
- [Git 工具](../git/README.md) - 本地 Git 操作
- [测试工具](../test/README.md) - 测试运行与报告
- [构建工具](../build/README.md) - 构建系统集成
---
## Python Tools
### 相关页面
相关主题：[Test Runner Tools](#test-tools), [System Architecture](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server-python/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/index.ts)
- [packages/server-python/src/lib/python-runner.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/lib/python-runner.ts)
- [packages/server-python/src/tools/pytest.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/tools/pytest.ts)
- [packages/server-python/src/tools/ruff.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/tools/ruff.ts)
- [packages/server-python/src/tools/pip.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/tools/pip.ts)
- [packages/shared/src/python.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/python.ts)
- [packages/server-python/README.md](https://github.com/Dave-London/Pare/blob/main/packages/server-python/README.md)
# Python Tools
## 概述
Python Tools 是 Pare 项目中专注于 Python 生态系统的 MCP 服务器包，提供了 8 个结构化、令牌高效的 Python 工具输出，专为 AI 代理设计。相比原始 CLI 输出，可减少高达 **65%** 的令牌消耗。
资料来源：[packages/server-python/README.md](https://github.com/Dave-London/Pare/blob/main/packages/server-python/README.md)
## 核心价值
| 特性 | 说明 |
| --- | --- |
| **令牌节省** | 相比原始 CLI 输出，减少 36-65% 令牌 |
| **结构化输出** | 返回类型安全的 JSON，而非字符串解析 |
| **自动回退** | 智能检测 Python 环境和虚拟环境 |
| **安全验证** | 防止命令注入攻击 |
资料来源：[packages/shared/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
## 工具列表
### 完整的 8 个 Python 工具
| 工具 | 描述 | 主要用途 |
| --- | --- | --- |
| `pytest` | 运行测试，返回结构化的通过/失败结果 | 测试执行 |
| `ruff-check` | Lint 诊断（文件、行号、代码、消息） | 代码质量检查 |
| `ruff-format` | 格式化代码，返回更改/未更改文件数 | 代码格式化 |
| `pip-install` | 安装包，返回已安装项摘要 | 依赖管理 |
| `pip-audit` | 已安装包的安全漏洞报告 | 安全审计 |
| `mypy` | 类型检查诊断（文件、行、严重性、消息） | 类型检查 |
| `uv-install` | 通过 uv 安装包，返回结构化摘要 | 快速依赖管理 |
| `uv-run` | 在 uv 管理环境中运行命令 | 隔离环境执行 |
资料来源：[packages/server-python/README.md](https://github.com/Dave-London/Pare/blob/main/packages/server-python/README.md)
## Python 解释器解析机制
### 解析顺序
Python Tools 实现了智能的 Python 解释器解析机制，支持多层回退策略：
```mermaid
graph TD
A[开始解析 Python 解释器] --> B{显式指定 interpreter?}
B -->|是| C[使用指定的解释器路径]
B -->|否| D{项目目录中有 .venv?}
D -->|是| E[使用 .venv/bin/python]
D -->|否| F{系统中是否有 python?}
F -->|是| G[使用 python 命令]
F -->|否| H[使用 python3 命令]
H --> I{python3 -m 工具可用?}
I -->|是| J[使用 python3 -m 工具名]
I -->|否| K[返回错误: 工具未找到]
C --> L[解析成功]
E --> L
G --> L
J --> L
K --> M[报告工具不可用]
```
资料来源：[packages/shared/src/python.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/python.ts)
### 虚拟环境检测
系统按以下优先级检测虚拟环境：
1. **显式指定** — 通过 `interpreter` 参数传入的完整路径
2. **项目 .venv** — 检测项目根目录下的 `.venv/` 目录
3. **系统 Python** — 使用 PATH 中的 `python` 命令
4. **python3 回退** — 当 `python` 不可用时使用 `python3`
5. **python -m 模式** — 作为最后手段，使用模块方式调用
资料来源：[packages/shared/CHANGELOG.md - v0.19.1](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
## 工具执行流程
### 统一执行架构
```mermaid
graph LR
A[MCP 客户端请求] --> B[Python Runner]
B --> C{工具类型}
C -->|标准命令| D[直接执行工具]
C -->|Python 模块| E[python -m 模块名]
D --> F[捕获 stdout/stderr]
E --> F
F --> G[JSON Schema 验证]
G --> H[结构化输出]
H --> I[MCP 响应]
```
## pytest 工具详解
### 输入参数
| 参数 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `path` | string | 否 | process.cwd() | 目标目录或 Python 文件路径 |
| `args` | string[] | 否 | [] | 传递给 pytest 的额外参数 |
| `interpreter` | string | 否 | 自动检测 | 显式指定 Python 解释器路径 |
| `compact` | boolean | 否 | true | 紧凑模式，减少输出令牌 |
资料来源：[packages/server-python/src/tools/pytest.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/tools/pytest.ts)
### 输出结构
```typescript
interface PytestResult {
exitCode: number;
passed: number;
failed: number;
skipped: number;
tests: Array<{
name: string;
status: "passed" | "failed" | "skipped";
duration?: number;
message?: string;
}>;
}
```
## ruff 工具详解
### ruff-check 输出结构
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `exitCode` | number | 退出代码（0=无错误） |
| `fileCount` | number | 检查的文件数 |
| `diagnostics` | Diagnostic[] | 诊断信息数组 |
| `summary` | object | 错误/警告/禁用统计 |
### Diagnostic 结构
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `file` | string | 文件路径 |
| `line` | number | 问题所在行 |
| `col` | number | 列号 |
| `code` | string | ruff 规则代码（如 F401） |
| `severity` | string | 严重程度 |
| `message` | string | 诊断消息 |
资料来源：[packages/server-python/src/tools/ruff.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/tools/ruff.ts)
## pip 工具详解
### pip-install 参数
| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `packages` | string[] | 是 | 要安装的包名列表 |
| `version` | string | 否 | 特定版本（默认安装最新） |
| `upgrade` | boolean | 否 | 是否升级已存在的包 |
| `dryRun` | boolean | 否 | 模拟运行，不实际安装 |
| `interpreter` | string | 否 | Python 解释器路径 |
资料来源：[packages/server-python/src/tools/pip.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/tools/pip.ts)
## 配置与使用
### MCP 客户端配置
```json
{
"mcpServers": {
"pare-python": {
"command": "npx",
"args": ["-y", "@paretools/python"]
}
}
}
```
### 环境变量
| 变量 | 描述 | 示例 |
| --- | --- | --- |
| `PARE_PYTHON_TOOLS` | 选择性启用特定工具 | `pytest,ruff-check` |
| `PARE_TOOLS` | 全局工具过滤 | `pytest` |
## 已知问题与解决方案
### Windows 用户站点 Scripts 问题
**问题描述**：在 Windows 系统上，当 pytest、ruff-check、ruff-format 作为 Python 模块安装到用户站点 Scripts 目录时，工具可能返回 "Command not found" 错误。
**影响版本**：所有版本（截至 v0.20.0）
**解决方案**：
1. 使用显式 `interpreter` 参数指定 Python 路径
2. 确保工具在系统 PATH 中可用
3. 考虑使用 `python -m pytest` 模式作为回退
资料来源：[GitHub Issue #891](https://github.com/Dave-London/Pare/issues/891)
### macOS python 命令缺失
**问题描述**：在 macOS 系统上，默认可能只有 `python3` 而没有 `python` 命令。
**解决方案**：系统已实现自动回退机制，会依次尝试：
1. `python` 命令
2. `python3` 命令
3. `python3 -m ` 模式
资料来源：[GitHub Issue #884](https://github.com/Dave-London/Pare/issues/884)
## 安全特性
### 命令注入防护
Python Tools 实现了多层安全验证：
1. **参数白名单** — 只允许已知的 pip/pytest/ruff 参数
2. **路径验证** — 防止路径遍历攻击
3. **输入限制** — Zod schema 对所有字符串/数组参数设置大小限制
4. **标志注入检测** — 使用 `assertNoFlagInjection` 验证用户输入
资料来源：[packages/server-python/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-python/src/index.ts)
## 版本历史
| 版本 | 日期 | 重要变更 |
| --- | --- | --- |
| 0.20.0 | 2026-05 | 文档化 Python 解释器解析顺序、虚拟环境检测、python -m 回退机制 |
| 0.19.1 | 2026-05 | 共享 Python 解释器解析逻辑、项目虚拟环境检测、python3 回退 |
| 0.8.0 | 2024 | 对齐 Windows CI 可靠性集成测试超时 |
| 0.7.0 | 2024 | 新增 ruff-format 工具 |
| 0.6.0 | 2024 | 自动紧凑模式、安全加固 |
资料来源：[packages/server-python/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-python/CHANGELOG.md)
## 相关链接
- [主项目仓库](https://github.com/Dave-London/Pare)
- [@paretools/python npm 包](https://www.npmjs.com/package/@paretools/python)
- [GitHub Issues - Python 相关](https://github.com/Dave-London/Pare/labels/area%3A%20python)
- [Pare 文档首页](../README.md)
---
## Docker Tools
### 相关页面
相关主题：[System Architecture](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server-docker/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/src/index.ts)
- [packages/server-docker/src/lib/docker-runner.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/src/lib/docker-runner.ts)
- [packages/server-docker/src/lib/validation.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/src/lib/validation.ts)
- [packages/server-docker/src/schemas/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/src/schemas/index.ts)
- [packages/server-docker/README.md](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/README.md)
- [packages/server-docker/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/CHANGELOG.md)
- [docs/tool-schemas/docker/build.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/docker/build.md)
- [docs/tool-schemas/docker/compose-up.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/docker/compose-up.md)
# Docker Tools
## 概述
Docker Tools 是 Pare 项目中专门用于封装 Docker CLI 操作的 MCP（Model Context Protocol）服务器包。其核心目标是为 AI 代理提供结构化、令牌高效的 Docker 输出，与原生 `docker` CLI 相比可节省高达 95% 的令牌使用量。
资料来源：[packages/server-docker/README.md](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/README.md)
该工具包属于 Pare 套件的一部分，后者是一个包含多个 MCP 服务器的集合，旨在为 AI 编程代理提供统一的开发工具接口。
## 工具列表
Docker Tools 当前提供 9 个核心工具，涵盖容器生命周期管理的完整流程：
| 工具 | 描述 | 用途场景 |
|------|------|----------|
| `ps` | 列出容器及其状态、端口和运行状态 | 查看当前运行的容器 |
| `build` | 构建镜像，返回镜像 ID、耗时和错误信息 | 构建自定义镜像 |
| `logs` | 以结构化行数组形式获取容器日志 | 调试容器问题 |
| `images` | 列出镜像及其仓库、标签和大小信息 | 管理本地镜像 |
| `run` | 从镜像运行容器，返回结构化结果 | 创建新容器 |
| `exec` | 在运行中的容器内执行命令 | 容器内操作 |
| `compose-up` | 启动 Docker Compose 服务，返回结构化状态 | 启动多容器应用 |
| `compose-down` | 停止 Docker Compose 服务，返回结构化状态 | 停止多容器应用 |
| `pull` | 从镜像仓库拉取镜像，返回摘要信息 | 获取最新镜像 |
资料来源：[packages/server-docker/README.md](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/README.md)
## 架构设计
### 组件结构
```mermaid
graph TD
A[MCP 客户端] --> B[@paretools/docker 服务器]
B --> C[docker-runner 执行器]
B --> D[validation 验证器]
B --> E[schemas 数据模式]
C --> F[docker CLI]
D --> G[安全检查]
E --> H[输出格式化]
H --> I[结构化 JSON 输出]
F --> J[原始输出]
G -->|阻止危险挂载| K[/, /etc, /var/run/docker.sock]
```
### 执行流程
```mermaid
sequenceDiagram
participant M as MCP 客户端
participant D as docker-runner
participant V as validation
participant S as schemas
participant CLI as docker CLI
M->>D: 调用 Docker 工具
D->>V: 验证输入参数
V->>V: 检查危险挂载卷
V->>V: 验证 flag 注入
V-->>D: 验证通过
D->>CLI: 执行 docker 命令
CLI-->>D: 返回原始输出
D->>S: 格式化输出
S-->>M: 结构化 JSON
```
## 核心功能详解
### 容器管理工具
#### ps（容器列表）
`ps` 工具用于列出 Docker 容器，返回包含状态、端口映射和运行状态的结构化数据。与原始 `docker ps` 输出相比，经过结构化处理后更易于 AI 代理解析和理解。
#### run（运行容器）
`run` 工具封装了 `docker run` 命令，提供结构化的执行结果。参数验证确保容器启动的安全性。
#### exec（容器内执行）
`exec` 工具允许在运行中的容器内执行命令，适用于调试和交互式操作场景。
### 镜像管理工具
#### build（构建镜像）
`build` 工具封装 `docker build` 操作，返回构建结果包括镜像 ID、构建耗时和任何错误信息。
资料来源：[docs/tool-schemas/docker/build.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/docker/build.md)
#### pull（拉取镜像）
`pull` 工具从镜像仓库拉取镜像并返回镜像摘要信息，支持版本管理和镜像更新。
#### images（镜像列表）
`images` 工具列出本地所有镜像，包含仓库名、标签和大小信息。
### 日志管理
#### logs（获取日志）
`logs` 工具以结构化行数组形式返回容器日志，便于 AI 代理进行日志分析和问题诊断。
### Docker Compose 支持
#### compose-up（启动服务）
`compose-up` 工具启动 Docker Compose 定义的服务集，返回每个服务的启动状态。
资料来源：[docs/tool-schemas/docker/compose-up.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/docker/compose-up.md)
#### compose-down（停止服务）
`compose-down` 工具停止 Docker Compose 服务，确保资源正确释放。
## 安全性设计
Docker Tools 在 v0.6.0 版本中引入了多项安全加固措施：
### 危险挂载卷阻止
系统会阻止以下危险路径的挂载：
| 路径 | 危险原因 |
|------|----------|
| `/` | 暴露整个文件系统 |
| `/etc` | 暴露系统配置 |
| `/var/run/docker.sock` | 可能导致容器逃逸 |
资料来源：[packages/server-docker/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/CHANGELOG.md)
### Flag 注入防护
所有 `args[]` 数组都会经过 Flag 注入验证，确保恶意命令无法通过参数注入方式执行。
### 错误消息清理
错误消息经过清理处理，防止路径信息泄露到输出中，保护系统内部结构不被暴露。
## 输出格式与令牌优化
### 自动紧凑模式
Docker Tools 支持自动紧凑模式（`compact` 参数，默认为 `true`）。当结构化 JSON 输出的令牌数超过原始 CLI 输出时，系统会自动应用紧凑投影，保留关键字段而丢弃详细信息的部分（如堆栈跟踪、详细诊断信息）。
### 令牌节省
通过结构化输出和自动压缩，Docker Tools 相比原生 `docker` CLI 可节省 **高达 95% 的令牌使用量**。
### 日志输出限制
为防止无界令牌消耗，`logs` 工具的完整模式输出设有上限。容器 ID 会被截断为 12 个字符，时间戳采用相对格式显示。
资料来源：[packages/server-docker/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/CHANGELOG.md)
## 配置与使用
### 快速开始
```bash
npx -y @paretools/docker
```
### MCP 客户端配置
在 Claude Desktop 或其他 MCP 客户端中添加以下配置：
```json
{
"mcpServers": {
"pare-docker": {
"command": "npx",
"args": ["-y", "@paretools/docker"]
}
}
}
```
### 工具调用示例
```typescript
// 构建镜像
{
tool: "mcp__pare-docker__build",
args: {
contextPath: "./docker",
tag: "myapp:latest"
}
}
// 运行容器
{
tool: "mcp__pare-docker__run",
args: {
image: "nginx:latest",
name: "web-server",
ports: [{ host: 8080, container: 80 }]
}
}
// 获取日志
{
tool: "mcp__pare-docker__logs",
args: {
container: "web-server",
tail: 100
}
}
```
## 版本历史
| 版本 | 主要变更 |
|------|----------|
| 0.20.0 | 更新依赖至 @paretools/shared@0.20.0 |
| 0.18.0 | 错误消息清理防止路径泄露 |
| 0.9.0 | 令牌优化：紧凑模式自动应用 |
| 0.8.5 | 新增 compose-logs、compose-build、docker-stats 工具 |
| 0.8.1 | 重塑品牌：mcpName 使用 pare-* 前缀 |
| 0.6.0 | 安全加固：阻止危险挂载、错误消息清理、超时延长至 60s |
资料来源：[packages/server-docker/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-docker/CHANGELOG.md)
## 已知问题与限制
### v0.18.1 之前版本
在 v0.18.1 之前的版本中，错误消息可能包含内部路径信息，存在信息泄露风险。**建议升级至 v0.18.1 或更高版本以获取安全修复。**
### 集成测试时序
某些 Windows CI 环境下的集成测试可能因时序问题失败，建议在本地开发时适当调整超时设置。
## 依赖关系
```mermaid
graph LR
A[@paretools/docker] --> B[@paretools/shared]
B --> C[zod]
B --> D[run]
A --> E[docker CLI]
```
Docker Tools 依赖以下核心包：
- `@paretools/shared@0.20.0` — 共享工具和验证逻辑
- `zod` — 输入参数验证
- `run` — 命令执行封装（超时从 30s 提升至 60s）
## 故障排除
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 容器启动失败 | 镜像不存在 | 先使用 `pull` 拉取镜像 |
| 挂载被拒绝 | 路径在危险列表中 | 检查 `/`, `/etc`, `/var/run/docker.sock` |
| 命令超时 | 操作耗时过长 | 增加超时设置或检查 Docker 守护进程状态 |
| 权限错误 | Docker 守护进程未运行 | 确保 Docker 服务正常运行 |
### 调试建议
1. **验证 Docker 状态**：运行 `docker ps` 确认守护进程可用
2. **检查镜像存在**：使用 `images` 工具列出本地镜像
3. **查看日志**：使用 `logs` 工具获取详细执行日志
4. **简化参数**：移除可选参数以隔离问题
## 参见
- [Git Tools](https://github.com/Dave-London/Pare/wiki/Git-Tools) — Git 版本控制工具集
- [Python Tools](https://github.com/Dave-London/Pare/wiki/Python-Tools) — Python 开发环境工具集
- [GitHub Tools](https://github.com/Dave-London/Pare/wiki/GitHub-Tools) — GitHub CLI 封装工具集
- [Search Tools](https://github.com/Dave-London/Pare/wiki/Search-Tools) — 代码搜索工具集
- [Pare 项目主页](https://github.com/Dave-London/Pare) — 完整项目文档
---
## Test Runner Tools
### 相关页面
相关主题：[Python Tools](#python-tools), [System Architecture](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server-test/src/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/index.ts)
- [packages/server-test/src/lib/detect.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/detect.ts)
- [packages/server-test/src/tools/run.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/tools/run.ts)
- [packages/server-test/src/lib/parsers/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/parsers/index.ts)
- [packages/server-test/src/lib/parsers/pytest.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/parsers/pytest.ts)
- [packages/server-test/src/lib/parsers/vitest.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/parsers/vitest.ts)
- [docs/tool-schemas/README.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/README.md)
# Test Runner Tools
## 概述
Test Runner Tools（Pare 测试运行工具）是 `@paretools/test` 包提供的核心功能集，封装了多种测试框架的统一接口。该工具包通过自动检测项目类型和配置，智能选择合适的测试运行器，并以结构化 JSON 格式返回结果，从而大幅减少 LLM 上下文中的令牌消耗。
核心设计目标包括：
- **自动检测**：无需手动指定测试框架，工具自动识别项目使用的测试技术栈
- **统一输出**：无论底层使用何种测试框架，输出格式保持一致
- **令牌优化**：相比原始测试输出，可节省 80-92% 的令牌消耗
- **跨平台兼容**：支持 macOS、Windows、Linux 等主流操作系统
资料来源：[packages/server-test/src/index.ts:1-50](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/index.ts)
---
## 架构设计
### 组件关系
```mermaid
graph TD
A[用户/Agent 调用 test-run] --> B[工具入口 index.ts]
B --> C[detect.ts 检测模块]
C --> D{检测结果}
D -->|Node.js 项目| E[Vitest Parser]
D -->|Python 项目| F[Pytest Parser]
D -->|未知类型| G[错误处理]
E --> H[统一输出格式化]
F --> H
G --> I[返回错误信息]
H --> J[结构化 JSON 结果]
```
### 核心模块
| 模块 | 文件路径 | 职责 |
|------|----------|------|
| 入口模块 | [index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/index.ts) | MCP 工具注册、请求路由 |
| 检测模块 | [detect.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/detect.ts) | 项目类型识别、解释器定位 |
| 运行模块 | [run.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/tools/run.ts) | 测试命令执行、超时控制 |
| 解析模块 | [parsers/index.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/parsers/index.ts) | 测试输出解析 |
---
## Python 解释器解析机制
### 解析顺序
v0.20.0 版本增强了 Python 解释器的自动检测机制。解析器按以下优先级顺序查找可用的 Python 解释器：
```mermaid
graph LR
A[显式指定解释器] --> B[虚拟环境检测]
B --> C[python 命令]
C --> D[python3 命令]
D --> E[python -m 模块调用]
E --> F[错误: 未找到解释器]
```
**完整解析顺序：**
1. **显式指定**：`interpreter` 参数传入的绝对路径
2. **虚拟环境**：`.venv/`、`venv/`、`env/` 等常见目录中的 Python
3. **系统 PATH**：`python` 命令（部分 macOS 系统需使用 `python3`）
4. **模块调用**：`python -m pytest` 作为后备方案
资料来源：[packages/server-test/src/lib/detect.ts:1-100](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/detect.ts)
### 虚拟环境自动检测
`detect.ts` 模块实现了智能虚拟环境检测逻辑。当项目目录存在虚拟环境时，系统会自动激活对应的解释器：
```typescript
// 虚拟环境检测逻辑（伪代码示例）
const VENV_PATTERNS = ['.venv', 'venv', 'env', '.virtualenv'];
const PYTHON_NAMES = ['python', 'python3', 'python3.11', 'python3.12'];
function detectPythonInterpreter(projectPath: string): string | null {
// 1. 检查显式指定
// 2. 扫描常见虚拟环境目录
for (const venv of VENV_PATTERNS) {
const venvPath = join(projectPath, venv);
for (const name of PYTHON_NAMES) {
const python = join(venvPath, 'bin', name);
if (exists(python)) return python;
}
}
// 3. 回退到 PATH 中的 python/python3
// 4. 尝试 python -m 模块调用
}
```
资料来源：[packages/server-test/src/lib/detect.ts:50-80](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/detect.ts)
### 已知限制
根据 Issue #884 报告，在以下场景中测试运行可能失败：
| 场景 | 原因 | 解决方案 |
|------|------|----------|
| macOS 默认配置 | 系统无 `python` 命令仅有 `python3` | 使用 `python3` 或创建符号链接 |
| Windows 用户脚本目录 | Python 模块不在 PATH 中 | 使用显式 `interpreter` 参数 |
| 全局安装项目 | 缺少虚拟环境目录 | 创建 `.venv/` 或指定解释器 |
资料来源：[GitHub Issue #884](https://github.com/Dave-London/Pare/issues/884)
---
## 支持的测试框架
### Vitest（Node.js 项目）
Vitest 是 Pare 默认支持的 Node.js 测试框架。解析器将原始测试输出转换为标准化结构：
```typescript
interface VitestResult {
success: boolean;
duration: number; // 毫秒
suites: number;
tests: number;
passed: number;
failed: number;
pending: number;
testResults: Array<{
file: string;
duration: number;
errors: Array<{message: string; location: string}>;
}>;
}
```
资料来源：[packages/server-test/src/lib/parsers/vitest.ts:1-60](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/parsers/vitest.ts)
### Pytest（Python 项目）
Pytest 解析器处理 Python 项目的测试输出：
```typescript
interface PytestResult {
success: boolean;
exitCode: number;
duration: number;
summary: {
passed: number;
failed: number;
skipped: number;
error: number;
};
failures: Array<{
test: string;
file: string;
line: number;
message: string;
}>;
}
```
资料来源：[packages/server-test/src/lib/parsers/pytest.ts:1-70](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/lib/parsers/pytest.ts)
---
## 工具 API
### 核心参数
| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `path` | string | 否 | 当前目录 | 测试运行的根目录 |
| `interpreter` | string | 否 | 自动检测 | Python 解释器路径（用于 pytest） |
| `mode` | string | 否 | `"compact"` | 输出模式：`compact` 或 `full` |
| `timeout` | number | 否 | 120000 | 超时时间（毫秒） |
资料来源：[packages/server-test/src/tools/run.ts:10-50](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/tools/run.ts)
### 输出模式
```mermaid
graph LR
A[测试运行] --> B{mode 参数}
B -->|compact| C[精简输出
仅关键信息]
B -->|full| D[完整输出
包含详细错误]
```
- **compact 模式**：返回通过/失败计数、测试文件列表、总耗时
- **full 模式**：包含每个测试用例的详细错误信息和堆栈跟踪
资料来源：[packages/server-test/src/index.ts:30-45](https://github.com/Dave-London/Pare/blob/main/packages/server-test/src/index.ts)
---
## 使用示例
### 基础调用
```json
{
"name": "mcp__pare-test__run",
"arguments": {
"path": "/project/root"
}
}
```
### 指定 Python 解释器
```json
{
"name": "mcp__pare-test__run",
"arguments": {
"path": "/python-project",
"interpreter": "/usr/local/bin/python3"
}
}
```
### 完整输出模式
```json
{
"name": "mcp__pare-test__run",
"arguments": {
"path": "/project/root",
"mode": "full",
"timeout": 180000
}
}
```
---
## 令牌优化效果
Test Runner Tools 的核心价值在于将冗长的测试输出转换为结构化 JSON：
```mermaid
graph LR
A[Vitest 原始输出
~500 tokens] --> B[解析器处理]
B --> C[结构化 JSON
~59 tokens]
C --> D[节省 ~88%]
E[Pytest 原始输出
~800 tokens] --> B
E --> F[结构化 JSON
~72 tokens]
F --> D
```
**典型节省比例：**
| 输出类型 | 原始大小 | 结构化大小 | 节省比例 |
|----------|----------|------------|----------|
| Git 状态 | ~120 tokens | ~59 tokens | ~50% |
| 测试结果 | ~500-800 tokens | ~60-80 tokens | 80-92% |
| 构建日志 | ~1000+ tokens | ~100-150 tokens | ~85% |
资料来源：[README.md](https://github.com/Dave-London/Pare/blob/main/README.md)
---
## 常见问题
### 1. Python 解释器未找到
**错误信息**：`Command not found: "pytest"`
**排查步骤**：
1. 确认 `python3` 是否在 PATH 中
2. 检查项目是否在虚拟环境中
3. 显式指定 `interpreter` 参数
```bash
# 验证 Python 路径
which python3
# 检查虚拟环境
ls -la .venv/bin/python 2>/dev/null || echo "无 .venv"
```
### 2. macOS 上 `python` 命令不可用
macOS 默认只有 `python3`，需要：
- 创建符号链接：`ln -s $(which python3) /usr/local/bin/python`
- 或在调用时使用 `python3`
- 或设置 `PYTHON` 环境变量指向 `python3`
### 3. Windows 用户脚本目录问题
Windows 上 Python 模块常安装在用户目录的 `Scripts` 文件夹中，需要显式指定完整路径：
```json
{
"arguments": {
"interpreter": "C:\\Users\\username\\AppData\\Local\\Programs\\Python\\Python311\\python.exe"
}
}
```
---
## 版本历史
| 版本 | 更新内容 |
|------|----------|
| 0.20.0 | 完善 Python 解释器解析顺序文档、虚拟环境检测、`python -m` 后备方案 |
| 0.7.0 | 新增 100 工具、14 包，扩展测试覆盖 |
| 0.3.0 | 安全加固、测试套件扩展至 305 测试 |
资料来源：[packages/server-test/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-test/CHANGELOG.md)
---
## 相关资源
- [@paretools/test 包主页](https://github.com/Dave-London/Pare/tree/main/packages/server-test)
- [工具模式文档](https://github.com/Dave-London/Pare/blob/main/docs/tool-schemas/README.md)
- [安全审计报告](./security/audit-2026-02-12.md)
- [GitHub Issues - 测试相关](https://github.com/Dave-London/Pare/issues?q=label%3Apare-test)
---
## System Architecture
### 相关页面
相关主题：[Home - What is Pare?](#home)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/shared/src/server.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/server.ts)
- [packages/shared/src/runner.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/runner.ts)
- [packages/shared/src/types.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/types.ts)
- [packages/shared/src/validation.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/validation.ts)
- [packages/shared/src/output.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/output.ts)
- [packages/shared/src/strict-input.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/strict-input.ts)
- [packages/server-git/src/tools/worktree.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/tools/worktree.ts)
- [packages/server-github/src/tools/release-list.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/release-list.ts)
- [packages/server-db/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-db/CHANGELOG.md)
- [SECURITY.md](https://github.com/Dave-London/Pare/blob/main/SECURITY.md)
# System Architecture
## 概述
Pare 是一个 MCP（Model Context Protocol）工具服务器集合，提供 100+ 工具，横跨 14 个 npm 包。这些工具通过统一的架构模式包装外部 CLI 工具（如 git、docker、npm、pytest 等），为 AI 代理提供标准化的编程接口。
系统架构的核心设计目标包括：
- **安全性**：通过参数白名单和注入检测防止命令注入攻击
- **可发现性**：为每个工具提供 MCP `instructions` 字段以提升 AI 代理的工具发现能力
- **可扩展性**：通过工厂模式和标准化接口支持新工具的快速添加
- **可靠性**：统一的错误处理、超时管理和输出格式化
资料来源：[SECURITY.md](https://github.com/Dave-London/Pare/blob/main/SECURITY.md)
## 核心组件架构
### 包结构概览
Pare 项目采用 monorepo 结构，主要包含以下类型的包：
| 包类型 | 示例 | 职责 |
|--------|------|------|
| **共享核心包** | `@paretools/shared` | 提供 server factory、runner、validation 等基础设施 |
| **服务器包** | `@paretools/git`、`@paretools/docker` | 实现特定领域的 MCP 工具服务器 |
| **工具集合包** | `@paretools/test`、`@paretools/lint` | 聚合相关工具的服务器 |
| **专用工具包** | `@paretools/github`、`@paretools/http` | 包装特定 CLI 工具的服务器 |
资料来源：[packages/server-db/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-db/CHANGELOG.md)
### 共享核心包架构
`@paretools/shared` 是整个生态系统的基石，提供所有服务器包共享的基础设施：
```mermaid
graph TD
subgraph "shared/src 核心模块"
A[server.ts] --> B[createServer 工厂函数]
C[runner.ts] --> D[工具执行器]
E[types.ts] --> F[统一类型定义]
G[validation.ts] --> H[安全验证工具]
I[output.ts] --> J[输出格式化]
K[strict-input.ts] --> L[输入验证]
end
B --> M[标准化 MCP Server]
D --> M
H --> D
J --> D
L --> D
M --> N[@paretools/* 各服务器包]
```
#### 核心模块职责
| 模块 | 文件 | 主要功能 |
|------|------|----------|
| **server.ts** | `createServer()` | 工厂函数，创建标准化 MCP 服务器实例 |
| **runner.ts** | `runTool()` | 工具执行器，处理超时、错误包装和输出格式化 |
| **validation.ts** | `assertNoFlagInjection()`、`assertAllowedCommand()` | 安全验证，防止命令注入 |
| **types.ts** | 工具输入/输出 schema | 统一的 Zod schema 定义 |
| **output.ts** | 响应格式化 | 统一工具输出的格式化逻辑 |
| **strict-input.ts** | 输入验证 | 对用户输入进行严格验证 |
资料来源：[packages/shared/src/server.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/server.ts)
## Server 工厂模式
### createServer 架构
v0.11.1 版本引入了 `createServer()` 工厂函数，将通用的 MCP server 样板代码提取到共享模块中：
```mermaid
graph LR
A[工具定义数组] --> B[createServer 配置]
B --> C{延迟加载模式?}
C -->|是 PARE_LAZY=true| D[仅注册核心工具]
C -->|否| E[注册所有工具]
D --> F[discover-tools 元工具]
F --> G[按需加载扩展工具]
E --> H[MCP Server 就绪]
G --> H
```
### 延迟加载机制
当环境变量 `PARE_LAZY=true` 时，系统采用懒加载策略：
- **启动时**：仅注册核心工具，减少 LLM 提示中的 token 消耗
- **运行时**：通过 `discover-tools` 元工具按需发现和加载扩展工具
- **优势**：显著降低 AI 代理获取工具列表时的 token 开销
资料来源：[packages/server-db/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-db/CHANGELOG.md)
## 安全架构
### 命令注入防护
v0.3.0 版本实现了全面的安全加固：
#### assertNoFlagInjection
验证用户提供的字符串参数不以 `-` 开头，防止攻击者通过注入标志来修改命令行为：
```typescript
// 伪代码示例
function assertNoFlagInjection(input: string, paramName: string): void {
if (input.startsWith('-')) {
throw new Error(`${paramName} cannot start with '-': ${input}`);
}
}
```
#### assertAllowedCommand
通过白名单机制限制允许执行的构建/安装工具：
```typescript
const ALLOWED_BUILD_TOOLS = [
'npm', 'pnpm', 'yarn', 'bun',
'docker', 'podman',
'cargo', 'go', 'gradle', 'maven',
// ... 共 24 种工具
];
function assertAllowedCommand(cmd: string): void {
if (!ALLOWED_BUILD_TOOLS.includes(cmd)) {
throw new Error(`Command not allowed: ${cmd}`);
}
}
```
资料来源：[packages/shared/src/validation.ts](https://github.com/Dave-London/Pare/blob/main/packages/shared/src/validation.ts)
### MCP 工具注解
所有工具都配备标准化的 MCP 注解，帮助 AI 代理理解工具行为：
| 注解 | 含义 |
|------|------|
| `readOnlyHint` | 工具仅读取数据，不修改状态 |
| `destructiveHint` | 工具执行破坏性操作 |
| `openWorldHint` | 工具与外部系统交互 |
## 工具执行流程
### 标准工具调用流程
```mermaid
sequenceDiagram
participant AI as AI Agent
participant MCP as MCP Client
participant Server as @paretools/* Server
participant Runner as runner.ts
participant Tool as 具体工具实现
participant CLI as 外部 CLI
AI->>MCP: 调用工具 (e.g., mcp__pare-git__status)
MCP->>Server: 转发请求
Server->>Runner: runTool(toolName, args)
Runner->>Tool: 执行工具逻辑
Tool->>CLI: 调用外部命令
CLI-->>Tool: 返回结果
Tool-->>Runner: 格式化输出
Runner-->>Server: 统一响应格式
Server-->>MCP: MCP Response
MCP-->>AI: 解析结果
```
### 输出格式化
`output.ts` 模块负责将各种 CLI 输出转换为统一格式：
```typescript
// 紧凑模式：减少 token 消耗
// 完整模式：保留所有详细信息
// 自定义模式：根据工具类型定制输出结构
```
## 工具包架构
### Git 工具集 (@paretools/git)
提供 20+ git 操作工具，包括：
| 工具 | 功能 |
|------|------|
| `status` | 查看仓库状态 |
| `branch` | 分支管理 |
| `commit` | 提交更改 |
| `push` | 推送到远程 |
| `worktree` | 工作树管理 |
| `stash` | 暂存管理 |
| `blame` | 责任追踪 |
#### 工作树列表问题
⚠️ **已知问题** (#906)：调用 `worktree` 工具时设置 `listVerbose=true` 会导致冲突错误：
```
fatal: options '--verbose' and '--porcelain' cannot be used together
```
这是因为实现同时传递了 `--porcelain` 和 `--verbose` 标志，而 git 不支持这种组合。
资料来源：[packages/server-git/src/tools/worktree.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-git/src/tools/worktree.ts)
#### 暂存列表索引问题
⚠️ **已知问题** (#908)：`stash-list` 工具将所有暂存条目都标记为 `stash@{0}`，而不是递增的 `stash@{0}`、`stash@{1}`、`stash@{2}` 等。
### GitHub 工具集 (@paretools/github)
封装 `gh` CLI，提供 GitHub API 操作：
| 工具 | 功能 |
|------|------|
| `pr-view` | 查看 PR 详情 |
| `pr-list` | 列出 PR |
| `pr-create` | 创建 PR |
| `pr-diff` | 获取 PR 差异 |
| `issue-view` | 查看 Issue |
| `issue-list` | 列出 Issue |
| `issue-create` | 创建 Issue |
| `run-view` | 查看 Action 运行 |
| `run-list` | 列出 Action 运行 |
| `release-list` | 列出发布版本 |
#### PR Diff 选项问题
⚠️ **已知问题** (#907)：`pr-diff` 工具忽略 `full=true` 和 `nameOnly=true` 参数，总是返回文件级统计信息，从不返回补丁内容或文件名列表。
### Python 工具集 (@paretools/python)
提供 Python 相关开发工具：
| 工具 | 功能 |
|------|------|
| `pytest` | 运行测试 |
| `ruff-check` | 代码检查 |
| `ruff-format` | 代码格式化 |
| `pip-list` | 列出已安装包 |
| `pip-show` | 显示包信息 |
#### Python 工具已知问题
⚠️ **Windows 模块问题** (#891)：在 Windows 上，当工具安装为 Python 模块而非 PATH 命令时，`pytest`、`ruff-check`、`ruff-format` 可能失败。
⚠️ **Python 解释器检测** (#884)：`pare-test` 在 macOS 等没有 `python` 命令但有 `python3` 的系统上可能失败。
## 路径解析机制
### path 参数权威性
v0.20.0 版本明确了 `path` 参数的权威性规则：
```mermaid
graph TD
A[工具调用] --> B{path 参数存在?}
B -->|是| C[使用提供的 path]
B -->|否| D{从嵌套 worktree 调用?}
D -->|是| E[可能使用错误的 cwd]
D -->|否| F[使用 server cwd]
C --> G[正确的仓库上下文]
E -.->|已知问题 #876| G
F --> G
```
⚠️ **已知问题** (#876)：从嵌套 git worktree 调用工具时，如果未提供显式 `path` 参数，工具可能使用错误的仓库根目录。
资料来源：[packages/server-github/src/tools/release-list.ts](https://github.com/Dave-London/Pare/blob/main/packages/server-github/src/tools/release-list.ts)
## 配置与环境变量
### 核心环境变量
| 变量 | 作用 | 默认值 |
|------|------|--------|
| `PARE_LAZY` | 启用延迟工具加载 | `false` |
| `path` | 指定工作目录 | `process.cwd()` |
### MCP 服务器配置
```typescript
// server.ts 中的标准化配置
interface ServerConfig {
name: string; // 服务器名称
version: string; // 版本号
tools: Tool[]; // 工具定义
instructions?: string; // AI 代理指导
mcpName?: string; // MCP 注册表名称
}
```
## 解析器安全
### 空输出处理
⚠️ **已知问题** (#905)：多个 `parse*` 函数在 CLI 返回空输出（而非 `[]`）时会崩溃。问题出现在：
- `gh label list --search ` 无匹配结果时返回空 stdout
- 10+ 个解析器使用 `JSON.parse(json)` 而未检查空输入
```typescript
// 不安全的模式
const raw = JSON.parse(json); // json 为空时会崩溃
// 安全的模式
const raw = json.trim() ? JSON.parse(json) : [];
```
## 超时配置
### 操作超时策略
| 操作类型 | 默认超时 | 示例命令 |
|----------|----------|----------|
| 标准命令 | 30 秒 | `git status` |
| Docker 操作 | 5 分钟 | `docker build` |
| npm 操作 | 5 分钟 | `npm install` |
| Cargo 操作 | 5 分钟 | `cargo build` |
| Go 操作 | 5 分钟 | `go get` |
资料来源：[packages/server-lint/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-lint/CHANGELOG.md)
## 版本演进
| 版本 | 里程碑 |
|------|--------|
| 0.2.0 | 初始发布，9 个 MCP 服务器 |
| 0.3.0 | 安全加固，305 测试，MCP 注解 |
| 0.7.0 | 100 工具，14 包，新增 GitHub/Search/Http/Make |
| 0.11.0 | 延迟工具加载 (`PARE_LAZY`) |
| 0.20.0 | 明确 `path` 参数权威性，Python 解释器改进 |
## 故障排除
### 常见问题
| 问题 | 原因 | 解决方案 |
|------|------|----------|
| `Command not found` | Windows 模块工具 | 使用 `python -m pytest` 形式 |
| 工具使用错误仓库 | 嵌套 worktree cwd 问题 | 显式传递 `path` 参数 |
| `Unexpected end of JSON` | 空 stdout 解析 | 检查 CLI 输出是否为空 |
| 超时错误 | 大型构建操作 | 使用 `timeout` 参数调整 |
### NPM Token 更新
⚠️ **维护提醒**：GitHub `NPM_TOKEN` secret 需要每 90 天续期。下次续期日期：2026-08-26。
资料来源：[GitHub Issue #866](https://github.com/Dave-London/Pare/issues/866)
## 相关文档
- [安全策略](../security/SECURITY.md) - 漏洞报告流程和支持版本
- [工具使用指南](../guides/using-tools.md) - 详细的工具调用示例
- [开发指南](../development/contributing.md) - 如何添加新工具
- [包列表](../packages/README.md) - 所有 @paretools 包索引
---
## Agent Integration Guide
### 相关页面
相关主题：[Quickstart Guide](#quickstart), [Configuration Reference](#configuration), [System Architecture](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/agent-integration.md](https://github.com/Dave-London/Pare/blob/main/docs/agent-integration.md)
- [rules/CLAUDE.md](https://github.com/Dave-London/Pare/blob/main/rules/CLAUDE.md)
- [rules/CONVENTIONS.md](https://github.com/Dave-London/Pare/blob/main/rules/CONVENTIONS.md)
- [hooks/README.md](https://github.com/Dave-London/Pare/blob/main/hooks/README.md)
- [hooks/pare-prefer-mcp.sh](https://github.com/Dave-London/Pare/blob/main/hooks/pare-prefer-mcp.sh)
- [docs/tool-response-examples.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-response-examples.md)
# Agent Integration Guide
本文档介绍如何将 Pare MCP 工具套件与 AI Agent 进行集成。Pare 提供了 100+ 工具，涵盖 Git、Docker、GitHub、Python、npm 等生态系统，旨在帮助 AI 编程代理高效完成开发任务。
## 概述
Pare 是一套面向 AI Agent 的 MCP（Model Context Protocol）工具集合，通过标准化接口为 AI 提供操作系统和开发工具的操作能力。该项目采用 monorepo 结构，包含 14 个 npm 包，涵盖语言运行时、构建系统、容器化工具和版本控制等核心开发场景。
资料来源：[packages/shared/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
## 架构设计
### MCP 服务器架构
Pare 采用独立 MCP 服务器设计，每个服务器专注于特定工具领域。这种模块化架构允许 AI Agent 按需加载工具，减少不必要的上下文开销。
```mermaid
graph TD
A[AI Agent] --> B[MCP Client]
B --> C[pare-git]
B --> D[pare-docker]
B --> E[pare-github]
B --> F[pare-python]
B --> G[pare-npm]
B --> H[pare-cargo]
B --> I[pare-http]
C --> J[Git Operations]
D --> K[Docker Operations]
E --> L[GitHub CLI Operations]
F --> M[Python/pip/pytest/ruff]
G --> N[npm/pnpm/yarn]
H --> O[Rust/Cargo]
I --> P[curl wrappers]
```
资料来源：[packages/server-git/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-git/CHANGELOG.md)
### 工具命名规范
所有 MCP 工具遵循统一命名约定：`mcp__pare-__`，其中：
| 组成部分 | 说明 | 示例 |
|---------|------|------|
| `mcp__` | MCP 协议前缀 | 固定前缀 |
| `pare-` | Pare 包标识 | 表示来自 Pare 项目 |
| `` | 工具领域 | git, docker, github, python, npm |
| `` | 操作类型 | list, run, create, view |
资料来源：[rules/CONVENTIONS.md](https://github.com/Dave-London/Pare/blob/main/rules/CONVENTIONS.md)
## 核心服务器包
### 包列表与工具数量
| 包名 | 功能领域 | 工具数量 | 主要工具 |
|------|---------|---------|---------|
| `@paretools/git` | Git 版本控制 | 15+ | branch, commit, diff, log, stash, worktree, tag, blame |
| `@paretools/docker` | 容器管理 | 12+ | run, build, ps, logs, inspect, compose-ps |
| `@paretools/github` | GitHub CLI | 8 | pr-view, pr-list, pr-create, issue-view, issue-list |
| `@paretools/python` | Python 生态 | 8+ | run, pip, pytest, ruff-check, ruff-format |
| `@paretools/npm` | npm/pnpm/yarn | 8+ | install, list, outdated, exec |
| `@paretools/cargo` | Rust 构建 | 6+ | build, test, check, run, clippy |
| `@paretools/http` | HTTP 客户端 | 4 | request, get, post, head |
| `@paretools/search` | 代码搜索 | 3 | search, find, count |
| `@paretools/make` | 构建工具 | 2 | run, list |
资料来源：[packages/shared/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/shared/CHANGELOG.md)
## 集成配置
### 环境变量
Pare 支持以下环境变量用于配置行为：
| 环境变量 | 说明 | 默认值 |
|---------|------|-------|
| `PARE_LAZY` | 启用懒加载工具注册 | `false` |
| `PARE_PATH` | 指定工作目录路径 | 当前目录 |
| `NPM_TOKEN` | npm 发布认证令牌 | - |
| `GITHUB_TOKEN` | GitHub API 认证 | 从 `gh auth` 获取 |
资料来源：[hooks/README.md](https://github.com/Dave-London/Pare/blob/main/hooks/README.md)
### 懒加载模式
启用 `PARE_LAZY=true` 后，服务器仅在启动时注册核心工具，扩展工具通过 `discover-tools` 元工具按需发现和加载。此功能可显著减少 LLM 提示词中的工具架构开销。
资料来源：[packages/server-db/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-db/CHANGELOG.md)
## 工具使用示例
### Git 工具
```javascript
// 列出所有分支
await mcp__pare-git__branch({ action: "list" });
// 创建新分支
await mcp__pare-git__branch({
action: "create",
name: "feature/new-feature",
path: "/path/to/repo"
});
// 查看提交历史
await mcp__pare-git__log({
action: "list",
maxCount: 10,
format: "oneline"
});
```
### Docker 工具
```javascript
// 运行容器
await mcp__pare-docker__run({
image: "node:20-alpine",
command: ["node", "-v"]
});
// 查看运行中的容器
await mcp__pare-docker__ps({ all: false });
// 查看容器日志
await mcp__pare-docker__logs({
container: "my-container-id",
tail: 100
});
```
### GitHub 工具
```javascript
// 列出 Pull Requests
await mcp__pare-github__pr_list({
state: "open",
limit: 10
});
// 查看 PR 详情
await mcp__pare-github__pr_view({
number: 123,
comments: true
});
// 创建 Issue
await mcp__pare-github__issue_create({
title: "Bug: 修复登录问题",
body: "详细的问题描述...",
labels: ["bug", "priority-high"]
});
```
资料来源：[docs/tool-response-examples.md](https://github.com/Dave-London/Pare/blob/main/docs/tool-response-examples.md)
## 安全特性
### 命令注入防护
Pare 在 v0.3.0 中引入了全面的安全加固措施：
- **Git 参数注入防护**：阻止以 `-` 开头的 ref/branch 参数
- **构建命令白名单**：仅允许 24 种已知的构建工具
- **验证工具**：`assertNoFlagInjection()` 和 `assertAllowedCommand()`
```javascript
// 不安全的输入会被阻止
await mcp__pare-git__branch({
action: "create",
name: "feature; rm -rf /" // 被阻止
});
```
资料来源：[packages/server-git/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-git/CHANGELOG.md)
### MCP 工具注解
所有工具都包含安全注解，帮助 AI 理解工具行为：
| 注解 | 说明 |
|------|------|
| `readOnlyHint` | 工具仅读取数据，不修改系统状态 |
| `destructiveHint` | 工具可能删除或覆盖数据 |
| `openWorldHint` | 工具与外部系统交互 |
资料来源：[packages/server-git/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-git/CHANGELOG.md)
## AI Agent 工作流
### 推荐工作流
```mermaid
graph LR
A[Agent Task] --> B[Discovery: 发现可用工具]
B --> C[Plan: 规划工具调用序列]
C --> D[Execute: 执行 MCP 调用]
D --> E[Parse: 解析工具响应]
E --> F[Validate: 验证结果正确性]
F --> G{完成?}
G -->|是| H[返回结果]
G -->|否| C
```
### Agent 提示词配置
Pare 为所有服务器添加了 `instructions` 字段，用于向 AI 客户端提供更精确的工具使用指导：
```javascript
{
name: "pare-git",
description: "Git operations for version control",
instructions: "Use git tools for version control tasks. Always specify path parameter when operating on specific repositories.",
tools: [...]
}
```
资料来源：[packages/server-git/CHANGELOG.md](https://github.com/Dave-London/Pare/blob/main/packages/server-git/CHANGELOG.md)
## 已知限制与问题
### 社区报告的问题
| 问题编号 | 描述 | 状态 |
|---------|------|------|
| [#908](https://github.com/Dave-London/Pare/issues/908) | stash-list 所有条目都显示为 `stash@{0}` | 待修复 |
| [#907](https://github.com/Dave-London/Pare/issues/907) | pr-diff 的 `full` 和 `nameOnly` 参数无效 | 待修复 |
| [#906](https://github.com/Dave-London/Pare/issues/906) | worktree listVerbose 导致参数冲突错误 | 待修复 |
| [#891](https://github.com/Dave-London/Pare/issues/891) | Windows 上 Python 模块工具命令未找到 | 待修复 |
| [#876](https://github.com/Dave-London/Pare/issues/876) | 嵌套 worktree 中 cwd 解析错误 | 待修复 |
资料来源：[社区议题](https://github.com/Dave-London/Pare/issues)
### 常见故障排查
#### Python 工具找不到命令
**问题**：Windows 上 `pytest`、`ruff` 等工具报错 "Command not found"。
**原因**：这些工具安装为 Python 模块而非可执行文件。
**解决方案**：使用 `python -m pytest` 或 `python -m ruff` 形式调用。
资料来源：[问题 #891](https://github.com/Dave-London/Pare/issues/891)
#### Git 工具操作错误的仓库
**问题**：从嵌套 worktree 调用 git 工具时，操作了错误的仓库。
**原因**：`path` 参数未指定时使用服务器默认工作目录。
**解决方案**：始终显式传递 `path` 参数指定目标仓库。
资料来源：[问题 #876](https://github.com/Dave-London/Pare/issues/876)
#### 空结果导致解析失败
**问题**：GitHub 工具在查询返回空结果时崩溃。
**原因**：部分 `gh` 命令在无结果时输出空 stdout 而非 `[]`。
**解决方案**：已在 `#903/#904` 中修复了 `parseLabelList`，其他解析器修复进行中。
资料来源：[问题 #905](https://github.com/Dave-London/Pare/issues/905)
## Claude Code 集成
### 钩子脚本
Pare 提供了 `pare-prefer-mcp.sh` 钩子脚本，用于在 Claude Code 中优先使用 MCP 工具而非 shell 命令：
```bash
#!/bin/bash
# hooks/pare-prefer-mcp.sh
# 当 MCP 服务器提供等效工具时，优先使用 MCP 版本
```
资料来源：[hooks/pare-prefer-mcp.sh](https://github.com/Dave-London/Pare/blob/main/hooks/pare-prefer-mcp.sh)
### 代理配置示例
```javascript
// claude_desktop_config.json
{
"mcpServers": {
"pare-git": {
"command": "npx",
"args": ["-y", "@paretools/git"]
},
"pare-github": {
"command": "npx",
"args": ["-y", "@paretools/github"]
},
"pare-python": {
"command": "npx",
"args": ["-y", "@paretools/python"]
}
}
}
```
## 扩展阅读
- [CLAUDE.md](https://github.com/Dave-London/Pare/blob/main/rules/CLAUDE.md) - Claude Code 项目规则
- [CONVENTIONS.md](https://github.com/Dave-London/Pare/blob/main/rules/CONVENTIONS.md) - 代码规范和约定
- [工具响应示例](https://github.com/Dave-London/Pare/blob/main/docs/tool-response-examples.md) - 各工具的响应格式说明
---
---
## Doramagic 踩坑日志
项目：dave-london/pare
摘要：发现 17 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Renew NPM_TOKEN before August 26, 2026。
## 1. 安全/权限坑 · 来源证据：Renew NPM_TOKEN before August 26, 2026
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Renew NPM_TOKEN before August 26, 2026
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_54641627ecff4e69be15ff36eed7a387 | https://github.com/Dave-London/Pare/issues/866 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 2. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `pare` 与安装入口 `@paretools/npm` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx @paretools/npm`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | repo=pare; install=@paretools/npm
## 3. 安装坑 · 来源证据：Nightly suite failure — 2026-05-28
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Nightly suite failure — 2026-05-28
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0055539ad4314d8bb47021f15b060fa3 | https://github.com/Dave-London/Pare/issues/895 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：[pare-test] Auto-detect venv + fall back to python3 when python is missing
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[pare-test] Auto-detect venv + fall back to python3 when python is missing
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_cb3a4a9195ef4c4982904c6db8b41dae | https://github.com/Dave-London/Pare/issues/884 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 配置坑 · 来源证据：github parsers: empty stdout on zero results crashes 10 more parse* functions (sibling of #903)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：github parsers: empty stdout on zero results crashes 10 more parse* functions (sibling of #903)
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5d1dd81a40084b6c80c536e93f03898b | https://github.com/Dave-London/Pare/issues/905 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 配置坑 · 来源证据：pare-git worktree: listVerbose=true on `list` fails — "options '--verbose' and '--porcelain' cannot be used together"
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：pare-git worktree: listVerbose=true on `list` fails — "options '--verbose' and '--porcelain' cannot be used together"
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c31213f7d41d4d82ad4e5295b99d4d76 | https://github.com/Dave-London/Pare/issues/906 | 来源类型 github_issue 暴露的待验证使用条件。
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | README/documentation is current enough for a first validation pass.
## 8. 运行坑 · 来源证据：pare-git stash-list: all entries reported with index stash@{0} instead of 0/1/2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：pare-git stash-list: all entries reported with index stash@{0} instead of 0/1/2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f9de30f482b84bf48362f1a69d7bbb56 | https://github.com/Dave-London/Pare/issues/908 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 运行坑 · 来源证据：pare-git: cwd resolution wrong when called from a nested worktree without explicit `path` arg
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：pare-git: cwd resolution wrong when called from a nested worktree without explicit `path` arg
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b89f4be8df5246d0b2423d0bb13d39e4 | https://github.com/Dave-London/Pare/issues/876 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. 运行坑 · 来源证据：pare-github pr-diff: full=true and nameOnly=true return only file stats, no patch/filenames
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：pare-github pr-diff: full=true and nameOnly=true return only file stats, no patch/filenames
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ae87316305eb458c8c50f896426ee6cd | https://github.com/Dave-London/Pare/issues/907 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. 运行坑 · 社区讨论暴露的待验证问题：Your self-hosted AI agents can match closed-source models - I ... - Reddit
- 严重度：medium
- 证据强度：source_linked
- 发现：Your self-hosted AI agents can match closed-source models - I ... - Reddit 24 Nov 2025 · Looking for open-source knowledge management tool ... Let's compare 5 Open-Source AI Agent Tools that everyone cannot stop talking about on Reddit.
- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。
- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。
- 证据：social_signal:reddit | ssig_4fefa11ceedb46d4af5e2ff44e7709e1 | https://www.reddit.com/r/selfhosted/comments/1p5q8f1/your_selfhosted_ai_agents_can_match_closedsource/ | Your self-hosted AI agents can match closed-source models - I ... - Reddit
## 12. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | last_activity_observed missing
## 13. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | no_demo; severity=medium
## 14. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | no_demo; severity=medium
## 15. 安全/权限坑 · 来源证据：pare-python tools (pytest/ruff-check/ruff-format) fail "Command not found" when tool is a python module / on user-site…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：pare-python tools (pytest/ruff-check/ruff-format) fail "Command not found" when tool is a python module / on user-site Scripts (Windows)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_716ce8621d7243deaf982ad0fc944772 | https://github.com/Dave-London/Pare/issues/891 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 16. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | issue_or_pr_quality=unknown
## 17. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.Dave-London/npm:0.8.0 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Dave-London%2Fnpm/versions/0.8.0 | release_recency=unknown