Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

feat(portable): add Pi host support (adapter + Portable installer CLI) (#24)

Chen Zhongaf44e5d12384
diff --git a/EDITIONS.md b/EDITIONS.md
index e1ae6e57..9202cbb2 100644
--- a/EDITIONS.md
+++ b/EDITIONS.md
@@ -6,7 +6,7 @@ DevFlow 有两套独立维护的实现。为避免同一宿主同时加载两套
| Edition | 仓库事实源 | 入口 | 维护方式 |
| --- | --- | --- | --- |
-| Portable | `skills/` | CodeBuddy/Cursor/Claude 使用 `/devflow`,Codex 使用 `$devflow` | 修改 canonical Skill 和 adapter manifest |
+| Portable | `skills/` | CodeBuddy/Cursor/Claude 使用 `/devflow`,Codex 使用 `$devflow`,Pi 使用 `/skill:devflow` | 修改 canonical Skill 和 adapter manifest |
| Classic(默认) | `.codebuddy/`、`.codex/`、`.cursor/`、`.claude/` | CodeBuddy/Cursor/Claude 使用 `/start-devflow`,Codex 使用 `$devflow-codex` | 以 `.codebuddy` 为参考行为;Cursor/Claude 由生成器产生 |
保留这些顶层目录是有意为之:`.xxx/` 是各宿主的原生项目目录,`skills/` 是
@@ -24,3 +24,6 @@ loopforge skills install claude
`plan` 只读取安装资产,不修改目标项目。实际安装后,edition 和每个托管文件的
摘要记录在项目的 `.devflow/install-state.json` 中。
+
+Portable 的 Pi 适配是声明型的:`skills install pi` 只安装 `.pi/skills/`,isolated
+(medium/large)模式还需要公开扩展 `pi install npm:pi-subagents` 提供 `subagent` 工具。
diff --git a/README.md b/README.md
index 7e77971d..2b3531be 100644
--- a/README.md
+++ b/README.md
@@ -179,6 +179,19 @@ Then start a workflow:
/devflow "add status filtering to the order list and cover the API with tests"
```
+### Pi
+
+```bash
+npx -y loopforge-cli@latest skills install pi
+pi install npm:pi-subagents
+```
+
+Then start a workflow:
+
+```text
+/skill:devflow "add status filtering to the order list and cover the API with tests"
+```
+
See [`EDITIONS.md`](EDITIONS.md) for the complete boundaries and directory layout.
## Update and uninstall
@@ -235,6 +248,11 @@ loopforge skills uninstall cursor
loopforge skills update claude
loopforge skills status claude
loopforge skills uninstall claude
+
+# Pi
+loopforge skills update pi
+loopforge skills status pi
+loopforge skills uninstall pi
```
Installation state is stored in `.devflow/install-state.json`. An update stops instead of overwriting user-modified or conflicting files. Use `--force` only when you intend to replace conflicts or switch editions, preferably after inspecting `loopforge plan`.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 5a6f79b5..ab175c6f 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -178,6 +178,19 @@ npx -y loopforge-cli@latest skills install claude
/devflow "为订单列表增加状态筛选,并补充接口测试"
```
+### Pi
+
+```bash
+npx -y loopforge-cli@latest skills install pi
+pi install npm:pi-subagents
+```
+
+安装后使用:
+
+```text
+/skill:devflow "为订单列表增加状态筛选,并补充接口测试"
+```
+
完整边界和目录说明见 [`EDITIONS.md`](EDITIONS.md)。
## 更新与卸载
@@ -234,6 +247,11 @@ loopforge skills uninstall cursor
loopforge skills update claude
loopforge skills status claude
loopforge skills uninstall claude
+
+# Pi
+loopforge skills update pi
+loopforge skills status pi
+loopforge skills uninstall pi
```
安装状态保存在 `.devflow/install-state.json`。检测到用户修改或文件冲突时,更新会停止而不是覆盖。只有在确认要替换冲突文件或切换 Edition 时才使用 `--force`,建议先运行 `loopforge plan` 检查变更。
diff --git a/docs/architecture.md b/docs/architecture.md
index e985ee7d..b9511f97 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -11,7 +11,8 @@
## Portable Edition
`skills/` 提供独立的新 DevFlow 状态机、模板、规则、测试和 adapter,
-支持 CodeBuddy、Codex、Cursor 与 Claude Code。脚本只依赖 Python 3.8+
+支持 CodeBuddy、Codex、Cursor、Claude Code 与 Pi(Pi 只有声明型 adapter,
+isolated 模式依赖公开扩展 `npm:pi-subagents`)。脚本只依赖 Python 3.8+
标准库;具体 Agent 调度能力由宿主提供。
`skills/manifest.json` 是跨宿主 Skill 集合清单。`skills/` 是这一层的唯一
diff --git a/docs/compatibility.md b/docs/compatibility.md
index 6112b208..dd53a906 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -8,6 +8,7 @@
| Codex | `.codex/` + `.agents/skills` | `.agents/skills/devflow` |
| Cursor | `.cursor/` 完整包 | `.cursor/skills` + 两个执行器 |
| Claude Code | `.claude/` 完整包 | `.claude/skills` + 两个执行器 |
+| Pi | 无(Portable only) | `.pi/skills` + `subagent` adapter(需 `npm:pi-subagents`) |
Classic 的 Cursor/Claude 目录是生成产物;Portable 的事实只保存在 `skills/`。
两者只共享显式行为合同和测试,不共享宿主运行文件。
@@ -16,7 +17,7 @@ Classic 的 Cursor/Claude 目录是生成产物;Portable 的事实只保存在
1. **结构门禁**:校验 JSON/YAML、Skill frontmatter、manifest 引用和链接。
2. **漂移门禁**:`build-classic-hosts.py --check` 逐字比较 Classic 生成包。
-3. **安装门禁**:统一 CLI 覆盖 4 宿主 × 2 edition,并验证重复安装、更新、卸载、
+3. **安装门禁**:统一 CLI 覆盖 5 宿主 × 2 edition(pi 仅 Portable),并验证重复安装、更新、卸载、
mixed-edition 拒绝和用户文件保护。
4. **流程回归**:标准库单测和 CLI E2E 验证状态机、门禁、产物与恢复协议。
5. **真实宿主 canary**:发布前或宿主大版本升级后,在隔离 fixture 仓库用真实
diff --git a/scripts/smoke-install.sh b/scripts/smoke-install.sh
index 5b180368..46eec94a 100755
--- a/scripts/smoke-install.sh
+++ b/scripts/smoke-install.sh
@@ -68,6 +68,12 @@ DOWNSTREAM_PROJECT="$TMP_DIR/downstream-project"
mkdir -p "$CODEBUDDY_PROJECT" "$DOWNSTREAM_PROJECT"
"$VENV_DIR/bin/loopforge" skills install codebuddy --project-root "$CODEBUDDY_PROJECT"
test -f "$CODEBUDDY_PROJECT/.codebuddy/skills/manifest.json"
+
+PI_PROJECT="$TMP_DIR/pi-project"
+mkdir -p "$PI_PROJECT"
+"$VENV_DIR/bin/loopforge" skills install pi --project-root "$PI_PROJECT"
+test -f "$PI_PROJECT/.pi/skills/manifest.json"
+test -f "$PI_PROJECT/.pi/skills/devflow/SKILL.md"
"$VENV_DIR/bin/python" \
"$CODEBUDDY_PROJECT/.codebuddy/skills/devflow/scripts/install_adapter.py" \
--adapter claude --project-root "$DOWNSTREAM_PROJECT" --copy-skills --refresh-managed
diff --git a/scripts/validate.sh b/scripts/validate.sh
index 9c28a1bb..ff77b487 100755
--- a/scripts/validate.sh
+++ b/scripts/validate.sh
@@ -129,12 +129,13 @@ if set(portable) != set(discovered):
if DEFAULT_EDITION != "classic" or tuple(EDITION_SPECS) != ("portable", "classic"):
raise SystemExit("Edition registry must keep Classic as the explicit default")
for edition, metadata in EDITION_SPECS.items():
- if set(metadata.get("entrypoints", {})) != set(HOSTS):
+ hosts = metadata.get("hosts", HOSTS)
+ if set(metadata.get("entrypoints", {})) != set(hosts):
raise SystemExit(f"Edition entrypoint drift: {edition}")
for source in metadata.get("source_roots", ()):
if not (root / source).is_dir():
raise SystemExit(f"Edition source does not exist: {edition}: {source}")
- for host in HOSTS:
+ for host in hosts:
source = source_for(edition, host)
if not (root / source).is_dir():
raise SystemExit(f"Edition host source does not exist: {edition}/{host}: {source}")
diff --git a/skills/devflow/adapters/pi/adapter.md b/skills/devflow/adapters/pi/adapter.md
new file mode 100644
index 00000000..47f31b5d
--- /dev/null
+++ b/skills/devflow/adapters/pi/adapter.md
@@ -0,0 +1,42 @@
+# Pi 适配器
+
+pi 构建在 Agent Skills 之上,通过 `npm:pi-subagents` 扩展提供 `subagent` 工具。使用前先安装:
+
+```bash
+pi install npm:pi-subagents
+```
+
+没有该工具时不存在可用的生命周期 API,只能按 [runtime-core.md](../../references/runtime-core.md)
+降级为 `single-context`,不得把降级状态标成 `isolated`。
+
+## 能力映射
+
+`subagent` 前台调用(`async: false`)会启动一个独立子会话并在返回前阻塞,属于 `spawn` 拓扑:
+
+1. `spawn(role, prompt) -> executor_id`:调用
+ `subagent { agent: "delegate", task: "<完整阶段提示>" }`,返回内容中的
+ `Mission: <uuid> (completed)` 就是宿主签发的 `executor_id`。
+2. `wait(executor_id)`:前台调用本身就是阻塞的,返回即子会话完成。
+3. `close(executor_id)`:前台模式无需显式关闭;异步模式下用 pi-subagents 的 fleet/stop 能力。
+4. `spawn_helper(role, bounded_prompt) -> executor_id`:调用只读内置 agent,例如
+ `subagent { agent: "scout", task: "<有边界的检索提示>" }`,并把返回的 `Mission` UUID 作为 helper id。
+5. `send(executor_id, message)`:前台模式不支持对已结束子会话追加消息。需要补充或重试时,
+ 重新 `subagent` 一个全新实例并重新 `assign`,不得复用已结束的 Mission id。
+
+## 使用步骤
+
+1. 确认已安装 `pi-subagents`,且当前会话能看到 `subagent` 工具;缺失时停止并报告,
+ 不得自创替代工具。
+2. medium/large 使用 `--execution-mode isolated --host-adapter pi` 初始化。
+3. REQUIREMENT 执行 `prepare --emit-prompt → start`,由主 Agent 调用 `devflow-clarify-requirements`
+ 并填写需求报告,再 `finish`;不得创建需求分析 subagent。
+4. route 中其他 Agent 阶段先用 `prepare --emit-prompt` 一次生成完整提示,再调用
+ `subagent { agent: "delegate", task: "<提示>" }` 创建全新子会话,从返回的 `Mission: <uuid>`
+ 取出 `executor_id`,用 `assign --executor-type dynamic --dispatch-tool subagent` 登记,再 `start`,
+ 等待返回后校验产物并 `finish`。协调者不得代写 isolated 阶段产物。
+5. 只读检索使用 `subagent { agent: "scout", task: "<有边界提示>" }`,并以 `devflow-code-explorer` 或
+ `devflow-knowledge-retriever` 作为审计角色用 `helper --executor-type dynamic --dispatch-tool subagent`
+ 登记。REVIEW 前不得使用 `devflow-code-reviewer`。
+
+不同阶段使用不同的 `Mission` UUID。由于前台模式不支持 `send`,同阶段重试必须重新派发新实例并重新登记,
+不得在状态里复用已结束的 id。
diff --git a/skills/devflow/adapters/pi/manifest.json b/skills/devflow/adapters/pi/manifest.json
new file mode 100644
index 00000000..037741bd
--- /dev/null
+++ b/skills/devflow/adapters/pi/manifest.json
@@ -0,0 +1,13 @@
+{
+ "version": "1.0",
+ "id": "pi",
+ "compatibility": {
+ "verified_on": "2026-09-17",
+ "documentation": "https://github.com/nicobailon/pi-subagents"
+ },
+ "dispatch_tool": "subagent",
+ "topology": "spawn",
+ "stage_executor": "dynamic",
+ "research_executor": "dynamic",
+ "required_tools": ["subagent"]
+}
diff --git a/src/devflow_cli/cli.py b/src/devflow_cli/cli.py
index 24fc3d21..574d967d 100644
--- a/src/devflow_cli/cli.py
+++ b/src/devflow_cli/cli.py
@@ -5,7 +5,7 @@ import sys
from pathlib import Path
from . import __version__
-from .core import DevFlowError, apply_install, build_plan, doctor, status_rows, uninstall
+from .core import DevFlowError, apply_install, build_plan, doctor, status_rows, uninstall, validate_choice
from .editions import DEFAULT_EDITION, EDITIONS, HOSTS, entrypoint_for, host_label, source_for, spec
from .targets import load
@@ -107,6 +107,7 @@ def main(argv=None) -> int:
))
return 0
if args.command == "plan":
+ validate_choice(args.host, args.edition)
files = sorted(build_plan(args.host, args.edition))
row = {
"edition": args.edition,
@@ -143,6 +144,8 @@ def main(argv=None) -> int:
f"Next: reopen {host_label(args.host)} and run "
f"{entrypoint_for(args.edition, args.host)} <你的需求>"
)
+ if args.host == "pi" and args.edition == "portable":
+ print("Note: Pi isolated mode also needs the public extension: pi install npm:pi-subagents")
return 0
if args.command == "skills":
if args.skills_command in {"install", "update"}:
@@ -163,6 +166,8 @@ def main(argv=None) -> int:
f"Next: reopen {host_label(args.host)} and run "
f"{entrypoint_for('portable', args.host)} <你的需求>"
)
+ if args.host == "pi":
+ print("Note: Pi isolated mode also needs the public extension: pi install npm:pi-subagents")
return 0
if args.skills_command == "status":
rows = [
diff --git a/src/devflow_cli/core.py b/src/devflow_cli/core.py
index b04a8ac0..d40097b7 100644
--- a/src/devflow_cli/core.py
+++ b/src/devflow_cli/core.py
@@ -10,7 +10,7 @@ from pathlib import Path
from typing import Dict, List, Optional, Tuple
from . import __version__
-from .editions import EDITIONS, HOSTS, source_for
+from .editions import EDITIONS, HOSTS, hosts_for, source_for
STATE_VERSION = 1
@@ -134,6 +134,14 @@ def materialize_portable(host: str, stage: Path) -> None:
for name in manifest["skill_sets"]["portable"]:
copy_skill(skills_root / name, target / name)
return
+ if host == "pi":
+ target = stage / ".pi/skills"
+ target.mkdir(parents=True, exist_ok=True)
+ manifest = json.loads((skills_root / "manifest.json").read_text(encoding="utf-8"))
+ copy_skills_manifest(skills_root, target)
+ for name in manifest["skill_sets"]["portable"]:
+ copy_skill(skills_root / name, target / name)
+ return
raise DevFlowError(f"不支持的宿主: {host}")
@@ -173,6 +181,14 @@ def validate_choice(host: str, edition: str) -> None:
raise DevFlowError(f"未知宿主 {host};可选: {', '.join(HOSTS)}")
if edition not in EDITIONS:
raise DevFlowError(f"未知 edition {edition};可选: {', '.join(EDITIONS)}")
+ if host not in hosts_for(edition):
+ available = [item for item in EDITIONS if host in hosts_for(item)]
+ hint = (
+ f";Pi 只有 Portable,请运行: loopforge skills install {host}"
+ if host == "pi" and "portable" in available
+ else f";{host} 可用 edition: {', '.join(available)}"
+ )
+ raise DevFlowError(f"{edition} edition 不支持宿主 {host}{hint}")
def path_present(path: Path) -> bool:
diff --git a/src/devflow_cli/editions.py b/src/devflow_cli/editions.py
index a22b805b..bcc3ead8 100644
--- a/src/devflow_cli/editions.py
+++ b/src/devflow_cli/editions.py
@@ -4,28 +4,32 @@ from typing import Dict, Tuple
DEFAULT_EDITION = "classic"
-HOSTS: Tuple[str, ...] = ("codebuddy", "codex", "cursor", "claude")
+HOSTS: Tuple[str, ...] = ("codebuddy", "codex", "cursor", "claude", "pi")
HOST_LABELS = {
"codebuddy": "CodeBuddy",
"codex": "Codex",
"cursor": "Cursor",
"claude": "Claude Code",
+ "pi": "Pi",
}
EDITION_SPECS: Dict[str, dict] = {
"portable": {
"description": "Agent Skills based portable workflow",
"source_roots": ("skills/",),
+ "hosts": ("codebuddy", "codex", "cursor", "claude", "pi"),
"entrypoints": {
"codebuddy": "/devflow",
"codex": "$devflow",
"cursor": "/devflow",
"claude": "/devflow",
+ "pi": "/skill:devflow",
},
},
"classic": {
"description": "Full host-native workflow derived from .codebuddy behavior",
"source_roots": (".codebuddy/", ".codex/", ".cursor/", ".claude/"),
+ "hosts": ("codebuddy", "codex", "cursor", "claude"),
"entrypoints": {
"codebuddy": "/start-devflow",
"codex": "$devflow-codex",
@@ -42,6 +46,15 @@ def spec(edition: str) -> dict:
return EDITION_SPECS[edition]
+def hosts_for(edition: str) -> Tuple[str, ...]:
+ """返回某个 edition 支持的宿主集合。
+
+ Classic 只覆盖有完整宿主原生包的宿主;Portable 覆盖所有支持 Agent Skills
+ 的宿主,包括只有声明型 adapter 的 pi。
+ """
+ return tuple(spec(edition).get("hosts", HOSTS))
+
+
def source_for(edition: str, host: str) -> str:
if edition == "classic":
return f".{host}/"
diff --git a/src/devflow_cli/targets/pi.py b/src/devflow_cli/targets/pi.py
new file mode 100644
index 00000000..08aa628c
--- /dev/null
+++ b/src/devflow_cli/targets/pi.py
@@ -0,0 +1,10 @@
+HOST = "pi"
+
+
+def describe() -> str:
+ return "Pi project workflow target"
+
+
+def materialize(edition, stage) -> None:
+ from devflow_cli.core import materialize_classic, materialize_portable
+ (materialize_portable if edition == "portable" else materialize_classic)(HOST, stage)
diff --git a/tests/test_installer.py b/tests/test_installer.py
index 7c992e87..5dd10c73 100644
--- a/tests/test_installer.py
+++ b/tests/test_installer.py
@@ -154,10 +154,26 @@ class InstallerTests(unittest.TestCase):
self.assertEqual("classic", DEFAULT_EDITION)
self.assertEqual(("portable", "classic"), tuple(EDITION_SPECS))
for edition, metadata in EDITION_SPECS.items():
- self.assertEqual(set(HOSTS), set(metadata["entrypoints"]))
- for host in HOSTS:
+ hosts = metadata.get("hosts", HOSTS)
+ self.assertEqual(set(hosts), set(metadata["entrypoints"]))
+ for host in hosts:
self.assertTrue((ROOT / source_for(edition, host)).is_dir())
+ def test_pi_is_portable_only(self):
+ self.assertIn("pi", EDITION_SPECS["portable"]["hosts"])
+ self.assertNotIn("pi", EDITION_SPECS["classic"]["hosts"])
+ self.assertEqual("/skill:devflow", EDITION_SPECS["portable"]["entrypoints"]["pi"])
+
+ def test_pi_installs_portable_skills_and_rejects_classic(self):
+ with tempfile.TemporaryDirectory() as td:
+ project = Path(td)
+ installed, _unchanged = apply_install(project, "pi", "portable")
+ self.assertGreater(installed, 0)
+ self.assertTrue((project / ".pi/skills/devflow/SKILL.md").is_file())
+ self.assertTrue((project / ".pi/skills/manifest.json").is_file())
+ with self.assertRaises(DevFlowError):
+ apply_install(project, "pi", "classic")
+
def test_editions_and_plan_make_the_split_visible_without_writing(self):
output = StringIO()
with redirect_stdout(output):