docs(comments): 注释中文化 · internal/runtime/memory(31 文件,纯替换)
- 只翻注释/文档字符串:820 增 / 820 删 严格 1:1;剥掉整行注释与行尾注释尾巴后, 逐文件与 HEAD 比对「代码部分差异 = 0」;裁决/design 编号计数逐项与 HEAD 一致 - 保留可执行 SQL 样例、SQLite 报错原文、pgvector/HNSW/ANN/BLOB 等技术词原文 - 复核:go build 绿 + memory/projectindex/vector 三包测试绿;gofmt 仅剩 2 个既有未格式化文件(改动前即如此,未顺手修)
This commit is contained in:
1 parent
eb1828ee7a
commit
61cf80d5ee
31 files changed
+820
-820
No files matched your search
@@ -8,33 +8,33 @@ import (
|
||||
"time"
|
||||
)
|
||||
|
||||
// timeLayout is the fixed-width timestamp layout used for every stored
|
||||
// created_at/updated_at value. Unlike time.RFC3339Nano it never drops trailing
|
||||
// fractional zeros, so every value is exactly storedTimeLen bytes wide. SQLite
|
||||
// compares these TEXT columns as plain strings, and equal width is what makes
|
||||
// that comparison agree with chronological order. UTC values render the zone as
|
||||
// a single "Z".
|
||||
// timeLayout 是每个已存 created_at/updated_at 值使用的定宽
|
||||
// 时间戳布局。与 time.RFC3339Nano 不同,它从不丢弃末尾
|
||||
// 小数零,因此每个值恰好 storedTimeLen 字节宽。SQLite
|
||||
// 把这些 TEXT 列按普通字符串比较,而等宽正是让
|
||||
// 该比较与时间顺序一致的原因。UTC 值把时区渲染为
|
||||
// 单个 "Z"。
|
||||
const timeLayout = "2006-01-02T15:04:05.000000000Z07:00"
|
||||
|
||||
// storedTimeLen is the byte length of a UTC value formatted with timeLayout:
|
||||
// "2006-01-02T15:04:05.000000000Z" — the Z07:00 zone collapses to "Z" in UTC.
|
||||
// storedTimeLen 是用 timeLayout 格式化的 UTC 值的字节长度:
|
||||
// "2006-01-02T15:04:05.000000000Z" —— Z07:00 时区在 UTC 下坍缩为 "Z"。
|
||||
const storedTimeLen = 30
|
||||
|
||||
// memoryItemsTable is the table whose timestamps are normalized when the store
|
||||
// opens. It must match the DDL in store.go.
|
||||
// memoryItemsTable 是存储打开时需要规范化时间戳的表。
|
||||
// 它必须与 store.go 中的 DDL 一致。
|
||||
const memoryItemsTable = "memory_items"
|
||||
|
||||
// formatTime encodes t in UTC with the fixed-width timeLayout. Always writing
|
||||
// UTC keeps ordering and round-trips stable across processes, and the fixed
|
||||
// width is what lets ORDER BY created_at order these TEXT columns by time.
|
||||
// formatTime 用定宽 timeLayout 把 t 编码为 UTC。始终写
|
||||
// UTC 使排序与往返在各进程间保持稳定,而定宽
|
||||
// 正是 ORDER BY created_at 能按时间排序这些 TEXT 列的原因。
|
||||
func formatTime(t time.Time) string {
|
||||
return t.UTC().Format(timeLayout)
|
||||
}
|
||||
|
||||
// parseTime decodes a stored timestamp. time.RFC3339Nano accepts both the
|
||||
// fixed-width values this package writes and the legacy variable-width ones, so
|
||||
// the same parser serves reads and the open-time normalization. Blank input
|
||||
// yields a zero time.
|
||||
// parseTime 解码一个已存时间戳。time.RFC3339Nano 同时接受
|
||||
// 本包写入的定宽值与旧的变宽值,因此同一个解析器既服务
|
||||
// 读取、也服务打开时的规范化。空输入
|
||||
// 得到零值时间。
|
||||
func parseTime(s string) (time.Time, error) {
|
||||
if strings.TrimSpace(s) == "" {
|
||||
return time.Time{}, nil
|
||||
@@ -46,15 +46,15 @@ func parseTime(s string) (time.Time, error) {
|
||||
return t, nil
|
||||
}
|
||||
|
||||
// normalizeMemoryTimestamps rewrites every memory_items timestamp that is not
|
||||
// storedTimeLen bytes wide into the fixed-width timeLayout. Rows written before
|
||||
// the layout existed carry variable-width RFC3339Nano text whose string order
|
||||
// is not its time order; this brings them in line.
|
||||
// normalizeMemoryTimestamps 把每个非 storedTimeLen 字节宽的 memory_items
|
||||
// 时间戳重写为定宽 timeLayout。布局存在之前写入的行
|
||||
// 携带变宽 RFC3339Nano 文本,其字符串顺序
|
||||
// 并非时间顺序;这把它们拉齐。
|
||||
//
|
||||
// It is idempotent: only rows whose column length differs from storedTimeLen are
|
||||
// selected, so running it again on a normalized table is a no-op. A row whose
|
||||
// value does not parse is left exactly as it is — one bad legacy value must not
|
||||
// keep the store from opening.
|
||||
// 它是幂等的:只选取列长度与 storedTimeLen 不同的行,
|
||||
// 因此在已规范化的表上再跑一次是空操作。值解析不了的行
|
||||
// 原样保留 —— 一个坏的遗留值不该
|
||||
// 妨碍存储打开。
|
||||
func normalizeMemoryTimestamps(ctx context.Context, db *sql.DB) error {
|
||||
if err := normalizeTimeColumn(ctx, db, memoryItemsTable, "created_at"); err != nil {
|
||||
return err
|
||||
@@ -62,11 +62,11 @@ func normalizeMemoryTimestamps(ctx context.Context, db *sql.DB) error {
|
||||
return normalizeTimeColumn(ctx, db, memoryItemsTable, "updated_at")
|
||||
}
|
||||
|
||||
// normalizeTimeColumn rewrites every table.col value that is not storedTimeLen
|
||||
// bytes wide. table and col are compile-time constants, never user input, so
|
||||
// splicing them into the statement is safe; the length comparison and every
|
||||
// value written are parameterized. All rewrites are collected before any UPDATE
|
||||
// runs, so no write happens while the SELECT cursor is still open.
|
||||
// normalizeTimeColumn 重写 table.col 中每个非 storedTimeLen
|
||||
// 字节宽的值。table 与 col 是编译期常量,绝非用户输入,因此
|
||||
// 把它们拼进语句是安全的;长度比较与每个
|
||||
// 写入值都参数化。所有重写都在任何 UPDATE
|
||||
// 执行前收集完毕,因此 SELECT 游标仍打开时不会发生写入。
|
||||
func normalizeTimeColumn(ctx context.Context, db *sql.DB, table, col string) error {
|
||||
fixes, err := collectLegacyTimestamps(ctx, db, table, col)
|
||||
if err != nil {
|
||||
@@ -81,8 +81,8 @@ func normalizeTimeColumn(ctx context.Context, db *sql.DB, table, col string) err
|
||||
return nil
|
||||
}
|
||||
|
||||
// timeFix is one pending timestamp rewrite: which table and column, which row
|
||||
// (by primary key id), and the fixed-width value to write.
|
||||
// timeFix 是一条待执行的时间戳重写:哪张表哪一列、哪一行
|
||||
// (按主键 id),以及要写入的定宽值。
|
||||
type timeFix struct {
|
||||
table string
|
||||
col string
|
||||
@@ -90,10 +90,10 @@ type timeFix struct {
|
||||
value string
|
||||
}
|
||||
|
||||
// collectLegacyTimestamps reads the rows of table.col whose value is not
|
||||
// storedTimeLen bytes wide and returns the parseable ones as pending rewrites.
|
||||
// Unparseable values are skipped, so normalization can never fail a row: the
|
||||
// only errors are genuine read failures.
|
||||
// collectLegacyTimestamps 读取 table.col 中值非 storedTimeLen
|
||||
// 字节宽的行,把可解析的作为待重写项返回。
|
||||
// 不可解析的值跳过,因此规范化绝不会让某行失败:
|
||||
// 唯一的错误是真正的读取失败。
|
||||
func collectLegacyTimestamps(ctx context.Context, db *sql.DB, table, col string) ([]timeFix, error) {
|
||||
rows, err := db.QueryContext(ctx,
|
||||
"SELECT id, "+col+" FROM "+table+" WHERE length("+col+") != ?", storedTimeLen)
|
||||
@@ -120,9 +120,9 @@ func collectLegacyTimestamps(ctx context.Context, db *sql.DB, table, col string)
|
||||
return fixes, nil
|
||||
}
|
||||
|
||||
// reformatTime re-encodes raw with timeLayout. The bool is false when raw is
|
||||
// already storedTimeLen wide or when it does not parse, in which case the caller
|
||||
// leaves the stored value untouched.
|
||||
// reformatTime 用 timeLayout 重新编码 raw。raw 已经
|
||||
// storedTimeLen 宽、或无法解析时 bool 为 false,此时调用方
|
||||
// 保持存储值不动。
|
||||
func reformatTime(raw string) (string, bool) {
|
||||
if len(raw) == storedTimeLen {
|
||||
return "", false
|
||||
|
||||
Reference in new issue
Block a user