AICoreUtils

> Glama 92% | TDQS A 级 (均值 4.6) | 114 工具全部 A 级 | CI 全平台通过 | Production/Stable

🤖 MCP 目录已收录：Glama · ModelScope · awesome-mcp-servers

中文说明

AICoreUtils 是一个面向 LLM Agent 的 JSON 优先命令行工具包原型。它参考
GNU Coreutils 的常用命令，但不是完整的 GNU 兼容替代品。

项目目标是给机器调用方提供确定、低噪音、易解析的 CLI 接口：

- 默认输出 JSON
- 错误以 JSON 写入 stderr
- 退出码语义稳定
- 修改文件的命令支持 --dry-run
- 需要管道组合时显式使用 --raw

快速开始

pip install aicoreutils
aicoreutils schema --pretty
aicoreutils ls . --limit 20
aicoreutils rm build --recursive --dry-run

🤖 Claude Desktop / MCP 集成

一行配置，让 Claude 直接操作你的文件系统：

编辑 Claude Desktop 配置文件（详细说明 →）：

| 系统 | 配置文件 |
|------|---------|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |

{
  "mcpServers": {
    "aicoreutils": {
      "command": "python",
      "args": ["-m", "aicoreutils.mcp_server"]
    }
  }
}

重启 Claude Desktop，然后对它说：

> "列出项目里所有 Python 文件，统计代码行数"

Claude 自动调用 aicoreutils ls + aicoreutils wc，全程 JSON 交互。

更多集成方式：aicoreutils tool-list --format openai 输出 OpenAI Function Calling 格式，可直接用于任意 Agent 框架。
如需给调度器或审计系统保留风险标签，可追加 --include-risk。

> ⚠️ 安全提示：生产环境建议以最低权限运行。
>

> aicoreutils-mcp --profile readonly         # 推荐：只读工具

> aicoreutils-mcp --profile workspace-write  # 仅允许低风险 cwd 内写入

> 

🤖 AI IDE 集成

在 Cursor / Windsurf / Continue.dev 中直接使用 aicoreutils：AI IDE 集成指南 →

// ~/.cursor/mcp.json
{ "mcpServers": { "aicoreutils": { "command": "python", "args": ["-m", "aicoreutils.mcp_server"] } } }

🔗 更多：Claude Desktop 集成 | AI IDE 集成 | Agent 任务示例 | LangChain 包装器

运行测试

# 推荐主入口（pytest，含 Hypothesis property-based 测试和 GNU 对照测试）
uv run pytest tests/ -v --tb=short
Legacy 入口（unittest，部分运行器）
uv run python -m unittest discover -s tests -v

项目结构

.
|-- src/aicoreutils/        # Python 包源码
|-- docs/                   # 文档入口
|   |-- reference/          # 协议、命令面和安全生产契约
|   |-- guides/             # 使用指南
|   |-- architecture/       # 架构决策记录 (ADR) 和 AI 代理规则
|   |-- development/        # 测试和开发说明
|   |-- status/             # 当前项目状态（唯一权威来源）
|   |-- audits/             # 兼容性和质量审计
|   |-- analysis/           # 项目分析日志（历史归档）
|   -- reports/            # 测试报告等生成/归档文档
|-- tests/                  # 测试套件
|-- examples/               # 示例
|-- scripts/                # CI/审计/发布脚本
|-- .github/                # CI workflows 和 issue 模板
-- vendor/                 # 本地上游源码缓存

文档

- 文档索引
- 当前项目状态 ← 权威状态来源
- Agent 协议与示例
- 安全模型
- 中英文使用说明
- GNU Coreutils 兼容性审计
- 测试说明
- WSL 本地 CI
- 文档治理规则
- 事实传播矩阵

发布状态

当前实现：aicoreutils schema 中登记 114 个 CLI 命令（含 tool-list 等 Agent 元命令）。

重要限制：本项目是受 GNU Coreutils 启发的 Agent 友好子集，不是完整的
GNU Coreutils 克隆。

---

English

AICoreUtils is a JSON-first command-line toolkit prototype for LLM agents. It is
inspired by common GNU Coreutils commands, but it is not a complete GNU-compatible
replacement.

The goal is a deterministic, low-noise interface for machine callers:

- JSON output by default
- JSON errors on stderr
- Stable semantic exit codes
- --dry-run for mutation commands
- Explicit --raw output for pipeline composition

Quick Start

pip install aicoreutils
aicoreutils schema --pretty
aicoreutils ls . --limit 20
aicoreutils rm build --recursive --dry-run

🤖 Claude Desktop / MCP Integration

One config line to let Claude operate your filesystem:

Edit Claude Desktop config (full guide →):

| OS | Config File |
|----|------------|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |

{
  "mcpServers": {
    "aicoreutils": {
      "command": "python",
      "args": ["-m", "aicoreutils.mcp_server"]
    }
  }
}

Restart Claude Desktop, then ask:

> "List all Python files in the project and count lines of code"

Claude calls aicoreutils ls + aicoreutils wc automatically.

For other frameworks: aicoreutils tool-list --format openai outputs OpenAI Function Calling format directly.
Add --include-risk when an orchestrator or audit system needs machine-readable risk metadata.

> ⚠️ Security: Run with least privilege in production.
>

> aicoreutils-mcp --profile readonly         # Recommended: read-only tools

> aicoreutils-mcp --profile workspace-write  # Low-risk cwd-local writes only

> 

Run tests

# Recommended primary entry (pytest, includes Hypothesis property-based and GNU differential tests)
uv run pytest tests/ -v --tb=short
Legacy entry (unittest, partial runner)
uv run python -m unittest discover -s tests -v

Project Layout

.
|-- src/aicoreutils/        # Python package
|-- docs/                   # documentation index
|   |-- reference/          # protocol, command-surface and security contracts
|   |-- guides/             # usage guides
|   |-- architecture/       # ADRs and AI agent governance rules
|   |-- development/        # testing and development notes
|   |-- status/             # current project status (single authoritative source)
|   |-- audits/             # compatibility and quality audits
|   |-- analysis/           # project analysis logs (historical archive)
|   -- reports/            # test reports and archived generated docs
|-- tests/                  # test suite
|-- examples/               # examples
|-- scripts/                # CI/audit/release scripts
|-- .github/                # CI workflows and issue templates
-- vendor/                 # local upstream source cache

Documentation

- Documentation index
- Current project status ← authoritative status source
- Agent protocol and examples
- Security model
- Chinese/English user guide
- GNU Coreutils compatibility audit
- Testing guide
- WSL local CI
- Documentation governance rules
- Fact propagation matrix

Release Status

Current implementation: 114 CLI commands in aicoreutils schema (including agent-native meta-commands like tool-list).

Important limitation: this project is an agent-friendly subset inspired by GNU
Coreutils, not a full GNU Coreutils clone.

稳定性和 SemVer

aicoreutils 从 v1.0.0 起采用语义化版本控制，承诺如下：

- Patch (1.0.x)：修复 bug、改进错误消息、补充文档。JSON 输出结构不变。
- Minor (1.x.0)：新增命令、新增参数。已有命令的 JSON 输出结构保持向后兼容。
- Major (x.0.0)：破坏性变更 — JSON schema 变化、命令重命名、MCP tool schema 变化。

⚠️ Stability note: JSON envelope (ok, result, error, command, version), MCP tool schema, and semantic exit codes are stable. Production use: pin the version (pip install aicoreutils==1.2.3). v1.2.3 LTS — critical bug and security fixes backported for at least 12 months. CLI internal argument parsing may evolve across minor versions. See Stability & SemVer.