wuyang
154 lines
4.7 KiB
Markdown
154 lines
4.7 KiB
Markdown
# K1412 Agent
|
||
|
||
K1412 Agent is a multi-user web Agent built around two deliberately different
|
||
experiences:
|
||
|
||
- **Chat** is fast, conversational, and uses Open WebUI's native tool loop.
|
||
- **Work** is a long-running coding Agent whose loop, scheduler, context,
|
||
memory, tools, and sub-agents are owned by this repository.
|
||
|
||
A conversation may be upgraded from Chat to Work. The upgrade is intentionally
|
||
one-way so that two independent Agent loops never compete for the same
|
||
conversation state.
|
||
|
||
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 + Work 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 model picker is replaced by two
|
||
product-level choices: `Chat / Work` and `轻度 / 中 / 高 / 极高`. Provider URLs,
|
||
provider model IDs, API keys, tool server settings, system prompts, and runtime
|
||
parameters remain server-side.
|
||
|
||
The inference mapping is fixed:
|
||
|
||
| Strength | Provider model |
|
||
| --- | --- |
|
||
| 轻度 | `ChatGPT-5.6:Luna` |
|
||
| 中 | `ChatGPT-5.6:Terra` |
|
||
| 高 | `ChatGPT-5.6:Sol` |
|
||
| 极高 | `deepseek-v4-pro`（Thinking，`reasoning_effort=max`） |
|
||
|
||
## 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.
|
||
|
||
The pasted provider credential from the planning conversation is intentionally
|
||
not stored here. Rotate it and place the replacement 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 Work 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 work-extreme
|
||
```
|
||
|
||
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, both Agent loops, workspace
|
||
isolation, and the one-way mode upgrade 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 mode
|
||
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).
|