wuyang
144 lines
4.9 KiB
Markdown
144 lines
4.9 KiB
Markdown
# 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)。
|