Skip to content

项目存储与旧状态迁移 ​

文档导航 · 会话恢复

Wenext-Pi 将任务、会话、运行记录与证据放在用户状态目录,普通项目不需要维护仓库内运行脚本或状态文件。旧 .wenext-spec 运行状态在项目准备时复制迁移,原文件保留。

查找项目 ​

bash
wenext-pi projects
wenext-pi projects my-project --json
wenext-pi doctor --root /path/to/project

projects 只读枚举已知项目,可按名称、项目根或状态路径过滤,不创建目录、不迁移、不启动模型。返回 name、root、stateRoot、tasksRoot、status 及可选 reason;源目录缺失为 missing_root,身份损坏或重复为 invalid。

doctor 和交互启动使用相同项目准备路径,可能初始化或迁移状态。项目根默认为启动目录,可用 --root 指定,不自动查找 Git 根。

存储布局 ​

WENEXT_PI_HOME 默认 ~/.wenext-pi:

text
~/.wenext-pi/
  nodes.json
  reporting.json
  metrics-installation.json
  metrics/v2/<destination-hash>/
  tools/test-tool/
  memory/user/
  projects/<name>--<path-hash>/
    project.json
    tasks/
      <task>/
        task.json
        planning-contract.json
        prd.md
        sessions/
        agents/
        continuity/
        quality/
        write-scope/
        plan-review/
        plugins/
        artifacts/
      archive/
      .coordination/
    workspace/
    runtime/

任务内部目录按需要创建,并非每个任务都需要完整方案或所有插件状态。模型与凭据通常在 ~/.pi/agent,不属于这里的 Wenext-Pi 状态根。

项目名来自规范化目录名,后缀为规范化根路径 SHA-256 的前 12 位;project.json.root 中完整根仍用于身份校验。同名 checkout/worktree 分离,指向同一规范根的别名复用状态。移动源根不会自动绑定旧任务。

旧 32 字符哈希目录原地复用,不改名以免破坏绝对会话和证据引用。若旧目录和可读目录同时存在,明确报错并保留两者,不自动合并。非空目录身份错误时也不创建空状态覆盖它。

迁移规则 ​

旧 .wenext-spec/ 下的内容新项目状态中的目标
tasks/tasks/
workspace/workspace/
.runtime/runtime/

业务规范和模板不自动迁移。初次迁移复制到临时相邻目录,再校验源指纹、写入项目标记并原子改名激活。指纹覆盖路径、类型、大小、时间、权限和符号链接目标,是元数据检查,不是内容摘要或跨进程写锁。检测到源新增、删除或改变时拒绝激活。

标记为 schema 1,包含 root 与可选 legacyFingerprints。已有无指纹的合法标记仍可用。激活后外置状态为权威,后续旧备份改变、不可读或新增内容只产生提示,不重新导入或覆盖当前任务;旧备份删除也不阻止启动。

迁移会更新被复制 Pi JSONL 的 task.sessionFile、活动指针及 continuity/ranges 引用,并重新生成范围文件键。业务任务额外元数据保留,缺少的批准和质量证据不补造。多个未完成候选仍须明确选择。

空目录与冲突处理 ​

情况行为
没有外置状态且旧目录稳定复制迁移,保留原文件
外置目标为空或只有普通 .DS_Store清除 Finder 元数据与空壳,再正常初始化
非空目标缺少合法标记/根不匹配拒绝,保留内容
同时存在旧哈希与新可读目录拒绝,报告两个路径
初次复制期间源变化放弃临时目标,不激活
激活后旧备份变化提示差异,继续使用外置状态
源项目目录已不存在projects 可列出 missing_root,不修复

空壳删除采用非递归 rmdir;并发写者新增内容会阻止删除并转入身份校验。任意其他文件、任务、运行目录或符号链接都不能按空目录处理。

出现冲突时先用 projects 查清两套状态的归属,保留历史再决定显式导入或备份处置。不要复制旧 task.json 覆盖外置任务,也不要通过删除标记和锁让 CLI 重新初始化。

任务发现与锁目录 ​

只有活动任务根下含 task.json 的普通直接子目录才是候选。archive、点开头内部目录、符号链接和无任务记录的目录不会被当作任务。候选记录损坏时仍报解析错误,不静默跳过。

.coordination 是完成等操作的协调目录,释放租约后父目录可以保留。它不是用户任务,也不应为了恢复启动而删除。活进程租约不能按时间强制抢占;正常停止占用者后再恢复,见本机协调。