model

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: 10 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// ArchiveBaselinePending:基线摘要已经登记,但对应的包还没有完整写出(写到一半断了,这一行就会被丢弃)。
	// 它不能当作增量的起点——调用方手里没有与它对应的完整的包。
	ArchiveBaselinePending = "pending"
	// ArchiveBaselineReady:对应的包已经完整写出,可以做增量导出的起点。
	ArchiveBaselineReady = "ready"
)

归档基线的状态。

View Source
const (
	ArchiveBaselineFull        = "full"
	ArchiveBaselineIncremental = "incremental"
)

归档基线的种类。

View Source
const (
	ArtifactDataMaxBytes = 256 * 1024
	ArtifactDataMaxKeys  = 200
	ArtifactKeyMaxLen    = 128
)

Artifact 数据的上限。

View Source
const (
	AuditAllow   = "allow"
	AuditDeny    = "deny"
	AuditAssumed = "assumed"
)

审计结果:allow 放行;deny 被拒绝(audit 档里表示「若启用 enforce 会被拒绝」);assumed 调用方没有身份断言,按工作流绑定推断。

View Source
const (
	AuditDocWrite         = "doc.write"
	AuditDocDelete        = "doc.delete"
	AuditDocReadCross     = "doc.read.cross"
	AuditCrossWrite       = "write.cross" // 非文档的跨工作流写(任务、会话数据等),被授权放行时记录
	AuditGrant            = "grant"
	AuditRevoke           = "revoke"
	AuditACLDenied        = "acl.denied"
	AuditArtifactDataSet  = "artifact.data_write"
	AuditGroupCreate      = "group.create"
	AuditGroupMemberAdd   = "group.member_add"
	AuditGroupMemberRm    = "group.member_remove"
	AuditGroupCooling     = "group.cooling"
	AuditWakeManual       = "wake.manual"
	AuditLauncherRun      = "launcher.run" // 项目管理 Agent 经 MCP 运行了预设(#179):范围 tasks,allow = 提交成功,deny = 被拒绝
	AuditIdentityRename   = "identity.rename"
	AuditIdentityDisable  = "identity.disable"
	AuditProjectCreate    = "project.create"
	AuditProjectUpdate    = "project.update"
	AuditProjectDirAdd    = "project.dir_add"
	AuditProjectDirRemove = "project.dir_remove"
	AuditProjectMigrate   = "project.migrate"
	AuditProjectExport    = "project.export" // 导出项目归档(#270):Detail 只记范围与数量,不含正文;经 MCP 令牌导出(#272)时 detail.via = "mcp"
	AuditArchiveGrant     = "archive.grant"  // 用户给一把令牌授予了导出这个项目归档的权限(#272):Target = 令牌名称,Detail = 令牌编号
	AuditArchiveRevoke    = "archive.revoke" // 令牌导出这个项目归档的权限被收回(关掉权限位、移出项目名单、停用或删除令牌)
	AuditModuleWrite      = "module.write"

	// 可选语义检索的设置(#266 第 2 步):范围 search/semantic。Detail 只记改了哪些字段名、操作类型与「开 / 关」,
	// 从不含 API Key、服务地址的路径与取值;Target 只有主机:端口。
	AuditSearchSemanticConfig = "search.semantic_config" // 改了配置(字段名 + 服务主机;allow_private 的开关状态)
	AuditSearchSemanticKey    = "search.semantic_key"    // 保存或清除了 API Key(detail.op = set | clear)
	AuditSearchSemanticTest   = "search.semantic_test"   // 点了「测试连接」(detail.ok / detail.kind)

	// 语义检索的运行(#266 第 2 步 · 2b)。Detail 只记 ID、数量与布尔,从不含任何内容文本、查询词或密钥。
	AuditSearchSemanticEnable  = "search.semantic_enable"  // 总开关(detail.enabled)
	AuditSearchSemanticScope   = "search.semantic_scope"   // 改了勾选范围(detail.added / removed 项目 ID、kinds、deleted_entries)
	AuditSearchSemanticRun     = "search.semantic_run"     // 暂停 / 继续 / 立即检查(detail.op)
	AuditSearchSemanticRebuild = "search.semantic_rebuild" // 确认重建(detail.dropped_entries)
	AuditSearchSemanticClear   = "search.semantic_clear"   // 清除全部向量(detail.entries / chunks)

	// 智能体检索(MCP search 工具,#274)。Detail 只记模式、类型、数量与布尔,**从不含查询词与命中内容**。
	AuditSearchAgentAccess    = "search.agent_access"    // 用户在设置里改了「允许智能体使用全文 / 语义检索」(detail.keyword / semantic)
	AuditAgentSearch          = "search.agent"           // 智能体用 search 工具查了一次(detail.mode / kinds / hits / keyword_hits / semantic_hits / hidden / would_hide …)
	AuditAgentSearchThrottled = "search.agent_throttled" // 一次 search 因超过令牌限额被挡回(detail.mode / which;同一令牌 1 分钟内只记一条)
	AuditSearchAgentQuota     = "search.agent_quota"     // 用户在设置里改了「智能体检索额度」(#303;detail 只有被改的那几项的新值,或 reset: true 表示恢复默认)
	AuditSearchHints          = "search.hints"           // 用户在设置里改了「相关线索」(#303 D;detail 只有被改项的新值——enabled / max / threshold / per_hour,或 reset: true)

	// 会话回收站(#292):范围 workflow/<工作流编号>。Detail 只记回收站条目编号、轮数、追加条数、截图张数与快照大小,**从不含任何会话正文**;
	// Target 是会话名(用户自己起的名字或最近一轮的标题,不是正文)。
	AuditSessionTrash   = "session.trash"   // 用户把一条已归档的会话移进回收站
	AuditSessionRestore = "session.restore" // 用户从回收站恢复了一条会话
	AuditSessionPurge   = "session.purge"   // 保留期满,后台把回收站里的一条彻底清理(actor = system)
	AuditSessionHost    = "session.host"    // 用户为一个会话固定了主机,或清除了固定(#299;detail 只记旧值 / 新值、改写行数与项目名,不含会话正文)

	// 群聊回收站(#321):范围 group/<群编号>。Detail 只记回收站条目编号、消息数、成员数、被撤销的授权条数与快照大小,**从不含任何群聊正文**;
	// Target 是群名(用户自己起的名字,不是正文)。被撤销的每条群授权另记一条 revoke(detail.via = group.trash),记在授权所属的项目名下。
	AuditGroupTrash   = "group.trash"   // 用户把一个已归档的群移进回收站
	AuditGroupRestore = "group.restore" // 用户从回收站恢复了一个群(群级授权不会自动恢复)
	AuditGroupPurge   = "group.purge"   // 保留期满,后台把回收站里的一个群彻底清理(actor = system)
)

审计动作(设计稿 06 §7.6)。审计从不记录文档正文与聊天正文。

View Source
const (
	RoleRead    = "read"
	RoleComment = "comment"
	RoleEdit    = "edit"
	RoleManage  = "manage"

	ScopeProject  = "project"
	ScopeModule   = "module"
	ScopeDoc      = "doc"
	ScopeWorkflow = "workflow"
	// ScopeTasks 是项目任务板的管理权(#175 B2c):被授予的 Agent 是「项目管理 Agent」,能派任务、改所有人的任务。
	// 范围引用 = 项目编号,角色只能是 edit,主体只能是单个 Agent 身份,只有用户能授予(Agent 不能自授、不能转授)。
	ScopeTasks = "tasks"

	PrincipalIdentity = "identity"
	PrincipalGroup    = "group"
)

授权角色(逐级包含)与范围。

View Source
const (
	BranchStatusActive = "active"
	BranchStatusClosed = "closed"
)

分支关系的状态。

View Source
const (
	BranchCreatedByHuman   = "human"
	BranchCreatedByMigrate = "migrate"
)

分支关系的创建者(created_by):human 网页用户;agent:<主会话的工作流编号> 主会话经 MCP 建的;migrate 迁移命令。

View Source
const (
	ActorKindMain   = "main"   // 主会话 Agent
	ActorKindBranch = "branch" // 分支 Agent
	ActorKindHuman  = "human"  // 用户本人(在另一个会话页里说的,被抄送过来)
	ActorKindSystem = "system" // 系统(分支已创建 / 已结束等)
)

消息发言者的种类(queued_feedbacks.actor 里的 kind)。

View Source
const (
	ExposeHistoryOff     = "off"
	ExposeHistorySummary = "summary"
	ExposeHistoryFull    = "full"

	ExposeParamsOff           = "off"
	ExposeParamsResident      = "resident"
	ExposeParamsResidentPhase = "resident_phase"
	ExposeParamsAll           = "all"

	ExposeTasksRead   = "read"
	ExposeTasksAssign = "assign"
)

「向主会话开放多少」各项的取值。

View Source
const (
	ExposePresetVisible = "visible" // 仅可见
	ExposePresetCollab  = "collab"  // 协作
	ExposePresetManaged = "managed" // 托管
)

开放范围的三个一键预设。

View Source
const (
	// BranchEscalateDefaultMinutes 是路由给主会话的请示超过多久没人答复就自动升级给用户(分钟)。
	BranchEscalateDefaultMinutes = 30
	BranchEscalateMinMinutes     = 5
	BranchEscalateMaxMinutes     = 1440
)

分支的全局偏好(system_settings 的 branch.prefs 键,JSON;#236 P2)。

View Source
const (
	ParamFieldResident   = PromptFieldResident
	ParamFieldPhase      = "phase"
	ParamFieldWakeResume = PromptFieldWakeResume
	ParamFieldWakeNew    = PromptFieldWakeNew
	ParamFieldTitle      = "title"
	ParamFieldAsync      = "async"
)

会话参数里能被主会话改的字段名;常驻规则与唤醒词沿用 workflow_prompt_revisions 里的字段名,保持同一套叫法。

View Source
const (
	// BranchParamEventKeep 是每个分支保留的事件条数,超出的按时间删旧。
	BranchParamEventKeep = 200
	// BranchParamRateLimit 是每个分支每小时最多接受的主会话参数写入数(按字段计):防止失控的主会话刷屏。
	BranchParamRateLimit = 30
	// BranchParamTitleMax 是主会话给分支改的标题的最大字数(按字符计)。
	BranchParamTitleMax = 80
	// BranchParamSummaryMax 是事件摘要的最大字数(按字符计)。
	BranchParamSummaryMax = 240
	// BranchParamByHuman 是由用户本人(网页登录态)产生的事件的操作者;主会话写入记成 agent:<主会话工作流编号>。
	BranchParamByHuman = "human"
)
View Source
const (
	ConfirmKindAsk      = "ask"      // 智能体异步提问(async_ask)
	ConfirmKindPlan     = "plan"     // 计划确认:绑定任务,批准后再动手
	ConfirmKindDecision = "decision" // 文档里的 “`decision 围栏

	ConfirmStatusPending   = "pending"
	ConfirmStatusAnswered  = "answered"
	ConfirmStatusDismissed = "dismissed"
	ConfirmStatusWithdrawn = "withdrawn"
	ConfirmStatusExpired   = "expired"

	// 风险等级:L0 只读 / 可随时回滚;L1 可回滚的改动;L2 不可逆或高风险(批准前绝不执行:没有默认值、批量入口不处理、
	// 不能一键采用推荐、不会自动过期;异步对话里智能体用 async_ask 发 L2 确认卡,同步模式仍是阻塞式确认)。
	ConfirmRiskL0 = "L0"
	ConfirmRiskL1 = "L1"
	ConfirmRiskL2 = "L2"

	ConfirmCreatedByAgent = "agent"
	ConfirmCreatedByDoc   = "doc"

	ConfirmTitleMax   = 200
	ConfirmBodyMax    = 20000
	ConfirmNoteMax    = 2000
	ConfirmCustomMax  = 2000 // 自定义答复(#183)的字数上限,与备注同一口径
	ConfirmBatchMax   = 50
	ConfirmOptionsMin = 2
	ConfirmOptionsMax = 8

	// 每个工作流每小时最多通过 async_ask 创建的条数;超过时提示合并提问。
	ConfirmCreateRateHour = 30
	// 同一时刻待处理超过这个数,async_ask 的返回里会提示合并提问。
	ConfirmPendingWarn = 10

	// 收件箱里确认项答复的消息种类(QueuedFeedback.Kind)。
	InboxKindAnswer = "answer"

	// 决策路由(#236 P2):分支里智能体发的请示,先送主会话定夺。
	// addressee = wf:<主会话工作流>;空 = 直接给用户。答复人 By = agent:<主会话工作流>(人 = human)。
	ConfirmAddresseeMainPrefix = "wf:"
	ConfirmByAgentPrefix       = "agent:"
	// 转交 / 升级的来源(ConfirmEscalation.By):agent:<主会话工作流> 主会话自己转的;timeout 超时自动升级;system 关系结束 / 关了「定夺」。
	ConfirmEscalatedByTimeout = "timeout"
	ConfirmEscalatedBySystem  = "system"
	// ConfirmEscalateNoteMax 是主会话转交时说明的字数上限(必填,用户要靠它看懂为什么转给他)。
	ConfirmEscalateNoteMax = 300
)
View Source
const (
	ConversationReaderHuman    = "human"    // 你(Web)
	ConversationReaderWorkflow = "workflow" // 某个工作流里的 Agent
)

已读游标的读者种类。

View Source
const (
	ConversationEventChatEnd  = "chat_end"  // Agent 声明本会话结束(chat end)
	ConversationEventAsyncOn  = "async_on"  // 开启异步对话
	ConversationEventAsyncOff = "async_off" // 关闭异步对话
	ConversationEventWake     = "wake"      // 用户手动唤醒了托管终端里的智能体(只记次数与方式,不记提示词)
)

会话事件的种类。

View Source
const (
	MemberKindHuman    = "human"    // 你(Web);当前只有一个人,字段按通用设计
	MemberKindWorkflow = "workflow" // 一个工作流里的 Agent(成员单位 = 工作流)

	GroupRoleOwner  = "owner"
	GroupRoleMember = "member"
)

群成员的种类与角色。

View Source
const (
	PushMentions = "mentions" // 默认:只在被 @ 时
	PushAll      = "all"      // 你发的每条消息都扔给它
	PushNone     = "none"     // 连 @ 也不扔(只留在群里,成员自己 read 才看得到)
)

成员的推送策略:决定「没点名这个成员的话」要不要把消息扔进它的收件箱。

View Source
const (
	ChatKindText   = "text"
	ChatKindSystem = "system" // 系统行:成员加入 / 离开、冷却、回复链过长;Body 是事件码,SenderRef 是相关成员

	ChatSenderHuman    = "human"
	ChatSenderWorkflow = "workflow"
	ChatSenderSystem   = "system"

	// ChatMentionAll / ChatMentionHuman 是 mentions 里除工作流编号之外的两个特殊值。
	ChatMentionAll   = "all"
	ChatMentionHuman = "human"
)

群消息的种类与发送者。

View Source
const (
	GroupEventCreated      = "group_created"
	GroupEventJoined       = "member_joined"
	GroupEventLeft         = "member_left"
	GroupEventArchived     = "group_archived"
	GroupEventHopLimit     = "hop_limit"     // 某成员的消息因回复链过长没有发出
	GroupEventCooling      = "cooling"       // 群进入冷却:Agent 之间的新消息只落库、不投递
	GroupEventPolicyChange = "policy_change" // 预留
)

系统行的事件码(ChatMessage.Body)。

View Source
const (
	MaxSegmentBytes           = 32 * 1024
	MaxWorkOrderBytes         = 48 * 1024
	MaxTaskContentBytes       = 128 * 1024
	MaxReportingGuideBytes    = 12 * 1024
	MaxReportingExampleBytes  = 16 * 1024
	MaxMessageBytes           = 32 * 1024
	MaxPathReferences         = 50
	MaxSegments               = 64
	MaxPageSize               = 100
	MaxCommunicationPageBytes = 160 * 1024
)
View Source
const (
	InboxStateQueued    = "queued"
	InboxStateDelivered = "delivered"
	InboxStateAcked     = "acked"
	InboxStateRevoked   = "revoked"
	InboxStateRetracted = "retracted"
	InboxStateExpired   = "expired"
)

收件箱条目的状态名。

View Source
const (
	TerminalModeFollow   = ""
	TerminalModeAuto     = "auto"
	TerminalModeApprove  = "approve"
	TerminalModeReadonly = "readonly"
)

令牌的终端执行模式上限;空字符串表示跟随主机设置。

View Source
const (
	PhaseDiscuss = "discuss"
	PhasePlan    = "plan"
	PhaseDev     = "dev"

	// DefaultPhaseID 是新工作流的起始阶段。
	DefaultPhaseID = PhaseDiscuss
)

工作流阶段。

v1.7 起阶段收敛为三段:讨论 / 方案 / 开发。

  • 讨论:快速沟通信息(原「评估」);
  • 方案:基于已核实的事实做方案评估;
  • 开发:按已确认的方案实施,原「验证」「完成」的检查清单并入本阶段的提示词。

阶段描述的是「智能体现在该怎么表现」,与任务状态(工作项走到哪一步)是两条正交的轴。

View Source
const (
	ACLOff     = "off"
	ACLAudit   = "audit"
	ACLEnforce = "enforce"
)

ACL 档位:off(现状,不记录)→ audit(只记录「若启用会被拒绝」的调用,不拦)→ enforce(真正拦截,只由用户打开)。

View Source
const (
	DocRenderMarkdown = "md"
	DocRenderMermaid  = "mermaid"
	DocRenderHTML     = "html"
	DocRenderData     = "data"
)

文档渲染类型。

View Source
const (
	DocKindDesign    = "design"
	DocKindDecision  = "decision"
	DocKindPlan      = "plan"
	DocKindEval      = "eval"
	DocKindSpec      = "spec"
	DocKindGuide     = "guide"
	DocKindReference = "reference"
	DocKindRunbook   = "runbook"
	DocKindNote      = "note"
	DocKindChangelog = "changelog"
	DocKindOther     = "other"

	DocStatusDraft      = "draft"
	DocStatusReview     = "review"
	DocStatusApproved   = "approved"
	DocStatusSuperseded = "superseded"
	DocStatusArchived   = "archived"

	DocActorHuman  = "human"
	DocActorAgent  = "agent"
	DocActorImport = "import"
)

项目文档类型与状态(见 docs/project-docs.md)。

View Source
const (
	HostKindAgent = "agent"
	HostKindSSH   = "ssh"
)

主机的接入方式。

View Source
const (
	HostDefaultDeny  = "deny"
	HostDefaultAllow = "allow"
)

主机对新建模型授权的默认态(TerminalHost.DefaultForNewModels)。

View Source
const (
	RunAwaitingApproval = "awaiting_approval"
	RunRunning          = "running"
	RunSucceeded        = "succeeded"
	RunFailed           = "failed" // 命令自行结束且退出码非 0,或被信号终止
	RunTimedOut         = "timeout"
	RunCancelled        = "cancelled"
	RunRejected         = "rejected" // 需批准模式下被人工拒绝或批准超时
	RunDenied           = "denied"   // 被闸门拒绝(含本机一票否决)
	RunLost             = "lost"     // 主机重启 / 守护进程消失后无法确认结果
)

模型运行的状态。

View Source
const (
	WorkStateTodo    = "todo"
	WorkStateDoing   = "doing"
	WorkStateReview  = "review"
	WorkStateDone    = "done"
	WorkStateShelved = "shelved"
)

任务状态。主线:待办 → 进行中 → 验证中 → 已完成;「已搁置」是旁支,随时可以回到主线。 review 这个存储值沿用旧名(数据库里已有大量记录),界面与回执里叫「验证中」。

View Source
const (
	WorkClaimOffered  = "offered"  // 已派未接
	WorkClaimAccepted = "accepted" // 承接者已接取
	WorkClaimDeclined = "declined" // 承接者拒绝(保留承接者与理由,等重派)
)

指派后的接取状态(WorkItem.ClaimState)。空串 = 没有指派。状态机本身不加新状态(todo / doing / review / done / shelved), 「已交付待验收」就是有协作指派的任务停在 review。

View Source
const (
	WorkEventAssign         = "assign"
	WorkEventReassign       = "reassign"
	WorkEventUnassign       = "unassign"
	WorkEventAccept         = "accept"
	WorkEventDecline        = "decline"
	WorkEventDeliver        = "deliver"
	WorkEventAcceptDelivery = "accept_delivery"
	WorkEventRejectDelivery = "reject_delivery"
)

时间线上的协作事件(WorkItemUpdate.Event)。

View Source
const (
	WorkKindBug      = "bug"
	WorkKindFeature  = "feature"
	WorkKindImprove  = "improve"
	WorkKindResearch = "research"
	WorkKindOps      = "ops"
)

任务类型:五类固定分类 + 自由标签。分类用来回答「这是什么性质的事」,标签补充领域(例如 终端 / 设置 / 发布)。

View Source
const (
	WorkStageAssess  = "assess"  // 评估:搞清楚要不要做、值不值得做
	WorkStagePlan    = "plan"    // 方案:已决定做,正在定怎么做
	WorkStageDev     = "dev"     // 开发:按方案实现
	WorkStageImprove = "improve" // 改进:已交付,在迭代打磨
)

任务阶段:这件事在「做什么」这条线上走到哪了——评估 → 方案 → 开发 → 改进。

它与另外两个维度互相独立:

  • 类型(Kind)回答「这是什么性质的事」(缺陷 / 功能 / …),不是一条前进的线;
  • 状态(State)回答「现在做到流程的哪一步」(待办 / 进行中 / 验证中 / …),智能体置「已完成」必须带结论;
  • 阶段(Stage)只是一个标注,人和智能体都能改,不进状态机。空串 = 未标注(界面按类型推导一个默认值)。
View Source
const (
	WorkActorHuman = "human" // Web 界面(已登录的管理员)
	WorkActorAgent = "agent" // MCP 工具(智能体)
)

操作者类型:任务的写入口只有两个,规则也只因它而不同。

View Source
const (
	WorkTitleMax       = 200
	WorkDescriptionMax = 1000
	WorkProgressMax    = 500
	WorkConclusionMax  = 400
	WorkNoteMax        = 500
	// WorkImproveMax 是「发起改进需求」的正文上限:它会连同「改进需求:」前缀一起写进时间线(≤ WorkNoteMax)。
	WorkImproveMax = 450
	WorkLabelMax   = 24
	WorkLabelsMax  = 8
	WorkRefMax     = 200
	WorkRefsMax    = 10
	// WorkUpdatesKeep 是每个任务保留的最近进展条数;更早的会被新条目挤掉。
	WorkUpdatesKeep = 20
	// WorkFlipMergeMinutes:同一个人在这么多分钟之内把状态改了又改回去,时间线上这两次改动互相抵消、不留记录
	// (误点后改回来的操作不算进展);超过这个时间的反复属于真实的重开 / 重新确认,照常记录。
	WorkFlipMergeMinutes = 30
	// WorkCompactAfterDays:任务关闭(已完成 / 已搁置)超过这么多天后,进展时间线被压缩掉,只保留结论与引用。
	WorkCompactAfterDays = 90
	// WorkConclusionFallback 压缩时若没有结论,从最新进度截取多少字作为结论。
	WorkConclusionFallback = 300
)

字段上限。进度和结论都是「摘要」而不是文档:长内容请放会话文档,这里只留能定位问题的几行。 描述回答「这件事到底是什么」:背景、要做什么、做到什么算完成,一小段话,创建时写一次,以后很少改。

View Source
const (
	WorkModuleNameMax = 40
	WorkModuleDescMax = 200
	// WorkModulesMax 每个工作流最多的顶层模块数。
	WorkModulesMax = 30
	// WorkFeaturesMax 每个顶层模块下最多的功能数。
	WorkFeaturesMax = 30
	// WorkModuleDepthMax 规划树的最大深度(模块 + 功能)。
	WorkModuleDepthMax = 2
	// WorkModulePathSep 模块路径的分隔符。
	WorkModulePathSep = "/"
)
View Source
const (
	// FeedbackKindFeedback 是常规的阻塞式汇报(库里存空串,保持旧版本读写不变);
	// FeedbackKindNotice 是异步模式下不阻塞发布的进度 / 回答气泡:没有回复框,发布即完成。
	FeedbackKindFeedback = "feedback"
	FeedbackKindNotice   = "notice"

	// FeedbackNoticeLevelKey 是「重点」级进度通知(#275):网页上用强调样式显示,要用户滑动确认「已收到」。
	// 普通级不写库(空串),旧版本与旧数据保持原样;只有 kind = notice 的行才可能是重点级。
	// FeedbackNoticeLevelNormal 只用来表示调用方显式传了 normal,不入库。
	FeedbackNoticeLevelKey    = "key"
	FeedbackNoticeLevelNormal = "normal"

	// KeyNoticeLimitPerHour 是每个工作流每滚动一小时最多发布的重点通知条数:重点用多了就不「重点」了,
	// 超出的按普通通知发布(并在回执里说明),不是报错。
	KeyNoticeLimitPerHour = 3

	// 授权档位的风险上限:智能体不必先问就能处理到哪一级。
	// L0 只做读与分析,任何写入都先问;L1 可回滚的改动(工作树内修改、本地提交)直接做。
	// 不可逆的操作(L2)在任何档位下都要用户明确批准才能执行(INV-3)——异步对话里发 L2 确认卡、批准前不执行——
	// 所以没有 L2 档位。
	AuthLevelL0 = "L0"
	AuthLevelL1 = "L1"

	AuthProfileNameMax  = 24
	AuthProfileRulesMax = 240
	AuthProfileMax      = 12
)
View Source
const (
	// ResidentPromptMax 是常驻提示词的最大字数(按字符计,不是字节)。每轮回执最多因此多出这么多字。
	ResidentPromptMax = 1200
	// PromptRevisionKeep 是每个会话每个字段保留的历史版本数,超出的按字段滚动删除。
	PromptRevisionKeep = 10
	// PromptFieldResident 是版本记录里常驻提示词的字段名(唤醒词模板等字段沿用同一张表)。
	PromptFieldResident = "resident"
	// PromptFieldWakeResume / PromptFieldWakeNew 是会话自己的唤醒词模板在版本记录里的字段名(#232 D3)。
	PromptFieldWakeResume = "wake_resume"
	PromptFieldWakeNew    = "wake_new"
)
View Source
const ArtifactCommentMaxLen = 4000

ArtifactCommentMaxLen 是一条评论的字数上限。

View Source
const ConversationKindGroup = "group"

会话种类(目前只有群)。

View Source
const CredentialSourceOAuth = "oauth"

CredentialSourceOAuth 是 MCPCredential.OAuthSource 里「由 OAuth 授权创建」的取值。

View Source
const InboxKindBranch = "branch"

InboxKindBranch 是主会话与分支之间互发消息(以及用户在分支里的发言抄送给主会话)在收件箱里的 kind。 和确认项答复、群聊 @ 提醒一样属于「系统投递」:不是用户追加的话,不占用户的待读上限,不并入 interactive_feedback 的秒回,用户不能撤回。

View Source
const InboxKindChatMention = "chat_mention"

InboxKindChatMention 是群消息扔进成员收件箱时的 kind:不并入 interactive_feedback 的秒回,也不算「你追加的话」。

View Source
const SSHKeyMismatch = "mismatch"

SSH 主机密钥状态。

Variables

BranchParamFields 是 session_params 能写的全部字段,也是 get 展示与 set 写入的固定顺序(开放档位从低到高)。

View Source
var ErrInvalidBranchPrefs = errors.New("分支偏好不合法")

ErrInvalidBranchPrefs 标记偏好校验不过(接口层据此回 400)。

View Source
var WorkClaims = []string{"accept", "decline", "deliver", "accept_delivery", "reject_delivery"}

WorkClaims 是 claim 参数的合法取值(显式的接取 / 拒绝 / 交付 / 验收 / 退回)。

WorkKinds 按展示顺序列出全部分类。

WorkStages 按前进顺序列出全部阶段。

WorkStates 按看板列顺序列出全部状态。

Functions

func BranchCreatedByAgent added in v2.1.0

func BranchCreatedByAgent(workflowID string) string

BranchCreatedByAgent 拼出「某个主会话 Agent 创建」的 created_by。

func BranchCreatorOfAgent added in v2.2.0

func BranchCreatorOfAgent(createdBy string) (workflowID string, ok bool)

BranchCreatorOfAgent 是 BranchCreatedByAgent 的逆:从 created_by 里取出建这个分支的主会话工作流编号; 不是「agent:<主会话>」这一形态(human / migrate / 空)时 ok 为 false。

func BuildSessionImageRelativeURL

func BuildSessionImageRelativeURL(sessionID string, index int, hash string) string

BuildSessionImageRelativeURL 统一定义图片标准相对访问路径(带不可变内容哈希)

func CanonicalPhaseID

func CanonicalPhaseID(id string) string

CanonicalPhaseID 把旧阶段 id 换成对应的新 id,其他 id(含用户自建的阶段)原样返回。

func ClampPercent

func ClampPercent(v int) int

ClampPercent 把进度限制在 0–100。

func ConfirmAddresseeMain added in v2.1.0

func ConfirmAddresseeMain(workflowID string) string

ConfirmAddresseeMain 拼出「路由给某个主会话」的 addressee。

func ConfirmAddresseeMainOf added in v2.1.0

func ConfirmAddresseeMainOf(addressee string) string

ConfirmAddresseeMainOf 取出 addressee 里的主会话工作流编号;不是路由给主会话的返回空串。

func ConfirmByAgent added in v2.1.0

func ConfirmByAgent(workflowID string) string

ConfirmByAgent 拼出「某个主会话 Agent 代答」的 By。

func ConfirmRef

func ConfirmRef(seq int) string

ConfirmRef 把序号写成界面与收件箱里用的 Q12;序号非法时返回空串。

func EffectivePercent

func EffectivePercent(state string, percent *int, childTotal, childDone int) (value int, derived string)

EffectivePercent 是任务进度条上的取值(0–100):

已完成 = 100;显式写过 percent 的用它;有子任务的按完成比例;否则由状态推导(待办 0 / 进行中 50 / 验证中 90 / 已搁置 0)。

derived 说明数值的来源:explicit(显式)/ children(子任务比例)/ state(状态推导,只适合画条、不适合当数字展示)。

func EffectiveWholeFS

func EffectiveWholeFS(p Permissions, l TerminalLimits) bool

EffectiveWholeFS 报告这把令牌是否真的拥有「整个文件系统」的访问:开关打开且文件权限位同时打开。 文件权限位关闭时,开关只是一个被保留的设置,不产生任何访问;权限位再次打开时它会重新生效—— 所以「从无到有」的判断(是否需要重新验证密码、是否写审计)必须用这个值,而不是只看开关本身。

func ExposeParamsRank added in v2.1.0

func ExposeParamsRank(level string) int

ExposeParamsRank 把「改参数」的四档换算成可比较的等级:off 0、resident 1、resident_phase 2、all 3; 不认识的取值一律按 off(0)处理——权限判定宁可偏紧。

func ExposeWidens added in v2.1.0

func ExposeWidens(from, to BranchExpose) bool

ExposeWidens 判断把开放范围从 from 改成 to 是不是「放宽」: 「改参数」从低档调到更高的一档(任何一档非 off 的上调),或把「启动」从关打开。 放宽要终端解锁(密码再验证),收紧只需登录;对其它几项(读历史、发消息、定夺、任务)不设这道关。

func IsClosedWorkState

func IsClosedWorkState(state string) bool

IsClosedWorkState 判断状态是否已离开主线。

func IsFinalRunState

func IsFinalRunState(state string) bool

IsFinalRunState 判断运行状态是否已终结。

func IsLegacyPhaseID

func IsLegacyPhaseID(id string) bool

IsLegacyPhaseID 判断 id 是不是已经并入别的阶段的旧 id。

func JoinModulePath

func JoinModulePath(parts ...string) string

JoinModulePath 把模块名与功能名拼成路径。

func NormalizeACLMode

func NormalizeACLMode(s string) string

NormalizeACLMode 把输入规整成合法档位;不认识的返回空串。

func NormalizeConfirmRisk

func NormalizeConfirmRisk(s string) string

NormalizeConfirmRisk 把任意输入规整成 L0 / L1 / L2;不认识的按 L1(中间档)处理。

func NormalizeDocKind

func NormalizeDocKind(s string) string

func NormalizeDocRender

func NormalizeDocRender(s string) string

NormalizeDocRender 规整渲染类型;空串等价于 md,不认识的返回空串。

func NormalizeDocStatus

func NormalizeDocStatus(s string) string

func NormalizeWorkKind

func NormalizeWorkKind(s string) string

NormalizeWorkKind 把类型规整成标准 id(接受中文名与常见英文别名);无法识别时返回空串。

func NormalizeWorkStage

func NormalizeWorkStage(s string) string

NormalizeWorkStage 把阶段规整成标准 id(接受中文名与常见英文别名);无法识别时返回空串。 空串本身也表示「未标注」,调用方需要区分「清除」与「无法识别」时先判断输入是否为空。

func NormalizeWorkState

func NormalizeWorkState(s string) string

NormalizeWorkState 把状态规整成标准 id(接受中文名与常见英文别名);无法识别时返回空串。

func ParamFieldAllowed added in v2.1.0

func ParamFieldAllowed(level, field string) bool

ParamFieldAllowed 判断某个开放档位能不能改这个字段。

func ParamFieldLabel added in v2.1.0

func ParamFieldLabel(field string) string

ParamFieldLabel 是字段在界面与回执里的叫法。

func ParamFieldMinLevel added in v2.1.0

func ParamFieldMinLevel(field string) string

ParamFieldMinLevel 返回改某个字段至少需要的「改参数」档位;不是可写字段返回空串。

常驻规则 ≥ resident;阶段 ≥ resident_phase;标题、两类唤醒词与异步开关只在 all。 授权档位、凭据、目录与主机、终端永不在这里(见 store.neverOpenParamKeys)。

func ParamFieldsEditable added in v2.1.0

func ParamFieldsEditable(level string) []string

ParamFieldsEditable 返回某个开放档位下能改的字段(按 BranchParamFields 的顺序)。

func ParamsSummary added in v2.1.0

func ParamsSummary(level string) string

ParamsSummary 是「改参数」这一项在摘要里的写法(P3 起生效):写明主会话能改哪些,不认识的取值按「不可改」写(宁紧勿松)。

func SplitModulePath

func SplitModulePath(path string) []string

SplitModulePath 把用户 / 智能体给的路径拆成各段:按 `/` 分段,去掉每段两端的空白与空段。 同时容忍 `>`、`>`、`/` 这几种常见写法。

func TasksSummary added in v2.1.0

func TasksSummary(level string) string

TasksSummary 是「派任务」这一项在摘要里的写法(P5 起生效):主会话能不能把自己建的任务指派给这个分支。 看任务不在这里:同一张任务板上的工作流本来就读得到彼此的任务。不认识的取值按「不可派任务」写。

func ValidBranchCreatedBy added in v2.1.0

func ValidBranchCreatedBy(v string) bool

ValidBranchCreatedBy 判断 created_by 是不是三种形态之一。

func WorkStageLabel

func WorkStageLabel(stage string) string

WorkStageLabel 返回阶段的中文名;空串或未知值返回「未标注」。

Types

type ACLGrant

type ACLGrant struct {
	ID             uint       `gorm:"primaryKey;autoIncrement" json:"id"`
	ProjectID      uint       `gorm:"not null;default:0;index" json:"project_id,omitempty"`
	PrincipalKind  string     `gorm:"size:16;not null;index:idx_grant_principal,priority:1" json:"principal_kind"`
	PrincipalRef   string     `gorm:"size:160;not null;index:idx_grant_principal,priority:2" json:"principal_ref"`
	ScopeKind      string     `gorm:"size:16;not null;index:idx_grant_scope,priority:1" json:"scope_kind"`
	ScopeRef       string     `gorm:"size:256;not null;index:idx_grant_scope,priority:2" json:"scope_ref"`
	Role           string     `gorm:"size:8;not null" json:"role"`
	GrantedByKind  string     `gorm:"size:16;not null" json:"granted_by_kind"`
	GrantedByRef   string     `gorm:"size:160;not null" json:"granted_by_ref"`
	GrantedByLabel string     `gorm:"size:200" json:"granted_by_label,omitempty"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`
	CreatedAt      time.Time  `json:"created_at"`
	RevokedAt      *time.Time `json:"revoked_at,omitempty"`
	Note           string     `gorm:"size:500" json:"note,omitempty"`
}

ACLGrant 是一条显式授权。「群共享」就是 principal_kind=group、role=read 的一条授权。

type AckSummary

type AckSummary struct {
	TaskID                     string `json:"task_id"`
	AcknowledgedReportSequence int64  `json:"acknowledged_report_sequence"`
	UnreadReportCount          int64  `json:"unread_report_count"`
}

type AddReportInput

type AddReportInput struct {
	ProjectID                    string          `json:"project_id"`
	TaskID                       string          `json:"task_id"`
	AcknowledgedTaskRevision     int64           `json:"acknowledged_task_revision"`
	AcknowledgedFeedbackSequence int64           `json:"acknowledged_feedback_sequence"`
	Kind                         string          `json:"kind"`
	Body                         string          `json:"body"`
	References                   []PathReference `json:"references,omitempty"`
	IdempotencyKey               string          `json:"idempotency_key,omitempty"`
}

type AgentEventRecord

type AgentEventRecord struct {
	ID         uint      `gorm:"primaryKey" json:"id"`
	IdentityID uint      `gorm:"index" json:"identity_id"`
	SessionID  uint      `gorm:"index" json:"session_id"` // 0 = 不属于某个会话(比如改名审计)
	At         time.Time `gorm:"index" json:"at"`
	Source     string    `gorm:"size:12" json:"source"` // hook | mcp | tui | guard | web
	Event      string    `gorm:"size:24" json:"event"`
	Tool       string    `gorm:"size:64" json:"tool,omitempty"`
	DurationMS int       `json:"duration_ms,omitempty"`
	Extra      string    `gorm:"type:text" json:"extra,omitempty"` // 很小的 JSON:note、stop 状态等,不含任何正文
}

AgentEventRecord 是状态机事件的流水(环形:保留 7 天或 2 万行)。表名 agent_events。

func (AgentEventRecord) TableName

func (AgentEventRecord) TableName() string

TableName 固定表名,免得被复数化成 agent_event_records。

type AgentIdentity

type AgentIdentity struct {
	ID               uint       `gorm:"primaryKey" json:"id"`
	CredentialID     uint       `gorm:"uniqueIndex:ux_agent_identity,priority:1" json:"credential_id"`
	HostName         string     `gorm:"size:128;uniqueIndex:ux_agent_identity,priority:2" json:"host_name"`
	ProjectDirectory string     `gorm:"size:512;uniqueIndex:ux_agent_identity,priority:3" json:"project_directory"`
	Name             string     `gorm:"size:80" json:"name"`                  // 用户改的名字;空 = 用目录名
	ClientKind       string     `gorm:"size:16" json:"client_kind,omitempty"` // ide | cli | unknown
	CursorVersion    string     `gorm:"size:32" json:"cursor_version,omitempty"`
	FirstSeenAt      time.Time  `json:"first_seen_at"`
	LastSeenAt       time.Time  `gorm:"index" json:"last_seen_at"`
	LastHookAt       *time.Time `json:"last_hook_at,omitempty"`  // 最近一次收到 hook 事件
	LastMCPAt        *time.Time `json:"last_mcp_at,omitempty"`   // 最近一次 MCP 调用
	LastQueryAt      *time.Time `json:"last_query_at,omitempty"` // 最近一次「读类」MCP 调用(收件箱、会话列表、文档读取……)
	CreatedAt        time.Time  `json:"created_at"`
	UpdatedAt        time.Time  `json:"updated_at"`
}

AgentIdentity 是「谁」:Token + 主机 + 项目路径。同一个 Token 可以被多个项目共用,所以光有凭据区分不了项目。 身份来自调用方自报(MCP 调用里断言的 project_directory、hook 上报的工作区根目录),不是安全边界; 真正的边界仍然是 Token(谁能连上 Hub)。

type AgentSession

type AgentSession struct {
	ID             uint   `gorm:"primaryKey" json:"id"`
	IdentityID     uint   `gorm:"uniqueIndex:ux_agent_session,priority:1" json:"identity_id"`
	ConversationID string `gorm:"size:64;uniqueIndex:ux_agent_session,priority:2" json:"conversation_id"`
	WorkflowID     string `gorm:"size:128;index" json:"workflow_id"`
	ClientKind     string `gorm:"size:16" json:"client_kind,omitempty"`
	CursorVersion  string `gorm:"size:32" json:"cursor_version,omitempty"`

	StartedAt time.Time `json:"started_at"`
	EndedAt   time.Time `json:"ended_at"`
	EndReason string    `gorm:"size:16" json:"end_reason,omitempty"`

	State         string    `gorm:"size:24" json:"state"`
	Sub           string    `gorm:"size:96" json:"sub,omitempty"`          // thinking | responding | tool:<名>
	StateSource   string    `gorm:"size:12" json:"state_source,omitempty"` // hook | tui | run:现在这个状态是谁说的
	StateSince    time.Time `json:"state_since"`
	LastEventAt   time.Time `gorm:"index" json:"last_event_at"`
	LastTool      string    `gorm:"size:64" json:"last_tool,omitempty"`
	ToolStartedAt time.Time `json:"tool_started_at"`
	TurnStartedAt time.Time `json:"turn_started_at"`
	TurnEndedAt   time.Time `json:"turn_ended_at"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

AgentSession 是一个 Cursor 对话在某个身份下的运行状态;状态机在这一层跑。

type ArchiveBaseline added in v2.2.0

type ArchiveBaseline struct {
	// ID 是调用方可见的基线编号(bl-xxxxxxxxxxxx):导出登记时就生成,写进包的 manifest.json 的 baseline.id。
	ID           string `gorm:"primaryKey;size:40" json:"id"`
	ProjectID    uint   `gorm:"not null;index:idx_archive_baseline_owner,priority:1" json:"project_id"`
	CredentialID uint   `gorm:"not null;index:idx_archive_baseline_owner,priority:2" json:"credential_id"`
	State        string `gorm:"size:12;not null;default:pending" json:"state"`
	// Kind 是登记它的包的种类(full | incremental);ParentID 是增量包基于的基线。
	Kind     string `gorm:"size:16;not null" json:"kind"`
	ParentID string `gorm:"size:40" json:"parent_id,omitempty"`
	// ExportID 是登记它的那次导出(ex-…),方便把基线和 status 里的导出对上。
	ExportID string `gorm:"size:40" json:"export_id,omitempty"`
	// ManifestSHA256 是登记它的那个包里 manifest.json 的 SHA-256:增量包的 based_on 引用它,离线把包串成链。
	ManifestSHA256 string `gorm:"size:64;not null" json:"manifest_sha256"`
	// Include 是基线的范围(规整后的类别,逗号分隔;空 = 全部类别)。增量导出沿用它。
	Include string `gorm:"size:120" json:"include,omitempty"`
	// Records 是摘要里登记的记录条数(给 status 展示用)。
	Records int `gorm:"not null;default:0" json:"records"`
	// Digests 是压缩后的摘要(archive.Baseline.Encode 的输出)。列表接口不读它。
	Digests []byte `gorm:"type:blob;not null" json:"-"`
	// ExportedAt 是包里 manifest.json 的 exported_at;CreatedAt 是基线登记的时刻(保留期从它算起)。
	ExportedAt time.Time `json:"exported_at"`
	CreatedAt  time.Time `gorm:"index" json:"created_at"`
}

ArchiveBaseline 是一次令牌导出的项目归档登记的「基线」(#272 阶段 2):那一刻项目里每类可变记录的(键 → 摘要), 以及群消息的水位。它不含任何正文——只回答「这条记录自那以后变没变」,所以增量导出不需要在 Hub 上留一份完整的副本。

归属:(项目,令牌凭据)。一把令牌只能用自己在这个项目里登记的基线做增量的起点。 保留:每个(项目,令牌)最近 5 条可用的、最长 30 天(见 store 的 ArchiveBaselineKeep / ArchiveBaselineTTL)。

func (*ArchiveBaseline) IncludeList added in v2.2.0

func (b *ArchiveBaseline) IncludeList() []string

IncludeList 把 Include 还原成类别列表(nil = 全部类别)。

func (*ArchiveBaseline) SetIncludeList added in v2.2.0

func (b *ArchiveBaseline) SetIncludeList(list []string)

SetIncludeList 记下基线的范围。

type ArtifactComment

type ArtifactComment struct {
	ID          uint       `gorm:"primaryKey" json:"id"`
	DocID       uint       `gorm:"not null;index:idx_artifact_comment_doc,priority:1" json:"doc_id"`
	Anchor      string     `gorm:"size:128" json:"anchor,omitempty"`
	Body        string     `gorm:"type:text;not null" json:"body"`
	AuthorKind  string     `gorm:"size:16;not null" json:"author_kind"` // human | identity
	AuthorRef   string     `gorm:"size:64" json:"author_ref,omitempty"`
	AuthorLabel string     `gorm:"size:128" json:"author_label"`
	Resolved    bool       `gorm:"not null;default:false;index:idx_artifact_comment_doc,priority:2" json:"resolved"`
	ResolvedAt  *time.Time `json:"resolved_at,omitempty"`
	CreatedAt   time.Time  `gorm:"index" json:"created_at"`
}

ArtifactComment 是对一篇文档(尤其是 Artifact)的评论 / 批注,Agent 经 project_docs 的 comments 动作读取。

type ArtifactData

type ArtifactData struct {
	ID    uint   `gorm:"primaryKey" json:"id"`
	DocID uint   `gorm:"not null;uniqueIndex:ux_artifact_data,priority:1" json:"doc_id"`
	Key   string `gorm:"column:data_key;size:128;not null;uniqueIndex:ux_artifact_data,priority:2" json:"key"`
	// Value 是合法 JSON 文本。
	Value string `gorm:"type:text;not null" json:"value"`
	// Version 每次写入 +1,用于乐观并发(看板被多个 Agent 同时写时避免互相覆盖)。
	Version      int       `gorm:"not null;default:1" json:"version"`
	UpdatedBy    string    `gorm:"size:128" json:"updated_by"`
	UpdatedAt    time.Time `json:"updated_at"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedByRef string    `gorm:"size:64" json:"updated_by_ref,omitempty"`
}

ArtifactData 是一篇 Artifact(render 为 html / data 的文档)自带的 JSON 键值数据。 设计稿 06 §6:每篇 ≤ 256 KB、≤ 200 键;写入记审计(不记值)。

type AuditEvent

type AuditEvent struct {
	ID         uint      `gorm:"primaryKey;autoIncrement" json:"id"`
	At         time.Time `gorm:"not null;index" json:"at"`
	ProjectID  uint      `gorm:"not null;default:0;index" json:"project_id,omitempty"`
	ActorKind  string    `gorm:"size:16;not null" json:"actor_kind"` // human | identity | token | system(token = 持令牌的脚本 / 智能体,署名是令牌名称 + 自报身份,#272)
	ActorRef   string    `gorm:"size:160;not null;index" json:"actor_ref"`
	ActorLabel string    `gorm:"size:200" json:"actor_label,omitempty"`
	Action     string    `gorm:"size:32;not null;index" json:"action"`
	ScopeKind  string    `gorm:"size:16" json:"scope_kind,omitempty"`
	ScopeRef   string    `gorm:"size:256" json:"scope_ref,omitempty"`
	Target     string    `gorm:"size:512" json:"target,omitempty"`
	Result     string    `gorm:"size:8;not null;default:'allow'" json:"result"`
	Detail     string    `gorm:"type:text" json:"detail,omitempty"` // JSON;不含正文
}

AuditEvent 是一条审计记录。ActorLabel 在写入时快照,改名之后历史不变。

type AuthProfile

type AuthProfile struct {
	ID    uint   `gorm:"primaryKey" json:"id"`
	Name  string `gorm:"size:96;uniqueIndex;not null" json:"name"`
	Level string `gorm:"size:4;not null;default:'L1'" json:"level"`
	// Rules 是写给智能体看的规则摘要(回执里的 auth: 行整行不超过 300 字,名称与档位占用一部分)。
	Rules     string    `gorm:"size:960;not null" json:"rules"`
	IsDefault bool      `gorm:"default:false" json:"is_default"`
	Sort      int       `gorm:"default:0" json:"sort"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

AuthProfile 是全局的授权档位:异步模式下取代「讨论 / 方案 / 开发」阶段提示词,告诉智能体哪些事可以直接做。 默认有一档「标准授权」,其余由用户手动添加;工作流各自选择当前档位。

type BranchExpose added in v2.1.0

type BranchExpose struct {
	History string `json:"history"` // off | summary | full:branch read 能看到的汇报深度
	Decide  bool   `json:"decide"`  // P2:分支的请示能否由主会话定夺
	Say     bool   `json:"say"`     // 主会话能否给分支发消息(分支给主会话发消息恒允许)
	Params  string `json:"params"`  // P3:off | resident | resident_phase | all
	Launch  bool   `json:"launch"`  // P4:主会话能否启动 / 唤醒分支
	Tasks   string `json:"tasks"`   // P5:read | assign(主会话能否把自己建的任务指派给这个分支;同板才有意义)
}

BranchExpose 是分支向主会话开放的范围(只有人能改)。状态(Agent 状态 / 最近活动 / 待答数 / 任务数)恒开,不在这里。 一次定义全部可配的六项;各项由哪一期执行见 2026-10-24-236-p1-impl-plan.md 第 3 节(P1 只执行 History 与 Say)。

func BranchExposePreset added in v2.1.0

func BranchExposePreset(name string) (BranchExpose, bool)

BranchExposePreset 返回预设对应的开放范围。

func ClampExposeWiden added in v2.1.0

func ClampExposeWiden(from, to BranchExpose) (BranchExpose, []string)

ClampExposeWiden 把 to 里「放宽」的部分压回 from 的取值,其余各项照 to:返回压回之后的开放范围与被压回的项名 ("params" / "launch")。用于「终端不可用、没法验证是本人在点」时仍然让其它设置生效,而不放宽授权。 from 里不认识的「改参数」档位按 off 处理(宁紧勿松)。to 本身没有放宽时原样返回。

func (BranchExpose) ExceedsCeiling added in v2.2.0

func (e BranchExpose) ExceedsCeiling(ceiling BranchExpose) []string

ExceedsCeiling 列出 e 比 ceiling 放得更宽的各项(每项一句人话;空 = 没有放宽,即 e 只是收窄或相等)。 history / params / tasks 按档位高低比;decide / say / launch 只有「ceiling 里是关、e 里是开」才算放宽。 用在主会话的 Agent 自己建分支时:它只能收窄开放范围,放宽只能由用户在网页上做(#264 I-3)。

func (BranchExpose) PresetName added in v2.1.0

func (e BranchExpose) PresetName() string

PresetName 返回与当前取值完全一致的预设名;都不一致返回空串(界面显示「自定义」)。

func (*BranchExpose) Scan added in v2.1.0

func (e *BranchExpose) Scan(value interface{}) error

func (BranchExpose) Summary added in v2.1.0

func (e BranchExpose) Summary() string

Summary 是给人 / 智能体看的一行摘要,只列当前版本真正生效的几项:读历史、发消息、定夺请示(P2 起)、改参数(P3 起)、启动(P4 起)、派任务(P5 起)。 一项在预设里有取值、但对应的能力还没实现时不能写进摘要:写出来等于告诉智能体「你可以做」,它会照着去做然后撞墙。 任务这一项(P5 之前就是这种情况)从 P5 起生效,所以现在写进来;不认识的取值按「不可派任务」写(宁紧勿松)。

func (BranchExpose) Validate added in v2.1.0

func (e BranchExpose) Validate() error

Validate 检查各项取值都在枚举里。

func (BranchExpose) Value added in v2.1.0

func (e BranchExpose) Value() (driver.Value, error)

Value / Scan 让它在 SQLite 里存成一列 JSON 文本。

type BranchParamEvent added in v2.1.0

type BranchParamEvent struct {
	ID               uint      `gorm:"primaryKey" json:"id"`
	CreatedAt        time.Time `gorm:"index" json:"created_at"`
	ParentWorkflowID string    `gorm:"size:128;not null;index" json:"parent_workflow_id"`
	BranchWorkflowID string    `gorm:"size:128;not null;index" json:"branch_workflow_id"`
	// Field 是 ParamField* 之一。
	Field string `gorm:"size:16;not null" json:"field"`
	// By 是写入者:agent:<主会话工作流编号> 或 human(用户撤销)。库里的列叫 actor:by 是 SQL 关键字,裸写进查询里容易出事。
	By string `gorm:"column:actor;size:160;not null" json:"by"`
	// Summary 是一句人话(「常驻规则 rev 3」「阶段 讨论 → 开发」),不含常驻 / 唤醒词的全文。
	Summary string `gorm:"size:240;not null" json:"summary"`
	// OldValue / NewValue 是撤销用的旧值与新值全文(常驻规则 ≤1200 字、唤醒词 ≤1500 字,其余很短;异步为 on / off)。
	OldValue string `gorm:"type:text" json:"old_value,omitempty"`
	NewValue string `gorm:"type:text" json:"new_value,omitempty"`
	// Rev 是常驻规则写入后的版本号;其它字段为 0。
	Rev int `gorm:"not null;default:0" json:"rev,omitempty"`
	// ToldAt 是分支的回执 params: 行已经带过这条事件的时间;空 = 还没告诉。
	ToldAt *time.Time `gorm:"index" json:"told_at,omitempty"`
	// RevertedAt / RevertedBy 标记这条事件已被用户撤销;撤销本身另记一条事件,用 RevertOf 指回原事件。
	RevertedAt *time.Time `json:"reverted_at,omitempty"`
	RevertedBy string     `gorm:"size:64" json:"reverted_by,omitempty"`
	RevertOf   uint       `gorm:"index" json:"revert_of,omitempty"`
}

BranchParamEvent 是一次参数写入(或一次撤销)。库里的 ParentWorkflowID / BranchWorkflowID 记事件发生时的关系两端。

func (BranchParamEvent) ByAgent added in v2.1.0

func (e BranchParamEvent) ByAgent() bool

ByAgent 表示这条事件由主会话的智能体写入。

func (BranchParamEvent) IsRevert added in v2.1.0

func (e BranchParamEvent) IsRevert() bool

IsRevert 表示这条事件是用户撤销产生的。

type BranchPrefs added in v2.1.0

type BranchPrefs struct {
	// L2Guard 为真时,风险档为 L2 的请示不允许主会话代答(只能转交用户);默认关(平台不对决策分级,见总方案 D4)。
	L2Guard bool `json:"l2_guard,omitempty"`
	// EscalateMinutes 是升级时限(5~1440 分钟);0 = 没设置过,按默认 30。
	EscalateMinutes int `json:"escalate_minutes,omitempty"`
}

BranchPrefs 是分支的全局偏好。零值 = 出厂默认:兜底开关关、30 分钟升级。

func (BranchPrefs) EscalateAfterMinutes added in v2.1.0

func (p BranchPrefs) EscalateAfterMinutes() int

EscalateAfterMinutes 返回实际生效的升级时限(分钟):没设置过 / 越界(旧值损坏)都按默认处理。

func (BranchPrefs) Validate added in v2.1.0

func (p BranchPrefs) Validate() error

Validate 校验取值:升级时限只能是 0(默认)或 5~1440 分钟。

type ChatMessage

type ChatMessage struct {
	ID             uint        `gorm:"primaryKey" json:"id"`
	ConversationID string      `gorm:"size:64;not null;uniqueIndex:idx_chat_conv_seq,priority:1;index:idx_chat_conv_time,priority:1" json:"conversation_id"`
	Seq            int64       `gorm:"not null;uniqueIndex:idx_chat_conv_seq,priority:2" json:"seq"`
	SenderKind     string      `gorm:"size:16;not null" json:"sender_kind"`
	SenderRef      string      `gorm:"size:128;index:idx_chat_sender" json:"sender_ref"`
	Kind           string      `gorm:"size:16;not null;default:'text'" json:"kind"`
	Body           string      `gorm:"type:text" json:"body"`
	ReplyTo        string      `gorm:"size:32" json:"reply_to,omitempty"` // m:<消息 id>
	Mentions       StringArray `gorm:"type:text" json:"mentions,omitempty"`
	Hop            int         `gorm:"not null;default:0" json:"hop"`
	// IdemKey 是「会话|发送者|幂等键」拼成的整串,唯一;Agent 重试同一条不会重复落库。没有幂等键时为空(空值互不冲突)。
	IdemKey   *string   `gorm:"size:320;uniqueIndex:idx_chat_idem" json:"-"`
	CreatedAt time.Time `gorm:"index:idx_chat_conv_time,priority:2" json:"created_at"`
}

ChatMessage 是群消息,会话内序号 Seq 唯一递增。

type CheckFeedbackInput

type CheckFeedbackInput struct {
	ProjectID                    string `json:"project_id"`
	TaskID                       string `json:"task_id"`
	AfterFeedbackSequence        int64  `json:"after_feedback_sequence"`
	AcknowledgedTaskRevision     int64  `json:"acknowledged_task_revision"`
	AcknowledgedFeedbackSequence int64  `json:"acknowledged_feedback_sequence"`
	IdempotencyKey               string `json:"idempotency_key,omitempty"`
}

type CheckFeedbackResult

type CheckFeedbackResult struct {
	Feedback []Feedback `json:"feedback,omitempty"`
	Wait     WaitStatus `json:"wait"`
}

type CheckpointBasis

type CheckpointBasis struct {
	TaskRevision     int    `json:"task_revision,omitempty"`
	ReportSequence   int    `json:"report_sequence,omitempty"`
	FeedbackSequence int    `json:"feedback_sequence,omitempty"`
	GitCommit        string `json:"git_commit,omitempty"`
	// AnchorSessionID 指向胶囊所基于的那次交付(其 git_commit 与上面的哈希一致),
	// 供 Web 时间线把胶囊与交付关联起来。缺省基准时由服务端自动填写。
	AnchorSessionID string `json:"anchor_session_id,omitempty"`
}

type CheckpointClaim

type CheckpointClaim struct {
	Claim    string   `json:"claim"`
	Evidence []string `json:"evidence,omitempty"`
}

type CheckpointContent

type CheckpointContent struct {
	Basis              CheckpointBasis      `json:"basis"`
	Objective          string               `json:"objective"`
	AcceptanceCriteria []string             `json:"acceptance_criteria,omitempty"`
	CurrentStage       *CheckpointStage     `json:"current_stage,omitempty"`
	Completed          []CheckpointClaim    `json:"completed,omitempty"`
	Decisions          []CheckpointDecision `json:"decisions,omitempty"`
	InProgress         []string             `json:"in_progress,omitempty"`
	NextActions        []string             `json:"next_actions,omitempty"`
	Blockers           []string             `json:"blockers,omitempty"`
	OpenQuestions      []string             `json:"open_questions,omitempty"`
	Constraints        []string             `json:"constraints,omitempty"`
	ChangedFiles       []string             `json:"changed_files,omitempty"`
	Verification       []string             `json:"verification,omitempty"`
	Unknowns           []string             `json:"unknowns,omitempty"`
	ResumeInstruction  string               `json:"resume_instruction,omitempty"`
}

type CheckpointDecision

type CheckpointDecision struct {
	DecisionID string `json:"decision_id"`
	Status     string `json:"status"`
	Summary    string `json:"summary"`
	Supersedes string `json:"supersedes,omitempty"`
	Source     string `json:"source,omitempty"`
}

type CheckpointStage

type CheckpointStage struct {
	ID     string `json:"id"`
	Status string `json:"status"`
}

type ConfirmAnswer

type ConfirmAnswer struct {
	OptionIDs []string `json:"options"`
	Note      string   `json:"note,omitempty"`
	Custom    string   `json:"custom,omitempty"`
	By        string   `json:"by"` // human(Web 登录用户)| agent:<主会话工作流>(分支里的请示由主会话代为定夺,#236 P2;老记录只有 human)
}

ConfirmAnswer 记录一次作答(选项 id 列表 + 可选备注 + 可选的自定义答复 + 作答人来源)。

Custom 是用户觉得「预设选项都不合适」时自己写的答复(#183):单选时与选项互斥(OptionIDs 为空), 多选时可以与选中的选项并存;备注 Note 仍然是对所选内容的补充,两者互不替代。 老答复没有这个字段(JSON 里缺省即为空),界面与智能体都按「没有自定义答复」处理。

type ConfirmEscalation added in v2.1.0

type ConfirmEscalation struct {
	By   string `json:"by"`
	Note string `json:"note,omitempty"`
}

ConfirmEscalation 记录一次转交 / 升级:谁转的、说了什么。

type ConfirmItem

type ConfirmItem struct {
	ID         uint   `gorm:"primaryKey" json:"id"`
	WorkflowID string `gorm:"size:128;not null;uniqueIndex:idx_confirm_wf_seq,priority:1;index:idx_confirm_wf_created,priority:1" json:"workflow_id"`
	Seq        int    `gorm:"not null;uniqueIndex:idx_confirm_wf_seq,priority:2" json:"seq"`

	Kind  string `gorm:"size:16;not null;index" json:"kind"`
	Title string `gorm:"size:200;not null" json:"title"`
	Body  string `gorm:"type:text" json:"body,omitempty"`

	OptionsJSON   string `gorm:"type:text;not null" json:"-"`
	Multi         bool   `gorm:"not null;default:false" json:"multi"`
	AllowNote     bool   `gorm:"not null;default:false" json:"allow_note"`
	DefaultOption string `gorm:"size:64" json:"default_option,omitempty"`
	Risk          string `gorm:"size:4;not null;default:'L1';index" json:"risk"`

	TaskSeq   int    `gorm:"not null;default:0;index" json:"task_seq,omitempty"`
	DocID     uint   `gorm:"not null;default:0;index" json:"doc_id,omitempty"`
	DocKey    string `gorm:"size:64;index" json:"doc_key,omitempty"`
	Anchor    string `gorm:"size:200" json:"anchor,omitempty"`
	OptionsFP string `gorm:"size:64;index" json:"options_fp,omitempty"` // 选项指纹:文档决策卡选项是否变化的判据

	Status      string     `gorm:"size:16;not null;default:'pending';index" json:"status"`
	AnswerJSON  string     `gorm:"type:text" json:"-"`
	AnsweredAt  *time.Time `json:"answered_at,omitempty"`
	DeliveredAt *time.Time `json:"delivered_at,omitempty"` // 答复被智能体读到的时间(预留;当前由收件箱状态承载)

	CreatedBy string    `gorm:"size:16;not null" json:"created_by"`
	CreatedAt time.Time `gorm:"index:idx_confirm_wf_created,priority:2" json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`

	// 决策路由(#236 P2),三列都可空:空 = 和以前完全一样(直接给用户)。
	//   - Addressee:wf:<主会话工作流> = 先送主会话定夺;转交 / 升级时清空,作答后保留(用来标注「这条曾路由给主会话」);
	//   - EscalatedAt:主会话转交 / 超时升级 / 关系结束善后的时刻;
	//   - EscalationJSON:{"by":…,"note":…}(见 ConfirmEscalation)。
	Addressee      string     `gorm:"size:160;index" json:"addressee,omitempty"`
	EscalatedAt    *time.Time `json:"escalated_at,omitempty"`
	EscalationJSON string     `gorm:"type:text" json:"-"`
}

func (ConfirmItem) RoutedToMain added in v2.1.0

func (c ConfirmItem) RoutedToMain() bool

RoutedToMain 报告这条请示此刻是否在等主会话定夺(路由给了主会话、仍待处理)。

type ConfirmItemCounter

type ConfirmItemCounter struct {
	WorkflowID string `gorm:"primaryKey;size:128" json:"workflow_id"`
	LastSeq    int    `gorm:"not null;default:0" json:"last_seq"`
}

ConfirmItemCounter 保证工作流内确认项序号不复用(即使中间的项被删除)。

type ConfirmItemView

type ConfirmItemView struct {
	ID            uint            `json:"id"`
	WorkflowID    string          `json:"workflow_id"`
	Seq           int             `json:"seq"`
	Ref           string          `json:"ref"`
	Kind          string          `json:"kind"`
	Title         string          `json:"title"`
	Body          string          `json:"body,omitempty"`
	Options       []ConfirmOption `json:"options"`
	Multi         bool            `json:"multi"`
	AllowNote     bool            `json:"allow_note"`
	DefaultOption string          `json:"default_option,omitempty"`
	Risk          string          `json:"risk"`
	TaskSeq       int             `json:"task_seq,omitempty"`
	DocID         uint            `json:"doc_id,omitempty"`
	DocKey        string          `json:"doc_key,omitempty"`
	DocPath       string          `json:"doc_path,omitempty"`
	DocTitle      string          `json:"doc_title,omitempty"`
	Anchor        string          `json:"anchor,omitempty"`
	Status        string          `json:"status"`
	Answer        *ConfirmAnswer  `json:"answer,omitempty"`
	AnsweredAt    *time.Time      `json:"answered_at,omitempty"`
	CreatedBy     string          `json:"created_by"`
	CreatedAt     time.Time       `json:"created_at"`
	UpdatedAt     time.Time       `json:"updated_at"`

	// 决策路由(#236 P2):Addressee 非空且 Status=pending = 在等主会话定夺;Escalated* 有值 = 主会话转交 / 超时升级给了用户。
	Addressee   string             `json:"addressee,omitempty"`
	EscalatedAt *time.Time         `json:"escalated_at,omitempty"`
	Escalation  *ConfirmEscalation `json:"escalation,omitempty"`
}

ConfirmItemView 是对外(REST / MCP)的确认项视图:选项与答复已解码,绑定的文档带路径与标题。

func NewConfirmItemView

func NewConfirmItemView(item *ConfirmItem) ConfirmItemView

NewConfirmItemView 把库里的行转成对外视图(选项 JSON 损坏时返回空选项,不让一行脏数据拖垮整个列表)。

type ConfirmOption

type ConfirmOption struct {
	ID          string `json:"id"`
	Label       string `json:"label"`
	Detail      string `json:"detail,omitempty"`
	Recommended bool   `json:"recommended,omitempty"`
}

ConfirmOption 是确认项里的一个可选项。

type Conversation

type Conversation struct {
	ID         string     `gorm:"primaryKey;size:64" json:"id"` // grp:<8 位十六进制>
	Kind       string     `gorm:"size:16;not null;default:'group'" json:"kind"`
	Title      string     `gorm:"size:120;not null" json:"title"`
	ProjectID  string     `gorm:"size:128" json:"project_id,omitempty"` // 可选绑定的项目(跨项目群留空)
	CreatedBy  string     `gorm:"size:64" json:"created_by"`
	Settings   string     `gorm:"type:text" json:"settings,omitempty"` // JSON,预留
	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
	ArchivedAt *time.Time `json:"archived_at,omitempty"`
}

Conversation 是一个群。1:1 会话不建行。

type ConversationEvent

type ConversationEvent struct {
	ID             uint      `gorm:"primaryKey" json:"id"`
	ConversationID string    `gorm:"size:160;not null;index:idx_conv_event_time,priority:1" json:"conversation_id"`
	WorkflowID     string    `gorm:"size:128;index" json:"workflow_id"`
	Kind           string    `gorm:"size:24;not null" json:"kind"`
	ActorKind      string    `gorm:"size:16" json:"actor_kind,omitempty"` // human | workflow | system
	ActorRef       string    `gorm:"size:128" json:"actor_ref,omitempty"`
	Text           string    `gorm:"size:400" json:"text"`
	Meta           string    `gorm:"type:text" json:"meta,omitempty"`
	CreatedAt      time.Time `gorm:"index:idx_conv_event_time,priority:2" json:"created_at"`
}

ConversationEvent 是会话时间线上的一条系统行(居中灰字):模式切换、Agent 收尾等。 文字是给人看的一句话,不含任何提示词或正文;需要结构化信息时放 Meta(JSON)。

type ConversationMember

type ConversationMember struct {
	ID             uint       `gorm:"primaryKey" json:"id"`
	ConversationID string     `gorm:"size:64;not null;uniqueIndex:idx_conv_member,priority:1" json:"conversation_id"`
	MemberKind     string     `gorm:"size:16;not null;uniqueIndex:idx_conv_member,priority:2" json:"member_kind"`
	MemberRef      string     `gorm:"size:128;not null;uniqueIndex:idx_conv_member,priority:3" json:"member_ref"`
	Role           string     `gorm:"size:16;not null;default:'member'" json:"role"`
	AddedBy        string     `gorm:"size:64" json:"added_by"`
	JoinedAt       time.Time  `json:"joined_at"`
	LeftAt         *time.Time `json:"left_at,omitempty"`
	PushPolicy     string     `gorm:"size:16;not null;default:'mentions'" json:"push_policy"`
	MutedUntil     *time.Time `json:"muted_until,omitempty"`
}

ConversationMember 是群成员。成员单位是工作流;离开后保留一行(LeftAt 不为空),看不到离开之后的消息。

type ConversationRead

type ConversationRead struct {
	ID             uint      `gorm:"primaryKey" json:"id"`
	ConversationID string    `gorm:"size:160;not null;uniqueIndex:idx_conv_reader,priority:1" json:"conversation_id"`
	ReaderKind     string    `gorm:"size:16;not null;uniqueIndex:idx_conv_reader,priority:2" json:"reader_kind"`
	ReaderRef      string    `gorm:"size:128;not null;uniqueIndex:idx_conv_reader,priority:3" json:"reader_ref"`
	ReadMs         int64     `gorm:"not null;default:0" json:"read_ms"`
	ReadSeq        int64     `gorm:"not null;default:0" json:"read_seq"`
	UpdatedAt      time.Time `json:"updated_at"`
}

ConversationRead 是已读游标:每个会话、每个读者一行。

1:1 会话的消息没有序号,按「发送时间(Unix 毫秒)」推进,读到的位置存在 ReadMs; 群会话(阶段 2b)的消息有会话内序号,存在 ReadSeq。两者互不干扰,各自只增不减。

type CreateTaskInput

type CreateTaskInput struct {
	ProjectID      string     `json:"project_id"`
	TaskID         string     `json:"task_id,omitempty"`
	Title          string     `json:"title,omitempty"`
	Mode           string     `json:"mode,omitempty"`
	Stages         TaskStages `json:"stages,omitempty"`
	Segments       []Segment  `json:"segments"`
	WaitPolicy     WaitPolicy `json:"wait_policy"`
	IdempotencyKey string     `json:"idempotency_key,omitempty"`
}

type DraftImage

type DraftImage struct {
	WorkflowID string `gorm:"primaryKey;size:128" json:"workflow_id"`
	// Key 是前端对整段正文算出的内容键(长度 + 53 位哈希),服务端只当作不透明标识使用。
	Key      string `gorm:"primaryKey;size:96" json:"key"`
	Name     string `gorm:"size:255" json:"name,omitempty"`
	Format   string `gorm:"size:16" json:"format,omitempty"`
	DataType string `gorm:"size:16" json:"data_type,omitempty"`
	Hash     string `gorm:"size:64" json:"hash,omitempty"`
	Width    int    `json:"width,omitempty"`
	Height   int    `json:"height,omitempty"`
	// Size 是正文(Base64 文本)的长度,用于配额统计,列表时不必读出正文。
	Size int    `json:"size"`
	Data string `gorm:"type:text" json:"data,omitempty"`
	// UpdatedAt 是最近一次写入(上传 / 重新确认)的时间,后台清理据此判断「遗弃多久了」。
	UpdatedAt time.Time `gorm:"index" json:"updated_at"`
}

DraftImage 草稿区的一张图片(云存储):粘贴即上传,草稿 JSON 里只留引用; 提交时会话直接复用这份正文(不再重传),草稿销毁时删除。主键 (工作流, 内容键):同一张图在一个工作流里只存一份。

type EmbedChunk added in v2.2.0

type EmbedChunk struct {
	ID    uint    `gorm:"primaryKey" json:"-"`
	Kind  string  `gorm:"size:16;not null;uniqueIndex:uq_embed_chunk,priority:1" json:"-"`
	Ref   string  `gorm:"size:128;not null;uniqueIndex:uq_embed_chunk,priority:2" json:"-"`
	Seq   int     `gorm:"not null;uniqueIndex:uq_embed_chunk,priority:3" json:"-"`
	Hash  string  `gorm:"size:40;not null" json:"-"`
	Dims  int     `gorm:"not null" json:"-"`
	Scale float32 `gorm:"not null" json:"-"`
	Vec   []byte  `gorm:"type:blob;not null" json:"-"`
}

EmbedChunk 是一块的向量:先 L2 归一化,再按向量内最大绝对值做对称 int8 量化(Scale = 最大值 / 127)。 不存块的原文:要片段时用回源后的活文本按同一个确定性切块函数重切,取第 Seq 块。

type EmbedCredential added in v2.2.0

type EmbedCredential struct {
	Name      string    `gorm:"primaryKey;size:32" json:"-"`
	Sealed    string    `gorm:"type:text;not null" json:"-"` // v1:… AES-256-GCM 密文,AAD 绑定 BoundHost
	Last4     string    `gorm:"size:4" json:"-"`             // 给界面看的末四位;密钥太短时为空
	BoundHost string    `gorm:"size:255;not null" json:"-"`  // 密钥所属服务的 主机:端口
	UpdatedAt time.Time `json:"-"`
}

EmbedCredential 是在线嵌入服务的 API Key,密封后保存(#266 第 2 步,见 internal/embedding/vault.go)。

单独成表而不是放进 system_settings:后者可能被整体读取或导出,独立的表不会被误带出去。 每个字段都标 json:"-":这张表的任何行都不该被序列化到接口或日志里,连密文也不例外。 主密钥在数据目录的 master.key 文件里,不在库里——所以只拿到数据库文件(备份、回滚点)读不出密钥。

type EmbedEntry added in v2.2.0

type EmbedEntry struct {
	Kind           string    `gorm:"primaryKey;size:16" json:"kind"`
	Ref            string    `gorm:"primaryKey;size:128" json:"ref"`
	FP             string    `gorm:"size:255" json:"-"`                           // 源版本戳(与词法索引同一份 SQL 表达式)
	TextHash       string    `gorm:"size:40" json:"-"`                            // 清洗后「标题 + 正文」的哈希
	Sig            string    `gorm:"size:200;index:idx_embed_entry_sig" json:"-"` // 模型|维度;与当前配置不同的向量不参与查询
	Chunks         int       `json:"chunks"`
	State          string    `gorm:"size:16" json:"state"` // ok | skipped
	Truncated      bool      `json:"truncated"`
	ChunkCap       int       `gorm:"not null;default:0" json:"-"` // 嵌入时的单条块数上限(0 = 旧数据,按 200 算);上限提高时据此只重做被截断的条目
	WorkflowID     string    `gorm:"size:100" json:"-"`
	ProjectID      uint      `json:"-"`
	ConversationID string    `gorm:"size:100" json:"-"`
	UpdatedAt      time.Time `json:"updated_at"`
}

EmbedEntry 是一个已处理的源条目:已嵌入(ok)或判定为不嵌入(skipped:太短 / 几乎全是被隐去的内容)。

Kind 与 Ref 同词法索引(文档 / 任务 / 确认项 / 会话汇报按各自主键;群消息是 "<会话 ID>/<段号>",一段 200 条消息)。 WorkflowID / ProjectID / ConversationID 是嵌入时源行归属的快照,只用来在内存里先筛范围; 命中交出去之前仍按源行的真实归属再核一遍(V4)。

type EmbedProject added in v2.2.0

type EmbedProject struct {
	ProjectID uint      `gorm:"primaryKey;autoIncrement:false" json:"project_id"`
	EnabledAt time.Time `json:"enabled_at"`
}

EmbedProject 是勾选了语义检索的项目。取消勾选 = 删行并清掉只因它而存在的向量(V8:撤回同意即删)。

type EmbedUsage added in v2.2.0

type EmbedUsage struct {
	Day       string    `gorm:"primaryKey;size:10" json:"day"` // YYYY-MM-DD
	Requests  int64     `gorm:"not null;default:0" json:"requests"`
	Tokens    int64     `gorm:"not null;default:0" json:"tokens"`
	Errors    int64     `gorm:"not null;default:0" json:"errors"`
	UpdatedAt time.Time `json:"updated_at"`
}

EmbedUsage 是嵌入服务按天(Hub 本地日期)的用量。次数包含失败的尝试;超过 400 天的行在写入时顺手清理。

type Feedback

type Feedback struct {
	ID             uint           `gorm:"primaryKey" json:"-"`
	TaskID         string         `gorm:"index;not null;size:128" json:"task_id"`
	Sequence       int64          `gorm:"not null" json:"sequence"`
	TaskRevision   int64          `gorm:"default:0" json:"task_revision"`
	Source         string         `gorm:"size:32;default:'human'" json:"source"` // "human" | "commander"
	Body           string         `gorm:"type:text;not null" json:"body"`
	References     PathReferences `gorm:"type:text" json:"references,omitempty"`
	IdempotencyKey string         `gorm:"size:128;index" json:"idempotency_key,omitempty"`
	CreatedAt      time.Time      `json:"created_at"`
}

type FeedbackSession

type FeedbackSession struct {
	ID string `gorm:"primaryKey;size:128" json:"session_id"`
	// WorkflowID 另有一个与 CreatedAt 的复合索引:聊天消息流按「工作流 + 时间」分页取(设计稿 03),不走它就是全表排序。
	// 与 UpdatedAt / ProjectDirectory / HostName 还有一个覆盖索引 idx_fs_wf_proj:项目成员解析(ProjectWorkflowIDs,每个工作流取「最近一条带目录的会话」)
	// 要读 updated_at,它在 summary / response_text 这些大文本列之后,没有覆盖索引就得逐行翻溢出页(2 万会话约 230 ms,有了约 9 ms)。
	WorkflowID string `gorm:"index;index:idx_fs_wf_created,priority:1;index:idx_fs_wf_proj,priority:1;size:128" json:"workflow_id"`
	// Kind 区分常规阻塞式汇报与异步模式下不阻塞发布的进度气泡:空串 / feedback 是前者,notice 是后者
	//(见 workflow_mode.go)。库里不写 feedback,旧会话与旧版本保持原样,接口里也只在 notice 时才有这个字段。
	Kind string `gorm:"size:16" json:"kind,omitempty"`
	// NoticeLevel 是进度通知的强调级别(#275):空串 = 普通;key = 「重点」,网页上要用户滑动确认「已收到」。
	// 只有 kind = notice 的行才可能是 key;库里不写 normal,旧会话与旧版本保持原样,接口里也只在 key 时才有这个字段。
	// 可空的只增列:旧二进制可打开新库,历史会话保持空值。
	NoticeLevel string `gorm:"size:16" json:"notice_level,omitempty"`
	// AckedAt 是用户在网页上确认「已收到」这条重点通知的时间;空 = 还没确认(或不是重点通知)。
	// 确认只是网页侧的记录:不反向通知智能体、不进收件箱、不影响任何等待与收尾。可空的只增列。
	AckedAt          *time.Time `json:"acked_at,omitempty"`
	CredentialID     *uint      `gorm:"index" json:"credential_id,omitempty"`
	HostName         string     `gorm:"size:128;index:idx_fs_wf_proj,priority:4" json:"host_name,omitempty"`
	ProjectDirectory string     `gorm:"size:512;index:idx_fs_wf_proj,priority:3" json:"project_directory"`
	Title            string     `gorm:"size:256" json:"title"`
	Summary          string     `gorm:"type:text;not null" json:"summary"`
	// Status 与 CreatedAt 另有复合索引 idx_fs_status_created:「当前待答会话」(GET /sessions/current,各页面轮询)按
	// status = 'pending' 过滤再按创建时间倒序取 1 行,没有它就是整表扫描 + 临时排序(#177)。
	Status               string        `gorm:"size:32;default:'pending';index:idx_fs_status_created,priority:1" json:"status"` // pending, completed, timeout, cancelled, archived
	ResponseText         string        `gorm:"type:text" json:"response_text"`
	UserMessages         StringArray   `gorm:"type:text" json:"user_messages"`
	Images               SessionImages `gorm:"type:text" json:"images"`
	ConsumedByAI         bool          `gorm:"default:false" json:"consumed_by_ai"`
	ConsumedAt           *time.Time    `json:"consumed_at,omitempty"`
	RespondedAt          *time.Time    `json:"responded_at,omitempty"`
	TimeoutSeconds       int           `gorm:"default:600" json:"timeout_seconds"`
	NoFeedbackChecks     int           `gorm:"default:0" json:"no_feedback_checks"`
	MaxNoFeedbackChecks  int           `gorm:"default:24" json:"max_no_feedback_checks"`
	PromptWaitMinutes    int           `gorm:"default:2" json:"prompt_wait_minutes"`
	WaitCountdownMinutes int           `gorm:"default:2" json:"wait_countdown_minutes"`
	// WaitCountdownSeconds 是秒级的挂起倒计时(秒回 0 / 30 / 60 …);-1 表示没设过,沿用 WaitCountdownMinutes(#121)。
	WaitCountdownSeconds int        `gorm:"default:-1" json:"wait_countdown_seconds"`
	IsMCPActive          bool       `gorm:"-" json:"is_mcp_active"`
	MCPActiveAt          *time.Time `gorm:"-" json:"mcp_active_at,omitempty"`
	MCPTimeoutSec        int        `gorm:"-" json:"mcp_timeout_seconds,omitempty"`
	LastKeepaliveAt      *time.Time `gorm:"-" json:"last_keepalive_at,omitempty"`
	DeadlineAt           *time.Time `json:"deadline_at,omitempty"`
	GitCommit            string     `gorm:"size:40" json:"git_commit,omitempty"`
	GitSubject           string     `gorm:"size:200" json:"git_subject,omitempty"`
	// ReplyHints 是挂在用户回复上的「相关线索」(#303 D,Q191 a):用户回复(或有追加并进这一轮)后,服务端在后台按消息的含义
	// 做一次语义检索,把可能相关的旧内容记在这里;智能体读到这条回复时一并看到,只是线索,不是指令。
	// ReplyHintsAt 是线索算好写入的时间:晚于 ConsumedAt 说明智能体读的时候还没算好,那一次就没带上(网页上会如实标出)。
	// 都是可空的只增列:旧二进制可打开新库,没有线索(绝大多数回复)保持 NULL,接口里也不输出。
	ReplyHints   Hints      `gorm:"type:text" json:"reply_hints,omitempty"`
	ReplyHintsAt *time.Time `json:"reply_hints_at,omitempty"`
	// CreatedAt 还有两个索引:单列 idx_fs_created 让「按创建时间倒序取最新 N 行」(侧栏会话列表的窗口查询)直接顺着索引读 N 行,
	// 不再整表扫描 + 临时排序;与 Status 的复合索引 idx_fs_status_created 见上(#177,向后兼容的只增索引,旧版本照常读写)。
	CreatedAt time.Time `gorm:"index:idx_fs_wf_created,priority:2;index:idx_fs_created;index:idx_fs_status_created,priority:2" json:"created_at"`
	UpdatedAt time.Time `gorm:"index:idx_fs_wf_proj,priority:2" json:"updated_at"`

	// 以下两项是「整个工作流」的只读聚合(不入库):只有会话列表与当前会话接口会带,侧栏会话卡据此推出会话级状态(#159)。
	// 用指针 + omitempty:没带(nil)与「带了、值为 0」要能区分——前者表示旧服务端 / 没算,后者表示确实没有待处理。
	PendingConfirmCount *int       `gorm:"-" json:"pending_confirm_count,omitempty"`
	AgentLastActivityAt *time.Time `gorm:"-" json:"agent_last_activity_at,omitempty"`
	// UnackedKeyNotices 是这个工作流里还没确认的「重点」通知条数(#275,不含已归档的会话):侧栏会话卡的「重点」徽标要的是整个工作流的总数,
	// 而不是列表窗口里恰好带出的行。同样用指针 + omitempty:没带(nil)表示旧服务端 / 没算,带了 0 表示确实没有。
	UnackedKeyNotices *int `gorm:"-" json:"unacked_key_notices,omitempty"`
	// WorkflowRounds 是这个工作流在库里一共有多少行会话(含已归档,#173):侧栏「N 轮」徽标要的是总数,
	// 而不是列表里恰好带出的行数(列表只带最新一批,老工作流往往只剩一行)。没算出来(nil)时前端退回按列表里的行数显示。
	WorkflowRounds *int `gorm:"-" json:"workflow_rounds,omitempty"`
	// BodyOmitted 标记「轻量行」(#169 第二期):工作流会话表在 light 模式下,较早的行只带首行预览(summary / response_text 被截成第一行),
	// user_messages 与 images 为空,完整正文要按 id 另取(GET /workflows/{id}/sessions/bodies)。不入库;不是轻量行时不出现在响应里。
	BodyOmitted bool `gorm:"-" json:"body_omitted,omitempty"`
}

FeedbackSession 是一次「AI 交付 + 人类回复」的轮次。

交付锚点(GitCommit / GitSubject):模型随本次交付申报的「仓库最新提交」;时间不单独存, 就是本会话的 CreatedAt(服务端时间)。两列均为可空的只增列:旧二进制可打开新库,历史会话保持空值。

回复时间(RespondedAt):人类提交这条回复的时刻——合并追加时保留第一次,撤回后清空,「秒回」取走收件箱时取其中最早一条的创建时间。 不能用 UpdatedAt 代替:智能体取走回复时 UpdatedAt 会被刷新,页面上「您的确认回复」的时间就成了「被取走」的时间。 同样是可空的只增列,历史会话保持空值(界面回退到 UpdatedAt)。

func (*FeedbackSession) HoldSeconds

func (s *FeedbackSession) HoldSeconds() (int, bool)

HoldSeconds 返回秒级挂起倒计时;没有设过(-1)时 ok=false,调用方回落到分钟值。

type GroupTrash added in v2.2.0

type GroupTrash struct {
	ID      uint   `gorm:"primaryKey" json:"id"`
	GroupID string `gorm:"size:64;not null;index" json:"group_id"`
	// Title 是删除时的群名(也就是确认框要求输入的名字),只用于「最近删除」列表展示。
	Title string `gorm:"size:256" json:"title"`
	// ProjectID 是删除时群绑定的项目(原样的字符串;跨项目群为空)。
	ProjectID string `gorm:"size:128" json:"project_id,omitempty"`
	// Members / ActiveMembers / Messages 是快照里的成员行数(含「你」与已离开的)、删除时仍在群里的工作流成员数、消息行数(含系统行),
	// 只给列表展示用;恢复时以快照内容为准。
	Members       int `json:"members"`
	ActiveMembers int `json:"active_members"`
	Messages      int `json:"messages"`
	// GrantCount 是被撤销的群级授权条数;RevokedGrants 是这些授权的清单(JSON,只含授权的元数据,不含任何正文)。
	GrantCount    int    `json:"revoked_grants"`
	RevokedGrants string `gorm:"type:text" json:"-"`
	// SizeBytes 是快照(压缩后)占用的字节数。
	SizeBytes int64 `json:"size_bytes"`
	// FormatVersion 是快照格式的版本,将来换格式时靠它区分。
	FormatVersion int       `gorm:"not null;default:1" json:"-"`
	TrashedAt     time.Time `gorm:"index" json:"trashed_at"`
	// ExpiresAt 之后后台清理会把这一条彻底删掉。
	ExpiresAt time.Time `gorm:"index" json:"expires_at"`
	// Payload 是 gzip 压缩的 JSON Lines(逐条记录,恢复时逐条读);列表接口从不读它。
	Payload []byte `gorm:"type:blob" json:"-"`
}

GroupTrash 是群聊回收站里的一条(#321,Q209 选 a):一个已归档的群在被删除那一刻的完整快照。

为什么和会话回收站(WorkflowTrash)是两张表、而不是给那张表加一个「类型」列:旧版本的二进制打开新库时会忽略它不认识的表, 但如果在既有的 workflow_trash 里混进群聊条目,旧版本会把它们当成会话去列出、恢复,恢复出来的就是一堆对不上的东西。 单独一张只增表,回滚到旧版本时它原样留在库里,什么都不影响。

快照里有什么:群本身(含它绑定的项目)、全部成员行(含「你」与已离开的)、全部消息行(含系统行,保留序号与编号)、各读者的已读位置。 没有的:项目、会话(工作流)、任务、确认项本身——它们从来不属于群,删除时原样不动;群级授权不进快照,而是被撤销, 撤销清单(RevokedGrants)只用来在恢复之后告诉用户「这些授权被撤销了」,**恢复不会把授权还回去**。

type Hint added in v2.2.0

type Hint struct {
	Kind string `json:"kind"` // doc / task / confirm / session(与 search 的 kinds 同名)
	// Ref 是给人和智能体看的引用,写成能直接拿去用的样子:d12 / #274 / Q151 / sess-xxxxxxxx。
	Ref string `json:"ref"`
	// RawRef 是命中在库里的引用(文档 / 任务 / 确认项的主键,会话的编号):投递给智能体时按它再判一次读权限,也用来去重。
	RawRef string `json:"raw_ref"`
	// WorkflowID 是命中所属的工作流:项目权限(ACL)判定要用;文档以库里的归属为准,这里只是兜底。
	WorkflowID string `json:"workflow_id,omitempty"`
	Title      string `json:"title"`
	// At 是命中内容最近一次更新的时间(不是线索算出来的时间)。
	At time.Time `json:"at"`
	// Score 是语义相似度(余弦,0–1,保留 3 位)。
	Score float64 `json:"score"`
}

Hint 是挂在一条用户消息上的一条「相关线索」(#303 D,Q191 a):用户给智能体发消息时,服务端在后台按这条消息的含义 做一次语义检索,把可能相关的旧内容(文档 / 任务 / 确认项 / 会话轮次)记成线索存在这条消息上。 智能体读到这条消息时一并看到「时间 · 类型 · 标题 · 编号」,需要时再自己用 search / project_docs 去看全文; 线索只是线索,不是指令,也不会展开正文。

一条线索只记「它指向什么」,不记内容:标题是写入时已经净化过的单行短文本(见 internal/mcp/hints.go),正文永远不进这里。

func (Hint) Key added in v2.2.0

func (h Hint) Key() string

Key 是去重用的键:同一类型下同一个库内引用只算一条。

type Hints added in v2.2.0

type Hints []Hint

Hints 是一条消息上的线索列表,按相似度从高到低排列。存成 JSON 文本列;没有线索时存 NULL(不是 "[]"), 绝大多数消息都没有线索,不为它们多占行空间;读出来是 nil,接口里不输出这个字段。

func MergeHints added in v2.2.0

func MergeHints(max int, groups ...Hints) Hints

MergeHints 把几组线索并成一组:同一条(类型 + 库内引用)只留相似度高的那份,按相似度从高到低排,最多留 max 条(max ≤ 0 不限)。 不改入参;结果为空时返回 nil。

func (*Hints) Scan added in v2.2.0

func (h *Hints) Scan(value interface{}) error

func (Hints) Value added in v2.2.0

func (h Hints) Value() (driver.Value, error)

type MCPCredential

type MCPCredential struct {
	ID          uint        `gorm:"primaryKey" json:"id"`
	Name        string      `gorm:"size:128;uniqueIndex;not null" json:"name"`
	Token       string      `gorm:"size:256;uniqueIndex;not null" json:"token"`
	HostName    string      `gorm:"size:128" json:"host_name"`
	IsActive    bool        `gorm:"default:true" json:"is_active"`
	Permissions Permissions `gorm:"type:text" json:"permissions"`
	Note        string      `gorm:"size:512" json:"note"`
	CreatedAt   time.Time   `json:"created_at"`
	UpdatedAt   time.Time   `json:"updated_at"`

	// 终端相关(只增字段,旧库自动迁移,旧版二进制仍可打开)。
	TerminalHosts   StringList     `gorm:"type:text" json:"terminal_hosts"`                     // 可用主机机器码;["*"] 表示全部;空表示无
	TerminalModeCap string         `gorm:"size:16" json:"terminal_mode_cap"`                    // "" 跟随主机 / auto / approve / readonly(只能比主机更严)
	TerminalLimits  TerminalLimits `gorm:"type:text" json:"terminal_limits"`                    // 令牌级限额,默认不设限
	ExpiresAt       *time.Time     `json:"expires_at"`                                          // 过期时间;为空表示不过期
	AllowedCIDRs    StringList     `gorm:"column:allowed_cidrs;type:text" json:"allowed_cidrs"` // 来源 IP 白名单(CIDR 或单个 IP);空表示不限
	LastUsedAt      *time.Time     `json:"last_used_at"`
	LastUsedIP      string         `gorm:"size:64" json:"last_used_ip"`

	// ArchiveProjects 是这把令牌允许导出归档的项目编号(#272)。带 Permissions.Archive 位时必须非空;
	// 没有该位时它只是一个被保留的设置,不产生任何访问。导出时服务端只认这份名单——调用里自报的身份不是安全边界,令牌才是。
	ArchiveProjects UintList `gorm:"type:text" json:"archive_projects"`

	// Capability 表示这是一把「能力 URL」凭据:令牌本身是网址的一部分(/mcp/c/<令牌>),给无法发送请求头的客户端
	// (例如只能填一个网址的自定义连接器)使用。它只在该网址上有效(请求头 / 查询串 / 旧式路径一律不认),
	// 只能是 ExecMesh 档并逐台授权主机,创建后不可更改。
	Capability bool `gorm:"default:false" json:"capability"`

	// Hidden 为 true 时凭据由 OAuth 授权自动创建,不在默认列表与手动创建接口中暴露。
	Hidden bool `gorm:"default:false" json:"hidden"`
	// OAuthSource 标记凭据来源(如 oauth);空表示普通手动令牌。
	OAuthSource  string `gorm:"size:32" json:"oauth_source,omitempty"`
	OAuthGrantID *uint  `gorm:"index" json:"oauth_grant_id,omitempty"`
}

func (MCPCredential) AllowsTerminalHost

func (c MCPCredential) AllowsTerminalHost(machineCode string) bool

AllowsTerminalHost 判断令牌是否可使用指定机器码的主机。

func (MCPCredential) CapabilityProblem

func (c MCPCredential) CapabilityProblem() string

CapabilityProblem 检查能力 URL 凭据必须长期满足的约束;不是能力 URL 凭据,或没有问题时返回空串。 创建 / 更新时用它拒绝违规配置,运行时再用它兜底(例如数据库被手工改动过)。

func (MCPCredential) IsOAuthOwned added in v2.2.0

func (c MCPCredential) IsOAuthOwned() bool

IsOAuthOwned 报告这把凭据是否由某次 OAuth 授权自动创建并绑定(隐藏 + 来源 oauth + 指向一条授权)。 这类凭据没有可用的令牌:连接器手里拿的是 OAuth 访问令牌(rmo_…),而权限、有效期、来源限制与启停都以这条记录为准, 所以管理员在「MCP 凭据管理」里改它,下一次调用就生效。

type MsgActor added in v2.1.0

type MsgActor struct {
	Kind     string `json:"kind"`
	Workflow string `json:"workflow,omitempty"`
}

MsgActor 是一条消息的发言者:紧凑 JSON 存在 queued_feedbacks.actor 里;空 = 和以前一样(用户 / 本会话 Agent)。

func ParseMsgActor added in v2.1.0

func ParseMsgActor(s string) (MsgActor, bool)

ParseMsgActor 解析库里的 actor 文本;空串或不合法返回 false。

func (MsgActor) String added in v2.1.0

func (a MsgActor) String() string

String 是入库的紧凑 JSON;空发言者返回空串。

type MutationResult

type MutationResult struct {
	TaskID   string `json:"task_id"`
	Revision int64  `json:"revision"`
	State    string `json:"state,omitempty"`
}

type OAuthAccessToken

type OAuthAccessToken struct {
	TokenHash string    `gorm:"primaryKey;size:64" json:"-"`
	GrantID   uint      `gorm:"index;not null" json:"grant_id"`
	ExpiresAt time.Time `gorm:"index" json:"expires_at"`
	CreatedAt time.Time `json:"created_at"`
}

OAuthAccessToken 存访问令牌的 SHA-256(明文 rmo_ 只在签发时返回一次)。

type OAuthClient

type OAuthClient struct {
	ClientID      string     `gorm:"primaryKey;size:512" json:"client_id"`
	ClientName    string     `gorm:"size:256" json:"client_name"`
	RedirectURIs  StringList `gorm:"type:text" json:"redirect_uris"`
	GrantTypes    StringList `gorm:"type:text" json:"grant_types"`
	ResponseTypes StringList `gorm:"type:text" json:"response_types"`
	TokenAuth     string     `gorm:"size:32" json:"token_endpoint_auth_method"` // none
	CreatedAt     time.Time  `json:"created_at"`
	LastUsedAt    *time.Time `json:"last_used_at"`
	// CreatedIP 是登记(POST /oauth/register)时的来源地址(#239),只给管理员在设置页「刚登记、还没授权的客户端」
	// 清单里核对用;json:"-" 让这个模型无论从哪条路径序列化都不会带上它,清单接口用自己的行结构显式给出。
	// 这一列是可空的增量列:旧版本登记的客户端为空,旧版本读取到这一列也直接忽略。
	CreatedIP string `gorm:"size:64" json:"-"`
}

OAuthClient 表示通过 DCR 注册的动态客户端;CIMD 客户端不落库,只在授权时校验元数据。

type OAuthGrant

type OAuthGrant struct {
	ID                  uint       `gorm:"primaryKey" json:"id"`
	ClientID            string     `gorm:"index;size:512;not null" json:"client_id"`
	ClientDisplayName   string     `gorm:"size:256" json:"client_display_name"`
	RedirectURI         string     `gorm:"size:2048" json:"redirect_uri"`
	Resource            string     `gorm:"size:2048" json:"resource"`
	Scopes              StringList `gorm:"type:text" json:"scopes"`
	CredentialID        uint       `gorm:"index;not null" json:"credential_id"`
	RefreshTokenHash    string     `gorm:"size:64;index" json:"-"`
	RefreshExpiresAt    *time.Time `json:"refresh_expires_at"`
	AbsoluteExpiresAt   *time.Time `json:"absolute_expires_at"`
	RevokedAt           *time.Time `json:"revoked_at"`
	RefreshGraceUntil   *time.Time `json:"-"` // 并发刷新宽限
	PreviousRefreshHash string     `gorm:"size:64" json:"-"`
	CreatedAt           time.Time  `json:"created_at"`
	UpdatedAt           time.Time  `json:"updated_at"`
}

OAuthGrant 一次用户批准产生的授权:绑定隐藏 MCP 凭据与刷新令牌哈希。

type OAuthPolicy

type OAuthPolicy struct {
	Enabled               bool   `json:"enabled"`    // OAuth 授权服务器总开关,默认 false
	PublicURL             string `json:"public_url"` // 对外根地址(https://…),缺省用环境变量或请求推导
	AllowDCR              bool   `json:"allow_dcr"`
	DCRAlways             bool   `json:"dcr_always"`               // 自动注册常开(不需要接入窗口);只在 AllowDCR 为真时有意义,旧库没有这个键 = false = 限时窗口
	AccessTokenTTLMinutes int    `json:"access_token_ttl_minutes"` // 默认 60
	RefreshIdleDays       int    `json:"refresh_idle_days"`        // 默认 30
	RefreshAbsoluteDays   int    `json:"refresh_absolute_days"`    // 默认 90
}

OAuthPolicy 持久化在 system_settings 的 oauth_policy 键。

真正的闸门只有两个:总开关 Enabled 与 AllowDCR(关闭后 POST /oauth/register 返回 403)。 早期版本里还有 allow_chatgpt / allow_claude / allow_loopback / client_host_allowlist 四项「信任来源」, 它们只决定批准页要不要标黄警告、不拒绝任何授权,#238 起删除(批准页的提示改为固定的内置规则,见 oauth.WarnUntrustedClient)。库里旧版本存下的这几个键在读取时被忽略,用户下次保存策略时自然消失。

自动注册有三种方式(#239),由 AllowDCR 与 DCRAlways 两个布尔值组合表达:

AllowDCR=false                  关闭:POST /oauth/register 一律 403 registration_disabled;
AllowDCR=true,  DCRAlways=false 限时窗口(默认):管理员在设置里开启「接入窗口」期间才受理,窗口外 403 registration_window_closed;
AllowDCR=true,  DCRAlways=true  常开:任何时候都受理(等同 2.0.0 的行为,公网上不建议)。

func DefaultOAuthPolicy

func DefaultOAuthPolicy() OAuthPolicy

type PageDiagReport added in v2.2.0

type PageDiagReport struct {
	ID        uint      `gorm:"primaryKey" json:"id"`
	CreatedAt time.Time `gorm:"index" json:"created_at"`
	// Kind 是上报的缘由:crash-suspect(检测到上一次没有正常收尾)、manual(用户在诊断条上手动点了上报)、
	// record(用户在诊断条上录了一次卡顿——帧节奏、长帧归因、动画清单、视口与焦点事件——并上报,#296)、
	// browser-crash(浏览器自己经 Reporting API 报的崩溃:渲染进程内存不足 / 无响应 / 其它崩溃,#290;走匿名只写入口,字段经白名单整理)。
	Kind string `gorm:"size:32" json:"kind"`
	// Flags 是上报时开着的诊断开关,逗号分隔(如 "tail,ime");没有开关时为空。
	Flags     string `gorm:"size:64" json:"flags"`
	UserAgent string `gorm:"size:256" json:"user_agent"`
	// Payload 是页面交来的原始 JSON(对象),整段原样保存;读取时按 json.RawMessage 原样给出,不在这一层解析。
	Payload string `gorm:"type:text" json:"-"`
}

PageDiagReport 是网页「诊断模式」上报的一条记录(#290):页面发现上一次异常退出(疑似渲染进程崩溃)之后, 把崩溃前最后几百条「面包屑」(填充批次、滚动位置、堆内存、节点数、长任务……)交给服务端留存,方便事后读。

只存数字与短标记,不含会话正文;新增时自动清掉更旧的(见 store.AddPageDiagReport):页面自己交来的几类共留最近 PageDiagKeep 条, 浏览器自报的崩溃(browser-crash)另外留最近 BrowserCrashKeep 条,两边各算各的,谁也挤不掉谁。 这是排障用的诊断设施:用户复测稳定后决定保留(#5190);将来真要拿掉,整张表与对应接口可以一并拿掉。

type PathReference

type PathReference struct {
	Path        string `json:"path"`
	Line        int    `json:"line,omitempty"`
	Description string `json:"description,omitempty"`
}

type PathReferences

type PathReferences []PathReference

func (*PathReferences) Scan

func (p *PathReferences) Scan(value interface{}) error

func (PathReferences) Value

func (p PathReferences) Value() (driver.Value, error)

type Permissions

type Permissions struct {
	Feedback   bool `json:"feedback"`
	Sessions   bool `json:"sessions"`
	SystemInfo bool `json:"system_info"`
	Skills     bool `json:"skills"`
	Configure  bool `json:"configure"`
	// Execute 只对应自驾(autopilot)的 report_progress,与「执行命令」无关;界面文案为「自驾上报」。
	Execute bool `json:"execute"`
	// Terminal 允许使用终端执行类工具(terminal_targets / terminal_exec / terminal_run)。
	// 缺省 false,且不包含在 AllPermissions() 里:远程执行必须由人在权限页显式授予。
	Terminal bool `json:"terminal"`
	// TerminalFiles 允许终端文件类工具(P2)。同样缺省 false。
	TerminalFiles bool `json:"terminal_files"`
	// TerminalCompat 让终端工具以 ExecMesh 的工具名(targets_list / target_info / exec / exec_start / job_status /
	// job_output / job_cancel)与返回形状暴露,方便既有 ExecMesh 客户端与提示词迁移。
	// 它只改变名字与返回形状,不增加任何能力;没有 Terminal 位时没有意义(Normalized 会把它清为 false)。
	// 开启后 tools/list 与 tools/call 都只认兼容名,原生的 terminal_* 名字不再可用(两处由同一个位决定)。
	TerminalCompat bool `json:"terminal_compat"`
	// Launcher 允许使用 preset_run 工具:项目管理 Agent 运行已有的「非交互续聊」预设(#179,设计稿 design/headless-new-conversation.md §8)。
	// 缺省 false,且不包含在 AllPermissions() 里:让一个智能体去拉起另一个智能体,必须由人在凭据页显式授予;没有这一位的凭据,
	// tools/list 里根本没有这个工具(可见性按凭据而不是按身份决定,所以它同时是一个随时能关掉的总闸)。
	// 光有这一位还不够:调用时调用方还必须是所在项目的管理 Agent(acl.CanManageTasks),两道门缺一不可。
	Launcher bool `json:"launcher"`
	// Archive 允许使用 project_archive 工具:把凭据名下授权的项目打成归档包(#272),给智能体与脚本做定时备份。
	// 缺省 false,且不包含在 AllPermissions() 里:整个项目的过程信息(群聊、任务、会话汇报、文档)能被一次取走,
	// 必须由人在凭据页显式授予(授予时要重新输入密码),并同时在凭据上勾选允许导出的项目(MCPCredential.ArchiveProjects,不能为空)。
	// 环境变量令牌、本地 stdio、开放访问与能力 URL 凭据都不带这一位;没有它的凭据,tools/list 里根本没有这个工具。
	Archive bool `json:"archive"`
}

func AllPermissions

func AllPermissions() Permissions

AllPermissions 返回 RelayMesh 治理类的全部权限。 注意:它**不包含** Terminal / TerminalFiles——开放访问、环境变量令牌与本地 stdio 都不应隐式获得远程执行能力。

func (Permissions) AllowsTool

func (p Permissions) AllowsTool(toolName string) bool

func (Permissions) HasGovernanceTools

func (p Permissions) HasGovernanceTools() bool

HasGovernanceTools 表示凭据是否带有 RelayMesh 治理类(工作流 / 反馈 / 自驾等)工具权限。 返回 false 且 HasTerminal 为 true 的凭据就是「ExecMesh 档」令牌:只暴露终端工具,也不应收到 RelayMesh 的治理指引。

func (Permissions) HasTerminal

func (p Permissions) HasTerminal() bool

HasTerminal 表示凭据是否带有任一终端类权限。

func (Permissions) IsTerminalOnly

func (p Permissions) IsTerminalOnly() bool

IsTerminalOnly 判断是否为只含终端类权限的令牌(ExecMesh 档)。

func (Permissions) Normalized

func (p Permissions) Normalized() Permissions

Normalized 返回归一化后的权限:兼容命名只在带有终端执行权限时才有意义。

func (*Permissions) Scan

func (p *Permissions) Scan(value interface{}) error

func (Permissions) Value

func (p Permissions) Value() (driver.Value, error)

type PhaseItem

type PhaseItem struct {
	ID          string `json:"id"`
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
	Prompt      string `json:"prompt,omitempty"`
}

func DefaultPhaseTemplate

func DefaultPhaseTemplate() []PhaseItem

DefaultPhaseTemplate 是出厂的三段式阶段模板。

func MigratePhaseItems

func MigratePhaseItems(items []PhaseItem) ([]PhaseItem, bool)

MigratePhaseItems 把旧五段式的阶段列表收敛为三段式,返回新列表以及是否发生了变化。

规则(逐字段,保证「用户改过的文案不丢」):

  • 旧 id 收敛:assess → discuss;verify、done → dev。列表里已经有目标阶段时,旧条目并入它(直接丢弃); 没有时,第一条旧条目改名充当目标阶段,后面的重复条目丢弃。
  • 标签、描述、提示词三个字段各自判断:仍然等于旧版出厂文案的,换成新模板对应阶段的文案; 用户改过的原样保留。plan、dev 两个 id 没变,但出厂提示词变了,同样按此处理。
  • 用户自建的阶段(id 不属于旧五段)不动。

输入不含旧 id、也不含旧版出厂提示词时原样返回(changed=false),可安全重复调用。

type Project

type Project struct {
	ID          uint       `gorm:"primaryKey;autoIncrement" json:"id"`
	Slug        string     `gorm:"size:64;not null;uniqueIndex:ux_project_slug" json:"slug"`
	Name        string     `gorm:"size:128;not null" json:"name"`
	Description string     `gorm:"size:1000" json:"description,omitempty"`
	ACLMode     string     `gorm:"size:8;not null;default:'audit'" json:"acl_mode"`
	CreatedBy   string     `gorm:"size:16;not null;default:'human'" json:"created_by"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	ArchivedAt  *time.Time `gorm:"index" json:"archived_at,omitempty"`
}

Project 是项目知识库的根。

type ProjectDir

type ProjectDir struct {
	ID               uint      `gorm:"primaryKey;autoIncrement" json:"id"`
	ProjectID        uint      `gorm:"not null;index" json:"project_id"`
	HostName         string    `gorm:"size:128;not null;uniqueIndex:ux_project_dir,priority:1" json:"host_name"`
	ProjectDirectory string    `gorm:"size:512;not null;uniqueIndex:ux_project_dir,priority:2" json:"project_directory"`
	BranchHint       string    `gorm:"size:128" json:"branch_hint,omitempty"`
	AddedBy          string    `gorm:"size:16;not null;default:'human'" json:"added_by"`
	AddedAt          time.Time `json:"added_at"`
}

ProjectDir 把一个(主机,目录)归入项目:一个目录只属于一个项目。

type ProjectDoc

type ProjectDoc struct {
	ID         uint        `gorm:"primaryKey;autoIncrement" json:"id"`
	WorkflowID string      `` /* 134-byte string literal not displayed */
	Seq        int         `gorm:"not null;uniqueIndex:ux_project_doc_seq,priority:2" json:"seq"`
	Path       string      `gorm:"size:512;not null;uniqueIndex:ux_project_doc_path,priority:2" json:"path"`
	Title      string      `gorm:"size:256;not null" json:"title"`
	Kind       string      `gorm:"size:16;not null;default:'note';index" json:"kind"`
	Status     string      `gorm:"size:16;not null;default:'draft';index" json:"status"`
	Tags       StringArray `gorm:"type:text" json:"tags"`
	Body       string      `gorm:"type:text" json:"body"`
	Rev        int         `gorm:"not null;default:1" json:"rev"`
	Hash       string      `gorm:"size:64;not null" json:"hash"`
	// 项目知识库(#114):文档仍归属某个工作流(老唯一键不动),project_id 把它归入项目;0 = 没有归属项目。
	ProjectID       uint       `gorm:"not null;default:0;index" json:"project_id,omitempty"`
	ModulePath      string     `gorm:"size:256;not null;default:'';index" json:"module_path,omitempty"`
	OwnerIdentityID uint       `gorm:"not null;default:0" json:"owner_identity_id,omitempty"`
	Render          string     `gorm:"size:16;not null;default:'md'" json:"render,omitempty"`
	CreatedBy       string     `gorm:"size:16;not null" json:"created_by"`
	UpdatedBy       string     `gorm:"size:16;not null" json:"updated_by"`
	CreatedAt       time.Time  `json:"created_at"`
	UpdatedAt       time.Time  `json:"updated_at"`
	DeletedAt       *time.Time `gorm:"index" json:"deleted_at,omitempty"`
}

ProjectDoc 是工作流内的一篇 Markdown 文档。

type ProjectDocCounter

type ProjectDocCounter struct {
	WorkflowID string `gorm:"primaryKey;size:128" json:"workflow_id"`
	LastSeq    int    `gorm:"not null;default:0" json:"last_seq"`
}

ProjectDocCounter 保证 seq 单调不复用。

type ProjectDocRevision

type ProjectDocRevision struct {
	ID        uint      `gorm:"primaryKey;autoIncrement" json:"id"`
	DocID     uint      `gorm:"not null;index;uniqueIndex:ux_doc_rev,priority:1" json:"doc_id"`
	Rev       int       `gorm:"not null;uniqueIndex:ux_doc_rev,priority:2" json:"rev"`
	Body      string    `gorm:"type:text" json:"body"`
	Summary   string    `gorm:"size:500" json:"summary"`
	Actor     string    `gorm:"size:16;not null" json:"actor"`
	CreatedAt time.Time `json:"created_at"`
}

ProjectDocRevision 保存历史正文(每篇最多保留 50 版)。

type ProjectModule

type ProjectModule struct {
	ID              uint      `gorm:"primaryKey;autoIncrement" json:"id"`
	ProjectID       uint      `gorm:"not null;uniqueIndex:ux_project_module,priority:1" json:"project_id"`
	Path            string    `gorm:"size:256;not null;uniqueIndex:ux_project_module,priority:2" json:"path"`
	Title           string    `gorm:"size:128;not null" json:"title"`
	Description     string    `gorm:"size:1000" json:"description,omitempty"`
	OwnerIdentityID uint      `gorm:"not null;default:0" json:"owner_identity_id,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
}

ProjectModule 是项目的功能模块(路径是封闭列表);设计信息绑定到模块路径。

type QueuedFeedback

type QueuedFeedback struct {
	ID               uint          `gorm:"primaryKey" json:"id"`
	WorkflowID       string        `gorm:"index;index:idx_qf_wf_created,priority:1;size:128" json:"workflow_id"`
	HostName         string        `gorm:"size:128" json:"host_name,omitempty"`
	ProjectDirectory string        `gorm:"size:512" json:"project_directory"`
	ResponseText     string        `gorm:"type:text" json:"response_text"`
	UserMessages     StringArray   `gorm:"type:text" json:"user_messages"`
	Images           SessionImages `gorm:"type:text" json:"images"`
	Status           string        `gorm:"size:32;default:'pending'" json:"status"` // pending, consumed, revoked, expired
	CreatedAt        time.Time     `gorm:"index:idx_qf_wf_created,priority:2" json:"created_at"`
	UpdatedAt        time.Time     `json:"updated_at"`

	// OriginRef 记录这条追加「去了哪里」:被并进某一轮的秒回时写 s:<会话编号>;确认项答复写 c:Q12(多个用逗号分隔)。
	// 旧数据为空。聊天消息流靠它把确认项答复的投递状态挂回对应的卡(设计稿 03 / 旧稿 rev 5 附录 C)。可空的只增列。
	OriginRef string `gorm:"size:160" json:"origin_ref,omitempty"`

	// 群聊投递(阶段 2b):kind = chat_mention 的行记下它对应哪个群的哪条消息、谁发的。可空的只增列。
	ConversationID string `gorm:"size:64" json:"conversation_id,omitempty"`
	MessageID      uint   `json:"message_id,omitempty"`
	SenderRef      string `gorm:"size:128" json:"sender_ref,omitempty"`

	// 发言者(#236 分支会话):kind = branch 的行记下是谁说的——主会话 Agent、分支 Agent,或用户在另一个会话页里的发言被抄送过来。
	// 紧凑 JSON(见 MsgActor);空 = 用户 / 本会话 Agent,与以前一样,所以不是分支消息的行响应里没有这个字段。可空的只增列。
	Actor string `gorm:"size:200" json:"actor,omitempty"`

	// ---- 追加指令收件箱(D-210)----
	// 每条追加独立一行,各有各的状态:queued(已排队)→ delivered(Agent 读到了全文)→ acked(已确认)。
	// 旁支:revoked(Agent 完全不知道时被撤回)、retracted(Agent 读到、或被 hook / 提示行提醒过之后被撤回)、expired(超过保留期)。
	// 状态由 Status 与下面的时间戳推导(见 DeriveState),旧版本只认 Status,因此回滚到旧版本时:
	// pending 的行照旧会在 Agent 下次发起交互时被取走,不会丢。
	Kind             string     `gorm:"size:16;default:'append'" json:"kind"`   // append(预留 interrupt);空串按 append 处理
	DeliveredAt      *time.Time `json:"delivered_at,omitempty"`                 // Agent 第一次读到全文的时间
	DeliveredVia     string     `gorm:"size:16" json:"delivered_via,omitempty"` // feedback | hook | receipt | tool:是经哪条路径被发现的
	AckedAt          *time.Time `json:"acked_at,omitempty"`
	NotifiedCount    int        `gorm:"default:0" json:"notified_count"` // hook 提醒过几次(有上限)
	LastNotifiedAt   *time.Time `json:"last_notified_at,omitempty"`
	ReceiptHintAt    *time.Time `json:"receipt_hint_at,omitempty"` // 回执里的 inbox: 提示行最近一次提醒的时间
	RetractedAt      *time.Time `json:"retracted_at,omitempty"`    // 智能体读到之后、或被 hook / 提示行提醒过之后又被撤回的时间(完全不知道的撤回不记)
	RetractNoticedAt *time.Time `json:"-"`                         // 已把「这条撤回了」告诉 Agent 的时间

	// Hints 是挂在这条追加上的「相关线索」(#303 D,Q191 a):用户发出这条消息后,服务端在后台按它的含义做一次语义检索,
	// 把可能相关的旧内容(时间 · 类型 · 标题 · 编号)记在这里;智能体读到这条追加时一并看到,只是线索,不是指令。
	// HintsAt 是线索算好写入的时间:它晚于 DeliveredAt 说明智能体读的时候还没算好,那一次就没带上(网页上会如实标出)。
	// 都是可空的只增列:旧二进制可打开新库,没有线索(绝大多数消息)保持 NULL,接口里也不输出。
	Hints   Hints      `gorm:"type:text" json:"hints,omitempty"`
	HintsAt *time.Time `json:"hints_at,omitempty"`

	// State 是派生字段,不入库:queued | delivered | acked | revoked | retracted | expired。
	State string `gorm:"-" json:"state"`
}

func (*QueuedFeedback) DeriveState

func (q *QueuedFeedback) DeriveState() string

DeriveState 由 Status 与时间戳推导收件箱状态;读出来的行由 store 统一填进 State。

type Report

type Report struct {
	ID                       uint           `gorm:"primaryKey" json:"-"`
	TaskID                   string         `gorm:"index;not null;size:128" json:"task_id"`
	Sequence                 int64          `gorm:"not null" json:"sequence"`
	AcknowledgedTaskRevision int64          `gorm:"default:0" json:"acknowledged_task_revision"`
	Kind                     string         `gorm:"size:32;not null" json:"kind"` // progress, stage, evidence, question, completion
	Body                     string         `gorm:"type:text;not null" json:"body"`
	References               PathReferences `gorm:"type:text" json:"references,omitempty"`
	IdempotencyKey           string         `gorm:"size:128;index" json:"idempotency_key,omitempty"`
	CreatedAt                time.Time      `json:"created_at"`
}

type ReportPage

type ReportPage struct {
	Reports      []Report `json:"reports"`
	NextSequence int64    `json:"next_sequence"`
	HasMore      bool     `json:"has_more"`
}

type ReportResult

type ReportResult struct {
	Report           Report     `json:"report"`
	FeedbackSequence int64      `json:"feedback_sequence"`
	Feedback         []Feedback `json:"feedback,omitempty"`
	Wait             WaitStatus `json:"wait"`
}

type SearchEntry added in v2.2.0

type SearchEntry struct {
	ID   uint   `gorm:"primaryKey;autoIncrement"`
	Kind string `gorm:"size:16;not null;uniqueIndex:ux_search_entry_ref,priority:1"`
	Ref  string `gorm:"size:128;not null;uniqueIndex:ux_search_entry_ref,priority:2"`
	// FTSRowID 是这一行在 search_fts 里的 rowid:高位是源行的时间(毫秒),低 12 位是同一毫秒内的序号,
	// 所以「按 rowid 倒序」就是「越新越靠前」,宽泛查询可以提前结束。永不复用(见 SearchStale)。
	FTSRowID int64 `gorm:"column:fts_rowid;not null;uniqueIndex:ux_search_entry_rowid"`
	// Rev 是写入索引时源行的版本戳(由 SQL 表达式算出,与对账时算的逐字相同);对账时对不上就重新加载这一行。
	Rev string `gorm:"size:256;not null;default:''"`
	// Hash 是写入索引的文本(标题、正文、范围词条)的内容摘要:重新加载后摘要没变就不重写索引,
	// 避免与检索无关的字段更新(已读标记、状态位……)把索引写成一堆作废条目。
	Hash string `gorm:"size:32;not null;default:''"`
}

SearchEntry 是定位表:(类型, 源行编号) → 当前有效的 FTS rowid。 源行被编辑时索引里写一个新条目(新 rowid),旧 rowid 进 SearchStale;源行被删时定位行删掉、rowid 进 SearchStale。

type SearchStale added in v2.2.0

type SearchStale struct {
	FTSRowID int64 `gorm:"column:fts_rowid;primaryKey;autoIncrement:false"`
}

SearchStale 记下已经作废的 FTS rowid:它们的倒排记录还留在无内容的 FTS 表里(当前 SQLite 3.41 不支持无内容表的 DELETE), 靠「定位表里没有它」来屏蔽,并且永远不再被分配给新条目(否则旧版本的词会「复活」在新行上)。累积到一定数量就整体重建。

type SearchState added in v2.2.0

type SearchState struct {
	Key   string `gorm:"primaryKey;size:64"`
	Value string `gorm:"size:256;not null;default:''"`
}

SearchState 是引擎的键值状态:索引版本、各类型的回填完成时间、最近一次对账 / 重建的时间等。

type Segment

type Segment struct {
	ID              uint      `gorm:"primaryKey" json:"-"`
	TaskID          string    `gorm:"index;not null;size:128" json:"task_id,omitempty"`
	Name            string    `gorm:"size:64;not null" json:"name"`
	Content         string    `gorm:"type:text;not null" json:"content"`
	Position        int       `gorm:"default:0" json:"position"`
	UpdatedRevision int64     `gorm:"default:1" json:"updated_revision"`
	CreatedAt       time.Time `json:"created_at,omitempty"`
	UpdatedAt       time.Time `json:"updated_at,omitempty"`
}

type SendFeedbackInput

type SendFeedbackInput struct {
	ProjectID        string          `json:"project_id"`
	TaskID           string          `json:"task_id"`
	ExpectedRevision int64           `json:"expected_revision"`
	Source           string          `json:"source,omitempty"` // "human" | "commander"
	Body             string          `json:"body"`
	References       []PathReference `json:"references,omitempty"`
	IdempotencyKey   string          `json:"idempotency_key,omitempty"`
}

type SessionImage

type SessionImage struct {
	Name     string `json:"name,omitempty"`
	Format   string `json:"format,omitempty"`
	Data     string `json:"data,omitempty"` // base64 (轻量传输时可省略)
	DataType string `json:"data_type,omitempty"`
	Hash     string `json:"hash,omitempty"`
	Width    int    `json:"width,omitempty"`
	Height   int    `json:"height,omitempty"`
	URL      string `json:"url,omitempty"`
}

type SessionImages

type SessionImages []SessionImage

func (*SessionImages) Scan

func (s *SessionImages) Scan(value interface{}) error

func (SessionImages) Value

func (s SessionImages) Value() (driver.Value, error)

type SetWaitPolicyInput

type SetWaitPolicyInput struct {
	ProjectID        string     `json:"project_id"`
	TaskID           string     `json:"task_id"`
	ExpectedRevision int64      `json:"expected_revision"`
	WaitPolicy       WaitPolicy `json:"wait_policy"`
	IdempotencyKey   string     `json:"idempotency_key,omitempty"`
}

type StringArray

type StringArray []string

func (*StringArray) Scan

func (s *StringArray) Scan(value interface{}) error

func (StringArray) Value

func (s StringArray) Value() (driver.Value, error)

type StringList

type StringList []string

StringList 以 JSON 文本存放的字符串列表(SQLite 里是 text 列,API 里是数组)。

func (*StringList) Scan

func (l *StringList) Scan(value interface{}) error

func (StringList) Value

func (l StringList) Value() (driver.Value, error)

type SyncInput

type SyncInput struct {
	ProjectID                    string `json:"project_id"`
	TaskID                       string `json:"task_id"`
	KnownTaskRevision            int64  `json:"known_task_revision"`
	AcknowledgedTaskRevision     int64  `json:"acknowledged_task_revision"`
	AfterFeedbackSequence        int64  `json:"after_feedback_sequence"`
	AcknowledgedFeedbackSequence int64  `json:"acknowledged_feedback_sequence"`
}

type SyncResult

type SyncResult struct {
	TaskID                       string      `json:"task_id"`
	State                        string      `json:"state"`
	Revision                     int64       `json:"revision"`
	ReportSequence               int64       `json:"report_sequence"`
	FeedbackSequence             int64       `json:"feedback_sequence"`
	AcknowledgedTaskRevision     int64       `json:"acknowledged_task_revision"`
	AcknowledgedFeedbackSequence int64       `json:"acknowledged_feedback_sequence"`
	Segments                     []Segment   `json:"segments,omitempty"`
	Feedback                     []Feedback  `json:"feedback,omitempty"`
	Wait                         *WaitStatus `json:"wait,omitempty"`
}

type SystemSetting

type SystemSetting struct {
	Key       string    `gorm:"primaryKey;size:64" json:"key"`
	Value     string    `gorm:"type:text;not null" json:"value"`
	UpdatedAt time.Time `json:"updated_at"`
}

type Task

type Task struct {
	ID                           string     `gorm:"primaryKey;size:128" json:"task_id"`
	ProjectID                    string     `gorm:"index;size:128;not null" json:"project_id"`
	Title                        string     `gorm:"size:256;default:''" json:"title"`
	Mode                         string     `gorm:"size:64;default:'managed_autopilot'" json:"mode"` // managed_autopilot, lite
	State                        string     `gorm:"size:32;default:'active'" json:"state"`           // active, closed, archived, paused
	CurrentStageID               string     `gorm:"size:64;default:''" json:"current_stage_id"`
	Stages                       TaskStages `gorm:"type:text" json:"stages,omitempty"`
	CommanderSessionID           string     `gorm:"size:128;default:''" json:"commander_session_id,omitempty"`
	ExecutorSessionID            string     `gorm:"size:128;default:''" json:"executor_session_id,omitempty"`
	CommanderHeartbeatAt         *time.Time `json:"commander_heartbeat_at,omitempty"`
	ExecutorHeartbeatAt          *time.Time `json:"executor_heartbeat_at,omitempty"`
	Revision                     int64      `gorm:"default:1" json:"revision"`
	ReportSequence               int64      `gorm:"default:0" json:"report_sequence"`
	FeedbackSequence             int64      `gorm:"default:0" json:"feedback_sequence"`
	AcknowledgedTaskRevision     int64      `gorm:"default:0" json:"acknowledged_task_revision"`
	AcknowledgedFeedbackSequence int64      `gorm:"default:0" json:"acknowledged_feedback_sequence"`
	AcknowledgedReportSequence   int64      `gorm:"default:0" json:"acknowledged_report_sequence"`
	WaitPolicy                   WaitPolicy `gorm:"type:text" json:"wait_policy"`
	Segments                     []Segment  `gorm:"foreignKey:TaskID;constraint:OnDelete:CASCADE" json:"segments,omitempty"`
	CreatedAt                    time.Time  `json:"created_at"`
	UpdatedAt                    time.Time  `json:"updated_at"`
}

type TaskPage

type TaskPage struct {
	Tasks      []TaskSummary `json:"tasks"`
	NextCursor string        `json:"next_cursor,omitempty"`
}

type TaskStage

type TaskStage struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Status    string    `json:"status"` // pending, in_progress, completed, blocked
	Summary   string    `json:"summary,omitempty"`
	Evidence  string    `json:"evidence,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitempty"`
}

type TaskStages

type TaskStages []TaskStage

func (*TaskStages) Scan

func (s *TaskStages) Scan(value interface{}) error

func (TaskStages) Value

func (s TaskStages) Value() (driver.Value, error)

type TaskSummary

type TaskSummary struct {
	ID                         string     `json:"task_id"`
	ProjectID                  string     `json:"project_id"`
	Title                      string     `json:"title"`
	Mode                       string     `json:"mode"`
	State                      string     `json:"state"`
	CurrentStageID             string     `json:"current_stage_id,omitempty"`
	Stages                     TaskStages `json:"stages,omitempty"`
	CommanderSessionID         string     `json:"commander_session_id,omitempty"`
	ExecutorSessionID          string     `json:"executor_session_id,omitempty"`
	Revision                   int64      `json:"revision"`
	ReportSequence             int64      `json:"report_sequence"`
	FeedbackSequence           int64      `json:"feedback_sequence"`
	AcknowledgedReportSequence int64      `json:"acknowledged_report_sequence"`
	UnreadReportCount          int64      `json:"unread_report_count"`
	UpdatedAt                  time.Time  `json:"updated_at"`
}

type TerminalArchive

type TerminalArchive struct {
	ItemKey    string    `gorm:"column:item_key;primaryKey;size:160" json:"key"`
	ArchivedAt time.Time `gorm:"index" json:"archived_at"`
}

TerminalArchive 记录 ExecMesh 侧栏里哪些条目被归档(D-200)。

归档只决定侧栏默认显示不显示:不结束会话、不影响记录与审计,也不改变模型线程里的任何内容。 ItemKey 与前端侧栏条目的 key 一致:人工会话是「机器码:会话 ID」,模型线程是「r:线程键」。 单独存一张表而不是挂在 TerminalSession 上,是因为模型线程没有自己的行,两类条目这样可以走同一条路径。

type TerminalAuditLog

type TerminalAuditLog struct {
	ID          uint      `gorm:"primaryKey" json:"id"`
	CreatedAt   time.Time `gorm:"index" json:"created_at"`
	Event       string    `gorm:"size:48;index;not null" json:"event"`
	Result      string    `gorm:"size:8" json:"result"` // ok | fail | deny
	Actor       string    `gorm:"size:64" json:"actor"`
	IP          string    `gorm:"size:64" json:"ip"`
	MachineCode string    `gorm:"size:32;index" json:"machine_code"`
	SessionID   string    `gorm:"size:40" json:"session_id"`
	Detail      string    `gorm:"size:512" json:"detail"`
	// ActorKind 标明操作者类型:human(Web 登录主体)/ model(MCP 令牌)/ system;空表示旧记录(均为 human 或 system)。
	ActorKind string `gorm:"size:8" json:"actor_kind"`
	// RunID 在审计事件与某次模型运行有关时给出,便于从运行跳到审计。
	RunID string `gorm:"size:32;index" json:"run_id"`
}

TerminalAuditLog 是终端相关的安全审计记录。

永不记录按键、终端输出、票据、解锁令牌与 Agent 私钥; Agent 自报字段必须先净化再写入 Detail。

type TerminalHost

type TerminalHost struct {
	ID           uint   `gorm:"primaryKey" json:"-"`
	MachineCode  string `gorm:"uniqueIndex;size:32;not null" json:"machine_code"`
	PublicKey    string `gorm:"size:64;not null" json:"-"` // base64url(Ed25519 公钥 32 字节)
	Remark       string `gorm:"size:256" json:"remark"`
	Status       string `gorm:"size:16;index;not null" json:"status"` // enabled | disabled | blocked
	Hostname     string `gorm:"size:128" json:"hostname"`
	OS           string `gorm:"size:64" json:"os"`
	Arch         string `gorm:"size:32" json:"arch"`
	AgentVersion string `gorm:"size:32" json:"agent_version"`
	// AgentRev 是 Agent 自报的「Agent 侧代码指纹」(见 termproto.ValidAgentRev),每次握手刷新;空表示旧版本 / 非发布构建。
	// 离线主机的「可升级」也靠它判断,所以要落库。
	AgentRev   string     `gorm:"size:40" json:"agent_rev,omitempty"`
	Privilege  string     `gorm:"size:16" json:"privilege"`
	LastIP     string     `gorm:"size:64" json:"last_ip"`
	LastSeenAt *time.Time `json:"last_seen_at,omitempty"`
	EnabledAt  *time.Time `json:"enabled_at,omitempty"`
	// RecOff 为 true 表示管理员在这台主机上关闭了终端记录(作为服务端策略下发,只能更严格)。
	RecOff bool `gorm:"not null;default:false" json:"rec_off"`
	// IdleSec 是这台主机上会话的默认生命周期:连续这么多秒没有交互才回收;0 表示永久保持(默认)。
	IdleSec int `gorm:"not null;default:0" json:"idle_sec"`
	// AllowModel 是 G2:管理员在 Web 上(解锁后)允许模型通过 MCP 在这台主机上执行命令。默认关闭。
	AllowModel bool `gorm:"not null;default:false" json:"allow_model"`
	// DefaultForNewModels 决定这台主机对「之后新建的模型授权」的默认态:空串或 deny(默认,不预先授予)/ allow(预先授予)。
	// 它只在两个时刻生效,并且生效方式是「写成令牌主机名单里的明确条目」:这台主机被新增时授予现有的模型令牌,
	// 新建模型令牌时预填入名单。运行期间不做任何继承——判定一台主机能否被某个令牌使用,仍然只看令牌自己的名单。
	DefaultForNewModels string `gorm:"size:8;not null;default:''" json:"default_for_new_models"`
	// ExecMode 是这台主机的模型执行模式:空串或 auto(令牌授权 + 主机授权即放行)/ approve(每次需人工批准)/ readonly(只读)。
	// 令牌自己的模式上限只能比它更严。
	ExecMode string `gorm:"size:16;not null;default:''" json:"exec_mode"`
	// ModelPaused 为 true 时拒绝这台主机上的一切模型运行(并已取消进行中的);全局暂停是另一个独立的开关。
	ModelPaused bool `gorm:"not null;default:false" json:"model_paused"`

	// Kind 是主机的接入方式:空串或 agent(装了 RelayMesh Agent,由 Agent 与会话守护进程执行)/ ssh(没有 Agent,经 SSH 执行,仅支持模型运行)。
	Kind string `gorm:"size:8;not null;default:''" json:"kind"`
	// 以下 SSH_* 字段只对 Kind=ssh 有意义。连接地址与凭据只来自这里,模型永远只能给出 target。
	SSHAddr        string     `gorm:"column:ssh_addr;size:260;not null;default:''" json:"-"`         // host:port
	SSHUser        string     `gorm:"column:ssh_user;size:64;not null;default:''" json:"-"`          // 登录用户名
	SSHAuth        string     `gorm:"column:ssh_auth;size:8;not null;default:''" json:"-"`           // password | key
	SSHSecret      string     `gorm:"column:ssh_secret;type:text;not null;default:''" json:"-"`      // 密封后的凭据(AES-256-GCM),永不进 JSON、永不明文落库
	SSHHostKeyType string     `gorm:"column:ssh_host_key_type;size:32;not null;default:''" json:"-"` // 固定的主机密钥类型
	SSHHostKey     string     `gorm:"column:ssh_host_key;type:text;not null;default:''" json:"-"`    // 固定的主机公钥(base64)
	SSHFingerprint string     `gorm:"column:ssh_fingerprint;size:64;not null;default:''" json:"-"`   // SHA256:…
	SSHKeyState    string     `gorm:"column:ssh_key_state;size:12;not null;default:''" json:"-"`     // 空 | mismatch(出现过不一致,需管理员重新确认)
	SSHError       string     `gorm:"column:ssh_error;size:200;not null;default:''" json:"-"`        // 最近一次失败的原因(已净化,不含凭据)
	SSHCheckedAt   *time.Time `gorm:"column:ssh_checked_at" json:"-"`                                // 最近一次连接尝试
	SSHOKAt        *time.Time `gorm:"column:ssh_ok_at" json:"-"`                                     // 最近一次成功
	// SSHGateway 非空表示这台 SSH 主机经「网关主机」接入:值是网关(一台开启了 --ssh-gateway 的 Agent 主机)的机器码。
	// 经网关接入的主机:连接由网关上的会话守护进程出站建立(人工终端由它持有会话;模型执行由 Hub 驱动、经网关代理 SSH exec),
	// Hub 不会直连它,也不保存它的登录凭据(SSHSecret 恒为空,凭据只在网关自己的密封凭据库里)。
	// 空串表示由 Hub 直连(仅供模型执行,没有人工终端)。
	SSHGateway string `gorm:"column:ssh_gateway;size:32;not null;default:''" json:"-"`
	// SSHTermOnly 为 true 表示这台经网关接入的主机只能当人工终端用(登记时无法探测出 POSIX 环境:Windows OpenSSH、网络设备、受限 shell),
	// 模型不能在它上面执行。取反的语义让存量行默认可执行。
	SSHTermOnly bool `gorm:"column:ssh_term_only;not null;default:false" json:"-"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

TerminalHost 是已被管理员处理过(启用 / 停用 / 忽略)的终端主机。

库里只保存 Agent 的**公钥**:机器码由公钥派生,冒充主机需要私钥; 服务端数据库泄露不会泄露任何可冒充主机的秘密。 待启用(发现列表)的主机只存在于内存,不入库,避免被匿名灌库。

func (TerminalHost) GrantsNewModelsByDefault

func (h TerminalHost) GrantsNewModelsByDefault() bool

GrantsNewModelsByDefault 判断这台主机是否预先授予新建的模型令牌。

func (TerminalHost) IsSSH

func (h TerminalHost) IsSSH() bool

IsSSH 判断这是一台经 SSH 接入的主机。

func (TerminalHost) ViaGateway

func (h TerminalHost) ViaGateway() bool

ViaGateway 判断这是一台经网关主机接入的 SSH 主机(Hub 不直连、不保存凭据,由网关出站连接)。

type TerminalLimits

type TerminalLimits struct {
	MaxConcurrent     int      `json:"max_concurrent,omitempty"`      // 同时运行的上限
	MaxWaitSeconds    int      `json:"max_wait_seconds,omitempty"`    // terminal_exec 的 wait_seconds 上限
	MaxTimeoutSeconds int      `json:"max_timeout_seconds,omitempty"` // 单次运行 timeout_seconds 上限
	MaxOutputBytes    int      `json:"max_output_bytes,omitempty"`    // 单次返回的输出字节上限
	AllowedDirs       []string `json:"allowed_dirs,omitempty"`        // 工作目录白名单(前缀匹配);为空表示不限
	// AllowedPaths 是文件工具(terminal_files)可以访问的目录。与 AllowedDirs 不同,它是强制边界:
	// 文件权限位打开时必须非空(或明确开启 AllowWholeFS),路径经符号链接也不能逃出这些目录;为空表示此令牌没有任何文件访问范围。
	AllowedPaths []string `json:"allowed_paths,omitempty"`
	// AllowWholeFS 是「允许整个文件系统」开关:文件工具不再限制在 AllowedPaths 里,而是可以访问这台主机上
	// Agent 所属账户能访问的任何路径(Windows 上是任一盘符)。这是一个显式的高风险开关,默认关闭:
	// 在允许目录里写 `/` 仍然被拒绝(防手误),只有这个开关能放开;开启时必须刚刚重新验证过密码并写审计,
	// 且只在文件权限位打开时才有意义。开关开着时 AllowedPaths 在运行时不再起作用,但原样保留(仍要合法):
	// 关闭开关后回到管理员原本明确列出的目录,而不是更宽的范围。
	AllowWholeFS bool `json:"allow_whole_fs,omitempty"`
}

TerminalLimits 是令牌级的终端限额。全部为零值表示「不设限」——这是默认值,由人在权限页主动设置。

func (TerminalLimits) HasFileScope

func (l TerminalLimits) HasFileScope() bool

HasFileScope 报告文件工具的访问范围是否非空:至少一个允许目录,或明确开启了「允许整个文件系统」。 文件权限没有「默认全部可访问」的含义——两者都没有就等于没有范围。

func (TerminalLimits) IsZero

func (l TerminalLimits) IsZero() bool

func (*TerminalLimits) Scan

func (l *TerminalLimits) Scan(value interface{}) error

func (TerminalLimits) Value

func (l TerminalLimits) Value() (driver.Value, error)

type TerminalLostDismissal

type TerminalLostDismissal struct {
	MachineCode string    `gorm:"column:machine_code;primaryKey;size:32" json:"machine_code"`
	SID         string    `gorm:"column:sid;primaryKey;size:64" json:"sid"`
	DismissedAt time.Time `gorm:"index" json:"dismissed_at"`
}

TerminalLostDismissal 记录管理员在主机页「忽略」了哪些「会话已不存在」提示(第六批 #28)。

提示的来源是主机上会话守护进程的上报(terminal.HolderView.Lost):守护进程每次与 Hub 建立连接都会把 它记着的丢失会话再报一遍,所以「删掉这条提示」必须由 Hub 记住,否则下一次重连又会冒出来。 忽略只是「不再提醒」:不删除会话记录、审计与历史入口,也不要求主机在线、不要求 Agent 升级(协议不变)。 过期的忽略记录随时间清理(见 store.DismissTerminalLost),主机被删除时一并清除。

type TerminalRun

type TerminalRun struct {
	ID    uint   `gorm:"primaryKey" json:"-"`
	RunID string `gorm:"column:run_id;uniqueIndex;size:32;not null" json:"run_id"`

	// ThreadKey 是线程键的短哈希:ExecMesh 档为 (凭据, 目标主机, thread),混合令牌且带 workflow_id 时为 (workflow_id, 目标主机)。
	ThreadKey string `gorm:"size:32;index;not null" json:"thread_key"`
	Backend   string `gorm:"size:8" json:"backend"`    // agent
	ActorKind string `gorm:"size:8" json:"actor_kind"` // model | human | system

	CredentialID   uint   `gorm:"index" json:"credential_id"`
	CredentialName string `gorm:"size:128" json:"credential_name"`
	ClientName     string `gorm:"size:96" json:"client_name"` // 客户端自报(User-Agent 摘要),只作展示
	RemoteIP       string `gorm:"size:64" json:"remote_ip"`
	OriginHost     string `gorm:"size:128" json:"origin_host"`

	WorkflowID       string `gorm:"size:128;index" json:"workflow_id"`
	Thread           string `gorm:"size:64" json:"thread"`
	ProjectDirectory string `gorm:"size:256" json:"project_directory"`
	Description      string `gorm:"size:256" json:"description"`

	Target        string `gorm:"size:32;index;not null" json:"target"` // 机器码
	Cwd           string `gorm:"size:512" json:"cwd"`
	Shell         string `gorm:"size:16" json:"shell"`
	Command       string `gorm:"size:4096" json:"command"` // 脱敏副本
	CommandSHA256 string `gorm:"size:64" json:"command_sha256"`
	Tools         string `gorm:"size:256" json:"tools"` // 命令名清单(逗号分隔),仅展示

	State      string     `gorm:"size:20;index;not null" json:"state"`
	DenyReason string     `gorm:"size:32" json:"deny_reason"` // denied / rejected 时的原因码
	ExitCode   *int       `json:"exit_code,omitempty"`
	Signal     string     `gorm:"size:16" json:"signal"`
	PolicyMode string     `gorm:"size:8" json:"policy_mode"` // 生效的执行模式:auto | approve | readonly
	ApprovedBy string     `gorm:"size:64" json:"approved_by"`
	ApprovedAt *time.Time `json:"approved_at,omitempty"`

	StartedAt  *time.Time `json:"started_at,omitempty"`
	EndedAt    *time.Time `gorm:"index" json:"ended_at,omitempty"`
	DurationMS int64      `json:"duration_ms"`
	TimeoutSec int        `json:"timeout_sec"`

	StdoutBytes   int64 `json:"stdout_bytes"`
	StderrBytes   int64 `json:"stderr_bytes"`
	Truncated     bool  `json:"truncated"`
	MiddleDropped int64 `json:"middle_dropped_bytes"`

	PreviewHead string `gorm:"type:text" json:"preview_head"`
	PreviewTail string `gorm:"type:text" json:"preview_tail"`

	IdempotencyKey string `gorm:"size:96;index" json:"-"`

	CreatedAt time.Time `gorm:"index" json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

TerminalRun 是一次模型运行的**元数据**:谁、在哪台主机、做了什么、结果如何,外加有界的预览。

这里永远不保存完整输出(INV-M4):完整输出只存在主机本机,由人类或持有令牌的模型按需经 Agent 读取。 命令文本保存的是脱敏副本(常见密钥模式已被替换);预览同样脱敏并去除控制序列。

type TerminalSession

type TerminalSession struct {
	ID          uint   `gorm:"primaryKey" json:"-"`
	SID         string `gorm:"column:sid;uniqueIndex:ux_terminal_session,priority:2;size:32;not null" json:"sid"`
	MachineCode string `gorm:"uniqueIndex:ux_terminal_session,priority:1;size:32;not null" json:"machine_code"`
	Name        string `gorm:"size:128" json:"name"`
	Shell       string `gorm:"size:128" json:"shell"`
	StartedAt   int64  `json:"started_at"` // 会话创建时间(Agent 时钟的 Unix 秒,仅供展示)

	// EndedAt 是 Hub 观察到会话结束的时间;nil 表示仍在运行。
	EndedAt     *time.Time `gorm:"index" json:"ended_at,omitempty"`
	EndedReason string     `gorm:"size:32" json:"ended_reason"` // exit | killed | gone | host_reboot | holder_stopped | holder_exit | …
	ExitCode    *int       `json:"exit_code,omitempty"`

	// 录制状态与主机上记录的索引(不含内容)。
	RecState  string `gorm:"size:12" json:"rec"`                       // on | paused | error | off | veto | incognito | ""(旧版本 Agent 未报告)
	RecBytes  int64  `json:"rec_bytes"`                                // 主机上保留的记录字节数(最近一次报告)
	RecFirst  int64  `json:"rec_first"`                                // 最早保留内容的时间(Unix 秒)
	RecLast   int64  `json:"rec_last"`                                 // 最近写入的时间(Unix 秒)
	RecGap    bool   `json:"rec_gap"`                                  // 记录不完整
	RecPurged bool   `gorm:"not null;default:false" json:"rec_purged"` // 主机报告记录已不存在(过期或被清理)

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

TerminalSession 是终端会话的**索引**:用来在侧栏里保留「已结束」的会话并指向主机上的记录。

这里永远不保存终端内容、按键、输入输出(INV-M4):内容只存在主机本地的记录文件里, 由人类按需经 Agent 读取,Hub 不落盘。名称是人类给会话起的标签,经净化后保存。

type UintList added in v2.2.0

type UintList []uint

UintList 以 JSON 文本存放的正整数列表(SQLite 里是 text 列,API 里是数组),用来存凭据允许导出的项目编号。

func (UintList) Contains added in v2.2.0

func (l UintList) Contains(id uint) bool

Contains 报告列表里是否有这个编号。

func (*UintList) Scan added in v2.2.0

func (l *UintList) Scan(value interface{}) error

func (UintList) Value added in v2.2.0

func (l UintList) Value() (driver.Value, error)

type UpdateStagesInput

type UpdateStagesInput struct {
	ProjectID        string     `json:"project_id"`
	TaskID           string     `json:"task_id"`
	ExpectedRevision int64      `json:"expected_revision,omitempty"`
	CurrentStageID   string     `json:"current_stage_id,omitempty"`
	Stages           TaskStages `json:"stages"`
	IdempotencyKey   string     `json:"idempotency_key,omitempty"`
}

type UpdateTaskInput

type UpdateTaskInput struct {
	ProjectID        string `json:"project_id"`
	TaskID           string `json:"task_id"`
	ExpectedRevision int64  `json:"expected_revision"`
	Mode             string `json:"mode"` // replace, patch
	Segment          string `json:"segment"`
	OldText          string `json:"old_text,omitempty"`
	NewText          string `json:"new_text"`
	IdempotencyKey   string `json:"idempotency_key,omitempty"`
}

type UserNorm

type UserNorm struct {
	Name      string    `gorm:"primaryKey;size:128" json:"name"`
	Summary   string    `gorm:"size:500;not null" json:"summary"`
	Content   string    `gorm:"type:text;not null" json:"content"`
	IsActive  bool      `gorm:"default:true" json:"is_active"`
	SortOrder int       `gorm:"default:0" json:"sort_order"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type WaitPolicy

type WaitPolicy struct {
	AfterMinutes         int    `json:"after_minutes"`
	MaxNoFeedbackChecks  int    `json:"max_no_feedback_checks"`
	WaitInstruction      string `json:"wait_instruction"`
	ExhaustedInstruction string `json:"exhausted_instruction"`
}

func (*WaitPolicy) Scan

func (w *WaitPolicy) Scan(value interface{}) error

func (WaitPolicy) Value

func (w WaitPolicy) Value() (driver.Value, error)

type WaitStatus

type WaitStatus struct {
	State                string `json:"state"` // waiting, exhausted
	SourceReportSequence int64  `json:"source_report_sequence,omitempty"`
	NoFeedbackChecks     int    `json:"no_feedback_checks,omitempty"`
	MaxChecks            int    `json:"max_checks,omitempty"`
	AfterMinutes         int    `json:"after_minutes,omitempty"`
	Instruction          string `json:"instruction"`
}

type WorkBoardCounter

type WorkBoardCounter struct {
	BoardKey string `gorm:"primaryKey;size:160" json:"board_key"`
	LastSeq  int    `gorm:"not null;default:0" json:"last_seq"`
}

WorkBoardCounter 记录每张板已发出的最大序号,保证序号不复用(#175)。

type WorkItem

type WorkItem struct {
	ID         uint   `gorm:"primaryKey;autoIncrement" json:"id"`
	WorkflowID string `gorm:"size:128;not null;index;uniqueIndex:ux_work_item_seq,priority:1" json:"workflow_id"`
	// BoardKey 是任务所在的板(#175):项目板 "p<项目编号>",独立板 "w:<工作流编号>"。Seq 在板内唯一、只增不复用;
	// WorkflowID 的含义是「创建它的工作流」(来源)。迁移前的历史行是空串,启动时由 reconcileBoards 补齐;
	// 部分唯一索引只约束已归板的行,旧二进制写入的空值行不会触发冲突。
	BoardKey string      `` /* 147-byte string literal not displayed */
	Seq      int         `gorm:"not null;uniqueIndex:ux_work_item_seq,priority:2;uniqueIndex:ux_work_item_board_seq,priority:2" json:"seq"`
	Title    string      `gorm:"size:256;not null" json:"title"`
	Kind     string      `gorm:"size:16;not null;default:'feature';index" json:"kind"`
	Labels   StringArray `gorm:"type:text" json:"labels"`
	State    string      `gorm:"size:16;not null;default:'todo';index" json:"state"`
	// Description 是任务内容的说明:这件事是什么、要做到什么程度。标题只是名字,进度只回答「现在做到哪」,
	// 都不足以让人在任务页和任务弹窗里看懂「这个任务到底指什么」;创建任务时写一次,之后很少改。
	// 只改描述不算进展:不动 updated_at、不占时间线(与调整归属同理)。
	Description string `gorm:"type:text" json:"description"`
	// Stage 是任务所处的阶段(评估 / 方案 / 开发 / 改进),空串 = 未标注;见上面的常量说明。
	Stage string `gorm:"size:16;not null;default:''" json:"stage,omitempty"`
	// Progress 是「最新进度」:每次覆盖写入,只回答现在做到哪;历史由时间线承载。
	Progress string `gorm:"type:text" json:"progress"`
	// Conclusion 是 1–3 行的结论,任务收尾时写;时间线被压缩后它是唯一保留下来的「做完了什么」。
	Conclusion string      `gorm:"type:text" json:"conclusion"`
	Refs       StringArray `gorm:"type:text" json:"refs"`
	// ParentID 指向「批次」任务,只允许一层嵌套。
	ParentID *uint `gorm:"index" json:"parent_id,omitempty"`
	// ModuleID 指向规划树上的模块或功能(work_modules);为空表示「未归类」。
	ModuleID *uint `gorm:"index" json:"module_id,omitempty"`
	// Percent 是显式写下的完成度(0–100);为空表示由状态 / 子任务推导,见 EffectivePercent。
	Percent         *int       `json:"percent,omitempty"`
	SourceSessionID string     `gorm:"size:128" json:"source_session_id,omitempty"`
	LastSessionID   string     `gorm:"size:128" json:"last_session_id,omitempty"`
	CreatedBy       string     `gorm:"size:16;not null;default:'human'" json:"created_by"`
	ClosedAt        *time.Time `json:"closed_at,omitempty"`
	CreatedAt       time.Time  `json:"created_at"`
	UpdatedAt       time.Time  `json:"updated_at"`

	// 指派(#175 B2,设计稿 design/shared-task-board-b2.md):管理 Agent / 人把任务派给板上的某个工作流,
	// 承接者接取(或拒绝)、交付,派发者验收。这四个字段回答「现在由谁承接、谁派的、接没接」,
	// 全部是加列、默认空串:空 AssigneeWorkflowID = 没有指派,行为与 B2 之前完全一致。
	// AssignedByWorkflowID 为空而 AssigneeWorkflowID 非空 = 人在 Web 上派的(没有 Agent 派发者)。
	AssigneeWorkflowID string `gorm:"size:128;not null;default:'';index" json:"assignee_workflow_id,omitempty"`
	// AssignedByWorkflowID 带索引(#180 B3a):回执头的 board: 行每次回执都要按「谁派的」查派发者侧的待办(待验收 / 被拒绝 / 久无人接)。
	AssignedByWorkflowID string     `gorm:"size:128;not null;default:'';index" json:"assigned_by_workflow_id,omitempty"`
	ClaimState           string     `gorm:"size:16;not null;default:''" json:"claim_state,omitempty"`
	AssignedAt           *time.Time `json:"assigned_at,omitempty"`
	AcceptedAt           *time.Time `json:"accepted_at,omitempty"`
	// OfferRemindedAt 是「指派久无人接」那条一次性提醒发出的时间(#180 B3d):空 = 还没提醒过。
	// 它只记「这一轮派出(AssignedAt 之后)已经提醒过」:重新派出(AssignedAt 变新)后重新有资格被提醒一次,所以改派 / 拒绝后再派不必清它。
	// 只加一个可空列;旧版本二进制不认识它、直接忽略,回滚不受影响。不对外返回。
	OfferRemindedAt *time.Time `json:"-"`

	// 以下字段不落库,由查询按需填充。
	Updates     []WorkItemUpdate  `gorm:"-" json:"updates,omitempty"`
	Sessions    []WorkItemSession `gorm:"-" json:"sessions,omitempty"`
	ChildTotal  int               `gorm:"-" json:"child_total,omitempty"`
	ChildDone   int               `gorm:"-" json:"child_done,omitempty"`
	SessionNum  int               `gorm:"-" json:"session_count,omitempty"`
	ParentTitle string            `gorm:"-" json:"parent_title,omitempty"`
	ParentSeq   int               `gorm:"-" json:"parent_seq,omitempty"`
	// ModulePath 是所属模块的完整路径(终端/历史日志);未归类时为空。
	ModulePath string `gorm:"-" json:"module,omitempty"`
	// ProgressPct / ProgressFrom 是进度条上的取值与来源(explicit / children / state),见 EffectivePercent。
	ProgressPct  int    `gorm:"-" json:"progress_pct"`
	ProgressFrom string `gorm:"-" json:"progress_from,omitempty"`
	// SessionCtx 只在按会话查询(WorkItemFilter.SessionID)时填充:这个会话对这条任务做了什么。
	SessionCtx *WorkItemSessionCtx `gorm:"-" json:"session_ctx,omitempty"`
}

WorkItem 是任务本体。ID 是全局自增主键(REST 使用);Seq 是板内的序号(智能体与界面上的 #12)。 单工作流的板里它就是工作流内的序号;同一项目的多个工作流共用一张板时,它们共用一套序号。 序号只增不复用:删掉 #12 之后新任务也是 #13,避免提交说明里的旧引用指向别的事。

func (*WorkItem) IsClosed

func (w *WorkItem) IsClosed() bool

IsClosed 表示任务已离开主线(已完成或已搁置)。

func (*WorkItem) IsCollaborative

func (w *WorkItem) IsCollaborative() bool

IsCollaborative 表示任务有「协作指派」:已指派,且派发者 ≠ 承接者(人在 Web 上派的也算)。 只有这种任务才有「承接者交付、派发者验收」的分工;自己给自己的任务(无指派,或派发者 = 承接者)照旧由自己置完成。

type WorkItemAlias

type WorkItemAlias struct {
	OldWorkflowID string    `gorm:"primaryKey;size:128" json:"old_workflow_id"`
	OldSeq        int       `gorm:"primaryKey" json:"old_seq"`
	WorkItemID    uint      `gorm:"not null;index" json:"work_item_id"`
	CreatedAt     time.Time `json:"created_at"`
}

WorkItemAlias 是改号后的旧号别名(#175):显式合并板时,被重编的任务把旧的(工作流,序号)留在这里, 这样旧提交说明、文档里的 #N 仍能解析到它。迁移本身永不改号,所以平时这张表是空的。

type WorkItemCounter

type WorkItemCounter struct {
	WorkflowID string `gorm:"primaryKey;size:128" json:"workflow_id"`
	LastSeq    int    `gorm:"not null;default:0" json:"last_seq"`
}

WorkItemCounter 记录每个工作流已发出的最大序号,保证序号不复用。 #175 起序号按板分配(WorkBoardCounter),这张旧表由新代码同步写入,只为让旧二进制回滚后仍能接着发号。

type WorkItemSession

type WorkItemSession struct {
	WorkItemID uint      `gorm:"primaryKey" json:"-"`
	SessionID  string    `gorm:"primaryKey;size:128;index" json:"session_id"`
	CreatedAt  time.Time `json:"linked_at"`

	// 以下字段不落库,来自会话本身,方便界面直接展示。
	Title  string `gorm:"-" json:"title,omitempty"`
	Status string `gorm:"-" json:"status,omitempty"`
}

WorkItemSession 是任务与会话的关联(多对多)。

type WorkItemSessionCtx

type WorkItemSessionCtx struct {
	// Created 表示这条任务是这个会话创建的。
	Created bool `json:"created"`
	// Updates 是这个会话写在时间线上的条数(创建那一条也算)。
	Updates int `json:"updates"`
	// FromState / ToState:这个会话第一次与最近一次改变状态时的「原状态」与「新状态」;会话没有改过状态时为空。
	FromState string `json:"from_state,omitempty"`
	ToState   string `json:"to_state,omitempty"`
	// LastAt 是这个会话最近一次写时间线的时间;时间线上没有它的记录(只是被关联)时为空。
	LastAt *time.Time `json:"last_at,omitempty"`
}

WorkItemSessionCtx 描述「某个会话」与「某条任务」的关系,供会话页的「本对话的任务」展示。 数据来自任务的时间线(每个任务只保留最近 WorkUpdatesKeep 条),所以 Updates 是「时间线上还看得见的条数」。

type WorkItemSessionLink struct {
	SessionID  string `json:"session_id"`
	WorkItemID uint   `json:"work_item_id"`
	WorkItemSessionCtx
}

WorkItemSessionLink 是「某个会话涉及某个任务」的一条关联,连同这个会话对任务做了什么。 会话页按轮次(每个会话)展开本轮涉及的任务时,一次取回整个工作流的全部关联。

type WorkItemUpdate

type WorkItemUpdate struct {
	ID         uint      `gorm:"primaryKey;autoIncrement" json:"id"`
	WorkItemID uint      `gorm:"not null;index" json:"work_item_id"`
	ActorKind  string    `gorm:"size:16;not null" json:"actor_kind"`
	SessionID  string    `gorm:"size:128" json:"session_id,omitempty"`
	FromState  string    `gorm:"size:16" json:"from_state,omitempty"`
	ToState    string    `gorm:"size:16" json:"to_state,omitempty"`
	Text       string    `gorm:"type:text" json:"text,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	// ActorWorkflowID 是智能体写入时它自己的工作流(共享板上看「谁改的」);人在 Web 上写入为空。
	ActorWorkflowID string `gorm:"size:128;not null;default:''" json:"actor_workflow_id,omitempty"`
	// Event 只给协作相关的动作写(见 WorkEvent* 常量);普通进展(状态 / 进度 / 备注)留空,由 from / to / text 表达。
	Event string `gorm:"size:24;not null;default:''" json:"event,omitempty"`
}

WorkItemUpdate 是时间线上的一条进展:一次状态变化、一段进度或一句备注。

type WorkModule

type WorkModule struct {
	ID         uint   `gorm:"primaryKey;autoIncrement" json:"id"`
	WorkflowID string `gorm:"size:128;not null;index" json:"workflow_id"`
	// BoardKey 是规划树所在的板(#175),同一张板里的各工作流共用一棵树;WorkflowID 是创建它的工作流。
	BoardKey    string `gorm:"size:160;not null;default:'';index" json:"board_key"`
	ParentID    *uint  `gorm:"index" json:"parent_id,omitempty"`
	Name        string `gorm:"size:128;not null" json:"name"`
	Description string `gorm:"size:512" json:"description"`
	// Sort 是同级内的顺序(小的在前);每次写入后会被规整成 0..n-1。
	Sort      int       `gorm:"not null;default:0" json:"sort"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`

	// 以下字段不落库,由查询按需填充。
	Path  string          `gorm:"-" json:"path"`
	Depth int             `gorm:"-" json:"depth"`
	Stats WorkModuleStats `gorm:"-" json:"stats"`
}

WorkModule 是规划树上的一个节点。ParentID 为空的是顶层「模块」,否则是它下面的「功能」。

type WorkModuleStats

type WorkModuleStats struct {
	Total   int `json:"total"`
	Todo    int `json:"todo"`
	Doing   int `json:"doing"`
	Review  int `json:"review"`
	Done    int `json:"done"`
	Shelved int `json:"shelved"`
	// Percent 是未搁置任务有效进度(见 EffectivePercent)的平均值;没有任务时为 0。
	Percent int `json:"percent"`
}

WorkModuleStats 是节点上任务的汇总(顶层模块包含它下面各功能的任务)。 只统计「叶子任务」(没有子任务的任务),批次任务本身不重复计入。

func (WorkModuleStats) Open

func (s WorkModuleStats) Open() int

Open 是尚未结束的任务数(待办 + 进行中 + 验证中)。

type WorkflowBranch added in v2.1.0

type WorkflowBranch struct {
	ID               uint         `gorm:"primaryKey" json:"id"`
	BranchWorkflowID string       `gorm:"size:128;not null;uniqueIndex" json:"branch_workflow_id"`
	ParentWorkflowID string       `gorm:"size:128;not null;index" json:"parent_workflow_id"`
	CreatedBy        string       `gorm:"size:160;not null" json:"created_by"`
	Expose           BranchExpose `gorm:"type:text" json:"expose"`
	CopyUserNotes    bool         `gorm:"not null" json:"copy_user_notes"`
	Status           string       `gorm:"size:16;not null;index" json:"status"`
	CreatedAt        time.Time    `json:"created_at"`
	ClosedAt         *time.Time   `json:"closed_at,omitempty"`
}

WorkflowBranch 是一条「分支 → 主会话」的关系。库里没有 workflows 表,所以关系直接记两个工作流编号。 CopyUserNotes 故意不写 default 标签:GORM 创建时会把零值换成列默认值,「关闭抄送」就存不进去了。

func (WorkflowBranch) Active added in v2.1.0

func (b WorkflowBranch) Active() bool

Active 表示关系仍然生效。

type WorkflowCheckpoint

type WorkflowCheckpoint struct {
	ID          uint      `gorm:"primaryKey;autoIncrement" json:"id"`
	WorkflowID  string    `gorm:"index;size:128;not null" json:"workflow_id"`
	Revision    int       `gorm:"not null" json:"revision"`
	Status      string    `gorm:"size:32;not null;default:'submitted'" json:"status"`
	ContentJSON string    `gorm:"type:text;not null" json:"content_json"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type WorkflowDraft

type WorkflowDraft struct {
	WorkflowID  string    `gorm:"primaryKey;size:128" json:"workflow_id"`
	ActiveIndex int       `gorm:"default:0" json:"active_index"`
	DraftsJSON  string    `gorm:"type:text" json:"drafts_json"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type WorkflowHookSeen

type WorkflowHookSeen struct {
	WorkflowID string    `gorm:"primaryKey;size:128" json:"workflow_id"`
	SeenAt     time.Time `gorm:"not null;index" json:"seen_at"`
}

WorkflowHookSeen 记下某个工作流的编辑器 hook 最近一次来过的时间,唯一目的是让 Hub 重启后不丢(#103)。 写入有节流(同一工作流最多每分钟一次,见 store.HookSeenPersistEvery),所以落库的时间最多比真实时间旧一分钟: 重启后恢复出来的值只会偏旧、不会偏新——对 60 分钟的新鲜度窗口可以忽略,而且方向是安全的。

type WorkflowMode

type WorkflowMode struct {
	WorkflowID   string `gorm:"primaryKey;size:128" json:"workflow_id"`
	AsyncEnabled bool   `gorm:"default:false" json:"async_enabled"`
	// EverEnabled:曾经开启过(关掉之后仍为真)。只有开启过的工作流,回执头里才会出现 mode: 行(INV-2:
	// 没用过异步的工作流,回执与升级之前逐字一致)。
	EverEnabled bool `gorm:"default:false" json:"ever_enabled"`
	// ProfileID 是选用的授权档位;0 或档位已被删除时按默认档位处理。
	ProfileID uint `json:"profile_id"`
	// EnabledAt 是最近一次开启的时间:时间线里的任务更新卡只显示这之后的变化,免得一开启就刷出一屏历史。
	EnabledAt *time.Time `json:"enabled_at,omitempty"`
	// ReplyWindowUntil 是异步对话的「回复窗口」截止时间(#123):智能体每发一条新消息就累加一段,用户一回复就清零;
	// nil = 当前没有在等回复。窗口走完而没有新消息,智能体才可以收尾。
	ReplyWindowUntil *time.Time `json:"reply_window_until,omitempty"`
	// ReplyWindowBankSec 是窗口暂停时攒着的剩余秒数:只要智能体还有进行中 / 验证中的任务,回复窗口就不走,
	// 因为它没有「空下来等你」;任务清零后从这里接着走(用户 2026-10-15:倒计时仅在没有任务时触发,否则不算异步)。
	ReplyWindowBankSec int `gorm:"default:0" json:"reply_window_bank_sec,omitempty"`
	// StrictWrapupOff:用户在这个会话上关掉了「严格收尾门」(#232 D2)。默认 false = 开着:回复窗口只要本会话名下
	// 还有未完成(待办 / 进行中 / 验证中)的任务就不走,且不按时间截断——「做完所有非搁置任务再结束会话」;
	// 关掉后回到老口径(只数进行中 / 验证中、且 3 小时内有更新的任务)。取反存储,老库升级后自然是「开着」。
	StrictWrapupOff bool `gorm:"default:false" json:"strict_wrapup_off,omitempty"`
	// GateReleased:用户点了「本次放行」,当前这一轮窗口不再被任务挡住、照常倒计时。
	// 「一次」的含义:用户下一次回复(窗口清零)或窗口过期后重新起算时自动复位,不留成永久开关。
	GateReleased bool `gorm:"default:false" json:"gate_released,omitempty"`
	// ToldSig 是最近一次告诉智能体的「模式签名」(见 asyncmode.Signature):模式或档位变了、而智能体还没被告知时,
	// 下一次任意工具回执会补一段说明(只提醒一次),让它在工作中途就知道升级 / 降级了。
	ToldSig   string    `gorm:"size:64" json:"-"`
	UpdatedAt time.Time `json:"updated_at"`
}

WorkflowMode 记录某个工作流是否开启了异步对话,以及选用的授权档位。每个工作流至多一行,没有行等于「从未开启」。

type WorkflowNote

type WorkflowNote struct {
	ID         uint      `gorm:"primaryKey;autoIncrement" json:"id"`
	WorkflowID string    `gorm:"index;size:128" json:"workflow_id"`
	SessionID  string    `gorm:"index;size:128" json:"session_id,omitempty"`
	NoteKey    string    `gorm:"size:128" json:"note_key,omitempty"`
	Content    string    `gorm:"type:text;not null" json:"content"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type WorkflowPhaseState

type WorkflowPhaseState struct {
	WorkflowID            string    `gorm:"primaryKey;size:128" json:"workflow_id"`
	CurrentPhaseID        string    `gorm:"size:64;not null;default:'assess'" json:"current_phase_id"`
	HumanPreferredPhaseID string    `gorm:"size:64;not null;default:'assess'" json:"human_preferred_phase_id"`
	PhasesJSON            string    `gorm:"type:text" json:"phases_json"`
	UpdatedAt             time.Time `json:"updated_at"`
}

type WorkflowPrompt added in v2.1.0

type WorkflowPrompt struct {
	WorkflowID string `gorm:"primaryKey;size:128" json:"workflow_id"`
	// Resident 是常驻提示词全文;空串表示没有(或已清除)。
	Resident string `gorm:"type:text" json:"resident"`
	// ResidentRev 每次保存(内容有变化时)加一;从没保存过为 0。
	ResidentRev int `gorm:"default:0" json:"resident_rev"`
	// ResidentToldRev 是已经告诉过智能体的版本:回执头 / 恢复路径带上全文时追平;
	// 它落后于 ResidentRev,说明用户改过而智能体还没见到新版本,下一次任意工具回执会补一段「常驻指令已更新」(只提醒一次)。
	ResidentToldRev int `gorm:"default:0" json:"resident_told_rev"`
	// WakeResume / WakeNew 是这个会话自己的唤醒词模板(#232 D3):Hub 在非交互续聊 / 新开对话时发给智能体的那段话。
	// 空串 = 没有,沿用全局设置里的覆盖,再没有就用内置默认。模板里的 %变量 在每次发送时现算(见 internal/sessionprompt)。
	// 它们没有「已告知」状态:模板由 Hub 在发送时读取,不是智能体在回执里读的,所以保存即生效、不涨 ResidentRev。
	WakeResume string    `gorm:"type:text" json:"wake_resume"`
	WakeNew    string    `gorm:"type:text" json:"wake_new"`
	UpdatedAt  time.Time `json:"updated_at"`
	// UpdatedBy 是最近一次保存的操作者(Web 登录用户名;回滚时同样记录)。
	UpdatedBy string `gorm:"size:64" json:"updated_by,omitempty"`
}

WorkflowPrompt 是某个工作流的提示词设置;每个工作流至多一行,没有行等于「从没配置过」。

type WorkflowPromptRevision added in v2.1.0

type WorkflowPromptRevision struct {
	ID         uint      `gorm:"primaryKey" json:"id"`
	WorkflowID string    `gorm:"size:128;not null;index:idx_wpr_wf_field,priority:1" json:"workflow_id"`
	Field      string    `gorm:"size:32;not null;index:idx_wpr_wf_field,priority:2" json:"field"`
	Rev        int       `json:"rev"`
	Text       string    `gorm:"type:text" json:"text"`
	Actor      string    `gorm:"size:64" json:"actor,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
}

WorkflowPromptRevision 是提示词的一个历史版本,用于回滚与审计。

type WorkflowTrash added in v2.2.0

type WorkflowTrash struct {
	ID         uint   `gorm:"primaryKey" json:"id"`
	WorkflowID string `gorm:"size:128;not null;index" json:"workflow_id"`
	// Title 是删除时的会话名(自定义名 > 最近一轮的标题 > 工作流编号),只用于「最近删除」列表展示。
	Title            string `gorm:"size:256" json:"title"`
	ProjectDirectory string `gorm:"size:512" json:"project_directory,omitempty"`
	HostName         string `gorm:"size:128" json:"host_name,omitempty"`
	// Rounds / Queued / Images 是快照里的轮次数、追加指令数、截图张数(只给列表展示用,恢复时以快照内容为准)。
	Rounds int `json:"rounds"`
	Queued int `json:"queued"`
	Images int `json:"images"`
	// SizeBytes 是快照(压缩后)占用的字节数。
	SizeBytes int64 `json:"size_bytes"`
	// FormatVersion 是快照格式的版本,将来换格式时靠它区分。
	FormatVersion int       `gorm:"not null;default:1" json:"-"`
	TrashedAt     time.Time `gorm:"index" json:"trashed_at"`
	// ExpiresAt 之后后台清理会把这一条彻底删掉。
	ExpiresAt time.Time `gorm:"index" json:"expires_at"`
	// Payload 是 gzip 压缩的 JSON Lines(逐条记录,恢复时逐条读,不必一次装进内存);列表接口从不读它。
	Payload []byte `gorm:"type:blob" json:"-"`
}

WorkflowTrash 是会话回收站里的一条(#292):整条会话(工作流)在被删除那一刻的完整快照。

为什么是「快照 + 删原行」而不是给原行打删除标记:会话相关的查询散在几十处(侧栏、搜索、项目成员、用量统计、MCP 工具……), 逐处加「排除已删除」迟早会漏一处,让删掉的内容在某个角落冒出来;把整条会话搬进这张表,原表里就真的没有它了, 现有的所有查询都不用改,也就不会漏。恢复时再把快照原样放回去。

快照里有什么:这条会话的全部轮次(含截图)、追加指令(含截图)、阶段状态、检查点、备忘、草稿与草稿图片、自定义会话名。 没有的(删除时原样留在库里,不属于「会话本身」):任务清单里的任务、项目文档、群聊里的发言、审计记录; 也不含场景模式、提示词参数、确认项、终端记录等「按工作流编号挂着」的杂项,它们不跟着会话走,恢复后自然还在。

只增表:旧版本二进制打开新库时忽略它,不影响任何已有数据。

Jump to

Keyboard shortcuts

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