# K1412 Agent

中文 · [English](README.md)

K1412 Agent 是一个多人 Web 编码 Agent。每一次用户请求都会进入同一套可独立演进的
Agent Loop；调度器、上下文策略、记忆、工具、证据规则和子 Agent 均由本仓库实现和维护。

生产环境：<https://agent.k1412.top>

架构、Agent 实现细节和实验台账：<https://agent.k1412.top/doc/>

## 架构

```text
浏览器
  |
  v
Open WebUI（鉴权、RBAC、对话历史、界面）
  |
  v
Agent Runtime（模型网关 + Agent Loop）
  |
  v
Workspace Gateway（身份、策略、审计）
  |
  v
专用执行主机上，每个 Open WebUI 用户对应一个 Docker 工作区
```

Open WebUI 被固定到明确版本并进行少量补丁修改。它的选择器只展示四个模型名称，以及一个
独立、只读的思考状态。Provider URL、上游模型 ID、API Key、工具服务设置、系统提示词和
Runtime 参数全部保留在服务端。

模型身份与思考能力有意分开表达：

| 界面模型 | Provider 模型 | 思考 | 推理强度 |
| --- | --- | --- | --- |
| Luna | `ChatGPT-5.6:Luna` | 开启，不分强度档位 | — |
| Terra | `ChatGPT-5.6:Terra` | 开启，不分强度档位 | — |
| Sol | `ChatGPT-5.6:Sol` | 开启，不分强度档位 | — |
| DeepSeek V4 Pro | `deepseek-v4-pro` | 开启 | 极高（`max`） |

三个 Ollama 模型会声明 `thinking` 能力，但它们属于仅提供思考开关的 Qwen 系列模型，
没有 GPT-OSS 风格的低、中、高推理强度。Luna、Terra、Sol 是三个不同的模型，不是同一个
模型的三个推理设置。

## 本地开发

1. 将 `.env.example` 复制为 `.env` 并填写密钥。绝不能提交 `.env`。可使用
   `./scripts/init-secrets.sh` 生成新值。
2. 构建用户工作区镜像：

   ```bash
   docker compose --profile build-only build workspace-image
   ```

3. 启动完整服务栈：

   ```bash
   docker compose up --build
   ```

4. 打开 <http://localhost:3000>。新用户注册后的角色为 `pending`，必须由初始化管理员批准。

Provider 凭据不会保存在仓库中，只能放在受保护的部署 `.env` 中。

## 测试

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
```

运行包含真实 Docker 隔离测试的完整本地验证：

```bash
./scripts/verify.sh
```

在唯一、可销毁、禁用网络的 Docker 工作区中运行真实 Agent 评测：

```bash
set -a
source /path/to/protected/deepseek.env
set +a
.venv/bin/python scripts/eval-live-work.py --model deepseek-v4-pro
```

评测器会报告延迟、Token 使用、工具调用次数、完成证据和生成文件列表。除非传入
`--keep-workspace`，否则结束时只会删除本次评测唯一对应的容器、卷和网络。

运行使用确定性假模型 Provider 的一次性六服务集成栈，验证注册审批、Agent Loop、
工作区隔离和文件交付：

```bash
./scripts/verify-e2e.sh
```

E2E 服务栈及其测试专用卷会在退出时删除。只有需要检查运行中容器时才设置
`E2E_KEEP_STACK=1`。

审计所有最终服务镜像和工作区镜像，要求 Python 环境依赖一致、没有已知 Python 漏洞，
且不存在可修复的 High/Critical 镜像漏洞：

```bash
./scripts/audit-images.sh
```

生成文件可通过模型选择器旁边的“工作区文件”按钮获取。用户可以浏览目录、下载单个文件，
或者将当前目录下载为 `.tar.gz` 归档。浏览器请求先由 Open WebUI 鉴权，再为 Workspace
Gateway 重新签名；任何内部密钥都不会暴露给浏览器。

## 文档

- [中文文档索引](docs/README.zh-CN.md)
- [架构与 Agent Loop](docs/architecture.zh-CN.md)
- [Agent Loop 实现](docs/agent-loop.zh-CN.md)
- [实验体系](docs/experiments.zh-CN.md)
- [项目历史与决策](docs/project-history.zh-CN.md)
- [Open WebUI 集成](docs/openwebui-integration.zh-CN.md)
- [基础设施地图](docs/infrastructure.zh-CN.md)
- [开发与验证](docs/development.zh-CN.md)
- [运维手册](docs/operations.zh-CN.md)
- [安全模型](docs/security.zh-CN.md)
- [English documentation](docs/README.md)

## 部署

生产环境使用 `docker.k1412.top/wuyang/*` 中不可变的 `linux/amd64` 镜像、Unraid Compose
Manager 项目、私有服务网络，以及唯一的公开 HTTPS 入口
<https://agent.k1412.top>。

用户工作区通过 SSH 运行在专用 Docker 主机上；应用服务和数据库仍运行在 NAS。

## 许可证与 Open WebUI 归属

Web 服务派生自 Open WebUI v0.9.6。Open WebUI 的版权、许可证和归属继续遵循上游
Open WebUI License。K1412 原创的 Runtime、Gateway、部署、测试和文档使用 Apache-2.0。
因此本仓库是混合许可证仓库；派生自 Open WebUI 的 Web 层不会被重新许可为 Apache-2.0。

生产部署使用 Open WebUI 针对滚动 30 天内不超过 50 名最终用户的品牌移除例外。公开构建
默认保留上游品牌。详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。