# k_agent

**Repository Path**: lmk73444/k_agent

## Basic Information

- **Project Name**: k_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-04
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# k_agent

**开箱即用的 Claude Code 协作平台** — 让团队无需配置环境，浏览器打开即可使用 AI 编程助手。

## 为什么需要 k_agent？

Claude Code 能力很强，但让团队每个人都在本地配好环境却是个麻烦事——装 Node.js、配代理、折腾 Docker、解决各种系统兼容问题。对新手来说，光是看到终端界面就已经劝退了。

k_agent 把这些复杂度封装进容器，提供一个 **Web 端的隔离工作空间**：

- **零环境配置**：用户只需一个浏览器，登录即用，无需安装任何工具链
- **一人一容器，资源可控**：每个用户独享隔离的 Claude Code 容器环境，可限制 CPU/内存，空闲自动回收——不互相干扰，也不浪费资源
- **两种交互模式，覆盖不同场景**：
  - **对话模式**：适合新手和日常问答，像聊天一样使用 AI，对话自动保存、上下文可视，产物一键下载
  - **Shell 模式**：适合开发者，浏览器内嵌完整终端（tmux），侧边栏管理文件——跟本地开发体验一致，但不需要配任何环境
- **多租户管理**：管理员可统一监控用量、管理用户，一条命令部署整个团队的工作空间

本质上，k_agent 是一个 **自托管的 Claude Code 网关**——你把 AI 编程能力部署在自己的服务器上，团队成员通过浏览器接入，所有人的工作环境统一、隔离、可管控。

### 设计理念：工作窗口不应丢失

本地运行 Claude Code 有一个根本性的脆弱点——**会话是绑定在终端进程上的**：

- 坐高铁穿隧道，SSH 断开 → Claude 正在分析代码的会话消失
- 笔记本合盖休眠，WiFi 断开重连 → 终端里的 `vim` 和 `claude` 全没了
- 手机热点信号抖动 → 刚跑了一半的测试结果丢失
- 下班关电脑，早上的上下文要全部重建

这些场景在本地开发中每天都在发生。**终端会话的持久性不是"锦上添花"，而是专业工作流的基本要求。**

K-Agent 的设计从第一天起就围绕这个理念：

```
本地模式                           K-Agent 模式
────────                           ────────────
终端进程在笔记本上                 终端进程在服务器上（tmux）
笔记本合盖 = 进程暂停/死亡         笔记本合盖 = 服务器继续运行
换设备 = 全新环境                  换设备 = 打开浏览器，看到同一个终端
网络断开 = 连接丢失                网络断开 = 重连后看到所有输出（缓冲回放）
关机 = 工作丢失                    关机 = 明天打开浏览器，tmux 还在，claude 还在
```

**关键机制：**
- **tmux 持久化**：每个 Terminal Tab 映射到一个服务端 tmux session，浏览器只是"观察窗口"。关闭 Tab、关闭浏览器、换设备——tmux 始终在服务器上运行
- **跨设备共享**：两个浏览器打开同一个 Terminal Tab，看到完全相同的实时内容——因为背后是同一个 tmux session
- **数据不丢失**：Tab 切换时 WebSocket 保持连接，非活跃 Tab 的输出缓冲在内存中，切回时一次性回放——你不会错过任何一行输出
- **重连即恢复**：网络断开重连后，自动重新 attach 到同一个 tmux session，无需手动操作

这就是 k_agent 相比本地运行 Claude Code 的核心价值——**你的工作窗口不再绑定到你的设备，而是存在于云端**。

## 流程

1. 阅读 `doc/v0.0.1/` 下的设计文档
2. 按 Phase 顺序实现功能（见 `doc/v0.0.1/architecture.md` → Implementation Phases）
3. 每个 Phase 完成后：`git add -A && git commit -m "feat(PN): ..." && git push`
4. 每个新增功能必须附带：
   - 功能设计文档（`doc/v0.0.1/<feature>.md`）
   - E2E 测试（`src/serv/tests/e2e/`）
5. 遇到无法自行解决的阻塞问题 → 记录到 `doc/block.md`
6. 返回步骤 1 继续

## 实现状态

| Phase | 状态 | 内容 |
|-------|------|------|
| P1 | ✅ | 项目骨架、Dockerfile（多阶段）、docker-compose、`src/serv` + `src/web` |
| P2 | ✅ | Auth：登录/登出、JWT、seed admin/admin123 |
| P3 | ✅ | 容器管理：docker-py 创建/启动/停止，每用户独立容器 |
| P4 | ✅ | Agent 配置 CRUD + Driver 接口（claude 默认，qwen/kimi 预留） |
| P5 | ✅ | 前端：Login、Dashboard、Workspace（双模式 Tab） |
| P6 | ✅ | 文档模式：上下文百分比、文件树、超阈值自动 /compress |
| P7 | ✅ | Shell 模式：xterm.js + tmux |
| P8 | ✅ | Admin 面板：用户管理 + 全局监控折线图 |
| P9 | ✅ | Token 统计：记录 + Recharts 折线图（hourly/daily） |
| P10 | ✅ | E2E：多轮对话记忆测试 |
| P11 | ✅ | 对话持久化 + 多会话管理 |
| P12 | ✅ | 文件操作：创建、编辑、删除工作区文件 |
| P13 | ✅ | 用户自助注册 |
| P14 | ✅ | 容器资源限制 + 空闲自动停止 |

## 平台状态

```
v0.9.2 | 452 commits | 40 tests | TSC clean | Ruff clean | Build ✓ | Playwright E2E
```

P1-P14 全部完成后，v0.9.x 新增：

| 类别 | 功能 |
|------|------|
| 协作 | 对话分享链接、系统广播公告 (WebSocket)、Prompt 片段库、工作区模板 |
| 实时 | WebSocket 通知推送、用量配额告警 (80%阈值)、通知历史页面 |
| 效率 | 全文消息搜索、批量操作 (worker/对话)、对话标签+固定、Worker 定时调度 |
| 安全 | 命令注入修复、Repo 凭证加密、密码强度验证、注册限流、安全响应头 |
| 性能 | Docker SDK 异步化、DB 索引优化、N+1 查询修复、get_summary 单查询聚合 |
| 管理 | CSV 用量导出、Worker 日志查看器、GraphQL 风格的 Activity Feed、Dashboard 预算仪表盘 |
| UX | Ctrl+Enter 发送、内联编辑替代 prompt()、会话重新生成、代码块 Apply to File、Sparkline 图表 |