# Helmsman

**Repository Path**: to-doing/helmsman

## Basic Information

- **Project Name**: Helmsman
- **Description**: K8s 舰队的知识积累与智慧进化系统——有温度的运维伙伴。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Helmsman (星渡)

K8s 舰队的知识积累与智慧进化系统——有温度的运维伙伴。

## 定位

Helmsman 不是监控平台，不是控制中枢。它观察舰队的长期运行，积累实战知识，用 LLM 做高维推理，把经过验证的运维智慧传播给舰队操作员。

**三个"不"**：不侵入、不监控、不控制
**三个"要"**：要积累、要验证、要传播

## 快速开始

### 环境要求

- Go 1.25+
- Node.js 20+
- Python 3.11+

### 安装

```bash
# Go 后端
cd helmsman && go mod tidy && cd ..

# 前端
cd web && npm install && cd ..

# Python LLM 服务
cd ai && pip install -r requirements.txt
```

### 配置

```bash
# 编辑 helmsman/configs/helmsman.yaml，填入 kubeconfig 路径和 LLM API Key
```

### 启动

```bash
# Go 后端 (端口 8080)
cd helmsman && go run ./server

# 前端 (端口 3000)
cd web && npm run dev

# Python LLM 服务 (端口 8000)
cd ai && python server.py
```

或使用 Makefile：

```bash
make dev        # Go 后端
make web-dev    # 前端
make ai-run     # Python LLM
```

访问 http://localhost:3000

## 项目结构

```
helmsman/                — Go 后端（模块根）
  ├── server/main.go     — 入口
  ├── internal/
  │   ├── config/        — 配置管理
  │   ├── db/            — SQLite 数据库
  │   ├── cluster/       — 集群连接与注册
  │   ├── snapshot/      — 快照采集与存储
  │   └── api/           — HTTP API
  └── configs/           — 配置文件
web/                     — React 前端 (Vite + Ant Design)
ai/                      — Python LLM 服务 (FastAPI)
scripts/                 — 工具脚本（舰桥采集脚本）
docs/                    — 文档
```

## 数据获取模式

| 模式 | 场景 | 方式 |
|------|------|------|
| 试验场 | Helmsman 自有集群 | kubeconfig 常驻 |
| 靠港 | 外部集群临时可达 | kubeconfig 临时连接 |
| 报告 | 外部集群不可达 | 操作员上传数据包 |

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/clusters | 列出所有集群 |
| GET | /api/clusters/:id | 获取集群详情 |
| POST | /api/clusters | 注册集群 |
| POST | /api/clusters/:id/capture | 采集快照 |
| GET | /api/clusters/:id/snapshots | 集群快照列表 |
| GET | /api/clusters/:id/snapshots/latest | 最新快照 |
| GET | /api/stats | 全局统计 |

## 文档

- [战略架构](docs/strategy/01-strategic-vision.md)
- [命名定义](docs/strategy/02-naming.md)
- [演进路径](docs/strategy/03-evolution-roadmap.md)
- [整体架构](docs/architecture/01-overview.md)
- [试验场](docs/architecture/02-test-ground.md)
- [知识引擎](docs/architecture/03-knowledge-engine.md)
- [推理引擎](docs/architecture/04-reasoning-engine.md)
- [数据通道](docs/architecture/05-data-channel.md)
- [Web 界面](docs/architecture/06-web-interface.md)

## License

Internal use only.