zk-data-agent/docs/README.zh-CN.md

K1412 Agent 中文文档

中文 · English

本目录是 K1412 Agent 的权威技术记录。公开文档门户 https://agent.k1412.top/doc/ 是同一套设计的精选呈现。行为、基础设施或实验发生变化时， 应在同一个 commit 中同时更新对应的 Markdown 文档和门户摘要。

从这里开始

文档	适合读者	回答的问题
架构	所有人	哪些组件运行在哪里？为什么这样划分边界？
Agent Loop	Agent 研究者、后端工程师	上下文、工具、调度、证据、记忆和子 Agent 如何工作？
实验体系	Agent 研究者	如何修改 Loop，同时保持实验可比性和生产安全？
项目历史	维护者	已经做出了哪些产品和架构决策？
Open WebUI 集成	前端、平台工程师	哪些职责属于 Open WebUI，哪些仍由 K1412 负责？
安全模型	安全、平台工程师	用户、凭据、工作区和 Docker 如何隔离？
基础设施地图	运维人员	哪些是共享基础设施，哪些属于 Agent 核心？
开发与验证	贡献者	如何运行、测试并安全修改系统？
运维手册	运维人员	如何构建、部署、验证、备份和迁移生产环境？

当前产品约定

• 用户只看到一种模式：K1412 Agent Loop。早期的 Chat/Work 双模式已被有意移除。
• Open WebUI 负责账户、会话、审批、对话存储和聊天外壳；K1412 负责 Agent 行为。
• 服务端定义四个模型选项：Luna、Terra、Sol、DeepSeek V4 Pro。模型身份和思考能力 分开显示。
• 每个 Open WebUI 用户都会在专用物理执行主机上获得独立的 Docker 容器、网络和持久卷。
• 生成文件可以通过已鉴权的 Web UI 浏览和下载，内部依赖目录默认隐藏。
• Provider 凭据、内部提示词、Docker 权限、SSH 配置和工具服务凭据都不能在浏览器配置。

哪些部分属于实验

稳定的平台边界包括鉴权、用户/工作区隔离、持久存储和公开的 OpenAI 兼容 Runtime API。 计划持续实验的范围包括：

• 上下文选择与压缩；
• 记忆检索与生命周期；
• 工具描述、规范化和路由；
• 并行调度与变更串行化；
• 子 Agent 委派策略；
• 证据和完成门禁；
• 恢复提示词与重试策略；
• 模型路由与各档预算。

每项实验都应在运行事件中记录版本，并在进入生产环境前针对固定任务集完成评测。详见 实验体系。