Documentation
¶
Overview ¶
Package archive 把一个项目的「过程信息」(工作流、群聊、任务、确认项、用户追加、会话轮次、文档) 打成一个可以脱离 RelayMesh 保存、核对和(以后)重建的压缩包(#270)。
分层:
- 本包只依赖 model 与标准库,不碰数据库:数据从 Source 接口分页取,渲染与打包是纯函数;
- 实现 Source 的是 store.ArchiveSource(对着 SQLite 分页读,永不长时间占住唯一的库连接);
- 路由与审计在 internal/api。
压缩包的契约(字段、文件名、排序、校验和)写在 docs/project-archive.md;这里的代码是它的唯一实现。
Index ¶
- Constants
- Variables
- func EffectiveInclude(normalized []string) []string
- func NormalizeInclude(in []string) ([]string, error)
- func OpenPackage(path string) (*Package, []Problem, error)
- func SafeStem(id string) string
- func Verify(r io.ReaderAt, size int64) (*Manifest, []Problem)
- type BasedOn
- type Baseline
- type BaselineRef
- type BranchRecord
- type ChainItem
- type ConfirmAnswerRecord
- type ConfirmRecord
- type Counts
- type DeltaCount
- type DeltaSet
- type DirInfo
- type DocFile
- type DocRename
- type FileEntry
- type GroupExported
- type GroupInfo
- type GroupMark
- type GroupMember
- type GroupMemberRecord
- type GroupMessageRecord
- type GroupRecord
- type GroupSummary
- type IDRange
- type IDRanges
- type ImageRecord
- type InboxRecord
- type Key
- type KeyDigest
- type Manifest
- type ManifestDir
- type ManifestProject
- type ManifestScope
- type MergeReport
- type MergedFrom
- type MessageCounter
- type Options
- type Package
- type Plan
- type Problem
- type ProjectInfo
- type SenderRecord
- type SeqRange
- type SessionRecord
- type SessionRow
- type Since
- type Source
- type Summary
- type SummaryProject
- type TaskModuleRecord
- type TaskRecord
- type TaskSet
- type TaskUpdateRecord
- type Tombstone
- type UnknownGroupError
- type Watermark
- type WorkflowBrief
- type WorkflowInfo
- type WorkflowRecord
Constants ¶
const ( TombWorkflow = "workflow" TombGroup = "group" TombTask = "task" TombTaskModule = "task_module" TombConfirm = "confirm" TombInbox = "inbox" TombSession = "session" TombDoc = "doc" )
墓碑(tombstones.jsonl)里的 kind:被删除的是哪一类记录。
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"])。
const ( FormatName = "relaymesh-project-archive" FormatVersion = 1 // FormatVersionIncremental 是增量包的版本:它的文件只含相对某个基线新增 / 改动的记录,不能当完整包读, // 所以用不同的版本号——只认识版本 1 的读取器会直接拒绝它,而不是把一个残缺的包当成完整的。 FormatVersionIncremental = 2 // ModeIncremental 是清单 mode 字段在增量包里的取值;完整包没有这个字段。 ModeIncremental = "incremental" // ManifestName 是压缩包里清单的路径;它写在最后,列出其余所有文件的校验和。 ManifestName = "manifest.json" )
压缩包格式的名字与版本。字段只增不改不删;要做不兼容的改动时升 FormatVersion。
const ( BaselineFull = "full" BaselineIncremental = "incremental" )
基线的种类。
const ( KindData = "data" // jsonl 数据文件:机器读的权威内容 KindMarkdown = "markdown" // 给人读的渲染 KindDoc = "doc" // docs/ 下的项目文档 KindReadme = "readme" )
文件的种类,写进 manifest 方便按类过滤。
const ( ViaDirectory = "directory" // 最近一条带目录的会话落在项目登记的目录里 ViaBranch = "branch" // 自己的目录不在项目里,但与项目里的工作流有主会话 / 分支关系 )
工作流进入导出范围的原因。
const ( RoleMain = "main" RoleBranch = "branch" RoleNone = "none" )
工作流在分支关系里的角色。
const BaselineVersion = 1
BaselineVersion 是基线摘要编码的版本。
const OpReplace = "replace"
OpReplace 是 FileEntry.Op 的取值:整份替换。
const TombstonesName = "tombstones.jsonl"
TombstonesName 是增量包里删除清单的路径。
Variables ¶
var AllIncludes = []string{ IncludeWorkflows, IncludeGroups, IncludeTasks, IncludeConfirms, IncludeInbox, IncludeSessions, IncludeDocs, }
AllIncludes 是全部类别,按它们在包里出现的固定顺序。
var ErrBaselineMismatch = fmt.Errorf("%w:基线与这次导出的范围不一致", ErrInvalidOptions)
ErrBaselineMismatch 表示基线与这次导出的范围对不上(选项不一致或基线损坏)。
var ErrBaselineVersion = errors.New("archive: 基线摘要的编码版本不认识")
ErrBaselineVersion 表示基线是别的版本的编码,读不了。
var ErrInvalidOptions = errors.New("archive: 导出参数不合法")
ErrInvalidOptions 表示导出参数不合法。
var ErrMerge = errors.New("archive: 合并失败")
ErrMerge 是合并失败的统一前缀:包链对不上、数据不自洽、或来自更新版本的 RelayMesh。
var ExcludedScope = []string{
"图片原文件(记录里只有名字、格式、哈希与尺寸)",
"群消息的 @ 投递记录(chat_mention 收件箱行)",
"终端与执行日志",
"凭据、令牌与系统设置(任何时候都不导出)",
}
ExcludedScope 写进清单,让读压缩包的人一眼看到「这个版本没有包含什么」。
Functions ¶
func EffectiveInclude ¶
EffectiveInclude 返回一次导出实际包含的类别(nil = 全部,也就是 AllIncludes)。
func NormalizeInclude ¶
NormalizeInclude 校验并规整 include 参数。
- 空(nil / 空切片)= 全部类别,返回 nil;
- 含未知类别 → ErrInvalidOptions(列出可用的取值);
- 去重、按固定顺序排列,并补上总是在包里的 workflows;
- 规整之后等于全部类别时同样返回 nil:「全选」与「不选」导出的是同一个包,清单里也不写 scope.include, 所以不带 include 的旧调用方拿到的字节与以前完全相同。
func OpenPackage ¶
OpenPackage 打开一个压缩包(zip 文件或目录)并核对它。返回的问题清单为空才说明包是完整的; 即使有问题,清单读得出来时也会返回 Package(方便把「是哪个包、出了什么问题」说清楚)。 打不开(文件不存在等)返回 error。调用方负责 Close。
func SafeStem ¶
namer 把群 / 工作流编号变成压缩包里的文件名主干:只留 [A-Za-z0-9._-],其余字符换成 -(grp:3d18931d → grp-3d18931d)。 两个不同编号落到同一个名字时(不区分大小写),后来的在结尾补上自己编号 SHA-256 的前 8 位; 调用方按编号升序依次取名,所以同样的输入总得到同样的文件名。 SafeStem 把任意标识(工作流编号等)变成可以当目录名 / 文件名主干的一段,不依赖任何已分配的状态: 不安全的字符换成 -,只要发生过替换或被截断,就附上原值哈希的前 8 位——所以不同的输入不会得到同一个结果, 同一个输入永远得到同一个结果。
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 ¶
DecodeBaseline 是 Encode 的逆。
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 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 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 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 KeyDigest ¶
KeyDigest 是一条记录的(键,摘要)。摘要 = 完整包里那一行 JSON 的 SHA-256(见方案文档的 I1)。
func (KeyDigest) MarshalJSON ¶
MarshalJSON 编成 ["键","十六进制摘要"],比对象紧凑。
func (*KeyDigest) UnmarshalJSON ¶
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 外,同样的数据得到同样的内容。
type ManifestDir ¶
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 ¶
MergeReport 是合并的结果摘要。
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 文件,或者解开 / 合并出来的目录。
type Plan ¶
type Plan struct {
// contains filtered or unexported fields
}
Plan 是准备好的一次导出:范围已经确定、水位已经取好。Prepare 只做小查询, 能在写出第一个字节之前把「群不存在」这类错误报给调用方;真正的大数据在 Write 里分页流式写出。
type Problem ¶
Problem 是核对压缩包时发现的一个问题。
func VerifyChain ¶
VerifyChain 核对一串包能不能接成一条链:第一个必须是完整包,其后每个必须是增量包,并且 每个增量包基于它前面那一个(基线编号与 manifest SHA-256 对得上、before 水位等于前一个包的水位), 项目与范围不变、导出时刻不倒退。包少一环、顺序错、被换成别的包,这里都会报出来。
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 ¶
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 的一行。