archive

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package archive 把一个项目的「过程信息」(工作流、群聊、任务、确认项、用户追加、会话轮次、文档) 打成一个可以脱离 RelayMesh 保存、核对和(以后)重建的压缩包(#270)。

分层:

  • 本包只依赖 model 与标准库,不碰数据库:数据从 Source 接口分页取,渲染与打包是纯函数;
  • 实现 Source 的是 store.ArchiveSource(对着 SQLite 分页读,永不长时间占住唯一的库连接);
  • 路由与审计在 internal/api。

压缩包的契约(字段、文件名、排序、校验和)写在 docs/project-archive.md;这里的代码是它的唯一实现。

Index

Constants

View Source
const (
	TombWorkflow   = "workflow"
	TombGroup      = "group"
	TombTask       = "task"
	TombTaskModule = "task_module"
	TombConfirm    = "confirm"
	TombInbox      = "inbox"
	TombSession    = "session"
	TombDoc        = "doc"
)

墓碑(tombstones.jsonl)里的 kind:被删除的是哪一类记录。

View Source
const (
	IncludeWorkflows = "workflows"
	IncludeGroups    = "groups"
	IncludeTasks     = "tasks"
	IncludeConfirms  = "confirms"
	IncludeInbox     = "inbox"
	IncludeSessions  = "sessions"
	IncludeDocs      = "docs"
)

可以选择的内容类别(Options.Include / 清单 scope.include)。

workflows(以及 README.md、manifest.json)永远在包里:其他类别的记录都引用工作流,没有它们,包就无法单独阅读。 它出现在取值表里,是为了让调用方可以把「只要工作流清单」明确写出来(include=["workflows"])。

View Source
const (
	FormatName    = "relaymesh-project-archive"
	FormatVersion = 1
	// FormatVersionIncremental 是增量包的版本:它的文件只含相对某个基线新增 / 改动的记录,不能当完整包读,
	// 所以用不同的版本号——只认识版本 1 的读取器会直接拒绝它,而不是把一个残缺的包当成完整的。
	FormatVersionIncremental = 2
	// ModeIncremental 是清单 mode 字段在增量包里的取值;完整包没有这个字段。
	ModeIncremental = "incremental"
	// ManifestName 是压缩包里清单的路径;它写在最后,列出其余所有文件的校验和。
	ManifestName = "manifest.json"
)

压缩包格式的名字与版本。字段只增不改不删;要做不兼容的改动时升 FormatVersion。

View Source
const (
	BaselineFull        = "full"
	BaselineIncremental = "incremental"
)

基线的种类。

View Source
const (
	KindData     = "data"     // jsonl 数据文件:机器读的权威内容
	KindMarkdown = "markdown" // 给人读的渲染
	KindDoc      = "doc"      // docs/ 下的项目文档
	KindReadme   = "readme"
)

文件的种类,写进 manifest 方便按类过滤。

View Source
const (
	ViaDirectory = "directory" // 最近一条带目录的会话落在项目登记的目录里
	ViaBranch    = "branch"    // 自己的目录不在项目里,但与项目里的工作流有主会话 / 分支关系
)

工作流进入导出范围的原因。

View Source
const (
	RoleMain   = "main"
	RoleBranch = "branch"
	RoleNone   = "none"
)

工作流在分支关系里的角色。

View Source
const BaselineVersion = 1

BaselineVersion 是基线摘要编码的版本。

View Source
const OpReplace = "replace"

OpReplace 是 FileEntry.Op 的取值:整份替换。

View Source
const TombstonesName = "tombstones.jsonl"

TombstonesName 是增量包里删除清单的路径。

Variables

AllIncludes 是全部类别,按它们在包里出现的固定顺序。

View Source
var ErrBaselineMismatch = fmt.Errorf("%w:基线与这次导出的范围不一致", ErrInvalidOptions)

ErrBaselineMismatch 表示基线与这次导出的范围对不上(选项不一致或基线损坏)。

View Source
var ErrBaselineVersion = errors.New("archive: 基线摘要的编码版本不认识")

ErrBaselineVersion 表示基线是别的版本的编码,读不了。

View Source
var ErrInvalidOptions = errors.New("archive: 导出参数不合法")

ErrInvalidOptions 表示导出参数不合法。

View Source
var ErrMerge = errors.New("archive: 合并失败")

ErrMerge 是合并失败的统一前缀:包链对不上、数据不自洽、或来自更新版本的 RelayMesh。

View Source
var ExcludedScope = []string{
	"图片原文件(记录里只有名字、格式、哈希与尺寸)",
	"群消息的 @ 投递记录(chat_mention 收件箱行)",
	"终端与执行日志",
	"凭据、令牌与系统设置(任何时候都不导出)",
}

ExcludedScope 写进清单,让读压缩包的人一眼看到「这个版本没有包含什么」。

Functions

func EffectiveInclude

func EffectiveInclude(normalized []string) []string

EffectiveInclude 返回一次导出实际包含的类别(nil = 全部,也就是 AllIncludes)。

func NormalizeInclude

func NormalizeInclude(in []string) ([]string, error)

NormalizeInclude 校验并规整 include 参数。

  • 空(nil / 空切片)= 全部类别,返回 nil;
  • 含未知类别 → ErrInvalidOptions(列出可用的取值);
  • 去重、按固定顺序排列,并补上总是在包里的 workflows;
  • 规整之后等于全部类别时同样返回 nil:「全选」与「不选」导出的是同一个包,清单里也不写 scope.include, 所以不带 include 的旧调用方拿到的字节与以前完全相同。

func OpenPackage

func OpenPackage(path string) (*Package, []Problem, error)

OpenPackage 打开一个压缩包(zip 文件或目录)并核对它。返回的问题清单为空才说明包是完整的; 即使有问题,清单读得出来时也会返回 Package(方便把「是哪个包、出了什么问题」说清楚)。 打不开(文件不存在等)返回 error。调用方负责 Close。

func SafeStem

func SafeStem(id string) string

namer 把群 / 工作流编号变成压缩包里的文件名主干:只留 [A-Za-z0-9._-],其余字符换成 -(grp:3d18931d → grp-3d18931d)。 两个不同编号落到同一个名字时(不区分大小写),后来的在结尾补上自己编号 SHA-256 的前 8 位; 调用方按编号升序依次取名,所以同样的输入总得到同样的文件名。 SafeStem 把任意标识(工作流编号等)变成可以当目录名 / 文件名主干的一段,不依赖任何已分配的状态: 不安全的字符换成 -,只要发生过替换或被截断,就附上原值哈希的前 8 位——所以不同的输入不会得到同一个结果, 同一个输入永远得到同一个结果。

func Verify

func Verify(r io.ReaderAt, size int64) (*Manifest, []Problem)

Verify 核对一个压缩包:清单存在且格式对、清单列出的每个文件都在、SHA-256 / 字节数 / jsonl 记录数都对得上、 包里没有清单没列出的文件、各类记录数与 counts 一致。返回清单(读得出来时)和问题清单;没有问题 = 包是完整的。

它是「导出」的对偶:测试用它证明导出自洽,以后的 import-archive 也要先过它。 增量包(格式版本 2)按它自己的规则核对:文件里的记录数对 delta,而不是对 counts(counts 是整个项目的状态)。

Types

type BasedOn

type BasedOn struct {
	BaselineID     string `json:"baseline_id"`
	ManifestSHA256 string `json:"manifest_sha256"`
}

BasedOn 说明增量包基于哪个包:基线编号,以及那个包的 manifest.json 的 SHA-256。离线按它把包串成链。

type Baseline

type Baseline struct {
	Version int `json:"version"`
	// Include 是这个基线的范围(规整后;nil = 全部类别)。增量导出沿用它。
	Include   []string  `json:"include,omitempty"`
	Watermark Watermark `json:"watermark"`
	// Sets 按集合名存(键,摘要),顺序就是导出时的写出顺序(会话集合靠它判断顺序有没有被打乱)。
	Sets   map[string][]KeyDigest `json:"sets"`
	Groups map[string]GroupMark   `json:"groups,omitempty"`
}

Baseline 是一次导出登记的摘要:那一刻项目里每类可变记录的(键 → 摘要),以及群消息的水位。 不含任何正文;它只回答「这条记录自那以后变没变」。

func DecodeBaseline

func DecodeBaseline(data []byte) (*Baseline, error)

DecodeBaseline 是 Encode 的逆。

func (*Baseline) Encode

func (b *Baseline) Encode() ([]byte, error)

Encode 把基线编成可以存进数据库的字节:JSON 再 gzip。

func (*Baseline) Records

func (b *Baseline) Records() int

Records 是基线里登记的记录总数(给状态展示用)。

type BaselineRef

type BaselineRef struct {
	ID     string `json:"id"`
	Kind   string `json:"kind"`
	Parent string `json:"parent,omitempty"`
}

BaselineRef 是一次导出登记的基线:编号、种类(完整 / 增量)、增量时它基于的基线。

type BranchRecord

type BranchRecord struct {
	Parent        string             `json:"parent"`
	CreatedBy     string             `json:"created_by"`
	Status        string             `json:"status"`
	Expose        model.BranchExpose `json:"expose"`
	CopyUserNotes bool               `json:"copy_user_notes"`
	CreatedAt     string             `json:"created_at"`
	ClosedAt      string             `json:"closed_at,omitempty"`
}

BranchRecord 是分支对主会话的关系。

type ChainItem

type ChainItem struct {
	Name           string
	Manifest       *Manifest
	ManifestSHA256 string
}

ChainItem 是链上的一个包(已经单包校验过)。

type ConfirmAnswerRecord

type ConfirmAnswerRecord struct {
	Options []string `json:"options"`
	Note    string   `json:"note,omitempty"`
	Custom  string   `json:"custom,omitempty"`
	By      string   `json:"by"`
}

ConfirmAnswerRecord 是确认项的答复:选了哪些选项、备注、自定义答复、谁签的字。

type ConfirmRecord

type ConfirmRecord struct {
	Workflow      string                   `json:"workflow"`
	Seq           int                      `json:"seq"`
	Ref           string                   `json:"ref"`
	ID            uint                     `json:"id"`
	Kind          string                   `json:"kind"`
	Title         string                   `json:"title"`
	Body          string                   `json:"body,omitempty"`
	Options       []model.ConfirmOption    `json:"options"`
	Multi         bool                     `json:"multi"`
	AllowNote     bool                     `json:"allow_note"`
	DefaultOption string                   `json:"default_option,omitempty"`
	Risk          string                   `json:"risk"`
	Status        string                   `json:"status"`
	Answer        *ConfirmAnswerRecord     `json:"answer,omitempty"`
	AnsweredAt    string                   `json:"answered_at,omitempty"`
	TaskSeq       int                      `json:"task_seq,omitempty"`
	DocKey        string                   `json:"doc_key,omitempty"`
	Anchor        string                   `json:"anchor,omitempty"`
	CreatedBy     string                   `json:"created_by"`
	CreatedAt     string                   `json:"created_at"`
	UpdatedAt     string                   `json:"updated_at"`
	Addressee     string                   `json:"addressee,omitempty"`
	EscalatedAt   string                   `json:"escalated_at,omitempty"`
	Escalation    *model.ConfirmEscalation `json:"escalation,omitempty"`
}

ConfirmRecord 是 confirms.jsonl 的一行。

type Counts

type Counts struct {
	Workflows     int `json:"workflows"`
	Groups        int `json:"groups"`
	GroupMessages int `json:"group_messages"`
	Tasks         int `json:"tasks"`
	TaskModules   int `json:"task_modules"`
	Confirms      int `json:"confirms"`
	Inbox         int `json:"inbox"`
	Sessions      int `json:"sessions"`
	Docs          int `json:"docs"`
}

Counts 是各类记录的条数,应与对应 jsonl 的记录数一致。

type DeltaCount

type DeltaCount struct {
	Added   int `json:"added"`
	Changed int `json:"changed"`
	Deleted int `json:"deleted"`
}

DeltaCount 是一类记录相对基线的变化条数。Changed 包含「整份重发」的文件里没变的记录, 所以 Added + Changed 恒等于这一类 delta 文件里的记录总数。

type DeltaSet

type DeltaSet map[string]DeltaCount

DeltaSet 按类别汇总增量包的变化条数。类别名:workflows、groups、group_messages、tasks、task_modules、confirms、inbox、sessions、docs。

type DirInfo

type DirInfo struct {
	Host string
	Path string
}

DirInfo 是项目登记的一个(主机,目录)。

type DocFile

type DocFile struct {
	Path      string // 压缩包内 docs/ 之后的相对路径,已规整
	Content   []byte
	Generated bool
}

DocFile 是 docs/ 下的一个文件(正文已含决策结果表)。Generated 为真的是导出时生成的目录文件(INDEX),不算项目文档。

type DocRename

type DocRename struct {
	From string `json:"from"`
	To   string `json:"to"`
}

DocRename 记一次文档改名:From 是文档在项目里的原路径,To 是它在 docs/ 下的实际路径(不含 docs/ 前缀)。

type FileEntry

type FileEntry struct {
	Path    string `json:"path"`
	SHA256  string `json:"sha256"`
	Bytes   int64  `json:"bytes"`
	Records int    `json:"records,omitempty"`
	Kind    string `json:"kind"`
	// Subject 与 Op 只在增量包里出现。Subject 是这个文件属于哪个群 / 工作流(文件名只是个主干,不能反推编号);
	// Op 为 "replace" 表示这个文件要整份替换基线里的同一主体的文件,而不是在它后面追加 / 按键合并。
	Subject string `json:"subject,omitempty"`
	Op      string `json:"op,omitempty"`
}

FileEntry 是 manifest.json 里的一个文件:路径、内容的 SHA-256、字节数、记录数(jsonl 才有)。

type GroupExported

type GroupExported struct {
	File         string `json:"file"`
	MarkdownFile string `json:"markdown_file"`
	AfterSeq     int64  `json:"after_seq"`
	FromSeq      int64  `json:"from_seq,omitempty"`
	ToSeq        int64  `json:"to_seq,omitempty"`
	Count        int    `json:"count"`
	FirstID      string `json:"first_id,omitempty"`
	LastID       string `json:"last_id,omitempty"`
	FirstAt      string `json:"first_at,omitempty"`
	LastAt       string `json:"last_at,omitempty"`
}

GroupExported 说明这次导出了这个群的哪一段消息,调用方据此续导(after_seq = ToSeq)。

type GroupInfo

type GroupInfo struct {
	model.Conversation
	Members []GroupMember
}

GroupInfo 是范围内的一个群:绑定了本项目,或有范围内的工作流做过成员。

type GroupMark

type GroupMark struct {
	// Upto 是导出那一刻的水位(群里最大的 seq);下次增量从它之后读。
	Upto  int64 `json:"upto"`
	Count int   `json:"count"`
	// 下面是已导出消息的首条 / 末条(清单 id_ranges 要用,增量时不重读旧消息就能给出整个群的区间)。
	FirstSeq int64  `json:"first_seq,omitempty"`
	FirstID  string `json:"first_id,omitempty"`
	FirstAt  string `json:"first_at,omitempty"`
	LastSeq  int64  `json:"last_seq,omitempty"`
	LastID   string `json:"last_id,omitempty"`
	LastAt   string `json:"last_at,omitempty"`
}

GroupMark 是一个群的消息在基线那一刻的状态。群消息只追加、不改不删,所以只记水位与条数: 下次从 Upto 之后接着读;基线之前的消息条数对不上(将来出现删除)就整份重发。

type GroupMember

type GroupMember struct {
	model.ConversationMember
	Name string
}

GroupMember 是群成员加上界面上显示的名字(名字取工作流的显示标题)。

type GroupMemberRecord

type GroupMemberRecord struct {
	Kind       string `json:"kind"`
	Ref        string `json:"ref"`
	Name       string `json:"name,omitempty"`
	Role       string `json:"role"`
	AddedBy    string `json:"added_by,omitempty"`
	JoinedAt   string `json:"joined_at"`
	LeftAt     string `json:"left_at,omitempty"`
	PushPolicy string `json:"push_policy,omitempty"`
}

GroupMemberRecord 是群成员。

type GroupMessageRecord

type GroupMessageRecord struct {
	Group    string       `json:"group"`
	ID       string       `json:"id"`
	Seq      int64        `json:"seq"`
	At       string       `json:"at"`
	Sender   SenderRecord `json:"sender"`
	Kind     string       `json:"kind"`
	Text     string       `json:"text"`
	Mentions []string     `json:"mentions,omitempty"`
	ReplyTo  string       `json:"reply_to,omitempty"`
}

GroupMessageRecord 是 groups/<群>.jsonl 的一行。每行都带群编号,所以单独拿出一行也能看懂; 文件里只有消息、没有表头,因此「旧文件 + 续导的文件 = 全量文件」。

type GroupRecord

type GroupRecord struct {
	Group      string              `json:"group"`
	Title      string              `json:"title"`
	Kind       string              `json:"kind"`
	ProjectID  string              `json:"project_id,omitempty"`
	CreatedBy  string              `json:"created_by,omitempty"`
	CreatedAt  string              `json:"created_at"`
	ArchivedAt string              `json:"archived_at,omitempty"`
	Members    []GroupMemberRecord `json:"members"`
	LastSeq    int64               `json:"last_seq"`
	Exported   GroupExported       `json:"exported"`
}

GroupRecord 是 groups.jsonl 的一行。

type GroupSummary

type GroupSummary struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	LastSeq int64  `json:"last_seq"`
	// Messages = last_seq - after_seq:群消息的 seq 是连续的(含系统行),所以它就是这次会写出的条数;读不到的极端情况下以导出后清单里的 counts 为准。
	Messages int64 `json:"messages"`
	Members  int   `json:"members"`
}

GroupSummary 是 Summary 里的一个群:id 与水位(last_seq)是续导要用的,messages 是这次会导出的消息数(见 Summary 的说明)。

type IDRange

type IDRange struct {
	First uint `json:"first"`
	Last  uint `json:"last"`
}

IDRange 是一类记录的编号区间。

type IDRanges

type IDRanges struct {
	Inbox         *IDRange            `json:"inbox,omitempty"`
	Confirms      *IDRange            `json:"confirms,omitempty"`
	Tasks         *IDRange            `json:"tasks,omitempty"`
	GroupMessages map[string]SeqRange `json:"group_messages"`
}

IDRanges 汇总各类记录的编号区间,方便与库里的最大编号对账。

type ImageRecord

type ImageRecord struct {
	Name   string `json:"name,omitempty"`
	Format string `json:"format,omitempty"`
	Hash   string `json:"hash,omitempty"`
	Width  int    `json:"width,omitempty"`
	Height int    `json:"height,omitempty"`
}

ImageRecord 只记图片的元数据;图片本体不进压缩包(见 docs/project-archive.md 的「不在范围内」)。

type InboxRecord

type InboxRecord struct {
	ID           uint          `json:"id"`
	Ref          string        `json:"ref"`
	Workflow     string        `json:"workflow"`
	At           string        `json:"at"`
	Kind         string        `json:"kind"`
	State        string        `json:"state"`
	Text         string        `json:"text"`
	Messages     []string      `json:"messages,omitempty"`
	Images       []ImageRecord `json:"images,omitempty"`
	OriginRef    string        `json:"origin_ref,omitempty"`
	Sender       string        `json:"sender,omitempty"`
	Actor        string        `json:"actor,omitempty"`
	DeliveredAt  string        `json:"delivered_at,omitempty"`
	DeliveredVia string        `json:"delivered_via,omitempty"`
	AckedAt      string        `json:"acked_at,omitempty"`
	RetractedAt  string        `json:"retracted_at,omitempty"`
}

InboxRecord 是 inbox-user.jsonl 的一行:一条用户(或被抄送 / 路由进来的)追加。ref 是界面上的「追加 #N」。

type Key

type Key []string

Key 是一条记录在它那一类里的身份。全是字符串(序号写成十进制),整体编成 JSON 数组,所以不会有分隔符歧义。

func (Key) String

func (k Key) String() string

String 是键的规范写法(基线里存的就是它)。

type KeyDigest

type KeyDigest struct {
	Key string
	Sum [sha256.Size]byte
}

KeyDigest 是一条记录的(键,摘要)。摘要 = 完整包里那一行 JSON 的 SHA-256(见方案文档的 I1)。

func (KeyDigest) MarshalJSON

func (d KeyDigest) MarshalJSON() ([]byte, error)

MarshalJSON 编成 ["键","十六进制摘要"],比对象紧凑。

func (*KeyDigest) UnmarshalJSON

func (d *KeyDigest) UnmarshalJSON(b []byte) error

type Manifest

type Manifest struct {
	Format        string          `json:"format"`
	FormatVersion int             `json:"format_version"`
	ExportedAt    string          `json:"exported_at"`
	HubVersion    string          `json:"hub_version,omitempty"`
	Project       ManifestProject `json:"project"`
	Scope         ManifestScope   `json:"scope"`
	Watermark     Watermark       `json:"watermark"`
	Counts        Counts          `json:"counts"`
	IDRanges      IDRanges        `json:"id_ranges"`
	// DocRenames 只在有文档因为路径只差大小写(在不分大小写的文件系统上解压会互相覆盖)而被改名时出现。
	DocRenames []DocRename `json:"doc_renames,omitempty"`
	Files      []FileEntry `json:"files"`
	Excluded   []string    `json:"excluded"`

	// 下面几项只在「登记了基线」的导出(用令牌导出)或增量包 / 合并结果里出现;网页导出的清单没有它们,字节与以前相同。
	//
	// Mode 只在增量包里是 "incremental"。增量包的 counts / id_ranges / watermark 与完整包同义:
	// 是「导出那一刻整个项目」的状态,而不是这个包里的文件条数——文件里有什么看 Delta 与 files[].records。
	Mode string `json:"mode,omitempty"`
	// Baseline 是这次导出登记的基线(之后可以用它的编号做增量的起点)。
	Baseline *BaselineRef `json:"baseline,omitempty"`
	// BasedOn 与 Before 只在增量包里:基于哪个基线 / 哪个包,以及那一刻的水位。
	BasedOn *BasedOn   `json:"based_on,omitempty"`
	Before  *Watermark `json:"before,omitempty"`
	// Delta 只在增量包里:各类记录相对基线新增、改动、删除了多少条。
	Delta *DeltaSet `json:"delta,omitempty"`
	// MergedFrom 只在离线合并的结果里:它是由哪些包按什么顺序合出来的。
	MergedFrom []MergedFrom `json:"merged_from,omitempty"`
}

Manifest 是 manifest.json。除 exported_at 与 hub_version 外,同样的数据得到同样的内容。

func Export

func Export(ctx context.Context, src Source, opts Options, w io.Writer) (*Manifest, error)

Export 是 Prepare + Write 的合体,给不需要「先校验再开写」的调用方(测试、命令行)。

func (*Manifest) Marshal

func (m *Manifest) Marshal() ([]byte, error)

Marshal 是清单写进压缩包(manifest.json)的字节:固定缩进、末尾换行;map 的键有序,所以同一份清单总是得到同样的字节。

func (*Manifest) SHA256

func (m *Manifest) SHA256() (string, error)

SHA256 是 manifest.json 的 SHA-256(十六进制)。清单里有每个数据文件的校验和,所以这一个值就能证明整个包没有被改过; 定时备份的脚本把它与下载完成后自己算的值核对即可。

type ManifestDir

type ManifestDir struct {
	Host string `json:"host"`
	Path string `json:"path"`
}

ManifestDir 是项目登记的一个(主机,目录)。

type ManifestProject

type ManifestProject struct {
	ID          uint          `json:"id"`
	Slug        string        `json:"slug"`
	Name        string        `json:"name"`
	Description string        `json:"description,omitempty"`
	Dirs        []ManifestDir `json:"dirs"`
	CreatedAt   string        `json:"created_at"`
	ArchivedAt  string        `json:"archived_at,omitempty"`
}

ManifestProject 是被导出的项目。

type ManifestScope

type ManifestScope struct {
	AfterSeq int64    `json:"after_seq"`
	Groups   []string `json:"groups"` // 空 = 范围内的全部群
	// Include 只在「部分类别」的导出里出现(规整后的类别,固定顺序,含总是在包里的 workflows);没有它 = 全部类别。
	Include []string `json:"include,omitempty"`
}

ManifestScope 记下这次导出的取舍,续导时照着它接。

type MergeReport

type MergeReport struct {
	Manifest *Manifest
	Packages int
	Files    int
	Bytes    int64
}

MergeReport 是合并的结果摘要。

func Merge

func Merge(pkgs []*Package, outDir string) (*MergeReport, error)

Merge 把 pkgs(第一个是完整包,其后依次是增量包)合并到 outDir。调用方先用 OpenPackage 打开并确认各包自身没有问题。

type MergedFrom

type MergedFrom struct {
	Mode           string `json:"mode"`
	ManifestSHA256 string `json:"manifest_sha256"`
	ExportedAt     string `json:"exported_at"`
}

MergedFrom 记合并结果来自的一个包。

type MessageCounter

type MessageCounter interface {
	GroupMessageCount(ctx context.Context, groupID string, uptoSeq int64) (int, error)
}

MessageCounter 是 Source 可以选择实现的接口:数出群里 seq <= uptoSeq 的消息条数。 增量导出用它确认「基线之前的消息还原样在」;没实现就只比较水位。

type Options

type Options struct {
	// Now 是写进清单的导出时刻(测试里固定它);零值取当前时间。
	Now        time.Time
	HubVersion string
	// AfterSeq 只导 seq 大于它的群消息(续导用:上次清单里该群的 exported.to_seq / watermark);0 = 从头。
	// seq 是每个群各自的序号(各从 1 起),所以一个数字只对一个群有意义:AfterSeq > 0 时必须用 Groups 指明是哪些群,
	// 否则同一个数字会被套在所有群上,序号较小的群会被悄悄漏掉消息。
	AfterSeq int64
	// Groups 非空时只导这些群;空 = 范围内的全部群(此时只能从头导,不能续导)。
	Groups   []string
	PageSize int
	// Include 只导这些类别(取值见 AllIncludes;workflows 总是会在包里)。空 = 全部类别。
	// 不含 groups 时不能再指定 Groups / AfterSeq(它们只对群消息有意义,悄悄忽略会让调用方以为续导成功了)。
	Include []string
	// Docs 取项目文档(含生成的目录文件);nil = 包里没有 docs/。
	Docs func(ctx context.Context) ([]DocFile, error)
	// DocsCount 只数文档的篇数(不读正文),给 Summary 用;nil = Summary 里的文档数记 0。
	DocsCount func(ctx context.Context) (int, error)

	// Since 非 nil = 增量导出:只写相对这个基线新增 / 改动的记录、删除清单、群里新增的消息与有变化的文档。
	// 范围(Include)由基线决定,所以不能再指定 Include / Groups / AfterSeq。
	Since *Since
	// NewBaselineID 非空 = 这次导出要登记一个新基线(清单里写 baseline 一项);摘要在清单写出之前交给 OnBaseline。
	// 登记的基线必须覆盖整个范围,所以不能与 Groups / AfterSeq 同用。
	NewBaselineID string
	// OnBaseline 在最后一个数据文件写完、清单还没写出时被调用:manifestSHA256 是即将写出的 manifest.json 的 SHA-256。
	// 它返回错误就中止整个导出——这样「包里有基线编号」就一定意味着「基线已经登记」。
	OnBaseline func(b *Baseline, manifestSHA256 string) error
}

Options 控制一次导出。

type Package

type Package struct {
	Path string
	// Manifest 与 ManifestRaw 在清单读得出来时才有;ManifestSHA256 是 manifest.json 原始字节的 SHA-256。
	Manifest       *Manifest
	ManifestRaw    []byte
	ManifestSHA256 string
	// contains filtered or unexported fields
}

Package 是一个读进来的压缩包:zip 文件,或者解开 / 合并出来的目录。

func (*Package) Close

func (p *Package) Close() error

Close 释放底层文件。

func (*Package) Names

func (p *Package) Names() []string

Names 是包里的文件名(不含目录)。

func (*Package) Read

func (p *Package) Read(name string) ([]byte, error)

Read 读包里的一个文件。

type Plan

type Plan struct {
	// contains filtered or unexported fields
}

Plan 是准备好的一次导出:范围已经确定、水位已经取好。Prepare 只做小查询, 能在写出第一个字节之前把「群不存在」这类错误报给调用方;真正的大数据在 Write 里分页流式写出。

func Prepare

func Prepare(ctx context.Context, src Source, opts Options) (*Plan, error)

Prepare 确定导出范围并取水位。

func (*Plan) Project

func (p *Plan) Project() ProjectInfo

Project 返回被导出的项目。

func (*Plan) Summary

func (p *Plan) Summary(ctx context.Context) (*Summary, error)

Summary 只读地描述这次导出:包含的类别、各类记录的条数、各群的水位。它读的数据比真正导出少得多 (群消息与会话只数条数,文档只数篇数),能放心地反复调用。

func (*Plan) Write

func (p *Plan) Write(ctx context.Context, w io.Writer) (*Manifest, error)

Write 把压缩包写到 w:各数据文件依次写出,清单(带全部校验和)最后写。出错时返回错误, 此时 zip 没有写完(缺少中央目录与清单),任何解压工具都会报它损坏,不会被当成完整的包。

type Problem

type Problem struct {
	Path   string `json:"path,omitempty"`
	Reason string `json:"reason"`
}

Problem 是核对压缩包时发现的一个问题。

func VerifyChain

func VerifyChain(items []ChainItem) []Problem

VerifyChain 核对一串包能不能接成一条链:第一个必须是完整包,其后每个必须是增量包,并且 每个增量包基于它前面那一个(基线编号与 manifest SHA-256 对得上、before 水位等于前一个包的水位), 项目与范围不变、导出时刻不倒退。包少一环、顺序错、被换成别的包,这里都会报出来。

func (Problem) String

func (p Problem) String() string

type ProjectInfo

type ProjectInfo struct {
	ID          uint
	Slug        string
	Name        string
	Description string
	CreatedAt   time.Time
	ArchivedAt  *time.Time
	Dirs        []DirInfo
}

ProjectInfo 是被导出的项目本身。

type SenderRecord

type SenderRecord struct {
	Kind string `json:"kind"`
	Ref  string `json:"ref,omitempty"`
	Name string `json:"name,omitempty"`
}

SenderRecord 是群消息的发送者。

type SeqRange

type SeqRange struct {
	FirstSeq int64  `json:"first_seq"`
	LastSeq  int64  `json:"last_seq"`
	FirstID  string `json:"first_id"`
	LastID   string `json:"last_id"`
}

SeqRange 是一个群里导出的消息区间。

type SessionRecord

type SessionRecord struct {
	Workflow   string        `json:"workflow"`
	Session    string        `json:"session"`
	At         string        `json:"at"`
	Kind       string        `json:"kind,omitempty"`
	Status     string        `json:"status"`
	Title      string        `json:"title,omitempty"`
	Host       string        `json:"host,omitempty"`
	Directory  string        `json:"directory,omitempty"`
	Report     string        `json:"report"`
	Reply      string        `json:"reply,omitempty"`
	ReplyAt    string        `json:"reply_at,omitempty"`
	Messages   []string      `json:"messages,omitempty"`
	Images     []ImageRecord `json:"images,omitempty"`
	GitCommit  string        `json:"git_commit,omitempty"`
	GitSubject string        `json:"git_subject,omitempty"`
	ConsumedAt string        `json:"consumed_at,omitempty"`
	UpdatedAt  string        `json:"updated_at"`
}

SessionRecord 是 sessions/<工作流>.jsonl 的一行:智能体的一次汇报,加上用户对它的答复。

type SessionRow

type SessionRow struct {
	RowID int64
	model.FeedbackSession
}

SessionRow 是一行会话轮次:RowID 是库里的追加序(分页游标),Images 已去掉图片本体(只剩名字 / 哈希 / 尺寸)。

type Since

type Since struct {
	// BaselineID 与 ManifestSHA256 写进增量包的 based_on:它们标识「上一个包」。
	BaselineID     string
	ManifestSHA256 string
	Baseline       *Baseline
}

Since 是增量导出的起点:一个已经登记的基线。

type Source

type Source interface {
	Project() ProjectInfo
	Workflows(ctx context.Context) ([]WorkflowInfo, error)
	Groups(ctx context.Context) ([]GroupInfo, error)
	// GroupLastSeq 是群里当前最大的消息序号(没有消息 = 0);导出开始时取一次,作为这次导出的水位。
	GroupLastSeq(ctx context.Context, groupID string) (int64, error)
	// GroupMessages 取 afterSeq < seq <= uptoSeq 的消息,按 seq 升序,最多 limit 条;含系统行,不做成员可见性裁剪。
	GroupMessages(ctx context.Context, groupID string, afterSeq, uptoSeq int64, limit int) ([]model.ChatMessage, error)
	Tasks(ctx context.Context) (*TaskSet, error)
	// Confirms 返回范围内全部确认项,按(工作流,序号)升序。
	Confirms(ctx context.Context) ([]model.ConfirmItem, error)
	// InboxIDs 返回范围内全部「用户追加」行的编号(升序,排除群消息投递 chat_mention);InboxRows 按编号取行(图片只剩元数据)。
	InboxIDs(ctx context.Context) ([]uint, error)
	InboxRows(ctx context.Context, ids []uint) ([]model.QueuedFeedback, error)
	// SessionsMaxRowID 是会话轮次的当前最大追加序(水位);Sessions 取一个工作流 afterRowID < rowid <= uptoRowID 的行,升序,最多 limit 行。
	SessionsMaxRowID(ctx context.Context) (int64, error)
	Sessions(ctx context.Context, workflowID string, afterRowID, uptoRowID int64, limit int) ([]SessionRow, error)
}

Source 是导出要读的数据。所有方法都要能在 ctx 取消时尽快返回;分页方法每次只拿一页,不得在返回后还占着数据库连接。

type Summary

type Summary struct {
	Format        string          `json:"format"`
	FormatVersion int             `json:"format_version"`
	Project       SummaryProject  `json:"project"`
	Include       []string        `json:"include"`
	Scope         ManifestScope   `json:"scope"`
	Counts        Counts          `json:"counts"`
	Watermark     Watermark       `json:"watermark"`
	Groups        []GroupSummary  `json:"groups"`
	Excluded      []string        `json:"excluded"`
	Workflows     []WorkflowBrief `json:"workflows"`
}

Summary 是一次导出「会包含什么」的只读预览:不写任何文件、不读正文,只数条数、取水位。 数字是此刻的快照——真正导出时水位以那一刻为准,写进清单。

type SummaryProject

type SummaryProject struct {
	ID   uint   `json:"id"`
	Slug string `json:"slug"`
	Name string `json:"name"`
}

SummaryProject 是预览里的项目(只有身份,不带登记的目录)。

type TaskModuleRecord

type TaskModuleRecord struct {
	Board       string `json:"board"`
	Path        string `json:"path"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Depth       int    `json:"depth"`
	Sort        int    `json:"sort"`
	Workflow    string `json:"workflow,omitempty"`
	CreatedAt   string `json:"created_at"`
}

TaskModuleRecord 是 task-modules.jsonl 的一行(任务板的规划树:模块与功能)。

type TaskRecord

type TaskRecord struct {
	Board       string             `json:"board"`
	Seq         int                `json:"seq"`
	Ref         string             `json:"ref"`
	ID          uint               `json:"id"`
	Workflow    string             `json:"workflow"`
	Title       string             `json:"title"`
	Kind        string             `json:"kind"`
	State       string             `json:"state"`
	Stage       string             `json:"stage,omitempty"`
	Percent     *int               `json:"percent,omitempty"`
	Module      string             `json:"module,omitempty"`
	Labels      []string           `json:"labels,omitempty"`
	Refs        []string           `json:"refs,omitempty"`
	Description string             `json:"description,omitempty"`
	Progress    string             `json:"progress,omitempty"`
	Conclusion  string             `json:"conclusion,omitempty"`
	ParentSeq   int                `json:"parent_seq,omitempty"`
	CreatedBy   string             `json:"created_by"`
	Assignee    string             `json:"assignee,omitempty"`
	AssignedBy  string             `json:"assigned_by,omitempty"`
	ClaimState  string             `json:"claim_state,omitempty"`
	AssignedAt  string             `json:"assigned_at,omitempty"`
	AcceptedAt  string             `json:"accepted_at,omitempty"`
	CreatedAt   string             `json:"created_at"`
	UpdatedAt   string             `json:"updated_at"`
	ClosedAt    string             `json:"closed_at,omitempty"`
	Updates     []TaskUpdateRecord `json:"updates,omitempty"`
	Sessions    []string           `json:"sessions,omitempty"`
}

TaskRecord 是 tasks.jsonl 的一行。序号在板内唯一,所以(board,seq)才是任务的身份;ref 是界面和提交说明里的 #N。

type TaskSet

type TaskSet struct {
	// Boards 是涉及的任务板键(项目板,以及范围内工作流各自还留着任务的独立板),升序。
	Boards  []string
	Modules []model.WorkModule // Path 已填
	// Items 按(板,序号)升序;Updates 按时间线先后升序,Sessions 只带会话编号,ModulePath / ParentSeq 已填。
	Items []model.WorkItem
}

TaskSet 是任务板导出:规划树加全部任务(含已完成、已搁置)。

type TaskUpdateRecord

type TaskUpdateRecord struct {
	At            string `json:"at"`
	Actor         string `json:"actor"`
	ActorWorkflow string `json:"actor_workflow,omitempty"`
	Session       string `json:"session,omitempty"`
	From          string `json:"from,omitempty"`
	To            string `json:"to,omitempty"`
	Text          string `json:"text,omitempty"`
	Event         string `json:"event,omitempty"`
}

TaskUpdateRecord 是任务时间线上的一条。

type Tombstone

type Tombstone struct {
	Kind string   `json:"kind"`
	Key  []string `json:"key"`
}

Tombstone 是 tombstones.jsonl 的一行:基线里有、现在没有的一条记录。

键的含义:workflow / group [编号];task [板, 序号];task_module [板, 路径];confirm [工作流, 序号]; inbox [编号];session [工作流, 会话编号];doc [docs/ 之后的路径]。 群与工作流整个离开范围时只写它们自己的墓碑,合并时级联丢掉它们的消息 / 会话文件,不会再为里面的每条记录各写一行。

type UnknownGroupError

type UnknownGroupError struct{ ID string }

UnknownGroupError 表示请求的群不在这个项目的归档范围内。

func (*UnknownGroupError) Error

func (e *UnknownGroupError) Error() string

type Watermark

type Watermark struct {
	GroupLastSeq     map[string]int64 `json:"group_last_seq"`
	InboxMaxID       uint             `json:"inbox_max_id"`
	ConfirmMaxID     uint             `json:"confirm_max_id"`
	TaskMaxID        uint             `json:"task_max_id"`
	SessionsMaxRowID int64            `json:"sessions_max_rowid"`
}

Watermark 是导出开始时各类数据的水位:之后新增的内容不在这次包里,续导从这里接。

type WorkflowBrief

type WorkflowBrief struct {
	ID     string `json:"id"`
	Title  string `json:"title,omitempty"`
	Rounds int    `json:"rounds"`
}

WorkflowBrief 是预览里的一个工作流:编号、标题与会话轮数(会话文件的条数)。

type WorkflowInfo

type WorkflowInfo struct {
	ID        string
	Title     string
	Host      string
	Directory string
	Via       string
	// Branch 非空 = 它是别人的分支(含已关闭的关系)。
	Branch *model.WorkflowBranch
	// Branches 是它作为主会话时名下的分支工作流编号(含已关闭的关系),升序。
	Branches []string
	FirstAt  time.Time
	LastAt   time.Time
	Rounds   int
}

WorkflowInfo 是范围内的一个工作流。

type WorkflowRecord

type WorkflowRecord struct {
	Workflow       string        `json:"workflow"`
	Title          string        `json:"title,omitempty"`
	Role           string        `json:"role"`
	Via            string        `json:"via"`
	Host           string        `json:"host,omitempty"`
	Directory      string        `json:"directory,omitempty"`
	Branch         *BranchRecord `json:"branch,omitempty"`
	Branches       []string      `json:"branches,omitempty"`
	Rounds         int           `json:"rounds"`
	CreatedAt      string        `json:"created_at,omitempty"`
	LastActivityAt string        `json:"last_activity_at,omitempty"`
	SessionsFile   string        `json:"sessions_file,omitempty"`
}

WorkflowRecord 是 workflows.jsonl 的一行。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL