Documentation
¶
Overview ¶
Package continuitybinding 实现 user-level continuity binding registry。
binding 把当前 Git repository/worktree 精确映射到一个已注册 vault 和 bounded scope。registry 是 CLI/service 独占写入的 versioned YAML 文件, 存放在 user-level config 目录(owner-only 0600),不进入 repository、 vault note 或 Git。Agent 和用户不得手写该文件。
第一 slice 只支持 exact canonical worktree root 匹配:不按目录名、Git remote、语义相似度或最近使用记录猜测绑定,避免错误合并两个本地 checkout。
Index ¶
- Constants
- func CanonicalizeRepoRoot(path string) (string, error)
- func DetectWorktreeRoot(ctx context.Context, path string) (string, error)
- func Digest(canonicalRoot string) string
- func RedactedRoot(canonicalRoot string) string
- func RegistryPath(configDir string) string
- func SaveRegistry(configDir string, registry Registry) error
- type Binding
- type BindingStatus
- type Registry
Constants ¶
const ( // ErrCodeBindingAmbiguous 表示同一 canonical worktree 存在多个 enabled exact binding。 ErrCodeBindingAmbiguous = "continuity_binding_ambiguous" // ErrCodeBindingInvalid 表示 registry 或 binding record 损坏/目标失效。 ErrCodeBindingInvalid = "continuity_binding_invalid" )
稳定错误码(additive;不回写已有 agentprotocol 错误码语义)。
const BindingSchemaVersion = "pinax.continuity_binding.v1"
BindingSchemaVersion 是 continuity binding 的逻辑 schema 版本。
Variables ¶
This section is empty.
Functions ¶
func CanonicalizeRepoRoot ¶
CanonicalizeRepoRoot 把任意 repo 路径规范化为 canonical worktree root。 顺序:Abs → EvalSymlinks。Windows 下大小写不敏感但保留原样, 由 registry 的 exact key 比较负责一致性(测试覆盖)。
注意:这里不做 prefix 匹配。两个路径即使共享前缀也只在完全相等时 命中同一 binding,这是 fail-closed 的关键边界。
func DetectWorktreeRoot ¶
DetectWorktreeRoot 返回 path 所属 Git worktree 的 canonical 顶层目录。
边界说明(中文):
- 使用 `git rev-parse --show-toplevel` 解析 worktree 根。该命令在 非 Git 目录返回非零退出码,我们据此返回 not_a_repository 语义; 不向父目录之外的未知位置搜索,也不扫描其他 vault。
- 返回路径经 CanonicalizeRepoRoot 规范化(Abs + EvalSymlinks), 使得通过 symlink 进入同一 worktree 的调用命中同一 exact binding key。
- 超时 5s 防止损坏的 Git 状态挂起短生命周期 CLI 进程。
func Digest ¶
Digest 计算 canonical worktree root 的 bounded sha256 digest(16 hex chars)。 digest 用于 machine output 与 receipt 关联,不可逆推出完整路径。
func RedactedRoot ¶
RedactedRoot 返回 bounded basename,用于默认 machine output。 只暴露路径最后一段,避免泄漏用户 home 目录结构。
func RegistryPath ¶
RegistryPath 返回 registry 文件路径(user-level config dir 下)。 configDir 为空时使用默认 config dir 调用方提供的路径。
func SaveRegistry ¶
SaveRegistry 原子写入 registry(temp + rename),权限 owner-only 0600。 原子写保证并发/崩溃时不会留下半截 YAML 触发损坏分支。
Types ¶
type Binding ¶
type Binding struct {
// BindingID 是 opaque 稳定标识(bind_<digest>)。
BindingID string `yaml:"binding_id" json:"binding_id"`
// SchemaVersion 固定为 pinax.continuity_binding.v1。
SchemaVersion string `yaml:"schema_version" json:"schema_version"`
// CanonicalRepoRoot 是 canonical(symlink-resolved)worktree 绝对路径。
CanonicalRepoRoot string `yaml:"canonical_repo_root" json:"-"`
// RepoRootDigest 是 CanonicalRepoRoot 的 bounded sha256 digest。
RepoRootDigest string `yaml:"repo_root_digest" json:"repo_root_digest"`
// VaultRef 是已注册 vault selector(alias 或绝对路径),必须可解析。
VaultRef string `yaml:"vault_ref" json:"vault_ref"`
// ScopeKind 是 bounded scope kind(如 project)。
ScopeKind string `yaml:"scope_kind" json:"scope_kind"`
// ScopeID 是 bounded scope 标识(如 pinax)。
ScopeID string `yaml:"scope_id" json:"scope_id"`
// Enabled 控制该 binding 是否参与自动解析。
Enabled bool `yaml:"enabled" json:"enabled"`
// CreatedAt 是创建时间。
CreatedAt time.Time `yaml:"created_at" json:"created_at"`
// UpdatedAt 是最近更新时间。
UpdatedAt time.Time `yaml:"updated_at" json:"updated_at"`
}
Binding 是一条 continuity binding 记录(pinax.continuity_binding.v1)。 canonical_repo_root 只用于本机解析;machine output 只暴露 digest 和 bounded basename,不泄漏完整 home 路径。
func (Binding) Scope ¶
func (b Binding) Scope() agentprotocol.Scope
Scope 返回 binding 的 protocol scope。
type BindingStatus ¶
type BindingStatus string
BindingStatus 是 binding 解析状态机,用于 status projection 与自动解析。
const ( // StatusReady 表示 repository、vault、scope 与 registry 均可解析。 StatusReady BindingStatus = "ready" // StatusMissing 表示当前 worktree 没有 enabled binding。 StatusMissing BindingStatus = "missing" // StatusDisabled 表示 binding 存在但被显式禁用(rollback 保留数据)。 StatusDisabled BindingStatus = "disabled" // StatusInvalid 表示 binding record 或目标 vault/scope 不可解析。 StatusInvalid BindingStatus = "invalid" // StatusAmbiguous 表示同一 worktree 有多个 enabled exact binding(fail closed)。 StatusAmbiguous BindingStatus = "ambiguous" // StatusNotARepository 表示当前目录不属于可解析的 Git worktree。 StatusNotARepository BindingStatus = "not_a_repository" )
type Registry ¶
type Registry struct {
SchemaVersion string `yaml:"schema_version" json:"schema_version"`
Bindings []Binding `yaml:"bindings,omitempty" json:"bindings,omitempty"`
}
Registry 是 continuity binding registry 的 versioned 文件形态。
func LoadRegistry ¶
LoadRegistry 读取 registry;文件不存在时返回空 registry(不是错误)。 YAML 损坏时返回 continuity_binding_invalid,调用方必须 fail closed。
func (Registry) EnabledFor ¶
EnabledFor 返回某 canonical root 的全部 enabled binding。 多条结果即 ambiguous——registry 写路径保证唯一,读到多条说明状态损坏。