# 项目沿革与决策

中文 · [English](project-history.md)

这份记录总结了从 2026-07-26 开始的重构。Git 仍是精确变更的事实来源；本文记录产品意图和架构决策，因为这些信息很难从单个提交中还原。

## 1. 从零重建网页 Agent

原有的业务/数据专用应用被明确作为一个不要求向后兼容的新项目重建。业务 Skill、领域工作流和用户可配置的模型提供方设置都被移出范围。保留的核心需求是通用编码 Agent 能力，以及可以独立演进的 Agent 循环。

决策：

- 构建一个通用的多用户网页 Agent；
- 保留编码、Shell、文件、Git、进程、计划、记忆和委派能力；
- 将基础设施和产品外壳与 Agent 智能分离。

## 2. 以 Open WebUI 作为产品外壳

项目没有继续维护第二套完整的账户/聊天前端，而是固定使用 Open WebUI v0.9.6，并做少量补丁。它提供注册、登录、RBAC、管理员审批、对话历史和熟悉的聊天交互。

K1412 保留 Agent 循环、提供方路由、记忆、工具、调度、事件和工作区执行的所有权。这样既降低了 Agent 实验成本，也没有让循环依赖 Open WebUI 内部实现。

## 3. 单一 Agent 路径，而不是 Chat 与 Work

早期设计曾考虑在 Open WebUI 原生 Chat 循环和 K1412 Work 循环之间切换。最终产品简化为一条 Agent 路径，原因是：

- 用户不应被迫理解两套编排引擎；
- 在两种模式间继续对话会产生含糊状态；
- 两个循环会让前端状态和验证行为翻倍；
- 自定义循环才是项目最重要的研究资产。

保留下来的界面是 Agent 优先的聊天界面，模型选择由服务端管理。

## 4. 模型与思考语义

原先的“轻度/中/高推理”标签把不同模型和可调推理强度混为一谈。现在 UI 和后端会区分模型身份与思考能力：

- Luna、Terra 和 Sol 是三个不同的 K1412/Ollama 本地模型；
- 每个模型都标为支持思考，但没有可调节的强度档位；
- DeepSeek V4 Pro 是云端极高档位，使用最大推理强度。

提供方模型 ID、URL、凭据和调优参数都保留在服务端。

## 5. 多用户远程工作区

每个用户都有一个由不可变用户 ID 的哈希派生出的专属 Docker 容器、网络和持久数据卷。执行环境通过 SSH Docker 从 NAS 迁移到物理机 `home-node-itx`。

物理节点的准备包括：

- 一块挂载到 `/srv/k1412-data` 的 ext4 500 GB 数据盘；
- Docker root 位于 `/srv/k1412-data/docker`；
- 严格的 SSH 主机校验；
- 不存放应用或数据库密钥。

本地与 SSH 执行提供方保持同一套接口，因此以后更换主机时不需要改变 Agent 行为。

## 6. 文件交付与聚焦的界面

前端围绕 Agent 进行了简化：

- K1412 产品名称与视觉资产；
- 紧凑的模型选择器，并单独显示思考状态；
- 不向用户暴露提供方、工具或系统提示词设置；
- 已鉴权的工作区文件浏览器；
- 单文件下载和目录流式归档。

Open WebUI 的署名与许可证要求仍有完整记录。

## 7. 从失败任务分析中加固循环

真实的排序脚本/报告任务暴露了模型能力弱点和平台缺陷。循环随后逐步强化：

- 要求生成真实文件，而不是只做文字声明；
- 要求源码与报告分别形成文件；
- 先执行源码，再写报告；
- 要求使用实测的基准数值；
- 拒绝无效 Python 和转义换行造成的版式损坏；
- 从失败的验证中恢复；
- 防止无变化的重试循环和重复批次；
- 即使输出经过管道，也保留前序命令的失败状态；
- 限制迭代、工具批次、模型输出和重试预算。

这些约束并不被假定为永久最优。它们是当前基线，只应通过有测量结果的实验来删除或修改。

## 8. Python 环境与长任务可靠性

生产调试发现了三个平台问题：

1. 容器根文件系统只读，但 `pip` 默认写入 `/home/agent`；
2. `/tmp` 以 `noexec` 挂载；
3. Shell 管道返回最后一个命令的状态，掩盖了安装失败。

修复方案把 home、缓存、用户软件包和虚拟环境移动到持久工作区，启用 Bash `pipefail`，把工具超时延长到 900 秒，并让 Agent 使用受支持的 `.venv` 工作流。

同一次排查还发现，五分钟有效期的身份令牌会在一次长任务的每个工具调用中重复使用。现在 Runtime 会在原始请求身份校验通过后，为每次 Gateway 调用重新签发短期身份。

生产验证实际创建了 `.venv`，安装并导入 `psutil 7.2.2`，通过 Web API 下载了生成的证明文件，随后删除了临时证明文件。

## 9. 文档与实验门户

仓库文档围绕架构、Agent 实现、安全、运维、项目沿革、开发和实验重新组织。整理后的公开门户打包在现有 Web 镜像中，通过 `/doc/` 提供，因此无需第二个服务或代理规则。

## 当前方向

平台现在已经适合开展受控的 Agent 循环实验。下一阶段应优先建设评测数据、上下文/记忆实验、调度器设计、委派契约、成本核算，以及针对恶意多租户环境的加固，而不是增加特定业务工作流。