将项目写锁从 project/filesystem.rs 纯搬移到 project/write_lock.rs
- 新建 project/write_lock.rs：取锁、等待分类、持锁方诊断、残留回收与 4 条锁用例整体搬移，逻辑不变 - project/filesystem.rs 只保留项目文件 IO（1533 → 680 行），锁相关常量、结构、进程判据与用例全部移出 - project.rs 注册 mod write_lock 并 pub(crate) use write_lock::*，crate::project:: 与 crate:: 既有路径不变 - windows_metadata_is_reparse_point 提为 pub(crate)，供 write_lock 复用同一条 reparse point 判据 - agent_db.rs 与 checkpoint.rs 的 PROJECT_FILE_FLAG_OPEN_REPARSE_POINT 导入路径改为 super::write_lock - 同步修正技术方案、Fast GDD 技术方案、decision-log、pitfalls 中指向锁实现的文件路径，并把“拆锁”从后续事项改为已完成
This commit is contained in:
@@ -16,6 +16,7 @@ mod resource_dependency_graph;
|
||||
mod resource_editor;
|
||||
mod resource_layout;
|
||||
mod verification;
|
||||
mod write_lock;
|
||||
|
||||
pub(crate) use agent_db::*;
|
||||
pub(crate) use asset_canvas::*;
|
||||
@@ -30,3 +31,4 @@ pub(crate) use resource_dependency_graph::*;
|
||||
pub(crate) use resource_editor::*;
|
||||
pub(crate) use resource_layout::*;
|
||||
pub(crate) use verification::*;
|
||||
pub(crate) use write_lock::*;
|
||||
|
||||
@@ -2,7 +2,7 @@ use super::*;
|
||||
use std::collections::BTreeSet;
|
||||
|
||||
#[cfg(windows)]
|
||||
use super::filesystem::PROJECT_FILE_FLAG_OPEN_REPARSE_POINT;
|
||||
use super::write_lock::PROJECT_FILE_FLAG_OPEN_REPARSE_POINT;
|
||||
|
||||
const AGENT_DB_MAX_RECORD_BYTES: usize = 1024 * 1024;
|
||||
const AGENT_DB_ACTION_RECEIPT_RECORD_TYPE: &str = "agent.runtime.action_receipt";
|
||||
|
||||
@@ -3,7 +3,7 @@ use super::*;
|
||||
use super::filesystem::validate_portable_project_path_component;
|
||||
|
||||
#[cfg(windows)]
|
||||
use super::filesystem::PROJECT_FILE_FLAG_OPEN_REPARSE_POINT;
|
||||
use super::write_lock::PROJECT_FILE_FLAG_OPEN_REPARSE_POINT;
|
||||
|
||||
#[cfg(windows)]
|
||||
fn windows_regular_file_handle_identity(file: &File, label: &str) -> Result<(u32, u64), String> {
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -27,7 +27,7 @@
|
||||
|
||||
- 背景：#211 要求 sidecar 满足当前用户独占、禁止继承的 DACL。新建文件会先继承父目录 ACE，生产路径把这种短暂不合格送进 UAC；`project.lock` 还在独占句柄上 harden。含空格项目路径上提权 ArgumentList 被拆开，修复以 exit 1 失败。GDD 审批改意见因此弹权限，V1 锁创建不会。
|
||||
- 决策：`harden_new_game_creator_private_path` 只在本进程收紧 owner/DACL，失败则删除刚创建的对象，不 UAC 接管。项目锁先写再释放句柄再 harden，并用内容回读防换绑；UAC 仍只用于允许范围内的已有外人本对象。提权 helper 的 ArgumentList 改为一条按 Windows 规则加引号的字符串。
|
||||
- 影响范围：`config.rs` 的新建 harden 与提权命令行、`filesystem.rs` 的项目锁创建；不改变锁竞争、失效回收、Drop 删除，也不放宽 symlink / reparse / 外人本 fail-closed。
|
||||
- 影响范围：`config.rs` 的新建 harden 与提权命令行、`project/write_lock.rs` 的项目锁创建；不改变锁竞争、失效回收、Drop 删除，也不放宽 symlink / reparse / 外人本 fail-closed。
|
||||
- 验证方式：Windows 定向测试覆盖 `Genarrative GameAgent\gameagent-*` 取锁与私有 DACL，以及带空格路径的 quoted ArgumentList。
|
||||
- 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/pitfalls.md`。
|
||||
|
||||
|
||||
@@ -5058,7 +5058,7 @@
|
||||
- 原因：fixture 用 `0xFFFF_FFF0` 当死 PID；Unix 的 `pid_t` 是有符号 32 位，`i32::try_from` 直接失败，存活判定返回 `None`（无法判定）而不是 `Some(false)`，于是落回 600 秒保守分支，残留锁不再被回收。
|
||||
- 处理：实现层把“平台不可能分配出的进程号”（0 或超出平台 pid 宽度）判为持有者不存在并直接回收；fixture 改用 `i32::MAX as u64 - 1`，另加 `u64::MAX` 非法进程号用例。
|
||||
- 验证：WSL Ubuntu 上 `cargo test --bin genarrative-ai-game-creator-shell project_lock_recovery` 7 条全过；Windows 上把可表示性判据临时回退到 HEAD 后，只有 `project_write_lock_reclaims_unrepresentable_owner_pid` 失败，说明该用例确实覆盖这条分支；Linux CI 的原始失败记录覆盖越界 PID 分支。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`、`apps/ai-game-creator-shell/src-tauri/src/tests/project_lock_recovery.rs`。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/write_lock.rs`、`apps/ai-game-creator-shell/src-tauri/src/tests/project_lock_recovery.rs`。
|
||||
|
||||
## 锁文件回收的判定与删除必须基于同一份快照（2026-09-09）
|
||||
|
||||
@@ -5066,7 +5066,7 @@
|
||||
- 原因：`project_write_lock_can_be_reclaimed` 只是快照观察，调用方拿到 true 后无条件 unlink；helper 还分别重读 `createdAt` / `pid` / `processStartedAt`，并发替换会拼出“旧 inode 的死 PID + 新 inode 的启动身份”。
|
||||
- 处理：payload 只解析一次并连同字节一起快照；删除前重新核对字节，只有内容仍是判定时的内容才 unlink；文件已消失或被替换时返回 false 并重试 `create_new`，不报错。
|
||||
- 补充：`project_write_lock_file_modified_seconds` 读不到 mtime 时不要返回 `0`——纪元 0 会被算成极大年龄，把保守判定反转成“立刻回收”，甚至把活持有者当 PID 复用抢走；要用 `Option` 区分“mtime 未知”和“mtime 等于纪元 0”。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`。
|
||||
- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/write_lock.rs`。
|
||||
|
||||
## 2026-09-10 Direct 写通道零等待取锁把毫秒级竞争放大成整轮阻断
|
||||
|
||||
@@ -5076,4 +5076,4 @@
|
||||
- **补充：重试性不能由一次 metadata 观察决定**。Windows 上 `create_new` 在目标被删除的拆链窗口里会返回 `ACCESS_DENIED(5)`，而此刻 `exists()` 往往已经报 false——本机 6 万次建锁 / 删锁竞争实测 396-538 例命中“5 + 目标不可见”。用 `path.exists()` 当场判成权限拒绝，等待层会立刻失败关闭，把同一个问题换成更误导的 ACL 文案。正确形状是：重试性只看错误码（`ACCESS_DENIED(5)` / sharing violation(32) / lock violation(33) / 已存在都可重试），终态改判放到等满预算之后——真的等过、目标此刻仍不存在，才改判成权限拒绝。分类判据把平台作为参数传入，Linux CI 才能覆盖 Windows 分支（CI 没有 Windows runner，`#[cfg(windows)]` 用例在 CI 里一次都不跑）。
|
||||
- **排查顺序**：① 先看失败耗时——几十毫秒说明该入口没等，是等待窗口缺失，不是锁没释放。② 看错误里的 `ownerIsSelf`：`true` 指向同进程另一条写通道，`false` 指向外部进程；该字段只比 PID，PID 复用会把外人报成自己人，只当线索、不当判据（回收判据另有 `processStartedAt` 兜底）。③ **锁文件在失败后通常已被 Drop 删掉，现场缺文件不否定争用**；同理 `agc_list_registered_assets` 的 `pendingOperations: []` 只表示没有在跑的付费生成，与项目写锁无关，不构成“锁没有持有者”的证据。④ `.agent/.manifest.json.lock` 是 manifest 的持久 OS 文件锁（Windows 不共享写句柄 / Unix `flock`），0 字节长期存在是设计如此，不是残留锁，也不要用项目写锁的回收判据去处理它。⑤ 看到“项目写锁路径权限被拒绝”时注意它的含义：这是**等满等待窗口后**的终态改判（Windows 上真实 ACL 拒绝就走这条路），不是某一瞬间的 metadata 观察；反过来，`项目正在被其他写操作占用：…（持锁方身份不可读：锁文件此刻不存在…）` 是零等待入口无法区分拆链窗口与 ACL 拒绝时的并列表述，两者不要互相否定。
|
||||
- **验证**：Rust 定向覆盖同进程重叠写等待、同轮并行写、活外部进程持锁带身份、权限拒绝不投影成争用，以及两条平台无关判据用例（重试性只由错误码决定、终态改判三条件）；`runtime_project_write_lock_waits_for_delete_pending_target` 继续覆盖带句柄的 delete-pending 必须等到成功。
|
||||
- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs`、`apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs`。
|
||||
- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs`、`apps/ai-game-creator-shell/src-tauri/src/project/write_lock.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs`。
|
||||
|
||||
@@ -1348,4 +1348,4 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过
|
||||
- 复用 2026-09-09 的回收机制，不新增第二套：`ProjectWriteLockSnapshot` 补 `commandId` 与 `describe_holder()`，争用错误、`project.write_lock.reclaim_stale`、`project.write_lock.wait_exhausted` 三处共用同一份身份描述。“活持有者始终不回收”的判据不变。
|
||||
- 等待预算耗尽时按 `project.write_lock.wait_exhausted` 记录 `commandId`、尝试次数、等待毫秒数、`projection=`（contention / permission_denied）与持锁方身份，Unix 上明确判定的权限拒绝按 `project.write_lock.permission_denied` 记录；争用不在零等待入口里逐次记账，避免有界等待的上千次重试淹没日志。这条日志正是 Issue #318 现场缺的“谁在持锁、是不是自己人”。
|
||||
- 定向验收覆盖：同进程重叠写等待后成功、同一轮并行写多个文件、活外部进程持锁（错误带 `ownerIsSelf=false` 且锁文件不被回收）、ACL 拒绝不投影成争用，外加两条平台无关判据用例（重试性只由错误码决定、终态改判三条件）——后两条让 Linux CI 也能盯住 Windows 分支。对应 `project_lock_recovery`、`direct_tool_bridge` 与 `project/filesystem` 定向测试；`tests/project_tools.rs` 既有的 `runtime_project_write_lock_waits_for_delete_pending_target` 继续覆盖“带句柄的 delete-pending 必须等到成功”。
|
||||
- 仍待收口（后续事项）：① 其余仍用零等待取锁的入口（`command.exec / project.verify / memory / conversation / task / checkpoint / 预览 / UI 编辑器 / 资源编辑器 / Tauri 命令`）本批不改，遇到同类争用仍会立刻失败；零等待入口无法区分“拆链窗口 / ACL 拒绝”，因此在前缀不变的前提下补一句“锁文件此刻不存在，可能是删除挂起、删除拆链窗口或权限 / ACL 拒绝”。② `project/filesystem.rs` 已经堆了回收、分类、诊断三套锁策略（1533 行），`direct_tool_bridge.rs` 也超过 3000 行，后续把锁策略拆到 `project/write_lock.rs`、Direct 锁用例移到 `tests/project_lock_recovery.rs`。③ 行为级 Windows 用例（delete-pending 等）仍只在 Windows 本地执行，CI 没有 Windows runner；关键判据已参数化到 Linux 可覆盖，行为级覆盖仍需本地执行或后续补 runner。
|
||||
- 仍待收口（后续事项）：① 其余仍用零等待取锁的入口（`command.exec / project.verify / memory / conversation / task / checkpoint / 预览 / UI 编辑器 / 资源编辑器 / Tauri 命令`）本批不改，遇到同类争用仍会立刻失败；零等待入口无法区分“拆链窗口 / ACL 拒绝”，因此在前缀不变的前提下补一句“锁文件此刻不存在，可能是删除挂起、删除拆链窗口或权限 / ACL 拒绝”。② 锁策略已按“单一职责”收口到 `project/write_lock.rs`（856 行：取锁、等待分类、持锁方诊断、残留回收），`project/filesystem.rs` 回到项目文件 IO（680 行）；仍待收口的是 Direct 锁用例，它们还留在 `direct_tool_bridge.rs`（3054 行，锁用例与 120 行桥实现混在一起），后续移到 `tests/project_lock_recovery.rs` 或独立测试文件。③ 行为级 Windows 用例（delete-pending 等）仍只在 Windows 本地执行，CI 没有 Windows runner；关键判据已参数化到 Linux 可覆盖，行为级覆盖仍需本地执行或后续补 runner。
|
||||
|
||||
@@ -1896,7 +1896,7 @@ M0 文档 PR 本身最低验证：Markdown 结构与三张 Mermaid 图可解析
|
||||
| 现役 pending wire | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver.rs:26-27`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_action_batch.rs:3-46,219-270`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/pending_confirmation_ledger.rs:290-520` | 保持 `game-creator-pending-action.v5`；M1 另建 planning pending，不升级全局 wire |
|
||||
| submit 专用提交/恢复分支 | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_recovery.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_action_batch.rs` | **2026-08-14 按 M1B-2 收口**：在普通 dispatch 前处理 Runtime-owned submit；提交后终止策划子 run，并保留 generic v5 standalone pending + v4 batch anchors，不复用 `WaitingForUserInput`，不创建 planning pending。审批等待属于 M1C-1 |
|
||||
| JSON sidecar | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/json_sidecar.rs:44-104,122-250` | 现有 writer 可覆盖；不可变文件必须新增 no-replace helper |
|
||||
| 项目锁 | `apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs:85-138`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs:1467-1505` | 所有 planning mutation 在同一项目锁内重读事实 |
|
||||
| 项目锁 | `apps/ai-game-creator-shell/src-tauri/src/project/write_lock.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs:1467-1505` | 所有 planning mutation 在同一项目锁内重读事实 |
|
||||
| completion blocker | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/planning_approval.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop.rs` | **M1C-1 隔离 worktree 已补齐**：仅对 exact `project-supervisor-plan` standard 顶层根 Run 生效，读取 GDD lineage、approval pending/receipt、generic submit anchors、terminal observation、decision audit、planning session 与 recovery，且只读不创建 pending；现役 collaboration blocker 对策划子 Agent 仍不适用 |
|
||||
| plan 根 run 子 Agent 创建面 | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/delegation.rs`（`observe_agent_runtime_agent_delegate` / `observe_agent_runtime_agent_spawn_isolated`）、`agent/runtime_protocol/run_configuration.rs`（`validate_project_supervisor_plan_root_binding_at`）、`agent/prompt.rs`（`game_creator_project_supervisor_tool_plan_prompt`） | **2026-08-14 `M1A-4` 已落地**：plan 根 run 只能委派 `project-planning`，`agent.spawn_isolated` 一律拒，两条通道共用 typed `kind=plan-root-child-target-unsupported`；plan source 下不拼 `supervisorIntro` 与 `$visualContract`。**已知残留（有意保留，见 decision-log 2026-08-14 `M1A-4` 条）**：`$base` 的 `$isolatedAgentTemplates` 段仍会向 plan 根 run 列出全部专业角色名——那是 `agent.spawn_isolated` 的模板目录，因执行层硬拒而成为死文本；因此**不得**写「plan 根 run 上下文不出现其它 Agent 名」这类验收句 |
|
||||
| plan retry | `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/lifecycle_control.rs`（`resolve_game_creator_agent_runtime_retry_configuration_at`）、`runtime_driver.rs`（`supervisor_plan_root_identity_holds_at`） | **2026-08-13 `M1A-3` 已落地 source 保源**：`task.source == project-supervisor-plan` 时先走强判据，通过则保留该 source，失败 `kind=plan-root-retry-identity-unsupported`、不降级。gui/cli 仍走 `agent-background-task`。plan-session revision / `gddId` / 按 `gdd-approval` kind 禁 retry 仍属后续包（现役已拒 `waiting-*`） |
|
||||
|
||||
Reference in New Issue
Block a user