v0.5.2 — scope 生产者落地 + P2 硬化 + 失败可逆

[0.5.2] - 2026-09-15

Fixed（P2 小裂缝批量清理，均有证据）

• shell=True 执行 test_command（注入面）：验证器用 shell 跑来自 LLM planner 的
  test_command，P19 明令禁止。改为：默认 pytest 调用以安全 argv 列表下发（同时在 Windows 上
  避开带空格的 sys.executable 被切碎的问题），自定义命令经 shlex.split(..., posix=True)
  转为 argv 且 shell=False → ;、&&、| 退化为字面参数而非被执行。
  注：曾用 posix=False 保 Windows 反斜杠，实测引号不被剥离导致
  python -c "…" 变成空转的字符串表达式、瞬时"通过"，改回 posix=True。
• 产物 id 复用导致重试覆盖：{task_id}_output 等固定 id 让同一任务的多次尝试只留最后一份，
  历史丢失。改为 {task_id}_{kind}_{token_hex(4)}——保留 {task_id}_ 前缀以兼容
  ArtifactStore.list_for_task，多次尝试各自成档。
• validated_at 恒为空：写入 ISO-8601 UTC 时间戳，P19 的 validation_duration 才可计算。
  （顺带：test_deterministic_validator_deterministic 的全量 dump 对比排除该时间戳。）
• 自测超时 120s 硬编码：改为 DeterministicValidator(self_test_timeout=...) 构造参数，默认仍 120s。
  并接上 --timeout 体系：ProjectService._build_executor 现在把解析后的 task_timeout
  注入验证器，即 --timeout / PROJECTFORGE_TASK_TIMEOUT_SECONDS 同时管住"任务内所有子进程"
  （含自测）。（注：经 service 走的自测预算随之由 120s 变为配置的 task_timeout，默认 300s。）

Added

• 检查点回滚（让"失败"真正可逆）：git checkpoint 原已建好基线/逐任务提交/validator GIT 判据，
  但失败后工作区仍躺着半成品，后续任务在污染的地基上继续。现在任务判 FAILED 时
  （执行异常 / 执行结果非 IMPLEMENTED / 验证 FAIL 三条路径）回到该任务开始前的 HEAD：
  git reset --hard <head_before> + git clean -fd -e artifacts（保留审计产物）。
  因属破坏性操作，默认关闭：ExecutionOrchestrator(rollback_on_failure=True) 或
  env PROJECTFORGE_ROLLBACK_ON_FAILURE=1|true|yes 显式启用。
• EventStore 去掉 O(n²)：append 原每次重读整个 jsonl 建 id 集（n 大时 O(n²)），
  改为惰性 id 缓存 + 增量更新。保留幂等去重，并补测"换实例重开仍能对既有事件去重"。
• 事件日志滚动：活跃文件超过 max_file_bytes 即切为 events-<时间戳>-<hex>.jsonl 分片，
  活跃文件重新起头；get_events 会读取全部分片，故滚动不会隐藏历史。
  同样默认关闭（会改变磁盘布局）：EventStore(max_file_bytes=...) 或
  env PROJECTFORGE_EVENT_MAX_FILE_BYTES。（日志按 run 分片未做，留待后续。）
• 主循环加全局时长预算：ExecutionOrchestrator(max_run_seconds=...)，主循环以
  time.monotonic() 卡预算，超限即以 TIME_BUDGET_EXCEEDED 收束（与用户 CANCELLED 区分）。
  默认 None 维持原不受限行为，属显式启用；配套 env PROJECTFORGE_MAX_RUN_SECONDS
  （resolve_max_run_seconds()，未设/非法值即不受限），无需改代码即可打开闸门。

Fixed（自查中揪出的回归）

• 事件 id 缓存跨项目串味：上一项把 id 集做成实例级单集，虽换掉了 O(n²)，
  却引入新 bug——同一实例先碰项目 A 再碰 B 时，B 不会加载自己的磁盘事件，
  导致 B 既有的 event_id 被重复写入。改为按项目键控 dict[project_id, set]。
  已补针对性测试，并做 RED 校验（还原旧行为时该测试确实失败，报错为 2 == 1）。

核实后未改动的项

• ArtifactStore.list_for_task 的"T1 匹配 T10_x"实测不重现：现有实现用
  startswith(f"{task_id}_") 的 _ 边界，T10_output 对 T1_ 为假。
  不改生产代码，补一条 T1/T10 回归测试锁定该边界行为。

ProjectForge v0.5.0

任务级路径约束（可选启用）+ 分阶段上线。

Added

• Task.allowed_paths：任务可声明允许修改的路径；声明后按声明校验，并自动放行跨切文件（依赖清单、构建配置、文档、任意层级的 __init__.py）
• PROJECTFORGE_SCOPE_MODE：默认 warn 只记录不判死，enforce 才判 SCOPE_VIOLATION

Changed

• scope 判定抽到 app/agents/scope_policy.py，消除 validator 与 cli_adapter 的重复实现

Fixed

• 声明路径校验漏掉 Windows 无盘符根路径（/abs/path 的 is_absolute() 为 False），可解析到工作区之外；改用 anchor 判定

Documentation

• README / docs/demo.md 的 scope 表述改为准确描述（原先宣称的越界拦截在生产路径从不触发）

验证

• 本地：416 passed, 19 skipped
• VM：433 passed（新增 21 项全过）；2 项 Hermes 真实推理用例因缺 LLM 凭据失败，与前版基线一致（既存环境问题）

ProjectForge v0.4.2

修复 LLM planner 链路与审计产物隔离。

Fixed

• --planner llm 完全不可用（UnboundLocalError）：规则版 planner 的 import 被误关在 rule 分支内，命令直接崩溃
• LlmPlanner 缺省 client 缺失导致 AttributeError 逃出降级捕获，破坏"永不抛错"契约
• LLM 调用沿用 httpx 默认 5 秒超时，真实往返必然超时并静默降级；改为显式 300 秒
• 审计产物被卷入逐任务 git checkpoint，污染 diff；产物改存 runs/<run_id>/artifacts 且提交显式排除 artifacts

Added

• tests/test_planner_factory.py：工厂四条路径 + 降级契约
• tests/test_artifact_isolation.py：产物位置与 checkpoint 隔离

验证

• 本地：395 passed, 19 skipped
• VM：412 passed（新增 11 项全过）；2 项 Hermes 真实推理用例因缺 LLM 凭据失败，已用 v0.4.1 基线对照确认为既存环境问题

ProjectForge v0.4.1

修复执行工作区的 Git 隔离问题。

• 防止嵌套工作区误用外层宿主仓库
• 新增 workspace git ownership 双层守卫
• 增加 6 个回归测试
• 本地测试：384 passed, 19 skipped
• VM 验证：397 passed, 0 skipped（真实 Hermes + bwrap）

ProjectForge v0.4.0

v0.4.0 主题：面试叙事——把 v0.1.0 以来积累的项目资产变成面试官面前说得出口、拿得出证据的东西。

主要变化

projectforge interview <project_id>（主菜）

• 一条命令生成面试前突击复习文档，五小节：
  • ① 项目速览（30 秒版）
  • ② 3 分钟架构讲法（含工程亮点、设计决策、权衡）
  • ③ 逐任务深挖卡（目标/验收标准/技术点/面试表达点/可能被问）
  • ④ 执行证据（每任务的 git 提交区间、变更文件、验证状态——「项目是真的」有据可查）
  • ⑤ 红线（claims_to_avoid / credibility_risks 原样保留，永不润色）
• 生成机制：LLM 加工（PROJECTFORGE_LLM_*）+ 模板兜底，命令永不失败；--no-llm 强制离线

计划审批关卡

• plan new 停在 PLANNING（展示任务图供人工审），plan approve 后才解锁执行
• 与 replan 的人工审批哲学对齐：LLM 生成的计划不再无人把关直奔沙箱

其他

• CHANGELOG.md 建立（Keep a Changelog）
• --out 支持嵌套目录自动创建
• ADD_DEPENDENCY 死代码分支清理（Replanner 从无此生产者）

验证证据

层	结果
GitHub Actions CI（3.10/3.11/3.12）	通过
本地全量多轮	378 passed / 19 skipped，零 flake
真实执行环境（Hermes + bwrap sandbox）	397 passed / 0 skipped

升级注意

• BREAKING：plan new 停在 PLANNING，需 plan approve 才能执行（原一步到 READY 拆为两步，与人工审批哲学对齐）
• PyPI：发本 Release 时经 trusted publishing 自动发布 jdforge 0.4.0

ProjectForge v0.3.0

v0.3.0 主题：「约束可审计」——规划接入 LLM、执行全程可审计、超时可调。

主要变化

LLM Planner：一条命令从 JD 到任务图

• projectforge plan <jd_file> --planner llm：LLM 按 JD 生成项目蓝图与 6–12 个带依赖、验收标准的任务，输出经 pydantic schema 与任务图（环检测/拓扑）双重校验
• 任何 OpenAI 兼容厂商均可（StepFun / DeepSeek / OpenRouter / 本地 ollama），三个环境变量配置
• 坏输出重试一次后自动回退离线规则版，plan 命令永不失败
• 规则版保留为离线默认（--planner rule），无需任何 key

git checkpoint：执行全程可审计

• 执行器 workspace 自动 git 基线化（非仓库时 init + baseline commit）
• 每个任务成功后自动提交——每个任务一个独立可回滚的 commit，checkpoint 为逐任务精确 diff
• validator 新增 GIT 判据：自报改动与 git 实况矛盾 = 硬 FAIL；无 git 环境仅警告不阻塞

超时参数化

• run start/resume --timeout 与 PROJECTFORGE_TASK_TIMEOUT_SECONDS，默认 300 秒，终结隐藏的 900s×3 最坏 45 分钟

验证证据

层	结果
GitHub Actions CI（3.10/3.11/3.12）	通过
本地全量多轮	360 passed / 19 skipped，零 flake
真实执行环境（Hermes + bwrap sandbox）	379 passed / 0 skipped
干净 venv wheel 冒烟	安装 → plan → run → COMPLETED

离线体验：python scripts/demo.py 或 projectforge plan ./jd.txt --planner rule，见 docs/demo.md。

升级注意

• v0.3.0 声明了完整运行时依赖（含此前缺失的 httpx 与 pytest），pip install projectforge 即装即用
• 沙箱与宿主共享网络（真隔离需 slirp4netns，未实现）

ProjectForge v0.2.0

v0.2.0 把"约束式执行"从口号变成现实：executor 可插拔、cancel 真正生效、确定性验证真实执行、base-dir 单一贯通。

主要变化

executor 可插拔（MS1）

• CodingAgentAdapter 泛化为 CliAgentAdapter 模板基类（重试/超时映射/git checkpoint/scope 判定可复用），sandbox 变为可注入的 SandboxPolicy
• ProjectService(executor_factory=...)；CLI/API 新增 --executor {hermes,mock}
• 新增离线 MockExecutor：真实走 orchestrator + validator，无需 Hermes/bwrap/网络即可跑通全链路（demo 与 CI 的关键解锁）

base-dir 单一贯通（MS2，⚠️ BREAKING）

• --base-dir 现在是唯一运行时根：projects/、runs/、workspaces/ 三分；workspace 独立为 --run-dir（默认 <base>/workspaces/<project>）
• 修复 replan/resume 路径忽略 --base-dir 的缺陷；v0.1.x 自定义布局不自动迁移，默认 .runtime 布局不变

cancel 真正生效（MS3）

• 持久化 cancel_requested（跨覆盖粘滞），orchestrator 在任务间检查取消并置 BLOCKED/CANCELLED
• run 执行移出全局锁；run 身份统一（orchestrator 复用 run_control 的 run_id）；终态不再被覆盖

确定性验证真实执行 + 验收标准语义修复（MS4）

• 任务可声明 test_paths/test_command，validator 真实执行声明的测试命令
• 声明的测试套件通过时，人工验收标准降级为 manual_review_items，任务可达 DONE；无 test_scope 保持保守 BLOCKED；套件失败 = 硬 FAIL
• scope 检查支持 workspace 相对路径与绝对 allowed_paths 的解析比对
• 此前生产路径的任务因验收标准恒 NEEDS_REVIEW 永远无法完成——已修复

验证证据

层	结果
GitHub Actions CI（3.10/3.11/3.12）	通过
本地全量多轮	325 passed / 19 skipped，零 flake
真实执行环境（Hermes + bwrap sandbox，19 个真实 LLM 用例）	344 passed / 0 skipped

离线一键体验：python scripts/demo.py（生命周期 → 执行 → 注入失败 → 人工审批 replan → resume → COMPLETED），见 docs/demo.md。

PyPI

元数据已就绪（sdist + wheel 构建通过）。发布由 tag/release 触发的 workflow 完成，需要在仓库 Secrets 配置 PYPI_API_KEY。

已知限制

• 沙箱与宿主共享网络（真隔离需 slirp4netns）
• git checkpoint 在非 git workspace 下为空，validator 尚未消费 checkpoint
• hermes 执行超时最坏 900s × 3 次

ProjectForge v0.1.2

纯 bugfix 版本：三个控制面修复，无行为变更、无布局变更、无新依赖。

修复

replan 支持执行期失败
Agent 崩溃或超时产生的 run 记录没有 execution/validation 结果，此前 create_proposal 强制要求两者存在，恰好拒绝了最需要重新规划的 run。现在缺失的结果以 None 透传，FailureAnalyzer 将无结果的记录归类为 agent failure 并套用标准重试预算（2 次）。

run 持久化保留 replan 控制字段
PersistedExecution 此前丢弃 replan_count 与 active_proposal_id，run 落盘再加载后 replan 状态静默丢失。

事件 id 碰撞导致丢事件
event_id 由墙钟微秒生成，在时钟粒度较粗的系统（如 Windows）上同一微秒内的两个事件 id 相同，被 append 去重逻辑静默吞掉。id 生成收敛到共享函数并加随机后缀；事件日志排序改为仅按时间戳稳定排序，同时刻保持追加顺序。

验证

• GitHub Actions CI（Python 3.10 / 3.11 / 3.12）：通过
• 本地全量套件连跑 8 轮：309 passed / 19 skipped，稳定无 flake
• 真实执行环境（Hermes + bwrap sandbox）：328 passed / 0 skipped，含 19 个真实 LLM 沙箱执行用例

v0.2.0（executor 可插拔、离线 mock 后端、cancel 生效、确定性验证接通）已在准备中。

ProjectForge v0.1.1

维护版本：打包依赖闭包、测试套件迁移、sandbox 网络修复。v0.1.0 行为契约不变。

主要内容

移除遗留线

• 删除 video pipeline（providers / render / pipeline）、12 个未使用 agent 与死代码 schema，约 -4000 行

执行链路修复

• run_control 执行桥正确传入 ProjectMap（此前字段名错误会被 pydantic 静默吞掉）
• orchestrator 支持注入 validator 并透传 workspace
• Hermes sandbox 不再使用 --unshare-all（会掐断 LLM API 连接）：保留宿主网络命名空间，bind 进 /etc/resolv.conf、hermes CLI 与配置目录，已用真实 Hermes 运行端到端验证

测试套件

• 全量迁移到当前执行/路由契约；本地 302 passed / 19 skipped
• 真实 Hermes 用例统一 requires_hermes 门控；在具备 hermes + bwrap 的主机上全部真实执行（验证环境 321 passed, 0 skipped）
• GitHub Actions CI（Python 3.10 / 3.11 / 3.12）绿灯

文档与打包

• pyproject.toml 补齐运行时依赖，pip install -e . 后即可使用 projectforge 命令
• README 新增安装、快速开始与 Hermes/bwrap 前置要求章节

已知问题（v0.1.2+ 候选）

• 纯执行层失败（agent 崩溃 / 超时，无 validation 结果）目前无法进入 replan 流程
• API/CLI replan 的 artifact store 使用 CWD 相对路径，--base-dir 不传导
• run 执行期间持有全局锁，cancel 仅设置标记、实际不中断执行
• sandbox 隔离文件系统与 pid/ipc，但共享宿主网络（真正网络隔离需 slirp4netns）
• 执行超时最坏情况 900s × 3 次重试

运行真实执行的环境要求

Hermes CLI（已认证）+ bubblewrap；Ubuntu 24.04+ 需为 bwrap 配置允许 unprivileged user namespace 的 AppArmor profile（详见 README）。

ProjectForge v0.1.0

ProjectForge v0.1.0

这是 ProjectForge 的首个公开版本。

ProjectForge 是一个基于岗位 JD 的工程项目教练与约束式执行引擎，
将 JD 转化为能力画像、项目蓝图、任务依赖图，并通过受约束的执行、
验证与重新规划推进项目落地。

本版本包含

• Product Core 工作流
• JD 分析与 Project Matching
• Project Blueprint 与 Task Graph
• 基于 Hermes 的真实任务执行
• Validation 与 Replan
• CLI / API
• Workspace Isolation 与 fail-closed sandbox
• MIT License
• GitHub Actions CI
• CONTRIBUTING / SECURITY
• Python packaging（pyproject.toml）

已知限制

• bwrap Runtime E2E 尚未完成，当前环境缺少 bubblewrap
• 测试套件存在部分近期生产语义变更导致的 baseline drift
• CI 已配置并能够执行，但当前 pytest baseline 尚未完全通过

项目状态

这是一个早期公开版本（v0.1.0），重点用于展示和验证核心架构与执行模型。