client

Documentation

Index

• Constants
• Variables
• func FindProjectRoot(start string) string
• func GlobalConfigPath() (string, error)
• func LoadGlobalBaseURL() (string, error)
• func SaveConfig(root string, cfg *Config) error
• func SaveGlobalBaseURL(baseURL string) error
• func SaveState(root string, st *IndexState) error
• type Config
  • func LoadOrInit(root string) (*Config, error)
• type FailedBatch
• type FileEntry
  • func Scan(root string, opts ScanOptions) ([]FileEntry, error)
• type FileState
• type HTTP
  • func NewHTTP(baseURL string) *HTTP
  • func (h *HTTP) Clear(ctx context.Context, codebaseID string) error
  • func (h *HTTP) DeleteFiles(ctx context.Context, codebaseID string, paths []string) (int, error)
  • func (h *HTTP) Flush(ctx context.Context, codebaseID string) error
  • func (h *HTTP) Health(ctx context.Context) error
  • func (h *HTTP) List(ctx context.Context) ([]model.IndexInfo, error)
  • func (h *HTTP) Search(ctx context.Context, codebaseID, query string, topK int) ([]model.SearchResult, error)
  • func (h *HTTP) SearchText(ctx context.Context, codebaseID, query string, topK int) (string, error)
  • func (h *HTTP) Upsert(ctx context.Context, codebaseID string, files []model.PushFile) (*model.UpsertResult, error)
• type IndexState
  • func LoadState(root string) (*IndexState, error)
• type ScanOptions
• type SyncOptions
• type SyncReport
  • func Sync(ctx context.Context, root string, cfg *Config, opts SyncOptions) (*SyncReport, error)

Constants

const ConfigFile = "config.json"

ConfigFile 项目配置文件名

const HCEDir = ".hce"

HCEDir 项目内 hce 工作目录

const IndexFile = "index.json"

IndexFile 项目索引文件名

const MaxFileSize = 1024 * 1024

MaxFileSize 单文件大小上限（>1MB 跳过）

Variables

var DefaultExtensions = map[string]bool{
	".go": true, ".py": true, ".js": true, ".jsx": true, ".ts": true, ".tsx": true,
	".java": true, ".c": true, ".h": true, ".cpp": true, ".hpp": true, ".cc": true,
	".cs": true, ".rs": true, ".rb": true, ".php": true, ".swift": true, ".kt": true,
	".scala": true, ".lua": true, ".sh": true, ".bash": true, ".md": true,
}

DefaultExtensions 默认会被索引的源码扩展名

Functions

func FindProjectRoot

func FindProjectRoot(start string) string

FindProjectRoot 从 start 向上找到含 .hce/ 或 .git/ 的目录；都没有就返回 start。

func GlobalConfigPath

func GlobalConfigPath() (string, error)

GlobalConfigPath 返回每用户机器级配置路径 ~/.hce/config.json。 与项目级 .hce/config.json 同名不同位：项目级随项目走、可覆盖全局；全局级随用户走、做机器默认。

func LoadGlobalBaseURL

func LoadGlobalBaseURL() (string, error)

LoadGlobalBaseURL 读取全局配置里的 base_url；文件不存在返回空串且不报错。

func SaveConfig

func SaveConfig(root string, cfg *Config) error

SaveConfig 保存 .hce/config.json

func SaveGlobalBaseURL

func SaveGlobalBaseURL(baseURL string) error

SaveGlobalBaseURL 把 base_url 写入 ~/.hce/config.json（全局只用到 base_url，codebase_id 留空）。

func SaveState

func SaveState(root string, st *IndexState) error

SaveState 写回 .hce/index.json

Types

type Config

type Config struct {
	CodebaseID string `json:"codebase_id"`
	BaseURL    string `json:"base_url,omitempty"`
}

Config 项目级配置（落到 .hce/config.json）

func LoadOrInit

func LoadOrInit(root string) (*Config, error)

LoadOrInit 读取 .hce/config.json；不存在则在 root 下创建并返回。codebase_id 默认派生自 root 绝对路径。

type FailedBatch

type FailedBatch struct {
	Idx   int
	Files int
	Err   string
}

FailedBatch 单个失败 batch 的诊断信息

type FileEntry

type FileEntry struct {
	AbsPath      string
	RelativePath string
	Size         int64
	ModTime      time.Time
}

FileEntry 扫描得到的候选文件

func Scan

func Scan(root string, opts ScanOptions) ([]FileEntry, error)

Scan 遍历 root，返回符合条件的文件（统一用 forward-slash 相对路径，跨平台一致）

type FileState

type FileState struct {
	SHA256  string    `json:"sha256"`
	Size    int64     `json:"size"`
	ModTime time.Time `json:"mtime,omitempty"` // 用于秒级跳过 sha256：mtime+size 一致就认为内容未变
}

FileState 单文件状态

type HTTP

type HTTP struct {
	BaseURL string
	Client  *http.Client
}

HTTP HCE 服务端 HTTP 客户端

func NewHTTP

func NewHTTP(baseURL string) *HTTP

NewHTTP 用默认超时（5 分钟）创建客户端

func (*HTTP) Clear

func (h *HTTP) Clear(ctx context.Context, codebaseID string) error

Clear 清除整个 codebase

func (*HTTP) DeleteFiles

func (h *HTTP) DeleteFiles(ctx context.Context, codebaseID string, paths []string) (int, error)

DeleteFiles 删除指定相对路径

func (*HTTP) Flush

func (h *HTTP) Flush(ctx context.Context, codebaseID string) error

Flush 触发服务端落盘 growing segment（sync 完成时调一次）

func (*HTTP) Health

func (h *HTTP) Health(ctx context.Context) error

Health 检查服务可达

func (*HTTP) List

func (h *HTTP) List(ctx context.Context) ([]model.IndexInfo, error)

List 列出所有已索引的集合

func (*HTTP) Search

func (h *HTTP) Search(ctx context.Context, codebaseID, query string, topK int) ([]model.SearchResult, error)

Search 语义搜索（json 格式）

func (*HTTP) SearchText

func (h *HTTP) SearchText(ctx context.Context, codebaseID, query string, topK int) (string, error)

SearchText 直接拿到 text 格式的字符串（保留服务端的 path:line 排版）

func (*HTTP) Upsert

func (h *HTTP) Upsert(ctx context.Context, codebaseID string, files []model.PushFile) (*model.UpsertResult, error)

Upsert 推送一批文件

type IndexState

type IndexState struct {
	Version  int                  `json:"version"`
	Files    map[string]FileState `json:"files"`
	LastSync time.Time            `json:"last_sync,omitempty"`
}

IndexState 客户端索引状态：path → 文件 hash

func LoadState

func LoadState(root string) (*IndexState, error)

LoadState 读取 .hce/index.json；不存在返回空 state（不报错）

type ScanOptions

type ScanOptions struct {
	Extensions map[string]bool // nil 表示用默认
	MaxSize    int64           // 0 表示用默认
}

ScanOptions 扫描参数

type SyncOptions

type SyncOptions struct {
	BatchSize   int     // 单次 upsert 的最大文件数；默认 50
	BatchBytes  int64   // 单次 upsert 的最大累计字节；默认 5 MiB
	RPS         float64 // 每秒最多多少次 upsert 请求（避免 EMB 提供商 RPM 限流）；0 = 无限制
	TPM         int     // 每分钟最多多少 tokens（避免 EMB 提供商 TPM 限流）；0 = 无限制
	Concurrency int     // 并发上传的 worker 数；默认 4
	Progress    func(stage string, args ...any)
}

SyncOptions sync 控制参数

type SyncReport

type SyncReport struct {
	Scanned       int
	Added         int
	Modified      int
	Removed       int
	Unchanged     int
	UpsertResults []model.UpsertResult
	ChunksDeleted int
	FailedBatches []FailedBatch // 单批失败不中断整体；这里记录每个失败 batch 的诊断
	Duration      time.Duration
}

SyncReport sync 一次的统计

func Sync

func Sync(ctx context.Context, root string, cfg *Config, opts SyncOptions) (*SyncReport, error)

Sync 比较本地与 .hce/index.json，把新增/修改的文件推上去，删除已删除的；最后落盘 index.json。