内容
<p align="center">
<img src=".github/og.png" alt="AIShell — 面向 AI 开发的直接操作系统上下文" width="100%">
</p>
# AIShell
[](https://github.com/kitepon-rgb/aishell/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@quolu/aishell)
> 一个 macOS 原生 MCP 运行时，为 AI 开发提供新鲜的工作空间状态、有限的上下文和保留的执行证据，而无需将每个操作折叠成一个 shell 字符串。
[日本語](README.ja.md)
由 [Quo](https://x.com/QLyun35332) 在 [kitepon.dev](https://kitepon.dev/en) 构建和维护。
**所有权边界：** 该仓库拥有 macOS Apple Silicon 操作系统上下文运行时。跨产品安装和集成合同由 [dotagents](https://github.com/kitepon-rgb/dotagents) 处理，这是 kitepon.dev 产品的内部开发工具链。
AIShell 拥有模型以下的面向操作系统的状态：允许的根、文件标识、文件系统协调、直接启动的进程、完整的日志和保留的工件。AI 主机负责推理、线程、压缩、子代理和一般终端工作。
## 30 秒试用
需要运行 macOS 15 或更高版本的 Apple Silicon Mac。
```sh
npm install -g @quolu/aishell
aishell-open
codex mcp add aishell -- /opt/homebrew/bin/aishell-mcp
```
在管理器应用程序中，添加 AI 可以访问的文件夹。启动新的 Codex 任务并尝试：
```text
使用 workspace_snapshot 作为初始工作空间上下文。使用 run_check 运行关注的测试，如果摘要省略证据，则使用 artifact_read 读取保留的输出。
```
默认配置文件公开了五个高密度开发工具和两个始终可用的恢复控件：
| 工具 | 目的 |
|---|---|
| `workspace_snapshot` | 有限的初始工作空间预览、协调的更改增量、Git 状态和主要上下文 |
| `read_context` | 具有 SHA-256 标识和续期的预算多文件读取 |
| `search_context` | 来自直接启动的 `rg` 工作程序的预算词汇上下文；扩展功能还提供基于光标的语义定义/引用/符号查询，无需词汇回退 |
| `run_check` | 直接进程执行、主要诊断和完整的 stdout/stderr 工件 |
| `artifact_read` | 从保留的工件中进行范围、尾部和模式中心读取；扩展功能还搜索和比较最终的托管运行工件 |
| `runtime_status` | 允许根、暂停、工作树和下一个操作状态，包括暂停或未配置时 |
| `runtime_open_manager` | 打开管理器应用程序以添加根或恢复 AI 操作 |
在 MCP 服务器进程上设置 `AISHELL_CAPABILITY_SET=expanded-v1` 以选择加入候选界面。它公开了九个高密度开发工具和两个恢复控件。新增的工具是 `run_observe`、`workspace_wait`、`change_impact` 和 `apply_change_set`；现有工具获得了封闭的托管运行、工件查询、语义搜索、项目配置文件和 Git 分支/工作树模式。跨运行工件操作需要显式项目路径，并拒绝实时、过期、遗产未绑定或不同项目证据，而不是静默回退到部分日志。
对于 Codex，请显式注册扩展界面：
```sh
codex mcp add aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- /opt/homebrew/bin/aishell-mcp
```
未知或空的 `AISHELL_CAPABILITY_SET` 和 `AISHELL_TOOL_PROFILE` 值会以类型错误启动；它们永远不会回退到另一个配置文件。
`AISHELL_TOOL_PROFILE=factory` 是一个单独的、具有一个工具的配置文件，用于工厂报告员而不是开发工作。它仅公开 `factory_diagnostics`，这是一个无路径和活动报告的原生就绪报告。
## 为什么选择 AIShell
典型的无状态集成反复要求模型重新发现工作空间状态和解释命令输出。AIShell 将有状态的、面向操作系统的部分保留在模型以下，以便后续可以请求增量和主要证据，而不是重新扫描所有内容。
| 问题 | AIShell | 典型的 shell-first 集成 |
|---|---|---|
| 工作空间状态 | 文件标识加上文件系统观察和协调 | 重新运行命令并从文本中重建状态 |
| 上下文 | 有限的、基于光标的结构化结果 | 无限或手动截断的 stdout |
| 执行 | 可执行 URL、参数、工作目录和生命周期保持独立 | shell 评估一个命令字符串 |
| 证据 | 完整的 stdout/stderr 在过期句柄后保留 | 证据通常在响应被截断时消失 |
| 范围 | 人工管理的允许根和显式停止状态 | 取决于周围的 shell 和主机策略 |
AIShell 不是一个沙盒，它不使任意代码执行安全。其进程轨道存在以保留类型化执行和可观察的生命周期——而不是停止重命名的二进制文件或允许的工作程序启动的子进程。
## 架构
```mermaid
flowchart LR
Host[AI 主机<br/>推理 · 线程 · 压缩] --> MCP[AIShellMCP<br/>MCP 2025-11-25]
MCP --> Core[AIShellCore]
Core --> State[允许根 · 文件标识<br/>FSEvents + 协调]
Core --> Process[直接进程生命周期<br/>stdout · stderr · 超时]
Core --> Evidence[保留证据<br/>工件 · 新鲜度]
Process --> Workers[git · rg · 编译器 · 测试]
State --> macOS[macOS APIs]
Evidence --> Host
```
`AIShellCore` 拥有领域行为。`AIShellMCP` 仅翻译协议请求和结果。Git、ripgrep、编译器、测试和 SourceKit-LSP 仍然是直接启动的工作程序，而不是新的状态所有者。
## 从 npm 安装
全局包将 `aishell-mcp` 和 `aishell-open` 添加到 `PATH`。`aishell-open` 通过 LaunchServices 打开捆绑的管理器应用程序。该包不运行安装脚本。
升级替换了打开的任何管理器窗口下的应用程序包，这会破坏该窗口 — 它保留了一个已删除的包，并静默丢失了每个打开文件面板的操作。窗口本身检测到这一点，并用横幅说明。当新版本位于同一路径时，横幅将窗口重新启动到其中；否则，它要求退出并进行新的 `aishell-open`。验证了实际的 `npm install -g` 升级，而不仅仅是模拟的升级。
```sh
npm install -g @quolu/aishell
aishell-open
```
当前的实验性构建尚未经过 Developer ID 签名或 notarization。
## 从源代码构建
```sh
git clone https://github.com/kitepon-rgb/aishell.git
cd aishell
swift test
scripts/package-app.sh release
open build/AIShell.app
```
MCP 可执行文件在 `build/AIShell.app/Contents/Helpers/aishell-mcp` 处捆绑。
打开应用程序后，使用 **添加允许根** 选择 AIShell 可以访问的文件夹。在允许的仓库下注册的 Git 工作树在双方的工作树元数据同意时自动识别。
## 连接另一个 AI 主机
对于 Homebrew 前缀 npm 安装，请注册绝对可执行路径：
```sh
codex mcp add aishell -- /opt/homebrew/bin/aishell-mcp
codex mcp get aishell
```
使用以下命令删除注册：
```sh
codex mcp remove aishell
```
在没有扩展功能的情况下，兼容性配置文件保留所有 25 个工具。默认的七个工具是五个开发工具加上两个恢复控件；完整模式添加其余的传统基元。使用 `expanded-v1`，开发公开了 11 个工具，完整公开了 29 个：
```sh
AISHELL_TOOL_PROFILE=full /opt/homebrew/bin/aishell-mcp
AISHELL_CAPABILITY_SET=expanded-v1 AISHELL_TOOL_PROFILE=full /opt/homebrew/bin/aishell-mcp
```
完整配置文件包括文件列表和读取、原子 SHA-256 保护的更新、复制/移动/重命名/回收站、直接进程执行、应用程序发现和启动、运行时状态和管理器激活。
## 执行和安全边界
- AIShell 永远不会评估 shell 命令字符串。它将开发程序从 `PATH` 解析为可执行 URL，并保持参数、环境和工作目录的独立性。
- 直接启动 shell 和包装器基本名称（例如 `sh`、`bash`、`zsh`、`env` 和 `osascript`）作为产品轨道被拒绝，而不是作为安全边界宣传。
- `run_check` 是一个开放世界的 capa：允许的工作程序可以更新文件、启动子进程或访问网络。AI 主机可能需要在执行前获得批准。
- npm 项目可以将 `build`、`test` 或 `lint` 检查纳入新鲜度缓存中，使用封闭的直接 Node `package.json` 声明，如 `docs/adr/0009-project-profile-contract.md` 中所述。普通的 npm 脚本仍然可执行，但不符合缓存资格；AIShell 不会推断参数、输入或 shell 脚本文本的效果。
- 文本更新可以使用 SHA-256 或预期旧文本作为前提条件。删除操作进入回收站。
- 管理器应用程序可以全局停止正常操作。运行时状态和管理器激活在停止时仍然可用。
## 当前限制
- stdio 服务器一次处理一个请求。
- MCP 取消和并发运行轮询未实现。
- 超时终止直接拥有的进程树，但允许的工作程序在终止前仍然具有开放世界的副作用。
- 初始工作空间条目是有限的预览；后续增量是基于光标分页的。
- 开发者 ID 签名和 notarization 尚未配置。
## 开发
```sh
swift test
scripts/package-app.sh release
```
运行 `xcodegen generate` 以重新生成 `AIShell.xcodeproj`。权威实现位于 `Sources/AIShellCore`、`Sources/AIShellMCP` 和 `Sources/AIShellApp` 下；聚焦测试位于 `Tests/` 下。
<details>
<summary>本地 Xcode 验证注意</summary>
在原始验证机器上，Xcode 26.6 和已安装的 CoreSimulator 构建版本不匹配，因此 `xcodebuild` 在 XCBuild 开始前停滞。相同的 Swift 6.3.3 工具链通过 SwiftPM。那台主机问题未被视为源代码成功。
</details>
## 贡献和安全
在提出更改之前，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。请通过 [SECURITY.md](SECURITY.md) 中的私有流程报告漏洞，而不是通过公共问题。
发行说明保存在 [`docs/`](docs/) 中。GitHub Releases 是已发货版本的公共记录。
## 许可证
AIShell 在 [Apache License 2.0](LICENSE) 下获得许可。
