内容
_ _ ____ _
/ | | |__ __| |_ / ___|___ __| | / _ \ | | / _ \ '__| | | / _ \ / _` |/ _ \
\| | |_) | | |_ |__| (_) | (_| __/
/_/ \_\_|_.__/ \___|_| \__| \____\___/ \__,_|\___|
```
# Albert 代码
⚠️ 实验性项目 ⚠️
**自主编码技术栈，适用于国家，通过一条命令即可使用：OpenCode + agent-vm + Albert API + 国家技能 + MCP.**
Albert Code 汇集了现有的组件，带有内置国家 AI 进行编码：
- **[Albert API](https://al.etalab.gouv.fr)**：国家的自主模型（SecNumCloud 托管），兼容 OpenAI 的提供程序。
- **[agent-vm](https://github.com/sylvinus/agent-vm)**：可丢弃的 Lima 沙盒。代理在虚拟机中自主运行，无需访问主机。
- **[OpenCode](https://opencode.ai)**：代码终端助手。
- **[国家技能](https://github.com/etalab-ia/skills)**：DSFR、 accessibility (RGAA)、安全、data.gouv。
- **MCP**：data.gouv、context7、playwright、chrome-devtools。
这不是一个 IDE 或 fork：它是一个轻量级的编排（脚本 + 配置）层，位于 OpenCode 之上。
> 状态：v1，于 2026-07-02 完成内部测试。正在与早期采用者进行测试。欢迎反馈和问题。
## 前置条件
- macOS 或 Linux（不支持 Windows）。
- [Lima](https://lima-vm.io)（如果未安装，安装脚本会自动安装，通过 Homebrew）。
- Node.js（用于通过 `npx` 启动的 MCP 服务器）。
- **Albert API 密钥**（仅限于公职人员：在 https://albert.api.etalab.gouv.fr 上申请）。
- GitHub 账户（用于代理从虚拟机推送 PR）。
## 安装
```bash
git clone https://github.com/etalab-ia/albert-code.git ~/albert-code
cd ~/albert-code
./install.sh
```
> 安装路径**不能包含空格**（agent-vm/Lima 的限制，它在虚拟机中挂载工作目录）。
`install.sh` 是**幂等的**和**非破坏性的**：它不会重新安装已经，也不会覆盖配置。两个阶段：
- **阶段 A（主机初始化）**：Lima + agent-vm、Albert 提供程序、国家技能、MCP 连接器、虚拟机中的密钥。从存储库运行脚本时启动。
- **阶段 B（项目脚手架）**：从项目目录运行脚本时启动。请求上下文，然后设置 `AGENTS.md` 配置文件和项目范围的 `opencode.json`。
标志：`--dry-run`（模拟安装而不进行任何更改），`--help`。
### 惯例配置文件
在项目脚手架过程中，请求上下文并应用**其约定（无默认值，无混合）：
| 配置文件定 |
|---|---|
| `beta.gouv` | DSpnpm、French commits、Next.js / FastAPI |
Suite` | UI Suite、yarn、gitmoji commits、Django |
| `IAE / Albert` | FastAPI、uv、Ruff（OpenGateLLM 风格） |
| `其他` | 无强加约定（提供自己的 `AGENTS.md`） |
## 使用
```bash
mkdir -p ~/my-project && cd ~/my-project
~/albert-code/install # 阶段 B：选择配置文件 + 项目配置
agent setup --disk 32 # 仅一次：创建基本虚拟机
agent-vm --cpus 4 --memory 8 --disk 32 opencode # 打开隔离的虚拟机 + OpenCode
```
在虚拟机中，代理以自主模式运行（`--dangerously-skip-permissions`），由于所有内容都封装在虚拟机中，因此是安全的。你可以用法语与它交流。
确切的命令（带有你的值）将在 `install.sh` 结束时显示在“下一步”下。
> 如果你的项目已经有一个 `opencode.json`，它将被**保留**（非破坏性）- 检查它是否包含 Albert 提供程序，否则 Albert 将无法连接。参见[故障排除](#故障排除)部分。
### 虚拟机资源
agent-vm 的默认资源（1 CPU / 3 GiB / 10 GiB）对于代码代理来说太有限了。Albert Code 默认应用 `4 CPU / 8 GiB / 32 GiB`，可以通过环境变量重载：
```bash
AC_VM_CPUS=8 AC_VM_MEMORY=16 AC_VM_DISK=64 ./install.sh
```
| 变量 | 默认值 | 角色 |
|---|---|---|
| `AC_VM_CPUS` | `4` | 分配的 CPU（在 `agent-vm opencode` 启动时应用）。 |
| `AC_VM_MEMORY` | `8`（GiB） | 分配的 RAM（在启动时应用）。 |
| `AC_VM_DISK` | `32`（GiB） | 磁盘，在第一次 `agent-vm setup` 时固定，之后只能增长。 |
**主机保护**（只读，macOS + Linux）：`install.sh` 检测主机资源（`sysctl`/`nproc`）并建议不超过主机 CPU/RAM 的一半，即使 `AC_VM_*` 请求更多 - 以避免在小型主机上分配过多资源。磁盘永远不会被截断（稀疏：按需分配，而不是一次性分配）；如果可用空间不足，则会显示警告。
## 安全
- **内核隔离（Lima）**：代理无法访问主机的 SSH 密钥、凭证、cookie 或会话。虚拟机是可丢弃的（`agent-vm rm`）。
- **机密**：密钥 (`ALBERT_API_KEY`、`7_API_KEY`) 永远不会被版本控制或记录；它们在虚拟机的 `~/.zshenv` 中以 `chmod 600` 权限保存。
- **残留风险（提示注入）**：恶意内容（网页、问题、文件）可能会促使代理通过网络提取密钥。最佳实践：**专用和可撤销的** Albert 密钥（不是你的主密钥），每个 PR 在合并人工审查，不要向代理提供敏感数据。
## 内部机制
- **Harness** OpenCode。通过 `@ai-sdk/openai-compatible` 使用程序（`model` = `Mistral-Medium-3.5-128B`，`small_model` = `DeepSeek-V4-Flash`）。
- **配置**：项目范围的 `opencode.json`（永远不是用户的全局配置，可能有其他提供程序）。
- **技能**：`etalab-ia/skills` 克隆到缓存 (`~/.config/opencode/.albert-skills-cache`) 并符号链接到 OpenCode 扫描的目录中，每次虚拟机启动时更新。现有的个人技能永远不会被覆盖。
- **MCP**：`data-gouv`（远程），`context7`（远程，**可选** - 如果没有 `CONTEXT7_API_KEY`，可以忽略；如果需要，请访问 https://context7.com/plans 获取 API 密钥），`playwright` 和 `chrome-devtools`（本地）。
注意：如果没有密钥，context7 MCP 将在虚拟机中显示为错误 -> 如果有干扰，请在 `opencode.json` 中禁用。
## 文档
[OpenCode](https://opencode.ai/docs/fr) · [Albert API](https://doc.incubateur.net/alliance/albert-api) · [agent-vm](https://github.com/sylvinus/agent-vm) · [国家技能](https://github.com/etalab-ia/skills)
## 故障排除
- **`agent-vm: command not found` 在安装后立即出现** → 该命令位于 PATH 中。如果仍然无法找到，请打开一个新的终端窗口以重新加载 PATH。
- **`Base VM not found. Run 'agent-vm setup' first.`** → 运行 `agent-vm setup --disk 32` 一次（安装脚本也会自动建议）。
- **在 OpenCode 中，但未连接到 Albert（无 `/models`，`/mcp`，`/skills`）** → 您在没有 `opencode.json` 的目录中运行了 `agent-vm opencode`（例如，Albert Code 存储库本身或从未脚手架的项目）。首先脚手架：`cd <your-project> && ~/albert-code/install.sh`（阶段 B），然后重新运行 `agent-vm opencode`。
- **我的项目已经有一个 `opencode.json`** → 它将被**保留**（性）。检查它是否包含 Albert 提供程序；如果不，请手动添加 `provider.albert` 块和 `model` / `small_model`。
## 卸载
```bash
./uninstall.sh
```
删除虚拟机运行时、缓存和技能符号链接。保留个人技能和配置。
## 贡献
欢迎提交问题和 PR。该存储库遵循其自身的约定，位于 [`AGENTS.md`](AGENTS.md) 中；上下文和决策位于 [`docs/PLAN.md`](docs/PLAN.md) 中。
> **开发 Albert Code 本身**：复制 `config/opencode.template.json` 到 `opencode.json`（已经在 `.gitignore` 中），然后运行 `agent-vm opencode` -.sh` 不会为其自己的存储库脚手架。
---
Albert Code · 国家人工智能部门（IAE），DINUM · MIT 许可证
MCP 市场