wuyang
151 lines
4.8 KiB
Markdown
151 lines
4.8 KiB
Markdown
# K1412 Agent
|
|
|
|
K1412 Agent is a multi-user web coding Agent. Every user request enters the
|
|
same independently evolvable Agent loop; its scheduler, context policy, memory,
|
|
tools, evidence rules, and child Agents are owned by this repository.
|
|
|
|
The production instance is available at <https://agent.k1412.top>.
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
browser
|
|
|
|
|
v
|
|
Open WebUI (auth, RBAC, chat history, UI)
|
|
|
|
|
v
|
|
Agent Runtime (model gateway + Agent loop)
|
|
|
|
|
v
|
|
Workspace Gateway (identity, policy, audit)
|
|
|
|
|
v
|
|
one Docker workspace per Open WebUI user on a dedicated execution host
|
|
```
|
|
|
|
Open WebUI is pinned and lightly patched. Its picker exposes only four model
|
|
names and a separate read-only thinking status. Provider URLs, provider model
|
|
IDs, API keys, tool server settings, system prompts, and runtime parameters
|
|
remain server-side.
|
|
|
|
Model identity and thinking control are intentionally separate:
|
|
|
|
| UI model | Provider model | Thinking | Reasoning effort |
|
|
| --- | --- | --- | --- |
|
|
| Luna | `ChatGPT-5.6:Luna` | On, no effort levels | — |
|
|
| Terra | `ChatGPT-5.6:Terra` | On, no effort levels | — |
|
|
| Sol | `ChatGPT-5.6:Sol` | On, no effort levels | — |
|
|
| DeepSeek V4 Pro | `deepseek-v4-pro` | On | Extreme (`max`) |
|
|
|
|
The three Ollama models advertise `thinking`, but they are Qwen-family models
|
|
with a boolean thinking switch rather than GPT-OSS-style low/medium/high
|
|
effort levels. Luna, Terra, and Sol are different models, not three reasoning
|
|
settings for one model.
|
|
|
|
## Local development
|
|
|
|
1. Copy `.env.example` to `.env` and fill in the secret values. Never commit
|
|
`.env`. Generate new values with `./scripts/init-secrets.sh`.
|
|
2. Build the user workspace image:
|
|
|
|
```bash
|
|
docker compose --profile build-only build workspace-image
|
|
```
|
|
|
|
3. Start the stack:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
4. Open <http://localhost:3000>. New users register as `pending` and require
|
|
approval by the bootstrap administrator.
|
|
|
|
Provider credentials are intentionally not stored here. Keep them only in the
|
|
protected deployment `.env`.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
.venv/bin/pip install -e '.[dev]'
|
|
.venv/bin/pytest
|
|
```
|
|
|
|
Run the complete local verification path, including the real Docker isolation
|
|
test, with:
|
|
|
|
```bash
|
|
./scripts/verify.sh
|
|
```
|
|
|
|
Run a live Agent evaluation in a unique, disposable, network-disabled Docker
|
|
workspace with:
|
|
|
|
```bash
|
|
set -a
|
|
source /path/to/protected/deepseek.env
|
|
set +a
|
|
.venv/bin/python scripts/eval-live-work.py --model deepseek-v4-pro
|
|
```
|
|
|
|
The evaluator reports latency, token usage, tool counts, completion evidence,
|
|
and the generated file listing. It removes only the uniquely named evaluation
|
|
container, volume, and network unless `--keep-workspace` is supplied.
|
|
|
|
Run the disposable six-service integration stack with a deterministic fake
|
|
model provider and exercise registration approval, the Agent loop, workspace
|
|
isolation, and file delivery with:
|
|
|
|
```bash
|
|
./scripts/verify-e2e.sh
|
|
```
|
|
|
|
The E2E stack and its test-only volumes are removed on exit. Set
|
|
`E2E_KEEP_STACK=1` only when you need to inspect the running containers.
|
|
|
|
Audit every finished service and workspace image, requiring consistent Python
|
|
environments, zero known Python vulnerabilities, and zero fixable
|
|
High/Critical image vulnerabilities, with:
|
|
|
|
```bash
|
|
./scripts/audit-images.sh
|
|
```
|
|
|
|
Generated files are available from the **工作区文件** button beside the model
|
|
selector. Users can browse directories, download one file, or download the
|
|
current directory as a `.tar.gz` archive. Browser requests are authenticated by
|
|
Open WebUI and re-signed for the Workspace Gateway; no internal key is exposed.
|
|
|
|
## Documentation
|
|
|
|
- [Architecture and Agent loop](docs/architecture.md)
|
|
- [Open WebUI integration](docs/openwebui-integration.md)
|
|
- [Infrastructure map](docs/infrastructure.md)
|
|
- [Operations runbook](docs/operations.md)
|
|
- [Security model](docs/security.md)
|
|
|
|
## Deployment
|
|
|
|
Production uses immutable `linux/amd64` images in
|
|
`docker.k1412.top/wuyang/*`, an Unraid Compose Manager project, private
|
|
service networking, and a single public HTTPS entry at
|
|
`https://agent.k1412.top`.
|
|
|
|
User workspaces run through SSH on a dedicated Docker host; application and
|
|
database services remain on the NAS.
|
|
|
|
## License and Open WebUI attribution
|
|
|
|
The web service is derived from Open WebUI v0.9.6. Open WebUI's copyright,
|
|
license, and attribution remain under the upstream Open WebUI License. K1412's
|
|
original Runtime, Gateway, deployment, tests, and documentation are Apache-2.0.
|
|
This is therefore a mixed-license source repository; the Open WebUI-derived web
|
|
layer is not relicensed as Apache-2.0.
|
|
|
|
The production deployment uses Open WebUI's branding-removal exception for
|
|
installations with at most 50 end users in a rolling 30-day period. Public
|
|
builds retain upstream branding by default. See
|
|
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|