为 AI 编码代理自动加载本地作用域

AI 编码代理正在成为日常开发流程的一部分。

Codex 和 Claude Code 这类工具可以帮助开发者写代码、调试问题，并直接在真实项目中工作。但它们通常需要读取项目相关的环境变量。

这会带来一个很实际的问题：正确的密钥应该只在正确的项目目录里生效，而不是泄露到所有项目中。

GitHub

aiscope 是什么？

aiscope 是一个小型开源 CLI 工具，用来为 AI 编码代理自动加载本地作用域。

它想解决的问题很简单：

cd ~/projects/demo-app
codex

这就应该足够了。

不需要包装命令。不需要全局 API Key。不需要手动切换环境变量。

当你进入一个已配置作用域的目录时，aiscope 会加载对应的环境变量。当你离开这个目录时，它会自动卸载该作用域。

cd ~/projects/demo-app
aiscope: loaded project/demo-app
codex

cd ..
aiscope: unloaded project/demo-app

目录决定作用域。

任何在该目录中启动的 CLI 都会获得正确的环境变量。

为什么本地作用域很重要

AI 编码工具经常需要这些环境变量：

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• 数据库 URL
• Cloudflare Token
• Vercel Token
• 项目专属配置

常见做法通常不够理想：

dotenvx run -- codex
source .env && claude
OPENAI_API_KEY=... codex

另一种常见方式是把所有东西都导出到 .zshrc。

这在一开始能用，但当你在多个项目之间切换时，很容易把错误的密钥带到错误的项目里。

对于开发者、独立开发者和 SaaS 构建者来说，项目越多，这个问题越明显。

aiscope 的目标就是让这个流程更安全、更简单。

aiscope 如何工作

aiscope 会为每个项目或技能创建独立的本地作用域。

项目作用域可以用于某个具体应用、SaaS 项目、API 或网站。

mkdir my-app
cd my-app
aiscope init project my-app
aiscope edit
codex

技能作用域可以用于可复用的工作流，比如前端设计、基础设施配置，或者某个代理专用的环境。

mkdir frontend-design
cd frontend-design
aiscope init skill frontend-design
aiscope edit
claude

启用 shell hook 之后，aiscope 会监听目录变化。

进入带有作用域的目录时，它会加载对应环境。离开时，它会卸载环境。

aiscope 目前支持什么

第一个版本保持得很小。

目前支持：

• 项目作用域
• 技能作用域
• zsh hook
• bash hook
• 本地环境变量 vault
• 状态输出自动打码
• 安全的 dotenv 解析

这个设计让 aiscope 专注于一件事：让本地 AI 编码环境更容易管理。

安装 aiscope

使用 npm 安装：

npm install -g aiscope

然后启用 shell hook：

eval "$(aiscope hook zsh)"

如果要永久启用 zsh 配置：

echo 'eval "$(aiscope hook zsh)"' >> ~/.zshrc
source ~/.zshrc

完成后，aiscope 就可以在你切换目录时自动加载和卸载作用域。

安全模型

aiscope 是 local-first 的。

密钥保存在：

~/.aiscope/vault

状态输出会默认隐藏真实值：

Loaded keys:
  OPENAI_API_KEY=***
  ANTHROPIC_API_KEY=***
  DATABASE_URL=***

环境变量文件会作为数据解析，而不是作为 shell 脚本执行。

aiscope 目前并不是云端密钥管理器，也还不是加密 vault。它是一个小型本地工具，用来让 AI 编码工作流更顺畅，并减少出错概率。

路线图

未来版本可能会加入：

• 加密本地 vault
• agent 和 workflow 作用域
• 作用域权限
• AI context 文件
• 1Password 集成
• Bitwarden 集成
• Homebrew 安装
• VS Code 扩展

这些能力可以让 aiscope 支持更复杂的代理工作流，同时继续保持 local-first 的使用方式。

相关链接

• GitHub
• 官网
• npm

推荐

如果你每天都在使用 AI 编码代理，并且经常在多个项目之间切换，aiscope 值得一试。

它解决的是一个很具体的问题：把正确的环境变量绑定到正确的本地目录。

对独立开发者、SaaS 构建者和网站维护者来说，这可以让 AI 辅助编码流程更清晰、更安全，也更不容易出错。