AICoreUtils

中文说明

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 配置文件（详细说明 →）：

{
  "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 框架。

运行测试

# 推荐主入口（pytest，含 Hypothesis property-based 测试和 GNU 对照测试）
python -m pytest project/tests/ -v --tb=short

# Legacy 入口（unittest，部分运行器）
python -m unittest discover -s project/tests -v

项目结构

.
|-- src/aicoreutils/        # Python 包源码
|-- .github/               # CI、Copilot 指令和开发脚本
|-- pyproject.toml         # 包元数据和构建配置
|-- README.md              # 项目入口
`-- project/               # 项目附属资源
    |-- tests/             # 子进程级行为测试
    |-- docs/              # 文档入口和分类文档目录
    |   |-- reference/     # 协议、命令面和安全生产契约
    |   |-- guides/        # 使用指南
    |   |-- audits/        # 兼容性和质量审计
    |   |-- development/   # 测试和开发说明
    |   |-- status/        # 当前项目状态（唯一权威来源）
    |   |-- analysis/      # 项目分析日志（历史归档）
    |   |-- agent-guides/  # AI 辅助编码与文档治理规则
    |   `-- reports/       # 测试报告等生成/归档文档
    |-- vendor/gnu-coreutils/  # 本地上游源码缓存，默认被 Git 忽略
    `-- AGENTS.md          # 仓库级 Agent 入口规则

文档

• 文档索引
• 当前项目状态 ← 权威状态来源
• 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 →):

{
  "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.

Run tests

# Recommended primary entry (pytest, includes Hypothesis property-based and GNU differential tests)
python -m pytest project/tests/ -v --tb=short

# Legacy entry (unittest, partial runner)
python -m unittest discover -s project/tests -v

Project Layout

.
|-- src/aicoreutils/        # Python package
|-- .github/               # CI, Copilot instructions and development scripts
|-- pyproject.toml         # package metadata and build config
|-- README.md              # project entry point
`-- project/               # project collateral
    |-- tests/             # subprocess-level behavior tests
    |-- docs/              # documentation index and categorized docs
    |   |-- reference/     # protocol, command-surface and security contracts
    |   |-- guides/        # usage guides
    |   |-- audits/        # compatibility and quality audits
    |   |-- development/   # testing and development notes
    |   |-- status/        # current project status (single authoritative source)
    |   |-- analysis/      # project analysis logs (historical archive)
    |   |-- agent-guides/  # AI coding assistant and docs governance rules
    |   `-- reports/       # test reports and archived generated docs
    |-- vendor/gnu-coreutils/  # local upstream source cache, ignored by Git by default
    `-- AGENTS.md          # repository-level agent entry rules

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.