From 534113e3454d7900110ba82d86a203787c75c39a Mon Sep 17 00:00:00 2001 From: wei <104672881+shengzhaowei@users.noreply.github.com> Date: Sat, 21 Nov 2026 13:53:04 +0800 Subject: [PATCH] docs(local): document Pi front-blocking and retry boundaries --- local/skills/devflow/adapters/pi/adapter.md | 8 ++++++++ local/skills/devflow/tests/test_regressions.py | 16 ++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/local/skills/devflow/adapters/pi/adapter.md b/local/skills/devflow/adapters/pi/adapter.md index 47f31b5d8..7047a29fb 100644 --- a/local/skills/devflow/adapters/pi/adapter.md +++ b/local/skills/devflow/adapters/pi/adapter.md @@ -40,3 +40,11 @@ pi install npm:pi-subagents 不同阶段使用不同的 `Mission` UUID。由于前台模式不支持 `send`,同阶段重试必须重新派发新实例并重新登记, 不得在状态里复用已结束的 id。 + +## 前台阻塞与重试边界 + +1. 前台阻塞期间协调者无法中途 steering:前台调用在返回前一直阻塞,协调者不能在子会话 + 进行中追加指令、改提示或中途叫停;只能等返回后校验产物,再按需重新派发新实例。 +2. `runLoop` 是两层 while 循环,没有写死步数上限,不得把步数上限当作安全网;阶段提示必须先收敛—— + 目标、产物和验收标准一次写清,长上下文先摘要再派发,不得把未收敛的长提示直接交给子会话。 +3. 重试见上文能力映射第 5 条:重新派发新实例并重新登记,不得复用已结束的 Mission id。 diff --git a/local/skills/devflow/tests/test_regressions.py b/local/skills/devflow/tests/test_regressions.py index 7794cc143..e301493c5 100644 --- a/local/skills/devflow/tests/test_regressions.py +++ b/local/skills/devflow/tests/test_regressions.py @@ -368,6 +368,22 @@ def test_codebuddy_adapter_requires_team_member_dispatch(self): self.assertIn("cleanup_team.py", adapter) self.assertIn("不得读取 Team 配置、成员、inbox 或状态", adapter) + def test_pi_adapter_documents_front_blocking_and_retry_boundaries(self): + manifest = json.loads( + (SKILL_ROOT / "adapters/pi/manifest.json").read_text(encoding="utf-8") + ) + adapter = (SKILL_ROOT / "adapters/pi/adapter.md").read_text(encoding="utf-8") + self.assertEqual("spawn", manifest["topology"]) + self.assertEqual("subagent", manifest["dispatch_tool"]) + self.assertIn("前台阻塞与重试边界", adapter) + self.assertIn("前台阻塞期间协调者无法中途 steering", adapter) + self.assertIn("只能等返回后校验产物,再按需重新派发新实例", adapter) + self.assertIn("`runLoop` 是两层 while 循环,没有写死步数上限", adapter) + self.assertIn("不得把步数上限当作安全网", adapter) + self.assertIn("阶段提示必须先收敛", adapter) + self.assertIn("长上下文先摘要再派发", adapter) + self.assertIn("不得复用已结束的 Mission id", adapter) + def fill_stage_artifacts(self, state_path, stage): state = json.loads(state_path.read_text(encoding="utf-8")) artifact_root = Path(state["artifacts_dir"])