项目存储与旧状态迁移
Wenext-Pi 将任务、会话、运行记录与证据放在用户状态目录,普通项目不需要维护仓库内运行脚本或状态文件。旧 .wenext-spec 运行状态在项目准备时复制迁移,原文件保留。
查找项目
wenext-pi projects
wenext-pi projects my-project --json
wenext-pi doctor --root /path/to/projectprojects 只读枚举已知项目,可按名称、项目根或状态路径过滤,不创建目录、不迁移、不启动模型。返回 name、root、stateRoot、tasksRoot、status 及可选 reason;源目录缺失为 missing_root,身份损坏或重复为 invalid。
doctor 和交互启动使用相同项目准备路径,可能初始化或迁移状态。项目根默认为启动目录,可用 --root 指定,不自动查找 Git 根。
存储布局
WENEXT_PI_HOME 默认 ~/.wenext-pi:
~/.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 是完成等操作的协调目录,释放租约后父目录可以保留。它不是用户任务,也不应为了恢复启动而删除。活进程租约不能按时间强制抢占;正常停止占用者后再恢复,见本机协调。